doctrina-cli 0.16.0 → 0.18.0

package/src/lib/args.js

@@ -74,9 +74,23 @@ export function parseArgs(argv, opts = {}) {
 function isNextTokenFlag(token) {
   if (token === undefined) return true;
   if (typeof token !== "string") return true;
+  // `--budget -5` is a value, not a flag named "5": no flag name starts with
+  // a digit, and reading it as one answered "unknown flag --5, did you mean
+  // --h?" instead of letting the command say the number is out of range.
+  if (/^-\d/.test(token)) return false;
   return token.startsWith("-");
 }
 
+// A count read off a flag: digits only, above zero, or null. `parseInt`
+// reads "7x" as 7 and "1.5" as 1, so a typo became a different request that
+// ran without a word.
+export function parsePositiveInt(raw) {
+  const s = String(raw ?? "").trim();
+  if (!/^\d+$/.test(s)) return null;
+  const n = Number(s);
+  return Number.isSafeInteger(n) && n > 0 ? n : null;
+}
+
 export function flagString(flags, name, fallback = undefined) {
   const v = flags.get(name);
   if (v === undefined || v === true) return fallback;

package/src/lib/change-ops.js

@@ -15,6 +15,10 @@ import { flagBool, flagString } from "./args.js";
 import { c } from "./colors.js";
 import { ensureDoctrinaProject, isChangeId, resolveWithinProject } from "./project.js";
 import { changeEntry } from "./scan.js";
+import { parseOp, insertOps, extractOps, applyOps } from "./spec-ops.js";
+import { parseOperation } from "./doc-model.js";
+import { substitute } from "./templates.js";
+import { EXIT } from "./exit-codes.js";
 export function changeNew(args, flags) {
   const id = args[0];
   const title = args.slice(1).join(" ").trim();
@@ -96,8 +100,10 @@ export function changeNew(args, flags) {
 
   console.log("");
   if (chore) {
+    // A chore is still a change: it closes through the one definition of
+    // done, not a hand-run apply and archive (change 0180).
     console.log(c.bold("Chore opened.") + " No spec deltas expected — implement, check the tasks, then " +
-      c.cyan(`doctrina change apply ${id}`) + " and " + c.cyan(`doctrina change archive ${id}`) + ".");
+      c.cyan(`doctrina close ${id}`) + ".");
   } else {
     console.log(c.bold("Change opened.") + " Add spec deltas under " +
       c.cyan(`.doctrina/changes/${id}/specs/<capability>/delta.md`));
@@ -129,3 +135,91 @@ export function reindexChange(projectRoot, id, date = today()) {
   idx.touch(index, date);
   idx.save(projectRoot, index);
 }
+
+/**
+ * Add op lines to a change's MODIFIED delta for one capability (change 0205).
+ *
+ * A field review of 0.17 asked for "a command to add a requirement and a
+ * criterion without writing the ops blocks by hand". The grammar is
+ * `apply`'s (ADR 0021): every line is parsed by the same parser, and the
+ * whole block — what was there plus what is added — is dry-run against the
+ * current spec before anything is written, so an op that would not apply is
+ * refused now rather than at the close. Creates the delta from the template
+ * when the change has none for the capability yet; a second `bump-version`
+ * replaces the first instead of bumping twice.
+ *
+ * @param {string} projectRoot
+ * @param {string} id          change id (already refused/resolved by the caller)
+ * @param {string} capability
+ * @param {string[]} lines     op lines, one operation each
+ * @returns {{ code: number, error?: string, hint?: string, details?: string[],
+ *             deltaRel?: string, created?: boolean, block?: string[] }}
+ */
+export function addDeltaOps(projectRoot, id, capability, lines) {
+  if (lines.length === 0) {
+    return { code: EXIT.USAGE, error: "nothing to add",
+      hint: "pass --requirement \"<section>: <text>\", --criterion \"<text>\", --bump <level> or an op line" };
+  }
+  const bad = lines.map((l) => ({ l, op: parseOp(l) })).filter((x) => x.op.error);
+  if (bad.length > 0) {
+    return { code: EXIT.USAGE, error: "not an operation `apply` can read", details: bad.map((x) => x.op.error) };
+  }
+  const specPath = path.join(projectRoot, ".doctrina", "specs", capability, "spec.md");
+  if (!isFile(specPath)) {
+    return { code: EXIT.USAGE, error: `capability "${capability}" has no spec at ${relPath(projectRoot, specPath)}`,
+      hint: `a NEW capability is an ADDED delta with the full body — \`doctrina spec new ${capability}\`, then write it` };
+  }
+  const deltaPath = path.join(projectRoot, ".doctrina", "changes", id, "specs", capability, "delta.md");
+  const created = !isFile(deltaPath);
+  let text;
+  if (created) {
+    const tpl = read(path.join(locateTemplatesDir(), "change", "spec-delta.md.template"));
+    text = substitute(tpl, { CAPABILITY: capability }).replace(/^\*\*Operation:\*\*.*$/m, "**Operation:** MODIFIED");
+  } else {
+    text = read(deltaPath);
+    const op = parseOperation(text);
+    if (op && op !== "MODIFIED") {
+      return { code: EXIT.PRECONDITION, error: `${relPath(projectRoot, deltaPath)} is an ${op} delta — ops apply only to a MODIFIED one`,
+        hint: op === "ADDED" ? "write the requirement into the ADDED body itself" : "a REMOVED delta deletes the spec; there is nothing to add to" };
+    }
+  }
+  const next = insertOps(text, lines);
+  const dry = applyOps(read(specPath), extractOps(next));
+  if (dry.errors.length > 0) {
+    return { code: EXIT.GATE, error: `the ops block would not apply to ${relPath(projectRoot, specPath)} — nothing written`, details: dry.errors };
+  }
+  mkdirp(path.dirname(deltaPath));
+  write(deltaPath, next, { force: true });
+  addAffectedSpec(projectRoot, id, capability);
+  return { code: EXIT.OK, deltaRel: relPath(projectRoot, deltaPath), created, block: extractOps(next).map((o) => o.verb) };
+}
+
+/**
+ * Name `capability` in the proposal's `Affects specs:` header when the
+ * header does not already (change 0207). A change whose delta targets a
+ * capability affects that spec, and a header left empty while the delta
+ * folder said otherwise was the one fact `prime`, `status` and the review
+ * of the proposal disagreed on. A chore's "(none — chore)" is left alone:
+ * that is a declaration, and the structure gate is where a chore carrying a
+ * delta gets questioned.
+ *
+ * @param {string} projectRoot
+ * @param {string} id
+ * @param {string} capability
+ * @returns {boolean} whether the header changed
+ */
+export function addAffectedSpec(projectRoot, id, capability) {
+  const proposalPath = path.join(projectRoot, ".doctrina", "changes", id, "proposal.md");
+  if (!isFile(proposalPath)) return false;
+  const text = read(proposalPath);
+  const m = text.match(/^(-[ \t]+\*\*Affects specs:\*\*)([^\r\n]*)/m);
+  if (!m) return false;
+  const current = m[2].trim();
+  if (/^\(none/i.test(current)) return false;
+  const named = current.split(",").map((s) => s.trim().replace(/`/g, "")).filter(Boolean);
+  if (named.includes(capability)) return false;
+  const value = [...named, capability].join(", ");
+  write(proposalPath, text.replace(m[0], `${m[1]} ${value}`), { force: true });
+  reindexChange(projectRoot, id);
+  return true;
+}

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,8 +46,8 @@ 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)"],
+  ["change delta", "Add a requirement/criterion/bump to a change's delta (ops written for you)"],
   ["contract new", "Own the integration surface (ports, env, interfaces)"],
   ["contract list", "List contracts with status and last-updated date"],
   ["contract check", "Verify port collisions, env drift, referenced specs"],
@@ -82,7 +82,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 +125,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 +146,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 +162,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 +256,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",
+  },
+  "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",
   },
-  "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",
+  "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 +517,20 @@ 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.18.0": [
+    "`doctrina change delta <id> <capability> --requirement \"<section>: <text>\" --criterion \"<text>\" --bump minor` writes the ops lines for you and dry-runs them against the spec — stop hand-writing ops blocks.",
+    "`close` runs `verify --reuse`: running `doctrina verify` yourself right before `doctrina close` is no longer paid twice, and a batch close runs the suite once. Use `verify --affected` while working when checks declare `\"paths\"`.",
+    "The review inside `close` counts the change's own deltas as spec updates and reports code under other capabilities in ONE line — read it: either this change forgot a delta or other work is lying in the tree.",
+    "`close` ends by listing other open changes that look finished or are a week old; close them with the `doctrina close <id>` it prints. `next` no longer suggests `change archive`.",
+    "A spec can shrink: `remove-requirement <section> <n>` / `remove-criterion <n>`, and `doctrina work --consolidate <cap>` when a spec has grown past what it needs to say.",
+  ],
+  "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;
     },
   },