create-cmp-cli 0.7.1 → 0.9.0

package/src/lib/upgrade.mjs

@@ -73,18 +73,49 @@ export function lockstepViolation(versions) {
   const kotlin = versions.kotlin;
   const ksp = versions.ksp;
   if (!kotlin || !ksp) return null;
-  if (!ksp.startsWith(`${kotlin}-`)) {
+  // Two valid schemes: the classic KSP1 form "<kotlin>-<kspVersion>" (e.g.
+  // 2.2.20-2.0.4), and the KSP2 aligned form where the KSP version EQUALS the
+  // Kotlin version (e.g. kotlin 2.3.10 ↔ ksp 2.3.10 — KSP dropped the -<ksp> suffix).
+  if (ksp !== kotlin && !ksp.startsWith(`${kotlin}-`)) {
     return (
-      `kotlin ${kotlin} and ksp ${ksp} are OUT OF LOCKSTEP — ksp must be ` +
-      `"${kotlin}-<kspVersion>" (e.g. "${kotlin}-2.0.4"). Refusing to write a broken pairing.`
+      `kotlin ${kotlin} and ksp ${ksp} are OUT OF LOCKSTEP — ksp must be either ` +
+      `"${kotlin}" (KSP2 aligned) or "${kotlin}-<kspVersion>" (e.g. "${kotlin}-2.0.4"). ` +
+      `Refusing to write a broken pairing.`
     );
   }
   return null;
 }
 
+/**
+ * Apply a set's `androidSdk` levels (compileSdk / targetSdk) to the text of
+ * composeApp/build.gradle.kts. These live in build.gradle.kts, NOT the version
+ * catalog — but they are coupled to the set (a dependency built against a newer
+ * Android API forces a higher compileSdk, which in turn needs a newer AGP), so
+ * the version set manages them too. Surgical, line-preserving replacement of the
+ * `compileSdk = N` / `targetSdk = N` assignments.
+ * @param {string} content build.gradle.kts text
+ * @param {{compileSdk?:number,targetSdk?:number}} androidSdk
+ * @returns {{content:string, changes:Array<{key,from,to}>}}
+ */
+export function applyAndroidSdk(content, androidSdk) {
+  if (!androidSdk || content == null) return { content, changes: [] };
+  const changes = [];
+  let out = content;
+  for (const key of ["compileSdk", "targetSdk"]) {
+    if (androidSdk[key] == null) continue;
+    const re = new RegExp(`(\\b${key}\\s*=\\s*)(\\d+)`);
+    const m = out.match(re);
+    if (m && Number(m[2]) !== Number(androidSdk[key])) {
+      changes.push({ key, from: m[2], to: String(androidSdk[key]) });
+      out = out.replace(re, `$1${androidSdk[key]}`);
+    }
+  }
+  return { content: changes.length ? out : content, changes };
+}
+
 /**
  * Compute the full upgrade plan for one catalog + optional gradle.properties +
- * optional wrapper properties. Pure — no filesystem.
+ * optional wrapper properties + optional composeApp/build.gradle.kts. Pure — no filesystem.
  * @param {object} params
  * @param {string} params.tomlContent gradle/libs.versions.toml text
  * @param {string|null} params.gradlePropertiesContent gradle.properties text (null = absent)
@@ -101,7 +132,7 @@ export function lockstepViolation(versions) {
  *   fromOurTemplate: boolean
  * }}
  */
-export function planUpgrade({ tomlContent, gradlePropertiesContent, wrapperPropertiesContent, set }) {
+export function planUpgrade({ tomlContent, gradlePropertiesContent, wrapperPropertiesContent, buildGradleContent = null, set }) {
   const projectVersions = parseVersions(tomlContent);
   const diff = diffAgainstSet(projectVersions, set);
   const resulting = resultingVersions(projectVersions, diff.changes);
@@ -146,6 +177,17 @@ export function planUpgrade({ tomlContent, gradlePropertiesContent, wrapperPrope
     }
   }
 
+  // Android compileSdk / targetSdk (composeApp/build.gradle.kts), when the set pins them.
+  let sdkChanges = [];
+  let newBuildGradleContent = null;
+  if (!lockstepError && set.androidSdk && buildGradleContent !== null) {
+    const r = applyAndroidSdk(buildGradleContent, set.androidSdk);
+    if (r.changes.length > 0) {
+      sdkChanges = r.changes;
+      newBuildGradleContent = r.content;
+    }
+  }
+
   return {
     diff,
     lockstepError,
@@ -154,6 +196,8 @@ export function planUpgrade({ tomlContent, gradlePropertiesContent, wrapperPrope
     newGradlePropertiesContent,
     wrapperChange,
     newWrapperPropertiesContent,
+    sdkChanges,
+    newBuildGradleContent,
     fromOurTemplate: looksLikeOurTemplate(tomlContent),
   };
 }

package/src/scaffold.mjs

@@ -15,7 +15,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { validate, formatErrors } from "./lib/schema.mjs";
 import { buildTokenMap, replaceTokens, replacePathTokens, isBinaryPath, slugifyAppName } from "./lib/tokens.mjs";
@@ -26,6 +26,7 @@ import {
   deleteDisabledFeaturePaths,
 } from "./lib/toggle.mjs";
 import { rewriteTabSurfaces } from "./lib/tabs.mjs";
+import { seedConfigAdrs } from "./lib/adr-seed.mjs";
 import { copyDir, listFiles, listDirsDeepestFirst } from "./lib/fsutil.mjs";
 import { runVerify, printVerifyVerdict } from "./lib/verify.mjs";
 import { colors, step, ok, warn } from "./lib/log.mjs";
@@ -155,6 +156,42 @@ function stripDisabledBlocks(projectDir, disabled) {
   }
 }
 
+// Regenerate docs/ARCHITECTURE.md's `cmp:generated` sections against the tree
+// AS STAMPED — after disabled-feature paths are deleted, tab surfaces are
+// rewritten, the package is renamed, and marker blocks are stripped. The
+// template ships the doc true for the RAW template's shape (all features on);
+// any config that changes the tree (--no-ios removes iosMain and its actuals,
+// custom tabs add PlaceholderScreen.kt, …) would otherwise fail the verify
+// lane's archDoc freshness gate on a fresh, untouched app. Same philosophy as
+// rewriteTabSurfaces: derived surfaces are regenerated from what was actually
+// stamped, never hand-corrected afterward.
+//
+// The generator itself is the project's OWN vendored walker
+// (qa/lib/arch-doc.mjs) — imported from the stamped output so the engine can
+// never drift from what the app's `node qa/arch-doc.mjs --check` will verify
+// later. Tolerant by design: a template without the walker or the doc (the
+// synthetic test templates; a --no-e2e config that strips qa/) skips quietly,
+// and a walker failure warns but never blocks the stamp.
+async function regenerateArchDoc(projectDir) {
+  const walkerPath = path.join(projectDir, "qa", "lib", "arch-doc.mjs");
+  const docPath = path.join(projectDir, "docs", "ARCHITECTURE.md");
+  if (!fs.existsSync(walkerPath) || !fs.existsSync(docPath)) return;
+  step("Regenerating docs/ARCHITECTURE.md generated sections for the stamped tree…");
+  try {
+    const { writeArchDoc } = await import(pathToFileURL(walkerPath).href);
+    const result = writeArchDoc(projectDir);
+    if (!result.ok) {
+      warn(`ARCHITECTURE.md regeneration skipped: ${result.reason}`);
+    } else if (result.wrote) {
+      process.stdout.write(`  arch-doc → updated section(s): ${result.changedSections.join(", ")}\n`);
+    } else {
+      process.stdout.write("  arch-doc → already fresh for this configuration\n");
+    }
+  } catch (err) {
+    warn(`ARCHITECTURE.md regeneration failed (stamp continues): ${err?.message ?? err}`);
+  }
+}
+
 /**
  * Resolve the Android SDK location from the environment or the conventional
  * install path, then write `local.properties` (sdk.dir) into the project so
@@ -358,6 +395,20 @@ export async function scaffold(config, opts = {}) {
   );
   stripDisabledBlocks(projectDir, disabled);
 
+  // (e.1) Seed one project ADR per configuration decision that deviates from
+  // the interview default (--no-room, --no-ios, a non-"both" auth choice —
+  // see src/lib/adr-seed.mjs for why this is an engine hook, not a SKILL.md
+  // instruction). MUST run before regenerateArchDoc below so the stamped
+  // project's own adr-index walker (qa/lib/arch-doc.mjs, which scans
+  // docs/adr/*.md) picks the seeded files up in the same pass.
+  step("Seeding project ADRs for configuration decisions…");
+  const { seeded } = seedConfigAdrs(projectDir, config, (m) => process.stdout.write(`${m}\n`));
+  if (seeded.length === 0) process.stdout.write("  no configuration deviated from the interview default — nothing to seed\n");
+
+  // (e.2) regenerate the architecture doc's derived sections for the tree as
+  // stamped — see regenerateArchDoc above.
+  await regenerateArchDoc(projectDir);
+
   // Write local.properties (sdk.dir) so the Gradle build can find the Android
   // SDK even when ANDROID_HOME/ANDROID_SDK_ROOT aren't exported (manifest
   // stampPipeline step 7). Skip silently if no SDK is found and env vars are

package/src/versions/candidates.json

@@ -0,0 +1,4 @@
+{
+  "description": "Staging area for CANDIDATE version sets awaiting canary certification. `scripts/promote-set.mjs` applies one candidate to a fresh full-featured scaffold (catalog + gradle.properties + wrapper + composeApp/build.gradle.kts compileSdk/targetSdk), builds it for real (Android assembleDebug + the device-free lane gates + the iOS framework link), and ONLY on all-green promotes it into registry.json as a new proven-green set (the new default `upgrade` target). Red leaves registry.json untouched. Same shape as a registry set: `versions` mirrors the [versions] table, `androidSdk` pins compileSdk/targetSdk, plus `status: candidate` and `baseline`.",
+  "candidates": []
+}

package/src/versions/registry.json

@@ -31,12 +31,100 @@
         "version": "8.11.1",
         "distributionUrl": "https://services.gradle.org/distributions/gradle-8.11.1-bin.zip"
       },
+      "androidSdk": {
+        "compileSdk": 35,
+        "targetSdk": 35
+      },
       "notes": [
         "KSP must be `<kotlin>-<kspVersion>`: kotlin 2.2.20 pairs with ksp 2.2.20-2.0.4. Never bump one without the other — Kotlin / KSP / Compose / Room / AGP move as ONE set or the build dies.",
         "ksp.useKSP2=true is REQUIRED when Room's KSP processor runs on Kotlin/Native (iOS): KSP1 fails with `ClassNotFoundException: org.jetbrains.kotlin.cli.utilities.MainKt` (the KSP2/iOS catch-22).",
         "Room 2.8.4 + sqlite-bundled 2.6.2 is the KMP-native pairing; Room < 2.7 has no Kotlin/Native support at all.",
         "Gradle wrapper 8.11.1 matches AGP 8.7.3 (AGP 8.7 requires Gradle >= 8.9)."
       ]
+    },
+    {
+      "id": "2026.07c",
+      "label": "Conservative bump — coil + kotlinx-serialization to latest; lockstep held at 2026.06 (ktor 3.2.0 excluded: needs DEX 040 / newer AGP R8)",
+      "status": "proven-green",
+      "versions": {
+        "kotlin": "2.2.20",
+        "agp": "8.7.3",
+        "google-services": "4.4.2",
+        "compose-multiplatform": "1.10.3",
+        "koin": "4.1.1",
+        "ktor": "3.1.0",
+        "room": "2.8.4",
+        "sqlite": "2.6.2",
+        "ksp": "2.2.20-2.0.4",
+        "kotlinx-serialization": "1.9.0",
+        "kotlinx-datetime": "0.7.0",
+        "lifecycle": "2.10.0",
+        "navigation": "2.9.2",
+        "firebase-gitlive": "2.1.0",
+        "coil": "3.2.0",
+        "androidx-core": "1.15.0",
+        "androidx-activity": "1.10.1"
+      },
+      "gradleProperties": {
+        "ksp.useKSP2": "true"
+      },
+      "gradleWrapper": {
+        "version": "8.11.1",
+        "distributionUrl": "https://services.gradle.org/distributions/gradle-8.11.1-bin.zip"
+      },
+      "androidSdk": {
+        "compileSdk": 35,
+        "targetSdk": 35
+      },
+      "notes": [
+        "Delta vs 2026.06: coil 3.1.0→3.2.0, kotlinx-serialization 1.7.3→1.9.0. Everything else, including the entire Kotlin/KSP/Compose/Room/AGP lockstep, is held identical — the conservative-first strategy: prove the canary + upgrade loop before a risky compiler-version jump.",
+        "ktor 3.2.0 was EXCLUDED after the canary caught it: ktor-client-core-jvm 3.2.0 carries a backtick identifier with a space (`use streaming syntax`) that requires DEX version 040, which AGP 8.7.3's bundled R8 (8.7.18) rejects at :composeApp:mergeExtDexDebug. Bumping ktor needs a newer AGP/R8 — deferred to a bold set.",
+        "Bumps verified latest via Maven Central 2026-07-15.",
+        "Promoted by promote-set.mjs 2026-07-15: green on :composeApp:assembleDebug, :composeApp:desktopTest, :composeApp:linkDebugFrameworkIosSimulatorArm64 (456s). Evidence: qa-artifacts/canary/2026.07c.json"
+      ]
+    },
+    {
+      "id": "2026.07r",
+      "label": "July 2026 recommended standard — Kotlin 2.3.10 / KSP 2.3.10 / Compose 1.11.1 / AGP 8.13.2 / Gradle 8.14.3, compileSdk 36. ktor held at 3.1.0 (3.2.0 not dexable at minSdk 24) and androidx UI libs held at SDK-36-safe versions.",
+      "status": "proven-green",
+      "versions": {
+        "kotlin": "2.3.10",
+        "agp": "8.13.2",
+        "google-services": "4.5.0",
+        "compose-multiplatform": "1.11.1",
+        "koin": "4.2.2",
+        "ktor": "3.1.0",
+        "room": "2.8.4",
+        "sqlite": "2.7.0",
+        "ksp": "2.3.10",
+        "kotlinx-serialization": "1.9.0",
+        "kotlinx-datetime": "0.7.0",
+        "lifecycle": "2.10.0",
+        "navigation": "2.9.2",
+        "firebase-gitlive": "2.4.0",
+        "coil": "3.2.0",
+        "androidx-core": "1.15.0",
+        "androidx-activity": "1.10.1"
+      },
+      "gradleProperties": {
+        "ksp.useKSP2": "true"
+      },
+      "gradleWrapper": {
+        "version": "8.14.3",
+        "distributionUrl": "https://services.gradle.org/distributions/gradle-8.14.3-bin.zip"
+      },
+      "androidSdk": {
+        "compileSdk": 36,
+        "targetSdk": 35
+      },
+      "notes": [
+        "Sourced, mutually-compatible July 2026 set (verified 2026-07-15): Kotlin 2.3.10 is the newest Kotlin with a matching KSP (KSP tops out at 2.3.10; no KSP for Kotlin 2.4.10). KSP2 aligned scheme (ksp == kotlin). Compose Multiplatform 1.11.1 (latest stable) is compatible with Kotlin 2.3.10.",
+        "AGP 8.13.2 is the top of the Kotlin-2.3-supported AGP range (per developer.android.com/build/kotlin-support). Gradle 8.14.3 satisfies AGP 8.13's minimum. compileSdk moves to 36 (Android 16, the latest STABLE API) — now a managed field applied to composeApp/build.gradle.kts.",
+        "ktor HELD at 3.1.0: even AGP 8.13.2's newer R8 (8.13.19) cannot dex ktor-client-core 3.2.0 — its backtick identifier `use streaming syntax` needs DEX version 040, which D8 only emits at a much higher minSdk than 24. Not an R8-version issue; ktor 3.2.0 is not adoptable at a normal minSdk yet.",
+        "HELD ON PURPOSE: androidx-core (1.15.0) and lifecycle (2.10.0) are kept at their SDK-36-safe versions. Their latest (core 1.19.0, lifecycle 2.11.0) require compileSdk 37 — an unreleased-stable API — so 'latest-of-each' is NOT the recommended-stable choice; revisit when a compileSdk-37 set is warranted. targetSdk held at 35 for runtime-behavior stability.",
+        "Verified by the canary: Kotlin 2.3.10 + Compose 1.11.1 + firebase-gitlive 2.4.0 compile the template source and dex cleanly at compileSdk 36.",
+        "Promoted by promote-set.mjs 2026-07-15: green on :composeApp:assembleDebug, :composeApp:desktopTest, :composeApp:linkDebugFrameworkIosSimulatorArm64 (425s). Evidence: qa-artifacts/canary/2026.07r.json"
+      ]
     }
   ]
 }

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