@bhargavvc/sdd-cc 1.35.0 → 1.42.3

package/sdd/references/sketch-variant-patterns.md

@@ -0,0 +1,81 @@
+# Multi-Variant HTML Patterns
+
+Every sketch produces 2-3 variants in the same HTML file. The user switches between them to compare.
+
+## Tab-Based Variants
+
+The standard approach: a tab bar at the top of the page, each tab shows a different variant.
+
+```html
+<div id="variant-nav" style="position:fixed;top:0;left:0;right:0;z-index:9998;background:var(--color-surface, #fff);border-bottom:1px solid var(--color-border, #e5e5e5);padding:8px 16px;display:flex;gap:8px;font-family:system-ui;">
+  <button class="variant-tab active" onclick="showVariant('a')">A: Sidebar Layout</button>
+  <button class="variant-tab" onclick="showVariant('b')">B: Top Nav</button>
+  <button class="variant-tab" onclick="showVariant('c')">C: Floating Panels</button>
+</div>
+
+<div id="variant-a" class="variant active">
+  <!-- Variant A content -->
+</div>
+<div id="variant-b" class="variant" style="display:none">
+  <!-- Variant B content -->
+</div>
+<div id="variant-c" class="variant" style="display:none">
+  <!-- Variant C content -->
+</div>
+
+<script>
+function showVariant(id) {
+  document.querySelectorAll('.variant').forEach(v => v.style.display = 'none');
+  document.querySelectorAll('.variant-tab').forEach(t => t.classList.remove('active'));
+  document.getElementById('variant-' + id).style.display = 'block';
+  event.target.classList.add('active');
+}
+</script>
+```
+
+Add `padding-top` to the body to account for the fixed tab bar.
+
+## Marking the Winner
+
+After the user picks a direction, add a visual indicator to the winning tab:
+
+```html
+<button class="variant-tab active">A: Sidebar Layout ★ Selected</button>
+```
+
+Keep all variants visible and navigable — the winner is highlighted, not the only option.
+
+## Side-by-Side (for small variants)
+
+When comparing small elements (button styles, card layouts, icon treatments), render them next to each other with labels rather than using tabs:
+
+```html
+<div style="display:grid;grid-template-columns:repeat(3,1fr);gap:24px;padding:24px;">
+  <div>
+    <h3>A: Rounded</h3>
+    <!-- variant content -->
+  </div>
+  <div>
+    <h3>B: Sharp</h3>
+    <!-- variant content -->
+  </div>
+  <div>
+    <h3>C: Pill</h3>
+    <!-- variant content -->
+  </div>
+</div>
+```
+
+## Variant Count
+
+- **First round (dramatic):** 2-3 meaningfully different approaches
+- **Refinement rounds:** 2-3 subtle variations within the chosen direction
+- **Never more than 4** — more than that overwhelms. If there are 5+ options, narrow before showing.
+
+## Synthesis Variants
+
+When the user cherry-picks elements across variants, create a new variant tab labeled descriptively:
+
+```html
+<button class="variant-tab" onclick="showVariant('synth1')">Synthesis: A's layout + C's palette</button>
+```

package/sdd/references/spidr-splitting.md

@@ -0,0 +1,69 @@
+# SPIDR Story Splitting Rules
+
+> Used by `mvp-phase` workflow when the user-supplied story is too large for a single phase. Per PRD decision Q3, SPIDR runs as a **full interactive flow** — not a lightweight check.
+
+## When SPIDR triggers
+
+Trigger SPIDR splitting if **any** of these size signals fire on the user story:
+
+1. **Compound capabilities.** The story names two or more independent user actions joined by "and" (e.g., "register **and** log in **and** reset their password"). Each "and" is a candidate split point.
+2. **Multi-actor.** The story names more than one `[user role]` (e.g., "As a user or admin..."). Each role is a candidate split.
+3. **Length.** The assembled story exceeds ~120 chars on a single line.
+4. **Vague capability.** The capability is a noun phrase, not a verb-noun pair (e.g., "I want to use the dashboard" — needs to specify *which interaction* with the dashboard).
+
+If none of these fire, skip SPIDR entirely and proceed to ROADMAP write.
+
+## The five SPIDR axes
+
+For each axis, ask one targeted question. The user picks the axis that best fits their story; only one axis is applied per split.
+
+### Spike
+
+> "Is there an unknown that needs research before this can be implemented? If so, the spike is its own phase."
+
+If yes: split out a research phase (no acceptance criteria except "we know enough to plan the rest"). The remaining story becomes a follow-up phase.
+
+### Paths
+
+> "Does this feature have a happy path and one or more error/edge paths?"
+
+If yes: split happy path into the first phase, edge paths into follow-ups. Order: happy path first (it proves the slice works), then progressively edge cases.
+
+### Interfaces
+
+> "Does this feature need to work on more than one interface (web, mobile, API, CLI)?"
+
+If yes: split by interface. Web first if user-facing; API first if integration-driven; mobile last unless it's the primary platform.
+
+### Data
+
+> "Does this feature touch multiple data scopes (one user vs. many, single team vs. multi-tenant, small CSV vs. large dataset)?"
+
+If yes: split by scope. Smallest scope first (one user, single team, small data), then expand.
+
+### Rules
+
+> "Does this feature have multiple business rules that could be added incrementally (basic validation first, then complex policy)?"
+
+If yes: split by rule complexity. Minimum viable rules first; complex policy in follow-ups.
+
+## Workflow
+
+When SPIDR triggers, the workflow:
+
+1. Restates the user-supplied story.
+2. Asks "Which SPIDR axis fits best?" with the five options above.
+3. Walks through the chosen axis interactively (one focused question), produces a split proposal: "Phase N (this one): X. Phase N+1: Y. Phase N+2: Z."
+4. Confirms the split with the user.
+5. On accept: writes the FIRST phase's story to the current ROADMAP entry; defers creating new phases for the splits to a follow-up step (the workflow surfaces a list of `/sdd add-phase` invocations the user can run after `mvp-phase` completes — but does not run them automatically, to preserve user control over phase numbering).
+6. On reject: proceeds with the original story unchanged.
+
+## Anti-patterns to reject
+
+- **Splitting by technical layer.** "Phase 1: schema. Phase 2: API. Phase 3: UI." That's horizontal planning. Reject.
+- **Pre-splitting before the user even sees the original.** Always show the user-supplied story first; only offer split if it triggers a size signal.
+- **Splitting more than one axis at once.** SPIDR is one axis per split. If a story needs splitting on two axes (e.g., paths AND data), do paths first, then re-evaluate the resulting smaller stories.
+
+## Reference
+
+See [Mike Cohn — Five Simple But Powerful Ways to Split User Stories](https://www.mountaingoatsoftware.com/blog/five-simple-but-powerful-ways-to-split-user-stories).

package/sdd/references/tdd.md

@@ -247,6 +247,73 @@ Both follow same format: `{type}({phase}-{plan}): {description}`
 - Consistent with overall commit strategy
 </commit_pattern>
 
+<gate_enforcement>
+## Gate Enforcement Rules
+
+When `workflow.tdd_mode` is enabled in config, the RED/GREEN/REFACTOR gate sequence is enforced for all `type: tdd` plans.
+
+### Gate Definitions
+
+| Gate | Required | Commit Pattern | Validation |
+|------|----------|---------------|------------|
+| RED | Yes | `test({phase}-{plan}): ...` | Test exists AND fails before implementation |
+| GREEN | Yes | `feat({phase}-{plan}): ...` | Test passes after implementation |
+| REFACTOR | No | `refactor({phase}-{plan}): ...` | Tests still pass after cleanup |
+
+### Fail-Fast Rules
+
+1. **Unexpected GREEN in RED phase:** If the test passes before any implementation code is written, STOP. The feature may already exist or the test is wrong. Investigate before proceeding.
+2. **Missing RED commit:** If no `test(...)` commit precedes the `feat(...)` commit, the TDD discipline was violated. Flag in SUMMARY.md.
+3. **REFACTOR breaks tests:** Undo the refactor immediately. Commit was premature — refactor in smaller steps.
+
+### Executor Gate Validation
+
+After completing a `type: tdd` plan, the executor validates the git log:
+```bash
+# Check for RED gate commit
+git log --oneline --grep="^test(${PHASE}-${PLAN})" | head -1
+# Check for GREEN gate commit  
+git log --oneline --grep="^feat(${PHASE}-${PLAN})" | head -1
+# Check for optional REFACTOR gate commit
+git log --oneline --grep="^refactor(${PHASE}-${PLAN})" | head -1
+```
+
+If RED or GREEN gate commits are missing, add a `## TDD Gate Compliance` section to SUMMARY.md with the violation details.
+</gate_enforcement>
+
+<end_of_phase_review>
+## End-of-Phase TDD Review Checkpoint
+
+When `workflow.tdd_mode` is enabled, the execute-phase orchestrator inserts a collaborative review checkpoint after all waves complete but before phase verification.
+
+### Review Checkpoint Format
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ TDD REVIEW — Phase {X}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+TDD Plans: {count} | Gate violations: {count}
+
+| Plan | RED | GREEN | REFACTOR | Status |
+|------|-----|-------|----------|--------|
+| {id} |  ✓  |   ✓   |    ✓     | Pass   |
+| {id} |  ✓  |   ✗   |    —     | FAIL   |
+
+{If violations exist:}
+⚠ Gate violations are advisory — review before advancing.
+```
+
+### What the Review Checks
+
+1. **Gate sequence:** Each TDD plan has RED → GREEN commits in order
+2. **Test quality:** RED phase tests fail for the right reason (not import errors or syntax)
+3. **Minimal GREEN:** Implementation is minimal — no premature optimization in GREEN phase
+4. **Refactor discipline:** If REFACTOR commit exists, tests still pass
+
+This checkpoint is advisory — it does not block phase completion but surfaces TDD discipline issues for human review.
+</end_of_phase_review>
+
 <context_budget>
 ## Context Budget
 

package/sdd/references/thinking-partner.md

@@ -69,7 +69,7 @@ Apply this recommendation to the revision? [Yes] / [No, let me decide]
 ### 3. Explore — Approach Comparison (requires #1729)
 
 **When:** During Socratic conversation, when multiple viable approaches emerge.
-**Note:** This integration point will be added when /sdd-explore (#1729) lands.
+**Note:** This integration point will be added when /sdd:explore (#1729) lands.
 
 ---
 

package/sdd/references/universal-anti-patterns.md

@@ -8,13 +8,13 @@ Rules that apply to ALL workflows and agents. Individual workflows may have addi
 
 1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them. Reading agent definitions into the orchestrator wastes context for content automatically injected into subagent sessions.
 2. **Never** inline large files into subagent prompts -- tell agents to read files from disk instead. Agents have their own context windows.
-3. **Read depth scales with context window** -- check `context_window_tokens` in `.planning/config.json`. At < 500000: read only frontmatter, status fields, or summaries. At >= 500000 (1M model): full body reads permitted when content is needed for inline decisions. See `references/context-budget.md` for the complete table.
+3. **Read depth scales with context window** -- check `context_window` in `.planning/config.json`. At < 500000: read only frontmatter, status fields, or summaries. At >= 500000 (1M model): full body reads permitted when content is needed for inline decisions. See `references/context-budget.md` for the complete table.
 4. **Delegate** heavy work to subagents -- the orchestrator routes, it does not build, analyze, research, investigate, or verify.
 5. **Proactive pause warning**: If you have already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider checkpointing progress."
 
 ## File Reading Rules
 
-6. **SUMMARY.md read depth scales with context window** -- at context_window_tokens < 500000: read frontmatter only from prior phase SUMMARYs. At >= 500000: full body reads permitted for direct-dependency phases. Transitive dependencies (2+ phases back) remain frontmatter-only regardless.
+6. **SUMMARY.md read depth scales with context window** -- at context_window < 500000: read frontmatter only from prior phase SUMMARYs. At >= 500000: full body reads permitted for direct-dependency phases. Transitive dependencies (2+ phases back) remain frontmatter-only regardless.
 7. **Never** read full PLAN.md files from other phases -- only current phase plans.
 8. **Never** read `.planning/logs/` files -- only the health workflow reads these.
 9. **Do not** re-read full file contents when frontmatter is sufficient -- frontmatter contains status, key_files, commits, and provides fields. Exception: at >= 500000, re-reading full body is acceptable when semantic content is needed.
@@ -34,7 +34,7 @@ Reference: `references/questioning.md` for the full anti-pattern list.
 
 ## State Management Anti-Patterns
 
-15. **No direct Write/Edit to STATE.md or ROADMAP.md for mutations.** Always use `sdd-tools.cjs` CLI commands (`state update`, `state advance-plan`, `roadmap update-status`) for mutations. Direct Write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.
+15. **No direct Write/Edit to STATE.md or ROADMAP.md for mutations.** Always use `sdd-sdk query` for registered state/roadmap handlers (e.g. `state.update`, `state.advance-plan`, `roadmap.update-plan-progress`), or legacy `node …/sdd-tools.cjs` for CLI-only commands. Direct Write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.
 
 ## Behavioral Rules
 
@@ -53,7 +53,7 @@ Reference: `references/questioning.md` for the full anti-pattern list.
 ## SDD-Specific Rules
 
 24. **Do not** check for `mode === 'auto'` or `mode === 'autonomous'` -- SDD uses `yolo` config flag. Check `yolo: true` for autonomous mode, absence or `false` for interactive mode.
-25. **Always use `sdd-tools.cjs`** (not `sdd-tools.js` or any other variant) -- SDD uses CommonJS for Node.js CLI compatibility.
+25. **Prefer `sdd-sdk query`** for orchestration when a handler exists; when shelling out to the legacy CLI, use **`sdd-tools.cjs`** (not `sdd-tools.js` or any other filename) — SDD ships the programmatic API as CommonJS for Node.js CLI compatibility.
 26. **Plan files MUST follow `{padded_phase}-{NN}-PLAN.md` pattern** (e.g., `01-01-PLAN.md`). Never use `PLAN-01.md`, `plan-01.md`, or any other variation -- sdd-tools detection depends on this exact pattern.
 27. **Do not start executing the next plan before writing the SUMMARY.md for the current plan** -- downstream plans may reference it via `@` includes.
 

package/sdd/references/user-story-template.md

@@ -0,0 +1,58 @@
+# User Story Template (MVP Mode)
+
+> Used by `mvp-phase` workflow and `sdd-planner` agent when `MVP_MODE=true`. Defines the canonical "As a / I want to / So that" format and the rules for converting it into the `**Goal:**` line in ROADMAP.md.
+
+## Canonical format
+
+```
+As a [user role], I want to [capability], so that [outcome].
+```
+
+Three required components:
+
+| Slot | Question | Examples |
+|---|---|---|
+| `[user role]` | Who is the actor? | "new user", "admin", "signed-in customer", "API consumer" |
+| `[capability]` | What can they do? | "register and log in", "upload a CSV", "see my dashboard" |
+| `[outcome]` | Why does it matter? | "I can access my account", "I can bulk-import contacts", "I can see at a glance what needs attention" |
+
+All three must be present. Refuse to assemble a partial story.
+
+## How it lands in ROADMAP.md
+
+The full user story replaces the existing `**Goal:**` line in the phase section:
+
+**Before:**
+```
+### Phase 1: User Auth MVP
+**Goal:** Users can register and log in
+```
+
+**After:**
+```
+### Phase 1: User Auth MVP
+**Goal:** As a new user, I want to register and log in, so that I can access my dashboard.
+**Mode:** mvp
+```
+
+Two structural rules:
+1. The `**Goal:**` line stays on a single line (no line breaks inside the story). If the story is longer than ~120 chars, it should be split into multiple phases via SPIDR (see `spidr-splitting.md`).
+2. The `**Mode:** mvp` line is added immediately below `**Goal:**`. If `**Mode:**` already exists, it is replaced (not duplicated).
+
+## How it lands in PLAN.md
+
+The `sdd-planner` agent (with MVP_MODE=true) emits the user story as the first content under the phase header in `PLAN.md`:
+
+```markdown
+## Phase Goal
+
+**As a** new user, **I want to** register and log in, **so that** I can access my dashboard.
+
+## Acceptance Criteria
+- [ ] ...
+
+## MVP Slice Tasks
+...
+```
+
+Note the bold-keyword formatting (`**As a**`, `**I want to**`, `**so that**`) is for the PLAN.md emit only. The ROADMAP.md `**Goal:**` line uses prose form (the keywords are not bolded inside the goal line, since the goal is itself a single bolded label).

package/sdd/references/verification-overrides.md

@@ -163,10 +163,10 @@ Then re-run verification to apply.
 
 Overrides can also be managed through the verification workflow:
 
-1. Run `/sdd-verify-work` — verification finds gaps
+1. Run `/sdd:verify-work` — verification finds gaps
 2. Review gaps — determine which are intentional deviations
 3. Add override entries to VERIFICATION.md frontmatter
-4. Re-run `/sdd-verify-work` — overrides are applied, remaining gaps shown
+4. Re-run `/sdd:verify-work` — overrides are applied, remaining gaps shown
 
 </creating_overrides>
 
@@ -183,7 +183,7 @@ When a phase is re-verified (e.g., after gap closure):
 
 ### At Milestone Completion
 
-During `/sdd-audit-milestone`, overrides are surfaced in the audit report:
+During `/sdd:audit-milestone`, overrides are surfaced in the audit report:
 
 ```
 ### Verification Overrides ({count} across {phase_count} phases)

package/sdd/references/verify-mvp-mode.md

@@ -0,0 +1,85 @@
+# Verify-Work — MVP Mode UAT Framing
+
+> Loaded by `verify-work` workflow and `sdd-verifier` agent only when the phase under verification has `mode: mvp` in ROADMAP.md. Reframes UAT generation from technical checks to user-flow walk-throughs.
+
+## Core rule
+
+**Show expected, ask if reality matches** — same philosophy as standard verify-work (from `workflows/verify-work.md`). The MVP-mode change is WHAT gets shown:
+
+- **Standard verify-work:** "The API endpoint at /users/register returns 201 with the new user's ID." → user confirms.
+- **MVP verify-work:** "Open the registration page. Fill in 'name', 'email', 'password'. Click Submit. You should see your dashboard with your name in the header." → user confirms.
+
+The user-flow form mirrors what a real user does: open, fill, click, see. No HTTP verbs, no JSON shapes, no error codes.
+
+## When this framing applies
+
+The framing fires when:
+- The phase under verification has `**Mode:** mvp` in ROADMAP.md (parsed via `sdd-sdk query roadmap.get-phase --pick mode`).
+- AND the phase has a user-story-formatted goal (set by `/sdd mvp-phase` per Phase 2): "As a [user role], I want to [capability], so that [outcome]."
+
+If the phase has `mode: mvp` but the goal is NOT in user-story format, the verifier surfaces this as a discrepancy and asks the user to run `/sdd mvp-phase` to reformat the goal — same pattern as the planner agent under MVP_MODE (per `references/planner-mvp-mode.md`).
+
+## Generated UAT script structure under MVP mode
+
+The UAT script generated by `verify-work` under MVP mode has THREE sections, in this exact order:
+
+### 1. User-flow walk-through (always first, always required)
+
+Derive ordered steps from the phase's user-story goal:
+
+1. The first step opens the entry point ("Open the app", "Navigate to /register", "Run `sdd mvp-phase 1`").
+2. Each subsequent step is one user action: fill, click, type, observe.
+3. The final step asserts the user-visible outcome from the `[outcome]` clause of the user story.
+
+Format each step as: "**Step N: [action]** — Expected: [what the user should see]". The user responds with one of:
+- `yes` / `y` / `next` / empty → step passes
+- Anything else → step is logged as an issue, and the script halts (do not proceed to step N+1 with a broken N).
+
+If ALL user-flow steps pass, advance to section 2. If any step fails, the verdict is FAIL — do not run technical checks.
+
+### 2. Technical checks (only if section 1 passes)
+
+After the user flow passes, run the technical checks that would normally run in non-MVP mode:
+- API endpoint schema verification (if the phase shipped APIs)
+- Error state behavior (4xx, 5xx codes; invalid input handling)
+- Edge cases (empty data, large data, concurrent requests if applicable)
+- Cross-browser / cross-runtime checks (if applicable)
+
+These are the same checks `verify-work` would run without MVP mode — just deferred until the user flow proves the slice actually works for a user.
+
+### 3. Coverage check (always last, always required)
+
+Verify that the user-story `[outcome]` clause is observably true in the codebase:
+- If the outcome is "I can access my dashboard", verify a dashboard route exists and renders for an authenticated user.
+- If the outcome is "I can bulk-import contacts", verify the import path produces persisted records.
+
+Coverage is a goal-backward check: "did this phase deliver what its user story promised?" — sourced from the existing `sdd-verifier` agent's goal-backward methodology, narrowed to the user story.
+
+## Anti-patterns to reject under MVP mode
+
+- **Lead with technical checks.** "Step 1: GET /api/users/me returns 200." Reject. The user does not see API endpoints. Reorder so a user action comes first.
+- **Schema-as-feature.** "User has a `name` field on the User model." Reject. The user does not see database fields. Express the same check as a user-visible outcome ("the user's name appears in the dashboard header").
+- **Skip user flow because the test passed.** The unit test passing in CI is not evidence that the user flow works. The user-flow walk-through is mandatory under MVP mode even when all unit tests are green.
+
+## Compatibility with existing verify-work philosophy
+
+The "show expected, ask if reality matches" model is preserved. The user still types `yes` / `next` / empty to advance. The UAT.md state file format is unchanged. Only the WHAT changes — under MVP mode, the "expected" is a user-visible outcome rather than a technical assertion.
+
+## Output: VERIFICATION.md changes under MVP mode
+
+The `sdd-verifier` agent produces `VERIFICATION.md`. Under MVP mode, the report adds a top-level "User Flow Coverage" section that maps each step of the user story to evidence in the codebase:
+
+```markdown
+## User Flow Coverage
+
+User story: «As a new user, I want to register and log in, so that I can access my dashboard.»
+
+| Step | Expected | Evidence | Status |
+|------|----------|----------|--------|
+| Register | Form at /register accepts name/email/password | src/app/register/page.tsx:12 (form component) | ✓ |
+| Submit | Persists user, redirects to /dashboard | src/api/register/route.ts:34 (db.insert + redirect) | ✓ |
+| See dashboard | Dashboard page renders, shows user's name | src/app/dashboard/page.tsx:8 (greeting line) | ✓ |
+| Outcome | "Access my dashboard" — user lands on a populated page | dashboard route + greeting both verified above | ✓ |
+```
+
+Standard technical-check sections of VERIFICATION.md remain (API verification, error handling, etc.) but are appended below "User Flow Coverage", not above.

package/sdd/references/workstream-flag.md

@@ -93,19 +93,19 @@ This ensures workstream scope chains automatically through the workflow:
 ## CLI Usage
 
 ```bash
-# All sdd-tools commands accept --ws
-node sdd-tools.cjs state json --ws feature-a
-node sdd-tools.cjs find-phase 3 --ws feature-b
+# All sdd-sdk query commands accept --ws
+sdd-sdk query state.json --ws feature-a
+sdd-sdk query find-phase 3 --ws feature-b
 
 # Session-local switching without --ws on every command
-SDD_SESSION_KEY=my-terminal-a node sdd-tools.cjs workstream set feature-a
-SDD_SESSION_KEY=my-terminal-a node sdd-tools.cjs state json
-SDD_SESSION_KEY=my-terminal-b node sdd-tools.cjs workstream set feature-b
-SDD_SESSION_KEY=my-terminal-b node sdd-tools.cjs state json
+SDD_SESSION_KEY=my-terminal-a sdd-sdk query workstream.set feature-a
+SDD_SESSION_KEY=my-terminal-a sdd-sdk query state.json
+SDD_SESSION_KEY=my-terminal-b sdd-sdk query workstream.set feature-b
+SDD_SESSION_KEY=my-terminal-b sdd-sdk query state.json
 
 # Workstream CRUD
-node sdd-tools.cjs workstream create <name>
-node sdd-tools.cjs workstream list
-node sdd-tools.cjs workstream status <name>
-node sdd-tools.cjs workstream complete <name>
+sdd-sdk query workstream.create <name>
+sdd-sdk query workstream.list
+sdd-sdk query workstream.status <name>
+sdd-sdk query workstream.complete <name>
 ```

package/sdd/references/worktree-path-safety.md

@@ -0,0 +1,89 @@
+# Worktree Path Safety
+
+Guards for executor agents running inside Claude Code worktrees. Three checks
+must run before any staging, Edit, or Write operation in worktree mode.
+
+---
+
+## Worktree branch check (run once at spawn-time)
+
+FIRST ACTION: HEAD assertion MUST run before any reset/checkout. Worktrees
+spawned by Claude Code's `isolation="worktree"` use the `worktree-agent-<id>`
+namespace. If HEAD is on a protected ref (main/master/develop/trunk/release/*)
+or detached, HALT — do NOT self-recover by force-rewinding via `git update-ref`,
+that destroys concurrent commits in multi-active scenarios (#2924). Only after
+this passes is `git reset --hard` safe (#2015 — affects all platforms).
+
+```bash
+HEAD_REF=$(git symbolic-ref --quiet HEAD || echo "DETACHED")
+ACTUAL_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+if [ "$HEAD_REF" = "DETACHED" ] || echo "$ACTUAL_BRANCH" | grep -Eq '^(main|master|develop|trunk|release/.*)$'; then
+  echo "FATAL: worktree HEAD on '$ACTUAL_BRANCH' (expected worktree-agent-*); refusing to self-recover via 'git update-ref' (#2924)." >&2
+  exit 1
+fi
+if ! echo "$ACTUAL_BRANCH" | grep -Eq '^worktree-agent-[A-Za-z0-9._/-]+$'; then
+  echo "FATAL: worktree HEAD '$ACTUAL_BRANCH' is not in the worktree-agent-* namespace; refusing to commit (#2924)." >&2
+  exit 1
+fi
+ACTUAL_BASE=$(git merge-base HEAD {EXPECTED_BASE})
+if [ "$ACTUAL_BASE" != "{EXPECTED_BASE}" ]; then
+  git reset --hard {EXPECTED_BASE}
+  [ "$(git rev-parse HEAD)" != "{EXPECTED_BASE}" ] && { echo "ERROR: could not correct worktree base"; exit 1; }
+fi
+```
+
+Per-commit HEAD assertion: `agents/sdd-executor.md` `<task_commit_protocol>` step 0.
+
+---
+
+## cwd-drift sentinel — step 0a (#3097)
+
+A prior Bash call may have `cd`'d out of the worktree into the main repo. When
+that happens `[ -f .git ]` is false (main repo's `.git` is a directory), silently
+skipping all worktree guards. The sentinel captures the spawn-time toplevel and
+detects drift before every commit.
+
+```bash
+if [ -f .git ]; then  # we are in a worktree
+  WT_GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
+  case "$WT_GIT_DIR" in
+    *.git/worktrees/*)
+      SENTINEL="$WT_GIT_DIR/sdd-spawn-toplevel"
+      [ ! -f "$SENTINEL" ] && git rev-parse --show-toplevel > "$SENTINEL" 2>/dev/null
+      EXPECTED_TL=$(cat "$SENTINEL" 2>/dev/null)
+      ACTUAL_TL=$(git rev-parse --show-toplevel 2>/dev/null)
+      if [ -n "$EXPECTED_TL" ] && [ "$ACTUAL_TL" != "$EXPECTED_TL" ]; then
+        echo "FATAL: cwd drifted from spawn-time worktree root (#3097)" >&2
+        echo "  Spawn-time: $EXPECTED_TL" >&2
+        echo "  Current:    $ACTUAL_TL" >&2
+        echo "RECOVERY: cd \"$EXPECTED_TL\" before staging, then re-run this commit." >&2
+        exit 1
+      fi
+      ;;
+  esac
+fi
+```
+
+---
+
+## Absolute-path guard — step 0b (#3099)
+
+Edit/Write calls using absolute paths constructed from the **orchestrator's** `pwd`
+(main repo root) will resolve to the main repo, not the worktree. Writes land in
+the wrong directory; `git commit` from the worktree sees a clean tree and the work
+is silently lost.
+
+Before any Edit or Write using an absolute path:
+
+```bash
+WT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+# Fail fast if ABS_PATH resolves outside the worktree
+if [[ "$ABS_PATH" != "$WT_ROOT"* ]]; then
+  echo "WARNING: $ABS_PATH is outside the worktree ($WT_ROOT)" >&2
+  echo "Use a relative path or recompute the absolute path from WT_ROOT." >&2
+fi
+```
+
+**Prefer relative paths** for all Edit/Write operations. When an absolute path is
+unavoidable, always derive it from `git rev-parse --show-toplevel` run inside the
+worktree — never from `pwd` captured in the orchestrator context.

package/sdd/templates/AI-SPEC.md

@@ -1,6 +1,6 @@
 # AI-SPEC — Phase {N}: {phase_name}
 
-> AI design contract generated by `/sdd-ai-integration-phase`. Consumed by `sdd-planner` and `sdd-eval-auditor`.
+> AI design contract generated by `/sdd:ai-integration-phase`. Consumed by `sdd-planner` and `sdd-eval-auditor`.
 > Locks framework selection, implementation guidance, and evaluation strategy before planning begins.
 
 ---

package/sdd/templates/DEBUG.md

@@ -20,7 +20,9 @@ updated: [ISO timestamp]
 hypothesis: [current theory being tested]
 test: [how testing it]
 expecting: [what result means if true/false]
-next_action: [immediate next step]
+next_action: [immediate next step — be specific, not "continue investigating"]
+reasoning_checkpoint: null  <!-- populated before every fix attempt — see structured_returns -->
+tdd_checkpoint: null  <!-- populated when tdd_mode is active after root cause confirmed -->
 
 ## Symptoms
 <!-- Written during gathering, then immutable -->
@@ -69,7 +71,10 @@ files_changed: []
 - OVERWRITE entirely on each update
 - Always reflects what Claude is doing RIGHT NOW
 - If Claude reads this after /clear, it knows exactly where to resume
-- Fields: hypothesis, test, expecting, next_action
+- Fields: hypothesis, test, expecting, next_action, reasoning_checkpoint, tdd_checkpoint
+- `next_action`: must be concrete and actionable — bad: "continue investigating"; good: "Add logging at line 47 of auth.js to observe token value before jwt.verify()"
+- `reasoning_checkpoint`: OVERWRITE before every fix_and_verify — five-field structured reasoning record (hypothesis, confirming_evidence, falsification_test, fix_rationale, blind_spots)
+- `tdd_checkpoint`: OVERWRITE during TDD red/green phases — test file, name, status, failure output
 
 **Symptoms:**
 - Written during initial gathering phase
@@ -99,7 +104,7 @@ files_changed: []
 
 <lifecycle>
 
-**Creation:** Immediately when /sdd-debug is called
+**Creation:** Immediately when /sdd:debug is called
 - Create file with trigger from user input
 - Set status to "gathering"
 - Current Focus: next_action = "gather symptoms"