Implementation Notes

Summary

• T1 completed the neutral context-plan schema contract in packages/scaffold.
• T2 completed the pure repository context compiler in apps/cli.
• T3 completed setup/default-stage consumer cutover and the IP-325 public evidence gate.
• T4 completed the versioned harness capability and projection outcome schema contract.
• T5 completed the portable projection core, application boundary, and shared adapter contract.
• T6 and T7 completed all four independently reviewed harness adapter seams in one disjoint parallel wave.
• T8 completed consumer-side projection integration, durable truthful receipts, caller-visible projection status, failure containment, path safety, and the IP-326 acceptance gate.
• T9 ingested the proven T5-T8 flow, capability contract, shared-model ownership, operator response, navigation, and durable bookkeeping into the private wiki and root docs.

Execution Mode

• Sequential repair mode completed. Scoped workers repaired accepted T10 findings; parent validation and final autoreview are clean. T1-T10 are complete.

2026-07-19 Stack Checkpoint

• Before sync, every local branch was clean and matched its remote at the exact audited head: parent PR #76 dc0d90ef6e35c47b633583ba844643686591281c; PR #77 b1d3cd12571fd0e8b025a0278422c86c62e20762; PR #78 c297800266b9e7f1707a3f1c757798d3a6822e3b; PR #79 da8e0bea688bc6f6dcfeb33effd36365985f11aa; PR #80 efb92ec50ba4677f132d0c364e9e1218597d9dbd; PR #81 dfdd383f80762844fa38962559cebdcc1a130854; PR #82 0f431c083ddb073472d2adf9084d7e7c2ce99a33; PR #83 22fe8b1f16a0a5481c1690b1629ad4fc21a37350.
• stack status inferred the exact fan-out: #76 is based on main; #77-#83 are sibling children based on team/stefan/refactor-cli-architecture. No stack track exists.
• stack sync --dry-run preserved that fan-out and previewed rebasing #76, then each sibling onto the parent, updating #76-#83.
• The attempted stack sync failed while replaying parent commit 0e800522 (chore(scaffold): accept latest baseline). It created backup backup/stack-sync-2026-07-19T002137949Z-team/stefan/refactor-cli-architecture, auto-aborted the cherry-pick, restored the original parent, deleted the temporary replay, and saved the undo journal. The children were reported unchanged.
• After the failed sync, stack status still showed the exact fan-out. PRs #76-#83 remain open, draft, unmerged, and unclosed, with the correct bases and the exact head OIDs above unchanged.
• Constraints remained intact: no stack track, retargeting, linearization, manual rebase, force-push, or merge. PR #83 does not include sibling branches. Any convergence remains a separate explicit decision.

2026-07-18 T10 Structured-Autoreview Repair

• Fixed point: child 0a816fe8411a6d77d6c04c44fce418a4b2c7c486, parent dc0d90ef6e35c47b633583ba844643686591281c, draft/open/unmerged PR #77 with base team/stefan/refactor-cli-architecture.
• Codex CLI 0.144.5 completed the exact branch autoreview command. It accepted six findings: update preservation of canonical evidence; manifest/plan reconciliation; stage-created wiki docs projection; pack-only subagent resolution; lifecycle-hook/config removal reconciliation; and shared managed-kind schema coverage.
• RED/GREEN repair matrix:
  • Update preservation: the new write-update test first reported the canonical plan as stale; GREEN preserves the plan and receipt bytes and keeps both entries in the refreshed manifest.
  • Manifest/plan reconciliation: the new sync test first applied actions after the authored manifest diverged from the persisted plan; GREEN emits an InvalidHarnessProjectionError, zero adapter actions, and no consumer mutation.
  • Prospective wiki scope: the existing monorepo-shaped stage test first lacked the docs pack and scoped prompt; GREEN creates the wiki before compilation and projects the docs scope in the same run.
  • Pack-only agents: the new public-context test first rendered no skill references; GREEN resolves the agent's capability packs when explicit skills are absent.
  • Lifecycle removal: the new sync test first retained removed hook mirrors/config; GREEN appends one plan-scoped reconciliation action per adapter, removes absent managed hooks/config, and validates the config leaf before mutation.
  • Managed kinds: the public scaffold fixture first failed strict decode on context-plan; GREEN accepts both canonical context evidence kinds in the shared and update schemas.
• Integration initially failed 3/25 sync tests: two receipt expectations lacked the new reconciliation action, and the hostile Cursor config-leaf symlink test exposed an unsafe nested write. The reconciliation action now carries its config file through the existing realpath containment gate; the unchanged hostile test and the full sync suite pass 25/25.
• Final repair validation passed scaffold 44/44, CLI 314/314, both package typechecks, and the 1038-module CLI build. Focused Oxfmt and git diff --check pass. The package check wrappers remain blocked before linting by missing local Effect lint-plugin dependencies (@typescript-eslint/utils for CLI and @effect/eslint-plugin for scaffold). Independent rereview remains required; T10 is still in progress.

2026-07-18 T10 Independent-Rereview Repair

• Independent rereview accepted two findings: lifecycle-hook mirror deletion still used implicit adapter directories outside the action-declared containment boundary, and apps/cli/src/update/run.ts duplicated the shared managed-file-kind literals.
• Hook containment RED failed all four hostile adapter cases: symlinked .claude/hooks, .codex/hooks, .cursor/hooks, and .opencode/plugins directories deleted the external formatter sentinel. GREEN declares both managed mirror paths on each reconciliation action, resolves them through lexical and nearest-existing-ancestor realpath containment before mutation, preserves both external sentinels, and records the affected reconciliation action as HarnessApplicationFailureError. The unchanged hostile Cursor config-leaf regression remains green. Focused sync GREEN passed 29/29.
• Managed-kind authority RED failed the focused public contract because update still used a local Schema.Literal and ManagedFileKind remained a local union. GREEN composes ScaffoldManagedFileKind into the update manifest parser and aliases the CLI model type to the shared scaffold type. The focused contract passed 1/1; full public-context GREEN passed 5/5.
• Final worker validation passed scaffold 44/44, sync 29/29, CLI 319/319, both package typechecks, and the 1038-module CLI build. Focused Oxfmt and git diff --check pass. Independent rereview remains parent-owned; T10 is still in progress.

2026-07-19 T10 Lifecycle and Local-Skill Repair

• Review REDs proved that project-local skill roots could be contained symlinks, update evidence could be trusted after source mutation, Claude prompt ownership could be reclaimed after one consumer-preserving update, and never-managed regular Claude prompts could enter the manifest through broad directory inventory.
• GREEN requires an ordinary non-symlink directory for every project-local skill root and explicitly rejects every closure entry that is not an ordinary directory or regular file, including FIFOs. Update validates recorded evidence before mutation, keeps local skills project-owned, records managed file form, and inventories receipt-backed Claude prompts only from successful projection actions. Receipt-less clean staging retains unchanged legacy managed root/workspace symlinks while their canonical sources remain active. Split-output and unrecorded root/workspace consumer symlinks remain unowned across consecutive updates; only unchanged recorded symlink evidence remains managed. Legacy-untyped file copies require unchanged recorded hashes and canonical byte equality. Typed file copies use unchanged recorded hash/type evidence, retain file form across active updates, refresh from current authored or staged managed canonical bytes, and stale-clean once that scope disappears. Consumer replacements, synthetic symlink-hash collisions, and never-managed regular prompts remain unowned across arbitrary later updates. Ownership-only manifest transitions independently drive write/check state without reporting the consumer target as managed content drift. The scaffold manifest is excluded from its own serialized file/type ownership and comparison, while context-plan and receipt hashes remain validated.
• Focused public/update validation passed 76/76 (18 public-context and 58 update), full CLI passed 354/354, CLI typecheck passed, and the CLI build bundled 1038 modules. The lifecycle tracers prove dangling consumer Claude symlinks remain lexically intact and excluded from ownership, canonical managed dangling links remain stale-cleanable, unchanged typed copies refresh from independently changed canonical guidance without changing file form, locally edited managed canonical guidance remains authoritative over staged generated bytes, FIFO skill entries fail explicitly, and every final managed path receives filesystem-derived file-form metadata while preserved context hashes stay valid. Corrupted evidence no longer leaks a punks-update-* tree; one Effect.ensuring finalizer owns update and wiki-alignment staging across success and all failure exits. Focused Oxfmt and git diff --check passed. The repo-wide build is independently blocked by absent NEXT_PUBLIC_SERVER_URL in apps/web; CLI-local build is green.

2026-07-19 T10 Final Verification

• Final aggregate 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 Oxfmt, and git diff --check.
• .agents/skills/autoreview/scripts/autoreview --mode local --stream-engine-output returned zero findings and judged the overall patch correct with confidence 0.87.
• T10 is complete. No PHASE-HANDOFF, broader wiki closeout, commit, or push was produced by this evidence update.
• Known unrelated blockers remain: CLI check cannot resolve the pre-existing @typescript-eslint/utils required by @effect/eslint-plugin; repo-wide build cannot resolve apps/web NEXT_PUBLIC_SERVER_URL. CLI-local build and all scoped validation are green.

2026-07-18 Repair Checkpoint

• T3 keeps the encoded canonical plan intact when root/workspace AGENTS.md sources are absent. Each adapter now records a typed MissingCanonicalPromptWarning omission instead of losing the contribution before persistence. The manual withSubagentContributions compiler was deleted. Prompt blueprints reuse pure scope selection, leaving exactly one canonical compileContextPlan invocation with the real capability groups and template inputs.
• T5 rejects missing, empty, or non-string matrix version and adapter identity/version metadata before actions. Invalid metadata also fails an empty plan with a versioned synthetic trace instead of false success.
• T8 strictly validates raw consumer ContextPlan JSON, including excess fields and all nested identity/provenance/reference/order shapes, before adapters. JSON null now yields a durable failure receipt and nonzero exit. Action paths retain lexical checks and additionally resolve their nearest existing ancestor with realpath; symlinked parents and symlinked nested configuration leaves outside the repo fail before mutation while safe actions continue.
• TDD evidence: projection/script RED had 7 failures; public-context RED had 2 failures; the final Cursor config.path leaf-symlink RED failed 1/21. Repair GREEN passed the sync suite at 21/21, the standalone core at 19/19, full CLI at 308/308, CLI types, build (1038 modules), focused format, and diff integrity. The CLI check wrapper still hits the recorded pre-existing missing @typescript-eslint/utils peer dependency. T10 remains Planned and readonly.

2026-07-18 T10 Cleanup-Trace Repair

• Final review found that cleanupManagedAgents still deleted stale managed agent files outside applyProjection and before receipt persistence. A malformed plan could therefore delete managed output, and a cleanup filesystem failure could exit without durable typed evidence.
• Initial RED failed 2/22: invalid canonical input removed a managed sentinel, while a stale-agent cleanup error left no projection receipt. The first repair then failed a 1/23 zero-template regression because a valid empty plan left stale managed agents, and the public-schema RED failed 1/19 because no strict plan-scoped application trace existed.
• Cleanup is now one path-contained application action per adapter for every valid plan, including plans with zero templates. Its strict trace records the plan version, adapter and matrix versions, and cleanup operation without inventing a canonical contribution or scope. Invalid plans schedule no cleanup; successful stale deletion is receipt-visible; cleanup failure becomes HarnessApplicationFailureError; other adapters continue.
• GREEN passed package scaffold 44/44, the sync suite 23/23, focused sync/public/core contract 45/45, full CLI 310/310, both package typechecks, CLI build (1038 modules), focused Oxfmt, diff integrity, and the complete 15-task root behavior contract including 8/8 browser flows. An earlier root attempt's browser assertions passed but its known process-group cleanup guard failed; removing only that run's exact surviving processes and rerunning unchanged passed. The final root run passed directly.
• PR checkpoint before this uncommitted repair: local/remote child 7af72d13002a3687b8cba188873b49eef081f556; live parent dc0d90ef6e35c47b633583ba844643686591281c; PR #77 draft/open/unmerged with base team/stefan/refactor-cli-architecture. Structured autoreview remains blocked because Codex 0.139.0 cannot run its selected gpt-5.6-sol model. Independent rereview remains required before T10 completion.

Deviations From the Plan

• T8 made one necessary integration repair in the already accepted adapter files: the real compiler emits shared prompt scope id shared, while the adapters recognized only .agents. All four now treat both identities as the same canonical shared prompt scope. OpenCode's real formatter lifecycle projection also regained its mirror action so existing managed bytes remain exact. These changes did not expand capability semantics or begin T9.

Surprises and Decisions

• Effect Schema strips excess object fields by default. ContextPlan owns strict decode options so forbidden materialization and workflow fields fail decoding at any nested plan object instead of disappearing.
• The first RED attempt exited 127 because dependencies were not installed. After bun install --frozen-lockfile, the unchanged command passed while the requested test file was absent because Vitest ignored it. Neither run was accepted as RED. The public-seam tracer test then produced the recorded missing-contract failure.
• Review found that docs/README.md still listed only the pre-T1 scaffold contracts. Its package-ownership sentence now includes neutral ContextPlan schemas.
• T2 keeps project packs and subagent capability groups as separate compiler inputs. Subagent-template references come only from named capability groups, so changing selected project packs cannot silently redefine a template.
• Exact current workspace placement includes service only as a package-name signal, not a path segment, and recognizes @tanstack/query-persist-client-core.
• T2 keeps the existing baseline and skill catalog shape unchanged. A separate pre-resolved skill metadata input owns exact reference closure and compatibility; the effect-authoring fixture carries all six authored references plus Effect ^3.21.2, while unrelated contribution families carry explicit empty arrays only where no references or compatibility exist.
• The pure compiler uses local synchronous Error failures for unknown catalog references. This keeps invalid inputs visible without entering the typed error architecture owned by IP-320 or the consumer integration owned by T3.
• A typed test passes the real bundledBaseline directly to compileContextPlan with separate resolved metadata. Missing metadata for any selected skill is rejected, and no skill catalog or bundled baseline regeneration is required.
• Setup and default-stage compile once after final pack selection. The same in-memory plan is returned publicly and passed to output; output reads scope packs, resolved skill identities, hook identities, prompt meaning, and lint placement from that plan.
• The compiler input includes prompt scopes plus every detected manifest workspace. This keeps conditional existing wiki roots represented without fallback rediscovery during output.
• .devpunks/context-plan.json is schema-encoded semantic evidence and a managed context-plan asset. Its payload contains no path, filename, hash, mutation, or write-action fields. Existing managed fixture hashes stayed unchanged; the only new inventory entry is the evidence file.
• writeScaffoldOutput keeps a legacy non-persisting finalPacks call shape for the existing update path. That compatibility path uses the compiler for rendering but does not add context evidence to update reconciliation; IP-318 remains separate.
• Review correction moved default-stage wiki-target selection before compilation and supplies the prospective apps/wiki, app/wiki, or wiki scope to that one compile before any filesystem write.
• Review correction replaced the empty repository-subagents contribution with explicit per-agent template and capability-group inputs resolved from the authored/generated manifest blueprint. Output preserves the existing manifest bytes only after validating that every emitted agent identity and deduplicated skill closure matches the ContextPlan; no default semantic fallback remains.
• T4 requires exactly one capability row for each of the five contribution families. It models supported application, degraded application with a reason, and unsupported omission with a typed warning as distinct variants. Omission-only partial summaries are valid; failure summaries retain prior omissions alongside independent typed errors. Invalid projection, adapter defect, and application failure remain separate traceable error variants.
• T5 keeps project(adapter, contextPlan) pure and keeps filesystem effects behind applyProjection. The shared contract proves supported, degraded, unsupported, defect, failure, deterministic replay, traceability, and run-owned cleanup before any real adapter is accepted.
• T6 and T7 used disjoint adapter and fixture roots. Neither worker edited the shared core, the other adapter pair, the plan, or T8 integration files; the coordinator alone updated shared evidence after both independent reviews passed.
• Adapter fixtures are production/compiler shaped. Claude/Codex fixtures schema-decode repeated skills across root and workspace scopes, .agents/root/workspace prompts, both lifecycle hooks, four real tool IDs, and two distinct subagent contributions. Cursor/OpenCode fixtures compile through compileContextPlan and assert exact equality with their saved context plans. One common compiler-generated plan also runs through all four adapters so pair-local fixture counts cannot hide scope or target drift.
• Codex no longer invents a standalone .codex/agents skill-registration action. Canonical skills remain targetless .agents/skills/<id> native intents, while exact [[skills.config]]-compatible paths are carried only by the specific subagent TOML render that references them. Claude represents the existing shared .claude/skills compatibility mirror without claiming per-scope ownership.
• Each Claude/Codex subagent contribution now yields one template-specific render intent with its canonical template id, source selector, filename, unique target, native format, and exact skill closure. This removed the reviewed N-copies-of-the-whole-manifest collision.
• Shared and scoped prompt mechanisms match current harness behavior. Canonical shared scope id .agents mirrors .agents/AGENTS.md to Claude, Codex, and OpenCode global prompt targets; Cursor consumes the same canonical file natively and records an explicit self-target. Claude root/workspace prompts use sibling CLAUDE.md mirrors, while Codex, Cursor, and OpenCode consume native scoped AGENTS.md files.
• T7 review removed a fabricated OpenCode tool identity and projects formatting through the real lifecycle formatter/scaffold-update mechanism instead. Cursor keeps canonical shared prompt identity at .agents/AGENTS.md; OpenCode mirrors it to .opencode/AGENTS.md. Production compiler fixtures include Effect-pack and effect-authoring resolved skill metadata, so native skill actions and all four typed real-tool omissions are fixture-proved without adapter defects.
• All four matrices expose exactly five versioned rows. Real operator tool IDs (agent-browser, opensrc, portless, skills) remain explicit typed omissions with partial outcomes; supported projections continue. Capability and omission reasons stay fixture locked.
• Common-plan convergence found no write-target collision inside any adapter: Claude produced 8 actions/7 targets, Codex 8/6, Cursor 6/5, and OpenCode 6/5. The same compiler-generated plan preserved canonical .agents prompt identity across every adapter; each returned exactly four typed tool omissions and a HarnessProjectionPartial summary.
• sync-subagents.mjs now loads the canonical .devpunks/context-plan.json and applies the four accepted adapters through the shared core. Legacy materialization runs only when that file is absent. A present malformed JSON payload, invalid shape, or scopes: null produces per-adapter InvalidHarnessProjectionError evidence, a durable failure receipt, and a nonzero exit.
• .devpunks/harness-projection-receipt.json is deterministic evidence, not desired state. It records context-plan version, aggregate status, adapter and matrix versions, canonical traces, actions, warnings, omissions, and failures. Setup and default-stage results expose the receipt path and success, partial, or failure status.
• Supported actions continue independently. Missing canonical sources and injected write failures become HarnessApplicationFailureError for the affected action. Consumer-owned regular prompt files are preserved as explicit HarnessApplicationOmission entries with PreservedConsumerPromptWarning; they are removed from both the applied-action count and the mutation set.
• Scaffold output persists only projectable scoped-prompt contributions: canonical shared guidance always remains, while optional root/workspace prompts remain only when their source exists. This keeps the persisted plan identical to the caller result without claiming a projection source that setup did not materialize.
• Final review found that a malicious scope id could send adapter paths outside the consumer repository. Every projected source, target, file, nativePath, and canonicalPath now receives POSIX/Windows absolute-path, portable .. traversal, and resolved repo-root containment checks before action mutation. The unsafe action is retained long enough for typed failure evidence while independent safe actions continue.
• The direct path-safety RED used scope ../ip317-path-escape: before repair the script exited zero and created /tmp/ip317-path-escape/CLAUDE.md; after repair it exits nonzero with a truthful failure receipt, creates no external target, and still renders the safe Codex subagent. The review-owned temp directory contained only matching AGENTS.md and CLAUDE.md files with outside fixture source; those exact artifacts were removed after provenance verification and the path remained absent after all gates.
• T9's scoped routed-learning scan found no existing context-plan or capability-projection learning artifact to update, consolidate, replace, or mark stale. The new context-plan flow, capability concept, shared-model cross-links, and operator runbook are the future-use hooks; unrelated raw fragments did not justify a separate learning page.

Sanity Checks

Acceptance Criteria Status

Manual Review Checklist

Remaining Work

• T10 is complete. PHASE-HANDOFF and broader wiki closeout remain intentionally outside this evidence-only update.