@bhargavvc/sdd-cc 1.35.0 → 1.42.3

package/sdd/templates/README.md

@@ -0,0 +1,77 @@
+# SDD Canonical Artifact Registry
+
+This directory contains the template files for every artifact that SDD workflows officially produce. The table below is the authoritative index: **if a `.planning/` root file is not listed here, `sdd-health` will flag it as W019** (unrecognized artifact).
+
+Agents should query this file before treating a `.planning/` file as authoritative. If the file name does not appear below, it is not a canonical SDD artifact.
+
+---
+
+## `.planning/` Root Artifacts
+
+These files live directly at `.planning/` — not inside phase subdirectories.
+
+| File | Template | Produced by | Purpose |
+|------|----------|-------------|---------|
+| `PROJECT.md` | `project.md` | `/sdd:new-project` | Project identity, goals, requirements summary |
+| `ROADMAP.md` | `roadmap.md` | `/sdd:new-milestone`, `/sdd:new-project` | Phase plan with milestones and progress tracking |
+| `STATE.md` | `state.md` | `/sdd:new-project`, `/sdd:health --repair` | Current session state, active phase, last activity |
+| `REQUIREMENTS.md` | `requirements.md` | `/sdd:new-milestone` | Functional requirements with traceability |
+| `MILESTONES.md` | `milestone.md` | `/sdd:complete-milestone` | Log of completed milestones with accomplishments |
+| `BACKLOG.md` | *(inline)* | `/sdd-add-backlog` | Pending ideas and deferred work |
+| `LEARNINGS.md` | *(inline)* | `/sdd:extract-learnings`, `/sdd:execute-phase` | Phase retrospective learnings for future plans |
+| `THREADS.md` | *(inline)* | `/sdd:thread` | Persistent discussion threads |
+| `config.json` | `config.json` | `/sdd:new-project`, `/sdd:health --repair` | Project-specific SDD configuration |
+| `CLAUDE.md` | `claude-md.md` | `/sdd-profile` | Auto-assembled Claude Code context file |
+| `RETROSPECTIVE.md` | *(inline)* | `/sdd:complete-milestone` | Living milestone retrospective updated at each milestone close |
+
+### Version-stamped artifacts (pattern: `vX.Y-*.md`)
+
+| Pattern | Produced by | Purpose |
+|---------|-------------|---------|
+| `vX.Y-MILESTONE-AUDIT.md` | `/sdd:audit-milestone` | Milestone audit report before archiving |
+
+These files are archived to `.planning/milestones/` by `/sdd:complete-milestone`. Finding them at the `.planning/` root after completion indicates the archive step was skipped.
+
+---
+
+## Phase Subdirectory Artifacts (`.planning/phases/NN-name/`)
+
+These files live inside a phase directory. They are NOT checked by W019 (which only inspects the `.planning/` root).
+
+| File Pattern | Template | Produced by | Purpose |
+|-------------|----------|-------------|---------|
+| `NN-MM-PLAN.md` | `phase-prompt.md` | `/sdd:plan-phase` | Executable implementation plan |
+| `NN-MM-SUMMARY.md` | `summary.md` | `/sdd:execute-phase` | Post-execution summary with learnings |
+| `NN-CONTEXT.md` | `context.md` | `/sdd:discuss-phase` | Scoped discussion decisions for the phase |
+| `NN-RESEARCH.md` | `research.md` | `/sdd:plan-phase`, `/sdd:plan-phase --research-phase <N>` | Technical research for the phase |
+| `NN-VALIDATION.md` | `VALIDATION.md` | `/sdd:plan-phase` (Nyquist) | Validation architecture (Nyquist method) |
+| `NN-UAT.md` | `UAT.md` | `/sdd:validate-phase` | User acceptance test results |
+| `NN-PATTERNS.md` | *(inline)* | `/sdd:plan-phase` (pattern mapper) | Analog file mapping for the phase |
+| `NN-UI-SPEC.md` | `UI-SPEC.md` | `/sdd:ui-phase` | UI design contract |
+| `NN-SECURITY.md` | `SECURITY.md` | `/sdd:secure-phase` | Security threat model |
+| `NN-AI-SPEC.md` | `AI-SPEC.md` | `/sdd:ai-integration-phase` | AI integration spec with eval strategy |
+| `NN-DEBUG.md` | `DEBUG.md` | `/sdd:debug` | Debug session log |
+| `NN-REVIEWS.md` | *(inline)* | `/sdd:review` | Cross-AI review feedback |
+
+---
+
+## Milestone Archive (`.planning/milestones/`)
+
+Files archived by `/sdd:complete-milestone`. These are never checked by W019.
+
+| File Pattern | Source |
+|-------------|--------|
+| `vX.Y-ROADMAP.md` | Snapshot of ROADMAP.md at milestone close |
+| `vX.Y-REQUIREMENTS.md` | Snapshot of REQUIREMENTS.md at milestone close |
+| `vX.Y-MILESTONE-AUDIT.md` | Moved from `.planning/` root |
+| `vX.Y-phases/` | Archived phase directories (if `--archive-phases` used) |
+
+---
+
+## Adding a New Canonical Artifact
+
+When a new workflow produces a `.planning/` root file:
+
+1. Add the file name to `CANONICAL_EXACT` in `sdd/bin/lib/artifacts.cjs`
+2. Add a row to the **`.planning/` Root Artifacts** table above
+3. Add the template to `sdd/templates/` if one exists

package/sdd/templates/UAT.md

@@ -106,7 +106,7 @@ blocked: [N]
 **Gaps:**
 - APPEND only when issue found (YAML format)
 - After diagnosis: fill `root_cause`, `artifacts`, `missing`, `debug_session`
-- This section feeds directly into /sdd-plan-phase --gaps
+- This section feeds directly into /sdd:plan-phase --gaps
 
 </section_rules>
 
@@ -120,7 +120,7 @@ blocked: [N]
 4. UAT.md Gaps section updated with diagnosis:
    - Each gap gets `root_cause`, `artifacts`, `missing`, `debug_session` filled
 5. status → "diagnosed"
-6. Ready for /sdd-plan-phase --gaps with root causes
+6. Ready for /sdd:plan-phase --gaps with root causes
 
 **After diagnosis:**
 ```yaml
@@ -144,7 +144,7 @@ blocked: [N]
 
 <lifecycle>
 
-**Creation:** When /sdd-verify-work starts new session
+**Creation:** When /sdd:verify-work starts new session
 - Extract tests from SUMMARY.md files
 - Set status to "testing"
 - Current Test points to test 1
@@ -171,7 +171,7 @@ blocked: [N]
 - Present summary with outstanding items highlighted
 
 **Resuming partial session:**
-- `/sdd-verify-work {phase}` picks up from first pending/blocked test
+- `/sdd:verify-work {phase}` picks up from first pending/blocked test
 - When all items resolved, status advances to "complete"
 
 **Resume after /clear:**

package/sdd/templates/VALIDATION.md

@@ -29,7 +29,7 @@ created: {date}
 
 - **After every task commit:** Run `{quick run command}`
 - **After every plan wave:** Run `{full suite command}`
-- **Before `/sdd-verify-work`:** Full suite must be green
+- **Before `/sdd:verify-work`:** Full suite must be green
 - **Max feedback latency:** {N} seconds
 
 ---

package/sdd/templates/claude-md.md

@@ -21,7 +21,7 @@ The profile section is managed exclusively by `generate-claude-profile`.
 
 **Fallback text:**
 ```
-Project not yet initialized. Run /sdd-new-project to set up.
+Project not yet initialized. Run /sdd:new-project to set up.
 ```
 
 ### Stack Section
@@ -96,9 +96,9 @@ No project skills found. Add skills to any of: `.claude/skills/`, `.agents/skill
 Before using Edit, Write, or other file-changing tools, start work through a SDD command so planning artifacts and execution context stay in sync.
 
 Use these entry points:
-- `/sdd-quick` for small fixes, doc updates, and ad-hoc tasks
-- `/sdd-debug` for investigation and bug fixing
-- `/sdd-execute-phase` for planned phase work
+- `/sdd:quick` for small fixes, doc updates, and ad-hoc tasks
+- `/sdd:debug` for investigation and bug fixing
+- `/sdd:execute-phase` for planned phase work
 
 Do not make direct repo edits outside a SDD workflow unless the user explicitly asks to bypass it.
 <!-- SDD:workflow-end -->
@@ -109,7 +109,7 @@ Do not make direct repo edits outside a SDD workflow unless the user explicitly
 <!-- SDD:profile-start -->
 ## Developer Profile
 
-> Profile not yet configured. Run `/sdd-profile-user` to generate your developer profile.
+> Profile not yet configured. Run `/sdd:profile-user` to generate your developer profile.
 > This section is managed by `generate-claude-profile` — do not edit manually.
 <!-- SDD:profile-end -->
 ```

package/sdd/templates/config.json

@@ -11,13 +11,26 @@
     "security_asvs_level": 1,
     "security_block_on": "high",
     "discuss_mode": "discuss",
-    "research_before_questions": false
+    "research_before_questions": false,
+    "code_review_command": null,
+    "plan_bounce": false,
+    "plan_bounce_script": null,
+    "plan_bounce_passes": 2,
+    "cross_ai_execution": false,
+    "cross_ai_command": "",
+    "cross_ai_timeout": 300
+  },
+  "ship": {
+    "pr_body_sections": []
   },
   "planning": {
     "commit_docs": true,
     "search_gitignored": false,
     "sub_repos": []
   },
+  "git": {
+    "create_tag": true
+  },
   "parallelization": {
     "enabled": true,
     "plan_level": true,
@@ -44,5 +57,6 @@
     "context_warnings": true
   },
   "project_code": null,
-  "agent_skills": {}
+  "agent_skills": {},
+  "claude_md_path": "./CLAUDE.md"
 }

package/sdd/templates/debug-subagent-prompt.md

@@ -51,7 +51,7 @@ Create: .planning/debug/{slug}.md
 
 ## Usage
 
-**From /sdd-debug:**
+**From /sdd:debug:**
 ```python
 Task(
   prompt=filled_template,

package/sdd/templates/dev-preferences.md

@@ -5,7 +5,7 @@ description: Load developer preferences into this session
 # Developer Preferences
 
 > Generated by SDD on {{generated_at}} from {{data_source}}.
-> Run `/sdd-profile-user --refresh` to regenerate.
+> Run `/sdd:profile-user --refresh` to regenerate.
 
 ## Behavioral Directives
 

package/sdd/templates/discovery.md

@@ -4,7 +4,7 @@ Template for `.planning/phases/XX-name/DISCOVERY.md` - shallow research for libr
 
 **Purpose:** Answer "which library/option should we use" questions during mandatory discovery in plan-phase.
 
-For deep ecosystem research ("how do experts build this"), use `/sdd-research-phase` which produces RESEARCH.md.
+For deep ecosystem research ("how do experts build this"), use `/sdd:plan-phase --research-phase` which produces RESEARCH.md.
 
 ---
 
@@ -142,5 +142,5 @@ Create `.planning/phases/XX-name/DISCOVERY.md`:
 - Niche/complex domains (3D, games, audio, shaders)
 - Need ecosystem knowledge, not just library choice
 - "How do experts build this" questions
-- Use `/sdd-research-phase` for these
+- Use `/sdd:plan-phase --research-phase` for these
 </guidelines>

package/sdd/templates/phase-prompt.md

@@ -142,7 +142,7 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 | `user_setup` | No | Array of human-required setup items (external services) |
 | `must_haves` | Yes | Goal-backward verification criteria (see below) |
 
-**Wave is pre-computed:** Wave numbers are assigned during `/sdd-plan-phase`. Execute-phase reads `wave` directly from frontmatter and groups plans by wave number. No runtime dependency analysis needed.
+**Wave is pre-computed:** Wave numbers are assigned during `/sdd:plan-phase`. Execute-phase reads `wave` directly from frontmatter and groups plans by wave number. No runtime dependency analysis needed.
 
 **Must-haves enable verification:** The `must_haves` field carries goal-backward requirements from planning to execution. After all plans complete, execute-phase spawns a verification subagent that checks these criteria against the actual codebase.
 

package/sdd/templates/planner-subagent-prompt.md

@@ -34,7 +34,7 @@ Template for spawning sdd-planner agent. The agent contains all planning experti
 </planning_context>
 
 <downstream_consumer>
-Output consumed by /sdd-execute-phase
+Output consumed by /sdd:execute-phase
 Plans must be executable prompts with:
 - Frontmatter (wave, depends_on, files_modified, autonomous)
 - Tasks in XML format
@@ -68,7 +68,7 @@ Before returning PLANNING COMPLETE:
 
 ## Usage
 
-**From /sdd-plan-phase (standard mode):**
+**From /sdd:plan-phase (standard mode):**
 ```python
 Task(
   prompt=filled_template,
@@ -77,7 +77,7 @@ Task(
 )
 ```
 
-**From /sdd-plan-phase --gaps (gap closure mode):**
+**From /sdd:plan-phase --gaps (gap closure mode):**
 ```python
 Task(
   prompt=filled_template,  # with mode: gap_closure

package/sdd/templates/project.md

@@ -149,7 +149,7 @@ and implemented by workflows/transition.md and workflows/complete-milestone.md.
 
 For existing codebases:
 
-1. **Map codebase first** via `/sdd-map-codebase`
+1. **Map codebase first** via `/sdd:map-codebase`
 
 2. **Infer Validated requirements** from existing code:
    - What does the codebase actually do?

package/sdd/templates/research.md

@@ -18,7 +18,7 @@ Template for `.planning/phases/XX-name/{phase_num}-RESEARCH.md` - comprehensive
 <user_constraints>
 ## User Constraints (from CONTEXT.md)
 
-**CRITICAL:** If CONTEXT.md exists from /sdd-discuss-phase, copy locked decisions here verbatim. These MUST be honored by the planner.
+**CRITICAL:** If CONTEXT.md exists from /sdd:discuss-phase, copy locked decisions here verbatim. These MUST be honored by the planner.
 
 ### Locked Decisions
 [Copy from CONTEXT.md `## Decisions` section - these are NON-NEGOTIABLE]
@@ -38,6 +38,18 @@ Template for `.planning/phases/XX-name/{phase_num}-RESEARCH.md` - comprehensive
 **If no CONTEXT.md exists:** Write "No user constraints - all decisions at Claude's discretion"
 </user_constraints>
 
+<architectural_responsibility_map>
+## Architectural Responsibility Map
+
+Map each phase capability to its standard architectural tier owner before diving into framework research. This prevents tier misassignment from propagating into plans.
+
+| Capability | Primary Tier | Secondary Tier | Rationale |
+|------------|-------------|----------------|-----------|
+| [capability from phase description] | [Browser/Client, Frontend Server, API/Backend, CDN/Static, or Database/Storage] | [secondary tier or —] | [why this tier owns it] |
+
+**If single-tier application:** Write "Single-tier application — all capabilities reside in [tier]" and omit the table.
+</architectural_responsibility_map>
+
 <research_summary>
 ## Summary
 
@@ -82,6 +94,20 @@ yarn add [packages]
 <architecture_patterns>
 ## Architecture Patterns
 
+### System Architecture Diagram
+
+Architecture diagrams MUST show data flow through conceptual components, not file listings.
+
+Requirements:
+- Show entry points (how data/requests enter the system)
+- Show processing stages (what transformations happen, in what order)
+- Show decision points and branching paths
+- Show external dependencies and service boundaries
+- Use arrows to indicate data flow direction
+- A reader should be able to trace the primary use case from input to output by following the arrows
+
+File-to-implementation mapping belongs in the Component Responsibilities table, not in the diagram.
+
 ### Recommended Project Structure
 ```
 src/
@@ -300,6 +326,20 @@ npm install three @react-three/fiber @react-three/drei @react-three/rapier zusta
 <architecture_patterns>
 ## Architecture Patterns
 
+### System Architecture Diagram
+
+Architecture diagrams MUST show data flow through conceptual components, not file listings.
+
+Requirements:
+- Show entry points (how data/requests enter the system)
+- Show processing stages (what transformations happen, in what order)
+- Show decision points and branching paths
+- Show external dependencies and service boundaries
+- Use arrows to indicate data flow direction
+- A reader should be able to trace the primary use case from input to output by following the arrows
+
+File-to-implementation mapping belongs in the Component Responsibilities table, not in the diagram.
+
 ### Recommended Project Structure
 ```
 src/

package/sdd/templates/spec.md

@@ -0,0 +1,307 @@
+# Phase Spec Template
+
+Template for `.planning/phases/XX-name/{phase_num}-SPEC.md` — locks requirements before discuss-phase.
+
+**Purpose:** Capture WHAT a phase delivers and WHY, with enough precision that requirements are falsifiable. discuss-phase reads this file and focuses on HOW to implement (skipping "what/why" questions already answered here).
+
+**Key principle:** Every requirement must be falsifiable — you can write a test or check that proves it was met or not. Vague requirements like "improve performance" are not allowed.
+
+**Downstream consumers:**
+- `discuss-phase` — reads SPEC.md at startup; treats Requirements, Boundaries, and Acceptance Criteria as locked; skips "what/why" questions
+- `sdd-planner` — reads locked requirements to constrain plan scope
+- `sdd-verifier` — uses acceptance criteria as explicit pass/fail checks
+
+---
+
+## File Template
+
+```markdown
+# Phase [X]: [Name] — Specification
+
+**Created:** [date]
+**Ambiguity score:** [score] (gate: ≤ 0.20)
+**Requirements:** [N] locked
+
+## Goal
+
+[One precise sentence — specific and measurable. NOT "improve X" — instead "X changes from A to B".]
+
+## Background
+
+[Current state from codebase — what exists today, what's broken or missing, what triggers this work. Grounded in code reality, not abstract description.]
+
+## Requirements
+
+1. **[Short label]**: [Specific, testable statement.]
+   - Current: [what exists or does NOT exist today]
+   - Target: [what it should become after this phase]
+   - Acceptance: [concrete pass/fail check — how a verifier confirms this was met]
+
+2. **[Short label]**: [Specific, testable statement.]
+   - Current: [what exists or does NOT exist today]
+   - Target: [what it should become after this phase]
+   - Acceptance: [concrete pass/fail check]
+
+[Continue for all requirements. Each must have Current/Target/Acceptance.]
+
+## Boundaries
+
+**In scope:**
+- [Explicit list of what this phase produces]
+- [Each item is a concrete deliverable or behavior]
+
+**Out of scope:**
+- [Explicit list of what this phase does NOT do] — [brief reason why it's excluded]
+- [Adjacent problems excluded from this phase] — [brief reason]
+
+## Constraints
+
+[Performance, compatibility, data volume, dependency, or platform constraints.
+If none: "No additional constraints beyond standard project conventions."]
+
+## Acceptance Criteria
+
+- [ ] [Pass/fail criterion — unambiguous, verifiable]
+- [ ] [Pass/fail criterion]
+- [ ] [Pass/fail criterion]
+
+[Every acceptance criterion must be a checkbox that resolves to PASS or FAIL.
+No "should feel good", "looks reasonable", or "generally works" — those are not checkboxes.]
+
+## Ambiguity Report
+
+| Dimension          | Score | Min  | Status | Notes                              |
+|--------------------|-------|------|--------|------------------------------------|
+| Goal Clarity       |       | 0.75 |        |                                    |
+| Boundary Clarity   |       | 0.70 |        |                                    |
+| Constraint Clarity |       | 0.65 |        |                                    |
+| Acceptance Criteria|       | 0.70 |        |                                    |
+| **Ambiguity**      |       | ≤0.20|        |                                    |
+
+Status: ✓ = met minimum, ⚠ = below minimum (planner treats as assumption)
+
+## Interview Log
+
+[Key decisions made during the Socratic interview. Format: round → question → answer → decision locked.]
+
+| Round | Perspective    | Question summary         | Decision locked                    |
+|-------|----------------|-------------------------|------------------------------------|
+| 1     | Researcher     | [what was asked]        | [what was decided]                 |
+| 2     | Simplifier     | [what was asked]        | [what was decided]                 |
+| 3     | Boundary Keeper| [what was asked]        | [what was decided]                 |
+
+[If --auto mode: note "auto-selected" decisions with the reasoning Claude used.]
+
+---
+
+*Phase: [XX-name]*
+*Spec created: [date]*
+*Next step: /sdd:discuss-phase [X] — implementation decisions (how to build what's specified above)*
+```
+
+<good_examples>
+
+**Example 1: Feature addition (Post Feed)**
+
+```markdown
+# Phase 3: Post Feed — Specification
+
+**Created:** 2025-01-20
+**Ambiguity score:** 0.12
+**Requirements:** 4 locked
+
+## Goal
+
+Users can scroll through posts from accounts they follow, with new posts available after pull-to-refresh.
+
+## Background
+
+The database has a `posts` table and `follows` table. No feed query or feed UI exists today. The home screen shows a placeholder "Your feed will appear here." This phase builds the feed query, API endpoint, and the feed list component.
+
+## Requirements
+
+1. **Feed query**: Returns posts from followed accounts ordered by creation time, descending.
+   - Current: No feed query exists — `posts` table is queried directly only from profile pages
+   - Target: `GET /api/feed` returns paginated posts from followed accounts, newest first, max 20 per page
+   - Acceptance: Query returns correct posts for a user who follows 3 accounts with known post counts; cursor-based pagination advances correctly
+
+2. **Feed display**: Posts display in a scrollable card list.
+   - Current: Home screen shows static placeholder text
+   - Target: Home screen renders feed cards with author, timestamp, post content, and reaction count
+   - Acceptance: Feed renders without error for 0 posts (empty state shown), 1 post, and 20+ posts
+
+3. **Pull-to-refresh**: User can refresh the feed manually.
+   - Current: No refresh mechanism exists
+   - Target: Pull-down gesture triggers refetch; new posts appear at top of list
+   - Acceptance: After a new post is created in test, pull-to-refresh shows the new post without full app restart
+
+4. **New posts indicator**: When new posts arrive, a banner appears instead of auto-scrolling.
+   - Current: No such mechanism
+   - Target: "3 new posts" banner appears when refetch returns posts newer than the oldest visible post; tapping banner scrolls to top and shows new posts
+   - Acceptance: Banner appears for ≥1 new post, does not appear when no new posts, tap navigates to top
+
+## Boundaries
+
+**In scope:**
+- Feed query (backend) — posts from followed accounts, paginated
+- Feed list UI (frontend) — post cards with author, timestamp, content, reaction counts
+- Pull-to-refresh gesture
+- New posts indicator banner
+- Empty state when user follows no one or no posts exist
+
+**Out of scope:**
+- Creating posts — that is Phase 4
+- Reacting to posts — that is Phase 5
+- Following/unfollowing accounts — that is Phase 2 (already done)
+- Push notifications for new posts — separate backlog item
+
+## Constraints
+
+- Feed query must use cursor-based pagination (not offset) — the database has 500K+ posts and offset pagination is unacceptably slow beyond page 3
+- The feed card component must reuse the existing `<AvatarImage>` component from Phase 2
+
+## Acceptance Criteria
+
+- [ ] `GET /api/feed` returns posts only from followed accounts (not all posts)
+- [ ] `GET /api/feed` supports `cursor` parameter for pagination
+- [ ] Feed renders correctly at 0, 1, and 20+ posts
+- [ ] Pull-to-refresh triggers refetch
+- [ ] New posts indicator appears when posts newer than current view exist
+- [ ] Empty state renders when user follows no one
+
+## Ambiguity Report
+
+| Dimension          | Score | Min  | Status | Notes                            |
+|--------------------|-------|------|--------|----------------------------------|
+| Goal Clarity       | 0.92  | 0.75 | ✓      |                                  |
+| Boundary Clarity   | 0.95  | 0.70 | ✓      | Explicit out-of-scope list       |
+| Constraint Clarity | 0.80  | 0.65 | ✓      | Cursor pagination required       |
+| Acceptance Criteria| 0.85  | 0.70 | ✓      | 6 pass/fail criteria             |
+| **Ambiguity**      | 0.12  | ≤0.20| ✓      |                                  |
+
+## Interview Log
+
+| Round | Perspective     | Question summary              | Decision locked                         |
+|-------|-----------------|------------------------------|-----------------------------------------|
+| 1     | Researcher      | What exists in posts today?  | posts + follows tables exist, no feed  |
+| 2     | Simplifier      | Minimum viable feed?         | Cards + pull-refresh, no auto-scroll   |
+| 3     | Boundary Keeper | What's NOT this phase?       | Creating posts, reactions out of scope |
+| 3     | Boundary Keeper | What does done look like?    | Scrollable feed with 4 card fields     |
+
+---
+
+*Phase: 03-post-feed*
+*Spec created: 2025-01-20*
+*Next step: /sdd:discuss-phase 3 — implementation decisions (card layout, loading skeleton, etc.)*
+```
+
+**Example 2: CLI tool (Database backup)**
+
+```markdown
+# Phase 2: Backup Command — Specification
+
+**Created:** 2025-01-20
+**Ambiguity score:** 0.15
+**Requirements:** 3 locked
+
+## Goal
+
+A `sdd backup` CLI command creates a reproducible database snapshot that can be restored by `sdd restore` (a separate phase).
+
+## Background
+
+No backup tooling exists. The project uses PostgreSQL. Developers currently use `pg_dump` manually — there is no standardized process, no output naming convention, and no CI integration. Three incidents in the last quarter involved restoring from wrong or corrupt dumps.
+
+## Requirements
+
+1. **Backup creation**: CLI command executes a full database backup.
+   - Current: No `backup` subcommand exists in the CLI
+   - Target: `sdd backup` connects to the database (via `DATABASE_URL` env or `--db` flag), runs pg_dump, writes output to `./backups/YYYY-MM-DD_HH-MM-SS.dump`
+   - Acceptance: Running `sdd backup` on a test database creates a `.dump` file; running `pg_restore` on that file recreates the database without error
+
+2. **Network retry**: Transient network failures are retried automatically.
+   - Current: pg_dump fails immediately on network error
+   - Target: Backup retries up to 3 times with 5-second delay; 4th failure exits with code 1 and a message to stderr
+   - Acceptance: Simulating 2 sequential network failures causes 2 retries then success; simulating 4 failures causes exit code 1 and stderr message
+
+3. **Partial cleanup**: Failed backups do not leave corrupt files.
+   - Current: Manual pg_dump leaves partial files on failure
+   - Target: If backup fails after starting, the partial `.dump` file is deleted before exit
+   - Acceptance: After a simulated failure mid-dump, no `.dump` file exists in `./backups/`
+
+## Boundaries
+
+**In scope:**
+- `sdd backup` subcommand (full dump only)
+- Output to `./backups/` directory (created if missing)
+- Network retry (3 attempts)
+- Partial file cleanup on failure
+
+**Out of scope:**
+- `sdd restore` — that is Phase 3
+- Incremental backups — separate backlog item (full dump only for now)
+- S3 or remote storage — separate backlog item
+- Encryption — separate backlog item
+- Scheduled/cron backups — separate backlog item
+
+## Constraints
+
+- Must use `pg_dump` (not a custom query) — ensures compatibility with standard `pg_restore`
+- `--no-retry` flag must be available for CI use (fail fast, no retries)
+
+## Acceptance Criteria
+
+- [ ] `sdd backup` creates a `.dump` file in `./backups/YYYY-MM-DD_HH-MM-SS.dump` format
+- [ ] `sdd backup` uses `DATABASE_URL` env var or `--db` flag for connection
+- [ ] 3 retries on network failure, then exit code 1 with stderr message
+- [ ] `--no-retry` flag skips retries and fails immediately on first error
+- [ ] No partial `.dump` file left after a failed backup
+
+## Ambiguity Report
+
+| Dimension          | Score | Min  | Status | Notes                          |
+|--------------------|-------|------|--------|--------------------------------|
+| Goal Clarity       | 0.90  | 0.75 | ✓      |                                |
+| Boundary Clarity   | 0.95  | 0.70 | ✓      | Explicit out-of-scope list     |
+| Constraint Clarity | 0.75  | 0.65 | ✓      | pg_dump required               |
+| Acceptance Criteria| 0.80  | 0.70 | ✓      | 5 pass/fail criteria           |
+| **Ambiguity**      | 0.15  | ≤0.20| ✓      |                                |
+
+## Interview Log
+
+| Round | Perspective     | Question summary              | Decision locked                         |
+|-------|-----------------|------------------------------|-----------------------------------------|
+| 1     | Researcher      | What backup tooling exists?  | None — pg_dump manual only             |
+| 2     | Simplifier      | Minimum viable backup?       | Full dump only, local only             |
+| 3     | Boundary Keeper | What's NOT this phase?       | Restore, S3, encryption excluded       |
+| 4     | Failure Analyst | What goes wrong on failure?  | Partial files, CI fail-fast needed     |
+
+---
+
+*Phase: 02-backup-command*
+*Spec created: 2025-01-20*
+*Next step: /sdd:discuss-phase 2 — implementation decisions (progress reporting, flag design, etc.)*
+```
+
+</good_examples>
+
+<guidelines>
+**Every requirement needs all three fields:**
+- Current: grounds the requirement in reality — what exists today?
+- Target: the concrete change — not "improve X" but "X becomes Y"
+- Acceptance: the falsifiable check — how does a verifier confirm this?
+
+**Ambiguity Report must reflect the actual interview.** If a dimension is below minimum, mark it ⚠ — the planner knows to treat it as an assumption rather than a locked requirement.
+
+**Interview Log is evidence of rigor.** Don't skip it. It shows that requirements came from discovery, not assumption.
+
+**Boundaries protect the phase from scope creep.** The out-of-scope list with reasoning is as important as the in-scope list. Future phases that touch adjacent areas can point to this SPEC.md to understand what was intentionally excluded.
+
+**SPEC.md is a one-way door for requirements.** discuss-phase will treat these as locked. If requirements change after SPEC.md is written, the user should update SPEC.md first, then re-run discuss-phase.
+
+**SPEC.md does NOT replace CONTEXT.md.** They serve different purposes:
+- SPEC.md: what the phase delivers (requirements, boundaries, acceptance criteria)
+- CONTEXT.md: how the phase will be implemented (decisions, patterns, tradeoffs)
+
+discuss-phase generates CONTEXT.md after reading SPEC.md.
+</guidelines>