From fb309386913c02f1f0e7d57c0fec77ebdceb5019 Mon Sep 17 00:00:00 2001 From: Big Nuge Date: Tue, 4 Aug 2026 02:42:59 -0700 Subject: [PATCH] feat(agents): escalate a contradiction with the captain's word AGENTS.md section 9 now states that firstmate never resolves a contradiction between its own analysis and something the captain decided. Substituting a different mechanism, reinterpreting either side, or narrowing his words down to what is buildable is inventing under his authority, so the contradiction goes back to him with the evidence and the options before any work is shaped around it. The immediate-escalation list carries a matching entry. The wording is captain-approved verbatim, adapted only to the repo's plain-dash and one-sentence-per-line style. Section 9's existing static regression test covers the new rule and guards it against a second copy landing in ask-user-authority, decision-hold-lifecycle, or the brief scaffold. bin/fm-brief.sh keeps its own worker-facing sibling of this idea unchanged: it addresses a different actor through a different escalation channel and has to stand alone for a worker that never loads this file. --- AGENTS.md | 6 ++++ tests/fm-captain-translation-contract.test.sh | 28 ++++++++++++++++++- 2 files changed, 33 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 973862ae36f..610c802fae3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -431,11 +431,17 @@ Every escalation must stand alone and remain concise. Lead directly with concrete evidence, then the consequence, options when applicable, and a recommendation. Use the same evidence-first form for objections or clarifying challenges rather than unsupported deference. +**Never resolve a contradiction with the captain's word yourself.** +When firstmate's own analysis contradicts something the captain decided - because the code cannot do it as stated, because measurement disagrees, or because two of his rulings pull apart - that contradiction is his to resolve, not firstmate's to reconcile. +Surface it with the evidence and the options. +Substituting a different mechanism, reinterpreting either side, or narrowing his words down to what is buildable is inventing under his authority, however much it looks like plumbing from the inside. + Reach the captain immediately for: - Work ready for their review, with the full PR URL. - Finished investigation findings, relayed as findings rather than only a completion notice. - Gate findings that require their decision under the configured authority. +- A contradiction between the captain's word and what firstmate has found, before any work is shaped around it. - A real blocker or failure after the relevant playbook is exhausted. - Anything destructive, irreversible, or security-sensitive. - A needed credential or login. diff --git a/tests/fm-captain-translation-contract.test.sh b/tests/fm-captain-translation-contract.test.sh index cc7c75311ee..93294296b74 100755 --- a/tests/fm-captain-translation-contract.test.sh +++ b/tests/fm-captain-translation-contract.test.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash # Static regression tests for the captain-facing plain-English translation -# contract owned by AGENTS.md section 9. +# contract and the escalation rules owned by AGENTS.md section 9. # shellcheck disable=SC2016 set -u @@ -11,6 +11,7 @@ AGENTS="$ROOT/AGENTS.md" BOOTSTRAP="$ROOT/.agents/skills/bootstrap-diagnostics/SKILL.md" AFK="$ROOT/.agents/skills/afk/SKILL.md" DECISION="$ROOT/.agents/skills/decision-hold-lifecycle/SKILL.md" +ASK_USER="$ROOT/.agents/skills/ask-user-authority/SKILL.md" RECOVERY="$ROOT/.agents/skills/stuck-crewmate-recovery/SKILL.md" HARNESS="$ROOT/.agents/skills/harness-adapters/SKILL.md" CODEXAPP="$ROOT/.agents/skills/firstmate-codexapp/SKILL.md" @@ -18,6 +19,7 @@ FMX="$ROOT/.agents/skills/fmx-respond/SKILL.md" UPDATE="$ROOT/.agents/skills/updatefirstmate/SKILL.md" AHOY="$ROOT/.agents/skills/ahoy/SKILL.md" README="$ROOT/README.md" +BRIEF="$ROOT/bin/fm-brief.sh" section_9() { awk ' @@ -113,6 +115,29 @@ test_routine_no_action_response_is_event_scoped() { pass "routine no-action response is exact and scoped to its event" } +# Section 9 also owns the rule that firstmate never reconciles a contradiction +# with the captain's word on its own. The adjacent authority owners carry their +# own scoped contracts - ask-user findings, unresolved decision holds, and the +# worker-facing brief scaffold - and none of them may grow a second copy of this +# one, because the copy that is not edited is the one a session will believe. +test_section_9_owns_the_contradiction_escalation_rule() { + local contract file + contract=$(section_9) + assert_contains "$contract" "**Never resolve a contradiction with the captain's word yourself.**" \ + "section 9 does not own the contradiction-escalation rule" + assert_contains "$contract" "that contradiction is his to resolve, not firstmate's to reconcile" \ + "section 9 does not leave the contradiction with the captain" + assert_contains "$contract" "is inventing under his authority, however much it looks like plumbing from the inside" \ + "section 9 does not name reinterpretation as inventing under the captain's authority" + assert_contains "$contract" "- A contradiction between the captain's word and what firstmate has found, before any work is shaped around it." \ + "the immediate-escalation list does not carry the contradiction bullet" + for file in "$ASK_USER" "$DECISION" "$BRIEF"; do + assert_no_grep "not firstmate's to reconcile" "$file" \ + "$(basename "$file") duplicated section 9's contradiction-escalation owner" + done + pass "section 9 solely owns the contradiction-escalation rule" +} + test_outward_facing_skill_points_reference_section_9_owner() { assert_grep "using \`AGENTS.md\` section 9's captain-facing translation contract" "$BOOTSTRAP" \ "bootstrap diagnostics do not reference section 9 at captain handoff" @@ -284,6 +309,7 @@ test_compressed_safety_labels_have_plain_renderings test_mapping_list_covers_high_risk_internal_families test_verbatim_internal_evidence_is_rejected_from_chat test_routine_no_action_response_is_event_scoped +test_section_9_owns_the_contradiction_escalation_rule test_outward_facing_skill_points_reference_section_9_owner test_section_9_owner_is_not_duplicated_into_skills test_ahoy_is_an_internal_user_invocable_skill