@benjaminthomas/spec-driven-dev 1.11.0 → 1.11.1

package/README.md

@@ -263,7 +263,22 @@ Risk = 0.30 × Churn + 0.35 × Bug Density + 0.20 × Fan-out + 0.15 × Security
 | 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:
+Tiers: critical ≥ 75, high ≥ 50, medium ≥ 25. Files added in the last 90 days with fewer than 3
+commits, or not committed yet, are labelled **new** instead of being scored, because too little history isn't the same as
+safe. Each new file shows the riskiest file it imports or is imported by, and inherits that file's
+care when it's high or critical.
+
+**When it updates:** setup scores the whole history once. After that it re-scores at every batch
+commit in `spec-implement` and at `spec-checkpoint`. Each run takes under a second and uses no model,
+so later batches see the new files and the extra fan-out they add. Lookups for the files a ticket
+touches (`--files=`) always read the live history. Commits made outside the pipeline are picked up
+at the next run. It doesn't hook into every commit.
+
+`risk.md` is regenerated on every run, so the first run adds it to `.gitignore`, the way you'd ignore
+a build output. Committing it would cause merge conflicts between branches. `doctor` flags it if
+it's committed.
+
+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
@@ -726,16 +741,16 @@ skips that step rather than failing.
 
 | Skill | Stage | SKILL.md lines | Words | Supporting files |
 |---|---|---:|---:|---:|
-| `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-setup` | 0 · configure | 162 | 1,545 | 3 |
+| `spec-investigate` | 1 · understand | 373 | 3,211 | 1 |
+| `spec-create` | 2 · plan | 198 | 1,782 | 6 |
+| `spec-implement` | 3 · build | 327 | 2,753 | 3 |
 | `spec-verify` | 4 · prove | 163 | 1,557 | 1 |
-| `spec-review` | 5 · review | 135 | 1,270 | 1 |
-| `spec-checkpoint` | 6 · commit | 133 | 1,046 | 0 |
+| `spec-review` | 5 · review | 137 | 1,294 | 1 |
+| `spec-checkpoint` | 6 · commit | 140 | 1,144 | 0 |
 | `spec-ship` | 7 · PR | 230 | 1,388 | 0 |
 | `generative-seo` | standalone | 255 | 2,209 | 7 |
-| **Total** | | **1,965** | **16,585** | **22** |
+| **Total** | | **1,985** | **16,883** | **22** |
 
 - **8** skills: **1** setup + **6** workflow stages + **1** standalone
 - **4** tools supported natively (Claude Code, Codex CLI, Cursor, Antigravity), plus an MCP fallback
@@ -787,7 +802,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.11.0 && git push origin v1.11.0`.
+  3. Tag the release and push the tag: `git tag v1.11.1 && git push origin v1.11.1`.
   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

@@ -593,6 +593,9 @@ 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);
+  const rmd = path.join(specs, "context", "risk.md"), rtop = run("git", ["rev-parse", "--show-toplevel"], root);
+  if (rtop && fs.existsSync(rmd) && run("git", ["ls-files", path.relative(path.resolve(rtop), real(rmd))], rtop))
+    problems.push(`${c.specs_dir || "specs"}/context/risk.md is committed to git. It's regenerated on every run, so it causes merge conflicts. Run: git rm --cached ${path.relative(path.resolve(rtop), real(rmd))}  (spec-driven-dev risk adds it to .gitignore)`);
   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));
@@ -641,6 +644,19 @@ function context() {
   }
 }
 
+// risk.md is regenerated on every run (it carries a date), so committing it means noisy diffs and merge
+// conflicts between branches. Keep it out of git like a build output; anyone can recreate it in a second.
+function ignoreGenerated(file) {
+  const top = run("git", ["rev-parse", "--show-toplevel"], path.dirname(file));
+  if (!top) return; // e.g. a multi-repo workspace folder that isn't a repo
+  const rel = path.relative(path.resolve(top), real(file)).split(path.sep).join("/");
+  if (rel.startsWith("..") || run("git", ["check-ignore", "--no-index", rel], top)) return;
+  const gi = path.join(top, ".gitignore");
+  const text = fs.existsSync(gi) ? fs.readFileSync(gi, "utf8") : "";
+  fs.writeFileSync(gi, `${text}${text && !text.endsWith("\n") ? "\n" : ""}# GitRisk scores, regenerated by spec-driven-dev risk\n${rel}\n`);
+  console.log(`  Added ${rel} to .gitignore (it's regenerated on every run, so it shouldn't be committed).`);
+}
+
 function loadConfig() {
   const file = findConfig(DIR);
   return { file, root: file ? path.dirname(file) : gitTop(DIR), c: file ? parseYaml(fs.readFileSync(file, "utf8")) : {} };
@@ -660,7 +676,9 @@ function risk() {
     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})`);
+    else for (const h of hits) console.log(h.score === null ? `${h.file}: not scored (not a code file, or doesn't exist)`
+      : h.tier === "new" ? `${h.file}: new${h.committed ? "" : ", not committed yet"} — too little history to score.${h.near ? ` Connects to ${h.near.file} (${h.near.score} ${h.near.tier})${["high", "critical"].includes(h.near.tier) ? ": treat it as " + h.near.tier : ""}.` : " Give it standard care."}`
+      : `${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; }
@@ -668,10 +686,11 @@ function risk() {
   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 }));
+  ignoreGenerated(out);
   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}`);
+  console.log(`  ${count("critical")} critical · ${count("high")} high · ${count("medium")} medium · ${count("new")} new. Top 5:`);
+  for (const r of rows.filter((x) => x.tier !== "new").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.");
 }
 

package/bin/risk.mjs

@@ -7,12 +7,13 @@ 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 NEW_DAYS = 90; // a file added within this many days with fewer than MIN_COMMITS commits (or not committed yet) has too little history to score fairly
 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 SKIP = /(^|\/)(node_modules|dist|build|out|vendor|coverage|\.next|graphify-out|specs|experiments)\/|(^|\/)(\.spec-driven\.yml|\.gitignore|\.gitattributes|\.gitmodules)$|\.(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) => {
@@ -50,13 +51,25 @@ function fanOut(repo, files) {
     }
     for (const t of targets) if (t !== f) dependents.get(t).add(f);
   }
-  return new Map([...dependents].map(([f, s]) => [f, s.size]));
+  const imports = new Map(files.map((f) => [f, new Set()]));
+  for (const [t, srcs] of dependents) for (const f of srcs) imports.get(f).add(t);
+  return { counts: new Map([...dependents].map(([f, s]) => [f, s.size])), dependents, imports };
 }
 
-// Score every tracked code file in one repo. `prefix` labels files in multi-repo workspaces.
+// Score every code file in one repo, including new files not committed yet. `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 committed = git(repo, ["ls-files"]).split("\n").filter((f) => f && !SKIP.test(f));
+  const untracked = git(repo, ["ls-files", "--others", "--exclude-standard"]).split("\n").filter((f) => f && !SKIP.test(f));
+  const files = [...committed, ...untracked];
   const tracked = new Set(files);
+  // When each file was first added (all history, not just `since`), to tell new files from quiet old ones.
+  const added = new Map();
+  for (const block of git(repo, ["log", "--diff-filter=A", "--format=%x1e%ct", "--name-only"]).split("\x1e").slice(1)) {
+    const [ts, ...names] = block.split("\n");
+    for (const f of names) if (f) added.set(f, Number(ts)); // log is newest first, so the last write is the first add
+  }
+  const cutoff = Date.now() / 1000 - NEW_DAYS * 86400;
+  const recent = (f) => !added.has(f) || added.get(f) >= cutoff;
   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.
@@ -72,7 +85,9 @@ export function scoreRepo(repo, { since = "2 years ago", weights = DEFAULT_WEIGH
       if (c.security) s.security++;
     }
   }
-  const fan = fanOut(repo, files);
+  // "New" = recent AND too few commits to judge. A young file that's already been fixed a lot has real history.
+  const isNew = new Set(files.filter((f) => untracked.includes(f) || (recent(f) && stats.get(f).commits < MIN_COMMITS)));
+  const graph = fanOut(repo, files), fan = graph.counts;
   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);
@@ -84,9 +99,20 @@ export function scoreRepo(repo, { since = "2 years ago", weights = DEFAULT_WEIGH
     };
     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,
+    return { file: prefix ? `${prefix}/${f}` : f, path: 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) } };
   });
+  // New files: too little history for a fair score, so label them "new" and show the riskiest established
+  // file they import or are imported by. New code next to a hotspot deserves the hotspot's care.
+  const byPath = new Map(rows.map((x) => [x.path, x]));
+  for (const x of rows) {
+    if (!isNew.has(x.path)) continue;
+    x.tier = "new";
+    x.committed = !untracked.includes(x.path);
+    const near = [...graph.imports.get(x.path), ...graph.dependents.get(x.path)].map((n) => byPath.get(n)).filter((n) => n && !isNew.has(n.path)).sort((a, b) => b.score - a.score)[0];
+    if (near) x.near = { file: near.file, score: near.score, tier: near.tier };
+  }
+  for (const x of rows) delete x.path;
   return { commits, head: git(repo, ["rev-parse", "--short", "HEAD"]).trim(), rows };
 }
 
@@ -110,7 +136,9 @@ export function weightProblems(w) {
 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 fresh = rows.filter((r) => r.tier === "new");
+  const freshShown = fresh.filter((r) => r.near).sort((a, b) => b.near.score - a.near.score).slice(0, 15);
+  const shown = rows.filter((r) => r.score > 0 && r.tier !== "new").slice(0, Math.min(top, 120 - freshShown.length));
   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. -->",
@@ -123,7 +151,11 @@ export function riskMarkdown({ rows, repos, weights, since, top }) {
     "|---|---|---|---|---|---|---|---|",
     ...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.`);
+  if (fresh.length) {
+    lines.push("", `## New files (${fresh.length})`, "", `Added in the last ${NEW_DAYS} days with fewer than ${MIN_COMMITS} commits, or not committed yet, so there's too little history to score. Give them standard care, and the care of the riskiest file they connect to when that file is high or critical.`);
+    if (freshShown.length) lines.push("", "| New file | Connects to | Its score / tier |", "|---|---|---|", ...freshShown.map((r) => `| \`${r.file}\` | \`${r.near.file}\` | ${r.near.score} ${r.near.tier} |`));
+  }
+  if (rows.length > shown.length + freshShown.length) lines.push("", `${rows.length - shown.length - freshShown.length} more files not shown. \`spec-driven-dev risk --files=a,b\` prints any file's score.`);
   return lines.join("\n") + "\n";
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benjaminthomas/spec-driven-dev",
-  "version": "1.11.0",
+  "version": "1.11.1",
   "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": {

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

@@ -1,6 +1,6 @@
 {
   "name": "ticket-to-pr",
-  "version": "1.11.0",
+  "version": "1.11.1",
   "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",

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

@@ -66,9 +66,16 @@ Skip this step unless the changes belong to a spec (`{specs_dir}/{feature}/` exi
      one line to CONTEXT.md's **Specs** list. Follow the rules in
      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`.
+   - **New areas and files.** Compare `git diff --name-status --diff-filter=A <base>...HEAD` with
+     CONTEXT.md's **Areas** table. Add a row for any new folder that holds a real area (not a
+     single helper), and one line per important new file (an entry point, a shared module others
+     will import) to its area file. Stay within the size limits.
+   - **Areas that grew.** If the feature changed what an existing area does (new commands,
+     responsibilities, or sub-folders), update that row's "What it does" in **Areas** so the
+     map stays true. Keep it to one line.
    - Show the context changes in the report so the user can correct them.
 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.
+   include this work. It's git-only, so it costs no tokens. `risk.md` is gitignored: don't stage it.
 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

@@ -57,6 +57,9 @@ creates or modifies a **high** or **critical** file (from the investigation's **
 - Its **Tests** must include at least one test aimed at that past failure pattern, not just the new
   behaviour.
 
+A task that creates a **new** file next to a high or critical one (it imports it, or the hotspot will
+import it) gets the same treatment, because the new code inherits that file's failure modes.
+
 ## When to Use
 
 - After a planning conversation where requirements and technical details have been discussed

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

@@ -225,6 +225,11 @@ After the batch passes review (or the user chooses to proceed):
 2. **Update README.md**: change `- [ ]` to `- [x]` for each completed task
 3. **Update memory**: append a log entry (what this batch decided or changed from the spec) and
    overwrite the README's **Resume here** (`Stage: batch {N}/{total} done`, `Next: …`).
+   **Refresh risk** after the commit when `risk.enabled` is on and the CLI is available: run
+   `spec-driven-dev risk`. It takes well under a second with no model. New files from this batch
+   show as `new`, and files they import gain fan-out, so later batches and the reviewers see
+   current scores, not the ones from before this feature started. `risk.md` is gitignored (the
+   command adds it), so never stage or commit it.
 4. **Commit the batch**:
    ```
    git add -A

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

@@ -25,7 +25,7 @@ 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. **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.
+5. **Risk**: new files show as tier `new`, which means unproven, not safe; review them at standard care, or at the tier of the hotspot they connect to. 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

@@ -80,6 +80,9 @@ clean.
    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.
+4. **New files** (added in the last 90 days with fewer than 3 commits, or not committed yet) show as tier `new`: too little
+   history to score, which is not the same as safe. Give them standard care. When one connects to a
+   high or critical file (`Connects to …` in the lookup), treat it at that file's tier.
 
 ## Invocation
 

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

@@ -77,7 +77,9 @@ review on a weaker model than the code was written with misses things.
    **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.
+   put the score in any finding on them. New files show as tier `new`: review them at standard care,
+   or at the tier of the high or critical file they connect to. 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.
 

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

@@ -120,7 +120,7 @@ Skip if `{specs_dir}/CONTEXT.md` already exists (offer a refresh instead, see `r
    Keep the index to 60 lines and area files to 150.
 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
+   git only, no model, and adds `risk.md` to `.gitignore` because it's regenerated on every run. 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: