doctrina-cli 0.15.1 → 0.17.0

package/src/lib/scan.js

@@ -1,11 +1,16 @@
 // @ts-check
-import { getHeader, getSection } from "./doc-model.js";
+import { getHeader, getSection, parseChangeTitle } from "./doc-model.js";
+import { projectName } from "./project.js";
 import path from "node:path";
 import { readdirSync } from "node:fs";
 import { isDir, isFile, read, walk } from "./fs-ops.js";
 import { today } from "./dates.js";
-import { parseFrontmatter } from "../commands/skill.js";
-import { parseOperation, parseCapabilityFromDelta } from "../commands/change.js";
+import { cliVersion, newestVersion } from "./version.js";
+import { load } from "./index-json.js";
+import { parseFrontmatter, isScaffoldValue } from "./doc-model.js";
+import { parseCapabilityFromDelta } from "./doc-model.js";
+import { parseOperation } from "./doc-model.js";
+import { git, gitLines, isRepo, GIT_STATE } from "./git.js";
 
 // Header reading lives in ONE place now (lib/doc-model.js, audit item M3).
 // These two names survive because dozens of call sites use them and the
@@ -25,6 +30,44 @@ export function parseDependsOn(text) {
   return raw.match(/[a-z][a-z0-9][a-z0-9-]*/g) ?? [];
 }
 
+/**
+ * The source globs a spec DECLARES as its own, from the optional
+ * `**Source:**` header — comma-separated, `*` inside a segment and `**`
+ * across directories (the same minimal glob the contract's Selectors use).
+ *
+ * Doctrina infers nothing about which code belongs to which capability
+ * (ADR 0027, and the same principle ADR 0023 applies to the runtime
+ * surface). Before this header the only signals were the capability name
+ * appearing as a path segment and the spec happening to cite a filename,
+ * which left 80 of this repository's 92 source files owned by nobody — so
+ * `review`, the gate that asks whether the spec kept up with the code,
+ * could not see the code it was reviewing.
+ *
+ * Returns [] when the header is absent, "n/a", or "—".
+ */
+export function parseSourceGlobs(text) {
+  const raw = specHeader(text, "Source");
+  if (!raw || /^n\/a\b/i.test(raw.trim()) || raw.trim() === "—") return [];
+  // Split on commas at brace depth ZERO: a comma inside `{a,b}` separates
+  // alternatives of ONE glob, not two globs, and splitting on it blindly
+  // shreds every grouped declaration into fragments that match nothing.
+  const out = [];
+  let cur = "";
+  let depth = 0;
+  for (const ch of raw) {
+    if (ch === "{") depth += 1;
+    else if (ch === "}") depth = Math.max(0, depth - 1);
+    if (ch === "," && depth === 0) {
+      out.push(cur);
+      cur = "";
+      continue;
+    }
+    cur += ch;
+  }
+  out.push(cur);
+  return out.map((g) => g.trim().replace(/^`|`$/g, "").trim()).filter(Boolean);
+}
+
 function dirEntries(dir) {
   if (!isDir(dir)) return [];
   return readdirSync(dir).filter((e) => !e.startsWith(".")).sort();
@@ -95,6 +138,54 @@ export function decisionEntry(text, basename, prev, date) {
   return entry;
 }
 
+/**
+ * The index entry for ONE open change, derived from its proposal. Same
+ * discipline as `decisionEntry` above and for the same reason: `deriveIndex`
+ * builds the whole list from it, and `doctrina work` / `change new` register
+ * a new change THROUGH it instead of assembling a look-alike by hand.
+ *
+ * Two constructors for one record shape is how the `lane` field (change 0042)
+ * — added to the deriver and not to the writer — turned every freshly opened
+ * change into index drift the moment it was written: `doctrina work` followed
+ * by `doctrina validate` errored on a tree nobody had touched.
+ *
+ * @param {string} proposal Text of the change's proposal.md ("" when absent).
+ * @param {string} id       The change id (its directory name).
+ * @param {object|null} prev The entry already in the index, when there is one.
+ * @param {string} date     Fallback for a proposal carrying no Date header.
+ */
+export function changeEntry(proposal, id, prev, date) {
+  const title = parseChangeTitle(proposal);
+  return {
+    id,
+    title: title ?? prev?.title ?? id,
+    path: `.doctrina/changes/${id}`,
+    status: listHeader(proposal, "Status") ?? prev?.status ?? "proposed",
+    opened: listHeader(proposal, "Date") ?? prev?.opened ?? date,
+    // The lane the change was born in (change 0042). Optional: a change
+    // opened before the field existed simply has none, and every consumer
+    // treats its absence as "unknown" rather than as a lane.
+    ...laneOf(proposal, prev),
+  };
+}
+
+
+// An archived change, as an index entry — the one constructor both the
+// rebuild and `change archive` use. They each built their own, and neither
+// carried the lane: an archived change lost the lane it was born in, so the
+// report's "Lanes" section counted the whole history as unknown (change
+// 0192), which is the question change 0042 recorded the lane to answer.
+export function archivedChangeEntry(proposal, { id, archiveName, applied, specsAffected, prev = null, title = undefined }) {
+  return {
+    id,
+    title: (title === undefined ? parseChangeTitle(proposal) : title) ?? prev?.title ?? id,
+    path: `.doctrina/changes/archive/${archiveName}`,
+    status: "applied",
+    applied,
+    specs_affected: specsAffected,
+    ...laneOf(proposal, prev),
+  };
+}
 
 // Regenerate the index object from the artifacts on disk. The files are
 // the source of truth; fields with no on-disk source (project name,
@@ -106,7 +197,7 @@ export function deriveIndex(projectRoot, current) {
 
   const out = {
     $schema_version: current?.$schema_version ?? "0.1.0",
-    project: current?.project ?? path.basename(projectRoot),
+    project: projectName(projectRoot, current),
     framework_version: current?.framework_version ?? "0.0.0",
     last_updated: current?.last_updated ?? date,
     // Project settings, carried over verbatim. `deriveIndex` rebuilds the
@@ -166,6 +257,10 @@ export function deriveIndex(projectRoot, current) {
     // dependents of a touched capability.
     const depends = specHeader(text, "Depends on") !== null ? parseDependsOn(text) : prev?.depends_on;
     if (depends && depends.length) entry.depends_on = depends;
+    // Source: the code this capability owns (change 0077). Declared, never
+    // inferred — the same discipline ADR 0023 applies to the runtime surface.
+    const source = specHeader(text, "Source") !== null ? parseSourceGlobs(text) : prev?.source;
+    if (source && source.length) entry.source = source;
     out.artifacts.specs.push(entry);
   }
 
@@ -187,14 +282,7 @@ export function deriveIndex(projectRoot, current) {
     const prev = (cur.changes ?? []).find((c) => c.id === id);
     const proposalPath = path.join(changesDir, id, "proposal.md");
     const proposal = isFile(proposalPath) ? read(proposalPath) : "";
-    const titleMatch = proposal.match(/^#\s+Change\s+\S+\s*[—-]\s*(.+)$/m);
-    out.artifacts.changes.push({
-      id,
-      title: titleMatch ? titleMatch[1].trim() : prev?.title ?? id,
-      path: `.doctrina/changes/${id}`,
-      status: listHeader(proposal, "Status") ?? prev?.status ?? "proposed",
-      opened: listHeader(proposal, "Date") ?? prev?.opened ?? date,
-    });
+    out.artifacts.changes.push(changeEntry(proposal, id, prev, date));
   }
 
   // Archived changes — folder name carries the applied date and id.
@@ -205,7 +293,7 @@ export function deriveIndex(projectRoot, current) {
     const prev = (cur.changes_archive ?? []).find((c) => c.path?.endsWith(name));
     const proposalPath = path.join(archiveDir, name, "proposal.md");
     const proposal = isFile(proposalPath) ? read(proposalPath) : "";
-    const titleMatch = proposal.match(/^#\s+Change\s+\S+\s*[—-]\s*(.+)$/m);
+    const title = parseChangeTitle(proposal);
     const specsAffected = [];
     for (const deltaPath of walk(path.join(archiveDir, name, "specs"))) {
       if (!deltaPath.endsWith("delta.md")) continue;
@@ -215,14 +303,9 @@ export function deriveIndex(projectRoot, current) {
         specsAffected.push({ capability, operation: parseOperation(text) ?? "MODIFIED" });
       }
     }
-    out.artifacts.changes_archive.push({
-      id: m[2],
-      title: titleMatch ? titleMatch[1].trim() : prev?.title ?? m[2],
-      path: `.doctrina/changes/archive/${name}`,
-      status: "applied",
-      applied: m[1],
-      specs_affected: specsAffected,
-    });
+    out.artifacts.changes_archive.push(archivedChangeEntry(proposal, {
+      id: m[2], archiveName: name, applied: m[1], specsAffected, prev, title,
+    }));
   }
 
   // Contracts — the integration/runtime surface (ports, env, interfaces)
@@ -241,18 +324,26 @@ export function deriveIndex(projectRoot, current) {
     });
   }
 
-  // Skills — frontmatter description wins.
+  // Skills — a WRITTEN frontmatter description wins. The rebuild is the one
+  // reconciliation (change 0177 retired `skill sync`, which did a subset of
+  // this), so it carries sync's rule: a description still in the scaffold's
+  // `<...>` form never overwrites one somebody wrote (change 0111), and the
+  // entry's date moves when its description does.
   const skillsDir = path.join(dot, "skills");
   for (const f of walk(skillsDir)) {
     if (!f.endsWith(".md")) continue;
     const id = path.basename(f, ".md");
     const prev = (cur.skills ?? []).find((s) => s.id === id);
+    const written = parseFrontmatter(read(f), "description");
+    const kept = prev?.description && !isScaffoldValue(prev.description) ? prev.description : null;
+    const description = written && !isScaffoldValue(written)
+      ? written
+      : kept ?? written ?? "<edit me — one-sentence summary>";
     out.artifacts.skills.push({
       id,
       path: `.doctrina/skills/${id}.md`,
-      description: parseFrontmatter(read(f), "description")
-        ?? prev?.description ?? "<edit me — one-sentence summary>",
-      last_updated: prev?.last_updated ?? date,
+      description,
+      last_updated: prev && prev.description === description ? prev.last_updated ?? date : date,
     });
   }
 
@@ -296,3 +387,215 @@ export function indexesMatch(a, b) {
   };
   return stableStringify(normalize(a)) === stableStringify(normalize(b));
 }
+
+// The lane recorded in a proposal header (change 0042), as an index field —
+// or nothing at all. A change opened before the field existed, or one whose
+// header is still the empty scaffold, has no lane, and "unknown" is the
+// honest answer rather than a default that would poison the mix.
+function laneOf(proposal, prev) {
+  const raw = (listHeader(proposal, "Lane") ?? "").trim();
+  if (!raw) return prev?.lane ? { lane: prev.lane } : {};
+  return { lane: raw };
+}
+
+/**
+ * Is the on-disk index still what the tree derives to, and if not, how does
+ * it differ?
+ *
+ * `index rebuild` renders this (and writes the derived index when asked);
+ * `doctor` reports it as one row. Before this it was the command's private
+ * business, so `doctor` answered "has the index drifted?" by spawning the
+ * CLI again and reading an exit code (audit finding F4).
+ *
+ * The framework stamp is migrated to the running CLI here rather than in the
+ * caller: deriveIndex carries the old value over so `next` does not nag on a
+ * version-only difference, and overriding it lets a stale stamp COUNT as
+ * drift, so `index rebuild` both reports and fixes it instead of
+ * short-circuiting on "nothing to do".
+ *
+ * @param {string} projectRoot
+ * @returns {{ok: boolean, drift: string[], derived: any, current: any, unreadable: string|null}}
+ */
+export function collectIndexDrift(projectRoot) {
+  let current = null;
+  let unreadable = null;
+  try {
+    current = load(projectRoot);
+  } catch (err) {
+    unreadable = err.message;
+  }
+  const derived = deriveIndex(projectRoot, current);
+  // A stamp ahead of this CLI is not drift (change 0116): the tree is
+  // managed by a newer release, and `--check` in CI must not go red because
+  // one teammate's CLI is older than the one that last wrote the index.
+  derived.framework_version = newestVersion(current?.framework_version, cliVersion());
+  if (indexesMatch(derived, current)) {
+    return { ok: true, drift: [], derived, current, unreadable };
+  }
+  return { ok: false, drift: describeDrift(current, derived), derived, current, unreadable };
+}
+
+// Human-readable category-level drift between the on-disk index and the
+// derived one: added / removed / changed entry ids.
+function describeDrift(current, derived) {
+  const lines = [];
+  if (!current) return ["index.json missing or unreadable"];
+  if ((current.framework_version ?? null) !== (derived.framework_version ?? null)) {
+    lines.push(`framework_version: ${current.framework_version ?? "unset"} -> ${derived.framework_version}`);
+  }
+  const categories = ["specs", "decisions", "changes", "changes_archive", "skills"];
+  for (const cat of categories) {
+    const cur = new Map((current.artifacts?.[cat] ?? []).map((e) => [e.id, e]));
+    const der = new Map((derived.artifacts?.[cat] ?? []).map((e) => [e.id, e]));
+    for (const id of der.keys()) {
+      if (!cur.has(id)) lines.push(`${cat}: "${id}" on disk but not in index`);
+      else if (stableStringify(cur.get(id)) !== stableStringify(der.get(id))) {
+        lines.push(`${cat}: "${id}" metadata differs from the files`);
+      }
+    }
+    for (const id of cur.keys()) {
+      if (!der.has(id)) lines.push(`${cat}: "${id}" in index but not on disk`);
+    }
+  }
+  if (stableStringify(current.artifacts?.product ?? null) !== stableStringify(derived.artifacts.product)) {
+    lines.push("product: metadata differs");
+  }
+  if (lines.length === 0) lines.push("structural difference (key order or missing category)");
+  return lines;
+}
+
+/**
+ * The capabilities that actually have a spec on disk.
+ *
+ * The one list every command checks a named capability against. `coverage
+ * --only` refuses a name that is not in it (change 0090); `context <cap>`
+ * refuses the same way, because a scope filter that matches nothing is the
+ * same defect wherever it appears. Kept here rather than in either command
+ * so the two cannot disagree about which capabilities exist.
+ *
+ * @param {string} projectRoot
+ * @returns {string[]} directory names, in readdir order
+ */
+export function knownCapabilities(projectRoot) {
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  if (!isDir(specsDir)) return [];
+  return readdirSync(specsDir).filter((e) => isFile(path.join(specsDir, e, "spec.md")));
+}
+
+/**
+ * Which capabilities declare a dependency on any of `caps`.
+ *
+ * The `**Depends on:**` header is the tree's only machine-readable statement
+ * that one capability builds on another, and two commands ask the same
+ * question of it: `review` notes a dependent whose ground moved, and `close`
+ * reports their coverage alongside the change's own. One definition, so they
+ * cannot disagree about who depends on what.
+ *
+ * @param {string} projectRoot
+ * @param {Iterable<string>} caps
+ * @returns {{capability: string, dependsOn: string[]}[]} sorted by capability
+ */
+export function dependentsOf(projectRoot, caps) {
+  const wanted = new Set(caps);
+  const specsDir = path.join(projectRoot, ".doctrina", "specs");
+  if (wanted.size === 0 || !isDir(specsDir)) return [];
+  const out = [];
+  for (const cap of readdirSync(specsDir).sort()) {
+    if (wanted.has(cap)) continue;
+    const specPath = path.join(specsDir, cap, "spec.md");
+    if (!isFile(specPath)) continue;
+    const deps = parseDependsOn(read(specPath)).filter((d) => wanted.has(d));
+    if (deps.length > 0) out.push({ capability: cap, dependsOn: deps });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------- staged
+
+/**
+ * The same question as `collectIndexDrift`, asked of the COMMIT instead of
+ * the disk.
+ *
+ * `index.json` is derived from the whole tree, so it cannot describe a
+ * subset of it. Stage some of `.doctrina/` and the index that rides along
+ * names artifacts the commit does not carry — and every gate that would
+ * catch it reads the working tree, where those artifacts are still present.
+ * Four commits of this repository shipped that way, each green locally and
+ * each red on checkout: `index.json references missing artifact`.
+ *
+ * Read with git plumbing, never from disk: `:<path>` is the staged blob and
+ * `ls-files --cached` is the file list the commit will have.
+ *
+ * @param {string} projectRoot
+ * @returns {{ok: boolean, applicable: boolean, missing: string[], unindexed: string[], reason: string|null}}
+ */
+export function collectStagedIndexDrift(projectRoot) {
+  const nothing = { ok: true, applicable: false, missing: [], unindexed: [], reason: null };
+  if (!isRepo(projectRoot)) return { ...nothing, reason: "not a git repository" };
+
+  const blob = git(projectRoot, ["show", ":.doctrina/index.json"]);
+  if (blob.state !== GIT_STATE.OK || !blob.stdout.trim()) {
+    // Not staged at all — this commit does not carry an index, so it cannot
+    // carry one that disagrees with itself.
+    return { ...nothing, reason: "no staged .doctrina/index.json" };
+  }
+
+  let staged;
+  try {
+    staged = JSON.parse(blob.stdout);
+  } catch {
+    return { ok: false, applicable: true, missing: [], unindexed: [],
+      reason: "the staged .doctrina/index.json is not valid JSON" };
+  }
+
+  const files = new Set(gitLines(projectRoot, ["ls-files", "--cached", "--", ".doctrina"]));
+  // An entry's path is a file for specs, ADRs, skills and contracts, and a
+  // DIRECTORY for changes — a directory is in the commit when any file under
+  // it is.
+  const inCommit = (p) => files.has(p) || [...files].some((f) => f.startsWith(`${p}/`));
+
+  const artifacts = staged.artifacts ?? {};
+  const missing = [];
+  for (const [kind, entries] of Object.entries(artifacts)) {
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      const p = String(entry?.path ?? "");
+      if (p && !inCommit(p)) missing.push(`${kind}: ${p}`);
+    }
+  }
+
+  // The mirror case: an artifact staged into the commit that the staged index
+  // never heard of. Same shapes `index rebuild` derives entries from.
+  const indexed = new Set();
+  for (const entries of Object.values(artifacts)) {
+    if (Array.isArray(entries)) for (const e of entries) indexed.add(String(e?.path ?? ""));
+  }
+  const unindexed = [];
+  for (const f of [...files].sort()) {
+    const owner = artifactPathOf(f);
+    if (owner && !indexed.has(owner)) unindexed.push(owner);
+  }
+
+  const unique = [...new Set(unindexed)];
+  return {
+    ok: missing.length === 0 && unique.length === 0,
+    applicable: true,
+    missing,
+    unindexed: unique,
+    reason: null,
+  };
+}
+
+// The index entry a staged file belongs to, or null when the file is not an
+// artifact (templates, config.json, product.md, the index itself).
+function artifactPathOf(file) {
+  let m = /^\.doctrina\/specs\/[^/]+\/spec\.md$/.exec(file);
+  if (m) return file;
+  m = /^\.doctrina\/(?:decisions|skills|contracts)\/[^/]+\.md$/.exec(file);
+  if (m) return file;
+  m = /^(\.doctrina\/changes\/archive\/[^/]+)\/proposal\.md$/.exec(file);
+  if (m) return m[1];
+  m = /^(\.doctrina\/changes\/(?!archive\/)[^/]+)\/proposal\.md$/.exec(file);
+  if (m) return m[1];
+  return null;
+}

package/src/lib/signoff.js

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