chore(wheelhouse): cascade template@28b9c737

Auto-applied by socket-wheelhouse sync-scaffolding into cascade-socket-addon-57801.
9 file(s) touched:
  - .claude/hooks/fleet/claude-segmentation-guard/README.md
  - .claude/hooks/fleet/claude-segmentation-guard/index.mts
  - .claude/hooks/fleet/claude-segmentation-guard/package.json
  - .claude/hooks/fleet/claude-segmentation-guard/test/index.test.mts
  - .claude/hooks/fleet/claude-segmentation-guard/tsconfig.json
  - .claude/hooks/fleet/setup-security-tools/external-tools.json
  - .claude/settings.json
  - .config/socket-registry-pins.json
  - scripts/check-claude-segmentation.mts

Author: jdalton

.claude/hooks/fleet/claude-segmentation-guard/README.md

@@ -0,0 +1,48 @@
+# claude-segmentation-guard
+
+PreToolUse Edit/Write hook that blocks new files/directories at dangling top-level paths under `.claude/{agents,commands,hooks,skills}/`.
+
+## Why
+
+Every entry under those four directories must live under one of:
+
+- `<kind>/fleet/<name>/` — wheelhouse-canonical entries (the wheelhouse template ships an entry with this name).
+- `<kind>/repo/<name>/` — repo-only entries (everything else).
+- `<kind>/_<name>/` — internals folder (`_shared` and friends).
+
+Top-level dangling entries like `.claude/skills/foo/SKILL.md` shadow the canonical `.claude/skills/fleet/foo/SKILL.md` copy and break skill resolution in unpredictable ways.
+
+Past incident: 2026-06-01 fleet-wide audit found ~200 dangling entries across 10 repos — every fleet repo had at least 18 duplicate top-level skill directories shadowing their `fleet/<name>/` counterparts. The cleanup script (`node scripts/check-claude-segmentation.mts --fix`) resolved them in bulk; this hook prevents the regression at edit time.
+
+## What it blocks
+
+Edit/Write on any path matching `.claude/<kind>/<name>/...` where `<kind>` is `agents | commands | hooks | skills` and `<name>` is NOT one of `fleet | repo | _*`.
+
+| Path                                                    | Result |
+| ------------------------------------------------------- | ------ |
+| `.claude/skills/foo/SKILL.md`                           | block  |
+| `.claude/agents/foo.md`                                 | block  |
+| `.claude/hooks/foo/index.mts`                           | block  |
+| `.claude/skills/fleet/foo/SKILL.md`                     | pass   |
+| `.claude/skills/repo/foo/SKILL.md`                      | pass   |
+| `.claude/skills/_shared/util.mts`                       | pass   |
+| `.claude/skills/_internal/x.mts`                        | pass   |
+| `template/.claude/skills/foo/SKILL.md` (wheelhouse)     | block  |
+
+## How
+
+The hook reads the Claude Code PreToolUse JSON payload from stdin, runs the regex `\.claude/(?<kind>agents|commands|hooks|skills)/(?<entry>[^/]+)` on `tool_input.file_path`, and exits 2 if the captured `entry` segment is not `fleet`, `repo`, or `_`-prefixed.
+
+The stderr message names the offending path and the two allowed destinations (`fleet/<name>/` or `repo/<name>/`), plus the autofix command for cleaning up entries already on disk.
+
+Fails open on malformed payloads or unknown errors (exit 0).
+
+## Bypass
+
+None. The autofix is always available: `node scripts/check-claude-segmentation.mts --fix` moves dangling entries into the right subdir based on the wheelhouse-canonical fleet/ set.
+
+## Test
+
+```sh
+pnpm test
+```

.claude/hooks/fleet/claude-segmentation-guard/index.mts

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// Claude Code PreToolUse hook — claude-segmentation-guard.
+//
+// Blocks Edit/Write tool calls that create or modify entries directly
+// under `.claude/{agents,commands,hooks,skills}/<name>/` (instead of
+// `fleet/<name>/` or `repo/<name>/`). Pre-segmentation top-level
+// dangling entries shadow the canonical `fleet/<name>/` copy and break
+// skill resolution.
+//
+// Past incident: 2026-06-01 fleet-wide audit found ~200 dangling
+// entries across 10 repos — every fleet repo had at least 18
+// duplicate top-level skill directories shadowing their `fleet/<name>/`
+// counterparts. The cleanup script
+// (`scripts/check-claude-segmentation.mts --fix`) resolved them in
+// bulk; this hook prevents the regression at edit time.
+//
+// Allowed paths:
+//   .claude/agents/fleet/<name>/...
+//   .claude/agents/repo/<name>/...
+//   .claude/agents/_*/...                  (internals folder exception)
+//   .claude/commands/fleet/<name>.md
+//   .claude/commands/repo/<name>.md
+//   .claude/hooks/_shared/...              (and any _-prefixed name)
+//   .claude/hooks/fleet/<name>/...
+//   .claude/hooks/repo/<name>/...
+//   .claude/skills/_shared/...
+//   .claude/skills/fleet/<name>/...
+//   .claude/skills/repo/<name>/...
+//
+// Blocked:
+//   .claude/agents/<name>.md               (not under fleet/ or repo/)
+//   .claude/commands/<name>.md             (same)
+//   .claude/hooks/<name>/...               (same)
+//   .claude/skills/<name>/...              (same)
+//
+// Wheelhouse-template paths under `template/.claude/<kind>/` follow
+// the same rule — the template ships canonical entries, and the
+// cascade keeps the layout consistent fleet-wide.
+//
+// Reads a Claude Code PreToolUse JSON payload from stdin:
+//   { "tool_name": "Edit" | "Write",
+//     "tool_input": { "file_path": "..." },
+//     ... }
+//
+// Exit codes:
+//   0 — pass (not Edit/Write, or path is in an allowed location).
+//   2 — block (path is a dangling top-level entry).
+//
+// Fails open on malformed payloads (exit 0 + stderr log).
+
+import process from 'node:process'
+
+import { getDefaultLogger } from '@socketsecurity/lib-stable/logger/default'
+
+const logger = getDefaultLogger()
+
+interface ToolInput {
+  readonly tool_input?:
+    | { readonly file_path?: string | undefined }
+    | undefined
+  readonly tool_name?: string | undefined
+}
+
+const KINDS: readonly string[] = ['agents', 'commands', 'hooks', 'skills']
+
+// Match `.claude/<kind>/<entry>` at the root of the captured path. The
+// regex is rooted on `.claude/` and consumes the kind segment; the
+// post-kind segment is what we validate.
+//
+// Examples:
+//   path=/.../template/.claude/skills/foo/SKILL.md  → kind=skills entry=foo
+//   path=/.../.claude/skills/fleet/foo/SKILL.md      → kind=skills entry=fleet (OK)
+//   path=/.../.claude/skills/repo/bar/SKILL.md       → kind=skills entry=repo (OK)
+//   path=/.../.claude/skills/_shared/util.mts        → kind=skills entry=_shared (OK)
+//   path=/.../.claude/agents/foo.md                  → kind=agents entry=foo.md (block)
+const SEGMENT_RE = new RegExp(
+  String.raw`\.claude/(?<kind>${KINDS.join('|')})/(?<entry>[^/]+)`,
+)
+
+interface SegmentMatch {
+  kind: string
+  entry: string
+}
+
+export function findDanglingSegment(filePath: string): SegmentMatch | undefined {
+  const m = SEGMENT_RE.exec(filePath)
+  if (!m?.groups) {
+    return undefined
+  }
+  const kind = m.groups['kind']!
+  const entry = m.groups['entry']!
+  // `_`-prefixed internals folder, `fleet/`, and `repo/` are the
+  // allowed second-level segments. Anything else is a dangling
+  // top-level entry that should be moved.
+  if (entry.startsWith('_') || entry === 'fleet' || entry === 'repo') {
+    return undefined
+  }
+  return { kind, entry }
+}
+
+let payloadRaw = ''
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', chunk => {
+  payloadRaw += chunk
+})
+process.stdin.on('end', () => {
+  // Fail OPEN on any internal bug. The JSON.parse below has its own
+  // try/catch (bad payloads exit 0), but unexpected throws elsewhere
+  // would otherwise crash the hook → exit 1 → block. Hooks must not
+  // brick the session on their own crash.
+  try {
+    let payload: ToolInput
+    try {
+      payload = JSON.parse(payloadRaw) as ToolInput
+    } catch {
+      process.exit(0)
+    }
+
+    if (payload.tool_name !== 'Edit' && payload.tool_name !== 'Write') {
+      process.exit(0)
+    }
+    const filePath = payload.tool_input?.file_path ?? ''
+    if (!filePath) {
+      process.exit(0)
+    }
+
+    const hit = findDanglingSegment(filePath)
+    if (!hit) {
+      process.exit(0)
+    }
+
+    const targetForCanonical = `.claude/${hit.kind}/fleet/${hit.entry}`
+    const targetForRepo = `.claude/${hit.kind}/repo/${hit.entry}`
+
+    logger.error(
+      [
+        '[claude-segmentation-guard] Blocked: dangling top-level entry.',
+        '',
+        `  Attempted path: \`.claude/${hit.kind}/${hit.entry}\``,
+        '',
+        '  `.claude/{agents,commands,hooks,skills}/<name>/` must segment as',
+        '  `fleet/<name>/` (wheelhouse-canonical) or `repo/<name>/` (everything',
+        '  else). Top-level entries shadow the canonical `fleet/<name>/`',
+        '  copy and break skill resolution.',
+        '',
+        `  Fix: pick the right subdir for \`${hit.entry}\`:`,
+        '',
+        `    Wheelhouse-canonical (look in socket-wheelhouse/template/.claude/${hit.kind}/fleet/ for the set):`,
+        `      ${targetForCanonical}`,
+        '',
+        '    Repo-only:',
+        `      ${targetForRepo}`,
+        '',
+        '  Or run `node scripts/check-claude-segmentation.mts --fix` from the',
+        '  repo root to auto-resolve any dangling entries already on disk.',
+        '',
+      ].join('\n'),
+    )
+    process.exit(2)
+  } catch (e) {
+    logger.error(
+      `[claude-segmentation-guard] hook error (allowing): ${e}`,
+    )
+    process.exit(0)
+  }
+})

.claude/hooks/fleet/claude-segmentation-guard/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "hook-claude-segmentation-guard",
+  "private": true,
+  "type": "module",
+  "main": "./index.mts",
+  "exports": {
+    ".": "./index.mts"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mts"
+  },
+  "devDependencies": {
+    "@socketsecurity/lib-stable": "catalog:",
+    "@types/node": "catalog:"
+  }
+}

.claude/hooks/fleet/claude-segmentation-guard/test/index.test.mts

@@ -0,0 +1,161 @@
+// node --test specs for the claude-segmentation-guard hook.
+
+// prefer-async-spawn: streaming-stdio-required — test spawns child
+// subprocess and pipes stdin/stdout/stderr; Node spawn returns the
+// ChildProcess streaming surface the lib promise wrapper does not.
+import { spawn } from '@socketsecurity/lib-stable/process/spawn/child'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const HOOK = path.join(here, '..', 'index.mts')
+
+interface Result {
+  readonly code: number
+  readonly stderr: string
+}
+
+async function runHook(payload: Record<string, unknown>): Promise<Result> {
+  const child = spawn(process.execPath, [HOOK], { stdio: 'pipe' })
+  void child.catch(() => undefined)
+  child.stdin!.end(JSON.stringify(payload))
+  let stderr = ''
+  child.process.stderr!.on('data', chunk => {
+    stderr += chunk.toString('utf8')
+  })
+  return new Promise(resolve => {
+    child.process.on('exit', code => {
+      resolve({ code: code ?? 0, stderr })
+    })
+  })
+}
+
+function edit(filePath: string): Record<string, unknown> {
+  return { tool_input: { file_path: filePath }, tool_name: 'Edit' }
+}
+
+function write(filePath: string): Record<string, unknown> {
+  return { tool_input: { file_path: filePath }, tool_name: 'Write' }
+}
+
+test('non-Edit/Write tool calls pass through', async () => {
+  const r = await runHook({
+    tool_input: { command: 'ls' },
+    tool_name: 'Bash',
+  })
+  assert.strictEqual(r.code, 0)
+  assert.strictEqual(r.stderr, '')
+})
+
+test('empty / unparseable payload passes through', async () => {
+  assert.strictEqual((await runHook({})).code, 0)
+})
+
+test('paths outside .claude/ pass through', async () => {
+  for (const p of [
+    'src/index.ts',
+    'docs/claude.md/fleet/topic.md',
+    'README.md',
+    'package.json',
+  ]) {
+    assert.strictEqual((await runHook(edit(p))).code, 0, `expected pass for ${p}`)
+  }
+})
+
+test('blocks dangling skill at .claude/skills/<name>/SKILL.md', async () => {
+  const r = await runHook(edit('.claude/skills/foo/SKILL.md'))
+  assert.strictEqual(r.code, 2)
+  assert.match(r.stderr, /claude-segmentation-guard/)
+  assert.match(r.stderr, /skills\/foo/)
+  assert.match(r.stderr, /fleet\/foo/)
+  assert.match(r.stderr, /repo\/foo/)
+  assert.match(r.stderr, /--fix/)
+})
+
+test('blocks dangling agent at .claude/agents/<name>.md', async () => {
+  const r = await runHook(edit('.claude/agents/code-reviewer.md'))
+  assert.strictEqual(r.code, 2)
+  assert.match(r.stderr, /agents\/code-reviewer/)
+})
+
+test('blocks dangling hook at .claude/hooks/<name>/index.mts', async () => {
+  const r = await runHook(write('.claude/hooks/my-guard/index.mts'))
+  assert.strictEqual(r.code, 2)
+  assert.match(r.stderr, /hooks\/my-guard/)
+})
+
+test('blocks dangling command at .claude/commands/<name>.md', async () => {
+  const r = await runHook(write('.claude/commands/foo.md'))
+  assert.strictEqual(r.code, 2)
+  assert.match(r.stderr, /commands\/foo/)
+})
+
+test('passes .claude/<kind>/fleet/<name>/ paths', async () => {
+  for (const p of [
+    '.claude/skills/fleet/foo/SKILL.md',
+    '.claude/agents/fleet/security-reviewer.md',
+    '.claude/commands/fleet/quality-loop.md',
+    '.claude/hooks/fleet/my-guard/index.mts',
+  ]) {
+    const r = await runHook(edit(p))
+    assert.strictEqual(r.code, 0, `expected pass for ${p}, got stderr: ${r.stderr}`)
+  }
+})
+
+test('passes .claude/<kind>/repo/<name>/ paths', async () => {
+  for (const p of [
+    '.claude/skills/repo/foo/SKILL.md',
+    '.claude/agents/repo/code-reviewer.md',
+    '.claude/commands/repo/update-something.md',
+    '.claude/hooks/repo/local-only/index.mts',
+  ]) {
+    const r = await runHook(edit(p))
+    assert.strictEqual(r.code, 0, `expected pass for ${p}, got stderr: ${r.stderr}`)
+  }
+})
+
+test('passes _-prefixed internals folder paths', async () => {
+  for (const p of [
+    '.claude/skills/_shared/util.mts',
+    '.claude/skills/_internal/x.mts',
+    '.claude/hooks/_shared/foreign-paths.mts',
+    '.claude/hooks/_shared/test/foo.test.mts',
+  ]) {
+    const r = await runHook(edit(p))
+    assert.strictEqual(r.code, 0, `expected pass for ${p}, got stderr: ${r.stderr}`)
+  }
+})
+
+test('blocks under wheelhouse template/.claude/<kind>/<name>/ too', async () => {
+  // The cascade ships everything under template/.claude/<kind>/fleet/
+  // so a dangling template entry breaks every downstream repo. Same
+  // rule applies there.
+  const r = await runHook(edit('template/.claude/skills/foo/SKILL.md'))
+  assert.strictEqual(r.code, 2)
+  assert.match(r.stderr, /skills\/foo/)
+})
+
+test('passes paths that mention .claude/ but not as a directory prefix', async () => {
+  // The regex anchors on `.claude/<kind>/`, so a string-literal mention
+  // inside an unrelated file doesn't match.
+  const r = await runHook(edit('docs/notes.md'))
+  assert.strictEqual(r.code, 0)
+})
+
+test('passes when tool_input has no file_path', async () => {
+  const r = await runHook({ tool_input: {}, tool_name: 'Edit' })
+  assert.strictEqual(r.code, 0)
+})
+
+test('passes for absolute paths under fleet/', async () => {
+  const r = await runHook(edit('/tmp/fake-repo/.claude/skills/fleet/bar/SKILL.md'))
+  assert.strictEqual(r.code, 0)
+})
+
+test('blocks absolute paths to a dangling top-level entry', async () => {
+  const r = await runHook(edit('/tmp/fake-repo/.claude/skills/bar/SKILL.md'))
+  assert.strictEqual(r.code, 2)
+  assert.match(r.stderr, /skills\/bar/)
+})