doctrina-cli 0.17.0 → 0.20.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.20.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install
@@ -25,10 +25,11 @@ 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|card
             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
+Orchestrate workspace init|add|attach|detach|list|tool|guard · delivery new|route|list|status|check|close
 Maintain    upgrade · index rebuild · hooks install · watch · metrics · completion · ci · templates list
 ```
 
@@ -72,14 +73,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.20.0",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [

package/src/commands/adapter.js

@@ -4,6 +4,7 @@ import process from "node:process";
 import { exists, isFile, mkdirp, pruneEmptyDirs, read, relPath, remove, write } from "../lib/fs-ops.js";
 import {
   ADAPTER_STATES, adapterFiles, describeAdapter, listAdapterNames, renderAdapterFile,
+  isMergedConfig, mergeJson, unmergeJson, containsJson, holdsAnyOf,
 } from "../lib/adapters.js";
 import { flagBool } from "../lib/args.js";
 import { today } from "../lib/dates.js";
@@ -11,6 +12,7 @@ import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { projectName } from "../lib/project.js";
+import { applySkillExport } from "../lib/skill-export.js";
 
 // `doctrina adapter` — add, remove, and inventory agent adapters (audit
 // item C1).
@@ -109,6 +111,21 @@ function adapterAdd(projectRoot, name, cmdFlags) {
   let skipped = 0;
   for (const file of spec.files) {
     const dest = path.join(projectRoot, file.relativePath);
+    // A shared settings file is merged, never overwritten nor skipped
+    // (change 0211): the user's own keys stay, ours are added once.
+    if (isMergedConfig(file) && exists(dest)) {
+      const merged = mergeInto(dest, renderAdapterFile(file, tokens));
+      if (merged === null) {
+        console.log(c.yellow("skip   ") + ` ${file.relativePath} (not valid JSON — add the entries by hand)`);
+        skipped += 1;
+      } else if (merged) {
+        console.log(c.green("merged ") + ` ${file.relativePath}`);
+        written += 1;
+      } else {
+        console.log(c.gray("ok     ") + ` ${file.relativePath} (already holds the doctrina entries)`);
+      }
+      continue;
+    }
     if (exists(dest) && !force) {
       console.log(c.yellow("skip   ") + ` ${file.relativePath} (already present; --force overwrites)`);
       skipped += 1;
@@ -124,6 +141,12 @@ function adapterAdd(projectRoot, name, cmdFlags) {
   console.log(`${c.bold("Adapter " + name)} — ${written} file${written === 1 ? "" : "s"} written` +
     (skipped > 0 ? `, ${skipped} left alone` : "") +
     (spec.source === "project" ? c.gray(" (from .doctrina/templates/adapters/)") : ""));
+  // The project's skills follow the agent in (change 0212): with the claude
+  // adapter, `.claude/skills/` becomes an export root.
+  const exported = applySkillExport(projectRoot);
+  if (exported.writes.length > 0) {
+    console.log(c.green("export ") + ` ${exported.writes.length} skill file${exported.writes.length === 1 ? "" : "s"} where the agent discovers skills`);
+  }
   console.log(c.gray("Additive only: AGENTS.md and .doctrina/product.md were not touched."));
   return 0;
 }
@@ -156,6 +179,29 @@ function adapterRemove(projectRoot, name, cmdFlags) {
   for (const file of spec.files) {
     const dest = path.join(projectRoot, file.relativePath);
     if (!isFile(dest)) continue;
+    // A shared settings file loses only the entries this adapter added;
+    // the file goes only when nothing of the user's is left in it.
+    if (isMergedConfig(file)) {
+      const left = unmergeFrom(dest, renderAdapterFile(file, tokens));
+      if (left === undefined) {
+        console.log(c.yellow("kept   ") + ` ${file.relativePath} (not valid JSON — remove the doctrina entries by hand)`);
+        kept += 1;
+        continue;
+      }
+      if (left === UNTOUCHED) {
+        console.log(c.gray("kept   ") + ` ${file.relativePath} (holds no doctrina entries — yours)`);
+        continue;
+      }
+      if (left !== null) {
+        console.log(c.green("updated") + ` ${file.relativePath} (doctrina entries removed; yours kept)`);
+        continue;
+      }
+      remove(dest);
+      console.log(c.green("removed") + ` ${file.relativePath}`);
+      removed += 1;
+      vacated.add(path.dirname(dest));
+      continue;
+    }
     const pristine = normalise(read(dest)) === normalise(renderAdapterFile(file, tokens));
     if (!pristine && !force) {
       console.log(c.yellow("kept   ") + ` ${file.relativePath} (edited since install; --force removes it)`);
@@ -191,6 +237,34 @@ function adapterRemove(projectRoot, name, cmdFlags) {
   return 0;
 }
 
+// Merge the rendered template into an existing JSON file. Returns true when
+// the file changed, false when it already held every entry, null when the
+// file is not JSON this command can safely rewrite.
+function mergeInto(dest, rendered) {
+  let theirs;
+  try { theirs = JSON.parse(read(dest)); } catch { return null; }
+  const ours = JSON.parse(rendered);
+  if (containsJson(theirs, ours)) return false;
+  write(dest, JSON.stringify(mergeJson(theirs, ours), null, 2) + "\n", { force: true });
+  return true;
+}
+
+const UNTOUCHED = Symbol("untouched");
+
+// Take the rendered template's entries back out of a JSON file. Returns what
+// is left (written back), null when nothing is (the caller removes the
+// file), undefined when the file is not JSON.
+function unmergeFrom(dest, rendered) {
+  let theirs;
+  try { theirs = JSON.parse(read(dest)); } catch { return undefined; }
+  // A file holding none of our entries was never ours, or was rewritten by
+  // the user since: it is theirs, and stays as it is.
+  if (!holdsAnyOf(theirs, JSON.parse(rendered))) return UNTOUCHED;
+  const left = unmergeJson(theirs, JSON.parse(rendered));
+  if (left !== null) write(dest, JSON.stringify(left, null, 2) + "\n", { force: true });
+  return left;
+}
+
 function normalise(text) {
   return text.replace(/\r\n/g, "\n").trim();
 }

package/src/commands/analyze.js

@@ -1,7 +1,9 @@
 // @ts-check
 import path from "node:path";
 import process from "node:process";
-import { isDir, relPath } from "../lib/fs-ops.js";
+import { isDir, isFile, read, relPath } from "../lib/fs-ops.js";
+import { listHeader } from "../lib/scan.js";
+import { stripAnsi } from "../lib/json-out.js";
 import { c } from "../lib/colors.js";
 import { collectAnalysis } from "../lib/analysis.js";
 import { EXIT } from "../lib/exit-codes.js";
@@ -40,13 +42,22 @@ export async function run(positional, _flags) {
   console.log(`analyzing ${relPath(projectRoot, changeDir)}/`);
   console.log("");
 
-  const results = collectAnalysis(projectRoot, changeDir);
+  // An APPLIED change is asked only what still means something (change
+  // 0221): its pre-apply checks read the spec the apply wrote as a conflict,
+  // and a close stopped after its apply could never be rerun. The integrity
+  // checks — the set `archive` asks — still count.
+  const proposal = path.join(changeDir, "proposal.md");
+  const applied = isFile(proposal) && (listHeader(read(proposal), "Status") ?? "").toLowerCase() === "applied";
+  const results = collectAnalysis(projectRoot, changeDir)
+    .map((r) => applied && r.kind === "fail" && r.scope === "pre-apply"
+      ? { ...r, kind: "info", line: c.gray("- " + stripAnsi(r.line).replace(/^✗\s*/, "") + " (already applied — a pre-apply check, not asked again)") }
+      : r);
   for (const r of results) console.log(r.line);
   console.log("");
 
   const failed = results.filter((r) => r.kind === "fail").length;
   if (failed === 0) {
-    console.log(c.green("ok") + ` ready to apply`);
+    console.log(c.green("ok") + (applied ? " already applied — resuming: the integrity checks pass" : ` ready to apply`));
   } else {
     console.log(c.red("fail") + ` ${failed} issue${failed === 1 ? "" : "s"}`);
   }

package/src/commands/change.js

@@ -16,17 +16,18 @@ import { c } from "../lib/colors.js";
 import { appendLedgerLine, archivedLine, abandonedLine } from "../lib/ledger.js";
 import { suggest } from "../lib/suggest.js";
 import { confirm, isInteractive } from "../lib/prompt.js";
+import { taskCard } from "../lib/task-card.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", "card"];
 
 // 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 +45,10 @@ 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);
+    case "card":
+      return changeCard(positional.slice(1));
     default:
       console.error(c.red("error:") + ` unknown change subcommand "${sub ?? ""}"`);
       const guess = suggest(sub, SUBCOMMANDS);
@@ -54,6 +59,64 @@ export async function run(positional, flags) {
   }
 }
 
+// `change card <id> [<n>]` (change 0222, ADR 0030): one task as an executor
+// receives it — the task and the lines under it, the change's why, the spec
+// cut to the task, and what to do when done. The executor does not see the
+// planner's conversation; the card is its whole context.
+function changeCard(args) {
+  const id = args[0];
+  if (!id) {
+    console.error(c.red("error:") + " change card requires <id> [task number]");
+    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;
+  }
+  let ordinal = null;
+  if (args[1] !== undefined) {
+    ordinal = Number(args[1]);
+    if (!Number.isInteger(ordinal) || ordinal < 1) {
+      console.error(c.red("error:") + ` task number must be a positive integer (got "${args[1]}")`);
+      return EXIT.USAGE;
+    }
+  }
+  const { card, reason } = taskCard(projectRoot, id, ordinal);
+  if (!card) {
+    console.log(c.gray(reason));
+    return reason.startsWith("every task") ? EXIT.OK : EXIT.PRECONDITION;
+  }
+  const L = [];
+  L.push(`# Task card — ${card.change}, task ${card.ordinal} of ${card.total}` + (card.checked ? " (already ticked)" : ""));
+  L.push("");
+  L.push(`Change: ${card.title}` + (card.delivery ? ` · delivery ${card.delivery}` : ""));
+  L.push(`Repository: ${projectRoot}`);
+  L.push("");
+  L.push("## Task");
+  L.push("");
+  L.push(card.text);
+  for (const d of card.details) L.push(`- ${d}`);
+  if (card.why) {
+    L.push("", "## Why the change exists", "", card.why);
+  }
+  for (const s of card.slices) {
+    L.push("", `## Spec — ${s.capability} (cut to this task)`, "", s.text.trim());
+  }
+  L.push("", "## When done", "");
+  L.push(card.fields.verify
+    ? `1. Run the card's check: \`${card.fields.verify}\` — it must pass.`
+    : "1. Run the project's check: `doctrina verify` — it must pass.");
+  L.push(`2. Tick the box: \`doctrina change tick ${card.change} ${card.ordinal}\`.`);
+  L.push("3. Report back: the files you changed, the commands you ran and what they printed.");
+  L.push("Stay inside this card: do not open, close or archive a change, and do not edit `.doctrina/` — the planner does.");
+  for (const line of L) console.log(line);
+  return EXIT.OK;
+}
+
 // Enforce a lifecycle transition's preconditions from the shared gate map.
 // One implementation, so every driver of a transition refuses — and
 // explains, and forces — identically (C6).
@@ -151,9 +214,6 @@ function changeApply(args, flags) {
   // and exit 0 — through the very analyze → apply path the docs prescribe.
   // The preconditions now come from the shared map, so what guards a
   // transition does not depend on which command drove it.
-  const applyGate = enforceTransition(projectRoot, id, changeDir, "apply", flags);
-  if (!applyGate.ok) return 1;
-
   // Applying twice is silent corruption. The ops verbs are ADDITIVE —
   // `append-requirement` appends, `bump-version` bumps — so a second pass
   // duplicates every requirement and criterion the delta carries and bumps
@@ -171,6 +231,12 @@ function changeApply(args, flags) {
     return 0;
   }
 
+  // The skip above comes FIRST (change 0221): the apply gate is a pre-apply
+  // question, and on an applied change its ADDED check reads the content the
+  // apply wrote as a conflict — which refused the resume of a killed close.
+  const applyGate = enforceTransition(projectRoot, id, changeDir, "apply", flags);
+  if (!applyGate.ok) return 1;
+
   const deltaFiles = walk(path.join(changeDir, "specs")).filter((p) => p.endsWith("delta.md"));
   const date = today();
   let errors = 0;
@@ -398,6 +464,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 +877,18 @@ 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.
+  card <id> [<n>]        Print task <n> (default: the next open one) as a
+                         self-contained card for an executor: the task and the
+                         lines indented under it (Files:, Requirement:, Verify:),
+                         the change's Why, the spec cut to the task, and the
+                         tick command. Exit 0 with a note when every task is done.
 
 apply / archive / check accept multiple ids (batch close of a backlog); the
 exit code is the worst per-id result.
@@ -780,9 +901,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

@@ -1,19 +1,19 @@
 // @ts-check
 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 { appendFileSync, readdirSync } from "node:fs";
+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;
@@ -113,6 +166,8 @@ async function closeOne(projectRoot, id, flags) {
   // archive), which is rendering, not sequencing.
   const verifyConfigured = isFile(path.join(projectRoot, ".doctrina", "verify.json"));
   const runners = {
+    // An applied change resumes here: analyze asks it only the integrity
+    // checks (change 0221).
     analyze: { run: () => analyze.run([id], new Map()) },
 
     // ADR checkpoint (operator review §4.6): the playbook's "record an ADR"
@@ -138,13 +193,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 +296,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 +332,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,18 +468,15 @@ 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)));
+  // Where it went, and the sentence for the human (change 0214): the close
+  // moves the change out of every default read, and a field review found
+  // the person asking for "the doctrina work" of work already archived.
+  const archived = archivedPathOf(projectRoot, id);
+  if (archived) {
+    console.log(c.bold("Tell the human: ") + `change ${id} is closed — archived at ${archived}`);
+  }
   console.log(c.gray("Next: ") + c.cyan("doctrina next"));
   return 0;
 }
@@ -448,6 +509,14 @@ function closingClaim(ran, skippedSteps) {
   return `${claimed || " —"} ${skipped.length === 1 ? "Skipped" : "Skipped"}: ${skipped.join(", ")}.`;
 }
 
+// The archive folder a just-closed change landed in, newest first.
+function archivedPathOf(projectRoot, id) {
+  const dir = path.join(projectRoot, ".doctrina", "changes", "archive");
+  if (!isDir(dir)) return null;
+  const name = readdirSync(dir).sort().reverse().find((n) => n.endsWith(`-${id}`) && /^\d{4}-\d{2}-\d{2}-/.test(n));
+  return name ? `.doctrina/changes/archive/${name}/` : null;
+}
+
 function missingRunner(step) {
   console.error(c.red("error:") +
     ` "${step.label}" is declared in the close sequence but has no runner here`);
@@ -484,14 +553,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 +584,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;