feat(verify): detect semantic planning residue

docs/commands.md

@@ -374,7 +374,7 @@ AI:  Reading add-dark-mode artifacts...
 
 ### `/opsx:verify`
 
-Validate that implementation matches your change artifacts. Checks completeness, correctness, and coherence.
+Validate that implementation matches your change artifacts. Checks completeness, correctness, coherence, and relevance.
 
 **Syntax:**
 ```
@@ -387,7 +387,7 @@ Validate that implementation matches your change artifacts. Checks completeness,
 | `change-name` | No | Which change to verify (inferred from context if not provided) |
 
 **What it does:**
-- Checks three dimensions of implementation quality
+- Checks four dimensions of implementation quality
 - Searches codebase for implementation evidence
 - Reports issues categorized as CRITICAL, WARNING, or SUGGESTION
 - Does not block archive, but surfaces issues
@@ -399,6 +399,7 @@ Validate that implementation matches your change artifacts. Checks completeness,
 | **Completeness** | All tasks done, all requirements implemented, scenarios covered |
 | **Correctness** | Implementation matches spec intent, edge cases handled |
 | **Coherence** | Design decisions reflected in code, patterns consistent |
+| **Relevance** | Changed code serves the final implementation, without planning residue |
 
 **Example:**
 ```
@@ -421,15 +422,20 @@ AI:  Verifying add-dark-mode...
      ✓ Naming conventions consistent with design.md
      ⚠ Design mentions "CSS variables" but implementation uses Tailwind classes
 
+     RELEVANCE
+     ✓ New implementation elements map to requirements or necessary infrastructure
+     ⚠ Unused theme adapter remains from an earlier approach
+
      SUMMARY
      ─────────────────────────────
      Critical issues: 0
-     Warnings: 2
+     Warnings: 3
      Ready to archive: Yes (with warnings)
 
      Recommendations:
      1. Add test for system preference detection
      2. Update design.md to reflect Tailwind usage, or refactor to use CSS variables
+     3. Remove the unused theme adapter
 ```
 
 **Tips:**

docs/editing-changes.md

@@ -43,7 +43,7 @@ Concretely, after some `/opsx:apply` work:
 
 - Want to re-examine the plan? Open the artifacts and read them, or run `openspec show <change>` in your terminal for a consolidated view.
 - Found something to change? Edit the artifact (or ask the AI to), then continue.
-- Want a structured check that the code matches the plan? Run `/opsx:verify` (expanded command). It reports completeness, correctness, and coherence without blocking anything. See [Workflows: Verify](workflows.md#verify-check-your-work).
+- Want a structured check that the code matches the plan? Run `/opsx:verify` (expanded command). It reports completeness, correctness, coherence, and relevance without blocking anything. See [Workflows: Verify](workflows.md#verify-check-your-work).
 
 There's no "review phase" to return to, because review is something you can do at any point, including after implementation.
 

docs/reviewing-changes.md

@@ -97,13 +97,14 @@ Then re-read the part you changed. Re-draft until it's a plan you'd sign your na
 
 ## After the code: verify
 
-Once the work is built, `/opsx:verify` is your second review. It re-reads the artifacts and the code and reports mismatches across three dimensions:
+Once the work is built, `/opsx:verify` is your second review. It re-reads the artifacts and the code and reports mismatches across four dimensions:
 
 | Dimension | What it checks |
 |-----------|----------------|
 | **Completeness** | Every task done, every requirement implemented, scenarios covered |
 | **Correctness** | The implementation matches the spec's intent, edge cases handled |
 | **Coherence** | Design decisions actually show up in the code |
+| **Relevance** | Code introduced by the change still serves the final implementation |
 
 ```
 You: /opsx:verify

docs/workflows.md

@@ -330,7 +330,7 @@ The recommended completion flow:
 
 #### Verify: Check Your Work
 
-`/opsx:verify` validates implementation against your artifacts across three dimensions:
+`/opsx:verify` validates implementation against your artifacts across four dimensions:
 
 ```text
 You: /opsx:verify
@@ -352,15 +352,20 @@ AI:  Verifying add-auth...
      ✓ Naming conventions consistent with design.md
      ⚠ Design mentions "event-driven" but implementation uses polling
 
+     RELEVANCE
+     ✓ New implementation elements map to requirements or necessary infrastructure
+     ⚠ Unused compatibility branch remains from an earlier approach
+
      SUMMARY
      ─────────────────────────────
      Critical issues: 0
-     Warnings: 2
+     Warnings: 3
      Ready to archive: Yes (with warnings)
 
      Recommendations:
      1. Add test for session timeout scenario
      2. Consider refactoring to event-driven as designed, or update design.md
+     3. Remove the unused compatibility branch
 ```
 
 **What verify checks:**
@@ -370,6 +375,7 @@ AI:  Verifying add-auth...
 | Completeness | All tasks done, all requirements implemented, scenarios covered |
 | Correctness | Implementation matches spec intent, edge cases handled |
 | Coherence | Design decisions reflected in code, patterns consistent |
+| Relevance | Changed code serves the final implementation, without planning residue |
 
 Verify won't block archive, but it surfaces issues you might want to address first.
 

skills/openspec-verify-change/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openspec-verify-change
-description: Verify implementation matches change artifacts. Use when the user wants to validate that implementation is complete, correct, and coherent before archiving.
+description: Verify implementation matches change artifacts. Use when the user wants to validate that implementation is complete, correct, coherent, and relevant before archiving.
 allowed-tools: Bash(openspec:*)
 license: MIT
 compatibility: Requires openspec CLI.
@@ -47,16 +47,27 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
 
    This returns the change directory and `contextFiles` (artifact ID -> array of concrete file paths). Read all available artifacts from `contextFiles`.
 
-4. **Initialize verification report structure**
+4. **Establish implementation scope**
 
-   Create a report structure with three dimensions:
+   Determine the complete implementation diff before evaluating relevance:
+   - Identify the change's version-control baseline from repository context (for example, its target branch or merge base). If the baseline is ambiguous, ask the user instead of guessing.
+   - Use an available read-only version-control or file-inventory capability to list every file added, modified, deleted, or renamed between that baseline and the current working state. Include committed, staged, unstaged, and untracked files when applicable; untracked files require a separate inventory because they do not appear in ordinary diffs.
+   - Record the baseline and the changed-file discovery method so the audit scope is reproducible.
+   - Separate implementation files (source, tests, configuration, scripts, and other runtime-affecting files) from OpenSpec change artifacts. Save the implementation file set for the relevance audit.
+   - Do not derive this file set from requirement keyword searches. Those searches find supporting evidence, but cannot detect disconnected implementation.
+   - If version-control information is unavailable or no reliable baseline can be established, state the limitation and skip the relevance audit rather than inspecting the entire repository as though it were part of the change.
+
+5. **Initialize verification report structure**
+
+   Create a report structure with four dimensions:
    - **Completeness**: Track tasks and spec coverage
    - **Correctness**: Track requirement implementation and scenario coverage
    - **Coherence**: Track design adherence and pattern consistency
+   - **Relevance**: Track semantic residue and unnecessary scope
 
    Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
 
-5. **Verify Completeness**
+6. **Verify Completeness**
 
    **Task Completion**:
    - If `contextFiles.tasks` exists, read every file path in it
@@ -76,7 +87,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
        - Add CRITICAL issue: "Requirement not found: <requirement name>"
        - Recommendation: "Implement requirement X: <description>"
 
-6. **Verify Correctness**
+7. **Verify Correctness**
 
    **Requirement Implementation Mapping**:
    - For each requirement from delta specs:
@@ -95,7 +106,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
        - Add WARNING: "Scenario not covered: <scenario name>"
        - Recommendation: "Add test or implementation for scenario: <description>"
 
-7. **Verify Coherence**
+8. **Verify Coherence**
 
    **Design Adherence**:
    - If `contextFiles.design` exists:
@@ -113,7 +124,22 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
      - Add SUGGESTION: "Code pattern deviation: <details>"
      - Recommendation: "Consider following project pattern: <example>"
 
-8. **Generate Verification Report**
+9. **Verify Relevance**
+
+   **Semantic Residue Audit**:
+   - Review every file in the implementation file set established from the version-control diff
+   - For each new API, function, type field, state value, helper, branch, or mapping, identify the requirement, task, design decision, or necessary enabling role it serves
+   - Look for residue from superseded planning assumptions: unused elements, unreachable branches, placeholder or mock code, duplicated mappings, and extension points disconnected from any requirement or task
+   - Before reporting a candidate, confirm from the baseline diff hunks that the element was added or modified by this change, then trace references and data flow before flagging it as residue
+   - If an element has no traceable purpose:
+     - Add WARNING: "Planning residue: <element and evidence>"
+     - Recommendation: "Remove <element> or show the requirement/task it serves"
+   - If the purpose is uncertain:
+     - Add SUGGESTION: "Possibly irrelevant code: <element>"
+     - Recommendation: "Confirm whether <element> is required"
+   - Pre-existing debt is out of scope; keep findings limited to code introduced or changed for this change
+
+10. **Generate Verification Report**
 
    **Summary Scorecard**:
    ```markdown
@@ -125,6 +151,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
    | Completeness | X/Y tasks, N reqs|
    | Correctness  | M/N reqs covered |
    | Coherence    | Followed/Issues  |
+   | Relevance    | Clean/N residue  |
    ```
 
    **Issues by Priority**:
@@ -137,6 +164,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
    2. **WARNING** (Should fix):
       - Spec/design divergences
       - Missing scenario coverage
+      - Confirmed planning residue
       - Each with specific recommendation
 
    3. **SUGGESTION** (Nice to fix):
@@ -154,14 +182,16 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
 - **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
 - **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
 - **Coherence**: Look for glaring inconsistencies, don't nitpick style
+- **Relevance**: Require reference and data-flow evidence that a changed element serves no requirement, task, design decision, or necessary enabling role
 - **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
 - **Actionability**: Every issue must have a specific recommendation with file/line references where applicable
 
 **Graceful Degradation**
 
-- If only tasks.md exists: verify task completion only, skip spec/design checks
-- If tasks + specs exist: verify completeness and correctness, skip design
-- If full artifacts: verify all three dimensions
+- If only tasks.md exists: verify task completion and relevance against tasks, skip spec/design checks
+- If tasks + specs exist: verify completeness, correctness, and relevance against tasks and specs, skip design
+- If full artifacts: verify all four dimensions
+- If the implementation diff baseline or file set cannot be identified reliably: skip relevance and explain why
 - Always note which checks were skipped and why
 
 **Output Format**