context weight: defer branch-local blocks behind Reads (~22,300 B) #102

New issue

Closed

opened 2026-08-10 14:49:02 +00:00 by john · 1 comment

john commented

2026-08-10 14:49:02 +00:00

Owner

~22,300 B off the eager path by moving branch-local blocks behind a Read at the step that needs them. Blocked on #1 — every one of these anchors in a coverage hole of check 13's register, so landing them first means shipping deferrals CI cannot guard.

Each move is tested against references/seams.md:216-253: only some branches reach it, one consult site, and the read folds into a turn already being taken.

bytes	move	notes
8,052	`config.md:71-133` -> `references/config-catalog.md`	Knob catalog + Type-key legend (the legend travels; it is unreadable apart from the table). Read at the Interactive-menu walk step 2. `--review` and direct-set — two of three routes — never touch it. Takes `/cad-config` eager 20,547 -> ~11,700 (-43%). Keep behind: "Never hand-validate against this table; call the seam" — it binds all three routes. The `:61-70` derivation defense moves to the head of the new reference.
4,050	`plan.md:267-336` -> `references/plan-revision.md`	The BLOCKER revision branch, reached only when the checker returns a BLOCKER. Costs a `BRACKETING` edit in `trace.test.mjs` (plan.md 4 -> 2 dispatch moments, with 2 return and 2 checkpoint closes moving too). Guardrail 410 keeps the one-revision cap eager.
3,430	`execute.md:343-402` -> `references/execute-parallel.md`	The `execute_parallel` body. `choose_path` (`:120-171`) stays eager — it decides the branch. Two of the four per-arm triage-gate Read sentences travel along; do not consolidate the rest.
2,594	`cad-executor-contract:151-193` -> `references/worktree-executor.md`	`<worktree_mode>`. Dead on a default install (`worktree.baseRef` defaults `fresh` -> `parallelSafe:false`, `execute.md:139-150`), yet paid by every executor dispatch. The pointer must be an unconditional gate before task 1, and `execute.md:356`'s mode line should name the reference. Rules are safety-critical (never stash/merge/rebase, branch check before every commit) — this one needs the register most.
2,200	`plan.md:100-121`, `:173-178` and `context.md:74-104` -> `references/recall.md`	Recall gate, JSON shape, `<recalled_memory>` render rule, D-01/D-03 rationale — near-verbatim in both, and `workflows/debug.md` is a third consumer. Each side keeps ~200-250 B of site wiring including `plan.md`'s check-10-linted batching sentence.
1,050	`context.md:324-363` -> `templates/CONTEXT.md`	The CONTEXT.md output template, following how `plan.md` points cad-planner at `templates/PLAN.md`. Keep the one-line section list (`:365-366`) eager as the parse backstop for /cad-audit and /cad-verify.
950	`execute.md:316-335`	Worktree reconciliation remedy; travels with `execute_parallel`. Arguably a second consult site — if that reading wins, take only the ~450 B of pure rationale and leave the remedy.

Constraints

Every new reference needs a weight-budgets.json row (check 4 requires a row per measured surface) and must exist before its Read sentence lands (check 3).
seams.md:240-243: each new Read sentence states the reference's measured bytes and consult-site count inline.
Check 1's reverse arm: moving the config catalog is safe because references/ is walked, but deleting rows would orphan risk.override.<surface> and the three review.triggers.<t>.* keys, which are named only in that table.
Check 10 applies in references/ too, so concurrency sentences survive a move unchanged.
config-reach.md:136-138 names workflows/execute.md as the reach site for the three parallelization.* keys — deferring execute_parallel moves it.

Rejected, recorded so they are not re-derived

Cross-contract dedup. ~450 B is stated twice across cad-reviewer-contract and cad-plan-checker-contract, but a dispatch preloads exactly one — they never share a context. Factoring them out adds a Read round-trip per dispatch to save ~200 B each: a net loss under seams.md's own test.
Deriving config.md's catalog from the schema. config.mjs keys dumps 24,544 B, larger than the whole 19,256 B document, and carries no per-value explanation, which the walk requires as each option's description. The fix is residency, not derivation.
Extracting cad-land / cad-health to workflow files. Saves zero eager bytes: @-included loads on turn one, and the process is consulted at every step so it cannot defer (seams.md:235-237). Hygiene argument only.
git-guard.md's 6,721 B eager include in cad-land. Correct as-is — consulted at steps 1, 2 and 3, the exact case seams.md:236-240 names.
Moving contract material into agent rung files. Banned by check 7, and would multiply by four rungs. The rung files (407-519 B) are at floor.

Multiplier caveat

execute.md:192-195 asserts the contract is the "stable, cached definition", so repeat dispatches within a session read those bytes from prefix cache, not as fresh input. Honest fresh-input multiplier is ~1.3x, not the raw ~4x; the raw figure is the upper bound (cold cache, worktree batches where prefixes diverge, dispatches past TTL). Do not size this work off the 4x number.

~22,300 B off the eager path by moving branch-local blocks behind a `Read` at the step that needs them. **Blocked on #1** — every one of these anchors in a coverage hole of check 13's register, so landing them first means shipping deferrals CI cannot guard. Each move is tested against `references/seams.md:216-253`: only some branches reach it, one consult site, and the read folds into a turn already being taken. | bytes | move | notes | |---|---|---| | 8,052 | `config.md:71-133` -> `references/config-catalog.md` | Knob catalog + Type-key legend (the legend travels; it is unreadable apart from the table). Read at the Interactive-menu walk step 2. `--review` and direct-set — two of three routes — never touch it. Takes `/cad-config` eager 20,547 -> ~11,700 (-43%). **Keep behind:** "Never hand-validate against this table; call the seam" — it binds all three routes. The `:61-70` derivation defense moves to the head of the new reference. | | 4,050 | `plan.md:267-336` -> `references/plan-revision.md` | The BLOCKER revision branch, reached only when the checker returns a BLOCKER. Costs a `BRACKETING` edit in `trace.test.mjs` (plan.md 4 -> 2 dispatch moments, with 2 return and 2 checkpoint closes moving too). Guardrail 410 keeps the one-revision cap eager. | | 3,430 | `execute.md:343-402` -> `references/execute-parallel.md` | The `execute_parallel` body. `choose_path` (`:120-171`) stays eager — it decides the branch. Two of the four per-arm triage-gate Read sentences travel along; do not consolidate the rest. | | 2,594 | `cad-executor-contract:151-193` -> `references/worktree-executor.md` | `<worktree_mode>`. Dead on a default install (`worktree.baseRef` defaults `fresh` -> `parallelSafe:false`, `execute.md:139-150`), yet paid by every executor dispatch. The pointer must be an unconditional gate before task 1, and `execute.md:356`'s mode line should name the reference. Rules are safety-critical (never stash/merge/rebase, branch check before every commit) — this one needs the register most. | | 2,200 | `plan.md:100-121`, `:173-178` and `context.md:74-104` -> `references/recall.md` | Recall gate, JSON shape, `<recalled_memory>` render rule, D-01/D-03 rationale — near-verbatim in both, and `workflows/debug.md` is a third consumer. Each side keeps ~200-250 B of site wiring including `plan.md`'s check-10-linted batching sentence. | | 1,050 | `context.md:324-363` -> `templates/CONTEXT.md` | The CONTEXT.md output template, following how `plan.md` points cad-planner at `templates/PLAN.md`. Keep the one-line section list (`:365-366`) eager as the parse backstop for /cad-audit and /cad-verify. | | 950 | `execute.md:316-335` | Worktree reconciliation remedy; travels with `execute_parallel`. Arguably a second consult site — if that reading wins, take only the ~450 B of pure rationale and leave the remedy. | ## Constraints - Every new reference needs a `weight-budgets.json` row (check 4 requires a row per measured surface) and must exist before its Read sentence lands (check 3). - `seams.md:240-243`: each new Read sentence states the reference's measured bytes and consult-site count inline. - Check 1's reverse arm: *moving* the config catalog is safe because `references/` is walked, but deleting rows would orphan `risk.override.<surface>` and the three `review.triggers.<t>.*` keys, which are named only in that table. - Check 10 applies in `references/` too, so concurrency sentences survive a move unchanged. - `config-reach.md:136-138` names `workflows/execute.md` as the reach site for the three `parallelization.*` keys — deferring `execute_parallel` moves it. ## Rejected, recorded so they are not re-derived - **Cross-contract dedup.** ~450 B is stated twice across `cad-reviewer-contract` and `cad-plan-checker-contract`, but a dispatch preloads exactly one — they never share a context. Factoring them out adds a Read round-trip per dispatch to save ~200 B each: a net loss under seams.md's own test. - **Deriving `config.md`'s catalog from the schema.** `config.mjs keys` dumps 24,544 B, larger than the whole 19,256 B document, and carries no per-value explanation, which the walk requires as each option's `description`. The fix is residency, not derivation. - **Extracting `cad-land` / `cad-health` to workflow files.** Saves zero eager bytes: `@`-included loads on turn one, and the process is consulted at every step so it cannot defer (`seams.md:235-237`). Hygiene argument only. - **`git-guard.md`'s 6,721 B eager include in cad-land.** Correct as-is — consulted at steps 1, 2 and 3, the exact case `seams.md:236-240` names. - **Moving contract material into agent rung files.** Banned by check 7, and would multiply by four rungs. The rung files (407-519 B) are at floor. ## Multiplier caveat `execute.md:192-195` asserts the contract is the "stable, cached definition", so repeat dispatches within a session read those bytes from prefix cache, not as fresh input. Honest fresh-input multiplier is ~1.3x, not the raw ~4x; the raw figure is the upper bound (cold cache, worktree batches where prefixes diverge, dispatches past TTL). Do not size this work off the 4x number.

john added this to the v2.6.2 milestone

2026-08-10 14:49:02 +00:00

john commented

2026-08-12 15:10:48 +00:00

Author

Owner

Shipped: all four moves landed - config-catalog.md, plan-revision.md, execute-parallel.md, worktree-executor.md all exist as references with their consult-site Reads, and config.md sits at 11,470 B against the predicted ~11,700.

john closed this issue

2026-08-12 15:10:49 +00:00