create-cmp-cli 0.10.1 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.10.1",
+  "version": "0.11.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/src/lib/tabs.mjs

@@ -527,6 +527,8 @@ const PLACEHOLDER_REL =
 const PREVIEW_REGISTRY_REL =
   "composeApp/src/desktopMain/kotlin/com/example/app/inspector/PreviewRegistry.kt";
 const SMOKE_REL = "qa/e2e/smoke.yaml";
+const PROFILE_FEATURE_REL =
+  "composeApp/src/commonMain/kotlin/com/example/app/presentation/profile";
 
 /**
  * Rewrite every tab-driven surface present in the copied project dir. Runs
@@ -576,4 +578,28 @@ export function rewriteTabSurfaces(projectDir, tabs, log = () => {}) {
     fs.writeFileSync(smokePath, renderSmokeYaml(infos));
     log(`  tabs → ${SMOKE_REL}`);
   }
+
+  // A shipped default feature the config did NOT ask for must not be left on
+  // disk: rewriteNavHost drops its import and its appTabs() entry, and
+  // renderPreviewRegistryKt drops its preview, so the files would sit there
+  // wired to nothing — dead code the reachability gate (qa/lib/reachability.mjs)
+  // correctly FAILs at `--verify` time. Don't ship what you don't wire.
+  //
+  // `profile` is the only one: it is a self-contained stub screen (one file, no
+  // ViewModel, no spec clauses, no DI entry, no tests), so removing it leaves
+  // nothing dangling.
+  //
+  // `home` is deliberately NEVER stripped, even when it is not a configured tab.
+  // It is the governed EXEMPLAR (`qa/approvals.json`'s exemplarFeature — the file
+  // set `qa/scaffold-feature.mjs` clones and the genesis walk approves), and it
+  // owns `DetailScreen`, which AppNavHost registers as a destination
+  // unconditionally. So it stays both governed and reachable with no tab of its
+  // own — removing it would break the genesis walk and dangle the Detail route.
+  if (!infos.some((t) => t.slug === "profile")) {
+    const profilePath = path.join(projectDir, PROFILE_FEATURE_REL);
+    if (fs.existsSync(profilePath)) {
+      fs.rmSync(profilePath, { recursive: true, force: true });
+      log(`  tabs → removed ${PROFILE_FEATURE_REL} (no profile tab configured)`);
+    }
+  }
 }

package/template/.claude/skills/add-feature/SKILL.md

@@ -19,6 +19,26 @@ description: >-
 > feature to its real shape. You are not done until `node qa/verify.mjs` PASSes and the receipt
 > is committed — see this project's `CLAUDE.md`.
 
+## Step 0 — name the lane, out loud, before anything else
+
+Every post-genesis change enters through one of two lanes (`CLAUDE.md` §"After genesis"),
+and **the human must be told which one this request is taking, in your first reply** — one
+or two plain sentences before any tool runs: what you understood the change to be, which
+lane, and why. Never route silently; the human can overrule the triage in a word.
+
+- **Brief lane** — the request carries decisions a future contributor could plausibly
+  "simplify" away, or blast radius into other governed artifacts. Say so, e.g.: *"This
+  carries real decisions (day-boundary rules, scheduling semantics) — I'll draft a feature
+  brief at `docs/features/<name>.md` with the open decisions for you to close and sign
+  BEFORE I stamp anything."* Only after the brief is signed does this skill's stamping
+  start — and if the feature has a UI surface, the **design gate comes next, before the
+  spec**: draft the screens on stub data, render them, and stop for the human's signature
+  on `feature-design:<name>` (brief → design → spec → build). A human signs rendered
+  screens, never a description of screens.
+- **Direct lane** — an ordinary feature with no decisions worth recording. Say so, e.g.:
+  *"Straightforward slice, no decisions worth a brief — direct lane: spec clauses for your
+  confirmation, then I stamp and prove."* Then continue with Step 1 below.
+
 ## The clone source is configurable
 
 The stamper clones from the project's **configured exemplar** — `qa/approvals.json`'s

package/template/.claude/skills/add-repository/SKILL.md

@@ -24,6 +24,12 @@ to just the 5 data/domain files. Use it when you want the data layer to exist be
 consumes it (e.g. you're modeling several entities up front, or a screen for this entity will
 come later via `add-screen`).
 
+**Name the lane first, out loud.** Before any tool runs, tell the human in a sentence which
+lane this request takes (`CLAUDE.md` §"After genesis"): an entity carrying decisions worth
+recording (data-model semantics, boundary rules) goes through a feature brief
+(`docs/features/<name>.md`, signed before code); an ordinary entity is direct lane — say so,
+then continue here. Never route silently.
+
 ## Why a stamper and not hand-written files
 
 Every hand-written file is a drift chance in this project's architecture. `qa/scaffold-feature.mjs

package/template/.claude/skills/add-screen/SKILL.md

@@ -25,6 +25,12 @@ the 6 presentation+tests+spec files, **composed on top of an entity that already
 `add-repository` or a prior `add-feature` run). If the entity doesn't exist yet, this will refuse
 to stamp anything — see step 2.
 
+**Name the lane first, out loud.** Before any tool runs, tell the human in a sentence which
+lane this request takes (`CLAUDE.md` §"After genesis"): a screen carrying decisions worth
+recording or blast into signed artifacts goes through a feature brief
+(`docs/features/<name>.md`, signed before code); an ordinary screen is direct lane — say
+so, then continue here. Never route silently.
+
 ## Why a stamper and not hand-written files
 
 Every hand-written file is a drift chance in this project's architecture. `qa/scaffold-feature.mjs

package/template/CLAUDE.md

@@ -111,6 +111,12 @@ a provisional palette carries the build until then).
    the `cmp-new` interview; the seed's placeholder prose is marked unfilled. Its
    `## Glossary` section is lifted verbatim into `docs/ARCHITECTURE.md` §8 — write it there
    in the exact form you want published.
+0.5. **First feature brief** — `docs/features/<exemplar>.md`, drafted from the interview's
+   "first screens" answer the moment intent is signed: the first feature's decisions and
+   their why, signed BEFORE its spec is written. Genesis runs the same decide → contract →
+   build loop as every later change; the app's first feature gets the same decide step
+   every later feature gets. (Express lane: skipped honestly, never fabricated;
+   placeholders earn a brief when they become real.)
 1. **Architecture + structure** — `specs/app-base.spec.md` **and**
    [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) (`cmp:generated` sections stripped
    before hashing, so a mechanical regeneration never invalidates the approval — only an
@@ -131,16 +137,88 @@ a provisional palette carries the build until then).
 6. **Per-feature spec** — `specs/<feature>.spec.md`, one governed artifact per feature,
    added as features land.
 
+### After genesis — every change is the same loop
+
+Genesis governs the app's birth. Everything after runs the SAME loop — decide →
+contract → build → prove → sign — over a subset (`docs/CHANGE-FLOW-DESIGN.md` in the
+create-cmp repo is the doc of record). Two lanes, one triage rule — and **the triage is
+always visible**: your FIRST reply to any change request (new feature, edit, bug fix, copy
+tweak, redesign — every entry point) states in one or two plain sentences what you
+understood the change to be, which lane it takes, and why, before any tool runs. The human
+can overrule the lane in a word; a silent route is a routing error even when the lane was
+right.
+
+**Brief lane** — when the change carries **decisions a future contributor could plausibly
+"simplify" away** ("the day boundary is configurable, default 04:00 — not midnight") OR
+**blast radius into other governed artifacts**. After naming the lane:
+
+| Step | What |
+|---|---|
+| 1 | **Feature brief** — `docs/features/<name>.md`: the decisions with their why, research, rejected options, an **Open decisions** section until the human closes each. Signed BEFORE code. |
+| 2 | **Design** — iff the feature has a UI surface (`"screens": true`, or screen files exist): draft the screens on STUB data, register them in the PreviewRegistry, render, and STOP. The human judges the rendered screens and signs `feature-design:<name>`. Never ask a human to approve a described UI. |
+| 3 | **Contract** — reopen any signed spec the brief amends (`--reopen feature-spec:<surface> --reason "…"`); write the clauses where the behavior lives — about the form that now exists; the human signs |
+| 4 | Build the slice (`add-feature` / preview loop). Declared blast lands "as declared"; re-approve touched visual artifacts on rendered output (wiring the signed screens from stub to real state drifts `feature-design:<name>` — its re-approval is that pass) |
+| 5 | Prove — nothing to do: the lane's gates + receipt ARE the proof |
+| 6 | The human's `--accept` — enabled only at provenDone AND a signed design |
+
+**Direct lane** — everything else (bug fix, copy edit, tweak): confirm in chat, reopen →
+amend clause → re-approve if a signed contract is touched, build, lane once at done.
+Legacy features never get retro-briefs; spikes are ungoverned until they become real.
+
+**A brief's LOCATION is the governance opt-in**: every `docs/features/*.md` is a governed
+`feature-brief:<name>` artifact (hash-bound at signing; `<name>` pairs with
+`specs/<name>.spec.md`). `docs/proposals/` stays ungoverned. The brief carries at most one
+machine-read block, and it **declares — it never gates**:
+
+```json cmp:feature
+{ "touches": ["components", "design-system"], "screens": true }
+```
+
+`touches` is the declared blast radius — the artifact hashes already enforce; declaring
+lets the console show "components re-approval, as planned" instead of an unexplained
+failure, and surface **undeclared blast** when something drifted that no open brief
+accounted for. `screens: true` declares a UI surface: it holds the design gate
+(`feature-design:<name>` — the feature's own `presentation/<name>/*Screen.kt`, signed on
+rendered output) before any screen file exists; once files exist, disk is ground truth
+regardless. Both declare — neither gates.
+
+**Doneness is DERIVED, never claimed.** There is no `--deliver` and no checks block —
+deliberately (they existed and were removed as a weaker parallel truth). A feature is
+`provenDone` when, mechanically: its spec has live clauses **and** every one is cited by a
+test **and** the latest receipt is PASS **and** the receipt's `inputs.hash` attests the
+tree as it stands. `--status` and the console print the same one-line `doneReason` either
+way. What remains for humans is judgment: signing the brief (before code) and accepting
+the feature (after proof — "the proven thing is what I wanted"); `--accept` is refused
+until the derivation holds. Acceptance lives on the ledger row, never in the doc (the
+signed bytes must not move when the human accepts).
+
+| Command | What |
+|---|---|
+| `node qa/approve.mjs feature-brief:<name>` | the human signs the brief (before code) |
+| `node qa/approve.mjs --accept <name>` | the human's bookend; refused until provenDone |
+
+Editing a feature is the same brief **reopened** — `--reopen-feature <name> --reason "…"`
+reopens the brief + its spec + its design + the set it declared, as ONE recorded change;
+re-approval is one walk back. Every reopen **requires a `--reason`** (it walks back a
+signature; the signer reads why from the ledger itself) and is journaled with `via` — the
+append-only journal (`qa/approvals.log.jsonl`, printed by `--log`, shown in the console
+strip's History) is how "what happened while I was away" stays answerable.
+
 | Command | What |
 |---|---|
 | `node qa/approve.mjs --status` | Every governed artifact with live state (`unreviewed` / `approved` / `changed-since-approval` / `reopened`), short hash, mode badge |
 | `node qa/approve.mjs <artifact>` | Record approval — hashes the artifact's files now, stamps the time; also clears a `defaults-accepted` mode |
 | `node qa/approve.mjs --accept-defaults` | **Express lane**: approve every currently-resolvable artifact in one visible act, each stamped `"mode": "defaults-accepted"` — build now, walk the definition later. Unresolvable artifacts are skipped with the standard refusal printed. The ledger never pretends the defaults were designed. |
-| `node qa/approve.mjs --reopen <artifact>` | Move an *approved* artifact (shaped or defaults-accepted) back to `reopened` for deliberate redesign — recorded (`reopenedAt`). Refuses unknown ids and anything not currently approved. |
+| `node qa/approve.mjs --reopen <artifact> --reason "…"` | Move an *approved* artifact (shaped or defaults-accepted) back to `reopened` for deliberate redesign. `--reason` is REQUIRED and recorded (`reopenedAt`, `via`, `reason` — on the row and in the journal). Refuses unknown ids and anything not currently approved. |
+| `node qa/approve.mjs --reopen-feature <name> --reason "…"` | ONE recorded change: reopens the brief + `feature-spec:<name>` + `feature-design:<name>` + every declared `touches` artifact (each only if currently approved), all under one reason. |
+| `node qa/approve.mjs --log` | The governance journal — every approve/reopen/accept with when, which surface (`via`), and why. |
 
 With the create-cmp plugin, the same decisions can be made from the preview console
 (`preview {projectDir}`'s URL) — it calls the same library, so the CLI and the console
-never disagree. An agent blocks on a pending decision with
+never disagree. The console's rail is the human's work queue (colour = something waits
+on them), and a drifted artifact shows, in its own section, exactly **what changed
+against the signed bytes and which files are still exactly as signed**, with re-approval
+in place. An agent blocks on a pending decision with
 `approval_status {waitForDecision:true}`.
 
 The verify lane's `approvals` gate (a step like any other, in every profile) resolves each
@@ -267,4 +345,5 @@ conventions) · [`CONTRIBUTING.md`](./CONTRIBUTING.md) (workflow, Conventional C
 | `./gradlew :composeApp:desktopTest` | Unit tests only (fast inner loop) |
 | `node qa/setup-hooks.mjs` | Enable the pre-push receipt gate (one-time, after `git init`) |
 | `./gradlew :composeApp:assembleDebug` | Android debug build |
+| `./gradlew :composeApp:assembleRelease` | Android release build — R8 + `lintVital`, the variant the lane's `releaseBuild` step proves. Produces an **unsigned** APK; signing needs a keystore, which is yours to create and keep out of the repo. |
 | `./gradlew :composeApp:hotRunDesktop --auto` | Desktop dev-client with hot reload |

package/template/composeApp/build.gradle.kts

@@ -202,7 +202,19 @@ android {
         getByName("release") {
             isMinifyEnabled = true
             isShrinkResources = true
+            // Every field debug declares, release must declare too. BuildConfig is generated
+            // PER BUILD TYPE, so a field only debug carries simply does not exist in release —
+            // and `if (!USE_FIREBASE_EMULATORS) return` is a RUNTIME guard that does nothing
+            // for a compile-time symbol. Declaring the flag alone made release the one build
+            // nobody could produce: the code reading the host and ports failed to resolve them.
+            // The values below are never used (the flag is false); they exist so the shape of
+            // BuildConfig is the same in both build types.
             buildConfigField("boolean", "USE_FIREBASE_EMULATORS", "false")
+            buildConfigField("String", "FIREBASE_EMULATOR_HOST", "\"\"")
+            buildConfigField("int", "FIREBASE_AUTH_PORT", "0")
+            buildConfigField("int", "FIREBASE_FIRESTORE_PORT", "0")
+            buildConfigField("int", "FIREBASE_FUNCTIONS_PORT", "0")
+            buildConfigField("int", "FIREBASE_STORAGE_PORT", "0")
             manifestPlaceholders["usesCleartextTraffic"] = "false"
             proguardFiles(
                 getDefaultProguardFile("proguard-android-optimize.txt"),
@@ -226,6 +238,19 @@ android {
         // <<< cmp:feature !firebase
     }
 
+    lint {
+        // ONE disabled check, not the gate. `lintVitalRelease` runs on every release build and
+        // it is worth keeping; what is not worth keeping is a detector that CRASHES on it.
+        // NullSafeMutableLiveData's detector throws IncompatibleClassChangeError against this
+        // Kotlin version (AGP's bug, not ours) and takes the whole release build with it.
+        //
+        // Disabling it costs nothing beyond the crash: an app on this template has no LiveData —
+        // state is Compose + Flow throughout — so the check has nothing to inspect. The blunt
+        // alternatives, `checkReleaseBuilds = false` or `abortOnError = false`, would switch off
+        // every real lint finding to dodge one broken one.
+        disable += "NullSafeMutableLiveData"
+    }
+
     compileOptions {
         sourceCompatibility = JavaVersion.VERSION_17
         targetCompatibility = JavaVersion.VERSION_17

package/template/composeApp/proguard-rules.pro

@@ -20,6 +20,18 @@
 -keep class dev.gitlive.firebase.** { *; }
 -dontwarn com.google.firebase.**
 
+# GitLive's RemoteConfig module is compiled against kotlinx-datetime's OWN Instant, which
+# this version set no longer has: on Kotlin 2.2 Instant moved into the stdlib as
+# kotlin.time.Instant. R8 hits an unresolvable reference and FAILS the release build.
+#
+# Suppressed rather than resolved, deliberately. The reference lives in
+# FirebaseRemoteConfigInfo, and RemoteConfig is not a service this template wires up, so no
+# code path reaches it. Adding kotlinx-datetime back purely to satisfy a class nobody calls
+# would put two Instant types in the graph — the more expensive mistake. When GitLive ships
+# a build against kotlin.time, delete these two lines; the release build will say if it is time.
+-dontwarn kotlinx.datetime.Instant$Companion
+-dontwarn kotlinx.datetime.Instant
+
 # Coroutines
 -keepnames class kotlinx.coroutines.internal.MainDispatcherFactory {}
 -keepnames class kotlinx.coroutines.CoroutineExceptionHandler {}

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/navigation/AppNavHost.kt

@@ -2,6 +2,7 @@ package __PACKAGE__.presentation.navigation
 
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.ui.Modifier
 import androidx.navigation.NavType
 import androidx.navigation.compose.NavHost
 import androidx.navigation.compose.composable
@@ -10,6 +11,9 @@ import androidx.navigation.navArgument
 // Nav 2.9 (multiplatform): backStackEntry.arguments is a SavedState, not an Android Bundle.
 // Read it via the androidx.savedstate.read extension, NOT Bundle.getString().
 import androidx.savedstate.read
+// Kept OUTSIDE the screen-imports block below: the tab rewriter (src/lib/tabs.mjs) replaces
+// exactly those two lines with the configured tabs' screen imports.
+import __PACKAGE__.presentation.components.exposeTestTagsForAutomation
 import __PACKAGE__.presentation.home.HomeScreen
 import __PACKAGE__.presentation.profile.ProfileScreen
 
@@ -38,7 +42,18 @@ fun AppNavHost() {
         }
     }
 
-    NavHost(navController = navController, startDestination = Screen.Shell.route) {
+    // Expose Compose testTags to the platform automation layer (Android resource-ids / iOS
+    // accessibilityIdentifiers) for the WHOLE graph. The property is inherited by descendants,
+    // so it belongs on the graph root, not on a destination: applied inside AppShell it would
+    // cover the tabs and nothing else, leaving every destination registered directly here
+    // (detail screens, trays) with testTags no id-selector can see — e2e flows could not
+    // assert arrival on them at all. Here, a destination added later inherits it without
+    // anyone remembering to. Desktop: no-op.
+    NavHost(
+        navController = navController,
+        startDestination = Screen.Shell.route,
+        modifier = Modifier.exposeTestTagsForAutomation(),
+    ) {
         composable(Screen.Shell.route) {
             val tabs = appTabs(
                 home = {

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/navigation/AppShell.kt

@@ -10,7 +10,6 @@ import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
 import __PACKAGE__.presentation.components.AppBottomBar
 import __PACKAGE__.presentation.components.BaseScreen
-import __PACKAGE__.presentation.components.exposeTestTagsForAutomation
 
 /**
  * Generic bottom-nav shell. Parameterized by a [tabs] list — NOT role-hardcoded.
@@ -27,10 +26,8 @@ fun AppShell(tabs: List<AppTab>) {
     var selected by rememberSaveable { mutableIntStateOf(0) }
 
     BaseScreen(
-        // Expose Compose testTags to the platform automation layer (Android resource-ids /
-        // iOS accessibilityIdentifiers) so Appium/uiautomator id-selectors and the
-        // cmp-test-generated suites find them; covers the whole subtree. Desktop: no-op.
-        modifier = Modifier.exposeTestTagsForAutomation(),
+        // testTag exposure for automation is applied once on the NavHost in AppNavHost.kt —
+        // the graph root, so every destination inherits it, not just these tabs.
         // The bottom bar owns the navigation-bar inset; the body must not also pad it.
         applyNavBarPadding = false,
         bottomBar = {

package/template/qa/approve.mjs

@@ -9,8 +9,25 @@
 //   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> moves an approved artifact back to "reopened" for
-//                                            redesign (refuses anything not currently approved)
+//   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
@@ -22,12 +39,16 @@ 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)), "..");
@@ -52,22 +73,44 @@ function printStatus() {
     // approvable — approval over an unresolved file set is refused.
     const hashInfo =
       s.status === "reopened"
-        ? `reopened at ${s.reopenedAt} (was approved ${shortHash(s.storedHash)})`
+        ? `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"
-            ? shortHash(s.hash)
+            ? // 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}]` : "";
-    console.log(`${mark} ${s.id}: ${s.status} (${hashInfo})${modeInfo} — ${s.label}`);
+    // 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")) {
@@ -102,27 +145,92 @@ if (args.includes("--accept-defaults")) {
   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) {
-    console.error("usage: node qa/approve.mjs --reopen <artifact>");
+  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 = reopenArtifact(ROOT, artifactId);
+  const result = acceptFeature(ROOT, name, { via: "cli" });
   if (!result.ok) {
     console.error(`error: ${result.reason}`);
     process.exit(1);
   }
-  console.log(`↺ reopened ${result.artifact} for redesign — at ${result.reopenedAt}`);
+  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 | --accept-defaults | --reopen <artifact>\n" +
+    '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);
@@ -131,7 +239,7 @@ if (args.length === 0) {
 refuseIfUnresolvable();
 
 const artifactId = args[0];
-const result = approveArtifact(ROOT, artifactId);
+const result = approveArtifact(ROOT, artifactId, { via: "cli" });
 if (!result.ok) {
   console.error(`error: ${result.reason}`);
   process.exit(1);