doctrina-cli 0.17.0 → 0.20.0

package/src/commands/prime.js

@@ -1,11 +1,15 @@
 // @ts-check
 import path from "node:path";
 import process from "node:process";
-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";
+import { exists, read } from "../lib/fs-ops.js";
+import { findWorkspace, readWorkspace } from "../lib/workspace.js";
+import { listDeliveries } from "../lib/delivery.js";
+import { workspacePrimer } from "../lib/workspace-agents.js";
+import { flagBool, flagString } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
+import { collectSnapshot, openChanges, recentlyClosed } from "../lib/snapshot.js";
+import { renderView, pulse } 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
@@ -22,23 +26,77 @@ import { renderView } from "../lib/views.js";
 // 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", "rules"], string: [] };
+export const flags = { boolean: ["json", "rules", "pulse"], string: ["hook"] };
+
+// What an agent hook accepts on stdout (change 0211). Claude Code adds the
+// plain text of a SessionStart hook to the conversation; Cursor's
+// sessionStart reads `additional_context` from a JSON object. Both cap what
+// they keep — Claude at 10,000 characters — so the primer is cut short of
+// that rather than replaced by a file path the agent is never asked to read.
+const HOOK_AGENTS = ["claude", "cursor"];
+const HOOK_MAX_CHARS = 9000;
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
+    // At a workspace root the session belongs to the orchestrator (change
+    // 0223): the primer is the workspace's.
+    const found = findWorkspace(projectRoot);
+    if (found && found.via !== "pointer") return primeWorkspace(found.dir, flags);
     throw notADoctrinaProject();
   }
   // --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.
+  // --pulse: one line for a per-prompt hook — the open changes only, read
+  // without collecting the gates, because it runs before every prompt.
+  if (flagBool(flags, "pulse", false)) {
+    for (const line of pulse(openChanges(projectRoot), recentlyClosed(projectRoot, { limit: 1 }))) console.log(line);
+    return 0;
+  }
+  if (flags.has("hook")) {
+    const agent = flagString(flags, "hook");
+    if (!agent || !HOOK_AGENTS.includes(agent)) {
+      console.error(c.red("error:") + ` --hook needs one of ${HOOK_AGENTS.join(", ")} (got "${agent ?? ""}")`);
+      return EXIT.USAGE;
+    }
+    const text = ["Doctrina session primer (`doctrina prime`) — the project's gates, rules and open work:", "",
+      ...renderView("prime", collectSnapshot(projectRoot)), "", ...pulse(openChanges(projectRoot), recentlyClosed(projectRoot, { limit: 1 }))]
+      .join("\n").replace(/\x1b\[[0-9;]*m/g, "").slice(0, HOOK_MAX_CHARS);
+    console.log(agent === "cursor" ? JSON.stringify({ additional_context: text }) : text);
+    return 0;
+  }
   const view = flagBool(flags, "rules", false) ? "rules" : "prime";
   for (const line of renderView(view, collectSnapshot(projectRoot))) console.log(line);
   return 0;
 }
 
+function primeWorkspace(wsDir, flags) {
+  const ws = readWorkspace(wsDir);
+  const open = listDeliveries(wsDir).filter((d) => d.status !== "closed");
+  if (flagBool(flags, "pulse", false)) {
+    console.log(open.length === 0
+      ? "Doctrina workspace: no delivery is open — an item of work across repositories opens one with `doctrina delivery new \"<title>\" --ref <id>`."
+      : open.map((d) => `open delivery: ${d.id} — "${d.title}" (${d.projects.join(", ") || "not routed"}). Name it in your first sentence to the human; \`doctrina delivery status ${d.id}\`.`).join(" "));
+    return 0;
+  }
+  const lines = workspacePrimer(ws, wsDir, open);
+  if (flags.has("hook")) {
+    const agent = flagString(flags, "hook");
+    if (!agent || !HOOK_AGENTS.includes(agent)) {
+      console.error(c.red("error:") + ` --hook needs one of ${HOOK_AGENTS.join(", ")} (got "${agent ?? ""}")`);
+      return EXIT.USAGE;
+    }
+    const text = [...lines, "", read(path.join(wsDir, "AGENTS.md"))].join("\n").replace(/\x1b\[[0-9;]*m/g, "").slice(0, HOOK_MAX_CHARS);
+    console.log(agent === "cursor" ? JSON.stringify({ additional_context: text }) : text);
+    return 0;
+  }
+  for (const line of lines) console.log(line);
+  return 0;
+}
+
 export const help = `
-Usage: doctrina prime
+Usage: doctrina prime [--rules | --pulse | --hook claude|cursor]
 
 Print the session primer: gate digest, standing rules (accepted ADR
 titles + non-goal count), open work with task progress, and the top
@@ -51,6 +109,17 @@ 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.
+  --pulse   One line for a per-prompt agent hook: the open change(s), or
+            that a request changing behaviour opens one with \`work\`.
+  --hook <agent>
+            The primer plus the pulse, as the agent's session-start hook
+            reads it: plain text for claude, {"additional_context"} JSON
+            for cursor; cut at 9,000 characters. \`doctrina adapter add
+            claude|cursor\` installs the hooks that call these.
+
+At a workspace root (no .doctrina/, a workspace.json) it is the
+orchestrator's primer: the projects and their state, the open deliveries,
+the tools — and with --hook, the workspace's AGENTS.md after it.
 
 Read-only; always exits 0. Deeper reads: \`doctrina context\`,
 \`doctrina why <cap>\`, \`doctrina show <ref>\`.

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, fold, skillSlug } from "../lib/lexicon.js";
+import { fold, skillSlug } from "../lib/lexicon.js";
 import { artifactNameError } from "../lib/names.js";
 
 const SUBCOMMANDS = ["new", "list", "sync", "suggest"];
@@ -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"));
@@ -361,80 +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 and hand the rest to the shared slug, which folds.
-function commitSlug(subject) {
-  return skillSlug(subject.replace(/^[a-z]+(?:\([^)]*\))?!?\s*:\s*/i, ""));
-}
-
-// 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");

package/src/commands/upgrade.js

@@ -9,6 +9,7 @@ import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { today } from "../lib/dates.js";
 import { notADoctrinaProject } from "../lib/exit-codes.js";
+import { planSkillExport, applySkillExport } from "../lib/skill-export.js";
 import { collectFindings } from "../lib/templates-model.js";
 import * as templates from "./templates.js";
 import * as validate from "./validate.js";
@@ -74,6 +75,11 @@ export async function run(_positional, flags) {
     console.log(c.gray("    fix: ") + (f.remedy ? c.cyan(f.remedy) : c.gray("manual repair — no command can fix this")));
   }
 
+  // The skill exports (change 0212) follow the index: regenerated by the
+  // write, reported by the preview.
+  const exportPlan = planSkillExport(projectRoot);
+  const exportChanges = exportPlan.writes.length + exportPlan.removes.length;
+
   // 3. Index: rebuild from the tree, which also migrates the framework stamp.
   console.log("");
   console.log(c.gray("──── 2/3 index + framework stamp"));
@@ -81,6 +87,15 @@ export async function run(_positional, flags) {
     const current = idx.load(projectRoot);
     const drifted = !indexesMatch(deriveIndex(projectRoot, current), current);
     const staleStamp = (current.framework_version ?? null) !== running;
+    if (exportChanges > 0) {
+      if (writeMode) {
+        applySkillExport(projectRoot, exportPlan);
+        console.log(c.green("export ") + ` ${exportChanges} skill file${exportChanges === 1 ? "" : "s"} where the agents discover skills`);
+      } else {
+        console.log(c.yellow("would  ") + `export ${exportChanges} skill file${exportChanges === 1 ? "" : "s"} where the agents discover skills`);
+        pending += 1;
+      }
+    }
     if (!drifted && !staleStamp) {
       console.log(c.green("ok") + " index.json matches the tree and the stamp is current");
     } else if (writeMode) {

package/src/commands/verify.js

@@ -8,9 +8,10 @@ import { exists, isDir, isFile, read, write, relPath } from "../lib/fs-ops.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { today } from "../lib/dates.js";
 import { c } from "../lib/colors.js";
-import { loadSignoffs, saveSignoffs, recordSignoff, signoffState, short, SIGNOFF_REL } from "../lib/signoff.js";
+import { loadSignoffs, saveSignoffs, recordSignoff, signoffState, short, SIGNOFF_REL, declaredPaths, workingChanges } from "../lib/signoff.js";
 import { EXIT, notADoctrinaProject } from "../lib/exit-codes.js";
 import { collectReproducibility } from "../lib/reproducibility.js";
+import { verifyFingerprint, recordGreen, reusableGreen } from "../lib/verify-cache.js";
 
 // The build/verify gate `validate` is not. `validate` checks the shape of
 // the artifact tree; it never runs the project, so a repo that does not
@@ -40,7 +41,7 @@ const STARTER = {
 // 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", "clean", "force", "init", "list", "strict"], string: ["signoff"] };
+export const flags = { boolean: ["json", "clean", "force", "init", "list", "strict", "reuse", "affected"], string: ["signoff"] };
 
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
@@ -182,6 +183,22 @@ export async function run(_positional, flags) {
   }
 
   const strict = flagBool(flags, "strict", false);
+  const affected = flagBool(flags, "affected", false);
+  // The fingerprint of the code these checks are about to run on, taken
+  // BEFORE they run (change 0203): what a green run proves is the tree it
+  // started from. Null outside git — then nothing is remembered or reused.
+  const fingerprint = verifyFingerprint(projectRoot, read(configPath));
+  if (flagBool(flags, "reuse", false) && fingerprint !== null) {
+    const green = reusableGreen(projectRoot, fingerprint);
+    if (green) {
+      console.log(c.bold("doctrina verify") + c.gray(` — ${checks.length} check${checks.length === 1 ? "" : "s"} from ${CONFIG_REL}`));
+      console.log("");
+      console.log(c.green("ok") + ` reused the green run of ${green.at.replace("T", " ").slice(0, 16)} UTC — ` +
+        `the code and ${CONFIG_REL} are byte-identical to what it ran on (${green.checks.join(", ")})`);
+      console.log(c.gray("   `doctrina verify` runs the checks again"));
+      return 0;
+    }
+  }
   console.log(c.bold("doctrina verify") + c.gray(` — ${checks.length} check${checks.length === 1 ? "" : "s"} from ${CONFIG_REL}`));
   const results = [];
   for (const ch of checks) {
@@ -220,6 +237,20 @@ export async function run(_positional, flags) {
       continue;
     }
 
+    // --affected (change 0204): a check that declares the "paths" it covers
+    // runs only when the uncommitted work touches one of them. The inner
+    // loop of a change — not the close, which always runs every check. A
+    // check that declares no paths covers everything and always runs; a
+    // question git cannot answer runs the check.
+    if (affected && declaredPaths(ch).length > 0) {
+      const touched = workingChanges(projectRoot, declaredPaths(ch));
+      if (touched !== null && touched.length === 0) {
+        console.log(c.gray(`──── ${name}: `) + c.gray(`skip — the uncommitted work touches none of ${declaredPaths(ch).join(", ")}`));
+        results.push({ name, ok: true, kind: "command", skipped: true });
+        continue;
+      }
+    }
+
     const where = ch.cwd ? c.gray(` [${ch.cwd}]`) : "";
     console.log(c.gray(`──── ${name}: `) + ch.run + where);
     // Run through the shell so declared commands can use pipes, &&, env,
@@ -287,9 +318,18 @@ export async function run(_positional, flags) {
   // manual check still awaiting sign-off. Pending manual checks are otherwise
   // a non-blocking report.
   const failGate = cmdFailed.length > 0 || (strict && pending.length > 0);
-  const pendNote = pending.length > 0 ? c.gray(` (${pending.length} manual pending)`) : "";
+  const skipped = results.filter((r) => r.skipped);
+  const pendNote = (pending.length > 0 ? c.gray(` (${pending.length} manual pending)`) : "") +
+    (skipped.length > 0 ? c.gray(` (${skipped.length} skipped by --affected: ${skipped.map((r) => r.name).join(", ")})`) : "");
   if (!failGate) {
-    console.log(c.green("ok") + ` ${passed}/${results.length} checks passed${pendNote}`);
+    const ran = passed - skipped.length;
+    console.log(c.green("ok") + ` ${ran}/${results.length - skipped.length} checks passed${pendNote}`);
+    // Remembered only when EVERY check passed — a run green with a manual
+    // check still pending is a report, not something a close may stand on,
+    // and neither is a run --affected cut short.
+    if (fingerprint !== null && pending.length === 0 && skipped.length === 0) {
+      recordGreen(projectRoot, fingerprint, results.map((r) => r.name));
+    }
     return 0;
   }
   const reasons = [];
@@ -403,7 +443,7 @@ function renderReproducibility(projectRoot) {
 }
 
 export const help = `
-Usage: doctrina verify [--list] [--init] [--clean] [--strict] [--signoff "<name>=<note>"] [--force]
+Usage: doctrina verify [--list] [--init] [--clean] [--strict] [--reuse] [--affected] [--signoff "<name>=<note>"] [--force]
 
 Run the project-declared build/verify checks from ${CONFIG_REL} in order,
 streaming their output, and exit non-zero if any check fails. This is the
@@ -414,13 +454,18 @@ root, targets a sub-package in a monorepo; a "manual" check is the
 qualitative gate — judged by a human/eval, recorded as a sign-off, not run):
   {
     "checks": [
-      { "name": "typecheck", "run": "tsc --noEmit", "cwd": "packages/api" },
+      { "name": "typecheck", "run": "tsc --noEmit", "cwd": "packages/api",
+        "paths": ["packages/api"] },
       { "name": "test",      "run": "npm test" },
       { "name": "build",     "run": "npm run build" },
       { "name": "chronicle", "type": "manual", "rubric": "is the chronicle enjoyable to read?" }
     ]
   }
 
+"paths" (git pathspecs, relative to the project root) says what a check
+covers: --affected runs it only when the uncommitted work touches one, and a
+manual check's sign-off expires when one changes.
+
 A manual check passes when it has been signed off and is otherwise reported
 as "pending" — non-blocking by default, failing only under --strict (so CI
 can require the sign-off). Sign-offs are stored in ${SIGNOFF_REL}.
@@ -450,6 +495,14 @@ Flags:
              prepare/prepack; a Prisma dep with no generate on install) so
              "verify green" can't hide a clean checkout that won't build.
   --strict   Fail the gate when a manual check is still pending sign-off
+  --reuse    Skip the checks when the last fully green run covered this exact
+             code: the working tree (tracked, untracked, edits) minus
+             .doctrina/, plus ${CONFIG_REL}, are byte-identical. \`close\` runs
+             verify this way; a plain \`doctrina verify\` always runs them.
+  --affected Run a check that declares "paths" only when the uncommitted work
+             (edits against HEAD, untracked files) touches one of them —
+             the inner loop of a change. Checks with no "paths" always run;
+             \`close\` always runs every check. Never remembered by --reuse.
   --signoff "<name>=<note>"
              Record today's sign-off for a manual check, then exit
   --force    With --init, overwrite an existing config