@curdx/flow 2.0.0-beta.1 → 2.0.0-beta.10

package/cli/protocols.js

@@ -5,10 +5,23 @@
  * and reversible (uninstall removes it cleanly without touching user content).
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
 import { join, dirname } from "node:path";
-
-const HOME = process.env.HOME || "";
+import { homedir } from "node:os";
+
+// Use os.homedir() instead of process.env.HOME — HOME can be empty inside
+// non-login shells (CI containers, some spawned child envs), which would
+// resolve GLOBAL_CLAUDE_MD to "/.claude/CLAUDE.md" (filesystem root) and
+// cause mkdir/writeFileSync to fail with EACCES. homedir() falls back to
+// the effective user's passwd entry on POSIX and USERPROFILE on Windows.
+const HOME = homedir();
 export const GLOBAL_CLAUDE_MD = join(HOME, ".claude", "CLAUDE.md");
 
 const SENTINEL_BEGIN =
@@ -53,16 +66,56 @@ function readGlobalMd() {
 
 /**
  * Locate the sentinel block in the content.
- * Returns { start, end } indices into content, or null if not found.
+ * Returns { start, end } indices into content, `null` if neither sentinel is
+ * present, or throws if the block is corrupted (begin without matching end).
+ * The throw is intentional — previously the corrupted case silently returned
+ * null, so the next run would append a SECOND block, producing drift.
  */
 function findBlock(content) {
   const start = content.indexOf(SENTINEL_BEGIN);
-  if (start === -1) return null;
+  if (start === -1) {
+    // Also check for a dangling END without BEGIN — that is also corrupted.
+    if (content.indexOf(SENTINEL_END) !== -1) {
+      throw new Error(
+        `Corrupted protocol block in ${GLOBAL_CLAUDE_MD}: END sentinel found without BEGIN. ` +
+          `Manually inspect the file and remove the dangling END line, then re-run.`
+      );
+    }
+    return null;
+  }
   const endIdx = content.indexOf(SENTINEL_END, start);
-  if (endIdx === -1) return null;
+  if (endIdx === -1) {
+    throw new Error(
+      `Corrupted protocol block in ${GLOBAL_CLAUDE_MD}: BEGIN sentinel found without END. ` +
+        `Manually remove the orphan BEGIN line (or restore the END), then re-run.`
+    );
+  }
   return { start, end: endIdx + SENTINEL_END.length };
 }
 
+/**
+ * Write `content` to `path` atomically: write to a sibling temp file first,
+ * then rename. This prevents a half-written CLAUDE.md if the process is
+ * interrupted mid-write, and avoids races between concurrent install /
+ * uninstall invocations.
+ */
+function atomicWrite(path, content) {
+  const tmp = `${path}.curdx-flow.tmp.${process.pid}`;
+  try {
+    writeFileSync(tmp, content, "utf-8");
+    renameSync(tmp, path);
+  } catch (err) {
+    // Best-effort cleanup of the temp file; swallow errors here since we
+    // are already re-throwing the real failure.
+    try {
+      if (existsSync(tmp)) unlinkSync(tmp);
+    } catch {
+      // ignore
+    }
+    throw err;
+  }
+}
+
 /**
  * Inject (or upgrade) the protocol block in ~/.claude/CLAUDE.md.
  * @returns {{action:"created"|"upgraded"|"unchanged", path:string}}
@@ -81,8 +134,8 @@ export function injectGlobalProtocols() {
       ? (existing.endsWith("\n") ? "\n" : "\n\n")
       : "";
     const next = existing + sep + FULL_BLOCK + "\n";
-    writeFileSync(path, next, "utf-8");
-    return { action: existing.length === 0 ? "created" : "created", path };
+    atomicWrite(path, next);
+    return { action: existing.length === 0 ? "created" : "appended", path };
   }
 
   // Replace existing block (handle upgrade-in-place)
@@ -92,7 +145,7 @@ export function injectGlobalProtocols() {
   }
   const next =
     existing.slice(0, block.start) + FULL_BLOCK + existing.slice(block.end);
-  writeFileSync(path, next, "utf-8");
+  atomicWrite(path, next);
   return { action: "upgraded", path };
 }
 
@@ -119,6 +172,6 @@ export function removeGlobalProtocols() {
   }
 
   const next = existing.slice(0, start) + existing.slice(end);
-  writeFileSync(path, next, "utf-8");
+  atomicWrite(path, next);
   return { action: "removed", path };
 }

package/cli/registry.js

@@ -0,0 +1,73 @@
+/**
+ * Single source of truth for recommended companion plugins.
+ *
+ * Background: before this file existed, the list of recommended plugins lived
+ * in FOUR independent places (install.js, uninstall.js, upgrade.js,
+ * doctor.js). They drifted — chrome-devtools-mcp was added to install.js
+ * during the beta.8 MCP decoupling but forgotten in the other three,
+ * making it installable but uninstallable. This registry exists so adding
+ * or removing a plugin is a one-file change.
+ *
+ * Every consumer pulls what it needs via property access:
+ *   - install.js     → marketplace + installSpec + hint (+ optional postInstall)
+ *   - uninstall.js   → uninstallSpec
+ *   - upgrade.js     → installSpec (for `claude plugin update`) + marketplaceId
+ *   - doctor.js      → name + installSpec (for manual recovery hints)
+ */
+
+export const RECOMMENDED_PLUGINS = [
+  {
+    name: "pua",
+    marketplace: "tanweai/pua",
+    marketplaceId: "pua",
+    installSpec: "pua@pua-skills",
+    uninstallSpec: "pua@pua-skills",
+    hint: "no-give-up + three red lines",
+  },
+  {
+    name: "claude-mem",
+    marketplace: "thedotmack/claude-mem",
+    marketplaceId: "thedotmack",
+    installSpec: "claude-mem@thedotmack",
+    uninstallSpec: "claude-mem@thedotmack",
+    hint: "automatic cross-session memory",
+    postInstall: "claude-mem-runtimes",
+  },
+  {
+    name: "frontend-design",
+    // Already in default marketplace claude-plugins-official, no add needed
+    marketplace: null,
+    marketplaceId: "claude-plugins-official",
+    installSpec: "frontend-design@claude-plugins-official",
+    uninstallSpec: "frontend-design@claude-plugins-official",
+    hint: "Anthropic official UI skill",
+  },
+  {
+    name: "chrome-devtools-mcp",
+    marketplace: "ChromeDevTools/chrome-devtools-mcp",
+    marketplaceId: "chrome-devtools-plugins",
+    installSpec: "chrome-devtools-mcp@chrome-devtools-plugins",
+    uninstallSpec: "chrome-devtools-mcp@chrome-devtools-plugins",
+    hint: "Chrome DevTools + Puppeteer (Google official)",
+  },
+];
+
+/**
+ * Marketplaces to refresh during `upgrade`. Derived from RECOMMENDED_PLUGINS
+ * plus the curdx-flow marketplace itself.
+ */
+export const MARKETPLACES_TO_REFRESH = [
+  "curdx-flow-marketplace",
+  ...RECOMMENDED_PLUGINS
+    .filter((p) => p.marketplaceId && p.marketplaceId !== "claude-plugins-official")
+    .map((p) => p.marketplaceId),
+];
+
+/**
+ * Plugin install specs to update during `upgrade` — includes curdx-flow
+ * itself plus every recommended plugin.
+ */
+export const PLUGINS_TO_UPDATE = [
+  "curdx-flow@curdx-flow-marketplace",
+  ...RECOMMENDED_PLUGINS.map((p) => p.installSpec),
+];

package/cli/uninstall.js

@@ -4,6 +4,7 @@
 
 import { existsSync, lstatSync, unlinkSync, rmSync, readlinkSync } from "node:fs";
 import { join } from "node:path";
+import { homedir } from "node:os";
 
 import {
   color,
@@ -15,18 +16,15 @@ import {
   listPlugins,
 } from "./utils.js";
 import { removeGlobalProtocols, GLOBAL_CLAUDE_MD } from "./protocols.js";
+import { RECOMMENDED_PLUGINS } from "./registry.js";
 
-const HOME = process.env.HOME || "";
+const HOME = homedir();
 
-// Keep aligned with install.js
-const RECOMMENDED = [
-  { name: "pua", uninstallSpec: "pua@pua-skills" },
-  { name: "claude-mem", uninstallSpec: "claude-mem@thedotmack" },
-  {
-    name: "frontend-design",
-    uninstallSpec: "frontend-design@claude-plugins-official",
-  },
-];
+// Pull uninstall-relevant subset from the single registry. See registry.js.
+const RECOMMENDED = RECOMMENDED_PLUGINS.map(({ name, uninstallSpec }) => ({
+  name,
+  uninstallSpec,
+}));
 
 // Symlinks created by install.js (only cleaned with --purge)
 const MANAGED_SYMLINKS = [
@@ -116,7 +114,7 @@ export async function uninstall(args = []) {
       for (const name of toRemove) {
         const rec = presentRecs.find((r) => r.name === name);
         log.blank();
-        console.log(`  ${color.cyan("⏳")} Uninstalling ${color.bold(rec.name)}...`);
+        console.log(`  ${color.cyan("▸")} Uninstalling ${color.bold(rec.name)}...`);
         const r = await run(
           "claude",
           ["plugin", "uninstall", rec.uninstallSpec],

package/cli/upgrade.js

@@ -3,13 +3,10 @@
  */
 
 import { color, log, run, listPlugins, claudeVersion } from "./utils.js";
-
-const PLUGINS_TO_UPDATE = [
-  "curdx-flow@curdx-flow-marketplace",
-  "pua@pua-skills",
-  "claude-mem@thedotmack",
-  "frontend-design@claude-plugins-official",
-];
+import {
+  PLUGINS_TO_UPDATE,
+  MARKETPLACES_TO_REFRESH,
+} from "./registry.js";
 
 export async function upgrade(args = []) {
   log.title("⬆️  CurDX-Flow upgrade");
@@ -19,10 +16,9 @@ export async function upgrade(args = []) {
     process.exit(1);
   }
 
-  // Refresh marketplaces first
+  // Refresh marketplaces first (derived from cli/registry.js)
   log.step(1, 2, "Refreshing marketplaces...");
-  const marketplaces = ["curdx-flow-marketplace", "pua", "thedotmack"];
-  for (const mp of marketplaces) {
+  for (const mp of MARKETPLACES_TO_REFRESH) {
     const r = await run(
       "claude",
       ["plugin", "marketplace", "update", mp],

package/cli/utils.js

@@ -108,39 +108,6 @@ export function confirm(message, defaultYes = true) {
   });
 }
 
-/**
- * Ask user to pick from a list. Returns selected value or null if aborted.
- */
-export function select(message, choices, defaultIndex = 0) {
-  return new Promise((resolve) => {
-    console.log(`${color.cyan("?")}  ${message}`);
-    choices.forEach((ch, i) => {
-      const marker = i === defaultIndex ? color.green("▸") : " ";
-      console.log(`   ${marker} ${color.bold(String(i + 1))}. ${ch.label}`);
-    });
-
-    const rl = createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-    rl.question(
-      `   ${color.dim(`(default: ${defaultIndex + 1}, q to abort) `)}`,
-      (ans) => {
-        rl.close();
-        const v = ans.trim().toLowerCase();
-        if (v === "q") return resolve(null);
-        if (v === "") return resolve(choices[defaultIndex].value);
-        const n = parseInt(v, 10);
-        if (Number.isInteger(n) && n >= 1 && n <= choices.length) {
-          return resolve(choices[n - 1].value);
-        }
-        console.log(color.yellow("  (invalid, using default)"));
-        resolve(choices[defaultIndex].value);
-      }
-    );
-  });
-}
-
 /**
  * Multi-select (checkbox-style via comma-separated input).
  * Returns array of selected values.
@@ -199,47 +166,124 @@ export function claudeVersion() {
   return m ? m[1] : res.stdout.trim().split("\n")[0];
 }
 
-/** List installed plugins via `claude plugin list`. Returns array of { name, version, status }. */
+/**
+ * List installed plugins. Prefers the structured `claude plugin list --json`
+ * output (stable machine-readable format; confirmed present in claude
+ * 2.1.117+). Falls back to parsing the human-readable stream-text output
+ * for older CLI versions, but warns that parser is brittle.
+ *
+ * Returns array of { name, version, status }.
+ */
 export function listPlugins() {
-  const res = runSync("claude", ["plugin", "list"]);
-  if (res.code !== 0) return [];
-  const out = res.stdout;
-  const plugins = [];
-  // Parse format like:
+  // Preferred: structured JSON output.
+  const j = runSync("claude", ["plugin", "list", "--json"]);
+  if (j.code === 0 && j.stdout.trim().startsWith("[")) {
+    try {
+      const arr = JSON.parse(j.stdout);
+      return arr.map((p) => ({
+        // id has form "name@marketplace" — name is stable for dedup/lookup.
+        name: String(p.id || "").split("@")[0],
+        version: p.version,
+        status: p.enabled === false ? "disabled" : "enabled",
+        raw: JSON.stringify(p),
+      }));
+    } catch {
+      // JSON parse failed — fall through to legacy text parser.
+    }
+  }
+
+  // Legacy fallback: parse the human-readable format.
   //   ❯ curdx-flow@curdx-flow-marketplace
   //     Version: 1.1.1
-  //     Scope: user
   //     Status: ✔ enabled
-  const blocks = out.split(/\n\s*❯\s*/).slice(1);
+  // Fragile — matches unicode markers. Kept only for older claude CLIs.
+  const res = runSync("claude", ["plugin", "list"]);
+  if (res.code !== 0) return [];
+  const plugins = [];
+  const blocks = res.stdout.split(/\n\s*❯\s*/).slice(1);
   for (const block of blocks) {
     const lines = block.split("\n");
     const name = lines[0].trim().split("@")[0];
     const version = (block.match(/Version:\s*(\S+)/) || [])[1];
-    const status = block.includes("✔") ? "enabled" : block.includes("✘") ? "failed" : "unknown";
+    const status = block.includes("✔")
+      ? "enabled"
+      : block.includes("✘")
+        ? "failed"
+        : "unknown";
     plugins.push({ name, version, status, raw: block });
   }
   return plugins;
 }
 
-/** List MCPs via `claude mcp list`. Returns array of { name, status }. */
+/**
+ * List MCP servers registered with the `claude` CLI. Returns array of
+ *   { name, plugin, fullName, status, command }
+ * where `plugin` is set when the MCP came from a plugin (real name is
+ * `plugin:<plugin>:<mcp>`), `name` is the trailing segment, and `fullName`
+ * is the original as reported by claude.
+ *
+ * Fixture captured from `claude mcp list` (2.1.117):
+ *   Checking MCP server health…
+ *
+ *   plugin:curdx-flow:context7: npx -y @upstash/context7-mcp@latest - ✓ Connected
+ *   context7: npx -y @upstash/context7-mcp --api-key ... - ✓ Connected
+ *   claude.ai Gmail: https://gmailmcp... - ✓ Connected
+ *
+ * `claude mcp list --json` does not exist on 2.1.117 (verified), so this
+ * parser is the primary path. It is fixture-tested in test/utils.test.js
+ * so format regressions get caught in CI.
+ */
 export function listMcps() {
   const res = runSync("claude", ["mcp", "list"]);
   if (res.code !== 0) return [];
-  const lines = res.stdout.split("\n");
+  return parseMcpList(res.stdout);
+}
+
+/** Exported for testing against a fixed input. */
+export function parseMcpList(output) {
   const mcps = [];
-  for (const line of lines) {
-    // Rough parse — adjust if format differs
-    const m = line.match(/^\s*([a-z0-9-]+)\s*[:\-]/i);
-    if (m) mcps.push({ name: m[1], status: "registered" });
+  for (const raw of output.split("\n")) {
+    const line = raw.trimEnd();
+    if (!line) continue;
+    // skip the health-check header line
+    if (line.startsWith("Checking") || line.startsWith("checking")) continue;
+    // Expected format: "<fullName>: <command-or-url> - <status>"
+    // fullName may itself contain colons when prefixed with "plugin:<p>:<m>".
+    // Match from the end to find the status sentinel " - ", then split off
+    // the name at the first ": " after the identifier prefix.
+    const statusSplit = line.lastIndexOf(" - ");
+    if (statusSplit === -1) continue;
+    const statusRaw = line.slice(statusSplit + 3).trim();
+    const beforeStatus = line.slice(0, statusSplit);
+    // Find the first ": " that separates name from command. Note the space
+    // after the colon — this disambiguates from the colons inside
+    // "plugin:foo:bar".
+    const nameSplit = beforeStatus.indexOf(": ");
+    if (nameSplit === -1) continue;
+    const fullName = beforeStatus.slice(0, nameSplit).trim();
+    const command = beforeStatus.slice(nameSplit + 2).trim();
+
+    let plugin = null;
+    let name = fullName;
+    if (fullName.startsWith("plugin:")) {
+      const parts = fullName.split(":");
+      if (parts.length >= 3) {
+        plugin = parts[1];
+        name = parts.slice(2).join(":");
+      }
+    }
+
+    const status = /Connected|✓/.test(statusRaw)
+      ? "connected"
+      : /Failed|✗/.test(statusRaw)
+        ? "failed"
+        : "unknown";
+
+    mcps.push({ name, plugin, fullName, status, command });
   }
   return mcps;
 }
 
-// ---------- Paths ----------
-export function pluginCacheDir(pluginName = "curdx-flow", marketplace = "curdx-flow-marketplace") {
-  return `${process.env.HOME}/.claude/plugins/cache/${marketplace}/${pluginName}`;
-}
-
 // ---------- Runtime PATH guards (bun / uv) ----------
 // claude-mem hard-codes `command: "bun"` in its .mcp.json, but bun installs to
 // ~/.bun/bin which is not on PATH when Claude Code spawns MCP servers
@@ -247,10 +291,14 @@ export function pluginCacheDir(pluginName = "curdx-flow", marketplace = "curdx-f
 // detection + self-healing: create a symlink to the user-level bun install
 // in a PATH-visible directory.
 
-import { mkdirSync, symlinkSync, lstatSync, unlinkSync, readlinkSync } from "node:fs";
-// `existsSync` and `join` already imported at the top of this file.
+import { existsSync, mkdirSync, symlinkSync, lstatSync, unlinkSync, readlinkSync } from "node:fs";
+import { homedir } from "node:os";
+// `join` already imported at the top of this file.
 
-const HOME = process.env.HOME || "";
+// os.homedir() is sourced from the OS-level user record and works even
+// when $HOME is empty (non-login shells, some CI containers). See the
+// same rationale in cli/protocols.js.
+const HOME = homedir();
 
 /** Candidate bun install locations (priority order) */
 const BUN_CANDIDATES = [

package/commands/fast.md

@@ -123,6 +123,6 @@ Choosing the right scenario matters more than forcing the flow.
 ## Forbidden
 
 - ✗ Committing without running verification
-- ✗ Changes touching more than 5 files (means it is no longer fast — run the full flow)
+- ✗ Changes touching many unrelated files or modules (means it is no longer fast — run the full flow)
 - ✗ Writing library APIs from memory
 - ✗ Skipping the Step 2 5-question clarification (even when "obvious," explicit statement still has value)

package/commands/implement.md

@@ -15,7 +15,7 @@ Execute spec tasks per tasks.md. Select the best execution strategy based on arg
 ## Step 1: Preflight Checks
 
 ```bash
-[ ! -d ".flow" ] && { echo "❌ Not a CurDX-Flow project. Run /curdx-flow:init first"; exit 1; }
+[ ! -d ".flow" ] && { echo "✗ Not a CurDX-Flow project. Run /curdx-flow:init first"; exit 1; }
 
 ARGS="$ARGUMENTS"
 SPEC_NAME=""
@@ -35,10 +35,10 @@ for arg in $ARGS; do
 done
 
 [ -z "$SPEC_NAME" ] && SPEC_NAME=$(cat .flow/.active-spec 2>/dev/null)
-[ -z "$SPEC_NAME" ] && { echo "❌ No active spec. Run /curdx-flow:start first"; exit 1; }
+[ -z "$SPEC_NAME" ] && { echo "✗ No active spec. Run /curdx-flow:start first"; exit 1; }
 
 DIR=".flow/specs/$SPEC_NAME"
-[ ! -f "$DIR/tasks.md" ] && { echo "❌ Missing tasks.md. Run /curdx-flow:spec first (or /curdx-flow:spec --phase=tasks to rebuild just the tasks phase)"; exit 1; }
+[ ! -f "$DIR/tasks.md" ] && { echo "✗ Missing tasks.md. Run /curdx-flow:spec first (or /curdx-flow:spec --phase=tasks to rebuild just the tasks phase)"; exit 1; }
 ```
 
 ## Step 2: Parse Task Characteristics from tasks.md
@@ -330,7 +330,7 @@ Prerequisites:
 
 ## Step 6: Progress Feedback
 
-Every 5 tasks or every wave, print status:
+At each wave boundary (or periodically during long linear runs), print status:
 
 ```
 ═════ Progress ═════

package/commands/init.md

@@ -71,9 +71,20 @@ Append (if not already present):
 
 ### Step 5: Health Check
 
-Run `npx @curdx/flow doctor` (or inline its checks) to verify:
-- 3 MCPs started (context7 / sequential-thinking / chrome-devtools)
-- Recommended plugins status (pua / claude-mem / frontend-design)
+Do NOT shell out to a new terminal for this step — you are already inside
+Claude Code. Verify inline via the information the plugin already has:
+
+- Read `~/.claude/plugins/data/curdx-flow/.deps-checked` (optional — the
+  SessionStart hook already refreshes this once per day).
+- If the user asks for the full report, suggest they run
+  `npx @curdx/flow doctor` in a separate terminal — don't try to spawn
+  it from inside the Claude Code session (output won't render cleanly
+  and the user has to alt-tab to see it).
+
+Items the CLI doctor covers (for user reference):
+- 2 bundled MCPs (context7 / sequential-thinking) — visible in `claude mcp list`
+- 4 recommended plugins (pua / claude-mem / frontend-design / chrome-devtools-mcp)
+- Runtime PATH guards for `bun` / `uv` (relevant only when claude-mem is installed)
 
 ### Step 6: Prompt Next Steps
 

package/commands/review.md

@@ -16,8 +16,8 @@ Distinct from `/curdx-flow:verify`:
 | Flag | Default | Purpose |
 |------|---------|---------|
 | `--stage=<1\|2\|both>` | `both` | Stage 1 = spec compliance only. Stage 2 = code quality only. `both` = sequential. |
-| `--adversarial` | off | Add an adversarial review pass (6 dimensions × 2 sequential-thinking rounds). Zero-findings forbidden. |
-| `--edge-case` | off | Add edge-case hunting across the 7 categories. Produces a test-gap checklist. |
+| `--adversarial` | off | Add an adversarial review pass across applicable categories (zero findings requires proof-of-checking, not fabrication). |
+| `--edge-case` | off | Add edge-case hunting across applicable categories. Produces a test-gap checklist. |
 
 ## Preflight
 
@@ -65,7 +65,7 @@ Output: Stage-2 section of the report.
 ## Optional: adversarial review
 
 If `--adversarial`:
-Dispatch `flow-adversary`. It runs 6 dimensions × 2 rounds of `sequential-thinking`:
+Dispatch `flow-adversary`. It scans the applicable categories (Architecture / Implementation / Testing / Security / Maintainability / UX — skip N/A with reason) using `sequential-thinking` proportional to the residual uncertainty, probing:
 1. What's missing?
 2. What's overengineered?
 3. What would break first in production?
@@ -73,12 +73,12 @@ Dispatch `flow-adversary`. It runs 6 dimensions × 2 rounds of `sequential-think
 5. What decision locks us out of a future option?
 6. What would a skeptical reviewer reject?
 
-**Zero findings are forbidden** — if the agent reports "all good", re-dispatch with stronger skepticism. Per `@${CLAUDE_PLUGIN_ROOT}/gates/adversarial-review-gate.md`.
+**Zero findings requires proof-of-checking, not fabrication** — honest "clean" verdicts are fine if the agent lists what it examined. Per `@${CLAUDE_PLUGIN_ROOT}/gates/adversarial-review-gate.md`.
 
 ## Optional: edge-case hunting
 
 If `--edge-case`:
-Dispatch `flow-edge-hunter` across the 7 categories:
+Dispatch `flow-edge-hunter` across the applicable categories (skip N/A with one-line reason):
 1. Boundary values (0, MAX, empty, one-over-limit)
 2. Concurrency / race conditions
 3. Network failure / partial failure
@@ -91,6 +91,15 @@ Output: test-gap checklist with suggested test cases.
 
 ## Report
 
+**Landing check**: sub-agent responses can be truncated. After dispatching review agents, verify the report actually landed on disk:
+
+```bash
+REPORT=".flow/specs/$SPEC_NAME/review-report.md"
+if [ ! -f "$REPORT" ] || [ "$(wc -c < "$REPORT" 2>/dev/null | tr -d ' ')" -lt 300 ]; then
+  echo "⚠ Report missing or truncated. Re-dispatching flow-reviewer with a terse 'Write the report now, no narration' prompt."
+fi
+```
+
 Consolidated output: `.flow/specs/$SPEC_NAME/review-report.md`:
 
 ```markdown

package/commands/spec.md

@@ -82,7 +82,7 @@ Output: `requirements.md` with user stories (US-NN), acceptance criteria (AC-N.N
 
 ### design → `flow-architect`
 Inputs: `research.md` + `requirements.md`.
-Output: `design.md` with architecture decisions (AD-NN), component boundaries, data models, error-path design, mermaid diagrams. Must use `sequential-thinking` MCP (≥8 thoughts).
+Output: `design.md` with architecture decisions (AD-NN), component boundaries, data models, error-path design, mermaid diagrams (when they clarify). Uses `sequential-thinking` MCP proportional to the genuine tradeoff surface.
 
 ### tasks → `flow-planner`
 Inputs: all three prior files + `.flow/PROJECT.md` tech stack.
@@ -94,10 +94,34 @@ After each phase completes successfully, update `.state.json`:
 {
   "phase": "<just-completed-phase>",
   "phase_status": { "<phase>": "completed" },
-  "updated_at": "<ISO8601 timestamp>"
+  "updated": "<ISO8601 timestamp>"
 }
 ```
 
+### Artifact landing check (mandatory after every phase)
+
+Sub-agent responses can be truncated by the model's output-length limit, which means the `Write` tool call for the phase's Markdown artifact may never fire. Do NOT trust the agent's return value alone — always verify the file actually landed.
+
+For each phase just dispatched, run:
+
+```bash
+ARTIFACT=".flow/specs/$SPEC_NAME/<phase>.md"
+if [ ! -f "$ARTIFACT" ]; then
+  echo "⚠ $ARTIFACT did not land. Re-dispatching <phase> agent with an explicit 'write the file' prompt."
+  # Re-dispatch the same agent, but in the prompt, front-load:
+  #   "Your ONLY job is to call the Write tool with the full <phase>.md content now.
+  #    Do not explain. Do not narrate. Write the file and stop."
+  # This pattern produces an artifact even when prior verbosity caused truncation.
+fi
+
+# Minimum-size sanity check — if the file is <500 bytes, the write likely truncated
+if [ -f "$ARTIFACT" ] && [ "$(wc -c < "$ARTIFACT" | tr -d ' ')" -lt 500 ]; then
+  echo "⚠ $ARTIFACT looks truncated (<500 bytes). Re-dispatching to complete it."
+fi
+```
+
+Only advance `.state.json.phase` after both the file exists AND passes the size sanity check. If a re-dispatch also fails to produce the artifact, stop and surface the issue to the user instead of silently advancing — that prevents later phases from consuming an empty upstream file.
+
 ## Optional planning review
 
 If `--review` (or `--review=<dims>`) is present: