claude-code-safety-net

- Before filing an issue, read `CONTRIBUTING.md` and follow its reporting rules.
- 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, code comments, 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`.

## Windows verification

Windows behavior is verified on the `full-check-windows` CI job, from a disposable branch. Never push
a probe to a PR branch or `main`.

- Branch `tmp/<topic>-windows-probe` from `origin/main` in a `git worktree` under the scratchpad, then
  `git branch --unset-upstream` (a branch cut from `origin/main` tracks it).
- Red first: commit a `test.skipIf(process.platform !== 'win32')` test, push, run CI, and read the
  failure in the job's "Check source" step. Then commit the fix, push, and run CI again for green.
  Ignore the later "Reject stale generated artifacts" step; the pre-commit hook rebuilds `dist/`.
- `ci.yml` triggers on pushes to `main` and on PRs only, so a pushed probe branch runs nothing by
  itself. Start it with `gh workflow run ci.yml --ref <branch>`, then find the run with
  `gh run list --workflow ci.yml --branch <branch>`.
- Wait for the job with a background `until` loop on `gh run view <id> --json jobs`; foreground
  `sleep` is blocked.
- Do not bypass hooks. The pre-push hook runs the full `bun run check` (about 45s). Push from the
  main checkout, not the worktree.
- GitHub sometimes answers ref creation and workflow dispatch with HTTP 500. Retry in a background
  loop (it succeeded on the fifth attempt once). Only when the hook already passed on that exact
  commit may the retries use `LEFTHOOK=0`.
- After creating or removing a worktree or pushing from one, check `git config core.bare` in the
  main checkout. It was once found flipped to `true` (every git command then fails with "must be run
  in a work tree"); restore it with `git config core.bare false`.
- Clean up when done: `git worktree remove <path>` and `git branch -D <branch>`. The safety net
  blocks `git push origin --delete`, so ask the user to delete the remote branch.

## README

- `README.md` is the GitHub and npm landing page. It holds only what a newcomer needs before
  installing; everything else belongs to the docs site (`kenryu42/cc-safety-net-docs`), whose
  `docs-sync` skill documents each source commit after every release.
- Do not touch the README for a fix, behavior change, new option, version minimum, per-CLI
  install step, config key, or limitation. Docs-sync picks it up from the commit; a README
  paragraph duplicates it and goes stale.
- Edit the README only when something it already lists changes: a supported CLI (one table cell
  linking its Installation anchor), a headline capability (one Features bullet plus a docs link),
  or the Quick start commands.

## 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.
- Inline values used only once instead of naming them, unless the name says what would otherwise
  need a comment.
- Prefer `const` over `let`; use ternaries or early returns instead of reassignment.
- Avoid unnecessary destructuring; use dot notation to preserve context.

## Comments

- Do not write code comments. Say it in code: a clearer name, a named value, a type.
- Only three directives are allowed: a bare `/** @internal */`,
  `// oxlint-disable-next-line <rules> -- <reason>` and `// @ts-expect-error <reason>`.
- A fact about an external tool that code cannot express stays only when the maintainer adds it to
  `scripts/comment-allowlist.json`. Never add entries there yourself, just as you never add
  `ignoreIssues` entries to `knip.ts`. Deleting an entry whose comment is gone is fine.
- `bun run lint:comments`, part of `bun run check`, enforces this. To fix a failure, follow
  `.agents/skills/ccsn-no-comments/SKILL.md`.

## Knip

- Never add entries to `ignoreIssues` in `knip.ts` — it suppresses real problems instead of fixing them. The only valid use case is generated files that aren't under source control.
- When knip flags unused exports, fix the root cause:
  1. **Dead exports** (no consumers anywhere) — unexport or delete the code entirely.
  2. **Test-only exports** — add `/** @internal */` JSDoc above the export. Knip runs in `--production` mode (see `package.json`), so test files are excluded from analysis and test-only exports must be tagged.
  3. **Barrel file re-exports** — if nothing imports a name via the barrel, remove it from the barrel. Consumers that need it should import directly from the submodule.

More agent context in kenryu42/claude-code-safety-net

6 other files this repository gives its agents.