fix(security): scan runner finishes every repository; method docs current

[leemour]

Task

Bring the security method, runbook and lessons up to the current facts, and make the security scan runner finish a multi-repository run and work from the published package.

Why

• METHOD.md and RUNBOOK.md described an older setup: five repositories under pre-rename names, a high audit gate, zizmor as a gate, CodeQL through GitHub default setup, commands that no longer exist (max agent config, pino, diagnose). Runbook step 1 would have turned CodeQL default setup back on, which conflicts with the workflow CodeQL in release-checks.yml.
• scripts/security/scan stopped at the first repository whose scanner failed, so one repository could hide every repository after it.
• Semgrep timed out on this repository's saved third-party HTML pages, and its fallback handled only .ts/.tsx parse failures.
• From an installed package the Semgrep stage could not run at all: Node refuses to strip types under node_modules.

What

Runner (fix(security)):

• semgrep.ts moves to src/semgrep.ts and ships compiled as dist/semgrep.js. scan runs the source in a checkout and the compiled file from an install. files no longer lists the .ts.
• scan records a failing tool per repository, scans the remaining repositories, writes SCOPE.md, then exits 1 and names the failed ones on stderr. A failing gh api read no longer aborts the run either.
• The parse fallback covers .js, .jsx, .mjs, .cjs, .mts and .cts too, keeps top-level await (--supported:top-level-await=true), and refuses two sources that would compile to the same file.
• One rule failing on one file (Internal matching error, level warn) is recorded as coverageGaps in semgrep.json and as a gap line in SCOPE.md. This is a judgement call: such an error otherwise fails the repository on every run. Every other scanner error still fails closed: non-zero exit, invalid JSON, timeouts, errors at level error, unknown types, and compile or parse failures in the fallback.
• .semgrepignore excludes performance/**/fixtures/. The file replaces Semgrep's built-in list, so it repeats that list (taken from 1.178.0). scan writes a repository's .semgrepignore patterns into SCOPE.md.

Documents (docs(security)):

• METHOD.md: every WireCatLabs repository, with cli-private through gitleaks only. Steps use cli-testing security scan|socket, plus a gitleaks step run from each repository root. Release gates: pnpm audit --prod --audit-level critical, CodeQL ≥ 9.0, full-history gitleaks, and zizmor as a report (--no-exit-codes). CodeQL runs in release-checks.yml with default setup off. The settings read-back now expects not-configured, plus private reporting, the attached configuration, the npm environment and rulesets. It also shows how to verify that the organisation configuration WireCat public is the default for new repositories and keeps default setup disabled. Checklist names are current (max config set permissions, max mcp --permission, max/tg doctor report create, cli-base src/logging.ts, the postinstall scripts and Windows installers, and parser dependencies by repository).
• RUNBOOK.md: removes the default-setup step. Adds private reporting, the npm environment only where a repository publishes, the full repository list through the runner, and gitleaks per repository root.
• LESSONS.md: CodeQL 2.27 SARIF keeps rules in tool.extensions[].rules, so a gate must resolve rule.toolComponent.index. A new repository does not inherit settings applied repository by repository. gitleaks reads .gitleaksignore from the current folder. A .semgrepignore replaces the built-in list. Default setup refuses workflow SARIF uploads.
• CLAUDE.md: points at the security policy, names cli-core, and says this repository's tests run once on each merge to main (rule 4 and the check budget). The PR template and MONTHLY.md name cli-core.

Merge order

• Depends on ci: validate main on push, fix Dependabot, drop persisted checkout tokens #61 merging first. That PR adds main.yml; until then, the CLAUDE.md sentence about tests on merge is not yet true.
• Merge after the cli-base release-checks.yml CodeQL rule-resolution fix is released, since METHOD.md describes that gate as blocking.

Testing

• pnpm typecheck exit 0; biome check src scripts exit 0; pnpm docs:check exit 0.
• pnpm test:coverage: all tests pass, thresholds met.
• New src/semgrep.test.ts cases cover the .mjs fallback mapped back to source, refusal of colliding outputs, a recorded coverage gap, and fail-closed on timeout, error-level matching errors, non-JS syntax errors and a scanner exit 2.
• New scripts/security-scan.test.ts runs scan with stub tools against two local repositories. The first fails; the second is still scanned; the exit is 1; and SCOPE.md carries the exit codes, gap and ignore lines.
• pnpm pack, unpacked under node_modules/@wirecat/cli-testing/, then scripts/security/scan with stub tools: exit 0, semgrep.json written.
• Semgrep 1.178.0 on an export of this repository, with and without .semgrepignore: the scanned set differs only by performance/documents/html-readers/fixtures/.

🤖 Generated with Claude Code