docs: trim firstmate agent guidance duplication

[kunchenguid]

Intent

Third and final AGENTS.md diet PR (redundancy cleanups), per data/agentsmd-diet-s2/report.md items c3-c7 - items c1/c2 already shipped in prior PRs (#248, #253, #255). This pass consolidates five duplicated passages to a single canonical owner each: (1) the inheritable-config propagation mechanism, previously restated in full in sections 3, 4, and 7 - now owned by section 3 (where the sweep actually runs), with sections 4 and 7 trimmed to compact references (section 4 deliberately keeps one unique fact not stated elsewhere: the crew-harness inherit-vs-fallback semantics); (2) the landed-work definition, previously restated in full in section 1 hard rule #3 and section 7's ship-teardown paragraph - now owned by section 7 (since that is where fm-teardown's actual behavior and edge cases like the pr= discovery fallback must live in full); section 1 deliberately keeps the rule statement itself plus a three-case summary, since this touches a hard rule and should not be reduced further; (3) backend meta-field enumeration (herdr_, zellij_, orca_, cmux_ field names and window/tab naming), previously duplicated between AGENTS.md section 2 and docs/configuration.md's fuller 'Runtime backend' section - AGENTS.md now keeps only the fields common to every task and points at the docs for per-backend detail; docs/configuration.md needed no edit since it was already comprehensive including cmux, confirmed by comparing field lists; (4) a single redundant restatement of 'silence is correct while a healthy watcher is waiting' in section 8, deleted, keeping the fuller original statement a few lines above; (5) the worktree-tangle guard explanation, previously restated in full in both section 3's bootstrap TANGLE diagnostic and section 8's canonical version - section 3's bullet now keeps only the remediation action and points at section 8 for the why. Also added two captain-requested single-sentence rules that were confirmed genuinely absent beforehand: invoke bin/ scripts by absolute $FM_ROOT path after any cd away from the operational home (scripts self-locate internally, only invocation is cwd-fragile), and a backend spawn refusal (missing dependency, unauthenticated socket, version gate) must be surfaced to the captain as a blocker, never silently worked around by switching to a different backend. Every removed passage was verified to already have a fuller, intact copy at its new sole owner before being trimmed - none of the deletions are net loss of information, only de-duplication. Net effect: AGENTS.md goes from 901 to 889 lines (112355 to 108560 bytes); this lands a bit above the original diet report's ~830-840 line target because unrelated work (cmux backend, turn-end guard, afk-herdr) added lines to the file since that estimate was made, and this pass only tackled the smaller redundancy items rather than a fresh extraction round. Scope was deliberately narrow (AGENTS.md and docs/configuration.md only) and conservative: this pass touches a hard-rule section (section 1) and the ship-teardown safety section (section 7), so anywhere the right call was ambiguous the fuller text was left in place rather than trimmed.

What Changed

• Trimmed duplicated firstmate agent guidance in AGENTS.md, keeping canonical detail for landed-work checks, backend metadata, tangle handling, inherited config, and watcher behavior in one place.
• Added guidance to invoke bin/ scripts by absolute repo path after changing directories, and mirrored that in script documentation.
• Documented that selected backend spawn refusals are terminal blockers to surface, not reasons to silently retry on another backend.

Risk Assessment

✅ Low: Captain, this is a narrow AGENTS.md-only de-duplication and clarification change, and the removed details still have intact canonical coverage in section 7 or the backend docs.

Testing

The configured full tmux-backed test suite had already passed as baseline; I reran the targeted shell tests covering the trimmed safety areas, verified the documentation end-to-end with line-numbered evidence, produced the requested evidence artifact, cleaned transient state files, and found no failures.

Evidence: AGENTS.md trim verification report

# AGENTS.md Trim Verification

Purpose: verify the PR trims duplicate documentation without removing the operational rules the end user depends on.

## Diff Scope

`` `text
 AGENTS.md | 36 ++++++++++++------------------------
 1 file changed, 12 insertions(+), 24 deletions(-)
AGENTS.md
current:      889  108585 AGENTS.md
base:         901  112355
`` `

## Assertions

- Only AGENTS.md changed.
- AGENTS.md now has 889 lines, down from 901.
- The hard rule keeps a short landed-work summary and points to section 7 for PR containment and pr= fallback details.
- Backend-specific meta fields moved out of the layout table and remain in docs/configuration.md Runtime backend.
- Inheritable-config propagation is fully described in session start, with compact spawn references.
- The duplicate watcher-silence sentence is absent, while the fuller watcher-silence instruction remains.
- The two new rules are present: absolute bin invocation after cd and backend spawn refusal escalation.

## Evidence Lines

### Landed-work owner and section 7 fallback

`` `text
    33	3. **Never tear down a worktree that holds unlanded work.**
    34	   `bin/fm-teardown.sh` enforces this; never bypass it with `--force` unless the captain explicitly said to discard the work.
    35	   Three ways work counts as "landed": `HEAD` reachable from any remote-tracking branch (a fork counts, so an upstream-contribution PR pushed to a fork satisfies this in any mode); for a normal ship task, its PR merged with a head that contains the local work, or its content already present in the up-to-date default branch; for `local-only` ship tasks with no remote, merged into the local default branch.
    36	   Uncommitted changes are never landed.
    37	   The scout carve-out: a scout task's worktree is declared scratch from the start - its deliverable is the report, and teardown lets the worktree go once that report exists (section 7).
    38	   The full PR-containment mechanics and the `pr=` discovery fallback are section 7's ship-teardown detail, not restated here.
   582	The script refuses if the worktree holds uncommitted changes or committed work that has not landed; treat a refusal as a stop-and-investigate, not an obstacle.
   583	"Landed" is broader than remote-reachable: for a normal ship task whose commits are not reachable from any remote-tracking branch, the script also accepts the work when its PR is merged and GitHub reports a PR head that contains the current local work, or when its content is already present in the up-to-date default branch.
   584	Containment means local `HEAD` is the PR head, local `HEAD` is an ancestor of the PR head, or the unpushed local patches have matching patch IDs in that PR head after no-mistakes replayed the branch.
   585	This recognizes the common squash-merge-then-delete-branch flow, where the branch's own commits live nowhere on a remote yet the change is fully in `main`; a merged-and-deleted branch now tears down cleanly instead of false-refusing.
   586	The PR is looked up from the task's recorded `pr=` when present, or, when no `pr=` was ever recorded, by finding a merged PR whose head branch matches the worktree's branch and fetching its head via `refs/pull/<n>/head` if the branch itself was deleted - so a task whose merge skipped `bin/fm-pr-check.sh` (typically a yolo-authorized merge on a repo with no PR CI, where the "checks green" trigger never fires) still tears down cleanly instead of false-refusing.
   587	Genuinely unlanded work (no merged PR head containing the local work and content not in the default branch) and dirty worktrees still refuse, and a gh lookup error falls back to the content check rather than silently allowing.
`` `

### Backend meta moved to docs/configuration.md

`` `text
    96	  <id>.meta          written by fm-spawn: window=, worktree=, project=, harness=, model=, effort=, kind=, mode=, yolo=, tasktmp=; kind=secondmate also records home= and projects=; a non-default runtime backend records further backend-specific fields (docs/configuration.md "Runtime backend"; bin/fm-backend.sh, section 8); fm-pr-check, including through fm-pr-merge, appends pr= and GitHub's pr_head= when available; fm-x-link appends x_request=, x_request_ts=, and x_followups= for an X-mention-originated task (section 14)
    97	  <id>.check.sh      optional slow poll you write per task (e.g. merged-PR check)
    98	  x-watch.check.sh   generated X-mode relay poll shim; present only when opted in (section 14)
    99	  x-inbox/           generated X-mode pending mention payloads; fmx-respond drains it (section 14)
   100	  x-outbox/          generated X-mode dry-run reply and dismiss previews; inspect it when FMX_DRY_RUN is set (section 14)
   101	  x-poll.error       generated X-mode relay diagnostic dedupe marker
   102	  .wake-queue        durable queued wakes: epoch<TAB>seq<TAB>kind<TAB>key<TAB>payload
   103	  .afk               durable away-mode flag; present = sub-supervisor may inject escalations (set by /afk, cleared on user return)
   104	  .watch.lock .wake-queue.lock watcher singleton and queue serialization locks
   105	  .hash-* .count-* .stale-* .stale-since-* .seen-* .hb-surfaced-* .last-* .heartbeat-streak   watcher internals; never touch
   106	  .watch-triage.log  watcher's absorbed-wake debug log (size-capped); never relied on, safe to delete
   107	  .last-watcher-beat watcher liveness beacon, touched every poll (including while absorbing benign wakes); guard scripts read it
   108	  .subsuper-* .supervise-daemon.*   sub-supervisor internals; never touch
   109	.no-mistakes/        local validation state and evidence; gitignored
   110	`` `
   111	
   112	The shell working directory persists between commands, so after any `cd` away from the home, invoke `bin/` scripts by the absolute path to this repo's `bin/` directory; the scripts self-locate internally, so only invocation is cwd-fragile.
   113	
   114	Task ids are short kebab slugs with a random suffix, e.g. `fix-login-k3`.
   115	For the tmux backend, the task window is always named `fm-<id>`; per-backend window/tab naming and workspace scoping for herdr, zellij, orca, and cmux live in `docs/configuration.md` ("Runtime backend") and each backend's own doc.
    19	## Runtime backend (config/backend / FM_BACKEND)
    20	
    21	For spawn-capable adapters, the runtime session-provider backend controls where task windows/endpoints are created, captured, sent to, watched, and killed.
    22	`tmux` is the verified reference backend (see [`docs/tmux-backend.md`](tmux-backend.md)); `herdr`, `zellij`, `orca`, and `cmux` are experimental spawn backends (see [`docs/herdr-backend.md`](herdr-backend.md), [`docs/zellij-backend.md`](zellij-backend.md), [`docs/orca-backend.md`](orca-backend.md), and [`docs/cmux-backend.md`](cmux-backend.md)).
    23	Treehouse remains the worktree provider for tmux, herdr, zellij, and cmux, since herdr, zellij, and cmux are session providers only; Orca provides both the task worktree and terminal endpoint.
    24	New spawns choose the backend in this order: an explicit `--backend` flag firstmate passes when it spawns a task, then `FM_BACKEND`, then the first non-empty line of local gitignored `config/backend`, then runtime auto-detection from `$TMUX`, `HERDR_ENV=1`, or `CMUX_WORKSPACE_ID`, then default `tmux`.
    25	If more than one runtime marker is present, detection resolves innermost-first: `$TMUX` is checked before `HERDR_ENV=1`, which is checked before `CMUX_WORKSPACE_ID` - tmux or herdr started from inside a cmux terminal is the innermost, currently-executing layer, while cmux itself (a terminal application, not a nestable multiplexer) is always checked last.
    26	Auto-detected herdr or cmux prints a stderr notice naming `config/backend` and `--backend tmux` as opt-outs; auto-detected tmux stays silent to preserve existing default behavior.
    27	Zellij and Orca are never auto-detected; select them by putting the name in a local `config/backend` file, by exporting `FM_BACKEND=<name>`, or by telling the first mate in chat.
    28	Any value other than `tmux`, `herdr`, `zellij`, `orca`, or `cmux` is rejected until another adapter is implemented and verified.
    29	`fm-spawn.sh` accepts `tmux`, `herdr`, `zellij`, `orca`, and `cmux` for ship and scout tasks; `backend=orca` and `backend=cmux` both still refuse `--secondmate` until secondmate launch semantics are designed for each.
    30	A herdr spawn additionally version-gates against the installed `herdr` binary's protocol and requires `jq`, refusing loudly on an incompatible or missing installation.
    31	A zellij spawn additionally version-gates against the installed `zellij` binary's version and requires `jq`, refusing loudly when either is missing or the version is older than 0.44.
    32	A cmux spawn additionally version-gates against the installed `cmux` binary's version, requires `jq`, and requires the control socket to be reachable and authenticated (see [`docs/cmux-backend.md`](cmux-backend.md) "Setup" for the one-time password-mode configuration this needs), refusing loudly and non-retryably on a `cmuxOnly`/unauthenticated socket.
    33	When bootstrap resolves `backend=orca` from `FM_BACKEND` or `config/backend`, it checks for `orca`, keeps the universal `node` requirement, and skips the tmux/treehouse tool pair because Orca owns both the worktree and terminal lifecycle.
    34	Task meta records `backend=` only for a non-default backend; an absent `backend=` means `tmux`, preserving existing default-path meta files.
    35	A herdr task additionally records `herdr_session=`, `herdr_workspace_id=`, `herdr_tab_id=`, and `herdr_pane_id=`.
    36	A zellij task additionally records `zellij_session=`, `zellij_tab_id=`, and `zellij_pane_id=`.
    37	An Orca task additionally records `orca_worktree_id=` and `terminal=`, with `window=fm-<id>` kept as the shared firstmate alias.
    38	A cmux task additionally records `cmux_workspace_id=` and `cmux_surface_id=`.
`` `

### Inheritable config canonical session-start owner and compact spawn reference

`` `text
   151	The same sweep also propagates the primary's declared inheritable config (`config/crew-dispatch.json`, `config/crew-harness`, and `config/backlog-backend`; sections 4 and 10) into each live secondmate home's `config/`, so every secondmate's own crewmates, dispatch profiles, and backlog backend stay on the primary's settings.
   152	Because `config/` is gitignored this is a separate, primary-authoritative copy independent of the tracked-files fast-forward: it re-converges every live home whether or not its tracked files advanced, and it touches only the declared inheritable items (never `config/secondmate-harness`).
   153	For a mid-session inheritable-config change that should reach live secondmates without a full session start, run `bin/fm-config-push.sh`.
   154	It is config-only: it uses the same live secondmate discovery and the same `propagate_inheritable_config` helper as bootstrap, prints a per-home/per-item summary, does not fast-forward tracked files, and does not nudge secondmates.
   155	The propagation helper itself keeps stdout silent for existing callers, but warns on stderr when an item is skipped because the destination does not allow it or when a copy/remove error occurs.
   498	Before launching a secondmate, the script fast-forwards its home worktree to firstmate's own current default-branch commit, so a freshly spawned or recovery-respawned secondmate always starts on firstmate's current version.
   499	This is a purely local fast-forward of tracked files - never a fetch from origin, and never touching the gitignored operational dirs - so the secondmate's backlog, projects, and any prior in-flight work are untouched; a dirty, diverged, or in-flight home is left as-is and launches unchanged.
   500	If that pre-launch fast-forward is skipped, `fm-spawn.sh` prints a concise warning to stderr and still launches the secondmate from its unchanged checkout.
   501	The spawn also propagates the primary's inheritable config into the secondmate home's `config/`, mirroring the bootstrap sweep (section 3).
   502	No nudge is needed at spawn because the agent reads `AGENTS.md` fresh on launch.
   503	For already-live secondmates, use `bin/fm-config-push.sh` when only this inherited config needs to be pushed.
`` `

### TANGLE compact bootstrap reference and canonical section 8 explanation

`` `text
   165	- `TANGLE: <remediation>` - the primary checkout is stranded on a feature branch instead of its default branch; section 8 explains why this guard exists and what it protects. The work is safe on that branch ref; restore the primary to its default branch with the printed `git -C <root> checkout <default>`, then re-validate that branch in a proper worktree. This is the only sanctioned firstmate-initiated git write to the primary, and it is a non-destructive branch switch that strands nothing.
   703	`fm-guard.sh` carries a second, independent alarm in the same bordered ●-marked style: the **worktree-tangle** guard.
   704	Firstmate is a treehouse-pooled git repo of itself - the primary checkout (the repo root, `FM_ROOT`) and every crewmate worktree and secondmate home are linked worktrees of one repo - and the primary must stay on its default branch.
   705	If a crewmate sent to work firstmate-on-itself branches or commits in the primary instead of its own isolated worktree, the primary is stranded on a feature branch (the failure this guards against); the guard names the offending branch and prints the non-destructive restore (`git -C <root> checkout <default>`), so the tangle surfaces on the very next fleet action.
   706	The check is scoped precisely to the primary: detached HEAD (the legitimate resting state of crewmate worktrees and secondmate homes on the default branch) and the default branch itself never alarm; only a named non-default branch checked out in the primary does.
   707	The same assertion runs at session start as the bootstrap `TANGLE:` line inside the `bin/fm-session-start.sh` digest (section 3), with read-only wording when this session does not hold the fleet lock.
   708	Two further guards prevent the tangle upstream: `fm-spawn` refuses to launch unless treehouse or Orca yields a genuine isolated worktree distinct from the primary checkout, and every ship brief's first instruction has the crewmate verify it is in its own worktree before branching (section 11).
`` `

### Watcher-silence retained once

`` `text
   657	Waiting on the watcher is intentionally silent.
   658	After arming it, do not send idle progress updates to the captain; wait until it returns `signal`, `stale`, `check`, or `heartbeat`, unless the captain asks for status.
   659	Empty polls, elapsed waiting time, and "still no change" are tool bookkeeping, not conversational progress.
OK: old duplicate sentence is absent.
`` `

### New single-sentence rules

`` `text
   112	The shell working directory persists between commands, so after any `cd` away from the home, invoke `bin/` scripts by the absolute path to this repo's `bin/` directory; the scripts self-locate internally, so only invocation is cwd-fragile.
   487	A backend spawn refusal - a missing dependency, an unauthenticated socket, or a version gate - must be surfaced to the captain as a blocker; never silently retry the spawn on a different backend to work around it.
`` `

## Behavior Tests Re-run

`` `text
PASS: tests/fm-session-start.test.sh
PASS: tests/fm-tangle-guard.test.sh
PASS: tests/fm-backend.test.sh
PASS: tests/fm-backend-cmux.test.sh
PASS: tests/fm-spawn-dispatch-profile.test.sh
PASS: tests/fm-secondmate-sync.test.sh
PASS: tests/fm-teardown.test.sh
`` `

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed ✅

• 🚨 AGENTS.md:112 - Line 112 tells agents to invoke scripts via $FM_ROOT after cd, but FM_ROOT is only computed inside the scripts and is not exported for the interactive shell. In a normal session this expands to /bin/... or fails under unbound-variable handling, so the new cwd-safety rule can make post-cd firstmate commands fail. Change this to require the literal absolute repo path, or first define/export FM_ROOT at session start before telling agents to rely on it.

🔧 Fix: Clarify post-cd bin invocation guidance
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"
• Provided successful baseline: command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"
• bin/fm-session-start.sh
• git diff --stat 2c16f97e384c841f6915f32508c1ceb5f80f1634..6d55e93f307ecb3a058ee913e7dcd88af6d19941
• git diff --name-only 2c16f97e384c841f6915f32508c1ceb5f80f1634..6d55e93f307ecb3a058ee913e7dcd88af6d19941
• wc -l -c AGENTS.md and git show 2c16f97e384c841f6915f32508c1ceb5f80f1634:AGENTS.md | wc -l -c
• Line-numbered documentation checks for landed-work, backend metadata, inheritable config, TANGLE, watcher silence, absolute bin invocation, and backend spawn refusal
• for t in tests/fm-session-start.test.sh tests/fm-tangle-guard.test.sh tests/fm-backend.test.sh tests/fm-backend-cmux.test.sh tests/fm-spawn-dispatch-profile.test.sh tests/fm-secondmate-sync.test.sh tests/fm-teardown.test.sh; do printf '\n== %s ==\n' "$t"; bash "$t" || exit 1; done
• Created evidence report at /var/folders/5x/4nqprlbx0518k3ybcb1sz6gr0000gn/T/no-mistakes-evidence/01KWQFEKRGSK1N59ZMG931ZNQX/agentsmd-trim-verification.md
• git status --short
• Removed transient state/.lock and state/.wake-queue created during validation

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.