[mchwang]

Closes #6.

Summary

#6 was an umbrella issue. PR #4 delivered its library part, and later lanes delivered most of the runner part. This PR closes the remaining library and test gaps and moves the remaining runtime gaps to their own issues. docs/implementation/plan-library-alignment.md maps every obligation in #6 to its code and tests, or to the issue it moved to.

Schema loading (core/plan.ts, core/planning-author.ts)

• loadPlanSchemas compiles every version in schema/versions.json from its retained snapshots into one validator. Each plan or edit reply is checked by the version it declares; a value with no registered version is checked by the current schema, so v1 callers see the same /schema_version error as before.
• The loader refuses at module load: an invalid version key; a path with no snapshot, or one already named in the registry; a snapshot whose $id differs from its path, that does not require schema_version with a one-value enum, or whose plan/edit role differs; a validator key or implementation reused, or paired with another semantics document; a missing current version.
• A validator key with no implementation loads, and that version is refused as unsupported by validate, assertPlan and assertEditReply (docs/plan-format.md: "Treat a missing validator implementation as unsupported"). Before, any v1 registry change other than the exact v1 entry failed module load; test/registry.test.ts still pins the key to v<version>.
• importPlan requires the current version (no migrations exist). applySuggestion requires the reply's version to equal the plan's. Drafts get the current plan schema; suggestions get the previous plan's edit schema.
• Behaviour for v1 callers is unchanged: same codes, messages and check order.

Released files pinned

• test/schema-versions.test.ts pins the SHA-256 of every file a registry entry names. .gitattributes keeps schema/versions/** and the CLI copies LF on checkout.

New tests for the remaining #6 gaps

• Path identity and base entries (test/review.test.ts): the refusal without a known identity, case and NFC keys, the non-ASCII refusal on case-insensitive checkouts, and Git mode mapping (symlink targets verbatim, gitlinks, executable and odd-named files).
• Hostile text (test/planning-author.test.ts): repository, issue, lesson, feedback, previous-plan and continuation-context text, in initial drafts, revised drafts and suggestions.
• Output limits: the decoded supervisor output at the exact stdout and combined limits, in real Docker (test/agent-supervisor.test.ts); the 1 MiB parser limit on a decoded Claude answer in draft validation and the envelope fixtures (test/agent-adapter.test.ts); the 300-unit quote of a failed planning run (test/planning-provider.test.ts).

Not testable while v1 is the only version

Listed in the implementation note: module-level selection in assertPlan/assertEditReply, the current-version import check, the reply/plan version check, which schema each provider gets, and the unsupported refusal on shape-only paths. The loader behaviour behind them is tested through an injected two-version loader.

Follow-up issues

• Probe checkout path identity at runner startup #162 Probe checkout path identity at runner startup
• Enforce a pre-spawn model budget for planning invocations #163 Enforce a pre-spawn model budget for planning invocations
• Probe the planning profile at runner startup #164 Probe the planning profile at runner startup
• Bound the Docker daemon log of agent containers #165 Bound the Docker daemon log of agent containers
• Parse Claude planning answers under the v1 parsing contract #166 Parse Claude planning answers under the v1 parsing contract. Found here: parseClaudeOutput re-serializes structured_output, so duplicate keys and lossy numbers are normalized before parseV1 sees them.

Validation

Base main 7fd4dfe52d02de62a516e4d880b4564e83c78513 (merged in at 94b8611, 2026-10-19), head 6b42931284a016e145d27b1d9d7547e5fc1beed2 (current head).

Gate	Result
Typecheck (npm run typecheck)	Pass
Full suite without Docker (vitest --project parallel)	2360/2360 (81 files) at 94b8611; 6b42931 changes one doc line
New real-Docker test (agent-supervisor, "decoded output at the … limit")	2/2 run alone at f9c2e6b; CI real-docker runs it on this head
CI test, real-docker (both required on main since 2026-10-19)	pass on 6b42931 (19m49s, 19m57s; real-docker ran the new Docker test)

Since F6c (#177), test/agent-adapter.test.ts runs in the test job; this PR's new cases there only parse envelopes and read repository files, so they still need neither Docker nor a vendor CLI.

Earlier validated head f9c2e6b on base 22e76a8: typecheck pass; 2025/2025 without Docker.

Load-related failures, separate from product results: at load average ~140 (other agents on the machine), three full runs each had one timing failure in files this PR does not touch: pre-merge.test.ts "aborts remote work early enough…", review.test.ts "keeps review load available…", planning-worker.test.ts "never deletes Ask's folders…". Each passed 3/3 alone and in later full runs.

Each new test was checked against a deliberate break of its behaviour; the breaks are listed in the implementation note.

Review record

Round	Type and reviewer	Pair	Findings	Changed / declined
1	Independent agent	22e76a8 / uncommitted	8: latent version gaps (imports, reply vs plan version, shared validator keys, double selection), weak tests, CRLF digests	All fixed
2	Independent agent	same	Snapshot not pinned to its version; doc/test-name accuracy; CLI-copy rule	All fixed
3–5	Independent agent	same	required check; evidence overstated; unsupported version passing shape-only paths documented as untested; error-code consistency	All fixed
6–12	Independent agent	same	Doc precision; reused implementations; safe-integer key test; shared semantics paths; missing table rows	All fixed
13–17	Independent agent	same	assertPlan/assertEditReply now refuse unsupported versions; table rows for mounts, termination, schema/output channels, prompt bytes	All fixed
18–31	Independent agent	same	Comment and title wording; 300-unit quote test added; continuation-context hostile test; role check (plan/edit) and its edit half; message names the version	All fixed. Declined: the typeof guard in select (needed for TypeScript narrowing); a mutable Map behind a shallow freeze (production loader not exported); pinning examples/ (not conformance fixtures; no test reads them)
32	Independent agent	22e76a8 / tree committed as f9c2e6b	None	Clean pass
merge main	—	7fd4dfe / 94b8611	Merged main (async review loads #170, merge jobs F6a/F6b, F6c CI) with no conflicts	—
33	Independent agent	7fd4dfe / 94b8611	No code findings (semantic merge check; 223/223 in 9 files; mutation checks on the loader, digests, parser limit and edit schema). Docs: the alignment note's baseline and this body were stale	Note fixed in 6b42931; body updated here
34	Independent agent	7fd4dfe / 6b42931	Clean (265/265 in 10 files; nine mutation checks each failed a test)	—
Copilot 1	copilot-pull-request-reviewer	7fd4dfe / 6b42931	Requested after round 34 was clean and CI passed. No open issues; approval recommended	—

Self-review ran between rounds; every independent round reviewed the full diff against the base.

Review-lesson audit

Findings were classified against existing rules:

• Claims in docs and test titles stronger than the tests: covered by CLAUDE.md "Treat every behavioural claim … as something to verify".
• Behaviour unreachable while v1 is the only version: recorded as explicitly untested in the implementation note (one-off for this PR; the next version's PR must add the tests).
• Latent second-version defects (version pinning, role swap, shared validators): one-off design hardening for the loader introduced here.
  No new AGENTS.md rule is needed.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

No blocking issues remain; the changes preserve v1 behavior, add focused regressions, and explicitly document future-version limitations.

No open issues 🎉

What changed in this PR

Completes the remaining library work for #6 by loading plan schemas through the version registry, expanding regression coverage, and documenting separate runtime follow-ups.

Changes:

• Adds registry-selected schema validation and version compatibility guards.
• Pins released schema files and tests path identity, hostile prompts, and output boundaries.
• Maps #6 obligations to implementation evidence or follow-up issues.

File	Description
test/​schema-versions.test.ts	Tests registry loading, version dispatch, and released-file digests.
test/​review.test.ts	Tests checkout identity and Git entry mapping.
test/​planning-provider.test.ts	Tests bounded failure-output quotes.
test/​planning-author.test.ts	Expands hostile prompt-text coverage.
test/​agent-supervisor.test.ts	Tests decoded output boundaries in Docker.
test/​agent-adapter.test.ts	Tests envelope decoding and parser size limits.
docs/​implementation/​planning-audit.md	Links the historical audit to completed schema loading.
docs/​implementation/​plan-library-alignment.md	Records obligation coverage, limitations, and follow-ups.
docs/​implementation/​build-step-1.md	Links the original implementation record to #6 closure.
core/​planning-author.ts	Selects provider schemas by the appropriate version.
core/​plan.ts	Adds registry-driven validation and version guards.
.gitattributes	Preserves LF endings for pinned schemas and CLI copies.

_{Review effort: Balanced}