@ultimat3/cli 27.13.2 → 27.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "27.13.2",
+  "version": "27.14.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -39,33 +39,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "27.13.2",
-    "@ultimat3/admin": "27.13.2",
-    "@ultimat3/ai": "27.13.2",
-    "@ultimat3/auth": "27.13.2",
-    "@ultimat3/cache": "27.13.2",
-    "@ultimat3/core": "27.13.2",
-    "@ultimat3/db": "27.13.2",
-    "@ultimat3/entity": "27.13.2",
-    "@ultimat3/flags": "27.13.2",
-    "@ultimat3/http": "27.13.2",
-    "@ultimat3/i18n": "27.13.2",
-    "@ultimat3/jobs": "27.13.2",
-    "@ultimat3/mail": "27.13.2",
-    "@ultimat3/manifest": "27.13.2",
-    "@ultimat3/mcp": "27.13.2",
-    "@ultimat3/money": "27.13.2",
-    "@ultimat3/notify": "27.13.2",
-    "@ultimat3/policy": "27.13.2",
-    "@ultimat3/pwa": "27.13.2",
-    "@ultimat3/query": "27.13.2",
-    "@ultimat3/realtime": "27.13.2",
-    "@ultimat3/render": "27.13.2",
-    "@ultimat3/schema": "27.13.2",
-    "@ultimat3/seo": "27.13.2",
-    "@ultimat3/storage": "27.13.2",
-    "@ultimat3/testing": "27.13.2",
-    "@ultimat3/time": "27.13.2",
+    "@ultimat3/action": "27.14.0",
+    "@ultimat3/admin": "27.14.0",
+    "@ultimat3/ai": "27.14.0",
+    "@ultimat3/auth": "27.14.0",
+    "@ultimat3/cache": "27.14.0",
+    "@ultimat3/core": "27.14.0",
+    "@ultimat3/db": "27.14.0",
+    "@ultimat3/entity": "27.14.0",
+    "@ultimat3/flags": "27.14.0",
+    "@ultimat3/http": "27.14.0",
+    "@ultimat3/i18n": "27.14.0",
+    "@ultimat3/jobs": "27.14.0",
+    "@ultimat3/mail": "27.14.0",
+    "@ultimat3/manifest": "27.14.0",
+    "@ultimat3/mcp": "27.14.0",
+    "@ultimat3/money": "27.14.0",
+    "@ultimat3/notify": "27.14.0",
+    "@ultimat3/policy": "27.14.0",
+    "@ultimat3/pwa": "27.14.0",
+    "@ultimat3/query": "27.14.0",
+    "@ultimat3/realtime": "27.14.0",
+    "@ultimat3/render": "27.14.0",
+    "@ultimat3/schema": "27.14.0",
+    "@ultimat3/seo": "27.14.0",
+    "@ultimat3/storage": "27.14.0",
+    "@ultimat3/testing": "27.14.0",
+    "@ultimat3/time": "27.14.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/budgets-unmeasured.ts

@@ -39,13 +39,26 @@ const ACTOR_REFUSALS: ReadonlySet<string> = new Set([
   'X_TENANCY_ACTOR_ORG_REQUIRED',
 ]);
 
-function ownCodeFinding(url: string, entry: UnmeasuredRoute): Finding {
+/**
+ * The locator every finding here carries: `at` is the FILE an agent opens, never the route URL —
+ * `output.ts`'s `Finding.at`, and `verify-checks.ts` reads it as the path to open. The URL is a
+ * fact of its own and rides beside it in `meta.route`, so `--json` loses nothing by the move.
+ *
+ * OMITTED, not filled with something, when no file declares the route: a URL is not a path anyone
+ * can open, and `at` that names nothing opens nothing. The cause and the fix both name the URL.
+ */
+const locatorOf = (file: string | undefined, url: string): Pick<Finding, 'at' | 'meta'> => ({
+  ...(file === undefined ? {} : { at: file }),
+  meta: { route: url },
+});
+
+function ownCodeFinding(url: string, file: string | undefined, entry: UnmeasuredRoute): Finding {
   return {
     code: entry.code ?? 'X_BUDGET_UNMEASURED',
     cause: entry.cause ?? entry.reason,
     fix: entry.fix ?? `x build --target static --json   # its "unmeasured" list has ${url}`,
     docs: ERROR_DOCS_URL,
-    at: url,
+    ...locatorOf(file, url),
   };
 }
 
@@ -57,15 +70,20 @@ const refusalOf = (entry: UnmeasuredRoute): string =>
  * A build ran and has no row for `url`. `entry` is the report's account of why, when it has one:
  * an instruction under its own code, an actor edit, or — for a failure that is a fact about the
  * build's environment — the report, with the refusal already in the cause.
+ *
+ * `file` is the file that declares `url`, resolved by the caller (`budgets.ts` asks the loaded
+ * route table); `undefined` when no route file claims it, and the finding then carries no locator
+ * rather than a URL that opens nothing.
  */
 export function builtUnmeasuredFinding(
   url: string,
   declared: string,
   statsFile: string,
   entry: UnmeasuredRoute | undefined,
+  file: string | undefined,
 ): Finding {
   if (entry?.code !== undefined && REPORTED_BY_OWN_CODE.has(entry.code)) {
-    return ownCodeFinding(url, entry);
+    return ownCodeFinding(url, file, entry);
   }
   const base = `${url} declares a ${declared} budget and ${statsFile} has no row for it, so the build ran and could not weigh it`;
   if (entry?.code !== undefined && ACTOR_REFUSALS.has(entry.code)) {
@@ -76,7 +94,7 @@ export function builtUnmeasuredFinding(
       // The paste: one declaration in the one file every build imports.
       fix: "defineMeasurementActor(() => userActor({ id: 'measure', orgId: '<an org your dev seed creates>', roles: ['<the role this page requires>'] }))   # in app.config.ts",
       docs: ERROR_DOCS_URL,
-      at: url,
+      ...locatorOf(file, url),
     };
   }
   return {
@@ -86,6 +104,6 @@ export function builtUnmeasuredFinding(
     // route it could not weigh, and why.
     fix: `x build --target static --json   # its "unmeasured" list says why ${url} could not be weighed`,
     docs: ERROR_DOCS_URL,
-    at: url,
+    ...locatorOf(file, url),
   };
 }

package/src/budgets.ts

@@ -117,27 +117,34 @@ function exceededJsFix(url: string, file: string | undefined, bytes: number): st
  * run and could not weigh this one, which is `PrerenderReport.unmeasured`'s question and not a
  * second build's. Reporting the first as the second is what sends a reader to re-run a build that
  * already did everything it was going to do.
+ *
+ * `fileOf` names the file an agent opens to fix this route, exactly as it does for
+ * `X_BUDGET_EXCEEDED`: `Finding.at` is a PATH, never a URL (`output.ts`, `verify-checks.ts`),
+ * so the route rides beside it in `meta.route` and every cause below still spells the URL.
  */
 function unmeasuredFinding(
   url: string,
   declared: string,
   stats: BuildStats | undefined,
   unmeasured: readonly UnmeasuredRoute[],
+  fileOf: RouteFileOf,
 ): Finding {
+  const file = fileOf(url);
   if (stats?.stale === true) {
     return {
       code: 'X_BUDGET_UNMEASURED',
       cause: `${url} declares a ${declared} budget and ${BUILD_STATS_FILE} was written by an earlier measurement rule than this gate's (v${String(BUILD_STATS_RULES)}), so its numbers are not this gate's to read`,
       fix: 'x build --target static --json && x verify --json',
       docs: ERROR_DOCS_URL,
-      at: url,
+      ...(file === undefined ? {} : { at: file }),
+      meta: { route: url },
     };
   }
   // A build ran: the report's account of this route decides the instruction
   // (`budgets-unmeasured.ts`) — its own code, an actor edit, or the report.
   if (stats !== undefined) {
     const entry = unmeasured.find((one) => one.path === url);
-    return builtUnmeasuredFinding(url, declared, BUILD_STATS_FILE, entry);
+    return builtUnmeasuredFinding(url, declared, BUILD_STATS_FILE, entry, file);
   }
   return {
     code: 'X_BUDGET_UNMEASURED',
@@ -147,7 +154,8 @@ function unmeasuredFinding(
     // the one caller of `writeBuildStats`.
     fix: 'x build --target static --json && x verify --json',
     docs: ERROR_DOCS_URL,
-    at: url,
+    ...(file === undefined ? {} : { at: file }),
+    meta: { route: url },
   };
 }
 
@@ -161,8 +169,9 @@ function unmeasuredFinding(
  * and can be absent for the same reason; with it, a route whose measurement failed on a code in
  * `REPORTED_BY_OWN_CODE` (`budgets-unmeasured.ts`) is reported under that code, with the build's own cause and fix.
  *
- * `fileOf` names the file an `X_BUDGET_EXCEEDED` fix edits: the step runs after the app loaded,
- * so render's route table already holds it. A test hands its own.
+ * `fileOf` names the file an agent opens for a route's finding — the locator `Finding.at` carries
+ * and the file `X_BUDGET_EXCEEDED`'s fix edits: the step runs after the app loaded, so render's
+ * route table already holds it. A test hands its own.
  */
 export function checkBudgets(
   manifest: Manifest,
@@ -183,19 +192,24 @@ export function checkBudgets(
     const js = jsBudgetOf(route);
     if (measured === undefined) {
       if (js !== null) {
-        findings.push(unmeasuredFinding(route.url, 'JS', stats, unmeasured));
+        findings.push(unmeasuredFinding(route.url, 'JS', stats, unmeasured, fileOf));
       }
       continue;
     }
     if (js !== null && measured.jsBytes > js) {
-      const meta = chargedMeta(measured.jsBytes, measured.charged, measured.inlineJsBytes);
+      // `at` is the file an agent opens — the SAME resolution `exceededJsFix` edits, so the
+      // locator and the instruction name one place. The route URL it belongs to is in `cause`
+      // (`budgets-charged.test.ts` holds the per-file breakdown in `meta` only when a row carries
+      // one — adding a `route` key would conflict with that contract).
+      const file = fileOf(route.url);
+      const charged = chargedMeta(measured.jsBytes, measured.charged, measured.inlineJsBytes);
       findings.push({
         code: 'X_BUDGET_EXCEEDED',
         cause: `${route.url} ships ${formatBytes(measured.jsBytes)} of JS (minified, uncompressed) over a ${formatBytes(js)} budget via ${chainOf(measured)}${chargedClause(measured.charged, measured.inlineJsBytes)}`,
-        fix: exceededJsFix(route.url, fileOf(route.url), measured.jsBytes),
+        fix: exceededJsFix(route.url, file, measured.jsBytes),
         docs: ERROR_DOCS_URL,
-        at: route.url,
-        ...(meta === undefined ? {} : { meta }),
+        ...(file === undefined ? {} : { at: file }),
+        ...(charged === undefined ? {} : { meta: charged }),
       });
     }
   }

package/src/ci-log.ts

@@ -4,7 +4,7 @@
 // this file undoes the transport and reconstructs the `Finding`, rather than printing a wall of
 // text and asking the reader to spot the code in it.
 
-import type { Finding } from './output';
+import type { Finding, JsonValue } from './output';
 
 /** One log line, with the two columns Actions prefixes every line with taken off. */
 export interface CiLogLine {
@@ -67,11 +67,52 @@ export function jobsInLog(lines: readonly CiLogLine[]): readonly string[] {
 }
 
 const CODE = /^(X_[A-Z][A-Z0-9_]*)/;
-const LOCATOR = /\(([^()]+)\)$/;
+// The ONE way a `Finding.at` — a path an agent can open — returns from a log. The renderer
+// prints it as the parenthesised expression in the head (`renderFinding`, `output.ts`).
+//
+// Anchored to the head minus a trailing `[step=…]`, NOT to the end of the line:
+// `X_VERIFY_STEP_TIMEOUT` sets both `at` and `meta.step`, so that head reads
+// `CODE (path) [step=unit]` — an end-anchor matches only what follows the brackets, the match
+// fails, and the path is dropped. With no step the optional group is absent and the
+// parenthesised group is still the last thing on the line.
+const LOCATOR = /\(([^()]+)\)(?=\s*(?:\[step=[^[\]]+\]\s*)?$)/;
+// The second, non-path locator the renderer prints on the head — `meta.step` in the same
+// brackets-keyed form (`[step=lint]`) `renderFinding` writes — so a merge gap's gate step name
+// or any future non-path identifier survives the round-trip too. Its own brackets are what
+// `LOCATOR`'s lookahead stands aside for, so the two cannot collide in one head.
+const STEP_LOCATOR = /\[step=([^[\]]+)\]\s*$/;
 
 const after = (text: string, label: string): string | undefined =>
   text.trim().startsWith(label) ? text.trim().slice(label.length).trim() : undefined;
 
+// The `meta.step` locator the renderer prints in the head (`output.ts:185-189`): a gate step name
+// the finding carries on `meta`, never on `at`. Total on every shape `Finding.meta` may take —
+// the field is optional, and a malformed `meta` (a non-object value, an array) is read as "no
+// step", the same answer an absent `meta` gets.
+const stepOf = (finding: Finding): string => {
+  if (typeof finding.meta === 'object' && finding.meta !== null && !Array.isArray(finding.meta)) {
+    const value = (finding.meta as { readonly [key: string]: JsonValue })['step'];
+    return typeof value === 'string' ? value : '';
+  }
+  return '';
+};
+
+/**
+ * The dedupe key a finding is told apart by. Two findings are the same only if every locator
+ * the renderer prints agrees on them — `code`, `cause`, `at`, and `meta.step`. Ci-log's per-log
+ * dedupe (`findingsFrom` below) and `x ci`'s cross-log dedupe (`cmd-ci.ts`) both build the key
+ * off this formula, so a finding that survives one cannot be silently merged by the other.
+ *
+ * A re-run appends a second copy of the same block; two identical findings would read as two
+ * problems where the job has one. A `X_COVERAGE_BELOW` routed to two different packages is the
+ * opposite — two findings, where a key of code and cause alone folds the second into a duplicate.
+ * `fix` is deliberately not in it: the same block reprints its fix line, and `x ci` fences it
+ * differently per job, so keying on it would report a re-run twice.
+ */
+export function findingKey(finding: Finding): string {
+  return `${finding.code}\0${finding.cause}\0${finding.at ?? ''}\0${stepOf(finding)}`;
+}
+
 /**
  * `renderFinding`'s output, read backwards. A code line ALONE is not a finding — prose naming a
  * code, a summary counting them and a `fix:` quoting one all start with `X_`, and reconstructing
@@ -93,19 +134,26 @@ export function findingsFrom(lines: readonly CiLogLine[]): readonly Finding[] {
     if (cause === undefined || fix === undefined) continue;
     const code = head[1] ?? '';
     const at = LOCATOR.exec(texts[index] ?? '')?.[1];
+    const step = STEP_LOCATOR.exec(texts[index] ?? '')?.[1];
     const docs = after(texts[index + 3] ?? '', 'docs:');
-    const key = `${code}\0${cause}`;
-    // A re-run appends a second copy of the same block; two identical findings would read as two
-    // problems where the job has one.
-    if (!seen.has(key)) {
-      seen.add(key);
-      out.push({
-        code,
-        cause,
-        fix,
-        ...(at === undefined ? {} : { at }),
-        ...(docs === undefined ? {} : { docs }),
-      });
+    // Step name and any other reconstructed structured fact ride on `meta`, so the
+    // reconstructed finding has a place to put a non-path locator `at` cannot carry.
+    const meta = step === undefined ? undefined : { step };
+    // Built once, then keyed: `findingKey` reads `code`, `cause`, `at` and `meta.step` off it,
+    // so the per-log dedupe here and the across-log dedupe in `cmd-ci.ts` agree on what one
+    // finding is. `X_VERIFY_MERGE_INCOMPLETE` arrives here once per missing step, and only the
+    // step name tells them apart.
+    const finding: Finding = {
+      code,
+      cause,
+      fix,
+      ...(at === undefined ? {} : { at }),
+      ...(meta === undefined ? {} : { meta }),
+      ...(docs === undefined ? {} : { docs }),
+    };
+    if (!seen.has(findingKey(finding))) {
+      seen.add(findingKey(finding));
+      out.push(finding);
     }
     index += 2;
   }

package/src/ci-runs.ts

@@ -9,13 +9,14 @@ import type { GhRepo } from './gh-target';
 
 /** The fields both `gh run list` and `gh run view` accept, named once so the two agree. */
 export const RUN_FIELDS =
-  'databaseId,status,conclusion,headBranch,displayTitle,workflowName,url,createdAt';
+  'databaseId,status,conclusion,headBranch,displayTitle,workflowName,url,createdAt,headSha';
 
 const RUN_ROW = t.object({
   databaseId: t.number,
   status: t.string,
   conclusion: t.nullable(t.string),
   headBranch: t.string,
+  headSha: t.string,
   displayTitle: t.string,
   workflowName: t.string,
   url: t.string,
@@ -58,6 +59,7 @@ export interface CiRun {
   readonly workflow: string;
   readonly url: string;
   readonly createdAt: string;
+  readonly headSha: string;
 }
 
 /**
@@ -85,6 +87,7 @@ interface RunRow {
   readonly status: string;
   readonly conclusion: string | null;
   readonly headBranch: string;
+  readonly headSha: string;
   readonly displayTitle: string;
   readonly workflowName: string;
   readonly url: string;
@@ -96,6 +99,7 @@ const runOf = (row: RunRow): CiRun => ({
   status: row.status,
   conclusion: row.conclusion,
   branch: row.headBranch,
+  headSha: row.headSha,
   title: row.displayTitle,
   workflow: row.workflowName,
   url: row.url,

package/src/cmd-ci.ts

@@ -6,7 +6,7 @@
 
 import { UltimateError } from '@ultimat3/core';
 import type { CiLogLine } from './ci-log';
-import { findingsFrom, jobsInLog, parseLogLines, tailOf } from './ci-log';
+import { findingKey, findingsFrom, jobsInLog, parseLogLines, tailOf } from './ci-log';
 import type { CiJob, CiRun } from './ci-runs';
 import { failedLog, isFailed, isRunning, latestPerWorkflow, listRuns, viewRun } from './ci-runs';
 import { ciSpec, TAIL_LINES } from './cmd-ci-spec';
@@ -128,9 +128,11 @@ async function inspect(
     const pool: readonly CiLogLine[] = own.length > 0 ? own : lines;
     const job = failed.find((candidate) => candidate.name === name);
     for (const finding of findingsFrom(pool)) {
+      // Keep whatever the log carried: a path-style `at` or a non-path step (now on `meta.step`).
+      // Inventing a locator from the CI JOB name would put a non-path in `at` — exactly the seam
+      // this repair closes — so when the log had nothing, the finding reads nothing.
       findings.push({
         ...finding,
-        at: finding.at ?? name,
         // Fenced and tagged: the log is foreign text, and a `fix:` reconstructed from it is the
         // log author's instruction, not this CLI's. `commentBlock` is `x pr review`'s fence.
         fix: commentBlock(`ci-log ${name}`, [finding.fix]).join('\n'),
@@ -152,12 +154,17 @@ async function inspect(
 
 /**
  * The same block can be reached twice — once per job when the log attributes nothing, once per
- * attempt when a run was re-run — and two copies of one finding read as two problems.
+ * attempt when a run was re-run — and two copies of one finding read as two problems. The
+ * inverse is a finding with the same code and cause but a different `at` or `meta.step` (a
+ * `X_COVERAGE_BELOW` routed to two packages, the same gate step failing twice for different
+ * tests): they are NOT the same finding, and the key has to take every locator the gate printed
+ * to tell them apart. `findingKey` is the same formula `ci-log`'s per-log dedupe uses, so a
+ * finding that survives one cannot be silently merged by the other.
  */
 function dedupe(findings: readonly Finding[]): readonly Finding[] {
   const seen = new Set<string>();
   return findings.filter((finding) => {
-    const key = `${finding.code} ${finding.cause}`;
+    const key = findingKey(finding);
     if (seen.has(key)) return false;
     seen.add(key);
     return true;
@@ -241,6 +248,7 @@ function runJson(entry: RunReport): JsonValue {
     title: entry.run.title,
     url: entry.run.url,
     createdAt: entry.run.createdAt,
+    headSha: entry.run.headSha,
     // Absent rather than empty on a run that was never opened: `jobs: []` on a green run would
     // claim the run has no jobs, which is a different statement from "nobody asked".
     ...(entry.jobs === undefined

package/src/output.ts

@@ -21,7 +21,12 @@ export interface Finding {
   readonly cause: string;
   readonly fix: string;
   readonly docs?: string;
-  /** Optional locator: a file, route, or table the finding is about. */
+  /**
+   * Optional locator: a path an agent can OPEN — a source file (its path from the repo root) or
+   * a table. A gate step name, a route URL, or any other identifier that is not a file is NOT
+   * here: it belongs on `meta` (e.g. `meta.step`), and the renderer prints it in the head where
+   * `ci-log` can recover it. Set iff the finding is about a file the author can edit.
+   */
   readonly at?: string;
   /**
    * Where the finding's TEXT came from, when not from this process. `'ci-log'` is `x ci` reading
@@ -172,7 +177,18 @@ export function renderFinding(finding: Finding, indent = ''): string {
   // Every field through `singleLine`: this is the format's only renderer for the terminal and CI
   // logs, and a `cause` carrying a newline would print a line a reader takes for a real finding.
   const code = singleLine(finding.code);
-  const head = finding.at === undefined ? code : `${code} (${singleLine(finding.at)})`;
+  // The path-style locator (`at`) keeps its parenthesised form: `CODE (path)`. A non-path locator
+  // — today only `meta.step`, the gate step name — is printed AFTER, bracketed and keyed
+  // (`[step=lint]`), so `ci-log`'s existing `LOCATOR = /\(([^()]+)\)$/` still means `at` and a
+  // matching step regex can recover it without colliding. Either side may be absent; when BOTH
+  // are absent the head is the bare `CODE` it always was.
+  const stepValue =
+    typeof finding.meta === 'object' && finding.meta !== null && !Array.isArray(finding.meta)
+      ? (finding.meta as { readonly [key: string]: JsonValue })['step']
+      : undefined;
+  const stepLabel = typeof stepValue === 'string' ? ` [step=${singleLine(stepValue)}]` : '';
+  const pathLabel = finding.at === undefined ? '' : ` (${singleLine(finding.at)})`;
+  const head = `${code}${pathLabel}${stepLabel}`;
   const lines = [
     `${indent}${head}`,
     `${indent}  cause: ${singleLine(finding.cause)}`,

package/src/static-report.ts

@@ -57,7 +57,11 @@ export type SkippedRoute = RouteFacts & {
  * re-exports the name for its own callers.
  */
 export type UnmeasuredRoute = {
-  /** The DECLARED path, as `X_BUDGET_UNMEASURED`'s `at:` spells it, so the two rows join. */
+  /**
+   * The DECLARED path, the way the finding about it spells the route: `X_BUDGET_UNMEASURED`'s
+   * `meta.route` and its `cause`, so the report row and the gate's finding join. NOT its `at:` —
+   * `Finding.at` is the file an agent opens, and the declaring page is what that holds.
+   */
   readonly path: string;
   readonly reason: string;
   /**

package/src/verify-merge.ts

@@ -128,8 +128,13 @@ export function parsePart(file: string, text: string, command: string = GATE_COM
   };
 }
 
-/** A gap finding, with a fix spelled for the entry that raised it. */
-type Gap = (cause: string, at?: string) => Finding;
+/**
+ * A gap finding, with a fix spelled for the entry that raised it. The second positional is the
+ * gate `step` name the merge is naming — matching `X_VERIFY_STEP_TIMEOUT`'s precedent at
+ * `verify-stalled.ts:180-197`, where a timeout finding carries the step name in `meta.step`,
+ * never in `at` (which is, repo-wide, a path an agent can open — `output.ts:24-25`).
+ */
+type Gap = (cause: string, step: string, at?: string) => Finding;
 
 /**
  * The gap kinds a merge can find. `present` is a document that arrived and disagrees with the
@@ -149,13 +154,17 @@ const NEVER_ARRIVED =
 const gapsFor = (command: string): Gaps => {
   const finding =
     (fix: string): Gap =>
-    (cause, at) => ({
-      code: 'X_VERIFY_MERGE_INCOMPLETE',
-      cause,
-      fix,
-      docs: ERROR_DOCS_URL,
-      ...(at === undefined ? {} : { at }),
-    });
+    (cause, step, at) => {
+      const meta: { readonly step: string } = { step };
+      return {
+        code: 'X_VERIFY_MERGE_INCOMPLETE',
+        cause,
+        fix,
+        docs: ERROR_DOCS_URL,
+        ...(at === undefined ? {} : { at }),
+        meta,
+      };
+    };
   return {
     present: finding(
       `${command} merge parts/*.json --json   # after every CI job uploaded its part`,
@@ -354,7 +363,12 @@ export function mergeParts(
     part.steps
       .filter((step) => !declared.includes(step.name))
       .map((step) =>
-        kinds.present(`${part.file} reports "${step.name}", which x verify does not run`),
+        // The unknown step's own NAME rides on `meta.step` — it is the only locator here,
+        // never a path. `part.file` is already in the cause.
+        kinds.present(
+          `${part.file} reports "${step.name}", which x verify does not run`,
+          step.name,
+        ),
       ),
   );
   const steps = declared.map((name) =>