@benjaminthomas/spec-driven-dev 1.8.0 → 1.11.0

package/bin/cli.mjs

@@ -5,19 +5,24 @@
 //   spec-driven-dev                 install + project setup (interactive)
 //   spec-driven-dev setup           project setup only
 //   spec-driven-dev doctor          check .spec-driven.yml against the real repos (exit 1 on problems)
-//   spec-driven-dev status          list specs with unfinished tasks (used by the session-start hook)
+//   spec-driven-dev status          list specs with unfinished work and each one's "Resume here" next step
+//   spec-driven-dev context         print specs/CONTEXT.md; --areas=billing,api prints only those area files
+//   spec-driven-dev risk            GitRisk: score files from git history into specs/context/risk.md (--files=a,b  --json  --top=N  --since=…)
+//   spec-driven-dev settings        switch features on or off from a menu (GitRisk, run-through); or --risk=on|off --after-approval=…
+//   spec-driven-dev risk-eval       U8 experiment: run tickets with risk on vs off and compare agent behaviour (--tickets=<file> --runs=N --model=… --arms=on,off --timeout=20)
 //   flags: --yes  --global  --tools=claude,cursor  --skills=spec-create,...  --no-setup  --dir=<path>
 //          --layout=single|monorepo|multi-repo  --repos=~/Projects/frontend,/srv/backend  --workspace=<config dir>
-//          --packages=apps/web,packages/ui  --after-approval=stop|run-through  --version
+//          --packages=apps/web,packages/ui  --after-approval=stop|run-through  --project=new|existing  --risk=on|off  --version
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import prompts from "prompts";  // arrow-key menus that work in PowerShell, cmd, macOS and Linux terminals
 import { fileURLToPath } from "node:url";
+import { scoreRepo, riskMarkdown, normWeights, weightProblems, setConfigValue } from "./risk.mjs";
 
 const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
-const SKILLS_DIR = path.join(ROOT, "skills");
+const SKILLS_DIR = path.join(ROOT, "plugin", "skills");
 const HOME = process.env.SPEC_DRIVEN_HOME || os.homedir(); // overridable for tests
 const ALL_SKILLS = fs.readdirSync(SKILLS_DIR).filter((d) => fs.existsSync(path.join(SKILLS_DIR, d, "SKILL.md")));
 
@@ -33,7 +38,7 @@ const args = process.argv.slice(2);
 const flag = (n) => args.includes(`--${n}`);
 const opt = (n) => args.find((a) => a.startsWith(`--${n}=`))?.split("=")[1];
 const command = args.find((a) => !a.startsWith("-")) || "install";
-const YES = flag("yes") || flag("y") || !process.stdin.isTTY || ["doctor", "status"].includes(command);
+const YES = flag("yes") || flag("y") || !process.stdin.isTTY || ["doctor", "status", "context", "risk", "risk-eval"].includes(command);
 const DIR = path.resolve(opt("dir") || process.cwd());
 
 if (flag("version") || flag("v")) {
@@ -42,22 +47,23 @@ if (flag("version") || flag("v")) {
 }
 // No terminal to answer in (e.g. `!` in Claude Code, an IDE task, a pipe) and nothing passed explicitly:
 // stop rather than write a config from guesses.
-const ANSWER_FLAGS = ["yes", "y", "layout", "repos", "packages", "tools", "workspace", "after-approval", "skills", "global", "no-setup"];
-if (["install", "setup"].includes(command) && !process.stdin.isTTY && !args.some((a) => ANSWER_FLAGS.some((f) => a === `--${f}` || a.startsWith(`--${f}=`)))) {
-  console.log(`✗ No interactive terminal, so setup can't ask its questions. Nothing was changed.
+const ANSWER_FLAGS = ["risk", "yes", "y", "layout", "repos", "packages", "tools", "workspace", "after-approval", "skills", "global", "no-setup", "project"];
+if (["install", "setup", "settings"].includes(command) && !process.stdin.isTTY && !args.some((a) => ANSWER_FLAGS.some((f) => a === `--${f}` || a.startsWith(`--${f}=`)))) {
+  console.log(`✗ No interactive terminal, so ${command === "settings" ? "the settings menu can't open" : "setup can't ask its questions"}. Nothing was changed.
 
   This happens when it runs through another program: a "!" command in Claude Code, an editor task,
   or piped input. Either:
     • run it yourself in a terminal window (Terminal, iTerm, or your editor's terminal panel):
-        npx @benjaminthomas/spec-driven-dev@latest ${command === "setup" ? "setup" : ""}
+        npx @benjaminthomas/spec-driven-dev@latest ${command === "install" ? "" : command}
     • or give the answers as flags, for example:
-        npx @benjaminthomas/spec-driven-dev@latest setup --layout=multi-repo --repos=~/Projects/frontend,~/Projects/backend
+        npx @benjaminthomas/spec-driven-dev@latest ${command === "settings" ? "settings --risk=off" : "setup --layout=multi-repo --repos=~/Projects/frontend,~/Projects/backend"}
       (add --yes to accept everything it detects)`);
   process.exit(1);
 }
 
 if (flag("help") || flag("h")) {
-  console.log(fs.readFileSync(fileURLToPath(import.meta.url), "utf8").split("\n").slice(1, 11).join("\n").replace(/^\/\/ ?/gm, ""));
+  const lines = fs.readFileSync(fileURLToPath(import.meta.url), "utf8").split("\n").slice(1);
+  console.log(lines.slice(0, lines.findIndex((l) => !l.startsWith("//"))).join("\n").replace(/^\/\/ ?/gm, "")); // the whole header comment
   process.exit(0);
 }
 
@@ -109,7 +115,7 @@ async function install() {
 
   // Claude Code users who already have the plugin would get every skill twice.
   const plugins = path.join(HOME, ".claude/plugins/installed_plugins.json");
-  if (tools.includes("claude") && !opt("tools") && fs.existsSync(plugins) && fs.readFileSync(plugins, "utf8").includes('"spec-driven-dev@')) {
+  if (tools.includes("claude") && !opt("tools") && fs.existsSync(plugins) && /"(spec-driven-dev|ticket-to-pr)@/.test(fs.readFileSync(plugins, "utf8"))) {
     console.log("• Claude Code already has the spec-driven-dev plugin, so it's skipped here (update it with /plugin).");
     tools = tools.filter((t) => t !== "claude");
   }
@@ -239,7 +245,9 @@ function toYaml(c) {
     .map(([tool, m]) => `  ${tool}:\n` + MODEL_KEYS.map((t) => `    ${t}: ${m[t]}\n`).join("")).join("");
   out += "effort:   # effort / reasoning level per tier (Claude Code, Codex): low | medium | high | xhigh | max | default\n"
     + MODEL_KEYS.map((t) => `  ${t}: ${EFFORT_DEFAULTS[t]}\n`).join("");
-  out += `pipeline:\n  after_approval: ${c.afterApproval || "stop"}   # stop | run-through (implement → verify → checkpoint; ship always asks)\n`;
+  out += `context:   # project memory: {specs_dir}/CONTEXT.md (index) + context/<area>.md\n  project: ${c.project || "existing"}   # existing | new\n  graph: auto   # auto = use graphify if installed | off\n`;
+  out += "risk:   # GitRisk: historical risk per file from git (spec-driven-dev risk). Weights are a hypothesis to calibrate\n  enabled: on   # on | off (off = skills ignore risk; risk-eval compares the two)\n  since: \"2 years ago\"\n  weights:\n    churn: 0.30\n    bug_density: 0.35\n    fan_out: 0.20\n    security: 0.15\n";
+  out += `pipeline:\n  after_approval: ${c.afterApproval || "stop"}   # stop | run-through (implement → verify → review → checkpoint; ship always asks)\n`;
   return out + `specs_dir: ${y(c.specsDir)}\n`;
 }
 
@@ -381,7 +389,16 @@ async function choosePackages(d) {
   return { root, repos: pkgs };
 }
 
+// shortcut: counts only (no model here), so a big template repo with 1 commit reads as existing; the spec-setup skill confirms.
+function detectProject(dirs) {
+  const n = (d, a) => Number(run("git", a, d).split("\n").filter(Boolean).length);
+  const commits = dirs.reduce((t, d) => t + (Number(run("git", ["rev-list", "--count", "HEAD"], d)) || 0), 0);
+  const files = dirs.reduce((t, d) => t + n(d, ["ls-files"]), 0);
+  return { commits, files, kind: commits >= 20 || files >= 50 ? "existing" : "new" };
+}
+
 async function setup() {
+  if (opt("project") && !["new", "existing"].includes(opt("project"))) throw new Error("--project must be new or existing");
   if (opt("after-approval") && !["stop", "run-through"].includes(opt("after-approval"))) throw new Error("--after-approval must be stop or run-through");
   console.log("\nProject setup — detecting how this project works…");
   const d = detectLayout(DIR);
@@ -439,11 +456,17 @@ async function setup() {
   const specsDir = await askText("Folder for specs (one sub-folder per feature)", "specs");
   const afterApproval = opt("after-approval") || await askSelect("After you approve a spec…", [
     { title: "Stop after each stage", value: "stop", description: "you start implement, verify and checkpoint yourself" },
-    { title: "Run straight through", value: "run-through", description: "implement → verify → commit in one go; stops at any failure, never pushes without asking" },
+    { title: "Run straight through", value: "run-through", description: "implement → verify → review → commit in one go; stops at any failure or review blocker, never pushes without asking" },
   ], "stop");
 
+  const pd = detectProject(repoDirs.filter(isRepo));
+  const project = opt("project") || await askSelect("Is this a new project or an existing one?", [
+    { title: `Existing project${pd.kind === "existing" ? "  (detected)" : ""}`, value: "existing", description: `${pd.commits} commits, ${pd.files} files — your AI tool audits it once and saves what it learns` },
+    { title: `New project${pd.kind === "new" ? "  (detected)" : ""}`, value: "new", description: "nothing to audit — your AI tool asks about the stack and conventions you want" },
+  ], pd.kind);
+
   const config = {
-    layout, tracker: { type: trackerType, key, url }, specsDir, devUrl: "", afterApproval,
+    project, layout, tracker: { type: trackerType, key, url }, specsDir, devUrl: "", afterApproval,
     git: { remote: "origin", base_branch: base, pr_target: pr, branch_name: branchName, commit_style: commitStyle },
     commands: layout === "single" ? commandsFor(repoDirs[0]) : commandsFor(root),
     repos: repos.map((r) => {
@@ -456,7 +479,9 @@ async function setup() {
   if (layout === "multi-repo") register(real(file), repos.map((r) => real(path.resolve(root, r))));
   console.log(`✓ Wrote ${file}`);
   console.log(isRepo(root) ? "  Commit it so your team shares the same rules." : "  This folder isn't a git repo, so the config is personal to this machine.");
-  console.log('  Fill in repo roles, dev_url, and non-Node commands by asking your AI tool to "run spec-setup".');
+  console.log(project === "existing"
+    ? `  Next: ask your AI tool to "run spec-setup". It audits the ${layout === "multi-repo" ? "repos" : "repo"}, asks a few questions, and saves ${specsDir}/CONTEXT.md.`
+    : `  Next: ask your AI tool to "run spec-setup". It asks about your stack and conventions and saves ${specsDir}/CONTEXT.md.`);
 }
 
 // ---------- reading the config ----------
@@ -496,10 +521,20 @@ function parseYaml(text) {
   return root;
 }
 
+// A multi-repo config applies only in its own folder and inside the repos it lists, so a repo that
+// merely sits under that folder (e.g. ~/Projects/other-project) doesn't pick up the workspace's rules.
+function configApplies(f, dir) {
+  let c;
+  try { c = parseYaml(fs.readFileSync(f, "utf8")); } catch { return true; }
+  if (c.layout !== "multi-repo" || !Array.isArray(c.repos)) return true;
+  const here = real(dir), base = path.dirname(f);
+  return here === real(base) || c.repos.some((r) => { const p = real(path.resolve(base, expandHome(String(r.path || "")))); return here === p || here.startsWith(p + path.sep); });
+}
+
 function findConfig(dir) {
   for (let d = dir; ; d = path.dirname(d)) {
     const f = path.join(d, ".spec-driven.yml");
-    if (fs.existsSync(f)) return f;
+    if (fs.existsSync(f) && configApplies(f, dir)) return f;
     if (d === path.dirname(d) || d === HOME) break;
   }
   // Not above us: a multi-repo workspace elsewhere may list this repo.
@@ -554,6 +589,15 @@ function doctor() {
   }
   const specs = path.join(root, c.specs_dir || "specs");
   if (!fs.existsSync(specs)) notes.push(`${c.specs_dir || "specs"}/ doesn't exist yet — created on first spec`);
+  if (c.context?.project && !["new", "existing"].includes(c.context.project)) problems.push(`context.project "${c.context.project}" must be new or existing`);
+  if (c.context?.graph && !["auto", "off"].includes(c.context.graph)) problems.push(`context.graph "${c.context.graph}" must be auto or off`);
+  const repoRoots = c.layout === "multi-repo" ? (c.repos || []).map((r) => path.resolve(root, expandHome(r.path))) : [root];
+  checkContext(specs, c.specs_dir || "specs", repoRoots, problems, notes);
+  if (c.risk) {
+    if (c.risk.enabled && !["on", "off"].includes(c.risk.enabled)) problems.push(`risk.enabled "${c.risk.enabled}" must be on or off`);
+    problems.push(...weightProblems(c.risk.weights));
+    if (c.risk.enabled !== "off" && !fs.existsSync(path.join(specs, "context", "risk.md"))) notes.push(`risk is on but ${c.specs_dir || "specs"}/context/risk.md doesn't exist — run: spec-driven-dev risk`);
+  }
   console.log(`Checked ${file}`);
   for (const n of notes) console.log(`  • ${n}`);
   for (const p of problems) console.log(`  ✗ ${p}`);
@@ -561,7 +605,140 @@ function doctor() {
   else console.log("✓ Config matches the repos.");
 }
 
-// Silent unless something is unfinished, so it costs no context in a session start hook.
+const LIMITS = { "CONTEXT.md": 60, area: 150 };
+// Context lines point at code as `path` or `path:line`; flag the ones that no longer exist anywhere in the repos.
+function checkContext(specs, specsName, repoRoots, problems, notes) {
+  const index = path.join(specs, "CONTEXT.md");
+  if (!fs.existsSync(index)) { notes.push(`no ${specsName}/CONTEXT.md yet — ask your AI tool to "run spec-setup" to audit the project`); return; }
+  const areaDir = path.join(specs, "context");
+  const files = [index, ...(fs.existsSync(areaDir) ? fs.readdirSync(areaDir).filter((f) => f.endsWith(".md") && f !== "archive.md").map((f) => path.join(areaDir, f)) : [])];
+  for (const f of files) {
+    const text = fs.readFileSync(f, "utf8");
+    const rel = path.relative(specs, f), max = f === index ? LIMITS["CONTEXT.md"] : LIMITS.area, lines = text.split("\n").length;
+    if (lines > max) problems.push(`${specsName}/${rel} is ${lines} lines (limit ${max}) — merge duplicates or move old entries to context/archive.md`);
+    for (const [, p] of text.matchAll(/`([\w.@-]+(?:\/[\w.@-]+)+\/?)(?::\d+)?`/g)) {
+      if (p.startsWith("context/") || /^(?:https?|www|@)/.test(p)) continue; // @scope/pkg is a package name, not a path
+      if (!repoRoots.some((r) => fs.existsSync(path.join(r, p)))) notes.push(`${specsName}/${rel} mentions \`${p}\`, which no longer exists — stale context?`);
+    }
+  }
+}
+
+function context() {
+  const file = findConfig(DIR);
+  const root = file ? path.dirname(file) : DIR;
+  const specsName = (file && parseYaml(fs.readFileSync(file, "utf8")).specs_dir) || "specs";
+  const index = path.join(root, specsName, "CONTEXT.md");
+  const areas = splitList(opt("areas"));
+  if (!areas.length) {
+    if (!fs.existsSync(index)) { console.log(`No ${specsName}/CONTEXT.md yet. Ask your AI tool to "run spec-setup" to create it.`); return; }
+    process.stdout.write(fs.readFileSync(index, "utf8"));
+    return;
+  }
+  for (const a of areas) {
+    const f = path.join(root, specsName, "context", `${a.replace(/[^\w-]/g, "")}.md`);
+    if (fs.existsSync(f)) process.stdout.write(fs.readFileSync(f, "utf8").replace(/\n*$/, "\n\n"));
+    else console.log(`(no ${specsName}/context/${a}.md — nothing recorded for this area yet)\n`);
+  }
+}
+
+function loadConfig() {
+  const file = findConfig(DIR);
+  return { file, root: file ? path.dirname(file) : gitTop(DIR), c: file ? parseYaml(fs.readFileSync(file, "utf8")) : {} };
+}
+
+function risk() {
+  const { root, c } = loadConfig();
+  const bad = weightProblems(c.risk?.weights);
+  if (bad.length) throw new Error(bad.join("; "));
+  const weights = normWeights(c.risk?.weights), since = opt("since") || c.risk?.since || "2 years ago";
+  const repoDirs = c.layout === "multi-repo" ? (c.repos || []).map((r) => ({ dir: path.resolve(root, expandHome(r.path)), name: r.path })) : [{ dir: root, name: path.basename(root) }];
+  const scored = repoDirs.filter((r) => isRepo(r.dir)).map((r) => ({ ...r, ...scoreRepo(r.dir, { since, weights, prefix: c.layout === "multi-repo" ? r.name : "" }) }));
+  if (!scored.length) throw new Error(`No git repo found at ${root}`);
+  const rows = scored.flatMap((s) => s.rows).sort((a, b) => b.score - a.score || b.commits - a.commits);
+  const wanted = splitList(opt("files"));
+  if (wanted.length) {
+    const norm = (f) => f.replace(/\\/g, "/").replace(/^\.\//, "");
+    const hits = wanted.map((f) => rows.find((r) => r.file === norm(f) || r.file.endsWith("/" + norm(f))) || { file: norm(f), score: null, tier: "no history" });
+    if (flag("json")) console.log(JSON.stringify(hits, null, 2));
+    else for (const h of hits) console.log(h.score === null ? `${h.file}: no history (new, untracked or not code)` : `${h.file}: ${h.score} ${h.tier} (churn ${h.factors.churn}, bug density ${h.factors.bug_density}, fan-out ${h.factors.fan_out}, security ${h.factors.security})`);
+    return;
+  }
+  if (flag("json")) { console.log(JSON.stringify({ weights, since, rows }, null, 2)); return; }
+  const specs = path.join(root, c.specs_dir || "specs");
+  fs.mkdirSync(path.join(specs, "context"), { recursive: true });
+  const out = path.join(specs, "context", "risk.md");
+  fs.writeFileSync(out, riskMarkdown({ rows, repos: scored, weights, since, top: Number(opt("top")) || 40 }));
+  const count = (t) => rows.filter((r) => r.tier === t).length;
+  console.log(`✓ Scored ${rows.length} files from ${scored.reduce((t, s) => t + s.commits, 0)} commits → ${path.relative(DIR, out) || out}`);
+  console.log(`  ${count("critical")} critical · ${count("high")} high · ${count("medium")} medium. Top 5:`);
+  for (const r of rows.slice(0, 5)) console.log(`  ${String(r.score).padStart(5)}  ${r.tier.padEnd(8)} ${r.file}`);
+  if (c.risk?.enabled === "off") console.log("  Note: risk.enabled is off in .spec-driven.yml, so the skills won't use this until you turn it on.");
+}
+
+async function riskEvalCmd() {
+  const { file, root, c } = loadConfig();
+  const repo = gitTop(DIR);
+  if (c.layout === "multi-repo" && real(repo) === real(root)) throw new Error("risk-eval runs on one repo: run it inside one of the workspace's repos");
+  const ticketsFile = opt("tickets");
+  if (!ticketsFile) throw new Error("Pass --tickets=<file> with one ticket per line");
+  const tickets = fs.readFileSync(path.resolve(DIR, ticketsFile), "utf8").split("\n").map((l) => l.replace(/^\s*[-*]\s+/, "").trim()).filter((l) => l && !l.startsWith("#"));
+  const claude = opt("claude") || "claude";
+  if (!opt("claude") && !onPath("claude")) throw new Error("risk-eval drives Claude Code headlessly; install it first (https://code.claude.com)");
+  const { riskEval } = await import("./risk-eval.mjs");
+  const runs = Number(opt("runs")) || 1, stages = splitList(opt("stages") || "investigate,create");
+  console.log(`GitRisk U8 experiment: ${tickets.length} ticket(s) × ${runs} run(s) × 2 arms (risk on / off) on ${root}`);
+  // A workspace config's repo paths don't resolve inside a lone clone, so a multi-repo member gets a single-repo config.
+  const configText = c.layout === "multi-repo" ? "version: 1\nlayout: single\n" : file ? fs.readFileSync(file, "utf8") : "";
+  const arms = splitList(opt("arms") || "on,off");
+  if (!arms.length || arms.some((a) => !["on", "off"].includes(a))) throw new Error("--arms must be on, off, or on,off");
+  const { dir } = await riskEval({ repo, tickets, arms, timeoutMin: Number(opt("timeout")) || 20, runs, model: opt("model") || "sonnet", stages, claude, out: path.resolve(DIR, opt("out") || "experiments"),
+    pluginDir: path.join(ROOT, "plugin"), since: c.risk?.since || "2 years ago", weights: c.risk?.weights, configText });
+  console.log(`✓ Report: ${path.join(dir, "report.md")}`);
+}
+
+// Plain-language switches, so anyone can change them without editing YAML.
+const SETTINGS = [
+  { block: "risk", key: "enabled", flag: "risk", name: "GitRisk", about: "extra care on files with a history of bugs",
+    get: (c) => c.risk?.enabled || "on", options: [
+      { value: "on", title: "On", description: "investigations, plans and reviews look harder at historically risky files" },
+      { value: "off", title: "Off", description: "the skills ignore risk completely" }] },
+  { block: "pipeline", key: "after_approval", flag: "after-approval", name: "After you approve a spec", about: "how far it goes on its own",
+    get: (c) => c.pipeline?.after_approval || "stop", options: [
+      { value: "stop", title: "Stop after each stage", description: "you start implement, verify, review and commit yourself" },
+      { value: "run-through", title: "Run straight through", description: "implement → verify → review → commit; stops at any failure, never pushes" }] },
+];
+
+async function settings() {
+  const file = findConfig(DIR);
+  if (!file) throw new Error(`No .spec-driven.yml in ${DIR} or above. Run: spec-driven-dev setup`);
+  let text = fs.readFileSync(file, "utf8");
+  const label = (s, v) => s.options.find((o) => o.value === v)?.title || v;
+  const save = (s, v) => {
+    if (!s.options.some((o) => o.value === v)) throw new Error(`--${s.flag} must be ${s.options.map((o) => o.value).join(" or ")}`);
+    text = setConfigValue(text, s.block, s.key, v);
+    fs.writeFileSync(file, text);
+    console.log(`✓ ${s.name}: ${label(s, v)}  (saved in ${file})`);
+  };
+  const given = SETTINGS.filter((s) => opt(s.flag));
+  if (given.length) given.forEach((s) => save(s, opt(s.flag)));
+  else for (;;) {
+    const c = parseYaml(text);
+    const pick = await askSelect("Settings: pick one to change", [
+      ...SETTINGS.map((s) => ({ title: `${s.name}: ${label(s, s.get(c))}`, description: s.about, value: s })),
+      { title: "Done", value: null }], null);
+    if (!pick) break;
+    const v = await askSelect(`${pick.name}`, pick.options, pick.get(c));
+    if (v !== pick.get(c)) save(pick, v);
+  }
+  const c = parseYaml(text);
+  if (c.risk?.enabled !== "off" && !fs.existsSync(path.join(path.dirname(file), c.specs_dir || "specs", "context", "risk.md"))) {
+    if (given.length || !(await askConfirm("GitRisk is on but files haven't been scored yet. Score them now? (uses git only, takes seconds)", true)))
+      console.log("  GitRisk is on, but nothing is scored yet. Run: spec-driven-dev risk");
+    else risk();
+  }
+}
+
+// Silent unless something is unfinished, so it's cheap to run at the start of a session.
 function status() {
   const file = findConfig(DIR);
   const root = file ? path.dirname(file) : DIR;
@@ -575,9 +752,12 @@ function status() {
       continue;
     }
     const t = fs.readFileSync(readme, "utf8");
+    const next = t.match(/^## Resume here[\s\S]*?^- \*\*Next:\*\*\s*(.+)$/m)?.[1]?.trim();
     const done = (t.match(/^\s*- \[x\]/gim) || []).length, todo = (t.match(/^\s*- \[ \]/gm) || []).length;
-    if (todo) lines.push(`- ${specsName}/${name}: ${done}/${done + todo} tasks done → next: spec-implement`);
+    if (todo) lines.push(`- ${specsName}/${name}: ${done}/${done + todo} tasks done → next: ${next || "spec-implement"}`);
     else if (done && !fs.existsSync(path.join(specs, name, "verification-report.md"))) lines.push(`- ${specsName}/${name}: all tasks done, not verified → next: spec-verify`);
+    else if (done && !fs.existsSync(path.join(specs, name, "review.md"))) lines.push(`- ${specsName}/${name}: verified, not reviewed → next: spec-review`);
+    else if (done && /\[blocker\][^\n]*\n(?:(?!###)[^\n]*\n)*?- \*\*Status:\*\* open/.test(fs.readFileSync(path.join(specs, name, "review.md"), "utf8"))) lines.push(`- ${specsName}/${name}: review has open blockers → next: fix them (spec-review)`);
   }
   if (lines.length) console.log(`spec-driven-dev: unfinished work in ${root}\n${lines.join("\n")}`);
 }
@@ -585,11 +765,15 @@ function status() {
 try {
   if (command === "doctor") doctor();
   else if (command === "status") status();
+  else if (command === "context") context();
+  else if (command === "risk") risk();
+  else if (command === "settings") await settings();
+  else if (command === "risk-eval") await riskEvalCmd();
   else if (command === "install") {
     await install();
     if (!flag("no-setup") && (await askConfirm("Set up this project now?", true))) await setup();
   } else if (command === "setup") await setup();
-  else throw new Error(`Unknown command "${command}" — use install (default), setup, doctor, or status`);
+  else throw new Error(`Unknown command "${command}" — use install (default), setup, settings, doctor, status, context, risk, or risk-eval`);
   if (["install", "setup"].includes(command)) console.log('\nNext: in your AI tool, say "investigate <ticket>" or "create a spec".');
 } catch (e) {
   console.error(`✗ ${e.message}`);

package/bin/risk-eval.mjs

@@ -0,0 +1,152 @@
+// GitRisk U8 experiment: does giving the agent the risk signal change what it does?
+// Each ticket runs twice in fresh clones of the repo, risk ON and risk OFF, with the same model and
+// prompt. We then measure behaviour from what the agent read and wrote, and keep a dated log.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync, spawnSync } from "node:child_process";
+import { scoreRepo, riskMarkdown, normWeights, setConfigValue } from "./risk.mjs";
+
+const TIER_RANK = { light: 1, standard: 2, deep: 3 };
+const sh = (cwd, cmd, args) => execFileSync(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"], maxBuffer: 512 * 1024 * 1024 }).toString();
+
+export const setRiskEnabled = (text, on) => setConfigValue(text, "risk", "enabled", on ? "on" : "off");
+
+// Behaviour metrics from the agent's transcript (stream-json) and the spec it wrote.
+export function measure({ transcript, clone, risky, tracked = [] }) {
+  const reads = new Set();
+  let cost = 0, turns = 0, inTok = 0, outTok = 0, error = "";
+  for (const line of transcript.split("\n")) {
+    let e;
+    try { e = JSON.parse(line); } catch { continue; }
+    if (e.type === "assistant") for (const c of e.message?.content || []) {
+      // A file counts as looked at when a Read, Grep or Bash call names it (agents often use grep/sed/cat, not Read).
+      if (c.type !== "tool_use" || !["Read", "Grep", "Bash", "Glob"].includes(c.name)) continue;
+      const text = JSON.stringify(c.input || {}).split(clone + "/").join("").split(clone.replace(/^\/private/, "") + "/").join("");
+      for (const f of tracked) if (text.includes(f)) reads.add(f);
+    }
+    if (e.type === "result") {
+      cost = e.total_cost_usd || 0; turns = e.num_turns || 0;
+      inTok = (e.usage?.input_tokens || 0) + (e.usage?.cache_read_input_tokens || 0) + (e.usage?.cache_creation_input_tokens || 0);
+      outTok = e.usage?.output_tokens || 0;
+      if (e.is_error) error = String(e.result || "error").slice(0, 200);
+    }
+  }
+  const specsDir = path.join(clone, "specs");
+  const feature = (fs.existsSync(specsDir) ? fs.readdirSync(specsDir) : []).find((d) => fs.existsSync(path.join(specsDir, d, "investigation.md")) || fs.existsSync(path.join(specsDir, d, "tasks")));
+  const read = (f) => { try { return fs.readFileSync(f, "utf8"); } catch { return ""; } };
+  const inv = feature ? read(path.join(specsDir, feature, "investigation.md")) : "";
+  const tasks = [];
+  const tdir = feature && path.join(specsDir, feature, "tasks");
+  if (tdir && fs.existsSync(tdir)) for (const t of fs.readdirSync(tdir).filter((f) => f.endsWith(".md"))) {
+    const text = read(path.join(tdir, t));
+    const section = (name) => (text.match(new RegExp(`^## ${name}\\s*\\n([\\s\\S]*?)(?=^## |$(?![\\s\\S]))`, "m")) || [])[1] || "";
+    const files = [...(section("Files to Create") + section("Files to Modify")).matchAll(/`([^`\s]+\.[\w]+)`/g)].map((m) => m[1]);
+    const tests = section("Tests").trim();
+    tasks.push({ name: t, files, tier: (text.match(/\*\*Tier:\*\*\s*(light|standard|deep)/i) || [])[1]?.toLowerCase(), hasTests: !!tests && !/^none\b/i.test(tests) });
+  }
+  const isRisky = (f) => risky.has(f);
+  const planFiles = new Set(tasks.flatMap((t) => t.files));
+  const riskyPlan = [...planFiles].filter(isRisky);
+  const riskyTasks = tasks.filter((t) => t.files.some(isRisky));
+  const avg = (xs) => (xs.length ? Math.round((xs.reduce((a, b) => a + b, 0) / xs.length) * 100) / 100 : null);
+  return {
+    feature: feature || null,
+    files_read: reads.size,
+    risky_files_read: [...reads].filter(isRisky).length,
+    investigation_risky_mentions: [...risky].filter((f) => inv.includes(f)).length,
+    plan_files: planFiles.size,
+    risky_plan_files: riskyPlan.length,
+    risky_files_with_tests: riskyPlan.filter((f) => tasks.some((t) => t.files.includes(f) && t.hasTests)).length,
+    tier_on_risky_tasks: avg(riskyTasks.map((t) => TIER_RANK[t.tier]).filter(Boolean)),
+    tier_all_tasks: avg(tasks.map((t) => TIER_RANK[t.tier]).filter(Boolean)),
+    tasks: tasks.length,
+    cost_usd: Math.round(cost * 10000) / 10000, turns, input_tokens: inTok, output_tokens: outTok, error,
+  };
+}
+
+const METRICS = [
+  ["risky_files_read", "Risky files looked at"], ["investigation_risky_mentions", "Risky files named in investigation"],
+  ["risky_plan_files", "Risky files in the plan"], ["risky_files_with_tests", "…of those, with tests planned"],
+  ["tier_on_risky_tasks", "Avg tier of tasks on risky files (1–3)"], ["files_read", "Repo files looked at (Read/Grep/Bash)"],
+  ["tasks", "Tasks"], ["cost_usd", "Cost (USD)"], ["output_tokens", "Output tokens"],
+];
+
+function report({ meta, results }) {
+  const lines = [`# GitRisk U8 experiment — ${meta.started}`, "",
+    "Question: does feeding GitRisk's historical-risk signal into the spec-driven-dev workflow change what the AI agent does?", "",
+    `- Repo: \`${meta.repo}\` at ${meta.head}; risky set = ${meta.risky} files scored high or critical (weights ${JSON.stringify(meta.weights)})`,
+    `- Model: ${meta.model} · stages: ${meta.stages.join(" → ")} · runs per arm: ${meta.runs} · tickets: ${meta.tickets.length}`,
+    "- Arms: **on** = risk.enabled on + specs/context/risk.md present; **off** = risk.enabled off, no risk file. Fresh clone per run, same prompt.",
+    "", "## Results (mean per arm)", "", "| Ticket | Metric | Off | On | Δ (on − off) |", "|---|---|---|---|---|"];
+  const mean = (rs, k) => { const v = rs.map((r) => r.metrics?.[k]).filter((x) => typeof x === "number"); return v.length ? Math.round((v.reduce((a, b) => a + b, 0) / v.length) * 100) / 100 : null; };
+  meta.tickets.forEach((t, i) => {
+    const off = results.filter((r) => r.ticket === i && r.arm === "off" && !r.metrics?.error), on = results.filter((r) => r.ticket === i && r.arm === "on" && !r.metrics?.error);
+    for (const [k, label] of METRICS) {
+      const a = mean(off, k), b = mean(on, k);
+      lines.push(`| ${i + 1}. ${t.slice(0, 40).replace(/\|/g, "/")} | ${label} | ${a ?? "—"} | ${b ?? "—"} | ${a !== null && b !== null ? Math.round((b - a) * 100) / 100 : "—"} |`);
+    }
+  });
+  const failed = results.filter((r) => r.metrics?.error || r.exit !== 0);
+  lines.push("", "## Runs", "", "| Ticket | Arm | Run | Exit | Feature folder | Error |", "|---|---|---|---|---|---|",
+    ...results.map((r) => `| ${r.ticket + 1} | ${r.arm} | ${r.run} | ${r.exit} | ${r.metrics?.feature || "—"} | ${(r.metrics?.error || "").replace(/\|/g, "/")} |`));
+  lines.push("", "## Caveats", "",
+    `- ${meta.runs} run(s) per arm is a pilot, not a significance test. Agent behaviour varies run to run; increase --runs before drawing conclusions.`,
+    "- Metrics are proxies read from the transcript and the written spec (files the agent opened, files and tests it planned, task tiers). They don't measure whether the eventual code has fewer bugs.",
+    "- The risky set comes from the same repo history the ON arm sees, so a higher \"risky files read\" in ON is expected; the interesting signal is whether that changes the plan (tests, tiers) without raising cost much.",
+    `- Failed runs: ${failed.length}. They are excluded from the means but kept in results.json.`);
+  return lines.join("\n") + "\n";
+}
+
+export async function riskEval(opts) {
+  const { repo, tickets, runs = 1, arms = ["on", "off"], timeoutMin = 20, model = "sonnet", stages = ["investigate", "create"], claude = "claude", out, pluginDir, since, weights, configText = "" } = opts;
+  if (!tickets.length) throw new Error("No tickets: pass --tickets=<file> with one ticket per line");
+  const started = new Date().toISOString().replace(/\.\d+Z$/, "Z");
+  const dir = path.join(out, `risk-eval-${started.replace(/[:]/g, "-")}`);
+  fs.mkdirSync(dir, { recursive: true });
+  const w = normWeights(weights);
+  const scored = scoreRepo(repo, { since, weights: w });
+  scored.rows.sort((a, b) => b.score - a.score);
+  const risky = new Set(scored.rows.filter((r) => r.tier === "high" || r.tier === "critical").map((r) => r.file));
+  const riskMd = riskMarkdown({ rows: scored.rows, repos: [{ name: path.basename(repo), head: scored.head, commits: scored.commits }], weights: w, since, top: 60 });
+  fs.writeFileSync(path.join(dir, "risk.md"), riskMd);
+  const meta = { started, repo, head: scored.head, risky: risky.size, weights: w, model, stages, runs, tickets };
+  const stageText = stages.map((s) => `spec-${s}`).join(", then ");
+  const results = [];
+  for (let t = 0; t < tickets.length; t++) for (let r = 1; r <= runs; r++) for (const arm of ((t + r) % 2 ? ["off", "on"] : ["on", "off"]).filter((a) => arms.includes(a))) {
+    const clone = fs.mkdtempSync(path.join(os.tmpdir(), `risk-eval-${arm}-`));
+    sh(os.tmpdir(), "git", ["clone", "-q", "--no-hardlinks", repo, clone]);
+    for (const extra of ["specs/CONTEXT.md", "specs/context"]) {
+      const src = path.join(repo, extra);
+      if (fs.existsSync(src) && !fs.existsSync(path.join(clone, extra))) fs.cpSync ? fs.cpSync(src, path.join(clone, extra), { recursive: true }) : sh(repo, "cp", ["-R", src, path.join(clone, extra)]);
+    }
+    fs.rmSync(path.join(clone, "specs/context/risk.md"), { force: true });
+    fs.writeFileSync(path.join(clone, ".spec-driven.yml"), setRiskEnabled(configText || "version: 1\nlayout: single\n", arm === "on"));
+    if (arm === "on") { fs.mkdirSync(path.join(clone, "specs/context"), { recursive: true }); fs.writeFileSync(path.join(clone, "specs/context/risk.md"), riskMd); }
+    const prompt = `Use the ticket-to-pr plugin skills. This is a non-interactive run: don't ask questions, make reasonable assumptions and record them. Ticket (plain text, no tracker): ${tickets[t]}\nRun ${stageText}. Work on the current branch; don't create branches, commit, push, or implement anything.`;
+    const res = spawnSync(claude, ["-p", "--output-format", "stream-json", "--verbose", "--model", model, "--plugin-dir", pluginDir, "--permission-mode", "acceptEdits",
+      "--allowedTools", "Read Write Edit Glob Grep Skill Bash(git:*) Bash(ls:*) Bash(cat:*) Bash(head:*) Bash(tail:*) Bash(wc:*) Bash(find:*) Bash(grep:*) Bash(node:*) Bash(npx:*) Bash(spec-driven-dev:*)"],
+      { cwd: clone, input: prompt, encoding: "utf8", maxBuffer: 512 * 1024 * 1024, timeout: timeoutMin * 60 * 1000 });
+    const transcript = res.stdout || "";
+    const tag = `t${t + 1}-${arm}-r${r}`;
+    fs.writeFileSync(path.join(dir, `${tag}.jsonl`), transcript);
+    const tracked = sh(clone, "git", ["ls-files"]).split("\n").filter((f) => f.includes("/") || f.includes("."));
+    const metrics = measure({ transcript, clone, risky, tracked });
+    if (res.status !== 0 && !metrics.error) {
+      // Say where it stopped, so a stall (usage limit, API wait) is told apart from a skill problem.
+      const events = transcript.split("\n").filter(Boolean).length;
+      const lastTool = [...transcript.matchAll(/"type":"tool_use","id":"[^"]+","name":"(\w+)"/g)].pop()?.[1] || "none";
+      metrics.error = `${res.error?.code === "ETIMEDOUT" ? `timed out after ${timeoutMin} min` : `exit ${res.status}`} · ${events} events · last tool ${lastTool} ${(res.stderr || "").slice(0, 120)}`.trim();
+    }
+    if (metrics.feature) fs.cpSync ? fs.cpSync(path.join(clone, "specs", metrics.feature), path.join(dir, tag), { recursive: true }) : sh(clone, "cp", ["-R", path.join("specs", metrics.feature), path.join(dir, tag)]);
+    results.push({ ticket: t, arm, run: r, exit: res.status, metrics });
+    fs.rmSync(clone, { recursive: true, force: true });
+    console.log(`  ${tag}: ${metrics.error ? `failed (${metrics.error.slice(0, 80)})` : `read ${metrics.risky_files_read} risky / ${metrics.files_read} files, ${metrics.risky_plan_files} risky in plan, $${metrics.cost_usd}`}`);
+  }
+  fs.writeFileSync(path.join(dir, "results.json"), JSON.stringify({ meta, results }, null, 2));
+  const md = report({ meta, results });
+  fs.writeFileSync(path.join(dir, "report.md"), md);
+  const failed = results.filter((x) => x.metrics.error).length;
+  fs.appendFileSync(path.join(out, "LOG.md"), `${fs.existsSync(path.join(out, "LOG.md")) ? "" : "# GitRisk experiment log\n\nAppend-only record of every run, including failures.\n\n"}- ${started} · ${tickets.length} ticket(s) × ${runs} run(s) × 2 arms on \`${path.basename(repo)}\` at ${scored.head}, ${model}, ${stages.join("+")} · ${results.length - failed} ok, ${failed} failed · [report](${path.basename(dir)}/report.md)\n`);
+  return { dir, report: md, results };
+}