doctrina-cli 0.6.0 → 0.8.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.4.0 — current release. Zero runtime dependencies
+**Status:** v0.6.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install

package/package.json

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

package/src/commands/close.js

@@ -0,0 +1,104 @@
+import path from "node:path";
+import process from "node:process";
+import { exists, isFile } from "../lib/fs-ops.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import * as analyze from "./analyze.js";
+import * as change from "./change.js";
+import * as verify from "./verify.js";
+import * as coverage from "./coverage.js";
+import * as trace from "./trace.js";
+import * as validate from "./validate.js";
+
+// One-command close (review 2026-06-27 passive-user feature #2). The work
+// playbook lists the closing sequence — analyze → apply → verify → coverage →
+// trace → archive → validate — and the agent runs it step by step, which is
+// exactly where a gate gets skipped. `close` runs the whole sequence in one
+// pass, in-process, stopping at the first failure with the exact command to
+// rerun, so the agent makes one call and the human approves once. It is a
+// driver over the existing commands; it adds no new checks of its own.
+
+export async function run(positional, flags) {
+  const id = positional[0];
+  if (!id) {
+    console.error(c.red("error:") + " close requires a change <id> (e.g. doctrina close 0001-add-login)");
+    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.");
+  }
+
+  const force = flagBool(flags, "force", false);
+  const strict = new Map([["strict", true]]);
+  const archiveFlags = force ? new Map([["force", true]]) : new Map();
+
+  // Each step: a label, the command that runs it, and the literal command to
+  // rerun on failure. verify is conditional (skipped, with a loud note, when no
+  // verify.json is declared — a project may not have wired the real gate yet).
+  const verifyConfigured = isFile(path.join(projectRoot, ".doctrina", "verify.json"));
+  const steps = [
+    { label: "analyze", rerun: `doctrina analyze ${id}`, run: () => analyze.run([id], new Map()) },
+    { label: "apply", rerun: `doctrina change apply ${id}`, run: () => change.run(["apply", id], new Map()) },
+    verifyConfigured
+      ? { label: "verify", rerun: "doctrina verify", run: () => verify.run([], new Map()) }
+      : { label: "verify", skip: "no .doctrina/verify.json — declare the real gate with `doctrina verify --init`" },
+    { label: "coverage", rerun: "doctrina coverage --strict", run: () => coverage.run([], strict) },
+    // trace is advisory (provenance is a warning, not a hard gate): report it,
+    // never let it block the close.
+    { label: "trace", rerun: "doctrina trace", run: async () => { await trace.run([], new Map()); return 0; } },
+    { label: "archive", rerun: `doctrina change archive ${id}${force ? " --force" : ""}`, run: () => change.run(["archive", id], archiveFlags) },
+    { label: "validate", rerun: "doctrina validate", run: () => validate.run([], new Map()) },
+  ];
+
+  console.log(c.bold(`Closing change ${id}`) + c.gray(" — analyze → apply → verify → coverage → trace → archive → validate"));
+
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    console.log("");
+    console.log(c.gray(`──── ${i + 1}/${steps.length} ${step.label}`));
+    if (step.skip) {
+      console.log(c.yellow("skip   ") + step.skip);
+      continue;
+    }
+    let code;
+    try {
+      code = await step.run();
+    } catch (err) {
+      code = 1;
+      console.error(c.red("error:") + ` ${err.message}`);
+    }
+    if (code !== 0) {
+      console.log("");
+      console.log(c.red(`✗ close stopped at "${step.label}"`) + c.gray(` (step ${i + 1}/${steps.length})`));
+      console.log(c.gray("Fix it, then rerun the step or the whole close:"));
+      console.log(`    ${c.cyan(step.rerun)}`);
+      console.log(`    ${c.cyan(`doctrina close ${id}`)}`);
+      return 1;
+    }
+  }
+
+  console.log("");
+  console.log(c.green(`✓ change ${id} closed`) + c.gray(" — verified, archived, and validated."));
+  console.log(c.gray("Next: ") + c.cyan("doctrina next"));
+  return 0;
+}
+
+export const help = `
+Usage: doctrina close <id> [--force]
+
+Run the whole closing sequence for a change in one pass, stopping at the
+first failure with the exact command to rerun:
+
+  analyze → change apply → verify → coverage --strict → trace → change
+  archive → validate
+
+verify is skipped (with a note) when no .doctrina/verify.json is declared;
+trace is advisory (a report, never a blocker). This is a driver over the
+existing commands — it adds no checks of its own — so the agent makes one
+call instead of seven and the human approves once.
+
+Options:
+  --force    Pass through to \`change archive\` (archive even if verification
+             is incomplete; records the gap).
+`;

package/src/commands/coverage.js

@@ -97,6 +97,33 @@ export async function run(_positional, flags) {
   return strict ? 1 : 0;
 }
 
+// Pure summary of coverage across the spec tree, for other commands
+// (`status`, `review`) that need the numbers without the report output.
+export function summarize(projectRoot) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  let totalCriteria = 0, totalCovered = 0, totalDangling = 0, totalConditional = 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 });
+    }
+  }
+  const pct = totalCriteria === 0 ? 100 : Math.round((totalCovered / totalCriteria) * 100);
+  return { perCap, totalCriteria, totalCovered, totalDangling, totalConditional, pct };
+}
+
 // Pull the numbered items out of the "## Acceptance criteria" section.
 // Each item may span multiple lines (continuation prose); accumulate until
 // the next number or the next "## " heading. Returns an array of strings.

package/src/commands/hooks.js

@@ -43,7 +43,9 @@ export async function run(positional, flags) {
   write(target, body, { force: true });
   chmodSync(target, 0o755);
   console.log(c.green("installed") + ` ${relPath(projectRoot, target)}`);
-  console.log(`The hook runs ${c.cyan("doctrina validate")} before each commit.`);
+  console.log(`The hook runs ${c.cyan("doctrina validate --fix")} before each commit:`);
+  console.log(c.gray("  it rebuilds index.json from the tree (healing drift, re-staging it)"));
+  console.log(c.gray("  and still blocks the commit on errors a rebuild cannot heal."));
   return 0;
 }
 
@@ -51,8 +53,12 @@ export const help = `
 Usage: doctrina hooks install [--force]
 
 Install the Doctrina pre-commit hook into .git/hooks/pre-commit.
-The hook runs \`doctrina validate\` and blocks the commit when
-validation reports errors.
+The hook runs \`doctrina validate --fix\`: it regenerates index.json
+from the tree (healing the most common gate failure — a hand-edited
+header that drifted the index — and re-staging the repaired index)
+and still blocks the commit on errors a rebuild cannot heal. Edit the
+installed hook freely; to gate without auto-repair, swap the line for a
+bare \`doctrina validate\`.
 
 Options:
   --force    Overwrite an existing pre-commit hook

package/src/commands/next.js

@@ -58,17 +58,43 @@ export async function run(_positional, _flags) {
     }
   }
 
-  // ADRs stuck in proposed need a human decision.
+  // ADRs stuck in proposed need a human decision; accepted-but-bare ADRs are
+  // the rot the review flagged — a decision with nothing behind it (no Evidence,
+  // no Landed) is drift waiting to be superseded. Surface the proposed ones
+  // first (a pending decision blocks more than a missing stamp).
   const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  const landNudges = [];
+  const isBareValue = (v) => {
+    const t = (v ?? "").trim();
+    return t === "" || t === "—" || t === "-";
+  };
   for (const f of walk(adrDir)) {
     if (!f.endsWith(".md")) continue;
     const m = path.basename(f).match(/^(\d{4})-/);
     if (!m) continue;
-    const status = listHeader(read(f), "Status");
+    const text = read(f);
+    const status = listHeader(text, "Status");
     if (status && status.toLowerCase() === "proposed") {
       actions.push(`review ADR ${m[1]} (${relPath(projectRoot, f)}): doctrina decision accept ${m[1]}, or supersede it`);
+    } else if (status && status.toLowerCase() === "accepted") {
+      // Bare only when BOTH anchors are empty (Evidence header present-but-bare
+      // and no Landed stamp). An ADR that opts out of Evidence entirely
+      // (header absent) is not nagged.
+      const evidence = listHeader(text, "Evidence");
+      const landed = listHeader(text, "Landed");
+      if (evidence !== null && isBareValue(evidence) && isBareValue(landed)) {
+        landNudges.push(`record what proves ADR ${m[1]}: cite its **Evidence:**, or once it ships, doctrina decision land ${m[1]}`);
+      }
     }
   }
+  for (const n of landNudges) actions.push(n);
+
+  // No procedural memory captured yet, but the history shows a fix-shaped
+  // change — exactly the lesson a skill exists to keep from being relearned
+  // (review §5: the change-0003 "tolerate LLM code fences" case). One gentle
+  // nudge, only when skills are empty, so it never nags a project that opted in.
+  const skillNudge = suggestSkillCapture(projectRoot);
+  if (skillNudge) actions.push(skillNudge);
 
   // Index drift is silent rot; surface it last.
   try {
@@ -95,13 +121,40 @@ export async function run(_positional, _flags) {
   return 0;
 }
 
+// Return a single skill-capture nudge, or null. Fires only when no skill has
+// been written yet (skills/ holds nothing but .gitkeep) AND the archive shows a
+// fix-shaped change whose lesson is the textbook case for a skill. Deterministic
+// pattern match on the archived folder name — a hint, never a decision (ADR 0005).
+const FIX_SHAPED = /(?:^|-)(fix|bug|hotfix|patch|parse|parsing|tolerate|workaround|race|deadlock|flaky|retry|escape|sanitize|sanitise)(?:-|$)/;
+
+function suggestSkillCapture(projectRoot) {
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  if (isDir(skillsDir)) {
+    const hasSkill = walk(skillsDir).some((f) => f.endsWith(".md"));
+    if (hasSkill) return null; // opted in already — never nag
+  }
+  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
+  if (!isDir(archiveDir)) return null;
+  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)) {
+      return `capture a skill from past fixes (e.g. "${id}"): doctrina skill new <slug> — ` +
+        `on-demand procedural memory so the next agent does not relearn it (none exist yet)`;
+    }
+  }
+  return null;
+}
+
 export const help = `
 Usage: doctrina next
 
 Inspect the .doctrina/ tree and print the recommended next workflow
 actions in priority order: open changes (missing proposal, unchecked
 tasks, deltas ready to apply, applied-but-unarchived), ADRs still in
-proposed status, and index drift. Read-only; always exits 0.
+proposed status, accepted ADRs with nothing proving them (cite Evidence
+or run "decision land"), a skill-capture nudge when a past fix went
+uncaptured, and index drift last. Read-only; always exits 0.
 
 Intended use: agents and humans run it to resume work without
 re-reading the whole tree.

package/src/commands/review.js

@@ -0,0 +1,177 @@
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { readdirSync } from "node:fs";
+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 { summarize as coverageSummary } from "./coverage.js";
+import { summarize as traceSummary } from "./trace.js";
+
+// Deterministic conformance review (review 2026-06-27 passive-user feature #3).
+// Given the working tree (or a diff against a ref), report STRUCTURAL breaks
+// between the change and the spec/ADR/contract tree, so the agent self-reviews
+// before bringing work to the human and the human's approval is one command.
+//
+// It checks links and conformance shape, NOT semantic fidelity — whether the
+// code actually does what the spec says stays a human/LLM call, the same honest
+// ceiling as `trace`/`clarify` (ADR 0005). Read-only; exits 0 as a report, 1
+// under --strict when any break exists (CI gate).
+
+export async function run(_positional, flags) {
+  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.");
+  }
+  const strict = flagBool(flags, "strict", false);
+  const against = flagString(flags, "diff"); // optional git ref to diff against
+
+  const { all, sourceFiles } = changedFiles(projectRoot, against);
+  console.log(c.bold("Review") + c.gray(against ? ` — vs ${against}` : " — working-tree changes"));
+  console.log("");
+
+  if (all.length === 0) {
+    console.log(c.gray(against
+      ? `no changes between ${against} and the working tree`
+      : "no working-tree changes to review (stage or edit code first, or pass --diff <ref>)"));
+    return 0;
+  }
+
+  const breaks = []; // hard conformance breaks (fail --strict)
+  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.
+  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);
+  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)`);
+    }
+  }
+
+  // 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) {
+    notes.push(`changed code maps to no existing capability spec — if this is a new capability, scaffold it: \`doctrina spec new <capability>\` (or \`doctrina work --from-diff\`)`);
+  }
+
+  // 3. Coverage — acceptance criteria whose cited proof is missing/skipped.
+  const cov = coverageSummary(projectRoot);
+  if (cov.totalDangling > 0) {
+    breaks.push(`${cov.totalDangling} acceptance criterion(s) cite evidence missing on disk (\`doctrina coverage\`)`);
+  }
+  if (cov.totalConditional > 0) {
+    notes.push(`${cov.totalConditional} acceptance criterion(s) proven only by a skipped test (\`doctrina coverage\`)`);
+  }
+  if (cov.totalCriteria > 0 && cov.totalCovered < cov.totalCriteria - cov.totalDangling - cov.totalConditional) {
+    notes.push(`coverage is ${cov.pct}% (${cov.totalCovered}/${cov.totalCriteria}) — uncovered criteria carry no proof`);
+  }
+
+  // 4. Trace — product intent that no spec realizes, or specs realizing nothing.
+  const tr = traceSummary(projectRoot);
+  if (tr.dropped > 0) breaks.push(`${tr.dropped} product intent anchor(s) are realized by no spec (\`doctrina trace\`)`);
+  if (tr.untraceable > 0) notes.push(`${tr.untraceable} active spec(s) trace to no product intent (\`doctrina trace\`)`);
+
+  // 5. Contract surface — port collisions / env drift / dangling spec refs.
+  const contractIssues = runContractCheck(projectRoot);
+  for (const issue of contractIssues) breaks.push(issue);
+
+  // --- 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(", "));
+  }
+  console.log("");
+
+  if (breaks.length === 0 && notes.length === 0) {
+    console.log(c.green("ok") + " no structural conformance breaks found");
+  } else {
+    for (const b of breaks) console.log(`  ${c.red("✗")} ${b}`);
+    for (const n of notes) console.log(`  ${c.yellow("!")} ${n}`);
+    console.log("");
+    const summary = `${breaks.length} break${breaks.length === 1 ? "" : "s"}, ${notes.length} note${notes.length === 1 ? "" : "s"}`;
+    const status = breaks.length === 0 ? c.green("ok") : (strict ? c.red("fail") : c.yellow("gap"));
+    console.log(status + " " + summary);
+  }
+
+  console.log("");
+  console.log(c.gray("Structural review only — whether the code is FAITHFUL to the spec is a human/LLM call."));
+  return strict && breaks.length > 0 ? 1 : 0;
+}
+
+// Changed paths between a base (a git ref, or HEAD + untracked for the working
+// tree) and now. Returns the full list and the subset outside .doctrina/.
+function changedFiles(projectRoot, against) {
+  const run = (args) => {
+    const r = spawnSync("git", args, { cwd: projectRoot, encoding: "utf8" });
+    if (r.error || r.status !== 0) return [];
+    return r.stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+  };
+  const set = new Set();
+  if (against) {
+    for (const f of run(["diff", "--name-only", against])) set.add(f);
+  } else {
+    for (const f of run(["diff", "--name-only", "HEAD"])) set.add(f);
+    for (const f of run(["ls-files", "--others", "--exclude-standard"])) set.add(f);
+  }
+  const all = [...set];
+  const sourceFiles = all.filter((f) => !f.replace(/\\/g, "/").startsWith(".doctrina/"));
+  return { all, sourceFiles };
+}
+
+// Light re-detection of the two contract breaks that matter to a review — a
+// port claimed by two contracts, and a referenced spec that does not exist. The
+// full contract gate stays `doctrina contract check`; this keeps review
+// self-contained without spawning it.
+function runContractCheck(projectRoot) {
+  const issues = [];
+  const contractsDir = path.join(projectRoot, ".doctrina", "contracts");
+  if (!isDir(contractsDir)) return issues;
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const ports = new Map(); // port -> contract id
+  for (const f of readdirSync(contractsDir)) {
+    if (!f.endsWith(".md")) continue;
+    const id = path.basename(f, ".md");
+    const text = read(path.join(contractsDir, f));
+    for (const m of text.matchAll(/`?(\d{2,5})`?\s*\|/g)) {
+      const port = m[1];
+      if (Number(port) >= 1 && Number(port) <= 65535) {
+        if (ports.has(port) && ports.get(port) !== id) {
+          issues.push(`contract port ${port} is claimed by both "${ports.get(port)}" and "${id}" (\`doctrina contract check\`)`);
+        } else {
+          ports.set(port, id);
+        }
+      }
+    }
+    for (const m of text.matchAll(/\.doctrina\/specs\/([a-z0-9-]+)\//g)) {
+      const cap = m[1];
+      if (!isFile(path.join(specsDir, cap, "spec.md"))) {
+        issues.push(`contract "${id}" references spec "${cap}" which does not exist (\`doctrina contract check\`)`);
+      }
+    }
+  }
+  return issues;
+}
+
+export const help = `
+Usage: doctrina review [--diff <ref>] [--strict]
+
+Deterministic conformance review of your changes against the spec / ADR /
+contract tree. By default it reviews the working-tree changes (tracked +
+untracked); with --diff <ref> it reviews everything that differs from a git
+ref (e.g. \`doctrina review --diff main\`).
+
+Reports structural breaks: code changed under a capability whose spec was
+not updated, changed code that maps to no capability, acceptance criteria
+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).
+
+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,6 +1,7 @@
 import path from "node:path";
 import process from "node:process";
-import { exists, isDir, mkdirp, read, relPath, walk, write } from "../lib/fs-ops.js";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, mkdirp, read, relPath, walk, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir, substitute } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
@@ -8,7 +9,7 @@ import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 
-const SUBCOMMANDS = ["new", "list", "sync"];
+const SUBCOMMANDS = ["new", "list", "sync", "suggest"];
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -22,9 +23,114 @@ export async function run(positional, flags) {
   }
   if (sub === "new") return skillNew(positional.slice(1), flags);
   if (sub === "sync") return skillSync();
+  if (sub === "suggest") return skillSuggest(positional.slice(1), flags);
   return skillList();
 }
 
+// Surface (and optionally scaffold) skills worth capturing (review 2026-06-27
+// passive-user feature #6). A skill exists so a hard-won lesson is not relearned
+// by the next agent/session; the framework otherwise never pulls you toward
+// writing one. `skill suggest` scans the archived changes for fix-shaped work —
+// the textbook case for a skill — and lists candidates whose lesson is not yet
+// captured. With --write it scaffolds a stub per candidate, pre-seeded from the
+// change so the human/agent only fills the body. Deterministic pattern match on
+// the archived folder name — a hint, never a decision (ADR 0005).
+const FIX_SHAPED = /(?:^|-)(fix|bug|hotfix|patch|parse|parsing|tolerate|workaround|race|deadlock|flaky|retry|escape|sanitize|sanitise)(?:-|$)/;
+
+function skillSuggest(args, flags) {
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+  const doWrite = flagBool(flags, "write", false);
+
+  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
+  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 candidates = [];
+  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 (existing.has(slug)) continue; // lesson already captured
+      const proposal = path.join(archiveDir, name, "proposal.md");
+      const why = isFile(proposal) ? firstWhyLine(read(proposal)) : "";
+      candidates.push({ id, slug, why, archive: name });
+    }
+  }
+
+  if (candidates.length === 0) {
+    console.log(c.gray("no uncaptured fix-shaped lessons found in .doctrina/changes/archive/"));
+    console.log(c.gray("(skills are written by humans; this only surfaces candidates — `doctrina skill new <slug>` to author one)"));
+    return 0;
+  }
+
+  if (!doWrite) {
+    console.log(c.bold("Skill candidates") + c.gray(" — fix-shaped lessons not yet captured:"));
+    console.log("");
+    for (const cand of candidates) {
+      console.log(`  ${c.cyan(cand.slug.padEnd(28))} ${c.gray("from " + cand.archive)}`);
+      if (cand.why) console.log(`    ${c.gray(cand.why.slice(0, 90))}`);
+    }
+    console.log("");
+    console.log(c.gray(`${candidates.length} candidate${candidates.length === 1 ? "" : "s"}. Scaffold them: `) + c.cyan("doctrina skill suggest --write"));
+    return 0;
+  }
+
+  // --write: scaffold a stub per candidate, pre-seeded from the change.
+  const templatesDir = locateTemplatesDir();
+  const tplPath = path.join(templatesDir, "skill.md.template");
+  const tpl = read(tplPath);
+  mkdirp(skillsDir);
+  const index = idx.load(projectRoot);
+  const date = today();
+  let created = 0;
+  for (const cand of candidates) {
+    const target = path.join(skillsDir, `${cand.slug}.md`);
+    if (exists(target)) {
+      console.log(c.yellow("skip   ") + ` ${cand.slug} (already exists)`);
+      continue;
+    }
+    let body = substitute(tpl, { SKILL_NAME: cand.slug });
+    if (cand.why) {
+      // Drop the originating lesson into the body so authoring is "fill", not "start".
+      body += `\n<!-- Candidate from change "${cand.id}". The lesson to capture:\n${cand.why}\n-->\n`;
+    }
+    write(target, body, { force: false });
+    idx.addSkill(index, {
+      id: cand.slug,
+      path: `.doctrina/skills/${cand.slug}.md`,
+      description: parseFrontmatter(body, "description") ?? "<edit me — one-sentence summary>",
+      last_updated: date,
+    });
+    console.log(c.green("created") + ` ${relPath(projectRoot, target)}`);
+    created += 1;
+  }
+  if (created > 0) {
+    idx.touch(index, date);
+    idx.save(projectRoot, index);
+  }
+  console.log("");
+  console.log(c.green("ok") + ` scaffolded ${created} skill stub${created === 1 ? "" : "s"} — fill the description/when/body, then \`doctrina skill sync\``);
+  return 0;
+}
+
+function skillSlug(id) {
+  // Reuse the change id as the skill slug, trimmed to a sane length.
+  const slug = id.replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug.length > 40 ? slug.slice(0, 40).replace(/-+$/g, "") : (slug || "lesson");
+}
+
+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];
   if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) {
@@ -176,6 +282,10 @@ Subcommands:
   sync          Copy each skill's frontmatter description into
                 .doctrina/index.json so the index never drifts
                 from the frontmatter (single source of truth).
+  suggest [--write]
+                Surface fix-shaped lessons in the change archive whose
+                skill is not yet captured. --write scaffolds a stub per
+                candidate (pre-seeded from the change) to fill in.
 
 Skills are written by humans, not generated. See docs/en/skills.md
 for the design rationale and the distinction from specs / AGENTS.md /