[dnth]

Summary

The cd-guard denied every persistent top-level cd in the primary firstmate shell: 38 denials in
7 days, of which one was the actual hazard (a cd into projects/infoconnect-search-engine) and the
rest were the home itself, /tmp, scratch worktrees, data/, state/, and $FM_HOME.
It now exempts a cd it can prove stays inside the home, and keeps denying everything else.

cd <target>                       (top-level, persists in the primary shell)
  proof gate
    ├ first node, or an exempt cd chain after `;` / newline / `&&`
    ├ no redirection, heredoc, or leading assignment on the node
    └ no shell keyword anywhere in the command
  operand
    ├ literal path (absolute or relative)
    ├ unquoted, unescaped leading `~`
    └ quoted `$FM_HOME` / `${FM_HOME}`
  destination
    ├ both path rules inside the home (logical `..`, physical symlinks)
    ├ outside `projects/` and outside every foreign git checkout
    └ an existing, searchable directory
  → allow, and open that directory for the next node
  otherwise → deny [persistent-cd]

Design source: upstream kunchenguid/firstmate commit d42a6997 (kunchenguid#8021) added the home exemption
(cdTargetsHome plus --home), which allows a cd to the home itself. This PR ports the behaviour and
its both-path-rules resolution, then extends it to a provable subset of the home.

Deliberately kept denied:

• anything under projects/, a home symlink that resolves into projects/ or out of the home, a
  treehouse or scratch worktree, any other repo checkout, and /tmp (a firstmate command run from there
  resolves the wrong home);
• any target that cannot be resolved, and any destination that is not an existing, searchable directory;
• any cd the policy cannot prove: after a non-cd command, through ||, inside a pipeline, background
  job, subshell, or brace group, inside a shell-keyword compound, with a redirection, heredoc, or leading
  assignment, with any option or the special -, with a glob, substitution, or other variable, with more
  than one operand, or with an unquoted $FM_HOME that Bash could split or pathname-expand.

Evidence

Before: every one of these was denied.

cd /home/<user>/Desktop/firstmate      → denied
cd data                                 → denied
cd ~/data                               → denied
cd "$FM_HOME/data"                      → denied

After: those run, and cd projects/<clone>, /tmp, foreign worktrees, and every unprovable shape stay
denied. Test evidence: tests/fm-cd-pretool-check.test.sh reports the acceptance matrix across all five
harness entry forms plus the dedicated refusal, CDPATH, tilde-quoting, and Bash-oracle regressions.

Contract amendment

The original AC1 listed the unquoted $FM_HOME form as allowed. A quoted expansion is neither word-split
nor pathname-expanded, so only cd "$FM_HOME..." is provably safe; the unquoted form is now a documented
refusal and the quoted form replaces it. docs/cd-guard.md is the single owner of the rule and lists
every refusal once.

Merge Danger

Door: two-way. One hook script, one policy module, one document, and the test suite; nothing migrates
state or touches projects/.

Blast radius: one harness seatbelt. A regression can only refuse a shell command, and the refusal
message names the allowed git -C / absolute-path / subshell alternatives. Verified by the acceptance
suite across Codex, Claude, Grok, OpenCode, and Pi entry forms.

Pipeline

Updates from git push no-mistakes

✅ **Intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 5 issues found → auto-fixed ✅

• 🚨 bin/fm-cd-command-policy.mjs:192 - An empty operand is resolved as the current directory, although Bash rejects cd "". With safe home/state and a checkout at home/data/state, cd data && cd "" && cd ..; cd state passes: the policy checks home/state, while Bash skips cd .. and enters the checkout. The earlier R6/R16 success-proof fixes left this sibling unresolved. Reject empty operands before resolving them. Related sites: bin/fm-cd-command-policy.mjs:85 treats empty text as cwd; :217 records success; :294 advances the tracked cwd.
• 🚨 bin/fm-cd-command-policy.mjs:138 - The new exemption trusts cooked paths from a lexer that removes every backslash inside double quotes. Bash preserves backslashes before ordinary characters. With safe home/datadir and a checkout named home/data\dir, cd "data\dir" passes against datadir but enters the checkout. Preserve Bash's double-quote escape semantics in the shared lexer before comparing destinations. Related sites: bin/fm-arm-command-policy.mjs:408-415 removes the backslash; bin/fm-cd-command-policy.mjs:154 also consumes incorrectly decoded quoted FM_HOME suffixes.
• 🚨 bin/fm-cd-command-policy.mjs:266 - The latest keyword handling contradicts the accepted criterion “no shell keyword compound in the command.” The added !word.quoted && CD_BUILTINS.has(word.value) check misses if "cd" /tmp; then :; fi, allowing Bash to leave home. Conversely, it denies if command -v cd; then :; fi, where cd is query data. The local check also permits cd data; if true; then :; fi, granting an exemption despite a later compound. Enforce the command-wide exemption restriction while distinguishing executed builtins from arguments and queries. Related sites: bin/fm-cd-command-policy.mjs:262 checks only the current node; :269 continues without detecting quoted builtins; :288 grants exemptions before inspecting later nodes. This is new behavior in 658ee8b, beyond the previously declined keyword-classification finding.
• ⚠️ bin/fm-cd-command-policy.mjs:157 - Simplification: the latest narrowing rejects leading assignments and redirections at :206-207, leaving two unnecessary components: assignment-specific CDPATH evaluation at :159-164 and redirection-failure destination branching at :290-294. Neither can be reached by an exempt cd. Remove those branches, read the inherited CDPATH directly, and retain one logical/physical cwd pair instead of the unreachable alternative-state machinery.
• ⚠️ tests/fm-cd-pretool-check.test.sh:151 - The accepted requirement says “Every refused shape has a deny test.” The expanded acceptance suite has no deny cases for glob operands, command-substitution operands, other variable operands, or multiple ordinary operands. Add executable guard cases such as cd data*, cd "$(printf data)", cd "$OTHER", and cd data state, using the accepted refusal contract as the oracle. These would reject accidental acceptance of each expressly forbidden shape.

🔧 Fix applied.
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• Live validation: ✅ go - 5 of 5 scenarios driven live against the product

Scenario	Result	Live	Evidence
Use absolute, relative, tilde, quoted FM_HOME, and symlink paths into a disposable home; guard allows and Bash reaches the expected directory	✅ pass	live	Live transcript: spellings
Chain safe directory changes with semicolons, newlines, or &&; subsequent paths resolve correctly	✅ pass	live	Live transcript: chains
Attempt projects, nested repositories, linked scratch worktrees, outside paths, missing directories, and divergent symlink paths; guard denies	✅ pass	live	Live transcript: hazards, including physical_rule_stdout
Attempt unprovable command shapes, expansion operands, empty operands, quoted backslashes, and CDPATH redirection; guard denies	✅ pass	live	Live transcript: refusals
Submit CLI and harness-shaped JSON payloads; receive correct decisions while scoped commands and linked-worktree scope remain allowed	✅ pass	live	Live transcript: transport

• python3 ~/.no-mistakes/evidence/01M796S134JFXVZXT5JVHEMWAY/drive-cd-guard.py — 77 real CLI probes
• bash --noprofile --norc directory checks using default logical resolution and set -P
• bash tests/fm-cd-pretool-check.test.sh and bash tests/fm-arm-pretool-check.test.sh — both exited 0
• Behavior-only copies of both focused suites, excluding embedded lint calls — both exited 0
• Removed disposable fixtures and temporary runners; confirmed clean working tree

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.