doctrina-cli 0.16.0 → 0.18.0

package/src/lib/gates.js

@@ -24,10 +24,10 @@ import { appendLedgerLine, forcedLine } from "./ledger.js";
 // A gate is a named precondition returning human-readable blockers.
 export const GATES = {
   // Structural validity: the change's own files parse and point at real
-  // targets. The same checks `doctrina analyze` reports.
+  // targets. The same checks `doctrina change check` reports first.
   structure: {
     label: "structure",
-    rerun: (id) => `doctrina analyze ${id}`,
+    rerun: (id) => `doctrina change check ${id}`,
     blockers(projectRoot, changeDir) {
       return collectAnalysis(projectRoot, changeDir)
         .filter((r) => r.kind === "fail")
@@ -49,7 +49,7 @@ export const GATES = {
   // history recorded six hollow proposals reaching the archive.
   integrity: {
     label: "integrity",
-    rerun: (id) => `doctrina analyze ${id}`,
+    rerun: (id) => `doctrina change check ${id}`,
     blockers(projectRoot, changeDir) {
       return collectAnalysis(projectRoot, changeDir)
         .filter((r) => r.kind === "fail" && r.scope !== "pre-apply")
@@ -58,8 +58,9 @@ export const GATES = {
   },
 
   // Verification: the work is claimed complete. Every checkbox in
-  // tasks.md (closing steps included) and in the proposal's
-  // "## Verification" section.
+  // tasks.md and in the proposal's "## Verification" section — except a
+  // legacy "## Closing steps" list, which names what the close itself does
+  // (change 0195).
   verification: {
     label: "verification",
     rerun: (id) => `doctrina change tick ${id}`,
@@ -72,7 +73,7 @@ export const GATES = {
       const tasksPath = path.join(changeDir, "tasks.md");
       if (isFile(tasksPath)) {
         const n = countUnchecked(read(tasksPath));
-        if (n > 0) out.push(`${n} unchecked task${n === 1 ? "" : "s"} in tasks.md (closing steps count)`);
+        if (n > 0) out.push(`${n} unchecked task${n === 1 ? "" : "s"} in tasks.md`);
       }
       const proposalPath = path.join(changeDir, "proposal.md");
       if (isFile(proposalPath)) {
@@ -158,7 +159,11 @@ export const SEQUENCES = {
   // The closing sequence. `close` runs these in order, in-process where it
   // can, stopping at the first blocking failure with the step's rerun line.
   close: [
-    { id: "analyze", label: "analyze", level: "blocking", argv: ["analyze", "<id>"] },
+    // The structural pre-flight. Its id stays "analyze" (the module it runs
+    // in-process), but a reader sees "structure", the gate it holds: change
+    // 0182 deprecated `doctrina analyze`, and the command a person reruns is
+    // `change check`, which reports the same checks first (change 0183).
+    { id: "analyze", label: "structure", level: "blocking", argv: ["analyze", "<id>"], rerun: "doctrina change check <id>" },
     { id: "adr-checkpoint", label: "ADR checkpoint (advisory)", level: "advisory", argv: ["decision", "list"] },
     // Conformance review (audit finding F3). It is the richest analysis the
     // project has — capabilities whose code moved while their spec did not,
@@ -179,6 +184,20 @@ export const SEQUENCES = {
     { id: "trace", label: "trace", level: "advisory", argv: ["trace"] },
     { id: "docs", label: "docs", level: "forceable", argv: null, rerun: "document the change, then rerun" },
     { id: "archive", label: "archive", level: "blocking", argv: ["change", "archive", "<id>"] },
+    // AFTER the archive, because the archive is the last step that WRITES the
+    // index, and a gate placed before the step it guards cannot guard it.
+    //
+    // The drift check already ran, inside `verify` — and that is exactly why
+    // it missed: `verify` is five steps earlier, so it certified an index the
+    // archive had not yet rewritten. Change 0138 closed green on a tree whose
+    // index had drifted, the commit shipped, and all six test legs of CI went
+    // red on the next push. The close was not wrong about what it checked; it
+    // checked before the damage.
+    //
+    // `validate` cannot stand in for it: drift of that kind is only visible by
+    // rebuilding the index and comparing, which validate deliberately does not
+    // do.
+    { id: "index-drift", label: "index drift", level: "blocking", argv: ["index", "rebuild", "--check"] },
     { id: "validate", label: "validate", level: "blocking", argv: ["validate"] },
   ],
 
@@ -191,7 +210,7 @@ export const SEQUENCES = {
     { id: "coverage", label: "coverage", level: "advisory", argv: ["coverage"] },
     { id: "trace", label: "trace", level: "advisory", argv: ["trace"] },
     { id: "clean-checkout", label: "clean-checkout", level: "blocking", argv: ["verify", "--clean"] },
-    { id: "templates", label: "templates", level: "advisory", argv: ["templates", "check"] },
+    { id: "templates", label: "templates", level: "advisory", argv: ["upgrade"] },
     { id: "runtime", label: "runtime", level: "blocking", argv: ["contract", "check"] },
     { id: "local-env", label: "local .env", level: "blocking", argv: null, rerun: "doctrina doctor --env", flag: "env" },
     { id: "verify-config", label: "verify config", level: "blocking", argv: ["verify", "--init"] },
@@ -265,6 +284,31 @@ export function sequence(name) {
   return steps;
 }
 
+/**
+ * The sequence as a reader sees it: each step's label, in order, with the
+ * forceable ones marked the way the advisory ones already are in their own
+ * labels.
+ *
+ * Every surface that SHOWS the sequence renders it from here. Four copies of
+ * the close sequence were written out by hand — `close --help`, two adapter
+ * command files, and the flow page in both languages — and all four had gone
+ * stale, each to a different list: one named four steps of thirteen, another
+ * eleven. A sequence a reader can count is a sequence a reader will trust, so
+ * it has exactly one author.
+ */
+export function sequenceLabels(name) {
+  // The marker comes from `level`, never from the label text: labels had
+  // already drifted among themselves — `trace` is advisory and did not say so
+  // while `ADR checkpoint` did — so any marker already written in is stripped
+  // and re-derived. One rule, applied to every step.
+  return sequence(name).map((s) => {
+    const base = s.label.replace(/\s*\((?:advisory|forceable)\)\s*$/, "");
+    if (s.level === "advisory") return `${base} (advisory)`;
+    if (s.level === "forceable") return `${base} (forceable)`;
+    return base;
+  });
+}
+
 /**
  * The command that runs one step on its own — what a surface prints when it
  * tells the operator how to clear the gate. Derived from `argv` so the
@@ -272,7 +316,7 @@ export function sequence(name) {
  * not a single command.
  */
 export function stepRerun(step, changeId = "<id>") {
-  if (step.rerun) return step.rerun;
+  if (step.rerun) return step.rerun.replace(/<id>/g, changeId);
   if (!step.argv) return `doctrina ${step.id}`;
   return `doctrina ${step.argv.map((a) => (a === "<id>" ? changeId : a)).join(" ")}`;
 }

package/src/lib/git.js

@@ -1,5 +1,10 @@
 // @ts-check
 import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, rmSync } from "node:fs";
+import { createHash } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
 
 // One place that knows how to ask git a question and how to interpret not
 // getting an answer (audit item C8).
@@ -32,8 +37,13 @@ export const GIT_STATE = Object.freeze({
 
 // Run a git command. Never throws. Returns
 // { state, stdout, lines, stderr, code }.
-export function git(cwd, args) {
-  const r = spawnSync("git", args, { cwd, encoding: "utf8" });
+/**
+ * @param {string} cwd
+ * @param {string[]} args
+ * @param {{ env?: Record<string, string> }} [opts]
+ */
+export function git(cwd, args, { env } = {}) {
+  const r = spawnSync("git", args, { cwd, encoding: "utf8", ...(env ? { env: { ...process.env, ...env } } : {}) });
   if (r.error) {
     // ENOENT here means the binary is missing, not that the command failed.
     return { state: GIT_STATE.ABSENT, stdout: "", lines: [], stderr: String(r.error.message ?? ""), code: null };
@@ -227,3 +237,50 @@ export function lastTagDate(cwd) {
   const date = tags[0] ?? "";
   return /^\d{4}-\d{2}-\d{2}$/.test(date) ? date : null;
 }
+
+/**
+ * A content fingerprint of the working tree under `cwd` — tracked AND
+ * untracked files, .gitignore respected, uncommitted edits included — with
+ * the top-level entries named in `exclude` left out (change 0203). Null when
+ * git cannot answer.
+ *
+ * Built from git's own object model rather than by reading files: the real
+ * index is copied to a scratch one, `git add -A` stages the whole tree into
+ * the copy (reusing the stat cache, so only changed files are hashed), and
+ * `git write-tree` names the result. The real index, HEAD and the working
+ * tree are never touched; the only side effect is loose objects for changed
+ * files, which `git gc` reclaims.
+ *
+ * @param {string} cwd
+ * @param {{ exclude?: string[] }} [opts]
+ * @returns {string | null}
+ */
+export function worktreeFingerprint(cwd, { exclude = [] } = {}) {
+  const top = git(cwd, ["rev-parse", "--show-toplevel"]);
+  const dir = git(cwd, ["rev-parse", "--absolute-git-dir"]);
+  if (top.state !== GIT_STATE.OK || dir.state !== GIT_STATE.OK) return null;
+  const root = top.stdout.trim();
+  const scratch = path.join(os.tmpdir(), `doctrina-fingerprint-${process.pid}-${Date.now()}`);
+  try {
+    const real = path.join(dir.stdout.trim(), "index");
+    if (existsSync(real)) copyFileSync(real, scratch);
+    const env = { GIT_INDEX_FILE: scratch };
+    if (git(root, ["add", "-A", "--", "."], { env }).state !== GIT_STATE.OK) return null;
+    const tree = git(root, ["write-tree"], { env });
+    if (tree.state !== GIT_STATE.OK) return null;
+    // Asked of git, never computed with path.relative: on macOS the tmpdir
+    // is `/var/…`, a symlink to `/private/var/…`, and git answers with the
+    // resolved toplevel — the relative path between the two spellings is
+    // `../..`, which names nothing in the tree (the 0.18 macOS CI run).
+    const prefixed = git(cwd, ["rev-parse", "--show-prefix"]);
+    if (prefixed.state !== GIT_STATE.OK) return null;
+    const prefix = prefixed.stdout.trim().replace(/\/$/, "");
+    const listing = git(root, ["ls-tree", prefix ? `${tree.stdout.trim()}:${prefix}` : tree.stdout.trim()]);
+    if (listing.state !== GIT_STATE.OK) return null;
+    const skip = new Set(exclude);
+    const kept = listing.lines.filter((l) => !skip.has(l.split("\t")[1]));
+    return createHash("sha256").update(kept.join("\n")).digest("hex");
+  } finally {
+    rmSync(scratch, { force: true });
+  }
+}

package/src/lib/index-json.js

@@ -64,10 +64,45 @@ export function blank(projectName, date) {
   };
 }
 
+// INSERT WHERE A REBUILD WOULD HAVE PUT IT.
+//
+// Every category here is written twice: incrementally, by the command that
+// creates the artifact, and wholesale by `index rebuild`, which walks the
+// directory — `readdirSync(...).sort()` — and writes what it finds, in that
+// order. The two agreed only by luck: appending matches a sorted walk exactly
+// when the new entry happens to sort last.
+//
+// It usually does, which is why this survived. `doctrina spec new alpha` after
+// `spec new zebra` does not, and neither does closing change 0138 after 0139 —
+// that one shipped, and turned all six test legs of CI red on a tree whose own
+// `close` had just reported green.
+//
+// `validate` cannot see it: drift of this kind is only visible by rebuilding
+// and comparing, which is `index rebuild --check`, a different gate. So the
+// tree looked healthy from inside and failed from outside.
+//
+// Each entry's `path` embeds the on-disk name the rebuild sorts by, and the
+// parent directory is constant within a category — so ordering by `path`
+// reproduces the walk exactly, without this module having to know how any
+// category is laid out.
+// The comparison has to be the SAME one: `readdirSync(dir).sort()` takes the
+// default comparator, which orders by UTF-16 code unit, and `localeCompare`
+// does not — it ignores or reweights punctuation, so `0100-a` and `0100_a`
+// can come out in the opposite order. Matching the walk means comparing the
+// way the walk compares.
+function insertInRebuildOrder(list, entry) {
+  list.push(entry);
+  list.sort((a, b) => {
+    const x = String(a.path ?? ""), y = String(b.path ?? "");
+    return x < y ? -1 : x > y ? 1 : 0;
+  });
+  return list;
+}
+
 export function addSkill(index, entry) {
   if (!index.artifacts.skills) index.artifacts.skills = [];
   if (!index.artifacts.skills.some((s) => s.id === entry.id)) {
-    index.artifacts.skills.push(entry);
+    insertInRebuildOrder(index.artifacts.skills, entry);
   }
   return index;
 }
@@ -75,7 +110,7 @@ export function addSkill(index, entry) {
 export function addContract(index, entry) {
   if (!index.artifacts.contracts) index.artifacts.contracts = [];
   if (!index.artifacts.contracts.some((s) => s.id === entry.id)) {
-    index.artifacts.contracts.push(entry);
+    insertInRebuildOrder(index.artifacts.contracts, entry);
   }
   return index;
 }
@@ -87,14 +122,14 @@ export function touch(index, date) {
 
 export function addSpec(index, entry) {
   if (!index.artifacts.specs.some((s) => s.id === entry.id)) {
-    index.artifacts.specs.push(entry);
+    insertInRebuildOrder(index.artifacts.specs, entry);
   }
   return index;
 }
 
 export function addDecision(index, entry) {
   if (!index.artifacts.decisions.some((d) => d.id === entry.id)) {
-    index.artifacts.decisions.push(entry);
+    insertInRebuildOrder(index.artifacts.decisions, entry);
   }
   return index;
 }
@@ -110,7 +145,7 @@ export function updateDecision(index, id, mutator) {
 export function moveChangeToArchive(index, id, archiveEntry) {
   index.artifacts.changes = index.artifacts.changes.filter((c) => c.id !== id);
   if (!index.artifacts.changes_archive.some((c) => c.id === id)) {
-    index.artifacts.changes_archive.push(archiveEntry);
+    insertInRebuildOrder(index.artifacts.changes_archive, archiveEntry);
   }
   return index;
 }

package/src/lib/intake-model.js

@@ -10,6 +10,8 @@ import { exists, isFile, read, relPath, write } from "./fs-ops.js";
 import { assessBrief } from "./clarity.js";
 import { c } from "./colors.js";
 import { printPlaybookTemplate } from "./playbook.js";
+import { getHeader, setHeader } from "./doc-model.js";
+import { stateWord } from "./spec-ops.js";
 // Clarification gate (review Topic A). A description too thin to spec from is
 // the moment to ask the user, not to let the agent invent requirements. Prints
 // the specific gaps before the bootstrap playbook; advisory, never blocking —
@@ -39,6 +41,30 @@ export function looksLikePath(value) {
   return false;
 }
 
+// What `init` tells a person to do next (change 0173). The first run used to
+// contradict itself three ways: `init` said "edit AGENTS.md and product.md",
+// `next` asked for the description again as an intake, and AGENTS.md said the
+// agent runs the commands while the human stays passive. One answer now,
+// the same one `next` and AGENTS.md give.
+//
+// `intakeFrom` is "tty" when the description was typed at init's question
+// (it is stored as the intake), or null when init got no intake at all.
+export function nextStepAfterInit(intakeFrom) {
+  if (intakeFrom === "tty") {
+    return [
+      "Next: open your AI agent in this repository and tell it:",
+      "    read AGENTS.md and run doctrina next",
+      "It turns your description into product.md and specs; you review and approve.",
+    ];
+  }
+  return [
+    "Next: give your AI agent the whole project description. It runs",
+    "    doctrina intake --text \"<description>\"",
+    "and turns it into product.md and specs (AGENTS.md, \"Working from intent\");",
+    "for an existing codebase, `doctrina work --from-diff` backfills them from the code.",
+  ];
+}
+
 export function warnIfThinIntake(body) {
   const assessment = assessBrief(body, { kind: "intake" });
   if (!assessment.thin) return;
@@ -47,8 +73,51 @@ export function warnIfThinIntake(body) {
   console.log("");
 }
 
+// THE INTAKE'S STATUS IS A CONTROL VALUE, SO IT GETS AN ENUM AND AN OWNER.
+//
+// `next` branches on it: pending means the bootstrap is unfinished, and every
+// other artifact's status in this framework is both written by a command and
+// checked against an enum — `spec set` refuses "Status: nonsense", and
+// `validate` calls it an error. The intake was the one header the playbook
+// told an agent to edit BY HAND, and the one nothing read back.
+//
+// So any token that was not exactly "converted" meant pending, in silence:
+// "convertido" typed in a Portuguese project, "done", or an empty value left
+// by a botched edit. `validate` exited 0 on all of them and `next` went on
+// asking for a bootstrap that had already happened.
+export const INTAKE_STATUSES = ["pending", "converted"];
+
+/** The intake's status word, note stripped and folded. Defaults to pending. */
+export function intakeStatus(text) {
+  const raw = getHeader(String(text ?? ""), "Status");
+  if (raw === null) return "pending";
+  return stateWord(raw) || "";
+}
+
+/** null when the intake's status is a declared value; otherwise the error. */
+export function intakeStatusError(text) {
+  const word = intakeStatus(text);
+  if (INTAKE_STATUSES.includes(word)) return null;
+  const got = getHeader(String(text ?? ""), "Status");
+  return `Status must be one of ${INTAKE_STATUSES.join("|")} `
+    + `(got "${String(got ?? "").trim()}") — every other value reads as pending, in silence`;
+}
+
+/**
+ * Flip the stored intake to `converted`. Returns the path written, or null
+ * when there is no intake (or no Status header) to flip.
+ */
+export function markIntakeConverted(projectRoot) {
+  const intakePath = path.join(projectRoot, ".doctrina", "intake.md");
+  if (!exists(intakePath)) return null;
+  const next = setHeader(read(intakePath), "Status", "converted");
+  if (next === null) return null;
+  write(intakePath, next, { force: true });
+  return intakePath;
+}
+
 // Shared with `init --intake`. Writes the intake verbatim under a small
-// status header; the agent flips Status to converted at the end of the
+// status header; `doctrina intake --converted` flips it at the end of the
 // playbook, which is how `next` knows the bootstrap is done.
 export function writeIntakeFile(projectRoot, { body, source, projectName, date, force = false }) {
   const intakePath = path.join(projectRoot, ".doctrina", "intake.md");
@@ -61,7 +130,7 @@ export function writeIntakeFile(projectRoot, { body, source, projectName, date,
     "",
     "<!-- Raw project intent, stored verbatim. The bootstrap playbook",
     "     (doctrina intake) converts it into product.md and capability",
-    "     specs, then flips Status to converted. After conversion the",
+    "     specs. Close it with `doctrina intake --converted`; after that the",
     "     specs are the only source of truth; never edit this file to",
     "     change requirements. -->",
     "",

package/src/lib/lexicon.js

@@ -183,9 +183,46 @@ export const CONFIDENT_MARGIN = 10;
 // content words, no interpretation (ADR 0005).
 export const SLUG_WORDS = 4;
 
+// A number is content in an id (change 0191). `terms` serves retrieval, where
+// a bare "24" matches everything, so it keeps only words that start with a
+// letter — and the slug inherited that: "cortar a 0.17.0" became `cortar`
+// and "migrar para Node 24" `migrar-node`. The slug reads its own tokens: a
+// version or a number is one word, its dots folded into hyphens.
+function slugTerms(prompt) {
+  const words = (fold(String(prompt ?? "")).match(/[a-z0-9][a-z0-9.-]*/g) ?? [])
+    .map((w) => w.replace(/[.-]+$/g, "").replace(/\./g, "-"))
+    .filter((w) => (w.length > 1 || /^\d$/.test(w)) && !STOPWORDS.has(w));
+  return [...new Set(words)];
+}
+
 export function slugFromPrompt(prompt, { words = SLUG_WORDS } = {}) {
-  const content = terms(prompt).slice(0, words);
+  const content = slugTerms(prompt).slice(0, words);
   const slug = slugify(content.join(" "));
   // A prompt of nothing but stopwords ("do it now") still needs an id.
   return slug || slugify(prompt).split("-").slice(0, words).join("-");
 }
+
+// A SKILL SLUG IS FOLDED, NOT SHREDDED.
+//
+// `skill suggest` names a lesson from text a person wrote — a change id, a
+// commit subject, the seed tokens of an error. That name became a filename,
+// and it was built by stripping everything outside `[a-z0-9-]` from the raw
+// text. On Portuguese input the strip is destructive rather than normalising:
+// every capital is DELETED and every accented letter becomes a hyphen, so
+// "Corrigir A Validação" came out "orrigir-alida-o" and a real run wrote
+// `.doctrina/skills/o-modelo-de-documento-n-o-l-cabe-alho-de.md`.
+//
+// The tell was already in this module: SLUG_NOISE lists "nao", a token the
+// old pipeline could never produce. So the slug goes through `slugify`, the
+// same fold every other slug in the tree uses.
+//
+// The leading numeric run goes with it. The source is often a change id
+// ("0049-fix-tela-preta"), the digits identify nothing about the lesson, and
+// the skills spec requires a filename slug to start with a letter.
+export const SKILL_SLUG_MAX = 40;
+
+export function skillSlug(text, { max = SKILL_SLUG_MAX } = {}) {
+  const slug = slugify(text).replace(/^\d+(?:-|$)/, "");
+  const capped = slug.length > max ? slug.slice(0, max).replace(/-+$/g, "") : slug;
+  return capped || "lesson";
+}

package/src/lib/metrics-model.js

@@ -83,6 +83,36 @@ export function round(x) {
 }
 
 
+const WINDOW_UNIT = /^(\d+)\s+(second|minute|hour|day|week|month|year)s?\s+ago$/i;
+
+/**
+ * The git `--since` value for a `--since` flag, or null when the flag is not
+ * a window this can check.
+ *
+ * git never refuses a date: "abc" parses as NOW (an empty window, reported
+ * as "nothing to measure") and "2026-13-45" as some other day. Handing it
+ * free text turned a typo into a confident, wrong answer, so only the forms
+ * whose meaning is certain pass: a day count, a calendar date
+ * (YYYY-MM-DD), or "<n> <unit>s ago".
+ *
+ * @param {string} raw
+ * @returns {string | null}
+ */
+export function sinceWindow(raw) {
+  const s = String(raw ?? "").trim();
+  if (/^\d+$/.test(s)) return Number(s) > 0 ? `${Number(s)} days ago` : null;
+  const date = s.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (date) {
+    const [y, m, d] = date.slice(1).map(Number);
+    const t = new Date(Date.UTC(y, m - 1, d));
+    const real = t.getUTCFullYear() === y && t.getUTCMonth() === m - 1 && t.getUTCDate() === d;
+    return real ? s : null;
+  }
+  const rel = s.match(WINDOW_UNIT);
+  if (rel) return Number(rel[1]) > 0 ? s.replace(/\s+/g, " ") : null;
+  return null;
+}
+
 /**
  * A snapshot for a window, or null when there is no history to read.
  *

package/src/lib/playbook.js

@@ -94,4 +94,4 @@ export function printPlaybookTemplate(projectRoot, name, tokens = {}) {
 }
 
 /** The playbooks the CLI ships and `templates check` expects to resolve. */
-export const PLAYBOOKS = ["work", "chore", "bootstrap"];
+export const PLAYBOOKS = ["work", "chore", "bootstrap", "consolidate"];

package/src/lib/project.js

@@ -1,7 +1,9 @@
 // @ts-check
 import path from "node:path";
 import { exists } from "./fs-ops.js";
-import { notADoctrinaProject } from "./exit-codes.js";
+import { EXIT, notADoctrinaProject } from "./exit-codes.js";
+import { c } from "./colors.js";
+import { load } from "./index-json.js";
 
 // The one precondition every command shares: this is a Doctrina project.
 // Six command modules carried an identical private copy of it; a lib
@@ -13,6 +15,31 @@ export function ensureDoctrinaProject(projectRoot) {
   }
 }
 
+/**
+ * What this project is CALLED — the name it recorded at `init`, with the
+ * directory as the fallback for a tree that has none.
+ *
+ * Four modules asked this privately and one of them answered differently:
+ * `adapter` read the directory and never the record, so every adapter file
+ * installed after `doctrina init --project-name "Minha Carteira"` greeted the
+ * agent with the folder's name instead. `init --agent`, holding the name it
+ * had just been given, got it right — the same templates, two callers, two
+ * answers.
+ *
+ * Pass `index` when you already hold it; the helper then reads nothing.
+ *
+ * @param {string} projectRoot
+ * @param {any} [index] an already-loaded index.json, when the caller has one
+ */
+export function projectName(projectRoot, index) {
+  if (index !== undefined) return index?.project ?? path.basename(projectRoot);
+  try {
+    return load(projectRoot)?.project ?? path.basename(projectRoot);
+  } catch {
+    return path.basename(projectRoot);
+  }
+}
+
 // The grammar a change id obeys: lowercase letters, digits and hyphens,
 // opening on a letter or a digit — `0042-short-slug` is the shape `work`
 // derives. Deliberately NOT the capability grammar, which additionally
@@ -31,6 +58,27 @@ export function isChangeId(id) {
   return typeof id === "string" && CHANGE_ID.test(id);
 }
 
+// A reference to an EXISTING change is looser than the id `change new`
+// accepts — a project may hold a change named before that grammar — but it
+// is always a folder NAME under .doctrina/changes/, never a path. Nothing
+// checked that: `change archive ../../victim --force` moved the project's
+// own `victim/` directory into the archive and wrote it into the ledger and
+// the index (change 0196). `archive` is the archive's own folder, not a
+// change.
+export function isChangeRef(id) {
+  return typeof id === "string" && id.length > 0 && id !== "." && id !== ".."
+    && id !== "archive" && !/[\/\\\0]/.test(id);
+}
+
+// The one refusal every command that takes a change reference prints: the
+// USAGE class, before anything is resolved against the filesystem.
+export function refuseChangeRef(id) {
+  if (isChangeRef(id)) return null;
+  console.error(c.red("error:") + ` "${id}" is not a change — a change is named by its folder under .doctrina/changes/, never by a path`);
+  console.error(c.gray("hint: ") + "open changes: `doctrina next`");
+  return EXIT.USAGE;
+}
+
 /**
  * Resolve `segments` under `projectRoot` and refuse anything that escapes it.
  *

package/src/lib/runtime.js

@@ -631,6 +631,12 @@ export function expandBraces(glob) {
 // `{a,b}` alternates. Enough for the "where do my selectors live" and "which
 // code is mine" declarations, with no dependency and no surprises.
 export function globToRegExp(glob) {
+  // A pattern ending in `/` names a DIRECTORY, and a directory claims what
+  // is under it (change 0199). Compiled as written it matched only the
+  // literal path `src/health/` — which no file has — so the most natural way
+  // to declare a module's ownership claimed nothing, and `review` reported
+  // every file in it as ownerless.
+  if (/\/$/.test(String(glob))) glob = `${glob}**`;
   // Always compile the EXPANSION, never the original. Using it only when it
   // produced more than one alternative left `src/{a}.js` compiling with its
   // braces as literal characters, so a one-element group matched nothing