doctrina-cli 0.16.0 → 0.18.0

package/src/commands/close.js

@@ -2,26 +2,28 @@
 import path from "node:path";
 import process from "node:process";
 import { appendFileSync } from "node:fs";
-import { exists, isDir, isFile, read, walk } from "../lib/fs-ops.js";
+import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
 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 { specHeader, dependentsOf, deltaCapabilities } from "../lib/scan.js";
+import { sequence, sequenceLabels, stepRerun } from "../lib/gates.js";
 import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
+import { refuseChangeRef } from "../lib/project.js";
+import { unfinishedChanges } from "../lib/snapshot.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";
+import { skillCandidates } from "../lib/skill-candidates.js";
 
 // One-command close (review 2026-06-27 passive-user feature #2). The work
 // playbook lists the closing sequence — analyze → apply → runtime → verify →
@@ -63,10 +65,65 @@ export async function run(positional, flags) {
       ? c.green("ok") + ` all ${positional.length} changes closed`
       : c.red("fail") + " at least one close stopped — see above");
   }
+  reportSkills(projectRoot, positional);
+  reportUnfinished(projectRoot, positional);
   return worst;
 }
 
+// Capture the lesson while it is fresh (operator review §4.7) — the lesson
+// THIS close produced (change 0202). The close used to print the whole
+// `skill suggest` listing, per id: the same thirteen candidates after every
+// close, which a field review of 0.17 named as noise nobody read. Now a
+// candidate born from a change just closed gets its line; every other one is
+// a count pointing at the full listing. Once per run, batch or not.
+// Advisory — a listing, never a gate, and a failure never un-closes anything.
+function reportSkills(projectRoot, closing) {
+  let candidates;
+  try {
+    candidates = skillCandidates(projectRoot);
+  } catch {
+    return;
+  }
+  if (candidates.length === 0) return;
+  const ids = new Set(closing);
+  const fresh = candidates.filter((cand) => cand.source === "change" && ids.has(cand.id));
+  const waiting = candidates.length - fresh.length;
+  console.log("");
+  console.log(c.gray("──── skills (advisory)"));
+  for (const cand of fresh) {
+    console.log(c.yellow("  ! ") + `${cand.id} is fix-shaped — capture the lesson while it is fresh: ` +
+      c.cyan(`doctrina skill new ${cand.slug}`));
+  }
+  if (waiting > 0) {
+    console.log(c.gray(`  ${waiting} ${fresh.length > 0 ? "older " : ""}candidate${waiting === 1 ? "" : "s"} waiting — \`doctrina skill suggest\``));
+  }
+}
+
+// The other open changes, said at the one moment someone is looking (change
+// 0201). A field review of 0.17: change 0078 shipped, stayed open, and no
+// close after it said a word. A change that looks finished — applied, or
+// every task ticked — and one open a week or more get a line each; the rest
+// are a count. Advisory: it never moves the exit code.
+function reportUnfinished(projectRoot, closing) {
+  const others = unfinishedChanges(projectRoot, { exclude: closing });
+  if (others.length === 0) return;
+  const flagged = others.filter((ch) => ch.reason !== null);
+  console.log("");
+  console.log(c.gray(`──── other open changes (advisory) — ${others.length}`));
+  for (const ch of flagged) {
+    const age = ch.ageDays !== null ? `, opened ${ch.ageDays}d ago` : "";
+    const how = ch.finished ? ` — ${c.cyan(`doctrina close ${ch.id}`)}` : "";
+    console.log(c.yellow("  ! ") + `${ch.id}: ${ch.reason}${age}${how}`);
+  }
+  const quiet = others.length - flagged.length;
+  if (quiet > 0) {
+    console.log(c.gray(`  ${quiet} more open and recent — \`doctrina next\``));
+  }
+}
+
 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.
@@ -134,13 +191,17 @@ async function closeOne(projectRoot, id, flags) {
     },
 
     // The review runs against the working tree, which for a close IS the
-    // change's diff: the work is done and not yet archived. Its exit code is
+    // change's diff: the work is done and not yet archived. It is told which
+    // change it is reviewing (change 0200): the deltas it carries are the
+    // spec updates, merged one step later by `apply`, and code under a
+    // capability the change carries no delta for is one line, not one
+    // break per capability. Its exit code is
     // discarded on purpose — the step is declared advisory, and an advisory
     // step that could still move the close's result would be advisory in name
     // only. A crash is caught by the loop and reported the same way.
     review: {
       run: async () => {
-        await review.run([], new Map());
+        await review.run([], new Map([["change", id]]));
         return 0;
       },
     },
@@ -233,7 +294,10 @@ async function closeOne(projectRoot, id, flags) {
     // verify is conditional: skipped with a loud note when no verify.json is
     // declared, because a project may not have wired the real gate yet.
     verify: verifyConfigured
-      ? { run: () => verify.run([], new Map()) }
+      // --reuse (change 0203): the suite the agent just ran by hand, or the
+      // one the previous id of this batch ran, on byte-identical code, is
+      // not run a second time. Anything that differs runs everything.
+      ? { run: () => verify.run([], new Map([["reuse", true]])) }
       : { skip: "no .doctrina/verify.json — declare the real gate with `doctrina verify --init`" },
 
     coverage: {
@@ -257,10 +321,26 @@ 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) {
+            // One line when both answers are the same sentence (change 0202):
+            // "touches no documented surface" twice read as two checks.
+            if (log.reason !== r.reason) 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 +348,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 +373,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()) },
   };
 
@@ -369,16 +466,6 @@ async function closeOne(projectRoot, id, flags) {
     }
   }
 
-  // Capture the lesson while it is fresh (operator review §4.7): surface the
-  // fix-shaped lessons not yet written as skills, right where the operator
-  // just proved they finish what they start. Advisory — a listing, never a
-  // gate, and a suggest failure never un-closes the change.
-  console.log("");
-  console.log(c.gray("──── skills (advisory)"));
-  try {
-    await skill.run(["suggest"], new Map());
-  } catch { /* advisory only */ }
-
   console.log("");
   console.log(c.green(`✓ change ${id} closed`) + c.gray(closingClaim(ran, skippedSteps)));
   console.log(c.gray("Next: ") + c.cyan("doctrina next"));
@@ -449,14 +536,27 @@ function reportDependentCoverage(projectRoot, touched) {
 }
 
 function touchedCapabilities(projectRoot, id) {
-  const specsDir = path.join(projectRoot, ".doctrina", "changes", id, "specs");
-  const caps = new Set();
-  for (const deltaPath of walk(specsDir)) {
-    if (!deltaPath.endsWith("delta.md")) continue;
-    const cap = parseCapabilityFromDelta(read(deltaPath), deltaPath);
-    if (cap) caps.add(cap);
+  return deltaCapabilities(path.join(projectRoot, ".doctrina", "changes", id));
+}
+
+// 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;
   }
-  return [...caps].sort();
+  if (line !== "") lines.push(indent + line);
+  return lines.join("\n");
 }
 
 export const help = `
@@ -465,9 +565,11 @@ 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 two advisory notes, once per run: the skill candidate a just-closed
+fix-shaped change produced (the others are a count), and the other open
+changes that look finished or are a week old.
 
 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 +583,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

package/src/commands/decision.js

@@ -152,8 +152,20 @@ function decisionSupersede(args) {
   });
   // Inject Supersedes link
   body = body.replace(/(\*\*Supersedes:\*\*)\s+—/, `$1 ${padded}`);
+  // Carry the predecessor's Scope. A successor built from the bare template
+  // had none, so it was GLOBAL: refining a decision that governed one
+  // capability, then accepting the refinement, loaded it into every
+  // capability's pack — ones the original never governed — and nothing said
+  // so. A replacement decides the same subject; its scope starts where the
+  // predecessor's was, written into the file where the author can widen it
+  // on purpose (ADR 0022: a pack is retrieval, not a dump).
+  const inheritedScope = parseAdrScope(oldText);
+  if (inheritedScope.length > 0) body = insertScopeHeader(body, inheritedScope) ?? body;
   write(newPath, body, { force: false });
   console.log(c.green("created") + ` ${relPath(projectRoot, newPath)}`);
+  if (inheritedScope.length > 0) {
+    console.log(c.gray("scope: ") + `inherited from ${padded} — ${inheritedScope.join(", ")} (edit the Scope: header to change it)`);
+  }
 
   // Mutate ONLY the Status: and Superseded by: headers of the old ADR.
   // Both go through the document model, so an ADR written with a slightly

package/src/commands/doctor.js

@@ -188,7 +188,7 @@ export async function run(_positional, _flags) {
         ? tmplFindings[0].message
         : `${tmplFindings.length} template findings`;
       const remedy = [...byRemedy.keys()].filter((k) => k !== "(manual repair)");
-      row("warn", "templates", summary, remedy.length === 1 ? remedy[0] : "doctrina templates check   (each finding names its own fix)");
+      row("warn", "templates", summary, remedy.length === 1 ? remedy[0] : "doctrina upgrade   (each finding names its own fix)");
       warningsTotal += 1;
     },
 

package/src/commands/hooks.js

@@ -10,6 +10,7 @@ const here = path.dirname(fileURLToPath(import.meta.url));
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
+import { EXIT } from "../lib/exit-codes.js";
 
 const SUBCOMMANDS = ["install"];
 
@@ -33,8 +34,12 @@ export async function run(positional, flags) {
   const projectRoot = process.cwd();
 
   if (!exists(path.join(projectRoot, ".git"))) {
+    // A PRECONDITION, not a gate: nothing was measured and found wanting,
+    // the place to put the hook simply does not exist yet. Class 1 told an
+    // agent to fix its work and retry the same command, which never clears.
     console.error(c.red("error:") + " not a git repository (no .git/ in cwd)");
-    return 1;
+    console.error(c.gray("hint: ") + "run `git init` here, then `doctrina hooks install`");
+    return EXIT.PRECONDITION;
   }
 
   const hooksDir = path.join(projectRoot, ".git", "hooks");

package/src/commands/index-rebuild.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import process from "node:process";
 import { exists } from "../lib/fs-ops.js";
 import * as idx from "../lib/index-json.js";
-import { collectIndexDrift } from "../lib/scan.js";
+import { collectIndexDrift, collectStagedIndexDrift } from "../lib/scan.js";
 import { today } from "../lib/dates.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
@@ -15,7 +15,7 @@ const SUBCOMMANDS = ["rebuild"];
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
 // let six flags ship undeclared and silently swallow a positional (C3).
-export const flags = { boolean: ["json", "check"], string: [] };
+export const flags = { boolean: ["json", "check", "staged"], string: [] };
 
 export async function run(positional, flags) {
   const sub = positional[0];
@@ -32,11 +32,21 @@ export async function run(positional, flags) {
 
 function rebuild(flags) {
   const check = flagBool(flags, "check", false);
+  const staged = flagBool(flags, "staged", false);
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
 
+  if (staged) {
+    if (!check) {
+      console.error(c.red("error:") + " --staged reads the commit, so it can only check; it never writes");
+      console.error(c.gray("hint: ") + "run `doctrina index rebuild --check --staged`");
+      return 2;
+    }
+    return checkStaged(projectRoot);
+  }
+
   const state = collectIndexDrift(projectRoot);
   if (state.unreadable) {
     if (check) {
@@ -70,6 +80,39 @@ function rebuild(flags) {
   return 0;
 }
 
+// The drift check, asked of what git will record. `index.json` is derived
+// from the WHOLE tree, so it cannot describe a subset of it: stage part of
+// `.doctrina/` and the index riding along names artifacts the commit does
+// not carry. Every other gate reads the working tree, where those artifacts
+// are still sitting, so none of them can see it.
+function checkStaged(projectRoot) {
+  const state = collectStagedIndexDrift(projectRoot);
+  if (!state.applicable) {
+    console.log(c.green("ok") + ` nothing to check — ${state.reason}`);
+    return 0;
+  }
+  if (state.ok) {
+    console.log(c.green("ok") + " the staged index matches the staged tree");
+    return 0;
+  }
+  if (state.reason) {
+    console.error(c.red("error:") + ` ${state.reason}`);
+    return 1;
+  }
+  for (const p of state.missing) {
+    console.log(c.yellow("staged: ") + `${p} — named by the staged index, absent from the commit`);
+  }
+  for (const p of state.unindexed) {
+    console.log(c.yellow("staged: ") + `${p} — in the commit, absent from the staged index`);
+  }
+  const n = state.missing.length + state.unindexed.length;
+  console.log("");
+  console.log(c.red("fail") + ` the staged index does not describe this commit (${n} difference${n === 1 ? "" : "s"})`);
+  console.log(c.gray("hint: ") + "stage the artifacts above with the index, or unstage the index — "
+    + "index.json is derived from the whole tree, so a partial commit of .doctrina/ cannot carry a matching one");
+  return 1;
+}
+
 export const help = `
 Usage: doctrina index <subcommand>
 
@@ -80,6 +123,13 @@ Subcommands:
                     source of truth; the index is derived.
   rebuild --check   Write nothing; exit 1 with a drift summary when the
                     index no longer matches the tree. CI-friendly.
+  rebuild --check --staged
+                    Ask the same question of the COMMIT rather than the
+                    disk: every artifact the staged index names must be in
+                    the commit, and every staged artifact must be in the
+                    index. A partial commit of .doctrina/ cannot satisfy
+                    both, because the index is derived from the whole tree.
+                    Exits 0 when nothing relevant is staged.
 
 Fields with no on-disk source (project name, framework_version, product
 metadata) are carried over from the existing index.

package/src/commands/init.js

@@ -14,7 +14,7 @@ import { flagBool, flagString, flagGivenWithoutValue } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { EXIT } from "../lib/exit-codes.js";
 import { ask, isInteractive } from "../lib/prompt.js";
-import { looksLikePath, writeIntakeFile, printBootstrapPlaybook, warnIfThinIntake } from "../lib/intake-model.js";
+import { looksLikePath, writeIntakeFile, printBootstrapPlaybook, warnIfThinIntake, nextStepAfterInit } from "../lib/intake-model.js";
 
 const SUPPORTED_AGENTS = [
   "claude",
@@ -107,9 +107,20 @@ export async function run(_positional, flags) {
   // isTTY check the adapter prompt already had. A non-interactive caller
   // that forgot --non-interactive read EOF, got an empty answer, and
   // scaffolded a project with a blank description — silently (C9).
+  // At a terminal, ONE question, and its answer is the intake (change 0173):
+  // it was asked as a one-line description, written into product.md, and
+  // then `next` asked for the same thing again as an intake. A person
+  // describes the project once.
+  let intakeFromTty = false;
   if (!description && !nonInteractive) {
     if (isInteractive()) {
-      description = await ask("One-sentence project description:");
+      const answer = await ask("Describe the project — what it is, who it is for, what it must do:");
+      if (answer && answer.trim() !== "") {
+        intakeBody = answer.trim();
+        intakeSource = "typed at `doctrina init`";
+        intakeFromTty = true;
+        description = firstLineSummary(intakeBody);
+      }
     }
     if (!description) {
       console.error(c.red("error:") + " no project description given and no terminal to ask on");
@@ -293,7 +304,11 @@ export async function run(_positional, flags) {
 
   console.log("");
   console.log(c.bold("Doctrina initialised."));
-  if (intakeBody) {
+  if (intakeFromTty) {
+    // A person at a terminal gets the one instruction, not the agent's
+    // playbook: the agent reprints it with `doctrina intake`.
+    for (const line of nextStepAfterInit("tty")) console.log(line);
+  } else if (intakeBody) {
     console.log(`Next: execute the bootstrap playbook below — it converts the intake into`);
     console.log(`${c.cyan(".doctrina/product.md")} and capability specs. Any AGENTS.md-aware agent`);
     console.log(`runs it on its own; reprint anytime with ${c.cyan("doctrina intake")}.`);
@@ -301,7 +316,7 @@ export async function run(_positional, flags) {
     warnIfThinIntake(intakeBody);
     printBootstrapPlaybook(projectRoot);
   } else {
-    console.log(`Next: edit ${c.cyan("AGENTS.md")} and ${c.cyan(".doctrina/product.md")} for your project.`);
+    for (const line of nextStepAfterInit(null)) console.log(line);
   }
   return 0;
 }

package/src/commands/intake.js

@@ -2,17 +2,19 @@
 import path from "node:path";
 import process from "node:process";
 import { exists, isFile, read, relPath, write } from "../lib/fs-ops.js";
+import { ensureDoctrinaProject, projectName } from "../lib/project.js";
 import { listHeader } from "../lib/scan.js";
 import { assessBrief } from "../lib/clarity.js";
 import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
-import { looksLikePath, warnIfThinIntake, writeIntakeFile, printBootstrapPlaybook } from "../lib/intake-model.js";
+import { looksLikePath, markIntakeConverted, printBootstrapPlaybook, warnIfThinIntake, writeIntakeFile } from "../lib/intake-model.js";
 
 // `init --intake` performs the same operations; they live in
 // lib/intake-model.js so neither command imports out of the other (F7).
 export { warnIfThinIntake, writeIntakeFile, printBootstrapPlaybook } from "../lib/intake-model.js";
+import { collectValidation } from "../lib/validation-model.js";
 import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 
 // `intake` is the first half of the no-ceremony path (ADR 0005): store the
@@ -24,10 +26,47 @@ import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
 // let six flags ship undeclared and silently swallow a positional (C3).
-export const flags = { boolean: ["json", "force"], string: ["text"] };
+export const flags = { boolean: ["json", "force", "converted"], string: ["text"] };
 
 export async function run(positional, flags) {
   const projectRoot = process.cwd();
+
+  // Close the bootstrap through the CLI, not by hand.
+  //
+  // Step 7 of the playbook used to read "flip Status to converted in
+  // .doctrina/intake.md" — the one place this framework told an agent to
+  // hand-author a metadata header, against its own standing rule, and the one
+  // header nothing read back. A mistyped word left `next` asking forever for
+  // a bootstrap that was already done.
+  if (flagBool(flags, "converted", false)) {
+    ensureDoctrinaProject(projectRoot);
+    // Converting is the claim that the bootstrap is done — step 6 of the
+    // playbook, "fix everything the gates report", made checkable (change
+    // 0194). It used to convert over a tree `validate` failed, so the specs
+    // became "the source of truth" while an error still said they were not
+    // well-formed. --force converts anyway, for a tree whose errors are not
+    // the bootstrap's to fix.
+    if (isFile(path.join(projectRoot, ".doctrina", "intake.md")) && !flagBool(flags, "force", false)) {
+      const { errors } = collectValidation(projectRoot);
+      if (errors.length > 0) {
+        console.error(c.red("error:") + ` the bootstrap is not done — \`doctrina validate\` reports ${errors.length} error${errors.length === 1 ? "" : "s"}:`);
+        for (const e of errors.slice(0, 5)) console.error("  - " + e);
+        if (errors.length > 5) console.error(`  … and ${errors.length - 5} more`);
+        console.error(c.gray("hint: ") + "fix them (`doctrina validate --fix` heals index drift), then rerun; `--force` converts anyway");
+        return EXIT.GATE;
+      }
+    }
+    const written = markIntakeConverted(projectRoot);
+    if (!written) {
+      console.error(c.red("error:") + " no intake to mark converted at .doctrina/intake.md");
+      console.error(c.gray("hint: ") + 'store one first: `doctrina intake --text "<description>"`');
+      return EXIT.PRECONDITION;
+    }
+    console.log(c.green("converted") + ` ${relPath(projectRoot, written)} — specs are the source of truth now`);
+    console.log(c.gray("next: ") + 'doctrina next');
+    return EXIT.OK;
+  }
+
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
@@ -102,8 +141,8 @@ export async function run(positional, flags) {
     return EXIT.PRECONDITION;
   }
 
-  const projectName = idx.load(projectRoot).project ?? path.basename(projectRoot);
-  writeIntakeFile(projectRoot, { body, source, projectName, date: today(), force });
+  const name = projectName(projectRoot);
+  writeIntakeFile(projectRoot, { body, source, projectName: name, date: today(), force });
   console.log(c.green("created") + ` ${relPath(projectRoot, intakePath)}`);
   console.log("");
   warnIfThinIntake(body);
@@ -127,11 +166,20 @@ Forms:
   doctrina intake --text "<text>"     Ingest an inline description
   doctrina intake                     Reprint the playbook for the
                                       existing pending intake
+  doctrina intake --converted         Close the bootstrap: flip the stored
+                                      intake's Status to converted
 
 Options:
   --text "<description>"   Inline description instead of a file
-  --force                  Overwrite an existing .doctrina/intake.md
+  --force                  Overwrite an existing .doctrina/intake.md; with
+                           --converted, convert although validate fails
+  --converted              Mark the stored intake converted (ends the
+                           bootstrap; nothing else writes that header).
+                           Refuses (exit 1) while validate reports an error
 
-After conversion the agent flips the intake header to
-"- **Status:** converted"; specs become the only source of truth.
+Close the bootstrap with \`doctrina intake --converted\` rather than editing
+the header by hand: \`next\` branches on that value, and \`validate\` reports a
+Status that is neither pending nor converted, because every other word read
+as pending in silence. After conversion the specs are the only source of
+truth.
 `;