feat(bin): add a token-efficiency work policy to the owner contract and ship briefs - #1971
Open
Andy7596183 wants to merge 10 commits into
Open
feat(bin): add a token-efficiency work policy to the owner contract and ship briefs#1971Andy7596183 wants to merge 10 commits into
Andy7596183 wants to merge 10 commits into
Conversation
…o existing owner language
…op boundary mode-neutral
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Intent
Codify a small, durable Firstmate policy for token-efficient work that never weakens intelligence, reasoning, accepted scope, evidence, validation, or safety. Inspect existing authoritative contracts first and patch their owner language rather than appending a parallel policy or duplicating rules already present. The policy must apply across project tasks and supported worker runtimes without depending on one model vendor or an optional plugin. Save tokens by eliminating duplicated work, irrelevant raw context, and repeated evidence collection, not by lowering the task-appropriate model or effort solely to conserve quota. Preserve direct user requirements, authoritative source material, durable decisions, and necessary targeted rereads; never rely on a lossy summary when an exact source is required to act safely or correctly. During implementation and correction loops, group related fixes and prefer the smallest focused checks that establish changed behavior before rerunning broader suites. The selected delivery path remains authoritative: required final tests, documentation, review, no-mistakes gates, PR checks, and CI may never be skipped, narrowed, or replaced for token savings. Do not commission optional duplicate reviewers or repeat an already-answered investigation unless the captain explicitly requested that deliverable or new evidence could materially change the outcome. Do not restart, duplicate, or supersede an active validation run to save tokens; preserve its fixes and drive its current gate. Keep independent ready work moving, but do not create redundant parallel work on the same deliverable. This is an instruction-policy change, not new machinery: do not add wrappers, hooks, daemons, background processes, model routers, token counters, custom verifiers, or new runtime state. Do not change watcher, supervision, dispatch, no-mistakes, merge-authority, approval, worktree, recovery, destructive-action, or security-sensitive contracts. Preserve automatic no-mistakes and green-merge behavior, routine yolo decision authority, required captain boundaries, and true semantic dependency handling. Keep the always-loaded addition concise. Use the documentation audience inventory and one-owner rule to place supporting prose; do not create a new skill without a genuine conditional trigger. Validate the complete final diff for contradictory or duplicate rules. Run bin/fm-doc-audience-check.sh and every existing relevant documentation/instruction check. Do not add source-text assertion tests. Commit the minimal coherent change, run the full no-mistakes path, and report the green PR URL. Do not create a standalone HTML summary.
What Changed
AGENTS.md: folded token-efficiency rules into the existing owner clauses instead of a parallel section — savings must come from eliminating duplicated work, irrelevant raw context, and repeated evidence collection, never from weakening accepted scope, reasoning, evidence, validation, or safety; model and effort are chosen from the accepted work and dispatch evidence and never lowered to conserve quota; the selected delivery path's required final tests, docs, review, no-mistakes gates, PR checks, and CI can't be skipped, narrowed, or replaced; an active validation run can't be restarted, duplicated, or superseded for token savings; and dispatch may not create redundant parallel work on the same deliverable.bin/fm-brief.sh: generated ship briefs now carry a worker-owned iteration rule (rule 8) to group related fixes behind the smallest focused checks that establish the changed behavior before rerunning broader suites, explicitly bounded so it ends when the mode's required final checks begin and never narrows the Definition of done; the script header documents the same rule.bin/fm-promote.sh: the promotion handoff hint relays that mode-neutral loop guidance to a promoted scout, whose original brief never contained it. Tests assert the guidance appears in all three ship-mode briefs and in the promotion hint, and that the hint's payload stays safe under its own single quoting.Risk Assessment
✅ Low: Instruction-policy-only change: five net lines of always-loaded prose plus mode-neutral guidance in two generated interfaces, with no new machinery, no runtime state, every intent criterion traceable to a specific line, the earlier out-of-scope quota-array-dispatch edit fully reverted to base, and new assertions that exercise emitted output rather than implementation source.
Testing
Ran the documentation-audience check and the targeted tests covering both changed scripts (fm-brief, fm-task-delivery, fm-documentation-audiences, fm-ask-user-authority, fm-tangle-guard, fm-secondmate-safety, fm-subagent-pretool-check) — all pass — then went past the unit assertions and exercised the real surfaces: generated actual ship briefs for all three delivery modes plus a scout, confirming the new grouped-fix/focused-check rule renders with its "never narrows your Definition of done" boundary in every ship mode and is absent from the scout brief, and ran the scout-to-ship promotion end-to-end, shell-parsing and executing its emitted handoff command against a stub fm-send.sh to prove the relayed instructions reach the promoted crewmate as one intact argument. No rendered UI exists in this change (it edits AGENTS.md prose and two bash scripts that emit agent instruction text), so evidence is the generated brief and executed CLI transcripts rather than screenshots. Transient temp state was removed and the worktree is clean; no findings.
Evidence: Generated crewmate ship brief (no-mistakes mode) carrying the new rule 8
Evidence: New brief rule as rendered in all three ship modes (and absent from the scout brief)
===== mode=no-mistakes : tail of the # Rules section ===== 8. While the change is still yours to edit, group related fixes and run the smallest focused checks that establish the changed behavior before rerunning broader suites. This ordering ends when this mode's required final checks begin, and it never narrows what your Definition of done requires. (identical rule 8 renders for mode=direct-PR and mode=local-only) ===== --scout ===== rule-8 lines in scout brief: 0Evidence: Scout to ship promotion handoff executed end-to-end
$ FM_HOME=<home> bin/fm-promote.sh demo-scout --mode no-mistakes --yolo on promoted demo-scout to ship mode=no-mistakes yolo=on (teardown protection restored) next: FM_HOME=<home> bin/fm-send.sh fm-demo-scout '<ship instructions for mode=no-mistakes: ... implement, grouping related fixes and running the smallest focused checks that establish the changed behavior before rerunning broader suites; that ordering ends when the final checks this delivery mode requires begin, and never narrows the definition of done; report done>' task record after promotion: window=fm-demo-scout / kind=ship / mode=no-mistakes / yolo=on The captain runs that emitted command. Executed here against a stub fm-send.sh: fm-send.sh received argc=2 arg1 (window) = fm-demo-scout arg2 = the full ship instructions above, delivered intact as a single argumentEvidence: AGENTS.md policy sentences shown under the owner sections they were patched into
[## 4. Harness and runtime dispatch] AGENTS.md:190 - task-appropriate model/effort, never lowered solely to conserve tokens or quota [### Intake and authority] AGENTS.md:263-265 - save tokens by removing duplicated work/irrelevant context/repeated evidence; preserve requirements, sources, durable decisions, targeted rereads; grouped fixes behind smallest focused checks for direct work [### Intake and authority] AGENTS.md:283 - no redundant parallel work for the same deliverable [### Selected delivery path and approval authority] AGENTS.md:302 - token savings never skip/narrow/replace required final tests, docs, review, gates, PR checks, or CI [### Validate] AGENTS.md:329 - token savings never authorize restarting/duplicating/superseding an active validation run AGENTS.md total lines: 562 (net +7)Pipeline
Updates from git push no-mistakes
✅ **intent** - passed
✅ No issues found.
✅ **Rebase** - passed
✅ No issues found.
🔧 **Review** - 3 issues found → auto-fixed (3) ✅
AGENTS.md:325- Commit 71bb97d removed the always-loaded copy of the focused-check loop rule ("Within each delivery-path owner's implementation and correction loops, group related fixes and run the smallest focused checks...") from the Validate section, leaving it only in generated ship briefs (bin/fm-brief.sh:454) and the scout-promotion hint (bin/fm-promote.sh:89). That covers crewmates doing project tasks, which is what the intent's "across project tasks and supported worker runtimes" asks for, but AGENTS.md:40 explicitly authorizes firstmate to change shared tracked material directly when the fleet is empty, and secondmates read AGENTS.md rather than a generated brief. Those actors run their own implementation and correction loops and no longer see the rule anywhere. Confirm the narrowing to crewmate briefs is intended, or restore a one-clause owner sentence for the firstmate/secondmate path.bin/fm-brief.sh:454- Ship-brief rule 8 says "While implementing and correcting your own work, group related fixes and run the smallest focused checks..." with no scoping to the pre-validation phase. In no-mistakes mode the same brief later states "Do not hand-edit, commit, or fix findings yourself while a run is active - the pipeline applies every fix" (bin/fm-brief.sh:394), and AGENTS.md:345 treats a worker fixing/committing during an active run as duplicated pipeline ownership. Rule 8's guard only protects the Definition of done from being narrowed; it does not say when the loop applies, so a worker mid-pipeline could read a prominent numbered rule as sanction to batch its own fixes. The promotion handoff has the same gap. Scoping the clause (e.g. "while implementing, before validation starts") would close it.AGENTS.md:281- "Keep independent ready work moving" restates the rule stated in full on the very next line ("dispatch isolated work immediately with no concurrency cap when each change can be independently implemented and validated..."). The only new normative content in the added line is "never dispatch redundant parallel work for the same deliverable," which could be appended to the existing owner sentence instead of adding a line. Given the intent's "Keep the always-loaded addition concise" and "patch their owner language rather than appending a parallel policy or duplicating rules already present," the duplicated clause is worth folding in.🔧 Fix: Restore owner loop clause and scope pre-validation guidance
2 issues (1 warning, 1 info) still open:
.agents/skills/quota-array-dispatch/SKILL.md:92- Fix round 71bb97d deleted "rather than downgrading it to conserve quota" from selection-order step 3 of the quota-array-dispatch skill. The intent says "Do not change watcher, supervision, dispatch, no-mistakes, ... contracts," and AGENTS.md:193 names this skill "the single owner of the completion-aware selection procedure" - so this is an edit to a dispatch contract. It is also out of scope for the change: the author's own commit (44cf86a) never touched this file, and the duplication being removed was pre-existing, not introduced here. The behavior has a dedicated eval case named for it (tests/fm-quota-array-dispatch-live-e2e.test.sh:103, "required strongest reasoning class is not downgraded for quota"), and docs/verification/dispatch-auth.md:178 lists "the strongest-reasoning constraint" as covered regression surface; removing the only clause in the step that names the quota motive weakens the signal that case exercises. Mitigating: the prohibition is still implied by SKILL.md:89 ("Never use headroom, runway, pace, or reserve to silently replace that reasoning class"), step 3's first sentence, and AGENTS.md:190. Either restore the clause or confirm the dispatch-contract edit is intended.AGENTS.md:264- The restored owner clause opens "When firstmate or a secondmate implements or corrects work directly, ..." without naming the narrow authority that makes that premise legal. Every other place in this file that contemplates firstmate touching code anchors it explicitly - AGENTS.md:54, :88, and :221 all say "hard rule 1's concrete captain-approved project operation exception," and AGENTS.md:40 scopes the other case to "when the fleet is empty, firstmate may change [shared tracked material] directly." AGENTS.md:16-17 and hard rule 1 ("Never write to a project") are the top-priority rules of the document. A conditional clause is not an authority grant, so this is not a contradiction, but in an always-loaded rule file read by an agent it normalizes the premise without the guardrail the rest of the file consistently attaches. Anchoring it (e.g. "When firstmate or a secondmate implements or corrects work directly under section 1's exceptions, ...") costs a few words and matches the established convention.🔧 Fix: Restore dispatch clause and anchor direct-work loop guidance
2 infos still open:
AGENTS.md:190- The intent requires token savings "not by lowering the task-appropriate model or effort solely to conserve quota" as an unconditional rule. The author's commit 44cf86a wrote it that way ("Choose the task-appropriate model and effort from the accepted work and dispatch evidence; never lower either solely to conserve tokens or quota"), but the pipeline's consolidation commit 5bd2921 deleted that sentence and folded its content into the pre-existing tight-candidate sentence, which is guarded by "When every candidate is tight". As a result the concrete model/effort anti-downgrade rule now only fires inside a tight quota-array selection; an ordinary dispatch that picks a cheaper model or lower effort while quota is plentiful is no longer covered by section 4 language. AGENTS.md:194 selects effort by task nature but never forbids a token-motivated downgrade, and AGENTS.md:262's "never by weakening ... necessary reasoning" is the only remaining general coverage. Confirm the tight-candidate scoping is intended, or restore the unconditional phrasing (e.g. drop the tight-case guard from the model/effort half, or name model and effort in AGENTS.md:262).bin/fm-brief.sh:454- Rule 8 is emitted into the shared ship-brief rules block, so it reaches all three delivery modes, but its scoping term "Before validation starts" only has a referent in no-mistakes mode. The direct-PR Definition of done (bin/fm-brief.sh:364) says "Do NOT run /no-mistakes" and the local-only one (bin/fm-brief.sh:373) says "no remote, no PR, no pipeline", and neither block uses the word validation - so for those workers the condition never becomes false and the clause reads as standing guidance right through their final pre-push checks. bin/fm-promote.sh:89 carries the same phrasing ("apply only before validation starts") into a hint whose --mode may be direct-PR or local-only. Mitigating: the clause is an ordering rule that presumes "rerunning broader suites", and the second sentence still protects the Definition of done, so nothing is authorized to be skipped. Consider a mode-neutral phrasing (e.g. "while implementing, before you hand the change to this mode's final checks") or omitting rule 8 from the non-pipeline modes.🔧 Fix: Restore unconditional model/effort rule, make loop boundary mode-neutral
✅ Re-checked - no issues remain.
✅ **Test** - passed
✅ No issues found.
bin/fm-doc-audience-check.sh(ok surfaces=65 local_links=214)bin/fm-test-run.sh tests/fm-brief.test.sh tests/fm-task-delivery.test.sh tests/fm-documentation-audiences.test.shbin/fm-test-run.sh tests/fm-ask-user-authority.test.sh tests/fm-tangle-guard.test.sh tests/fm-secondmate-safety.test.sh tests/fm-subagent-pretool-check.test.sh(all remaining consumers of bin/fm-brief.sh and bin/fm-promote.sh)Manual: generated real briefs withFM_HOME=<tmp> bin/fm-brief.sh demo-<mode> some-proj --mode no-mistakes|direct-PR|local-onlyand--scout, then read the rendered# Rulessection a crewmate receivesManual:FM_HOME=<tmp> FM_STATE_OVERRIDE=<tmp>/state bin/fm-promote.sh demo-scout --mode no-mistakes --yolo onend-to-end, inspecting the resulting.metarecordManual:bash -non the emittednext:command, then executed it viaevalagainst a stubbin/fm-send.shto confirm the ship instructions arrive as one intact argument (argc=2)Manual: extracted each new AGENTS.md sentence with its enclosing section heading to confirm owner-section placement instead of a parallel policy blockbin/fm-test-run.sh --list --changed --base 833a9a2to scope the relevant test setAGENTS.md:265- Duplicate-rule validation over the final diff: AGENTS.md:265 ends the interim grouped-fix ordering at "the delivery path's required final checks" and AGENTS.md:302 states the delivery path's own rigor rule enumerating those gates. I judged this a deliberate boundary clause at the intake owner rather than a second copy of the delivery-path contract (each is operative in its own section, and the loop rule is unsafe without its boundary), so I left both. Flagging it as the one near-overlap the diff contains, in case a later consolidation pass wants the boundary reduced to a bare cross-reference to the delivery-path section.✅ **Lint** - passed
✅ No issues found.
✅ **Push** - passed
✅ No issues found.