Spec: Review Contract and Handoff Consistency

Context

Resolved review threads exposed eight ways the public review validator can accept evidence that does not prove a real review, plus three contradictions in distributed handoff and activation guidance. These defects weaken the boundary between immutable review evidence, deterministic delivery routing, and the next agent's resume state.

The repair must originate in each owning source. Reusable review and delivery skills change in wearedevpunks-skills first. Harness then synchronizes that exact source and updates its own generated subagent manifest contract. Managed consumer snapshots are evidence, not authority.

Non-Goals

• Infer return routes from finding prose, lens names, or severity alone.
• Treat another caller-supplied hash as independent proof of committed report bytes.
• Rewrite retained review reports after their commit is created.
• Hand-edit active .agents projections or pre-existing-skill snapshots.
• Restore historical test counts or test-path claims in installed handoff guidance.
• Publish a baseline or npm package without the normal release authority and gates.

User Stories

US-001: Reject meaningless review identities and bounds

As a delivery operator, I want review targets, sources, timestamps, and delivery lineage to prove a real bounded review so that empty or impossible identities cannot consume a review ordinal.

US-002: Bind retained evidence to the claimed commit

As a reviewer, I want the validator to compare local report bytes with bytes read from the claimed commit and path so that retention evidence cannot describe different content.

US-003: Derive routing from structured findings

As the next delivery phase, I want each finding to declare one machine-readable return route and the report route to be derived from those declarations so that prose and aggregate routing cannot contradict each other.

US-004: Resume debt follow-up deterministically

As a delivery agent, I want debt_follow_up represented in durable handoff state and handled by the delivery router so that a valid review result cannot fall through.

US-005: Receive truthful handoff and skill activation guidance

As an installed agent, I want distributed review evidence to avoid unreproducible source test claims and generated manifests to use the current Skills trigger contract.

Acceptance Criteria

• AC-001: Delivery review normalization rejects an empty inclusive scope.
  • Covers: US-001
• AC-002: Frontmatter parsing cannot mutate object prototypes, and prototype-sensitive keys are rejected as malformed report frontmatter.
  • Covers: US-001
• AC-003: Governing-source normalization rejects an empty source set.
  • Covers: US-001
• AC-004: Review timestamp normalization rejects calendar-invalid or out-of-range UTC timestamps, not only strings with the expected shape.
  • Covers: US-001
• AC-005: Delivery lineage creation and retained-report validation reject an empty delivery-goal identity.
  • Covers: US-001
• AC-006: Retention validation accepts ref containment only when the value is boolean true.
  • Covers: US-002
• AC-007: Retention validation requires exact byte equality between the local report and bytes resolved from reportCommitSha:reportPath; local hash equality alone is insufficient.
  • Covers: US-002
• AC-008: Every non-empty finding carries one validated return-route classification. The report's primary and secondary routing values are derived centrally from the complete finding set using one documented precedence order; a contradictory supplied aggregate route is rejected.
  • Covers: US-003
• AC-009: A finding-free report derives closeout; documentation-only findings derive docs_ingest; broader debt remains a durable secondary follow-up when a higher-priority repair route is also present.
  • Covers: US-003
• AC-010: debt_follow_up is a valid durable handoff state with an explicit delivery resume branch. Delivery's review handoff handler records the broad-architecture finding once in a goal/spec-linked debt artifact keyed by retained report and stable finding ID, then continues to docs_ingest or closeout without implementing unaccepted debt.
  • Covers: US-004
• AC-011: Installed review authoring handoff guidance states reproducible contract seams without historical source-repository suite counts or claims that packaged tests exist.
  • Covers: US-005
• AC-012: Both dynamic and bundled subagent manifest guidance read the current ## Skills table, treat a matching row trigger as mandatory, and retain progressive disclosure to the selected installed SKILL.md body. The guidance excludes the stale Primary skills here and What / when labels.
  • Covers: US-005
• AC-013: The synchronized Harness review and delivery skill files are byte-identical to the canonical files at the pinned shared commit. Dynamic and bundled manifest outputs both satisfy AC-012, and an isolated candidate consumer receives those same semantics.
  • Covers: US-001, US-002, US-003, US-004, US-005

Constraints

• Apply writing-for-agents to every AI-context Markdown change; apply skill mechanics when changing skill instructions.
• Edit reusable skill content in wearedevpunks-skills, push an immutable ref, then run the supported exact-ref Harness synchronization.
• Keep the Harness change stacked on team/stefan/scaffold-skill-operator-followups until that parent merges; then rebase and retarget bottom-up.
• Preserve the dirty detached root checkout and inherited managed-scaffold drift.
• Capture focused public-contract RED evidence before each behavior change and retain the smallest fixture updates produced by supported generators.

Dependency Readiness

Ready.

• Harness parent PR #127 is retained on team/stefan/scaffold-skill-operator-followups at 18ec41b0.
• This work uses clean branch team/stefan/review-contract-handoff-consistency from that exact parent head.
• Shared-skill parent authority for the preceding stack is immutable commit 408746ad5fdf10d75513cd1b63c71c6f22fa7fb7 and tag sync/scaffold-skill-followups-408746ad5fdf.
• Issues #129 and #130 contain the accepted defect inventory and source review evidence.

Branch/Base Intent

• Harness parent/base: team/stefan/scaffold-skill-operator-followups.
• Harness child: team/stefan/review-contract-handoff-consistency.
• The child PR remains based on the parent branch until PR #127 merges, then is rebased onto the parent's new base and retargeted in stack order.
• Shared skills use a dedicated team/stefan/* branch from the preceding immutable shared-skill commit; Harness sync pins a new immutable tag at its pushed head.

Accepted Technical Decisions

• Compare exact resolved commit-tree bytes with local report bytes at the validator boundary. A second asserted digest does not satisfy retention proof.
• Add explicit finding return-route classification and derive aggregate routing through one public helper and precedence contract.
• Reject prototype-sensitive frontmatter keys without permitting prototype mutation.
• Represent debt follow-up in durable state and resume through delivery's review handoff handler for idempotent artifact capture rather than inventing a parallel implementation path.
• Keep installed skill bodies as semantic authority; generated activation text names the stable Skills table and row-trigger branch without coupling to a column label.

Accepted Testing Decisions

• Add one focused public RED for each of the eight validator gaps before implementation.
• Exercise report-byte binding with different local and commit-resolved bytes while all other retention evidence remains valid.
• Exercise route derivation with empty, single-route, mixed-priority, debt-secondary, and contradictory aggregate cases.
• Assert handoff semantics instead of historical file counts.
• Assert the dynamic renderer and bundled manifest fallback against the same current activation vocabulary, then read back an isolated generated consumer.
• Verify exact shared-source/package parity after synchronization and update managed fixture identities only through supported commands.

Verification Seams

• Review contract seam: canonical Node contract tests and retained-report mutation fixtures.
• Routing seam: structured findings to derived aggregate route and durable handoff state.
• Shared-source seam: exact immutable ref, synchronization receipt, and byte parity.
• Manifest seam: dynamic renderer, bundled fallback, generator output, and consumer readback.
• Delivery seam: focused CLI checks, wiki content checks, formatter checks, and frozen diff review.

Parked Decisions

• Retrofitting old retained reports with the new finding schema. Owner: Harness maintainers. Resume trigger: a migration requirement for historical report ingestion.
• Publishing a stable baseline or npm release. Owner: Stefan. Resume trigger: explicit release authorization after the normal candidate gates are available.

Decision Log