create-cmp-cli 0.8.0 → 0.9.0

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

@@ -3,7 +3,8 @@ name: add-feature
 description: >-
   Add a new conforming vertical-slice feature (Screen + ViewModel + UseCase + Repository + spec
   + tests + golden tree + nav route + DI wiring) to this Compose Multiplatform app, cloned
-  deterministically from the `home` exemplar. Use this when the user wants to "add a feature",
+  deterministically from the project's configured exemplar feature (qa/approvals.json's
+  exemplarFeature — `home` by default). Use this when the user wants to "add a feature",
   "add a screen with data", "scaffold a feature", "create a new screen backed by a repository",
   "add a list screen", or names a new domain noun they want a screen for (e.g. "add a Favorites
   feature", "I need a Bookmarks screen"). Works with NO create-cmp plugin installed — the
@@ -13,11 +14,28 @@ description: >-
 # add-feature — stamp a conforming vertical slice
 
 > Spec-first, deterministic-stamp, gate-proven. The script (`qa/scaffold-feature.mjs`) does the
-> mechanical work — copy the `home` exemplar file set, whole-word identifier rename, anchor
+> mechanical work — copy the exemplar file set, whole-word identifier rename, anchor
 > injection into the three shared files. You (the AI) only refine spec wording and adapt the
 > 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`.
 
+## The clone source is configurable
+
+The stamper clones from the project's **configured exemplar** — `qa/approvals.json`'s
+top-level `"exemplarFeature"` key (absent ⇒ `home`, the shipped exemplar). This is the same
+resolution the approvals registry uses for the governed `exemplar-feature` artifact, so what
+gets stamped is always exactly what the human signed off on. After the genesis walk retargets
+`exemplarFeature` to the user's own first feature, every stamp from then on clones *their*
+pattern in *their* domain language — do not assume `home` still exists as the exemplar; read
+the config (or just run the stamper: it resolves the source itself).
+
+If the configured exemplar has grown files beyond the canonical 11-file shape (an extra
+ViewModel, a helper, a second use case named for its entity), the stamper clones **only the
+canonical set** and prints a `WARNING:` listing exactly what it skipped — never silently.
+When you see that warning, tell the human: the extras are part of the exemplar's pattern in
+spirit but not in mechanism, and porting them into the new feature (or slimming the exemplar
+back to canon) is a deliberate follow-up, not something to ignore.
+
 ## Why a stamper and not hand-written files
 
 This project's whole thesis is that determinism beats freehand generation for anything
@@ -58,9 +76,9 @@ node qa/scaffold-feature.mjs <FeatureName> --entity <EntityName>
 
 This writes the new Screen/ViewModel/UseCase/Repository(+impl)/tests/fake, wires them into
 `di/AppModule.kt`, `presentation/navigation/Screen.kt`, and `presentation/navigation/AppNavHost.kt`
-at their `// cmp:anchor` markers, and writes `specs/<feature>.spec.md` with a default six-clause
-set (`<FEATURE>-01..06`: loading, success, error, reload-after-failure, tap-navigates, golden
-tree) — copied verbatim from the `home` exemplar's shape.
+at their `// cmp:anchor` markers, and writes `specs/<feature>.spec.md` with a default seven-clause
+set (`<FEATURE>-01..07`: loading, success, error, reload-after-failure, tap-navigates, golden
+tree, empty state) — copied verbatim from the configured exemplar's shape.
 
 The stamped screen arrives **already wrapped in `BaseScreen { … }`** (SHELL-05): it is a
 pushed NavHost destination, so unlike the tab exemplar it must handle its own insets — the
@@ -73,9 +91,9 @@ flagging, not something to route around by hand-splicing.
 
 ### 4. Refine the spec, then the behavior
 
-The default spec clauses are placeholders shaped like the `home` exemplar (a plain list of
+The default spec clauses are placeholders shaped like the exemplar (by default a plain list of
 title/subtitle rows). **Rewrite the clause prose** in `specs/<feature>.spec.md` to describe the
-feature's real behavior — the six clause **ids stay fixed** (`specCoverage` binds tests to ids,
+feature's real behavior — the seven clause **ids stay fixed** (`specCoverage` binds tests to ids,
 not prose), only the wording changes. Propose the rewritten clauses to the human; get them
 confirmed before moving on — this project's contract is spec-first.
 
@@ -84,7 +102,12 @@ Then adapt the generated code to match:
 - If the feature isn't shaped like "a list of `{id, title, subtitle}`", update the entity's
   fields in `domain/model/<Entity>.kt`, the sample data in `<Entity>RepositoryImpl.kt`, and the
   screen's rendering in `presentation/<feature>/<Feature>Screen.kt` together — keep them
-  consistent with each other and with the tests.
+  consistent with each other and with the tests. The stamped screen already **composes the
+  registry vocabulary** (`ScreenColumn`/`AppHeader`/`ContentStateContainer`/`ListItemCard`,
+  `presentation/components/*.kt`) — adapt the content shape inside `ContentStateContainer`'s
+  trailing slot, don't hand-roll a new header/loading state/list row on top of it. If the
+  feature's data genuinely needs a component the nine don't cover, propose the addition to the
+  human explicitly (a new file is a registry change — it invalidates the `components` approval).
 - Update the copied tests (`<Feature>ViewModelTest.kt`, `<Feature>ScreenTest.kt`) to match
   whatever you changed. The gate (step 6) will tell you exactly what you missed — a compile
   error names the mismatch; a spec-coverage failure names an orphaned clause or tag.
@@ -113,10 +136,12 @@ copy-paste artifact. Commit it alongside the feature.
 node qa/verify.mjs
 ```
 
-This must PASS. It proves: the spec's six clauses are all bound to a citing test
+This must PASS. It proves: the spec's seven clauses are all bound to a citing test
 (`specCoverage`), the build compiles, unit tests pass (ViewModel + UseCase + Repository +
 fakes), architecture conformance holds (`presentation` doesn't import `data`, the new
-`*Screen.kt` carries a `testTag`, the new `*ViewModel.kt` has a matching test), the golden tree
+`*Screen.kt` is automation-reachable — a literal `testTag` or `screenTag =` wiring into a
+registry component — the new `*ViewModel.kt` has a matching test, and it references no
+`CircularProgressIndicator`/`LinearProgressIndicator` directly), the golden tree
 matches what you just captured, and accessibility holds. **Not done until this is PASS and the
 evidence receipt (`qa/evidence/latest.json`) is committed with your change** — this is this
 project's standing definition of done (see `CLAUDE.md`).

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

@@ -76,7 +76,7 @@ the real entity:
 
 **No spec clauses are added by this preset, and that's intentional** — a bare repository has no
 observable behavior to specify yet (no screen, no user-facing flow). Clauses attach once a
-screen consumes this entity; that's `add-screen`'s job (`FEATURE-01..06` bound to the repository
+screen consumes this entity; that's `add-screen`'s job (`FEATURE-01..07` bound to the repository
 you just built).
 
 ### 5. Gate

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

@@ -29,7 +29,7 @@ to stamp anything — see step 2.
 
 Every hand-written file is a drift chance in this project's architecture. `qa/scaffold-feature.mjs
 --preset screen` produces a **conforming skeleton by construction**: a Screen composable with a
-testTagged root, a ViewModel (+ test), a Compose UI test, a golden-tree test, and a six-clause
+testTagged root, a ViewModel (+ test), a Compose UI test, a golden-tree test, and a seven-clause
 spec — wired into Koin and the nav graph. Your job is to make it *behave* like the real screen,
 not to make it *structurally correct*.
 
@@ -72,7 +72,7 @@ node qa/scaffold-feature.mjs <FeatureName> --entity <EntityName> --preset screen
 This writes the Screen/ViewModel/tests/golden-tree-test, wires the ViewModel into
 `di/AppModule.kt` and a route into `presentation/navigation/Screen.kt` +
 `presentation/navigation/AppNavHost.kt` at their `// cmp:anchor` markers, and writes
-`specs/<feature>.spec.md` with a default six-clause set (`<FEATURE>-01..06`) cited by the three
+`specs/<feature>.spec.md` with a default seven-clause set (`<FEATURE>-01..07`) cited by the three
 generated test files.
 
 If it exits non-zero, read the message — it is actionable. Do not hand-edit around a stamper
@@ -88,7 +88,11 @@ Then adapt the generated code to match the entity's actual shape (which may diff
 `home` exemplar's `{id, title, subtitle}` list): update the screen's rendering in
 `presentation/<feature>/<Feature>Screen.kt` and the copied tests
 (`<Feature>ViewModelTest.kt`, `<Feature>ScreenTest.kt`) together, consistent with whatever
-`<Entity>.kt` already looks like. The gate (step 6) will name exactly what you missed.
+`<Entity>.kt` already looks like. The stamped screen already **composes the registry
+vocabulary** (`ScreenColumn`/`AppHeader`/`ContentStateContainer`/`ListItemCard`,
+`presentation/components/*.kt`) — adapt the content shape inside `ContentStateContainer`'s
+trailing slot rather than hand-rolling a new header/loading state/list row. The gate (step 6)
+will name exactly what you missed.
 
 ### 5. Capture the golden tree
 
@@ -109,10 +113,12 @@ node qa/verify.mjs
 ```
 
 This must PASS. It proves: the spec's six clauses are all bound to a citing test
-(specCoverage — `<FEATURE>-01..06` newly bound), the build compiles, unit tests pass, architecture
-conformance holds, the golden tree matches, and accessibility holds. **Not done until this is
-PASS and the evidence receipt (`qa/evidence/latest.json`) is committed with your change** — this
-project's standing definition of done (see `CLAUDE.md`).
+(specCoverage — `<FEATURE>-01..07` newly bound), the build compiles, unit tests pass, architecture
+conformance holds (the screen is automation-reachable via a literal `testTag` or `screenTag =`
+wiring into a registry component, and references no `CircularProgressIndicator`/
+`LinearProgressIndicator` directly), the golden tree matches, and accessibility holds. **Not done
+until this is PASS and the evidence receipt (`qa/evidence/latest.json`) is committed with your
+change** — this project's standing definition of done (see `CLAUDE.md`).
 
 If it fails: read the failing step's reason, fix the actual behavior or spec/test binding, and
 re-run. Do not delete or weaken a test to reach green.

package/template/.githooks/pre-push

@@ -0,0 +1,24 @@
+#!/bin/sh
+# create-cmp pre-push gate — the human checkpoint before code leaves the machine.
+#
+# The committed evidence receipt (qa/evidence/latest.json) must attest HEAD.
+# This is the SAME check CI runs (qa/receipt-check.mjs), moved earlier so an
+# unverified push is caught locally. It is the CHEAP predicate — a hash
+# comparison — not the full lane, so it never rebuilds anything.
+#
+# Enable once with `node qa/setup-hooks.mjs`. Bypass in a pinch with
+# `git push --no-verify`; CI still enforces the same check.
+
+if [ ! -f qa/receipt-check.mjs ]; then
+  exit 0 # not a create-cmp project layout — nothing to gate
+fi
+
+if node qa/receipt-check.mjs; then
+  exit 0
+fi
+
+echo ""
+echo "✗ pre-push blocked — the committed receipt does not attest HEAD."
+echo "  Run:  node qa/verify.mjs   then commit qa/evidence/latest.json, and push again."
+echo "  Bypass this local gate with: git push --no-verify  (CI still checks)."
+exit 1

package/template/CLAUDE.md

@@ -1,85 +1,232 @@
 # __APP_NAME__ — AI delivery contract
 
-This project was generated by [create-cmp](https://github.com/kvdm-co-pilot/create-cmp) with a
-verification harness. Any AI session working in this repo follows this contract.
+Generated by [create-cmp](https://github.com/kvdm-co-pilot/create-cmp) with a verification
+harness. Every AI session in this repo works under this contract.
 
 ## Definition of done
 
-You are **not done until `node qa/verify.mjs` reports PASS** and the receipt it writes
-(`qa/evidence/latest.json`) is included in your commit. Claiming completion without a PASS
-receipt is a failure. SKIPped steps are recorded in the receipt — never present green-with-gaps
-as fully verified.
+Done means `node qa/verify.mjs` reports PASS and the receipt it writes
+(`qa/evidence/latest.json`) is in your commit. Claiming completion without a PASS receipt is
+a failure. SKIPped steps are recorded in the receipt; never present green-with-gaps as fully
+verified.
+
+**Verify in two tiers — the full lane is a checkpoint, not an inner loop.** It builds,
+tests, and gates the whole tree to produce the receipt, so it is slow by design; running it
+after every edit wastes the minutes it takes. Iterate on the fast tier, and run the lane
+once — when you believe the change is done.
+
+- **Inner loop — run continuously (seconds):** the preview loop (below) for UI, and
+  `./gradlew :composeApp:desktopTest` for the unit tests your change touches. This is where
+  you catch your own mistakes.
+- **Checkpoint — run once, at done:** `node qa/verify.mjs`. It writes the receipt; commit
+  the receipt with your change. The Stop hook (`qa/receipt-check.mjs`) then confirms — with a
+  cheap hash check, not another lane run — that a valid receipt attests your commit, and CI
+  re-runs the full lane on push. After a green checkpoint, do not re-run the lane unless you
+  change the tree again.
+
+Humans get the same gate at push time: run `node qa/setup-hooks.mjs` once (after `git init`)
+to enable the shipped pre-push hook. It blocks a push whose committed receipt doesn't attest
+HEAD — the same cheap check, before code leaves the machine (`git push --no-verify` bypasses
+it; CI still enforces it).
 
 ## Specifications — behavior starts here
 
-**New behavior begins as a spec clause** in `specs/<feature>.spec.md` (Given/When/Then with a
-stable id — see [`specs/README.md`](./specs/README.md)). Propose the clause, get it confirmed,
+New behavior begins as a spec clause in `specs/<feature>.spec.md`: Given/When/Then with a
+stable id (see [`specs/README.md`](./specs/README.md)). Propose the clause, get it confirmed,
 then implement. Durable tests cite their clause (`// SPEC: HOME-02`).
 [`specs/app-base.spec.md`](./specs/app-base.spec.md) states the architecture and shell
 invariants the conformance gates enforce.
 
-## Architecture (violations will be named by the conformance gates)
+## Architecture
+
+[`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) is the doc of record. Every normative
+sentence in it carries a tier tag: `[enforced: CLAUSE-ID]`, `[governed]`, or `[advisory]`.
+Its `cmp:generated` sections (expect/actual table, layer inventory, ADR index, glossary) are
+derived from a tree walk, never hand-maintained — `node qa/arch-doc.mjs` regenerates them,
+and `node qa/arch-doc.mjs --check`, a verify-lane step, fails the lane when they drift from
+the tree. The governed `architecture` artifact (below) hashes the document alongside
+`specs/app-base.spec.md`, so approving it is consent to this document. The summary:
 
 - **Layers:** `presentation` → `domain` ← `data`. `domain` imports nothing app-internal;
   `presentation` never imports `data`. Koin wires implementations in `di/`.
-- **Every screen:** a `*Screen` composable with a `testTag`ged root, a ViewModel with a test.
-- **Design values** (colors / spacing / typography / radii) come from the theme's token catalog
-  (`presentation/theme/`). Never hardcode literals in screens.
-- The `home` feature is the **exemplar** — it shows the full pattern through every layer,
-  including the tests. When you add a feature, mirror it exactly: Screen → ViewModel (+ test) →
-  UseCase (+ test) → Repository interface in `domain` + impl in `data` (+ test) → DI module
-  entry → navigation route.
-
-## Testing (the pyramid this project uses)
+- **Screens compose the registry vocabulary** (`presentation/components/*.kt` —
+  `ScreenColumn`, `AppHeader`, `ContentStateContainer`, `ListItemCard`, …). Do not hand-roll
+  a header, loading state, or list row; the exemplar's `HomeScreen.kt` shows the pattern.
+  `ScreenColumn(screenTag = "<feature>")` tags the root, and ARCH-04 accepts that wiring as
+  tag provenance — a literal `testTag` is only needed for content the registry does not
+  already tag (per-row ids, for example). Every screen is a `*Screen` composable with a
+  tested ViewModel.
+- **Errors are typed, never thrown across layers.** Repositories return `AppResult`
+  (`Failure` carries a `DomainError` kind). The data layer's `suspendRunCatching` is the
+  only catch point and always rethrows `CancellationException`. ViewModels contain no
+  `try`/`catch`; they fold results into a sealed UiState, and presentation maps error kinds
+  to user copy.
+- **Design values** (colors, spacing, typography, radii) come from the token catalog in
+  `presentation/theme/`. No hardcoded literals in screens.
+- **One feature is the exemplar** — the full pattern through every layer, tests included.
+  It ships as `home`; `qa/approvals.json`'s `exemplarFeature` key retargets it to your own
+  first feature once shaped (see "Configurable exemplar"). New features mirror the exemplar
+  exactly: Screen → ViewModel (+ test) → UseCase (+ test) → Repository interface in `domain`
+  + impl in `data` (+ test) → DI entry → navigation route.
+
+## Testing
 
 - **Unit** (`composeApp/src/commonTest`, run via `./gradlew :composeApp:desktopTest`):
-  kotlin-test + coroutines-test + Turbine. **Hand-written fakes** in `testing/fakes/` — never
+  kotlin-test + coroutines-test + Turbine. Hand-written fakes in `testing/fakes/`; no
   mocking frameworks. Every new ViewModel/UseCase/Repository gets a test in the exemplar's
   style: Arrange-Act-Assert, behavior-named backtick tests, one behavior per test.
-- **Conformance + screen tests** (`composeApp/src/desktopTest`): dependency-free
-  source-scanning architecture gates (they enforce `specs/app-base.spec.md`'s ARCH clauses) + Compose UI Tests (durable,
-  spec-cited, testTag selectors) + the golden-tree structural baseline (`qa/golden/`). Golden
-  drift you did not intend = fix your change; intended drift = regenerate explicitly
-  (`UPDATE_GOLDEN=1`) and declare it.
-- **E2E** (`qa/e2e/*.yaml`): Maestro flows; smoke covers boot + bottom nav. Selectors by
-  testTag — never by display text.
-- Do not delete, weaken, or `@Ignore` a failing test to get to green. Fix the behavior, or if
-  the test itself is wrong, say so explicitly in your summary and justify the change.
+- **Conformance + screen tests** (`composeApp/src/desktopTest`): source-scanning
+  architecture gates enforcing `specs/app-base.spec.md`'s ARCH clauses, Compose UI Tests
+  (spec-cited, testTag selectors), and the golden-tree baseline (`qa/golden/`). Unintended
+  golden drift means fix your change; intended drift is regenerated explicitly
+  (`UPDATE_GOLDEN=1`) and declared.
+- **E2E** (`qa/e2e/*.yaml`): Maestro flows; smoke covers boot + bottom nav. Select by
+  testTag, never by display text.
+- Never delete, weaken, or `@Ignore` a failing test to reach green. Fix the behavior — or,
+  if the test itself is wrong, say so in your summary and justify the change.
 
 ## Evidence
 
 `node qa/verify.mjs` writes `qa/evidence/latest.json` (schema: `qa/evidence/schema.json`).
-Commit it with your change — git history is the audit ledger. Binary artifacts under
-`qa-artifacts/` are hashed into the receipt; never commit them.
+Commit it with your change; git history is the audit ledger. Binary artifacts under
+`qa-artifacts/` are hashed into the receipt, never committed. The studio console's Evidence
+page reconstructs the full audit trail from the git log of `latest.json` — every commit is
+one verified, attributed state — so committing each receipt is what builds the record.
+
+## Approvals — governed artifacts need a human's sign-off
+
+Some artifacts are **governed**: a human approves them, and the approval is bound to the
+artifact's content by hash (`qa/approvals.json`) — the evidence-receipt idea, applied to a
+human decision. The ordered walk is a **definition order**, not just an approval order:
+each artifact is the vocabulary the next is written in, so on a fresh app each step is a
+conversation that ends in an approval — the genesis walk, six conversations:
+
+0. **Intent** — `specs/intent.md`, the root brief everything else traces to (purpose,
+   audience, platforms, brand feel, reference apps, first screens, **glossary**). Filled by
+   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.
+1. **Design system** — `presentation/theme/Theme.kt`, `presentation/theme/Tokens.kt`.
+2. **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
+   authored-prose edit does).
+3. **Components** — every `presentation/components/*.kt` (a dynamic, sorted glob). Once
+   approved, the registry is law: adding or changing a common component invalidates the
+   approval until a human re-approves.
+4. **Exemplar feature** — the **configured** exemplar's 11-file set the `add-feature`
+   stamper clones from (see "Configurable exemplar").
+5. **Exemplar spec** — `specs/<exemplar>.spec.md`.
+6. **Per-feature spec** — `specs/<feature>.spec.md`, one governed artifact per feature,
+   added as features land.
+
+| 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. |
+
+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
+`approval_status {waitForDecision:true}`.
+
+The verify lane's `approvals` gate (a step like any other, in every profile) resolves each
+artifact's live status against `qa/approvals.json`:
+
+- **`unreviewed`** → SKIP with a warning line. Nothing fails until a human opts in by
+  approving.
+- **`reopened`** → SKIP with a warning line, exactly like `unreviewed`. Sanctioned redesign
+  never trips the gate; edits made while reopened are never drift. Re-approve when the
+  redesign lands.
+- **`approved`, hash still matches** → PASS.
+- **`approved`, hash no longer matches** → FAIL, naming the artifact and the re-approval
+  command. The artifact changed after sign-off — re-approve it or revert the change.
+  Invalidation is mechanical, like golden-tree drift, not a judgment call.
+
+That asymmetry is the point: **redesign is a decision; drift is an accident** — the ledger
+records which was which. A run with one reopened artifact and one drifted artifact FAILs
+naming only the drifted one.
+
+A gate FAIL fails the lane verdict, which fails `qa/receipt-check.mjs` (the Stop hook) by
+the same mechanism as any other FAIL — no separate enforcement to maintain. `add-feature`
+seeds each new feature's spec as `unreviewed` and prints the approval reminder; it never
+refuses to stamp over this.
+
+### Configurable exemplar — the DNA features are cloned from
+
+`qa/approvals.json` carries a top-level `"exemplarFeature"` key (absent means `"home"`, so
+older ledgers keep meaning what they meant). It names the feature whose 11-file set is the
+governed **exemplar-feature** artifact and the clone source `qa/scaffold-feature.mjs`
+stamps new features from. The genesis walk's endgame is pointing it at *your* first real
+feature: stamp it (`add-feature`), shape it, then set `exemplarFeature` — from then on the
+stamper clones your pattern in your domain language, and `home` demotes to an ordinary
+feature spec. If the configured exemplar has grown files beyond the canonical 11-file
+shape, the stamper clones the canonical set and warns, listing exactly what it skipped.
+
+## Comments — review feedback flows back through the agent
+
+Approvals are binding (they gate the verify lane); **comments are advisory** — a human's
+running commentary, with a defined path back into your plan, spec, and code.
+`qa/comments.json` is the ledger; `qa/lib/comments.mjs` is the library, mirroring
+`qa/lib/approvals.mjs`'s shape: state, validation, transitions, nothing fabricated.
+
+**The loop of record:**
+
+1. A human adds a comment from the preview console — on a screen, a spec clause, a
+   design-system token or component, or an architecture tree node.
+2. You observe it — `review_comments { waitForComment: true }` (plugin) blocks until a new
+   one lands; without the plugin, `node qa/comment.mjs --list --open`.
+3. You act on it — update the plan, the spec clause, or the code it points at.
+4. You resolve it **after** acting, with a note saying what you did —
+   `resolve_comment { id, note }` (plugin) or `node qa/comment.mjs --resolve <id> --note
+   "..."` (CLI, records author `agent-cli`). The console then shows `resolved` plus your
+   note. The console never edits code: humans comment, agents resolve.
+
+| Command | What |
+|---|---|
+| `node qa/comment.mjs --list` | Every comment, open and resolved, with resolution notes |
+| `node qa/comment.mjs --list --open` | Only open comments |
+| `node qa/comment.mjs --resolve <id> --note "..."` | Resolve a comment, recording what changed |
+
+A comment targets one of: a **screen**, an **element** (screen + testTag), a **spec-line**
+(file + clause id), a **design-system** token, an **architecture** path, or **general**.
+`addComment` refuses empty text and a target missing the fields its type requires — the
+same refusal-over-fabrication stance as approvals. A ledger that exists but cannot be
+parsed is never treated as empty (that would hide real feedback); reads and writes surface
+the honest error instead.
 
 ## UI feedback loop — see what you build, without a device
 
 <!-- >>> cmp:feature inspector -->
-While building or changing ANY screen, use the preview loop instead of an emulator: it
-renders this app's REAL screens (real DI, real theme, seeded data) headlessly in seconds
-and tells you exactly what your edit changed.
+While building or changing any screen, use the preview loop instead of an emulator. It
+renders this app's real screens (real DI, real theme, seeded data) headlessly in seconds
+and tells you what your edit changed.
 
 **With the create-cmp plugin (cmp-inspector MCP tools):**
 
-1. `preview { projectDir }` — once per session. Returns a live gallery URL (give it to
-   the human; it re-renders itself on every save) plus per-screen structural summaries
-   for you. Sources are watched; you never run Gradle by hand.
-2. After each edit: `preview_status { waitForRender: true }` — blocks until the
-   render/compile outcome. `changedLastRender` names the screens your edit touched
-   (empty = the edit reached no screen); `lastErrorSource: "compile"` means the edit
-   didn't even build (the compiler's `e:` lines are in `lastError`).
-3. `preview_diff { screen }` — one call proves the change: verdict `proven-clean` /
-   `changed-with-regressions` / `no-change`. No snapshot bookkeeping needed.
+1. `preview { projectDir }` — once per session. Returns a live gallery URL for the human
+   (it re-renders on every save) and per-screen structural summaries for you. Sources are
+   watched; you never run Gradle by hand.
+2. After each edit: `preview_status { waitForRender: true }` blocks until the outcome.
+   `changedLastRender` names the screens your edit touched (empty = the edit reached no
+   screen); `lastErrorSource: "compile"` means the edit did not build — the compiler's `e:`
+   lines are in `lastError`.
+3. `preview_diff { screen }` proves the change in one call: `proven-clean` /
+   `changed-with-regressions` / `no-change`. No snapshot bookkeeping.
 
 **Without the plugin:** `./gradlew :composeApp:renderScreens` renders every screen to
 `composeApp/build/previews/<id>/{screen.png, tree.json}` (`-Pscreen=<id>` for one);
 `node qa/preview-gallery.mjs` builds a self-contained gallery page from the output.
 
-Screens come from `inspector/PreviewRegistry.kt` (desktopMain). The `add-feature`/`add-screen`
-stamper **auto-registers** a stamped screen there (at the `// cmp:anchor preview-registry`
-marker). **When you add a screen by hand, register it there** — a forced-state variant is just
-another entry (`"home@empty"`).
-Assert on the `tree.json` structure; never read PNG bytes (pixels are for humans).
+Screens come from `inspector/PreviewRegistry.kt` (desktopMain). The `add-feature` and
+`add-screen` stampers auto-register stamped screens at the `// cmp:anchor preview-registry`
+marker; when you add a screen by hand, register it there — a forced-state variant is just
+another entry (`"home@empty"`). Every common component also carries a story entry
+(`"component.<kebab-name>"` in `inspector/ComponentStories.kt`); when you add a component,
+add its story — the lane's `componentStories` step fails naming the missing id otherwise.
+Assert on `tree.json` structure; never read PNG bytes. Pixels are for humans.
 <!-- <<< cmp:feature inspector -->
 <!-- >>> cmp:feature dev-client -->
 For one interactive window instead of stills of every screen:
@@ -98,7 +245,8 @@ conventions) · [`CONTRIBUTING.md`](./CONTRIBUTING.md) (workflow, Conventional C
 
 | Command | What |
 |---|---|
-| `node qa/verify.mjs` | The verify lane (profile `local`) — your definition of done |
+| `node qa/verify.mjs` | The verify lane (profile `local`) — the done checkpoint, run once |
 | `./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:hotRunDesktop --auto` | Desktop dev-client with hot reload |

package/template/README.md

@@ -1,6 +1,6 @@
 # __APP_NAME__
 
-A Kotlin / Compose Multiplatform app — generated by
+A Kotlin / Compose Multiplatform app, generated by
 [create-cmp](https://github.com/kvdm-co-pilot/create-cmp) with a **verification harness**:
 the architecture, testing conventions, and definition of done are enforced mechanically, not
 by convention. Start with [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md); AI collaborators
@@ -80,32 +80,28 @@ Every change must pass the verify lane (`node qa/verify.mjs`) and commit its upd
 
 ## Verification enforcement
 
-This project ships a **Stop hook** (`.claude/settings.json`) that makes `CLAUDE.md`'s definition
-of done mechanical instead of honor-system, for AI sessions using Claude Code.
-
-**What it does:** when a session tries to end, the hook runs `node qa/receipt-check.mjs --hook`.
-That script recomputes a sha256 hash over this project's "verified surface" (`composeApp/`,
-`specs/`, `qa/`, and the Gradle build files — see `qa/lib/inputs-hash.mjs`) and compares it to the
-`inputs.hash` recorded in the committed `qa/evidence/latest.json`. If the receipt is a `PASS` and
-its hash matches the current tree, the session ends silently. If source changed without a fresh
-`PASS` receipt — or the receipt is missing, a `FAIL`, or predates this mechanism — the hook blocks
-with the specific reason and asks you to run `node qa/verify.mjs` and commit the receipt. **It runs
-no build and no tests — only file hashing —** so it costs milliseconds, and it never fires twice in
-a row for the same stop.
-
-Doc-only edits (`*.md`, `README`, `.github/`, `.claude/`) are deliberately **outside** the verified
-surface, so editing docs never invalidates a good receipt or forces a needless re-run — the intent
-is transparent enforcement, not a hostile one.
-
-**Why:** `CLAUDE.md` already says a change is "not done" without a `PASS` receipt committed. The
-Stop hook is what makes that check happen automatically instead of relying on the AI session to
-remember to run it.
-
-**Escape hatch:** this is your project. If you don't want the hook, delete or comment out the
-`Stop` block in [`.claude/settings.json`](./.claude/settings.json) — nothing else depends on it
-locally. Note that CI independently enforces the same "receipt attests HEAD" check on every push
-(see `.github/workflows/verify.yml`), so disabling the local hook only trades an immediate local
-signal for a later one in CI.
+For AI sessions using Claude Code, a **Stop hook** (`.claude/settings.json`) makes
+`CLAUDE.md`'s definition of done mechanical instead of honor-system.
+
+**What it does:** when a session tries to end, the hook runs
+`node qa/receipt-check.mjs --hook`. That script recomputes a sha256 hash over the project's
+verified surface (`composeApp/`, `specs/`, `qa/`, and the Gradle build files — see
+`qa/lib/inputs-hash.mjs`) and compares it to the `inputs.hash` in the committed
+`qa/evidence/latest.json`. A `PASS` receipt whose hash matches the tree ends the session
+silently. Source changed without a fresh `PASS` — or a missing, failed, or pre-mechanism
+receipt — blocks with the specific reason and asks for `node qa/verify.mjs` plus a committed
+receipt. It runs no build and no tests, only file hashing, so it costs milliseconds, and it
+never fires twice in a row for the same stop.
+
+Doc-only edits (`*.md`, `README`, `.github/`, `.claude/`) are deliberately outside the
+verified surface: editing docs never invalidates a good receipt. The intent is transparent
+enforcement, not a hostile one.
+
+**Escape hatch:** this is your project. If you don't want the hook, delete the `Stop` block
+in [`.claude/settings.json`](./.claude/settings.json) — nothing else depends on it locally.
+CI independently enforces the same "receipt attests HEAD" check on every push
+(`.github/workflows/verify.yml`), so disabling the local hook only trades an immediate
+signal for a later one.
 
 ---