doctrina-cli 0.15.1 → 0.17.0

package/src/commands/next.js

@@ -2,13 +2,18 @@
 import path from "node:path";
 import process from "node:process";
 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 { exists, isDir } from "../lib/fs-ops.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { emitJson } from "../lib/json-out.js";
-import { collectRuntimeFindings } from "../lib/runtime.js";
+import { EXIT } from "../lib/exit-codes.js";
+import { action, computeActions, invocation } from "../lib/actions.js";
+
+// `next` answers "what now?". The ANSWER lives in `lib/actions.js` as
+// records; this module renders them and, under `--run`, executes one
+// (change 0032). Before that the answer WAS the sentence, so `--json`
+// returned prose in quotes and an agent had to re-read English to re-issue
+// a command the CLI had already assembled.
 
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
@@ -17,186 +22,127 @@ import { collectRuntimeFindings } from "../lib/runtime.js";
 // wrap it in the generic envelope.
 export const jsonNative = true;
 
-export const flags = { boolean: ["json"], string: [] };
+export const flags = { boolean: ["json", "run"], string: [] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
   const json = flagBool(flags, "json", false);
   if (!exists(path.join(projectRoot, ".doctrina"))) {
-    const first = "doctrina init — this directory is not a Doctrina project yet";
+    const first = action({
+      id: "not-a-project",
+      command: "init",
+      runnable: false,
+      why: "this directory is not a Doctrina project yet",
+    });
     if (json) emitJson("next", { actions: [first] });
-    else console.log(`1. ${first}`);
+    else console.log(`1. ${first.text}`);
     return 0;
   }
 
   const actions = computeActions(projectRoot);
 
+  if (flagBool(flags, "run", false)) {
+    return runFirst(actions);
+  }
+
   if (json) {
     emitJson("next", { actions });
     return 0;
   }
 
   if (actions.length === 0) {
-    console.log(c.green("ok") + " no open work.");
+    // The two doors AGENTS.md tells an agent to use, not the two hand-authoring
+    // commands it tells them to avoid (second audit). `intake` first for a
+    // project with nothing specced yet, `work` for one that has.
+    const specced = isDir(path.join(projectRoot, ".doctrina", "specs"))
+      && readdirSync(path.join(projectRoot, ".doctrina", "specs"), { withFileTypes: true })
+        .some((e) => e.isDirectory());
+    console.log(c.green("ok") + " every gate is satisfied and no change is open.");
     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`);
+    if (!specced) {
+      console.log(`  doctrina intake --text "<what this project is>"   turn intent into specs`);
+    }
+    console.log(`  doctrina work "<prompt>"                          open the next change`);
     return 0;
   }
 
   console.log(c.bold("Next actions") + c.gray(" (in priority order):"));
   console.log("");
-  actions.forEach((a, i) => console.log(`${i + 1}. ${a}`));
+  actions.forEach((a, i) => console.log(`${i + 1}. ${a.text}`));
   return 0;
 }
 
-// The priority-ordered action list, render-free — shared with `prime`,
-// `handoff`, and the --json output.
-export function computeActions(projectRoot) {
-  const actions = [];
-
-  // RUNTIME FIRST (change 0029). A declared wiring that does not hold is
-  // not a queue item — it is the reason the last run lied. After a job goes
-  // green having executed nothing, "open a change on the observability
-  // capability" sends the agent to polish the Markdown of an empty-state
-  // message while the cause sits in a file no other action names. A broken
-  // declaration outranks every artifact chore below it.
-  try {
-    const runtime = collectRuntimeFindings(projectRoot);
-    const errs = runtime.findings.filter((f) => f.level === "error");
-    if (errs.length > 0) {
-      actions.push(
-        `doctrina triage — ${errs.length} runtime declaration${errs.length === 1 ? " does" : "s do"} not hold ` +
-        `(first: ${errs[0].code} ${errs[0].message.slice(0, 80)}${errs[0].message.length > 80 ? "…" : ""})`,
-      );
+// The command modules `--run` may dispatch to, loaded on demand. Static
+// imports here would make every module that imports `next` (prime, handoff,
+// watch) pay for the whole command tree just to render a list.
+export const RUNNERS = {
+  triage: () => import("./triage.js"),
+  intake: () => import("./intake.js"),
+  "change check": () => import("./change.js"),
+  "change apply": () => import("./change.js"),
+  "change archive": () => import("./change.js"),
+  "index rebuild": () => import("./index-rebuild.js"),
+};
+
+/**
+ * Execute the first runnable action, and only that one.
+ *
+ * ONE action, not the queue: the list is recomputed from the tree after
+ * every change to it, so running two in a row would act on a list the
+ * second half of which was computed before the first half ran. Stopping
+ * also keeps the human's approval point where they put it — `close` is the
+ * command that deliberately runs a whole sequence.
+ */
+async function runFirst(actions) {
+  const next = actions.find((a) => a.runnable);
+  if (!next) {
+    const blocked = actions.find((a) => !a.runnable);
+    if (!blocked) {
+      console.log(c.green("ok") + " no open work to run.");
+      return EXIT.OK;
     }
-  } catch {
-    // A malformed contract is `validate`'s finding to make, not a reason
-    // for `next` to fall over.
-  }
-
-  // A pending intake is the very first thing to resolve: until it is
-  // converted, product.md and the specs are still empty scaffolding.
-  const intakePath = path.join(projectRoot, ".doctrina", "intake.md");
-  if (isFile(intakePath)) {
-    const status = (listHeader(read(intakePath), "Status") ?? "pending").toLowerCase();
-    if (status !== "converted") {
-      actions.push("doctrina intake — a pending intake awaits conversion into product.md and specs");
+    // Everything left needs authorship, not execution. Say what, and say
+    // it is not a failure of the command.
+    console.log(c.yellow("nothing to run") + " — the next action needs a person, not a command:");
+    console.log("");
+    console.log(`    ${blocked.text}`);
+    const inv = invocation(blocked);
+    if (inv) {
+      console.log("");
+      console.log(c.gray("When you have made the call, record it with: ") + c.cyan(inv));
     }
+    return EXIT.OK;
   }
 
-  // Open changes drive the loop: finish what is started before opening more.
-  const changesDir = path.join(projectRoot, ".doctrina", "changes");
-  if (isDir(changesDir)) {
-    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");
-      if (!isFile(proposalPath)) {
-        actions.push(`add a proposal.md to .doctrina/changes/${id}/ (open changes need one)`);
-        continue;
-      }
-      const status = listHeader(read(proposalPath), "Status") ?? "proposed";
-      if (status === "applied") {
-        actions.push(`doctrina change archive ${id} — applied but not archived`);
-        continue;
-      }
-      const tasksPath = path.join(changesDir, id, "tasks.md");
-      const unchecked = isFile(tasksPath)
-        ? (read(tasksPath).match(/^-\s+\[ \]/gm) ?? []).length
-        : 0;
-      if (unchecked > 0) {
-        actions.push(`complete ${unchecked} open task${unchecked === 1 ? "" : "s"} in .doctrina/changes/${id}/tasks.md`);
-        continue;
-      }
-      const deltas = walk(path.join(changesDir, id, "specs")).filter((p) => p.endsWith("delta.md"));
-      if (deltas.length > 0) {
-        actions.push(`doctrina analyze ${id}, then doctrina change apply ${id} — tasks done, ${deltas.length} delta${deltas.length === 1 ? "" : "s"} ready`);
-      } else {
-        actions.push(`add spec deltas under .doctrina/changes/${id}/specs/, or apply as metadata-only: doctrina change apply ${id}`);
-      }
-    }
+  const loader = RUNNERS[next.command];
+  if (!loader) {
+    // A runnable action whose command has no runner is a bug in this map,
+    // not something to paper over by silently doing nothing.
+    console.error(c.red("error:") + ` no runner for "${next.command}"`);
+    console.error(c.gray("hint: ") + `run it yourself: ${invocation(next)}`);
+    return EXIT.GATE;
   }
 
-  // ADRs stuck in proposed need a human decision; accepted-but-bare ADRs are
-  // the rot the review flagged — a decision with nothing behind it (no Evidence,
-  // no Landed) is drift waiting to be superseded. Surface the proposed ones
-  // first (a pending decision blocks more than a missing stamp).
-  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
-  const landNudges = [];
-  const isBareValue = (v) => {
-    const t = (v ?? "").trim();
-    return t === "" || t === "—" || t === "-";
-  };
-  for (const f of walk(adrDir)) {
-    if (!f.endsWith(".md")) continue;
-    const m = path.basename(f).match(/^(\d{4})-/);
-    if (!m) continue;
-    const text = read(f);
-    const status = listHeader(text, "Status");
-    if (status && status.toLowerCase() === "proposed") {
-      actions.push(`review ADR ${m[1]} (${relPath(projectRoot, f)}): doctrina decision accept ${m[1]}, or supersede it`);
-    } else if (status && status.toLowerCase() === "accepted") {
-      // Bare only when BOTH anchors are empty (Evidence header present-but-bare
-      // and no Landed stamp). An ADR that opts out of Evidence entirely
-      // (header absent) is not nagged.
-      const evidence = listHeader(text, "Evidence");
-      const landed = listHeader(text, "Landed");
-      if (evidence !== null && isBareValue(evidence) && isBareValue(landed)) {
-        landNudges.push(`record what proves ADR ${m[1]}: cite its **Evidence:**, or once it ships, doctrina decision land ${m[1]}`);
-      }
-    }
-  }
-  for (const n of landNudges) actions.push(n);
-
-  // No procedural memory captured yet, but the history shows a fix-shaped
-  // change — exactly the lesson a skill exists to keep from being relearned
-  // (review §5: the change-0003 "tolerate LLM code fences" case). One gentle
-  // nudge, only when skills are empty, so it never nags a project that opted in.
-  const skillNudge = suggestSkillCapture(projectRoot);
-  if (skillNudge) actions.push(skillNudge);
-
-  // Index drift is silent rot; surface it last.
-  try {
-    const current = idx.load(projectRoot);
-    if (!indexesMatch(deriveIndex(projectRoot, current), current)) {
-      actions.push("doctrina index rebuild — index.json has drifted from the tree");
-    }
-  } catch {
-    actions.push("doctrina index rebuild — index.json is missing or unreadable");
-  }
-
-  return actions;
-}
+  console.log(c.bold("Running") + ` ${c.cyan(invocation(next))}` + c.gray(` — ${next.why}`));
+  console.log("");
+  const mod = await loader();
+  // A sub-operation ("change archive") is passed as a positional, exactly
+  // as the entrypoint would.
+  const [, ...sub] = next.command.split(" ");
+  const code = await mod.run([...sub, ...next.args], new Map());
 
-// Return a single skill-capture nudge, or null. Fires only when no skill has
-// been written yet (skills/ holds nothing but .gitkeep) AND the archive shows a
-// fix-shaped change whose lesson is the textbook case for a skill. Deterministic
-// pattern match on the archived folder name — a hint, never a decision (ADR 0005).
-const FIX_SHAPED = /(?:^|-)(fix|bug|hotfix|patch|parse|parsing|tolerate|workaround|race|deadlock|flaky|retry|escape|sanitize|sanitise)(?:-|$)/;
-
-function suggestSkillCapture(projectRoot) {
-  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
-  if (isDir(skillsDir)) {
-    const hasSkill = walk(skillsDir).some((f) => f.endsWith(".md"));
-    if (hasSkill) return null; // opted in already — never nag
-  }
-  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
-  if (!isDir(archiveDir)) return null;
-  for (const name of readdirSync(archiveDir).sort()) {
-    if (!isDir(path.join(archiveDir, name))) continue;
-    const id = name.replace(/^\d{4}-\d{2}-\d{2}-/, "");
-    if (FIX_SHAPED.test(id)) {
-      return `capture a skill from past fixes (e.g. "${id}"): doctrina skill new <slug> — ` +
-        `on-demand procedural memory so the next agent does not relearn it (none exist yet)`;
-    }
+  console.log("");
+  if (code === EXIT.OK) {
+    console.log(c.green("✓ ran ") + c.cyan(invocation(next)) + c.gray(" — `doctrina next` for what follows"));
+  } else {
+    console.log(c.red("✗ ") + c.cyan(invocation(next)) + c.gray(` exited ${code} — fix it, then rerun`));
   }
-  return null;
+  return code;
 }
 
 export const help = `
-Usage: doctrina next [--json]
+Usage: doctrina next [--json] [--run]
 
 Inspect the .doctrina/ tree and print the recommended next workflow
 actions in priority order: runtime declarations that no longer hold
@@ -205,8 +151,20 @@ run lied), open changes (missing proposal, unchecked
 tasks, deltas ready to apply, applied-but-unarchived), ADRs still in
 proposed status, accepted ADRs with nothing proving them (cite Evidence
 or run "decision land"), a skill-capture nudge when a past fix went
-uncaptured, and index drift last. Read-only; always exits 0.
+uncaptured, and index drift last.
 
 Intended use: agents and humans run it to resume work without
 re-reading the whole tree.
+
+Options:
+  --json   Emit the actions as records — { id, command, args, why, gate,
+           severity, runnable, text }. Branch on \`command\`/\`args\`; \`text\`
+           is the same line the terminal prints.
+  --run    Execute the first RUNNABLE action in-process and stop. An action
+           that needs a person to decide — accept an ADR, write a proposal,
+           complete a task, capture a skill — is never runnable however
+           mechanical its edit would be, and \`--run\` names it instead.
+           Exits with the executed command's own code.
+
+Read-only without --run, and always exits 0 then.
 `;

package/src/commands/prime.js

@@ -1,14 +1,11 @@
 // @ts-check
 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";
+import { exists } from "../lib/fs-ops.js";
+import { flagBool } from "../lib/args.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { collectSnapshot } from "../lib/snapshot.js";
+import { renderView } from "../lib/views.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
@@ -16,102 +13,30 @@ import { notADoctrinaProject } from "../lib/exit-codes.js";
 // 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).
+//
+// Since change 0037 the primer is a VIEW over lib/snapshot.js, rendered by
+// lib/views.js and reachable as `doctrina status --view prime`. This module
+// is the name AGENTS.md tells agents to run, and nothing else: no collection,
+// no formatting, and nothing for another command to import out of.
 
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
 // let six flags ship undeclared and silently swallow a positional (C3).
-export const flags = { boolean: ["json"], string: [] };
+export const flags = { boolean: ["json", "rules"], string: [] };
 
-export async function run(_positional, _flags) {
+export async function run(_positional, flags) {
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
-
-  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>`"));
+  // --rules: the standing rules in full, which is what the removed
+  // `constitution` printed (changes 0049, 0175). The primer names the ADRs and counts the non-goals; this
+  // prints both lists, from the same collection, so the two cannot disagree.
+  const view = flagBool(flags, "rules", false) ? "rules" : "prime";
+  for (const line of renderView(view, collectSnapshot(projectRoot))) console.log(line);
   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
 
@@ -120,6 +45,13 @@ 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.
 
+The same view as \`doctrina status --view prime\`; both render one
+collection of the tree, so they cannot disagree.
+
+  --rules   Print the standing rules in full instead of the primer: every
+            accepted ADR and every declared non-goal — what the removed
+            \`doctrina constitution\` printed, from the same collection.
+
 Read-only; always exits 0. Deeper reads: \`doctrina context\`,
 \`doctrina why <cap>\`, \`doctrina show <ref>\`.
 `;

package/src/commands/report.js

@@ -1,24 +1,28 @@
 // @ts-check
 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 { flagBool, flagString, parsePositiveInt } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { collectSnapshot, collectReportWindow } from "../lib/snapshot.js";
+import { renderView } from "../lib/views.js";
+import { draftAgentChangelog, renderDraft } from "../lib/agent-changelog.js";
+import { cliVersion } from "../lib/version.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.
+//
+// Since change 0037 it is a VIEW over the shared snapshot (lib/snapshot.js →
+// lib/views.js), also reachable as `doctrina status --view report --since N`,
+// and its two git probes go through lib/git.js rather than a private
+// spawnSync that could read a refusal as an empty answer.
 
 // Flags this command accepts. Declared HERE, with the command, so
 // adding a command never requires editing the entrypoint — the gap that
 // let six flags ship undeclared and silently swallow a positional (C3).
-export const flags = { boolean: ["json"], string: ["since"] };
+export const flags = { boolean: ["json", "agent-changelog"], string: ["since"] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -26,117 +30,32 @@ export async function run(_positional, flags) {
     throw notADoctrinaProject();
   }
 
-  const sinceRaw = flagString(flags, "since") ?? "7";
-  const days = Number.parseInt(sinceRaw, 10);
-  if (!Number.isFinite(days) || days <= 0) {
+  const sinceRaw = flagString(flags, "since");
+  const days = parsePositiveInt(sinceRaw ?? "7");
+  if (days === null) {
     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}`);
-    }
+  // --agent-changelog: a DRAFT of the block `upgrade --write` writes into
+  // AGENTS.md, proposed from what the archived changes said they touched.
+  // A different report for a different audience — five bullets for an
+  // arriving agent, not a digest for a standup — so it replaces the view
+  // rather than appending to it. Authorship stays human (ADR 0005): the
+  // command proposes, a person cuts and rewrites.
+  if (flagBool(flags, "agent-changelog", false)) {
+    const draft = draftAgentChangelog(projectRoot, { days: sinceRaw === undefined ? null : days });
+    for (const line of renderDraft(draft, cliVersion())) console.log(line);
+    return 0;
   }
 
-  // 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\`.*`);
+  // One collector with `status --view report` (change 0176), so the
+  // deprecated name and its survivor cannot print different digests.
+  const options = collectReportWindow(projectRoot, days);
+  for (const line of renderView("report", collectSnapshot(projectRoot), options)) console.log(line);
   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>]
 
@@ -146,4 +65,16 @@ 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.
+
+Deprecated: this is \`doctrina status --view report --since <days>\`, and
+\`--agent-changelog\` is \`doctrina status --view agent-changelog\`.
+
+  --agent-changelog   Draft the AGENTS.md "What changed" block instead of
+                      the digest: one candidate bullet per archived change
+                      that touched a documented surface (a command, a flag,
+                      an exit code), newest first, capped at the block's
+                      five bullets. The window is "since the last tag"
+                      unless --since names one. It PROPOSES; a person cuts
+                      and rewrites, because what an agent must do
+                      differently is a judgement the CLI does not make.
 `;