@vibe-agent-toolkit/utils 0.2.0-rc.1 → 0.2.0-rc.10

package/eslint/rules/no-literal-process-exit.cjs

@@ -0,0 +1,129 @@
+/**
+ * ESLint rule: no-literal-process-exit
+ *
+ * Flags `process.exit(<number>)` and `process.exitCode = <number>`. A numeric
+ * exit code written at the call site re-decides the exit contract inline: one
+ * command exits 1 for "findings" and another exits 1 for "the config was
+ * unreadable", and nothing but a reader comparing two files can tell. The
+ * allowed shape names the meaning — `process.exit(ExitCode.FINDINGS)` — so the
+ * contract lives in one enum and every command shares it.
+ *
+ * The literal may hide inside an expression: `ok ? 0 : 1`, `status ?? 1`,
+ * `-1`. Those are flagged too, because each branch is still a number chosen at
+ * this site. Any non-literal argument — an identifier, a member, a call
+ * result — is accepted; the rule is a syntactic floor and does not chase what
+ * a variable holds.
+ *
+ * Option `allow: string[]` — repo-relative paths of the files permitted to
+ * exit with a literal (the one `bin.ts` last-resort fallback that runs when
+ * the enum module itself failed to load). Entries are matched at a path
+ * segment boundary via `exempt-path-matcher.cjs`; give the full repo-relative
+ * path, not a bare basename.
+ *
+ * @example
+ * // BAD — 1 means what, exactly?
+ * process.exit(1);
+ *
+ * // GOOD — the meaning is the code
+ * process.exit(ExitCode.FINDINGS);
+ */
+
+'use strict';
+
+const { createExemptPathMatcher } = require('./exempt-path-matcher.cjs');
+
+/** Whether `node` is the member expression `process.<name>` (non-computed). */
+function isProcessMember(node, name) {
+  return (
+    node.type === 'MemberExpression' &&
+    !node.computed &&
+    node.object.type === 'Identifier' &&
+    node.object.name === 'process' &&
+    node.property.type === 'Identifier' &&
+    node.property.name === name
+  );
+}
+
+/**
+ * The first numeric literal reachable through the expression's value
+ * branches, or null. Walks conditionals, nullish/logical fallbacks, unary
+ * minus, and TypeScript wrappers — every path a number can take to become the
+ * exit code without passing through a name.
+ */
+function numericLiteralLeaf(expr) {
+  switch (expr.type) {
+    case 'Literal':
+      return typeof expr.value === 'number' ? expr : null;
+    case 'UnaryExpression':
+      return numericLiteralLeaf(expr.argument);
+    case 'ConditionalExpression':
+      return numericLiteralLeaf(expr.consequent) ?? numericLiteralLeaf(expr.alternate);
+    case 'LogicalExpression':
+      return numericLiteralLeaf(expr.left) ?? numericLiteralLeaf(expr.right);
+    case 'TSAsExpression':
+    case 'TSNonNullExpression':
+    case 'TSSatisfiesExpression':
+      return numericLiteralLeaf(expr.expression);
+    default:
+      return null;
+  }
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow process.exit(<number>) and process.exitCode = <number> — name the meaning with ' +
+        'the ExitCode enum so every command shares one exit contract',
+      recommended: false,
+      recommendedSeverity: 'warn',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          allow: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      literalExit:
+        'process.exit({{literal}}) re-decides the exit contract at this call site. Use the ' +
+        'ExitCode enum from @vibe-agent-toolkit/schema — process.exit(ExitCode.X) — so the code ' +
+        'means the same thing in every command.',
+      literalExitCode:
+        'process.exitCode = {{literal}} re-decides the exit contract at this site. Assign an ' +
+        'ExitCode member from @vibe-agent-toolkit/schema instead.',
+    },
+  },
+
+  create(context) {
+    const allow = context.options?.[0]?.allow ?? [];
+    const filename = context.filename ?? context.getFilename();
+    if (createExemptPathMatcher(allow)(filename)) {
+      return {};
+    }
+
+    function reportLiteral(node, expr, messageId) {
+      const leaf = numericLiteralLeaf(expr);
+      if (leaf !== null) {
+        context.report({ node, messageId, data: { literal: String(leaf.raw ?? leaf.value) } });
+      }
+    }
+
+    return {
+      CallExpression(node) {
+        if (isProcessMember(node.callee, 'exit') && node.arguments.length > 0) {
+          reportLiteral(node, node.arguments[0], 'literalExit');
+        }
+      },
+      AssignmentExpression(node) {
+        if (isProcessMember(node.left, 'exitCode')) {
+          reportLiteral(node, node.right, 'literalExitCode');
+        }
+      },
+    };
+  },
+};

package/eslint/rules/no-manual-path-normalize.cjs

@@ -1,16 +1,32 @@
 /**
- * ESLint rule to enforce using toForwardSlash() instead of manual normalization
+ * ESLint rule to enforce the forward-slash converters instead of hand-rolled
+ * normalization.
  *
- * Detects manual path normalization patterns and suggests using the utility function.
+ * Two converters, because a backslash means two different things:
+ *
+ * - `toForwardSlash(p)` — a NATIVE path (from `fs`, `path.*`, git). Converts
+ *   only where the host's separator is a backslash; on POSIX a backslash is a
+ *   filename character and is kept. `split(path.sep).join('/')` is exactly
+ *   this, so it autofixes here.
+ * - `toForwardSlashAnyPlatform(text)` — AUTHOR-WRITTEN text (an href, a glob, a
+ *   config value, an archive entry name). Converts every backslash on every
+ *   host. A literal-backslash `split('\\').join('/')`, `replaceAll('\\', '/')`
+ *   or `replace(/\\/g, '/')` is exactly this, so each autofixes here — never to
+ *   `toForwardSlash`, which would silently stop converting on POSIX.
+ *
+ * Whether a given literal-backslash site is really author text is the author's
+ * call; the fix preserves behaviour, and a native-path site should then be
+ * switched to `toForwardSlash` by hand.
  *
  * @example
  * // ❌ BAD - manual normalization
- * const normalized = relativePath.split(path.sep).join('/');
- * const normalized = somePath.split('\\').join('/');
+ * const a = relativePath.split(path.sep).join('/');
+ * const b = href.replaceAll('\\', '/');
  *
- * // ✅ GOOD - use utility function
- * import { toForwardSlash } from '@vibe-agent-toolkit/utils/path';
- * const normalized = toForwardSlash(relativePath);
+ * // ✅ GOOD - use the utility functions
+ * import { toForwardSlash, toForwardSlashAnyPlatform } from '@vibe-agent-toolkit/utils/path';
+ * const a = toForwardSlash(relativePath);
+ * const b = toForwardSlashAnyPlatform(href);
  */
 
 const {
@@ -26,22 +42,85 @@ const {
   resolveSafeModule,
 } = require('./safe-import.cjs');
 
-const SAFE_FN = 'toForwardSlash';
+const NATIVE_FN = 'toForwardSlash';
+const ANY_PLATFORM_FN = 'toForwardSlashAnyPlatform';
+const MESSAGE_FOR = { [NATIVE_FN]: 'useToForwardSlash', [ANY_PLATFORM_FN]: 'useToForwardSlashAnyPlatform' };
 const PATH_MODULES = new Set(['node:path', 'path']);
+const BACKSLASH = '\\';
+
+/** `.name(...)` on some receiver, with exactly `arity` arguments? */
+function isMethodCall(node, name, arity) {
+  return (
+    node?.type === 'CallExpression' &&
+    node.callee.type === 'MemberExpression' &&
+    node.callee.property.name === name &&
+    node.arguments.length === arity
+  );
+}
+
+function isStringLiteral(node, value) {
+  return node.type === 'Literal' && node.value === value;
+}
+
+/** `/\\/g` — one literal backslash, global. */
+function isGlobalBackslashRegex(node) {
+  return node.type === 'Literal' && node.regex?.pattern === String.raw`\\` && node.regex.flags.includes('g');
+}
+
+function isPathSep(node) {
+  return node.type === 'MemberExpression' && node.object.name === 'path' && node.property.name === 'sep';
+}
+
+/**
+ * `<x>.split(<sep>).join('/')` → the converter it is equivalent to.
+ *
+ * Splitting on a TWO-backslash SEQUENCE (e.g. collapsing a UNC server prefix)
+ * is a different operation that neither converter matches, so it is not
+ * reported.
+ */
+function matchSplitJoin(node) {
+  if (!isMethodCall(node, 'join', 1) || !isStringLiteral(node.arguments[0], '/')) return undefined;
+  const split = node.callee.object;
+  if (!isMethodCall(split, 'split', 1)) return undefined;
+  const [separator] = split.arguments;
+  if (isPathSep(separator)) return { receiver: split.callee.object, fn: NATIVE_FN };
+  if (isStringLiteral(separator, BACKSLASH)) return { receiver: split.callee.object, fn: ANY_PLATFORM_FN };
+  return undefined;
+}
+
+/** `<x>.replaceAll('\\', '/')` or `<x>.replace(/\\/g, '/')` → the any-platform converter. */
+function matchReplace(node) {
+  const isReplace = isMethodCall(node, 'replace', 2) || isMethodCall(node, 'replaceAll', 2);
+  if (!isReplace || !isStringLiteral(node.arguments[1], '/')) return undefined;
+  const [pattern] = node.arguments;
+  const allBackslashes =
+    isGlobalBackslashRegex(pattern) ||
+    (node.callee.property.name === 'replaceAll' && isStringLiteral(pattern, BACKSLASH));
+  return allBackslashes ? { receiver: node.callee.object, fn: ANY_PLATFORM_FN } : undefined;
+}
 
 module.exports = {
   meta: {
     type: 'problem',
     docs: {
-      description: 'Disallow manual path normalization patterns',
-      category: 'Cross-platform compatibility',
+      description:
+        'Disallow manual path normalization patterns',
+      category: 'Path handling',
+      bans: "hand-rolled `.replace(/\\\\/g, '/')` / `split(path.sep).join('/')`",
+      useInstead: '`toForwardSlash()` (native paths) / `toForwardSlashAnyPlatform()` (authored text)',
+      subpath: '/path',
       recommended: true,
+      recommendedSeverity: 'error',
     },
     fixable: 'code',
     messages: {
       useToForwardSlash:
         'Use toForwardSlash() from {{safeModule}} instead of manual path normalization. ' +
-        'Manual normalization is error-prone and less maintainable.',
+        'It converts a native path only where the host separator is a backslash.',
+      useToForwardSlashAnyPlatform:
+        'Use toForwardSlashAnyPlatform() from {{safeModule}} instead of a hand-rolled backslash replace. ' +
+        'If this string is a native filesystem/git path rather than authored text, use toForwardSlash() — ' +
+        'on POSIX a backslash is a filename character.',
       [DEAD_UNSAFE_IMPORT]: DEAD_UNSAFE_IMPORT_MESSAGE,
     },
     schema: [SAFE_MODULE_ONLY_SCHEMA],
@@ -50,24 +129,43 @@ module.exports = {
   create(context) {
     const sourceCode = context.getSourceCode();
     const targetModule = resolveSafeModule(context, SAFE_PATH_MODULE);
-    // Seeded from SCOPE: a file that already imports `toForwardSlash` from the
-    // barrel must have the call rewritten WITHOUT gaining a second binding of
-    // the same name — that is a SyntaxError. See `safe-import.cjs`.
-    let hasToForwardSlashImport = isNameAlreadyBound(sourceCode, SAFE_FN);
+    // Seeded from SCOPE: a file that already binds the name must have the call
+    // rewritten WITHOUT gaining a second binding of the same name — that is a
+    // SyntaxError. See `safe-import.cjs`.
+    const bound = {
+      [NATIVE_FN]: isNameAlreadyBound(sourceCode, NATIVE_FN),
+      [ANY_PLATFORM_FN]: isNameAlreadyBound(sourceCode, ANY_PLATFORM_FN),
+    };
     // Never mutated — the dead-import leg must not be armed by a flag that a
     // suppressed report's `fix()` can spend. See `dead-import.cjs`.
-    const safeBoundInSource = hasToForwardSlashImport;
+    const safeBoundInSource = bound[NATIVE_FN];
     // The dead-import leg's OTHER gate: a `toForwardSlash(…)` call is the text
-    // this fixer writes, and the only evidence available that it wrote it here.
-    // Without it, any file with `toForwardSlash` in scope armed the leg — see
-    // `dead-import.cjs`. Read from the source, never from a `fix()`.
+    // this fixer writes for `path.sep`, and the only evidence available that it
+    // wrote it here. Read from the source, never from a `fix()`.
     let safeReplacementCalled = false;
     let utilsImportNode = null;
     // `path.sep` is the last `path.*` reference in plenty of files, and
-    // `toForwardSlash(raw)` consumes it — leaving the same dead `node:path`
-    // binding the `safePath` rules used to leave.
+    // `toForwardSlash(raw)` consumes it — leaving a dead `node:path` binding.
     const pathImportNodes = [];
 
+    /**
+     * Add `fn` to the import, when nothing binds it yet.
+     *
+     * NOT latched: two reports insert identical text at the identical anchor, so
+     * ESLint applies one and drops the other as overlapping. Latching is not
+     * free — ESLint runs `fix()` for a SUPPRESSED problem before the
+     * `eslint-disable` filter discards it, so a latch could be spent by a report
+     * that is then thrown away.
+     */
+    function importFix(fixer, fn) {
+      if (bound[fn]) return [];
+      if (utilsImportNode) {
+        return [fixer.insertTextAfter(utilsImportNode.specifiers.at(-1), `, ${fn}`)];
+      }
+      const newImport = `import { ${fn} } from '${targetModule}';\n`;
+      return [insertAboveWithComments(fixer, sourceCode, sourceCode.ast.body[0], newImport)];
+    }
+
     return {
       'Program:exit'() {
         reportDeadUnsafeImports(
@@ -83,99 +181,30 @@ module.exports = {
         if (PATH_MODULES.has(node.source.value)) {
           pathImportNodes.push(node);
         }
-        if (node.source.value === targetModule) {
-          utilsImportNode = node;
-          for (const spec of node.specifiers) {
-            if (spec.type === 'ImportSpecifier' && spec.imported.name === SAFE_FN) {
-              hasToForwardSlashImport = true;
-            }
+        if (node.source.value !== targetModule) return;
+        utilsImportNode = node;
+        for (const spec of node.specifiers) {
+          if (spec.type === 'ImportSpecifier' && spec.imported.name in bound) {
+            bound[spec.imported.name] = true;
           }
         }
       },
 
       CallExpression(node) {
-        if (node.callee.type === 'Identifier' && node.callee.name === SAFE_FN) {
+        if (node.callee.type === 'Identifier' && node.callee.name === NATIVE_FN) {
           safeReplacementCalled = true;
         }
-
-        // Check for .split(...).join('/') pattern
-        if (
-          node.callee.type === 'MemberExpression' &&
-          node.callee.property.name === 'join' &&
-          node.arguments.length === 1 &&
-          node.arguments[0].type === 'Literal' &&
-          node.arguments[0].value === '/'
-        ) {
-          // Check if the object is a .split() call
-          const splitCall = node.callee.object;
-          if (
-            splitCall.type === 'CallExpression' &&
-            splitCall.callee.type === 'MemberExpression' &&
-            splitCall.callee.property.name === 'split' &&
-            splitCall.arguments.length === 1
-          ) {
-            const splitArg = splitCall.arguments[0];
-
-            // Split on path.sep, or on a single backslash character
-            // (source literal '\\'). Splitting on a two-backslash SEQUENCE
-            // (source literal '\\\\', decoded value: two backslash characters)
-            // is a different, rarer operation -- e.g. collapsing a UNC path's
-            // leading double-backslash server prefix -- and toForwardSlash()
-            // is not equivalent to it. Autofixing that case would silently
-            // change program behavior, so it is deliberately excluded here.
-            const isSplittingByPathSep =
-              (splitArg.type === 'MemberExpression' &&
-                splitArg.object.name === 'path' &&
-                splitArg.property.name === 'sep') ||
-              (splitArg.type === 'Literal' && splitArg.value === '\\');
-
-            if (isSplittingByPathSep) {
-              const variableBeingSplit = splitCall.callee.object;
-
-              context.report({
-                node,
-                messageId: 'useToForwardSlash',
-                data: { safeModule: targetModule },
-                fix(fixer) {
-                  const fixes = [];
-
-                  // Replace the entire .split(...).join('/') with toForwardSlash(...)
-                  const originalVar = sourceCode.getText(variableBeingSplit);
-                  fixes.push(fixer.replaceText(node, `${SAFE_FN}(${originalVar})`));
-
-                  // Add import if needed
-                  if (!hasToForwardSlashImport) {
-                    if (utilsImportNode) {
-                      // Add to existing utils import
-                      const lastSpecifier = utilsImportNode.specifiers.at(-1);
-                      fixes.push(fixer.insertTextAfter(lastSpecifier, `, ${SAFE_FN}`));
-                    } else {
-                      // Create new import at the top
-                      const firstNode = sourceCode.ast.body[0];
-                      const newImport = `import { ${SAFE_FN} } from '${targetModule}';\n`;
-                      fixes.push(insertAboveWithComments(fixer, sourceCode, firstNode, newImport));
-                    }
-                    // NOT latched. The comment here used to claim that without a
-                    // `hasToForwardSlashImport = true` a second occurrence would
-                    // insert the import twice; an adversarial run could not
-                    // reproduce that at any occurrence count. It cannot happen:
-                    // both reports insert identical text at the identical anchor,
-                    // so the ranges coincide and ESLint applies one and drops the
-                    // other as overlapping.
-                    //
-                    // Latching it is not free, either. ESLint runs `fix()` for a
-                    // SUPPRESSED problem before the `eslint-disable` filter
-                    // discards it, so the first report could spend the flag and
-                    // then be thrown away — leaving later occurrences rewritten
-                    // to a `toForwardSlash` nothing imports.
-                  }
-
-                  return fixes;
-                },
-              });
-            }
-          }
-        }
+        const match = matchSplitJoin(node) ?? matchReplace(node);
+        if (!match) return;
+        context.report({
+          node,
+          messageId: MESSAGE_FOR[match.fn],
+          data: { safeModule: targetModule },
+          fix(fixer) {
+            const receiver = sourceCode.getText(match.receiver);
+            return [fixer.replaceText(node, `${match.fn}(${receiver})`), ...importFix(fixer, match.fn)];
+          },
+        });
       },
     };
   },

package/eslint/rules/no-os-tmpdir.cjs

@@ -21,4 +21,12 @@ module.exports = factory({
   // No baked-in exemption: the file that implements normalizedTmpdir() is
   // repo-specific. Consumers declare it as { exemptFiles: [...] }.
   checkMemberExpression: true, // Catch os.tmpdir() pattern
+  docs: {
+    category: 'Filesystem and process',
+    bans: '`os.tmpdir()` (8.3 short names on Windows)',
+    useInstead: '`normalizedTmpdir()`',
+    subpath: '/fs',
+    recommended: true,
+    recommendedSeverity: 'error',
+  },
 });

package/eslint/rules/no-path-operations-in-comparisons.cjs

@@ -25,9 +25,14 @@ module.exports = {
   meta: {
     type: 'problem',
     docs: {
-      description: 'Disallow using path operations directly in string comparisons',
-      category: 'Cross-platform compatibility',
+      description:
+        'Disallow using path operations directly in string comparisons',
+      category: 'Path handling',
+      bans: 'raw `path.*()` results in string comparisons',
+      useInstead: 'wrap in `toForwardSlash()`',
+      subpath: '/path',
       recommended: true,
+      recommendedSeverity: 'error',
     },
     messages: {
       normalizePathOperation:

package/eslint/rules/no-path-sep-in-strings.cjs

@@ -25,9 +25,14 @@ module.exports = {
   meta: {
     type: 'problem',
     docs: {
-      description: 'Disallow using path.sep in string operations',
-      category: 'Cross-platform compatibility',
+      description:
+        'Disallow using path.sep in string operations',
+      category: 'Path handling',
+      bans: '`path.sep` embedded in a string literal',
+      useInstead: '`toForwardSlash()`',
+      subpath: '/path',
       recommended: true,
+      recommendedSeverity: 'error',
     },
     messages: {
       noPathSep:

package/eslint/rules/no-path-startswith.cjs

@@ -68,9 +68,14 @@ module.exports = {
   meta: {
     type: 'problem',
     docs: {
-      description: 'Disallow direct path.startsWith() without normalization',
-      category: 'Cross-platform compatibility',
+      description:
+        'Disallow direct path.startsWith() without normalization',
+      category: 'Path handling',
+      bans: '`path.startsWith()` on a raw path',
+      useInstead: '`toForwardSlash()` first',
+      subpath: '/path',
       recommended: true,
+      recommendedSeverity: 'error',
     },
     messages: {
       useNormalizeHelper:

package/eslint/rules/no-process-exit-in-phase.cjs

@@ -0,0 +1,127 @@
+/**
+ * ESLint Rule: no-process-exit-in-phase
+ *
+ * Forbid `process.exit()` inside a phase entry point — a function whose name
+ * ends in `Phase`.
+ *
+ * ## Why this rule exists
+ *
+ * `vat validate`, `vat verify` and `vat build` used to run each phase as a
+ * SEPARATE CHILD PROCESS. A `process.exit()` inside a phase was then perfectly
+ * safe: it ended that child, the parent read the exit code, and the run carried
+ * on to the next phase. Nothing about the code said so — the safety came
+ * entirely from the process boundary.
+ *
+ * That boundary is gone. Phases now run in the orchestrator's own process, so a
+ * surviving `process.exit()` ends THE WHOLE RUN: every later phase is silently
+ * skipped, the parent's aggregation never happens, and the process exits 0-or-1
+ * having done half the work with nothing in the document to say so. It is the
+ * worst shape of failure this codebase has — a confident, well-formed, wrong
+ * answer — and it cannot be caught by a type, because `process.exit()`
+ * typechecks anywhere.
+ *
+ * A phase must RETURN `{ document, exitCode }` and let its caller decide whether
+ * to print and exit (a command-line run) or to fold the result into the run (an
+ * orchestrated one).
+ *
+ * ## Why the name is the marker
+ *
+ * The `…Phase` suffix is the convention every phase entry point already follows
+ * (`runResourcesValidatePhase`, `runSkillsBuildPhase`, …). Keying the rule to it
+ * means a new phase is protected the moment it is named like one, with no list
+ * to keep in sync — a list is the thing that goes stale silently, which is the
+ * defect class this rule exists to prevent in the first place.
+ *
+ * The thin Commander wrappers that CALL these functions keep their
+ * `process.exit()`: deciding how the process ends is exactly their job, and they
+ * are not named `…Phase`.
+ */
+
+/** Does this call expression read as `process.exit(...)`? */
+function isProcessExitCall(node) {
+  const { callee } = node;
+  return (
+    callee.type === 'MemberExpression' &&
+    !callee.computed &&
+    callee.object.type === 'Identifier' &&
+    callee.object.name === 'process' &&
+    callee.property.type === 'Identifier' &&
+    callee.property.name === 'exit'
+  );
+}
+
+/**
+ * The declared name of a function-ish node, however it was declared.
+ *
+ * Covers the three spellings a phase entry point can legitimately take: a
+ * function declaration, a `const x = function () {}`, and a `const x = () => {}`.
+ * A rule that only understood declarations would be silently inert against an
+ * arrow const — the same blind spot `no-test-scoped-functions` documents.
+ */
+function functionName(node) {
+  if (node.id && node.id.type === 'Identifier') return node.id.name;
+
+  const { parent } = node;
+  if (parent && parent.type === 'VariableDeclarator' && parent.id.type === 'Identifier') {
+    return parent.id.name;
+  }
+  if (parent && parent.type === 'Property' && parent.key.type === 'Identifier') {
+    return parent.key.name;
+  }
+  return undefined;
+}
+
+const FUNCTION_TYPES = new Set([
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'ArrowFunctionExpression',
+]);
+
+/** The nearest enclosing function named like a phase entry point, if any. */
+function enclosingPhaseName(node) {
+  for (let current = node.parent; current; current = current.parent) {
+    if (!FUNCTION_TYPES.has(current.type)) continue;
+    const name = functionName(current);
+    if (name !== undefined && name.endsWith('Phase')) return name;
+  }
+  return undefined;
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Forbid process.exit() inside a phase entry point, where it would end the whole orchestrated run',
+      category: 'Process control',
+      bans: '`process.exit()` inside a function named `…Phase`',
+      useInstead: 'return the exit code from the phase; only the command wrapper exits',
+      // Not in `recommended`: it keys on a NAMING CONVENTION that is VAT's, not a
+      // portable fact. The hazard is real and general (an in-process orchestrator
+      // whose step calls `process.exit()` silently skips every later step), but
+      // the marker is the `…Phase` suffix, and an adopter with an unrelated
+      // `computeRenderPhase()` that legitimately exits would get a finding they
+      // cannot act on. VAT enables it explicitly, repo-wide, so a NEW phase is
+      // covered the moment it is named like one.
+      recommended: false,
+      recommendedSeverity: 'error',
+    },
+    fixable: null,
+    schema: [],
+    messages: {
+      exitInPhase:
+        "'{{name}}' is a phase entry point, so process.exit() here ends the ENTIRE run — every later phase is skipped and the orchestrator never aggregates. Return { document, exitCode } instead and let the caller decide how the process ends.",
+    },
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (!isProcessExitCall(node)) return;
+        const name = enclosingPhaseName(node);
+        if (name === undefined) return;
+        context.report({ node, messageId: 'exitInPhase', data: { name } });
+      },
+    };
+  },
+};