create-cmp-cli 0.17.1 → 0.18.0

package/template/CLAUDE.md

@@ -317,21 +317,47 @@ evidence attached"). `node qa/walk-status.mjs` derives the live position; a
 UserPromptSubmit hook injects it every prompt. **Render the injected state — never
 your memory of it.**
 
-**At kickoff** (with the triage restatement): print the itinerary —
+**At kickoff** (with the triage restatement): print the itinerary — and DECLARE it as
+the live chain, so the studio's Drive strip and the statusline's readers see the same
+steps you just printed:
 
     Navigation redesign — the journey (brief lane)
     Decide → Design → Contract → Build → Prove → Sign-off
     Stops for you: 3 (Decide — now · Contract · Sign-off). Build and Prove never stop for you.
     First stop is now: 2 open decisions below.
 
-**While working — quiet:** one line per stage transition, nothing per-file. The
-statusline carries the position continuously; do not repeat it in prose.
-
-**At every human gate — loud:** a full stop card, never a bare question:
+```bash
+node qa/plan.mjs --set "sign the brief | draft screens | agree the promises | build | full check | your sign-off" --title "navigation redesign"
+```
 
-    ■ YOUR TURN — <feature> · stage 3 of 6: Contract
+**The chain stays current** — this is part of the contract, not a nicety: advance it
+with `node qa/plan.mjs --step N` as each step lands and `--done` when the request
+lands. The current request itself is recorded mechanically (the per-prompt hook), the
+steps are yours to declare, and every surface shows the declaration's age — a stale
+chain reads as stale to the human watching the studio, which is worse than no chain.
+The chain gates nothing; the walk stays the truth for doneness.
+
+**The studio is a standing check:** every injected context opens with a `[studio: …]`
+line. If it says DOWN or not running, restore it before proceeding — call the
+cmp-inspector `preview { projectDir }` tool (it starts a detached resident console
+that survives the session) — or, if the tools are absent, tell the human once. A
+missing window is a fault to heal, never something to work silently past.
+
+**While working — the header, then quiet:** open EVERY reply with the walk's one-line
+header — the exact `[chat header]` line the per-prompt inject delivers. Paste it
+verbatim, never compose it: it is the derivation's own string, so it cannot drift, and
+it persists in the transcript, which the statusline beneath the input box never does.
+After the header: one line per stage transition, nothing per-file. Stages carry their
+plain-words gloss on first mention ("Contract — agreeing what it promises"); quote the
+lane's cost only from the measured figure in the injected card, never an estimate.
+
+**At every human gate — loud:** a full stop card, never a bare question — and the
+easiest act leads:
+
+    ■ YOUR TURN — <feature> · stage 3 of 6: Contract — agreeing what it promises
     <what it is, in plain words — two lines maximum>
-    → <exactly what to do: the command, or the studio tab, or "reply approve">
+    → Easiest: the studio console at <url from the injected card> — the row carries the button.
+    → CLI fallback: <the command>   (or "reply approve" when no console is up)
     After this: <the remaining stages, and which ones stop for the human>
 
 **Arrivals:** work that belongs to no open walk (undeclared drift, a harness

package/template/gitignore

@@ -34,3 +34,10 @@ xcuserdata/
 # ignored by git. Delete them once you have reviewed the upgrade's diff.
 *.bak-upgrade
 *.cmp-new
+
+# The live chain's ephemeral state (studio-drive-mode): the current request
+# (rewritten by the UserPromptSubmit hook on every prompt) and the agent's
+# declared step plan. Per-session windshield, not project history — and also
+# hard-excluded from the receipt's hashed input surface (qa/lib/inputs-hash.mjs).
+qa/.request.json
+qa/.plan.json

package/template/qa/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/template/qa/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/template/qa/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/template/qa/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");
+}