doctrina-cli 0.11.0 → 0.12.0

package/src/commands/coverage.js

@@ -1,8 +1,10 @@
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { exists, isDir, isFile, read, relPath } from "../lib/fs-ops.js";
-import { flagBool } from "../lib/args.js";
+import { specHeader } from "../lib/scan.js";
+import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 
 // Traceability report: how many acceptance criteria cite an artifact or
@@ -28,7 +30,21 @@ export async function run(_positional, flags) {
   const strict = flagBool(flags, "strict", false);
   const json = flagBool(flags, "json", false);
 
-  const reports = collect(projectRoot);
+  // --only <cap,cap>: scope the report/gate to specific capabilities — the
+  // hook `doctrina close` uses so one deliberately deferred spec elsewhere in
+  // the tree cannot block closing a change that never touched it.
+  const onlyRaw = flagString(flags, "only");
+  const only = onlyRaw ? new Set(onlyRaw.split(",").map((s) => s.trim()).filter(Boolean)) : null;
+
+  const reports = collect(projectRoot, { only });
+
+  // --run: execute the cited evidence instead of only checking it exists —
+  // promotes "the file is on disk" to "the proof passes". The runner is
+  // project-declared in .doctrina/verify.json ("evidence_runner": a command
+  // template with a {file} placeholder); the CLI never guesses a test runner.
+  if (flagBool(flags, "run", false)) {
+    return runEvidence(projectRoot, reports, strict);
+  }
 
   if (reports.length === 0) {
     if (json) {
@@ -43,19 +59,22 @@ export async function run(_positional, flags) {
   let totalCovered = 0;
   let totalDangling = 0;
   let totalConditional = 0;
+  let totalDeferred = 0;
   for (const rep of reports) {
     totalCriteria += rep.rows.length;
     totalCovered += rep.rows.filter((r) => r.kind === "covered").length;
     totalDangling += rep.rows.filter((r) => r.kind === "dangling").length;
     totalConditional += rep.rows.filter((r) => r.kind === "conditional").length;
+    totalDeferred += rep.rows.filter((r) => r.kind === "deferred").length;
   }
   const jsonPct = totalCriteria === 0 ? 100 : Math.round((totalCovered / totalCriteria) * 100);
-  const jsonClean = totalCovered === totalCriteria && totalDangling === 0 && totalConditional === 0;
+  // Deferred criteria are visible but never gate: declared debt ≠ hidden debt.
+  const jsonClean = totalCovered + totalDeferred === totalCriteria && totalDangling === 0 && totalConditional === 0;
 
   if (json) {
     console.log(JSON.stringify({
-      specs: reports.map((rep) => ({ capability: rep.cap, criteria: rep.rows })),
-      summary: { criteria: totalCriteria, covered: totalCovered, dangling: totalDangling, conditional: totalConditional, pct: jsonPct },
+      specs: reports.map((rep) => ({ capability: rep.cap, deferred: rep.deferred, criteria: rep.rows })),
+      summary: { criteria: totalCriteria, covered: totalCovered, dangling: totalDangling, conditional: totalConditional, deferred: totalDeferred, pct: jsonPct },
     }, null, 2));
     return jsonClean ? 0 : strict ? 1 : 0;
   }
@@ -67,15 +86,19 @@ export async function run(_positional, flags) {
     const covered = rep.rows.filter((r) => r.kind === "covered").length;
     const dangling = rep.rows.filter((r) => r.kind === "dangling").length;
     const conditional = rep.rows.filter((r) => r.kind === "conditional").length;
+    const deferredN = rep.rows.filter((r) => r.kind === "deferred").length;
 
     const notes = [];
     if (conditional > 0) notes.push(c.yellow(`${conditional} conditional`));
     if (dangling > 0) notes.push(c.yellow(`${dangling} dangling`));
+    if (deferredN > 0) notes.push(c.gray(`${deferredN} deferred`));
     const note = notes.length > 0 ? `  (${notes.join(", ")})` : "";
     console.log(`  ${c.cyan(rep.cap.padEnd(20))} ${covered}/${rep.rows.length} criteria${note}`);
     for (const r of rep.rows) {
       if (r.kind === "covered") continue;
-      if (r.kind === "bare") {
+      if (r.kind === "deferred") {
+        console.log(`    ${c.gray("○")} #${r.n}  deferred — spec declares "Implementation: planned — <why>" (visible, not gated)`);
+      } else if (r.kind === "bare") {
         console.log(`    ${c.red("✗")} #${r.n}  no evidence linked — cite the file/test that proves it in backticks`);
       } else if (r.kind === "conditional") {
         console.log(`    ${c.yellow("!")} #${r.n}  evidence is a skipped test (proves nothing): ${r.skipped.map((m) => `\`${m}\``).join(", ")}`);
@@ -88,64 +111,141 @@ export async function run(_positional, flags) {
   const pct = totalCriteria === 0 ? 100 : Math.round((totalCovered / totalCriteria) * 100);
   console.log("");
   const summary = `${totalCovered} of ${totalCriteria} acceptance criteria across ${reports.length} spec${reports.length === 1 ? "" : "s"} have linked evidence (${pct}%)`;
-  const clean = totalCovered === totalCriteria && totalDangling === 0 && totalConditional === 0;
-  if (clean) {
-    console.log(c.green("ok") + " " + summary);
-    return 0;
-  }
+  const clean = totalCovered + totalDeferred === totalCriteria && totalDangling === 0 && totalConditional === 0;
   const extras = [];
   if (totalConditional > 0) extras.push(`${totalConditional} conditional`);
   if (totalDangling > 0) extras.push(`${totalDangling} dangling`);
+  if (totalDeferred > 0) extras.push(`${totalDeferred} deferred (not gated)`);
   const extraSummary = extras.length > 0 ? `, ${extras.join(", ")}` : "";
+  if (clean) {
+    console.log(c.green("ok") + " " + summary + extraSummary);
+    return 0;
+  }
   console.log((strict ? c.red("fail") : c.yellow("gap")) + " " + summary + extraSummary);
   // A report by default (exit 0); a gate under --strict (exit 1 for CI). A
   // conditional criterion fails the gate too: a skipped test is not proof.
+  // Deferred criteria never fail: the deferral is declared in the spec.
   return strict ? 1 : 0;
 }
 
+// --run: execute every unique cited-and-resolving evidence file through the
+// project-declared runner. Declared in .doctrina/verify.json as
+//   "evidence_runner": "python -m pytest {file}"
+// ({file} is replaced per file). Exit 1 when any run fails (or under --strict
+// when nothing is runnable). Deferred specs are skipped like everywhere else.
+function runEvidence(projectRoot, reports, strict) {
+  const cfgPath = path.join(projectRoot, ".doctrina", "verify.json");
+  let runner = null;
+  if (isFile(cfgPath)) {
+    try { runner = JSON.parse(read(cfgPath))?.evidence_runner ?? null; } catch { runner = null; }
+  }
+  if (!runner || typeof runner !== "string" || !runner.includes("{file}")) {
+    console.error(c.red("error:") + " coverage --run needs an \"evidence_runner\" in .doctrina/verify.json");
+    console.error(c.gray("hint: ") + `add e.g. "evidence_runner": "python -m pytest {file}" (the {file} placeholder is required — the CLI never guesses a test runner)`);
+    return 1;
+  }
+
+  // Unique evidence files: cited by a non-deferred criterion, resolving on
+  // disk, and test-shaped (running a cited source artifact proves nothing).
+  const files = new Set();
+  for (const rep of reports) {
+    for (const r of rep.rows) {
+      if (rep.deferred || r.kind === "deferred") continue;
+      for (const token of r.evidence ?? []) files.add(token);
+    }
+  }
+
+  if (files.size === 0) {
+    console.log(c.gray("no runnable evidence found (no non-deferred criterion cites a resolving test file)"));
+    return strict ? 1 : 0;
+  }
+
+  console.log(c.bold("coverage --run") + c.gray(` — executing ${files.size} evidence file${files.size === 1 ? "" : "s"} via: ${runner}`));
+  let failed = 0;
+  for (const file of [...files].sort()) {
+    const cmd = runner.replaceAll("{file}", file);
+    console.log("");
+    console.log(c.gray(`──── ${cmd}`));
+    const res = spawnSync(cmd, { cwd: projectRoot, shell: true, stdio: "inherit" });
+    const ok = !res.error && res.status === 0;
+    console.log(ok ? c.green(`✓ ${file}`) : c.red(`✗ ${file}${res.error ? ` — ${res.error.message}` : ` (exit ${res.status})`}`));
+    if (!ok) failed += 1;
+  }
+  console.log("");
+  if (failed === 0) {
+    console.log(c.green("ok") + ` ${files.size}/${files.size} evidence runs passed — cited proof actually proves`);
+    return 0;
+  }
+  console.log(c.red("fail") + ` ${files.size - failed}/${files.size} evidence runs passed — a cited proof does not pass`);
+  return 1;
+}
+
 // Per-spec criterion rows — the full classification behind both the report
 // and the --json output. Each row: { n, kind, missing?, skipped? }.
-export function collect(projectRoot) {
+//
+// A spec that declares a deliberate deferral — `Implementation: planned —
+// <why>`, the exact escape hatch `validate` already honours — has its
+// non-covered criteria remapped to kind "deferred": visible in every report,
+// never a --strict failure. Declared debt and hidden debt stop being punished
+// identically (0.11.0 field review item 4: one deferred capability poisoned
+// the close of every unrelated change).
+export function collect(projectRoot, { only = null } = {}) {
   const specsDir = path.join(projectRoot, ".doctrina", "specs");
   const reports = [];
   if (isDir(specsDir)) {
     for (const cap of readdirSync(specsDir).sort()) {
+      if (only && !only.has(cap)) continue;
       const specPath = path.join(specsDir, cap, "spec.md");
       if (!isFile(specPath)) continue;
-      const criteria = extractAcceptanceCriteria(read(specPath));
+      const text = read(specPath);
+      const criteria = extractAcceptanceCriteria(text);
       if (criteria.length === 0) continue;
-      const rows = criteria.map((crit, i) => classify(crit, i + 1, projectRoot, path.dirname(specPath)));
-      reports.push({ cap, specPath, rows });
+      const deferred = isDeclaredDeferral(text);
+      const rows = criteria.map((crit, i) => {
+        const row = classify(crit, i + 1, projectRoot, path.dirname(specPath));
+        if (deferred && row.kind !== "covered") {
+          return { ...row, kind: "deferred", was: row.kind };
+        }
+        return row;
+      });
+      reports.push({ cap, specPath, rows, deferred });
     }
   }
   return reports;
 }
 
+// The declared-deferral escape hatch, matching validate's two-axis check:
+// Implementation is "planned" WITH an explanatory note after the state word.
+// A bare "planned" is an inventory claim, not a deferral, and gets no pass.
+function isDeclaredDeferral(specText) {
+  const implRaw = specHeader(specText, "Implementation");
+  if (!implRaw) return false;
+  const tokens = implRaw.trim().split(/\s+/);
+  const word = (tokens[0] ?? "").replace(/[—-]+$/, "").toLowerCase();
+  return word === "planned" && tokens.length > 1;
+}
+
 // Pure summary of coverage across the spec tree, for other commands
 // (`status`, `review`) that need the numbers without the report output.
+// Deferred criteria (declared deferral, see collect) are counted separately
+// and excluded from the problem counts, matching the gate semantics.
 export function summarize(projectRoot) {
-  const specsDir = path.join(projectRoot, ".doctrina", "specs");
-  let totalCriteria = 0, totalCovered = 0, totalDangling = 0, totalConditional = 0;
+  let totalCriteria = 0, totalCovered = 0, totalDangling = 0, totalConditional = 0, totalDeferred = 0;
   const perCap = [];
-  if (isDir(specsDir)) {
-    for (const cap of readdirSync(specsDir).sort()) {
-      const specPath = path.join(specsDir, cap, "spec.md");
-      if (!isFile(specPath)) continue;
-      const criteria = extractAcceptanceCriteria(read(specPath));
-      if (criteria.length === 0) continue;
-      const rows = criteria.map((crit, i) => classify(crit, i + 1, projectRoot, path.dirname(specPath)));
-      const covered = rows.filter((r) => r.kind === "covered").length;
-      const dangling = rows.filter((r) => r.kind === "dangling").length;
-      const conditional = rows.filter((r) => r.kind === "conditional").length;
-      totalCriteria += rows.length;
-      totalCovered += covered;
-      totalDangling += dangling;
-      totalConditional += conditional;
-      perCap.push({ cap, total: rows.length, covered, dangling, conditional });
-    }
+  for (const rep of collect(projectRoot)) {
+    const covered = rep.rows.filter((r) => r.kind === "covered").length;
+    const dangling = rep.rows.filter((r) => r.kind === "dangling").length;
+    const conditional = rep.rows.filter((r) => r.kind === "conditional").length;
+    const deferred = rep.rows.filter((r) => r.kind === "deferred").length;
+    totalCriteria += rep.rows.length;
+    totalCovered += covered;
+    totalDangling += dangling;
+    totalConditional += conditional;
+    totalDeferred += deferred;
+    perCap.push({ cap: rep.cap, total: rep.rows.length, covered, dangling, conditional, deferred });
   }
   const pct = totalCriteria === 0 ? 100 : Math.round((totalCovered / totalCriteria) * 100);
-  return { perCap, totalCriteria, totalCovered, totalDangling, totalConditional, pct };
+  return { perCap, totalCriteria, totalCovered, totalDangling, totalConditional, totalDeferred, pct };
 }
 
 // Pull the numbered items out of the "## Acceptance criteria" section.
@@ -206,11 +306,14 @@ function classify(criterion, n, projectRoot, specDir) {
     resolved.push({ token, isTest, skipped });
   }
   if (resolved.length === 0) return { kind: "dangling", n, missing };
+  // Runnable evidence: the resolving test-shaped citations, recorded so
+  // `coverage --run` can execute them (existence → passing proof).
+  const evidence = resolved.filter((r) => r.isTest && !r.skipped).map((r) => r.token);
   // Real proof = a non-test artifact, or a test file whose suite runs. If the
   // only thing that resolves is a skipped test, the criterion is conditional.
   const hasRealProof = resolved.some((r) => !r.isTest || !r.skipped);
-  if (hasRealProof) return { kind: "covered", n };
-  return { kind: "conditional", n, skipped: resolved.map((r) => r.token) };
+  if (hasRealProof) return { kind: "covered", n, evidence };
+  return { kind: "conditional", n, skipped: resolved.map((r) => r.token), evidence: [] };
 }
 
 // A cited path is a test file when it sits under a tests directory or carries
@@ -265,7 +368,7 @@ function looksLikePath(s) {
 }
 
 export const help = `
-Usage: doctrina coverage [--strict]
+Usage: doctrina coverage [--strict] [--only <cap,cap>] [--run] [--json]
 
 Report how many acceptance criteria across .doctrina/specs/ cite an
 artifact or test that exists on disk. Each numbered criterion may cite
@@ -275,10 +378,23 @@ A criterion is covered when a cited path resolves to real proof,
 conditional when its only resolving proof is a test file whose suite is
 skipped (\`describe.skip\` / \`xit\` / \`@pytest.mark.skip\` — proves
 nothing), dangling when a cited path is missing on disk, and bare when
-nothing is cited. Read-only.
+nothing is cited. A spec that declares a deliberate deferral —
+\`Implementation: planned — <why>\`, the same escape hatch validate
+honours — has its unproven criteria reported as DEFERRED: visible, but
+never a --strict failure (declared debt is not hidden debt).
 
 Flags:
-  --strict   Exit 1 when any criterion is bare, dangling, or conditional
-             (CI gate). Without it the command always exits 0 (a report).
-  --json     Emit per-spec criterion rows + summary as JSON.
+  --strict           Exit 1 when any criterion is bare, dangling, or
+                     conditional (CI gate). Deferred never fails. Without
+                     it the command always exits 0 (a report).
+  --only <cap,cap>   Scope the report/gate to specific capabilities
+                     (\`doctrina close\` uses this so an unrelated deferred
+                     spec cannot block a change's close).
+  --run              Execute the cited evidence via the project-declared
+                     "evidence_runner" in .doctrina/verify.json (a command
+                     template with a {file} placeholder, e.g.
+                     "python -m pytest {file}"). Exits 1 when any run
+                     fails — promotes "the file exists" to "the proof
+                     passes". The CLI never guesses a test runner.
+  --json             Emit per-spec criterion rows + summary as JSON.
 `;

package/src/commands/intent.js

@@ -0,0 +1,173 @@
+import path from "node:path";
+import process from "node:process";
+import { exists, isFile, read, relPath, write } from "../lib/fs-ops.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+
+// Post-intake intent evolution (0.11.0 field review item 8). The intake is
+// converted once; capabilities born later — brainstorms, pivots, new asks —
+// had no way to gain a product anchor, so they inevitably ended at
+// `Realizes: n/a` and `trace` reported "14/14 ok" while blind to 40% of the
+// system. `intent add` appends a new [SC*] anchor bullet to product.md's
+// Success criteria (allocating the next number), so growth keeps provenance:
+// new intent gets an anchor, the new spec Realizes it, `trace` sees it.
+//
+// The CLI allocates and appends; WHAT the intent says is the human/agent's
+// words verbatim (ADR 0005).
+
+const SUBCOMMANDS = ["add", "list"];
+
+export async function run(positional, _flags) {
+  const sub = positional[0];
+  if (!SUBCOMMANDS.includes(sub)) {
+    console.error(c.red("error:") + ` unknown intent subcommand "${sub ?? ""}"`);
+    const guess = suggest(sub, SUBCOMMANDS);
+    console.error(c.gray("hint: ") + (guess
+      ? `did you mean \`doctrina intent ${guess}\`?`
+      : `available: ${SUBCOMMANDS.join(", ")}`));
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+  if (sub === "list") return intentList(projectRoot);
+  return intentAdd(projectRoot, positional.slice(1).join(" ").trim());
+}
+
+function productPathOf(projectRoot) {
+  return path.join(projectRoot, ".doctrina", "product.md");
+}
+
+// Every "[A-Z]+\d+" anchor at the head of a bullet, in document order —
+// the same convention `trace` reads.
+function collectAnchors(text) {
+  const out = [];
+  const seen = new Set();
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^\s*[-*]\s+\[([A-Z]+)(\d+)\]\s+(.*)$/);
+    if (m && !seen.has(m[1] + m[2])) {
+      seen.add(m[1] + m[2]);
+      out.push({ prefix: m[1], num: Number(m[2]), id: m[1] + m[2], text: m[3].trim(), line: i });
+    }
+  }
+  return out;
+}
+
+function intentList(projectRoot) {
+  const p = productPathOf(projectRoot);
+  if (!isFile(p)) {
+    console.error(c.red("error:") + " no .doctrina/product.md");
+    return 1;
+  }
+  const anchors = collectAnchors(read(p));
+  if (anchors.length === 0) {
+    console.log(c.gray("no intent anchors in product.md — tag bullets with `- [SC1] ...`, or add one: doctrina intent add \"<text>\""));
+    return 0;
+  }
+  console.log(c.bold("Intent anchors") + c.gray(" — product.md, document order:"));
+  console.log("");
+  for (const a of anchors) {
+    console.log(`  ${c.cyan(a.id.padEnd(6))} ${a.text}`);
+  }
+  console.log("");
+  console.log(c.gray(`${anchors.length} anchor${anchors.length === 1 ? "" : "s"}. Provenance: doctrina trace · doctrina why <id>`));
+  return 0;
+}
+
+function intentAdd(projectRoot, textArg) {
+  if (!textArg) {
+    console.error(c.red("error:") + " intent add requires the intent text (quote it)");
+    console.error(c.gray("hint: ") + `example: doctrina intent add "Risk map answers 'what should we test next?' in one read"`);
+    return 2;
+  }
+  const p = productPathOf(projectRoot);
+  if (!isFile(p)) {
+    console.error(c.red("error:") + " no .doctrina/product.md — run `doctrina init` / `doctrina intake` first");
+    return 1;
+  }
+  const original = read(p);
+  const anchors = collectAnchors(original);
+
+  // Accept "SC15: text" to pin an explicit id; otherwise allocate the next
+  // number for the dominant prefix (SC by default).
+  let id = null;
+  let text = textArg;
+  const pinned = textArg.match(/^([A-Z]+)(\d+)\s*:\s*(.+)$/);
+  if (pinned) {
+    id = pinned[1] + pinned[2];
+    text = pinned[3].trim();
+    if (anchors.some((a) => a.id === id)) {
+      console.error(c.red("error:") + ` anchor [${id}] already exists in product.md`);
+      return 1;
+    }
+  } else {
+    const prefix = anchors.length > 0 ? dominantPrefix(anchors) : "SC";
+    const maxNum = anchors.filter((a) => a.prefix === prefix).reduce((m, a) => Math.max(m, a.num), 0);
+    id = `${prefix}${maxNum + 1}`;
+  }
+
+  const lines = original.split(/\r?\n/);
+  const bullet = `- [${id}] ${text}`;
+
+  // Insertion point: after the LAST existing anchor bullet (keeps them
+  // contiguous); else at the end of "## Success criteria"; else appended as a
+  // new Success criteria section (a product.md without one gains it).
+  const samePrefix = anchors.length > 0;
+  let inserted = false;
+  if (samePrefix) {
+    const last = anchors[anchors.length - 1];
+    lines.splice(last.line + 1, 0, bullet);
+    inserted = true;
+  } else {
+    for (let i = 0; i < lines.length; i++) {
+      if (/^##\s+Success criteria\b/i.test(lines[i])) {
+        // Insert before the next "## " heading (or at EOF).
+        let j = i + 1;
+        while (j < lines.length && !/^##\s+/.test(lines[j])) j += 1;
+        // Trim trailing blank lines inside the section for a tidy append.
+        let k = j;
+        while (k > i + 1 && lines[k - 1].trim() === "") k -= 1;
+        lines.splice(k, 0, bullet);
+        inserted = true;
+        break;
+      }
+    }
+  }
+  if (!inserted) {
+    lines.push("", "## Success criteria", "", bullet);
+  }
+
+  write(p, lines.join("\n"), { force: true });
+  console.log(c.green("added") + ` [${id}] to ${relPath(projectRoot, p)}`);
+  console.log("");
+  console.log(`  ${c.cyan(id.padEnd(6))} ${text}`);
+  console.log("");
+  console.log(c.gray("Next: the spec that delivers this intent declares it —"));
+  console.log(`    ${c.cyan(`**Realizes:** ${id}`)}  ${c.gray("(in .doctrina/specs/<capability>/spec.md; `doctrina trace` closes the loop)")}`);
+  return 0;
+}
+
+function dominantPrefix(anchors) {
+  const counts = new Map();
+  for (const a of anchors) counts.set(a.prefix, (counts.get(a.prefix) ?? 0) + 1);
+  return [...counts.entries()].sort((x, y) => y[1] - x[1] || x[0].localeCompare(y[0]))[0][0];
+}
+
+export const help = `
+Usage: doctrina intent add "<text>"
+       doctrina intent add "SC15: <text>"
+       doctrina intent list
+
+Post-intake intent evolution. \`add\` appends a new intent anchor bullet
+(\`- [SC5] <text>\`) to product.md's Success criteria, allocating the next
+number automatically (or pin one with the "SC15: ..." form). New
+capabilities born after the intake — brainstorms, pivots — get an anchor
+to Realize instead of inevitably landing at "Realizes: n/a", so
+\`doctrina trace\` keeps seeing the whole system as it grows.
+
+\`list\` prints every anchor in document order (the same convention trace
+reads). The CLI allocates and appends; the intent's wording is yours,
+verbatim (ADR 0005).
+`;

package/src/commands/review.js

@@ -6,6 +6,7 @@ import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { rankCapabilitiesByDiff } from "./work.js";
+import { parseDependsOn } from "../lib/scan.js";
 import { summarize as coverageSummary } from "./coverage.js";
 import { summarize as traceSummary } from "./trace.js";
 
@@ -42,18 +43,38 @@ export async function run(_positional, flags) {
   const notes = [];  // advisory observations
 
   // 1. Code changed under a capability whose spec was NOT touched — the spec
-  //    may have drifted from the code it describes.
+  //    may have drifted from the code it describes. Touched = every capability
+  //    matched by the code diff (UNCAPPED — the top-3 hint truncation is how
+  //    this missed 5 of 8 in the 0.11.0 field session) UNIONED with every
+  //    capability whose spec.md itself changed.
   const specChanged = new Set(
     all.filter((f) => /(^|\/)\.doctrina\/specs\/[^/]+\/spec\.md$/.test(f.replace(/\\/g, "/")))
       .map((f) => f.replace(/\\/g, "/").match(/\.doctrina\/specs\/([^/]+)\/spec\.md$/)[1]),
   );
-  const ranked = rankCapabilitiesByDiff(projectRoot, sourceFiles);
+  const ranked = rankCapabilitiesByDiff(projectRoot, sourceFiles, { limit: Infinity });
+  const touched = new Set([...specChanged, ...ranked.map((m) => m.id)]);
   for (const m of ranked) {
     if (!specChanged.has(m.id)) {
       breaks.push(`code under capability "${m.id}" changed, but its spec was not updated — confirm \`.doctrina/specs/${m.id}/spec.md\` still describes the code (update it, or note why not)`);
     }
   }
 
+  // 1b. Dependents of touched capabilities (the machine-readable
+  //     **Depends on:** header): a spec that builds on something you changed
+  //     may silently no longer hold. Advisory — a pointer, not a verdict.
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  if (isDir(specsDir) && touched.size > 0) {
+    for (const cap of readdirSync(specsDir).sort()) {
+      if (touched.has(cap)) continue;
+      const specPath = path.join(specsDir, cap, "spec.md");
+      if (!isFile(specPath)) continue;
+      const deps = parseDependsOn(read(specPath)).filter((d) => touched.has(d));
+      if (deps.length > 0) {
+        notes.push(`capability "${cap}" depends on touched ${deps.map((d) => `"${d}"`).join(", ")} — confirm it still holds (\`doctrina why ${cap}\`)`);
+      }
+    }
+  }
+
   // 2. New source files that map to no capability at all — code with no home
   //    in any spec (a likely new, unspecced capability).
   if (ranked.length === 0 && sourceFiles.length > 0) {
@@ -83,8 +104,8 @@ export async function run(_positional, flags) {
 
   // --- Output ---
   console.log(c.gray(`${all.length} changed path(s); ${sourceFiles.length} source file(s) outside .doctrina/.`));
-  if (ranked.length > 0) {
-    console.log(c.gray("Capabilities touched: ") + ranked.map((m) => c.cyan(m.id)).join(", "));
+  if (touched.size > 0) {
+    console.log(c.gray("Capabilities touched: ") + [...touched].sort().map((id) => c.cyan(id)).join(", "));
   }
   console.log("");
 

package/src/commands/skill.js

@@ -61,9 +61,23 @@ function skillSuggest(args, flags) {
   const since = flagString(flags, "since");
 
   const skillsDir = path.join(projectRoot, ".doctrina", "skills");
-  const existing = new Set(
-    isDir(skillsDir) ? walk(skillsDir).filter((f) => f.endsWith(".md")).map((f) => path.basename(f, ".md")) : [],
-  );
+  const existingFiles = isDir(skillsDir) ? walk(skillsDir).filter((f) => f.endsWith(".md")) : [];
+  const existing = new Set(existingFiles.map((f) => path.basename(f, ".md")));
+  // A lesson may already be captured under a DIFFERENT slug (0.11.0 field
+  // review item 11: the human names the skill after the lesson, not after the
+  // change id — "tela-preta-crash-de-render..." for change 0049). Two extra
+  // dedup signals: an existing skill whose body cites the candidate's change
+  // id / commit hash, and token-overlap similarity between the slugs.
+  const existingBodies = existingFiles.map((f) => ({ slug: path.basename(f, ".md"), body: read(f) }));
+  const captured = (cand) => {
+    if (existing.has(cand.slug)) return true;
+    for (const sk of existingBodies) {
+      if (cand.id && sk.body.includes(cand.id)) return true;
+      if (cand.from && sk.body.includes(cand.from)) return true;
+      if (slugSimilarity(cand.slug, sk.slug) >= 0.5) return true;
+    }
+    return false;
+  };
 
   // Two deterministic sources, deduped by slug. `seen` guards against a lesson
   // appearing twice (e.g. a fix committed and later archived as a change).
@@ -78,18 +92,20 @@ function skillSuggest(args, flags) {
       const id = name.replace(/^\d{4}-\d{2}-\d{2}-/, "");
       if (!FIX_SHAPED.test(id)) continue;
       const slug = skillSlug(id);
-      if (existing.has(slug) || seen.has(slug)) continue; // captured or already queued
+      if (seen.has(slug)) continue;
+      const cand = { id, slug, source: "change", from: name };
+      if (captured(cand)) continue; // captured (any slug) or cited by an existing skill
       const proposal = path.join(archiveDir, name, "proposal.md");
-      const why = isFile(proposal) ? firstWhyLine(read(proposal)) : "";
+      cand.why = isFile(proposal) ? firstWhyLine(read(proposal)) : "";
       seen.add(slug);
-      candidates.push({ id, slug, why, source: "change", from: name });
+      candidates.push(cand);
     }
   }
 
   // Source 2 — fix-shaped commits in the git history (ADR 0013). Archive wins a
   // slug collision: a `## Why` paragraph is a richer seed than a subject line.
   for (const cand of gitFixCommits(projectRoot, { since, limit: GIT_LOG_LIMIT })) {
-    if (existing.has(cand.slug) || seen.has(cand.slug)) continue;
+    if (seen.has(cand.slug) || captured(cand)) continue;
     seen.add(cand.slug);
     candidates.push(cand);
   }
@@ -216,6 +232,29 @@ function skillSlug(id) {
   return slug.length > 40 ? slug.slice(0, 40).replace(/-+$/g, "") : (slug || "lesson");
 }
 
+// Token-overlap similarity between two kebab slugs (Jaccard over meaningful
+// tokens). "0049-fix-tela-preta-render" vs "tela-preta-crash-de-render-sem-
+// error-boundary" share tela/preta/render → high overlap even though the
+// human renamed the skill after the lesson. Deterministic; never semantic.
+function slugSimilarity(a, b) {
+  const toks = (s) => new Set(
+    String(s).split("-").filter((t) => t.length >= 3 && !/^\d+$/.test(t) && !SLUG_NOISE.has(t)),
+  );
+  const A = toks(a);
+  const B = toks(b);
+  if (A.size === 0 || B.size === 0) return 0;
+  let inter = 0;
+  for (const t of A) if (B.has(t)) inter += 1;
+  return inter / (A.size + B.size - inter);
+}
+
+// Fix-shaped verbs and connectives carry no lesson identity — without this,
+// every "fix-..." candidate looks 30% similar to every "fix-..." skill.
+const SLUG_NOISE = new Set([
+  "fix", "bug", "hotfix", "patch", "the", "and", "for", "with", "sem", "com",
+  "que", "nao", "por", "para", "una", "uma", "dos", "das",
+]);
+
 function firstWhyLine(proposalText) {
   const m = proposalText.match(/##\s*Why\s*\r?\n+([^\r\n][^\r\n]*)/i);
   if (!m) return "";