chore(sync): cascade predicate lift + docs/claude.md/ reorg from socket-repo-template

Author: jdalton

.config/oxlint-plugin/rules/prefer-undefined-over-null.js

@@ -103,6 +103,97 @@ const rule = {
       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 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)
@@ -277,6 +368,12 @@ const rule = {
         if (isJsonStringifyReplacer(node)) {
           return
         }
+        if (isAssertionLibraryArg(node)) {
+          return
+        }
+        if (isNullableTypeInitializer(node)) {
+          return
+        }
 
         if (hasNullTypeAnnotation(node)) {
           // Surrounding type annotation mentions null — report without

CLAUDE.md

@@ -152,7 +152,7 @@ The principle: the working tree at end-of-turn should match the user's mental mo
 
 ### Hook bypasses require the canonical phrase
 
-🚨 Reverting tracked changes or bypassing a hook (--no-verify, DISABLE*PRECOMMIT*\*, --no-gpg-sign, force-push) requires the user to type **`Allow <X> bypass`** verbatim in a recent user turn (e.g. `Allow revert bypass`, `Allow no-verify bypass`). Paraphrases don't count. Enforced by `.claude/hooks/no-revert-guard/`. Full phrase table: [`docs/references/bypass-phrases.md`](docs/references/bypass-phrases.md).
+🚨 Reverting tracked changes or bypassing a hook (--no-verify, DISABLE*PRECOMMIT*\*, --no-gpg-sign, force-push) requires the user to type **`Allow <X> bypass`** verbatim in a recent user turn (e.g. `Allow revert bypass`, `Allow no-verify bypass`). Paraphrases don't count. Enforced by `.claude/hooks/no-revert-guard/`. Full phrase table: [`docs/claude.md/bypass-phrases.md`](docs/claude.md/bypass-phrases.md).
 
 ### Variant analysis on every High/Critical finding
 
@@ -191,6 +191,10 @@ How to check:
 
 Never silently let drift sit. Either reconcile in the same PR or open a follow-up PR titled `chore(sync): cascade <thing> from <newer-repo>` and link it.
 
+### Never fork fleet-canonical files locally
+
+🚨 Fleet-canonical files (anything tracked by `socket-repo-template/scripts/sync-scaffolding/manifest.mts`) MUST be edited in `socket-repo-template/template/...` and cascaded out — never branched locally in a downstream fleet repo. If you spot a useful predicate / helper / test / behavior in a fleet-canonical file in a downstream repo that's NOT in the template, that's a bug — lift it up first, then re-cascade. Full canonical-surface list + lifting workflow: [`docs/claude.md/no-local-fork-canonical.md`](docs/claude.md/no-local-fork-canonical.md).
+
 ### Code style
 
 - **Comments** — default to none. Write one only when the WHY is non-obvious to a senior engineer. **When you do write a comment, the audience is a junior dev**: explain the constraint, the hidden invariant, the "why this and not the obvious thing." Don't label it ("for junior devs:", "intuition:", etc.) — just write in that voice. No teacher-tone, no condescension, no flattering the reader.
@@ -204,8 +208,8 @@ Never silently let drift sit. Either reconcile in the same PR or open a follow-u
 - **File deletion** — 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. Prefer the async `safeDelete()` over `safeDeleteSync()` when the surrounding code is already async (test bodies, request handlers, build scripts that await elsewhere) — sync I/O blocks the event loop and there's no benefit when the caller is awaiting anyway. Reserve `safeDeleteSync()` for top-level scripts whose entire flow is sync.
 - **Edits** — Edit tool, never `sed` / `awk`.
 - **Generated reports** — quality scans, security audits, perf snapshots, anything an automated tool emits — write to `.claude/reports/` (naturally gitignored as part of `.claude/*`, no separate rule needed). Never commit reports to a tracked `reports/`, `docs/reports/`, or similarly-named tracked directory: dated reports rot the moment they land and the directory becomes a graveyard. The current state of the repo is the report; tools regenerate findings on demand. If a finding is genuinely worth keeping past one run, fix it or open an issue — don't pickle it as a markdown file.
-- **Inclusive language** — see [`docs/references/inclusive-language.md`](docs/references/inclusive-language.md) for the substitution table.
-- **Sorting** — sort alphanumerically (literal byte order, ASCII before letters). Applies to: object property keys (config + return shapes + internal state — `__proto__: null` first); named imports inside a single statement (`import { a, b, c }`); `Set` / `SafeSet` constructor arguments; allowlists / denylists / config arrays / interface members. Position-bearing arrays (where index matters) keep their meaningful order. Full details in [`docs/references/sorting.md`](docs/references/sorting.md). When in doubt, sort.
+- **Inclusive language** — see [`docs/claude.md/inclusive-language.md`](docs/claude.md/inclusive-language.md) for the substitution table.
+- **Sorting** — sort alphanumerically (literal byte order, ASCII before letters). Applies to: object property keys (config + return shapes + internal state — `__proto__: null` first); named imports inside a single statement (`import { a, b, c }`); `Set` / `SafeSet` constructor arguments; allowlists / denylists / config arrays / interface members. Position-bearing arrays (where index matters) keep their meaningful order. Full details in [`docs/claude.md/sorting.md`](docs/claude.md/sorting.md). When in doubt, sort.
 - **`Promise.race` / `Promise.any` in loops** — never re-race a pool that survives across iterations (the handlers stack). See `.claude/skills/plug-leaking-promise-race/SKILL.md`.
 - **`Safe` suffix** — non-throwing wrappers end in `Safe` (`safeDelete`, `safeDeleteSync`, `applySafe`, `weakRefSafe`). Read it as "X, but safe from throwing." The wrapper traps the thrown value internally and returns `undefined` (or the documented fallback). Don't invent alternative suffixes (`Try`, `OrUndefined`, `Maybe`) — pick `Safe`.
 - **`node:smol-*` modules** — feature-detect, then require. From outside socket-btm (socket-lib, socket-cli, anywhere else): `import { isBuiltin } from 'node:module'; if (isBuiltin('node:smol-X')) { const mod = require('node:smol-X') }`. The `node:smol-*` namespace is provided by socket-btm's smol Node binary; on stock Node `isBuiltin` returns false and the require would throw. Wrap the loader in a `/*@__NO_SIDE_EFFECTS__*/` lazy-load that caches the result — see `socket-lib/src/smol/util.ts` and `socket-lib/src/smol/primordial.ts` for canonical shape. **Inside** socket-btm's `additions/source-patched/` JS (the smol binary's own bootstrap code), use `internalBinding('smol_X')` directly — that's the C++-binding access path and it's guaranteed available there.
@@ -275,7 +279,7 @@ An error message is UI. The reader should fix the problem from the message alone
 3. **Saw vs. wanted** — the bad value and the allowed shape or set.
 4. **Fix** — one imperative action (`rename the key to …`).
 
-Use `isError` / `isErrnoException` / `errorMessage` / `errorStack` from `@socketsecurity/lib/errors` over hand-rolled checks. Use `joinAnd` / `joinOr` from `@socketsecurity/lib/arrays` for allowed-set lists. Full guidance in [`docs/references/error-messages.md`](docs/references/error-messages.md).
+Use `isError` / `isErrnoException` / `errorMessage` / `errorStack` from `@socketsecurity/lib/errors` over hand-rolled checks. Use `joinAnd` / `joinOr` from `@socketsecurity/lib/arrays` for allowed-set lists. Full guidance in [`docs/claude.md/error-messages.md`](docs/claude.md/error-messages.md).
 
 ### Token hygiene
 
@@ -296,7 +300,7 @@ Full hook spec in [`.claude/hooks/token-guard/README.md`](.claude/hooks/token-gu
 - `/scanning-security` — AgentShield + zizmor audit
 - `/scanning-quality` — quality analysis
 - Shared subskills in `.claude/skills/_shared/`
-- **Handing off to another agent** — see [`docs/references/agent-delegation.md`](docs/references/agent-delegation.md) for when to reach for `codex:codex-rescue`, the `delegate` subagent (OpenCode → Fireworks/Synthetic/Kimi), `Explore`, `Plan`, vs. driving the skill CLIs directly. The CLI-subprocess contract used by skills lives in [`_shared/multi-agent-backends.md`](.claude/skills/_shared/multi-agent-backends.md).
+- **Handing off to another agent** — see [`docs/claude.md/agent-delegation.md`](docs/claude.md/agent-delegation.md) for when to reach for `codex:codex-rescue`, the `delegate` subagent (OpenCode → Fireworks/Synthetic/Kimi), `Explore`, `Plan`, vs. driving the skill CLIs directly. The CLI-subprocess contract used by skills lives in [`_shared/multi-agent-backends.md`](.claude/skills/_shared/multi-agent-backends.md).
 
 #### Skill scope: fleet vs partial vs unique