@benjaminthomas/spec-driven-dev 1.10.0 → 1.11.0

package/README.md

@@ -46,6 +46,7 @@ Asking an AI agent to "just build it" tends to fail in predictable ways:
 | One agent working alone is slow | **`spec-implement`** runs several coder agents in parallel, each in its own copy of the repo |
 | "It compiles" gets treated as "it works" | **`spec-verify`** drives the real running app and checks every acceptance criterion, with evidence |
 | Problems slip through because nobody reviews the whole change | **`spec-review`** checks the finished branch against the spec, your conventions, and the code, and blocks shipping on real problems |
+| The agent treats a file that broke five times like any other | **GitRisk** scores files from git history (churn, bug fixes, dependents, security fixes), so risky files get a deeper look, a higher tier and targeted tests. Switch it on or off any time |
 | A new session forgets what was decided last time | **Project memory**: a small `specs/CONTEXT.md`, plus a "Resume here" block and a log in every spec, kept short so reloading them is cheap |
 | Broken code gets committed, or a PR is pushed by accident | **`spec-checkpoint`** commits only once lint, types, tests, and build all pass. **`spec-ship`** asks before it pushes |
 
@@ -246,6 +247,54 @@ lines that point to files that no longer exist. If you install
 [graphify](https://github.com/Graphify-Labs/graphify), the skills use it for cheaper code
 navigation. It's optional (`context.graph: off` turns it off), and nothing is installed for you.
 
+### GitRisk: which files have a history of breaking
+
+`spec-driven-dev risk` scores every tracked code file from git history alone, with no model and no
+tokens, and writes the top files to `specs/context/risk.md`:
+
+```
+Risk = 0.30 × Churn + 0.35 × Bug Density + 0.20 × Fan-out + 0.15 × Security      (each factor 0–100)
+```
+
+| Factor | Weight | What it measures |
+|---|---|---|
+| Churn | 30% | how often the file changes, against the repo's 90th percentile |
+| Bug Density | 35% | share of its commits that were bug fixes (`fix:` type or fix-like wording) |
+| Fan-out | 20% | how many other files import it, against the repo's 90th percentile |
+| Security | 15% | share of its commits that were security fixes (security, CVE, XSS, injection…) |
+
+Tiers: critical ≥ 75, high ≥ 50, medium ≥ 25. When `risk.enabled` is on, the skills use it:
+- `spec-investigate` digs into high and critical files in the change surface (past fix commits,
+  dependents) and lists them as **Risk Hotspots**;
+- `spec-create` raises those tasks one tier and requires a test aimed at each file's past failure
+  pattern;
+- `spec-implement`'s reviewer and `spec-review` check those tests and read the risky files line
+  by line.
+
+**Turning it on or off, no YAML needed:**
+- **In your AI tool:** say "turn GitRisk off" or "turn GitRisk on". `spec-setup` changes just that
+  setting and tells you what it means.
+- **In a terminal:** run `spec-driven-dev settings` and pick with the arrow keys. It also switches
+  run-through mode. For scripts, use `spec-driven-dev settings --risk=off`.
+- **By hand:** set `risk.enabled: on` or `off` in `.spec-driven.yml`.
+
+Off means every skill ignores risk completely.
+
+`spec-driven-dev risk --files=a.ts,b.ts` prints scores for chosen files. The weights are a starting
+hypothesis: change them under `risk.weights` in `.spec-driven.yml` once you've backtested them
+against your own past bugs.
+
+**Does it change what the agent does?** `spec-driven-dev risk-eval --tickets=tickets.md` runs each
+ticket twice, in fresh clones with risk on and off, through investigate and create on the same
+model. It then compares what the agent did:
+- risky files read and named in the investigation;
+- risky files in the plan, and whether tests were planned for them;
+- task tiers;
+- cost.
+
+Results go to `experiments/` with the transcripts, and every run, including failures, is appended to
+`experiments/LOG.md`. It needs Claude Code.
+
 ## How the workflow fits together
 
 ```
@@ -314,6 +363,9 @@ It starts from the project memory (`specs/CONTEXT.md` and only the area files th
 treats it as a lead rather than evidence, and notes where the code contradicts it. If graphify is
 installed, it uses it to map the code more cheaply.
 
+With GitRisk on, it also looks harder at high-risk files in the change surface (their past fix
+commits and dependents) and lists them as **Risk Hotspots**.
+
 **You get:** `specs/<feature>/investigation.md`, with every finding labelled **VERIFIED**,
 **INFERRED**, **ASSUMPTION**, or **UNKNOWN**, a short **Relevant Context** digest for the next
 stages, and requirements numbered R1, R2… so they can be traced through to verification and review.
@@ -335,6 +387,9 @@ to write**, acceptance criteria, the requirements it **covers**, and the few **p
 that apply to it. Every requirement must map to a task, and the spec isn't finished until it does.
 It also starts the spec's `log.md` and **Resume here** block.
 
+With GitRisk on, a task that touches a high-risk file goes up one tier and must include a test
+aimed at that file's past failures.
+
 **Then:** read it, edit anything you disagree with, and only then run `spec-implement`.
 
 ### 3. `spec-implement`: build it, batch by batch
@@ -380,6 +435,8 @@ nothing out of scope), the project's recorded conventions, and the code itself:
 security, error handling, tests, and hot-path performance. It checks each finding against the code
 before reporting it, and reads the diff rather than the whole repo.
 
+With GitRisk on, high-risk files get a line-by-line read of their error paths and callers.
+
 **You get:** `specs/<feature>/review.md`, with findings ranked blocker, should-fix, nit, or question,
 each with `file:line` and a suggested fix. Blockers stop `spec-ship` and run-through. It then asks
 whether to fix them, and fixes go through `spec-implement`'s fix loop only after you say yes. It also
@@ -443,6 +500,8 @@ specs/
     └── review.md                 ← spec-review: ranked findings; open blockers stop spec-ship
 specs/CONTEXT.md                  ← spec-setup / spec-checkpoint: project memory index (≤60 lines)
 specs/context/<area>.md           ← details per area, loaded only when needed (≤150 lines)
+specs/context/risk.md             ← spec-driven-dev risk: GitRisk scores (regenerate; don't edit)
+experiments/                      ← spec-driven-dev risk-eval: on/off reports, transcripts, LOG.md
 ```
 
 These are plain Markdown files, so you can review them in a PR, edit them, or hand them to a
@@ -475,6 +534,11 @@ Built into the skills, not left to the agent's judgment:
 
 ## FAQ
 
+**How do I turn GitRisk off (or on)?**
+Say "turn GitRisk off" in your AI tool, or run `spec-driven-dev settings` and pick from the menu.
+Off means every skill ignores risk scores. Turning it on again offers to score the files if that
+hasn't been done yet.
+
 **Do I need Jira?**
 No. Use GitHub Issues, Linear, a transcript, a document, or a sentence of plain text. Jira is just
 one of the options.
@@ -565,6 +629,10 @@ spec-driven-dev --yes                             # accept every detected defaul
 spec-driven-dev doctor                            # check .spec-driven.yml against the real repos
 spec-driven-dev status                            # list unfinished specs and each one's next step
 spec-driven-dev context --areas=billing           # print the project memory (index, or chosen areas)
+spec-driven-dev settings                          # switch GitRisk and run-through on/off from a menu
+spec-driven-dev risk                              # GitRisk: score files from git history → specs/context/risk.md
+spec-driven-dev risk-eval --tickets=tickets.md    # compare agent behaviour with the risk signal on vs off
+                                                  #   (--runs=3 --arms=on --timeout=20 --model=sonnet)
 spec-driven-dev --help                            # show all of the above
 ```
 
@@ -658,16 +726,16 @@ skips that step rather than failing.
 
 | Skill | Stage | SKILL.md lines | Words | Supporting files |
 |---|---|---:|---:|---:|
-| `spec-setup` | 0 · configure | 142 | 1,334 | 3 |
-| `spec-investigate` | 1 · understand | 354 | 3,007 | 1 |
-| `spec-create` | 2 · plan | 183 | 1,646 | 6 |
+| `spec-setup` | 0 · configure | 162 | 1,534 | 3 |
+| `spec-investigate` | 1 · understand | 370 | 3,152 | 1 |
+| `spec-create` | 2 · plan | 195 | 1,746 | 6 |
 | `spec-implement` | 3 · build | 322 | 2,683 | 3 |
 | `spec-verify` | 4 · prove | 163 | 1,557 | 1 |
-| `spec-review` | 5 · review | 131 | 1,209 | 1 |
-| `spec-checkpoint` | 6 · commit | 131 | 1,020 | 0 |
+| `spec-review` | 5 · review | 135 | 1,270 | 1 |
+| `spec-checkpoint` | 6 · commit | 133 | 1,046 | 0 |
 | `spec-ship` | 7 · PR | 230 | 1,388 | 0 |
 | `generative-seo` | standalone | 255 | 2,209 | 7 |
-| **Total** | | **1,911** | **16,053** | **22** |
+| **Total** | | **1,965** | **16,585** | **22** |
 
 - **8** skills: **1** setup + **6** workflow stages + **1** standalone
 - **4** tools supported natively (Claude Code, Codex CLI, Cursor, Antigravity), plus an MCP fallback
@@ -688,7 +756,9 @@ plugin/skills/<name>/references/ templates and prompts the skill loads when need
 plugin/                       the Claude Code plugin (manifest + skills only, no scripts or hooks)
 .agents/skills/               symlinks so Codex/Antigravity pick the skills up inside this repo
 bin/spec-driven-dev.cjs       launcher (runs on any Node, explains if it's too old)
-bin/cli.mjs                   the `spec-driven-dev` CLI: installer, setup menus, doctor, status, context
+bin/cli.mjs                   the `spec-driven-dev` CLI: installer, setup menus, doctor, status, context, risk
+bin/risk.mjs                  GitRisk scoring (churn, bug density, fan-out, security)
+bin/risk-eval.mjs             risk on/off experiment harness
 package.json                  npm package (ships bin/ and plugin/skills/)
 mcp-server/                   MCP fallback server
 CHANGELOG.md                  what changed in each version
@@ -717,7 +787,7 @@ plugin/evals/                 `claude plugin eval` cases
   1. Increase `version` in both `package.json` and `plugin/.claude-plugin/plugin.json` (the check fails if
      they differ).
   2. Add a `CHANGELOG.md` entry, then commit and push.
-  3. Tag the release and push the tag: `git tag v1.10.0 && git push origin v1.10.0`.
+  3. Tag the release and push the tag: `git tag v1.11.0 && git push origin v1.11.0`.
   4. Watch the **publish** run in the repo's Actions tab. When it's green, the new version is on
      npm. Claude Code plugin users get it from the marketplace once the commit is on `main`.
 

package/bin/cli.mjs

@@ -7,15 +7,19 @@
 //   spec-driven-dev doctor          check .spec-driven.yml against the real repos (exit 1 on problems)
 //   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  --project=new|existing  --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, "plugin", "skills");
@@ -34,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", "context"].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")) {
@@ -43,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", "project"];
-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);
 }
 
@@ -241,6 +246,7 @@ function toYaml(c) {
   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 += `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`;
 }
@@ -515,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.
@@ -577,6 +593,11 @@ function doctor() {
   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}`);
@@ -620,6 +641,103 @@ function context() {
   }
 }
 
+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);
@@ -648,11 +766,14 @@ 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, status, or context`);
+  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 };
+}

package/bin/risk.mjs

@@ -0,0 +1,137 @@
+// GitRisk: per-file historical risk from git alone (no model, no tokens).
+//   Risk = 0.30·Churn + 0.35·BugDensity + 0.20·FanOut + 0.15·Security   (each factor 0–100)
+// The weights are a hypothesis to calibrate by backtest, so .spec-driven.yml `risk.weights` overrides them.
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+export const DEFAULT_WEIGHTS = { churn: 0.3, bug_density: 0.35, fan_out: 0.2, security: 0.15 };
+export const TIERS = [[75, "critical"], [50, "high"], [25, "medium"], [0, "low"]];
+const MIN_COMMITS = 3; // shortcut: a file with 1 commit that was a fix would score 100% bug density; divide by at least 3. Replace with Bayesian smoothing if calibration shows it matters.
+
+// Classification uses the conventional-commit type when the repo uses one, and message keywords otherwise.
+const BUG = /^(fix|hotfix|bugfix|revert)(\(.+\))?!?:|\b(fix(e[sd]|ing)?|bug|hotfix|regression|broken|crash(es|ed)?|patch(ed)?|defect)\b/i;
+const SECURITY = /\b(security|cve-\d+|xss|csrf|ssrf|sqli|injection|vuln(erability)?|exploit|sanitiz(e|ation)|escap(e|ing) (html|input|output)|auth(entication|orization)? (bypass|fix)|privilege|secret(s)? (leak|exposed)|leak(ed|s)? (token|key|secret|credential)|rate.?limit|helmet|csp)\b/i;
+const SKIP = /(^|\/)(node_modules|dist|build|out|vendor|coverage|\.next|graphify-out|specs)\/|\.(md|mdx|txt|lock|log|png|jpe?g|gif|svg|ico|webp|pdf|zip|map|snap|csv)$|(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|Cargo\.lock|go\.sum|poetry\.lock|composer\.lock)$/i;
+const CODE = /\.(m?[jt]sx?|cjs|py|rb|go|rs|java|kt|php|cs|swift|scala|vue|svelte)$/i;
+
+const git = (cwd, args) => {
+  try { return execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "ignore"], maxBuffer: 512 * 1024 * 1024 }).toString(); } catch { return ""; }
+};
+export const classify = (subject) => ({ bug: BUG.test(subject), security: SECURITY.test(subject) });
+export const tierOf = (score) => TIERS.find(([min]) => score >= min)[1];
+
+// Value at the 90th percentile; "expected" in min(100, actual / expected × 100), so one outlier can't flatten everyone else.
+function p90(values) {
+  const v = values.filter((x) => x > 0).sort((a, b) => a - b);
+  return v.length ? v[Math.min(v.length - 1, Math.floor(v.length * 0.9))] : 1;
+}
+
+// Within-repo dependents: how many other files import this one. Relative JS/TS imports and Python module paths.
+// shortcut: no tsconfig path aliases or cross-repo consumers (GitRisk open question U7); add when a repo needs them.
+function fanOut(repo, files) {
+  const set = new Set(files), dependents = new Map(files.map((f) => [f, new Set()]));
+  const exts = ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", "/index.ts", "/index.tsx", "/index.js", "/index.jsx", ".py", "/__init__.py"];
+  const pyIndex = new Map(files.filter((f) => f.endsWith(".py")).map((f) => [f.replace(/\/__init__\.py$|\.py$/, "").split("/").join("."), f]));
+  for (const f of files) {
+    if (!CODE.test(f)) continue;
+    let text = "";
+    try { text = fs.readFileSync(path.join(repo, f), "utf8"); } catch { continue; }
+    if (text.length > 2e6) continue;
+    const targets = new Set();
+    for (const m of text.matchAll(/(?:from\s+|require\(\s*|import\(\s*|import\s+)["'](\.{1,2}\/[^"']+)["']/g)) {
+      const base = path.posix.normalize(path.posix.join(path.posix.dirname(f), m[1]));
+      const hit = exts.map((e) => base + e).find((c) => set.has(c));
+      if (hit) targets.add(hit);
+    }
+    if (f.endsWith(".py")) for (const m of text.matchAll(/^\s*(?:from\s+([\w.]+)\s+import|import\s+([\w.]+))/gm)) {
+      const hit = pyIndex.get(m[1] || m[2]);
+      if (hit) targets.add(hit);
+    }
+    for (const t of targets) if (t !== f) dependents.get(t).add(f);
+  }
+  return new Map([...dependents].map(([f, s]) => [f, s.size]));
+}
+
+// Score every tracked code file in one repo. `prefix` labels files in multi-repo workspaces.
+export function scoreRepo(repo, { since = "2 years ago", weights = DEFAULT_WEIGHTS, prefix = "" } = {}) {
+  const files = git(repo, ["ls-files"]).split("\n").filter((f) => f && !SKIP.test(f));
+  const tracked = new Set(files);
+  const stats = new Map(files.map((f) => [f, { commits: 0, bug: 0, security: 0 }]));
+  let commits = 0;
+  // \x1e starts each commit; the subject follows, then the changed file names.
+  for (const block of git(repo, ["log", "--no-merges", `--since=${since}`, "--name-only", "--format=%x1e%s"]).split("\x1e").slice(1)) {
+    const [subject, ...changed] = block.split("\n");
+    const c = classify(subject);
+    commits++;
+    for (const f of changed) {
+      const s = tracked.has(f) && stats.get(f);
+      if (!s) continue;
+      s.commits++;
+      if (c.bug) s.bug++;
+      if (c.security) s.security++;
+    }
+  }
+  const fan = fanOut(repo, files);
+  const expChurn = p90([...stats.values()].map((s) => s.commits)), expFan = p90([...fan.values()]);
+  const rows = files.map((f) => {
+    const s = stats.get(f), denom = Math.max(s.commits, MIN_COMMITS);
+    const factors = {
+      churn: Math.min(100, (s.commits / expChurn) * 100),
+      bug_density: s.commits ? (s.bug / denom) * 100 : 0,
+      fan_out: Math.min(100, ((fan.get(f) || 0) / expFan) * 100),
+      security: s.commits ? (s.security / denom) * 100 : 0,
+    };
+    const score = Object.keys(DEFAULT_WEIGHTS).reduce((t, k) => t + (Number(weights[k]) || 0) * factors[k], 0);
+    const r = (x) => Math.round(x * 10) / 10;
+    return { file: prefix ? `${prefix}/${f}` : f, score: r(score), tier: tierOf(score), commits: s.commits, bug_fixes: s.bug, security_fixes: s.security, dependents: fan.get(f) || 0,
+      factors: { churn: r(factors.churn), bug_density: r(factors.bug_density), fan_out: r(factors.fan_out), security: r(factors.security) } };
+  });
+  return { commits, head: git(repo, ["rev-parse", "--short", "HEAD"]).trim(), rows };
+}
+
+export function normWeights(w) {
+  const out = { ...DEFAULT_WEIGHTS };
+  for (const k of Object.keys(DEFAULT_WEIGHTS)) if (w && w[k] !== undefined && w[k] !== "") out[k] = Number(w[k]);
+  return out;
+}
+export function weightProblems(w) {
+  const p = [];
+  for (const [k, v] of Object.entries(w || {})) {
+    if (!(k in DEFAULT_WEIGHTS)) p.push(`risk.weights.${k}: unknown factor (use ${Object.keys(DEFAULT_WEIGHTS).join(", ")})`);
+    else if (!(Number(v) >= 0)) p.push(`risk.weights.${k} "${v}" must be a number ≥ 0`);
+  }
+  const sum = Object.values(normWeights(w)).reduce((a, b) => a + b, 0);
+  if (Math.abs(sum - 1) > 0.001) p.push(`risk.weights add up to ${Math.round(sum * 1000) / 1000}, not 1`);
+  return p;
+}
+
+// The area file skills read: top N files, within the 150-line area-file limit.
+export function riskMarkdown({ rows, repos, weights, since, top }) {
+  const pct = (x) => `${Math.round(x * 100)}%`;
+  const w = weights;
+  const shown = rows.filter((r) => r.score > 0).slice(0, Math.min(top, 120));
+  const lines = [
+    "# Risk",
+    "<!-- Generated by `spec-driven-dev risk`. Don't edit by hand: re-run it. Skills read this only when risk.enabled is on. -->",
+    `Scored ${repos.map((r) => `${r.name} at ${r.head} (${r.commits} commits)`).join(", ")} · since ${since} · ${new Date().toISOString().slice(0, 10)}`,
+    "",
+    `Risk = ${w.churn} × Churn + ${w.bug_density} × Bug Density + ${w.fan_out} × Fan-out + ${w.security} × Security (each 0–100; weights ${pct(w.churn)} / ${pct(w.bug_density)} / ${pct(w.fan_out)} / ${pct(w.security)}).`,
+    "Tiers: critical ≥ 75 · high ≥ 50 · medium ≥ 25. A historical signal, not proof of a bug.",
+    "",
+    "| File | Score | Tier | Churn | Bug density | Fan-out | Security | Commits (fixes / security) |",
+    "|---|---|---|---|---|---|---|---|",
+    ...shown.map((r) => `| \`${r.file}\` | ${r.score} | ${r.tier} | ${r.factors.churn} | ${r.factors.bug_density} | ${r.factors.fan_out} | ${r.factors.security} | ${r.commits} (${r.bug_fixes} / ${r.security_fixes}) |`),
+  ];
+  if (rows.length > shown.length) lines.push("", `${rows.length - shown.length} more files not shown. \`spec-driven-dev risk --files=a,b\` prints any file's score.`);
+  return lines.join("\n") + "\n";
+}
+
+// Change one `block: key: value` line in .spec-driven.yml text, keeping every comment and other line as is.
+export function setConfigValue(text, blockName, key, value) {
+  const block = text.match(new RegExp(`^${blockName}:.*\\n(?:(?:[ \\t]+.*|[ \\t]*)\\n)*`, "m"));
+  const line = new RegExp(`^([ \\t]+${key}:[ \\t]*)[^\\s#]+`, "m");
+  if (!block) return `${text.replace(/\n*$/, "\n")}${blockName}:\n  ${key}: ${value}\n`;
+  const body = line.test(block[0]) ? block[0].replace(line, `$1${value}`) : block[0].replace(new RegExp(`^${blockName}:.*\\n`), `$&  ${key}: ${value}\n`);
+  return text.replace(block[0], body);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benjaminthomas/spec-driven-dev",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Spec-driven AI development workflow (investigate → spec → implement → verify → review → ship) as Agent Skills for Claude Code, Cursor, Codex CLI and Antigravity.",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "bin",
-    "plugin/skills"
+    "plugin/skills",
+    "plugin/.claude-plugin"
   ],
   "scripts": {
     "test": "python3 scripts/check.py && node scripts/test-cli.mjs"

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "ticket-to-pr",
+  "version": "1.11.0",
+  "description": "Parallel-batch spec-driven feature workflow (spec-setup, spec-investigate, spec-create, spec-implement, spec-verify, spec-review, spec-checkpoint, spec-ship) plus a portable SEO/GEO operations skill (generative-seo) for any codebase.",
+  "author": {
+    "name": "Benjamin Thomas",
+    "url": "https://github.com/benjaminthomas"
+  },
+  "keywords": [
+    "spec-driven-development",
+    "feature-workflow",
+    "parallel-agents",
+    "seo",
+    "geo",
+    "productivity"
+  ],
+  "homepage": "https://github.com/benjaminthomas/spec-driven-dev",
+  "repository": "https://github.com/benjaminthomas/spec-driven-dev",
+  "icon": ".claude-plugin/icon.png"
+}

package/plugin/skills/spec-checkpoint/SKILL.md

@@ -67,7 +67,9 @@ Skip this step unless the changes belong to a spec (`{specs_dir}/{feature}/` exi
      references/context-template.md inside the installed `spec-setup` skill folder (not this repo): dated, with a source, added at the end, within the size
      limits, superseded lines moved to `context/archive.md`.
    - Show the context changes in the report so the user can correct them.
-3. No CONTEXT.md? Skip the distilling and suggest running `spec-setup` to create one.
+3. If `risk.enabled` is on and the CLI is available, re-run `spec-driven-dev risk` so the scores
+   include this work. It's git-only, so it costs no tokens.
+4. No CONTEXT.md? Skip the distilling and suggest running `spec-setup` to create one.
 
 ### Step 3: Stage Everything
 

package/plugin/skills/spec-create/SKILL.md

@@ -45,6 +45,18 @@ the answers to `.spec-driven.yml` (keys: `layout`, `repos`, `tracker`, `git`, `c
 - **Start the memory.** Create or extend `log.md` (`references/log-template.md`) and fill the
   README's **Resume here** block.
 
+## Risk signal (GitRisk)
+
+Same rule as `spec-investigate`: use it only when `risk.enabled` is on (or absent) and
+`{specs_dir}/context/risk.md` exists, and ignore risk completely when it's `off`. For each task that
+creates or modifies a **high** or **critical** file (from the investigation's **Risk Hotspots**, or
+`spec-driven-dev risk --files=…`):
+
+- **Raise its tier by one** (light → standard → deep), and say why in Complexity's Signals.
+- Fill the task's **Risk** section: the file, its score, and the past failure pattern.
+- Its **Tests** must include at least one test aimed at that past failure pattern, not just the new
+  behaviour.
+
 ## When to Use
 
 - After a planning conversation where requirements and technical details have been discussed

package/plugin/skills/spec-create/references/task-template.md

@@ -35,6 +35,12 @@ pending
 
 **Context from dependencies:** {Prose summary of what the dependency tasks produce that this task needs. For example: "task-01-setup-database.md creates the PostgreSQL schema with users and sessions tables. This task builds the API routes that query those tables." This is what makes each file self-contained — the agent does not need to read other task files to understand its inputs.}
 
+## Risk
+
+{Only when the task touches a high/critical file and risk.enabled is on; otherwise write "None".}
+
+- `path/to/file.ts`: {score} {tier}. Past failures: {what the fix commits show keeps breaking}. Test: {the test in Tests aimed at it}
+
 ## Project Context
 
 {Only the 3–5 lines from the project context (CONTEXT.md / context/<area>.md, via the investigation's Relevant Context) that apply to THIS task: conventions, pitfalls, off-limits areas. The coder never reads the context files itself. Write "None" if nothing applies.}

package/plugin/skills/spec-implement/references/review-prompt-template.md

@@ -25,7 +25,8 @@ You are reviewing the combined output of Batch {batch_number} of a feature imple
    - No duplicate or conflicting definitions
    - Shared state (env vars, config) is consistent
 4. **Code Quality**: Check for security issues, performance problems, and adherence to project conventions.
-5. **Scope**: Verify each task stayed within its defined scope (Files to Create/Modify). Flag any unexpected file changes.
+5. **Risk**: for every task with a filled **Risk** section, check the code handles the past failure pattern it names, and that the test aimed at it exists and would fail without the fix.
+6. **Scope**: Verify each task stayed within its defined scope (Files to Create/Modify). Flag any unexpected file changes.
 
 ## Verdict
 

package/plugin/skills/spec-investigate/SKILL.md

@@ -65,6 +65,22 @@ Cheap sources first, code second:
 
 No CONTEXT.md? Investigate as usual, and suggest running `spec-setup` afterwards to create one.
 
+## Risk signal (GitRisk)
+
+Use it only when `.spec-driven.yml` has `risk.enabled: on`, or has no `risk:` block, **and**
+`{specs_dir}/context/risk.md` exists. If `risk.enabled: off`, ignore risk entirely: don't read the
+file, compute scores, or mention risk. That keeps on/off comparisons (`spec-driven-dev risk-eval`)
+clean.
+
+1. Once you know the change surface, look up its files: `spec-driven-dev risk --files=a,b` (or
+   `npx -y @benjaminthomas/spec-driven-dev risk --files=…`), or find them in `risk.md`. Without the
+   CLI, approximate a file's history with `git log --since="2 years ago" --format=%s -- <file>`.
+2. For each **high** or **critical** file in the surface, look harder: read its last ~10 commit
+   subjects and the diffs of its last 1–2 fix commits, and check its dependents. Write what keeps
+   breaking there in the report's **Risk Hotspots** section.
+3. A score is a reason to look harder, never evidence. Hotspot findings still need their
+   VERIFIED / INFERRED labels.
+
 ## Invocation
 
 ```

package/plugin/skills/spec-investigate/references/report-template.md

@@ -22,6 +22,11 @@ Copy this structure into `specs/{feature-slug}/investigation.md`.
 - Conventions / decisions / pitfalls that apply: (one line each, with the source)
 - Context corrections: (where the code contradicts CONTEXT.md, with evidence; or "none")
 
+## Risk Hotspots
+<!-- Only when risk.enabled is on. One row per high/critical file in the change surface; else "none" or omit. -->
+| File | Score / tier | What has broken here before (from fix commits) | What to watch in this change |
+|---|---|---|---|
+
 ## Business Context
 ## Problem Statement
 ## Expected Behaviour

package/plugin/skills/spec-review/SKILL.md

@@ -74,7 +74,11 @@ review on a weaker model than the code was written with misses things.
 3. **The code.** Correctness (logic, edge cases, error paths, races), security (injection, authz,
    secrets, unsafe input), data safety (migrations, deletes, irreversible writes), tests (behaviour
    without a test, tests weakened, skipped or deleted), and performance on hot paths only.
-4. **Run the checks.** Run `commands.lint`, `typecheck`, and `test` once if verify didn't just run
+   **Risk.** When `risk.enabled` is on and `{specs_dir}/context/risk.md` exists, look up the changed
+   files (`spec-driven-dev risk --files=…`). Give **high** and **critical** files a line-by-line read
+   of their error paths and callers, check that the tests target their past failure patterns, and
+   put the score in any finding on them. When risk is `off`, skip this and don't mention it.
+4. **Run the checks.**4. **Run the checks.** Run `commands.lint`, `typecheck`, and `test` once if verify didn't just run
    them on this exact commit. A failing check is a blocker.
 
 **Verify every finding before reporting it.** Re-read the code around it and ask "what concrete

package/plugin/skills/spec-setup/SKILL.md

@@ -8,7 +8,7 @@ description: >
   plus one round of questions, for a new one the intended stack and conventions, saved to a small
   specs/CONTEXT.md that later skills load cheaply. Use when the user says "set up spec-driven",
   "configure the pipeline", "spec-setup", "audit this repo", "refresh the project context",
-  "change our branch rules", or when any other spec-* skill finds no .spec-driven.yml or no
+  "change our branch rules", "turn GitRisk on/off", "turn on run-through", or when any other spec-* skill finds no .spec-driven.yml or no
   CONTEXT.md. Detects everything it can first and only asks about what is ambiguous. Writes config
   and context files only — never changes code, branches, or commits.
 license: MIT
@@ -118,13 +118,33 @@ Skip if `{specs_dir}/CONTEXT.md` already exists (offer a refresh instead, see `r
    intended stack and conventions for a new one. One round of questions, no more.
 2. Write `{specs_dir}/CONTEXT.md` (and any area files) using `references/context-template.md`.
    Keep the index to 60 lines and area files to 150.
-3. **Offer, don't do:** ask whether to add this one line to `CLAUDE.md` / `AGENTS.md` (whichever
+3. **Risk scores.** For an existing project, run `spec-driven-dev risk` (or
+   `npx -y @benjaminthomas/spec-driven-dev risk`) to write `{specs_dir}/context/risk.md`. It uses
+   git only, no model. Skip it for a new project with no history. Mention the hotspot count in the
+   report. Set `risk.enabled: off` only if the user doesn't want it.
+4. **Offer, don't do:** ask whether to add this one line to `CLAUDE.md` / `AGENTS.md` (whichever
    the project uses), so hosts reload the pointer after compaction and in every new session:
    `For spec work, read specs/CONTEXT.md first, then the "Resume here" block of any unfinished spec.`
    Add it only on a yes.
-4. Re-run `npx -y @benjaminthomas/spec-driven-dev doctor` if available. It checks the size limits
+5. Re-run `npx -y @benjaminthomas/spec-driven-dev doctor` if available. It checks the size limits
    and flags context lines that point to files which no longer exist.
 
+## Quick switches (plain words, no YAML)
+
+When the user asks to switch a feature on or off, change only that one line of `.spec-driven.yml`,
+keep every other line and comment, and confirm in one sentence. Don't re-run discovery.
+
+| They say | Set |
+|---|---|
+| "turn GitRisk off", "stop using risk scores", "ignore risky files" | `risk.enabled: off` |
+| "turn GitRisk on", "use the risk scores" | `risk.enabled: on`, then run `spec-driven-dev risk` if `{specs_dir}/context/risk.md` doesn't exist yet |
+| "run straight through after I approve", "fewer stops" | `pipeline.after_approval: run-through` |
+| "stop after each stage" | `pipeline.after_approval: stop` |
+
+Reply with what changed and what it means, for example: "GitRisk is now off. Investigations, plans
+and reviews will ignore risk scores until you turn it back on." People who prefer a menu can run
+`spec-driven-dev settings` in a terminal.
+
 ## Updating
 
 Re-running `spec-setup` with an existing config: load it, re-detect, and show only what changed or

package/plugin/skills/spec-setup/references/config-template.yml

@@ -75,6 +75,18 @@ effort:
   deep: high
   escalate: xhigh
 
+# GitRisk: historical risk per file from git alone (`spec-driven-dev risk` writes {specs_dir}/context/risk.md).
+# Risk = churn × 0.30 + bug_density × 0.35 + fan_out × 0.20 + security × 0.15 (each factor 0–100).
+# The weights are a starting hypothesis; calibrate them against your own past bugs.
+risk:
+  enabled: on                   # on | off — off makes every skill ignore risk (used by risk-eval's A/B)
+  since: "2 years ago"          # how much history to score
+  weights:
+    churn: 0.30                 # how often the file changes, vs the repo's 90th percentile
+    bug_density: 0.35           # share of its commits that were bug fixes
+    fan_out: 0.20               # how many other files import it, vs the repo's 90th percentile
+    security: 0.15              # share of its commits that were security fixes
+
 pipeline:
   # stop        — every stage waits for you (default)
   # run-through — after you approve a spec: implement → verify → review → checkpoint in one go,