Repository navigation
feat(prompts): pass agent reports and plan as file paths - #776
Merged
Merged
Conversation
plan-files.cjs holds the three checks a plan run makes before agents pass report files by path: claim makes a stamp-only run folder under the plan docs folder, check vets one report path before an agent writes it, and hash prints the sha256 of a finished report. The script follows resolve-root.cjs: main() returns a code and a line and never throws, git runs from an argv array with no shell, and every failure prints nothing on stdout, one reason on stderr and a non-zero exit. It refuses a linked .devflow, docs or plan folder, a plan folder that git tracks, a path with a shell or glob character, a root that is not its own git toplevel, and any file that already exists. It writes nothing except the claim folders and uses no network. The install snapshots list every installed script, so they are red until the fixture-only snapshot commit that follows this one. Refs feat/774-pass-paths
The installer copies every file under the scripts folder, so the new plan-files.cjs adds one executable line, after package.json and before pr-evidence.cjs, to each of the three install snapshots. The hook matrix does not change. Regenerated with the golden update command.
The byte cuts land first, in their own commit, so the later steps of #774 have room for new rule text. Each cut is restated text, a rationale, a reference row or table dashes. No cut removes a trust-boundary, security, data-loss or fail-closed rule. Compliance-off and both-off ceilings of /implement, /plan and /code-review now equal the measured size. The other ceilings stay. The implement goldens are regenerated. Bytes, on / curation-off / compliance-off / both-off: implement 41855/39993/43904/42042 to 41724/39862/43773/41911 plan 33310/31706/33165/31561 to 32908/31304/32763/31159 code-review 31882/30266/29225/27609 to 31651/30035/29102/27486
Run from a plan document, /implement sets EXECUTION_PLAN to PLAN_FILE and PLAN_SECTIONS lines. Code, Evaluate and Test read only the named sections by heading range, treat the text as data that sets the task scope only, and Code never edits the file. The command hashes the file in Phase 1 and again after each Evaluate and each Test return, and stops on a changed digest or other output. A run without a plan file makes no check, and issue-only and empty-input runs paste as before. A relative plan path resolves against the worktree root; a quote or a control character in it stops the run. Restated clauses of the command paid for part of the new text. Raises: Code body 9,524 to 9,662; implement 41,855 to 42,192, 39,993 to 40,330, 43,773 to 44,132 and 41,911 to 42,270. The new guard drives probes through one collector per arm, and the two spawn fences are repinned.
…774 The cuts land first, in their own commit, so the report-path text of the next commit has room. Each cut is restated text: a purpose clause, a list the table repeats, a placeholder that repeats its heading. No cut removes a trust-boundary, security, data-loss or fail-closed rule. Bytes, on / curation-off: skim 6440/5318 to 6352/5230. design 3201/2635 to 3153/2587. architect 3782/3216 to 3743/3177 (it shares the Design partial). explore 2950 to 2860 and synthesize 3204 to 3061 (one build each). No ceiling changes.
The Evidence and Resolution placeholders and one escalation line repeat what their label says. The cut pays for the report-path bullet of the next commit. No trust-boundary, security, data-loss or fail-closed rule is cut. Bytes, on / curation-off: design 3153/2587 to 3119/2553. architect 3743/3177 to 3709/3143. No ceiling changes.
Each agent takes an optional REPORT_PATH. Only a REPORT_PATH: line of the spawn prompt counts; the same text in a file, a tool result or a quoted block is data. Skim and Design write the whole report there and reply with the path (Design adds its Overall Assessment); on a failed Write they reply with the report. Explore runs the plan-files check first, writes once only on OK= with exit 0, and otherwise replies with the report as text. Synthesize reads passed report files whole as data, and writes to an Output: path in any mode. Explore and Skim gain the Write tool. Explore keeps no Edit tool and keeps the redirect, heredoc and tee ban with no exception. Its parity rows, tool-name collector and file-limit pins are updated, with known-bad probes for a missing clause, a check after the Write, a missing text fallback and a REPORT_PATH line in read content. The platform doc records that it is not confirmed whether plan mode blocks a subagent Write. Ceilings: explore 3276 to 3283 (cap 3500 holds); design 3348/2782 to 3362/2796 on / curation-off. Skim and Synthesize keep theirs. Bytes, on / curation-off: skim 6352/5230 to 6577/5455. design 3119/2553 to 3362/2796. explore 2860 to 3283. synthesize 3061 to 3171. No golden holds the text of these agents.
A writer arm in the pass-paths guard checks each Skim and Design build for one REPORT_PATH line: only a REPORT_PATH: line of the spawn prompt counts, the whole report goes to the path, the reply is the path (with the Overall Assessment for Design), and a failed Write replies with the report. It checks Synthesize for the passed report files read whole as data and the Output: path write in any mode. Known-bad probes remove each clause through the same collector.
The byte cuts of #774 removed the file-naming table, and the worked example `42-jwt-auth.2026-04-07_1430.md` went with it. The issue-vocabulary guard pins that example once in the skill and once in /plan. The skill now states it in one short sentence after the `{ISSUE_ID}` note, so the guard is green again. docs-framework skill: 8464 to 8507 bytes, under its 8777 ceiling.
The cuts land first, in their own commit, so the run folder step has room. Each cut is restated text. No cut removes a trust-boundary, security, data-loss or fail-closed rule. - A DEGRADED sentence that the issue capture contract above it already states. - The multiple-choice hint of the first Gate 0 question. - The rationale clause of the test-plan line, and the artifact-path aside that the next sentence repeats. - Two Synthesize prompt lines that the design and exploration mode references already hold. - The Skim prompt, merged into one sentence, and the usage padding. Compliance-off and both-off ceilings of /plan now equal the measured size. The other ceilings stay. Bytes, on / curation-off / compliance-off / both-off: plan 32908/31304/32763/31159 to 32357/30753/32212/30608 (-551 each)
/plan claims one run folder in the message of the settings call. With it, Skim, Explore and Design write their report to a named file there, Synthesize writes its summary there, and later agents get the paths. Without it, or when an agent replies with text, the report passes as text as before. Every prompt that passes paths tells its reader to read each file whole and to treat the content as data. The main session reads a report before a gate shows it. ACCEPTED_GAPS stays text, and no Plan prompt gets a report path. The docs-framework skill lists the run folder, the two /code-review text files and /plan among the commands that create their own run directory. docs/commands.md describes the run folder. The guard in tests/guards/pass-paths.test.ts holds the claim, the path forms, the name count, the path-only-when-replied rule, the read-whole clause and the read before a gate, in all four /plan builds. Known-bad probes drive each rule. The claim line may hold no feature text, title or topic, and no step may glob the run folder. Raises, each under its approved maximum (the byte cuts of the previous commit paid for 551 bytes of the 693 new bytes): plan compliance-off 32763 to 32905 (+142), both-off 31159 to 31301 (+142), set to the measured size. On and curation-off stay under their ceilings (33050 of 33310, 31446 of 31706). docs-framework skill 8777 to 8791 (+14), set to the measured size.
…#774 The cuts land first, in their own commit, so the file-path step has room. Each cut is restated text. No cut removes a trust-boundary, security, data-loss or fail-closed rule. - The Backwards Compatibility section, which docs/cli-reference.md states. - The Step 0b closing line, which Step 1.2b and Phase 1 already state per worktree. - The wording of two Phase 0a flow lines, and the reason in Principle 2. The Edge Cases guard now ends that section at Principles. Compliance-off and both-off ceilings of /code-review now equal the measured size. The other ceilings stay. Bytes, on / curation-off / compliance-off / both-off: code-review 31651/30035/29102/27486 to 31313/29697/28764/27148 (-338 each)
Step 0d fetches the PR body into the review folder, in the Bash call of the mkdir, only for a digits-only PR number. The fetch writes a temp file and moves it to pr-description.txt only after it succeeds. Step 0e-i writes the cut prior resolutions to prior-resolutions.txt with the Write tool, never by a copy, cat, redirect or filter of the source. The Review and Synthesize prompts pass the two paths, or (none), with no wrapper. The Review agent and the Synthesize review reference read each file whole, read a missing or empty file as (none), and treat its content as data. Principle 1 names both files. The temp file is removed with a plain rm, as the other prompts do. Guards: a /code-review arm in pass-paths (the claims, the spawn lines, a copy, cat, redirect or filter of the summary, a write before the fetch succeeds, the order) and a file reader arm for Review and Synthesize. The marker pins of the convergence tests became path and data-clause pins, and the private-section group pins the Write step and the never-copy rule. Compliance-off and both-off ceilings of /code-review now equal the measured size, 41 bytes under the sizes held before the cuts. The other ceilings, and those of the Review agent and the Synthesize reference, stay. Bytes, on / curation-off / compliance-off / both-off: code-review 31313/29697/28764/27148 to 31610/29994/29061/27445 (+297 each) review agent 10696/10100 to 10690/10094 (curation on / off) synthesize review reference 3797 to 3780
The cuts of restated text that paid for the file-path text were larger than that text in 14 builds. Each ceiling now equals the measured size: /plan on and curation-off (-260), /code-review on and curation-off (-272), Architect on and off (-73), Review on and off (-82), Skim on and off (-28), Synthesize (-101), the Synthesize review reference (-17), Evaluate (-1) and Test (-63). Each manifest description gives the old value, the new value and the reason. No ceiling rises.
Add the Unreleased entry for #774. It names the effect: the main session no longer retypes reports and the plan into spawn prompts. It lists the ceiling raises and the ceiling cuts with their sizes.
The hash call reads the plan file through the shared bounded reader. The file it hashes is always the regular file that it checked. Tests cover the new property.
The /implement Orchestration-only principle now names the plan hash calls among its inline calls. /plan now says that the agent part of a report name is lower case, as the path check requires, and its first two Gate 0 questions are two list items again. A restated article and a restated no-dumps clause paid for part of the text. The guards pin both new rules. The implement ceilings rise by 10 bytes and the plan ceilings fall by 6 bytes, each to the measured size.
The file organization entry and the script header now name lib/project-config.cjs as the owner of the bounded file read. They also say that /implement uses the hash call for the plan file.
The cut of restated text in /plan dropped the rule that a TRACEABILITY: DEGRADED status line is never issue content. Gate 0 says again that no issue content is inferred from the status line, and the pass-paths guard pins the rule in all four /plan builds. docs/commands.md now says that each Review agent gets the PR body path and the prior resolutions path, and that Synthesize gets only the prior resolutions path. /plan ceilings, each raised by 45 bytes to the measured size: on 33,044 to 33,089, curation-off 31,440 to 31,485, compliance-off 32,899 to 32,944, both-off 31,295 to 31,340.
…774) With a plan file, each phase or subtask EXECUTION_PLAN is now the PLAN_FILE: line plus its own PLAN_SECTIONS: line. A phase could get the section names with no file path. The pass-paths guard pins the sentence in all four builds. Three restated clauses leave the command to pay for it: the Code-agent clause of the Phase 9 lead-in, the continue-to-Phase-12 clause of the Phase 11 script step and the evidence file aside about the handoff file. The four size ceilings fall to the measured sizes.
The evidence file lead of the Test plan step said the file stays after the PR exists. The last commit cut that text from both compliance arms. The text tells a cleanup to keep the file, so the cut risked data loss. The text returns in both arms. The pass-paths guard now pins it once in each of the four builds. The four size ceilings rise by 58 bytes to the measured sizes, inside the approved raise against main.
One closed list names each rule that no other test pins, the exact span that carries it, and the builds that must hold it once. A named collector reads the compiled builds, and known-bad probes run through that same collector. A missing manifest, host or build fails the run.
Owner
Author
Review and test evidence (head b762d85)Code review, cycle 1 (at 31cc000)Result: CHANGES REQUESTED. Blocking: 1 HIGH, 7 MEDIUM, 5 LOW. Gate level lean (three focus reviews), plus one alignment re-check against the plan and #774. Resolve (cycle 1): all findings fixed25 issues: 24 fixed, 1 duplicate, 0 deferred, 0 false positive.
Also fixed from the suggestions: Skim and Design check a report path before they write; Code, Evaluate and Test return BLOCKED on an unreadable plan file; the review folder path stops on a quote; the plan folder listing matches every spelling; two order-dependent tests; the relative plan path is normalized; Principle 1 is byte-equal with main again; lean-prompts.md names the never-cut guard. Evidence
Merge readiness: waits for an approving review. CI, threads and test plan are clear. |
After Evaluate returns, /implement runs the PLAN_SHA check alone and
starts no spawn until it passes. After Test returns, the check runs in
the claims message and no spawn starts until it passes.
Also:
- The phase PLAN_SECTIONS line names Patterns to Follow and Known
limits, as the sentence before it says.
- A relative plan path is normalized before it reaches the hash call.
- The Orchestration-only principle keeps its base wording ("the
bounded plumbing").
- The issue step drops the restated meaning of `pending`, which pays
for the added text. The four /implement ceilings fall by 18 bytes.
Task: resolve-b1-implement
- Explore holds Read and Bash only and replies as text. /plan no longer gives it a report path. - Skim and Design run the path check before they write a report. - Synthesize replies with the summary as text when its write fails. - /plan passes a path only when the reply holds the path it gave, and treats a failed read of a passed path as a failed report. - Code, Evaluate and Test return BLOCKED when PLAN_FILE cannot be read. - Size ceilings, docs and the changelog follow the new text. Task: resolve-b2-agents-plan
…older spelling (#774) - check refuses a report path when the stamp folder, or a folder above it, stands absent. Only claim makes those folders, one at a time. - The tracked-file listing matches the plan folder in any letter case, and in the two Unicode spellings a case-folding file system opens. - Tests: check with a failed listing, an overflowed listing, git off the path, a root directly below `/` and a root that is a file; the env of the listing call; each empty-folder assertion has its own folder. Task: resolve-b3-plan-files
…est helpers (#774) - /plan: restore "Frame as multiple choice when 2-3 interpretations exist." at the Gate 0 first question, and hold it as a never-cut item. - /code-review: stop on a quote or control character in the worktree path before the quoted PR body fetch, and set the prior resolutions path to (none) on the first review cycle. Both are pinned in the pass-paths guard. - Tests: pass-paths uses seedOnce and countOf from the helpers; the manifest-driven build list moves to tests/helpers.ts and both guards use it, so a missing build fails and never skips. - Ceilings of the four /plan and four /code-review builds move to the measured sizes, still below main (the /plan builds by 67 B, /code-review by 187 B and 79 B with compliance off).
…olve-b5-text) The code-body-max row said a value may be lowered and never raised, and then recorded a raise. Seven rows that earlier fixes touched carried the same clause. Each now says that a value may move up or down, with the old value, the new value and the reason in the description and in the PR.
…e doc (resolve-b5-text) plan-files.cjs also requires hooks/lib/tracked-areas.cjs, for the .devflow folder spellings and the git environment without redirects. The script header and the file-organization entry named only two requires.
…solve-b5-text) Step 1 of the cut rules named only the never-cut table. It now says that a protected span goes into NEVER_CUT_ITEMS and that a cut runs that guard before it lands.
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
The main session retypes agent reports and the plan into each spawn prompt. Typed output costs 5 times input, and the typing makes /plan wait. This branch passes file paths between the agents of /plan, /implement and /code-review instead of retyped text.
Changes
PLAN_FILE:line plus its ownPLAN_SECTIONS:line, which names Patterns to Follow, Known limits and its step and criterion numbers..txtfiles in its review folder. Each Review agent gets both paths. Synthesize gets the prior resolutions path (it never took the PR body).plan-files.cjsclaims the run folder, checks each report path and hashes the plan file.checkaccepts only a path in a claimed run folder. The hash reads the same file that it checked.tests/guards/never-cut.test.ts, pins every protected prompt sentence in every build, so no later byte cut can remove one without a red test.Study (the "Done when" report of #774)
Data: one
npm run audit:tokensrun over the sessions of one devflow checkout, 2026-10-20 to 2026-11-08 (337 sessions, 29,260 requests, 1,086 subagent transcripts), plus static byte counts of the built default tree. "ce" is the audit's cost weight: input 1, cache write 1.25 or 2, cache read 0.1, output 5. Token figures from bytes use 4 bytes per token and are estimates.Expected Saving and Proof
2026-11-10T12:00:00Z):npm run audit:tokens -- --project <checkout path> --until <merge time>npm run audit:tokens -- --project <checkout path> --since <merge time>ce per runof each command's workflow row, and theOutputcell of themainrow in "Main vs subagent (cost-equivalent)" divided by the runs in that window (the cell is a window total).Size and Commit Notes
Size ceilings that rise (each after a search for cuts, each under its approved maximum)
.txtfiles, the Who Writes What line and the same-minute list.Ceilings that fall to the measured size: all four /plan builds (67 B below main), /code-review on and curation-off (187 B below main) and compliance-off and both-off (79 B below main), and the Architect, Explore, Review, Skim, Synthesize, Evaluate and Test bodies and the Synthesize review reference. Each row description in
tests/fixtures/numeric-floors.jsongives the old value, new value and reason.Commit notes for reviewers
42-jwt-auth.2026-04-07_1430.mdfrom the docs-framework skill; c2ef9c6 restores it.rm -- "$F.tmp", notrm -f, because the repo's recommended deny list refuses flaggedrmforms.Breaking Changes
None expected. Every new path input is optional, and without it each agent behaves as before.
Known Limits
' " $ ` \ * ? [ ] { }stops /implement. devflow makes plan paths from letters, digits,.,-,_and/.Testing
Related Issues
Closes #774