doctrina-cli 0.9.0 → 0.11.0

package/src/commands/doctor.js

@@ -0,0 +1,135 @@
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { exists } from "../lib/fs-ops.js";
+import { collectStatus } from "./status.js";
+import { c } from "../lib/colors.js";
+
+// Aggregate diagnostic: the one command to run when "something looks wrong"
+// and you do not know which gate to ask. It sequences the existing checks —
+// validate, index drift, clean-checkout lint, template shape — and reports
+// each with its exact remediation command. A DRIVER over existing commands
+// (like `close`): it adds no checks of its own, so it can never disagree
+// with the authoritative gates it fronts.
+
+const cliEntry = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "index.js");
+
+export async function run(_positional, _flags) {
+  const projectRoot = process.cwd();
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+
+  console.log(c.bold("Doctrina doctor") + c.gray(" — aggregate diagnostic (read-only):"));
+  console.log("");
+
+  let failures = 0;
+  let warningsTotal = 0;
+  const row = (state, name, detail, fix) => {
+    const mark = state === "ok" ? c.green("ok  ") : state === "warn" ? c.yellow("warn") : c.red("FAIL");
+    console.log(`  ${mark}  ${name.padEnd(16)} ${detail}`);
+    if (fix) console.log(`        ${" ".repeat(16)} ${c.gray(`fix: ${fix}`)}`);
+    if (state === "fail") failures += 1;
+  };
+
+  // 1. Structural gate (validate), machine-read so the counts are exact.
+  const v = runSelf(["validate", "--json"], projectRoot);
+  let vParsed = null;
+  try {
+    vParsed = JSON.parse(v.stdout);
+  } catch {
+    vParsed = null;
+  }
+  if (!vParsed) {
+    row("fail", "validate", "did not produce a report", "doctrina validate");
+  } else if (!vParsed.ok) {
+    row("fail", "validate", `${vParsed.errors.length} error${vParsed.errors.length === 1 ? "" : "s"}, ${vParsed.warnings.length} warning${vParsed.warnings.length === 1 ? "" : "s"}`, "doctrina validate  (then `doctrina validate --fix` for index drift)");
+    for (const e of vParsed.errors.slice(0, 3)) console.log(`        ${" ".repeat(16)} ${c.red("·")} ${e}`);
+  } else if (vParsed.warnings.length > 0) {
+    warningsTotal += vParsed.warnings.length;
+    row("warn", "validate", `0 errors, ${vParsed.warnings.length} warning${vParsed.warnings.length === 1 ? "" : "s"}`, "doctrina validate  (warnings listed there)");
+  } else {
+    row("ok", "validate", "all structural checks pass");
+  }
+
+  // 2. Index ↔ tree drift.
+  const drift = runSelf(["index", "rebuild", "--check"], projectRoot);
+  if (drift.status === 0) row("ok", "index", "index.json matches the tree");
+  else row("fail", "index", "index.json has drifted from the tree", "doctrina validate --fix   (or `doctrina index rebuild`)");
+
+  // 3. Evidence and provenance ratios (cheap summaries; strict gates confirm).
+  const s = collectStatus(projectRoot);
+  if (s.coverage.totalCriteria === 0) {
+    row("warn", "coverage", "no acceptance criteria declared yet", "write criteria with evidence — see `doctrina coverage`");
+    warningsTotal += 1;
+  } else if (s.coverage.pct === 100 && s.coverage.totalDangling === 0 && s.coverage.totalConditional === 0) {
+    row("ok", "coverage", `${s.coverage.pct}% (${s.coverage.totalCovered}/${s.coverage.totalCriteria} criteria)`);
+  } else {
+    row("warn", "coverage", `${s.coverage.pct}% (${s.coverage.totalCovered}/${s.coverage.totalCriteria}${s.coverage.totalDangling ? `, ${s.coverage.totalDangling} dangling` : ""}${s.coverage.totalConditional ? `, ${s.coverage.totalConditional} conditional` : ""})`, "doctrina coverage   (cite the missing evidence)");
+    warningsTotal += 1;
+  }
+  if (s.trace.anchors === 0) {
+    row("warn", "trace", "no intent anchors declared in product.md", "tag bullets `- [SC1] ...`, add `**Realizes:**` to specs");
+    warningsTotal += 1;
+  } else if (s.trace.realized === s.trace.anchors && s.trace.untraceable === 0 && s.trace.dangling === 0) {
+    row("ok", "trace", `${s.trace.realized}/${s.trace.anchors} anchors realized`);
+  } else {
+    row("warn", "trace", `${s.trace.realized}/${s.trace.anchors} realized, ${s.trace.dropped} dropped, ${s.trace.untraceable} untraceable`, "doctrina trace");
+    warningsTotal += 1;
+  }
+
+  // 4. Clean-checkout reproducibility lint (ADR 0008).
+  const clean = runSelf(["verify", "--clean"], projectRoot);
+  if (clean.status === 0) row("ok", "clean-checkout", "no reproducibility footguns detected");
+  else row("fail", "clean-checkout", "a fresh clone would not build/run as-is", "doctrina verify --clean   (fix the listed package.json footguns)");
+
+  // 5. Template shape vs the running CLI's recommendation.
+  const tmpl = runSelf(["templates", "check"], projectRoot);
+  if (tmpl.status === 0) row("ok", "templates", "project follows the current template shape");
+  else {
+    row("warn", "templates", "recommended sections/fields are missing", "doctrina templates update   (--write applies)");
+    warningsTotal += 1;
+  }
+
+  // 6. Verify configuration (the real build gate must exist to be run).
+  if (s.verify.invalid) row("fail", "verify config", ".doctrina/verify.json is invalid JSON", "fix the JSON, then `doctrina verify`");
+  else if (!s.verify.configured) {
+    row("warn", "verify config", "no verify.json — the build gate is undeclared", "doctrina verify --init");
+    warningsTotal += 1;
+  } else {
+    row("ok", "verify config", `${s.verify.checks} check${s.verify.checks === 1 ? "" : "s"} declared (run \`doctrina verify\` to execute)`);
+  }
+
+  console.log("");
+  if (failures > 0) {
+    console.log(c.red("fail") + ` ${failures} failing area${failures === 1 ? "" : "s"} — fix commands above, then re-run \`doctrina doctor\``);
+    return 1;
+  }
+  if (warningsTotal > 0) {
+    console.log(c.yellow("warn") + ` no failures; ${warningsTotal} advisory item${warningsTotal === 1 ? "" : "s"} above`);
+    return 0;
+  }
+  console.log(c.green("ok") + " every diagnostic is green — `doctrina verify` remains the build gate to execute");
+  return 0;
+}
+
+function runSelf(args, cwd) {
+  return spawnSync(process.execPath, [cliEntry, ...args], {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, NO_COLOR: "1" },
+  });
+}
+
+export const help = `
+Usage: doctrina doctor
+
+Aggregate diagnostic: run the structural gate (validate), the index
+drift check, the coverage/trace ratios, the clean-checkout lint
+(verify --clean), the template-shape check, and the verify-config
+presence — each reported with its exact remediation command.
+
+A driver over the existing commands; it adds no checks of its own.
+Read-only. Exits 1 when any area fails, 0 otherwise (warnings allowed).
+`;

package/src/commands/handoff.js

@@ -0,0 +1,94 @@
+import path from "node:path";
+import process from "node:process";
+import { exists } from "../lib/fs-ops.js";
+import { collectStatus } from "./status.js";
+import { computeActions } from "./next.js";
+import { openChanges } from "./prime.js";
+import { today } from "../lib/dates.js";
+import { c } from "../lib/colors.js";
+
+// Session handoff note: everything the NEXT session (a fresh agent, a
+// teammate, tomorrow's you) needs to resume without re-reading the tree —
+// where the open work stands task-by-task, which gates are red, and the
+// exact command to continue with. Doctrina's thesis is that context must
+// survive across sessions; this command is that thesis for the in-flight
+// change. It is a VIEW derived from the tree at call time, deliberately not
+// a stored file: a saved note goes stale the moment work continues, the
+// tree never does (no new home for facts).
+
+export async function run(_positional, _flags) {
+  const projectRoot = process.cwd();
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+
+  const s = collectStatus(projectRoot);
+  const open = openChanges(projectRoot);
+  const actions = computeActions(projectRoot);
+
+  console.log(`# Doctrina handoff — ${s.project} (${today()})`);
+  console.log("");
+
+  // Gate digest — the red ones are what the resuming session fixes first.
+  console.log("## Where things stand");
+  console.log("");
+  console.log(`- index: ${s.indexState} · framework stamp: ${s.stamp ?? "—"} (CLI ${s.cli})`);
+  console.log(`- coverage: ${s.coverage.pct}% (${s.coverage.totalCovered}/${s.coverage.totalCriteria} criteria` +
+    (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`;
+  console.log(`- trace: ${tr}` + (s.trace.untraceable ? ` (${s.trace.untraceable} untraceable)` : ""));
+  console.log(`- verify: ${s.verify.configured ? `${s.verify.checks} checks declared — run \`doctrina verify\`` : "not configured"}`);
+
+  // The in-flight work, task by task.
+  console.log("");
+  if (open.length === 0) {
+    console.log("## Open work");
+    console.log("");
+    console.log("- none — the tree is at rest; start with `doctrina work \"<prompt>\"`");
+  } else {
+    for (const ch of open) {
+      console.log(`## Open change \`${ch.id}\`${ch.title ? ` — ${ch.title}` : ""}`);
+      console.log("");
+      console.log(`- proposal status: ${ch.status}`);
+      if (ch.tasksTotal > 0) {
+        console.log(`- tasks: ${ch.tasksDone}/${ch.tasksTotal} checked`);
+        for (const t of ch.unchecked.slice(0, 8)) console.log(`  - [ ] ${t}`);
+        if (ch.unchecked.length > 8) console.log(`  - … ${ch.unchecked.length - 8} more in tasks.md`);
+      } else {
+        console.log("- tasks: no tasks.md checklist found");
+      }
+      console.log(`- resume with: \`doctrina work --resume ${ch.id}\` · close with: \`doctrina close ${ch.id}\``);
+      console.log("");
+    }
+  }
+
+  // What to do, in priority order.
+  console.log("## Next actions");
+  console.log("");
+  if (actions.length === 0) {
+    console.log("1. nothing pending — `doctrina next` will confirm; pick up new work");
+  } else {
+    actions.forEach((a, i) => console.log(`${i + 1}. ${a}`));
+  }
+
+  console.log("");
+  console.log("*Generated read-only from the tree — regenerate anytime with `doctrina handoff`.*");
+  if (process.stdout.isTTY) {
+    console.log("");
+    console.log(c.gray("tip: pipe it — `doctrina handoff > note.md` — or paste it as the first message of the next session"));
+  }
+  return 0;
+}
+
+export const help = `
+Usage: doctrina handoff
+
+Print a session handoff note in Markdown: gate digest, each open change
+with its task-by-task progress and the exact resume command, and the
+prioritised next actions. Made to be pasted as the first message of the
+next agent session (or piped to a file).
+
+Deliberately a derived view, not a stored file — the tree is the truth
+and never goes stale; regenerate on demand. Read-only; always exits 0.
+`;

package/src/commands/init.js

@@ -56,7 +56,18 @@ export async function run(_positional, flags) {
     description = await ask("One-sentence project description:");
   }
 
-  const agentSelector = flagString(flags, "agent");
+  let agentSelector = flagString(flags, "agent");
+  // Interactive wizard step: when no --agent was given and we are on a real
+  // terminal, offer the adapter install instead of silently skipping it —
+  // first-run users rarely know the flag exists. Never fires in pipes/CI
+  // (no TTY) or under --non-interactive, so scripted init is unchanged.
+  if (agentSelector === undefined && !nonInteractive && process.stdin.isTTY && process.stdout.isTTY) {
+    const answer = await ask(
+      `Install an agent adapter? (${SUPPORTED_AGENTS.join("/")}/all/none)`,
+      { defaultValue: "none" },
+    );
+    if (answer && answer !== "none") agentSelector = answer;
+  }
   const fromPath = flagString(flags, "from");
   const agentsMdPath = path.join(projectRoot, "AGENTS.md");
   const doctrinaDir = path.join(projectRoot, ".doctrina");

package/src/commands/next.js

@@ -4,15 +4,43 @@ import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, read, relPath, walk } from "../lib/fs-ops.js";
 import * as idx from "../lib/index-json.js";
 import { deriveIndex, indexesMatch, listHeader } from "../lib/scan.js";
+import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 
-export async function run(_positional, _flags) {
+export async function run(_positional, flags) {
   const projectRoot = process.cwd();
+  const json = flagBool(flags, "json", false);
   if (!exists(path.join(projectRoot, ".doctrina"))) {
-    console.log("1. doctrina init — this directory is not a Doctrina project yet");
+    const first = "doctrina init — this directory is not a Doctrina project yet";
+    console.log(json ? JSON.stringify({ actions: [first] }, null, 2) : `1. ${first}`);
     return 0;
   }
 
+  const actions = computeActions(projectRoot);
+
+  if (json) {
+    console.log(JSON.stringify({ actions }, null, 2));
+    return 0;
+  }
+
+  if (actions.length === 0) {
+    console.log(c.green("ok") + " no open work.");
+    console.log("");
+    console.log("Start something:");
+    console.log(`  doctrina change new <id> "<title>"   open a change proposal`);
+    console.log(`  doctrina spec new <capability>       spec a new capability`);
+    return 0;
+  }
+
+  console.log(c.bold("Next actions") + c.gray(" (in priority order):"));
+  console.log("");
+  actions.forEach((a, i) => console.log(`${i + 1}. ${a}`));
+  return 0;
+}
+
+// The priority-ordered action list, render-free — shared with `prime`,
+// `handoff`, and the --json output.
+export function computeActions(projectRoot) {
   const actions = [];
 
   // A pending intake is the very first thing to resolve: until it is
@@ -106,19 +134,7 @@ export async function run(_positional, _flags) {
     actions.push("doctrina index rebuild — index.json is missing or unreadable");
   }
 
-  if (actions.length === 0) {
-    console.log(c.green("ok") + " no open work.");
-    console.log("");
-    console.log("Start something:");
-    console.log(`  doctrina change new <id> "<title>"   open a change proposal`);
-    console.log(`  doctrina spec new <capability>       spec a new capability`);
-    return 0;
-  }
-
-  console.log(c.bold("Next actions") + c.gray(" (in priority order):"));
-  console.log("");
-  actions.forEach((a, i) => console.log(`${i + 1}. ${a}`));
-  return 0;
+  return actions;
 }
 
 // Return a single skill-capture nudge, or null. Fires only when no skill has
@@ -147,7 +163,7 @@ function suggestSkillCapture(projectRoot) {
 }
 
 export const help = `
-Usage: doctrina next
+Usage: doctrina next [--json]
 
 Inspect the .doctrina/ tree and print the recommended next workflow
 actions in priority order: open changes (missing proposal, unchecked

package/src/commands/prime.js

@@ -0,0 +1,118 @@
+import path from "node:path";
+import process from "node:process";
+import { readdirSync } from "node:fs";
+import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
+import { listHeader } from "../lib/scan.js";
+import { collectStatus } from "./status.js";
+import { computeActions } from "./next.js";
+import { acceptedDecisions, productSection } from "./constitution.js";
+import { c } from "../lib/colors.js";
+
+// Session primer: the ~40-line read that orients an agent at the start of a
+// session — where things stand, what the standing rules are, what work is
+// open, and what to do next — without paying for the full context pack.
+// It sits between `status` (numbers only) and `context --concat` (everything):
+// enough to act, cheap enough to run every session. Strictly read-only; every
+// line is assembled from artifacts that already own the fact (no new home).
+
+export async function run(_positional, _flags) {
+  const projectRoot = process.cwd();
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+
+  const s = collectStatus(projectRoot);
+
+  console.log(c.bold("Doctrina prime") + c.gray(` — ${s.project}  (framework ${s.stamp ?? "—"} / CLI ${s.cli})`));
+  console.log("");
+
+  // One-line gate digest.
+  const cov = `${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` : "verify not configured";
+  console.log(c.bold("Gates  ") + `index ${s.indexState} · coverage ${cov} · trace ${tr} · ${verify}`);
+  const implBreak = Object.entries(s.specs.impl).map(([k, v]) => `${v} ${k}`).join(", ");
+  console.log(
+    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`,
+  );
+
+  // Standing rules, titles only — `constitution` has the full text.
+  const adrs = acceptedDecisions(projectRoot);
+  console.log("");
+  console.log(c.bold("Rules") + c.gray(`  (${adrs.length} accepted ADRs — \`doctrina constitution\` for detail)`));
+  for (const a of adrs) console.log(`  ${c.cyan(a.id)}  ${a.title}`);
+  const nonGoals = productSection(projectRoot, "Non-goals");
+  if (nonGoals.length > 0) {
+    console.log(c.gray(`  + ${nonGoals.length} non-goal${nonGoals.length === 1 ? "" : "s"} declared in product.md`));
+  }
+
+  // Open work, with unchecked-task counts — the resume points.
+  console.log("");
+  console.log(c.bold("Open work"));
+  const open = openChanges(projectRoot);
+  if (open.length === 0) {
+    console.log(c.gray("  none — `doctrina work \"<prompt>\"` opens the next change"));
+  } else {
+    for (const ch of open) {
+      const tasks = ch.tasksTotal > 0 ? ` · tasks ${ch.tasksDone}/${ch.tasksTotal}` : "";
+      console.log(`  ${c.cyan(ch.id)}  ${ch.title ?? ""}${c.gray(` (${ch.status}${tasks})`)}`);
+    }
+  }
+
+  // Next actions (top 5 — `doctrina next` for the full list).
+  const actions = computeActions(projectRoot);
+  console.log("");
+  console.log(c.bold("Next"));
+  if (actions.length === 0) {
+    console.log(c.gray("  nothing pending — pick up new work"));
+  } else {
+    actions.slice(0, 5).forEach((a, i) => console.log(`  ${i + 1}. ${a}`));
+    if (actions.length > 5) console.log(c.gray(`  … ${actions.length - 5} more — \`doctrina next\``));
+  }
+
+  console.log("");
+  console.log(c.gray("Read deeper: `doctrina context [<cap>] --concat` · `doctrina why <cap>` · `doctrina show <ref>`"));
+  return 0;
+}
+
+// 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?.match(/^#\s+(?:Change\s+[^—-]*[—-]\s*)?(.+)$/m)?.[1]?.trim() ?? null;
+    const status = proposal ? (listHeader(proposal, "Status") ?? "proposed") : "no proposal.md";
+    const tasksPath = path.join(changesDir, id, "tasks.md");
+    let tasksDone = 0, tasksTotal = 0, unchecked = [];
+    if (isFile(tasksPath)) {
+      for (const line of read(tasksPath).split(/\r?\n/)) {
+        const m = line.match(/^-\s+\[([ xX])\]\s+(.*)$/);
+        if (!m) continue;
+        tasksTotal += 1;
+        if (m[1] === " ") unchecked.push(m[2].trim());
+        else tasksDone += 1;
+      }
+    }
+    out.push({ id, title, status, tasksDone, tasksTotal, unchecked });
+  }
+  return out;
+}
+
+export const help = `
+Usage: doctrina prime
+
+Print the session primer: gate digest, standing rules (accepted ADR
+titles + non-goal count), open work with task progress, and the top
+next actions — the ~40-line read that orients an agent at session
+start without paying for the full context pack.
+
+Read-only; always exits 0. Deeper reads: \`doctrina context\`,
+\`doctrina why <cap>\`, \`doctrina show <ref>\`.
+`;

package/src/commands/report.js

@@ -0,0 +1,142 @@
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { exists } from "../lib/fs-ops.js";
+import * as idx from "../lib/index-json.js";
+import { collectStatus } from "./status.js";
+import { openChanges } from "./prime.js";
+import { flagString } from "../lib/args.js";
+import { today } from "../lib/dates.js";
+import { c } from "../lib/colors.js";
+
+// Periodic digest in Markdown — the standup/PR-description view: what was
+// archived, where the gates stand, and what local git says about the period.
+// Read-only, no network; the git section degrades silently outside a repo.
+
+export async function run(_positional, flags) {
+  const projectRoot = process.cwd();
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+
+  const sinceRaw = flagString(flags, "since") ?? "7";
+  const days = Number.parseInt(sinceRaw, 10);
+  if (!Number.isFinite(days) || days <= 0) {
+    console.error(c.red("error:") + ` --since expects a positive day count, got "${sinceRaw}"`);
+    return 2;
+  }
+  const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+  const cutoffIso = cutoff.toISOString().slice(0, 10);
+
+  const s = collectStatus(projectRoot);
+
+  console.log(`# Doctrina report — ${s.project} (${cutoffIso} → ${today()})`);
+  console.log("");
+
+  // Gates.
+  console.log("## Gates");
+  console.log("");
+  console.log(`- index: ${s.indexState} · framework stamp: ${s.stamp ?? "—"} (CLI ${s.cli})`);
+  console.log(`- coverage: ${s.coverage.pct}% (${s.coverage.totalCovered}/${s.coverage.totalCriteria} criteria)` +
+    (s.coverage.totalDangling ? ` — ${s.coverage.totalDangling} dangling` : "") +
+    (s.coverage.totalConditional ? ` — ${s.coverage.totalConditional} conditional` : ""));
+  console.log(`- trace: ${s.trace.anchors === 0 ? "no anchors declared" : `${s.trace.realized}/${s.trace.anchors} anchors realized`}`);
+  console.log(`- verify: ${s.verify.configured ? `${s.verify.checks} checks declared` : "not configured"}`);
+
+  // Work shipped in the window (from the index ledger) + work in flight.
+  console.log("");
+  console.log("## Changes");
+  console.log("");
+  const archived = archivedSince(projectRoot, cutoffIso);
+  if (archived.length === 0) {
+    console.log(`- archived in period: none`);
+  } else {
+    console.log(`- archived in period: ${archived.length}`);
+    for (const ch of archived) console.log(`  - ${ch.applied} — \`${ch.id}\` ${ch.title}`);
+  }
+  const open = openChanges(projectRoot);
+  if (open.length === 0) {
+    console.log("- open now: none");
+  } else {
+    console.log(`- open now: ${open.length}`);
+    for (const ch of open) {
+      const tasks = ch.tasksTotal > 0 ? ` (tasks ${ch.tasksDone}/${ch.tasksTotal})` : "";
+      console.log(`  - \`${ch.id}\`${ch.title ? ` ${ch.title}` : ""}${tasks}`);
+    }
+  }
+
+  // Artifact counts, for trend-watching between reports.
+  console.log("");
+  console.log("## Artifacts");
+  console.log("");
+  console.log(`- specs: ${s.specs.total} · decisions: ${s.decisions.total}` +
+    (s.decisions.proposed ? ` (${s.decisions.proposed} proposed)` : "") +
+    ` · skills: ${s.skills}`);
+
+  // Local git window — commits, fix share, top churn. No network.
+  console.log("");
+  console.log("## Git (local, last " + days + " days)");
+  console.log("");
+  const git = gitWindow(projectRoot, days);
+  if (!git) {
+    console.log("- no git history available (not a repository, or git not installed)");
+  } else {
+    console.log(`- commits: ${git.commits} (${git.fixes} fix-shaped, ${git.commits ? Math.round((git.fixes / git.commits) * 100) : 0}%)`);
+    if (git.churn.length > 0) {
+      console.log(`- top-churn files:`);
+      for (const [file, n] of git.churn) console.log(`  - ${file} (${n} touches)`);
+    }
+  }
+
+  console.log("");
+  console.log(`*Generated read-only by \`doctrina report --since ${days}\`; deeper numbers: \`doctrina metrics\`.*`);
+  return 0;
+}
+
+function archivedSince(projectRoot, cutoffIso) {
+  let index;
+  try {
+    index = idx.load(projectRoot);
+  } catch {
+    return [];
+  }
+  return (index.artifacts?.changes_archive ?? [])
+    .filter((ch) => typeof ch.applied === "string" && ch.applied >= cutoffIso)
+    .sort((a, b) => String(a.applied).localeCompare(String(b.applied)));
+}
+
+function gitWindow(projectRoot, days) {
+  const log = spawnSync("git", ["log", `--since=${days} days ago`, "--pretty=%s"], {
+    cwd: projectRoot,
+    encoding: "utf8",
+  });
+  if (log.status !== 0) return null;
+  const subjects = log.stdout.split(/\r?\n/).filter((l) => l.trim().length > 0);
+  const fixes = subjects.filter((sub) => /^(fix|bug|hotfix|patch)(\(|:|!)/i.test(sub)).length;
+
+  const files = spawnSync("git", ["log", `--since=${days} days ago`, "--name-only", "--pretty=format:"], {
+    cwd: projectRoot,
+    encoding: "utf8",
+  });
+  const counts = new Map();
+  if (files.status === 0) {
+    for (const line of files.stdout.split(/\r?\n/)) {
+      const f = line.trim();
+      if (!f) continue;
+      counts.set(f, (counts.get(f) ?? 0) + 1);
+    }
+  }
+  const churn = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5);
+  return { commits: subjects.length, fixes, churn };
+}
+
+export const help = `
+Usage: doctrina report [--since <days>]
+
+Print a Markdown digest for the period (default: last 7 days): gate
+state, changes archived in the window (from the index ledger), open
+work with task progress, artifact counts, and a local-git summary
+(commits, fix share, top-churn files). Made for standups and PR
+descriptions. Read-only; no network. \`doctrina metrics\` has the
+deeper git-derived numbers.
+`;