create-cmp-cli 0.17.1 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.17.1",
+  "version": "0.18.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.",
   "type": "module",
   "bin": {

package/packages/harness/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@create-cmp/harness",
-  "version": "0.15.0",
+  "version": "0.16.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",

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

@@ -1063,7 +1063,10 @@ export function reopenFeature(root, name, options = {}) {
     return { ok: false, reason: `unknown feature "${name}" — known briefs: ${briefs.join(", ") || "(none)"}` };
   }
   const derived = deriveAllFeatures(root).find((d) => d.name === name);
-  const set = [briefId, `feature-spec:${name}`, `${FEATURE_DESIGN_PREFIX}${name}`, ...(derived ? derived.touches : [])];
+  // The spec side of the family follows the brief's own pairing (a multi-spec
+  // brief reopens every spec its promises live in), defaulting to the name.
+  const specIds = (derived?.specNames ?? [name]).map((n) => `feature-spec:${n}`);
+  const set = [briefId, ...specIds, `${FEATURE_DESIGN_PREFIX}${name}`, ...(derived ? derived.touches : [])];
   const byId = new Map(getApprovalStatuses(root).map((s) => [s.id, s]));
   const reopened = [];
   const skipped = [];
@@ -1274,7 +1277,12 @@ export function getFeatureBoard(root) {
   // feature-spec:* that is still signed must be reopened and amended, and the
   // step says so by name — that is what the human's signature set in motion.
   const deriveNextStep = (d, phase) => {
-    const specArtifact = byId.get(`feature-spec:${d.name}`);
+    // The brief's PAIRED specs (feature-brief.mjs pairedSpecNames — the one
+    // pairing function): a multi-spec brief waits on ALL of them being
+    // signed, and its contract step names each one still waiting.
+    const specArtifacts = (d.specNames ?? [d.name])
+      .map((n) => byId.get(`feature-spec:${n}`))
+      .filter(Boolean);
     const designArtifact = byId.get(`${FEATURE_DESIGN_PREFIX}${d.name}`) ?? null;
     const declaredSpecAmendments = d.touches
       .filter((id) => id.startsWith("feature-spec:") && byId.get(id)?.status === "approved")
@@ -1343,8 +1351,9 @@ export function getFeatureBoard(root) {
     // phase === "approved": building — which part of the loop is open?
     if (!d.specExists || d.total === 0)
       return { key: "contract", owner: "agent drafts → human signs", label: `contract: write the clauses in ${d.specRel}${amendNote}` };
-    if (specArtifact && specArtifact.status !== "approved")
-      return { key: "sign-spec", owner: "human", label: `sign the contract (feature-spec:${d.name})${amendNote}` };
+    const unsignedSpecs = specArtifacts.filter((a) => a.status !== "approved");
+    if (unsignedSpecs.length > 0)
+      return { key: "sign-spec", owner: "human", label: `sign the contract (${unsignedSpecs.map((a) => a.id).join(", ")})${amendNote}` };
     if (d.covered < d.total)
       return { key: "build", owner: "agent", label: `build & cite: ${d.total - d.covered} clause(s) have no citing test yet` };
     return { key: "prove", owner: "agent", label: "prove: run node qa/verify.mjs so the receipt attests this tree" };

package/packages/harness/src/lib/feature-brief.mjs

@@ -7,8 +7,9 @@
 // docs/features/ is a governed `feature-brief:<name>` artifact, hashed and
 // signed like anything else, approved BEFORE the feature is built. (Harness
 // design standards stay in docs/proposals/ — different directory, different
-// meaning.) `<name>` matches the feature's spec: docs/features/meal.md pairs
-// with specs/meal.spec.md.
+// meaning.) `<name>` pairs with the feature's spec — by default
+// specs/<name>.spec.md, overridable by the brief itself when its promises
+// genuinely live in several spec files (see pairedSpecNames).
 //
 // The brief carries at most ONE machine-read block, and it declares — it never
 // gates:
@@ -163,30 +164,90 @@ export function briefSections(markdown) {
 
 /**
  * A brief's declarations: blast radius (`touches`), UI surface (`screens`),
- * and the reachability exemption (`unrouted` — FI-7's escape hatch: a screen
- * intentionally not wired into the navigation graph yet). A missing block, or
- * one without a field, declares nothing — legal and common. A block that IS
- * present but malformed is surfaced as `error`: a doc that tried to declare
- * and failed should say so, not read as "declares nothing".
+ * the reachability exemption (`unrouted` — FI-7's escape hatch: a screen
+ * intentionally not wired into the navigation graph yet), and the paired
+ * spec files (`specs` — walk-legibility L1: spec NAMES, no path/extension;
+ * `"specs": ["catalog", "entry-editing"]`). A missing block, or one without a
+ * field, declares nothing — legal and common. A block that IS present but
+ * malformed is surfaced as `error`: a doc that tried to declare and failed
+ * should say so, not read as "declares nothing".
  * @param {string} markdown
- * @returns {{touches: string[], screens: boolean, unrouted: boolean, error: (string|null)}}
+ * @returns {{touches: string[], screens: boolean, unrouted: boolean, specs: string[], error: (string|null)}}
  */
 export function parseFeatureBlock(markdown) {
   const m = typeof markdown === "string" ? markdown.match(FEATURE_FENCE_RE) : null;
-  if (!m) return { touches: [], screens: false, unrouted: false, error: null };
+  if (!m) return { touches: [], screens: false, unrouted: false, specs: [], error: null };
   let parsed;
   try {
     parsed = JSON.parse(m[1]);
   } catch (err) {
-    return { touches: [], screens: false, unrouted: false, error: `cmp:feature block is not valid JSON — ${err.message}` };
+    return { touches: [], screens: false, unrouted: false, specs: [], error: `cmp:feature block is not valid JSON — ${err.message}` };
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    return { touches: [], screens: false, unrouted: false, error: "cmp:feature must be a JSON object" };
+    return { touches: [], screens: false, unrouted: false, specs: [], error: "cmp:feature must be a JSON object" };
   }
   const touches = Array.isArray(parsed.touches)
     ? parsed.touches.filter((t) => typeof t === "string" && t.trim() !== "")
     : [];
-  return { touches, screens: parsed.screens === true, unrouted: parsed.unrouted === true, error: null };
+  // `specs` entries are normalized to bare names ("specs/catalog.spec.md" and
+  // "catalog" both mean specs/catalog.spec.md) — declaring in either form is
+  // fine; storing one form keeps every consumer's arithmetic identical.
+  const specs = Array.isArray(parsed.specs)
+    ? [
+        ...new Set(
+          parsed.specs
+            .filter((s) => typeof s === "string" && s.trim() !== "")
+            .map((s) => s.trim().replace(/^specs\//, "").replace(/\.spec\.md$/, "")),
+        ),
+      ]
+    : [];
+  return { touches, screens: parsed.screens === true, unrouted: parsed.unrouted === true, specs, error: null };
+}
+
+/**
+ * The spec files a brief's promises live in — THE pairing function
+ * (walk-legibility L1). One definition, consumed by the board derivation, the
+ * walk, and (through them) the console, so no surface can pair differently.
+ * Precedence:
+ *   1. the cmp:feature block's `"specs": [...]` — the explicit declaration
+ *   2. the brief's `**Spec:**` paragraph — every `specs/<name>.spec.md`
+ *      reference in it (the form briefs already carry for human readers)
+ *   3. the filename default: `specs/<name>.spec.md`
+ * Before this existed, a brief whose blast radius genuinely spans two specs
+ * (catalog-and-editing, showcase 2026-08-26) derived as "still awaiting a
+ * contract" forever — a standing false instruction on the primary surface
+ * that invites an agent to write a second definition of signed behavior.
+ * @param {string} markdown the brief's full text
+ * @param {string} name the brief's name (docs/features/<name>.md)
+ * @param {{specs?: string[]}} [block] a parseFeatureBlock result, if the
+ *   caller already has one (avoids re-parsing; same answer either way)
+ * @returns {string[]} spec names, e.g. ["catalog", "entry-editing"]
+ */
+export function pairedSpecNames(markdown, name, block) {
+  const declared = (block ?? parseFeatureBlock(markdown)).specs ?? [];
+  if (declared.length > 0) return declared;
+  const fromHeader = specHeaderNames(markdown);
+  if (fromHeader.length > 0) return fromHeader;
+  return [name];
+}
+
+/**
+ * Every `specs/<name>.spec.md` referenced in the brief's `**Spec:**`
+ * paragraph — the line starting `**Spec:**` through the next blank line, so
+ * later prose that merely MENTIONS a spec path never redirects the pairing.
+ */
+function specHeaderNames(markdown) {
+  if (typeof markdown !== "string") return [];
+  const lines = markdown.split("\n");
+  const start = lines.findIndex((l) => /^\*\*Spec:?\*\*/.test(l.trim()));
+  if (start === -1) return [];
+  const para = [];
+  for (let i = start; i < lines.length && lines[i].trim() !== ""; i++) para.push(lines[i]);
+  const out = [];
+  for (const m of para.join("\n").matchAll(/specs\/([A-Za-z0-9_-]+)\.spec\.md/g)) {
+    if (!out.includes(m[1])) out.push(m[1]);
+  }
+  return out;
 }
 
 /**
@@ -262,12 +323,21 @@ export function deriveFeatureStatus(root, brief, pre = {}) {
   } catch {
     readable = false;
   }
-  const block = readable ? parseFeatureBlock(markdown) : { touches: [], screens: false, error: `${brief.rel} could not be read` };
+  const block = readable
+    ? parseFeatureBlock(markdown)
+    : { touches: [], screens: false, specs: [], error: `${brief.rel} could not be read` };
 
-  const specRel = `specs/${brief.name}.spec.md`;
-  const specExists = fs.existsSync(path.join(root, specRel));
+  // The paired specs (walk-legibility L1): usually one, by filename; a brief
+  // may name several. Clauses concatenate in declaration order — "done" means
+  // every live clause across ALL of them is cited.
+  const specNames = pairedSpecNames(markdown, brief.name, block);
+  const specRels = specNames.map((n) => `specs/${n}.spec.md`);
+  const specExists = specRels.every((rel) => fs.existsSync(path.join(root, rel)));
+  const specRel = specRels.join(" + ");
   const citedIds = new Set((pre.citations ?? scanCitations(root)).map((t) => t.id));
-  const clauses = clausesOfSpec(root, specRel).map((c) => ({ ...c, cited: citedIds.has(c.id) }));
+  const clauses = specRels
+    .flatMap((rel) => clausesOfSpec(root, rel))
+    .map((c) => ({ ...c, cited: citedIds.has(c.id) }));
   const live = clauses.filter((c) => !c.withdrawn);
   const covered = live.filter((c) => c.cited).length;
 
@@ -286,6 +356,8 @@ export function deriveFeatureStatus(root, brief, pre = {}) {
     // rung's only mechanical signal (see countEdgeCases).
     edgeCases: readable ? countEdgeCases(markdown) : 0,
     specRel,
+    specNames,
+    specRels,
     specExists,
     clauses,
     covered,

package/packages/harness/src/lib/inputs-hash.mjs

@@ -48,7 +48,15 @@ export const VERIFIED_SURFACE = [
 // bookkeeping about a commit that already happened, so appending a record
 // must never invalidate a receipt for a tree whose code did not change
 // (approvals.log.jsonl's principle, applied to audits).
+// qa/.request.json and qa/.plan.json are the live chain's EPHEMERAL state
+// (studio-drive-mode): the request file is rewritten on EVERY user prompt by
+// the UserPromptSubmit hook, so hashing either would invalidate the receipt
+// the moment the human speaks. They are also gitignored on fresh scaffolds,
+// but the exclusion here is the load-bearing one — upgraded apps keep their
+// own .gitignore, which never learns new entries.
 const EXCLUDED_PREFIXES = [
+  "qa/.plan.json",
+  "qa/.request.json",
   "qa/evidence",
   "qa-artifacts",
   "qa/comments.json",

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

@@ -0,0 +1,200 @@
+// plan.mjs — the live chain: what the CURRENT REQUEST is, which step the
+// agent is on, and what comes next. docs/features/studio-drive-mode.md is the
+// brief of record; this is D8's itinerary (walk-status.md) promoted from
+// kickoff prose to a tracked object.
+//
+// PROVENANCE TIERS, each rendered as what it is — this is the one surface in
+// the harness that is not purely derived, and the design is honest about it:
+//
+//   1. The REQUEST is machinery-owned: the UserPromptSubmit hook records the
+//      human's own prompt verbatim (walk-status --inject reads it from the
+//      hook's stdin). No agent claim involved.
+//   2. The STEPS are agent-declared: written once at kickoff (`node
+//      qa/plan.mjs --set`), advanced as work lands (`--step N`). Every
+//      rendering carries the declaration's age — a stale plan reads as
+//      stale, never as true.
+//   3. The CORROBORATION is derived and overrides: the lane/render markers
+//      (composeApp/build/.cmp-lane-in-progress / .cmp-render-in-progress,
+//      mtime-bounded like every other consumer) say what is ACTUALLY running
+//      right now, regardless of what was declared.
+//
+// THE PLAN GATES NOTHING. The walk (walk.mjs — a pure projection) stays the
+// load-bearing truth for doneness; the chain is a windshield, not an
+// instrument. Both live in EPHEMERAL dot-files that are excluded from the
+// receipt's hashed input surface (qa/lib/inputs-hash.mjs EXCLUDED_PREFIXES —
+// a request recorded on every prompt must never invalidate a receipt) and
+// gitignored on fresh scaffolds.
+//
+// FAIL-SOFT EVERYWHERE: readers return null, writers return {ok:false} — a
+// status surface never breaks the work it reports on.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const PLAN_REL = "qa/.plan.json";
+export const REQUEST_REL = "qa/.request.json";
+
+// A marker older than this is a crashed writer, not a live run — the same
+// bound qa/watch.mjs and the preview daemon apply to the same files.
+const MARKER_FRESH_MS = 5 * 60 * 1000;
+const MAX_REQUEST_CHARS = 500;
+const MAX_STEPS = 20;
+const MAX_LABEL_CHARS = 120;
+
+function readJson(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(p, value) {
+  try {
+    fs.writeFileSync(p, `${JSON.stringify(value, null, 2)}\n`);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, reason: err?.message ?? String(err) };
+  }
+}
+
+/**
+ * Record the human's latest prompt — tier 1, machinery-owned. Called by the
+ * UserPromptSubmit hook path with the hook's own `prompt` field; never by
+ * the agent with words of its own choosing.
+ */
+export function recordRequest(root, text) {
+  const t = typeof text === "string" ? text.trim() : "";
+  if (t === "") return { ok: false, reason: "empty prompt — nothing to record" };
+  return writeJson(path.join(root, REQUEST_REL), {
+    text: t.length > MAX_REQUEST_CHARS ? `${t.slice(0, MAX_REQUEST_CHARS - 1)}…` : t,
+    at: new Date().toISOString(),
+  });
+}
+
+/** @returns {{text: string, at: string}|null} */
+export function readRequest(root) {
+  const r = readJson(path.join(root, REQUEST_REL));
+  return r && typeof r.text === "string" ? r : null;
+}
+
+/**
+ * Declare the chain — tier 2, agent-declared, said so on every rendering.
+ * `title` is the agent's triage restatement of the ask (the contract already
+ * mandates one); `steps` are plain labels in order. Declaring replaces any
+ * previous chain: one request, one chain.
+ */
+export function setPlan(root, { title, feature, steps } = {}) {
+  const labels = (Array.isArray(steps) ? steps : [])
+    .map((s) => String(s ?? "").trim())
+    .filter((s) => s !== "")
+    .slice(0, MAX_STEPS)
+    .map((s) => (s.length > MAX_LABEL_CHARS ? `${s.slice(0, MAX_LABEL_CHARS - 1)}…` : s));
+  if (labels.length === 0) return { ok: false, reason: "a chain needs at least one step" };
+  return writeJson(path.join(root, PLAN_REL), {
+    title: typeof title === "string" && title.trim() !== "" ? title.trim() : null,
+    feature: typeof feature === "string" && feature.trim() !== "" ? feature.trim() : null,
+    steps: labels.map((label, i) => ({ n: i + 1, label, done: false })),
+    current: 1,
+    updatedAt: new Date().toISOString(),
+  });
+}
+
+/**
+ * Advance to step `n`: everything before it is done, `n` is current. `--done`
+ * (n past the end) closes the chain. Refuses without a declared chain —
+ * advancing nothing would fabricate a plan that was never stated.
+ */
+export function markStep(root, n) {
+  const plan = readJson(path.join(root, PLAN_REL));
+  if (!plan || !Array.isArray(plan.steps) || plan.steps.length === 0)
+    return { ok: false, reason: "no declared chain — declare one first: node qa/plan.mjs --set \"step | step | …\"" };
+  const step = Number(n);
+  if (!Number.isInteger(step) || step < 1 || step > plan.steps.length + 1)
+    return { ok: false, reason: `step must be 1..${plan.steps.length + 1} (=${plan.steps.length + 1} closes the chain), got ${n}` };
+  for (const s of plan.steps) s.done = s.n < step;
+  plan.current = step > plan.steps.length ? null : step;
+  plan.updatedAt = new Date().toISOString();
+  return writeJson(path.join(root, PLAN_REL), plan).ok ? { ok: true, plan } : { ok: false, reason: "could not write the chain" };
+}
+
+/** @returns {object|null} the declared chain, or null. */
+export function readPlan(root) {
+  const p = readJson(path.join(root, PLAN_REL));
+  return p && Array.isArray(p.steps) ? p : null;
+}
+
+/** Clear the chain (a landed request leaves no stale windshield behind). */
+export function clearPlan(root) {
+  try {
+    fs.rmSync(path.join(root, PLAN_REL), { force: true });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, reason: err?.message ?? String(err) };
+  }
+}
+
+function markerFresh(root, name) {
+  try {
+    const st = fs.statSync(path.join(root, "composeApp", "build", name));
+    return Date.now() - st.mtimeMs < MARKER_FRESH_MS;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Everything a chain-rendering surface needs, with provenance attached:
+ * request (tier 1) + plan with its age (tier 2) + what is ACTUALLY running
+ * (tier 3 — the markers the lane and preview daemon already stamp).
+ * @returns {{request: (object|null), plan: (object|null), planAgeMs: (number|null),
+ *   busy: {lane: boolean, render: boolean}}}
+ */
+export function deriveChain(root) {
+  const plan = readPlan(root);
+  const at = plan ? Date.parse(plan.updatedAt) : NaN;
+  return {
+    request: readRequest(root),
+    plan,
+    planAgeMs: Number.isNaN(at) ? null : Math.max(0, Date.now() - at),
+    busy: {
+      lane: markerFresh(root, ".cmp-lane-in-progress"),
+      render: markerFresh(root, ".cmp-render-in-progress"),
+    },
+  };
+}
+
+/** "40s ago" / "12 min ago" — freshness a human can weigh at a glance. */
+export function formatAge(ms) {
+  if (!(ms >= 0)) return "age unknown";
+  if (ms < 90000) return `${Math.round(ms / 1000)}s ago`;
+  if (ms < 90 * 60000) return `${Math.round(ms / 60000)} min ago`;
+  return `${Math.round(ms / 3600000)}h ago`;
+}
+
+/**
+ * The chain as one text block — the CLI's and the inject's rendering.
+ * Numbered steps: done ✓, current ◉ (with tier-3 corroboration when a lane
+ * or render is genuinely in flight), pending ○. "" when nothing is declared
+ * AND no request is recorded (silence, never an empty frame).
+ */
+export function renderChain(chain) {
+  if (!chain || (!chain.plan && !chain.request)) return "";
+  const lines = [];
+  const title = chain.plan?.title ?? chain.request?.text ?? null;
+  if (title) lines.push(`Request: ${title}`);
+  if (chain.plan) {
+    const p = chain.plan;
+    const seq = p.steps
+      .map((s) => `${s.done ? "✓" : s.n === p.current ? "◉" : "○"} ${s.n}. ${s.label}`)
+      .join("  →  ");
+    lines.push(seq);
+    const cur = p.steps.find((s) => s.n === p.current) ?? null;
+    const busy = chain.busy?.lane ? " · the full check is running NOW" : chain.busy?.render ? " · a preview render is in flight" : "";
+    const age = chain.planAgeMs !== null ? ` · declared by the agent, updated ${formatAge(chain.planAgeMs)}` : "";
+    lines.push(cur ? `now: step ${cur.n} of ${p.steps.length} — ${cur.label}${busy}${age}` : `chain complete${busy}${age}`);
+  } else {
+    lines.push("(no declared chain for this request yet — node qa/plan.mjs --set \"step | step | …\")");
+  }
+  return lines.join("\n");
+}