Skip to main content

Adding tooling

The one rule for scripts, checks and workflows, with examples of what to add and what not to add.

A check or script is allowed only if it guards behavior that a user relies on, or a real attack path.

Process documentation is not security. A script that records that a process happened does not make the release safer; the protected environment, trusted publishing and the ruleset do that.

Ask before adding anything

  1. What breaks for a user, or which attack works, without it?
  2. Does an existing tool already do it (pnpm, Renovate, GitHub, npm, Changesets, TypeScript, the test runner)?
  3. Will someone maintain it when it breaks in a year?

If the first answer is vague or the second is "yes", do not add it.

Budget

The audit warns when a repository grows past these. They are signals, not hard limits:

  • about 20 package scripts;
  • about 1500 lines in scripts/;
  • three workflows: ci.yml, release.yml, preview.yml.

Worth adding

  • Tests of the public API, including type tests.
  • A packed-consumer test: install the packed tarball in a temporary project and import it. It proves the published package works, not just the source.
  • The changeset linter, because the changelog is what users read.
  • A docs build check that catches broken pages.
  • A check that guards a specific past bug users hit.

Not worth adding

  • Release ledgers, state machines, evidence cards, certification manifests or reconciliation scripts. Changesets, the npm environment and npm provenance already record what was released.
  • Custom dependency-policy checkers. pnpm enforces the quarantine and the build allowlist itself.
  • Scripts that verify action SHAs exist. Renovate maintains the pins, and GitHub fails the job on a bad SHA before any code runs.
  • Checks of other checks, or tests that a policy file has a certain shape.
  • Linting of documentation prose.
  • Procedure handbooks inside a repository (MAINTAINING.md, RELEASING.md). Link to this handbook instead.
  • A second CI workflow for one more check. Add a job to ci.yml. If a check really must not block pull requests (a slow weekly smoke test, for example), a separate workflow is fine; name it and say why in internals/decisions.md, and the audit accepts it.
  • Wrapper scripts around one command.
  • Custom Vercel preview workflows. Vercel's Git integration and the ignore command already do this.

Removing tooling

Removing a check that does not meet the rule needs no special approval. Say in the pull request what it guarded and why that is covered elsewhere.

Record the decision

When you add or remove something notable, add a line to internals/decisions.md:

md
- D7 (2026-09-27): Add a packed-consumer test — v2.3.0 shipped without `dist/runtime`.