create-cmp-cli 0.23.0 → 0.25.0

package/template/qa/harness-manifest.json

@@ -0,0 +1,10 @@
+{
+  "schema": "harness-manifest/2",
+  "profile": { "id": "cmp" },
+  "receipt": "qa/evidence/latest.json",
+  "architectureDoc": "docs/ARCHITECTURE.md",
+  "specs": "specs",
+  "citationRoots": ["composeApp/src", "qa/e2e"],
+  "approvals": "qa/approvals.json",
+  "packs": ["cmp"]
+}

package/template/qa/lib/a11y.mjs

@@ -21,7 +21,7 @@
 // Trees produced before the role/clickable/disabled contract extension are handled
 // gracefully: nodes without `clickable` are simply skipped, never crashed on.
 
-import { walk } from "./tree.mjs";
+import { walk } from "./profiles/cmp/tree.mjs";
 
 /**
  * Audit a tree for accessibility faults.

package/template/qa/lib/affected-tests.mjs

@@ -14,11 +14,18 @@
 //     and the caller reports which case it was in the step's output and the
 //     receipt, so a filtered run can never be mistaken for the full suite.
 //   - The BLAST-RADIUS ESCAPE HATCH is mandatory: some paths fan out too
-//     widely to subset safely (build files rewire compilation, DI rewires
-//     object graphs, theme/tokens and shared components render into every
-//     screen, qa/ is the harness judging itself, and anything outside
-//     composeApp/src is by definition not a scoped source edit). Any one such
-//     change disables filtering for the run.
+//     widely to subset safely. qa/ is the harness judging itself — that one is
+//     the core's, on every stack. WHICH OTHER paths fan out, and how a changed
+//     source maps to a test filter, are facts about one build tool and one
+//     source layout, so they come from the PROFILE (Stage 0 PR 6d;
+//     profiles/cmp/affected.mjs). Any one broad-impact change disables
+//     filtering for the run.
+//
+// A profile that supplies no mapping gets `mode: "all"` with that as the
+// reason — fail open, said out loud. Vendored into a repo whose sources are
+// not under composeApp/src, the old hardcoded rules did something worse than
+// nothing: every path failed the layout test, so every fast run fell open to
+// the full suite with the optimisation silently off.
 //
 // Pure functions over path lists — git access is injected/separate so the
 // engine suite can test every branch with no repo state.
@@ -43,50 +50,37 @@ import path from "node:path";
 // first fell open to the full suite, visible only in one parenthetical.
 // Found by payment-blueprint's spine adoption (2026-09-03), where the same
 // line also landed in their locked region.
-export const LANE_OUTPUT_PREFIXES = ["qa/evidence", "qa-artifacts", "qa/flight-recorder.jsonl"];
+// qa/.lane-in-progress is the lane's own marker (qa/lib/lane-markers.mjs) —
+// present, untracked, for exactly the duration of the run that would read it.
+export const LANE_OUTPUT_PREFIXES = ["qa/evidence", "qa-artifacts", "qa/flight-recorder.jsonl", "qa/.lane-in-progress"];
 
 function isLaneOutput(p) {
   return LANE_OUTPUT_PREFIXES.some((prefix) => p === prefix || p.startsWith(`${prefix}/`));
 }
 
 /**
- * The mandatory blast-radius escape hatch: paths whose change fans out too
- * widely to subset the suite safely. Returns the human-readable category when
- * `p` is broad-impact, else null. Checked in order; the first match names the
- * reason.
+ * The core's own blast-radius rule, on every stack: a change under qa/ is the
+ * harness judging itself, so nothing may be subsetted by it.
  * @param {string} p POSIX relpath from the project root
  * @returns {string|null}
  */
-export function broadImpactReason(p) {
-  if (p.endsWith(".gradle.kts") || p === "gradle.properties" || p === "gradle/libs.versions.toml") {
-    return "build files rewire compilation";
-  }
-  if (/(^|\/)di\//.test(p)) return "DI rewires the object graph";
-  if (/(^|\/)theme\//.test(p)) return "theme/tokens render into every screen";
-  if (p.includes("presentation/components/")) return "shared components render into every screen";
+export function coreBroadImpactReason(p) {
   if (p === "qa" || p.startsWith("qa/")) return "qa/ is the harness itself";
-  if (!p.startsWith("composeApp/src/")) return "outside composeApp/src";
   return null;
 }
 
 /**
  * Derive the fast-mode unit-test filter from a list of changed paths.
  *
- * Mapping (deliberately simple and defensible): each changed `.kt` file under
- * composeApp/src contributes its package's last segment — the parent
- * directory name (`…/presentation/home/HomeViewModel.kt` → `home`, which the
- * template's package-mirrors-path conformance makes a package segment) — and
- * the union becomes Gradle `--tests "*<seg>*"` patterns matched against test
- * class FQNs. Coarse on purpose: `*home*` runs every test whose FQN mentions
- * the feature, which over-selects a little and under-maintains nothing.
- *
  * @param {string[]} changedPaths relpaths (either separator style) — tracked
  *   diffs plus untracked files, as from changedWorkingTreePaths()
+ * @param {{broadImpact: (p: string) => (string|null), patternsFor: (paths: string[]) => {patterns: string[], sourcePaths: string[]}}} [mapping]
+ *   the profile's rules (profiles/<id>/affected.mjs). Absent = no subsetting.
  * @returns {{mode: "filtered", patterns: string[], sourcePaths: string[]} |
  *   {mode: "all", reason: string, patterns: [], sourcePaths: string[]}}
  *   mode "all" ALWAYS carries the honest reason to report.
  */
-export function deriveAffectedFilter(changedPaths) {
+export function deriveAffectedFilter(changedPaths, mapping = null) {
   const paths = [...new Set((changedPaths ?? [])
     .filter((p) => typeof p === "string" && p.length > 0)
     .map((p) => p.split(path.sep).join("/")))]
@@ -97,32 +91,93 @@ export function deriveAffectedFilter(changedPaths) {
     return { mode: "all", reason: "no working-tree changes to scope by", patterns: [], sourcePaths: [] };
   }
 
+  // No mapping, no subsetting — and the reason says which half is missing, so
+  // a profile author sees the optimisation is off rather than wondering why
+  // the fast lane costs what the full one does.
+  if (!mapping || typeof mapping.broadImpact !== "function" || typeof mapping.patternsFor !== "function") {
+    return { mode: "all", reason: "this profile declares no affected-test mapping — every fast run tests everything", patterns: [], sourcePaths: paths };
+  }
+
   for (const p of paths) {
-    const broad = broadImpactReason(p);
+    const broad = coreBroadImpactReason(p) ?? mapping.broadImpact(p);
     if (broad) {
       return { mode: "all", reason: `broad-impact change — ${broad} (${p})`, patterns: [], sourcePaths: paths };
     }
   }
 
-  // Every remaining path is a scoped file under composeApp/src. Only .kt
-  // files map to test patterns; a change that maps to nothing (resources,
-  // manifests) falls open to the full suite below.
-  const ktPaths = paths.filter((p) => p.endsWith(".kt"));
-  const segments = new Set();
-  for (const p of ktPaths) {
-    const seg = path.posix.basename(path.posix.dirname(p));
-    if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(seg)) segments.add(seg);
-  }
-
-  if (segments.size === 0) {
+  // Every remaining path is a scoped source edit by the profile's own reckoning.
+  // A change that maps to no pattern (resources, manifests) falls open below.
+  const { patterns, sourcePaths } = mapping.patternsFor(paths);
+  if (!Array.isArray(patterns) || patterns.length === 0) {
     return { mode: "all", reason: "changed files map to no test filter", patterns: [], sourcePaths: paths };
   }
 
-  return {
-    mode: "filtered",
-    patterns: [...segments].sort().map((s) => `*${s}*`),
-    sourcePaths: ktPaths,
-  };
+  return { mode: "filtered", patterns, sourcePaths: Array.isArray(sourcePaths) ? sourcePaths : paths };
+}
+
+/**
+ * Must the expensive tier run for this change?
+ *
+ * The most costly thing an agent does is run a device or journey tier — minutes
+ * of emulator, build and flow — to prove something about a change that tier
+ * cannot see. Running it anyway is not rigour, it is latency, and latency is
+ * how an agent ends up CLAIMING instead of deriving (G1, G2).
+ *
+ * THE DECLARATION IS OF IRRELEVANCE, NOT OF RELEVANCE, and getting that
+ * backwards turns this into the defect it prevents. The first version of this
+ * function asked "is any changed path under a root that FEEDS the tier?" and
+ * answered "not required" when none matched — an allowlist, so anything nobody
+ * thought to list was silently deferred. `cmp` declares
+ * `sourceRoots: ["composeApp/src"]`, which excludes `build.gradle.kts` and
+ * `gradle/libs.versions.toml` — both of which absolutely change what runs on a
+ * device. A dependency bump would have skipped the device tier and said so
+ * confidently (ADR-0009, "what would make this wrong").
+ *
+ * So: the tier RUNS unless every changed path is under something explicitly
+ * declared unable to affect it. A path nobody classified obliges the tier,
+ * which is the safe direction — being wrong toward running costs minutes, being
+ * wrong toward deferring costs a regression nobody saw.
+ *
+ * This does not skip anything; it answers a question and always carries the
+ * reason, so a caller can record it and a reader can disagree with it. An
+ * unrecorded skip is a lie; a recorded one is evidence.
+ *
+ * @param {string[]|null} changedPaths relpaths, or null when git could not say
+ * @param {{irrelevantRoots?: string[], tierName?: string}} [decl] paths declared
+ *   unable to affect the tier: a `dir/` prefix, or a `*.ext` suffix
+ * @returns {{required: boolean, reason: string, obliging: string[]}}
+ */
+export function deriveTierNeed(changedPaths, { irrelevantRoots = [], tierName = "the device tier" } = {}) {
+  if (!Array.isArray(changedPaths)) {
+    return { required: true, reason: `cannot tell what changed — ${tierName} runs`, obliging: [] };
+  }
+  const paths = changedPaths
+    .filter((p) => typeof p === "string" && p.length > 0)
+    .map((p) => p.split(path.sep).join("/"))
+    .filter((p) => !isLaneOutput(p));
+  if (paths.length === 0) {
+    return { required: true, reason: `no change to reason about — ${tierName} runs`, obliging: [] };
+  }
+  // The harness judging itself is always broad impact — the same rule the
+  // fast-lane filter uses, so the two cannot disagree about the same edit.
+  const core = paths.find((p) => coreBroadImpactReason(p));
+  if (core) {
+    return { required: true, reason: `broad-impact change — ${coreBroadImpactReason(core)} (${core})`, obliging: [core] };
+  }
+  const declared = (irrelevantRoots ?? []).filter((r) => typeof r === "string" && r.length > 0);
+  if (declared.length === 0) {
+    return { required: true, reason: `nothing is declared unable to affect ${tierName} — it runs`, obliging: paths };
+  }
+  const isIrrelevant = (p) =>
+    declared.some((r) => (r.startsWith("*.") ? p.endsWith(r.slice(1)) : p === r.replace(/\/$/, "") || p.startsWith(r.endsWith("/") ? r : `${r}/`)));
+  const obliging = paths.filter((p) => !isIrrelevant(p));
+  return obliging.length > 0
+    ? {
+        required: true,
+        reason: `${obliging.length} changed path(s) are not declared irrelevant to ${tierName}: ${obliging.slice(0, 3).join(", ")}${obliging.length > 3 ? ", …" : ""}`,
+        obliging,
+      }
+    : { required: false, reason: `every changed path is declared unable to affect ${tierName} (${declared.join(", ")})`, obliging: [] };
 }
 
 function defaultRunGit(args, root) {

package/template/qa/lib/agent-hold.mjs

@@ -0,0 +1,234 @@
+// agent-hold.mjs — "an agent is working in this tree right now."
+//
+// TWO PROBLEMS, ONE MISSING FACT. Both were reported from payment-blueprint's
+// adoption on 2026-09-04, and both are the same absence:
+//
+//   1. LIVENESS. There was no way to answer "is the agent working, or wedged?"
+//      without filesystem archaeology. The lead architect guessed twice with two
+//      separately broken instruments — a `find` that excluded `build/` (the only
+//      directory a proof run writes to) and a `find -newermt` that reported zero
+//      writes in 45 minutes while `ls -lT` showed one at 10 — and on the first
+//      guess killed a healthy agent mid-proof. An instrument that cannot see the
+//      thing it exists to detect is worse than no instrument: it is confidently
+//      wrong, which is the same failure class GATE-RULES Rule 1 exists for.
+//
+//   2. FALSE ALARMS. The Stop hook fires identically whether a receipt is stale
+//      because nobody ran the lane or because a subagent is mid-commit on a
+//      half-adopted port. It fired ~15 times in one evening while the correct
+//      action every time was to WAIT. Anthropic's tool-design guidance is
+//      explicit that an error must communicate "specific and actionable
+//      improvements"; an alarm whose advice is wrong every time it fires trains
+//      its reader to ignore it, which is strictly worse than silence.
+//
+// WHAT THIS IS NOT. It is not a lock — nothing waits on it, nothing is excluded
+// by it. It is not a second journal: the flight recorder still owns lane history
+// that belongs in the repo. It is a DECLARATION with an expiry, in the same
+// ephemeral, gitignored, hash-excluded family as qa/.plan.json and
+// qa/.request.json — because a fact about who is typing must never be able to
+// invalidate a receipt.
+//
+// A HOLD CHANGES THE ADVICE, NEVER THE VERDICT. The Stop hook still refuses:
+// no receipt yet means not done, and a file an agent writes about itself must
+// never be able to end a turn — that would be turning the gate off by writing a
+// file, which is the attack the whole harness exists to refuse. This follows the
+// precedent already set for a lane in flight (qa/receipt-check.mjs): same
+// refusal, different instruction. "Run the lane" is wrong advice when the tree
+// is mid-edit and would not compile, and a gate that tells you to do the thing
+// you are already doing trains you to stop reading it.
+//
+// THE ASYMMETRY THAT KEEPS IT HONEST. A hold EXPLAINS the absence of fresh
+// evidence. It never explains CONTRADICTING evidence. A red receipt, a forged
+// receipt, a skipped device tier: for those the hold is not the reason and
+// saying so would mislead. Only two refusals are explicable by a hold — "no
+// receipt yet" and "the tree moved since a PASSing receipt" — exactly the two
+// states a working agent legitimately produces, and nothing else.
+//
+// SINGLE SOURCE OF TRUTH: packages/harness/src/lib/agent-hold.mjs in the
+// create-cmp repo. The copy in a generated project's qa/lib/ is vendored
+// byte-identical at scaffold time — edit the package source, then run
+// `node scripts/sync-harness.mjs`.
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Ephemeral, gitignored, and excluded from the receipt's hashed input surface
+ * (qa/lib/inputs-hash.mjs EXCLUDED_PREFIXES) — the same family as .plan.json.
+ */
+export const HOLD_REL = "qa/.agent-hold.json";
+
+/**
+ * A heartbeat older than this is a crashed writer, not a live agent. The same
+ * bound every other marker consumer in this lane applies (qa/lib/plan.mjs), for
+ * the same reason: a process that dies leaves its file behind, so freshness —
+ * never presence — is what makes a marker mean anything.
+ */
+export const HEARTBEAT_FRESH_MS = 5 * 60 * 1000;
+
+/**
+ * A hold this old is a wedge, not work. Past the ceiling the hook resumes
+ * blocking even while heartbeats keep arriving: an agent that has held the tree
+ * for three quarters of an hour is exactly the case the human needed to see, and
+ * a heartbeat proves the process is alive, never that it is making progress.
+ */
+export const HOLD_CEILING_MS = 45 * 60 * 1000;
+
+const MAX_TEXT = 200;
+
+const clip = (s, n = MAX_TEXT) => (typeof s === "string" ? s.trim().slice(0, n) : "");
+
+/** Fail-soft like every other status reader here: unreadable reads as absent. */
+export function readHold(root) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(root, ...HOLD_REL.split("/")), "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(root, value) {
+  try {
+    const p = path.join(root, ...HOLD_REL.split("/"));
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, `${JSON.stringify(value, null, 2)}\n`);
+    return { ok: true, hold: value };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * Claim the tree. `holder` is a name a human will read in an alarm — an agent
+ * or session label, not a UUID: Anthropic's tool guidance is that agents (and
+ * the people reading after them) do far better with natural-language
+ * identifiers than with opaque ids, and this string's whole job is to be read
+ * at 3am by someone deciding whether to kill a process.
+ */
+export function claimHold(root, { holder, note = "", now = Date.now() } = {}) {
+  const name = clip(holder, 80) || "an agent";
+  const existing = readHold(root);
+  const at = existing && assessHold(existing, now).held ? existing.at : new Date(now).toISOString();
+  return writeJson(root, {
+    holder: name,
+    note: clip(note),
+    at,
+    heartbeatAt: new Date(now).toISOString(),
+  });
+}
+
+/**
+ * Still here, still working. Optionally re-states what "here" means — an agent
+ * that only says "alive" is barely better than the `find` that started this.
+ */
+export function beatHold(root, { note, now = Date.now() } = {}) {
+  const existing = readHold(root);
+  if (!existing) return { ok: false, error: "no hold to beat — claim one first" };
+  return writeJson(root, {
+    ...existing,
+    note: note === undefined ? existing.note : clip(note),
+    heartbeatAt: new Date(now).toISOString(),
+  });
+}
+
+export function releaseHold(root) {
+  try {
+    fs.rmSync(path.join(root, ...HOLD_REL.split("/")), { force: true });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+/**
+ * Is a hold in force, and what does it say?
+ *
+ * Every negative branch names WHY, because this feeds an alarm's text: "no
+ * agent holds the tree" and "an agent claimed it 50 minutes ago and is past the
+ * ceiling" call for opposite actions by the human reading them.
+ *
+ * @param {object|null} hold
+ * @param {number} now
+ * @returns {{held: boolean, reason: string, holder?: string, note?: string,
+ *            heldMs?: number, sinceBeatMs?: number, expired?: boolean}}
+ */
+export function assessHold(hold, now = Date.now()) {
+  if (!hold || typeof hold !== "object") return { held: false, reason: "no agent holds the tree" };
+  const at = Date.parse(hold.at);
+  const beat = Date.parse(hold.heartbeatAt ?? hold.at);
+  if (Number.isNaN(at) || Number.isNaN(beat)) return { held: false, reason: "the hold file has no readable timestamp" };
+
+  const heldMs = Math.max(0, now - at);
+  const sinceBeatMs = Math.max(0, now - beat);
+  const holder = clip(hold.holder, 80) || "an agent";
+  const note = clip(hold.note);
+  const base = { holder, note, heldMs, sinceBeatMs };
+
+  if (sinceBeatMs > HEARTBEAT_FRESH_MS) {
+    return {
+      ...base,
+      held: false,
+      expired: true,
+      reason: `${holder} last checked in ${formatAge(sinceBeatMs)} — that is a crashed writer, not a live agent`,
+    };
+  }
+  if (heldMs > HOLD_CEILING_MS) {
+    return {
+      ...base,
+      held: false,
+      expired: true,
+      reason: `${holder} has held the tree for ${formatAge(heldMs)}, past the ${formatAge(HOLD_CEILING_MS)} ceiling — a heartbeat proves the process is alive, not that it is progressing`,
+    };
+  }
+  return { ...base, held: true, reason: `${holder} has held the tree for ${formatAge(heldMs)}` };
+}
+
+/**
+ * The ONE line an alarm prints instead of demanding a lane run. It says who,
+ * since when, what they said they were doing, and what the reader should do —
+ * "specific and actionable", which the alarm it replaces was not.
+ */
+export function describeHold(assessment) {
+  if (!assessment?.held) return null;
+  const what = assessment.note ? ` (${assessment.note})` : "";
+  return (
+    `${assessment.holder} has held this tree for ${formatAge(assessment.heldMs)}${what} — staleness is expected while it works. ` +
+    `Wait for it rather than starting a lane on a half-edited tree; \`node qa/plan.mjs --release\` if it is gone.`
+  );
+}
+
+/**
+ * Does a hold EXPLAIN this refusal? (It never lifts it — see the header.)
+ *
+ * The whitelist is the safety property, and it is deliberately two entries
+ * long. A hold explains why fresh evidence is ABSENT — no receipt yet, or the
+ * tree has moved under one — because those are the two states a working agent
+ * legitimately produces. It never explains a receipt that says something is
+ * wrong: for a FAIL, a forgery, a skipped device tier or an unreadable surface
+ * the hold is simply not the cause, and offering it as one would send the
+ * reader to wait for an agent when the actual problem is a red test. Inverting
+ * this to a blacklist would mean every refusal added later is treated as
+ * agent-explicable by default, which is how an alarm starts lying.
+ *
+ * @param {{valid: boolean, reason?: string}} result
+ * @param {object|null} receipt
+ * @returns {boolean}
+ */
+export function holdExplains(result, receipt) {
+  if (!result || result.valid) return false;
+  // No receipt at all: the agent has not finished enough to run the lane.
+  if (receipt === null || receipt === undefined) return true;
+  // The tree moved under a receipt that itself PASSED — the signature of an
+  // agent mid-edit. A receipt that was not a PASS is contradicting evidence and
+  // is never excused, whatever moved since.
+  return receipt.verdict === "PASS" && /^source changed since the receipt/.test(String(result.reason ?? ""));
+}
+
+/** "40s" / "12 min" / "1h 5m" — freshness a human can weigh at a glance. */
+export function formatAge(ms) {
+  if (!(ms >= 0)) return "an unknown time";
+  if (ms < 90_000) return `${Math.round(ms / 1000)}s`;
+  if (ms < 90 * 60_000) return `${Math.round(ms / 60_000)} min`;
+  const h = Math.floor(ms / 3_600_000);
+  return `${h}h ${Math.round((ms - h * 3_600_000) / 60_000)}m`;
+}