create-cmp-cli 0.24.0 → 0.25.0

package/template/qa/lib/framework-check.mjs

@@ -38,6 +38,17 @@
 // byte-identical at scaffold time — edit the package source, then run
 // `node scripts/sync-harness.mjs`.
 
+// The core's fallback grammar, for the ONE thing this file reads out of a flow:
+// the citation marker. Importing it rather than re-declaring the pattern is the
+// point — a second copy of "what a citation looks like" is how the selector and
+// the scanner came to disagree about the same file (see `flowCitation`). The
+// import performs no IO; every function below still takes data and returns data.
+// The badge floor's two halves, imported for the same reason as the grammar
+// above: the plant below calibrates THE grader the lane runs and THE definition
+// of plant material the runner plants from, not a re-statement of either.
+import { evidenceLevel } from "./evidence-level.mjs";
+import { plantCalibration } from "./plant-calibration.mjs";
+
 /**
  * Per-direction bound. Rule 0's whole claim is about SPEED of refusal, so the
  * default is small on purpose: the smoke profile is every pure-Node gate and no
@@ -62,18 +73,133 @@ export const PLANT_KINDS = Object.freeze({
 });
 
 /**
- * The plants that need nothing but a lane. `harnessIntegrity` reads the machine-
- * owned region, which exists in every project that has a lane at all — so these
- * two are the floor. If even these cannot run, the tree has no harness to check
- * and the instrument must say so rather than report a vacuous PASS.
+ * The plants that need nothing but a lane. The step that reads the machine-owned
+ * region exists in every project that has a lane at all — so these two are the
+ * floor. If even these cannot run, the tree has no harness to check and the
+ * instrument must say so rather than report a vacuous PASS.
  */
 export const FLOOR_KINDS = Object.freeze([PLANT_KINDS.NARROWED_SURFACE, PLANT_KINDS.EDITED_LANE]);
 
+/**
+ * How the two floor plants say which receipt row they are about.
+ *
+ * THE ROW THAT VOUCHES IS THE ROW CARRYING THE VOUCHING DATA, not the row with
+ * a particular name — the principle qa/lib/receipt-validate.mjs settled in
+ * `checkLaneVouching` one layer out, mirrored here rather than re-invented.
+ * These two plants used to declare `step: "harnessIntegrity"` as a literal.
+ * That is a name the cmp pack chose for its own step; REQUIRED_EXPORTS never
+ * mentions it and a profile author has no way to discover it. On a pack that
+ * spells its self-check `harness_integrity`, both floor plants looked for a row
+ * that does not exist and the instrument reported "the guard did not FAIL BY
+ * NAME" — about a guard that had failed, by name, on the row immediately beside
+ * it. An adopter's Rule 0 check therefore fails on a working lane, and the
+ * message sends them into the harness instead of into the spelling.
+ *
+ * `vouching` says: find the row whose `harness` object carries the integrity
+ * check's own findings (the field the receipt schema documents, written by
+ * every row that performs it). `step` stays as the FALLBACK name, for receipts
+ * written before rows carried one — the same two-step lookup checkLaneVouching
+ * uses, and the same reason.
+ *
+ * `hookPattern` is matched against the Stop hook's refusal when the plant's
+ * receipt is forged to PASS. It named `harnessIntegrity` too, and the hook's
+ * refusal quotes the failing ROW'S name — so on that same pack the hook refused
+ * correctly and the instrument called the correct refusal a framework defect.
+ * The alternatives here are the core's own two wordings for this class of
+ * refusal (qa/lib/receipt-validate.mjs `checkLaneVouching`: the failing-rows
+ * branch and the did-not-vouch branch), neither of which is any pack's to spell.
+ */
+const VOUCHING_STEP = Object.freeze({
+  step: "harnessIntegrity",
+  vouching: true,
+  hookPattern: "vouch|the row is the more specific truth",
+});
+
+/**
+ * Which of THIS pack's steps observes the violation a plant makes.
+ *
+ * THE SECOND HALF OF THE SAME LESSON, and the reason a fix applied to instances
+ * comes back. `VOUCHING_STEP` above took the literal `harnessIntegrity` out of
+ * the two floor plants because it is a name the cmp pack chose (NORTH-STAR
+ * §9.1). The other five plants kept theirs — `specCoverage` on the three spec
+ * plants, `e2eCoverage` on the two flow ones — and those are the same string in
+ * the same position, doing the same damage: a name the profile protocol never
+ * mentions, that REQUIRED_EXPORTS does not ask for and a profile author has no
+ * way to discover, asserted by the core against every profile there will ever
+ * be.
+ *
+ * Measured rather than reasoned about, because §9.1's lesson is that a stack
+ * assumption naming no stack is found only by running. A `harness init`
+ * skeleton with its two steps renamed to snake_case and NOTHING else changed:
+ * the lane FAILs, `spec_coverage` names the orphaned citation exactly as it
+ * should, and this instrument stops at the first plant with
+ *
+ *   planted "orphaned citation" and the lane said FAIL (specCoverage: no row)
+ *   — the guard did not FAIL BY NAME
+ *
+ * That is worse than the floor-plant case rather than equal to it, because the
+ * spec plants run FIRST and a plant failure aborts the run: on such a tree the
+ * two plants that were already fixed never execute at all, and the adopter's
+ * Rule 0 check accuses their working lane while pointing at the harness.
+ *
+ * Three ways to fix it; only one is honest here.
+ *
+ * THE DATA SELECTOR `vouching` USES IS NOT AVAILABLE. It works because the CORE
+ * computes the integrity findings and the row carries them — `harness`, the one
+ * part of that row the receipt schema documents — so every pack that performs
+ * the check answers to it whether it declares anything or not. There is no
+ * equivalent for spec or journey coverage. What cmp's coverage row carries is
+ * `details` ({clauses, withdrawn, tags, files}), written by cmp's own step
+ * function; the generated skeleton writes a different shape ({clauses,
+ * citations}) from the same core scanner; and nothing documents either as a
+ * contract. Inventing a field now would put an undocumented requirement on
+ * every future pack, silently unmet by any pack that omits it — the same
+ * undiscoverable literal wearing different clothes.
+ *
+ * WIDENING TO "ANY ROW THAT WENT RED" IS NOT IT EITHER. The kept plant in
+ * test/framework-check-agnostic.test.mjs builds the receipt that refutes it: the
+ * integrity row FAILs quoting the planted clause id while the coverage gate sits
+ * PASS beside it. A lookup that accepts that reads a broken lock as a working
+ * spec gate, which is the mix-up this whole instrument exists to catch.
+ *
+ * SO THE PACK SAYS — through the declaration that already exists for this
+ * instrument. `plants` is NORTH-STAR §6's eighth declaration, "the Rule 0/1
+ * violations the instrument runs forever", and its endpoint in
+ * AGNOSTIC-HARNESS-ARCHITECTURE.md §5.1 is a `plants(tree)` that returns the
+ * plants themselves. Which step asserts a plant is part of that plant, so it
+ * belongs there and no tenth declaration is invented to hold it. The KEY is a
+ * plant kind — PLANT_KINDS, the core's vocabulary — and the VALUE is the pack's
+ * spelling, so neither side has to learn the other's words.
+ *
+ * AND THE DEFAULT IS NOT cmp's SPELLING. That is the distinction §9.1 drew for
+ * `compileStepName`: "the distinction is the KEY's presence, not its value — a
+ * pack that declares none short-circuits on NOTHING rather than inheriting
+ * another stack's step name." Here a pack that declares no step for a kind gets
+ * null, and `plantRow` then holds the LANE instead of a row nobody named: the
+ * assertion widens honestly, still refuses a lane that stayed green or went red
+ * without naming what was planted, and reports the row it actually read.
+ * Declaring narrows it back to exactly one row; declaring nothing never inherits
+ * the wrong one.
+ *
+ * @param {{observedBy?: Record<string, string>}} tree
+ * @param {string} kind one of PLANT_KINDS
+ * @returns {string|null} this pack's name for the step, or null if it named none
+ */
+function observingStep(tree, kind) {
+  const declared = tree?.observedBy?.[kind];
+  return typeof declared === "string" && declared.length > 0 ? declared : null;
+}
+
 /** A clause id at the head of a spec list item: `- **HOME-02** — …`. */
 const CLAUSE_RE = /^-\s+\*\*([A-Z][A-Z0-9]*-\d{2,})\*\*/m;
 
-/** `# SPEC: HOME-02` in a flow file — the citation an e2e journey carries. */
-const FLOW_CITATION_RE = /^#\s*SPEC:\s*([A-Z][A-Z0-9]*-\d{2,})/m;
+/**
+ * The ids on a citation line, once the MARKER has already matched it:
+ * `# SPEC: HOME-02, HOME-03 — …`. The id grammar is the core's (it is the same
+ * one scanCitations uses); the marker in front of it is the profile's.
+ */
+const CITATION_IDS_RE = /SPEC:\s*([A-Z0-9,\s-]+)/;
+const CLAUSE_ID_RE = /^[A-Z][A-Z0-9]*-\d{2,}$/;
 
 /**
  * The first clause id in a spec, or null. Used to pick something real to plant
@@ -90,13 +216,43 @@ export function firstClauseId(text) {
 
 /**
  * The clause a flow cites, or null.
+ *
+ * THE MARKER IS THE PROFILE'S. This matched `^#\s*SPEC:` and nothing else,
+ * which is true of Maestro YAML and false of a stack whose journeys are .ts,
+ * .kt, .rb or anything C-family. The cost was not a refusal: a project whose
+ * journeys cite with `//` was told `no "# SPEC:" citation in N flow file(s)`,
+ * both e2eCoverage plants stood down, and the check printed PASS with the
+ * reason folded into an ⓘ line — a gate reported as calibrated that had never
+ * been read. And the disagreement was internal: the core's own fallback marker
+ * (spec-model.mjs `DEFAULT_GRAMMAR.citationMarker`) has always accepted `//`,
+ * so qa/lib/spec-coverage.mjs `scanCitations` was counting the very citation
+ * this function could not see, in the same file, in the same tree.
+ *
+ * Same shape as scanCitations: test the profile's marker against the trimmed
+ * line, then read the ids after it. A profile that declares no `grammar` gets
+ * the same fallback the scan uses, so the two answers cannot drift apart again.
+ *
  * @param {string} text
+ * @param {{citationMarker?: RegExp}} [grammar] the SpecModel's grammar
  * @returns {string|null}
  */
-export function flowCitation(text) {
+export function flowCitation(text, grammar) {
   if (typeof text !== "string") return null;
-  const m = text.match(FLOW_CITATION_RE);
-  return m ? m[1] : null;
+  // The marker is the profile's; with none declared nothing can be a citation — and the lane refuses that profile before this runs.
+  const MARKER = grammar?.citationMarker;
+  if (!(MARKER instanceof RegExp)) return null;
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!MARKER.test(trimmed)) continue;
+    const m = trimmed.match(CITATION_IDS_RE);
+    if (!m) continue;
+    const id = m[1]
+      .split(/[,\s]+/)
+      .map((s) => s.trim())
+      .find((s) => CLAUSE_ID_RE.test(s));
+    if (id) return id;
+  }
+  return null;
 }
 
 /**
@@ -115,11 +271,26 @@ export function clauseFamily(clause) {
  * Decide which plants this tree can support, and say WHY each unavailable one
  * is unavailable.
  *
+ * `grammar` is the SpecModel's (qa/lib/spec-model.mjs): the caller passes the
+ * profile's, and a caller that passes none gets the same fallback the coverage
+ * scan uses. It decides one thing here — what a citation in a journey looks
+ * like — and getting it from the profile is what stops this instrument from
+ * disagreeing with the gate it is calibrating (see `flowCitation`).
+ *
+ * `observedBy` is the profile's `plants.observedBy` — plant kind → the name
+ * THIS pack gives the step that catches that kind of violation. A kind it does
+ * not name gets a null `step`, which is an assertion over the lane rather than
+ * over one row, never cmp's spelling by default (see `observingStep`).
+ *
  * @param {{specs?: Array<{rel: string, text: string}>,
  *          flows?: Array<{rel: string, text: string}>,
  *          harnessLib?: string[],
- *          testDir?: string|null}} tree
- * @returns {{plants: Array<{kind: string, label: string, step: string,
+ *          testDir?: string|null,
+ *          plantsDeclared?: boolean,
+ *          unmeetableTier?: string,
+ *          observedBy?: Record<string, string>,
+ *          grammar?: {citationMarker?: RegExp}}} tree
+ * @returns {{plants: Array<{kind: string, label: string, step: string|null,
  *            names: string[], target: object}>,
  *           unavailable: Array<{kind: string, reason: string}>}}
  */
@@ -128,6 +299,14 @@ export function selectPlants(tree) {
   const flows = Array.isArray(tree?.flows) ? tree.flows : [];
   const harnessLib = Array.isArray(tree?.harnessLib) ? tree.harnessLib : [];
   const testDir = tree?.testDir ?? null;
+  // Where this stack keeps the flow-shaped citation files the lane executes
+  // (the profile's `layout.flows.dir`). The nested-flow plant must land INSIDE
+  // it — a subdirectory the runner walks past — so the directory cannot be a
+  // constant here. Derived from the flows themselves when the caller does not
+  // say, so a caller with flows always gets the plant.
+  const flowsDir = typeof tree?.flowsDir === "string" && tree.flowsDir
+    ? tree.flowsDir
+    : (flows.find((f) => typeof f?.rel === "string" && f.rel.includes("/"))?.rel.replace(/\/[^/]*$/, "") ?? null);
 
   const plants = [];
   const unavailable = [];
@@ -143,12 +322,13 @@ export function selectPlants(tree) {
       : "no spec files — nothing declares behavior to plant against";
     for (const kind of [PLANT_KINDS.ORPHANED_CITATION, PLANT_KINDS.UNBOUND_CITATION, PLANT_KINDS.TIER_UNMET]) skip(kind, why);
   } else {
-    // Renaming a live clause orphans every citation of it: specCoverage must
-    // name the id it can no longer find.
+    // Renaming a live clause orphans every citation of it: whichever step reads
+    // clause↔test citations must name the id it can no longer find. WHICH step
+    // that is is the pack's to spell and never this file's — see observingStep.
     plants.push({
       kind: PLANT_KINDS.ORPHANED_CITATION,
       label: "orphaned citation",
-      step: "specCoverage",
+      step: observingStep(tree, PLANT_KINDS.ORPHANED_CITATION),
       names: [clause],
       target: { spec: spec.rel, clause },
     });
@@ -158,39 +338,71 @@ export function selectPlants(tree) {
     // exists, the tag exists, and nothing runs. The two remaining spec plants
     // need somewhere to put that Kotlin, so they hang on a test source dir.
     if (!testDir) {
-      const why = "no Kotlin test source directory — a planted citation has nowhere to live";
+      // TWO different causes reached this branch and the message named only
+      // one of them, wrongly: a profile that declares no `plants` never even
+      // looks for a test directory (framework-check.mjs passes testDir: null),
+      // so an adopter with two perfectly good test directories was told they
+      // had none. Worse, the plant this silently skips is `tier-unmet` — the
+      // one that calibrates the gate the whole instrument exists to prove —
+      // and the run still printed PASS. Saying which cause it is turns an
+      // invisible gap into a one-line fix. (And the core names no language.)
+      const why = tree?.plantsDeclared === false
+        ? "this profile declares no plants — add a `plants` export { testFileBasename, unboundCitationSource, tierUnmetCitationSource, unmeetableTier }"
+        : "no test source directory found — a planted citation has nowhere to live";
       skip(PLANT_KINDS.UNBOUND_CITATION, why);
       skip(PLANT_KINDS.TIER_UNMET, why);
     } else {
       plants.push({
         kind: PLANT_KINDS.UNBOUND_CITATION,
         label: "unbound citation",
-        step: "specCoverage",
+        step: observingStep(tree, PLANT_KINDS.UNBOUND_CITATION),
         names: [`${family}-99`],
         target: { spec: spec.rel, clause: `${family}-99`, testDir },
       });
-      plants.push({
-        kind: PLANT_KINDS.TIER_UNMET,
-        label: "tier unmet",
-        step: "specCoverage",
-        names: [`${family}-98`],
-        target: { spec: spec.rel, clause: `${family}-98`, testDir },
-      });
+      // The tier this plant declares must be the PROFILE'S. The core used to
+      // fall back to `?? "e2e"` at the write site — a CMP tier name, asserted
+      // by the spine into any stack's spec file. A profile that ships plants
+      // but names no unmeetable tier would then plant a clause tagged with a
+      // tier it does not define, and the resulting FAIL would be right for
+      // entirely the wrong reason. There is no default; there is a skip.
+      if (!tree?.unmeetableTier) {
+        skip(
+          PLANT_KINDS.TIER_UNMET,
+          "this profile's plants declare no `unmeetableTier` — name a tier in `tiers.satisfying` that a host-tier test cannot satisfy",
+        );
+      } else {
+        plants.push({
+          kind: PLANT_KINDS.TIER_UNMET,
+          label: "tier unmet",
+          step: observingStep(tree, PLANT_KINDS.TIER_UNMET),
+          names: [`${family}-98`],
+          target: { spec: spec.rel, clause: `${family}-98`, testDir, unmeetableTier: tree.unmeetableTier },
+        });
+      }
     }
   }
 
   // ── Flow-derived plants ──────────────────────────────────────────────────
   // Both strip EVERY citation from every flow, not just one line. e2eCoverage
   // asks whether a screen feature has any device journey at all, so removing a
-  // single `# SPEC:` from a flow that carries several leaves the feature
+  // single citation from a flow that carries several leaves the feature
   // covered and the gate — correctly — green. A plant that does not actually
   // produce the violation is worse than no plant: it reads as a calibrated
   // gate while proving nothing.
-  const citingFlows = flows.filter((f) => flowCitation(f?.text));
+  //
+  // WHICH flows cite is decided by the profile's citation marker, never by `#`:
+  // see `flowCitation`. The skip below prints the marker it used, because "no
+  // citation in 3 flow files" over three flows that all carry one is a sentence
+  // that sends the reader to the flows instead of to the grammar.
+  const grammar = tree?.grammar ?? null;
+  const marker = grammar?.citationMarker instanceof RegExp ? grammar.citationMarker : null;
+  const citingFlows = marker ? flows.filter((f) => flowCitation(f?.text, grammar)) : [];
   if (!citingFlows.length) {
-    const why = flows.length
-      ? `no "# SPEC:" citation in ${flows.length} flow file(s) — e2eCoverage has nothing to lose`
-      : "no qa/e2e flows — this project declares no device journeys";
+    const why = !marker
+      ? "the profile declares no grammar.citationMarker — the plant selector cannot read a citation (the lane refuses this profile for the same reason)"
+      : flows.length
+      ? `no citation matching /${marker.source}/ in ${flows.length} flow file(s) — the journey-coverage gate has nothing to lose`
+      : `no flows${flowsDir ? ` under ${flowsDir}` : ""} — this project declares no journeys`;
     skip(PLANT_KINDS.FEATURE_WITHOUT_FLOW, why);
     skip(PLANT_KINDS.NESTED_FLOW, why);
   } else {
@@ -199,36 +411,44 @@ export function selectPlants(tree) {
     plants.push({
       kind: PLANT_KINDS.FEATURE_WITHOUT_FLOW,
       label: "feature without a flow",
-      step: "e2eCoverage",
+      step: observingStep(tree, PLANT_KINDS.FEATURE_WITHOUT_FLOW),
       names: [],
       // FAIL BY NAME, without knowing this project's feature names: the gate
       // must name the feature it caught, in the [brackets] its reason uses.
       reasonPattern: String.raw`\[[^\]\s]+\]`,
       target: { flows: rels },
     });
-    // The citations move into a subdirectory Maestro's directory run never
-    // executes. The tags exist, the YAML is real, and nothing runs it — which
-    // must read exactly like having no journey.
+    // The citations move into a subdirectory of the flows directory that the
+    // lane's own directory run does not descend into. The tags exist, the flow
+    // is real, and nothing executes it — which must read exactly like having no
+    // journey at all.
     plants.push({
       kind: PLANT_KINDS.NESTED_FLOW,
       label: "flow the lane never runs",
-      step: "e2eCoverage",
+      step: observingStep(tree, PLANT_KINDS.NESTED_FLOW),
       names: [],
       reasonPattern: String.raw`\[[^\]\s]+\]`,
-      target: { flows: rels, nestInto: "qa/e2e/wip" },
+      target: { flows: rels, nestInto: `${flowsDir}/wip` },
     });
   }
 
   // ── Region plants — the floor ────────────────────────────────────────────
   // A narrowed declaration un-attests a whole layer while every checker stays
   // intact (payment-blueprint's planted proof); an edited lane cannot vouch for
-  // its own verdict. Both are read by harnessIntegrity, which needs only a lane.
+  // its own verdict. Both are read by the step that vouches for the lane, which
+  // needs only a lane — see `vouching` below for how that row is found.
   plants.push({
     kind: PLANT_KINDS.NARROWED_SURFACE,
     label: "narrowed surface declaration",
-    step: "harnessIntegrity",
-    names: ["unrecorded"],
-    hookPattern: "harnessIntegrity|vouch",
+    ...VOUCHING_STEP,
+    // Assert the FILE, not an internal state word. "unrecorded" only holds when
+    // the declaration is absent from the lock — true for a freshly stamped app,
+    // false for a repo whose lock was taken after `harness init` wrote the
+    // surface, where the identical edit reads as "modified". Both are the same
+    // correct refusal; pinning one of them made the instrument fail on a lane
+    // that was working. What the plant actually cares about is that the refusal
+    // NAMES what it refused over, which is now true in either state.
+    names: ["qa/verified-surface.json"],
     target: { declaration: "qa/verified-surface.json" },
   });
 
@@ -239,9 +459,11 @@ export function selectPlants(tree) {
     plants.push({
       kind: PLANT_KINDS.EDITED_LANE,
       label: "edited lane cannot vouch",
-      step: "harnessIntegrity",
+      ...VOUCHING_STEP,
+      // "modified" is the integrity check's own status word (qa/lib/harness-
+      // region.mjs), not a step name and not a stack's — every pack's row
+      // reports it, because the core computes it.
       names: ["modified"],
-      hookPattern: "harnessIntegrity|vouch",
       target: { file: spine },
     });
   }
@@ -276,6 +498,148 @@ export function assessCoverage(plants) {
   return { ok: true };
 }
 
+/**
+ * THE BADGE FLOOR'S KEPT PLANT — "a profile with no calibrated plants earns no
+ * rung" (NORTH-STAR.md §8.9), watched failing rather than assumed to work.
+ *
+ * WHY IT IS HERE AND NOT ONLY IN THE HARNESS'S OWN SUITE. GATE-RULES Rule 1 is
+ * explicit about where a plant goes — "Add the plant to `qa/framework-check.mjs`
+ * and run that" — and the reason is this gate's own subject: the floor exists to
+ * protect a claim made on EVERY adopter's receipt, so the plant that proves it
+ * still bites has to run in every adopter's tree, forever, not once in ours.
+ * A gate proved only in the repository that wrote it is a gate proved on the one
+ * profile it was written against, which is how every wrong verdict in
+ * NORTH-STAR.md §9.1 survived a green suite.
+ *
+ * THE VIOLATION PLANTED is the twin `scripts/stage2-gate.mjs` built: this
+ * profile's own ladder and a lane whose rows all PASS, graded with the `plants`
+ * declaration REMOVED. Before 2026-09-08 that earned `L1` — measured on two
+ * scratch adopters differing in exactly one export. It must now earn nothing,
+ * and the same rows WITH the declaration must still earn their rung, or the
+ * plant would go green on a grader that had simply stopped grading anyone.
+ * Those two halves are the same pair criteria F and G of the stage-2 gate make,
+ * and they are made here in microseconds instead of two adopted trees.
+ *
+ * NO TREE IS TOUCHED AND NO LANE IS RUN. The rows are synthesised from the
+ * ladder's own step names, so this asserts over the GRADER — which is the only
+ * thing the floor lives in. That is also its limit, and it is stated in the
+ * runner's own output rather than hidden here: it proves the rung a lane WOULD
+ * be given, not that a lane was run.
+ *
+ * @param {{ladder: object|null|undefined, plants: object|null|undefined}} profile
+ *   the profile's resolved ladder (qa/lib/evidence-ladder.mjs) and its `plants`
+ *   declaration — both exactly as the lane runner reads them
+ * @returns {{ok: true, rung: string}
+ *   |{ok: false, reason: string}
+ *   |{available: false, reason: string}} `available: false` is neither a pass
+ *   nor a failure: it is a plant this tree cannot make, reported with its cause
+ *   the same way every unavailable plant is.
+ */
+export function assessBadgeFloor({ ladder, plants } = {}) {
+  const calibrated = plantCalibration(plants);
+  if (!calibrated.ok) {
+    return { available: false, reason: `${calibrated.reason} — there is no declaration to strip, and no rung to lose` };
+  }
+  if (!ladder || typeof ladder !== "object") {
+    return {
+      available: false,
+      reason:
+        "this profile declares no `ladder` a reader can see without starting a lane, so no rung exists either way " +
+        "(a ladder declared only on the object `steps(ctx)` returns is invisible here — qa/lib/evidence-ladder.mjs)",
+    };
+  }
+  const names = [...new Set([...(ladder.l0Required ?? []), ...(ladder.l1Required ?? [])])];
+  const rows = names.map((name) => ({ name, verdict: "PASS" }));
+  const earned = evidenceLevel(rows, null, { mode: "full", ladder, plants });
+  if (!earned) {
+    return {
+      available: false,
+      reason:
+        `this profile's ladder grants no rung even with ${names.length ? names.join(", ") : "every declared step"} PASSing, ` +
+        "so there is no rung for the floor to withhold",
+    };
+  }
+  // THE PLANT: the same rows, the same ladder, and no plant material.
+  const stripped = evidenceLevel(rows, null, { mode: "full", ladder, plants: undefined });
+  if (stripped) {
+    return {
+      ok: false,
+      reason:
+        `PLANTED the profile's own ladder with its \`plants\` declaration removed and the lane still earned ` +
+        `${stripped.rung} · ${stripped.name} — the badge floor is not being applied. NORTH-STAR.md §8.9: "a profile ` +
+        `with no calibrated plants earns no rung"; §6.7: a profile ships plants this instrument can run, or it ships ` +
+        `without a badge. The grader is qa/lib/evidence-level.mjs and the floor it asks is qa/lib/plant-calibration.mjs`,
+    };
+  }
+  return { ok: true, rung: earned.rung };
+}
+
+/**
+ * What "FAIL BY NAME" means for one plant, in ONE place.
+ *
+ * Two callers need this answer — `plantRow`, to pick the row a plant with no
+ * declared step is about, and `assessPlantRun`, to say which part of the
+ * naming is missing — and a second copy of "what counts as naming" is exactly
+ * how `flowCitation` and `scanCitations` came to disagree about the same file
+ * in the same tree. So there is one, and the caller that needs a sentence gets
+ * the offending part back rather than re-deriving it.
+ *
+ * @param {{reason?: string}} row
+ * @param {{names?: string[], reasonPattern?: string}} plant
+ * @returns {{kind: "name"|"pattern", want: string, reason: string}|null} null when the row names everything asked of it
+ */
+function missingName(row, plant) {
+  const reason = String(row?.reason ?? "");
+  for (const name of plant?.names ?? []) {
+    if (!reason.includes(name)) return { kind: "name", want: name, reason };
+  }
+  if (plant?.reasonPattern && !new RegExp(plant.reasonPattern).test(reason)) {
+    return { kind: "pattern", want: plant.reasonPattern, reason };
+  }
+  return null;
+}
+
+/**
+ * The receipt row a plant's assertion is about — found three ways, in the order
+ * of how much each one can be trusted about a pack nobody here has met.
+ *
+ * BY ITS DATA, for the two floor plants. Their assertion is about the step that
+ * VOUCHES FOR THE LANE, whatever the pack calls it, and the core computes the
+ * findings that row carries — so `harness` identifies it on every pack, with
+ * the name only as the pre-`harness` fallback. See VOUCHING_STEP.
+ *
+ * BY THE NAME THE PACK GAVE IT, when the pack declared one for this plant kind
+ * (`plants.observedBy`). This is the sharp case and the one to prefer: a
+ * different row failing instead is the mix-up the instrument exists to catch,
+ * and only a named row can catch it.
+ *
+ * BY THE LANE, when the pack declared nothing. There is no honest third source
+ * for another pack's step name (see `observingStep`), so the assertion becomes
+ * "some row went red naming what was planted" — the row carrying the plant's own
+ * fingerprint. Only FAIL rows can satisfy it: an ERROR is a step that fell over,
+ * not a gate that read something and refused, and treating the two alike is how
+ * a crash comes to read as a calibrated gate. When no FAIL row names the plant,
+ * a red row is returned anyway rather than null, because `assessPlantRun` then
+ * prints that row's reason — "this is what your lane actually said" is a far
+ * better sentence to hand an adopter than "no row" — and the FAIL rows are
+ * offered ahead of the ERROR ones, or a step that blew up alongside a gate that
+ * fired correctly would be reported as the finding. This branch is weaker than
+ * a declared name and is meant to be: it is what a pack gets for not saying,
+ * and it still bites.
+ *
+ * @param {Array<object>} steps
+ * @param {{step?: string|null, vouching?: boolean, names?: string[], reasonPattern?: string}} plant
+ * @returns {object|null}
+ */
+export function plantRow(steps, plant) {
+  const rows = Array.isArray(steps) ? steps : [];
+  const byName = plant?.step ? (rows.find((s) => s && s.name === plant.step) ?? null) : null;
+  if (plant?.vouching) return rows.find((s) => s && s.harness && typeof s.harness === "object") ?? byName;
+  if (plant?.step) return byName;
+  const failed = rows.filter((s) => s && s.verdict === "FAIL");
+  return failed.find((s) => !missingName(s, plant)) ?? failed[0] ?? rows.find((s) => s && s.verdict === "ERROR") ?? null;
+}
+
 /**
  * Judge one planted run. Every branch here is a distinct framework defect and
  * says which one it is: a hang, a lane that produced no receipt, a guard that
@@ -286,10 +650,15 @@ export function assessCoverage(plants) {
  * told apart from a gate failing for an unrelated reason, which is how a
  * calibration passes on a gate that was never actually read.
  *
+ * Every message below names the row it ACTUALLY READ, not the row the plant
+ * asked for: on a pack whose steps are spelled differently those are two
+ * different strings, and reporting the request instead of the finding is how a
+ * lookup miss reads as a gate defect.
+ *
  * @param {{hung?: boolean, ms?: number, exit?: number|null,
  *          receipt?: {verdict?: string, steps?: Array<object>}|null,
  *          stderr?: string}} run
- * @param {{label: string, step: string, names?: string[]}} plant
+ * @param {{label: string, kind?: string, step?: string|null, names?: string[], vouching?: boolean}} plant
  * @param {number} boundMs
  * @returns {{ok: true}|{ok: false, reason: string}}
  */
@@ -303,24 +672,36 @@ export function assessPlantRun(run, plant, boundMs) {
     const tail = String(run?.stderr ?? "").slice(-600);
     return { ok: false, reason: `"${label}" returned no receipt (exit ${run?.exit ?? "?"})${tail ? `:\n${tail}` : ""}` };
   }
-  const row = (receipt.steps ?? []).find((s) => s?.name === plant.step);
+  const row = plantRow(receipt.steps, plant);
+  const rowName = row?.name ?? plant.step ?? "the lane";
   if (receipt.verdict !== "FAIL" || !row || row.verdict !== "FAIL") {
+    // A missing row says what was looked for. "harnessIntegrity: no row" over a
+    // receipt whose vouching row is called something else is a true sentence
+    // that points at the wrong thing. The third branch is the pack that named
+    // no step for this kind: "no row" would be the same wrong sentence again,
+    // so it says what the lookup actually was AND names the declaration that
+    // would make it sharp — an adopter cannot fix a requirement nobody states.
+    const found = row
+      ? `${rowName}: ${row.verdict}`
+      : plant.vouching
+        ? `no row carries a \`harness\` object and none is named ${plant.step}`
+        : plant.step
+          ? `${plant.step}: no row`
+          : `no row on this receipt went red at all, and this profile's \`plants.observedBy\` names no step for ${plant.kind ?? "this plant"}`;
     return {
       ok: false,
-      reason: `planted "${label}" and the lane said ${receipt.verdict} (${plant.step}: ${row ? row.verdict : "no row"}) — the guard did not FAIL BY NAME`,
+      reason: `planted "${label}" and the lane said ${receipt.verdict} (${found}) — the guard did not FAIL BY NAME`,
     };
   }
-  const reason = String(row.reason ?? "");
-  for (const name of plant.names ?? []) {
-    if (!reason.includes(name)) {
-      return { ok: false, reason: `${plant.step} FAILed on "${label}" but did not NAME ${name}:\n${reason}` };
-    }
-  }
   // Some gates name something the selector cannot know in advance — a feature
-  // this project happens to have. The pattern is how those still assert FAIL BY
-  // NAME instead of settling for "it went red".
-  if (plant.reasonPattern && !new RegExp(plant.reasonPattern).test(reason)) {
-    return { ok: false, reason: `${plant.step} FAILed on "${label}" but named nothing matching /${plant.reasonPattern}/:\n${reason}` };
+  // this project happens to have. `reasonPattern` is how those still assert
+  // FAIL BY NAME instead of settling for "it went red"; `missingName` holds
+  // both halves so the row lookup above cannot drift from the judgement here.
+  const missing = missingName(row, plant);
+  if (missing) {
+    return missing.kind === "name"
+      ? { ok: false, reason: `${rowName} FAILed on "${label}" but did not NAME ${missing.want}:\n${missing.reason}` }
+      : { ok: false, reason: `${rowName} FAILed on "${label}" but named nothing matching /${missing.want}/:\n${missing.reason}` };
   }
   return { ok: true };
 }