feat(bin): carry standing worker rules in generated fm-brief scaffolds - #1395
Open
sbracewell64 wants to merge 3 commits into
Open
feat(bin): carry standing worker rules in generated fm-brief scaffolds#1395sbracewell64 wants to merge 3 commits into
sbracewell64 wants to merge 3 commits into
Conversation
Owner
|
Automated reminder: thanks for the PR! This branch currently has a merge conflict with the base branch. When you get a chance, please rebase onto (or merge) the latest base branch, resolve the conflict, and push. After that, checks will re-run and the PR will get looked at again. Noted for firstmate#1395 at |
kunchenguid
added
the
wheelhouse:pending-contributor-action
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
2 participants
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
Put the captain-approved standing worker rules for delegated branch conflict resolution and verification discipline where workers actually read them: the generated fm-brief scaffold and the firstmate-coding-guidelines skill. Branch-shipping briefs must require autonomous rebase/conflict resolution at any file count when intent is clear, with base changes retained where the branch made no deliberate change, branch contributions reapplied, all prior pipeline fix commits preserved, and only genuinely ambiguous intent escalated to firstmate, never the captain. Any variant that may run verification must require a witnessed negative control before trusting success-by-absence checks and must wait on completion artifacts rather than process names, treating a missing expected artifact at collection as failure. Ship briefs carry both rules; scout and secondmate variants carry verification only because they do not directly ship branches. Keep generated prose terse, state the measured ship-scaffold byte delta and generated output plus variant rationale in the PR body, carry the same rules in the coding skill by reference where cleaner, and make documentation/contract-text changes only with no runtime guard or enforcement code.
What Changed
bin/fm-brief.shemits two new heredoc sections into generated briefs:# Verification discipline(witness a negative control fail before trusting success-by-absence, wait on completion artifacts rather than process names, treat a missing artifact at collection as failure) and# Branch conflict resolution(rebase and resolve branch/base conflicts autonomously at any file count when intent is clear — keep base where the branch made no deliberate change, reapply branch contributions, preserve every prior pipeline fix commit, escalate only genuinely ambiguous intent to firstmate, never the captain). Verification discipline is interpolated into ship, scout, and secondmate scaffolds; branch conflict resolution only into ship, since scout and secondmate never ship a branch directly. The no-mistakes Definition of done gains a one-line carve-out naming the delegated rebase as the exception to "do not hand-edit or commit while a run is active", and the script header/--helpdocuments both new sections.AGENTS.mdnotes the delegated-rebase exception to its worker-validation rule, and.agents/skills/firstmate-coding-guidelines/SKILL.mdpoints at the two generated sections by reference rather than restating them.tests/fm-brief.test.shaddstest_standing_worker_rules_by_variant, pinning presence/absence of each section per variant plus the individual rule lines, and extends the--helpheader test to cover the new documentation lines.Risk Assessment
✅ Low: Documentation and contract-text only (102 added lines across a scaffold's generated prose, its --help header, and a new behavior test) with no runtime guard or enforcement code, all three prior findings resolved, the rule-vs-DOD contradiction now explicitly carved out and pinned by tests, and every source-verifiable acceptance criterion satisfied.
Testing
Ran the targeted fm-brief and documentation-audiences suites (all pass), then generated real briefs from both the base and target commits and diffed them to show what a worker actually reads: ship variants (no-mistakes, direct-PR, local-only, herdr-lab) gain both the branch-conflict-resolution and verification-discipline sections, scout and secondmate variants gain verification discipline only, and the no-mistakes definition-of-done gains the delegated-rebase carve-out while direct-PR correctly does not. Rule wording matches every required constraint and no brief escalates to the captain; measured ship-scaffold growth is +882 bytes for no-mistakes and +720 for other ship modes (verification 350 B + conflict 370 B + 162 B carve-out), with scout and secondmate at +350. The change is documentation/contract text only — no runtime guard or enforcement code was added. No screenshots apply: the end-user surface here is generated markdown brief text and CLI --help output, both captured verbatim as artifacts.
Evidence: Generated ship brief diff (base → head, no-mistakes mode) — shows both new sections and the delegated-rebase carve-out as the worker reads them
+# Branch conflict resolution +Rebase and resolve branch/base conflicts yourself whenever intent is clear, at any file count: keep the base wherever this branch made no deliberate change, reapply this branch's contributions on top, and preserve every prior pipeline fix commit through the rebase. +Escalate only genuinely ambiguous intent to firstmate, never the captain. + +# Verification discipline +- Before trusting success reported only by absence - an empty violations log, no output, or no failures - run a negative control and watch it fail, then run the real check. +- Wait on completion artifacts, never process names. + At collection time, report a missing expected artifact as failure, not as a job still running. ... (Definition of done) +The one exception is a rebase the pipeline hands back to you: resolve and commit it under# Branch conflict resolutionabove, then return to driving the gates.Evidence: Variant coverage matrix over 8 generated briefs + captain-escalation leak check
VARIANT KIND #BranchConflict #Verification RebaseCarveOut ship-nomistakes ship PRESENT PRESENT PRESENT ship-directpr ship PRESENT PRESENT absent ship-localonly ship PRESENT PRESENT absent ship-herdr ship PRESENT PRESENT PRESENT scout-demo scout absent PRESENT absent scout-herdr scout absent PRESENT absent secondmate-demo secondmate absent PRESENT absent secondmate-projects secondmate absent PRESENT absent captain-escalation leak check (must be 0 hits across all generated briefs): 0Evidence: Measured generated-brief byte delta (identical root/home layout), base f7d0d0a → head 911e248
ship-nomistakes 5883 -> 6765 (+882 bytes) ship-directpr 4825 -> 5545 (+720 bytes) scout-demo 3632 -> 3982 (+350 bytes) secondmate-demo 5513 -> 5863 (+350 bytes) Decomposition: verification discipline 350 B (all variants) + branch conflict resolution 370 B (ship only) + 162 B delegated-rebase carve-out (no-mistakes DOD only).Evidence: Generated scout brief diff — verification only, no branch conflict section
Evidence: Generated secondmate charter diff — verification only
Evidence: Full generated ship brief (head) as the worker receives it
Evidence: `bin/fm-brief.sh --help` excerpt documenting the generated sections
Every scaffold carries a verification-discipline section: witness a negative control fail before trusting success reported only by absence, and wait on completion artifacts rather than process names. Ship scaffolds additionally carry branch conflict resolution: rebase and resolve branch/base conflicts autonomously at any file count when intent is clear, escalating only genuinely ambiguous intent to firstmate. In no-mistakes mode that delegated rebase is the stated exception to the do-not-commit-while-a-run-is-active rule.Evidence: firstmate-coding-guidelines skill section (rule carried by reference)
## Generated worker discipline For firstmate-repo work, the generated# Branch conflict resolutionand# Verification disciplinesections inbin/fm-brief.shown the full worker rules. Follow both for branch shipping and verification even if the current task was scaffolded before those sections existed.Pipeline
Updates from git push no-mistakes
✅ **intent** - passed
✅ No issues found.
✅ **Rebase** - passed
✅ No issues found.
🔧 **Review** - 3 issues found → auto-fixed ✅
bin/fm-brief.sh:141- The new ship-brief rule at bin/fm-brief.sh:141 tells the worker "Rebase and resolve branch/base conflicts yourself whenever intent is clear, at any file count", but the same generated brief's no-mistakes Definition of done (bin/fm-brief.sh:360) states "Do not hand-edit, commit, or fix findings yourself while a run is active - the pipeline applies every fix." A delegated conflict resolution during an active pipeline run is exactly hand-editing and committing while a run is active, so the brief gives the reading agent two opposing instructions for the same moment with no scoping clause. The brief is the sole contract the worker reads, so the ambiguity resolves at runtime by guesswork: one reading stalls on a rebase gate it was told to resolve, the other commits during a run it was told not to touch. A one-clause carve-out (e.g. noting that pipeline-delegated rebases are the exception to the no-commit rule) would remove it without adding prose bulk.bin/fm-brief.sh:46- fm-brief.sh's header comment is its --help output (rendered by the awk block at lines 53-57) and documents each generated section family it emits - the worktree-isolation assertion at line 36, the project-memory section at lines 42-46, the Herdr contract at lines 24-28. The two new unconditional sections are emitted into every ship, scout, and secondmate brief but are not described there, so --help now understates what the scaffold generates. This also drifts from the coding skill's own tier-7 placement rule (mechanics live in the script header plus --help). Add one line to the header block before line 47's "Refuses to overwrite an existing brief." terminator noting that every scaffold carries the verification-discipline section and ship scaffolds additionally carry branch conflict resolution.tests/fm-brief.test.sh:208- tests/fm-brief.test.sh asserts the presence of every other generated section per variant - Definition of done and the {TASK} placeholder at lines 208-209, the Herdr contract headings at 292 and 344, the project-memory lines at 275-279, the secondmate status protocol at 407-434. The two new sections have no equivalent assertion in any variant, so a later edit to the heredocs or to the interpolation points (bin/fm-brief.sh:188, :304, :420, :422) can silently drop a captain-approved standing rule from generated briefs with the suite still green. Add assert_grep for "# Verification discipline" in the ship, scout, and secondmate cases, plus assert_grep for "# Branch conflict resolution" in ship and assert_no_grep for it in scout and secondmate, matching the variant split the change deliberately encodes.🔧 Fix: Scope rebase carve-out, document sections, test variant split
✅ Re-checked - no issues remain.
✅ **Test** - passed
✅ No issues found.
bash tests/fm-brief.test.sh— full fm-brief behavior suite including the newtest_standing_worker_rules_by_variantbash tests/fm-documentation-audiences.test.sh— validates local link resolution for the edited.agents/skills/firstmate-coding-guidelines/SKILL.mdGenerated real briefs at base f7d0d0a and target 911e248 from identical root/home layouts:FM_HOME=... bin/fm-brief.sh <id> <proj>,--scout,--herdr-lab,--secondmate --no-projects,--secondmate <proj>, and local-only/direct-PR registry modes; diffed the resultingbrief.mdfilesSection-presence matrix over 8 generated brief variants (grep '^# Branch conflict resolution$','^# Verification discipline$', delegated-rebase carve-out line)Captain-escalation leak check across all generated briefs (grep -rn 'escalate .*to the captain' data/) — 0 hitsMeasured ship-scaffold byte delta with path lengths held constant (wc -cbase vs head per variant)bin/fm-brief.sh --help— confirmed both new documentation lines renderVerified the relative skill link../../../bin/fm-brief.shresolves to the real scriptgit diff f7d0d0a..911e248 -- bin/fm-brief.sh | grep '^+' | grep -E '(if|case|exit|\[|test |grep|return)'— confirmed no runtime guard/enforcement code added✅ **Document** - passed
✅ No issues found.
✅ **Lint** - passed
✅ No issues found.
✅ **Push** - passed
✅ No issues found.