create-cmp-cli 0.10.1 → 0.11.0

package/template/qa/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));
+}

package/template/qa/lib/inputs-hash.mjs

@@ -29,11 +29,47 @@ export const VERIFIED_SURFACE = [
   "gradle.properties",
 ];
 
-// Paths EXCLUDED even though they fall under an included surface dir above —
-// these are lane OUTPUTS, not inputs. Including them would make the hash
-// depend on the lane's own prior output (or, for qa-artifacts, on binary
-// scratch that is deliberately never committed).
-const EXCLUDED_PREFIXES = ["qa/evidence", "qa-artifacts"];
+// Paths EXCLUDED even though they fall under an included surface dir above.
+// qa/evidence and qa-artifacts are lane OUTPUTS — including them would make
+// the hash depend on the lane's own prior output. qa/comments.json is excluded
+// by this file's own stated principle: comments are explicitly advisory and no
+// lane step reads them, so their content cannot change the verdict — hashing
+// them made resolving a review note invalidate a receipt for a tree whose
+// code had not changed. qa/approvals.log.jsonl (the governance journal) is
+// excluded by the same principle: it is append-only HISTORY of decisions the
+// snapshot (qa/approvals.json) already carries as state — no lane step reads
+// it, so recording who/why must never invalidate a receipt for a tree whose
+// code did not change (the exact failure FI-8 killed for acceptance).
+const EXCLUDED_PREFIXES = ["qa/evidence", "qa-artifacts", "qa/comments.json", "qa/approvals.log.jsonl"];
+
+// qa/approvals.json is hashed by PROJECTION, not raw bytes. The approvals gate's
+// verdict depends on exactly three row fields (artifact, status, hash) plus the
+// top-level exemplarFeature (it selects the exemplar artifact's file set).
+// Everything else on a row — approvedAt, mode, via, reopenedAt, accepted,
+// acceptedAt — is ledger bookkeeping that records a decision without gating one.
+// Hashing those bytes meant the human clicking Accept on a provenDone feature
+// instantly invalidated the receipt whose PASS permitted the acceptance.
+// Acceptance is a bookend recorded after proof; it must not destroy it.
+// An unparsable ledger falls back to raw bytes — refusal over fabrication.
+const APPROVALS_PROJECTED_PATH = "qa/approvals.json";
+
+function projectApprovalsBytes(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw.toString("utf8"));
+  } catch {
+    return raw;
+  }
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.artifacts)) return raw;
+  const rows = parsed.artifacts
+    .filter((a) => a && typeof a === "object")
+    .map((a) => ({ artifact: a.artifact ?? null, status: a.status ?? null, hash: a.hash ?? null }))
+    .sort((a, b) => (String(a.artifact) < String(b.artifact) ? -1 : String(a.artifact) > String(b.artifact) ? 1 : 0));
+  const projection = {};
+  if (typeof parsed.exemplarFeature === "string") projection.exemplarFeature = parsed.exemplarFeature;
+  projection.artifacts = rows;
+  return Buffer.from(`${JSON.stringify(projection)}\n`, "utf8");
+}
 
 function isExcluded(relPath) {
   return EXCLUDED_PREFIXES.some((prefix) => relPath === prefix || relPath.startsWith(`${prefix}/`));
@@ -133,7 +169,8 @@ export function computeInputsHash(root) {
 
   const overall = createHash("sha256");
   for (const relPath of files) {
-    const bytes = fs.readFileSync(path.join(root, relPath));
+    const raw = fs.readFileSync(path.join(root, relPath));
+    const bytes = relPath === APPROVALS_PROJECTED_PATH ? projectApprovalsBytes(raw) : raw;
     const fileSha = createHash("sha256").update(bytes).digest("hex");
     overall.update(`${relPath}\0${fileSha}\n`);
   }

package/template/qa/lib/reachability.mjs

@@ -0,0 +1,211 @@
+// reachability.mjs — the navigation-reachability gate (task FI-7,
+// docs/AUTONOMY-GAPS.md §3): a feature that passes spec coverage, conformance,
+// goldens, a11y, and on-device smoke — and is STILL unreachable because no
+// destination in the navigation graph points at it — is a confident false
+// green. `MealTrayScreen` was accepted that way: its `MealTrayRoute` composable
+// was referenced by nothing but its own tests. This gate exists to catch
+// exactly that shape of drift, mechanically, so it can never happen silently
+// again.
+//
+// Pure Node, no Gradle — same stance as component-stories.mjs and
+// spec-coverage.mjs: a pragmatic source scan, not a Kotlin front end.
+//
+// A "feature" is any top-level directory under commonMain's presentation/,
+// except `components` and `theme` (registry/design surfaces, not screens),
+// that contains at least one `*Screen.kt` file (recursive). Its ENTRY
+// composables are the top-level `fun <Name>(` declarations in those files
+// whose name ends in `Screen` or `Route` — the navigation-entry naming
+// convention this template's own exemplar follows (HomeScreen, DetailScreen).
+// A feature is REACHABLE if any entry composable's name is referenced —
+// word-boundary, not a call-site parse — from a commonMain `.kt` file OUTSIDE
+// its own presentation/<feature>/ directory. The navigation graph
+// (AppNavHost) is the expected referencer.
+//
+// desktopMain (PreviewRegistry.kt, ComponentStories.kt) and test sources
+// deliberately do NOT count: registering a screen in the preview gallery is
+// not wiring it into the app a user runs — that is exactly the false green
+// this gate exists to close, so only commonMain counts as a live reference.
+//
+// A feature with no entry composable at all (nothing named `*Screen`/`*Route`
+// declared at top level) has nothing this gate can check reachability FOR —
+// it is passed through untouched rather than flagged, the same "nothing to
+// check" stance component-stories.mjs takes for an empty registry.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { parseFeatureBlock } from "./feature-brief.mjs";
+
+// Mirrors component-stories.mjs's walkDirs: every directory named `wanted`
+// anywhere under `root`, recursive.
+function walkDirs(root, wanted) {
+  const out = [];
+  (function walk(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const p = path.join(dir, e.name);
+      if (e.name === wanted) out.push(p);
+      else walk(p);
+    }
+  })(root);
+  return out;
+}
+
+// Mirrors component-stories.mjs's walkKtFilesDeep: every `.kt` file under
+// `dir`, recursive.
+function walkKtFilesDeep(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...walkKtFilesDeep(p));
+    else if (e.name.endsWith(".kt")) out.push(p);
+  }
+  return out;
+}
+
+// Top-level `fun Name(` — unindented (column 0), the same line-anchored
+// scanning stance as spec-coverage.mjs's CLAUSE_LINE_RE: a pragmatic source
+// scan, not a Kotlin front end. Deliberately does not require `@Composable`
+// on the preceding line — the entry-naming convention (Screen/Route suffix)
+// is the signal, not the annotation.
+const TOP_LEVEL_FUN_RE = /^fun\s+([A-Za-z_][A-Za-z0-9_]*)\s*(?:<[^>]*>)?\s*\(/gm;
+
+/**
+ * The entry composables one `*Screen.kt` file's text declares: top-level
+ * `fun`s whose name ends `Screen` or `Route`. Order-preserving, de-duplicated
+ * by the caller across a feature's files.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function findEntryComposables(text) {
+  const names = [];
+  TOP_LEVEL_FUN_RE.lastIndex = 0;
+  let m;
+  while ((m = TOP_LEVEL_FUN_RE.exec(text))) {
+    if (/(Screen|Route)$/.test(m[1])) names.push(m[1]);
+  }
+  return names;
+}
+
+/**
+ * Evaluate navigation reachability for a project root.
+ * @param {string} root project root (contains composeApp/)
+ * @returns {{verdict: "PASS"|"FAIL"|"SKIP", reason?: string, details: {features: Array<{name: string, reachable: boolean, unrouted?: boolean, entryComposables: string[]}>}}}
+ */
+export function evaluateReachability(root) {
+  const commonRoot = path.join(root, "composeApp", "src", "commonMain", "kotlin");
+  if (!fs.existsSync(commonRoot)) {
+    return {
+      verdict: "SKIP",
+      reason: "no commonMain/kotlin directory under composeApp/src — kotlin root unresolvable, nothing to check",
+      details: { features: [] },
+    };
+  }
+
+  const presentationDirs = walkDirs(commonRoot, "presentation");
+  if (presentationDirs.length === 0) {
+    return { verdict: "SKIP", reason: "no presentation directory under commonMain — nothing to check", details: { features: [] } };
+  }
+
+  // The whole commonMain .kt surface, read once — both the per-feature scan
+  // source and the reachability search space (desktopMain/test deliberately
+  // excluded: see the file header).
+  const allKtFiles = walkKtFilesDeep(commonRoot);
+  const textOf = new Map(allKtFiles.map((f) => [f, fs.readFileSync(f, "utf8")]));
+
+  const features = []; // { name, dir, entryComposables }
+  for (const presentationDir of presentationDirs) {
+    let entries;
+    try {
+      entries = fs.readdirSync(presentationDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory() || e.name === "components" || e.name === "theme") continue;
+      const featureDir = path.join(presentationDir, e.name);
+      const screenFiles = walkKtFilesDeep(featureDir).filter((f) => path.basename(f).endsWith("Screen.kt"));
+      if (screenFiles.length === 0) continue; // not a feature per this gate's definition
+
+      const entryComposables = [];
+      for (const f of screenFiles) {
+        for (const name of findEntryComposables(textOf.get(f) ?? "")) {
+          if (!entryComposables.includes(name)) entryComposables.push(name);
+        }
+      }
+      features.push({ name: e.name, dir: featureDir, entryComposables });
+    }
+  }
+
+  if (features.length === 0) {
+    return { verdict: "SKIP", reason: "no presentation/<feature> directory has a *Screen.kt file — nothing to check", details: { features: [] } };
+  }
+
+  const resultFeatures = [];
+  const unreachable = [];
+  for (const feature of features) {
+    // Nothing named Screen/Route was declared at all — this gate has nothing
+    // to check reachability for; pass it through rather than flag it.
+    if (feature.entryComposables.length === 0) {
+      resultFeatures.push({ name: feature.name, reachable: true, entryComposables: [] });
+      continue;
+    }
+
+    const featurePrefix = feature.dir + path.sep;
+    const outsideFiles = allKtFiles.filter((f) => !f.startsWith(featurePrefix));
+    const reachable = feature.entryComposables.some((name) => {
+      const re = new RegExp(`\\b${name}\\b`);
+      return outsideFiles.some((f) => re.test(textOf.get(f) ?? ""));
+    });
+
+    if (reachable) {
+      resultFeatures.push({ name: feature.name, reachable: true, entryComposables: feature.entryComposables });
+      continue;
+    }
+
+    // Exemption: docs/features/<name>.md's cmp:feature block declares
+    // { "unrouted": true } — the same declare-not-gate mechanism
+    // feature-brief.mjs already defines for `touches`/`screens`.
+    let unrouted = false;
+    try {
+      const briefMarkdown = fs.readFileSync(path.join(root, "docs", "features", `${feature.name}.md`), "utf8");
+      unrouted = parseFeatureBlock(briefMarkdown).unrouted === true;
+    } catch {
+      unrouted = false;
+    }
+
+    if (unrouted) {
+      resultFeatures.push({ name: feature.name, reachable: true, unrouted: true, entryComposables: feature.entryComposables });
+      continue;
+    }
+
+    resultFeatures.push({ name: feature.name, reachable: false, entryComposables: feature.entryComposables });
+    unreachable.push(feature);
+  }
+
+  if (unreachable.length === 0) {
+    return { verdict: "PASS", details: { features: resultFeatures } };
+  }
+
+  const lines = [
+    "Reachability broken — a feature's screen passed every other gate but nothing in the navigation graph points at it (a screen nobody can navigate to is not a delivered feature):",
+  ];
+  for (const f of unreachable) {
+    lines.push(
+      `  [${f.name}] entry composable(s) ${f.entryComposables.join(", ")} — not referenced anywhere in commonMain outside presentation/${f.name}/. Fix it one of two ways: wire a destination for it in the navigation graph (AppNavHost), or, if it is intentionally not routed yet, declare { "unrouted": true } in docs/features/${f.name}.md's cmp:feature block.`,
+    );
+  }
+  return { verdict: "FAIL", reason: lines.join("\n"), details: { features: resultFeatures } };
+}

package/template/qa/lib/spec-coverage.mjs

@@ -0,0 +1,80 @@
+// spec-coverage.mjs — the clause ↔ citation scan, as a library.
+//
+// Extracted from qa/verify.mjs's stepSpecCoverage so there is exactly ONE
+// definition of "what is a clause" and "what cites it". Two consumers:
+//   - the lane's specCoverage gate (orphans in either direction FAIL)
+//   - feature-brief.mjs's derived doneness (a feature is done when every live
+//     clause in ITS spec is cited and the receipt attests the tree)
+// If these two scanned differently, the Features view and the lane could
+// disagree about the same clause — the exact two-truths problem this file
+// exists to prevent.
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** `- **HOME-01** — …` (live) or `- ~~**HOME-01**~~ — …` (withdrawn). */
+export const CLAUSE_LINE_RE = /^-\s+(~~)?\*\*([A-Z][A-Z0-9]*-\d{2,})\*\*/;
+
+const TAG_LINE_RE = /^(?:\/\/|#)\s*SPEC:/;
+const TAG_IDS_RE = /SPEC:\s*([A-Z0-9,\s-]+)/;
+const CLAUSE_ID_RE = /^[A-Z][A-Z0-9]*-\d{2,}$/;
+
+/** Recursive walk returning files under `dir` ending in one of `exts`. */
+export function walkFiles(dir, exts) {
+  const out = [];
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walkFiles(p, exts));
+    else if (exts.some((ext) => entry.name.endsWith(ext))) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Every clause in every specs/*.spec.md.
+ * @param {string} root
+ * @returns {Map<string, {file: string, withdrawn: boolean}>} id -> where/state
+ */
+export function scanSpecClauses(root) {
+  const clauses = new Map();
+  const specsDir = path.join(root, "specs");
+  if (!fs.existsSync(specsDir)) return clauses;
+  for (const f of fs.readdirSync(specsDir).filter((n) => n.endsWith(".spec.md"))) {
+    const abs = path.join(specsDir, f);
+    for (const line of fs.readFileSync(abs, "utf8").split("\n")) {
+      const m = line.match(CLAUSE_LINE_RE);
+      if (!m) continue;
+      clauses.set(m[2], { file: path.relative(root, abs), withdrawn: Boolean(m[1]) });
+    }
+  }
+  return clauses;
+}
+
+/**
+ * Every `// SPEC: ID[, ID…]` / `# SPEC: …` citation tag under composeApp/src
+ * and qa/e2e.
+ * @param {string} root
+ * @returns {Array<{id: string, file: string, line: number}>}
+ */
+export function scanCitations(root) {
+  const tags = [];
+  const searchDirs = [path.join(root, "composeApp/src"), path.join(root, "qa/e2e")];
+  const files = searchDirs.flatMap((d) => walkFiles(d, [".kt", ".kts", ".yaml", ".yml"]));
+  for (const f of files) {
+    fs.readFileSync(f, "utf8")
+      .split("\n")
+      .forEach((line, i) => {
+        const trimmed = line.trim();
+        if (!TAG_LINE_RE.test(trimmed)) return;
+        const m = trimmed.match(TAG_IDS_RE);
+        if (!m) return;
+        const ids = m[1]
+          .split(/[,\s]+/)
+          .map((s) => s.trim())
+          .filter((s) => CLAUSE_ID_RE.test(s));
+        for (const id of ids) tags.push({ id, file: path.relative(root, f), line: i + 1 });
+      });
+  }
+  return tags;
+}