Implementation Notes

Summary

The canonical review contract now rejects malformed identities, bounds, timestamps, frontmatter, containment evidence, and retained report bytes. Finding-owned routes derive one aggregate handoff, including a durable delivery-owned debt follow-up. Harness packages the immutable shared source and aligns dynamic, bundled, and isolated-consumer subagent activation with final ## Skills row triggers and installed SKILL.md authority.

Deviations From the Plan

The first T2 RED command could not start because the isolated Harness worktree lacked installed dependencies. bun install --frozen-lockfile restored the locked environment; the unchanged command then produced the required three behavioral failures before any production edit.
T3's managed-fixture check failed as expected after semantic and generated-source changes. T4 used the supported fixture generator and the independent check now passes.
The first frozen review found four actionable gaps: null and empty standalone review scopes, lost secondary repair routing after debt capture, and generated prompt/table drift. Each returned to its owning task, reproduced RED, and passed its focused suite before this replacement snapshot was prepared.
Later frozen reviews found capture-first state-table drift, iterable standalone scopes, and a fresh-wiki seed that bypassed the scoped Skills renderer. Each was reproduced at its public boundary and repaired before the final snapshot.
Structured closeout also found a leaked lifecycle phase row and unrepresentable docs_ingest/closeout cold-resume states. Focused regressions now cover both seams.
Final review then found missing router branches for those durable successors and obsolete Skills-table vocabulary in live update producers. Both public outputs now agree with the retained state and scoped activation contracts.
Canonical planning/setup consumers also carried the retired table vocabulary. Their final ## Skills contract now matches every generated and post-command producer.

Surprises and Decisions

The two existing GitHub issues are the accepted implementation records. They link the immutable spec, so no duplicate Linear epic/story projection was created.
The managed inventory stayed stable while 80 hashes changed across the synchronized skill, subagent, and derived harness outputs.
The immutable shared tag and exact sync receipt both resolve to 684f98dff76ac94ad3db2eb1f74230cb9910e1ad.

Sanity Checks

Check	Result	Evidence
Shared focused contract	Pass	`node --test tests/review-phase-graph.contract.test.mjs` in the shared worktree passed 40/40.
Shared full suite	Pass	`node --test tests/*.test.mjs` in the shared worktree passed 119/119.
Harness focused contracts	Pass	Content, bundled manifest, isolated scaffold, and sync tests passed 67/67.
CLI types	Pass	`bun run --cwd apps/cli check-types` exited 0.
Exact shared parity	Pass	`diff -qr /private/tmp/hi-review-contract-skills/skills apps/cli/skills` exited 0.
Managed fixtures	Pass	`bun run --cwd apps/cli fixtures:check:managed-assets` passed 1/1.
CLI outer check	Pass	`bun run --cwd apps/cli check` passed Oxlint, Oxfmt, and managed-fixture verification.
Wiki projection	Pass	`bun run --cwd apps/wiki check:content` reported current content.
Diff hygiene	Pass	`git diff --check` exited 0.
Frozen reviews	Pass	Exact-base Standards and Spec axes reported no findings; structured autoreview has no accepted actionable finding.

Skill Application Evidence

Task	Skill	Status	How/where
T1	`writing-for-agents`	applied	Canonical instructions expose explicit route, retention, debt-resume, and source-only provenance branches.
T1	`tdd`	applied	Sixteen public behavior gaps were observed RED and made GREEN one slice at a time.
T1	`codebase-design`	applied	`resolvedReportBytes` is explicit boundary input; `deriveReviewRouting` is the single route seam.
T1	`quality-types`	applied	Empty identities/sets/scopes, invalid instants/routes, non-boolean containment, and mismatched bytes fail.
T1	`simplify`	applied	Post-GREEN route validation and precedence duplication was removed within assigned scope.
T2	`writing-for-agents`	applied	Generated docs/workspace prompts use exact-invocation `## Skills` rows and installed `SKILL.md` targets.
T2	`tdd`	applied	Initial and frozen-review failures preceded their production edits; the focused suite passed 57/57.
T2	`codebase-design`	applied	Dynamic and bundled seams remain separate; shared semantics use tests, not a new abstraction.
T2	`simplify`	applied	Only obsolete instruction lines changed; isolated readback reuses one manifest value.
T3	`tdd`	applied	Default selection failed on the old pin before production constants changed, then passed 9/9.
T3	`codebase-design`	applied	Existing `resolveRepositorySelection` and fail-closed expected-commit seam were preserved.
T3	`repo-asset-management`	applied	Supported exact-tag sync retained final source identity; receipt and full-tree parity prove ownership.
T4	`writing-for-agents`	applied	Runbook uses explicit branches and points detailed behavior to installed review, delivery, and skill bodies.
T4	`repo-asset-management`	applied	Supported fixture/wiki generators retained exact branch, commit, tag, digest, and stable inventory provenance.
T4	`simplify`	applied	Review invariants are co-located in three concise paragraphs without duplicating installed workflows.
T5	`writing-for-agents`	applied	Final notes co-locate exact validation, criterion evidence, deviations, and the concrete manual checklist.
T5	`review`	applied	Independent Standards and Spec axes reviewed the exact frozen base/head diff and reported no findings.
T5	`autoreview`	applied	Accepted findings were repaired; the remaining suggestion conflicted with the installed-description authority.
T5	`simplify`	applied	Changed production, tests, generated assets, and docs were inspected; no concrete simplification issue remains.

Acceptance Criteria Status

Criterion	Status	Evidence
AC-001	Met	Focused contract test rejects an empty delivery inclusive scope.
AC-002	Met	Frontmatter uses a null-prototype record and rejects `__proto__`, `constructor`, and `prototype`; the mutation regression passes.
AC-003	Met	Focused contract test rejects an empty governing-source set.
AC-004	Met	Timestamp normalization validates a round-trippable UTC instant; invalid calendar and range cases fail.
AC-005	Met	Delivery lineage and retained-pass validation reject empty delivery-goal identity.
AC-006	Met	Retained ref containment accepts only boolean `true`.
AC-007	Met	Retention requires exact equality between local report bytes and bytes resolved from the named commit/path.
AC-008	Met	Every finding validates one `return_route`; `deriveReviewRouting` owns precedence and contradictory aggregate routing fails.
AC-009	Met	Route tests cover empty closeout, docs-only ingest, debt-only, and mixed higher-priority debt-secondary results.
AC-010	Met	Delivery handoff, router, review phase, and state graph represent idempotent `debt_follow_up` capture and resume without implementing debt.
AC-011	Met	Installed authoring handoff names omitted source tests without suite counts or packaged-test claims.
AC-012	Met	Dynamic and bundled manifests require matching final `## Skills` rows, disclose installed `SKILL.md`, and exclude both obsolete labels.
AC-013	Met	Immutable shared source and packaged skills have full byte parity; dynamic, bundled, and isolated-consumer assertions pass.

Manual Review Checklist

Area	Command	Expected result
Canonical review contract	`cd /private/tmp/hi-review-contract-skills && node --test tests/review-phase-graph.contract.test.mjs && node --test tests/*.test.mjs`	40 focused and 119 full shared tests pass.
Harness consumer contract	`bun run --cwd apps/cli test src/content/content.test.ts src/data/subagents/manifest.test.ts src/scaffold/run.test.ts src/scripts/sync-skills-repo.test.ts`	67 tests pass, including dynamic, bundled, isolated-consumer, and pin behavior.
Packaged-source integrity	`diff -qr /private/tmp/hi-review-contract-skills/skills apps/cli/skills`	No output and exit 0.
Generated asset integrity	`bun run --cwd apps/cli fixtures:check:managed-assets`	One managed public-contract test passes.
Repository checks	`bun run --cwd apps/cli check && bun run --cwd apps/wiki check:content && git diff --check`	CLI lint/format/fixtures pass, wiki content is current, and no whitespace errors remain.
Retained source identity	Inspect `apps/cli/.devpunks-cache/skills-sync.json`.	Qualified tag `refs/tags/sync/review-contract-handoff-consistency-684f98dff76a` and exact commit `684f98dff76ac94ad3db2eb1f74230cb9910e1ad`.

Remaining Work

No implementation work remains. PR #131 is open against team/stefan/scaffold-skill-operator-followups and the stack is synchronized bottom-up. After the parent merges, rebase this child onto main and retarget PR #131 to main.

Review Contract and Handoff Consistency Implementation Notes