create-cmp-cli 0.18.0 → 0.20.0

package/template/qa/lib/plan.mjs

@@ -33,6 +33,13 @@ import path from "node:path";
 
 export const PLAN_REL = "qa/.plan.json";
 export const REQUEST_REL = "qa/.request.json";
+// N5 (docs/features/drive-narration.md): closed chains leave a LOCAL trail —
+// request, steps, wall time, receipt state at close. Gitignored and excluded
+// from the hashed input surface like its siblings above, and deliberately NOT
+// a committed journal: it carries raw human prompts. Lane history that
+// belongs in the repo stays the flight recorder's.
+export const PLAN_HISTORY_REL = "qa/.plan-history.jsonl";
+const MAX_HISTORY_LINES = 50;
 
 // A marker older than this is a crashed writer, not a live run — the same
 // bound qa/watch.mjs and the preview daemon apply to the same files.
@@ -91,12 +98,17 @@ export function setPlan(root, { title, feature, steps } = {}) {
     .slice(0, MAX_STEPS)
     .map((s) => (s.length > MAX_LABEL_CHARS ? `${s.slice(0, MAX_LABEL_CHARS - 1)}…` : s));
   if (labels.length === 0) return { ok: false, reason: "a chain needs at least one step" };
+  // N1: the declaration's own write times ARE the timing data — createdAt for
+  // the whole chain, startedAt on step 1. No new claims, just timestamps the
+  // writes already imply; renderers derive durations from them.
+  const now = new Date().toISOString();
   return writeJson(path.join(root, PLAN_REL), {
     title: typeof title === "string" && title.trim() !== "" ? title.trim() : null,
     feature: typeof feature === "string" && feature.trim() !== "" ? feature.trim() : null,
-    steps: labels.map((label, i) => ({ n: i + 1, label, done: false })),
+    steps: labels.map((label, i) => ({ n: i + 1, label, done: false, ...(i === 0 ? { startedAt: now } : {}) })),
     current: 1,
-    updatedAt: new Date().toISOString(),
+    createdAt: now,
+    updatedAt: now,
   });
 }
 
@@ -112,10 +124,90 @@ export function markStep(root, n) {
   const step = Number(n);
   if (!Number.isInteger(step) || step < 1 || step > plan.steps.length + 1)
     return { ok: false, reason: `step must be 1..${plan.steps.length + 1} (=${plan.steps.length + 1} closes the chain), got ${n}` };
-  for (const s of plan.steps) s.done = s.n < step;
+  const now = new Date().toISOString();
+  for (const s of plan.steps) {
+    const willBeDone = s.n < step;
+    // N1: stamp doneAt the first time a step closes and startedAt the first
+    // time it becomes current — first-write-wins, so re-marking never
+    // rewrites history.
+    if (willBeDone && !s.done && !s.doneAt) s.doneAt = now;
+    s.done = willBeDone;
+    if (s.n === step && !s.startedAt) s.startedAt = now;
+  }
+  const closing = step > plan.steps.length && !plan.closedAt;
   plan.current = step > plan.steps.length ? null : step;
-  plan.updatedAt = new Date().toISOString();
-  return writeJson(path.join(root, PLAN_REL), plan).ok ? { ok: true, plan } : { ok: false, reason: "could not write the chain" };
+  if (closing) plan.closedAt = now;
+  plan.updatedAt = now;
+  if (!writeJson(path.join(root, PLAN_REL), plan).ok) return { ok: false, reason: "could not write the chain" };
+  // N5: the FIRST close leaves the trail entry; a re-close of an already
+  // closed chain never double-writes. Fail-soft — a trail that cannot be
+  // written must not fail the advance that was asked for.
+  if (closing) appendPlanHistory(root, plan);
+  return { ok: true, plan };
+}
+
+/** The receipt's verdict + rung right now, for the trail — fail-soft glance. */
+function receiptGlance(root) {
+  try {
+    const r = JSON.parse(fs.readFileSync(path.join(root, "qa/evidence/latest.json"), "utf8"));
+    return { verdict: r?.verdict ?? null, rung: r?.evidenceLevel?.rung ?? null };
+  } catch {
+    return null;
+  }
+}
+
+function appendPlanHistory(root, plan) {
+  try {
+    const started = Date.parse(plan.createdAt ?? "");
+    const closed = Date.parse(plan.closedAt ?? "");
+    const entry = {
+      schema: "cmp-plan-history/1",
+      at: plan.closedAt ?? new Date().toISOString(),
+      request: readRequest(root)?.text ?? null,
+      title: plan.title ?? null,
+      feature: plan.feature ?? null,
+      steps: plan.steps.map((s) => s.label),
+      durationMs: Number.isNaN(started) || Number.isNaN(closed) ? null : Math.max(0, closed - started),
+      receipt: receiptGlance(root),
+    };
+    const p = path.join(root, PLAN_HISTORY_REL);
+    let lines = [];
+    try {
+      lines = fs.readFileSync(p, "utf8").split("\n").filter((l) => l.trim() !== "");
+    } catch {
+      /* first entry */
+    }
+    lines.push(JSON.stringify(entry));
+    fs.writeFileSync(p, `${lines.slice(-MAX_HISTORY_LINES).join("\n")}\n`);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, reason: err?.message ?? String(err) };
+  }
+}
+
+/**
+ * The last `limit` closed chains, NEWEST FIRST — Drive's "Recent requests"
+ * fold. Absent trail or unparsable lines read as an empty/shorter list,
+ * never an error.
+ * @returns {object[]}
+ */
+export function readPlanHistory(root, limit = 5) {
+  try {
+    const raw = fs.readFileSync(path.join(root, PLAN_HISTORY_REL), "utf8");
+    const out = [];
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const e = JSON.parse(line);
+        if (e && typeof e === "object") out.push(e);
+      } catch {
+        /* skip the line, keep the trail */
+      }
+    }
+    return out.slice(-Math.max(0, limit)).reverse();
+  } catch {
+    return [];
+  }
 }
 
 /** @returns {object|null} the declared chain, or null. */
@@ -134,33 +226,130 @@ export function clearPlan(root) {
   }
 }
 
-function markerFresh(root, name) {
+/**
+ * A marker read WITH its content (N2, docs/features/drive-narration.md):
+ * every other marker consumer is mtime-only, so the content is free to carry
+ * the lane's own narration — verify.mjs rewrites the lane marker at each
+ * step start with {step, index, total, stepStartedAt, expectedStepMs,
+ * expectedLaneMs}. Legacy "pid iso" content (older lanes, the render marker)
+ * reads as a bare truthy {} — busy, no narration. Stale/absent -> false.
+ * @returns {object|false}
+ */
+function markerInfo(root, name) {
+  const p = path.join(root, "composeApp", "build", name);
   try {
-    const st = fs.statSync(path.join(root, "composeApp", "build", name));
-    return Date.now() - st.mtimeMs < MARKER_FRESH_MS;
+    const st = fs.statSync(p);
+    if (Date.now() - st.mtimeMs >= MARKER_FRESH_MS) return false;
+    const raw = fs.readFileSync(p, "utf8").trim();
+    if (raw.startsWith("{")) {
+      try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+      } catch {
+        return {};
+      }
+    }
+    return {};
   } catch {
     return false;
   }
 }
 
+// The build stage's observed tier (evidence-economics S3). Between the prompt
+// and the lane — most of the working time — the chain moved only if the agent
+// volunteered `plan.mjs --step`, so an undeclared chain was a still photo until
+// the lane landed. The lane marker already corroborates the lane mechanically;
+// this corroborates the build stage the same way: writes in the working tree
+// since the current request began. No agent cooperation required — which is
+// the point.
+const ACTIVITY_ROOTS = ["composeApp/src", "specs", "qa", "docs"];
+const ACTIVITY_SKIP_DIRS = new Set(["build", ".gradle", ".kotlin", ".git", ".idea", "node_modules", "evidence"]);
+// Machinery, not work: the chain's own files and the lane's outputs must not
+// count as "the agent wrote something", or the pulse would corroborate itself.
+const ACTIVITY_SKIP_FILES = new Set([".plan.json", ".request.json", ".plan-history.jsonl", "flight-recorder.jsonl", "approvals.log.jsonl", ".DS_Store"]);
+// Nothing written for this long, with no lane or render running, is a stall
+// worth naming — the human is watching a strip that has stopped moving.
+export const ACTIVITY_STALL_MS = 10 * 60 * 1000;
+
+/**
+ * Files written under the working roots since `sinceIso` — the request stamp.
+ * Pure filesystem, no git: a scaffold before `git init` still answers, and a
+ * mtime is a fact regardless of what is staged.
+ * @param {string} root
+ * @param {string|null|undefined} sinceIso the request's `at`
+ * @param {{now?: number}} [opts]
+ * @returns {{filesChanged: number, lastWriteAgoMs: (number|null), since: string}|null}
+ *   null when there is no request to measure from
+ */
+export function observeActivity(root, sinceIso, { now = Date.now() } = {}) {
+  const since = Date.parse(sinceIso ?? "");
+  if (Number.isNaN(since)) return null;
+  let filesChanged = 0;
+  let newest = -Infinity;
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        if (!ACTIVITY_SKIP_DIRS.has(e.name)) walk(path.join(dir, e.name));
+        continue;
+      }
+      if (!e.isFile() || ACTIVITY_SKIP_FILES.has(e.name)) continue;
+      let m;
+      try {
+        m = fs.statSync(path.join(dir, e.name)).mtimeMs;
+      } catch {
+        continue;
+      }
+      if (m > since) {
+        filesChanged += 1;
+        if (m > newest) newest = m;
+      }
+    }
+  };
+  for (const rel of ACTIVITY_ROOTS) walk(path.join(root, rel));
+  return {
+    filesChanged,
+    lastWriteAgoMs: filesChanged > 0 ? Math.max(0, now - newest) : null,
+    since: new Date(since).toISOString(),
+  };
+}
+
 /**
  * Everything a chain-rendering surface needs, with provenance attached:
  * request (tier 1) + plan with its age (tier 2) + what is ACTUALLY running
- * (tier 3 — the markers the lane and preview daemon already stamp).
+ * (tier 3 — the markers the lane and preview daemon already stamp, the lane's
+ * now carrying its own step narration) + the local trail of closed chains
+ * (N5). `busy.lane`/`busy.render` are truthy objects while fresh — existing
+ * truthiness consumers keep working unchanged.
  * @returns {{request: (object|null), plan: (object|null), planAgeMs: (number|null),
- *   busy: {lane: boolean, render: boolean}}}
+ *   busy: {lane: (object|false), render: (object|false)}, history: object[]}}
  */
 export function deriveChain(root) {
   const plan = readPlan(root);
   const at = plan ? Date.parse(plan.updatedAt) : NaN;
+  const busy = {
+    lane: markerInfo(root, ".cmp-lane-in-progress"),
+    render: markerInfo(root, ".cmp-render-in-progress"),
+  };
+  const request = readRequest(root);
+  // S3: the build stage's observed tier — writes since the request began.
+  const activity = observeActivity(root, request ? request.at : null);
   return {
-    request: readRequest(root),
+    request,
     plan,
     planAgeMs: Number.isNaN(at) ? null : Math.max(0, Date.now() - at),
-    busy: {
-      lane: markerFresh(root, ".cmp-lane-in-progress"),
-      render: markerFresh(root, ".cmp-render-in-progress"),
-    },
+    busy,
+    activity,
+    // Pre-rendered so every surface (chat, CLI, studio) speaks the observed
+    // tier in identical words — the console renders this string, never its
+    // own paraphrase of the marker.
+    busyText: describeBusy(busy, Date.now(), activity),
+    history: readPlanHistory(root, 5),
   };
 }
 
@@ -172,29 +361,106 @@ export function formatAge(ms) {
   return `${Math.round(ms / 3600000)}h ago`;
 }
 
+/** "12s" / "~3 min" — a plain duration (formatAge's sibling, no "ago"). */
+export function formatDuration(ms) {
+  if (!(ms >= 0)) return "";
+  if (ms < 120000) return `${Math.max(1, Math.round(ms / 1000))}s`;
+  return `~${Math.round(ms / 60000)} min`;
+}
+
+/** A done step's wall time from its own N1 stamps, or null pre-N1. */
+function stepDurationMs(s) {
+  const a = Date.parse(s.startedAt ?? "");
+  const b = Date.parse(s.doneAt ?? "");
+  return Number.isNaN(a) || Number.isNaN(b) ? null : Math.max(0, b - a);
+}
+
+/**
+ * The tier-3 corroboration as one phrase (N2): the lane's own narration when
+ * the marker carries it ("full check — unitTests (10/16) · 12s of ~3s,
+ * usually ~52s total"), the legacy phrase when it does not. "" when nothing
+ * is running. Shared by the text and HTML renderers so the observed tier
+ * speaks identically everywhere.
+ */
+export function describeBusy(busy, now = Date.now(), activity = null) {
+  if (!busy) return describeActivity(activity);
+  const lane = busy.lane;
+  if (lane) {
+    if (typeof lane === "object" && typeof lane.step === "string" && lane.step !== "") {
+      const pos = Number.isInteger(lane.index) && Number.isInteger(lane.total) ? ` (${lane.index}/${lane.total})` : "";
+      const started = Date.parse(lane.stepStartedAt ?? "");
+      const elapsed = Number.isNaN(started) ? null : Math.max(0, now - started);
+      const stepExpect = typeof lane.expectedStepMs === "number" && lane.expectedStepMs > 0 ? ` of ~${formatDuration(lane.expectedStepMs)}` : "";
+      const laneExpect =
+        typeof lane.expectedLaneMs === "number" && lane.expectedLaneMs > 0 ? `, usually ${formatDuration(lane.expectedLaneMs)} total` : "";
+      return `full check — ${lane.step}${pos}${elapsed !== null ? ` · ${formatDuration(elapsed)}${stepExpect}` : ""}${laneExpect}`;
+    }
+    return "the full check is running NOW";
+  }
+  if (busy.render) return "a preview render is in flight";
+  // Nothing mechanical is running — but the working tree may still be moving.
+  return describeActivity(activity);
+}
+
+/**
+ * The build stage's phrase (S3). Files written since the request, and how
+ * long ago the last one landed; a stall when the tree has stopped moving.
+ * "" when there is no request to measure from, or nothing has happened yet.
+ */
+export function describeActivity(activity) {
+  if (!activity) return "";
+  if (activity.filesChanged === 0) return "";
+  const n = activity.filesChanged;
+  const ago = activity.lastWriteAgoMs;
+  const files = `${n} file${n === 1 ? "" : "s"} written since the request`;
+  if (typeof ago === "number" && ago >= ACTIVITY_STALL_MS) return `${files} · stalled — nothing written for ${formatDuration(ago)}`;
+  return typeof ago === "number" ? `${files} · last ${formatDuration(ago)} ago` : files;
+}
+
 /**
  * The chain as one text block — the CLI's and the inject's rendering.
- * Numbered steps: done ✓, current ◉ (with tier-3 corroboration when a lane
- * or render is genuinely in flight), pending ○. "" when nothing is declared
- * AND no request is recorded (silence, never an empty frame).
+ * Numbered steps: done ✓ with wall time, current ◉ with elapsed, pending ○
+ * (N1); the tier-3 corroboration is prefixed "observed:" so the machine's
+ * word is visibly distinct from the agent's declaration (N3). "" when
+ * nothing is declared AND no request is recorded (silence, never an empty
+ * frame).
  */
 export function renderChain(chain) {
   if (!chain || (!chain.plan && !chain.request)) return "";
+  const now = Date.now();
   const lines = [];
   const title = chain.plan?.title ?? chain.request?.text ?? null;
   if (title) lines.push(`Request: ${title}`);
   if (chain.plan) {
     const p = chain.plan;
     const seq = p.steps
-      .map((s) => `${s.done ? "✓" : s.n === p.current ? "◉" : "○"} ${s.n}. ${s.label}`)
+      .map((s) => {
+        if (s.done) {
+          const d = stepDurationMs(s);
+          return `✓ ${s.n}. ${s.label}${d !== null ? ` (${formatDuration(d)})` : ""}`;
+        }
+        if (s.n === p.current) {
+          const a = Date.parse(s.startedAt ?? "");
+          return `◉ ${s.n}. ${s.label}${Number.isNaN(a) ? "" : ` · ${formatDuration(Math.max(0, now - a))} in`}`;
+        }
+        return `○ ${s.n}. ${s.label}`;
+      })
       .join("  →  ");
     lines.push(seq);
     const cur = p.steps.find((s) => s.n === p.current) ?? null;
-    const busy = chain.busy?.lane ? " · the full check is running NOW" : chain.busy?.render ? " · a preview render is in flight" : "";
+    const busyText = typeof chain.busyText === "string" ? chain.busyText : describeBusy(chain.busy, now, chain.activity ?? null);
+    const busy = busyText !== "" ? ` · observed: ${busyText}` : "";
     const age = chain.planAgeMs !== null ? ` · declared by the agent, updated ${formatAge(chain.planAgeMs)}` : "";
     lines.push(cur ? `now: step ${cur.n} of ${p.steps.length} — ${cur.label}${busy}${age}` : `chain complete${busy}${age}`);
   } else {
     lines.push("(no declared chain for this request yet — node qa/plan.mjs --set \"step | step | …\")");
+    // S3: an undeclared chain is no longer a still photo. The observed tier —
+    // a running lane, a render, or writes since the request — is printed even
+    // when the agent declared nothing, because it is the machine's word and
+    // needs no declaration to exist. This is the case that used to show nothing
+    // for forty minutes.
+    const observed = typeof chain.busyText === "string" ? chain.busyText : describeBusy(chain.busy, Date.now(), chain.activity ?? null);
+    if (observed !== "") lines.push(`observed: ${observed}`);
   }
   return lines.join("\n");
 }

package/template/qa/lib/receipt-validate.mjs

@@ -45,6 +45,51 @@ export function readReceipt(root, relPath = RECEIPT_REL_PATH) {
  *   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}}}
  */
+/**
+ * Does this receipt's own row-level evidence support its PASS?
+ *
+ * The receipt is necessarily excluded from the inputs hash it carries — a file
+ * cannot hash itself — so steps[] is the only thing between this gate and a text
+ * editor, and the top-level verdict is the most editable field on it.
+ *
+ * Two failures this catches, both observed downstream (payment-blueprint F2/F3):
+ * a receipt whose verdict was hand-edited from FAIL to PASS while its rows still
+ * said otherwise, and a lane made green by DELETING harness.lock.json, which
+ * downgraded harnessIntegrity from FAIL to SKIP and took the lane's verdict with
+ * it — a lane vouching for a tree with nothing vouching for the lane.
+ *
+ * @param {{verdict?: string, steps?: Array<{name?: string, verdict?: string}>}} receipt
+ * @returns {{ok: boolean, detail: string}}
+ */
+export function checkLaneVouching(receipt) {
+  const steps = Array.isArray(receipt?.steps) ? receipt.steps : null;
+  if (!steps || steps.length === 0) {
+    return { ok: false, detail: "receipt lists no verify-lane steps — a PASS over nothing attests nothing" };
+  }
+  const failed = steps.filter((s) => s && (s.verdict === "FAIL" || s.verdict === "ERROR"));
+  if (failed.length > 0) {
+    const names = failed.map((s) => `${s.name ?? "?"} (${s.verdict})`).join(", ");
+    return {
+      ok: false,
+      detail: `the receipt's verdict is PASS but ${failed.length} step(s) did not pass: ${names} — the row is the more specific truth`,
+    };
+  }
+  const integrity = steps.find((s) => s && s.name === "harnessIntegrity");
+  if (!integrity) {
+    return {
+      ok: false,
+      detail: "receipt has no harnessIntegrity row — nothing vouches that the lane's own code is the code that ran",
+    };
+  }
+  if (integrity.verdict !== "PASS") {
+    return {
+      ok: false,
+      detail: `harnessIntegrity is ${integrity.verdict}, not PASS — the lane did not vouch for itself, so its PASS over the tree cannot be trusted`,
+    };
+  }
+  return { ok: true, detail: "lane vouched for itself (harnessIntegrity PASS, no failing rows)" };
+}
+
 export function evaluateReceipt(receipt, recompute) {
   const profile = receipt.profile;
 
@@ -83,6 +128,13 @@ export function evaluateReceipt(receipt, recompute) {
     };
   }
 
+  // Did the lane vouch for ITSELF? See checkLaneVouching — the top-level verdict
+  // is the most editable field on a file the hash cannot cover.
+  const vouching = checkLaneVouching(receipt);
+  if (!vouching.ok) {
+    return { valid: false, reason: `${vouching.detail} (attesting profile: ${profile ?? "unknown"})`, profile, recomputed };
+  }
+
   return { valid: true, reason: `receipt is valid — PASS, attesting profile: ${profile ?? "unknown"}`, profile, recomputed };
 }
 
@@ -134,7 +186,10 @@ export function checkExecutionPlausibility(receipt, { minExecutedMs = DEFAULT_PO
   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");
+  // Executed = produced a verdict about the tree. SKIP did not try; ERROR
+  // tried and could not (a deadline, zero tests, a throw) — neither measured
+  // anything, so neither counts toward "this lane verified something".
+  const executed = steps.filter((s) => s && s.verdict !== "SKIP" && s.verdict !== "ERROR");
   if (executed.length === 0) {
     return { ok: false, detail: "every step in the receipt is a SKIP — the lane verified nothing" };
   }

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

@@ -14,8 +14,94 @@ 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,})\*\*/;
+// An OPTIONAL tier requirement on the clause line itself:
+//
+//   - **MOTION-13** [tier: device] — Given a cold start, When … Then …
+//
+// The clause declares what it takes to OBSERVE it, which is a property of the
+// promise, not of whatever test happened to cite it. Note this attaches to the
+// clause line, not to `[enforced: …]` — that tags docs/ARCHITECTURE.md prose and
+// is a different grammar entirely.
+const CLAUSE_TIER_RE = /\[tier:\s*(device|e2e)\]/i;
+/** Which citing tiers satisfy a declared requirement. */
+export const TIERS_SATISFYING = Object.freeze({
+  device: ["androidInstrumentedTest", "e2e"],
+  e2e: ["e2e"],
+});
 
 const TAG_LINE_RE = /^(?:\/\/|#)\s*SPEC:/;
+
+// A citation is a claim that a TEST covers a clause, so it has to sit on one.
+// Counting the tag wherever it appears makes a red specCoverage curable with a
+// comment and zero assertions — the one escape this gate exists to close. It is
+// not hypothetical: payment-blueprint hit a citation that had drifted onto a
+// class declaration, where it counted for the whole file while testing nothing.
+//
+// So a tag counts only when a test declaration follows it within
+// BINDING_WINDOW non-blank lines. The window is small enough that the tag must
+// be attached to the test, and loose enough for the @DisplayName / annotation
+// stack that idiomatically sits between them.
+export const BINDING_WINDOW = 5;
+
+// Kotlin @Test, a backticked test function, and the node:test / Maestro-adjacent
+// `test(` / `it(` call forms. Deliberately syntactic: a citation's binding must
+// be readable without compiling anything.
+const TEST_DECL_RE = /@Test\b|\bfun\s+`[^`]+`\s*\(|\b(?:test|it)\s*\(/;
+
+// A tag whose first meaningful line declares a TYPE is documenting that type,
+// not claiming a test — and it must be refused structurally rather than by
+// distance, because a short class body puts a real @Test inside the window and
+// would otherwise launder the citation. This is exactly payment-blueprint's
+// drift: `// SPEC: PP-07` sat on `class PaymentWorkerTest`, three properties
+// above a genuine @Test, and vouched for the whole file.
+const TYPE_DECL_RE = /^(?:@\w+\s+)*(?:public\s+|internal\s+|private\s+|abstract\s+|open\s+|sealed\s+|data\s+|enum\s+)*(?:class|object|interface)\b/;
+
+// A YAML flow's own shape counts as its test: a Maestro file IS the test, so a
+// tag in one binds to the flow rather than to a declaration inside it.
+const FLOW_EXTS = [".yaml", ".yml"];
+
+/**
+ * Does a test declaration follow `index` within BINDING_WINDOW non-blank lines,
+ * skipping block-comment bodies (a tag inside one is documentation, not a claim)?
+ * @param {string[]} lines
+ * @param {number} index line the tag sits on
+ * @returns {boolean}
+ */
+export function citationIsBound(lines, index) {
+  let seen = 0;
+  let inBlockComment = false;
+  for (let i = index + 1; i < lines.length && seen < BINDING_WINDOW; i += 1) {
+    const line = lines[i].trim();
+    if (line === "") continue;
+    if (inBlockComment) {
+      if (line.includes("*/")) inBlockComment = false;
+      continue;
+    }
+    if (line.startsWith("/*")) {
+      if (!line.includes("*/")) inBlockComment = true;
+      continue;
+    }
+    if (line.startsWith("//") || line.startsWith("*")) continue;
+    seen += 1;
+    // The FIRST meaningful line decides whether this tag is on a test at all.
+    if (seen === 1 && TYPE_DECL_RE.test(line)) return false;
+    if (TEST_DECL_RE.test(line)) return true;
+  }
+  return false;
+}
+
+/** Is this tag inside a block comment that began earlier in the file? */
+function insideBlockComment(lines, index) {
+  let open = false;
+  for (let i = 0; i < index; i += 1) {
+    const line = lines[i];
+    for (let c = 0; c < line.length - 1; c += 1) {
+      if (!open && line[c] === "/" && line[c + 1] === "*") open = true;
+      else if (open && line[c] === "*" && line[c + 1] === "/") open = false;
+    }
+  }
+  return open;
+}
 const TAG_IDS_RE = /SPEC:\s*([A-Z0-9,\s-]+)/;
 const CLAUSE_ID_RE = /^[A-Z][A-Z0-9]*-\d{2,}$/;
 
@@ -45,7 +131,12 @@ export function scanSpecClauses(root) {
     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]) });
+      const tierMatch = line.match(CLAUSE_TIER_RE);
+      clauses.set(m[2], {
+        file: path.relative(root, abs),
+        withdrawn: Boolean(m[1]),
+        requiredTier: tierMatch ? tierMatch[1].toLowerCase() : null,
+      });
     }
   }
   return clauses;
@@ -86,11 +177,14 @@ export function scanCitations(root) {
     const tier = tierForFile(rel);
     fs.readFileSync(f, "utf8")
       .split("\n")
-      .forEach((line, i) => {
+      .forEach((line, i, lines) => {
         const trimmed = line.trim();
         if (!TAG_LINE_RE.test(trimmed)) return;
         const m = trimmed.match(TAG_IDS_RE);
         if (!m) return;
+        // A flow file IS its test; anything else must have a test under the tag.
+        const isFlow = FLOW_EXTS.some((ext) => rel.endsWith(ext));
+        if (!isFlow && (insideBlockComment(lines, i) || !citationIsBound(lines, i))) return;
         const ids = m[1]
           .split(/[,\s]+/)
           .map((s) => s.trim())
@@ -108,6 +202,9 @@ export function scanCitations(root) {
  * (commonTest/desktopTest) — behavior claims no device-tier evidence backs.
  * `summaryLine` is the one line the lane's specCoverage step (and any other
  * consumer) can print verbatim; null when nothing is desktop-only.
+ * `unmetTier` is the PRESCRIPTIVE half — clauses that declared `[tier: …]` and
+ * have no citation from a tier that could observe them. specCoverage FAILS on it:
+ * "instrument before you police" was the right first move, and this is the second.
  * @param {Map<string, {file: string, withdrawn: boolean}>} clauses from scanSpecClauses
  * @param {Array<{id: string, tier: string}>} tags from scanCitations
  * @returns {{tiersByClause: Record<string, string[]>, desktopOnly: string[], summaryLine: string|null}}
@@ -117,6 +214,17 @@ export function clauseTierCoverage(clauses, tags) {
   for (const t of tags) {
     (tiersByClause[t.id] ??= []).includes(t.tier) || tiersByClause[t.id].push(t.tier);
   }
+  // The gate input. A clause that DECLARED the tier it needs and has no citation
+  // from that tier is not covered — it is cited by tests structurally incapable
+  // of observing it, which is the exact hole `desktopOnly` below could only ever
+  // describe. MOTION-13 promised an animation "plays once per process start" and
+  // was cited by a desktop Compose test, a tier with no process lifecycle at all:
+  // the citation existed, the gate went green, and nothing ever observed the
+  // promise. Declared requirements are checked; undeclared clauses are unchanged.
+  const unmetTier = [...clauses.entries()]
+    .filter(([, c]) => !c.withdrawn && c.requiredTier)
+    .map(([id, c]) => ({ id, requiredTier: c.requiredTier, tiers: tiersByClause[id] ?? [], file: c.file }))
+    .filter((u) => !(TIERS_SATISFYING[u.requiredTier] ?? []).some((t) => u.tiers.includes(t)));
   const desktopOnly = [...clauses.entries()]
     .filter(([, c]) => !c.withdrawn)
     .map(([id]) => id)
@@ -127,5 +235,5 @@ export function clauseTierCoverage(clauses, tags) {
   const summaryLine = desktopOnly.length
     ? `${desktopOnly.length} clause${desktopOnly.length === 1 ? "" : "s"} cited only from desktop-tier tests (${desktopOnly.join(", ")})`
     : null;
-  return { tiersByClause, desktopOnly, summaryLine };
+  return { tiersByClause, desktopOnly, unmetTier, summaryLine };
 }

package/template/qa/lib/step-cache.mjs

@@ -138,7 +138,7 @@ export function loadStepCache(root) {
 export function lookupCachedPass(root, stepName, inputsHash) {
   const entry = loadStepCache(root).steps[stepName];
   if (!entry || typeof entry !== "object") return null;
-  if (entry.verdict !== "PASS") return null; // FAIL/SKIP are never reused
+  if (entry.verdict !== "PASS") return null; // FAIL/SKIP/ERROR are never reused
   if (typeof inputsHash !== "string" || entry.inputsHash !== inputsHash) return null;
   if (typeof entry.at !== "string") return null;
   return entry;