plumbbob 0.8.14 → 0.8.18

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.8.14",
+  "version": "0.8.18",
   "description": "Attention-first build process — driver skills + a CLI that keep you the decider: guidance on the work, a latch on the record.",
   "author": { "name": "Rob McLarty", "email": "hello@robmclarty.com", "url": "https://robmclarty.com" },
   "homepage": "https://github.com/robmclarty/plumbbob#readme",

package/README.md

@@ -4,6 +4,12 @@
   <img src="hero.svg" alt="A row of plumb bobs of varying shapes hanging from strings" width="600">
 </p>
 
+<p align="center">
+  <a href="https://robmclarty.github.io/plumbbob/">Website</a> ·
+  <a href="https://robmclarty.github.io/plumbbob/docs.html">Docs</a> ·
+  <a href="https://robmclarty.github.io/plumbbob/api.html">API reference</a>
+</p>
+
 PlumbBob is a Claude Code plugin — twelve `/pb-*` skills and a small CLI — that runs
 LLM-assisted coding as a loop you control. You and the model settle the plan in a file
 *before* any code; then the model builds one small step at a time and **stops after

package/dist/lib/agents.js

@@ -327,7 +327,7 @@ function skipWarnings(heading, skipped) {
 // is the author's error and is refused loud. Slot *contents* stay lenient (D61): a
 // slot value may be one name or a list, and blanks/non-strings drop rather than
 // refuse, because bindings feed a spawn, not a git-gating parse.
-export function parseHarness(raw) {
+function parseHarness(raw) {
     if (!isObject(raw)) {
         return { ok: false, error: 'harness.json must be a JSON object.' };
     }

package/dist/lib/check.js

@@ -31,12 +31,15 @@ export async function detectGate(root) {
     }
 }
 // Checkride's always-on repo checks: the adapters its doctor reports even for
-// an EMPTY directory (links, the pnpm-audit security scan, and the
-// publint/attw package-shape probes). They exercise the repo's plumbing, not
-// its code — a gate made only of these green-lights every checkpoint while the
-// human believes their work is being checked. Coupled to checkride's built-in
-// set by construction; the doctor.test.ts probe pins the coupling.
-const ALWAYS_ON_ADAPTERS = ['links', 'pnpm-audit', 'publint', 'attw'];
+// an EMPTY directory — the built-in `links` slot, the pnpm-audit security
+// scan, the publint/attw package-shape probes, and (checkride 0.5.0's
+// publish bundle) the built-in pack/smoke/snippets slots, which resolve on any
+// package with no tool config of their own. They exercise the repo's plumbing
+// or its shipped artifact, not its code — a gate made only of these green-lights
+// every checkpoint while the human believes their work is being checked. Coupled
+// to checkride's built-in set by construction; the check.test.ts and
+// doctor.test.ts probes pin the coupling.
+const ALWAYS_ON_ADAPTERS = ['links', 'pnpm-audit', 'publint', 'attw', 'pack', 'smoke', 'snippets'];
 // The detection rule, shared by `start`'s probe and doctor's callout: some tool
 // slot beyond the always-on family has an adapter — i.e. checkride can see the
 // CODE (a tsconfig, a test runner, a linter…), not just the repo.

package/dist/verbs/finish.js

@@ -80,9 +80,11 @@ function buildDefaultScope(root, slug) {
 // `--body` reads the final-commit body from stdin (the single-quoted heredoc of
 // D34), so the pb-finish skill can compose a proportional close-out message. Returns
 // null when the flag is absent or stdin is empty — the commit then carries subject
-// only. A read error (no stdin attached) degrades to null rather than throwing.
+// only. Reading fd 0 blocks until EOF, which the heredoc supplies; a read error (no
+// stdin attached) degrades to null, and an interactive TTY — which would never send
+// EOF — skips the read instead of hanging (twin of checkpoint.ts's guard).
 function bodyArg(args) {
-    if (!args.includes('--body')) {
+    if (!args.includes('--body') || process.stdin.isTTY === true) {
         return null;
     }
     try {

package/node_modules/checkride/CHANGELOG.md

@@ -4,8 +4,235 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.2] - 2026-07-19
+
+### Internal
+
+- Split the release workflow into a gated `publish.yaml` (npm publish with
+  provenance, now paused behind a required-reviewer approval on the
+  `npm-publish` GitHub Environment) and a separate `release.yaml` (GitHub
+  Release from the CHANGELOG), matching the fascicle/plumbbob pattern so the
+  npm publish credential and the release-authoring permission never share a
+  job.
+
+## [0.5.1] - 2026-07-19
+
+### Added
+
+- **A GitHub Pages marketing site** under `site/` — a homepage pitching the
+  elevator case for checkride, a docs hub aggregating the existing
+  `docs/*.md` guides into a concise sidebar reference, and a full
+  CLI/config/programmatic API reference — plus the GitHub Actions workflow
+  that deploys it.
+- `docs/why.md` — the case for adopting checkride: what it's selling, the ROI
+  against ad-hoc scripts and task runners, and straight answers to the
+  objections that come up in an adoption conversation.
+
+## [0.5.0] - 2026-07-19
+
+### Contract
+
+- **The `order` field is now a first-class, promised scheduling surface.** A
+  config entry's `order` accepts a **number** — a wave, where distinct wave
+  numbers run in ascending order with a barrier between them, checks sharing a
+  number run concurrently, and decimals sequence steps within a wave (`1` before
+  `1.1`) — or one of `first`, `last`, `middle`, `single`, `any`. It is honored
+  on every object-form entry: a slot's `{ use, order }` and a custom check
+  alike. `first`/`last` keep their exact historical meaning, pinned by a
+  backward-compat contract test. See `docs/contract.md` §"Check ordering and
+  concurrency".
+- **Two deliberate default-placement changes**, both noted in `docs/contract.md`:
+  a config-only custom check with **no** `order` now defaults to `any` (the main
+  group) instead of the old implicit `last` — set `"order": "last"` to restore
+  the previous placement — and a catalogue-filling custom entry's `order`, which
+  earlier releases documented as ignored, is now **honored**. A sequential
+  default run is unaffected in verdicts and summary order; the difference is
+  visible only under concurrency or beside a numbered wave.
+- **New `--concurrency <n>` flag.** Sets the size of the pool that runs a wave's
+  checks concurrently (`1` = sequential; the default is a conservative cap
+  derived from the CPU count). `--bail` overrides it: the run goes fully
+  sequential and a one-line stderr note reports that `--concurrency` was ignored
+  (the combination is safe, just slower — not a usage error). Additive to the
+  flag contract and contract-tested.
+- **`total_duration_ms` is now the run's wall-clock duration.** Under
+  concurrency the summary's total is measured wall-to-wall rather than summed
+  across checks; the two are identical for any sequential run (including
+  `--bail`). The `checks` array stays in deterministic group order — the run's
+  scheduling sequence, never completion order. `schema_version` is unchanged.
+
+### Added
+
+- **A publish-ready bundle of four opt-in slots** that take the definition of
+  done past static publishing lint (`publint`, `attw`) and out to the shipped
+  artifact. Each is a built-in or runs the consumer's own `build`/`tsc`, so
+  enabling them adds **zero devDependencies**:
+  - **`build`** (wave 10) runs the consumer's `build` script, so the artifact
+    checks below inspect fresh output rather than a stale `dist/`. An opted-in
+    `build` on a repo with no build script stands down as a skip, never a red
+    check.
+  - **`pack`** (wave 20) packs the tarball with a dry-run and fails if a required
+    file (a resolved `exports`/`main`/`types`/`bin` target, or `README`) is
+    missing or a forbidden one (`src/`, tests, `.ts` sources — the
+    `dist/**/*.d.ts` declarations excepted) is shipped. npm/pnpm only; yarn/bun
+    report **unavailable** until a per-manager adapter lands, like `security`.
+  - **`smoke`** (wave 20) imports every `exports` entry of the built package
+    through its own resolution map and asserts each declared value export is live
+    at runtime — a liveness check, not a type check.
+  - **`snippets`** (wave 20 / `any`) type-checks the fenced code blocks tagged
+    `<!-- snippet: check -->` in `README.md` and `docs/*.md`. The default
+    `snippets` adapter checks against source; a second `snippets-dist` adapter
+    checks against the built `.d.ts`. A slot opted in with zero tagged fences is
+    a hard error.
+
+  All four are opt-in (`--all`, `--include`, or config), so a default run is
+  byte-for-byte unchanged. They **order themselves**: `build` at wave 10 precedes
+  `pack`/`smoke`/`snippets`/`publint`/`attw` at wave 20, so `checkride --all`
+  builds before it inspects the artifact with no ordering config. `checkride
+  init` on a library can scaffold the bundle.
+
+### Changed
+
+- **A dependency can now activate a slot, not just its config file.** Adapters
+  whose tool runs correctly with zero config — `oxlint` (lint), `knip` (dead),
+  `vitest` (test), `cspell` (spell), and `prettier` (the opt-in format slot) —
+  now also activate when the package appears in `dependencies`/`devDependencies`,
+  as a backup to the detect-file signal. A repo that installed one of these but
+  never wrote its config file gains that check on upgrade; `doctor` names which
+  signal matched. This widens the default run for those slots and is a
+  deliberate, noted behavior change.
+- **Checks now run concurrently within a wave by default.** The orchestrator
+  schedules the wave sequence — `first`s, the numeric line ascending (equal
+  values through a bounded pool, a barrier between distinct values), `single`s
+  exclusively, then `last`s — instead of strictly one-at-a-time cheapest-first.
+  `--bail` keeps the sequential fail-fast path. The catalogue ships ordered so
+  existing default runs produce the same verdicts and the same summary order as
+  before, only faster; `mutation` runs as a `single` (exclusive) because Stryker
+  saturates every core and races the real test run's cache.
+- **`mutation` now ships uncapped (`timeout: 0`) by default.** A real Stryker run
+  legitimately outlives the 600s per-check cap; because `mutation` is opt-in and
+  never part of the definition-of-done gate the cap protects, its adapter runs to
+  completion instead of tripping a timeout under `checkride --all`. Every other
+  slot keeps the safe-by-default cap; override per check or globally with
+  `timeout`.
+
+## [0.4.3] - 2026-07-18
+
+### Internal
+
+- Refactored for maintainability: decomposed high-complexity functions across
+  the orchestrator, `init`, `doctor`, `config`, and the baseline code into small
+  single-purpose helpers, extracted shared option/stanza helpers, and broke
+  internal import cycles. No change to runtime behavior or the public API.
+- Zeroed the project's grandfathered debt: cleared the `lint`, `dead`, `dupes`,
+  and `health` baselines and removed checkride's own `checkride.baseline.json`,
+  so the repo passes a full `pnpm check` with no suppressions.
+- The repo's own default `pnpm check` now also runs the `dupes` and `health`
+  slots. Mutation stays opt-in (`pnpm mutation`): a cold full pass has no warm
+  incremental cache in CI and would time out the gate.
+
+## [0.4.2] - 2026-07-18
+
+### Fixed
+
+- **The `dead` (fallow) slot now actually gates.** checkride ran fallow in JSON
+  mode, which exits `0` even with findings, so the slot reported ✔ while fallow
+  had real issues. checkride now reads fallow's JSON report and derives the
+  verdict from the issue count instead of the (unreliable) exit code — so the
+  slot fails `pnpm check` on new findings and passes only when clean or fully
+  baselined. An **unrecognized fallow report fails loudly** (explicit
+  "unsupported schema_version" / "unrecognized kind") rather than passing
+  silently.
+- **fallow ≥ 3.5 support.** The dead-code parser reads fallow's current
+  `schema_version` 7 JSON (2.x emitted schema 4 with an incompatible layout).
+  The pinned devDependency moves from `fallow@2.48.0` to `fallow@3.5.0`.
+
+### Added
+
+- **`checkride baseline` now grandfathers fallow findings.** A fingerprint
+  extractor keys each fallow finding by kind + file + symbol, so fallow slots
+  participate in `checkride.baseline.json` like `lint`/`struct`/`spell` (and
+  ratchet the same way). Repos that prefer fallow's native `--save-baseline`
+  suppression can still use it — see `docs/tools.md`.
+- **New opt-in `dupes` and `health` slots.** fallow's duplication and
+  complexity analyses are now first-class checks (`--include dupes,health` or
+  `"dupes": "fallow"` in config), each with gating and baselines. They stay
+  opt-in so adopting checkride never fails a repo on duplication/complexity it
+  never signed up for.
+
+## [0.4.1] - 2026-07-11
+
+### Internal
+
+- Docs refresh: updated the reported mutation score to 69% and bumped the README `$schema` example to v0.4.0.
+
+## [0.4.0] - 2026-07-11
+
+### Contract
+
+- **An unknown slot name is now a usage error.** An unrecognized slot in
+  `--only`, `--skip`, or `--include` (e.g. `checkride --only lints`) exits **2**,
+  naming the bad slot and the valid set (catalogue slots plus config
+  custom-check names). It previously matched nothing and exited **0** — a typo
+  could silently disable the gate, the worst vacuous green in a definition-of-done
+  check. See `docs/contract.md` §CLI.
+
+### Added
+
+- New-project `checkride init` refuses to overwrite existing files, listing
+  every collision, and writes nothing; `--force` overrides. Existing-project
+  mode (additive-only) is unchanged.
+- Per-command `--help` (`checkride init --help`, etc.); new-project `init` ends
+  by printing the next command to run; `checkride baseline` now rejects stray
+  flags instead of ignoring them.
+
+### Changed
+
+- `checkride init` scaffolds an exact checkride version (no caret), and the
+  README install uses `pnpm add -D -E checkride`, matching the pre-1.0
+  exact-pin policy consumers are told to follow.
+- Malformed consumer JSON (`.claude/settings.json`, a project `package.json`)
+  now produces an error naming the offending file instead of a bare stack trace.
+
+### Fixed
+
+- **Interrupts no longer orphan checks.** Ctrl-C (SIGINT) or SIGTERM on a
+  running `checkride` is forwarded to every in-flight check and group-kills its
+  whole process tree before exit, then re-raises so the shell still sees the
+  conventional signal exit (130/143). Since checks run in detached process
+  groups (for the timeout kill), a plain interrupt previously left them running.
+- `doctor` distinguishes a version probe that **timed out** from one that
+  **could not be parsed** (30s probe), so a slow `pnpm --version` is no longer
+  misdiagnosed.
+- `checkride init --baseline --dry-run` no longer writes a real
+  `checkride.baseline.json` — a dry run now truly writes nothing.
+- A timed-out check's whole process group is killed (wrapper-spawned
+  grandchildren included), and output is captured with a UTF-8 decoder so a
+  multibyte character split across read chunks survives intact.
+- `checkride fix` runs under the detected package manager (e.g. `npx` under
+  npm), matching the run path instead of assuming pnpm.
+- A slot's stale `.check/` artifacts are cleared before it re-runs, so a leaner
+  or empty run can't leave the previous run's output behind as authoritative.
+
+### Internal
+
+- Docs pass: README restructure linking all six `docs/` files and splitting the
+  existing-repo vs new-project install paths, getting-started/tools sync,
+  reconciliation of the "locked by `test/contract/`" claim with real tests, and
+  a batch of drift corrections.
+- Release automation: tag↔version guard on release, CI concurrency group,
+  security-only Dependabot; `publint` and `attw` added as dev checks and
+  dogfooded; explicit test timeouts for slow-spawn machines; npm publishing
+  switched to Trusted Publishing (OIDC).
+
 ## [0.3.0] - 2026-07-10
 
+### Contract
+
+- Three additions to the promised surfaces, each recorded in `docs/contract.md`
+  and locked by `test/contract/`: the `summary.json` `checks_run` field, the
+  `--strict` flag, and the `DEFAULT_TIMEOUT_SECONDS` export. (Heading added
+  retroactively — the full entries are under **Added** below.)
+
 ### Added
 
 - **Vacuous-green signal.** `summary.json` gains a top-level `checks_run` count
@@ -238,6 +465,13 @@ The first real release. (`0.0.0` was a name-claim placeholder.)
 - Flags: `--only`, `--skip`, `--bail`, `--json`, `--changed`, `--all`,
   `--include`.
 
+[0.5.2]: https://www.npmjs.com/package/checkride/v/0.5.2
+[0.5.1]: https://www.npmjs.com/package/checkride/v/0.5.1
+[0.5.0]: https://www.npmjs.com/package/checkride/v/0.5.0
+[0.4.3]: https://www.npmjs.com/package/checkride/v/0.4.3
+[0.4.2]: https://www.npmjs.com/package/checkride/v/0.4.2
+[0.4.1]: https://www.npmjs.com/package/checkride/v/0.4.1
+[0.4.0]: https://www.npmjs.com/package/checkride/v/0.4.0
 [0.3.0]: https://www.npmjs.com/package/checkride/v/0.3.0
 [0.2.1]: https://www.npmjs.com/package/checkride/v/0.2.1
 [0.2.0]: https://www.npmjs.com/package/checkride/v/0.2.0

package/node_modules/checkride/README.md

@@ -18,7 +18,9 @@ both halves of that problem.
 2. **Structured boundaries.** A module is an encapsulation boundary with a
    narrow public surface. When one grows internals worth hiding it becomes a
    folder whose only public surface is its `index.ts`, and siblings reach only
-   that index — never the internals. Enforced mechanically, boundaries keep
+   that index — never the internals. These are **deep modules** — Ousterhout's
+   term for a small interface hiding a substantial implementation (*A
+   Philosophy of Software Design*). Enforced mechanically, boundaries keep
    agents inside lanes and let humans and agents work in parallel with minimal
    merge conflicts.
 
@@ -29,33 +31,79 @@ meta-runner expensive to extend.
 
 ## Install
 
+For an **existing repository**, install checkride (exact-pinned — see the
+[pin policy](./docs/contract.md)) and let `init` adopt the tools you already
+have:
+
+```bash
+pnpm add -D -E checkride
+pnpm exec checkride init
+```
+
+For a **new project**, run `init` in an empty directory — no install first;
+`dlx` fetches checkride, and the generated `package.json` pins it:
+
 ```bash
-pnpm add -D checkride
-pnpm exec checkride init   # set up a project (new or existing, auto-detected)
+pnpm dlx checkride init --shape flat --name my-app
+pnpm install
+pnpm check
 ```
 
-`init` writes a `"check": "checkride"` alias, so daily usage is `pnpm check`
+Either way — `init` auto-detects which case it is in — it writes a
+`"check": "checkride"` alias, so daily usage is `pnpm check`
 regardless of the tool's name. It also writes the agent contract: an AGENTS.md
 stanza (the "exit 0 = done" rule) and a Claude Code **Stop hook** in
 `.claude/settings.json` that blocks an agent from finishing while the pipeline is
 red. The hook uses your detected package manager (`pnpm`/`npm`/`yarn`/`bun run
-check`); skip it with `--no-hook`, or add both to a repo you already set up with
-`checkride agent-setup`.
+check`); skip it with `--no-hook`, or add all of this — alias, stanza, and hook —
+to a repo you already set up with `checkride agent-setup`.
+
+## Docs
+
+Task-focused guides live in [docs/](./docs/README.md):
+
+- [Why checkride](./docs/why.md) — the case for adopting it: what it's
+  selling, the ROI versus ad-hoc scripts or a task runner, and answers to the
+  common objections.
+- [Getting started](./docs/getting-started.md) — prerequisites, adding
+  checkride to a project (new or existing), your first run, and the daily loop.
+- [Cheat sheet](./docs/cheatsheet.md) — one-screen reference for commands,
+  flags, npm-script aliases, and the `.check/` output files.
+- [Tools and installation](./docs/tools.md) — what each pipeline check runs,
+  and how to install a missing tool when `doctor` reports one.
+- [Running in CI](./docs/ci.md) — a copy-paste GitHub Actions recipe (and
+  npm/yarn/bun variants), and why gates should pass `--strict`.
+- [The contract](./docs/contract.md) — the surfaces consumers may rely on:
+  exit codes, the `summary.json` schema discipline, flags, exports, and the
+  pin policy.
+- [Reliability](./docs/reliability.md) — why checkride is safe to build a
+  gate on.
+
+The rest of this README is the reference: the command surface, the pipeline
+model, the `.check/` output contract, configuration, and the baseline.
 
 ## Commands
 
+The pipeline is a sequence of **slots** — roles like `types`, `lint`, `test` —
+each filled by an **adapter**, the concrete tool that runs it (the full
+catalogue is [below](#the-pipeline-slots-and-adapters)). The commands refer to
+both:
+
 ```text
 checkride              Run the default checks. Exit 0 pass / 1 fail / 2 error.
   --only <a,b>  --skip <a,b>  --bail  --json  --changed  --all  --include <a,b>
   --digest  --strict (zero checks running = exit 2 — use wherever checkride gates)
 checkride init         Set up a project (new or existing — auto-detected).
-  --shape flat|monorepo|hybrid  --name <n>  --scope <@s>  --license <id>  --dry-run
+  --shape flat|monorepo|hybrid  --name <n>  --scope <@s>  --license <id>  --author <a>
+  --add <a,b>  (existing mode) scaffold blessed configs for the named empty slots
   --baseline   (existing mode) grandfather current debt instead of disabling slots
+  --force      (new mode) overwrite existing files instead of refusing
   --no-hook    skip writing the Claude Code Stop hook
+  --dry-run    plan only; write nothing
 checkride doctor       Verify environment + every slot's status (read-only, exit 0/1).
 checkride fix          Run every active adapter's fix command (oxlint --fix, ...).
 checkride baseline     Record current diagnostics as a committed baseline.
-checkride agent-setup  Add the AGENTS.md stanza + Claude Code Stop hook to a repo.
+checkride agent-setup  Add the "check" alias, AGENTS.md stanza + Stop hook to a repo.
   --no-hook    skip the Stop hook (write only the stanza)
 ```
 
@@ -80,7 +128,9 @@ generates config for the blessed default.
 | `format`   | Formatting (opt-in)                    | `prettier`          | `biome`          |
 | `lint`     | Linting                                | `oxlint`            | `biome`, `eslint`|
 | `struct`   | Structural rules (deep modules)        | `ast-grep`          | —                |
-| `dead`     | Dead code, deps, cycles, boundaries    | `fallow`            | `knip`           |
+| `dead`     | Dead code, deps, cycles, boundaries    | `fallow` (dead-code)| `knip`           |
+| `dupes`    | Code duplication (opt-in)              | `fallow` (dupes)    | —                |
+| `health`   | Complexity / maintainability (opt-in)  | `fallow` (health)   | —                |
 | `test`     | Tests + coverage                       | `vitest`            | `jest`           |
 | `docs`     | Markdown lint                          | `markdownlint-cli2` | —                |
 | `links`    | Relative markdown links resolve        | built-in            | —                |
@@ -136,7 +186,7 @@ fields are additive-only under a given `schema_version`.
     "schema_version": 1,
     "timestamp": "…",
     "ok": true,
-    "checks_run": 8, // checks that actually executed; 0 + ok = vacuous green
+    "checks_run": 8, // checks that actually executed
     "total_duration_ms": 4200,
     "checks": [
       { "name": "lint", "adapter": "oxlint", "description": "…",
@@ -146,10 +196,11 @@ fields are additive-only under a given `schema_version`.
   ```
 
   `ok: true` with `checks_run: 0` means **nothing was verified** — every slot
-  sat out (no tool detected, disabled, or skipped). The run warns loudly on
-  stderr when that happens, and `--strict` turns it into exit 2, so a gate can
-  never mistake "nothing ran" for "everything passed". Anything that gates on
-  checkride (CI, commit hooks) should pass `--strict`.
+  sat out (no tool detected, disabled, or skipped). That state is a **vacuous
+  green**: a pass that verified nothing. The run warns loudly on stderr when it
+  happens, and `--strict` turns it into exit 2, so a gate can never mistake
+  "nothing ran" for "everything passed". Anything that gates on checkride (CI,
+  commit hooks) should pass `--strict`.
 
 - `<slot>.json` — the raw tool JSON when stdout parses as JSON; otherwise
   `<slot>.stdout.txt` / `<slot>.stderr.txt`. Tools that write their own files
@@ -161,10 +212,12 @@ runs with no baseline, so `schema_version` is unchanged.
 
 - `digest.md` — written only under `--digest`: a **token-bounded** Markdown
   excerpt of the *failing* slots, so an agent working through a big red repo
-  reads a capped index instead of every raw file. Each section lists the first few
+  reads a capped index instead of every raw file. Each section lists the first
   findings (reusing the baseline fingerprint extractors, or a tail of raw text
   for slots without one) and links the authoritative `.check/<slot>.json`, which
-  is never modified. It **truncates, never normalizes**; a green run leaves no
+  is never modified. The bound: **ten findings per slot, 8 kB overall** —
+  roughly two thousand tokens; past the cap, remaining failing slots are named
+  but not rendered. It **truncates, never normalizes**; a green run leaves no
   digest (any stale one is removed), so its presence always means "this run
   failed". It is a file, never stdout — the machine-output split holds.
 
@@ -178,14 +231,14 @@ slot's raw output for structured diagnostics. On a large repo, `--digest` writes
 
 ```jsonc
 {
-  "$schema": "https://raw.githubusercontent.com/robmclarty/checkride/v0.2.1/schema/checkride.config.schema.json",
+  "$schema": "https://raw.githubusercontent.com/robmclarty/checkride/v0.4.0/schema/checkride.config.schema.json",
   "extends": "@acme/checkride-preset", // inherit a shared preset, then override below
   "timeout": 1200,          // global per-check timeout in seconds (default: 600)
   "checks": {
     "format": "prettier",   // enable the opt-in format slot (blessed: prettier)
     "lint": "biome",        // pick an alternate adapter
     "spell": false,         // disable a slot
-    "test": { "use": "vitest", "timeout": 0, "changedArgs": ["--changed", "origin/master"] },
+    "test": { "use": "vitest", "timeout": 0, "changedArgs": ["--changed", "origin/main"] },
     "tidy": {           // a bespoke custom check that runs FIRST, ahead of the built-ins
       "command": "pnpm",
       "args": ["exec", "some-formatter", "--write"],
@@ -199,21 +252,15 @@ slot's raw output for structured diagnostics. On a large repo, `--digest` writes
 }
 ```
 
+### The `$schema` pointer
+
 The `"$schema"` pointer is optional but recommended: it turns on validation and
 autocompletion for `checkride.config.json` in editors that understand JSON
 Schema (VS Code and friends). `checkride init` writes a version-pinned pointer
 into the config it generates; the schema itself ships in the package at
 [`schema/checkride.config.schema.json`](./schema/checkride.config.schema.json).
 
-Use `"extends"` to inherit a shared preset — a file path (`"./base.json"`) or an
-installed package (`"@acme/checkride-preset"`), or an array of them to layer
-several. Bases merge left to right and your local config wins over all of them:
-objects deep-merge (so overriding one field of a check keeps the rest), while
-arrays and scalars replace outright — arrays are **not** concatenated. Pair it
-with `detect` above to publish one org-wide preset that stays safe across repos
-that don't all use the same tools. An `extends` that can't be found, or a config
-that extends itself in a loop, fails fast with
-`invalid checkride.config.json: <reason>`.
+### Custom checks
 
 A custom check (one keyed by a name that isn't a built-in slot) runs *after* the
 built-in catalogue by default. Set `"order": "first"` to run it ahead of every
@@ -227,6 +274,8 @@ enable it with `"format": "prettier"` and `checkride fix` writes formatting for
 The `order: "first"` custom-check hatch coexists with it, for a one-off formatter the
 slot doesn't cover; the slot didn't retire it.
 
+### Gating a custom check with `detect`
+
 Add `"detect": ["<file>", …]` to a custom check to gate it on marker files: it
 runs only when at least one listed file exists in the repo, and is skipped —
 skipped, not failed — otherwise. This keeps a shared config safe across repos
@@ -235,6 +284,20 @@ stands down instead of lighting up red. `detect` applies only to custom checks
 that run alongside the catalogue; a custom check that fills a built-in slot
 always runs.
 
+### Sharing presets with `extends`
+
+Use `"extends"` to inherit a shared preset — a file path (`"./base.json"`) or an
+installed package (`"@acme/checkride-preset"`), or an array of them to layer
+several. Bases merge left to right and your local config wins over all of them:
+objects deep-merge (so overriding one field of a check keeps the rest), while
+arrays and scalars replace outright — arrays are **not** concatenated. Pair it
+with `detect` above to publish one org-wide preset that stays safe across repos
+that don't all use the same tools. An `extends` that can't be found, or a config
+that extends itself in a loop, fails fast with
+`invalid checkride.config.json: <reason>`.
+
+### Timeouts
+
 A per-check timeout guards against a hung tool, and it is **on by default**: a
 definition-of-done gate that can hang forever fails its one job on the worst
 day. The default cap is a generous **600 seconds per check**; a check that hits
@@ -285,10 +348,22 @@ Once it exists, every normal run is **baseline-aware**:
 - Never add to the baseline to make a check pass; fix the finding, or re-run
   `checkride baseline` deliberately to re-grandfather.
 
+Two operational notes. **Merge conflicts:** the file is canonical (slots and
+keys are sorted), so parallel branches usually merge cleanly; when they do
+conflict, resolve by keeping both sides' entries and running a full
+`checkride` — the ratchet prunes anything already fixed, so an over-generous
+union self-heals, while a dropped entry that still fails simply resurfaces as
+a red check. **Deliberate re-baseline:** `checkride baseline` re-records
+*everything* currently failing — including brand-new debt you might rather
+fix — so treat re-running it as a reviewed change: do it deliberately (say,
+after adopting a stricter rule set) and read the `checkride.baseline.json`
+diff in the PR like code.
+
 Only slots whose tool has a fingerprint extractor participate (currently `lint` via
-oxlint, `struct` via ast-grep, `spell` via cspell); other slots (`types`, `dead`,
-`test`, …) never appear in the baseline. A crash or empty output is never masked —
-a slot only goes green when there are findings and all of them are grandfathered.
+oxlint, `struct` via ast-grep, `spell` via cspell, and the fallow slots `dead`/`dupes`/
+`health`); other slots (`types`, `test`, …) never appear in the baseline. A crash or
+empty output is never masked — a slot only goes green when there are findings and all
+of them are grandfathered.
 
 To adopt on an existing repo, `checkride init --baseline` grandfathers today's
 failing (fingerprintable) slots into the baseline and keeps them enabled, instead of
@@ -307,6 +382,14 @@ disable.
 
 Every generated shape is green out of the box — an end-to-end test enforces it.
 
+At runtime, checkride itself is workspace-agnostic: whatever the shape, it runs
+each tool **once, from the repo root** — one pipeline, one `.check/`. Workspace
+awareness comes from the tools' own configs, which is what the monorepo scaffold
+sets up: `tsc --build` follows the root tsconfig's project references, and
+vitest, oxlint, ast-grep, and the rest walk the whole tree. There is no
+per-package orchestration and no way to check a single package — narrow a run
+with `--only`/`--changed`, not per-directory.
+
 ## Conventions
 
 Module boundaries, enforced by `ast-grep` and `fallow`:
@@ -332,13 +415,33 @@ The promised surfaces (exit codes, `summary.json` shape, flags, exports) are
 locked by a dedicated [contract suite](./test/contract/) — see
 [docs/contract.md](./docs/contract.md). Beyond line coverage (enforced at 70%),
 the test suite is itself tested: Stryker mutation testing runs with a hard
-floor of 55; the current mutation score is **67%** (`pnpm mutation` to
+floor of 55; the current mutation score is **69%** (`pnpm mutation` to
 reproduce).
 
 See [AGENTS.md](./AGENTS.md) for the contract agents follow,
 [CONTRIBUTING.md](./CONTRIBUTING.md) for the release ritual, and
 [CHANGELOG.md](./CHANGELOG.md) for release notes.
 
+## Programmatic API
+
+The CLI is the primary interface, but every command is also a function. Import
+from the package root to run the pipeline inside your own tooling; the result
+carries the same summary written to `.check/summary.json`, plus the exit code the
+CLI would return:
+
+<!-- snippet: check -->
+```ts
+import { runChecks, type RunResult } from 'checkride';
+
+const result: RunResult = await runChecks({ cwd: process.cwd(), strict: true });
+process.exitCode = result.exitCode;
+```
+
+`runChecks` sits alongside `runInit`, `runDoctor`, `runFix`, and the
+`loadConfig`/`resolveChecks` pair; the adapter registry (`SLOTS`, `ADAPTERS`) and
+every public type are re-exported too. The full surface is the package's
+`exports`, and it is part of the [contract](./docs/contract.md).
+
 ## License
 
 [MIT](./LICENSE)