@haposoft/cafekit 0.16.0-rc.3 → 0.16.0-rc.5

package/src/claude/skills/specs/references/review.md

@@ -1,291 +1,243 @@
-# Spec Review (Red Team + Validate)
+# Whole-spec semantic review v2.1
 
 ## Purpose
 
-Review a spec before implementation. The system auto-decides the review depth based on spec complexity — from lightweight validation interview to full adversarial red team assault.
-
-## Spec Resolution
-
-1. If `<feature>` argument provided → use `specs/<feature>/`
-2. If not → check active spec (spec with `in_progress` status; accept legacy `in-progress` when reading existing files)
-3. If nothing found → ask user to specify path
-
-## Deterministic Validator Gate (MANDATORY)
-
-This gate is the hard source of truth for `hapo:specs --validate`. LLM red-team tables and markdown validation reports are advisory until this script passes.
-
-After resolving the spec path, run:
-
-```bash
-node .claude/scripts/validate-spec-output.cjs specs/<feature>
-```
-
-Required behavior:
-1. Run the validator once before the final PASS decision. If it fails, copy the exact failing categories into the validation findings/blockers and fix the physical spec artifacts.
-2. Red Team and Validate may continue while fixing issues, but they cannot approve the spec while validator errors remain.
-3. Run the validator again after every accepted Red Team / Validate fix set and before any final verdict.
-4. The final report MUST include the validator command and the final PASS/FAIL result.
-5. If the validator exits non-zero, final verdict is **FAIL / BLOCKED**, `validation.status` MUST NOT become `completed`, `ready_for_implementation` MUST remain `false`, and the output MUST NOT suggest `/hapo:develop`.
-6. A markdown checklist, manual QA table, or "all required sections present" claim cannot override validator failure.
-7. For specs with 5+ task files, a pre-review validator PASS only proves artifact shape. It does not mean implementation can start until Red Team + Validate finish, accepted fixes are propagated, and `spec.json.validation.status` is written as `completed`.
-
-## Auto-Decision: When to Red Team vs Validate
-
-The system evaluates the spec and picks the appropriate review mode:
-
-| Signal | Mode | Rationale |
-|---|---|---|
-| < 3 task files, no security/perf concerns | **Validate only** | Lightweight interview is sufficient |
-| 3-4 task files, medium complexity | **Validate only** | Interview catches most issues |
-| >= 5 task files | **Red Team → then Validate** | Complex enough to warrant adversarial review |
-| Keywords: "auth", "security", "payment", "migration", "database schema" | **Red Team → then Validate** | High-risk areas need hostile reviewers |
-| Keywords: "refactor", "architecture", "breaking change" | **Red Team → then Validate** | Structural changes need stress testing |
-| User says "quick review" or "just validate" | **Validate only** | Respect user's explicit intent |
-| User says "tear it apart" or "find flaws" | **Red Team only** | Respect user's explicit intent |
-
-**Important:** When both modes run, Red Team ALWAYS runs BEFORE Validate because:
-1. Red Team may change the spec (added risks, removed sections)
-2. Validate should confirm the FINAL spec, not a pre-review draft
-
-## Guardrails (NON-NEGOTIABLE)
-
-These rules override any self-reasoning or optimization the system may attempt:
-
-1. **No self-override of auto-decision.** If the table above says "Red Team → then Validate", you MUST run Red Team. You CANNOT skip it because:
-   - A `code-auditor` previously reviewed the spec (code review ≠ spec review)
-   - The spec "looks good" to you
-   - You want to "save time"
-   - Only the USER can downgrade the mode by explicitly saying "just validate" or "skip red team"
-2. **No implementation code files.** This workflow produces ONLY `.md` files. If a finding requires a new shared module or config file, describe it inside the relevant `task-*.md` file. Do NOT create `.ts`, `.js`, `.py`, or any source code file.
-3. **Findings must use the exact format** defined in Part A Step 5 below. No shortened or custom formats.
-4. **Apply YAGNI to fixes.** When user says "configure later" or "decide later", add a single note to the task file. Do NOT generate multiple concrete implementations (e.g., 4 provider files when user only asked for abstraction).
-5. **No false completion.** You MUST NOT set `validation.status = "completed"` or `ready_for_implementation = true` until a reconciliation audit proves the accepted findings and validation decisions are reflected in the physical spec artifacts.
-6. **Provider drift is a real defect.** If the scope changed away from Claude/Anthropic, stale strings like `Claude API`, `Haiku`, or `haiku_reachable` in `requirements.md`, `design.md`, or `tasks/*.md` are validation failures. `research.md` may mention them only as historical comparison.
-7. **Implementation-facing propagation is mandatory.** A decision that affects implementation is NOT considered applied if it only appears in `Risk Assessment`, `validate-log.md`, or `red-team-report.md`. It must update at least one of: `requirements.md`, `Canonical Contracts & Invariants`, `Context`, `Steps`, `Requirements`, `Completion Criteria`, or `Evidence`.
-8. **CafeKit command dialect only.** Validation output MUST use `/hapo:develop <feature>` as the implementation handoff. Never mention `/sdd:execute-spec`, `/sdd:*`, `/work`, `/code`, `/specs <feature> --approve`, `/hapo:specs <feature> --approve`, or non-CafeKit aliases.
-9. **CafeKit task filename convention only.** Task files MUST use `tasks/task-R{N}-{SEQ}-<slug>.md` with two-digit `SEQ` (for example `tasks/task-R0-01-project-scaffolding.md`). Files like `tasks/R0-1-project-scaffolding.md` are legacy/foreign format; rename them and update `spec.json.task_files`, `spec.json.task_registry`, and dependency references before passing validation.
-10. **Deterministic validator is mandatory.** The final validation verdict MUST be derived from `node .claude/scripts/validate-spec-output.cjs specs/<feature>`. If that command fails, report FAIL/BLOCKED and list the script output. Do NOT report PASS.
-
----
-
-## Part A: Red Team Review (Adversarial)
-
-### 8-Step Workflow
-
-#### Step 1: Read Entire Spec
-- `spec.json` — metadata and scope
-- `requirements.md` — technical requirements
-- `design.md` — architectural design
-- `tasks/task-*.md` — all task files
-
-#### Step 2: Determine Reviewer Count
-
-| Task file count | Reviewers | Lenses |
-|---|---|---|
-| 1-2 | 2 | Security + Assumption Destroyer |
-| 3-5 | 3 | + Failure Mode Analyst |
-| 6+ | 4 | + Scope & Complexity Critic (all) |
-
-#### Step 3: Assign Analysis Lenses
-
-| Reviewer | Lens | Focus |
-|---|---|---|
-| **Security Adversary** | Attacker mindset | Auth bypass, injection, data exposure, privilege escalation, OWASP Top 10 |
-| **Failure Mode Analyst** | Murphy's Law | Race conditions, data loss, cascading failures, recovery gaps, rollback holes |
-| **Assumption Destroyer** | Skeptic | Unstated dependencies, false claims, missing error paths, scale assumptions |
-| **Scope & Complexity Critic** | YAGNI enforcer | Over-engineering, premature abstraction, scope creep, gold plating |
-
-#### Step 4: Spawn Reviewers in Parallel
-Each reviewer receives:
-- Their specific lens and persona
-- Spec file paths to read directly
-- Instructions: report findings only when backed by concrete citations
-
-**Reviewer instructions:**
+Review the spec as one consistency graph. A structural validator exit 0 proves
+only implemented structural checks; it does not prove semantic completeness,
+grounding, product correctness, negative paths, or executable behavior.
+
+## Resolve and inventory
+
+1. Resolve the exact spec path; ambiguous active specs fail closed.
+2. Read final physical `spec.json`, `requirements.md`, `design.md`, optional
+   `research.md`, every task, and the machine-recorded semantic-review state.
+3. Confirm the physical artifact set matches `planning_depth` and its justified
+   optional gates:
+   - `None`: no durable spec;
+   - `Compact`: three-file core plus an optional task bundle/registry only when
+     ownership, dependency, durable transition, separate proof, or parallel
+     coordination activates the task gate;
+   - `Full`: the same three-file core plus only justified optional research,
+     task, or complex-task-graph phase metadata. Full depth
+     alone does not justify any optional artifact.
+4. Reject `feature-receipt.md` in spec authoring. It belongs to execution
+   closeout only.
+
+## Consistency graph
+
+Build and inspect these edges:
+
+```text
+scope_lock
+  -> outcomes/non-goals
+  -> RN.M acceptance
+  -> design boundary + typed anchors
+  -> named contracts/invariants
+  -> conditional task owners/consumers
+  -> verification + negative paths
+  -> technical readiness
 ```
-You are a hostile reviewer. Your job is to DESTROY this spec.
-Adopt the {LENS_NAME} perspective. Find every flaw you can.
-
-Rules:
-- Be specific: cite exact task/section where flaw lives
-- Be concrete: describe failure scenario, not just "could be a problem"
-- Rate severity: Critical (blocks success) | High (significant risk) | Medium (notable concern)
-- Skip trivial observations (style, naming, formatting)
-- No praise. No "overall looks good". Only evidence-backed findings.
-- Quality over quantity; do not pad to a count.
-```
-
-#### Step 5: Collect → Deduplicate → Cap
-1. Gather all findings from all reviewers
-2. Remove duplicate or overlapping findings
-3. Sort by severity: Critical → High → Medium
-4. Cap at 15 findings maximum
-
-#### Step 5.5: Evidence Filter (MANDATORY — auto-reject before merit)
-Before adjudicating, drop any finding whose `Location`/`Evidence` does not point at a concrete spot in the spec: a task/section name (`task-R2-01... §Steps`) or a verbatim quote of the offending text. A finding that only asserts a problem in the abstract ("this might race", "auth could be bypassed") **without citing where in the spec** is auto-`Reject (no evidence)` and is NOT counted toward the cap or shown to the user.
-
-Rationale: this is the spec-level analogue of ck-plan's `file:line` evidence gate. It stops reviewers from inventing plausible-sounding flaws that aren't actually in the artifact. A real flaw can always be located; an imagined one cannot.
-
-#### Step 6: Adjudicate
-For each finding (that survived the Evidence Filter), evaluate and propose: **Accept** or **Reject** with rationale.
 
-#### Step 7: User Review
-Present via `AskUserQuestion`:
-- "Apply all accepted findings"
-- "Let me review each one"
-- "Reject all, spec is fine"
+Check both directions:
+
+- every scoped outcome reaches measurable acceptance and proof;
+- every design decision traces to scope or acceptance;
+- every anchor has an ID unique across the whole spec, allowed type, exact
+  target, and role;
+- design anchors use `A-D-NN`; task-owned anchors use the canonical task-scoped
+  `A-R{requirement}-{sequence}-NN` namespace;
+- file anchors come first and symbols identify their containing files;
+- a task that only consumes a design target references its canonical `A-D-NN`
+  anchor instead of redefining the same target under a task-local ID;
+- every named contract/invariant has one canonical definition;
+- tasks reference contract IDs without copying bodies;
+- every cross-task contract/transition has exactly one owner before consumers;
+- every `RN.M` has exactly one implementation owner; a proof verifier owns a
+  separate proof criterion/artifact and does not repeat the subject's Acceptance;
+- every dependency is real and Markdown agrees with `task_registry`;
+- every task has one canonical `**Status:**` header using `pending`,
+  `in_progress`, `blocked`, or `done`, and its exact status token matches
+  `spec.json.task_registry[path].status`;
+- every task has exactly seven H2 sections and one
+  `ID | Type | Target | Role | Access | Action` table;
+- typed `coordination.boundaries` own topology; legacy trigger fields, priority
+  markers, related-file lists, and prose own nothing;
+- every executable implementation task owns a concrete test file or artifact
+  anchor or shares proof through a typed `proof` boundary; a bare `npm test`
+  string without such an anchor is not ownership;
+- specs-only never creates or updates docs and never fabricates execution
+  proof; doc impact is a brief recommendation at most;
+- no task, phase, research note, or review finding expands `scope_lock`;
+- optional phases exist only as compact `spec.json` groups for a complex Full
+  task graph and never repeat prose.
+- exactly one `## Verification Definitions` section uses parser-visible lines
+  `- **Vn**: Criteria RN.M; Owner ...; [Proof criteria ...; Proof owner ...;
+  Evidence anchor ...;] Decision refs D/I/C; Method ...; Expected ...;
+  Negative/failure ...; Reachability/grounding ...`; the proof extension is
+  conditional on a typed proof boundary; tables and V headings are not canonical.
+
+## Counterexample review
+
+For every `RN.M`, try at least one concrete counterexample that could
+make two competent implementers choose different behavior. Use relevant lenses:
+
+- missing/invalid input or permission;
+- dependency unavailable, timeout, partial success, retry, or duplicate event;
+- conflicting state, ordering, concurrency, restart, rollback, or migration;
+- boundary bypass, data disclosure, retention, or authorization confusion;
+- wrong clock anchor/source/timezone/precision or cutoff comparator/inclusivity or enforcement boundary for a retention/lifecycle rule (for example creation time or UTC vs local or `>` vs `>=` mismatch) that would retain or delete the wrong records;
+- partial public, replay, or operator API contract (missing method, route, auth, headers, request or response schema, error semantics, or idempotency and concurrency behavior);
+- orphaned route/component/worker/artifact with no runtime reachability;
+- task consumer beginning before its contract/schema/transition owner;
+- verification command passing while the user-visible behavior is wrong;
+- an executable task with only a generic test command and no owned test file or typed proof verifier.
+
+A counterexample passes only when requirements or design already choose the
+behavior and the verification plan can distinguish the correct result. Do not
+invent a product decision during review; unresolved choices require a user
+decision. Two-review target is advisory: after two failed semantic rounds, pause for unresolved product/security/architecture uncertainty or repeated non-convergence; one clearly bounded mechanical correction without weakening gates is allowed; budgets never override correctness. Specs-only never creates or updates docs and never fabricates execution proof; record doc impact as a brief recommendation only.
+
+## Assurance depth
+
+| Level | Required semantic review |
+|---|---|
+| Routine | Same-session graph check and relevant counterexamples; no reviewer ceremony. |
+| Elevated | Same-session targeted adversarial review; no reviewer ceremony. |
+| Strict | Full red-team plus a host-hook-observed event from an allowlisted reviewer capability. |
 
-If "Review each one": For each finding, ask: "Apply" | "Reject" | "Modify suggestion"
+Risk presence sets the automatic minimum to Elevated. Strict is opt-in only
+for an explicit user/project independent-audit requirement or a user-confirmed,
+scope-specific audit decision. Never select it from a keyword, severity label,
+Full depth, or reviewer availability. If the required host event is unavailable,
+pause once and report the capability blocker; do not retry loops or downgrade.
 
-#### Step 8: Apply to Spec
-- Edit design.md / task files directly for accepted findings
-- Create `reports/red-team-report.md` documenting the full review session
-- Mark a finding as `Applied To = ...` only after the physical file really contains the change
+Strict red-team lenses are Security Adversary, Failure Mode Analyst, Assumption
+Destroyer, and Scope & Complexity Critic. Findings without a concrete physical
+location and counterexample are rejected as unsupported.
 
-### Finding Output Format
+## Finding format
 
 ```markdown
-## Finding {N}: {title}
+## Finding N: <title>
 - **Severity:** Critical | High | Medium
-- **Location:** Task {X}, section "{name}"
-- **Flaw:** {description}
-- **Failure scenario:** {concrete description of how this fails}
-- **Evidence:** {quote from spec or missing element}
-- **Suggested fix:** {brief recommendation}
+- **Location:** <file:line or exact section/anchor/requirement ID>
+- **Broken edge:** <source -> target in the consistency graph>
+- **Flaw:** <specific contradiction or omission>
+- **Counterexample:** <concrete input/state/event and incorrect possible result>
+- **Evidence:** <short quote or missing required mapping>
+- **Suggested fix:** <smallest semantic correction>
 - **Disposition:** Accept | Reject
-- **Rationale:** {explanation}
+- **Rationale:** <why>
 ```
 
-### Red Team Summary
-
-```markdown
-## Red Team Review — {YYYY-MM-DD}
-**Findings:** {total} ({N} accepted, {M} rejected)
-**Severity breakdown:** {N} Critical, {N} High, {N} Medium
+Apply accepted findings to requirements, design, task acceptance/changes, named
+contracts/invariants, dependencies, or verification. A report-only fix is not a
+fix. Scope or product decisions require explicit user approval before editing.
+
+## Deterministic and grounding gates
+
+Finalize requirements, design, optional research, task files, and canonical
+`spec.json` topology first. Every required authoring stage (`requirements`,
+`design`, and, when present, `research`/`tasks`) must already read `validated`
+via a fresh run of `spec-authoring-validation.cjs` — the sole atomic writer of
+that transition and its C16 `AuthoringValidationReceipt` — before the digest
+below is computed; a `validated` reading with no matching fresh receipt digest
+is treated as `draft` everywhere it is read. Compute the candidate digest
+read-only, then provide a review JSON object with exactly `verdict`,
+`findings`, `unresolved_decisions`, `graph_coverage`, `reviewed_criteria`,
+`counterexamples`, and `reviewer_evidence` — the frozen C2 fields the reviewer
+itself supplies. `lifecycle_disposition` and `repair_round` are never authored
+in this JSON: the finalizer derives both (repair_round is the C13 `attempt_index`
+for the current review_epoch; lifecycle_disposition is CONTINUE unless a
+non-PASS at the epoch's third attempt forces BLOCKED) and appends the completed
+receipt to the durable, append-only `semantic_review_history` lineage. The
+author must not fabricate or directly write authority state.
+
+The digest projects task registry semantics as `id`, `dependencies`, and optional
+`artifacts`. Execution-only status, blocker, timestamps, Markdown `Status`, and
+checkbox checked state do not stale review; requirement, design, research, task
+prose, dependency, artifact, or coordination changes do.
 
-| # | Finding | Severity | Disposition | Applied To |
-|---|---------|----------|-------------|------------|
-| 1 | {title} | Critical | Accept | task-R0-02-... |
+```bash
+# Claude Code
+node .claude/scripts/validate-spec-output.cjs specs/<feature> --semantic-digest
+# Codex (installed projection — verify, not raw .claude path)
+node .codex/scripts/validate-spec-output.cjs specs/<feature> --semantic-digest
 ```
 
----
-
-## Part B: Validation Interview
-
-### 8-Step Workflow
-
-#### Step 1: Read Spec
-- `requirements.md` — technical requirements
-- `design.md` — architectural design
-- `tasks/task-*.md` — all task files
-- Look for: decision points, assumptions, risks, trade-offs
-
-#### Step 2: Extract Question Topics
-
-| Category | Detection Keywords |
-|---|---|
-| **Architecture** | "approach", "pattern", "design", "structure", "database", "API" |
-| **Assumptions** | "assume", "expect", "should", "will", "must", "default" |
-| **Trade-offs** | "tradeoff", "vs", "alternative", "option", "choice" |
-| **Risks** | "risk", "might", "could fail", "dependency", "blocker" |
-| **Scope** | "phase", "MVP", "future", "out of scope", "nice to have" |
-
-#### Step 3: Generate Questions
-- Each question has 2-4 concrete options
-- Mark recommended option with "(Recommended)" suffix
-- "Other" option is automatically added
-- Questions should surface implicit decisions
-
-#### Step 4: Interview User
-- Use `AskUserQuestion` tool
-- Group max 4 questions per call
-- Focus on: assumptions → risks → trade-offs → architecture
-- If spec is simple → fewer than 3 questions is OK
-
-#### Step 5: Document Answers
-
-Save to `reports/validate-log.md`:
-
-```markdown
-## Validation Log — Session {N} — {YYYY-MM-DD}
-**Trigger:** {what prompted this validation session}
-**Questions asked:** {N}
+The machine-recorded state binds the returned digest, exact reviewed `RN.M`
+criteria, and one concrete counterexample per criterion. Each counterexample uses exactly `criterion`,
+`case_kind`, `scenario`, `expected`, `decision_refs`, and `verification_ref`.
+Decision refs resolve to real `D`/`I`/`C` definitions; the `V` definition traces
+both the criterion and decisions. This state binds what was reviewed; it never
+substitutes for semantic judgment or resolves ambiguity.
+
+Routine and Elevated have no reviewer ceremony. Strict requires a real event
+observed by the installed host hook from an allowlisted reviewer capability.
+The hook derives reviewer identity/capability and binds the digest; authoring
+prose cannot self-declare it.
+The final reviewer message contains
+exactly one line:
+
+```text
+CAFEKIT_SEMANTIC_REVIEW_ATTESTATION {"feature_name":"<feature>","spec_file":"specs/<feature>/spec.json","semantic_digest":"sha256:<digest>","verdict":"PASS"}
+```
 
-### Questions & Answers
+The `SubagentStop` hook recomputes the digest and stores a MAC-protected record
+outside the project, bound to canonical project/spec/feature identity. Codex
+must use its event-capable thread-spawn path for this Strict gate. Its legacy
+internal multi-agent path does not expose the child completion message through
+a supported hook event, so it stays not-ready; never derive authority from a
+parent summary or a spawn-only `PostToolUse` event.
+Do not add reviewer identity or independence claims to `semantic_review`.
+This is a host-hook-observed honest-agent guardrail. It is not host-attested
+evidence and not a security boundary against another process running as the
+same OS account.
 
-1. **[{Category}]** {full question text}
-   - Options: {A} | {B} | {C}
-   - **Answer:** {user's choice}
-   - **Custom input:** {verbatim "Other" text if applicable}
-   - **Rationale:** {why this decision affects implementation}
+After the Strict observation (or immediately for Routine/Elevated), invoke the
+only supported atomic promotion path:
 
-### Confirmed Decisions
-- {decision}: {choice} — {brief why}
+```bash
+# Claude Code
+node .claude/scripts/spec-readiness.cjs specs/<feature> --review-result <review.json>
+# Codex (installed projection — verify, not raw .claude path)
+node .codex/scripts/spec-readiness.cjs specs/<feature> --review-result <review.json>
+```
 
-### Action Items
-- [ ] {specific change needed}
+Run normal validation only after the installed finalizer records that state:
 
-### Impact on Tasks
-- Task {N}: {what needs updating and why}
+```bash
+# Claude Code
+node .claude/scripts/validate-spec-output.cjs specs/<feature>
+# Codex (installed projection)
+node .codex/scripts/validate-spec-output.cjs specs/<feature>
 ```
 
-#### Step 6: Propagate Changes
-- Auto-update task files affected by new decisions
-- Add marker: `<!-- Updated: Validation Session N — {change} -->`
-- Change mapping:
+Run the runtime-provided grounding command for every durable spec. It
+deterministically recomputes factual anchor/path/symbol/command reachability and
+creates no additional receipt. Record command, exit code, and failing categories.
+Non-zero blocks readiness. Exit 0 does not override a broken consistency edge or
+counterexample; semantic review remains mandatory at the selected assurance level.
 
-| Change Type | Update Target |
-|---|---|
-| Requirements | `requirements.md` |
-| Architecture | `design.md` |
-| Scope | `requirements.md` + task files |
-| Risk | Task files (Risk Assessment section) |
-| Unknown | `design.md` (add new subsection) |
-
-**Additional propagation rules:**
-- If the decision changes implementation behavior, update an implementation-facing section, not only `Risk Assessment`.
-- If the decision changes scope or provider choice, scan `requirements.md`, `design.md`, and `tasks/*.md` for stale wording and normalize it.
-- If the decision changes deletion/privacy behavior, update `Canonical Contracts & Invariants` first, then tasks that inherit that contract.
-
-#### Step 7: Reconciliation Audit (MANDATORY)
-Before declaring validation complete:
-1. Re-read `spec.json`, `requirements.md`, `design.md`, and all `tasks/task-*.md`
-2. Verify every accepted red-team finding and every validation action item is reflected in the correct physical file(s)
-3. Run `node .claude/scripts/validate-spec-output.cjs specs/<feature>` and keep the raw result visible
-4. Fail the audit if:
-   - a report says "applied" but the file still contains the old text
-   - stale provider strings remain after a provider change
-   - delete-data/privacy artifacts mix multiple canonical policies
-   - any task path fails the CafeKit `tasks/task-R{N}-{SEQ}-<slug>.md` naming convention
-   - `spec.json.updated_at`, `timestamps.review_done`, or `timestamps.validation_done` do not reflect the final reviewed state
-   - deterministic validator exits non-zero
-5. Only after the audit passes may you:
-   - set `spec.json.validation.status = "completed"`
-   - set `spec.json.timestamps.validation_done`
-   - set `spec.json.timestamps.review_done`
-   - set `spec.json.ready_for_implementation = true` when all other gates are satisfied
-
-#### Step 8: Final Status Write-Back
-- Update `spec.json.updated_at` to the reconciliation time
-- On final PASS, set `spec.json.validation.status = "completed"`, `spec.json.timestamps.validation_done`, and, when Red Team ran, `spec.json.timestamps.review_done`
-- On final PASS, set `spec.json.ready_for_implementation = true` only after the deterministic validator passes on the final physical artifacts
-- Ensure `red-team-report.md` and `validate-log.md` do not contradict `spec.json`
-- If reconciliation or deterministic validation fails, keep `validation.status` as `not-run` or `in_progress`, keep `ready_for_implementation = false`, list blockers explicitly, and do not provide an implementation handoff.
-
----
-
-## Combined Output
-
-When both Red Team and Validate run:
+## Final reconciliation
 
-```
-📋 Review Complete: specs/<feature>/
+Before readiness:
 
-Red Team: {N} findings ({A} accepted, {R} rejected)
-Validate: {Q} questions asked, {D} decisions confirmed
+1. Re-read all physical artifacts after fixes.
+2. Confirm accepted findings changed implementation-facing content.
+3. Confirm requirements, globally unique anchor IDs, canonical design-anchor
+   references, contracts, owners/consumers, dependencies, negative paths, and
+   verification form a closed graph.
+4. Confirm `feature-receipt.md`, phase files, copied contract bodies, legacy
+   topology markers, and unused template sections are absent.
+5. Write coherent final timestamps/status and rerun deterministic gates;
+   readiness means technical artifact readiness, not permission to implement.
 
-Files modified: {list}
-Deterministic validator: PASS via `node .claude/scripts/validate-spec-output.cjs specs/<feature>`
+If any check fails, report `FAIL` or `BLOCKED`, preserve unfinished lifecycle
+state, and do not suggest implementation handoff.
 
-📌 Next step: /hapo:develop <feature>    (ONLY if reconciliation audit passed)
-```
+## Platform acceptance
+
+Acceptance covers Claude Code and Codex artifacts only. Verify the semantic
+rules/templates installed for both runtimes remain equivalent. Do not add a
+third runtime to this acceptance scope.

package/src/claude/skills/specs/references/scope-inquiry.md

@@ -2,7 +2,9 @@
 
 ## Purpose
 
-Before investing time in planning, confirm with the user the appropriate level of investment. Avoid wasting time on deep research for simple tasks, or missing risks for complex ones.
+Before investing time in planning, select the smallest scope consistent with the
+request and evidence. Scope inquiry is an analysis step, not a mandatory user
+question.
 
 ## Skip Conditions
 
@@ -38,7 +40,9 @@ Classify the *knowability* of the solution path:
 - **Complex**: Outcome is uncertain; solution emerges through experimentation (e.g., AI/ML tuning, novel UX interactions, performance bottleneck with unknown root cause). Requires prototyping or spike tasks before committing to a full spec.
 - **Chaotic**: No clear path; urgent stabilization needed first (e.g., production outage, data corruption). Skip spec workflow entirely — use `hapo:hotfix` instead.
 
-> **Rule**: If Dimension 4 = Complex or Chaotic, flag this to the user immediately. Complex tasks should include explicit spike/prototype tasks in the spec. Chaotic tasks should exit the spec workflow.
+> **Rule**: If Dimension 4 = Complex, record the uncertainty and add a bounded
+> spike only when it is a real dependency. Chaotic tasks exit to `hapo:hotfix`.
+> Ask only when the response requires a user-owned scope or irreversible choice.
 
 ### Dimension 5: Dependency & Blast Radius
 Assess how many other parts of the system are affected if this change breaks or behaves unexpectedly:
@@ -57,11 +61,20 @@ After the qualitative 5-Dimension pass, run a quick quantitative gut-check. Thes
 - **> 12 task files** → the spec is large; consider splitting by deliverable boundary into sibling specs (cross-spec `blockedBy`) rather than one mega-spec.
 - **> 15 task files** → strong signal to split. A single mega-spec is slow to generate, prone to mid-run failure, and hard to review. Prefer 2-3 focused specs unless the work is genuinely one indivisible slice.
 
-If any tripwire fires, surface it in the Scope Inquiry summary and let the user decide (Expand / Hold / Reduce / Split). Do not silently build the mega-version.
+If a tripwire fires, first reduce or split using the simplest reversible boundary.
+HOLD and ASK only when that change would alter user-owned deliverables or scope.
+Do not silently build the mega-version.
 
 ## Level Selection
 
-After completing the 5-Dimension Assessment, present via `AskUserQuestion`:
+After the assessment, classify the remaining choice:
+
+- Ground current size, dependencies, and blast radius as `repository_fact`.
+- Choose the smallest `reversible_assumption` and record its bounded reversal.
+- For a `user_owned` Expand/Hold/Reduce/Split decision, HOLD and present via
+  `AskUserQuestion`; unresolved scope blocks readiness.
+
+When a user-owned choice exists, use:
 
 **Title:** "Scope Inquiry"
 **Question:** "Based on analysis, what scope level do you want?"
@@ -90,5 +103,5 @@ Scope Inquiry:
 - Blast Radius: [Isolated/Moderate/Critical Path] — [affected modules]
 - Complexity smells: [none | >8 files | >2 new services | >12 tasks → consider split | >15 tasks → split]
 - Minimum Change: [Essential gap vs Niceties]
-- User chose: [Expand / Hold / Reduce / Split]
+- Decision: [grounded fact | reversible default + reversal boundary | user choice]
 ```