@ultimat3/cli 1.2.0 → 2.0.0

package/src/verify-tests.ts

@@ -1,7 +1,7 @@
-// One `bun test` invocation per test type, so every type reports on its own line of the gate. A
-// test's type is its filename suffix — `*.contract.test.ts`, `*.live.test.ts`, `*.job.test.ts`,
-// `*.e2e.test.ts` (or any file under an `e2e/` directory), `*.eval.test.ts`. Everything else is a
-// unit test, which is why the unit step is the only one that selects by exclusion.
+// One gate step per test type, so every type reports on its own line. A test's type is its
+// filename suffix — `*.contract.test.ts`, `*.live.test.ts`, `*.job.test.ts`, `*.e2e.test.ts`,
+// `*.eval.test.ts` — and only then the `e2e/` directory it sits in, which is why `OWNERSHIP` below
+// is an ordered list. Everything else is a unit test, the only step that selects by exclusion.
 //
 // `eval` carries one rule beyond its suite — every prompt must have an eval — so it is the only
 // step here that can fail with no test file of its own.
@@ -12,67 +12,131 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { checkEvalBaselines, checkEvalCoverage, checkEvalRecording } from './app-evals';
 import { APP_CONFIG_FILE } from './app-root';
+import { countsOf } from './test-counts';
+import type { TestFile } from './test-select';
+import { discoverTests } from './test-select';
+import { defaultWorkers } from './test-workers';
 import type { StepOutcome, VerifyContext, VerifyStep } from './verify-step';
 import { fromExec, fromFindings } from './verify-step';
+import { runParallel } from './verify-test-run';
 
 export const TEST_TYPES = ['unit', 'contract', 'live', 'job', 'e2e', 'eval'] as const;
 
 export type TestType = (typeof TEST_TYPES)[number];
 
-interface TestSuite {
-  readonly summary: string;
-  /** Substring `bun test` matches against each file path. */
-  readonly filter: string;
-  /** Globs that decide whether this type exists here at all. */
-  readonly globs: readonly string[];
-}
+type TypedTest = Exclude<TestType, 'unit'>;
 
 const TYPED_SUFFIXES = '{contract,live,job,e2e,eval}';
 
-const SUITES: Readonly<Record<Exclude<TestType, 'unit'>, TestSuite>> = {
-  contract: {
-    summary: 'action/query schemas, policy denials, emitted OpenAPI and MCP shapes',
-    filter: '.contract.test.',
-    globs: ['**/*.contract.test.{ts,tsx}'],
-  },
-  live: {
-    summary: 'live-query snapshots, incremental patches, reconnect deltas',
-    filter: '.live.test.',
-    globs: ['**/*.live.test.{ts,tsx}'],
-  },
-  job: {
-    summary: 'step replay, idempotency dedupe, retry/backoff, outbox atomicity',
-    filter: '.job.test.',
-    globs: ['**/*.job.test.{ts,tsx}'],
-  },
-  e2e: {
-    summary: 'the built output, incl. offline and SW update',
-    filter: 'e2e',
-    globs: ['**/*.e2e.test.{ts,tsx}', '**/e2e/**/*.test.{ts,tsx}'],
-  },
-  eval: {
-    summary: 'LLM output scored against thresholds',
-    filter: '.eval.test.',
-    globs: ['**/*.eval.test.{ts,tsx}'],
-  },
+const SUMMARIES: Readonly<Record<TypedTest, string>> = {
+  contract: 'action/query schemas, policy denials, emitted OpenAPI and MCP shapes',
+  live: 'live-query snapshots, incremental patches, reconnect deltas',
+  job: 'step replay, idempotency dedupe, retry/backoff, outbox atomicity',
+  e2e: 'the built output, incl. offline and SW update',
+  eval: 'LLM output scored against thresholds',
 };
 
 /**
- * Build output, and nested projects that carry their own `x verify`. `examples/**` is the second
- * kind: the reference app is gated by its own run of this same step list, so collecting it here
- * would report one app failure on two different gates. The patterns are relative to the run's
- * root, so this excludes nothing when the app itself is the root.
+ * Every rule that decides a file's type, MOST SPECIFIC FIRST: the first entry a path matches owns
+ * it, and no later entry may claim it. Each is a substring `bun test` matches against a file path,
+ * which is exactly how bun reads more than one positional filter (measured: `.contract.test.` +
+ * `.job.test.` runs the union of both suites, never the intersection).
+ *
+ * A FILENAME declares a type; a DIRECTORY only fills in for a filename that declares none — which
+ * is why the one directory rule is last. Ownership had no order at all until 2026-08, so
+ * `packages/app/e2e/payment.contract.test.ts` matched `.contract.test.` AND `e2e/`: the `contract`
+ * step selected it by name while the `e2e` step's argv selected it by directory, and one test ran
+ * twice in one gate. The bare word `e2e` was worse still — it matched any path holding those three
+ * characters anywhere, so `src/e2e-helpers.test.ts` joined the e2e step and left the unit step,
+ * which selects by exclusion.
+ */
+const OWNERSHIP = [
+  ['contract', '.contract.test.'],
+  ['live', '.live.test.'],
+  ['job', '.job.test.'],
+  ['e2e', '.e2e.test.'],
+  ['eval', '.eval.test.'],
+  // `e2e/`, not `/e2e/`: bun matches a filter against the cwd-relative path and answers
+  // `Test filter "/e2e/" had no matches` for the anchored form (bun 1.3.14). The trailing slash
+  // is the boundary this can express, and it is the same string `ownerOf` ranks last, so the
+  // step's argv and the file list can never disagree about what an e2e test is.
+  ['e2e', 'e2e/'],
+] as const satisfies readonly (readonly [TypedTest, string])[];
+
+/** The types whose filename rule outranks the `e2e/` directory — e2e's own never does. */
+const OUTRANKING_E2E: readonly TypedTest[] = [
+  ...new Set(OWNERSHIP.filter(([type]) => type !== 'e2e').map(([type]) => type)),
+];
+
+/**
+ * The one suite a path belongs to, and `unit` when no rule claims it — the single definition of a
+ * file's type, which both `x test <type>` and the gate's own steps select through. Exactly one
+ * owner is the point: two owners is a file two steps run, and a test that runs twice in one gate
+ * proves nothing the first run did not.
+ */
+export const ownerOf = (path: string): TestType =>
+  OWNERSHIP.find(([, filter]) => path.includes(filter))?.[0] ?? 'unit';
+
+/**
+ * Paths a suite's own filters match but the suite does NOT own, as `--path-ignore-patterns`. Only
+ * `e2e` has any, for the reason above. It has to be said in the argv and not only in `ownerOf`:
+ * bun has no "match this and not that" filter, and a serial step runs the argv rather than a file
+ * list — so exclusivity that lived only in the file list would still have run the file twice.
+ */
+const disownedBy = (type: TypedTest): readonly string[] =>
+  type === 'e2e' ? [`**/e2e/**/*.{${OUTRANKING_E2E.join(',')}}.test.*`] : [];
+
+/**
+ * Which types run across worker processes, and why the other two cannot.
+ *
+ * Parallel is safe when the only thing a test file shares with another file is the database, and
+ * the database is per worker by construction (`ULTIMATE_TEST_WORKER` → one clone of the migrated
+ * template, `@ultimat3/testing`'s `acquireWorkerDatabase`). Every other process-global in this
+ * framework — the permission set, the roles, the entity/action/query registries, the error-code
+ * titles, the fixture bag — is handled by `--isolate` giving each FILE its own module registry.
+ *
+ * | Type | Why |
+ * |---|---|
+ * | `live` | **serial.** A logical replication slot and a publication are named at the Postgres
+ * CLUSTER level, not inside a database, and this repo's own feed tests hard-code
+ * `x_live_slot` / `x_live_pub` against `TEST_REPLICATION_URL` — the one server, never a per-worker
+ * clone. Two workers would race `pg_create_logical_replication_slot` and the loser's failure would
+ * read as a flake. A per-worker database does not isolate a cluster-wide object |
+ * | `e2e` | **serial.** It runs against the *built output*: one `dist/`, one service-worker
+ * registration, one browser profile. There is nothing per-worker to hand it, and the type is
+ * seconds at most, so a split would buy a race and no time |
+ *
+ * The two are named here rather than tested for, because "can this type be sharded?" is a design
+ * fact about the type, not something a run can discover about itself.
  */
-const NEVER_A_TEST = ['**/dist/**', '**/build/**', '**/examples/**'];
+export const SERIAL_TYPES: readonly TestType[] = ['live', 'e2e'];
+
+const isSerial = (type: TestType): boolean => SERIAL_TYPES.includes(type);
+
+/**
+ * Build output, and nested projects that carry their own `x verify`. `examples/**` and
+ * `dummy/**` are the second kind: each holds a whole app gated by its own run of this same step
+ * list, so collecting them here would report one app failure on two different gates. The patterns
+ * are relative to the run's root, so this excludes nothing when the app itself is the root.
+ *
+ * `dummy/**` was added after the framework gate started running a demo app's tests and disagreeing
+ * with `bun run test` — which already excluded it — for no reason a reader could see.
+ *
+ * Excluded here is not ungated: `scripts/reference-app-gate.ts` runs `x verify` inside each of
+ * those apps and blocks on a per-app ratchet. Until 2026-08 that was only true of `examples/**`,
+ * and `dummy/social-media-clone` was excluded by this list and gated by nothing.
+ */
+const NEVER_A_TEST = ['**/dist/**', '**/build/**', '**/examples/**', '**/dummy/**'];
 
 const ignoreFlags = (patterns: readonly string[]): readonly string[] =>
   patterns.map((pattern) => `--path-ignore-patterns=${pattern}`);
 
 /**
- * The substring that decides a file's type — the same one the step's `bun test` runs with, so
+ * The substrings that decide a file's type — the same ones the step's `bun test` runs with, so
  * `x test <type>` and the gate's `<type>` step can never disagree about what a contract test is.
  */
-export const typeFilterOf = (type: Exclude<TestType, 'unit'>): string => SUITES[type].filter;
+export const typeFiltersOf = (type: Exclude<TestType, 'unit'>): readonly string[] =>
+  OWNERSHIP.filter(([owner]) => owner === type).map(([, filter]) => filter);
 
 /** Unit is everything the typed suites do not claim, so no test can fall between two steps. */
 export const testStepCommand = (type: TestType): readonly string[] =>
@@ -82,34 +146,60 @@ export const testStepCommand = (type: TestType): readonly string[] =>
         'test',
         ...ignoreFlags([...NEVER_A_TEST, '**/e2e/**', `**/*.${TYPED_SUFFIXES}.test.*`]),
       ]
-    : ['bun', 'test', ...ignoreFlags(NEVER_A_TEST), SUITES[type].filter];
+    : [
+        'bun',
+        'test',
+        ...ignoreFlags([...NEVER_A_TEST, ...disownedBy(type)]),
+        ...typeFiltersOf(type),
+      ];
 
 /**
- * Whether a step applies has to be decided by the same rule that decides what it runs. When the
- * two drifted, a suite that lived only under an ignored path made its step apply and then fail
- * with "no test files matched" — a red gate reporting a suite that, by its own rule, is not here.
+ * Whether a step applies and what it runs are now one question with one answer: the file list.
+ * They used to be two — a glob for `applies`, `--path-ignore-patterns` for the run — and when they
+ * drifted, a suite that lived only under an ignored path made its step apply and then fail with
+ * "no test files matched", a red gate reporting a suite that by its own rule is not here.
+ *
+ * Memoized because `runVerify` asks `applies` and then `run`, and a repeated walk of the whole
+ * tree per type is the cost this change exists to remove.
  */
-const NEVER_A_TEST_GLOBS = NEVER_A_TEST.map((pattern) => new Bun.Glob(pattern));
+const discovered = new Map<string, readonly TestFile[]>();
+
+const filesFor = async (root: string, type: TestType): Promise<readonly TestFile[]> => {
+  const key = `${root}\u0000${type}`;
+  const cached = discovered.get(key);
+  if (cached !== undefined) return cached;
+  const files = await discoverTests(root, undefined, type);
+  discovered.set(key, files);
+  return files;
+};
 
-const ignoredPath = (path: string): boolean =>
-  path.includes('node_modules') || NEVER_A_TEST_GLOBS.some((glob) => glob.match(path));
+/** Test seam: a fixture that writes new test files under a root this process already scanned. */
+export const resetTestDiscovery = (): void => discovered.clear();
 
-const exists = async (root: string, globs: readonly string[]): Promise<boolean> => {
-  for (const pattern of globs) {
-    for await (const path of new Bun.Glob(pattern).scan({ cwd: root, absolute: false })) {
-      if (!ignoredPath(path)) return true;
-    }
-  }
-  return false;
+const runSerial = async (ctx: VerifyContext, type: TestType): Promise<StepOutcome> => {
+  const command = testStepCommand(type);
+  const result = await ctx.runner(command, { cwd: ctx.root });
+  return {
+    ...fromExec(result, {
+      code: 'X_TEST_FAILED',
+      cause: `one or more ${type} tests failed`,
+      fix: command.join(' '),
+    }),
+    workers: 1,
+    tests: countsOf([result]),
+  };
 };
 
 const runType = async (ctx: VerifyContext, type: TestType): Promise<StepOutcome> => {
-  const command = testStepCommand(type);
-  const result = await ctx.runner(command, { cwd: ctx.root });
-  return fromExec(result, {
-    code: 'X_TEST_FAILED',
-    cause: `one or more ${type} tests failed`,
-    fix: command.join(' '),
+  if (isSerial(type)) return runSerial(ctx, type);
+  const files = await filesFor(ctx.root, type);
+  if (files.length === 0) return runSerial(ctx, type);
+  return runParallel({
+    root: ctx.root,
+    runner: ctx.runner,
+    files,
+    workers: ctx.workers ?? defaultWorkers(),
+    type,
   });
 };
 
@@ -123,8 +213,8 @@ const isApp = (root: string): boolean => existsSync(join(root, APP_CONFIG_FILE))
  */
 const evalStep: VerifyStep = {
   name: 'eval',
-  summary: SUITES.eval.summary,
-  applies: async (ctx) => isApp(ctx.root) || (await exists(ctx.root, SUITES.eval.globs)),
+  summary: SUMMARIES.eval,
+  applies: async (ctx) => isApp(ctx.root) || (await filesFor(ctx.root, 'eval')).length > 0,
   async run(ctx) {
     // First, and instead of the suite: under recording every eval writes the numbers it just
     // measured and passes, so running it here would rewrite the committed baselines during the
@@ -134,12 +224,12 @@ const evalStep: VerifyStep = {
     const declarations = isApp(ctx.root)
       ? [...(await checkEvalCoverage(ctx.root)), ...(await checkEvalBaselines(ctx.root))]
       : [];
-    if (!(await exists(ctx.root, SUITES.eval.globs))) return fromFindings(declarations);
+    if ((await filesFor(ctx.root, 'eval')).length === 0) return fromFindings(declarations);
     const suite = await runType(ctx, 'eval');
     return {
+      ...suite,
       ok: suite.ok && declarations.length === 0,
       findings: [...declarations, ...suite.findings],
-      ...(suite.output === undefined ? {} : { output: suite.output }),
     };
   },
 };
@@ -153,11 +243,10 @@ const stepFor = (type: TestType): VerifyStep => {
     };
   }
   if (type === 'eval') return evalStep;
-  const suite = SUITES[type];
   return {
     name: type,
-    summary: suite.summary,
-    applies: (ctx) => exists(ctx.root, suite.globs),
+    summary: SUMMARIES[type],
+    applies: async (ctx) => (await filesFor(ctx.root, type)).length > 0,
     run: (ctx) => runType(ctx, type),
   };
 };

package/src/version-loader.ts

@@ -5,12 +5,29 @@
 // Bun has no path-join primitive; `import.meta.dir` is this module's directory in both the
 // checked-out `src/` layout and the published `dist/` one, each one level below the package root.
 import { resolve } from 'node:path';
-import { readPackageVersion } from '@ultimat3/core';
+import { resolveVersion } from '@ultimat3/core';
 
 /** `@ultimat3/cli`'s own manifest — released in lockstep with the rest of `@ultimat3/*`. */
 export const CLI_MANIFEST = resolve(import.meta.dir, '..', 'package.json');
 
-/** Throws `X_INVARIANT` if this package shipped without a version — see `readPackageVersion`. */
+// Replaced with a string literal by `bun build --define ULTIMATE_FRAMEWORK_VERSION='"1.2.3"'`
+// (`binaryArgs` in `cmd-build.ts`), and declared by nothing at runtime — hence the `typeof` guard
+// below. An unbundled process must see `undefined` here, not a `ReferenceError`.
+declare const ULTIMATE_FRAMEWORK_VERSION: string | undefined;
+
+/**
+ * Manifest first, build define second — the same fallback `frameworkVersion()` takes, through the
+ * same `resolveVersion`, off deliberately the same define. A compiled single-file executable
+ * carries no `package.json`, so without the fallback `x --version` inside one answers `X_INVARIANT`
+ * for a version the build already knew; and a second define name would be a second version fact to
+ * hold in step, when `@ultimat3/cli` and `@ultimat3/core` ship one version, one commit, one tag.
+ *
+ * Throws `X_INVARIANT` if neither source answers — a publish with no version, or a `--compile` that
+ * skipped the define. See `resolveVersion`.
+ */
 export function loadVersion(): string {
-  return readPackageVersion(CLI_MANIFEST);
+  return resolveVersion(
+    CLI_MANIFEST,
+    typeof ULTIMATE_FRAMEWORK_VERSION === 'string' ? ULTIMATE_FRAMEWORK_VERSION : undefined,
+  );
 }

package/src/workspace-checks.ts

@@ -1,12 +1,14 @@
-// Three shape rules the gate owns: one file, one job (a hard line ceiling), every workspace
-// package shipping the same contract files, and every published package's tarball matching what
-// its manifest promises. All report findings — a shape rule that is only written down is not a
-// rule (axiom 3).
+// Four shape rules the gate owns: one file, one job (a hard line ceiling), every workspace
+// package shipping the same contract files, every published package's tarball matching what its
+// manifest promises, and every published package being in the root build graph. All report
+// findings — a shape rule that is only written down is not a rule (axiom 3).
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { renderCauseValue } from '@ultimat3/core';
 import type { Finding } from './output';
-import { eachSourceFile } from './source-files';
+import { eachSourceFile, isGenerated } from './source-files';
+import { checkRootReferences } from './tsconfig-references';
 
 export const LINE_CEILING = 500;
 
@@ -34,6 +36,7 @@ export const countLines = (text: string): number =>
 export async function checkFileSizes(root: string): Promise<readonly Finding[]> {
   const findings: Finding[] = [];
   for await (const path of eachSourceFile(root)) {
+    if (isGenerated(path)) continue;
     const lines = countLines(await Bun.file(join(root, path)).text());
     if (lines > LINE_CEILING) findings.push(tooLongFinding(path, lines));
   }
@@ -52,7 +55,7 @@ export const missingFileFinding = (dir: string, file: string, scaffolder: boolea
 
 /**
  * A published package reports its own version by reading its own `package.json` at runtime
- * (`@ultimat3/core`'s `FRAMEWORK_VERSION`, the CLI's `CLI_VERSION`, every dependency `x new` pins).
+ * (`@ultimat3/core`'s `frameworkVersion()`, the CLI's `loadVersion()`, every dependency `x new` pins).
  * A manifest with no semver `version` therefore breaks the MCP handshake and every scaffold — so
  * the gate refuses the publish here, where the fix is one line, rather than at someone's install.
  */
@@ -60,7 +63,10 @@ export const SEMVER = /^\d+\.\d+\.\d+(?:[-+][\w.-]+)*$/;
 
 export const badVersionFinding = (dir: string, found: unknown): Finding => ({
   code: 'X_PACKAGE_SHAPE',
-  cause: `packages/${dir}/package.json has no semver "version" (found ${JSON.stringify(found)})`,
+  // `found` is whatever the manifest's `version` parsed to — an app's JSON, not the gate's value.
+  // Bare `JSON.stringify` throws on a bigint and a cycle and runs any `toJSON`, which would replace
+  // this finding with a TypeError from inside the gate.
+  cause: `packages/${dir}/package.json has no semver "version" (found ${renderCauseValue(found)})`,
   fix: `set a semver "version" in packages/${dir}/package.json, then: bun run verify`,
   docs: docs('X_PACKAGE_SHAPE'),
   at: `packages/${dir}/package.json`,
@@ -124,19 +130,27 @@ export const pinSkewFinding = (
  * Private packages are exempt on both counts: a generated app's `packages/*` are private, carry
  * their own version line and depend on the framework by caret range.
  */
-export function checkLockstep(manifests: readonly ManifestFacts[]): readonly Finding[] {
+export function checkLockstep(
+  manifests: readonly ManifestFacts[],
+  release?: string,
+): readonly Finding[] {
   const published = manifests.filter((manifest) => !manifest.private);
   // `core` is tier 0 and everything depends on it, so it is the version the rest must match.
-  const anchor = published.find((manifest) => manifest.dir === 'core') ?? published[0];
-  if (anchor === undefined) return [];
+  const internal = published.find((manifest) => manifest.dir === 'core') ?? published[0];
+  // With a release version the anchor is EXTERNAL, and that is the whole point: comparing packages
+  // only to each other is green in a repo where all 29 sit at 1.2.0 and nine tags (v1.3.0 …
+  // v1.10.1) have been cut with no bump — a publish that dies `EPUBLISHCONFLICT` on all 29 while
+  // the gate says shippable. There is no anchor to the version being released unless one is given.
+  const version = release ?? internal?.version;
+  if (version === undefined) return [];
   const findings: Finding[] = [];
   for (const manifest of published) {
-    if (manifest.version !== anchor.version) {
-      findings.push(versionSkewFinding(manifest.dir, manifest.version, anchor.version));
+    if (manifest.version !== version) {
+      findings.push(versionSkewFinding(manifest.dir, manifest.version, version));
     }
     for (const [dep, range] of manifest.frameworkDeps) {
-      if (range !== anchor.version) {
-        findings.push(pinSkewFinding(manifest.dir, dep, range, anchor.version));
+      if (range !== version) {
+        findings.push(pinSkewFinding(manifest.dir, dep, range, version));
       }
     }
   }
@@ -165,6 +179,27 @@ export const publishesTestsFinding = (dir: string): Finding => ({
   at: `packages/${dir}/package.json`,
 });
 
+/**
+ * Emit that is authored source anyway, so the sweep may not take it. One list, read by the check
+ * and written into the `fix:` that performs it — a second spelling is a command that deletes a file
+ * the gate then reports as missing.
+ */
+export const ARTIFACT_ALLOWLIST: readonly string[] = ['packages/ui/src/scss.d.ts'];
+
+/** `-name` matches the same suffixes the check globs; `! -path` spares each allowlisted file. */
+const SWEEP_PREDICATE = [
+  `\\( -name '*.d.ts' -o -name '*.js' -o -name '*.map' \\)`,
+  ...ARTIFACT_ALLOWLIST.map((path) => `! -path '${path}'`),
+].join(' ');
+
+export const buildArtifactsFinding = (dir: string, count: number): Finding => ({
+  code: 'X_PACKAGE_SHAPE',
+  cause: `packages/${dir}/src/ contains ${count} build artifacts (.d.ts, .js, .map files)`,
+  fix: `find packages/${dir}/src ${SWEEP_PREDICATE} -delete`,
+  docs: docs('X_PACKAGE_SHAPE'),
+  at: `packages/${dir}/src/`,
+});
+
 /**
  * Reported apart from the exclusion above so the `fix:` stays runnable. Told to "add an entry to
  * `files`" when there is no `files` at all, an author edits a key that is not there — and axiom 4
@@ -254,16 +289,40 @@ export async function workspacePackages(root: string): Promise<readonly string[]
 export const hasWorkspacePackages = async (root: string): Promise<boolean> =>
   (await workspacePackages(root)).length > 0;
 
+export interface PackageShapeOptions {
+  /**
+   * The version being released. Anchors the lockstep rule to it instead of to whatever the
+   * packages happen to agree on, which is what lets `scripts/release.ts --check <version>` and the
+   * release workflow ask "is this repo actually at the version this tag claims?" before publishing.
+   */
+  readonly release?: string;
+}
+
 /** Every package ships the same contract files; a missing one is a build error, not a chore. */
-export async function checkPackageShape(root: string): Promise<readonly Finding[]> {
+export async function checkPackageShape(
+  root: string,
+  options: PackageShapeOptions = {},
+): Promise<readonly Finding[]> {
   const scaffolder = existsSync(join(root, 'scripts', 'new-package.ts'));
   const findings: Finding[] = [];
   const facts: ManifestFacts[] = [];
+  const allowlisted = new Set(ARTIFACT_ALLOWLIST);
   for (const dir of await workspacePackages(root)) {
     for (const file of PACKAGE_FILES) {
       if (existsSync(join(root, 'packages', dir, file))) continue;
       findings.push(missingFileFinding(dir, file, scaffolder));
     }
+    // `src/` is authored source only; anything a build emitted there ships in the tarball too.
+    const artifacts: string[] = [];
+    for await (const path of new Bun.Glob('src/**/*.{d.ts,js,map}').scan({
+      cwd: join(root, 'packages', dir),
+      absolute: false,
+    })) {
+      if (!allowlisted.has(join('packages', dir, path))) artifacts.push(path);
+    }
+    if (artifacts.length > 0) {
+      findings.push(buildArtifactsFinding(dir, artifacts.length));
+    }
     const manifest: unknown = await Bun.file(join(root, 'packages', dir, 'package.json')).json();
     const record = (typeof manifest === 'object' && manifest !== null ? manifest : {}) as {
       name?: unknown;
@@ -284,5 +343,17 @@ export async function checkPackageShape(root: string): Promise<readonly Finding[
       files: filesOf(manifest),
     });
   }
-  return [...findings, ...checkLockstep(facts), ...checkPublishShape(root, facts)];
+  return [
+    ...findings,
+    ...checkLockstep(facts, options.release),
+    ...checkPublishShape(root, facts),
+    // Nothing enforced that a workspace joins the root build graph, and `scripts/new-package.ts`
+    // never added one — so a package could ship, be imported, and be typechecked by nothing. It
+    // rides on this step because it is this step's own question: what does a workspace owe the
+    // repo it lives in?
+    ...(await checkRootReferences(
+      root,
+      facts.filter((fact) => !fact.private).map((fact) => fact.dir),
+    )),
+  ];
 }

package/src/write-line.ts

@@ -0,0 +1,34 @@
+// The one stdout write every published entry point uses. Its own module because there are two of
+// them — `packages/cli/src/bin.ts` and `create-ultimate`'s — and the second shipped
+// `process.stdout.write` + `process.exit`, the exact pair the note below exists to rule out.
+
+// `node:fs`, and unavoidable: Bun has no synchronous stdout write of its own.
+import { writeSync } from 'node:fs';
+
+/**
+ * Write to stdout and be certain it arrived, even if the next statement exits the process.
+ *
+ * `process.stdout.write()` is ASYNCHRONOUS whenever stdout is a pipe — which is what it is in CI
+ * and under `| jq`. Anything past the 64KB pipe buffer is queued, and `process.exit()` discards the
+ * queue, so the output silently truncates. A `--json` contract that truncates under a pipe is a
+ * `--json` contract for nobody: the pipe is the only reason it exists.
+ *
+ * The loop is not decoration — one `writeSync` to a pipe may write fewer bytes than it was handed,
+ * and dropping the remainder reintroduces the bug in a harder-to-see form.
+ *
+ * `EAGAIN` is "the pipe is full right now", not a failure. CI hands the process a NON-BLOCKING
+ * stdout, where `writeSync` throws rather than blocking — so the loop that fixed the truncation
+ * took the whole command down on a runner, emitting nothing at all. The reader drains in
+ * microseconds; the retry is the correct response to "would block".
+ */
+export function writeLine(line: string): void {
+  const buffer = Buffer.from(`${line}\n`);
+  let written = 0;
+  while (written < buffer.length) {
+    try {
+      written += writeSync(1, buffer, written, buffer.length - written);
+    } catch (cause) {
+      if ((cause as NodeJS.ErrnoException).code !== 'EAGAIN') throw cause;
+    }
+  }
+}