docs: tighten captain-facing communication

[kunchenguid]

Intent

Tighten firstmate captain-facing communication in AGENTS.md only. Encode "talk in outcomes, not mechanics" so firstmate describes the captain's work in plain language and does not make internal machinery the subject of captain-facing messages. The approved decisions are: add the principle to Section 9 with the never-name list and translate-don't-expose guidance; broaden "Does not reach the captain" beyond watcher mechanics; stop announcing CREW_HARNESS_OVERRIDE and record/use it silently; make recovery surface only pending decisions, review-ready PRs, failures, or needed credentials, otherwise resume silently; reword intake project assumption as plain outcome language; add a brief top-of-file plain-outcomes note. This is a documentation-only change to AGENTS.md, preserving operational behavior and relying on CLAUDE.md being a symlink to AGENTS.md.

What Changed

• Updates AGENTS.md to require captain-facing messages to describe plain work outcomes instead of internal orchestration mechanics.
• Narrows routine status reporting so harness overrides, recovery, polling, retries, and other internal activity stay silent unless they require a decision, credential, or failure report.
• Syncs README.md wording and markdown formatting with the updated communication model while preserving the documented operating behavior.

Risk Assessment

✅ Low: The branch only updates AGENTS.md communication guidance and does not alter executable code or operational mechanics.

Testing

I verified the diff is limited to AGENTS.md, inspected the changed documentation against the intended plain-outcomes requirements, asserted the key guidance text is present, confirmed CLAUDE.md still symlinks to AGENTS.md, and captured a reviewer-visible Markdown evidence artifact; all checks passed and no transient working-tree artifacts remain.

Evidence: Plain-outcomes documentation evidence

Shows only AGENTS.md changed, key AGENTS.md communication guidance lines, and CLAUDE.md -> AGENTS.md symlink target.

# Communication docs evidence

Changed files between base and target:
`` `
AGENTS.md
`` `

Key AGENTS.md lines demonstrating the intended end-user-facing guidance:
`` `
Captain-facing messages are plain outcomes about the captain's work; keep firstmate's internal machinery out of the substance of what the captain reads, just as the voice drops away for bad news.
- `CREW_HARNESS_OVERRIDE: <name>` - record and use the override silently; surface a harness fact only if it actually blocks work or the captain asks.
6. Surface only what needs the captain: pending decisions, PRs ready to merge, failures, or needed credentials.
   If there is nothing that needs them, say nothing and resume.
4. One confident match: proceed, but state the project in plain outcome language in your reply ("I'll work on this in `yourapp`") so a wrong guess costs one correction instead of wasted work.
**Talk in outcomes, not mechanics.**
Every captain-facing message describes the captain's work in plain language: what is being looked into, built, ready for review, blocked, or needing their decision.
Never name firstmate internals in captain-facing messages: bootstrap, recovery, the session lock, the watcher, heartbeats, polling, "going quiet", crewmate, scout, ship, task ids, briefs, worktrees, status files, meta files, teardown, promotion, harness names such as pi or codex, context budgets, delivery-mode labels, or yolo labels.
Translate, don't expose: say the project is blocked, ready, or needs a decision instead of describing the machinery that found it.

Reaches the captain immediately:

- Work ready for review, with the full PR URL.
- Finished investigation findings, relayed as findings and not just "it's done".
- Review findings that need the captain's decision, relayed verbatim unless routine approval is authorized on firstmate judgment.
- A real blocker or failure after the playbook is exhausted, with evidence.
- Anything destructive, irreversible, or security-sensitive.
- A needed credential or login.

Does not reach the captain: auto-fixes, retries, routine progress, or firstmate's internal vocabulary and machinery.
Internal vocabulary and machinery include bootstrap, recovery, the session lock, the watcher, heartbeats, polling, "going quiet", crewmate, scout, ship, task ids, briefs, worktrees, status files, meta files, teardown, promotion, harness names, context budgets, delivery-mode labels, and yolo labels.
`` `

CLAUDE.md symlink:
`` `
AGENTS.md
`` `

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.

• git diff --stat 84e7d321709b16e1abf887253cbd7f8412b94659..15ca5c24c319cbce74abe94b652a4d49433e0ac5
• git diff --name-only 84e7d321709b16e1abf887253cbd7f8412b94659..15ca5c24c319cbce74abe94b652a4d49433e0ac5
• git diff --unified=3 84e7d321709b16e1abf887253cbd7f8412b94659..15ca5c24c319cbce74abe94b652a4d49433e0ac5 -- AGENTS.md
• test -L CLAUDE.md && test "$(readlink CLAUDE.md)" = "AGENTS.md"
• git diff --quiet 84e7d321709b16e1abf887253cbd7f8412b94659..15ca5c24c319cbce74abe94b652a4d49433e0ac5 -- . ':(exclude)AGENTS.md'
• perl -0ne 'BEGIN { $ok = 1 } $ok &&= /Captain-facing messages are plain outcomes about the captain.s work/; $ok &&= /CREW_HARNESS_OVERRIDE: <name> - record and use the override silently/; $ok &&= /Surface only what needs the captain: pending decisions, PRs ready to merge, failures, or needed credentials/; $ok &&= /state the project in plain outcome language/; $ok &&= /Talk in outcomes, not mechanics/; $ok &&= /Never name firstmate internals in captain-facing messages/; $ok &&= /Does not reach the captain: auto-fixes, retries, routine progress, or firstmate.s internal vocabulary and machinery/; END { exit($ok ? 0 : 1) }' AGENTS.md`
• Created reviewer evidence at /var/folders/5x/4nqprlbx0518k3ybcb1sz6gr0000gn/T/no-mistakes-evidence/01KV3W8MY3TN5K0KC9C93TDE5H/comms-plain-evidence.md
• git status --short

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[kboyd12]

Retired on the captain's decision, 2026-08-06, following the board triage of that date.

This is one of four prior dashboard framings (#16, #21, #26, #19) that the approved 2026-08-05 design work supersedes. #350 names them as "prior framings of this page, to fold in or close", and the captain has chosen to close.

Specifically: #350 argues against keying a dashboard off role at all, since capabilities resolve as a union across held roles and role-keying would reintroduce what #203 removed — which contradicts #16's premise directly. The Stitch-template framing in #21 is superseded by the three 2026-08-05 design studies. #26 and #19 are absorbed by that cluster plus #217 and the Project Detail epics #177–#181.

Nothing here is lost: a closed issue stays readable, and the live successors are #350, #217, #328 and #177–#181. Reopen if a requirement here turns out to have no successor.