create-cmp-cli 0.24.0 → 0.25.0

package/template/qa/lib/profiles/cmp/artifacts.mjs

@@ -0,0 +1,381 @@
+// profiles/cmp/artifacts.mjs — what a human SIGNS in a Compose Multiplatform
+// app, in definition order, and how each artifact resolves to files on disk.
+// Mobile's governance model, by definition (docs/NORTH-STAR.md §5, §6;
+// AGNOSTIC-HARNESS-ARCHITECTURE.md §4.2 #2).
+//
+// Stage 0 PR 5. Until this file, qa/lib/approvals.mjs hardcoded the six
+// genesis artifacts — intent, architecture, exemplar-spec, exemplar-feature,
+// design-system, components — with their Kotlin source-set roots, the
+// composeApp namespace lookup, the exemplar's eleven-file shape and the
+// presentation/<name>/*Screen.kt design surface. A Kotlin backend that adopted
+// the harness replaced the whole file (1,636 lines) to change that list. The
+// MECHANIC — artifact = path set + hash, signature on the hash, status
+// derivation, reopen/accept, the ledger, the gate — is the core's and never
+// moved. THIS is the model: which artifacts, in what order, how each is
+// hashed. The core reads it through the profile the manifest names.
+//
+// The neutral entries — feature briefs (the Decide layer), feature designs
+// (one per brief with a surface) and feature specs — are built by the core's
+// own helpers, so every profile that has briefs gets the same walk; this
+// profile only says what a design SURFACE is here (screens on disk) and which
+// spec files are not feature specs (the base spec, the exemplar's).
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { ARCH_DOC_REL_PATH } from "../../arch-doc.mjs";
+import {
+  architectureArtifact,
+  featureBriefArtifacts,
+  featureDesignArtifacts,
+  featureSpecArtifacts,
+  loadApprovals,
+} from "../../approvals.mjs";
+
+// Kotlin source-set roots, relative to project root — mirrors qa/scaffold-feature.mjs's
+// SRC() helper (composeApp/src/<sourceSet>/kotlin/<packageDir>).
+const KOTLIN_SOURCE_SETS = {
+  commonMain: "composeApp/src/commonMain/kotlin",
+  commonTest: "composeApp/src/commonTest/kotlin",
+  desktopTest: "composeApp/src/desktopTest/kotlin",
+};
+
+// The canonical 11-file EXEMPLAR SHAPE (10 kotlin files + 1 spec), parametrized by
+// the exemplar's own names — F (PascalCase feature, e.g. "Home"), f (lowercase
+// package segment, e.g. "home"), E (PascalCase entity, e.g. "Item"). This is the
+// SAME shape qa/scaffold-feature.mjs's ALL_FILES clones FROM (GENESIS-FLOW-DESIGN.md
+// §1's "configurable exemplar") — the stamper imports this exact function so the
+// clone-source list and the governed-artifact list can never drift from each other
+// (single source of truth, not a parallel copy to keep in sync by hand).
+// @param {string} F PascalCase feature name (e.g. "Home", "Favorites")
+// @param {string} f lowercase package-segment name (e.g. "home", "favorites")
+// @param {string} E PascalCase entity name (e.g. "Item", "Favorite")
+// @returns {Array<{sourceSet: string, rel: string}>}
+export function exemplarKotlinFileSet(F, f, E) {
+  return [
+    { sourceSet: "commonMain", rel: `domain/model/${E}.kt` },
+    { sourceSet: "commonMain", rel: `domain/repository/${E}Repository.kt` },
+    { sourceSet: "commonMain", rel: `domain/usecase/Get${E}sUseCase.kt` },
+    { sourceSet: "commonMain", rel: `data/remote/${E}RepositoryImpl.kt` },
+    { sourceSet: "commonTest", rel: `testing/fakes/Fake${E}Repository.kt` },
+    { sourceSet: "commonMain", rel: `presentation/${f}/${F}Screen.kt` },
+    { sourceSet: "commonMain", rel: `presentation/${f}/${F}ViewModel.kt` },
+    { sourceSet: "commonTest", rel: `presentation/${f}/${F}ViewModelTest.kt` },
+    { sourceSet: "desktopTest", rel: `presentation/${f}/${F}ScreenTest.kt` },
+    { sourceSet: "desktopTest", rel: `presentation/${f}/${F}GoldenTreeTest.kt` },
+  ];
+}
+
+// Naive de-pluralization, shared verbatim with qa/scaffold-feature.mjs's own
+// entity-name default (a feature stamped without `--entity` gets this exact
+// guess). Exported so both the stamper (deriving a NEW feature's entity) and this
+// registry (guessing a CONFIGURED exemplar's entity from its feature name alone —
+// see resolveExemplarNames) apply the identical heuristic. Unreliable for
+// irregular nouns by design (the skill surfaces the guess for human override at
+// stamp time); a wrong guess here simply fails to resolve files, which is refused
+// (never fabricated), not silently wrong.
+export function defaultEntityName(feature) {
+  if (feature.endsWith("ies") && feature.length > 3) return `${feature.slice(0, -3)}y`;
+  if (feature.endsWith("s") && !feature.endsWith("ss")) return feature.slice(0, -1);
+  return feature;
+}
+
+function toPascalCase(f) {
+  return f.charAt(0).toUpperCase() + f.slice(1);
+}
+
+function toUpperSnake(F) {
+  return F.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase();
+}
+
+/**
+ * The configured exemplar feature's lowercase name (the package-segment form,
+ * e.g. `"home"`, `"favorites"`) — `qa/approvals.json`'s top-level
+ * `exemplarFeature` key, defaulting to `"home"` when absent (GENESIS-FLOW-DESIGN.md
+ * §1). This is the ONE function both `resolveExemplarNames` (registry) and
+ * qa/scaffold-feature.mjs (clone-source resolution) call — never read the raw key
+ * directly, so the default lives in exactly one place.
+ * @param {string} root
+ * @returns {string}
+ */
+export function getExemplarFeature(root) {
+  return loadApprovals(root).exemplarFeature ?? "home";
+}
+
+/**
+ * Resolve the CONFIGURED exemplar's names — the ones the exemplar-feature/
+ * exemplar-spec governed artifacts (and qa/scaffold-feature.mjs's clone source)
+ * are built from.
+ *
+ * `home` (the default, and the only exemplar that predates configurability) is a
+ * hardcoded exception: its entity is `Item`, not derivable from `Home` by
+ * `defaultEntityName` (which would naively guess `Home`). Every OTHER exemplar is
+ * itself a feature that was stamped by qa/scaffold-feature.mjs, so its entity
+ * followed defaultEntityName(F) UNLESS it was stamped with an explicit `--entity`
+ * override — a choice this config key cannot see. In that mismatch case the guess
+ * is wrong and the file set simply fails to resolve (0 or partial files), which
+ * `resolveArtifactStatus`/`approveArtifact` already refuse rather than fabricate —
+ * the correct failure mode, not a special case to add here.
+ * @param {string} root
+ * @returns {{f: string, F: string, F_UPPER: string, E: string}}
+ */
+export function resolveExemplarNames(root) {
+  const f = getExemplarFeature(root);
+  const F = toPascalCase(f);
+  const F_UPPER = toUpperSnake(F);
+  const E = f === "home" ? "Item" : defaultEntityName(F);
+  return { f, F, F_UPPER, E };
+}
+
+// Backward-compatible constants for the DEFAULT (`home`) exemplar — kept exported
+// because they describe the shipped template's own exemplar shape independent of
+// any project's configuration, and because they're the fixture the "stamping from
+// home must be byte-identical" pin (test/genesis-flow.test.mjs) anchors to.
+export const EXEMPLAR_FEATURE_KOTLIN_FILES = exemplarKotlinFileSet("Home", "home", "Item");
+export const EXEMPLAR_SPEC_REL = "specs/home.spec.md";
+export const ARCHITECTURE_SPEC_REL = "specs/app-base.spec.md";
+export const INTENT_REL = "specs/intent.md";
+
+// ── Package resolution ───────────────────────────────────────────────────────
+// Mirrors qa/scaffold-feature.mjs's resolvePackage() primary path (the
+// composeApp/build.gradle.kts namespace). Unlike the stamper, this NEVER dies —
+// an unresolved package means the kotlin-rooted artifacts resolve to zero files.
+// Zero resolution never CRASHES anything (the lane and the stamper stay up),
+// but it is NOT benign for decisions: an approval over zero files would be the
+// empty-input sha256 attesting nothing — a silent vacuous PASS, the exact
+// failure mode this harness exists to kill (evidence must attest execution).
+// So: approveArtifact REFUSES zero-file artifacts, and an already-approved
+// artifact whose files stop resolving goes to changed-since-approval (FAIL),
+// never PASS.
+//
+// IMPORTANT: detect "unresolved" by TOKEN SHAPE (`/^__[A-Z_]+__$/`), never by
+// comparing against the literal string "__PACKAGE__". This file ships through
+// the SAME scaffold pipeline that resolves that token — a literal comparison
+// string is itself blindly text-substituted at stamp time (`replaceContents`
+// does a global `"__PACKAGE__" -> config.package` replace over every template
+// file's content, this one included), which would silently rewrite the
+// sentinel into the real package and make the check always fail. A shape
+// regex never spells the token out, so the pipeline has nothing to match.
+const UNRESOLVED_TOKEN_RE = /^__[A-Z_]+__$/;
+
+function resolvePackageDir(root) {
+  const gradleFile = path.join(root, "composeApp", "build.gradle.kts");
+  if (!fs.existsSync(gradleFile)) return null;
+  let contents;
+  try {
+    contents = fs.readFileSync(gradleFile, "utf8");
+  } catch {
+    return null;
+  }
+  const m = contents.match(/namespace\s*=\s*"([^"]+)"/);
+  if (!m || UNRESOLVED_TOKEN_RE.test(m[1])) return null;
+  return m[1].split(".").join("/");
+}
+
+function kotlinFile(root, sourceSet, rel) {
+  const packageDir = resolvePackageDir(root);
+  if (!packageDir) return null;
+  return path.posix.join(KOTLIN_SOURCE_SETS[sourceSet], packageDir, rel);
+}
+
+/**
+ * Is the project's package resolvable at all? False in the raw template (the
+ * namespace is still a placeholder token) and in any pre-stamp tree — the tell
+ * that this is not a generated project. The approve CLI refuses to WRITE
+ * approvals in such a tree (recording decisions against a template pollutes
+ * the template itself); read-only status remains available.
+ * @param {string} root
+ * @returns {boolean}
+ */
+export function isPackageResolvable(root) {
+  return resolvePackageDir(root) !== null;
+}
+
+/**
+ * The profile's answer to "may approvals be RECORDED in this tree?" — the
+ * core's `isProjectGovernable` asks every profile this and refuses to write
+ * a ledger where the answer is no.
+ * @param {string} root
+ * @returns {{ok: true} | {ok: false, reason: string}}
+ */
+export function governable(root) {
+  if (isPackageResolvable(root)) return { ok: true };
+  return {
+    ok: false,
+    reason:
+      "this tree's package is not resolvable (composeApp/build.gradle.kts namespace is missing or still a placeholder) — " +
+      "this looks like the raw template or a pre-stamp tree. Approvals are recorded in a generated project; refusing to write qa/approvals.json here.",
+  };
+}
+
+// ── Components glob ─────────────────────────────────────────────────────────
+
+/**
+ * Sorted list of `presentation/components/*.kt` files under the resolved
+ * package, non-recursive (GENESIS-FLOW-DESIGN.md §1's `components` artifact — the
+ * component vocabulary conversation 3 approves). Package-unresolvable or a
+ * missing/empty directory both yield `[]` — resolveArtifactStatus/approveArtifact
+ * already treat a 0-file artifact as unresolvable ("a components glob matching
+ * zero files is unresolvable, not approvable-empty" — §1), so no special-casing
+ * is needed here beyond returning the honest (possibly empty) list.
+ * @param {string} root
+ * @returns {string[]} root-relative paths, sorted
+ */
+function listComponentFiles(root) {
+  const dirRel = kotlinFile(root, "commonMain", "presentation/components");
+  if (!dirRel) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(path.join(root, dirRel), { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && e.name.endsWith(".kt"))
+    .map((e) => path.posix.join(dirRel, e.name))
+    .sort((a, b) => a.localeCompare(b));
+}
+
+// ── Feature screens glob ────────────────────────────────────────────────────
+
+/**
+ * The screen files of one feature — `presentation/<name>/**\/*Screen.kt`,
+ * recursive, sorted. DELIBERATELY only `*Screen.kt`: the design signature
+ * covers the FORM (what renders), so binding the whole presentation dir would
+ * make every ViewModel edit during a legitimate build read as design drift.
+ * This is what a DESIGN SURFACE is on mobile — the core's feature-design
+ * mechanic asks the profile for it and knows nothing else.
+ * @param {string} root
+ * @param {string} name the feature name (presentation/<name>/)
+ * @returns {string[]} repo-relative posix paths
+ */
+export function listFeatureScreenFiles(root, name) {
+  const dirRel = kotlinFile(root, "commonMain", `presentation/${name}`);
+  if (!dirRel) return [];
+  const out = [];
+  const walk = (rel) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(path.join(root, rel), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const childRel = path.posix.join(rel, e.name);
+      if (e.isDirectory()) walk(childRel);
+      else if (e.isFile() && e.name.endsWith("Screen.kt")) out.push(childRel);
+    }
+  };
+  walk(dirRel);
+  return out.sort((a, b) => a.localeCompare(b));
+}
+
+// ── The registry ────────────────────────────────────────────────────────────
+
+/**
+ * The governed-artifact registry, resolved against the project at `root` right
+ * now. GENESIS-FLOW-DESIGN.md §1 definition order — two ordering principles,
+ * one per artifact kind (the dogfooding-run correction):
+ *   BEHAVIORAL artifacts are SPEC-FIRST — the exemplar's clauses are proposed
+ *   and human-confirmed BEFORE the slice is built (exemplar-spec precedes
+ *   exemplar-feature, matching add-feature's discipline).
+ *   VISUAL artifacts are UI-FIRST — the design system and component vocabulary
+ *   are distilled FROM the real screens, so they lock AFTER the exemplar
+ *   exists (a provisional palette carries the build until then).
+ * Order: intent(0), then feature-brief:<name> per docs/features/*.md — the
+ * DECIDE layer sits directly after intent (a brief speaks intent's
+ * vocabulary; only the SPEC needs architecture's) — then architecture,
+ * exemplar-spec, exemplar-feature, design-system, components, one
+ * feature-design:<name> per brief with a screen surface, and one
+ * feature-spec:<name> per non-base, non-CONFIGURED-exemplar spec present.
+ *
+ * `complete: false` marks an artifact whose kotlin-rooted files could NOT be
+ * resolved (unresolvable package — raw template / pre-stamp tree). Such an
+ * artifact's `files` list is empty or partial (spec files only), so hashing it
+ * would attest nothing (or only a fraction) of what the artifact governs —
+ * approveArtifact refuses it, and the status surfaces treat it as unresolvable.
+ * @param {string} root absolute path to the project root
+ * @returns {Array<{id: string, label: string, files: string[], complete: boolean, hash?: (root: string) => {hash: string, fileCount: number, missing: string[]}}>}
+ */
+export function artifacts(root) {
+  const out = [];
+  const packageResolved = resolvePackageDir(root) !== null;
+  // Why a kotlin-rooted artifact is incomplete, quoted by the core's refusal.
+  const incompleteReason = packageResolved
+    ? undefined
+    : "the kotlin-rooted files are unresolvable because the project package is not resolvable from composeApp/build.gradle.kts (likely the raw template or a pre-stamp tree — run this in a generated project)";
+
+  out.push({
+    id: "intent",
+    label: `Intent brief (${INTENT_REL})`,
+    files: [INTENT_REL],
+    complete: true,
+  });
+
+  // The decide layer, directly after intent — the core's helper, so every
+  // profile with briefs walks them the same way.
+  out.push(...featureBriefArtifacts(root));
+
+  // Hashed via the core's architecture hasher (spec bytes + the doc with its
+  // generated sections stripped), NOT raw files — `files` is still the
+  // artifact's expected-files surface (missing-file refusals, "what governs
+  // this" bookkeeping), just not what gets hashed raw.
+  out.push(architectureArtifact(root, { specRel: ARCHITECTURE_SPEC_REL, docRel: ARCH_DOC_REL_PATH }));
+
+  const { f: exemplarF, F: exemplarF_Pascal, E: exemplarE } = resolveExemplarNames(root);
+  const exemplarSpecRel = `specs/${exemplarF}.spec.md`;
+  const exemplarKotlinFiles = exemplarKotlinFileSet(exemplarF_Pascal, exemplarF, exemplarE);
+
+  // Spec-first: the exemplar's behavior clauses are confirmed BEFORE the slice
+  // is built — the definition order is the discipline, not just a display order.
+  out.push({
+    id: "exemplar-spec",
+    label: `Exemplar spec (${exemplarSpecRel})`,
+    files: [exemplarSpecRel],
+    complete: true,
+  });
+
+  out.push({
+    id: "exemplar-feature",
+    label: `Exemplar feature (${exemplarF} — the file set the stamper clones)`,
+    files: [...exemplarKotlinFiles.map((f) => kotlinFile(root, f.sourceSet, f.rel)).filter(Boolean), exemplarSpecRel],
+    complete: packageResolved,
+    incompleteReason,
+  });
+
+  // UI-first: the design system LOCKS on the real exemplar (candidates render on
+  // real screens, never stubs), and the component vocabulary is DISTILLED from
+  // those screens — both follow the exemplar in the definition order.
+  out.push({
+    id: "design-system",
+    label: "Design system (presentation/theme/Theme.kt, Tokens.kt)",
+    files: [kotlinFile(root, "commonMain", "presentation/theme/Theme.kt"), kotlinFile(root, "commonMain", "presentation/theme/Tokens.kt")].filter(Boolean),
+    complete: packageResolved,
+    incompleteReason,
+  });
+
+  out.push({
+    id: "components",
+    label: "Components (presentation/components/*.kt)",
+    files: listComponentFiles(root),
+    complete: packageResolved,
+    incompleteReason,
+  });
+
+  // Feature designs — the core's mechanic (one per brief with a surface,
+  // signed on rendered output BEFORE the behaviour contract); this profile
+  // says what the surface is: `"screens": true` declared, or *Screen.kt on disk.
+  out.push(
+    ...featureDesignArtifacts(root, {
+      surfaceFiles: (r, name) => listFeatureScreenFiles(r, name),
+      declares: (block) => block.screens === true,
+      label: (name) => `Feature design (${name} — presentation/${name}/*Screen.kt, signed on rendered output)`,
+      complete: (files) => packageResolved && files.length > 0,
+      incompleteReason: (files) => (packageResolved ? (files.length === 0 ? "no *Screen.kt rendered yet for this feature" : undefined) : incompleteReason),
+    }),
+  );
+
+  out.push(...featureSpecArtifacts(root, { specsDir: "specs", exclude: ["app-base.spec.md", `${exemplarF}.spec.md`] }));
+
+  return out;
+}

package/template/qa/lib/{component-stories.mjs → profiles/cmp/component-stories.mjs}

@@ -1,5 +1,8 @@
-// component-stories.mjs — the component ↔ story parity gate (the IMP-1
-// screen↔registry parity idea, applied at component granularity).
+// profiles/cmp/component-stories.mjs — the component ↔ story parity gate (the
+// IMP-1 screen↔registry parity idea, applied at component granularity).
+// Mobile's, by definition: a @Composable and a preview-registry story are
+// Compose facts, and this file names composeApp source paths throughout.
+// Stage 0 PR 6b.2 moved it out of the spine (docs/NORTH-STAR.md §6).
 //
 // Every `@Composable fun` in `composeApp/src/commonMain/**/presentation/
 // components/*.kt` must have a preview-registry story whose id is

package/template/qa/lib/profiles/cmp/console-copy.mjs

@@ -0,0 +1,29 @@
+// THE CONSOLE'S COMPOSE-SPECIFIC COPY, OWNED BY THE PROFILE THAT KNOWS IT.
+//
+// PATTERN: contribution points (VS Code `contributes.viewsWelcome`, Backstage
+// plugins, Grafana panels): the shell renders neutral section types; the
+// provider supplies rows AND the words around them. WHY IT WORKS: the shell
+// stops naming Tokens.kt or @Composable, so a Python profile's console does not
+// tell its user to edit a Kotlin file. HOW IT FAILS: a provider forgets a key
+// and the shell shows a neutral placeholder where the adopter expected help —
+// or the shell grows a new string nobody routes through `copy`. WHAT WE DO:
+// every key has a neutral default in the shell, the widened agnostic lint now
+// scans console/ for language-shaped strings, and this file is the one place
+// a Compose word may live on the console path.
+//
+// SINGLE SOURCE OF TRUTH: packages/harness/src/lib/profiles/cmp/console-copy.mjs.
+export const copy = Object.freeze({
+  usesIn: "commonMain",
+  tokensEditHint: "Edit <code>Tokens.kt</code>, let the preview re-render, then stash the result with the",
+  componentsEmpty: "no @Composable components found in presentation/components/*.kt",
+  versionSetFile: "gradle/libs.versions.toml",
+  versionSetUnreadable: "gradle/libs.versions.toml not readable",
+  kspPairLabel: "KSP is <code>&lt;kotlin&gt;-&lt;ksp&gt;</code>",
+  kspPrefixWarning: "is not prefixed by Kotlin",
+  previewRegistryFile: "inspector/PreviewRegistry.kt",
+  noRenderableApp: "no Compose app",
+  kspName: "KSP",
+  kspCarriesLabel: "carries Kotlin",
+  kspCarriesNote: " — Room's KMP native compilation breaks on this.",
+  depGraphGatesNote: "The Kotlin conformance gates (and the receipt they write, below) are authoritative.",
+});

package/template/qa/lib/profiles/cmp/declarations.mjs

@@ -0,0 +1,181 @@
+// profiles/cmp/declarations.mjs — what a Compose Multiplatform app IS, to the
+// harness: where its specs, sources, tests and flows live, and which test
+// tiers can observe which kind of promise. Mobile's facts, by definition.
+//
+// Stage 0 PR 4 (docs/proposals/AGNOSTIC-HARNESS-ARCHITECTURE.md §11.3 step 4;
+// docs/NORTH-STAR.md §6). Until this file, qa/lib/spec-coverage.mjs carried
+// these as constants — `composeApp/src`, `qa/e2e`, `.kt`, the four tier names,
+// which tier satisfies `[tier: device]` — so a Kotlin backend that adopted the
+// spine had to fork the scanner to change a path. The scanner is the core's
+// (the clause grammar, the citation binding window, both-direction coverage,
+// tier-must-observe); THESE are the profile's. The core reads them through
+// qa/lib/spec-model.mjs and never names any of them.
+//
+// Two declarations of the nine (§4.2): #1 layout and #4 tiers. The rest move
+// here in the PRs that follow, one at a time.
+
+/**
+ * Layout — where the things the scanner reads live, relative to the project
+ * root, posix-separated.
+ *
+ *   specs          the directory of `*.spec.md` files
+ *   citationRoots  the trees walked for `// SPEC:` citations
+ *   sourceRoots    the trees a human edits — watched by the inner loop, counted
+ *                  as activity by the chain view
+ *   citationExts   the source files a citation may sit in
+ *   buildDir       the stack's build output directory, when it has one — the
+ *                  provider's render marker lives there (optional)
+ *   flows          flow-shaped citation files: the file IS the test, so a tag
+ *                  in one binds to the flow rather than to a declaration
+ *                  inside it. Only TOP-LEVEL files in `dir` count — the lane
+ *                  runs that directory, and a citation may only come from a
+ *                  flow that executes (2026-09-03: four nested hand-written
+ *                  flows on the showcase satisfied clauses without running).
+ */
+export const layout = Object.freeze({
+  specs: "specs",
+  citationRoots: Object.freeze(["composeApp/src", "qa/e2e"]),
+  // The trees a human edits when they work on this app — what the inner-loop
+  // watcher watches and what the chain view counts as observed activity.
+  // Narrower than citationRoots: qa/e2e is a citation source but not app source.
+  sourceRoots: Object.freeze(["composeApp/src"]),
+  citationExts: Object.freeze([".kt", ".kts"]),
+  flows: Object.freeze({ dir: "qa/e2e", exts: Object.freeze([".yaml", ".yml"]) }),
+  // Gradle's output directory for the app module — where the eyes stamp their
+  // render marker (qa/lib/lane-markers.mjs) and where KSP's single-owner
+  // incremental storage lives (steps-cmp.mjs's coexistence self-heal).
+  buildDir: "composeApp/build",
+  // Directories the inputs hash and the activity scan skip when there is no
+  // git and no .gitignore to ask. The repo's own .gitignore is the truth
+  // (git ls-files --exclude-standard, or the walk that reads the same file);
+  // this is the floor beneath it, and it is THIS stack's to declare — the core
+  // used to hardcode .gradle and .kotlin for every ecosystem.
+  ignore: Object.freeze([".gradle", ".kotlin", ".idea"]),
+});
+
+/**
+ * THE GRAMMAR — what a citation and a test declaration look like in Kotlin.
+ *
+ * PATTERN: declaration over fallback (the shape tree-sitter uses — one query
+ * file per language, named captures, nothing inferred). WHY IT WORKS: a
+ * required declaration cannot be silently wrong for the profile that forgot
+ * it; until 2026-09-08 this regex lived in the core as a FALLBACK and `cmp`
+ * itself never declared one, so any profile that omitted `grammar` was graded
+ * with Kotlin's — and nothing said so. HOW IT FAILS: an author copies another
+ * language's regex and it binds nothing, or binds the wrong lines. WHAT WE DO:
+ * the Rule 0 instrument plants `unboundCitationSource` in THIS language and
+ * watches the grammar fail to bind it by name, so a grammar that cannot see
+ * its own language is caught before it grades anything; and the coverage
+ * diagnostic prints "N markers seen, 0 bound" rather than a quiet PASS.
+ */
+export const grammar = Object.freeze({
+  // TWO citation dialects, both this profile's: Kotlin sources cite with `//`, and
+  // the Maestro YAML journeys under qa/e2e cite with `#`. Declared here — the
+  // old core fallback happened to accept both, which is how nobody noticed.
+  citationMarker: /^(?:\/\/|#)\s*SPEC:/,
+  lineComment: /^(?:\/\/|\*)/,
+  blockComment: Object.freeze({ open: "/*", close: "*/" }),
+  testDeclaration: /@Test\b|\bfun\s+`[^`]+`\s*\(/,
+  typeDeclaration: /^(?:@\w+\s+)*(?:public\s+|internal\s+|private\s+|abstract\s+|open\s+|sealed\s+|data\s+|enum\s+)*(?:class|object|interface)\s+\w+/,
+  bindingWindow: 5,
+});
+
+/**
+ * THE REPORT FORMAT the lane's runners emit, so the core parses what was
+ * declared and never assumes. PATTERN: JUnit XML as the lingua franca (pytest
+ * --junitxml, go-junit-report, cargo2junit, jest-junit, swift test
+ * --xunit-output all emit it). WHY IT WORKS: one parser, every ecosystem, and
+ * the declaration is a fact the profile author knows. HOW IT FAILS: a runner
+ * emits a dialect (no classname, nested suites) and the parser reads {} — an
+ * empty leg that looks like "no tests". WHAT WE DO: the parser refuses an
+ * undeclared or unsupported format by name instead of returning {}, and the
+ * determinism probe treats an empty outcome map as a refusal, never a pass.
+ */
+export const reports = Object.freeze({ format: "junit-xml", dir: "composeApp/build/test-results" });
+
+/**
+ * The top-level `qa/*.mjs` tools that are THIS profile's, not the spine's, and
+ * are therefore never vendored into a repo that does not run this profile.
+ *
+ * PATTERN: the contribution point — the core holds no list of stacks, and the
+ * only thing that knows a tool belongs to Compose is the Compose profile.
+ * WHY IT WORKS: the fact is declared once, where it is known, and the installer
+ * derives the set (install/portability.mjs) instead of mirroring it by hand in
+ * two packages, which is what it did until 2026-09-08. HOW IT FAILS: this
+ * profile grows a fifth tool and nobody adds it here, so a foreign repo is
+ * vendored a module that names a stack it is not. WHAT WE DO: the import
+ * closure is the check — `undeclaredProfileTools` refuses a tool whose own
+ * imports reach this profile and that is missing from this list, so the only
+ * gap this can leave is a tool that lies in strings alone.
+ *
+ * These four live at the spine's path for historical reasons; the debt is
+ * recorded in test/agnostic-lint.test.mjs, and the exit is that they move into
+ * this directory, at which point this declaration becomes redundant and goes.
+ */
+export const tools = Object.freeze([
+  "preview-gallery.mjs",
+  "refusal-demo.mjs",
+  "scaffold-feature.mjs",
+  "walkthrough.mjs",
+]);
+
+/**
+ * Does this tree belong to THIS profile? PATTERN: Cloud Native Buildpacks'
+ * `bin/detect` — each stack recognises itself from marker files and the
+ * platform holds no table. WHY IT WORKS: the profile author knows the markers;
+ * `harness init` asks every known profile and keeps no language list of its
+ * own. HOW IT FAILS: an eager detect claims a tree that is not its (any Gradle
+ * repo is not a Compose app), or two profiles claim one tree. WHAT WE DO:
+ * evidence is returned and printed, never a bare boolean; two claims refuse
+ * and ask; and the claim needs BOTH the build file and the module the stamper
+ * writes, not either.
+ */
+export function detect(root, fs) {
+  const has = (rel) => fs.existsSync(`${root}/${rel}`);
+  const evidence = [];
+  if (has("composeApp/build.gradle.kts")) evidence.push("composeApp/build.gradle.kts");
+  if (has("settings.gradle.kts") || has("settings.gradle")) evidence.push("settings.gradle(.kts)");
+  const claims = evidence.length === 2;
+  return { claims, evidence, reason: claims ? "a Compose Multiplatform app: the composeApp module and a Gradle settings file" : `not a Compose Multiplatform app (found: ${evidence.join(", ") || "neither marker"})` };
+}
+
+
+/**
+ * Evidence tiers — the source-set / harness boundaries that decide what a
+ * citing test can actually SEE. commonTest and desktopTest run on the host
+ * JVM, blind to androidMain and to every OS fact (lifecycle, alarms,
+ * notifications, permissions); androidInstrumentedTest runs in the app's
+ * process on a device; e2e flows drive the installed app.
+ *
+ *   names       every tier this profile knows, in ascending observability
+ *   hostOnly    tiers that run on the host and cannot observe the target
+ *               platform — a clause cited only from these is REPORTED
+ *   satisfying  a clause tagged `[tier: X]` must be cited from one of
+ *               satisfying[X], or specCoverage FAILS by name (MOTION-13: an
+ *               animation "plays once per process start", cited only from a
+ *               desktop test with no process lifecycle at all)
+ *   journey     the tier whose citation proves a device journey — what a UI
+ *               feature needs at least one of to be done (feature-brief)
+ *   forFile     the tier a citing file belongs to, from its path
+ */
+export const tiers = Object.freeze({
+  names: Object.freeze(["commonTest", "desktopTest", "androidInstrumentedTest", "e2e"]),
+  hostOnly: Object.freeze(["commonTest", "desktopTest"]),
+  satisfying: Object.freeze({
+    device: Object.freeze(["androidInstrumentedTest", "e2e"]),
+    e2e: Object.freeze(["e2e"]),
+  }),
+  journey: "e2e",
+  /**
+   * @param {string} rel path relative to the project root (either separator)
+   * @returns {"commonTest"|"desktopTest"|"androidInstrumentedTest"|"e2e"|"other"}
+   */
+  forFile(rel) {
+    const p = String(rel).split("\\").join("/");
+    if (p.includes("/androidInstrumentedTest/")) return "androidInstrumentedTest";
+    if (p.includes("/commonTest/")) return "commonTest";
+    if (p.includes("/desktopTest/")) return "desktopTest";
+    if (p.startsWith("qa/e2e/")) return "e2e";
+    return "other";
+  },
+});

package/{packages/harness/src/lib → template/qa/lib/profiles/cmp}/e2e-coverage.mjs

@@ -19,7 +19,17 @@
 import fs from "node:fs";
 import path from "node:path";
 import { evaluateReachability } from "./reachability.mjs";
-import { E2E_FLOW_DIR, scanCitations, scanSpecClauses } from "./spec-coverage.mjs";
+import { scanCitations, scanSpecClauses } from "../../spec-coverage.mjs";
+import { specModelFrom } from "../../spec-model.mjs";
+import { layout as cmpLayout, tiers as cmpTiers, grammar as cmpGrammar } from "./declarations.mjs";
+
+const SPEC_MODEL = (() => {
+  const r = specModelFrom({ id: "cmp", layout: cmpLayout, tiers: cmpTiers, grammar: cmpGrammar });
+  if (!r.ok) throw new Error(r.reason);
+  return r.model;
+})();
+const E2E_FLOW_DIR = cmpLayout.flows.dir;
+const JOURNEY_TIER = cmpTiers.journey;
 
 /**
  * @param {string} root
@@ -34,8 +44,8 @@ export function evaluateE2eCoverage(root) {
   if (screenFeatures.length === 0) {
     return { verdict: "SKIP", reason: reach.reason ?? "no presentation/<feature> directory has a *Screen.kt file — nothing to cover", details: { features: [] } };
   }
-  const clauses = scanSpecClauses(root);
-  const e2eTags = scanCitations(root).filter((t) => t.tier === "e2e");
+  const clauses = scanSpecClauses(root, SPEC_MODEL);
+  const e2eTags = scanCitations(root, SPEC_MODEL).filter((t) => t.tier === JOURNEY_TIER);
   const features = screenFeatures.map((f) => {
     const specRel = `specs/${f.name}.spec.md`;
     const spec = fs.existsSync(path.join(root, specRel)) ? specRel : null;