chore(wheelhouse): cascade template@71c60ade

Author: jdalton

.claude/skills/fleet/_shared/multi-agent-backends.md

@@ -37,15 +37,32 @@ Document skips inline in whatever output the skill produces (`> Skipped pass: <r
 
 ## Env-var conventions
 
-| Var               | Default       | Purpose                                        |
-| ----------------- | ------------- | ---------------------------------------------- |
-| `CODEX_MODEL`     | `gpt-5.4`     | Codex model when codex is the active backend   |
-| `CODEX_REASONING` | `xhigh`       | Codex reasoning effort                         |
-| `CLAUDE_MODEL`    | `opus`        | Claude model when claude is the active backend |
-| `KIMI_MODEL`      | `kimi-latest` | Kimi model when kimi is the active backend     |
+| Var               | Default       | Purpose                                          |
+| ----------------- | ------------- | ------------------------------------------------ |
+| `CLAUDE_EFFORT`   | `high`        | Claude reasoning effort (claude `--effort`)      |
+| `CLAUDE_MODEL`    | `opus`        | Claude model when claude is the active backend   |
+| `CODEX_MODEL`     | `gpt-5.4`     | Codex model when codex is the active backend     |
+| `CODEX_REASONING` | `xhigh`       | Codex reasoning effort                           |
+| `KIMI_MODEL`      | `kimi-latest` | Kimi model when kimi is the active backend       |
+
+Pair model with effort, never just model: a cheap model left on the session's default effort still burns reasoning tokens, and a premium model on `low` underthinks. Both codex (`CODEX_REASONING`) and claude (`CLAUDE_EFFORT`) carry an effort knob — set both axes when a backend supports it. Kimi has no effort flag, so it inherits its CLI default.
 
 Don't invent per-skill env var names — reuse these. Skills that need a non-default model for a specific run accept a `--model` flag rather than introducing new env vars.
 
+## Effort-capability matrix
+
+Reasoning effort is NOT one flat vocabulary across backends — only map an effort onto a backend that actually accepts that level, or you'll pass an invalid value. The lib's `spawnAiAgent` translates the shared `AiEffort` (`@socketsecurity/lib/ai/types`) per-agent; this table is the source of truth for what each accepts.
+
+| Backend  | Effort flag                        | Accepted levels                       | `max` handling          |
+| -------- | ---------------------------------- | ------------------------------------- | ----------------------- |
+| claude   | `--effort <level>`                 | low / medium / high / xhigh / max     | passes through          |
+| codex    | `-c model_reasoning_effort=<level>`| minimal / low / medium / high / xhigh | clamped to `xhigh`      |
+| gemini   | (none)                             | —                                     | ignored                 |
+| kimi     | (none)                             | —                                     | ignored                 |
+| opencode | (none — provider-internal)         | —                                     | ignored                 |
+
+`AiEffort` = `low | medium | high | xhigh | max`. `minimal` is codex-only and outside `AiEffort`; `max` is claude-only, so `buildArgs` clamps it to codex's `xhigh` ceiling. A backend with no effort flag silently ignores the value — never gate behavior on a backend honoring effort it doesn't support. When you hand-roll a backend runner (not via `spawnAiAgent`), pick the effort default from this table's vocab for that backend, not a flat constant.
+
 ## Canonical implementation
 
 `.claude/skills/reviewing-code/run.mts` is the reference implementation. New skills that need multi-agent delegation should import the same registry shape and detection function (or copy the small block until extraction is worth doing) — don't roll a parallel pattern.

.claude/skills/fleet/reviewing-code/run.mts

@@ -75,6 +75,10 @@ const BACKENDS: Readonly<Record<BackendName, BackendDescriptor>> = {
     name: 'claude',
     run(_promptFile, _outFile) {
       const model = process.env['CLAUDE_MODEL'] ?? 'opus'
+      // Pair the model with a reasoning effort (claude `--effort`) — see
+      // _shared/multi-agent-backends.md. Review is judgment-heavy, so the
+      // default is `high`; codex's sibling knob is CODEX_REASONING.
+      const effort = process.env['CLAUDE_EFFORT'] ?? 'high'
       // Programmatic-Claude lockdown — all four flags per CLAUDE.md
       // (tools / allowedTools / disallowedTools / permission-mode).
       // The official permission flow is hooks → deny → mode → allow →
@@ -89,6 +93,8 @@ const BACKENDS: Readonly<Record<BackendName, BackendDescriptor>> = {
           '--print',
           '--model',
           model,
+          '--effort',
+          effort,
           '--no-session-persistence',
           '--permission-mode',
           'dontAsk',

pnpm-workspace.yaml

@@ -90,7 +90,8 @@ minimumReleaseAgeExclude:
   - '@ultrathink/*'
   - '@yuku-parser/*'
   - '@socketoverride/*'
-  - 'shell-quote'
+  # published: 2026-05-22 | removable: 2026-05-29
+  - 'shell-quote@1.8.4'
 
 # Refuse transitive dependencies declared via git/tarball/local-tarball
 # specs — an npm package shouldn't be allowed to drag in a git URL we

scripts/fleet/ai-lint-fix.mts

@@ -42,7 +42,11 @@ import { getDefaultLogger } from '@socketsecurity/lib-stable/logger/default'
 import { hasClaudeCli, runClaudeFix } from './ai-lint-fix/claude.mts'
 import { runLintJson } from './ai-lint-fix/oxlint-json.mts'
 import { bucketFindings, buildPrompt } from './ai-lint-fix/prompt.mts'
-import { TIER_MODEL, escalateTier } from './ai-lint-fix/rule-guidance.mts'
+import {
+  TIER_EFFORT,
+  TIER_MODEL,
+  escalateTier,
+} from './ai-lint-fix/rule-guidance.mts'
 
 const logger = getDefaultLogger()
 
@@ -113,18 +117,20 @@ async function main(): Promise<void> {
 
   for (const [filePath, findings] of byFile) {
     const rel = path.relative(cwd, filePath)
-    // Pick the model from the highest-tier rule in this file's batch.
-    // Pure-Haiku files (identifier renames, null→undefined, etc.) run
-    // cheap; any caller-chain rewrite escalates to Sonnet; a
-    // `socket/max-file-lines` finding escalates to Opus.
+    // Pick the model AND effort from the highest-tier rule in this file's
+    // batch. Pure-Haiku files (identifier renames, null→undefined, etc.) run
+    // cheap on low effort; any caller-chain rewrite escalates to Sonnet on
+    // medium; a `socket/max-file-lines` finding escalates to Opus on high.
+    // Effort tracks the tier per the CLAUDE.md token-spend rule.
     const ruleIds = findings
       .map(f => f.ruleId)
       .filter((r): r is string => typeof r === 'string')
     const tier = escalateTier(ruleIds)
     const model = TIER_MODEL[tier]
-    logger.log(`AI-fix ${rel} (${findings.length} findings, ${tier})…`)
+    const effort = TIER_EFFORT[tier]
+    logger.log(`AI-fix ${rel} (${findings.length} findings, ${tier}/${effort})…`)
     const prompt = buildPrompt(filePath, findings)
-    const { exitCode, stderr } = await runClaudeFix(prompt, cwd, model)
+    const { exitCode, stderr } = await runClaudeFix(prompt, cwd, model, effort)
     if (exitCode === 0) {
       totalEdits += findings.length
       continue

scripts/fleet/ai-lint-fix/claude.mts

@@ -8,22 +8,30 @@ import { discoverAiAgents } from '@socketsecurity/lib-stable/ai/discover'
 import { AI_PROFILE } from '@socketsecurity/lib-stable/ai/profiles'
 import { spawnAiAgent } from '@socketsecurity/lib-stable/ai/spawn'
 
+import type { AiEffort } from '@socketsecurity/lib-stable/ai/types'
+
 export async function runClaudeFix(
   prompt: string,
   cwd: string,
   model: string,
+  effort: AiEffort,
 ): Promise<{ exitCode: number; stdout: string; stderr: string }> {
   // AI_PROFILE.edit = in-place edits only (Edit on existing files, no
   // Write/MultiEdit) — exactly the lint-fix contract: the prompt forbids
   // creating files. spawnAiAgent owns the --no-session-persistence /
   // --add-dir / 529-retry the hand-rolled version used to duplicate.
-  // The model is picked per-file by the caller via escalateTier() — see
-  // RULE_MODEL_TIER in rule-guidance.mts. Simple regex-shaped rewrites
-  // run on Haiku; control-flow + caller-chain rewrites run on Sonnet;
-  // module-split refactors (`socket/max-file-lines`) run on Opus.
+  // Model AND effort are picked per-file by the caller via escalateTier() —
+  // see RULE_MODEL_TIER + TIER_EFFORT in rule-guidance.mts. Simple
+  // regex-shaped rewrites run on Haiku/low; control-flow + caller-chain
+  // rewrites run on Sonnet/medium; module-split refactors
+  // (`socket/max-file-lines`) run on Opus/high. Pinning effort alongside the
+  // model is the CLAUDE.md token-spend rule — a cheap model left on the
+  // session's default (often high) still burns reasoning a mechanical
+  // rewrite never needs.
   const { exitCode, stderr, stdout } = await spawnAiAgent({
     ...AI_PROFILE.edit,
     cwd,
+    effort,
     model,
     prompt,
     timeoutMs: 5 * 60 * 1000,

scripts/fleet/ai-lint-fix/rule-guidance.mts

@@ -16,6 +16,8 @@
  *      becomes a concern.
  */
 
+import type { AiEffort } from '@socketsecurity/lib-stable/ai/types'
+
 // 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.
@@ -88,6 +90,26 @@ export const TIER_MODEL: Readonly<Record<'haiku' | 'opus' | 'sonnet', string>> =
     opus: 'claude-opus-4-8',
   } as Readonly<Record<'haiku' | 'opus' | 'sonnet', string>>
 
+/**
+ * Map a tier label to its reasoning-effort level (claude `--effort`). Effort
+ * rides alongside the model per the CLAUDE.md token-spend rule ("match model
+ * AND effort to the job") — a cheap model on max effort still burns reasoning
+ * tokens a mechanical rewrite never needs. The tier ladder already encodes the
+ * job's complexity, so effort tracks it: regex-shaped Haiku rewrites run `low`;
+ * caller-chain Sonnet rewrites run `medium`; Opus module splits (the one tier
+ * that genuinely reasons over the whole file) run `high`. The lib's
+ * `spawnAiAgent` passes this through as the claude `--effort` flag; other agents
+ * ignore it. Resolved via `AiEffort` from `@socketsecurity/lib-stable/ai/types`.
+ */
+export const TIER_EFFORT: Readonly<
+  Record<'haiku' | 'opus' | 'sonnet', AiEffort>
+> = {
+  __proto__: null,
+  haiku: 'low',
+  sonnet: 'medium',
+  opus: 'high',
+} as unknown as Readonly<Record<'haiku' | 'opus' | 'sonnet', AiEffort>>
+
 /**
  * Pick the highest tier present in a per-file batch's rule set. Returns a tier
  * label; the caller resolves it to a model via `TIER_MODEL`. Default (no

scripts/fleet/check.mts

@@ -50,6 +50,11 @@ const steps: Array<() => boolean> = [
   // Cost routing: every mutating (fix) skill must declare a model: tier so
   // mechanical work runs cheap. See docs/claude.md/fleet/skill-model-routing.md.
   () => run('node', ['scripts/fleet/check/mutating-skills-have-model.mts']),
+  // Cost routing twin: a programmatic AI spawn that pins a model must also pin
+  // reasoning effort (CLAUDE.md token-spend). The lib makes effort optional —
+  // this gate is the enforcement the optional field can't provide. Vocab per
+  // backend: .claude/skills/fleet/_shared/multi-agent-backends.md.
+  () => run('node', ['scripts/fleet/check/ai-spawns-have-paired-effort.mts']),
   // Code is law: every hook + socket/* rule ships thorough tests (both arms,
   // every branch). A token or absent test fails the gate.
   () => run('node', ['scripts/fleet/check/enforcers-have-thorough-tests.mts']),
@@ -99,7 +104,7 @@ const steps: Array<() => boolean> = [
   // taxonomy applied — not external/, not _-prefixed) is reachable through some
   // exports entry (no orphaned public module). Complements files[] allowlist
   // hygiene and runtime require-ability; this is the map ↔ files check.
-  () => run('node', ['scripts/fleet/check/exports-cover-public-files.mts']),
+  () => run('node', ['scripts/fleet/check/public-files-are-exported.mts']),
   // Every external-tools.json / bundle-tools.json must match the shared
   // TypeBox schema (scripts/fleet/lib/external-tools-schema.mts). These files
   // pin tool versions + integrities; an unvalidated shape drift surfaces only