chore(sync): cascade fleet skills + helpers from socket-repo-template

Pulls in the latest fleet-canonical skill changes from
socket-repo-template via `node scripts/sync-scaffolding.mts --fix`.

Highlights of what's new from upstream:
- _shared/ taxonomy: prose modules + scripts/ for shared TS helpers.
- New shared docs: variant-analysis.md, compound-lessons.md,
  skill-authoring.md.
- New shared TS: scripts/git-default-branch.mts (main → master fallback).
- worktree-management/ skill (new / pr-fanout / prune modes).
- scanning-quality/scans/ split: variant-analysis, insecure-defaults,
  differential.
- guarding-paths restructured: reference.md (prose) + templates/ (.tmpl
  scaffolding) instead of mixed reference/.
- Skill orchestrator/reference split across updating, updating-lockstep,
  driving-cursor-bugbot, refreshing-history, guarding-paths.
- refreshing-history/run.sh → run.mts (cross-platform via
  @socketsecurity/lib/spawn).
- CLAUDE.md fleet block: new rules for variant analysis, compound
  lessons, plan review, default-branch fallback, .mts-over-.sh runners.

Author: jdalton

.claude/skills/_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/_shared/scripts/git-default-branch.mts

@@ -0,0 +1,88 @@
+/**
+ * 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, spawn } from '@socketsecurity/lib/spawn'
+
+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
+  }
+}

.claude/skills/_shared/skill-authoring.md

@@ -0,0 +1,98 @@
+# Skill authoring patterns
+
+Conventions every fleet skill follows. Reference from new-skill scaffolds and from auditor agents.
+
+## Modular structure
+
+A skill's `SKILL.md` is the **orchestrator**, not the encyclopedia. When a skill grows past ~300 lines or covers more than one phase / tool / domain, push the depth into siblings:
+
+```
+.claude/skills/
+├── _shared/
+│   ├── <topic>.md          # shared prose loaded on demand by multiple skills
+│   └── scripts/
+│       └── <helper>.mts    # shared TS helpers used by per-skill run.mts files
+└── my-skill/
+    ├── SKILL.md            # ≤ 300 lines, table of contents + decision flow
+    ├── reference.md        # long-form prose Claude reads (single file, growable to a dir)
+    ├── scans/<type>.md     # one file per scan type / phase / tool (when many)
+    ├── templates/          # file scaffolding copied verbatim by install/setup modes
+    │   └── <name>.tmpl
+    └── run.mts             # skill-specific executable runner
+```
+
+Two naming conventions are load-bearing:
+
+- **`lib/` vs `scripts/`** matches the fleet's public-vs-private convention. `lib/` names a public, importable, stable surface (think `@socketsecurity/lib`); `scripts/` names private, internal automation that's not consumed outside the host repo. Skill helpers under `_shared/scripts/` are internal automation — no external consumers — so `scripts/` is the right name. (No `_shared/lib/` exists in this tree.)
+- **`reference.md` vs `reference/`** — single file by default; grow to a directory only when a skill genuinely has multiple distinct reference docs. Don't preemptively wrap a single doc in a dir.
+- **`templates/`** is reserved for file scaffolding (`.tmpl` files copied verbatim by `install` / `setup` modes). Don't mix templates into `reference/` — readers can't tell prose from scaffolding by directory name alone.
+
+The same File-size rule from CLAUDE.md applies — soft cap 500, hard cap 1000 — but for skills the trigger is usually **shape**, not lines: as soon as the SKILL.md is "this and also that and also the other thing," extract.
+
+What goes where:
+
+| Path | Purpose |
+|---|---|
+| `<skill>/SKILL.md` | Orchestrator: when to use, modes, phase list, links to deeper files. Reads top-to-bottom in one screen. |
+| `<skill>/reference.md` | Long-form depth: bash blocks, full validation rules, sample outputs, recovery procedures. Loaded by the orchestrator when a phase needs it. |
+| `<skill>/scans/`, `phases/`, `tools/` | One file per discrete unit when the skill enumerates many (e.g., `scanning-quality/scans/<type>.md`). Adding a new unit = one new file, no SKILL.md touch. |
+| `<skill>/templates/<name>.tmpl` | File scaffolding (`.tmpl` files copied verbatim by `install` / `setup` modes — gate scripts, allowlist starters, etc.). Distinct from `reference.md` which is prose, not scaffolding. |
+| `<skill>/run.mts` | Skill-specific executable runner. Inline prompts so prompts and code can't drift. Per CLAUDE.md _Tooling — Runners are `.mts`, not `.sh`_. |
+| `_shared/<topic>.md` | Shared **prose** (variant-analysis discipline, compound-lessons workflow, multi-agent backends). Cross-skill load surface. |
+| `_shared/scripts/<helper>.mts` | Shared **TypeScript** helpers imported by per-skill `run.mts` (default-branch resolution, report formatting, spawn wrappers). Internal automation — not a public library, hence `scripts/` not `lib/`. Use `@socketsecurity/lib/spawn` for subprocesses, never raw `node:child_process`. |
+
+## Auditor agents
+
+Skills that author other artifacts (skills, hooks, slash commands, subagents) should ship an auditor sibling. The pattern:
+
+1. The authoring skill emits a draft.
+2. An auditor agent (separate prompt, narrower tool surface) reviews against a checklist.
+3. The authoring skill applies the auditor's feedback before shipping.
+
+Three audit dimensions per artifact:
+
+| Artifact | Auditor checks |
+|---|---|
+| Skill | frontmatter complete, when-to-use unambiguous, tool surface minimal, no buried opinions |
+| Hook | matcher tight, command exits fast, doesn't depend on session state, can't deadlock |
+| Slash command | argument shape clear, idempotent, doesn't touch shared state without confirmation |
+| Subagent | prompt self-contained (no "based on the conversation"), tool surface matches the task, return shape documented |
+
+A fleet skill that does this well is the canonical reference; the auditor is a `Task` agent spawned by the authoring skill, not a long-running daemon.
+
+## Compound-lessons capture
+
+When a fleet skill discovers a recurring failure mode — a lint rule that catches the same kind of bug, a hook that blocks the same antipattern, a review pass that flags the same regression — codify it once:
+
+1. Open a follow-up to add the rule to CLAUDE.md, the hook, or the skill prompt.
+2. Reference the original incident (commit, PR, finding ID) in a one-line `**Why:**` so future readers know the rule is load-bearing.
+3. Resist the urge to write a full retrospective doc — the fleet rule **is** the retrospective.
+
+This is the fleet's equivalent of a post-mortem: every recurring bug becomes a rule, every rule earns its place by closing a class of bugs. The principle is _compound engineering_: each unit of work makes the next unit easier.
+
+## When to NOT extract
+
+- One-off skill (≤ 100 lines, single phase, single tool) — keep it monolithic.
+- Code unique to one repo that can't be shared — keep it in that repo's `unique` skill.
+- Prompt that's tightly coupled to its caller — inline, don't split.
+
+The principle: **a reader should be able to predict what's in a skill from its name, and find what they need without scrolling past three other concerns.** Same as the File-size rule, applied to skills.
+
+## Frontmatter requirements (from upstream)
+
+The Anthropic docs codify several rules; honor them:
+
+- `name`: ≤ 64 chars, lowercase letters / numbers / hyphens only. No `anthropic` / `claude` substring.
+- `description`: ≤ 1024 chars, third-person voice (`"Manages X"`, not `"I help with X"` or `"You can use this to X"`). Include both **what** and **when to use**.
+- Prefer **gerund form** for the name (`processing-pdfs`, `scanning-quality`); noun-phrase (`pdf-processing`) and verb-imperative (`process-pdfs`) are acceptable alternatives, but pick one and be consistent across the fleet.
+- Use forward slashes in any path the skill references — never backslashes, even in docs that target Windows users.
+
+## References
+
+Authoritative upstream docs — keep these as the source of truth, mirror their guidance here only when fleet specifics demand it:
+
+- [Anthropic — Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — frontmatter rules, progressive disclosure, evaluation-driven development.
+- [Anthropic — Claude Code best practices: writing an effective CLAUDE.md](https://code.claude.com/docs/en/best-practices#write-an-effective-claude-md) — CLAUDE.md scope, pruning discipline, when to push knowledge into a skill instead.
+- [Anthropic — Prompt engineering best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) — model-tuning, response-length calibration, examples-over-descriptions.
+
+Real-world plugin reference (not fleet-canonical, useful as a worked example of skills + hooks + templates working together): [`arscontexta`](https://github.com/agenticnotetaking/arscontexta) — knowledge-system plugin that derives skills/hooks/templates from a conversational setup. Useful as a study of the "skills compose into a system" pattern.

.claude/skills/_shared/variant-analysis.md

@@ -0,0 +1,52 @@
+# Variant analysis
+
+When a finding lands — a bug, a regression, a security issue — the next question is always: **does this same shape exist anywhere else in the repo?** Variant analysis is the systematic answer.
+
+## Why this exists
+
+A bug is rarely unique. The mental model that produced it usually produced siblings. The reviewer who didn't catch it once usually missed the rest. Treating each finding as one-off leaks variants into production.
+
+This file is referenced by `scanning-quality` (variant-analysis scan type), `scanning-security`, and `reviewing-code`.
+
+## The pattern
+
+For every confirmed finding, run three searches before closing it out:
+
+1. **Same file, different lines** — the antipattern often clusters within the file that exhibits it. Read the whole file, not just the diff.
+2. **Sibling files, same shape** — `rg`/`grep` for the same call, the same condition, the same data flow. If the bug was `if (foo == null)`, search for that exact shape.
+3. **Cross-package, same concept** — does another package own a parallel implementation? If `socket-cli` has the bug, does `socket-registry` have it too? Fleet drift loves to hide variants.
+
+## What counts as "the same shape"
+
+| Bug class | What to search for |
+|---|---|
+| Missing null check | the call before the access — `foo.bar()` where `foo` could be undefined |
+| Race condition | the lock primitive + the call sequence |
+| Path construction | literal `path.join('build', …)` outside the canonical `paths.mts` |
+| Insecure default | the option name, the boolean default, the env-var fallback |
+| Token leak | the field name (`token`, `api_key`, …), the log statement, the error message |
+| Promise.race leak | `Promise.race(`, `Promise.any(` inside a `for`/`while` |
+| Forbidden API | `fetch(`, `fs.rm(`, `fs.access(`, raw `npx` / `pnpm dlx` |
+
+## Outputs
+
+For each variant found, emit:
+
+```
+- file:line — variant of <original-finding-id>
+  Pattern: <one-line shape>
+  Severity: <propagate from original, or LOWER if context differs>
+  Fix: <reference original fix, or note where it diverges>
+```
+
+Variants should be batched into the same fix commit when mechanical (one find/replace), or filed as sibling commits on the same branch when each needs review.
+
+## Don't
+
+- Don't variant-hunt for style nits. Reserve this for correctness / security / fleet-drift findings.
+- Don't expand the search radius past one repo without writing it down — cross-fleet variants get a `chore(sync): cascade <fix>` PR per the _Drift watch_ rule.
+- Don't skip the search because the finding "looks unique." Looking unique is exactly when the search pays off.
+
+## Trail-of-Bits influence
+
+This pattern is borrowed from Trail of Bits' `variant-analysis` plugin (https://github.com/trailofbits/skills) and adapted to the fleet's drift-watch discipline. Their version is Semgrep-rule-driven for security; ours is `rg`-driven for general correctness. Same idea, lighter machinery.