feat(verify): detect semantic planning residue

[Seekers2001]

What changed

• add Relevance as a fourth verification dimension in both the generated openspec-verify-change skill and /opsx:verify command
• audit changed implementation elements for traceable links to requirements, tasks, design decisions, or necessary enabling roles
• require reference and data-flow evidence before reporting planning residue
• keep pre-existing debt out of scope and downgrade uncertain findings to suggestions
• update the verify documentation and add parity coverage for both generated templates

Why

Issue #1073 proposes an optional semantic cleanup checkpoint after implementation and before verification/archive. This draft integrates that checkpoint into the existing optional /opsx:verify workflow rather than adding another command. It keeps the workflow surface small while placing the check immediately before archive.

Impact

This changes generated verification instructions and documentation only. It does not automatically remove code or block archive; it reports evidence-backed warnings and suggestions for human review.

Validation

• OPENSPEC_TELEMETRY=0 ./node_modules/.bin/vitest run — 100 test files, 1,876 tests passed
• node build.js
• ./node_modules/.bin/eslint src/ — 0 errors
• git diff --check

Review note

This is a draft specifically to confirm that extending /opsx:verify is preferable to introducing a separate checkpoint command.

Prepared with Codex assistance and reviewed locally for scope and false-positive boundaries.

Addresses #1073

Summary by CodeRabbit

• New Features

  • Verification now evaluates implementation across four dimensions: completeness, correctness, coherence, and relevance.
  • Reports include a relevance score and identify potentially unused or unrelated implementation elements.

• Documentation

  • Updated verification guidance, workflow descriptions, examples, and review criteria to reflect the new relevance checks.

[coderabbitai]

📝 Walkthrough

Walkthrough

The /opsx:verify workflow now evaluates completeness, correctness, coherence, and relevance. Relevance audits changed implementation for planning residue or potentially irrelevant code, updates reports and fallback rules, and is reflected in generated skills, documentation, and parity hashes.

Changes

Verify relevance workflow

Layer / File(s)	Summary
Add relevance auditing to verify templates src/core/templates/workflows/verify-change.ts	Both verify templates now include relevance scorecards, semantic residue audits, issue classifications, heuristics, and four-dimension graceful-degradation rules.
Align generated skill and documentation skills/openspec-verify-change/SKILL.md, docs/commands.md, docs/editing-changes.md, docs/reviewing-changes.md, docs/workflows.md	The generated skill and documentation describe relevance as the fourth dimension and update verification examples and tables.
Update template parity expectations test/core/templates/skill-templates-parity.test.ts	Golden hashes are updated for the revised templates and generated skill content.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• Fission-AI/OpenSpec#497: Established the related dimension-based /opsx:verify workflow that this change extends.
• Fission-AI/OpenSpec#501: Related changes to the same verify workflow and its scorecard.
• Fission-AI/OpenSpec#1089: Also modifies the verify-change workflow template.

Suggested reviewers: tabishb, clay-good

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title matches the main change by describing the new semantic planning residue detection added to the verify workflow.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Seekers2001]

Updated the branch against current main and resolved the template-parity conflict in afd700c. I also regenerated the committed openspec-verify-change skill and its parity hashes so the distributed skill matches the source template. Local validation: build passes, template parity 14/14, and the full suite passes 2253/2253 with telemetry disabled. This PR is now ready for review.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/core/templates/workflows/verify-change.ts`:
- Around line 119-122: Update the verify-change workflow to deterministically
discover and baseline the complete implementation-file diff before auditing
relevance, then use that file set when reviewing changed code. Apply the same
discovery instructions at src/core/templates/workflows/verify-change.ts lines
119-122 and 311-314, and regenerate skills/openspec-verify-change/SKILL.md lines
117-120 with the matching guidance.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: e98dae52-6848-42ee-abf6-f261f714e77e

📥 Commits

Reviewing files that changed from the base of the PR and between 19d4171 and afd700c.

📒 Files selected for processing (7)

• docs/commands.md
• docs/editing-changes.md
• docs/reviewing-changes.md
• docs/workflows.md
• skills/openspec-verify-change/SKILL.md
• src/core/templates/workflows/verify-change.ts
• test/core/templates/skill-templates-parity.test.ts

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Establish the current change’s implementation-file set before auditing relevance.

The earlier steps only search for requirement implementation evidence; they cannot discover disconnected changed code, so the new audit either misses planning residue or risks inspecting pre-existing debt. Add a deterministic changed-file discovery/baseline step before this audit.

• src/core/templates/workflows/verify-change.ts#L119-L122: identify the complete implementation diff for the change before iterating elements.
• src/core/templates/workflows/verify-change.ts#L311-L314: add the same discovery step to the OPSX command template.
• skills/openspec-verify-change/SKILL.md#L117-L120: regenerate the skill with the same discovery instructions.

📍 Affects 2 files

• src/core/templates/workflows/verify-change.ts#L119-L122 (this comment)
• src/core/templates/workflows/verify-change.ts#L311-L314
• skills/openspec-verify-change/SKILL.md#L117-L120

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/core/templates/workflows/verify-change.ts` around lines 119 - 122, Update
the verify-change workflow to deterministically discover and baseline the
complete implementation-file diff before auditing relevance, then use that file
set when reviewing changed code. Apply the same discovery instructions at
src/core/templates/workflows/verify-change.ts lines 119-122 and 311-314, and
regenerate skills/openspec-verify-change/SKILL.md lines 117-120 with the
matching guidance.