From 7d1c694cd8bc444f3ddb7804249a49c90ccd0b7c Mon Sep 17 00:00:00 2001 From: kunchenguid Date: Thu, 3 Sep 2026 15:21:44 -0700 Subject: [PATCH 1/2] fix(bin): require a self-sufficient no-mistakes intent A no-mistakes worker's --intent is only as useful as the string it passes. PR #3604 shipped with an intent that was only "do 1, 2, 3, 7 from the report": the real contract lived in a private scout report and never reached --intent, so nobody holding that string plus the codebase could have derived the specification. This is pure instruction at the contract's one owner; no spawn-side or promotion-side check is added. - bin/fm-dod-lib.sh: the generated no-mistakes Definition of done now states that the --intent string must be self-sufficient (the string plus the codebase reconstructs roughly the same specification) and tells the worker to write the substance of any report, decision, or PR the captain's intent refers to into --intent rather than the pointer, while Firstmate build instructions and the worker's own decisions still stay out. The spawn-time overlay points back at that rule so its "supersedes" wording cannot cancel it, and the header's owner statement carries the rule. - AGENTS.md section 11 and bin/fm-brief.sh's header ask Firstmate to include the substance of referenced material when filling ## Captain's intent, and section 11 points at the owner of the rule. - tests/fm-brief.test.sh and tests/fm-task-delivery.test.sh assert the rendered brief and launch contract carry the rule. Claude-Session: https://claude.ai/code/session_01YMhEe42q7BAAoN6RxNuzim --- AGENTS.md | 4 ++-- bin/fm-brief.sh | 3 ++- bin/fm-dod-lib.sh | 15 +++++++++++---- tests/fm-brief.test.sh | 7 +++++++ tests/fm-task-delivery.test.sh | 3 +++ 5 files changed, 25 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 149894ad849..4d1776254d8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -520,8 +520,8 @@ Preserve durable structured identifiers, dependencies, and completion artifact l ## 11. Crewmate briefs `bin/fm-brief.sh` and its help own scaffold syntax, generated variants, status protocol, delivery-mode definitions of done, and exact safety mechanics. -Use its scaffold as the contract, then fill `## Captain's intent` (`{TASK}`) with the captain's own ask plus only the context needed to read it, and fill `## Firstmate spec` (`{FIRSTMATE_SPEC}`) with Firstmate's build instructions. -`bin/fm-dod-lib.sh` owns what a no-mistakes worker may pass as `--intent`. +Use its scaffold as the contract, then fill `## Captain's intent` (`{TASK}`) with the captain's own ask plus the context needed to read it, including the substance of any report, decision, or PR the ask refers to, and fill `## Firstmate spec` (`{FIRSTMATE_SPEC}`) with Firstmate's build instructions. +`bin/fm-dod-lib.sh` owns what a no-mistakes worker may pass as `--intent` and its rule that the string must be self-sufficient. Keep additions task-specific rather than repeating lifecycle instructions, and alter generated sections only when the task genuinely differs from the standard shape. Every ship brief must retain the worktree-isolation assertion and stop if launched in the primary checkout. diff --git a/bin/fm-brief.sh b/bin/fm-brief.sh index 3a80a701678..3a557f5ea01 100755 --- a/bin/fm-brief.sh +++ b/bin/fm-brief.sh @@ -4,7 +4,8 @@ # For ordinary tasks, the standard Setup/Rules/Definition-of-done contract is # filled in. Ship and scout `# Task` sections have two subsections Firstmate # fills before dispatch: `{TASK}` under `## Captain's intent` (the captain's -# own ask plus only the context needed to read it) and `{FIRSTMATE_SPEC}` +# own ask plus the context needed to read it, including the substance of any +# report, decision, or PR the ask refers to) and `{FIRSTMATE_SPEC}` # under `## Firstmate spec` (build instructions, which are never the captain's # intent). bin/fm-dod-lib.sh owns the no-mistakes `--intent` contract those # subsections feed; bin/fm-spawn.sh refuses leftover placeholders. Secondmate diff --git a/bin/fm-dod-lib.sh b/bin/fm-dod-lib.sh index d7d0f3ccc6e..557bcf981a9 100755 --- a/bin/fm-dod-lib.sh +++ b/bin/fm-dod-lib.sh @@ -12,10 +12,14 @@ # line that bin/fm-spawn.sh checks a ship brief against. # This file is the one owner of the no-mistakes `--intent` contract: only the # brief's `## Captain's intent` subsection plus later captain words, never -# `## Firstmate spec` and never the worker's own tradeoffs. bin/fm-brief.sh -# scaffolds those two `# Task` subsections; bin/fm-spawn.sh and bin/fm-promote.sh -# refuse leftover `{TASK}` / `{FIRSTMATE_SPEC}` placeholders through the helpers -# below. Other mentions of `--intent` point here rather than restating the rule. +# `## Firstmate spec` and never the worker's own tradeoffs. +# The string passed must be self-sufficient - it plus the codebase reconstructs +# roughly the same specification - so a report, decision, or PR the intent +# refers to is written into it as substance, never left as a pointer. +# bin/fm-brief.sh scaffolds those two `# Task` subsections; bin/fm-spawn.sh and +# bin/fm-promote.sh refuse leftover `{TASK}` / `{FIRSTMATE_SPEC}` placeholders +# through the helpers below. Other mentions of `--intent` point here rather than +# restating the rule. # Every heredoc here stays outside a command substitution: `VAR=$(cat < Date: Thu, 3 Sep 2026 15:49:51 -0700 Subject: [PATCH 2/2] no-mistakes(document): Replace incident-specific intent test commentary --- tests/fm-brief.test.sh | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/fm-brief.test.sh b/tests/fm-brief.test.sh index 7c0c51f7a61..dabff8d67de 100755 --- a/tests/fm-brief.test.sh +++ b/tests/fm-brief.test.sh @@ -351,9 +351,9 @@ test_no_mistakes_dod_wording() { "no-mistakes DOD must keep worker tradeoffs out of --intent" assert_grep "This replaces the no-mistakes skill's advice to enrich \`--intent\`" "$brief" \ "no-mistakes DOD must override the external skill's enrich-with-decisions guidance" - # The passed string must be self-sufficient (PR #3604 shipped with an intent that - # was only "do 1, 2, 3, 7 from the report"), so the rendered DOD states the rule - # and tells the worker to resolve referenced material into its substance. + # A bare reference cannot preserve the captain's ask, so the rendered DOD states + # the self-sufficiency rule and requires referenced material to be resolved into + # its substance. assert_grep "The \`--intent\` string you pass must be self-sufficient" "$brief" \ "no-mistakes DOD must require a self-sufficient --intent string" assert_grep "write the substance of the referenced items into \`--intent\`" "$brief" \