docs(unic-pr-review): ratify spawn-gating parity contract (ADR-0008 amendment + PRD elevation)

[orioltf]

What to build

Ratify — as documents of record — the spawn-gating parity decisions reached in the PR #5612 comparison (unic-pr-review v2.1.2 vs pr-review v1.4.0). This is the contract every spawn-gating slice cites; it lands before implementation.

The decision: unic-pr-review's Review Aspect spawn-gating becomes content-aware for the comment / errors / types gates, matching pr-review-toolkit's semantic gating, via deterministic diff-parsing (Y-det) biased toward spawning on ambiguity. The deterministic, unit-testable classifier stays — path classification remains the fast path; only the three semantic gates additionally read the diff.

Two records to update:

• Amend ADR-0008 (currently "a path/extension heuristic, not diff-content inspection") to permit content-gated spawning for the comment/errors/types gates, keeping the deterministic classifier. This resolves the existing three-way contradiction (PRD :203 says "changed-files list + a small content sample" → ADR-0008 says no content → code is path-only).
• PRD edit: realign the analyser description with the original "content sample" intent, and elevate :229's "loosely inspired by pr-review-toolkit" to a documented behavioural-parity contract for the code-analysis aspects — preserving the clean-slate doctrine (no code/prompt copying from apps/claude-code/pr-review/).

Acceptance criteria

• ADR-0008 amended: records content-gated Y-det spawning for the comment/errors/types gates, the bias-toward-spawn rationale, and that path classification stays the fast path.
• ADR-0008 notes the errors gate as the first Y-llm-promotion candidate if deterministic detection proves too noisy/blind.
• PRD updated: analyser described as content-aware (consistent with the "content sample" line); toolkit parity stated as a contract for code-analysis behaviour, not "loosely inspired".
• No contradiction remains between the PRD, ADR-0008, and the intended analyser behaviour.
• Wording reviewed and approved by the maintainer on the PR (HITL — decisions are locked, exact text needs sign-off).

Blocked by

None - can start immediately.

[orioltf]

✅ Issue Resolution Report

PR: #219 (#219)
Status: COMPLETE — awaiting maintainer review/sign-off

---

Summary

Docs-only change ratifying the Y-det hybrid spawn-gating parity contract. The three-way contradiction between PRD :203 ("content sample"), ADR-0008 ("path/extension heuristic, not diff-content inspection"), and the path-only changed-file-analyser.mjs implementation is fully resolved. A self-fix pass addressed all 4 LOW-severity review findings.

---

Changes Made

File	Change
docs/adr/0008-conditional-sub-agent-spawning.md	Status line amended; forward-reference added to Decision section; new "Content-gated spawning for semantic gates" amendment section; Spawn Table †-annotated for the 3 affected rows
docs/issues/unic-pr-review/PRD.md	:203 expanded to name the 3 content-aware semantic gates; :229 elevated from "loosely inspired by" to behavioural-parity contract
CONTEXT.md	Spawn Set glossary extended with content-aware sampling note

---

Validation

✅ Type check (0 errors, 9 packages) | ✅ Lint (Biome + Prettier, 0 errors) | ✅ Tests (1165 passed, 0 failed)

---

Review & Self-Fix

• 4 findings (all LOW — no CRITICAL/HIGH/MEDIUM)
• 3 fixed inline: Spawn Table stale header + amendment pointers, CONTEXT.md Spawn Set definition, PRD :229 "match" → "approximate"
• 1 deferred: Y-det implementation guide (correctly out of scope — tracked by feat(unic-pr-review): content-aware comment gate + diff-to-analyser plumbing #213–feat(unic-pr-review): content-aware types gate for type-design-analyzer #215)

---

Unaddressed Items

Finding	Severity	Reason
Y-det gate implementation guide (regex fixtures + diff-hunk parsing)	LOW	Out of scope for doc-ratification PR; tracked by implementation issues #213–#215

---

Suggested Follow-up Issues

1. Y-det gate implementation guide (P2) — Document regex fixture patterns and diff-hunk parsing approach for changed-file-analyser.mjs; scoped to feat(unic-pr-review): content-aware comment gate + diff-to-analyser plumbing #213–feat(unic-pr-review): content-aware types gate for type-design-analyzer #215 implementation work.

---

Resolved by Archon workflow 90d7ce3479271d9dae8e3e66712383a0