Epic: schema/technique/disclosure review repeat-pass backlog (2026-07-08)

[m2ux]

Overview

Epic tracking the backlog from the 2026-07-08 repeat pass of the schema/technique/disclosure review, run after everything in #166 shipped. Full analysis, measurements, and evidence live in the planning artifacts (see References) — this issue is just the work list.

The #166 fixes work, but almost nobody gets them. Reference delivery cuts a full walk by 27–36 % when switched on — and nothing switches it on: it's opt-in, the default worker topology can't use it, and the bootstrap guide never suggests it. Hybrid bundling shipped with zero workflows using it. The biggest remaining waste is repeated contract/rules content inside technique payloads (~25 % of technique delivery), which the current dedup can't see. On the comprehension side the new annotations clearly help; what's left is a handful of small spec gaps. And the four content defects found by the original review were never fixed — no backlog item owned them.

Backlog

Cluster groups items that ship together (1–4; numbers follow implementation order, cluster 4 runs in parallel). Server / Workflows mark which repo each item touches. All items are additive except C8 and C13. R-references resolve in the report's friction register (§1).

#	Cluster	Server	Workflows	Change	Removes	Effort	Risk
C1	1	✅	✅	Make the delivery optimisations reachable: bootstrap/IDE guidance for context_mode: "persistent", adopt bundleTechniques on a few high-traffic activities, per-call reference opt-in on get_technique	R1, R3	S	Low
C2	3	✅		Dedupe the repeated contract/rules blocks inside technique payloads (block-level delivery ledger)	R2	M	Low
C3	4	✅	✅	Fix the five known content defects; add a lint for checkpoint messages that reference variables nothing sets	R4	S	None
C4	2	✅		Specify how a step reports multiple outputs in its manifest (today agents have to guess)	R5	S	None
C5	2	✅		Annotate every input with its provenance — no more silent gaps	R6	S	None
C6	1	✅	✅	Fix docs that drifted during #166 (api-reference vs seeded variables, stale schema README rows, worker prompt)	R9, R14	S	None
C7	2	✅		Say in the payload itself which fields the server does not execute (agents still misread them there)	R7	S/M	Low
C8	6	✅	✅	Decide and execute the when vs condition merge (17 uses to migrate)	R8	M	Medium
C9	4	✅	✅	Burn down the baselined binding debt (124 dead outputs, 97 orphan inputs)	R10	M	Low
C10	4	✅	✅	Fragments phase 2: convert the last inline ORCHESTRATION MODEL copies, allow refs in activity rules, dedupe fragment bodies	R11	M	Low
C11	5	✅		Close the fidelity-observability gaps left by B8 (resource validation, step events, per-agent filtering)	R13	M	None
C12	3	✅		Slim get_workflow on resume (only if resume traffic shows it matters)	R12	S	Low
C13	7	✅	✅	Execute the B12 retire sweep at the next schema major	R16	S	None now

Implementation clusters & order

Items are grouped by what code they touch, so each cluster is one PR built and reviewed once:

• Cluster 1 — guidance & docs (first): C1 + C6. One pass over the guidance surface, including a single update to the worker prompt. C1's corpus opt-ins land via cluster 4; its server opt-in and C6's marker unification ride cluster 3.
• Cluster 2 — payload rendering (second): C4 + C5 + C7. All change what rides the composed payload; one probe re-run validates all three.
• Cluster 3 — delivery ledger (third): C2 + C12, plus the carried bits from cluster 1. All in the same module chain; one design pass, one test re-baseline.
• Cluster 4 — corpus content (parallel throughout): C3 + C9 + C10 + C1's opt-ins. Workflows-repo only; separate PRs, no serialization needed.
• Solo: C11 (5), C8 (6 — the only migration-risk item, keep isolated), C13 (last).

Roughly six server PRs plus the parallel corpus stream. Full rationale in the report's §3.

Tracking

Cluster 1 — guidance & docs — ✅ shipped 2026-07-10 (PRs #207, #208 breaking v2.0.0, #209 submodule bump — all merged; see progress comment below)

• C1 — adoption guidance (bootstrap/IDE context_mode, canonical agent_id, worker prompt) — plus automatic per-agent context-derived bundling (context_tokens REQUIRED on get_activity; server opt-in pulled forward from cluster 3), replacing the planned per-activity bundleTechniques opt-ins
• C6 — post-Epic: schema/technique/disclosure review backlog (2026-07-03) #166 doc-drift fixes — incl. marker-dialect unification (pulled forward from cluster 3)

Cluster 2 — payload rendering (one PR) — ✅ shipped 2026-07-10 (PR #210, additive v2.1.0 — merged; server-only, no corpus change so no submodule bump)

• C4 — multi-output manifest encoding specified (JSON object keyed by output id; stated on the two distinct-reader surfaces — technique provenance_note + step_manifest field — plus technique-protocol spec §7.5; destination: made conditional)
• C5 — full provenance coverage (noteworthy-only policy stated on the inherited_inputs scope note so an absent source: reads as ordinary scope; per-item filtering retained)
• C7 — payload-borne enforcement hints (conditional enforcement_notes block on get_activity: actions and auto_advance notes, present only when the activity contains those constructs)

Cluster 3 — delivery ledger (one PR)

• C2 — block-level ledger for contract/rules blocks
• C12 — get_workflow slimming (conditional)
• (carried) C1's get_technique opt-in + C6's marker unification — done in cluster 1 (feat(server)!: context-derived eager technique bundling + unified unchanged-marker (BREAKING, v2.0.0) [#189 cluster 1] #208): markers unified, get_technique { full: true } reference opt-in docs-surfaced

Cluster 4 — corpus content (parallel)

• C3 — content-defect sweep + checkpoint-message lint
• C9 — binding-debt burndown
• C10 — fragments phase 2 (C1's bundleTechniques opt-ins — dropped; automatic context-derived bundling in cluster 1 replaces per-activity opt-ins)

Solo

• C11 — fidelity follow-through (5)
• C8 — when/condition merge + migration (6)
• C13 — B12 retire sweep at next schema major (7)

References

Planning artifacts in artifacts/planning/2026-07-08-schema-technique-disclosure-review-repeat/ on the engineering branch (committed in 5e34fcd):

• evaluation-report.md — friction register (R1–R16), disclosure-policy verdict, and the C1–C13 backlog with full rationale
• fix-verification-ledger.md — what each Epic: schema/technique/disclosure review backlog (2026-07-03) #166 item actually fixed, and what's left
• payload-measurements.md — live walk measurements, default vs reference delivery
• probe-transcripts.md — fresh-agent comprehension probes on the new payload shapes

[m2ux]

Cluster 1 (guidance & docs) — shipped ✅ 2026-07-10

Merged to main: #207 (workflows meta-resources → workflows), #208 (server, breaking v2.0.0 → main), #209 (submodule-pointer bump → main). Delivered via a workflow-design run; planning artifacts under .engineering/artifacts/planning/2026-07-10-workflow-design-cluster1-guidance-docs/.

What shipped

C1 — adoption guidance + automatic context-derived bundling. Rather than hard-coding bundleTechniques onto a handful of activities (which left the zero-adoption root cause in place), bundling is now automatic and sized to the consuming agent:

• context_tokens is a REQUIRED parameter on get_activity (omission = validation error). It is per-agent, declared on the worker's own entry call — not on get_workflow (which does no technique bundling), and not session-level. No fallback/default: the server never guesses a window.
• The server derives a cumulative eager-bundle budget = context_tokens × 0.80 (availability headroom) × 4 (chars/token), both env-overridable config constants. It inlines ungated step techniques in document order, stopping at the first that would overflow; the rest stay lazy via get_technique.
• Per-activity bundleTechniques.maxChars is retained as an explicit per-technique override (0 = opt out; schema relaxed to .nonnegative()).
• Preserving the semantics of the intentional get_technique call: inlined techniques render as discrete ▼ STEP <id> arrival blocks, and the worker prompt prescribes an emitted ▶ step <id> begin-beat per inlined step (in document order) — which also serves as the observability substitute for the per-step fetch event (no server ping).
• Resources stay lazy — techniques inline, but get_resource is still called on demand; the budget measures technique bodies only. Shared-resource inlining is deferred to C2 (block-level dedup ledger).
• IDE/bootstrap guidance added for context_mode: "persistent" + canonical agent_id (solo topology); get_technique { full: true } reference opt-in docs-surfaced.

C6 — post-#166 doc-drift + marker unification. docs/api-reference.md Enforcement Boundary reclassification (variable types/defaults are server-seeded/warn-only per B7, not agent-interpreted); two stale activity artifacts rows removed from schemas/README.md; worker-prompt bundle-shape wording reconciled. The two unchanged-marker dialects are now unified to { delivery: "unchanged", content_hash } across both the bundle path and get_technique (shared technique:<id> ledger key preserved).

Scope changes vs. the original plan

• Server bundling + marker unification pulled forward from cluster 3 into cluster 1. With C1's adoption work necessarily touching the delivery path, unifying the marker and landing the derivation server-side here was the coherent scope.
• The cluster-4 bundleTechniques corpus opt-ins are dropped — automatic context-derived bundling makes per-activity opt-ins unnecessary (the schema field survives only as an override).

Verification

typecheck clean; full suite 540 passing / 0 failing (incl. a new tests/context-window-smoke.test.ts graduated context-window sweep proving the delivery-shape/budget relationship); 7 repo guards green; post-update review 0 findings.

Follow-ups

• Empirically tune bundleHeadroomFraction (0.80) / bundleCharsPerToken (4) once live-walk data accumulates.
• C2 shared-resource inlining / block-level dedup ledger (now the home for resource inlining).