doctrina-cli 0.15.1 → 0.16.0

package/src/lib/fs-ops.js

@@ -2,8 +2,26 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, renameSync, unlinkSync, rmdirSync } from "node:fs";
 import path from "node:path";
 
+// Every module reads a file through here, so the byte-order mark is removed
+// here — once, at the door (third audit, finding 5).
+//
+// A spec saved by a Windows editor opens `# Spec — …`, and `validate`
+// reported "carries no title" while `show`, `spec list` and `coverage` read
+// the same file without complaint: the surfaces disagreed about a file none
+// of them had a problem with. The mark is an encoding artifact of how the
+// bytes were stored, not something the Doctrina grammar has an opinion
+// about, so no parser downstream should have to know it exists.
+//
+// It matters beyond Markdown: `JSON.parse` throws on a leading BOM, so an
+// `index.json` written by the wrong editor was unreadable with an error
+// that named neither the cause nor the file.
+//
+// A file that had one loses it when a command rewrites it. That is a
+// normalisation, and the right one — nothing in this tree is served by
+// keeping it.
 export function read(p) {
-  return readFileSync(p, "utf8");
+  const text = readFileSync(p, "utf8");
+  return text.charCodeAt(0) === 0xFEFF ? text.slice(1) : text;
 }
 
 export function write(p, content, { force = false } = {}) {
@@ -53,6 +71,45 @@ export function remove(p) {
   }
 }
 
+/**
+ * Remove `dir` and each ancestor of it, walking up, for as long as each one
+ * is EMPTY — stopping at the first directory that still holds something, and
+ * never touching `stopAt` itself or anything outside it.
+ *
+ * The asymmetry this closes: a command that creates a directory with
+ * `mkdirp` on the way in has to unmake it on the way out, or "remove" leaves
+ * a configuration root behind. An EMPTY directory is the safe case to
+ * delete — there is nothing of anyone else's in it — which is why this
+ * stops at the first non-empty one rather than recursing.
+ *
+ * @param {string} dir     The innermost directory to consider.
+ * @param {string} stopAt  Boundary, never removed and never escaped.
+ * @returns {string[]} The directories removed, innermost first.
+ */
+export function pruneEmptyDirs(dir, stopAt) {
+  const removed = [];
+  const boundary = path.resolve(stopAt);
+  let cur = path.resolve(dir);
+  while (cur !== boundary && cur.startsWith(boundary + path.sep)) {
+    if (!isDir(cur)) break;
+    let entries;
+    try {
+      entries = readdirSync(cur);
+    } catch {
+      break;
+    }
+    if (entries.length > 0) break;
+    try {
+      rmdirSync(cur);
+    } catch {
+      break;
+    }
+    removed.push(cur);
+    cur = path.dirname(cur);
+  }
+  return removed;
+}
+
 // Recursive file walk. Returns absolute paths of every regular file.
 export function walk(root) {
   const out = [];

package/src/lib/gates.js

@@ -1,10 +1,11 @@
 // @ts-check
-import { getSection } from "./doc-model.js";
+import { checklistProgress, getSection } from "./doc-model.js";
 import path from "node:path";
 import { appendFileSync, writeFileSync } from "node:fs";
 import { exists, isFile, mkdirp, read } from "./fs-ops.js";
 import { today } from "./dates.js";
-import { collectAnalysis } from "../commands/analyze.js";
+import { collectAnalysis } from "./analysis.js";
+import { appendLedgerLine, forcedLine } from "./ledger.js";
 
 // The gate-to-transition map (audit item C6).
 //
@@ -64,7 +65,9 @@ export const GATES = {
     rerun: (id) => `doctrina change tick ${id}`,
     blockers(projectRoot, changeDir) {
       const out = [];
-      const countUnchecked = (s) => (s.match(/^\s*-\s*\[ \]/gm) ?? []).length;
+      // Same counter as every other surface (change 0067).
+      const countUnchecked = (text, section = null) =>
+        checklistProgress(text, { section }).total - checklistProgress(text, { section }).done;
 
       const tasksPath = path.join(changeDir, "tasks.md");
       if (isFile(tasksPath)) {
@@ -73,7 +76,7 @@ export const GATES = {
       }
       const proposalPath = path.join(changeDir, "proposal.md");
       if (isFile(proposalPath)) {
-        const n = countUnchecked(getSection(read(proposalPath), "Verification"));
+        const n = countUnchecked(read(proposalPath), "Verification");
         if (n > 0) out.push(`${n} unmet verification item${n === 1 ? "" : "s"} in proposal.md (## Verification)`);
       }
       return out;
@@ -105,6 +108,175 @@ export const TRANSITIONS = {
   archive: { label: "change archive", gates: ["integrity", "verification"] },
 };
 
+// ---------------------------------------------------------------------------
+// The gate SEQUENCES (audit finding F1)
+// ---------------------------------------------------------------------------
+//
+// ADR 0017 promised ONE gate map. TRANSITIONS above delivered it for the two
+// mutating transitions and stopped there: `close` carried a literal array of
+// ten steps, `doctor` eight hand-written rows, and `action.yml` five YAML
+// steps. Four lists, four owners, and nothing that noticed when they
+// diverged — which is how the runtime gate could land in `close` and stay
+// absent from CI (change 0033 had to add it to both by hand, and nothing
+// would have caught it if the second edit had been forgotten).
+//
+// So a sequence is DATA. Each step declares what it is, how hard it bites,
+// and the command that runs it standalone. The surfaces only RENDER it:
+// `close` executes it in order, `doctor` reports each as a row, and
+// `doctrina ci --emit github` writes it as CI YAML. None of them may invent
+// a step, drop one, or reorder — a drift test holds each surface to this
+// declaration, and the emitted YAML to the versioned `action.yml`.
+//
+// What this does NOT decide is which gates belong in a sequence; it declares
+// the sequences that exist so that the answer lives in one file.
+
+/**
+ * One step of a gate sequence.
+ *
+ * @typedef {object} GateStep
+ * @property {string} id        Stable key. The surfaces bind their renderer/runner to it.
+ * @property {string} label     What the surface calls the step.
+ * @property {"blocking"|"advisory"|"forceable"} level
+ *   blocking  — a non-zero result stops the sequence.
+ *   advisory  — reported, never stops anything.
+ *   forceable — blocking, unless --force, which records the gap in the ledger.
+ * @property {string[]|null} argv
+ *   The standalone CLI invocation this step is, or null when the step is not
+ *   one command (the ADR checkpoint, the docs gate). The token "<id>" is
+ *   replaced with the change id at render time.
+ * @property {string} [rerun]   Literal rerun line, for a step argv cannot describe.
+ * @property {string} [why]     One line of rationale. The CI emitter writes it as a comment.
+ * @property {boolean} [strict] CI only: the command takes --strict when the action runs strict.
+ * @property {string} [script]  CI only: a shell body that replaces the derived one-liner.
+ * @property {string} [flag]    Only run/report this step when that flag is set.
+ * @property {string} [short]   CI only: the name used in the action's own description.
+ * @property {string} [summary] CI only: the name plus what it checks, for the file header.
+ */
+
+/** @type {Record<string, GateStep[]>} */
+export const SEQUENCES = {
+  // The closing sequence. `close` runs these in order, in-process where it
+  // can, stopping at the first blocking failure with the step's rerun line.
+  close: [
+    { id: "analyze", label: "analyze", level: "blocking", argv: ["analyze", "<id>"] },
+    { id: "adr-checkpoint", label: "ADR checkpoint (advisory)", level: "advisory", argv: ["decision", "list"] },
+    // Conformance review (audit finding F3). It is the richest analysis the
+    // project has — capabilities whose code moved while their spec did not,
+    // affected dependants, dangling coverage — and no driver invoked it, so
+    // it only ever happened when somebody typed the command.
+    //
+    // BEFORE the apply, deliberately: that is the point where its findings can
+    // still change what gets written. Advisory for now — it raises a break for
+    // every capability with touched code and a still spec, and that noise has
+    // to be measured before it is allowed to refuse. `review --strict` remains
+    // the door for a project that wants CI to block on it.
+    { id: "review", label: "review (advisory)", level: "advisory", argv: ["review"] },
+    { id: "apply", label: "apply", level: "blocking", argv: ["change", "apply", "<id>"] },
+    { id: "runtime", label: "runtime", level: "blocking", argv: ["contract", "check"] },
+    { id: "implementation", label: "implementation (advisory)", level: "advisory", argv: null, rerun: "doctrina spec set <cap> --implementation auto" },
+    { id: "verify", label: "verify", level: "blocking", argv: ["verify"] },
+    { id: "coverage", label: "coverage", level: "blocking", argv: ["coverage", "--strict"] },
+    { id: "trace", label: "trace", level: "advisory", argv: ["trace"] },
+    { id: "docs", label: "docs", level: "forceable", argv: null, rerun: "document the change, then rerun" },
+    { id: "archive", label: "archive", level: "blocking", argv: ["change", "archive", "<id>"] },
+    { id: "validate", label: "validate", level: "blocking", argv: ["validate"] },
+  ],
+
+  // The diagnostic sequence. Every row is advisory in the sense that `doctor`
+  // never mutates anything; the level says whether the row counts as a
+  // failing area (exit 1) or an advisory one (exit 0).
+  doctor: [
+    { id: "validate", label: "validate", level: "blocking", argv: ["validate"] },
+    { id: "index", label: "index", level: "blocking", argv: ["index", "rebuild", "--check"] },
+    { id: "coverage", label: "coverage", level: "advisory", argv: ["coverage"] },
+    { id: "trace", label: "trace", level: "advisory", argv: ["trace"] },
+    { id: "clean-checkout", label: "clean-checkout", level: "blocking", argv: ["verify", "--clean"] },
+    { id: "templates", label: "templates", level: "advisory", argv: ["templates", "check"] },
+    { id: "runtime", label: "runtime", level: "blocking", argv: ["contract", "check"] },
+    { id: "local-env", label: "local .env", level: "blocking", argv: null, rerun: "doctrina doctor --env", flag: "env" },
+    { id: "verify-config", label: "verify config", level: "blocking", argv: ["verify", "--init"] },
+    // The declared size budgets, and the headroom left. Reported BEFORE either
+    // is breached: `agents-md-lines` is OUTPUT, so `analyze` refuses the
+    // raise-the-ceiling fix, and the generated surface block lives inside
+    // AGENTS.md — one command added spends a line of both (change 0072).
+    { id: "budgets", label: "budgets", level: "advisory", argv: null, rerun: "doctrina validate" },
+    // Not a check — a READOUT. Every other row can fail; this one exists
+    // because a project could not see what it had configured without reading
+    // the CLI's source, which is how a pt-BR project sat red under `clarify`
+    // with no clue why (change 0047). Advisory: a default is not a fault.
+    { id: "config", label: "config", level: "advisory", argv: null, rerun: "edit .doctrina/config.json" },
+    // Also a readout, and also advisory. It appears only when the operator
+    // has switched the usage log on: an instrument that is off has nothing
+    // to say, and a row saying so every run would train the reader to skip
+    // the section (change 0050).
+    { id: "usage", label: "usage", level: "advisory", argv: null, rerun: "doctrina metrics --commands" },
+  ],
+
+  // The CI sequence, emitted as the composite action. Deliberately WITHOUT
+  // `verify`: the build gate is the adopting project's own to run, and the
+  // action exists to check the artifact tree.
+  ci: [
+    { id: "validate", label: "doctrina validate", level: "blocking", argv: ["validate"], short: "validate", summary: "validate (schema/structure)" },
+    { id: "index-drift", label: "doctrina index rebuild --check", level: "blocking", argv: ["index", "rebuild", "--check"], short: "index drift", summary: "index rebuild --check (index ↔ tree drift)" },
+    {
+      id: "contract-check",
+      label: "doctrina contract check",
+      level: "blocking",
+      argv: ["contract", "check"],
+      short: "contract check",
+      summary: "contract check (the declared runtime surface, RT01-RT05)",
+      why:
+        "The runtime gate (RT01-RT05). Every other step reads Markdown; this one\n" +
+        "reads what the Markdown CLAIMS about the running system and holds the\n" +
+        "implementation to it — the variable no workflow exports, the default an\n" +
+        "empty CI value never triggers, the unvalidated enum, the selector that\n" +
+        "matches nothing and still exits 0. Not gated on `strict`: a declaration\n" +
+        "that does not hold is an error at any adoption stage. A project with no\n" +
+        "contracts prints one line and exits 0.",
+    },
+    { id: "coverage", label: "doctrina coverage", level: "blocking", argv: ["coverage"], strict: true, short: "coverage", summary: "coverage (acceptance-criteria evidence)" },
+    { id: "trace", label: "doctrina trace", level: "blocking", argv: ["trace"], strict: true, short: "trace", summary: "trace (intent provenance)" },
+    {
+      id: "context-budget",
+      label: "doctrina context (budget)",
+      level: "blocking",
+      argv: ["context"],
+      short: "context budget",
+      summary: "context (the pack budget, ADR 0022)",
+      why:
+        "The context budget (ADR 0022). A pack that degrades to fit is fine; this\n" +
+        "fails only when a pack's irreducible core no longer fits at all, which\n" +
+        "means a spec has outgrown itself or a change has gone stale. Configure\n" +
+        "the ceiling per project with \"context_budget\": n in\n" +
+        ".doctrina/config.json.",
+      script:
+        "{{PREFIX}} context >/dev/null\n" +
+        "for cap in $(ls .doctrina/specs 2>/dev/null); do\n" +
+        "  {{PREFIX}} context \"$cap\" >/dev/null\n" +
+        "done",
+    },
+  ],
+};
+
+/** The declared steps of a sequence, or an error naming the ones that exist. */
+export function sequence(name) {
+  const steps = SEQUENCES[name];
+  if (!steps) throw new Error(`unknown gate sequence "${name}" (declared: ${Object.keys(SEQUENCES).join(", ")})`);
+  return steps;
+}
+
+/**
+ * The command that runs one step on its own — what a surface prints when it
+ * tells the operator how to clear the gate. Derived from `argv` so the
+ * declaration cannot disagree with itself; `rerun` covers the steps that are
+ * not a single command.
+ */
+export function stepRerun(step, changeId = "<id>") {
+  if (step.rerun) return step.rerun;
+  if (!step.argv) return `doctrina ${step.id}`;
+  return `doctrina ${step.argv.map((a) => (a === "<id>" ? changeId : a)).join(" ")}`;
+}
+
 // Evaluate a transition's gates. Returns { ok, blockers, gates } where
 // blockers is a flat list of human-readable reasons.
 export function checkTransition(projectRoot, changeDir, transition) {
@@ -123,25 +295,11 @@ export function checkTransition(projectRoot, changeDir, transition) {
 // waved through is part of the visible history rather than nothing at all
 // — the same posture `change archive --force` and `change abandon` take.
 export function recordForcedGap(projectRoot, id, transition, blockers) {
-  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
-  const ledgerPath = path.join(archiveDir, "LEDGER.md");
-  // Create the ledger if this is the first entry. A forced transition can
-  // happen before any change has ever been archived, and a gap that goes
-  // unrecorded because the file did not exist yet is exactly the silence
-  // this is meant to break.
-  if (!exists(ledgerPath)) {
-    mkdirp(archiveDir);
-    writeFileSync(ledgerPath,
-      "# Change ledger\n\n" +
-      "One line per archived change, newest last. Appended by\n" +
-      "`doctrina change archive`; edit freely, the CLI only appends.\n\n");
-  }
-  const summary = blockers.map((b) => `${b.gate}: ${b.message}`).join("; ");
-  appendFileSync(
-    ledgerPath,
-    `  - ${today()} — ${id} — forced ${transition} past ${blockers.length} ` +
-    `blocker${blockers.length === 1 ? "" : "s"} (${summary})\n`,
-  );
+  // The ledger owns its own format and its own creation (lib/ledger.js): a
+  // forced transition can happen before any change has ever been archived,
+  // and a gap that goes unrecorded because the file did not exist yet is
+  // exactly the silence this is meant to break.
+  appendLedgerLine(projectRoot, forcedLine(id, transition, blockers));
   return true;
 }
 

package/src/lib/git.js

@@ -69,6 +69,23 @@ export function hasCommits(cwd) {
   return git(cwd, ["rev-parse", "--verify", "HEAD"]).state === GIT_STATE.OK;
 }
 
+/**
+ * Does this ref resolve to a commit in this repository?
+ *
+ * Asked directly, because the message heuristic above cannot answer it: git
+ * says "unknown revision or path not in the working tree" both for a
+ * repository with no commits and for a ref that does not exist, so a diff
+ * against a missing ref came back as GIT_STATE.EMPTY and every caller read
+ * it as "nothing changed". `doctrina review --diff main --strict` therefore
+ * passed on a shallow clone with no local `main` (change 0092).
+ *
+ * False when git is absent, this is not a repository, or the ref is unknown —
+ * callers that need to tell those apart ask `historyState` as well.
+ */
+export function refExists(cwd, ref) {
+  return git(cwd, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]).state === GIT_STATE.OK;
+}
+
 // The state a command should report before trying to read history:
 // { usable, state, reason } where `reason` is a sentence fit to print.
 export function historyState(cwd) {
@@ -95,3 +112,118 @@ export function gitLines(cwd, args) {
 function splitLines(s) {
   return s.split(/\r?\n/).map((x) => x.trim()).filter(Boolean);
 }
+
+// ---------------------------------------------------------------------------
+// The period window the report view describes (change 0037)
+// ---------------------------------------------------------------------------
+//
+// `report` shelled out to git twice with its own spawnSync, which is the one
+// pattern this module exists to end: a caller that reads a non-zero exit as
+// "no commits" rather than "the command refused". Both probes go through
+// `git()` here, so an absent binary, a non-repository and a real failure stay
+// distinguishable — and the view above stays a pure formatter.
+
+/** The ISO date `days` ago — the left edge of a report window. */
+export function windowCutoff(days) {
+  return new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+}
+
+/**
+ * Commits, fix-shaped share and top-churn files in the window.
+ * Returns null when there is no history to read — outside a repository, with
+ * git absent, or before the first commit — so the caller can say so rather
+ * than print a confident zero.
+ */
+export function gitWindow(cwd, days) {
+  const since = `--since=${days} days ago`;
+  const log = git(cwd, ["log", since, "--pretty=%s"]);
+  if (log.state !== GIT_STATE.OK) return null;
+  const subjects = log.lines.filter((l) => l.trim().length > 0);
+  const fixes = subjects.filter((sub) => /^(fix|bug|hotfix|patch)(\(|:|!)/i.test(sub)).length;
+
+  const files = git(cwd, ["log", since, "--name-only", "--pretty=format:"]);
+  const counts = new Map();
+  if (files.state === GIT_STATE.OK) {
+    for (const line of files.lines) {
+      const f = line.trim();
+      if (!f) continue;
+      counts.set(f, (counts.get(f) ?? 0) + 1);
+    }
+  }
+  const churn = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5);
+  return { commits: subjects.length, fixes, churn };
+}
+
+// ---------------------------------------------------------------------------
+// Changed files: the one answer, four callers (audit finding F5)
+// ---------------------------------------------------------------------------
+//
+// `work`, `review`, `context` and `docs-impact` each carried their own
+// "which files changed" — four spawnSync helpers, four slightly different
+// answers, and each one reading a non-zero exit as an empty list rather than
+// a refusal. The semantics that genuinely differ between them are OPTIONS
+// here, not separate implementations: `docs-impact` needs the merge-base so a
+// branch's earlier commits count, `context --diff` compares against a named
+// ref, and a review against a ref does not want untracked files mixed in.
+
+/**
+ * The files that changed, as the caller defines "changed".
+ *
+ * @param {string} cwd
+ * @param {object} [opts]
+ * @param {string|null} [opts.since]      Compare against this ref instead of HEAD.
+ * @param {boolean} [opts.untracked]      Include untracked, non-ignored files (default true).
+ * @param {boolean} [opts.mergeBase]      Also include everything since the merge-base with the
+ *                                        default branch, so a branch's earlier commits count.
+ * @param {string[]} [opts.bases]         Which branch names to try as the merge-base target.
+ * @returns {{ ok: boolean, files: string[], state: string }}
+ *   `ok` is false when git could not answer — outside a repository, with git
+ *   absent, or on a real failure. A caller that treats "not ok" as "nothing
+ *   changed" is making the mistake this door exists to prevent, so the state
+ *   is returned rather than folded into an empty list.
+ */
+export function changedFiles(cwd, { since = null, untracked = true, mergeBase = false, bases = ["main", "master"] } = {}) {
+  const out = new Set();
+  const add = (r) => {
+    for (const line of r.lines) {
+      const p = line.trim();
+      if (p) out.add(p.replace(/\\/g, "/"));
+    }
+  };
+
+  const diff = git(cwd, since ? ["diff", "--name-only", since, "--"] : ["diff", "--name-only", "HEAD"]);
+  if (diff.state !== GIT_STATE.OK) return { ok: false, files: [], state: diff.state };
+  add(diff);
+
+  if (untracked) {
+    const others = git(cwd, ["ls-files", "--others", "--exclude-standard"]);
+    if (others.state === GIT_STATE.OK) add(others);
+  }
+
+  if (mergeBase) {
+    for (const base of bases) {
+      const mb = git(cwd, ["merge-base", "HEAD", base]);
+      if (mb.state === GIT_STATE.OK && mb.lines[0]) {
+        const since = git(cwd, ["diff", "--name-only", `${mb.lines[0].trim()}..HEAD`]);
+        if (since.state === GIT_STATE.OK) add(since);
+        break;
+      }
+    }
+  }
+
+  return { ok: true, files: [...out].sort(), state: GIT_STATE.OK };
+}
+
+/**
+ * The date of the most recent tag, as YYYY-MM-DD, or null.
+ *
+ * The left edge of "what has landed since the last release". Null when there
+ * is no tag, no history, or no repository — the caller then has to say which
+ * window it used rather than pretend there was one.
+ */
+export function lastTagDate(cwd) {
+  const tags = gitLines(cwd, ["for-each-ref", "--sort=-creatordate", "--count=1",
+    "--format=%(creatordate:short)", "refs/tags"]);
+  const date = tags[0] ?? "";
+  return /^\d{4}-\d{2}-\d{2}$/.test(date) ? date : null;
+}

package/src/lib/index-json.js

@@ -1,7 +1,7 @@
 // @ts-check
 import path from "node:path";
 import { read, write, exists } from "./fs-ops.js";
-import { cliVersion } from "./version.js";
+import { cliVersion, newestVersion } from "./version.js";
 
 export const SCHEMA_VERSION = "0.1.0";
 
@@ -39,7 +39,7 @@ export function save(projectRoot, index) {
   // records which CLI last wrote it, so a stale stamp (an index written by an
   // older CLI) is detectable by `doctrina validate` and migrated by
   // `doctrina index rebuild`.
-  index.framework_version = cliVersion();
+  index.framework_version = newestVersion(index.framework_version, cliVersion());
   const p = indexPath(projectRoot);
   const text = JSON.stringify(index, null, 2) + "\n";
   write(p, text, { force: true });
@@ -80,12 +80,6 @@ export function addContract(index, entry) {
   return index;
 }
 
-export function removeSkill(index, id) {
-  if (!index.artifacts.skills) return index;
-  index.artifacts.skills = index.artifacts.skills.filter((s) => s.id !== id);
-  return index;
-}
-
 export function touch(index, date) {
   index.last_updated = date;
   return index;
@@ -98,11 +92,6 @@ export function addSpec(index, entry) {
   return index;
 }
 
-export function removeSpec(index, id) {
-  index.artifacts.specs = index.artifacts.specs.filter((s) => s.id !== id);
-  return index;
-}
-
 export function addDecision(index, entry) {
   if (!index.artifacts.decisions.some((d) => d.id === entry.id)) {
     index.artifacts.decisions.push(entry);
@@ -117,12 +106,6 @@ export function updateDecision(index, id, mutator) {
   return index;
 }
 
-export function addChange(index, entry) {
-  if (!index.artifacts.changes.some((c) => c.id === entry.id)) {
-    index.artifacts.changes.push(entry);
-  }
-  return index;
-}
 
 export function moveChangeToArchive(index, id, archiveEntry) {
   index.artifacts.changes = index.artifacts.changes.filter((c) => c.id !== id);

package/src/lib/intake-model.js

@@ -0,0 +1,86 @@
+// @ts-check
+// Writing the intake and printing the bootstrap playbook.
+//
+// `init --intake` performs the same three operations `intake` does, and
+// reached into `commands/intake.js` for them (audit finding F7). They are
+// operations over the tree, not renderings of one command, so both
+// entry points read them from here.
+import path from "node:path";
+import { exists, isFile, read, relPath, write } from "./fs-ops.js";
+import { assessBrief } from "./clarity.js";
+import { c } from "./colors.js";
+import { printPlaybookTemplate } from "./playbook.js";
+// Clarification gate (review Topic A). A description too thin to spec from is
+// the moment to ask the user, not to let the agent invent requirements. Prints
+// the specific gaps before the bootstrap playbook; advisory, never blocking —
+// the intake is still captured verbatim (the playbook step 6 resolves it).
+/**
+ * Does this argument read as a FILE PATH, or as the description itself?
+ *
+ * `doctrina intake "<description>"` is the form the surface block's wording
+ * invites — "store the intent" — and it answered `description file not found:`
+ * followed by the author's whole sentence, echoed back as if it were a
+ * filename, with no mention of `--text` (change 0071). Prose and a path are
+ * distinguishable without guessing: a path has no sentence in it.
+ *
+ * Deliberately conservative — anything that could be a path IS treated as one,
+ * so a real file is never mistaken for prose and read as a description.
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function looksLikePath(value) {
+  const v = String(value).trim();
+  if (v === "") return false;
+  if (/[/\\]/.test(v)) return true;            // a separator settles it
+  if (/^[.~]/.test(v)) return true;             // ./x, ../x, ~/x
+  if (!/\s/.test(v)) return true;              // one token: assume a filename
+  if (/\.(md|txt|markdown|rst|adoc|org)$/i.test(v)) return true; // "my notes.txt"
+  return false;
+}
+
+export function warnIfThinIntake(body) {
+  const assessment = assessBrief(body, { kind: "intake" });
+  if (!assessment.thin) return;
+  console.log(c.yellow("⚠ thin intake — clarify with the user before converting to specs:"));
+  for (const reason of assessment.reasons) console.log(`    - ${reason}`);
+  console.log("");
+}
+
+// Shared with `init --intake`. Writes the intake verbatim under a small
+// status header; the agent flips Status to converted at the end of the
+// playbook, which is how `next` knows the bootstrap is done.
+export function writeIntakeFile(projectRoot, { body, source, projectName, date, force = false }) {
+  const intakePath = path.join(projectRoot, ".doctrina", "intake.md");
+  const content = [
+    `# Intake — ${projectName}`,
+    "",
+    "- **Status:** pending",
+    `- **Date:** ${date}`,
+    `- **Source:** ${source}`,
+    "",
+    "<!-- Raw project intent, stored verbatim. The bootstrap playbook",
+    "     (doctrina intake) converts it into product.md and capability",
+    "     specs, then flips Status to converted. After conversion the",
+    "     specs are the only source of truth; never edit this file to",
+    "     change requirements. -->",
+    "",
+    "---",
+    "",
+    body.replace(/\r\n/g, "\n").replace(/\n*$/, "\n"),
+  ].join("\n");
+  write(intakePath, content, { force });
+  return intakePath;
+}
+
+// The bootstrap playbook, like the work and chore playbooks, is a TEMPLATE
+// resolved project-over-bundled (audit finding F17). What stays here is the
+// one conditional: a tree that never got its specs/ directory.
+export function printBootstrapPlaybook(projectRoot) {
+  const hasSpecs = exists(path.join(projectRoot, ".doctrina", "specs"));
+  printPlaybookTemplate(projectRoot, "bootstrap", {
+    MISSING_SPECS_WARNING: hasSpecs
+      ? ""
+      : "\n" + c.yellow("warn:") + " .doctrina/specs/ is missing — re-run `doctrina init` first.",
+  });
+}