doctrina-cli 0.17.0 → 0.18.0

package/README.md

@@ -3,7 +3,7 @@
 > CLI for the Doctrina framework. The package is published as
 > `doctrina-cli`; the executable it installs is `doctrina`.
 
-**Status:** v0.17.0 — current release. Zero runtime dependencies
+**Status:** v0.18.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install
@@ -25,7 +25,7 @@ surface, by the moment you reach for it:
 ```
 Bootstrap   init · intake · adapter list|add|remove
 Orient      prime · next · status · context · show · search · why · handoff
-Change      triage · work · spec new|list|set · change new|apply|archive|check|tick|abandon
+Change      triage · work · spec new|list|set · change new|apply|archive|check|tick|abandon|delta
             contract new|list|check · decision new|accept|land|supersede|list|scope
             skill new|list|suggest · intent add|list
 Gate        clarify · validate · coverage · trace · review · verify · close · doctor
@@ -72,14 +72,17 @@ For each spec delta found under `.doctrina/changes/<id>/specs/`:
 - **REMOVED:** deletes the target spec.
 - **MODIFIED:** when the delta carries a fenced ` ```ops ` block
   (`set-header` / `bump-version` / `set-criterion` / `replace-criterion`
-  / `append-criterion` / `append-requirement` / `replace-requirement`),
+  / `append-criterion` / `append-requirement` / `replace-requirement` /
+  `remove-requirement` / `remove-criterion`),
   applies it mechanically to the target spec — all
   ops or none — and regenerates the index (ADR 0007). Without an ops
   block it prints a manual-merge pointer and does not write: auto-merging
   arbitrary prose is the kind of implicit decision Doctrina avoids.
 
 On any spec write, the index is rebuilt from the tree so it never drifts
-from the applied spec. `doctrina change abandon <id>` is the inverse of
+from the applied spec. `doctrina change delta <id> <capability>` writes the
+ops lines for you (`--requirement`, `--criterion`, `--bump`), dry-run
+against the spec before anything is written. `doctrina change abandon <id>` is the inverse of
 `change new`: it deletes an open change and its index entry and ledgers
 the abandonment. `doctrina close <id>` runs apply together with verify,
 coverage, archive and validate in one attested pass — the definition of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [

package/src/commands/change.js

@@ -19,14 +19,14 @@ import { confirm, isInteractive } from "../lib/prompt.js";
 import { EXIT } from "../lib/exit-codes.js";
 import { ensureDoctrinaProject, refuseChangeRef } from "../lib/project.js";
 import { parseOperation, parseCapabilityFromDelta, isUntouchedScaffold } from "../lib/doc-model.js";
-import { changeNew } from "../lib/change-ops.js";
+import { changeNew, addDeltaOps } from "../lib/change-ops.js";
 
-const SUBCOMMANDS = ["new", "apply", "archive", "check", "tick", "abandon"];
+const SUBCOMMANDS = ["new", "apply", "archive", "check", "tick", "abandon", "delta"];
 
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
 // let six flags ship undeclared and silently swallow a positional (C3).
-export const flags = { boolean: ["json", "all", "chore", "design", "force", "no-spec", "verbose"], string: ["reason"] };
+export const flags = { boolean: ["json", "all", "chore", "design", "force", "no-spec", "verbose"], string: ["reason", "requirement", "criterion", "bump", "op"] };
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -44,6 +44,8 @@ export async function run(positional, flags) {
       return changeTick(positional.slice(1), flags);
     case "abandon":
       return await changeAbandon(positional.slice(1), flags);
+    case "delta":
+      return changeDelta(positional.slice(1), flags);
     default:
       console.error(c.red("error:") + ` unknown change subcommand "${sub ?? ""}"`);
       const guess = suggest(sub, SUBCOMMANDS);
@@ -398,6 +400,49 @@ async function changeCheck(id, { verbose = false } = {}) {
 // `tick <id> --all` checks everything (tasks.md + the proposal's
 // ## Verification). Ticking is a claim of completion — the honest gate is
 // still archive/verify; this only removes the mechanical friction.
+// `change delta <id> <capability> [ops]` — write ops lines into the change's
+// MODIFIED delta through the grammar `apply` reads (change 0205). Rendering
+// only; lib/change-ops.js decides.
+function changeDelta(args, flags) {
+  const [id, capability, ...rest] = args;
+  if (!id || !capability) {
+    console.error(c.red("error:") + " change delta requires <id> <capability> and at least one operation");
+    console.error(c.gray("hint: ") + "doctrina change delta <id> <capability> --requirement \"event: When <trigger>, the system shall <action>.\" --criterion \"[unverified] <signal> — verified by `<test>`\" --bump minor");
+    return EXIT.USAGE;
+  }
+  const refused = refuseChangeRef(id);
+  if (refused !== null) return refused;
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+  if (!isDir(path.join(projectRoot, ".doctrina", "changes", id))) {
+    console.error(c.red("error:") + ` change "${id}" not found at .doctrina/changes/${id}`);
+    return EXIT.USAGE;
+  }
+  // In the order a reader expects them: requirement, criterion, any raw op,
+  // and the bump last.
+  const lines = [];
+  const requirement = flagString(flags, "requirement");
+  const criterion = flagString(flags, "criterion");
+  const raw = flagString(flags, "op") ?? (rest.length > 0 ? rest.join(" ") : undefined);
+  const bump = flagString(flags, "bump");
+  if (requirement) lines.push(`append-requirement ${requirement}`);
+  if (criterion) lines.push(`append-criterion ${criterion}`);
+  if (raw) lines.push(raw);
+  if (bump) lines.push(`bump-version ${bump}`);
+
+  const r = addDeltaOps(projectRoot, id, capability, lines);
+  if (r.code !== EXIT.OK) {
+    console.error(c.red("error:") + ` ${r.error}`);
+    for (const d of r.details ?? []) console.error(`  - ${d}`);
+    if (r.hint) console.error(c.gray("hint: ") + r.hint);
+    return r.code;
+  }
+  console.log(c.green(r.created ? "created" : "updated") + ` ${r.deltaRel}` +
+    c.gray(` — ${lines.length} op${lines.length === 1 ? "" : "s"} added; the block now holds ${r.block.length} (${r.block.join(", ")}), and applies cleanly`));
+  console.log(c.gray("Preview the merge: ") + c.cyan(`doctrina change check ${id} --verbose`));
+  return EXIT.OK;
+}
+
 function changeTick(args, flags) {
   const id = args[0];
   if (!id) {
@@ -768,6 +813,13 @@ Subcommands:
                          or every one with --all. No args = list only.
   abandon <id>           Delete an open change folder and its index entry, and
                          record the abandonment in the ledger ([--reason "..."]).
+  delta <id> <capability> [--requirement "<section>: <text>"] [--criterion "<text>"]
+        [--bump major|minor|patch] [--op "<op line>" | <op line>]
+                         Write ops into the change's MODIFIED delta for the
+                         capability — created from the template when absent —
+                         parsed by the grammar apply reads and dry-run against
+                         the spec first: nothing is written unless the whole
+                         block applies. A second --bump replaces the first.
 
 apply / archive / check accept multiple ids (batch close of a backlog); the
 exit code is the worst per-id result.
@@ -780,9 +832,12 @@ A MODIFIED delta may carry a fenced operations block that \`apply\` executes:
   append-criterion [unverified] new signal — verified by \`test/x.test.ts\`
   append-requirement event: When <trigger>, the system shall <action>.
   replace-requirement ubiquitous 2: The system shall <action>.
+  remove-requirement state 1: superseded by event 3
+  remove-criterion 4: proven by criterion 2 since 0.9
   \`\`\`
 append-* ops resolve numbering/position at apply time, so concurrent open
-changes appending to the same spec cannot collide.
+changes appending to the same spec cannot collide. \`change delta\` writes
+these lines for you, one call per addition.
 
 Options:
   --force                Overwrite existing files (where applicable)

package/src/commands/close.js

@@ -2,18 +2,18 @@
 import path from "node:path";
 import process from "node:process";
 import { appendFileSync } from "node:fs";
-import { exists, isDir, isFile, read, walk } from "../lib/fs-ops.js";
+import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
-import { parseCapabilityFromDelta } from "../lib/doc-model.js";
 import { printAdrCheckpoint, acceptedDecisionCount } from "../lib/adr-guard.js";
 import { docsRemedy, checkDocsImpact, checkChangelogImpact } from "../lib/docs-impact.js";
 import { collectRuntimeFindings } from "../lib/runtime.js";
 import { derivedImplementations, implementationMismatch, summarize } from "../lib/coverage-model.js";
-import { specHeader, dependentsOf } from "../lib/scan.js";
+import { specHeader, dependentsOf, deltaCapabilities } from "../lib/scan.js";
 import { sequence, sequenceLabels, stepRerun } from "../lib/gates.js";
 import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 import { refuseChangeRef } from "../lib/project.js";
+import { unfinishedChanges } from "../lib/snapshot.js";
 import * as analyze from "./analyze.js";
 import * as change from "./change.js";
 import * as verify from "./verify.js";
@@ -23,7 +23,7 @@ import * as validate from "./validate.js";
 import * as indexRebuild from "./index-rebuild.js";
 import { appendLedgerLine, docsGapLine, ledgerPath as ledgerFile } from "../lib/ledger.js";
 import * as review from "./review.js";
-import * as skill from "./skill.js";
+import { skillCandidates } from "../lib/skill-candidates.js";
 
 // One-command close (review 2026-06-27 passive-user feature #2). The work
 // playbook lists the closing sequence — analyze → apply → runtime → verify →
@@ -65,9 +65,62 @@ export async function run(positional, flags) {
       ? c.green("ok") + ` all ${positional.length} changes closed`
       : c.red("fail") + " at least one close stopped — see above");
   }
+  reportSkills(projectRoot, positional);
+  reportUnfinished(projectRoot, positional);
   return worst;
 }
 
+// Capture the lesson while it is fresh (operator review §4.7) — the lesson
+// THIS close produced (change 0202). The close used to print the whole
+// `skill suggest` listing, per id: the same thirteen candidates after every
+// close, which a field review of 0.17 named as noise nobody read. Now a
+// candidate born from a change just closed gets its line; every other one is
+// a count pointing at the full listing. Once per run, batch or not.
+// Advisory — a listing, never a gate, and a failure never un-closes anything.
+function reportSkills(projectRoot, closing) {
+  let candidates;
+  try {
+    candidates = skillCandidates(projectRoot);
+  } catch {
+    return;
+  }
+  if (candidates.length === 0) return;
+  const ids = new Set(closing);
+  const fresh = candidates.filter((cand) => cand.source === "change" && ids.has(cand.id));
+  const waiting = candidates.length - fresh.length;
+  console.log("");
+  console.log(c.gray("──── skills (advisory)"));
+  for (const cand of fresh) {
+    console.log(c.yellow("  ! ") + `${cand.id} is fix-shaped — capture the lesson while it is fresh: ` +
+      c.cyan(`doctrina skill new ${cand.slug}`));
+  }
+  if (waiting > 0) {
+    console.log(c.gray(`  ${waiting} ${fresh.length > 0 ? "older " : ""}candidate${waiting === 1 ? "" : "s"} waiting — \`doctrina skill suggest\``));
+  }
+}
+
+// The other open changes, said at the one moment someone is looking (change
+// 0201). A field review of 0.17: change 0078 shipped, stayed open, and no
+// close after it said a word. A change that looks finished — applied, or
+// every task ticked — and one open a week or more get a line each; the rest
+// are a count. Advisory: it never moves the exit code.
+function reportUnfinished(projectRoot, closing) {
+  const others = unfinishedChanges(projectRoot, { exclude: closing });
+  if (others.length === 0) return;
+  const flagged = others.filter((ch) => ch.reason !== null);
+  console.log("");
+  console.log(c.gray(`──── other open changes (advisory) — ${others.length}`));
+  for (const ch of flagged) {
+    const age = ch.ageDays !== null ? `, opened ${ch.ageDays}d ago` : "";
+    const how = ch.finished ? ` — ${c.cyan(`doctrina close ${ch.id}`)}` : "";
+    console.log(c.yellow("  ! ") + `${ch.id}: ${ch.reason}${age}${how}`);
+  }
+  const quiet = others.length - flagged.length;
+  if (quiet > 0) {
+    console.log(c.gray(`  ${quiet} more open and recent — \`doctrina next\``));
+  }
+}
+
 async function closeOne(projectRoot, id, flags) {
   const refused = refuseChangeRef(id);
   if (refused !== null) return refused;
@@ -138,13 +191,17 @@ async function closeOne(projectRoot, id, flags) {
     },
 
     // The review runs against the working tree, which for a close IS the
-    // change's diff: the work is done and not yet archived. Its exit code is
+    // change's diff: the work is done and not yet archived. It is told which
+    // change it is reviewing (change 0200): the deltas it carries are the
+    // spec updates, merged one step later by `apply`, and code under a
+    // capability the change carries no delta for is one line, not one
+    // break per capability. Its exit code is
     // discarded on purpose — the step is declared advisory, and an advisory
     // step that could still move the close's result would be advisory in name
     // only. A crash is caught by the loop and reported the same way.
     review: {
       run: async () => {
-        await review.run([], new Map());
+        await review.run([], new Map([["change", id]]));
         return 0;
       },
     },
@@ -237,7 +294,10 @@ async function closeOne(projectRoot, id, flags) {
     // verify is conditional: skipped with a loud note when no verify.json is
     // declared, because a project may not have wired the real gate yet.
     verify: verifyConfigured
-      ? { run: () => verify.run([], new Map()) }
+      // --reuse (change 0203): the suite the agent just ran by hand, or the
+      // one the previous id of this batch ran, on byte-identical code, is
+      // not run a second time. Anything that differs runs everything.
+      ? { run: () => verify.run([], new Map([["reuse", true]])) }
       : { skip: "no .doctrina/verify.json — declare the real gate with `doctrina verify --init`" },
 
     coverage: {
@@ -270,7 +330,9 @@ async function closeOne(projectRoot, id, flags) {
           // one session with an empty `## [Unreleased]` behind them.
           const log = checkChangelogImpact(projectRoot, changeDir);
           if (log.ok) {
-            console.log(c.green("ok") + ` ${log.reason}`);
+            // One line when both answers are the same sentence (change 0202):
+            // "touches no documented surface" twice read as two checks.
+            if (log.reason !== r.reason) console.log(c.green("ok") + ` ${log.reason}`);
             return 0;
           }
           console.error(c.red("error:") + ` this change ${log.reason}:`);
@@ -404,16 +466,6 @@ async function closeOne(projectRoot, id, flags) {
     }
   }
 
-  // Capture the lesson while it is fresh (operator review §4.7): surface the
-  // fix-shaped lessons not yet written as skills, right where the operator
-  // just proved they finish what they start. Advisory — a listing, never a
-  // gate, and a suggest failure never un-closes the change.
-  console.log("");
-  console.log(c.gray("──── skills (advisory)"));
-  try {
-    await skill.run(["suggest"], new Map());
-  } catch { /* advisory only */ }
-
   console.log("");
   console.log(c.green(`✓ change ${id} closed`) + c.gray(closingClaim(ran, skippedSteps)));
   console.log(c.gray("Next: ") + c.cyan("doctrina next"));
@@ -484,14 +536,7 @@ function reportDependentCoverage(projectRoot, touched) {
 }
 
 function touchedCapabilities(projectRoot, id) {
-  const specsDir = path.join(projectRoot, ".doctrina", "changes", id, "specs");
-  const caps = new Set();
-  for (const deltaPath of walk(specsDir)) {
-    if (!deltaPath.endsWith("delta.md")) continue;
-    const cap = parseCapabilityFromDelta(read(deltaPath), deltaPath);
-    if (cap) caps.add(cap);
-  }
-  return [...caps].sort();
+  return deltaCapabilities(path.join(projectRoot, ".doctrina", "changes", id));
 }
 
 // The sequence is DECLARED once, in lib/gates.js, and rendered here. It used
@@ -522,7 +567,9 @@ first failure with the exact command to rerun:
 
 ${SEQUENCE}
 
-then a closing skill-suggest listing (advisory).
+then two advisory notes, once per run: the skill candidate a just-closed
+fix-shaped change produced (the others are a count), and the other open
+changes that look finished or are a week old.
 
 The coverage gate is scoped to the capabilities the change's deltas touch,
 so a deliberately deferred spec elsewhere cannot block an unrelated close;

package/src/commands/next.js

@@ -82,6 +82,7 @@ export const RUNNERS = {
   "change check": () => import("./change.js"),
   "change apply": () => import("./change.js"),
   "change archive": () => import("./change.js"),
+  close: () => import("./close.js"),
   "index rebuild": () => import("./index-rebuild.js"),
 };
 

package/src/commands/review.js

@@ -8,7 +8,8 @@ import { c } from "../lib/colors.js";
 import { rankCapabilitiesByDiff } from "../lib/work-model.js";
 import { readLedger, churnByCapability } from "../lib/ledger.js";
 import { changedFiles, windowCutoff, historyState, refExists } from "../lib/git.js";
-import { dependentsOf } from "../lib/scan.js";
+import { dependentsOf, deltaCapabilities } from "../lib/scan.js";
+import { refuseChangeRef } from "../lib/project.js";
 import { notADoctrinaProject, EXIT } from "../lib/exit-codes.js";
 import { summarize as coverageSummary } from "../lib/coverage-model.js";
 import { summarize as traceSummary } from "../lib/trace-model.js";
@@ -37,7 +38,7 @@ const CHURN_NOTABLE = 3;
 // bury every other finding under a file listing.
 const ORPHAN_LIST_LIMIT = 5;
 
-export const flags = { boolean: ["json", "strict"], string: ["diff"] };
+export const flags = { boolean: ["json", "strict"], string: ["diff", "change"] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -60,8 +61,26 @@ export async function run(_positional, flags) {
     return EXIT.USAGE;
   }
 
+  // --change <id>: review the tree AS that change's close sees it (change
+  // 0200). Its deltas are the spec updates — merged one step later, by
+  // `apply` — so the capabilities they target count as updated.
+  const changeId = flagString(flags, "change");
+  /** @type {Set<string> | null} */
+  let changeCaps = null;
+  if (changeId !== undefined) {
+    const refused = refuseChangeRef(changeId);
+    if (refused !== null) return refused;
+    const changeDir = path.join(projectRoot, ".doctrina", "changes", changeId);
+    if (!isDir(changeDir)) {
+      console.error(c.red("error:") + ` change "${changeId}" not found at .doctrina/changes/${changeId}`);
+      return EXIT.USAGE;
+    }
+    changeCaps = new Set(deltaCapabilities(changeDir));
+  }
+
   const { all, sourceFiles } = reviewScope(projectRoot, against);
-  console.log(c.bold("Review") + c.gray(against ? ` — vs ${against}` : " — working-tree changes"));
+  console.log(c.bold("Review") + c.gray(against ? ` — vs ${against}` : " — working-tree changes") +
+    (changeId ? c.gray(` · change ${changeId}`) : ""));
   console.log("");
 
   if (all.length === 0) {
@@ -85,10 +104,18 @@ export async function run(_positional, flags) {
   );
   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)`);
+  const stale = ranked.map((m) => m.id).filter((id) => !specChanged.has(id) && !changeCaps?.has(id));
+  if (changeCaps === null) {
+    for (const id of stale) {
+      breaks.push(`code under capability "${id}" changed, but its spec was not updated — confirm \`.doctrina/specs/${id}/spec.md\` still describes the code (update it, or note why not)`);
     }
+  } else if (stale.length > 0) {
+    // Reviewed as a change: code under capabilities it carries no delta for
+    // is either this change forgetting a delta or other work lying in the
+    // tree — the review cannot tell which, so it says both, ONCE. One break
+    // per capability, repeated on every close, is how the warning became
+    // noise nobody read (field review, 0.17).
+    breaks.push(`code changed under ${stale.length === 1 ? "a capability" : `${stale.length} capabilities`} this change carries no delta for: ${stale.map((id) => `"${id}"`).join(", ")} — if this change made those edits, add a delta (or note why the spec still holds); if other work did, it is not this change's (commit or stash it)`);
   }
 
   // 1b. Dependents of touched capabilities (the machine-readable
@@ -107,7 +134,10 @@ export async function run(_positional, flags) {
   if (touched.size > 0) {
     const since = windowCutoff(CHURN_WINDOW_DAYS);
     const churn = churnByCapability(readLedger(projectRoot).entries, { since })
-      .filter((row) => touched.has(row.capability) && row.changes >= CHURN_NOTABLE);
+      // Reviewed as a change, only the capabilities it updates: churn is
+      // context for the spec being changed, and four lines of it about
+      // ground the change merely stands near was more noise per close.
+      .filter((row) => (changeCaps ?? touched).has(row.capability) && row.changes >= CHURN_NOTABLE);
     for (const row of churn) {
       notes.push(`capability "${row.capability}" landed ${row.changes} changes in the last ${CHURN_WINDOW_DAYS} days (last ${row.last}) — history, not a verdict: read it as "this area is moving", not "this area is wrong"`);
     }
@@ -219,7 +249,7 @@ function runContractCheck(projectRoot) {
 }
 
 export const help = `
-Usage: doctrina review [--diff <ref>] [--strict]
+Usage: doctrina review [--diff <ref>] [--change <id>] [--strict]
 
 Deterministic conformance review of your changes against the spec / ADR /
 contract tree. By default it reviews the working-tree changes (tracked +
@@ -232,6 +262,15 @@ citing missing proof, product intent realized by no spec, and contract
 port/reference collisions. It checks conformance shape, NOT semantic
 fidelity (whether the code does what the spec says stays a human/LLM call).
 
+--change <id> reviews the tree as that change's close does: the capabilities
+its deltas target count as updated (the close merges them one step later),
+and code under capabilities it carries no delta for is reported in one line —
+this change forgot a delta, or other work is lying in the tree.
+
+A file's owner is the spec whose \`**Source:**\` claims it; failing that, the
+spec citing its exact path; failing both, the path and basename inference,
+from specs that declare no Source.
+
 Read-only. Exits 0 as a report; with --strict, exits 1 when any hard break
 exists (CI gate). Notes (advisory) never fail the gate.
 `;

package/src/commands/skill.js

@@ -1,7 +1,6 @@
 // @ts-check
 import path from "node:path";
 import process from "node:process";
-import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, mkdirp, read, relPath, walk, write } from "../lib/fs-ops.js";
 import { readTemplate, locateTemplatesDir, substitute } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
@@ -9,10 +8,10 @@ import { today } from "../lib/dates.js";
 import { flagBool, flagString, flagGivenWithoutValue } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
+import { skillCandidates } from "../lib/skill-candidates.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { parseFrontmatter } from "../lib/doc-model.js";
-import { git, GIT_STATE } from "../lib/git.js";
-import { FIX_SHAPED, FIX_SHAPED_SUBJECT, fold, skillSlug } from "../lib/lexicon.js";
+import { fold, skillSlug } from "../lib/lexicon.js";
 import { artifactNameError } from "../lib/names.js";
 
 const SUBCOMMANDS = ["new", "list", "sync", "suggest"];
@@ -237,57 +236,8 @@ function skillSuggest(args, flags) {
     return writeErrorDraft(projectRoot, draft, doWrite);
   }
 
+  const candidates = skillCandidates(projectRoot, { since, limit: GIT_LOG_LIMIT });
   const skillsDir = path.join(projectRoot, ".doctrina", "skills");
-  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).
-  /** @type {SkillCandidate[]} */
-  const candidates = [];
-  const seen = new Set();
-
-  // Source 1 — archived change proposals with a fix-shaped folder name.
-  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
-  if (isDir(archiveDir)) {
-    for (const name of readdirSync(archiveDir).sort()) {
-      if (!isDir(path.join(archiveDir, name))) continue;
-      const id = name.replace(/^\d{4}-\d{2}-\d{2}-/, "");
-      if (!FIX_SHAPED.test(id)) continue;
-      const slug = skillSlug(id);
-      if (seen.has(slug)) continue;
-      /** @type {SkillCandidate} */
-      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");
-      cand.why = isFile(proposal) ? firstWhyLine(read(proposal)) : "";
-      seen.add(slug);
-      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 (seen.has(cand.slug) || captured(cand)) continue;
-    seen.add(cand.slug);
-    candidates.push(cand);
-  }
 
   if (candidates.length === 0) {
     console.log(c.gray("no uncaptured fix-shaped lessons found in .doctrina/changes/archive/ or the git history"));
@@ -361,80 +311,6 @@ function seedLabel(cand) {
     : `Candidate from change "${cand.id}"`;
 }
 
-// Source 2 for `skill suggest`: fix-shaped commits in the git history (ADR
-// 0013). Deterministic — a regex on the subject, never a read of the diff
-// (ADR 0005 semantic-fidelity ceiling). Returns [] silently when this is not a
-// git repo, git is absent, or the --since ref is unknown, so the command
-// degrades to archive-only rather than erroring.
-function gitFixCommits(projectRoot, { since, limit }) {
-  // US (0x1f) between fields, RS (0x1e) between records — robust against any
-  // newline or punctuation inside a subject or body.
-  const format = "%H%x1f%s%x1f%b%x1e";
-  const args = ["log", "--no-merges", `--format=${format}`];
-  if (since) args.push(`${since}..HEAD`);
-  else args.push("-n", String(limit));
-
-  const r = git(projectRoot, args);
-  if (r.state !== GIT_STATE.OK || !r.stdout) return [];
-
-  /** @type {SkillCandidate[]} */
-  const out = [];
-  const seen = new Set();
-  for (const record of r.stdout.split("\x1e")) {
-    const [sha, subject = "", body = ""] = record.replace(/^\r?\n/, "").split("\x1f");
-    if (!sha || !sha.trim()) continue;
-    if (!FIX_SHAPED_SUBJECT.test(subject)) continue;
-    const slug = commitSlug(subject);
-    if (!slug || seen.has(slug)) continue; // first commit wins a duplicate lesson
-    seen.add(slug);
-    const firstBodyLine = body.split(/\r?\n/).map((l) => l.trim()).find(Boolean) ?? "";
-    out.push({
-      id: slug,
-      slug,
-      source: "commit",
-      ref: sha.trim().slice(0, 9),
-      why: subject.trim() + (firstBodyLine ? ` — ${firstBodyLine}` : ""),
-    });
-  }
-  return out;
-}
-
-// Derive a skill slug from a commit subject: drop a conventional-commit
-// "type(scope): " prefix and hand the rest to the shared slug, which folds.
-function commitSlug(subject) {
-  return skillSlug(subject.replace(/^[a-z]+(?:\([^)]*\))?!?\s*:\s*/i, ""));
-}
-
-// 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 "";
-  const line = m[1].trim();
-  return /^<!--/.test(line) ? "" : line;
-}
-
 function skillNew(args, flags) {
   const name = args[0];
   const nameError = artifactNameError(name, "skill name");