chore(hooks+claude+oxfmt+kind-config): hooks-mts + sweeper + CLAUDE.md restructure + oxfmt JSDoc + logger-guard + auth-rotation-reminder + kind config

[John-David Dalton (jdalton)]

Self-landable split from #1279. Combines the hook overhaul into one atomic PR.

Path-guard infra

• .claude/hooks/path-guard/ — hook + tests + canonical segments.mts
• .claude/skills/path-guard/ — audit-and-fix skill
• .claude/skills/_shared/path-guard-rule.md — canonical mantra rule
• scripts/check-paths.mts — the whole-repo gate
• .github/paths-allowlist.yml — empty starter, full schema docs
• .claude/settings.json — wires hook on Edit|Write
• scripts/check.mts — invokes the gate

Token-guard hook

• .claude/hooks/token-guard/ — renamed from token-hygiene. Word-boundary match for sensitive env names. ALWAYS_DANGEROUS check skips when a redaction pipeline is present.

Stale-process-sweeper hook

• .claude/hooks/stale-process-sweeper/ — Stop hook that reaps orphan vitest/tsgo/type-coverage/esbuild workers at turn-end. Only kills processes whose parent has died.
• Wired into .claude/settings.json under Stop hook block.

Logger-guard hook (new)

• .claude/hooks/logger-guard/ — PreToolUse(Edit|Write) hook that blocks direct stream writes (process.std{err,out}.write, console.*) in source files; suggests getDefaultLogger() rewrite per hit.
• Path-exempts hooks/, .git-hooks/, scripts/, tests, fixtures, external/ vendor/ upstream/.
• Honors # socket-hook: allow [logger] opt-out marker.

Auth-rotation-reminder hook (new)

• .claude/hooks/auth-rotation-reminder/ — Stop hook that periodically auto-logs out of authenticated CLIs (npm/pnpm/yarn/gcloud/aws-sso/vault/docker/socket); gh stays logged-in by default (Claude Code uses it).
• 1h throttle via ~/.claude/hooks/auth-rotation/last-run mtime; ISO-8601 .claude/auth-rotation.snooze with auto-cleanup via safeDelete.
• Skip when CI or SOCKET_AUTH_ROTATION_DISABLED set.

Pre-commit/pre-push scanLoggerLeaks

• .git-hooks/_helpers.mts adds scanLoggerLeaks for the same rule, so edits made outside Claude Code are caught at commit/push time.
• Canonical # socket-hook: allow <rule> marker (legacy # zizmor: still recognized for one cycle).

CLAUDE.md restructure

• Split CLAUDE.md into ## 📚 Fleet Standards (byte-identical across the fleet, wrapped in <!-- BEGIN/END FLEET-CANONICAL -->) and ## 🏗️ CLI-Specific.
• Fleet block trimmed to ~8.6 KB. Verbose content moves to load-on-demand references.
• New: docs/references/inclusive-language.md, docs/references/sorting.md, .claude/skills/promise-race-pitfall/SKILL.md.
• CLAUDE.md size: 13.5 KB → 9.7 KB.

.sh → .mts hook conversion (Node 25+)

• .git-hooks/_helpers.mts (was _helpers.sh) — exports filterAllowedApiKeys + scanners
• .git-hooks/{commit-msg,pre-commit,pre-push}.mts (were .sh)
• .husky/* shims invoke node directly

Fleet hooks

• .claude/hooks/check-new-deps — npm dep introspection
• .claude/hooks/private-name-guard
• .claude/hooks/release-workflow-guard
• .claude/hooks/setup-security-tools (updated to canonical)
• .claude/hooks/public-surface-reminder/package.json (updated)

oxfmt JSDoc formatting

oxfmt 0.37+ formats JSDoc comments. Adopt canonical jsdoc block from socket-repo-template. Verified zero new format violations on this repo's source.

Cleanup

• Remove orphan .claude/hooks/token-hygiene (renamed to token-guard)

Test plan

• CI passes
• stale-process-sweeper hook tests pass
• logger-guard hook tests pass (12/12)
• auth-rotation-reminder hook tests pass (6/6)
• CLAUDE.md fleet block byte-matches socket-repo-template

blockExoticSubdeps + .mjs->.mts ref sync (added 2026-05-01)

• pnpm-workspace.yaml: blockExoticSubdeps: true (fleet default — refuses transitive git/tarball subdeps; direct git deps still allowed).
• Sync .mjs -> .mts references for scripts/sync-scaffolding across hook READMEs, path-guard segments, _shared skill rules, CLAUDE.md, xport-schema header.
• Adopt "soak window" terminology in security-reviewer + CLAUDE.md tooling block.

socket-repo-template kind config + schema (added 2026-05-03)

• .socket-repo-template.json declaring kind: "consumer" (socket-cli ships multiple npm packages and produces SEAs by consuming socket-btm's prebuilt binaries — it doesn't emit GH releases of its own).
• scripts/socket-repo-template-{schema,emit-schema}.mts + socket-repo-template-schema.json synced byte-identical from socket-repo-template@5ad601c. The TypeBox source defines the per-repo config shape; the emitter regenerates the JSON Schema for IDE autocompletion.
• Read by socket-repo-template's sync-scaffolding kind-aware checker to enforce the consumer contract (must ship release-checksums/core.mts + consumer.mts; must not ship producer.mts).

[John-David Dalton (jdalton)]

bugbot run

[John-David Dalton (jdalton)]

bugbot run

[John-David Dalton (jdalton)]

bugbot run

[John-David Dalton (jdalton)]

bugbot run

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Whole-command redaction check bypasses conditional-operator truncation
  • Moved the REDACTION_WHOLE_COMMAND_MARKERS check to run after the ||/&& truncation so whole-command markers are tested against the truncated string, preventing redirection markers in never-executed conditional branches from bypassing the env-dump block.

Or push these changes by commenting:

@cursor push c4d7dca9ab

Preview (c4d7dca9ab)

diff --git a/.claude/hooks/token-guard/index.mts b/.claude/hooks/token-guard/index.mts
--- a/.claude/hooks/token-guard/index.mts
+++ b/.claude/hooks/token-guard/index.mts
@@ -53,12 +53,12 @@
   /\bcut\b.*-d['"]?=['"]?\s*-f\s*1/i,
   /\bawk\b.*-F\s*['"]?=['"]?/i,
 ]
-// Whole-command redirection markers. Anchored at a pipe-segment
-// boundary (`^`, whitespace, `|`, or `;`) so they fire only on real
-// shell redirection (`env > file`, `env >> file`, `env > /dev/null`)
-// and not on the literal `>` inside regex/HTML-style markers like
-// `<redacted>` or `s/=.*/.../`. The previous /\s*[^|]/ shape would
-// match the `>` in `<redacted>` and bypass the env-dump check.
+// Whole-command redirection markers, checked against the truncated
+// command (after stripping `||`/`&&` suffixes). Anchored at a
+// pipe-segment boundary (`^`, whitespace, `|`, or `;`) so they fire
+// only on real shell redirection (`env > file`, `env >> file`,
+// `env > /dev/null`) and not on the literal `>` inside regex/HTML-
+// style markers like `<redacted>` or `s/=.*/.../`.
 const REDACTION_WHOLE_COMMAND_MARKERS = [
   /(?:^|[\s|;])>\s*\/dev\/null\b/,
   /(?:^|[\s|;])>>?\s*[^|<>'"\\$&\s]/,
@@ -137,9 +137,6 @@
 // where a `redact`-named downstream tool would otherwise launder the
 // upstream `env` dump.
 const hasRedaction = (command: string): boolean => {
-  if (REDACTION_WHOLE_COMMAND_MARKERS.some(re => re.test(command))) {
-    return true
-  }
   // Drop everything from the first `||` or `&&` onwards. Those branches
   // don't unconditionally execute, so a redaction marker on their
   // right side cannot launder an upstream leak. The bypass shape is
@@ -147,13 +144,19 @@
   // `sed` arm never runs at runtime, but the previous logic credited
   // it as a redaction and let the env dump through. Truncating before
   // the conditional operator forces the redaction to live in the same
-  // unconditional pipeline as the leaky stage.
+  // unconditional pipeline as the leaky stage. Both whole-command and
+  // segment markers must check the truncated string — otherwise
+  // `env || true > /dev/null` would match a whole-command marker and
+  // return true early despite the redirection never executing.
   const idxOr = command.indexOf('||')
   const idxAnd = command.indexOf('&&')
   let cut = command.length
   if (idxOr !== -1) cut = Math.min(cut, idxOr)
   if (idxAnd !== -1) cut = Math.min(cut, idxAnd)
   const truncated = command.slice(0, cut)
+  if (REDACTION_WHOLE_COMMAND_MARKERS.some(re => re.test(truncated))) {
+    return true
+  }
   // Split first on `|` (pipe-stage boundary), then on `;` (statement
   // boundary) within each stage. A redaction marker is only credited
   // when both `sed` and the redaction target live in the same

_{You can send follow-ups to the cloud agent here.}

[John-David Dalton (jdalton)]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit aa927eb. Configure here.}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​socketsecurity/​lib@​5.24.0 ⏵ 5.26.1

View full report

[socket-security-staging]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​socketsecurity/​lib@​5.24.0 ⏵ 5.26.1	+13

View full report

[John-David Dalton (jdalton)]

Superseded by three focused splits:

• chore(hooks): sync .claude/hooks fleet — mts conversion + new guards #1300 — hooks + harness-config (.claude/hooks/, .git-hooks/,
  .husky/, .claude/settings.json, .oxfmtrc.json)
• docs(claude+skills): CLAUDE.md restructure + path-guard + new skills #1301 — skills + CLAUDE.md (CLAUDE.md, docs/references/,
  .claude/skills/*, .socket-repo-template.json,
  scripts/socket-repo-template-*)
• chore(ci+deps): cascade socket-registry to 51f34ffb + drift updates #1302 — cascade SHA bump + deps drift (workflow pins,
  package.json/pnpm-lock.yaml/pnpm-workspace.yaml,
  packages/cli/* drift, scripts/check.mts,
  scripts/power-state.mts)

Every file in this PR is content-identical to one of the three splits
(verified by sha-comparing each path's contents). Closing this in
favor of the focused review surface.