doctrina-cli 0.16.0 → 0.17.0

package/README.md

@@ -3,7 +3,7 @@
 > CLI for the Doctrina framework. The package is published as
 > `doctrina-cli`; the executable it installs is `doctrina`.
 
-**Status:** v0.16.0 — current release. Zero runtime dependencies
+**Status:** v0.17.0 — current release. Zero runtime dependencies
 (Node.js standard library only).
 
 ## Install
@@ -18,59 +18,31 @@ Requires Node.js 20.12 or later.
 
 ## Commands
 
+Start with `doctrina init` in your repository, then tell your AI agent to
+read `AGENTS.md` and run `doctrina next` — it drives the rest. The
+surface, by the moment you reach for it:
+
 ```
-doctrina init                              scaffold AGENTS.md + .doctrina/ in cwd
-doctrina intake [<file>]                   store the full description + bootstrap playbook (clarification gate)
-doctrina work "<prompt>"                   brief prompt -> scaffolded change + work playbook (clarification gate)
-doctrina work --resume <id>                reprint an open change's playbook (no new change)
-doctrina work --from-diff                  backfill a spec from working-tree changes (code-first)
-doctrina work "<prompt>" --chore           spec-less chore (infra/docs/build): no spec-delta steps
-doctrina spec new <capability>             create a capability spec
-doctrina spec list                         list specs with version, status, size
-doctrina spec set <cap> [--bump ...]       edit spec headers/criterion + resync index (no lockstep)
-doctrina change new <id> "<title>"         open a change proposal
-doctrina change apply <id>                 apply spec deltas (ADDED/REMOVED auto; MODIFIED ops block applies)
-doctrina change archive <id>               archive an applied change
-doctrina change abandon <id>               delete an open change + its index entry (ledgered)
-doctrina change diff <id>                  preview spec deltas (line diff for MODIFIED)
-doctrina contract new <name>               own the integration surface (ports, env, interfaces)
-doctrina contract check                    verify port collisions, env drift, referenced specs
-doctrina decision new "<title>"            create the next sequential ADR
-doctrina decision accept <num>             flip a proposed ADR to accepted
-doctrina decision land <num> [path...]     stamp an accepted ADR as implemented (non-mutating Landed:)
-doctrina decision supersede <num> "<t>"    supersede an existing ADR
-doctrina decision list                     list ADRs with status, date, title
-doctrina skill new <name>                  scaffold an on-demand procedural-memory skill
-doctrina skill list                        list skills with descriptions (read-only)
-doctrina skill sync                        mirror skill frontmatter descriptions into index.json
-doctrina analyze <change-id>               inspect a change folder before applying
-doctrina clarify <path>                    smell-test a Markdown file for ambiguity (--all: tree)
-doctrina context [<capability>]            print the context pack in read order (--concat)
-doctrina search <term> [...]               search artifacts, grouped by category (ranked)
-doctrina validate                          schema + artifact-existence + index-drift checks (--fix rebuilds)
-doctrina coverage                          acceptance criteria with linked evidence (--strict gates; skips = conditional)
-doctrina trace                             intent provenance: product intent -> specs (--strict gates)
-doctrina verify                            run project typecheck/test/build checks (the real gate)
-doctrina verify --clean                    reproducibility lint: clean-checkout footguns (dist/codegen)
-doctrina templates list                    enumerate shipped templates
-doctrina templates check                   compare project against recommended template shape
-doctrina templates update                  additive fixer for check findings (preview; --write applies)
-doctrina hooks install                     install pre-commit hook
-doctrina index rebuild                     regenerate index.json from the files (--check for CI)
-doctrina next                              print the recommended next workflow actions
-doctrina metrics                           local git-derived adoption metrics (no network)
-doctrina --help | -h                       print the command surface
-doctrina --version | -v                    print the package version
+Bootstrap   init · intake · adapter list|add|remove
+Orient      prime · next · status · context · show · search · why · handoff
+Change      triage · work · spec new|list|set · change new|apply|archive|check|tick|abandon
+            contract new|list|check · decision new|accept|land|supersede|list|scope
+            skill new|list|suggest · intent add|list
+Gate        clarify · validate · coverage · trace · review · verify · close · doctor
+Maintain    upgrade · index rebuild · hooks install · watch · metrics · completion · ci · templates list
 ```
 
-Per-command help is available with `doctrina <command> --help`.
+`doctrina --help` prints the same grouping with one line per command, and
+`doctrina <command> --help` the flags of each. Every command, flag and exit
+code is in the
+[CLI reference](https://github.com/GCarin1/Doctrina/blob/main/docs/en/cli-reference.md).
 
 ## `init` flags
 
 | Flag | Purpose |
 |------|---------|
 | `--project-name <name>` | Override the project name (defaults to cwd basename) |
-| `--project-description <text>` | One-sentence description (prompted if omitted) |
+| `--project-description <text>` | One-sentence description, with no intake. Without it on a terminal, `init` asks you to describe the project once and keeps the answer as the intake |
 | `--agent <name>` | Install the adapter for one of the twelve supported agents (`claude`, `codex`, `cursor`, `copilot`, `gemini`, `aider`, `windsurf`, `continue`, `amp`, `devin`, `factory`, `jules`) or `all` |
 | `--date <YYYY-MM-DD>` | Override the system date in artifacts |
 | `--force` | Overwrite existing files |
@@ -100,7 +72,8 @@ For each spec delta found under `.doctrina/changes/<id>/specs/`:
 - **REMOVED:** deletes the target spec.
 - **MODIFIED:** when the delta carries a fenced ` ```ops ` block
   (`set-header` / `bump-version` / `set-criterion` / `replace-criterion`
-  / `append-criterion`), applies it mechanically to the target spec — all
+  / `append-criterion` / `append-requirement` / `replace-requirement`),
+  applies it mechanically to the target spec — all
   ops or none — and regenerates the index (ADR 0007). Without an ops
   block it prints a manual-merge pointer and does not write: auto-merging
   arbitrary prose is the kind of implicit decision Doctrina avoids.
@@ -108,35 +81,17 @@ For each spec delta found under `.doctrina/changes/<id>/specs/`:
 On any spec write, the index is rebuilt from the tree so it never drifts
 from the applied spec. `doctrina change abandon <id>` is the inverse of
 `change new`: it deletes an open change and its index entry and ledgers
-the abandonment.
+the abandonment. `doctrina close <id>` runs apply together with verify,
+coverage, archive and validate in one attested pass — the definition of
+done.
 
 ## `validate` checks
 
-1. `AGENTS.md` exists at root and is ≤ 200 lines (warns at > 150).
-2. `.doctrina/product.md` exists.
-3. `.doctrina/index.json` parses and matches the v0.1 shape.
-4. Every artifact referenced in `index.json` exists.
-5. Every ADR has a parseable `Status:` header.
-6. Every adapter template under `.doctrina/templates/adapters/` is ≤ 30 lines.
-7. Every open change has a `proposal.md`.
-8. Capability specs are ≤ 400 lines (warns above).
-9. ADRs are ≤ 300 lines (warns above).
-10. Spec/ADR files on disk are present in `index.json` (orphan warn).
-11. Markdown links inside specs/ADRs resolve to real files (stale ref warn).
-12. Skills carry the required frontmatter triple (`name`, `description`, `when`).
-13. Skills are ≤ 200 lines (warns at > 150).
-14. Each skill's `name:` matches its filename slug.
-15. Indexed artifact metadata (spec/decision/change/contract) matches its
-    file — a mismatch is an **error** so a green `validate` can't hide the
-    drift `index rebuild --check` would catch (G5; `validate --fix` rebuilds).
-16. Each skill's frontmatter description matches `index.json` (drift warn; `skill sync` fixes).
-17. EARS grammar shape per section in specs declaring `## Requirements (EARS)` (warn).
-18. Nested `AGENTS.md` files obey the root size caps (warn > 150, error > 200).
-19. No two ADR files share the same `NNNN` number (merge-collision error).
-20. `index.json` records a `framework_version` matching the running CLI
-    (stamp-divergence warn; `index rebuild` migrates it).
-21. Accepted ADRs anchor to reality via `Evidence:` and/or `Landed:`; cited
-    paths must exist on disk (drift warn).
+Structure, schema, EARS grammar, index drift, size caps, links, skills,
+ADR anchoring and more — the full, numbered list with the reason for each
+check is in the
+[CLI reference](https://github.com/GCarin1/Doctrina/blob/main/docs/en/cli-reference.md#doctrina-validate).
+A second copy here fell behind it once; there is now one list.
 
 Exit code: 0 if no errors (warnings allowed), 1 otherwise. `--fix`
 regenerates `index.json` from the tree before validating.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [
@@ -15,7 +15,7 @@
   ],
   "type": "module",
   "bin": {
-    "doctrina": "./src/index.js"
+    "doctrina": "src/index.js"
   },
   "scripts": {
     "test": "node --test",
@@ -32,7 +32,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/gcarin1/doctrina.git",
+    "url": "git+https://github.com/GCarin1/Doctrina.git",
     "directory": "packages/doctrina-cli"
   },
   "publishConfig": {

package/src/commands/adapter.js

@@ -10,6 +10,7 @@ import { today } from "../lib/dates.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { projectName } from "../lib/project.js";
 
 // `doctrina adapter` — add, remove, and inventory agent adapters (audit
 // item C1).
@@ -96,7 +97,7 @@ function adapterAdd(projectRoot, name, cmdFlags) {
 
   const force = flagBool(cmdFlags, "force", false);
   const tokens = {
-    PROJECT_NAME: path.basename(projectRoot),
+    PROJECT_NAME: projectName(projectRoot),
     PROJECT_DESCRIPTION: "",
     DATE: today(),
   };
@@ -145,7 +146,7 @@ function adapterRemove(projectRoot, name, cmdFlags) {
   // Only delete files this adapter created AND that still match what it
   // would write. A file the user edited is theirs now; --force overrides.
   const force = flagBool(cmdFlags, "force", false);
-  const tokens = { PROJECT_NAME: path.basename(projectRoot), PROJECT_DESCRIPTION: "", DATE: today() };
+  const tokens = { PROJECT_NAME: projectName(projectRoot), PROJECT_DESCRIPTION: "", DATE: today() };
   let removed = 0;
   let kept = 0;
   // Directories a removed file lived in, innermost first. Only these are

package/src/commands/analyze.js

@@ -5,6 +5,7 @@ import { isDir, relPath } from "../lib/fs-ops.js";
 import { c } from "../lib/colors.js";
 import { collectAnalysis } from "../lib/analysis.js";
 import { EXIT } from "../lib/exit-codes.js";
+import { ensureDoctrinaProject, refuseChangeRef } from "../lib/project.js";
 
 // The findings themselves live in lib/analysis.js, where the gate map reads
 // them; this command is their renderer (audit finding F7).
@@ -23,6 +24,13 @@ export async function run(positional, _flags) {
   }
 
   const projectRoot = process.cwd();
+  // The project first, then the reference. Asked the other way round, a
+  // directory that is not a project at all answered `change "x" not found`
+  // — which points at creating a change somewhere there is nothing to
+  // create it in.
+  ensureDoctrinaProject(projectRoot);
+  const refused = refuseChangeRef(id);
+  if (refused !== null) return refused;
   const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
   if (!isDir(changeDir)) {
     console.error(c.red("error:") + ` change "${id}" not found at ${relPath(projectRoot, changeDir)}`);

package/src/commands/change.js

@@ -6,7 +6,7 @@ import { exists, isDir, isFile, lineCount, mkdirp, move, read, relPath, remove,
 import { diffLines, formatUnified } from "../lib/diff.js";
 import { locateTemplatesDir, loadTemplateTree, materialiseEntry } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
-import { deriveIndex } from "../lib/scan.js";
+import { archivedChangeEntry, deriveIndex } from "../lib/scan.js";
 import { extractOps, applyOps } from "../lib/spec-ops.js";
 import { printAdrCheckpoint } from "../lib/adr-guard.js";
 import { GATES, TRANSITIONS, checkTransition, recordForcedGap } from "../lib/gates.js";
@@ -17,11 +17,11 @@ import { appendLedgerLine, archivedLine, abandonedLine } from "../lib/ledger.js"
 import { suggest } from "../lib/suggest.js";
 import { confirm, isInteractive } from "../lib/prompt.js";
 import { EXIT } from "../lib/exit-codes.js";
-import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { ensureDoctrinaProject, refuseChangeRef } from "../lib/project.js";
 import { parseOperation, parseCapabilityFromDelta, isUntouchedScaffold } from "../lib/doc-model.js";
 import { changeNew } from "../lib/change-ops.js";
 
-const SUBCOMMANDS = ["new", "apply", "archive", "check", "tick", "diff", "abandon"];
+const SUBCOMMANDS = ["new", "apply", "archive", "check", "tick", "abandon"];
 
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
@@ -42,8 +42,6 @@ export async function run(positional, flags) {
         changeCheck(id, { verbose: flagBool(flags, "verbose", false) }));
     case "tick":
       return changeTick(positional.slice(1), flags);
-    case "diff":
-      return changeDiff(positional.slice(1), flags);
     case "abandon":
       return await changeAbandon(positional.slice(1), flags);
     default:
@@ -100,6 +98,8 @@ async function forEachId(ids, name, one) {
   }
   let worst = 0;
   for (const id of ids) {
+    const refused = refuseChangeRef(id);
+    if (refused !== null) { worst = Math.max(worst, refused); continue; }
     if (ids.length > 1) {
       console.log("");
       console.log(c.bold(`──── change ${name} ${id}`));
@@ -108,6 +108,14 @@ async function forEachId(ids, name, one) {
     try {
       code = await one(id);
     } catch (err) {
+      // A TYPED error is a condition of the RUN, not a verdict on this id:
+      // "not a Doctrina project" is equally true of every id, and the class
+      // it carries is the whole point of the contract. Flattening it to 1
+      // here made `change apply|archive|check` answer "fix your work and
+      // retry" where `change new`, one switch arm away, answered "run the
+      // setup command first" — same condition, same sentence, two codes.
+      // The entrypoint owns the mapping and prints the remedy; let it.
+      if (err && typeof err.exitCode === "number") throw err;
       console.error(c.red("error:") + ` ${err.message}`);
       code = 1;
     }
@@ -308,7 +316,7 @@ async function changeCheck(id, { verbose = false } = {}) {
   let failures = 0;
 
   // 1. Structural analysis — same checks analyze runs before an apply.
-  console.log(c.gray("──── 1/3 structure (analyze)"));
+  console.log(c.gray("──── 1/3 structure"));
   const analyze = await import("./analyze.js");
   if ((await analyze.run([id], new Map())) !== 0) failures += 1;
 
@@ -348,7 +356,7 @@ async function changeCheck(id, { verbose = false } = {}) {
   if (deltaFiles.length === 0) console.log(c.gray("- no spec deltas"));
   if (opsFindings > 0) failures += 1;
 
-  // --verbose: the same per-delta preview `change diff` prints. The dry-run
+  // --verbose: the per-delta preview the removed `change diff` printed. The dry-run
   // above says whether the ops WOULD apply; this says what the file would
   // look like afterwards, which is the question the separate command existed
   // to answer (change 0049).
@@ -396,6 +404,8 @@ function changeTick(args, flags) {
     console.error(c.red("error:") + " change tick requires <id> [ordinals... | --all]");
     return 2;
   }
+  const refused = refuseChangeRef(id);
+  if (refused !== null) return refused;
   const projectRoot = process.cwd();
   ensureDoctrinaProject(projectRoot);
   const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
@@ -522,7 +532,7 @@ function changeArchive(args, flags) {
 
   // Verification gate. "Done" is a claim until it is checked. Archiving is
   // the act of declaring a change finished, so it must refuse while any
-  // task (including closing steps) or any declared verification item is
+  // task or any declared verification item is
   // still unchecked. This is the difference between "boxes marked" and
   // "verification passed" the framework was faulted for collapsing.
   // Preconditions from the shared map (C6): structure AND verification.
@@ -594,14 +604,10 @@ function changeArchive(args, flags) {
   console.log(c.green("ledger") + ` +1 line in ${relPath(projectRoot, ledgerFile)}`);
 
   const index = idx.load(projectRoot);
-  idx.moveChangeToArchive(index, id, {
-    id,
-    title,
-    path: `.doctrina/changes/archive/${archiveName}`,
-    status: "applied",
-    applied: date,
-    specs_affected: specsAffected,
-  });
+  idx.moveChangeToArchive(index, id, archivedChangeEntry(
+    exists(proposal) ? read(proposal) : "",
+    { id, archiveName, applied: date, specsAffected, title },
+  ));
   idx.touch(index, date);
   idx.save(projectRoot, index);
   console.log(c.green("indexed") + " change archived");
@@ -618,6 +624,8 @@ async function changeAbandon(args, flags) {
     console.error(c.red("error:") + " change abandon requires <id>");
     return 2;
   }
+  const refused = refuseChangeRef(id);
+  if (refused !== null) return refused;
   const projectRoot = process.cwd();
   ensureDoctrinaProject(projectRoot);
 
@@ -675,9 +683,9 @@ async function changeAbandon(args, flags) {
 // ADDED reports the body it would write, REMOVED the spec it would delete,
 // MODIFIED a line diff against the current spec.
 //
-// One renderer, two callers (change 0049): `change diff` is this and nothing
-// else, and `change check --verbose` prints it after its ops dry-run — which
-// is what makes the merge honest rather than a claim. Returns the number of
+// `change check --verbose` prints this after its ops dry-run. It was also
+// the whole of `change diff`, until that alias was retired (changes 0049,
+// 0175) — the one renderer is what made the merge honest. Returns the number of
 // deltas it could not read.
 export function printDeltaPreview(projectRoot, changeDir, deltaFiles) {
   let errors = 0;
@@ -725,33 +733,6 @@ export function printDeltaPreview(projectRoot, changeDir, deltaFiles) {
   return errors;
 }
 
-function changeDiff(args, _flags) {
-  const id = args[0];
-  if (!id) {
-    console.error(c.red("error:") + " change diff requires <id>");
-    return 2;
-  }
-  const projectRoot = process.cwd();
-  ensureDoctrinaProject(projectRoot);
-
-  const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
-  if (!isDir(changeDir)) {
-    console.error(c.red("error:") + ` change "${id}" not found at ${relPath(projectRoot, changeDir)}`);
-    return EXIT.USAGE;
-  }
-
-  const deltaFiles = walk(path.join(changeDir, "specs")).filter((p) => p.endsWith("delta.md"));
-  if (deltaFiles.length === 0) {
-    console.log(c.gray("no spec deltas in this change; nothing to diff"));
-    return 0;
-  }
-
-  const errors = printDeltaPreview(projectRoot, changeDir, deltaFiles);
-  console.log("");
-  return errors > 0 ? 1 : 0;
-}
-
-
 function extractDeltaBody(text) {
   // The delta separates headers from the spec body with a `---` line.
   const idxSep = text.indexOf("\n---\n");
@@ -760,34 +741,6 @@ function extractDeltaBody(text) {
 }
 
 
-// Reasons a change is not finished enough to archive. Counts unchecked
-// GitHub-style checkboxes (`- [ ]`) in tasks.md (every task, including the
-// closing steps) and in the proposal's "## Verification" section. Returns
-// a list of human-readable blocker strings; empty means clear to archive.
-function collectArchiveBlockers(changeDir) {
-  const blockers = [];
-  const countUnchecked = (s) => (s.match(/^\s*-\s*\[ \]/gm) ?? []).length;
-
-  const tasksPath = path.join(changeDir, "tasks.md");
-  if (exists(tasksPath)) {
-    const n = countUnchecked(read(tasksPath));
-    if (n > 0) blockers.push(`${n} unchecked task${n === 1 ? "" : "s"} in tasks.md (closing steps count)`);
-  }
-
-  const proposalPath = path.join(changeDir, "proposal.md");
-  if (exists(proposalPath)) {
-    const n = countUnchecked(getSection(read(proposalPath), "Verification"));
-    if (n > 0) blockers.push(`${n} unmet verification item${n === 1 ? "" : "s"} in proposal.md (## Verification)`);
-  }
-  return blockers;
-}
-
-function ensureDoctrinaProject(projectRoot) {
-  if (!exists(path.join(projectRoot, ".doctrina"))) {
-    throw notADoctrinaProject();
-  }
-}
-
 export const help = `
 Usage: doctrina change <subcommand> [args]
 
@@ -805,7 +758,7 @@ Subcommands:
                          MODIFIED without one prints a manual-merge pointer.
                          On any spec write the index is rebuilt from the tree.
   archive <id...>        Move the change to .doctrina/changes/archive/YYYY-MM-DD-<id>/
-  check <id...>          Pre-close dry-run, read-only: analyze's structural
+  check <id...>          Pre-close dry-run, read-only: the structural
                          checks + every ops block executed in memory against
                          its target + the archive gate preview + an advisory
                          list of accepted ADRs citing the touched capabilities.
@@ -815,8 +768,6 @@ Subcommands:
                          or every one with --all. No args = list only.
   abandon <id>           Delete an open change folder and its index entry, and
                          record the abandonment in the ledger ([--reason "..."]).
-  diff <id>              Preview every spec delta: line diff for MODIFIED,
-                         summary for ADDED/REMOVED. Read-only.
 
 apply / archive / check accept multiple ids (batch close of a backlog); the
 exit code is the worst per-id result.

package/src/commands/clarify.js

@@ -37,7 +37,14 @@ const RULES_EN = [
     // hid the one real finding among them ("name some of them", which said
     // nothing about how many). A gate that cries wolf teaches people to
     // ignore it.
-    re: /(?<!\bhow\s+)\b(many|few|some|several)\b(?!\s+\d)/gi,
+    //
+    // The quality adjectives sit here for the same reason the quantifiers do:
+    // "robust" names no threshold, so it cannot be met or missed. They were
+    // in the Portuguese lexicon and nowhere in this one, so the SAME sentence
+    // translated came back with three smells in one language and none in the
+    // other — and this project keeps its own pages in both. A smell test that
+    // answers differently per language is not testing the writing.
+    re: /(?<!\bhow\s+)\b(many|few|some|several|adequate|robust|scalable)\b(?!\s+\d)/gi,
     hint: "quantify (use a number or a precise scope)",
   },
   {

package/src/commands/close.js

@@ -7,18 +7,20 @@ import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { parseCapabilityFromDelta } from "../lib/doc-model.js";
 import { printAdrCheckpoint, acceptedDecisionCount } from "../lib/adr-guard.js";
-import { docsRemedy, checkDocsImpact } from "../lib/docs-impact.js";
+import { docsRemedy, checkDocsImpact, checkChangelogImpact } from "../lib/docs-impact.js";
 import { collectRuntimeFindings } from "../lib/runtime.js";
 import { derivedImplementations, implementationMismatch, summarize } from "../lib/coverage-model.js";
 import { specHeader, dependentsOf } from "../lib/scan.js";
-import { sequence, stepRerun } from "../lib/gates.js";
+import { sequence, sequenceLabels, stepRerun } from "../lib/gates.js";
 import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
+import { refuseChangeRef } from "../lib/project.js";
 import * as analyze from "./analyze.js";
 import * as change from "./change.js";
 import * as verify from "./verify.js";
 import * as coverage from "./coverage.js";
 import * as trace from "./trace.js";
 import * as validate from "./validate.js";
+import * as indexRebuild from "./index-rebuild.js";
 import { appendLedgerLine, docsGapLine, ledgerPath as ledgerFile } from "../lib/ledger.js";
 import * as review from "./review.js";
 import * as skill from "./skill.js";
@@ -67,6 +69,8 @@ export async function run(positional, flags) {
 }
 
 async function closeOne(projectRoot, id, flags) {
+  const refused = refuseChangeRef(id);
+  if (refused !== null) return refused;
   // A change id that does not resolve is the USAGE class, before any step
   // is sequenced (change 0114) — every sibling that takes a change id
   // answers 2; `close` answered 1 through the analyze step it ran first.
@@ -257,10 +261,24 @@ async function closeOne(projectRoot, id, flags) {
     // escape hatch archive offers, and records the gap in the ledger.
     docs: {
       run: async () => {
-        const r = checkDocsImpact(projectRoot, path.join(projectRoot, ".doctrina", "changes", id));
+        const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
+        const r = checkDocsImpact(projectRoot, changeDir);
         if (r.ok) {
           console.log(c.green("ok") + ` ${r.reason}`);
-          return 0;
+          // Documentation says how it works; the changelog says that it
+          // changed. Asking only the first is how thirteen changes closed in
+          // one session with an empty `## [Unreleased]` behind them.
+          const log = checkChangelogImpact(projectRoot, changeDir);
+          if (log.ok) {
+            console.log(c.green("ok") + ` ${log.reason}`);
+            return 0;
+          }
+          console.error(c.red("error:") + ` this change ${log.reason}:`);
+          for (const s of log.signals) console.error(`  - ${s}`);
+          console.error(c.gray("hint: ") + "add an entry under the changelog's unreleased heading" +
+            ", or pass --force to close anyway (records the gap)");
+          docsGap = log;
+          return 1;
         }
         console.error(c.red("error:") + ` this change ${r.reason}:`);
         for (const s of r.signals) console.error(`  - ${s}`);
@@ -268,8 +286,21 @@ async function closeOne(projectRoot, id, flags) {
         // Doctrina's own repository (change 0058): an adopting project with
         // no `docs/` was being told to write English AND Portuguese and to
         // read a skill it does not have.
-        console.error(c.gray("hint: ") + docsRemedy(projectRoot) +
-          ", or pass --force to close anyway (records the gap)");
+        console.error(c.gray("hint: ") + docsRemedy(projectRoot) + ".");
+        // THE SECOND ANSWER, NAMED WHERE IT IS NEEDED.
+        //
+        // The gate reads names, and a name is all it can see: a change that
+        // explains an effect, or a Scope boundaries line saying what it does
+        // NOT touch, reads exactly like one that alters the command. When the
+        // only remedy on offer was `--force`, an author looking at a false
+        // positive took the worst of the two exits — the ledger fills with
+        // gaps that were never gaps, and a real one stops standing out.
+        //
+        // The declaration exists for precisely this (change 0139) and was
+        // named nowhere the author would be looking.
+        console.error(c.gray("      ") + "if the names above are only MENTIONED, say so on the record: " +
+          "add `- **Documented surface:** n/a — <why>` to the proposal.");
+        console.error(c.gray("      ") + "or pass --force to close anyway (records the gap).");
         docsGap = r;
         return 1;
       },
@@ -280,6 +311,10 @@ async function closeOne(projectRoot, id, flags) {
       run: () => change.run(["archive", id], archiveFlags),
     },
 
+    // In-process, like every other runner here: the close starts no subprocess
+    // of its own binary, and a criterion holds it to that.
+    "index-drift": { run: () => indexRebuild.run(["rebuild"], new Map([["check", true]])) },
+
     validate: { run: () => validate.run([], new Map()) },
   };
 
@@ -459,15 +494,35 @@ function touchedCapabilities(projectRoot, id) {
   return [...caps].sort();
 }
 
+// The sequence is DECLARED once, in lib/gates.js, and rendered here. It used
+// to be typed out in this string, which is how the help came to name ten
+// steps of thirteen — review, implementation, docs and the index-drift check
+// were added over time and the paragraph was not.
+const SEQUENCE = wrapArrows(sequenceLabels("close"), 70, "  ");
+
+function wrapArrows(labels, width, indent) {
+  const lines = [];
+  let line = "";
+  for (const label of labels) {
+    const piece = line === "" ? label : `${line} → ${label}`;
+    if (piece.length + indent.length > width && line !== "") {
+      lines.push(indent + line + " →");
+      line = label;
+    } else line = piece;
+  }
+  if (line !== "") lines.push(indent + line);
+  return lines.join("\n");
+}
+
 export const help = `
 Usage: doctrina close <id...> [--force]
 
 Run the whole closing sequence for a change in one pass, stopping at the
 first failure with the exact command to rerun:
 
-  analyze → ADR checkpoint (advisory) → change apply → runtime → verify →
-  coverage --strict (scoped to the change's touched capabilities) → trace →
-  change archive → validate → skill suggest (advisory)
+${SEQUENCE}
+
+then a closing skill-suggest listing (advisory).
 
 The coverage gate is scoped to the capabilities the change's deltas touch,
 so a deliberately deferred spec elsewhere cannot block an unrelated close;
@@ -481,7 +536,7 @@ trace, the ADR checkpoint
 (accepted ADRs citing the touched capabilities — amend via \`decision
 supersede\`, not silence), and the closing skill-suggest listing are
 advisory (reports, never blockers). This is a driver over the existing
-commands so the agent makes one call instead of nine and the human
+commands so the agent makes one call instead of thirteen and the human
 approves once.
 
 Multiple ids close in sequence, each independently; the exit code is the

package/src/commands/completion.js

@@ -1,15 +1,21 @@
 // @ts-check
-import { OPERATIONS, COMMAND_NAMES } from "../lib/commands.js";
+import { DEPRECATED, OPERATIONS } from "../lib/commands.js";
 import { c } from "../lib/colors.js";
 
 // Shell completions, generated from the same OPERATIONS catalog that feeds
 // `--help` and the docs drift tests — so the completion script can never
 // know a different surface than the CLI ships. Static output by design:
 // paste it into your shell config once; regenerate after upgrading.
+//
+// Deprecated operations are left out (change 0188): they still run, with a
+// notice, for a script that already types them — but tab completion is how
+// a person discovers the surface, and it should offer the replacement only.
+const LIVE = OPERATIONS.filter(([op]) => !DEPRECATED[op]);
+const COMMAND_NAMES = [...new Set(LIVE.map(([op]) => op.split(" ")[0]))];
 
 function subcommandMap() {
   const map = new Map();
-  for (const [op] of OPERATIONS) {
+  for (const [op] of LIVE) {
     const [cmd, sub] = op.split(" ");
     if (!sub) continue;
     if (!map.has(cmd)) map.set(cmd, []);

package/src/commands/context.js

@@ -7,7 +7,7 @@ import { listHeader, parseDependsOn, parseAdrScope, adrSummary, knownCapabilitie
 import { suggest } from "../lib/suggest.js";
 import { checklistProgress, getTitle, getSectionParagraph } from "../lib/doc-model.js";
 import { parseFrontmatter } from "../lib/doc-model.js";
-import { flagBool, flagString, flagGivenWithoutValue } from "../lib/args.js";
+import { flagBool, flagString, flagGivenWithoutValue, parsePositiveInt } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { loadConfig, DEFAULTS } from "../lib/config.js";
 import { GIT_STATE, historyState, changedFiles } from "../lib/git.js";
@@ -466,16 +466,18 @@ function capabilitiesInPlay(projectRoot) {
   return [...caps];
 }
 
+// Line endings are not content: a Windows checkout stores every line with a
+// CR, which added ~2% to the same pack, so the budget gate — run on every OS
+// in CI — could pass on Linux and fail on Windows for the same tree.
 function estimateTokens(text) {
-  return Math.round(text.length / TOKEN_DIVISOR);
+  return Math.round(text.replace(/\r\n/g, "\n").length / TOKEN_DIVISOR);
 }
 
 // Flag beats project config beats the built-in default. Returns null for a
 // malformed --budget so the caller can report a usage error.
 function resolveBudget(projectRoot, budgetRaw) {
   if (budgetRaw !== undefined) {
-    const n = Number.parseInt(budgetRaw, 10);
-    return Number.isFinite(n) && n > 0 ? n : null;
+    return parsePositiveInt(budgetRaw);
   }
   // One configuration reader (lib/config.js, change 0047): `.doctrina/
   // config.json` is the declared home and index.json's `config` block is