claude-code-pilot 3.2.0 → 3.3.1

package/src/lib/project-detect.js

@@ -3,8 +3,6 @@
  *
  * Cross-platform (Windows, macOS, Linux) project type detection
  * by inspecting files in the working directory.
- *
- * Resolves: https://github.com/affaan-m/everything-claude-code/issues/293
  */
 
 const fs = require('fs');

package/src/lib/shell-substitution.js

@@ -0,0 +1,499 @@
+'use strict';
+
+/**
+ * Shell substitution / subshell / brace-group extractors.
+ *
+ * Ported into CCP (re-authored from ECC `744f4169`) as the sole non-stdlib
+ * dependency of the GateGuard fact-forcing hook (src/hooks/ccp-write-gateguard.js).
+ * Pure, stdlib-only logic — no requires, no I/O. Other PreToolUse hooks that need
+ * the same "scan inside `$(...)`, backticks, `(...)`, and `{ ...; }`" behavior can
+ * reuse it without duplicating the parser.
+ */
+
+/**
+ * Extract executable command-substitution bodies from a shell line.
+ *
+ * Single quotes are literal, so substitutions inside them are ignored;
+ * double quotes still permit substitutions, so those bodies are scanned
+ * before quoted text is stripped. Returns each substitution body plus
+ * any nested substitutions discovered recursively.
+ *
+ * @param {string} input
+ * @returns {string[]}
+ */
+function extractCommandSubstitutions(input) {
+  const source = String(input || '');
+  const substitutions = [];
+  let inSingle = false;
+  let inDouble = false;
+
+  for (let i = 0; i < source.length; i++) {
+    const ch = source[i];
+    const prev = source[i - 1];
+
+    if (ch === '\\' && !inSingle) {
+      i += 1;
+      continue;
+    }
+
+    if (ch === "'" && !inDouble && prev !== '\\') {
+      inSingle = !inSingle;
+      continue;
+    }
+
+    if (ch === '"' && !inSingle && prev !== '\\') {
+      inDouble = !inDouble;
+      continue;
+    }
+
+    if (inSingle) {
+      continue;
+    }
+
+    if (ch === '`') {
+      let body = '';
+      i += 1;
+      while (i < source.length) {
+        const inner = source[i];
+        if (inner === '\\') {
+          body += inner;
+          if (i + 1 < source.length) {
+            body += source[i + 1];
+            i += 2;
+            continue;
+          }
+        }
+        if (inner === '`') {
+          break;
+        }
+        body += inner;
+        i += 1;
+      }
+      if (body.trim()) {
+        substitutions.push(body);
+        substitutions.push(...extractCommandSubstitutions(body));
+      }
+      continue;
+    }
+
+    if (ch === '$' && source[i + 1] === '(') {
+      let depth = 1;
+      let body = '';
+      let bodyInSingle = false;
+      let bodyInDouble = false;
+      i += 2;
+      while (i < source.length && depth > 0) {
+        const inner = source[i];
+        const innerPrev = source[i - 1];
+        if (inner === '\\' && !bodyInSingle) {
+          body += inner;
+          if (i + 1 < source.length) {
+            body += source[i + 1];
+            i += 2;
+            continue;
+          }
+        }
+        if (inner === "'" && !bodyInDouble && innerPrev !== '\\') {
+          bodyInSingle = !bodyInSingle;
+        } else if (inner === '"' && !bodyInSingle && innerPrev !== '\\') {
+          bodyInDouble = !bodyInDouble;
+        } else if (!bodyInSingle && !bodyInDouble) {
+          if (inner === '(') {
+            depth += 1;
+          } else if (inner === ')') {
+            depth -= 1;
+            if (depth === 0) {
+              break;
+            }
+          }
+        }
+        body += inner;
+        i += 1;
+      }
+      if (body.trim()) {
+        substitutions.push(body);
+        substitutions.push(...extractCommandSubstitutions(body));
+      }
+    }
+  }
+
+  return substitutions;
+}
+
+/**
+ * Extract bodies of plain `(...)` subshell groups.
+ *
+ * Bash treats `(npm run dev)` as a subshell that executes its contents, but
+ * the regex-light segment splitters used by our PreToolUse hooks don't peer
+ * inside those parens. This helper finds top-level `(...)` groups (skipping
+ * `$(...)` command substitutions and backticks, which `extractCommandSubstitutions`
+ * already covers) and returns each body, recursing for nested groups.
+ *
+ * Quote semantics:
+ * - Single quotes are literal: `'( ... )'` is a string, not a subshell.
+ * - Double quotes are literal *for parens*: `"( ... )"` is a string too —
+ *   bash only honors `$( )` inside double quotes, not bare `( )`.
+ *
+ * @param {string} input
+ * @returns {string[]}
+ */
+function extractSubshellGroups(input) {
+  const source = String(input || '');
+  const groups = [];
+  let inSingle = false;
+  let inDouble = false;
+
+  for (let i = 0; i < source.length; i++) {
+    const ch = source[i];
+    const prev = source[i - 1];
+
+    if (ch === '\\' && !inSingle) {
+      i += 1;
+      continue;
+    }
+
+    if (ch === "'" && !inDouble && prev !== '\\') {
+      inSingle = !inSingle;
+      continue;
+    }
+
+    if (ch === '"' && !inSingle && prev !== '\\') {
+      inDouble = !inDouble;
+      continue;
+    }
+
+    if (inSingle || inDouble) {
+      continue;
+    }
+
+    if (ch === '$' && source[i + 1] === '(') {
+      let depth = 1;
+      let skipInSingle = false;
+      let skipInDouble = false;
+      i += 2;
+      while (i < source.length && depth > 0) {
+        const inner = source[i];
+        const innerPrev = source[i - 1];
+        if (inner === '\\' && !skipInSingle) {
+          i += 2;
+          continue;
+        }
+        if (inner === "'" && !skipInDouble && innerPrev !== '\\') {
+          skipInSingle = !skipInSingle;
+        } else if (inner === '"' && !skipInSingle && innerPrev !== '\\') {
+          skipInDouble = !skipInDouble;
+        } else if (!skipInSingle && !skipInDouble) {
+          if (inner === '(') depth += 1;
+          else if (inner === ')') depth -= 1;
+        }
+        i += 1;
+      }
+      i -= 1;
+      continue;
+    }
+
+    if (ch === '`') {
+      i += 1;
+      while (i < source.length && source[i] !== '`') {
+        if (source[i] === '\\' && i + 1 < source.length) {
+          i += 2;
+          continue;
+        }
+        i += 1;
+      }
+      continue;
+    }
+
+    if (ch === '(') {
+      let depth = 1;
+      let body = '';
+      let bodyInSingle = false;
+      let bodyInDouble = false;
+      i += 1;
+      while (i < source.length && depth > 0) {
+        const inner = source[i];
+        const innerPrev = source[i - 1];
+        if (inner === '\\' && !bodyInSingle) {
+          body += inner;
+          if (i + 1 < source.length) {
+            body += source[i + 1];
+            i += 2;
+            continue;
+          }
+        }
+        if (inner === "'" && !bodyInDouble && innerPrev !== '\\') {
+          bodyInSingle = !bodyInSingle;
+        } else if (inner === '"' && !bodyInSingle && innerPrev !== '\\') {
+          bodyInDouble = !bodyInDouble;
+        } else if (!bodyInSingle && !bodyInDouble) {
+          if (inner === '(') {
+            depth += 1;
+          } else if (inner === ')') {
+            depth -= 1;
+            if (depth === 0) {
+              break;
+            }
+          }
+        }
+        body += inner;
+        i += 1;
+      }
+      if (body.trim()) {
+        groups.push(body);
+        groups.push(...extractSubshellGroups(body));
+      }
+    }
+  }
+
+  return groups;
+}
+
+/**
+ * Extract bodies of `{ ...; }` brace groups.
+ *
+ * Bash brace groups run their body in the *current* shell (unlike `(...)`,
+ * which forks a subshell). Both forms group multiple commands, so for the
+ * purposes of destructive-bash and dev-server detection they are equivalent:
+ * a `rm -rf` or `npm run dev` inside `{ ...; }` still executes.
+ *
+ * Recognition rules match bash's own reserved-word semantics:
+ * - `{` is a reserved word only when followed by whitespace and preceded by
+ *   the line start, whitespace, or a shell operator (`;`, `|`, `&`, `(`).
+ *   So `{npm run dev}` is NOT a brace group (single token starting with `{`).
+ * - `}` closes the group only when preceded by `;` or whitespace.
+ *   So `foo}` inside the body is not a closing brace.
+ * - Single quotes are literal; double quotes are also literal for `{`/`}`.
+ * - `$(...)`, backticks, and plain `(...)` spans are skipped so we don't
+ *   double-extract bodies the sibling extractors already cover.
+ *
+ * @param {string} input
+ * @returns {string[]}
+ */
+function extractBraceGroups(input) {
+  const source = String(input || '');
+  const groups = [];
+  let inSingle = false;
+  let inDouble = false;
+
+  for (let i = 0; i < source.length; i++) {
+    const ch = source[i];
+    const prev = source[i - 1];
+
+    if (ch === '\\' && !inSingle) {
+      i += 1;
+      continue;
+    }
+
+    if (ch === "'" && !inDouble && prev !== '\\') {
+      inSingle = !inSingle;
+      continue;
+    }
+
+    if (ch === '"' && !inSingle && prev !== '\\') {
+      inDouble = !inDouble;
+      continue;
+    }
+
+    if (inSingle || inDouble) {
+      continue;
+    }
+
+    if (ch === '$' && source[i + 1] === '(') {
+      let depth = 1;
+      let skipInSingle = false;
+      let skipInDouble = false;
+      i += 2;
+      while (i < source.length && depth > 0) {
+        const inner = source[i];
+        const innerPrev = source[i - 1];
+        if (inner === '\\' && !skipInSingle) {
+          i += 2;
+          continue;
+        }
+        if (inner === "'" && !skipInDouble && innerPrev !== '\\') {
+          skipInSingle = !skipInSingle;
+        } else if (inner === '"' && !skipInSingle && innerPrev !== '\\') {
+          skipInDouble = !skipInDouble;
+        } else if (!skipInSingle && !skipInDouble) {
+          if (inner === '(') depth += 1;
+          else if (inner === ')') depth -= 1;
+        }
+        i += 1;
+      }
+      i -= 1;
+      continue;
+    }
+
+    if (ch === '`') {
+      i += 1;
+      while (i < source.length && source[i] !== '`') {
+        if (source[i] === '\\' && i + 1 < source.length) {
+          i += 2;
+          continue;
+        }
+        i += 1;
+      }
+      continue;
+    }
+
+    if (ch === '(') {
+      let depth = 1;
+      let skipInSingle = false;
+      let skipInDouble = false;
+      i += 1;
+      while (i < source.length && depth > 0) {
+        const inner = source[i];
+        const innerPrev = source[i - 1];
+        if (inner === '\\' && !skipInSingle) {
+          i += 2;
+          continue;
+        }
+        if (inner === "'" && !skipInDouble && innerPrev !== '\\') {
+          skipInSingle = !skipInSingle;
+        } else if (inner === '"' && !skipInSingle && innerPrev !== '\\') {
+          skipInDouble = !skipInDouble;
+        } else if (!skipInSingle && !skipInDouble) {
+          if (inner === '(') depth += 1;
+          else if (inner === ')') depth -= 1;
+        }
+        i += 1;
+      }
+      i -= 1;
+      continue;
+    }
+
+    if (ch === '{' && /\s/.test(source[i + 1] || '')) {
+      const prevIsBoundary = i === 0 || /[\s;|&(]/.test(prev);
+      if (!prevIsBoundary) continue;
+
+      let depth = 1;
+      let body = '';
+      let bodyInSingle = false;
+      let bodyInDouble = false;
+      i += 1;
+      while (i < source.length && depth > 0) {
+        const inner = source[i];
+        const innerPrev = source[i - 1];
+        if (inner === '\\' && !bodyInSingle) {
+          body += inner;
+          if (i + 1 < source.length) {
+            body += source[i + 1];
+            i += 2;
+            continue;
+          }
+        }
+        if (inner === "'" && !bodyInDouble && innerPrev !== '\\') {
+          bodyInSingle = !bodyInSingle;
+          body += inner;
+          i += 1;
+          continue;
+        }
+        if (inner === '"' && !bodyInSingle && innerPrev !== '\\') {
+          bodyInDouble = !bodyInDouble;
+          body += inner;
+          i += 1;
+          continue;
+        }
+        if (bodyInSingle || bodyInDouble) {
+          body += inner;
+          i += 1;
+          continue;
+        }
+        // Skip $(...) spans — a quoted `}` or `}`-as-text inside a
+        // substitution body must not close the enclosing brace group.
+        if (inner === '$' && source[i + 1] === '(') {
+          body += inner + source[i + 1];
+          let subDepth = 1;
+          let subInSingle = false;
+          let subInDouble = false;
+          i += 2;
+          while (i < source.length && subDepth > 0) {
+            const c = source[i];
+            const p = source[i - 1];
+            body += c;
+            if (c === '\\' && !subInSingle && i + 1 < source.length) {
+              body += source[i + 1];
+              i += 2;
+              continue;
+            }
+            if (c === "'" && !subInDouble && p !== '\\') subInSingle = !subInSingle;
+            else if (c === '"' && !subInSingle && p !== '\\') subInDouble = !subInDouble;
+            else if (!subInSingle && !subInDouble) {
+              if (c === '(') subDepth += 1;
+              else if (c === ')') subDepth -= 1;
+            }
+            i += 1;
+          }
+          continue;
+        }
+        // Skip backtick spans for the same reason.
+        if (inner === '`') {
+          body += inner;
+          i += 1;
+          while (i < source.length && source[i] !== '`') {
+            if (source[i] === '\\' && i + 1 < source.length) {
+              body += source[i] + source[i + 1];
+              i += 2;
+              continue;
+            }
+            body += source[i];
+            i += 1;
+          }
+          if (i < source.length) {
+            body += source[i];
+            i += 1;
+          }
+          continue;
+        }
+        // Skip plain (...) subshell spans for the same reason.
+        if (inner === '(') {
+          body += inner;
+          let subDepth = 1;
+          let subInSingle = false;
+          let subInDouble = false;
+          i += 1;
+          while (i < source.length && subDepth > 0) {
+            const c = source[i];
+            const p = source[i - 1];
+            body += c;
+            if (c === '\\' && !subInSingle && i + 1 < source.length) {
+              body += source[i + 1];
+              i += 2;
+              continue;
+            }
+            if (c === "'" && !subInDouble && p !== '\\') subInSingle = !subInSingle;
+            else if (c === '"' && !subInSingle && p !== '\\') subInDouble = !subInDouble;
+            else if (!subInSingle && !subInDouble) {
+              if (c === '(') subDepth += 1;
+              else if (c === ')') subDepth -= 1;
+            }
+            i += 1;
+          }
+          continue;
+        }
+        if (inner === '{' && /\s/.test(source[i + 1] || '')) {
+          // Match the outer-scan boundary rule for nested `{` so
+          // tokens like `foo{` (no boundary, but followed by space
+          // via `foo{ bar`) cannot bump nested depth.
+          const nestedPrevIsBoundary = /[\s;|&(]/.test(innerPrev);
+          if (nestedPrevIsBoundary) depth += 1;
+        } else if (inner === '}' && (innerPrev === ';' || /\s/.test(innerPrev))) {
+          depth -= 1;
+          if (depth === 0) {
+            break;
+          }
+        }
+        body += inner;
+        i += 1;
+      }
+      if (body.trim()) {
+        groups.push(body);
+        groups.push(...extractBraceGroups(body));
+      }
+    }
+  }
+
+  return groups;
+}
+
+module.exports = { extractCommandSubstitutions, extractSubshellGroups, extractBraceGroups };

package/src/pilot/references/execute-mvp-tdd.md

@@ -0,0 +1,81 @@
+# Execute-Phase — MVP+TDD Gate (Runtime Enforcement)
+
+> Loaded by `execute-phase` workflow and `ccp-executor` agent only when **both** `MVP_MODE=true` AND `TDD_MODE=true` for the phase. Defines the runtime gate that blocks behavior-adding tasks until a failing-test commit exists.
+
+## When this gate fires
+
+- `MVP_MODE` is `true` (resolved from CLI flag → ROADMAP `**Mode:**` field → config; see `references/planner-mvp-mode.md`).
+- `TDD_MODE` is `true` (resolved from `--tdd` flag → `workflow.tdd_mode` config).
+- The current task being executed has `tdd="true"` in its `<task>` frontmatter (set by the planner per Phase 1).
+- The task's `<behavior>` block lists at least one expected behavior.
+
+If any of these is false, the gate is inactive — execution proceeds normally.
+
+## What the gate checks
+
+For each task gated by MVP+TDD, the executor MUST verify (before running the implementation step):
+
+1. **A failing-test commit exists.** Search git log on the current branch for a commit matching `test({phase}-{plan})` whose subject mentions the same plan as the current task. The commit must touch a test file (`*.test.*`, `*.spec.*`, `tests/**`).
+2. **The test was actually red.** The commit message body or the executor's recent shell history must show the test failed when first run. Acceptable evidence:
+   - Commit message contains `RED:` prefix or `(RED)` tag
+   - Recent terminal output shows `FAIL` or non-zero exit on the new test before any implementation commit
+3. **No implementation commit yet.** No `feat({phase}-{plan})` commit may exist for the same plan ID before the failing-test commit.
+
+If any check fails, the gate trips.
+
+## What "behavior-adding task" means
+
+A task is behavior-adding when:
+- Its frontmatter has `tdd="true"` AND
+- Its `<behavior>` block names at least one user-visible outcome (not a config-only or doc-only task) AND
+- Its `<files>` list includes at least one source file (not exclusively docs/tests/config files such as `*.md`, `*.json`, `*.test.*`, `*.spec.*`, `*.yml`, `*.yaml`, `*.toml`, `*.ini`, `.env*`)
+
+Pure documentation, configuration, or test-only tasks are skipped by this gate even when both modes are active.
+
+## What happens when the gate trips
+
+The executor MUST:
+
+1. Halt before running the task's implementation step.
+2. Emit a structured halt report:
+
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    MVP+TDD GATE TRIPPED — Plan {plan_id}, Task {task_id}
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   Reason: {missing_red_commit | red_commit_not_failing | feat_before_test}
+
+   Behavior expected to be tested:
+   - {first behavior bullet}
+
+   Required next step:
+   1. Write a failing test for the behavior above.
+   2. Commit it as: test({phase}-{plan}): {short description}
+   3. Re-run /ccp:execute-phase
+   ```
+
+3. Exit the current execution wave cleanly. Do NOT roll back any prior commits in the same wave.
+4. Update `STATE.md` with `last_gate_trip: {plan_id}/{task_id}` so the user can resume after writing the test.
+
+## Escalation: end-of-phase TDD review under MVP+TDD
+
+The existing end-of-phase TDD review (in `workflows/execute-phase.md`'s `tdd_review_checkpoint` step) is normally **advisory** — it surfaces gate violations but does not block phase completion.
+
+Under MVP+TDD, escalate this to **blocking**:
+- If any TDD plan is missing a RED or GREEN commit, the executor MUST refuse to mark the phase complete.
+- The user is shown the same review table, but the verdict line reads:
+  > "Phase blocked: {N} TDD plan(s) violate the RED→GREEN gate sequence under MVP+TDD. Resolve and re-run /ccp:execute-phase, or override with `/ccp:execute-phase {phase} --force-mvp-gate` to ship anyway."
+
+The `--force-mvp-gate` flag is documented but not introduced by this plan — it is the escape hatch the spec mentions; if the user later builds it, the workflow already references the contract.
+
+## What this gate does NOT do
+
+- It does not enforce REFACTOR commits. REFACTOR remains optional (per `references/tdd.md`).
+- It does not check test quality (the test could be trivially passing). That's the planner's job.
+- It does not run tests. The executor only inspects git log + file system. Running tests is the implementation step's job.
+- It does not gate config-only or doc-only tasks (see "behavior-adding task" definition).
+
+## Compatibility with existing TDD discipline
+
+This gate is additive to `references/tdd.md`. Tasks not under MVP+TDD continue to use the existing advisory TDD discipline (RED/GREEN/REFACTOR commits with end-of-phase review checkpoint). Only the runtime gate and the blocking escalation are new.

package/src/pilot/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. | `ccp-planner` agent when `MVP_MODE=true` |
+| `references/skeleton-template.md` | **Template.** Shape of `SKELETON.md` for new-project Phase 1 under `--mvp`. | `ccp-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`. | `ccp:mvp-phase` workflow during interactive prompting; `ccp-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. | `ccp: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. | `ccp-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. | `ccp-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** — parsed by the planner workflow when MVP mode is active in ROADMAP.md. Workflows compare against the parser output, never re-parse.
+- **User Story regex** — `/^As a .+, I want to .+, so that .+\.$/` — applied at runtime by `ccp-verifier` (the user-story-format guard) and `ccp:mvp-phase` (interactive validation).
+- **Behavior-Adding Task predicate** — `references/execute-mvp-tdd.md` (the canonical three-check definition). Applied at runtime by `ccp-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 `ccp-roadmapper` agent makes the MVP/standard decision once at project init** based on `PROJECT_MODE`. Per-phase opt-in/out happens later via `/ccp:mvp-phase` or `/ccp: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` — ccp-planner agent MVP section
+- `mvp-phase-command.test.cjs`, `mvp-phase-integration.test.cjs`, `mvp-phase-spidr.test.cjs` — `/ccp: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