create-cmp-cli 0.23.0 → 0.25.0

package/bin/create-cmp.mjs

@@ -15,7 +15,7 @@
 
 import { parseArgs } from "../src/lib/args.mjs";
 
-const COMMANDS = new Set(["create", "doctor", "upgrade", "clean", "verify", "harden", "attach", "help"]);
+const COMMANDS = new Set(["create", "doctor", "upgrade", "clean", "verify", "harden", "attach", "harness", "help"]);
 
 async function main() {
   const argv = process.argv.slice(2);
@@ -63,6 +63,30 @@ async function main() {
       await runAttach(flags, rest[0]);
       return;
     }
+    // `harness` takes a subcommand because it is stack-neutral and will grow
+    // siblings (`upgrade`, `doctor`) that must not collide with the Compose
+    // verbs above. It is also the form that survived the rename it predicted:
+    // since 2026-09-08 the implementation lives in the harness package and its
+    // own binary spells these `prooflane init` / `prooflane relock`. This
+    // dispatch DELEGATES rather than duplicating — `invocation` is the only
+    // difference, and it decides which command names the output prints back.
+    case "harness": {
+      const sub = rest[0];
+      if (sub === "init") {
+        const { runHarnessInit } = await import("../packages/harness/install/init.mjs");
+        process.exit((await runHarnessInit(flags, rest[1], { invocation: "create-cmp" })) ?? 0);
+      }
+      if (sub === "relock") {
+        const { runHarnessRelock } = await import("../packages/harness/install/relock.mjs");
+        process.exit((await runHarnessRelock(flags, rest[1], { invocation: "create-cmp" })) ?? 0);
+      }
+      process.stderr.write(
+        `create-cmp harness: unknown subcommand ${JSON.stringify(sub ?? "")}\n` +
+          `  usage: create-cmp harness init   [--profile <id>] [--target-dir <dir>] [--dry-run]\n` +
+          `         create-cmp harness relock [--target-dir <dir>] [--dry-run]\n`
+      );
+      process.exit(2);
+    }
     case "create":
     default: {
       const { runCreate } = await import("../src/commands/create.mjs");
@@ -85,7 +109,9 @@ function printHelp() {
       `  npx create-cmp clean                   ~/.konan + Gradle build-output hygiene (consent-gated)\n` +
       `  npx create-cmp verify                  run the green-build gate on an existing project\n` +
       `  npx create-cmp harden                  install the full harness into a --minimal scaffold\n` +
-      `  npx create-cmp attach                  wire the agent contract into an EXISTING Compose/KMP repo\n\n` +
+      `  npx create-cmp attach                  wire the agent contract into an EXISTING Compose/KMP repo\n` +
+      `  npx create-cmp harness init            install the verify lane into a repo of ANY stack\n` +
+      `  npx create-cmp harness relock          re-take the lock after editing YOUR profile or declarations\n\n` +
       `create (scaffold) flags:\n` +
       `  --name --package --bundle-id --region --theme-prefix\n` +
       `  --minimal   (light scaffold: app + tests + previews, no verify lane/receipts —\n` +
@@ -103,7 +129,11 @@ function printHelp() {
       `clean flags:   --target-dir <dir>  --dry-run  --yes\n` +
       `verify flags:  --target-dir <dir>  --no-ios  --dry-run\n` +
       `harden flags:  --target-dir <dir>  --dry-run  --yes  --verify (run the lane after install)\n` +
-      `attach flags:  --target-dir <dir>  --dry-run  --yes\n`
+      `attach flags:  --target-dir <dir>  --dry-run  --yes\n` +
+      `harness init flags:   --profile <id>  --target-dir <dir>  --dry-run\n` +
+      `harness relock flags: --target-dir <dir>  --dry-run\n` +
+      `  (relock covers qa/lib/profiles/<id>/** and qa/{verified-surface,harness-manifest}.json only —\n` +
+      `   a machine-owned edit is a fork and is refused by name; \`upgrade --harness\` restores it)\n`
   );
 }
 

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.23.0",
-  "description": "Create production mobile apps (Android + iOS, one Kotlin codebase) with AI — the delivery harness for Compose Multiplatform, the current generation of cross-platform (Google-backed KMP, iOS stable since May 2025). A deterministic, non-interactive generator that scaffolds a green-building app in minutes, then holds AI-driven changes to a machine-enforced verify lane with a committed evidence receipt. Every app carries a device-free UI preview loop (real screens rendered headlessly on save; changed-screen attribution and compile-error surfacing for coding agents, a live gallery for humans) plus agent-first docs (CLAUDE.md + AGENTS.md). Installs the `create-cmp` command.",
+  "version": "0.25.0",
+  "description": "Create production mobile apps (Android + iOS, one Kotlin codebase) with AI \u2014 the delivery harness for Compose Multiplatform, the current generation of cross-platform (Google-backed KMP, iOS stable since May 2025). A deterministic, non-interactive generator that scaffolds a green-building app in minutes, then holds AI-driven changes to a machine-enforced verify lane with a committed evidence receipt. Every app carries a device-free UI preview loop (real screens rendered headlessly on save; changed-screen attribution and compile-error surfacing for coding agents, a live gallery for humans) plus agent-first docs (CLAUDE.md + AGENTS.md). Installs the `create-cmp` command.",
   "type": "module",
   "bin": {
     "create-cmp": "bin/create-cmp.mjs",
     "create-cmp-cli": "bin/create-cmp.mjs"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20.19.0"
   },
   "files": [
     "bin",
@@ -74,5 +74,11 @@
   "dependencies": {
     "prompts": "^2.4.2",
     "picocolors": "^1.1.1"
-  }
+  },
+  "workspaces": [
+    "packages/harness",
+    "packages/receipts",
+    "packages/aliases/*",
+    "inspector/mcp"
+  ]
 }

package/packages/harness/package.json

@@ -1,33 +1,43 @@
 {
-  "name": "@create-cmp/harness",
-  "version": "0.18.0",
-  "description": "The create-cmp verify lane — the machine-owned harness code every stamped app carries byte-identical: evidence receipts, spec coverage, approvals, conformance reporting, golden trees, a11y, and the preview/inspector libs. Dependency-free ESM, vendored into each generated project so the lane runs offline with no install step, and content-hashed so a receipt can name the exact lane that issued it.",
+  "name": "prooflane-harness",
+  "version": "0.21.0",
+  "description": "The prooflane verify lane: a stack-agnostic evidence harness that derives done from evidence rather than an agent's word. Profile loader, lane runner, receipts, hash-locked region, Stop hook, spec-to-citation binding and the Rule 0/1/2 instruments. Dependency-free ESM, vendored into each project so a receipt is checkable offline from the repo alone, and content-hashed so a receipt names the exact lane that issued it. NOTE: this release still carries the `cmp` (Compose Multiplatform) stack profile as its source of truth; it moves to prooflane-profile-cmp in the package split.",
   "type": "module",
   "main": "src/verify.mjs",
   "exports": {
     ".": "./src/verify.mjs",
     "./harness-region": "./src/lib/harness-region.mjs",
     "./lib/*.mjs": "./src/lib/*.mjs",
-    "./lib/*": "./src/lib/*.mjs"
+    "./lib/*": "./src/lib/*.mjs",
+    "./console": "./src/console/preview-service.mjs",
+    "./console/*.mjs": "./src/console/*.mjs",
+    "./console/*": "./src/console/*.mjs"
+  },
+  "bin": {
+    "prooflane": "bin/prooflane.mjs"
   },
   "files": [
     "src",
+    "install",
+    "bin",
+    "evidence",
     "README.md"
   ],
   "scripts": {
     "test": "node --test"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20.19.0"
   },
   "keywords": [
-    "create-cmp",
+    "prooflane",
     "verify",
     "evidence",
     "receipt",
     "harness",
-    "compose-multiplatform",
-    "kotlin-multiplatform"
+    "stack-agnostic",
+    "ci",
+    "agents"
   ],
   "license": "MIT",
   "author": "Karel van der Merwe",

package/packages/harness/src/approve.mjs

@@ -1,8 +1,12 @@
 #!/usr/bin/env node
 // The approvals CLI — thin shell over qa/lib/approvals.mjs.
 //
-//   node qa/approve.mjs <artifact>          records approval (recomputes the artifact's
-//                                            hash now, stamps the time, writes qa/approvals.json)
+//   node qa/approve.mjs <artifact> [<artifact> …] --as "Name <email>"
+//                                            records approval (recomputes each artifact's
+//                                            hash now, stamps the time, writes qa/approvals.json).
+//                                            Sign every pending artifact in ONE command: each
+//                                            signature moves the receipt's input hash, so N
+//                                            separate signings cost N lane re-runs.
 //   node qa/approve.mjs --status            lists every governed artifact + live state
 //                                            (unreviewed / approved / changed-since-approval /
 //                                            reopened, + mode when set) + short hash
@@ -44,7 +48,7 @@ import {
   approveArtifact,
   getApprovalStatuses,
   getFeatureBoard,
-  isPackageResolvable,
+  isProjectGovernable,
   listGovernedArtifacts,
   readJournal,
   reopenArtifact,
@@ -118,17 +122,16 @@ if (args.includes("--status")) {
   process.exit(0);
 }
 
-// Write guard: refuse to RECORD approvals in a tree whose package is not
-// resolvable (the raw template / a pre-stamp tree). Approvals belong to a
-// generated project; writing qa/approvals.json into the template pollutes the
+// Write guard: refuse to RECORD approvals in a tree that cannot be governed —
+// no manifest, no loadable profile, or a tree the profile itself refuses (the
+// raw template, whose package is still a placeholder). Approvals belong to a
+// real project; writing qa/approvals.json into the template pollutes the
 // template itself. Read-only --status (above) stays available anywhere. Applies
 // to every write operation below (single approve, express lane, reopen).
 function refuseIfUnresolvable() {
-  if (isPackageResolvable(ROOT)) return;
-  console.error(
-    "error: this tree's package is not resolvable (composeApp/build.gradle.kts namespace is missing or still a placeholder) — " +
-      "this looks like the raw template or a pre-stamp tree. Approvals are recorded in a generated project; refusing to write qa/approvals.json here.",
-  );
+  const v = isProjectGovernable(ROOT);
+  if (v.ok) return;
+  console.error(`error: ${v.reason}`);
   process.exit(1);
 }
 
@@ -243,7 +246,7 @@ if (acceptFlagIdx !== -1) {
 if (args.length === 0) {
   const ids = listGovernedArtifacts(ROOT).map((a) => a.id);
   console.error(
-    'usage: node qa/approve.mjs <artifact> | --status | --log | --accept-defaults | --reopen <artifact> --reason "…" | --reopen-feature <name> --reason "…" | --accept <name>\n' +
+    'usage: node qa/approve.mjs <artifact> --as "Name <email>" | --status | --log | --accept-defaults | --reopen <artifact> --reason "…" | --reopen-feature <name> --reason "…" | --accept <name>\n' +
       `  valid artifacts: ${ids.length > 0 ? ids.join(", ") : "(none resolved in this project)"}`,
   );
   process.exit(1);
@@ -251,7 +254,27 @@ if (args.length === 0) {
 
 refuseIfUnresolvable();
 
-const artifactId = args[0];
+// EVERY artifact named in one command — one write, one invalidation.
+//
+// A signature changes qa/approvals.json's `status`, which the approvals gate
+// reads, so it legitimately moves the receipt's input hash. Signed one at a
+// time AFTER a green lane, that means N signatures invalidate the receipt N
+// times and cost N lane re-runs and N bookkeeping commits. Measured in
+// payment-blueprint's log on 2026-09-04: of 21 commits in one session, 8 were
+// "sign the approval" / "bind the receipt" with no product content, and every
+// code change cost two to three commits. It compounds as a repo accumulates
+// governed artifacts, which is what makes a session start fast and grind later.
+//
+// Two halves to the fix: sign them together (here), and sign BEFORE the final
+// lane run so the receipt you keep is already the one that covers the
+// signatures. `--reopen-feature` established the idiom — one recorded change,
+// not N commands.
+const artifactIds = args.filter((a, i) => !a.startsWith("--") && (i === 0 || !args[i - 1].startsWith("--")));
+// An unrecognised flag must still be REFUSED by name, never silently skipped:
+// filtering flags out is how `node qa/approve.mjs --delivr meal` would quietly
+// approve nothing and exit 0. Falling back to the first argument reproduces the
+// exact refusal an unknown verb has always produced.
+if (artifactIds.length === 0) artifactIds.push(args[0]);
 // The signer is REQUIRED, not optional: see approveArtifact's refusal. Parsed
 // here rather than defaulted from git config on purpose — `git config user.name`
 // is whatever the machine says, and an agent running on a developer's laptop
@@ -267,9 +290,14 @@ if (!approvedBy || approvedBy.startsWith("--")) {
   );
   process.exit(1);
 }
-const result = approveArtifact(ROOT, artifactId, { via: "cli", approvedBy });
-if (!result.ok) {
-  console.error(`error: ${result.reason}`);
-  process.exit(1);
+const results = artifactIds.map((id) => ({ id, result: approveArtifact(ROOT, id, { via: "cli", approvedBy }) }));
+const failed = results.filter((r) => !r.result.ok);
+for (const { id, result } of results) {
+  if (result.ok) console.log(`✓ approved ${result.artifact} — hash ${shortHash(result.hash)}, at ${result.approvedAt}`);
+  else console.error(`error: ${id}: ${result.reason}`);
+}
+if (results.length > 1) {
+  const signed = results.length - failed.length;
+  console.log(`\n${signed} signature${signed === 1 ? "" : "s"} in one write. Run the lane AFTER signing, not before — a signature moves the receipt's input hash, so signing after a green run costs you that run.`);
 }
-console.log(`✓ approved ${result.artifact} — hash ${shortHash(result.hash)}, at ${result.approvedAt}`);
+if (failed.length) process.exit(1);

package/packages/harness/src/console/console-data.mjs

@@ -0,0 +1,117 @@
+// console-data.mjs — the pure derivations the console's own section renderers
+// need, and nothing else.
+//
+// MOVED HERE from inspector/mcp/src/lib/ (design-language.mjs and
+// components.mjs) when the console moved into this package — NORTH-STAR §9,
+// stage 0.5, "the console into the harness". A reader coming from either of
+// those files should know why these four functions left them.
+//
+// The reason is the package boundary, not tidiness. `packages/harness` is
+// `prooflane-harness`, whose `files` list ships `src/` and whose whole claim
+// (PACKAGE-SPLIT.md §3) is "the console ... Knows no stack. THIS IS THE
+// PRODUCT." A console module that imported back into inspector/mcp would ship
+// with a dangling relative path — the sibling package is not in the tarball —
+// so the console cannot have a single edge pointing that way, and these were
+// the only three it had.
+//
+// What stayed behind is exactly the stack-coupled half. `getTokenUsage` scans
+// Kotlin source for a declaring `object`; `walkKtFiles`/`getComponentsData`
+// parse `.kt` signatures. Those are the eyes (PACKAGE-SPLIT.md §3,
+// `prooflane-studio-cmp`) and they stay in inspector/mcp. What moved is what a
+// console for ANY stack could use: bucket a dimens catalog by name, compute a
+// WCAG pair table from a colour catalog, and spell a component's story id.
+// None of them reads a file or names a path.
+//
+// The originals are re-exports now, so every existing import site and both
+// unit tests still resolve — one definition, two doors.
+
+import { contrastRatio } from "./contrast.mjs";
+
+// --- component story ids (was components.mjs) ---------------------------------
+
+/**
+ * PascalCase/camelCase → kebab-case: AppHeader → app-header, ListItemCard →
+ * list-item-card. Mirrors the template's qa/lib/component-stories.mjs (the
+ * lane-side parity gate) — keep the two in sync, same contract as navSlug.
+ */
+export function kebabCase(name) {
+  return String(name)
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .toLowerCase();
+}
+
+/** The preview-registry story id a component of this name registers (§3.3): `component.<kebab>`. */
+export function componentStoryId(name) {
+  return `component.${kebabCase(name)}`;
+}
+
+// --- dimens classification ----------------------------------------------------
+
+const DP_RE = /^(\d+(?:\.\d+)?)\s*dp$/;
+
+/**
+ * @param {Record<string, string>} dimens catalog dimens (name -> "16dp"-style value)
+ * @returns {{spacing: Array<{name:string,value:string,dp:number}>,
+ *            radius: Array<{name:string,value:string,dp:(number|null)}>,
+ *            elevation: Array<{name:string,value:string,dp:(number|null)}>,
+ *            other: Array<{name:string,value:string,dp:(number|null)}>}}
+ *   spacing sorted ascending by dp (it is rendered as a scale); the rest in
+ *   catalog order. A `Padding`/`Gap` token whose value doesn't parse as dp
+ *   cannot be drawn to scale — it goes to `other` (stated, not stretched).
+ */
+export function classifyDimens(dimens = {}) {
+  const spacing = [];
+  const radius = [];
+  const elevation = [];
+  const other = [];
+  for (const [name, value] of Object.entries(dimens)) {
+    const m = DP_RE.exec(String(value).trim());
+    const dp = m ? Number(m[1]) : null;
+    if (/^(Padding|Gap|Spacing)/.test(name) && dp !== null) spacing.push({ name, value, dp });
+    else if (/^Radius/.test(name)) radius.push({ name, value, dp });
+    else if (/^Elevation/.test(name)) elevation.push({ name, value, dp });
+    else other.push({ name, value, dp });
+  }
+  spacing.sort((a, b) => a.dp - b.dp || a.name.localeCompare(b.name));
+  return { spacing, radius, elevation, other };
+}
+
+// --- WCAG contrast pairs ------------------------------------------------------
+
+// Normal-text thresholds, WCAG 2.2 SC 1.4.3 (AA) / SC 1.4.6 (AAA).
+export const WCAG_AA_NORMAL = 4.5;
+export const WCAG_AAA_NORMAL = 7;
+
+/**
+ * @param {Record<string, string>} colors catalog colors (name -> hex)
+ * @returns {Array<{fg:string,bg:string,fgHex:string,bgHex:string,ratio:number,aa:boolean,aaa:boolean,role:string}>}
+ */
+export function deriveContrastPairs(colors = {}) {
+  const pairs = [];
+  const seen = new Set();
+  const add = (fg, bg, role) => {
+    if (!(fg in colors) || !(bg in colors)) return;
+    const key = `${fg}/${bg}`;
+    if (seen.has(key)) return;
+    const ratio = contrastRatio(colors[fg], colors[bg]);
+    if (ratio === null) return; // unparseable hex -> the pair is absent, not guessed
+    seen.add(key);
+    pairs.push({
+      fg,
+      bg,
+      fgHex: colors[fg],
+      bgHex: colors[bg],
+      ratio,
+      aa: ratio >= WCAG_AA_NORMAL,
+      aaa: ratio >= WCAG_AAA_NORMAL,
+      role,
+    });
+  };
+  for (const name of Object.keys(colors)) {
+    if (/^On.+/.test(name)) add(name, name.slice(2), "text on its own surface");
+  }
+  add("OnSurfaceVariant", "Surface", "secondary text on Surface");
+  add("OnSurface", "Background", "body text on Background");
+  return pairs;
+}

package/packages/harness/src/console/console-evidence.mjs

@@ -0,0 +1,122 @@
+// console-evidence.mjs — THE RUNG'S ONE SPELLING IN THIS CONSOLE.
+//
+// NORTH-STAR.md §6.5 ends with the rule this file exists to keep: "every
+// surface that shows a rung shows the pack". §8.9 says why it is a guarantee
+// and not a preference — "a `cmp` L2 and any other pack's L2 are different
+// claims and are shown as such". L2 means "a phone drove the app" under one
+// pack and "proven against a real database" under another, and the letter alone
+// does not say which. A rung with no pack beside it is therefore a claim its
+// reader cannot check, which is the one thing this product refuses everywhere
+// else; §3 already promises Gatekeeper "shows the pack beside the rung".
+//
+// WHY A MODULE AND NOT SEVEN EDITS. The console renders a rung in SEVEN places:
+// the rail foot, the front door's standing line, the recent-requests rows, the
+// Evidence section's status line, its headline chip, the committed-receipt
+// timeline, and the digest's lane-run table. NORTH-STAR.md §9.2 says "five",
+// lists six locations, and the count under the scan is seven — the miss being
+// the recent-requests rows, whose rung OUTLIVES the run that earned it. That
+// arithmetic is the argument: §9.2 closes by naming what a list costs — "a fix
+// applied to the instances rather than to the class comes back", a price that
+// section records this repository paying twice in one file. So the console does
+// not hold seven spellings of a rung. It holds one function, every surface
+// calls it, and test/evidence-ladder.test.mjs refuses any console module that
+// reads a rung another way — so an EIGHTH surface is covered the day it is
+// written, by the same inversion the agnostic lint uses, and by nobody
+// remembering a list.
+//
+// ONLY THE ID IS EVER SHOWN. `pack.version` on a receipt is today the harness
+// LOCK's version rather than the profile's — the code that writes it says so
+// ("its version is the lock's until the profile loader gives it its own") and
+// docs/adr/0008-a-resolved-harness-is-still-a-vendored-one.md decided that
+// number "must become null, not inherited". Until it does, a surface printing
+// it would be naming a version of the wrong thing, so nothing here reads it.
+// The id is the part that carries the meaning, and the id is the profile's own.
+//
+// Pure text, never HTML: every caller already owns an `esc` and its own markup,
+// and a derivation that returned tags could not be shared by a rail line, a
+// badge span and a table cell without one of them wearing another's chrome —
+// which console-shell.mjs's design rules forbid outright.
+
+/**
+ * The pack id out of whatever the caller is holding, or null.
+ *
+ * Three shapes reach the console and all three are honoured, because forcing
+ * one on the callers would mean a bridge, a git-history row and a plan-trail
+ * entry each having to remember the same normalisation:
+ *   - `"cmp"` — the flat id, how the receipt bridge and the plan trail carry it;
+ *   - `{id: "cmp", version: …}` — the receipt's own `pack` object, verbatim,
+ *     for any caller that holds the parsed receipt rather than a summary of it;
+ *   - null/undefined/`{}`/`{id: "  "}` — all of them mean the same thing, that
+ *     nothing here names a pack, and all of them are rendered as that rather
+ *     than as an absence the reader has to notice for themselves.
+ */
+function packIdOf(pack) {
+  if (typeof pack === "string") return pack.trim() || null;
+  if (pack && typeof pack === "object" && typeof pack.id === "string") return pack.id.trim() || null;
+  return null;
+}
+
+/**
+ * The rung as a reader may safely quote it: the grade, its name when there is
+ * one, and the pack that graded it — or the statement that no pack is named.
+ *
+ * `null` when there is no rung to show. That is the honest absence and it has
+ * three causes the console must not tell apart: a FAILed lane (the lane itself
+ * records no level), a receipt written before the ladder existed, and a
+ * malformed field. None of them may be rendered as a rung, so none of them is.
+ *
+ * @param {{rung?: string, name?: string}|string|null|undefined} level the
+ *   receipt's own derived `evidenceLevel`, read verbatim and never re-derived
+ *   here — the lane is the law. A bare string is accepted for the two trails
+ *   that store only the grade (the plan history's receipt glance, the digest's
+ *   lane runs), so those surfaces get the pack without inventing a name.
+ * @param {{id?: string}|string|null|undefined} pack the pack id, or the
+ *   receipt's `pack` object.
+ * @returns {string|null} e.g. `"L2 device · pack cmp"`, or
+ *   `"L2 device · pack unnamed"` when the receipt named none. The grade and its
+ *   name are joined by a SPACE and the pack by a middle dot, which is the
+ *   console's existing spelling of a rung with one clause added rather than a
+ *   new grammar: `L2 device` is what the rail foot, the front door and the
+ *   Evidence status line already read, and the dot is what the done-gate CLI
+ *   already puts before `pack`. A shared derivation is worth having; a shared
+ *   derivation that also restyles six pages is two changes wearing one commit.
+ */
+export function rungWithPack(level, pack) {
+  const grade =
+    typeof level === "string"
+      ? level.trim()
+      : level && typeof level === "object" && typeof level.rung === "string"
+        ? level.rung.trim()
+        : "";
+  if (!grade) return null;
+  const name =
+    level && typeof level === "object" && typeof level.name === "string" && level.name.trim() ? level.name.trim() : "";
+  const id = packIdOf(pack);
+  // "pack unnamed" is the wording the README badge already uses for this exact
+  // state (packages/harness/src/lib/evidence-badge.mjs) and the done-gate CLI
+  // says the same thing at greater length. One vocabulary across the surfaces
+  // matters more than each one's best phrasing: a reader who learns it on the
+  // badge reads it on the console without being taught twice.
+  return `${grade}${name ? ` ${name}` : ""} · ${id ? `pack ${id}` : "pack unnamed"}`;
+}
+
+/**
+ * The sentence that belongs in a `title=` beside a rung — why the pack is
+ * there, in the words the badge and the done-gate CLI already use.
+ *
+ * Two states, and the second is the load-bearing one. A receipt that names no
+ * pack is SAID to name none, because an unattributed rung is comparable to
+ * nothing and hiding that fact would be the overclaim the whole ladder exists
+ * to refuse. `null` when there is no rung, so a caller can build its tooltip
+ * without a second absence check.
+ *
+ * @returns {string|null}
+ */
+export function rungPackNote(level, pack) {
+  if (!rungWithPack(level, pack)) return null;
+  const grade = typeof level === "string" ? level.trim() : String(level.rung).trim();
+  const id = packIdOf(pack);
+  return id
+    ? `this rung is pack ${id}'s: a ${id} ${grade} and another pack's ${grade} are different claims`
+    : "the receipt names no pack, so this rung is comparable to nothing";
+}