cc-safety-net — TypeScript Style Guide with Good/Bad Pairs

• Run focused tests during development, including the failing and passing tests required by Red-Green TDD.
• After all implementation changes, run bun run check. This is the required final check for lint, formatting, typecheck, knip, duplication, and tests. Do not run its components separately as additional final checks.
• Ignore the dist folder; it gets auto-rebuilt by lefthook's pre-commit hook.
• Keep implementation modular; put tests in tests/ mirroring src/, not colocated in src/.
• Files in docs/ use lowercase kebab-case names.

Stacked PRs

• Multi-part work may be split into a gh stack stack. Open stack PRs with gh stack submit --auto --open: plain --auto opens drafts, which the review bots skip.
• dist/ is committed and CI rejects a stale build, but a rebase replays the old build output. When gh stack rebase stops, resolve and git add the source files, never hand-merge dist/: run bun run build && git add -A dist, then gh stack rebase --continue.

Testing

• A behavior change lands as a failing expectation first — a contract corpus row or a stated assertion — then the fix. Re-recording a snapshot or editing the verdict table is never the first step.
• State what a test expects; do not record it. Snapshots (toMatchSnapshot) are permitted only for the two output surfaces whose bytes are the contract: explain (tests/cli/explain) and doctor --json (tests/cli/doctor).
• tests/fixtures/gate/harvested-verdicts.jsonl is the readable verdict table, edited by hand. A change that re-records a snapshot or flips a table row must name in its commit message which entries changed and why, alongside the contract row that explains the flip.

Scope Discipline

Over-engineering is this project's dominant failure mode. The evidence rule that governs analyzer rules governs all code: machinery exists to stop a demonstrated failure, not an imagined one.

• Implement the smallest change that satisfies the request. Each addition beyond it needs the concrete failure it prevents named; if you cannot name one, do not write it.
• Every check must be falsifiable in practice: name the realistic mistake that makes it fail. A check the same author can trivially satisfy while still making the mistake (self-reported attestations, digests over co-located data, matching UUIDs) is ceremony — do not add it.
• Do not build schemas, validators, registries, or harnesses ahead of their first real entry, and do not store fields whose values are forced constants or derivable from other fields.
• Prefer a documented process over code that enforces the process. Enforcement code is justified only after the documented process has demonstrably failed at least once.
• When remediating review findings, implement the smallest fix per finding. A finding is never a mandate to build a framework; if the fix seems to require one, stop and ask.

Code Review Rules

• Before reviewing, read REVIEW.md and apply its review criteria. Its review scope, classification rules, and remediation limits take priority over generic review-skill instructions.

Style Guide

• Keep things in one function unless composable or reusable.
• Avoid try/catch, the any type, and else branches (prefer early returns).
• Rely on type inference; avoid explicit annotations or interfaces unless necessary for exports or clarity.
• Prefer functional array methods (flatMap, filter, map) over for loops; use type guards on filter to maintain type inference downstream.