create-cmp-cli 0.3.2 → 0.5.0

package/README.md

@@ -18,6 +18,16 @@ machine-enforced definition of done.
 
 ---
 
+```bash
+npx create-cmp-cli@latest my-app --name Acme --package com.acme.app --yes --verify
+```
+
+Deterministic (stamps a frozen, CI-verified template), fully non-interactive with flags, and
+exits non-zero on failure. Every generated project ships its own verify lane — `node qa/verify.mjs`,
+8 gates, evidence receipts — with nothing installed. Agent-readable: [llms.txt](./llms.txt) ·
+[options.schema.json](./options.schema.json). Also answers to `npm create compose-multiplatform`
+and `npm create kmp` — official aliases ([packages/aliases](packages/aliases)) that delegate here.
+
 ## What is this, in plain words
 
 **Day one, it's a scaffolder.** One command gives you a working Compose Multiplatform app —
@@ -88,6 +98,9 @@ Everything except `create` works on **any** KMP project, not just ones this tool
 | `create-cmp clean` | Reclaims disk: stale Kotlin/Native toolchains, `build/` dirs. Shows sizes, asks before deleting. |
 | `create-cmp verify` | Runs the green-build gate against an existing project. Exit 0 = green. Useful in scripts and CI. |
 
+Hit a KMP build error? [Common CMP/KMP build errors and fixes](docs/errors/README.md) — kotlin↔KSP
+mismatch, the KSP2/iOS catch-22, `SDK location not found`, `No space left on device`, version drift.
+
 ## The Claude Code plugin (8 skills)
 
 ```text

package/llms.txt

@@ -0,0 +1,29 @@
+# create-cmp
+
+> The AI delivery harness for Kotlin/Compose Multiplatform (Android + iOS): scaffolds a deterministic, green-building app in which every project carries a spec-driven verify lane, evidence receipts, and mechanical enforcement of "done".
+
+create-cmp (npm package: `create-cmp-cli`) stamps a frozen, CI-verified template — it never asks an LLM to freehand project code, so every scaffold is identical and every scaffold builds. It runs fully non-interactively with flags, validates them against a machine-readable schema (`options.schema.json`), and exits non-zero on failure. The `--verify` flag builds the generated app before reporting success.
+
+Non-interactive one-liner (flags per `options.schema.json` and `create-cmp --help`):
+
+```bash
+npx create-cmp-cli@latest my-app --name Acme --package com.acme.app --yes --verify
+```
+
+Other flags: `--bundle-id`, `--region`, `--theme-prefix`, `--ios/--no-ios`, `--firebase/--no-firebase`, `--auth <email|phone|both|none>`, `--room/--no-room`, `--e2e/--no-e2e`, `--inspector/--no-inspector`, `--dev-client/--no-dev-client`, `--tabs Home:home,Profile:person`, `--target-dir`, `--force`. Subcommands `doctor`, `upgrade`, `clean`, and `verify` work on any KMP project.
+
+Official alias packages (same tool, same flags, same maintainer): `npm create compose-multiplatform@latest my-app` and `npm create kmp@latest my-app` both delegate to create-cmp-cli.
+
+create-cmp is also invokable as a Claude Code plugin (`/plugin marketplace add kvdm-co-pilot/create-cmp`, then `/plugin install create-cmp`) with eight skills and the `cmp-inspector` MCP server. Generated projects self-verify without the plugin installed: `node qa/verify.mjs` runs 8 gates (spec coverage, build, unit tests, conformance, golden trees, token drift, a11y, on-device E2E) and writes a content-hash-bound evidence receipt; a Stop hook and CI both refuse "done" without a fresh PASS receipt.
+
+## Docs
+
+- [README](https://github.com/kvdm-co-pilot/create-cmp/blob/main/README.md): full feature tour — CLI commands, plugin skills, and the harness every generated project carries
+- [Usage guide](https://github.com/kvdm-co-pilot/create-cmp/blob/main/docs/USAGE.md): every command, skill, MCP tool, and workflow in detail
+- [Options schema](https://github.com/kvdm-co-pilot/create-cmp/blob/main/options.schema.json): machine-readable JSON Schema for the engine config the flags build
+- [Changelog](https://github.com/kvdm-co-pilot/create-cmp/blob/main/CHANGELOG.md): release history, Keep-a-Changelog format
+
+## Examples
+
+- [create-cmp-showcase](https://github.com/kvdm-co-pilot/create-cmp-showcase): public repo built entirely by this tool, every commit carrying its evidence receipt
+- [Refusal PR #1](https://github.com/kvdm-co-pilot/create-cmp-showcase/pull/1): live proof of the harness blocking a bad change and naming the violated rule

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.3.2",
-  "description": "The AI delivery harness for Kotlin/Compose Multiplatform — scaffolds a green-building app (Android + iOS) in minutes and holds AI-driven changes to a machine-enforced verify lane with a committed evidence receipt. Installs the `create-cmp` command.",
+  "version": "0.5.0",
+  "description": "The AI delivery harness for Kotlin/Compose Multiplatform — a deterministic, non-interactive project generator that scaffolds a green-building app (Android + iOS) in minutes, then holds AI-driven changes to a machine-enforced verify lane with a committed evidence receipt. Installs the `create-cmp` command.",
   "type": "module",
   "bin": {
     "create-cmp": "bin/create-cmp.mjs",
@@ -14,7 +14,8 @@
     "bin",
     "src",
     "template",
-    "options.schema.json"
+    "options.schema.json",
+    "llms.txt"
   ],
   "scripts": {
     "test": "node --test",
@@ -24,13 +25,23 @@
   "keywords": [
     "create-cmp",
     "create-cmp-cli",
+    "compose multiplatform",
     "compose-multiplatform",
+    "kotlin multiplatform",
     "kotlin-multiplatform",
+    "kotlin",
+    "compose",
     "kmp",
     "cmp",
     "scaffold",
+    "project generator",
+    "cli",
+    "claude code",
+    "ai agent",
     "android",
-    "ios"
+    "ios",
+    "verify",
+    "e2e"
   ],
   "license": "MIT",
   "author": "Karel van der Merwe",

package/src/bootstrap/checks.mjs

@@ -71,7 +71,11 @@ export const checks = [
   },
   {
     id: "jdk",
-    label: "JDK 17 (Temurin)",
+    // Label states the actual requirement (17+), and detect() reports the
+    // resolved major — previously the row read "JDK 17 (Temurin)" while
+    // happily accepting JDK 21, a label/evidence contradiction that erodes
+    // trust in every other row (field-report finding 2.6).
+    label: "JDK (17+ required)",
     platforms: ["darwin", "linux"],
     detect() {
       const r = probe("javac", ["-version"]);
@@ -80,7 +84,10 @@ export const checks = [
       const m = out.match(/(\d+)(\.\d+)?/);
       const major = m ? parseInt(m[1], 10) : 0;
       if (!out) return { present: false, detail: "not found" };
-      return { present: major >= 17, detail: out.split("\n")[0] };
+      return {
+        present: major >= 17,
+        detail: `resolved major ${major} — ${out.split("\n")[0]}`,
+      };
     },
     installCommand: () =>
       isMac ? "brew install --cask temurin@17" : "sdk install java 17.0.13-tem  # (sdkman)",

package/src/lib/tabs.mjs

@@ -0,0 +1,370 @@
+// Tab-driven surface regeneration (scaffold pipeline step b.3).
+//
+// The template ships the DEFAULT tabs (Home:home, Profile:person) baked into
+// three surfaces; this module rewrites them from `config.tabs` at stamp time
+// so a non-default tabs config can never go stale:
+//   - presentation/navigation/AppTab.kt      (the appTabs() list — one entry per tab)
+//   - presentation/navigation/AppNavHost.kt  (the appTabs(...) call-site wiring)
+//   - qa/e2e/smoke.yaml                      (Maestro taps/asserts per tab)
+// Tabs without a shipped feature screen (anything that doesn't slug to
+// `home`/`profile`) get a generated PlaceholderScreen stub carrying the
+// `<slug>_title` testTag the smoke flow asserts.
+//
+// Everything is written in TEMPLATE-TOKEN form (__PACKAGE__ contents, literal
+// com/example/app paths) BEFORE token replacement / package rename, so the
+// normal pipeline stamps these files like any other template file. For the
+// default tabs config the output is byte-identical to the static template
+// files — golden/deterministic scaffolding is a core product property.
+
+import fs from "node:fs";
+import path from "node:path";
+
+// --- slug + naming ------------------------------------------------------------
+
+/**
+ * Nav-item tag slug for a tab label.
+ * MUST MIRROR `navItemTag` in
+ * template/composeApp/src/commonMain/kotlin/com/example/app/presentation/navigation/AppShell.kt:
+ * lowercase, every run of chars outside [a-z0-9] collapsed to a single "_",
+ * leading/trailing "_" trimmed. ("My Stuff!" → "my_stuff")
+ * @param {string} label
+ * @returns {string}
+ */
+export function navSlug(label) {
+  return String(label)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+}
+
+// Kotlin hard keywords — a derived parameter name colliding with one must be backticked.
+const KOTLIN_HARD_KEYWORDS = new Set([
+  "as", "break", "class", "continue", "do", "else", "false", "for", "fun",
+  "if", "in", "interface", "is", "null", "object", "package", "return",
+  "super", "this", "throw", "true", "try", "typealias", "typeof", "val",
+  "var", "when", "while",
+]);
+
+/**
+ * Kotlin parameter name for a tab: camelCase of the slug ("my_stuff" → "myStuff"),
+ * backticked when it collides with a hard keyword or starts with a digit.
+ * @param {string} slug
+ * @returns {string}
+ */
+export function kotlinParamName(slug) {
+  const parts = slug.split("_").filter(Boolean);
+  const name = parts
+    .map((p, i) => (i === 0 ? p : p[0].toUpperCase() + p.slice(1)))
+    .join("");
+  if (KOTLIN_HARD_KEYWORDS.has(name) || /^[0-9]/.test(name)) return `\`${name}\``;
+  return name;
+}
+
+/**
+ * Material icon symbol for a CLI icon key: PascalCase the key's alphanumeric
+ * parts ("home" → "Home", "shopping_cart" → "ShoppingCart", "ShoppingCart"
+ * stays as-is). The template depends on compose.materialIconsExtended, so any
+ * `Icons.Filled.*` symbol from the extended set resolves.
+ * @param {string} key
+ * @returns {string}
+ */
+export function iconSymbol(key) {
+  return String(key)
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((p) => p[0].toUpperCase() + p.slice(1))
+    .join("");
+}
+
+/** Escape a label for use inside a Kotlin double-quoted string literal. */
+function kotlinString(s) {
+  return String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\$/g, "\\$");
+}
+
+/**
+ * Derive per-tab info (slug, param, icon) and validate the set: every label
+ * must produce a non-empty, unique slug (the slug is the nav testTag AND the
+ * Kotlin parameter name — collisions or empties cannot compile/automate).
+ * @param {Array<{label:string, icon:string}>} tabs
+ */
+export function tabInfos(tabs) {
+  const seen = new Map();
+  return tabs.map((tab) => {
+    const slug = navSlug(tab.label);
+    if (!slug) {
+      throw new Error(
+        `tab label ${JSON.stringify(tab.label)} produces an empty nav slug — labels need at least one [a-z0-9] character`
+      );
+    }
+    if (seen.has(slug)) {
+      throw new Error(
+        `tab labels ${JSON.stringify(seen.get(slug))} and ${JSON.stringify(tab.label)} both slug to "${slug}" — nav testTags must be unique`
+      );
+    }
+    seen.set(slug, tab.label);
+    return { label: tab.label, slug, param: kotlinParamName(slug), icon: iconSymbol(tab.icon) };
+  });
+}
+
+// --- generators ----------------------------------------------------------------
+
+/**
+ * Render AppTab.kt (template-token form). For the default tabs this reproduces
+ * the static template file byte-for-byte.
+ * @param {ReturnType<typeof tabInfos>} infos
+ */
+export function renderAppTabsKt(infos) {
+  const iconImports = [...new Set(infos.map((t) => t.icon))]
+    .sort()
+    .map((i) => `import androidx.compose.material.icons.filled.${i}`)
+    .join("\n");
+  const params = infos.map((t) => `    ${t.param}: @Composable () -> Unit,`).join("\n");
+  const entries = infos
+    .map((t) => `    AppTab("${kotlinString(t.label)}", Icons.Filled.${t.icon}, ${t.param}),`)
+    .join("\n");
+
+  return `package __PACKAGE__.presentation.navigation
+
+import androidx.compose.material.icons.Icons
+${iconImports}
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.graphics.vector.ImageVector
+
+// A single bottom-nav tab: its label, icon, and the screen it renders.
+data class AppTab(
+    val label: String,
+    val icon: ImageVector,
+    val content: @Composable () -> Unit,
+)
+
+// The tab list drives AppShell + AppBottomNav generically (no role-hardcoded shells).
+// The scaffolder regenerates this list from the configured \`tabs\`.
+@Composable
+fun appTabs(
+${params}
+): List<AppTab> = listOf(
+${entries}
+)
+`;
+}
+
+/**
+ * Render qa/e2e/smoke.yaml (template-token form): launch, wait for the first
+ * tab's content, then for each subsequent tab tap nav_<slug> and assert its
+ * <slug>_title + the shell, then return to the first tab. Byte-identical to
+ * the static template file for the default tabs.
+ * @param {ReturnType<typeof tabInfos>} infos
+ */
+export function renderSmokeYaml(infos) {
+  const [first, ...rest] = infos;
+  const lines = [];
+  lines.push(`# E2E smoke — Maestro flow. SPEC: SHELL-01, SHELL-02.
+#
+# Proves the real app boots on a device/emulator and the bottom-nav shell works.
+# Selectors go by testTag (surfaced as resource-ids on Android via TestTagAutomation),
+# never by display text. Nav-item ids are nav_<label-slug> — the slug rule lives in
+# AppShell.kt's navItemTag (lowercase, non-[a-z0-9] runs collapsed to "_", trimmed);
+# keep these ids in sync with it if the configured tabs change.
+#
+# Run:  maestro test qa/e2e/smoke.yaml      (device/emulator attached)
+# The verify lane's e2eSmoke step runs this automatically when maestro + a device are present.
+appId: __PACKAGE__
+---
+- launchApp:
+    clearState: true
+
+# SPEC: SHELL-01 — the app boots and the first tab renders inside the shell, bottom nav visible.
+# Cold-start after clearState can take longer than a bare assert's default window on a slow/CI
+# emulator (first Compose frame under load). Waiting for the first frame IS the SHELL-01 boot
+# proof, so wait explicitly with a generous budget rather than asserting immediately.
+- extendedWaitUntil:
+    visible:
+      id: "${first.slug}_title"
+    timeout: 60000
+- assertVisible:
+    id: "app_bottom_nav"`);
+
+  rest.forEach((tab, i) => {
+    lines.push("");
+    if (i === 0) lines.push("# SPEC: SHELL-02 — switching tabs keeps the shell");
+    lines.push(`- tapOn:
+    id: "nav_${tab.slug}"
+- assertVisible:
+    id: "${tab.slug}_title"
+- assertVisible:
+    id: "app_bottom_nav"`);
+  });
+
+  if (rest.length > 0) {
+    lines.push("");
+    lines.push(`# and back
+- tapOn:
+    id: "nav_${first.slug}"
+- assertVisible:
+    id: "${first.slug}_title"`);
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+/** Call-site content lambda for one tab in AppNavHost's appTabs(...) call. */
+function navHostTabArg(tab) {
+  if (tab.slug === "home") {
+    return `                ${tab.param} = {
+                    HomeScreen(
+                        onItemClick = { itemId -> navController.navigate(Routes.detail(itemId)) },
+                    )
+                },`;
+  }
+  if (tab.slug === "profile") {
+    return `                ${tab.param} = { ProfileScreen() },`;
+  }
+  return `                ${tab.param} = { PlaceholderScreen(title = "${kotlinString(tab.label)}", titleTag = "${tab.slug}_title") },`;
+}
+
+// The exact template blocks AppNavHost rewriting anchors on. If the template
+// drifts, rewriteNavHost throws instead of silently shipping stale wiring.
+const NAVHOST_IMPORTS_ANCHOR = `import __PACKAGE__.presentation.home.HomeScreen
+import __PACKAGE__.presentation.profile.ProfileScreen`;
+const NAVHOST_TABS_OPEN = "            val tabs = appTabs(\n";
+const NAVHOST_TABS_CLOSE = "\n            )\n";
+
+/**
+ * Rewrite AppNavHost.kt content: the screen imports and the appTabs(...) call
+ * site, one argument per configured tab. Home/Profile slugs wire the shipped
+ * feature screens; anything else wires a PlaceholderScreen stub.
+ * @param {string} content template-token AppNavHost.kt content
+ * @param {ReturnType<typeof tabInfos>} infos
+ * @returns {string}
+ */
+export function rewriteNavHost(content, infos) {
+  if (!content.includes(NAVHOST_IMPORTS_ANCHOR)) {
+    throw new Error("AppNavHost.kt: screen-imports block not found — template drifted from the tab rewriter");
+  }
+  const start = content.indexOf(NAVHOST_TABS_OPEN);
+  const end = start === -1 ? -1 : content.indexOf(NAVHOST_TABS_CLOSE, start);
+  if (start === -1 || end === -1) {
+    throw new Error("AppNavHost.kt: `val tabs = appTabs(` block not found — template drifted from the tab rewriter");
+  }
+
+  const imports = [];
+  if (infos.some((t) => t.slug !== "home" && t.slug !== "profile")) {
+    imports.push("import __PACKAGE__.presentation.components.PlaceholderScreen");
+  }
+  if (infos.some((t) => t.slug === "home")) {
+    imports.push("import __PACKAGE__.presentation.home.HomeScreen");
+  }
+  if (infos.some((t) => t.slug === "profile")) {
+    imports.push("import __PACKAGE__.presentation.profile.ProfileScreen");
+  }
+
+  const tabsBlock =
+    NAVHOST_TABS_OPEN + infos.map(navHostTabArg).join("\n") + NAVHOST_TABS_CLOSE;
+
+  return (
+    content.slice(0, start) + tabsBlock + content.slice(end + NAVHOST_TABS_CLOSE.length)
+  ).replace(NAVHOST_IMPORTS_ANCHOR, () => imports.join("\n"));
+}
+
+/**
+ * Render the PlaceholderScreen stub (template-token form) — written only when
+ * a configured tab has no shipped feature screen, so the default scaffold's
+ * output is unchanged. Mirrors ProfileScreen's stub shape; the title testTag
+ * is what qa/e2e/smoke.yaml asserts for the tab.
+ */
+export function renderPlaceholderScreenKt() {
+  return `package __PACKAGE__.presentation.components
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.semantics.testTag
+import androidx.compose.ui.unit.dp
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__Tokens
+
+// Generated stub for a configured bottom-nav tab that has no feature yet.
+// Build the real feature with the add-feature skill (qa/scaffold-feature.mjs),
+// then swap this out in AppNavHost. The title testTag (\`<slug>_title\`) is what
+// qa/e2e/smoke.yaml asserts for this tab — keep it when you replace the stub.
+@Composable
+fun PlaceholderScreen(title: String, titleTag: String) {
+    Column(
+        modifier = Modifier
+            .fillMaxSize()
+            .padding(__THEME_PREFIX__Tokens.PaddingPage),
+        verticalArrangement = Arrangement.spacedBy(8.dp),
+        horizontalAlignment = Alignment.Start,
+    ) {
+        Text(
+            text = title,
+            style = MaterialTheme.typography.headlineMedium,
+            modifier = Modifier.semantics { testTag = titleTag },
+        )
+        Text(
+            text = "This is a generated stub tab. Wire it up like the Home feature.",
+            style = MaterialTheme.typography.bodyMedium,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+        )
+    }
+}
+`;
+}
+
+// --- pipeline entry --------------------------------------------------------------
+
+const APPTAB_REL =
+  "composeApp/src/commonMain/kotlin/com/example/app/presentation/navigation/AppTab.kt";
+const NAVHOST_REL =
+  "composeApp/src/commonMain/kotlin/com/example/app/presentation/navigation/AppNavHost.kt";
+const PLACEHOLDER_REL =
+  "composeApp/src/commonMain/kotlin/com/example/app/presentation/components/PlaceholderScreen.kt";
+const SMOKE_REL = "qa/e2e/smoke.yaml";
+
+/**
+ * Rewrite every tab-driven surface present in the copied project dir. Runs
+ * BEFORE token replacement and the package rename (files are addressed at
+ * their literal com/example/app template paths and written in token form).
+ * Surfaces missing from the tree (feature-stripped qa/e2e, synthetic test
+ * templates) are skipped; a PRESENT AppNavHost that no longer contains the
+ * expected blocks throws.
+ * @param {string} projectDir
+ * @param {Array<{label:string, icon:string}>} tabs
+ * @param {(msg:string)=>void} [log]
+ */
+export function rewriteTabSurfaces(projectDir, tabs, log = () => {}) {
+  const infos = tabInfos(tabs);
+
+  const appTabPath = path.join(projectDir, APPTAB_REL);
+  if (fs.existsSync(appTabPath)) {
+    fs.writeFileSync(appTabPath, renderAppTabsKt(infos));
+    log(`  tabs → ${APPTAB_REL}`);
+  }
+
+  const navHostPath = path.join(projectDir, NAVHOST_REL);
+  if (fs.existsSync(navHostPath)) {
+    const rewritten = rewriteNavHost(fs.readFileSync(navHostPath, "utf8"), infos);
+    fs.writeFileSync(navHostPath, rewritten);
+    log(`  tabs → ${NAVHOST_REL}`);
+  }
+
+  if (infos.some((t) => t.slug !== "home" && t.slug !== "profile")) {
+    const placeholderPath = path.join(projectDir, PLACEHOLDER_REL);
+    if (fs.existsSync(path.dirname(placeholderPath))) {
+      fs.writeFileSync(placeholderPath, renderPlaceholderScreenKt());
+      log(`  tabs → ${PLACEHOLDER_REL}`);
+    }
+  }
+
+  const smokePath = path.join(projectDir, SMOKE_REL);
+  if (fs.existsSync(smokePath)) {
+    fs.writeFileSync(smokePath, renderSmokeYaml(infos));
+    log(`  tabs → ${SMOKE_REL}`);
+  }
+}

package/src/lib/verify.mjs

@@ -66,8 +66,15 @@ export async function runVerify({ projectDir, manifest, config, dryRun = false }
       results.push({ platform: item.platform, command: item.command, code: 0, ran: false });
       continue;
     }
+    const startedAt = Date.now();
     const { code } = await runCommand(item.command, projectDir);
-    results.push({ platform: item.platform, command: item.command, code, ran: true });
+    results.push({
+      platform: item.platform,
+      command: item.command,
+      code,
+      ran: true,
+      durationMs: Date.now() - startedAt,
+    });
     if (code !== 0) green = false;
   }
 
@@ -94,4 +101,20 @@ export function printVerifyVerdict(verdict) {
       ? `\n${colors.green("GREEN — build proven.")}\n`
       : `\n${colors.red("FAIL — build did not go green.")}\n`
   );
+
+  // Machine-readable verdict, one greppable line (field-report finding 2.3):
+  // a verify run can exceed 170k log lines, where "-Werror=" clang flags and
+  // Xcode phase names false-positive naive error greps. Agents anchor on this
+  // marker instead of parsing raw Gradle/xcodebuild output.
+  process.stdout.write(
+    `::create-cmp-verdict::${JSON.stringify({
+      green: verdict.green,
+      results: verdict.results.map((r) => ({
+        platform: r.platform,
+        green: r.code === 0,
+        ran: r.ran,
+        durationMs: r.durationMs ?? null,
+      })),
+    })}\n`
+  );
 }

package/src/scaffold.mjs

@@ -3,6 +3,8 @@
 //   (b) copy template/ → targetDir
 //   (b.2) delete disabled-feature paths (MUST precede the package rename —
 //         feature paths are declared against the literal com/example/app)
+//   (b.3) regenerate tab-driven surfaces (AppTab.kt, AppNavHost wiring,
+//         qa/e2e/smoke.yaml) from config.tabs, in template-token form
 //   (c) token-replace contents AND paths
 //   (d) rename package source dirs com/example/app → __PACKAGE_PATH__ (atomic)
 //   (e) toggle features (strip cmp:feature marker blocks)
@@ -23,6 +25,7 @@ import {
   disabledFeaturesFromConfig,
   deleteDisabledFeaturePaths,
 } from "./lib/toggle.mjs";
+import { rewriteTabSurfaces } from "./lib/tabs.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";
@@ -202,6 +205,46 @@ function applyAppNameSlug(projectDir, appName) {
   }
 }
 
+/**
+ * Persist the fully-resolved engine config as `create-cmp.json` in the project
+ * root — the durable spec-of-record (field-report finding 5.5-1 / D6). The
+ * conformance/consistency tooling compares code against whatever this file
+ * currently says, so a hand-edit is a visible spec change rather than drift.
+ * @param {string} projectDir
+ * @param {object} config validated engine config
+ */
+function writeSpecOfRecord(projectDir, config) {
+  let engineVersion = "unknown";
+  try {
+    engineVersion = JSON.parse(
+      fs.readFileSync(path.join(REPO_ROOT, "package.json"), "utf8")
+    ).version;
+  } catch {
+    /* best-effort — never fail the stamp over version metadata */
+  }
+  const record = {
+    schemaVersion: 1,
+    name: config.appName,
+    package: config.package,
+    bundleId: config.iosBundleId,
+    themePrefix: config.themePrefix,
+    region: config.region,
+    platforms: config.platforms,
+    firebase: config.firebase,
+    room: config.room,
+    e2e: config.e2e,
+    inspector: config.inspector,
+    devClient: config.devClient,
+    tabs: config.tabs,
+    engineVersion,
+    stampedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(
+    path.join(projectDir, "create-cmp.json"),
+    JSON.stringify(record, null, 2) + "\n"
+  );
+}
+
 /**
  * Run the full scaffold pipeline.
  * @param {object} config engine config object (CONTRACT)
@@ -228,10 +271,20 @@ export async function scaffold(config, opts = {}) {
 
   const projectDir = path.resolve(config.targetDir);
   if (fs.existsSync(projectDir)) {
+    // Harmless entries must not force `--force`: our own doctor/session
+    // droppings (.claude), VCS metadata, and OS/editor noise. The documented
+    // doctor→create flow used to poison its own target dir this way. Anything
+    // else is real user content and still refuses — naming the offenders so
+    // the caller can decide without an `ls` round-trip.
+    const HARMLESS = new Set([".git", ".claude", ".DS_Store", ".idea", ".vscode"]);
     const entries = fs.readdirSync(projectDir).filter((e) => e !== "." && e !== "..");
-    if (entries.length > 0 && !opts.force) {
+    const blocking = entries.filter((e) => !HARMLESS.has(e) && !e.endsWith(".swp"));
+    if (blocking.length > 0 && !opts.force) {
+      const ignored = entries.filter((e) => !blocking.includes(e));
       throw new Error(
-        `target directory ${projectDir} is not empty (pass force to overwrite)`
+        `target directory ${projectDir} is not empty (pass force to overwrite)\n` +
+          `  Blocking entries: ${blocking.join(", ")}` +
+          (ignored.length > 0 ? `\n  (ignored as harmless: ${ignored.join(", ")})` : "")
       );
     }
   }
@@ -261,6 +314,14 @@ export async function scaffold(config, opts = {}) {
     );
   }
 
+  // (b.3) Regenerate the tab-driven surfaces from config.tabs BEFORE token
+  // replacement and the package rename: the rewriter addresses files at their
+  // literal com/example/app template paths and writes template-token contents,
+  // so the pipeline below stamps them like any other template file. For the
+  // default tabs this reproduces the static template files byte-for-byte.
+  step("Regenerating tab surfaces from configured tabs…");
+  rewriteTabSurfaces(projectDir, config.tabs, (m) => process.stdout.write(`${m}\n`));
+
   const tokenMap = buildTokenMap(config);
 
   // (c) token-replace contents AND paths
@@ -311,6 +372,14 @@ export async function scaffold(config, opts = {}) {
     if (fs.existsSync(abs)) fs.rmSync(abs);
   }
 
+  // Persist the resolved config as the project's spec-of-record. Until now the
+  // config was validated, consumed, and discarded — the only pre-code spec in
+  // the system evaporated at stamp time, so nothing could later answer "was
+  // this app built to its spec?" (tabs ↔ AppTab ↔ smoke consistency, upgrade
+  // intent, re-stamp/resume all need it). Committed with the app; hand-edits
+  // are visible spec changes, not drift.
+  writeSpecOfRecord(projectDir, config);
+
   ok("Scaffold complete.");
 
   // (f) verify gate

package/template/README.md

@@ -101,3 +101,7 @@ remember to run 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.
+
+---
+
+Built with [create-cmp](https://github.com/kvdm-co-pilot/create-cmp) — the AI delivery harness for Compose Multiplatform.

package/template/composeApp/build.gradle.kts

@@ -250,7 +250,19 @@ compose.resources {
 
 // >>> cmp:feature room
 room {
-    schemaDirectory("$projectDir/schemas")
+    // Per-target schema directories, NOT one shared dir. With a single directory the
+    // copyRoomSchemas aggregation task requires every target's exported schema to be
+    // byte-identical — and the first entity edit after scaffold trips a cross-target
+    // checksum conflict against the stale intermediate of whichever target built last
+    // ("Inconsistency detected exporting Room schema files"). Per-target locations are
+    // exactly what that error's remediation asks for.
+    schemaDirectory("android", "$projectDir/schemas/android")
+    schemaDirectory("desktop", "$projectDir/schemas/desktop")
+    // >>> cmp:feature ios
+    schemaDirectory("iosSimulatorArm64", "$projectDir/schemas/iosSimulatorArm64")
+    schemaDirectory("iosX64", "$projectDir/schemas/iosX64")
+    schemaDirectory("iosArm64", "$projectDir/schemas/iosArm64")
+    // <<< cmp:feature ios
 }
 // <<< cmp:feature room
 

package/template/composeApp/src/commonMain/kotlin/com/example/app/core/format/Format.kt

@@ -0,0 +1,36 @@
+package __PACKAGE__.core.format
+
+/**
+ * KMP-safe formatting helpers.
+ *
+ * `String.format` / `"%02d".format(...)` are JVM-only — they compile in `androidMain` but do
+ * not exist in `commonMain`, and reaching for them is the single most common first-week
+ * porting mistake in a shared module. These cover the cases that actually come up; add here
+ * rather than sprinkling `padStart` call sites.
+ */
+
+/** Pad an Int to two digits: 7 -> "07". The `%02d` you were about to write. */
+fun pad2(n: Int): String = n.toString().padStart(2, '0')
+
+/** "HH:mm" from minutes-since-midnight: 555 -> "09:15". */
+fun clockLabel(minutesOfDay: Int): String {
+    val m = ((minutesOfDay % (24 * 60)) + 24 * 60) % (24 * 60) // wrap + never negative
+    return "${pad2(m / 60)}:${pad2(m % 60)}"
+}
+
+/**
+ * Fixed decimal places without java.text: 12.5 -> "12.5" (1 dp). Rounds half away from zero
+ * via floor(abs + 0.5) — deterministic on every backend (kotlin.math.round's tie behavior and
+ * `%.Nf` locale handling both vary). For layout-stable numeric UI text, not accounting math.
+ */
+fun fixed(value: Double, decimals: Int = 1): String {
+    require(decimals >= 0) { "decimals must be >= 0" }
+    var factor = 1L
+    repeat(decimals) { factor *= 10 }
+    val scaled = kotlin.math.floor(kotlin.math.abs(value) * factor + 0.5).toLong()
+    val sign = if (value < 0 && scaled != 0L) "-" else ""
+    if (decimals == 0) return "$sign$scaled"
+    val whole = scaled / factor
+    val frac = (scaled % factor).toString().padStart(decimals, '0')
+    return "$sign$whole.$frac"
+}

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

@@ -114,7 +114,7 @@ private fun AppBottomNav(
     }
 }
 
-/** Deterministic automation tag for a nav item: `nav_` + the label lowercased with every non-[a-z0-9] run collapsed to `_` and trimmed (e.g. "My Stuff!" → `nav_my_stuff`). Mirrored by the id selectors in `qa/e2e/smoke.yaml` — keep the two in sync. */
+/** Deterministic automation tag for a nav item: `nav_` + the label lowercased with every non-[a-z0-9] run collapsed to `_` and trimmed (e.g. "My Stuff!" → `nav_my_stuff`). Must mirror `navSlug` in create-cmp's engine (src/lib/tabs.mjs), which generates `qa/e2e/smoke.yaml`'s id selectors from the configured tabs — keep the two in sync. */
 private fun navItemTag(label: String): String =
     "nav_" + label.lowercase().replace(Regex("[^a-z0-9]+"), "_").trim('_')
 

package/template/composeApp/src/commonTest/kotlin/com/example/app/core/format/FormatTest.kt

@@ -0,0 +1,36 @@
+package __PACKAGE__.core.format
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class FormatTest {
+
+    @Test
+    fun pad2_pads_single_digits() {
+        assertEquals("07", pad2(7))
+        assertEquals("00", pad2(0))
+        assertEquals("15", pad2(15))
+    }
+
+    @Test
+    fun clockLabel_formats_minutes_of_day() {
+        assertEquals("09:15", clockLabel(9 * 60 + 15))
+        assertEquals("00:00", clockLabel(0))
+        assertEquals("23:59", clockLabel(23 * 60 + 59))
+        // wraps past midnight and never goes negative
+        assertEquals("00:30", clockLabel(24 * 60 + 30))
+        assertEquals("23:30", clockLabel(-30))
+    }
+
+    @Test
+    fun fixed_renders_stable_decimals() {
+        // Binary-exact inputs only — 0.1-style values are not representable and would make
+        // these assertions depend on the platform's double formatting.
+        assertEquals("12.5", fixed(12.5, 1))
+        assertEquals("0.3", fixed(0.25, 1)) // half rounds away from zero
+        assertEquals("-0.8", fixed(-0.75, 1))
+        assertEquals("3.00", fixed(3.0, 2))
+        assertEquals("13", fixed(12.5, 0))
+        assertEquals("0.0", fixed(0.0, 1))
+    }
+}

package/template/composeApp/src/desktopTest/kotlin/com/example/app/conformance/ArchitectureConformanceTest.kt

@@ -27,22 +27,47 @@ class ArchitectureConformanceTest {
     private fun imports(file: File): List<String> =
         file.readLines().filter { it.trimStart().startsWith("import ") }.map { it.trim() }
 
+    /**
+     * Source lines with comment lines stripped. Layer-boundary rules scan these for BOTH
+     * `import x.y.` statements AND fully-qualified inline references (`x.y.Type(...)`) —
+     * import-only matching leaves a one-edit evasion open: delete the import, qualify the
+     * name inline, and the gate goes green while the violation remains.
+     */
+    private fun nonCommentLines(file: File): List<String> =
+        file.readLines().filterNot {
+            val t = it.trimStart()
+            t.startsWith("//") || t.startsWith("*") || t.startsWith("/*")
+        }
+
+    private fun bannedReference(file: File, banned: List<String>): Boolean =
+        nonCommentLines(file).any { line -> banned.any { line.contains(it) } }
+
     private fun under(file: File, segment: String): Boolean =
         file.path.replace(File.separatorChar, '/').contains("/$segment/")
 
+    /**
+     * True when the file sits in a feature subpackage (presentation/<feature>/…) rather than
+     * at the presentation root (App.kt) — the scope for the composable-file rules.
+     */
+    private fun inPresentationFeatureDir(file: File): Boolean {
+        val rel = file.path.replace(File.separatorChar, '/').substringAfter("/presentation/", "")
+        return rel.isNotEmpty() && rel.contains('/')
+    }
+
     private fun violation(clause: String, rule: String, offenders: List<String>, fix: String): String =
         "[$clause] $rule\n  Offending: ${offenders.joinToString("\n             ")}\n  Fix: $fix"
 
     // SPEC: ARCH-01
     @Test
-    fun `ARCH-01 presentation never imports the data layer`() {
+    fun `ARCH-01 presentation never references the data layer`() {
         val offenders = sources(commonMain)
             .filter { under(it, "presentation") }
-            .filter { file -> imports(file).any { it.startsWith("import __PACKAGE__.data.") } }
+            .filter { bannedReference(it, listOf("__PACKAGE__.data.")) }
             .map { it.path }
         if (offenders.isNotEmpty()) fail(
             violation(
-                "ARCH-01", "presentation depends on domain only — it never imports the data layer.",
+                "ARCH-01", "presentation depends on domain only — it never references the data layer " +
+                    "(neither imports nor fully-qualified inline names).",
                 offenders,
                 "depend on a domain interface (domain/repository) and let di/ wire the data implementation.",
             )
@@ -53,16 +78,17 @@ class ArchitectureConformanceTest {
     @Test
     fun `ARCH-02 domain is pure - no app layers, no frameworks`() {
         val banned = listOf(
-            "import __PACKAGE__.presentation.", "import __PACKAGE__.data.", "import __PACKAGE__.di.",
-            "import androidx.compose.", "import org.koin.",
+            "__PACKAGE__.presentation.", "__PACKAGE__.data.", "__PACKAGE__.di.",
+            "androidx.compose.", "org.koin.",
         )
         val offenders = sources(commonMain)
             .filter { under(it, "domain") }
-            .filter { file -> imports(file).any { imp -> banned.any { imp.startsWith(it) } } }
+            .filter { bannedReference(it, banned) }
             .map { it.path }
         if (offenders.isNotEmpty()) fail(
             violation(
-                "ARCH-02", "domain imports nothing app-internal and no UI/DI frameworks.",
+                "ARCH-02", "domain references nothing app-internal and no UI/DI frameworks " +
+                    "(neither imports nor fully-qualified inline names).",
                 offenders,
                 "move framework-touching code out to presentation/data; domain stays pure Kotlin.",
             )
@@ -88,17 +114,23 @@ class ArchitectureConformanceTest {
 
     // SPEC: ARCH-04
     @Test
-    fun `ARCH-04 every Screen composable declares a testTag`() {
+    fun `ARCH-04 every feature composable file declares a testTag`() {
+        // Scoped by CONTENT (contains @Composable), not by *Screen.kt filename: real apps
+        // split features into Screen.kt (often ViewModel-only) and Content.kt (the UI).
+        // Filename scoping produced both false negatives (untagged FooContent.kt slid
+        // through) and false positives (VM-only FooScreen.kt was flagged) in the field.
         val offenders = sources(commonMain)
-            .filter { it.name != "Screen.kt" && it.name.endsWith("Screen.kt") }
-            .filterNot { under(it, "components") || under(it, "navigation") }
+            .filter { inPresentationFeatureDir(it) }
+            .filterNot { under(it, "components") || under(it, "navigation") || under(it, "theme") }
+            .filter { it.readText().contains("@Composable") }
             .filterNot { it.readText().contains("testTag") }
             .map { it.path }
         if (offenders.isNotEmpty()) fail(
             violation(
-                "ARCH-04", "every screen is automation-reachable: *Screen files declare at least one testTag.",
+                "ARCH-04", "every feature UI file is automation-reachable: files containing a " +
+                    "@Composable declare at least one testTag.",
                 offenders,
-                "add Modifier.semantics { testTag = \"<feature>_<element>\" } to the screen's key nodes.",
+                "add Modifier.semantics { testTag = \"<feature>_<element>\" } to the file's key nodes.",
             )
         )
     }
@@ -120,6 +152,45 @@ class ArchitectureConformanceTest {
         )
     }
 
+    // SPEC: SHELL-05
+    @Test
+    fun `SHELL-05 every non-shell nav destination wraps its content in BaseScreen`() {
+        // SHELL-03 bans direct inset-API calls, but a destination that simply never handles
+        // insets at all (bare Column at the nav layer) passes that rule while rendering
+        // under the status bar. Tab screens are exempt — AppShell wraps them — so the rule
+        // targets exactly the destinations registered directly on the NavHost.
+        val navHost = sources(commonMain).firstOrNull { it.name == "AppNavHost.kt" } ?: return
+        val text = navHost.readText()
+        val screenCall = Regex("""([A-Z][A-Za-z0-9]*Screen)\s*\(""")
+        // A call with only a trailing lambda has no paren — `BaseScreen { … }` — so match both.
+        val baseScreenCall = Regex("""BaseScreen\s*[({]""")
+        val allSources = sources(commonMain)
+
+        val offenders = mutableListOf<String>()
+        val chunks = text.split("composable(").drop(1)
+        for (chunk in chunks) {
+            if (chunk.contains("AppShell(")) continue // shell destination: tabs inherit BaseScreen
+            for (m in screenCall.findAll(chunk)) {
+                val name = m.groupValues[1]
+                if (name == "BaseScreen") continue
+                val defining = allSources.firstOrNull { f ->
+                    Regex("""fun\s+$name\s*\(""").containsMatchIn(f.readText())
+                } ?: continue
+                if (!baseScreenCall.containsMatchIn(defining.readText())) {
+                    offenders.add("${defining.path} ($name is a NavHost destination without BaseScreen)")
+                }
+            }
+        }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "SHELL-05", "every screen registered directly on the NavHost composes inside " +
+                    "BaseScreen — otherwise it renders edge-to-edge with no inset handling.",
+                offenders.distinct(),
+                "wrap the destination's content in BaseScreen { … } (see DetailScreen).",
+            )
+        )
+    }
+
     // SPEC: SHELL-03
     @Test
     fun `SHELL-03 insets are owned by BaseScreen - screens never touch inset APIs`() {

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

@@ -5,15 +5,19 @@
 
 ## Architecture invariants
 
-- **ARCH-01** — Given any file in `presentation`, When its imports are inspected, Then none
-  resolve into the `data` layer (presentation depends on domain only).
-- **ARCH-02** — Given any file in `domain`, When its imports are inspected, Then none resolve
-  into `presentation`, `data`, or `di`, and none import Compose, Koin, or platform types
-  (domain is pure Kotlin).
+- **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).
+- **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).
 - **ARCH-03** — Given any ViewModel class, When the test sources are inspected, Then a
   corresponding `*ViewModelTest` exists (no untested presentation state).
-- **ARCH-04** — Given any file containing a `*Screen` composable, When its source is
-  inspected, Then it declares at least one `testTag` (every screen is automation-reachable).
+- **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).
 - **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).
@@ -28,3 +32,7 @@
   the safe-area insets owned by `BaseScreen` (edge-to-edge without overlap).
 - **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.