@ultimat3/cli 6.0.0 → 8.0.0

package/CLAUDE.md

@@ -6,10 +6,12 @@ Tier 5. May import tiers 0–4. Nothing imports this except `create-ultimate`.
 |---|---|
 | Entry | `src/bin.ts` (`#!/usr/bin/env bun`) — argv, stdout, exit code only |
 | stdout | `write-line.ts`'s `writeLine` — synchronous fd 1, never `process.stdout.write`, which truncates at the 64KB pipe buffer when `process.exit` follows. Exported, because `create-ultimate`'s entry point needs the same one |
+| stderr | `write-line.ts`'s `writeErrorLine` — the same loop on fd 2, for a line that is not the command's answer. A `CommandResult` declaring `stream: 'stderr'` is routed there by `dispatch.ts`'s `sinkFor`, and `x mcp serve --transport stdio` is the one case: its fd 1 carries JSON-RPC frames, so the `✓ mcp stdio serving 13 tools` line rendered after the loop was a malformed frame. Neither renderer carries `stream`, exactly like `hold` |
+| Boot logs under `--json` | `dispatch.ts` calls core's `setLogStream('stderr')` when `args.json` is set, once, for all thirty commands. `x db migrate --json` printed the boot logger's `ultimate migrate applied` and then the command's own object, so `json.load` raised on the second document. A server's stdout stays its log stream; this is the CLI process only |
 | Numeric flags | `flag-number.ts` — one reader for `--port` / `--workers` / `--shard`. A bare `Number.parseInt` accepts `4abc` and answers `NaN`, which turned three checks into ones that cannot fail |
 | Shell quoting | `shell-quote.ts`'s `quoteArg` — every value the CLI pastes into a `fix:` or a reproduce line, `exec.ts`'s missing-program refusal and `test-shards.ts`'s reproduce command both. A name holding a space or a `;` interpolated bare is an instruction that runs something else |
 | Missing positionals | `MissingPositionalError`, never `BadFlagError` (names a flag that does not exist) and never `UnknownCommandError` (says a known command form is not one). Its `example` is a REAL invocation — `x g route <name>` in a shell is a redirect |
-| Bare subcommands | `CommandSpec.defaultSubcommand`, **declared**. The parser answered `subcommands[0]` until 1.2.0, so `x db` ran `gen` — the migration GENERATOR — because it sorted first, and `x mcp` started a server. A command with no defensible default declares none and `MissingSubcommandError` refuses the bare form; `parse.test.ts` pins the set at exactly `db` and `mcp`. Its fix is `x help <command>`, never `x <command> --help`: the subcommand is resolved *after* the flag loop, so the latter throws the same error again — a fix line that reproduced its own failure |
+| Bare subcommands | `CommandSpec.defaultSubcommand`, **declared**. The parser answered `subcommands[0]` until 1.2.0, so `x db` ran `gen` — the migration GENERATOR — because it sorted first, and `x mcp` started a server. A command with no defensible default declares none and `MissingSubcommandError` refuses the bare form; `parse.test.ts` pins the set at exactly `db` and `mcp`. Its fix is `x help <command>`. Both forms answer now: `--help` is read off the flag loop and `readSubcommand` is SKIPPED when it is set, so `x db --help`, `x mcp --help` and `x pr --help` print usage instead of exiting 1 with this same refusal — which is what they did on every command taking a subcommand until 2026-08 (`parse.test.ts` pins it across the shipped registry) |
 | Closed flag values | a flag whose values are a closed set is READ through a function that refuses the rest — `cmd-build.ts`'s `readTarget`, `cmd-deploy.ts`'s `readMethod`, `cmd-routes.ts`'s `readSurfaceFilter`, `cmd-mcp.ts`'s `isTransport`. `=== 'helm' ? 'helm' : 'compose'` made `x deploy --method helmm` a COMPOSE deploy reporting `method: "compose"`, and `--surface App` reported `0 routes` and exit 0 — a typo and an empty table rendering identically. The set is the framework's own where one exists (`SURFACES` from `@ultimat3/render`), never a list restated here |
 | App root | `CommandSpec.requiresApp`, **enforced by `dispatch.ts`** before `target.run` — the field's doc said so for 17 commands and nothing read it, so the promise was kept only by each command remembering to call `requireAppRoot` itself. Those 17 calls stay (they hand the command its root, and name subcommands the dispatcher cannot see), but the DECLARATION is what decides, ahead of any check a command makes about its own arguments; `--help` is exempt, because `target` is the help command by then |
 | Result helpers | `command.ts`'s `ok()` / `failed()` write `ok` **after** the `extra` spread: the function's name is the verdict and nothing a caller passes can overturn it. Spread last, `failed('verify', '1 of 19 steps failed', { ok: true })` answered `ok: true` and `exitCodeFor` exited **0** on it — a green CI over a red command (`command.test.ts`) |
@@ -67,6 +69,17 @@ and the `tsc -b` that proves it took. Private packages are exempt (a generated a
 private), and a root that declares **no** `references` array is not judged at all: project
 references are opt-in, and a scaffolded app builds through `extends` + `include`.
 
+`workspace-graph.ts` is `package-shape`'s fifth rule: **every cross-workspace import is declared
+in the importing workspace's own manifest**. Without it a scaffolded repo's dependency graph exists
+only inside `tsc` — imports resolve through the root `tsconfig.json` `paths`, so affected-package
+detection, `bun --filter` ordering and "what breaks if I change this" all read manifests and all
+answer too small a set (issue #239, found in a real app where a change reaching five packages
+reported one). `X_WORKSPACE_DEP_UNDECLARED` names the manifest and the exact line to add. Shipped
+source only: a test file's import is not judged, because `packages/*` here declares no
+`devDependencies` by design and the root's hoist is what resolves them. A manifest the scan cannot
+read is its own finding rather than a silent skip — a skipped workspace is a hiding place for the
+very edge the rule is looking for.
+
 `app-agents-md.ts` is why the `manifest` step declares no `applies` at all. The drift half needs
 a committed `x.manifest.json` to compare against, but `AGENTS.md` is required of every repo the
 gate runs in — so the step always has a question to answer, and gating both halves on the file
@@ -139,6 +152,38 @@ emits a file `defineCatalogs` rejects at the app's first boot. `merge: 'json'` u
 (`json-merge.ts`) for the same reason: `x new` and `x g resource` both contribute under `app`, and
 a shallow spread keeps one of them.
 
+## Three commands that reach outside the process, and none of them is a gate step
+
+`x shot`, `x pr` and `x ci` exist because of the one line in the root `CLAUDE.md` that shapes this
+whole package: **the primary developer is an AI agent.** An agent cannot open a browser, cannot look
+at a running dev server and cannot read the GitHub web UI. It can read a file, and it can run a
+command that prints. These three turn each of those into a file and a print.
+
+They are also the only three commands that need something the process does not have — a browser, a
+network, a GitHub token — which is why **none of them is a step of `x verify`**, and why that is not
+an oversight to be corrected later. A gate that needs a browser goes red for reasons unrelated to the
+change, and CI does not install one.
+
+| | Reaches for | Never |
+|---|---|---|
+| `x shot <route>` | `x dev` on a scratch port, plus the app's own `puppeteer-core` through `@ultimat3/scraping` | the static build — `--target static` prerenders `site/` only, so an `app/` route would photograph the landing page |
+| `x pr review\|resolve\|reply` | `gh api graphql`, through the injected `Runner` | `gh pr view --comments`, which shows *issue* comments and not the line-anchored threads that carry the findings |
+| `x ci` | `gh run view --log-failed`, one call | a per-job log fetch — the run and all its jobs come back together |
+
+**`verdict.json` names its own blind spots, and that is the design.** `x shot` reports what it could
+not observe alongside what it did. A capture tool that silently omits what it cannot see is worse
+than one that says so, because the omission reads as a clean result.
+
+**`x shot` reuses a running `x dev` rather than booting a second one.** Embedded Postgres is
+single-writer, so a second boot is `X_DEV_ALREADY_RUNNING` and no picture is ever taken. A reused
+server's `stop()` deliberately does not clear the other process's lock.
+
+**`gh` is invoked through `ctx.runner`, never `Bun.spawn` directly** — that is what lets every test
+supply a reply table and assert the exact argv with no network and no `gh` installed. `GhOptions.fix`
+is a **required** field, so shelling out to GitHub without stating a remedy is a type error rather
+than a review comment. A GraphQL response is untrusted input and is parsed against a schema, never
+cast: a `null` where an id was expected would otherwise become a mutation against `undefined`.
+
 ## The `errors` step enforces the error contract
 
 | File | Job |
@@ -790,6 +835,18 @@ refuses). A guard returning `[1n]` is `X_GUARD_FINDING_INVALID`, per candidate,
 entry costs its own line and not the real findings beside it. The mechanism whose job is producing
 structured failures handing back a stack trace is the one outcome it exists to prevent.
 
+**`x new` ships four guards, `As of 2026-08-22`.** The scaffolded `AGENTS.md` states nine
+non-negotiables, and five of them used to be prose — each proven green on `x verify`: a hardcoded
+JSX string beside a `t()` call, `color: #ff0000` in a stylesheet whose own scaffolded header called
+it "a lint failure", `toLocaleDateString('en-US')` with no `timeZone`, `t.number` money, and a bare
+`throw new Error` in a repo. Four of the five are now guards the scaffold writes —
+`guard-raw-colour`, `guard-unzoned-date`, `guard-bare-error`, `guard-untranslated-string` — so the
+rule is a build error the day the app is created rather than a sentence an agent may skip. The
+fifth, money-as-float, has **no static signature**; the scaffolded `AGENTS.md` row now points at the
+`MoneyInput` type error that already fires, because shipping a guard that cannot work is worse than
+naming the mechanism that does. Their codes are app codes derived from the guard name, so none of
+them appears in `wiki/Error-Codes.md` or the manifest.
+
 `x g guard <name>` writes `guards/<name>.ts` and its test, and nothing else — no index, no
 registry row, no manifest entry. The emitted rule is the class of failure a guard exists for: a
 migration that adds a `NOT NULL` column with no `DEFAULT` applies cleanly to an empty local
@@ -816,10 +873,13 @@ typechecked there by default; an app whose tsconfig names an explicit `include`
 ## Two generators that scaffold something other than a primitive
 
 `x g island <name> [--at <dir>]` writes a **client entry point**, not a component: the filename is
-how the bundler discovers it and `mount` is how the hydration runtime calls it, so those two are
-what `templates/island.test.ts` pins and everything else in the file is example code. `--at` takes
-the directory directly rather than deriving one, because the caller that cannot guess is
-`X_ISLAND_INVALID` — its cause already holds the exact path a page's `src` resolved to, so its
+how the bundler discovers it and `mount` is how the hydration runtime calls it, so the filename,
+the `mount` export and that `mount` RENDERS are what `templates/island.test.ts` pins — it builds
+the emitted entry with `buildIslands` and drives it with `mountIsland`, so a template that
+typechecks and does not mount is a failing test. It runs the mutation too, rather than describing
+it: the same island with `{count()}` replaced by `{0}` must fail the assertion the live one passes.
+`--at` takes the directory directly rather than deriving one, because the caller that cannot guess
+is `X_ISLAND_INVALID` — its cause already holds the exact path a page's `src` resolved to, so its
 `fix:` hands that path straight back.
 
 `x g admin:page <name> --permission <perm> [--at <dir>]` writes an ordinary TSX component and **no

package/README.md

@@ -53,13 +53,18 @@ x verify --json
 ## `x verify` steps
 
 `typecheck lint boundaries filesize package-shape errors unit contract live job e2e eval drift
-contract-diff budgets manifest roadmap`
+contract-diff budgets seo i18n manifest roadmap`
 
-Seventeen, in cost order, defined once as `VERIFY_STEP_NAMES` (`verify-step.ts`) — the summary
+Nineteen, in cost order, defined once as `VERIFY_STEP_NAMES` (`verify-step.ts`) — the summary
 count above is projected from that list, and the framework repo's own gate (`bun run verify`)
 runs exactly it. A step with nothing to check here reports as skipped, never as
 passed. Never bails early: an agent fixing three things needs all three findings from one run.
-There is no `--only` and no `--skip`; the exit code is non-zero if any step fails.
+
+`--only <step>` runs one step, for an iteration loop — it prints `NOT A GATE RUN` in the human
+summary **and** in `--json` (`data.notAGateRun`), and it writes no floor file. **The gate is this
+command with no flag**, which is what "one command means shippable" means. There is no `--skip`:
+a knob that removes a step from a run that still calls itself the gate is the one thing this
+command must not offer. The exit code is non-zero if any step fails.
 
 A committed `x.verify.json` is the floor, `As of 2026-08`: it names the steps this repo has already
 proved it can run, and a step it names that reports nothing is `X_VERIFY_SUITE_VANISHED` rather

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "6.0.0",
+  "version": "8.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,29 +37,30 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "6.0.0",
-    "@ultimat3/admin": "6.0.0",
-    "@ultimat3/ai": "6.0.0",
-    "@ultimat3/cache": "6.0.0",
-    "@ultimat3/core": "6.0.0",
-    "@ultimat3/db": "6.0.0",
-    "@ultimat3/entity": "6.0.0",
-    "@ultimat3/http": "6.0.0",
-    "@ultimat3/i18n": "6.0.0",
-    "@ultimat3/jobs": "6.0.0",
-    "@ultimat3/mail": "6.0.0",
-    "@ultimat3/manifest": "6.0.0",
-    "@ultimat3/mcp": "6.0.0",
-    "@ultimat3/policy": "6.0.0",
-    "@ultimat3/pwa": "6.0.0",
-    "@ultimat3/query": "6.0.0",
-    "@ultimat3/realtime": "6.0.0",
-    "@ultimat3/render": "6.0.0",
-    "@ultimat3/schema": "6.0.0",
-    "@ultimat3/seo": "6.0.0",
-    "@ultimat3/storage": "6.0.0",
-    "@ultimat3/testing": "6.0.0",
-    "@ultimat3/time": "6.0.0",
+    "@ultimat3/action": "8.0.0",
+    "@ultimat3/admin": "8.0.0",
+    "@ultimat3/ai": "8.0.0",
+    "@ultimat3/cache": "8.0.0",
+    "@ultimat3/core": "8.0.0",
+    "@ultimat3/db": "8.0.0",
+    "@ultimat3/entity": "8.0.0",
+    "@ultimat3/http": "8.0.0",
+    "@ultimat3/i18n": "8.0.0",
+    "@ultimat3/jobs": "8.0.0",
+    "@ultimat3/mail": "8.0.0",
+    "@ultimat3/manifest": "8.0.0",
+    "@ultimat3/mcp": "8.0.0",
+    "@ultimat3/policy": "8.0.0",
+    "@ultimat3/pwa": "8.0.0",
+    "@ultimat3/query": "8.0.0",
+    "@ultimat3/realtime": "8.0.0",
+    "@ultimat3/render": "8.0.0",
+    "@ultimat3/schema": "8.0.0",
+    "@ultimat3/scraping": "8.0.0",
+    "@ultimat3/seo": "8.0.0",
+    "@ultimat3/storage": "8.0.0",
+    "@ultimat3/testing": "8.0.0",
+    "@ultimat3/time": "8.0.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/affected.ts

@@ -0,0 +1,320 @@
+// What a diff touches: the changed-file list read out of git, and the workspaces that list forces
+// a re-test of — closed TRANSITIVELY over the workspace graph, because A → B → C means an edit in
+// C breaks A and a single pass over an unordered list only ever reaches B.
+//
+// The diff defaults to a REF, never the working tree. Several agents share one checkout here (root
+// `CLAUDE.md`, the "Note": no worktrees, "run them as a team in this same checkout"), so a
+// working-tree diff returns every other agent's uncommitted work and the "affected" set silently
+// widens to nearly the whole monorepo — the command stops narrowing anything and nobody can tell.
+// A ref diff is stable under that concurrency; `--dirty` opts back in, which is right for one
+// developer iterating alone and wrong as a default here.
+
+// `join`/`relative` are `node:`-only by necessity: Bun exposes no path primitive, and a workspace
+// directory is checkout-relative while a caller's scan yields paths relative to its own root.
+import { join, relative } from 'node:path';
+import { singleLine, UltimateError } from '@ultimat3/core';
+import { docsFor } from './error-codes';
+import { BadFlagError } from './errors';
+import type { ExecResult, Runner } from './exec';
+import { execOutput } from './exec';
+import type { JsonValue } from './output';
+import type { ParsedArgs } from './parse';
+import { flagBool, flagString } from './parse';
+import type { WorkspaceNode } from './workspace-graph';
+import { readWorkspaceGraph } from './workspace-graph';
+
+/** The branch a change is measured against when `--base` says nothing. */
+export const DEFAULT_BASE = 'main';
+
+/**
+ * Root files that belong to no workspace and change what every workspace compiles to: a compiler
+ * option, a lint rule, the root manifest, the resolved dependency tree, the test preload, the app
+ * config. A "scoped" run that skipped them reports green over packages the edit just broke.
+ *
+ * Matched on the WHOLE path — `packages/cli/package.json` is the cli workspace's own file and
+ * reaches only cli's dependents, `package.json` at the root reaches everything.
+ */
+export const ROOT_WIDE_FILES: readonly string[] = [
+  'app.config.ts',
+  'biome.json',
+  'bun.lock',
+  'bunfig.toml',
+  'package.json',
+  'tsconfig.json',
+];
+
+/**
+ * A file with no compilation unit behind it. A doc or a plan re-checks nothing, so it maps to no
+ * workspace at all rather than to the one it happens to sit inside — `packages/cli/README.md` is
+ * not a reason to run `packages/cli`'s tests.
+ */
+const isDoc = (path: string): boolean => path.endsWith('.md');
+
+const owns = (node: WorkspaceNode, path: string): boolean =>
+  path === node.dir || path.startsWith(`${node.dir}/`);
+
+/**
+ * The workspace a path belongs to, longest directory first: nested workspaces exist (a scaffolded
+ * app's `apps/web` inside its own root), and the shorter prefix would swallow the inner one.
+ */
+export function owningWorkspace(
+  graph: readonly WorkspaceNode[],
+  path: string,
+): WorkspaceNode | undefined {
+  let best: WorkspaceNode | undefined;
+  for (const node of graph) {
+    if (!owns(node, path)) continue;
+    if (best === undefined || node.dir.length > best.dir.length) best = node;
+  }
+  return best;
+}
+
+/**
+ * Every workspace that depends on one of `seeds`, however many edges away.
+ *
+ * A queue with a growing cursor, not one pass over `seeds`: with `A → B → C`, one pass answers
+ * `{ C, B }` and leaves A untested while the change that broke it is in the diff — a green
+ * checkmark on a broken repo, which is the whole reason this command exists rather than each agent
+ * inventing its own scoping. `reached` doubles as the cycle guard.
+ */
+function withDependents(
+  graph: readonly WorkspaceNode[],
+  seeds: ReadonlySet<string>,
+): ReadonlySet<string> {
+  const dependents = new Map<string, string[]>();
+  for (const node of graph) {
+    for (const dependency of node.dependencies) {
+      const known = dependents.get(dependency);
+      if (known === undefined) dependents.set(dependency, [node.name]);
+      else known.push(node.name);
+    }
+  }
+  const reached = new Set(seeds);
+  const queue = [...reached];
+  for (let cursor = 0; cursor < queue.length; cursor += 1) {
+    const name = queue[cursor];
+    if (name === undefined) continue;
+    for (const dependent of dependents.get(name) ?? []) {
+      if (reached.has(dependent)) continue;
+      reached.add(dependent);
+      queue.push(dependent);
+    }
+  }
+  return reached;
+}
+
+export interface AffectedPlan {
+  /** Every path the diff reported, verbatim and in git's order. */
+  readonly changed: readonly string[];
+  /** The subset with no compilation unit behind it, named so an empty answer explains itself. */
+  readonly ignored: readonly string[];
+  /** The root files that forced every workspace in, empty when none did. */
+  readonly rootWide: readonly string[];
+  readonly workspaces: readonly WorkspaceNode[];
+}
+
+const byName = (a: WorkspaceNode, b: WorkspaceNode): number => (a.name > b.name ? 1 : -1);
+
+/**
+ * Pure: the graph and the file list in, the plan out. No git, no disk — so the transitive rule is
+ * testable without a checkout whose state would decide the verdict.
+ */
+export function planAffected(
+  graph: readonly WorkspaceNode[],
+  changed: readonly string[],
+): AffectedPlan {
+  const ignored = changed.filter(isDoc);
+  const considered = changed.filter((path) => !isDoc(path));
+  const rootWide = considered.filter((path) => ROOT_WIDE_FILES.includes(path));
+  if (rootWide.length > 0) {
+    return { changed, ignored, rootWide, workspaces: [...graph].sort(byName) };
+  }
+  const seeds = new Set<string>();
+  for (const path of considered) {
+    const node = owningWorkspace(graph, path);
+    if (node !== undefined) seeds.add(node.name);
+  }
+  const reached = withDependents(graph, seeds);
+  return {
+    changed,
+    ignored,
+    rootWide,
+    workspaces: graph.filter((node) => reached.has(node.name)).sort(byName),
+  };
+}
+
+/**
+ * How the calling command spells this scoping, so a `fix:` re-runs the invocation that actually
+ * failed. `x test --base main` is refused by `x test` itself — without `--affected` the flag
+ * narrows nothing — so a fix line that dropped it would reproduce its own failure, verbatim.
+ */
+const invocationOf = (command: string): string =>
+  command === 'affected' ? 'x affected' : `x ${command} --affected`;
+
+export interface AffectedSelection {
+  readonly base: string;
+  readonly dirty: boolean;
+}
+
+/**
+ * One reader for `--base` and `--dirty`, shared by `x affected` and `x test --affected`: two
+ * readers would be two answers to "what is this diff measured against", and the second command's
+ * scoping is only trustworthy if it is the first command's.
+ */
+export function readAffectedSelection(args: ParsedArgs, command: string): AffectedSelection {
+  const base = flagString(args, 'base') ?? DEFAULT_BASE;
+  if (base.trim().length === 0) {
+    throw new BadFlagError({
+      flag: 'base',
+      command,
+      reason: 'needs a git ref and got an empty value',
+      fix: `${invocationOf(command)} --base ${DEFAULT_BASE} --json`,
+    });
+  }
+  return { base, dirty: flagBool(args, 'dirty') };
+}
+
+const git = (runner: Runner, cwd: string, args: readonly string[]): Promise<ExecResult> =>
+  runner(['git', ...args], { cwd });
+
+/** NUL-delimited, so a path holding a space, a quote or a newline survives the read intact. */
+const paths = (stdout: string): readonly string[] =>
+  stdout.split('\0').filter((path) => path.length > 0);
+
+/**
+ * The checkout's own root, which is what every path git prints is relative to — so it is also the
+ * root the workspace graph has to be read from, or a `packages/cli/...` path would be matched
+ * against dirs resolved somewhere else.
+ */
+export async function gitRoot(runner: Runner, cwd: string, command: string): Promise<string> {
+  const result = await git(runner, cwd, ['rev-parse', '--show-toplevel']);
+  if (result.ok) return result.stdout.trim();
+  throw new UltimateError({
+    code: 'X_CLI_UNEXPECTED',
+    cause: `x ${command} reads its diff from git and "git rev-parse --show-toplevel" exited ${result.code} in ${cwd}: ${singleLine(execOutput(result))}`,
+    fix: `run x ${command} from inside a git checkout — confirm with: git rev-parse --show-toplevel`,
+    docs: docsFor('X_CLI_UNEXPECTED'),
+  });
+}
+
+export interface ChangedFilesOptions {
+  readonly cwd: string;
+  readonly command: string;
+  readonly selection: AffectedSelection;
+}
+
+/**
+ * `<base>...HEAD` — three dots, so the answer is "what this branch changed since it forked",
+ * never "how this branch differs from a base that has moved on underneath it". A two-dot diff
+ * reports someone else's merged commits as this branch's work.
+ *
+ * `--dirty` unions the working tree on top: tracked edits against HEAD, plus untracked files that
+ * are not ignored. Both halves are needed — a brand-new file is invisible to `git diff`.
+ */
+export async function changedFiles(
+  runner: Runner,
+  options: ChangedFilesOptions,
+): Promise<readonly string[]> {
+  const { base, dirty } = options.selection;
+  const resolved = await git(runner, options.cwd, [
+    'rev-parse',
+    '--verify',
+    '--quiet',
+    `${base}^{commit}`,
+  ]);
+  if (!resolved.ok) {
+    throw new BadFlagError({
+      flag: 'base',
+      command: options.command,
+      reason: `git resolves no commit named "${base}" in this checkout`,
+      fix: `git fetch --no-tags origin ${base}:${base}, then re-run: ${invocationOf(options.command)} --base ${base} --json`,
+    });
+  }
+  const runs = [
+    await git(runner, options.cwd, ['diff', '--name-only', '-z', `${base}...HEAD`]),
+    ...(dirty
+      ? [
+          await git(runner, options.cwd, ['diff', '--name-only', '-z', 'HEAD']),
+          await git(runner, options.cwd, ['ls-files', '-z', '--others', '--exclude-standard']),
+        ]
+      : []),
+  ];
+  const failed = runs.find((run) => !run.ok);
+  if (failed !== undefined) {
+    throw new UltimateError({
+      code: 'X_CLI_UNEXPECTED',
+      cause: `"${failed.command.join(' ')}" exited ${failed.code} in ${options.cwd}: ${singleLine(execOutput(failed))}`,
+      fix: `run it yourself to see why: ${failed.command.join(' ')}`,
+      docs: docsFor('X_CLI_UNEXPECTED'),
+    });
+  }
+  return [...new Set(runs.flatMap((run) => paths(run.stdout)))].sort();
+}
+
+/**
+ * One resolved answer, in the two shapes its two callers need: the `plan` (`x affected` reports
+ * it) and the `prefixes` (`x test --affected` selects with them). `plan.workspaces` holds dirs
+ * relative to the CHECKOUT; `prefixes` is the same set relative to the directory the caller scans,
+ * which is what its own paths are relative to.
+ */
+export interface AffectedScope {
+  readonly selection: AffectedSelection;
+  /** The checkout root git reported every path against. */
+  readonly root: string;
+  readonly plan: AffectedPlan;
+  readonly prefixes: readonly string[];
+}
+
+/**
+ * An empty prefix means the scan root IS an affected workspace, so every path it yields is in
+ * scope; a prefix starting with `..` is a workspace outside that root, which has no file there to
+ * select and must not be allowed to collapse into a match-everything empty string.
+ */
+const scopePrefixes = (root: string, cwd: string, dirs: readonly string[]): readonly string[] =>
+  dirs
+    .map((dir) => relative(cwd, join(root, dir)).split('\\').join('/'))
+    .filter((path) => !path.startsWith('..'));
+
+export const inScope = (path: string, prefixes: readonly string[]): boolean =>
+  prefixes.some((prefix) => prefix === '' || path === prefix || path.startsWith(`${prefix}/`));
+
+export interface AffectedScopeOptions {
+  readonly runner: Runner;
+  /** The directory the caller scans, which the prefixes come back relative to. */
+  readonly cwd: string;
+  readonly args: ParsedArgs;
+  readonly command: string;
+}
+
+/**
+ * The whole answer, resolved once: the diff, the graph, the closure and the prefixes. `x affected`
+ * and `x test --affected` both come through here, so the second can never scope a run differently
+ * from what the first reports — an invented scoping that misses a transitive dependent is a green
+ * checkmark on a broken repo, and two implementations is how one of them gets it wrong.
+ */
+export async function affectedScope(options: AffectedScopeOptions): Promise<AffectedScope> {
+  const selection = readAffectedSelection(options.args, options.command);
+  const root = await gitRoot(options.runner, options.cwd, options.command);
+  const plan = planAffected(
+    await readWorkspaceGraph(root),
+    await changedFiles(options.runner, { cwd: root, command: options.command, selection }),
+  );
+  return {
+    selection,
+    root,
+    plan,
+    prefixes: scopePrefixes(
+      root,
+      options.cwd,
+      plan.workspaces.map((workspace) => workspace.dir),
+    ),
+  };
+}
+
+/** The scope as `--json` carries it, from whichever command narrowed by it. */
+export const affectedScopeJson = (scope: AffectedScope): JsonValue => ({
+  base: scope.selection.base,
+  dirty: scope.selection.dirty,
+  changed: scope.plan.changed.length,
+  workspaces: scope.plan.workspaces.map((workspace) => workspace.dir),
+});

package/src/app-boundaries.ts

@@ -15,8 +15,9 @@ import { join as joinPath } from 'node:path';
 // The POSIX variants resolve specifiers against import-graph keys, which are POSIX on every host.
 import { dirname, join, normalize, relative } from 'node:path/posix';
 import type { BoundaryRule, ImportGraph } from '@ultimat3/render';
-import { checkSurfaceBoundary, importGraph } from '@ultimat3/render';
+import { checkSurfaceBoundary, importGraph, SURFACES } from '@ultimat3/render';
 import type { Finding } from './output';
+import { quoteArg } from './shell-quote';
 
 export const BOUNDARY_CODES = [
   'X_BOUNDARY_SITE_TO_APP',
@@ -132,8 +133,57 @@ const surfaceFindings = (graph: ImportGraph): readonly Finding[] =>
     };
   });
 
-/** `apps/web/app/posts/service.ts` → `posts`: the primitive a generator would be told to make. */
-const subjectOf = (path: string, fallback: string): string => path.split('/').at(-2) ?? fallback;
+/**
+ * The surface names, from `@ultimat3/render`'s own list rather than a copy: a resource can never
+ * be called one, because the directory carrying that name is the surface itself.
+ */
+const SURFACE_NAMES: ReadonlySet<string> = new Set<string>(SURFACES);
+
+/**
+ * `apps/web/app/posts/service.ts` → `posts`: the primitive a generator would be told to make.
+ *
+ * `undefined` at a surface ROOT, where the directory above the file is the surface. The old
+ * answer there was the surface's own name, so `X_BOUNDARY_ROUTE_TO_DB` on `apps/web/site/page.tsx`
+ * said `x g query site` — a runnable line that generates seven files and a `sites` table for a
+ * landing page whose only problem is one import. A fix that does the wrong thing successfully is
+ * worse than one that refuses, so the caller names the file and asks for a name instead.
+ */
+function subjectOf(path: string): string | undefined {
+  const parent = path.split('/').at(-2);
+  return parent === undefined || SURFACE_NAMES.has(parent) ? undefined : parent;
+}
+
+/**
+ * Control characters, `\u00xx`-escaped. The path is a value read off the repository being scanned,
+ * and it rides in a `#` comment: a directory holding a NEWLINE ends that comment, so everything
+ * after it is a second command in a line whose whole purpose is to be pasted into a shell.
+ * Escaped rather than deleted, because the comment still has to name the file the reader owns.
+ */
+const commentSafe = (path: string): string =>
+  [...path]
+    .map((char) => {
+      const code = char.codePointAt(0) ?? 0;
+      return code < 0x20 || code === 0x7f ? `\\u${code.toString(16).padStart(4, '0')}` : char;
+    })
+    .join('');
+
+/**
+ * `x g query posts` where the path names a resource, `x g query <name>` where it names a surface.
+ * The placeholder form is the shape `MissingPositionalError` already hands out (`x g route
+ * <name>`) and the one the `errors` step leaves unjudged in that slot — an open positional, where
+ * a reader substituting a word makes the line run. The path rides in the `#` comment because a
+ * `fix:` is copied on its own, and `Finding.at` is a field an agent pasting one line never sees.
+ *
+ * BOTH halves come from the scanned path, so both are hostile: the subject is an ARGUMENT and goes
+ * through `quoteArg` — a directory named `posts; id` emitted a fix that ran `id` — and the comment
+ * goes through `commentSafe`. `<name>` alone stays literal: it is a placeholder a reader replaces,
+ * and `'<name>'` would be pasted as a resource actually called that.
+ */
+const generate = (kind: 'query' | 'action', path: string, then: string): string => {
+  const subject = subjectOf(path);
+  const named = subject === undefined ? '<name>' : quoteArg(subject);
+  return `x g ${kind} ${named}   # ${then} ${commentSafe(path)}`;
+};
 
 /**
  * Both fixes are one runnable line, with the rest of the instruction behind a `#` — a fix a
@@ -147,7 +197,7 @@ function layerFindings(scanned: readonly ScannedFile[]): readonly Finding[] {
         findings.push({
           code: 'X_BOUNDARY_ROUTE_TO_DB',
           cause: `route imports the database ("${specifier}") — routes call actions and queries`,
-          fix: `x g query ${subjectOf(file.path, 'rows')}   # then call it from the route`,
+          fix: generate('query', file.path, 'then call it from'),
           docs: docs('X_BOUNDARY_ROUTE_TO_DB'),
           at: file.path,
         });
@@ -156,7 +206,7 @@ function layerFindings(scanned: readonly ScannedFile[]): readonly Finding[] {
         findings.push({
           code: 'X_BOUNDARY_SERVICE_TO_HTTP',
           cause: `service imports HTTP ("${specifier}") — a service that knows about requests cannot be reused by a job`,
-          fix: `x g action ${subjectOf(file.path, 'service')}   # read the request there, pass the service plain values`,
+          fix: generate('action', file.path, 'read the request there and pass plain values to'),
           docs: docs('X_BOUNDARY_SERVICE_TO_HTTP'),
           at: file.path,
         });

package/src/bin.ts

@@ -3,9 +3,11 @@
 // dispatch.ts, so the whole CLI is testable without spawning a process.
 
 import { dispatch } from './dispatch';
-// The write itself is `write-line.ts`: `create-ultimate`'s entry point needs the identical one,
-// and a second copy of a note about pipe truncation is a second copy that drifts.
-import { writeLine } from './write-line';
+// The writes themselves are `write-line.ts`: `create-ultimate`'s entry point needs the identical
+// one, and a second copy of a note about pipe truncation is a second copy that drifts. Two sinks,
+// because fd 1 is not always this process's to write on — `x mcp serve --transport stdio` hands it
+// to the protocol, and `dispatch` addresses that result to the second.
+import { writeErrorLine, writeLine } from './write-line';
 
 const code = await dispatch({
   argv: Bun.argv.slice(2),
@@ -13,6 +15,7 @@ const code = await dispatch({
   env: Bun.env,
   bunVersion: Bun.version,
   write: writeLine,
+  writeError: writeErrorLine,
 });
 
 process.exit(code);