doctrina-cli 0.16.0 → 0.17.0

package/src/commands/decision.js

@@ -152,8 +152,20 @@ function decisionSupersede(args) {
   });
   // Inject Supersedes link
   body = body.replace(/(\*\*Supersedes:\*\*)\s+—/, `$1 ${padded}`);
+  // Carry the predecessor's Scope. A successor built from the bare template
+  // had none, so it was GLOBAL: refining a decision that governed one
+  // capability, then accepting the refinement, loaded it into every
+  // capability's pack — ones the original never governed — and nothing said
+  // so. A replacement decides the same subject; its scope starts where the
+  // predecessor's was, written into the file where the author can widen it
+  // on purpose (ADR 0022: a pack is retrieval, not a dump).
+  const inheritedScope = parseAdrScope(oldText);
+  if (inheritedScope.length > 0) body = insertScopeHeader(body, inheritedScope) ?? body;
   write(newPath, body, { force: false });
   console.log(c.green("created") + ` ${relPath(projectRoot, newPath)}`);
+  if (inheritedScope.length > 0) {
+    console.log(c.gray("scope: ") + `inherited from ${padded} — ${inheritedScope.join(", ")} (edit the Scope: header to change it)`);
+  }
 
   // Mutate ONLY the Status: and Superseded by: headers of the old ADR.
   // Both go through the document model, so an ADR written with a slightly

package/src/commands/doctor.js

@@ -188,7 +188,7 @@ export async function run(_positional, _flags) {
         ? tmplFindings[0].message
         : `${tmplFindings.length} template findings`;
       const remedy = [...byRemedy.keys()].filter((k) => k !== "(manual repair)");
-      row("warn", "templates", summary, remedy.length === 1 ? remedy[0] : "doctrina templates check   (each finding names its own fix)");
+      row("warn", "templates", summary, remedy.length === 1 ? remedy[0] : "doctrina upgrade   (each finding names its own fix)");
       warningsTotal += 1;
     },
 

package/src/commands/hooks.js

@@ -10,6 +10,7 @@ const here = path.dirname(fileURLToPath(import.meta.url));
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
+import { EXIT } from "../lib/exit-codes.js";
 
 const SUBCOMMANDS = ["install"];
 
@@ -33,8 +34,12 @@ export async function run(positional, flags) {
   const projectRoot = process.cwd();
 
   if (!exists(path.join(projectRoot, ".git"))) {
+    // A PRECONDITION, not a gate: nothing was measured and found wanting,
+    // the place to put the hook simply does not exist yet. Class 1 told an
+    // agent to fix its work and retry the same command, which never clears.
     console.error(c.red("error:") + " not a git repository (no .git/ in cwd)");
-    return 1;
+    console.error(c.gray("hint: ") + "run `git init` here, then `doctrina hooks install`");
+    return EXIT.PRECONDITION;
   }
 
   const hooksDir = path.join(projectRoot, ".git", "hooks");

package/src/commands/index-rebuild.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import process from "node:process";
 import { exists } from "../lib/fs-ops.js";
 import * as idx from "../lib/index-json.js";
-import { collectIndexDrift } from "../lib/scan.js";
+import { collectIndexDrift, collectStagedIndexDrift } from "../lib/scan.js";
 import { today } from "../lib/dates.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
@@ -15,7 +15,7 @@ const SUBCOMMANDS = ["rebuild"];
 // 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", "check"], string: [] };
+export const flags = { boolean: ["json", "check", "staged"], string: [] };
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -32,11 +32,21 @@ export async function run(positional, flags) {
 
 function rebuild(flags) {
   const check = flagBool(flags, "check", false);
+  const staged = flagBool(flags, "staged", false);
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
 
+  if (staged) {
+    if (!check) {
+      console.error(c.red("error:") + " --staged reads the commit, so it can only check; it never writes");
+      console.error(c.gray("hint: ") + "run `doctrina index rebuild --check --staged`");
+      return 2;
+    }
+    return checkStaged(projectRoot);
+  }
+
   const state = collectIndexDrift(projectRoot);
   if (state.unreadable) {
     if (check) {
@@ -70,6 +80,39 @@ function rebuild(flags) {
   return 0;
 }
 
+// The drift check, asked of what git will record. `index.json` is derived
+// from the WHOLE tree, so it cannot describe a subset of it: stage part of
+// `.doctrina/` and the index riding along names artifacts the commit does
+// not carry. Every other gate reads the working tree, where those artifacts
+// are still sitting, so none of them can see it.
+function checkStaged(projectRoot) {
+  const state = collectStagedIndexDrift(projectRoot);
+  if (!state.applicable) {
+    console.log(c.green("ok") + ` nothing to check — ${state.reason}`);
+    return 0;
+  }
+  if (state.ok) {
+    console.log(c.green("ok") + " the staged index matches the staged tree");
+    return 0;
+  }
+  if (state.reason) {
+    console.error(c.red("error:") + ` ${state.reason}`);
+    return 1;
+  }
+  for (const p of state.missing) {
+    console.log(c.yellow("staged: ") + `${p} — named by the staged index, absent from the commit`);
+  }
+  for (const p of state.unindexed) {
+    console.log(c.yellow("staged: ") + `${p} — in the commit, absent from the staged index`);
+  }
+  const n = state.missing.length + state.unindexed.length;
+  console.log("");
+  console.log(c.red("fail") + ` the staged index does not describe this commit (${n} difference${n === 1 ? "" : "s"})`);
+  console.log(c.gray("hint: ") + "stage the artifacts above with the index, or unstage the index — "
+    + "index.json is derived from the whole tree, so a partial commit of .doctrina/ cannot carry a matching one");
+  return 1;
+}
+
 export const help = `
 Usage: doctrina index <subcommand>
 
@@ -80,6 +123,13 @@ Subcommands:
                     source of truth; the index is derived.
   rebuild --check   Write nothing; exit 1 with a drift summary when the
                     index no longer matches the tree. CI-friendly.
+  rebuild --check --staged
+                    Ask the same question of the COMMIT rather than the
+                    disk: every artifact the staged index names must be in
+                    the commit, and every staged artifact must be in the
+                    index. A partial commit of .doctrina/ cannot satisfy
+                    both, because the index is derived from the whole tree.
+                    Exits 0 when nothing relevant is staged.
 
 Fields with no on-disk source (project name, framework_version, product
 metadata) are carried over from the existing index.

package/src/commands/init.js

@@ -14,7 +14,7 @@ import { flagBool, flagString, flagGivenWithoutValue } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { EXIT } from "../lib/exit-codes.js";
 import { ask, isInteractive } from "../lib/prompt.js";
-import { looksLikePath, writeIntakeFile, printBootstrapPlaybook, warnIfThinIntake } from "../lib/intake-model.js";
+import { looksLikePath, writeIntakeFile, printBootstrapPlaybook, warnIfThinIntake, nextStepAfterInit } from "../lib/intake-model.js";
 
 const SUPPORTED_AGENTS = [
   "claude",
@@ -107,9 +107,20 @@ export async function run(_positional, flags) {
   // isTTY check the adapter prompt already had. A non-interactive caller
   // that forgot --non-interactive read EOF, got an empty answer, and
   // scaffolded a project with a blank description — silently (C9).
+  // At a terminal, ONE question, and its answer is the intake (change 0173):
+  // it was asked as a one-line description, written into product.md, and
+  // then `next` asked for the same thing again as an intake. A person
+  // describes the project once.
+  let intakeFromTty = false;
   if (!description && !nonInteractive) {
     if (isInteractive()) {
-      description = await ask("One-sentence project description:");
+      const answer = await ask("Describe the project — what it is, who it is for, what it must do:");
+      if (answer && answer.trim() !== "") {
+        intakeBody = answer.trim();
+        intakeSource = "typed at `doctrina init`";
+        intakeFromTty = true;
+        description = firstLineSummary(intakeBody);
+      }
     }
     if (!description) {
       console.error(c.red("error:") + " no project description given and no terminal to ask on");
@@ -293,7 +304,11 @@ export async function run(_positional, flags) {
 
   console.log("");
   console.log(c.bold("Doctrina initialised."));
-  if (intakeBody) {
+  if (intakeFromTty) {
+    // A person at a terminal gets the one instruction, not the agent's
+    // playbook: the agent reprints it with `doctrina intake`.
+    for (const line of nextStepAfterInit("tty")) console.log(line);
+  } else if (intakeBody) {
     console.log(`Next: execute the bootstrap playbook below — it converts the intake into`);
     console.log(`${c.cyan(".doctrina/product.md")} and capability specs. Any AGENTS.md-aware agent`);
     console.log(`runs it on its own; reprint anytime with ${c.cyan("doctrina intake")}.`);
@@ -301,7 +316,7 @@ export async function run(_positional, flags) {
     warnIfThinIntake(intakeBody);
     printBootstrapPlaybook(projectRoot);
   } else {
-    console.log(`Next: edit ${c.cyan("AGENTS.md")} and ${c.cyan(".doctrina/product.md")} for your project.`);
+    for (const line of nextStepAfterInit(null)) console.log(line);
   }
   return 0;
 }

package/src/commands/intake.js

@@ -2,17 +2,19 @@
 import path from "node:path";
 import process from "node:process";
 import { exists, isFile, read, relPath, write } from "../lib/fs-ops.js";
+import { ensureDoctrinaProject, projectName } from "../lib/project.js";
 import { listHeader } from "../lib/scan.js";
 import { assessBrief } from "../lib/clarity.js";
 import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
-import { looksLikePath, warnIfThinIntake, writeIntakeFile, printBootstrapPlaybook } from "../lib/intake-model.js";
+import { looksLikePath, markIntakeConverted, printBootstrapPlaybook, warnIfThinIntake, writeIntakeFile } from "../lib/intake-model.js";
 
 // `init --intake` performs the same operations; they live in
 // lib/intake-model.js so neither command imports out of the other (F7).
 export { warnIfThinIntake, writeIntakeFile, printBootstrapPlaybook } from "../lib/intake-model.js";
+import { collectValidation } from "../lib/validation-model.js";
 import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 
 // `intake` is the first half of the no-ceremony path (ADR 0005): store the
@@ -24,10 +26,47 @@ import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 // 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", "force"], string: ["text"] };
+export const flags = { boolean: ["json", "force", "converted"], string: ["text"] };
 
 export async function run(positional, flags) {
   const projectRoot = process.cwd();
+
+  // Close the bootstrap through the CLI, not by hand.
+  //
+  // Step 7 of the playbook used to read "flip Status to converted in
+  // .doctrina/intake.md" — the one place this framework told an agent to
+  // hand-author a metadata header, against its own standing rule, and the one
+  // header nothing read back. A mistyped word left `next` asking forever for
+  // a bootstrap that was already done.
+  if (flagBool(flags, "converted", false)) {
+    ensureDoctrinaProject(projectRoot);
+    // Converting is the claim that the bootstrap is done — step 6 of the
+    // playbook, "fix everything the gates report", made checkable (change
+    // 0194). It used to convert over a tree `validate` failed, so the specs
+    // became "the source of truth" while an error still said they were not
+    // well-formed. --force converts anyway, for a tree whose errors are not
+    // the bootstrap's to fix.
+    if (isFile(path.join(projectRoot, ".doctrina", "intake.md")) && !flagBool(flags, "force", false)) {
+      const { errors } = collectValidation(projectRoot);
+      if (errors.length > 0) {
+        console.error(c.red("error:") + ` the bootstrap is not done — \`doctrina validate\` reports ${errors.length} error${errors.length === 1 ? "" : "s"}:`);
+        for (const e of errors.slice(0, 5)) console.error("  - " + e);
+        if (errors.length > 5) console.error(`  … and ${errors.length - 5} more`);
+        console.error(c.gray("hint: ") + "fix them (`doctrina validate --fix` heals index drift), then rerun; `--force` converts anyway");
+        return EXIT.GATE;
+      }
+    }
+    const written = markIntakeConverted(projectRoot);
+    if (!written) {
+      console.error(c.red("error:") + " no intake to mark converted at .doctrina/intake.md");
+      console.error(c.gray("hint: ") + 'store one first: `doctrina intake --text "<description>"`');
+      return EXIT.PRECONDITION;
+    }
+    console.log(c.green("converted") + ` ${relPath(projectRoot, written)} — specs are the source of truth now`);
+    console.log(c.gray("next: ") + 'doctrina next');
+    return EXIT.OK;
+  }
+
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
@@ -102,8 +141,8 @@ export async function run(positional, flags) {
     return EXIT.PRECONDITION;
   }
 
-  const projectName = idx.load(projectRoot).project ?? path.basename(projectRoot);
-  writeIntakeFile(projectRoot, { body, source, projectName, date: today(), force });
+  const name = projectName(projectRoot);
+  writeIntakeFile(projectRoot, { body, source, projectName: name, date: today(), force });
   console.log(c.green("created") + ` ${relPath(projectRoot, intakePath)}`);
   console.log("");
   warnIfThinIntake(body);
@@ -127,11 +166,20 @@ Forms:
   doctrina intake --text "<text>"     Ingest an inline description
   doctrina intake                     Reprint the playbook for the
                                       existing pending intake
+  doctrina intake --converted         Close the bootstrap: flip the stored
+                                      intake's Status to converted
 
 Options:
   --text "<description>"   Inline description instead of a file
-  --force                  Overwrite an existing .doctrina/intake.md
+  --force                  Overwrite an existing .doctrina/intake.md; with
+                           --converted, convert although validate fails
+  --converted              Mark the stored intake converted (ends the
+                           bootstrap; nothing else writes that header).
+                           Refuses (exit 1) while validate reports an error
 
-After conversion the agent flips the intake header to
-"- **Status:** converted"; specs become the only source of truth.
+Close the bootstrap with \`doctrina intake --converted\` rather than editing
+the header by hand: \`next\` branches on that value, and \`validate\` reports a
+Status that is neither pending nor converted, because every other word read
+as pending in silence. After conversion the specs are the only source of
+truth.
 `;

package/src/commands/intent.js

@@ -2,6 +2,7 @@
 import path from "node:path";
 import process from "node:process";
 import { exists, isFile, read, relPath, write } from "../lib/fs-ops.js";
+import { intentKey } from "../lib/validation-model.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
@@ -102,9 +103,21 @@ function intentAdd(projectRoot, textArg) {
   let id = null;
   let text = textArg;
   const pinned = textArg.match(/^([A-Z]+)(\d+)\s*:\s*(.+)$/);
+  if (pinned) text = pinned[3].trim();
+
+  // The same intent twice is two anchors for one goal: realize either and the
+  // other stays "dropped", so `trace --strict` fails on a gap nobody can
+  // close. An agent re-running a playbook step is enough to do it. Compared
+  // folded, so case, accents and spacing do not slip a twin past.
+  const twin = anchors.find((a) => intentKey(a.text) === intentKey(text));
+  if (twin) {
+    console.error(c.red("error:") + ` [${twin.id}] already states this intent in product.md`);
+    console.error(c.gray("hint: ") + `realize [${twin.id}] with a spec's \`Realizes:\` header, or reword this one if it is a different goal`);
+    return 1;
+  }
+
   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;

package/src/commands/metrics.js

@@ -11,7 +11,7 @@ import { GIT_STATE, historyState, git } from "../lib/git.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { USAGE_ENV, summarise } from "../lib/usage.js";
 import { OPERATIONS } from "../lib/commands.js";
-import { REEDIT_WINDOW_DAYS, computeSnapshot, parseLog, readSeries, latestSnapshot, trend, round } from "../lib/metrics-model.js";
+import { REEDIT_WINDOW_DAYS, sinceWindow, computeSnapshot, parseLog, readSeries, latestSnapshot, trend, round } from "../lib/metrics-model.js";
 
 // Local-only adoption metrics derived from git history. No network calls,
 // no telemetry: the numbers stay in the repository, versioned like any
@@ -37,6 +37,14 @@ export async function run(_positional, flags) {
   // recent one (audit finding F15) — a year of measurement answering one
   // question. Reading the series is what makes the saving worth doing.
   if (flagBool(flags, "trend", false)) return printTrend(projectRoot);
+  // The window is the invocation's: refused the same with or without history.
+  const sinceRaw = flagString(flags, "since", "90");
+  const since = sinceWindow(sinceRaw);
+  if (since === null) {
+    console.error(c.red("error:") + ` --since expects a day count, a date (YYYY-MM-DD) or "<n> <unit>s ago", got "${sinceRaw}"`);
+    console.error(c.gray("hint: ") + "examples: --since 30 · --since 2026-01-01 · --since \"3 months ago\"");
+    return EXIT.USAGE;
+  }
   const probe = git(projectRoot, ["rev-parse", "--is-inside-work-tree"]);
   // "No history yet" is a VALID state, not a failure — a brand-new project
   // is the most common state in which someone explores this command, and it
@@ -55,8 +63,6 @@ export async function run(_positional, flags) {
     return EXIT.OK;
   }
 
-  const sinceRaw = flagString(flags, "since", "90");
-  const since = /^\d+$/.test(sinceRaw) ? `${sinceRaw} days ago` : sinceRaw;
   const save = flagBool(flags, "save", false);
 
   const log = git(projectRoot, [
@@ -218,8 +224,10 @@ Flags:
                      opt-in usage log. Recording is OFF unless DOCTRINA_USAGE_LOG
                      names a file; only the operation is recorded, never
                      arguments, and nothing leaves the machine.
-  --since <n|date>   Window: a day count (default 90) or any git-parseable
-                     date ("2026-01-01", "3 months ago").
+  --since <n|date>   Window: a day count (default 90), a calendar date
+                     ("2026-01-01") or "<n> <unit>s ago" ("3 months ago").
+                     Anything else is refused: git reads any text as a
+                     date, so a typo would measure the wrong window.
   --save             Write .doctrina/metrics/YYYY-MM-DD.json and print the
                      deltas against the most recent prior snapshot.
   --trend            Read the saved snapshots instead of git: every snapshot

package/src/commands/next.js

@@ -79,7 +79,7 @@ export async function run(_positional, flags) {
 export const RUNNERS = {
   triage: () => import("./triage.js"),
   intake: () => import("./intake.js"),
-  analyze: () => import("./analyze.js"),
+  "change check": () => import("./change.js"),
   "change apply": () => import("./change.js"),
   "change archive": () => import("./change.js"),
   "index rebuild": () => import("./index-rebuild.js"),

package/src/commands/prime.js

@@ -29,8 +29,8 @@ export async function run(_positional, flags) {
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
-  // --rules: the standing rules in full, which is what `constitution` printed
-  // (change 0049). The primer names the ADRs and counts the non-goals; this
+  // --rules: the standing rules in full, which is what the removed
+  // `constitution` printed (changes 0049, 0175). The primer names the ADRs and counts the non-goals; this
   // prints both lists, from the same collection, so the two cannot disagree.
   const view = flagBool(flags, "rules", false) ? "rules" : "prime";
   for (const line of renderView(view, collectSnapshot(projectRoot))) console.log(line);
@@ -49,9 +49,8 @@ The same view as \`doctrina status --view prime\`; both render one
 collection of the tree, so they cannot disagree.
 
   --rules   Print the standing rules in full instead of the primer: every
-            accepted ADR and every declared non-goal. The same lines
-            \`doctrina constitution\` printed, from the same collection —
-            that command is deprecated and delegates here.
+            accepted ADR and every declared non-goal — what the removed
+            \`doctrina constitution\` printed, from the same collection.
 
 Read-only; always exits 0. Deeper reads: \`doctrina context\`,
 \`doctrina why <cap>\`, \`doctrina show <ref>\`.

package/src/commands/report.js

@@ -2,14 +2,12 @@
 import path from "node:path";
 import process from "node:process";
 import { exists } from "../lib/fs-ops.js";
-import { flagBool, flagString } from "../lib/args.js";
+import { flagBool, flagString, parsePositiveInt } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
-import { collectSnapshot } from "../lib/snapshot.js";
+import { collectSnapshot, collectReportWindow } from "../lib/snapshot.js";
 import { renderView } from "../lib/views.js";
-import { gitWindow, historyState, windowCutoff } from "../lib/git.js";
 import { draftAgentChangelog, renderDraft } from "../lib/agent-changelog.js";
-import { collectMetrics } from "../lib/metrics-model.js";
 import { cliVersion } from "../lib/version.js";
 
 // Periodic digest in Markdown — the standup/PR-description view: what was
@@ -33,8 +31,8 @@ export async function run(_positional, flags) {
   }
 
   const sinceRaw = flagString(flags, "since");
-  const days = Number.parseInt(sinceRaw ?? "7", 10);
-  if (!Number.isFinite(days) || days <= 0) {
+  const days = parsePositiveInt(sinceRaw ?? "7");
+  if (days === null) {
     console.error(c.red("error:") + ` --since expects a positive day count, got "${sinceRaw}"`);
     return 2;
   }
@@ -51,19 +49,9 @@ export async function run(_positional, flags) {
     return 0;
   }
 
-  const options = {
-    days,
-    cutoffIso: windowCutoff(days),
-    git: gitWindow(projectRoot, days),
-    // Why there is no window, when there is none — the same door `metrics`
-    // and `context` already ask, so the three cannot disagree about the
-    // state of one repository (change 0080).
-    gitState: historyState(projectRoot),
-    // The same snapshot `metrics` renders, for the same window (change
-    // 0050). One definition of "revert rate", so the digest and the metrics
-    // command cannot report two different numbers for one period.
-    metrics: collectMetrics(projectRoot, `${days} days ago`),
-  };
+  // One collector with `status --view report` (change 0176), so the
+  // deprecated name and its survivor cannot print different digests.
+  const options = collectReportWindow(projectRoot, days);
   for (const line of renderView("report", collectSnapshot(projectRoot), options)) console.log(line);
   return 0;
 }
@@ -78,7 +66,8 @@ work with task progress, artifact counts, and a local-git summary
 descriptions. Read-only; no network. \`doctrina metrics\` has the
 deeper git-derived numbers.
 
-The same view as \`doctrina status --view report --since <days>\`.
+Deprecated: this is \`doctrina status --view report --since <days>\`, and
+\`--agent-changelog\` is \`doctrina status --view agent-changelog\`.
 
   --agent-changelog   Draft the AGENTS.md "What changed" block instead of
                       the digest: one candidate bullet per archived change

package/src/commands/skill.js

@@ -12,7 +12,7 @@ import { suggest } from "../lib/suggest.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 } from "../lib/lexicon.js";
+import { FIX_SHAPED, FIX_SHAPED_SUBJECT, fold, skillSlug } from "../lib/lexicon.js";
 import { artifactNameError } from "../lib/names.js";
 
 const SUBCOMMANDS = ["new", "list", "sync", "suggest"];
@@ -104,7 +104,7 @@ export function draftFromError(text) {
   // Distinctive words, most frequent first — the fallback when an error
   // carries no structure at all.
   const counts = new Map();
-  for (const w of raw.toLowerCase().match(/[a-z][a-z0-9_-]{3,}/g) ?? []) {
+  for (const w of fold(raw).match(/[a-z][a-z0-9_-]{3,}/g) ?? []) {
     if (ERROR_STOP.has(w)) continue;
     counts.set(w, (counts.get(w) ?? 0) + 1);
   }
@@ -125,8 +125,8 @@ export function draftFromError(text) {
   // also mentions do not both land in the name.
   const seedTokens = [];
   const seenToken = new Set();
-  for (const token of [...identifiers.map((i) => i.toLowerCase()), ...keywords]) {
-    const norm = token.replace(/[^a-z0-9]/g, "");
+  for (const token of [...identifiers.map((i) => fold(i)), ...keywords]) {
+    const norm = fold(token).replace(/[^a-z0-9]/g, "");
     if (norm === "" || seenToken.has(norm)) continue;
     seenToken.add(norm);
     seedTokens.push(token);
@@ -344,7 +344,7 @@ function skillSuggest(args, flags) {
     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\``);
+  console.log(c.green("ok") + ` scaffolded ${created} skill stub${created === 1 ? "" : "s"} — fill the description/when/body, then \`doctrina index rebuild\``);
   return 0;
 }
 
@@ -400,16 +400,9 @@ function gitFixCommits(projectRoot, { since, limit }) {
 }
 
 // Derive a skill slug from a commit subject: drop a conventional-commit
-// "type(scope): " prefix, then reuse skillSlug for the lowercase/hyphenate/cap.
+// "type(scope): " prefix and hand the rest to the shared slug, which folds.
 function commitSlug(subject) {
-  const stripped = subject.replace(/^[a-z]+(?:\([^)]*\))?!?\s*:\s*/i, "");
-  return skillSlug(stripped.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, ""));
-}
-
-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");
+  return skillSlug(subject.replace(/^[a-z]+(?:\([^)]*\))?!?\s*:\s*/i, ""));
 }
 
 // Token-overlap similarity between two kebab slugs (Jaccard over meaningful
@@ -482,7 +475,7 @@ function skillNew(args, flags) {
   idx.save(projectRoot, index);
   console.log(c.green("indexed") + ` skill "${name}"`);
   console.log("");
-  console.log(c.gray("hint: ") + "fill the description and when frontmatter fields, then run `doctrina skill sync` to update index.json");
+  console.log(c.gray("hint: ") + "fill the description and when frontmatter fields, then run `doctrina index rebuild` to update index.json");
   return 0;
 }
 

package/src/commands/spec.js

@@ -155,8 +155,12 @@ function specSet(args, flags) {
   let text = read(specPath);
   const applied = [];
   const errors = [];
+  // An error names what to correct: the INVOCATION (a value out of domain, a
+  // criterion that does not exist, a malformed flag) or the SPEC (a header
+  // or section it lacks). Only the second is fixed by editing the work.
+  const refused = (msg) => errors.push({ msg, argument: true });
   const apply = (res) => {
-    if (res.error) errors.push(res.error);
+    if (res.error) errors.push({ msg: res.error, argument: res.cause === "argument" });
     else { text = res.text; applied.push(res.summary); }
   };
   // Order: headers, then version, then criterion — independent edits, all or
@@ -173,7 +177,7 @@ function specSet(args, flags) {
       const derivedValue = derivedImplementations(projectRoot, { only: new Set([capability]) })
         .get(capability)?.derived;
       if (!derivedValue) {
-        errors.push(`--implementation auto needs acceptance criteria to derive from; ${capability} declares none`);
+        errors.push({ msg: `--implementation auto needs acceptance criteria to derive from; ${capability} declares none`, argument: false });
       } else {
         apply(setHeader(text, "Implementation", derivedValue));
       }
@@ -182,23 +186,25 @@ function specSet(args, flags) {
     }
   }
   if (bump !== undefined) {
-    if (!["major", "minor", "patch"].includes(bump)) errors.push(`--bump needs major|minor|patch (got "${bump}")`);
+    if (!["major", "minor", "patch"].includes(bump)) refused(`--bump needs major|minor|patch (got "${bump}")`);
     else apply(bumpVersion(text, bump));
   }
   if (versionExplicit !== undefined) {
-    if (!/^\d+\.\d+\.\d+$/.test(versionExplicit)) errors.push(`--version needs semver X.Y.Z (got "${versionExplicit}")`);
+    if (!/^\d+\.\d+\.\d+$/.test(versionExplicit)) refused(`--version needs semver X.Y.Z (got "${versionExplicit}")`);
     else apply(setHeader(text, "Version", versionExplicit));
   }
   if (criterion !== undefined) {
     const m = String(criterion).match(/^(\d+)\s*:\s*(.+)$/);
-    if (!m) errors.push(`--criterion needs "<n>:<mark>" (got "${criterion}")`);
+    if (!m) refused(`--criterion needs "<n>:<mark>" (got "${criterion}")`);
     else apply(setCriterionMark(text, Number(m[1]), m[2].trim()));
   }
 
   if (errors.length > 0) {
     console.error(c.red("error:") + ` ${errors.length} operation error${errors.length === 1 ? "" : "s"} — spec left untouched:`);
-    for (const e of errors) console.error(`  - ${e}`);
-    return 1;
+    for (const e of errors) console.error(`  - ${e.msg}`);
+    // Retrying an invocation error unchanged never succeeds (ADR 0018), so
+    // one in the list is enough to answer USAGE.
+    return errors.some((e) => e.argument) ? EXIT.USAGE : EXIT.GATE;
   }
 
   // Stamp Last updated when the header exists (best-effort, never an error).