doctrina-cli 0.13.0 → 0.15.0

package/src/lib/scan.js

@@ -1,3 +1,5 @@
+// @ts-check
+import { getHeader, getSection } from "./doc-model.js";
 import path from "node:path";
 import { readdirSync } from "node:fs";
 import { isDir, isFile, read, walk } from "./fs-ops.js";
@@ -5,29 +7,18 @@ import { today } from "./dates.js";
 import { parseFrontmatter } from "../commands/skill.js";
 import { parseOperation, parseCapabilityFromDelta } from "../commands/change.js";
 
-// Parse a metadata header line, tolerating BOTH conventions:
-//   **Name:** value        (spec style)
-//   - **Name:** value      (ADR / proposal / intake style)
-// The leading "- " is optional so a one-character convention slip (an
-// agent hand-authoring an ADR with the bare spec form, or vice versa)
-// still parses instead of silently falling back to a default value.
-const HEADER_PREFIX = "(?:-\\s+)?";
-
-// Parse a spec-style header line: **Name:** value (dash optional).
+// Header reading lives in ONE place now (lib/doc-model.js, audit item M3).
+// These two names survive because dozens of call sites use them and the
+// distinction they once encoded — spec style vs list style — is now the
+// document model's job, not the caller's.
 export function specHeader(text, name) {
-  const m = text.match(new RegExp(`^${HEADER_PREFIX}\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
-  return m ? m[1].trim() : null;
+  return getHeader(text, name);
 }
 
-// Parse an ADR/proposal-style header line: - **Name:** value (dash optional).
 export function listHeader(text, name) {
-  const m = text.match(new RegExp(`^${HEADER_PREFIX}\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
-  return m ? m[1].trim() : null;
+  return getHeader(text, name);
 }
 
-// The machine-readable "**Depends on:** defects, decisions" spec header: the
-// sibling capabilities this spec builds on. Returns [] when absent, "n/a", or
-// empty. One parser so index, why, context, and review agree.
 export function parseDependsOn(text) {
   const raw = specHeader(text, "Depends on");
   if (!raw || /^n\/a\b/i.test(raw.trim()) || raw.trim() === "—") return [];
@@ -39,6 +30,72 @@ function dirEntries(dir) {
   return readdirSync(dir).filter((e) => !e.startsWith(".")).sort();
 }
 
+
+// The capabilities an ADR governs, from its optional "Scope:" header
+// (M4). Returns [] when absent, "n/a", or "—" — an unscoped ADR is global
+// and belongs in every pack, which is what keeps this backward compatible.
+export function parseAdrScope(text) {
+  const raw = listHeader(text, "Scope");
+  if (!raw || /^n\/a\b/i.test(raw.trim()) || raw.trim() === "—") return [];
+  return raw.match(/[a-z][a-z0-9][a-z0-9-]*/g) ?? [];
+}
+
+// One sentence describing what an ADR decided, taken from its "## Decision"
+// section. This is what a budget-constrained pack falls back to before it
+// drops an ADR entirely: a title and a sentence still carry the decision,
+// where an omission carries nothing.
+export function adrSummary(text) {
+  const body = getSection(text, "Decision");
+  if (!body) return null;
+  for (const line of body.split("\n")) {
+    const s = line.trim();
+    if (!s || s.startsWith("<!--") || s.startsWith("#") || s.startsWith("|")) continue;
+    // Take the first sentence, capped so the index stays scannable.
+    const plain = s.replace(/^[-*\d.]+\s*/, "").replace(/\*\*/g, "");
+    const sentence = (plain.match(/^.*?[.!?](?=\s|$)/) ?? [plain])[0].trim();
+    if (sentence.length < 12) continue;
+    return sentence.length > 220 ? sentence.slice(0, 217).trimEnd() + "..." : sentence;
+  }
+  return null;
+}
+
+// The index entry for ONE decision, derived from its file. This is the
+// single definition of a decision record: `deriveIndex` builds the whole
+// list from it, and `doctrina decision new` registers a new ADR through it
+// rather than assembling a look-alike by hand. Two constructors for one
+// record shape is how a field added to the deriver (M4's `summary`) turns
+// every freshly created ADR into index drift the moment it is written.
+export function decisionEntry(text, basename, prev, date) {
+  const id = basename.match(/^(\d{4})-/)?.[1] ?? prev?.id ?? "0000";
+  const titleMatch = text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m);
+  const entry = {
+    id,
+    path: `.doctrina/decisions/${basename}`,
+    title: titleMatch ? titleMatch[1].trim() : prev?.title ?? basename,
+    status: listHeader(text, "Status") ?? prev?.status ?? "proposed",
+    date: listHeader(text, "Date") ?? prev?.date ?? date,
+  };
+  const supersedes = listHeader(text, "Supersedes");
+  if (supersedes && supersedes !== "—") entry.supersedes = supersedes;
+  const supersededBy = listHeader(text, "Superseded by");
+  if (supersededBy && supersededBy !== "—") entry.superseded_by = supersededBy;
+  const landed = listHeader(text, "Landed");
+  if (landed && landed !== "—") entry.landed = landed;
+  // Scope (M4): the capabilities this decision governs. ADRs are immutable
+  // and never retire, so without a scope every accepted ADR loads into every
+  // context pack forever — the pack grows O(project age) with no decay. An
+  // ADR with no Scope: is GLOBAL by definition, the backward-compatible
+  // default.
+  const scope = parseAdrScope(text);
+  if (scope.length > 0) entry.scope = scope;
+  // Summary: one sentence from the Decision section, so a pack over budget
+  // can degrade an ADR to title + summary instead of dropping it outright.
+  const summary = adrSummary(text);
+  if (summary) entry.summary = summary;
+  return entry;
+}
+
+
 // Regenerate the index object from the artifacts on disk. The files are
 // the source of truth; fields with no on-disk source (project name,
 // framework_version, product metadata) are carried over from `current`.
@@ -52,6 +109,12 @@ export function deriveIndex(projectRoot, current) {
     project: current?.project ?? path.basename(projectRoot),
     framework_version: current?.framework_version ?? "0.0.0",
     last_updated: current?.last_updated ?? date,
+    // Project settings, carried over verbatim. `deriveIndex` rebuilds the
+    // artifact graph FROM DISK, so anything it does not explicitly carry is
+    // silently erased on the next `index rebuild` — config has no on-disk
+    // source to be rederived from, which is exactly why it must be listed
+    // here alongside project and framework_version. Absent means defaults.
+    ...(current?.config !== undefined ? { config: current.config } : {}),
     artifacts: {
       product: cur.product ?? {
         path: ".doctrina/product.md",
@@ -112,23 +175,8 @@ export function deriveIndex(projectRoot, current) {
     const base = path.basename(f);
     const m = base.match(/^(\d{4})-.*\.md$/);
     if (!m) continue;
-    const text = read(f);
     const prev = (cur.decisions ?? []).find((d) => d.id === m[1]);
-    const titleMatch = text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m);
-    const entry = {
-      id: m[1],
-      path: `.doctrina/decisions/${base}`,
-      title: titleMatch ? titleMatch[1].trim() : prev?.title ?? base,
-      status: listHeader(text, "Status") ?? prev?.status ?? "proposed",
-      date: listHeader(text, "Date") ?? prev?.date ?? date,
-    };
-    const supersedes = listHeader(text, "Supersedes");
-    if (supersedes && supersedes !== "—") entry.supersedes = supersedes;
-    const supersededBy = listHeader(text, "Superseded by");
-    if (supersededBy && supersededBy !== "—") entry.superseded_by = supersededBy;
-    const landed = listHeader(text, "Landed");
-    if (landed && landed !== "—") entry.landed = landed;
-    out.artifacts.decisions.push(entry);
+    out.artifacts.decisions.push(decisionEntry(read(f), base, prev, date));
   }
 
   // Open changes — every directory except archive/.

package/src/lib/spec-ops.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Structured spec operations (ADR 0007 / review F3). A MODIFIED spec delta
 // historically carried prose ("flip criterion 2 to verified", "bump to
 // 0.3.0") that a human merged by hand — the single most error-prone step in
@@ -32,6 +33,9 @@
 // no ops block, apply falls back to the manual-merge pointer (backward
 // compatible).
 
+// The read grammar is the document model's (M3); this local pattern exists
+// only because the ops verbs REWRITE headers in place and need the prefix
+// captured to preserve it.
 const HEADER_RE = (name) =>
   new RegExp(`^(\\s*(?:-\\s+)?\\*\\*${escapeRe(name)}:\\*\\*)\\s*(.*)$`, "m");
 
@@ -57,14 +61,28 @@ export function extractOps(deltaText) {
 
 // Find the body of the first ```ops fenced block, or null if absent. The
 // info string must be exactly "ops" (case-insensitive) so a normal code
-// fence in the prose is never mistaken for operations. HTML comments are
-// stripped first: the scaffolded delta template carries an EXAMPLE ops block
-// inside its instructional comment, and executing an example against a real
-// spec is exactly the surprise this guard removes.
+// fence in the prose is never mistaken for operations.
+//
+// A fence sitting INSIDE an HTML comment is skipped: the scaffolded delta
+// template carries an EXAMPLE ops block in its instructional comment, and
+// executing an example against a real spec is exactly the surprise this
+// guard removes. The comment is skipped by POSITION, never by deleting the
+// comment text first — stripping mutated ops values that legitimately
+// contain a comment (an `<!-- illustrative -->` marker inside an
+// append-criterion landed in the spec with the marker silently gutted).
 function matchOpsBlock(text) {
-  const visible = text.replace(/<!--[\s\S]*?-->/g, "");
-  const m = visible.match(/^[ \t]*```[ \t]*ops[ \t]*\r?\n([\s\S]*?)^[ \t]*```[ \t]*$/m);
-  return m ? m[1] : null;
+  const commentRanges = [];
+  for (const m of text.matchAll(/<!--[\s\S]*?-->/g)) {
+    commentRanges.push([m.index, m.index + m[0].length]);
+  }
+  const insideComment = (offset) => commentRanges.some(([a, b]) => offset >= a && offset < b);
+
+  const fenceRe = /^[ \t]*```[ \t]*ops[ \t]*\r?\n([\s\S]*?)^[ \t]*```[ \t]*$/gm;
+  let m;
+  while ((m = fenceRe.exec(text))) {
+    if (!insideComment(m.index)) return m[1];
+  }
+  return null;
 }
 
 function parseOpLine(line) {
@@ -322,15 +340,82 @@ function endOfItem(lines, startIndex) {
   return i;
 }
 
+// The EARS subsections in the order the spec template lays them out. A
+// created subsection goes where a reader expects it, not at the end.
+const EARS_ORDER = ["ubiquitous", "event", "state", "unwanted", "optional"];
+const EARS_HEADINGS = {
+  ubiquitous: "### Ubiquitous",
+  event: "### Event-driven",
+  state: "### State-driven",
+  unwanted: "### Unwanted-behavior (must-not)",
+  optional: "### Optional",
+};
+
+// Create an absent `### <EARS>` subsection under `## Requirements (EARS)`,
+// carrying its first requirement, in canonical order: after the last
+// existing subsection that precedes it, or ahead of them all when none
+// does. The requirement goes in with the heading rather than in a second
+// pass, so the blank lines around the new block are exact.
+function createEarsSubsection(loc, section, value) {
+  const heading = EARS_HEADINGS[section];
+  if (!heading) return { error: `append-requirement: unknown EARS subsection "${section}"` };
+  const lines = [...loc.lines];
+
+  let insertAt = null;
+  const rank = EARS_ORDER.indexOf(section);
+  for (const token of EARS_ORDER.slice(0, rank).reverse()) {
+    const prior = loc.sections[token];
+    if (prior) {
+      // End of that subsection, trimmed back past the blank lines it trails.
+      let end = Math.min(prior.endIndex, lines.length);
+      while (end > prior.headingIndex + 1 && lines[end - 1].trim() === "") end -= 1;
+      insertAt = end;
+      break;
+    }
+  }
+  if (insertAt === null) {
+    // Nothing precedes it: place it ahead of whichever subsection currently
+    // comes first, or directly under the Requirements heading.
+    const first = EARS_ORDER.map((t) => loc.sections[t]).find(Boolean);
+    if (first) {
+      insertAt = first.headingIndex;
+    } else {
+      const reqIndex = lines.findIndex((l) => /^##\s+Requirements\b/i.test(l));
+      if (reqIndex < 0) return { error: "append-requirement: spec has no '## Requirements (EARS)' section" };
+      insertAt = reqIndex + 1;
+    }
+  }
+
+  // Exactly one blank line on each side, borrowing whichever the
+  // insertion point already provides rather than adding a second.
+  const block = [heading, "", `- ${value}`];
+  if (insertAt > 0 && lines[insertAt - 1].trim() !== "") block.unshift("");
+  if (lines[insertAt] !== undefined && lines[insertAt].trim() !== "") block.push("");
+  lines.splice(insertAt, 0, ...block);
+  return { text: lines.join("\n") };
+}
+
 // append-requirement <section>: <text> — add "- <text>" at the end of the
 // EARS subsection. A lone "-" placeholder bullet (the untouched scaffold) is
 // replaced instead of appended after, so the first real requirement does not
 // land under an empty stub.
 export function appendRequirement(text, section, value) {
-  const loc = locateRequirements(text);
+  let loc = locateRequirements(text);
   if (!loc) return { error: "append-requirement: spec has no '## Requirements (EARS)' section" };
+  if (!loc.sections[section]) {
+    // The subsection does not exist yet. Refusing here is a dead end: the
+    // author cannot hand-edit the spec (AGENTS.md forbids editing specs
+    // outside a delta) and no op creates a subsection, so a spec that was
+    // split — losing the EARS headings it had no requirements for — could
+    // never receive one again. Create it, in canonical EARS order.
+    const created = createEarsSubsection(loc, section, value);
+    if (created.error) return created;
+    return {
+      text: created.text,
+      summary: `append-requirement ${section} (created subsection): ${value.slice(0, 44)}`,
+    };
+  }
   const sec = loc.sections[section];
-  if (!sec) return { error: `append-requirement: no '### ${section}...' subsection found under Requirements` };
   const placeholder = sec.bullets.length === 1 && /^\s*-\s*$/.test(loc.lines[sec.bullets[0]]);
   if (placeholder) {
     loc.lines[sec.bullets[0]] = `- ${value}`;

package/src/lib/suggest.js

@@ -1,3 +1,4 @@
+// @ts-check
 // Tiny Levenshtein distance + "did you mean" suggester. Zero deps.
 
 export function distance(a, b) {

package/src/lib/templates.js

@@ -1,3 +1,4 @@
+// @ts-check
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { read, toPosix, walk, write } from "./fs-ops.js";
@@ -35,6 +36,94 @@ export function locateTemplatesDir() {
   );
 }
 
+// ---------------------------------------------------------------------------
+// The project-local override chain (audit item M1).
+//
+// `doctrina init` creates `.doctrina/templates/` containing a single
+// `.gitkeep`, and nothing ever read it or wrote to it. The resolver above
+// answers only "where did the CLI install its templates?", so a directory
+// the framework creates in every project was inert — a ghost.
+//
+// Resolution is now a CHAIN, per file: a template present under the
+// project's `.doctrina/templates/` wins; anything absent falls back to the
+// bundled copy. That turns the ghost into the customisation point, and it
+// is the same wiring the custom-adapter support needs (ADR 0016).
+//
+// Deliberately per FILE, not per directory: a team that wants its own
+// `spec.md.template` should not have to vendor the whole tree and then
+// maintain every other template forever.
+
+export function projectTemplatesDir(projectRoot) {
+  return path.join(projectRoot, ".doctrina", "templates");
+}
+
+// Where a named template resolves for this project.
+// Returns { path, source: "project" | "bundled" } or null when neither has
+// it. `relativePath` is POSIX-ish and relative to a templates root, e.g.
+// "spec.md.template" or "change/proposal.md.template".
+export function resolveTemplate(projectRoot, relativePath) {
+  const rel = relativePath.split("/").join(path.sep);
+  if (projectRoot) {
+    const local = path.join(projectTemplatesDir(projectRoot), rel);
+    if (fileExists(local)) return { path: local, source: "project" };
+  }
+  try {
+    const bundled = path.join(locateTemplatesDir(), rel);
+    if (fileExists(bundled)) return { path: bundled, source: "bundled" };
+  } catch { /* no bundled tree (unusual install) */ }
+  return null;
+}
+
+// Read a template through the chain. Throws with both candidates named
+// when neither side has it, because "template not found" with no path is
+// the least actionable error a scaffolder can give.
+export function readTemplate(projectRoot, relativePath) {
+  const resolved = resolveTemplate(projectRoot, relativePath);
+  if (!resolved) {
+    throw new Error(
+      `template "${relativePath}" not found in the project override ` +
+      `(${projectTemplatesDir(projectRoot)}) or in the installed CLI`,
+    );
+  }
+  return { ...resolved, body: read(resolved.path) };
+}
+
+// Every template the chain can serve, with where each one resolved from —
+// what `templates list` prints so the source is never a guess.
+export function listResolvedTemplates(projectRoot) {
+  const seen = new Map();
+  let bundledRoot = null;
+  try {
+    bundledRoot = locateTemplatesDir();
+  } catch { /* none */ }
+
+  if (bundledRoot) {
+    for (const f of walk(bundledRoot)) {
+      const rel = toPosix(path.relative(bundledRoot, f));
+      seen.set(rel, { relativePath: rel, path: f, source: "bundled" });
+    }
+  }
+  const localRoot = projectRoot ? projectTemplatesDir(projectRoot) : null;
+  if (localRoot) {
+    for (const f of walk(localRoot)) {
+      const rel = toPosix(path.relative(localRoot, f));
+      if (rel === ".gitkeep") continue;
+      const overrides = seen.has(rel);
+      seen.set(rel, { relativePath: rel, path: f, source: "project", overrides });
+    }
+  }
+  return [...seen.values()].sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+
+function fileExists(p) {
+  try {
+    read(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // Single-pass {{TOKEN}} substitution. Tokens are uppercase, digits, or
 // underscore inside double curly braces.
 export function substitute(text, tokens) {

package/src/lib/usage.js

@@ -0,0 +1,89 @@
+// @ts-check
+// Audit item M8: instrument the command surface before shrinking it.
+//
+// The surface is 36 commands and 59 operations. The audit's charge is that
+// some of them exist because they were easy to add, not because anybody
+// reaches for them — and the honest way to find out which is to MEASURE,
+// not to guess from the outside. Guessing is how `prime`, `handoff` and
+// `doctor` were nearly cut in 0.13.0, right before the operator review
+// found they had gone unused only because AGENTS.md never named them.
+//
+// The design constraints this is built under:
+//
+//   OFF unless asked.  No file appears, and nothing is recorded, until the
+//     operator sets DOCTRINA_USAGE_LOG. A tool that starts logging because
+//     it was updated has broken faith regardless of what it logs.
+//   LOCAL only.  One append-only JSONL file at a path the operator names.
+//     The CLI makes no network calls at all (a spec requirement), and this
+//     changes nothing about that.
+//   NO ARGUMENTS.  The command and the sub-operation, never the values.
+//     `change apply 0021-secret-project` records `change apply`. Paths,
+//     titles, prompts and ids are the user's, not the instrument's.
+//   NEVER FATAL.  A failure to record is silent. Losing a usage sample
+//     matters less than nothing, and losing the command's real work to an
+//     instrumentation error would be absurd.
+
+import { appendFileSync } from "node:fs";
+import process from "node:process";
+
+export const USAGE_ENV = "DOCTRINA_USAGE_LOG";
+
+// Which operation was invoked, with no user data attached.
+//
+// The second positional is kept ONLY when the catalog says this command has
+// that sub-operation. Shape alone is not enough to tell a sub-command from
+// an argument: `context cli` and `spec new` are identical in shape, but the
+// first is a capability name. Guessing recorded `context cli` as an
+// operation and left the real `context` looking unused — which is exactly
+// the wrong answer from an instrument whose whole job is deciding what
+// nobody uses.
+export function operationOf(positional, knownOperations) {
+  const command = positional[0];
+  if (!command) return null;
+  const next = positional[1];
+  if (typeof next !== "string" || !/^[a-z][a-z-]{1,20}$/.test(next)) return command;
+  const pair = `${command} ${next}`;
+  return knownOperations?.has(pair) ? pair : command;
+}
+
+// Append one sample. Returns true when it recorded, false otherwise — the
+// tests assert on that rather than on the file, so the "off by default"
+// guarantee is checked directly.
+export function recordUsage(positional, exitCode, knownOperations, env = process.env) {
+  const target = env[USAGE_ENV];
+  if (!target) return false;
+  const operation = operationOf(positional, knownOperations);
+  if (!operation) return false;
+  try {
+    appendFileSync(target, JSON.stringify({
+      at: new Date().toISOString(),
+      operation,
+      exit: exitCode ?? 0,
+    }) + "\n");
+    return true;
+  } catch {
+    // Instrumentation never breaks the command it is measuring.
+    return false;
+  }
+}
+
+// Summarise a usage log: how often each operation ran, and — the number the
+// shrink decision actually turns on — which catalog operations never ran at
+// all. An operation with zero samples is a CANDIDATE for cutting or
+// folding, never a verdict: a command used once a quarter (`init`) and a
+// command nobody wants look identical over one week.
+export function summarise(logText, catalogOperations) {
+  const counts = new Map();
+  let samples = 0;
+  for (const line of String(logText).split("\n")) {
+    if (!line.trim()) continue;
+    let row;
+    try { row = JSON.parse(line); } catch { continue; }
+    if (!row?.operation) continue;
+    counts.set(row.operation, (counts.get(row.operation) ?? 0) + 1);
+    samples += 1;
+  }
+  const used = [...counts.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1));
+  const unused = catalogOperations.filter((op) => !counts.has(op)).sort();
+  return { samples, used, unused };
+}

package/src/lib/version.js

@@ -1,3 +1,4 @@
+// @ts-check
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFileSync } from "node:fs";

package/templates/AGENTS.md.template

@@ -33,19 +33,42 @@ prompt and approves; do not make them run the CLI or hand-author artifacts.
 <!-- doctrina:surface:begin — CLI-owned block, generated from the installed command catalog. Refreshed by `doctrina upgrade --write`; edits inside are overwritten. -->
 ## Doctrina command surface (generated — reach for these, don't hand-author)
 
-Every operation of the installed CLI, grouped by workflow. The CLI
-scaffolds from canonical templates and keeps `index.json` in sync, so
-prefer it over writing artifacts by hand. Details: `doctrina --help`.
-
-- **Start:** `doctrina init` · `doctrina intake` · `doctrina work "<prompt>" (--capability · --chore · --from-diff · --quiet)`
-- **Author:** `doctrina spec new|list|set` · `doctrina change new|apply|archive|check|tick|diff|abandon` · `doctrina contract new|list|check` · `doctrina decision new|accept|land|supersede|list` · `doctrina skill new|list|sync|suggest` · `doctrina intent add|list`
-- **Read / orient:** `doctrina prime (session start)` · `doctrina context [<cap>] --concat` · `doctrina show` · `doctrina search` · `doctrina status` · `doctrina next` · `doctrina why` · `doctrina handoff (before compaction/handover)` · `doctrina constitution`
-- **Gates:** `doctrina analyze` · `doctrina clarify --all (--lang pt|en)` · `doctrina validate (--fix)` · `doctrina coverage --strict` · `doctrina trace --strict` · `doctrina review` · `doctrina verify` · `doctrina close <id...>` · `doctrina doctor`
-- **Maintain:** `doctrina templates list|check|update` · `doctrina hooks install` · `doctrina index rebuild` · `doctrina watch` · `doctrina metrics` · `doctrina report` · `doctrina completion` · `doctrina upgrade --write`
-
-Session bookends: `doctrina prime` to orient at session start;
-`doctrina handoff` before compaction or handover. Continuous:
-`doctrina watch`. Capture lessons: `doctrina skill suggest`.
+Every command, with the moment you reach for it. The CLI scaffolds from
+canonical templates and syncs `index.json`. Flags: `doctrina <cmd> --help`.
+**Bootstrap**
+- `doctrina init` — scaffold AGENTS.md and .doctrina/. *When:* starting a project that has no AGENTS.md yet.
+- `doctrina intake` — store the intent and print the bootstrap playbook. *When:* you have a full project description and no specs yet.
+- `doctrina adapter list|add|remove` — install/remove agent adapters (additive). *When:* adding or removing an agent's pointer files.
+**Orient**
+- `doctrina prime (session start)` — gates, standing rules, and open work in one read. *When:* at the START of every session.
+- `doctrina context [<cap>] --for "<task>" --concat` — the read pack, assembled to fit a token budget. *When:* before working on any task, to load the right files.
+- `doctrina show` — point-read a single artifact by reference. *When:* you need one requirement, criterion, or ADR, not a file.
+- `doctrina search` — search the artifact tree, grouped by category. *When:* you do not know which artifact mentions a term.
+- `doctrina status` — index, coverage, trace, and artifact counts. *When:* you need the health of the tree at a glance.
+- `doctrina next` — the recommended next workflow action. *When:* you finished something and do not know what follows.
+- `doctrina why` — provenance: intent, proof, ADRs, and history. *When:* you need to justify or trace a capability's existence.
+- `doctrina handoff (before compaction/handover)` — a resume note: open work, task state, next command. *When:* BEFORE compaction or handing over to another session.
+- `doctrina constitution` — accepted ADRs and product non-goals. *When:* you need the standing rules before deciding something.
+**Change**
+- `doctrina triage` — classify the lane (product/runtime/chore) and check the declared runtime surface. *When:* a request arrives — BEFORE scaffolding, especially if it smells like an incident.
+- `doctrina work "<prompt>" (--capability · --chore · --from-diff · --quiet)` — scaffold a change and print the playbook to execute. *When:* a request arrives that changes behaviour (triage says PRODUCT).
+- `doctrina spec new|list|set` — create, list, and edit capability specs. *When:* a capability needs creating or its headers advancing.
+- `doctrina change new|apply|archive|check|tick|diff|abandon` — new / apply / archive / check / tick / diff / abandon. *When:* driving a change through its lifecycle by hand.
+- `doctrina contract new|list|check` — own and verify the integration surface. *When:* the change touches ports, env vars, or public endpoints.
+- `doctrina decision new|accept|land|supersede|list|scope` — record, accept, land, scope, and supersede ADRs. *When:* the change decides something a later session must not relitigate.
+- `doctrina skill new|list|sync|suggest` — capture on-demand procedural memory. *When:* a lesson is worth not relearning.
+- `doctrina intent add|list` — append and list product intent anchors. *When:* new product intent appears after the intake.
+**Gate**
+- `doctrina analyze` — structural pre-flight on a change folder. *When:* before applying a change.
+- `doctrina clarify --all (--lang pt|en)` — smell-test Markdown for ambiguity. *When:* before applying, or before opening a PR.
+- `doctrina validate (--fix)` — schema, structure, EARS, and index drift. *When:* after any artifact edit, and before considering work done.
+- `doctrina coverage --strict` — acceptance criteria against cited evidence. *When:* before claiming a capability is proven.
+- `doctrina trace --strict` — intent provenance across the tree. *When:* checking that product intent still maps to capabilities.
+- `doctrina review` — conformance of your changes vs specs/ADRs/contracts. *When:* before handing work back, to self-review it.
+- `doctrina verify` — the project's declared typecheck/test/build checks. *When:* the real build gate must run.
+- `doctrina close <id...>` — the whole closing sequence in one attested pass. *When:* a change is implemented and ready to finish.
+- `doctrina doctor` — aggregate diagnostic with per-finding remedies. *When:* something looks wrong and you do not know which gate to ask.
+**Maintain** (triggers: `doctrina <command> --help`) — `doctrina templates list|check|update` · `doctrina hooks install` · `doctrina index rebuild` · `doctrina watch` · `doctrina metrics` · `doctrina report` · `doctrina completion` · `doctrina upgrade --write`
 <!-- doctrina:surface:end -->
 
 ## Stack and tooling
@@ -78,55 +101,38 @@ Session bookends: `doctrina prime` to orient at session start;
 - Archived changes in `.doctrina/changes/archive/` are out of the default
   read path; consult only when explicitly debugging history.
 
-## Artifact invariants (verbatim — `doctrina validate` enforces these)
-
-Scaffold artifacts with the CLI (`doctrina decision new`, `doctrina work`),
-which writes from the canonical templates. Do NOT hand-author these files
-from memory. If you must write one by hand, match these exactly:
-
-- **Metadata headers come in two forms — do not mix them up:**
-  - ADRs, change proposals, and the intake use **list items**:
-    `- **Status:** accepted`, `- **Date:** 2026-06-13`.
-  - Specs use **bare bold** (no leading `- `):
-    `**Status:** active`, `**Version:** 0.1.0`.
-  Match the template for the artifact you are writing.
-- **ADR filename** must be `NNNN-slug.md` — four digits, e.g.
-  `0001-jwt-algorithm.md`. `ADR-001-...md` or `1-...md` is invisible to
-  `doctrina decision accept`, the index, and the orphan check.
-- **Change folder** at `.doctrina/changes/<id>/` must contain a file named
-  exactly `proposal.md` (not `change.md`, not `README.md`). `tasks.md` and
-  `design.md` are optional siblings.
-- **Spec** lives at `.doctrina/specs/<capability>/spec.md` and its
-  `**Version:**` header must equal the `version` recorded for it in
-  `.doctrina/index.json`.
-- **Every artifact on disk** must be registered in `.doctrina/index.json`,
-  and every path in `index.json` must exist on disk. Update the index in
-  the same change that adds or moves a file.
-
-Always finish by running `doctrina validate` and resolving every `error:`
-before considering work done.
+## Artifact invariants (`doctrina validate` enforces these)
+
+Scaffold with the CLI; do not hand-author from memory. If you must:
+
+- **Headers:** ADRs / proposals / intake use list items
+  (`- **Status:** accepted`); specs use bare bold (`**Status:** active`).
+- **ADR filename:** `NNNN-slug.md`, four digits. Other shapes are invisible
+  to `decision accept`, the index, and the orphan check.
+- **Change folder:** `.doctrina/changes/<id>/proposal.md`, that exact name.
+- **Spec:** `.doctrina/specs/<cap>/spec.md`; its `**Version:**` must equal
+  the version recorded in `index.json`.
+- **Every artifact** is registered in `index.json`, and every indexed path
+  exists. Update the index in the same change.
+
+Finish by running `doctrina validate` and resolving every `error:`.
 
 ## How to read context efficiently
 
 `doctrina context [<capability>] --concat` assembles the read pack in one
-call, in order: this `AGENTS.md` → `.doctrina/product.md` → the capability
-spec → open `.doctrina/changes/<id>/` → `.doctrina/decisions/` filtered to
-`Status: accepted`. Run it for ANY task, not only `doctrina work`; it skips
-`changes/archive/` (history — read only when debugging it).
+call: this `AGENTS.md` → `product.md` → the capability spec → open changes →
+accepted ADRs. Run it for ANY task. It skips `changes/archive/` (history).
 
-On demand only: if the task matches a skill in `.doctrina/skills/`, read its
-`description:` / `when:` frontmatter; load the full body when the trigger fires.
+Skills are on demand: read the `description:` / `when:` frontmatter in
+`.doctrina/skills/`; load a body only when its trigger fires.
 
-Keep this file under 150 lines. Density beats prose. Use exact commands.
+Keep this file under 150 lines. Density beats prose.
 
 ## Definition of done
 
-A change is done when:
-- All tasks in the change's `tasks.md` are checked.
-- Deltas have been merged into affected spec files.
-- The change folder has been moved to `.doctrina/changes/archive/`.
-- Any architectural decisions are recorded as ADRs with `Status: accepted`.
-- `.doctrina/index.json` has been updated.
+`doctrina close <id>` is the definition: tasks checked, deltas merged into
+specs, gates green, ADRs recorded and accepted, change archived, index
+updated. If close refuses, the change is not done.
 
 ## What never goes in this file