doctrina-cli 0.15.1 → 0.16.0

package/src/lib/version.js

@@ -11,6 +11,28 @@ import { readFileSync } from "node:fs";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 
+// Numeric semver comparison ("0.15.10" sorts above "0.15.9"); anything
+// that is not X.Y.Z sorts lowest, so a garbage stamp is always migrated.
+export function compareVersions(a, b) {
+  const parse = (v) => {
+    const m = String(v ?? "").match(/^(\d+)\.(\d+)\.(\d+)$/);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+  };
+  const pa = parse(a); const pb = parse(b);
+  if (!pa && !pb) return 0;
+  if (!pa) return -1;
+  if (!pb) return 1;
+  for (let i = 0; i < 3; i++) if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1;
+  return 0;
+}
+
+// The stamp to WRITE: the newer of what the index holds and what runs
+// (change 0116). An older CLI rebuilding a newer tree keeps the newer
+// stamp; a newer CLI migrates an older one forward. Never rewound.
+export function newestVersion(current, running) {
+  return compareVersions(current, running) > 0 ? String(current) : String(running);
+}
+
 export function cliVersion() {
   // src/lib/version.js -> packages/doctrina-cli/package.json
   const pkgPath = path.resolve(here, "..", "..", "package.json");

package/src/lib/views.js

@@ -0,0 +1,410 @@
+// @ts-check
+import { c } from "./colors.js";
+import { today } from "./dates.js";
+import { churnByCapability } from "./ledger.js";
+
+// Executed proof and signed proof are different claims (change 0039). One
+// phrasing, used by every view, so none of them can quietly add the two
+// together and call the total green.
+function signoffNote(verify, { verbose = false } = {}) {
+  const s = verify.signoffs;
+  if (!s || s.manual === 0) return "";
+  const stale = s.expired + s.unverifiable + s.pending;
+  if (stale === 0) return verbose ? ` (${s.manual} signed, all current)` : ` · ${s.manual} signed`;
+  const parts = [];
+  if (s.expired) parts.push(`${s.expired} expired`);
+  if (s.unverifiable) parts.push(`${s.unverifiable} unverifiable`);
+  if (s.pending) parts.push(`${s.pending} unsigned`);
+  return ` (${s.manual} signed, ${parts.join(", ")})`;
+}
+
+// The four VIEWS of one snapshot (audit finding F7).
+//
+// `status`, `prime`, `handoff` and `report` differ only in shape: a
+// dashboard, a session primer, a Markdown resume note, a period digest. They
+// were four commands, each re-collecting the tree and reaching into the
+// others' modules for the parts it did not collect itself.
+//
+// Each function below takes the snapshot lib/snapshot.js already produced and
+// returns lines. They are pure: no reads, no writes, no process exits — which
+// is what makes "the four views agree" a property of the code rather than a
+// promise, and what lets `doctrina status --view <name>` render any of them.
+
+export const VIEWS = ["dashboard", "prime", "handoff", "report", "rules"];
+
+// Count the recorded lanes, keeping "unknown" as its own row rather than
+// dropping it: a mix that silently omits the changes it could not classify
+// reports a cleaner project than the one that exists.
+function laneMix(records) {
+  const counts = new Map();
+  let overridden = 0;
+  let total = 0;
+  for (const raw of records) {
+    total += 1;
+    if (!raw) {
+      counts.set("unknown", (counts.get("unknown") ?? 0) + 1);
+      continue;
+    }
+    const lane = String(raw).split(/[\s(]/)[0] || "unknown";
+    counts.set(lane, (counts.get(lane) ?? 0) + 1);
+    if (/opened as|opened anyway/.test(raw)) overridden += 1;
+  }
+  return { total, overridden, rows: [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])) };
+}
+
+/** Render one named view. Unknown names are a caller error, not a fallback. */
+// One rendering of the coverage ratio, shared by every view (change 0037
+// unified the collector; this is the same argument for the label). A pct of
+// null means no criterion was declared — there is nothing to be a ratio OF,
+// so the views say so instead of printing a score. `trace` has always said
+// "no anchors declared" for its own empty case; coverage now matches it.
+export function coverageLabel(cov) {
+  if (cov.pct === null) return `no criteria declared (0/0)`;
+  return `${cov.pct}% (${cov.totalCovered}/${cov.totalCriteria} criteria)`;
+}
+
+export function renderView(name, snapshot, options = {}) {
+  switch (name) {
+    case "dashboard": return dashboard(snapshot);
+    case "prime": return prime(snapshot);
+    case "handoff": return handoff(snapshot);
+    case "report": return report(snapshot, options);
+    case "rules": return rules(snapshot);
+    default: throw new Error(`unknown view "${name}" (declared: ${VIEWS.join(", ")})`);
+  }
+}
+
+// --------------------------------------------------------------- dashboard
+
+export function dashboard(s) {
+  const out = [];
+  out.push(c.bold("Doctrina status") + c.gray(` — ${s.project}  (framework ${s.stamp ?? "—"} / CLI ${s.cli})`));
+  out.push("");
+
+  out.push(c.bold("  Gates"));
+  let driftLine;
+  if (s.indexState === "missing") {
+    driftLine = c.red("missing/unreadable") + c.gray(" — run `doctrina index rebuild`");
+  } else if (s.indexState === "in-sync") {
+    driftLine = c.green("in sync");
+  } else {
+    driftLine = c.yellow("drifted") + c.gray(" — run `doctrina validate --fix`");
+  }
+  out.push(`    ${"index".padEnd(11)} ${driftLine}`);
+
+  const stampLine = s.stamp === s.cli
+    ? c.green("current")
+    : c.yellow(`${s.stamp ?? "—"} (CLI ${s.cli})`) + c.gray(" — `doctrina index rebuild`");
+  out.push(`    ${"stamp".padEnd(11)} ${stampLine}`);
+
+  const cov = s.coverage;
+  const covExtra = cov.totalDangling + cov.totalConditional > 0
+    ? c.yellow(` ${cov.totalDangling} dangling, ${cov.totalConditional} conditional`)
+    : "";
+  if (cov.pct === null) {
+    out.push(`    ${"coverage".padEnd(11)} ${c.yellow("no criteria declared")} ${c.gray("(0/0)")}`);
+  } else {
+    const covColor = cov.pct === 100 ? c.green : cov.pct >= 50 ? c.yellow : c.red;
+    out.push(`    ${"coverage".padEnd(11)} ${covColor(`${cov.pct}%`)} ${c.gray(`(${cov.totalCovered}/${cov.totalCriteria} criteria)`)}${covExtra}`);
+  }
+
+  const tr = s.trace;
+  const trExtra = tr.untraceable + tr.dropped + tr.dangling > 0
+    ? c.yellow(` ${tr.dropped} dropped, ${tr.untraceable} untraceable`)
+    : "";
+  const trColor = tr.anchors === 0 ? c.gray : (tr.realized === tr.anchors && tr.untraceable === 0 ? c.green : c.yellow);
+  const trText = tr.anchors === 0 ? "no anchors" : `${tr.realized}/${tr.anchors} anchors`;
+  out.push(`    ${"trace".padEnd(11)} ${trColor(trText)}${trExtra}`);
+
+  let verifyLine = c.gray("not configured") + c.gray(" — `doctrina verify --init`");
+  if (s.verify.invalid) {
+    verifyLine = c.red("invalid JSON");
+  } else if (s.verify.configured) {
+    const n = s.verify.checks;
+    const stale = s.verify.signoffs
+      ? s.verify.signoffs.expired + s.verify.signoffs.unverifiable + s.verify.signoffs.pending
+      : 0;
+    verifyLine = c.cyan(`${n} check${n === 1 ? "" : "s"}`) +
+      (stale > 0 ? c.yellow(signoffNote(s.verify)) : c.gray(signoffNote(s.verify))) +
+      c.gray(" — run `doctrina verify`");
+  }
+  out.push(`    ${"verify".padEnd(11)} ${verifyLine}`);
+
+  out.push("");
+  out.push(c.bold("  Work"));
+  const implBreak = Object.entries(s.specs.impl).map(([k, v]) => `${v} ${k}`).join(", ");
+  out.push(`    ${"specs".padEnd(11)} ${s.specs.total}${implBreak ? c.gray(`  (${implBreak})`) : ""}`);
+  out.push(`    ${"changes".padEnd(11)} ${s.specs.openChanges} open`);
+  const adrNotes = [];
+  if (s.decisions.proposed > 0) adrNotes.push(c.yellow(`${s.decisions.proposed} proposed`));
+  if (s.decisions.bare > 0) adrNotes.push(c.yellow(`${s.decisions.bare} unproven`));
+  out.push(`    ${"decisions".padEnd(11)} ${s.decisions.total}${adrNotes.length ? c.gray("  (") + adrNotes.join(c.gray(", ")) + c.gray(")") : ""}`);
+  out.push(`    ${"skills".padEnd(11)} ${s.skills}`);
+
+  out.push("");
+  out.push(c.gray("  Full gates: `doctrina validate` · `doctrina verify`.  Next step: `doctrina next`."));
+  return out;
+}
+
+// ------------------------------------------------------------------- prime
+
+export function prime(s) {
+  const out = [];
+  out.push(c.bold("Doctrina prime") + c.gray(` — ${s.project}  (framework ${s.stamp ?? "—"} / CLI ${s.cli})`));
+  out.push("");
+
+  const cov = s.coverage.pct === null
+    ? "no criteria declared"
+    : `${s.coverage.pct}% (${s.coverage.totalCovered}/${s.coverage.totalCriteria})`;
+  const tr = s.trace.anchors === 0 ? "no anchors" : `${s.trace.realized}/${s.trace.anchors}`;
+  const verify = s.verify.configured
+    ? `${s.verify.checks} verify checks${signoffNote(s.verify)}`
+    : "verify not configured";
+  out.push(c.bold("Gates  ") + `index ${s.indexState} · coverage ${cov} · trace ${tr} · ${verify}`);
+  const implBreak = Object.entries(s.specs.impl).map(([k, v]) => `${v} ${k}`).join(", ");
+  out.push(
+    c.bold("Work   ") +
+      `${s.specs.total} specs${implBreak ? ` (${implBreak})` : ""} · ${s.specs.openChanges} open change${s.specs.openChanges === 1 ? "" : "s"} · ` +
+      `${s.decisions.total} decisions · ${s.skills} skills`,
+  );
+
+  out.push("");
+  out.push(c.bold("Rules") + c.gray(`  (${s.adrs.length} accepted ADRs — \`doctrina prime --rules\` for detail)`));
+  for (const a of s.adrs) out.push(`  ${c.cyan(a.id)}  ${a.title}`);
+  if (s.nonGoals.length > 0) {
+    out.push(c.gray(`  + ${s.nonGoals.length} non-goal${s.nonGoals.length === 1 ? "" : "s"} declared in product.md`));
+  }
+
+  out.push("");
+  out.push(c.bold("Open work"));
+  if (s.openChanges.length === 0) {
+    out.push(c.gray("  none — `doctrina work \"<prompt>\"` opens the next change"));
+  } else {
+    for (const ch of s.openChanges) {
+      const tasks = ch.tasksTotal > 0 ? ` · tasks ${ch.tasksDone}/${ch.tasksTotal}` : "";
+      out.push(`  ${c.cyan(ch.id)}  ${ch.title ?? ""}${c.gray(` (${ch.status}${tasks})`)}`);
+    }
+  }
+
+  out.push("");
+  out.push(c.bold("Next"));
+  if (s.actions.length === 0) {
+    out.push(c.gray("  nothing pending — pick up new work"));
+  } else {
+    s.actions.slice(0, 5).forEach((a, i) => out.push(`  ${i + 1}. ${a.text}`));
+    if (s.actions.length > 5) out.push(c.gray(`  … ${s.actions.length - 5} more — \`doctrina next\``));
+  }
+
+  out.push("");
+  out.push(c.gray("Read deeper: `doctrina context [<cap>] --concat` · `doctrina why <cap>` · `doctrina show <ref>`"));
+  return out;
+}
+
+// ----------------------------------------------------------------- handoff
+
+export function handoff(s) {
+  const out = [];
+  out.push(`# Doctrina handoff — ${s.project} (${today()})`);
+  out.push("");
+
+  out.push("## Where things stand");
+  out.push("");
+  out.push(`- index: ${s.indexState} · framework stamp: ${s.stamp ?? "—"} (CLI ${s.cli})`);
+  out.push(`- coverage: ${coverageLabel(s.coverage)}` +
+    (s.coverage.totalDangling ? `, ${s.coverage.totalDangling} dangling` : "") +
+    (s.coverage.totalConditional ? `, ${s.coverage.totalConditional} conditional` : ""));
+  const tr = s.trace.anchors === 0 ? "no anchors declared" : `${s.trace.realized}/${s.trace.anchors} anchors realized`;
+  out.push(`- trace: ${tr}` + (s.trace.untraceable ? ` (${s.trace.untraceable} untraceable)` : ""));
+  out.push(`- verify: ${s.verify.configured ? `${s.verify.checks} checks declared${signoffNote(s.verify, { verbose: true })} — run \`doctrina verify\`` : "not configured"}`);
+
+  out.push("");
+  if (s.openChanges.length === 0) {
+    out.push("## Open work");
+    out.push("");
+    out.push("- none — the tree is at rest; start with `doctrina work \"<prompt>\"`");
+  } else {
+    for (const ch of s.openChanges) {
+      out.push(`## Open change \`${ch.id}\`${ch.title ? ` — ${ch.title}` : ""}`);
+      out.push("");
+      out.push(`- proposal status: ${ch.status}`);
+      if (ch.tasksTotal > 0) {
+        out.push(`- tasks: ${ch.tasksDone}/${ch.tasksTotal} checked`);
+        for (const t of ch.unchecked.slice(0, 8)) out.push(`  - [ ] ${t}`);
+        if (ch.unchecked.length > 8) out.push(`  - … ${ch.unchecked.length - 8} more in tasks.md`);
+      } else {
+        out.push("- tasks: no tasks.md checklist found");
+      }
+      out.push(`- resume with: \`doctrina work --resume ${ch.id}\` · close with: \`doctrina close ${ch.id}\``);
+      out.push("");
+    }
+  }
+
+  out.push("## Next actions");
+  out.push("");
+  if (s.actions.length === 0) {
+    out.push("1. nothing pending — `doctrina next` will confirm; pick up new work");
+  } else {
+    s.actions.forEach((a, i) => out.push(`${i + 1}. ${a.text}`));
+  }
+
+  out.push("");
+  out.push("*Generated read-only from the tree — regenerate anytime with `doctrina handoff`.*");
+  return out;
+}
+
+// ------------------------------------------------------------------- rules
+//
+// The project's standing rules, in full: the accepted ADRs and the product's
+// declared non-goals. Assembled, never owned — to change a principle you
+// supersede its ADR, to change a non-goal you edit product.md.
+//
+// One rendering, two callers (change 0049). `prime --rules` prints it, and
+// `doctrina constitution` — deprecated, kept working — prints the same lines,
+// so the merge is demonstrable rather than asserted. `prime` on its own still
+// shows the ADR titles and a non-goal COUNT: the primer is a fixed-size read,
+// and the full list is what `--rules` is for.
+export function rules(s) {
+  const out = [];
+  out.push(c.bold("Standing rules") + c.gray(`  — ${s.project}  (accepted decisions + non-goals)`));
+  out.push("");
+  out.push(c.bold("  Principles") + c.gray("  (immutable — supersede an ADR to change one)"));
+  if (s.adrs.length === 0) {
+    out.push(`    ${c.gray("no accepted ADRs yet — record decisions with `doctrina decision new`")}`);
+  } else {
+    for (const a of s.adrs) out.push(`    ${c.cyan("ADR " + a.id)}  ${a.title}`);
+  }
+  out.push("");
+  out.push(c.bold("  Non-goals") + c.gray("  (.doctrina/product.md)"));
+  if (s.nonGoals.length === 0) {
+    // Name the act that is actually missing (rule C2): telling an author to
+    // add a section they already wrote is a remedy that resolves nothing.
+    out.push(`    ${c.gray(s.hasNonGoalsSection
+      ? "none declared — the `## Non-goals` section of product.md is empty"
+      : "none declared — add a `## Non-goals` section to product.md")}`);
+  } else {
+    for (const g of s.nonGoals) out.push(`    ${c.gray("•")} ${g}`);
+  }
+  out.push("");
+  out.push(c.gray(`  ${s.adrs.length} accepted decision${s.adrs.length === 1 ? "" : "s"} · ` +
+    `${s.nonGoals.length} non-goal${s.nonGoals.length === 1 ? "" : "s"} · read-only`));
+  return out;
+}
+
+// ------------------------------------------------------------------ report
+
+function asPct(x) {
+  return typeof x === "number" ? `${(x * 100).toFixed(1)}%` : "—";
+}
+
+/**
+ * @param {object} s the snapshot
+ * @param {{ days?: number, cutoffIso?: string, git?: any, gitState?: any, metrics?: any }} [options]
+ */
+export function report(s, { days = 7, cutoffIso = "", git = null, gitState = null, metrics = null } = {}) {
+  const out = [];
+  out.push(`# Doctrina report — ${s.project} (${cutoffIso} → ${today()})`);
+  out.push("");
+
+  out.push("## Gates");
+  out.push("");
+  out.push(`- index: ${s.indexState} · framework stamp: ${s.stamp ?? "—"} (CLI ${s.cli})`);
+  out.push(`- coverage: ${coverageLabel(s.coverage)}` +
+    (s.coverage.totalDangling ? ` — ${s.coverage.totalDangling} dangling` : "") +
+    (s.coverage.totalConditional ? ` — ${s.coverage.totalConditional} conditional` : ""));
+  out.push(`- trace: ${s.trace.anchors === 0 ? "no anchors declared" : `${s.trace.realized}/${s.trace.anchors} anchors realized`}`);
+  out.push(`- verify: ${s.verify.configured ? `${s.verify.checks} checks declared${signoffNote(s.verify, { verbose: true })}` : "not configured"}`);
+
+  out.push("");
+  out.push("## Changes");
+  out.push("");
+  const archived = s.archive
+    .filter((ch) => typeof ch.applied === "string" && ch.applied >= cutoffIso)
+    .sort((a, b) => String(a.applied).localeCompare(String(b.applied)));
+  if (archived.length === 0) {
+    out.push(`- archived in period: none`);
+  } else {
+    out.push(`- archived in period: ${archived.length}`);
+    for (const ch of archived) out.push(`  - ${ch.applied} — \`${ch.id}\` ${ch.title}`);
+  }
+  if (s.openChanges.length === 0) {
+    out.push("- open now: none");
+  } else {
+    out.push(`- open now: ${s.openChanges.length}`);
+    for (const ch of s.openChanges) {
+      const tasks = ch.tasksTotal > 0 ? ` (tasks ${ch.tasksDone}/${ch.tasksTotal})` : "";
+      out.push(`  - \`${ch.id}\`${ch.title ? ` ${ch.title}` : ""}${tasks}`);
+    }
+  }
+
+  // What KIND of work the period held (change 0042). The classifier's verdict
+  // used to be computed, printed and thrown away, so no report could answer
+  // this — and the classifier had no set of right and wrong answers to be
+  // calibrated against. A change with no recorded lane is counted as unknown,
+  // never folded into a lane it might not belong to.
+  const lanes = laneMix([...archived.map((ch) => ch.lane ?? null), ...s.openLanes]);
+  if (lanes.total > 0) {
+    out.push("");
+    out.push("## Lanes");
+    out.push("");
+    for (const [lane, n] of lanes.rows) out.push(`- ${lane}: ${n}`);
+    if (lanes.overridden > 0) {
+      out.push(`- of which the operator opened a different lane than read: ${lanes.overridden}`);
+    }
+  }
+
+  // WHERE the work landed, from the ledger rather than from git (change
+  // 0046). git counts files; the ledger counts capabilities, which is the
+  // unit the specs, the gates and this report are all written in. The number
+  // is reported, never judged: a capability that moves often may be badly
+  // drawn or may simply be where the work is, and nothing here can tell those
+  // apart (ADR 0005).
+  const churn = churnByCapability(s.ledger ?? [], { since: cutoffIso });
+  if (churn.length > 0) {
+    out.push("");
+    out.push("## Capability churn (in period)");
+    out.push("");
+    for (const row of churn) {
+      out.push(`- ${row.capability}: ${row.changes} change${row.changes === 1 ? "" : "s"} (last ${row.last})`);
+    }
+  }
+
+  out.push("");
+  out.push("## Artifacts");
+  out.push("");
+  out.push(`- specs: ${s.specs.total} · decisions: ${s.decisions.total}` +
+    (s.decisions.proposed ? ` (${s.decisions.proposed} proposed)` : "") +
+    ` · skills: ${s.skills}`);
+
+  out.push("");
+  out.push("## Git (local, last " + days + " days)");
+  out.push("");
+  if (!git) {
+    // Name the ACTUAL condition, from the one git door (change 0040), not a
+    // list of causes that might apply. In a freshly `git init`ed repository
+    // this said "not a repository, or git not installed" — two causes, both
+    // false, sending the reader to look for an installation problem that was
+    // not there, while `metrics` read the same state and got it right
+    // (change 0080).
+    const why = gitState?.reason;
+    out.push(`- no git history available${why ? ` — ${why}` : ""}`);
+  } else {
+    out.push(`- commits: ${git.commits} (${git.fixes} fix-shaped, ${git.commits ? Math.round((git.fixes / git.commits) * 100) : 0}%)`);
+    if (git.churn.length > 0) {
+      out.push(`- top-churn files:`);
+      for (const [file, n] of git.churn) out.push(`  - ${file} (${n} touches)`);
+    }
+    // The rework proxies for the same window, from the same snapshot
+    // `doctrina metrics` renders (change 0050) — reported, never judged:
+    // both rates move with team size and release cadence, and iterative
+    // work trips the re-edit proxy exactly like rework does.
+    if (metrics) {
+      out.push(`- reverts: ${metrics.reverts} (${asPct(metrics.revert_rate)} of commits)`);
+      out.push(`- ${metrics.reedit_window_days}-day re-edit rate: ${asPct(metrics.reedit_rate)}` +
+        " (touches a file edited in the prior window — a proxy for rework, not a verdict)");
+    }
+  }
+
+  out.push("");
+  out.push(`*Generated read-only by \`doctrina report --since ${days}\`; deeper numbers: \`doctrina metrics\`.*`);
+  return out;
+}

package/src/lib/work-model.js

@@ -0,0 +1,77 @@
+// @ts-check
+// Ranking capabilities — by a set of changed files, or by a prompt.
+//
+// `review` needs the diff ranker to map a diff onto the specs it touches, and
+// reached into `commands/work.js` for it (audit finding F7). Both rankers are
+// pure functions over the spec tree, and `work` now ACTS on the prompt one
+// (it scaffolds the winner's delta), so neither belongs in a command module:
+// ADR 0025 — command modules render, shared logic lives in lib/.
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read } from "./fs-ops.js";
+import { score, terms } from "./lexicon.js";
+import { parseSourceGlobs } from "./scan.js";
+import { globToRegExp } from "./runtime.js";
+// Rank capabilities by the working tree, not the prompt (review F10): a changed
+// file scores its capability when the file sits under a path segment named for
+// it, or when the spec cites the file as evidence. A deterministic overlap
+// hint for the agent — never a decision (ADR 0005).
+export function rankCapabilitiesByDiff(projectRoot, files, { limit = 3 } = {}) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  if (!files || files.length === 0 || !isDir(specsDir)) return [];
+  const norm = files.map((f) => f.replace(/\\/g, "/"));
+
+  const ranked = [];
+  for (const cap of readdirSync(specsDir).sort()) {
+    const specPath = path.join(specsDir, cap, "spec.md");
+    if (!isFile(specPath)) continue;
+    const specText = read(specPath);
+    // A DECLARED glob outranks every inference: the spec said this code is
+    // its own, and a declaration is not a guess (change 0077).
+    const declared = parseSourceGlobs(specText).map((g) => globToRegExp(g));
+    let score = 0;
+    for (const f of norm) {
+      if (declared.some((re) => re.test(f))) score += 10;     // the spec claims it
+      if (f.split("/").includes(cap)) score += 3;            // src/<cap>/... etc.
+      if (specText.includes(f)) score += 5;                  // file cited in the spec
+      else if (specText.includes(path.basename(f))) score += 2; // filename cited
+    }
+    if (score > 0) ranked.push({ id: cap, score, path: `.doctrina/specs/${cap}/spec.md` });
+  }
+  // `limit` keeps the work-playbook hint short (top 3); review passes
+  // Infinity — truncating there is how it missed 5 of 8 touched capabilities
+  // in the 0.11.0 field session.
+  return ranked.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, limit);
+}
+
+// Deterministic term overlap: fold prompt and spec text with the SHARED
+// lexicon, then score. This is a hint for the agent, never a decision
+// (ADR 0005).
+//
+// Before change 0040 this carried its own stop list and its own fold, while
+// `context --for` carried different ones — and the work playbook tells the
+// agent to run `context` immediately after `work`. Two rankers, in sequence,
+// on the same prompt, free to disagree about which capability it is about.
+// Both now read lib/lexicon.js, and the score below is that module's
+// PROJECTION of the relevance tuple, not a second calculation.
+export function rankCapabilities(projectRoot, prompt) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const queryTerms = terms(prompt);
+  if (queryTerms.length === 0 || !isDir(specsDir)) return [];
+
+  const ranked = [];
+  for (const cap of readdirSync(specsDir).sort()) {
+    const specPath = path.join(specsDir, cap, "spec.md");
+    if (!isFile(specPath)) continue;
+    // The capability name is the emphasis: a term in the name says far more
+    // about what the prompt is about than the same term buried in the body.
+    const points = score(read(specPath), queryTerms, cap.split("-").join(" "));
+    if (points > 0) ranked.push({ id: cap, score: points, path: `.doctrina/specs/${cap}/spec.md` });
+  }
+  const sorted = ranked.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+  // The margin over the NEXT capability — computed before the top-3 cut, so
+  // the winner's margin is a real one — is what lets a caller tell a lead
+  // apart from a coin toss (change 0044). The last capability's runner-up is
+  // 0, the same convention `triage` uses for a lane nothing scored against.
+  return sorted.slice(0, 3).map((e, i) => ({ ...e, margin: e.score - (sorted[i + 1]?.score ?? 0) }));
+}

package/templates/AGENTS.md.template

@@ -1,34 +1,28 @@
 # AGENTS.md — {{PROJECT_NAME}}
 
 Operational source of truth for AI coding agents working in this
-repository. Follows the open AGENTS.md standard.
+repository. Follows the open AGENTS.md standard; the Doctrina framework
+artifacts live under `.doctrina/`.
 
 ## What this repo is
 
 {{PROJECT_DESCRIPTION}}
 
-This repository uses the Doctrina framework for spec-driven, AGENTS.md
-native multi-agent development. The full framework artifacts live under
-`.doctrina/`.
-
 ## Working from intent (you drive; the human stays passive)
 
 You — the AI agent — run the Doctrina commands. The human gives a brief
 prompt and approves; do not make them run the CLI or hand-author artifacts.
 
-- **Bootstrap.** If `.doctrina/intake.md` is `Status: pending`, the specs
-  are not written yet: run `doctrina intake` and execute the printed
-  playbook in one pass (fill `product.md`, derive capabilities, one EARS
-  spec each, `doctrina clarify --all` + `doctrina validate`, then flip the
-  intake to `Status: converted`). After conversion the specs are the only
-  source of truth — never edit `intake.md` to change requirements.
+- **Bootstrap.** No capability in `.doctrina/specs/`, or an intake still
+  `Status: pending`? The specs are not written: run `doctrina intake --text
+  "<description>"` and execute the printed playbook in one pass (existing
+  codebase: `doctrina work --from-diff`). After conversion the specs are the
+  only source of truth — never edit `intake.md` to change requirements.
 - **Day-to-day.** Start every session with `doctrina prime` (gates, rules,
-  open work in one read). Turn any request into a change with `doctrina
-  work "<prompt>"` and follow the printed playbook (spec delta → tasks →
-  implement → close). Preview a close with `doctrina change check <id>`;
-  close with `doctrina close <id>`. Unsure what's next? `doctrina next`.
-  Before compaction or handover: `doctrina handoff`. Ask the human only on
-  genuine ambiguity.
+  open work in one read). Turn any request into a change with `doctrina work
+  "<prompt>"` and follow the printed playbook. Preview a close with `doctrina
+  change check <id>`; close with `doctrina close <id>`. Unsure what's next?
+  `doctrina next`. Before compaction or handover: `doctrina handoff`.
 
 <!-- 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)
@@ -40,7 +34,7 @@ canonical templates and syncs `index.json`. Flags: `doctrina <cmd> --help`.
 - `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 prime (session start)` — gates, open work and next steps in one read (--rules for the full standing rules). *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.
@@ -48,12 +42,11 @@ canonical templates and syncs `index.json`. Flags: `doctrina <cmd> --help`.
 - `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 change new|apply|archive|check|tick|abandon` — new / apply / archive / check (--verbose) / tick / 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.
@@ -68,7 +61,7 @@ canonical templates and syncs `index.json`. Flags: `doctrina <cmd> --help`.
 - `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`
+**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 ci --emit github`
 <!-- doctrina:surface:end -->
 
 ## Stack and tooling
@@ -121,12 +114,13 @@ Finish by running `doctrina validate` and resolving every `error:`.
 
 `doctrina context [<capability>] --concat` assembles the read pack in one
 call: this `AGENTS.md` → `product.md` → the capability spec → open changes →
-accepted ADRs. Run it for ANY task. It skips `changes/archive/` (history).
-
-Skills are on demand: read the `description:` / `when:` frontmatter in
-`.doctrina/skills/`; load a body only when its trigger fires.
+accepted ADRs. Run it for ANY task; it skips `changes/archive/`. Skills are
+on demand: read the `description:` / `when:` frontmatter in
+`.doctrina/skills/` and load a body only when its trigger fires.
 
-Keep this file under 150 lines. Density beats prose.
+Keep this file under 150 lines. The scaffold already spends most of them
+and the generated block above grows with the CLI — `doctrina doctor`
+reports what is left. Density beats prose.
 
 ## Definition of done
 

package/templates/README.md

@@ -29,10 +29,45 @@ replace. No conditionals, loops, or includes.
 CLI authors and template authors share this vocabulary. Adding a token
 requires extending the templates spec at `.doctrina/specs/templates/spec.md`.
 
+### Playbook tokens
+
+The playbooks under `playbooks/` carry the variable parts of the procedure
+the agent executes. Each is PRE-RENDERED by the CLI into a plain string, so
+the template stays a document rather than a language with conditionals and
+loops in it.
+
+| Token | Meaning | Default if not supplied |
+|-------|---------|-------------------------|
+| `{{TITLE}}` | "Work playbook" or "Backfill playbook" | required in `work` |
+| `{{PROMPT}}` | The prompt the change was opened from, verbatim | required |
+| `{{FROM_DIFF_NOTE}}` | The code-first note, on `--from-diff` | empty |
+| `{{THIN_WARNING}}` | The thin-prompt clarification block | empty |
+| `{{CAPABILITY_BLOCK}}` | The pinned capability, the ranked hints, or "no match" | required in `work` |
+| `{{DIFF_MATCHES}}` | Capabilities the working tree touched | empty |
+| `{{STEP3_INTRO}}` | The delta step's opening, pinned or not | required in `work` |
+| `{{FROM_DIFF_DELTA_NOTE}}` | The backfill caveat on writing the delta | empty |
+| `{{MISSING_SPECS_WARNING}}` | Warning that `.doctrina/specs/` is absent | empty |
+
+A line holding NOTHING but one token whose value is empty is removed rather
+than left blank, which is what lets the optional blocks above be plain tokens.
+
+Colour is marked inline and expanded before substitution, so a token's value
+can never inject it:
+
+| Markup | Renders as |
+|--------|-----------|
+| `[[c]]...[[/c]]` | cyan — a command to run |
+| `[[g]]...[[/g]]` | gray — commentary |
+| `[[b]]...[[/b]]` | bold — a heading |
+| `[[y]]...[[/y]]` | yellow — a warning |
+
 ## Inventory (v0)
 
 ```
 README.md                                  this file
+playbooks/work.md.template                 the work / backfill playbook
+playbooks/chore.md.template                the spec-less chore playbook
+playbooks/bootstrap.md.template            the intake -> specs playbook
 AGENTS.md.template                         root rules for the target repo
 doctrina/                                  the .doctrina/ skeleton
   product.md.template