plumbbob 0.9.3 → 0.10.0

package/node_modules/checkride/LICENSE

@@ -1,21 +1,201 @@
-MIT License
-
-Copyright (c) 2026 Rob McLarty
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Rob McLarty
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/node_modules/checkride/README.md

@@ -2,9 +2,20 @@
 
 # checkride
 
-**An agent harness for TypeScript repositories**, delivered as one npm package.
-It gives an LLM agent two things it otherwise lacks: a definition of done, and
-lanes to stay inside.
+**One command that tells a coding agent — and you — when the work is actually
+done.**
+
+checkride is an npm package that runs your whole verification pipeline as a
+single command (`pnpm check`) whose exit code is the verdict, and mechanically
+enforces module boundaries so parallel changes stay out of each other's way.
+Together those give an LLM agent the two things it otherwise lacks: a
+definition of done, and lanes to stay inside.
+
+It is built first for TypeScript, but it is not TypeScript-only: built-in
+checks stand down when their tool isn't in the repo, and custom checks run any
+command — so the same gate works for a plain-JavaScript package, a
+mixed-language monorepo, or a different ecosystem entirely (delivered through
+npm either way, for now).
 
 ## The thesis
 
@@ -15,19 +26,25 @@ both halves of that problem.
    types, lint, structure, dead code, tests, docs, links, spelling. **Exit 0
    means the work is complete.** Agents stop guessing; humans stop re-reviewing
    half-finished work.
-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. 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.
-
-The consumer of the output is an LLM, so checkride never normalizes diagnostics
-into a common format. Each tool writes its own raw JSON to `.check/`; the agent
-reads whatever the tool emits. That deletes the layer that makes every prior
-meta-runner expensive to extend.
+2. **Structured boundaries.** Code is organized into modules with narrow
+   public surfaces. In the default layout, a module starts as a single file;
+   when it grows internals worth hiding, it becomes a folder whose only public
+   surface is its `index.ts`, and sibling modules import that index — never the
+   internals. (These are [**deep modules**](./docs/deep-modules.md) —
+   Ousterhout's term, from *A Philosophy of Software Design*, for a small
+   interface hiding a substantial implementation.) checkride enforces this
+   mechanically, which keeps each
+   change inside one module's boundary and lets humans and agents work in
+   parallel with minimal merge conflicts. Deep modules are checkride's default
+   convention, not a hardcoded one — the rules are swappable ast-grep files in
+   your repo, and the same slot enforces boundaries in other conventions and
+   languages (see [Conventions](#conventions)).
+
+One design choice to know up front: because the consumer of the output is an
+LLM, checkride never normalizes diagnostics into a common format. Each tool
+writes its own raw JSON to `.check/`, and the agent reads whatever the tool
+emits. Skipping normalization deletes the adapter-maintenance layer that makes
+traditional run-all-my-tools wrappers expensive to extend.
 
 ## Install
 
@@ -49,14 +66,34 @@ pnpm install
 pnpm check
 ```
 
-Either way — `init` auto-detects which case it is in — it writes a
-`"check": "checkride"` alias, so daily usage is `pnpm check`
+Both paths end in the same place — `init` auto-detects which case it is in.
+It writes a `"check": "checkride"` script 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 all of this — alias, stanza, and hook —
-to a repo you already set up with `checkride agent-setup`.
+stanza stating the "exit 0 = done" rule, and **hooks** in your agent harness's
+config — `.claude/settings.json` for Claude Code, `.cursor/hooks.json` for
+Cursor. Three of them: a stop gate (a checkride-owned script that runs your
+detected package manager's `run check --strict --digest` and blocks an agent
+from finishing while the pipeline is red), an edit marker so turns that touched
+no files skip the gate, and a guard that denies edits to
+`checkride.baseline.json` and `.check/**`. Select hooks with `--hook <a,b>`
+(gate | dirty | protect), harnesses with `--harness <a,b>` (claude | cursor;
+detected by default), skip the hooks with `--no-hook`, or take an installed one
+back out with `--remove-hook <a,b>`. To add all of this — alias, stanza, hooks,
+and the Cursor skills — to a repo you already set up, run
+`checkride agent-setup`.
+
+Re-running either command refreshes the stanza in place, but never behind your
+back: the marker carries a hash of what checkride wrote, so a stanza you have
+since edited stops the run (exit 2) instead of being overwritten. Keep
+repo-specific additions outside the markers, where nothing rewrites them — or
+pass `--force` to discard the edits and refresh. A stanza written before the hash
+existed is matched against the wordings checkride released, so upgrading is not
+itself mistaken for an edit.
+
+To add or remove a hook on its own, use `checkride hooks add <a,b>` /
+`checkride hooks remove <a,b>`. It writes only the harness config and the
+generated scripts, and never reads or writes AGENTS.md — managing a hook is not
+managing your contract file, and an edited stanza does not stand in its way.
 
 ## Docs
 
@@ -76,9 +113,21 @@ Task-focused guides live in [docs/](./docs/README.md):
 - [The contract](./docs/contract.md) — the surfaces consumers may rely on:
   exit codes, the `summary.json` schema discipline, flags, exports, and the
   pin policy.
+- [The Claude Code plugin](./docs/plugin.md) — the bundled `/checkride:check`
+  and `/checkride:qa` skills: install, what each one reads, and what they
+  deliberately do not do.
+- [Cursor](./docs/cursor.md) — what `agent-setup` writes for Cursor, where
+  Cursor's hook API differs from Claude Code's, and the assumptions not yet
+  verified against a live Cursor.
 - [Reliability](./docs/reliability.md) — why checkride is safe to build a
   gate on.
 
+Runnable counterparts live in [examples/](./examples/): standalone projects you
+can install and run on their own, each demonstrating one thing — what an agent
+reads when the gate is red, or how a repo with existing debt adopts checkride
+without a cleanup project first. Each one declares the run it expects, and the
+end-to-end suite asserts it on every push.
+
 The rest of this README is the reference: the command surface, the pipeline
 model, the `.check/` output contract, configuration, and the baseline.
 
@@ -98,13 +147,30 @@ checkride init         Set up a project (new or existing — auto-detected).
   --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
+  --hook <a,b> write only these hooks (gate | dirty | protect)
+  --no-hook    skip writing the agent hooks
+  --remove-hook <a,b>  remove these installed hooks (entry + generated script)
+  --harness <a,b> write them for these harnesses (claude | cursor; default: detected)
   --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 "check" alias, AGENTS.md stanza + Stop hook to a repo.
-  --no-hook    skip the Stop hook (write only the stanza)
+checkride recover      Rebuild checkride.baseline.json candidates from git history
+                       and restore one (bare `recover` lists them with deltas).
+  --pick <n|sha|union> apply a candidate — additive union with the current file
+  --exact      write the picked snapshot verbatim instead of the union
+  --dry-run    preview the per-slot delta; write nothing
+  --depth <n>  commits of file history to walk (default 25)
+checkride agent-setup  Add the "check" alias, AGENTS.md stanza + agent hooks to a repo.
+  --hook <a,b> write only these hooks (gate | dirty | protect)
+  --no-hook    skip the hooks (write only the stanza)
+  --remove-hook <a,b>  remove these installed hooks; with --no-hook, remove only
+  --harness <a,b> which harnesses to write for (claude | cursor; default: detected)
+  --force      refresh a stanza that has local edits (refused otherwise)
+checkride gate         Run the check script as a stop gate, answering a harness's
+                       hook protocol. The generated hook scripts invoke this.
+checkride triage       Triage a red gate: run it, then read .check/ as a bounded report.
+checkride qa           Read the quality artifacts a previous run left.
 ```
 
 During iteration, narrow the loop: `checkride --bail`, `checkride --only
@@ -118,8 +184,8 @@ default run leaves stdout empty.
 ## The pipeline: slots and adapters
 
 A **slot** is a role in the pipeline (order matters — cheapest first). An
-**adapter** is a concrete tool that fills a slot. There is one blessed default
-per slot; alternates are wired so checkride can run them, but `init` only
+**adapter** is a concrete tool that fills a slot. Each slot has one blessed
+default; alternates are wired so checkride can run them, but `init` only
 generates config for the blessed default.
 
 | Slot       | Role                                   | Blessed default     | Alternates       |
@@ -127,7 +193,7 @@ generates config for the blessed default.
 | `types`    | Type checking                          | `tsc --build`       | —                |
 | `format`   | Formatting (opt-in)                    | `prettier`          | `biome`          |
 | `lint`     | Linting                                | `oxlint`            | `biome`, `eslint`|
-| `struct`   | Structural rules (deep modules)        | `ast-grep`          | —                |
+| `struct`   | Structural rules (deep modules by default) | `ast-grep`      | —                |
 | `dead`     | Dead code, deps, cycles, boundaries    | `fallow` (dead-code)| `knip`           |
 | `dupes`    | Code duplication (opt-in)              | `fallow` (dupes)    | —                |
 | `health`   | Complexity / maintainability (opt-in)  | `fallow` (health)   | —                |
@@ -135,23 +201,40 @@ generates config for the blessed default.
 | `docs`     | Markdown lint                          | `markdownlint-cli2` | —                |
 | `links`    | Relative markdown links resolve        | built-in            | —                |
 | `spell`    | Spelling                               | `cspell`            | —                |
+| `prose`    | Writing style (opt-in)                 | `vale`              | —                |
 | `mutation` | Mutation testing (opt-in)              | `stryker`           | —                |
 | `security` | Dependency audit (opt-in)              | `pnpm audit`        | —                |
+| `build`    | Runs the consumer's build script (opt-in) | `<pm> run build` | —                |
 | `publint`  | Package publishing lint (opt-in)       | `publint`           | —                |
 | `attw`     | Type resolution across module systems (opt-in) | `attw --pack`| —                |
+| `pack`     | Tarball ships the right files (opt-in) | built-in            | —                |
+| `smoke`    | Built package imports cleanly (opt-in) | built-in            | —                |
+| `snippets` | Tagged doc fences type-check (opt-in)  | built-in (`tsc`)    | —                |
+
+Most of these tools you already know. The one unfamiliar name, `fallow`, is a
+Rust-native codebase-analysis tool covering dead code, duplication, and
+complexity; the [tools guide](./docs/tools.md) covers it and every other
+adapter.
 
 Zero-config: for each slot, checkride runs the first adapter whose config file
 exists, and skips slots with no detected tool. The core has **no runtime
 dependency** on any checked tool — it spawns `<pm> exec <tool>`; the project
 owns the pinned tool versions.
 
-**Opt-in slots** (`format`, `mutation`, `security`, `publint`, `attw`) stay out of the
+**Opt-in slots** (`format`, `dupes`, `health`, `prose`, `mutation`, `security`, `build`,
+`publint`, `attw`, `pack`, `smoke`, `snippets`) stay out of the
 default run so adopting checkride — or bumping its version — never turns a repo red on a
 check it didn't ask for. Turn one on with `--include <slot>` (or `--all`), or by **naming
 it in `checks`**: an explicit entry like `"format": "prettier"` opts the slot into every
-run. `checkride fix` then runs its write form (e.g. `prettier --write`) alongside the
+run. `checkride fix` then runs its write form (for example `prettier --write`) alongside the
 other fixers. `format` sits before `lint` so the tree is tidy before the linters look.
 
+To **configure a slot without opting it in** — say, give `attw` a `--profile` but keep it
+in the full sweep only — add `"optIn": true` to its entry: it stays out of the default run
+and runs solely under `--all`/`--include <slot>`. The same field demotes a normally default
+slot (or a heavy custom check like `test:integration`) to full-sweep-only; `"optIn": false`
+does the opposite, forcing a slot into the default run.
+
 `publint` and `attw` are the **library-publishing** pair — turn them on for a package you
 ship to npm to make "the published artifact is correct" part of your definition of done.
 `publint` lints `package.json`'s publishing surface (exports, files, types); `attw` runs
@@ -225,6 +308,36 @@ To debug a failure: read `summary.json` to find the failing slot, then read that
 slot's raw output for structured diagnostics. On a large repo, `--digest` writes
 `digest.md` as a capped starting point.
 
+## The Claude Code plugin
+
+The package root is also a [Claude Code](https://claude.com/claude-code) plugin
+— two skills that consume the contract above, bundled in the same npm package
+and versioned with it:
+
+```text
+/plugin marketplace add robmclarty/agent-tools
+/plugin install checkride@robmclarty
+```
+
+- **`/checkride:check`** — triage a red gate. It runs the repo's own `check`
+  script, branches on the promised 0/1/2 exit split, and names **one root cause**
+  plus what it is deliberately not reading. It covers the corners a summary read
+  by hand gets wrong — exit 2 versus exit 1, vacuous green, a narrow run's green,
+  `baselined` counts, `skipped` slots, `exit_code: -1`, stale artifacts — then
+  opens exactly one raw file.
+- **`/checkride:qa`** — read the quality signal. It folds `mutation.json`,
+  `dead.json`, `dupes.json` and `health.json` into a report under 8 kB, runs
+  nothing, and reports which dimensions were never measured rather than guessing
+  at them.
+
+Both are **readers**: no new command, no new flag, no config, no hook. They
+exist because reading `.check/` by hand is unbounded (`mutation.json` is 2.2 MB
+in this repo) and credulous (every run overwrites `summary.json`, so an
+`ok: true` on disk may describe three of seventeen slots from a while ago). The
+readers ship prebuilt in `dist/`, so installing the plugin needs no build step,
+and they run without it too — `node node_modules/checkride/dist/triage/cli.js`
+prints the same report. Full details in [docs/plugin.md](./docs/plugin.md).
+
 ## Configuration
 
 `checkride.config.json` is optional — add it only to deviate from the defaults:
@@ -246,12 +359,29 @@ slot's raw output for structured diagnostics. On a large repo, `--digest` writes
     },
     "licenses": {           // a custom check (runs last by default)
       "command": "node",
-      "args": ["scripts/check-licenses.mjs"]
+      "args": ["scripts/check-licenses.mjs"],
+      "description": "License audit",     // rendered beside the check in the output
+      "note": "Legal asked for this in RFC-114; drop it when the SBOM job lands."
     }
   }
 }
 ```
 
+### `description` vs `note`
+
+Two strings, deliberately not one. **`description`** is user-facing: it is the
+text a run prints beside the check in its status line and records in
+`.check/summary.json`, so it wants to be short. **`note`** is the opposite —
+maintainer commentary that never renders anywhere, the JSON-comment this file
+otherwise has no room for. Put "why is this check here", "revisit after the
+2.0 upgrade", or a ticket number in `note` and keep the output readable.
+
+`note` is accepted on any check entry — an adapter override (`{ "use": … }`) or
+a custom check (`{ "command": … }`) — and at the top level of the file for a
+note about the config as a whole. It is validated as a string (a typo is a
+config error, not silence) and then dropped: no code path carries it onto an
+adapter, so it cannot reach the CLI output or the summary.
+
 ### The `$schema` pointer
 
 The `"$schema"` pointer is optional but recommended: it turns on validation and
@@ -296,6 +426,10 @@ 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>`.
 
+For operating a preset across many repos — versioning it, rolling a rule out as
+a release, and automating the per-repo bump — see
+[Running a fleet with shared presets](./docs/presets.md).
+
 ### Timeouts
 
 A per-check timeout guards against a hung tool, and it is **on by default**: a
@@ -353,7 +487,13 @@ 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
+a red check. When a merge went badly anyway — entries deleted wholesale, or a
+file so mangled it no longer parses (a run says so on stderr and treats it as
+no baseline at all) — the run diagnoses what it can: a red run whose "new"
+findings were grandfathered until a recent commit prints a `hint:` line naming
+that commit. `checkride recover` then rebuilds candidate states from the
+file's git history and restores one additively; see `checkride recover --help`.
+**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`
@@ -386,13 +526,15 @@ 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.
+vitest, oxlint, ast-grep, and the rest walk the whole tree. checkride itself
+does no per-package orchestration and offers 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`:
+`init` scaffolds one **default** convention — [deep
+modules](./docs/deep-modules.md), whose boundaries are enforced by `ast-grep`
+(the `struct` slot) and `fallow`:
 
 - A module is a unit of encapsulation. A single file is a module; promote it to
   a folder with a barrel `index.ts` when it grows internals worth hiding — a
@@ -403,6 +545,23 @@ Module boundaries, enforced by `ast-grep` and `fallow`:
 - Named exports only; no classes; `.js` extensions on relative imports
   (NodeNext); tests colocated with the code they cover.
 
+None of this is hardcoded into checkride. The `struct` slot just runs whatever
+ast-grep rules live in your repo's `rules/` directory (the barrel rule is
+`rules/no-deep-sibling-import.yml`), so the convention is whatever those files
+encode:
+
+- **A different convention, same language.** Edit or replace the rules to match
+  how your repo is organized — public/private folders, a naming prefix, an
+  allowed-import list — and `struct` enforces the new shape unchanged.
+- **Another language.** ast-grep is polyglot; set each rule's `language`
+  (`typescript`, `python`, `go`, `rust`, …) and the same slot covers boundaries
+  there.
+- **Beyond ast-grep.** When a rule can't be expressed in ast-grep, or lives in
+  another ecosystem's tooling (`import-linter`, `depguard`, `dependency-cruiser`),
+  wire it as a [custom check](./docs/tools.md#when-to-write-a-custom-check).
+
+checkride ships an opinionated default; it does not lock you to it.
+
 ## Tested envelope
 
 Every push runs the full suite — unit, contract, and end-to-end (generated
@@ -444,4 +603,4 @@ every public type are re-exported too. The full surface is the package's
 
 ## License
 
-[MIT](./LICENSE)
+[Apache-2.0](./LICENSE)

package/node_modules/checkride/dist/__tests__/fixtures/released-stanzas.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The stanza body checkride actually shipped, one per distinct wording, taken
+ * verbatim from the release tags with `activeSlots = ['types', 'lint']`.
+ *
+ * These exist so the legacy registry in `init.ts` is pinned against real
+ * released output rather than against itself: a hash list can only be verified
+ * by the text it was computed from. Regenerate from git if a wording is ever
+ * found missing — `git show <tag>:src/init.ts` — but the set is closed, since
+ * every release from 0.10.1 stamps what it writes.
+ */
+export declare const RELEASED_STANZAS: readonly {
+    range: string;
+    body: string;
+}[];
+//# sourceMappingURL=released-stanzas.d.ts.map

package/node_modules/checkride/dist/__tests__/fixtures/released-stanzas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"released-stanzas.d.ts","sourceRoot":"","sources":["../../../src/__tests__/fixtures/released-stanzas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAKtE,CAAC"}

package/node_modules/checkride/dist/__tests__/fixtures/released-stanzas.js

@@ -0,0 +1,17 @@
+/**
+ * The stanza body checkride actually shipped, one per distinct wording, taken
+ * verbatim from the release tags with `activeSlots = ['types', 'lint']`.
+ *
+ * These exist so the legacy registry in `init.ts` is pinned against real
+ * released output rather than against itself: a hash list can only be verified
+ * by the text it was computed from. Regenerate from git if a wording is ever
+ * found missing — `git show <tag>:src/init.ts` — but the set is closed, since
+ * every release from 0.10.1 stamps what it writes.
+ */
+export const RELEASED_STANZAS = [
+    { range: "v0.1.1–v0.1.6", body: "## Checkride: the definition of done\n\n`pnpm check` is the single source of truth for \"done\". Exit 0 means the work is\ncomplete; any other exit code means it is not. Never claim a task is finished while\n`pnpm check` is red.\n\nWhen it fails:\n\n1. Read `.check/summary.json` to see which check failed.\n2. Read that check's raw output (`.check/<slot>.json` or `.check/<slot>.stdout.txt`).\n3. Fix the root cause, then re-run.\n\nTight feedback loops: `pnpm check --bail`, `pnpm check --only types,lint`, and\n`pnpm check --changed`.\n\n### Module boundaries\n\nA module is a unit of encapsulation. A single file is a module; promote it to a\nfolder with a barrel `index.ts` when it grows internals worth hiding. A folder\nmodule's `index.ts` is its only public surface — re-exports only, no logic. Import\nsiblings through `'../<sibling>/index.js'`, never their internals.\n\nNamed exports only; no classes; `.js` extensions on relative imports.\n\nActive checks in this repo: types, lint." },
+    { range: "v0.2.0–v0.7.0", body: "## Checkride: the definition of done\n\n`pnpm check` is the single source of truth for \"done\". Exit 0 means the work is\ncomplete; any other exit code means it is not. Never claim a task is finished while\n`pnpm check` is red.\n\nWhen it fails:\n\n1. Read `.check/summary.json` to see which check failed.\n2. Read that check's raw output (`.check/<slot>.json` or `.check/<slot>.stdout.txt`).\n3. Fix the root cause, then re-run.\n\nTight feedback loops: `pnpm check --bail`, `pnpm check --only types,lint`, and\n`pnpm check --changed`.\n\nIf a Claude Code Stop hook is configured (`.claude/settings.json`), it runs the full\n`pnpm check` as the final gate — so while iterating, prefer the narrow commands above\nand let the hook run the authoritative pipeline once at the end rather than running\nthe full check yourself every loop.\n\n### Baseline\n\nIf `checkride.baseline.json` is present, checkride grandfathers the diagnostics it\nlists: a slot is green as long as only baselined findings remain, while a genuinely\nnew diagnostic still fails it. Fixing a baselined finding prunes it from the file —\nthe ratchet, so the baseline only ever shrinks. Never add to the baseline to make a\ncheck pass; fix the finding.\n\n### Module boundaries\n\nA module is a unit of encapsulation. A single file is a module; promote it to a\nfolder with a barrel `index.ts` when it grows internals worth hiding. A folder\nmodule's `index.ts` is its only public surface — re-exports only, no logic. Import\nsiblings through `'../<sibling>/index.js'`, never their internals.\n\nNamed exports only; no classes; `.js` extensions on relative imports.\n\nActive checks in this repo: types, lint." },
+    { range: "v0.8.0–v0.9.6", body: "## Checkride: the definition of done\n\n`pnpm check` is the single source of truth for \"done\". Exit 0 means the work is\ncomplete; any other exit code means it is not. Never claim a task is finished while\n`pnpm check` is red.\n\nWhen it fails:\n\n1. Read `.check/summary.json` to see which check failed.\n2. Read that check's raw output (`.check/<slot>.json` or `.check/<slot>.stdout.txt`).\n3. Fix the root cause, then re-run.\n\nWith the checkride plugin installed, `/checkride:check` runs this procedure in full.\n\nTight feedback loops: `pnpm check --bail`, `pnpm check --only types,lint`, and\n`pnpm check --changed`.\n\nIf a Claude Code Stop hook is configured (`.claude/settings.json`), it runs the full\n`pnpm check` as the final gate — so while iterating, prefer the narrow commands above\nand let the hook run the authoritative pipeline once at the end rather than running\nthe full check yourself every loop.\n\n### Baseline\n\nIf `checkride.baseline.json` is present, checkride grandfathers the diagnostics it\nlists: a slot is green as long as only baselined findings remain, while a genuinely\nnew diagnostic still fails it. Fixing a baselined finding prunes it from the file —\nthe ratchet, so the baseline only ever shrinks. Never add to the baseline to make a\ncheck pass; fix the finding.\n\n### Module boundaries\n\nA module is a unit of encapsulation. A single file is a module; promote it to a\nfolder with a barrel `index.ts` when it grows internals worth hiding. A folder\nmodule's `index.ts` is its only public surface — re-exports only, no logic. Import\nsiblings through `'../<sibling>/index.js'`, never their internals.\n\nNamed exports only; no classes; `.js` extensions on relative imports.\n\nActive checks in this repo: types, lint." },
+    { range: "v0.10.0", body: "## Checkride: the definition of done\n\n`pnpm check` is the single source of truth for \"done\". Exit 0 means the work is\ncomplete; any other exit code means it is not. Never claim a task is finished while\n`pnpm check` is red.\n\nWhen it fails:\n\n1. Read `.check/summary.json` to see which check failed.\n2. Read that check's raw output (`.check/<slot>.json` or `.check/<slot>.stdout.txt`).\n3. Fix the root cause, then re-run.\n\n`pnpm exec checkride triage` runs this procedure in full and reads `.check/` for you\n(`/checkride:check` and `/checkride-check` are the same thing as a skill).\n\nTight feedback loops: `pnpm check --bail`, `pnpm check --only types,lint`, and\n`pnpm check --changed`.\n\nIf a stop-gate hook is configured (`.claude/settings.json` or `.cursor/hooks.json`),\nit runs the full `pnpm check` as the final gate — so while iterating, prefer the narrow\ncommands above and let the hook run the authoritative pipeline once at the end rather\nthan running the full check yourself every loop.\n\n### Baseline\n\nIf `checkride.baseline.json` is present, checkride grandfathers the diagnostics it\nlists: a slot is green as long as only baselined findings remain, while a genuinely\nnew diagnostic still fails it. Fixing a baselined finding prunes it from the file —\nthe ratchet, so the baseline only ever shrinks. Never add to the baseline to make a\ncheck pass; fix the finding.\n\n### Module boundaries\n\nA module is a unit of encapsulation. A single file is a module; promote it to a\nfolder with a barrel `index.ts` when it grows internals worth hiding. A folder\nmodule's `index.ts` is its only public surface — re-exports only, no logic. Import\nsiblings through `'../<sibling>/index.js'`, never their internals.\n\nNamed exports only; no classes; `.js` extensions on relative imports.\n\nActive checks in this repo: types, lint." },
+];
+//# sourceMappingURL=released-stanzas.js.map