@redspec/cli 0.1.0-alpha.1

package/dist/index.js

@@ -0,0 +1,1429 @@
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/accept.ts
+import { spawnSync } from "child_process";
+import pc from "picocolors";
+import { stamp, writeLock } from "@redspec/core";
+
+// src/context.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import {
+  loadConfig,
+  loadSpecs,
+  publishedBoard,
+  reportBundle,
+  unregisteredBundles
+} from "@redspec/core";
+async function loadContext(root = process.cwd(), now = /* @__PURE__ */ new Date()) {
+  const { config, path } = await loadConfig(root);
+  const specs = await loadSpecs(root, config);
+  const reports = specs.map((s) => reportBundle(root, config, s, now));
+  const extra = [...unregisteredBundles(root, config, specs), ...publishedBoard(config)];
+  const pkgPath = join(root, "package.json");
+  const pkg = existsSync(pkgPath) ? JSON.parse(readFileSync(pkgPath, "utf8")) : null;
+  return { root, config, configPath: path, specs, reports, extra, pkg };
+}
+var allFindings = (ctx) => [
+  ...ctx.reports.flatMap((r) => r.findings),
+  ...ctx.extra
+];
+function packageManager(root) {
+  if (existsSync(join(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(root, "yarn.lock"))) return "yarn";
+  if (existsSync(join(root, "bun.lockb")) || existsSync(join(root, "bun.lock")))
+    return "bun";
+  return "npm";
+}
+var runScript = (pm, script) => pm === "npm" ? `npm run ${script}` : `${pm} ${script}`;
+
+// src/commands/accept.ts
+async function accept(root, opts) {
+  const ctx = await loadContext(root);
+  const log = opts.quiet ? () => {
+  } : console.log;
+  const targets = [];
+  if (opts.slice) {
+    const report2 = ctx.reports.find((r) => r.slices.some((s) => s.path === opts.slice));
+    const slice2 = report2?.slices.find((s) => s.path === opts.slice);
+    if (!report2 || !slice2) {
+      console.error(pc.red(`No slice at ${opts.slice}.`));
+      return 1;
+    }
+    for (const id of slice2.claims) targets.push({ id, slice: slice2.path, report: report2 });
+  }
+  for (const id of opts.ids ?? []) {
+    const report2 = ctx.reports.find((r) => id in r.digests);
+    if (!report2) {
+      console.error(
+        pc.red(`Nothing digests to "${id}". Is it declared, and spelled as declared?`)
+      );
+      return 1;
+    }
+    const owners = report2.slices.filter((s) => s.claims.includes(id));
+    const owner = owners[owners.length - 1];
+    if (!owner) {
+      console.error(
+        pc.red(
+          `"${id}" is claimed by no slice. Claim it first (\`redspec new slice\`), or accept via --slice.`
+        )
+      );
+      return 1;
+    }
+    targets.push({ id, slice: owner.path, report: report2 });
+  }
+  if (targets.length === 0) {
+    console.error(pc.red("Nothing to accept. Pass IDs or --slice <path>."));
+    return 1;
+  }
+  const command = opts.command ?? ctx.config.accept.command;
+  log(pc.dim(`$ ${command}`));
+  const run2 = spawnSync(command, {
+    shell: true,
+    stdio: opts.quiet ? "ignore" : "inherit",
+    cwd: root
+  });
+  if (run2.status !== 0) {
+    console.error(pc.red(`
+Verification exited ${run2.status}. Nothing stamped.`));
+    return 1;
+  }
+  const commit = spawnSync("git", ["rev-parse", "--short", "HEAD"], {
+    cwd: root,
+    encoding: "utf8"
+  });
+  const sha = commit.status === 0 ? commit.stdout.trim() : void 0;
+  const byReport = /* @__PURE__ */ new Map();
+  for (const tg of targets)
+    byReport.set(tg.report.slug, [...byReport.get(tg.report.slug) ?? [], tg]);
+  for (const [slug, tgs] of byReport) {
+    const report2 = ctx.reports.find((r) => r.slug === slug);
+    let lock = report2.lock;
+    for (const tg of tgs) {
+      lock = stamp(lock, [tg.id], report2.digests, tg.slice, {
+        commit: sha,
+        note: opts.clarification
+      });
+    }
+    writeLock(report2.lockPath, lock);
+    for (const tg of tgs)
+      log(`  ${pc.green("stamped")}  ${tg.id}  ${pc.dim(`\u2190 ${tg.slice}`)}`);
+  }
+  return 0;
+}
+
+// src/commands/board.ts
+import { spawn } from "child_process";
+import pc2 from "picocolors";
+async function board(root, feature) {
+  const ctx = await loadContext(root);
+  if (ctx.config.framework === "none") {
+    console.error(
+      pc2.red(
+        'No framework adapter configured, so there is no spec route to open. Set framework: "next" in spec.config.ts.'
+      )
+    );
+    return 1;
+  }
+  const url = `http://localhost:3000${ctx.config.route}${feature ? `/${feature}` : ""}`;
+  console.log(pc2.dim(`$ ${runScript(packageManager(root), "dev")}`));
+  console.log(`${pc2.bold("Board:")} ${url}`);
+  const child = spawn(runScript(packageManager(root), "dev"), {
+    shell: true,
+    stdio: "inherit",
+    cwd: root
+  });
+  return await new Promise((resolve) => child.on("exit", (code) => resolve(code ?? 0)));
+}
+
+// src/commands/check.ts
+import pc4 from "picocolors";
+
+// src/print.ts
+import pc3 from "picocolors";
+import { flowCoverage } from "@redspec/core";
+var GROUPS = [
+  {
+    title: "UNNAMED \u2014 declared with only an ID",
+    kinds: ["unnamed-state"],
+    hint: "\u2192 say what the person is looking at",
+    tone: pc3.yellow
+  },
+  {
+    title: "DECLARED \u2014 not yet rendered",
+    kinds: ["declared-not-rendered"],
+    hint: "\u2192 /render-states",
+    tone: pc3.yellow
+  },
+  {
+    title: "AMENDED \u2014 changed since it was verified",
+    kinds: ["amended", "unverified"],
+    hint: "\u2192 /amend, or redspec accept",
+    tone: pc3.magenta
+  },
+  {
+    title: "WAIVERS",
+    kinds: ["waiver-due", "waiver-unwitnessed", "unknown-witness"],
+    hint: "\u2192 re-read it: believe it, or build the state",
+    tone: pc3.cyan
+  },
+  {
+    title: "DECISION TABLES",
+    kinds: ["table-gap", "table-overlap", "table-parse", "unknown-state-outcome"],
+    hint: "\u2192 make the table total",
+    tone: pc3.red
+  },
+  {
+    title: "SHAPE",
+    kinds: [
+      "off-path",
+      "off-checklist",
+      "unclaimed-id",
+      "unknown-surface",
+      "surface-mismatch",
+      "dangling-deviation",
+      "deviation-off-deviation",
+      "compound-actor",
+      "spine-ends-early",
+      "empty-spine",
+      "bad-id"
+    ],
+    hint: "\u2192 the registry disagrees with itself",
+    tone: pc3.red
+  },
+  {
+    title: "BUNDLE",
+    kinds: [
+      "actor-without-flow",
+      "missing-brief",
+      "unregistered-feature",
+      "unknown-copy"
+    ],
+    hint: "\u2192 the bundle on disk disagrees with the registry",
+    tone: pc3.red
+  },
+  {
+    title: "CONFIG",
+    kinds: ["board-published"],
+    hint: "\u2192 the repo disagrees with its own declarations",
+    tone: pc3.red
+  },
+  {
+    title: "COVERAGE",
+    kinds: ["orphan", "claimless", "unknown-id", "claimed-twice"],
+    hint: "\u2192 /cut-slices",
+    tone: pc3.red
+  }
+];
+function printStatus(ctx, write = console.log) {
+  if (ctx.specs.length === 0 && ctx.extra.length === 0) {
+    write(pc3.dim("No specs yet. Run /draft-skeleton, or `redspec new feature <slug>`."));
+    return;
+  }
+  for (const report2 of ctx.reports) {
+    const spec = ctx.specs.find((s) => s.spec.slug === report2.slug).spec;
+    const declared = report2.artifacts.filter((a) => a.kind === "STATE").length;
+    const rendered = Object.keys(spec.cases).length;
+    write(
+      `${pc3.bold(report2.slug)}${" ".repeat(Math.max(1, 50 - report2.slug.length))}${pc3.dim(`${rendered} of ${declared} states rendered`)}`
+    );
+    printGroups(report2.findings, write);
+    const cov = flowCoverage(spec, ctx.config.journeyBudget);
+    const paths = cov.reduce((n, c) => n + c.reachablePaths, 0);
+    const stamped = Object.keys(report2.lock.entries).length;
+    const line = [
+      `${report2.findings.length} finding${report2.findings.length === 1 ? "" : "s"}`,
+      `${cov.length} flow${cov.length === 1 ? "" : "s"} \xB7 ${paths} reachable path${paths === 1 ? "" : "s"}${cov.some((c) => c.truncated) ? " (truncated)" : ""}`,
+      `${stamped} of ${report2.artifacts.length} artifacts stamped`
+    ].join(" \xB7 ");
+    write(pc3.dim(`  ${line}`));
+    write("");
+  }
+  if (ctx.extra.length) {
+    printGroups(ctx.extra, write);
+    write("");
+  }
+}
+function printGroups(findings, write) {
+  for (const group of GROUPS) {
+    const rows = findings.filter((f) => group.kinds.includes(f.kind));
+    if (rows.length === 0) continue;
+    write("");
+    write(
+      `  ${group.tone(pc3.bold(group.title))}${" ".repeat(Math.max(1, 48 - group.title.length))}${pc3.dim(group.hint)}`
+    );
+    for (const f of rows) {
+      write(`    ${f.id}${f.at ? pc3.dim(`  (${f.at})`) : ""}`);
+      write(pc3.dim(`      ${f.kind}: ${f.detail}`));
+    }
+  }
+}
+function printCheck(findings, write = console.log) {
+  for (const f of findings) {
+    write(`${pc3.red(f.kind.padEnd(24))} ${f.id}${f.at ? pc3.dim(`  ${f.at}`) : ""}`);
+    write(pc3.dim(`${" ".repeat(25)}${f.detail}`));
+  }
+}
+
+// src/commands/check.ts
+async function check(root, opts = {}) {
+  const ctx = await loadContext(root);
+  const findings = allFindings(ctx);
+  if (opts.json) {
+    console.log(
+      JSON.stringify({ findings, specs: ctx.specs.map((s) => s.spec.slug) }, null, 2)
+    );
+    return findings.length ? 1 : 0;
+  }
+  if (findings.length === 0) {
+    if (!opts.quiet)
+      console.log(
+        pc4.green(
+          `redspec: clean. ${ctx.specs.length} spec${ctx.specs.length === 1 ? "" : "s"}, ${ctx.reports.reduce((n, r) => n + r.artifacts.length, 0)} artifacts.`
+        )
+      );
+    return 0;
+  }
+  if (!opts.quiet) printCheck(findings);
+  console.log("");
+  console.log(
+    pc4.red(`${findings.length} finding${findings.length === 1 ? "" : "s"}. Exit 1.`) + pc4.dim("  redspec status for the grouped view.")
+  );
+  return 1;
+}
+
+// src/commands/doctor.ts
+import { existsSync as existsSync6 } from "fs";
+import { join as join6 } from "path";
+import pc6 from "picocolors";
+import { DIGEST_ALGO, HARNESSES } from "@redspec/core";
+import { CAPABILITIES } from "@redspec/method";
+
+// src/harness.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join2 } from "path";
+function detectHarnesses(root, env = process.env) {
+  const found = [];
+  const has = (p2) => existsSync2(join2(root, p2));
+  if (has(".claude") || has("CLAUDE.md") || env.CLAUDECODE)
+    found.push({
+      harness: "claude",
+      evidence: has(".claude") ? ".claude/" : has("CLAUDE.md") ? "CLAUDE.md" : "$CLAUDECODE"
+    });
+  if (has(".cursor") || has(".cursorrules") || env.CURSOR_TRACE_ID)
+    found.push({
+      harness: "cursor",
+      evidence: has(".cursor") ? ".cursor/" : ".cursorrules"
+    });
+  const agentsMd = has("AGENTS.md") ? readFileSync2(join2(root, "AGENTS.md"), "utf8") : null;
+  const foreignAgentsMd = agentsMd !== null && agentsMd.replace(/<!-- redspec:start -->[\s\S]*?<!-- redspec:end -->/g, "").trim().length > 0;
+  if (has(".codex") || foreignAgentsMd)
+    found.push({ harness: "codex", evidence: has(".codex") ? ".codex/" : "AGENTS.md" });
+  if (has(".github/copilot-instructions.md") || has(".github/prompts"))
+    found.push({ harness: "copilot", evidence: ".github/copilot-instructions.md" });
+  if (has(".gemini") || has("GEMINI.md"))
+    found.push({ harness: "gemini", evidence: has(".gemini") ? ".gemini/" : "GEMINI.md" });
+  return found;
+}
+function detectFramework(pkg) {
+  const deps = {
+    ...pkg?.dependencies ?? {},
+    ...pkg?.devDependencies ?? {}
+  };
+  if (deps.next) return "next";
+  return "none";
+}
+function hasTestRunner(pkg) {
+  const deps = {
+    ...pkg?.dependencies ?? {},
+    ...pkg?.devDependencies ?? {}
+  };
+  return {
+    unit: deps.vitest ? "vitest" : deps.jest ? "jest" : null,
+    browser: deps["@playwright/test"] ? "playwright" : null
+  };
+}
+
+// src/install.ts
+import { spawnSync as spawnSync2 } from "child_process";
+import { existsSync as existsSync3 } from "fs";
+import { join as join3 } from "path";
+import pc5 from "picocolors";
+function missingDeps(root, deps) {
+  return deps.filter((d) => !existsSync3(join3(root, "node_modules", d)));
+}
+function installArgs(pm, deps, dev) {
+  if (pm === "npm")
+    return ["npm", "install", "--save-exact", dev ? "--save-dev" : "--save", ...deps];
+  if (pm === "yarn") return ["yarn", "add", "--exact", ...dev ? ["--dev"] : [], ...deps];
+  if (pm === "bun") return ["bun", "add", "--exact", ...dev ? ["--dev"] : [], ...deps];
+  return ["pnpm", "add", "--save-exact", dev ? "--save-dev" : "--save-prod", ...deps];
+}
+var installCommand = (pm, deps, dev) => installArgs(pm, deps, dev).join(" ");
+function installDeps(root, pm, deps, dev, log) {
+  if (!deps.length) return true;
+  log("");
+  log(`Installing ${dev ? "devDependencies" : "dependencies"} (${pm}):`);
+  for (const d of deps) log(`  ${pc5.cyan(d)}`);
+  const [cmd, ...args] = installArgs(pm, deps, dev);
+  const run2 = spawnSync2(cmd, args, { cwd: root, stdio: "inherit" });
+  return run2.status === 0;
+}
+
+// src/commands/sync.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
+import { join as join5 } from "path";
+import {
+  readMethod,
+  renderHarness
+} from "@redspec/method";
+
+// src/fs.ts
+import { existsSync as existsSync4, mkdirSync, readFileSync as readFileSync3, writeFileSync } from "fs";
+import { dirname, join as join4 } from "path";
+import { mergeSection } from "@redspec/method";
+var Writer = class {
+  constructor(root) {
+    this.root = root;
+  }
+  root;
+  written = [];
+  /** Write only if the file does not exist. */
+  create(rel, content) {
+    const abs = join4(this.root, rel);
+    if (existsSync4(abs)) {
+      this.written.push({ path: rel, action: "kept" });
+      return;
+    }
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+    this.written.push({ path: rel, action: "created" });
+  }
+  /** Overwrite; these are generated files that carry a "generated" header. */
+  write(rel, content) {
+    const abs = join4(this.root, rel);
+    const existed = existsSync4(abs);
+    if (existed && readFileSync3(abs, "utf8") === content) {
+      this.written.push({ path: rel, action: "kept" });
+      return;
+    }
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+    this.written.push({ path: rel, action: existed ? "updated" : "created" });
+  }
+  /** Replace or append a marked section, leaving the rest of the file alone. */
+  section(rel, content) {
+    const abs = join4(this.root, rel);
+    const existing = existsSync4(abs) ? readFileSync3(abs, "utf8") : null;
+    const next = mergeSection(existing, content);
+    if (existing === next) {
+      this.written.push({ path: rel, action: "kept" });
+      return;
+    }
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, next);
+    this.written.push({ path: rel, action: existing ? "updated" : "created" });
+  }
+  append(rel, content) {
+    const abs = join4(this.root, rel);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, (existsSync4(abs) ? readFileSync3(abs, "utf8") : "") + content);
+    this.written.push({ path: rel, action: "updated" });
+  }
+  read(rel) {
+    const abs = join4(this.root, rel);
+    return existsSync4(abs) ? readFileSync3(abs, "utf8") : null;
+  }
+};
+
+// src/commands/sync.ts
+var CONTEXT_LOCK = ".redspec/contexts.json";
+var digest = (s) => "sha256:" + createHash("sha256").update(s).digest("hex").slice(0, 16);
+function renderContext(root, config) {
+  const pm = packageManager(root);
+  return {
+    specsDir: config.specsDir,
+    route: config.route,
+    framework: config.framework,
+    unitCommand: runScript(pm, "test"),
+    stateCommand: runScript(pm, "test:state"),
+    journeyCommand: runScript(pm, "test:journey"),
+    conventionsPath: "docs/agents/redspec.md",
+    publicBoard: config.publicBoard
+  };
+}
+function sync(root, config, harnesses = config.harnesses) {
+  const method = readMethod();
+  const ctx = renderContext(root, config);
+  const w = new Writer(root);
+  const lock = { version: 1, files: {} };
+  const files = /* @__PURE__ */ new Map();
+  for (const h of harnesses) {
+    for (const f of renderHarness(h, method, ctx)) {
+      const prev = files.get(f.path);
+      if (!prev || f.content.length > prev.content.length) files.set(f.path, f);
+    }
+  }
+  for (const f of files.values()) {
+    if (f.mode === "section") w.section(f.path, f.content);
+    else w.write(f.path, f.content);
+    lock.files[f.path] = digest(f.content);
+  }
+  w.write(CONTEXT_LOCK, JSON.stringify(lock, null, 2) + "\n");
+  return w;
+}
+function staleContexts(root, config) {
+  const lockPath = join5(root, CONTEXT_LOCK);
+  if (!existsSync5(lockPath)) return [];
+  const lock = JSON.parse(readFileSync4(lockPath, "utf8"));
+  const method = readMethod();
+  const ctx = renderContext(root, config);
+  const files = /* @__PURE__ */ new Map();
+  for (const h of config.harnesses) {
+    for (const f of renderHarness(h, method, ctx)) {
+      const prev = files.get(f.path);
+      if (!prev || f.content.length > prev.content.length) files.set(f.path, f);
+    }
+  }
+  return [...files.values()].filter((f) => lock.files[f.path] !== digest(f.content)).map((f) => f.path);
+}
+
+// src/commands/doctor.ts
+async function doctor(root) {
+  let problems = 0;
+  const ok = (s) => console.log(`  ${pc6.green("\u2713")} ${s}`);
+  const warn = (s) => console.log(`  ${pc6.yellow("!")} ${s}`);
+  const bad = (s) => {
+    problems++;
+    console.log(`  ${pc6.red("\u2717")} ${s}`);
+  };
+  let ctx;
+  try {
+    ctx = await loadContext(root);
+  } catch (e) {
+    bad(`Specs failed to load: ${e.message}`);
+    return 1;
+  }
+  console.log(pc6.bold("Config"));
+  ctx.configPath ? ok(
+    `spec.config.ts (framework: ${ctx.config.framework}, route: ${ctx.config.route})`
+  ) : bad("No spec.config.ts. Run `redspec init`.");
+  ok(
+    `${ctx.specs.length} feature${ctx.specs.length === 1 ? "" : "s"} load${ctx.specs.length === 1 ? "s" : ""}`
+  );
+  for (const r of ctx.reports) {
+    if (r.lock.algo !== 0 && r.lock.algo !== DIGEST_ALGO)
+      bad(
+        `${r.slug}: lock algo ${r.lock.algo}, this redspec writes ${DIGEST_ALGO}. Run \`redspec accept\` over its claims after upgrading.`
+      );
+  }
+  for (const f of ctx.extra) warn(`${f.id}: ${f.detail}`);
+  if (ctx.config.framework === "next") {
+    console.log(pc6.bold("\nNext.js"));
+    const src = existsSync6(join6(root, "src/app")) ? "src/" : "";
+    const has = (p2) => existsSync6(join6(root, src + p2));
+    has("proxy.ts") || has("proxy.redspec.ts") ? ok("proxy.ts gates the spec route in production") : bad("No proxy.ts. The spec route will serve in production.");
+    has("app/spec/_routes.ts") ? ok("app/spec/ routes present") : bad("app/spec/_routes.ts missing.");
+    existsSync6(join6(root, ctx.config.specsDir, "index.ts")) ? ok(`${ctx.config.specsDir}/index.ts registers features for the app`) : bad(`${ctx.config.specsDir}/index.ts missing.`);
+  }
+  console.log(pc6.bold("\nDependencies"));
+  const pm = packageManager(root);
+  const runners = hasTestRunner(ctx.pkg);
+  const runtime = ["@redspec/core", "@redspec/cli"];
+  if (ctx.config.framework === "next") runtime.push("@redspec/next");
+  const dev = [
+    "fast-check",
+    runners.unit === "jest" ? "jest" : "vitest",
+    "@playwright/test"
+  ];
+  const needRuntime = missingDeps(root, runtime);
+  const needDev = missingDeps(root, dev);
+  const missing = /* @__PURE__ */ new Set([...needRuntime, ...needDev]);
+  for (const d of [...runtime, ...dev]) {
+    missing.has(d) ? bad(`${d} is not installed.`) : ok(d);
+  }
+  if (needRuntime.length)
+    console.log(pc6.dim(`      ${installCommand(pm, needRuntime, false)}`));
+  if (needDev.length) console.log(pc6.dim(`      ${installCommand(pm, needDev, true)}`));
+  console.log(pc6.bold("\nHarnesses"));
+  const detected = new Set(detectHarnesses(root).map((d) => d.harness));
+  for (const h of HARNESSES) {
+    const configured = ctx.config.harnesses.includes(h);
+    const cap = CAPABILITIES[h];
+    const mark = configured ? pc6.green("\u2713") : detected.has(h) ? pc6.yellow("!") : pc6.dim("\u25CB");
+    const label = configured ? "configured" : detected.has(h) ? "detected, not configured \u2014 add to spec.config.ts harnesses and `redspec sync`" : "";
+    console.log(`  ${mark} ${h.padEnd(9)} ${pc6.dim(label)}`);
+    if (configured) {
+      console.log(
+        `      ${cap.hitlOnly ? pc6.green("steps are HITL-only") : pc6.yellow("steps are conventions, not gates")} \xB7 ${cap.subagents ? "adversary/verifier run as subagents" : "adversary/verifier run as fresh tasks"}`
+      );
+      console.log(pc6.dim(`      ${cap.note}`));
+    }
+  }
+  const stale = staleContexts(root, ctx.config);
+  if (stale.length) {
+    warn(
+      `${stale.length} rendered context file${stale.length === 1 ? " is" : "s are"} stale (redspec upgraded, or config changed). Run \`redspec sync\`.`
+    );
+    for (const s of stale) console.log(pc6.dim(`      ${s}`));
+  } else if (ctx.config.harnesses.length)
+    ok("rendered contexts match this redspec version");
+  console.log("");
+  console.log(
+    problems ? pc6.red(`${problems} problem${problems === 1 ? "" : "s"}.`) : pc6.green("Healthy.")
+  );
+  return problems ? 1 : 0;
+}
+
+// src/commands/init.ts
+import { existsSync as existsSync7, readFileSync as readFileSync5, writeFileSync as writeFileSync2 } from "fs";
+import { join as join7 } from "path";
+import * as p from "@clack/prompts";
+import pc7 from "picocolors";
+import {
+  defineSpecConfig,
+  HARNESSES as HARNESSES2,
+  loadConfig as loadConfig2
+} from "@redspec/core";
+import { CAPABILITIES as CAPABILITIES2 } from "@redspec/method";
+
+// src/templates.ts
+var specConfig = (framework, harnesses) => `import { defineSpecConfig } from "@redspec/core"
+
+export default defineSpecConfig({
+  framework: "${framework}",
+  route: "/spec",
+  caseViewport: { width: 1280, height: 720 },
+  // "witnessed" makes every waiver name the INV- that would go red if it stopped holding.
+  waivers: "free",
+  // Must exit 0 in the same invocation for \`redspec accept\` to stamp anything.
+  accept: { command: "pnpm test && pnpm test:state" },
+  // Which agent harnesses \`redspec sync\` writes context for.
+  harnesses: ${JSON.stringify(harnesses)},
+})
+`;
+var proxy = `import { createSpecProxy } from "@redspec/next/gate"
+
+// The production gate. It answers 404 before anything renders: a layout-level
+// notFound() still serializes the page into the response body.
+export const proxy = createSpecProxy({ route: "/spec" })
+
+// Next statically parses this at build time, so every value has to stay a
+// literal -- a helper call here fails the build.
+export const config = { matcher: ["/spec", "/spec/:path*"] }
+`;
+var specsIndex = `// Every feature this repo declares. \`redspec new feature\` appends here.
+import type { Spec } from "@redspec/core"
+
+// redspec:imports
+
+export const specs: Spec[] = [
+  // redspec:specs
+]
+`;
+var nextRoutes = (config) => `import { createSpecRoutes } from "@redspec/next"
+import { specs } from "../../specs"
+
+export const { SpecLayout, SpecIndexPage, SpecBoardPage, SpecCasePage, generateStaticParams } =
+  createSpecRoutes(specs, {
+    route: ${JSON.stringify(config.route)},
+    specsDir: ${JSON.stringify(config.specsDir)},
+    stateTestsDir: ${JSON.stringify(config.stateTestsDir)},
+  })
+`;
+var nextLayout = `export { SpecLayout as default } from "./_routes"
+`;
+var nextIndex = `export { SpecIndexPage as default } from "./_routes"
+`;
+var nextBoard = `export { SpecBoardPage as default, generateStaticParams } from "../_routes"
+`;
+var nextCase = `export { SpecCasePage as default } from "../../_routes"
+`;
+var playwrightConfig = `import { defineConfig, devices } from "@playwright/test"
+
+// Two tiers, differing by target rather than by tool. \`state\` points at the
+// spec route -- fixtures only, no auth, no backend -- and asserts exhaustively.
+// \`journey\` points at the real app and stays a handful of paths. Both run
+// against the dev server: the spec route 404s in production by design.
+export default defineConfig({
+  testDir: "./e2e",
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  reporter: process.env.CI ? "github" : "list",
+  expect: { toHaveScreenshot: { stylePath: "./e2e/screenshot.css" } },
+  use: { baseURL: "http://localhost:3000", trace: "on-first-retry" },
+  projects: [
+    { name: "state", testDir: "./e2e/state", use: { ...devices["Desktop Chrome"], viewport: { width: 1280, height: 720 } } },
+    { name: "journey", testDir: "./e2e/journey", use: { ...devices["Desktop Chrome"] } },
+  ],
+  webServer: { command: "pnpm dev", url: "http://localhost:3000", reuseExistingServer: !process.env.CI, timeout: 120_000 },
+})
+`;
+var screenshotCss = `/* Injected into every screenshot. The Next dev-tools indicator changes with the
+ * dev server's state, so it stays out of frame. */
+nextjs-portal { display: none !important; }
+`;
+var ciWorkflow = `name: redspec
+on:
+  pull_request:
+  push:
+    branches: [main]
+jobs:
+  spec:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      # The gate. Red on a skeleton is correct; red on main is a stop.
+      - run: pnpm exec redspec check
+      - run: pnpm test
+`;
+var brief = (slug, title2) => `# ${title2}
+
+## Problem
+
+What is wrong today, from the perspective of the person it is wrong for. Two or three sentences.
+
+## Actors
+
+- **Someone**: what they want from this. One bolded bullet per actor; the audit reads this list and fails on an actor with no flow.
+
+## What changes
+
+The shortest honest statement of the new capability.
+
+## Non-goals
+
+- **Something a reader would assume is included.** Why it is not.
+
+## Deliberate unknowns
+
+- **A question knowingly left open.** What happens if the guess is wrong, and how expensive that is.
+`;
+var specTs = (slug, title2) => `import { defineSpec } from "@redspec/core"
+import { copy } from "./copy"
+import * as fixtures from "./fixtures"
+import * as sketches from "./sketches"
+
+// \`redspec status\` is the work list. After /draft-skeleton, \`surfaces\` and
+// \`flows\` are filled and \`cases\` is empty: every declared state is a stub on
+// the board and a red line in status. /render-states fills \`cases\`.
+export default defineSpec({
+  slug: "${slug}",
+  title: "${title2}",
+
+  surfaces: {
+    // <key>: {
+    //   title: "The screen",
+    //   checklist: {
+    //     empty: { state: "STATE-${slug}-<key>-empty" },
+    //     loading: { state: "STATE-${slug}-<key>-loading" },
+    //     partial: { waived: "Why this screen cannot be half-loaded.", witness: "INV-\u2026" },
+    //     populated: { state: "STATE-${slug}-<key>-populated" },
+    //     overflowing: { state: "STATE-${slug}-<key>-overflowing" },
+    //     recoverableError: { state: "STATE-${slug}-<key>-retry" },
+    //     terminalError: { state: "STATE-${slug}-<key>-failed" },
+    //     permissionDenied: { state: "STATE-${slug}-<key>-read-only" },
+    //     stale: { waived: "Reads are live.", review: "2027-01-01" },
+    //     inFlight: { state: "STATE-${slug}-<key>-saving" },
+    //     terminalSuccess: { waived: "A place, not a flow that finishes." },
+    //     conflict: { state: "STATE-${slug}-<key>-conflict" },
+    //   },
+    // },
+  },
+
+  // What each declared state *is*, in one line -- said where it is declared,
+  // because the board is read from here until /render-states, and a state
+  // whose only name is its ID is a state nobody can review. Say what the
+  // person is looking at, not which row it answers.
+  states: {
+    // "STATE-${slug}-<key>-empty": "Nothing here yet, and one button to start",
+  },
+
+  cases: {},
+
+  flows: [
+    // {
+    //   id: "JOURNEY-${slug}-<intent>",
+    //   title: "What the actor gets",
+    //   actor: "Someone",            // must match a bolded actor in BRIEF.md
+    //   spine: [
+    //     { case: "STATE-${slug}-<key>-empty", on: "Does the first thing" },
+    //     { case: "STATE-${slug}-<key>-populated", end: "What they are left with." },
+    //   ],
+    //   deviations: [
+    //     { from: "STATE-${slug}-<key>-populated", when: "Cold cache", case: "STATE-${slug}-<key>-loading", rejoins: "STATE-${slug}-<key>-populated" },
+    //   ],
+    // },
+  ],
+})
+
+// Keep the imports live so the skeleton typechecks before any case uses them.
+void copy
+void fixtures
+void sketches
+`;
+var copyTs = (slug) => `import { defineCopy } from "@redspec/core"
+
+// Every user-facing string this feature ships, once. Sketches render from it;
+// assertions assert against it. A word changes here and both readers see it.
+export const copy = defineCopy({
+  // "COPY-${slug}-<key>-empty-title": "Nothing here yet",
+})
+`;
+var fixturesTs = () => `// Fixtures for the cases. Plain data, no network, no database: a case that
+// reaches for either is a Journey wearing a State's clothes.
+export {}
+`;
+var sketchesTsx = () => `// Sketch markup for the cases. Drafts: a slice promotes them into components/
+// and the assertions survive unchanged, which is why those are written in
+// user intent rather than against a selector.
+export {}
+`;
+var stateSpec = (slug) => `import { expect, test } from "@playwright/test"
+import { copy } from "../../specs/${slug}/copy"
+
+// One behavioural assertion and one screenshot per state, named for its ID,
+// written in user intent. \`redspec new state <ID>\` appends here.
+void copy
+void expect
+void test
+`;
+var journeySpecHeader = (slug) => `import { test } from "@playwright/test"
+
+// Generated by \`redspec new journeys ${slug}\` from the flows in spec.ts \u2014 one
+// per reachable path. Regenerate rather than edit. Each stays fixme until the
+// slice that claims its JOURNEY- lands and un-fixmes it.
+`;
+var journeyTest = (id, index, states, labels, end) => {
+  const steps = states.map((s, i) => labels[i] ? `  // ${s}
+  //   \u2192 ${labels[i]}` : `  // ${s}`).join("\n");
+  return `
+test.fixme("${id} [path ${index + 1}]: ${end.replace(/"/g, '\\"')}", async ({ page }) => {
+${steps}
+  // Ends: ${end}
+  await page.goto("/")
+})
+`;
+};
+var stateFixture = (id) => `
+// ${id}
+export const ${camel(id)} = {}
+`;
+var stateSketch = (id, component) => `
+// ${id}
+export function ${component}() {
+  return <div>{/* ${id} */}</div>
+}
+`;
+var stateAssertion = (id) => `
+test("${id} <what a reviewer would say out loud about it>", async ({ page }) => {
+  await page.goto("/spec/<slug>/${id}")
+  // await expect(page.getByText(copy["COPY-\u2026"])).toBeVisible()
+  await expect(page).toHaveScreenshot("${id}.png")
+})
+`;
+var caseSnippet = (id, surface, component, fixture) => `    "${id}": {
+      surface: "${surface}",
+      render: () => <sketches.${component} {...fixtures.${fixture}} />,
+    },`;
+var stateNameSnippet = (id) => `    "${id}": "<what the person is looking at>",`;
+function camel(id) {
+  return id.replace(/^(STATE|RULE|INV|JOURNEY|COPY)-/, "").split("-").map((p2, i) => i === 0 ? p2 : p2[0].toUpperCase() + p2.slice(1)).join("");
+}
+function pascal(id) {
+  const c = camel(id);
+  return c[0].toUpperCase() + c.slice(1);
+}
+var ruleStub = (id) => `# ${id}
+
+What this rule decides, in one sentence.
+
+| Input | Output | Why |
+| --- | --- | --- |
+| the figure the person gave | in their words | their reason |
+
+**Status:** stub. /implement-rules picks the rung.
+`;
+var ruleTable = (id) => `## ${id}
+
+What this rule decides, in one sentence.
+
+**Inputs:** amount: number(0..), plan: {free, pro}
+**Hit policy:** UNIQUE
+
+| amount   | plan | outcome | note |
+| -------- | ---- | ------- | ---- |
+| [0..100] | -    | allowed | under the limit |
+| (100..]  | free | blocked | free plans stop at 100 |
+| (100..]  | pro  | allowed | pro plans have no limit |
+
+<!-- \`redspec check\` proves this total and non-overlapping. Drive it from a test with
+     parseDecisionTable + decide + representativeInputs from @redspec/core. -->
+`;
+var ruleTableTest = (id) => `import { readFileSync } from "node:fs"
+import { join } from "node:path"
+import { describe, expect, it } from "vitest"
+import { decide, parseDecisionTable, representativeInputs } from "@redspec/core"
+
+// ${id}: the markdown table is the artifact a reviewer signs; this is plumbing.
+const table = parseDecisionTable(readFileSync(join(import.meta.dirname, "${id}.md"), "utf8"))
+
+// Replace with the real implementation under test.
+const implementation = (input: Record<string, number | string | boolean>) => decide(table, input)
+
+describe("${id}", () => {
+  it("agrees with the table in every region it distinguishes", () => {
+    for (const input of representativeInputs(table)) {
+      expect(implementation(input)).toEqual(decide(table, input))
+    }
+  })
+})
+`;
+var ruleMachine = (id) => `// ${id}
+//
+// A lifecycle as an explicit states \xD7 events table. The empty cells are the
+// point: an undefined transition is visible by inspection.
+
+export type State = "draft" | "submitted" | "approved"
+export type Event = "submit" | "approve" | "reject"
+
+export const machine = {
+  draft: { submit: "submitted" },
+  submitted: { approve: "approved", reject: "draft" },
+  approved: {},
+} as const satisfies Record<State, Partial<Record<Event, State>>>
+
+export function next(state: State, event: Event): State | null {
+  return (machine[state] as Partial<Record<Event, State>>)[event] ?? null
+}
+`;
+var ruleMachineTest = (id) => `import fc from "fast-check"
+import { describe, expect, it } from "vitest"
+import { machine, next, type Event, type State } from "./${id}"
+
+// ${id}: two tests. The shape test proves the table is well-formed; the
+// model-based run proves the implementation *is* the table.
+describe("${id}", () => {
+  it("names every state", () => {
+    const states: State[] = ["draft", "submitted", "approved"]
+    for (const s of states) expect(machine).toHaveProperty(s)
+  })
+
+  it("the implementation tracks the table across random legal event sequences", () => {
+    const events: Event[] = ["submit", "approve", "reject"]
+    fc.assert(
+      fc.property(fc.array(fc.constantFrom(...events), { maxLength: 20 }), (seq) => {
+        let model: State = "draft"
+        // Replace \`sut\` with the real system under test and step it alongside the model.
+        let sut: State = "draft"
+        for (const e of seq) {
+          const to = next(model, e)
+          if (to === null) continue // illegal in the model: the SUT must refuse it too
+          model = to
+          sut = to
+          expect(sut).toBe(model)
+        }
+      })
+    )
+  })
+})
+`;
+var ruleInvariant = (id) => `import fc from "fast-check"
+import { describe, expect, it } from "vitest"
+
+// ${id}: a sentence about the domain that admits no exception.
+describe("${id}", () => {
+  it("holds for every input", () => {
+    fc.assert(
+      fc.property(fc.integer(), (n) => {
+        expect(n + 0).toBe(n) // replace with the property
+      })
+    )
+  })
+})
+`;
+var ruleType = (id) => `// ${id}
+//
+// Make the illegal state unrepresentable and the rule needs no test.
+export type Example =
+  | { status: "draft" }
+  | { status: "sent"; sentAt: Date }
+`;
+var slice = (title2, claims, amends) => `# ${title2}
+
+**Delivers:** the end-to-end behaviour this makes work, from the user's perspective.
+
+**Blocked by:** None.
+${amends.length ? `
+**Amends:**
+
+${amends.map((a) => `- \`${a}\``).join("\n")}
+
+**Because:** why the requirement moved.
+` : ""}
+**Claims:**
+
+${claims.map((c) => `- \`${c}\``).join("\n") || "- `STATE-\u2026`"}
+
+**Status:** ready
+`;
+
+// src/commands/init.ts
+async function init(opts) {
+  const root = opts.root;
+  const log = opts.quiet ? () => {
+  } : console.log;
+  const pkgPath = join7(root, "package.json");
+  const pkg = existsSync7(pkgPath) ? JSON.parse(readFileSync5(pkgPath, "utf8")) : null;
+  if (!pkg)
+    throw new Error(
+      `No package.json in ${root}. Run redspec init at the root of a Node project.`
+    );
+  const detectedFramework = opts.framework ?? detectFramework(pkg);
+  const detectedHarnesses = detectHarnesses(root);
+  const runners = hasTestRunner(pkg);
+  const pm = packageManager(root);
+  let harnesses;
+  let framework = detectedFramework;
+  if (opts.harness !== void 0) {
+    harnesses = opts.harness.split(",").map((h) => h.trim()).filter((h) => HARNESSES2.includes(h));
+  } else if (opts.yes) {
+    const existing = existsSync7(join7(root, "spec.config.ts")) ? (await loadConfig2(root)).config.harnesses : null;
+    harnesses = existing ?? detectedHarnesses.map((d) => d.harness);
+  } else {
+    p.intro(pc7.bgCyan(pc7.black(" redspec ")));
+    p.note(
+      [
+        `framework   ${framework === "next" ? pc7.green("Next.js") : pc7.yellow("none detected \u2014 core only, no board")}`,
+        `unit tests  ${runners.unit ?? pc7.yellow("none \u2014 vitest will be added")}`,
+        `browser     ${runners.browser ?? pc7.yellow("none \u2014 @playwright/test will be added")}`,
+        "",
+        ...HARNESSES2.map((h) => {
+          const d = detectedHarnesses.find((x) => x.harness === h);
+          return `${d ? pc7.green("\u2713") : pc7.dim("\u25CB")} ${h.padEnd(9)} ${d ? pc7.dim(d.evidence) : ""}`;
+        })
+      ].join("\n"),
+      "Detected"
+    );
+    const picked = await p.multiselect({
+      message: "Write agent context for which harnesses?",
+      options: HARNESSES2.map((h) => ({
+        value: h,
+        label: h,
+        hint: CAPABILITIES2[h].hitlOnly ? "steps are HITL-only" : "steps are conventions; CI is the guardrail"
+      })),
+      initialValues: detectedHarnesses.map((d) => d.harness),
+      required: false
+    });
+    if (p.isCancel(picked)) {
+      p.cancel("Nothing written.");
+      process.exit(1);
+    }
+    harnesses = picked;
+    if (framework === "none") {
+      const go = await p.confirm({
+        message: "No supported framework found. Set up core only (specs, rules, lock, coverage \u2014 no spec route or board)?"
+      });
+      if (p.isCancel(go) || !go) {
+        p.cancel("Nothing written.");
+        process.exit(1);
+      }
+    }
+  }
+  const w = new Writer(root);
+  const config = defineSpecConfig({ framework, harnesses });
+  w.create("spec.config.ts", specConfig(framework, harnesses));
+  w.create("specs/index.ts", specsIndex);
+  w.create("specs/.gitkeep", "");
+  w.create("e2e/state/.gitkeep", "");
+  w.create("e2e/journey/.gitkeep", "");
+  w.create("e2e/screenshot.css", screenshotCss);
+  if (!runners.browser) w.create("playwright.config.ts", playwrightConfig);
+  w.create(".github/workflows/redspec.yml", ciWorkflow);
+  if (framework === "next") {
+    const src = existsSync7(join7(root, "src/app")) ? "src/" : "";
+    if (existsSync7(join7(root, `${src}proxy.ts`)) || existsSync7(join7(root, `${src}middleware.ts`))) {
+      w.create(`${src}proxy.redspec.ts`, proxy);
+      log(
+        pc7.yellow(
+          `  A proxy/middleware already exists. Wrote ${src}proxy.redspec.ts \u2014 merge its gate into yours.`
+        )
+      );
+    } else {
+      w.create(`${src}proxy.ts`, proxy);
+    }
+    w.create(`${src}app/spec/_routes.ts`, nextRoutes(config));
+    w.create(`${src}app/spec/layout.tsx`, nextLayout);
+    w.create(`${src}app/spec/page.tsx`, nextIndex);
+    w.create(`${src}app/spec/[feature]/page.tsx`, nextBoard);
+    w.create(`${src}app/spec/[feature]/[case]/page.tsx`, nextCase);
+  }
+  const scripts = pkg.scripts ?? {};
+  const add = {
+    spec: "redspec check",
+    "spec:status": "redspec status",
+    "test:state": "playwright test --project=state",
+    "test:journey": "playwright test --project=journey"
+  };
+  if (!runners.unit) add.test = "vitest run";
+  let changed = false;
+  for (const [k, v] of Object.entries(add)) {
+    if (!scripts[k]) {
+      scripts[k] = v;
+      changed = true;
+    }
+  }
+  if (changed) {
+    pkg.scripts = scripts;
+    writeFileSync2(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    w.written.push({ path: "package.json", action: "updated" });
+  }
+  const synced = sync(root, config, harnesses);
+  w.written.push(...synced.written);
+  const runtime = ["@redspec/core", "@redspec/cli"];
+  if (framework === "next") runtime.push("@redspec/next");
+  const dev = ["fast-check"];
+  if (!runners.unit) dev.push("vitest");
+  if (!runners.browser) dev.push("@playwright/test");
+  const needRuntime = missingDeps(root, runtime);
+  const needDev = missingDeps(root, dev);
+  const installLines = [
+    ...needRuntime.length ? [installCommand(pm, needRuntime, false)] : [],
+    ...needDev.length ? [installCommand(pm, needDev, true)] : []
+  ];
+  if (!opts.quiet) {
+    for (const f of w.written) {
+      if (f.action === "kept") continue;
+      log(
+        `  ${f.action === "created" ? pc7.green("create") : pc7.cyan("update")}  ${f.path}`
+      );
+    }
+  }
+  const installed = opts.skipInstall ? false : installDeps(root, pm, needRuntime, false, log) && installDeps(root, pm, needDev, true, log);
+  if (!opts.quiet) {
+    log("");
+    log(pc7.bold("Next:"));
+    if (installLines.length && !installed) for (const l of installLines) log(`  ${l}`);
+    log(`  ${pm === "npm" ? "npx" : `${pm} exec`} redspec doctor`);
+    if (harnesses.length) {
+      log("");
+      for (const h of harnesses) {
+        log(`  ${pc7.dim(h.padEnd(9))} ${CAPABILITIES2[h].note}`);
+      }
+    }
+    log("");
+    log(pc7.dim("Then: /draft-skeleton <an idea, at whatever resolution you have it>"));
+  }
+  return { writer: w, install: installLines, harnesses, framework };
+}
+
+// src/commands/new.ts
+import { existsSync as existsSync8, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "fs";
+import { join as join8 } from "path";
+import pc8 from "picocolors";
+import { compileFlow, ID_PATTERN, simplePaths } from "@redspec/core";
+var title = (slug) => slug.split("-").map((p2) => p2[0].toUpperCase() + p2.slice(1)).join(" ");
+async function newFeature(root, slug, quiet = false) {
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(slug)) {
+    console.error(pc8.red(`"${slug}" is not a slug. Lowercase, hyphenated.`));
+    return 1;
+  }
+  const ctx = await loadContext(root);
+  const dir = join8(ctx.config.specsDir, slug);
+  const w = new Writer(root);
+  w.create(`${dir}/BRIEF.md`, brief(slug, title(slug)));
+  w.create(`${dir}/${ctx.config.specFile}`, specTs(slug, title(slug)));
+  w.create(`${dir}/copy.ts`, copyTs(slug));
+  w.create(`${dir}/fixtures.ts`, fixturesTs());
+  w.create(`${dir}/sketches.tsx`, sketchesTsx());
+  w.create(`${dir}/rules/.gitkeep`, "");
+  w.create(`${dir}/slices/.gitkeep`, "");
+  w.create(`${ctx.config.stateTestsDir}/${slug}.spec.ts`, stateSpec(slug));
+  w.create(`${ctx.config.journeyTestsDir}/${slug}.spec.ts`, journeySpecHeader(slug));
+  const indexPath = join8(root, ctx.config.specsDir, "index.ts");
+  if (existsSync8(indexPath)) {
+    const ident = slug.replace(/-(\w)/g, (_, c) => c.toUpperCase()) + "Spec";
+    let src = readFileSync6(indexPath, "utf8");
+    if (!src.includes(`./${slug}/spec`)) {
+      src = src.replace(
+        "// redspec:imports",
+        `import ${ident} from "./${slug}/spec"
+// redspec:imports`
+      );
+      src = src.replace("  // redspec:specs", `  ${ident},
+  // redspec:specs`);
+      writeFileSync3(indexPath, src);
+      w.written.push({ path: `${ctx.config.specsDir}/index.ts`, action: "updated" });
+    }
+  }
+  report(w, quiet);
+  if (!quiet)
+    console.log(
+      pc8.dim(
+        `
+Now fill ${dir}/BRIEF.md and declare surfaces and flows in ${dir}/${ctx.config.specFile}. \`redspec status\` is the work list.`
+      )
+    );
+  return 0;
+}
+async function newState(root, id, opts) {
+  if (!ID_PATTERN.test(id) || !id.startsWith("STATE-")) {
+    console.error(pc8.red(`"${id}" is not a STATE- ID. Lowercase, hyphenated.`));
+    return 1;
+  }
+  const ctx = await loadContext(root);
+  const owner = ctx.specs.find((s) => id.startsWith(`STATE-${s.spec.slug}-`));
+  if (!owner) {
+    console.error(
+      pc8.red(
+        `No feature's slug prefixes "${id}". Features: ${ctx.specs.map((s) => s.spec.slug).join(", ") || "none"}.`
+      )
+    );
+    return 1;
+  }
+  const slug = owner.spec.slug;
+  const declared = ctx.reports.find((r) => r.slug === slug).artifacts.some((a) => a.id === id);
+  if (!declared)
+    console.log(
+      pc8.yellow(
+        `  "${id}" is not declared by any checklist row or flow yet. Declare it in ${ctx.config.specFile} too, or the audit will call it unclaimed.`
+      )
+    );
+  const rel = (f) => join8(ctx.config.specsDir, slug, f);
+  const local = id.slice(`STATE-${slug}-`.length);
+  const component = pascal(local);
+  const fixture = camel(local);
+  const w = new Writer(root);
+  if (!(w.read(rel("fixtures.ts")) ?? "").includes(`// ${id}`))
+    w.append(rel("fixtures.ts"), stateFixture(id));
+  if (!(w.read(rel("sketches.tsx")) ?? "").includes(`// ${id}`))
+    w.append(rel("sketches.tsx"), stateSketch(id, component));
+  const testPath = `${ctx.config.stateTestsDir}/${slug}.spec.ts`;
+  if (!(w.read(testPath) ?? "").includes(`"${id} `))
+    w.append(testPath, stateAssertion(id).replace("<slug>", slug));
+  report(w, opts.quiet);
+  const surface = opts.surface ?? Object.keys(owner.spec.surfaces)[0] ?? "<surface>";
+  if (!opts.quiet) {
+    console.log(`
+Add to \`states\` in ${rel(ctx.config.specFile)}:
+`);
+    console.log(stateNameSnippet(id));
+    console.log(`
+And to \`cases\`:
+`);
+    console.log(caseSnippet(id, surface, component, fixture));
+    console.log(
+      pc8.dim(
+        "\nThen fill the fixture, the sketch (strings via copy.ts), and the assertion (user intent, no selectors)."
+      )
+    );
+  }
+  return 0;
+}
+async function newRule(root, id, opts) {
+  if (!ID_PATTERN.test(id) || !/^(RULE|INV)-/.test(id)) {
+    console.error(pc8.red(`"${id}" is not a RULE- or INV- ID.`));
+    return 1;
+  }
+  const ctx = await loadContext(root);
+  const slug = opts.feature ?? (ctx.specs.length === 1 ? ctx.specs[0].spec.slug : void 0);
+  if (!slug) {
+    console.error(pc8.red("Pass --feature <slug>; more than one feature is declared."));
+    return 1;
+  }
+  const dir = join8(ctx.config.specsDir, slug, "rules");
+  const w = new Writer(root);
+  switch (opts.form) {
+    case "stub":
+      w.create(`${dir}/${id}.md`, ruleStub(id));
+      break;
+    case "table":
+      w.create(`${dir}/${id}.md`, ruleTable(id));
+      w.create(`${dir}/${id}.test.ts`, ruleTableTest(id));
+      break;
+    case "machine":
+      w.create(`${dir}/${id}.ts`, ruleMachine(id));
+      w.create(`${dir}/${id}.test.ts`, ruleMachineTest(id));
+      break;
+    case "invariant":
+      w.create(`${dir}/${id}.test.ts`, ruleInvariant(id));
+      w.create(`${dir}/${id}.ts`, `// ${id}: see ${id}.test.ts
+export {}
+`);
+      break;
+    case "type":
+      w.create(`${dir}/${id}.ts`, ruleType(id));
+      break;
+    default:
+      console.error(pc8.red(`--form must be stub, table, machine, invariant, or type.`));
+      return 1;
+  }
+  report(w, opts.quiet);
+  return 0;
+}
+async function newSlice(root, slug, name, opts) {
+  const ctx = await loadContext(root);
+  if (!ctx.specs.some((s) => s.spec.slug === slug)) {
+    console.error(pc8.red(`No feature "${slug}".`));
+    return 1;
+  }
+  if (!/^A?\d{2}-[a-z0-9-]+$/.test(name)) {
+    console.error(
+      pc8.red(
+        `Slice files are <NN>-<name> (or A<NN>-<name> for an amendment): "${name}" is not.`
+      )
+    );
+    return 1;
+  }
+  const heading = `${name.split("-")[0]}: ${title(name.split("-").slice(1).join("-"))}`;
+  const w = new Writer(root);
+  w.create(
+    join8(ctx.config.specsDir, slug, "slices", `${name}.md`),
+    slice(heading, opts.claims, opts.amends)
+  );
+  report(w, opts.quiet);
+  return 0;
+}
+async function newJourneys(root, slug, quiet = false) {
+  const ctx = await loadContext(root);
+  const owner = ctx.specs.find((s) => s.spec.slug === slug);
+  if (!owner) {
+    console.error(pc8.red(`No feature "${slug}".`));
+    return 1;
+  }
+  let out = journeySpecHeader(slug);
+  let n = 0;
+  for (const flow of owner.spec.flows) {
+    const { paths, truncated } = simplePaths(compileFlow(flow), ctx.config.journeyBudget);
+    paths.forEach((path, i) => {
+      out += journeyTest(flow.id, i, path.states, path.labels, path.end);
+      n++;
+    });
+    if (truncated)
+      out += `
+// ${flow.id}: path enumeration stopped at the budget (${ctx.config.journeyBudget}). Raise journeyBudget in spec.config.ts, or simplify the flow.
+`;
+  }
+  const w = new Writer(root);
+  w.write(`${ctx.config.journeyTestsDir}/${slug}.spec.ts`, out);
+  report(w, quiet);
+  if (!quiet)
+    console.log(
+      pc8.dim(
+        `${n} path${n === 1 ? "" : "s"} across ${owner.spec.flows.length} flow${owner.spec.flows.length === 1 ? "" : "s"}.`
+      )
+    );
+  return 0;
+}
+function report(w, quiet) {
+  if (quiet) return;
+  for (const f of w.written) {
+    if (f.action === "kept") continue;
+    console.log(
+      `  ${f.action === "created" ? pc8.green("create") : pc8.cyan("update")}  ${f.path}`
+    );
+  }
+}
+
+// src/commands/status.ts
+async function status(root, opts = {}) {
+  const ctx = await loadContext(root);
+  if (opts.ids !== void 0) {
+    const reports = opts.ids ? ctx.reports.filter((r) => r.slug === opts.ids) : ctx.reports;
+    for (const r of reports) for (const a of r.artifacts) console.log(a.id);
+    return 0;
+  }
+  printStatus(ctx);
+  return 0;
+}
+
+// src/index.ts
+function program() {
+  const cli = new Command("redspec").description("Specs made of artifacts that can go red.").option("-C, --cwd <dir>", "repo root", process.cwd()).exitOverride();
+  const root = () => cli.opts().cwd;
+  cli.command("init").description(
+    "Set this repo up: config, spec route, test tiers, and agent context for the harnesses you use."
+  ).option("-y, --yes", "accept detected defaults, no prompts").option("--harness <list>", "comma-separated: claude,cursor,codex,copilot,gemini").option("--framework <name>", "next | none").option("--skip-install", "write the files, install nothing").action(
+    async (o) => {
+      await init({ root: root(), ...o });
+    }
+  );
+  cli.command("check").description(
+    "The gate: audit, coverage, decision tables, lock. Exit 1 on any finding."
+  ).option("--json", "machine-readable").option("-q, --quiet", "only the summary line").action(
+    async (o) => process.exit(await check(root(), o))
+  );
+  cli.command("status").description("The work list, in English.").option("--ids [slug]", "list artifact IDs (optionally for one feature) and exit").action(
+    async (o) => process.exit(
+      await status(root(), {
+        ids: o.ids === true ? "" : o.ids === false ? void 0 : o.ids
+      })
+    )
+  );
+  const n = cli.command("new").description("Scaffold an artifact. Never hand-write what this writes.");
+  n.command("feature <slug>").description(
+    "a bundle: BRIEF, spec.ts, copy, fixtures, sketches, rules/, slices/, both test files"
+  ).action(async (slug) => process.exit(await newFeature(root(), slug)));
+  n.command("state <id>").description("fixture, sketch, and assertion scaffolds for a declared STATE-").option("--surface <key>").action(
+    async (id, o) => process.exit(await newState(root(), id, o))
+  );
+  n.command("rule <id>").description("a rule on a rung").requiredOption("--form <form>", "stub | table | machine | invariant | type").option("--feature <slug>").action(
+    async (id, o) => process.exit(await newRule(root(), id, o))
+  );
+  n.command("slice <slug> <name>").description("a slice file: <NN>-<name>, or A<NN>-<name> for an amendment").option("--claims <ids...>", "artifact IDs", []).option("--amends <ids...>", "artifact IDs this amends", []).action(
+    async (slug, name, o) => process.exit(await newSlice(root(), slug, name, o))
+  );
+  n.command("journeys <slug>").description(
+    "regenerate the journey tier from the flows, one fixme per reachable path"
+  ).action(async (slug) => process.exit(await newJourneys(root(), slug)));
+  cli.command("accept [ids...]").description(
+    "Re-stamp artifacts after the verification command passes in this same run."
+  ).option("--slice <path>", "stamp every claim of one slice").option("--clarification <note>", "record that the change was wording, not behaviour").option("--command <cmd>", "override the configured verification command").action(
+    async (ids, o) => process.exit(await accept(root(), { ids, ...o }))
+  );
+  cli.command("sync").description("Re-render agent context for the configured harnesses.").action(async () => {
+    const ctx = await loadContext(root());
+    const w = sync(root(), ctx.config);
+    for (const f of w.written)
+      if (f.action !== "kept") console.log(`  ${f.action.padEnd(8)}${f.path}`);
+  });
+  cli.command("doctor").description("Verify the install and say what each harness can and cannot enforce.").action(async () => process.exit(await doctor(root())));
+  cli.command("board [feature]").description("Start the dev server and print the board URL.").action(async (feature) => process.exit(await board(root(), feature)));
+  return cli;
+}
+async function run(argv) {
+  try {
+    await program().parseAsync(argv);
+  } catch (e) {
+    const err = e;
+    if (err.code === "commander.helpDisplayed" || err.code === "commander.version" || err.code === "commander.help")
+      return;
+    console.error(err.message ?? String(e));
+    process.exit(1);
+  }
+}
+export {
+  accept,
+  check,
+  detectFramework,
+  detectHarnesses,
+  doctor,
+  init,
+  loadContext,
+  newFeature,
+  newJourneys,
+  newRule,
+  newSlice,
+  newState,
+  program,
+  run,
+  status,
+  sync
+};