create-cmp-cli 0.7.1 → 0.9.0

package/template/qa/scaffold-feature.mjs

@@ -21,7 +21,7 @@
 // that spans both, applied together.
 //
 //   feature    (default) — all 11 files; DI repo+usecase+viewModel; nav
-//              route+import; spec FEATURE-01..06.
+//              route+import; spec FEATURE-01..07.
 //   repository <Entity>  — ONLY the 5 data/domain files; DI repo+usecase ONLY;
 //              no nav, no viewModel, no spec file, zero SPEC tags. The
 //              positional arg IS the entity (no --entity, no feature name).
@@ -94,23 +94,35 @@ if (!IDENTIFIER_RE.test(entityName)) {
 // `repository` preset has no feature name (no nav/presentation/spec slice), so
 // F/f/F_UPPER are never read for it — the rename map still needs harmless
 // values to build (its feature-shaped entries never match repository-preset
-// file contents, which only reference Item/ItemRepository/GetItemsUseCase).
+// file contents, which only reference the exemplar's own entity, e.g.
+// Item/ItemRepository/GetItemsUseCase for the default `home` exemplar).
 const F = featureName ?? entityName; // PascalCase feature, e.g. Favorites
 const f = F[0].toLowerCase() + F.slice(1); // camelCase/package segment, e.g. favorites
 const F_UPPER = F.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase(); // FAVORITES
 const E = entityName; // PascalCase entity, e.g. Favorite
 
 // ── Resolve the target project's real package ───────────────────────────────
-// This script runs POST-scaffold, so __PACKAGE__ is already resolved in the
-// target project. Parse it from composeApp/build.gradle.kts (namespace) or,
-// failing that, from any source file's `package` line.
+// This script runs POST-scaffold, so the package placeholder token is already
+// resolved in the target project. Parse it from composeApp/build.gradle.kts
+// (namespace) or, failing that, from any source file's `package` line.
+//
+// Detect "still unresolved" by TOKEN SHAPE (`/^__[A-Z_]+__$/`), never by
+// comparing against the literal placeholder string: this script is itself a
+// template file that goes through the scaffold's own token-replacement pass,
+// which does a blind text substitution of that literal placeholder -> the
+// real package wherever it appears in file CONTENT — including a string
+// literal sitting right here. A literal comparison would silently become
+// `m[1] !== "<the real package>"` post-stamp (always true for the very
+// project it should detect as unresolved) and never fire. A shape regex never
+// spells the placeholder out, so the pipeline has nothing to match.
+const UNRESOLVED_TOKEN_RE = /^__[A-Z_]+__$/;
 
 function resolvePackage() {
   const gradleFile = path.join(ROOT, "composeApp", "build.gradle.kts");
   if (fs.existsSync(gradleFile)) {
     const contents = fs.readFileSync(gradleFile, "utf8");
     const m = contents.match(/namespace\s*=\s*"([^"]+)"/);
-    if (m && m[1] !== "__PACKAGE__") return m[1];
+    if (m && !UNRESOLVED_TOKEN_RE.test(m[1])) return m[1];
   }
   const homeViewModel = path.join(
     ROOT,
@@ -149,46 +161,126 @@ function guessPackageDirFromDisk() {
 const PACKAGE = resolvePackage();
 const PACKAGE_DIR = PACKAGE.split(".").join("/");
 
+// ── The file set (§4) ───────────────────────────────────────────────────────
+// Source paths are relative to composeApp/src/<sourceSet>/kotlin/<PACKAGE_DIR>.
+
+const SRC = (sourceSet) => path.join(ROOT, "composeApp/src", sourceSet, "kotlin", PACKAGE_DIR);
+
+// ── Configurable exemplar (GENESIS-FLOW-DESIGN.md §1) ───────────────────────
+// This stamper clones from the CONFIGURED exemplar (qa/approvals.json's
+// `exemplarFeature`, defaulting to `home`) — the same resolution
+// qa/lib/approvals.mjs's governed-artifact registry uses, so a stamped feature
+// always matches what the registry hashes. Tolerant of a missing/pre-genesis-flow
+// qa/lib/approvals.mjs (mirrors the seedUnreviewed step further down): a broken
+// or absent import falls back to the hardcoded `home`/`Item` shape that predates
+// configurability — this script must never refuse to stamp because the approvals
+// ledger's tooling isn't present.
+let approvalsLib = null;
+try {
+  approvalsLib = await import("./lib/approvals.mjs");
+} catch {
+  approvalsLib = null;
+}
+
+function resolveSourceNames() {
+  if (approvalsLib && typeof approvalsLib.resolveExemplarNames === "function") {
+    return approvalsLib.resolveExemplarNames(ROOT);
+  }
+  return { f: "home", F: "Home", F_UPPER: "HOME", E: "Item" };
+}
+
+const { f: SOURCE_f, F: SOURCE_F, F_UPPER: SOURCE_F_UPPER, E: SOURCE_E } = resolveSourceNames();
+
+// Extras beyond the canonical 11-file shape (§1: "clone the canonical set and
+// WARN, listing what it skipped — never silently"). Scoped by NAME, not by
+// directory membership: the exemplar's presentation directory can legitimately
+// hold files that aren't "this feature's own" (e.g. the shipped `home`
+// exemplar's directory also holds `DetailScreen.kt` — a deliberately
+// NOT-cloned, permanent fixture per add-feature's SKILL.md, not drift) — so a
+// file only counts as an extra when its name is actually built FROM the
+// exemplar's own identifiers (starts with `${sourceF}` in presentation/, or
+// contains the entity as a whole word in the shared domain/data directories).
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function scanDirForExtras(sourceSet, dirRel, canonicalBasenames, matches) {
+  const dirAbs = path.join(SRC(sourceSet), dirRel);
+  if (!fs.existsSync(dirAbs)) return [];
+  return fs
+    .readdirSync(dirAbs, { withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith(".kt") && matches(e.name) && !canonicalBasenames.has(e.name))
+    .map((e) => path.relative(ROOT, path.join(dirAbs, e.name)));
+}
+
+function findExemplarExtras(sourceF, sourceLowerF, sourceEntity) {
+  const namedForFeature = (n) => n.startsWith(sourceF);
+  const entityWholeWord = new RegExp(`\\b${escapeRegExp(sourceEntity)}\\b`);
+  return [
+    ...scanDirForExtras("commonMain", `presentation/${sourceLowerF}`, new Set([`${sourceF}Screen.kt`, `${sourceF}ViewModel.kt`]), namedForFeature),
+    ...scanDirForExtras("commonTest", `presentation/${sourceLowerF}`, new Set([`${sourceF}ViewModelTest.kt`]), namedForFeature),
+    ...scanDirForExtras("desktopTest", `presentation/${sourceLowerF}`, new Set([`${sourceF}ScreenTest.kt`, `${sourceF}GoldenTreeTest.kt`]), namedForFeature),
+    ...scanDirForExtras("commonMain", "domain/model", new Set([`${sourceEntity}.kt`]), (n) => entityWholeWord.test(n)),
+    ...scanDirForExtras("commonMain", "domain/repository", new Set([`${sourceEntity}Repository.kt`]), (n) => entityWholeWord.test(n)),
+    ...scanDirForExtras("commonMain", "domain/usecase", new Set([`Get${sourceEntity}sUseCase.kt`]), (n) => entityWholeWord.test(n)),
+    ...scanDirForExtras("commonMain", "data/remote", new Set([`${sourceEntity}RepositoryImpl.kt`]), (n) => entityWholeWord.test(n)),
+    ...scanDirForExtras("commonTest", "testing/fakes", new Set([`Fake${sourceEntity}Repository.kt`]), (n) => entityWholeWord.test(n)),
+  ];
+}
+
+const exemplarExtras = findExemplarExtras(SOURCE_F, SOURCE_f, SOURCE_E);
+if (exemplarExtras.length > 0) {
+  console.log(
+    `WARNING: the "${SOURCE_f}" exemplar has files beyond the canonical 11-file shape — only the canonical set is cloned, these are SKIPPED:\n` +
+      exemplarExtras.map((p) => `  - ${p}`).join("\n"),
+  );
+}
+
 // ── The rename map (§3) ──────────────────────────────────────────────────────
 // Whole-word (\b-delimited), applied LONGEST KEY FIRST so compound entries
-// (ItemRepositoryImpl) resolve before their substrings (ItemRepository, Item).
-// Anything not in this list is left untouched by design (see design doc §3
-// "LEAVE GENERIC" — awaitItem, items, item, goldenItems, itemId, onItemClick,
-// id, title, subtitle, and every androidx./kotlinx./org.koin./kotlin. token).
+// (<Entity>RepositoryImpl) resolve before their substrings (<Entity>Repository,
+// <Entity>). Generated from the CLONE-SOURCE's own names (SOURCE_F/SOURCE_f/
+// SOURCE_E/SOURCE_F_UPPER) rather than hardcoded `Home`/`home`/`Item`/`HOME` — when
+// the source is the shipped `home` exemplar these resolve to exactly those
+// literals, so stamping from `home` is byte-identical to before configurability
+// existed (pinned by test/genesis-flow.test.mjs's parity pin). Anything not in this
+// list is left untouched by design (see design doc §3 "LEAVE GENERIC" —
+// awaitItem, items, item, goldenItems, itemId, onItemClick, id, title, subtitle,
+// and every androidx./kotlinx./org.koin./kotlin. token).
 
 const RENAME_MAP = [
-  ["HomeScreenTest", `${F}ScreenTest`],
-  ["HomeViewModelTest", `${F}ViewModelTest`],
-  ["HomeGoldenTreeTest", `${F}GoldenTreeTest`],
-  ["HomeScreen", `${F}Screen`],
-  ["HomeViewModel", `${F}ViewModel`],
-  ["HomeUiState", `${F}UiState`],
-  ["home_title", `${f}_title`],
-  ["home_error", `${f}_error`],
-  ["FakeItemRepository", `Fake${E}Repository`],
-  ["ItemRepositoryImpl", `${E}RepositoryImpl`],
-  ["ItemRepository", `${E}Repository`],
-  ["GetItemsUseCase", `Get${E}sUseCase`],
-  ["getItemsCallCount", `get${E}sCallCount`],
-  ["getItems", `get${E}s`],
-  ["Item", E],
-  // Spec + test SPEC-tag retargeting (§6): HOME-0N -> <F_UPPER>-0N, then the
-  // bare HOME -> <F_UPPER> (must run AFTER the -0 form or "HOME-0" would be
-  // partially consumed oddly — longest-key-first already orders this).
-  ["HOME-0", `${F_UPPER}-0`],
-  ["HOME", F_UPPER],
+  [`${SOURCE_F}ScreenTest`, `${F}ScreenTest`],
+  [`${SOURCE_F}ViewModelTest`, `${F}ViewModelTest`],
+  [`${SOURCE_F}GoldenTreeTest`, `${F}GoldenTreeTest`],
+  [`${SOURCE_F}Screen`, `${F}Screen`],
+  [`${SOURCE_F}ViewModel`, `${F}ViewModel`],
+  [`${SOURCE_f}_title`, `${f}_title`],
+  [`${SOURCE_f}_error`, `${f}_error`],
+  [`${SOURCE_f}_empty`, `${f}_empty`],
+  [`${SOURCE_f}_loading`, `${f}_loading`],
+  [`${SOURCE_f}_retry`, `${f}_retry`],
+  [`${SOURCE_f}_item_`, `${f}_item_`],
+  [`Fake${SOURCE_E}Repository`, `Fake${E}Repository`],
+  [`${SOURCE_E}RepositoryImpl`, `${E}RepositoryImpl`],
+  [`${SOURCE_E}Repository`, `${E}Repository`],
+  [`Get${SOURCE_E}sUseCase`, `Get${E}sUseCase`],
+  [`get${SOURCE_E}sCallCount`, `get${E}sCallCount`],
+  [`get${SOURCE_E}s`, `get${E}s`],
+  [SOURCE_E, E],
+  // Spec + test SPEC-tag retargeting (§6): <SOURCE_F_UPPER>-0N -> <F_UPPER>-0N,
+  // then the bare <SOURCE_F_UPPER> -> <F_UPPER> (must run AFTER the -0 form or
+  // "<SOURCE_F_UPPER>-0" would be partially consumed oddly — longest-key-first
+  // already orders this).
+  [`${SOURCE_F_UPPER}-0`, `${F_UPPER}-0`],
+  [SOURCE_F_UPPER, F_UPPER],
   // Package segment / path / golden filename / display text. Order matters:
-  // must run after HomeXxx / home_xxx above so those compounds are already
-  // resolved; the bare `home` word only matches the standalone package
-  // segment, golden filename stem, and prose by this point.
-  ["home", f],
-  ["Home", F],
+  // must run after <SOURCE_F>Xxx / <SOURCE_f>_xxx above so those compounds are
+  // already resolved; the bare source-feature word only matches the standalone
+  // package segment, golden filename stem, and prose by this point.
+  [SOURCE_f, f],
+  [SOURCE_F, F],
 ].sort((a, b) => b[0].length - a[0].length);
 
-function escapeRegExp(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
 const COMPILED_RENAMES = RENAME_MAP.map(([from, to]) => [new RegExp(`\\b${escapeRegExp(from)}\\b`, "g"), to]);
 
 function applyRename(text) {
@@ -197,27 +289,30 @@ function applyRename(text) {
   return out;
 }
 
-// ── The file set (§4) ───────────────────────────────────────────────────────
-// Source paths are relative to composeApp/src/<sourceSet>/kotlin/<PACKAGE_DIR>.
-
-const SRC = (sourceSet) => path.join(ROOT, "composeApp/src", sourceSet, "kotlin", PACKAGE_DIR);
-
 // Every entry is tagged with the presets it belongs to. `feature` gets all 11
 // (the union); `repository` gets just the 5 data/domain files; `screen` gets
 // just the 6 presentation+tests+spec files. Filtered by the active preset
 // right after definition — nothing below this point sees the untagged list.
+//
+// `from:` sides are built from the CLONE-SOURCE names (SOURCE_F/SOURCE_f/
+// SOURCE_E) instead of hardcoded `home`/`Item` literals — this is exactly the
+// canonical-11-file SHAPE `exemplarKotlinFileSet` in qa/lib/approvals.mjs
+// encodes (that function is the registry's copy; this one is the stamper's,
+// kept independently so the stamper works even without qa/lib/approvals.mjs —
+// see the resolveSourceNames() fallback above). test/approvals-exemplar-list.test.mjs
+// pins that the two never disagree for a real project.
 const ALL_FILES = [
-  { from: path.join(SRC("commonMain"), "domain/model/Item.kt"), to: path.join(SRC("commonMain"), `domain/model/${E}.kt`), presets: ["feature", "repository"] },
-  { from: path.join(SRC("commonMain"), "domain/repository/ItemRepository.kt"), to: path.join(SRC("commonMain"), `domain/repository/${E}Repository.kt`), presets: ["feature", "repository"] },
-  { from: path.join(SRC("commonMain"), "domain/usecase/GetItemsUseCase.kt"), to: path.join(SRC("commonMain"), `domain/usecase/Get${E}sUseCase.kt`), presets: ["feature", "repository"] },
-  { from: path.join(SRC("commonMain"), "data/remote/ItemRepositoryImpl.kt"), to: path.join(SRC("commonMain"), `data/remote/${E}RepositoryImpl.kt`), presets: ["feature", "repository"] },
-  { from: path.join(SRC("commonTest"), "testing/fakes/FakeItemRepository.kt"), to: path.join(SRC("commonTest"), `testing/fakes/Fake${E}Repository.kt`), presets: ["feature", "repository"] },
-  { from: path.join(SRC("commonMain"), "presentation/home/HomeScreen.kt"), to: path.join(SRC("commonMain"), `presentation/${f}/${F}Screen.kt`), presets: ["feature", "screen"], wrapInBaseScreen: true },
-  { from: path.join(SRC("commonMain"), "presentation/home/HomeViewModel.kt"), to: path.join(SRC("commonMain"), `presentation/${f}/${F}ViewModel.kt`), presets: ["feature", "screen"] },
-  { from: path.join(SRC("commonTest"), "presentation/home/HomeViewModelTest.kt"), to: path.join(SRC("commonTest"), `presentation/${f}/${F}ViewModelTest.kt`), presets: ["feature", "screen"] },
-  { from: path.join(SRC("desktopTest"), "presentation/home/HomeScreenTest.kt"), to: path.join(SRC("desktopTest"), `presentation/${f}/${F}ScreenTest.kt`), presets: ["feature", "screen"] },
-  { from: path.join(SRC("desktopTest"), "presentation/home/HomeGoldenTreeTest.kt"), to: path.join(SRC("desktopTest"), `presentation/${f}/${F}GoldenTreeTest.kt`), presets: ["feature", "screen"] },
-  { from: path.join(ROOT, "specs/home.spec.md"), to: path.join(ROOT, `specs/${f}.spec.md`), isDefaultSpec: true, presets: ["feature", "screen"] },
+  { from: path.join(SRC("commonMain"), `domain/model/${SOURCE_E}.kt`), to: path.join(SRC("commonMain"), `domain/model/${E}.kt`), presets: ["feature", "repository"] },
+  { from: path.join(SRC("commonMain"), `domain/repository/${SOURCE_E}Repository.kt`), to: path.join(SRC("commonMain"), `domain/repository/${E}Repository.kt`), presets: ["feature", "repository"] },
+  { from: path.join(SRC("commonMain"), `domain/usecase/Get${SOURCE_E}sUseCase.kt`), to: path.join(SRC("commonMain"), `domain/usecase/Get${E}sUseCase.kt`), presets: ["feature", "repository"] },
+  { from: path.join(SRC("commonMain"), `data/remote/${SOURCE_E}RepositoryImpl.kt`), to: path.join(SRC("commonMain"), `data/remote/${E}RepositoryImpl.kt`), presets: ["feature", "repository"] },
+  { from: path.join(SRC("commonTest"), `testing/fakes/Fake${SOURCE_E}Repository.kt`), to: path.join(SRC("commonTest"), `testing/fakes/Fake${E}Repository.kt`), presets: ["feature", "repository"] },
+  { from: path.join(SRC("commonMain"), `presentation/${SOURCE_f}/${SOURCE_F}Screen.kt`), to: path.join(SRC("commonMain"), `presentation/${f}/${F}Screen.kt`), presets: ["feature", "screen"], wrapInBaseScreen: true },
+  { from: path.join(SRC("commonMain"), `presentation/${SOURCE_f}/${SOURCE_F}ViewModel.kt`), to: path.join(SRC("commonMain"), `presentation/${f}/${F}ViewModel.kt`), presets: ["feature", "screen"] },
+  { from: path.join(SRC("commonTest"), `presentation/${SOURCE_f}/${SOURCE_F}ViewModelTest.kt`), to: path.join(SRC("commonTest"), `presentation/${f}/${F}ViewModelTest.kt`), presets: ["feature", "screen"] },
+  { from: path.join(SRC("desktopTest"), `presentation/${SOURCE_f}/${SOURCE_F}ScreenTest.kt`), to: path.join(SRC("desktopTest"), `presentation/${f}/${F}ScreenTest.kt`), presets: ["feature", "screen"] },
+  { from: path.join(SRC("desktopTest"), `presentation/${SOURCE_f}/${SOURCE_F}GoldenTreeTest.kt`), to: path.join(SRC("desktopTest"), `presentation/${f}/${F}GoldenTreeTest.kt`), presets: ["feature", "screen"] },
+  { from: path.join(ROOT, `specs/${SOURCE_f}.spec.md`), to: path.join(ROOT, `specs/${f}.spec.md`), isDefaultSpec: true, presets: ["feature", "screen"] },
 ];
 
 const FILES = ALL_FILES.filter((file) => file.presets.includes(preset));
@@ -229,8 +324,8 @@ for (const file of FILES) {
   if (!fs.existsSync(file.from)) {
     die(
       `exemplar source file missing: ${path.relative(ROOT, file.from)}\n` +
-        "This script must run in an unmodified (or already-featured) create-cmp scaffold " +
-        "where the `home` exemplar still exists.",
+        `This script must run in an unmodified (or already-featured) create-cmp scaffold ` +
+        `where the "${SOURCE_f}" exemplar (qa/approvals.json's "exemplarFeature") still exists in its canonical 11-file shape.`,
     );
   }
 }
@@ -273,7 +368,7 @@ if (FILES.some((file) => file.isDefaultSpec) && fs.existsSync(path.join(ROOT, `s
 function defaultSpec() {
   return `# Spec: ${f}
 
-> Generated by \`scaffold-feature.mjs\` from the \`home\` exemplar shape. Refine the clause
+> Generated by \`scaffold-feature.mjs\` from the \`${SOURCE_f}\` exemplar shape. Refine the clause
 > prose below for ${F}'s real behavior (ids stay fixed) before running the verify lane.
 
 - **${F_UPPER}-01** — Given the ${F} screen opens, When ${f} are being loaded, Then a loading
@@ -281,14 +376,17 @@ function defaultSpec() {
 - **${F_UPPER}-02** — Given the repository returns ${f}, When loading completes, Then the ${f}
   are listed with their title and subtitle, and no error is shown.
 - **${F_UPPER}-03** — Given the repository fails, When loading completes, Then a human-readable
-  error message is shown (\`${f}_error\`) and no ${f} are visible.
+  error message is shown (\`${f}_error\`) and no ${f} are visible — the copy is mapped in
+  presentation from the failure's \`DomainError\` kind, never a raw exception message.
 - **${F_UPPER}-04** — Given a load has failed, When the data source recovers and the user
-  triggers a reload, Then the error clears and the ${f} render.
+  triggers a reload (\`${f}_retry\`), Then the error clears and the ${f} render.
 - **${F_UPPER}-05** — Given ${f} are listed, When the user taps an item, Then the app navigates
   to that item's detail.
 - **${F_UPPER}-06** — Given the ${F} screen renders, When its structure is inspected, Then the
   screen matches its committed golden tree (\`qa/golden/${f}.json\`) — structural regressions
   are intentional, declared changes only.
+- **${F_UPPER}-07** — Given the repository succeeds with zero ${f}, When loading completes, Then
+  the empty state is shown (\`${f}_empty\`) and neither ${f} nor an error are visible.
 `;
 }
 
@@ -309,7 +407,7 @@ function wrapScreenInBaseScreen(content, relPathForErrors) {
   const themeImportIdx = lines.findIndex((l) => /^import .+\.presentation\.theme\./.test(l));
   if (themeImportIdx === -1) {
     die(
-      `no presentation.theme import found in ${relPathForErrors} — the HomeScreen exemplar ` +
+      `no presentation.theme import found in ${relPathForErrors} — the ${SOURCE_F}Screen exemplar ` +
         "drifted from the shape this stamper wraps; cannot place the BaseScreen import.",
     );
   }
@@ -319,11 +417,14 @@ function wrapScreenInBaseScreen(content, relPathForErrors) {
   );
   lines.splice(themeImportIdx, 0, importLine);
 
-  // 2. Root container start: the exemplar's body root is a top-level `    Column(`.
-  const rootIdx = lines.findIndex((l) => l === "    Column(");
+  // 2. Root container start: the exemplar's body root is a top-level `    ScreenColumn(`
+  //    call (the component-vocabulary rewrite — see docs/proposals/component-system-deep-dive.md
+  //    §5). The tag literal inside the call (`screenTag = "home"`) is renamed separately by
+  //    RENAME_MAP, so match on the call shape only, not the full line.
+  const rootIdx = lines.findIndex((l) => /^ {4}ScreenColumn\(/.test(l));
   if (rootIdx === -1) {
     die(
-      `root "    Column(" not found in ${relPathForErrors} — the HomeScreen exemplar drifted ` +
+      `root "    ScreenColumn(" not found in ${relPathForErrors} — the ${SOURCE_F}Screen exemplar drifted ` +
         "from the shape this stamper wraps in BaseScreen.",
     );
   }
@@ -339,7 +440,7 @@ function wrapScreenInBaseScreen(content, relPathForErrors) {
   if (funCloseIdx === -1 || lines[funCloseIdx - 1] !== "    }") {
     die(
       `could not locate the root container's closing brace in ${relPathForErrors} — the ` +
-        "HomeScreen exemplar drifted from the shape this stamper wraps in BaseScreen.",
+        `${SOURCE_F}Screen exemplar drifted from the shape this stamper wraps in BaseScreen.`,
     );
   }
   const rootCloseIdx = funCloseIdx - 1;
@@ -547,7 +648,7 @@ if (dryRun) {
     );
   }
   if (writesSpec) {
-    console.log(`\nspecs/${f}.spec.md will be written with default clauses ${F_UPPER}-01..06.`);
+    console.log(`\nspecs/${f}.spec.md will be written with default clauses ${F_UPPER}-01..07.`);
   } else {
     console.log("\nNo spec file written by this preset (zero SPEC clauses/tags added).");
   }
@@ -580,7 +681,23 @@ for (const result of fileResults) {
 
 console.log(`✓ Scaffolded ${planLabel} [preset: ${preset}] — ${filesWritten} files written, ${injectionsApplied} anchor injections applied.`);
 if (writesSpec) {
-  console.log(`  specs/${f}.spec.md written with default clauses ${F_UPPER}-01..06 — refine the prose next.`);
+  console.log(`  specs/${f}.spec.md written with default clauses ${F_UPPER}-01..07 — refine the prose next.`);
+
+  // Approvals seeding (VERIFICATION-LAYER-DESIGN.md §2): the new feature's spec
+  // is a governed artifact (`feature-spec:<name>`) — seed it unreviewed so the
+  // verify lane's `approvals` gate SKIP-warns until a human signs off. v1 does
+  // NOT refuse to stamp over this (warn-then-enforce-at-verify is the honest
+  // default) — reuses `approvalsLib` (already resolved above, tolerantly, for
+  // clone-source resolution) so a missing or out-of-date qa/lib/approvals.mjs
+  // (an older, pre-approvals scaffold) never blocks the stamp itself.
+  try {
+    if (!approvalsLib || typeof approvalsLib.seedUnreviewed !== "function") throw new Error("no seedUnreviewed export");
+    const artifactId = `feature-spec:${f}`;
+    approvalsLib.seedUnreviewed(ROOT, artifactId);
+    console.log(`  Approval: specs/${f}.spec.md is unreviewed — run \`node qa/approve.mjs ${artifactId}\` once you've reviewed it.`);
+  } catch {
+    console.log("  (approvals seeding skipped — qa/lib/approvals.mjs not found in this scaffold)");
+  }
 } else {
   console.log("  No spec file written by this preset (zero SPEC clauses/tags added).");
 }

package/template/qa/setup-hooks.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// Enable this project's shipped git hooks — one-time, idempotent, no dependency
+// and no hook-manager. Run it once after `git init`: it points git at the
+// tracked .githooks/ directory (core.hooksPath) and makes the hooks executable.
+//
+// The pre-push hook it activates gates a push on the evidence receipt attesting
+// HEAD — the same cheap check CI runs, before your code leaves the machine.
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+function main() {
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { stdio: "ignore" });
+  } catch {
+    console.error("Not a git repository yet. Run `git init` first, then `node qa/setup-hooks.mjs`.");
+    process.exit(1);
+  }
+  // core.hooksPath (git 2.9+) makes the tracked .githooks/ the hooks directory,
+  // so the hooks live in the repo and survive as one source of truth.
+  execFileSync("git", ["config", "core.hooksPath", ".githooks"], { stdio: "ignore" });
+  try {
+    fs.chmodSync(path.join(".githooks", "pre-push"), 0o755);
+  } catch {
+    // best-effort — on a filesystem without exec bits the hook still runs via core.hooksPath
+  }
+  console.log("✓ git hooks enabled (core.hooksPath = .githooks).");
+  console.log("  pre-push now blocks a push whose committed receipt doesn't attest HEAD.");
+  console.log("  Bypass in a pinch with `git push --no-verify`; CI still enforces the check.");
+}
+
+main();

package/template/qa/verify.mjs

@@ -26,6 +26,9 @@ import { fileURLToPath } from "node:url";
 
 import { computeInputsHash } from "./lib/inputs-hash.mjs";
 import { compareTokenDrift } from "./lib/token-drift.mjs";
+import { evaluateApprovalsGate } from "./lib/approvals.mjs";
+import { evaluateComponentStoryParity } from "./lib/component-stories.mjs";
+import { ARCH_DOC_REL_PATH, SECTION_IDS, regenerateArchDoc } from "./lib/arch-doc.mjs";
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const EVIDENCE_DIR = path.join(ROOT, "qa", "evidence");
@@ -176,6 +179,77 @@ function stepSpecCoverage() {
   };
 }
 
+// Human-approval gate (VERIFICATION-LAYER-DESIGN.md §2) — pure Node, no Gradle,
+// same grouping as specCoverage. The decision itself lives in
+// qa/lib/approvals.mjs (evaluateApprovalsGate); this step only adds the
+// name/duration bookkeeping every step in this file carries.
+function stepApprovals() {
+  const started = Date.now();
+  const { verdict, reason, statuses } = evaluateApprovalsGate(ROOT);
+  return {
+    name: "approvals",
+    verdict,
+    reason,
+    durationMs: Date.now() - started,
+    details: { artifacts: statuses.map((s) => ({ id: s.id, status: s.status, hash: s.hash })) },
+  };
+}
+
+// Component ↔ story parity gate (STUDIO-REDESIGN.md §3.3) — pure Node, no
+// Gradle, same grouping as specCoverage/approvals. The decision itself lives
+// in qa/lib/component-stories.mjs (evaluateComponentStoryParity); this step
+// only adds the name/duration bookkeeping every step in this file carries.
+function stepComponentStories() {
+  const started = Date.now();
+  const { verdict, reason, details } = evaluateComponentStoryParity(ROOT);
+  return { name: "componentStories", verdict, reason, durationMs: Date.now() - started, details };
+}
+
+// Architecture-doc freshness gate (Wave B, docs/proposals/architecture-document-
+// standard.md §6) — pure Node, no Gradle, same grouping as specCoverage/
+// approvals. The decision itself lives in qa/lib/arch-doc.mjs
+// (regenerateArchDoc); this step only adds the name/duration bookkeeping every
+// step in this file carries, plus wording the FAIL reason for an AI
+// collaborator (name the stale/missing section, name the fix command).
+function stepArchDoc() {
+  const started = Date.now();
+  const elapsed = () => Date.now() - started;
+
+  const result = regenerateArchDoc(ROOT);
+  if (!result.ok) {
+    return { name: "archDoc", verdict: "SKIP", reason: `${result.reason} — nothing to check`, durationMs: elapsed() };
+  }
+  if (result.unknownSections.length > 0) {
+    return {
+      name: "archDoc",
+      verdict: "FAIL",
+      reason: `${ARCH_DOC_REL_PATH} has cmp:generated marker(s) with no registered generator: ${result.unknownSections.join(", ")} — add a generator in qa/lib/arch-doc.mjs or remove the marker.`,
+      durationMs: elapsed(),
+    };
+  }
+
+  const stale = result.changed || result.missingSections.length > 0;
+  if (!stale) {
+    return { name: "archDoc", verdict: "PASS", durationMs: elapsed(), details: { sectionsChecked: SECTION_IDS.length } };
+  }
+
+  const lines = [`${ARCH_DOC_REL_PATH} is stale — a generated section no longer matches the tree:`];
+  for (const id of result.changedSections) {
+    lines.push(`  [${id}] regenerating would change this section.`);
+  }
+  for (const id of result.missingSections) {
+    lines.push(`  [${id}] marker missing from the doc entirely — never generated.`);
+  }
+  lines.push("Run: node qa/arch-doc.mjs");
+  return {
+    name: "archDoc",
+    verdict: "FAIL",
+    reason: lines.join("\n"),
+    durationMs: elapsed(),
+    details: { changedSections: result.changedSections, missingSections: result.missingSections },
+  };
+}
+
 function stepBuild() {
   const res = sh(`${GRADLEW} :composeApp:assembleDebug --console=plain`);
   return {
@@ -372,15 +446,44 @@ function stepE2eSmoke() {
   //    that steal focus over the app — a Maestro assert would then see only the dialog;
   //  - MAESTRO_DRIVER_STARTUP_TIMEOUT gives the UiAutomator2 driver a generous budget to come
   //    up on a slow emulator (the built-in default gives up too early under load).
-  // Both are benign, reversible, and only touch the device while the lane is driving it.
+  // Both are benign, reversible, and only touch the device while the lane is driving it —
+  // hide_error_dialogs is restored to its pre-run value (or deleted, returning the device
+  // to its default) in the finally below, on every exit path.
+  // hide_error_dialogs suppresses the OS dialog, NEVER the underlying event — so after the
+  // run we grep the device log for ANR/crash lines the dialog would have shown, and FAIL on
+  // them. The eyes must report what automation stability had to hide.
+  const prevHideErrorDialogs = sh("adb shell settings get global hide_error_dialogs").out.trim();
   sh("adb shell settings put global hide_error_dialogs 1");
-  const res = sh("maestro test qa/e2e/smoke.yaml", { env: { ...process.env, MAESTRO_DRIVER_STARTUP_TIMEOUT: "120000" } });
-  return {
-    name: "e2eSmoke",
-    verdict: res.ok ? "PASS" : "FAIL",
-    reason: res.ok ? undefined : `Maestro smoke failed (flow cites the SHELL spec clauses it proves):\n${res.out.split("\n").slice(-15).join("\n")}`,
-    durationMs: install.durationMs + res.durationMs,
-  };
+  sh("adb logcat -c"); // clear so the post-run dump only reflects this run
+  try {
+    const res = sh("maestro test qa/e2e/smoke.yaml", { env: { ...process.env, MAESTRO_DRIVER_STARTUP_TIMEOUT: "120000" } });
+    if (!res.ok) {
+      return {
+        name: "e2eSmoke",
+        verdict: "FAIL",
+        reason: `Maestro smoke failed (flow cites the SHELL spec clauses it proves):\n${res.out.split("\n").slice(-15).join("\n")}`,
+        durationMs: install.durationMs + res.durationMs,
+      };
+    }
+    const anrDump = sh("adb logcat -d -b system,crash,main");
+    const anrRe = /ANR in |FATAL EXCEPTION/i;
+    if (anrDump.ok && anrRe.test(anrDump.out)) {
+      const anrLines = anrDump.out.split("\n").filter((l) => anrRe.test(l)).slice(0, 10).join("\n");
+      return {
+        name: "e2eSmoke",
+        verdict: "FAIL",
+        reason: `Maestro smoke passed, but the device log shows an ANR/crash during the run (hide_error_dialogs only suppresses the OS dialog, never the underlying event):\n${anrLines}`,
+        durationMs: install.durationMs + res.durationMs,
+      };
+    }
+    return { name: "e2eSmoke", verdict: "PASS", durationMs: install.durationMs + res.durationMs };
+  } finally {
+    if (prevHideErrorDialogs && prevHideErrorDialogs !== "null") {
+      sh(`adb shell settings put global hide_error_dialogs ${prevHideErrorDialogs}`);
+    } else {
+      sh("adb shell settings delete global hide_error_dialogs");
+    }
+  }
 }
 
 // ── Lane ───────────────────────────────────────────────────────────────────
@@ -388,9 +491,12 @@ function stepE2eSmoke() {
 const stepsForProfile = {
   // scaffold: what `create-cmp --verify` proves at stamp time — specCoverage,
   // the full JVM tier (unit + conformance + golden + UI tests) plus the Android build.
-  scaffold: [stepSpecCoverage, stepBuild, stepUnitTests],
+  scaffold: [stepSpecCoverage, stepApprovals, stepComponentStories, stepArchDoc, stepBuild, stepUnitTests],
   local: [
     stepSpecCoverage,
+    stepApprovals,
+    stepComponentStories,
+    stepArchDoc,
     stepBuild,
     stepUnitTests,
     stepConformance,
@@ -465,6 +571,9 @@ const receipt = {
 
 fs.mkdirSync(EVIDENCE_DIR, { recursive: true });
 fs.writeFileSync(path.join(EVIDENCE_DIR, "latest.json"), `${JSON.stringify(receipt, null, 2)}\n`);
+// latest.json is the single receipt-of-record. Commit it with your change: the
+// studio console's Evidence audit trail reconstructs the full history from the
+// git log of this file — every commit is one verified, attributed state.
 
 if (asJson) console.log(JSON.stringify(receipt, null, 2));
 else console.log(`\n${verdict === "PASS" ? "✅" : "❌"} verify lane: ${verdict} — receipt written to qa/evidence/latest.json (commit it with your change)`);

package/template/specs/app-base.spec.md

@@ -7,8 +7,7 @@
 
 - **ARCH-01** — Given any file in `presentation`, When its imports **and fully-qualified
   inline references** are inspected, Then none resolve into the `data` layer (presentation
-  depends on domain only; qualifying the name inline instead of importing is the same
-  violation).
+  depends on domain only).
 - **ARCH-02** — Given any file in `domain`, When its imports **and fully-qualified inline
   references** are inspected, Then none resolve into `presentation`, `data`, or `di`, and
   none reference Compose, Koin, or platform types (domain is pure Kotlin).
@@ -16,11 +15,37 @@
   corresponding `*ViewModelTest` exists (no untested presentation state).
 - **ARCH-04** — Given any file in a `presentation` feature package that contains a
   `@Composable` function, When its source is inspected, Then it declares at least one
-  `testTag` (scoped by content, not `*Screen.kt` filename — split `Content.kt` UI files are
-  covered, ViewModel-only files are exempt).
+  literal `testTag` **or** passes a `screenTag =` argument to a component imported from
+  `presentation.components` (scoped by content, not `*Screen.kt` filename — split
+  `Content.kt` UI files are covered, ViewModel-only files are exempt). Component-derived
+  tags count as tag provenance: a screen built entirely from `ScreenColumn`/`AppHeader`/
+  `ContentStateContainer`/etc. is automation-reachable through the tags those components
+  emit (`<screenTag>_screen`, `<screenTag>_title`, `<screenTag>_loading`, …) even without a
+  literal `testTag` of its own.
 - **ARCH-05** — Given any file outside `presentation/theme`, When its source is inspected,
   Then it constructs no literal `Color(0x…)` values (design colors come from the token
   catalog).
+- **ARCH-06** — Given any repository interface in `domain/repository`, When its one-shot
+  operations (`suspend fun`s) are inspected, Then each declares an `AppResult<…>` return
+  type — raw exceptions never cross the data → domain boundary; failures travel as typed
+  `DomainError` values assigned inside the data implementation.
+- **ARCH-07** — Given any ViewModel in `presentation`, When its source is inspected, Then it
+  contains no `try`/`catch`/`runCatching` — ViewModels fold over `AppResult` and map
+  `DomainError` kinds to user-facing copy; a raw exception message is never shown to a user.
+- **ARCH-08** — Given any file in the `data` layer, When its source is inspected, Then the
+  only exception-catching mechanism is the shared `suspendRunCatching` helper
+  (`data/AppResultCatching.kt`), and the helper always rethrows `CancellationException` —
+  cancellation is never swallowed into a failure state.
+- **ARCH-09** — Given any file in `data`, When its imports and fully-qualified inline
+  references are inspected, Then none resolve into `presentation` or `di` (data serves
+  domain contracts; it never reaches upward).
+- **ARCH-10** — Given any file in `core`, When its imports and fully-qualified inline
+  references are inspected, Then none resolve into `presentation`, `data`, or `di` (core
+  is leaf utility code; `domain` at most).
+- **ARCH-11** — Given any file in a presentation feature package (`components/` excluded),
+  When its source is inspected, Then it references neither `CircularProgressIndicator` nor
+  `LinearProgressIndicator` directly — loading is presented through the components
+  registry (`ContentStateContainer`/`ContentStateDefaults`), never hand-rolled per screen.
 
 ## App shell
 
@@ -33,6 +58,18 @@
 - **SHELL-04** — Given the app renders any screen, When interactive elements are present,
   Then each is perceivable by automation: it exposes a testTag, text, or content description.
 - **SHELL-05** — Given any screen registered directly on the NavHost (not a shell tab), When
-  it renders, Then its content is composed inside `BaseScreen` — a bare destination that
-  never touches inset APIs still renders under the status bar, which SHELL-03 alone cannot
-  catch.
+  it renders, Then its content is composed inside `BaseScreen`.
+
+## Component vocabulary
+
+> Component *contracts* — the shared state/a11y behavior every screen inherits from
+> `presentation/components/*.kt` (the governed `components` artifact). Feature clauses
+> (e.g. `HOME-NN`) keep citing feature behavior; these clauses are covered once, here.
+
+- **COMP-01** — Given any screen with a data-backed state, When it renders, Then
+  loading/error/empty are presented by `ContentStateContainer` with tags
+  `<screen>_loading` / `<screen>_error` / `<screen>_empty`.
+- **COMP-02** — Given a recoverable load failure and a retry handler, When the error state
+  renders, Then a `<screen>_retry` control of at least 48 dp is present.
+- **COMP-03** — Given any interactive registry component, When it renders, Then its
+  pointer target is at least 48×48 dp.