create-cmp-cli 0.13.0 → 0.14.1

package/packages/harness/src/lib/evidence-badge.mjs

@@ -0,0 +1,158 @@
+// The README's evidence badge — the evidence ladder, rendered where a human
+// actually looks (roadmap §10 item 2: "render the rung in the console and
+// README badge").
+//
+// The console already shows the rung (rail foot, Evidence section, receipt
+// timeline). The README is the surface a human meets FIRST, and the one that
+// travels — into a GitHub repo page, a PR, a screenshot in a deck. That makes
+// it the surface where an overclaim does the most damage, so the badge obeys
+// one rule above all others:
+//
+//   **The badge is a statement about a specific commit, never about "now".**
+//
+// A badge that says "L2 device" says nothing about whether the code has moved
+// since. So it never renders a bare rung: it renders the rung AND the commit
+// it was attested against AND the date. That sentence stays true forever — a
+// reader can see at a glance whether the sha still matches what they are
+// looking at. Everything else follows from the same rule: no receipt says so,
+// a FAIL says so, and a --fast run (which the ladder deliberately grants no
+// rung) says so rather than borrowing the last good one.
+//
+// Written by the lane AFTER the receipt (it is an output derived from the
+// receipt, never a gate), and committed alongside it.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const README_REL_PATH = "README.md";
+export const BADGE_SECTION_ID = "evidence";
+
+const MARKER_RE = new RegExp(
+  `<!-- cmp:generated ${BADGE_SECTION_ID} -->\\n([\\s\\S]*?)<!-- /cmp:generated -->`
+);
+
+/** Shields.io colours, one per rung — the ladder read at a glance. */
+const RUNG_COLOR = {
+  L0: "9E9E9E", // scaffold — grey: a green build, nothing proven about behavior
+  L1: "42A5F5", // desktop — blue
+  L2: "26A69A", // device — teal
+  L3: "43A047", // release — green: the strongest rung this harness can attest
+};
+
+/** shields.io escaping: `-` → `--`, `_` → `__`, space → `_`. */
+function shieldEscape(s) {
+  return String(s).replace(/-/g, "--").replace(/_/g, "__").replace(/ /g, "_");
+}
+
+/**
+ * The badge body for a receipt — Markdown, no trailing newline handling (the
+ * caller frames it). Pure: every degraded state has its own honest rendering
+ * and NONE of them fall back to a rung.
+ *
+ * @param {object|null} receipt parsed qa/evidence/latest.json, or null
+ * @returns {string} Markdown
+ */
+export function renderEvidenceBadge(receipt) {
+  const link = "https://github.com/kvdm-co-pilot/create-cmp";
+  const badge = (label, message, color, title) =>
+    `[![${title}](https://img.shields.io/badge/${shieldEscape(label)}-${shieldEscape(message)}-${color})](${link})`;
+
+  if (!receipt || typeof receipt !== "object") {
+    return `${badge("evidence", "none yet", "9E9E9E", "No evidence receipt")} — no verify receipt yet. Run \`node qa/verify.mjs\`.`;
+  }
+
+  const verdict = typeof receipt.verdict === "string" ? receipt.verdict : "?";
+  const mode = receipt.mode === "fast" ? "fast" : "full";
+  const sha = typeof receipt.commit?.sha === "string" ? receipt.commit.sha.slice(0, 7) : null;
+  const dirty = Array.isArray(receipt.commit?.dirty) ? receipt.commit.dirty.length : 0;
+  const when = typeof receipt.generatedAt === "string" ? receipt.generatedAt.slice(0, 10) : null;
+
+  // Provenance is not decoration — it is what keeps the sentence true later.
+  const at = sha ? ` at \`${sha}\`` : "";
+  const on = when ? ` on ${when}` : "";
+  const uncommitted =
+    dirty > 0
+      ? ` The tree had ${dirty} uncommitted file${dirty === 1 ? "" : "s"} at attestation, so this describes that run, not that commit.`
+      : "";
+
+  if (verdict !== "PASS") {
+    return `${badge("evidence", `lane ${verdict}`, "E53935", `Verify lane ${verdict}`)} — the last lane run${at}${on} did not pass. No rung is earned by a failed lane.${uncommitted}`;
+  }
+
+  if (mode === "fast") {
+    // The inner loop is a signal, never evidence. Borrowing the previous
+    // full run's rung here is exactly the lie the ladder exists to prevent.
+    return `${badge("evidence", "fast run, no rung", "9E9E9E", "Fast run — no evidence rung")} — the last run${at}${on} was \`--fast\`: the device and release tiers were skipped, so it earns no rung.${uncommitted} Run \`node qa/verify.mjs\` for evidence.`;
+  }
+
+  const level = receipt.evidenceLevel;
+  if (!level || typeof level.rung !== "string" || typeof level.name !== "string") {
+    return `${badge("evidence", `PASS, rung unrecorded`, "9E9E9E", "Lane PASS, no rung recorded")} — the lane passed${at}${on} but the receipt records no evidence rung.`;
+  }
+
+  const color = RUNG_COLOR[level.rung] || "9E9E9E";
+  const satisfied = Array.isArray(level.satisfiedBy) && level.satisfiedBy.length
+    ? ` Earned by: ${level.satisfiedBy.map((s) => `\`${s}\``).join(", ")}.`
+    : "";
+  return (
+    `${badge("evidence", `${level.rung} ${level.name}`, color, `Evidence ${level.rung} — ${level.name}`)}` +
+    ` — the verify lane passed${at}${on} at rung **${level.rung} · ${level.name}**.` +
+    `${satisfied}${uncommitted}` +
+    ` The rung describes that run; it says nothing about changes made since.`
+  );
+}
+
+/**
+ * Read the project's receipt and rewrite README.md's `cmp:generated evidence`
+ * block from it. Never creates the marker — a project that removed the block
+ * has opted out, and that is honoured silently.
+ *
+ * NOTE the asymmetry with renderEvidenceBadge above: the RENDERER is total —
+ * every receipt, including a `--fast` one, has an honest rendering. The WRITER
+ * is selective: a fast receipt is not written to the README at all. Two
+ * reasons, and the second is the load-bearing one:
+ *   1. The badge reports EVIDENCE. A fast run produces none, so it has nothing
+ *      to say — and overwriting a true statement about a real full-lane run
+ *      with "no rung" loses information rather than adding honesty.
+ *   2. `qa/watch.mjs` runs the fast lane on every save. A writer that fired
+ *      there would rewrite README.md on every keystroke-to-save cycle, putting
+ *      a permanently-dirty file in the inner loop. A recorder must not disturb
+ *      what it records.
+ * The badge therefore always describes the last run that could BEAR evidence,
+ * and says so by naming that run's commit and date.
+ *
+ * @param {string} root project root
+ * @returns {{changed: boolean, reason?: string}}
+ */
+export function updateReadmeBadge(root) {
+  const readmePath = path.join(root, README_REL_PATH);
+  let readme;
+  try {
+    readme = fs.readFileSync(readmePath, "utf8");
+  } catch {
+    return { changed: false, reason: `${README_REL_PATH} not found` };
+  }
+  if (!MARKER_RE.test(readme)) {
+    return { changed: false, reason: `${README_REL_PATH} has no cmp:generated ${BADGE_SECTION_ID} block` };
+  }
+
+  let receipt = null;
+  try {
+    receipt = JSON.parse(fs.readFileSync(path.join(root, "qa", "evidence", "latest.json"), "utf8"));
+  } catch {
+    receipt = null; // no receipt / unreadable → the "none yet" rendering, never a guess
+  }
+
+  if (receipt && receipt.mode === "fast") {
+    return { changed: false, reason: "fast run — the inner loop bears no evidence, so the badge is left as it stands" };
+  }
+
+  const body = `${renderEvidenceBadge(receipt)}\n`;
+  const next = readme.replace(
+    MARKER_RE,
+    () => `<!-- cmp:generated ${BADGE_SECTION_ID} -->\n${body}<!-- /cmp:generated -->`
+  );
+  if (next === readme) return { changed: false };
+  fs.writeFileSync(readmePath, next);
+  return { changed: true };
+}

package/packages/harness/src/lib/evidence-level.mjs

@@ -0,0 +1,117 @@
+// The evidence ladder — the receipt's COARSE grade, derived, never declared.
+//
+// Receipts already grade themselves in fine print ("PASS (desktop-only)",
+// "PASS (on-device: e2eSmoke+androidChecks)"). This module names the rungs so
+// every surface that shows a receipt can say the same thing in one word:
+//
+//   L0 "scaffold" — the scaffold profile's checks passed (stamp-time green
+//                   build: build + unit tests + the pure-Node gates).
+//   L1 "desktop"  — full static + JVM evidence: everything L0 proves PLUS
+//                   conformance, golden trees, a11y, and the release COMPILE
+//                   (releaseBuild) — a green lane with no on-device step run.
+//   L2 "device"   — L1 plus at least one on-device EXECUTION step PASSed
+//                   (e2eSmoke, androidChecks, or the live tokenDrift tier).
+//   L3 "release"  — L2 plus releaseSmoke PASSed (the release APK installed
+//                   and driven on a device).
+//
+// HONESTY RULES — the rung must be honest to a fault, it is the vocabulary
+// evidence is sold in:
+//   - A rung is DERIVED from which steps actually ran and PASSED. It is never
+//     declared: the `profile` argument is deliberately NOT part of the
+//     derivation — a requested profile can never buy a rung its steps did not
+//     earn (it is accepted so callers state what was asked for vs. earned).
+//   - A SKIP never upgrades. A SKIPped device step does not count toward L2;
+//     a SKIPped releaseSmoke (e.g. unsigned keystore) is NOT L3. The label
+//     can never overclaim.
+//   - A FAILED lane has no rung: the rung is only computed for a PASS
+//     verdict; the receipt of a FAIL records evidenceLevel null.
+//   - A FAST-MODE lane has no rung either — not even L0. `verify --fast` is
+//     the inner loop, a signal rather than evidence, so a fast receipt must
+//     never be silently reused as if it were a full-lane result: pass the
+//     run's mode and "fast" derives null, always.
+//   - The rung is COARSE by design. The per-step list (and the existing
+//     strength string) stays the fine print alongside it — steps that may
+//     SKIP for honest configuration absence (approvals unreviewed, no
+//     exported schemas) are visible there; only the always-run steps gate
+//     the desktop rungs, and only executed PASSes gate the device rungs.
+
+/** The scaffold profile's step set (verify.mjs stepsForProfile.scaffold). */
+const SCAFFOLD_CORE = [
+  "specCoverage",
+  "approvals",
+  "componentStories",
+  "reachability",
+  "archDoc",
+  "schemaHistory",
+  "build",
+  "unitTests",
+];
+
+/** Steps every PASS must carry to claim even L0 — they run in every profile and never SKIP. */
+const L0_REQUIRED = ["build", "unitTests"];
+
+/**
+ * The steps that distinguish full desktop evidence (L1) from the scaffold
+ * checks. None of these can SKIP — they PASS or FAIL — so "PASSed" is exactly
+ * "ran green".
+ */
+const L1_REQUIRED = ["releaseBuild", "conformance", "goldenTrees", "a11y"];
+
+/** On-device EXECUTION steps — the only steps that can earn L2. */
+const DEVICE_EXECUTION = ["e2eSmoke", "tokenDrift", "androidChecks"];
+
+/** The one step that can lift L2 to L3. */
+const RELEASE_EXECUTION = "releaseSmoke";
+
+const RUNG_NAMES = { L0: "scaffold", L1: "desktop", L2: "device", L3: "release" };
+
+/**
+ * Derive the receipt's evidence rung from the lane's step results.
+ *
+ * @param {Array<{name: string, verdict: string}>} stepResults the lane's steps
+ *   as recorded on the receipt (verdict PASS | FAIL | SKIP per step)
+ * @param {string} [profile] the profile that was REQUESTED — recorded context
+ *   only, never part of the derivation (see honesty rules above)
+ * @param {{mode?: string}} [opts] the run's mode ("full" | "fast"). "fast"
+ *   derives null unconditionally — the inner loop earns no rung (see honesty
+ *   rules above). Absent/other values mean full.
+ * @returns {{rung: "L0"|"L1"|"L2"|"L3", name: string, satisfiedBy: string[]}|null}
+ *   null when any step FAILed (a failed lane has no rung), when the run was
+ *   fast-mode (the inner loop is never evidence), or when even the L0 floor
+ *   was not earned. `satisfiedBy` lists the PASSed steps the rung counts as
+ *   its evidence, in lane order.
+ */
+export function evidenceLevel(stepResults, profile, { mode } = {}) { // eslint-disable-line no-unused-vars
+  if (mode === "fast") return null; // the inner loop derives no rung — ever
+  const steps = Array.isArray(stepResults) ? stepResults.filter((s) => s && typeof s.name === "string") : [];
+  if (steps.some((s) => s.verdict === "FAIL")) return null; // a failed lane has no rung
+  const passed = new Set(steps.filter((s) => s.verdict === "PASS").map((s) => s.name));
+
+  if (!L0_REQUIRED.every((name) => passed.has(name))) return null; // not even a stamp-time green build
+
+  const inLaneOrder = (names) => steps.filter((s) => names.has(s.name) && passed.has(s.name)).map((s) => s.name);
+
+  let rung = "L0";
+  const counted = new Set(SCAFFOLD_CORE);
+
+  if (L1_REQUIRED.every((name) => passed.has(name))) {
+    rung = "L1";
+    for (const name of L1_REQUIRED) counted.add(name);
+
+    // Only an EXECUTED (PASSed) device step lifts to L2 — a SKIP never does.
+    const deviceRan = DEVICE_EXECUTION.some((name) => passed.has(name));
+    if (deviceRan) {
+      rung = "L2";
+      for (const name of DEVICE_EXECUTION) counted.add(name);
+
+      // Only a PASSed releaseSmoke lifts to L3 — a SKIP (unsigned keystore,
+      // no device) never does.
+      if (passed.has(RELEASE_EXECUTION)) {
+        rung = "L3";
+        counted.add(RELEASE_EXECUTION);
+      }
+    }
+  }
+
+  return { rung, name: RUNG_NAMES[rung], satisfiedBy: inLaneOrder(counted) };
+}

package/packages/harness/src/lib/feature-brief.mjs

@@ -0,0 +1,324 @@
+// feature-brief.mjs — feature briefs and DERIVED doneness.
+//
+// A feature brief is `docs/features/<name>.md`: the why of a feature — the
+// decisions with their rationale ("the day boundary is a configurable
+// dayStartHour, default 04:00 — not midnight, because…"), the research, the
+// rejected options. Location is the governance opt-in: every doc in
+// docs/features/ is a governed `feature-brief:<name>` artifact, hashed and
+// signed like anything else, approved BEFORE the feature is built. (Harness
+// design standards stay in docs/proposals/ — different directory, different
+// meaning.) `<name>` matches the feature's spec: docs/features/meal.md pairs
+// with specs/meal.spec.md.
+//
+// The brief carries at most ONE machine-read block, and it declares — it never
+// gates:
+//
+//   ```json cmp:feature
+//   { "touches": ["components", "design-system"], "screens": true }
+//   ```
+//
+// `touches` is the declared blast radius: the governed artifacts this feature
+// expects to invalidate. The artifact hashes already enforce; declaring lets
+// the console tell "re-approval, as planned" apart from undeclared blast.
+// `screens` declares a UI surface: this feature will have its own screens, so
+// the walk holds a design gate (feature-design:<name> — signed on RENDERED
+// output) between the brief and the behavior contract, BEFORE any screen file
+// exists. Like touches it declares, never gates: once presentation/<name>/
+// screen files exist on disk, the gate derives from them regardless.
+//
+// DONENESS IS DERIVED, NEVER CLAIMED. This file's earlier incarnation
+// (intent-checks.mjs) let the agent assert delivery over its own grep checks —
+// a weaker parallel truth beside the strong one the harness already maintains:
+// clause ↔ citing test ↔ lane gate ↔ receipt. That mechanism is gone. A
+// feature is provably done when, mechanically:
+//
+//   1. its spec has live clauses, and every one is cited by a test
+//      (spec-coverage.mjs — the same scan the lane's specCoverage gate runs),
+//   2. the latest receipt's verdict is PASS, and
+//   3. the receipt's inputs.hash matches a recompute of the tree RIGHT NOW —
+//      evidence must attest execution of *this* code, not some earlier tree.
+//
+// No new lane step needed: specCoverage already fails uncovered clauses and
+// the test steps already fail broken promises. What remains for humans is
+// judgment, not verification: approving the brief (before code) and accepting
+// the feature (after proof) — acceptFeature in approvals.mjs refuses until
+// provenDone is true.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { computeInputsHash } from "./inputs-hash.mjs";
+import { CLAUSE_LINE_RE, scanCitations } from "./spec-coverage.mjs";
+
+export const FEATURES_DIR_REL = "docs/features";
+
+/** The declaration block's info string — ```json cmp:feature */
+const FEATURE_FENCE_RE = /```json\s+cmp:feature\s*\n([\s\S]*?)\n```/;
+
+// The EDGE-CASE AUDIT (CHANGE-FLOW-DESIGN.md §1): the adversarial pass a brief
+// must survive before anyone is asked to sign the design. It exists because of a
+// measured failure — on 2026-07-27 the meal-plan brief was signed, designed,
+// signed again, and only THEN audited; the audit found nine gaps (three of them
+// defects in already-signed clauses), which cost three signing rounds on one
+// feature. The audit was never optional; it was simply unplaced, so it happened
+// last. This gives it a place: BEFORE the gate, not after it.
+//
+// The section is a plain `## Edge cases` heading followed by list items — one
+// case per line, each ending in how it was resolved (a decision, a clause, or an
+// explicit "out of scope"). The gate can only count entries; it cannot judge
+// them. That is deliberate and enough: what it buys is that the adversarial pass
+// HAPPENS while the artifacts are still unsigned, so whatever it finds lands in
+// the same signing round instead of reopening one.
+const EDGE_CASES_HEADING_RE = /^##\s+Edge cases\b[^\n]*\n([\s\S]*)$/im;
+const LIST_ITEM_RE = /^\s*(?:[-*]|\d+\.)\s+\S/gm;
+
+/**
+ * How many edge cases a brief records — 0 when the section is absent or empty.
+ *
+ * The body is taken to the NEXT `## ` heading by splitting, not by a lookahead:
+ * with the /m flag `$` means end-of-LINE, so a lazy `[\s\S]*?(?=\n##\s|$)`
+ * terminates on the first newline and silently captures nothing. Splitting says
+ * what it means and cannot regress that way.
+ *
+ * @param {string} markdown
+ * @returns {number}
+ */
+export function countEdgeCases(markdown) {
+  if (typeof markdown !== "string") return 0;
+  const m = markdown.match(EDGE_CASES_HEADING_RE);
+  if (!m) return 0;
+  const body = m[1].split(/\n##\s/)[0];
+  return (body.match(LIST_ITEM_RE) || []).length;
+}
+
+/**
+ * The brief with its cmp:feature declaration block removed — the basis the
+ * feature-brief approval hash is computed over (approvals.mjs). The human signs
+ * the brief's REASONING; the block is machine-read declaration whose claims the
+ * harness independently enforces (artifact hashes enforce `touches`; disk
+ * presence enforces the design gate), so editing it must never invalidate a
+ * signature — the same stance as `architecture`'s cmp:generated stripping.
+ * @param {string} markdown
+ * @returns {string}
+ */
+export function stripFeatureBlock(markdown) {
+  if (typeof markdown !== "string") return "";
+  // Consume the blank space around the block and leave one paragraph break, and
+  // normalize the trailing edge — so adding, editing, or removing the block
+  // (typically the doc's last element) yields the same basis as never having
+  // one. The fence grammar itself stays FEATURE_FENCE_RE — one definition,
+  // shared with parseFeatureBlock.
+  const stripped = markdown.replace(new RegExp(String.raw`\s*` + FEATURE_FENCE_RE.source + String.raw`\s*`), "\n\n");
+  return stripped.trim() === "" ? "" : stripped.replace(/\s+$/, "\n");
+}
+
+/**
+ * Every feature brief — docs/features/*.md, sorted (code-unit sort: artifact
+ * ids derive from this list and must read identically on every machine).
+ * @param {string} root
+ * @returns {Array<{name: string, rel: string}>}
+ */
+export function listFeatureBriefs(root) {
+  const dir = path.join(root, FEATURES_DIR_REL);
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  return names
+    .filter((f) => f.endsWith(".md") && f !== "README.md")
+    .sort()
+    .map((f) => ({ name: f.slice(0, -".md".length), rel: `${FEATURES_DIR_REL}/${f}` }));
+}
+
+/**
+ * The brief's prose, split on `## ` headings — the SUBSTANCE the human signs.
+ * The console renders these on the feature card (the decisions section inline,
+ * the rest collapsible): an approval moment must show what is being approved,
+ * never just a status shell. Fenced code blocks are kept verbatim inside
+ * their section (the cmp:feature block included — it is part of the signed
+ * bytes and the reader may want to see it).
+ * @param {string} markdown
+ * @returns {Array<{heading: string, body: string}>}
+ */
+export function briefSections(markdown) {
+  if (typeof markdown !== "string" || markdown.trim() === "") return [];
+  const out = [];
+  let current = null;
+  let inFence = false;
+  for (const line of markdown.split("\n")) {
+    if (/^```/.test(line.trim())) inFence = !inFence;
+    const m = !inFence && line.match(/^##\s+(.+)$/);
+    if (m) {
+      if (current) out.push({ heading: current.heading, body: current.lines.join("\n").trim() });
+      current = { heading: m[1].trim(), lines: [] };
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+  if (current) out.push({ heading: current.heading, body: current.lines.join("\n").trim() });
+  return out;
+}
+
+/**
+ * A brief's declarations: blast radius (`touches`), UI surface (`screens`),
+ * and the reachability exemption (`unrouted` — FI-7's escape hatch: a screen
+ * intentionally not wired into the navigation graph yet). A missing block, or
+ * one without a field, declares nothing — legal and common. A block that IS
+ * present but malformed is surfaced as `error`: a doc that tried to declare
+ * and failed should say so, not read as "declares nothing".
+ * @param {string} markdown
+ * @returns {{touches: string[], screens: boolean, unrouted: boolean, error: (string|null)}}
+ */
+export function parseFeatureBlock(markdown) {
+  const m = typeof markdown === "string" ? markdown.match(FEATURE_FENCE_RE) : null;
+  if (!m) return { touches: [], screens: false, unrouted: false, error: null };
+  let parsed;
+  try {
+    parsed = JSON.parse(m[1]);
+  } catch (err) {
+    return { touches: [], screens: false, unrouted: false, error: `cmp:feature block is not valid JSON — ${err.message}` };
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { touches: [], screens: false, unrouted: false, error: "cmp:feature must be a JSON object" };
+  }
+  const touches = Array.isArray(parsed.touches)
+    ? parsed.touches.filter((t) => typeof t === "string" && t.trim() !== "")
+    : [];
+  return { touches, screens: parsed.screens === true, unrouted: parsed.unrouted === true, error: null };
+}
+
+/**
+ * Parse one spec file's clauses in document order.
+ * @param {string} root
+ * @param {string} specRel e.g. "specs/meal.spec.md"
+ * @returns {Array<{id: string, withdrawn: boolean}>}
+ */
+function clausesOfSpec(root, specRel) {
+  let text;
+  try {
+    text = fs.readFileSync(path.join(root, specRel), "utf8");
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of text.split("\n")) {
+    const m = line.match(CLAUSE_LINE_RE);
+    if (m) out.push({ id: m[2], withdrawn: Boolean(m[1]) });
+  }
+  return out;
+}
+
+/**
+ * The latest receipt, reduced to what doneness needs: verdict, and whether its
+ * inputs.hash attests the tree AS IT STANDS (same cheap recompute the Stop
+ * hook and pre-push gate use). Absent/unparsable receipt -> present:false —
+ * never treated as PASS.
+ * @param {string} root
+ * @returns {{present: boolean, verdict: (string|null), attestsTree: boolean}}
+ */
+export function receiptAttestation(root) {
+  let receipt;
+  try {
+    receipt = JSON.parse(fs.readFileSync(path.join(root, "qa/evidence/latest.json"), "utf8"));
+  } catch {
+    return { present: false, verdict: null, attestsTree: false };
+  }
+  const recorded = receipt?.inputs?.hash;
+  let attestsTree = false;
+  if (typeof recorded === "string" && recorded !== "") {
+    try {
+      attestsTree = computeInputsHash(root).hash === recorded;
+    } catch {
+      attestsTree = false;
+    }
+  }
+  return { present: true, verdict: receipt?.verdict ?? null, attestsTree };
+}
+
+/**
+ * One feature's full derived state — brief, spec, coverage, receipt, verdict.
+ *
+ * `provenDone` is strict on purpose; each conjunct closes a specific hole:
+ *   - `total > 0`: a spec with no live clauses proves nothing (the vacuous-
+ *     approval stance, applied to doneness)
+ *   - `covered === total`: every promise has a citing test (specCoverage's own
+ *     definition, via the same scan)
+ *   - `verdict === "PASS"`: the citing tests actually ran green
+ *   - `attestsTree`: they ran green against THIS tree, not an earlier one
+ *
+ * @param {string} root
+ * @param {{name: string, rel: string}} brief
+ * @param {{citations?: Array<object>, receipt?: object}} [pre] precomputed
+ *   shared scans (callers resolving many features pass these once)
+ * @returns {object}
+ */
+export function deriveFeatureStatus(root, brief, pre = {}) {
+  let markdown = "";
+  let readable = true;
+  try {
+    markdown = fs.readFileSync(path.join(root, brief.rel), "utf8");
+  } catch {
+    readable = false;
+  }
+  const block = readable ? parseFeatureBlock(markdown) : { touches: [], screens: false, error: `${brief.rel} could not be read` };
+
+  const specRel = `specs/${brief.name}.spec.md`;
+  const specExists = fs.existsSync(path.join(root, specRel));
+  const citedIds = new Set((pre.citations ?? scanCitations(root)).map((t) => t.id));
+  const clauses = clausesOfSpec(root, specRel).map((c) => ({ ...c, cited: citedIds.has(c.id) }));
+  const live = clauses.filter((c) => !c.withdrawn);
+  const covered = live.filter((c) => c.cited).length;
+
+  const receipt = pre.receipt ?? receiptAttestation(root);
+  const provenDone = live.length > 0 && covered === live.length && receipt.verdict === "PASS" && receipt.attestsTree;
+
+  return {
+    name: brief.name,
+    rel: brief.rel,
+    touches: block.touches,
+    screens: block.screens,
+    blockError: block.error,
+    // The signed substance, for surfaces that show WHAT is being approved.
+    sections: readable ? briefSections(markdown) : [],
+    // How many edge cases the brief's adversarial pass recorded — the `audit`
+    // rung's only mechanical signal (see countEdgeCases).
+    edgeCases: readable ? countEdgeCases(markdown) : 0,
+    specRel,
+    specExists,
+    clauses,
+    covered,
+    total: live.length,
+    receipt,
+    provenDone,
+    // The one-line honest explanation of why it is / isn't done — the console
+    // and --status print this instead of re-deriving their own wording.
+    doneReason: provenDone
+      ? `${covered}/${live.length} clauses cited · receipt PASS · attests this tree`
+      : !specExists
+        ? `no spec yet (${specRel}) — behavior starts as clauses there`
+        : live.length === 0
+          ? `${specRel} has no live clauses — nothing is promised yet`
+          : covered < live.length
+            ? `${covered}/${live.length} clauses cited — ${live.length - covered} promise(s) have no citing test`
+            : !receipt.present
+              ? "all clauses cited, but no receipt — run node qa/verify.mjs"
+              : receipt.verdict !== "PASS"
+                ? `all clauses cited, but the latest receipt is ${receipt.verdict}`
+                : "all clauses cited and receipt PASS, but it attests an older tree — re-run node qa/verify.mjs",
+  };
+}
+
+/**
+ * Every feature, derived — the one call the CLI status surface and the console
+ * section share. Shared scans (citations, receipt) run once.
+ * @param {string} root
+ * @returns {Array<ReturnType<typeof deriveFeatureStatus>>}
+ */
+export function deriveAllFeatures(root) {
+  const briefs = listFeatureBriefs(root);
+  if (briefs.length === 0) return [];
+  const pre = { citations: scanCitations(root), receipt: receiptAttestation(root) };
+  return briefs.map((b) => deriveFeatureStatus(root, b, pre));
+}