@bhargavvc/sdd-cc 1.35.0 → 1.42.3

package/sdd/references/executor-examples.md

@@ -0,0 +1,110 @@
+# Executor Extended Examples
+
+> Reference file for sdd-executor 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.
+
+## Deviation Rule Examples
+
+### Rule 1 — Auto-fix bugs
+
+**Examples of Rule 1 triggers:**
+- Wrong queries returning incorrect data
+- Logic errors in conditionals
+- Type errors and type mismatches
+- Null pointer exceptions / undefined access
+- Broken validation (accepts invalid input)
+- Security vulnerabilities (XSS, SQL injection)
+- Race conditions in async code
+- Memory leaks from uncleaned resources
+
+### Rule 2 — Auto-add missing critical functionality
+
+**Examples of Rule 2 triggers:**
+- Missing error handling (unhandled promise rejections, no try/catch on I/O)
+- No input validation on user-facing endpoints
+- Missing null checks before property access
+- No auth on protected routes
+- Missing authorization checks (user can access other users' data)
+- No CSRF/CORS configuration
+- No rate limiting on public endpoints
+- Missing DB indexes on frequently queried columns
+- No error logging (failures silently swallowed)
+
+### Rule 3 — Auto-fix blocking issues
+
+**Examples of Rule 3 triggers:**
+- Missing dependency not in package.json
+- Wrong types preventing compilation
+- Broken imports (wrong path, wrong export name)
+- Missing env var required at runtime
+- DB connection error (wrong URL, missing credentials)
+- Build config error (wrong entry point, missing loader)
+- Missing referenced file (import points to non-existent module)
+- Circular dependency preventing module load
+
+### Rule 4 — Ask about architectural changes
+
+**Examples of Rule 4 triggers:**
+- New DB table (not just adding a column)
+- Major schema changes (renaming tables, changing relationships)
+- New service layer (adding a queue, cache, or message bus)
+- Switching libraries/frameworks (e.g., replacing Express with Fastify)
+- Changing auth approach (switching from session to JWT)
+- New infrastructure (adding Redis, S3, etc.)
+- Breaking API changes (removing or renaming endpoints)
+
+## Edge Case Decision Guide
+
+| Scenario | Rule | Rationale |
+|----------|------|-----------|
+| Missing validation on input | Rule 2 | Security requirement |
+| Crashes on null input | Rule 1 | Bug — incorrect behavior |
+| Need new database table | Rule 4 | Architectural decision |
+| Need new column on existing table | Rule 1 or 2 | Depends on context |
+| Pre-existing linting warnings | Out of scope | Not caused by current task |
+| Unrelated test failures | Out of scope | Not caused by current task |
+
+**Decision heuristic:** "Does this affect correctness, security, or ability to complete the current task?"
+- YES → Rules 1-3 (fix automatically)
+- MAYBE → Rule 4 (ask the user)
+- NO → Out of scope (log to deferred-items.md)
+
+## Checkpoint Examples
+
+### Good checkpoint placement
+
+```xml
+<!-- Automate everything, then verify at the end -->
+<task type="auto">Create database schema</task>
+<task type="auto">Create API endpoints</task>
+<task type="auto">Create UI components</task>
+<task type="checkpoint:human-verify">
+  <what-built>Complete auth flow (schema + API + UI)</what-built>
+  <how-to-verify>
+    1. Visit http://localhost:3000/register
+    2. Create account with test@example.com
+    3. Log in with those credentials
+    4. Verify dashboard loads with user name
+  </how-to-verify>
+</task>
+```
+
+### Bad checkpoint placement
+
+```xml
+<!-- Too many checkpoints — causes verification fatigue -->
+<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>
+<task type="auto">Create UI</task>
+<task type="checkpoint:human-verify">Check UI</task>
+```
+
+### Auth gate handling
+
+When an auth error occurs during `type="auto"` execution:
+1. Recognize it as an auth gate (not a bug) — indicators: "Not authenticated", "401", "403", "Please run X login"
+2. STOP the current task
+3. Return a `checkpoint:human-action` with exact auth steps
+4. In SUMMARY.md, document auth gates as normal flow, not deviations

package/sdd/references/gate-prompts.md

@@ -47,7 +47,7 @@ Simple 2-option confirmation for re-planning, rebuild, replace plans, commit.
 4-option escalation for review escalation (max retries exceeded).
 - question: "Phase {N} has failed verification {attempt} times. How should we proceed?"
 - header: "Escalate"
-- options: Accept gaps | Re-plan (via /sdd-plan-phase) | Debug (via /sdd-debug) | Retry
+- options: Accept gaps | Re-plan (via /sdd:plan-phase) | Debug (via /sdd:debug) | Retry
 
 ## Pattern: multi-option-gaps
 4-option gap handler for review gaps-found.
@@ -78,7 +78,7 @@ Up to 4 suggested next actions with selection (status, resume workflows).
 3-option confirmation for quick task scope validation.
 - question: "This task looks complex. Proceed as quick task or use full planning?"
 - header: "Scope"
-- options: Quick task | Full plan (via /sdd-plan-phase) | Revise
+- options: Quick task | Full plan (via /sdd:plan-phase) | Revise
 
 ## Pattern: depth-select
 3-option depth selection for planning workflow preferences.

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>
@@ -274,7 +277,7 @@ Set `commit_docs: false` so planning docs stay local and are not committed to an
 
 ### How It Works
 
-1. **Auto-detection:** During `/sdd-new-project`, directories with their own `.git` folder are detected and offered for selection as sub-repos. On subsequent runs, `loadConfig` auto-syncs the `sub_repos` list with the filesystem — adding newly created repos and removing deleted ones. This means `config.json` may be rewritten automatically when repos change on disk.
+1. **Auto-detection:** During `/sdd:new-project`, directories with their own `.git` folder are detected and offered for selection as sub-repos. On subsequent runs, `loadConfig` auto-syncs the `sub_repos` list with the filesystem — adding newly created repos and removing deleted ones. This means `config.json` may be rewritten automatically when repos change on disk.
 2. **File grouping:** Code files are grouped by their sub-repo prefix (e.g., `backend/src/api/users.ts` belongs to the `backend/` repo).
 3. **Independent commits:** Each sub-repo receives its own atomic commit via `sdd-tools.cjs commit-to-subrepo`. File paths are made relative to the sub-repo root before staging.
 4. **Planning stays local:** The `.planning/` directory is not committed; it acts as cross-repo coordination.
@@ -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/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-profiles.md

@@ -19,6 +19,53 @@ Model profiles control which Claude model each SDD agent uses. This allows balan
 | 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
 
 **quality** - Maximum reasoning power
@@ -75,7 +122,7 @@ If you're using Claude Code with OpenRouter, a local model, or any non-Anthropic
 
 ```bash
 # Via settings command
-/sdd-settings
+/sdd:settings
 # → Select "Inherit" for model profile
 
 # Or manually in .planning/config.json
@@ -86,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:

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.

package/sdd/references/planner-chunked.md

@@ -0,0 +1,49 @@
+# Chunked Mode Return Formats
+
+Used when `plan-phase` spawns `sdd-planner` with `CHUNKED_MODE=true` (triggered by `--chunked`
+flag or `workflow.plan_chunked: true` config). Splits the single long-lived planner Task into
+shorter-lived Tasks to bound the blast radius of Windows stdio hangs.
+
+## Modes
+
+### outline-only
+
+Write **only** `{PHASE_DIR}/{PADDED_PHASE}-PLAN-OUTLINE.md`. Do not write any PLAN.md files.
+Return:
+
+```markdown
+## OUTLINE COMPLETE
+
+**Phase:** {phase-name}
+**Plans:** {N} plan(s) in {M} wave(s)
+
+| Plan ID | Objective | Wave | Depends On | Requirements |
+|---------|-----------|------|-----------|-------------|
+| {padded_phase}-01 | [brief objective] | 1 | none | REQ-001, REQ-002 |
+| {padded_phase}-02 | [brief objective] | 1 | none | REQ-003 |
+```
+
+The orchestrator reads this table, then spawns one single-plan Task per row.
+
+### single-plan
+
+Write **exactly one** `{PHASE_DIR}/{plan_id}-PLAN.md`. Do not write any other plan files.
+Return:
+
+```markdown
+## PLAN COMPLETE
+
+**Plan:** {plan-id}
+**Objective:** {brief}
+**File:** {PHASE_DIR}/{plan-id}-PLAN.md
+**Tasks:** {N}
+```
+
+The orchestrator verifies the file exists on disk after each return, commits it, then moves
+to the next plan entry from the outline.
+
+## Resume Behaviour
+
+If the orchestrator detects that `PLAN-OUTLINE.md` already exists (from a prior interrupted
+run), it skips the outline-only Task and goes directly to single-plan Tasks, skipping any
+`{plan_id}-PLAN.md` files that already exist on disk.

package/sdd/references/planner-human-verify-mode.md

@@ -0,0 +1,57 @@
+# Planner — Human Verification Mode
+
+> Loaded by `sdd-planner` when deciding whether to emit `<task type="checkpoint:human-verify">` tasks. Read `workflow.human_verify_mode` from `.planning/config.json` (default `end-of-phase` since #3309).
+
+## The two modes
+
+### `end-of-phase` (default — issue #3309)
+
+Do **not** emit any `<task type="checkpoint:human-verify">` tasks. Every mid-flight halt costs a full executor cold-start (CLAUDE.md, MEMORY.md, STATE.md, plan re-read on respawn) because subagent context is discarded across the pause; a plan with N human-verify checkpoints pays the cold-start cost N+1 times — measured at "tens of thousands of tokens" per round-trip on real projects. This is the default for that reason.
+
+Instead, fold each would-be verification step into the relevant `auto` task using a `<verify><human-check>` sub-block:
+
+```xml
+<task type="auto">
+  <name>Wire dashboard route</name>
+  <files>app/dashboard/page.tsx, app/api/dashboard/route.ts</files>
+  <action>...</action>
+  <verify>
+    <automated>npm test -- --filter=dashboard</automated>
+    <human-check>
+      <test>Visit http://localhost:3000/dashboard</test>
+      <expected>Sidebar left, content right on desktop &gt;1024px; collapses to hamburger at 768px</expected>
+      <why_human>Visual layout — grep cannot verify breakpoint behavior</why_human>
+    </human-check>
+  </verify>
+  <done>Layout renders correctly across breakpoints</done>
+</task>
+```
+
+The verifier (Step 8) harvests every `<verify><human-check>` block at end-of-phase and consolidates them into the existing `human_needed` → HUMAN-UAT.md path in `workflows/execute-phase.md`. The user reviews everything in one batch instead of paying a cold-start cost per item.
+
+### `mid-flight` (opt-back-in — pre-#3309 behavior)
+
+Set `sdd config-set workflow.human_verify_mode mid-flight` to restore the canonical mid-flight pattern: emit `<task type="checkpoint:human-verify">` tasks at the points where human confirmation is required, and the executor halts at each one to ask the user.
+
+```xml
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Dev server running at http://localhost:3000</what-built>
+  <how-to-verify>
+    1. Visit /dashboard
+    2. Sidebar collapses at 768px
+  </how-to-verify>
+  <resume-signal>"approved" or describe issues</resume-signal>
+</task>
+```
+
+Choose `mid-flight` when you genuinely need the work to stop before any subsequent task runs (e.g., the next task depends on visual confirmation of the previous one), and you accept the cold-start cost as the price of that hard barrier.
+
+## What is *not* affected
+
+`checkpoint:decision` and `checkpoint:human-action` tasks are still emitted in `end-of-phase` mode. Those gate the work itself (a choice the executor needs from the user, or an auth step only the user can perform), not post-hoc verification of completed work. Only `checkpoint:human-verify` is suppressed.
+
+## Compatibility with other modes
+
+- **`workflow.tdd_mode`**: orthogonal. TDD tasks still emit `tdd="true"` and `<behavior>`; the `<verify>` block carries the human-check sub-element when `human_verify_mode = end-of-phase`.
+- **`MVP_MODE`**: orthogonal. Vertical-slice ordering is unchanged. The first task remains a failing end-to-end test; later auto tasks may carry `<verify><human-check>` instead of standalone checkpoint tasks.
+- **`workflow.auto_advance` / `_auto_chain_active`**: in mid-flight mode these auto-approve checkpoint:human-verify halts. In end-of-phase mode there are no halts to auto-approve, so the flags have no effect on this code path.