create-cmp-cli 0.10.1 → 0.12.0

package/template/qa/lib/approvals.mjs

@@ -10,20 +10,22 @@
 //
 // Three concerns, kept separable:
 //   1. The REGISTRY (`listGovernedArtifacts`) — artifact id -> resolved file list, in
-//      GENESIS-FLOW-DESIGN.md §1 order: intent(0), architecture(1), exemplar-spec(2),
-//      exemplar-feature(3), design-system(4), components(5), then one
-//      `feature-spec:<name>` (6+) per non-base, non-exemplar spec file present in
-//      specs/ right now. (Spec-first: the exemplar's clauses are confirmed before the
-//      slice is built. UI-first: design system + components are distilled from the
-//      real screens, so they lock after the exemplar.) The exemplar (2/3) is
+//      definition order (GENESIS-FLOW-DESIGN.md §1 + CHANGE-FLOW-DESIGN.md §6):
+//      intent(0), feature-brief:<name> per docs/features/*.md (the decide layer,
+//      directly after intent), architecture, exemplar-spec, exemplar-feature,
+//      design-system, components, then one `feature-spec:<name>` per non-base,
+//      non-exemplar spec file present in specs/ right now. (Decide-first: a brief
+//      speaks intent's vocabulary. Spec-first: the exemplar's clauses are confirmed
+//      before the slice is built. UI-first: design system + components are distilled
+//      from the real screens, so they lock after the exemplar.) The exemplar is
 //      CONFIGURABLE — see
 //      `getExemplarFeature`/`resolveExemplarNames` below — defaulting to `home` so
 //      every ledger written before this config key existed keeps meaning what it
 //      meant. The registry is recomputed on every call — it reflects the tree as it
 //      stands, never a stale snapshot.
 //   2. STATE (`loadApprovals`/`saveApprovals`) — qa/approvals.json, the human's
-//      decisions: { artifact, status, hash, approvedAt, mode?, reopenedAt? } plus the
-//      top-level `exemplarFeature` config key. Absent or corrupt is TOLERATED
+//      decisions: { artifact, status, hash, approvedAt, mode?, reopenedAt?, via?,
+//      reason? } plus the top-level `exemplarFeature` config key. Absent or corrupt is TOLERATED
 //      (treated as empty / all-unreviewed / default exemplar) — this ledger must
 //      never crash the verify lane or the stamper.
 //
@@ -57,9 +59,20 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { ARCH_DOC_REL_PATH, stripGeneratedSections } from "./arch-doc.mjs";
+import { deriveAllFeatures, deriveFeatureStatus, listFeatureBriefs, parseFeatureBlock, stripFeatureBlock } from "./feature-brief.mjs";
 
 export const APPROVALS_REL_PATH = "qa/approvals.json";
 export const APPROVALS_SCHEMA = "cmp-approvals/1";
+// The JOURNAL (2026-07-28 flow audit, fix 1): qa/approvals.json is a mutable
+// snapshot — every transition overwrites the row, so the ledger cannot answer
+// "what happened while I was away?". The journal is the append-only memory
+// beside it: one JSON line per human-meaningful transition (approve / reopen /
+// accept), each carrying {at, verb, artifact, via, reason?}. State stays
+// DERIVED from the snapshot exactly as before; the journal gates nothing and
+// no lane step reads it — which is why it sits in inputs-hash.mjs's
+// EXCLUDED_PREFIXES (like qa/comments.json): appending history must never
+// invalidate the receipt for a tree whose code did not change.
+export const APPROVALS_JOURNAL_REL_PATH = "qa/approvals.log.jsonl";
 
 // Kotlin source-set roots, relative to project root — mirrors qa/scaffold-feature.mjs's
 // SRC() helper (composeApp/src/<sourceSet>/kotlin/<packageDir>).
@@ -234,6 +247,41 @@ function listComponentFiles(root) {
     .sort((a, b) => a.localeCompare(b));
 }
 
+// ── Feature screens glob ────────────────────────────────────────────────────
+
+/** The `feature-design:` id prefix — one place, so the CLI/console/gate never drift on it. */
+export const FEATURE_DESIGN_PREFIX = "feature-design:";
+
+/**
+ * The screen files of one feature — `presentation/<name>/**\/*Screen.kt`,
+ * recursive, sorted. DELIBERATELY only `*Screen.kt`: the design signature
+ * covers the FORM (what renders), so binding the whole presentation dir would
+ * make every ViewModel edit during a legitimate build read as design drift.
+ * @param {string} root
+ * @param {string} name the feature name (presentation/<name>/)
+ * @returns {string[]} repo-relative posix paths
+ */
+function listFeatureScreenFiles(root, name) {
+  const dirRel = kotlinFile(root, "commonMain", `presentation/${name}`);
+  if (!dirRel) return [];
+  const out = [];
+  const walk = (rel) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(path.join(root, rel), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const childRel = path.posix.join(rel, e.name);
+      if (e.isDirectory()) walk(childRel);
+      else if (e.isFile() && e.name.endsWith("Screen.kt")) out.push(childRel);
+    }
+  };
+  walk(dirRel);
+  return out.sort((a, b) => a.localeCompare(b));
+}
+
 // ── Registry ─────────────────────────────────────────────────────────────────
 
 /**
@@ -246,9 +294,11 @@ function listComponentFiles(root) {
  *   VISUAL artifacts are UI-FIRST — the design system and component vocabulary
  *   are distilled FROM the real screens, so they lock AFTER the exemplar
  *   exists (a provisional palette carries the build until then).
- * Order: intent(0), architecture(1), exemplar-spec(2), exemplar-feature(3),
- * design-system(4), components(5), then one feature-spec:<name> (6+) per
- * non-base, non-CONFIGURED-exemplar spec present.
+ * Order: intent(0), then feature-brief:<name> per docs/features/*.md — the
+ * DECIDE layer sits directly after intent (a brief speaks intent's
+ * vocabulary; only the SPEC needs architecture's) — then architecture,
+ * exemplar-spec, exemplar-feature, design-system, components, and one
+ * feature-spec:<name> per non-base, non-CONFIGURED-exemplar spec present.
  *
  * `complete: false` marks an artifact whose kotlin-rooted files could NOT be
  * resolved (unresolvable package — raw template / pre-stamp tree). Such an
@@ -269,6 +319,24 @@ export function listGovernedArtifacts(root) {
     complete: true,
   });
 
+  // Feature briefs (feature-brief.mjs): one `feature-brief:<name>` per doc
+  // under docs/features/ — LOCATION is the governance opt-in (CHANGE-FLOW-
+  // DESIGN.md §2); docs/proposals/ stays ungoverned harness-standards prose.
+  // They sit DIRECTLY after intent: the decide layer. At genesis the first
+  // feature's brief is drafted from the intent interview before architecture
+  // is even walked; post-genesis every decision-carrying change enters here.
+  // Approving one hashes the doc's bytes, so a signed brief cannot be quietly
+  // rewritten; acceptance is a LEDGER field on the same row (acceptFeature
+  // below), so the human's bookend never touches the signed bytes.
+  for (const brief of listFeatureBriefs(root)) {
+    artifacts.push({
+      id: `feature-brief:${brief.name}`,
+      label: `Feature brief (${brief.rel})`,
+      files: [brief.rel],
+      complete: true,
+    });
+  }
+
   artifacts.push({
     id: "architecture",
     label: `Architecture + structure (${ARCHITECTURE_SPEC_REL} + ${ARCH_DOC_REL_PATH}, generated sections stripped)`,
@@ -323,6 +391,32 @@ export function listGovernedArtifacts(root) {
     complete: packageResolved,
   });
 
+  // Feature designs (brief → design → spec → build, decided 2026-07-25): one
+  // `feature-design:<name>` per BRIEF with a UI surface — declared
+  // (`"screens": true` in the cmp:feature block, so the gate exists before any
+  // file does) or evident (presentation/<name>/*Screen.kt on disk). Signed on
+  // RENDERED output, never descriptions, BEFORE the behavior contract pins the
+  // form down. Briefs only, deliberately: legacy features (governed by
+  // exemplar-feature or nothing) never sprout retro-governance. With no screen
+  // files yet, `complete: false` — approveArtifact refuses, exactly right: you
+  // cannot sign a design that has nothing rendered.
+  for (const brief of listFeatureBriefs(root)) {
+    let declaresScreens = false;
+    try {
+      declaresScreens = parseFeatureBlock(fs.readFileSync(path.join(root, brief.rel), "utf8")).screens;
+    } catch {
+      /* an unreadable brief declares nothing */
+    }
+    const screenFiles = listFeatureScreenFiles(root, brief.name);
+    if (!declaresScreens && screenFiles.length === 0) continue;
+    artifacts.push({
+      id: `${FEATURE_DESIGN_PREFIX}${brief.name}`,
+      label: `Feature design (${brief.name} — presentation/${brief.name}/*Screen.kt, signed on rendered output)`,
+      files: screenFiles,
+      complete: packageResolved && screenFiles.length > 0,
+    });
+  }
+
   const specsDir = path.join(root, "specs");
   if (fs.existsSync(specsDir)) {
     const featureSpecs = fs
@@ -455,7 +549,49 @@ export function hashArchitectureArtifact(root) {
  * @returns {{ hash: string, fileCount: number, missing: string[] }}
  */
 function computeArtifactHash(root, artifact) {
-  return artifact.id === "architecture" ? hashArchitectureArtifact(root) : hashArtifactFiles(root, artifact.files);
+  if (artifact.id === "architecture") return hashArchitectureArtifact(root);
+  if (artifact.id.startsWith(FEATURE_BRIEF_PREFIX)) return hashFeatureBriefArtifact(root, artifact);
+  return hashArtifactFiles(root, artifact.files);
+}
+
+/**
+ * A feature brief's hash basis: the doc's content, EOL-normalized, with the
+ * cmp:feature declaration block stripped (`stripFeatureBlock` — the ONE
+ * definition of the block grammar, shared with parseFeatureBlock so the
+ * stripper and the parser can never disagree about what a block is).
+ *
+ * Same rationale as `hashArchitectureArtifact`'s cmp:generated stripping: the
+ * human signs the brief's reasoning; `touches`/`screens` are declarations the
+ * harness independently enforces (artifact hashes enforce blast radius; disk
+ * presence enforces the design gate) and can authorise nothing — so adding
+ * mandatory machine-read metadata to a signed brief must never manufacture a
+ * human re-approval. Normalized `\r\n` -> `\n` first, because the fence
+ * grammar matches a literal `\n` and a checkout-induced EOL flip in prose must
+ * never read as authored drift.
+ * @param {string} root
+ * @param {{id: string, files: string[]}} artifact
+ * @returns {{ hash: string, fileCount: number, missing: string[] }}
+ */
+function hashFeatureBriefArtifact(root, artifact) {
+  const files = [...new Set(artifact.files)].sort();
+  const rows = [];
+  const missing = [];
+  for (const relPath of files) {
+    let raw;
+    try {
+      raw = fs.readFileSync(path.join(root, relPath), "utf8");
+    } catch {
+      missing.push(relPath);
+      continue;
+    }
+    const stripped = stripFeatureBlock(raw.replace(/\r\n/g, "\n"));
+    rows.push([relPath, createHash("sha256").update(stripped, "utf8").digest("hex")]);
+  }
+  const overall = createHash("sha256");
+  for (const [relPath, fileSha] of rows) {
+    overall.update(`${relPath}\0${fileSha}\n`);
+  }
+  return { hash: overall.digest("hex"), fileCount: rows.length, missing };
 }
 
 // ── State (qa/approvals.json) ─────────────────────────────────────────────────
@@ -512,6 +648,56 @@ export function saveApprovals(root, state) {
   fs.writeFileSync(p, `${JSON.stringify(out, null, 2)}\n`);
 }
 
+// ── The journal (append-only; the snapshot above stays the derived state) ────
+
+/**
+ * Append one transition to qa/approvals.log.jsonl. TOLERANT — a failed append
+ * (read-only fs, weird mount) must never block the transition it records, so
+ * this returns {ok:false} rather than throwing; the snapshot write (the state
+ * that gates) has already happened or is about to, and history-keeping is
+ * strictly subordinate to it.
+ * @param {string} root
+ * @param {{verb: string, artifact: string, via?: string, reason?: string, [k: string]: unknown}} event
+ * @returns {{ok: boolean}}
+ */
+export function appendJournal(root, event) {
+  const p = path.join(root, APPROVALS_JOURNAL_REL_PATH);
+  try {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.appendFileSync(p, `${JSON.stringify({ at: new Date().toISOString(), ...event })}\n`);
+    return { ok: true };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/**
+ * Every journal event, oldest first. Absent file -> []. A corrupt LINE is
+ * skipped, never fatal (same tolerance stance as loadApprovals) — one mangled
+ * append must not blind the console to the rest of the history.
+ * @param {string} root
+ * @returns {Array<{at: string, verb: string, artifact: string, via?: string, reason?: string}>}
+ */
+export function readJournal(root) {
+  let raw;
+  try {
+    raw = fs.readFileSync(path.join(root, APPROVALS_JOURNAL_REL_PATH), "utf8");
+  } catch {
+    return [];
+  }
+  const events = [];
+  for (const line of raw.split("\n")) {
+    if (line.trim() === "") continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed && typeof parsed === "object" && typeof parsed.verb === "string") events.push(parsed);
+    } catch {
+      /* skip the mangled line, keep the history */
+    }
+  }
+  return events;
+}
+
 /**
  * The configured exemplar feature's lowercase name (the package-segment form,
  * e.g. `"home"`, `"favorites"`) — `qa/approvals.json`'s top-level
@@ -573,7 +759,15 @@ function shortHash(hash) {
  * stored record actually carries them — never as an explicit `undefined` key, so
  * structural equality checks against a plain unreviewed/approved status shape
  * still hold.
- * @returns {{id: string, label: string, status: string, hash: string, storedHash: (string|null), approvedAt: (string|null), fileCount: number, missing: string[], resolvable: boolean, mode?: string, reopenedAt?: string}}
+ *
+ * `hash` is always the LIVE recompute and `storedHash` always what was actually
+ * signed. They are equal for every artifact signed on the current basis, which is
+ * why they are easy to conflate — but a display that means "the signature" must
+ * read `storedHash`. The one case where they legitimately differ on an `approved`
+ * row is `hashBasis: "raw-bytes"` (below): the stored hash is on a superseded
+ * basis, so the live recompute is a number NOBODY EVER SIGNED and must never be
+ * labelled as one.
+ * @returns {{id: string, label: string, status: string, hash: string, storedHash: (string|null), approvedAt: (string|null), fileCount: number, missing: string[], resolvable: boolean, mode?: string, reopenedAt?: string, hashBasis?: string}}
  */
 export function resolveArtifactStatus(root, artifact, storedRecord) {
   const recomputed = computeArtifactHash(root, artifact);
@@ -591,6 +785,11 @@ export function resolveArtifactStatus(root, artifact, storedRecord) {
       missing: recomputed.missing,
       resolvable,
       reopenedAt: storedRecord.reopenedAt,
+      // Attribution (2026-07-28 flow audit): who walked the signature back and
+      // why, read straight off the row — surfaced only when actually recorded
+      // (pre-audit rows carry neither; absence is the honest answer there).
+      ...(storedRecord.via ? { via: storedRecord.via } : {}),
+      ...(storedRecord.reason ? { reason: storedRecord.reason } : {}),
     };
   }
 
@@ -607,7 +806,27 @@ export function resolveArtifactStatus(root, artifact, storedRecord) {
       resolvable,
     };
   }
-  const changed = !resolvable || storedRecord.hash !== recomputed.hash;
+  let changed = !resolvable || storedRecord.hash !== recomputed.hash;
+  // Legacy feature-brief approvals (pre block-stripping) stored the RAW-bytes
+  // hash. If the stored hash still matches the raw bytes on disk, the file is
+  // byte-identical to what the human signed — strictly stronger than a
+  // stripped-basis match — so the signature stands. Permanent and safe: this
+  // path can only accept content that has not changed at all since signing.
+  let hashBasis = null;
+  if (
+    changed &&
+    resolvable &&
+    artifact.id.startsWith(FEATURE_BRIEF_PREFIX) &&
+    storedRecord.hash === hashArtifactFiles(root, artifact.files).hash
+  ) {
+    changed = false;
+    // Say so. This is the ONE approved state where storedHash !== hash
+    // legitimately, and a row that shows the disagreement without naming its
+    // cause is indistinguishable from tolerated drift — the exact ambiguity the
+    // governance surface exists to remove. Emitted only when the path actually
+    // fires; absence means "signed on the current basis", the normal case.
+    hashBasis = "raw-bytes";
+  }
   return {
     id: artifact.id,
     label: artifact.label,
@@ -618,7 +837,13 @@ export function resolveArtifactStatus(root, artifact, storedRecord) {
     fileCount: recomputed.fileCount,
     missing: recomputed.missing,
     resolvable,
+    ...(hashBasis ? { hashBasis } : {}),
     ...(storedRecord.mode ? { mode: storedRecord.mode } : {}),
+    // Feature-brief acceptance (acceptFeature) — surfaced only when the row
+    // actually carries the fields, same stance as `mode`: never an explicit
+    // `undefined` key, so plain-status structural equality still holds.
+    ...(storedRecord.via ? { via: storedRecord.via } : {}),
+    ...(storedRecord.accepted ? { accepted: true, acceptedAt: storedRecord.acceptedAt ?? null } : {}),
   };
 }
 
@@ -652,12 +877,18 @@ export function getApprovalStatuses(root) {
  * unresolvable (raw template / pre-stamp tree), the artifact's expected files
  * are all missing on disk, or (a dynamic artifact, e.g. `components`) nothing
  * currently matches its pattern.
+ * A fresh approval also clears a feature brief's `accepted` field: re-signing
+ * a brief whose bytes changed is a NEW signature over new content, and an
+ * acceptance given against the old content does not carry over — the human
+ * re-accepts once the new content is provenDone again. Same wholesale-replace
+ * semantics that already clear `mode`/`reopenedAt`.
  * @param {string} root
  * @param {string} artifactId
- * @param {{mode?: string}} [options] `mode` (e.g. `"defaults-accepted"`) is
- *   stamped onto the record when the express lane approves a resolvable-but-
- *   unshaped artifact (GENESIS-FLOW-DESIGN.md §2). Omitted for a normal/real
- *   approval.
+ * @param {{mode?: string, via?: string}} [options] `mode` (e.g.
+ *   `"defaults-accepted"`) is stamped onto the record when the express lane
+ *   approves a resolvable-but-unshaped artifact (GENESIS-FLOW-DESIGN.md §2).
+ *   Omitted for a normal/real approval. `via` records the surface the approval
+ *   came through (`"console"` / `"cli"`) — an audit field, never behavior.
  * @returns {{ok: true, artifact: string, hash: string, approvedAt: string, mode?: string} | {ok: false, reason: string}}
  */
 export function approveArtifact(root, artifactId, options = {}) {
@@ -691,8 +922,16 @@ export function approveArtifact(root, artifactId, options = {}) {
   const approvedAt = new Date().toISOString();
   const record = { artifact: artifactId, status: "approved", hash: resolved.hash, approvedAt };
   if (options.mode) record.mode = options.mode;
+  if (options.via) record.via = options.via;
   others.push(record);
   saveApprovals(root, { artifacts: others, exemplarFeature: state.exemplarFeature });
+  appendJournal(root, {
+    verb: "approve",
+    artifact: artifactId,
+    hash: resolved.hash,
+    ...(options.via ? { via: options.via } : {}),
+    ...(options.mode ? { mode: options.mode } : {}),
+  });
   return { ok: true, artifact: artifactId, hash: resolved.hash, approvedAt, ...(options.mode ? { mode: options.mode } : {}) };
 }
 
@@ -730,11 +969,33 @@ export function approveAllDefaults(root) {
  * artifact whose LIVE status is not `"approved"` — reopening the unreviewed, the
  * already-reopened, or a changed-since-approval artifact is meaningless (there is
  * nothing sanctioned to walk back from).
+ *
+ * REFUSES a missing `reason` (2026-07-28 flow audit, fix 2): a reopen is a
+ * state change on a SIGNED document — the one act in this file that walks back
+ * a human's signature. The ledger used to record neither who did it nor why,
+ * so the signer came back to "reopened" with no way to learn what happened.
+ * ECO discipline: every change to a released document carries initiator and
+ * justification, mechanically required. `via`/`reason` land on the row (they
+ * are outside the inputs-hash projection, so no receipt is invalidated) and
+ * in the journal.
  * @param {string} root
  * @param {string} artifactId
+ * @param {{reason: string, via?: string, feature?: string}} options `reason` is
+ *   REQUIRED — one plain sentence for the human who signed. `via` records the
+ *   surface ("console"/"cli"). `feature` groups the reopens of one
+ *   `reopenFeature` walk under the brief's name.
  * @returns {{ok: true, artifact: string, reopenedAt: string} | {ok: false, reason: string}}
  */
-export function reopenArtifact(root, artifactId) {
+export function reopenArtifact(root, artifactId, options = {}) {
+  const why = typeof options.reason === "string" ? options.reason.trim() : "";
+  if (why === "") {
+    return {
+      ok: false,
+      reason:
+        `cannot reopen "${artifactId}" without a reason — a reopen walks back a signature, and the signer ` +
+        `must be able to read why from the ledger itself. Pass one plain sentence (CLI: --reason "…").`,
+    };
+  }
   const registry = listGovernedArtifacts(root);
   const artifact = registry.find((a) => a.id === artifactId);
   if (!artifact) {
@@ -752,14 +1013,82 @@ export function reopenArtifact(root, artifactId) {
   }
   const others = state.artifacts.filter((a) => a.artifact !== artifactId);
   const reopenedAt = new Date().toISOString();
-  const record = { artifact: artifactId, status: "reopened", hash: stored.hash, approvedAt: stored.approvedAt, reopenedAt };
+  const record = { artifact: artifactId, status: "reopened", hash: stored.hash, approvedAt: stored.approvedAt, reopenedAt, reason: why };
+  if (options.via) record.via = options.via;
   others.push(record);
   saveApprovals(root, { artifacts: others, exemplarFeature: state.exemplarFeature });
+  appendJournal(root, {
+    verb: "reopen",
+    artifact: artifactId,
+    reason: why,
+    ...(options.via ? { via: options.via } : {}),
+    ...(options.feature ? { feature: options.feature } : {}),
+  });
   // `artifact` is the ID STRING — the same convention approveArtifact returns
   // (one library, one shape; the console bridge relies on the symmetry).
   return { ok: true, artifact: artifactId, reopenedAt };
 }
 
+/**
+ * Reopen one FEATURE as one recorded change (2026-07-28 flow audit, fix 4):
+ * the brief is the change container — a human edits "the meal-plan feature",
+ * not four artifact ids at four timestamps. This walks the brief's set —
+ * `feature-brief:<name>`, `feature-spec:<name>`, `feature-design:<name>`, and
+ * every artifact the brief DECLARES in `touches` — and reopens each one that
+ * is currently `approved`, all under the same reason, each journal event
+ * carrying `feature: <name>` so the history reads as one change.
+ *
+ * Artifacts in the set that are not currently approved are SKIPPED and
+ * reported (already reopened, unreviewed, or drifted — each already tells its
+ * own story; silently "fixing" their state here would erase it). Refuses only
+ * when the set contains nothing approved at all — then there is no signature
+ * to walk back and the caller's premise is wrong.
+ * @param {string} root
+ * @param {string} name the brief's name (docs/features/<name>.md)
+ * @param {{reason: string, via?: string}} options same contract as reopenArtifact
+ * @returns {{ok: true, feature: string, reopened: string[], skipped: Array<{id: string, status: string}>} | {ok: false, reason: string}}
+ */
+export function reopenFeature(root, name, options = {}) {
+  const why = typeof options.reason === "string" ? options.reason.trim() : "";
+  if (why === "") {
+    return {
+      ok: false,
+      reason: `cannot reopen feature "${name}" without a reason — pass one plain sentence (CLI: --reason "…").`,
+    };
+  }
+  const briefId = `${FEATURE_BRIEF_PREFIX}${name}`;
+  const registry = listGovernedArtifacts(root);
+  if (!registry.some((a) => a.id === briefId)) {
+    const briefs = registry.filter((a) => a.id.startsWith(FEATURE_BRIEF_PREFIX)).map((a) => a.id.slice(FEATURE_BRIEF_PREFIX.length));
+    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 : [])];
+  const byId = new Map(getApprovalStatuses(root).map((s) => [s.id, s]));
+  const reopened = [];
+  const skipped = [];
+  for (const id of [...new Set(set)]) {
+    const live = byId.get(id);
+    if (!live) continue; // declared touch that resolves to no governed artifact — nothing to reopen
+    if (live.status !== "approved") {
+      skipped.push({ id, status: live.status });
+      continue;
+    }
+    const result = reopenArtifact(root, id, { reason: why, via: options.via, feature: name });
+    if (result.ok) reopened.push(id);
+    else skipped.push({ id, status: `refused: ${result.reason}` });
+  }
+  if (reopened.length === 0) {
+    return {
+      ok: false,
+      reason:
+        `nothing in "${name}"'s set is currently approved — there is no signature to walk back. ` +
+        `Set: ${[...new Set(set)].join(", ")}; states: ${skipped.map((s) => `${s.id}=${s.status}`).join(", ") || "(unresolved)"}`,
+    };
+  }
+  return { ok: true, feature: name, reopened, skipped };
+}
+
 // ── The verify-lane gate ─────────────────────────────────────────────────────
 
 /**
@@ -807,7 +1136,7 @@ export function evaluateApprovalsGate(root) {
     for (const s of pending) {
       if (s.status === "reopened") {
         lines.push(
-          `  [${s.id}] ${s.label} — reopened for redesign at ${s.reopenedAt} (non-blocking until re-approved). Approve: node qa/approve.mjs ${s.id}`,
+          `  [${s.id}] ${s.label} — reopened for redesign at ${s.reopenedAt}${s.reason ? ` (reason: ${s.reason})` : ""} (non-blocking until re-approved). Approve: node qa/approve.mjs ${s.id}`,
         );
       } else if (!s.resolvable) {
         lines.push(`  [${s.id}] ${s.label} — unreviewed, currently unresolvable (${s.fileCount} of expected files resolved) — not approvable in this tree.`);
@@ -820,3 +1149,255 @@ export function evaluateApprovalsGate(root) {
 
   return { verdict: "PASS", reason: undefined, statuses };
 }
+
+// ── Feature-brief lifecycle (feature-brief.mjs is the doc/doneness model; ────
+// ── this file owns the LEDGER side: `accepted` lives on the approval row) ────
+
+/** The `feature-brief:` id prefix — one place, so the CLI/console/gate never drift on it. */
+export const FEATURE_BRIEF_PREFIX = "feature-brief:";
+
+/**
+ * The human's bookend: mark a feature brief `accepted` — "the proven thing is
+ * what I wanted" (CHANGE-FLOW-DESIGN.md §1). There is no agent claim in
+ * between: doneness is DERIVED (deriveFeatureStatus — clauses cited, receipt
+ * PASS, receipt attests this tree), so acceptance refuses until the harness
+ * can prove done, and needs nothing else.
+ *
+ * Refusals, each a real gap in the acceptance's standing:
+ *   - unknown brief (no docs/features/<name>.md)
+ *   - brief not approved (accepting an unsigned plan attests nothing — the
+ *     walk is sign the brief, build, then accept), and a drifted brief must be
+ *     re-approved first (the bytes being accepted must be the bytes signed)
+ *   - not provenDone (the refusal quotes the derived doneReason verbatim —
+ *     uncited clause, red receipt, or a receipt attesting an older tree)
+ * Acceptance never gates the lane — it closes the card, on the human's schedule.
+ * @param {string} root
+ * @param {string} name the brief's name (docs/features/<name>.md)
+ * @param {{via?: string}} [options] `via` records the surface ("console"/"cli") in the journal
+ * @returns {{ok: true, artifact: string, acceptedAt: string} | {ok: false, reason: string}}
+ */
+export function acceptFeature(root, name, options = {}) {
+  const artifactId = `${FEATURE_BRIEF_PREFIX}${name}`;
+  const registry = listGovernedArtifacts(root);
+  const artifact = registry.find((a) => a.id === artifactId);
+  if (!artifact) {
+    const briefs = registry.filter((a) => a.id.startsWith(FEATURE_BRIEF_PREFIX)).map((a) => a.id.slice(FEATURE_BRIEF_PREFIX.length));
+    return {
+      ok: false,
+      reason: `unknown feature brief "${name}" — known briefs: ${briefs.join(", ") || "(none — a brief is any docs/features/<name>.md; the location is the governance opt-in)"}`,
+    };
+  }
+  const state = loadApprovals(root);
+  const stored = state.artifacts.find((a) => a.artifact === artifactId);
+  const live = resolveArtifactStatus(root, artifact, stored);
+  if (live.status !== "approved") {
+    return {
+      ok: false,
+      reason:
+        `cannot accept "${name}" — the brief is "${live.status}", not "approved". ` +
+        (live.status === "changed-since-approval"
+          ? `It changed after sign-off; re-approve it first (node qa/approve.mjs ${artifactId}).`
+          : "The walk is: sign the brief, build, then accept the proven result."),
+    };
+  }
+  // The design signature is part of the contract (brief → design → spec →
+  // build): a feature with a UI surface cannot be accepted past an unsigned
+  // or drifted design — "the proven thing is what I wanted" includes its form.
+  const designArtifact = registry.find((a) => a.id === `${FEATURE_DESIGN_PREFIX}${name}`);
+  if (designArtifact) {
+    const designStored = state.artifacts.find((a) => a.artifact === designArtifact.id);
+    const designLive = resolveArtifactStatus(root, designArtifact, designStored);
+    if (designLive.status !== "approved") {
+      return {
+        ok: false,
+        reason:
+          `cannot accept "${name}" — feature-design:${name} is "${designLive.status}", not "approved". ` +
+          `The feature's screens are signed on rendered output before acceptance (node qa/approve.mjs feature-design:${name}).`,
+      };
+    }
+  }
+  const derived = deriveFeatureStatus(root, { name, rel: artifact.files[0] });
+  if (!derived.provenDone) {
+    return { ok: false, reason: `cannot accept "${name}" — not provenDone: ${derived.doneReason}` };
+  }
+  const acceptedAt = new Date().toISOString();
+  // MERGE into the approved row (not wholesale-replace): the signature —
+  // hash/approvedAt/mode/via — must survive the acceptance verbatim. Contrast
+  // approveArtifact, where replacement is the point (a new signature clears
+  // an old acceptance).
+  const next = state.artifacts.map((a) => (a.artifact === artifactId ? { ...a, accepted: true, acceptedAt } : a));
+  saveApprovals(root, { artifacts: next, exemplarFeature: state.exemplarFeature });
+  appendJournal(root, { verb: "accept", artifact: artifactId, ...(options.via ? { via: options.via } : {}) });
+  return { ok: true, artifact: artifactId, acceptedAt };
+}
+
+/**
+ * The console's per-feature view — every brief with its full live state, in
+ * one call, so the section renders without composing (the console never
+ * re-implements the model; VERIFICATION-LAYER-DESIGN.md §4).
+ *
+ * Per feature: the DERIVED doneness (deriveFeatureStatus — clauses with their
+ * citation state, receipt attestation, provenDone, the one-line doneReason),
+ * the brief's approval record, a phase for the card chip, and the DECLARED
+ * blast radius resolved against each touched artifact's live status — so the
+ * console can render "components: changed-since-approval (as declared)" as
+ * expected work, not alarm.
+ *
+ * Phase vocabulary (CHANGE-FLOW-DESIGN.md §6): `proposed` (no signature yet) →
+ * `approved` (signed, building) → `proven` (provenDone, awaiting the human) →
+ * `accepted`; a drifted or reopened brief reads as itself.
+ *
+ * `undeclared`: governed artifacts currently `changed-since-approval` that NO
+ * open brief (approved, not yet accepted) declared in `touches` — with the
+ * feature-brief/feature-spec families excluded (a brief's own doc drifting is
+ * its card's business; spec drift is the feature-spec artifact's own row). The
+ * plan drifted from reality; the console shows it as exactly that.
+ * @param {string} root
+ * @returns {{features: Array<object>, undeclared: Array<{id: string, label: string}>}}
+ */
+// How many recorded edge cases satisfy the `audit` rung. A count cannot judge an
+// audit's QUALITY — it can only insist the pass happened and left written output,
+// which is the whole point: findings then land in the same signing round rather
+// than reopening a signed artifact. One is too easy to satisfy accidentally;
+// three is the smallest number that requires actually looking.
+const MIN_AUDITED_EDGE_CASES = 3;
+
+export function getFeatureBoard(root) {
+  const statuses = getApprovalStatuses(root);
+  const byId = new Map(statuses.map((s) => [s.id, s]));
+
+  // The DERIVED next step (CHANGE-FLOW-DESIGN.md §4): computed from live
+  // state exactly like provenDone, never claimed. An approval HANDS OFF, it
+  // never commands — so each step names its owner: the agent drafts/builds/
+  // proves, the human signs/accepts. For a change to EXISTING features the
+  // contract step includes the declared amendments: every touched
+  // 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}`);
+    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")
+      .map((id) => id.slice("feature-spec:".length));
+    const amendNote =
+      declaredSpecAmendments.length > 0 ? ` + reopen & amend ${declaredSpecAmendments.map((n) => `specs/${n}.spec.md`).join(", ")} (declared)` : "";
+    // PRE-SIGNATURE AGENT WORK (the anti-churn ordering). A feature with a UI
+    // surface gets its design drafted AND adversarially audited before the human
+    // is asked for a single signature. The old ladder asked for the brief first,
+    // so the design — and the audit that attacks it — happened against an already
+    // signed artifact, and every finding reopened it. Measured on meal-plan
+    // (2026-07-27): three signing rounds, the third triggered by an audit that
+    // found nine gaps including three defects in signed clauses. The work did not
+    // change; only when it happens relative to the gate.
+    const designPending = designArtifact !== null && designArtifact.status !== "approved";
+    const designUndrafted = designPending && !designArtifact.resolvable;
+    const auditMissing = designPending && d.edgeCases < MIN_AUDITED_EDGE_CASES;
+
+    if (phase === "accepted") return { key: "closed", owner: null, label: "closed — the brief is this feature's doc-of-record" };
+    if (phase === "changed-since-approval")
+      return { key: "re-approve", owner: "human", label: `re-approve the brief — it changed after signing (or revert the edit)` };
+    // `reopened` is ONE stored state covering two OPPOSITE situations (2026-07-28
+    // flow audit, fix 3): mid-redesign it waits on the WORK; once the redesign is
+    // proven (provenDone — every live clause cited + receipt PASS + receipt
+    // attests this tree) it waits on the SIGNATURE. The split is derived, never
+    // claimed — the same derivation acceptance already trusts. Before this,
+    // meal-plan sat reopened AND 23/23-proven simultaneously: the card said
+    // "waiting on you" while the guided queue said "nothing waits on you".
+    if (phase === "reopened") {
+      return d.provenDone
+        ? { key: "re-approve", owner: "human", label: "redesign proven — re-approve the brief" }
+        : { key: "redesign", owner: "agent", label: "redesign in progress — finish and prove it; the brief then returns for your signature" };
+    }
+    if (designUndrafted)
+      return {
+        key: "design",
+        owner: "agent drafts → human signs",
+        label: `design: draft the ${d.name} screens on stub data and render them — you sign what renders, never a description`,
+      };
+    if (auditMissing)
+      return {
+        key: "audit",
+        owner: "agent",
+        label:
+          `audit the ${d.name} design for edge cases — record each case and how it resolves under ` +
+          `"## Edge cases" in ${d.rel}. Findings land BEFORE the signature, not after it`,
+      };
+    if (phase === "proposed")
+      return { key: "sign-brief", owner: "human", label: "sign the brief — decisions close before code, and the design below is audited" };
+    // Design before contract (brief → design → spec → build): the form is
+    // signed on RENDERED output before behavior clauses pin it down — and
+    // before acceptance, so these rungs outrank `proven`.
+    if (designPending) {
+      if (designArtifact.status === "reopened")
+        return { key: "design", owner: "agent", label: `redesign in progress: finish the ${d.name} screens, then re-approve the design` };
+      return {
+        key: "sign-design",
+        owner: "human",
+        label:
+          designArtifact.status === "changed-since-approval"
+            ? `re-approve the design (feature-design:${d.name}) — the screens changed after signing (or revert)`
+            : `sign the design (feature-design:${d.name}) — audited, judged on the rendered screens`,
+      };
+    }
+    if (phase === "proven") return { key: "accept", owner: "human", label: "accept — the proven thing awaits your judgment" };
+    // 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}` };
+    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" };
+  };
+
+  const features = deriveAllFeatures(root).map((d) => {
+    const record = byId.get(`${FEATURE_BRIEF_PREFIX}${d.name}`) ?? null;
+    // Drift outranks acceptance: a brief edited after sign-off reads as
+    // changed-since-approval even if it was accepted — a sneaky post-
+    // acceptance edit must surface, never hide behind the closed card.
+    const phase =
+      !record || record.status === "unreviewed"
+        ? "proposed"
+        : record.status !== "approved"
+          ? record.status // changed-since-approval / reopened read as themselves
+          : record.accepted
+            ? "accepted"
+            : d.provenDone
+              ? "proven"
+              : "approved";
+    const designStatus = byId.get(`${FEATURE_DESIGN_PREFIX}${d.name}`) ?? null;
+    return {
+      ...d,
+      record,
+      phase,
+      // The design gate's live state, for the card: null = no UI surface
+      // (a pure-logic feature honestly has no design rung to show).
+      design: designStatus
+        ? { id: designStatus.id, status: designStatus.status, resolvable: designStatus.resolvable, fileCount: designStatus.fileCount }
+        : null,
+      nextStep: deriveNextStep(d, phase),
+      touches: d.touches.map((id) => {
+        const t = byId.get(id);
+        return t ? { id, status: t.status, label: t.label } : { id, status: "unknown", label: `(no governed artifact "${id}")` };
+      }),
+    };
+  });
+
+  const declaredByOpenBriefs = new Set();
+  for (const f of features) {
+    if (f.record && f.record.status === "approved" && !f.record.accepted) {
+      for (const t of f.touches) declaredByOpenBriefs.add(t.id);
+    }
+  }
+  const undeclared = statuses
+    .filter(
+      (s) =>
+        s.status === "changed-since-approval" &&
+        !s.id.startsWith(FEATURE_BRIEF_PREFIX) &&
+        !s.id.startsWith("feature-spec:") &&
+        !declaredByOpenBriefs.has(s.id),
+    )
+    .map((s) => ({ id: s.id, label: s.label }));
+
+  return { features, undeclared };
+}