♻️ Replace verify skill with an npm verify script

A skill duplicated AGENTS.md policy and only worked in Agent-Skills harnesses.
A bare top-level script is the repo-native affordance: every harness (and CI,
and a human) reads package.json#scripts as the source of truth. Add
`npm run verify` = `npm run check` + `test:unit` (tsc runs once, since check
already type-checks) as the one-shot whole-project correctness gate.

Delete .agents/skills/verify/SKILL.md. Document verify in README (Development +
a Tooling-decisions bullet + bare-command note in the prefix list), CONTRIBUTING
(feedback-tier table, "Before pushing", the bare-command paragraph, a "why these
splits" bullet), and AGENTS.md (test = fast iterating gate, verify = definition
of done; skill pointer removed).
This commit is contained in:
tmu committed 2026-09-05 21:46:59 +02:00
1 parent 3d0fe18d6a
commit da5ab79f9b
5 files changed
+14 -49

No files matched your search

+4
View File
@@ -8,6 +8,7 @@ Pattern matching for TypeScript/ESM environments (F#-style, not regex).
- **Test:** `npm run test`, `npm run test:ci`
- **Watch:** `npm run watch` (re-runs tests on file save; the earliest feedback tier)
- **Checks:** `npm run check`, `npm run fix`
- **Verify (definition of done):** `npm run verify` — `npm run check` + the unit suite in one shot; the whole-project correctness gate (excludes advisory `maintain`)
- **Maintenance (advisory):** `npm run maintain` — `knip` + `check-outdated`; run on a maintenance / update-deps branch, not part of the feature loop
- **Individual fixes:** `npm run fix:oxfmt`, `npm run fix:oxlint`
@@ -37,6 +38,7 @@ The choice and configuration of each tool above is the result of deliberate trad
- **`attw --profile esm-only`** is semantically correct: this package is intentionally ESM-only (no CommonJS shim), so CJS resolution scenarios are out of scope by design, not a bug.
- **The `publish:` prefix has no local aggregator.** `publint` and `attw` validate the _publishable artifact_ (`dist/`), not the source, and require a fresh build. They run only in the CI `publish` job immediately before `npm publish` — there is intentionally no `npm run publish`.
- **`check:tsc` runs first** in the `npm run check` chain so a type error short-circuits the rest (faster feedback than letting oxlint/oxfmt run and then failing on tsc at the end).
- **`verify` is the one-shot definition of done.** `npm run verify` composes `npm run check` with the unit suite (`test:unit`) into a single whole-project correctness gate, so a human or an agent reaches for one command instead of re-deriving the sequence. It deliberately uses `test:unit` (not `test`) because `check` already runs `check:tsc` — so tsc runs exactly once. It excludes `maintain` (advisory) by design. CI is not switched to it: the build job runs `check` + `test:ci` to also collect coverage.
- **The `check:` / `maintain:` split is correctness gates vs. advisory scans.** `npm run check` is the fast, offline, whole-project correctness ladder (`tsc → oxlint → oxfmt → cspell`) and can run anywhere, including the agent loop. `knip` (~4s, whole project) and `check-outdated` (~6.5s, queries the npm registry) are advisory, not correctness — a stale dependency or an unused export must not fail a feature PR — so they moved to `npm run maintain`, kept out of pre-commit, and run in CI as a **non-blocking** job (see `.github/workflows/ci.yml`). Note `check-outdated` exits non-zero whenever any dep is outdated, which is exactly why it must not gate merges.
- **The pre-commit hook sets the `LEFTHOOK_FILES` env var** to the staged-files list, and the affected scripts use `${LEFTHOOK_FILES:-<default>}` to default to the whole project when invoked manually. This keeps `package.json#scripts` as the single source of truth for the underlying commands — `lefthook.yml` only describes _what to run on which files_.
- **`tslib` and `type-fest` are deliberately not used.** `tslib` is a runtime helper for old ES3/ES5 targets (the project targets ES2024); `type-fest` was never imported. knip caught both.
@@ -66,6 +68,8 @@ Script names follow a prefix convention that signals _when_ they run:
- `maintain:*` — advisory repo-maintenance scans (dead code, dependency freshness). Aggregated by `npm run maintain`. Whole-project and/or network-bound, so **not** correctness gates: run on a maintenance branch, and in CI as a non-blocking job that reports without failing.
- `publish:*` — runs only at publish time, in the CI `publish` job (immediately before `npm publish`). There is no local `npm run publish` script — publishing is CI-only by policy.
Bare, prefix-free top-level commands are the entry points: `build`, `clean`, `check`, `fix`, `test`, `watch`, `maintain`, and `verify`. `verify` (`check` + `test:unit`) is the one-shot "whole-project correctness" gate; `maintain` is the advisory counterpart that never gates a merge.
## Contributing
For maintainer and contributor docs — the script prefix convention, the feedback-tier system, the rules the tools don't enforce, and the publishing workflow — see [CONTRIBUTING.md](./CONTRIBUTING.md). AI coding agents: your entry point is [AGENTS.md](./AGENTS.md), which points back to CONTRIBUTING.md.