plumbbob 0.5.4 → 0.6.1

package/dist/verbs/status.js

@@ -2,8 +2,10 @@
 // Read-only, always exits 0. Skills pre-inject this output to gate their own
 // behavior, so the `NO ACTIVE SESSION` sentinel is kept exact.
 import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { findRepoRoot } from "../lib/git.js";
-import { buildLogPath, checkpointsPath, hasSession, inSpike, intentPath, listBuilds, resolveBuild, stepPath, } from "../lib/sidecar.js";
+import { SLOTS, readHarnessFile, resolveAgent, } from "../lib/agents.js";
+import { buildFolder, buildLogPath, checkpointsPath, hasSession, inSpike, intentPath, listBuilds, resolveBuild, stepPath, } from "../lib/sidecar.js";
 import { formatOrientation, orient } from "../lib/orient.js";
 function readOr(path) {
     try {
@@ -38,6 +40,66 @@ export function status(cwd, args = []) {
         inFlight: /^\d+$/.test(inFlightRaw) ? Number(inFlightRaw) : null,
         spiking: inSpike(root, slug),
     });
-    process.stdout.write(`${formatOrientation(orientation)}\n`);
+    const lines = [formatOrientation(orientation), ...harnessSection(root, slug)];
+    process.stdout.write(`${lines.join('\n')}\n`);
     return 0;
 }
+// The active build's harness bindings (D48): the agents bound to each slot, per
+// `defaults` and per step, with a warning on any bound agent that does not resolve
+// (D54 — a teammate can lack a personal agent and the loop still works). Returns []
+// when the build has no harness.json (a clean no-op) or the file binds nothing, so
+// the dashboard stays uncluttered for builds that use no agents. A broken
+// harness.json surfaces its parse error rather than hiding.
+function harnessSection(root, slug) {
+    const parsed = readHarnessFile(join(buildFolder(root, slug), 'harness.json'));
+    if (parsed === null)
+        return [];
+    if (!parsed.ok)
+        return ['', `harness bindings: ✗ ${parsed.error}`];
+    const harness = parsed.harness;
+    const rows = [];
+    for (const frag of slotFragments(harness.defaults))
+        rows.push(`  defaults · ${frag}`);
+    for (const [n, binding] of [...harness.steps.entries()].sort((a, b) => a[0] - b[0])) {
+        for (const frag of slotFragments(binding.bindings))
+            rows.push(`  step ${n} · ${frag}`);
+        if (binding.note.length > 0)
+            rows.push(`  step ${n} · note: ${binding.note}`);
+    }
+    if (rows.length === 0)
+        return [];
+    return ['', 'harness bindings:', ...rows, ...bindingWarnings(root, harness)];
+}
+// Render a SlotBindings as `slot: name1, name2` fragments, in slot order. A slot
+// bound to no agents (an explicit "override to none") is omitted — there is nothing
+// to run and nothing to name.
+function slotFragments(bindings) {
+    const out = [];
+    for (const slot of SLOTS) {
+        const names = bindings[slot];
+        if (names !== undefined && names.length > 0)
+            out.push(`${slot}: ${names.join(', ')}`);
+    }
+    return out;
+}
+// A warning line for every distinct agent bound anywhere in the harness that does
+// not resolve (D54). Deduped and sorted so the report is stable; a name bound in
+// several slots warns once.
+function bindingWarnings(root, harness) {
+    const names = new Set();
+    for (const slot of SLOTS)
+        for (const name of harness.defaults[slot] ?? [])
+            names.add(name);
+    for (const binding of harness.steps.values()) {
+        for (const slot of SLOTS)
+            for (const name of binding.bindings[slot] ?? [])
+                names.add(name);
+    }
+    const warnings = [];
+    for (const name of [...names].sort()) {
+        const res = resolveAgent(root, name);
+        if (!res.ok)
+            warnings.push(`  ⚠ bound agent "${name}" does not resolve — ${res.error}`);
+    }
+    return warnings;
+}

package/node_modules/checkride/CHANGELOG.md

@@ -0,0 +1,139 @@
+# Changelog
+
+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.1.6] - 2026-06-30
+
+### Added
+
+- Custom checks (config entries keyed by a name outside the built-in slot
+  catalogue) accept an `order` field: `"order": "first"` runs the check ahead
+  of every built-in, `"last"` (the default) keeps it after them. Lets a
+  formatter such as `biome format --write` normalize the tree before the
+  linters and tests run. Within each group, config key order is preserved.
+
+## [0.1.5] - 2026-06-30
+
+### Added
+
+- `checkride --help` / `-h` and `checkride --version` / `-V`.
+- Optional per-check timeout, off by default: set a global `timeout` (seconds)
+  in `checkride.config.json` or override it per check; `0` exempts a slot. A hung
+  check is killed and reported as failed with its elapsed duration.
+
+### Changed
+
+- Supported Node floor lowered to 22.18 (the minimum required by the cspell and
+  oxlint toolchain). `init` and `doctor` reflect it, and CI now runs a Node
+  22 + 24 matrix.
+- Unknown commands and bad flags print a concise message plus a `checkride
+  --help` pointer; a malformed `checkride.config.json` now reports `invalid
+  checkride.config.json: <reason>` instead of a raw parser error.
+- `prepublishOnly` runs the test suite before publishing, not just the build.
+
+### Internal
+
+- `package.json` gains `repository`, `homepage`, and `bugs` for the npm page.
+- README and cheat sheet document the stderr/stdout stream split; README gains a
+  header image.
+
+## [0.1.4] - 2026-06-26
+
+### Added
+
+- Onboarding and reference documentation under `docs/`: a getting-started guide,
+  a command and flag cheat sheet, and a tool-installation reference (system
+  prerequisites plus how to install a missing slot tool such as fallow or
+  ast-grep). Includes a "Working with agents" section covering how Claude Code
+  and other agents adopt the `pnpm check` contract via the AGENTS.md stanza, and
+  how to enforce it with a Stop hook without double-running the pipeline.
+
+### Internal
+
+- Removed the v1 build plan now that it is fully implemented.
+
+## [0.1.3] - 2026-06-17
+
+### Changed
+
+- `checkride doctor` now reports every catalogue slot with its enablement —
+  `default`, `opt-in`, `disabled`, or `unavailable` — instead of listing only
+  the slots the default run executes. Opt-in slots (mutation, security),
+  config-disabled slots, and slots with no detected tool are no longer silently
+  omitted; each shows how to enable it. Exit-code behavior is unchanged: only
+  default slots are required, so the newly surfaced slots never fail the report.
+
+## [0.1.2] - 2026-06-12
+
+### Fixed
+
+- The CLI now runs when invoked through its installed bin — `pnpm exec
+  checkride`, `npx checkride`, and the generated `pnpm check` alias. The 0.1.1
+  entrypoint guard compared unresolved paths, so launching via the
+  `node_modules/.bin/checkride` symlink (how every consumer runs it) silently
+  exited 0 without running any checks.
+
+### Internal
+
+- Added an end-to-end regression test that invokes the CLI through a bin
+  symlink and asserts it behaves identically to a direct invocation.
+- Bumped the CI GitHub Actions to their node24-runtime majors
+  (`actions/checkout`, `actions/setup-node`, `pnpm/action-setup`), clearing the
+  Node 20 deprecation warning.
+
+## [0.1.1] - 2026-06-12
+
+### Added
+
+- `checkride init` for existing projects gained `--add <slots>`: it scaffolds
+  blessed-default configs for the named empty slots (lint, spell, struct, test,
+  docs, types, dead) and adopts them in the same run, never clobbering an
+  existing config.
+- `checkride init` for existing projects now writes the `check: checkride` alias
+  to `package.json` when it is missing — additive, and never overwriting an
+  existing `check` script.
+
+### Internal
+
+- Flattened checkride's own source to named single-file modules with a
+  logic-free barrel `index.ts`, relocated unit tests to `src/__tests__/`, and
+  added a `no-logic-in-barrel` structural rule. The deep-modules folder pattern
+  still ships to consumers unchanged.
+- Added Stryker mutation testing, strengthened weak tests, and gitignored the
+  regenerated `stryker.incremental.json` cache.
+- Added a GitHub Actions workflow running `pnpm check` plus the e2e suite.
+- Added a `/version` release skill for cutting tagged releases.
+- Reconciled the module-boundary documentation with the flat source layout.
+
+## [0.1.0] - 2026-06-11
+
+The first real release. (`0.0.0` was a name-claim placeholder.)
+
+### Added
+
+- `checkride` run command: the verification pipeline across ten slots (types,
+  lint, struct, dead, test, docs, links, spell, plus opt-in mutation and
+  security), writing raw per-tool output and an aggregate `.check/summary.json`
+  (`schema_version: 1`).
+- Adapter registry with blessed defaults (`tsc`, `oxlint`, `ast-grep`,
+  `fallow`, `vitest`, `markdownlint-cli2`, built-in links, `cspell`, `stryker`,
+  `pnpm audit`) and wired alternates (`biome`, `eslint`, `knip`, `jest`).
+- Zero-config detection plus `checkride.config.json` for overrides, disabled
+  slots, adapter swaps, and custom checks.
+- `checkride init` for new projects (flat / monorepo / hybrid shapes, each green
+  out of the box) and existing projects (additive adoption, idempotent AGENTS.md
+  stanza, failing slots disabled with a report).
+- `checkride doctor` (read-only environment + tooling verification) and
+  `checkride fix` (runs every active adapter's fix command).
+- Flags: `--only`, `--skip`, `--bail`, `--json`, `--changed`, `--all`,
+  `--include`.
+
+[0.1.6]: https://www.npmjs.com/package/checkride/v/0.1.6
+[0.1.5]: https://www.npmjs.com/package/checkride/v/0.1.5
+[0.1.4]: https://www.npmjs.com/package/checkride/v/0.1.4
+[0.1.3]: https://www.npmjs.com/package/checkride/v/0.1.3
+[0.1.2]: https://www.npmjs.com/package/checkride/v/0.1.2
+[0.1.1]: https://www.npmjs.com/package/checkride/v/0.1.1
+[0.1.0]: https://www.npmjs.com/package/checkride/v/0.1.0

package/node_modules/checkride/LICENSE

@@ -0,0 +1,21 @@
+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.

package/node_modules/checkride/README.md

@@ -0,0 +1,179 @@
+![A flight instructor evaluating a student pilot during a simulator checkride](./checkride_photo.png)
+
+# 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.
+
+## The thesis
+
+Agents are good at writing code and bad at knowing when to stop. Checkride fixes
+both halves of that problem.
+
+1. **A definition of done.** One command runs the whole verification pipeline —
+   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. 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.
+
+## Install
+
+```bash
+pnpm add -D checkride
+pnpm exec checkride init   # set up a project (new or existing, auto-detected)
+```
+
+`init` writes a `"check": "checkride"` alias, so daily usage is `pnpm check`
+regardless of the tool's name.
+
+## Commands
+
+```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>
+checkride init         Set up a project (new or existing — auto-detected).
+  --shape flat|monorepo|hybrid  --name <n>  --scope <@s>  --license <id>  --dry-run
+checkride doctor       Verify environment + every slot's status (read-only, exit 0/1).
+checkride fix          Run every active adapter's fix command (oxlint --fix, ...).
+```
+
+During iteration, narrow the loop: `checkride --bail`, `checkride --only
+types,lint`, `checkride --changed`.
+
+Output streams: human-readable progress goes to stderr; stdout carries machine
+output only — the summary JSON under `--json`, mirroring `.check/summary.json`.
+So `checkride --json` produces clean JSON on stdout that is safe to pipe, and the
+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
+generates config for the blessed default.
+
+| Slot       | Role                                   | Blessed default     | Alternates       |
+| ---------- | -------------------------------------- | ------------------- | ---------------- |
+| `types`    | Type checking                          | `tsc --build`       | —                |
+| `lint`     | Linting                                | `oxlint`            | `biome`, `eslint`|
+| `struct`   | Structural rules (deep modules)        | `ast-grep`          | —                |
+| `dead`     | Dead code, deps, cycles, boundaries    | `fallow`            | `knip`           |
+| `test`     | Tests + coverage                       | `vitest`            | `jest`           |
+| `docs`     | Markdown lint                          | `markdownlint-cli2` | —                |
+| `links`    | Relative markdown links resolve        | built-in            | —                |
+| `spell`    | Spelling                               | `cspell`            | —                |
+| `mutation` | Mutation testing (opt-in)              | `stryker`           | —                |
+| `security` | Dependency audit (opt-in)              | `pnpm audit`        | —                |
+
+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 `pnpm exec <tool>`; the project
+owns the pinned tool versions.
+
+## The `.check/` contract
+
+Every run writes to `.check/`. This is a public API for agents; treat schema
+changes as breaking.
+
+- `summary.json` — the aggregate report:
+
+  ```jsonc
+  {
+    "schema_version": 1,
+    "timestamp": "…",
+    "ok": true,
+    "total_duration_ms": 4200,
+    "checks": [
+      { "name": "lint", "adapter": "oxlint", "description": "…",
+        "ok": true, "exit_code": 0, "duration_ms": 470, "output_file": "lint.json" }
+    ]
+  }
+  ```
+
+- `<slot>.json` — the raw tool JSON when stdout parses as JSON; otherwise
+  `<slot>.stdout.txt` / `<slot>.stderr.txt`. Tools that write their own files
+  (vitest `--outputFile`, stryker) keep doing so.
+
+To debug a failure: read `summary.json` to find the failing slot, then read that
+slot's raw output for structured diagnostics.
+
+## Configuration
+
+`checkride.config.json` is optional — add it only to deviate from the defaults:
+
+```jsonc
+{
+  "timeout": 600,           // global per-check timeout in seconds (off by default)
+  "checks": {
+    "lint": "biome",        // pick an alternate adapter
+    "spell": false,         // disable a slot
+    "test": { "use": "vitest", "timeout": 0, "changedArgs": ["--changed", "origin/master"] },
+    "format": {             // a custom check that runs FIRST, ahead of the built-ins
+      "command": "pnpm",
+      "args": ["exec", "biome", "format", "--write"],
+      "order": "first"
+    },
+    "licenses": {           // a custom check (runs last by default)
+      "command": "node",
+      "args": ["scripts/check-licenses.mjs"]
+    }
+  }
+}
+```
+
+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
+built-in check instead — handy for a formatter like `biome format --write` that
+should normalize the tree before the linters and tests look at it. `"order":
+"last"` is the explicit form of the default. Within each group, custom checks
+run in the order they appear in the config.
+
+A per-check timeout guards against a hung tool. It is **off by default** — a cap
+short enough to catch a hang on a small repo is short enough to kill a legitimate
+slow run on a large one, and CI job timeouts already bound true hangs. Set a
+global `timeout` (seconds) to opt in, override it per check (`"timeout": <n>`),
+and use `"timeout": 0` to exempt a slot. Leave `dead`, `test`, and `mutation`
+generous or uncapped — they legitimately run long.
+
+## Project shapes
+
+`init` scaffolds three shapes. They share everything except `tsconfig.json`,
+`fallow.toml`, and `pnpm-workspace.yaml`:
+
+- **flat** — a single package using the deep-modules layout under `src/`.
+- **monorepo** — a pnpm workspace of `apps/*` (deployable leaves) and `libs/*`
+  (reusable internals); libs may not import from apps.
+- **hybrid** — a root app in `src/` plus internal packages under `packages/*`.
+
+Every generated shape is green out of the box — an end-to-end test enforces it.
+
+## Conventions
+
+Module boundaries, enforced by `ast-grep` 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
+  one-file folder is just ceremony.
+- A folder module's `index.ts` is its only public surface: it re-exports, it
+  holds no logic. Siblings import it via `'../<sibling>/index.js'`, never its
+  internals.
+- Named exports only; no classes; `.js` extensions on relative imports
+  (NodeNext); tests colocated with the code they cover.
+
+See [AGENTS.md](./AGENTS.md) for the contract agents follow, and
+[CHANGELOG.md](./CHANGELOG.md) for release notes.
+
+## License
+
+[MIT](./LICENSE)

package/node_modules/checkride/dist/adapters.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Adapter registry — pure data.
+ *
+ * A `Slot` is a role in the pipeline (the catalogue; order matters, cheapest
+ * first). An `Adapter` is a concrete tool that can fill a slot. The registry is
+ * data only: no logic lives here. Resolution (config vs detection) lives in
+ * `../config`, and execution lives in `../orchestrator`.
+ *
+ * Phase 1 ships the blessed defaults plus the two opt-in slots. Alternates
+ * (biome, knip, eslint, jest) land in Phase 2.
+ */
+/** The aggregate-report schema version written to `.check/summary.json`. */
+export declare const SCHEMA_VERSION = 1;
+/** A role in the pipeline. */
+export type Slot = {
+    /** Stable slot name, e.g. `'lint'`. Used by `--only`/`--skip` and the report. */
+    name: string;
+    /** Opt-in slots are excluded from the default run (need `--all`/`--include`). */
+    optIn?: boolean;
+};
+/** A concrete tool that can fill a slot. */
+export type Adapter = {
+    /** Adapter name, e.g. `'oxlint'`. Recorded as `adapter` in the report. */
+    name: string;
+    /** The slot this adapter fills, e.g. `'lint'`. */
+    slot: string;
+    /** Human description for the report (mirrors the interim check catalogue). */
+    description: string;
+    /** Config files whose presence activates this adapter. `[]` = always available. */
+    detect: string[];
+    /** Command to spawn (usually `'pnpm'`). Ignored when `builtin` is set. */
+    command: string;
+    /** Arguments to the command. Ignored when `builtin` is set. */
+    args: string[];
+    /** `.check/<file>` target when stdout is JSON; `null` if the tool writes its own. */
+    outputFile: string | null;
+    /** Appended to `args` under `--changed`. */
+    changedArgs?: string[];
+    /** Used by `checkride fix`. */
+    fixArgs?: string[];
+    /** Per-check timeout in seconds; `0` disables the cap. Falls back to the config-level `timeout`. */
+    timeout?: number;
+    /** In-process check id (e.g. `'links'`); when set, the orchestrator runs it directly. */
+    builtin?: string;
+    /** Pinned versions `init` writes into package.json. */
+    devDeps: Record<string, string>;
+};
+/** Pipeline order. Cheapest first so `--bail` fails fast. */
+export declare const SLOTS: readonly Slot[];
+/**
+ * Adapter registry. The FIRST adapter for a slot is its blessed default: it
+ * wins detection when several tool configs coexist, and is the only one `init`
+ * generates config for. Alternates follow so checkride can still *run* them.
+ */
+export declare const ADAPTERS: readonly Adapter[];
+//# sourceMappingURL=adapters.d.ts.map

package/node_modules/checkride/dist/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,4EAA4E;AAC5E,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,8BAA8B;AAC9B,MAAM,MAAM,IAAI,GAAG;IACjB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,OAAO,GAAG;IACpB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,qFAAqF;IACrF,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,oGAAoG;IACpG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC,CAAC;AAEF,6DAA6D;AAC7D,eAAO,MAAM,KAAK,EAAE,SAAS,IAAI,EAWhC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,SAAS,OAAO,EA0LtC,CAAC"}