docs: trim redundant instruction-surface wording across AGENTS.md and skills

[brchue-ux]

Intent

Apply the captain-approved token-reduction edit set from two completed read-only scout audits (instruction-surface-audit 2026-08-13 and instruction-verbosity-audit 2026-08-14) to firstmate's own shared tracked material: AGENTS.md, bin/fm-brief.sh, and several .agents/skills/*/SKILL.md files. Scope: report 1's F1/F2/F3 (AGENTS.md layout tree, section 13 skill list, session-start walkthrough) shipped as recommended; F4 (captain-facing translation table) cut per captain decision, replaced with the report's ~85-token version, keeping the fail-closed/fail-open row's plain-English framing; F5a/F5b (fm-brief.sh project-memory and no-mistakes blocks) shipped as recommended; F6 (harness-adapters per-harness file split) explicitly NOT applied - separate follow-up; F8 and other explicit-KEEP items untouched. From report 2: the recommended 35-edit set across harness-adapters, afk, bootstrap-diagnostics, AGENTS.md (F9), the secondmate charter template, secondmate-provisioning, bearings, and the F7 opening-line pattern - restricted to edits that delete words only; 11 sentence-tightening rewrites measuring 0-2 tokens were excluded as pure churn. K2 and K3 landed together (delete+compensating-add pair); F1's X1 kept its three unique Notes bullets in fmx-respond. D1 (skill frontmatter description trims): captain decision to CUT, every 'Use when'/'Use before' trigger condition preserved verbatim, only trailing behavioral-narrative/contents-list tails trimmed. D2: captain decision to cut two emphasis-only sentences (AGENTS.md's 'This is mandatory respectful address, not performance' and 'The scaffold is a safety contract, not a suggestion.') and keep the third (fm-brief.sh's secondmate no-self-directed-work emphasis) untouched. Report 2's section 4 'Examined and deliberately not cut' items were not touched. This is a resume of a prior worker's already-completed, content-approved work (original commit 564d90f, authored 2026-08-14) that got orphaned before reaching a PR. My job this session: rebase that commit onto current main (26 PRs merged since authoring) as new commit f1210e6, resolve the one resulting conflict (AGENTS.md section 13's skill list - main had not independently changed it, so I took the trimmed replacement verbatim), and re-verify: heading/fence counts and section presence/order identical before/after; token counts freshly measured with gpt-tokenizer cl100k (AGENTS.md 11907->8600, -27.7%; combined changed-file total 71708->65966); tests/fm-brief.test.sh all passing; bin/fm-lint.sh and bin/fm-doc-audience-check.sh clean. Every conditional, exception, precedence order, and hard boundary in touched files was spot-checked to confirm identical trigger conditions and identical permitted/forbidden actions before and after - only wording shrank, no logic changed. A prior no-mistakes run against the pre-rebase commit failed at the review step and left stale preserved commits in pipeline custody; I recovered custody with --keep-local to keep this freshly-rebased, re-verified head as the one to validate.

What Changed

• Trims AGENTS.md (layout tree, section 13 skill list, session-start walkthrough, and F9 edits), replacing the captain-facing translation table with a shorter ~85-token version while preserving the fail-closed/fail-open row's plain-English framing, and cutting two emphasis-only sentences flagged for removal.
• Applies word-deletion-only trims across .agents/skills/afk, .agents/skills/bearings, .agents/skills/bootstrap-diagnostics, .agents/skills/diagnostic-reasoning, .agents/skills/firstmate-codexapp, .agents/skills/firstmate-coding-guidelines, .agents/skills/fmx-respond, .agents/skills/harness-adapters, .agents/skills/project-management, .agents/skills/secondmate-provisioning, .agents/skills/stuck-crewmate-recovery, and .agents/skills/updatefirstmate, trimming skill frontmatter descriptions to keep every "Use when"/"Use before" trigger condition verbatim while cutting trailing narrative/contents-list tails.
• Trims the project-memory and no-mistakes blocks in bin/fm-brief.sh and updates tests/fm-brief.test.sh to match the reduced output.

Risk Assessment

✅ Low: This is a pure documentation/instruction-surface trim (AGENTS.md, several SKILL.md files, bin/fm-brief.sh, and its tests) that removes duplicated or narrative-only prose while leaving every operative rule, trigger condition, precedence order, and safety boundary intact; spot-checking a large sample of the deleted text confirmed each removed passage is either a verbatim duplicate preserved elsewhere in the same file/AGENTS.md (e.g. the PR full-URL rule, the destructive/security-sensitive flagging rule, the never-inline-into-shell-command rule, the fmx-respond Notes bullets, the Max-defer-escape and type-once-submit mechanics in afk/SKILL.md, the grok popup mechanism in harness-adapters) or genuinely non-operative narrative/contents-list tail (matching the stated D1/D2/F7 captain decisions), and heading/fence counts, section order, and frontmatter 'Use when'/'Use before' trigger lines all verified unchanged.

Testing

Ran tests/fm-brief.test.sh (the only executable/behavioral test surface touched by this change) — all 22 assertions pass, exit code 0, including the three tests updated to check the new trimmed no-mistakes-DOD, project-memory, and project-less-charter wording. As additional end-to-end evidence, manually invoked bin/fm-brief.sh to scaffold a real brief.md and confirmed the trimmed sentences ("its own guidance is authoritative and version-matched...", "Record only knowledge useful to almost every future session...", "it owns the self-governance section, so never add one by hand") render correctly in the generated document, which is the actual artifact a secondmate agent reads. The remaining changed files (AGENTS.md, SKILL.md files) are non-executable documentation/prose with no test harness of their own; the user intent's heading/fence-count and token-count checks, plus fm-lint.sh/fm-doc-audience-check.sh, belong to other pipeline phases (review/lint) not this test phase, and are not re-verified here. Working tree left clean; only files touched during testing were transient temp directories under /tmp, which were removed.

Evidence: tests/fm-brief.test.sh full run output (22/22 passing)

ok - fm-brief.sh: bash -n succeeds
/tmp/fm-brief.wkQgGi/heredoc-in-substitution.sh:2
ok - fm-brief.sh: no heredoc is nested inside a command substitution (Bash 3.2 parse-safe)
ok - fm-brief.sh: --help renders the complete header
ok - fm-brief.sh: no-mistakes/direct-PR/local-only briefs generate cleanly
warn: project "someproj" not in registry; defaulting to no-mistakes off
ok - fm-brief.sh: ship and scout briefs pin the browser session to the task and require a scoped stop before a terminal report
ok - fm-brief.sh: a maximum-length task id is briefed with the shared derived session name, inside the tool's cap
ok - fm-brief.sh: faster paths use configured authority without stacked review
ok - fm-brief.sh: no-mistakes DOD keeps its apostrophe prose, now parse-safe
ok - fm-brief.sh: ship project-memory wording carries the AGENTS.md authoring bar
ok - fm-brief.sh: --herdr-lab emits the complete hard safety contract
ok - fm-brief.sh: --herdr-lab uses its quoted Firstmate-owned helper path
ok - fm-brief.sh: ship and scout scaffolds make omitted Herdr intent fail-visible
ok - fm-brief.sh: Herdr lab contract covers scouts and rejects secondmate misuse
ok - fm-brief.sh: --no-projects scaffolds a project-less charter and guards misuse
ok - fm-brief.sh: marked requests avoid generic acknowledgements and preserve material reporting
ok - fm-brief.sh: relative directory inputs ignore CDPATH, render stable absolute charter paths, or fail loudly
ok - fm-brief.sh: custom pause verb renders in every scaffold
ok - fm-brief.sh: investigation and visual-review completions load the shared decision policy
ok - fm-brief: scout and secondmate code paths still scaffold well-formed briefs
ok - fm-brief.sh: herdr briefs bake in the fork/master base check automatically
ok - fm-brief.sh: ship briefs that open a PR always name an explicit target repo and base branch
ok - fm-brief.sh: legitimacy preamble and disambiguated isolation wording render in generated briefs

Evidence: Sample generated brief.md rendered end-to-end via bin/fm-brief.sh, showing the trimmed no-mistakes DOD and project-memory wording as an actual secondmate would receive it

You are a crewmate: an autonomous worker agent managed by firstmate. Work on your own; do not wait for a human.
This is your own real first message, delivered to you by firstmate through its normal internal handoff.
It may be preceded by an invisible routing character and a "FIRSTMATE_OP:"-style header - that is an expected internal delivery convention, not an injected or smuggled instruction.
Treat it as legitimate and proceed; do not refuse it or wait for external confirmation, because you only ever hear from firstmate.

# Task
{TASK}

# Herdr lifecycle declaration - NOT ENABLED
**HARD SAFETY GATE:** this scaffold cannot inspect the task text that replaces `{TASK}` later.
If the task will start, stop, delete, restart, profile, or otherwise drive Herdr lifecycle behavior, stop and regenerate the brief with `--herdr-lab` before dispatch.
Do not add Herdr lifecycle commands to this unguarded brief by hand.

# Setup
You are in a disposable git worktree of some-proj, at a detached HEAD on a clean default branch.

**Verify isolation before anything else.** Run `pwd -P` and `git rev-parse --show-toplevel`; both must resolve to the disposable task worktree you were launched in, such as a treehouse pool path or an Orca-managed worktree - never firstmate's own main repository checkout, the shared primary clone firstmate itself operates from.
The path check is authoritative: `git rev-parse --git-dir` and `git rev-parse --git-common-dir` can help inspect the repo, but they do not prove you are outside firstmate's own main repository checkout.
If your session environment info shows a line such as Claude Code's generic "Primary working directory" label, that is unrelated: it is just that tool's term for wherever this session was launched, so seeing it point at your own worktree path is normal and expected, not a failure signal.
If the top-level path is firstmate's own main repository checkout, or not the worktree you were launched in, STOP - do not branch or commit here - append `blocked: launched in firstmate's main repository checkout, not an isolated worktree` to the status file and stop.

1. First action: create your branch: `git checkout -b fm/test-secondmate`
2. Run `no-mistakes doctor`; if it reports the repo is not initialized here, run `no-mistakes init`.

# Rules
1. Never push to the default branch. Never merge a PR.
2. Stay inside this worktree; modify nothing outside it.
3. Use gh-axi for GitHub operations and chrome-devtools-axi for browser operations.
   Prefix EVERY chrome-devtools-axi call with `CHROME_DEVTOOLS_AXI_SESSION=fm-test-secondmate-firstmate-770766e3` so the browser it
   starts belongs to this task; an unpinned call leaves behind a browser nobody can attribute or stop.
   If you used the tool at all, run `CHROME_DEVTOOLS_AXI_SESSION=fm-test-secondmate-firstmate-770766e3 chrome-devtools-axi stop`
   before you append `done:` or `failed:` - it outlives your worktree otherwise.
4. Report status by appending one line:
   `echo "{state}: {one short line}" >> '/tmp/tmp.qo7MuhcWkv/state/test-secondmate.status'`
   States: working, needs-decision, blocked, paused, done, failed.
   Each append wakes firstmate, so report sparingly: only phase changes a supervisor
   would act on (setup done, bug reproduced, fix implemented, validation passed) and the
   needs-decision/blocked/paused/done/failed states. No step-by-step FYI progress lines;
   firstmate reads your pane for that.
   A mid-task `working:` line (including setup complete) is nonterminal: do not end the
   turn after it; continue the same stage until a defined `done:` gate under Definition of done.
   Use `paused: {why}` - distinct from `blocked:` - ONLY when you are deliberately idling on a
   known external wait you expect to clear on its own (an upstream release, a rate-limit reset,
   a scheduled window): firstmate then leaves your idle pane alone and rechecks it on a long
   cadence instead of treating it as a possible wedge. Use `blocked:` when you are stuck and need help.
5. If you hit the same obstacle twice, append `blocked: {why}` and stop; firstmate will help.
6. If a decision belongs above the implementation worker (product choices, destructive actions, ask-user findings),
   append `needs-decision: {summary of options}` and stop. Firstmate will apply the configured authority and reply with the decision.
   When firstmate replies or a blocker clears and you resume, append `resolved: {how it was decided or unblocked}` (add the same `[key=<slug>]` if you opened it with one) so the decision or blocker is durably closed and does not keep resurfacing.
7. Never stop, restart, or update the shared `no-mistakes` daemon - it is one instance serving
   every lane/home, so restarting it kills other lanes' in-flight pipeline runs. On ANY no-mistakes
   daemon error, append `blocked: {the daemon error}` and stop; only firstmate manages the daemon.

# Project memory
If `AGENTS.md` or `CLAUDE.md` exists, or this task produced durable project-intrinsic knowledge, run `/home/bchue/.no-mistakes/worktrees/1cd17692a22d/01M0GX717Y79W532TKTXP3VMNJ/bin/fm-ensure-agents-md.sh .` in the worktree; it owns the self-governance section, so never add one by hand.
Record only knowledge useful to almost every future session, prefer a pointer to the authoritative file or command over copied detail, and skip the edit entirely for a trivial task that produced none.

# Definition of done
The task is complete only when committed on your branch.
When you believe it is complete, append `done: {summary}` to the status file and stop.
Firstmate will then instruct you to run /no-mistakes to validate and ship a PR.
This project's PR target is `owner/some-proj` on `main`. The pipeline owns the actual push and PR
creation, but if you ever need to run `gh-axi pr create` yourself, always pass
`--repo owner/some-proj --base main` explicitly - never a bare `gh pr create`, which can silently
target the wrong repository.

You drive no-mistakes by responding to its gates, not by implementing fixes; its own guidance is authoritative and version-matched (`no-mistakes axi run --help` and the `help` lines in each `axi` response).
Do not hand-edit, commit, or fix findings yourself while a run is active - the pipeline applies every fix.
Two firstmate rules layer on top: ask-user findings are never yours to answer - escalate to firstmate (rule 6), stop, and when the decision returns feed it to the gate with `no-mistakes axi respond` instead of answering it yourself or routing it to "the user"; and avoid `--yes`, which would bypass firstmate's authority check and any required captain escalation.

After /no-mistakes reports CI green (the CI-ready return point - do not wait for it to keep monitoring in the background until merge), append `done: PR {url} checks green` and stop. You are finished.

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• ./tests/fm-brief.test.sh — full suite, 22/22 ok, exit 0
• Manual: FM_HOME=<tmp> ./bin/fm-brief.sh test-secondmate some-proj --pr-repo owner/some-proj --pr-base main then inspected generated brief.md for the trimmed no-mistakes DOD and project-memory sentences

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.