chore(wheelhouse): cascade template@5a97706a

Auto-applied by socket-wheelhouse sync-scaffolding into cascade-socket-bin-2036.
46 file(s) touched:
  - .claude/skills/fleet/_shared/compound-lessons.md
  - .claude/skills/fleet/_shared/env-check.md
  - .claude/skills/fleet/_shared/multi-agent-backends.md
  - .claude/skills/fleet/_shared/path-guard-rule.md
  - .claude/skills/fleet/_shared/report-format.md
  - .claude/skills/fleet/_shared/scripts/git-default-branch.mts
  - .claude/skills/fleet/_shared/scripts/logger-guardrails.mts
  - .claude/skills/fleet/_shared/scripts/resolve-tools.mts
  - .claude/skills/fleet/_shared/security-tools.md
  - .claude/skills/fleet/_shared/skill-authoring.md
  - .claude/skills/fleet/_shared/variant-analysis.md
  - .claude/skills/fleet/_shared/verify-build.md
  - .claude/skills/fleet/agent-ci/SKILL.md
  - .claude/skills/fleet/agent-ci/reference.md
  - .claude/skills/fleet/auditing-gha-settings/SKILL.md
  - .claude/skills/fleet/auditing-gha-settings/run.mts
  - .claude/skills/fleet/cascading-fleet/SKILL.md
  - .claude/skills/fleet/cascading-fleet/lib/cascade-template.mts
  - .claude/skills/fleet/cascading-fleet/lib/fleet-repos.json
  - .claude/skills/fleet/cascading-fleet/lib/fleet-repos.txt
  ... and 26 more

Author: jdalton

.claude/skills/fleet/_shared/compound-lessons.md

@@ -0,0 +1,44 @@
+# Compound lessons
+
+How a fleet skill or review turns a finding into a durable rule, instead of fixing it once and forgetting.
+
+## The principle
+
+Each unit of engineering work should make subsequent units **easier**, not harder. A bug fix that doesn't update the rule that allowed the bug is a half-finished job: the next change in the same area will hit the same class of bug, and the cycle repeats.
+
+Three places a lesson can land in this fleet:
+
+| Where                       | When                                                                   | Effect                                                  |
+| --------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------- |
+| **CLAUDE.md fleet rule**    | The mistake recurs across repos or is a fleet-wide invariant           | Every fleet repo inherits the rule on next sync         |
+| **`.claude/hooks/*` block** | The mistake is mechanical and can be detected from tool input/output   | Hook blocks the next attempt before the file is written |
+| **Skill prompt update**     | The mistake is judgment-shaped (review pass missed a class of finding) | Future runs of that skill catch the variant             |
+
+## When to compound
+
+Compound a lesson **only** when one of these is true:
+
+1. **Recurrence** — the same kind of bug has now appeared 2+ times. Write down the rule that would have caught both.
+2. **High blast radius** — the bug shipped, broke a downstream user, or required a revert. The rule prevents the next shipping incident.
+3. **Drift signal** — fleet repos disagreed on the answer. The rule reconciles which answer wins.
+
+Don't compound for one-off fixes that won't recur. Don't write a "lesson" doc when the lesson is just "we fixed it." The fleet rule **is** the lesson; if you can't crystallize it into a rule, the lesson isn't ready.
+
+## How to compound
+
+1. **Name the rule** — one sentence, imperative voice. "Never X." "Always Y."
+2. **Cite the incident** — one-line `**Why:**` line referencing the commit, PR, or finding. Don't write a paragraph.
+3. **State the application** — one-line `**How to apply:**` line saying when the rule fires.
+4. **Land it where it'll fire** — CLAUDE.md, hook, or skill prompt. Pick the lowest-friction surface that catches the next occurrence.
+
+Skip the retrospective doc. Skip the post-mortem template. The rule is the artifact.
+
+## Anti-patterns
+
+- **The "lessons learned" graveyard** — a `docs/lessons/` folder where dated markdown files rot. Don't. The rule belongs in the live config that fires on the next run.
+- **Vague rules** — "be careful with X." Useless. If you can't write the rule as a `rg` pattern or a CLAUDE.md `🚨` line, it isn't a rule yet.
+- **Rules without why** — future readers can't judge edge cases without the original incident. Always cite.
+
+## Source
+
+Borrowed from Every Inc.'s _Compound Engineering_ playbook (https://every.to/chain-of-thought/compound-engineering-how-every-codes-with-agents). Their `/ce-compound` slash command is the verb form of this principle; we encode the same discipline as a fleet convention rather than a slash command.

.claude/skills/fleet/_shared/env-check.md

@@ -0,0 +1,28 @@
+# Environment Check
+
+Shared prerequisite validation for all pipelines. Run at the start of every skill.
+
+## Steps
+
+1. Run `git status` to check working directory state
+2. Detect CI mode: check for `GITHUB_ACTIONS` or `CI` environment variables
+3. Verify `node_modules/` exists (run `pnpm install` if missing)
+4. Verify on a valid branch (`git branch --show-current`)
+
+## Behavior
+
+- **Clean working directory**: proceed normally
+- **Dirty working directory**: warn and continue (most skills are read-only or create their own commits)
+- **CI mode**: set `CI_MODE=true` — skills should skip interactive prompts and local-only validation
+- **Missing node_modules**: run `pnpm install` before proceeding
+
+## Queue Tracking
+
+Write a run entry to `.claude/ops/queue.yaml` with:
+
+- `id`: `{pipeline}-{YYYY-MM-DD}-{NNN}`
+- `pipeline`: the invoking skill name
+- `status`: `in-progress`
+- `started`: current UTC timestamp
+- `current_phase`: `env-check`
+- `completed_phases`: `[]`

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

@@ -0,0 +1,57 @@
+# Multi-agent backends
+
+Shared policy for skills that delegate work to multiple AI CLIs (codex, claude, opencode, kimi, …). Any skill that calls out to another agent should follow this contract so the user gets a uniform experience across skills.
+
+> Looking for _when_ to hand work off to another agent (CLI subprocess vs. mid-conversation `Agent(subagent_type=…)`)? See [`docs/references/agent-delegation.md`](../../../docs/references/agent-delegation.md). This file covers the _how_ for the CLI-subprocess path.
+
+## Goals
+
+- **Graceful detection.** Skills don't hard-fail when a preferred backend isn't installed. They fall back through a documented preference order, then skip the pass with a recorded note if nothing usable is available.
+- **Consistent attribution.** When a backend produces output, the skill labels the section / report / commit message with the backend name (`Codex Verification`, not just `Verification`) so the reader knows which model said what.
+- **No silent provider routing.** Hybrid backends like `opencode` (which dispatch to other providers internally per their own config) are only used when **explicitly** selected, never auto-picked. Direct backends (codex, claude, kimi) are preferred so model attribution stays accurate.
+
+## Backend registry
+
+| Backend  | CLI binary | Hybrid? | Default role preference                              |
+| -------- | ---------- | ------- | ---------------------------------------------------- |
+| codex    | `codex`    | no      | discovery, discovery-secondary, remediation          |
+| claude   | `claude`   | no      | verify                                               |
+| kimi     | `kimi`     | no      | any role (fallback)                                  |
+| opencode | `opencode` | **yes** | only when `--pass <role>=opencode` explicitly chosen |
+
+Adding a new backend = one entry in the registry: `{ name, bin, hybrid, run(promptFile, outFile) -> { argv, outMode } }`. No other call site changes.
+
+## Detection policy
+
+Detect availability via `command -v <bin>` at runtime, never hardcode "claude is always there." A skill that wants Codex but only has Kimi should run on Kimi (fallback), not bail out.
+
+```
+For each role:
+  preferred = explicit override (--pass role=backend) or first match in role.preferenceOrder
+  if preferred is hybrid AND not explicitly selected -> skip preferred, try next
+  if preferred is installed -> use it
+  if no backend installed for this role -> skip the pass with a note in the output
+```
+
+Document skips inline in whatever output the skill produces (`> Skipped pass: <role> — no available backend`) so the reader sees the gap.
+
+## 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     |
+
+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.
+
+## 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.
+
+## When NOT to use
+
+- Skills that only need _one_ agent (the current Claude session driving the user). No detection needed; just do the work.
+- Skills that need a specific model unconditionally (e.g. a benchmark that compares two models — those use direct API calls, not the CLI registry).
+- Per-repo fix scripts that rely on a single tool (`pnpm`, `git`, `cargo`). Tooling, not agents.

.claude/skills/fleet/_shared/path-guard-rule.md

@@ -0,0 +1,39 @@
+<!--
+Shared snippet — the canonical "1 path, 1 reference" rule text.
+Synced byte-identical across the Socket fleet via socket-wheelhouse's
+sync-scaffolding.mts (SHARED_SKILL_FILES).
+
+This file is the source of truth for the rule's wording. Three artifacts
+embed (or paraphrase) it:
+
+  1. CLAUDE.md — every Socket repo's instructions to Claude.
+  2. .claude/hooks/fleet/path-guard/README.md — what the hook blocks.
+  3. .claude/skills/guarding-paths/SKILL.md — what the skill enforces.
+
+If the wording changes here, re-run `node scripts/sync-scaffolding.mts
+--all --fix` from socket-wheelhouse to propagate.
+-->
+
+## 1 path, 1 reference
+
+**A path is _constructed_ exactly once. Everywhere else _references_ the constructed value.**
+
+Referencing a single computed path many times is fine — that's the whole point of computing it once. What's banned is _re-constructing_ the same path in multiple places, because that's where drift is born. Three concrete shapes:
+
+1. **Within a package** — every script, test, and lib file that needs a build path imports it from the package's `scripts/paths.mts` (or `lib/paths.mts`). No `path.join('build', mode, ...)` outside that module.
+
+2. **Across packages** — when package B consumes package A's output, B imports A's `paths.mts` via the workspace `exports` field. Never `path.join(PKG, '..', '<sibling>', 'build', ...)`. The R28 yoga/ink bug — ink hand-building yoga's wasm path and missing the `wasm/` segment — is the canonical failure mode this rule prevents.
+
+3. **Workflows, Dockerfiles, shell scripts** — they can't `import` TS, so they construct the string once and reference it everywhere downstream. Workflows: a "Compute paths" step exposes `steps.paths.outputs.final_dir`; later steps read `${{ steps.paths.outputs.final_dir }}`. Dockerfiles/shell: assign once to a variable, reference by name thereafter. Each canonical construction carries a comment naming the source-of-truth `paths.mts` so the YAML can't drift from TS without a flagged change. **Re-building** the same path in a second step is the violation, not referring to the constructed value many times.
+
+Comments that re-state a full path are forbidden. The import statement IS the comment. Docs and READMEs may describe the structure ("output goes under the Final dir") but should not encode a complete `build/<mode>/<platform-arch>/out/Final/binary` string — encoded paths get parsed by tools and silently rot.
+
+Code execution takes priority over docs: violations in `.mts`/`.cts`, Makefiles, Dockerfiles, workflow YAML, and shell scripts are blocking. README and doc-comment violations are advisory unless they contain a fully-qualified path with no parametric placeholders.
+
+### Three-level enforcement
+
+- **Hook** — `.claude/hooks/fleet/path-guard/` blocks `Edit`/`Write` calls that would introduce a violation in a `.mts`/`.cts` file. Refusal at edit time stops new duplication from landing.
+- **Gate** — `scripts/check-paths.mts` runs in `pnpm check`. Fails the build on any violation that isn't allowlisted.
+- **Skill** — `/guarding-paths` audits the repo and fixes findings; `/guarding-paths check` reports only; `/guarding-paths install` drops the gate + hook + rule into a fresh repo.
+
+The mantra is intentionally short so it sticks: **1 path, 1 reference**. When in doubt, find the canonical owner and import from it.

.claude/skills/fleet/_shared/report-format.md

@@ -0,0 +1,50 @@
+# Report Format
+
+Shared output format for all scan and review pipelines.
+
+## Finding Format
+
+Each finding:
+
+```
+- **[SEVERITY]** file:line — description
+  Fix: how to fix it
+```
+
+Severity levels: CRITICAL, HIGH, MEDIUM, LOW
+
+## Grade Calculation
+
+Based on finding severity distribution:
+
+- **A** (90-100): 0 critical, 0 high
+- **B** (80-89): 0 critical, 1-3 high
+- **C** (70-79): 0 critical, 4+ high OR 1 critical
+- **D** (60-69): 2-3 critical
+- **F** (< 60): 4+ critical
+
+## Pipeline HANDOFF
+
+When a skill completes as part of a larger pipeline (e.g., scanning-quality within release),
+output a structured handoff block:
+
+```
+=== HANDOFF: {skill-name} ===
+Status: {pass|fail}
+Grade: {A-F}
+Findings: {critical: N, high: N, medium: N, low: N}
+Summary: {one-line description}
+=== END HANDOFF ===
+```
+
+The parent pipeline reads this to decide whether to proceed (gate check) or abort.
+
+## Queue Completion
+
+When the final phase completes, update `.claude/ops/queue.yaml`:
+
+- `status`: `done` (or `failed`)
+- `completed`: current UTC timestamp
+- `current_phase`: `~` (null)
+- `completed_phases`: full list
+- `findings_count`: `{critical: N, high: N, medium: N, low: N}`

.claude/skills/fleet/_shared/scripts/git-default-branch.mts

@@ -0,0 +1,95 @@
+/**
+ * Default-branch resolution for fleet skill runners.
+ *
+ * Per CLAUDE.md "Default branch fallback" rule: prefer main, fall back to
+ * master. Never hard-code one or the other — fleet repos are mostly on main,
+ * but a few legacy / vendored repos still use master, and a script that
+ * hard-codes main silently no-ops on those.
+ *
+ * Cross-platform: shells out to git via @socketsecurity/lib/spawn, which works
+ * the same on macOS / Linux / Windows.
+ */
+import { isSpawnError } from '@socketsecurity/lib/process/spawn/errors'
+import { spawn } from '@socketsecurity/lib/process/spawn/child'
+
+export type ResolveDefaultBranchOptions = {
+  /**
+   * Working directory; defaults to process.cwd().
+   */
+  readonly cwd?: string | undefined
+  /**
+   * Remote name; defaults to 'origin'.
+   */
+  readonly remote?: string | undefined
+}
+
+/**
+ * Resolve the remote's default branch, preferring `main` and falling back to
+ * `master`. Returns `'main'` as a final fallback when the remote has neither
+ * branch (e.g., fresh clone before `git fetch`).
+ *
+ * Resolution order:
+ *
+ * 1. `git symbolic-ref refs/remotes/<remote>/HEAD` — most reliable.
+ * 2. Probe `refs/remotes/<remote>/main` — true on the vast majority of fleet
+ *    repos.
+ * 3. Probe `refs/remotes/<remote>/master` — legacy / vendored repos.
+ * 4. Assume `main` and let the next git command fail loudly.
+ */
+export async function resolveDefaultBranch(
+  options: ResolveDefaultBranchOptions = {},
+): Promise<string> {
+  const { cwd = process.cwd(), remote = 'origin' } = options
+
+  // Step 1: ask the remote what its HEAD points to.
+  try {
+    const ref = await runGit(
+      ['symbolic-ref', '--quiet', '--short', `refs/remotes/${remote}/HEAD`],
+      cwd,
+    )
+    if (ref) {
+      // Strip the "<remote>/" prefix.
+      return ref.startsWith(`${remote}/`) ? ref.slice(remote.length + 1) : ref
+    }
+  } catch {
+    // Fall through.
+  }
+
+  // Step 2 + 3: probe main, then master.
+  for (const branch of ['main', 'master']) {
+    if (await branchExists(branch, cwd, remote)) {
+      return branch
+    }
+  }
+
+  // Step 4: last resort.
+  return 'main'
+}
+
+async function branchExists(
+  branch: string,
+  cwd: string,
+  remote: string,
+): Promise<boolean> {
+  try {
+    await runGit(
+      ['show-ref', '--verify', '--quiet', `refs/remotes/${remote}/${branch}`],
+      cwd,
+    )
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function runGit(args: readonly string[], cwd: string): Promise<string> {
+  try {
+    const result = await spawn('git', args, { cwd, stdioString: true })
+    return String(result.stdout ?? '').trim()
+  } catch (e) {
+    if (isSpawnError(e)) {
+      throw e
+    }
+    throw e
+  }
+}