Guarding Paths

guarding-paths

Mantra: 1 path, 1 reference. A path is constructed exactly once; everywhere else references the constructed value. Re-constructing the same path twice is the violation. Referencing the constructed value many times is fine.

Modes

Three-level enforcement

The strategy lives in three artifacts that ship together:

1. CLAUDE.md rule: the mantra and detection rules in plain language. Every fleet repo's CLAUDE.md carries ## 1 path, 1 reference. Synced from _shared/path-guard-rule.md.
2. Hook: .claude/hooks/fleet/path-guard/index.mts runs PreToolUse on Edit / Write of .mts / .cts files. Blocks new violations at edit time.
3. Gate: scripts/fleet/check/paths-are-canonical.mts runs in pnpm check (and CI). Whole-repo scan. Fails the build on any unsanctioned violation.

The hook and gate share their stage / build-root / mode / sibling-package vocabulary via .claude/hooks/fleet/path-guard/segments.mts: a single canonical source. Adding a new stage segment or fleet package means editing one file; the two consumers can never drift on what counts as a build-output path.

This skill is the audit-and-fix workflow that makes a repo conform initially and validates conformance over time.

Detection rules

The gate enforces six rules. The hook enforces a subset (A and B), since it sees only one diff at a time.

Comments may describe path structure with placeholders (<mode>/<arch> or ${BUILD_MODE}/${PLATFORM_ARCH}) but should not encode a complete literal path string. Violations in .mts, Makefiles, Dockerfiles, workflow YAML, and shell scripts are blocking; comments come second.

Mode: audit-and-fix (default)

Worktree setup uses the default-branch fallback from CLAUDE.md:

# Resolved by the shared runner so the chain lives in exactly one place.
BASE=$(node .claude/skills/fleet/_shared/scripts/git-default-branch.mts)
git worktree add -b paths-audit ../<repo>-paths-audit "$BASE"

Mode: check (read-only)

pnpm run check:paths --explain

Prints findings without making edits. Exit 0 if clean, 1 if findings present. Useful for CI / pre-merge inspection.

Mode: install (new repo)

For Socket repos that don't yet have the gate:

1. Copy the gate file:

   cp .claude/skills/guarding-paths/templates/check-paths.mts.tmpl scripts/fleet/check/paths-are-canonical.mts
   

2. No allowlist file to create — exemptions live in the pathsAllowlist array of .config/socket-wheelhouse.json (absent key = no exemptions, which is the default).
3. Add "check:paths": "node scripts/fleet/check/paths-are-canonical.mts" to package.json.
4. Wire runPathHygieneCheck() into scripts/check.mts (after the existing checks).
5. Append the rule snippet from _shared/path-guard-rule.md to the repo's CLAUDE.md if a 1 path, 1 reference section is missing.
6. Add the hook entry to .claude/settings.json PreToolUse matcher Edit|Write:

   {
     "type": "command",
     "command": "node .claude/hooks/fleet/path-guard/index.mts"
   }
   

7. Run the gate against the repo. Triage findings as you would in audit-and-fix mode.

Allowlisting a finding

Genuine exemptions are rare; most "false positives" should be reported as gate bugs. When needed, add an entry to the pathsAllowlist array in .config/socket-wheelhouse.json (each entry needs a reason). Two ways to pin:

• line:: exact line number. Strict; a single-line edit above shifts the entry off-target and the finding re-surfaces.
• snippet_hash:: 12-char SHA-256 prefix of the offending snippet (whitespace-normalized). Drift-resistant: survives reformatting, but any content-changing edit invalidates it. Get the hash via pnpm run check:paths --show-hashes.

Both may be set — either matching is sufficient. Prefer snippet_hash over raw line: when the exemption is expected to outlive routine reformatting; prefer line: when you specifically want the entry to fall off after any nearby edit.

Commit cadence

• Per-rule fix → its own commit. Rule A fix in packages/foo/ and Rule C workflow fix go in separate commits even when found in the same audit pass.
• Re-run the gate before each commit. A green pnpm run check:paths is the entry criterion.
• Don't leave a partial fix uncommitted across phases. Commit what's done on chore/paths-audit-wip if the audit gets interrupted.

Conventional commit shape: fix(paths): rule A: extract foo build paths into scripts/paths.mts.

Tie-in with scanning-quality

/scanning-quality calls pnpm run check:paths --json as one of its sub-scans and surfaces findings in its A-F report. The full audit-and-fix workflow lives here. scanning-quality only detects during periodic scans.

Fix patterns

Per-rule fix templates (Rules A through G) plus the worked-example reference patterns from socket-btm: reference.md. File scaffolding for install mode lives in templates/.