create-cmp-cli 0.12.0 → 0.14.0

package/packages/harness/src/lib/inputs-hash.mjs

@@ -0,0 +1,194 @@
+// Shared primitive: a content hash of the "verified surface" — every tracked
+// file whose content can change the verify lane's verdict, minus the lane's
+// own outputs. Both qa/verify.mjs (writes inputs.hash into the receipt) and
+// qa/receipt-check.mjs (recomputes it to test validity) import this module so
+// there is exactly one definition of the surface and the algorithm.
+//
+// SINGLE SOURCE OF TRUTH: packages/receipts/src/inputs-hash.mjs in the
+// create-cmp repo (the `cmp-receipts` package). The copy in a generated
+// project's qa/lib/ is vendored byte-identical at scaffold time and pinned by
+// test/receipts-parity.test.mjs — edit the package source, then run
+// `node scripts/sync-harness.mjs`.
+//
+// See docs/adr/0005-evidence-binding-by-inputs-hash.md for the why.
+
+import { execSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+// Directories / files INCLUDED in the verified surface (relative to project ROOT).
+// Principle: every tracked file whose content can change the lane's verdict.
+export const VERIFIED_SURFACE = [
+  "composeApp",
+  "specs",
+  "qa",
+  "gradle/libs.versions.toml",
+  "build.gradle.kts",
+  "settings.gradle.kts",
+  "gradle.properties",
+];
+
+// 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).
+// qa/flight-recorder.jsonl is a lane OUTPUT in the strictest sense: the lane
+// appends one line to it on every run, after the receipt is written — hashing
+// it would make every run invalidate its own receipt. qa/audits.jsonl (the
+// cmp-audit ledger) is read by exactly one lane step (auditCadence), which is
+// a REPORT and can never change the verdict — and recording an audit is
+// bookkeeping about a commit that already happened, so appending a record
+// must never invalidate a receipt for a tree whose code did not change
+// (approvals.log.jsonl's principle, applied to audits).
+const EXCLUDED_PREFIXES = [
+  "qa/evidence",
+  "qa-artifacts",
+  "qa/comments.json",
+  "qa/approvals.log.jsonl",
+  "qa/flight-recorder.jsonl",
+  "qa/audits.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}/`));
+}
+
+// The verified surface is the set of files that WILL be committed: tracked files
+// PLUS untracked-but-not-ignored files (`--others --exclude-standard`). A freshly
+// generated feature's files are untracked when the lane runs and the receipt is
+// written, yet they land in the very same commit as the receipt — so they must be
+// hashed, or the committed receipt would never attest its own commit (and CI's
+// receipt-matches-HEAD gate would false-fail on every change). Gitignored scratch
+// (build outputs, qa-artifacts) is still excluded via --exclude-standard.
+function tryGitLsFiles(root) {
+  try {
+    const out = execSync("git ls-files -z --cached --others --exclude-standard", { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return out.split("\0").filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+// Directory names the walk fallback must skip wherever they appear under a
+// surface root. These mirror what the stamped .gitignore excludes: without
+// this, a pre-`git init` hash (walk mode) includes composeApp/build/** and
+// Gradle/Kotlin scratch that the post-`git init` hash (`git ls-files
+// --exclude-standard`) excludes — so the stamp-time PASS receipt would read
+// "INVALID — source changed" the moment the user runs `git init`, even though
+// no source changed. Pre-git and post-git hashes must agree for identical
+// source; that is the invariant the regression test pins.
+const WALK_EXCLUDED_DIRS = new Set(["build", ".gradle", ".kotlin", ".git", ".idea", "node_modules"]);
+// File-level mirror of the same principle (OS/editor junk the .gitignore covers).
+const WALK_EXCLUDED_FILES = new Set([".DS_Store"]);
+const WALK_EXCLUDED_SUFFIXES = [".iml", ".log"];
+
+function walkIncludesFile(name) {
+  if (WALK_EXCLUDED_FILES.has(name)) return false;
+  return !WALK_EXCLUDED_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+
+// Dependency-free recursive walk, used when git is unavailable (non-git scaffold).
+function walkAllFiles(dir) {
+  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()) {
+      if (WALK_EXCLUDED_DIRS.has(entry.name)) continue; // non-source scratch — see note above
+      out.push(...walkAllFiles(p));
+    } else if (entry.isFile() && walkIncludesFile(entry.name)) out.push(p);
+  }
+  return out;
+}
+
+// Resolve the verified surface to a flat, sorted list of paths (relative to
+// root, POSIX-style `/` separators) that currently exist on disk.
+function resolveSurfaceFiles(root) {
+  const gitFiles = tryGitLsFiles(root);
+
+  if (gitFiles) {
+    return gitFiles
+      .map((p) => p.split(path.sep).join("/"))
+      .filter((relPath) => VERIFIED_SURFACE.some((surface) => relPath === surface || relPath.startsWith(`${surface}/`)))
+      .filter((relPath) => !isExcluded(relPath))
+      .filter((relPath) => fs.existsSync(path.join(root, relPath)) && fs.statSync(path.join(root, relPath)).isFile());
+  }
+
+  // Fallback: no git available — walk the surface directories directly so a
+  // non-git scaffold still produces a stable hash.
+  const collected = [];
+  for (const surface of VERIFIED_SURFACE) {
+    const abs = path.join(root, surface);
+    if (!fs.existsSync(abs)) continue;
+    const stat = fs.statSync(abs);
+    if (stat.isFile()) {
+      collected.push(surface);
+    } else if (stat.isDirectory()) {
+      for (const file of walkAllFiles(abs)) {
+        collected.push(path.relative(root, file).split(path.sep).join("/"));
+      }
+    }
+  }
+  return collected.filter((relPath) => !isExcluded(relPath));
+}
+
+/**
+ * Compute the sha256 hash of the verified surface for the project rooted at `root`.
+ * Deterministic: same tree (same file paths + same file bytes) → same hash.
+ * @param {string} root absolute path to the project root
+ * @returns {{ hash: string, fileCount: number }}
+ */
+export function computeInputsHash(root) {
+  // Code-unit sort (default String sort), NOT localeCompare: the hash depends
+  // on iteration order, and ICU collation varies with the machine's locale
+  // (e.g. a da_DK machine orders "aa" after "z"; en orders case-insensitively
+  // where code units do not) — the same tree must hash identically everywhere.
+  const files = [...new Set(resolveSurfaceFiles(root))].sort();
+
+  const overall = createHash("sha256");
+  for (const relPath of files) {
+    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`);
+  }
+
+  return { hash: overall.digest("hex"), fileCount: files.length };
+}

package/packages/harness/src/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/packages/harness/src/lib/receipt-validate.mjs

@@ -0,0 +1,234 @@
+// The evidence-binding predicate and its service-grade extensions, as pure
+// dependency-free functions. `evaluateReceipt` is the exact predicate the
+// generated project's qa/receipt-check.mjs (and its Stop hook + CI) runs;
+// the additional checks (freshness, execution plausibility, SKIP listing) are
+// consumed by hosted validators that judge a receipt fetched from a repo
+// tarball rather than the working tree.
+//
+// SINGLE SOURCE OF TRUTH: packages/receipts/src/receipt-validate.mjs in the
+// create-cmp repo (the `cmp-receipts` package). The copy in a generated
+// project's qa/lib/ is vendored byte-identical at scaffold time and pinned by
+// test/receipts-parity.test.mjs — edit the package source, then run
+// `node scripts/sync-harness.mjs`.
+//
+// See docs/adr/0005-evidence-binding-by-inputs-hash.md for the why.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { computeInputsHash } from "./inputs-hash.mjs";
+
+/** Where a generated project keeps its committed receipt, relative to root. */
+export const RECEIPT_REL_PATH = "qa/evidence/latest.json";
+
+/**
+ * Read and parse the committed receipt for the project rooted at `root`.
+ * @param {string} root absolute path to the project root
+ * @returns {object|null} the parsed receipt, or null when absent/unparsable
+ */
+export function readReceipt(root, relPath = RECEIPT_REL_PATH) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, relPath), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The core predicate: does this receipt validly attest the tree whose inputs
+ * hash `recompute()` returns? Reasons are the exact refusal strings the
+ * generated project's receipt-check CLI (and Stop hook) prints.
+ *
+ * @param {object} receipt parsed receipt JSON
+ * @param {() => {hash: string, fileCount: number}} recompute lazily invoked —
+ *   never called when the receipt fails structurally first (missing binding,
+ *   FAIL verdict), so callers don't pay for a hash they don't need.
+ * @returns {{valid: boolean, reason: string, profile: (string|undefined), recomputed?: {hash: string, fileCount: number}}}
+ */
+export function evaluateReceipt(receipt, recompute) {
+  const profile = receipt.profile;
+
+  if (!receipt.inputs || typeof receipt.inputs.hash !== "string") {
+    return {
+      valid: false,
+      reason: `receipt predates evidence binding — re-run the lane (attesting profile: ${profile ?? "unknown"})`,
+      profile,
+    };
+  }
+
+  if (receipt.verdict === "FAIL") {
+    return {
+      valid: false,
+      reason: `the committed receipt is a FAIL (attesting profile: ${profile ?? "unknown"})`,
+      profile,
+    };
+  }
+
+  const recomputed = recompute();
+
+  if (receipt.inputs.hash !== recomputed.hash) {
+    return {
+      valid: false,
+      reason: `source changed since the receipt — re-run the lane (attesting profile: ${profile ?? "unknown"})`,
+      profile,
+      recomputed,
+    };
+  }
+
+  if (receipt.verdict !== "PASS") {
+    return {
+      valid: false,
+      reason: `receipt verdict is "${receipt.verdict}", not PASS (attesting profile: ${profile ?? "unknown"})`,
+      profile,
+    };
+  }
+
+  return { valid: true, reason: `receipt is valid — PASS, attesting profile: ${profile ?? "unknown"}`, profile, recomputed };
+}
+
+// ── Service-grade checks (hosted validators; the local predicate above does
+//    not enforce these — the tree it checks is by definition "now") ─────────
+
+/** Default policy for hosted validation. Every knob is overridable. */
+export const DEFAULT_POLICY = {
+  /** A receipt older than this no longer counts as fresh (hosted check only). */
+  maxAgeMs: 30 * 24 * 60 * 60 * 1000, // 30 days
+  /**
+   * Executed (non-SKIP) gates must report at least this much total wall time.
+   * A "PASS" receipt whose executed gates sum to less cannot attest a real
+   * lane run — the tell for replayed/cached or hand-written verdicts
+   * (evidence must attest execution, not results).
+   */
+  minExecutedMs: 5000,
+};
+
+/**
+ * Freshness: is the receipt's generatedAt within maxAgeMs of `now`?
+ * @returns {{ok: boolean, detail: string, ageMs?: number}}
+ */
+export function checkFreshness(receipt, { now = Date.now(), maxAgeMs = DEFAULT_POLICY.maxAgeMs } = {}) {
+  const generatedAt = Date.parse(receipt?.generatedAt ?? "");
+  if (Number.isNaN(generatedAt)) {
+    return { ok: false, detail: "receipt has no parsable generatedAt timestamp" };
+  }
+  const ageMs = now - generatedAt;
+  if (ageMs < -60_000) {
+    // A receipt from the future is a clock lie, not a rounding artifact.
+    return { ok: false, detail: `receipt claims a future generatedAt (${receipt.generatedAt})`, ageMs };
+  }
+  if (ageMs > maxAgeMs) {
+    const days = Math.floor(ageMs / 86_400_000);
+    return { ok: false, detail: `receipt is stale — generated ${days} day(s) ago, older than the ${Math.floor(maxAgeMs / 86_400_000)}-day freshness window`, ageMs };
+  }
+  return { ok: true, detail: `receipt generated ${receipt.generatedAt}`, ageMs };
+}
+
+/**
+ * Execution plausibility: do the executed (non-SKIP) gates report durations a
+ * real lane run could produce? Catches replayed/cached greens and hand-edited
+ * receipts whose numbers were never lived.
+ * @returns {{ok: boolean, detail: string, executedMs?: number, executedSteps?: number}}
+ */
+export function checkExecutionPlausibility(receipt, { minExecutedMs = DEFAULT_POLICY.minExecutedMs } = {}) {
+  const steps = Array.isArray(receipt?.steps) ? receipt.steps : null;
+  if (!steps || steps.length === 0) {
+    return { ok: false, detail: "receipt lists no verify-lane steps — nothing was executed" };
+  }
+  const executed = steps.filter((s) => s && s.verdict !== "SKIP");
+  if (executed.length === 0) {
+    return { ok: false, detail: "every step in the receipt is a SKIP — the lane verified nothing" };
+  }
+  let total = 0;
+  for (const step of executed) {
+    if (typeof step.durationMs !== "number" || !Number.isFinite(step.durationMs) || step.durationMs < 0) {
+      return { ok: false, detail: `step "${step.name ?? "?"}" reports an invalid duration (${step.durationMs}) — durations must be real, non-negative numbers` };
+    }
+    total += step.durationMs;
+  }
+  if (total < minExecutedMs) {
+    return {
+      ok: false,
+      detail: `implausibly fast — executed gates report ${total}ms total, below the ${minExecutedMs}ms floor; a receipt this fast cannot attest a real lane run (evidence must attest execution)`,
+      executedMs: total,
+      executedSteps: executed.length,
+    };
+  }
+  return { ok: true, detail: `${executed.length} executed gate(s), ${total}ms total`, executedMs: total, executedSteps: executed.length };
+}
+
+/**
+ * List the SKIPped steps with their honest reasons. SKIPs are reported, not
+ * failed — green-with-gaps must be visible, never silently equated with
+ * fully-verified (or silently punished).
+ * @returns {Array<{name: string, reason: string}>}
+ */
+export function listSkippedSteps(receipt) {
+  const steps = Array.isArray(receipt?.steps) ? receipt.steps : [];
+  return steps
+    .filter((s) => s && s.verdict === "SKIP")
+    .map((s) => ({ name: s.name ?? "?", reason: s.reason ?? "no reason recorded" }));
+}
+
+/**
+ * The hosted composite: validate the receipt found in an extracted repo tree
+ * (e.g. a tarball at a PR's head SHA) with the full service-grade policy.
+ *
+ * @param {object} args
+ * @param {string} args.root absolute path to the extracted tree's project root
+ * @param {number} [args.now] epoch ms, for freshness (defaults to Date.now())
+ * @param {object} [args.policy] overrides for DEFAULT_POLICY
+ * @returns {{
+ *   status: "missing"|"valid"|"invalid",
+ *   reason: string,
+ *   profile?: string,
+ *   checks: Array<{id: string, ok: boolean, detail: string}>,
+ *   skips: Array<{name: string, reason: string}>,
+ * }}
+ */
+export function validateReceiptForTree({ root, now = Date.now(), policy = {} } = {}) {
+  const effective = { ...DEFAULT_POLICY, ...policy };
+  const receipt = readReceipt(root);
+
+  if (receipt === null) {
+    return {
+      status: "missing",
+      reason: `no receipt at ${RECEIPT_REL_PATH} — this repo does not carry the create-cmp evidence harness (that is not a failure)`,
+      checks: [{ id: "receipt-present", ok: false, detail: `no parsable receipt at ${RECEIPT_REL_PATH}` }],
+      skips: [],
+    };
+  }
+
+  const checks = [{ id: "receipt-present", ok: true, detail: RECEIPT_REL_PATH }];
+  const skips = listSkippedSteps(receipt);
+
+  // The core predicate (binding + verdict + hash), verbatim local semantics.
+  const core = evaluateReceipt(receipt, () => computeInputsHash(root));
+  checks.push({ id: "binding-and-hash", ok: core.valid, detail: core.reason });
+
+  // Service-grade extensions run regardless, so a failing receipt reports
+  // every violated rule at once (refusals name what failed, all of it).
+  const freshness = checkFreshness(receipt, { now, maxAgeMs: effective.maxAgeMs });
+  checks.push({ id: "freshness", ok: freshness.ok, detail: freshness.detail });
+
+  const plausibility = checkExecutionPlausibility(receipt, { minExecutedMs: effective.minExecutedMs });
+  checks.push({ id: "execution-plausibility", ok: plausibility.ok, detail: plausibility.detail });
+
+  const failed = checks.filter((c) => !c.ok);
+  if (failed.length > 0) {
+    return {
+      status: "invalid",
+      reason: failed.map((c) => c.detail).join("; "),
+      profile: core.profile,
+      checks,
+      skips,
+    };
+  }
+
+  return {
+    status: "valid",
+    reason: core.reason,
+    profile: core.profile,
+    checks,
+    skips,
+  };
+}