diff --git a/.config/lockstep.schema.json b/.config/lockstep.schema.json
new file mode 100644
index 0000000..f0b7689
--- /dev/null
+++ b/.config/lockstep.schema.json
@@ -0,0 +1,463 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/SocketDev/lockstep.schema.json",
+  "title": "lockstep manifest",
+  "description": "Unified lock-step manifest shared across Socket repos. One schema, all cases — the `kind` discriminator on each row selects which flavor of lock-step applies. Single-file manifests work for repos with one cohesive concern; the `includes[]` field carves a manifest into per-area files (e.g. lockstep-acorn.json + lockstep-build.json) when one repo tracks multiple independent concerns.",
+  "type": "object",
+  "required": ["rows"],
+  "properties": {
+    "$schema": {
+      "description": "JSON Schema reference for editor autocompletion. Conventionally `./lockstep.schema.json` — both the manifest and its schema live side-by-side at repo root.",
+      "type": "string"
+    },
+    "description": {
+      "description": "Human-readable description of what this manifest tracks. Read by humans, not parsed. One short paragraph.",
+      "type": "string"
+    },
+    "area": {
+      "description": "Optional label for this manifest file. Used as a grouping key in harness output (per-area summaries). Defaults to 'root' for the top-level file and to the filename stem (with the `lockstep-` prefix stripped) for included files.",
+      "type": "string"
+    },
+    "includes": {
+      "description": "Relative paths to sub-manifests. The harness loads each and merges its rows into a single flattened view. Top-level `upstreams` and `sites` maps override any same-keyed entries from included manifests (top wins on conflict).",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "upstreams": {
+      "description": "Named upstream submodules. Each entry pairs a submodule path with its repo URL. Referenced by rows[].upstream on file-fork / version-pin / feature-parity / spec-conformance rows. Omit when the manifest only has lang-parity rows.",
+      "type": "object",
+      "patternProperties": {
+        "^(.*)$": {
+          "additionalProperties": false,
+          "description": "A submodule + its upstream repo URL. Referenced by file-fork / version-pin / feature-parity / spec-conformance rows via `upstream`.",
+          "type": "object",
+          "required": ["submodule", "repo"],
+          "properties": {
+            "submodule": {
+              "description": "Submodule path, relative to repo root. Must match an entry in `.gitmodules`.",
+              "type": "string"
+            },
+            "repo": {
+              "pattern": "^https?://[^/\\s]+",
+              "description": "Upstream repository URL (http:// or https:// + host). Anchored at the host so empty URLs fail validation rather than failing at git-fetch time.",
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "sites": {
+      "description": "Named sibling ports (typically per-language: `cpp`, `go`, `rust`, `typescript`). Referenced by rows[].ports.<site> on lang-parity rows. Omit when the manifest has no lang-parity rows.",
+      "type": "object",
+      "patternProperties": {
+        "^(.*)$": {
+          "additionalProperties": false,
+          "description": "A sibling port (typically per-language). Referenced by lang-parity rows via `ports.<site-key>`.",
+          "type": "object",
+          "required": ["path"],
+          "properties": {
+            "path": {
+              "description": "Path to the port's root directory, relative to repo root. The harness reads files under this path when checking the port's assertions.",
+              "type": "string"
+            },
+            "language": {
+              "description": "Language label for human reports (e.g. `cpp`, `go`, `rust`, `typescript`). The harness does no language-specific processing — it's purely informational.",
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "rows": {
+      "description": "The actual checks the harness runs. Empty array is valid (and expected for repos that have no upstream relationships — e.g. socket-cli's empty rows).",
+      "type": "array",
+      "items": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "description": "A local file derived from an upstream file with intentional modifications. Drift = upstream moved forward on this path; we may need to cherry-pick or update our deviations.",
+            "type": "object",
+            "required": [
+              "kind",
+              "id",
+              "upstream",
+              "local",
+              "upstream_path",
+              "forked_at_sha",
+              "deviations"
+            ],
+            "properties": {
+              "kind": {
+                "const": "file-fork",
+                "type": "string"
+              },
+              "id": {
+                "pattern": "^[a-z0-9][a-z0-9-]*(/[A-Za-z0-9_-]+)?$",
+                "description": "Stable identifier, unique within the manifest. Kebab-case (lowercase letters / digits / hyphens). For ids that mirror an external API name, use a namespace prefix: `api/findNodeAt`, `node/parseURL`. The slash separates the kebab namespace from the free-form leaf.",
+                "type": "string"
+              },
+              "upstream": {
+                "description": "Key into the top-level `upstreams` map. The harness errors if no matching upstream entry exists.",
+                "type": "string"
+              },
+              "criticality": {
+                "minimum": 1,
+                "maximum": 10,
+                "description": "Stay-in-step importance. Anchors: 1 = cosmetic / nice-to-have; 5 = behavioral parity expected; 10 = security-sensitive. The harness surfaces high-criticality drift louder and gates feature-parity rows on the criticality/10 floor.",
+                "type": "integer"
+              },
+              "conformance_test": {
+                "description": "Path (relative to repo root) of a test that enforces behavior parity (modulo documented deviations). Strongly recommended — static checks catch syntactic drift, not behavioral. A row without a conformance test relies entirely on code-pattern / fixture-snapshot checks.",
+                "type": "string"
+              },
+              "notes": {
+                "description": "Free-form context: why this row exists, gotchas, links to related issues / PRs / upstream discussions. Read by humans, not by the harness.",
+                "type": "string"
+              },
+              "local": {
+                "description": "Path (relative to repo root) of our ported copy of the upstream file.",
+                "type": "string"
+              },
+              "upstream_path": {
+                "description": "Path within the upstream submodule (relative to the submodule root) of the source file we forked from.",
+                "type": "string"
+              },
+              "forked_at_sha": {
+                "pattern": "^[0-9a-f]{40}$",
+                "description": "Full 40-char SHA of the upstream commit we forked from. The harness runs `git log <sha>..HEAD -- <upstream_path>` inside the submodule to surface drift.",
+                "type": "string"
+              },
+              "deviations": {
+                "minItems": 1,
+                "description": "Human-readable list of intentional differences from upstream. Zero deviations = the file should not be forked; consume upstream directly. Each entry is one short sentence (e.g. `swap require() for import` or `remove Node 14 fallback`).",
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          {
+            "additionalProperties": false,
+            "description": "A submodule pinned to an upstream release. Drift = upstream cut a new release we haven't adopted.",
+            "type": "object",
+            "required": [
+              "kind",
+              "id",
+              "upstream",
+              "pinned_sha",
+              "upgrade_policy"
+            ],
+            "properties": {
+              "kind": {
+                "const": "version-pin",
+                "type": "string"
+              },
+              "id": {
+                "pattern": "^[a-z0-9][a-z0-9-]*(/[A-Za-z0-9_-]+)?$",
+                "description": "Stable identifier, unique within the manifest. Kebab-case (lowercase letters / digits / hyphens). For ids that mirror an external API name, use a namespace prefix: `api/findNodeAt`, `node/parseURL`. The slash separates the kebab namespace from the free-form leaf.",
+                "type": "string"
+              },
+              "upstream": {
+                "description": "Key into the top-level `upstreams` map. The harness errors if no matching upstream entry exists.",
+                "type": "string"
+              },
+              "criticality": {
+                "minimum": 1,
+                "maximum": 10,
+                "description": "Stay-in-step importance. Anchors: 1 = cosmetic / nice-to-have; 5 = behavioral parity expected; 10 = security-sensitive. The harness surfaces high-criticality drift louder and gates feature-parity rows on the criticality/10 floor.",
+                "type": "integer"
+              },
+              "conformance_test": {
+                "description": "Path (relative to repo root) of a test that enforces behavior parity (modulo documented deviations). Strongly recommended — static checks catch syntactic drift, not behavioral. A row without a conformance test relies entirely on code-pattern / fixture-snapshot checks.",
+                "type": "string"
+              },
+              "notes": {
+                "description": "Free-form context: why this row exists, gotchas, links to related issues / PRs / upstream discussions. Read by humans, not by the harness.",
+                "type": "string"
+              },
+              "pinned_sha": {
+                "pattern": "^[0-9a-f]{40}$",
+                "description": "Full 40-char SHA the submodule is pinned to. Authoritative — the harness compares this against the submodule HEAD, not against `pinned_tag`.",
+                "type": "string"
+              },
+              "pinned_tag": {
+                "description": "Human-readable release tag for reports / PR titles (e.g. `v3.2.1`). Informational only — `pinned_sha` is the source of truth. Useful when an upstream cuts a release without changing semver but moves the SHA.",
+                "type": "string"
+              },
+              "upgrade_policy": {
+                "description": "`track-latest` = any new release is actionable; updating-lockstep auto-bumps. `major-gate` = patch / minor auto-bump; major bumps surfaced as advisory. `locked` = explicit decision per upgrade; the harness reports drift but never auto-bumps. Pick `locked` when bumping is gated on a coordinated change in another repo (e.g. Node vendoring temporal-rs).",
+                "anyOf": [
+                  {
+                    "const": "track-latest",
+                    "type": "string"
+                  },
+                  {
+                    "const": "major-gate",
+                    "type": "string"
+                  },
+                  {
+                    "const": "locked",
+                    "type": "string"
+                  }
+                ]
+              }
+            }
+          },
+          {
+            "additionalProperties": false,
+            "description": "A behavioral feature reimplemented locally to match upstream behavior. Three-pillar validation: code patterns + test patterns + fixture snapshot. The total score is averaged across present pillars; rows below the criticality / 10 floor surface as drift.",
+            "type": "object",
+            "required": ["kind", "id", "upstream", "criticality", "local_area"],
+            "properties": {
+              "kind": {
+                "const": "feature-parity",
+                "type": "string"
+              },
+              "id": {
+                "pattern": "^[a-z0-9][a-z0-9-]*(/[A-Za-z0-9_-]+)?$",
+                "description": "Stable identifier, unique within the manifest. Kebab-case (lowercase letters / digits / hyphens). For ids that mirror an external API name, use a namespace prefix: `api/findNodeAt`, `node/parseURL`. The slash separates the kebab namespace from the free-form leaf.",
+                "type": "string"
+              },
+              "upstream": {
+                "description": "Key into the top-level `upstreams` map. The harness errors if no matching upstream entry exists.",
+                "type": "string"
+              },
+              "criticality": {
+                "minimum": 1,
+                "maximum": 10,
+                "description": "Stay-in-step importance. Anchors: 1 = cosmetic / nice-to-have; 5 = behavioral parity expected; 10 = security-sensitive. The harness surfaces high-criticality drift louder and gates feature-parity rows on the criticality/10 floor.",
+                "type": "integer"
+              },
+              "conformance_test": {
+                "description": "Path (relative to repo root) of a test that enforces behavior parity (modulo documented deviations). Strongly recommended — static checks catch syntactic drift, not behavioral. A row without a conformance test relies entirely on code-pattern / fixture-snapshot checks.",
+                "type": "string"
+              },
+              "notes": {
+                "description": "Free-form context: why this row exists, gotchas, links to related issues / PRs / upstream discussions. Read by humans, not by the harness.",
+                "type": "string"
+              },
+              "local_area": {
+                "description": "Path (relative to repo root) of the local module / directory implementing the feature. The code-pattern scan targets this directory recursively, excluding test files (matched by `*.test.{ts,mts,js,mjs}` and `*.spec.*`).",
+                "type": "string"
+              },
+              "test_area": {
+                "description": "Path (relative to repo root) of the directory where tests for this feature live. When absent, the harness searches for tests inside `local_area`. Useful when tests live in a sibling directory (e.g. `local_area=src/auth`, `test_area=test/auth`).",
+                "type": "string"
+              },
+              "code_patterns": {
+                "description": "Regex patterns the local implementation must contain. Prefer anchored patterns (function signatures, exported symbols) over loose keywords to avoid matching comments. Each pattern is searched independently across `local_area`; missing patterns lower the code score.",
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "test_patterns": {
+                "description": "Regex patterns the test suite must contain. Same scoring as `code_patterns` but searched across `test_area` (or `local_area` when `test_area` is absent).",
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "fixture_check": {
+                "additionalProperties": false,
+                "description": "Golden-input verification. Snapshot-based diffs replace the brittle hardcoded-count checks the harness used historically (sdxgen's lock-step-features lesson).",
+                "type": "object",
+                "required": ["fixture_path"],
+                "properties": {
+                  "fixture_path": {
+                    "description": "Path (relative to repo root) of the input fixture the local implementation runs against.",
+                    "type": "string"
+                  },
+                  "snapshot_path": {
+                    "description": "Path (relative to repo root) of the snapshot file the implementation's output is diffed against. When absent, the harness only checks that the fixture is processed without error — no output comparison.",
+                    "type": "string"
+                  },
+                  "diff_tolerance": {
+                    "description": "How the snapshot diff is computed. `exact` = byte-identical; the strictest check. `line-by-line` = per-line diff after normalizing line endings (CRLF / LF); tolerates trailing-newline drift. `semantic` = harness-defined deeper comparison (typically AST or normalized JSON for output that has equivalent representations); each row kind documents what `semantic` means in its context.",
+                    "anyOf": [
+                      {
+                        "const": "exact",
+                        "type": "string"
+                      },
+                      {
+                        "const": "line-by-line",
+                        "type": "string"
+                      },
+                      {
+                        "const": "semantic",
+                        "type": "string"
+                      }
+                    ]
+                  }
+                }
+              }
+            }
+          },
+          {
+            "additionalProperties": false,
+            "description": "A local reimplementation of an external specification. Drift = the spec was revised; we may need to update our impl, the spec_version, or both.",
+            "type": "object",
+            "required": [
+              "kind",
+              "id",
+              "upstream",
+              "local_impl",
+              "spec_version"
+            ],
+            "properties": {
+              "kind": {
+                "const": "spec-conformance",
+                "type": "string"
+              },
+              "id": {
+                "pattern": "^[a-z0-9][a-z0-9-]*(/[A-Za-z0-9_-]+)?$",
+                "description": "Stable identifier, unique within the manifest. Kebab-case (lowercase letters / digits / hyphens). For ids that mirror an external API name, use a namespace prefix: `api/findNodeAt`, `node/parseURL`. The slash separates the kebab namespace from the free-form leaf.",
+                "type": "string"
+              },
+              "upstream": {
+                "description": "Key into the top-level `upstreams` map. The harness errors if no matching upstream entry exists.",
+                "type": "string"
+              },
+              "criticality": {
+                "minimum": 1,
+                "maximum": 10,
+                "description": "Stay-in-step importance. Anchors: 1 = cosmetic / nice-to-have; 5 = behavioral parity expected; 10 = security-sensitive. The harness surfaces high-criticality drift louder and gates feature-parity rows on the criticality/10 floor.",
+                "type": "integer"
+              },
+              "conformance_test": {
+                "description": "Path (relative to repo root) of a test that enforces behavior parity (modulo documented deviations). Strongly recommended — static checks catch syntactic drift, not behavioral. A row without a conformance test relies entirely on code-pattern / fixture-snapshot checks.",
+                "type": "string"
+              },
+              "notes": {
+                "description": "Free-form context: why this row exists, gotchas, links to related issues / PRs / upstream discussions. Read by humans, not by the harness.",
+                "type": "string"
+              },
+              "local_impl": {
+                "description": "Path (relative to repo root) of our reimplementation of the spec. Either a file or a directory.",
+                "type": "string"
+              },
+              "spec_version": {
+                "description": "Version label of the spec we conform to (e.g. `ECMAScript-2024`, `RFC-9110`, commit SHA, or upstream tag). Free-form — the harness only checks for drift via the upstream submodule, not the version string itself.",
+                "type": "string"
+              },
+              "spec_path": {
+                "description": "Path within the upstream submodule to the spec document. Used to scope drift detection to the spec file (rather than every change in the upstream repo).",
+                "type": "string"
+              }
+            }
+          },
+          {
+            "additionalProperties": false,
+            "description": "N sibling language ports of one spec within a single project. Drift = a port diverged from its siblings (one implemented, others opt-out without reason / or vice versa), or a `rejected` anti-pattern was reintroduced.",
+            "type": "object",
+            "required": [
+              "kind",
+              "id",
+              "name",
+              "description",
+              "category",
+              "ports"
+            ],
+            "properties": {
+              "kind": {
+                "const": "lang-parity",
+                "type": "string"
+              },
+              "id": {
+                "pattern": "^[a-z0-9][a-z0-9-]*(/[A-Za-z0-9_-]+)?$",
+                "description": "Stable identifier, unique within the manifest. Kebab-case (lowercase letters / digits / hyphens). For ids that mirror an external API name, use a namespace prefix: `api/findNodeAt`, `node/parseURL`. The slash separates the kebab namespace from the free-form leaf.",
+                "type": "string"
+              },
+              "name": {
+                "description": "Short human-readable label for this row (e.g. `Range parsing`, `Async iterators`). Used in report headers; not parsed.",
+                "type": "string"
+              },
+              "description": {
+                "description": "One-paragraph description of what behavior this row asserts on each port. Read by humans; not parsed.",
+                "type": "string"
+              },
+              "category": {
+                "description": "Grouping tag for report aggregation (e.g. `parser`, `runtime`, `api`). The single magic value is `rejected` — RESERVED for anti-patterns: every port MUST be `opt-out`, and any port flipping to `implemented` exits 2 ('rejected anti-pattern reintroduced'). Use freely otherwise.",
+                "type": "string"
+              },
+              "criticality": {
+                "minimum": 1,
+                "maximum": 10,
+                "description": "Stay-in-step importance. Anchors: 1 = cosmetic / nice-to-have; 5 = behavioral parity expected; 10 = security-sensitive. The harness surfaces high-criticality drift louder and gates feature-parity rows on the criticality/10 floor.",
+                "type": "integer"
+              },
+              "conformance_test": {
+                "description": "Path (relative to repo root) of a test that enforces behavior parity (modulo documented deviations). Strongly recommended — static checks catch syntactic drift, not behavioral. A row without a conformance test relies entirely on code-pattern / fixture-snapshot checks.",
+                "type": "string"
+              },
+              "notes": {
+                "description": "Free-form context: why this row exists, gotchas, links to related issues / PRs / upstream discussions. Read by humans, not by the harness.",
+                "type": "string"
+              },
+              "assertions": {
+                "description": "Assertions checked against each port. Each entry is `{kind: string, ...}`; the harness dispatches on `kind`. See AssertionSchema description for known kinds; unknown kinds skip with a log line. Mutually compatible with `matrix_files` (a row can have both, neither, or one).",
+                "type": "array",
+                "items": {
+                  "description": "A typed assertion the lang-parity row asserts on each port. Shape: `{kind: string, ...kind-specific fields}`. The lockstep harness dispatches on `kind`; per-kind contracts are documented in the harness, not here.",
+                  "type": "object",
+                  "patternProperties": {
+                    "^(.*)$": {}
+                  }
+                }
+              },
+              "matrix_files": {
+                "description": "Paths (relative to this manifest) of `lockstep-lang-*.json` sub-manifests this row indexes. For inventory-style rows that group many smaller checks under one parent. The harness loads each and merges its rows.",
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "ports": {
+                "description": "Per-port status map. Keys MUST match top-level `sites` keys exactly — the harness errors on stray ports / missing sites. Each value is `{status: 'implemented' | 'opt-out', ...}` per PortStatusSchema.",
+                "type": "object",
+                "patternProperties": {
+                  "^(.*)$": {
+                    "additionalProperties": false,
+                    "description": "Per-port status for a lang-parity row. The `ports` map on a row pairs each top-level `sites` key with one of these.",
+                    "type": "object",
+                    "required": ["status"],
+                    "properties": {
+                      "status": {
+                        "description": "`implemented` = port meets the row's assertions; `opt-out` = port consciously skips this row (requires `reason`).",
+                        "anyOf": [
+                          {
+                            "const": "implemented",
+                            "type": "string"
+                          },
+                          {
+                            "const": "opt-out",
+                            "type": "string"
+                          }
+                        ]
+                      },
+                      "reason": {
+                        "description": "Why this port opts out. SCHEMA-CONDITIONAL: required when status is `opt-out`. The TypeBox type cannot express the conditional, but the harness rejects opt-out rows with empty / missing reason.",
+                        "type": "string"
+                      },
+                      "path": {
+                        "description": "Optional path to this port's implementation of the row. Useful for module-inventory rows where each language points at a different directory; redundant when the port's overall layout already encodes the path.",
+                        "type": "string"
+                      },
+                      "note": {
+                        "description": "Optional free-form note attached to this specific port's status. For multi-port context, prefer the row-level `notes` field.",
+                        "type": "string"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
+}
diff --git a/.config/oxlint-plugin/index.mts b/.config/oxlint-plugin/index.mts
new file mode 100644
index 0000000..8008216
--- /dev/null
+++ b/.config/oxlint-plugin/index.mts
@@ -0,0 +1,83 @@
+/**
+ * @fileoverview Fleet oxlint plugin. Custom rules that encode the
+ * fleet's CLAUDE.md style guide as lint errors with autofix where
+ * the rewrite is unambiguous.
+ *
+ * Why a plugin instead of a separate scanner: oxlint's native plugin
+ * surface integrates with the existing `pnpm run lint` pipeline,
+ * inherits oxlint's AST + sourcemap + fix-application machinery, and
+ * keeps the rule set discoverable via `oxlint --rules`.
+ *
+ * Wiring: `.config/oxlintrc.json` adds this plugin via `jsPlugins:
+ * ["./oxlint-plugin/index.mts"]` and enables rules under the
+ * `socket/` namespace.
+ */
+
+import exportTopLevelFunctions from './rules/export-top-level-functions.mts'
+import inclusiveLanguage from './rules/inclusive-language.mts'
+import maxFileLines from './rules/max-file-lines.mts'
+import noConsolePreferLogger from './rules/no-console-prefer-logger.mts'
+import noDefaultExport from './rules/no-default-export.mts'
+import noDynamicImportOutsideBundle from './rules/no-dynamic-import-outside-bundle.mts'
+import noFetchPreferHttpRequest from './rules/no-fetch-prefer-http-request.mts'
+import noInlineLogger from './rules/no-inline-logger.mts'
+import noNpxDlx from './rules/no-npx-dlx.mts'
+import noPlaceholders from './rules/no-placeholders.mts'
+import noPromiseRace from './rules/no-promise-race.mts'
+import noPromiseRaceInLoop from './rules/no-promise-race-in-loop.mts'
+import noStatusEmoji from './rules/no-status-emoji.mts'
+import personalPathPlaceholders from './rules/personal-path-placeholders.mts'
+import preferAsyncSpawn from './rules/prefer-async-spawn.mts'
+import preferCachedForLoop from './rules/prefer-cached-for-loop.mts'
+import preferExistsSync from './rules/prefer-exists-sync.mts'
+import preferFunctionDeclaration from './rules/prefer-function-declaration.mts'
+import preferNodeBuiltinImports from './rules/prefer-node-builtin-imports.mts'
+import preferSafeDelete from './rules/prefer-safe-delete.mts'
+import preferSeparateTypeImport from './rules/prefer-separate-type-import.mts'
+import preferUndefinedOverNull from './rules/prefer-undefined-over-null.mts'
+import socketApiTokenEnv from './rules/socket-api-token-env.mts'
+import sortEqualityDisjunctions from './rules/sort-equality-disjunctions.mts'
+import sortNamedImports from './rules/sort-named-imports.mts'
+import sortRegexAlternations from './rules/sort-regex-alternations.mts'
+import sortSetArgs from './rules/sort-set-args.mts'
+import sortSourceMethods from './rules/sort-source-methods.mts'
+
+/** @type {import('eslint').ESLint.Plugin} */
+const plugin = {
+  meta: {
+    name: 'socket',
+    version: '0.5.0',
+  },
+  rules: {
+    'export-top-level-functions': exportTopLevelFunctions,
+    'inclusive-language': inclusiveLanguage,
+    'max-file-lines': maxFileLines,
+    'no-console-prefer-logger': noConsolePreferLogger,
+    'no-default-export': noDefaultExport,
+    'no-dynamic-import-outside-bundle': noDynamicImportOutsideBundle,
+    'no-fetch-prefer-http-request': noFetchPreferHttpRequest,
+    'no-inline-logger': noInlineLogger,
+    'no-npx-dlx': noNpxDlx,
+    'no-placeholders': noPlaceholders,
+    'no-promise-race': noPromiseRace,
+    'no-promise-race-in-loop': noPromiseRaceInLoop,
+    'no-status-emoji': noStatusEmoji,
+    'personal-path-placeholders': personalPathPlaceholders,
+    'prefer-async-spawn': preferAsyncSpawn,
+    'prefer-cached-for-loop': preferCachedForLoop,
+    'prefer-exists-sync': preferExistsSync,
+    'prefer-function-declaration': preferFunctionDeclaration,
+    'prefer-node-builtin-imports': preferNodeBuiltinImports,
+    'prefer-safe-delete': preferSafeDelete,
+    'prefer-separate-type-import': preferSeparateTypeImport,
+    'prefer-undefined-over-null': preferUndefinedOverNull,
+    'socket-api-token-env': socketApiTokenEnv,
+    'sort-equality-disjunctions': sortEqualityDisjunctions,
+    'sort-named-imports': sortNamedImports,
+    'sort-regex-alternations': sortRegexAlternations,
+    'sort-set-args': sortSetArgs,
+    'sort-source-methods': sortSourceMethods,
+  },
+}
+
+export default plugin
diff --git a/.config/oxlint-plugin/package.json b/.config/oxlint-plugin/package.json
new file mode 100644
index 0000000..fbbf76b
--- /dev/null
+++ b/.config/oxlint-plugin/package.json
@@ -0,0 +1,9 @@
+{
+  "name": "socket-oxlint-plugin",
+  "private": true,
+  "type": "module",
+  "main": "./index.mts",
+  "exports": {
+    ".": "./index.mts"
+  }
+}
diff --git a/.config/oxlint-plugin/rules/_inject-import.mts b/.config/oxlint-plugin/rules/_inject-import.mts
new file mode 100644
index 0000000..254ad04
--- /dev/null
+++ b/.config/oxlint-plugin/rules/_inject-import.mts
@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Shared helper for rule fixers that need to inject
+ * an `import { Name } from 'specifier'` statement (and optionally a
+ * matching hoisted `const`) into a file.
+ *
+ * Fixers call `summarizeImportTarget(programNode, specifier, importName)`
+ * to learn the file's current shape, then `appendImportFixes(...)`
+ * inside their `fix(fixer)` callback to add the missing pieces.
+ *
+ * ESLint's autofixer dedupes overlapping inserts at the same range,
+ * so multiple violations in the same file can each emit the import
+ * insertion safely — only one survives.
+ */
+
+/**
+ * Walk a Program node body once and figure out:
+ *   - the last top-level ImportDeclaration node (or undefined)
+ *   - whether `importName` is already imported (from ANY source)
+ *   - whether a top-level `localName` identifier already exists
+ *     (any const/let/var or import-as-local with that name)
+ *
+ * Import detection ignores the specifier path: a file inside the lib
+ * package itself imports `getDefaultLogger` from `'../logger'`, while
+ * a downstream repo imports the same name from
+ * `'@socketsecurity/lib/logger'`. Both resolve to the same identifier;
+ * either should count as "already imported" so the autofix doesn't
+ * inject a duplicate (and broken — see issue #64).
+ *
+ * `specifier` is retained in the signature for backward compatibility
+ * but is no longer used for the match decision. Callers may pass any
+ * truthy value (typically the canonical package path the rule would
+ * inject if the import were missing).
+ */
+export function summarizeImportTarget(
+  program,
+  // eslint-disable-next-line no-unused-vars
+  specifier,
+  importName,
+  localName,
+) {
+  let lastImport
+  let hasImport = false
+  let hasLocal = false
+  for (const stmt of program.body) {
+    if (stmt.type === 'ImportDeclaration') {
+      lastImport = stmt
+      for (const spec of stmt.specifiers) {
+        if (
+          spec.type === 'ImportSpecifier' &&
+          spec.imported &&
+          spec.imported.name === importName
+        ) {
+          hasImport = true
+        }
+        if (
+          localName &&
+          spec.local &&
+          spec.local.name === localName &&
+          (spec.type === 'ImportSpecifier' ||
+            spec.type === 'ImportDefaultSpecifier' ||
+            spec.type === 'ImportNamespaceSpecifier')
+        ) {
+          hasLocal = true
+        }
+      }
+      continue
+    }
+    if (localName && stmt.type === 'VariableDeclaration') {
+      for (const decl of stmt.declarations) {
+        if (
+          decl.id &&
+          decl.id.type === 'Identifier' &&
+          decl.id.name === localName
+        ) {
+          hasLocal = true
+        }
+      }
+    }
+  }
+  return { hasImport, hasLocal, lastImport }
+}
+
+/**
+ * Build the fixer-side inserts for missing import + optional hoist.
+ * Returns an array of fixer operations the caller appends to its own
+ * fix() return value.
+ *
+ *   summary       — output of summarizeImportTarget()
+ *   fixer         — the fixer passed to context.report({ fix })
+ *   importLine    — the literal `import { ... } from '...'` text
+ *   hoistLine     — optional; the literal `const x = ...()` text
+ */
+export function appendImportFixes(summary, fixer, importLine, hoistLine) {
+  const ops = []
+  if (!summary.hasImport) {
+    if (summary.lastImport) {
+      ops.push(fixer.insertTextAfter(summary.lastImport, `\n${importLine}`))
+    } else {
+      ops.push(fixer.insertTextBeforeRange([0, 0], `${importLine}\n`))
+    }
+  }
+  if (hoistLine && !summary.hasLocal) {
+    if (summary.lastImport) {
+      ops.push(fixer.insertTextAfter(summary.lastImport, `\n\n${hoistLine}`))
+    } else {
+      ops.push(fixer.insertTextBeforeRange([0, 0], `${hoistLine}\n\n`))
+    }
+  }
+  return ops
+}
diff --git a/.config/oxlint-plugin/rules/export-top-level-functions.mts b/.config/oxlint-plugin/rules/export-top-level-functions.mts
new file mode 100644
index 0000000..cb4741b
--- /dev/null
+++ b/.config/oxlint-plugin/rules/export-top-level-functions.mts
@@ -0,0 +1,122 @@
+/**
+ * @fileoverview Require every top-level `function` declaration to be
+ * `export`ed. Per the fleet rule: "we should export all methods for
+ * testing." Exposing internal helpers as named exports lets tests
+ * import them directly, no `__test_only__` shim or per-test rebuild.
+ *
+ * Scope: top-level function declarations only (not class methods,
+ * not arrow functions assigned to const, not local nested functions).
+ * Local helpers and arrow-as-const are visible to their parent
+ * module's tests via the parent function; only the top-level surface
+ * needs explicit export.
+ *
+ * Allowed exceptions (skipped):
+ *   - The function is named `main` (script entrypoint convention).
+ *
+ * Autofix: prepends `export ` to the function declaration when the
+ * function isn't already named in a sibling `export { ... }`
+ * statement. If a named-re-export already exists, report without
+ * autofix (the human picks: keep the named-re-export shape, or
+ * collapse to the inline `export function`).
+ */
+
+const SCRIPT_ENTRY_NAMES = new Set(['main'])
+
+/**
+ * Walk Program body once and collect names exported via:
+ *   - `export { foo, bar }`
+ *   - `export { foo as bar }` (the local-name `foo` counts)
+ *   - `export default foo`
+ *
+ * Function declarations that already say `export function foo` won't
+ * reach this rule's visitor (the visitor matches bare function
+ * declarations only via `Program > FunctionDeclaration`; an
+ * `ExportNamedDeclaration` wraps them in a different shape).
+ */
+function collectExportedNames(program) {
+  const exported = new Set()
+  for (const stmt of program.body) {
+    if (stmt.type === 'ExportNamedDeclaration' && !stmt.declaration) {
+      // `export { foo, bar as baz }` — count the local name.
+      for (const spec of stmt.specifiers) {
+        if (spec.local && spec.local.type === 'Identifier') {
+          exported.add(spec.local.name)
+        }
+      }
+    }
+    if (
+      stmt.type === 'ExportDefaultDeclaration' &&
+      stmt.declaration &&
+      stmt.declaration.type === 'Identifier'
+    ) {
+      exported.add(stmt.declaration.name)
+    }
+  }
+  return exported
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Require top-level function declarations to be exported (testability).',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      missing:
+        'Top-level function `{{name}}` should be `export function {{name}}`. Exporting internal helpers makes them directly testable.',
+      missingAlreadyReExported:
+        'Top-level function `{{name}}` is named in a separate `export {{ }}` statement; collapse to inline `export function {{name}}` for clarity (autofix skipped to avoid creating a duplicate export).',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+    let exportedNames
+
+    return {
+      'Program > FunctionDeclaration'(node) {
+        if (!node.id || node.id.type !== 'Identifier') {
+          return
+        }
+        const name = node.id.name
+        if (SCRIPT_ENTRY_NAMES.has(name)) {
+          return
+        }
+        if (!exportedNames) {
+          exportedNames = collectExportedNames(sourceCode.ast)
+        }
+        if (exportedNames.has(name)) {
+          // Already exported via `export { name }` — report without
+          // autofix; the human can choose whether to collapse to the
+          // inline export.
+          context.report({
+            node: node.id,
+            messageId: 'missingAlreadyReExported',
+            data: { name },
+          })
+          return
+        }
+        context.report({
+          node: node.id,
+          messageId: 'missing',
+          data: { name },
+          fix(fixer) {
+            // Insert `export ` at the function's start. Handles both
+            // `function name(...)` and `async function name(...)`.
+            return fixer.insertTextBefore(node, 'export ')
+          },
+        })
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/inclusive-language.mts b/.config/oxlint-plugin/rules/inclusive-language.mts
new file mode 100644
index 0000000..c8109a9
--- /dev/null
+++ b/.config/oxlint-plugin/rules/inclusive-language.mts
@@ -0,0 +1,410 @@
+/* oxlint-disable socket/inclusive-language -- this file IS the rule definition; the legacy terms are lookup-table data, not real usage. */
+
+/**
+ * @fileoverview Per CLAUDE.md "Inclusive language" rule (full table
+ * in docs/references/inclusive-language.md).
+ *
+ * Substitutions:
+ *
+ *   whitelist  → allowlist
+ *   blacklist  → denylist
+ *   master     → main / primary
+ *   slave      → replica / secondary / worker
+ *   grandfathered → legacy
+ *   sanity check  → quick check
+ *   dummy      → placeholder
+ *
+ * Detects identifiers, string literals, and comments containing the
+ * legacy terms. Word-boundary matched on the literal stem so case
+ * variants `Whitelist` / `WHITELIST` / `whitelisted` all fire.
+ *
+ * Autofix:
+ *   - Identifiers and string literals: rewrite case-preserving
+ *     (e.g. `Whitelist` → `Allowlist`, `WHITELIST` → `ALLOWLIST`,
+ *     `whitelistEntry` → `allowlistEntry`).
+ *   - Comments: rewrite the comment text in place, same case rules.
+ *   - Multi-word terms (`sanity check`, `master branch`): only the
+ *     first word is replaced; the rest is left alone (`sanity check`
+ *     → `quick check`).
+ *
+ * Allowed exceptions (skipped — no report, no fix):
+ *   - Third-party API field references: comment with
+ *     `inclusive-language: external-api` adjacent to the line.
+ *   - Vendored / fixture paths: handled at the .config/oxlintrc.json
+ *     ignorePatterns level; this rule trusts the include set.
+ *   - The literal phrase "main / primary" / etc. inside a doc that
+ *     spells out the substitution table — handled by the
+ *     `docs/references/inclusive-language.md` ignore pattern in
+ *     .config/oxlintrc.json (caller adds the override).
+ */
+
+// [legacyStem, replacementStem]. The detector matches the stem
+// case-insensitively and word-boundary anchored. Replacement preserves
+// case shape.
+const SUBSTITUTIONS = [
+  ['whitelist', 'allowlist'],
+  ['blacklist', 'denylist'],
+  ['grandfathered', 'legacy'],
+  ['sanity', 'quick'],
+  ['dummy', 'placeholder'],
+  // master/slave are loaded but rewriting requires more nuance — only
+  // flag, never autofix (could mean main/primary/controller; depends
+  // on the surrounding domain).
+]
+
+const REPORT_ONLY = new Set(['master', 'slave'])
+const REPORT_ONLY_TERMS = ['master', 'slave']
+
+const BYPASS_RE = /inclusive-language:\s*external-api/
+
+/** Build a regex matching any legacy stem with word boundaries.
+ *
+ * Stems are sorted alphabetically before being joined so the regex
+ * alternation has a deterministic, stable form. Two reasons:
+ *   1. The fleet ships a `sort-regex-alternations` rule that flags
+ *      unsorted `(a|b|c)`-style alternations; this regex would trip
+ *      its own sibling rule without the sort.
+ *   2. Regex engines treat `|` as "first match wins" when alternatives
+ *      have shared prefixes — sorting keeps the precedence visible
+ *      in source rather than depending on declaration order.
+ */
+function buildDetectorRegex() {
+  const stems = [
+    ...SUBSTITUTIONS.map(([legacy]) => legacy),
+    ...REPORT_ONLY_TERMS,
+  ].sort()
+  return new RegExp(`\\b(${stems.join('|')})\\w*`, 'gi')
+}
+
+const DETECTOR_RE = buildDetectorRegex()
+
+/**
+ * Replace a single hit `match` (e.g. `Whitelist`, `WHITELIST`,
+ * `whitelisted`, `whitelistEntry`) with the case-preserving form of
+ * the new stem. Returns undefined when there's no autofix-able
+ * substitution (master/slave).
+ */
+function rewriteHit(match) {
+  const lower = match.toLowerCase()
+  for (const [legacy, replacement] of SUBSTITUTIONS) {
+    if (!lower.startsWith(legacy)) {
+      continue
+    }
+    const tail = match.slice(legacy.length)
+    const original = match.slice(0, legacy.length)
+    let rebuilt
+    if (original === original.toUpperCase()) {
+      rebuilt = replacement.toUpperCase()
+    } else if (original[0] === original[0].toUpperCase()) {
+      rebuilt = replacement[0].toUpperCase() + replacement.slice(1)
+    } else {
+      rebuilt = replacement
+    }
+    return rebuilt + tail
+  }
+  return undefined
+}
+
+function findHits(text) {
+  const hits = []
+  DETECTOR_RE.lastIndex = 0
+  let m
+  while ((m = DETECTOR_RE.exec(text)) !== null) {
+    const stem = m[1].toLowerCase()
+    hits.push({
+      start: m.index,
+      end: m.index + m[0].length,
+      match: m[0],
+      stem,
+    })
+  }
+  return hits
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Use inclusive language. Replace whitelist/blacklist/master/slave/grandfathered/sanity/dummy per the fleet substitution table.',
+      category: 'Stylistic Issues',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      legacy:
+        '`{{match}}` — replace with the inclusive-language equivalent. See docs/references/inclusive-language.md.',
+      legacyMaster:
+        '`{{match}}` — replace with `main` (branch), `primary` / `controller` (process). Manual rewrite — context decides which fits.',
+      legacySlave:
+        '`{{match}}` — replace with `replica` / `worker` / `secondary` / `follower`. Manual rewrite — context decides which fits.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    function hasBypassComment(node) {
+      const before = sourceCode.getCommentsBefore(node)
+      const after = sourceCode.getCommentsAfter(node)
+      for (const c of [...before, ...after]) {
+        if (BYPASS_RE.test(c.value)) {
+          return true
+        }
+      }
+      // Fall-back: scan the entire source line containing the node for
+      // a trailing bypass comment. AST-level "after" comments stop at
+      // the statement boundary, but a chained method call's string
+      // literal won't see a trailing comment on the same physical line.
+      const loc = node.loc
+      if (loc && loc.start.line === loc.end.line) {
+        const lineText = sourceCode.lines?.[loc.start.line - 1]
+        if (lineText && BYPASS_RE.test(lineText)) {
+          return true
+        }
+      }
+      return false
+    }
+
+    function reportHit(node, hit, replaceFn) {
+      let messageId = 'legacy'
+      if (hit.stem === 'master') {
+        messageId = 'legacyMaster'
+      } else if (hit.stem === 'slave') {
+        messageId = 'legacySlave'
+      }
+      const isReportOnly = REPORT_ONLY.has(hit.stem)
+      const replacement = isReportOnly ? undefined : rewriteHit(hit.match)
+      if (!replacement) {
+        context.report({ node, messageId, data: { match: hit.match } })
+        return
+      }
+      context.report({
+        node,
+        messageId,
+        data: { match: hit.match },
+        fix(fixer) {
+          return replaceFn(fixer, hit, replacement)
+        },
+      })
+    }
+
+    function checkIdentifier(node) {
+      if (!node.name) {
+        return
+      }
+      const hits = findHits(node.name)
+      if (hits.length === 0) {
+        return
+      }
+      if (hasBypassComment(node)) {
+        return
+      }
+      // Identifiers can have multiple hits in compound names —
+      // process each and merge into a single rewrite.
+      let rebuilt = ''
+      let cursor = 0
+      let mutated = false
+      let allReportOnly = true
+      for (const h of hits) {
+        rebuilt += node.name.slice(cursor, h.start)
+        const replacement = REPORT_ONLY.has(h.stem)
+          ? undefined
+          : rewriteHit(h.match)
+        if (replacement) {
+          rebuilt += replacement
+          mutated = true
+          allReportOnly = false
+        } else {
+          rebuilt += h.match
+        }
+        cursor = h.end
+      }
+      rebuilt += node.name.slice(cursor)
+
+      if (!mutated) {
+        // All hits are report-only (master/slave) — emit one report
+        // for each.
+        for (const h of hits) {
+          let messageId = 'legacy'
+          if (h.stem === 'master') {
+            messageId = 'legacyMaster'
+          } else if (h.stem === 'slave') {
+            messageId = 'legacySlave'
+          }
+          context.report({ node, messageId, data: { match: h.match } })
+        }
+        return
+      }
+
+      // Emit one report per hit but a single combined fix.
+      const firstHit = hits[0]
+      let messageId = 'legacy'
+      if (firstHit.stem === 'master') {
+        messageId = 'legacyMaster'
+      } else if (firstHit.stem === 'slave') {
+        messageId = 'legacySlave'
+      }
+      context.report({
+        node,
+        messageId,
+        data: { match: firstHit.match },
+        fix(fixer) {
+          return fixer.replaceText(node, rebuilt)
+        },
+      })
+    }
+
+    return {
+      Identifier: checkIdentifier,
+
+      Literal(node) {
+        if (typeof node.value !== 'string') {
+          return
+        }
+        const hits = findHits(node.value)
+        if (hits.length === 0) {
+          return
+        }
+        if (hasBypassComment(node)) {
+          return
+        }
+
+        let rebuilt = ''
+        let cursor = 0
+        let mutated = false
+        for (const h of hits) {
+          rebuilt += node.value.slice(cursor, h.start)
+          const replacement = REPORT_ONLY.has(h.stem)
+            ? undefined
+            : rewriteHit(h.match)
+          if (replacement) {
+            rebuilt += replacement
+            mutated = true
+          } else {
+            rebuilt += h.match
+          }
+          cursor = h.end
+        }
+        rebuilt += node.value.slice(cursor)
+
+        if (!mutated) {
+          for (const h of hits) {
+            let messageId = 'legacy'
+            if (h.stem === 'master') {
+              messageId = 'legacyMaster'
+            } else if (h.stem === 'slave') {
+              messageId = 'legacySlave'
+            }
+            context.report({ node, messageId, data: { match: h.match } })
+          }
+          return
+        }
+
+        const firstHit = hits[0]
+        let messageId = 'legacy'
+        if (firstHit.stem === 'master') {
+          messageId = 'legacyMaster'
+        } else if (firstHit.stem === 'slave') {
+          messageId = 'legacySlave'
+        }
+        context.report({
+          node,
+          messageId,
+          data: { match: firstHit.match },
+          fix(fixer) {
+            const raw = sourceCode.getText(node)
+            const quote = raw[0]
+            if (quote === '`') {
+              return fixer.replaceText(node, '`' + rebuilt + '`')
+            }
+            const escaped = rebuilt.replace(
+              new RegExp(`\\\\|${quote}`, 'g'),
+              ch => '\\' + ch,
+            )
+            return fixer.replaceText(node, quote + escaped + quote)
+          },
+        })
+      },
+
+      Program() {
+        // Sweep comments — rewriting comment bodies is harmless even
+        // when literal text matches "legacy" examples, because the
+        // bypass comment + ignorePatterns handle external-API and
+        // vendored cases.
+        const comments = sourceCode.getAllComments()
+        for (const comment of comments) {
+          if (BYPASS_RE.test(comment.value)) {
+            continue
+          }
+          const hits = findHits(comment.value)
+          if (hits.length === 0) {
+            continue
+          }
+
+          let rebuilt = ''
+          let cursor = 0
+          let mutated = false
+          for (const h of hits) {
+            rebuilt += comment.value.slice(cursor, h.start)
+            const replacement = REPORT_ONLY.has(h.stem)
+              ? undefined
+              : rewriteHit(h.match)
+            if (replacement) {
+              rebuilt += replacement
+              mutated = true
+            } else {
+              rebuilt += h.match
+            }
+            cursor = h.end
+          }
+          rebuilt += comment.value.slice(cursor)
+
+          if (!mutated) {
+            for (const h of hits) {
+              let messageId = 'legacy'
+              if (h.stem === 'master') {
+                messageId = 'legacyMaster'
+              } else if (h.stem === 'slave') {
+                messageId = 'legacySlave'
+              }
+              context.report({
+                node: comment,
+                messageId,
+                data: { match: h.match },
+              })
+            }
+            continue
+          }
+
+          const firstHit = hits[0]
+          let messageId = 'legacy'
+          if (firstHit.stem === 'master') {
+            messageId = 'legacyMaster'
+          } else if (firstHit.stem === 'slave') {
+            messageId = 'legacySlave'
+          }
+          context.report({
+            node: comment,
+            messageId,
+            data: { match: firstHit.match },
+            fix(fixer) {
+              const prefix = comment.type === 'Line' ? '//' : '/*'
+              const suffix = comment.type === 'Line' ? '' : '*/'
+              return fixer.replaceTextRange(
+                comment.range,
+                prefix + rebuilt + suffix,
+              )
+            },
+          })
+        }
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/max-file-lines.mts b/.config/oxlint-plugin/rules/max-file-lines.mts
new file mode 100644
index 0000000..ac025c6
--- /dev/null
+++ b/.config/oxlint-plugin/rules/max-file-lines.mts
@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Per CLAUDE.md "File size" rule:
+ *
+ *   Source files have a soft cap of 500 lines and a hard cap of 1000
+ *   lines. Past those thresholds, split the file along its natural
+ *   seams.
+ *
+ * Two severities:
+ *   - >500 lines: warning, with the message pointing at the splitting
+ *     guidance in CLAUDE.md.
+ *   - >1000 lines: error.
+ *
+ * No autofix — splitting requires judgment about where the natural
+ * seams are. The rule's job is to make the cap visible at every
+ * commit.
+ *
+ * Allowed exceptions:
+ *   - Files marked at the top with a comment containing
+ *     `max-file-lines: legitimate parser/state-machine/table` or
+ *     `eslint-disable socket/max-file-lines`. Per CLAUDE.md the rare
+ *     legitimate cases are parsers, state machines, and config tables;
+ *     they should self-document with a one-line comment.
+ *   - Generated artifacts — the rule trusts .config/oxlintrc.json's
+ *     ignorePatterns to keep generated files out of scope.
+ */
+
+const SOFT_CAP = 500
+const HARD_CAP = 1000
+
+const BYPASS_RE =
+  /max-file-lines:\s*(legitimate|parser|state[- ]?machine|table)/i
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Files have a soft cap of 500 lines (warn) and a hard cap of 1000 lines (error). Split along natural seams.',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    messages: {
+      soft: '{{lines}} lines — past the 500-line soft cap. Consider splitting along natural seams (one tool / domain / phase per file). See CLAUDE.md "File size".',
+      hard: '{{lines}} lines — past the 1000-line hard cap. Split this file. See CLAUDE.md "File size".',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    return {
+      Program(node) {
+        // Trust the parser's location info — `loc.end.line` is the
+        // 1-indexed line of the last token. Empty trailing lines are
+        // counted as part of the source per the line-counting
+        // convention CLAUDE.md uses.
+        const lines = node.loc.end.line
+
+        if (lines <= SOFT_CAP) {
+          return
+        }
+
+        // Bypass detection — scan leading comments only. A bypass
+        // comment buried 600 lines deep doesn't communicate intent at
+        // the file level.
+        const leadingComments = sourceCode
+          .getAllComments()
+          .filter(c => c.loc.start.line <= 5)
+        for (const c of leadingComments) {
+          if (BYPASS_RE.test(c.value)) {
+            return
+          }
+        }
+
+        const messageId = lines > HARD_CAP ? 'hard' : 'soft'
+        // Anchor the report at line 1 — the file as a whole is the
+        // problem, not any specific node.
+        context.report({
+          loc: { line: 1, column: 0 },
+          messageId,
+          data: { lines: String(lines) },
+        })
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/no-console-prefer-logger.mts b/.config/oxlint-plugin/rules/no-console-prefer-logger.mts
new file mode 100644
index 0000000..43ce88e
--- /dev/null
+++ b/.config/oxlint-plugin/rules/no-console-prefer-logger.mts
@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Ban `console.log` / `console.error` / `console.warn`
+ * / `console.info` / `console.debug` / `console.trace`. The fleet uses
+ * `getDefaultLogger()` from `@socketsecurity/lib/logger` — those
+ * methods emit theme-aware coloring + canonical symbols.
+ *
+ * Autofix: rewrites `console.<method>(...)` → `logger.<loggerMethod>(...)`
+ * AND inserts the missing pieces in one go:
+ *
+ *   1. `import { getDefaultLogger } from '@socketsecurity/lib/logger'`
+ *      — appended after the last existing top-level import (or at the
+ *      top of the file if there are none).
+ *   2. `const logger = getDefaultLogger()` — appended after the import
+ *      block (so `logger` is hoisted at module scope).
+ *
+ * Each `console.<method>(...)` call site emits its own fix
+ * independently. ESLint's autofixer dedupes overlapping inserts (the
+ * import line + hoist), so the visit order is irrelevant.
+ */
+
+import { appendImportFixes, summarizeImportTarget } from './_inject-import.mts'
+
+const CONSOLE_TO_LOGGER = {
+  debug: 'log',
+  error: 'fail',
+  info: 'info',
+  log: 'log',
+  trace: 'log',
+  warn: 'warn',
+}
+
+const LOGGER_IMPORT_LINE =
+  "import { getDefaultLogger } from '@socketsecurity/lib/logger'"
+const LOGGER_HOIST_LINE = 'const logger = getDefaultLogger()'
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Ban console.* calls; use logger from @socketsecurity/lib/logger.',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      banned:
+        'console.{{method}}() — use logger.{{loggerMethod}}() from @socketsecurity/lib/logger.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    let summary
+
+    function ensureSummary() {
+      if (summary) {
+        return summary
+      }
+      summary = summarizeImportTarget(
+        sourceCode.ast,
+        '@socketsecurity/lib/logger',
+        'getDefaultLogger',
+        'logger',
+      )
+      return summary
+    }
+
+    return {
+      MemberExpression(node) {
+        if (
+          node.object.type !== 'Identifier' ||
+          node.object.name !== 'console' ||
+          node.property.type !== 'Identifier'
+        ) {
+          return
+        }
+        const method = node.property.name
+        const loggerMethod = CONSOLE_TO_LOGGER[method]
+        if (!loggerMethod) {
+          return
+        }
+
+        // Only flag when console.<method> is the callee of a call
+        // (skip e.g. `typeof console.log` or destructuring).
+        const parent = node.parent
+        if (
+          !parent ||
+          parent.type !== 'CallExpression' ||
+          parent.callee !== node
+        ) {
+          return
+        }
+
+        const s = ensureSummary()
+
+        context.report({
+          node,
+          messageId: 'banned',
+          data: { method, loggerMethod },
+          fix(fixer) {
+            return [
+              fixer.replaceText(node, `logger.${loggerMethod}`),
+              ...appendImportFixes(
+                s,
+                fixer,
+                LOGGER_IMPORT_LINE,
+                LOGGER_HOIST_LINE,
+              ),
+            ]
+          },
+        })
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/no-default-export.mts b/.config/oxlint-plugin/rules/no-default-export.mts
new file mode 100644
index 0000000..98ea18e
--- /dev/null
+++ b/.config/oxlint-plugin/rules/no-default-export.mts
@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Forbid `export default` — fleet convention is named
+ * exports only. Default exports lose the name at the import site
+ * (`import x from 'mod'` lets the caller rename freely), defeat
+ * grep / "find references" tools, and don't compose with re-exports
+ * (`export * from 'mod'` skips the default).
+ *
+ * Style signal that motivated the rule: across socket-sdk-js,
+ * socket-cli, socket-packageurl-js, socket-sdxgen, socket-lib, and
+ * socket-stuie, the named-vs-default ratio is essentially
+ * 100-to-1 — socket-lib has zero `export default` statements, the
+ * other repos have a handful of stragglers each.
+ *
+ * Autofix scope:
+ *   - `export default function foo() {}` → `export function foo() {}`
+ *   - `export default class Foo {}` → `export class Foo {}`
+ *   - `export default <identifier>` (separate-declaration form) →
+ *     `export { <identifier> }`
+ *
+ * Skips (report-only, no fix):
+ *   - `export default function () {}` / `export default class {}` —
+ *     anonymous declarations, no canonical name to assign.
+ *   - `export default <expression>` where the expression isn't a bare
+ *     identifier (e.g. `export default { foo: 1 }`,
+ *     `export default makePlugin(...)`) — choosing a name requires
+ *     human input.
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Forbid `export default` — use named exports so the export name is stable across import sites.',
+      category: 'Stylistic Issues',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      noDefaultExport:
+        'Avoid `export default` — use a named export so the export name is stable across imports, greppable, and composable with `export * from`.',
+      noDefaultExportNoFix:
+        'Avoid `export default` — the default-exported value is anonymous or a complex expression. Give it a name and switch to `export { <name> }`.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    return {
+      ExportDefaultDeclaration(node) {
+        const decl = node.declaration
+        if (!decl) {
+          return
+        }
+
+        // `export default function name() {}` /
+        // `export default class Name {}` — drop the `default` keyword
+        // and emit the declaration as a named export.
+        if (
+          (decl.type === 'FunctionDeclaration' ||
+            decl.type === 'ClassDeclaration') &&
+          decl.id &&
+          decl.id.type === 'Identifier'
+        ) {
+          context.report({
+            node,
+            messageId: 'noDefaultExport',
+            fix(fixer) {
+              const declText = sourceCode.getText(decl)
+              return fixer.replaceText(node, `export ${declText}`)
+            },
+          })
+          return
+        }
+
+        // `export default someIdentifier` — rewrite to
+        // `export { someIdentifier }`. Only safe when the identifier
+        // is declared in the same module; we don't try to verify that
+        // here because the import side will fail loudly if not, and
+        // the autofix never strips a declaration.
+        if (decl.type === 'Identifier') {
+          context.report({
+            node,
+            messageId: 'noDefaultExport',
+            fix(fixer) {
+              return fixer.replaceText(node, `export { ${decl.name} }`)
+            },
+          })
+          return
+        }
+
+        // Anonymous declaration or complex expression — report without
+        // a fix; the human needs to choose a name.
+        context.report({
+          node,
+          messageId: 'noDefaultExportNoFix',
+        })
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/no-dynamic-import-outside-bundle.mts b/.config/oxlint-plugin/rules/no-dynamic-import-outside-bundle.mts
new file mode 100644
index 0000000..55fda97
--- /dev/null
+++ b/.config/oxlint-plugin/rules/no-dynamic-import-outside-bundle.mts
@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Ban dynamic `import()` (ImportExpression) in code that
+ * isn't bundled. The fleet favors static ES6 imports — dynamic import
+ * is only meaningful when a bundler resolves it statically at build
+ * time. Scripts under `scripts/` run directly via `node`; nothing
+ * bundles them, so a dynamic import only adds a runtime async hop for
+ * no resolution win.
+ *
+ * Allowed paths: `src/**`, `.config/**` (bundler configs themselves
+ * may load tools dynamically via the bundler's API).
+ *
+ * No autofix: converting `await import('foo')` to `import 'foo'`
+ * requires moving the statement to the top of the file and removing
+ * `await`/destructuring — the bundler-aware AST rewrite is non-trivial
+ * to do safely. Reporting only.
+ */
+
+import path from 'node:path'
+
+const DEFAULT_BUNDLED_ROOTS = ['src/', '.config/', 'packages/']
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Ban dynamic import() outside bundled trees (src/, .config/, packages/).',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    messages: {
+      dynamic:
+        'Dynamic import() in {{file}} — favor a static `import` statement at the top of the file. Dynamic import is only valid in bundled code (src/, .config/, packages/). If lazy resolution is required, justify it explicitly.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          bundledRoots: {
+            type: 'array',
+            items: { type: 'string' },
+            description:
+              'Path prefixes (relative to repo root) where dynamic import() is allowed.',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+
+  create(context) {
+    const options = context.options[0] || {}
+    const bundledRoots = options.bundledRoots || DEFAULT_BUNDLED_ROOTS
+    const filename = context.physicalFilename || context.filename
+    const cwd = context.cwd || process.cwd()
+    const relative = path.relative(cwd, filename).split(path.sep).join('/')
+
+    const inBundled = bundledRoots.some(root => relative.startsWith(root))
+
+    if (inBundled) {
+      return {}
+    }
+
+    return {
+      ImportExpression(node) {
+        context.report({
+          node,
+          messageId: 'dynamic',
+          data: { file: relative },
+        })
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/no-fetch-prefer-http-request.mts b/.config/oxlint-plugin/rules/no-fetch-prefer-http-request.mts
new file mode 100644
index 0000000..61d14a5
--- /dev/null
+++ b/.config/oxlint-plugin/rules/no-fetch-prefer-http-request.mts
@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Per CLAUDE.md "HTTP — never `fetch()`. Use httpJson /
+ * httpText / httpRequest from @socketsecurity/lib/http-request."
+ *
+ * Reports any `fetch(...)` call (global fetch). Does NOT auto-fix
+ * because the right replacement (`httpJson` vs `httpText` vs
+ * `httpRequest`) depends on what the caller does with the response —
+ * a wrong autofix would silently change behavior. Reporting only.
+ *
+ * Allowed exceptions (skipped):
+ *   - `globalThis.fetch` — explicit reference (often for monkey-patching
+ *     in tests).
+ *   - Method calls (`obj.fetch(...)`) — those aren't the global.
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Use httpJson / httpText / httpRequest from @socketsecurity/lib/http-request instead of global fetch().',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    messages: {
+      banned:
+        'global fetch() — use httpJson / httpText / httpRequest from @socketsecurity/lib/http-request. The right replacement depends on what you do with the response; the lib helpers ship consistent error shapes (HttpError) and JSON/text decoding.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+        // Only flag direct `fetch(...)` calls (Identifier callee).
+        if (callee.type !== 'Identifier' || callee.name !== 'fetch') {
+          return
+        }
+
+        // Skip if `fetch` is locally shadowed by a parameter / declaration.
+        // Best-effort: check the scope chain.
+        const scope = context.getScope ? context.getScope() : undefined
+        if (scope) {
+          const variable = scope.references.find(
+            ref => ref.identifier === callee,
+          )?.resolved
+          if (variable && variable.scope.type !== 'global') {
+            return
+          }
+        }
+
+        context.report({
+          node,
+          messageId: 'banned',
+        })
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/no-inline-logger.mts b/.config/oxlint-plugin/rules/no-inline-logger.mts
new file mode 100644
index 0000000..afabd00
--- /dev/null
+++ b/.config/oxlint-plugin/rules/no-inline-logger.mts
@@ -0,0 +1,112 @@
+/**
+ * @fileoverview Ban inline `getDefaultLogger().<method>(...)`. The
+ * logger must be hoisted at the top of the file:
+ *   const logger = getDefaultLogger()
+ *   ...
+ *   logger.success('...')
+ *
+ * Inline `getDefaultLogger().success(...)` re-resolves the logger on
+ * every call and reads inconsistently. The hoisted form is the
+ * fleet-canonical pattern.
+ *
+ * Autofix: rewrites `getDefaultLogger().<method>` → `logger.<method>`
+ * AND inserts the missing pieces in one go:
+ *
+ *   1. `import { getDefaultLogger } from '@socketsecurity/lib/logger'`
+ *      — appended after the last existing top-level import (or at the
+ *      top of the file if there are none).
+ *   2. `const logger = getDefaultLogger()` — appended after the import
+ *      block (so `logger` is hoisted at module scope).
+ *
+ * Each inline call site emits its own fix independently. ESLint's
+ * autofixer dedupes overlapping inserts, so multiple violations in the
+ * same file collapse the import + hoist into a single insertion.
+ */
+
+import { appendImportFixes, summarizeImportTarget } from './_inject-import.mts'
+
+const LOGGER_IMPORT_LINE =
+  "import { getDefaultLogger } from '@socketsecurity/lib/logger'"
+const LOGGER_HOIST_LINE = 'const logger = getDefaultLogger()'
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Hoist getDefaultLogger() to a const at the top of the file; do not call it inline.',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      inline:
+        'getDefaultLogger() must be hoisted: add `const logger = getDefaultLogger()` near the top of the file and use `logger.{{method}}(...)`.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    let summary
+
+    function ensureSummary() {
+      if (summary) {
+        return summary
+      }
+      summary = summarizeImportTarget(
+        sourceCode.ast,
+        '@socketsecurity/lib/logger',
+        'getDefaultLogger',
+        'logger',
+      )
+      return summary
+    }
+
+    return {
+      MemberExpression(node) {
+        // Match: getDefaultLogger().<method>
+        if (node.property.type !== 'Identifier') {
+          return
+        }
+        const obj = node.object
+        if (
+          obj.type !== 'CallExpression' ||
+          obj.callee.type !== 'Identifier' ||
+          obj.callee.name !== 'getDefaultLogger' ||
+          obj.arguments.length !== 0
+        ) {
+          return
+        }
+
+        const s = ensureSummary()
+
+        context.report({
+          node,
+          messageId: 'inline',
+          data: { method: node.property.name },
+          fix(fixer) {
+            // Replace `getDefaultLogger()` (the CallExpression) with
+            // `logger`. Leaves `.method(...)` intact, so the result is
+            // `logger.method(...)`.
+            return [
+              fixer.replaceText(obj, 'logger'),
+              ...appendImportFixes(
+                s,
+                fixer,
+                LOGGER_IMPORT_LINE,
+                LOGGER_HOIST_LINE,
+              ),
+            ]
+          },
+        })
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/no-npx-dlx.mts b/.config/oxlint-plugin/rules/no-npx-dlx.mts
new file mode 100644
index 0000000..dd754e1
--- /dev/null
+++ b/.config/oxlint-plugin/rules/no-npx-dlx.mts
@@ -0,0 +1,192 @@
+/* oxlint-disable socket/no-npx-dlx -- this file IS the rule definition; the banned commands are lookup-table data, not real usage. */
+
+/**
+ * @fileoverview Per CLAUDE.md "Tooling" rule:
+ *
+ *   🚨 NEVER use `npx`, `pnpm dlx`, or `yarn dlx` — use
+ *   `pnpm exec <package>` or `pnpm run <script>`.
+ *
+ * Detects `npx`, `pnpm dlx`, `pnx` (the pnpm-11 dlx shorthand), and
+ * `yarn dlx` in source string literals — argv slices passed to
+ * `spawn()`, shell strings, scripts, doc snippets, README examples,
+ * etc. The hook at `.claude/hooks/path-guard/` blocks these at the
+ * shell layer; this rule catches them at edit / commit time inside
+ * JavaScript / TypeScript source.
+ *
+ * Autofix: rewrites the literal in place — `npx foo` → `pnpm exec foo`,
+ * `pnpm dlx foo` → `pnpm exec foo`, `yarn dlx foo` → `pnpm exec foo`,
+ * `pnx foo` → `pnpm exec foo`.
+ *
+ * Allowed exceptions (skipped):
+ *   - The literal `npx` inside a comment with `socket-hook: allow npx`
+ *     — the canonical bypass marker, used by the lockdown skill spec.
+ *   - The literal `pnpm dlx` inside a comment justifying a soak-window
+ *     bypass (rare; case-by-case).
+ *   - The CLAUDE.md fleet block reference itself — string literals
+ *     like `'`pnpm dlx`'` documenting the rule. Heuristic: skip when
+ *     the literal is inside a backtick-wrapped phrase in the source
+ *     text (i.e. the literal value starts and ends with a backtick).
+ */
+
+const PATTERNS = [
+  // Order matters — longest-prefix first so `pnpm dlx` is matched
+  // before `pnpm` and `pnx ` is matched before `pnpm`. Each entry
+  // is [match-prefix, replacement-prefix, label].
+  ['pnpm dlx ', 'pnpm exec ', 'pnpm dlx'],
+  ['yarn dlx ', 'pnpm exec ', 'yarn dlx'], // socket-hook: allow npx
+  ['npx ', 'pnpm exec ', 'npx'], // socket-hook: allow npx
+  ['pnx ', 'pnpm exec ', 'pnx'],
+]
+
+const COMMENT_BYPASS_RE = /socket-hook:\s*allow\s+npx/ // socket-hook: allow npx
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Use `pnpm exec <package>` instead of `npx` / `pnpm dlx` / `yarn dlx` / `pnx`. Per CLAUDE.md "Tooling" rule.',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      banned:
+        '`{{label}}` — use `pnpm exec` instead. CLAUDE.md "Tooling" rule bans dlx-style commands; they bypass the soak window and fetch packages without lockfile verification.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    /**
+     * Return [matchPrefix, replacementPrefix, label] for the longest
+     * dlx-style prefix that appears anywhere in the string, or
+     * undefined when none match. Anchors at word boundaries — `pnxx`
+     * doesn't match `pnx`.
+     */
+    function findBannedPrefix(value) {
+      for (const [match, repl, label] of PATTERNS) {
+        // Word-boundary check: either the match is at the start, or
+        // the preceding char is non-alphanum (whitespace, punctuation).
+        let idx = 0
+        while ((idx = value.indexOf(match, idx)) !== -1) {
+          const before = idx === 0 ? ' ' : value[idx - 1]
+          if (!/[A-Za-z0-9_-]/.test(before)) {
+            return [match, repl, label, idx]
+          }
+          idx += match.length
+        }
+      }
+      return undefined
+    }
+
+    /**
+     * Skip when the surrounding source has the canonical bypass
+     * comment (`socket-hook: allow npx`) on the same or an adjacent
+     * line.
+     */
+    function hasBypassComment(node) {
+      const before = sourceCode.getCommentsBefore(node)
+      const after = sourceCode.getCommentsAfter(node)
+      for (const c of [...before, ...after]) {
+        if (COMMENT_BYPASS_RE.test(c.value)) {
+          return true
+        }
+      }
+      return false
+    }
+
+    function checkLiteral(node, value) {
+      const found = findBannedPrefix(value)
+      if (!found) {
+        return
+      }
+      if (hasBypassComment(node)) {
+        return
+      }
+      const [match, repl, label] = found
+
+      context.report({
+        node,
+        messageId: 'banned',
+        data: { label },
+        fix(fixer) {
+          // Replace every occurrence in the literal — the literal may
+          // be a shell pipeline like `npx foo && npx bar`.
+          let next = value
+          for (const [m, r] of PATTERNS) {
+            // Word-boundary aware replace-all.
+            const parts = next.split(m)
+            if (parts.length === 1) {
+              continue
+            }
+            // Rejoin only at boundaries; leave embedded matches alone.
+            let out = parts[0]
+            for (let i = 1; i < parts.length; i++) {
+              const prevChar = out.length === 0 ? ' ' : out[out.length - 1]
+              const replacement = /[A-Za-z0-9_-]/.test(prevChar) ? m : r
+              out += replacement + parts[i]
+            }
+            next = out
+          }
+          if (next === value) {
+            // Defensive — if our replace-all became a no-op, don't
+            // ship an empty fix.
+            return null
+          }
+          // Preserve the original quote style.
+          const raw = sourceCode.getText(node)
+          const quote = raw[0]
+          if (quote === '`') {
+            // Template literal — only safe to fix if no expressions.
+            return fixer.replaceText(node, '`' + next + '`')
+          }
+          // Plain string — escape the quote char if it appears.
+          const escaped = next.replace(
+            new RegExp(`\\\\|${quote}`, 'g'),
+            ch => '\\' + ch,
+          )
+          return fixer.replaceText(node, quote + escaped + quote)
+        },
+      })
+    }
+
+    return {
+      Literal(node) {
+        if (typeof node.value !== 'string') {
+          return
+        }
+        checkLiteral(node, node.value)
+      },
+      TemplateLiteral(node) {
+        // Only fix template literals with no expressions — interpolated
+        // strings can't be safely rewritten by string replace.
+        if (node.expressions.length !== 0) {
+          // Still flag — the cooked text might contain `npx`. Report
+          // without autofix.
+          for (const q of node.quasis) {
+            const found = findBannedPrefix(q.value.cooked)
+            if (found) {
+              context.report({
+                node,
+                messageId: 'banned',
+                data: { label: found[2] },
+              })
+              return
+            }
+          }
+          return
+        }
+        const cooked = node.quasis[0].value.cooked
+        checkLiteral(node, cooked)
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/no-placeholders.mts b/.config/oxlint-plugin/rules/no-placeholders.mts
new file mode 100644
index 0000000..589b302
--- /dev/null
+++ b/.config/oxlint-plugin/rules/no-placeholders.mts
@@ -0,0 +1,264 @@
+/* oxlint-disable socket/no-placeholders -- this rule documents the markers it bans. */
+/**
+ * @fileoverview Per CLAUDE.md "Completion" rule: never leave TODO /
+ * FIXME / XXX / shims / stubs / placeholders. Finish the work 100% or
+ * ask before deferring. This rule is the commit-time gate for that
+ * principle and covers every shape a placeholder hides in:
+ *
+ *   1. Comment markers — TODO, FIXME, XXX, HACK, TBD, STUB, WIP,
+ *      UNIMPLEMENTED. Word-boundary anchored so identifiers like
+ *      `todoStore` don't trigger.
+ *
+ *   2. `throw new Error('not implemented')` / `'TODO'` / `'unimplemented'`
+ *      / `'placeholder'` / `'stub'` — the runtime placeholder.
+ *
+ *   3. Stub function bodies — a function whose entire body is empty
+ *      (`{}`) or contains nothing but a placeholder-marker comment.
+ *      `() => undefined` and `() => {}` are flagged when not part of a
+ *      no-op contract (callbacks intentionally suppressed via a
+ *      docstring `@noop` tag escape).
+ *
+ * No autofix: a placeholder is a deferred decision; auto-removing it
+ * leaves the underlying gap. The right move is for a human to either
+ * implement the work or open a tracked issue.
+ *
+ * Allowed exceptions:
+ *   - Marker text inside a string or regex (intentional, e.g. a
+ *     parser that detects TODO comments). Skipped — the rule scopes
+ *     comment matches to comment AST nodes only.
+ *   - Functions that document themselves as intentional no-ops via a
+ *     leading `@noop` JSDoc tag in the immediately preceding comment.
+ *   - Functions whose body is `{ return }` / `{ return undefined }`
+ *     — not flagged unless paired with a placeholder comment. The
+ *     stub detector requires a marker comment in the body.
+ */
+
+const COMMENT_MARKER_RE = /\b(TODO|FIXME|XXX|HACK|TBD|STUB|WIP|UNIMPLEMENTED)\b/
+
+const STUB_BODY_MARKER_RE =
+  /\b(TODO|FIXME|XXX|HACK|TBD|STUB|WIP|UNIMPLEMENTED|not\s+implemented|unimplemented|placeholder|stub)\b/i
+
+const THROW_MESSAGE_RE =
+  /\b(TODO|FIXME|not\s+implemented|unimplemented|placeholder|stub)\b/i
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Ban placeholder code: TODO / FIXME / XXX / HACK / TBD / STUB / WIP / UNIMPLEMENTED markers, `throw new Error("not implemented")`, and empty/stub function bodies. Per CLAUDE.md "Completion" rule — finish the work 100% or open an issue.',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    messages: {
+      commentMarker:
+        '`{{marker}}` comment — finish the work, open an issue, or ask before deferring. CLAUDE.md "Completion" rule bans deferral markers in source.',
+      throwPlaceholder:
+        '`throw new Error({{message}})` is a placeholder — implement the function or remove the stub. CLAUDE.md bans unfinished work.',
+      stubBody:
+        'Function `{{name}}` has a stub body (placeholder comment with no implementation). Finish the function or remove it. Mark intentional no-ops with `@noop` in the leading JSDoc.',
+      emptyBody:
+        'Function `{{name}}` has an empty body and a placeholder marker. Finish the function or remove the marker. Mark intentional no-ops with `@noop` in the leading JSDoc.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    /**
+     * A function counts as "intentionally a no-op" when its leading
+     * JSDoc / line comment contains `@noop`. This is the documented
+     * escape hatch for callbacks that genuinely do nothing
+     * (e.g. event-handler defaults, test spies).
+     */
+    function isExplicitNoop(fnNode) {
+      const leading = sourceCode.getCommentsBefore(fnNode)
+      for (const c of leading) {
+        if (/@noop\b/.test(c.value)) {
+          return true
+        }
+      }
+      // For function declarations the comment is attached to the
+      // declaration; for inline arrows/expressions inside a variable
+      // declaration the comment is attached to the parent.
+      const parent = fnNode.parent
+      if (parent && parent.type === 'VariableDeclarator') {
+        const declStmt = parent.parent
+        if (declStmt) {
+          const above = sourceCode.getCommentsBefore(declStmt)
+          for (const c of above) {
+            if (/@noop\b/.test(c.value)) {
+              return true
+            }
+          }
+        }
+      }
+      return false
+    }
+
+    function functionDisplayName(fnNode) {
+      if (fnNode.id && fnNode.id.name) {
+        return fnNode.id.name
+      }
+      const parent = fnNode.parent
+      if (
+        parent &&
+        parent.type === 'VariableDeclarator' &&
+        parent.id &&
+        parent.id.type === 'Identifier'
+      ) {
+        return parent.id.name
+      }
+      if (
+        parent &&
+        parent.type === 'Property' &&
+        parent.key &&
+        parent.key.type === 'Identifier'
+      ) {
+        return parent.key.name
+      }
+      if (
+        parent &&
+        parent.type === 'MethodDefinition' &&
+        parent.key &&
+        parent.key.type === 'Identifier'
+      ) {
+        return parent.key.name
+      }
+      return '<anonymous>'
+    }
+
+    function bodyMarkerComment(blockNode) {
+      const inner = sourceCode.getCommentsInside
+        ? sourceCode.getCommentsInside(blockNode)
+        : []
+      for (const c of inner) {
+        if (STUB_BODY_MARKER_RE.test(c.value)) {
+          return c
+        }
+      }
+      return undefined
+    }
+
+    function checkFunctionBody(fnNode) {
+      // Arrow expressions like `() => 42` have a non-block body —
+      // they're not stubs.
+      if (!fnNode.body || fnNode.body.type !== 'BlockStatement') {
+        return
+      }
+      if (isExplicitNoop(fnNode)) {
+        return
+      }
+      const block = fnNode.body
+      const stmts = block.body
+      const name = functionDisplayName(fnNode)
+
+      // Empty body + a placeholder marker comment somewhere in the
+      // file pointing at this function. We restrict the marker scan
+      // to the block's own comments — broader scoping creates false
+      // positives.
+      if (stmts.length === 0) {
+        const marker = bodyMarkerComment(block)
+        if (marker) {
+          context.report({
+            node: fnNode,
+            messageId: 'emptyBody',
+            data: { name },
+          })
+        }
+        return
+      }
+
+      // Body that is just `return` / `return undefined` paired with a
+      // placeholder marker comment is a stub. A real return-undefined
+      // function with no marker is allowed (it's just terse).
+      if (stmts.length === 1) {
+        const only = stmts[0]
+        const isBareReturn =
+          only.type === 'ReturnStatement' &&
+          (!only.argument ||
+            (only.argument.type === 'Identifier' &&
+              only.argument.name === 'undefined') ||
+            (only.argument.type === 'Literal' && only.argument.value === null))
+        if (isBareReturn) {
+          const marker = bodyMarkerComment(block)
+          if (marker) {
+            context.report({
+              node: fnNode,
+              messageId: 'stubBody',
+              data: { name },
+            })
+          }
+        }
+      }
+    }
+
+    return {
+      Program() {
+        const comments = sourceCode.getAllComments()
+        for (const comment of comments) {
+          const match = COMMENT_MARKER_RE.exec(comment.value)
+          if (!match) {
+            continue
+          }
+          context.report({
+            node: comment,
+            messageId: 'commentMarker',
+            data: { marker: match[1] },
+          })
+        }
+      },
+
+      ThrowStatement(node) {
+        // Match `throw new Error(<string>)` where the string mentions
+        // a placeholder phrase. We skip non-Error throws and
+        // template-literal throws with interpolations (those usually
+        // carry real runtime context).
+        const arg = node.argument
+        if (
+          !arg ||
+          arg.type !== 'NewExpression' ||
+          arg.callee.type !== 'Identifier' ||
+          !/^(Error|TypeError|RangeError)$/.test(arg.callee.name)
+        ) {
+          return
+        }
+        const first = arg.arguments[0]
+        if (!first) {
+          return
+        }
+        let messageText
+        if (first.type === 'Literal' && typeof first.value === 'string') {
+          messageText = first.value
+        } else if (
+          first.type === 'TemplateLiteral' &&
+          first.expressions.length === 0 &&
+          first.quasis.length === 1
+        ) {
+          messageText = first.quasis[0].value.cooked
+        }
+        if (!messageText) {
+          return
+        }
+        if (!THROW_MESSAGE_RE.test(messageText)) {
+          return
+        }
+        context.report({
+          node,
+          messageId: 'throwPlaceholder',
+          data: { message: JSON.stringify(messageText) },
+        })
+      },
+
+      FunctionDeclaration: checkFunctionBody,
+      FunctionExpression: checkFunctionBody,
+      ArrowFunctionExpression: checkFunctionBody,
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/no-promise-race-in-loop.mts b/.config/oxlint-plugin/rules/no-promise-race-in-loop.mts
new file mode 100644
index 0000000..163e876
--- /dev/null
+++ b/.config/oxlint-plugin/rules/no-promise-race-in-loop.mts
@@ -0,0 +1,103 @@
+/**
+ * @fileoverview Per CLAUDE.md "Promise.race / Promise.any in loops"
+ * rule + the `plug-leaking-promise-race` skill: never re-race a pool
+ * that survives across iterations. Each call's handlers stack onto
+ * the surviving promises, leaking memory and deferring rejection
+ * propagation.
+ *
+ * Detects:
+ *   - `Promise.race(...)` / `Promise.any(...)` syntactically inside
+ *     a `for`, `for-of`, `for-in`, `while`, or `do-while` body.
+ *
+ * The semantic check (whether the racer is the SAME pool across
+ * iterations) is undecidable from syntax. We flag every race-in-loop
+ * and let the human confirm it's safe (e.g., a freshly-built array
+ * each iteration). The skill at .claude/skills/plug-leaking-promise-race/
+ * documents the safe shapes.
+ *
+ * No autofix: the right fix is design-level (track the pool outside
+ * the loop, use AbortController, or restructure to a single race).
+ * Reporting only.
+ */
+
+const RACE_METHODS = new Set(['race', 'any'])
+
+const LOOP_TYPES = new Set([
+  'ForStatement',
+  'ForOfStatement',
+  'ForInStatement',
+  'WhileStatement',
+  'DoWhileStatement',
+])
+
+function isInsideLoop(node) {
+  let current = node.parent
+  while (current) {
+    if (LOOP_TYPES.has(current.type)) {
+      return true
+    }
+    // Function boundaries break the chain — a function defined inside
+    // a loop and invoked elsewhere isn't "in" the loop.
+    if (
+      current.type === 'FunctionDeclaration' ||
+      current.type === 'FunctionExpression' ||
+      current.type === 'ArrowFunctionExpression'
+    ) {
+      return false
+    }
+    current = current.parent
+  }
+  return false
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Ban Promise.race / Promise.any inside loop bodies — handlers stack on surviving promises and leak.',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    messages: {
+      banned:
+        'Promise.{{method}}() inside a loop — handlers stack on surviving promises across iterations and leak. See .claude/skills/plug-leaking-promise-race/SKILL.md for safe shapes.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+        if (callee.type !== 'MemberExpression') {
+          return
+        }
+        if (
+          callee.object.type !== 'Identifier' ||
+          callee.object.name !== 'Promise'
+        ) {
+          return
+        }
+        if (callee.property.type !== 'Identifier') {
+          return
+        }
+        if (!RACE_METHODS.has(callee.property.name)) {
+          return
+        }
+        if (!isInsideLoop(node)) {
+          return
+        }
+
+        context.report({
+          node,
+          messageId: 'banned',
+          data: { method: callee.property.name },
+        })
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/no-promise-race.mts b/.config/oxlint-plugin/rules/no-promise-race.mts
new file mode 100644
index 0000000..d02412a
--- /dev/null
+++ b/.config/oxlint-plugin/rules/no-promise-race.mts
@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Forbid `Promise.race(...)` outright — fleet style.
+ * `Promise.race` resolves with the first settled promise but does not
+ * cancel the losers. Every unsettled promise continues to run, hold
+ * its handles open, and deliver its result into a `.then` chain that
+ * no one consumes. Worse: each call attaches fresh `.then` handlers
+ * to every input promise; if the same long-lived promise is raced
+ * repeatedly (a common shape: race a pool against successive
+ * timeouts), the handler list on that promise grows unboundedly. The
+ * memory leak is invisible at the callsite — the leaking promise is
+ * upstream — and has been known to V8 / Node.js for years without
+ * a fix landing.
+ *
+ * References:
+ *   - https://github.com/nodejs/node/issues/17469 — long-running
+ *     `nodejs/node` issue documenting the handler-list growth and
+ *     why `Promise.race` is the wrong tool for "wait with timeout".
+ *   - https://github.com/cefn/watchable/tree/main/packages/unpromise#readme
+ *     — `@watchable/unpromise` is the canonical workaround:
+ *     subscribe/unsubscribe to a long-lived promise without
+ *     attaching new `.then` handlers per call. Reach for it when
+ *     you genuinely need race semantics on a promise you can't
+ *     restructure away.
+ *
+ * Style signal that motivated the rule: across the fleet's six
+ * surveyed repos, `Promise.race` appears 3 times total (socket-sdk-js
+ * 2, socket-cli 1) — those are stragglers, not a pattern. The fleet
+ * already favors cancellation-aware shapes:
+ *   - `AbortSignal.timeout(ms)` + `AbortSignal.any([...signals])` for
+ *     timeouts and cancellation.
+ *   - `Promise.allSettled(...)` when you genuinely want all results.
+ *   - `Promise.any(...)` if you only care about the first SUCCESS
+ *     (not first SETTLE) — still leaks losers, but at least the
+ *     semantics aren't "first error wins".
+ *   - `@watchable/unpromise` when racing against a long-lived
+ *     promise is unavoidable.
+ *
+ * `no-promise-race-in-loop` is the narrower sibling rule for the
+ * specific "race-in-loop leaks the pool" antipattern. This rule is
+ * broader: every `Promise.race(...)` callsite, anywhere.
+ *
+ * No autofix: the right fix is design-level (introduce an
+ * AbortController, await the loser explicitly, switch to
+ * `AbortSignal.any` + timeout, or adopt `@watchable/unpromise`).
+ * Reporting only.
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Forbid `Promise.race(...)` — losers keep running and leak handles. Use `AbortSignal.any` + timeout, `Promise.allSettled`, or restructure the wait.',
+      category: 'Possible Errors',
+      recommended: true,
+    },
+    fixable: undefined,
+    messages: {
+      noPromiseRace:
+        '`Promise.race(...)` leaves the losing promises pending — they keep their handles, deliver results to no one, and each call attaches new `.then` handlers to every input (handler list grows unboundedly; see nodejs/node#17469). Use `AbortSignal.any([AbortSignal.timeout(ms), userSignal])` for timeouts, `Promise.allSettled` when you need every result, restructure to a single awaited promise, or adopt `@watchable/unpromise` when racing a long-lived promise is unavoidable.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+        if (callee.type !== 'MemberExpression') {
+          return
+        }
+        if (
+          callee.object.type !== 'Identifier' ||
+          callee.object.name !== 'Promise'
+        ) {
+          return
+        }
+        if (
+          callee.property.type !== 'Identifier' ||
+          callee.property.name !== 'race'
+        ) {
+          return
+        }
+        context.report({
+          node,
+          messageId: 'noPromiseRace',
+        })
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/no-status-emoji.mts b/.config/oxlint-plugin/rules/no-status-emoji.mts
new file mode 100644
index 0000000..7adc49c
--- /dev/null
+++ b/.config/oxlint-plugin/rules/no-status-emoji.mts
@@ -0,0 +1,184 @@
+/* oxlint-disable socket/no-status-emoji -- this file IS the rule definition; emoji literals are lookup-table data, not real usage. */
+
+/**
+ * @fileoverview Ban status-symbol emoji literals (✓ ✔ ❌ ✗ ⚠ ⚠️ ❗ ✅
+ * ❎ ☑) inside string literals. The `@socketsecurity/lib/logger`
+ * package owns the visual prefix via `logger.success()` /
+ * `logger.fail()` / `logger.warn()` etc. Hand-rolling the symbols
+ * fragments the visual style and bypasses theme-aware color.
+ *
+ * Autofix: when the literal is the FIRST argument to `console.log` /
+ * `console.error` / `logger.log` (no semantic logger method specified)
+ * AND only one symbol leads the string, rewrite to the matching
+ * `logger.<method>(...)`. Otherwise emit a warning without a fix
+ * (the human picks the right method).
+ */
+
+/* oxlint-disable socket/no-status-emoji -- this rule defines the emoji table it bans. */
+const EMOJI_TO_METHOD = {
+  '✓': 'success',
+  '✔': 'success',
+  '✅': 'success',
+  '❌': 'fail',
+  '✗': 'fail',
+  '❎': 'fail',
+  '⚠': 'warn',
+  '⚠️': 'warn',
+  '❗': 'warn',
+  '☑': 'success',
+}
+/* oxlint-enable socket/no-status-emoji */
+
+const EMOJI = Object.keys(EMOJI_TO_METHOD)
+
+const EMOJI_LEAD_RE = new RegExp(
+  `^\\s*(${EMOJI.map(e => e.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})\\s*`,
+)
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Ban status-symbol emoji literals; use the logger.',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      banned:
+        'Status-symbol emoji "{{emoji}}" — use logger.{{method}}() from @socketsecurity/lib/logger.',
+      bannedAmbiguous:
+        'Status-symbol emoji "{{emoji}}" — use a logger method (success/fail/warn/info) instead of an inline symbol.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    /**
+     * Find any banned emoji in a string. Returns the first match.
+     */
+    function findEmoji(value) {
+      for (const emoji of EMOJI) {
+        if (value.includes(emoji)) {
+          return emoji
+        }
+      }
+      return undefined
+    }
+
+    /**
+     * If the string `value` LEADS with a known emoji + whitespace,
+     * return { emoji, restAfter } where restAfter is the string with
+     * the leading emoji+spaces stripped. Otherwise null.
+     */
+    function leadingEmoji(value) {
+      const match = EMOJI_LEAD_RE.exec(value)
+      if (!match) {
+        return undefined
+      }
+      return {
+        emoji: match[1],
+        restAfter: value.slice(match[0].length),
+      }
+    }
+
+    /**
+     * Try to autofix by rewriting `console.log('✓ Done')` →
+     * `logger.success('Done')`. Returns a fixer function or null.
+     */
+    function tryFix(node, literalNode, leadInfo) {
+      const method = EMOJI_TO_METHOD[leadInfo.emoji]
+      if (!method) {
+        return undefined
+      }
+
+      // Only fix when the parent is a CallExpression and the literal
+      // is the first argument. Otherwise leave to the human.
+      const parent = node.parent
+      if (!parent || parent.type !== 'CallExpression') {
+        return undefined
+      }
+      if (parent.arguments[0] !== literalNode) {
+        return undefined
+      }
+
+      const callee = parent.callee
+      if (callee.type !== 'MemberExpression') {
+        return undefined
+      }
+
+      const objectName =
+        callee.object.type === 'Identifier' ? callee.object.name : undefined
+      const propName =
+        callee.property.type === 'Identifier' ? callee.property.name : undefined
+      if (!objectName || !propName) {
+        return undefined
+      }
+
+      const isConsole =
+        objectName === 'console' &&
+        ['log', 'error', 'warn', 'info'].includes(propName)
+      const isLoggerLog =
+        objectName === 'logger' && (propName === 'log' || propName === 'info')
+
+      if (!isConsole && !isLoggerLog) {
+        return undefined
+      }
+
+      // Build the replacement.
+      const quote = literalNode.raw[0]
+      const newLiteral = `${quote}${leadInfo.restAfter.replace(new RegExp(quote, 'g'), '\\' + quote)}${quote}`
+
+      return fixer => [
+        fixer.replaceText(callee, `logger.${method}`),
+        fixer.replaceText(literalNode, newLiteral),
+      ]
+    }
+
+    function reportLiteral(node) {
+      const value = typeof node.value === 'string' ? node.value : undefined
+      if (!value) {
+        return
+      }
+
+      const emoji = findEmoji(value)
+      if (!emoji) {
+        return
+      }
+
+      const leadInfo = leadingEmoji(value)
+      const method = leadInfo ? EMOJI_TO_METHOD[leadInfo.emoji] : undefined
+
+      if (leadInfo && method) {
+        const fix = tryFix(node, node, leadInfo)
+        context.report({
+          node,
+          messageId: 'banned',
+          data: { emoji: leadInfo.emoji, method },
+          ...(fix ? { fix } : {}),
+        })
+      } else {
+        context.report({
+          node,
+          messageId: 'bannedAmbiguous',
+          data: { emoji },
+        })
+      }
+    }
+
+    return {
+      Literal(node) {
+        reportLiteral(node)
+      },
+      TemplateElement(node) {
+        if (node.value && typeof node.value.cooked === 'string') {
+          // Treat template-string segments like literals for detection only.
+          reportLiteral({ ...node, value: node.value.cooked })
+        }
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/personal-path-placeholders.mts b/.config/oxlint-plugin/rules/personal-path-placeholders.mts
new file mode 100644
index 0000000..323b7a7
--- /dev/null
+++ b/.config/oxlint-plugin/rules/personal-path-placeholders.mts
@@ -0,0 +1,216 @@
+/**
+ * @fileoverview Per CLAUDE.md "Token hygiene → Personal-path
+ * placeholders" rule:
+ *
+ *   When a doc / test / comment needs to show an example user-home
+ *   path, use the canonical platform-specific placeholder so the
+ *   personal-paths scanner recognizes it as documentation:
+ *     /Users/<user>/...     (macOS)
+ *     /home/<user>/...      (Linux)
+ *     C:\Users\<USERNAME>\... (Windows)
+ *
+ *   Don't drift to <name> / <me> / <USER> / <u> etc. — the scanner
+ *   accepts anything in <...> but a fleet-wide audit relies on the
+ *   canonical strings being grep-able.
+ *
+ * Detects user-home paths in string literals + comments where the
+ * placeholder slug isn't the canonical form. The detection is
+ * conservative: a string must clearly look like a user-home path
+ * before the rule fires.
+ *
+ * Autofix: replaces the non-canonical placeholder with the canonical
+ * one for the platform path prefix:
+ *   /Users/<X>/      → /Users/<user>/
+ *   /home/<X>/       → /home/<user>/
+ *   C:\Users\<X>\    → C:\Users\<USERNAME>\
+ *   C:/Users/<X>/    → C:/Users/<USERNAME>/
+ *
+ * Real personal data (a literal username instead of a placeholder)
+ * is also flagged. Two scenarios:
+ *
+ *   1. Source code / docs / tests — the path was hand-written and
+ *      should be replaced with the canonical placeholder, an env-var
+ *      form (`$HOME`, `${USER}`, `%USERNAME%`), or deleted entirely.
+ *   2. WASM / generated bundles — a literal username inside compiled
+ *      output means a build pipeline is leaking the developer's path
+ *      into the artifact (typically esbuild / rolldown sourcemaps,
+ *      sourceMappingURL, or `__filename` baked at build time).
+ *      The fix is the build config, NOT the artifact — chasing the
+ *      string in the bundle is treating the symptom.
+ *
+ * The deterministic linter can't tell scenario 1 from scenario 2,
+ * so it reports without an autofix. The AI-fix step (Step 4 of
+ * `pnpm run fix`) handles both: rewriting source mentions for #1
+ * and tracing back to the build config for #2.
+ */
+
+const PLACEHOLDER_RE = /<([^>]+)>/
+
+const PATTERNS = [
+  {
+    // /Users/<X>/...
+    re: /(\/Users\/)<([^>]+)>(\/|$)/,
+    canonical: 'user',
+    label: '/Users/<user>/',
+  },
+  {
+    // /home/<X>/...
+    re: /(\/home\/)<([^>]+)>(\/|$)/,
+    canonical: 'user',
+    label: '/home/<user>/',
+  },
+  {
+    // C:\Users\<X>\... or C:/Users/<X>/
+    re: /([A-Za-z]:[\\/]Users[\\/])<([^>]+)>([\\/]|$)/,
+    canonical: 'USERNAME',
+    label: 'C:\\Users\\<USERNAME>\\',
+  },
+]
+
+/**
+ * A real-username detection — a path of the same shape but with a
+ * non-placeholder username segment. Reported, not fixed.
+ */
+const REAL_USERNAME_PATTERNS = [
+  /(\/Users\/)([a-zA-Z][a-zA-Z0-9_-]{1,31})(\/)/,
+  /(\/home\/)([a-zA-Z][a-zA-Z0-9_-]{1,31})(\/)/,
+]
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Use canonical personal-path placeholders (<user> on Unix, <USERNAME> on Windows). Drift breaks fleet-wide grep audits.',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      drift:
+        'Personal-path placeholder `<{{actual}}>` should be the canonical `<{{canonical}}>`. Saw `{{path}}`; expected the form `{{label}}`.',
+      realUsername:
+        'Personal path with literal username `{{name}}`. In source/docs: replace with placeholder `{{label}}`, an env-var form, or delete the path. In WASM / generated bundles: this is a build leak — fix the bundler config, not the artifact.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    function checkText(textNode, text, isComment) {
+      // First pass: drift detection — replace non-canonical
+      // placeholders with the canonical form.
+      let mutated = false
+      let next = text
+      let firstReport
+      for (const p of PATTERNS) {
+        const reAll = new RegExp(p.re.source, 'g')
+        next = next.replace(reAll, (whole, prefix, slug, suffix) => {
+          if (slug === p.canonical) {
+            return whole
+          }
+          // Skip env-var forms — already canonical.
+          if (/^\$|^%/.test(slug)) {
+            return whole
+          }
+          if (!firstReport) {
+            firstReport = {
+              actual: slug,
+              canonical: p.canonical,
+              path: whole,
+              label: p.label,
+            }
+          }
+          mutated = true
+          return `${prefix}<${p.canonical}>${suffix}`
+        })
+      }
+
+      if (mutated && firstReport) {
+        context.report({
+          node: textNode,
+          messageId: 'drift',
+          data: firstReport,
+          fix(fixer) {
+            if (isComment) {
+              const prefix = textNode.type === 'Line' ? '//' : '/*'
+              const suffix = textNode.type === 'Line' ? '' : '*/'
+              return fixer.replaceTextRange(
+                textNode.range,
+                prefix + next + suffix,
+              )
+            }
+            const raw = sourceCode.getText(textNode)
+            const quote = raw[0]
+            if (quote === '`') {
+              return fixer.replaceText(textNode, '`' + next + '`')
+            }
+            const escaped = next.replace(
+              new RegExp(`\\\\|${quote}`, 'g'),
+              ch => '\\' + ch,
+            )
+            return fixer.replaceText(textNode, quote + escaped + quote)
+          },
+        })
+        return
+      }
+
+      // Second pass: real-username detection (no autofix).
+      for (const re of REAL_USERNAME_PATTERNS) {
+        const m = re.exec(text)
+        if (!m) {
+          continue
+        }
+        // Skip if the slug is a known placeholder shape (already
+        // handled above), env-var, or canonical literal "user".
+        const slug = m[2]
+        if (slug === 'user' || slug === 'USERNAME') {
+          continue
+        }
+        // Skip platform-canonical literals like "Shared".
+        if (slug === 'Shared' || slug === 'Public') {
+          continue
+        }
+        const label =
+          re.source.indexOf('Users') !== -1 ? '/Users/<user>/' : '/home/<user>/'
+        context.report({
+          node: textNode,
+          messageId: 'realUsername',
+          data: { name: slug, label },
+        })
+        return
+      }
+    }
+
+    return {
+      Literal(node) {
+        if (typeof node.value !== 'string') {
+          return
+        }
+        checkText(node, node.value, false)
+      },
+      TemplateLiteral(node) {
+        if (node.expressions.length !== 0) {
+          // Mixed template — only inspect the static parts.
+          for (const q of node.quasis) {
+            checkText(node, q.value.cooked, false)
+          }
+          return
+        }
+        checkText(node, node.quasis[0].value.cooked, false)
+      },
+      Program() {
+        const comments = sourceCode.getAllComments()
+        for (const comment of comments) {
+          checkText(comment, comment.value, true)
+        }
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/prefer-async-spawn.mts b/.config/oxlint-plugin/rules/prefer-async-spawn.mts
new file mode 100644
index 0000000..2fa066b
--- /dev/null
+++ b/.config/oxlint-plugin/rules/prefer-async-spawn.mts
@@ -0,0 +1,271 @@
+/**
+ * @fileoverview Per CLAUDE.md "Subprocesses" rule:
+ *
+ *   Prefer async `spawn` from `@socketsecurity/lib/spawn` over
+ *   `spawnSync` from `node:child_process`. Async unblocks parallel
+ *   tests / event-loop work; the sync version freezes the runner for
+ *   the duration of the child. Use `spawnSync` only when you genuinely
+ *   need synchronous semantics.
+ *
+ * Detects:
+ *   - `import { spawnSync } from 'node:child_process'`
+ *   - `import { spawnSync } from 'child_process'`
+ *   - `child_process.spawnSync(...)` calls (when the require side
+ *     dodges the import-name detector).
+ *   - `spawn` from `node:child_process` — recommend the lib instead.
+ *     Even the async core spawn lacks the lib's SpawnError shape.
+ *
+ * Autofix scope (deterministic; no AI required):
+ *   - **Imports**: rewrites the import statement to pull from
+ *     `@socketsecurity/lib/spawn`. `spawnSync` becomes `spawn` and
+ *     callers see the imported binding rename. Skipped when:
+ *       a) the import has multiple violating names (would need a
+ *          merged import statement),
+ *       b) the file already has another import from the lib that
+ *          would clash,
+ *       c) any non-banned named import (e.g. `exec`, `execSync`)
+ *          shares the same statement — the lib doesn't re-export
+ *          those, so we can't safely rewrite the whole line.
+ *   - **Calls**: `await child_process.spawnSync(args)` inside an
+ *     async function body becomes `await spawn(args)` (assuming the
+ *     spawn import is also rewritten). We require the call to be the
+ *     argument of an `await` already, OR the surrounding function to
+ *     be async — that's the marker for "the caller is ready for a
+ *     promise."
+ *
+ * Allowed exceptions:
+ *   - Adjacent comment with `prefer-async-spawn: sync-required` —
+ *     for top-level scripts whose entire flow is sync (per CLAUDE.md
+ *     "Reserve `spawnSync` for top-level scripts whose entire flow is
+ *     sync").
+ *   - Files inside `@socketsecurity/lib/spawn` itself — they wrap the
+ *     core APIs. Handled at the .config/oxlintrc.json ignorePatterns level.
+ */
+
+const CHILD_PROCESS_SPECIFIERS = new Set([
+  'node:child_process',
+  'child_process',
+])
+
+const LIB_SPECIFIER = '@socketsecurity/lib/spawn'
+
+const BANNED_NAMES = new Set(['spawnSync', 'spawn'])
+
+const BYPASS_RE = /prefer-async-spawn:\s*sync-required/
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Use `spawn` from @socketsecurity/lib/spawn instead of `spawnSync` / core `spawn` from node:child_process.',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      importBanned:
+        'Importing `{{name}}` from {{specifier}} — use `spawn` from @socketsecurity/lib/spawn. Async unblocks parallel work and the lib ships consistent error shapes (SpawnError).',
+      callBanned:
+        'Calling `child_process.{{name}}(...)` — use `spawn` from @socketsecurity/lib/spawn instead.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    function hasBypassComment(node) {
+      const before = sourceCode.getCommentsBefore(node)
+      const after = sourceCode.getCommentsAfter(node)
+      for (const c of [...before, ...after]) {
+        if (BYPASS_RE.test(c.value)) {
+          return true
+        }
+      }
+      return false
+    }
+
+    /**
+     * Walk up the AST until we find an enclosing function or the
+     * Program root. Returns true when an `async` function or top-level
+     * module is reached (top-level await is allowed in ES modules).
+     */
+    function isInAsyncContext(node) {
+      let cur = node.parent
+      while (cur) {
+        if (
+          cur.type === 'FunctionDeclaration' ||
+          cur.type === 'FunctionExpression' ||
+          cur.type === 'ArrowFunctionExpression'
+        ) {
+          return Boolean(cur.async)
+        }
+        if (cur.type === 'Program') {
+          // Top-level: ESM allows top-level await, so async context is
+          // available. CommonJS doesn't, but we can't reliably tell
+          // from the AST alone — `sourceType: 'module'` is the signal.
+          return cur.sourceType === 'module'
+        }
+        cur = cur.parent
+      }
+      return false
+    }
+
+    /**
+     * Build a fixer for an import declaration. Conservatively skip
+     * when other (non-banned) named imports share the line — those
+     * may not be re-exported by the lib spawn module.
+     *
+     * Successful rewrite: replaces the whole import statement with
+     * `import { spawn } from '@socketsecurity/lib/spawn'`.
+     */
+    function fixImport(fixer, node) {
+      const banned = node.specifiers.filter(
+        s =>
+          s.type === 'ImportSpecifier' &&
+          s.imported &&
+          BANNED_NAMES.has(s.imported.name),
+      )
+      if (banned.length === 0) {
+        return null
+      }
+      const others = node.specifiers.filter(
+        s =>
+          s.type !== 'ImportSpecifier' ||
+          !s.imported ||
+          !BANNED_NAMES.has(s.imported.name),
+      )
+      if (others.length > 0) {
+        // Mixed line — leave it alone; a partial rewrite could lose
+        // the non-banned import.
+        return null
+      }
+      // The lib re-exports `spawn` (and the user can wire `as
+      // spawnSync` themselves if they really need a name). For the
+      // common case (single `spawnSync` import), rewrite to `spawn`
+      // and let the call sites get separately handled.
+      return fixer.replaceText(node, `import { spawn } from '${LIB_SPECIFIER}'`)
+    }
+
+    return {
+      ImportDeclaration(node) {
+        const specifier = node.source.value
+        if (!CHILD_PROCESS_SPECIFIERS.has(specifier)) {
+          return
+        }
+        if (hasBypassComment(node)) {
+          return
+        }
+        const banned = node.specifiers.filter(
+          s =>
+            s.type === 'ImportSpecifier' &&
+            s.imported &&
+            BANNED_NAMES.has(s.imported.name),
+        )
+        if (banned.length === 0) {
+          return
+        }
+
+        for (const spec of banned) {
+          context.report({
+            node: spec,
+            messageId: 'importBanned',
+            data: {
+              name: spec.imported.name,
+              specifier: `'${specifier}'`,
+            },
+            // Only the first banned-import on the line emits the fix;
+            // ESLint dedupes overlapping inserts so this is safe.
+            fix(fixer) {
+              return fixImport(fixer, node)
+            },
+          })
+        }
+      },
+
+      // child_process.spawnSync(...) — covers `require('child_process').spawnSync(...)`
+      // and `cp.spawnSync(...)` when the local binding is named cp.
+      CallExpression(node) {
+        const callee = node.callee
+        if (callee.type !== 'MemberExpression') {
+          return
+        }
+        if (callee.property.type !== 'Identifier') {
+          return
+        }
+        if (!BANNED_NAMES.has(callee.property.name)) {
+          return
+        }
+        // Match `<obj>.spawnSync(...)` where <obj> is a known
+        // child_process binding. We can't perfectly track requires
+        // without scope analysis, so accept common alias names.
+        const obj = callee.object
+        const objName =
+          obj.type === 'Identifier'
+            ? obj.name
+            : obj.type === 'MemberExpression' &&
+                obj.property.type === 'Identifier'
+              ? obj.property.name
+              : undefined
+        if (!objName) {
+          return
+        }
+        if (!/^(child_process|childProcess|cp)$/.test(objName)) {
+          return
+        }
+        if (hasBypassComment(node)) {
+          return
+        }
+
+        // Autofix only when we're confident the rewrite is safe:
+        //   - Surrounding scope is async (or top-level ESM).
+        //   - The call is not used as a value-bearing return (we
+        //     can't tell what the caller does with `{ stdout, stderr,
+        //     code }` — async spawn returns a thenable, not a sync
+        //     object). Detect: parent is an ExpressionStatement OR an
+        //     AwaitExpression. Anything else (assignment, return,
+        //     property access) needs human eyes.
+        const parent = node.parent
+        const looksAwaitable =
+          parent &&
+          (parent.type === 'AwaitExpression' ||
+            parent.type === 'ExpressionStatement')
+        const fixable = looksAwaitable && isInAsyncContext(node)
+
+        if (!fixable) {
+          context.report({
+            node,
+            messageId: 'callBanned',
+            data: { name: callee.property.name },
+          })
+          return
+        }
+
+        context.report({
+          node,
+          messageId: 'callBanned',
+          data: { name: callee.property.name },
+          fix(fixer) {
+            const argText = node.arguments
+              .map(a => sourceCode.getText(a))
+              .join(', ')
+            // If parent is already an AwaitExpression we keep the
+            // await — replace the inner CallExpression. If parent is
+            // an ExpressionStatement, prepend `await` so the promise
+            // chain is awaited.
+            if (parent.type === 'AwaitExpression') {
+              return fixer.replaceText(node, `spawn(${argText})`)
+            }
+            return fixer.replaceText(node, `await spawn(${argText})`)
+          },
+        })
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/prefer-cached-for-loop.mts b/.config/oxlint-plugin/rules/prefer-cached-for-loop.mts
new file mode 100644
index 0000000..f3eefc0
--- /dev/null
+++ b/.config/oxlint-plugin/rules/prefer-cached-for-loop.mts
@@ -0,0 +1,433 @@
+/**
+ * @fileoverview Prefer a cached-length C-style `for` loop over both
+ * `.forEach(cb)` and `for...of`. Two distinct wins:
+ *
+ *   1. `.forEach` creates a function frame per iteration; the
+ *      C-style loop does not. For hot paths the difference is
+ *      measurable, and the readability cost is small once the
+ *      pattern is uniform across the fleet.
+ *   2. `for...of` allocates an iterator object and dispatches
+ *      `Symbol.iterator` / `.next()` per step. For plain arrays
+ *      (the fleet's overwhelmingly common case) the cached-length
+ *      `for` loop is both faster and produces predictable
+ *      generated code under TS/oxc.
+ *
+ * Style signal that motivated the rule: jdalton has hand-optimized
+ * fleet hot paths to cached-length `for (let i = 0, { length } = arr; i < length; i += 1)`
+ * form repeatedly. Encoding the preference as a rule prevents drift
+ * back to the more idiomatic forms in subsequent edits.
+ *
+ * Canonical shape emitted by the autofix:
+ *
+ *   for (let i = 0, { length } = arr; i < length; i += 1) {
+ *     const item = arr[i]
+ *     <body>
+ *   }
+ *
+ * Notes on the shape:
+ *   - `i += 1` instead of `i++` — postfix `++` returns the
+ *     pre-increment value, which is a common source of off-by-one
+ *     bugs and which the fleet's lint config bans elsewhere.
+ *   - `{ length } = arr` destructures the length once at loop init,
+ *     so the test `i < length` doesn't re-read `arr.length` per
+ *     iteration. Equivalent to `const len = arr.length` but pairs
+ *     with `let i = 0` in a single `let` head.
+ *
+ * Autofix scope (deterministic only):
+ *
+ *   - `arr.forEach((item) => { body })` →
+ *     ```
+ *     for (let i = 0, { length } = arr; i < length; i += 1) {
+ *       const item = arr[i]
+ *       body
+ *     }
+ *     ```
+ *
+ *   - `arr.forEach((item, index) => { body })` →
+ *     ```
+ *     for (let index = 0, { length } = arr; index < length; index += 1) {
+ *       const item = arr[index]
+ *       body
+ *     }
+ *     ```
+ *     (The second-arg `index` name takes over the loop counter — no
+ *     name collision since the callback parameter is in its own
+ *     scope.)
+ *
+ *   - `for (const item of arr) { body }` →
+ *     ```
+ *     for (let i = 0, { length } = arr; i < length; i += 1) {
+ *       const item = arr[i]
+ *       body
+ *     }
+ *     ```
+ *
+ * Skips (report-only or skip entirely):
+ *   - `.forEach` with a function reference (not an inline arrow /
+ *     function expression) — e.g. `arr.forEach(handler)` — the
+ *     callback is opaque; rewriting would change semantics if the
+ *     handler uses `arguments` or has a non-trivial `.length`.
+ *   - `.forEach` with `thisArg` (2nd argument).
+ *   - `.forEach` whose callback uses a 3rd `array` parameter — we'd
+ *     need to bind a separate name, and the construct is rare.
+ *   - `.forEach` whose callback references `this` (would need
+ *     `.bind(this)`).
+ *   - `.forEach` whose callback has destructured / non-Identifier
+ *     parameters (`({ id }) => {}`) — rewriting requires inserting a
+ *     destructure pattern inside the loop body; doable but the
+ *     human review is cleaner.
+ *   - `.forEach` containing `await` (the callback was previously
+ *     async and the iterations were independent; switching to a
+ *     `for` loop changes that to sequential awaits, which IS what
+ *     the user wants here but only if they say so — flag instead).
+ *   - `for...of` over an iterator that isn't a bare Identifier
+ *     (`for (const x of getThings())`) — we'd need to hoist the
+ *     iterable to a `const` first; skip and flag.
+ *   - `for...of` whose body uses `continue`/`break` labels matching
+ *     `i` or `length` (extremely rare; skip to be safe).
+ *   - `for...await...of` — semantically distinct, do not touch.
+ *   - `for...of` over non-array iterables (Map, Set, generators)
+ *     — we can't tell statically, but the rule only fires when the
+ *     iterable looks like an array-typed identifier. To stay
+ *     deterministic we accept some false negatives and only autofix
+ *     the bare-Identifier-array shape; the reporter still flags
+ *     other shapes so the human can convert manually.
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Prefer cached-length C-style `for (let i = 0, { length } = arr; i < length; i += 1)` over `.forEach` and `for...of`.',
+      category: 'Stylistic Issues',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      preferCachedFor:
+        'Use a cached-length `for (let i = 0, { length } = {{iter}}; i < length; i += 1)` loop instead of `{{shape}}` — avoids per-iteration callback / iterator allocation.',
+      preferCachedForNoFix:
+        'Use a cached-length `for` loop instead of `{{shape}}`, but the rewrite is unsafe here ({{reason}}). Rewrite manually.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    return {
+      CallExpression(node) {
+        // Match `<iter>.forEach(cb)` patterns.
+        const callee = node.callee
+        if (callee.type !== 'MemberExpression') {
+          return
+        }
+        if (
+          callee.property.type !== 'Identifier' ||
+          callee.property.name !== 'forEach'
+        ) {
+          return
+        }
+        if (callee.computed) {
+          return
+        }
+        if (node.arguments.length === 0 || node.arguments.length > 1) {
+          // 0 args is invalid JS; 2 args means a `thisArg` was passed
+          // (changes semantics if we drop it).
+          return
+        }
+        const cb = node.arguments[0]
+        if (
+          cb.type !== 'ArrowFunctionExpression' &&
+          cb.type !== 'FunctionExpression'
+        ) {
+          context.report({
+            node,
+            messageId: 'preferCachedForNoFix',
+            data: {
+              shape: '.forEach(handler)',
+              reason: 'callback is not an inline arrow / function expression',
+            },
+          })
+          return
+        }
+        if (cb.params.length === 0 || cb.params.length > 2) {
+          // 3rd `array` param is rare; 0 params means the callback
+          // doesn't consume the item — flag without fix.
+          context.report({
+            node,
+            messageId: 'preferCachedForNoFix',
+            data: {
+              shape: '.forEach',
+              reason: 'callback arity is 0 or 3+',
+            },
+          })
+          return
+        }
+        const itemParam = cb.params[0]
+        const indexParam = cb.params[1]
+        if (itemParam.type !== 'Identifier') {
+          context.report({
+            node,
+            messageId: 'preferCachedForNoFix',
+            data: {
+              shape: '.forEach',
+              reason: 'first parameter is destructured',
+            },
+          })
+          return
+        }
+        if (indexParam && indexParam.type !== 'Identifier') {
+          context.report({
+            node,
+            messageId: 'preferCachedForNoFix',
+            data: {
+              shape: '.forEach',
+              reason: 'second parameter is destructured',
+            },
+          })
+          return
+        }
+        if (cb.body.type !== 'BlockStatement') {
+          // Expression-body arrow — would need to wrap as statement.
+          // Trivially doable but rare for forEach; flag.
+          context.report({
+            node,
+            messageId: 'preferCachedForNoFix',
+            data: {
+              shape: '.forEach',
+              reason: 'callback uses expression body',
+            },
+          })
+          return
+        }
+        if (cb.async) {
+          context.report({
+            node,
+            messageId: 'preferCachedForNoFix',
+            data: {
+              shape: '.forEach',
+              reason:
+                'callback is async (changes parallel-vs-sequential semantics)',
+            },
+          })
+          return
+        }
+        const bodyText = sourceCode.getText(cb.body)
+        if (/\bthis\b/.test(bodyText)) {
+          context.report({
+            node,
+            messageId: 'preferCachedForNoFix',
+            data: { shape: '.forEach', reason: 'callback references `this`' },
+          })
+          return
+        }
+        // Reject if the forEach call is followed by a chained call
+        // (.forEach(...).then(...) doesn't exist on void return, but
+        // .map(...).forEach(...).filter(...) would mean we're inside
+        // a chain — parent's a MemberExpression with us as object).
+        const parent = node.parent
+        if (
+          parent &&
+          parent.type === 'MemberExpression' &&
+          parent.object === node
+        ) {
+          // forEach returns undefined; chaining off it is broken — skip
+          // rather than rewrite something that doesn't even run.
+          return
+        }
+        // forEach call must be its own ExpressionStatement to be a
+        // safe textual replacement.
+        if (!parent || parent.type !== 'ExpressionStatement') {
+          context.report({
+            node,
+            messageId: 'preferCachedForNoFix',
+            data: {
+              shape: '.forEach',
+              reason: 'call result is consumed (not a standalone statement)',
+            },
+          })
+          return
+        }
+
+        const iterText = sourceCode.getText(callee.object)
+        const itemName = itemParam.name
+        const indexName = indexParam ? indexParam.name : 'i'
+        // If the callback body reassigns the item param (e.g.
+        // `arr.forEach(line => { line = line.trim(); ... })`), the
+        // rewritten `const line = arr[i]` would trip `no-const-assign`.
+        // Emit `let` in that case so the rewrite preserves the
+        // mutable-binding semantics the original arrow had per call.
+        const itemKind = reassignsInBody(sourceCode, cb.body, itemName)
+          ? 'let'
+          : 'const'
+
+        context.report({
+          node,
+          messageId: 'preferCachedFor',
+          data: { iter: iterText, shape: '.forEach' },
+          fix(fixer) {
+            const bodyInner = sourceCode.text.slice(
+              cb.body.range[0] + 1,
+              cb.body.range[1] - 1,
+            )
+            const indent = leadingIndent(sourceCode, parent)
+            const innerIndent = `${indent}  `
+            const replacement = `for (let ${indexName} = 0, { length } = ${iterText}; ${indexName} < length; ${indexName} += 1) {\n${innerIndent}${itemKind} ${itemName} = ${iterText}[${indexName}]${bodyInner}\n${indent}}`
+            return fixer.replaceText(parent, replacement)
+          },
+        })
+      },
+
+      ForOfStatement(node) {
+        // for await ... — leave alone.
+        if (node.await) {
+          return
+        }
+        const left = node.left
+        if (left.type !== 'VariableDeclaration') {
+          // `for (item of arr)` — bare assignment; rare, skip.
+          return
+        }
+        if (left.declarations.length !== 1) {
+          return
+        }
+        const declarator = left.declarations[0]
+        if (!declarator.id || declarator.id.type !== 'Identifier') {
+          context.report({
+            node,
+            messageId: 'preferCachedForNoFix',
+            data: {
+              shape: 'for...of',
+              reason: 'loop variable is destructured',
+            },
+          })
+          return
+        }
+        // Iterable must be a bare Identifier — otherwise we don't
+        // know if it's a (cheap) array indexing target.
+        const iter = node.right
+        if (iter.type !== 'Identifier') {
+          context.report({
+            node,
+            messageId: 'preferCachedForNoFix',
+            data: {
+              shape: 'for...of',
+              reason:
+                'iterable is not a bare identifier (could be Map/Set/Generator/expression)',
+            },
+          })
+          return
+        }
+        if (node.body.type !== 'BlockStatement') {
+          // for (x of y) statement; rare. Skip.
+          return
+        }
+
+        const itemName = declarator.id.name
+        const iterText = iter.name
+        const counterName = pickCounterName(itemName)
+        // Preserve the original `let`/`const` declaration kind from
+        // the `for...of`. `for (let item of arr)` opted into a
+        // mutable per-iteration binding (the body may reassign
+        // `item`); collapsing it to a `const` would break the loop.
+        // If the original was `const`, only keep `const` when the
+        // body never reassigns the loop variable.
+        const originalKind = left.kind
+        const itemKind =
+          originalKind === 'let' ||
+          reassignsInBody(sourceCode, node.body, itemName)
+            ? 'let'
+            : 'const'
+
+        context.report({
+          node,
+          messageId: 'preferCachedFor',
+          data: { iter: iterText, shape: 'for...of' },
+          fix(fixer) {
+            const bodyInner = sourceCode.text.slice(
+              node.body.range[0] + 1,
+              node.body.range[1] - 1,
+            )
+            const indent = leadingIndent(sourceCode, node)
+            const innerIndent = `${indent}  `
+            const replacement = `for (let ${counterName} = 0, { length } = ${iterText}; ${counterName} < length; ${counterName} += 1) {\n${innerIndent}${itemKind} ${itemName} = ${iterText}[${counterName}]${bodyInner}\n${indent}}`
+            return fixer.replaceText(node, replacement)
+          },
+        })
+      },
+    }
+  },
+}
+
+/**
+ * Pick a counter-variable name that won't collide with the item
+ * variable. Defaults to `i`, falls back to `i2`, `i3`, ... if the
+ * item is itself named `i` (rare but defensive).
+ */
+function pickCounterName(itemName) {
+  if (itemName !== 'i') {
+    return 'i'
+  }
+  return 'i2'
+}
+
+/**
+ * Textual check: does the loop body reassign the named identifier?
+ * Catches `name = ...`, `name +=`, `name++`, `++name`, etc., and
+ * destructuring-as-assignment patterns. Conservative: false
+ * positives only force `let` (semantically safe), false negatives
+ * trip `no-const-assign` (the bug this guards against).
+ *
+ * AST-walking would be more precise but oxlint's plugin host
+ * doesn't expose a uniform visitor for body subtrees here; the
+ * regex catches every reassignment shape that compiles today.
+ */
+function reassignsInBody(sourceCode, bodyNode, name) {
+  if (!bodyNode) {
+    return false
+  }
+  const text = sourceCode.text.slice(bodyNode.range[0], bodyNode.range[1])
+  // Escape any regex specials in the identifier (defensive — JS
+  // identifiers can't actually contain them, but cheap).
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  // Patterns:
+  //   1. <name> = ...   (simple assignment, not `==` / `===`)
+  //   2. <name> += ...  / -=, *=, /=, %=, **=, &=, |=, ^=, <<=, >>=, >>>=, &&=, ||=, ??=
+  //   3. <name>++ / <name>--
+  //   4. ++<name> / --<name>
+  //   5. ({ <name> } = ...) / ([<name>] = ...) destructuring — caught by the
+  //      same `<name>... =` shape inside a destructure since the rightmost
+  //      `=` is the assignment.
+  // Use `\b` boundaries on the name. The `(?!=)` lookahead rejects `==`.
+  const reassignRE = new RegExp(
+    String.raw`\b${escaped}\b\s*(?:=(?!=)|[-+*/%&|^]=|<<=|>>=|>>>=|\*\*=|&&=|\|\|=|\?\?=|\+\+|--)`,
+  )
+  if (reassignRE.test(text)) {
+    return true
+  }
+  // Prefix increment/decrement: `++<name>` / `--<name>`.
+  const prefixRE = new RegExp(String.raw`(?:\+\+|--)\s*\b${escaped}\b`)
+  return prefixRE.test(text)
+}
+
+/**
+ * Recover the indentation prefix on the line where `node` starts so
+ * the rewritten block can re-indent its contents consistently with
+ * the surrounding code.
+ */
+function leadingIndent(sourceCode, node) {
+  const text = sourceCode.text
+  const start = node.range[0]
+  const lineStart = text.lastIndexOf('\n', start - 1) + 1
+  const indent = text.slice(lineStart, start)
+  // Strip non-whitespace (in case the line has content before this
+  // statement). Indent is the leading-whitespace prefix only.
+  return /^\s*/.exec(indent)[0]
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/prefer-exists-sync.mts b/.config/oxlint-plugin/rules/prefer-exists-sync.mts
new file mode 100644
index 0000000..7c3e31a
--- /dev/null
+++ b/.config/oxlint-plugin/rules/prefer-exists-sync.mts
@@ -0,0 +1,171 @@
+/**
+ * @fileoverview Per CLAUDE.md "File existence" rule: use `existsSync`
+ * from `node:fs`. Never `fs.access` / `fs.stat`-for-existence / async
+ * `fileExists` wrapper.
+ *
+ * Detects:
+ *   - `fs.access(...)` / `fs.accessSync(...)` / `fs.promises.access(...)`
+ *   - `fs.stat(...)` / `fs.statSync(...)` / `fs.promises.stat(...)`
+ *     when the result is being used in a boolean / try-catch context
+ *     (a strong signal of "is it there"). We can't perfectly detect
+ *     all existence-checks, but flagging every `access(...)` and
+ *     `statSync(...)` covers the common cases — false positives are
+ *     fixed by switching to existsSync, which is harmless.
+ *   - Custom wrappers: `fileExists(p)` / `pathExists(p)` / `isFile(p)` /
+ *     `isDir(p)`.
+ *
+ * Autofix scope:
+ *   - **Deterministic**: custom wrappers (`fileExists(p)` /
+ *     `pathExists(p)` / `isFile(p)` / `isDir(p)`) are rewritten to
+ *     `existsSync(p)` with `import { existsSync } from 'node:fs'`
+ *     injected. Same arity, same boolean semantics, drop-in safe.
+ *   - **AI-handled** (Step 4 of `pnpm run fix`): `fs.access` /
+ *     `fs.stat` rewrites. These flip control flow — `try { await
+ *     fs.access(p); … } catch { … }` becomes `if (existsSync(p))
+ *     { … } else { … }`, and `const s = await fs.stat(p)` with
+ *     metadata access (`s.size`, `s.isDirectory()`) needs to stay
+ *     a stat call. The right rewrite depends on the surrounding
+ *     code, but the pattern is mechanical enough for the AI step
+ *     to handle reliably with the canonical guidance in
+ *     scripts/ai-lint-fix.mts.
+ */
+
+import { appendImportFixes, summarizeImportTarget } from './_inject-import.mts'
+
+const ACCESS_METHODS = new Set(['access', 'accessSync'])
+const STAT_METHODS = new Set(['stat', 'statSync', 'lstat', 'lstatSync'])
+const WRAPPER_NAMES = new Set(['fileExists', 'pathExists', 'isFile', 'isDir'])
+
+const EXISTS_SYNC_IMPORT_LINE = "import { existsSync } from 'node:fs'"
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Prefer existsSync from node:fs over fs.access / fs.stat-for-existence / async fileExists wrapper.',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      access:
+        'fs.{{method}}() — use existsSync from node:fs for existence checks. fs.access throws on missing files (forces try/catch); existsSync returns boolean directly.',
+      stat: 'fs.{{method}}() — if you only need to know whether the path exists, use existsSync from node:fs. If you need the metadata (size, mtime), keep stat but state intent in a comment.',
+      fileExists:
+        'Custom `{{name}}` wrapper — use existsSync from node:fs directly.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    let summary
+
+    function ensureSummary() {
+      if (summary) {
+        return summary
+      }
+      summary = summarizeImportTarget(sourceCode.ast, 'node:fs', 'existsSync')
+      return summary
+    }
+
+    function calleeMethodName(callee) {
+      if (callee.type !== 'MemberExpression') {
+        return undefined
+      }
+      if (callee.property.type !== 'Identifier') {
+        return undefined
+      }
+      return callee.property.name
+    }
+
+    /**
+     * Wrappers are only fixable when:
+     *   - exactly 1 argument (matches existsSync arity)
+     *   - argument is not a SpreadElement
+     *
+     * The call is often wrapped in `await` — that's fine. Replacing
+     * `await fileExists(p)` with `existsSync(p)` (no await) is the
+     * intended rewrite; existsSync is sync and the surrounding `await`
+     * collapses to a no-op on a non-promise value.
+     */
+    function isFixableWrapperCall(node) {
+      if (node.arguments.length !== 1) {
+        return false
+      }
+      if (node.arguments[0].type === 'SpreadElement') {
+        return false
+      }
+      return true
+    }
+
+    return {
+      CallExpression(node) {
+        const method = calleeMethodName(node.callee)
+        if (!method) {
+          // Direct call: `await fileExists(p)` — flag known wrapper
+          // names and autofix to `existsSync(p)`.
+          if (
+            node.callee.type === 'Identifier' &&
+            WRAPPER_NAMES.has(node.callee.name)
+          ) {
+            const name = node.callee.name
+            if (!isFixableWrapperCall(node)) {
+              context.report({
+                node,
+                messageId: 'fileExists',
+                data: { name },
+              })
+              return
+            }
+
+            const s = ensureSummary()
+            const argText = sourceCode.getText(node.arguments[0])
+
+            context.report({
+              node,
+              messageId: 'fileExists',
+              data: { name },
+              fix(fixer) {
+                // Replace just the callee identifier — preserve
+                // arg text + parens. `await` (if present) becomes a
+                // no-op against a sync boolean return; safe to leave.
+                return [
+                  fixer.replaceText(node, `existsSync(${argText})`),
+                  ...appendImportFixes(
+                    s,
+                    fixer,
+                    EXISTS_SYNC_IMPORT_LINE,
+                    undefined,
+                  ),
+                ]
+              },
+            })
+          }
+          return
+        }
+
+        if (ACCESS_METHODS.has(method)) {
+          context.report({
+            node,
+            messageId: 'access',
+            data: { method },
+          })
+        } else if (STAT_METHODS.has(method)) {
+          context.report({
+            node,
+            messageId: 'stat',
+            data: { method },
+          })
+        }
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/prefer-function-declaration.mts b/.config/oxlint-plugin/rules/prefer-function-declaration.mts
new file mode 100644
index 0000000..7128053
--- /dev/null
+++ b/.config/oxlint-plugin/rules/prefer-function-declaration.mts
@@ -0,0 +1,273 @@
+/**
+ * @fileoverview Module-scope function definitions should use
+ * `function foo() {}` declarations, not `const foo = () => {}` or
+ * `const foo = function () {}` expressions. Function declarations
+ * hoist, sort cleanly under `sort-source-methods`, and render with
+ * a stable `foo.name` in stack traces — arrow expressions assigned
+ * to `const` lose all three properties (no hoisting, treated as
+ * statements by the sort rule, and `.name` is the variable name
+ * which is fragile across refactors).
+ *
+ * Style signal that motivated the rule: across the fleet's six
+ * surveyed repos, the ratio of `function` declarations to top-level
+ * arrow `const`s is overwhelming — socket-cli 962:5, socket-lib
+ * 842:13, socket-sdk-js 200:6. The arrow stragglers are drift.
+ *
+ * Autofix scope (deterministic only):
+ *   - `const foo = () => { ... }` (block body) →
+ *     `function foo() { ... }`
+ *   - `const foo = (a, b) => expr` (expression body) →
+ *     `function foo(a, b) { return expr }`
+ *   - `const foo = function (a, b) { ... }` →
+ *     `function foo(a, b) { ... }`
+ *   - `const foo = async () => { ... }` → `async function foo() {}`
+ *   - `export const foo = () => {}` →
+ *     `export function foo() {}` (preserves the export)
+ *
+ * Skips (report-only, no fix):
+ *   - Generator function expressions (`function*`) — autofix needs
+ *     to insert `*` after `function` without losing the name, and
+ *     the construct is rare enough that the human can do it.
+ *   - Destructured / non-Identifier declarators
+ *     (`const { foo } = ...`, `const [foo] = ...`).
+ *   - Multi-declarator `const foo = ..., bar = ...` — splitting
+ *     into declarations + function declarations is messy; the
+ *     reader should split it manually first.
+ *   - Declarations carrying a TS type annotation
+ *     (`const foo: Handler = () => {}`) — the annotation is the
+ *     contract and would need to migrate to a `satisfies` or be
+ *     dropped. Human call.
+ *   - Functions that reference `this` — declaration-form `function`
+ *     has its own `this`; arrows inherit. Static check: the
+ *     function body contains the `this` keyword anywhere.
+ *   - Functions inside non-Program scopes (loops, conditionals, etc.)
+ *     — only the top-level (Program body) shape is rewritten.
+ */
+
+const SKIP_TYPE_ANNOTATION = true
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Module-scope functions should use `function foo() {}` declarations instead of `const foo = () => ...` / `const foo = function () {}`.',
+      category: 'Stylistic Issues',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      preferFunctionDeclaration:
+        'Module-scope `{{name}}` is an arrow/function expression. Use `function {{name}}() {}` — hoists, sorts under `sort-source-methods`, and renders a stable name in stack traces.',
+      preferFunctionDeclarationNoFix:
+        'Module-scope `{{name}}` should be a `function` declaration, but autofix is unsafe here (generator / `this` reference / type-annotated declarator / multi-declarator binding). Rewrite manually.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    return {
+      VariableDeclaration(node) {
+        // Only top-level: Program body, or `export const ...` whose
+        // parent is the Program body.
+        const parent = node.parent
+        const isTopLevel =
+          (parent && parent.type === 'Program') ||
+          (parent &&
+            (parent.type === 'ExportNamedDeclaration' ||
+              parent.type === 'ExportDefaultDeclaration') &&
+            parent.parent &&
+            parent.parent.type === 'Program')
+        if (!isTopLevel) {
+          return
+        }
+        if (node.kind !== 'const') {
+          return
+        }
+        if (node.declarations.length !== 1) {
+          return
+        }
+
+        const decl = node.declarations[0]
+        if (!decl.id || decl.id.type !== 'Identifier') {
+          return
+        }
+        if (!decl.init) {
+          return
+        }
+        const init = decl.init
+        if (
+          init.type !== 'ArrowFunctionExpression' &&
+          init.type !== 'FunctionExpression'
+        ) {
+          return
+        }
+
+        const name = decl.id.name
+
+        // Skip generator function expressions — autofix below doesn't
+        // re-insert the `*`.
+        if (init.generator) {
+          context.report({
+            node: decl.id,
+            messageId: 'preferFunctionDeclarationNoFix',
+            data: { name },
+          })
+          return
+        }
+
+        // Skip declarators that carry a type annotation — the
+        // annotation needs migration.
+        if (SKIP_TYPE_ANNOTATION && decl.id.typeAnnotation) {
+          context.report({
+            node: decl.id,
+            messageId: 'preferFunctionDeclarationNoFix',
+            data: { name },
+          })
+          return
+        }
+
+        // Skip if the function body references `this` — declaration
+        // form has its own `this`, would change semantics.
+        if (init.type === 'ArrowFunctionExpression' && referencesThis(init)) {
+          context.report({
+            node: decl.id,
+            messageId: 'preferFunctionDeclarationNoFix',
+            data: { name },
+          })
+          return
+        }
+
+        context.report({
+          node: decl.id,
+          messageId: 'preferFunctionDeclaration',
+          data: { name },
+          fix(fixer) {
+            const asyncPrefix = init.async ? 'async ' : ''
+            const params = init.params
+              .map(p => sourceCode.getText(p))
+              .join(', ')
+            let body
+            if (init.body.type === 'BlockStatement') {
+              body = sourceCode.getText(init.body)
+            } else {
+              // Expression body — wrap in a block with `return`.
+              body = `{\n  return ${sourceCode.getText(init.body)}\n}`
+            }
+            const replacement = `${asyncPrefix}function ${name}(${params}) ${body}`
+            // Replace the whole VariableDeclaration node (which
+            // includes the trailing semicolon if any — the
+            // declaration form doesn't take one but oxfmt will
+            // normalize on the next pass).
+            return fixer.replaceText(node, replacement)
+          },
+        })
+      },
+    }
+  },
+}
+
+/**
+ * Walk the function body iteratively looking for a `ThisExpression`.
+ *
+ * We previously serialized the AST with JSON.stringify + regex on
+ * `\bthis\b`, but oxlint's AST nodes can carry back-references
+ * (parent, scope, type-arg back-pointers from the TS plugin) via
+ * getters that return fresh wrapper objects. A WeakSet de-cycle
+ * keyed on object identity misses those cases — the seen-check
+ * returns false and JSON.stringify hits the limit and throws
+ * "Converting circular structure to JSON," crashing the rule. The
+ * AST walk avoids serialization entirely: each visit checks the
+ * node's `type` and pushes child nodes onto a work queue. Identity-
+ * based seen-set still de-cycles for safety, this time without
+ * paying the cost of stringification.
+ */
+function referencesThis(node) {
+  if (!node.body) {
+    return false
+  }
+  const seen = new WeakSet()
+  // Inline child-list keys we know the ESTree shape uses. Skip
+  // `parent` and other navigational back-refs — anything that's not
+  // a structural child of the function body.
+  const STRUCTURAL_KEYS = [
+    'argument',
+    'arguments',
+    'body',
+    'callee',
+    'cases',
+    'consequent',
+    'declaration',
+    'declarations',
+    'discriminant',
+    'elements',
+    'expression',
+    'expressions',
+    'finalizer',
+    'handler',
+    'id',
+    'init',
+    'key',
+    'left',
+    'object',
+    'param',
+    'params',
+    'properties',
+    'property',
+    'quasi',
+    'quasis',
+    'right',
+    'specifiers',
+    'tag',
+    'test',
+    'update',
+    'value',
+  ]
+  const queue = [
+    node.body.type === 'BlockStatement' ? node.body.body : node.body,
+  ]
+  while (queue.length > 0) {
+    const item = queue.pop()
+    if (item === null || item === undefined) {
+      continue
+    }
+    if (Array.isArray(item)) {
+      for (let i = 0, { length } = item; i < length; i += 1) {
+        queue.push(item[i])
+      }
+      continue
+    }
+    if (typeof item !== 'object') {
+      continue
+    }
+    if (seen.has(item)) {
+      continue
+    }
+    seen.add(item)
+    if (item.type === 'ThisExpression') {
+      return true
+    }
+    // Don't recurse into nested function-like nodes — they bind
+    // their own `this`, so a `this` inside them doesn't count.
+    if (
+      item.type === 'FunctionExpression' ||
+      item.type === 'FunctionDeclaration'
+    ) {
+      continue
+    }
+    for (let i = 0, { length } = STRUCTURAL_KEYS; i < length; i += 1) {
+      const k = STRUCTURAL_KEYS[i]
+      if (k && item[k] !== undefined) {
+        queue.push(item[k])
+      }
+    }
+  }
+  return false
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/prefer-node-builtin-imports.mts b/.config/oxlint-plugin/rules/prefer-node-builtin-imports.mts
new file mode 100644
index 0000000..9417b8c
--- /dev/null
+++ b/.config/oxlint-plugin/rules/prefer-node-builtin-imports.mts
@@ -0,0 +1,401 @@
+/**
+ * @fileoverview Per CLAUDE.md "Imports" rule:
+ *
+ *   `node:fs` cherry-picks (`existsSync`, `promises as fs`); `path` /
+ *   `os` / `url` / `crypto` use default imports. Exception:
+ *   `fileURLToPath` from `node:url`.
+ *
+ * The fleet's Node-builtin import shape is asymmetric on purpose:
+ *
+ *   - `node:fs` is large; cherry-picking is the canonical idiom and
+ *     keeps the import line meaningful (you can read off which fs
+ *     APIs the module actually uses).
+ *   - `node:path`, `node:os`, `node:url`, `node:crypto` are small;
+ *     a default import (`import path from 'node:path'`) reads cleaner
+ *     than four named imports and matches the way most fleet code
+ *     references `path.join` / `path.resolve` / `path.dirname`.
+ *   - `fileURLToPath` is the documented exception — named import
+ *     from `node:url` is allowed because every caller uses just that
+ *     one symbol and `url.fileURLToPath(import.meta.url)` reads worse
+ *     than `fileURLToPath(import.meta.url)`.
+ *
+ * Detects:
+ *   - `import fs from 'node:fs'` / `import * as fs from 'node:fs'`
+ *     — recommends named imports.
+ *   - `import { join, resolve } from 'node:path'`
+ *     — recommends default import + dotted access (`path.join`,
+ *     `path.resolve`).
+ *   - Same for `node:os`, `node:url` (with `fileURLToPath` exception),
+ *     `node:crypto`.
+ *
+ * Autofix:
+ *   - `import { join } from 'node:path'` → `import path from 'node:path'`
+ *     AND every `join(...)` reference in the file is rewritten to
+ *     `path.join(...)`. Same shape for os/url/crypto. Skipped when
+ *     the file already has a default import for the module (would
+ *     double-import).
+ *   - `import fs from 'node:fs'` / `import * as fs from 'node:fs'` →
+ *     scans the file's references to the local binding (e.g. `fs`),
+ *     collects the set of accessed properties (`fs.existsSync`,
+ *     `fs.readFileSync`), and rewrites the import to a sorted
+ *     named-imports clause. Each `fs.X` reference is rewritten to
+ *     bare `X`. Skipped when:
+ *       a) any reference shape is "weird" (computed access `fs[expr]`,
+ *          spread `...fs`, passed as a value `fn(fs)`, reassignment).
+ *          Those need human eyes — the rewrite would lose semantics.
+ *       b) collected names collide with existing top-level bindings
+ *          in the file.
+ */
+
+const PREFER_DEFAULT = ['node:path', 'node:os', 'node:url', 'node:crypto']
+const DEFAULT_LOCAL = {
+  'node:path': 'path',
+  'node:os': 'os',
+  'node:url': 'url',
+  'node:crypto': 'crypto',
+}
+
+// `fileURLToPath` is the documented exception per CLAUDE.md.
+const NAMED_EXCEPTIONS = {
+  'node:url': new Set(['fileURLToPath']),
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Use cherry-pick named imports for node:fs and default imports for node:path / os / url / crypto. Per CLAUDE.md "Imports" rule.',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      fsDefault:
+        "`import fs from 'node:fs'` — use cherry-pick named imports (e.g. `import { existsSync } from 'node:fs'`). Per CLAUDE.md.",
+      fsNamespace:
+        "`import * as fs from 'node:fs'` — use cherry-pick named imports. Per CLAUDE.md.",
+      preferDefault:
+        "`import {{names}} from '{{specifier}}'` — use a default import and dotted access (`{{local}}.{{first}}`). Per CLAUDE.md.",
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    /**
+     * Look at the program body to determine whether `localName` is
+     * already in use (any binding form). If so, autofixing to a
+     * default import would shadow it.
+     */
+    function localBindingExists(programBody, localName) {
+      for (const stmt of programBody) {
+        if (stmt.type === 'ImportDeclaration') {
+          for (const spec of stmt.specifiers) {
+            if (
+              spec.local &&
+              spec.local.name === localName &&
+              // Only count it as a clash if the import comes from a
+              // *different* specifier — same-specifier same-local
+              // means we'd be re-defining the same import.
+              stmt.source.value !== ''
+            ) {
+              return true
+            }
+          }
+          continue
+        }
+        if (stmt.type === 'VariableDeclaration') {
+          for (const decl of stmt.declarations) {
+            if (
+              decl.id &&
+              decl.id.type === 'Identifier' &&
+              decl.id.name === localName
+            ) {
+              return true
+            }
+          }
+        }
+      }
+      return false
+    }
+
+    return {
+      ImportDeclaration(node) {
+        const specifier = node.source.value
+        if (typeof specifier !== 'string') {
+          return
+        }
+
+        // Type-only imports have zero runtime impact — they exist purely
+        // for the type checker (e.g. `import type * as NodeFs from
+        // 'node:fs'` used in `vi.importActual<typeof NodeFs>('node:fs')`
+        // type arguments). The fleet's value-import shape rules don't
+        // apply to them: a type namespace import doesn't carry the
+        // "loaded the whole module" semantics of a value namespace
+        // import. Skip.
+        if (node.importKind === 'type') {
+          return
+        }
+
+        // node:fs — should be named-imports.
+        if (specifier === 'node:fs') {
+          let bannedSpec
+          let messageId
+          for (const spec of node.specifiers) {
+            if (spec.type === 'ImportDefaultSpecifier') {
+              bannedSpec = spec
+              messageId = 'fsDefault'
+              break
+            }
+            if (spec.type === 'ImportNamespaceSpecifier') {
+              bannedSpec = spec
+              messageId = 'fsNamespace'
+              break
+            }
+          }
+          if (!bannedSpec) {
+            return
+          }
+
+          const fsLocalName = bannedSpec.local.name
+
+          // Walk the scope graph to collect every reference to the
+          // local binding. If any reference is "weird" (not a plain
+          // member expression on the read side), bail on the autofix
+          // and report only — the rewrite isn't safe.
+          const scope = context.getScope ? context.getScope() : undefined
+          if (!scope) {
+            context.report({ node, messageId })
+            return
+          }
+
+          const accessed = new Set()
+          const memberRefs = []
+          let unsafe = false
+
+          function visit(s, visited) {
+            if (visited.has(s)) {
+              return
+            }
+            visited.add(s)
+            for (const ref of s.references) {
+              if (ref.identifier.name !== fsLocalName) {
+                continue
+              }
+              // Skip the import-binding declaration itself.
+              if (
+                ref.identifier.range[0] >= node.range[0] &&
+                ref.identifier.range[1] <= node.range[1]
+              ) {
+                continue
+              }
+              const refParent = ref.identifier.parent
+              if (
+                !refParent ||
+                refParent.type !== 'MemberExpression' ||
+                refParent.object !== ref.identifier ||
+                refParent.computed ||
+                refParent.property.type !== 'Identifier'
+              ) {
+                // Weird usage shape — bail.
+                unsafe = true
+                return
+              }
+              accessed.add(refParent.property.name)
+              memberRefs.push(refParent)
+            }
+            for (const child of s.childScopes) {
+              if (unsafe) {
+                return
+              }
+              visit(child, visited)
+            }
+          }
+
+          visit(scope, new Set())
+
+          if (unsafe || accessed.size === 0) {
+            // No usable references (or shadowed/aliased usage) — drop
+            // back to report-only.
+            context.report({ node, messageId })
+            return
+          }
+
+          // Skip autofix if any accessed name collides with an
+          // existing top-level binding (would shadow on rewrite).
+          const programBody = sourceCode.ast.body
+          for (const name of accessed) {
+            if (localBindingExists(programBody, name)) {
+              context.report({ node, messageId })
+              return
+            }
+          }
+
+          const sorted = [...accessed].sort()
+          const newImport = `import { ${sorted.join(', ')} } from 'node:fs'`
+
+          context.report({
+            node,
+            messageId,
+            fix(fixer) {
+              const fixes = [fixer.replaceText(node, newImport)]
+              for (const ref of memberRefs) {
+                // Replace `fs.X` with bare `X`. We need the entire
+                // member expression, not just the object.
+                fixes.push(fixer.replaceText(ref, ref.property.name))
+              }
+              return fixes
+            },
+          })
+          return
+        }
+
+        // node:path / os / url / crypto — should be default-import.
+        if (!PREFER_DEFAULT.includes(specifier)) {
+          return
+        }
+
+        // If there's already a default import on this statement,
+        // accept the rest of the named imports as-is — multi-form
+        // mix-ins (`import path, { sep } from 'node:path'`) are
+        // unusual but tolerated.
+        const hasDefault = node.specifiers.some(
+          s => s.type === 'ImportDefaultSpecifier',
+        )
+        if (hasDefault) {
+          return
+        }
+
+        const named = node.specifiers.filter(s => s.type === 'ImportSpecifier')
+        if (named.length === 0) {
+          return
+        }
+
+        // Allow documented exceptions (e.g. `fileURLToPath`).
+        const exceptions = NAMED_EXCEPTIONS[specifier]
+        const violatingNames = exceptions
+          ? named.filter(
+              s =>
+                s.imported &&
+                s.imported.name &&
+                !exceptions.has(s.imported.name),
+            )
+          : named
+        if (violatingNames.length === 0) {
+          return
+        }
+
+        const local = DEFAULT_LOCAL[specifier]
+        const violatingNameList = violatingNames
+          .map(s => s.imported.name)
+          .join(', ')
+
+        // Skip autofix if the local binding (`path`, `os`, etc.)
+        // already exists in the file under another name.
+        const programBody = sourceCode.ast.body
+        if (localBindingExists(programBody, local)) {
+          context.report({
+            node,
+            messageId: 'preferDefault',
+            data: {
+              names: `{ ${violatingNameList} }`,
+              specifier,
+              local,
+              first: violatingNames[0].imported.name,
+            },
+          })
+          return
+        }
+
+        context.report({
+          node,
+          messageId: 'preferDefault',
+          data: {
+            names: `{ ${violatingNameList} }`,
+            specifier,
+            local,
+            first: violatingNames[0].imported.name,
+          },
+          fix(fixer) {
+            const fixes = []
+
+            // Rewrite the import statement.
+            const keptNamed = exceptions
+              ? named.filter(
+                  s =>
+                    s.imported &&
+                    s.imported.name &&
+                    exceptions.has(s.imported.name),
+                )
+              : []
+
+            let newImport
+            if (keptNamed.length > 0) {
+              const keptText = keptNamed
+                .map(s => sourceCode.getText(s))
+                .join(', ')
+              newImport = `import ${local}, { ${keptText} } from '${specifier}'`
+            } else {
+              newImport = `import ${local} from '${specifier}'`
+            }
+            fixes.push(fixer.replaceText(node, newImport))
+
+            // Rewrite every reference in the file: each violating
+            // named import becomes `<local>.<name>`.
+            //
+            // Walk the source text and look for word-boundary matches
+            // of each violating name. Skip occurrences inside
+            // strings/comments to avoid breaking unrelated text.
+            //
+            // Cheap heuristic: use scope analysis if available.
+            const scope = context.getScope ? context.getScope() : undefined
+            const targetNames = new Set(violatingNames.map(s => s.local.name))
+
+            if (scope) {
+              const visited = new Set()
+
+              function visitScope(s) {
+                if (visited.has(s)) {
+                  return
+                }
+                visited.add(s)
+                for (const ref of s.references) {
+                  if (!targetNames.has(ref.identifier.name)) {
+                    continue
+                  }
+                  // Skip the import-declaration's own binding.
+                  if (
+                    ref.identifier.range[0] >= node.range[0] &&
+                    ref.identifier.range[1] <= node.range[1]
+                  ) {
+                    continue
+                  }
+                  fixes.push(
+                    fixer.replaceText(
+                      ref.identifier,
+                      `${local}.${ref.identifier.name}`,
+                    ),
+                  )
+                }
+                for (const child of s.childScopes) {
+                  visitScope(child)
+                }
+              }
+
+              visitScope(scope)
+            }
+
+            return fixes
+          },
+        })
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/prefer-safe-delete.mts b/.config/oxlint-plugin/rules/prefer-safe-delete.mts
new file mode 100644
index 0000000..755bb51
--- /dev/null
+++ b/.config/oxlint-plugin/rules/prefer-safe-delete.mts
@@ -0,0 +1,199 @@
+/**
+ * @fileoverview Per CLAUDE.md "File deletion" rule: route every delete
+ * through `safeDelete()` / `safeDeleteSync()` from
+ * `@socketsecurity/lib/fs`. Never `fs.rm` / `fs.unlink` / `fs.rmdir` /
+ * `rm -rf` directly — even for one known file.
+ *
+ * Detects:
+ *   - `fs.rm(...)` / `fs.rmSync(...)` / `fs.promises.rm(...)`
+ *   - `fs.unlink(...)` / `fs.unlinkSync(...)`
+ *   - `fs.rmdir(...)` / `fs.rmdirSync(...)`
+ *
+ * Autofix: rewrites the call to `safeDelete(path)` / `safeDeleteSync(path)`
+ * AND injects `import { safeDelete } from '@socketsecurity/lib/fs'`
+ * (or `safeDeleteSync`) when missing.
+ *
+ * The autofix is conservative — it only fires when the call shape is
+ * "obviously equivalent" to safeDelete:
+ *
+ *   - The first argument is a single expression (the path).
+ *   - Any second argument is an options object literal (we drop it;
+ *     safeDelete handles recursive/force internally).
+ *   - No third argument (rules out fs.rm with an explicit callback).
+ *   - Not a node-callback-style usage (no trailing function expression).
+ *
+ * Skipped (reported without fix):
+ *   - `fs.rm(p, opts, cb)` — node-callback style; semantics differ.
+ *   - Calls whose result is checked/assigned in a way that depends on
+ *     fs.rm's specific throw-on-missing or callback contract.
+ *
+ * Spawn-based bans (`rm -rf`, `Remove-Item`) live in a separate hook
+ * (`.claude/hooks/path-guard/`) — this rule covers the JavaScript side.
+ */
+
+import { appendImportFixes, summarizeImportTarget } from './_inject-import.mts'
+
+const DELETE_METHODS = new Set([
+  'rm',
+  'rmSync',
+  'unlink',
+  'unlinkSync',
+  'rmdir',
+  'rmdirSync',
+])
+
+const SYNC_METHODS = new Set(['rmSync', 'unlinkSync', 'rmdirSync'])
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Route every delete through safeDelete / safeDeleteSync from @socketsecurity/lib/fs.',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      banned:
+        'fs.{{method}}() — use safeDelete / safeDeleteSync from @socketsecurity/lib/fs. The lib wrapper handles ENOENT, retries on EBUSY, and integrates with the rest of the fleet.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    // One summary per replacement target — async (safeDelete) and
+    // sync (safeDeleteSync) are separate import names from the same
+    // specifier, so each gets its own summary cache.
+    const summaryCache = new Map()
+
+    function ensureSummary(importName) {
+      let s = summaryCache.get(importName)
+      if (s) {
+        return s
+      }
+      s = summarizeImportTarget(
+        sourceCode.ast,
+        '@socketsecurity/lib/fs',
+        importName,
+      )
+      summaryCache.set(importName, s)
+      return s
+    }
+
+    /**
+     * The autofix only fires when the call shape is unambiguous:
+     *   fs.rm(path)
+     *   fs.rm(path, { ...opts })
+     *   fs.rmSync(path)
+     *   fs.rmSync(path, { ...opts })
+     *
+     * Bail on:
+     *   - 0 args (malformed; skip)
+     *   - 3+ args (callback-style fs.rm — semantics differ)
+     *   - 2nd arg is a function expression (callback-style)
+     *   - any spread argument (...args; can't reason about arity)
+     */
+    function isFixable(node) {
+      const args = node.arguments
+      if (args.length === 0 || args.length > 2) {
+        return false
+      }
+      for (const a of args) {
+        if (a.type === 'SpreadElement') {
+          return false
+        }
+      }
+      if (args.length === 2) {
+        const second = args[1]
+        if (
+          second.type === 'FunctionExpression' ||
+          second.type === 'ArrowFunctionExpression'
+        ) {
+          return false
+        }
+      }
+      return true
+    }
+
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+        if (callee.type !== 'MemberExpression') {
+          return
+        }
+        if (callee.property.type !== 'Identifier') {
+          return
+        }
+        if (!DELETE_METHODS.has(callee.property.name)) {
+          return
+        }
+
+        // Heuristic: callee.object should be a node that plausibly
+        // refers to the fs module (named `fs`, `promises`, etc.).
+        // Cover both `fs.rm`, `fs.promises.rm`, `promises.rm`,
+        // `fsPromises.rm`. Skip method calls on instances (e.g.
+        // `child.rm()` — not fs).
+        const obj = callee.object
+        const objName =
+          obj.type === 'Identifier'
+            ? obj.name
+            : obj.type === 'MemberExpression' &&
+                obj.property.type === 'Identifier'
+              ? obj.property.name
+              : undefined
+
+        if (!objName) {
+          return
+        }
+
+        // Match common fs aliases. Conservative — we'd rather miss a
+        // case than flag `someChild.unlink()` on an unrelated object.
+        if (!/^(fs|fsPromises|promises|fsp)$/.test(objName)) {
+          return
+        }
+
+        const method = callee.property.name
+        const isSync = SYNC_METHODS.has(method)
+        const replacement = isSync ? 'safeDeleteSync' : 'safeDelete'
+
+        if (!isFixable(node)) {
+          context.report({
+            node,
+            messageId: 'banned',
+            data: { method },
+          })
+          return
+        }
+
+        const s = ensureSummary(replacement)
+        const pathArg = node.arguments[0]
+        const pathText = sourceCode.getText(pathArg)
+
+        context.report({
+          node,
+          messageId: 'banned',
+          data: { method },
+          fix(fixer) {
+            return [
+              fixer.replaceText(node, `${replacement}(${pathText})`),
+              ...appendImportFixes(
+                s,
+                fixer,
+                `import { ${replacement} } from '@socketsecurity/lib/fs'`,
+                undefined,
+              ),
+            ]
+          },
+        })
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/prefer-separate-type-import.mts b/.config/oxlint-plugin/rules/prefer-separate-type-import.mts
new file mode 100644
index 0000000..bcacfd3
--- /dev/null
+++ b/.config/oxlint-plugin/rules/prefer-separate-type-import.mts
@@ -0,0 +1,184 @@
+/**
+ * @fileoverview Forbid inline type specifiers (`import { type X, Y }`)
+ * — split into a dedicated `import type { X }` plus a value-only
+ * `import { Y }`. Two style benefits:
+ *
+ *   1. The reader sees the type-vs-value split at the import header
+ *      without parsing per-specifier `type` keywords.
+ *   2. Sorted-imports rules can group `import type` statements
+ *      separately from value imports (fleet convention is value
+ *      imports first, then types as a trailing block).
+ *
+ * Style signal that motivated the rule: across the fleet's six
+ * surveyed repos, separate `import type` statements outnumber inline
+ * `type` specifiers ~200-to-1 (socket-cli: 535 separate vs 2 inline;
+ * socket-lib: 212 vs 8). The stragglers are drift, not a different
+ * convention.
+ *
+ * Autofix:
+ *   - Inline `type` specifiers in a `import { ... } from 'mod'`
+ *     statement are moved into a new `import type { ... } from 'mod'`
+ *     statement inserted directly after the original import. The
+ *     `type` keyword is stripped from the inline specifier.
+ *   - If ALL specifiers in an import are `type`-prefixed, the whole
+ *     statement is converted in place to `import type { ... }`.
+ *   - Default + type-specifier mixes
+ *     (`import Foo, { type Bar } from 'mod'`) are split: default
+ *     keeps the original statement, types move to a new
+ *     `import type { Bar } from 'mod'` line.
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Prefer a separate `import type { X }` over inline `import { type X, Y }`.',
+      category: 'Stylistic Issues',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      preferSeparateTypeImport:
+        'Inline `type` specifier on `{{name}}` — move type-only specifiers into a separate `import type { ... } from "{{source}}"` statement.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    return {
+      ImportDeclaration(node) {
+        // `import type { ... }` at the statement level — already
+        // correct, no inline specifiers to surface.
+        if (node.importKind === 'type') {
+          return
+        }
+        if (!node.specifiers || node.specifiers.length === 0) {
+          return
+        }
+
+        const typeSpecifiers = []
+        const valueSpecifiers = []
+        let defaultSpec
+        let namespaceSpec
+        for (const spec of node.specifiers) {
+          if (spec.type === 'ImportDefaultSpecifier') {
+            defaultSpec = spec
+            continue
+          }
+          if (spec.type === 'ImportNamespaceSpecifier') {
+            namespaceSpec = spec
+            continue
+          }
+          if (spec.type === 'ImportSpecifier') {
+            if (spec.importKind === 'type') {
+              typeSpecifiers.push(spec)
+            } else {
+              valueSpecifiers.push(spec)
+            }
+          }
+        }
+
+        if (typeSpecifiers.length === 0) {
+          return
+        }
+
+        // Report each inline type specifier so the user sees every
+        // offender. Attach the autofix to the first one only — ESLint
+        // dedupes overlapping fixes and the rewrite replaces the
+        // whole statement (plus possibly inserts a new one).
+        const source = node.source.value
+        const indent = (() => {
+          const text = sourceCode.text
+          const lineStart = text.lastIndexOf('\n', node.range[0] - 1) + 1
+          return text.slice(lineStart, node.range[0])
+        })()
+
+        const typeNames = typeSpecifiers
+          .map(s => specifierText(sourceCode, s, true))
+          .join(', ')
+
+        let fixerAttached = false
+        for (const spec of typeSpecifiers) {
+          const name =
+            spec.imported && spec.imported.name
+              ? spec.imported.name
+              : '<unknown>'
+          const report = {
+            node: spec,
+            messageId: 'preferSeparateTypeImport',
+            data: { name, source: String(source) },
+          }
+          if (!fixerAttached) {
+            report.fix = function (fixer) {
+              // Case A: every specifier is a type specifier and there's
+              // no default/namespace import — convert the whole line.
+              if (
+                valueSpecifiers.length === 0 &&
+                !defaultSpec &&
+                !namespaceSpec
+              ) {
+                const originalText = sourceCode.getText(node)
+                const rewritten = originalText
+                  .replace(/^import\s+/, 'import type ')
+                  // Strip every inline `type ` keyword from inside
+                  // the brace list.
+                  .replace(/\btype\s+/g, '')
+                return fixer.replaceText(node, rewritten)
+              }
+              // Case B: mixed — keep value/default/namespace
+              // specifiers on the original line, append a new
+              // `import type { ... } from 'src'` below.
+              const remainingParts = []
+              if (defaultSpec) {
+                remainingParts.push(sourceCode.getText(defaultSpec))
+              }
+              if (namespaceSpec) {
+                remainingParts.push(sourceCode.getText(namespaceSpec))
+              }
+              if (valueSpecifiers.length > 0) {
+                const valueText = valueSpecifiers
+                  .map(s => specifierText(sourceCode, s, false))
+                  .join(', ')
+                remainingParts.push(`{ ${valueText} }`)
+              }
+              const quote = sourceCode.text[node.source.range[0]]
+              const rewrittenOriginal = `import ${remainingParts.join(', ')} from ${quote}${source}${quote}`
+              const newLine = `${indent}import type { ${typeNames} } from ${quote}${source}${quote}`
+              return fixer.replaceText(node, `${rewrittenOriginal}\n${newLine}`)
+            }
+            fixerAttached = true
+          }
+          context.report(report)
+        }
+      },
+    }
+  },
+}
+
+/**
+ * Render an `ImportSpecifier` for the rewritten statement. When
+ * `stripType` is true the `type` keyword is omitted (the specifier
+ * is being moved into a statement-level `import type` block, where
+ * per-specifier `type` would be redundant).
+ */
+function specifierText(sourceCode, spec, stripType) {
+  const imported = spec.imported
+  const local = spec.local
+  const importedName =
+    imported.type === 'Identifier' ? imported.name : `"${imported.value}"`
+  const localName = local.name
+  const renamed = importedName !== localName
+  const body = renamed ? `${importedName} as ${localName}` : importedName
+  if (!stripType && spec.importKind === 'type') {
+    return `type ${body}`
+  }
+  return body
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/prefer-undefined-over-null.mts b/.config/oxlint-plugin/rules/prefer-undefined-over-null.mts
new file mode 100644
index 0000000..3ba4a98
--- /dev/null
+++ b/.config/oxlint-plugin/rules/prefer-undefined-over-null.mts
@@ -0,0 +1,403 @@
+/**
+ * @fileoverview Per CLAUDE.md "null vs undefined": use `undefined`.
+ * `null` is allowed only for `__proto__: null` (object-literal
+ * prototype null) or external API requirements (e.g., JSON encoding,
+ * `Object.create(null)`, listener-error sinks, third-party callbacks).
+ *
+ * Autofix scope:
+ *   - **Deterministic**: rewrites `null` → `undefined` ONLY when
+ *     context is demonstrably safe. Earlier versions had a
+ *     context-blind autofix that produced fleet-wide regressions;
+ *     the current set of skip predicates covers every regression
+ *     seen in the rollout:
+ *       - `__proto__: null` (with or without `as` cast) — the
+ *         null-prototype-object contract.
+ *       - `Object.create(null)`, `Object.setPrototypeOf(o, null)`,
+ *         `Reflect.setPrototypeOf(o, null)` — prototype-aware
+ *         callsites that throw / reject `undefined`.
+ *       - `JSON.stringify(value, null, space)` — replacer-slot
+ *         convention.
+ *       - `=== null` / `!== null` comparisons — semantically distinct.
+ *   - **AI-handled** (Step 4 of `pnpm run fix`): literals whose
+ *     surrounding type annotation mentions `null`
+ *     (e.g. `let x: string | null = null`). The annotation is the
+ *     contract; flipping just the value creates type errors. The
+ *     AI step flips BOTH the value and the annotation in lockstep
+ *     and traces through the function signatures / interfaces /
+ *     return types that depend on it — exactly the refactor that
+ *     blew up socket-stuie when the deterministic autofix was
+ *     context-blind.
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Prefer `undefined` over `null` (CLAUDE.md style — `null` is allowed only for __proto__:null or external API requirements).',
+      category: 'Stylistic Issues',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      preferUndefined:
+        'Use `undefined` instead of `null` (allowed exceptions: `__proto__: null`, `Object.create(null)`, external API requirements like JSON.stringify replacer / third-party callbacks).',
+      preferUndefinedNoFix:
+        'Use `undefined` instead of `null`. Surrounding type annotation mentions `null` — both the annotation (`| null` → `| undefined`) and the value need to flip together. Handed off to the AI-fix step (Step 4 of `pnpm run fix`) to trace the refactor through the function signatures / interfaces / return types involved.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    /**
+     * Walk up through TS type-cast wrappers (`x as T`, `x as const`,
+     * `<T>x`) so that `null as never` inside `{ __proto__: null as never }`
+     * still matches the proto-null exception. Without this, the autofix
+     * rewrites `null as never` → `undefined as never`, which silently
+     * breaks the null-prototype object semantics — `Object.create(null)`
+     * vs `Object.create(undefined)` are very different.
+     */
+    function unwrapTsCast(node) {
+      let cur = node.parent
+      while (
+        cur &&
+        (cur.type === 'TSAsExpression' || cur.type === 'TSTypeAssertion')
+      ) {
+        cur = cur.parent
+      }
+      return cur
+    }
+
+    function isProtoNull(node) {
+      // Find the nearest non-cast ancestor; for `null as never` this
+      // skips the TSAsExpression and lands on the Property.
+      const parent = unwrapTsCast(node)
+      if (!parent || parent.type !== 'Property') {
+        return false
+      }
+      // Walk back down: parent.value may be the TSAsExpression or the
+      // Literal directly. Either is fine — we matched on the parent.
+      const key = parent.key
+      if (!key) {
+        return false
+      }
+      // { __proto__: null } — key is Identifier `__proto__` or string '__proto__'.
+      if (key.type === 'Identifier' && key.name === '__proto__') {
+        return true
+      }
+      if (key.type === 'Literal' && key.value === '__proto__') {
+        return true
+      }
+      return false
+    }
+
+    function isComparisonOperand(node) {
+      const parent = node.parent
+      if (!parent) {
+        return false
+      }
+      if (parent.type !== 'BinaryExpression') {
+        return false
+      }
+      return ['===', '!==', '==', '!='].includes(parent.operator)
+    }
+
+    /**
+     * `expect(x).toBe(null)` / `.toEqual(null)` / `.toStrictEqual(null)` /
+     * `.toMatchObject(null)` — vitest/jest assertion matchers where the
+     * `null` is the SEMANTIC value being asserted. Rewriting to
+     * `undefined` flips the test contract (a passing test that asserted
+     * "x is null" now asserts "x is undefined").
+     *
+     * Also covers chai (`.equal(null)` / `.equals(null)` / `.is(null)` /
+     * `.same(null)`) and node:assert (`assert.equal(_, null)` /
+     * `.deepEqual(_, null)` / `.deepStrictEqual(_, null)` /
+     * `.strictEqual(_, null)`).
+     *
+     * The detection is shape-based, not name-import-based — any call
+     * that ends in `.<assert-method>(null, ...)` qualifies. False
+     * positives (a non-test method named `toBe`) are extremely rare;
+     * the cost is missing a real autofix opportunity, which is a safe
+     * outcome.
+     */
+    const ASSERT_METHODS = new Set([
+      'deepEqual',
+      'deepStrictEqual',
+      'equal',
+      'equals',
+      'is',
+      'notDeepEqual',
+      'notDeepStrictEqual',
+      'notEqual',
+      'notStrictEqual',
+      'same',
+      'strictEqual',
+      'toBe',
+      'toEqual',
+      'toMatchObject',
+      'toStrictEqual',
+    ])
+
+    function isAssertionLibraryArg(node) {
+      const parent = unwrapTsCast(node)
+      if (!parent || parent.type !== 'CallExpression') {
+        return false
+      }
+      const callee = parent.callee
+      if (
+        callee.type !== 'MemberExpression' ||
+        callee.property.type !== 'Identifier'
+      ) {
+        return false
+      }
+      return ASSERT_METHODS.has(callee.property.name)
+    }
+
+    /**
+     * `const x: Foo | null = null` / `let y: Foo | null | undefined = null`
+     * — the developer explicitly opted into null in the variable's
+     * type signature. The dedicated annotation IS the contract;
+     * flipping the value alone leaves the contract intact but
+     * produces dead `undefined` writes against a `| null` slot.
+     *
+     * Faster than the generic `hasNullTypeAnnotation` walk-up
+     * because it short-circuits at the immediate VariableDeclarator
+     * parent. Both predicates are kept — this fast-path covers the
+     * canonical declarator shape; the walk-up handles the broader
+     * Property / Parameter / return-type / TS-cast cases that
+     * declarator-only detection misses.
+     *
+     * Textual scan over `<id>: <annot> = ` rather than AST navigation:
+     * the typeAnnotation field shape varies between oxlint AST and
+     * babel/typescript-eslint AST, so the regex is the most resilient
+     * detector across plugin host versions.
+     */
+    function isNullableTypeInitializer(node) {
+      const parent = node.parent
+      if (!parent || parent.type !== 'VariableDeclarator') {
+        return false
+      }
+      if (parent.init !== node) {
+        return false
+      }
+      const declStart = parent.range
+        ? parent.range[0]
+        : (parent.start ?? parent.id?.range?.[0])
+      const litStart = node.range ? node.range[0] : node.start
+      if (typeof declStart !== 'number' || typeof litStart !== 'number') {
+        return false
+      }
+      const sourceCode = context.getSourceCode
+        ? context.getSourceCode()
+        : context.sourceCode
+      const text = sourceCode.getText().slice(declStart, litStart)
+      // Require `: <typeexpr>... null ... =` — colon (type annotation),
+      // literal `null` token, then `=` (initializer separator).
+      return /:[^=]*\bnull\b[^=]*=/.test(text)
+    }
+
+    function isJsonStringifyReplacer(node) {
+      // JSON.stringify(value, replacer, space) — `replacer` is conventionally null.
+      const parent = unwrapTsCast(node)
+      if (
+        !parent ||
+        parent.type !== 'CallExpression' ||
+        parent.arguments[1] !== node
+      ) {
+        return false
+      }
+      const callee = parent.callee
+      if (callee.type !== 'MemberExpression') {
+        return false
+      }
+      return (
+        callee.object.type === 'Identifier' &&
+        callee.object.name === 'JSON' &&
+        callee.property.type === 'Identifier' &&
+        callee.property.name === 'stringify'
+      )
+    }
+
+    /**
+     * Prototype-aware callsites where `null` is the explicit "no
+     * prototype" sentinel. Replacing any of these with `undefined`
+     * either throws TypeError or silently changes semantics:
+     *
+     *   - `Object.create(null)` — first arg, throws if undefined.
+     *   - `Object.setPrototypeOf(o, null)` — second arg, semantics
+     *     differ (undefined is rejected by the spec).
+     *   - `Reflect.setPrototypeOf(o, null)` — same as above.
+     *
+     * Each entry is `[object, method, argIndex]` where argIndex is the
+     * 0-indexed slot whose `null` is allowed.
+     */
+    const PROTOTYPE_NULL_CALLSITES = [
+      ['Object', 'create', 0],
+      ['Object', 'setPrototypeOf', 1],
+      ['Reflect', 'setPrototypeOf', 1],
+    ]
+
+    function isPrototypeAwareNull(node) {
+      const parent = unwrapTsCast(node)
+      if (!parent || parent.type !== 'CallExpression') {
+        return false
+      }
+      const callee = parent.callee
+      if (callee.type !== 'MemberExpression') {
+        return false
+      }
+      if (
+        callee.object.type !== 'Identifier' ||
+        callee.property.type !== 'Identifier'
+      ) {
+        return false
+      }
+      const objectName = callee.object.name
+      const methodName = callee.property.name
+      for (const [obj, method, argIndex] of PROTOTYPE_NULL_CALLSITES) {
+        if (
+          obj === objectName &&
+          method === methodName &&
+          parent.arguments[argIndex] === node
+        ) {
+          return true
+        }
+      }
+      return false
+    }
+
+    /**
+     * Walk up the AST and return true if any ancestor carries a TS type
+     * annotation that mentions `null`. Used to skip autofix on cases
+     * like `let x: string | null = null` where flipping just the value
+     * creates a type error. Walks until a function / block / program
+     * boundary so we don't pick up unrelated type annotations elsewhere
+     * in the file.
+     *
+     * Cheap shortcut: stringify the typeAnnotation subtree and look for
+     * a 'null' token. Avoids a full type-system traversal.
+     */
+    function hasNullTypeAnnotation(node) {
+      const sourceCode = context.getSourceCode
+        ? context.getSourceCode()
+        : context.sourceCode
+
+      let cur = node.parent
+      while (cur) {
+        // Boundary nodes — stop walking here.
+        if (
+          cur.type === 'FunctionDeclaration' ||
+          cur.type === 'FunctionExpression' ||
+          cur.type === 'ArrowFunctionExpression' ||
+          cur.type === 'BlockStatement' ||
+          cur.type === 'Program'
+        ) {
+          // For functions, the return-type annotation lives on the
+          // function node itself. Check it before stopping.
+          if (cur.returnType) {
+            const text = sourceCode.getText(cur.returnType)
+            if (/\bnull\b/.test(text)) {
+              return true
+            }
+          }
+          return false
+        }
+        // Variable declarations: `let x: T = ...` puts the annotation on
+        // the VariableDeclarator's `id.typeAnnotation`.
+        if (
+          cur.type === 'VariableDeclarator' &&
+          cur.id &&
+          cur.id.typeAnnotation
+        ) {
+          const text = sourceCode.getText(cur.id.typeAnnotation)
+          if (/\bnull\b/.test(text)) {
+            return true
+          }
+        }
+        // Property: `foo: T` or `foo?: T` — check the property's
+        // typeAnnotation (in TS interfaces / type literals) or the
+        // value's wrapper for object literals.
+        if (cur.type === 'Property' && cur.typeAnnotation) {
+          const text = sourceCode.getText(cur.typeAnnotation)
+          if (/\bnull\b/.test(text)) {
+            return true
+          }
+        }
+        // Function parameters: `(x: T = null) => ...`. The default value
+        // is an AssignmentPattern; the annotated parameter is the left.
+        if (
+          cur.type === 'AssignmentPattern' &&
+          cur.left &&
+          cur.left.typeAnnotation
+        ) {
+          const text = sourceCode.getText(cur.left.typeAnnotation)
+          if (/\bnull\b/.test(text)) {
+            return true
+          }
+        }
+        // TS-specific: TSAsExpression / TSTypeAssertion carrying a `null`-
+        // bearing type — skip autofix even though the cast itself isn't
+        // the proto-null shape.
+        if (
+          (cur.type === 'TSAsExpression' || cur.type === 'TSTypeAssertion') &&
+          cur.typeAnnotation
+        ) {
+          const text = sourceCode.getText(cur.typeAnnotation)
+          if (/\bnull\b/.test(text)) {
+            return true
+          }
+        }
+        cur = cur.parent
+      }
+      return false
+    }
+
+    return {
+      Literal(node) {
+        if (node.value !== null || node.raw !== 'null') {
+          return
+        }
+
+        if (isProtoNull(node)) {
+          return
+        }
+        if (isComparisonOperand(node)) {
+          return
+        }
+        if (isPrototypeAwareNull(node)) {
+          return
+        }
+        if (isJsonStringifyReplacer(node)) {
+          return
+        }
+        if (isAssertionLibraryArg(node)) {
+          return
+        }
+        if (isNullableTypeInitializer(node)) {
+          return
+        }
+
+        if (hasNullTypeAnnotation(node)) {
+          // Surrounding type annotation mentions null — report without
+          // autofix so the human flips both annotation and value.
+          context.report({
+            node,
+            messageId: 'preferUndefinedNoFix',
+          })
+          return
+        }
+
+        context.report({
+          node,
+          messageId: 'preferUndefined',
+          fix(fixer) {
+            return fixer.replaceText(node, 'undefined')
+          },
+        })
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/socket-api-token-env.mts b/.config/oxlint-plugin/rules/socket-api-token-env.mts
new file mode 100644
index 0000000..ac77d8c
--- /dev/null
+++ b/.config/oxlint-plugin/rules/socket-api-token-env.mts
@@ -0,0 +1,146 @@
+/**
+ * @fileoverview Per CLAUDE.md "Token hygiene → Socket API token env
+ * var" rule:
+ *
+ *   The canonical fleet name is `SOCKET_API_TOKEN`. The legacy names
+ *   `SOCKET_API_KEY`, `SOCKET_SECURITY_API_TOKEN`, and
+ *   `SOCKET_SECURITY_API_KEY` are accepted as aliases for one cycle
+ *   (deprecation grace period) — bootstrap hooks read all four and
+ *   normalize to `SOCKET_API_TOKEN` going forward.
+ *
+ * Detects string literals naming any of the legacy aliases:
+ *   - SOCKET_API_KEY
+ *   - SOCKET_SECURITY_API_TOKEN
+ *   - SOCKET_SECURITY_API_KEY
+ *
+ * Autofix: rewrites to `SOCKET_API_TOKEN`. Skipped:
+ *   - Lines marked with `socket-api-token-env: bootstrap` adjacent
+ *     comment — the alias-normalization code that intentionally reads
+ *     all four names. The bootstrap hook is the one place legacy
+ *     aliases legitimately appear.
+ *   - The literal `SOCKET_CLI_API_TOKEN` — unrelated; that's the
+ *     socket-cli configuration setting, not an API token alias.
+ */
+
+const LEGACY_ALIASES = new Set([
+  'SOCKET_API_KEY',
+  'SOCKET_SECURITY_API_TOKEN',
+  'SOCKET_SECURITY_API_KEY',
+])
+
+const CANONICAL = 'SOCKET_API_TOKEN'
+
+const BYPASS_RE = /socket-api-token-env:\s*bootstrap/
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Use the canonical SOCKET_API_TOKEN env var; rewrite legacy aliases (SOCKET_API_KEY, SOCKET_SECURITY_API_TOKEN, SOCKET_SECURITY_API_KEY).',
+      category: 'Best Practices',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      legacy:
+        '`{{name}}` is a legacy alias — use `SOCKET_API_TOKEN` (the canonical fleet name). Bootstrap hooks normalize the aliases.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    function hasBypassComment(node) {
+      const before = sourceCode.getCommentsBefore(node)
+      const after = sourceCode.getCommentsAfter(node)
+      for (const c of [...before, ...after]) {
+        if (BYPASS_RE.test(c.value)) {
+          return true
+        }
+      }
+      return false
+    }
+
+    function checkStringValue(node, value) {
+      // Match exactly; we don't want partial substrings.
+      if (!LEGACY_ALIASES.has(value)) {
+        return
+      }
+      if (hasBypassComment(node)) {
+        return
+      }
+      context.report({
+        node,
+        messageId: 'legacy',
+        data: { name: value },
+        fix(fixer) {
+          const raw = sourceCode.getText(node)
+          const quote = raw[0]
+          if (quote === '`') {
+            return fixer.replaceText(node, '`' + CANONICAL + '`')
+          }
+          return fixer.replaceText(node, quote + CANONICAL + quote)
+        },
+      })
+    }
+
+    return {
+      Literal(node) {
+        if (typeof node.value !== 'string') {
+          return
+        }
+        checkStringValue(node, node.value)
+      },
+      TemplateLiteral(node) {
+        if (node.expressions.length !== 0) {
+          return
+        }
+        checkStringValue(node, node.quasis[0].value.cooked)
+      },
+      // Also catch `process.env.SOCKET_API_KEY` (member expression).
+      MemberExpression(node) {
+        if (node.computed) {
+          return
+        }
+        if (node.property.type !== 'Identifier') {
+          return
+        }
+        if (!LEGACY_ALIASES.has(node.property.name)) {
+          return
+        }
+        // Confirm it's `process.env.X` shape so we don't false-positive
+        // on unrelated objects that happen to have a property named
+        // SOCKET_API_KEY.
+        const obj = node.object
+        if (
+          obj.type !== 'MemberExpression' ||
+          obj.property.type !== 'Identifier' ||
+          obj.property.name !== 'env'
+        ) {
+          return
+        }
+        if (obj.object.type !== 'Identifier' || obj.object.name !== 'process') {
+          return
+        }
+        if (hasBypassComment(node)) {
+          return
+        }
+        context.report({
+          node: node.property,
+          messageId: 'legacy',
+          data: { name: node.property.name },
+          fix(fixer) {
+            return fixer.replaceText(node.property, CANONICAL)
+          },
+        })
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/sort-equality-disjunctions.mts b/.config/oxlint-plugin/rules/sort-equality-disjunctions.mts
new file mode 100644
index 0000000..10e7dfd
--- /dev/null
+++ b/.config/oxlint-plugin/rules/sort-equality-disjunctions.mts
@@ -0,0 +1,252 @@
+/**
+ * @fileoverview Sort string-equality disjunctions alphanumerically.
+ *
+ * Per CLAUDE.md "Sorting" rule, `x === 'a' || x === 'b' || x === 'c'`
+ * is sorted by the comparand string (literal byte order, ASCII before
+ * letters). Order doesn't affect runtime semantics — JS's `||`
+ * short-circuits regardless of operand order — but keeps the diff
+ * churn low when adding a new comparand and makes "is X in this set?"
+ * checks visually consistent across the fleet.
+ *
+ * Detects:
+ *   - `(x === 'a' || x === 'b')`
+ *   - `(x !== 'a' && x !== 'b')` — De Morgan dual; ordering rule applies
+ *   - Chains of any length (≥2 operands).
+ *
+ * Each disjunction must:
+ *   - Use the SAME left operand (`x` in the example) for every clause.
+ *   - Use the SAME comparison operator (`===` for `||` chains, `!==`
+ *     for `&&` chains).
+ *   - Use string-literal right operands (number / boolean / template
+ *     literals are skipped — those rarely benefit from alpha order
+ *     and confuse the autofix).
+ *
+ * Autofix: rewrites the right-hand string literals in sorted order.
+ * Skipped (reports without fix) when:
+ *   - Any clause's left operand differs (mixed identifier).
+ *   - Any clause's right operand isn't a plain string literal.
+ *   - Any clause uses a different operator from the first.
+ *   - Comments live between clauses (reordering through a comment
+ *     would break attribution).
+ *
+ * Why a separate rule from sort-named-imports / sort-set-args:
+ *   - The shape is structurally different (BinaryExpression chain
+ *     under LogicalExpression, not an ArrayExpression / ImportSpecifier).
+ *   - Catches the most common "is this one of these constants?"
+ *     pattern in dispatch code (e.g. switch-prelude guards,
+ *     fix-action category checks). A single rule keeps this normalized.
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Sort string-equality disjunctions alphanumerically (`x === "a" || x === "b"`).',
+      category: 'Stylistic Issues',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      unsorted:
+        'String-equality disjunction operands are out of alphabetical order. Saw `{{actual}}`, expected `{{expected}}`.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    /**
+     * Flatten a left-associative LogicalExpression chain into a list
+     * of leaf nodes. `(a || b) || c` and `a || (b || c)` both flatten
+     * to [a, b, c]. We require the chain operator to be uniform
+     * (caller checks).
+     */
+    function flatten(node, op, out) {
+      if (node.type === 'LogicalExpression' && node.operator === op) {
+        flatten(node.left, op, out)
+        flatten(node.right, op, out)
+      } else {
+        out.push(node)
+      }
+    }
+
+    /**
+     * For a binary-equality leaf, return `{ left, right, operator }`
+     * if it's the shape we sort. Returns undefined otherwise.
+     */
+    function asEqualityClause(node) {
+      if (node.type !== 'BinaryExpression') {
+        return undefined
+      }
+      if (node.operator !== '===' && node.operator !== '!==') {
+        return undefined
+      }
+      // Right side must be a plain string-literal Identifier-comparand pattern.
+      if (
+        node.right.type !== 'Literal' ||
+        typeof node.right.value !== 'string'
+      ) {
+        return undefined
+      }
+      // Left side: prefer Identifier, but accept MemberExpression so
+      // `cat.x === 'a' || cat.x === 'b'` works too.
+      if (
+        node.left.type !== 'Identifier' &&
+        node.left.type !== 'MemberExpression'
+      ) {
+        return undefined
+      }
+      return {
+        leftText: sourceCode.getText(node.left),
+        operator: node.operator,
+        right: node.right,
+        rightValue: node.right.value,
+      }
+    }
+
+    /**
+     * Returns true if a comment lies anywhere between the first and
+     * last leaf of the chain. Comment-aware skipping prevents the
+     * autofix from silently relocating attribution.
+     */
+    function hasInteriorComment(leaves) {
+      if (!sourceCode.getCommentsInside) {
+        return false
+      }
+      const first = leaves[0]
+      const last = leaves[leaves.length - 1]
+      const all = sourceCode.getCommentsInside({
+        range: [first.range[0], last.range[1]],
+        loc: { start: first.loc.start, end: last.loc.end },
+        type: 'Program',
+      })
+      return all.length > 0
+    }
+
+    function checkChain(rootNode) {
+      // Top-level filter: only check the OUTERMOST `||` or `&&` of a
+      // chain, not its sub-expressions. We detect "outermost" by the
+      // parent being either non-LogicalExpression or a different
+      // operator.
+      const parent = rootNode.parent
+      if (
+        parent &&
+        parent.type === 'LogicalExpression' &&
+        parent.operator === rootNode.operator
+      ) {
+        return
+      }
+
+      const op = rootNode.operator
+      // We only process || and && chains.
+      if (op !== '||' && op !== '&&') {
+        return
+      }
+
+      const leaves = []
+      flatten(rootNode, op, leaves)
+      if (leaves.length < 2) {
+        return
+      }
+
+      const clauses = []
+      for (const leaf of leaves) {
+        const c = asEqualityClause(leaf)
+        if (!c) {
+          // Mixed shape — skip the whole chain. The rule only
+          // applies to homogeneous equality chains.
+          return
+        }
+        clauses.push(c)
+      }
+
+      // Operator/leftText must be uniform within the chain. For `||`
+      // chains the natural shape is `===`; for `&&` chains it's `!==`
+      // (De Morgan). Mixed → skip (rare and the rewrite would change
+      // semantics).
+      const firstLeft = clauses[0].leftText
+      const firstOp = clauses[0].operator
+      for (let i = 1; i < clauses.length; i++) {
+        if (
+          clauses[i].leftText !== firstLeft ||
+          clauses[i].operator !== firstOp
+        ) {
+          return
+        }
+      }
+
+      // For `||` chains, expect `===`. For `&&` chains, expect `!==`.
+      // Other combinations are valid logic but not the shape this rule
+      // sorts (they'd be tautologies or contradictions).
+      if (op === '||' && firstOp !== '===') {
+        return
+      }
+      if (op === '&&' && firstOp !== '!==') {
+        return
+      }
+
+      // Compute the sorted order.
+      const sortedClauses = [...clauses].sort((a, b) => {
+        if (a.rightValue < b.rightValue) {
+          return -1
+        }
+        if (a.rightValue > b.rightValue) {
+          return 1
+        }
+        return 0
+      })
+
+      const actualOrder = clauses.map(c => c.rightValue).join(', ')
+      const expectedOrder = sortedClauses.map(c => c.rightValue).join(', ')
+
+      if (actualOrder === expectedOrder) {
+        return
+      }
+
+      // Check for interior comments — skip autofix if any.
+      if (hasInteriorComment(leaves)) {
+        context.report({
+          node: rootNode,
+          messageId: 'unsorted',
+          data: { actual: actualOrder, expected: expectedOrder },
+        })
+        return
+      }
+
+      context.report({
+        node: rootNode,
+        messageId: 'unsorted',
+        data: { actual: actualOrder, expected: expectedOrder },
+        fix(fixer) {
+          // Replace each leaf's right-string-literal with the
+          // sorted-position counterpart. Because the chain is
+          // homogeneous (same left, same op), the rewrite is safe
+          // semantically — only the comparand strings reorder.
+          const fixes = []
+          for (let i = 0; i < leaves.length; i++) {
+            const leaf = leaves[i]
+            const targetRight = sortedClauses[i].right
+            // The leaf's right node is what we rewrite.
+            // BinaryExpression.right's range covers just the literal.
+            const rawTarget = sourceCode.getText(targetRight)
+            fixes.push(
+              fixer.replaceText(asEqualityClause(leaf).right, rawTarget),
+            )
+          }
+          return fixes
+        },
+      })
+    }
+
+    return {
+      LogicalExpression: checkChain,
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/sort-named-imports.mts b/.config/oxlint-plugin/rules/sort-named-imports.mts
new file mode 100644
index 0000000..7d02d2d
--- /dev/null
+++ b/.config/oxlint-plugin/rules/sort-named-imports.mts
@@ -0,0 +1,176 @@
+/**
+ * @fileoverview Per CLAUDE.md "Sorting" rule: sort the named-imports
+ * inside a single `import { ... }` statement alphanumerically (literal
+ * byte order — ASCII before letters). Default + namespace imports
+ * (`import foo, { ... } from`, `import * as ns from`) keep their
+ * leading binding; only the named-imports clause gets sorted.
+ *
+ * Detects `import { c, b, a } from 'pkg'` (and aliased forms like
+ * `import { c as x, b, a } from 'pkg'`).
+ *
+ * Autofix: rewrites the brace contents in alphabetical order. Comments
+ * inside the brace are NOT moved — when there's a comment between
+ * specifiers, the rule skips the autofix and only reports, because
+ * reordering through a comment can break attribution. The rewrite
+ * preserves trailing-newline / multi-line layout: a single-line block
+ * stays single-line; a multi-line block stays multi-line with one
+ * specifier per line.
+ *
+ * Sort key: the *imported* name (before any `as` alias), so
+ * `Z as a, A as z` sorts to `A as z, Z as a` (the import side is the
+ * stable identity, not the local).
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Sort named imports alphanumerically within an import statement.',
+      category: 'Stylistic Issues',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      unsorted:
+        'Named imports must be sorted alphabetically. Saw `{{actual}}`, expected `{{expected}}`.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    function specSortKey(spec) {
+      // ImportSpecifier — sort by `imported.name`.
+      // Default / namespace specifiers don't appear in the named list.
+      if (spec.imported && spec.imported.name) {
+        return spec.imported.name
+      }
+      if (spec.imported && spec.imported.value) {
+        return spec.imported.value
+      }
+      return spec.local && spec.local.name ? spec.local.name : ''
+    }
+
+    function isAlreadySorted(names) {
+      for (let i = 1; i < names.length; i++) {
+        if (names[i - 1] > names[i]) {
+          return false
+        }
+      }
+      return true
+    }
+
+    return {
+      ImportDeclaration(node) {
+        // Pull only the named-imports (skip default + namespace).
+        const named = node.specifiers.filter(s => s.type === 'ImportSpecifier')
+        if (named.length < 2) {
+          return
+        }
+
+        const keys = named.map(specSortKey)
+        if (isAlreadySorted(keys)) {
+          return
+        }
+
+        const sorted = [...named].sort((a, b) => {
+          const ka = specSortKey(a)
+          const kb = specSortKey(b)
+          return ka < kb ? -1 : ka > kb ? 1 : 0
+        })
+        const sortedKeys = sorted.map(specSortKey)
+
+        // If any comment lives between the first and last named
+        // specifier, skip autofix — reordering through comments
+        // breaks attribution.
+        const first = named[0]
+        const last = named[named.length - 1]
+        const interior = sourceCode.getCommentsInside
+          ? sourceCode
+              .getCommentsInside(node)
+              .filter(
+                c =>
+                  c.range[0] >= first.range[0] && c.range[1] <= last.range[1],
+              )
+          : []
+
+        if (interior.length > 0) {
+          context.report({
+            node,
+            messageId: 'unsorted',
+            data: {
+              actual: keys.join(', '),
+              expected: sortedKeys.join(', '),
+            },
+          })
+          return
+        }
+
+        context.report({
+          node,
+          messageId: 'unsorted',
+          data: {
+            actual: keys.join(', '),
+            expected: sortedKeys.join(', '),
+          },
+          fix(fixer) {
+            // Detect single-line vs multi-line by looking at the
+            // first-token-after-`{` and last-token-before-`}`.
+            const firstText = sourceCode.getText(first)
+            const lastText = sourceCode.getText(last)
+            // The slice between { and } — preserves `,` newline padding.
+            const openBrace = sourceCode.getTokenBefore(first, {
+              filter: t => t.value === '{',
+            })
+            const closeBrace = sourceCode.getTokenAfter(last, {
+              filter: t => t.value === '}',
+            })
+            if (!openBrace || !closeBrace) {
+              return null
+            }
+            const sliceStart = openBrace.range[1]
+            const sliceEnd = closeBrace.range[0]
+            const original = sourceCode.text.slice(sliceStart, sliceEnd)
+
+            const isMultiline = /\n/.test(original)
+            // Trim leading/trailing whitespace on the original to
+            // detect indentation. Multi-line case preserves the
+            // pre-spec indent.
+            let indent = ''
+            if (isMultiline) {
+              const m = original.match(/\n([ \t]*)/)
+              if (m) {
+                indent = m[1]
+              }
+            }
+
+            const specTexts = sorted.map(s => sourceCode.getText(s))
+            let rebuilt
+            if (isMultiline) {
+              rebuilt = '\n' + specTexts.map(t => indent + t).join(',\n')
+              // Detect trailing comma in the original.
+              const trailingComma = /,\s*$/.test(original.replace(/\s+$/, ''))
+                ? ','
+                : ''
+              // Trim trailing whitespace before the closing brace and
+              // re-emit a newline + closing-brace indentation.
+              const closeIndent = indent.replace(/^( {2}| {4}|\t)/, '')
+              rebuilt += trailingComma + '\n' + closeIndent
+            } else {
+              rebuilt = ' ' + specTexts.join(', ') + ' '
+            }
+
+            return fixer.replaceTextRange([sliceStart, sliceEnd], rebuilt)
+          },
+        })
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/sort-regex-alternations.mts b/.config/oxlint-plugin/rules/sort-regex-alternations.mts
new file mode 100644
index 0000000..8c8b4e0
--- /dev/null
+++ b/.config/oxlint-plugin/rules/sort-regex-alternations.mts
@@ -0,0 +1,235 @@
+/**
+ * @fileoverview Sort regex alternation groups alphanumerically. Per
+ * CLAUDE.md "Sorting" rule extended to alternation: `(b|a)` should be
+ * `(a|b)` so the regex reads in the same order as the rest of the
+ * fleet's sorted-by-default style.
+ *
+ * Detects:
+ *   - Capturing groups: `(foo|bar|baz)` → require sorted order.
+ *   - Non-capturing groups: `(?:foo|bar)` → same.
+ *   - Named-capture: `(?<name>foo|bar)` → same.
+ *
+ * Allowed exceptions (skipped):
+ *   - Single-alternative groups (`(foo)`) — nothing to sort.
+ *   - Position-bearing alternations where order encodes precedence
+ *     (e.g. `<!--|-->` where `-->` MUST be tried after `<!--`). The
+ *     rule can't prove this is the case, so it requires authors to
+ *     append `// socket-hook: allow regex-alternation-order` on the
+ *     line for the genuine exception.
+ *   - Alternations whose elements aren't simple literals (containing
+ *     `(`, `[`, `?`, `*`, `+`, `{`, etc.) — sorting may change
+ *     match semantics in subtle ways. Reported but not auto-fixed.
+ *
+ * Autofix: rewrites the alternation in alphanumeric order when every
+ * element is a "simple literal" (alphanumeric / underscore / hyphen
+ * / colon / dot / forward-slash content). For richer alternations,
+ * reports without autofix.
+ */
+
+const SOCKET_HOOK_MARKER_RE =
+  /(?:#|\/\/|\/\*)\s*socket-hook:\s*allow(?:\s+([\w-]+))?/
+
+const SIMPLE_ALT_ELEMENT_RE = /^[\w\-:./]+$/
+
+function isLineMarkered(line) {
+  const m = line.match(SOCKET_HOOK_MARKER_RE)
+  if (!m) {
+    return false
+  }
+  return !m[1] || m[1] === 'regex-alternation-order'
+}
+
+/**
+ * Find every alternation group in a regex pattern. Returns
+ * `{ start, end, prefix, alternatives, suffix }` for each group.
+ * Walks the pattern character by character to handle nested groups +
+ * character classes correctly.
+ */
+function findAlternationGroups(pattern) {
+  const groups = []
+  // Stack entries: { start: idx of '(' in original, alts: [{start, end}], altStart: idx }
+  const stack = []
+  let inClass = false
+  let i = 0
+  while (i < pattern.length) {
+    const c = pattern[i]
+    if (c === '\\') {
+      i += 2
+      continue
+    }
+    if (inClass) {
+      if (c === ']') {
+        inClass = false
+      }
+      i++
+      continue
+    }
+    if (c === '[') {
+      inClass = true
+      i++
+      continue
+    }
+    if (c === '(') {
+      // Skip group-prefix syntax: `(?:`, `(?=`, `(?!`, `(?<name>`, `(?<=`, `(?<!`.
+      let prefixEnd = i + 1
+      let prefix = '('
+      if (pattern[prefixEnd] === '?') {
+        prefix += '?'
+        prefixEnd++
+        const next = pattern[prefixEnd]
+        if (next === ':' || next === '=' || next === '!') {
+          prefix += next
+          prefixEnd++
+        } else if (next === '<') {
+          prefix += '<'
+          prefixEnd++
+          // Read named capture name or lookbehind anchor.
+          const after = pattern[prefixEnd]
+          if (after === '=' || after === '!') {
+            prefix += after
+            prefixEnd++
+          } else {
+            // Named capture group: read name then `>`.
+            while (prefixEnd < pattern.length && pattern[prefixEnd] !== '>') {
+              prefix += pattern[prefixEnd]
+              prefixEnd++
+            }
+            if (prefixEnd < pattern.length) {
+              prefix += '>'
+              prefixEnd++
+            }
+          }
+        }
+      }
+      stack.push({ start: i, prefixEnd, alts: [], altStart: prefixEnd })
+      i = prefixEnd
+      continue
+    }
+    if (c === '|' && stack.length > 0) {
+      const top = stack[stack.length - 1]
+      top.alts.push({ start: top.altStart, end: i })
+      top.altStart = i + 1
+      i++
+      continue
+    }
+    if (c === ')') {
+      const top = stack.pop()
+      if (top) {
+        top.alts.push({ start: top.altStart, end: i })
+        if (top.alts.length > 1) {
+          groups.push({
+            altsRanges: top.alts,
+            end: i,
+            prefixEnd: top.prefixEnd,
+            start: top.start,
+          })
+        }
+      }
+      i++
+      continue
+    }
+    i++
+  }
+  return groups
+}
+
+/**
+ * Sort an alternation in alphanumeric order. Returns null if any
+ * element isn't a simple literal (caller should report-only).
+ */
+function sortAlternativesIfSimple(pattern, group) {
+  const alts = group.altsRanges.map(r => pattern.slice(r.start, r.end))
+  const allSimple = alts.every(a => SIMPLE_ALT_ELEMENT_RE.test(a))
+  if (!allSimple) {
+    return null
+  }
+  const sorted = [...alts].sort()
+  if (alts.every((a, i) => a === sorted[i])) {
+    return null
+  }
+  return { actual: alts, sorted }
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Sort regex alternation groups alphanumerically per the CLAUDE.md sorting rule.',
+      category: 'Stylistic Issues',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      unsorted:
+        'Regex alternation `({{actual}})` is not sorted alphanumerically. Expected `({{sorted}})`.',
+      unsortedNoFix:
+        'Regex alternation `({{actual}})` is not sorted alphanumerically. Expected `({{sorted}})`. (Not auto-fixed: contains non-literal elements; sort manually or append `// socket-hook: allow regex-alternation-order` if the order is intentional.)',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    function checkLiteral(node) {
+      if (!node.regex) {
+        return
+      }
+      const sourceCode = context.getSourceCode
+        ? context.getSourceCode()
+        : context.sourceCode
+      const line = sourceCode.lines[node.loc.start.line - 1] ?? ''
+      if (isLineMarkered(line)) {
+        return
+      }
+      const pattern = node.regex.pattern
+      const groups = findAlternationGroups(pattern)
+      for (const group of groups) {
+        const result = sortAlternativesIfSimple(pattern, group)
+        if (!result) {
+          // Not simple: still flag if alternation is unsorted (caller picks).
+          const alts = group.altsRanges.map(r => pattern.slice(r.start, r.end))
+          const sortedRaw = [...alts].sort()
+          if (alts.every((a, i) => a === sortedRaw[i])) {
+            continue
+          }
+          context.report({
+            node,
+            messageId: 'unsortedNoFix',
+            data: {
+              actual: alts.join('|'),
+              sorted: sortedRaw.join('|'),
+            },
+          })
+          continue
+        }
+        // Build the replacement pattern, then escape the slashes for
+        // RegExp literal form when emitting the autofix.
+        const before = pattern.slice(0, group.prefixEnd)
+        const after = pattern.slice(group.end)
+        const newPattern = before + result.sorted.join('|') + after
+
+        context.report({
+          node,
+          messageId: 'unsorted',
+          data: {
+            actual: result.actual.join('|'),
+            sorted: result.sorted.join('|'),
+          },
+          fix(fixer) {
+            const flags = node.regex.flags || ''
+            return fixer.replaceText(node, `/${newPattern}/${flags}`)
+          },
+        })
+      }
+    }
+
+    return {
+      Literal(node) {
+        checkLiteral(node)
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/sort-set-args.mts b/.config/oxlint-plugin/rules/sort-set-args.mts
new file mode 100644
index 0000000..867dae5
--- /dev/null
+++ b/.config/oxlint-plugin/rules/sort-set-args.mts
@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Sort `new Set([...])` array elements alphanumerically.
+ * Per CLAUDE.md "Sorting" rule, Set/SafeSet constructor arguments are
+ * sorted (literal byte order, ASCII before letters). Order doesn't
+ * affect Set semantics but keeps diff churn low and reading easier.
+ *
+ * Autofix: rewrites the array literal in sorted order. Only fires
+ * when every element is a Literal (string or number) — mixed-type
+ * arrays or arrays containing identifiers/expressions get reported
+ * but not auto-fixed (sorting computed values would change behavior).
+ */
+
+const SET_NAMES = new Set(['Set', 'SafeSet'])
+
+function isSortableElement(node) {
+  return (
+    node !== null &&
+    node.type === 'Literal' &&
+    (typeof node.value === 'string' || typeof node.value === 'number')
+  )
+}
+
+function compareSortable(a, b) {
+  const aVal = String(a.value)
+  const bVal = String(b.value)
+  if (aVal < bVal) {
+    return -1
+  }
+  if (aVal > bVal) {
+    return 1
+  }
+  return 0
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Sort Set/SafeSet constructor array arguments alphanumerically (CLAUDE.md sorting rule).',
+      category: 'Stylistic Issues',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      unsorted:
+        '{{name}}([...]) elements should be sorted alphanumerically. Expected: [{{expected}}]',
+      unsortedNoFix:
+        '{{name}}([...]) elements should be sorted alphanumerically (mixed-type or non-literal elements; sort manually).',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    return {
+      NewExpression(node) {
+        const callee = node.callee
+        if (callee.type !== 'Identifier' || !SET_NAMES.has(callee.name)) {
+          return
+        }
+        if (node.arguments.length !== 1) {
+          return
+        }
+        const arg = node.arguments[0]
+        if (arg.type !== 'ArrayExpression') {
+          return
+        }
+        const els = arg.elements
+        if (els.length < 2) {
+          return
+        }
+
+        const allSortable = els.every(isSortableElement)
+        if (!allSortable) {
+          // Check if it's already sorted by raw text — if so, no report.
+          const raws = els.map(e => (e ? e.raw || '' : ''))
+          const sortedRaws = [...raws].sort()
+          if (raws.every((r, i) => r === sortedRaws[i])) {
+            return
+          }
+          context.report({
+            node: arg,
+            messageId: 'unsortedNoFix',
+            data: { name: callee.name },
+          })
+          return
+        }
+
+        const sorted = [...els].sort(compareSortable)
+        const isSorted = sorted.every((s, i) => s === els[i])
+        if (isSorted) {
+          return
+        }
+
+        const sourceCode = context.getSourceCode
+          ? context.getSourceCode()
+          : context.sourceCode
+        const expected = sorted.map(e => sourceCode.getText(e)).join(', ')
+
+        context.report({
+          node: arg,
+          messageId: 'unsorted',
+          data: { name: callee.name, expected },
+          fix(fixer) {
+            const newText = `[${expected}]`
+            return fixer.replaceText(arg, newText)
+          },
+        })
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/oxlint-plugin/rules/sort-source-methods.mts b/.config/oxlint-plugin/rules/sort-source-methods.mts
new file mode 100644
index 0000000..cdbdc63
--- /dev/null
+++ b/.config/oxlint-plugin/rules/sort-source-methods.mts
@@ -0,0 +1,349 @@
+/**
+ * @fileoverview Top-level function declarations should be ordered by
+ * visibility group then alphanumerically within each group:
+ *
+ *   1. Private (un-exported) functions, sorted alphanumerically.
+ *   2. Exported functions (`export function ...`), sorted alphanumerically.
+ *   3. The script entrypoint (`main()` for runners) is allowed to be
+ *      last regardless of name.
+ *
+ * Rationale: a reader scanning the file should be able to predict
+ * where any function lives. Mixed-visibility ordering makes it hard
+ * to find the public surface; alphabetical inside each group is
+ * cheap, deterministic, and matches the rest of the fleet's sorting
+ * conventions (CLAUDE.md "Sorting" rule).
+ *
+ * Autofix: emits a single fix that re-orders top-level function
+ * declarations into canonical order. Function declarations are
+ * hoisted, so reordering them is safe for runtime semantics; the
+ * leading JSDoc / line-comment block above each declaration travels
+ * with the function. The rule only autofixes when every function in
+ * the file has a name (anonymous default exports are skipped) and
+ * when there are no top-level non-function statements interleaved
+ * between functions — interleaved statements can carry side-effects
+ * or rely on declaration order, so we don't reshuffle around them.
+ */
+
+const SCRIPT_ENTRY_NAMES = new Set(['main'])
+
+/**
+ * Type-only top-level statements that can travel with the function they
+ * sit above. Reordering them is safe because they're erased at compile
+ * time (no runtime side effects, no declaration-order semantics).
+ */
+function isTypeOnlyStatement(node) {
+  if (!node) {
+    return false
+  }
+  if (
+    node.type === 'TSTypeAliasDeclaration' ||
+    node.type === 'TSInterfaceDeclaration'
+  ) {
+    return true
+  }
+  if (
+    node.type === 'ExportNamedDeclaration' &&
+    node.declaration &&
+    (node.declaration.type === 'TSTypeAliasDeclaration' ||
+      node.declaration.type === 'TSInterfaceDeclaration')
+  ) {
+    return true
+  }
+  // `export type { ... }` re-exports — typically grouped at top with
+  // imports, but if one slipped between functions it's safe to move.
+  if (
+    node.type === 'ExportNamedDeclaration' &&
+    node.exportKind === 'type' &&
+    !node.declaration
+  ) {
+    return true
+  }
+  return false
+}
+
+function declVisibility(node) {
+  // ExportNamedDeclaration wrapping a FunctionDeclaration.
+  if (
+    node.type === 'ExportNamedDeclaration' &&
+    node.declaration &&
+    node.declaration.type === 'FunctionDeclaration'
+  ) {
+    return { visibility: 'export', fn: node.declaration }
+  }
+  // export default function ...
+  if (
+    node.type === 'ExportDefaultDeclaration' &&
+    node.declaration &&
+    node.declaration.type === 'FunctionDeclaration'
+  ) {
+    return { visibility: 'export', fn: node.declaration }
+  }
+  if (node.type === 'FunctionDeclaration') {
+    return { visibility: 'private', fn: node }
+  }
+  return undefined
+}
+
+/**
+ * Compute the sort key for a function entry. Private functions sort
+ * before exports; within each group, alphanumerical by name. The
+ * script entrypoint (`main`) is pinned to the end regardless of group.
+ */
+function sortKey(entry) {
+  if (entry.isEntrypoint) {
+    // '~' (0x7E) is the highest printable ASCII char, so this sort key
+    // pins the entrypoint to the end of any group.
+    return '~~entrypoint'
+  }
+  return `${entry.visibility === 'private' ? '0' : '1'}${entry.name}`
+}
+
+/**
+ * Locate the byte-range start of a function entry, including any
+ * leading JSDoc / line-comment block that's contiguous with it (a
+ * block separated by a blank line is treated as a free-standing
+ * comment and stays put). Falls back to the node's own start when
+ * there are no leading comments.
+ */
+function leadingCommentStart(sourceCode, node) {
+  const comments = sourceCode.getCommentsBefore
+    ? sourceCode.getCommentsBefore(node)
+    : []
+  if (!comments || comments.length === 0) {
+    return node.range[0]
+  }
+  // Walk from the last comment back, accepting any comment that's
+  // separated from the next one by no more than a single newline
+  // (allows a tight stack of `// foo\n// bar\n/** ... */`).
+  const tokenText = sourceCode.text
+  let earliest = node.range[0]
+  for (let i = comments.length - 1; i >= 0; i--) {
+    const c = comments[i]
+    const between = tokenText.slice(c.range[1], earliest)
+    // Reject if there's a blank line between this comment and the
+    // next block — that means it's a free-standing comment.
+    if (/\n\s*\n/.test(between)) {
+      break
+    }
+    earliest = c.range[0]
+  }
+  return earliest
+}
+
+/**
+ * Locate the byte-range end of a function entry, including any
+ * trailing comment that's contiguous (no blank line between) and
+ * exclusive of the next function. Useful for capturing
+ * c8-ignore-stop markers that pair with a start above the function
+ * — those need to travel with the function when reordered.
+ */
+function trailingCommentEnd(sourceCode, node, nextNodeStart) {
+  const tokenText = sourceCode.text
+  const comments = sourceCode.getCommentsAfter
+    ? sourceCode.getCommentsAfter(node)
+    : []
+  let latest = node.range[1]
+  if (!comments || comments.length === 0) {
+    return latest
+  }
+  for (const c of comments) {
+    if (nextNodeStart !== undefined && c.range[0] >= nextNodeStart) {
+      break
+    }
+    const between = tokenText.slice(latest, c.range[0])
+    // Reject if there's a blank line between this function and the
+    // comment — that means it's a free-standing comment.
+    if (/\n\s*\n/.test(between)) {
+      break
+    }
+    latest = c.range[1]
+  }
+  return latest
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Top-level functions sorted by visibility (private→export) and alphanumerically within each group.',
+      category: 'Stylistic Issues',
+      recommended: true,
+    },
+    fixable: 'code',
+    messages: {
+      groupOutOfOrder:
+        'Top-level function `{{name}}` ({{visibility}}) appears after a function from the next visibility group. Order: private functions first (alphanumeric), then exported functions (alphanumeric).',
+      alphaOutOfOrder:
+        'Top-level function `{{name}}` ({{visibility}}) is out of alphanumeric order within its visibility group. Expected to come before `{{prev}}`.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.getSourceCode
+      ? context.getSourceCode()
+      : context.sourceCode
+
+    return {
+      Program(programNode) {
+        // First pass: collect entries + detect violations.
+        const entries = []
+        let lastVisibilityRank = -1
+        let lastNameInGroup = null
+        let currentVisibility = null
+        const violations = []
+
+        // First find the next program-body node after each function, so
+        // trailingCommentEnd can stop before reaching it.
+        const bodyByIndex = programNode.body
+        for (let i = 0; i < bodyByIndex.length; i++) {
+          const node = bodyByIndex[i]
+          const info = declVisibility(node)
+          if (!info || !info.fn.id || info.fn.id.type !== 'Identifier') {
+            continue
+          }
+          const name = info.fn.id.name
+          const isEntrypoint = SCRIPT_ENTRY_NAMES.has(name)
+          let start = leadingCommentStart(sourceCode, node)
+          // Pull in any contiguous type-only statements (TS type aliases
+          // / interfaces) that sit immediately above this function —
+          // they're erased at compile time, have no runtime side
+          // effects, and are conventionally placed next to the function
+          // that consumes them. They travel with the function on sort.
+          let j = i - 1
+          while (j >= 0 && isTypeOnlyStatement(bodyByIndex[j])) {
+            // Only absorb the type when there's no other function entry
+            // between it and the current node (entries are pushed in
+            // order, so the previous entry's `end` marks where the
+            // previous function's range ended).
+            const prevEntry = entries[entries.length - 1]
+            if (prevEntry && prevEntry.end > bodyByIndex[j].range[0]) {
+              break
+            }
+            start = leadingCommentStart(sourceCode, bodyByIndex[j])
+            j -= 1
+          }
+          const nextStart =
+            i + 1 < bodyByIndex.length ? bodyByIndex[i + 1].range[0] : undefined
+          const end = trailingCommentEnd(sourceCode, node, nextStart)
+          entries.push({
+            node,
+            name,
+            visibility: info.visibility,
+            isEntrypoint,
+            start,
+            end,
+          })
+
+          if (isEntrypoint) {
+            continue
+          }
+
+          const rank = info.visibility === 'private' ? 0 : 1
+
+          if (rank < lastVisibilityRank) {
+            violations.push({
+              node: info.fn.id,
+              messageId: 'groupOutOfOrder',
+              data: { name, visibility: info.visibility },
+            })
+            continue
+          }
+          if (rank !== lastVisibilityRank) {
+            currentVisibility = info.visibility
+            lastVisibilityRank = rank
+            lastNameInGroup = name
+            continue
+          }
+          if (lastNameInGroup !== null && name < lastNameInGroup) {
+            violations.push({
+              node: info.fn.id,
+              messageId: 'alphaOutOfOrder',
+              data: {
+                name,
+                visibility: currentVisibility,
+                prev: lastNameInGroup,
+              },
+            })
+          } else {
+            lastNameInGroup = name
+          }
+        }
+
+        if (violations.length === 0) {
+          return
+        }
+
+        // Build the fix once, applied via the first violation. ESLint
+        // dedupes overlapping fixes, so attaching it once is enough.
+        const sorted = entries.slice().sort((a, b) => {
+          const ka = sortKey(a)
+          const kb = sortKey(b)
+          if (ka < kb) {
+            return -1
+          }
+          if (ka > kb) {
+            return 1
+          }
+          return 0
+        })
+
+        const orderedByPosition = entries
+          .slice()
+          .sort((a, b) => a.start - b.start)
+        const sourceText = sourceCode.text
+        const rangeStart = orderedByPosition[0].start
+        const rangeEnd = orderedByPosition[orderedByPosition.length - 1].end
+
+        // Bail if any runtime statement lives between the first and
+        // last function — re-ordering would skip over them and lose
+        // their side-effects / declaration-order semantics. Type-only
+        // statements (TSTypeAliasDeclaration / TSInterfaceDeclaration
+        // and their exported forms) are erased at compile time and are
+        // already absorbed into the preceding function's range above,
+        // so they don't trigger the bail.
+        for (const stmt of programNode.body) {
+          const isFn = entries.some(e => e.node === stmt)
+          if (isFn || isTypeOnlyStatement(stmt)) {
+            continue
+          }
+          if (stmt.range[0] >= rangeStart && stmt.range[1] <= rangeEnd) {
+            // Statement is sandwiched between functions; skip autofix.
+            for (const v of violations) {
+              context.report(v)
+            }
+            return
+          }
+        }
+
+        const sortedTexts = sorted.map(e => sourceText.slice(e.start, e.end))
+        const replacement = sortedTexts.join('\n\n')
+
+        // Attach the fix to the first violation only; the rest are
+        // reported without a fix so the user sees what's wrong even
+        // when applying without --fix.
+        let fixerAttached = false
+        for (const v of violations) {
+          if (!fixerAttached) {
+            context.report({
+              ...v,
+              fix(fixer) {
+                return fixer.replaceTextRange(
+                  [rangeStart, rangeEnd],
+                  replacement,
+                )
+              },
+            })
+            fixerAttached = true
+          } else {
+            context.report(v)
+          }
+        }
+      },
+    }
+  },
+}
+
+export default rule
diff --git a/.config/rolldown/lib-stub.mts b/.config/rolldown/lib-stub.mts
new file mode 100644
index 0000000..baa0fa7
--- /dev/null
+++ b/.config/rolldown/lib-stub.mts
@@ -0,0 +1,48 @@
+/**
+ * @fileoverview rolldown plugin: stub heavy `@socketsecurity/lib`
+ * internals that runtime code never reaches.
+ *
+ * Why: `@socketsecurity/lib` is the canonical fleet utility surface, but
+ * its module graph statically pulls in heavyweight files (e.g. globs.js
+ * → picomatch ~260KB, sorts.js → semver + npm-pack ~2.5MB) along import
+ * paths that real consumers never traverse. Tree-shaking can't drop
+ * unreachable subgraphs that look reachable to the static analyzer; we
+ * have to tell it explicitly.
+ *
+ * Each consumer passes a `stubPattern` regex matching the absolute
+ * resolved paths of the unreachable files for THEIR import surface.
+ * Verify reachability before adding a pattern — stubbing a file that IS
+ * reached at runtime gives runtime crashes, not bundle-time errors.
+ *
+ * Source: lifted from socket-packageurl-js's inline plugin
+ * (.config/rolldown.config.mts), generalized so the stub-pattern is
+ * caller-provided. Fleet-canonical via socket-wheelhouse.
+ */
+
+import type { Plugin } from 'rolldown'
+
+export type LibStubOptions = {
+  /**
+   * Regex matched against resolved module paths. Files matching get
+   * replaced with an empty CJS module. Required.
+   */
+  readonly stubPattern: RegExp
+  /**
+   * Replacement code. Defaults to `module.exports = {}`. Override only
+   * if you need a non-empty stub (rare).
+   */
+  readonly stubCode?: string
+}
+
+export function createLibStubPlugin(options: LibStubOptions): Plugin {
+  const { stubCode = 'module.exports = {}', stubPattern } = options
+  return {
+    name: 'stub-unused-lib-internals',
+    load(id) {
+      if (stubPattern.test(id)) {
+        return { code: stubCode, moduleSideEffects: false }
+      }
+      return undefined
+    },
+  }
+}
diff --git a/.config/socket-wheelhouse-schema.json b/.config/socket-wheelhouse-schema.json
new file mode 100644
index 0000000..abfbdec
--- /dev/null
+++ b/.config/socket-wheelhouse-schema.json
@@ -0,0 +1,234 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/SocketDev/socket-wheelhouse-schema.json",
+  "title": "socket-wheelhouse per-repo config",
+  "description": "Per-repo socket-wheelhouse config. Two valid locations: `.config/socket-wheelhouse.json` (primary) or `.socket-wheelhouse.json` at the repo root (alternative). Both are first-class — pick the location that fits your repo's convention.",
+  "type": "object",
+  "required": ["schemaVersion", "repoName", "layout", "native"],
+  "properties": {
+    "$schema": {
+      "description": "JSON Schema reference for editor autocompletion. Conventionally `./socket-wheelhouse-schema.json` — both the config and its schema live side-by-side in `.config/`.",
+      "type": "string"
+    },
+    "schemaVersion": {
+      "description": "Schema version. Bump on breaking changes; readers gate on it.",
+      "const": 1,
+      "type": "number"
+    },
+    "repoName": {
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "description": "Canonical repo basename (e.g. `socket-lib`, `ultrathink`). Used for layout / native-independent exemptions like the oxlint `socket-lib` carve-out.",
+      "type": "string"
+    },
+    "layout": {
+      "description": "Package layout. `single-package` = one `package.json` at root, no `packages/`. `monorepo` = pnpm workspaces under `packages/`.",
+      "anyOf": [
+        {
+          "const": "single-package",
+          "type": "string"
+        },
+        {
+          "const": "monorepo",
+          "type": "string"
+        }
+      ]
+    },
+    "native": {
+      "description": "Native-binary supply-chain role. `none` = pure-npm publish path. `consumer` = pulls prebuilt binaries from a sibling producer. `producer` = ships native artifacts via GH releases. `both` = consumes one set, produces another. (Per-language ports live in `lockstep.json` `lang-parity` rows, not here.)",
+      "anyOf": [
+        {
+          "const": "none",
+          "type": "string"
+        },
+        {
+          "const": "consumer",
+          "type": "string"
+        },
+        {
+          "const": "producer",
+          "type": "string"
+        },
+        {
+          "const": "both",
+          "type": "string"
+        }
+      ]
+    },
+    "hooks": {
+      "description": "Git-hook opt-ins.",
+      "type": "object",
+      "properties": {
+        "enablePrePush": {
+          "description": "Wire `.husky/pre-push` → `.git-hooks/pre-push.mts`. Mandatory security gate; default true.",
+          "type": "boolean"
+        },
+        "enableCommitMsg": {
+          "description": "Wire `.husky/commit-msg` → `.git-hooks/commit-msg.mts`. Strips AI attribution; default true.",
+          "type": "boolean"
+        },
+        "enablePreCommit": {
+          "description": "Wire `.husky/pre-commit` → `.git-hooks/pre-commit.mts`. Lint + secret scan on staged files; default true.",
+          "type": "boolean"
+        },
+        "preCommitVariant": {
+          "description": "`lint-only` runs format + secret scan; `lint-test` adds vitest on touched packages. Default `lint-test`.",
+          "anyOf": [
+            {
+              "const": "lint-only",
+              "type": "string"
+            },
+            {
+              "const": "lint-test",
+              "type": "string"
+            }
+          ]
+        }
+      }
+    },
+    "scripts": {
+      "description": "package.json script tracking overrides.",
+      "type": "object",
+      "properties": {
+        "required": {
+          "description": "Override REQUIRED_SCRIPTS from manifest.mts. Usually omitted — the fleet default applies.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "optional": {
+          "description": "Per-script opt-in map keyed by script name. `true` = repo ships this RECOMMENDED script; `false` = explicit opt-out.",
+          "type": "object",
+          "patternProperties": {
+            "^(.*)$": {
+              "type": "boolean"
+            }
+          }
+        },
+        "bodyExempt": {
+          "description": "Script names whose body is allowed to drift from the canonical form (e.g. socket-lib runs a richer test runner than the standard `node scripts/test.mts`). Each entry is the script name only.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "lint": {
+      "description": "oxlint profile.",
+      "type": "object",
+      "properties": {
+        "profile": {
+          "description": "`standard` requires the fleet plugin set (import + typescript + unicorn). `rich` opts into a wider set; check the runner for the exact basenames currently exempted.",
+          "anyOf": [
+            {
+              "const": "standard",
+              "type": "string"
+            },
+            {
+              "const": "rich",
+              "type": "string"
+            }
+          ]
+        }
+      }
+    },
+    "workflows": {
+      "description": "CI workflow opt-ins.",
+      "type": "object",
+      "properties": {
+        "ci": {
+          "description": "Ship `.github/workflows/ci.yml`.",
+          "type": "boolean"
+        },
+        "weeklyUpdate": {
+          "description": "Ship `.github/workflows/weekly-update.yml`.",
+          "type": "boolean"
+        },
+        "provenance": {
+          "description": "Repo publishes with npm provenance (OIDC). Hint for setup helpers; not enforced by the checker today.",
+          "type": "boolean"
+        },
+        "requirePinnedFullSha": {
+          "description": "Enforce 40-char SHA pins on every `uses:` ref. Defaults to true; an opt-out is reserved for special cases (e.g. workflow-dispatch test rigs) and currently has no consumer.",
+          "type": "boolean"
+        }
+      }
+    },
+    "claude": {
+      "description": "Claude Code opt-ins.",
+      "type": "object",
+      "properties": {
+        "includeSecurityScanSkill": {
+          "description": "Ship `.claude/skills/scanning-security/SKILL.md`.",
+          "type": "boolean"
+        },
+        "includeSharedSkills": {
+          "description": "Ship `.claude/skills/_shared/*` — env-check, path-guard-rule, report-format, security-tools, verify-build.",
+          "type": "boolean"
+        },
+        "includeUpdatingSkill": {
+          "description": "Ship the dependency-update skill. Reserved — no consumer wired today.",
+          "type": "boolean"
+        }
+      }
+    },
+    "workspace": {
+      "description": "pnpm-workspace.yaml setting hints. The runner reads from the YAML; this block exists for repos that prefer to declare intent in JSON.",
+      "type": "object",
+      "properties": {
+        "allowBuilds": {
+          "description": "pnpm `onlyBuiltDependencies` allowlist. Map a package name to true/false to grant/deny build scripts.",
+          "type": "object",
+          "patternProperties": {
+            "^(.*)$": {
+              "type": "boolean"
+            }
+          }
+        },
+        "blockExoticSubdeps": {
+          "description": "Refuse transitive git/tarball subdeps (direct git deps still allowed). Required true; the field exists so a repo can document the intent locally.",
+          "type": "boolean"
+        },
+        "minimumReleaseAge": {
+          "minimum": 0,
+          "description": "Soak window in minutes before installing freshly-published packages. Fleet default 10080 (= 7 days).",
+          "type": "integer"
+        },
+        "minimumReleaseAgeExclude": {
+          "description": "Scopes / package patterns exempt from the soak window. Socket-owned scopes typically listed here.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "resolutionMode": {
+          "description": "pnpm `resolutionMode`. Fleet default `highest`.",
+          "anyOf": [
+            {
+              "const": "highest",
+              "type": "string"
+            },
+            {
+              "const": "lowest-direct",
+              "type": "string"
+            }
+          ]
+        },
+        "trustPolicy": {
+          "description": "pnpm `trustPolicy`. Fleet default `no-downgrade`.",
+          "anyOf": [
+            {
+              "const": "no-downgrade",
+              "type": "string"
+            },
+            {
+              "const": "match-spec",
+              "type": "string"
+            }
+          ]
+        }
+      }
+    }
+  }
+}
diff --git a/.config/taze.config.mts b/.config/taze.config.mts
new file mode 100644
index 0000000..c5d7111
--- /dev/null
+++ b/.config/taze.config.mts
@@ -0,0 +1,40 @@
+import { defineConfig } from 'taze'
+
+/* Socket-owned scopes bypass the 7-day maturity cooldown.
+ *
+ * The cooldown (maturityPeriod: 7) exists to catch compromised
+ * upstream packages before we adopt them — but Socket-published
+ * packages go through our own provenance + publish pipeline, so
+ * we trust them to ship fresh.
+ *
+ * The scopes listed here are EXCLUDED from pass 1 (the
+ * cooldown-respecting pass) and INCLUDED in pass 2 (the
+ * immediate-bump pass). Keep this list in sync with
+ * scripts/update.mts if the repo ships one, or with whatever
+ * second-pass mechanism the consuming repo's update script
+ * uses.
+ */
+const SOCKET_SCOPES = [
+  '@socketregistry/*',
+  '@socketsecurity/*',
+  '@socketdev/*',
+  'socket-*',
+  'ecc-agentshield',
+  'sfw',
+]
+
+export default defineConfig({
+  // Interactive mode disabled for automation.
+  interactive: false,
+  // Minimal logging.
+  loglevel: 'warn',
+  // Socket scopes handled by a second pass with maturityPeriod 0.
+  exclude: SOCKET_SCOPES,
+  // 7-day cooldown on third-party deps — matches `.npmrc`'s
+  // min-release-age setting for install-time enforcement.
+  maturityPeriod: 7,
+  // Bump to latest across major boundaries.
+  mode: 'latest',
+  // Edit package.json in place.
+  write: true,
+})
diff --git a/.config/tsconfig.base.json b/.config/tsconfig.base.json
new file mode 100644
index 0000000..e1ffc53
--- /dev/null
+++ b/.config/tsconfig.base.json
@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "allowJs": false,
+    "composite": false,
+    "declarationMap": false,
+    "erasableSyntaxOnly": true,
+    "esModuleInterop": true,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "incremental": false,
+    "isolatedModules": true,
+    "lib": ["ES2024"],
+    "noEmitOnError": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noUncheckedIndexedAccess": true,
+    "noUncheckedSideEffectImports": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "sourceMap": false,
+    "strict": true,
+    "strictNullChecks": true,
+    "target": "ES2024",
+    "useUnknownInCatchVariables": true,
+    "verbatimModuleSyntax": true
+  }
+}
diff --git a/.git-hooks/_helpers.mts b/.git-hooks/_helpers.mts
new file mode 100755
index 0000000..9c71cc1
--- /dev/null
+++ b/.git-hooks/_helpers.mts
@@ -0,0 +1,773 @@
+// Shared helpers for git hooks — API-key allowlist + content scanners
+// + tiny string utilities (color wrappers, marker-syntax picker, path
+// normalize). Each hook imports `getDefaultLogger` from
+// `@socketsecurity/lib/logger` directly for output; this module stays
+// import-light so the cost of `import './_helpers.mts'` is bounded.
+//
+// Requires Node 25+ for stable .mts type-stripping (no flag needed).
+// Earlier Node versions either lacked --experimental-strip-types or
+// shipped it under a flag, both unacceptable for hook ergonomics.
+//
+// Hooks run *after* `pnpm install`, so `@socketsecurity/lib` is on the
+// resolution path for any caller that imports it.
+
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+
+// Hard-fail if Node is below 25. This runs at module load — every
+// hook invocation imports _helpers.mts before doing anything, so the
+// version check is the first thing that happens.
+const NODE_MIN_MAJOR = 25
+const nodeMajor = Number.parseInt(
+  process.versions.node.split('.')[0] || '0',
+  10,
+)
+if (nodeMajor < NODE_MIN_MAJOR) {
+  // @socketsecurity/lib requires Node >= 25; the canonical logger
+  // isn't importable here. Use raw process.stderr with ASCII (no
+  // status-emoji glyph) so the no-status-emoji lint rule stays clean
+  // — the lint rule's recommendation (use logger.fail()) doesn't
+  // apply when the entire branch is the logger-unavailable bail.
+  process.stderr.write(
+    `\x1b[0;31mHook requires Node >= ${NODE_MIN_MAJOR}.0.0 (have v${process.versions.node})\x1b[0m\n`,
+  )
+  process.stderr.write(
+    'Install Node 25+ — these hooks rely on stable .mts type stripping.\n',
+  )
+  process.exit(1)
+}
+
+// ── Allowlist constants ────────────────────────────────────────────
+// These exempt known-safe matches from the API-key scanner. Each
+// allowlist entry is a substring; if the matched line contains it,
+// the line is dropped from the findings.
+
+// Real public API key shipped in socket-lib test fixtures. Safe to
+// appear anywhere in the fleet.
+export const ALLOWED_PUBLIC_KEY =
+  'sktsec_t_--RAN5U4ivauy4w37-6aoKyYPDt5ZbaT5JBVMqiwKo_api'
+
+// Substring marker used in test fixtures (see
+// socket-lib/test/unit/utils/fake-tokens.ts). Lines containing this
+// are treated as test fixtures.
+export const FAKE_TOKEN_MARKER = 'socket-test-fake-token'
+
+// Legacy lib-scoped marker — accepted during the rename from
+// `socket-lib-test-fake-token` to `socket-test-fake-token`. Drop when
+// lib's rename PR lands.
+export const FAKE_TOKEN_LEGACY = 'socket-lib-test-fake-token'
+
+// Env-var name prefixes used in shell examples / `.env.example` files.
+// Lines containing `<name>=` are documentation, not real tokens — drop
+// them from secret-scanner hits. SOCKET_API_TOKEN is the canonical
+// fleet name; the rest are legacy variants kept on the allowlist for
+// one cycle so existing `.env.example` files don't trip the gate
+// after the rebrand.
+export const SOCKET_TOKEN_ENV_NAMES: readonly string[] = [
+  'SOCKET_API_TOKEN=',
+  'SOCKET_API_KEY=',
+  'SOCKET_SECURITY_API_TOKEN=',
+  'SOCKET_SECURITY_API_KEY=',
+]
+// Back-compat alias — earlier callers imported this single-string
+// constant. New code should reach for SOCKET_TOKEN_ENV_NAMES.
+export const SOCKET_SECURITY_ENV = SOCKET_TOKEN_ENV_NAMES[0]!
+
+// ── Output ──────────────────────────────────────────────────────────
+//
+// Hooks call `getDefaultLogger()` from `@socketsecurity/lib/logger`
+// directly. Color comes from the logger's semantic methods —
+// `.fail()` is red ✖, `.success()` is green ✔, `.warn()` is yellow ⚠,
+// `.info()` is blue ℹ, `.error()` is plain. ANSI constants and
+// `red()`/`green()`/`yellow()` wrappers are intentionally NOT exported
+// from this module; the logger owns the visual surface.
+
+// Posix-form path normalization for staged file lists. Git on Windows
+// can hand back backslash separators in some surfaces; the downstream
+// `startsWith('.git-hooks/')` / `includes('/external/')` pattern
+// matching assumes forward slashes. Cheap to convert once.
+export const normalizePath = (p: string): string => p.replace(/\\/g, '/')
+
+/**
+ * Split text into lines, normalizing CRLF (`\r\n`) to LF (`\n`) first.
+ *
+ * Hooks consume text from three sources where CRLF can show up:
+ *   - subprocess stdout/stderr (especially git on Windows / msys)
+ *   - stdin from the git push protocol on Windows
+ *   - file contents from a working copy with `core.autocrlf` semantics
+ *
+ * Plain `text.split('\n')` on CRLF input leaves a trailing `\r` on every
+ * line, which breaks per-line regex anchors used by the secret /
+ * personal-path / AI-attribution scanners. The hook then reports "no
+ * findings" on Windows even though the input clearly contains them —
+ * a security-gate fail-open. Always go through this helper for any
+ * text that didn't originate as a literal in our own code.
+ */
+export const splitLines = (text: string): string[] =>
+  text.replace(/\r\n/g, '\n').split('\n')
+
+// ── API-key allowlist filter ───────────────────────────────────────
+
+// Returns true if a line is on the allowlist (a public/example/fake
+// token we deliberately ship). Used by scanners to drop allowlisted
+// hits without losing each hit's original lineNumber.
+const isAllowedApiKey = (line: string): boolean =>
+  line.includes(ALLOWED_PUBLIC_KEY) ||
+  line.includes(FAKE_TOKEN_MARKER) ||
+  line.includes(FAKE_TOKEN_LEGACY) ||
+  SOCKET_TOKEN_ENV_NAMES.some(name => line.includes(name)) ||
+  line.includes('.example')
+
+// Drops any line that matches an allowlist entry. Kept for callers
+// that work on bare lines; new code should filter LineHit[] directly
+// via isAllowedApiKey to preserve per-hit lineNumber.
+export const filterAllowedApiKeys = (lines: readonly string[]): string[] =>
+  lines.filter(line => !isAllowedApiKey(line))
+
+// ── Personal-path scanner ──────────────────────────────────────────
+
+// Real personal paths to flag: /Users/foo/, /home/foo/, C:\Users\foo\.
+const PERSONAL_PATH_RE =
+  /(\/Users\/[^/\s]+\/|\/home\/[^/\s]+\/|C:\\Users\\[^\\]+\\)/
+
+// Placeholders we ALLOW (documentation, not real leaks). The scanner
+// accepts any path component wrapped in <...> or starting with $VAR /
+// ${VAR}, but for **canonical fleet style** use exactly these forms in
+// docs / tests / comments / error messages — pick the one matching the
+// path's platform:
+//
+//   POSIX  →  /Users/<user>/...     (macOS — `<user>` matches $USER)
+//   POSIX  →  /home/<user>/...      (Linux — same convention)
+//   Windows →  C:\Users\<USERNAME>\... (matches %USERNAME%)
+//
+// Don't drift to `<name>` / `<me>` / `<USER>` / `<u>` etc. The
+// `suggestPersonalPathReplacement` helper below auto-rewrites real
+// paths into these canonical shapes; mirror its output everywhere
+// else.
+const PERSONAL_PATH_PLACEHOLDER_RE =
+  /(\/Users\/<[^>]*>\/|\/home\/<[^>]*>\/|C:\\Users\\<[^>]*>\\|\/Users\/\$\{?[A-Z_]+\}?\/|\/home\/\$\{?[A-Z_]+\}?\/)/
+
+// Per-line opt-out marker for our pre-commit / pre-push scanners.
+//
+// Canonical form:    <comment-prefix> socket-hook: allow
+// Targeted form:     <comment-prefix> socket-hook: allow <rule>
+//
+// `<comment-prefix>` is whichever comment style the host file uses —
+// `#` for shell / YAML / TOML / Dockerfile, `//` for TS / JS / Rust /
+// Go / C-family, or `/*` for the C-block-comment opener. The hook is
+// invoked from many file types; pinning to `#` made the marker fail
+// silently in `.ts` / `.mts` files (where `// socket-hook: allow` is
+// the only sensible spelling) and confused contributors.
+//
+// The targeted form names a specific rule (`personal-path`, `npx`,
+// `aws-key`, etc.) and is recommended for reviewers; the bare `allow`
+// form blanket-suppresses every scanner on that line. eslint-style
+// precedent.
+//
+// Legacy `# zizmor: ...` markers are still recognized for one cycle so
+// existing files don't have to be rewritten in the same change that
+// renames the marker.
+const SOCKET_HOOK_MARKER_RE =
+  /(?:#|\/\/|\/\*)\s*socket-hook:\s*allow(?:\s+([\w-]+))?/
+
+// File extensions whose natural comment syntax is `//` (C-family + cousins).
+// Anything else falls through to `#` (shell / YAML / TOML / Dockerfile /
+// Makefile / Python / Ruby / etc).
+const SLASH_COMMENT_EXT_RE =
+  /\.(m?ts|tsx|cts|m?js|jsx|cjs|rs|go|c|cc|cpp|cxx|h|hpp|java|swift|kt|scala|dart|php|css|scss|less)$/i
+
+/**
+ * Pick the natural per-line opt-out marker for a host file.
+ *
+ * The marker regex above accepts `#`, `//`, and `/*` prefixes — but error
+ * messages should print the *one* form a contributor would actually paste
+ * into that file. TS edits get `// socket-hook: allow <rule>`; YAML gets
+ * `# socket-hook: allow <rule>`. Same rule, different comment lexer.
+ */
+export const socketHookMarkerFor = (filePath: string, rule: string): string =>
+  SLASH_COMMENT_EXT_RE.test(filePath)
+    ? `// socket-hook: allow ${rule}`
+    : `# socket-hook: allow ${rule}`
+const LEGACY_ZIZMOR_MARKER_RE = /(?:#|\/\/|\/\*)\s*zizmor:\s*[\w-]+/
+
+// Aliases: legacy marker names recognized as equivalent to a current
+// rule for one deprecation cycle, so callers can rename the canonical
+// rule without breaking files that still carry the old marker.
+//
+// Add entries as `<alias>: <canonical>`; both directions match in the
+// comparison below.
+const RULE_ALIASES: { [k: string]: string | undefined } = {
+  __proto__: null,
+  // 'logger' was the original name when the scanner only flagged
+  // process.std{out,err}.write; it now flags console.* too, so the
+  // canonical marker is 'console'. Keep 'logger' for one cycle.
+  logger: 'console',
+}
+
+export function aliasMatches(marker: string, rule: string): boolean {
+  if (marker === rule) {
+    return true
+  }
+  return RULE_ALIASES[marker] === rule || RULE_ALIASES[rule] === marker
+}
+
+export function lineIsSuppressed(line: string, rule?: string): boolean {
+  if (LEGACY_ZIZMOR_MARKER_RE.test(line)) {
+    return true
+  }
+  const m = line.match(SOCKET_HOOK_MARKER_RE)
+  if (!m) {
+    return false
+  }
+  // No rule named on the marker → blanket allow.
+  if (!m[1]) {
+    return true
+  }
+  // Marker named a specific rule → suppress when the names match
+  // directly OR through an alias.
+  return rule === undefined || aliasMatches(m[1], rule)
+}
+
+// Heuristic context flags: lines that look like "this is a doc example"
+// rather than a real call leaked into runtime code.
+//   - Comment lines (start with `*`, `//`, `#`).
+//   - Lines that contain a JSDoc tag like @example / @param / @returns
+//     (multi-line JSDoc bodies use leading ` * ` which we already match).
+//   - Lines whose entire interesting content sits inside a backtick span
+//     (markdown / template-literal example).
+const COMMENT_LINE_RE = /^\s*(\*|\/\/|#)/
+const JSDOC_TAG_RE = /@(example|param|returns?|see|link)\b/
+
+export function isInsideBackticks(line: string, needleRe: RegExp): boolean {
+  // Find every backtick-delimited span on the line and test if the
+  // pattern only appears within those spans. Conservative: if any
+  // hit is *outside* a span, treat the line as runtime code.
+  const spans: Array<[number, number]> = []
+  for (let i = 0; i < line.length; i++) {
+    if (line[i] === '`') {
+      const end = line.indexOf('`', i + 1)
+      if (end < 0) {
+        break
+      }
+      spans.push([i, end])
+      i = end
+    }
+  }
+  if (spans.length === 0) {
+    return false
+  }
+  let m: RegExpExecArray | null
+  const re = new RegExp(needleRe.source, needleRe.flags.replace('g', '') + 'g')
+  while ((m = re.exec(line)) !== null) {
+    const start = m.index
+    const end = start + m[0].length
+    const inside = spans.some(([s, e]) => start > s && end <= e)
+    if (!inside) {
+      return false
+    }
+  }
+  return true
+}
+
+export function looksLikeDocumentation(
+  line: string,
+  needleRe: RegExp,
+  rule?: string,
+): boolean {
+  if (lineIsSuppressed(line, rule)) {
+    return true
+  }
+  if (COMMENT_LINE_RE.test(line)) {
+    return true
+  }
+  if (JSDOC_TAG_RE.test(line)) {
+    return true
+  }
+  if (isInsideBackticks(line, needleRe)) {
+    return true
+  }
+  return false
+}
+
+export type LineHit = {
+  lineNumber: number
+  line: string
+  // Suggested rewrite when this flagged line is documentation-style and
+  // the scanner can offer a concrete fix. Undefined for runtime-code
+  // paths where the right answer depends on the surrounding code.
+  suggested?: string
+}
+
+// Generic line-walk scanner factory. Splits text into lines once,
+// applies the regex per line, optionally skips lines via `filter` (for
+// allowlists) and/or via `skipDocs` (for documentation-style
+// detection), and optionally attaches a suggested rewrite. Centralizes
+// the loop shape that every concrete scanner used to inline.
+//
+// Options:
+//   filter — return true to drop a line (e.g. allowlist match).
+//   skipDocs.rule — when set, calls looksLikeDocumentation() with the
+//     same regex + this rule name and skips lines that match.
+//   suggest — produces the per-line `suggested` rewrite shown to users.
+function scanLines(
+  text: string,
+  pattern: RegExp,
+  options: {
+    filter?: (line: string) => boolean
+    skipDocs?: { rule: string }
+    suggest?: (line: string) => string
+  } = {},
+): LineHit[] {
+  const hits: LineHit[] = []
+  const lines = splitLines(text)
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    if (!pattern.test(line)) {
+      continue
+    }
+    if (options.filter && options.filter(line)) {
+      continue
+    }
+    if (
+      options.skipDocs &&
+      looksLikeDocumentation(line, pattern, options.skipDocs.rule)
+    ) {
+      continue
+    }
+    const hit: LineHit = { lineNumber: i + 1, line }
+    if (options.suggest) {
+      hit.suggested = options.suggest(line)
+    }
+    hits.push(hit)
+  }
+  return hits
+}
+
+// Build a suggested rewrite for a documentation-style personal path.
+// Replaces the matched real-path username segment with the canonical
+// placeholder form: `<user>` / `<USERNAME>` (matching the platform
+// convention of the surrounding path).
+export function suggestPlaceholder(line: string): string {
+  return line
+    .replace(/\/Users\/[^/\s]+\//g, '/Users/<user>/')
+    .replace(/\/home\/[^/\s]+\//g, '/home/<user>/')
+    .replace(/C:\\Users\\[^\\]+\\/g, 'C:\\Users\\<USERNAME>\\')
+}
+
+// Returns lines that contain a real personal path (excludes lines that
+// are pure placeholders or look like documentation examples). Each hit
+// carries a `suggested` rewrite when the scanner can offer one — the
+// caller surfaces it to the user as the fix recipe.
+export const scanPersonalPaths = (text: string): LineHit[] =>
+  scanLines(text, PERSONAL_PATH_RE, {
+    filter: line => {
+      // Pure-placeholder lines (no real path remains after stripping
+      // every `<...>` placeholder) are documentation, not leaks.
+      if (!PERSONAL_PATH_PLACEHOLDER_RE.test(line)) {
+        return false
+      }
+      const stripped = line.replace(
+        new RegExp(PERSONAL_PATH_PLACEHOLDER_RE, 'g'),
+        '',
+      )
+      return !PERSONAL_PATH_RE.test(stripped)
+    },
+    skipDocs: { rule: 'personal-path' },
+    suggest: suggestPlaceholder,
+  })
+
+// ── Secret scanners ────────────────────────────────────────────────
+
+const SOCKET_API_KEY_RE = /sktsec_[a-zA-Z0-9_-]+/
+const AWS_KEY_RE = /(aws_access_key|aws_secret|\bAKIA[0-9A-Z]{16}\b)/i
+const GITHUB_TOKEN_RE = /gh[ps]_[a-zA-Z0-9]{36}/
+const PRIVATE_KEY_RE = /-----BEGIN (RSA |EC |DSA )?PRIVATE KEY-----/
+
+export const scanSocketApiKeys = (text: string): LineHit[] =>
+  scanLines(text, SOCKET_API_KEY_RE, { filter: isAllowedApiKey })
+
+export const scanAwsKeys = (text: string): LineHit[] =>
+  scanLines(text, AWS_KEY_RE)
+
+export const scanGitHubTokens = (text: string): LineHit[] =>
+  scanLines(text, GITHUB_TOKEN_RE)
+
+export const scanPrivateKeys = (text: string): LineHit[] =>
+  scanLines(text, PRIVATE_KEY_RE)
+
+// ── npx/dlx scanner ────────────────────────────────────────────────
+//
+// Match `npx` / `yarn dlx` only when the token sits at a command
+// position — preceded by start-of-line / whitespace / shell separator
+// (`&&`, `||`, `;`, `|`, `(`, backtick), or directly after a PowerShell
+// `& ` invoke. Exclude JSON-key, env-value, and identifier suffix
+// contexts where `npx` shows up as an embedded substring:
+//   - `"socket-npx": …`            (bin-name suffix)
+//   - `"dev:npx": "…SOCKET_CLI_MODE=npx node …"` (script key + env value)
+//   - `cmd-npx-helper`             (identifier interior)
+// The negative lookbehind catches hyphen / colon / equals / underscore /
+// dot prefixes; the negative lookahead catches the same followed forms
+// (`npx-helper`, `npx:foo`).
+//
+// **Allowed:** `pnpm dlx` / `pnpm exec` / `pn dlx` / `pn exec` / `pnx`
+// (the pnpm v11 shorthands for `pnpm dlx`). `pnpm dlx` is the
+// fleet-canonical fetch-and-run form for documentation lines that
+// describe ad-hoc CLI usage (where the consumer doesn't have the
+// package pinned in their workspace). `pnx` is the v11 shorthand and
+// is equally allowed.
+
+const NPX_DLX_RE = /(?<![\w\-:=.])\b(npx|yarn dlx)\b(?![\w\-:=.])/
+
+// Suggest the canonical replacement for a runtime npx/dlx call.
+// Documentation contexts (comments, JSDoc) are exempt via
+// looksLikeDocumentation(); we only ever land here for code lines, where
+// the right swap is `pnpm exec` (since `pnpm` is the fleet's package
+// manager) or `pnpm run` for script entries. For documentation lines
+// All dlx-style invocations rewrite to `pnpm exec`. This matches the
+// `socket/no-npx-dlx` oxlint rule's autofix and the CLAUDE.md tooling
+// rule (NEVER use npx / pnpm dlx / yarn dlx — use pnpm exec). Keep
+// the alternation ordered longest-prefix-first so `pnpm dlx` matches
+// before any future `pnpm`-anchored rule could shadow it.
+export function suggestNpxReplacement(line: string): string {
+  return line
+    .replace(/\bpnpm dlx\b/g, 'pnpm exec')
+    .replace(/\byarn dlx\b/g, 'pnpm exec')
+    .replace(/\bpnx\b/g, 'pnpm exec')
+    .replace(/\bnpx\b/g, 'pnpm exec')
+}
+
+export const scanNpxDlx = (text: string): LineHit[] =>
+  scanLines(text, NPX_DLX_RE, {
+    skipDocs: { rule: 'npx' },
+    suggest: suggestNpxReplacement,
+  })
+
+// ── Logger leak scanner ────────────────────────────────────────────
+//
+// The fleet rule: source code uses `getDefaultLogger()` from
+// `@socketsecurity/lib/logger`. Direct calls to `process.stderr.write`,
+// `process.stdout.write`, `console.log`, `console.error`, `console.warn`,
+// `console.info`, `console.debug` are blocked. Doc-context lines are
+// exempt; lines carrying `// socket-hook: allow console` (or `#` in
+// non-TS files) are exempt too. Legacy `allow logger` is accepted as
+// an alias for one deprecation cycle.
+
+const LOGGER_LEAK_RE =
+  /\b(process\.std(?:err|out)\.write|console\.(?:log|error|warn|info|debug))\s*\(/
+
+// Map each direct call to its lib-logger equivalent. process.stdout is
+// closer to logger.info; process.stderr / console.error → logger.error;
+// console.warn → logger.warn; console.info / console.log → logger.info;
+// console.debug → logger.debug.
+export function suggestLoggerReplacement(line: string): string {
+  return line
+    .replace(/\bprocess\.stderr\.write\s*\(/g, 'logger.error(')
+    .replace(/\bprocess\.stdout\.write\s*\(/g, 'logger.info(')
+    .replace(/\bconsole\.error\s*\(/g, 'logger.error(')
+    .replace(/\bconsole\.warn\s*\(/g, 'logger.warn(')
+    .replace(/\bconsole\.info\s*\(/g, 'logger.info(')
+    .replace(/\bconsole\.debug\s*\(/g, 'logger.debug(')
+    .replace(/\bconsole\.log\s*\(/g, 'logger.info(')
+}
+
+export const scanLoggerLeaks = (text: string): LineHit[] =>
+  scanLines(text, LOGGER_LEAK_RE, {
+    skipDocs: { rule: 'console' },
+    suggest: suggestLoggerReplacement,
+  })
+
+// ── Cross-repo path scanner ────────────────────────────────────────
+//
+// Two forbidden forms catch the same mistake — referencing another
+// fleet repo by a path that escapes the current repo:
+//
+//   1. `../<fleet-repo>/…` (cross-repo relative). Hardcodes the
+//      assumption that both repos are sibling clones under the same
+//      projects root; breaks in CI sandboxes / fresh clones / non-
+//      standard layouts.
+//   2. `<abs-prefix>/projects/<fleet-repo>/…` (cross-repo absolute,
+//      where <abs-prefix> isn't already caught by scanPersonalPaths
+//      because it uses a placeholder like `${HOME}`).
+//
+// The right way is to import from the published npm package
+// (`@socketsecurity/lib/...`, `@socketsecurity/registry/...`).
+// Scanner detects both shapes; suppress with the canonical marker
+// `<comment-prefix> socket-hook: allow cross-repo`.
+
+const FLEET_REPO_NAMES = [
+  'claude-code',
+  'skills',
+  'socket-addon',
+  'socket-btm',
+  'socket-cli',
+  'socket-lib',
+  'socket-packageurl-js',
+  'socket-registry',
+  'socket-wheelhouse',
+  'socket-sdk-js',
+  'socket-sdxgen',
+  'socket-stuie',
+  'ultrathink',
+  'vscode-socket-security',
+] as const
+
+// `../<repo>/…` or `../../<repo>/…` etc. — relative path that walks
+// out of the current repo into a sibling fleet repo.
+const CROSS_REPO_RELATIVE_RE = new RegExp(
+  String.raw`(?:^|[\s'"\`(=,])\.\.(?:/\.\.)*/(?:${FLEET_REPO_NAMES.join('|')})\b`,
+)
+// `…/projects/<repo>/…` — absolute or env-rooted path into a sibling
+// fleet repo. Catches cases where scanPersonalPaths has already been
+// satisfied via `${HOME}` / `<user>` substitution but the path itself
+// still escapes into another repo.
+const CROSS_REPO_ABSOLUTE_RE = new RegExp(
+  String.raw`/projects/(?:${FLEET_REPO_NAMES.join('|')})\b`,
+)
+const CROSS_REPO_ANY_RE = new RegExp(
+  `${CROSS_REPO_RELATIVE_RE.source}|${CROSS_REPO_ABSOLUTE_RE.source}`,
+)
+
+export const scanCrossRepoPaths = (
+  text: string,
+  currentRepoName?: string,
+): LineHit[] => {
+  const hits: LineHit[] = []
+  const lines = splitLines(text)
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    const m = line.match(CROSS_REPO_ANY_RE)
+    if (!m) {
+      continue
+    }
+    // A repo's own paths (`socket-lib/...` referenced from inside
+    // socket-lib) are fine — we only catch cross-repo escapes.
+    const matched = m[0]
+    if (currentRepoName && matched.includes(`/${currentRepoName}`)) {
+      continue
+    }
+    if (looksLikeDocumentation(line, CROSS_REPO_ANY_RE, 'cross-repo')) {
+      continue
+    }
+    hits.push({
+      lineNumber: i + 1,
+      line,
+      suggested: '',
+    })
+  }
+  return hits
+}
+
+// ── AI attribution scanner ─────────────────────────────────────────
+//
+// Matches BOILERPLATE attribution patterns ("Generated with Claude",
+// "Co-Authored-By: Claude", emoji prefixes, vendor email addresses) —
+// not legitimate product / directory references. Bare "Claude" /
+// "Claude Code" / ".claude/" are valid prose; only the
+// attribution-verb-anchored forms trigger the hook.
+
+const AI_ATTRIBUTION_RE =
+  /(?:(?:Generated|Built|Created|Made|Written|Authored|Powered|Crafted)\s+(?:with|by)\s+(?:Claude|AI|GPT|ChatGPT|Copilot|Cursor|Bard|Gemini)|Co-Authored-By:\s+(?:Claude|AI|GPT|ChatGPT|Copilot|Cursor|Bard|Gemini)|🤖\s+Generated|AI[\s-]generated|Machine[\s-]generated|@(?:anthropic|openai)\.com|^Assistant:)/im
+
+export const containsAiAttribution = (text: string): boolean =>
+  AI_ATTRIBUTION_RE.test(text)
+
+export const stripAiAttribution = (
+  text: string,
+): { cleaned: string; removed: number } => {
+  const lines = splitLines(text)
+  const kept: string[] = []
+  let removed = 0
+  for (const line of lines) {
+    if (AI_ATTRIBUTION_RE.test(line)) {
+      removed++
+    } else {
+      kept.push(line)
+    }
+  }
+  return { cleaned: kept.join('\n'), removed }
+}
+
+// ── Linear reference scanner ──────────────────────────────────────
+//
+// Linear tracking lives in Linear; commit messages stay tool-agnostic
+// (the same rule appears in the canonical CLAUDE.md "public-surface
+// hygiene" block). This scanner enforces it on commit messages and is
+// invoked by .git-hooks/commit-msg.mts.
+//
+// The team-key list is enumerated from the Socket Linear workspace.
+// `PATCH` is listed before `PAT` so the longest-prefix wins on
+// strings like `PATCH-123` — JS regex alternation is leftmost, not
+// longest, so order is load-bearing.
+const LINEAR_TEAM_KEYS = [
+  'ASK',
+  'AUTO',
+  'BOT',
+  'CE',
+  'CORE',
+  'DAT',
+  'DES',
+  'DEV',
+  'ENG',
+  'INFRA',
+  'LAB',
+  'MAR',
+  'MET',
+  'OPS',
+  'PAR',
+  'PATCH',
+  'PAT',
+  'PLAT',
+  'REA',
+  'SALES',
+  'SBOM',
+  'SEC',
+  'SMO',
+  'SUP',
+  'TES',
+  'TI',
+  'WEB',
+] as const
+
+// Match either:
+//   - a team-key + dash + digits, surrounded by non-word chars (or
+//     line start/end) so we don't match inside identifiers like
+//     `someENG-123foo`
+//   - a literal `linear.app/<path>` URL fragment
+//
+// `(^|[^A-Za-z0-9_])` and `($|[^A-Za-z0-9_])` are word-boundary
+// equivalents that also accept end-of-line, since `\b` in JS treats
+// punctuation as a word boundary inconsistently.
+const LINEAR_REF_RE = new RegExp(
+  `(^|[^A-Za-z0-9_])(${LINEAR_TEAM_KEYS.join('|')})-[0-9]+($|[^A-Za-z0-9_])|linear\\.app/[A-Za-z0-9/_-]+`,
+  'g',
+)
+
+// Capture groups for LINEAR_REF_RE:
+//   - match[0]: full match including the leading/trailing word
+//     boundary chars (or the linear.app URL).
+//   - match[1]: leading non-word char (when the team-key branch matched).
+//   - match[2]: team key (when the team-key branch matched).
+// Use the team-key branch's middle chunk by re-extracting `<KEY>-<N>`
+// from match[0]; the URL branch returns match[0] verbatim minus the
+// surrounding word boundaries (which it doesn't have).
+const LINEAR_KEY_DIGITS_RE = new RegExp(
+  `(${LINEAR_TEAM_KEYS.join('|')})-[0-9]+`,
+)
+
+// Returns up to `limit` distinct Linear-style references found in
+// `text`. Comment lines (lines starting with `#`, after the leading
+// whitespace is stripped) are ignored — git uses those for the
+// "Please enter the commit message" hint and we don't want to flag
+// references that appeared in the diff snippet that git inlined.
+export const scanLinearRefs = (text: string, limit = 5): string[] => {
+  const hits: string[] = []
+  for (const rawLine of splitLines(text)) {
+    if (rawLine.trimStart().startsWith('#')) {
+      continue
+    }
+    LINEAR_REF_RE.lastIndex = 0
+    let match: RegExpExecArray | null
+    while ((match = LINEAR_REF_RE.exec(rawLine))) {
+      // Extract the canonical reference: `KEY-NNN` for team-key
+      // matches, or the linear.app/... fragment verbatim.
+      const inner = LINEAR_KEY_DIGITS_RE.exec(match[0])
+      const ref = inner ? inner[0] : match[0]
+      if (!hits.includes(ref)) {
+        hits.push(ref)
+        if (hits.length >= limit) {
+          return hits
+        }
+      }
+    }
+  }
+  return hits
+}
+
+// ── File classification ────────────────────────────────────────────
+
+// Files we never scan: hooks themselves, husky shims, test fixtures.
+const SKIP_FILE_RE =
+  /\.(test|spec)\.(m?[jt]s|tsx?|cts|mts)$|\.example$|\/test\/|\/tests\/|fixtures\/|\.git-hooks\/|\.husky\/|node_modules\/|pnpm-lock\.yaml/
+
+export const shouldSkipFile = (filePath: string): boolean =>
+  SKIP_FILE_RE.test(filePath)
+
+// Returns file content as a string. For binaries, runs `strings` to
+// extract printable byte sequences (catches paths embedded in WASM
+// or other compiled artifacts).
+export const readFileForScan = (filePath: string): string => {
+  if (!existsSync(filePath)) {
+    return ''
+  }
+  try {
+    if (statSync(filePath).isDirectory()) {
+      return ''
+    }
+  } catch {
+    return ''
+  }
+  // Detect binary via grep -I (matches text-only); if grep says
+  // binary, fall back to `strings`.
+  const grepResult = spawnSync('grep', ['-qI', '', filePath])
+  if (grepResult.status === 0) {
+    // Text file.
+    try {
+      return readFileSync(filePath, 'utf8')
+    } catch {
+      return ''
+    }
+  }
+  // Binary — extract strings.
+  const stringsResult = spawnSync('strings', [filePath], {
+    encoding: 'utf8',
+  })
+  return stringsResult.stdout || ''
+}
+
+// ── Git wrappers ───────────────────────────────────────────────────
+//
+// Two flavors:
+//
+//   git(...)         — loose. Returns '' on failure. Used by callers that
+//                      legitimately tolerate a missing ref (e.g. probing
+//                      remote default-branch HEAD which may not be set up
+//                      locally) and provide their own fallback. Silent
+//                      by design — _helpers.mts can't import the canonical
+//                      logger because it runs before the Node-version
+//                      gate has cleared, and a fire-and-forget dynamic
+//                      import races process exit. Callers that need to
+//                      know about failure should use gitOrThrow().
+//
+//   gitOrThrow(...)  — strict. Throws on either spawn error (git not on
+//                      PATH, EAGAIN, …) or non-zero exit. Used by gitLines
+//                      and every security-gate caller in pre-commit /
+//                      pre-push: if `git diff --cached --name-only` fails
+//                      we MUST refuse to greenlight the commit, not pass
+//                      it with "no files to check."
+//
+// gitLines goes through gitOrThrow because every call site we have
+// (staged-file iteration, push-range walking, repo-toplevel lookup)
+// makes a security or correctness decision based on the result; an
+// empty array from a failed git invocation is a fail-open.
+
+export const git = (...args: string[]): string => {
+  const result = spawnSync('git', args, { encoding: 'utf8' })
+  return (result.stdout ?? '').trim()
+}
+
+export const gitOrThrow = (...args: string[]): string => {
+  const result = spawnSync('git', args, { encoding: 'utf8' })
+  if (result.error) {
+    throw new Error(`git ${args.join(' ')}: ${result.error.message}`)
+  }
+  if (typeof result.status !== 'number' || result.status !== 0) {
+    const err = result.stderr?.trim() || `exit ${result.status}`
+    throw new Error(`git ${args.join(' ')}: ${err}`)
+  }
+  return (result.stdout ?? '').trim()
+}
+
+export const gitLines = (...args: string[]): string[] => {
+  const out = gitOrThrow(...args)
+  return out ? splitLines(out) : []
+}
diff --git a/.git-hooks/commit-msg.mts b/.git-hooks/commit-msg.mts
new file mode 100755
index 0000000..08ae53a
--- /dev/null
+++ b/.git-hooks/commit-msg.mts
@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// Socket Security Commit-msg Hook
+//
+// Two responsibilities:
+//   1. Block commits that introduce API keys / .env files (security
+//      layer that runs even when pre-commit is bypassed via
+//      `--no-verify`).
+//   2. Auto-strip AI attribution lines from the commit message before
+//      git records the commit.
+//
+// Wired via .husky/commit-msg, which invokes this with the path to the
+// commit message file as argv[2] (after the script path itself).
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+
+import { basename } from 'node:path'
+import process from 'node:process'
+
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+
+import {
+  gitLines,
+  readFileForScan,
+  scanLinearRefs,
+  scanSocketApiKeys,
+  shouldSkipFile,
+  stripAiAttribution,
+} from './_helpers.mts'
+
+const logger = getDefaultLogger()
+
+const main = (): number => {
+  let errors = 0
+  const committedFiles = gitLines(
+    'diff',
+    '--cached',
+    '--name-only',
+    '--diff-filter=ACM',
+  )
+
+  for (const file of committedFiles) {
+    if (!file || shouldSkipFile(file)) {
+      continue
+    }
+    const text = readFileForScan(file)
+    if (!text) {
+      continue
+    }
+
+    // Socket API keys (allowlist-aware).
+    const apiHits = scanSocketApiKeys(text)
+    if (apiHits.length > 0) {
+      logger.fail('Potential API key detected in commit!')
+      logger.info(`File: ${file}`)
+      errors++
+    }
+
+    // .env files at any depth — allow only .env.example, .env.test,
+    // .env.precommit (templates / tracked placeholders).
+    const base = basename(file)
+    if (
+      /^\.env(\.[^/]+)?$/.test(base) &&
+      !/^\.env\.(example|test|precommit)$/.test(base)
+    ) {
+      logger.fail('.env file in commit!')
+      logger.info(`File: ${file}`)
+      errors++
+    }
+  }
+
+  // Block Linear issue references in the commit message. Linear
+  // tracking lives in Linear; commit history stays tool-agnostic. The
+  // canonical CLAUDE.md "public-surface hygiene" block documents the
+  // policy; this hook makes it mechanical so a typo in a hot rebase
+  // can't slip through.
+  const commitMsgFile = process.argv[2]
+  if (commitMsgFile && existsSync(commitMsgFile)) {
+    const original = readFileSync(commitMsgFile, 'utf8')
+    const linearHits = scanLinearRefs(original)
+    if (linearHits.length > 0) {
+      logger.fail('Commit message references Linear issue(s):')
+      for (const ref of linearHits) {
+        logger.info(`  ${ref}`)
+      }
+      logger.info(
+        'Linear tracking lives in Linear. Remove the reference from the commit message.',
+      )
+      errors++
+    }
+
+    // Auto-strip AI attribution lines from the commit message.
+    const { cleaned, removed } = stripAiAttribution(original)
+    if (removed > 0) {
+      writeFileSync(commitMsgFile, cleaned)
+      logger.success(
+        `Auto-stripped ${removed} AI attribution line(s) from commit message`,
+      )
+    }
+  }
+
+  if (errors > 0) {
+    logger.fail('Commit blocked by security validation')
+    return 1
+  }
+  return 0
+}
+
+process.exit(main())
diff --git a/.git-hooks/pre-commit.mts b/.git-hooks/pre-commit.mts
new file mode 100755
index 0000000..0ebb454
--- /dev/null
+++ b/.git-hooks/pre-commit.mts
@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+// Socket Security Pre-commit Hook
+//
+// Local-defense layer: scans staged files for sensitive content
+// before git records the commit. Mandatory enforcement re-runs in
+// pre-push for the final gate.
+//
+// Bypassable: --no-verify skips this hook entirely. Use sparingly
+// (hotfixes, history operations, pre-build states).
+
+import { basename } from 'node:path'
+import process from 'node:process'
+
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+
+import {
+  gitLines,
+  normalizePath,
+  readFileForScan,
+  scanAwsKeys,
+  scanCrossRepoPaths,
+  scanGitHubTokens,
+  scanLoggerLeaks,
+  scanNpxDlx,
+  scanPersonalPaths,
+  scanPrivateKeys,
+  scanSocketApiKeys,
+  shouldSkipFile,
+  socketHookMarkerFor,
+} from './_helpers.mts'
+
+const logger = getDefaultLogger()
+
+const main = (): number => {
+  logger.info('Running Socket Security checks...')
+  // Normalize to POSIX forward slashes so downstream
+  // `startsWith('.git-hooks/')` / `includes('/external/')` matchers
+  // work the same on Windows (where git can return `\` separators).
+  const stagedFiles = gitLines(
+    'diff',
+    '--cached',
+    '--name-only',
+    '--diff-filter=ACM',
+  ).map(normalizePath)
+  if (stagedFiles.length === 0) {
+    logger.success('No files to check')
+    return 0
+  }
+
+  let errors = 0
+
+  // .DS_Store files.
+  logger.info('Checking for .DS_Store files...')
+  const dsStores = stagedFiles.filter(f => f.includes('.DS_Store'))
+  if (dsStores.length > 0) {
+    logger.fail('.DS_Store file detected!')
+    dsStores.forEach(f => logger.info(f))
+    errors++
+  }
+
+  // Log files (ignore test logs).
+  logger.info('Checking for log files...')
+  const logs = stagedFiles.filter(
+    f => f.endsWith('.log') && !/test.*\.log$/.test(f),
+  )
+  if (logs.length > 0) {
+    logger.fail('Log file detected!')
+    logs.forEach(f => logger.info(f))
+    errors++
+  }
+
+  // .env files at any depth — allow only .env.example, .env.test,
+  // .env.precommit (templates / tracked placeholders). Match the
+  // commit-msg.mts behavior: a nested .env.local is just as much a
+  // leak as a root-level one. basename() catches both.
+  logger.info('Checking for .env files...')
+  const envFiles = stagedFiles.filter(f => {
+    const base = basename(f)
+    return (
+      /^\.env(\.[^/]+)?$/.test(base) &&
+      !/^\.env\.(example|test|precommit)$/.test(base)
+    )
+  })
+  if (envFiles.length > 0) {
+    logger.fail('.env file detected!')
+    envFiles.forEach(f => logger.info(f))
+    logger.info(
+      'These files should never be committed. Use .env.example for templates.',
+    )
+    errors++
+  }
+
+  // Hardcoded personal paths.
+  logger.info('Checking for hardcoded personal paths...')
+  for (const file of stagedFiles) {
+    if (shouldSkipFile(file)) {
+      continue
+    }
+    const text = readFileForScan(file)
+    if (!text) {
+      continue
+    }
+    const hits = scanPersonalPaths(text)
+    if (hits.length > 0) {
+      logger.fail(`Hardcoded personal path found in: ${file}`)
+      for (const h of hits.slice(0, 3)) {
+        logger.info(`${h.lineNumber}: ${h.line.trim()}`)
+        if (h.suggested && h.suggested !== h.line) {
+          logger.info(`     fix: ${h.suggested.trim()}`)
+        }
+      }
+      logger.info(
+        'Replace with the canonical placeholder for the path platform: ' +
+          '`/Users/<user>/...` (macOS), `/home/<user>/...` (Linux), or ' +
+          '`C:\\Users\\<USERNAME>\\...` (Windows). Env vars also work ' +
+          '(`$HOME`, `${USER}`). For documentation lines that need the ' +
+          `literal form, append the marker \`${socketHookMarkerFor(file, 'personal-path')}\`.`,
+      )
+      errors++
+    }
+  }
+
+  // Socket API keys (warning, not blocking).
+  logger.info('Checking for API keys...')
+  for (const file of stagedFiles) {
+    if (shouldSkipFile(file)) {
+      continue
+    }
+    const text = readFileForScan(file)
+    if (!text) {
+      continue
+    }
+    const hits = scanSocketApiKeys(text)
+    if (hits.length > 0) {
+      logger.warn(`Potential API key found in: ${file}`)
+      hits
+        .slice(0, 3)
+        .forEach(h => logger.info(`${h.lineNumber}:${h.line.trim()}`))
+      logger.info('If this is a real API key, DO NOT COMMIT IT.')
+    }
+  }
+
+  // Other secret patterns (AWS, GitHub, private keys).
+  logger.info('Checking for potential secrets...')
+  for (const file of stagedFiles) {
+    if (shouldSkipFile(file)) {
+      continue
+    }
+    const text = readFileForScan(file)
+    if (!text) {
+      continue
+    }
+
+    const aws = scanAwsKeys(text)
+    if (aws.length > 0) {
+      logger.fail(`Potential AWS credentials found in: ${file}`)
+      aws
+        .slice(0, 3)
+        .forEach(h => logger.info(`${h.lineNumber}:${h.line.trim()}`))
+      errors++
+    }
+
+    const gh = scanGitHubTokens(text)
+    if (gh.length > 0) {
+      logger.fail(`Potential GitHub token found in: ${file}`)
+      gh.slice(0, 3).forEach(h =>
+        logger.info(`${h.lineNumber}:${h.line.trim()}`),
+      )
+      errors++
+    }
+
+    const pk = scanPrivateKeys(text)
+    if (pk.length > 0) {
+      logger.fail(`Private key found in: ${file}`)
+      errors++
+    }
+  }
+
+  // npx/dlx usage.
+  logger.info('Checking for npx/dlx usage...')
+  for (const file of stagedFiles) {
+    // shouldSkipFile covers tests, fixtures, .git-hooks, etc. — test
+    // files frequently mention `npx` as part of fixture paths or
+    // resolution-logic test cases (see socket-lib/test/unit/bin.test.mts).
+    if (shouldSkipFile(file)) {
+      continue
+    }
+    if (
+      file.endsWith('pnpm-lock.yaml') ||
+      // CHANGELOG entries discuss npx ecosystem *behavior* (cache
+      // semantics, naming conventions) as historical documentation —
+      // they're not commands. Skip the npx/dlx scan for changelogs.
+      file === 'CHANGELOG.md' ||
+      file.endsWith('/CHANGELOG.md')
+    ) {
+      continue
+    }
+    const text = readFileForScan(file)
+    if (!text) {
+      continue
+    }
+    const hits = scanNpxDlx(text)
+    if (hits.length > 0) {
+      logger.fail(`npx/dlx usage found in: ${file}`)
+      for (const h of hits.slice(0, 3)) {
+        logger.info(`${h.lineNumber}: ${h.line.trim()}`)
+        if (h.suggested && h.suggested !== h.line) {
+          logger.info(`     fix: ${h.suggested.trim()}`)
+        }
+      }
+      logger.info(
+        "Use 'pnpm exec <package>' or 'pnpm run <script>' instead. For " +
+          'documentation lines that need the literal `npx` form, append ' +
+          `the marker \`${socketHookMarkerFor(file, 'npx')}\`.`,
+      )
+      errors++
+    }
+  }
+
+  // Direct stream writes (process.stderr.write, process.stdout.write,
+  // console.*) in source files. Source code uses getDefaultLogger()
+  // from @socketsecurity/lib/logger; the logger-guard PreToolUse hook
+  // catches these at edit time, this gate catches them at commit time
+  // for edits made outside Claude.
+  logger.info('Checking for direct stream writes...')
+  for (const file of stagedFiles) {
+    if (shouldSkipFile(file)) {
+      continue
+    }
+    // Apply the same exempt set as the logger-guard hook so the rule
+    // is consistent: hooks, git-hooks, scripts, vendored / external
+    // sources are allowed. The shouldSkipFile helper covers tests and
+    // fixtures already.
+    if (
+      file.startsWith('.claude/hooks/') ||
+      file.startsWith('.git-hooks/') ||
+      file.startsWith('scripts/') ||
+      file.includes('/external/') ||
+      file.includes('/vendor/') ||
+      file.includes('/upstream/')
+    ) {
+      continue
+    }
+    if (!/\.(m?ts|tsx|cts)$/.test(file)) {
+      continue
+    }
+    const text = readFileForScan(file)
+    if (!text) {
+      continue
+    }
+    const hits = scanLoggerLeaks(text)
+    if (hits.length > 0) {
+      logger.fail(`direct stream write found in: ${file}`)
+      for (const h of hits.slice(0, 3)) {
+        logger.info(`${h.lineNumber}: ${h.line.trim()}`)
+        if (h.suggested && h.suggested !== h.line) {
+          logger.info(`     fix: ${h.suggested.trim()}`)
+        }
+      }
+      logger.info(
+        'Use `getDefaultLogger()` from `@socketsecurity/lib/logger`. ' +
+          'For documentation lines that need the literal call, append ' +
+          `the marker \`${socketHookMarkerFor(file, 'logger')}\`.`,
+      )
+      errors++
+    }
+  }
+
+  // Cross-repo path references — `../<fleet-repo>/…` (relative escape
+  // out of the current repo) or `…/projects/<fleet-repo>/…` (absolute
+  // sibling-clone escape). Both forms hardcode someone's local layout
+  // and break in CI / fresh clones / non-standard checkouts.
+  logger.info('Checking for cross-repo path references...')
+  // Best-effort current repo name from the toplevel directory; if git
+  // isn't reachable we simply don't suppress own-repo matches.
+  const repoTopline = gitLines('rev-parse', '--show-toplevel')[0] ?? ''
+  const currentRepoName = repoTopline ? basename(repoTopline) : undefined
+  for (const file of stagedFiles) {
+    if (shouldSkipFile(file)) {
+      continue
+    }
+    // Don't scan the hook source itself (it lists fleet repo names by
+    // necessity), the canonical CLAUDE.md fleet block (which documents
+    // fleet repos), or vendored upstream sources.
+    if (
+      file.startsWith('.git-hooks/') ||
+      file.startsWith('.claude/hooks/') ||
+      file.endsWith('CLAUDE.md') ||
+      file.includes('/external/') ||
+      file.includes('/vendor/') ||
+      file.includes('/upstream/') ||
+      file === 'pnpm-lock.yaml' ||
+      file === 'pnpm-workspace.yaml'
+    ) {
+      continue
+    }
+    const text = readFileForScan(file)
+    if (!text) {
+      continue
+    }
+    const hits = scanCrossRepoPaths(text, currentRepoName)
+    if (hits.length > 0) {
+      logger.fail(`cross-repo path reference found in: ${file}`)
+      for (const h of hits.slice(0, 3)) {
+        logger.info(`${h.lineNumber}: ${h.line.trim()}`)
+      }
+      logger.info(
+        'Cross-repo paths (`../<fleet-repo>/…` or absolute `…/projects/<fleet-repo>/…`) ' +
+          'are forbidden — they assume sibling-clone layout and break in CI / fresh clones. ' +
+          'Import via the published npm package instead (`@socketsecurity/lib/<subpath>`, ' +
+          `\`@socketsecurity/registry/<subpath>\`). For documentation lines that need the ` +
+          `literal path, append the marker \`${socketHookMarkerFor(file, 'cross-repo')}\`.`,
+      )
+      errors++
+    }
+  }
+
+  if (errors > 0) {
+    logger.error('')
+    logger.fail(`Security check failed with ${errors} error(s).`)
+    logger.error('Fix the issues above and try again.')
+    return 1
+  }
+
+  logger.success('All security checks passed!')
+  return 0
+}
+
+process.exit(main())
diff --git a/.git-hooks/pre-push.mts b/.git-hooks/pre-push.mts
new file mode 100755
index 0000000..946ecba
--- /dev/null
+++ b/.git-hooks/pre-push.mts
@@ -0,0 +1,428 @@
+#!/usr/bin/env node
+// Socket Security Pre-push Hook
+//
+// Mandatory enforcement layer for all pushes. Validates commits
+// being pushed for AI attribution, secrets, and personal-path leaks.
+//
+// Architecture:
+//   .husky/pre-push (thin wrapper) → node .git-hooks/pre-push.mts
+//
+// Range logic:
+//   New branch:  remote/<default_branch>..<local_sha>  (only new commits)
+//   Existing:    <remote_sha>..<local_sha>             (only new commits)
+//   We never use release tags — that would re-scan already-merged history.
+//
+// Stdin format (provided by git): one push line per ref, each line:
+//   <local_ref> <local_sha> <remote_ref> <remote_sha>
+
+import { spawnSync } from 'node:child_process'
+import { existsSync, statSync } from 'node:fs'
+
+import { basename } from 'node:path'
+import process from 'node:process'
+
+import { errorMessage } from '@socketsecurity/lib/errors'
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+
+import {
+  containsAiAttribution,
+  git,
+  gitLines,
+  readFileForScan,
+  normalizePath,
+  scanAwsKeys,
+  scanCrossRepoPaths,
+  scanGitHubTokens,
+  scanLoggerLeaks,
+  scanPersonalPaths,
+  scanPrivateKeys,
+  scanSocketApiKeys,
+  shouldSkipFile,
+  socketHookMarkerFor,
+  splitLines,
+} from './_helpers.mts'
+
+const logger = getDefaultLogger()
+
+const ZERO_SHA = '0000000000000000000000000000000000000000'
+
+const readStdin = (): Promise<string> =>
+  new Promise(resolve => {
+    let buf = ''
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', chunk => {
+      buf += chunk
+    })
+    process.stdin.on('end', () => resolve(buf))
+  })
+
+// Submodule pristine check — refuses push if any submodule has a
+// drifted commit pointer or unresolved merge conflict.
+const checkSubmodules = (): number => {
+  if (!existsSync('.gitmodules')) {
+    return 0
+  }
+  logger.info('Checking submodules are pristine...')
+  let errors = 0
+  const status = gitLines('submodule', 'status')
+  for (const line of status) {
+    if (!line) {
+      continue
+    }
+    const prefix = line[0]
+    const rest = line.slice(1).trim().split(/\s+/)
+    const smPath = rest[1] || '<unknown>'
+    if (prefix === '+') {
+      logger.fail(`Submodule has wrong commit: ${smPath}`)
+      logger.info(`  Run: git submodule update --init ${smPath}`)
+      errors++
+    } else if (prefix === 'U') {
+      logger.fail(`Submodule has merge conflict: ${smPath}`)
+      errors++
+    }
+    // '-' (uninitialized) is OK — CI shallow clones skip submodules.
+  }
+  if (errors > 0) {
+    logger.error('')
+    logger.fail(`Push blocked: ${errors} submodule(s) not pristine!`)
+    logger.error('Fix submodules before pushing.')
+    return errors
+  }
+  logger.success('All submodules pristine')
+  return 0
+}
+
+// Computes the commit range to scan. Returns null if no scan needed
+// (skip case — tag, delete, or no baseline).
+const computeRange = (
+  remote: string,
+  localRef: string,
+  localSha: string,
+  remoteSha: string,
+): string | null => {
+  if (localRef.startsWith('refs/tags/')) {
+    logger.info(`Skipping tag push: ${localRef}`)
+    return null
+  }
+  if (localSha === ZERO_SHA) {
+    return null
+  }
+
+  const defaultBranchOf = (remoteName: string): string => {
+    const sym = git('symbolic-ref', `refs/remotes/${remoteName}/HEAD`).trim()
+    if (sym) {
+      return sym.replace(`refs/remotes/${remoteName}/`, '')
+    }
+    return 'main'
+  }
+
+  // git cat-file -e exits 0 silently on success; spawnSync directly
+  // so we can inspect status without printing.
+  const remoteShaExists = (sha: string): boolean => {
+    const result = spawnSync('git', ['cat-file', '-e', sha])
+    return result.status === 0
+  }
+
+  const refExists = (ref: string): boolean => {
+    const r = spawnSync('git', ['rev-parse', ref])
+    return r.status === 0
+  }
+
+  if (remoteSha === ZERO_SHA) {
+    // New branch — compare against remote default branch.
+    const def = defaultBranchOf(remote)
+    const baseRef = `${remote}/${def}`
+    if (!refExists(baseRef)) {
+      logger.success('Skipping validation (no baseline to compare against)')
+      return null
+    }
+    return `${baseRef}..${localSha}`
+  }
+
+  // Existing branch.
+  if (!remoteShaExists(remoteSha)) {
+    // Force-push or history rewrite — fall back to default branch.
+    const def = defaultBranchOf(remote)
+    const baseRef = `${remote}/${def}`
+    if (!refExists(baseRef)) {
+      logger.success('Skipping validation (no baseline for force-push)')
+      return null
+    }
+    return `${baseRef}..${localSha}`
+  }
+  return `${remoteSha}..${localSha}`
+}
+
+// Scans every commit in the range for AI attribution in commit
+// messages.
+const scanCommitMessages = (range: string): number => {
+  logger.info('Checking commit messages for AI attribution...')
+  const shas = gitLines('rev-list', range)
+  let errors = 0
+  for (const sha of shas) {
+    if (!sha) {
+      continue
+    }
+    const msg = git('log', '-1', '--format=%B', sha)
+    if (containsAiAttribution(msg)) {
+      if (errors === 0) {
+        logger.fail('AI attribution found in commit messages!')
+        logger.info('Commits with AI attribution:')
+      }
+      const oneline = git('log', '-1', '--oneline', sha)
+      logger.info(`  - ${oneline}`)
+      errors++
+    }
+  }
+  if (errors > 0) {
+    logger.info('')
+    logger.info(
+      'These commits were likely created with --no-verify, bypassing the',
+    )
+    logger.info('commit-msg hook that strips AI attribution.')
+    logger.info('')
+    const rangeBase = range.split('..')[0]
+    logger.info('To fix:')
+    logger.info(`  git rebase -i ${rangeBase}`)
+    logger.info("  Mark commits as 'reword', remove AI attribution, save")
+    logger.info('  git push')
+  }
+  return errors
+}
+
+// Scans changed files in the range for secrets, keys, and leaks.
+const scanFilesInRange = (range: string): number => {
+  logger.info('Checking files for security issues...')
+  // Normalize to POSIX forward slashes — same reason as pre-commit.mts.
+  const changed = gitLines('diff', '--name-only', range).map(normalizePath)
+  let errors = 0
+  if (changed.length === 0) {
+    return 0
+  }
+  // Best-effort current repo name — used by cross-repo scanner to
+  // avoid flagging a repo's own paths.
+  const repoTopline = gitLines('rev-parse', '--show-toplevel')[0] ?? ''
+  const currentRepoName = repoTopline ? basename(repoTopline) : undefined
+
+  // .env files at any depth — match commit-msg.mts and pre-commit.mts.
+  // Allow .env.example, .env.test, .env.precommit (templates / tracked
+  // placeholders); block bare .env / .env.local / .env.production /
+  // anything else regardless of directory depth.
+  const envHits = changed.filter(f => {
+    const base = basename(f)
+    return (
+      /^\.env(\.[^/]+)?$/.test(base) &&
+      !/^\.env\.(example|test|precommit)$/.test(base)
+    )
+  })
+  if (envHits.length > 0) {
+    logger.fail('Attempting to push .env file!')
+    logger.info(`Files: ${envHits.join(', ')}`)
+    errors += envHits.length
+  }
+  const dsHits = changed.filter(f => f.includes('.DS_Store'))
+  if (dsHits.length > 0) {
+    logger.fail('.DS_Store file in push!')
+    logger.info(`Files: ${dsHits.join(', ')}`)
+    errors += dsHits.length
+  }
+  const logHits = changed.filter(
+    f => f.endsWith('.log') && !/test.*\.log$/.test(f),
+  )
+  if (logHits.length > 0) {
+    logger.fail('Log file in push!')
+    logger.info(`Files: ${logHits.join(', ')}`)
+    errors += logHits.length
+  }
+
+  // Per-file content scans.
+  for (const file of changed) {
+    if (!file || !existsSync(file)) {
+      continue
+    }
+    try {
+      if (statSync(file).isDirectory()) {
+        continue
+      }
+    } catch {
+      continue
+    }
+    if (shouldSkipFile(file)) {
+      continue
+    }
+    // Tracked-only — skip files removed from git that still exist on disk.
+    const tracked = spawnSync('git', ['ls-files', '--error-unmatch', file])
+    if (tracked.status !== 0) {
+      continue
+    }
+
+    const text = readFileForScan(file)
+    if (!text) {
+      continue
+    }
+
+    const pathHits = scanPersonalPaths(text)
+    if (pathHits.length > 0) {
+      logger.fail(`Hardcoded personal path found in: ${file}`)
+      for (const h of pathHits.slice(0, 3)) {
+        logger.info(`${h.lineNumber}: ${h.line.trim()}`)
+        if (h.suggested && h.suggested !== h.line) {
+          logger.info(`     fix: ${h.suggested.trim()}`)
+        }
+      }
+      logger.info(
+        'Replace with the canonical placeholder for the path platform: ' +
+          '`/Users/<user>/...` (macOS), `/home/<user>/...` (Linux), or ' +
+          '`C:\\Users\\<USERNAME>\\...` (Windows). Env vars also work ' +
+          '(`$HOME`, `${USER}`). For documentation lines that need the ' +
+          `literal form, append the marker \`${socketHookMarkerFor(file, 'personal-path')}\`.`,
+      )
+      errors++
+    }
+
+    const apiHits = scanSocketApiKeys(text)
+    if (apiHits.length > 0) {
+      logger.fail(`Real API key detected in: ${file}`)
+      apiHits
+        .slice(0, 3)
+        .forEach(h => logger.info(`${h.lineNumber}:${h.line.trim()}`))
+      errors++
+    }
+
+    const awsHits = scanAwsKeys(text)
+    if (awsHits.length > 0) {
+      logger.fail(`Potential AWS credentials found in: ${file}`)
+      awsHits
+        .slice(0, 3)
+        .forEach(h => logger.info(`${h.lineNumber}:${h.line.trim()}`))
+      errors++
+    }
+
+    const ghHits = scanGitHubTokens(text)
+    if (ghHits.length > 0) {
+      logger.fail(`Potential GitHub token found in: ${file}`)
+      ghHits
+        .slice(0, 3)
+        .forEach(h => logger.info(`${h.lineNumber}:${h.line.trim()}`))
+      errors++
+    }
+
+    const pkHits = scanPrivateKeys(text)
+    if (pkHits.length > 0) {
+      logger.fail(`Private key found in: ${file}`)
+      errors++
+    }
+
+    if (
+      !file.startsWith('.claude/hooks/') &&
+      !file.startsWith('.git-hooks/') &&
+      !file.startsWith('scripts/') &&
+      !file.includes('/external/') &&
+      !file.includes('/vendor/') &&
+      !file.includes('/upstream/') &&
+      /\.(m?ts|tsx|cts)$/.test(file)
+    ) {
+      const loggerHits = scanLoggerLeaks(text)
+      if (loggerHits.length > 0) {
+        logger.fail(`direct stream write found in: ${file}`)
+        for (const h of loggerHits.slice(0, 3)) {
+          logger.info(`${h.lineNumber}: ${h.line.trim()}`)
+          if (h.suggested && h.suggested !== h.line) {
+            logger.info(`     fix: ${h.suggested.trim()}`)
+          }
+        }
+        logger.info(
+          'Use `getDefaultLogger()` from `@socketsecurity/lib/logger`. ' +
+            'For documentation lines that need the literal call, append ' +
+            `the marker \`${socketHookMarkerFor(file, 'logger')}\`.`,
+        )
+        errors++
+      }
+    }
+
+    // Cross-repo path references — both relative (`../<fleet-repo>/…`)
+    // and absolute (`…/projects/<fleet-repo>/…`) forms.
+    if (
+      !file.startsWith('.git-hooks/') &&
+      !file.startsWith('.claude/hooks/') &&
+      !file.endsWith('CLAUDE.md') &&
+      !file.includes('/external/') &&
+      !file.includes('/vendor/') &&
+      !file.includes('/upstream/') &&
+      file !== 'pnpm-lock.yaml' &&
+      file !== 'pnpm-workspace.yaml'
+    ) {
+      const crossRepoHits = scanCrossRepoPaths(text, currentRepoName)
+      if (crossRepoHits.length > 0) {
+        logger.fail(`cross-repo path reference in: ${file}`)
+        for (const h of crossRepoHits.slice(0, 3)) {
+          logger.info(`${h.lineNumber}: ${h.line.trim()}`)
+        }
+        logger.info(
+          'Cross-repo paths are forbidden — import via the published npm ' +
+            'package (`@socketsecurity/lib/<subpath>`) instead. For doc ' +
+            `lines, append \`${socketHookMarkerFor(file, 'cross-repo')}\`.`,
+        )
+        errors++
+      }
+    }
+  }
+  return errors
+}
+
+const main = async (): Promise<number> => {
+  logger.info('Running mandatory pre-push validation...')
+
+  const submoduleErrors = checkSubmodules()
+  if (submoduleErrors > 0) {
+    return 1
+  }
+
+  const remote = process.argv[2] || 'origin'
+  // url at process.argv[3] is unused.
+
+  const stdin = await readStdin()
+  let totalErrors = 0
+  const refLines = splitLines(stdin.trim()).filter(Boolean)
+
+  for (const refLine of refLines) {
+    const [localRef, localSha, , remoteSha] = refLine.split(/\s+/)
+    if (!localRef || !localSha || !remoteSha) {
+      continue
+    }
+    const range = computeRange(remote, localRef, localSha, remoteSha)
+    if (range === null) {
+      continue
+    }
+    // Validate range.
+    const rl = spawnSync('git', ['rev-list', range], { stdio: 'ignore' })
+    if (rl.status !== 0) {
+      logger.fail(`Invalid commit range: ${range}`)
+      return 1
+    }
+
+    totalErrors += scanCommitMessages(range)
+    totalErrors += scanFilesInRange(range)
+  }
+
+  if (totalErrors > 0) {
+    logger.error('')
+    logger.fail('Push blocked by mandatory validation!')
+    logger.error('Fix the issues above before pushing.')
+    return 1
+  }
+
+  logger.success('All mandatory validation passed!')
+  return 0
+}
+
+// Explicit .catch so a thrown error in main() doesn't become an
+// unhandled rejection — surface the error through the logger so the
+// user sees what blocked the push, then exit 1 intentionally.
+main().then(
+  code => process.exit(code),
+  e => {
+    logger.error(`pre-push: ${errorMessage(e)}`)
+    process.exit(1)
+  },
+)
diff --git a/.git-hooks/test/_helpers.test.mts b/.git-hooks/test/_helpers.test.mts
new file mode 100755
index 0000000..483065d
--- /dev/null
+++ b/.git-hooks/test/_helpers.test.mts
@@ -0,0 +1,584 @@
+/* oxlint-disable socket/no-npx-dlx -- test fixture: asserts on the literal `npx` marker that the hook's bypass detector looks for. */
+
+// node --test specs for .git-hooks/_helpers.mts.
+//
+// Covers the pure-function surface: AI-attribution scanner, marker
+// alias logic, suppression matching, backtick span detection, secret
+// scanners (Personal-paths / Linear / GitHub / AWS / Private-keys),
+// placeholder + replacement suggestion helpers, and the canonical
+// marker emitter. Hook entry points (commit-msg / pre-commit /
+// pre-push) have their own .test.mts files that exercise stdin/stdout
+// against a temp git repo.
+
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  aliasMatches,
+  containsAiAttribution,
+  filterAllowedApiKeys,
+  gitOrThrow,
+  isInsideBackticks,
+  lineIsSuppressed,
+  looksLikeDocumentation,
+  normalizePath,
+  scanAwsKeys,
+  scanCrossRepoPaths,
+  scanGitHubTokens,
+  scanLinearRefs,
+  scanPersonalPaths,
+  scanPrivateKeys,
+  scanSocketApiKeys,
+  socketHookMarkerFor,
+  splitLines,
+  stripAiAttribution,
+  suggestLoggerReplacement,
+  suggestNpxReplacement,
+  suggestPlaceholder,
+} from '../_helpers.mts'
+
+// ── containsAiAttribution ─────────────────────────────────────────
+
+test('containsAiAttribution: catches "Generated with Claude"', () => {
+  assert.strictEqual(containsAiAttribution('Generated with Claude Code'), true)
+  assert.strictEqual(containsAiAttribution('Generated with AI'), true)
+})
+
+test('containsAiAttribution: catches "Co-Authored-By:" tags', () => {
+  assert.strictEqual(
+    containsAiAttribution('Co-Authored-By: Claude <noreply@anthropic.com>'),
+    true,
+  )
+  assert.strictEqual(containsAiAttribution('Co-Authored-By: AI'), true)
+})
+
+test('containsAiAttribution: catches alternative attribution verbs', () => {
+  for (const verb of [
+    'Built',
+    'Created',
+    'Made',
+    'Written',
+    'Authored',
+    'Powered',
+    'Crafted',
+  ]) {
+    assert.strictEqual(
+      containsAiAttribution(`${verb} with Claude`),
+      true,
+      `${verb} with Claude should match`,
+    )
+    assert.strictEqual(
+      containsAiAttribution(`${verb} by Claude`),
+      true,
+      `${verb} by Claude should match`,
+    )
+  }
+})
+
+test('containsAiAttribution: catches alternative agent names', () => {
+  for (const agent of [
+    'Claude',
+    'AI',
+    'GPT',
+    'ChatGPT',
+    'Copilot',
+    'Cursor',
+    'Bard',
+    'Gemini',
+  ]) {
+    assert.strictEqual(
+      containsAiAttribution(`Generated by ${agent}`),
+      true,
+      `Generated by ${agent} should match`,
+    )
+  }
+})
+
+test('containsAiAttribution: catches emoji + email + line-start markers', () => {
+  assert.strictEqual(containsAiAttribution('🤖 Generated by foo'), true)
+  assert.strictEqual(containsAiAttribution('AI generated'), true)
+  assert.strictEqual(containsAiAttribution('AI-generated'), true)
+  assert.strictEqual(containsAiAttribution('Machine generated'), true)
+  assert.strictEqual(containsAiAttribution('Machine-generated'), true)
+  assert.strictEqual(containsAiAttribution('user@anthropic.com'), true)
+  assert.strictEqual(containsAiAttribution('user@openai.com'), true)
+  assert.strictEqual(containsAiAttribution('Assistant: hello'), true)
+  assert.strictEqual(
+    containsAiAttribution('line1\nAssistant: hello'),
+    true,
+    'multi-line: Assistant: at line start',
+  )
+})
+
+test('containsAiAttribution: ignores legitimate product/prose mentions', () => {
+  // The regression that prompted the fix: bare "Claude Code" or
+  // "Claude" in prose without an attribution verb must NOT trigger.
+  assert.strictEqual(
+    containsAiAttribution(
+      "Catches the failure mode where CLAUDE.md grows past Claude Code's warning threshold",
+    ),
+    false,
+  )
+  assert.strictEqual(
+    containsAiAttribution(
+      'Adds two PreToolUse hooks that enforce the fleet "Allow X bypass" phrase policy',
+    ),
+    false,
+  )
+  assert.strictEqual(
+    containsAiAttribution('See .claude/hooks/no-revert-guard for details'),
+    false,
+  )
+  assert.strictEqual(
+    containsAiAttribution('the assistant returned an error'),
+    false,
+    'lowercase "assistant" mid-line should not match',
+  )
+  assert.strictEqual(
+    containsAiAttribution('using the Claude Sonnet 4.6 model'),
+    false,
+    'model-name reference should not match',
+  )
+})
+
+// ── stripAiAttribution ────────────────────────────────────────────
+
+test('stripAiAttribution: removes only attribution lines', () => {
+  const input = [
+    'feat(auth): add login flow',
+    '',
+    'Implements the OAuth callback handler.',
+    '',
+    'Co-Authored-By: Claude <noreply@anthropic.com>',
+    '🤖 Generated with Claude Code',
+  ].join('\n')
+  const { cleaned, removed } = stripAiAttribution(input)
+  assert.strictEqual(removed, 2)
+  assert.match(cleaned, /feat\(auth\): add login flow/)
+  assert.match(cleaned, /Implements the OAuth callback handler\./)
+  assert.doesNotMatch(cleaned, /Co-Authored-By/)
+  assert.doesNotMatch(cleaned, /🤖/)
+})
+
+test('stripAiAttribution: keeps prose mentioning Claude in context', () => {
+  const input = [
+    'fix(hooks): tighten Claude Code marker handling',
+    '',
+    'See .claude/hooks/ for the canonical hook layout.',
+  ].join('\n')
+  const { cleaned, removed } = stripAiAttribution(input)
+  assert.strictEqual(removed, 0)
+  assert.strictEqual(cleaned, input)
+})
+
+// ── aliasMatches ──────────────────────────────────────────────────
+
+test('aliasMatches: identity match', () => {
+  assert.strictEqual(aliasMatches('console', 'console'), true)
+  assert.strictEqual(aliasMatches('npx', 'npx'), true)
+})
+
+test('aliasMatches: legacy logger → console alias', () => {
+  assert.strictEqual(aliasMatches('logger', 'console'), true)
+  assert.strictEqual(aliasMatches('console', 'logger'), true)
+})
+
+test('aliasMatches: unrelated names do not match', () => {
+  assert.strictEqual(aliasMatches('console', 'npx'), false)
+  assert.strictEqual(aliasMatches('foo', 'bar'), false)
+})
+
+// ── lineIsSuppressed ──────────────────────────────────────────────
+
+test('lineIsSuppressed: bare marker = blanket allow', () => {
+  assert.strictEqual(
+    lineIsSuppressed('console.log("x") // socket-hook: allow', 'console'),
+    true,
+  )
+  assert.strictEqual(lineIsSuppressed('foo() // socket-hook: allow'), true)
+})
+
+test('lineIsSuppressed: rule-named marker matches the named rule', () => {
+  assert.strictEqual(
+    lineIsSuppressed(
+      'console.log("x") // socket-hook: allow console',
+      'console',
+    ),
+    true,
+  )
+  assert.strictEqual(
+    lineIsSuppressed('console.log("x") // socket-hook: allow npx', 'console'),
+    false,
+    'npx marker does NOT suppress console rule',
+  )
+})
+
+test('lineIsSuppressed: alias-named marker also matches', () => {
+  // legacy `allow logger` still suppresses the console rule
+  assert.strictEqual(
+    lineIsSuppressed(
+      'console.log("x") // socket-hook: allow logger',
+      'console',
+    ),
+    true,
+  )
+})
+
+test('lineIsSuppressed: returns false when no marker', () => {
+  assert.strictEqual(lineIsSuppressed('console.log("x")', 'console'), false)
+})
+
+// ── isInsideBackticks ─────────────────────────────────────────────
+
+test('isInsideBackticks: pattern entirely within span', () => {
+  assert.strictEqual(
+    isInsideBackticks('use the `npx` command', /\bnpx\b/),
+    true,
+  )
+})
+
+test('isInsideBackticks: pattern only outside span', () => {
+  assert.strictEqual(
+    isInsideBackticks('npx is `something else`', /\bnpx\b/),
+    false,
+  )
+})
+
+test('isInsideBackticks: no spans → false', () => {
+  assert.strictEqual(isInsideBackticks('plain text', /\bnpx\b/), false)
+})
+
+// ── looksLikeDocumentation ────────────────────────────────────────
+
+test('looksLikeDocumentation: comment lines pass as docs', () => {
+  assert.strictEqual(
+    looksLikeDocumentation('// uses npx for the build', /\bnpx\b/),
+    true,
+  )
+  assert.strictEqual(
+    looksLikeDocumentation(' * runs npx in CI', /\bnpx\b/),
+    true,
+  )
+  assert.strictEqual(
+    looksLikeDocumentation('# npx documentation', /\bnpx\b/),
+    true,
+  )
+})
+
+test('looksLikeDocumentation: JSDoc tag lines pass as docs', () => {
+  assert.strictEqual(
+    looksLikeDocumentation('@example npx prettier', /\bnpx\b/),
+    true,
+  )
+})
+
+test('looksLikeDocumentation: backtick-only mentions pass', () => {
+  assert.strictEqual(
+    looksLikeDocumentation('use `npx` instead', /\bnpx\b/),
+    true,
+  )
+})
+
+test('looksLikeDocumentation: bare runtime call does not pass', () => {
+  assert.strictEqual(
+    looksLikeDocumentation('npx prettier --write', /\bnpx\b/),
+    false,
+  )
+})
+
+// ── normalizePath ─────────────────────────────────────────────────
+
+test('normalizePath: Windows backslashes → forward slashes', () => {
+  assert.strictEqual(
+    normalizePath('C:\\Users\\jdalton\\project'),
+    'C:/Users/jdalton/project',
+  )
+})
+
+test('normalizePath: POSIX path passes through', () => {
+  assert.strictEqual(
+    normalizePath('/Users/jdalton/project'),
+    '/Users/jdalton/project',
+  )
+})
+
+// ── filterAllowedApiKeys ──────────────────────────────────────────
+
+test('filterAllowedApiKeys: drops fake-token + env-var-name + .example markers', () => {
+  // SOCKET_TOKEN_ENV_NAMES carries the trailing `=` — the filter looks
+  // for the assignment shape, not the bare name in prose.
+  const lines = [
+    'const real = "abc123secretvalueabcdef"',
+    'const fake = "socket-test-fake-token-abc"',
+    'export SOCKET_API_TOKEN=somevalue',
+    'const example = "this is .example fixture data"',
+  ]
+  const filtered = filterAllowedApiKeys(lines)
+  assert.deepStrictEqual(filtered, ['const real = "abc123secretvalueabcdef"'])
+})
+
+test('filterAllowedApiKeys: retains lines without allowlist hits', () => {
+  const lines = ['line one', 'line two']
+  assert.deepStrictEqual(filterAllowedApiKeys(lines), lines)
+})
+
+// ── socketHookMarkerFor ───────────────────────────────────────────
+
+test('socketHookMarkerFor: emits canonical comment for .ts', () => {
+  const marker = socketHookMarkerFor('src/foo.ts', 'console')
+  assert.match(marker, /socket-hook:\s*allow\s+console/)
+})
+
+test('socketHookMarkerFor: chooses comment style by file extension', () => {
+  const py = socketHookMarkerFor('foo.py', 'npx')
+  const yml = socketHookMarkerFor('ci.yml', 'npx')
+  assert.match(py, /^#/)
+  assert.match(yml, /^#/)
+  const ts = socketHookMarkerFor('foo.ts', 'npx')
+  assert.match(ts, /^\/\//)
+})
+
+// ── suggestPlaceholder ────────────────────────────────────────────
+
+test('suggestPlaceholder: rewrites /Users/<name>/ → /Users/<user>/', () => {
+  const out = suggestPlaceholder('const p = "/Users/jdalton/foo.txt"')
+  assert.match(out, /\/Users\/<user>\//)
+})
+
+test('suggestPlaceholder: rewrites C:\\Users\\<name>\\ → C:\\Users\\<USERNAME>\\', () => {
+  // String contains 1 literal backslash per separator: C:\Users\jdalton\Documents
+  const out = suggestPlaceholder('const p = "C:\\Users\\jdalton\\Documents"')
+  assert.match(out, /C:\\Users\\<USERNAME>\\/)
+})
+
+// ── suggestNpxReplacement ─────────────────────────────────────────
+
+test('suggestNpxReplacement: npx → pnpm exec', () => {
+  assert.strictEqual(
+    suggestNpxReplacement('npx prettier --check'),
+    'pnpm exec prettier --check',
+  )
+})
+
+test('suggestNpxReplacement: pnpm dlx → pnpm exec', () => {
+  assert.strictEqual(
+    suggestNpxReplacement('pnpm dlx tsx foo.ts'),
+    'pnpm exec tsx foo.ts',
+  )
+})
+
+test('suggestNpxReplacement: yarn dlx → pnpm exec', () => {
+  assert.strictEqual(
+    suggestNpxReplacement('yarn dlx tsx foo.ts'),
+    'pnpm exec tsx foo.ts',
+  )
+})
+
+test('suggestNpxReplacement: pnx → pnpm exec', () => {
+  assert.strictEqual(
+    suggestNpxReplacement('pnx tsx foo.ts'),
+    'pnpm exec tsx foo.ts',
+  )
+})
+
+test('suggestNpxReplacement: leaves non-dlx commands alone', () => {
+  assert.strictEqual(
+    suggestNpxReplacement('pnpm install --frozen-lockfile'),
+    'pnpm install --frozen-lockfile',
+  )
+})
+
+// ── suggestLoggerReplacement ──────────────────────────────────────
+
+test('suggestLoggerReplacement: console.log → logger.log', () => {
+  const out = suggestLoggerReplacement("console.log('hi')")
+  assert.match(out, /logger\.(log|info)/)
+})
+
+test('suggestLoggerReplacement: console.error → logger.fail', () => {
+  const out = suggestLoggerReplacement("console.error('x')")
+  assert.match(out, /logger\.(fail|error)/)
+})
+
+// ── scanPersonalPaths ─────────────────────────────────────────────
+
+test('scanPersonalPaths: flags real /Users/<name>/ paths', () => {
+  const hits = scanPersonalPaths('const p = "/Users/jdalton/secret.txt"')
+  assert.ok(hits.length > 0)
+  assert.match(hits[0]!.line, /jdalton/)
+})
+
+test('scanPersonalPaths: ignores placeholder /Users/<user>/', () => {
+  const hits = scanPersonalPaths('const p = "/Users/<user>/foo"')
+  assert.strictEqual(hits.length, 0)
+})
+
+test('scanPersonalPaths: ignores Linux placeholder /home/<user>/', () => {
+  const hits = scanPersonalPaths('const p = "/home/<user>/foo"')
+  assert.strictEqual(hits.length, 0)
+})
+
+test('scanPersonalPaths: respects suppression marker', () => {
+  // Canonical rule name is singular: `personal-path`.
+  const hits = scanPersonalPaths(
+    'const p = "/Users/jdalton/foo" // socket-hook: allow personal-path',
+  )
+  assert.strictEqual(hits.length, 0)
+})
+
+test('scanPersonalPaths: bare-allow marker also suppresses', () => {
+  const hits = scanPersonalPaths(
+    'const p = "/Users/jdalton/foo" // socket-hook: allow',
+  )
+  assert.strictEqual(hits.length, 0)
+})
+
+// ── scanLinearRefs ────────────────────────────────────────────────
+
+test('scanLinearRefs: catches enumerated team-key IDs', () => {
+  // SOC- is NOT in the team-key list; ENG-, INFRA-, OPS- are.
+  const hits = scanLinearRefs('Fixes ENG-9999 and INFRA-42 and OPS-7')
+  assert.strictEqual(hits.length, 3)
+  assert.ok(hits.includes('ENG-9999'))
+  assert.ok(hits.includes('INFRA-42'))
+  assert.ok(hits.includes('OPS-7'))
+})
+
+test('scanLinearRefs: ignores unenumerated 3+ letter prefixes', () => {
+  // SOC- and FOO- are not in the team-key list.
+  const hits = scanLinearRefs('Tracking SOC-1234 and FOO-99')
+  assert.strictEqual(hits.length, 0)
+})
+
+test('scanLinearRefs: catches linear.app URLs', () => {
+  const hits = scanLinearRefs('See https://linear.app/socket/issue/SOC-1')
+  assert.ok(hits.length >= 1)
+})
+
+test('scanLinearRefs: respects limit cap', () => {
+  const text = Array.from({ length: 20 }, (_, i) => `SOC-${i}`).join(' ')
+  const hits = scanLinearRefs(text, 3)
+  assert.ok(hits.length <= 3)
+})
+
+test('scanLinearRefs: ignores arbitrary 3-letter prefixes (ABC-)', () => {
+  const hits = scanLinearRefs('issue ABC-123 was filed')
+  assert.strictEqual(hits.length, 0)
+})
+
+test('scanLinearRefs: skips lines that start with #', () => {
+  // Comment-style lines (commit-message comments) are skipped wholesale.
+  const hits = scanLinearRefs('# tracking ENG-1 and ENG-2')
+  assert.strictEqual(hits.length, 0)
+})
+
+// ── scanGitHubTokens / scanAwsKeys / scanPrivateKeys ─────────────
+
+test('scanGitHubTokens: catches ghp_* literal', () => {
+  const hits = scanGitHubTokens(
+    'GITHUB_TOKEN=ghp_abcdefghijklmnopqrstuvwxyzABCDEF1234',
+  )
+  assert.ok(hits.length >= 1)
+})
+
+test('scanGitHubTokens: catches ghs_* literal too', () => {
+  const hits = scanGitHubTokens(
+    'TOKEN=ghs_abcdefghijklmnopqrstuvwxyzABCDEF1234',
+  )
+  assert.ok(hits.length >= 1)
+})
+
+test('scanAwsKeys: catches AKIA literal access key', () => {
+  const hits = scanAwsKeys('AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE')
+  assert.ok(hits.length >= 1)
+})
+
+test('scanPrivateKeys: catches PEM header', () => {
+  const hits = scanPrivateKeys('-----BEGIN RSA PRIVATE KEY-----')
+  assert.ok(hits.length >= 1)
+})
+
+// ── scanSocketApiKeys ─────────────────────────────────────────────
+
+test('scanSocketApiKeys: catches sktsec_ literal', () => {
+  // The line MUST NOT contain the env-var-name shape (`SOCKET_API_TOKEN=`)
+  // or it gets allowlisted as a documented env-name reference.
+  const hits = scanSocketApiKeys('const t = "sktsec_abc123abc123abc123abc123"')
+  assert.ok(hits.length >= 1)
+})
+
+test('scanSocketApiKeys: ignores allowlisted fake-token shape', () => {
+  const hits = scanSocketApiKeys('const t = "socket-test-fake-token-abc"')
+  assert.strictEqual(hits.length, 0)
+})
+
+test('scanSocketApiKeys: env-var-name shape is allowlisted', () => {
+  // The trailing `=` triggers the env-var-name allowlist.
+  const hits = scanSocketApiKeys(
+    'export SOCKET_API_TOKEN=sktsec_realsecretrealsecret',
+  )
+  assert.strictEqual(hits.length, 0)
+})
+
+// ── scanCrossRepoPaths ────────────────────────────────────────────
+
+test('scanCrossRepoPaths: flags ../<other-repo>/ relative escapes', () => {
+  const hits = scanCrossRepoPaths(
+    'import x from "../socket-cli/src/foo"',
+    'src/test.ts',
+  )
+  assert.ok(hits.length >= 1)
+})
+
+test('scanCrossRepoPaths: flags absolute /Users/.../projects/<other-repo>', () => {
+  const hits = scanCrossRepoPaths(
+    'const p = "/Users/jdalton/projects/socket-cli/lib/foo"',
+    'src/test.ts',
+  )
+  assert.ok(hits.length >= 1)
+})
+
+test('scanCrossRepoPaths: allows same-repo relative imports', () => {
+  const hits = scanCrossRepoPaths('import x from "./foo"', 'src/test.ts')
+  assert.strictEqual(hits.length, 0)
+})
+
+// ── splitLines (CRLF normalization) ───────────────────────────────
+
+test('splitLines: LF-only input passes through', () => {
+  assert.deepStrictEqual(splitLines('a\nb\nc'), ['a', 'b', 'c'])
+})
+
+test('splitLines: CRLF input normalizes to LF', () => {
+  assert.deepStrictEqual(splitLines('a\r\nb\r\nc'), ['a', 'b', 'c'])
+})
+
+test('splitLines: mixed CRLF + LF input normalizes', () => {
+  assert.deepStrictEqual(splitLines('a\r\nb\nc\r\nd'), ['a', 'b', 'c', 'd'])
+})
+
+test('splitLines: trailing CRLF produces a trailing empty', () => {
+  assert.deepStrictEqual(splitLines('a\r\n'), ['a', ''])
+})
+
+test('splitLines: standalone \\r is preserved (mac classic — out of scope)', () => {
+  // Modern git / subprocess output is LF or CRLF, never bare CR. We
+  // don't try to normalize CR-only line endings; the helper is a
+  // pragmatic CRLF stripper, not a full line-ending sniffer.
+  assert.deepStrictEqual(splitLines('a\rb'), ['a\rb'])
+})
+
+// ── gitOrThrow ────────────────────────────────────────────────────
+
+test('gitOrThrow: returns stdout on success', () => {
+  // `git --version` works in any environment with git on PATH.
+  const out = gitOrThrow('--version')
+  assert.ok(out.startsWith('git version'), `expected "git version ...", got ${out}`)
+})
+
+test('gitOrThrow: throws on non-zero exit', () => {
+  assert.throws(
+    () => gitOrThrow('this-subcommand-does-not-exist'),
+    /git this-subcommand-does-not-exist:/,
+  )
+})
diff --git a/.git-hooks/test/commit-msg.test.mts b/.git-hooks/test/commit-msg.test.mts
new file mode 100755
index 0000000..ca6d47b
--- /dev/null
+++ b/.git-hooks/test/commit-msg.test.mts
@@ -0,0 +1,78 @@
+// node --test specs for .git-hooks/commit-msg.mts.
+//
+// Smoke tests: spawn the hook with a temp commit-message file and
+// inspect the rewritten file + exit code. The hook strips AI
+// attribution lines and blocks commits that look like they're
+// committing secrets / .env files.
+
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { spawn } from 'node:child_process'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const HOOK = path.join(here, '..', 'commit-msg.mts')
+
+type Result = { code: number; stderr: string }
+
+async function runHook(commitMsg: string): Promise<{
+  result: Result
+  rewrittenMessage: string
+}> {
+  const dir = mkdtempSync(path.join(tmpdir(), 'commit-msg-test-'))
+  const msgFile = path.join(dir, 'COMMIT_EDITMSG')
+  writeFileSync(msgFile, commitMsg)
+  try {
+    const child = spawn(process.execPath, [HOOK, msgFile], { stdio: 'pipe' })
+    let stderr = ''
+    child.stderr.on('data', chunk => {
+      stderr += chunk.toString('utf8')
+    })
+    const result = await new Promise<Result>(resolve => {
+      child.on('exit', code => resolve({ code: code ?? 0, stderr }))
+    })
+    const rewrittenMessage = readFileSync(msgFile, 'utf8')
+    return { result, rewrittenMessage }
+  } finally {
+    rmSync(dir, { force: true, recursive: true })
+  }
+}
+
+test('commit-msg: passes through clean prose', async () => {
+  const { result, rewrittenMessage } = await runHook(
+    'feat(auth): add OAuth callback handler\n\nWires the redirect URI through the new endpoint.\n',
+  )
+  assert.strictEqual(result.code, 0)
+  assert.match(rewrittenMessage, /feat\(auth\): add OAuth callback handler/)
+})
+
+test('commit-msg: strips Co-Authored-By: Claude attribution', async () => {
+  const { result, rewrittenMessage } = await runHook(
+    'feat: ship feature\n\nCo-Authored-By: Claude <noreply@anthropic.com>\n',
+  )
+  assert.strictEqual(result.code, 0)
+  assert.doesNotMatch(rewrittenMessage, /Co-Authored-By: Claude/)
+  assert.match(rewrittenMessage, /feat: ship feature/)
+})
+
+test('commit-msg: strips 🤖 emoji attribution line', async () => {
+  const { result, rewrittenMessage } = await runHook(
+    'fix: bug\n\n🤖 Generated with Claude Code\n',
+  )
+  assert.strictEqual(result.code, 0)
+  assert.doesNotMatch(rewrittenMessage, /🤖/)
+})
+
+test('commit-msg: keeps prose mentioning Claude in context', async () => {
+  // Bare "Claude Code" reference (not an attribution claim) survives
+  // the strip — this was the regression that prompted the regex fix.
+  const { result, rewrittenMessage } = await runHook(
+    'docs(claude): point at Claude Code best practices\n\nLinks the upstream guide that informs the .claude/ layout.\n',
+  )
+  assert.strictEqual(result.code, 0)
+  assert.match(rewrittenMessage, /Claude Code best practices/)
+  assert.match(rewrittenMessage, /\.claude\//)
+})
diff --git a/.git-hooks/test/pre-commit.test.mts b/.git-hooks/test/pre-commit.test.mts
new file mode 100755
index 0000000..66fa6bc
--- /dev/null
+++ b/.git-hooks/test/pre-commit.test.mts
@@ -0,0 +1,111 @@
+// node --test specs for .git-hooks/pre-commit.mts.
+//
+// Smoke tests: spin up a temp git repo, stage a file, run the hook
+// from inside it, and inspect exit code + stderr. Covers the clean
+// path and the secret-leak block path.
+
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { spawn, spawnSync } from 'node:child_process'
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs'
+import path from 'node:path'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const HOOK = path.join(here, '..', 'pre-commit.mts')
+
+function setupRepo(): string {
+  const dir = mkdtempSync(path.join(tmpdir(), 'pre-commit-test-'))
+  spawnSync('git', ['init', '-q'], { cwd: dir })
+  spawnSync('git', ['config', 'user.email', 'test@example.com'], { cwd: dir })
+  spawnSync('git', ['config', 'user.name', 'Test'], { cwd: dir })
+  spawnSync('git', ['config', 'commit.gpgsign', 'false'], { cwd: dir })
+  return dir
+}
+
+async function runHook(cwd: string): Promise<{ code: number; stderr: string }> {
+  const child = spawn(process.execPath, [HOOK], {
+    cwd,
+    stdio: 'pipe',
+  })
+  let stderr = ''
+  child.stderr.on('data', chunk => {
+    stderr += chunk.toString('utf8')
+  })
+  return new Promise(resolve => {
+    child.on('exit', code => resolve({ code: code ?? 0, stderr }))
+  })
+}
+
+test('pre-commit: passes a clean staged file', async () => {
+  const dir = setupRepo()
+  try {
+    writeFileSync(path.join(dir, 'foo.ts'), 'export const X = 1\n')
+    spawnSync('git', ['add', 'foo.ts'], { cwd: dir })
+    const { code } = await runHook(dir)
+    assert.strictEqual(code, 0)
+  } finally {
+    rmSync(dir, { force: true, recursive: true })
+  }
+})
+
+test('pre-commit: blocks a staged file with a real personal path', async () => {
+  const dir = setupRepo()
+  try {
+    writeFileSync(
+      path.join(dir, 'leak.ts'),
+      'export const HOME = "/Users/jdalton/secret"\n',
+    )
+    spawnSync('git', ['add', 'leak.ts'], { cwd: dir })
+    const { code, stderr } = await runHook(dir)
+    assert.notStrictEqual(code, 0, 'hook must reject personal-path leaks')
+    assert.match(stderr, /\/Users\/jdalton/i)
+  } finally {
+    rmSync(dir, { force: true, recursive: true })
+  }
+})
+
+test('pre-commit: blocks a staged file containing an AWS access key', async () => {
+  const dir = setupRepo()
+  try {
+    writeFileSync(
+      path.join(dir, 'aws.txt'),
+      'AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE\n',
+    )
+    spawnSync('git', ['add', 'aws.txt'], { cwd: dir })
+    const { code } = await runHook(dir)
+    assert.notStrictEqual(code, 0)
+  } finally {
+    rmSync(dir, { force: true, recursive: true })
+  }
+})
+
+test('pre-commit: passes when no files are staged', async () => {
+  const dir = setupRepo()
+  try {
+    const { code } = await runHook(dir)
+    assert.strictEqual(code, 0)
+  } finally {
+    rmSync(dir, { force: true, recursive: true })
+  }
+})
+
+test('pre-commit: blocks staged .env file', async () => {
+  const dir = setupRepo()
+  try {
+    writeFileSync(
+      path.join(dir, '.env'),
+      'SOCKET_API_TOKEN=sktsec_abc123abc123abc123abc123\n',
+    )
+    spawnSync('git', ['add', '-f', '.env'], { cwd: dir })
+    const { code } = await runHook(dir)
+    assert.notStrictEqual(code, 0, 'hook must reject .env files')
+  } finally {
+    rmSync(dir, { force: true, recursive: true })
+  }
+})
+
+// Suppress the unused-mkdir warning by referencing it (harness might
+// extend with subdir tests later).
+void mkdirSync
diff --git a/.git-hooks/test/pre-push.test.mts b/.git-hooks/test/pre-push.test.mts
new file mode 100755
index 0000000..d5a7b15
--- /dev/null
+++ b/.git-hooks/test/pre-push.test.mts
@@ -0,0 +1,162 @@
+// node --test specs for .git-hooks/pre-push.mts.
+//
+// Smoke tests: spin up a temp git repo, commit content, feed a
+// push-line to the hook over stdin, inspect exit code. Covers the
+// AI-attribution block path and the secret-leak block path.
+
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { spawn, spawnSync } from 'node:child_process'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const HOOK = path.join(here, '..', 'pre-push.mts')
+
+const ZERO_SHA = '0000000000000000000000000000000000000000'
+
+function setupRepo(): string {
+  const dir = mkdtempSync(path.join(tmpdir(), 'pre-push-test-'))
+  spawnSync('git', ['init', '-q', '-b', 'main'], { cwd: dir })
+  spawnSync('git', ['config', 'user.email', 'test@example.com'], { cwd: dir })
+  spawnSync('git', ['config', 'user.name', 'Test'], { cwd: dir })
+  spawnSync('git', ['config', 'commit.gpgsign', 'false'], { cwd: dir })
+  // Create a baseline commit and an `origin/main` remote-tracking ref
+  // pointing at it. The hook's range computation requires a baseline
+  // — without one, it skips validation entirely (treats the push as
+  // a brand-new branch with no baseline to diff against).
+  writeFileSync(path.join(dir, '.gitkeep'), '')
+  spawnSync('git', ['add', '.gitkeep'], { cwd: dir })
+  spawnSync('git', ['commit', '-q', '-m', 'baseline', '--no-verify'], {
+    cwd: dir,
+  })
+  // Manually create the remote-tracking ref so computeRange has a
+  // baseline. spawnSync('update-ref') is a low-level git plumbing call
+  // that bypasses the network.
+  const baseSha = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: dir })
+    .stdout.toString()
+    .trim()
+  spawnSync('git', ['update-ref', 'refs/remotes/origin/main', baseSha], {
+    cwd: dir,
+  })
+  spawnSync(
+    'git',
+    ['symbolic-ref', 'refs/remotes/origin/HEAD', 'refs/remotes/origin/main'],
+    { cwd: dir },
+  )
+  return dir
+}
+
+function commit(
+  dir: string,
+  file: string,
+  content: string,
+  msg: string,
+): string {
+  writeFileSync(path.join(dir, file), content)
+  spawnSync('git', ['add', file], { cwd: dir })
+  spawnSync('git', ['commit', '-q', '-m', msg, '--no-verify'], { cwd: dir })
+  const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: dir })
+  return r.stdout.toString().trim()
+}
+
+async function runHook(
+  cwd: string,
+  pushLine: string,
+): Promise<{ code: number; stderr: string }> {
+  const child = spawn(process.execPath, [HOOK, 'origin', cwd], {
+    cwd,
+    stdio: 'pipe',
+  })
+  let stderr = ''
+  child.stderr.on('data', chunk => {
+    stderr += chunk.toString('utf8')
+  })
+  child.stdin.end(pushLine)
+  return new Promise(resolve => {
+    child.on('exit', code => resolve({ code: code ?? 0, stderr }))
+  })
+}
+
+test('pre-push: empty stdin exits 0 (nothing to push)', async () => {
+  const dir = setupRepo()
+  try {
+    const { code } = await runHook(dir, '')
+    assert.strictEqual(code, 0)
+  } finally {
+    rmSync(dir, { force: true, recursive: true })
+  }
+})
+
+test('pre-push: clean commit + clean message passes', async () => {
+  const dir = setupRepo()
+  try {
+    const sha = commit(
+      dir,
+      'foo.ts',
+      'export const X = 1\n',
+      'feat: initial commit',
+    )
+    const pushLine = `refs/heads/main ${sha} refs/heads/main ${ZERO_SHA}\n`
+    const { code } = await runHook(dir, pushLine)
+    assert.strictEqual(code, 0)
+  } finally {
+    rmSync(dir, { force: true, recursive: true })
+  }
+})
+
+test('pre-push: blocks commit with AI-attribution body', async () => {
+  const dir = setupRepo()
+  try {
+    const sha = commit(
+      dir,
+      'foo.ts',
+      'export const X = 1\n',
+      'feat: ship feature\n\nCo-Authored-By: Claude <noreply@anthropic.com>',
+    )
+    const pushLine = `refs/heads/main ${sha} refs/heads/main ${ZERO_SHA}\n`
+    const { code, stderr } = await runHook(dir, pushLine)
+    assert.notStrictEqual(code, 0, 'AI attribution must block push')
+    assert.match(stderr, /AI attribution|Co-Authored-By/i)
+  } finally {
+    rmSync(dir, { force: true, recursive: true })
+  }
+})
+
+test('pre-push: keeps prose mentioning Claude in context', async () => {
+  // The previous regex matched bare "Claude Code" — verify the fix
+  // doesn't false-positive on legitimate references.
+  const dir = setupRepo()
+  try {
+    const sha = commit(
+      dir,
+      'foo.ts',
+      'export const X = 1\n',
+      'docs(claude): point at Claude Code best practices\n\nLinks the upstream guide that informs the .claude/ layout.',
+    )
+    const pushLine = `refs/heads/main ${sha} refs/heads/main ${ZERO_SHA}\n`
+    const { code } = await runHook(dir, pushLine)
+    assert.strictEqual(code, 0, 'legitimate Claude Code prose must pass')
+  } finally {
+    rmSync(dir, { force: true, recursive: true })
+  }
+})
+
+test('pre-push: blocks commit introducing a personal-path leak', async () => {
+  const dir = setupRepo()
+  try {
+    const sha = commit(
+      dir,
+      'leak.ts',
+      'export const HOME = "/Users/jdalton/secret"\n',
+      'feat: add config',
+    )
+    const pushLine = `refs/heads/main ${sha} refs/heads/main ${ZERO_SHA}\n`
+    const { code } = await runHook(dir, pushLine)
+    assert.notStrictEqual(code, 0)
+  } finally {
+    rmSync(dir, { force: true, recursive: true })
+  }
+})
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..f1b3fc3
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,225 @@
+* text=auto eol=lf
+
+# ─── BEGIN fleet-canonical (managed by socket-wheelhouse sync) ──
+# Cascaded from socket-wheelhouse/template/. Don't edit locally —
+# edit upstream and re-cascade via sync-scaffolding. Marked
+# linguist-generated so GitHub PR diffs collapse them by default.
+.claude/agents/security-reviewer.md linguist-generated=true
+.claude/commands/quality-loop.md linguist-generated=true
+.claude/commands/security-scan.md linguist-generated=true
+.claude/commands/setup-security-tools.md linguist-generated=true
+.claude/commands/squash-history.md linguist-generated=true
+.claude/hooks/_shared/README.md linguist-generated=true
+.claude/hooks/_shared/bash-quote-mask.mts linguist-generated=true
+.claude/hooks/_shared/markers.mts linguist-generated=true
+.claude/hooks/_shared/test/bash-quote-mask.test.mts linguist-generated=true
+.claude/hooks/auth-rotation-reminder/README.md linguist-generated=true
+.claude/hooks/auth-rotation-reminder/index.mts linguist-generated=true
+.claude/hooks/auth-rotation-reminder/package.json linguist-generated=true
+.claude/hooks/auth-rotation-reminder/services.mts linguist-generated=true
+.claude/hooks/auth-rotation-reminder/test/auth-rotation-reminder.test.mts linguist-generated=true
+.claude/hooks/auth-rotation-reminder/tsconfig.json linguist-generated=true
+.claude/hooks/check-new-deps/README.md linguist-generated=true
+.claude/hooks/check-new-deps/index.mts linguist-generated=true
+.claude/hooks/check-new-deps/package.json linguist-generated=true
+.claude/hooks/claude-md-size-guard/README.md linguist-generated=true
+.claude/hooks/claude-md-size-guard/index.mts linguist-generated=true
+.claude/hooks/claude-md-size-guard/package.json linguist-generated=true
+.claude/hooks/claude-md-size-guard/test/index.test.mts linguist-generated=true
+.claude/hooks/claude-md-size-guard/tsconfig.json linguist-generated=true
+.claude/hooks/cross-repo-guard/README.md linguist-generated=true
+.claude/hooks/cross-repo-guard/index.mts linguist-generated=true
+.claude/hooks/cross-repo-guard/package.json linguist-generated=true
+.claude/hooks/cross-repo-guard/test/cross-repo-guard.test.mts linguist-generated=true
+.claude/hooks/cross-repo-guard/tsconfig.json linguist-generated=true
+.claude/hooks/excuse-detector/README.md linguist-generated=true
+.claude/hooks/excuse-detector/index.mts linguist-generated=true
+.claude/hooks/excuse-detector/package.json linguist-generated=true
+.claude/hooks/excuse-detector/test/index.test.mts linguist-generated=true
+.claude/hooks/excuse-detector/tsconfig.json linguist-generated=true
+.claude/hooks/gitmodules-comment-guard/README.md linguist-generated=true
+.claude/hooks/gitmodules-comment-guard/index.mts linguist-generated=true
+.claude/hooks/gitmodules-comment-guard/package.json linguist-generated=true
+.claude/hooks/gitmodules-comment-guard/tsconfig.json linguist-generated=true
+.claude/hooks/logger-guard/README.md linguist-generated=true
+.claude/hooks/logger-guard/index.mts linguist-generated=true
+.claude/hooks/logger-guard/package.json linguist-generated=true
+.claude/hooks/logger-guard/test/logger-guard.test.mts linguist-generated=true
+.claude/hooks/logger-guard/tsconfig.json linguist-generated=true
+.claude/hooks/markdown-filename-guard/README.md linguist-generated=true
+.claude/hooks/markdown-filename-guard/index.mts linguist-generated=true
+.claude/hooks/markdown-filename-guard/package.json linguist-generated=true
+.claude/hooks/markdown-filename-guard/test/index.test.mts linguist-generated=true
+.claude/hooks/markdown-filename-guard/tsconfig.json linguist-generated=true
+.claude/hooks/no-experimental-strip-types-guard/README.md linguist-generated=true
+.claude/hooks/no-experimental-strip-types-guard/index.mts linguist-generated=true
+.claude/hooks/no-experimental-strip-types-guard/package.json linguist-generated=true
+.claude/hooks/no-experimental-strip-types-guard/test/index.test.mts linguist-generated=true
+.claude/hooks/no-experimental-strip-types-guard/tsconfig.json linguist-generated=true
+.claude/hooks/no-fleet-fork-guard/README.md linguist-generated=true
+.claude/hooks/no-fleet-fork-guard/index.mts linguist-generated=true
+.claude/hooks/no-fleet-fork-guard/package.json linguist-generated=true
+.claude/hooks/no-fleet-fork-guard/test/index.test.mts linguist-generated=true
+.claude/hooks/no-fleet-fork-guard/tsconfig.json linguist-generated=true
+.claude/hooks/no-revert-guard/README.md linguist-generated=true
+.claude/hooks/no-revert-guard/index.mts linguist-generated=true
+.claude/hooks/no-revert-guard/package.json linguist-generated=true
+.claude/hooks/no-revert-guard/test/index.test.mts linguist-generated=true
+.claude/hooks/no-revert-guard/tsconfig.json linguist-generated=true
+.claude/hooks/path-guard/README.md linguist-generated=true
+.claude/hooks/path-guard/index.mts linguist-generated=true
+.claude/hooks/path-guard/package.json linguist-generated=true
+.claude/hooks/path-guard/segments.mts linguist-generated=true
+.claude/hooks/path-guard/test/path-guard.test.mts linguist-generated=true
+.claude/hooks/path-guard/tsconfig.json linguist-generated=true
+.claude/hooks/private-name-guard/README.md linguist-generated=true
+.claude/hooks/public-surface-reminder/README.md linguist-generated=true
+.claude/hooks/release-workflow-guard/README.md linguist-generated=true
+.claude/hooks/release-workflow-guard/index.mts linguist-generated=true
+.claude/hooks/release-workflow-guard/package.json linguist-generated=true
+.claude/hooks/release-workflow-guard/test/release-workflow-guard.test.mts linguist-generated=true
+.claude/hooks/release-workflow-guard/tsconfig.json linguist-generated=true
+.claude/hooks/setup-security-tools/README.md linguist-generated=true
+.claude/hooks/stale-process-sweeper/README.md linguist-generated=true
+.claude/hooks/stale-process-sweeper/index.mts linguist-generated=true
+.claude/hooks/stale-process-sweeper/package.json linguist-generated=true
+.claude/hooks/stale-process-sweeper/test/stale-process-sweeper.test.mts linguist-generated=true
+.claude/hooks/stale-process-sweeper/tsconfig.json linguist-generated=true
+.claude/hooks/token-guard/README.md linguist-generated=true
+.claude/hooks/token-guard/index.mts linguist-generated=true
+.claude/hooks/token-guard/package.json linguist-generated=true
+.claude/hooks/token-guard/test/token-guard.test.mts linguist-generated=true
+.claude/hooks/token-guard/tsconfig.json linguist-generated=true
+.claude/settings.json linguist-generated=true
+.claude/skills/_shared/compound-lessons.md linguist-generated=true
+.claude/skills/_shared/env-check.md linguist-generated=true
+.claude/skills/_shared/multi-agent-backends.md linguist-generated=true
+.claude/skills/_shared/path-guard-rule.md linguist-generated=true
+.claude/skills/_shared/report-format.md linguist-generated=true
+.claude/skills/_shared/scripts/git-default-branch.mts linguist-generated=true
+.claude/skills/_shared/scripts/logger-guardrails.mts linguist-generated=true
+.claude/skills/_shared/scripts/resolve-tools.mts linguist-generated=true
+.claude/skills/_shared/security-tools.md linguist-generated=true
+.claude/skills/_shared/skill-authoring.md linguist-generated=true
+.claude/skills/_shared/variant-analysis.md linguist-generated=true
+.claude/skills/_shared/verify-build.md linguist-generated=true
+.claude/skills/driving-cursor-bugbot/SKILL.md linguist-generated=true
+.claude/skills/driving-cursor-bugbot/reference.md linguist-generated=true
+.claude/skills/guarding-paths/SKILL.md linguist-generated=true
+.claude/skills/guarding-paths/reference.md linguist-generated=true
+.claude/skills/guarding-paths/templates/check-paths.mts.tmpl linguist-generated=true
+.claude/skills/guarding-paths/templates/paths-allowlist.yml.tmpl linguist-generated=true
+.claude/skills/handing-off/SKILL.md linguist-generated=true
+.claude/skills/locking-down-programmatic-claude/SKILL.md linguist-generated=true
+.claude/skills/plug-leaking-promise-race/SKILL.md linguist-generated=true
+.claude/skills/refreshing-history/SKILL.md linguist-generated=true
+.claude/skills/refreshing-history/run.mts linguist-generated=true
+.claude/skills/reviewing-code/SKILL.md linguist-generated=true
+.claude/skills/reviewing-code/run.mts linguist-generated=true
+.claude/skills/scanning-quality/SKILL.md linguist-generated=true
+.claude/skills/scanning-quality/scans/bundle-trim.md linguist-generated=true
+.claude/skills/scanning-quality/scans/differential.md linguist-generated=true
+.claude/skills/scanning-quality/scans/insecure-defaults.md linguist-generated=true
+.claude/skills/scanning-quality/scans/variant-analysis.md linguist-generated=true
+.claude/skills/scanning-security/SKILL.md linguist-generated=true
+.claude/skills/squashing-history/SKILL.md linguist-generated=true
+.claude/skills/squashing-history/reference.md linguist-generated=true
+.claude/skills/updating-lockstep/SKILL.md linguist-generated=true
+.claude/skills/updating-lockstep/reference.md linguist-generated=true
+.claude/skills/updating/SKILL.md linguist-generated=true
+.claude/skills/updating/reference.md linguist-generated=true
+.claude/skills/worktree-management/SKILL.md linguist-generated=true
+.config/lockstep.schema.json linguist-generated=true
+.config/oxlint-plugin/index.mts linguist-generated=true
+.config/oxlint-plugin/package.json linguist-generated=true
+.config/oxlint-plugin/rules/_inject-import.mts linguist-generated=true
+.config/oxlint-plugin/rules/export-top-level-functions.mts linguist-generated=true
+.config/oxlint-plugin/rules/inclusive-language.mts linguist-generated=true
+.config/oxlint-plugin/rules/max-file-lines.mts linguist-generated=true
+.config/oxlint-plugin/rules/no-console-prefer-logger.mts linguist-generated=true
+.config/oxlint-plugin/rules/no-default-export.mts linguist-generated=true
+.config/oxlint-plugin/rules/no-dynamic-import-outside-bundle.mts linguist-generated=true
+.config/oxlint-plugin/rules/no-fetch-prefer-http-request.mts linguist-generated=true
+.config/oxlint-plugin/rules/no-inline-logger.mts linguist-generated=true
+.config/oxlint-plugin/rules/no-npx-dlx.mts linguist-generated=true
+.config/oxlint-plugin/rules/no-placeholders.mts linguist-generated=true
+.config/oxlint-plugin/rules/no-promise-race-in-loop.mts linguist-generated=true
+.config/oxlint-plugin/rules/no-promise-race.mts linguist-generated=true
+.config/oxlint-plugin/rules/no-status-emoji.mts linguist-generated=true
+.config/oxlint-plugin/rules/personal-path-placeholders.mts linguist-generated=true
+.config/oxlint-plugin/rules/prefer-async-spawn.mts linguist-generated=true
+.config/oxlint-plugin/rules/prefer-cached-for-loop.mts linguist-generated=true
+.config/oxlint-plugin/rules/prefer-exists-sync.mts linguist-generated=true
+.config/oxlint-plugin/rules/prefer-function-declaration.mts linguist-generated=true
+.config/oxlint-plugin/rules/prefer-node-builtin-imports.mts linguist-generated=true
+.config/oxlint-plugin/rules/prefer-safe-delete.mts linguist-generated=true
+.config/oxlint-plugin/rules/prefer-separate-type-import.mts linguist-generated=true
+.config/oxlint-plugin/rules/prefer-undefined-over-null.mts linguist-generated=true
+.config/oxlint-plugin/rules/socket-api-token-env.mts linguist-generated=true
+.config/oxlint-plugin/rules/sort-equality-disjunctions.mts linguist-generated=true
+.config/oxlint-plugin/rules/sort-named-imports.mts linguist-generated=true
+.config/oxlint-plugin/rules/sort-regex-alternations.mts linguist-generated=true
+.config/oxlint-plugin/rules/sort-set-args.mts linguist-generated=true
+.config/oxlint-plugin/rules/sort-source-methods.mts linguist-generated=true
+.config/rolldown/lib-stub.mts linguist-generated=true
+.config/socket-wheelhouse-schema.json linguist-generated=true
+.config/taze.config.mts linguist-generated=true
+.config/tsconfig.base.json linguist-generated=true
+.git-hooks/_helpers.mts linguist-generated=true
+.git-hooks/commit-msg.mts linguist-generated=true
+.git-hooks/pre-commit.mts linguist-generated=true
+.git-hooks/pre-push.mts linguist-generated=true
+.git-hooks/test/_helpers.test.mts linguist-generated=true
+.git-hooks/test/commit-msg.test.mts linguist-generated=true
+.git-hooks/test/pre-commit.test.mts linguist-generated=true
+.git-hooks/test/pre-push.test.mts linguist-generated=true
+.husky/commit-msg linguist-generated=true
+.husky/pre-commit linguist-generated=true
+.husky/pre-push linguist-generated=true
+assets/README.md linguist-generated=true
+assets/socket-icon-brand-128.png linguist-generated=true
+assets/socket-icon-brand-16.png linguist-generated=true
+assets/socket-icon-brand-256.png linguist-generated=true
+assets/socket-icon-brand-32.png linguist-generated=true
+assets/socket-icon-brand-512.png linguist-generated=true
+assets/socket-icon-brand-64.png linguist-generated=true
+assets/socket-icon-brand-square.svg linguist-generated=true
+assets/socket-icon-brand.svg linguist-generated=true
+assets/socket-icon-shield-square.svg linguist-generated=true
+assets/socket-icon-shield.svg linguist-generated=true
+assets/socket-icon-square.svg linguist-generated=true
+assets/socket-icon.svg linguist-generated=true
+assets/socket-logo-dark-1680.png linguist-generated=true
+assets/socket-logo-dark-420.png linguist-generated=true
+assets/socket-logo-dark-840.png linguist-generated=true
+assets/socket-logo-dark.svg linguist-generated=true
+assets/socket-logo-light-1680.png linguist-generated=true
+assets/socket-logo-light-420.png linguist-generated=true
+assets/socket-logo-light-840.png linguist-generated=true
+assets/socket-logo-light.svg linguist-generated=true
+docs/claude.md/agent-delegation.md linguist-generated=true
+docs/claude.md/bypass-phrases.md linguist-generated=true
+docs/claude.md/error-messages.md linguist-generated=true
+docs/claude.md/inclusive-language.md linguist-generated=true
+docs/claude.md/no-local-fork-canonical.md linguist-generated=true
+docs/claude.md/sorting.md linguist-generated=true
+packages/build-infra/lib/release-checksums/consumer.mts linguist-generated=true
+packages/build-infra/lib/release-checksums/core.mts linguist-generated=true
+packages/build-infra/lib/release-checksums/producer.mts linguist-generated=true
+packages/build-infra/release-assets.schema.json linguist-generated=true
+scripts/ai-lint-fix.mts linguist-generated=true
+scripts/check-paths.mts linguist-generated=true
+scripts/fix.mts linguist-generated=true
+scripts/install-sfw.mts linguist-generated=true
+scripts/lockstep-emit-schema.mts linguist-generated=true
+scripts/lockstep-schema.mts linguist-generated=true
+scripts/lockstep.mts linguist-generated=true
+scripts/power-state.mts linguist-generated=true
+scripts/security.mts linguist-generated=true
+scripts/socket-wheelhouse-emit-schema.mts linguist-generated=true
+scripts/socket-wheelhouse-schema.mts linguist-generated=true
+scripts/update.mts linguist-generated=true
+scripts/validate-config-paths.mts linguist-generated=true
+scripts/validate-esbuild-minify.mts linguist-generated=true
+scripts/validate-file-size.mts linguist-generated=true
+# ─── END fleet-canonical ────────────────────────────────────────
diff --git a/.husky/commit-msg b/.husky/commit-msg
new file mode 100755
index 0000000..42fe3bd
--- /dev/null
+++ b/.husky/commit-msg
@@ -0,0 +1,2 @@
+# Run commit message validation and auto-strip AI attribution.
+node .git-hooks/commit-msg.mts "$1"
diff --git a/.husky/pre-commit b/.husky/pre-commit
new file mode 100755
index 0000000..cf22d39
--- /dev/null
+++ b/.husky/pre-commit
@@ -0,0 +1,51 @@
+#!/bin/sh
+# Optional checks - can be bypassed with --no-verify for fast local commits.
+# Mandatory security checks ALSO run in pre-push hook.
+#
+# Architecture (parallels commit-msg and pre-push):
+#   .husky/pre-commit (this file) → .git-hooks/pre-commit.mts (security) + pnpm lint/test
+#
+# Use --no-verify for:
+# - History operations (squash, rebase, amend)
+# - Emergency hotfixes
+# - When tests require binaries that haven't been built yet
+#
+# Use environment variables to selectively disable:
+# - DISABLE_PRECOMMIT_LINT=1 to skip linting
+# - DISABLE_PRECOMMIT_TEST=1 to skip testing
+
+# Run Socket security pre-commit checks (API keys, .DS_Store, etc.).
+node .git-hooks/pre-commit.mts
+
+# Check if pnpm is available
+if ! command -v pnpm >/dev/null 2>&1; then
+  echo "Error: pnpm not found. Install pnpm to run git hooks."
+  echo "Visit: https://pnpm.io/installation"
+  exit 1
+fi
+
+if [ -z "${DISABLE_PRECOMMIT_LINT}" ]; then
+  pnpm lint --staged
+else
+  echo "Skipping lint due to DISABLE_PRECOMMIT_LINT env var"
+fi
+
+if [ -z "${DISABLE_PRECOMMIT_TEST}" ]; then
+  # Each repo's `pnpm test` script wraps a runner that understands
+  # `--staged` (e.g. scripts/test.mts forwards staged-filtering to
+  # vitest, or filters the staged set in a pre-pass). When
+  # DISABLE_PRECOMMIT_LINT is set, also pass --fast so the test
+  # runner skips its embedded format/lint check (otherwise lint
+  # bypass leaks through this path and re-blocks the commit).
+  #
+  # Repos whose `pnpm test` is bare vitest without a wrapper need a
+  # local override (skills/.husky/pre-commit pre-filters with
+  # `git diff --cached --name-only` then runs `pnpm test`).
+  if [ -n "${DISABLE_PRECOMMIT_LINT}" ]; then
+    pnpm test --staged --fast
+  else
+    pnpm test --staged
+  fi
+else
+  echo "Skipping testing due to DISABLE_PRECOMMIT_TEST env var"
+fi
diff --git a/.husky/pre-push b/.husky/pre-push
new file mode 100755
index 0000000..1af2737
--- /dev/null
+++ b/.husky/pre-push
@@ -0,0 +1,2 @@
+# Run pre-push security validation.
+node .git-hooks/pre-push.mts "$@"
diff --git a/docs/claude.md/agent-delegation.md b/docs/claude.md/agent-delegation.md
new file mode 100644
index 0000000..32eccd8
--- /dev/null
+++ b/docs/claude.md/agent-delegation.md
@@ -0,0 +1,39 @@
+# Agent delegation
+
+When a task fits one of the patterns below, hand it off instead of doing it in the current session. The point is to get a _different model's_ take or to keep heavy work out of the main context — not to avoid effort. Don't delegate trivial tasks: the round-trip overhead isn't worth it for things you can answer in one or two tool calls.
+
+There are two delegation surfaces in this fleet. They look similar but are used differently.
+
+## Surface 1 — CLI subprocess delegation (skills)
+
+Skills that need multi-model output spawn the agent CLIs (`codex`, `claude`, `kimi`, `opencode`) as subprocesses and fold the results into a report. The contract — backend registry, detection policy, fallback order, attribution — lives in [`_shared/multi-agent-backends.md`](../../.claude/skills/_shared/multi-agent-backends.md). The canonical implementation is [`reviewing-code/run.mts`](../../.claude/skills/reviewing-code/run.mts).
+
+Use this surface when _the skill itself_ is the orchestrator (multi-pass review, parallel scans, fleet-wide runs).
+
+## Surface 2 — Subagent delegation (mid-conversation)
+
+When the _current_ Claude session wants to hand off a single task to another model and consume its result inline, use `Agent(subagent_type=…)`. This is in-conversation delegation, not skill orchestration.
+
+| Subagent             | When to use                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `codex:codex-rescue` | You want GPT-5.4's take or a heavyweight async investigation. Best for: hard debugging you're stuck on, second implementation pass on a tricky design, deep root-cause work. Persistent runtime — check progress with `/codex:status`, get output with `/codex:result`. Also exposed as `/codex:rescue` for user-driven invocation.                                                                                                                                                                     |
+| `delegate`           | You want a Fireworks / Synthetic / Kimi open model via [OpenCode](https://opencode.ai). Best for: cheap bulk work (classification, summarization, drafting many things), specialist routing (e.g. Qwen-Coder for code-heavy tasks), second opinions from a non-GPT/non-Claude model. Caller specifies the model in the prompt (e.g. `fireworks/qwen3-coder-480b`). Fire-and-forget. **Optional** — only available if the dev has set up the `delegate` agent locally. Skill code must not depend on it. |
+| `Explore`            | Codebase search / "where is X defined" / cross-file lookups. Different model isn't the point — context isolation is.                                                                                                                                                                                                                                                                                                                                                                                    |
+| `Plan`               | Implementation strategy for a non-trivial task before writing code.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `general-purpose`    | Open-ended research that doesn't fit the above.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+
+## Routing heuristics
+
+- **Stuck after one or two failed attempts** → `codex:codex-rescue`. A different family often breaks the deadlock.
+- **About to do 20+ similar small operations** → `delegate` with a cheap model. Keep the main context clean.
+- **Want a sanity check on a non-trivial design or diff** → `/codex:adversarial-review` (slash command) _or_ `delegate` to a different family, depending on which perspective is more useful.
+- **Big codebase question that'll burn context** → `Explore`.
+- **Building a multi-pass workflow** → don't use `Agent(...)` ad hoc; write a skill that uses Surface 1.
+
+## When the surfaces overlap
+
+A skill that wants `codex` output should call the CLI (Surface 1) so the result lands in a structured report. A live conversation that wants Codex's opinion on the _current_ problem should use the subagent (Surface 2) so the result flows back into the conversation. Same model, different orchestration.
+
+## Compatibility note
+
+Codex is fleet-wide (the `codex` CLI is a fleet plugin). OpenCode and the `delegate` subagent are **per-developer** — they require local setup outside the repo. Skills that automate work across the fleet must not assume `delegate` exists; humans driving Claude in their own checkout can use it freely.
diff --git a/docs/claude.md/bypass-phrases.md b/docs/claude.md/bypass-phrases.md
new file mode 100644
index 0000000..88aaa03
--- /dev/null
+++ b/docs/claude.md/bypass-phrases.md
@@ -0,0 +1,50 @@
+# Hook bypass phrases
+
+Reverting tracked changes or bypassing the fleet's hook chain requires the user to type the canonical phrase verbatim in a recent user turn. Inferring intent from "go ahead", "skip the hook", "fix it", etc. does NOT count.
+
+The phrase format is `Allow <X> bypass` — case-sensitive, exact match.
+
+| Operation                                                                                                                                                                                                   | Phrase                    |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| Revert (any of: `git checkout -- <files>`, `git checkout <ref> -- <files>`, `git restore <files>` without `--staged`, `git reset --hard`, `git stash drop` / `pop` / `clear`, `git clean -f`, `git rm -rf`) | `Allow revert bypass`     |
+| `git --no-verify` (skips husky hooks)                                                                                                                                                                       | `Allow no-verify bypass`  |
+| `git --no-gpg-sign` / `-c commit.gpgsign=false`                                                                                                                                                             | `Allow gpg bypass`        |
+| `DISABLE_PRECOMMIT_LINT=1` (skips lint step)                                                                                                                                                                | `Allow lint bypass`       |
+| `DISABLE_PRECOMMIT_TEST=1` (skips test step)                                                                                                                                                                | `Allow test bypass`           |
+| `SKIP_ASSET_DOWNLOAD=1` (skips release-asset fetch in build — degraded-mode flag; becomes a bypass when used to push past rate-limited pre-commit)                                                          | `Allow asset-download bypass` |
+| `git push --force` / `-f`                                                                                                                                                                                   | `Allow force-push bypass`     |
+
+## Scope
+
+A phrase from a previous session does not carry over — only the current conversation's user turns count. The hook reads the active session's transcript (passed by Claude Code as `transcript_path` in the PreToolUse payload) and searches the concatenated user-turn text for the exact phrase.
+
+The match is **case-sensitive** and **substring-based**:
+
+- ✓ `Allow revert bypass — please drop my last edit`
+- ✓ a multi-line user message with `Allow revert bypass` on its own line
+- ✗ `allow revert bypass` (lowercase)
+- ✗ `please revert that file` (paraphrase)
+- ✗ `--no-verify is fine` (no `Allow ... bypass` shape)
+
+## Why a phrase
+
+Without the gate, the assistant has historically reverted whole batches of autofix changes mid-cleanup or used `--no-verify` to push past a failing hook, both of which destroy work and erode trust. The phrase is short enough to type when truly intended and specific enough that no other utterance accidentally triggers it.
+
+## Defense in depth
+
+The bypass policy is enforced at three layers:
+
+- **CLAUDE.md** documents the rule (`### Hook bypasses require the canonical phrase`).
+- **Memory** keeps the assistant honest across sessions even before the hook fires.
+- **`.claude/hooks/no-revert-guard/`** is the actual enforcement: a `PreToolUse(Bash)` hook that scans the proposed command, parses the transcript, and exits 2 with a clear stderr message naming the phrase the user must type.
+
+The hook fails open on its own bugs (exit 0 + stderr log) so a bad deploy can't brick the session. Trade-off: a buggy hook silently allows the destructive command. Acceptable because the alternative (hook crash wedges the session) is worse for development velocity.
+
+## How to add a new bypass
+
+When introducing a new destructive flag or hook bypass:
+
+1. Add a new entry to the `CHECKS` array in `.claude/hooks/no-revert-guard/index.mts`. Each check is `{ pattern: RegExp, bypassPhrase: string, label: string }`.
+2. Add a row to this reference's table.
+3. Add a test case to `.claude/hooks/no-revert-guard/test/index.test.mts` covering both the blocked-without-phrase and allowed-with-phrase paths.
+4. Cascade via `node socket-wheelhouse/scripts/sync-scaffolding.mts --all --fix` so every fleet repo picks up the change.
diff --git a/docs/claude.md/error-messages.md b/docs/claude.md/error-messages.md
new file mode 100644
index 0000000..d7848a3
--- /dev/null
+++ b/docs/claude.md/error-messages.md
@@ -0,0 +1,170 @@
+# Error Messages — Worked Examples
+
+Companion to the `## Error Messages` section of `CLAUDE.md`. That section
+holds the rules; this file holds longer examples and anti-patterns that
+would bloat CLAUDE.md if inlined.
+
+## The four ingredients
+
+Every message needs, in order:
+
+1. **What** — the rule that was broken.
+2. **Where** — the exact file, line, key, field, or CLI flag.
+3. **Saw vs. wanted** — the bad value and the allowed shape or set.
+4. **Fix** — one concrete action, in imperative voice.
+
+## Library API errors (terse)
+
+Callers may match on the message text, so stability matters. Aim for one
+sentence.
+
+| ✗ / ✓ | Message                                                                                                                                                                          | Notes                                                 |
+| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| ✗     | `Error: invalid component`                                                                                                                                                       | No rule, no saw, no where.                            |
+| ✗     | `The "name" component of type "npm" failed validation because the provided value "" is empty, which is not allowed because names are required; please provide a non-empty name.` | Restates the rule three times.                        |
+| ✓     | `npm "name" component is required`                                                                                                                                               | Rule + where + implied saw (missing). Six words.      |
+| ✗     | `Error: bad name`                                                                                                                                                                | No rule.                                              |
+| ✓     | `name "__proto__" cannot start with an underscore`                                                                                                                               | Rule, where (`name`), saw (`__proto__`), fix implied. |
+| ✗     | `Error: invalid argument`                                                                                                                                                        | No where, no rule, no fix.                            |
+| ✓     | `orgSlug is required`                                                                                                                                                            | Rule + where (`orgSlug`), saw (missing), implies fix. |
+| ✗     | `Error: request failed`                                                                                                                                                          | No status, no hint what to check.                     |
+| ✓     | `Socket API rejected the token (401); check SOCKET_API_TOKEN`                                                                                                                    | Rule (401), where (token), fix (check env var).       |
+
+## Validator / config / build-tool errors (verbose)
+
+The reader is looking at a file and wants to fix the record without
+re-running the tool. Give each ingredient its own words.
+
+✗ `Error: invalid tour config`
+
+✓ `tour.json: part 3 ("Parsing & Normalization") is missing "filename". Add a single-word lowercase filename (e.g. "parsing") to this part — one per part is required to route /<slug>/part/3 at publish time.`
+
+Breakdown:
+
+- **What**: `is missing "filename"` — the rule is "each part has a filename".
+- **Where**: `tour.json: part 3 ("Parsing & Normalization")` — file + record + human label.
+- **Saw vs. wanted**: saw = missing; wanted = a single-word lowercase filename, with `"parsing"` as a concrete model.
+- **Fix**: `Add … to this part` — imperative, specific.
+
+The trailing `to route /<slug>/part/3 at publish time` is optional. Include a _why_ clause only when the rule is non-obvious; skip it for rules the reader already knows (e.g. "names can't start with an underscore").
+
+## Programmatic errors (terse, rule only)
+
+Internal assertions and invariant checks. No end user will read them;
+terse keeps the assertion readable when you skim the code.
+
+- ✓ `assert(queue.length > 0)` with message `queue drained before worker exit`
+- ✓ `pool size must be positive`
+- ✗ `An unexpected error occurred while trying to acquire a connection from the pool because the pool size was not positive.` — nothing a maintainer can act on that the rule itself doesn't already say.
+
+## Common anti-patterns
+
+**"Invalid X" with no rule.**
+
+- ✗ `Invalid filename 'My Part'`
+- ✓ `filename 'My Part' must be [a-z]+ (lowercase, no spaces)`
+
+**Passive voice on the fix.**
+
+- ✗ `"filename" was missing`
+- ✓ `add "filename" to part 3`
+
+**Naming only one side of a collision.**
+
+- ✗ `duplicate key "foo"` (which record won, which lost?)
+- ✓ `duplicate key "foo" in config.json (lines 12 and 47) — rename one`
+
+**Silently auto-correcting.**
+
+- ✗ Stripping a trailing slash from a URL and continuing. The next run will hit the same bug; nothing learned.
+- ✓ `url "https://api/" has a trailing slash — remove it`.
+
+**Bloat that restates the rule.**
+
+- ✗ `The value provided for "timeout" is invalid because timeouts must be positive numbers and the value you provided was not a positive number.`
+- ✓ `timeout must be a positive number (saw: -5)`
+
+## Formatting lists of values
+
+When the error needs to show an allowed set, a list of conflicting
+records, or multiple missing fields, use the list formatters from
+`@socketsecurity/lib/arrays` rather than hand-joining with commas:
+
+- `joinAnd(['a', 'b', 'c'])` → `"a, b, and c"` — for conjunctions ("missing foo, bar, and baz")
+- `joinOr(['npm', 'pypi', 'maven'])` → `"npm, pypi, or maven"` — for disjunctions ("must be one of: …")
+
+Both wrap `Intl.ListFormat`, so the Oxford comma and one-/two-item cases come out right for free (`joinOr(['a'])` → `"a"`; `joinOr(['a', 'b'])` → `"a or b"`).
+
+- ✗ `--reach-ecosystems must be one of: npm, pypi, maven (saw: "foo")` — hand-joined, breaks if the list has one or two entries.
+- ✓ `` `--reach-ecosystems must be one of: ${joinOr(ALLOWED)} (saw: "foo")` ``
+- ✗ `missing keys: filename slug title` — no separators, no grammar.
+- ✓ `` `missing keys: ${joinAnd(missing)}` `` → `"missing keys: filename, slug, and title"`
+
+Use `joinOr` whenever the error is "must be one of X", `joinAnd` whenever it's "all of X are required / missing / in conflict".
+
+## Working with caught values
+
+`catch (e)` binds `unknown`. The helpers in `@socketsecurity/lib/errors` cover the four patterns that recur everywhere:
+
+```ts
+import {
+  errorMessage,
+  errorStack,
+  isError,
+  isErrnoException,
+} from '@socketsecurity/lib/errors'
+```
+
+### `isError(value)` — replaces `value instanceof Error`
+
+Cross-realm-safe. Uses the native ES2025 `Error.isError` when the engine ships it, falls back to a spec-compliant shim otherwise. Catches Errors from worker threads, `vm` contexts, and iframes that same-realm `instanceof Error` silently misses.
+
+- ✗ `if (e instanceof Error) { … }`
+- ✓ `if (isError(e)) { … }`
+
+### `isErrnoException(value)` — replaces `'code' in err` guards
+
+Narrows to `NodeJS.ErrnoException` (an Error with a string `code` set by libuv/syscalls like `ENOENT`, `EACCES`, `EBUSY`, `EPERM`). Builds on `isError`, so it's also cross-realm-safe, and it checks that `code` is a string — a merely branded Error without a real errno code returns `false`.
+
+- ✗ `if (e && typeof e === 'object' && 'code' in e && e.code === 'ENOENT') { … }`
+- ✓ `if (isErrnoException(e) && e.code === 'ENOENT') { … }`
+
+### `errorMessage(value)` — replaces the `instanceof Error ? e.message : String(e)` pattern
+
+Walks the `cause` chain via `messageWithCauses`, coerces primitives and objects to string, and returns the shared `UNKNOWN_ERROR` sentinel (the string `'Unknown error'`) for `null`, `undefined`, empty strings, `[object Object]`, or Errors with no message.
+
+That last bullet is the important one: **every `|| 'Unknown error'` fallback in the fleet should collapse into a single `errorMessage(e)` call.**
+
+- ✗ `` `Failed: ${e instanceof Error ? e.message : String(e)}` ``
+- ✗ `` `Failed: ${(e as Error)?.message ?? 'Unknown error'}` ``
+- ✗ `` `Failed: ${e instanceof Error ? e.message : 'Unknown error'}` ``
+- ✓ `` `Failed: ${errorMessage(e)}` ``
+
+When you want to preserve the cause chain upstream (recommended), pair it with `{ cause }`:
+
+```ts
+try {
+  await readConfig(path)
+} catch (e) {
+  throw new Error(`Failed to read ${path}: ${errorMessage(e)}`, { cause: e })
+}
+```
+
+### `errorStack(value)` — cause-aware stack, or `undefined`
+
+Returns the cause-walking stack for Errors; returns `undefined` for non-Errors so logger calls stay safe:
+
+```ts
+logger.error(`rebuild failed: ${errorMessage(e)}`, { stack: errorStack(e) })
+```
+
+## Voice & tone
+
+- Imperative for the fix: `rename`, `add`, `remove`, `set`.
+- Present tense for the rule: `must be`, `cannot`, `is required`.
+- No apology ("Sorry, …"), no blame ("You provided …"). State the rule and the fix.
+- Don't end with "please"; it doesn't add information and it makes the message feel longer than it is.
+
+## Bloat check
+
+Before shipping a message, cross out any word that, if removed, leaves the information intact. If only rhythm or politeness disappears, drop it.
diff --git a/docs/claude.md/inclusive-language.md b/docs/claude.md/inclusive-language.md
new file mode 100644
index 0000000..b34fb85
--- /dev/null
+++ b/docs/claude.md/inclusive-language.md
@@ -0,0 +1,34 @@
+# Inclusive language reference
+
+The fleet uses precise, neutral terms over historical metaphors that imply hierarchy or exclusion. The substitutes are not euphemisms — they're more _accurate_ (a list of allowed values genuinely is an "allowlist"; "whitelist" is a metaphor that hides what the list does).
+
+## Substitution table
+
+| Replace                          | With                                                |
+| -------------------------------- | --------------------------------------------------- |
+| `whitelist` / `whitelisted`      | `allowlist` / `allowed` / `allowlisted`             |
+| `blacklist` / `blacklisted`      | `denylist` / `denied` / `blocklisted` / `blocked`   |
+| `master` (branch, process, copy) | `main` (branch); `primary` / `controller` (process) |
+| `slave`                          | `replica`, `worker`, `secondary`, `follower`        |
+| `grandfathered`                  | `legacy`, `pre-existing`, `exempted`                |
+| `sanity check`                   | `quick check`, `confidence check`, `smoke test`     |
+| `dummy` (placeholder)            | `placeholder`, `stub`                               |
+
+## Where to apply
+
+- **Code**: identifiers, comments, string literals.
+- **Docs**: READMEs, CLAUDE.md, markdown.
+- **Config**: YAML, JSON.
+- **History**: commit messages, PR titles/descriptions.
+- **CI logs** you control.
+
+## Two narrow exceptions
+
+The legacy term must remain only when changing it would break something external:
+
+- **Third-party APIs / upstream code**: when interfacing with an external API field literally named `whitelist`, keep the field name; rename your local variable. Example: `const allowedDomains = response.whitelist`.
+- **Vendored upstream sources**: don't rewrite vendored code under `vendor/**`, `upstream/**`, or `**/fixtures/**`. Patch around it if needed.
+
+## When to fix
+
+When you encounter a legacy term during unrelated work, fix it inline — don't defer.
diff --git a/docs/claude.md/no-local-fork-canonical.md b/docs/claude.md/no-local-fork-canonical.md
new file mode 100644
index 0000000..a76096f
--- /dev/null
+++ b/docs/claude.md/no-local-fork-canonical.md
@@ -0,0 +1,46 @@
+# Never fork fleet-canonical files locally
+
+Fleet-canonical files (anything tracked by `socket-wheelhouse/scripts/sync-scaffolding/manifest.mts`) MUST be edited in `socket-wheelhouse/template/...` and cascaded out — never branched locally in a downstream fleet repo.
+
+## Canonical surfaces
+
+These directories and files cascade fleet-wide. They are **not** repo-local:
+
+- `.config/oxlint-plugin/` — plugin index + rules
+- `.git-hooks/` — commit-msg / pre-commit / pre-push hooks + helpers
+- `.claude/hooks/` — PreToolUse / PostToolUse hooks
+- `.claude/skills/_shared/` — shared skill helpers
+- `CLAUDE.md` fleet block (between `BEGIN/END FLEET-CANONICAL` markers)
+- `docs/claude.md/` — CLAUDE.md offshoot references (this file lives here)
+- `.husky/` — Husky entry shims
+- Anything else listed in the sync manifest
+
+If unsure, check `socket-wheelhouse/scripts/sync-scaffolding/manifest.mts`. Tracked = canonical.
+
+## How to apply
+
+If a downstream repo needs a behavior change in one of these files:
+
+1. Edit the file in `socket-wheelhouse/template/...`.
+2. Commit the template change.
+3. Run `node scripts/sync-scaffolding/main.mts --target <downstream-repo> --fix` to cascade.
+
+Do NOT edit the local copy in the downstream repo and rely on cascades to "preserve" your edits via `git checkout HEAD --` workarounds. That creates drift the sync mechanism then has to dance around, blocking other improvements from reaching that file in that repo.
+
+## Spotting drift to lift
+
+If you spot a useful predicate / helper / test / behavior in a fleet-canonical file in a downstream repo that is **not** in the template, that is a bug. Lift it up first, then re-cascade.
+
+The fix is mechanical:
+
+1. Diff the downstream version vs the template version.
+2. Identify the additions (if there are any subtractions, those are also drift — usually they need to be added back to the downstream repo via a cascade).
+3. Add the additions to the template.
+4. Commit + push the template.
+5. Re-cascade the downstream repo (overwrites its local copy with the now-superset canonical version).
+
+## Why this matters
+
+Local forks turn into "drift to preserve" hacks. Every cascade subagent has to be told to skip the locally-forked file, which makes the cascade fragile. Worse, those forks block fleet-wide improvements from reaching the forked repo: when the template's version of the file gets a real upgrade (e.g. a new fix predicate, a new exception case), the downstream repo's local copy never gets it.
+
+The fleet's value is the shared canon. Branching locally splits the canon and erodes the value.
diff --git a/docs/claude.md/sorting.md b/docs/claude.md/sorting.md
new file mode 100644
index 0000000..5917059
--- /dev/null
+++ b/docs/claude.md/sorting.md
@@ -0,0 +1,18 @@
+# Sorting reference
+
+Sort lists alphanumerically (literal byte order, ASCII before letters).
+
+## Where to sort
+
+- **Config lists** — `permissions.allow` / `permissions.deny` in `.claude/settings.json`, `external-tools.json` checksum keys, allowlists in workflow YAML.
+- **Object key entries** — keys in plain JSON config + return-shape literals + internal-state objects. (Exception: `__proto__: null` always comes first, ahead of any data keys.)
+- **Import specifiers** — sort named imports inside a single statement: `import { encrypt, randomDataKey, wrapKey } from './crypto.mts'`. `import type` follows the same rule. Statement _order_ (`node:` → external → local → types) is separate from specifier order _within_ a statement.
+- **Method / function placement** — within a module, sort top-level functions alphabetically. Convention: private functions (lowercase / un-exported) sort first, exported functions second. The `export` keyword is the divider.
+- **Array literals** — when the array is a config list, allowlist, or set-like collection. Position-bearing arrays (e.g. `argv`, anything where index matters semantically) keep their meaningful order.
+- **`Set` constructor arguments** — `new Set([...])` and `new SafeSet([...])` literals. The runtime is order-insensitive, so source order is alphanumeric. Same rationale as Array literals: predictable diffs, no merge conflicts on insertions.
+- **Regex alternation groups** — `(foo|bar|baz)` reads as `(bar|baz|foo)`. Capturing, non-capturing, and named-capture groups all follow the rule. Auto-fixable when every alternative is a simple literal. The exception is order-bearing alternations where the regex engine MUST try one alternative before another (rare; the canonical example is markup parsers where `<!--|-->` would silently mismatch if reordered) — append `// socket-hook: allow regex-alternation-order` on those lines.
+- **String-equality disjunctions** — `x === 'a' || x === 'b' || x === 'c'` reads with the comparand strings in alpha order. The De Morgan dual `x !== 'a' && x !== 'b'` (negative-membership check) follows the same rule. The `||` chain short-circuits regardless of operand order; sorting reduces diff churn when adding new comparands and makes "is X in this set?" checks visually consistent. Auto-fixable when every clause has the same left operand and uses string-literal comparands. Mixed shape (different left, different operator, non-string right) is skipped — those are usually genuine ordering-sensitive predicates and the autofix would change semantics.
+
+## Default
+
+When in doubt, sort. The cost of a sorted list that didn't need to be is approximately zero; the cost of an unsorted list that did need to be is a merge conflict.
diff --git a/scripts/ai-lint-fix.mts b/scripts/ai-lint-fix.mts
new file mode 100644
index 0000000..de8721c
--- /dev/null
+++ b/scripts/ai-lint-fix.mts
@@ -0,0 +1,452 @@
+/* oxlint-disable socket/inclusive-language -- AI-fix orchestrator documents the rules it handles, including the legacy terms each rule scans for. */
+
+/**
+ * @fileoverview AI-assisted lint fix step.
+ *
+ * Runs after `pnpm run lint --fix` (oxlint + oxfmt deterministic
+ * autofix) to handle the lint findings that aren't safely
+ * mechanically fixable. The CLAUDE.md "Lint rules" guidance is to
+ * autofix when the rewrite is unambiguous; what's left after the
+ * deterministic pass is by definition the judgment-call set.
+ *
+ * Pipeline:
+ *
+ *   1. Run `pnpm run lint --json` to capture remaining violations.
+ *   2. If there are any findings the AI step is allowed to handle,
+ *      build a per-file batch and spawn a headless `claude --print`
+ *      with Sonnet, the four lockdown flags, and a tight tool list
+ *      (Read, Edit, Grep, Glob). Each spawn handles one file's
+ *      worth of findings to keep the context window predictable.
+ *   3. After all spawns finish, re-run `pnpm run lint` (without
+ *      --fix) to verify nothing got worse. If the count went up,
+ *      log a warning and exit non-zero.
+ *
+ * Skipped silently:
+ *   - When the `claude` CLI isn't on PATH.
+ *   - When `SKIP_AI_FIX=1` is set (CI sets this; AI-fix runs locally).
+ *   - When `--no-ai` is passed.
+ *
+ * The four lockdown flags per CLAUDE.md "Programmatic Claude calls":
+ *   - tools / allowedTools / disallowedTools / permissionMode.
+ *
+ * Cost / safety:
+ *   - Sonnet 4.6, not Opus — judgment work but not architecturally
+ *     deep; cost-tier-appropriate.
+ *   - Per-file batches with a 5-minute timeout — bounds runaway loops.
+ *   - Tools restricted to Read/Edit/Grep/Glob — no Bash, no Write of
+ *     new files. The AI can only edit files that already exist.
+ *   - permissionMode `acceptEdits` so Edit calls don't deadlock on
+ *     the missing AskUserQuestion surface.
+ */
+
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+import { isSpawnError, spawn } from '@socketsecurity/lib/spawn'
+
+const logger = getDefaultLogger()
+
+// Rules below need an AI-driven fix because the right rewrite
+// depends on surrounding code structure that a regex / AST pass can't
+// safely infer. Each one IS fixable — the AI step does the work.
+// The deterministic linter already handled the unambiguous shapes;
+// what remains is the structural-rewrite set.
+const AI_HANDLED_RULES = new Set([
+  // master/slave — context decides main/primary/controller vs
+  // replica/worker. Other forms (whitelist/blacklist/etc.) auto-fix.
+  'socket/inclusive-language',
+  // Literal username in a user-home path. In source: substitute a
+  // placeholder / env-var / delete. In WASM or generated bundles:
+  // the bundler is leaking the path — fix the build config.
+  'socket/personal-path-placeholders',
+  // fs.access / fs.stat existence checks. AI rewrites the try/catch
+  // → if/else and preserves metadata calls when the result is
+  // destructured. Wrapper-name shapes (fileExists / pathExists /
+  // isFile / isDir) auto-fix deterministically.
+  'socket/prefer-exists-sync',
+  // node:fs default/namespace where references are "weird" (computed
+  // access, passed as a value, reassigned). Plain `fs.X` shapes
+  // auto-fix via scope rename.
+  'socket/prefer-node-builtin-imports',
+  // spawnSync where the call site isn't already in async context or
+  // its return value is consumed (assignment, property access).
+  // await/expression-statement shapes auto-fix.
+  'socket/prefer-async-spawn',
+  // null whose surrounding type annotation also mentions null. AI
+  // flips BOTH the annotation and the value in lockstep through the
+  // function signatures / interfaces / return types involved.
+  // Cross-file ripple is handled by per-file passes on the next run.
+  'socket/prefer-undefined-over-null',
+  // File splitting needs to choose natural seams.
+  'socket/max-file-lines',
+  // Placeholder finishes need actual implementation.
+  'socket/no-placeholders',
+  // No-fetch needs httpJson/httpText/httpRequest decision based on
+  // how the response is consumed.
+  'socket/no-fetch-prefer-http-request',
+])
+
+interface OxlintMessage {
+  ruleId?: string
+  message: string
+  severity: number
+  line: number
+  column: number
+  endLine?: number
+  endColumn?: number
+}
+
+interface OxlintFile {
+  filePath: string
+  messages: OxlintMessage[]
+}
+
+interface CliArgs {
+  noAi: boolean
+  staged: boolean
+  all: boolean
+  passthrough: string[]
+}
+
+function parseArgs(argv: readonly string[]): CliArgs {
+  const passthrough: string[] = []
+  let noAi = false
+  let staged = false
+  let all = false
+  for (const arg of argv) {
+    if (arg === '--no-ai') {
+      noAi = true
+      continue
+    }
+    if (arg === '--staged') {
+      staged = true
+      passthrough.push(arg)
+      continue
+    }
+    if (arg === '--all') {
+      all = true
+      passthrough.push(arg)
+      continue
+    }
+    passthrough.push(arg)
+  }
+  return { all, noAi, passthrough, staged }
+}
+
+async function runLintJson(
+  passthrough: readonly string[],
+): Promise<OxlintFile[]> {
+  // Run oxlint directly with --format=json. Bypass `pnpm run lint`
+  // because that wrapper formats for humans.
+  const args = [
+    'exec',
+    'oxlint',
+    '--format=json',
+    '--config=.config/oxlintrc.json',
+    ...passthrough.filter(a => a !== '--all'),
+  ]
+  if (!passthrough.includes('--all') && !passthrough.includes('--staged')) {
+    args.push('.')
+  }
+  let stdout = ''
+  try {
+    const result = await spawn('pnpm', args, {
+      shell: process.platform === 'win32',
+      stdio: 'pipe',
+      stdioString: true,
+    })
+    stdout = String(result.stdout ?? '')
+  } catch (e) {
+    if (isSpawnError(e)) {
+      // oxlint exits non-zero when there are violations — that's
+      // expected. Read stdout regardless.
+      stdout = String(e.stdout ?? '')
+    } else {
+      throw e
+    }
+  }
+  if (!stdout.trim()) {
+    return []
+  }
+  try {
+    const parsed = JSON.parse(stdout) as OxlintFile[]
+    if (!Array.isArray(parsed)) {
+      return []
+    }
+    return parsed
+  } catch {
+    logger.warn('oxlint JSON parse failed; skipping AI-fix')
+    return []
+  }
+}
+
+function bucketFindings(files: OxlintFile[]): Map<string, OxlintMessage[]> {
+  const byFile = new Map<string, OxlintMessage[]>()
+  for (const f of files) {
+    const handled = f.messages.filter(
+      m => m.ruleId && AI_HANDLED_RULES.has(m.ruleId),
+    )
+    if (handled.length === 0) {
+      continue
+    }
+    byFile.set(f.filePath, handled)
+  }
+  return byFile
+}
+
+/**
+ * Per-rule guidance — concise, low-freedom (one canonical rewrite
+ * per rule). Built per Anthropic's prompt-engineering best practices:
+ * direct instructions, XML structure, examples per rule.
+ *
+ * Each entry is rendered into the prompt as `<rule id="...">…</rule>`
+ * inside a `<rules>` block. Claude sees only the rules that fired in
+ * the current file, so noise stays low.
+ */
+const RULE_GUIDANCE = {
+  // oxlint-disable-next-line socket/prefer-undefined-over-null -- null-prototype object literal.
+  __proto__: null,
+  // oxlint-disable-next-line socket/inclusive-language -- rule guidance string documents the legacy terms it scans for.
+  'socket/inclusive-language':
+    'Replace `master`/`slave` with the contextually correct term: `main` (branch), `primary`/`controller` (process), `replica`/`worker`/`secondary`/`follower` (subordinate). Read the surrounding code to pick the right one. Do not autofix when an external API field name forces the legacy term — leave a `// inclusive-language: external-api` comment instead.',
+  'socket/personal-path-placeholders':
+    "Two scenarios. (1) Source code / docs / tests: replace literal usernames in user-home paths with the canonical placeholder — `<user>` for /Users/ and /home/, `<USERNAME>` for C:\\Users\\. Env-var forms (`$HOME`, `${USER}`, `%USERNAME%`) are also acceptable. (2) WASM / generated bundles / minified output: a literal username inside compiled output means the bundler is leaking the developer's path. Trace back to the build config (esbuild / rolldown / webpack `sourcemap`, `sourceRoot`, `__dirname` baking, fs.realpath calls in plugins) and fix THAT — do not chase the string in the artifact.",
+  'socket/prefer-exists-sync':
+    'Rewrite `fs.access` / `fs.stat` existence-checks to `existsSync(p)` from `node:fs`. Common shapes: `try { await fs.access(p); return true } catch { return false }` → `return existsSync(p)`. `await fs.access(p).then(() => true).catch(() => false)` → `existsSync(p)`. `if (await fs.stat(p))` → `if (existsSync(p))`. When the stat result is destructured for metadata (`s.size`, `s.mtime`, `s.isDirectory()`), KEEP the stat call and add a one-line comment stating intent — that is not an existence check. Trace back through callers: if the caller awaited a Promise<boolean>, the rewrite collapses to a sync boolean and the await becomes a no-op (safe).',
+  'socket/prefer-node-builtin-imports':
+    "Rewrite `import fs from 'node:fs'` / `import * as fs from 'node:fs'` to `import { … } from 'node:fs'` with the names actually used in the file. Change every `fs.X` reference to bare `X`. If `fs` is passed as a value (e.g. `someApi(fs)`), keep the namespace import and add a `// prefer-node-builtin-imports: passed-as-value` comment.",
+  'socket/prefer-async-spawn':
+    'Replace `spawnSync` from `node:child_process` with async `spawn` from `@socketsecurity/lib/spawn`. The lib spawn returns a thenable that yields `{ code, stdout, stderr }`; await it. If the caller is genuinely sync (no async ancestor, top-level CommonJS), leave the call and add a `// prefer-async-spawn: sync-required` comment.',
+  'socket/prefer-undefined-over-null':
+    'In the target file, flip BOTH the value and the surrounding type annotation in lockstep: `let x: string | null = null` → `let x: string | undefined = undefined`. Apply to function-parameter annotations, return-type annotations, generic-parameter constraints, interface / type-alias members. For tight-equality checks in the same file: `x === null` → `x === undefined` (loose `x == null` already covers both — leave loose-equality alone). DO NOT edit other files; if a caller in another file depends on the type, the lint rule will fire there on the next run and a separate AI-fix subprocess will pick it up. Skip the finding if the type is a third-party API contract you cannot change (e.g. a return type from a library).',
+  'socket/max-file-lines':
+    'Split the file along its natural seams: one tool/domain/phase per file. Name the new files descriptively (`spawn-cdxgen.mts`, `parse-arguments.mts`). Update import paths in callers. Do not introduce a barrel just to hide the split. If the file is a single legitimate parser/state-machine/table, add a leading `// max-file-lines: legitimate parser` comment instead of splitting.',
+  'socket/no-placeholders':
+    'Implement the placeholder. If the work is too large, do NOT delete the marker — leave the file unchanged and explain in your final reply.',
+  'socket/no-fetch-prefer-http-request':
+    'Replace `fetch(url, opts)` with the right helper from `@socketsecurity/lib/http-request`: `httpJson` when the caller calls `.json()` on the response, `httpText` when it calls `.text()`, `httpRequest` for raw access. Add the named import.',
+} as unknown as Readonly<Record<string, string>>
+
+function renderFindings(findings: OxlintMessage[], _rel: string): string {
+  return findings
+    .map(
+      f =>
+        `<finding rule="${f.ruleId}" line="${f.line}" column="${f.column}">${f.message
+          .replace(/[<>&]/g, ch =>
+            ch === '<' ? '&lt;' : ch === '>' ? '&gt;' : '&amp;',
+          )
+          .replace(/\n/g, ' ')}</finding>`,
+    )
+    .map(line => `  ${line}`)
+    .join('\n')
+}
+
+function renderRuleGuidance(findings: OxlintMessage[]): string {
+  const seen = new Set<string>()
+  for (const f of findings) {
+    if (f.ruleId) {
+      seen.add(f.ruleId)
+    }
+  }
+  const entries = [...seen]
+    .sort()
+    .map(id => {
+      const guidance = RULE_GUIDANCE[id]
+      if (!guidance) {
+        return ''
+      }
+      return `  <rule id="${id}">${guidance}</rule>`
+    })
+    .filter(s => s.length > 0)
+  if (entries.length === 0) {
+    return ''
+  }
+  return `<rules>\n${entries.join('\n')}\n</rules>`
+}
+
+/**
+ * Build the per-file prompt. Structure follows Anthropic's prompt-
+ * engineering best practices for headless tool-use:
+ *   - <task>: one-sentence framing.
+ *   - <file>: the target path. Edits must stay scoped to it.
+ *   - <findings>: machine-readable list of violations.
+ *   - <rules>: per-rule canonical rewrite (low freedom).
+ *   - <constraints>: hard rules — no Bash, no Write, single-file scope.
+ *   - <output>: response format expectation.
+ *
+ * The prompt is deliberately short. Claude already knows what oxlint
+ * is, what the rule names mean (the rules are project-specific, but
+ * the guidance block carries enough context), and how to use Edit /
+ * Read. Adding boilerplate dilutes the instructions.
+ */
+function buildPrompt(filePath: string, findings: OxlintMessage[]): string {
+  const rel = path.relative(process.cwd(), filePath)
+  const findingsBlock = renderFindings(findings, rel)
+  const rulesBlock = renderRuleGuidance(findings)
+  return `<task>Fix the lint findings in a single source file.</task>
+
+<file>${rel}</file>
+
+<findings>
+${findingsBlock}
+</findings>
+
+${rulesBlock}
+
+<constraints>
+  <constraint>Read ${rel} with the Read tool before editing.</constraint>
+  <constraint>Apply the minimum change needed to satisfy each finding. Preserve unrelated code, comments, and formatting.</constraint>
+  <constraint>Edit only ${rel}. Do not create new files. Do not run Bash commands.</constraint>
+  <constraint>If a finding requires changes you cannot safely make (e.g. file split, real implementation of a placeholder), skip it and state why in your reply. Do not delete the marker.</constraint>
+  <constraint>If your fix could break callers in other files, skip the finding and state why.</constraint>
+</constraints>
+
+<output>One short sentence summarizing what you changed. No markdown, no code blocks, no preamble.</output>`
+}
+
+async function runClaudeFix(
+  _filePath: string,
+  prompt: string,
+  cwd: string,
+): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  const claudeArgs = [
+    '--print',
+    '--model',
+    'claude-sonnet-4-6',
+    '--permission-mode',
+    'acceptEdits',
+    '--no-session-persistence',
+    '--add-dir',
+    cwd,
+    '--allowedTools',
+    'Read',
+    'Edit',
+    'Grep',
+    'Glob',
+    '--disallowedTools',
+    'Bash',
+    'Write',
+    'WebFetch',
+    'WebSearch',
+    'Agent',
+  ]
+  let stdout = ''
+  let stderr = ''
+  let exitCode = 0
+  try {
+    const child = spawn('claude', claudeArgs, {
+      cwd,
+      stdio: 'pipe',
+      stdioString: true,
+      timeout: 5 * 60 * 1000,
+    })
+    child.stdin?.end(prompt)
+    const result = await child
+    stdout = String(result.stdout ?? '')
+    stderr = String(result.stderr ?? '')
+    exitCode = result.code ?? 0
+  } catch (e) {
+    if (isSpawnError(e)) {
+      stdout = String(e.stdout ?? '')
+      stderr = String(e.stderr ?? '')
+      exitCode = e.code ?? 1
+    } else {
+      stderr = e instanceof Error ? e.message : String(e)
+      exitCode = 1
+    }
+  }
+  return { exitCode, stderr, stdout }
+}
+
+async function hasClaudeCli(): Promise<boolean> {
+  try {
+    const result = await spawn('claude', ['--version'], {
+      shell: process.platform === 'win32',
+      stdio: 'pipe',
+      stdioString: true,
+      timeout: 5000,
+    })
+    return result.code === 0
+  } catch {
+    return false
+  }
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.noAi) {
+    return
+  }
+  if (process.env['SKIP_AI_FIX'] === '1') {
+    return
+  }
+  if (!existsSync('.config/oxlintrc.json')) {
+    return
+  }
+
+  const files = await runLintJson(args.passthrough)
+  const byFile = bucketFindings(files)
+  if (byFile.size === 0) {
+    return
+  }
+
+  if (!(await hasClaudeCli())) {
+    const total = [...byFile.values()].reduce((n, m) => n + m.length, 0)
+    logger.warn(
+      `${total} AI-handled lint findings remain in ${byFile.size} files; skipping AI-fix step (claude CLI not on PATH).`,
+    )
+    return
+  }
+
+  const cwd = process.cwd()
+  let totalEdits = 0
+  let totalErrors = 0
+
+  for (const [filePath, findings] of byFile) {
+    const rel = path.relative(cwd, filePath)
+    logger.log(`AI-fix ${rel} (${findings.length} findings)…`)
+    const prompt = buildPrompt(filePath, findings)
+    const { exitCode, stderr } = await runClaudeFix(filePath, prompt, cwd)
+    if (exitCode === 0) {
+      totalEdits += findings.length
+      continue
+    }
+    totalErrors++
+    logger.warn(`AI-fix exited ${exitCode} for ${rel}: ${stderr.slice(0, 200)}`)
+  }
+
+  // Verification — re-run lint and count remaining AI-handled
+  // findings. Per CLAUDE.md / Anthropic best practices, "give Claude
+  // a way to verify its work" is the highest-leverage thing; we do
+  // it at the script level since the AI subprocesses don't have Bash.
+  const beforeCount = [...byFile.values()].reduce((n, m) => n + m.length, 0)
+  const afterFiles = await runLintJson(args.passthrough)
+  const afterByFile = bucketFindings(afterFiles)
+  const afterCount = [...afterByFile.values()].reduce((n, m) => n + m.length, 0)
+
+  if (totalErrors > 0) {
+    logger.warn(
+      `AI-fix finished with ${totalErrors} subprocess errors. ${afterCount}/${beforeCount} findings remain. Re-run \`pnpm run lint\` to see what survived.`,
+    )
+    process.exitCode = 1
+    return
+  }
+  if (afterCount > beforeCount) {
+    logger.warn(
+      `AI-fix introduced regressions: ${beforeCount} → ${afterCount} findings. Inspect the changes.`,
+    )
+    process.exitCode = 1
+    return
+  }
+  logger.log(
+    `AI-fix attempted ${totalEdits} findings across ${byFile.size} files (${beforeCount} → ${afterCount} remaining).`,
+  )
+}
+
+main().catch((e: unknown) => {
+  const msg = e instanceof Error ? e.message : String(e)
+  logger.error(`ai-lint-fix: ${msg}`)
+  process.exitCode = 1
+})
diff --git a/scripts/check-paths.mts b/scripts/check-paths.mts
new file mode 100644
index 0000000..99443e9
--- /dev/null
+++ b/scripts/check-paths.mts
@@ -0,0 +1,953 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Path-hygiene gate.
+ *
+ * Mantra: 1 path, 1 reference. A path is constructed exactly once;
+ * everywhere else references the constructed value.
+ *
+ * Whole-repo scan complementing the per-edit `.claude/hooks/path-guard`
+ * hook. The hook stops new violations from landing; this gate finds
+ * the existing ones and blocks merges that introduce more.
+ *
+ * Rules enforced:
+ *
+ *   A — Multi-stage path constructed inline. A `path.join(...)` call
+ *       (or template literal) in a `.mts`/`.cts` file outside a
+ *       `paths.mts` that stitches together two or more "stage"
+ *       segments (Final, Release, Stripped, Compressed, Optimized,
+ *       Synced, wasm, downloaded), or one stage plus a build-root
+ *       (`build`/`out`) plus a mode (`dev`/`prod`/`shared`). The
+ *       construction belongs in the package's `paths.mts` (or a
+ *       build-infra helper); every consumer imports the computed
+ *       value.
+ *
+ *   B — Cross-package path traversal. A `path.join(*, '..', '<sibling
+ *       package>', 'build', ...)` reaches into a sibling's build
+ *       output without going through its `exports`. The sibling owns
+ *       its layout; consumers declare a workspace dep and import the
+ *       sibling's `paths.mts`.
+ *
+ *   C — Hand-built workflow path. A `.github/workflows/*.yml` step
+ *       constructs `build/${...}/out/<stage>/...` inline outside a
+ *       canonical "Compute paths" step. Workflows can carry path
+ *       strings, but the strings are constructed once and exposed via
+ *       step outputs / job env that downstream steps reference.
+ *
+ *   D — Comment-encoded paths. Comments (in code or YAML) that re-state
+ *       a fully-qualified multi-stage path. Comments may describe the
+ *       structure ("Final dir" or "build/<mode>/...") but should not
+ *       encode a complete path string that a tool would parse — the
+ *       canonical construction IS the documentation.
+ *
+ *   F — Same path constructed in multiple places. The same shape of
+ *       multi-stage `path.join(...)` (or workflow `build/${...}/...`
+ *       string template) appearing in two or more files. Construct
+ *       once and import; references of the constructed value are
+ *       unlimited.
+ *
+ *   G — Hand-built paths in Makefiles, Dockerfiles, and shell scripts.
+ *       Same shape as A, applied to executable artifacts that don't
+ *       run TypeScript. Each canonical construction must carry a
+ *       comment naming the source-of-truth `paths.mts` so the script
+ *       can't drift from TS without a flagged change.
+ *
+ * Allowlist: `.github/paths-allowlist.yml`. Each entry needs a
+ * `reason` so the list stays audit-able. Patterns are deliberately
+ * narrow — entries should be specific, not blanket.
+ *
+ * Usage:
+ *   node scripts/check-paths.mts             # default: report + fail
+ *   node scripts/check-paths.mts --explain   # long-form explanation
+ *   node scripts/check-paths.mts --json      # machine-readable
+ *   node scripts/check-paths.mts --quiet     # silent on clean
+ *
+ * Exit codes:
+ *   0 — clean (no findings, or every finding is allowlisted)
+ *   1 — findings present
+ *   2 — gate itself crashed
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+
+import { fileURLToPath } from 'node:url'
+
+import { parseArgs } from 'node:util'
+
+import {
+  BUILD_ROOT_SEGMENTS,
+  KNOWN_SIBLING_PACKAGES,
+  MODE_SEGMENTS,
+  STAGE_SEGMENTS,
+} from '../.claude/hooks/path-guard/segments.mts'
+
+// Plain stderr/stdout output — no @socketsecurity/lib dependency so
+// the gate is self-contained and works in socket-lib itself (which
+// would otherwise import itself).
+const logger = {
+  log: (msg: string) => process.stdout.write(msg + '\n'),
+  error: (msg: string) => process.stderr.write(msg + '\n'),
+  step: (msg: string) => process.stdout.write(`→ ${msg}\n`),
+  // oxlint-disable-next-line socket/no-status-emoji -- local logger replica; can't import lib's logger because this gate runs in socket-lib itself.
+  success: (msg: string) => process.stdout.write(`✔ ${msg}\n`),
+  substep: (msg: string) => process.stdout.write(`  ${msg}\n`),
+}
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const REPO_ROOT = path.resolve(__dirname, '..')
+
+// Stage / build-root / mode / sibling-package vocabularies are imported
+// from `.claude/hooks/path-guard/segments.mts` (the canonical source).
+// Both this gate and the path-guard hook share that single definition
+// — Mantra: 1 path, 1 reference.
+
+// File-path patterns that legitimately enumerate path segments.
+const EXEMPT_FILE_PATTERNS: RegExp[] = [
+  // Any paths.mts is the canonical constructor.
+  /(^|\/)paths\.(mts|cts|js)$/,
+  // Build-infra owns shared helpers that enumerate stages.
+  /packages\/build-infra\/lib\/paths\.mts$/,
+  /packages\/build-infra\/lib\/constants\.mts$/,
+  // Path-scanning gates that intentionally enumerate.
+  /scripts\/check-paths\.mts$/,
+  /scripts\/check-consistency\.mts$/,
+  /\.claude\/hooks\/path-guard\//,
+  // Allowlist + config files.
+  /\.github\/paths-allowlist\.yml$/,
+]
+
+type Finding = {
+  rule: 'A' | 'B' | 'C' | 'D' | 'F' | 'G'
+  file: string
+  line: number
+  snippet: string
+  message: string
+  fix: string
+}
+
+const findings: Finding[] = []
+
+const args = parseArgs({
+  options: {
+    explain: { type: 'boolean', default: false },
+    json: { type: 'boolean', default: false },
+    quiet: { type: 'boolean', default: false },
+    'show-hashes': { type: 'boolean', default: false },
+  },
+  strict: false,
+})
+
+const isExempt = (filePath: string): boolean =>
+  EXEMPT_FILE_PATTERNS.some(re => re.test(filePath))
+
+// ──────────────────────────────────────────────────────────────────
+// Allowlist loading
+// ──────────────────────────────────────────────────────────────────
+
+type AllowlistEntry = {
+  file?: string
+  pattern?: string
+  rule?: string
+  line?: number
+  snippet_hash?: string
+  reason: string
+}
+
+const loadAllowlist = (): AllowlistEntry[] => {
+  const allowlistPath = path.join(REPO_ROOT, '.github', 'paths-allowlist.yml')
+  if (!existsSync(allowlistPath)) {
+    return []
+  }
+  const text = readFileSync(allowlistPath, 'utf8')
+  // Tiny YAML parser — only the shape we need: list of entries with
+  // `file`, `pattern`, `rule`, `line`, `reason` scalar fields, plus
+  // YAML 1.2 block-scalar indicators `|` (literal) and `>` (folded)
+  // for multi-line reasons. Avoids a yaml dep for a gate that has to
+  // be self-contained.
+  const entries: AllowlistEntry[] = []
+  let current: Partial<AllowlistEntry> | undefined = undefined
+  // When set, subsequent more-indented lines fold into this key as a
+  // block scalar (literal '|' keeps newlines, folded '>' joins with
+  // spaces).
+  let blockKey: string | undefined = undefined
+  let blockKind: '|' | '>' | undefined = undefined
+  let blockIndent = 0
+  let blockLines: string[] = []
+  const flushBlock = () => {
+    if (current && blockKey) {
+      const value =
+        blockKind === '>'
+          ? blockLines.join(' ').replace(/\s+/g, ' ').trim()
+          : blockLines.join('\n').replace(/\n+$/, '')
+      ;(current as any)[blockKey] = value
+    }
+    blockKey = undefined
+    blockKind = undefined
+    blockLines = []
+  }
+  const indentOf = (line: string): number => {
+    let i = 0
+    while (i < line.length && line[i] === ' ') {
+      i += 1
+    }
+    return i
+  }
+  const lines = text.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i]!
+    const line = raw.replace(/\r$/, '')
+    // Block-scalar accumulation takes precedence over normal parsing.
+    if (blockKey !== null) {
+      if (line.trim() === '') {
+        // Preserve blank lines inside a literal block; folded blocks
+        // turn them into paragraph breaks (kept as separate joins).
+        blockLines.push('')
+        continue
+      }
+      const indent = indentOf(line)
+      if (indent >= blockIndent) {
+        blockLines.push(line.slice(blockIndent))
+        continue
+      }
+      flushBlock()
+      // Fall through and re-process the dedented line as normal.
+    }
+    if (!line.trim() || line.trim().startsWith('#')) {
+      continue
+    }
+    const tryAssign = (key: string, value: string) => {
+      const trimmed = value.trim()
+      if (current === null) {
+        return
+      }
+      if (trimmed === '|' || trimmed === '>') {
+        blockKey = key
+        blockKind = trimmed as '|' | '>'
+        blockIndent = indentOf(lines[i + 1] ?? '') || indentOf(line) + 2
+        blockLines = []
+        return
+      }
+      ;(current as any)[key] =
+        key === 'line' ? Number(unquote(trimmed)) : unquote(trimmed)
+    }
+    if (line.startsWith('- ')) {
+      if (current && current.reason) {
+        entries.push(current as AllowlistEntry)
+      }
+      current = {}
+      const rest = line.slice(2).trim()
+      if (rest) {
+        const m = rest.match(/^([\w-]+):\s*(.*)$/)
+        if (m) {
+          tryAssign(m[1]!, m[2]!)
+        }
+      }
+    } else if (current) {
+      const m = line.match(/^\s+([\w-]+):\s*(.*)$/)
+      if (m) {
+        tryAssign(m[1]!, m[2]!)
+      }
+    }
+  }
+  if (blockKey !== null) {
+    flushBlock()
+  }
+  if (current && current.reason) {
+    entries.push(current as AllowlistEntry)
+  }
+  return entries
+}
+
+const unquote = (s: string): string => {
+  const t = s.trim()
+  if (
+    (t.startsWith('"') && t.endsWith('"')) ||
+    (t.startsWith("'") && t.endsWith("'"))
+  ) {
+    return t.slice(1, -1)
+  }
+  return t
+}
+
+const ALLOWLIST = loadAllowlist()
+
+/**
+ * Stable, normalized snippet hash. Whitespace-insensitive so trivial
+ * reformatting (indent change, trailing comma, line wrap) doesn't
+ * invalidate an allowlist entry, but content-changing edits do. The
+ * hash exposes only the first 12 hex chars (~48 bits) which is plenty
+ * for collision-resistance within a single repo's finding set and
+ * keeps the YAML readable.
+ */
+const snippetHash = (snippet: string): string => {
+  const normalized = snippet.replace(/\s+/g, ' ').trim()
+  return createHash('sha256').update(normalized).digest('hex').slice(0, 12)
+}
+
+/**
+ * Allowlist matching trades off two failure modes:
+ *
+ *   - Drift via reformatting (a line shift breaks an entry, the
+ *     finding re-surfaces, devs paper over with a new entry).
+ *   - Stealth allowlisting (an entry pinned to "anywhere in this file"
+ *     silently exempts unrelated future violations).
+ *
+ * Strategy: exact line match OR `snippet_hash` match (whitespace-
+ * normalized SHA-256, first 12 hex). Either is sufficient. Lines stay
+ * exact (was ±2; the slack let reformatting silently slide), and
+ * `snippet_hash` provides reformatting-tolerant matching that's still
+ * tied to the literal text — paste-and-edit cheating would change the
+ * hash. If neither `line` nor `snippet_hash` is provided, the entry
+ * matches purely by `rule` + `file` + `pattern` (file-level exempt;
+ * use sparingly and always pair with a precise `pattern`).
+ */
+const isAllowlisted = (finding: Finding): boolean =>
+  ALLOWLIST.some(entry => {
+    if (entry.rule && entry.rule !== finding.rule) {
+      return false
+    }
+    if (entry.file && !finding.file.includes(entry.file)) {
+      return false
+    }
+    if (entry.pattern && !finding.snippet.includes(entry.pattern)) {
+      return false
+    }
+    const lineProvided = entry.line !== undefined
+    const hashProvided =
+      typeof entry.snippet_hash === 'string' && entry.snippet_hash.length > 0
+    if (lineProvided || hashProvided) {
+      const lineMatches = lineProvided && entry.line === finding.line
+      const hashMatches =
+        hashProvided && entry.snippet_hash === snippetHash(finding.snippet)
+      if (!(lineMatches || hashMatches)) {
+        return false
+      }
+    }
+    return true
+  })
+
+// ──────────────────────────────────────────────────────────────────
+// File walking
+// ──────────────────────────────────────────────────────────────────
+
+const SKIP_DIRS = new Set([
+  '.git',
+  'node_modules',
+  'build',
+  'dist',
+  'out',
+  'target',
+  '.cache',
+  'upstream',
+])
+
+const walk = function* (
+  dir: string,
+  filter: (relPath: string) => boolean,
+): Generator<string> {
+  let entries
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return
+  }
+  for (const e of entries) {
+    if (SKIP_DIRS.has(e.name)) {
+      continue
+    }
+    const full = path.join(dir, e.name)
+    const rel = path.relative(REPO_ROOT, full)
+    if (e.isDirectory()) {
+      yield* walk(full, filter)
+    } else if (e.isFile() && filter(rel)) {
+      yield rel
+    }
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────
+// Rule A + B: code scan (.mts / .cts)
+// ──────────────────────────────────────────────────────────────────
+
+// Locate `path.join(` or `path.resolve(` call sites; argument-list
+// extraction uses a paren-balancing scanner below to handle arbitrary
+// nesting depth (the previous regex-only approach silently missed any
+// argument containing 2+ levels of nested function calls).
+const PATH_CALL_RE = /\bpath\.(?:join|resolve)\s*\(/g
+const STRING_LITERAL_RE = /(['"])((?:\\.|(?!\1)[^\\])*)\1/g
+
+// Template literal scanner. Captures backtick-delimited strings
+// (including those with `${...}` placeholders) so Rule A also catches
+// path construction via template literals like
+// `${buildDir}/out/Final/${binary}` or `build/${mode}/out/Final`.
+const TEMPLATE_LITERAL_RE =
+  /`((?:\\.|(?:\$\{(?:[^{}]|\{[^{}]*\})*\})|(?!`)[^\\])*)`/g
+
+/**
+ * Convert a template-literal body into a synthetic forward-slash path
+ * by replacing `${...}` placeholders with a sentinel and normalizing
+ * separators. Returns the sequence of path segments split on `/`. The
+ * sentinel doesn't match any STAGE/BUILD_ROOT/MODE token, so a
+ * placeholder-only segment (`${binaryName}`) won't match those sets.
+ */
+const templateLiteralSegments = (body: string): string[] => {
+  // Strip placeholders so they don't introduce noise in segments.
+  // Empty result for a placeholder is fine; downstream filters by set
+  // membership and skips empties.
+  const stripped = body.replace(/\$\{(?:[^{}]|\{[^{}]*\})*\}/g, '\x00')
+  return stripped.split('/').filter(seg => seg.length > 0 && seg !== '\x00')
+}
+
+/**
+ * Extract every `path.join(...)` and `path.resolve(...)` call from the
+ * source text, returning each call's literal start offset and argument
+ * substring. Uses paren-balancing so deeply-nested arguments like
+ * `path.join(getDir(child(x)), 'build', 'Final')` are captured fully.
+ */
+const extractPathCalls = (
+  source: string,
+): Array<{ offset: number; args: string }> => {
+  const calls: Array<{ offset: number; args: string }> = []
+  PATH_CALL_RE.lastIndex = 0
+  let match: RegExpExecArray | null
+  while ((match = PATH_CALL_RE.exec(source)) !== null) {
+    const callStart = match.index
+    const argsStart = PATH_CALL_RE.lastIndex
+    let depth = 1
+    let i = argsStart
+    let inString: '"' | "'" | '`' | undefined = undefined
+    while (i < source.length && depth > 0) {
+      const ch = source[i]!
+      if (inString) {
+        if (ch === '\\') {
+          i += 2
+          continue
+        }
+        if (ch === inString) {
+          inString = undefined
+        }
+      } else {
+        if (ch === '"' || ch === "'" || ch === '`') {
+          inString = ch
+        } else if (ch === '(') {
+          depth += 1
+        } else if (ch === ')') {
+          depth -= 1
+          if (depth === 0) {
+            break
+          }
+        }
+      }
+      i += 1
+    }
+    if (depth === 0) {
+      calls.push({ offset: callStart, args: source.slice(argsStart, i) })
+      PATH_CALL_RE.lastIndex = i + 1
+    }
+  }
+  return calls
+}
+
+const extractStringLiterals = (args: string): string[] => {
+  const literals: string[] = []
+  let match: RegExpExecArray | null
+  STRING_LITERAL_RE.lastIndex = 0
+  while ((match = STRING_LITERAL_RE.exec(args)) !== null) {
+    if (match[2] !== undefined) {
+      literals.push(match[2])
+    }
+  }
+  return literals
+}
+
+const scanCodeFile = (relPath: string): void => {
+  const full = path.join(REPO_ROOT, relPath)
+  let content: string
+  try {
+    content = readFileSync(full, 'utf8')
+  } catch {
+    return
+  }
+  const lines = content.split('\n')
+  // Build a line-offset map so we can map regex offsets back to line
+  // numbers cheaply.
+  const lineOffsets: number[] = [0]
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === '\n') {
+      lineOffsets.push(i + 1)
+    }
+  }
+  const offsetToLine = (offset: number): number => {
+    let lo = 0
+    let hi = lineOffsets.length - 1
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >>> 1
+      if (lineOffsets[mid]! <= offset) {
+        lo = mid
+      } else {
+        hi = mid - 1
+      }
+    }
+    return lo + 1
+  }
+
+  for (const call of extractPathCalls(content)) {
+    const literals = extractStringLiterals(call.args)
+    const stages = literals.filter(l => STAGE_SEGMENTS.has(l))
+    const buildRoots = literals.filter(l => BUILD_ROOT_SEGMENTS.has(l))
+    const modes = literals.filter(l => MODE_SEGMENTS.has(l))
+
+    // Rule A: 2+ stages OR (1 stage + 1 build-root + 1 mode).
+    const triggersA =
+      stages.length >= 2 ||
+      (stages.length >= 1 && buildRoots.length >= 1 && modes.length >= 1)
+    if (triggersA) {
+      const line = offsetToLine(call.offset)
+      const snippet = (lines[line - 1] ?? '').trim()
+      findings.push({
+        rule: 'A',
+        file: relPath,
+        line,
+        snippet,
+        message: 'Multi-stage path constructed inline (outside paths.mts).',
+        fix: 'Construct in the owning paths.mts (or use getFinalBinaryPath / getDownloadedDir from build-infra/lib/paths). Import the computed value here.',
+      })
+    }
+
+    // Rule B: each '..' opens a window; the window stays open only
+    // until the next non-'..' literal. A sibling-package literal
+    // *immediately after* a '..' (no path segment between them)
+    // triggers, AND there must be build context elsewhere in the
+    // call. Resetting per-segment prevents false positives where '..'
+    // appears earlier and sibling-name appears much later in an
+    // unrelated position.
+    const hasBuildContext = literals.some(
+      l => BUILD_ROOT_SEGMENTS.has(l) || STAGE_SEGMENTS.has(l),
+    )
+    if (hasBuildContext) {
+      for (let i = 0; i < literals.length - 1; i++) {
+        if (
+          literals[i] === '..' &&
+          KNOWN_SIBLING_PACKAGES.has(literals[i + 1]!)
+        ) {
+          const sibling = literals[i + 1]!
+          const line = offsetToLine(call.offset)
+          const snippet = (lines[line - 1] ?? '').trim()
+          findings.push({
+            rule: 'B',
+            file: relPath,
+            line,
+            snippet,
+            message: `Cross-package traversal into '${sibling}' build output.`,
+            fix: `Add '${sibling}: workspace:*' as a dep, declare an exports entry on '${sibling}' (e.g. './scripts/paths' → './scripts/paths.mts'), and import the path from there.`,
+          })
+          break
+        }
+      }
+    }
+  }
+
+  // Rule A (template literal variant). Backtick strings like
+  // `${buildDir}/out/Final/${binary}` or `build/${mode}/${arch}/out/Final`
+  // construct paths the same way `path.join(...)` does — flag the
+  // same shapes. Skip raw imports / template tag positions by
+  // filtering out leading `import.meta.url`-style / tag positions
+  // implicitly: TEMPLATE_LITERAL_RE matches any backtick string and
+  // we rely on segment composition to decide if it's a path.
+  TEMPLATE_LITERAL_RE.lastIndex = 0
+  let tmpl: RegExpExecArray | null
+  while ((tmpl = TEMPLATE_LITERAL_RE.exec(content)) !== null) {
+    const body = tmpl[1] ?? ''
+    if (!body.includes('/')) {
+      continue
+    }
+    const segments = templateLiteralSegments(body)
+    const stages = segments.filter(s => STAGE_SEGMENTS.has(s))
+    const buildRoots = segments.filter(s => BUILD_ROOT_SEGMENTS.has(s))
+    const modes = segments.filter(s => MODE_SEGMENTS.has(s))
+    // Template literal trigger is tighter than path.join() because
+    // backtick strings often appear in patch fixtures, error messages,
+    // and other multi-line content that incidentally contains stage
+    // tokens like `wasm`. Require the canonical build-output shape:
+    //   - 'build' + 'out' + stage (canonical multi-stage layout), OR
+    //   - 2+ stage segments AND 'out' (e.g. `wasm/out/Final`), OR
+    //   - 'build' + stage + literal mode (back-compat with path.join).
+    const hasBuildAndOut =
+      buildRoots.includes('build') && buildRoots.includes('out')
+    const hasOut = buildRoots.includes('out')
+    const hasBuild = buildRoots.includes('build')
+    const triggersA =
+      (hasBuildAndOut && stages.length >= 1) ||
+      (stages.length >= 2 && hasOut) ||
+      (hasBuild && stages.length >= 1 && modes.length >= 1)
+    if (triggersA) {
+      const line = offsetToLine(tmpl.index)
+      const snippet = (lines[line - 1] ?? '').trim()
+      findings.push({
+        rule: 'A',
+        file: relPath,
+        line,
+        snippet,
+        message:
+          'Multi-stage path constructed inline via template literal (outside paths.mts).',
+        fix: 'Construct in the owning paths.mts (or use getFinalBinaryPath / getDownloadedDir from build-infra/lib/paths). Import the computed value here.',
+      })
+    }
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────
+// Rule C + D: workflow YAML scan
+// ──────────────────────────────────────────────────────────────────
+
+const WORKFLOW_PATH_RE =
+  /build\/\$\{[^}]+\}\/[^"'`\s]*\/out\/(?:Final|Release|Stripped|Compressed|Optimized|Synced)/g
+const WORKFLOW_GH_EXPR_PATH_RE =
+  /build\/\$\{\{\s*[^}]+\}\}\/[^"'`\s]*\/out\/(?:Final|Release|Stripped|Compressed|Optimized|Synced)/g
+
+const isInsideComputePathsBlock = (
+  lines: string[],
+  lineIdx: number,
+): boolean => {
+  // Walk backwards up to 60 lines looking for the start of the
+  // current step. If that step is a "Compute paths" step, the line
+  // is exempt.
+  for (let i = lineIdx; i >= Math.max(0, lineIdx - 60); i--) {
+    const l = lines[i] ?? ''
+    if (/^\s*-\s*name:/i.test(l)) {
+      // Step boundary — check if THIS step is a Compute paths step.
+      // The step body may include `id: paths` even if the name is
+      // something else (e.g. `id: stub-paths`), so look at the next
+      // ~20 lines for either marker.
+      for (let j = i; j < Math.min(lines.length, i + 20); j++) {
+        const m = lines[j] ?? ''
+        if (
+          /^\s*-\s*name:\s*Compute\s+[\w-]+\s+paths/i.test(m) ||
+          /^\s*id:\s*[\w-]*paths\s*$/i.test(m)
+        ) {
+          return true
+        }
+        if (j > i && /^\s*-\s*name:/i.test(m)) {
+          // Hit the next step — current step is NOT Compute paths.
+          return false
+        }
+      }
+      return false
+    }
+  }
+  return false
+}
+
+const scanWorkflowFile = (relPath: string): void => {
+  const full = path.join(REPO_ROOT, relPath)
+  let content: string
+  try {
+    content = readFileSync(full, 'utf8')
+  } catch {
+    return
+  }
+  const lines = content.split('\n')
+
+  // First pass: collect every hand-built path occurrence outside a
+  // "Compute paths" step. Per the mantra, a single reference is fine
+  // — what's banned is reconstructing the same path 2+ times.
+  type PathHit = {
+    line: number
+    snippet: string
+    pathStr: string
+  }
+  const occurrences = new Map<string, PathHit[]>()
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    if (/^\s*#/.test(line)) {
+      // Skip comment lines from C scan; they're under D below.
+      continue
+    }
+    if (isInsideComputePathsBlock(lines, i)) {
+      // Inside the canonical construction step — exempt.
+      continue
+    }
+    WORKFLOW_PATH_RE.lastIndex = 0
+    WORKFLOW_GH_EXPR_PATH_RE.lastIndex = 0
+    const matches: string[] = []
+    let m: RegExpExecArray | null
+    while ((m = WORKFLOW_PATH_RE.exec(line)) !== null) {
+      matches.push(m[0])
+    }
+    while ((m = WORKFLOW_GH_EXPR_PATH_RE.exec(line)) !== null) {
+      matches.push(m[0])
+    }
+    for (const pathStr of matches) {
+      const list = occurrences.get(pathStr) ?? []
+      list.push({ line: i + 1, snippet: line.trim(), pathStr })
+      occurrences.set(pathStr, list)
+    }
+  }
+
+  // Flag every occurrence of a shape that appears 2+ times.
+  for (const [pathStr, hits] of occurrences) {
+    if (hits.length < 2) {
+      continue
+    }
+    for (const hit of hits) {
+      findings.push({
+        rule: 'C',
+        file: relPath,
+        line: hit.line,
+        snippet: hit.snippet,
+        message: `Workflow constructs the same path ${hits.length} times: ${pathStr}`,
+        fix: 'Add a "Compute <pkg> paths" step (id: paths) early in the job that computes this path ONCE and exposes it via $GITHUB_OUTPUT. Reference as ${{ steps.paths.outputs.<name> }} in subsequent steps. References of the constructed value are unlimited; reconstructing is the violation.',
+      })
+    }
+  }
+
+  // Rule D: comments encoding a fully-qualified multi-stage path
+  // (separate scan since it has different semantics).
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    if (!/^\s*#/.test(line)) {
+      continue
+    }
+    const literalShape =
+      /build\/(?:dev|prod|shared)\/[a-z0-9-]+\/(?:wasm\/)?out\/(?:Final|Release|Stripped|Compressed|Optimized|Synced)/i
+    if (literalShape.test(line)) {
+      findings.push({
+        rule: 'D',
+        file: relPath,
+        line: i + 1,
+        snippet: line.trim(),
+        message: 'Comment encodes a fully-qualified path string.',
+        fix: 'Cite the canonical paths.mts (e.g. "see packages/<pkg>/scripts/paths.mts:getBuildPaths()") instead of duplicating the path string. Comments may describe structure with placeholders ("<mode>/<arch>") but should not be a parsable path.',
+      })
+    }
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────
+// Rule G: Makefile / Dockerfile / shell scan
+// ──────────────────────────────────────────────────────────────────
+
+const SCRIPT_HAND_BUILT_RE =
+  /build\/\$?\{?(?:BUILD_MODE|MODE|prod|dev)\}?\/[\w${}.-]*\/out\/(?:Final|Release|Stripped|Compressed|Optimized|Synced)/g
+
+const scanScriptFile = (relPath: string): void => {
+  const full = path.join(REPO_ROOT, relPath)
+  let content: string
+  try {
+    content = readFileSync(full, 'utf8')
+  } catch {
+    return
+  }
+  const lines = content.split('\n')
+  const isDockerfile =
+    /Dockerfile/i.test(relPath) || /\.glibc$|\.musl$/.test(relPath)
+
+  // First pass: collect every multi-stage path occurrence in this file,
+  // scoped per Dockerfile stage (each `FROM ... AS ...` starts a new
+  // scope where ENV/ARG don't propagate).
+  type Hit = { line: number; text: string; pathStr: string; stage: number }
+  const hits: Hit[] = []
+  let stage = 0
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    if (/^\s*#/.test(line)) {
+      // Skip comments — documentation, not construction.
+      continue
+    }
+    if (isDockerfile && /^FROM\s+/i.test(line)) {
+      stage += 1
+      continue
+    }
+    SCRIPT_HAND_BUILT_RE.lastIndex = 0
+    let m: RegExpExecArray | null
+    while ((m = SCRIPT_HAND_BUILT_RE.exec(line)) !== null) {
+      hits.push({
+        line: i + 1,
+        text: line.trim(),
+        pathStr: m[0],
+        stage,
+      })
+    }
+  }
+
+  // Group by (stage, pathStr) — only flag when a path is built 2+
+  // times within the SAME Dockerfile stage (or anywhere in non-
+  // Dockerfile scripts, where stages don't apply).
+  const grouped = new Map<string, Hit[]>()
+  for (const h of hits) {
+    const key = `${h.stage}::${h.pathStr}`
+    const list = grouped.get(key) ?? []
+    list.push(h)
+    grouped.set(key, list)
+  }
+  for (const [, list] of grouped) {
+    if (list.length < 2) {
+      continue
+    }
+    for (const hit of list) {
+      findings.push({
+        rule: 'G',
+        file: relPath,
+        line: hit.line,
+        snippet: hit.text,
+        message: `Hand-built multi-stage path constructed ${list.length} times in this file: ${hit.pathStr}`,
+        fix: 'Assign to a variable / ENV once near the top of the script / Dockerfile stage, with a comment naming the canonical paths.mts. Reference the variable everywhere downstream. References of a single construction are unlimited; reconstructing the same path is the violation.',
+      })
+    }
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────
+// Rule F: cross-file path repetition
+// ──────────────────────────────────────────────────────────────────
+
+const checkRuleF = (): void => {
+  // A path is "constructed" each time we see a new path.join with a
+  // matching shape. Group findings of Rule A by their snippet shape;
+  // when the same shape appears in 2+ files, demote them to Rule F so
+  // the message is more accurate.
+  const byShape = new Map<string, Finding[]>()
+  for (const f of findings) {
+    if (f.rule !== 'A') {
+      continue
+    }
+    // Normalize: strip whitespace, identifiers, surrounding context;
+    // keep just the literal path-segment shape.
+    const literalsRe = /'[^']*'|"[^"]*"/g
+    const literals = (f.snippet.match(literalsRe) ?? []).join(',')
+    if (!literals) {
+      continue
+    }
+    const list = byShape.get(literals) ?? []
+    list.push(f)
+    byShape.set(literals, list)
+  }
+  for (const [shape, list] of byShape) {
+    if (list.length < 2) {
+      continue
+    }
+    // Rule F is "same path shape appears in two or more *files*" — two
+    // hand-builds in a single file are still a Rule-A pattern, not a
+    // cross-file duplication. Promote only when at least two distinct
+    // files share the shape.
+    const distinctFiles = new Set(list.map(f => f.file))
+    if (distinctFiles.size < 2) {
+      continue
+    }
+    for (const f of list) {
+      f.rule = 'F'
+      f.message = `Same path shape constructed in ${distinctFiles.size} files (${list.length} places): ${shape.slice(0, 100)}`
+      f.fix =
+        'Construct this path ONCE in a paths.mts (or build-infra helper) and import the computed value. References of the computed variable are unlimited; re-constructing the same shape twice is the violation.'
+    }
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────
+// Main
+// ──────────────────────────────────────────────────────────────────
+
+const main = (): number => {
+  // Scan code files (Rule A + B).
+  for (const rel of walk(
+    REPO_ROOT,
+    p => p.endsWith('.mts') || p.endsWith('.cts'),
+  )) {
+    if (isExempt(rel)) {
+      continue
+    }
+    scanCodeFile(rel)
+  }
+  // Scan workflows (Rule C + D).
+  const workflowDir = path.join(REPO_ROOT, '.github', 'workflows')
+  if (existsSync(workflowDir)) {
+    for (const rel of walk(workflowDir, p => p.endsWith('.yml'))) {
+      if (isExempt(rel)) {
+        continue
+      }
+      scanWorkflowFile(rel)
+    }
+  }
+  // Scan scripts/Makefiles/Dockerfiles (Rule G).
+  for (const rel of walk(REPO_ROOT, p => {
+    const base = path.basename(p)
+    return (
+      base === 'Makefile' ||
+      base.endsWith('.mk') ||
+      base.endsWith('.Dockerfile') ||
+      base === 'Dockerfile' ||
+      base.endsWith('.glibc') ||
+      base.endsWith('.musl') ||
+      (base.endsWith('.sh') && !p.includes('test/'))
+    )
+  })) {
+    if (isExempt(rel)) {
+      continue
+    }
+    scanScriptFile(rel)
+  }
+  // Promote cross-file Rule-A repeats to Rule F.
+  checkRuleF()
+
+  // Filter against allowlist.
+  const blocking = findings.filter(f => !isAllowlisted(f))
+
+  if (args.values.json) {
+    process.stdout.write(
+      JSON.stringify(
+        { findings: blocking, allowlisted: findings.length - blocking.length },
+        null,
+        2,
+      ) + '\n',
+    )
+    return blocking.length === 0 ? 0 : 1
+  }
+
+  if (blocking.length === 0) {
+    if (!args.values.quiet) {
+      logger.success('Path-hygiene check passed (1 path, 1 reference)')
+      if (findings.length > 0) {
+        logger.substep(`${findings.length} finding(s) allowlisted`)
+      }
+    }
+    return 0
+  }
+
+  logger.error(`Path-hygiene check FAILED — ${blocking.length} finding(s)`)
+  logger.log('')
+  logger.log('Mantra: 1 path, 1 reference')
+  logger.log('')
+  for (const f of blocking) {
+    logger.log(`  [${f.rule}] ${f.file}:${f.line}`)
+    logger.log(`      ${f.snippet}`)
+    logger.log(`      → ${f.message}`)
+    if (args.values['show-hashes']) {
+      logger.log(`      snippet_hash: ${snippetHash(f.snippet)}`)
+    }
+    if (args.values.explain) {
+      logger.log(`      Fix: ${f.fix}`)
+    }
+    logger.log('')
+  }
+  if (!args.values.explain) {
+    logger.log('Run with --explain to see fix suggestions per finding.')
+    logger.log(
+      'Add intentional exceptions to .github/paths-allowlist.yml with a `reason` field.',
+    )
+    logger.log(
+      'Run with --show-hashes to print the snippet_hash for each finding (drift-resistant allowlisting).',
+    )
+  }
+  return 1
+}
+
+try {
+  process.exitCode = main()
+} catch (e) {
+  logger.error(`Path-hygiene gate crashed: ${e}`)
+  process.exitCode = 2
+}
diff --git a/scripts/fix.mts b/scripts/fix.mts
new file mode 100644
index 0000000..fd05946
--- /dev/null
+++ b/scripts/fix.mts
@@ -0,0 +1,112 @@
+/**
+ * @fileoverview Auto-fix script — runs linters with --fix, then security
+ * tools (zizmor, agentshield) if available, then an AI-assisted pass
+ * for the lint findings the deterministic fixer can't safely handle.
+ *
+ * Steps:
+ *   1. pnpm run lint --fix — oxlint + oxfmt (forwards extra argv like --all)
+ *   2. zizmor --fix .github/ — GitHub Actions workflow fixes
+ *      (skipped if .github/ doesn't exist)
+ *   3. agentshield scan --fix — Claude config fixes
+ *      (skipped if .claude/ or agentshield isn't installed)
+ *   4. AI-assisted lint fix — headless claude (Sonnet) with a
+ *      restricted toolset for judgment-call rules. Skipped silently
+ *      when the claude CLI isn't installed, when SKIP_AI_FIX=1, or
+ *      when --no-ai is passed. See scripts/ai-lint-fix.mts.
+ *
+ * Forwards `process.argv.slice(2)` to the lint step, so
+ * `pnpm run fix --all` runs `pnpm run lint --fix --all` (full-tree
+ * fix), and `pnpm run fix --staged` does the staged-only flow.
+ */
+
+import { existsSync } from 'node:fs'
+import process from 'node:process'
+
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+import { spawn } from '@socketsecurity/lib/spawn'
+
+const WIN32 = process.platform === 'win32'
+const logger = getDefaultLogger()
+
+async function run(
+  cmd: string,
+  args: string[],
+  { label, required = true }: { label?: string; required?: boolean } = {},
+): Promise<number> {
+  try {
+    const result = await spawn(cmd, args, {
+      shell: WIN32,
+      stdio: 'inherit',
+    })
+    if (result.code !== 0 && required) {
+      logger.error(`${label || cmd} failed (exit ${result.code})`)
+      return result.code
+    }
+    if (result.code !== 0) {
+      // Non-blocking: log warning and continue.
+      logger.warn(`${label || cmd}: exited ${result.code} (non-blocking)`)
+    }
+    return 0
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e)
+    if (!required) {
+      logger.warn(`${label || cmd}: ${msg} (non-blocking)`)
+      return 0
+    }
+    throw e
+  }
+}
+
+async function main(): Promise<void> {
+  // Step 1: Lint fix — delegates to scripts/lint.mts which runs both
+  // oxfmt and oxlint. Forward extra argv so `--all` / `--staged` /
+  // explicit file paths reach the lint runner unchanged.
+  const lintExit = await run(
+    'pnpm',
+    ['run', 'lint', '--fix', ...process.argv.slice(2)],
+    { label: 'lint --fix' },
+  )
+  if (lintExit) {
+    process.exitCode = lintExit
+  }
+
+  // Step 2: zizmor — fixes GitHub Actions workflow security issues.
+  // Only runs if .github/ directory exists (some repos don't have workflows).
+  if (existsSync('.github')) {
+    await run('zizmor', ['--fix', '.github/'], {
+      label: 'zizmor --fix',
+      required: false,
+    })
+  }
+
+  // Step 3: AgentShield — fixes Claude config security findings.
+  // Only runs if .claude/ exists and agentshield binary is installed.
+  if (existsSync('.claude') && existsSync('node_modules/.bin/agentshield')) {
+    await run('pnpm', ['exec', 'agentshield', 'scan', '--fix'], {
+      label: 'agentshield --fix',
+      required: false,
+    })
+  }
+
+  // Step 4: AI-assisted lint fix. Most lint rules ship a
+  // deterministic autofix and Step 1 handled them. What remains is
+  // the judgment-call set — rule violations whose right rewrite
+  // depends on surrounding context that a regex / AST rewrite can't
+  // safely infer. This step shells out to a headless Claude (Sonnet,
+  // four-flag lockdown per CLAUDE.md "Programmatic Claude calls",
+  // restricted toolset) to handle just those rules.
+  //
+  // Skipped silently when the claude CLI isn't on PATH, when
+  // SKIP_AI_FIX=1, or when --no-ai is passed. CI sets SKIP_AI_FIX=1
+  // because the fleet rule is "no AI in CI for code changes."
+  await run('node', ['scripts/ai-lint-fix.mts', ...process.argv.slice(2)], {
+    label: 'ai-lint-fix',
+    required: false,
+  })
+}
+
+main().catch((e: unknown) => {
+  const msg = e instanceof Error ? e.message : String(e)
+  logger.error(msg)
+  process.exitCode = 1
+})
diff --git a/scripts/install-sfw.mts b/scripts/install-sfw.mts
new file mode 100644
index 0000000..2e0161d
--- /dev/null
+++ b/scripts/install-sfw.mts
@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Install Socket Firewall (sfw) into the Socket _dlx cache
+ * via @socketsecurity/lib's downloadBinary helper.
+ *
+ * Matches the CI install path: same version source, same binary
+ * integrity check (SHA-256 inline), same on-disk layout
+ * (~/.socket/_dlx/<hash>/sfw). The dev-only piece is a stable shim
+ * symlink at ~/.socket/sfw/bin/sfw → _dlx-hashed path so existing
+ * shims in ~/.socket/sfw/shims/ continue to resolve.
+ *
+ * Reads version + per-platform sha256 from the repo's root
+ * `external-tools.json` under `tools.sfw-free` / `tools.sfw-enterprise`.
+ * That file is the single fleet source of truth — every consumer of
+ * external tooling reads the same entries.
+ *
+ * Usage:
+ *   pnpm run install:sfw                  # free flavor
+ *   pnpm run install:sfw -- --enterprise  # requires SOCKET_API_TOKEN
+ *   pnpm run install:sfw -- --force       # ignore cache, redownload
+ *   pnpm run install:sfw -- --quiet
+ */
+
+import { existsSync, promises as fsPromises, readFileSync } from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+
+import { WIN32, getArch } from '@socketsecurity/lib/constants/platform'
+import { downloadBinary } from '@socketsecurity/lib/dlx/binary'
+import { errorMessage } from '@socketsecurity/lib/errors'
+import { safeDelete } from '@socketsecurity/lib/fs'
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+
+const logger = getDefaultLogger()
+
+// Resolve the repo-root external-tools.json. Scripts live at
+// <repo-root>/scripts/install-sfw.mts, so go one dir up.
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const REPO_ROOT = path.join(__dirname, '..')
+const EXTERNAL_TOOLS_PATH = path.join(REPO_ROOT, 'external-tools.json')
+
+// HOME on POSIX, USERPROFILE on Windows. Both can be set to an empty
+// string in degenerate shells (`HOME= some-cmd`) or to a non-absolute
+// stub like `~`, which would resolve `path.join(HOME, ...)` to a path
+// rooted at the current working directory — silently installing sfw
+// somewhere unexpected. Insist on an absolute path before accepting
+// either value.
+const resolveHome = (): string | undefined => {
+  for (const candidate of [process.env['HOME'], process.env['USERPROFILE']]) {
+    if (candidate && path.isAbsolute(candidate)) {
+      return candidate
+    }
+  }
+  return undefined
+}
+const HOME = resolveHome()
+if (!HOME) {
+  logger.fail(
+    'HOME / USERPROFILE not set to an absolute path — cannot resolve install dir',
+  )
+  process.exit(1)
+}
+const SFW_BIN_DIR = path.join(HOME, '.socket', 'sfw', 'bin')
+
+interface ToolEntry {
+  version: string
+  repository?: string
+  release?: string
+  checksums?: Record<string, { asset: string; sha256: string }>
+}
+
+interface ExternalToolsFile {
+  tools: Record<string, ToolEntry>
+}
+
+export function detectPlatform(): string {
+  const arch = getArch()
+  if (process.platform === 'darwin') {
+    return `darwin-${arch}`
+  }
+  if (process.platform === 'win32') {
+    return `win-${arch}`
+  }
+  if (process.platform === 'linux') {
+    // Detect musl vs glibc via the loader presence — same heuristic
+    // the CI install-tool.mjs uses.
+    const isMusl =
+      existsSync('/lib/ld-musl-x86_64.so.1') ||
+      existsSync('/lib/ld-musl-aarch64.so.1')
+    return `linux-${arch}${isMusl ? '-musl' : ''}`
+  }
+  throw new Error(`Unsupported platform: ${process.platform}`)
+}
+
+async function main(): Promise<void> {
+  const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      enterprise: { type: 'boolean', default: false },
+      force: { type: 'boolean', default: false },
+      quiet: { type: 'boolean', default: false },
+    },
+    strict: false,
+  })
+
+  if (values['enterprise'] && !process.env['SOCKET_API_TOKEN']) {
+    logger.fail('--enterprise requires SOCKET_API_TOKEN in env')
+    process.exit(1)
+    return
+  }
+
+  if (!values['quiet']) {
+    logger.info(`Reading version table from ${EXTERNAL_TOOLS_PATH}`)
+  }
+
+  if (!existsSync(EXTERNAL_TOOLS_PATH)) {
+    logger.fail(
+      `external-tools.json not found at ${EXTERNAL_TOOLS_PATH}\n` +
+        '  Every fleet repo ships this file at its root via the wheelhouse cascade.',
+    )
+    process.exit(1)
+    return
+  }
+  const tools = JSON.parse(
+    readFileSync(EXTERNAL_TOOLS_PATH, 'utf8'),
+  ) as ExternalToolsFile
+  const toolKey = values['enterprise'] ? 'sfw-enterprise' : 'sfw-free'
+  const entry = tools.tools?.[toolKey]
+  if (!entry) {
+    logger.fail(
+      `external-tools.json has no \`tools.${toolKey}\` entry at ${EXTERNAL_TOOLS_PATH}`,
+    )
+    process.exit(1)
+    return
+  }
+  if (!entry.repository) {
+    logger.fail(`tools.${toolKey} is missing the required \`repository\` field`)
+    process.exit(1)
+    return
+  }
+
+  const platform = detectPlatform()
+  const platformMeta = entry.checksums?.[platform]
+  if (!platformMeta) {
+    const supported = Object.keys(entry.checksums ?? {}).join(', ')
+    logger.fail(
+      `${toolKey} v${entry.version} is not published for ${platform}.\n` +
+        `  Supported: ${supported || '(none)'}`,
+    )
+    process.exit(1)
+    return
+  }
+
+  const repoSlug = entry.repository.replace(/^github:/, '')
+  const url = `https://github.com/${repoSlug}/releases/download/v${entry.version}/${platformMeta.asset}`
+  const binaryName = WIN32 ? 'sfw.exe' : 'sfw'
+  const sha256 = platformMeta.sha256
+
+  if (!values['quiet']) {
+    logger.info(`Installing ${toolKey} v${entry.version} (${platform})`)
+    logger.log(`  from: ${url}`)
+  }
+
+  const { binaryPath, downloaded } = await downloadBinary({
+    force: Boolean(values['force']),
+    name: binaryName,
+    sha256,
+    url,
+  })
+
+  if (!values['quiet']) {
+    logger.log(`  ${downloaded ? 'downloaded' : 'cached'}: ${binaryPath}`)
+  }
+
+  // Stable shim entry point: ~/.socket/sfw/bin/sfw → _dlx-hashed path.
+  // The shims in ~/.socket/sfw/shims/ exec this symlink so the _dlx
+  // hash is invisible to PATH-prepending consumers. Refresh on every
+  // install so a version bump updates the link target.
+  await fsPromises.mkdir(SFW_BIN_DIR, { recursive: true })
+  const linkPath = path.join(SFW_BIN_DIR, binaryName)
+  // oxlint-disable-next-line socket/prefer-exists-sync -- need lstat (not existsSync) to detect broken symlinks; existsSync follows the link and returns false if the target is gone, leaving the stale link in place.
+  const linkExists = await fsPromises
+    .lstat(linkPath)
+    .then(() => true)
+    .catch(() => false)
+  if (linkExists) {
+    await safeDelete(linkPath)
+  }
+  await fsPromises.symlink(binaryPath, linkPath)
+
+  if (!values['quiet']) {
+    logger.success(`sfw v${entry.version} ready at ${linkPath}`)
+    logger.log(`  → ${binaryPath}`)
+  }
+}
+
+main().catch((e: unknown) => {
+  logger.fail(errorMessage(e))
+  process.exitCode = 1
+})
diff --git a/scripts/lockstep-emit-schema.mts b/scripts/lockstep-emit-schema.mts
new file mode 100644
index 0000000..6087382
--- /dev/null
+++ b/scripts/lockstep-emit-schema.mts
@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Emit `lockstep.schema.json` from the TypeBox schema.
+ *
+ * The TypeBox schema in `scripts/lockstep-schema.mts` is the source of truth.
+ * TypeBox schemas are JSON Schema natively — no conversion library needed,
+ * just serialize the schema object and add the draft-2020-12 meta headers.
+ *
+ * Run via `pnpm run lockstep:emit-schema` when the schema changes.
+ */
+
+import { writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { spawn } from '@socketsecurity/lib/spawn'
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+
+import { LockstepManifestSchema } from './lockstep-schema.mts'
+
+const logger = getDefaultLogger()
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const rootDir = path.resolve(__dirname, '..')
+const outPath = path.join(rootDir, 'lockstep.schema.json')
+
+// TypeBox schemas carry JSON Schema shape directly, plus a Symbol-keyed
+// [Kind] marker that JSON.stringify drops. Spreading the schema first
+// then layering the canonical $schema / $id / title on top gives a clean
+// draft-2020-12 document with the Socket-specific headers.
+const enriched = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'https://github.com/SocketDev/lockstep.schema.json',
+  title: 'lockstep manifest',
+  ...LockstepManifestSchema,
+}
+
+writeFileSync(outPath, JSON.stringify(enriched, null, 2) + '\n', 'utf8')
+
+// Run oxfmt on the output so the file matches what oxfmt would
+// produce. Without this, `pnpm run check --all` (which runs oxfmt
+// over the tree) would flag the emitted schema as drifted on every
+// repo that re-emits it. The schema is in IDENTICAL_FILES, so the
+// formatted form is the byte-canonical form fleet-wide.
+await spawn(
+  'pnpm',
+  ['exec', 'oxfmt', '-c', '.config/oxfmtrc.json', outPath],
+  {
+    cwd: rootDir,
+    stdio: 'inherit',
+  },
+)
+
+logger.success(`wrote ${path.relative(rootDir, outPath)}`)
diff --git a/scripts/lockstep-schema.mts b/scripts/lockstep-schema.mts
new file mode 100644
index 0000000..3965d09
--- /dev/null
+++ b/scripts/lockstep-schema.mts
@@ -0,0 +1,459 @@
+/**
+ * @fileoverview TypeBox schema for lockstep.json — single source of truth.
+ *
+ * Everything else is derived:
+ *   - TypeScript types in scripts/lockstep.mts via `Static<typeof ...>`
+ *   - lockstep.schema.json (draft 2020-12) via direct JSON.stringify of the
+ *     TypeBox schema, emitted by scripts/lockstep-emit-schema.mts
+ *   - Runtime validation at harness startup via
+ *     `validateSchema(LockstepManifestSchema, ...)` from
+ *     `@socketsecurity/lib/validation/validate-schema`
+ *
+ * Byte-identical across sdxgen / socket-btm / socket-registry /
+ * socket-wheelhouse / stuie / ultrathink via sync-scaffolding.mts.
+ */
+
+import { Type, type Static } from '@sinclair/typebox'
+
+// ---------------------------------------------------------------------------
+// Shared primitives.
+// ---------------------------------------------------------------------------
+
+// Full git commit SHA. Used by file-fork.forked_at_sha and
+// version-pin.pinned_sha. Centralized so adding a new SHA-bearing
+// field can't accidentally accept short SHAs.
+const FULL_SHA_PATTERN = '^[0-9a-f]{40}$'
+
+const IdSchema = Type.String({
+  // Kebab-case enforced. The earlier "camelCase segments allowed for
+  // API-mirror ids" relaxation produced inconsistent ids across
+  // manifests. When an id needs to mirror an API name, namespace it:
+  // `api/findNodeAt` instead of `export-findNodeAt`. The slash carves
+  // out the camelCase segment without polluting top-level ids.
+  pattern: '^[a-z0-9][a-z0-9-]*(/[A-Za-z0-9_-]+)?$',
+  description:
+    'Stable identifier, unique within the manifest. Kebab-case (lowercase letters / digits / hyphens). For ids that mirror an external API name, use a namespace prefix: `api/findNodeAt`, `node/parseURL`. The slash separates the kebab namespace from the free-form leaf.',
+})
+
+const CriticalitySchema = Type.Integer({
+  minimum: 1,
+  maximum: 10,
+  description:
+    'Stay-in-step importance. Anchors: 1 = cosmetic / nice-to-have; 5 = behavioral parity expected; 10 = security-sensitive. The harness surfaces high-criticality drift louder and gates feature-parity rows on the criticality/10 floor.',
+})
+
+const UpstreamRefSchema = Type.String({
+  description:
+    'Key into the top-level `upstreams` map. The harness errors if no matching upstream entry exists.',
+})
+
+const ConformanceTestSchema = Type.String({
+  description:
+    'Path (relative to repo root) of a test that enforces behavior parity (modulo documented deviations). Strongly recommended — static checks catch syntactic drift, not behavioral. A row without a conformance test relies entirely on code-pattern / fixture-snapshot checks.',
+})
+
+const NotesSchema = Type.String({
+  description:
+    'Free-form context: why this row exists, gotchas, links to related issues / PRs / upstream discussions. Read by humans, not by the harness.',
+})
+
+const PortStatusSchema = Type.Object(
+  {
+    status: Type.Union([Type.Literal('implemented'), Type.Literal('opt-out')], {
+      description:
+        "`implemented` = port meets the row's assertions; `opt-out` = port consciously skips this row (requires `reason`).",
+    }),
+    reason: Type.Optional(
+      Type.String({
+        description:
+          'Why this port opts out. SCHEMA-CONDITIONAL: required when status is `opt-out`. The TypeBox type cannot express the conditional, but the harness rejects opt-out rows with empty / missing reason.',
+      }),
+    ),
+    path: Type.Optional(
+      Type.String({
+        description:
+          "Optional path to this port's implementation of the row. Useful for module-inventory rows where each language points at a different directory; redundant when the port's overall layout already encodes the path.",
+      }),
+    ),
+    note: Type.Optional(
+      Type.String({
+        description:
+          "Optional free-form note attached to this specific port's status. For multi-port context, prefer the row-level `notes` field.",
+      }),
+    ),
+  },
+  {
+    additionalProperties: false,
+    description:
+      'Per-port status for a lang-parity row. The `ports` map on a row pairs each top-level `sites` key with one of these.',
+  },
+)
+
+const UpstreamSchema = Type.Object(
+  {
+    submodule: Type.String({
+      description:
+        'Submodule path, relative to repo root. Must match an entry in `.gitmodules`.',
+    }),
+    repo: Type.String({
+      // Tightened from `^https?://` to require a host. Empty hosts
+      // (`http://`) silently match the loose pattern but break every
+      // git operation downstream.
+      pattern: '^https?://[^/\\s]+',
+      description:
+        'Upstream repository URL (http:// or https:// + host). Anchored at the host so empty URLs fail validation rather than failing at git-fetch time.',
+    }),
+  },
+  {
+    additionalProperties: false,
+    description:
+      'A submodule + its upstream repo URL. Referenced by file-fork / version-pin / feature-parity / spec-conformance rows via `upstream`.',
+  },
+)
+
+const SiteSchema = Type.Object(
+  {
+    path: Type.String({
+      description:
+        "Path to the port's root directory, relative to repo root. The harness reads files under this path when checking the port's assertions.",
+    }),
+    language: Type.Optional(
+      Type.String({
+        description:
+          "Language label for human reports (e.g. `cpp`, `go`, `rust`, `typescript`). The harness does no language-specific processing — it's purely informational.",
+      }),
+    ),
+  },
+  {
+    additionalProperties: false,
+    description:
+      'A sibling port (typically per-language). Referenced by lang-parity rows via `ports.<site-key>`.',
+  },
+)
+
+const FixtureCheckSchema = Type.Object(
+  {
+    fixture_path: Type.String({
+      description:
+        'Path (relative to repo root) of the input fixture the local implementation runs against.',
+    }),
+    snapshot_path: Type.Optional(
+      Type.String({
+        description:
+          "Path (relative to repo root) of the snapshot file the implementation's output is diffed against. When absent, the harness only checks that the fixture is processed without error — no output comparison.",
+      }),
+    ),
+    diff_tolerance: Type.Optional(
+      Type.Union(
+        [
+          Type.Literal('exact'),
+          Type.Literal('line-by-line'),
+          Type.Literal('semantic'),
+        ],
+        {
+          description:
+            'How the snapshot diff is computed. `exact` = byte-identical; the strictest check. `line-by-line` = per-line diff after normalizing line endings (CRLF / LF); tolerates trailing-newline drift. `semantic` = harness-defined deeper comparison (typically AST or normalized JSON for output that has equivalent representations); each row kind documents what `semantic` means in its context.',
+        },
+      ),
+    ),
+  },
+  {
+    additionalProperties: false,
+    description:
+      "Golden-input verification. Snapshot-based diffs replace the brittle hardcoded-count checks the harness used historically (sdxgen's lock-step-features lesson).",
+  },
+)
+
+// ---------------------------------------------------------------------------
+// Row kinds.
+//
+// Five kinds, each tracking a different "stay in sync with X" relation:
+//
+//   file-fork         — vendored file derived from upstream
+//   version-pin       — submodule pinned to upstream release
+//   feature-parity    — local impl mirrors upstream behavior
+//   spec-conformance  — local impl of an external spec
+//   lang-parity       — N sibling language ports of one spec
+//
+// The `kind` literal on each row is the harness's dispatch key. Adding
+// a new kind = (1) new row schema here, (2) new case in lockstep.mts'
+// dispatcher, (3) new report-row type. The schema keeps row kinds
+// closed (no Type.Union with `any`); harness errors on unknown kinds
+// rather than silently skipping.
+// ---------------------------------------------------------------------------
+
+const FileForkRowSchema = Type.Object(
+  {
+    kind: Type.Literal('file-fork'),
+    id: IdSchema,
+    upstream: UpstreamRefSchema,
+    criticality: Type.Optional(CriticalitySchema),
+    conformance_test: Type.Optional(ConformanceTestSchema),
+    notes: Type.Optional(NotesSchema),
+    local: Type.String({
+      description:
+        'Path (relative to repo root) of our ported copy of the upstream file.',
+    }),
+    upstream_path: Type.String({
+      description:
+        'Path within the upstream submodule (relative to the submodule root) of the source file we forked from.',
+    }),
+    forked_at_sha: Type.String({
+      pattern: FULL_SHA_PATTERN,
+      description:
+        'Full 40-char SHA of the upstream commit we forked from. The harness runs `git log <sha>..HEAD -- <upstream_path>` inside the submodule to surface drift.',
+    }),
+    deviations: Type.Array(Type.String(), {
+      minItems: 1,
+      description:
+        'Human-readable list of intentional differences from upstream. Zero deviations = the file should not be forked; consume upstream directly. Each entry is one short sentence (e.g. `swap require() for import` or `remove Node 14 fallback`).',
+    }),
+  },
+  {
+    additionalProperties: false,
+    description:
+      'A local file derived from an upstream file with intentional modifications. Drift = upstream moved forward on this path; we may need to cherry-pick or update our deviations.',
+  },
+)
+
+const VersionPinRowSchema = Type.Object(
+  {
+    kind: Type.Literal('version-pin'),
+    id: IdSchema,
+    upstream: UpstreamRefSchema,
+    criticality: Type.Optional(CriticalitySchema),
+    conformance_test: Type.Optional(ConformanceTestSchema),
+    notes: Type.Optional(NotesSchema),
+    pinned_sha: Type.String({
+      pattern: FULL_SHA_PATTERN,
+      description:
+        'Full 40-char SHA the submodule is pinned to. Authoritative — the harness compares this against the submodule HEAD, not against `pinned_tag`.',
+    }),
+    pinned_tag: Type.Optional(
+      Type.String({
+        description:
+          'Human-readable release tag for reports / PR titles (e.g. `v3.2.1`). Informational only — `pinned_sha` is the source of truth. Useful when an upstream cuts a release without changing semver but moves the SHA.',
+      }),
+    ),
+    upgrade_policy: Type.Union(
+      [
+        Type.Literal('track-latest'),
+        Type.Literal('major-gate'),
+        Type.Literal('locked'),
+      ],
+      {
+        description:
+          '`track-latest` = any new release is actionable; updating-lockstep auto-bumps. `major-gate` = patch / minor auto-bump; major bumps surfaced as advisory. `locked` = explicit decision per upgrade; the harness reports drift but never auto-bumps. Pick `locked` when bumping is gated on a coordinated change in another repo (e.g. Node vendoring temporal-rs).',
+      },
+    ),
+  },
+  {
+    additionalProperties: false,
+    description:
+      "A submodule pinned to an upstream release. Drift = upstream cut a new release we haven't adopted.",
+  },
+)
+
+const FeatureParityRowSchema = Type.Object(
+  {
+    kind: Type.Literal('feature-parity'),
+    id: IdSchema,
+    upstream: UpstreamRefSchema,
+    criticality: CriticalitySchema,
+    conformance_test: Type.Optional(ConformanceTestSchema),
+    notes: Type.Optional(NotesSchema),
+    local_area: Type.String({
+      description:
+        'Path (relative to repo root) of the local module / directory implementing the feature. The code-pattern scan targets this directory recursively, excluding test files (matched by `*.test.{ts,mts,js,mjs}` and `*.spec.*`).',
+    }),
+    test_area: Type.Optional(
+      Type.String({
+        description:
+          'Path (relative to repo root) of the directory where tests for this feature live. When absent, the harness searches for tests inside `local_area`. Useful when tests live in a sibling directory (e.g. `local_area=src/auth`, `test_area=test/auth`).',
+      }),
+    ),
+    code_patterns: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          'Regex patterns the local implementation must contain. Prefer anchored patterns (function signatures, exported symbols) over loose keywords to avoid matching comments. Each pattern is searched independently across `local_area`; missing patterns lower the code score.',
+      }),
+    ),
+    test_patterns: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          'Regex patterns the test suite must contain. Same scoring as `code_patterns` but searched across `test_area` (or `local_area` when `test_area` is absent).',
+      }),
+    ),
+    fixture_check: Type.Optional(FixtureCheckSchema),
+  },
+  {
+    additionalProperties: false,
+    description:
+      'A behavioral feature reimplemented locally to match upstream behavior. Three-pillar validation: code patterns + test patterns + fixture snapshot. The total score is averaged across present pillars; rows below the criticality / 10 floor surface as drift.',
+  },
+)
+
+const SpecConformanceRowSchema = Type.Object(
+  {
+    kind: Type.Literal('spec-conformance'),
+    id: IdSchema,
+    upstream: UpstreamRefSchema,
+    criticality: Type.Optional(CriticalitySchema),
+    conformance_test: Type.Optional(ConformanceTestSchema),
+    notes: Type.Optional(NotesSchema),
+    local_impl: Type.String({
+      description:
+        'Path (relative to repo root) of our reimplementation of the spec. Either a file or a directory.',
+    }),
+    spec_version: Type.String({
+      description:
+        'Version label of the spec we conform to (e.g. `ECMAScript-2024`, `RFC-9110`, commit SHA, or upstream tag). Free-form — the harness only checks for drift via the upstream submodule, not the version string itself.',
+    }),
+    spec_path: Type.Optional(
+      Type.String({
+        description:
+          'Path within the upstream submodule to the spec document. Used to scope drift detection to the spec file (rather than every change in the upstream repo).',
+      }),
+    ),
+  },
+  {
+    additionalProperties: false,
+    description:
+      'A local reimplementation of an external specification. Drift = the spec was revised; we may need to update our impl, the spec_version, or both.',
+  },
+)
+
+// Open-ended assertion shape — each lang-parity row attaches whatever
+// shape its harness needs.
+//
+// Each assertion is a `{ kind: string, ... }` object: the harness reads
+// `kind` and dispatches to a per-kind checker. Known kinds (subject to
+// per-repo extension):
+//
+//   `presence`     — `{kind: 'presence', symbol: string}`
+//   `signature`    — `{kind: 'signature', signature: string, where?: string}`
+//   `not-present`  — `{kind: 'not-present', anti_pattern: string, where?: string}`
+//
+// Repos add new kinds in their own harness extensions. Unknown kinds
+// are skipped with a log line — schema-level enumeration would couple
+// the manifest to one harness's dispatch table. Historical precedent:
+// ultrathink/acorn/scripts/xlang-harness.mts.
+const AssertionSchema = Type.Record(Type.String(), Type.Unknown(), {
+  description:
+    'A typed assertion the lang-parity row asserts on each port. Shape: `{kind: string, ...kind-specific fields}`. The lockstep harness dispatches on `kind`; per-kind contracts are documented in the harness, not here.',
+})
+
+const LangParityRowSchema = Type.Object(
+  {
+    kind: Type.Literal('lang-parity'),
+    id: IdSchema,
+    name: Type.String({
+      description:
+        'Short human-readable label for this row (e.g. `Range parsing`, `Async iterators`). Used in report headers; not parsed.',
+    }),
+    description: Type.String({
+      description:
+        'One-paragraph description of what behavior this row asserts on each port. Read by humans; not parsed.',
+    }),
+    category: Type.String({
+      description:
+        "Grouping tag for report aggregation (e.g. `parser`, `runtime`, `api`). The single magic value is `rejected` — RESERVED for anti-patterns: every port MUST be `opt-out`, and any port flipping to `implemented` exits 2 ('rejected anti-pattern reintroduced'). Use freely otherwise.",
+    }),
+    criticality: Type.Optional(CriticalitySchema),
+    conformance_test: Type.Optional(ConformanceTestSchema),
+    notes: Type.Optional(NotesSchema),
+    assertions: Type.Optional(
+      Type.Array(AssertionSchema, {
+        description:
+          'Assertions checked against each port. Each entry is `{kind: string, ...}`; the harness dispatches on `kind`. See AssertionSchema description for known kinds; unknown kinds skip with a log line. Mutually compatible with `matrix_files` (a row can have both, neither, or one).',
+      }),
+    ),
+    matrix_files: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          'Paths (relative to this manifest) of `lockstep-lang-*.json` sub-manifests this row indexes. For inventory-style rows that group many smaller checks under one parent. The harness loads each and merges its rows.',
+      }),
+    ),
+    ports: Type.Record(Type.String(), PortStatusSchema, {
+      description:
+        "Per-port status map. Keys MUST match top-level `sites` keys exactly — the harness errors on stray ports / missing sites. Each value is `{status: 'implemented' | 'opt-out', ...}` per PortStatusSchema.",
+    }),
+  },
+  {
+    additionalProperties: false,
+    description:
+      'N sibling language ports of one spec within a single project. Drift = a port diverged from its siblings (one implemented, others opt-out without reason / or vice versa), or a `rejected` anti-pattern was reintroduced.',
+  },
+)
+
+export const RowSchema = Type.Union([
+  FileForkRowSchema,
+  VersionPinRowSchema,
+  FeatureParityRowSchema,
+  SpecConformanceRowSchema,
+  LangParityRowSchema,
+])
+
+// ---------------------------------------------------------------------------
+// Top-level manifest.
+// ---------------------------------------------------------------------------
+
+export const LockstepManifestSchema = Type.Object(
+  {
+    $schema: Type.Optional(
+      Type.String({
+        description:
+          'JSON Schema reference for editor autocompletion. Conventionally `./lockstep.schema.json` — both the manifest and its schema live side-by-side at repo root.',
+      }),
+    ),
+    description: Type.Optional(
+      Type.String({
+        description:
+          'Human-readable description of what this manifest tracks. Read by humans, not parsed. One short paragraph.',
+      }),
+    ),
+    area: Type.Optional(
+      Type.String({
+        description:
+          "Optional label for this manifest file. Used as a grouping key in harness output (per-area summaries). Defaults to 'root' for the top-level file and to the filename stem (with the `lockstep-` prefix stripped) for included files.",
+      }),
+    ),
+    includes: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          'Relative paths to sub-manifests. The harness loads each and merges its rows into a single flattened view. Top-level `upstreams` and `sites` maps override any same-keyed entries from included manifests (top wins on conflict).',
+      }),
+    ),
+    upstreams: Type.Optional(
+      Type.Record(Type.String(), UpstreamSchema, {
+        description:
+          'Named upstream submodules. Each entry pairs a submodule path with its repo URL. Referenced by rows[].upstream on file-fork / version-pin / feature-parity / spec-conformance rows. Omit when the manifest only has lang-parity rows.',
+      }),
+    ),
+    sites: Type.Optional(
+      Type.Record(Type.String(), SiteSchema, {
+        description:
+          'Named sibling ports (typically per-language: `cpp`, `go`, `rust`, `typescript`). Referenced by rows[].ports.<site> on lang-parity rows. Omit when the manifest has no lang-parity rows.',
+      }),
+    ),
+    rows: Type.Array(RowSchema, {
+      description:
+        "The actual checks the harness runs. Empty array is valid (and expected for repos that have no upstream relationships — e.g. socket-cli's empty rows).",
+    }),
+  },
+  {
+    description:
+      'Unified lock-step manifest shared across Socket repos. One schema, all cases — the `kind` discriminator on each row selects which flavor of lock-step applies. Single-file manifests work for repos with one cohesive concern; the `includes[]` field carves a manifest into per-area files (e.g. lockstep-acorn.json + lockstep-build.json) when one repo tracks multiple independent concerns.',
+  },
+)
+
+export type Row = Static<typeof RowSchema>
+export type LockstepManifest = Static<typeof LockstepManifestSchema>
+export type Upstream = Static<typeof UpstreamSchema>
+export type Site = Static<typeof SiteSchema>
+export type PortStatus = Static<typeof PortStatusSchema>
+export type FileForkRow = Static<typeof FileForkRowSchema>
+export type VersionPinRow = Static<typeof VersionPinRowSchema>
+export type FeatureParityRow = Static<typeof FeatureParityRowSchema>
+export type SpecConformanceRow = Static<typeof SpecConformanceRowSchema>
+export type LangParityRow = Static<typeof LangParityRowSchema>
diff --git a/scripts/lockstep.mts b/scripts/lockstep.mts
new file mode 100644
index 0000000..302a5b7
--- /dev/null
+++ b/scripts/lockstep.mts
@@ -0,0 +1,1000 @@
+/**
+ * @fileoverview lockstep harness (canonical; mirrored in
+ * socket-wheelhouse/template/scripts/lockstep.mts).
+ *
+ * Reads `lockstep.json` (+ any `includes[]` sub-manifests) and validates each
+ * row against its upstream or sibling ports. Every supported `kind` has a
+ * checker; a repo populates its manifest only with the kinds it needs.
+ *
+ * Kinds:
+ *   file-fork         vendored upstream file with local deviations;
+ *                     drift = upstream moved since our fork SHA.
+ *   version-pin       submodule pinned to a specific SHA/tag;
+ *                     drift = upstream cut a new release (on default ref).
+ *   feature-parity    local impl should match an upstream behavior;
+ *                     three-pillar score: code + test + fixture snapshot.
+ *   spec-conformance  local impl of an external spec at a known version.
+ *   lang-parity       N sibling language ports of one spec;
+ *                     drift = port diverged, or rejected anti-pattern
+ *                     reintroduced on any port.
+ *
+ * Exit codes:
+ *   0 — manifest valid, no drift.
+ *   1 — schema violation, missing file, unreachable baseline, unknown kind.
+ *   2 — drift (upstream moved, parity below floor, rejected anti-pattern).
+ *
+ * Output:
+ *   Default — human-readable, compact per-area summary + detailed rows.
+ *   `--format=json` or `--json` — single JSON object for CI tooling.
+ *
+ * Sources and learnings:
+ *   - file-fork and version-pin semantics: stuie (this repo).
+ *   - feature-parity three-pillar scoring: sdxgen
+ *     lock-step-features.json (snapshots replace the 20% tolerance).
+ *   - lang-parity ports, rejected anti-pattern, per-area summaries, exit
+ *     code 2 semantics: ultrathink/acorn/scripts/xlang-harness.mts.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+import { errorMessage } from '@socketsecurity/lib/errors'
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+import { spawnSync } from '@socketsecurity/lib/spawn'
+import { validateSchema } from '@socketsecurity/lib/schema/validate'
+
+import {
+  LockstepManifestSchema,
+  type FeatureParityRow,
+  type FileForkRow,
+  type LangParityRow,
+  type PortStatus,
+  type Row,
+  type Site,
+  type SpecConformanceRow,
+  type Upstream,
+  type VersionPinRow,
+  type LockstepManifest,
+} from './lockstep-schema.mts'
+
+const logger = getDefaultLogger()
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const rootDir = path.resolve(__dirname, '..')
+
+type Manifest = LockstepManifest
+
+// ---------------------------------------------------------------------------
+// Report types — one per kind so dispatcher output is typed precisely.
+// ---------------------------------------------------------------------------
+
+type Severity = 'ok' | 'drift' | 'error'
+
+interface ReportBase {
+  area: string
+  id: string
+  severity: Severity
+  messages: string[]
+}
+
+interface DriftCommit {
+  sha: string
+  summary: string
+}
+
+interface FileForkReport extends ReportBase {
+  kind: 'file-fork'
+  local: string
+  upstream: string
+  upstream_path: string
+  forked_at_sha: string
+  drift: DriftCommit[]
+}
+
+interface VersionPinReport extends ReportBase {
+  kind: 'version-pin'
+  upstream: string
+  pinned_sha: string
+  pinned_tag: string | undefined
+  upgrade_policy: string
+  head_sha: string | undefined
+  drift_count: number
+}
+
+interface FeatureParityReport extends ReportBase {
+  kind: 'feature-parity'
+  upstream: string
+  local_area: string
+  criticality: number
+  code_score: number
+  test_score: number
+  fixture_score: number
+  total_score: number
+}
+
+interface SpecConformanceReport extends ReportBase {
+  kind: 'spec-conformance'
+  upstream: string
+  local_impl: string
+  spec_version: string
+  spec_path: string | undefined
+}
+
+interface LangParityReport extends ReportBase {
+  kind: 'lang-parity'
+  category: string
+  ports: Record<string, PortStatus>
+}
+
+type Report =
+  | FileForkReport
+  | VersionPinReport
+  | FeatureParityReport
+  | SpecConformanceReport
+  | LangParityReport
+
+// ---------------------------------------------------------------------------
+// Generic helpers.
+// ---------------------------------------------------------------------------
+
+function readManifest(manifestPath: string): Manifest {
+  if (!existsSync(manifestPath)) {
+    logger.error(`lockstep: manifest not found at ${manifestPath}`)
+    process.exit(1)
+  }
+  let raw: unknown
+  try {
+    raw = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  } catch (e) {
+    logger.error(`lockstep: could not parse ${manifestPath}`)
+    logger.fail(`  ${errorMessage(e)}`)
+    process.exit(1)
+  }
+  const result = validateSchema(LockstepManifestSchema, raw)
+  if (result.ok) {
+    return result.value
+  }
+  logger.error(`lockstep: schema validation failed for ${manifestPath}`)
+  for (const issue of result.errors) {
+    const loc = issue.path.length ? issue.path.join('.') : '<root>'
+    logger.fail(`  ${loc}: ${issue.message}`)
+  }
+  process.exit(1)
+}
+
+/**
+ * Resolve a manifest + all its `includes[]` sub-manifests into a single
+ * flattened view. Each sub-manifest contributes its rows; the top-level
+ * upstreams/sites maps are merged (top-level wins on conflict).
+ */
+function loadManifestTree(rootManifestPath: string): {
+  areas: Array<{ area: string; manifest: Manifest }>
+  merged: Manifest
+} {
+  const rootManifest = readManifest(rootManifestPath)
+  const rootArea = rootManifest.area ?? 'root'
+  const areas: Array<{ area: string; manifest: Manifest }> = [
+    { area: rootArea, manifest: rootManifest },
+  ]
+
+  const includes = rootManifest.includes ?? []
+  const baseDir = path.dirname(rootManifestPath)
+  for (const rel of includes) {
+    const subPath = path.resolve(baseDir, rel)
+    const sub = readManifest(subPath)
+    const area =
+      sub.area ?? path.basename(rel, '.json').replace(/^lockstep-/, '')
+    areas.push({ area, manifest: sub })
+  }
+
+  // Null-prototype maps guard against prototype pollution via untrusted
+  // manifest keys. Double-cast through `unknown` so the
+  // `exactOptionalPropertyTypes + noUncheckedIndexedAccess` strict
+  // tsconfig in some repos accepts the `__proto__` sigil.
+  const mergedUpstreams: Record<string, Upstream> = {
+    __proto__: null,
+  } as unknown as Record<string, Upstream>
+  const mergedSites: Record<string, Site> = {
+    __proto__: null,
+  } as unknown as Record<string, Site>
+
+  const mergedRows: Row[] = []
+  // Include order, root last so it wins on duplicate keys.
+  for (const { manifest } of [...areas.slice(1), ...areas.slice(0, 1)]) {
+    for (const [k, v] of Object.entries(manifest.upstreams ?? {})) {
+      mergedUpstreams[k] = v
+    }
+    for (const [k, v] of Object.entries(manifest.sites ?? {})) {
+      mergedSites[k] = v
+    }
+  }
+  for (const { manifest } of areas) {
+    mergedRows.push(...manifest.rows)
+  }
+  return {
+    areas,
+    merged: {
+      upstreams: mergedUpstreams,
+      sites: mergedSites,
+      rows: mergedRows,
+    },
+  }
+}
+
+/**
+ * Split text on LF after CRLF normalization. Git on Windows / msys may
+ * emit CRLF-terminated output; bare `.split('\n')` leaves a trailing
+ * `\r` on every line that throws off downstream `includes`/match checks.
+ */
+function splitLines(text: string): string[] {
+  return text.replace(/\r\n/g, '\n').split('\n')
+}
+
+function gitIn(submoduleDir: string, args: string[]): string {
+  const result = spawnSync('git', ['-C', submoduleDir, ...args], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    stdioString: true,
+  })
+  if (result.error) {
+    throw result.error
+  }
+  if (result.status !== 0) {
+    throw new Error(
+      `git ${args.join(' ')} failed (status ${result.status}): ${String(result.stderr).trim()}`,
+    )
+  }
+  return String(result.stdout)
+}
+
+function shaIsReachable(submoduleDir: string, sha: string): boolean {
+  try {
+    gitIn(submoduleDir, ['cat-file', '-e', sha])
+    return true
+  } catch {
+    return false
+  }
+}
+
+function driftCommitsSince(
+  submoduleDir: string,
+  sha: string,
+  pathInRepo: string,
+): DriftCommit[] {
+  try {
+    const out = gitIn(submoduleDir, [
+      'log',
+      '--pretty=format:%H%x09%s',
+      `${sha}..HEAD`,
+      '--',
+      pathInRepo,
+    ])
+    const trimmed = out.trim()
+    if (!trimmed) {
+      return []
+    }
+    return splitLines(trimmed).map(line => {
+      // Preserve any embedded tabs in the commit subject (rare but
+      // possible) — `.split` destructuring would truncate at the
+      // first tab inside the summary.
+      const [commitSha, ...summaryParts] = line.split('\t')
+      return {
+        sha: commitSha ?? '',
+        summary: summaryParts.join('\t') ?? '',
+      }
+    })
+  } catch {
+    return []
+  }
+}
+
+function resolveUpstream(
+  manifest: Manifest,
+  alias: string,
+  messages: string[],
+): Upstream | undefined {
+  const upstream = manifest.upstreams?.[alias]
+  if (!upstream) {
+    const known = Object.keys(manifest.upstreams ?? {}).join(', ') || '(none)'
+    messages.push(`unknown upstream alias '${alias}' (known: ${known})`)
+    return undefined
+  }
+  return upstream
+}
+
+function walkDirFiles(dir: string, extRe: RegExp): string[] {
+  const files: string[] = []
+  if (!existsSync(dir)) {
+    return files
+  }
+  const stack: string[] = [dir]
+  while (stack.length > 0) {
+    const current = stack.pop()!
+    let entries: string[] = []
+    try {
+      entries = readdirSync(current)
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (entry === 'node_modules' || entry === '.git' || entry === 'dist') {
+        continue
+      }
+      const full = path.join(current, entry)
+      let stat
+      try {
+        stat = statSync(full)
+      } catch {
+        continue
+      }
+      if (stat.isDirectory()) {
+        stack.push(full)
+      } else if (stat.isFile() && extRe.test(entry)) {
+        files.push(full)
+      }
+    }
+  }
+  return files
+}
+
+function countPatternHits(files: string[], patterns: string[]): number {
+  if (patterns.length === 0) {
+    return 0
+  }
+  // Manifest authors occasionally land a bad regex; surface the bad
+  // pattern and keep going rather than throwing a SyntaxError that
+  // kills the whole run.
+  const compiled: RegExp[] = []
+  for (const p of patterns) {
+    try {
+      compiled.push(new RegExp(p))
+    } catch (e) {
+      logger.warn(
+        `lockstep: skipping invalid regex ${JSON.stringify(p)}: ${errorMessage(e)}`,
+      )
+    }
+  }
+  let hits = 0
+  for (const pat of compiled) {
+    for (const file of files) {
+      let content: string
+      try {
+        content = readFileSync(file, 'utf8')
+      } catch {
+        continue
+      }
+      if (pat.test(content)) {
+        hits += 1
+        break
+      }
+    }
+  }
+  return hits
+}
+
+// ---------------------------------------------------------------------------
+// Kind checkers.
+// ---------------------------------------------------------------------------
+
+function checkFileFork(
+  row: FileForkRow,
+  manifest: Manifest,
+  area: string,
+): FileForkReport {
+  const messages: string[] = []
+  const upstream = resolveUpstream(manifest, row.upstream, messages)
+  const base: FileForkReport = {
+    kind: 'file-fork',
+    area,
+    id: row.id,
+    severity: 'ok',
+    messages,
+    local: row.local,
+    upstream: row.upstream,
+    upstream_path: row.upstream_path,
+    forked_at_sha: row.forked_at_sha,
+    drift: [],
+  }
+  if (!upstream) {
+    base.severity = 'error'
+    return base
+  }
+  const submoduleDir = path.join(rootDir, upstream.submodule)
+  const localPath = path.join(rootDir, row.local)
+  const upstreamFilePath = path.join(submoduleDir, row.upstream_path)
+
+  if (!existsSync(localPath)) {
+    base.severity = 'error'
+    messages.push(`local file missing: ${row.local}`)
+  }
+  if (!existsSync(upstreamFilePath)) {
+    base.severity = 'error'
+    messages.push(
+      `upstream file missing — submodule out of date, or upstream_path stale`,
+    )
+  }
+  if (!shaIsReachable(submoduleDir, row.forked_at_sha)) {
+    base.severity = 'error'
+    messages.push(
+      `forked_at_sha unreachable in submodule — submodule too shallow, or SHA typo`,
+    )
+  }
+  if (base.severity === 'error') {
+    return base
+  }
+  const drift = driftCommitsSince(
+    submoduleDir,
+    row.forked_at_sha,
+    row.upstream_path,
+  )
+  base.drift = drift
+  if (drift.length > 0) {
+    base.severity = 'drift'
+    messages.push(
+      `${drift.length} upstream commit(s) since fork — review for bugfixes/features`,
+    )
+  }
+  return base
+}
+
+function checkVersionPin(
+  row: VersionPinRow,
+  manifest: Manifest,
+  area: string,
+): VersionPinReport {
+  const messages: string[] = []
+  const upstream = resolveUpstream(manifest, row.upstream, messages)
+  const base: VersionPinReport = {
+    kind: 'version-pin',
+    area,
+    id: row.id,
+    severity: 'ok',
+    messages,
+    upstream: row.upstream,
+    pinned_sha: row.pinned_sha,
+    pinned_tag: row.pinned_tag ?? undefined,
+    upgrade_policy: row.upgrade_policy,
+    head_sha: undefined,
+    drift_count: 0,
+  }
+  if (!upstream) {
+    base.severity = 'error'
+    return base
+  }
+  const submoduleDir = path.join(rootDir, upstream.submodule)
+  if (!existsSync(submoduleDir)) {
+    base.severity = 'error'
+    messages.push(
+      `submodule not checked out at ${upstream.submodule} — run \`git submodule update --init\``,
+    )
+    return base
+  }
+  if (!shaIsReachable(submoduleDir, row.pinned_sha)) {
+    base.severity = 'error'
+    messages.push(`pinned_sha unreachable — submodule too shallow, or SHA typo`)
+    return base
+  }
+  let head = ''
+  try {
+    head = gitIn(submoduleDir, ['rev-parse', 'HEAD']).trim()
+  } catch {
+    base.severity = 'error'
+    messages.push(`could not read submodule HEAD`)
+    return base
+  }
+  base.head_sha = head
+
+  if (head !== row.pinned_sha) {
+    base.severity = 'error'
+    messages.push(
+      `submodule HEAD (${head.slice(0, 12)}) does not match pinned_sha (${row.pinned_sha.slice(0, 12)}) — run \`git submodule update\``,
+    )
+    return base
+  }
+
+  // Count commits on the upstream default branch since pinned SHA.
+  let driftRef = ''
+  try {
+    const remoteRefs = gitIn(submoduleDir, [
+      'for-each-ref',
+      '--format=%(refname)',
+      'refs/remotes/origin/',
+    ])
+    const lines = splitLines(remoteRefs).filter(s => s.trim())
+    const pref = [
+      'refs/remotes/origin/HEAD',
+      'refs/remotes/origin/main',
+      // inclusive-language: external-api — git's historical default branch.
+      'refs/remotes/origin/master',
+    ]
+    for (const p of pref) {
+      if (lines.includes(p)) {
+        driftRef = p
+        break
+      }
+    }
+  } catch {
+    // no remotes available — drift can't be computed; report OK with a note.
+  }
+  if (!driftRef) {
+    messages.push(`no origin remote ref found; cannot compute upstream drift`)
+    return base
+  }
+  try {
+    const count = gitIn(submoduleDir, [
+      'rev-list',
+      '--count',
+      `${row.pinned_sha}..${driftRef}`,
+    ]).trim()
+    const n = parseInt(count, 10)
+    if (!Number.isNaN(n) && n > 0) {
+      base.drift_count = n
+      base.severity = 'drift'
+      const tagSuffix = row.pinned_tag ? ` (from ${row.pinned_tag})` : ''
+      messages.push(
+        `${n} upstream commit(s) since pin${tagSuffix} on ${driftRef.replace('refs/remotes/', '')}`,
+      )
+    }
+  } catch {
+    // silent — drift ref not fetched.
+  }
+  return base
+}
+
+function checkFeatureParity(
+  row: FeatureParityRow,
+  _manifest: Manifest,
+  area: string,
+): FeatureParityReport {
+  const messages: string[] = []
+  const base: FeatureParityReport = {
+    kind: 'feature-parity',
+    area,
+    id: row.id,
+    severity: 'ok',
+    messages,
+    upstream: row.upstream,
+    local_area: row.local_area,
+    criticality: row.criticality,
+    code_score: 0,
+    test_score: 0,
+    fixture_score: 0,
+    total_score: 0,
+  }
+  const localAreaPath = path.join(rootDir, row.local_area)
+  if (!existsSync(localAreaPath)) {
+    base.severity = 'error'
+    messages.push(`local_area path missing: ${row.local_area}`)
+    return base
+  }
+
+  const codePatterns = row.code_patterns ?? []
+  const testPatterns = row.test_patterns ?? []
+  const codeFiles = walkDirFiles(localAreaPath, /\.(m?[jt]sx?|json)$/).filter(
+    f => !/[/\\](test|tests|__tests__)[/\\]|\.test\.|\.spec\./.test(f),
+  )
+
+  const codeScore =
+    codePatterns.length === 0
+      ? 1
+      : countPatternHits(codeFiles, codePatterns) / codePatterns.length
+
+  // Test files: by default search local_area; if test_area is set, search
+  // that directory instead (sdxgen-style where tests live outside the
+  // parser directory).
+  const testAreaPath = path.join(rootDir, row.test_area ?? row.local_area)
+  const testAreaFiles = walkDirFiles(testAreaPath, /\.(m?[jt]sx?|json)$/)
+  const testFiles = row.test_area
+    ? testAreaFiles
+    : testAreaFiles.filter(f =>
+        /[/\\](test|tests|__tests__)[/\\]|\.test\.|\.spec\./.test(f),
+      )
+  const testScore =
+    testPatterns.length === 0
+      ? 1
+      : countPatternHits(testFiles, testPatterns) / testPatterns.length
+
+  let fixtureScore = 1
+  if (row.fixture_check) {
+    const fixturePath = path.join(rootDir, row.fixture_check.fixture_path)
+    if (!existsSync(fixturePath)) {
+      fixtureScore = 0
+      messages.push(`fixture not found: ${row.fixture_check.fixture_path}`)
+    } else if (row.fixture_check.snapshot_path) {
+      const snapPath = path.join(rootDir, row.fixture_check.snapshot_path)
+      if (!existsSync(snapPath)) {
+        fixtureScore = 0
+        messages.push(
+          `snapshot not found: ${row.fixture_check.snapshot_path} — run test suite to generate`,
+        )
+      }
+    }
+  }
+
+  base.code_score = Math.round(codeScore * 100) / 100
+  base.test_score = Math.round(testScore * 100) / 100
+  base.fixture_score = Math.round(fixtureScore * 100) / 100
+  const total = 0.3 * codeScore + 0.3 * testScore + 0.4 * fixtureScore
+  base.total_score = Math.round(total * 100) / 100
+
+  // Floor: higher criticality = stricter. Cap at 0.85 so 10/10 criticality
+  // doesn't demand perfect pattern coverage (code is prose, patterns miss).
+  const floor = Math.min(0.85, row.criticality / 10)
+  if (total < floor) {
+    base.severity = 'drift'
+    messages.push(
+      `parity score ${base.total_score} below floor ${Math.round(floor * 100) / 100} (criticality ${row.criticality})`,
+    )
+  }
+  return base
+}
+
+function checkSpecConformance(
+  row: SpecConformanceRow,
+  manifest: Manifest,
+  area: string,
+): SpecConformanceReport {
+  const messages: string[] = []
+  const upstream = resolveUpstream(manifest, row.upstream, messages)
+  const base: SpecConformanceReport = {
+    kind: 'spec-conformance',
+    area,
+    id: row.id,
+    severity: 'ok',
+    messages,
+    upstream: row.upstream,
+    local_impl: row.local_impl,
+    spec_version: row.spec_version,
+    spec_path: row.spec_path ?? undefined,
+  }
+  if (!upstream) {
+    base.severity = 'error'
+    return base
+  }
+  const localImplPath = path.join(rootDir, row.local_impl)
+  if (!existsSync(localImplPath)) {
+    base.severity = 'error'
+    messages.push(`local_impl missing: ${row.local_impl}`)
+    return base
+  }
+  if (row.spec_path) {
+    const specPath = path.join(rootDir, upstream.submodule, row.spec_path)
+    if (!existsSync(specPath)) {
+      base.severity = 'error'
+      messages.push(`spec_path missing in upstream submodule: ${row.spec_path}`)
+      return base
+    }
+  }
+  return base
+}
+
+function checkLangParity(
+  row: LangParityRow,
+  manifest: Manifest,
+  area: string,
+): LangParityReport {
+  const messages: string[] = []
+  const base: LangParityReport = {
+    kind: 'lang-parity',
+    area,
+    id: row.id,
+    severity: 'ok',
+    messages,
+    category: row.category,
+    ports: row.ports,
+  }
+
+  const declaredSites = Object.keys(manifest.sites ?? {})
+  if (declaredSites.length === 0) {
+    base.severity = 'error'
+    messages.push(`manifest has lang-parity rows but no top-level 'sites' map`)
+    return base
+  }
+
+  for (const site of declaredSites) {
+    if (!(site in row.ports)) {
+      base.severity = 'error'
+      messages.push(`port '${site}' missing (declared in sites)`)
+    }
+  }
+  for (const port of Object.keys(row.ports)) {
+    if (!declaredSites.includes(port)) {
+      base.severity = 'error'
+      messages.push(`port '${port}' not in sites map`)
+    }
+    const state = row.ports[port]!
+    if (state.status === 'opt-out' && (!state.reason || !state.reason.trim())) {
+      base.severity = 'error'
+      messages.push(`port '${port}' is opt-out without a reason`)
+    }
+  }
+
+  if (row.category === 'rejected') {
+    for (const port of Object.keys(row.ports)) {
+      const state = row.ports[port]!
+      if (state.status !== 'opt-out') {
+        base.severity = 'drift'
+        messages.push(
+          `REJECTED anti-pattern reintroduced: port '${port}' is '${state.status}' (must be 'opt-out' for category=rejected)`,
+        )
+      }
+    }
+  }
+
+  return base
+}
+
+// ---------------------------------------------------------------------------
+// Cross-row consistency checks (beyond zod's per-row validation).
+// ---------------------------------------------------------------------------
+
+/**
+ * Cross-row checks that zod validation can't express: unique ids, upstream
+ * refs resolve to the `upstreams` map, port keys resolve to the `sites`
+ * map. Zod's `LockstepManifestSchema.parse()` (called from `loadManifestTree`)
+ * already covers per-row shape, enum values, id pattern, and required
+ * fields — this is the referential-integrity layer on top.
+ */
+function checkCrossRowConsistency(
+  rowsWithArea: Array<{ row: Row; area: string }>,
+  merged: Manifest,
+): string[] {
+  const errors: string[] = []
+  // Ids are unique per area, not globally. Same concept can legitimately
+  // appear in multiple areas (e.g. ultrathink has `transport-stdio` in both
+  // lsp and mcp). Scope the seen-set per area.
+  const seenIdsPerArea = new Map<string, Set<string>>()
+  const upstreamAliases = new Set(Object.keys(merged.upstreams ?? {}))
+  const siteKeys = new Set(Object.keys(merged.sites ?? {}))
+
+  for (const { row, area } of rowsWithArea) {
+    const loc = `[${area}/${row.id}]`
+
+    let areaIds = seenIdsPerArea.get(area)
+    if (!areaIds) {
+      areaIds = new Set()
+      seenIdsPerArea.set(area, areaIds)
+    }
+    if (areaIds.has(row.id)) {
+      errors.push(`${loc} duplicate id within area`)
+    }
+    areaIds.add(row.id)
+
+    if (
+      row.kind === 'file-fork' ||
+      row.kind === 'version-pin' ||
+      row.kind === 'feature-parity' ||
+      row.kind === 'spec-conformance'
+    ) {
+      if (!upstreamAliases.has(row.upstream)) {
+        errors.push(
+          `${loc} upstream '${row.upstream}' not in upstreams map (known: ${[...upstreamAliases].join(', ') || '(none)'})`,
+        )
+      }
+    }
+
+    if (row.kind === 'lang-parity') {
+      for (const port of Object.keys(row.ports)) {
+        if (!siteKeys.has(port)) {
+          errors.push(
+            `${loc} port '${port}' not in sites map (known: ${[...siteKeys].join(', ') || '(none)'})`,
+          )
+        }
+      }
+    }
+  }
+
+  return errors
+}
+
+// ---------------------------------------------------------------------------
+// Dispatcher.
+// ---------------------------------------------------------------------------
+
+function evaluate(
+  rowsWithArea: Array<{ row: Row; area: string }>,
+  merged: Manifest,
+): Report[] {
+  const reports: Report[] = []
+  for (const { row, area } of rowsWithArea) {
+    switch (row.kind) {
+      case 'file-fork':
+        reports.push(checkFileFork(row, merged, area))
+        break
+      case 'version-pin':
+        reports.push(checkVersionPin(row, merged, area))
+        break
+      case 'feature-parity':
+        reports.push(checkFeatureParity(row, merged, area))
+        break
+      case 'spec-conformance':
+        reports.push(checkSpecConformance(row, merged, area))
+        break
+      case 'lang-parity':
+        reports.push(checkLangParity(row, merged, area))
+        break
+      default: {
+        const anyRow = row as { kind: string; id: string }
+        reports.push({
+          kind: 'file-fork',
+          area,
+          id: anyRow.id,
+          severity: 'error',
+          messages: [`no checker registered for kind '${anyRow.kind}'`],
+          local: '',
+          upstream: '',
+          upstream_path: '',
+          forked_at_sha: '',
+          drift: [],
+        })
+        process.exitCode = 1
+      }
+    }
+  }
+  return reports
+}
+
+// ---------------------------------------------------------------------------
+// Per-area summary (learned from ultrathink xlang-harness).
+// ---------------------------------------------------------------------------
+
+interface AreaSummary {
+  area: string
+  total: number
+  ok: number
+  drift: number
+  error: number
+}
+
+function summarize(reports: Report[]): AreaSummary[] {
+  const byArea = new Map<string, AreaSummary>()
+  for (const r of reports) {
+    let s = byArea.get(r.area)
+    if (!s) {
+      s = { area: r.area, total: 0, ok: 0, drift: 0, error: 0 }
+      byArea.set(r.area, s)
+    }
+    s.total += 1
+    s[r.severity] += 1
+  }
+  return [...byArea.values()].sort((a, b) => a.area.localeCompare(b.area))
+}
+
+// ---------------------------------------------------------------------------
+// Output.
+// ---------------------------------------------------------------------------
+
+function emitHuman(reports: Report[], summaries: AreaSummary[]): number {
+  logger.info(
+    `lockstep — ${reports.length} row(s) across ${summaries.length} area(s)`,
+  )
+  logger.info('')
+  for (const s of summaries) {
+    const label = s.area.padEnd(24)
+    const parts = `total=${String(s.total).padStart(3)}  ok=${String(s.ok).padStart(3)}  drift=${String(s.drift).padStart(3)}  error=${String(s.error).padStart(3)}`
+    logger.info(`  ${label}${parts}`)
+  }
+  logger.info('')
+
+  let hadError = false
+  let hadDrift = false
+  for (const r of reports) {
+    const banner = `[${r.area}/${r.id}] (${r.kind})`
+    if (r.kind === 'file-fork') {
+      logger.info(banner)
+      logger.info(`  local: ${r.local}`)
+      logger.info(
+        `  upstream: ${r.upstream}:${r.upstream_path} @ ${r.forked_at_sha.slice(0, 12)}`,
+      )
+    } else if (r.kind === 'version-pin') {
+      logger.info(banner)
+      const tag = r.pinned_tag ? ` (${r.pinned_tag})` : ''
+      logger.info(
+        `  upstream: ${r.upstream} @ ${r.pinned_sha.slice(0, 12)}${tag}, policy=${r.upgrade_policy}`,
+      )
+    } else if (r.kind === 'feature-parity') {
+      logger.info(banner)
+      logger.info(
+        `  upstream: ${r.upstream}, local_area: ${r.local_area}, criticality: ${r.criticality}`,
+      )
+      logger.info(
+        `  scores: code=${r.code_score} test=${r.test_score} fixture=${r.fixture_score} total=${r.total_score}`,
+      )
+    } else if (r.kind === 'spec-conformance') {
+      logger.info(banner)
+      logger.info(
+        `  upstream: ${r.upstream}, local_impl: ${r.local_impl}, spec_version: ${r.spec_version}`,
+      )
+    } else if (r.kind === 'lang-parity') {
+      logger.info(banner)
+      logger.info(`  category: ${r.category}`)
+      for (const [port, state] of Object.entries(r.ports)) {
+        const suffix =
+          state.status === 'opt-out' ? ` (${state.reason ?? ''})` : ''
+        logger.info(`    ${port}: ${state.status}${suffix}`)
+      }
+    }
+
+    for (const msg of r.messages) {
+      if (r.severity === 'error') {
+        logger.fail(`  ${msg}`)
+      } else if (r.severity === 'drift') {
+        logger.warn(`  ${msg}`)
+      } else {
+        logger.info(`  ${msg}`)
+      }
+    }
+
+    if (r.kind === 'file-fork') {
+      for (const c of r.drift) {
+        logger.info(`    ${c.sha.slice(0, 12)} ${c.summary}`)
+      }
+    }
+
+    if (r.severity === 'ok') {
+      logger.success(`  ok`)
+    } else if (r.severity === 'error') {
+      hadError = true
+    } else if (r.severity === 'drift') {
+      hadDrift = true
+    }
+    logger.info('')
+  }
+
+  if (hadError) {
+    return 1
+  }
+  if (hadDrift) {
+    return 2
+  }
+  return 0
+}
+
+function main(): void {
+  const rootManifestPath = path.join(rootDir, 'lockstep.json')
+  const { areas, merged } = loadManifestTree(rootManifestPath)
+
+  const rowsWithArea: Array<{ row: Row; area: string }> = []
+  for (const { area, manifest } of areas) {
+    for (const row of manifest.rows) {
+      rowsWithArea.push({ row, area })
+    }
+  }
+
+  const crossRowErrors = checkCrossRowConsistency(rowsWithArea, merged)
+  if (crossRowErrors.length > 0) {
+    for (const err of crossRowErrors) {
+      logger.fail(err)
+    }
+    logger.error(
+      `lockstep: ${crossRowErrors.length} cross-row error(s) — fix before running drift checks`,
+    )
+    process.exit(1)
+  }
+
+  const reports = evaluate(rowsWithArea, merged)
+  const summaries = summarize(reports)
+
+  const jsonMode =
+    process.argv.includes('--json') || process.argv.includes('--format=json')
+
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify({ reports, summaries }, null, 2) + '\n')
+    const anyError = reports.some(r => r.severity === 'error')
+    const anyDrift = reports.some(r => r.severity === 'drift')
+    if (anyError) {
+      process.exitCode = 1
+    } else if (anyDrift) {
+      process.exitCode = 2
+    }
+    return
+  }
+
+  const code = emitHuman(reports, summaries)
+  if (code !== 0) {
+    process.exitCode = code
+  }
+}
+
+main()
diff --git a/scripts/power-state.mts b/scripts/power-state.mts
new file mode 100644
index 0000000..e4a293b
--- /dev/null
+++ b/scripts/power-state.mts
@@ -0,0 +1,185 @@
+/**
+ * @fileoverview Detect whether the host is currently on AC power
+ * (vs battery). Used by long-running build/test scripts to size
+ * timeouts adaptively — laptops on battery throttle CPU hard
+ * (especially macOS), and a static timeout that fits AC will kill
+ * an otherwise-healthy run on battery.
+ *
+ * Two paths, in priority order:
+ *
+ *   1. `node:smol-power` — when running inside a node-smol binary
+ *      that ships the smol_power native binding (socket-btm's custom
+ *      Node distribution). Pure C++ syscalls, sub-millisecond.
+ *
+ *   2. Shellout fallback — system Node doesn't have node:smol-power.
+ *      Each platform has a different mechanism:
+ *        * macOS:   `pmset -g batt` parses "AC Power" / "Battery Power"
+ *        * Linux:   reads /sys/class/power_supply/<entry>/online
+ *                   (no shellout, just open/read syscalls)
+ *        * Windows: PowerShell `Get-CimInstance Win32_Battery`
+ *
+ * On detection failure we conservatively assume AC — the downstream
+ * timeout becomes the shorter / more aggressive value, which is
+ * appropriate for build servers and headless CI (those environments
+ * are expected to run at full speed).
+ *
+ * Returns a Promise so callers don't block the event loop on shellout
+ * paths.
+ *
+ * Byte-identical across the fleet via socket-wheelhouse's
+ * sync-scaffolding (IDENTICAL_FILES).
+ */
+
+import { Buffer } from 'node:buffer'
+import { existsSync, promises as fs } from 'node:fs'
+import { isBuiltin } from 'node:module'
+import path from 'node:path'
+import process from 'node:process'
+
+import { spawn } from '@socketsecurity/lib/spawn'
+
+// Probe for node:smol-power. Lives in socket-btm's node-smol binary
+// — `isBuiltin()` returns true on those builds and false on system
+// Node, so we only attempt the dynamic import when the module is
+// actually available.
+interface SmolPower {
+  isOnAcPower: () => boolean
+}
+let _smolPower: SmolPower | undefined
+let _smolPowerProbed = false
+async function getSmolPower(): Promise<SmolPower | undefined> {
+  if (_smolPowerProbed) {
+    return _smolPower
+  }
+  _smolPowerProbed = true
+  if (!isBuiltin('node:smol-power')) {
+    return undefined
+  }
+  // Cast through `unknown` because system Node's typings don't
+  // declare the module — only node-smol's lib.d.ts does.
+  _smolPower = (await import(
+    'node:smol-power' as string
+  )) as unknown as SmolPower
+  return _smolPower
+}
+
+// Coerce spawn's stdout (string | Buffer | undefined) to a string.
+function stdoutString(value: unknown): string {
+  if (typeof value === 'string') {
+    return value
+  }
+  if (value instanceof Uint8Array) {
+    return Buffer.from(value).toString('utf8')
+  }
+  return ''
+}
+
+async function detectMacOs(): Promise<boolean> {
+  try {
+    // `pmset -g batt` on macOS prints lines like
+    //   Now drawing from 'AC Power'
+    //   Now drawing from 'Battery Power'
+    // Match the AC variant; everything else (battery, unknown) is
+    // treated as not-AC.
+    const result = await spawn('pmset', ['-g', 'batt'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    return /AC Power/.test(stdoutString(result.stdout))
+  } catch {
+    return true
+  }
+}
+
+async function detectLinux(): Promise<boolean> {
+  // Linux exposes power state under /sys/class/power_supply. Each
+  // AC adapter is its own dir (`AC`, `ADP1`, `AC0`, `ACAD`, …)
+  // with an `online` file holding "1" when power is connected.
+  // Containers and headless servers often have no power_supply
+  // tree at all — treat that as AC since those environments are
+  // expected to run at full speed.
+  const psDir = '/sys/class/power_supply'
+  if (!existsSync(psDir)) {
+    return true
+  }
+  try {
+    const entries = await fs.readdir(psDir)
+    for (const entry of entries) {
+      const onlineFile = path.join(psDir, entry, 'online')
+      if (!existsSync(onlineFile)) {
+        continue
+      }
+      try {
+        const value = await fs.readFile(onlineFile, 'utf8')
+        if (value.trim() === '1') {
+          return true
+        }
+      } catch {
+        // Unreadable entry — skip; another entry may report.
+      }
+    }
+  } catch {
+    // Directory enumeration failed — fall through to AC.
+    return true
+  }
+  return false
+}
+
+async function detectWindows(): Promise<boolean> {
+  try {
+    // Windows: query the battery status via PowerShell + CIM.
+    // `Win32_Battery.BatteryStatus`:
+    //   1 = Discharging        (battery)
+    //   2 = On AC, not charging or fully charged
+    //   3..5 = Various battery states
+    //   6 = AC + charging
+    // Desktops with no battery return an empty result; treat as AC.
+    const result = await spawn(
+      'powershell.exe',
+      [
+        '-NoProfile',
+        '-Command',
+        '(Get-CimInstance -ClassName Win32_Battery).BatteryStatus',
+      ],
+      { stdio: ['ignore', 'pipe', 'ignore'] },
+    )
+    const trimmed = stdoutString(result.stdout).trim()
+    if (trimmed === '') {
+      return true
+    }
+    const status = Number.parseInt(trimmed, 10)
+    if (Number.isNaN(status)) {
+      return true
+    }
+    return status === 2 || status === 6
+  } catch {
+    return true
+  }
+}
+
+/**
+ * Returns `true` if the host is on AC power. Conservative on
+ * detection failure (returns `true`) — callers using this for
+ * timeout sizing prefer a longer timeout to a too-short one.
+ *
+ * Prefers the native binding (`node:smol-power`) when running
+ * inside a node-smol binary; falls back to a per-platform path
+ * (shellout on macOS / Windows, direct sysfs reads on Linux) on
+ * system Node.
+ */
+export async function isOnAcPower(): Promise<boolean> {
+  const native = await getSmolPower()
+  if (native) {
+    return native.isOnAcPower()
+  }
+  if (process.platform === 'darwin') {
+    return await detectMacOs()
+  }
+  if (process.platform === 'linux') {
+    return await detectLinux()
+  }
+  if (process.platform === 'win32') {
+    return await detectWindows()
+  }
+  // Unsupported platform; conservative default.
+  return true
+}
diff --git a/scripts/security.mts b/scripts/security.mts
new file mode 100644
index 0000000..b6c9290
--- /dev/null
+++ b/scripts/security.mts
@@ -0,0 +1,86 @@
+/**
+ * @fileoverview Canonical fleet scanning-security runner.
+ *
+ * Runs the two static-analysis tools the fleet uses for local security
+ * checks before push:
+ *
+ *   1. AgentShield — scans `.claude/` config for prompt-injection,
+ *      leaked secrets, and overly-permissive tool permissions.
+ *   2. zizmor      — static analysis for `.github/workflows/*.yml`
+ *      (unpinned actions, secret exposure, template injection,
+ *      permission issues).
+ *
+ * Either tool missing prints a "run pnpm run setup" hint (which
+ * downloads + verifies the pinned binary via the setup-security-tools
+ * hook) and skips that scan rather than failing the entire run.
+ *
+ * Cross-platform: uses `which` from `@socketsecurity/lib/bin` for
+ * binary discovery (handles Windows .exe/.cmd resolution; returns null
+ * rather than throwing on miss) and `spawn` from
+ * `@socketsecurity/lib/spawn` for proper async lifecycle.
+ *
+ * Wired in via `package.json`:
+ *
+ *   "security": "node scripts/security.mts"
+ *
+ * Byte-identical across every fleet repo. Sync-scaffolding flags
+ * drift.
+ */
+
+import process from 'node:process'
+
+import { which } from '@socketsecurity/lib/bin'
+import { WIN32 } from '@socketsecurity/lib/constants/platform'
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+import { spawn } from '@socketsecurity/lib/spawn'
+
+const logger = getDefaultLogger()
+
+async function hasExecutable(name: string): Promise<boolean> {
+  // socket-lib's `which` returns null when the binary isn't on PATH
+  // (no throw), so a simple truthy check suffices.
+  return Boolean(await which(name))
+}
+
+async function runTool(command: string, args: string[]): Promise<number> {
+  try {
+    const result = await spawn(command, args, {
+      stdio: 'inherit',
+      shell: WIN32,
+    })
+    return result.code ?? 1
+  } catch (e) {
+    if (e && typeof e === 'object' && 'code' in e) {
+      const code = (e as { code: unknown }).code
+      return typeof code === 'number' ? code : 1
+    }
+    throw e
+  }
+}
+
+async function main(): Promise<void> {
+  if (!(await hasExecutable('agentshield'))) {
+    logger.info('agentshield not installed; run "pnpm run setup" to install')
+  } else {
+    const agentshieldCode = await runTool('agentshield', ['scan'])
+    if (agentshieldCode !== 0) {
+      process.exitCode = agentshieldCode
+      return
+    }
+  }
+
+  if (!(await hasExecutable('zizmor'))) {
+    logger.info('zizmor not installed; run "pnpm run setup" to install')
+    return
+  }
+
+  const zizmorCode = await runTool('zizmor', ['.github/'])
+  if (zizmorCode !== 0) {
+    process.exitCode = zizmorCode
+  }
+}
+
+main().catch((e: unknown) => {
+  logger.error(e)
+  process.exitCode = 1
+})
diff --git a/scripts/socket-wheelhouse-emit-schema.mts b/scripts/socket-wheelhouse-emit-schema.mts
new file mode 100644
index 0000000..596a158
--- /dev/null
+++ b/scripts/socket-wheelhouse-emit-schema.mts
@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Emit `socket-wheelhouse-schema.json` from the
+ * TypeBox source.
+ *
+ * Run via `pnpm run socket-wheelhouse:emit-schema` from a fleet
+ * repo (the worktree where TypeBox is installed). Mirrors the lockstep
+ * emit pattern.
+ */
+
+import { writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { spawn } from '@socketsecurity/lib/spawn'
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+
+import { SocketWheelhouseConfigSchema } from './socket-wheelhouse-schema.mts'
+
+const logger = getDefaultLogger()
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const rootDir = path.resolve(__dirname, '..')
+// Schema lives in `.config/` next to the per-repo
+// `.config/socket-wheelhouse.json` it describes — the marker's
+// `$schema` ref is `./socket-wheelhouse-schema.json`.
+const outPath = path.join(rootDir, '.config', 'socket-wheelhouse-schema.json')
+
+const enriched = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'https://github.com/SocketDev/socket-wheelhouse-schema.json',
+  title: 'socket-wheelhouse per-repo config',
+  ...SocketWheelhouseConfigSchema,
+}
+
+writeFileSync(outPath, JSON.stringify(enriched, null, 2) + '\n', 'utf8')
+
+// Run oxfmt on the output so the file matches what oxfmt would
+// produce. Without this, `pnpm run check --all` (which runs oxfmt
+// over the tree) would flag the emitted schema as drifted on every
+// repo that re-emits it. The schema is in IDENTICAL_FILES, so the
+// formatted form is the byte-canonical form fleet-wide.
+await spawn(
+  'pnpm',
+  ['exec', 'oxfmt', '-c', '.config/oxfmtrc.json', outPath],
+  {
+    cwd: rootDir,
+    stdio: 'inherit',
+  },
+)
+
+logger.success(`wrote ${path.relative(rootDir, outPath)}`)
diff --git a/scripts/socket-wheelhouse-schema.mts b/scripts/socket-wheelhouse-schema.mts
new file mode 100644
index 0000000..c141acc
--- /dev/null
+++ b/scripts/socket-wheelhouse-schema.mts
@@ -0,0 +1,281 @@
+/**
+ * @fileoverview TypeBox schema for the per-fleet-repo socket-wheelhouse
+ * config consumed by `sync-scaffolding`. Two valid locations:
+ * `.config/socket-wheelhouse.json` (primary) or
+ * `.socket-wheelhouse.json` at the repo root (alternative). Both are
+ * first-class — pick the location that fits your repo's convention.
+ *
+ * Each fleet repo (socket-lib, socket-cli, ultrathink, …) ships this
+ * config declaring its `layout` + `native` axes plus any per-repo
+ * opt-ins. The runner reads it to decide which optional files the
+ * repo is expected to ship and which it must not ship.
+ *
+ * Source-of-truth flow:
+ *   - This TypeBox source → `Static<typeof SocketWheelhouseConfigSchema>`
+ *     for typed reads in the runner.
+ *   - `socket-wheelhouse-emit-schema.mts` writes
+ *     `.config/socket-wheelhouse-schema.json` (draft 2020-12) next to
+ *     the per-repo config.
+ *   - The per-repo config references the JSON Schema via its `$schema`
+ *     field for IDE autocompletion.
+ *
+ * Byte-identical across the fleet via sync-scaffolding's IDENTICAL_FILES.
+ */
+
+import { Type, type Static } from '@sinclair/typebox'
+
+// ---------------------------------------------------------------------------
+// Two orthogonal axes describe a fleet repo:
+//
+//   layout  — package shape: single-package vs monorepo.
+//   native  — native-binary supply-chain role: none / consumer /
+//             producer / both.
+//
+// Per-language ports (e.g. ultrathink's cpp/go/rust/typescript ports
+// of one spec) live in `lockstep.json` `lang-parity` rows, not here —
+// the manifest is the source of truth for parity tracking.
+// ---------------------------------------------------------------------------
+
+const LayoutSchema = Type.Union(
+  [Type.Literal('single-package'), Type.Literal('monorepo')],
+  {
+    description:
+      'Package layout. `single-package` = one `package.json` at root, no `packages/`. `monorepo` = pnpm workspaces under `packages/`.',
+  },
+)
+
+const NativeSchema = Type.Union(
+  [
+    Type.Literal('none'),
+    Type.Literal('consumer'),
+    Type.Literal('producer'),
+    Type.Literal('both'),
+  ],
+  {
+    description:
+      'Native-binary supply-chain role. `none` = pure-npm publish path. `consumer` = pulls prebuilt binaries from a sibling producer. `producer` = ships native artifacts via GH releases. `both` = consumes one set, produces another. (Per-language ports live in `lockstep.json` `lang-parity` rows, not here.)',
+  },
+)
+
+// ---------------------------------------------------------------------------
+// Hooks block — git hook variant selection.
+// ---------------------------------------------------------------------------
+
+const HooksSchema = Type.Object(
+  {
+    enablePrePush: Type.Optional(
+      Type.Boolean({
+        description:
+          'Wire `.husky/pre-push` → `.git-hooks/pre-push.mts`. Mandatory security gate; default true.',
+      }),
+    ),
+    enableCommitMsg: Type.Optional(
+      Type.Boolean({
+        description:
+          'Wire `.husky/commit-msg` → `.git-hooks/commit-msg.mts`. Strips AI attribution; default true.',
+      }),
+    ),
+    enablePreCommit: Type.Optional(
+      Type.Boolean({
+        description:
+          'Wire `.husky/pre-commit` → `.git-hooks/pre-commit.mts`. Lint + secret scan on staged files; default true.',
+      }),
+    ),
+    preCommitVariant: Type.Optional(
+      Type.Union([Type.Literal('lint-only'), Type.Literal('lint-test')], {
+        description:
+          '`lint-only` runs format + secret scan; `lint-test` adds vitest on touched packages. Default `lint-test`.',
+      }),
+    ),
+  },
+  { description: 'Git-hook opt-ins.' },
+)
+
+// ---------------------------------------------------------------------------
+// Scripts block — package.json script declarations.
+// ---------------------------------------------------------------------------
+
+const ScriptsSchema = Type.Object(
+  {
+    required: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          'Override REQUIRED_SCRIPTS from manifest.mts. Usually omitted — the fleet default applies.',
+      }),
+    ),
+    optional: Type.Optional(
+      Type.Record(Type.String(), Type.Boolean(), {
+        description:
+          'Per-script opt-in map keyed by script name. `true` = repo ships this RECOMMENDED script; `false` = explicit opt-out.',
+      }),
+    ),
+    bodyExempt: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          'Script names whose body is allowed to drift from the canonical form (e.g. socket-lib runs a richer test runner than the standard `node scripts/test.mts`). Each entry is the script name only.',
+      }),
+    ),
+  },
+  { description: 'package.json script tracking overrides.' },
+)
+
+// ---------------------------------------------------------------------------
+// Lint block — oxlint profile selection.
+// ---------------------------------------------------------------------------
+
+const LintSchema = Type.Object(
+  {
+    profile: Type.Optional(
+      Type.Union([Type.Literal('standard'), Type.Literal('rich')], {
+        description:
+          '`standard` requires the fleet plugin set (import + typescript + unicorn). `rich` opts into a wider set; check the runner for the exact basenames currently exempted.',
+      }),
+    ),
+  },
+  { description: 'oxlint profile.' },
+)
+
+// ---------------------------------------------------------------------------
+// Workflows block — GitHub Actions opt-ins.
+// ---------------------------------------------------------------------------
+
+const WorkflowsSchema = Type.Object(
+  {
+    ci: Type.Optional(
+      Type.Boolean({ description: 'Ship `.github/workflows/ci.yml`.' }),
+    ),
+    weeklyUpdate: Type.Optional(
+      Type.Boolean({
+        description: 'Ship `.github/workflows/weekly-update.yml`.',
+      }),
+    ),
+    provenance: Type.Optional(
+      Type.Boolean({
+        description:
+          'Repo publishes with npm provenance (OIDC). Hint for setup helpers; not enforced by the checker today.',
+      }),
+    ),
+    requirePinnedFullSha: Type.Optional(
+      Type.Boolean({
+        description:
+          'Enforce 40-char SHA pins on every `uses:` ref. Defaults to true; an opt-out is reserved for special cases (e.g. workflow-dispatch test rigs) and currently has no consumer.',
+      }),
+    ),
+  },
+  { description: 'CI workflow opt-ins.' },
+)
+
+// ---------------------------------------------------------------------------
+// Claude block — opt-in agents/skills/commands.
+// ---------------------------------------------------------------------------
+
+const ClaudeSchema = Type.Object(
+  {
+    includeSecurityScanSkill: Type.Optional(
+      Type.Boolean({
+        description: 'Ship `.claude/skills/scanning-security/SKILL.md`.',
+      }),
+    ),
+    includeSharedSkills: Type.Optional(
+      Type.Boolean({
+        description:
+          'Ship `.claude/skills/_shared/*` — env-check, path-guard-rule, report-format, security-tools, verify-build.',
+      }),
+    ),
+    includeUpdatingSkill: Type.Optional(
+      Type.Boolean({
+        description:
+          'Ship the dependency-update skill. Reserved — no consumer wired today.',
+      }),
+    ),
+  },
+  { description: 'Claude Code opt-ins.' },
+)
+
+// ---------------------------------------------------------------------------
+// Workspace block — pnpm-workspace.yaml derived settings.
+// ---------------------------------------------------------------------------
+
+const WorkspaceSchema = Type.Object(
+  {
+    allowBuilds: Type.Optional(
+      Type.Record(Type.String(), Type.Boolean(), {
+        description:
+          'pnpm `onlyBuiltDependencies` allowlist. Map a package name to true/false to grant/deny build scripts.',
+      }),
+    ),
+    blockExoticSubdeps: Type.Optional(
+      Type.Boolean({
+        description:
+          'Refuse transitive git/tarball subdeps (direct git deps still allowed). Required true; the field exists so a repo can document the intent locally.',
+      }),
+    ),
+    minimumReleaseAge: Type.Optional(
+      Type.Integer({
+        minimum: 0,
+        description:
+          'Soak window in minutes before installing freshly-published packages. Fleet default 10080 (= 7 days).',
+      }),
+    ),
+    minimumReleaseAgeExclude: Type.Optional(
+      Type.Array(Type.String(), {
+        description:
+          'Scopes / package patterns exempt from the soak window. Socket-owned scopes typically listed here.',
+      }),
+    ),
+    resolutionMode: Type.Optional(
+      Type.Union([Type.Literal('highest'), Type.Literal('lowest-direct')], {
+        description: 'pnpm `resolutionMode`. Fleet default `highest`.',
+      }),
+    ),
+    trustPolicy: Type.Optional(
+      Type.Union([Type.Literal('no-downgrade'), Type.Literal('match-spec')], {
+        description: 'pnpm `trustPolicy`. Fleet default `no-downgrade`.',
+      }),
+    ),
+  },
+  {
+    description:
+      'pnpm-workspace.yaml setting hints. The runner reads from the YAML; this block exists for repos that prefer to declare intent in JSON.',
+  },
+)
+
+// ---------------------------------------------------------------------------
+// Top-level config.
+// ---------------------------------------------------------------------------
+
+export const SocketWheelhouseConfigSchema = Type.Object(
+  {
+    $schema: Type.Optional(
+      Type.String({
+        description:
+          'JSON Schema reference for editor autocompletion. Conventionally `./socket-wheelhouse-schema.json` — both the config and its schema live side-by-side in `.config/`.',
+      }),
+    ),
+    schemaVersion: Type.Literal(1, {
+      description:
+        'Schema version. Bump on breaking changes; readers gate on it.',
+    }),
+    repoName: Type.String({
+      pattern: '^[a-z0-9][a-z0-9-]*$',
+      description:
+        'Canonical repo basename (e.g. `socket-lib`, `ultrathink`). Used for layout / native-independent exemptions like the oxlint `socket-lib` carve-out.',
+    }),
+    layout: LayoutSchema,
+    native: NativeSchema,
+    hooks: Type.Optional(HooksSchema),
+    scripts: Type.Optional(ScriptsSchema),
+    lint: Type.Optional(LintSchema),
+    workflows: Type.Optional(WorkflowsSchema),
+    claude: Type.Optional(ClaudeSchema),
+    workspace: Type.Optional(WorkspaceSchema),
+  },
+  {
+    description:
+      "Per-repo socket-wheelhouse config. Two valid locations: `.config/socket-wheelhouse.json` (primary) or `.socket-wheelhouse.json` at the repo root (alternative). Both are first-class — pick the location that fits your repo's convention.",
+  },
+)
+
+export type SocketWheelhouseConfig = Static<typeof SocketWheelhouseConfigSchema>
+export type Layout = Static<typeof LayoutSchema>
+export type Native = Static<typeof NativeSchema>
diff --git a/scripts/update.mts b/scripts/update.mts
new file mode 100644
index 0000000..cde99f9
--- /dev/null
+++ b/scripts/update.mts
@@ -0,0 +1,78 @@
+/**
+ * Update: two-pass taze to apply the fleet's maturity policy
+ * correctly.
+ *
+ *   Pass 1: default config (.config/taze.config.mts) —
+ *     non-Socket deps respect maturityPeriod: 7.
+ *
+ *   Pass 2: CLI-flag override — Socket-owned scopes only,
+ *     maturityPeriod: 0. taze's config auto-discovery is
+ *     path-based and doesn't support a --config override, so
+ *     the second pass uses `--include <scopes> --maturity-
+ *     period 0` flags instead of a second config file.
+ *
+ *   Pass 3: pnpm install to refresh the lockfile against the
+ *     updated package.json.
+ *
+ * SOCKET_SCOPES below MUST match the `exclude` list in
+ * .config/taze.config.mts — drift causes double-bumps or
+ * misses.
+ *
+ * This is a reference script. Consuming repos can drop it into
+ * their own scripts/ dir and wire it in via a `"update": "node
+ * scripts/update.mts"` package.json entry.
+ */
+import { spawn } from '@socketsecurity/lib/spawn'
+
+async function run(cmd: string, args: string[]): Promise<boolean> {
+  try {
+    await spawn(cmd, args, { stdio: 'inherit' })
+    return true
+  } catch (e) {
+    process.exitCode = (e as { code?: number }).code ?? 1
+    return false
+  }
+}
+
+/* Socket-owned scopes — keep in lockstep with the exclude list
+ * in .config/taze.config.mts. */
+const SOCKET_SCOPES = [
+  '@socketregistry/*',
+  '@socketsecurity/*',
+  '@socketdev/*',
+  'socket-*',
+  'ecc-agentshield',
+  'sfw',
+]
+
+const steps: Array<[string, string[]]> = [
+  /* Pass 1 — third-party deps, respects the 7-day cooldown.
+   *
+   * `--maturity-period 7` MUST be passed on the CLI even though
+   * the config file (.config/taze.config.mts) sets the same
+   * value. Taze's CLI default for this flag is 0, and CLI
+   * defaults override config — without this flag, the cooldown
+   * is silently disabled. */
+  ['pnpm', ['exec', 'taze', '--maturity-period', '7', '--write']],
+  /* Pass 2 — Socket deps, no cooldown. --include is comma-separated. */
+  [
+    'pnpm',
+    [
+      'exec',
+      'taze',
+      '--include',
+      SOCKET_SCOPES.join(','),
+      '--maturity-period',
+      '0',
+      '--write',
+    ],
+  ],
+  /* Pass 3 — resync lockfile against the updated package.json. */
+  ['pnpm', ['install']],
+]
+
+for (const [cmd, args] of steps) {
+  if (!(await run(cmd, args))) {
+    break
+  }
+}
diff --git a/scripts/validate-config-paths.mts b/scripts/validate-config-paths.mts
new file mode 100644
index 0000000..cc424fd
--- /dev/null
+++ b/scripts/validate-config-paths.mts
@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Repo gate: every tooling config that *can* live in
+ * `.config/` *does* live there, and there is no stale duplicate at
+ * the repo root.
+ *
+ * Per CLAUDE.md's "Config files in `.config/`" rule, the root keeps
+ * only what *must* be there:
+ *   - package manifests + lockfile (package.json, pnpm-lock.yaml,
+ *     pnpm-workspace.yaml)
+ *   - linter / formatter dotfiles whose tools require root
+ *     placement (.oxlintrc.json, .oxfmtrc.json, .npmrc, .gitignore,
+ *     .gitattributes, .node-version)
+ *   - tsconfig.json (TypeScript's project root anchor — extends
+ *     from .config/tsconfig.base.json)
+ *
+ * Everything else (taze.config.mts, vitest.config*.mts,
+ * tsconfig.base.json, tsconfig.check.json, tsconfig.dts.json,
+ * esbuild.config.mts, lockstep.json, socket-wheelhouse.json, etc.)
+ * lives in `.config/`. A copy at root is drift — usually a
+ * half-finished move that left a stale file behind.
+ *
+ * Exit codes:
+ *   0 — clean
+ *   1 — duplicate(s) found
+ */
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+
+const logger = getDefaultLogger()
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const rootPath = path.resolve(__dirname, '..')
+const configPath = path.join(rootPath, '.config')
+
+// Filename patterns that must live in .config/ when they exist at all,
+// and must NOT have a root duplicate. Listed by basename — the gate
+// checks both root and .config/ for each.
+const CONFIG_BASENAMES: readonly string[] = [
+  'esbuild.config.mts',
+  'isolated-tests.json',
+  'lockstep.json',
+  'lockstep.schema.json',
+  'oxfmtrc.json',
+  'oxlintrc.json',
+  'socket-wheelhouse-schema.json',
+  'socket-wheelhouse.json',
+  'taze.config.mts',
+  'tsconfig.base.json',
+  'tsconfig.check.json',
+  'tsconfig.check.local.json',
+  'tsconfig.dts.json',
+  'vitest.config.isolated.mts',
+  'vitest.config.mts',
+  'vitest.coverage.config.mts',
+]
+
+// Root dotfile aliases for files that ALSO appear without the dot in
+// .config/. e.g. `.oxlintrc.json` is the root-required form (tool
+// looks for it at cwd); `oxlintrc.json` is the .config/ form. Both
+// are legitimate; the gate verifies only one of each pair is present.
+const ROOT_DOT_PAIRS: ReadonlyArray<readonly [string, string]> = [
+  ['.oxlintrc.json', 'oxlintrc.json'],
+  ['.oxfmtrc.json', 'oxfmtrc.json'],
+]
+
+function main(): void {
+  const findings: string[] = []
+
+  // Direct duplicates: same basename at root AND in .config/.
+  for (const basename of CONFIG_BASENAMES) {
+    const rootCopy = path.join(rootPath, basename)
+    const configCopy = path.join(configPath, basename)
+    if (existsSync(rootCopy) && existsSync(configCopy)) {
+      findings.push(
+        `Duplicate config: ${basename} exists at both repo root and .config/. Delete the root copy; .config/ is canonical.`,
+      )
+    } else if (existsSync(rootCopy)) {
+      findings.push(
+        `Stale root config: ${basename} should live in .config/, not at the repo root. Move it.`,
+      )
+    }
+  }
+
+  // Dotfile aliases: only ONE of the pair should exist.
+  for (const [dotName, plainName] of ROOT_DOT_PAIRS) {
+    const dotPath = path.join(rootPath, dotName)
+    const plainPath = path.join(configPath, plainName)
+    if (existsSync(dotPath) && existsSync(plainPath)) {
+      findings.push(
+        `Duplicate config: ${dotName} (root) and .config/${plainName} both exist. Keep the .config/ copy; tools accept -c .config/${plainName} explicitly.`,
+      )
+    }
+  }
+
+  if (findings.length === 0) {
+    logger.success(
+      `Config-path hygiene OK — ${CONFIG_BASENAMES.length} basenames checked, no root duplicates.`,
+    )
+    return
+  }
+
+  logger.error(`Config-path hygiene violations (${findings.length}):`)
+  for (const f of findings) {
+    logger.error(`  ${f}`)
+  }
+  process.exitCode = 1
+}
+
+main()
diff --git a/scripts/validate-esbuild-minify.mts b/scripts/validate-esbuild-minify.mts
new file mode 100644
index 0000000..d0d66d6
--- /dev/null
+++ b/scripts/validate-esbuild-minify.mts
@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Validates that esbuild configuration has minify: false.
+ * Minification breaks ESM/CJS interop and makes debugging harder.
+ */
+
+import path from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+
+const logger = getDefaultLogger()
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const rootPath = path.join(__dirname, '..')
+
+interface MinifyViolation {
+  config: string
+  value: unknown
+  message: string
+  location: string
+}
+
+/**
+ * Validate esbuild configuration has minify: false.
+ */
+async function validateEsbuildMinify(): Promise<MinifyViolation[]> {
+  const configPath = path.join(rootPath, '.config/esbuild.config.mts')
+
+  try {
+    // Dynamic import of the esbuild config
+    const config = await import(configPath)
+
+    const violations: MinifyViolation[] = []
+
+    // Check buildConfig
+    if (config.buildConfig) {
+      if (config.buildConfig.minify !== false) {
+        violations.push({
+          config: 'buildConfig',
+          value: config.buildConfig.minify,
+          message: 'buildConfig.minify must be false',
+          location: `${configPath}:212`,
+        })
+      }
+    }
+
+    // Check watchConfig
+    if (config.watchConfig) {
+      if (config.watchConfig.minify !== false) {
+        violations.push({
+          config: 'watchConfig',
+          value: config.watchConfig.minify,
+          message: 'watchConfig.minify must be false',
+          location: `${configPath}:248`,
+        })
+      }
+    }
+
+    return violations
+  } catch (e) {
+    logger.error(
+      `Failed to load esbuild config: ${e instanceof Error ? e.message : String(e)}`,
+    )
+    process.exitCode = 1
+    return []
+  }
+}
+
+async function main(): Promise<void> {
+  const violations = await validateEsbuildMinify()
+
+  if (violations.length === 0) {
+    logger.success('esbuild minify validation passed')
+    process.exitCode = 0
+    return
+  }
+
+  logger.fail('esbuild minify validation failed\n')
+
+  for (const violation of violations) {
+    logger.error(`  ${violation.message}`)
+    logger.error(`  Found: minify: ${violation.value}`)
+    logger.error('  Expected: minify: false')
+    logger.error(`  Location: ${violation.location}`)
+    logger.error('')
+  }
+
+  logger.error(
+    'Minification breaks ESM/CJS interop and makes debugging harder.',
+  )
+  logger.error('')
+
+  process.exitCode = 1
+}
+
+main().catch((e: unknown) => {
+  logger.error('Validation failed:', e)
+  process.exitCode = 1
+})
diff --git a/scripts/validate-file-size.mts b/scripts/validate-file-size.mts
new file mode 100644
index 0000000..dbae278
--- /dev/null
+++ b/scripts/validate-file-size.mts
@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Validates that no individual files exceed size threshold.
+ *
+ * Rules:
+ * - No single file should exceed 2MB (2,097,152 bytes)
+ * - Helps prevent accidental commits of large binaries, data files, or artifacts
+ * - Excludes: node_modules, .git, dist, build, coverage directories
+ */
+
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+
+const logger = getDefaultLogger()
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const rootPath = path.join(__dirname, '..')
+
+// Maximum file size: 2MB (2,097,152 bytes)
+const MAX_FILE_SIZE = 2 * 1024 * 1024
+
+// Directories to skip
+const SKIP_DIRS = new Set([
+  '.cache',
+  '.git',
+  '.next',
+  '.nuxt',
+  '.output',
+  '.turbo',
+  '.vercel',
+  '.vscode',
+  'build',
+  'coverage',
+  'dist',
+  'external',
+  'node_modules',
+  'tmp',
+])
+
+/**
+ * Format bytes to human-readable size.
+ */
+function formatBytes(bytes: number): string {
+  if (bytes === 0) {
+    return '0 B'
+  }
+  const k = 1024
+  const sizes = ['B', 'KB', 'MB', 'GB', 'TB']
+  const i = Math.min(
+    Math.floor(Math.log(bytes) / Math.log(k)),
+    sizes.length - 1,
+  )
+  return `${(bytes / k ** i).toFixed(2)} ${sizes[i]}`
+}
+
+interface FileSizeViolation {
+  file: string
+  size: number
+  formattedSize: string
+  maxSize: string
+}
+
+/**
+ * Recursively scan directory for files exceeding size limit.
+ */
+async function scanDirectory(
+  dir: string,
+  violations: FileSizeViolation[] = [],
+): Promise<FileSizeViolation[]> {
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name)
+
+      if (entry.isDirectory()) {
+        // Skip excluded directories and hidden directories (except .claude, .config, .github)
+        if (
+          !SKIP_DIRS.has(entry.name) &&
+          (!entry.name.startsWith('.') ||
+            entry.name === '.claude' ||
+            entry.name === '.config' ||
+            entry.name === '.github')
+        ) {
+          await scanDirectory(fullPath, violations)
+        }
+      } else if (entry.isFile()) {
+        try {
+          // oxlint-disable-next-line socket/prefer-exists-sync -- need stats.size for the size threshold check; this IS the file-size validator.
+          const stats = await fs.stat(fullPath)
+          if (stats.size > MAX_FILE_SIZE) {
+            const relativePath = path.relative(rootPath, fullPath)
+            violations.push({
+              file: relativePath,
+              size: stats.size,
+              formattedSize: formatBytes(stats.size),
+              maxSize: formatBytes(MAX_FILE_SIZE),
+            })
+          }
+        } catch {
+          // Skip files we can't stat
+        }
+      }
+    }
+  } catch {
+    // Skip directories we can't read
+  }
+
+  return violations
+}
+
+/**
+ * Validate file sizes in repository.
+ */
+async function validateFileSizes(): Promise<FileSizeViolation[]> {
+  const violations = await scanDirectory(rootPath)
+
+  // Sort by size descending (largest first)
+  violations.sort((a, b) => b.size - a.size)
+
+  return violations
+}
+
+async function main(): Promise<void> {
+  try {
+    const violations = await validateFileSizes()
+
+    if (violations.length === 0) {
+      logger.success('All files are within size limits')
+      process.exitCode = 0
+      return
+    }
+
+    logger.fail('File size violations found')
+    logger.log('')
+    logger.log(`Maximum allowed file size: ${formatBytes(MAX_FILE_SIZE)}`)
+    logger.log('')
+    logger.log('Files exceeding limit:')
+    logger.log('')
+
+    for (const violation of violations) {
+      logger.log(`  ${violation.file}`)
+      logger.log(`    Size: ${violation.formattedSize}`)
+      logger.log(
+        `    Exceeds limit by: ${formatBytes(violation.size - MAX_FILE_SIZE)}`,
+      )
+      logger.log('')
+    }
+
+    logger.log(
+      'Reduce file sizes, move large files to external storage, or exclude from repository.',
+    )
+    logger.log('')
+
+    process.exitCode = 1
+  } catch (e) {
+    logger.fail(
+      `Validation failed: ${e instanceof Error ? e.message : String(e)}`,
+    )
+    process.exitCode = 1
+  }
+}
+
+main().catch((e: unknown) => {
+  logger.fail(`Validation failed: ${e}`)
+  process.exitCode = 1
+})
diff --git a/tsconfig.declaration.json b/tsconfig.declaration.json
index 1bb637d..a754f56 100644
--- a/tsconfig.declaration.json
+++ b/tsconfig.declaration.json
@@ -11,6 +11,11 @@
     "**/*.test.ts",
     "node_modules",
     "coverage",
-    ".github"
+    ".github",
+    ".claude",
+    ".git-hooks",
+    ".husky",
+    "docs",
+    "scripts/**/*.mts"
   ]
 }
diff --git a/tsconfig.json b/tsconfig.json
index 51cb725..221f4c6 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,42 +1,29 @@
 {
   "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./.config/tsconfig.base.json",
   "compilerOptions": {
-    "module": "nodenext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
-    "esModuleInterop": true,
-    "allowSyntheticDefaultImports": true,
-    "lib": ["es2024"],
-    "target": "es2024",
-    "removeComments": true,
-    "stripInternal": true,
+    "allowImportingTsExtensions": true,
     "allowJs": true,
+    "allowSyntheticDefaultImports": true,
     "checkJs": true,
+    "module": "nodenext",
+    "moduleResolution": "NodeNext",
     "noEmit": true,
-    "resolveJsonModule": true,
-    "exactOptionalPropertyTypes": true,
-    "noFallthroughCasesInSwitch": true,
-    "noImplicitOverride": true,
-    "noPropertyAccessFromIndexSignature": true,
-    "noUncheckedIndexedAccess": true,
-    "noUncheckedSideEffectImports": true,
-    "forceConsistentCasingInFileNames": true,
     "noImplicitReturns": false,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "skipLibCheck": true,
-    "erasableSyntaxOnly": true,
-    "allowImportingTsExtensions": true,
+    "removeComments": true,
     "rewriteRelativeImportExtensions": true,
-    "verbatimModuleSyntax": true
+    "stripInternal": true
   },
-  "include": [
-     "**/*"
-   ],
-   "exclude": [
-     "**/*.js",
-     "node_modules",
-     "coverage",
-     ".github"
-   ]
+  "include": ["**/*"],
+  "exclude": [
+    "**/*.js",
+    "node_modules",
+    "coverage",
+    ".github",
+    ".claude",
+    ".git-hooks",
+    ".husky",
+    "docs",
+    "scripts/**/*.mts"
+  ]
 }