doctrina-cli 0.15.1 → 0.17.0

package/src/commands/review.js

@@ -1,16 +1,17 @@
 // @ts-check
 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 { parseDependsOn } from "../lib/scan.js";
-import { notADoctrinaProject } from "../lib/exit-codes.js";
-import { summarize as coverageSummary } from "./coverage.js";
-import { summarize as traceSummary } from "./trace.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 { 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";
 
 // Deterministic conformance review (review 2026-06-27 passive-user feature #3).
 // Given the working tree (or a diff against a ref), report STRUCTURAL breaks
@@ -25,6 +26,17 @@ import { summarize as traceSummary } from "./trace.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).
+// How far back the churn note looks, and how many landed changes make it
+// worth saying at all. A window rather than "all time": a capability that
+// moved nine times two years ago is history, not news.
+const CHURN_WINDOW_DAYS = 60;
+const CHURN_NOTABLE = 3;
+
+// How many unclaimed files the orphan note names before it summarises the
+// rest. Long enough to act on, short enough that a wide refactor does not
+// bury every other finding under a file listing.
+const ORPHAN_LIST_LIMIT = 5;
+
 export const flags = { boolean: ["json", "strict"], string: ["diff"] };
 
 export async function run(_positional, flags) {
@@ -35,7 +47,20 @@ export async function run(_positional, flags) {
   const strict = flagBool(flags, "strict", false);
   const against = flagString(flags, "diff"); // optional git ref to diff against
 
-  const { all, sourceFiles } = changedFiles(projectRoot, against);
+  // A ref the git cannot resolve is a filter that matches nothing, and the
+  // review used to read it as "nothing changed" — exit 0, `--strict`
+  // included, on a tree where a valid ref reported breaks. A CI job running
+  // `doctrina review --diff main --strict` stayed green forever on a shallow
+  // clone with no local `main` (change 0092). Only asked inside a usable
+  // repository: outside one the command still stays silent rather than
+  // accusing.
+  if (against && historyState(projectRoot).usable && !refExists(projectRoot, against)) {
+    console.error(c.red("error:") + ` --diff names a ref this repository cannot resolve: "${against}"`);
+    console.error(c.gray("hint: ") + "check the branch or commit name — a ref that resolves to nothing is not an empty diff");
+    return EXIT.USAGE;
+  }
+
+  const { all, sourceFiles } = reviewScope(projectRoot, against);
   console.log(c.bold("Review") + c.gray(against ? ` — vs ${against}` : " — working-tree changes"));
   console.log("");
 
@@ -69,23 +94,39 @@ export async function run(_positional, flags) {
   // 1b. Dependents of touched capabilities (the machine-readable
   //     **Depends on:** header): a spec that builds on something you changed
   //     may silently no longer hold. Advisory — a pointer, not a verdict.
-  const specsDir = path.join(projectRoot, ".doctrina", "specs");
-  if (isDir(specsDir) && touched.size > 0) {
-    for (const cap of readdirSync(specsDir).sort()) {
-      if (touched.has(cap)) continue;
-      const specPath = path.join(specsDir, cap, "spec.md");
-      if (!isFile(specPath)) continue;
-      const deps = parseDependsOn(read(specPath)).filter((d) => touched.has(d));
-      if (deps.length > 0) {
-        notes.push(`capability "${cap}" depends on touched ${deps.map((d) => `"${d}"`).join(", ")} — confirm it still holds (\`doctrina why ${cap}\`)`);
-      }
+  for (const dep of dependentsOf(projectRoot, touched)) {
+    notes.push(`capability "${dep.capability}" depends on touched ${dep.dependsOn.map((d) => `"${d}"`).join(", ")} — confirm it still holds (\`doctrina why ${dep.capability}\`)`);
+  }
+
+  // 1c. How often each touched capability has moved lately, from the archive
+  //     ledger (change 0046). Reported as a NUMBER and never as a verdict:
+  //     frequent change can mean a spec that was drawn badly or a spec that
+  //     is simply where the work is, and nothing here can tell those apart
+  //     (ADR 0005). It is context for the human reading the review, not a
+  //     finding — so it goes in the notes even when the count is high.
+  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);
+    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"`);
     }
   }
 
-  // 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\`)`);
+  // 2. Changed source files that map to no capability at all — code with no
+  //    home in any spec. Reported PER FILE (change 0077): the old form fired
+  //    only when the WHOLE diff matched nothing, so one incidental match —
+  //    any file under `docs/`, which matches the `docs` capability because
+  //    the directory is named after it — silenced the finding for every other
+  //    file in the change. A review of an adapter change reported
+  //    "Capabilities touched: docs" and said nothing about the adapter.
+  const orphans = sourceFiles.filter(
+    (f) => rankCapabilitiesByDiff(projectRoot, [f], { limit: 1 }).length === 0,
+  );
+  if (orphans.length > 0) {
+    const shown = orphans.slice(0, ORPHAN_LIST_LIMIT).map((f) => `\`${f}\``).join(", ");
+    const more = orphans.length > ORPHAN_LIST_LIMIT ? `, and ${orphans.length - ORPHAN_LIST_LIMIT} more` : "";
+    notes.push(`${orphans.length} changed file(s) belong to no capability: ${shown}${more} — claim them with a \`**Source:**\` header on the owning spec, or scaffold the capability they are (\`doctrina spec new <capability>\`)`);
   }
 
   // 3. Coverage — acceptance criteria whose cited proof is missing/skipped.
@@ -133,21 +174,12 @@ export async function run(_positional, flags) {
 }
 
 // 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];
+// tree) and now, split into the full list and the subset outside .doctrina/.
+// The git question itself goes through the one door (lib/git.js).
+function reviewScope(projectRoot, against) {
+  // Against a named ref, untracked files are noise: the question is what this
+  // branch changed, not what is lying around uncommitted.
+  const all = changedFiles(projectRoot, { since: against, untracked: !against }).files;
   const sourceFiles = all.filter((f) => !f.replace(/\\/g, "/").startsWith(".doctrina/"));
   return { all, sourceFiles };
 }

package/src/commands/search.js

@@ -4,6 +4,7 @@ import process from "node:process";
 import { exists, isDir, read, relPath, walk } from "../lib/fs-ops.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { fold } from "../lib/lexicon.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
 
 // Category-aware full-text search across the artifact tree. Answers
@@ -25,7 +26,13 @@ const MAX_MATCHES_PER_FILE = 5;
 export const flags = { boolean: ["json", "archive"], string: [] };
 
 export async function run(positional, flags) {
-  const terms = positional.map((t) => t.toLowerCase()).filter(Boolean);
+  // Folded, not merely lowercased (third audit, finding 8). `search` matched
+  // raw substrings, so an accent decided the answer: `search patrimonio`
+  // found nothing in a spec that says "patrimônio" — and typing without the
+  // accent is the common case, not the rare one. The shared lexicon (ADR
+  // 0040) already folds for `work` and `context --for`; `search` was the
+  // one retrieval surface still deciding on its own.
+  const terms = positional.map((t) => fold(t)).filter(Boolean);
   if (terms.length === 0) {
     console.error(c.red("error:") + " search requires at least one term");
     return 2;
@@ -64,7 +71,7 @@ export async function run(positional, flags) {
       const hits = [];
       for (let i = 0; i < lines.length; i++) {
         const raw = lines[i];
-        const low = raw.toLowerCase();
+        const low = fold(raw);
         if (terms.every((t) => low.includes(t))) {
           hits.push({ line: i + 1, text: raw.trim(), score: lineScore(raw, low, phrase) });
         }
@@ -92,7 +99,14 @@ export async function run(positional, flags) {
 
   if (totalMatches === 0) {
     console.log(c.gray(`no matches for "${positional.join(" ")}"${includeArchive ? "" : " (archive excluded; pass --archive to include it)"}`));
-    return 1;
+    // Not finding is the answer, not a failure. Exit 1 is GATE in the
+    // five-class contract — "fix the work, retry the same command" — and
+    // this command fixes nothing. The `insight` spec says it outright: a
+    // VIEW assembles what is there and never refuses anything, and the
+    // other six listings (spec, decision, skill, contract, templates,
+    // intent) all exit 0 on an empty result. The grep convention is a
+    // shell habit; this CLI declared its own contract (change 0093).
+    return 0;
   }
   console.log(c.gray(`${totalMatches} match${totalMatches === 1 ? "" : "es"} in ${filesWithMatches} file${filesWithMatches === 1 ? "" : "s"}`));
   return 0;
@@ -116,7 +130,7 @@ function lineScore(raw, low, phrase) {
 // A file whose name carries the query is almost always the right one;
 // reward a full filename match more than a partial one.
 function filenameBonus(rel, terms) {
-  const base = rel.toLowerCase();
+  const base = fold(rel);
   if (terms.every((t) => base.includes(t))) return 3;
   return terms.some((t) => base.includes(t)) ? 1 : 0;
 }

package/src/commands/show.js

@@ -6,7 +6,8 @@ import { exists, isDir, isFile, read, relPath } from "../lib/fs-ops.js";
 import { parseAcceptanceCriteria } from "../lib/criteria.js";
 import { suggest } from "../lib/suggest.js";
 import { c } from "../lib/colors.js";
-import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { notADoctrinaProject, EXIT } from "../lib/exit-codes.js";
+import { maskComments } from "../lib/doc-model.js";
 
 // Point reads. An agent that needs ONE requirement re-reads a whole spec —
 // hundreds of lines for a two-line fact. `show` resolves a compact reference
@@ -57,7 +58,7 @@ function showAdr(projectRoot, num) {
   const file = isDir(dir) ? readdirSync(dir).find((f) => f.startsWith(`${num}-`) && f.endsWith(".md")) : null;
   if (!file) {
     console.error(c.red("error:") + ` no ADR ${num} under .doctrina/decisions/`);
-    return 1;
+    return EXIT.USAGE;
   }
   const full = path.join(dir, file);
   console.log(c.gray(`— ${relPath(projectRoot, full)} —`));
@@ -79,7 +80,7 @@ function loadSpec(projectRoot, cap) {
 
 function showSpecHead(projectRoot, cap) {
   const spec = loadSpec(projectRoot, cap);
-  if (!spec) return 1;
+  if (!spec) return EXIT.USAGE;
   const lines = spec.text.split(/\r?\n/);
   const out = [];
   let mode = "head"; // header block -> seek Purpose -> purpose body -> stop
@@ -98,14 +99,14 @@ function showSpecHead(projectRoot, cap) {
 
 function showSpecItem(projectRoot, cap, kind, n) {
   const spec = loadSpec(projectRoot, cap);
-  if (!spec) return 1;
+  if (!spec) return EXIT.USAGE;
 
   if (kind === "C") {
     const criteria = parseAcceptanceCriteria(spec.text);
     const crit = criteria.find((r) => r.n === n);
     if (!crit) {
       console.error(c.red("error:") + ` ${cap} has no acceptance criterion #${n} (it declares ${criteria.length})`);
-      return 1;
+      return EXIT.USAGE;
     }
     console.log(c.gray(`— ${cap}-C${n} · ${relPath(projectRoot, spec.specPath)} · ## Acceptance criteria —`));
     console.log(`${n}. ${crit.body}`);
@@ -119,7 +120,7 @@ function showSpecItem(projectRoot, cap, kind, n) {
   const req = reqs[n - 1];
   if (!req) {
     console.error(c.red("error:") + ` ${cap} has no requirement R${n} (it declares ${reqs.length})`);
-    return 1;
+    return EXIT.USAGE;
   }
   console.log(c.gray(`— ${cap}-R${n} · ${relPath(projectRoot, spec.specPath)} · ${req.section} —`));
   console.log(req.text);
@@ -129,7 +130,13 @@ function showSpecItem(projectRoot, cap, kind, n) {
 // Top-level bullets of the "## Requirements (EARS)" section, in file order,
 // each with its `### <grammar>` sub-section name and continuation lines.
 export function parseRequirements(text) {
-  const lines = text.split(/\r?\n/);
+  // The scaffolded spec writes the five-line EARS legend as bullets inside
+  // an HTML comment under `## Requirements (EARS)`. Counted as content, the
+  // legend became R1..R5 and the capability's first real requirement was R6
+  // — on every spec `doctrina spec new` had ever created. Comments are
+  // blanked by position (same offsets, same line count), so the numbering
+  // below is over authored bullets only.
+  const lines = maskComments(text).split(/\r?\n/);
   const out = [];
   let inSection = false;
   let sub = "";
@@ -175,6 +182,14 @@ Point-read one artifact fragment instead of a whole file:
   doctrina show 0007       ADR 0007 (the whole decision)
   doctrina show cli        the spec's header block + Purpose only
 
-R-refs are positional (they shift when a requirement is inserted above);
-C-refs use the criteria's own numbers. Read-only.
+R-refs are positional across the WHOLE spec, in file order, and they shift
+when a requirement is inserted above. C-refs use the criteria's own numbers.
+Both count authored content only — a bullet inside an HTML comment (the
+scaffold's EARS legend, for one) is annotation and is never numbered.
+
+A spec delta's replace-requirement <section> <n> numbers differently, and
+on purpose: it counts WITHIN one "### <section>", so the number stays put
+when another section grows. doctrina show <cap>-RN prints the section it
+landed in, which is what turns an R-ref into the delta's pair of coordinates.
+Read-only.
 `;

package/src/commands/skill.js

@@ -2,7 +2,6 @@
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
-import { spawnSync } from "node:child_process";
 import { exists, isDir, isFile, 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";
@@ -11,6 +10,10 @@ import { flagBool, flagString, flagGivenWithoutValue } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 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, fold, skillSlug } from "../lib/lexicon.js";
+import { artifactNameError } from "../lib/names.js";
 
 const SUBCOMMANDS = ["new", "list", "sync", "suggest"];
 
@@ -46,15 +49,7 @@ export async function run(positional, flags) {
 // --write it scaffolds a stub per candidate, pre-seeded from the source so the
 // human/agent only fills the body. Both sources are a pattern match — a hint,
 // never a decision (ADR 0005); skills are still authored, never generated.
-const FIX_SHAPED = /(?:^|-)(fix|bug|hotfix|patch|parse|parsing|tolerate|workaround|race|deadlock|flaky|retry|escape|sanitize|sanitise)(?:-|$)/;
 
-// The same idea applied to a commit subject. Narrower than FIX_SHAPED on
-// purpose: a deliberate folder slug tolerates more noise than a free-form
-// subject line. Matches conventional fix-type prefixes (fix:, fix(scope):,
-// bug:, hotfix:, patch:, and the free-form "Fix the…") plus the strongly
-// fix-flavoured debugging keywords — never feat:/refactor:/docs:/chore:.
-const FIX_SHAPED_SUBJECT =
-  /^(?:fix|bug|hotfix|patch)\b|\b(?:tolerate|workaround|deadlock|flaky|race condition|retry|sanitiz|sanitis)/i;
 
 // How far back the git source looks when --since is not given, and how many
 // candidates we print before collapsing the rest into a "+N more" line.
@@ -109,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);
   }
@@ -130,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);
@@ -349,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;
 }
 
@@ -379,8 +374,8 @@ function gitFixCommits(projectRoot, { since, limit }) {
   if (since) args.push(`${since}..HEAD`);
   else args.push("-n", String(limit));
 
-  const r = spawnSync("git", args, { cwd: projectRoot, encoding: "utf8" });
-  if (r.error || r.status !== 0 || !r.stdout) return [];
+  const r = git(projectRoot, args);
+  if (r.state !== GIT_STATE.OK || !r.stdout) return [];
 
   /** @type {SkillCandidate[]} */
   const out = [];
@@ -405,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
@@ -449,8 +437,9 @@ function firstWhyLine(proposalText) {
 
 function skillNew(args, flags) {
   const name = args[0];
-  if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) {
-    console.error(c.red("error:") + " skill name must be lowercase letters, digits, or hyphens (e.g. \"db-migration\")");
+  const nameError = artifactNameError(name, "skill name");
+  if (nameError) {
+    console.error(c.red("error:") + ` ${nameError} (e.g. "db-migration")`);
     return 2;
   }
   const force = flagBool(flags, "force", false);
@@ -486,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;
 }
 
@@ -512,6 +501,13 @@ function skillSync() {
       console.log(c.yellow("skip   ") + ` ${id} (no description frontmatter)`);
       continue;
     }
+    // A description still in the template's `<...>` form is not "up to
+    // date" (change 0111): it is a file nobody wrote yet, and mirroring it
+    // into the index is what put the placeholder in every context pack.
+    if (/^<[^<>]*>$/.test(desc.trim())) {
+      console.log(c.yellow("scaffold") + ` ${id} — description is still the scaffold's placeholder; write description/when, then sync`);
+      continue;
+    }
     const entry = (index.artifacts.skills ?? []).find((s) => s.id === id);
     if (!entry) {
       idx.addSkill(index, {
@@ -568,15 +564,6 @@ function skillList() {
   return 0;
 }
 
-function parseFrontmatter(text, key) {
-  // Match frontmatter blocks bounded by `---` lines at start of file.
-  const fmMatch = text.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
-  if (!fmMatch) return null;
-  const block = fmMatch[1];
-  const lineRe = new RegExp(`^${key}\\s*:\\s*(.+)$`, "m");
-  const m = block.match(lineRe);
-  return m ? m[1].trim() : null;
-}
 
 function ensureDoctrinaProject(projectRoot) {
   if (!exists(path.join(projectRoot, ".doctrina"))) {
@@ -618,6 +605,3 @@ Skills are written by humans, not generated. See docs/en/skills.md
 for the design rationale and the distinction from specs / AGENTS.md /
 the rejected memory/ folder.
 `;
-
-// Re-export the frontmatter parser so validate.js can reuse it.
-export { parseFrontmatter };

package/src/commands/spec.js

@@ -11,7 +11,9 @@ import { today } from "../lib/dates.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
-import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { notADoctrinaProject, EXIT } from "../lib/exit-codes.js";
+import { derivedImplementations } from "../lib/coverage-model.js";
+import { artifactNameError } from "../lib/names.js";
 
 const SUBCOMMANDS = ["new", "list", "set"];
 
@@ -34,8 +36,9 @@ export async function run(positional, flags) {
   if (sub === "set") return specSet(positional.slice(1), flags);
 
   const capability = positional[1];
-  if (!capability || !/^[a-z][a-z0-9-]*$/.test(capability)) {
-    console.error(c.red("error:") + " capability must be lowercase letters, digits, or hyphens (e.g. \"core\", \"templates\").");
+  const nameError = artifactNameError(capability, "capability");
+  if (nameError) {
+    console.error(c.red("error:") + ` ${nameError} (e.g. "core", "templates")`);
     return 2;
   }
 
@@ -135,7 +138,7 @@ function specSet(args, flags) {
   const specPath = path.join(projectRoot, ".doctrina", "specs", capability, "spec.md");
   if (!isFile(specPath)) {
     console.error(c.red("error:") + ` no spec at ${relPath(projectRoot, specPath)} (create it with \`doctrina spec new ${capability}\`)`);
-    return 1;
+    return EXIT.USAGE;
   }
 
   const impl = flagString(flags, "implementation");
@@ -152,32 +155,56 @@ 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
   // none (a failed op leaves the spec untouched, like `change apply`).
   if (status !== undefined) apply(setHeader(text, "Status", status));
-  if (impl !== undefined) apply(setHeader(text, "Implementation", impl));
+  if (impl !== undefined) {
+    // `--implementation auto` reads the value off the coverage arithmetic
+    // instead of the author's memory (audit finding F10): coverage already
+    // knows how many of this spec's criteria cite proof that resolves, and
+    // that is the definition of "verified". A spec with no acceptance
+    // criteria has nothing to derive from, so `auto` refuses rather than
+    // guessing — the spec is left untouched, like any other failed op.
+    if (String(impl).trim().toLowerCase() === "auto") {
+      const derivedValue = derivedImplementations(projectRoot, { only: new Set([capability]) })
+        .get(capability)?.derived;
+      if (!derivedValue) {
+        errors.push({ msg: `--implementation auto needs acceptance criteria to derive from; ${capability} declares none`, argument: false });
+      } else {
+        apply(setHeader(text, "Implementation", derivedValue));
+      }
+    } else {
+      apply(setHeader(text, "Implementation", impl));
+    }
+  }
   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).