sddx-workflow 0.9.0 → 0.10.0

package/templates/cursor-rules/sddx-workflow.mdc

@@ -5,23 +5,52 @@ alwaysApply: true
 
 This project uses the SDD Protocol. Before starting any task, read:
 
-1. `.sdd/workflow.md` — all commands, ceremony levels, and stop points
+1. `.sdd/workflow.md` — all commands, permissions, stop points, anti-patterns
 2. `.sdd/project-overview.md` — what this app is, its non-goals, and domains
 3. `.sdd/conventions.md` — project-specific conventions and patterns
 
 ## Available commands
 
+### Project setup
+| Command | Purpose |
+|---|---|
+| `/bootstrap` | Populate project context — interview or `--scan` |
+| `/scan` | Discovery-only pass over an existing codebase |
+| `/conventions-sync` | Refresh conventions, preserving manual sections |
+
+### Exploration
 | Command | Purpose |
 |---|---|
-| `/bootstrap` | Populate project context — interview or codebase scan |
 | `/ask` | Research only — no code changes |
+| `/research` | Non-binding research artifact |
 | `/assume` | List assumptions and stop for confirmation |
-| `/bugfix` | Reproduce → diagnose → fix → validate |
-| `/refactor` | Restructure without behavior change |
+
+### Feature flow
+| Command | Purpose |
+|---|---|
 | `/spec-new` | Scaffold a spec folder |
+| `/spec-clarify` | Pre-plan clarification |
 | `/spec-plan` | Generate technical plan — stop for approval |
 | `/spec-tasks` | Execute plan one task at a time, TDD-first |
-| `/review` | Final audit before closing |
+| `/impl-gap` | Stop and report blocking ambiguity |
+| `/spec-amend` | Documented Change Request |
+| `/spec-analyze` | Cross-consistency analysis |
+| `/verify` | Strict mechanical audit |
+| `/review` | Lighter human-touch final pass |
 | `/finish` | Stage files and generate commit message |
 
+### Multi-spec
+| Command | Purpose |
+|---|---|
+| `/spec-status` | Show all active specs and phase |
+| `/spec-conflicts` | Detect file conflicts between specs |
+
+### Other
+| Command | Purpose |
+|---|---|
+| `/bugfix` | Reproduce → diagnose → fix → validate |
+| `/refactor` | Restructure without behavior change |
+
+Standard workflow: `/spec-new` → `/spec-clarify` → `/spec-plan` → `/spec-tasks` → `/verify` → `/review` → `/finish`.
+
 Full definitions for each command are in `.sdd/workflow.md`.

package/templates/gemini-commands/ask.toml

@@ -0,0 +1,8 @@
+description = "Research and exploration — no code changes"
+prompt = """
+Execute the /ask command defined in .sdd/workflow.md.
+
+Research and exploration only — do not modify any files. Read, analyze, and summarize findings with explicit options or recommendations.
+
+Topic: {{args}}
+"""

package/templates/gemini-commands/assume.toml

@@ -0,0 +1,10 @@
+description = "Surface all assumptions before acting — stop for confirmation"
+prompt = """
+Execute the /assume command defined in .sdd/workflow.md.
+
+List every assumption being made about the task, codebase state, and technical decisions.
+For each: what you're assuming, why, and what changes if it's wrong.
+Stop and wait for confirmation before proceeding.
+
+Context: {{args}}
+"""

package/templates/gemini-commands/bootstrap.toml

@@ -0,0 +1,9 @@
+description = "Populate project context via interview or codebase scan"
+prompt = """
+Execute the /bootstrap command defined in .sdd/workflow.md.
+
+If the project already has code, scan the codebase first (read structure, package files, schema, routes), infer what you can, then ask only about what the code cannot answer.
+If it's a new project, ask the 6 interview questions defined in workflow.md one at a time.
+
+Present the full draft of .sdd/project-overview.md and .sdd/conventions.md for approval before writing any file.
+"""

package/templates/gemini-commands/bugfix.toml

@@ -0,0 +1,10 @@
+description = "Reproduce → diagnose → fix → validate"
+prompt = """
+Execute the /bugfix command defined in .sdd/workflow.md.
+
+Follow the stages in order without skipping: Reproduce → Diagnose → Fix → Validate.
+Stop after Reproduce if the bug cannot be confirmed with a test or repro case.
+Escalate to /spec-new if the fix scope exceeds ~1 file or ~50 lines.
+
+Bug or error: {{args}}
+"""

package/templates/gemini-commands/conventions-sync.toml

@@ -0,0 +1,6 @@
+description = "Refresh .sdd/conventions.md from current project state — preserves manual sections"
+prompt = """
+Execute the /conventions-sync command defined in .sdd/workflow.md.
+
+Scan packages, structure, lint/format configs, ORM/router. Preserve sections marked `<!-- manual -->` verbatim; regenerate auto-sections. Present diff and STOP for approval before writing.
+"""

package/templates/gemini-commands/finish.toml

@@ -0,0 +1,8 @@
+description = "Stage files and generate a conventional commit message"
+prompt = """
+Execute the /finish command defined in .sdd/workflow.md.
+
+Run git status and git diff. Stage all relevant files (exclude .env*, build artifacts, scratch files). Determine the commit type. Draft a conventional commit message following the format in workflow.md — one overview sentence, detailed bullets with reasoning, optional footer for non-obvious context.
+
+Stop and present the staged file list and commit message for approval before committing.
+"""

package/templates/gemini-commands/impl-gap.toml

@@ -0,0 +1,10 @@
+description = "Stop and report when a task is blocked by ambiguity or impossibility"
+prompt = """
+Execute the /impl-gap command defined in .sdd/workflow.md.
+
+Usage: /impl-gap <feature>
+
+STOP execution. Create specs/<feature>/impl-gaps.md from the template if missing, then append a GAP entry with current task, problem, impact, proposed resolution, action required, and resolution placeholder. Wait for human direction. If the gap requires changing the spec, escalate to /spec-amend.
+
+Feature: {{args}}
+"""

package/templates/gemini-commands/refactor.toml

@@ -0,0 +1,8 @@
+description = "Restructure without changing external behavior"
+prompt = """
+Execute the /refactor command defined in .sdd/workflow.md.
+
+Run existing tests first to establish a green baseline. Implement in small steps — tests must stay green throughout. No new features or bug fixes mixed in.
+
+Target: {{args}}
+"""

package/templates/gemini-commands/research.toml

@@ -0,0 +1,10 @@
+description = "Targeted exploration with non-binding artifact — separates exploration from commitment"
+prompt = """
+Execute the /research command defined in .sdd/workflow.md.
+
+Usage: /research <feature> <topic>
+
+Investigate options for the topic. Read specs/<feature>/1-requirements.md and write a research artifact in the spec folder with options, pros/cons, current versions/maintenance status, and a non-binding recommendation. Do NOT modify 2-plan.md.
+
+Spec and topic (e.g. "auth-refresh jwt-libraries"): {{args}}
+"""

package/templates/gemini-commands/review.toml

@@ -0,0 +1,8 @@
+description = "Lighter human-touch final pass — runs after /verify"
+prompt = """
+Execute the /review command defined in .sdd/workflow.md.
+
+Read the implementation qualitatively: clarity, naming, simplicity, leaky abstractions, copy-paste smell, comments that lie. Note minor follow-ups; don't enforce mechanical checks (that's /verify's job). If a structural issue is found, escalate to /spec-amend.
+
+Spec: {{args}}
+"""

package/templates/gemini-commands/scan.toml

@@ -0,0 +1,6 @@
+description = "Discovery-only pass over an existing codebase — writes scan-report.md"
+prompt = """
+Execute the /scan command defined in .sdd/workflow.md.
+
+Read package manifests, directory structure, lint/format configs, and observable conventions. Produce scan-report.md at repo root with findings. Do not modify any .sdd/ file.
+"""

package/templates/gemini-commands/spec-amend.toml

@@ -0,0 +1,10 @@
+description = "Documented Change Request for post-approval spec changes"
+prompt = """
+Execute the /spec-amend command defined in .sdd/workflow.md.
+
+Usage: /spec-amend <feature> <change-summary>
+
+Create specs/<feature>/amendments.md from the template if missing, then append a CR entry with motive, requirement changes, plan changes, affected tasks, and status "Pending approval". Stop for explicit approval before propagating any change to 1-requirements.md or 2-plan.md.
+
+Feature and change summary: {{args}}
+"""

package/templates/gemini-commands/spec-analyze.toml

@@ -0,0 +1,6 @@
+description = "Cross-consistency analysis (goal-task coverage, plan-task coverage, scope creep)"
+prompt = """
+Execute the /spec-analyze command defined in .sdd/workflow.md.
+
+Check: every G-ID referenced by at least one task; every "Components Affected" entry referenced by at least one task; any task lacking a goal reference (scope creep). Write specs/{{args}}/analysis.md.
+"""

package/templates/gemini-commands/spec-clarify.toml

@@ -0,0 +1,6 @@
+description = "Pre-plan clarification — generates blocking and non-blocking questions"
+prompt = """
+Execute the /spec-clarify command defined in .sdd/workflow.md.
+
+Generate categorized clarification questions for specs/{{args}}/1-requirements.md (blocking vs. non-blocking). Wait for answers. Append questions and answers to a Clarifications section of the requirements doc. No other section is modified.
+"""

package/templates/gemini-commands/spec-conflicts.toml

@@ -0,0 +1,6 @@
+description = "Detect file-level conflicts between active specs — detection only"
+prompt = """
+Execute the /spec-conflicts command defined in .sdd/workflow.md.
+
+Cross-reference "Components Affected" across all active specs. Report each file touched by two or more specs, naming the specs and suggesting sequencing. Do not modify any spec.
+"""

package/templates/gemini-commands/spec-new.toml

@@ -0,0 +1,7 @@
+description = "Scaffold a spec folder for a new feature"
+prompt = """
+Execute the /spec-new command defined in .sdd/workflow.md.
+
+Create a specs/{{args}}/ folder by copying the three template files from specs/_template/.
+Replace <Feature Name> in each file title with the actual feature name.
+"""

package/templates/gemini-commands/spec-plan.toml

@@ -0,0 +1,7 @@
+description = "Generate technical plan — stops for approval before any code"
+prompt = """
+Execute the /spec-plan command defined in .sdd/workflow.md.
+
+Read specs/{{args}}/1-requirements.md, run /assume to surface assumptions, then draft the technical plan in specs/{{args}}/2-plan.md.
+Stop for explicit approval before writing any implementation code.
+"""

package/templates/gemini-commands/spec-status.toml

@@ -0,0 +1,6 @@
+description = "Show state of all active specs — phase, progress, outstanding CRs and gaps"
+prompt = """
+Execute the /spec-status command defined in .sdd/workflow.md.
+
+List directories under specs/ excluding _template and _done. For each: feature name, current phase, progress (N/M tasks), outstanding CRs or unresolved gaps. Do not modify any file.
+"""

package/templates/gemini-commands/spec-tasks.toml

@@ -0,0 +1,8 @@
+description = "Execute approved plan one task at a time, TDD-first"
+prompt = """
+Execute the /spec-tasks command defined in .sdd/workflow.md.
+
+Then read the approved specs/{{args}}/2-plan.md and execute tasks one at a time. Write the test first (red), implement until green, run the full suite, then move to the next task.
+
+If a task is blocked by ambiguity, contradiction, or technical impossibility, STOP and run /impl-gap — never improvise. If the gap requires changing the spec, escalate to /spec-amend.
+"""

package/templates/gemini-commands/verify.toml

@@ -0,0 +1,6 @@
+description = "Strict mechanical audit — read-only; writes verify-report.md"
+prompt = """
+Execute the /verify command defined in .sdd/workflow.md.
+
+Read-only mechanical audit. Check: all tasks marked complete, every goal has an artifact, every acceptance scenario has a passing test, full test suite green, no out-of-scope file changes, no unresolved /impl-gap entries, no pending CRs. Write specs/{{args}}/verify-report.md. Do not modify code or specs.
+"""

package/templates/gemini.md

@@ -2,23 +2,55 @@
 
 This project uses the SDD Protocol. Read these files before starting any task:
 
-1. **[.sdd/workflow.md](.sdd/workflow.md)** — commands, ceremony levels, and stop points
+1. **[.sdd/workflow.md](.sdd/workflow.md)** — commands, permissions, stop points, anti-patterns
 2. **[.sdd/project-overview.md](.sdd/project-overview.md)** — what this app is, its non-goals, domains, and definition of done
 3. **[.sdd/conventions.md](.sdd/conventions.md)** — project-specific conventions and patterns
 
 ## Quick Reference
 
+### Project setup
 | Intent | Workflow |
 |---|---|
-| Initialize project context | `bootstrap` (new) · `bootstrap --scan` (existing) |
-| Explore / research | `ask` |
+| Initialize project context (new) | `bootstrap` |
+| Initialize project context (existing codebase) | `bootstrap --scan` |
+| Discovery-only scan of an existing codebase | `scan` |
+| Refresh conventions from current project state | `conventions-sync` |
+
+### Exploration
+| Intent | Workflow |
+|---|---|
+| Research / ask without changing anything | `ask` |
+| Non-binding research artifact for a topic | `research` |
 | Surface and validate assumptions | `assume` |
+
+### Feature flow
+| Intent | Workflow |
+|---|---|
+| Scaffold a spec folder | `spec-new` |
+| Clarify a draft before planning | `spec-clarify` |
+| Generate technical plan (stops for approval) | `spec-plan` |
+| Execute approved plan one task at a time | `spec-tasks` |
+| Stop and report an implementation gap | `impl-gap` |
+| Document a Change Request for spec edits | `spec-amend` |
+| Cross-consistency analysis (goals / plan / tasks) | `spec-analyze` |
+| Strict mechanical audit | `verify` |
+| Lighter human-touch final pass | `review` |
+| Stage and commit | `finish` |
+
+### Multi-spec
+| Intent | Workflow |
+|---|---|
+| Show state of all active specs | `spec-status` |
+| Detect file-level conflicts between specs | `spec-conflicts` |
+
+### Other
+| Intent | Workflow |
+|---|---|
 | Fix a confirmed bug | `bugfix` → `finish` |
 | Restructure without behavior change | `refactor` → `finish` |
-| New feature | `spec-new` → `spec-plan` → `spec-tasks` → `review` → `finish` |
-| Stage + commit after any work | `finish` |
 
 Invoke any workflow by name (e.g., "run bootstrap", "start spec-new for auth-refresh").
+Standard workflow: `spec-new` → `spec-clarify` → `spec-plan` → `spec-tasks` → `verify` → `review` → `finish`.
 Full definitions are in `.sdd/workflow.md`.
 
 ## Active Specs

package/templates/specs/_template/1-requirements.md

@@ -1,5 +1,10 @@
 # Requirements: <Feature Name>
 
+> **Decisions and trade-offs only — no implementation.** Code snippets are allowed
+> only when they reduce ambiguity (e.g. a function signature, an example input/output,
+> a concrete error shape). If a snippet is doing anything more than that, it belongs
+> in `2-plan.md`, not here.
+
 ## Status
 
 - [ ] Draft
@@ -70,6 +75,24 @@ Scenario: <add one scenario per distinct behavior>
      Business:   "Must ship before the Q2 demo on May 15."
      UX:         "Must match the existing row layout in the info modal — no redesign." -->
 
+## Assumptions
+
+<!-- What this document is taking as given about users, business rules, or scope.
+     Different from Constraints (hard rules from outside) and Open Questions (unresolved).
+     Each assumption must be **falsifiable** — something the reader could correct.
+     Generic filler ("users want a good experience") is not an assumption.
+
+     Format: what + why we're assuming it + what changes if it's wrong.
+
+     Example:
+     1. **Users only need the most recent open timestamp, not a history.** — based on
+        the original feature request; nobody asked for history.
+        If wrong: the data model needs an access_log table, not a single column.
+
+     2. **"Opening" means clicking into the file viewer, not previewing in a list.** —
+        list previews are passive, not deliberate access.
+        If wrong: the trigger surface expands and we'd record many more events. -->
+
 ## Open Questions
 
 <!-- Mark each question by whether it blocks planning or can be decided during it.
@@ -79,3 +102,22 @@ Scenario: <add one scenario per distinct behavior>
 
      ⚠️ Non-blocking — can be decided during planning with a reasonable default:
         Should the timestamp be relative ("3 days ago") or absolute ("Apr 12, 14:30")? -->
+
+## Clarifications
+
+<!-- Populated by /spec-clarify (pre-plan) or appended by /spec-amend (post-approval).
+
+     Format — use checkboxes so /spec-plan can detect unanswered blocking questions:
+       - [ ] ⛔ BLOCKING — <question>
+       - [x] ⛔ BLOCKING — <question> → <answer>
+       - [ ] ⚠️ NON-BLOCKING — <question> (default if unanswered: <assumed default>)
+       - [x] ⚠️ NON-BLOCKING — <question> → <answer>
+
+     /spec-plan must stop if any "[ ] ⛔ BLOCKING" entry exists with no answer.
+     Non-blocking questions without an answer proceed with the stated default.
+
+     Example:
+     - [x] ⛔ BLOCKING — Does folder navigation count as "opening" a file? → No. Only files opened in the viewer count. Trigger surface stays narrow.
+     - [x] ⚠️ NON-BLOCKING — Timestamp format? → Relative ("3 days ago"); switch to absolute on hover.
+-->
+

package/templates/specs/_template/2-plan.md

@@ -39,6 +39,13 @@
      — rejected because it would bump updated_at on every read, corrupting
      the 'modified' timestamp shown to users." -->
 
+<!-- Optional artifacts: if this plan needs more depth in a specific area, /spec-plan
+     may produce additional files alongside this one — reference them here:
+       - 2a-data-model.md   — when persistence is non-trivial (schemas, migrations, ER)
+       - 2b-api-contracts.md — when new external HTTP/RPC/event contracts are introduced
+       - 2c-research.md      — when outstanding /research output belongs in the plan
+     If unused, just delete this comment. -->
+
 ## Tradeoffs
 
 <!-- Conscious sacrifices the chosen approach makes. Only include if they exist.
@@ -104,6 +111,13 @@
        since this plan was written, changing its interface
      - A task requires touching files not listed here -->
 
+## Gap Handling
+
+<!-- Implementation-time ambiguities, contradictions, or technical impossibilities
+     are NOT recorded in this plan. Run /impl-gap and append to
+     specs/<feature>/impl-gaps.md. If the resolution changes requirements or plan,
+     escalate via /spec-amend before editing approved spec files. -->
+
 ## Verification
 
 <!-- How to confirm each task is done. Link explicitly to scenarios in 1-requirements.md.

package/templates/specs/_template/2a-data-model.md

@@ -0,0 +1,29 @@
+# Data Model — <Feature Name>
+
+> Optional artifact. Generated by /spec-plan when persistence changes are non-trivial.
+> Referenced from `2-plan.md` §Approach. Delete this file if unused.
+
+## Tables / Collections
+
+<!-- For each new or modified table:
+     - **Name** — purpose, primary key
+     - **New columns:** name, type, nullable, default, constraint
+     - **Indexes added:** columns, unique/non-unique, reason
+     - **Relationships:** FK target, ON DELETE behavior, embedding, etc.
+
+     Example:
+     **recent_files** — stores per-user recently opened file list
+     - user_id: uuid, FK → users.id ON DELETE CASCADE
+     - file_path: text, not null
+     - opened_at: timestamptz, not null, default now()
+     - Index: (user_id, opened_at DESC) for timeline queries
+-->
+
+## Migrations
+
+<!-- Migration strategy and order of operations.
+     Note zero-downtime constraints (add-column-then-backfill, rename-in-steps, etc.) -->
+
+## ER Diagram (optional)
+
+<!-- ASCII or Mermaid ER diagram if the relationships are non-obvious -->

package/templates/specs/_template/2b-api-contracts.md

@@ -0,0 +1,27 @@
+# API Contracts — <Feature Name>
+
+> Optional artifact. Generated by /spec-plan when new external HTTP/RPC/event contracts are introduced.
+> Referenced from `2-plan.md` §Approach. Delete this file if unused.
+
+## HTTP Endpoints
+
+<!-- For each new or modified endpoint:
+     Method + path | Auth required | Request body | Response | Error codes
+
+     Example:
+     **GET /api/recent-files**
+     - Auth: session cookie (user must be authenticated)
+     - Query params: limit (default 10, max 50)
+     - Response 200: { files: [{ path: string, openedAt: string }] }
+     - Response 401: { error: "unauthenticated" }
+-->
+
+## Events / Webhooks
+
+<!-- For each new event or webhook:
+     Name | Payload schema | Trigger condition | Consumer(s) -->
+
+## External APIs Consumed
+
+<!-- Third-party APIs this feature calls:
+     Service | Endpoint | Auth method | Rate limits | Fallback behavior -->

package/templates/specs/_template/2c-research.md

@@ -0,0 +1,25 @@
+# Research Summary — <Feature Name>
+
+> Optional artifact. Carries over /research output that directly informs the plan.
+> Referenced from `2-plan.md` §Approach. Delete this file if unused.
+> Full research detail lives in `specs/<feature>/research-<topic>.md` files.
+
+## Decision
+
+<!-- The option selected and the one-line rationale.
+     Example: "Using NextAuth with GitHub provider — OAuth2 support is built-in,
+     team already has a GitHub org, and it avoids a separate auth service." -->
+
+## Alternatives Considered
+
+<!-- Options evaluated and rejected, with rejection reason.
+     Prevents re-litigating the same debate in future PRs.
+
+     Example:
+     - **Passport.js** — rejected: requires manual session management; more boilerplate for no benefit here.
+     - **Auth0** — rejected: adds a paid third-party dependency; overkill for internal tooling. -->
+
+## Open Questions
+
+<!-- Research items not yet resolved.
+     Move blocking ones to `1-requirements.md` §Clarifications as ⛔ BLOCKING entries. -->

package/templates/specs/_template/3-tasks.md

@@ -11,7 +11,7 @@ Plan approved: <!-- date -->
 - One task at a time — finish it completely before moving on
 - Write the test first — it must fail (red) before any implementation; implement until green; then run the full suite
 - Each task touches only what's needed — no cleanup of adjacent code
-- If a task reveals new scope, STOP and update 2-plan.md before continuing
+- If a task reveals ambiguity, contradiction, impossibility, or new scope, STOP and run /impl-gap. If requirements or plan must change, escalate to /spec-amend before editing approved spec files.
 
 ---
 
@@ -49,5 +49,6 @@ Plan approved: <!-- date -->
 
 - [ ] All tasks done
 - [ ] Every acceptance scenario in 1-requirements.md covered by a passing test
+- [ ] /verify completed
 - [ ] /review completed
 - [ ] Spec moved to `specs/_done/<name>/`

package/templates/specs/_template/amendments.md

@@ -0,0 +1,15 @@
+# Change Requests — <Feature Name>
+
+<!-- Populated by /spec-amend. Never edit existing entries — append only.
+     CR numbering is per-spec and monotonic (CR-001, CR-002, …).
+     Rejected CRs stay with status "Rejected" and a one-line reason — never delete history.
+
+     Format:
+     ## CR-NNN — YYYY-MM-DD
+     - **Trigger:** user-requested | gap-NNN | review-finding
+     - **Motive:** why this change is necessary
+     - **Change in requirements:** what sections of 1-requirements.md change, and how
+     - **Change in plan:** what sections of 2-plan.md change, and how
+     - **Affected tasks:** T-XX, T-YY (tasks that may need to redo work or whose verification changes)
+     - **Status:** Pending approval | Approved YYYY-MM-DD | Rejected — <reason>
+-->

package/templates/specs/_template/analysis.md

@@ -0,0 +1,49 @@
+# Cross-Consistency Analysis — <Feature Name>
+
+Date: <YYYY-MM-DD>
+Re-runs overwrite this file. Output is advisory — the human decides whether to amend or accept each gap.
+
+---
+
+## 1. Goal-to-Task Coverage
+
+Every goal ID (G1, G2…) from `1-requirements.md` must appear in at least one task in `3-tasks.md`.
+
+| Goal | Referenced in task(s) | Status |
+|------|-----------------------|--------|
+| G1   | | ✅ / ❌ |
+
+### Missing goals
+<!-- Goals with no referencing task — these are coverage gaps -->
+
+---
+
+## 2. Plan-to-Task Coverage
+
+Every entry in "Components Affected" in `2-plan.md` must appear in at least one task's Changes field.
+
+| Component | Referenced in task(s) | Status |
+|-----------|-----------------------|--------|
+|           | | ✅ / ❌ |
+
+### Missing components
+<!-- Components with no referencing task — may indicate unplanned work or an incomplete task list -->
+
+---
+
+## 3. Scope Creep
+
+Tasks that do not reference any goal ID may be out of scope.
+
+| Task | Goals referenced |
+|------|-----------------|
+|      |                 |
+
+### Findings
+<!-- Tasks with no goal reference — flag for human review. May be legitimate (housekeeping) or genuine scope creep. -->
+
+---
+
+## Conclusion
+
+<!-- Advisory summary. For each miss: state whether to add a task, add a goal, or accept the gap as intentional. -->

package/templates/specs/_template/impl-gaps.md

@@ -0,0 +1,15 @@
+# Implementation Gaps — <Feature Name>
+
+<!-- Populated by /impl-gap during /spec-tasks. Never improvise — always stop and record.
+     GAP numbering is per-spec and monotonic (GAP-001, GAP-002, …).
+     Resolved entries include a Resolution field. If escalated to /spec-amend, include the CR reference.
+
+     Format:
+     ## GAP-NNN — YYYY-MM-DD
+     - **Task:** T-XX (short description)
+     - **Problem:** what the spec says vs. what is blocking
+     - **Impact:** which other tasks are blocked
+     - **Proposed resolution:** agent's suggestion (non-binding)
+     - **Action required:** Approval | Escalate to /spec-amend
+     - **Resolution:** filled in after human direction (and CR-NNN reference if applicable)
+-->

package/templates/specs/_template/verify-report.md

@@ -0,0 +1,43 @@
+# Verify Report — <Feature Name>
+
+Date: <YYYY-MM-DD>
+Spec: specs/<feature>/
+
+---
+
+## Checks
+
+| # | Check | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | All tasks in `3-tasks.md` marked complete | | |
+| 2 | Every goal (G1, G2…) has a referencing task and an observable artifact | | |
+| 3 | Every acceptance scenario has a corresponding passing test | | |
+| 4 | Full test suite passes | | |
+| 5 | No files modified outside "Components Affected" in `2-plan.md` | | |
+| 6 | No unresolved `/impl-gap` entries | | |
+| 7 | No CRs in "Pending approval" status | | |
+
+---
+
+## Detail
+
+### Tasks
+<!-- List each task from 3-tasks.md and its completion artifact (file, test, route, etc.) -->
+
+### Goals
+<!-- List each G-ID from 1-requirements.md with the task(s) that implement it -->
+
+### Scenarios
+<!-- List each BDD scenario with its test file and pass/fail status -->
+
+### Scope
+<!-- List all modified files and confirm each appears in "Components Affected" -->
+
+### Gaps and CRs
+<!-- State of any open impl-gaps.md or amendments.md entries -->
+
+---
+
+## Conclusion
+
+<!-- PASS or FAIL — one sentence. If FAIL, name each failing check and the artifact needed to resolve it. -->