@bhargavvc/sdd-cc 1.30.1 → 1.42.3

package/sdd/references/gates.md

@@ -0,0 +1,70 @@
+# Gates Taxonomy
+
+Canonical gate types used across SDD workflows. Every validation checkpoint maps to one of these four types.
+
+---
+
+## Gate Types
+
+### Pre-flight Gate
+**Purpose:** Validates preconditions before starting an operation.
+**Behavior:** Blocks entry if conditions unmet. No partial work created.
+**Recovery:** Fix the missing precondition, then retry.
+**Examples:**
+- Plan-phase checks for REQUIREMENTS.md before planning
+- Execute-phase validates PLAN.md exists before execution
+- Discuss-phase confirms phase exists in ROADMAP.md
+
+### Revision Gate
+**Purpose:** Evaluates output quality and routes to revision if insufficient.
+**Behavior:** Loops back to producer with specific feedback. Bounded by iteration cap.
+**Recovery:** Producer addresses feedback; checker re-evaluates. The loop also escalates early if issue count does not decrease between consecutive iterations (stall detection). After max iterations, escalates unconditionally.
+**Examples:**
+- Plan-checker reviewing PLAN.md (max 3 iterations)
+- Verifier checking phase deliverables against success criteria
+
+### Escalation Gate
+**Purpose:** Surfaces unresolvable issues to the developer for a decision.
+**Behavior:** Pauses workflow, presents options, waits for human input.
+**Recovery:** Developer chooses action; workflow resumes on selected path.
+**Examples:**
+- Revision loop exhausted after 3 iterations
+- Merge conflict during worktree cleanup
+- Ambiguous requirement needing clarification
+
+### Abort Gate
+**Purpose:** Terminates the operation to prevent damage or waste.
+**Behavior:** Stops immediately, preserves state, reports reason.
+**Recovery:** Developer investigates root cause, fixes, restarts from checkpoint.
+**Examples:**
+- Context window critically low during execution
+- STATE.md in error state blocking /sdd-next
+- Verification finds critical missing deliverables
+
+---
+
+## Gate Matrix
+
+| Workflow | Phase | Gate Type | Artifacts Checked | Failure Behavior |
+|----------|-------|-----------|-------------------|------------------|
+| plan-phase | Entry | Pre-flight | REQUIREMENTS.md, ROADMAP.md | Block with missing-file message |
+| plan-phase | Step 12 | Revision | PLAN.md quality | Loop to planner (max 3) |
+| plan-phase | Post-revision | Escalation | Unresolved issues | Surface to developer |
+| execute-phase | Entry | Pre-flight | PLAN.md | Block with missing-plan message |
+| execute-phase | Completion | Revision | SUMMARY.md completeness | Re-run incomplete tasks |
+| verify-work | Entry | Pre-flight | SUMMARY.md | Block with missing-summary |
+| verify-work | Evaluation | Escalation | Failed criteria | Surface gaps to developer |
+| next | Entry | Abort | Error state, checkpoints | Stop with diagnostic |
+
+---
+
+## Implementing Gates
+
+Use this taxonomy when designing or auditing workflow validation points:
+
+- **Pre-flight** gates belong at workflow entry points. They are cheap, deterministic checks that prevent wasted work. If you can verify a precondition with a file-existence check or a config read, use a pre-flight gate.
+- **Revision** gates belong after a producer step where quality varies. Always pair them with an iteration cap to prevent infinite loops. The cap should reflect the cost of each iteration -- expensive operations get fewer retries.
+- **Escalation** gates belong wherever automated resolution is impossible or ambiguous. They are the safety valve between revision loops and abort. Present the developer with clear options and enough context to decide.
+- **Abort** gates belong at points where continuing would cause damage, waste significant resources, or produce meaningless output. They should preserve state so work can resume after the root cause is fixed.
+
+**Selection heuristic:** Start with pre-flight. If the check happens after work is produced, it is a revision gate. If the revision loop cannot resolve the issue, escalate. If continuing is dangerous, abort.

package/sdd/references/git-integration.md

@@ -51,7 +51,7 @@ Phases:
 What to commit:
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: initialize [project-name] ([N] phases)" --files .planning/
+sdd-sdk query commit "docs: initialize [project-name] ([N] phases)" --files .planning/
 ```
 
 </format>
@@ -62,8 +62,11 @@ node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs: initialize [project-nam
 Each task gets its own commit immediately after completion.
 
 > **Parallel agents:** When running as a parallel executor (spawned by execute-phase),
-> use `--no-verify` on all commits to avoid pre-commit hook lock contention.
-> The orchestrator validates hooks once after all agents complete.
+> run commits normally — let pre-commit hooks run. Do NOT pass `--no-verify` by default
+> (#2924). Hooks should fire on the introducing commit; silent bypass violates project
+> CLAUDE.md guidance. If a project explicitly opts out via
+> `workflow.worktree_skip_hooks=true`, the orchestrator surfaces that flag in the
+> executor prompt; absent that signal, hooks run normally.
 
 ```
 {type}({phase}-{plan}): {task-name}
@@ -133,7 +136,7 @@ SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
 What to commit:
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
+sdd-sdk query commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
 ```
 
 **Note:** Code files NOT included - already committed per-task.
@@ -153,7 +156,7 @@ Current: [task name]
 What to commit:
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
+sdd-sdk query commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
 ```
 
 </format>
@@ -284,7 +287,7 @@ Set `commit_docs: false` so planning docs stay local and are not committed to an
 Instead of the standard `commit` command, use `commit-to-subrepo` when `sub_repos` is configured:
 
 ```bash
-node ~/.claude/sdd/bin/sdd-tools.cjs commit-to-subrepo "feat(02-01): add user API" \
+sdd-sdk query commit-to-subrepo "feat(02-01): add user API" \
   --files backend/src/api/users.ts backend/src/types/user.ts frontend/src/components/UserForm.tsx
 ```
 

package/sdd/references/git-planning-commit.md

@@ -1,13 +1,15 @@
 # Git Planning Commit
 
-Commit planning artifacts using the sdd-tools CLI, which automatically checks `commit_docs` config and gitignore status.
+Commit planning artifacts via `sdd-sdk query commit`, which checks `commit_docs` config and gitignore status (same behavior as legacy `sdd-tools.cjs commit`).
 
 ## Commit via CLI
 
-Always use `sdd-tools.cjs commit` for `.planning/` files — it handles `commit_docs` and gitignore checks automatically:
+Pass the message first, then file paths via `--files`. Both `commit` and `commit-to-subrepo` use `--files` to declare the paths to commit.
+
+Always use this for `.planning/` files — it handles `commit_docs` and gitignore checks automatically:
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
+sdd-sdk query commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
 ```
 
 The CLI will return `skipped` (with reason) if `commit_docs` is `false` or `.planning/` is gitignored. No manual conditional checks needed.
@@ -17,7 +19,7 @@ The CLI will return `skipped` (with reason) if `commit_docs` is `false` or `.pla
 To fold `.planning/` file changes into the previous commit:
 
 ```bash
-node "$HOME/.claude/sdd/bin/sdd-tools.cjs" commit "" --files .planning/codebase/*.md --amend
+sdd-sdk query commit "" --files .planning/codebase/*.md --amend
 ```
 
 ## Commit Message Patterns

package/sdd/references/ios-scaffold.md

@@ -0,0 +1,123 @@
+# iOS App Scaffold Reference
+
+Rules and patterns for scaffolding iOS applications. Apply when any plan involves creating a new iOS app target.
+
+---
+
+## Critical Rule: Never Use Package.swift as the Primary Build System for iOS Apps
+
+**NEVER use `Package.swift` with `.executableTarget` (or `.target`) to scaffold an iOS app.** Swift Package Manager executable targets compile as macOS command-line tools — they do not produce `.app` bundles, cannot be signed for iOS devices, and cannot be submitted to the App Store.
+
+**Prohibited pattern:**
+```swift
+// Package.swift — DO NOT USE for iOS apps
+.executableTarget(name: "MyApp", dependencies: [])
+// or
+.target(name: "MyApp", dependencies: [])
+```
+
+Using this pattern produces a macOS CLI binary, not an iOS app. The app will not build for any iOS simulator or device.
+
+---
+
+## Required Pattern: XcodeGen
+
+All iOS app scaffolding MUST use XcodeGen to generate the `.xcodeproj`.
+
+### Step 1 — Install XcodeGen (if not present)
+
+```bash
+brew install xcodegen
+```
+
+### Step 2 — Create `project.yml`
+
+`project.yml` is the XcodeGen spec that describes the project structure. Minimum viable spec:
+
+```yaml
+name: MyApp
+options:
+  bundleIdPrefix: com.example
+  deploymentTarget:
+    iOS: "17.0"
+settings:
+  SWIFT_VERSION: "5.10"
+  IPHONEOS_DEPLOYMENT_TARGET: "17.0"
+targets:
+  MyApp:
+    type: application
+    platform: iOS
+    sources: [Sources/MyApp]
+    settings:
+      PRODUCT_BUNDLE_IDENTIFIER: com.example.MyApp
+      INFOPLIST_FILE: Sources/MyApp/Info.plist
+    scheme:
+      testTargets:
+        - MyAppTests
+  MyAppTests:
+    type: bundle.unit-test
+    platform: iOS
+    sources: [Tests/MyAppTests]
+    dependencies:
+      - target: MyApp
+```
+
+### Step 3 — Generate the .xcodeproj
+
+```bash
+xcodegen generate
+```
+
+This creates `MyApp.xcodeproj` in the project root. Commit `project.yml` but add `*.xcodeproj` to `.gitignore` (regenerate on checkout).
+
+### Step 4 — Standard project layout
+
+```
+MyApp/
+├── project.yml              # XcodeGen spec — commit this
+├── .gitignore               # includes *.xcodeproj
+├── Sources/
+│   └── MyApp/
+│       ├── MyAppApp.swift   # @main entry point
+│       ├── ContentView.swift
+│       └── Info.plist
+└── Tests/
+    └── MyAppTests/
+        └── MyAppTests.swift
+```
+
+---
+
+## iOS Deployment Target Compatibility
+
+Always verify SwiftUI API availability against the project's `IPHONEOS_DEPLOYMENT_TARGET` before using any SwiftUI component.
+
+| API | Minimum iOS |
+|-----|-------------|
+| `NavigationView` | iOS 13 |
+| `NavigationStack` | iOS 16 |
+| `NavigationSplitView` | iOS 16 |
+| `List(selection:)` with multi-select | iOS 17 |
+| `ScrollView` scroll position APIs | iOS 17 |
+| `Observable` macro (`@Observable`) | iOS 17 |
+| `SwiftData` | iOS 17 |
+| `@Bindable` | iOS 17 |
+| `TipKit` | iOS 17 |
+
+**Rule:** If a plan requires a SwiftUI API that exceeds the project's deployment target, either:
+1. Raise the deployment target in `project.yml` (and document the decision), or
+2. Wrap the call in `if #available(iOS NN, *) { ... }` with a fallback implementation.
+
+Do NOT silently use an API that requires a higher iOS version than the declared deployment target — the app will crash at runtime on older devices.
+
+---
+
+## Verification
+
+After running `xcodegen generate`, verify the project builds:
+
+```bash
+xcodebuild -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16' build
+```
+
+A successful build (exit code 0) confirms the scaffold is valid for iOS.

package/sdd/references/mandatory-initial-read.md

@@ -0,0 +1,2 @@
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<required_reading>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.

package/sdd/references/model-profile-resolution.md

@@ -26,6 +26,8 @@ Task(
 
 **Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific opus versions.
 
+If `model_profile` is `"adaptive"`, agents resolve to role-based assignments (opus/sonnet/haiku based on agent type).
+
 If `model_profile` is `"inherit"`, all agents resolve to `"inherit"` (useful for OpenCode `/model`).
 
 ## Usage

package/sdd/references/model-profiles.md

@@ -4,20 +4,67 @@ Model profiles control which Claude model each SDD agent uses. This allows balan
 
 ## Profile Definitions
 
-| Agent | `quality` | `balanced` | `budget` | `inherit` |
-|-------|-----------|------------|----------|-----------|
-| sdd-planner | opus | opus | sonnet | inherit |
-| sdd-roadmapper | opus | sonnet | sonnet | inherit |
-| sdd-executor | opus | sonnet | sonnet | inherit |
-| sdd-phase-researcher | opus | sonnet | haiku | inherit |
-| sdd-project-researcher | opus | sonnet | haiku | inherit |
-| sdd-research-synthesizer | sonnet | sonnet | haiku | inherit |
-| sdd-debugger | opus | sonnet | sonnet | inherit |
-| sdd-codebase-mapper | sonnet | haiku | haiku | inherit |
-| sdd-verifier | sonnet | sonnet | haiku | inherit |
-| sdd-plan-checker | sonnet | sonnet | haiku | inherit |
-| sdd-integration-checker | sonnet | sonnet | haiku | inherit |
-| sdd-nyquist-auditor | sonnet | sonnet | haiku | inherit |
+| Agent | `quality` | `balanced` | `budget` | `adaptive` | `inherit` |
+|-------|-----------|------------|----------|------------|-----------|
+| sdd-planner | opus | opus | sonnet | opus | inherit |
+| sdd-roadmapper | opus | sonnet | sonnet | sonnet | inherit |
+| sdd-executor | opus | sonnet | sonnet | sonnet | inherit |
+| sdd-phase-researcher | opus | sonnet | haiku | sonnet | inherit |
+| sdd-project-researcher | opus | sonnet | haiku | sonnet | inherit |
+| sdd-research-synthesizer | sonnet | sonnet | haiku | haiku | inherit |
+| sdd-debugger | opus | sonnet | sonnet | opus | inherit |
+| sdd-codebase-mapper | sonnet | haiku | haiku | haiku | inherit |
+| sdd-verifier | sonnet | sonnet | haiku | sonnet | inherit |
+| sdd-plan-checker | sonnet | sonnet | haiku | haiku | inherit |
+| sdd-integration-checker | sonnet | sonnet | haiku | haiku | inherit |
+| sdd-nyquist-auditor | sonnet | sonnet | haiku | haiku | inherit |
+
+## Per-Phase-Type Model Map (#3023)
+
+`.planning/config.json` accepts a coarse per-**phase-type** map under the `models` key. Use this when you want tuning at the phase level ("Opus for planning and execution, Sonnet for the rest") without learning the agent taxonomy.
+
+```json
+{
+  "model_profile": "balanced",
+  "models": {
+    "planning": "opus",
+    "discuss": "opus",
+    "research": "sonnet",
+    "execution": "opus",
+    "verification": "sonnet",
+    "completion": "sonnet"
+  },
+  "model_overrides": {
+    "sdd-codebase-mapper": "haiku"
+  }
+}
+```
+
+### Phase-type → agent mapping
+
+| Phase type | Agents |
+|---|---|
+| `planning` | sdd-planner, sdd-roadmapper, sdd-pattern-mapper |
+| `discuss` | (reserved — no subagent today) |
+| `research` | sdd-phase-researcher, sdd-project-researcher, sdd-research-synthesizer, sdd-codebase-mapper, sdd-ui-researcher |
+| `execution` | sdd-executor, sdd-debugger, sdd-doc-writer |
+| `verification` | sdd-verifier, sdd-plan-checker, sdd-integration-checker, sdd-nyquist-auditor, sdd-ui-checker, sdd-ui-auditor, sdd-doc-verifier |
+| `completion` | (reserved — no subagent today) |
+
+### Resolution precedence (highest to lowest)
+
+1. **Per-agent `model_overrides[agent]`** — full IDs accepted; targeted exceptions
+2. **Phase-type `models[phase_type]`** — tier alias only (`opus` / `sonnet` / `haiku` / `inherit`)
+3. **Profile table** — the per-agent column from the active `model_profile`
+4. **Runtime default** — when nothing else applies
+
+### Why two layers above the profile?
+
+- **Profile** is a global tier strategy (everyone runs balanced).
+- **`models`** is coarse phase-level tuning without learning agent names.
+- **`model_overrides`** is per-agent precision (e.g. force `haiku` on `sdd-codebase-mapper` for a fan-out).
+
+The three layers compose: `models` defaults a phase, `model_overrides` carves an exception out of it.
 
 ## Profile Philosophy
 
@@ -37,13 +84,19 @@ Model profiles control which Claude model each SDD agent uses. This allows balan
 - Haiku for research and verification
 - Use when: conserving quota, high-volume work, less critical phases
 
+**adaptive** — Role-based cost optimization
+- Opus for planning and debugging (where reasoning quality has highest impact)
+- Sonnet for execution, research, and verification (follows explicit instructions)
+- Haiku for mapping, checking, and auditing (high volume, structured output)
+- Use when: optimizing cost without sacrificing plan quality, solo development on paid API tiers
+
 **inherit** - Follow the current session model
 - All agents resolve to `inherit`
-- Best when you switch models interactively (for example OpenCode `/model`)
+- Best when you switch models interactively (for example OpenCode or Kilo `/model`)
 - **Required when using non-Anthropic providers** (OpenRouter, local models, etc.) — otherwise SDD may call Anthropic models directly, incurring unexpected costs
 - Use when: you want SDD to follow your currently selected runtime model
 
-## Using Non-Claude Runtimes (Codex, OpenCode, Gemini CLI)
+## Using Non-Claude Runtimes (Codex, OpenCode, Gemini CLI, Kilo)
 
 When installed for a non-Claude runtime, the SDD installer sets `resolve_model_ids: "omit"` in `~/.sdd/defaults.json`. This returns an empty model parameter for all agents, so each agent uses the runtime's default model. No manual setup is needed.
 
@@ -80,17 +133,70 @@ If you're using Claude Code with OpenRouter, a local model, or any non-Anthropic
 
 Without `inherit`, SDD's default `balanced` profile spawns specific Anthropic models (`opus`, `sonnet`, `haiku`) for each agent type, which can result in additional API costs through your non-Anthropic provider.
 
-## Resolution Logic
+## Dynamic Routing with Failure-Tier Escalation (#3024)
 
-Orchestrators resolve model before spawning:
+When `dynamic_routing.enabled = true` in `.planning/config.json`, the resolver picks a model from a tier-mapped table based on the agent's *default tier* (light / standard / heavy) and escalates to the next tier up on orchestrator-detected soft failure.
 
+```json
+{
+  "dynamic_routing": {
+    "enabled": true,
+    "tier_models": {
+      "light":    "haiku",
+      "standard": "sonnet",
+      "heavy":    "opus"
+    },
+    "escalate_on_failure": true,
+    "max_escalations": 1
+  }
+}
 ```
+
+**Agent default tiers** (each agent in `MODEL_PROFILES` declares one):
+
+| Tier | Agents | Use case |
+|---|---|---|
+| `light` | sdd-codebase-mapper, sdd-pattern-mapper, sdd-research-synthesizer, sdd-plan-checker, sdd-integration-checker, sdd-nyquist-auditor, sdd-ui-checker, sdd-ui-auditor, sdd-doc-verifier | Cheap/fast — pure mappers, scanners, low-stakes audits |
+| `standard` | sdd-executor, sdd-phase-researcher, sdd-project-researcher, sdd-verifier, sdd-doc-writer, sdd-ui-researcher | Default workhorse — research, writing, primary verification |
+| `heavy` | sdd-planner, sdd-roadmapper, sdd-debugger | Deep reasoning — already at top, can't escalate further |
+
+**Escalation flow** (orchestrator-driven):
+
+1. Orchestrator spawns agent with `attempt: 0` → resolver returns `tier_models[default_tier]`
+2. If orchestrator marks the result a soft failure, it re-spawns with `attempt: 1` → resolver returns `tier_models[next_tier_up]`
+3. `max_escalations` caps total retries (default 1). Beyond the cap the resolver returns the cap-tier model so the orchestrator can log without burning further budget.
+4. Hard failures (exceptions) bypass escalation and surface immediately.
+
+**Precedence with other tier sources** (highest → lowest):
+
+1. `model_overrides[<agent>]` — full ID, always wins
+2. `dynamic_routing.tier_models[escalated_tier]` — when `enabled: true`
+3. `models[<phase_type>]` — coarse phase-level (#3023)
+4. `model_profile` — global tier strategy
+
+When `dynamic_routing.enabled = false` (default), behavior is identical to today.
+
+## Resolution Logic
+
+Orchestrators resolve model before spawning. The full precedence ladder
+is (highest → lowest):
+
+```text
 1. Read .planning/config.json
-2. Check model_overrides for agent-specific override
-3. If no override, look up agent in profile table
-4. Pass model parameter to Task call
+2. Check model_overrides[<agent>] (full IDs accepted; targeted exceptions)
+3. If dynamic_routing.enabled, return tier_models[escalated_tier]
+   (see §Dynamic Routing — escalation steps tier up per attempt counter)
+4. If no dynamic_routing match, check models[phase_type] for a phase-type tier
+   (see §Per-Phase-Type Model Map for the agent → phase-type mapping)
+5. If no phase-type slot, look up agent in profile table
+6. Pass model parameter to Task call
 ```
 
+The same precedence applies to `reasoning_effort` resolution on runtimes
+that support it (Codex), so `model` and `reasoning_effort` always derive
+from the same tier source — a `models[phase_type]` or
+`dynamic_routing` override flips both.
+
 ## Per-Agent Overrides
 
 Override specific agents without changing the entire profile:
@@ -109,7 +215,7 @@ Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `hai
 
 ## Switching Profiles
 
-Runtime: `/sdd:set-profile <profile>`
+Runtime: `/sdd-set-profile <profile>`
 
 Per-project default: Set in `.planning/config.json`:
 ```json

package/sdd/references/mvp-concepts.md

@@ -0,0 +1,49 @@
+# MVP Concepts — index
+
+Cross-reference for the six MVP-related reference files. Each file has a single, narrow purpose. This index exists so future readers (and agents resolving `@`-refs) can find the right file without grepping the directory.
+
+Canonical domain terms for the concepts named below live in [CONTEXT.md](../../CONTEXT.md) under "Domain terms" — start there if you need a precise definition.
+
+## File map
+
+| File | Purpose | Loaded by |
+|---|---|---|
+| `references/planner-mvp-mode.md` | **Rules.** Vertical-slice planning rules, slice ordering, Walking Skeleton constraints. | `sdd-planner` agent when `MVP_MODE=true` |
+| `references/skeleton-template.md` | **Template.** Shape of `SKELETON.md` for new-project Phase 1 under `--mvp`. | `sdd-planner` agent when the Walking Skeleton gate fires |
+| `references/user-story-template.md` | **Template.** Format and slot definitions for `As a / I want to / So that`. | `sdd-mvp-phase` workflow during interactive prompting; `sdd-planner` when emitting the `## Phase Goal` header |
+| `references/spidr-splitting.md` | **Splitting discipline.** Five-axis decomposition (Spike, Paths, Interfaces, Data, Rules) for stories too large for one phase. | `sdd-mvp-phase` workflow when the user story exceeds size threshold |
+| `references/execute-mvp-tdd.md` | **Gate.** MVP+TDD runtime gate semantics: when it fires, what it checks, halt-and-report protocol, end-of-phase blocking escalation, Behavior-Adding Task definition. | `sdd-executor` agent when `MVP_MODE=true && TDD_MODE=true` |
+| `references/verify-mvp-mode.md` | **UAT framing.** Three-section UAT structure (user-flow → technical → coverage), anti-patterns, `User Flow Coverage` section in VERIFICATION.md. | `sdd-verifier` agent when the phase under verification has `mode: mvp` |
+
+## Concept-to-file map
+
+If you're looking for the canonical statement of a concept, this is where to find it:
+
+- **MVP Mode resolution chain** — `workflows/plan-phase.md` Step 1 (CLI flag → roadmap → config → false). Mirrored in `execute-phase.md` and `verify-work.md`.
+- **`**Mode:** mvp` parser** — `sdd/bin/lib/roadmap.cjs` (`searchPhaseInContent` + `cmdRoadmapAnalyze`). Workflows compare against the parser output, never re-parse.
+- **User Story regex** — `/^As a .+, I want to .+, so that .+\.$/` — applied at runtime by `sdd-verifier` (the user-story-format guard) and `sdd-mvp-phase` (interactive validation).
+- **Behavior-Adding Task predicate** — `references/execute-mvp-tdd.md` (the canonical three-check definition). Applied at runtime by `sdd-executor`.
+- **Walking Skeleton gate condition** — `workflows/plan-phase.md` (Phase 1 + new project + `--mvp` + no prior summaries → emit `SKELETON.md`).
+- **MVP+TDD Gate** (RED→GREEN enforcement) — `references/execute-mvp-tdd.md`.
+- **MVP-mode UAT framing** (user-flow first, technical deferred) — `references/verify-mvp-mode.md`.
+- **Per-phase mode authoring** — `workflows/mvp-phase.md` (writes `**Mode:** mvp` to ROADMAP.md after collecting the user story).
+- **Project-wide mode prompt at init** — `workflows/new-project.md` (Vertical MVP vs Horizontal Layers question).
+
+## Interactions worth knowing
+
+- **`--mvp` and `--prd <file>` together on Phase 1.** Both paths converge at the planner spawn. The PRD express path creates `CONTEXT.md` from the PRD file and continues to the research step; the Walking Skeleton gate fires independently when Phase 1 + new project + `--mvp`. The planner therefore receives both `WALKING_SKELETON=true` and PRD-derived context. This is intentional: the PRD informs what the skeleton should prove.
+- **`MVP_MODE` is all-or-nothing per phase, not per task.** A phase is either MVP-mode or standard. Mixed-mode phases are not supported (PRD #2826 Q1).
+- **`TDD_MODE` is independent of `MVP_MODE`.** TDD can be on without MVP, MVP can be on without TDD. Only the *intersection* (both true) activates the MVP+TDD Gate.
+- **The `sdd-roadmapper` agent makes the MVP/standard decision once at project init** based on `PROJECT_MODE`. Per-phase opt-in/out happens later via `/sdd:mvp-phase` or `/sdd-edit-phase`.
+
+## Tests
+
+Structural contract tests for each integration site live under `tests/`:
+
+- `plan-phase-mvp-flag.test.cjs` — plan-phase MVP_MODE resolution chain
+- `planner-mvp-mode.test.cjs` — sdd-planner agent MVP section
+- `mvp-phase-command.test.cjs`, `mvp-phase-integration.test.cjs`, `mvp-phase-spidr.test.cjs` — `/sdd:mvp-phase`
+- `execute-mvp-tdd-gate.test.cjs`, `executor-mvp-tdd-section.test.cjs` — MVP+TDD Gate
+- `verifier-mvp-section.test.cjs`, `verify-mvp-uat.test.cjs` — verifier UAT framing
+- `new-project-mvp-prompt.test.cjs` — mode prompt at init
+- `progress-mvp-display.test.cjs`, `stats-mvp-display.test.cjs`, `graphify-mvp-viz.test.cjs` — discovery surfaces

package/sdd/references/phase-argument-parsing.md

@@ -14,7 +14,7 @@ From `$ARGUMENTS`:
 The `find-phase` command handles normalization and validation in one step:
 
 ```bash
-PHASE_INFO=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" find-phase "${PHASE}")
+PHASE_INFO=$(sdd-sdk query find-phase "${PHASE}")
 ```
 
 Returns JSON with:
@@ -45,7 +45,7 @@ fi
 Use `roadmap get-phase` to validate phase exists:
 
 ```bash
-PHASE_CHECK=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" roadmap get-phase "${PHASE}" --pick found)
+PHASE_CHECK=$(sdd-sdk query roadmap.get-phase "${PHASE}" --pick found)
 if [ "$PHASE_CHECK" = "false" ]; then
   echo "ERROR: Phase ${PHASE} not found in roadmap"
   exit 1
@@ -57,5 +57,5 @@ fi
 Use `find-phase` for directory lookup:
 
 ```bash
-PHASE_DIR=$(node "$HOME/.claude/sdd/bin/sdd-tools.cjs" find-phase "${PHASE}" --raw)
+PHASE_DIR=$(sdd-sdk query find-phase "${PHASE}" --raw)
 ```

package/sdd/references/planner-antipatterns.md

@@ -0,0 +1,89 @@
+# Planner Anti-Patterns and Specificity Examples
+
+> Reference file for sdd-planner agent. Loaded on-demand via `@` reference.
+> For sub-200K context windows, this content is stripped from the agent prompt and available here for on-demand loading.
+
+## Checkpoint Anti-Patterns
+
+### Bad — Asking human to automate
+
+```xml
+<task type="checkpoint:human-action">
+  <action>Deploy to Vercel</action>
+  <instructions>Visit vercel.com, import repo, click deploy...</instructions>
+</task>
+```
+
+**Why bad:** Vercel has a CLI. Claude should run `vercel --yes`. Never ask the user to do what Claude can automate via CLI/API.
+
+### Bad — Too many checkpoints
+
+```xml
+<task type="auto">Create schema</task>
+<task type="checkpoint:human-verify">Check schema</task>
+<task type="auto">Create API</task>
+<task type="checkpoint:human-verify">Check API</task>
+```
+
+**Why bad:** Verification fatigue. Users should not be asked to verify every small step. Combine into one checkpoint at the end of meaningful work.
+
+### Good — Single verification checkpoint
+
+```xml
+<task type="auto">Create schema</task>
+<task type="auto">Create API</task>
+<task type="auto">Create UI</task>
+<task type="checkpoint:human-verify">
+  <what-built>Complete auth flow (schema + API + UI)</what-built>
+  <how-to-verify>Test full flow: register, login, access protected page</how-to-verify>
+</task>
+```
+
+### Bad — Mixing checkpoints with implementation
+
+A plan should not interleave multiple checkpoint types with implementation tasks. Checkpoints belong at natural verification boundaries, not scattered throughout.
+
+## Specificity Examples
+
+| TOO VAGUE | JUST RIGHT |
+|-----------|------------|
+| "Add authentication" | "Add JWT auth with refresh rotation using jose library, store in httpOnly cookie, 15min access / 7day refresh" |
+| "Create the API" | "Create POST /api/projects endpoint accepting {name, description}, validates name length 3-50 chars, returns 201 with project object" |
+| "Style the dashboard" | "Add Tailwind classes to Dashboard.tsx: grid layout (3 cols on lg, 1 on mobile), card shadows, hover states on action buttons" |
+| "Handle errors" | "Wrap API calls in try/catch, return {error: string} on 4xx/5xx, show toast via sonner on client" |
+| "Set up the database" | "Add User and Project models to schema.prisma with UUID ids, email unique constraint, createdAt/updatedAt timestamps, run prisma db push" |
+
+**Specificity test:** Could a different Claude instance execute the task without asking clarifying questions? If not, add more detail.
+
+## Context Section Anti-Patterns
+
+### Bad — Reflexive SUMMARY chaining
+
+```markdown
+<context>
+@.planning/phases/01-foundation/01-01-SUMMARY.md
+@.planning/phases/01-foundation/01-02-SUMMARY.md  <!-- Does Plan 02 actually need Plan 01's output? -->
+@.planning/phases/01-foundation/01-03-SUMMARY.md  <!-- Chain grows, context bloats -->
+</context>
+```
+
+**Why bad:** Plans are often independent. Reflexive chaining (02 refs 01, 03 refs 02...) wastes context. Only reference prior SUMMARY files when the plan genuinely uses types/exports from that prior plan or a decision from it affects the current plan.
+
+### Good — Selective context
+
+```markdown
+<context>
+@.planning/PROJECT.md
+@.planning/STATE.md
+@.planning/phases/01-foundation/01-01-SUMMARY.md  <!-- Uses User type defined in Plan 01 -->
+</context>
+```
+
+## Scope Reduction Anti-Patterns
+
+**Prohibited language in task actions:**
+- "v1", "v2", "simplified version", "static for now", "hardcoded for now"
+- "future enhancement", "placeholder", "basic version", "minimal implementation"
+- "will be wired later", "dynamic in future phase", "skip for now"
+
+If a decision from CONTEXT.md says "display cost calculated from billing table in impulses", the plan must deliver exactly that. Not "static label /min" as a "v1". If the phase is too complex, recommend a phase split instead of silently reducing scope.