doctrina-cli 0.16.0 → 0.17.0

package/src/lib/commands.js

@@ -16,7 +16,7 @@ export const COMMAND_NAMES = [
   // authoring
   "spec", "change", "contract", "decision", "skill", "intent", "adapter",
   // read / orient
-  "prime", "context", "show", "search", "status", "next", "why", "handoff", "constitution",
+  "prime", "context", "show", "search", "status", "next", "why", "handoff",
   // gates
   "analyze", "clarify", "validate", "coverage", "trace", "review", "verify", "close", "doctor",
   // maintenance
@@ -46,7 +46,6 @@ export const OPERATIONS = [
   ["change archive", "Archive an applied change (batch ids ok)"],
   ["change check", "Pre-close dry-run: everything close would refuse, listed first"],
   ["change tick", "List/tick the unchecked boxes (tasks + verification; --all)"],
-  ["change diff", "Preview spec deltas (line diff for MODIFIED)"],
   ["change abandon", "Discard an open change cleanly (recorded in the ledger)"],
   ["contract new", "Own the integration surface (ports, env, interfaces)"],
   ["contract list", "List contracts with status and last-updated date"],
@@ -82,7 +81,6 @@ export const OPERATIONS = [
   ["status", "One-glance project health dashboard"],
   ["why", "Explain provenance: a capability's chain, or an anchor's (SC1)"],
   ["handoff", "Markdown handoff note: open work, task state, resume command"],
-  ["constitution", "Print the standing rules: accepted ADRs + product non-goals"],
   ["templates list", "List the templates shipped by the installed CLI"],
   ["templates check", "Compare the project against the recommended template shape"],
   ["templates update", "Additive fixer for check findings (preview; --write applies)"],
@@ -126,13 +124,12 @@ export const COMMAND_META = {
   show:         { moment: "Orient",     when: "you need one requirement, criterion, or ADR, not a file", purpose: "point-read a single artifact by reference" },
   search:       { moment: "Orient",     when: "you do not know which artifact mentions a term", purpose: "search the artifact tree, grouped by category" },
   why:          { moment: "Orient",     when: "you need to justify or trace a capability's existence", purpose: "provenance: intent, proof, ADRs, and history" },
-  constitution: { moment: "Orient",     when: "you need the standing rules before deciding something", purpose: "accepted ADRs and product non-goals" },
   handoff:      { moment: "Orient",     when: "BEFORE compaction or handing over to another session", purpose: "a resume note: open work, task state, next command" },
 
   triage:       { moment: "Change",     when: "a request arrives — BEFORE scaffolding, especially if it smells like an incident", purpose: "classify the lane (product/runtime/chore) and check the declared runtime surface" },
   work:         { moment: "Change",     when: "a request arrives that changes behaviour (triage says PRODUCT)", purpose: "scaffold a change and print the playbook to execute" },
   spec:         { moment: "Change",     when: "a capability needs creating or its headers advancing", purpose: "create, list, and edit capability specs" },
-  change:       { moment: "Change",     when: "driving a change through its lifecycle by hand", purpose: "new / apply / archive / check (--verbose) / tick / abandon" },
+  change:       { moment: "Change",     when: "driving a change through its lifecycle by hand", purpose: "drive a change by hand — check --verbose previews every delta" },
   decision:     { moment: "Change",     when: "the change decides something a later session must not relitigate", purpose: "record, accept, land, scope, and supersede ADRs" },
   contract:     { moment: "Change",     when: "the change touches ports, env vars, or public endpoints", purpose: "own and verify the integration surface" },
   intent:       { moment: "Change",     when: "new product intent appears after the intake", purpose: "append and list product intent anchors" },
@@ -148,7 +145,7 @@ export const COMMAND_META = {
   close:        { moment: "Gate",       when: "a change is implemented and ready to finish", purpose: "the whole closing sequence in one attested pass" },
   doctor:       { moment: "Gate",       when: "something looks wrong and you do not know which gate to ask", purpose: "aggregate diagnostic with per-finding remedies" },
 
-  templates:    { moment: "Maintain",   when: "after upgrading the CLI, or to customise a scaffold", purpose: "inspect, check, and refresh the template shape" },
+  templates:    { moment: "Maintain",   when: "customising a scaffold, to see which template file wins", purpose: "where each shipped template resolves from" },
   upgrade:      { moment: "Maintain",   when: "you just updated the doctrina-cli package", purpose: "bring this project up to the installed CLI" },
   index:        { moment: "Maintain",   when: "the index drifted from the tree", purpose: "regenerate index.json from the artifacts on disk" },
   hooks:        { moment: "Maintain",   when: "setting up a repo so drift cannot be committed", purpose: "install the pre-commit gate" },
@@ -164,10 +161,49 @@ export const MOMENTS = ["Bootstrap", "Orient", "Change", "Gate", "Maintain"];
 
 // The Commands block of `doctrina --help`, generated from OPERATIONS so the
 // printed surface can never omit an operation the catalog knows about.
+//
+// Grouped by the MOMENT an operation is reached for, in the same order as
+// the AGENTS.md block, and opened by the two lines a newcomer needs: a flat
+// list of sixty operations, deprecated ones mixed in, answered "where do I
+// start?" with the whole catalog (change 0174). Deprecated operations stay
+// listed — someone types those names — but last, each pointing at its
+// replacement.
 export function surfaceHelp() {
-  return OPERATIONS.map(([op, summary]) => `  ${op.padEnd(21)}${summary}`).join("\n");
+  // A name longer than the column puts its text on the next line, aligned,
+  // so the summaries stay one scannable column at 80 characters.
+  const line = (op, text) => op.length < 20
+    ? `  ${op.padEnd(21)}${text}`
+    : `  ${op}\n  ${"".padEnd(21)}${text}`;
+  const out = [
+    "Start here:",
+    line("doctrina init", "set up this repository (asks for a one-line description)"),
+    line("doctrina next", "what to do now — your agent runs the rest from AGENTS.md"),
+  ];
+  // One line per COMMAND, its subcommands joined: the summary a newcomer
+  // scans; `doctrina <command> --help` has each subcommand's detail.
+  const live = OPERATIONS.filter(([op]) => !DEPRECATED[op]);
+  for (const moment of MOMENTS) {
+    const cmds = [...new Set(live.map(([op]) => op.split(" ")[0]))]
+      .filter((cmd) => COMMAND_META[cmd]?.moment === moment);
+    if (cmds.length === 0) continue;
+    out.push("", `${moment}:`);
+    for (const cmd of cmds) {
+      const ops = live.filter(([op]) => op.split(" ")[0] === cmd);
+      const subs = ops.map(([op]) => op.split(" ")[1]).filter(Boolean);
+      const text = ops.length === 1 ? ops[0][1] : capitalise(COMMAND_META[cmd].purpose);
+      out.push(line(subs.length > 0 ? `${cmd} ${subs.join("|")}` : cmd, text));
+    }
+  }
+  const old = OPERATIONS.filter(([op]) => DEPRECATED[op]);
+  if (old.length > 0) {
+    out.push("", "Deprecated (still run, with a notice on stderr):",
+      ...old.map(([op]) => line(op, `→ ${DEPRECATED[op].use}`)));
+  }
+  return out.join("\n");
 }
 
+const capitalise = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+
 // ---------------------------------------------------------------------------
 // The CLI-owned AGENTS.md command-surface block (operator review 2026-07-19,
 // meta-conclusion): for an agent, AGENTS.md IS the discovery interface — it
@@ -219,18 +255,48 @@ const SURFACE_HINTS = {
 // leaves the surface block — an agent should not reach for it, and the block
 // is the list of things to reach for. Removal is a later, separate change.
 export const DEPRECATED = Object.freeze({
-  "constitution": {
-    since: "0.16.0",
-    use: "doctrina prime --rules",
-    why: "prime renders the same standing-rules view, from the same collection",
+  "analyze": {
+    since: "0.17.0",
+    use: "doctrina change check",
+    why: "check reports the same structural checks first, then the ops dry-run and the archive-gate preview — it answers 'would the close pass?', so it also exits 1 while a Verification box is open; `change apply` still refuses what analyze refused",
   },
-  "change diff": {
-    since: "0.16.0",
-    use: "doctrina change check --verbose",
-    why: "check runs every ops block against the target spec and now prints the same per-delta preview",
+  "report": {
+    since: "0.17.0",
+    use: "doctrina status --view report",
+    why: "status renders the same digest from the same collector; --agent-changelog is status --view agent-changelog",
   },
+  "skill sync": {
+    since: "0.17.0",
+    use: "doctrina index rebuild",
+    why: "the rebuild registers every skill and mirrors its description, keeping a written one over a scaffold placeholder",
+  },
+  "templates check": {
+    since: "0.17.0",
+    use: "doctrina upgrade",
+    why: "the upgrade preview reports every template finding, each with its fix, and exits 1 while one is left",
+  },
+  "templates update": {
+    since: "0.17.0",
+    use: "doctrina upgrade --write",
+    why: "the upgrade's first step is this update, previewed without --write and applied with it",
+  },
+});
+
+// A deprecated operation that has since been REMOVED. Typing the old name
+// answers with its replacement instead of "unknown command, did you mean
+// ...?" — whoever still has it in a script or a habit learns the one thing
+// they need. Usage class: the fix is the invocation (ADR 0018).
+export const REMOVED = Object.freeze({
+  "constitution": { since: "0.17.0", use: "doctrina prime --rules" },
+  "change diff": { since: "0.17.0", use: "doctrina change check --verbose" },
 });
 
+/** The removal record for an invocation, or null. */
+export function removalFor(argv) {
+  const words = argv.filter((a) => !a.startsWith("-"));
+  return REMOVED[words.slice(0, 2).join(" ")] ?? REMOVED[words[0] ?? ""] ?? null;
+}
+
 /** The deprecation record for an invocation, or null. */
 export function deprecationFor(argv) {
   const words = argv.filter((a) => !a.startsWith("-"));
@@ -450,6 +516,13 @@ export const AGENT_CHANGELOG = {
   // Each entry lists only ITS OWN delta. The series carries the rest
   // forward (see agentChangelogEntries), so a patch never has to restate
   // the minor that introduced the commands, and never silently erases it.
+  "0.17.0": [
+    "Preview a close with `doctrina change check <id>` (it exits 1 while a Verification box is open), then run `doctrina close <id>` — do not run `analyze`, `change apply` or `change archive` by hand; a chore closes the same way.",
+    "Deprecated names still run with a notice — use the replacement: `analyze` → `change check`, `report` → `status --view report`, `skill sync` → `index rebuild`, `templates check|update` → `upgrade [--write]`. `constitution` and `change diff` are removed (exit 2).",
+    "`doctrina upgrade` now reports an installed slash command that still teaches a retired command; run the fix it prints (`doctrina adapter add <agent> --force`).",
+    "`doctrina work \"<prompt>\" --design` also scaffolds design.md — no need to fall back to `change new` for a change with non-trivial choices.",
+    "A new tasks.md has no Closing steps — the close applies, archives and indexes. `intake --converted` refuses while `validate` reports an error; a change reference is its folder name, never a path (exit 2).",
+  ],
   "0.16.0": [
     "A reference or path that does not resolve now answers exit 2 (USAGE) everywhere — `clarify`, `show`, `why`, `analyze`, `context`, `change check`, `spec set`, `decision accept|scope`. Correct the invocation; retrying it unchanged never succeeds.",
     "The `--json` envelope names the OPERATION in `command` and carries arguments in `args` — branch on those two, not on a joined string. An undeclared flag now answers with `{ok: false, exit_code: 2}` instead of an empty stdout.",

package/src/lib/coverage-model.js

@@ -272,6 +272,35 @@ function classifyOrchestration(criterion, n, projectRoot) {
 }
 
 // Decide whether a single criterion is covered, conditional, dangling, or bare.
+// Where a criterion stops DESCRIBING and starts CITING.
+//
+// The tree's grammar for an acceptance criterion is "<observable signal> —
+// verified by `<proof>`", and 212 of them across ten specs follow it. Both
+// halves can contain backtick paths, and they mean opposite things: the paths
+// after the marker are what the criterion offers as proof; the paths before it
+// are the SCENARIO it describes.
+//
+// Change 0106 taught this module to report a cited path that does not resolve
+// even when another one does — right, because one proof resolving does not
+// make a second one true. But it could not see the halves, so a criterion that
+// describes bad input by name was read as claiming that input as evidence.
+// Criterion 72 of the gates spec says a loose `specs/legacy.md` draws a
+// warning; those files exist only inside the test, and coverage reported them
+// as unresolvable proof on every single run.
+//
+// A gate that always prints the same complaint teaches its reader to skip the
+// line it prints it on, which costs more than the check was ever worth.
+//
+// Returns null for a criterion with no marker — then every backtick path is a
+// claim, exactly as before, which is what a project not using this grammar
+// gets.
+const EVIDENCE_MARKER = /\b(?:verified|proven|evidenced|demonstrated)\s+by\b|\bverificad[oa]\s+por\b/i;
+
+function evidenceClause(criterion) {
+  const m = EVIDENCE_MARKER.exec(criterion);
+  return m ? criterion.slice(m.index) : null;
+}
+
 function classify(criterion, n, projectRoot, specDir) {
   // An orchestration criterion is judged on its GUARD, not on whether a
   // cited file exists — the whole point is that existence proves nothing here.
@@ -333,8 +362,18 @@ function classify(criterion, n, projectRoot, specDir) {
   // `missing` rides along on a covered row: one citation resolving does
   // not make the other one true, and the report names it (change 0106).
   if (hasRealProof) {
+    // A `missing` entry may carry its reason — "x.md (a directory, not a
+    // file)" — so recover the bare token before asking where it was written.
+    const clause = evidenceClause(criterion);
+    const isClaimed = (entry) => {
+      if (clause === null) return true;
+      const token = entry.replace(/\s+\([^)]*\)$/, "");
+      return clause.includes(`\`${token}\``);
+    };
     const claims = missing.filter((m) =>
-      !mentions.some((d) => m.startsWith(`${d} `)) && /[\\/]/.test(m) && !/[\\/]$/.test(m));
+      !mentions.some((d) => m.startsWith(`${d} `))
+      && /[\\/]/.test(m) && !/[\\/]$/.test(m)
+      && isClaimed(m));
     return { kind: "covered", n, evidence, unverified, missing: claims };
   }
   return { kind: "conditional", n, skipped: resolved.map((r) => r.token), evidence: [], unverified, missing };

package/src/lib/doc-model.js

@@ -93,7 +93,12 @@ function headerPattern(name) {
  *             line: number, conforming: boolean } | null}
  */
 export function readHeader(text, name) {
-  const m = headerPattern(name).exec(String(text));
+  // Match against the MASKED text so a header written inside an HTML comment
+  // — a template's example of the form, say — is never mistaken for one the
+  // author wrote. Masking replaces comment content with spaces and keeps
+  // every line terminator, so offsets and line numbers are the document's own
+  // and `raw` below is still the real line.
+  const m = headerPattern(name).exec(maskComments(String(text)));
   if (!m) return null;
   const [raw, indent, dash, value] = m;
   const style = dash ? HEADER_STYLE.LIST : HEADER_STYLE.BARE;
@@ -133,7 +138,13 @@ export function setHeader(text, name, value, opts = {}) {
   const useStyle = style ?? existing.style;
   const prefix = useStyle === HEADER_STYLE.LIST ? "- " : "";
   const replacement = `${existing.indent}${prefix}**${name}:** ${value}`.replace(/\s+$/, "");
-  return String(text).replace(headerPattern(name), replacement);
+  // Write over the line `readHeader` actually found, by OFFSET. Replacing on
+  // a pattern would find the first textual match, which — now that reading
+  // skips annotation — may be an example inside a comment sitting above the
+  // real header. Masking preserves offsets, so the index is the real one.
+  const at = maskComments(String(text)).search(headerPattern(name));
+  if (at < 0) return null;
+  return String(text).slice(0, at) + String(text).slice(at).replace(headerPattern(name), replacement);
 }
 
 // The PREAMBLE: everything before the first `## ` section. Metadata headers
@@ -150,7 +161,22 @@ export function preamble(text) {
 // Every header in the document's preamble, in order, with conformance
 // recorded.
 export function readAllHeaders(fullText) {
-  const text = preamble(fullText);
+  // AN HTML COMMENT IS ANNOTATION, NOT A HEADER.
+  //
+  // This module is the one owner of that rule — every other reader in the
+  // tree defers to it — and this function did not apply it. The preamble is
+  // exactly where a template puts its guidance, so an EXAMPLE header written
+  // to show an author the form counted as a header the author wrote.
+  //
+  // It showed as a disagreement rather than a wrong answer: `readHeader`
+  // takes the first match in the whole document, this one collects every
+  // match in the preamble, and a commented example made the two return
+  // different sets. A round-trip test on the real tree caught it the moment
+  // the proposal template gained such an example.
+  //
+  // Masking preserves line terminators, so the reported line numbers are the
+  // document's own either way.
+  const text = preamble(maskComments(fullText));
   const out = [];
   const re = /^([ \t]*)(-[ \t]+)?\*\*([A-Za-z][A-Za-z .-]*?)[ \t]*(?::\*\*|\*\*[ \t]*:)[ \t]*(.*?)[ \t]*$/gm;
   let m;
@@ -393,15 +419,17 @@ export function isPlaceholderHeaderValue(value, opts = {}) {
  *
  * @param {string} text
  * @param {{ section?: string|null }} [opts] limit to one `## ` section
- * @returns {Array<{ line: number, checked: boolean, text: string, placeholder: boolean }>}
+ * @returns {Array<{ line: number, checked: boolean, text: string, placeholder: boolean, section: string|null }>}
  */
 export function parseChecklist(text, opts = {}) {
   const section = opts.section ?? null;
   const lines = String(text).split(/\r?\n/);
   const out = [];
   let inSection = section === null;
+  let heading = null;
   for (let i = 0; i < lines.length; i++) {
     if (/^##\s+/.test(lines[i])) {
+      heading = lines[i].replace(/^##\s+/, "").trim();
       if (section !== null) {
         inSection = new RegExp(`^##\\s+${section.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i")
           .test(lines[i]);
@@ -416,7 +444,7 @@ export function parseChecklist(text, opts = {}) {
     const m = /^\s*[-*+]\s*\[([ xX])\]\s*(.*)$/.exec(lines[i]);
     if (!m) continue;
     const body = m[2].trim();
-    out.push({ line: i, checked: m[1] !== " ", text: body, placeholder: body === "" });
+    out.push({ line: i, checked: m[1] !== " ", text: body, placeholder: body === "", section: heading });
   }
   return out;
 }
@@ -430,8 +458,16 @@ export function parseChecklist(text, opts = {}) {
  * @param {{ section?: string|null }} [opts]
  * @returns {{ total: number, done: number, open: string[], placeholders: number }}
  */
+// A tasks.md scaffolded before change 0195 ends with "## Closing steps" —
+// apply, archive, update the index. Those are what `doctrina close` DOES,
+// so asking for them ticked before the close ran was asking the agent to
+// claim three things that had not happened yet. The template no longer
+// writes them; a change that still carries them is not held to them.
+const CLOSING_STEPS = /^closing steps$/i;
+
 export function checklistProgress(text, opts = {}) {
-  const boxes = parseChecklist(text, opts);
+  const boxes = parseChecklist(text, opts)
+    .filter((b) => opts.section != null || !CLOSING_STEPS.test(b.section ?? ""));
   return {
     total: boxes.length,
     done: boxes.filter((b) => b.checked).length,
@@ -611,3 +647,8 @@ export function parseChangeTitle(text) {
   const title = m?.[1]?.trim();
   return title ? title : null;
 }
+
+/** A value still wrapped in the template's angle brackets: `<one-sentence …>`. */
+export function isScaffoldValue(value) {
+  return /^<[^<>]*>$/.test(String(value ?? "").trim());
+}

package/src/lib/docs-impact.js

@@ -163,6 +163,40 @@ export function documentedSurfaceSignals(changeDir, projectRoot = null) {
     // the finding — and had to close with --force (change 0088).
     if (/chore/i.test(listHeader(text, "Lane") ?? "")) return signals;
 
+    // THE AUTHOR MAY DECLARE THAT A NAME IS A MENTION, NOT A CHANGE.
+    //
+    // Everything below reads NAMES out of the authored text, and a name is
+    // all it can see: a change that says "coverage no longer knows this
+    // test exists" is describing an effect, and one whose Scope boundaries
+    // say "does not touch `verify`" is describing an absence, but both read
+    // to this gate exactly like a change that alters the command. Three
+    // closes in one session were forced for that reason, and a gate that is
+    // routinely forced stops being a gate — the ledger fills with gaps that
+    // were never gaps, and a real one stops standing out.
+    //
+    // No smarter extraction settles it, because the difference is semantic
+    // and ADR 0005 puts semantics outside a deterministic gate. So the
+    // author declares it, in the grammar the tree already uses for exactly
+    // this — `Realizes: n/a — <why>`: a bare `n/a` is an assertion nobody
+    // wrote, and only `n/a` WITH a reason is a decision.
+    // Read it from AUTHORED text only. An HTML comment is annotation — the
+    // rule this module already applies everywhere else, and the one this
+    // header shipped without: a `Documented surface:` line inside a comment
+    // counted, so the example in the proposal template silenced the gate for
+    // every change scaffolded from it. A declaration nobody wrote is not a
+    // declaration, exactly as a bare `n/a` is not one.
+    const declaredNone = listHeader(maskComments(text), "Documented surface");
+    if (declaredNone !== null) {
+      // The separator is punctuation, not a reason: "n/a —" says no more than
+      // "n/a". Strip the word, then the dash, and require words to remain.
+      const rest = declaredNone.trim()
+        .replace(/^(n\/a|none)\b/i, (m) => (m ? "" : m))
+        .replace(/^\s*[—–-]+\s*/, "")
+        .trim();
+      const word = declaredNone.trim().split(/\s+/)[0]?.toLowerCase() ?? "";
+      if ((word === "n/a" || word === "none") && rest.length > 0) return signals;
+    }
+
     sources.push(authored(withoutVerification(text)));
   }
   for (const p of walk(path.join(changeDir, "specs"))) {
@@ -265,6 +299,46 @@ export function isGitRepo(projectRoot) {
   return isRepo(projectRoot);
 }
 
+// A CHANGELOG IS A DIFFERENT OBLIGATION FROM DOCUMENTATION.
+//
+// The docs gate asks "can a reader learn how this works". The changelog asks
+// "can a reader learn that it changed" — and the second is not answered by
+// the first, because prose describing the new behaviour reads exactly like
+// prose that always described it.
+//
+// Nothing asked for it, so it drifted immediately: thirteen changes landed in
+// one session, every one of them through `close`, and `## [Unreleased]` was
+// still empty at the end of it. The file's own first line says every notable
+// change is recorded there.
+//
+// Silent for a project that keeps no CHANGELOG.md — this gate reports a
+// promise the project made, and never invents one it did not.
+export function checkChangelogImpact(projectRoot, changeDir) {
+  const signals = documentedSurfaceSignals(changeDir, projectRoot);
+  if (signals.length === 0) {
+    return { ok: true, signals, touched: [], reason: "touches no documented surface" };
+  }
+  if (!isFile(path.join(projectRoot, CHANGELOG))) {
+    return { ok: true, signals, touched: [], reason: `no ${CHANGELOG} in this project` };
+  }
+  if (!isRepo(projectRoot)) {
+    return { ok: true, signals, touched: [], reason: "not a git repository — cannot tell what moved" };
+  }
+  const touched = changedFiles(projectRoot, { mergeBase: true })
+    .files.filter((f) => f === CHANGELOG);
+  if (touched.length > 0) {
+    return { ok: true, signals, touched, reason: `recorded in ${CHANGELOG}` };
+  }
+  return {
+    ok: false,
+    signals,
+    touched,
+    reason: `alters a documented surface but ${CHANGELOG} does not say so`,
+  };
+}
+
+const CHANGELOG = "CHANGELOG.md";
+
 // Where THIS project keeps its documentation, read off its own tree.
 //
 // The gate is portable; the instruction it printed was not. It named

package/src/lib/ears.js

@@ -3,6 +3,16 @@
 // word-level smells; this catches grammar-shape problems per EARS section.
 // All findings are warnings: specs evolve, validation should not block.
 
+// A prohibition negates its own modal. Either the modal directly
+// ("shall not", "shall never") or the object the verb takes, immediately
+// ("shall do no work", "shall carry neither X nor Y").
+//
+// The gap is ONE word wide on purpose. Allowing two lets "shall report when
+// no contracts are declared" back in — a report, not a prohibition, and the
+// exact shape this check exists to keep out of the must-not section.
+const UNWANTED_NEGATION =
+  /\bshall\s+(?:not|never)\b|\bshall\s+\w+\s+(?:no|neither|nothing)\b/i;
+
 const SECTION_RULES = [
   {
     match: /^###\s+Ubiquitous/i,
@@ -38,7 +48,20 @@ const SECTION_RULES = [
     name: "Unwanted-behavior",
     check(req) {
       if (!/\bshall\b/i.test(req)) return "missing \"shall\" — unwanted-behavior form is \"The system shall not ...\"";
-      if (!/\b(not|no|never)\b/i.test(req)) return "missing a negation — unwanted-behavior requirements forbid something";
+      // The negation has to hang off the MODAL, not merely appear somewhere in
+      // the sentence. Searching the whole line let "no" the determiner stand
+      // in for a prohibition: "the system shall report it as a finding, because
+      // a claim over code that is not there..." forbids nothing and passed.
+      // Two requirements of this repository's own specs were positive
+      // obligations filed under must-not for exactly that reason.
+      //
+      // Both attachments count: "shall not/never <verb>", and the form that
+      // negates the object instead — "shall do no work", "shall carry neither".
+      if (!UNWANTED_NEGATION.test(req)) {
+        return "missing a negation on \"shall\" — unwanted-behavior forbids something "
+          + "(\"shall not ...\", \"shall never ...\", \"shall <verb> no ...\"); a "
+          + "requirement that only reports or accepts belongs in another section";
+      }
       return null;
     },
   },

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(" ")}`;
 }