opencodekit 0.20.5 → 0.20.6

package/dist/template/.opencode/command/health.md

@@ -155,7 +155,129 @@ For each rule:
 
 Flag rules with intent but no control as **IMPORTANT** gaps.
 
-## Phase 5: Agent Tool Restriction Audit
+## Phase 5: AI Governance Audit
+
+Audit AI-facing configuration for token efficiency, rule health, and instruction quality.
+
+### 5a. Token Budget Estimation
+
+Estimate the total token cost of context injected into each command execution:
+
+```bash
+# Base context (always injected)
+echo "=== Base Context ==="
+wc -c AGENTS.md
+wc -c .opencode/memory/project/user.md .opencode/memory/project/tech-stack.md .opencode/memory/project/project.md 2>/dev/null
+echo "=== Agent Prompts ==="
+wc -c .opencode/agent/*.md 2>/dev/null
+```
+
+For each command, estimate total context = Base + Agent prompt + Skills loaded:
+
+| Command | Base | Agent    | Skills Loaded                                          | Est. Tokens | Budget             |
+| ------- | ---- | -------- | ------------------------------------------------------ | ----------- | ------------------ |
+| `/ship` | [N]  | build.md | beads, memory-grounding, workspace-setup, verification | [total]     | [OK/HEAVY/BLOATED] |
+| `/plan` | [N]  | plan.md  | beads, memory-grounding, writing-plans                 | [total]     | [OK/HEAVY/BLOATED] |
+| ...     | ...  | ...      | ...                                                    | ...         | ...                |
+
+**Thresholds:**
+
+- **OK**: < 15k tokens total injected context
+- **HEAVY**: 15-30k tokens (warn — leaves less room for codebase context)
+- **BLOATED**: > 30k tokens (flag — likely causing quality degradation)
+
+Rough token estimate: `bytes / 4` for English text.
+
+### 5b. Rule Echo Detection
+
+Find instructions duplicated across layers:
+
+```bash
+# Find common instruction phrases across AGENTS.md and agent prompts
+# Look for exact or near-duplicate paragraphs
+grep -hF "Never" AGENTS.md .opencode/agent/*.md | sort | uniq -c | sort -rn | head -20
+grep -hF "Always" AGENTS.md .opencode/agent/*.md | sort | uniq -c | sort -rn | head -20
+grep -hF "MUST" AGENTS.md .opencode/agent/*.md | sort | uniq -c | sort -rn | head -20
+```
+
+Also check for:
+
+- Rules in AGENTS.md that are repeated verbatim in agent prompts (redundant — AGENTS.md is already injected)
+- Rules in agent prompts that contradict AGENTS.md (dangerous)
+- Rules in skills that duplicate AGENTS.md content (bloat)
+
+Report:
+
+| Rule Text (truncated)   | Found In            | Count | Issue                       |
+| ----------------------- | ------------------- | ----- | --------------------------- |
+| "Never force push main" | AGENTS.md, build.md | 2     | ECHO — remove from build.md |
+| "Stage specific files"  | AGENTS.md, ship.md  | 2     | ECHO — remove from ship.md  |
+
+### 5c. Instruction Bloat Detection
+
+Flag oversized configuration files:
+
+| File             | Lines | Tokens (est.) | Status            |
+| ---------------- | ----- | ------------- | ----------------- |
+| AGENTS.md        | [N]   | [N]           | [OK/WARN/BLOATED] |
+| [skill]/SKILL.md | [N]   | [N]           | [OK/WARN/BLOATED] |
+| [command].md     | [N]   | [N]           | [OK/WARN/BLOATED] |
+
+**Thresholds:**
+
+- Skills: WARN > 200 lines, BLOATED > 400 lines
+- Commands: WARN > 300 lines, BLOATED > 500 lines
+- AGENTS.md: WARN > 500 lines, BLOATED > 800 lines
+
+### 5d. Compression Opportunities
+
+Identify repeated boilerplate across skills and commands:
+
+````bash
+# Find common blocks across skills
+for f in .opencode/skill/*/SKILL.md; do
+  grep -c "## When to Use" "$f"
+  grep -c "## When NOT to Use" "$f"
+done
+
+# Find repeated code blocks
+grep -rh "```typescript" .opencode/command/*.md | wc -l
+grep -rh "skill({ name:" .opencode/command/*.md | sort | uniq -c | sort -rn | head -10
+````
+
+Flag opportunities:
+
+- Skills that share >50% identical content (candidates for merging or shared base)
+- Commands with identical boilerplate sections (candidates for shared template)
+- Repeated `skill({ name: "X" })` calls across commands (consider making X a dependency)
+
+### AI Governance Report
+
+```text
+## AI Governance Summary
+
+Token Budget:
+- Lightest command: [command] ([N] tokens)
+- Heaviest command: [command] ([N] tokens)
+- Commands over budget: [list]
+
+Rule Health:
+- Echo rules found: [N] (wasted tokens on duplicates)
+- Contradictions found: [N] (CRITICAL)
+- Compression opportunities: [N]
+
+Instruction Bloat:
+- Oversized skills: [N]
+- Oversized commands: [N]
+- AGENTS.md status: [OK/WARN/BLOATED]
+
+Recommendations:
+1. [Most impactful recommendation]
+2. [Second recommendation]
+3. [Third recommendation]
+```
+
+## Phase 6: Agent Tool Restriction Audit
 
 For each agent in `.opencode/agent/*.md`:
 
@@ -170,7 +292,7 @@ Flag:
 - **IMPORTANT**: Agents with no tool restrictions at all
 - **MINOR**: Agents with restrictions that could be tighter
 
-## Phase 6: Report
+## Phase 7: Report
 
 Output a health report:
 

package/dist/template/.opencode/command/iterate.md

@@ -0,0 +1,200 @@
+---
+description: Refine PRD mid-implementation when scope changes, discoveries emerge, or requirements pivot
+argument-hint: "<bead-id> [--scope expand|reduce|pivot] [--reason <text>]"
+agent: build
+---
+
+# Iterate: $ARGUMENTS
+
+Refine a bead's PRD during active implementation. Two-phase process: define what changed, then update spec artifacts and re-derive affected tasks.
+
+> **When to use:** Mid-`/ship` when you discover scope changed, requirements shifted, or a technical discovery invalidates the original plan.
+>
+> **NOT for:** Pre-implementation changes (use `/create` to rewrite the PRD) or post-implementation retrospectives (use `/compound`).
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "memory-grounding" });
+skill({ name: "prd" });
+skill({ name: "prd-task" });
+```
+
+## Parse Arguments
+
+| Argument    | Default       | Description                        |
+| ----------- | ------------- | ---------------------------------- |
+| `<bead-id>` | required      | The bead being iterated            |
+| `--scope`   | auto-detected | Change type: expand, reduce, pivot |
+| `--reason`  | prompted      | Why the change is needed           |
+
+## Before You Iterate
+
+- **Be certain**: Only iterate if continuing with the current spec would produce wrong output
+- **Don't over-iterate**: Minor adjustments don't need a full iterate cycle — just fix inline during `/ship`
+- **Preserve progress**: Completed tasks stay completed unless explicitly invalidated
+- **Document the delta**: Every change must be traceable to a reason
+
+## Phase 1: Guards
+
+```bash
+br show $ARGUMENTS
+```
+
+Read `.beads/artifacts/$ARGUMENTS/` to check what artifacts exist.
+
+Verify:
+
+- Bead is `in_progress`
+- `prd.md` exists
+- Implementation is partially complete (at least 1 task done or in-progress)
+
+If no tasks are started yet, redirect: "Use `/create --spec-only` to rewrite the PRD instead."
+
+## Phase 2: Assess Change Type
+
+If `--scope` was not provided, determine the change type:
+
+| Type       | Signal                                                  | Example                                   |
+| ---------- | ------------------------------------------------------- | ----------------------------------------- |
+| **expand** | New requirement discovered, additional files needed     | "We also need to handle edge case X"      |
+| **reduce** | Feature is over-scoped, some tasks are unnecessary      | "We don't need the admin panel after all" |
+| **pivot**  | Fundamental approach changed, different solution needed | "REST won't work, switching to WebSocket" |
+
+Ask user to confirm:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Change Type",
+      question: "What kind of spec change is this?",
+      options: [
+        { label: "Expand", description: "Adding scope — new requirements or files" },
+        { label: "Reduce", description: "Removing scope — dropping unnecessary work" },
+        { label: "Pivot", description: "Changing approach — different solution path" },
+      ],
+    },
+  ],
+});
+```
+
+## Phase 3: Define the Delta
+
+### Step 1: Capture the change reason
+
+If `--reason` was not provided, ask:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Reason",
+      question: "What triggered this change? (Be specific — this goes into the PRD changelog)",
+      options: [],
+    },
+  ],
+});
+```
+
+### Step 2: Identify affected artifacts
+
+Read the current PRD and list:
+
+- **Tasks completed:** (preserve these unless pivot invalidates them)
+- **Tasks in-progress:** (may need modification)
+- **Tasks not started:** (may need modification, removal, or replacement)
+- **New tasks needed:** (for expand/pivot)
+
+### Step 3: Document the delta
+
+Write a change record to `.beads/artifacts/$ARGUMENTS/iterations.md`:
+
+```markdown
+## Iteration [N] — [date]
+
+**Type:** [expand | reduce | pivot]
+**Reason:** [user-provided reason]
+**Triggered by:** [discovery | user request | technical constraint | external dependency]
+
+### Impact Assessment
+
+| Area  | Before                  | After                     | Action                         |
+| ----- | ----------------------- | ------------------------- | ------------------------------ |
+| Scope | [original scope]        | [new scope]               | [expanded/reduced/pivoted]     |
+| Tasks | [N] total, [M] complete | [N'] total, [M] preserved | [added/removed/modified count] |
+| Files | [original file list]    | [updated file list]       | [new/removed files]            |
+
+### Task Changes
+
+- **Preserved:** [list of completed task titles — unchanged]
+- **Modified:** [list of tasks with what changed]
+- **Removed:** [list of tasks marked obsolete, with reason]
+- **Added:** [list of new tasks]
+```
+
+## Phase 4: Apply Changes
+
+### For Expand:
+
+1. Add new sections/requirements to `prd.md`
+2. Add new tasks at the end of the Tasks section
+3. Mark new tasks with `depends_on` referencing completed tasks if needed
+4. Re-run `prd-task` skill to regenerate `prd.json` with merged task state
+
+### For Reduce:
+
+1. Move removed scope items to "Out-of-Scope" in `prd.md` with note: `[Removed in Iteration N: reason]`
+2. Mark affected tasks by changing their heading from `### Task Title [category]` to `### ~~Task Title~~ [OBSOLETE — Iteration N]` in `prd.md` (don't delete — preserve history). The `prd-task` skill skips headings containing `OBSOLETE` or `INVALIDATED` markers.
+3. Re-run `prd-task` to regenerate `prd.json` (obsolete tasks excluded)
+
+### For Pivot:
+
+1. Archive current PRD section as `## Original Approach (Superseded)` at bottom of file
+2. Rewrite affected sections (Proposed Solution, Requirements, Tasks)
+3. Preserve completed tasks that are still valid
+4. Mark invalidated completed tasks by changing their heading to `### ~~Task Title~~ [INVALIDATED — Iteration N: reason]`
+5. Re-run `prd-task` to regenerate `prd.json`
+
+### Update plan.md (if exists):
+
+If `.beads/artifacts/$ARGUMENTS/plan.md` exists:
+
+1. Add an "## Iteration [N] Changes" section to the plan
+2. Update dependency graph if tasks changed
+3. Re-compute waves for remaining tasks
+
+## Phase 5: Validate
+
+After applying changes:
+
+- [ ] PRD has no `[NEEDS CLARIFICATION]` markers (resolve or add to Open Questions)
+- [ ] All preserved completed tasks are still valid
+- [ ] New/modified tasks have verification steps
+- [ ] `iterations.md` documents the full delta
+- [ ] `prd.json` reflects the updated task state
+
+## Phase 6: Report
+
+```bash
+br comments add $ARGUMENTS "Iteration [N]: [type] — [reason summary]. Tasks: [added/removed/modified] count"
+```
+
+Output:
+
+1. **Change type:** [expand | reduce | pivot]
+2. **Reason:** [brief summary]
+3. **Task changes:** [N] preserved, [M] modified, [K] removed, [J] added
+4. **Files affected:** [updated list]
+5. **Iteration log:** `.beads/artifacts/$ARGUMENTS/iterations.md`
+6. **Next step:** Continue `/ship $ARGUMENTS` with updated spec
+
+## Related Commands
+
+| Need                       | Command            |
+| -------------------------- | ------------------ |
+| Create initial spec        | `/create`          |
+| Continue shipping          | `/ship <id>`       |
+| Review after changes       | `/review-codebase` |
+| Post-implementation review | `/compound <id>`   |

package/dist/template/.opencode/command/plan.md

@@ -317,7 +317,68 @@ Wave 3: C
 - **Each step is 2-5 minutes** — one action per step
 - **Tasks map to PRD tasks**
 
-## Phase 8: Create Child Beads (if --create-beads or L size)
+## Phase 8: Constitutional Compliance Gate
+
+Before executing, scan the plan against AGENTS.md hard constraints. This catches violations before they become implementation bugs.
+
+### Automated Checks
+
+Scan `plan.md` content for these patterns:
+
+| Violation Pattern                                 | AGENTS.md Rule                              | Severity     |
+| ------------------------------------------------- | ------------------------------------------- | ------------ |
+| `git add .` or `git add -A`                       | Multi-Agent Safety: stage specific files    | **CRITICAL** |
+| `--force` push or `force push`                    | Git Safety: never force push main           | **CRITICAL** |
+| `--no-verify`                                     | Git Safety: never bypass hooks              | **CRITICAL** |
+| `as any` or `@ts-ignore` without justification    | Quality Bar: strong typing                  | **WARNING**  |
+| New package/dependency without approval step      | Guardrails: no new deps without approval    | **WARNING**  |
+| Task modifying >3 files without plan confirmation | Guardrails: no surprise edits               | **WARNING**  |
+| `reset --hard` or `checkout .` or `clean -fd`     | Git Restore: never without explicit request | **CRITICAL** |
+| Secret/credential patterns                        | Security: never expose credentials          | **CRITICAL** |
+
+### Check Process
+
+```bash
+# Scan plan for violation patterns (fixed-string mode to avoid regex false positives)
+grep -inF "git add ." .beads/artifacts/$ARGUMENTS/plan.md
+grep -inF "git add -A" .beads/artifacts/$ARGUMENTS/plan.md
+grep -inF -- "--no-verify" .beads/artifacts/$ARGUMENTS/plan.md
+grep -inF "force push" .beads/artifacts/$ARGUMENTS/plan.md
+grep -inF -- "--force" .beads/artifacts/$ARGUMENTS/plan.md
+grep -inF "reset --hard" .beads/artifacts/$ARGUMENTS/plan.md
+grep -inF "checkout ." .beads/artifacts/$ARGUMENTS/plan.md
+grep -inF "clean -fd" .beads/artifacts/$ARGUMENTS/plan.md
+```
+
+Also check:
+
+- Count files per task: if any task lists >3 files in its `files:` metadata, flag as WARNING
+- Check for `as any` or `@ts-ignore` usage that lacks a documented reason
+- Check if any task adds new dependencies (look for `npm install`, `pnpm add`, `yarn add`, `pip install`, `cargo add`)
+
+### Violation Response
+
+| Severity     | Action                                                             |
+| ------------ | ------------------------------------------------------------------ |
+| **CRITICAL** | Stop. Remove violation from plan. Report to user.                  |
+| **WARNING**  | Flag in plan output. Add confirmation checkpoint to affected task. |
+
+If no violations found, report: `Constitutional compliance: ✓ PASS`
+
+If violations found:
+
+```markdown
+## ⚠️ Constitutional Compliance Check
+
+| #   | Pattern Found        | Location       | Severity | Action                              |
+| --- | -------------------- | -------------- | -------- | ----------------------------------- |
+| 1   | `git add .`          | Task 3, step 2 | CRITICAL | Removed — use specific file staging |
+| 2   | New dependency `zod` | Task 1         | WARNING  | Added approval checkpoint           |
+
+Violations resolved. Plan is compliant.
+```
+
+## Phase 9: Create Child Beads (if --create-beads or L size)
 
 For large work, create child beads for each plan phase:
 
@@ -326,7 +387,7 @@ CHILD=$(br create "[Phase title]" --type task --json | jq -r '.id')
 br dep add $CHILD $ARGUMENTS
 ```
 
-## Phase 9: Report
+## Phase 10: Report
 
 Output:
 

package/dist/template/.opencode/memory/_templates/prd.md

@@ -1,5 +1,12 @@
 # Beads PRD Template
 
+> **Template Instructions:**
+>
+> - Replace ALL bracketed placeholders with real content
+> - If you cannot fill a section with confidence, use `[NEEDS CLARIFICATION: reason]` instead of guessing
+> - Any `[NEEDS CLARIFICATION]` markers MUST be resolved before planning can proceed
+> - Delete this instruction block after filling the template
+
 **Bead:** br-[id]  
 **Created:** [date]  
 **Status:** Draft | In Review | Approved
@@ -20,11 +27,11 @@ estimated_hours: 2 # Time estimate for planning
 
 ### What problem are we solving?
 
-[Clear description of the problem. Include user impact and business impact.]
+[Clear description of the problem. Include user impact and business impact. If unclear, use [NEEDS CLARIFICATION: what specifically is unknown]]
 
 ### Why now?
 
-[What triggered this work? Cost of inaction?]
+[What triggered this work? Cost of inaction? Use [NEEDS CLARIFICATION] if motivation is unclear]
 
 ### Who is affected?
 
@@ -37,11 +44,11 @@ estimated_hours: 2 # Time estimate for planning
 
 ### In-Scope
 
-- [List what's allowed]
+- [List what's in scope. Use [NEEDS CLARIFICATION] for ambiguous boundaries]
 
 ### Out-of-Scope
 
-- [List what's explicitly off-limits]
+- [List what's explicitly off-limits. Use [NEEDS CLARIFICATION] for unresolved scope questions]
 - [Deferred to future iterations]
 
 ---
@@ -50,7 +57,7 @@ estimated_hours: 2 # Time estimate for planning
 
 ### Overview
 
-[One paragraph describing what this feature does when complete.]
+[One paragraph describing what this feature does when complete. Use [NEEDS CLARIFICATION] for uncertain design decisions]
 
 ### User Flow (if user-facing)
 
@@ -80,6 +87,8 @@ Brief description of what must be true.
 - **Accessibility:** [WCAG level if applicable]
 - **Compatibility:** [constraint if applicable]
 
+> If any requirement is unknown or unresearched, mark it `[NEEDS CLARIFICATION: what needs investigation]` rather than omitting it.
+
 ---
 
 ## Success Criteria
@@ -127,6 +136,8 @@ files:
 | ---------- | ----- | -------- | ------------- |
 | Question 1 | Name  | Date     | Open/Resolved |
 
+> **All `[NEEDS CLARIFICATION]` markers should be converted to entries in this table for tracking.**
+
 ---
 
 ## Tasks

package/dist/template/.opencode/skill/reconcile/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: reconcile
+description: >
+  Use when verifying implementation matches its specification — detects drift between PRD requirements
+  and actual code, identifies missing features, extra features, and diverged behavior. Load after /ship
+  or before closing a bead.
+version: 1.0.0
+tags: [workflow, verification, quality]
+dependencies: [verification-before-completion]
+---
+
+# Reconcile — Spec↔Code Drift Detection
+
+## When to Use
+
+- After `/ship` completes all tasks, before closing the bead
+- When you suspect implementation has drifted from the original spec
+- During `/review-codebase` to check spec adherence
+- Before creating a PR to verify completeness
+
+## When NOT to Use
+
+- During active implementation (wait until tasks are done)
+- For code quality issues (use `requesting-code-review` instead)
+- For structural config audits (use `/health` instead)
+
+## Overview
+
+Implementation drift is the silent killer of spec-driven development. Tasks can pass all verification gates while the overall feature drifts from its specification. This skill systematically compares PRD artifacts against code evidence.
+
+## Reconciliation Process
+
+### Step 1: Load Artifacts
+
+```bash
+# Read the PRD
+cat .beads/artifacts/$BEAD_ID/prd.md
+
+# Read the plan (if exists)
+cat .beads/artifacts/$BEAD_ID/plan.md 2>/dev/null
+
+# Determine comparison base (works with main, master, or any default branch)
+BASE=$(git rev-parse origin/main 2>/dev/null || git rev-parse origin/master 2>/dev/null || git merge-base HEAD $(git rev-parse --abbrev-ref HEAD@{upstream} 2>/dev/null || echo HEAD~10))
+
+# Get the actual diff
+git diff $BASE --name-only
+git diff $BASE --stat
+```
+
+### Step 2: Extract Spec Claims
+
+From the PRD, extract these verifiable claims:
+
+| Claim Type                  | Source Section                          | Example                             |
+| --------------------------- | --------------------------------------- | ----------------------------------- |
+| **Success Criteria**        | `## Success Criteria`                   | "User can see existing messages"    |
+| **Functional Requirements** | `## Requirements`                       | "WHEN user clicks X THEN Y happens" |
+| **Affected Files**          | `## Technical Context > Affected Files` | `src/api/users.ts`                  |
+| **Scope Boundaries**        | `## Scope`                              | "In-scope: X, Out-of-scope: Y"      |
+| **Task Deliverables**       | `## Tasks`                              | Each task's end-state description   |
+
+### Step 3: Verify Each Claim
+
+For each extracted claim, gather evidence:
+
+#### Success Criteria Verification
+
+```bash
+# For each success criterion, find code evidence
+# Example: "User can see existing messages"
+grep -r "messages" src/ --include="*.ts" --include="*.tsx" -l
+grep -r "fetchMessages\|getMessages\|listMessages" src/ -l
+```
+
+Map each criterion to:
+
+- **VERIFIED**: Code evidence confirms the criterion is met
+- **PARTIAL**: Some evidence exists but incomplete
+- **MISSING**: No code evidence found
+- **UNTESTABLE**: Cannot be verified via code search (needs manual check)
+
+#### Affected Files Verification
+
+```bash
+# Compare PRD affected files vs actual changed files
+# PRD claims these files would be modified:
+PRD_FILES=$(grep -A 50 "Affected Files" .beads/artifacts/$BEAD_ID/prd.md | grep "src/" | sed 's/.*`//' | sed 's/`.*//')
+
+# Actually modified files:
+ACTUAL_FILES=$(git diff $BASE --name-only)
+
+# Files in PRD but not modified (missing implementation):
+comm -23 <(echo "$PRD_FILES" | sort) <(echo "$ACTUAL_FILES" | sort)
+
+# Files modified but not in PRD (scope creep):
+comm -13 <(echo "$PRD_FILES" | sort) <(echo "$ACTUAL_FILES" | sort)
+```
+
+#### Scope Boundary Check
+
+- **In-scope items**: Verify each has corresponding code changes
+- **Out-of-scope items**: Verify NO code touches those areas (scope creep detection)
+
+### Step 4: Detect Drift Patterns
+
+| Drift Type                 | Detection Method                                       | Severity |
+| -------------------------- | ------------------------------------------------------ | -------- |
+| **Missing Feature**        | Success criterion with no code evidence                | HIGH     |
+| **Partial Implementation** | Criterion partially met (stub, TODO)                   | HIGH     |
+| **Scope Creep**            | Files modified that aren't in PRD affected files       | MEDIUM   |
+| **Spec Rot**               | PRD sections that contradict actual implementation     | MEDIUM   |
+| **Over-Engineering**       | Significant code not traceable to any PRD requirement  | LOW      |
+| **Diverged Behavior**      | Code does something different from WHEN/THEN scenarios | HIGH     |
+
+### Step 5: Calculate Drift Score
+
+```
+Drift Score Calculation:
+- Total claims: [N]
+- VERIFIED: [n] (×1.0)
+- PARTIAL: [n] (×0.5)
+- MISSING: [n] (×0.0)
+- UNTESTABLE: [n] (excluded from calculation)
+
+Adherence = (VERIFIED×1.0 + PARTIAL×0.5) / (Total - UNTESTABLE) × 100
+
+Scope Creep = Extra files modified / Total files modified × 100
+```
+
+## Drift Report Format
+
+```markdown
+## Reconciliation Report: <bead-id>
+
+**PRD:** `.beads/artifacts/<id>/prd.md`
+**Branch:** `<branch-name>`
+**Adherence Score:** [N]%
+**Scope Creep:** [N]%
+
+### Success Criteria
+
+| #   | Criterion        | Status      | Evidence                                   |
+| --- | ---------------- | ----------- | ------------------------------------------ |
+| 1   | [criterion text] | ✅ VERIFIED | `src/file.ts:42` — [what confirms it]      |
+| 2   | [criterion text] | ⚠️ PARTIAL  | `src/file.ts` exists but handler is a stub |
+| 3   | [criterion text] | ❌ MISSING  | No code evidence found                     |
+
+### File Reconciliation
+
+| Category                    | Files                      | Count |
+| --------------------------- | -------------------------- | ----- |
+| ✅ Expected & Modified      | `src/api/users.ts`, ...    | [N]   |
+| ❌ Expected but Untouched   | `src/models/user.ts`, ...  | [N]   |
+| ⚠️ Unexpected Modifications | `src/utils/helper.ts`, ... | [N]   |
+
+### Drift Issues
+
+| #   | Type            | Severity | Description      | Recommendation                                                 |
+| --- | --------------- | -------- | ---------------- | -------------------------------------------------------------- |
+| 1   | Missing Feature | HIGH     | [what's missing] | Implement or use `/iterate --scope reduce` to remove from spec |
+| 2   | Scope Creep     | MEDIUM   | [what's extra]   | Document in PRD or revert                                      |
+
+### Verdict
+
+| Score       | Meaning              | Action                                                 |
+| ----------- | -------------------- | ------------------------------------------------------ |
+| **90-100%** | Excellent adherence  | Ready to close                                         |
+| **70-89%**  | Good with minor gaps | Fix gaps or document as intentional deviations         |
+| **50-69%**  | Significant drift    | Use `/iterate` to reconcile spec and code              |
+| **<50%**    | Major drift          | **BLOCK** — spec and code are fundamentally misaligned |
+```
+
+## Integration Points
+
+- **`/ship` Phase 5**: Run reconcile after review, before close decision
+- **`/compound`**: Include adherence score in retrospective observations
+- **`/pr`**: Include drift report in PR description
+
+## Gotchas
+
+- Some criteria genuinely can't be verified by code search (UI behavior, UX feel) — mark as UNTESTABLE, don't count against score
+- Scope creep isn't always bad — sometimes good engineering requires touching adjacent files. Flag it, don't auto-block.
+- Run AFTER phantom completion detection — reconcile assumes code is substantive, not stubs