chore(wheelhouse): cascade template@27b2c578

Auto-applied by socket-wheelhouse sync-scaffolding into socket-lib.
109 file(s) touched:
  - .claude/hooks/fleet/claude-segmentation-guard/README.md
  - .claude/hooks/fleet/claude-segmentation-guard/index.mts
  - .claude/hooks/fleet/excuse-detector/index.mts
  - .claude/hooks/fleet/excuse-detector/test/index.test.mts
  - .claude/hooks/fleet/lock-step-ref-guard/index.mts
  - .claude/hooks/fleet/no-fleet-fork-guard/index.mts
  - .claude/hooks/fleet/no-fleet-fork-guard/test/index.test.mts
  - .claude/hooks/fleet/no-test-in-scripts-guard/README.md
  - .claude/hooks/fleet/no-test-in-scripts-guard/index.mts
  - .claude/hooks/fleet/no-test-in-scripts-guard/package.json
  - .claude/hooks/fleet/no-test-in-scripts-guard/test/index.test.mts
  - .claude/hooks/fleet/no-test-in-scripts-guard/tsconfig.json
  - .claude/hooks/fleet/oxlint-plugin-load-guard/README.md
  - .claude/hooks/fleet/oxlint-plugin-load-guard/index.mts
  - .claude/hooks/fleet/oxlint-plugin-load-guard/test/index.test.mts
  - .claude/hooks/fleet/path-guard/README.md
  - .claude/hooks/fleet/path-guard/segments.mts
  - .claude/hooks/fleet/path-guard/test/path-guard.test.mts
  - .claude/hooks/fleet/prose-antipattern-guard/test/index.test.mts
  - .claude/hooks/fleet/provenance-publish-reminder/index.mts
  ... and 89 more

Author: jdalton

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

@@ -12,7 +12,7 @@ Every entry under those four directories must live under one of:
 
 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/fleet/check-claude-segmentation.mts --fix`) resolved them in bulk; this hook prevents the regression at edit time.
+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/fleet/check/claude-segmentation.mts --fix`) resolved them in bulk; this hook prevents the regression at edit time.
 
 ## What it blocks
 
@@ -39,7 +39,7 @@ Fails open on malformed payloads or unknown errors (exit 0).
 
 ## Bypass
 
-None. The autofix is always available: `node scripts/fleet/check-claude-segmentation.mts --fix` moves dangling entries into the right subdir based on the wheelhouse-canonical fleet/ set.
+None. The autofix is always available: `node scripts/fleet/check/claude-segmentation.mts --fix` moves dangling entries into the right subdir based on the wheelhouse-canonical fleet/ set.
 
 ## Test
 

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

@@ -11,7 +11,7 @@
 // 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/fleet/check-claude-segmentation.mts --fix`) resolved them in
+// (`scripts/fleet/check/claude-segmentation.mts --fix`) resolved them in
 // bulk; this hook prevents the regression at edit time.
 //
 // Allowed paths:
@@ -151,7 +151,7 @@ process.stdin.on('end', () => {
         '    Repo-only:',
         `      ${targetForRepo}`,
         '',
-        '  Or run `node scripts/fleet/check-claude-segmentation.mts --fix` from the',
+        '  Or run `node scripts/fleet/check/claude-segmentation.mts --fix` from the',
         '  repo root to auto-resolve any dangling entries already on disk.',
         '',
       ].join('\n'),

.claude/hooks/fleet/excuse-detector/index.mts

@@ -160,8 +160,7 @@ await runStopReminder({
         hits.push({
           label: 'relaying an unverified subagent claim (count)',
           why: 'CLAUDE.md "Verify subagent claims before relaying or acting": a subagent\'s counts / lists / behavior assertions are leads, not facts. grep/read the cited files and report only what you confirmed (plus an explicit disproved / unverified section). See docs/claude.md/fleet/agent-delegation.md.',
-          snippet:
-            sentence.length > 80 ? sentence.slice(0, 77) + '…' : sentence,
+          snippet: sentence.length > 80 ? sentence.slice(0, 77) + '…' : sentence,
         })
       }
     }

.claude/hooks/fleet/excuse-detector/test/index.test.mts

@@ -462,8 +462,7 @@ test('fires on relaying an unverified subagent claim (count)', async () => {
   const result = await runHook([
     {
       type: 'assistant',
-      content:
-        'The audit found 52 guards that only advise instead of blocking.',
+      content: 'The audit found 52 guards that only advise instead of blocking.',
     },
   ])
   assert.match(result.stdout, /unverified subagent claim/)

.claude/hooks/fleet/lock-step-ref-guard/index.mts

@@ -362,7 +362,7 @@ async function main(): Promise<void> {
   }
   out.push('  Spec: docs/claude.md/fleet/parser-comments.md §5–6.')
   out.push(
-    '  CI gate: scripts/fleet/check-lock-step-refs.mts (run via `pnpm check`).',
+    '  CI gate: scripts/fleet/check/lock-step-refs.mts (run via `pnpm check`).',
   )
   out.push('  Bypass: "Allow lock-step bypass" in a recent user message, or')
   out.push(`  ${ENV_DISABLE}=1.`)

.claude/hooks/fleet/no-fleet-fork-guard/index.mts

@@ -54,11 +54,26 @@ import { isDirSync } from '@socketsecurity/lib-stable/fs/inspect'
 import { bypassPhrasePresent, readStdin } from '../_shared/transcript.mts'
 
 type ToolInput = {
-  tool_input?: { file_path?: string | undefined } | undefined
+  tool_input?:
+    | {
+        file_path?: string | undefined
+        content?: string | undefined
+        new_string?: string | undefined
+      }
+    | undefined
   tool_name?: string | undefined
   transcript_path?: string | undefined
 }
 
+// True when a string carries both fleet-block markers.
+function textHasFleetBlockMarkers(text: string | undefined): boolean {
+  return (
+    text !== undefined &&
+    text.includes('BEGIN fleet-canonical (managed by socket-wheelhouse') &&
+    text.includes('END fleet-canonical')
+  )
+}
+
 const BYPASS_PHRASE = 'Allow fleet-fork bypass'
 
 // How many recent user turns to scan for the bypass phrase. Matches
@@ -109,19 +124,45 @@ export function findFleetRepoRoot(filePath: string): string | undefined {
   return undefined
 }
 
+// True when the on-disk file carries the fleet-block BEGIN/END markers — i.e.
+// it's a hybrid file whose content outside the markers is repo-owned. The
+// markers are the same comment sentinels the sync's *-fleet-block checks use
+// (gitignore, gitattributes, workflows). Comment-prefix-agnostic: match the
+// marker text regardless of the leading `#`.
+function hasFleetBlockMarkers(absPath: string): boolean {
+  if (!existsSync(absPath)) {
+    return false
+  }
+  try {
+    return textHasFleetBlockMarkers(readFileSync(absPath, 'utf8'))
+  } catch {
+    return false
+  }
+}
+
 export function isCanonicalRelativePath(
   rel: string,
   repoRoot?: string | undefined,
 ): boolean {
   const normalized = rel.replace(/\\/g, '/')
-  // A file is fleet-canonical iff its parent directory exists under
-  // template/ in the wheelhouse. Directory-level check: if the dir is
-  // in the template, every file in that dir is canonical.
-  if (repoRoot) {
-    const dir = path.posix.dirname(normalized)
-    return isDirSync(path.join(repoRoot, 'template', dir))
+  if (!repoRoot) {
+    return false
+  }
+  const dir = path.posix.dirname(normalized)
+  // Root-level files (dir === '.') have no parent dir to probe — `template/.`
+  // is the template dir itself and ALWAYS exists, which would wrongly mark
+  // EVERY root file (pnpm-workspace.yaml, package.json) as canonical. Root
+  // config like pnpm-workspace.yaml is the wheelhouse's OWN source of truth
+  // (synthesized into downstream via the cascade, not via a template/ copy) —
+  // there is no `template/pnpm-workspace.yaml`. So for a root file, require an
+  // actual `template/<file>` to exist before calling it canonical.
+  if (dir === '.') {
+    return existsSync(path.join(repoRoot, 'template', normalized))
   }
-  return false
+  // A file is fleet-canonical iff its parent directory exists under template/
+  // in the wheelhouse. Directory-level: if the dir is in the template, every
+  // file in that dir is canonical.
+  return isDirSync(path.join(repoRoot, 'template', dir))
 }
 
 export function isInsideTemplate(filePath: string): boolean {
@@ -175,6 +216,19 @@ async function main(): Promise<number> {
     return 0
   }
 
+  // Fleet-block allowance: a canonical file that carries the
+  // `# ─── BEGIN/END fleet-canonical ───` markers is only PART fleet-managed —
+  // content outside the markers is repo-owned (e.g. a workflow's repo-specific
+  // jobs below the END marker). Allow edits when the markers are present
+  // either on disk OR in the incoming content (the bootstrap that first adds
+  // the markers). The sync's workflow-fleet-block check re-validates the marked
+  // block at commit time, so a fork INSIDE the block is still caught.
+  const incoming =
+    payload.tool_input?.content ?? payload.tool_input?.new_string
+  if (hasFleetBlockMarkers(absPath) || textHasFleetBlockMarkers(incoming)) {
+    return 0
+  }
+
   // Bypass-phrase check.
   if (
     bypassPhrasePresent(

.claude/hooks/fleet/no-fleet-fork-guard/test/index.test.mts

@@ -395,3 +395,40 @@ test('empty stdin passes through', async () => {
   })
   assert.strictEqual(result.code, 0)
 })
+
+// Root-level files (dirname === '.') previously mis-resolved to `template/.`
+// (the template dir, which always exists) and were wrongly blocked. A root file
+// is canonical only when an actual template/<file> twin exists.
+test('Edit on a root-level file with NO template twin passes (e.g. pnpm-workspace.yaml)', async () => {
+  const repo = makeFakeFleetRepo()
+  try {
+    // The repo HAS a template/ dir but no template/pnpm-workspace.yaml.
+    mkdirSync(path.join(repo, 'template'), { recursive: true })
+    const file = path.join(repo, 'pnpm-workspace.yaml')
+    writeFileSync(file, 'catalog:\n')
+    const result = await runHook({
+      tool_input: { file_path: file, new_string: 'x' },
+      tool_name: 'Edit',
+    })
+    assert.strictEqual(result.code, 0)
+  } finally {
+    rmSync(repo, { force: true, recursive: true })
+  }
+})
+
+test('Edit on a root-level file WITH a template twin is BLOCKED (e.g. CLAUDE.md)', async () => {
+  const repo = makeFakeFleetRepo()
+  try {
+    mkdirSync(path.join(repo, 'template'), { recursive: true })
+    writeFileSync(path.join(repo, 'template/CLAUDE.md'), '# canonical\n')
+    const file = path.join(repo, 'CLAUDE.md')
+    const result = await runHook({
+      tool_input: { file_path: file, new_string: 'x' },
+      tool_name: 'Edit',
+    })
+    assert.strictEqual(result.code, 2)
+    assert.match(result.stderr, /no-fleet-fork-guard/)
+  } finally {
+    rmSync(repo, { force: true, recursive: true })
+  }
+})

.claude/hooks/fleet/no-test-in-scripts-guard/README.md

@@ -0,0 +1,46 @@
+# no-test-in-scripts-guard
+
+PreToolUse(Edit/Write/MultiEdit) hook that blocks creating a `*.test.*` file
+anywhere under `scripts/`.
+
+## What it catches
+
+An Edit/Write whose `file_path` matches `scripts/**/*.test.*` — e.g.
+`scripts/fleet/test/foo.test.mts`, `scripts/repo/sync-scaffolding/test/bar.test.mts`.
+
+Tests live under `test/` (`test/unit/`, `test/isolated/`, …). `scripts/` is for
+scripts. A test under `scripts/**` is invisible to the vitest runner — the fleet
+`.config/repo/vitest.config.mts` excludes `scripts/**/test/**` and nothing else
+runs it — so it silently never executes. That's worse than no test: it looks
+green while proving nothing.
+
+Reusable test helpers belong in `test/_shared/fleet/lib/`, not a
+`scripts/**/test/helpers.mts`.
+
+## What it allows
+
+- `*.test.*` under `test/**` — the canonical home.
+- The co-located test homes that own their own runners and are NOT under
+  `scripts/`: `.config/fleet/oxlint-plugin/test/`, `.claude/hooks/**/test/`,
+  `.git-hooks/**/test/`.
+- Non-test files under `scripts/` — only `*.test.*` paths are blocked.
+
+## Why
+
+2026-06-04: the wheelhouse had 11 `scripts/fleet/test/` + 22
+`scripts/repo/sync-scaffolding/test/` node:test suites that never ran in CI —
+the cascade engine's own tests were dead. Moving them to `test/unit/` (vitest)
+surfaced a real regression (a `check-lock-step-refs` regex gone all-non-capturing
+so every reference resolved as `undefined`). This guard stops the pattern
+recurring at edit time.
+
+## Bypass
+
+Type `Allow test-in-scripts bypass` in a recent user turn.
+
+## Exit codes
+
+- `0` — pass (not a test under scripts/, or bypass present).
+- `2` — block.
+
+Fails open on any throw.

.claude/hooks/fleet/no-test-in-scripts-guard/index.mts

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// Claude Code PreToolUse hook — no-test-in-scripts-guard.
+//
+// Blocks Edit/Write that create a `*.test.*` file anywhere under `scripts/`.
+// Tests live under `test/` (test/unit/, test/isolated/, …). `scripts/` is for
+// scripts. A test under `scripts/**` is INVISIBLE to the vitest runner — the
+// fleet `.config/repo/vitest.config.mts` excludes `scripts/**/test/**`, and no
+// other runner picks it up — so it silently never runs (false confidence:
+// written, green-looking, never executed).
+//
+// The only legitimate co-located test homes are the tooling trees that own
+// their own suites and have their own runners: `.config/fleet/oxlint-plugin/
+// test/`, `.claude/hooks/**/test/`, `.git-hooks/**/test/`. Those are NOT under
+// scripts/, so this guard never touches them.
+//
+// Incident: 2026-06-04 the wheelhouse had 11 scripts/fleet/test/*.test.mts +
+// 22 scripts/repo/sync-scaffolding/test/*.test.mts suites that imported
+// node:test and never ran in CI — the cascade engine's own tests were dead.
+// Moving them to test/unit/ (vitest) surfaced a real regression (a
+// check-lock-step-refs regex that had gone all-non-capturing). This guard
+// stops the pattern recurring at edit time.
+//
+// Reusable test helpers belong in `test/_shared/fleet/lib/`, not a
+// `scripts/**/test/helpers.mts`.
+//
+// Bypass: `Allow test-in-scripts bypass` in a recent user turn.
+//
+// Exit codes: 0 — pass; 2 — block. Fails open on any throw.
+
+import process from 'node:process'
+
+import { getDefaultLogger } from '@socketsecurity/lib-stable/logger/default'
+import { normalizePath } from '@socketsecurity/lib-stable/paths/normalize'
+
+import { withEditGuard } from '../_shared/payload.mts'
+import { bypassPhrasePresent } from '../_shared/transcript.mts'
+
+const logger = getDefaultLogger()
+
+const BYPASS_PHRASE = 'Allow test-in-scripts bypass'
+
+// A `*.test.*` file (test.mts/ts/js/mjs/cjs/tsx/jsx) sitting under a `scripts/`
+// dir at any depth. Path normalized to `/` first so the regex stays
+// single-separator.
+const TEST_IN_SCRIPTS_RE =
+  /(?:^|\/)scripts\/.*\.test\.[a-z]+$/
+
+export function isTestInScripts(filePath: string): boolean {
+  return TEST_IN_SCRIPTS_RE.test(normalizePath(filePath))
+}
+
+// Async IIFE rather than top-level await: directly-run `.mts` hooks aren't
+// CJS-bundled, but the fleet `no-top-level-await` rule is on for this path, and
+// weakening it globally is the wrong fix (no-disable-lint-rule).
+void (async () => {
+  await withEditGuard((filePath, _content, payload) => {
+    if (!isTestInScripts(filePath)) {
+      return
+    }
+    if (bypassPhrasePresent(payload.transcript_path, BYPASS_PHRASE)) {
+      return
+    }
+    logger.error(
+      [
+        '[no-test-in-scripts-guard] Blocked: test file under scripts/.',
+        '',
+        `  Path: ${normalizePath(filePath)}`,
+        '',
+        '  Tests live under `test/` (test/unit/, test/isolated/, …). A test',
+        '  under scripts/** is excluded by the vitest config and silently',
+        '  never runs. Move it:',
+        '',
+        '    test/unit/<name>.test.mts   not   scripts/**/test/<name>.test.mts',
+        '',
+        '  Reusable test helpers go in test/_shared/fleet/lib/.',
+        '  Co-located test homes (NOT under scripts/) are the only exception:',
+        '  .config/fleet/oxlint-plugin/test/, .claude/hooks/**/test/,',
+        '  .git-hooks/**/test/.',
+        '',
+        `  Bypass: type \`${BYPASS_PHRASE}\` if this is genuinely intended.`,
+        '',
+      ].join('\n'),
+    )
+    process.exitCode = 2
+  })
+})()

.claude/hooks/fleet/no-test-in-scripts-guard/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "hook-no-test-in-scripts-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:"
+  }
+}