@vibe-agent-toolkit/utils 0.2.0-rc.2 → 0.2.0-rc.4

package/dist/timing-dump.js

@@ -0,0 +1,230 @@
+/**
+ * The on-disk plumbing every VAT timing seam shares.
+ *
+ * Two seams write per-process JSON dumps to an operator-named directory:
+ * `@vibe-agent-toolkit/resources`' `parse-timing.ts` (which pass inside a parser
+ * owns the time) and this package's `crawl-timing.ts` (which contributor or
+ * crawler owns the time). They sit in different packages because `crawl-timing`
+ * has to bracket `GitTracker`, which is here — so this module lives at the lower
+ * of the two and is exported for the higher one. What they
+ * MEASURE could not be less alike — one axis is a closed enum of parser passes,
+ * the other is an open set of contributor ids — but every property that makes
+ * the *file* trustworthy is identical between them, and the lab's
+ * `harness/dumps.ts` already says so from the reading end:
+ *
+ * 1. A directory that cannot be created is reported the moment the seam turns
+ *    on, while there is still a run to abandon — never at exit, where a failure
+ *    costs the whole measurement.
+ * 2. A dump failure is written to **stderr and never thrown**. These run from
+ *    an `exit` listener, where a throw changes the process's exit behaviour, and
+ *    they must never touch stdout, which carries vat's report.
+ * 3. A pid can file more than one dump, and the name is CLAIMED rather than
+ *    checked. `vat validate` spawns the vat binary once per phase and pids are
+ *    reused, so `<stem>-<pid>.json` genuinely collides; worse, worker threads
+ *    SHARE their parent's pid, so a thread pool's whole cohort competes for one
+ *    `<stem>-<pid>` sequence at the same instant. The name gains a counter
+ *    rather than overwriting, and the counter is settled by
+ *    {@link EXCLUSIVE_CREATE} so the OS — not a check-then-write gap — decides
+ *    who won it.
+ * 4. The process's own wall and CPU time is read ONCE, at dump time. It is a
+ *    lifetime figure for the process and never a duration of the measured work;
+ *    its value is the RATIO, which tells a reader whether the wall-timed
+ *    brackets above it were competing with a loaded machine.
+ *
+ *    ⚠️ **A reader must never SUM these across dumps.** Point 3 means one
+ *    command routinely files several, and a vat command's phase processes
+ *    overlap in time — so summing their lifetimes counts the same wall clock
+ *    more than once and produces a "total" longer than the command took. The
+ *    figure is per process, and the only honest aggregate over several is the
+ *    per-process ratio read one dump at a time. The `crawl` facet keeps one
+ *    record per dump and publishes no total for exactly this reason; `parse`
+ *    still sums, which is review finding F2 (2026-08-14) and is annotated at
+ *    `facets/parse/dump.ts`. This list is where both seams learn what makes a
+ *    dump trustworthy, so the hazard belongs here rather than only beside the
+ *    consumer that already fixed it.
+ *
+ * Writing that twice would give two seams two chances to diverge on the one
+ * thing a reader has to be able to trust identically. What each seam keeps for
+ * itself is its accumulator shape, its dump body and the noun it is called by.
+ */
+import { writeFileSync } from 'node:fs';
+import { safePath } from './path-core.js';
+import { mkdirSyncReal } from './path-utils.js';
+/** `process.cpuUsage()` reports microseconds; a dump reports milliseconds. */
+const MICROSECONDS_PER_MS = 1000;
+/** `process.uptime()` reports seconds; a dump reports milliseconds. */
+const MS_PER_SECOND = 1000;
+/**
+ * Ceiling on the pid-collision search. A directory holding this many dumps for
+ * one pid is a runaway, not a collision, and giving up on a reported line is a
+ * better outcome than spinning.
+ *
+ * Exhausting it does NOT fall back to overwriting the last slot. That was the
+ * old behaviour, and it destroyed a dump for the same reason the check-then-
+ * write gap did — silently, and precisely when the directory was busiest.
+ */
+export const MAX_DUMP_COLLISIONS = 1000;
+/**
+ * The `writeFileSync` flag that makes claiming a name atomic.
+ *
+ * `wx` is create-exclusive: the OS fails the call with `EEXIST` when the path
+ * already exists, so exactly one caller wins each name no matter how many are
+ * racing for it. Asking `existsSync` first and writing second is two operations
+ * with a gap in between, and threads sharing a pid land in that gap routinely —
+ * a measured 8-worker parse pool lost 6 of 9 dumps to it, reporting 44 of 172
+ * documents as if that were the whole run.
+ */
+const EXCLUSIVE_CREATE = 'wx';
+/** How the failure line names the ceiling case, so it reads unlike an OS error. */
+const CEILING_DETAIL = `every name up to the ${String(MAX_DUMP_COLLISIONS)}-collision ceiling was already claimed`;
+/**
+ * Reduce a raw env value to a directory or `null`.
+ *
+ * An empty-string value counts as absent: `VAT_PARSE_TIMING=` in a shell profile
+ * is a variable somebody meant to unset, not a request to dump into the process's
+ * working directory.
+ *
+ * @param raw - The env var's value, if set
+ * @returns The dump directory, or `null` when the seam is off
+ */
+export function normalizeTimingDirectory(raw) {
+    return raw === undefined || raw === '' ? null : raw;
+}
+/**
+ * Report a dump problem on stderr.
+ *
+ * Never throws and never touches stdout: vat's stdout carries a YAML report, and
+ * an exit handler that threw would change the process's exit behaviour.
+ *
+ * @param noun - What the seam is called, so a reader knows which instrument failed
+ * @param target - Path the failure concerns
+ * @param error - Whatever was caught
+ */
+export function reportTimingDumpFailure(noun, target, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`vat: ${noun} dump failed for ${target}: ${detail}\n`);
+}
+/**
+ * Create the dump directory, swallowing failure.
+ *
+ * Done once when the seam turns on rather than at exit, so a bad path is
+ * reported while there is still a run to abandon — and so the exit handler does
+ * the minimum possible work.
+ *
+ * @param noun - What the seam is called, for the failure line
+ * @param directory - Directory dumps will be written to
+ */
+export function ensureTimingDirectory(noun, directory) {
+    try {
+        mkdirSyncReal(directory, { recursive: true });
+    }
+    catch (error) {
+        reportTimingDumpFailure(noun, directory, error);
+    }
+}
+/**
+ * Read this process's lifetime wall and CPU time.
+ *
+ * Called ONCE per dump — two syscalls for a whole run, which is why the process
+ * level can afford a CPU reading that a per-bracket level cannot. Deliberately
+ * not an accumulator and deliberately not reset: it describes the process, not
+ * the measurement window.
+ *
+ * @returns Wall clock and CPU since process start, in milliseconds
+ */
+export function readTimingProcess() {
+    const cpu = process.cpuUsage();
+    return {
+        wallMs: process.uptime() * MS_PER_SECOND,
+        cpuUserMs: cpu.user / MICROSECONDS_PER_MS,
+        cpuSystemMs: cpu.system / MICROSECONDS_PER_MS,
+    };
+}
+/**
+ * The nth candidate name in one pid's dump sequence.
+ *
+ * @param directory - Directory dumps are written to
+ * @param stem - Basename and pid, already joined
+ * @param collision - 0 for the unsuffixed name, then the collision counter
+ * @returns The candidate path
+ */
+function timingDumpCandidate(directory, stem, collision) {
+    const suffix = collision === 0 ? '' : `-${String(collision)}`;
+    return safePath.join(directory, `${stem}${suffix}.json`);
+}
+/**
+ * Whether a caught write failure means somebody else already holds the name.
+ *
+ * @param error - Whatever `writeFileSync` threw
+ * @returns `true` only for `EEXIST`, which is a lost race and not a fault
+ */
+function isNameAlreadyTaken(error) {
+    return error instanceof Error && 'code' in error && error.code === 'EEXIST';
+}
+/**
+ * Claim a name by creating it, and fill it in the same operation.
+ *
+ * Choosing the name and writing it CANNOT be two steps: whatever separates them
+ * is a window in which another writer takes the name that was just declared
+ * free, and the loser's dump disappears with no error raised anywhere. So each
+ * candidate is written create-exclusively ({@link EXCLUSIVE_CREATE}) and an
+ * `EEXIST` — the OS saying somebody else got there — advances to the next
+ * counter rather than overwriting.
+ *
+ * @param directory - Directory dumps are written to
+ * @param basename - Basename stem; the pid and any collision counter follow
+ * @param contents - The already-serialized dump body
+ * @returns Which name was claimed, or why none could be
+ */
+function claimTimingDump(directory, basename, contents) {
+    const stem = `${basename}-${String(process.pid)}`;
+    for (let collision = 0; collision <= MAX_DUMP_COLLISIONS; collision += 1) {
+        const candidate = timingDumpCandidate(directory, stem, collision);
+        try {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- operator-supplied diagnostic directory from a VAT_*_TIMING variable
+            writeFileSync(candidate, contents, { encoding: 'utf-8', flag: EXCLUSIVE_CREATE });
+            return { outcome: 'written', path: candidate };
+        }
+        catch (error) {
+            if (!isNameAlreadyTaken(error))
+                return { outcome: 'failed', path: candidate, error };
+        }
+    }
+    return {
+        outcome: 'exhausted',
+        path: timingDumpCandidate(directory, stem, MAX_DUMP_COLLISIONS),
+    };
+}
+/**
+ * Write one seam's dump, if the seam is on.
+ *
+ * The body is built lazily, inside this call, so a disabled seam never pays to
+ * snapshot accumulators nobody will read — and a `build` that throws is reported
+ * like any other failure, because this runs from an `exit` listener where a
+ * throw would change the process's exit behaviour.
+ *
+ * @param noun - What the seam is called, for any failure line
+ * @param directory - Where to write, or `null` when the seam is off
+ * @param basename - Basename stem for the file
+ * @param build - Produces the dump body
+ * @returns The path written, or `null` when the seam is off or nothing was written
+ */
+export function writeTimingDump(noun, directory, basename, build) {
+    if (directory === null)
+        return null;
+    let claim;
+    try {
+        claim = claimTimingDump(directory, basename, `${JSON.stringify(build(), null, 2)}\n`);
+    }
+    catch (error) {
+        // Only `build()` and its serialization can reach here; every filesystem
+        // failure is already an outcome rather than a throw.
+        reportTimingDumpFailure(noun, directory, error);
+        return null;
+    }
+    if (claim.outcome === 'written')
+        return claim.path;
+    reportTimingDumpFailure(noun, claim.path, claim.outcome === 'exhausted' ? CEILING_DETAIL : claim.error);
+    return null;
+}
+//# sourceMappingURL=timing-dump.js.map

package/dist/timing-dump.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing-dump.js","sourceRoot":"","sources":["../src/timing-dump.ts"],"names":[],"mappings":"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"}

package/eslint/README.md

@@ -25,7 +25,7 @@ export default [
 ];
 ```
 
-`configs.recommended` registers the plugin under the `@vibe-agent-toolkit` namespace and enables the **cross-platform safety core** — 18 of the 21 rules, most at `error` and three at `warn` (see [Severities](#severities)). The other three are opt-in; the [rule tables](#rules) mark each rule's `recommended` severity, and `—` means not in `recommended`.
+`configs.recommended` registers the plugin under the `@vibe-agent-toolkit` namespace and enables the **cross-platform safety core** — 18 of the 22 rules, most at `error` and three at `warn` (see [Severities](#severities)). The other four are opt-in; the [rule tables](#rules) mark each rule's `recommended` severity, and `—` means not in `recommended`.
 
 To pick rules yourself, register the plugin and name them:
 
@@ -111,6 +111,21 @@ Two ways your target can be wrong, which surface differently: `ERR_MODULE_NOT_FO
 | `no-fs-promises-cp` | `cp()` from `node:fs/promises` (drops nested files on Node 22) | `cpSync()` from `node:fs` | — | ✓ | `error` |
 | `no-child-process-execSync` | `child_process.execSync()` | `safeExecSync()` | `/process` | ✓ | `error` |
 | `no-unix-shell-commands` | `tar`, `grep`, `rm`, `echo`, … spawned directly | Node APIs, or a portable script fixture | — | | `error` |
+| `no-bare-symlink-in-tests` | unguarded `fs.symlinkSync()` / `fs.promises.symlink()` | in tests: `createSymlink(cap, …)` / `createSymlinkAsync(cap, …)`; in shipped code: a win32 junction, or a `catch` naming the privilege | `/testing` | | — |
+
+**`no-bare-symlink-in-tests` reports two different remedies, and the name is narrower than the rule.**
+Creating a symlink on Windows requires `SeCreateSymbolicLinkPrivilege` — Developer Mode or an
+elevated shell — which most user machines and CI agents lack. In a **test file** the fix is to probe
+with `symlinkCapability()` and pass the resulting token to `createSymlink()`, so a host without the
+privilege produces a visible `skip()` rather than a failure or a silently-swallowed one. In **shipped
+code** there is deliberately no wrapper to route through: `createSymlink()` lives on the `/testing`
+subpath, and pointing production code at a test helper would be worse advice than the bare call.
+There the guidance is a junction for a directory link on win32 (no elevation required), or catching
+the failure and naming the missing privilege. Declaring a platform out of scope is legitimate —
+say so in an `eslint-disable` justification, which is what `vat agent install --dev` does.
+
+`exemptFiles` matters here: the implementation file holding the sanctioned `symlinkSync` is not a
+test file, so it needs an explicit exemption once the rule covers shipped code.
 
 The member-call rules here check the **receiver**, not just the method name, so `env.tmpdir()` on some unrelated object is not a finding — and the namespace they check for can be bound by a static `import * as os`, by `const os = require('node:os')`, or by `const os = await import('node:os')`. The fix replaces the whole callee (`os.tmpdir()` → `normalizedTmpdir()`), which is correct however the binding was made. Matching the method name alone was the earlier behaviour and it produced `os.normalizedTmpdir()` — a method that does not exist, compiles, and throws.
 
@@ -122,6 +137,63 @@ The member-call rules here check the **receiver**, not just the method name, so
 | `no-bare-dynamic-import-path` | `await import(absolutePath)` | `dynamicImportPath()` / `pathToFileURL(p).href` | `/fs` | | `error` |
 | `no-file-url-string-concat` | `` `file://${p}` `` | `pathToFileURL(p).href` | — | | `error` |
 
+### Content decoding
+
+| Rule | Bans | Use instead | Subpath | Fix | `recommended` |
+|---|---|---|---|---|---|
+| `no-raw-text-decode` | `buf.toString('utf-8')`, `new TextDecoder(…)`, `readFile(p, 'utf-8')` | one project-owned decoding seam | — | | — |
+
+`buf.toString('utf-8')` ignores every byte-order mark and cannot express UTF-16BE at all — Node's `Buffer` has no such encoding. A UTF-16 document therefore decodes to NUL-interleaved mojibake, and whatever sniffs for binary content downstream believes it. PowerShell 5.1's `Out-File` and `>` write UTF-16LE by default, so this is a Windows-authored file, not an exotic one.
+
+This rule has no wrapper to point at, because the seam is yours: write one decoder, name it with `safeModule`, and exempt its own file with `exemptFiles`. Put the decoder at the **bottom** of your dependency arrow — a seam in a leaf package cannot be imported by the primitive packages the rule also lints, and those files would then have no legal way to comply.
+
+**Not every `'utf-8'` read is a content read**, and this is the distinction that decides whether the rule survives. Three categories:
+
+1. **A document you did not write** — an adopter's markdown, config, schema, `.gitignore`, `package.json`. The encoding must be **discovered**. This is the rule's target.
+2. **An artifact your project wrote** — its own cache entry, its own published asset. The encoding was **chosen at the write**; reading it back the same way is a closed loop.
+3. **Bytes that were never a file** — subprocess stdout, an HTTP body, a Buffer you built. The **producer's contract** decides.
+
+Static analysis cannot tell them apart, so the rule reports all three and you settle 2 and 3 at the call site with a one-line `eslint-disable-next-line` that **names the writer or the producer**:
+
+```js
+// eslint-disable-next-line @vibe-agent-toolkit/no-raw-text-decode -- subprocess stdout; producer is the credential helper spawned above
+const out = result.stdout.toString('utf8');
+```
+
+That gives a reviewer a falsifiable test: a justification that cannot name who wrote the bytes is a category-1 call wearing a disable comment. Do not settle these by adding paths to `exemptFiles` — that list is for the seam's own implementation file.
+
+```js
+{
+  files: ['src/corpus/**/*.ts'],
+  rules: {
+    '@vibe-agent-toolkit/no-raw-text-decode': ['error', {
+      safeModule: '@my-org/resources',
+      exemptFiles: ['src/corpus/text-content.ts'],
+    }],
+  },
+}
+```
+
+Only a string **literal** encoding triggers it. `buf.toString(enc)` is deliberately not reported: without type information it is indistinguishable from `n.toString(radix)`, and `readFile(p, cb)` from `readFile(p, encoding)`.
+
+### Build correctness
+
+| Rule | Bans | Use instead | Subpath | Fix | `recommended` |
+|---|---|---|---|---|---|
+| `no-self-package-import` | importing the enclosing package by its own name | a relative path to the defining module | — | | — (needs `packageName`) |
+
+A file inside `packages/foo` that writes `import … from '@scope/foo'` resolves out through `node_modules` to its own `package.json`, whose `types` point at `./dist/index.d.ts` — a file the compiler is in the middle of producing. It works only by a TypeScript courtesy: while `dist` **is** the running project's output path, that declaration is recognised as the project's own output and the import is redirected back to `src`, so it resolves with no `dist/` on disk.
+
+Change `outDir` — to a staging directory that makes emit atomic, say — and the redirect is gone, tsc looks for a literal `dist/index.d.ts`, and a tree that has never been built has none:
+
+```
+error TS2307: Cannot find module '@scope/foo' or its corresponding type declarations.
+```
+
+The knock-on `TS2339`s land wherever a local type extended one of the now-unresolved imports, which is what makes it read as a type bug in code nobody touched.
+
+It is latent by construction, and worse, **it is invisible to any tree that has built before**: a stale `dist/` satisfies the literal lookup, so the build passes by typechecking against the *previous* build's declarations. In a monorepo whose worktrees live inside the main checkout, resolution walks up past the worktree and satisfies it from the *parent checkout's* `dist/`. Both are green locally and red in CI, which is the only genuinely pristine tree. Lint is the only stage that sees it on the author's machine.
+
 ### Code and test hygiene
 
 | Rule | Bans | Use instead | Subpath | Fix | `recommended` |
@@ -132,7 +204,7 @@ The member-call rules here check the **receiver**, not just the method name, so
 
 ### What `recommended` deliberately leaves out
 
-Three rules ship without riding in `recommended`, for two different reasons.
+Six rules ship without riding in `recommended`, for five different reasons.
 
 **Test-style opinions** — `no-test-scoped-functions` (where a helper may be declared) and `require-justified-skip` (the annotation grammar for a disabled test). Neither is a portability or correctness fact, and installing this package for `safePath.join()` should not also import someone else's test conventions. Both are worth turning on deliberately.
 
@@ -147,7 +219,27 @@ safePath.join(base, userInput)              // SILENT — the shape it exists to
 
 A rule that misses its own target does not belong in a config named `recommended` at any severity: a safety core that cries wolf teaches people to ignore it, and that costs you the true positives too. It still ships, and it still earns `error` when scoped to directories where a path escape is a security boundary — which is how this repo uses it, on its skill-test staging code. It will return to `recommended` when it keys on taint rather than on naming.
 
-Enable any of the three by naming it:
+**No wrapper to point at** — `no-raw-text-decode`. Every other rule in this pack names a replacement this package publishes; this one names a decoding seam that only exists once *you* write it. Shipped in `recommended`, its every message would read "use `decodeTextContent()` from your content-decoding module", which is advice nobody can follow. Turn it on with `safeModule` and `exemptFiles` set, as shown above.
+
+**Needs an option, and only in the directories you compile** — `no-self-package-import`. The import it bans is a genuine build-breaker with no style opinion in it, but the rule cannot discover on its own which package a file is in: reading `package.json` would mean `require('node:fs')`, and every module on this subpath is plain data that requires *nothing* — not `eslint`, not a third-party package, not even a Node builtin. That is what keeps `eslint` an optional peer dependency and lets these rules ship as a subpath of a runtime package rather than as one of their own. So the caller names the package. The caller is a config file, which already runs in full Node and can read every manifest it likes:
+
+```js
+import { readFileSync, readdirSync } from 'node:fs';
+
+export default readdirSync('packages').flatMap((dir) => {
+  const { name } = JSON.parse(readFileSync(`packages/${dir}/package.json`, 'utf8'));
+  return [{
+    files: [`packages/${dir}/src/**/*.ts`],
+    rules: { '@vibe-agent-toolkit/no-self-package-import': ['error', { packageName: name }] },
+  }];
+});
+```
+
+Scope it to the sources you **compile**. Test and example trees — normally excluded from the build — import their own package by name **on purpose**, to exercise the public entry point exactly as a consumer does. This repo has ~10 such imports, every one of them correct.
+
+**Half its advice is unreachable without a helper you may not have** — `no-bare-symlink-in-tests`. In a test file it points at `createSymlink()` / `createSymlinkAsync()`, which live on *this* package's `./testing` subpath and route through a probed capability token; an adopter on a different test runner, or with no symlink-heavy tests, should not silently inherit that opinion — nor the vitest-specific `skip()` idiom the message names. Its **shipped-code** half (`unguardedSymlink`) carries neither dependency and is portable advice on its own, so this is the one exclusion that is half arbitrary; it stays out because the two halves cannot be enabled separately. This repo turns it on explicitly, scoped to its own test-file convention.
+
+Enable any of the six by naming it:
 
 ```js
 import vat from '@vibe-agent-toolkit/utils/eslint';
@@ -160,6 +252,16 @@ export default [
       '@vibe-agent-toolkit/require-justified-skip': 'error',
     },
   },
+  {
+    // Scope it to the code that reads files whose encoding you do not choose.
+    files: ['src/corpus/**/*.ts'],
+    rules: {
+      '@vibe-agent-toolkit/no-raw-text-decode': ['error', {
+        safeModule: '@my-org/resources',
+        exemptFiles: ['src/corpus/text-content.ts'],
+      }],
+    },
+  },
   {
     // Scope it to where an escape is a security boundary, not repo-wide.
     files: ['src/staging/**/*.ts'],

package/eslint/index.cjs

@@ -50,7 +50,11 @@ const rules = {
   'no-file-url-string-concat': require('./rules/no-file-url-string-concat.cjs'),
   'prefer-startswith-over-regex': require('./rules/prefer-startswith-over-regex.cjs'),
   'no-unsafe-root-join': require('./rules/no-unsafe-root-join.cjs'),
+  'no-raw-text-decode': require('./rules/no-raw-text-decode.cjs'),
+  'no-self-package-import': require('./rules/no-self-package-import.cjs'),
   'require-justified-skip': require('./rules/require-justified-skip.cjs'),
+  'no-bare-symlink-in-tests': require('./rules/no-bare-symlink-in-tests.cjs'),
+  'no-process-exit-in-phase': require('./rules/no-process-exit-in-phase.cjs'),
 };
 
 /**
@@ -95,6 +99,52 @@ const RECOMMENDED_EXCLUDE = new Set([
   // a security boundary (this repo scopes it to the skill-test staging code).
   // Re-include it when it keys on taint rather than on naming.
   'no-unsafe-root-join',
+  // Excluded because it names a seam that does not exist until a consumer builds
+  // one. `decodeTextContent()` is VAT's module, in VAT's repo; an adopter who
+  // installed this package for `safePath.join()` has no content-decoding seam to
+  // be pointed at, so `recommended` would hand them a rule whose every message
+  // advises importing from `your content-decoding module`. It ships in `rules`
+  // and is enabled — with `safeModule` naming the real seam and `exemptFiles`
+  // naming the file that implements it — by whoever has one. VAT itself does
+  // exactly that, scoped to the directories that read corpus documents.
+  'no-raw-text-decode',
+  // Excluded for two reasons, either of which would be enough. It REQUIRES a
+  // `packageName` option — it will not read a `package.json` to find out, because
+  // that would mean `require('node:fs')` and break the empty-external-set property
+  // this whole subpath rests on — and a rule with a required option cannot ride in
+  // a config that supplies none. And the directories it must not fire in are a
+  // property of the adopter's `tsconfig`, not of this package: a self-import only
+  // breaks the build in files the package actually COMPILES, while test and
+  // example trees import their own package by name on purpose, to exercise the
+  // public entry point the way a consumer does. This repo has ~10 such imports
+  // across `utils`, `agent-skills`, `claude-marketplace` and
+  // `vat-example-cat-agents`, every one of them correct. It ships in `rules`, and
+  // `eslint.config.js` generates one scoped block per workspace package.
+  'no-self-package-import',
+  // Excluded for its TEST half only, which is the honest way to say it. That
+  // half names a vitest-specific idiom (`skip()` from the per-test context) and
+  // a replacement — `createSymlink()` / `createSymlinkAsync()` /
+  // `symlinkCapability()` — living on THIS package's own `./testing` subpath
+  // rather than on a seam every consumer already has. An adopter using a
+  // different test runner, or no symlink-heavy tests at all, should not
+  // silently inherit an opinion about vitest control flow.
+  //
+  // ⚠️ The rule now covers SHIPPED code too, and that half (`unguardedSymlink`)
+  // has neither dependency: it names the Windows privilege and a junction, both
+  // portable facts. So this exclusion is weaker than it reads — the two halves
+  // share one rule id and cannot be enabled separately, and the test half is
+  // what keeps the pair out. Splitting the rule would let the production half
+  // ride in `recommended`; that is a public-API change and has not been made.
+  // VAT enables the whole rule explicitly, scoped to its own conventions.
+  'no-bare-symlink-in-tests',
+  // Excluded because it keys on a NAMING CONVENTION that is VAT's, not a
+  // portable fact — the same reason `no-unsafe-root-join` is excluded above. The
+  // hazard it guards 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. It ships in
+  // `rules` and VAT enables it explicitly, scoped to its own orchestrators.
+  'no-process-exit-in-phase',
 ]);
 
 /**

package/eslint/index.d.cts

@@ -47,10 +47,20 @@ declare namespace plugin {
     rules: Record<string, RuleModule>;
     configs: {
       /**
-       * The cross-platform safety core: 18 of the 21 rules, 15 `error` / 3 `warn`.
-       * `no-test-scoped-functions` and `require-justified-skip` are excluded — they
-       * are positions on test style, not portability facts. Both still ship in
-       * `rules` and are enabled by naming them.
+       * The cross-platform safety core: 18 of the 25 rules, 15 `error` / 3 `warn`.
+       *
+       * Seven are excluded, for four reasons. `no-test-scoped-functions`,
+       * `require-justified-skip` and `no-bare-symlink-in-tests` are positions on
+       * TEST STYLE rather than portability facts. `no-unsafe-root-join` and
+       * `no-process-exit-in-phase` key on NAMING rather than on the property they
+       * care about (taint, and an orchestrated call site). `no-raw-text-decode`
+       * names a decoding SEAM that only exists in the consuming repo. And
+       * `no-self-package-import` REQUIRES an option this config cannot supply.
+       *
+       * All seven still ship in `rules` and are enabled by naming them — which is
+       * what this repo's own `eslint.config.js` does. The count above is asserted
+       * by `packages/utils/test/eslint/rules.test.ts`, so it cannot drift
+       * unnoticed the way it did when this comment said "four".
        */
       recommended: FlatConfig;
     };