create-cmp-cli 0.24.0 → 0.25.0

package/packages/harness/src/watch.mjs

@@ -26,8 +26,9 @@
 // COORDINATION (non-negotiable): two concurrent Gradle invocations against one
 // project corrupt each other's output (KSP cache collisions, half-written
 // classes dirs — a real 20+ bogus-failure cascade). The lane and the preview
-// daemon already coordinate via marker files under composeApp/build:
-//   .cmp-lane-in-progress    — stamped by verify.mjs for a run's duration
+// daemon already coordinate via marker files:
+//   qa/.lane-in-progress     — stamped by verify.mjs for a run's duration (core
+//                              state; qa/lib/lane-markers.mjs)
 //   .cmp-render-in-progress  — stamped by the preview daemon while its Gradle
 //                              build is in flight
 // Watch mode participates as a third citizen: it never launches a run while a
@@ -51,17 +52,20 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { LANE_MARKER_REL, LANE_MARKER_STALE_MS, RENDER_MARKER_FRESH_MS, laneMarkerPath, renderMarkerPath } from "./lib/lane-markers.mjs";
+import { resolveSpecModel } from "./lib/spec-model.mjs";
+
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
 // ── CLI ─────────────────────────────────────────────────────────────────────
 
 export const USAGE = `node qa/watch.mjs [--once] [--json] [--help]
 
-Resident watch mode — the inner verification loop. Watches composeApp/src,
-specs/, and qa/ and runs \`node qa/verify.mjs --fast\` on every save (debounced;
+Resident watch mode — the inner verification loop. Watches the project's
+source roots, specs/, and qa/ and runs \`node qa/verify.mjs --fast\` on every save (debounced;
 a save storm triggers ONE run, changes during a run coalesce into one
 follow-up). It defers while a verify lane or a preview-daemon render holds the
-project (the .cmp-*-in-progress markers under composeApp/build), so two Gradle
+project (qa/.lane-in-progress and the eyes' own render marker), so two build
 invocations never collide.
 
 THIS IS NOT A GATE. It runs the fast tier only: every receipt records
@@ -93,23 +97,106 @@ export function parseWatchArgs(rawArgs) {
 }
 
 // ── The watch set ───────────────────────────────────────────────────────────
-// composeApp/src (the app), specs/ (the contract), qa/ (the harness itself —
-// a golden-tree or e2e-flow edit should re-verify too). NOT watched: build
-// output anywhere, qa/evidence/ (verify.mjs writes latest.json there on every
-// run — watching your own output is an infinite loop), and dotfiles (VCS
-// internals, editor droppings, and the .cmp-*-in-progress markers themselves).
+// The profile's source roots (the app), its specs directory (the contract),
+// and qa/ (the harness itself — a golden-tree or flow edit should re-verify
+// too). NOT watched: the build output directory the PROFILE declares, at any
+// depth (see shouldIgnorePath); qa/evidence/ (verify.mjs writes latest.json
+// there on every run — watching your own output is an infinite loop); and
+// dotfiles (VCS internals, editor droppings, and the in-progress markers
+// themselves).
+
+/**
+ * The trees this loop watches: the profile's own source roots and specs
+ * directory, plus qa/ (the harness judging itself — always core).
+ *
+ * Stage 0 PR 6b: this was `["composeApp/src", "specs", "qa"]`, so the inner
+ * loop in a repo whose code lives anywhere else watched two directories out of
+ * three and never fired on a source edit — a watcher that looks idle and is.
+ * A project with no usable manifest gets the core roots alone and the startup
+ * banner says so, rather than guessing a source layout.
+ * @param {string} root
+ * @returns {{roots: string[], degraded: string|null}}
+ */
+export function watchRoots(root) {
+  const model = resolveSpecModel(root);
+  if (!model.ok) {
+    return { roots: ["specs", "qa"], degraded: model.reason };
+  }
+  return { roots: [...new Set([...model.model.sourceRoots, model.model.specsDir, "qa"])], degraded: null };
+}
+
+// ── Build output: the profile's word, not one stack's ───────────────────────
+// The ignore set's whole job is to keep the loop from watching its own output.
+// It used to find that output by the single literal directory name `build`,
+// which is Gradle's — Rust writes `target/`, .NET `bin/` and `obj/`, Python
+// `__pycache__`, Xcode `DerivedData`. Both halves were wrong, and both
+// silently, with a watcher that looked like it was working:
+//
+//   on those stacks the lane's own writes woke the watcher, which ran the lane
+//   again — a feedback loop, in the one process whose entire purpose is to fire
+//   on a human's edit
+//   and on EVERY stack a real source directory named `build/` (a build script
+//   package, a `build/` module, Python's `app/build/`) was never watched at
+//   all — the "watcher that looks idle and is" that Stage 0 PR 6b already
+//   fixed once for source ROOTS and left in place here
+//
+// The profile declares `layout.buildDir` (qa/lib/spec-model.mjs), so the name
+// is available and was simply not asked for.
+//
+// THE DECLARED DIRECTORY'S NAME MATCHES AT ANY DEPTH, not just the one declared
+// path. A profile declares its app module's output, but a multi-module tree has
+// one such directory PER MODULE (Gradle writes one into every module; the
+// harness's own qa/ subtrees get one too — see test/watch-loop.test.mjs's
+// `qa/somewhere/build/out.json`). Ignoring only the declared path would re-open
+// the feedback loop one directory over. Only that name matches, so a stack that
+// calls its output `target` starts watching `build/` as the ordinary source it
+// is there.
+//
+// That rule is deliberately BROADER than the declaration, and the price is
+// named here rather than discovered: a profile declaring a nested `buildDir`
+// gets its LEAF name ignored everywhere (`build/outputs` ignores every
+// `outputs/` in the tree, not just that one). The startup banner prints the
+// glob it settled on for exactly this reason — an ignore set a reader can see
+// is one they can correct in `layout.buildDir`.
 
-export const WATCH_ROOTS = ["composeApp/src", "specs", "qa"];
+/**
+ * The historical name, kept ONLY for a project whose profile could not be
+ * resolved or which declares no `layout.buildDir`. It is a FALLBACK and not a
+ * default in the approving sense — the startup banner names it, exactly as
+ * spec-model.mjs's `DEFAULT_GRAMMAR.isDefault` makes the borrowed citation
+ * grammar say so out loud. The two failures are not symmetric: watching your
+ * own output loops forever, while missing a source directory named `build/`
+ * costs one manual run. When we know nothing, we take the cheaper mistake.
+ */
+export const FALLBACK_BUILD_OUTPUT_NAME = "build";
+
+/**
+ * The directory NAMES this project's build output wears, from the profile's
+ * declaration. `composeApp/build` → ["build"]; `target` → ["target"].
+ * @param {{buildDir?: string|null}|null} [model] a SpecModel, or null when none resolved
+ * @returns {string[]}
+ */
+export function buildOutputNames(model) {
+  const declared = typeof model?.buildDir === "string" ? model.buildDir : "";
+  const name = declared.replace(/\\/g, "/").split("/").filter(Boolean).pop();
+  return name ? [name] : [FALLBACK_BUILD_OUTPUT_NAME];
+}
 
-/** Ignore predicate over a ROOT-relative path (forward slashes or backslashes). */
-export function shouldIgnorePath(rel) {
+/**
+ * Ignore predicate over a ROOT-relative path (forward slashes or backslashes).
+ * @param {string} rel
+ * @param {{buildDir?: string|null}|null} [model] the project's SpecModel — supplies the
+ *   build output name. Omitted/null falls back to FALLBACK_BUILD_OUTPUT_NAME.
+ */
+export function shouldIgnorePath(rel, model = null) {
   const norm = String(rel).replace(/\\/g, "/");
   if (!norm) return true;
   const parts = norm.split("/");
-  // Any dotted segment: .git, .gradle, .DS_Store, .cmp-lane-in-progress, …
+  // Any dotted segment: .git, .gradle, .DS_Store, .lane-in-progress, …
   if (parts.some((s) => s.startsWith("."))) return true;
-  // Any build dir at any depth (composeApp/build, qa/**/build, …).
-  if (parts.includes("build")) return true;
+  // This profile's build output, at any depth (see the note above).
+  const buildNames = buildOutputNames(model);
+  if (parts.some((s) => buildNames.includes(s))) return true;
   // The lane's own output — the one path that would make watch feed itself.
   if (norm === "qa/evidence" || norm.startsWith("qa/evidence/")) return true;
   return false;
@@ -133,10 +220,11 @@ export const POLL_MS = 2000; // marker-wait poll AND the no-recursive-watch fall
 // around its Gradle builds. Freshness is mtime-bounded so a crashed stamper
 // never wedges us.
 
-export const LANE_MARKER_REL = ["composeApp", "build", ".cmp-lane-in-progress"];
-export const RENDER_MARKER_REL = ["composeApp", "build", ".cmp-render-in-progress"];
-export const LANE_MARKER_STALE_MS = 30 * 60 * 1000; // preview-service.mjs's bound for this marker
-export const RENDER_MARKER_FRESH_MS = 5 * 60 * 1000; // verify.mjs's bound for this marker
+// Paths and bounds are qa/lib/lane-markers.mjs's — the lane marker is core state
+// under qa/, the render marker is the profile's (under its buildDir, or none).
+// Re-exported because markerDecision's bounds are part of this module's
+// contract (qa/watch.mjs --json consumers and the engine suite read them).
+export { LANE_MARKER_STALE_MS, RENDER_MARKER_FRESH_MS };
 
 /**
  * The launch decision, pure: given the two markers' mtimes (null = absent) and
@@ -145,10 +233,10 @@ export const RENDER_MARKER_FRESH_MS = 5 * 60 * 1000; // verify.mjs's bound for t
  */
 export function markerDecision({ laneMtimeMs = null, renderMtimeMs = null, nowMs = Date.now() } = {}) {
   if (laneMtimeMs != null && nowMs - laneMtimeMs < LANE_MARKER_STALE_MS) {
-    return { launch: false, reason: "a verify lane is in progress (.cmp-lane-in-progress is fresh) — deferring; changes coalesce into one run when it finishes" };
+    return { launch: false, reason: `a verify lane is in progress (${LANE_MARKER_REL} is fresh) — deferring; changes coalesce into one run when it finishes` };
   }
   if (renderMtimeMs != null && nowMs - renderMtimeMs < RENDER_MARKER_FRESH_MS) {
-    return { launch: false, reason: "the preview daemon has a Gradle build in flight (.cmp-render-in-progress is fresh) — deferring; changes coalesce into one run when it finishes" };
+    return { launch: false, reason: "the preview daemon has a build in flight (.cmp-render-in-progress is fresh) — deferring; changes coalesce into one run when it finishes" };
   }
   return { launch: true };
 }
@@ -304,8 +392,8 @@ function markerMtime(absPath) {
 
 function launchDecisionNow() {
   return markerDecision({
-    laneMtimeMs: markerMtime(path.join(ROOT, ...LANE_MARKER_REL)),
-    renderMtimeMs: markerMtime(path.join(ROOT, ...RENDER_MARKER_REL)),
+    laneMtimeMs: markerMtime(laneMarkerPath(ROOT)),
+    renderMtimeMs: markerMtime(renderMarkerPath(ROOT)),
   });
 }
 
@@ -383,7 +471,7 @@ function main() {
         currentChild = null;
         // A signal-killed child never ran verify's `finally` — clean the lane
         // marker it stamped so nothing defers on a ghost for 30 minutes.
-        if (signal) clearMarkerIfOwnedBy(path.join(ROOT, ...LANE_MARKER_REL), child.pid);
+        if (signal) clearMarkerIfOwnedBy(laneMarkerPath(ROOT), child.pid);
         const durationMs = Date.now() - started;
         const receipt = parseReceipt(stdout);
         const rawTail = `${stdout}\n${stderr}`.split("\n").filter(Boolean);
@@ -453,7 +541,18 @@ function main() {
 
   const watchers = [];
   const pollTimers = [];
-  const watchedRoots = WATCH_ROOTS.filter((rel) => fs.existsSync(path.join(ROOT, rel)));
+  const { roots: declaredRoots, degraded: rootsDegraded } = watchRoots(ROOT);
+  const watchedRoots = declaredRoots.filter((rel) => fs.existsSync(path.join(ROOT, rel)));
+  // The ignore set is this profile's too: WHICH directory holds build output is
+  // a stack fact (`layout.buildDir`), and a watcher that guesses it either
+  // feeds itself or skips real source. resolveSpecModel shares the module cache
+  // with watchRoots's own call, so this is a map lookup, not a second load.
+  const specModel = (() => {
+    const r = resolveSpecModel(ROOT);
+    return r.ok ? r.model : null;
+  })();
+  const ignoredBuildNames = buildOutputNames(specModel);
+  const ignorePath = (rel) => shouldIgnorePath(rel, specModel);
 
   // Poll fallback for platforms without recursive fs.watch: a full mtime scan
   // per tick, diffed against the previous one so changed paths still get
@@ -470,7 +569,7 @@ function main() {
       }
       for (const e of entries) {
         const rel = `${dirRel}/${e.name}`;
-        if (shouldIgnorePath(rel)) continue;
+        if (ignorePath(rel)) continue;
         const abs = path.join(dirAbs, e.name);
         if (e.isDirectory()) walk(abs, rel);
         else {
@@ -511,7 +610,7 @@ function main() {
     try {
       const w = fs.watch(path.join(ROOT, rootRel), { recursive: true }, (_event, filename) => {
         const rel = filename ? `${rootRel}/${String(filename).replace(/\\/g, "/")}` : rootRel;
-        if (shouldIgnorePath(rel)) return;
+        if (ignorePath(rel)) return;
         loop.change(rel);
       });
       w.on("error", () => {
@@ -531,9 +630,23 @@ function main() {
   }
 
   // Startup: what is watched, what is respected, what this is NOT.
+  // The ignore globs are PRINTED, never assumed: they name the directory this
+  // profile declared, so a reader can see at a glance that the loop is ignoring
+  // this stack's output and not some other stack's word for it.
+  const ignoreGlobs = [...ignoredBuildNames.map((n) => `**/${n}/**`), "qa/evidence/**", "dotfiles"];
   say("qa/watch.mjs — resident inner loop: runs `node qa/verify.mjs --fast` on save");
-  say(`watching: ${watchedRoots.join(", ")}  (ignoring **/build/**, qa/evidence/**, dotfiles)`);
-  say("coordination: defers while composeApp/build/.cmp-lane-in-progress or .cmp-render-in-progress is fresh — never two Gradle invocations against this project");
+  say(`watching: ${watchedRoots.join(", ")}  (ignoring ${ignoreGlobs.join(", ")})`);
+  // Never watch a guessed layout silently: if the manifest could not be read,
+  // the source roots are unknown and this loop is watching less than it looks.
+  if (rootsDegraded) say(`NOTE: watching the core roots only — ${rootsDegraded}`);
+  // And never ignore a guessed layout silently either. A profile that declares
+  // no layout.buildDir leaves this loop on FALLBACK_BUILD_OUTPUT_NAME — one
+  // stack's convention, applied to a stack that never claimed it — so it says
+  // so, the way a borrowed citation grammar does (spec-model.mjs).
+  else if (specModel && typeof specModel.buildDir !== "string") {
+    say(`NOTE: this profile declares no layout.buildDir — ignoring **/${FALLBACK_BUILD_OUTPUT_NAME}/** as a fallback, which may be this project's real source`);
+  }
+  say(`coordination: defers while ${LANE_MARKER_REL} or the eyes' render marker is fresh — never two builds against this project`);
   say(`debounce: ${DEBOUNCE_MS}ms — a save storm triggers one run; changes during a run coalesce into one follow-up`);
   say(FOOTER);
   say("waiting for changes… (Ctrl-C to stop · --once for a single pass · --json for line-per-run output)");
@@ -541,9 +654,9 @@ function main() {
     event: "start",
     pid: process.pid,
     watching: watchedRoots,
-    ignoring: ["**/build/**", "qa/evidence/**", "dotfiles"],
+    ignoring: ignoreGlobs,
     debounceMs: DEBOUNCE_MS,
-    coordinates: [LANE_MARKER_REL.join("/"), RENDER_MARKER_REL.join("/")],
+    coordinates: [LANE_MARKER_REL, renderMarkerPath(ROOT) ? path.relative(ROOT, renderMarkerPath(ROOT)).split(path.sep).join("/") : null].filter(Boolean),
     runs: "node qa/verify.mjs --fast",
     note: FOOTER,
   });
@@ -598,7 +711,7 @@ function installSignalHandlers(stopWork, getChild, emit, say) {
         signalTree("SIGKILL");
         await Promise.race([exited, sleep(1000)]);
       }
-      clearMarkerIfOwnedBy(path.join(ROOT, ...LANE_MARKER_REL), child.pid);
+      clearMarkerIfOwnedBy(laneMarkerPath(ROOT), child.pid);
     }
     say(`watch mode stopped (${sig}) — no receipt was made valid by watching; the done-gate is still one full \`node qa/verify.mjs\` run`);
     emit({ event: "shutdown", reason: sig });

package/packages/receipts/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@create-cmp/receipts",
+  "name": "prooflane-receipts",
   "version": "0.1.0",
   "description": "Validate create-cmp evidence receipts: inputs-hash recompute, receipt-vs-tree binding, freshness, and execution-plausibility. Dependency-free ESM \u2014 the single source of truth vendored into every generated project's qa/lib/ and consumed by the hosted receipt check.",
   "type": "module",

package/packages/receipts/src/index.mjs

@@ -1,9 +1,9 @@
-// @create-cmp/receipts — validate create-cmp evidence receipts.
+// prooflane-receipts — validate create-cmp evidence receipts.
 // Single source of truth for the inputs-hash algorithm and the receipt
 // predicate; vendored byte-identical into every generated project's qa/lib/
 // and consumed by hosted validators. Dependency-free ESM.
 
-export { computeInputsHash, VERIFIED_SURFACE } from "./inputs-hash.mjs";
+export { computeInputsHash, defaultSurface } from "./inputs-hash.mjs";
 export {
   RECEIPT_REL_PATH,
   readReceipt,

package/packages/receipts/src/inputs-hash.mjs

@@ -5,7 +5,7 @@
 // there is exactly one definition of the surface and the algorithm.
 //
 // SINGLE SOURCE OF TRUTH: packages/receipts/src/inputs-hash.mjs in the
-// create-cmp repo (the `@create-cmp/receipts` package). The copy in a generated
+// create-cmp repo (the `prooflane-receipts` package). The copy in a generated
 // project's qa/lib/ is vendored byte-identical at scaffold time and pinned by
 // test/receipts-parity.test.mjs — edit the package source, then run
 // `node scripts/sync-harness.mjs`.
@@ -30,15 +30,46 @@ import path from "node:path";
 // looking the same is the worst failure this harness can have, so the surface
 // is now resolved per project (see resolveVerifiedSurface) and an empty one is
 // refused rather than hashed.
-export const VERIFIED_SURFACE = [
-  "composeApp",
-  "specs",
-  "qa",
-  "gradle/libs.versions.toml",
-  "build.gradle.kts",
-  "settings.gradle.kts",
-  "gradle.properties",
-];
+/**
+ * The surface a project gets when it has NOT declared one.
+ *
+ * This used to be a constant: `composeApp`, `specs`, `qa`, and the Gradle files
+ * — one stack's directory names, in the module every adopter's receipt is
+ * computed by. Vendored into a repo whose code lives under `services/`, it
+ * matched `qa/` and `specs/` and nothing else, so the lane produced a valid,
+ * confident, SMALLER hash: a receipt attesting a fraction of a project while
+ * looking complete. The file's own header calls that the worst failure this
+ * harness can have, and then shipped it as the default.
+ *
+ * Derived from the tree instead, and deliberately WIDE. Over-attesting costs a
+ * hash that moves more often than it needs to; under-attesting silently drops
+ * files from what a receipt claims. Only one of those is a lie, so the error is
+ * taken in the safe direction. Build output and dependency directories are
+ * excluded because they are outputs, not the thing being attested.
+ *
+ * A project that wants a narrower or pinned surface DECLARES one — `harness
+ * init` writes it, and the template ships one, so this fallback is for repos
+ * that predate the declaration rather than the normal path.
+ *
+ * @param {string} root
+ * @returns {string[]}
+ */
+export function defaultSurface(root) {
+  // The same construction as the walk — the universal floor plus what this
+  // repo's own .gitignore says — so the two agree by construction. qa-artifacts
+  // is the lane's own output and stays named.
+  const skip = new Set([...WALK_FLOOR, "qa-artifacts", ...gitignoredDirs(root), ...declaredIgnore(root)]);
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => !e.name.startsWith(".") && !skip.has(e.name))
+    .map((e) => e.name)
+    .sort();
+}
 
 // Paths EXCLUDED even though they fall under an included surface dir above.
 // qa/evidence and qa-artifacts are lane OUTPUTS — including them would make
@@ -74,6 +105,10 @@ const EXCLUDED_PREFIXES = [
   // un-proves the tree — the exact inversion this family of exclusions exists
   // to prevent.
   "qa/.agent-hold.json",
+  // The lane's own in-flight marker (qa/lib/lane-markers.mjs): stamped for a
+  // run's duration, rewritten at every step. Hashing it would make the lane
+  // invalidate its own receipt mid-run.
+  "qa/.lane-in-progress",
   "qa/evidence",
   "qa-artifacts",
   "qa/comments.json",
@@ -139,7 +174,111 @@ function tryGitLsFiles(root) {
 // "INVALID — source changed" the moment the user runs `git init`, even though
 // no source changed. Pre-git and post-git hashes must agree for identical
 // source; that is the invariant the regression test pins.
-const WALK_EXCLUDED_DIRS = new Set(["build", ".gradle", ".kotlin", ".git", ".idea", "node_modules"]);
+// A FLOOR, not the rule. This used to BE the rule, and it was one ecosystem's:
+// it knew build/.gradle/.kotlin/.idea/node_modules and nothing of __pycache__,
+// venv, target (Rust, Maven), bin and obj (.NET), vendor (Go, PHP), Pods or
+// DerivedData. So a Python tree hashed one set of bytes before `git init` and a
+// different set after, and the stamp-time PASS receipt read "source changed
+// since the receipt" the instant a user ran `git init` — with no source change.
+// That is the exact invariant the constant was written to hold, broken for
+// every ecosystem but the first.
+// THE FLOOR IS UNIVERSAL; EVERYTHING ELSE IS DECLARED. `.git` is git's, and
+// `node_modules` is this lane's own runtime. Until 2026-09-08 this set also
+// carried `build`, `.gradle`, `.kotlin`, `.idea` — one ecosystem's build output,
+// applied to every tree. PATTERN: the repo's own ignore file is the truth
+// (ripgrep, watchman and git itself all read .gitignore rather than a table);
+// beneath it, the profile declares `layout.ignore` and `layout.buildDir`,
+// written into qa/verified-surface.json as `ignore` so THIS package — the
+// notary's, which must know no profile — reads a project fact, not a stack.
+// WHY IT WORKS: the people who know the stack maintain the list, in the file
+// they already maintain. HOW IT FAILS: a tree with no git, no .gitignore and no
+// declaration hashes its build output — a hash that moves too often, which is
+// the safe direction. WHAT WE DO: that case is the walk, and the walk prints
+// its rules. Q5 (NORTH-STAR §10): git-mode hashing is untouched, and a cmp
+// tree's .gitignore already lists these directories, so no receipt moves.
+const WALK_FLOOR = new Set([".git", "node_modules"]);
+const WALK_EXCLUDED_DIRS = WALK_FLOOR;
+
+/**
+ * Directories the project DECLARED unhashable — qa/verified-surface.json's
+ * optional `ignore` list, written by `harness init` from `layout.ignore` and
+ * `layout.buildDir`, so the notary reads a project fact rather than a profile.
+ * @param {string} root
+ * @returns {Set<string>}
+ */
+export function declaredIgnore(root) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(root, SURFACE_CONFIG_REL), "utf8"));
+    const list = Array.isArray(parsed?.ignore) ? parsed.ignore : [];
+    return new Set(list.filter((x) => typeof x === "string" && x.trim() && !x.includes("..")).map((x) => x.replace(/^\.\//, "").replace(/\/$/, "")));
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * The directories THIS repo ignores, read from its own `.gitignore`.
+ *
+ * Walk mode exists only before `git init`, and its whole job is to agree with
+ * what `git ls-files --exclude-standard` will say afterwards. Maintaining a
+ * hand-written list of every ecosystem's build directory is a losing game and
+ * was already lost; reading the file git reads makes the two modes agree BY
+ * CONSTRUCTION rather than by vigilance.
+ *
+ * Deliberately a small subset of gitignore syntax — bare directory names, with
+ * or without a leading or trailing slash. Globs, negations and nested paths are
+ * left to git, which is running in every case that matters. Missing one costs a
+ * hash that moves too often; that is the safe direction, and the same one
+ * `defaultSurface` errs in.
+ *
+ * @param {string} root
+ * @returns {Set<string>}
+ */
+export function gitignoredDirs(root) {
+  let text;
+  try {
+    text = fs.readFileSync(path.join(root, ".gitignore"), "utf8");
+  } catch {
+    return new Set();
+  }
+  const out = new Set();
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#") || line.startsWith("!")) continue;
+    if (line.includes("*") || line.includes("?") || line.includes("[")) continue;
+    const name = line.replace(/^\//, "").replace(/\/$/, "");
+    if (name && !name.includes("/")) out.add(name);
+  }
+  return out;
+}
+/**
+ * Files that are INPUTS TO THE RESOLUTION rather than members of the surface.
+ *
+ * `.gitignore` decides what is attested: `git ls-files --exclude-standard`
+ * honours it, and `gitignoredDirs` above makes the walk fallback honour it too.
+ * A file that decides the attested set and is not itself attested is a hole —
+ * edit one line and a directory silently leaves every future receipt, with
+ * nothing in the chain saying the coverage moved. That is the narrowing failure
+ * this module's header calls the worst one it can have, arriving through the
+ * side door.
+ *
+ * Attested STRUCTURALLY, outside `surfaceEntries`, because a declaration that
+ * could omit it would reopen exactly the hole: `defaultSurface` skips dotfiles,
+ * the shipped template surface lists none, and no adopter writing
+ * `qa/verified-surface.json` by hand would think to add it. It is not the
+ * adopter's to declare — it is the resolver's own input.
+ *
+ * Not locked: adopters edit `.gitignore` legitimately and often. Attestation is
+ * the right instrument — a change makes the receipt say "source changed", which
+ * is true, and re-running mints a valid one.
+ */
+const RESOLUTION_INPUTS = Object.freeze([".gitignore"]);
+
+/** @param {string} relPath @returns {boolean} */
+function isResolutionInput(relPath) {
+  return RESOLUTION_INPUTS.includes(relPath);
+}
+
 // File-level mirror of the same principle (OS/editor junk the .gitignore covers).
 const WALK_EXCLUDED_FILES = new Set([".DS_Store"]);
 const WALK_EXCLUDED_SUFFIXES = [".iml", ".log"];
@@ -150,14 +289,16 @@ function walkIncludesFile(name) {
 }
 
 // Dependency-free recursive walk, used when git is unavailable (non-git scaffold).
-function walkAllFiles(dir) {
+// `ignored` is the floor plus whatever this repo's own .gitignore names, so the
+// pre-git hash agrees with the post-git one for any ecosystem, not just the first.
+function walkAllFiles(dir, ignored = WALK_EXCLUDED_DIRS) {
   const out = [];
   if (!fs.existsSync(dir)) return out;
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const p = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (WALK_EXCLUDED_DIRS.has(entry.name)) continue; // non-source scratch — see note above
-      out.push(...walkAllFiles(p));
+      if (ignored.has(entry.name)) continue; // non-source scratch — see note above
+      out.push(...walkAllFiles(p, ignored));
     } else if (entry.isFile() && walkIncludesFile(entry.name)) out.push(p);
   }
   return out;
@@ -191,7 +332,7 @@ export function resolveVerifiedSurface(root) {
   try {
     raw = fs.readFileSync(p, "utf8");
   } catch {
-    return VERIFIED_SURFACE; // no declaration — the CMP default, unchanged
+    return defaultSurface(root); // no declaration — the tree's own top level
   }
   let parsed;
   try {
@@ -208,32 +349,41 @@ export function resolveVerifiedSurface(root) {
 
 // Resolve the verified surface to a flat, sorted list of paths (relative to
 // root, POSIX-style `/` separators) that currently exist on disk.
-function resolveSurfaceFiles(root, VERIFIED_SURFACE) {
+function resolveSurfaceFiles(root, surfaceEntries) {
   const gitFiles = tryGitLsFiles(root);
 
   if (gitFiles) {
     return gitFiles
       .map((p) => p.split(path.sep).join("/"))
-      .filter((relPath) => VERIFIED_SURFACE.some((surface) => relPath === surface || relPath.startsWith(`${surface}/`)))
+      .filter((relPath) => isResolutionInput(relPath) || surfaceEntries.some((surface) => relPath === surface || relPath.startsWith(`${surface}/`)))
       .filter((relPath) => !isExcluded(relPath))
       .filter((relPath) => fs.existsSync(path.join(root, relPath)) && fs.statSync(path.join(root, relPath)).isFile());
   }
 
   // Fallback: no git available — walk the surface directories directly so a
-  // non-git scaffold still produces a stable hash.
+  // non-git scaffold still produces a stable hash. The ignore set is the floor
+  // PLUS this repo's own .gitignore, which is what `git ls-files
+  // --exclude-standard` will honour the moment the tree becomes a repo. Reading
+  // the same file is what makes the two modes agree by construction.
+  const ignored = new Set([...WALK_FLOOR, ...gitignoredDirs(root), ...declaredIgnore(root)]);
   const collected = [];
-  for (const surface of VERIFIED_SURFACE) {
+  for (const surface of surfaceEntries) {
     const abs = path.join(root, surface);
     if (!fs.existsSync(abs)) continue;
     const stat = fs.statSync(abs);
     if (stat.isFile()) {
       collected.push(surface);
     } else if (stat.isDirectory()) {
-      for (const file of walkAllFiles(abs)) {
+      for (const file of walkAllFiles(abs, ignored)) {
         collected.push(path.relative(root, file).split(path.sep).join("/"));
       }
     }
   }
+  // The resolver's own inputs, attested whatever the surface declares.
+  for (const rel of RESOLUTION_INPUTS) {
+    const abs = path.join(root, rel);
+    if (!collected.includes(rel) && fs.existsSync(abs) && fs.statSync(abs).isFile()) collected.push(rel);
+  }
   return collected.filter((relPath) => !isExcluded(relPath));
 }
 
@@ -246,7 +396,9 @@ function resolveSurfaceFiles(root, VERIFIED_SURFACE) {
  * it belongs in qa/verified-surface.json. Sorted; [] when git is unavailable
  * (the walk fallback has no notion of "what git sees") or everything is
  * covered. Lane outputs (EXCLUDED_PREFIXES) are not "undeclared" — they are
- * excluded by decision.
+ * excluded by decision, and RESOLUTION_INPUTS are not undeclared either: they
+ * are attested structurally, so naming them here would report a file as
+ * unattested that the very same hash attests.
  * @param {string} root
  * @param {string[]} [surface] defaults to resolveVerifiedSurface(root)
  * @returns {string[]}
@@ -254,7 +406,8 @@ function resolveSurfaceFiles(root, VERIFIED_SURFACE) {
 export function undeclaredTopLevel(root, surface = resolveVerifiedSurface(root)) {
   const gitFiles = tryGitLsFiles(root);
   if (!gitFiles) return [];
-  const covered = (relPath) => surface.some((entry) => relPath === entry || relPath.startsWith(`${entry}/`)) || isExcluded(relPath);
+  const covered = (relPath) =>
+    surface.some((entry) => relPath === entry || relPath.startsWith(`${entry}/`)) || isExcluded(relPath) || isResolutionInput(relPath);
   const out = new Set();
   for (const raw of gitFiles) {
     const relPath = raw.split(path.sep).join("/");