feat(brief): add context-discipline guidance to crewmate scaffold - #1848
Open
RosanFiqri wants to merge 2 commits into
Open
feat(brief): add context-discipline guidance to crewmate scaffold#1848RosanFiqri wants to merge 2 commits into
RosanFiqri wants to merge 2 commits into
Conversation
A live worker was measured mid-task with cumulative tool costs (browser captures, file reads) exceeding the live context window, meaning that material was paid for, compacted away, and in several cases read again. A captain-side usage reading separately showed context is billed per turn, so a worker sitting at high context pays that cost repeatedly for as long as it runs. Add two short additions to the generated ship and scout briefs: worker-owned compaction at the next natural phase boundary once past ~150k tokens (never externally injected, since firstmate cannot see whether a worker is mid-file-write or holding a gate open), and intake discipline (read with offset/limit, don't re-read unchanged files, keep captures targeted). Also strengthen the existing gh-axi/chrome-devtools-axi rule with the measured cost of a worker that skipped it and drove browser work through the MCP path instead, burning 662k tokens. External threshold-triggered compaction (firstmate polling and injecting /compact into workers) was considered and rejected: firstmate cannot see a worker's phase boundaries, and no demonstrated blocker justifies that machinery over the worker owning its own compaction.
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.
Summary
Adds context-discipline guidance to the crewmate brief scaffold (
bin/fm-brief.sh) so future workers manage their own context window deliberately instead of accumulating until the runtime compacts for them.Two short additions to the generated ship and scout Rules sections:
It never compacts mid-validation-run or while holding a gate open. Firstmate still never injects
/compactinto a worker from outside - it cannot see whether a worker is mid-write, mid-gate, or holding pipeline ownership, so the threshold stays the worker's own to act on.Also strengthens the existing "Use gh-axi for GitHub operations and chrome-devtools-axi for browser operations" rule into a stated cost rule, since it was measurably ignored: a previous fleet worker drove browser work through the MCP browser path instead of
chrome-devtools-axiand burned 662,300 tokens doing it - the single largest context consumer measured in that run.Why the evidence pointed this way
A live crewmate (Sonnet 5, a long multi-phase build) was measured mid-task at 61% context, not in distress, with the runtime's own compaction buffer already reserved. But its cumulative per-tool token costs (662.3k for browser batching, 406k for file reads) exceeded the live context window, meaning that material was paid for, compacted away, and in several cases read again. Intake cost, not conversation sprawl, was the dominant cost.
A separate
/usagereading on the captain's account showed context is billed per turn, not once: 76% of usage was at >150k context, and a worker sitting at high context pays a multiple of that cost on every single turn for as long as it runs.External threshold-triggered compaction was considered and rejected
An earlier draft omitted a specific token number, reasoning that a number invites compacting on a schedule rather than at a safe moment. That's addressed here by requiring both the ~150k condition and the phase-boundary condition together - one names when it's overdue, the other says when it's safe to act.
Separately, firstmate itself never injects
/compactinto a worker: firstmate cannot see whether a worker is mid-file-write, mid-validation-gate, or holding pipeline ownership, so an externally triggered compaction risks landing mid-thought. Only the worker knows where its own phase boundaries are, so compaction stays worker-owned rather than becoming external machinery - consistent with AGENTS.md section 7's bar that machinery needs a demonstrated blocker, and no such blocker exists here since the runtime's own compaction already works.Scope
Only the generated brief text changed - no new script logic, flags, configuration, or
context-inspecting machinery. The worktree-isolation assertion, status protocol, paused/blocked distinction, no-mistakes delivery contract, and ask-user escalation rule are untouched. The secondmate charter scaffold is deliberately untouched too: it's a persistent home, not a short-lived task worker with phase boundaries to compact at.
AGENTS.mdis untouched (owned by a separate task).Test plan
bash -n bin/fm-brief.shsyntax checkbin/fm-lint.sh bin/fm-brief.sh(ShellCheck 0.11.0, pinned) clean--scout,--herdr-lab,--secondmate) into a tempFM_HOME- all generate without error, and the new guidance reads naturally in place in the ship and scout output