@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/sdd/bin/verify-reapply-patches.cjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Deterministic verifier for the /sdd-reapply-patches Step 5 "Hunk Verification
+ * Gate". For each backed-up patch file, asserts that the user's added lines
+ * (computed from a real diff against the pristine baseline, not from the
+ * LLM's prose summary) survive into the merged output.
+ *
+ * Usage:
+ *   node scripts/verify-reapply-patches.cjs \
+ *     --patches-dir <path>        \  # sdd-local-patches/
+ *     --config-dir <path>         \  # ~/.claude (or runtime equivalent)
+ *     [--pristine-dir <path>]        # sdd-pristine/; if absent, falls back to
+ *                                    # treating every significant backup line as
+ *                                    # required (over-broad but safe for #2969:
+ *                                    # false-positive halts beat silent successes
+ *                                    # on lost content)
+ *     [--json]                       # emit JSON report instead of human text
+ *
+ * Exit codes:
+ *   0 — every user-added line is present in the merged file (gate passes)
+ *   1 — at least one missing line in at least one file (gate fails)
+ *   2 — usage / structural error (e.g. patches dir missing)
+ *
+ * Bug #2969: the Step 5 gate previously trusted Claude's free-text "verified:
+ * yes/no" reporting per hunk. The LLM was filling in `yes` even when content
+ * had been silently dropped. Moving the check to a deterministic script is the
+ * durability fix.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SIGNIFICANT_MIN_CHARS = 12;
+
+function parseArgs(argv) {
+  const opts = { patchesDir: null, configDir: null, pristineDir: null, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--patches-dir') opts.patchesDir = argv[++i];
+    else if (arg === '--config-dir') opts.configDir = argv[++i];
+    else if (arg === '--pristine-dir') opts.pristineDir = argv[++i];
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '--help' || arg === '-h') {
+      process.stdout.write(
+        'usage: verify-reapply-patches.cjs --patches-dir <path> --config-dir <path> [--pristine-dir <path>] [--json]\n',
+      );
+      process.exit(0);
+    } else {
+      process.stderr.write(`unknown argument: ${arg}\n`);
+      process.exit(2);
+    }
+  }
+  return opts;
+}
+
+function isSignificantLine(line) {
+  const trimmed = line.trim();
+  if (trimmed.length < SIGNIFICANT_MIN_CHARS) return false;
+  // Pure punctuation / closing brackets carry too little structural info to
+  // reliably distinguish a survived hunk from incidental similarity.
+  if (/^[\s})\];,]+$/.test(trimmed)) return false;
+  // Generic decorative comments like `// ----` similarly fail the test.
+  if (/^[\s\-=#*/]+$/.test(trimmed)) return false;
+  return true;
+}
+
+/**
+ * Walk a directory, returning every file's path relative to the root.
+ */
+function walk(rootDir, relPrefix = '') {
+  const out = [];
+  if (!fs.existsSync(rootDir)) return out;
+  for (const entry of fs.readdirSync(rootDir, { withFileTypes: true })) {
+    const rel = relPrefix ? path.join(relPrefix, entry.name) : entry.name;
+    const abs = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...walk(abs, rel));
+    } else if (entry.isFile()) {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+/**
+ * Compute the set of "user-added" lines: lines present in the backup but
+ * absent from the pristine baseline. If no pristine is provided, falls back
+ * to using every significant line in the backup (over-broad but safe — favours
+ * false-positive failures over silent successes, which is the right side to
+ * err on for #2969).
+ */
+function computeUserAddedLines(backupContent, pristineContent) {
+  const backupLines = backupContent.split(/\r?\n/);
+  if (!pristineContent) {
+    return backupLines.filter(isSignificantLine);
+  }
+  const pristineSet = new Set(pristineContent.split(/\r?\n/));
+  return backupLines.filter((line) => isSignificantLine(line) && !pristineSet.has(line));
+}
+
+/**
+ * Stable reason codes for the per-file result. Tests assert via
+ * `assert.equal(result.reason, REASON.X)` rather than regex-matching prose,
+ * so the diagnostic surface is a typed enum, not free text.
+ *
+ * Adding a new reason requires updating the REASON map AND the tests'
+ * shape assertion that locks the documented set of codes.
+ */
+const REASON = Object.freeze({
+  OK_NO_USER_LINES_VS_PRISTINE: 'ok_no_user_lines_vs_pristine',
+  OK_NO_SIGNIFICANT_BACKUP_LINES: 'ok_no_significant_backup_lines',
+  FAIL_INSTALLED_MISSING: 'fail_installed_missing',
+  FAIL_INSTALLED_NOT_REGULAR_FILE: 'fail_installed_not_regular_file',
+  FAIL_READ_ERROR: 'fail_read_error',
+  FAIL_USER_LINES_MISSING: 'fail_user_lines_missing',
+});
+
+function verifyFile({ relPath, patchesDir, configDir, pristineDir }) {
+  const backupPath = path.join(patchesDir, relPath);
+  const installedPath = path.join(configDir, relPath);
+  const result = { file: relPath, status: 'ok', missing: [], reason: null };
+
+  if (!fs.existsSync(backupPath) || !fs.statSync(backupPath).isFile()) {
+    return result; // walked entry no longer exists — non-fatal
+  }
+
+  // Installed path checks: must exist, must be a regular file, must be
+  // readable. Anything else is a fail-with-diagnostic, not a crash that
+  // aborts the whole gate run and drops structured output.
+  let installedStat;
+  try {
+    installedStat = fs.statSync(installedPath);
+  } catch {
+    result.status = 'fail';
+    result.reason = REASON.FAIL_INSTALLED_MISSING;
+    return result;
+  }
+  if (!installedStat.isFile()) {
+    result.status = 'fail';
+    result.reason = REASON.FAIL_INSTALLED_NOT_REGULAR_FILE;
+    return result;
+  }
+
+  let backupContent;
+  let installedContent;
+  try {
+    backupContent = fs.readFileSync(backupPath, 'utf8');
+    installedContent = fs.readFileSync(installedPath, 'utf8');
+  } catch {
+    result.status = 'fail';
+    result.reason = REASON.FAIL_READ_ERROR;
+    return result;
+  }
+
+  let pristineContent = null;
+  if (pristineDir) {
+    const pristinePath = path.join(pristineDir, relPath);
+    try {
+      const stat = fs.statSync(pristinePath);
+      if (stat.isFile()) {
+        pristineContent = fs.readFileSync(pristinePath, 'utf8');
+      }
+    } catch {
+      // Pristine missing or unreadable — fall through to over-broad mode.
+    }
+  }
+
+  const userAdded = computeUserAddedLines(backupContent, pristineContent);
+  if (userAdded.length === 0) {
+    // Backup and pristine match exactly (or no significant content) — nothing
+    // to verify but also nothing to lose. Report as ok with diagnostic code.
+    result.reason = pristineContent
+      ? REASON.OK_NO_USER_LINES_VS_PRISTINE
+      : REASON.OK_NO_SIGNIFICANT_BACKUP_LINES;
+    return result;
+  }
+
+  for (const line of userAdded) {
+    if (!installedContent.includes(line)) {
+      result.missing.push(line.trim());
+    }
+  }
+  if (result.missing.length > 0) {
+    result.status = 'fail';
+    result.reason = REASON.FAIL_USER_LINES_MISSING;
+  }
+  return result;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (!opts.patchesDir || !opts.configDir) {
+    process.stderr.write('--patches-dir and --config-dir are required\n');
+    process.exit(2);
+  }
+  if (!fs.existsSync(opts.patchesDir)) {
+    process.stderr.write(`patches dir not found: ${opts.patchesDir}\n`);
+    process.exit(2);
+  }
+  if (!fs.existsSync(opts.configDir)) {
+    process.stderr.write(`config dir not found: ${opts.configDir}\n`);
+    process.exit(2);
+  }
+
+  const files = walk(opts.patchesDir).filter((f) => !f.endsWith('backup-meta.json'));
+  const results = files.map((relPath) =>
+    verifyFile({
+      relPath,
+      patchesDir: opts.patchesDir,
+      configDir: opts.configDir,
+      pristineDir: opts.pristineDir,
+    }),
+  );
+
+  const failures = results.filter((r) => r.status === 'fail');
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ checked: results.length, failures: failures.length, results }, null, 2) + '\n');
+  } else {
+    process.stdout.write(`# Hunk Verification Gate (#2969)\n\n`);
+    process.stdout.write(`Checked: ${results.length} file(s)\n`);
+    process.stdout.write(`Failures: ${failures.length}\n\n`);
+    if (failures.length > 0) {
+      process.stdout.write(`## Files with missing user-added content\n\n`);
+      for (const r of failures) {
+        process.stdout.write(`- ${r.file}\n`);
+        if (r.reason) process.stdout.write(`  reason: ${r.reason}\n`);
+        for (const line of r.missing.slice(0, 5)) {
+          process.stdout.write(`  missing: ${line}\n`);
+        }
+        if (r.missing.length > 5) {
+          process.stdout.write(`  …and ${r.missing.length - 5} more line(s)\n`);
+        }
+      }
+    }
+  }
+
+  process.exit(failures.length > 0 ? 1 : 0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { computeUserAddedLines, isSignificantLine, verifyFile, walk, REASON };

package/sdd/contexts/review.md

@@ -16,6 +16,7 @@ Agent output guidance for review mode. Loaded when `context: review` is set in c
 - Performance — unnecessary allocations, O(n^2) patterns, missing caching
 - Style and consistency — naming, formatting, import order
 - Test coverage — untested branches, missing assertions, flaky patterns
+- Structural Findings (fallow) — machine-derived cross-module facts injected as `<structural_findings>{ findings: [...], summary: { total, unusedExports, duplicates, circularDependencies } }</structural_findings>`. Render in REVIEW.md under `## Structural Findings (fallow)` as a separate section from narrative findings. Treat as ground truth for cross-module facts; do not re-derive.
 
 ## Verbosity
 

package/sdd/references/artifact-types.md

@@ -72,6 +72,24 @@ reads is inert — the consumption mechanism is what gives an artifact meaning.
 - **Location**: `.planning/spikes/SPIKE-NNN/`
 - **Consumed by**: Planner when spike is referenced; `pause-work` for spike context handoff
 
+### Spike README.md / MANIFEST.md (per-spike, via /sdd:spike)
+- **Shape**: YAML frontmatter (spike, name, validates, verdict, related, tags) + run instructions + results
+- **Lifecycle**: Created by `/sdd:spike` → Verified → Wrapped up by `/sdd-spike-wrap-up`
+- **Location**: `.planning/spikes/NNN-name/README.md`, `.planning/spikes/MANIFEST.md`
+- **Consumed by**: `/sdd-spike-wrap-up` for curation; `pause-work` for spike context handoff
+
+### Sketch README.md / MANIFEST.md / index.html (per-sketch)
+- **Shape**: YAML frontmatter (sketch, name, question, winner, tags) + variants as tabbed HTML
+- **Lifecycle**: Created by `/sdd:sketch` → Evaluated → Wrapped up by `/sdd-sketch-wrap-up`
+- **Location**: `.planning/sketches/NNN-name/README.md`, `.planning/sketches/NNN-name/index.html`, `.planning/sketches/MANIFEST.md`
+- **Consumed by**: `/sdd-sketch-wrap-up` for curation; `pause-work` for sketch context handoff
+
+### WRAP-UP-SUMMARY.md (per wrap-up session)
+- **Shape**: Curation results, included/excluded items, feature/design area groupings
+- **Lifecycle**: Created by `/sdd-spike-wrap-up` or `/sdd-sketch-wrap-up`
+- **Location**: `.planning/spikes/WRAP-UP-SUMMARY.md` or `.planning/sketches/WRAP-UP-SUMMARY.md`
+- **Consumed by**: Project history; not read by automated workflows
+
 ---
 
 ## Standing Reference Artifacts

package/sdd/references/autonomous-smart-discuss.md

@@ -0,0 +1,277 @@
+# Smart Discuss — Autonomous Mode
+
+Smart discuss is the autonomous-optimized variant of `sdd-discuss-phase`. It proposes grey area answers in batch tables — the user accepts or overrides per area — then writes an identical CONTEXT.md to what discuss-phase produces.
+
+**Inputs:** `PHASE_NUM` from execute_phase. Run init to get phase paths:
+
+```bash
+PHASE_STATE=$(sdd-sdk query init.phase-op ${PHASE_NUM})
+```
+
+Parse from JSON: `phase_dir`, `phase_slug`, `padded_phase`, `phase_name`.
+
+---
+
+## Sub-step 1: Load prior context
+
+Read project-level and prior phase context to avoid re-asking decided questions.
+
+**Read project files:**
+
+```bash
+cat .planning/PROJECT.md 2>/dev/null || true
+cat .planning/REQUIREMENTS.md 2>/dev/null || true
+cat .planning/STATE.md 2>/dev/null || true
+```
+
+Extract from these:
+- **PROJECT.md** — Vision, principles, non-negotiables, user preferences
+- **REQUIREMENTS.md** — Acceptance criteria, constraints, must-haves vs nice-to-haves
+- **STATE.md** — Current progress, decisions logged so far
+
+**Read all prior CONTEXT.md files:**
+
+```bash
+(find .planning/phases -name "*-CONTEXT.md" 2>/dev/null || true) | sort
+```
+
+For each CONTEXT.md where phase number < current phase:
+- Read the `<decisions>` section — these are locked preferences
+- Read `<specifics>` — particular references or "I want it like X" moments
+- Note patterns (e.g., "user consistently prefers minimal UI", "user rejected verbose output")
+
+**Build internal prior_decisions context** (do not write to file):
+
+```
+<prior_decisions>
+## Project-Level
+- [Key principle or constraint from PROJECT.md]
+- [Requirement affecting this phase from REQUIREMENTS.md]
+
+## From Prior Phases
+### Phase N: [Name]
+- [Decision relevant to current phase]
+- [Preference that establishes a pattern]
+</prior_decisions>
+```
+
+If no prior context exists, continue without — expected for early phases.
+
+---
+
+## Sub-step 2: Scout Codebase
+
+Lightweight codebase scan to inform grey area identification and proposals. Keep under ~5% context.
+
+**Check for existing codebase maps:**
+
+```bash
+ls .planning/codebase/*.md 2>/dev/null || true
+```
+
+**If codebase maps exist:** Read the most relevant ones (CONVENTIONS.md, STRUCTURE.md, STACK.md based on phase type). Extract reusable components, established patterns, integration points. Skip to building context below.
+
+**If no codebase maps, do targeted grep:**
+
+Extract key terms from the phase goal. Search for related files:
+
+```bash
+grep -rl "{term1}\|{term2}" src/ app/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" 2>/dev/null | head -10 || true
+ls src/components/ src/hooks/ src/lib/ src/utils/ 2>/dev/null || true
+```
+
+Read the 3-5 most relevant files to understand existing patterns.
+
+**Build internal codebase_context** (do not write to file):
+- **Reusable assets** — existing components, hooks, utilities usable in this phase
+- **Established patterns** — how the codebase does state management, styling, data fetching
+- **Integration points** — where new code connects (routes, nav, providers)
+
+---
+
+## Sub-step 3: Analyze Phase and Generate Proposals
+
+**Get phase details:**
+
+```bash
+DETAIL=$(sdd-sdk query roadmap.get-phase ${PHASE_NUM})
+```
+
+Extract `goal`, `requirements`, `success_criteria` from the JSON response.
+
+**Infrastructure detection — check FIRST before generating grey areas:**
+
+A phase is pure infrastructure when ALL of these are true:
+1. Goal keywords match: "scaffolding", "plumbing", "setup", "configuration", "migration", "refactor", "rename", "restructure", "upgrade", "infrastructure"
+2. AND success criteria are all technical: "file exists", "test passes", "config valid", "command runs"
+3. AND no user-facing behavior is described (no "users can", "displays", "shows", "presents")
+
+**If infrastructure-only:** Skip Sub-step 4. Jump directly to Sub-step 5 with minimal CONTEXT.md. Display:
+
+```
+Phase ${PHASE_NUM}: Infrastructure phase — skipping discuss, writing minimal context.
+```
+
+Use these defaults for the CONTEXT.md:
+- `<domain>`: Phase boundary from ROADMAP goal
+- `<decisions>`: Single "### Claude's Discretion" subsection — "All implementation choices are at Claude's discretion — pure infrastructure phase"
+- `<code_context>`: Whatever the codebase scout found
+- `<specifics>`: "No specific requirements — infrastructure phase"
+- `<deferred>`: "None"
+
+**If NOT infrastructure — generate grey area proposals:**
+
+Determine domain type from the phase goal:
+- Something users **SEE** → visual: layout, interactions, states, density
+- Something users **CALL** → interface: contracts, responses, errors, auth
+- Something users **RUN** → execution: invocation, output, behavior modes, flags
+- Something users **READ** → content: structure, tone, depth, flow
+- Something being **ORGANIZED** → organization: criteria, grouping, exceptions, naming
+
+Check prior_decisions — skip grey areas already decided in prior phases.
+
+Generate **3-4 grey areas** with **~4 questions each**. For each question:
+- **Pre-select a recommended answer** based on: prior decisions (consistency), codebase patterns (reuse), domain conventions (standard approaches), ROADMAP success criteria
+- Generate **1-2 alternatives** per question
+- **Annotate** with prior decision context ("You decided X in Phase N") and code context ("Component Y exists with Z variants") where relevant
+
+---
+
+## Sub-step 4: Present Proposals Per Area
+
+Present grey areas **one at a time**. For each area (M of N):
+
+Display a table:
+
+```
+### Grey Area {M}/{N}: {Area Name}
+
+| # | Question | ✅ Recommended | Alternative(s) |
+|---|----------|---------------|-----------------|
+| 1 | {question} | {answer} — {rationale} | {alt1}; {alt2} |
+| 2 | {question} | {answer} — {rationale} | {alt1} |
+| 3 | {question} | {answer} — {rationale} | {alt1}; {alt2} |
+| 4 | {question} | {answer} — {rationale} | {alt1} |
+```
+
+Then prompt the user via **AskUserQuestion**:
+- **header:** "Area {M}/{N}"
+- **question:** "Accept these answers for {Area Name}?"
+- **options:** Build dynamically — always "Accept all" first, then "Change Q1" through "Change QN" for each question (up to 4), then "Discuss deeper" last. Cap at 6 explicit options max (AskUserQuestion adds "Other" automatically).
+
+**On "Accept all":** Record all recommended answers for this area. Move to next area.
+
+**On "Change QN":** Use AskUserQuestion with the alternatives for that specific question:
+- **header:** "{Area Name}"
+- **question:** "Q{N}: {question text}"
+- **options:** List the 1-2 alternatives plus "You decide" (maps to Claude's Discretion)
+
+Record the user's choice. Re-display the updated table with the change reflected. Re-present the full acceptance prompt so the user can make additional changes or accept.
+
+**On "Discuss deeper":** Switch to interactive mode for this area only — ask questions one at a time using AskUserQuestion with 2-3 concrete options per question plus "You decide". After 4 questions, prompt:
+- **header:** "{Area Name}"
+- **question:** "More questions about {area name}, or move to next?"
+- **options:** "More questions" / "Next area"
+
+If "More questions", ask 4 more. If "Next area", display final summary table of captured answers for this area and move on.
+
+**On "Other" (free text):** Interpret as either a specific change request or general feedback. Incorporate into the area's decisions, re-display updated table, re-present acceptance prompt.
+
+**Scope creep handling:** If user mentions something outside the phase domain:
+
+```
+"{Feature} sounds like a new capability — that belongs in its own phase.
+I'll note it as a deferred idea.
+
+Back to {current area}: {return to current question}"
+```
+
+Track deferred ideas internally for inclusion in CONTEXT.md.
+
+---
+
+## Sub-step 5: Write CONTEXT.md
+
+After all areas are resolved (or infrastructure skip), write the CONTEXT.md file.
+
+**File path:** `${phase_dir}/${padded_phase}-CONTEXT.md`
+
+Use **exactly** this structure (identical to discuss-phase output):
+
+```markdown
+# Phase {PHASE_NUM}: {Phase Name} - Context
+
+**Gathered:** {date}
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+{Domain boundary statement from analysis — what this phase delivers}
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### {Area 1 Name}
+- {Accepted/chosen answer for Q1}
+- {Accepted/chosen answer for Q2}
+- {Accepted/chosen answer for Q3}
+- {Accepted/chosen answer for Q4}
+
+### {Area 2 Name}
+- {Accepted/chosen answer for Q1}
+- {Accepted/chosen answer for Q2}
+...
+
+### Claude's Discretion
+{Any "You decide" answers collected — note Claude has flexibility here}
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- {From codebase scout — components, hooks, utilities}
+
+### Established Patterns
+- {From codebase scout — state management, styling, data fetching}
+
+### Integration Points
+- {From codebase scout — where new code connects}
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+{Any specific references or "I want it like X" from discussion}
+{If none: "No specific requirements — open to standard approaches"}
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+{Ideas captured but out of scope for this phase}
+{If none: "None — discussion stayed within phase scope"}
+
+</deferred>
+```
+
+Write the file.
+
+**Commit:**
+
+```bash
+sdd-sdk query commit "docs(${PADDED_PHASE}): smart discuss context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+```
+
+Display confirmation:
+
+```
+Created: {path}
+Decisions captured: {count} across {area_count} areas
+```

package/sdd/references/checkpoints.md

@@ -18,6 +18,12 @@ Plans execute autonomously. Checkpoints formalize interaction points where human
 
 **When:** Claude completed automated work, human confirms it works correctly.
 
+> **Default mode (#3309): `workflow.human_verify_mode = end-of-phase`.** New projects do NOT halt mid-flight at `checkpoint:human-verify`. The planner suppresses those task emissions and embeds the verification details into the relevant `auto` task's `<verify><human-check>` block; the verifier harvests every `<verify><human-check>` at end-of-phase (Step 8) and consolidates them into the existing `human_needed` → HUMAN-UAT.md flow in `workflows/execute-phase.md`. The user reviews everything in one batch.
+>
+> **Why this is the default:** 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.
+>
+> Set `workflow.human_verify_mode = mid-flight` in `.planning/config.json` to opt back into the pre-#3309 behavior of halting at every checkpoint. `checkpoint:decision` and `checkpoint:human-action` are unaffected by either value — those gate the work itself, not post-hoc verification.
+
 **Use for:**
 - Visual UI checks (layout, styling, responsiveness)
 - Interactive flows (click through wizard, test user flows)
@@ -759,6 +765,36 @@ timeout 30 bash -c 'until node -e "fetch(\"http://localhost:3000\").then(r=>{pro
 
 </anti_patterns>
 
+<type name="tdd-review">
+## checkpoint:tdd-review (TDD Mode Only)
+
+**When:** All waves in a phase complete and `workflow.tdd_mode` is enabled. Inserted by the execute-phase orchestrator after `aggregate_results`.
+
+**Purpose:** Collaborative review of TDD gate compliance across all `type: tdd` plans in the phase. Advisory — does not block execution.
+
+**Use for:**
+- Verifying RED/GREEN/REFACTOR commit sequence for each TDD plan
+- Surfacing gate violations (missing RED or GREEN commits)
+- Reviewing test quality (tests fail for the right reason)
+- Confirming minimal GREEN implementations
+
+**Structure:**
+```xml
+<task type="checkpoint:tdd-review" gate="advisory">
+  <what-checked>TDD gate compliance for {count} plans in Phase {X}</what-checked>
+  <gate-results>
+    | Plan | RED | GREEN | REFACTOR | Status |
+    |------|-----|-------|----------|--------|
+    | {id} |  ✓  |   ✓   |    ✓     | Pass   |
+  </gate-results>
+  <violations>[List of gate violations, or "None"]</violations>
+  <resume-signal>Review complete — proceed to phase verification</resume-signal>
+</task>
+```
+
+**Auto-mode behavior:** When `workflow._auto_chain_active` or `workflow.auto_advance` is true, the TDD review checkpoint auto-approves (advisory gate — never blocks).
+</type>
+
 <summary>
 
 Checkpoints formalize human-in-the-loop points for verification and decisions, not manual work.