create-cmp-cli 0.12.0 → 0.14.0

package/bin/create-cmp.mjs

@@ -71,6 +71,7 @@ function printHelp() {
       `  npx create-cmp create [target-dir]     same, explicit\n` +
       `  npx create-cmp doctor                  toolchain doctor + project diagnosis (any KMP project)\n` +
       `  npx create-cmp upgrade                 migrate to the next proven-green version set\n` +
+      `  npx create-cmp upgrade --harness       refresh engine-owned files of a stamped app (3-way merge)\n` +
       `  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\n` +
       `create (scaffold) flags:\n` +
@@ -83,6 +84,8 @@ function printHelp() {
       `  --target-dir  --verify/--no-verify  --yes  --force  --dry-run-verify\n\n` +
       `doctor flags:  --yes  --dry-run  --no-ios  --no-install  --target-dir <dir>  --fix\n` +
       `upgrade flags: --target-dir <dir>  --set <id>  --dry-run  --yes  --verify\n` +
+      `  --harness mode flags: --target-dir <dir>  --base-dir <extracted-template>  --dry-run  --yes\n` +
+      `  (--harness dry-runs by default; conflicts never clobber — they land as *.cmp-new sidecars)\n` +
       `clean flags:   --target-dir <dir>  --dry-run  --yes\n` +
       `verify flags:  --target-dir <dir>  --no-ios  --dry-run\n`
   );

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.12.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.14.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",
@@ -14,6 +14,10 @@
     "bin",
     "src",
     "template",
+    "packages/harness/package.json",
+    "packages/harness/src",
+    "packages/receipts/package.json",
+    "packages/receipts/src",
     "options.schema.json",
     "llms.txt"
   ],

package/packages/harness/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "create-cmp-harness",
+  "version": "0.14.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.",
+  "type": "module",
+  "main": "src/verify.mjs",
+  "exports": {
+    ".": "./src/verify.mjs",
+    "./harness-region": "./src/lib/harness-region.mjs",
+    "./lib/*": "./src/lib/*.mjs"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "create-cmp",
+    "verify",
+    "evidence",
+    "receipt",
+    "harness",
+    "compose-multiplatform",
+    "kotlin-multiplatform"
+  ],
+  "license": "MIT",
+  "author": "Karel van der Merwe",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kvdm-co-pilot/create-cmp.git",
+    "directory": "packages/harness"
+  }
+}

package/packages/harness/src/approve.mjs

@@ -0,0 +1,247 @@
+#!/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 --status            lists every governed artifact + live state
+//                                            (unreviewed / approved / changed-since-approval /
+//                                            reopened, + mode when set) + short hash
+//   node qa/approve.mjs --accept-defaults   express lane (GENESIS-FLOW-DESIGN.md §2): approves
+//                                            every currently-resolvable, not-yet-approved
+//                                            artifact, each stamped "defaults-accepted"
+//   node qa/approve.mjs --reopen <artifact> --reason "…"
+//                                            moves an approved artifact back to "reopened" for
+//                                            redesign (refuses anything not currently approved).
+//                                            --reason is REQUIRED — a reopen walks back a
+//                                            signature, and the signer must be able to read why
+//                                            from the ledger itself (2026-07-28 flow audit)
+//   node qa/approve.mjs --reopen-feature <name> --reason "…"
+//                                            one recorded change, not N reopen commands: reopens
+//                                            the brief + its spec + its design + every artifact
+//                                            the brief declares in `touches` (each only if
+//                                            currently approved), all under one reason
+//   node qa/approve.mjs --log               the journal — every approve/reopen/accept with
+//                                            when, which surface, and why (newest last)
+//   node qa/approve.mjs --accept <name>     the HUMAN's bookend on a feature brief
+//                                            (feature-brief:<name>) — refused until the feature
+//                                            is provenDone (every live clause cited + receipt
+//                                            PASS + receipt attests this tree). There is no
+//                                            --deliver: doneness is DERIVED, never claimed
+//                                            (CHANGE-FLOW-DESIGN.md §2).
+//
+// This file has NO logic of its own — every decision (the registry, hashing,
+// state, the transitions) lives in qa/lib/approvals.mjs. That's deliberate: the
+// console (VERIFICATION-LAYER-DESIGN.md §4, `POST /api/approve`; GENESIS-FLOW-DESIGN.md
+// §2, `POST /api/reopen`) calls the SAME library this CLI calls, so this file is the
+// API surface, kept intentionally thin and easy to keep in lockstep.
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  acceptFeature,
+  approveAllDefaults,
+  approveArtifact,
+  getApprovalStatuses,
+  getFeatureBoard,
+  isPackageResolvable,
+  listGovernedArtifacts,
+  readJournal,
+  reopenArtifact,
+  reopenFeature,
+} from "./lib/approvals.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const args = process.argv.slice(2);
+
+function shortHash(hash) {
+  return hash ? hash.slice(0, 8) : "none";
+}
+
+function printStatus() {
+  const statuses = getApprovalStatuses(ROOT);
+  if (statuses.length === 0) {
+    console.log("No governed artifacts resolved in this project (no specs/, or the package could not be resolved).");
+    return;
+  }
+  console.log("Approval status:\n");
+  for (const s of statuses) {
+    const mark =
+      s.status === "approved" ? "✓" : s.status === "changed-since-approval" ? "✗" : s.status === "reopened" ? "↺" : "→";
+    // An unresolvable artifact (0 files, or a partial kotlin set in a
+    // pre-stamp tree) must never display its degraded hash as if it were
+    // approvable — approval over an unresolved file set is refused.
+    const hashInfo =
+      s.status === "reopened"
+        ? `reopened at ${s.reopenedAt} (was approved ${shortHash(s.storedHash)})${s.reason ? ` — ${s.reason}` : ""}`
+        : s.status === "changed-since-approval"
+          ? s.resolvable
+            ? `approved ${shortHash(s.storedHash)} -> now ${shortHash(s.hash)}`
+            : `approved ${shortHash(s.storedHash)} -> unresolvable (${s.fileCount} of expected files resolved)`
+          : s.status === "approved"
+            ? // storedHash is the signature; s.hash is the live recompute. They
+              // agree except on a legacy raw-bytes row, where printing the live
+              // value would name a hash nobody signed.
+              `${shortHash(s.storedHash) || shortHash(s.hash)}${
+                s.hashBasis === "raw-bytes" ? ", signed pre-strip — bytes unchanged since" : ""
+              }`
+            : s.resolvable
+              ? `would approve at ${shortHash(s.hash)}`
+              : `unresolvable (${s.fileCount} of expected files resolved) — not approvable`;
+    const modeInfo = s.mode ? ` [${s.mode}]` : "";
+    // A feature brief's acceptance lives on the ledger row, never in the doc
+    // (the signed bytes must not move when the human accepts).
+    const lifecycle = s.accepted ? ` · accepted ${s.acceptedAt}` : "";
+    console.log(`${mark} ${s.id}: ${s.status} (${hashInfo})${modeInfo}${lifecycle} — ${s.label}`);
+    if (s.missing.length > 0) {
+      console.log(`    missing: ${s.missing.join(", ")}`);
+    }
+  }
+
+  // Per-feature DERIVED doneness + next step — the same getFeatureBoard the
+  // console renders, so --status and the console never tell different
+  // stories. The next step names its owner: a signature HANDS OFF, it never
+  // commands — the agent drafts/builds/proves, the human signs/accepts.
+  const { features } = getFeatureBoard(ROOT);
+  if (features.length > 0) {
+    console.log("\nFeatures (doneness is derived, never claimed):");
+    for (const f of features) {
+      const mark = f.provenDone ? "✓" : "…";
+      console.log(`  ${mark} ${f.name}: ${f.doneReason}${f.blockError ? ` — BLOCK ERROR: ${f.blockError}` : ""}`);
+      console.log(`      next → ${f.nextStep.label}${f.nextStep.owner ? ` · ${f.nextStep.owner}` : ""}`);
+    }
+  }
+}
+
+if (args.includes("--status")) {
+  printStatus();
+  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
+// 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.",
+  );
+  process.exit(1);
+}
+
+if (args.includes("--accept-defaults")) {
+  refuseIfUnresolvable();
+  const { approved, skipped } = approveAllDefaults(ROOT);
+  for (const id of approved) {
+    console.log(`✓ approved ${id} [defaults-accepted]`);
+  }
+  for (const s of skipped) {
+    console.log(`→ skipped ${s.id}: ${s.reason}`);
+  }
+  console.log(`\n${approved.length} approved (defaults-accepted), ${skipped.length} skipped (unresolvable).`);
+  process.exit(0);
+}
+
+// --reason is shared by --reopen and --reopen-feature: one plain sentence for
+// the human who signed, recorded on the ledger row AND the journal. The library
+// refuses without it; parsing it here just makes the usage line honest.
+const reasonFlagIdx = args.indexOf("--reason");
+const reason = reasonFlagIdx !== -1 ? args[reasonFlagIdx + 1] : undefined;
+
+if (args.includes("--log")) {
+  const events = readJournal(ROOT);
+  if (events.length === 0) {
+    console.log("No journal yet (qa/approvals.log.jsonl) — it starts recording with the next approve/reopen/accept.");
+    process.exit(0);
+  }
+  console.log("Governance journal (oldest first):\n");
+  for (const e of events) {
+    const mark = e.verb === "approve" ? "✓" : e.verb === "reopen" ? "↺" : e.verb === "accept" ? "◆" : "·";
+    const bits = [e.via ? `via ${e.via}` : null, e.mode ? `[${e.mode}]` : null, e.feature ? `feature ${e.feature}` : null]
+      .filter(Boolean)
+      .join(" · ");
+    console.log(`${mark} ${e.at}  ${e.verb} ${e.artifact}${bits ? ` (${bits})` : ""}${e.reason ? ` — ${e.reason}` : ""}`);
+  }
+  process.exit(0);
+}
+
+const reopenFlagIdx = args.indexOf("--reopen");
+if (reopenFlagIdx !== -1) {
+  refuseIfUnresolvable();
+  const artifactId = args[reopenFlagIdx + 1];
+  if (!artifactId || artifactId === "--reason") {
+    console.error('usage: node qa/approve.mjs --reopen <artifact> --reason "why, in one sentence"');
+    process.exit(1);
+  }
+  const result = reopenArtifact(ROOT, artifactId, { reason, via: "cli" });
+  if (!result.ok) {
+    console.error(`error: ${result.reason}`);
+    process.exit(1);
+  }
+  console.log(`↺ reopened ${result.artifact} for redesign — at ${result.reopenedAt}\n  reason: ${reason.trim()}`);
+  process.exit(0);
+}
+
+// One recorded change, not N reopen commands (2026-07-28 flow audit, fix 4):
+// the brief is the container the human thinks in — reopen its whole declared
+// set under one reason, each journal event grouped by the feature's name.
+const reopenFeatureFlagIdx = args.indexOf("--reopen-feature");
+if (reopenFeatureFlagIdx !== -1) {
+  refuseIfUnresolvable();
+  const name = args[reopenFeatureFlagIdx + 1];
+  if (!name || name === "--reason") {
+    console.error('usage: node qa/approve.mjs --reopen-feature <name> --reason "why, in one sentence"');
+    process.exit(1);
+  }
+  const result = reopenFeature(ROOT, name, { reason, via: "cli" });
+  if (!result.ok) {
+    console.error(`error: ${result.reason}`);
+    process.exit(1);
+  }
+  console.log(`↺ reopened feature "${result.feature}" as one change — reason: ${reason.trim()}`);
+  for (const id of result.reopened) console.log(`  ↺ ${id}`);
+  for (const s of result.skipped) console.log(`  → skipped ${s.id} (${s.status})`);
+  process.exit(0);
+}
+
+// The human's bookend: --accept takes the brief NAME, not the full artifact
+// id — the docs/features/<name>.md filename is what a human knows. The library
+// refuses until the feature is provenDone; there is no agent claim in between.
+const acceptFlagIdx = args.indexOf("--accept");
+if (acceptFlagIdx !== -1) {
+  refuseIfUnresolvable();
+  const name = args[acceptFlagIdx + 1];
+  if (!name) {
+    console.error("usage: node qa/approve.mjs --accept <name>   (the brief's name — docs/features/<name>.md)");
+    process.exit(1);
+  }
+  const result = acceptFeature(ROOT, name, { via: "cli" });
+  if (!result.ok) {
+    console.error(`error: ${result.reason}`);
+    process.exit(1);
+  }
+  console.log(`✓ accepted ${result.artifact} at ${result.acceptedAt} — the feature's card closes; the brief is its doc-of-record.`);
+  process.exit(0);
+}
+
+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' +
+      `  valid artifacts: ${ids.length > 0 ? ids.join(", ") : "(none resolved in this project)"}`,
+  );
+  process.exit(1);
+}
+
+refuseIfUnresolvable();
+
+const artifactId = args[0];
+const result = approveArtifact(ROOT, artifactId, { via: "cli" });
+if (!result.ok) {
+  console.error(`error: ${result.reason}`);
+  process.exit(1);
+}
+console.log(`✓ approved ${result.artifact} — hash ${shortHash(result.hash)}, at ${result.approvedAt}`);

package/packages/harness/src/arch-doc.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// The architecture-doc generator/checker — thin shell over qa/lib/arch-doc.mjs,
+// mirroring qa/approve.mjs's CLI-over-library split.
+//
+//   node qa/arch-doc.mjs            regenerate docs/ARCHITECTURE.md's
+//                                    `cmp:generated` sections in place from a
+//                                    real tree walk — touches NOTHING outside
+//                                    the markers
+//   node qa/arch-doc.mjs --check    exit nonzero (naming every stale/missing
+//                                    section) if regenerating would change the
+//                                    file; never writes
+//
+// This file has no logic of its own — every decision (what each section
+// derives from, the marker grammar) lives in qa/lib/arch-doc.mjs. The verify
+// lane's `archDoc` step (qa/verify.mjs) calls the SAME library in --check mode.
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { ARCH_DOC_REL_PATH, regenerateArchDoc, writeArchDoc } from "./lib/arch-doc.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const checkOnly = process.argv.includes("--check");
+
+function reportUnknown(result) {
+  if (result.unknownSections.length === 0) return false;
+  console.error(
+    `error: ${ARCH_DOC_REL_PATH} has cmp:generated marker(s) with no registered generator: ${result.unknownSections.join(", ")}`,
+  );
+  return true;
+}
+
+if (checkOnly) {
+  const result = regenerateArchDoc(ROOT);
+  if (!result.ok) {
+    console.error(`error: ${result.reason}`);
+    process.exit(1);
+  }
+  if (reportUnknown(result)) process.exit(1);
+
+  const stale = result.changed || result.missingSections.length > 0;
+  if (!stale) {
+    console.log(`✓ ${ARCH_DOC_REL_PATH} is fresh — every generated section matches the tree.`);
+    process.exit(0);
+  }
+
+  console.error(`✗ ${ARCH_DOC_REL_PATH} is stale:`);
+  for (const id of result.changedSections) {
+    console.error(`  [${id}] regenerating would change this section — the tree no longer matches the doc`);
+  }
+  for (const id of result.missingSections) {
+    console.error(`  [${id}] marker missing from the doc entirely — never generated`);
+  }
+  console.error("Run: node qa/arch-doc.mjs");
+  process.exit(1);
+}
+
+const result = writeArchDoc(ROOT);
+if (!result.ok) {
+  console.error(`error: ${result.reason}`);
+  process.exit(1);
+}
+if (reportUnknown(result)) process.exit(1);
+
+if (!result.wrote) {
+  console.log(`✓ ${ARCH_DOC_REL_PATH} already fresh — nothing to regenerate.`);
+  process.exit(0);
+}
+console.log(`✓ regenerated ${ARCH_DOC_REL_PATH} — updated section(s): ${result.changedSections.join(", ")}`);

package/packages/harness/src/comment.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// The comments CLI — thin shell over qa/lib/comments.mjs (mirrors qa/approve.mjs).
+//
+//   node qa/comment.mjs --list [--open]              readable table of the ledger,
+//                                                     including resolution notes
+//   node qa/comment.mjs --resolve <id> --note "..."  resolves a comment as "agent-cli",
+//                                                     recording the note explaining
+//                                                     what changed as a result
+//
+// This file has NO logic of its own — every decision (validation, ids, the ledger)
+// lives in qa/lib/comments.mjs. Adding a comment is a console/human action (the
+// console's `POST /api/comment` calls the same library through a bridge); this CLI
+// covers the agent's side of the loop of record: observe, act, resolve.
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { listComments, resolveComment } from "./lib/comments.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const args = process.argv.slice(2);
+
+function argValue(flag) {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx === args.length - 1) return undefined;
+  return args[idx + 1];
+}
+
+function printList(openOnly) {
+  let result;
+  try {
+    result = listComments(ROOT, openOnly ? { status: "open" } : {});
+  } catch (err) {
+    console.error(`error: ${err.message}`);
+    process.exit(1);
+  }
+  if (result.comments.length === 0) {
+    console.log(openOnly ? "No open comments." : "No comments recorded yet.");
+    return;
+  }
+  console.log(`Comments${openOnly ? " (open only)" : ""}:\n`);
+  for (const c of result.comments) {
+    const mark = c.status === "resolved" ? "✓" : "→";
+    console.log(`${mark} ${c.id} [${c.target?.type ?? "unknown"}] ${c.status} — by ${c.author} at ${c.createdAt}`);
+    console.log(`    ${c.text}`);
+    if (c.status === "resolved") {
+      const note = c.resolutionNote ? `: ${c.resolutionNote}` : " (no note)";
+      console.log(`    resolved by ${c.resolvedBy} at ${c.resolvedAt}${note}`);
+    }
+  }
+}
+
+if (args.includes("--list")) {
+  printList(args.includes("--open"));
+  process.exit(0);
+}
+
+if (args.includes("--resolve")) {
+  const id = argValue("--resolve");
+  if (!id) {
+    console.error('usage: node qa/comment.mjs --resolve <id> --note "..."');
+    process.exit(1);
+  }
+  const note = argValue("--note");
+  const result = resolveComment(ROOT, id, { note, author: "agent-cli" });
+  if (!result.ok) {
+    console.error(`error: ${result.reason}`);
+    process.exit(1);
+  }
+  const noteSuffix = result.comment.resolutionNote ? ` — ${result.comment.resolutionNote}` : "";
+  console.log(`✓ resolved ${result.comment.id}${noteSuffix}`);
+  process.exit(0);
+}
+
+console.error('usage: node qa/comment.mjs --list [--open] | --resolve <id> --note "..."');
+process.exit(1);

package/packages/harness/src/lib/a11y.mjs

@@ -0,0 +1,113 @@
+// a11y.mjs — accessibility audit over the tree contract.
+// Pure logic only — no fs, no MCP imports; unit-testable.
+//
+// Rules (violations):
+//   touch-target-too-small — a clickable node whose width or height is below the
+//                            minimum touch target (default 48px; the harness dumps
+//                            at density 1 so px == dp there — pass a different
+//                            minTouchTargetPx for device-density trees). Judged on the
+//                            FULL composed size (the tree's additive `size` field) when
+//                            present: `bounds` is the visible slice after ancestor
+//                            clipping, so a list row bisected by a scroll fold reports
+//                            e.g. 371x36 while measuring 371x88 — a scroll-position
+//                            artifact, never an a11y defect. Trees without `size`
+//                            (older dumps) are judged on bounds, as before.
+//   missing-label          — a clickable node with no text, no contentDescription,
+//                            and no descendant text: nothing for a screen reader.
+// Rules (warnings):
+//   empty-content-description — contentDescription === "" (redundant/empty; either
+//                               label it or drop the attribute).
+//
+// Trees produced before the role/clickable/disabled contract extension are handled
+// gracefully: nodes without `clickable` are simply skipped, never crashed on.
+
+import { walk } from "./tree.mjs";
+
+/**
+ * Audit a tree for accessibility faults.
+ *
+ * @param {object} tree  a full tree ({root}) or bare node.
+ * @param {{minTouchTargetPx?: number}} [opts]
+ * @returns {{
+ *   violations: Array<{path:string, testTag:string|null, rule:string, detail:string, bounds:object|null}>,
+ *   warnings:   Array<{path:string, testTag:string|null, rule:string, detail:string, bounds:object|null}>,
+ *   warningCount: number,
+ *   passCount: number
+ * }}  passCount = clickable nodes that passed every check.
+ */
+export function auditA11y(tree, opts = {}) {
+  const minTouchTargetPx =
+    typeof opts.minTouchTargetPx === "number" && opts.minTouchTargetPx > 0
+      ? opts.minTouchTargetPx
+      : 48;
+
+  const violations = [];
+  const warnings = [];
+  let passCount = 0;
+
+  for (const { node, path } of walk(tree)) {
+    const entryBase = {
+      path,
+      testTag: node.testTag ?? null,
+      bounds: node.bounds ?? null,
+    };
+
+    // Warn on redundant/empty contentDescription regardless of clickability.
+    if (node.contentDescription === "") {
+      warnings.push({
+        ...entryBase,
+        rule: "empty-content-description",
+        detail: 'contentDescription is an empty string ("") — either label the node or drop the attribute',
+      });
+    }
+
+    // Interactive checks only apply to nodes that self-report clickable:true.
+    // Old trees without the optional field are skipped gracefully.
+    if (node.clickable !== true) continue;
+
+    let violated = false;
+
+    // Judge the FULL composed size when the dump carries it (`size` is unclipped; `bounds`
+    // is the visible slice after ancestor clipping — see the rule doc above). max() keeps
+    // the check honest either way: a genuinely small target is small in both.
+    const b = node.bounds;
+    const s = node.size;
+    const dim = (bv, sv) =>
+      Math.max(typeof bv === "number" ? bv : -1, typeof sv === "number" ? sv : -1);
+    const width = dim(b && b.width, s && s.width);
+    const height = dim(b && b.height, s && s.height);
+    if (width >= 0 && height >= 0 && (width < minTouchTargetPx || height < minTouchTargetPx)) {
+      violations.push({
+        ...entryBase,
+        rule: "touch-target-too-small",
+        detail: `clickable node is ${width}x${height}px; minimum touch target is ${minTouchTargetPx}x${minTouchTargetPx}px`,
+      });
+      violated = true;
+    }
+
+    const hasOwnLabel =
+      (node.text != null && node.text !== "") ||
+      (node.contentDescription != null && node.contentDescription !== "");
+    if (!hasOwnLabel && !hasDescendantText(node)) {
+      violations.push({
+        ...entryBase,
+        rule: "missing-label",
+        detail: "clickable node has no text, no contentDescription, and no descendant text — invisible to screen readers",
+      });
+      violated = true;
+    }
+
+    if (!violated) passCount++;
+  }
+
+  return { violations, warnings, warningCount: warnings.length, passCount };
+}
+
+function hasDescendantText(node) {
+  for (const child of node.children || []) {
+    if (child.text != null && child.text !== "") return true;
+    if (child.contentDescription != null && child.contentDescription !== "") return true;
+    if (hasDescendantText(child)) return true;
+  }
+  return false;
+}