doctrina-cli 0.16.0 → 0.18.0

package/src/commands/intent.js

@@ -2,6 +2,7 @@
 import path from "node:path";
 import process from "node:process";
 import { exists, isFile, read, relPath, write } from "../lib/fs-ops.js";
+import { intentKey } from "../lib/validation-model.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
@@ -102,9 +103,21 @@ function intentAdd(projectRoot, textArg) {
   let id = null;
   let text = textArg;
   const pinned = textArg.match(/^([A-Z]+)(\d+)\s*:\s*(.+)$/);
+  if (pinned) text = pinned[3].trim();
+
+  // The same intent twice is two anchors for one goal: realize either and the
+  // other stays "dropped", so `trace --strict` fails on a gap nobody can
+  // close. An agent re-running a playbook step is enough to do it. Compared
+  // folded, so case, accents and spacing do not slip a twin past.
+  const twin = anchors.find((a) => intentKey(a.text) === intentKey(text));
+  if (twin) {
+    console.error(c.red("error:") + ` [${twin.id}] already states this intent in product.md`);
+    console.error(c.gray("hint: ") + `realize [${twin.id}] with a spec's \`Realizes:\` header, or reword this one if it is a different goal`);
+    return 1;
+  }
+
   if (pinned) {
     id = pinned[1] + pinned[2];
-    text = pinned[3].trim();
     if (anchors.some((a) => a.id === id)) {
       console.error(c.red("error:") + ` anchor [${id}] already exists in product.md`);
       return 1;

package/src/commands/metrics.js

@@ -11,7 +11,7 @@ import { GIT_STATE, historyState, git } from "../lib/git.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { USAGE_ENV, summarise } from "../lib/usage.js";
 import { OPERATIONS } from "../lib/commands.js";
-import { REEDIT_WINDOW_DAYS, computeSnapshot, parseLog, readSeries, latestSnapshot, trend, round } from "../lib/metrics-model.js";
+import { REEDIT_WINDOW_DAYS, sinceWindow, computeSnapshot, parseLog, readSeries, latestSnapshot, trend, round } from "../lib/metrics-model.js";
 
 // Local-only adoption metrics derived from git history. No network calls,
 // no telemetry: the numbers stay in the repository, versioned like any
@@ -37,6 +37,14 @@ export async function run(_positional, flags) {
   // recent one (audit finding F15) — a year of measurement answering one
   // question. Reading the series is what makes the saving worth doing.
   if (flagBool(flags, "trend", false)) return printTrend(projectRoot);
+  // The window is the invocation's: refused the same with or without history.
+  const sinceRaw = flagString(flags, "since", "90");
+  const since = sinceWindow(sinceRaw);
+  if (since === null) {
+    console.error(c.red("error:") + ` --since expects a day count, a date (YYYY-MM-DD) or "<n> <unit>s ago", got "${sinceRaw}"`);
+    console.error(c.gray("hint: ") + "examples: --since 30 · --since 2026-01-01 · --since \"3 months ago\"");
+    return EXIT.USAGE;
+  }
   const probe = git(projectRoot, ["rev-parse", "--is-inside-work-tree"]);
   // "No history yet" is a VALID state, not a failure — a brand-new project
   // is the most common state in which someone explores this command, and it
@@ -55,8 +63,6 @@ export async function run(_positional, flags) {
     return EXIT.OK;
   }
 
-  const sinceRaw = flagString(flags, "since", "90");
-  const since = /^\d+$/.test(sinceRaw) ? `${sinceRaw} days ago` : sinceRaw;
   const save = flagBool(flags, "save", false);
 
   const log = git(projectRoot, [
@@ -218,8 +224,10 @@ Flags:
                      opt-in usage log. Recording is OFF unless DOCTRINA_USAGE_LOG
                      names a file; only the operation is recorded, never
                      arguments, and nothing leaves the machine.
-  --since <n|date>   Window: a day count (default 90) or any git-parseable
-                     date ("2026-01-01", "3 months ago").
+  --since <n|date>   Window: a day count (default 90), a calendar date
+                     ("2026-01-01") or "<n> <unit>s ago" ("3 months ago").
+                     Anything else is refused: git reads any text as a
+                     date, so a typo would measure the wrong window.
   --save             Write .doctrina/metrics/YYYY-MM-DD.json and print the
                      deltas against the most recent prior snapshot.
   --trend            Read the saved snapshots instead of git: every snapshot

package/src/commands/next.js

@@ -79,9 +79,10 @@ export async function run(_positional, flags) {
 export const RUNNERS = {
   triage: () => import("./triage.js"),
   intake: () => import("./intake.js"),
-  analyze: () => import("./analyze.js"),
+  "change check": () => import("./change.js"),
   "change apply": () => import("./change.js"),
   "change archive": () => import("./change.js"),
+  close: () => import("./close.js"),
   "index rebuild": () => import("./index-rebuild.js"),
 };
 

package/src/commands/prime.js

@@ -29,8 +29,8 @@ export async function run(_positional, flags) {
   if (!exists(path.join(projectRoot, ".doctrina"))) {
     throw notADoctrinaProject();
   }
-  // --rules: the standing rules in full, which is what `constitution` printed
-  // (change 0049). The primer names the ADRs and counts the non-goals; this
+  // --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);
@@ -49,9 +49,8 @@ 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. The same lines
-            \`doctrina constitution\` printed, from the same collection —
-            that command is deprecated and delegates here.
+            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

@@ -2,14 +2,12 @@
 import path from "node:path";
 import process from "node:process";
 import { exists } from "../lib/fs-ops.js";
-import { flagBool, flagString } from "../lib/args.js";
+import { flagBool, flagString, parsePositiveInt } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
-import { collectSnapshot } from "../lib/snapshot.js";
+import { collectSnapshot, collectReportWindow } from "../lib/snapshot.js";
 import { renderView } from "../lib/views.js";
-import { gitWindow, historyState, windowCutoff } from "../lib/git.js";
 import { draftAgentChangelog, renderDraft } from "../lib/agent-changelog.js";
-import { collectMetrics } from "../lib/metrics-model.js";
 import { cliVersion } from "../lib/version.js";
 
 // Periodic digest in Markdown — the standup/PR-description view: what was
@@ -33,8 +31,8 @@ export async function run(_positional, flags) {
   }
 
   const sinceRaw = flagString(flags, "since");
-  const days = Number.parseInt(sinceRaw ?? "7", 10);
-  if (!Number.isFinite(days) || days <= 0) {
+  const days = parsePositiveInt(sinceRaw ?? "7");
+  if (days === null) {
     console.error(c.red("error:") + ` --since expects a positive day count, got "${sinceRaw}"`);
     return 2;
   }
@@ -51,19 +49,9 @@ export async function run(_positional, flags) {
     return 0;
   }
 
-  const options = {
-    days,
-    cutoffIso: windowCutoff(days),
-    git: gitWindow(projectRoot, days),
-    // Why there is no window, when there is none — the same door `metrics`
-    // and `context` already ask, so the three cannot disagree about the
-    // state of one repository (change 0080).
-    gitState: historyState(projectRoot),
-    // The same snapshot `metrics` renders, for the same window (change
-    // 0050). One definition of "revert rate", so the digest and the metrics
-    // command cannot report two different numbers for one period.
-    metrics: collectMetrics(projectRoot, `${days} days ago`),
-  };
+  // 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;
 }
@@ -78,7 +66,8 @@ work with task progress, artifact counts, and a local-git summary
 descriptions. Read-only; no network. \`doctrina metrics\` has the
 deeper git-derived numbers.
 
-The same view as \`doctrina status --view report --since <days>\`.
+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

package/src/commands/review.js

@@ -8,7 +8,8 @@ import { c } from "../lib/colors.js";
 import { rankCapabilitiesByDiff } from "../lib/work-model.js";
 import { readLedger, churnByCapability } from "../lib/ledger.js";
 import { changedFiles, windowCutoff, historyState, refExists } from "../lib/git.js";
-import { dependentsOf } from "../lib/scan.js";
+import { dependentsOf, deltaCapabilities } from "../lib/scan.js";
+import { refuseChangeRef } from "../lib/project.js";
 import { notADoctrinaProject, EXIT } from "../lib/exit-codes.js";
 import { summarize as coverageSummary } from "../lib/coverage-model.js";
 import { summarize as traceSummary } from "../lib/trace-model.js";
@@ -37,7 +38,7 @@ const CHURN_NOTABLE = 3;
 // bury every other finding under a file listing.
 const ORPHAN_LIST_LIMIT = 5;
 
-export const flags = { boolean: ["json", "strict"], string: ["diff"] };
+export const flags = { boolean: ["json", "strict"], string: ["diff", "change"] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -60,8 +61,26 @@ export async function run(_positional, flags) {
     return EXIT.USAGE;
   }
 
+  // --change <id>: review the tree AS that change's close sees it (change
+  // 0200). Its deltas are the spec updates — merged one step later, by
+  // `apply` — so the capabilities they target count as updated.
+  const changeId = flagString(flags, "change");
+  /** @type {Set<string> | null} */
+  let changeCaps = null;
+  if (changeId !== undefined) {
+    const refused = refuseChangeRef(changeId);
+    if (refused !== null) return refused;
+    const changeDir = path.join(projectRoot, ".doctrina", "changes", changeId);
+    if (!isDir(changeDir)) {
+      console.error(c.red("error:") + ` change "${changeId}" not found at .doctrina/changes/${changeId}`);
+      return EXIT.USAGE;
+    }
+    changeCaps = new Set(deltaCapabilities(changeDir));
+  }
+
   const { all, sourceFiles } = reviewScope(projectRoot, against);
-  console.log(c.bold("Review") + c.gray(against ? ` — vs ${against}` : " — working-tree changes"));
+  console.log(c.bold("Review") + c.gray(against ? ` — vs ${against}` : " — working-tree changes") +
+    (changeId ? c.gray(` · change ${changeId}`) : ""));
   console.log("");
 
   if (all.length === 0) {
@@ -85,10 +104,18 @@ export async function run(_positional, flags) {
   );
   const ranked = rankCapabilitiesByDiff(projectRoot, sourceFiles, { limit: Infinity });
   const touched = new Set([...specChanged, ...ranked.map((m) => m.id)]);
-  for (const m of ranked) {
-    if (!specChanged.has(m.id)) {
-      breaks.push(`code under capability "${m.id}" changed, but its spec was not updated — confirm \`.doctrina/specs/${m.id}/spec.md\` still describes the code (update it, or note why not)`);
+  const stale = ranked.map((m) => m.id).filter((id) => !specChanged.has(id) && !changeCaps?.has(id));
+  if (changeCaps === null) {
+    for (const id of stale) {
+      breaks.push(`code under capability "${id}" changed, but its spec was not updated — confirm \`.doctrina/specs/${id}/spec.md\` still describes the code (update it, or note why not)`);
     }
+  } else if (stale.length > 0) {
+    // Reviewed as a change: code under capabilities it carries no delta for
+    // is either this change forgetting a delta or other work lying in the
+    // tree — the review cannot tell which, so it says both, ONCE. One break
+    // per capability, repeated on every close, is how the warning became
+    // noise nobody read (field review, 0.17).
+    breaks.push(`code changed under ${stale.length === 1 ? "a capability" : `${stale.length} capabilities`} this change carries no delta for: ${stale.map((id) => `"${id}"`).join(", ")} — if this change made those edits, add a delta (or note why the spec still holds); if other work did, it is not this change's (commit or stash it)`);
   }
 
   // 1b. Dependents of touched capabilities (the machine-readable
@@ -107,7 +134,10 @@ export async function run(_positional, flags) {
   if (touched.size > 0) {
     const since = windowCutoff(CHURN_WINDOW_DAYS);
     const churn = churnByCapability(readLedger(projectRoot).entries, { since })
-      .filter((row) => touched.has(row.capability) && row.changes >= CHURN_NOTABLE);
+      // Reviewed as a change, only the capabilities it updates: churn is
+      // context for the spec being changed, and four lines of it about
+      // ground the change merely stands near was more noise per close.
+      .filter((row) => (changeCaps ?? touched).has(row.capability) && row.changes >= CHURN_NOTABLE);
     for (const row of churn) {
       notes.push(`capability "${row.capability}" landed ${row.changes} changes in the last ${CHURN_WINDOW_DAYS} days (last ${row.last}) — history, not a verdict: read it as "this area is moving", not "this area is wrong"`);
     }
@@ -219,7 +249,7 @@ function runContractCheck(projectRoot) {
 }
 
 export const help = `
-Usage: doctrina review [--diff <ref>] [--strict]
+Usage: doctrina review [--diff <ref>] [--change <id>] [--strict]
 
 Deterministic conformance review of your changes against the spec / ADR /
 contract tree. By default it reviews the working-tree changes (tracked +
@@ -232,6 +262,15 @@ citing missing proof, product intent realized by no spec, and contract
 port/reference collisions. It checks conformance shape, NOT semantic
 fidelity (whether the code does what the spec says stays a human/LLM call).
 
+--change <id> reviews the tree as that change's close does: the capabilities
+its deltas target count as updated (the close merges them one step later),
+and code under capabilities it carries no delta for is reported in one line —
+this change forgot a delta, or other work is lying in the tree.
+
+A file's owner is the spec whose \`**Source:**\` claims it; failing that, the
+spec citing its exact path; failing both, the path and basename inference,
+from specs that declare no Source.
+
 Read-only. Exits 0 as a report; with --strict, exits 1 when any hard break
 exists (CI gate). Notes (advisory) never fail the gate.
 `;

package/src/commands/skill.js

@@ -1,7 +1,6 @@
 // @ts-check
 import path from "node:path";
 import process from "node:process";
-import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, mkdirp, read, relPath, walk, write } from "../lib/fs-ops.js";
 import { readTemplate, locateTemplatesDir, substitute } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
@@ -9,10 +8,10 @@ import { today } from "../lib/dates.js";
 import { flagBool, flagString, flagGivenWithoutValue } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
+import { skillCandidates } from "../lib/skill-candidates.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
 import { parseFrontmatter } from "../lib/doc-model.js";
-import { git, GIT_STATE } from "../lib/git.js";
-import { FIX_SHAPED, FIX_SHAPED_SUBJECT } from "../lib/lexicon.js";
+import { fold, skillSlug } from "../lib/lexicon.js";
 import { artifactNameError } from "../lib/names.js";
 
 const SUBCOMMANDS = ["new", "list", "sync", "suggest"];
@@ -104,7 +103,7 @@ export function draftFromError(text) {
   // Distinctive words, most frequent first — the fallback when an error
   // carries no structure at all.
   const counts = new Map();
-  for (const w of raw.toLowerCase().match(/[a-z][a-z0-9_-]{3,}/g) ?? []) {
+  for (const w of fold(raw).match(/[a-z][a-z0-9_-]{3,}/g) ?? []) {
     if (ERROR_STOP.has(w)) continue;
     counts.set(w, (counts.get(w) ?? 0) + 1);
   }
@@ -125,8 +124,8 @@ export function draftFromError(text) {
   // also mentions do not both land in the name.
   const seedTokens = [];
   const seenToken = new Set();
-  for (const token of [...identifiers.map((i) => i.toLowerCase()), ...keywords]) {
-    const norm = token.replace(/[^a-z0-9]/g, "");
+  for (const token of [...identifiers.map((i) => fold(i)), ...keywords]) {
+    const norm = fold(token).replace(/[^a-z0-9]/g, "");
     if (norm === "" || seenToken.has(norm)) continue;
     seenToken.add(norm);
     seedTokens.push(token);
@@ -237,57 +236,8 @@ function skillSuggest(args, flags) {
     return writeErrorDraft(projectRoot, draft, doWrite);
   }
 
+  const candidates = skillCandidates(projectRoot, { since, limit: GIT_LOG_LIMIT });
   const skillsDir = path.join(projectRoot, ".doctrina", "skills");
-  const existingFiles = isDir(skillsDir) ? walk(skillsDir).filter((f) => f.endsWith(".md")) : [];
-  const existing = new Set(existingFiles.map((f) => path.basename(f, ".md")));
-  // A lesson may already be captured under a DIFFERENT slug (0.11.0 field
-  // review item 11: the human names the skill after the lesson, not after the
-  // change id — "tela-preta-crash-de-render..." for change 0049). Two extra
-  // dedup signals: an existing skill whose body cites the candidate's change
-  // id / commit hash, and token-overlap similarity between the slugs.
-  const existingBodies = existingFiles.map((f) => ({ slug: path.basename(f, ".md"), body: read(f) }));
-  const captured = (cand) => {
-    if (existing.has(cand.slug)) return true;
-    for (const sk of existingBodies) {
-      if (cand.id && sk.body.includes(cand.id)) return true;
-      if (cand.from && sk.body.includes(cand.from)) return true;
-      if (slugSimilarity(cand.slug, sk.slug) >= 0.5) return true;
-    }
-    return false;
-  };
-
-  // Two deterministic sources, deduped by slug. `seen` guards against a lesson
-  // appearing twice (e.g. a fix committed and later archived as a change).
-  /** @type {SkillCandidate[]} */
-  const candidates = [];
-  const seen = new Set();
-
-  // Source 1 — archived change proposals with a fix-shaped folder name.
-  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
-  if (isDir(archiveDir)) {
-    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)) continue;
-      const slug = skillSlug(id);
-      if (seen.has(slug)) continue;
-      /** @type {SkillCandidate} */
-      const cand = { id, slug, source: "change", from: name };
-      if (captured(cand)) continue; // captured (any slug) or cited by an existing skill
-      const proposal = path.join(archiveDir, name, "proposal.md");
-      cand.why = isFile(proposal) ? firstWhyLine(read(proposal)) : "";
-      seen.add(slug);
-      candidates.push(cand);
-    }
-  }
-
-  // Source 2 — fix-shaped commits in the git history (ADR 0013). Archive wins a
-  // slug collision: a `## Why` paragraph is a richer seed than a subject line.
-  for (const cand of gitFixCommits(projectRoot, { since, limit: GIT_LOG_LIMIT })) {
-    if (seen.has(cand.slug) || captured(cand)) continue;
-    seen.add(cand.slug);
-    candidates.push(cand);
-  }
 
   if (candidates.length === 0) {
     console.log(c.gray("no uncaptured fix-shaped lessons found in .doctrina/changes/archive/ or the git history"));
@@ -344,7 +294,7 @@ function skillSuggest(args, flags) {
     idx.save(projectRoot, index);
   }
   console.log("");
-  console.log(c.green("ok") + ` scaffolded ${created} skill stub${created === 1 ? "" : "s"} — fill the description/when/body, then \`doctrina skill sync\``);
+  console.log(c.green("ok") + ` scaffolded ${created} skill stub${created === 1 ? "" : "s"} — fill the description/when/body, then \`doctrina index rebuild\``);
   return 0;
 }
 
@@ -361,87 +311,6 @@ function seedLabel(cand) {
     : `Candidate from change "${cand.id}"`;
 }
 
-// Source 2 for `skill suggest`: fix-shaped commits in the git history (ADR
-// 0013). Deterministic — a regex on the subject, never a read of the diff
-// (ADR 0005 semantic-fidelity ceiling). Returns [] silently when this is not a
-// git repo, git is absent, or the --since ref is unknown, so the command
-// degrades to archive-only rather than erroring.
-function gitFixCommits(projectRoot, { since, limit }) {
-  // US (0x1f) between fields, RS (0x1e) between records — robust against any
-  // newline or punctuation inside a subject or body.
-  const format = "%H%x1f%s%x1f%b%x1e";
-  const args = ["log", "--no-merges", `--format=${format}`];
-  if (since) args.push(`${since}..HEAD`);
-  else args.push("-n", String(limit));
-
-  const r = git(projectRoot, args);
-  if (r.state !== GIT_STATE.OK || !r.stdout) return [];
-
-  /** @type {SkillCandidate[]} */
-  const out = [];
-  const seen = new Set();
-  for (const record of r.stdout.split("\x1e")) {
-    const [sha, subject = "", body = ""] = record.replace(/^\r?\n/, "").split("\x1f");
-    if (!sha || !sha.trim()) continue;
-    if (!FIX_SHAPED_SUBJECT.test(subject)) continue;
-    const slug = commitSlug(subject);
-    if (!slug || seen.has(slug)) continue; // first commit wins a duplicate lesson
-    seen.add(slug);
-    const firstBodyLine = body.split(/\r?\n/).map((l) => l.trim()).find(Boolean) ?? "";
-    out.push({
-      id: slug,
-      slug,
-      source: "commit",
-      ref: sha.trim().slice(0, 9),
-      why: subject.trim() + (firstBodyLine ? ` — ${firstBodyLine}` : ""),
-    });
-  }
-  return out;
-}
-
-// Derive a skill slug from a commit subject: drop a conventional-commit
-// "type(scope): " prefix, then reuse skillSlug for the lowercase/hyphenate/cap.
-function commitSlug(subject) {
-  const stripped = subject.replace(/^[a-z]+(?:\([^)]*\))?!?\s*:\s*/i, "");
-  return skillSlug(stripped.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, ""));
-}
-
-function skillSlug(id) {
-  // Reuse the change id as the skill slug, trimmed to a sane length.
-  const slug = id.replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
-  return slug.length > 40 ? slug.slice(0, 40).replace(/-+$/g, "") : (slug || "lesson");
-}
-
-// Token-overlap similarity between two kebab slugs (Jaccard over meaningful
-// tokens). "0049-fix-tela-preta-render" vs "tela-preta-crash-de-render-sem-
-// error-boundary" share tela/preta/render → high overlap even though the
-// human renamed the skill after the lesson. Deterministic; never semantic.
-function slugSimilarity(a, b) {
-  const toks = (s) => new Set(
-    String(s).split("-").filter((t) => t.length >= 3 && !/^\d+$/.test(t) && !SLUG_NOISE.has(t)),
-  );
-  const A = toks(a);
-  const B = toks(b);
-  if (A.size === 0 || B.size === 0) return 0;
-  let inter = 0;
-  for (const t of A) if (B.has(t)) inter += 1;
-  return inter / (A.size + B.size - inter);
-}
-
-// Fix-shaped verbs and connectives carry no lesson identity — without this,
-// every "fix-..." candidate looks 30% similar to every "fix-..." skill.
-const SLUG_NOISE = new Set([
-  "fix", "bug", "hotfix", "patch", "the", "and", "for", "with", "sem", "com",
-  "que", "nao", "por", "para", "una", "uma", "dos", "das",
-]);
-
-function firstWhyLine(proposalText) {
-  const m = proposalText.match(/##\s*Why\s*\r?\n+([^\r\n][^\r\n]*)/i);
-  if (!m) return "";
-  const line = m[1].trim();
-  return /^<!--/.test(line) ? "" : line;
-}
-
 function skillNew(args, flags) {
   const name = args[0];
   const nameError = artifactNameError(name, "skill name");
@@ -482,7 +351,7 @@ function skillNew(args, flags) {
   idx.save(projectRoot, index);
   console.log(c.green("indexed") + ` skill "${name}"`);
   console.log("");
-  console.log(c.gray("hint: ") + "fill the description and when frontmatter fields, then run `doctrina skill sync` to update index.json");
+  console.log(c.gray("hint: ") + "fill the description and when frontmatter fields, then run `doctrina index rebuild` to update index.json");
   return 0;
 }
 

package/src/commands/spec.js

@@ -155,8 +155,12 @@ function specSet(args, flags) {
   let text = read(specPath);
   const applied = [];
   const errors = [];
+  // An error names what to correct: the INVOCATION (a value out of domain, a
+  // criterion that does not exist, a malformed flag) or the SPEC (a header
+  // or section it lacks). Only the second is fixed by editing the work.
+  const refused = (msg) => errors.push({ msg, argument: true });
   const apply = (res) => {
-    if (res.error) errors.push(res.error);
+    if (res.error) errors.push({ msg: res.error, argument: res.cause === "argument" });
     else { text = res.text; applied.push(res.summary); }
   };
   // Order: headers, then version, then criterion — independent edits, all or
@@ -173,7 +177,7 @@ function specSet(args, flags) {
       const derivedValue = derivedImplementations(projectRoot, { only: new Set([capability]) })
         .get(capability)?.derived;
       if (!derivedValue) {
-        errors.push(`--implementation auto needs acceptance criteria to derive from; ${capability} declares none`);
+        errors.push({ msg: `--implementation auto needs acceptance criteria to derive from; ${capability} declares none`, argument: false });
       } else {
         apply(setHeader(text, "Implementation", derivedValue));
       }
@@ -182,23 +186,25 @@ function specSet(args, flags) {
     }
   }
   if (bump !== undefined) {
-    if (!["major", "minor", "patch"].includes(bump)) errors.push(`--bump needs major|minor|patch (got "${bump}")`);
+    if (!["major", "minor", "patch"].includes(bump)) refused(`--bump needs major|minor|patch (got "${bump}")`);
     else apply(bumpVersion(text, bump));
   }
   if (versionExplicit !== undefined) {
-    if (!/^\d+\.\d+\.\d+$/.test(versionExplicit)) errors.push(`--version needs semver X.Y.Z (got "${versionExplicit}")`);
+    if (!/^\d+\.\d+\.\d+$/.test(versionExplicit)) refused(`--version needs semver X.Y.Z (got "${versionExplicit}")`);
     else apply(setHeader(text, "Version", versionExplicit));
   }
   if (criterion !== undefined) {
     const m = String(criterion).match(/^(\d+)\s*:\s*(.+)$/);
-    if (!m) errors.push(`--criterion needs "<n>:<mark>" (got "${criterion}")`);
+    if (!m) refused(`--criterion needs "<n>:<mark>" (got "${criterion}")`);
     else apply(setCriterionMark(text, Number(m[1]), m[2].trim()));
   }
 
   if (errors.length > 0) {
     console.error(c.red("error:") + ` ${errors.length} operation error${errors.length === 1 ? "" : "s"} — spec left untouched:`);
-    for (const e of errors) console.error(`  - ${e}`);
-    return 1;
+    for (const e of errors) console.error(`  - ${e.msg}`);
+    // Retrying an invocation error unchanged never succeeds (ADR 0018), so
+    // one in the list is enough to answer USAGE.
+    return errors.some((e) => e.argument) ? EXIT.USAGE : EXIT.GATE;
   }
 
   // Stamp Last updated when the header exists (best-effort, never an error).

package/src/commands/status.js

@@ -2,13 +2,14 @@
 import path from "node:path";
 import process from "node:process";
 import { exists } from "../lib/fs-ops.js";
-import { flagBool, flagString } from "../lib/args.js";
+import { flagBool, flagString, parsePositiveInt } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { emitJson } from "../lib/json-out.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
-import { collectSnapshot, collectStatus } from "../lib/snapshot.js";
+import { collectSnapshot, collectStatus, collectReportWindow } from "../lib/snapshot.js";
 import { renderView, VIEWS } from "../lib/views.js";
-import { gitWindow, historyState, windowCutoff } from "../lib/git.js";
+import { draftAgentChangelog, renderDraft } from "../lib/agent-changelog.js";
+import { cliVersion } from "../lib/version.js";
 import { suggest } from "../lib/suggest.js";
 
 // One-glance project health (review 2026-06-27 passive-user feature #1): a
@@ -32,6 +33,9 @@ export const jsonNative = true;
 
 export const flags = { boolean: ["json"], string: ["view", "since"] };
 
+// The snapshot's views, plus the one draft that is not a view of it.
+const STATUS_VIEWS = [...VIEWS, "agent-changelog"];
+
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
@@ -39,10 +43,10 @@ export async function run(_positional, flags) {
   }
 
   const view = flagString(flags, "view") ?? "dashboard";
-  if (!VIEWS.includes(view)) {
+  if (!STATUS_VIEWS.includes(view)) {
     console.error(c.red("error:") + ` unknown view "${view}"`);
-    const guess = suggest(view, VIEWS);
-    console.error(c.gray("hint: ") + (guess ? `did you mean --view ${guess}?` : `available: ${VIEWS.join(", ")}`));
+    const guess = suggest(view, STATUS_VIEWS);
+    console.error(c.gray("hint: ") + (guess ? `did you mean --view ${guess}?` : `available: ${STATUS_VIEWS.join(", ")}`));
     return 2;
   }
 
@@ -53,18 +57,24 @@ export async function run(_positional, flags) {
     return 0;
   }
 
-  const options = {};
-  if (view === "report") {
-    const sinceRaw = flagString(flags, "since") ?? "7";
-    const days = Number.parseInt(sinceRaw, 10);
-    if (!Number.isFinite(days) || days <= 0) {
+  let options = {};
+  if (view === "report" || view === "agent-changelog") {
+    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;
     }
-    options.days = days;
-    options.cutoffIso = windowCutoff(days);
-    options.git = gitWindow(projectRoot, days);
-    options.gitState = historyState(projectRoot);
+    // A DRAFT of the block `upgrade --write` writes into AGENTS.md, proposed
+    // from what the archived changes said they touched. Not a view of the
+    // snapshot, so it renders here; authorship stays human (ADR 0005). With
+    // no --since the window is "since the last tag".
+    if (view === "agent-changelog") {
+      const draft = draftAgentChangelog(projectRoot, { days: sinceRaw === undefined ? null : days });
+      for (const line of renderDraft(draft, cliVersion())) console.log(line);
+      return 0;
+    }
+    options = collectReportWindow(projectRoot, days);
   }
 
   const snapshot = collectSnapshot(projectRoot);
@@ -85,13 +95,22 @@ Flags:
                     dashboard  the default one-glance health board
                     prime      the session primer (\`doctrina prime\`)
                     handoff    the Markdown resume note (\`doctrina handoff\`)
-                    report     the period digest (\`doctrina report\`)
-  --since <days>  With --view report: the window (default 7).
+                    report     the period digest: gates, archived changes,
+                               open work, and local git numbers
+                    rules      the standing rules (\`doctrina prime --rules\`)
+                    agent-changelog
+                               a DRAFT of the AGENTS.md "What changed" block:
+                               one bullet per archived change that touched a
+                               documented surface, newest first, at most five.
+                               It proposes; a person cuts and rewrites.
+  --since <days>  With --view report: the window (default 7). With
+                  --view agent-changelog: the window (default: since the
+                  last tag).
   --json          Emit the snapshot as JSON (stable shape for agents and CI).
 
-All four views read ONE collection of the tree, so they can never report
-different numbers; \`prime\`, \`handoff\` and \`report\` are the same views
-under their own names.
+The views read ONE collection of the tree, so they can never report
+different numbers; \`prime\` and \`handoff\` are the same views under their
+own names. \`doctrina report\` is deprecated: it is \`--view report\`.
 
 It is a fast summary, not the authoritative gate: run \`doctrina validate\`
 and \`doctrina verify\` for the full structural and build checks, and