create-cmp-cli 0.24.0 → 0.25.0

package/template/qa/lib/audit-cadence.mjs

@@ -34,7 +34,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 export const AUDITS_REL_PATH = "qa/audits.jsonl";
-export const AUDIT_RECORD_SCHEMA = "cmp-audit-record/1";
+export const AUDIT_RECORD_SCHEMA = "prooflane-audit-record/1";
 
 /** The pseudo-subsystem for Kotlin files directly at the androidMain package root. */
 export const ROOT_SUBSYSTEM = "(root)";

package/template/qa/lib/comments.mjs

@@ -17,7 +17,7 @@
 //   - A MISSING file is tolerated as the empty seed on read (a brand-new project has
 //     no comments yet — that's not corruption) and is created on first write.
 //   - A file that EXISTS but is corrupt (unparsable JSON, wrong shape, or a schema
-//     string that isn't "cmp-comments/1") is NOT tolerated on read — listComments
+//     string this reader does not know) is NOT tolerated on read — listComments
 //     throws a descriptive error instead of returning an empty list. Approvals can
 //     safely treat corruption as "all unreviewed" because that is the conservative
 //     (non-blocking) default; silently reading a broken comments ledger as "no
@@ -30,7 +30,21 @@ import fs from "node:fs";
 import path from "node:path";
 
 export const COMMENTS_REL_PATH = "qa/comments.json";
-export const COMMENTS_SCHEMA = "cmp-comments/1";
+export const COMMENTS_SCHEMA = "prooflane-comments/1";
+
+/**
+ * Every schema name a comments ledger may declare — ADR-0007's enum pattern,
+ * applied where it is load-bearing rather than cosmetic.
+ *
+ * This reader REFUSES an unknown schema by design ("a ledger whose schema we do
+ * not know is not one we may interpret"), which makes it the one artifact in
+ * this rename where getting it wrong destroys user data: an adopter's existing
+ * `cmp-comments/1` ledger would become unreadable, and the comments in it are
+ * theirs, not ours. So the old name stays ACCEPTED for the life of /1 and stops
+ * only being WRITTEN — exactly what ADR-0007 decided for the receipt, for the
+ * same reason: renaming a label must not invalidate what was written under it.
+ */
+export const COMMENTS_SCHEMAS = Object.freeze(["cmp-comments/1", COMMENTS_SCHEMA]);
 
 /** target.type -> the fields addComment requires on `target` for that type. */
 const TARGET_FIELD_REQUIREMENTS = {
@@ -70,9 +84,9 @@ function parseLedger(raw) {
       `${COMMENTS_REL_PATH} has an unexpected shape (expected {schema, comments: [...]}) — refusing to read it as a ledger.`,
     );
   }
-  if (parsed.schema !== undefined && parsed.schema !== COMMENTS_SCHEMA) {
+  if (parsed.schema !== undefined && !COMMENTS_SCHEMAS.includes(parsed.schema)) {
     throw new Error(
-      `${COMMENTS_REL_PATH} declares schema "${parsed.schema}", expected "${COMMENTS_SCHEMA}" — refusing to read an unknown-schema ledger.`,
+      `${COMMENTS_REL_PATH} declares schema ${JSON.stringify(parsed.schema)}, expected one of ${COMMENTS_SCHEMAS.map((x) => `"${x}"`).join(" or ")} — refusing to read an unknown-schema ledger.`,
     );
   }
   return { schema: COMMENTS_SCHEMA, comments: parsed.comments };

package/template/qa/lib/determinism.mjs

@@ -55,7 +55,13 @@ function unescapeXml(s) {
 }
 
 function attr(attrs, name) {
-  const m = attrs.match(new RegExp(`${name}="([^"]*)"`));
+  // ANCHORED. Unanchored, `name="…"` matches inside `classname="…"`, so for any
+  // writer that emits classname FIRST — pytest, jest-junit, gotestsum all do —
+  // `attr(attrs, "name")` returned the CLASSNAME. Every test in a class then
+  // collapsed onto one `classname.classname` key, last-write-wins, and the
+  // determinism probe reported a genuine timezone flip as deterministic. Gradle
+  // emits name first and worked by luck, which is why this survived.
+  const m = attrs.match(new RegExp(`(?:^|\\s)${name}="([^"]*)"`));
   return m ? unescapeXml(m[1]) : null;
 }
 
@@ -70,11 +76,51 @@ function attr(attrs, name) {
  *   keyed by `classname.name`; empty object when the directory is absent
  *   (the caller decides what an empty leg means — this parser never guesses)
  */
-export function parseJUnitOutcomes(dir) {
+/**
+ * The report formats the core can read. Each is its OWN parser, dispatched by
+ * the profile's declaration — never sniffed from the file, because a wrong
+ * guess here produces `{}`, and an empty leg compared against an empty leg
+ * yields no differences: the probe would pass having read nothing. That exact
+ * failure is why the declaration exists.
+ *
+ * Every parser here obeys one rule, and it is the rule the whole probe rests
+ * on: READ ONLY VERDICT-BEARING CONTENT. No durations, no timestamps, no run
+ * ids. Two runs that differ solely in how long they took must produce byte-
+ * identical outcome maps, or the probe reports its own noise as a defect.
+ */
+export const REPORT_FORMATS = Object.freeze(["junit-xml", "tap", "ctrf"]);
+
+/**
+ * Why a profile's `reports` declaration cannot be read — or null when it can.
+ * PATTERN: JUnit XML as the lingua franca (pytest --junitxml, go-junit-report,
+ * cargo2junit, jest-junit, swift test --xunit-output); the profile DECLARES it.
+ * WHY IT WORKS: the parser stops assuming what a runner emitted. HOW IT FAILS:
+ * a dialect parses to {} and looks like "no tests". WHAT WE DO: undeclared or
+ * unsupported is a refusal by name here, and the probe treats an empty leg as a
+ * refusal, never a pass.
+ * @param {{format?: string}|null|undefined} reports
+ * @returns {string|null}
+ */
+export function reportFormatProblem(reports) {
+  if (!reports || typeof reports !== "object") return "the profile declares no `reports` — declare { format: \"junit-xml\" } (the format this stack's test runner emits) so the probe parses what was declared rather than assuming it";
+  if (!REPORT_FORMATS.includes(reports.format)) return `reports.format ${JSON.stringify(reports.format)} is not one the core can read (${REPORT_FORMATS.join(", ")}) — a parser for it is its own change`;
+  return null;
+}
+
+export function parseJUnitOutcomes(dir, { format } = {}) {
+  const problem = reportFormatProblem({ format });
+  if (problem) throw new Error(problem);
   const outcomes = {};
   if (!fs.existsSync(dir)) return outcomes;
   for (const entry of fs.readdirSync(dir)) {
-    if (!entry.startsWith("TEST-") || !entry.endsWith(".xml")) continue;
+    // ANY .xml, not just `TEST-*.xml`. That prefix is the Ant/Gradle/Surefire
+    // filename convention; pytest writes `junit.xml`, jest-junit `junit.xml`,
+    // gotestsum `junit.xml`, cargo2junit `results.xml`, `dotnet test`
+    // `TestResults.xml`. Every one of them parsed to {} — and an empty leg
+    // compared against an empty leg yields no differences, so the probe passed
+    // having read nothing. The `<testcase` match below is the real filter: a
+    // file with no test cases contributes nothing either way.
+    if (!entry.endsWith(".xml")) continue;
     const xml = fs.readFileSync(path.join(dir, entry), "utf8");
     const caseRe = /<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g;
     for (const m of xml.matchAll(caseRe)) {
@@ -100,17 +146,25 @@ export function parseJUnitOutcomes(dir) {
 }
 
 /**
- * Which lane step owns a test class — so the probe's failure message names
- * the step a reader would re-run, not just a class name. The patterns are
- * the same filters the lane's own gradleTestStep calls use.
+ * Which lane step owns a test class — so the probe's failure message names the
+ * step a reader would re-run, not just a class name.
+ *
+ * THIS IS THE PROFILE'S KNOWLEDGE and it moved there (profiles/cmp/steps-cmp.mjs).
+ * The core used to answer it with four names — `goldenTrees`, `conformance`,
+ * `a11y`, `unitTests` — three of which exist only in the cmp pack, matched
+ * against Kotlin class-name conventions. `compareOutcomes` called it
+ * unconditionally, so ANY profile reusing the core's determinism comparison got
+ * another stack's step names stamped onto its own diffs. It survived the lint
+ * only because this module was not in the lint's list; it is now.
+ *
+ * A caller that supplies no attribution gets `null` and the diff carries no
+ * step — an honest absence, not a borrowed name.
  * @param {string} classname fully-qualified test class
- * @returns {"goldenTrees"|"conformance"|"a11y"|"unitTests"}
+ * @param {((classname: string) => string|null)} [attribute] the profile's mapping
+ * @returns {string|null}
  */
-export function laneStepForTestClass(classname) {
-  if (/GoldenTreeTest$/.test(classname)) return "goldenTrees";
-  if (/ArchitectureConformanceTest$/.test(classname)) return "conformance";
-  if (/A11yConformanceTest$/.test(classname)) return "a11y";
-  return "unitTests";
+export function laneStepForTestClass(classname, attribute) {
+  return typeof attribute === "function" ? (attribute(classname) ?? null) : null;
 }
 
 function classnameOf(testId) {
@@ -143,11 +197,11 @@ function classnameOf(testId) {
  * @param {string} labelB human label for leg B
  * @returns {Array<{test: string, step: string, kind: string, detail: string}>}
  */
-export function compareOutcomes(a, b, labelA, labelB) {
+export function compareOutcomes(a, b, labelA, labelB, attribute) {
   const diffs = [];
   const ids = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort();
   for (const id of ids) {
-    const step = laneStepForTestClass(classnameOf(id));
+    const step = laneStepForTestClass(classnameOf(id), attribute);
     const inA = a[id];
     const inB = b[id];
     if (!inA || !inB) {
@@ -177,3 +231,210 @@ export function compareOutcomes(a, b, labelA, labelB) {
   }
   return diffs;
 }
+
+// ── TAP and CTRF ────────────────────────────────────────────────────────────
+// The second and third formats the core can read. Both were named as "next"
+// beside REPORT_FORMATS for months; a profile declaring either got a refusal
+// telling it a parser was its own change. This is that change.
+//
+// The rule both obey is the one the whole probe rests on: READ ONLY
+// VERDICT-BEARING CONTENT. TAP carries timings in YAML diagnostics and in
+// `# time=…` comments; CTRF carries `duration`, `start` and `stop` on every
+// test and a `summary` block full of them. None of it is read. A parser that
+// let a millisecond through would make every second run "nondeterministic" and
+// the probe would be reporting its own noise.
+
+/**
+ * Parse a TAP stream into per-test outcomes.
+ *
+ * IDENTITY. TAP has no classname — a test is its description, and the number is
+ * positional, so it is NOT part of the key: a suite whose tests reorder between
+ * two runs would otherwise read as every test having changed. Duplicate
+ * descriptions are disambiguated by occurrence, which is the honest answer when
+ * a runner emits two tests with one name.
+ *
+ * DIRECTIVES decide status before the ok/not-ok does: `# SKIP` is a skip
+ * whichever way the line reads, and a `# TODO` failure is an expected one, so
+ * it is a skip rather than a fail — that is TAP's own semantics, and reading it
+ * as a failure would make a passing suite look broken.
+ *
+ * @param {string} text one TAP stream
+ * @returns {Record<string, {status: "pass"|"fail"|"error"|"skip", messages: string[]}>}
+ */
+export function parseTapStream(text) {
+  const outcomes = {};
+  const seen = new Map();
+  const lines = String(text ?? "").split("\n");
+  // NESTING IS INDENTATION, and identity is the PATH. Found by running Node's
+  // own `--test-reporter=tap` at it: a child keyed by its bare name collides
+  // with a same-named child under another parent, and the collision is then
+  // resolved positionally — which reintroduces exactly the ordering
+  // sensitivity the bare test number was excluded to avoid. `parent > child`
+  // is stable however the parents run, and it mirrors what JUnit keys as
+  // `classname.name` and CTRF as `suite.name`, so all three formats identify
+  // the same test the same way.
+  //
+  // THE PARENT IS NOT KNOWN FROM ITS RESULT LINE. TAP emits a parent's `ok`
+  // AFTER its children — it cannot report a verdict it has not finished
+  // computing — so a stack built from result lines makes the previous SIBLING
+  // the parent, which is what the first attempt did (children came out under
+  // "todo one"). The line that does precede the block is `# Subtest: <name>`,
+  // at the parent's own indentation, and both major TAP producers emit it.
+  // A producer that emits none has a flat stream, where there is nothing to
+  // nest and bare names are already the whole path.
+  const stack = [];
+  let pending = null;
+
+  const commit = () => {
+    if (!pending) return;
+    const n = (seen.get(pending.name) ?? 0) + 1;
+    seen.set(pending.name, n);
+    outcomes[n === 1 ? pending.name : `${pending.name} #${n}`] = { status: pending.status, messages: pending.messages };
+    pending = null;
+  };
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const sub = line.match(/^(\s*)#\s*Subtest:\s*(.+?)\s*$/);
+    if (sub) {
+      commit();
+      const depth = sub[1].length;
+      while (stack.length && stack[stack.length - 1].depth >= depth) stack.pop();
+      stack.push({ depth, name: sub[2] });
+      continue;
+    }
+    const m = line.match(/^(\s*)(not ok|ok)\b[ \t]*(\d+)?[ \t]*-?[ \t]*(.*)$/);
+    if (!m) {
+      // A YAML diagnostic block belongs to the test above it.
+      //
+      // WHICH KEYS ARE READ decides whether a whole defect class is visible.
+      // The first version read `message` and `severity` — the keys the TAP spec's
+      // own examples show — and Node writes the failure text under `error:` as a
+      // block scalar instead. Every failure therefore parsed with NO messages,
+      // and `compareOutcomes`'s "failed under both, with different output" could
+      // never fire for the most widely available TAP producer there is. That is a
+      // silent wrong verdict, and no amount of reading the spec would have found
+      // it.
+      //
+      // `duration_ms` and `location` stay excluded: one is time, the other is an
+      // absolute path. Neither is verdict-bearing, and both would make two
+      // identical runs look different.
+      if (pending && /^\s*---\s*$/.test(line)) {
+        for (i += 1; i < lines.length && !/^\s*\.\.\.\s*$/.test(lines[i]); i += 1) {
+          const kv = lines[i].match(/^(\s*)(message|severity|error|code|name|failureType)\s*:\s*(.*)$/);
+          if (!kv) continue;
+          const [, indent, key, rawValue] = kv;
+          const value = rawValue.trim();
+          if (/^[|>]-?\+?$/.test(value)) {
+            // A block scalar: its body is the more-indented lines beneath it.
+            const body = [];
+            for (let j = i + 1; j < lines.length; j += 1) {
+              if (/^\s*\.\.\.\s*$/.test(lines[j])) break;
+              const deeper = lines[j].match(/^(\s*)(.*)$/);
+              if (lines[j].trim() && deeper[1].length <= indent.length) break;
+              body.push(deeper[2]);
+              i = j;
+            }
+            const firstLine = body.find((b) => b.trim());
+            if (firstLine) pending.messages.push(`${key}: ${firstLine.trim()}`);
+            continue;
+          }
+          if (value) pending.messages.push(key === "message" ? value.replace(/^["']|["']$/g, "") : `${key}: ${value.replace(/^["']|["']$/g, "")}`);
+        }
+      }
+      continue;
+    }
+    commit();
+    const depth = m[1].length;
+    // A result line CLOSES its own frame: everything at or deeper than it is
+    // finished, and the frame it names is itself (pushed by its `# Subtest:`).
+    while (stack.length && stack[stack.length - 1].depth >= depth) stack.pop();
+    const rest = m[4] ?? "";
+    // The directive is separated from the description by ` # `. Splitting on it
+    // also strips a runner's `# time=…` trailer, which must never reach a key.
+    const hash = rest.indexOf("#");
+    const description = (hash === -1 ? rest : rest.slice(0, hash)).trim();
+    const directive = hash === -1 ? "" : rest.slice(hash + 1).trim();
+    let status = m[2] === "ok" ? "pass" : "fail";
+    if (/^skip\b/i.test(directive)) status = "skip";
+    else if (/^todo\b/i.test(directive)) status = "skip";
+    const own = description || `test ${m[3] ?? Object.keys(outcomes).length + 1}`;
+    const name = [...stack.map((f) => f.name), own].join(" > ");
+    pending = { name, status, messages: [] };
+  }
+  commit();
+  return outcomes;
+}
+
+/**
+ * Parse a CTRF report (JSON) into per-test outcomes.
+ *
+ * CTRF names four statuses this maps onto the probe's four: `passed`,
+ * `failed`, `skipped`, `pending` (a skip — it did not run), and `other`, which
+ * is the honest match for `error`: the runner could not say. A status the
+ * schema does not define is `error` too, because "I do not know what this
+ * means" is not "it passed" — the same stance `ERROR` takes everywhere else in
+ * this harness.
+ *
+ * IDENTITY is `suite.name` when a suite is given, mirroring JUnit's
+ * `classname.name`, so the two formats key the same test the same way.
+ *
+ * @param {string} json one CTRF document
+ * @returns {Record<string, {status: "pass"|"fail"|"error"|"skip", messages: string[]}>}
+ */
+export function parseCtrfReport(json) {
+  const outcomes = {};
+  let doc;
+  try {
+    doc = JSON.parse(json);
+  } catch {
+    // Unparseable is EMPTY, not a throw: the caller's own rule is that an empty
+    // leg is a refusal, never a pass, so this cannot hide a defect — and one
+    // corrupt file must not stop the other leg from being read.
+    return outcomes;
+  }
+  const tests = Array.isArray(doc?.results?.tests) ? doc.results.tests : Array.isArray(doc?.tests) ? doc.tests : [];
+  const STATUS = { passed: "pass", failed: "fail", skipped: "skip", pending: "skip", other: "error" };
+  const seen = new Map();
+  for (const t of tests) {
+    if (!t || typeof t.name !== "string" || !t.name) continue;
+    const base = typeof t.suite === "string" && t.suite ? `${t.suite}.${t.name}` : t.name;
+    const n = (seen.get(base) ?? 0) + 1;
+    seen.set(base, n);
+    const messages = [];
+    if (typeof t.message === "string" && t.message) messages.push(t.message);
+    if (!messages.length && typeof t.trace === "string" && t.trace) messages.push(t.trace.split("\n")[0]);
+    outcomes[n === 1 ? base : `${base} #${n}`] = { status: STATUS[t.status] ?? "error", messages };
+  }
+  return outcomes;
+}
+
+/**
+ * The one entry point a step should call: parse a results directory according
+ * to the format the PROFILE declared.
+ *
+ * Dispatching here rather than at each call site is what keeps the refusal in
+ * one place. A step that picked its own parser would be free to disagree with
+ * `reportFormatProblem` about what is supported, and the disagreement would
+ * surface as an empty outcome map — the failure mode this whole file is
+ * arranged to prevent.
+ *
+ * @param {string} dir a test-results directory
+ * @param {{format?: string}} declared the profile's `reports`
+ * @returns {Record<string, {status: string, messages: string[]}>}
+ */
+export function parseReportOutcomes(dir, { format } = {}) {
+  const problem = reportFormatProblem({ format });
+  if (problem) throw new Error(problem);
+  if (format === "junit-xml") return parseJUnitOutcomes(dir, { format });
+
+  const outcomes = {};
+  if (!fs.existsSync(dir)) return outcomes;
+  const wanted = format === "tap" ? /\.(tap|txt)$/i : /\.json$/i;
+  for (const entry of fs.readdirSync(dir).sort()) {
+    if (!wanted.test(entry)) continue;
+    const body = fs.readFileSync(path.join(dir, entry), "utf8");
+    Object.assign(outcomes, format === "tap" ? parseTapStream(body) : parseCtrfReport(body));
+  }
+  return outcomes;
+}

package/template/qa/lib/evidence-badge.mjs

@@ -18,6 +18,12 @@
 // a FAIL says so, and a --fast run (which the ladder deliberately grants no
 // rung) says so rather than borrowing the last good one.
 //
+// And it never renders a rung without the PACK that graded it, which is the
+// same rule in the other axis: the commit says WHEN the claim was true, the
+// pack says WHOSE L2 it is. Until 2026-09-08 it printed the rung alone, so the
+// most-travelled surface this harness writes invited exactly the comparison
+// NORTH-STAR.md §8.9 forbids — one pack's L2 read as another's.
+//
 // Written by the lane AFTER the receipt (it is an output derived from the
 // receipt, never a gate), and committed alongside it.
 
@@ -94,10 +100,36 @@ export function renderEvidenceBadge(receipt) {
   const satisfied = Array.isArray(level.satisfiedBy) && level.satisfiedBy.length
     ? ` Earned by: ${level.satisfiedBy.map((s) => `\`${s}\``).join(", ")}.`
     : "";
+  // THE PACK TRAVELS WITH THE RUNG, in the badge itself and not only in the
+  // prose under it. NORTH-STAR.md §6.5 requires it of every surface that shows
+  // a rung, and §8.9 says why: one pack's L2 and another pack's L2 are
+  // different claims — one may mean a phone drove the app, another that a
+  // container held a real database. This badge is the surface that TRAVELS
+  // furthest (a GitHub repo page, a PR, a screenshot in a deck), so it is the
+  // one where a bare "L2" does the most damage: the reader who sees it has no
+  // receipt in front of them to check which ladder it was graded against.
+  //
+  // Only the ID. `pack.version` on a receipt is currently the harness lock's
+  // number rather than the profile's — docs/adr/0008-a-resolved-harness-is-
+  // still-a-vendored-one.md — so a badge that printed it would be publishing a
+  // borrowed fact on the most-quoted surface we own. The id is the part that
+  // carries the meaning, and the id is the profile's own.
+  //
+  // A receipt with no pack SAYS SO instead of rendering as though the question
+  // never arose — an unattributed rung is comparable to nothing, and hiding
+  // that is the overclaim this file exists to refuse.
+  const pack = typeof receipt.pack?.id === "string" && receipt.pack.id.trim() ? receipt.pack.id.trim() : null;
+  const message = pack ? `${pack} ${level.rung} ${level.name}` : `${level.rung} ${level.name}, pack unnamed`;
+  const comparability = pack
+    ? ` The rung is this pack's: \`${pack}\`'s ${level.rung} and another pack's ${level.rung} are different claims.`
+    : ` The receipt names no pack, so this rung cannot be compared with any other project's.`;
   return (
-    `${badge("evidence", `${level.rung} ${level.name}`, color, `Evidence ${level.rung} — ${level.name}`)}` +
+    // The alt text is a rung-bearing surface too — it is what a screen reader
+    // and a text-only renderer get instead of the image, so it carries the pack
+    // for the same reason the image does.
+    `${badge("evidence", message, color, `Evidence ${level.rung} — ${level.name}${pack ? ` (pack ${pack})` : " (pack unnamed)"}`)}` +
     ` — the verify lane passed${at}${on} at rung **${level.rung} · ${level.name}**.` +
-    `${satisfied}${uncommitted}` +
+    `${comparability}${satisfied}${uncommitted}` +
     ` The rung describes that run; it says nothing about changes made since.`
   );
 }

package/template/qa/lib/evidence-ladder.mjs

@@ -0,0 +1,202 @@
+// The evidence ladder, resolved — ONE answer, for every reader.
+//
+// WHY THIS FILE EXISTS. Until 2026-09-08 the ladder had two spellings and each
+// had a different reader, and neither reader knew the other existed:
+//
+//   `export const ladder`         the top-level declaration. `harness init`
+//                                 seeds it as THE way to declare rungs
+//                                 (install/init.mjs), and
+//                                 qa/receipt-check.mjs read it.
+//   `evidenceLadder` on the pack  a key on the object `steps(ctx)` returns.
+//                                 The lane runner read only this one
+//                                 (qa/verify.mjs).
+//
+// The one real profile exports BOTH, out of the same frozen constant, so
+// whichever reader ran got the same object and the split was invisible from
+// inside it. A foreign author who did exactly what the seeded skeleton says
+// declared `ladder`; the lane looked for `evidenceLadder`, found none, and
+// graded the run at NO RUNG with no message — because "no ladder, no rung" is
+// the honest answer to a profile that declared nothing and a silently wrong one
+// to a profile that declared it in the other place. Found on 2026-09-08 by
+// scripts/stage2-gate.mjs running in an ecosystem this code had never met,
+// which is how all eight wrong verdicts in NORTH-STAR.md §9.1 were found.
+//
+// BOTH SPELLINGS STAY, because they answer different questions. The pack's is
+// the only one a pack can COMPUTE — it is built inside `steps(ctx)`, where the
+// run's own context is in hand. The top-level one is the only one a reader that
+// must not START A LANE can ask: the Stop hook deciding whether a tier that
+// could have run did holds a project root and nothing else, and calling
+// `steps(ctx)` to find out would be a done-gate that runs a lane
+// (lib/profiles/cmp/index.mjs states this reason where it re-exports the
+// constant).
+//
+// THE PRECEDENCE, AND WHY IT IS DELIBERATELY UNOBSERVABLE. The top-level
+// declaration wins. The argument is not that it is better data; it is that it
+// is the data the WEAKEST reader can see, and the weakest reader and the lane
+// must grade from the same bytes or the product's own comparability rule
+// (NORTH-STAR.md §8.9 — one pack's L2 and another's are different claims)
+// becomes a question of which reader ran. Preferring the pack's would mean the
+// lane grades from something the Stop hook can never see.
+//
+// And because the two must be the SAME ladder, the precedence can never change
+// a rung: where both are present they must agree, and where they disagree this
+// refuses instead of choosing. Deriving a grade from a contradiction would mint
+// a claim nobody made, in the vocabulary evidence is actually sold in. That
+// refusal is the one gate this module adds, and it is calibrated by a kept
+// plant that watches the real lane refuse by name (test/evidence-ladder.test.mjs).
+//
+// WHAT COUNTS AS DISAGREEMENT is exactly the fields the grader reads
+// (evidence-level.mjs), and nothing else. A difference the grader cannot see
+// cannot change a rung, so refusing over one would be a gate with no wrong
+// verdict behind it — mechanism for its own sake, which NORTH-STAR.md §8.8
+// presumes against. The pairing is pinned by a test that derives the read
+// fields from evidence-level.mjs's own source, so the two cannot drift apart.
+//
+// SINGLE SOURCE OF TRUTH: packages/harness/src/lib/evidence-ladder.mjs in the
+// create-cmp repo. Vendored byte-identical into qa/lib/ — edit the package
+// source, then run `node scripts/sync-harness.mjs`.
+
+/**
+ * The ladder fields `evidenceLevel` actually reads (evidence-level.mjs). Two
+ * declarations differing anywhere else are not in disagreement about any grade,
+ * so they are not refused.
+ */
+export const GRADED_FIELDS = Object.freeze(["scaffoldCore", "l0Required", "l1Required", "deviceExecution", "release", "names"]);
+
+/** The two spellings, named the way an author wrote them, for every message below. */
+const DECLARED_SPELLING = "`export const ladder` (the profile's top-level declaration)";
+const PACK_SPELLING = "`evidenceLadder` (a key on the object `steps(ctx)` returns)";
+
+/** A declaration is PRESENT when it is neither absent nor an explicit "none". */
+function present(v) {
+  return v !== undefined && v !== null;
+}
+
+/**
+ * Deep equality with functions compared by IDENTITY — a ladder is data, and two
+ * distinct functions in the same slot are a difference this cannot see through
+ * and must not pretend to.
+ */
+function same(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((x, i) => same(x, b[i]));
+  }
+  if (a && b && typeof a === "object" && typeof b === "object") {
+    const ka = Object.keys(a).sort();
+    const kb = Object.keys(b).sort();
+    if (ka.length !== kb.length || ka.some((k, i) => k !== kb[i])) return false;
+    return ka.every((k) => same(a[k], b[k]));
+  }
+  return false;
+}
+
+/** How a value reads in a refusal — short, and never a whole ladder dumped inline. */
+function brief(v) {
+  if (v === undefined) return "absent";
+  if (Array.isArray(v)) return JSON.stringify(v);
+  if (v && typeof v === "object") return `{${Object.keys(v).sort().join(", ")}}`;
+  return JSON.stringify(v) ?? String(v);
+}
+
+/**
+ * The evidence ladder this profile declares, however it declared it.
+ *
+ * @param {object|null|undefined} profile the loaded profile module namespace
+ * @param {object|null|undefined} [pack] the object `steps(ctx)` returned, when
+ *   the caller has one. A reader that must not start a lane passes nothing and
+ *   gets what the profile DECLARES — which is the whole reason the top-level
+ *   spelling takes precedence.
+ * @returns {{ok: true, ladder: object|null, source: "profile"|"pack"|"both"|"none"}
+ *   |{ok: false, reason: string, source: "both"|"profile"|"pack"}}
+ *   `ladder: null` with `source: "none"` is the honest grade for a profile that
+ *   declared no rungs — it is not a failure, and the caller derives no rung.
+ */
+export function evidenceLadderFor(profile, pack) {
+  const id = profile && typeof profile.id === "string" ? profile.id : "(unnamed)";
+  const declared = profile && typeof profile === "object" ? profile.ladder : undefined;
+  const packed = pack && typeof pack === "object" ? pack.evidenceLadder : undefined;
+
+  // Present-but-wrong is refused, never ignored — the same rule the profile
+  // loader applies to `artifacts` and `governable`. A ladder that is not an
+  // object silently grades as no ladder at all, which is the defect this
+  // module exists to close wearing a different hat.
+  for (const [value, spelling, source] of [
+    [declared, DECLARED_SPELLING, "profile"],
+    [packed, PACK_SPELLING, "pack"],
+  ]) {
+    if (present(value) && (typeof value !== "object" || Array.isArray(value))) {
+      return {
+        ok: false,
+        source,
+        reason:
+          `profile "${id}" declares ${spelling} as ${brief(value)}, which is not an evidence ladder — ` +
+          `a ladder is an object of step names ({ names, l0Required, l1Required, deviceExecution, release }). ` +
+          `Fix it or remove it; a profile that declares no ladder earns no rung, which is honest, and this is not that.`,
+      };
+    }
+  }
+
+  // `release` is the ONE graded field the grader reads as a single step name
+  // rather than as a list, and that asymmetry produces a silently wrong verdict.
+  // evidence-level.mjs does `passed.has(L.release)` against a Set of step-name
+  // STRINGS, so a `release: ["distribution"]` never matches anything and L3
+  // becomes unreachable without one word being said about it. Every sibling
+  // field — scaffoldCore, l0Required, l1Required, deviceExecution — IS a list,
+  // and the seeded skeleton showed `release: []`, so the shape an author is
+  // most likely to reach for is exactly the one that fails silently. A real
+  // one did: the second-stack author who wrote the ktor-backend profile from
+  // the contract alone declared `release: ["distribution"]`, and their L3 was
+  // unreachable. Executed rather than read — the same ladder grades L2 as a
+  // list and L3 as a string.
+  //
+  // This REFUSES rather than reinterpreting. Accepting the list would be the
+  // semantically obvious repair, and it is not taken here, because it would
+  // move an existing pack's rung from L2 to L3 — changing what a receipt
+  // claims, which fit-test question 5 (NORTH-STAR.md §10) sends to an ADR
+  // first. A refusal changes no grade anywhere: a string means exactly what it
+  // meant, an absent one earns no L3 exactly as before, and the only tree
+  // whose behaviour moves is one that was already being graded wrongly and
+  // silently. Whether the ladder should be uniformly list-shaped is the open
+  // question, and it belongs in that ADR rather than in this fix.
+  for (const [value, spelling, source] of [
+    [declared, DECLARED_SPELLING, "profile"],
+    [packed, PACK_SPELLING, "pack"],
+  ]) {
+    const release = present(value) ? value.release : undefined;
+    if (present(release) && typeof release !== "string") {
+      return {
+        ok: false,
+        source,
+        reason:
+          `profile "${id}" declares ${spelling} with release = ${brief(release)}, which names no step. ` +
+          `\`release\` takes ONE step name as a string — it is the only ladder field that is not a list, ` +
+          `and a list here matches nothing, so L3 is unreachable and nothing says so. ` +
+          `Write \`release: "${Array.isArray(release) && typeof release[0] === "string" ? release[0] : "yourReleaseStep"}"\`, ` +
+          `or remove the field: a profile that declares no release step earns no L3, which is honest.`,
+      };
+    }
+  }
+
+  if (present(declared) && present(packed)) {
+    const differing = GRADED_FIELDS.filter((f) => !same(declared[f], packed[f]));
+    if (differing.length) {
+      return {
+        ok: false,
+        source: "both",
+        reason:
+          `profile "${id}" declares its evidence ladder TWICE and the two disagree, at ` +
+          `${differing.map((f) => `${f} (${brief(declared[f])} vs ${brief(packed[f])})`).join("; ")}. ` +
+          `${DECLARED_SPELLING} and ${PACK_SPELLING} must be the same ladder — the top-level one is what a reader ` +
+          `that cannot start a lane asks, and a rung graded from whichever declaration a given reader happened to ` +
+          `see would be a claim nobody made. Delete one, or export the same object from both.`,
+      };
+    }
+    return { ok: true, ladder: declared, source: "both" };
+  }
+
+  if (present(declared)) return { ok: true, ladder: declared, source: "profile" };
+  if (present(packed)) return { ok: true, ladder: packed, source: "pack" };
+  return { ok: true, ladder: null, source: "none" };
+}