@ultimat3/cli 6.0.0 → 8.0.0

package/src/templates/scaffold-db-package.ts

@@ -1,6 +1,6 @@
-// The generated app's `packages/db`: the entity re-export list the migration generator reads and
-// the deterministic seed. No business logic — that is the package's own stated boundary, and it is
-// why `example` reaches only the two files describing the slice's table.
+// The generated app's `packages/db`: the entity re-export list the app's own modules import from
+// and the deterministic seed. No business logic — that is the package's own stated boundary, and it
+// is why `example` reaches only the two files describing the slice's table.
 //
 // No migration. `x db gen` is the ONE writer of `packages/db/migrations`, and a scaffold that hand-
 // wrote `0000_initial.sql` was a second one: it declared a `posts` table the generator had never
@@ -13,6 +13,37 @@ import { packageShapeFiles, workspacePackageJson } from './scaffold-package-shap
 
 const DESCRIPTION = 'Entity re-exports and SQL migrations, no business logic';
 
+/**
+ * The example slice's entity lives in `apps/web/app/post/`, so `src/schema.ts` re-exports it from
+ * there — an edge this manifest has to declare or it exists only inside the root tsconfig's
+ * `paths`, where `bun --filter` and every change-detection tool are blind to it
+ * (`X_WORKSPACE_DEP_UNDECLARED`). Written here rather than through `workspacePackageJson` for the
+ * reason `scaffold-i18n.ts` states: that helper is the dependency-free shape.
+ *
+ * Under `--no-example` there is no entity and no import, so there is no dependency either: a pin
+ * for an edge the package does not have is the same lie in the other direction.
+ */
+const dbPackage = (app: NameSet, example: boolean): string =>
+  example
+    ? `{
+  "name": "@${app.kebab}/db",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "${DESCRIPTION}",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p ../../tsconfig.json"
+  },
+  "dependencies": {
+    "@${app.kebab}/web": "0.0.0"
+  }
+}
+`
+    : workspacePackageJson(app, 'db', DESCRIPTION);
+
 const dbIndex =
   (): string => `// Schema and migrations only — no business logic lives in this package. The client itself is
 // @ultimat3/db's: one connection pool, sized by ROLE, shared by every package in the app.
@@ -25,8 +56,16 @@ export * as schema from './schema';
 // never written, so each one ships its empty counterpart instead of a reference to a file that is
 // not there — `export { post } from …` alone made `x new --no-example` an app that cannot compile.
 
-const SCHEMA_HEADER = `// Every entity the app declares, re-exported here. This list is what the migration generator
-// reads, so an entity that is not exported here does not exist as far as the database is concerned.`;
+// Not "what the migration generator reads" — that claim shipped into every generated app and was
+// false. `x db gen` and `x verify`'s `drift` step both project the ENTITY REGISTRY that `loadApp`
+// fills (`describeEntities()`, `packages/cli/src/app-entities.ts`), so an entity declared anywhere
+// `loadApp` reaches is already in the migration whether or not this file names it. Re-exporting an
+// entity here does exactly one thing, and it is worth doing: it gives `seed.ts` and every other
+// consumer ONE import to reach the app's tables through.
+const SCHEMA_HEADER = `// Every entity the app declares, re-exported here so the seed and anything else that needs a table
+// reach them through one import. It is not what the migration generator reads: \`x db gen\` and the
+// \`drift\` step project the entity registry, so an entity is in the migration because it was
+// declared, never because it was listed here.`;
 
 const dbSchema = (app: NameSet, example: boolean): string =>
   example
@@ -34,7 +73,7 @@ const dbSchema = (app: NameSet, example: boolean): string =>
 export { post } from '@${app.kebab}/web/app/post/entity';
 `
     : `${SCHEMA_HEADER}
-// \`x g entity <name>\` writes the entity; add its export here so the database learns about it.
+// \`x g entity <name>\` writes the entity; add its export here to reach it through \`@${app.kebab}/db\`.
 export {};
 `;
 
@@ -101,7 +140,7 @@ export const ${app.camel}Seed = defineSeed('${app.kebab}', async () => {
 
 /** Every file the `packages/db` workspace ships, in the order `x new` writes them. */
 export const dbPackageFiles = (app: NameSet, example: boolean): readonly GeneratedFile[] => [
-  { path: 'packages/db/package.json', contents: workspacePackageJson(app, 'db', DESCRIPTION) },
+  { path: 'packages/db/package.json', contents: dbPackage(app, example) },
   ...packageShapeFiles(app, 'db', DESCRIPTION),
   { path: 'packages/db/src/index.ts', contents: dbIndex() },
   { path: 'packages/db/src/schema.ts', contents: dbSchema(app, example) },

package/src/templates/scaffold-docs.ts

@@ -13,19 +13,30 @@ const agents = (app: NameSet): string => `# AGENTS.md
 Human-authored, short, stable. Facts live in \`x.manifest.json\`; this file holds only what an
 agent cannot infer from the code.
 
-| Rule | Detail |
-|---|---|
-| One gate | \`x verify\` — green means shippable. Never merge red. |
-| One way | generators, not hand-rolled files: \`x g resource\`, \`x g action\`, \`x g route\` |
-| Surfaces | \`site/\` is 0kb JS and may not import \`app/\`; \`shared/\` is a leaf |
-| Data | routes call actions and queries; only \`repo.ts\` touches the database |
-| Errors | never \`throw new Error\` — subclass \`UltimateError\` with a code, a cause and a fix |
-| Money | integer minor units + ISO code, never a float |
-| Time | store UTC, format with an explicit IANA time zone |
-| Strings | every user-facing string goes through \`t()\` |
-| Colour | semantic tokens only, never a raw hex |
-
-Commands: \`x dev\`, \`x verify\`, \`x g <primitive>\`, \`x db branch create <name>\`, \`x doctor\`.
+Every row below names what refuses it. A rule with nothing in the last column is a rule that does
+not exist — five of these had an empty column and were each measured green on \`x verify\`.
+
+| Rule | Detail | Refused by |
+|---|---|---|
+| One gate | \`x verify\` — green means shippable. Never merge red. | the gate itself |
+| One way | generators, not hand-rolled files: \`x g resource\`, \`x g action\`, \`x g route\` | review |
+| Surfaces | \`site/\` is 0kb JS and may not import \`app/\`; \`shared/\` is a leaf | \`X_BOUNDARY_SITE_TO_APP\` |
+| Data | routes call actions and queries; only \`repo.ts\` touches the database | \`X_BOUNDARY_ROUTE_TO_DB\` |
+| Errors | never \`throw new Error\` — subclass \`UltimateError\` with a code, a cause and a fix | \`guards/bare-error.ts\` |
+| Money | \`{ minor, currency }\`, never a float — \`money()\` on the column | the type: \`price: 19.99\` is TS2322, \`number\` is not \`MoneyInput\` |
+| Time | store UTC, format with an explicit IANA time zone | \`guards/unzoned-date.ts\` |
+| Strings | every user-facing string goes through \`t()\` | \`guards/untranslated-string.ts\` |
+| Colour | semantic tokens only, never a raw hex | \`guards/raw-colour.ts\` |
+
+\`guards/\` is yours: each file is one rule, discovered by \`x verify\` and run inside its
+\`boundaries\` step. Delete one to drop the rule, and \`x g guard <name>\` writes the next.
+
+Money is the one row with no guard, deliberately: a float has no static signature a text rule can
+see, and the type already fires — measured, \`price: 19.99\` in a seed is
+\`TS2322: Type 'number' is not assignable to type 'MoneyInput'\`. A guard that pretended to check
+it would be worse than the type that really does.
+
+Commands: \`x dev\`, \`x verify\`, \`x g <primitive>\`, \`x g guard <name>\`, \`x db branch create <name>\`, \`x doctor\`.
 
 Project notes for ${app.kebab}: replace this line with the conventions a newcomer could not guess.
 `;

package/src/templates/scaffold-entries.ts

@@ -0,0 +1,131 @@
+// The two entry files a deploy needs — `apps/web/server.ts` and `apps/web/prerender.ts`. Split out
+// of `scaffold-app.ts` because that file is the three SURFACES and these are neither: they are what
+// a container starts and what a CDN is handed. Both are deliberately thin — which role a container
+// is, which port it binds, how it drains and what a static build enumerates are the framework's
+// answers, so an upgrade moves them without a codemod in every app that ever shipped.
+
+import type { GeneratedFile } from './naming';
+
+const server =
+  (): string => `// The production entry. \`docker/Dockerfile\` starts this, and \`x build --target binary\` compiles it.
+// ROLE selects what this process is — web, sync, worker, scheduler, replicator, or migrate, which
+// applies the migrations and exits. PORT is bound on every interface, because a container bound to
+// localhost is unreachable through its own port mapping.
+
+import { join } from 'node:path';
+import { runRole } from '@ultimat3/cli';
+
+// MORE THAN ONE REPLICA? Add these two lines, above \`runRole\`:
+//
+//   import { configureIdempotency } from '@ultimat3/action';
+//   configureIdempotency({ scope: 'shared' });
+//
+// \`idempotent: true\` on an action promises that a retry does not repeat the work. Under the
+// process-scoped default that promise holds inside ONE process — a client retrying
+// \`POST /api/payments/charge\` after a timeout lands on another replica, which has never seen the
+// key, and charges the card twice, silently, with \`x verify\` green. Declaring \`'shared'\` is what
+// makes that a boot error (\`X_IDEMPOTENCY_NOT_SHARED\`) unless a shared store is installed.
+// \`runRole\` installs the Postgres one for you, on the connection it resolved from \`DATABASE_URL\`,
+// so the declaration is all this app owes. It must run before \`runRole\` imports the actions.
+
+/**
+ * Where the app is. From this file normally — the image's WORKDIR is not the app root's business.
+ * A \`--compile\` binary is the exception: its \`import.meta.dir\` is Bun's virtual filesystem, which
+ * holds this module's bundled imports and none of the app's source, and the framework's registries
+ * are filled by scanning that source at boot. So a binary reads its root from the directory it is
+ * started in — it is a launcher for an app tree, not a self-contained copy of one.
+ */
+const root = import.meta.dir.startsWith('/$bunfs')
+  ? process.cwd()
+  : join(import.meta.dir, '..', '..');
+
+// Guarded, because the framework's module scan imports every file under apps/*/ to fill its
+// registries — an unguarded boot would start a server inside \`x verify\`.
+if (import.meta.main) {
+  await runRole({ root, env: Bun.env });
+}
+`;
+
+const prerender =
+  (): string => `// The static entry. \`x build --target static\` runs this with \`--out <dir>\` and it writes one HTML
+// file per \`render: 'static'\` route — a CDN or an object store then serves site/ with no process
+// behind it. Every other render mode needs a running app and is reported as skipped, never emitted.
+//
+// Skipped is not unweighed: a route that declares a \`budget:\` is rendered in memory and measured
+// whatever its mode, so \`x verify\`'s \`budgets\` step has a number for it. \`unmeasured\` is the list
+// this build could not render — each one is an X_BUDGET_UNMEASURED at the gate, and this is where
+// the reason is.
+//
+// It writes the whole of \`pages\` and \`skipped\`, never a COUNT of either. A count is what let a
+// partial artifact read as a complete one: someone pointed a screenshot tool at \`.x/static\` and
+// filed "the island did not mount" against a route that had never been emitted (issue #242). Each
+// skipped route carries its own \`reason\` and \`why\`, and \`report\` is where the same inventory
+// landed on disk — which is what \`x build --target static --json\` reads back.
+
+import { join } from 'node:path';
+import { DEFAULT_ORIGIN, type PrerenderReport, prerenderSite } from '@ultimat3/cli';
+import { routeEntries } from '@ultimat3/render';
+import { buildRobots, buildSitemap, type RouteRecord } from '@ultimat3/seo';
+
+const root = join(import.meta.dir, '..', '..');
+const flag = Bun.argv.indexOf('--out');
+const out = (flag === -1 ? undefined : Bun.argv[flag + 1]) ?? join(root, '.x', 'static');
+// SITE_ORIGIN is what canonical and og:url are built from; the default is only ever a local build.
+// Property access, not \`Bun.env['SITE_ORIGIN']\`: the scaffolded tsconfig does not set
+// \`noPropertyAccessFromIndexSignature\`, so the bracket form is the one biome's useLiteralKeys
+// reports — a diagnostic in an app's first lint run over a file the app never wrote.
+const origin = Bun.env.SITE_ORIGIN;
+
+/**
+ * The route table as \`@ultimat3/seo\` reads it. \`RouteRecord\` is a static row and \`defineRoute\`
+ * is a live declaration, so one has to be projected onto the other — and \`prerenderSite\` has
+ * already loaded the app by the time this runs, which is what fills \`routeEntries()\`.
+ *
+ * A DYNAMIC route contributes exactly the URLs this build enumerated for it, read back off the
+ * report rather than by calling \`prerender()\` a second time: the sitemap then cannot name a page
+ * the artifact does not contain, which is the only failure mode a sitemap really has.
+ */
+const siteRoutes = (report: PrerenderReport): readonly RouteRecord[] =>
+  routeEntries()
+    .filter((entry) => entry.surface === 'site')
+    .map((entry) => ({
+      path: entry.path,
+      file: entry.file,
+      surface: 'site' as const,
+      render: entry.config.render,
+      prerender: () =>
+        report.pages.filter((page) => page.route === entry.path).map((page) => page.path),
+    }));
+
+/**
+ * \`sitemap.xml\` and \`robots.txt\`, into the same directory the HTML went. Both belong to the
+ * ARTIFACT rather than to a request: a static export is served with no process behind it, so a
+ * route that answered them at run time would be a file the CDN never has.
+ *
+ * \`buildRobots\` fails closed — anything that is not \`ULTIMATE_ENV=production\` emits
+ * \`Disallow: /\` and advertises no sitemap — so a preview build cannot outrank the real site.
+ */
+async function writeSeoFiles(report: PrerenderReport, baseUrl: string): Promise<readonly string[]> {
+  const sitemap = await buildSitemap(siteRoutes(report), { baseUrl });
+  // Past 50,000 URLs \`files\` are \`/sitemap-N.xml\` and the index is \`/sitemap.xml\`; below it,
+  // \`files\` is that one file and there is no index. Writing both lists covers each case once.
+  const written = sitemap.index === undefined ? sitemap.files : [sitemap.index, ...sitemap.files];
+  for (const file of written) await Bun.write(join(out, file.path), file.xml);
+  await Bun.write(join(out, 'robots.txt'), buildRobots({ baseUrl, sitemaps: ['/sitemap.xml'] }));
+  return [...written.map((file) => file.path), '/robots.txt'];
+}
+
+if (import.meta.main) {
+  const report = await prerenderSite({ root, out, ...(origin === undefined ? {} : { origin }) });
+  const seo = await writeSeoFiles(report, origin ?? DEFAULT_ORIGIN);
+  await Bun.stdout.write(
+    \`\${JSON.stringify({ ok: true, out: report.out, emitted: report.pages, skipped: report.skipped, unmeasured: report.unmeasured, report: report.report, seo })}\\n\`,
+  );
+}
+`;
+
+/** The two files, in the order a deploy meets them: the process, then the artifact. */
+export const entryFiles = (): readonly GeneratedFile[] => [
+  { path: 'apps/web/server.ts', contents: server() },
+  { path: 'apps/web/prerender.ts', contents: prerender() },
+];

package/src/templates/scaffold-guards.ts

@@ -0,0 +1,26 @@
+// The `guards/` directory `x new` writes, and the one list that names every guard in it.
+//
+// `x new` shipped ZERO guards while the `AGENTS.md` it writes stated nine non-negotiables — five of
+// which nothing enforced, each measured green on `x verify` in a scaffolded app. The mechanism was
+// never missing: `guards/` is discovered, not registered, and runs inside the `boundaries` step
+// (`packages/cli/src/guards.ts`). What was missing is any guard to discover. Four of the five are
+// here; the fifth, money-as-float, has no static signature and is answered by the `Money` type
+// instead — `scaffold-docs.ts` says so where an author reads it.
+
+import { bareErrorGuardFiles } from './guard-bare-error';
+import { rawColourGuardFiles } from './guard-raw-colour';
+import { untranslatedStringGuardFiles } from './guard-untranslated-string';
+import { unzonedDateGuardFiles } from './guard-unzoned-date';
+import type { GeneratedFile } from './naming';
+
+/**
+ * Every guard `x new` ships, each with its test. One module per guard, because an app deletes a
+ * rule it does not want by deleting one file — and a guard the app then writes for itself is
+ * `x g guard <name>`, the same shape.
+ */
+export const scaffoldGuardFiles = (): readonly GeneratedFile[] => [
+  ...bareErrorGuardFiles(),
+  ...rawColourGuardFiles(),
+  ...untranslatedStringGuardFiles(),
+  ...unzonedDateGuardFiles(),
+];

package/src/templates/scaffold-mcp-package.ts

@@ -3,10 +3,43 @@
 // itself.
 
 import type { GeneratedFile, NameSet } from './naming';
-import { packageShapeFiles, workspacePackageJson } from './scaffold-package-shape';
+import { packageShapeFiles } from './scaffold-package-shape';
 
 const DESCRIPTION = "The app's own MCP tools";
 
+/**
+ * Writes its own manifest, for the reason `scaffold-i18n.ts` does: `workspacePackageJson` is the
+ * dependency-free shape, and this package has a real dependency — `src/index.ts` below imports the
+ * app's actions out of `apps/web/api`, because `registerActions` has to see them.
+ *
+ * The edge points AT the app, which is unusual and correct. `apps/web` is a workspace like any
+ * other; reversing it would put the tool catalog upstream of the actions it projects. Declared
+ * rather than left to the root tsconfig's `paths`: an undeclared edge resolves for `tsc` and for
+ * nothing else — not for `bun --filter` ordering, not for any tool asking what a change affects
+ * (`X_WORKSPACE_DEP_UNDECLARED`).
+ *
+ * `"0.0.0"` and not `workspace:*`: it is the version `apps/web` really carries, which is what
+ * `checkLockstep` compares a sibling pin against, and it is the one spelling every other manifest
+ * `x new` writes already uses.
+ */
+const mcpPackage = (app: NameSet): string => `{
+  "name": "@${app.kebab}/mcp",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "${DESCRIPTION}",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p ../../tsconfig.json"
+  },
+  "dependencies": {
+    "@${app.kebab}/web": "0.0.0"
+  }
+}
+`;
+
 const mcpIndex = (
   app: NameSet,
 ): string => `// The app's own MCP tools. Every action with mcp.expose is already a tool; add app-specific
@@ -42,7 +75,7 @@ unitTest('the app exposes its actions as MCP tools', () => {
 
 /** Every file the `packages/mcp` workspace ships, in the order `x new` writes them. */
 export const mcpPackageFiles = (app: NameSet): readonly GeneratedFile[] => [
-  { path: 'packages/mcp/package.json', contents: workspacePackageJson(app, 'mcp', DESCRIPTION) },
+  { path: 'packages/mcp/package.json', contents: mcpPackage(app) },
   ...packageShapeFiles(app, 'mcp', DESCRIPTION),
   { path: 'packages/mcp/src/index.ts', contents: mcpIndex(app) },
   { path: 'packages/mcp/src/index.test.ts', contents: mcpTest() },

package/src/templates/scaffold-package-shape.ts

@@ -50,8 +50,13 @@ export const packageShapeFiles = (
 
 /**
  * The manifest every scaffolded `packages/*` carries. Private, versionless-by-convention and
- * dependency-free: these packages only re-export a framework package's types, so the one that does
- * name a dependency writes its own (`scaffold-i18n.ts`, and it says why). Lives beside
+ * dependency-free: these packages only re-export a framework package's types. Three now DO name a
+ * dependency and each writes its own manifest — `scaffold-i18n.ts`, `scaffold-mcp-package.ts` and
+ * `scaffold-db-package.ts` (the last only under `--example`, which is the branch that emits the
+ * import). Each says why at its own site. They write their own rather than taking a `dependencies`
+ * parameter here because the edge is a fact about the SOURCE that template emits, and a parameter
+ * would let a caller declare an edge its generated code does not have — which is the drift
+ * `X_WORKSPACE_DEP_UNDECLARED` exists to catch, pointed the other way. Lives beside
  * `packageShapeFiles` because every caller of one calls the other.
  */
 export const workspacePackageJson = (app: NameSet, name: string, description: string): string => `{

package/src/templates/scaffold-repo.ts

@@ -12,6 +12,7 @@ import { dbPackageFiles } from './scaffold-db-package';
 import { docsFiles } from './scaffold-docs';
 import { domainPackageFiles } from './scaffold-domain-package';
 import { envExampleSource, envSchemaSource } from './scaffold-env';
+import { scaffoldGuardFiles } from './scaffold-guards';
 import { i18nFiles } from './scaffold-i18n';
 import { mcpPackageFiles } from './scaffold-mcp-package';
 import { uiPackageFiles } from './scaffold-ui-package';
@@ -70,6 +71,7 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "@ultimat3/query": "^${version}",
     "@ultimat3/render": "^${version}",
     "@ultimat3/schema": "^${version}",
+    "@ultimat3/seo": "^${version}",
     "@ultimat3/ui": "^${version}",
     "solid-js": "1.9.14"
   },
@@ -121,11 +123,13 @@ const envDeclaration = (): string => `${envSchemaSource()}
 export const env = defineEnv(envSchema);`;
 
 /**
- * No `installPrompt`. `PwaConfig` declares it, `defineConfig` defaults it, and NO file reads it —
- * `packages/core/src/config.ts` carries the marker saying so. Scaffolding it wrote a switch with
- * no wire into every generated app, and the note belongs HERE rather than in the emitted file: an
- * app author has no use for a comment about a framework key their config does not name. Deleting
- * the key itself is core's edit; not writing it is this template's half.
+ * No `installPrompt`, no `afterSignInPath`, no `modelEnv`. All three were declared by
+ * `defineConfig`, defaulted by it, and read by NO file; all three are DELETED from
+ * `packages/core/src/config.ts` as of 2026-08-22, whose header now records the removal rather than
+ * the marker this comment used to cite. So scaffolding one is no longer a switch with no wire — it
+ * is `TS2353` in the generated app's first `x verify`. The note belongs HERE rather than in the
+ * emitted file: an app author has no use for a comment about keys their config does not name.
+ * `scaffold-config.test.ts` is what keeps them from growing back.
  */
 const appConfig = (
   app: NameSet,
@@ -164,10 +168,34 @@ export const config = defineConfig({
 // otherwise fail `lint` on a file no author typed and `x db gen` would rewrite anyway.
 // `preset`, not `recommended`: the older key is deprecated from 2.5 on and every `bun run lint`
 // in the scaffolded app printed the migration notice for a config the app never wrote by hand.
+//
+// `!**/.x` is the one that makes the app's fix chain terminate. `x build` writes MINIFIED island
+// bundles to `.x/static/islands/<name>-<contenthash>.js`; without the exclusion `lint` reported
+// ~175 `noCommaOperator`/`noAssignInExpressions` errors in Bun's own output, and the `fix:` for
+// that step — `biome check --write .` — still exits 1, so `x verify` was red forever on a pristine
+// scaffold the moment `x build` ran (which the `budgets` step's own `fix:` tells the author to do).
+// `--unsafe` was worse: it REWROTE a content-hashed chunk in place, 55,499 → 83,605 bytes, so the
+// name no longer matched the bytes and `.x/build-stats.json` no longer matched the artifact.
+// `--no-example` hid it, because an app with no island has nothing under `.x/static/islands`.
+//
+// `vcs.useIgnoreFile` is the second half and not a duplicate of the first: it makes every future
+// generated directory the app adds to `.gitignore` excluded by the act of ignoring it, rather than
+// by an edit to this file nobody will remember to make. It needs `.gitignore` to EXIST — Biome
+// exits 1 with `couldn't find an ignore file` when it does not — which `x new` writes, and which
+// is why the two are declared together rather than one of them alone.
 const biome = (): string => `{
   "$schema": "https://biomejs.dev/schemas/${BIOME_VERSION}/schema.json",
+  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
   "files": {
-    "includes": ["**", "!**/migrations", "!x.manifest.json", "!openapi.json"]
+    "includes": [
+      "**",
+      "!**/.x",
+      "!**/dist",
+      "!**/.output",
+      "!**/migrations",
+      "!x.manifest.json",
+      "!openapi.json"
+    ]
   },
   "formatter": { "indentStyle": "space", "indentWidth": 2, "lineWidth": 100 },
   "linter": {
@@ -304,6 +332,9 @@ export function repoFiles(
     // One call per workspace package, in write order. Each owns its own files (`scaffold-i18n.ts`
     // already did), so this list stays a table of contents rather than a second copy of every
     // package's contents.
+    // The app's own conventions, as build errors. Not a package — `guards/` sits at the repo root
+    // because the gate discovers it there, and every rule it holds is about the whole app.
+    ...scaffoldGuardFiles(),
     ...domainPackageFiles(app),
     ...dbPackageFiles(app, example),
     ...i18nFiles(app, version),

package/src/test-select.ts

@@ -2,12 +2,13 @@
 // validation behind the type positional and `--sample`. Selection only — nothing here splits a
 // shard or spawns a process, so a wrong file list is always this file's bug and never a race.
 
+import { join } from 'node:path';
 // Bun ships no equivalent: `join` builds the host-separator path from the scan root to a hit.
 // Sizing is Bun's own (`Bun.file().size`), so nothing here reaches for `node:fs`.
-import { join } from 'node:path';
+import { nearestName } from '@ultimat3/core';
 import { BadFlagError } from './errors';
 import type { ParsedArgs } from './parse';
-import { flagString, nearest } from './parse';
+import { flagString } from './parse';
 import type { TestType } from './verify-tests';
 import { ownerOf, TEST_TYPES } from './verify-tests';
 
@@ -103,7 +104,7 @@ export function readType(raw: string | undefined): TestType | undefined {
   if (raw === undefined) return undefined;
   const known: readonly string[] = TEST_TYPES;
   if (known.includes(raw)) return raw as TestType;
-  const suggestion = nearest(raw, known);
+  const suggestion = nearestName(raw, known);
   throw new BadFlagError({
     flag: 'type',
     command: 'test',

package/src/test-shards.ts

@@ -3,6 +3,7 @@
 // cmd-test.ts because a printed reproduction is only true if it carries every input to the split —
 // that rule is this file's, and argv parsing is that one's.
 
+import type { AffectedSelection } from './affected';
 import { docsFor } from './error-codes';
 import type { Runner } from './exec';
 import { execOutput } from './exec';
@@ -72,12 +73,18 @@ export interface ReproduceOptions {
   readonly type?: TestType;
   /** Files `--sample` kept, so the rerun samples the same corpus instead of the whole type. */
   readonly sample?: number;
+  /**
+   * The `--affected` narrowing, when there was one. The fourth input to the split and the one most
+   * easily forgotten: `--affected` decides which files exist to shard at all, so a rerun without it
+   * re-splits the WHOLE corpus and its shard 2 is a different shard 2.
+   */
+  readonly affected?: AffectedSelection;
 }
 
 /**
- * Every input to the split, printed back. The type and `--filter` decide which files exist to
- * shard, `--sample` decides how many of them survive, `--workers` decides the bins — drop any one
- * and the command still runs, over a different file set, which reproduces nothing.
+ * Every input to the split, printed back. The type, `--filter` and `--affected` decide which files
+ * exist to shard, `--sample` decides how many of them survive, `--workers` decides the bins — drop
+ * any one and the command still runs, over a different file set, which reproduces nothing.
  */
 export function reproduceFor(shard: Shard, options: ReproduceOptions): string {
   return [
@@ -85,6 +92,12 @@ export function reproduceFor(shard: Shard, options: ReproduceOptions): string {
     ...(options.type === undefined ? [] : [quoteArg(options.type)]),
     ...(options.filter === undefined ? [] : ['--filter', quoteArg(options.filter)]),
     ...(options.sample === undefined ? [] : ['--sample', String(options.sample)]),
+    // `--base` is emitted always rather than only when non-default: the default is `main`, and a
+    // rerun days later against a moved `main` is a different diff wearing the same flag.
+    ...(options.affected === undefined
+      ? []
+      : ['--affected', '--base', quoteArg(options.affected.base)]),
+    ...(options.affected?.dirty === true ? ['--dirty'] : []),
     '--workers',
     String(options.workers),
     '--worker',
@@ -107,6 +120,8 @@ export interface RunShardsOptions {
    * shard of the sample and would otherwise report that shard's size as the corpus.
    */
   readonly sample?: { readonly kept: number; readonly total: number };
+  /** Passed straight to `reproduceFor`: see `ReproduceOptions.affected`. */
+  readonly affected?: AffectedSelection;
 }
 
 /** The reproduction's inputs, resolved once: `workers` is the split's real width, not the ask. */
@@ -115,6 +130,7 @@ const planOf = (options: RunShardsOptions, workers: number): ReproduceOptions =>
   ...(options.filter === undefined ? {} : { filter: options.filter }),
   ...(options.type === undefined ? {} : { type: options.type }),
   ...(options.sample === undefined ? {} : { sample: options.sample.kept }),
+  ...(options.affected === undefined ? {} : { affected: options.affected }),
 });
 
 const failureOf = (shard: Shard, code: number, plan: ReproduceOptions): Finding => ({

package/src/verify-checks.ts

@@ -35,6 +35,7 @@ import type { VerifyStep } from './verify-step';
 import { fromExec, fromFindings, hostFindings } from './verify-step';
 import { TEST_STEPS } from './verify-tests';
 import { checkFileSizes, checkPackageShape, hasWorkspacePackages } from './workspace-checks';
+import { checkWorkspaceDependencies } from './workspace-graph';
 
 /** The one file that makes the `roadmap` step answerable, and therefore what `applies` reads. */
 const ROADMAP_FILE = join('docs', 'idea', '14-roadmap.md');
@@ -100,7 +101,16 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     name: 'package-shape',
     summary: 'every package ships the same contract files',
     applies: (ctx) => hasWorkspacePackages(ctx.root),
-    run: async (ctx) => fromFindings(await checkPackageShape(ctx.root)),
+    // The dependency rule rides here rather than becoming a twentieth step because it is this
+    // step's own question — what does a workspace owe the repo it lives in? — asked of the
+    // manifest's `dependencies` instead of its `files`. It is deliberately NOT inside
+    // `checkPackageShape`: `scripts/release.ts --check` calls that one to ask whether the tree is
+    // at the version a tag claims, and an undeclared import is not that question.
+    run: async (ctx) =>
+      fromFindings([
+        ...(await checkPackageShape(ctx.root)),
+        ...(await checkWorkspaceDependencies(ctx.root)),
+      ]),
   },
   {
     name: 'errors',

package/src/verify-run.ts

@@ -16,6 +16,10 @@ import type { StepOutcome, VerifyContext, VerifyStep } from './verify-step';
 /**
  * Run every step in order, never bailing early: an agent fixing three things at once needs all
  * three findings from one run, not one per round-trip.
+ *
+ * `ctx.only` narrows the list to one step. The narrowing lives HERE rather than in `cmd-verify.ts`
+ * so that every caller of the runner — the command, `x build`, the MCP host — gets the banner and
+ * the `--json` flag with it, instead of one of them filtering a list quietly.
  */
 export async function runVerify(
   steps: readonly VerifyStep[],
@@ -23,7 +27,8 @@ export async function runVerify(
 ): Promise<CommandResult> {
   const floor = await readVerifyFloor(ctx.root);
   const results: StepResult[] = [];
-  for (const step of steps) {
+  const selected = ctx.only === undefined ? steps : steps.filter((step) => step.name === ctx.only);
+  for (const step of selected) {
     const applies = step.applies === undefined ? true : await step.applies(ctx);
     if (!applies) {
       // A skip this repo already ruled out is not a skip. The step ran here before — the floor is
@@ -67,14 +72,31 @@ export async function runVerify(
   const failedSteps = results.filter((step) => !step.ok).map((step) => step.name);
   const skippedSteps = results.filter((step) => step.skipped === true).map((step) => step.name);
   const totalMs = results.reduce((sum, step) => sum + step.durationMs, 0);
+  const summary = verifySummary({
+    results,
+    failed: failedSteps,
+    skipped: skippedSteps,
+    totalMs,
+  });
   return {
     ok: failedSteps.length === 0,
     command: 'verify',
-    summary: verifySummary({ results, failed: failedSteps, skipped: skippedSteps, totalMs }),
+    // Rendered through the catalog like every other summary this file emits; the machine marker
+    // is `data.notAGateRun` below. It was a bare `NOT A GATE RUN` constant, which put one
+    // user-facing string outside `messages.ts` for a fact `--json` was already carrying twice.
+    summary: ctx.only === undefined ? summary : msg('cli.verify.notAGateRun', { summary }),
     steps: results,
     // `skipped` is a list beside `failed` and not a count, because the two answer the same kind of
     // question — *which* steps, not how many — and a caller ratcheting on coverage needs the names.
-    data: { failed: failedSteps, skipped: skippedSteps, durationMs: totalMs },
+    data: {
+      failed: failedSteps,
+      skipped: skippedSteps,
+      durationMs: totalMs,
+      // A BOOLEAN beside the banner, so a reader of `--json` never has to substring-match a
+      // summary line to learn that this run checked one thing.
+      ...(ctx.only === undefined ? {} : { notAGateRun: true, only: ctx.only }),
+    },
+    // The step's own status: one step, so `failedSteps` is that step and nothing else.
     exitCode: failedSteps.length === 0 ? 0 : 1,
   };
 }

package/src/verify-step.ts

@@ -59,10 +59,19 @@ export interface VerifyContext {
   readonly hostChecks?: Partial<Record<VerifyStepName, HostCheck>>;
   /**
    * How wide the parallel test steps go. Absent means `defaultWorkers()` — a knob, never a
-   * narrowing: no value of it changes which steps run or what "green" means, which is why this is
-   * the only flag `x verify` accepts beyond the global ones.
+   * narrowing: no value of it changes which steps run or what "green" means.
    */
   readonly workers?: number;
+  /**
+   * ONE step, by name — an iteration loop, and the one thing here that IS a narrowing. Every
+   * iteration of the whole gate costs ~18s (14s of it `tsc -b`), which is the cost of asking a
+   * question about one step. It does not weaken axiom 5, and the two rules that keep it honest are
+   * mechanical rather than remembered: a run with this set prints `NOT A GATE RUN` in the summary
+   * AND carries `notAGateRun` in `--json` (`verify-run.ts`), so no reader of either can mistake it
+   * for the gate; and nothing writes `x.verify.json`, so the suite floor cannot be lowered by a
+   * run that never executed the suites. Green still means the no-flag run, unchanged.
+   */
+  readonly only?: VerifyStepName;
 }
 
 export interface StepOutcome {