doctrina-cli 0.15.1 → 0.16.0

package/src/lib/scan.js

@@ -1,11 +1,14 @@
 // @ts-check
-import { getHeader, getSection } from "./doc-model.js";
+import { getHeader, getSection, parseChangeTitle } from "./doc-model.js";
 import path from "node:path";
 import { readdirSync } from "node:fs";
 import { isDir, isFile, read, walk } from "./fs-ops.js";
 import { today } from "./dates.js";
-import { parseFrontmatter } from "../commands/skill.js";
-import { parseOperation, parseCapabilityFromDelta } from "../commands/change.js";
+import { cliVersion, newestVersion } from "./version.js";
+import { load } from "./index-json.js";
+import { parseFrontmatter } from "./doc-model.js";
+import { parseCapabilityFromDelta } from "./doc-model.js";
+import { parseOperation } from "./doc-model.js";
 
 // 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
@@ -25,6 +28,44 @@ export function parseDependsOn(text) {
   return raw.match(/[a-z][a-z0-9][a-z0-9-]*/g) ?? [];
 }
 
+/**
+ * The source globs a spec DECLARES as its own, from the optional
+ * `**Source:**` header — comma-separated, `*` inside a segment and `**`
+ * across directories (the same minimal glob the contract's Selectors use).
+ *
+ * Doctrina infers nothing about which code belongs to which capability
+ * (ADR 0027, and the same principle ADR 0023 applies to the runtime
+ * surface). Before this header the only signals were the capability name
+ * appearing as a path segment and the spec happening to cite a filename,
+ * which left 80 of this repository's 92 source files owned by nobody — so
+ * `review`, the gate that asks whether the spec kept up with the code,
+ * could not see the code it was reviewing.
+ *
+ * Returns [] when the header is absent, "n/a", or "—".
+ */
+export function parseSourceGlobs(text) {
+  const raw = specHeader(text, "Source");
+  if (!raw || /^n\/a\b/i.test(raw.trim()) || raw.trim() === "—") return [];
+  // Split on commas at brace depth ZERO: a comma inside `{a,b}` separates
+  // alternatives of ONE glob, not two globs, and splitting on it blindly
+  // shreds every grouped declaration into fragments that match nothing.
+  const out = [];
+  let cur = "";
+  let depth = 0;
+  for (const ch of raw) {
+    if (ch === "{") depth += 1;
+    else if (ch === "}") depth = Math.max(0, depth - 1);
+    if (ch === "," && depth === 0) {
+      out.push(cur);
+      cur = "";
+      continue;
+    }
+    cur += ch;
+  }
+  out.push(cur);
+  return out.map((g) => g.trim().replace(/^`|`$/g, "").trim()).filter(Boolean);
+}
+
 function dirEntries(dir) {
   if (!isDir(dir)) return [];
   return readdirSync(dir).filter((e) => !e.startsWith(".")).sort();
@@ -95,6 +136,37 @@ export function decisionEntry(text, basename, prev, date) {
   return entry;
 }
 
+/**
+ * The index entry for ONE open change, derived from its proposal. Same
+ * discipline as `decisionEntry` above and for the same reason: `deriveIndex`
+ * builds the whole list from it, and `doctrina work` / `change new` register
+ * a new change THROUGH it instead of assembling a look-alike by hand.
+ *
+ * Two constructors for one record shape is how the `lane` field (change 0042)
+ * — added to the deriver and not to the writer — turned every freshly opened
+ * change into index drift the moment it was written: `doctrina work` followed
+ * by `doctrina validate` errored on a tree nobody had touched.
+ *
+ * @param {string} proposal Text of the change's proposal.md ("" when absent).
+ * @param {string} id       The change id (its directory name).
+ * @param {object|null} prev The entry already in the index, when there is one.
+ * @param {string} date     Fallback for a proposal carrying no Date header.
+ */
+export function changeEntry(proposal, id, prev, date) {
+  const title = parseChangeTitle(proposal);
+  return {
+    id,
+    title: title ?? prev?.title ?? id,
+    path: `.doctrina/changes/${id}`,
+    status: listHeader(proposal, "Status") ?? prev?.status ?? "proposed",
+    opened: listHeader(proposal, "Date") ?? prev?.opened ?? date,
+    // The lane the change was born in (change 0042). Optional: a change
+    // opened before the field existed simply has none, and every consumer
+    // treats its absence as "unknown" rather than as a lane.
+    ...laneOf(proposal, prev),
+  };
+}
+
 
 // Regenerate the index object from the artifacts on disk. The files are
 // the source of truth; fields with no on-disk source (project name,
@@ -166,6 +238,10 @@ export function deriveIndex(projectRoot, current) {
     // dependents of a touched capability.
     const depends = specHeader(text, "Depends on") !== null ? parseDependsOn(text) : prev?.depends_on;
     if (depends && depends.length) entry.depends_on = depends;
+    // Source: the code this capability owns (change 0077). Declared, never
+    // inferred — the same discipline ADR 0023 applies to the runtime surface.
+    const source = specHeader(text, "Source") !== null ? parseSourceGlobs(text) : prev?.source;
+    if (source && source.length) entry.source = source;
     out.artifacts.specs.push(entry);
   }
 
@@ -187,14 +263,7 @@ export function deriveIndex(projectRoot, current) {
     const prev = (cur.changes ?? []).find((c) => c.id === id);
     const proposalPath = path.join(changesDir, id, "proposal.md");
     const proposal = isFile(proposalPath) ? read(proposalPath) : "";
-    const titleMatch = proposal.match(/^#\s+Change\s+\S+\s*[—-]\s*(.+)$/m);
-    out.artifacts.changes.push({
-      id,
-      title: titleMatch ? titleMatch[1].trim() : prev?.title ?? id,
-      path: `.doctrina/changes/${id}`,
-      status: listHeader(proposal, "Status") ?? prev?.status ?? "proposed",
-      opened: listHeader(proposal, "Date") ?? prev?.opened ?? date,
-    });
+    out.artifacts.changes.push(changeEntry(proposal, id, prev, date));
   }
 
   // Archived changes — folder name carries the applied date and id.
@@ -205,7 +274,7 @@ export function deriveIndex(projectRoot, current) {
     const prev = (cur.changes_archive ?? []).find((c) => c.path?.endsWith(name));
     const proposalPath = path.join(archiveDir, name, "proposal.md");
     const proposal = isFile(proposalPath) ? read(proposalPath) : "";
-    const titleMatch = proposal.match(/^#\s+Change\s+\S+\s*[—-]\s*(.+)$/m);
+    const title = parseChangeTitle(proposal);
     const specsAffected = [];
     for (const deltaPath of walk(path.join(archiveDir, name, "specs"))) {
       if (!deltaPath.endsWith("delta.md")) continue;
@@ -217,7 +286,7 @@ export function deriveIndex(projectRoot, current) {
     }
     out.artifacts.changes_archive.push({
       id: m[2],
-      title: titleMatch ? titleMatch[1].trim() : prev?.title ?? m[2],
+      title: title ?? prev?.title ?? m[2],
       path: `.doctrina/changes/archive/${name}`,
       status: "applied",
       applied: m[1],
@@ -296,3 +365,125 @@ export function indexesMatch(a, b) {
   };
   return stableStringify(normalize(a)) === stableStringify(normalize(b));
 }
+
+// The lane recorded in a proposal header (change 0042), as an index field —
+// or nothing at all. A change opened before the field existed, or one whose
+// header is still the empty scaffold, has no lane, and "unknown" is the
+// honest answer rather than a default that would poison the mix.
+function laneOf(proposal, prev) {
+  const raw = (listHeader(proposal, "Lane") ?? "").trim();
+  if (!raw) return prev?.lane ? { lane: prev.lane } : {};
+  return { lane: raw };
+}
+
+/**
+ * Is the on-disk index still what the tree derives to, and if not, how does
+ * it differ?
+ *
+ * `index rebuild` renders this (and writes the derived index when asked);
+ * `doctor` reports it as one row. Before this it was the command's private
+ * business, so `doctor` answered "has the index drifted?" by spawning the
+ * CLI again and reading an exit code (audit finding F4).
+ *
+ * The framework stamp is migrated to the running CLI here rather than in the
+ * caller: deriveIndex carries the old value over so `next` does not nag on a
+ * version-only difference, and overriding it lets a stale stamp COUNT as
+ * drift, so `index rebuild` both reports and fixes it instead of
+ * short-circuiting on "nothing to do".
+ *
+ * @param {string} projectRoot
+ * @returns {{ok: boolean, drift: string[], derived: any, current: any, unreadable: string|null}}
+ */
+export function collectIndexDrift(projectRoot) {
+  let current = null;
+  let unreadable = null;
+  try {
+    current = load(projectRoot);
+  } catch (err) {
+    unreadable = err.message;
+  }
+  const derived = deriveIndex(projectRoot, current);
+  // A stamp ahead of this CLI is not drift (change 0116): the tree is
+  // managed by a newer release, and `--check` in CI must not go red because
+  // one teammate's CLI is older than the one that last wrote the index.
+  derived.framework_version = newestVersion(current?.framework_version, cliVersion());
+  if (indexesMatch(derived, current)) {
+    return { ok: true, drift: [], derived, current, unreadable };
+  }
+  return { ok: false, drift: describeDrift(current, derived), derived, current, unreadable };
+}
+
+// Human-readable category-level drift between the on-disk index and the
+// derived one: added / removed / changed entry ids.
+function describeDrift(current, derived) {
+  const lines = [];
+  if (!current) return ["index.json missing or unreadable"];
+  if ((current.framework_version ?? null) !== (derived.framework_version ?? null)) {
+    lines.push(`framework_version: ${current.framework_version ?? "unset"} -> ${derived.framework_version}`);
+  }
+  const categories = ["specs", "decisions", "changes", "changes_archive", "skills"];
+  for (const cat of categories) {
+    const cur = new Map((current.artifacts?.[cat] ?? []).map((e) => [e.id, e]));
+    const der = new Map((derived.artifacts?.[cat] ?? []).map((e) => [e.id, e]));
+    for (const id of der.keys()) {
+      if (!cur.has(id)) lines.push(`${cat}: "${id}" on disk but not in index`);
+      else if (stableStringify(cur.get(id)) !== stableStringify(der.get(id))) {
+        lines.push(`${cat}: "${id}" metadata differs from the files`);
+      }
+    }
+    for (const id of cur.keys()) {
+      if (!der.has(id)) lines.push(`${cat}: "${id}" in index but not on disk`);
+    }
+  }
+  if (stableStringify(current.artifacts?.product ?? null) !== stableStringify(derived.artifacts.product)) {
+    lines.push("product: metadata differs");
+  }
+  if (lines.length === 0) lines.push("structural difference (key order or missing category)");
+  return lines;
+}
+
+/**
+ * The capabilities that actually have a spec on disk.
+ *
+ * The one list every command checks a named capability against. `coverage
+ * --only` refuses a name that is not in it (change 0090); `context <cap>`
+ * refuses the same way, because a scope filter that matches nothing is the
+ * same defect wherever it appears. Kept here rather than in either command
+ * so the two cannot disagree about which capabilities exist.
+ *
+ * @param {string} projectRoot
+ * @returns {string[]} directory names, in readdir order
+ */
+export function knownCapabilities(projectRoot) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  if (!isDir(specsDir)) return [];
+  return readdirSync(specsDir).filter((e) => isFile(path.join(specsDir, e, "spec.md")));
+}
+
+/**
+ * Which capabilities declare a dependency on any of `caps`.
+ *
+ * The `**Depends on:**` header is the tree's only machine-readable statement
+ * that one capability builds on another, and two commands ask the same
+ * question of it: `review` notes a dependent whose ground moved, and `close`
+ * reports their coverage alongside the change's own. One definition, so they
+ * cannot disagree about who depends on what.
+ *
+ * @param {string} projectRoot
+ * @param {Iterable<string>} caps
+ * @returns {{capability: string, dependsOn: string[]}[]} sorted by capability
+ */
+export function dependentsOf(projectRoot, caps) {
+  const wanted = new Set(caps);
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  if (wanted.size === 0 || !isDir(specsDir)) return [];
+  const out = [];
+  for (const cap of readdirSync(specsDir).sort()) {
+    if (wanted.has(cap)) continue;
+    const specPath = path.join(specsDir, cap, "spec.md");
+    if (!isFile(specPath)) continue;
+    const deps = parseDependsOn(read(specPath)).filter((d) => wanted.has(d));
+    if (deps.length > 0) out.push({ capability: cap, dependsOn: deps });
+  }
+  return out;
+}

package/src/lib/signoff.js

@@ -0,0 +1,147 @@
+// @ts-check
+import path from "node:path";
+import { isFile, read, write } from "./fs-ops.js";
+import { today } from "./dates.js";
+import { git, GIT_STATE, isRepo } from "./git.js";
+
+// A manual sign-off has an EXPIRY (audit finding F12).
+//
+// `verify --signoff` recorded `{ date, note }`, that file was read by nothing
+// but `verify` itself, and the signature held forever. So the one deliberate
+// escape hatch from the build gate was also the one place a green gate could
+// lie indefinitely: sign off "the error copy reads well", rewrite every
+// message the next morning, and the gate still says yes.
+//
+// That is honest gates (ADR 0008) turned on the escape hatch itself. A
+// signature is a statement about code at a moment; when that code moves, the
+// statement is no longer evidence — it is history.
+//
+// The mechanism stays: a qualitative check is legitimate, and nothing here
+// removes it. What changes is that the record now carries WHAT was signed
+// (the covered paths, declared in verify.json like everything else — never
+// inferred) and WHEN (the commit). `verify` compares the two against the
+// working tree and reports one of four states.
+
+export const SIGNOFF_REL = ".doctrina/verify.signoffs.json";
+
+/**
+ * The state of a manual check's evidence.
+ *
+ *   pending       never signed off.
+ *   fresh         signed, and nothing it covers has moved since.
+ *   expired       signed, but a covered path changed after the signature.
+ *   unverifiable  signed in the pre-expiry format (no commit recorded), or
+ *                 signed outside a repository — so "has it moved?" has no
+ *                 answer. Not a pass: silence about whether evidence still
+ *                 holds is not evidence that it does.
+ *
+ * Only `fresh` passes. The other three are warnings by default and failures
+ * under --strict, which is exactly the rule `pending` already followed — a
+ * manual check has always been non-blocking locally and required in CI, and
+ * this keeps one rule rather than inventing a second.
+ */
+export function signoffState(projectRoot, check, record) {
+  if (!record || !record.date) return { state: "pending" };
+  const paths = declaredPaths(check);
+
+  if (!record.sha) {
+    return {
+      state: "unverifiable",
+      why: "signed before sign-offs recorded a commit, so what it covered cannot be checked",
+      record,
+    };
+  }
+  if (!isRepo(projectRoot)) {
+    return { state: "unverifiable", why: "not a git repository, so a change since the signature cannot be detected", record };
+  }
+  if (paths.length === 0) {
+    return {
+      state: "unverifiable",
+      why: `the check declares no "paths", so there is nothing to hold the signature to`,
+      record,
+    };
+  }
+
+  const changed = changedSince(projectRoot, record.sha, paths);
+  if (changed === null) {
+    return { state: "unverifiable", why: `commit ${short(record.sha)} is not in this repository's history`, record };
+  }
+  if (changed.length > 0) return { state: "expired", changed, record };
+  return { state: "fresh", record };
+}
+
+/** The paths a check declares it covers. Declared, never inferred. */
+export function declaredPaths(check) {
+  const raw = check?.paths;
+  if (Array.isArray(raw)) return raw.filter((p) => typeof p === "string" && p.trim() !== "");
+  if (typeof raw === "string" && raw.trim() !== "") return [raw];
+  return [];
+}
+
+/**
+ * Which of `paths` changed between `sha` and the working tree.
+ * Returns null when `sha` is not a commit this repository knows — an
+ * unanswerable question, reported as such rather than as "nothing changed".
+ */
+export function changedSince(projectRoot, sha, paths) {
+  const known = git(projectRoot, ["cat-file", "-e", `${sha}^{commit}`]);
+  if (known.state !== GIT_STATE.OK) return null;
+  // Committed changes and the working tree both count: a signature is about
+  // the code as it stands, not as it was last committed.
+  const committed = git(projectRoot, ["diff", "--name-only", sha, "--", ...paths]);
+  const working = git(projectRoot, ["diff", "--name-only", "HEAD", "--", ...paths]);
+  if (committed.state !== GIT_STATE.OK) return null;
+  const out = new Set(committed.lines.filter(Boolean));
+  if (working.state === GIT_STATE.OK) for (const f of working.lines.filter(Boolean)) out.add(f);
+  return [...out].sort();
+}
+
+/** The commit a signature is anchored to, or null outside a repository. */
+export function currentSha(projectRoot) {
+  const r = git(projectRoot, ["rev-parse", "HEAD"]);
+  return r.state === GIT_STATE.OK ? r.stdout.trim() : null;
+}
+
+export function short(sha) {
+  return String(sha ?? "").slice(0, 8);
+}
+
+export function loadSignoffs(projectRoot) {
+  const p = path.join(projectRoot, SIGNOFF_REL);
+  if (!isFile(p)) return {};
+  try {
+    return JSON.parse(read(p)) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+export function saveSignoffs(projectRoot, signoffs) {
+  write(path.join(projectRoot, SIGNOFF_REL), JSON.stringify(signoffs, null, 2) + "\n", { force: true });
+}
+
+/** Record a signature against today's date, the current commit, and what it covers. */
+export function recordSignoff(projectRoot, check, note) {
+  const entry = { date: today(), note };
+  const sha = currentSha(projectRoot);
+  if (sha) entry.sha = sha;
+  const paths = declaredPaths(check);
+  if (paths.length > 0) entry.paths = paths;
+  return entry;
+}
+
+/**
+ * How many of a project's manual checks are signed and still fresh — the
+ * number that lets a report say "executed proof" and "signed proof" apart
+ * instead of counting both as green.
+ */
+export function summarizeSignoffs(projectRoot, checks) {
+  const signoffs = loadSignoffs(projectRoot);
+  const counts = { manual: 0, fresh: 0, expired: 0, unverifiable: 0, pending: 0 };
+  for (const ch of checks) {
+    if (ch?.type !== "manual") continue;
+    counts.manual += 1;
+    counts[signoffState(projectRoot, ch, signoffs[ch.name ?? "check"]).state] += 1;
+  }
+  return counts;
+}

package/src/lib/snapshot.js

@@ -0,0 +1,209 @@
+// @ts-check
+import path from "node:path";
+import { readdirSync } from "node:fs";
+import { isDir, isFile, read, walk } from "./fs-ops.js";
+import * as idx from "./index-json.js";
+import { deriveIndex, indexesMatch, specHeader, listHeader } from "./scan.js";
+import { cliVersion } from "./version.js";
+import { summarize as coverageSummary } from "./coverage-model.js";
+import { summarize as traceSummary } from "./trace-model.js";
+import { acceptedDecisions, productSection, hasProductSection } from "./constitution-model.js";
+import { computeActions } from "./actions.js";
+import { readLedger } from "./ledger.js";
+import { parseChangeTitle, checklistProgress } from "./doc-model.js";
+import { summarizeSignoffs } from "./signoff.js";
+
+// ONE collector, several views (audit finding F7).
+//
+// `status`, `prime`, `handoff` and `report` were four commands rendering the
+// same three collections, and they got at them by importing functions out of
+// each other's modules: `prime` reached into `status` for `collectStatus`,
+// `handoff` and `report` reached into `prime` for `openChanges`, and all
+// three reached into `coverage` and `trace` for their summaries. Every one of
+// those is a command module — a RENDERER — being used as a data source, which
+// is how four surfaces end up able to disagree about the same number.
+//
+// So the project's state is collected ONCE, here, into a plain object. The
+// four commands become formatters over it: same numbers, four shapes, and a
+// new view costs a function rather than a fifth traversal of the tree.
+//
+// Nothing here prints and nothing here writes.
+
+const VERIFY_CONFIG_REL = ".doctrina/verify.json";
+
+/**
+ * Everything the read-only views report, collected in one pass.
+ *
+ * `actions` is included because three of the four views end with "what next",
+ * and computing it separately in each was the same duplication one level up.
+ */
+export function collectSnapshot(projectRoot, { actions = true } = {}) {
+  let index = null;
+  try {
+    index = idx.load(projectRoot);
+  } catch {
+    index = null;
+  }
+  let indexState = "missing";
+  if (index) {
+    indexState = indexesMatch(deriveIndex(projectRoot, index), index) ? "in-sync" : "drifted";
+  }
+
+  // Collected once, then shared: the views render it and `computeActions`
+  // recommends from it, so a recommendation can never disagree with the row
+  // it comes from (change 0037, extended to `next` by change 0064).
+  const coverage = coverageSummary(projectRoot);
+  const trace = traceSummary(projectRoot);
+  const verify = readVerifyConfig(projectRoot);
+
+  return {
+    project: index?.project ?? path.basename(projectRoot),
+    stamp: index?.framework_version ?? null,
+    cli: cliVersion(),
+    indexState,
+    coverage,
+    trace,
+    verify,
+    specs: countSpecs(projectRoot),
+    decisions: countDecisions(projectRoot),
+    skills: countSkills(projectRoot),
+    openChanges: openChanges(projectRoot),
+    adrs: acceptedDecisions(projectRoot),
+    nonGoals: productSection(projectRoot, "Non-goals"),
+    hasNonGoalsSection: hasProductSection(projectRoot, "Non-goals"),
+    // The gate state is already collected above; hand it over so the whole
+    // snapshot stays one read of the tree (change 0037).
+    actions: actions ? computeActions(projectRoot, { coverage, trace, verify }) : [],
+    archive: index?.artifacts?.changes_archive ?? [],
+    // The lane each open change was born in, for the report's mix. Read from
+    // the index rather than re-parsed, so one derivation owns the field.
+    openLanes: (index?.artifacts?.changes ?? []).map((c) => c.lane ?? null),
+    // The archive ledger, parsed (change 0046). The index records WHICH
+    // changes landed; the ledger records what each one touched and when, in
+    // one append-only file — which is what a question like "how often has
+    // this capability moved?" is actually asking about.
+    ledger: readLedger(projectRoot).entries,
+  };
+}
+
+/**
+ * The subset `status --json`, `doctor` and the dashboard have always
+ * published. Kept as its own shape so the JSON envelope does not silently
+ * grow the day a view needs one more field.
+ */
+export function collectStatus(projectRoot) {
+  const s = collectSnapshot(projectRoot, { actions: false });
+  return {
+    project: s.project,
+    stamp: s.stamp,
+    cli: s.cli,
+    indexState: s.indexState,
+    coverage: s.coverage,
+    trace: s.trace,
+    verify: s.verify,
+    specs: s.specs,
+    decisions: s.decisions,
+    skills: s.skills,
+  };
+}
+
+function readVerifyConfig(projectRoot) {
+  const p = path.join(projectRoot, VERIFY_CONFIG_REL);
+  if (!isFile(p)) return { configured: false, checks: 0, invalid: false, signoffs: null };
+  try {
+    const cfg = JSON.parse(read(p));
+    const checks = Array.isArray(cfg?.checks) ? cfg.checks : [];
+    // Executed proof and SIGNED proof are different claims (change 0039), and
+    // a report that adds them together hides which is which. The counts ride
+    // along so every view can say so without loading the sign-off store
+    // itself.
+    const signoffs = summarizeSignoffs(projectRoot, checks);
+    return { configured: true, checks: checks.length, invalid: false, signoffs };
+  } catch {
+    return { configured: true, checks: 0, invalid: true, signoffs: null };
+  }
+}
+
+/** Open changes with their proposal status/title and task progress. */
+export function openChanges(projectRoot) {
+  const changesDir = path.join(projectRoot, ".doctrina", "changes");
+  const out = [];
+  if (!isDir(changesDir)) return out;
+  for (const id of readdirSync(changesDir).sort()) {
+    if (id === "archive" || id.startsWith(".")) continue;
+    if (!isDir(path.join(changesDir, id))) continue;
+    const proposalPath = path.join(changesDir, id, "proposal.md");
+    const proposal = isFile(proposalPath) ? read(proposalPath) : null;
+    const title = proposal ? parseChangeTitle(proposal) : null;
+    const status = proposal ? (listHeader(proposal, "Status") ?? "proposed") : "no proposal.md";
+    const tasksPath = path.join(changesDir, id, "tasks.md");
+    // One counter for every surface (change 0067). This one used to require
+    // TEXT after the box, so the scaffold's empty placeholders were invisible
+    // and `prime` reported "tasks 0/3" for a change with six open boxes.
+    const progress = isFile(tasksPath)
+      ? checklistProgress(read(tasksPath))
+      : { total: 0, done: 0, open: [], placeholders: 0 };
+    const tasksTotal = progress.total;
+    const tasksDone = progress.done;
+    const unchecked = progress.open.map((t) => t || "(unwritten task — the scaffold's placeholder)");
+    out.push({ id, title, status, tasksDone, tasksTotal, unchecked });
+  }
+  return out;
+}
+
+function countSpecs(projectRoot) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  const impl = {};
+  let total = 0;
+  if (isDir(specsDir)) {
+    for (const cap of readdirSync(specsDir).sort()) {
+      const p = path.join(specsDir, cap, "spec.md");
+      if (!isFile(p)) continue;
+      total += 1;
+      const implRaw = specHeader(read(p), "Implementation");
+      if (implRaw) {
+        const word = implRaw.trim().split(/[\s—-]+/)[0].toLowerCase();
+        impl[word] = (impl[word] ?? 0) + 1;
+      }
+    }
+  }
+  const changesDir = path.join(projectRoot, ".doctrina", "changes");
+  let open = 0;
+  if (isDir(changesDir)) {
+    for (const e of readdirSync(changesDir)) {
+      if (e === "archive" || e.startsWith(".")) continue;
+      if (isDir(path.join(changesDir, e))) open += 1;
+    }
+  }
+  return { total, impl, openChanges: open };
+}
+
+function countDecisions(projectRoot) {
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  let total = 0, proposed = 0, bare = 0;
+  const isBare = (v) => {
+    const t = (v ?? "").trim();
+    return t === "" || t === "—" || t === "-";
+  };
+  if (isDir(adrDir)) {
+    for (const f of walk(adrDir)) {
+      if (!/^\d{4}-.+\.md$/.test(path.basename(f))) continue;
+      total += 1;
+      const text = read(f);
+      const status = (listHeader(text, "Status") ?? "").toLowerCase();
+      if (status === "proposed") proposed += 1;
+      if (status === "accepted") {
+        const evidence = listHeader(text, "Evidence");
+        const landed = listHeader(text, "Landed");
+        if (evidence !== null && isBare(evidence) && isBare(landed)) bare += 1;
+      }
+    }
+  }
+  return { total, proposed, bare };
+}
+
+function countSkills(projectRoot) {
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  if (!isDir(skillsDir)) return 0;
+  return walk(skillsDir).filter((f) => f.endsWith(".md")).length;
+}