Plan: Compile Context Once and Project It Truthfully

Plan State

• Status: Complete; T1-T10 green
• Mode: sequential documentation and final review after completed implementation integration
• Scope: IP-317, including every IP-325 and IP-326 acceptance signal
• Planning branch: team/stefan/ip-317-context-plan
• Parent pull request: draft PR #76 on team/stefan/refactor-cli-architecture
• Child branch: team/stefan/ip-317-context-plan
• Child pull-request base: team/stefan/refactor-cli-architecture, never main
• Merge/deploy state: parent and child remain unmerged and undeployed
• Current graph step: T10 complete after clean final autoreview and aggregate validation

Initial Situation

The CLI currently derives context in several places. resolvePackSelection chooses repository packs, while scaffold/output.ts separately computes workspace pack placement, skill closure, prompts, hooks, tools, subagent templates, generated files, and harness mirrors. The generated sync-subagents.mjs then reinterprets neutral .agents content into Claude, Codex, Cursor, and OpenCode files without an explicit capability contract or durable omission record.

packages/scaffold already owns shared schema-only scaffold terms. IP-319 added public-seam characterization that semantically locks repository scopes, packs, contributions, provenance, compatibility, and meaningful ordering while byte-locking managed output downstream. This is the required migration safety net.

Issue

The same semantic inputs can be reinterpreted by setup, stage, projection, and later update paths. Contribution identity, provenance, compatibility, reference closure, and ordering are not represented once at a neutral seam. Harness support is implicit in one portable script, so a known unsupported capability can disappear or be confused with an adapter defect or failed write.

Proposed Solution Shape

Create one shared schema vocabulary in packages/scaffold, then one pure CLI compiler that accepts explicit detected scopes, selected packs, and baseline/catalog data and returns a deterministic neutral ContextPlan. The plan ends at repository-scope identifiers and contribution intent. It contains no target path, filename, link, hash, package mutation, configuration mutation, or write action.

Make setup and default-stage consumers use that compiled plan instead of independently expanding packs. Preserve current output through semantic context equality and the existing byte-locked managed-output fixture.

After IP-325 is green, add schema-backed harness capability matrices and projection outcomes. Refactor the portable consumer-side sync script into a small projection core plus harness adapters. Every adapter declares a versioned matrix for skills, scoped prompts, subagent templates, lifecycle hooks, and tool configuration. Supported actions continue, known gaps emit typed warnings plus partial outcomes and durable omissions, and invalid input, adapter defects, or failed applications remain typed failures for the affected action. Harness files remain reproducible projections of canonical contribution identities.

Design It Twice

1. Put context and projection behavior in packages/scaffold. This gives one importable package but violates its schema-only boundary and pulls CLI placement, harness formats, and filesystem behavior into a shared model package.
2. Keep shared schemas in packages/scaffold; put compilation and portable projection behavior in apps/cli. This preserves package depth: shared consumers learn stable data contracts, while the CLI owns repository discovery, selection, projection, and application.

Choose option 2. The compiler and projector are separate deep modules: the compiler hides semantic resolution behind one pure interface; the projector hides harness-specific representability and output decisions behind versioned adapters. Filesystem application remains outside both.

Locked Decision Ledger

Assumptions and Constraints

• IP-330 remains a native Linear blocker, but accepted PR #76/IP-319 characterization evidence proves the readiness gate. The 2026-07-16 Linear checkpoint comment predates that accepted repo evidence and is not a new product ambiguity.
• IP-325 and IP-326 remain Backlog until implementation evidence exists. Planning does not mutate Linear state.
• The current Effect dependency resolves to 3.22.0 in this checkout. This plan uses existing Schema and @effect/vitest conventions without selecting or blocking IP-320's later repository-wide v4 API migration.
• The canonical contribution categories are: resolved skill, scoped prompt, lifecycle hook, tool configuration, and subagent template. Packs are selection inputs, not contributions; capability groups are subagent composition inputs, not project packs.
• Neutral ordering is explicit and meaningful. Filesystem ordering and byte layout remain downstream projection/application concerns.
• Runtime validation is not required: the accepted behavior is deterministic in-process compilation plus run-owned local filesystem projection. No provider, persistence, queue, deployment, or remote process boundary is involved.
• External dependency research is unnecessary for this slice. Repository code, the accepted grill, live Linear, Effect source guidance, and the resolved local Effect source are sufficient.
• parallel-research was applicable because compiler and harness paths were independent, but no readonly slot was available during planning. Discovery was completed locally from owning sources. A plan-reviewer must still pass before implementation.

Story and Acceptance Mapping

Codebase Findings

• apps/cli/src/scaffold/output.ts currently owns workspace placement and most contribution expansion. It is the main duplication seam to retire, not a target for broader cleanup.
• apps/cli/src/core/resolve-packs.ts already deterministically selects the repository-level pack set. The new compiler consumes its result; it does not replace detection or add selectors.
• apps/cli/src/content/{packs,skills,prompts,hooks,tools,subagents}.ts and baseline data are the existing authored/catalog sources. The compiler references them rather than duplicating workflow prose.
• apps/cli/src/context/public-context-contract.test.ts already distinguishes semantic context from byte-locked managed assets and is the nearest durable public seam.
• apps/cli/src/data/scripts/sync-subagents.mjs is a portable consumer-repo runtime. It currently combines capability policy, rendering, filesystem application, and cleanup for four harnesses.
• packages/scaffold/src/index.ts exports fourteen current runtime schemas, and its public contract fixture enforces round-trip and rejection behavior. New context/capability schemas belong here, while compiler/projector behavior does not.
• docs/README.md, docs/runbooks/hi-cli-scaffolding.md, and routed CLI scaffold-model docs must move with the architecture and operator-visible degradation contract.

Branch/Base Intent

• Parent pull request: draft PR #76.
• Parent branch: team/stefan/refactor-cli-architecture.
• Child branch: team/stefan/ip-317-context-plan.
• Open or update the child pull request with base team/stefan/refactor-cli-architecture, never main.
• Keep parent and child unmerged and undeployed.
• Dependency evidence: PR #76 plus apps/wiki/content/docs/project/specs/cli/IP-319-establish-one-comprehensive-behavior-contract/IMPLEMENTATION-NOTES.md record accepted IP-330 characterization evidence. IP-325 precedes IP-326 inside the child branch.
• Rebase/refresh from the base only with explicit parent coordination because sibling epic work may change shared characterization fixtures.

Dependency Graph

T1 -> T2 -> T3 -> T4 -> T5 -> [T6, T7] -> T8 -> T9 -> T10

The T6/T7 branch is the only parallel implementation wave. Their write scopes are disjoint adapter modules and test files. T8 alone owns shared integration files after both finish.

Parallel Execution Waves

Tasks

T1: Define the neutral context-plan contract

• depends_on: []
• location: packages/scaffold/src/context-plan.ts; packages/scaffold/src/context-plan.test.ts; packages/scaffold/src/index.ts; packages/scaffold/src/public-scaffold-contract.test.ts; packages/scaffold/test-fixtures/public-scaffold.json; docs/README.md
• description: Add schema-backed repository-scope, selected-pack, contribution-identity, source/provenance, compatibility, reference-closure, ordering, and neutral ContextPlan types. Model the five contribution families as a discriminated union. Explicitly reject materialization/write fields and skill workflow policy. Export schemas through @punks/scaffold without adding compiler or filesystem behavior.
• validation: Every new runtime schema round-trips valid data, rejects malformed identity/provenance/closure/order, rejects every forbidden materialization/write field instead of stripping it, and preserves the package's schema-only boundary.
• status: Completed
• log: 2026-07-16 — Added the strict schema-only neutral context contract, test-drove all five contribution families through the public package seam, and added fixture coverage for every exported runtime schema. No compiler, filesystem, materialization, or workflow policy behavior entered packages/scaffold.
• files edited/created: packages/scaffold/src/context-plan.ts; packages/scaffold/src/context-plan.test.ts; packages/scaffold/src/index.ts; packages/scaffold/src/public-scaffold-contract.test.ts; packages/scaffold/test-fixtures/public-scaffold.json; docs/README.md; apps/wiki/content/docs/project/specs/cli/IP-317-compile-context-once-and-project-it-truthfully/PLAN.md; apps/wiki/content/docs/project/specs/cli/IP-317-compile-context-once-and-project-it-truthfully/IMPLEMENTATION-NOTES.md
• backlog_item_id: IP-325
• backlog_item_url: https://linear.app/devpunks/issue/IP-325/resolve-a-neutral-context-plan-for-every-repository-scope
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, tdd]
• tdd_status: required
• tdd_target: The public scaffold contract cannot decode a complete neutral context plan or reject a contribution containing target/write data.
• red_command: bun run --cwd packages/scaffold test -- src/context-plan.test.ts src/public-scaffold-contract.test.ts
• expected_red_failure: The public decode assertion expects failure for fixtures containing targetPath, sha256, writeAction, or packageMutation; any successful decode, including unknown-field stripping, fails RED.
• green_command: bun run --cwd packages/scaffold test -- src/context-plan.test.ts src/public-scaffold-contract.test.ts && bun run --cwd packages/scaffold check-types
• reason_not_testable:
• red_evidence: bun run --cwd packages/scaffold test -- src/context-plan.test.ts src/public-scaffold-contract.test.ts exited 1 after the public-seam tracer test was added: ContextPlan was absent, so decoding failed with Cannot read properties of undefined (reading 'ast'). An earlier exit 127 from missing installed vitest, followed by a passing run while the requested test file was absent, was treated as inconclusive rather than RED.
• green_evidence: Exact green_command passed on 2026-07-16: 2 files, 18 tests passed; tsc --noEmit passed. Focused oxfmt --check and git diff --check also passed. Review correction added docs/README.md ownership for neutral ContextPlan schemas; targeted format and diff checks passed with that file included. Full package check could not load the pre-existing Oxlint JS plugin dependency @effect/eslint-plugin; focused tests, types, formatting, and diff validation remained green.
• codebase_design_notes: ContextPlan is the shared interface; schema validation hides invalid-state complexity. packages/scaffold remains a deep schema module and does not acquire behavior. The contribution union makes category-specific invalid states unrepresentable.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T2: Compile repository context once through the neutral seam

• depends_on: [T1]
• location: apps/cli/src/context/compile-context-plan.ts; apps/cli/src/context/compile-context-plan.test.ts; apps/cli/src/context/test-fixtures/monorepo-context-plan.json; apps/cli/src/context/test-fixtures/single-package-context-plan.json; apps/cli/src/core/models.ts
• description: Implement one pure compiler over explicit detection/scopes, final pack selection, and baseline/catalog inputs. Centralize the current packsForWorkspace placement semantics and resolve skills, scoped prompts, hooks, tools, and subagent contribution intent with stable identity, provenance, compatibility, reference closure, and meaningful order. Keep capability groups distinct from project packs and never inspect SKILL.md workflow prose.
• validation: Identical inputs produce identical encoded plans; monorepo and single-package fixtures cover every contribution family; pack placement matches characterized current behavior; negative assertions prove no target/write data and no pack-to-capability-group shortcut.
• status: Completed
• log: 2026-07-16 — Added one pure compileContextPlan(input) seam over explicit scopes, final packs, the unchanged baseline catalog, pre-resolved skill metadata, capability groups, and subagent templates. Characterized monorepo and single-package plans cover all five contribution families, exact current workspace placement edges, deterministic identity/provenance/order, no materialization data, and pack-independent capability-group resolution. Review follow-up made skill reference closure and compatibility explicit context-resolution input, then rejected missing resolved metadata plus unknown pack/capability-group skill references, required tools, and template capability groups instead of silently omitting them. No skill catalog or bundled baseline data changed.
• files edited/created: apps/cli/src/context/compile-context-plan.ts; apps/cli/src/context/compile-context-plan.test.ts; apps/cli/src/context/test-fixtures/monorepo-context-plan.json; apps/cli/src/context/test-fixtures/single-package-context-plan.json; apps/cli/src/core/models.ts
• backlog_item_id: IP-325
• backlog_item_url: https://linear.app/devpunks/issue/IP-325/resolve-a-neutral-context-plan-for-every-repository-scope
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: A characterized repository input has no single result containing the exact per-scope packs and all five resolved contribution families.
• red_command: bun run --cwd apps/cli test -- src/context/compile-context-plan.test.ts
• expected_red_failure: Compiler export/fixture is absent, or scope placement/contribution metadata differs from the characterized semantic outcome.
• green_command: bun run --cwd apps/cli test -- src/context/compile-context-plan.test.ts && bun run --cwd apps/cli check-types
• reason_not_testable:
• red_evidence: Exact plan command exited 1 because ./compile-context-plan did not exist. Later vertical slices failed against empty monorepo/single-package fixtures and exposed two placement mismatches: apps/service was incorrectly treated as backend and @tanstack/query-persist-client-core was omitted. Review RED failed both fixtures because effect-authoring emitted its source directory with empty compatibility instead of six required references and Effect ^3.21.2; the referential-integrity RED then failed four cases for silently omitted or untyped unknown capability groups, pack/capability-group skills, and required tools. Final seam RED failed five tests because metadata was incorrectly required on baseline skills, real bundledBaseline metadata was not consumed separately, and missing resolved metadata did not fail.
• green_evidence: Exact plan command passed 1 file and 10 tests; bun run --cwd apps/cli check-types passed, including a typed compiler call with the real unchanged bundledBaseline plus separate resolved metadata. Focused Oxfmt check passed. Tracked git diff --check passed, and explicit git diff --no-index --check /dev/null <file> produced no check diagnostics for each of the four untracked T2 files (expected diff exit 1).
• codebase_design_notes: One compileContextPlan(input) interface hides catalog joins, placement, closure, and ordering. Inputs are in-process immutable data; discovery and I/O stay outside. The compiler is the public semantic test surface.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T3: Cut scaffold consumers over and close IP-325

• depends_on: [T2]
• location: apps/cli/src/context/compile-context-plan.ts; apps/cli/src/scaffold/output.ts; apps/cli/src/scaffold/run.ts; apps/cli/src/scaffold/stage.ts; apps/cli/src/scaffold/run.test.ts; apps/cli/src/scaffold/stage.test.ts; apps/cli/src/context/public-context-contract.test.ts; apps/cli/test-fixtures/public-output/context-outcome.json; apps/cli/test-fixtures/public-output/managed-assets.json; apps/cli/src/core/models.ts
• description: Compile once after final pack selection, pass the plan to setup and default-stage output, and remove their independent workspace pack/contribution derivation. Persist an encoded neutral plan as semantic evidence without putting materialization data into it. Keep current managed files and prose byte-locked downstream. Do not implement update/reconciliation policy owned by IP-318.
• validation: Setup and stage consume the same compiler; public context meaning is unchanged; every manifest-managed byte remains unchanged unless an explicitly reviewed evidence-only path is added; a search/test proves removed duplicate derivation is not still active.
• status: Completed
• log: 2026-07-16 — Setup and default-stage now compile one neutral context plan after final pack selection and pass that same value into scaffold output. Default-stage adds its prospective final wiki scope before that single compile and before writes. Output derives workspace packs, skills, prompts, hooks, lint placement, and real subagent identities/reference closure from the plan, persists schema-encoded .devpunks/context-plan.json as managed semantic evidence, and removes the prior workspace/subagent derivation and empty placeholder fallback. Existing managed bytes remain fixture-locked; only the reviewed context evidence inventory entry changed. Legacy update callers keep their existing non-persisting path so IP-318 reconciliation remains out of scope. 2026-07-18 repair: output no longer filters canonical scoped-prompt contributions by current filesystem presence, and subagent capability/template semantics now return through compileContextPlan instead of a second hand-written contribution compiler.
• files edited/created: apps/cli/src/context/compile-context-plan.ts; apps/cli/src/scaffold/output.ts; apps/cli/src/scaffold/run.ts; apps/cli/src/scaffold/stage.ts; apps/cli/src/scaffold/run.test.ts; apps/cli/src/scaffold/stage.test.ts; apps/cli/src/context/public-context-contract.test.ts; apps/cli/test-fixtures/public-output/context-outcome.json; apps/cli/test-fixtures/public-output/managed-assets.json; apps/cli/src/core/models.ts; apps/wiki/content/docs/project/specs/cli/IP-317-compile-context-once-and-project-it-truthfully/PLAN.md; apps/wiki/content/docs/project/specs/cli/IP-317-compile-context-once-and-project-it-truthfully/IMPLEMENTATION-NOTES.md
• backlog_item_id: IP-325
• backlog_item_url: https://linear.app/devpunks/issue/IP-325/resolve-a-neutral-context-plan-for-every-repository-scope
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: The public context contract cannot prove setup and stage use one neutral plan while preserving characterized meaning and managed bytes.
• red_command: bun run --cwd apps/cli test -- src/context/public-context-contract.test.ts src/scaffold/run.test.ts src/scaffold/stage.test.ts
• expected_red_failure: No persisted neutral plan exists, consumers still derive contributions independently, or semantic/byte fixtures drift.
• green_command: bun run --cwd apps/cli test -- src/context/public-context-contract.test.ts src/scaffold/run.test.ts src/scaffold/stage.test.ts && bun run --cwd apps/cli build && bun run --cwd apps/cli check-types
• reason_not_testable:
• red_evidence: Exact red_command exited 1 after the public tracer assertions were added: 3 tests failed and 33 passed. Setup and stage returned undefined for contextPlanFile; the public contract then failed because path.join received that undefined value. No production code had been edited before this RED. Repair RED failed the fresh root/workspace public contract because only the shared prompt survived persistence, and the compiler-authority scan found withSubagentContributions plus empty compiler inputs.
• green_evidence: Exact green_command passed on 2026-07-16: 3 files and 36 tests passed; the CLI build bundled 1037 modules; tsc --noEmit passed. Review-fix RED then failed 2 tests/34 passed for the missing prospective apps/wiki scope and placeholder subagent semantics; the corrected focused suite returned to 36/36. Focused update/public-output regression coverage also passed: 2 files and 39 tests. The 2026-07-18 repair focused suite passed 5 files/77 tests: absent root/workspace sources remain in the encoded plan and produce per-adapter MissingCanonicalPromptWarning omissions. Prompt blueprint input reuses the compiler's pure scope-selection seam, and the source scan proves exactly one compileContextPlan( invocation with real capability/template inputs plus no hand-written subagent contribution constructor. Focused Oxfmt and git diff --check passed.
• codebase_design_notes: Setup and stage become callers of the compiler seam. Filesystem rendering remains an adapter outside the neutral plan. This task removes only derivation made redundant by the new seam.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T4: Define versioned harness capability and outcome contracts

• depends_on: [T3]
• location: packages/scaffold/src/harness-capability.ts; packages/scaffold/src/harness-capability.test.ts; packages/scaffold/src/index.ts; packages/scaffold/src/public-scaffold-contract.test.ts; packages/scaffold/test-fixtures/public-scaffold.json
• description: Add neutral capability-family, support-level, matrix-version, adapter identity, typed unsupported warning, projection action outcome, omission, partial/success/failure summary, and traceability schemas. Separate known unsupported/degraded support from invalid projection, adapter defect, and failed application errors.
• validation: Schema tests cover supported, degraded, unsupported, omission-only partial, invalid, defect, and application-failure shapes; impossible warning/error combinations are rejected; matrix version is mandatory; every matrix has exactly one row for each of the five contribution families; failures preserve prior omissions alongside independent errors.
• status: Completed
• log: 2026-07-16 — Added the schema-only versioned harness capability contract. Capability matrices declare adapter identity and exactly one supported, degraded, or unsupported row for each neutral contribution family. Projection outcomes preserve context-plan, scope, contribution, adapter, and matrix traceability; known unsupported omissions remain typed warnings, including omission-only partial summaries and failures that also contain independent typed errors. Invalid projections, adapter defects, and application failures remain distinct. No adapter, projection, materialization, skill, or baseline behavior was added.
• files edited/created: packages/scaffold/src/harness-capability.ts; packages/scaffold/src/harness-capability.test.ts; packages/scaffold/src/index.ts; packages/scaffold/src/public-scaffold-contract.test.ts; packages/scaffold/test-fixtures/public-scaffold.json; docs/README.md; apps/wiki/content/docs/project/specs/cli/IP-317-compile-context-once-and-project-it-truthfully/PLAN.md; apps/wiki/content/docs/project/specs/cli/IP-317-compile-context-once-and-project-it-truthfully/IMPLEMENTATION-NOTES.md
• backlog_item_id: IP-326
• backlog_item_url: https://linear.app/devpunks/issue/IP-326/project-canonical-contributions-through-explicit-harness-capabilities
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, tdd]
• tdd_status: required
• tdd_target: Shared schemas cannot distinguish a known unsupported omission from an invalid projection or failed application.
• red_command: bun run --cwd packages/scaffold test -- src/harness-capability.test.ts src/public-scaffold-contract.test.ts
• expected_red_failure: Capability matrices and discriminated warning/outcome/error contracts are absent or permit ambiguous states.
• green_command: bun run --cwd packages/scaffold test -- src/harness-capability.test.ts src/public-scaffold-contract.test.ts && bun run --cwd packages/scaffold check-types
• reason_not_testable:
• red_evidence: Exact red_command exited 1 with 1 failed/4 passed because HarnessCapabilityMatrix was absent and public decoding failed with Cannot read properties of undefined (reading 'ast'). Subsequent vertical tracers failed for the absent typed unsupported omission, applied action outcome, projection summary, and 44-case public runtime-schema fixture. Review repair RED then failed two matrix tests because missing and duplicate families decoded successfully; separate omission-only partial and omission-preserving failure tracers failed at their public summary variants before each minimal schema correction.
• green_evidence: Exact green_command passed on 2026-07-16 after review repair: 2 files and 20 tests passed; tsc --noEmit passed. The full scaffold package suite passed with 4 files and 39 tests. Focused oxfmt --check across the eight owned code, fixture, plan, notes, and docs files passed; tracked and untracked diff integrity checks passed.
• codebase_design_notes: The shared schema is the compatibility interface. Version and support state are explicit data, not incidental adapter branches. Behavior and harness formats stay outside the package.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T5: Extract the portable projection core and shared contract harness

• depends_on: [T4]
• location: apps/cli/src/data/scripts/harness-projection/core.mjs; apps/cli/src/data/scripts/harness-projection/apply.mjs; apps/cli/src/data/scripts/harness-projection/contract.ts; apps/cli/src/data/scripts/harness-projection/contract.test.ts; apps/cli/src/data/scripts/harness-projection/test-fixtures
• description: Define the portable adapter interface and shared contract suite used by the generated consumer-repo runtime. Project canonical contribution identities into adapter actions, continue independent supported actions, accumulate typed known-gap warnings/omissions into partial outcomes, and fail invalid input, adapter defects, or application errors only for affected actions. Keep filesystem application separate from pure projection.
• validation: Stub adapters pass the same supported/degraded/unsupported/mixed/error/determinism contract before real harness adapters are added; run-owned temp application proves per-action failure and cleanup.
• status: Completed
• log: 2026-07-17 — Added the dependency-light pure projection core, portable adapter interface, separate filesystem application boundary, and shared contract suite. Supported and degraded actions continue independently, unsupported capabilities produce traceable omissions and partial summaries, adapter defects remain typed failures, application failures stay scoped to their actions, and deterministic replay plus run-owned cleanup are covered. Published as commit 200623e8 before adapter fan-out. 2026-07-18 repair: mandatory matrix version and adapter id/version metadata are validated before projection, including empty plans, so invalid matrices cannot return false success or emit unversioned actions.
• files edited/created: apps/cli/src/data/scripts/harness-projection/apply.d.mts; apps/cli/src/data/scripts/harness-projection/apply.mjs; apps/cli/src/data/scripts/harness-projection/contract.test.ts; apps/cli/src/data/scripts/harness-projection/contract.ts; apps/cli/src/data/scripts/harness-projection/core.d.mts; apps/cli/src/data/scripts/harness-projection/core.mjs; apps/cli/src/data/scripts/harness-projection/test-fixtures/application-context-plan.json; apps/cli/src/data/scripts/harness-projection/test-fixtures/mixed-context-plan.json
• backlog_item_id: IP-326
• backlog_item_url: https://linear.app/devpunks/issue/IP-326/project-canonical-contributions-through-explicit-harness-capabilities
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: Mixed supported and unsupported contributions either abort entirely or omit a capability without typed partial evidence.
• red_command: bun run --cwd apps/cli test -- src/data/scripts/harness-projection/contract.test.ts
• expected_red_failure: Portable core/contract is absent, or the mixed case lacks continued supported actions, scoped warning, omission, and partial result.
• green_command: bun run --cwd apps/cli test -- src/data/scripts/harness-projection/contract.test.ts && bun run --cwd apps/cli check-types
• reason_not_testable:
• red_evidence: The exact red_command first failed while the portable core and contract exports were absent. Vertical tracers then exposed missing mixed projection, invalid matrix/result validation, adapter-defect isolation, application-failure isolation, deterministic replay, and run-owned cleanup behavior.
• green_evidence: Exact green_command passed on 2026-07-17: 1 file and 12 tests passed; CLI tsc --noEmit passed. Commit 200623e8 published the reviewed shared seam before the disjoint T6/T7 adapter wave. Repair RED added six missing/invalid metadata variants plus an empty-plan false-success case; the repaired shared contract passes 1 file/19 tests with typed InvalidHarnessProjectionError evidence and zero actions.
• codebase_design_notes: project(adapter, context) is the seam; the adapter returns projection intent, and apply owns local filesystem effects. A shared contract tests every adapter through that same interface. The portable module remains dependency-light so the generated script can run under Node.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T6: Implement Claude and Codex capability adapters

• depends_on: [T5]
• location: apps/cli/src/data/scripts/harness-projection/adapters/claude.mjs; apps/cli/src/data/scripts/harness-projection/adapters/codex.mjs; apps/cli/src/data/scripts/harness-projection/adapters/claude.test.ts; apps/cli/src/data/scripts/harness-projection/adapters/codex.test.ts; apps/cli/src/data/scripts/harness-projection/test-fixtures/claude; apps/cli/src/data/scripts/harness-projection/test-fixtures/codex
• description: Publish versioned Claude and Codex matrices and implement their pure projection behavior for skills, scoped prompts, subagent templates, lifecycle hooks, and tool configuration. Preserve current harness-native bytes for supported behavior and declare every known gap explicitly.
• validation: Both adapters pass the T5 shared contract plus exact supported-output fixtures; matrix/version changes cannot occur without fixture changes; all outputs carry canonical contribution identity.
• status: Completed
• log: 2026-07-17 — Implemented versioned Claude and Codex adapters through the T5 seam with schema-valid production-shaped context fixtures. Independent review rejected whole-manifest fan-out, invented Codex skill registration, synthetic single-contribution fixtures, ambiguous shared configuration targets, and incorrect shared/root prompt mappings. The corrected adapters use targetless canonical skill intents, exact native prompt/hook mechanisms, one collision-free render intent per canonical subagent template, template-local Codex skill linkage, and typed omissions for all four real tool contributions. Independent rereview passed; post-parallel convergence remained green.
• files edited/created: apps/cli/src/data/scripts/harness-projection/adapters/claude.mjs; apps/cli/src/data/scripts/harness-projection/adapters/claude.test.ts; apps/cli/src/data/scripts/harness-projection/adapters/codex.mjs; apps/cli/src/data/scripts/harness-projection/adapters/codex.test.ts; apps/cli/src/data/scripts/harness-projection/test-fixtures/claude/actions.json; apps/cli/src/data/scripts/harness-projection/test-fixtures/claude/context-plan.json; apps/cli/src/data/scripts/harness-projection/test-fixtures/claude/matrix.json; apps/cli/src/data/scripts/harness-projection/test-fixtures/claude/traces.json; apps/cli/src/data/scripts/harness-projection/test-fixtures/codex/actions.json; apps/cli/src/data/scripts/harness-projection/test-fixtures/codex/context-plan.json; apps/cli/src/data/scripts/harness-projection/test-fixtures/codex/matrix.json; apps/cli/src/data/scripts/harness-projection/test-fixtures/codex/traces.json
• backlog_item_id: IP-326
• backlog_item_url: https://linear.app/devpunks/issue/IP-326/project-canonical-contributions-through-explicit-harness-capabilities
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: Claude and Codex have no explicit matrix or shared-contract proof tying generated output to canonical contribution identities.
• red_command: bun run --cwd apps/cli test -- src/data/scripts/harness-projection/adapters/claude.test.ts src/data/scripts/harness-projection/adapters/codex.test.ts
• expected_red_failure: Adapter exports/matrices are absent or supported bytes and unsupported outcomes are implicit.
• green_command: bun run --cwd apps/cli test -- src/data/scripts/harness-projection/adapters/claude.test.ts src/data/scripts/harness-projection/adapters/codex.test.ts
• reason_not_testable:
• red_evidence: Exact red_command first exited 1 because claude.mjs was absent. Subsequent vertical tracers failed for missing Claude family actions; Codex then failed first for its absent adapter and again for missing native actions. Review-repair RED failed 6 assertions across both files: invented Codex .codex/agents skill registration, N whole-manifest renders targeting the same directory, synthetic fixtures, ambiguous shared config targets, wrong shared/root prompt mechanisms, and stale capability matrices.
• green_evidence: Exact green_command passed after review repair on 2026-07-17: 2 files and 18 tests passed. The shared-core convergence command passed 5 files and 47 tests; CLI tsc --noEmit, direct Node imports, focused Oxfmt across all 24 adapter/fixture files, and git diff --check passed. The Claude/Codex fixture audit found 13 Claude actions with 9 unique targets and 13 Codex actions with 7 unique targets; each returned exactly four typed tool omissions and a partial summary.
• codebase_design_notes: Each adapter is a real seam because it implements the common projection interface. Harness filenames and schemas remain local to the adapter, never the context plan.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T7: Implement Cursor and OpenCode capability adapters

• depends_on: [T5]
• location: apps/cli/src/data/scripts/harness-projection/adapters/cursor.mjs; apps/cli/src/data/scripts/harness-projection/adapters/opencode.mjs; apps/cli/src/data/scripts/harness-projection/adapters/cursor.test.ts; apps/cli/src/data/scripts/harness-projection/adapters/opencode.test.ts; apps/cli/src/data/scripts/harness-projection/test-fixtures/cursor; apps/cli/src/data/scripts/harness-projection/test-fixtures/opencode
• description: Publish versioned Cursor and OpenCode matrices and implement their pure projection behavior for the same five neutral capability families. Preserve supported current bytes and make narrower support explicit rather than silently dropping contributions.
• validation: Both adapters pass the T5 shared contract plus exact supported-output fixtures; known gaps produce scoped warnings/omissions and do not stop independent supported actions.
• status: Completed
• log: 2026-07-17 — Implemented versioned Cursor and OpenCode adapters in the disjoint T7 write scope. Both consume production compileContextPlan inputs, lock exact matrices and projection fixtures, preserve neutral .agents skill/prompt sources, project the two known lifecycle hooks through their current harness-native mechanisms, render template-specific agent files, and record all four operator-tool gaps as typed omissions without stopping supported work. Review corrected fabricated OpenCode tool identity, prompt target drift, and missing skill-bearing compiler inputs. Independent rereview passed; post-parallel common-plan convergence remained green.
• files edited/created: apps/cli/src/data/scripts/harness-projection/adapters/cursor.mjs; apps/cli/src/data/scripts/harness-projection/adapters/cursor.test.ts; apps/cli/src/data/scripts/harness-projection/adapters/opencode.mjs; apps/cli/src/data/scripts/harness-projection/adapters/opencode.test.ts; apps/cli/src/data/scripts/harness-projection/test-fixtures/cursor/compiler-input.json; apps/cli/src/data/scripts/harness-projection/test-fixtures/cursor/context-plan.json; apps/cli/src/data/scripts/harness-projection/test-fixtures/cursor/matrix.json; apps/cli/src/data/scripts/harness-projection/test-fixtures/cursor/projection.json; apps/cli/src/data/scripts/harness-projection/test-fixtures/opencode/compiler-input.json; apps/cli/src/data/scripts/harness-projection/test-fixtures/opencode/context-plan.json; apps/cli/src/data/scripts/harness-projection/test-fixtures/opencode/matrix.json; apps/cli/src/data/scripts/harness-projection/test-fixtures/opencode/projection.json
• backlog_item_id: IP-326
• backlog_item_url: https://linear.app/devpunks/issue/IP-326/project-canonical-contributions-through-explicit-harness-capabilities
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: Cursor and OpenCode silently rely on incidental script behavior instead of explicit versioned support and typed omissions.
• red_command: bun run --cwd apps/cli test -- src/data/scripts/harness-projection/adapters/cursor.test.ts src/data/scripts/harness-projection/adapters/opencode.test.ts
• expected_red_failure: Adapter exports/matrices are absent or a known unsupported family disappears without warning and partial outcome.
• green_command: bun run --cwd apps/cli test -- src/data/scripts/harness-projection/adapters/cursor.test.ts src/data/scripts/harness-projection/adapters/opencode.test.ts
• reason_not_testable:
• red_evidence: Exact red_command first failed both suites because cursor.mjs and opencode.mjs were absent. Review then exposed an OpenCode formatter action under a fabricated tool id while every real tool defected, plus shared-prompt target drift. A final fixture-only review found compiler inputs without skill contributions, so native skill actions were unproved.
• green_evidence: Initial GREEN passed 14/14 focused tests and 26/26 shared-plus-T7 tests. Review repair moved OpenCode formatting to the real lifecycle formatter/scaffold-update mechanism, kept all four real tools as typed omissions without defects, and restored canonical shared prompt targets (.agents/AGENTS.md for Cursor and .opencode/AGENTS.md for OpenCode); 16/16 focused and 28/28 shared-plus-T7 tests passed. Adding Effect-pack and effect-authoring resolved skill metadata preserved that rereview PASS. The common-plan convergence addition then brought the current exact green_command to 2 files/17 tests and the shared-core command to 5 files/47 tests. CLI tsc --noEmit, direct Node imports, focused Oxfmt across all 24 adapter/fixture files, and git diff --check passed. The common-plan audit found Claude 8 actions/7 unique targets, Codex 8/6, Cursor 6/5, and OpenCode 6/5; every adapter retained exactly four typed tool omissions and a partial summary.
• codebase_design_notes: Same common interface and locality rule as T6. Cursor/OpenCode support differences are data in their matrices and behavior in their adapters, not conditionals leaked into shared compilation.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T8: Integrate truthful projection and close IP-326

• depends_on: [T6, T7]
• location: apps/cli/src/data/scripts/sync-subagents.mjs; apps/cli/src/data/scripts/sync-subagents.test.ts; apps/cli/src/scaffold/output.ts; apps/cli/src/scaffold/run.ts; apps/cli/src/scaffold/stage.ts; apps/cli/src/scaffold/run.test.ts; apps/cli/src/scaffold/stage.test.ts; apps/cli/src/context/public-context-contract.test.ts; apps/cli/src/core/models.ts; apps/cli/test-fixtures/public-output/context-outcome.json; apps/cli/test-fixtures/public-output/managed-assets.json
• description: Make the generated sync entrypoint a thin loader/application shell over T5-T7. Feed it the canonical context plan, validate matrices/outcomes, persist a projection receipt with supported actions, warnings, omissions, failures, matrix versions, and canonical identities, and surface partial status to scaffold callers. Preserve successful independent writes. Propagate invalid projection, adapter defect, or failed application as typed affected-action failure instead of ordinary degradation.
• validation: A run-owned consumer fixture exercises all four harnesses together; mixed support yields exact partial evidence and successful supported files; defect/write-failure scenarios remain errors; repeated input produces identical projection/receipt bytes; existing supported managed output remains byte-compatible.
• status: Completed
• log: 2026-07-18 — Integrated the accepted projection core and all four adapters into the generated consumer sync shell. Canonical setup/stage output now persists a deterministic receipt and exposes its status; supported actions continue beside explicit omissions, while malformed plans, adapter defects, missing sources, failed writes, and unsafe paths remain typed affected-action failures. Review repairs made legacy fallback absence-only, preserved consumer-owned prompt files as omissions instead of applied actions, aligned all adapters with the compiler's real shared scope, restored the OpenCode formatter mirror, and rejected absolute/traversal/out-of-root action paths before mutation. Repair follow-up strictly validates the full portable ContextPlan before every adapter, makes JSON null and forbidden/malformed nested fields durable typed failures, and resolves existing ancestors through realpath so symlinked parent directories cannot escape the repository. Nested action configuration paths receive the same containment checks, preventing Cursor's .cursor/hooks.json leaf from following a symlink outside. T10 review then found stale managed-agent cleanup still mutated outside the typed action pipeline and before receipt persistence. Cleanup is now one path-contained, plan-scoped action per adapter for every valid plan, including plans with zero templates. Its strict application trace records the plan version, adapter and matrix versions, and cleanup operation without inventing a contribution or scope. Invalid plans perform no cleanup, successful stale deletion appears in receipt actions, and cleanup scan/delete failures become durable HarnessApplicationFailureError evidence while independent adapters continue.
• files edited/created: packages/scaffold/src/harness-capability.ts; packages/scaffold/src/harness-capability.test.ts; packages/scaffold/src/public-scaffold-contract.test.ts; packages/scaffold/test-fixtures/public-scaffold.json; apps/cli/src/context/public-context-contract.test.ts; apps/cli/src/core/models.ts; apps/cli/src/data/scripts/harness-projection/adapters/claude.mjs; apps/cli/src/data/scripts/harness-projection/adapters/codex.mjs; apps/cli/src/data/scripts/harness-projection/adapters/cursor.mjs; apps/cli/src/data/scripts/harness-projection/adapters/opencode.mjs; apps/cli/src/data/scripts/harness-projection/apply.d.mts; apps/cli/src/data/scripts/harness-projection/apply.mjs; apps/cli/src/data/scripts/harness-projection/contract.ts; apps/cli/src/data/scripts/harness-projection/test-fixtures/opencode/projection.json; apps/cli/src/data/scripts/sync-subagents.mjs; apps/cli/src/data/scripts/sync-subagents.test.ts; apps/cli/src/scaffold/output.ts; apps/cli/src/scaffold/run.test.ts; apps/cli/src/scaffold/run.ts; apps/cli/src/scaffold/stage.test.ts; apps/cli/src/scaffold/stage.ts; apps/cli/test-fixtures/public-output/context-outcome.json; apps/cli/test-fixtures/public-output/json-serialization.json; apps/cli/test-fixtures/public-output/managed-assets.json; apps/wiki/content/docs/project/specs/cli/IP-317-compile-context-once-and-project-it-truthfully/PLAN.md; apps/wiki/content/docs/project/specs/cli/IP-317-compile-context-once-and-project-it-truthfully/IMPLEMENTATION-NOTES.md
• backlog_item_id: IP-326
• backlog_item_url: https://linear.app/devpunks/issue/IP-326/project-canonical-contributions-through-explicit-harness-capabilities
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: End-to-end scaffold projection cannot report exactly which harness/contribution degraded while retaining supported output and distinguishing real failures.
• red_command: bun run --cwd apps/cli test -- src/data/scripts/sync-subagents.test.ts src/context/public-context-contract.test.ts src/scaffold/run.test.ts src/scaffold/stage.test.ts
• expected_red_failure: No versioned matrices or durable receipt exist, mixed support is silent/abortive, or failure categories collapse into warnings.
• green_command: bun run --cwd apps/cli test -- src/data/scripts/sync-subagents.test.ts src/context/public-context-contract.test.ts src/scaffold/run.test.ts src/scaffold/stage.test.ts && bun run --cwd apps/cli build && bun run --cwd apps/cli check-types
• reason_not_testable:
• red_evidence: The first all-four run-owned consumer test failed because .devpunks/harness-projection-receipt.json did not exist while the legacy sync path still exited successfully. Subsequent RED slices exposed adapter defects and application failures exiting zero, scopes: null falling into legacy behavior, malformed JSON exiting without durable evidence, missing hook sources counted as applied, and consumer prompt collisions counted as successful writes. Final independent review reproduced a path escape: scope ../ip317-path-escape exited zero, reported success, and created /tmp/ip317-path-escape/CLAUDE.md; the direct regression test then failed 1/16 because the sync promise resolved instead of rejecting. Repair RED added seven failures: JSON null produced no receipt, forbidden targetPath and missing identity.version still projected actions, and a linked -> outside scope wrote outside/CLAUDE.md with exit zero. The leaf-symlink RED then failed 1/21 because .cursor/hooks.json -> outside/hooks.json exited zero and overwrote the external file. T10 cleanup RED failed 2/22: malformed canonical input deleted a managed sentinel, and a cleanup filesystem error exited before writing any receipt. The first repair then failed a 1/23 zero-template regression because a valid empty plan left stale managed agents, while the public-schema RED failed 1/19 because no strict plan-scoped application trace existed.
• green_evidence: The accepted integration persists deterministic action, warning, omission, failure, matrix-version, adapter-version, and canonical-identity evidence; returns partial to setup/stage callers; preserves supported bytes and consumer-owned prompt files; and writes a failure receipt before nonzero exit for malformed input, adapter defects, missing sources, failed writes, unsafe paths, and managed-agent cleanup failures. Lexical plus resolved-ancestor containment validates every projected source, target, file, nativePath, canonicalPath, managed-agent directory, and nested config.path before action mutation while independent safe actions continue. Invalid plans cannot schedule cleanup; every valid plan schedules one cleanup action per adapter even when it has no template contribution. Final repair validation passed package scaffold at 4 files/44 tests, the sync suite at 23/23, the focused sync/public/core contract at 3 files/45 tests, and full CLI at 35 files/310 tests. Both package typechecks, the 1038-module CLI build, focused Oxfmt, git diff --check, and the complete 15-task repository behavior contract including 8/8 browser flows passed. The known CLI check wrapper remains blocked by its pre-existing missing @typescript-eslint/utils peer dependency.
• codebase_design_notes: sync-subagents.mjs becomes a thin application boundary. The projection receipt is evidence, not a new source of desired state. Canonical context identities flow through adapters to every output and omission.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: Review-owned /tmp/ip317-path-escape was provenance-checked, removed exactly, and verified absent after the regression and final validation gates.

T9: Ingest operator, architecture, and scaffold-model documentation

• depends_on: [T8]
• location: docs/README.md; docs/runbooks/hi-cli-scaffolding.md; apps/wiki/content/docs/cli/scaffold-model/context-plan.mdx; apps/wiki/content/docs/cli/scaffold-model/harness-capability-projection.mdx; apps/wiki/content/docs/cli/scaffold-model/shared-scaffold-model.mdx; apps/wiki/content/docs/cli/scaffold-model/meta.json; apps/wiki/content/docs/project/runbooks/hi-cli-scaffolding.md; apps/wiki/content/docs/project/specs/cli/IP-317-compile-context-once-and-project-it-truthfully/SPEC.md; apps/wiki/content/docs/project/specs/cli/IP-317-compile-context-once-and-project-it-truthfully/PLAN.md; apps/wiki/content/docs/project/specs/cli/IP-317-compile-context-once-and-project-it-truthfully/IMPLEMENTATION-NOTES.md; apps/wiki/index.md; apps/wiki/log.md
• description: Enter docs-ingest-phase private/internal routing. Scan relevant routed learnings, write the context-plan flow before the capability-projection concept, update shared-model ownership, navigation, runbook/operator expectations, ingest metadata/bookkeeping, and durable implementation evidence. Explain partial/degraded results and the distinction from failures without embedding agent task instructions in product docs.
• validation: New routes are navigable; frontmatter/source links and ingest bookkeeping are current; runbook and wiki agree on ownership, neutral boundaries, warning/failure semantics, and matrix compatibility.
• status: Completed
• log: Entered docs-ingest-phase private/internal routing; the scoped routed-learning and raw scans found no relevant context-plan/projection artifact to update, so the new flow, capability concept, shared-model links, and operator runbook became the future-use hooks. Wrote the context-plan flow before the capability concept, updated shared ownership/navigation/root docs, added ingest metadata and capped bookkeeping, and kept T10 explicitly pending.
• files edited/created: docs/README.md; docs/runbooks/hi-cli-scaffolding.md; apps/wiki/content/docs/cli/scaffold-model/context-plan.mdx; apps/wiki/content/docs/cli/scaffold-model/harness-capability-projection.mdx; apps/wiki/content/docs/cli/scaffold-model/shared-scaffold-model.mdx; apps/wiki/content/docs/cli/scaffold-model/meta.json; apps/wiki/content/docs/project/runbooks/hi-cli-scaffolding.md; apps/wiki/content/docs/project/specs/cli/IP-317-compile-context-once-and-project-it-truthfully/SPEC.md; apps/wiki/content/docs/project/specs/cli/IP-317-compile-context-once-and-project-it-truthfully/PLAN.md; apps/wiki/content/docs/project/specs/cli/IP-317-compile-context-once-and-project-it-truthfully/IMPLEMENTATION-NOTES.md; apps/wiki/index.md; apps/wiki/log.md
• backlog_item_id: IP-317
• backlog_item_url: https://linear.app/devpunks/issue/IP-317/compile-context-once-and-project-it-truthfully
• relation_mode: native
• assigned_skills: [docs-ingest-phase, autoreview, codebase-design, docs-onboarding, improve-codebase-architecture, parallel-research, simplify, tdd, writing-beats, writing-fragments, writing-great-skills, writing-shape, agent-browser, async-react-patterns, design-taste-frontend, frontend-domain-structure, next-best-practices, next-cache-components, quality-types, react-doctor, vercel-composition-patterns, vercel-react-best-practices]
• tdd_status: not_applicable
• tdd_target: Documentation and ingest bookkeeping accurately expose the proven architecture and operator-visible outcomes.
• red_command: not_applicable
• expected_red_failure: not_applicable
• green_command: bun run --cwd apps/wiki test && bun run --cwd apps/wiki check-types && bunx oxfmt --check docs/README.md docs/runbooks/hi-cli-scaffolding.md apps/wiki/content/docs/cli/scaffold-model apps/wiki/content/docs/project/specs/cli/IP-317-compile-context-once-and-project-it-truthfully apps/wiki/index.md apps/wiki/log.md
• reason_not_testable: Docs-only and ingest-bookkeeping task; validated through route/type/format checks.
• red_evidence:
• green_evidence: Exact T9 command passed: wiki Vitest 2 files/6 tests, the scripted wiki check-types command, and focused Oxfmt. The check-types pre-step exposed pre-existing mutating sync behavior by pruning checked-in project routes when their projection sources are absent in this worktree; that validation-only drift was restored exactly. Running the local Fumadocs MDX generator, Next route type generation, and tsc --noEmit directly against the restored tree passed. git diff --check, route/navigation inspection, frontmatter/source-link inspection, and the 50-entry log cap passed.
• codebase_design_notes: Documentation preserves the same seam boundaries: shared schemas, CLI compiler, harness adapters, and filesystem application. No duplicate source-of-truth tree is introduced.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T10: Run final review and coordinated acceptance gates

• depends_on: [T9]
• location: readonly inspection of all T1-T9 paths; apps/wiki/content/docs/project/specs/cli/IP-317-compile-context-once-and-project-it-truthfully/PLAN.md; apps/wiki/content/docs/project/specs/cli/IP-317-compile-context-once-and-project-it-truthfully/IMPLEMENTATION-NOTES.md; child pull-request evidence based on team/stefan/refactor-cli-architecture
• description: Parent performs readonly validation by rerunning the narrow package/CLI gates and then the one comprehensive repository behavior contract. Run findings-first review plus structured autoreview against the actual child PR base. Verify every IP-325/IP-326 criterion, exact task evidence, zero silent omission, no context materialization leakage, no duplicate compiler path, capability matrix versioning, docs freshness, branch/base safety, and cleanup. T10 edits nothing: route every accepted finding back to its owning T1-T9 task and scoped worker, then repeat readonly validation only after that owner returns green evidence.
• validation: All focused and repository gates pass; independent review has no accepted actionable finding; every task contains RED/GREEN evidence; child PR base is team/stefan/refactor-cli-architecture; parent and child remain unmerged/undeployed. Any failure leaves T10 incomplete and returns to the owning task without cross-scope repair.
• status: Complete
• log: 2026-07-19 — Structured and independent review repairs preserve canonical evidence, reconcile authored manifests and lifecycle mirrors, compile prospective docs and pack-only agents, and share managed-kind authority. Follow-up lifecycle/security repair requires ordinary contained project-local skill roots/files, explicitly rejects non-directory/non-regular-file skill entries, validates recorded evidence before mutation, and records managed file form. Receipt-less clean staging retains unchanged legacy managed Claude symlinks while canonical sources remain active; receipt-backed split output inventories only successful projection actions. Unrecorded consumer root/workspace symlinks remain unowned across consecutive writes, including dangling consumer symlinks whose lexical link target differs from the canonical managed target, while unchanged recorded symlink evidence remains managed and canonical managed links still stale-clean after source removal. Legacy-untyped regular copies require unchanged hashes and canonical-source byte equality; typed regular copies use their unchanged recorded hash and file type as management evidence, retain file form, use staged canonical bytes only while a managed source still matches its recorded hash, otherwise refresh from current locally authored canonical bytes, and stale-clean when their scope disappears. Ownership-only manifest transitions independently drive write/check state while content drift arrays remain empty. The scaffold manifest no longer owns or hashes itself; every final owned path receives file-form metadata on write, including preserved context evidence whose hashes remain valid. Update and wiki-alignment staging directories are finalized on success and every typed failure. Final validation passed scaffold 47/47, CLI 354/354, focused CLI 76/76, the public schema contract 6/6 with 112 assertions across 51 schemas, both package typechecks, the 1038-module CLI build, focused formatting, and diff integrity. .agents/skills/autoreview/scripts/autoreview --mode local --stream-engine-output returned zero findings and judged the overall patch correct with confidence 0.87. CLI check remains blocked before linting by the pre-existing missing @typescript-eslint/utils required by @effect/eslint-plugin; the repo-wide build remains independently blocked outside this slice by missing NEXT_PUBLIC_SERVER_URL in apps/web.
• files edited/created: packages/scaffold/src/index.ts; packages/scaffold/test-fixtures/public-scaffold.json; apps/cli/src/context/compile-context-plan.ts; apps/cli/src/context/public-context-contract.test.ts; apps/cli/src/core/models.ts; apps/cli/src/data/scripts/sync-subagents.mjs; apps/cli/src/data/scripts/sync-subagents.test.ts; apps/cli/src/scaffold/output.ts; apps/cli/src/scaffold/stage.ts; apps/cli/src/scaffold/stage.test.ts; apps/cli/src/update/run.ts; apps/cli/src/update/run.test.ts; apps/cli/test-fixtures/public-output/managed-assets.json; this PLAN.md; IMPLEMENTATION-NOTES.md
• backlog_item_id: IP-317
• backlog_item_url: https://linear.app/devpunks/issue/IP-317/compile-context-once-and-project-it-truthfully
• relation_mode: native
• assigned_skills: [review-phase, autoreview, codebase-design, effect-authoring, effect-best-practices, improve-codebase-architecture, parallel-research, quality-types, simplify, tdd, turborepo]
• tdd_status: required
• tdd_target: Six accepted structured-review regressions prove canonical evidence survives update, manifest changes cannot diverge from the persisted plan, prospective wiki docs prompts are projected, pack-only agents compile, removed lifecycle hooks/configuration reconcile, and the shared managed-file schema accepts every emitted kind. Independent-rereview regressions prove hostile hook/plugin directory symlinks cannot escape action containment and the shared managed-kind schema/type is the only literal authority.
• red_command: bun run --cwd apps/cli test -- src/update/run.test.ts src/context/public-context-contract.test.ts src/data/scripts/sync-subagents.test.ts src/scaffold/stage.test.ts src/scaffold/run.test.ts && bun run --cwd packages/scaffold test -- src/public-scaffold-contract.test.ts
• expected_red_failure: Each new public-seam regression fails against the reviewed head for its specific accepted finding before its owning production seam changes.
• green_command: bun run --cwd packages/scaffold test && bun run --cwd apps/cli test && bun run --cwd packages/scaffold check-types && bun run --cwd apps/cli check-types && bun run test && git diff --check
• reason_not_testable:
• red_evidence: Six focused tracers failed before their owning production seam changed. The managed-kind fixture failed strict decode on context-plan; update check reported the persisted plan stale; pack-only subagent output had no skill references; monorepo stage output omitted the prospective wiki docs pack/prompt; manifest drift still produced adapter actions; and lifecycle removal retained old mirrors/config. The first full sync integration then failed 3/25, including the unchanged hostile Cursor config-leaf symlink test because reconciliation bypassed containment. Independent-rereview hook-directory RED failed 4/4 because symlinked Claude, Codex, Cursor, and OpenCode hook/plugin directories deleted the external formatter sentinel. Managed-kind authority RED failed 1/1 because update still declared local literals and the CLI model retained a local union.
• green_evidence: Each focused tracer passed after its minimal repair. Lifecycle/security GREEN rejects contained root symlinks, validates ordinary contained local-skill closure, and explicitly rejects FIFO or other non-directory/non-regular-file entries. It preserves consumer regular files and unrecorded root/workspace symlinks across consecutive updates, and preserves dangling consumer symlinks lexically while canonical managed dangling links remain stale-cleanable. It inventories unchanged legacy managed root/workspace symlinks only in receipt-less clean staging, excludes receipt-backed split-output omissions, and preserves legacy-untyped regular copies only with canonical-source byte evidence. The typed lifecycle uses unchanged recorded file/hash evidence, keeps file form, selects staged managed canonical bytes only when current canonical bytes remain unchanged, selects current bytes after a local canonical edit, reports truthful target changes, and stale-cleans after scope removal. A metadata-only consumer ownership transition applies the refreshed manifest with empty content-change/stale arrays; the normalized no-change control remains unapplied. Serialized ownership excludes the scaffold manifest itself, records a filesystem-derived file type for every other final owned path, and retains valid context evidence hashes. The corrupted-evidence tracer snapshots both staging prefixes and proves the Effect finalizer leaves no new update or wiki-alignment directory after failure; success and wiki-alignment guards remain green. The synthetic symlink-hash collision remains preserved. Final gates passed: scaffold 47/47; CLI 354/354; focused CLI 76/76; public schema contract 6/6 with 112 assertions across 51 schemas; both package typechecks; CLI build at 1038 modules; focused Oxfmt; and git diff --check. The final local autoreview returned zero findings and overall-correct confidence 0.87. The CLI lint wrapper and unrelated repo-wide web build blockers remain recorded above.
• codebase_design_notes: Canonical plan bytes remain the update authority. Manifest inputs are validated against persisted subagent-template semantics before any adapter action. Prospective docs scopes exist before the single compiler invocation. Pack expansion remains centralized in scaffold output. Lifecycle deletion/config reconciliation is one plan-scoped action per adapter; every config and hook/plugin mirror mutation crosses the shared lexical/realpath application boundary, and its trace does not invent a canonical contribution or scope. ScaffoldManagedFileKind is the single runtime and type authority for managed literals across scaffold and CLI update parsing.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

Testing Strategy

• Use vertical RED → GREEN slices. T1 establishes schema invariants; T2 proves compilation; T3 proves real consumer cutover before any projection work starts.
• Keep semantic context assertions one level above helpers. Compare repository scopes, packs, contribution identities/categories, provenance, compatibility, reference closure, and meaningful ordering.
• Keep downstream managed-output hashes byte-locked through the existing public context contract. Do not weaken byte fixtures to make the refactor pass.
• Apply one shared projection contract to stub and real adapters. Cover supported, degraded, unsupported, mixed partial, invalid input, adapter defect, application failure, deterministic replay, and traceability.
• Use run-owned temporary repositories for portable script/application tests. Record exact owned roots and remove only those roots.
• Use @effect/vitest for TypeScript tests and public exported/runtime seams. Avoid private-method assertions and module mocks.
• Finish with package tests/types/build, wiki checks, the comprehensive root behavior contract, git diff --check, and clean structured review.

Review Gates

1. Pre-implementation plan gate: readonly plan-reviewer verifies dependencies, disjoint scopes, RED targets, assigned skills, story coverage, and branch/base intent.
2. IP-325 gate after T3: semantic equality and downstream byte fixtures are green before T4 begins.
3. Projection-core gate after T5: shared mixed/error contract is green before adapter fan-out.
4. Adapter convergence gate after T8: all four matrices/adapters pass the same contract and the end-to-end receipt is truthful.
5. Docs gate after T9: private/internal ingest, routed navigation, root docs, and implementation notes are current.
6. Final gate T10: focused checks, comprehensive suite, findings-first review, structured autoreview, exact PR base, and unmerged/undeployed status all pass.

Risks and Mitigations

Backlog Sync

• No new backlog items are needed. IP-317 is the epic; IP-325 and IP-326 are the complete product-facing story set.
• Native hierarchy is correct: IP-325 and IP-326 are children of IP-317.
• Native internal order is correct: IP-325 blocks IP-326.
• IP-317 remains blocked by IP-330 in Linear, while accepted PR #76/IP-319 evidence satisfies the implementation readiness gate recorded in the spec.
• IP-317 blocks IP-346; IP-326 blocks IP-328. This plan does not alter those downstream relations.
• Planning intentionally performs no Linear mutation. Implementation closeout may update status/evidence only after the corresponding story gates pass.

Unresolved Questions

None. Exact symbol naming and capability-matrix version values are implementation tuning inside the locked schema and compatibility constraints; they are not product decisions.

Stop Condition

This artifact ends planning. Do not implement, commit, push, open a pull request, merge, deploy, or mutate backlog state from this planning run.