loopbreaker

# Loopbreaker **A local planning and review graph that lets agent review stop without pretending the code is ready to ship.** Loopbreaker is the small public demo extracted from a deeper review-and-shipping feature embedded in [Rordi](https://github.com/rordi-ai). It stores an issue's shape decision, planning health, independent planning approval, acceptance behaviors, attributable evidence, findings, bounded review passes, and human waivers in local SQLite; exposes the same substrate to agents through MCP; and renders the ordered gates as a live workflow graph. The hard-won lesson behind it: **review convergence and shipping readiness are different facts**. A reviewer can finish checking a repair while a required behavior still lacks production-relevant proof. Conflating those facts caused review loops to grow indefinitely. A second lesson followed: a verification gate cannot rescue an issue whose scope, work ownership, proof plan, production wiring, or rollback was never made explicit. Loopbreaker makes the distinct authorities explicit: shape, structural planning health, semantic planning approval, implementation review, and shipping readiness. It now packages the complete public workflow as five reusable agent skills: - `shape-strategy` — frame appetite, reversibility, smallest slice, and success. - `plan-feature` — freeze enforced behaviors and reach healthy planning. - `review-planning` — independently approve or redirect shape and planning in at most three passes. - `implement-feature` — build only a planning-ready contract and record evidence. - `review-invariants` — enforce planning preflight, two-plus-one review, and ship authority.  ## Try the incident Requires Node.js 22.5+ and pnpm. ```sh git clone https://github.com/rordi-ai/loopbreaker.git cd loopbreaker pnpm install pnpm build node dist/cli.js demo node dist/cli.js node dist/cli.js substrate DEMO-1 node dist/cli.js serve ``` Open <http://127.0.0.1:7331>. The seeded incident starts here: - One comprehensive pass compresses thirteen legacy review iterations. - Planning health is 100/100 with zero hard blockers. - Two of three enforced behaviors are verified. - A unit test exists for the third behavior, but wired replay proof does not. - Review's next action is repair verification; shipping is held. Use **Record repair pass**. Review becomes complete, but shipping remains held. Then use **Add wired proof**. The behavior becomes verified and the disposition changes to ship. The two decisions never overwrite one another. The graph is inspectable but deliberately read-only: pan, zoom, focus, and select nodes to trace the contract, proof, findings, review budget, and ship decision. A WebSocket carries changes made by another CLI or MCP process into the open graph. If that connection drops, the status badge changes to **Polling recovery** and the client keeps converging through interval polling. Use `?transport=poll` when you want to exercise that recovery path explicitly. CLI stdout uses [TOON](https://toonformat.dev/) so agents receive compact, regular data. The database defaults to `.loopbreaker/loopbreaker.db`; override it with `--db PATH` or `LOOPBREAKER_DB`. ## Install as a Codex plugin The repository is a complete plugin: [.codex-plugin/plugin.json](.codex-plugin/plugin.json) registers the five skills and [.mcp.json](.mcp.json) starts the bundled local MCP server. No TypeScript runtime is needed after the repository has been built. ```sh pnpm install pnpm build ``` The generated `mcp/server.bundle.mjs` is the plugin entry point. Set `LOOPBREAKER_DB` in your MCP environment when you want an explicit database path; otherwise the server uses `.loopbreaker/loopbreaker.db` under its working directory. ## Install as a Claude Code plugin The same repository is also a Claude Code plugin: [.claude-plugin/plugin.json](.claude-plugin/plugin.json) starts the bundled MCP server (database at `.loopbreaker/loopbreaker.db` under the current project), and the five skills under [skills/](skills/) are auto-discovered as `/loopbreaker:<skill-name>`. ```sh pnpm install && pnpm build claude --plugin-dir /path/to/loopbreaker ``` Or install it persistently from GitHub: ```text /plugin marketplace add rordi-ai/loopbreaker /plugin install loopbreaker@loopbreaker ``` Working inside this repository needs no install at all: the project-scope [.mcp.json](.mcp.json) loads the same bundled server directly. ## Use it with any MCP client Build the repo, then add this local stdio server to your MCP client config: ```json { "mcpServers": { "loopbreaker": { "command": "node", "args": [ "/absolute/path/to/loopbreaker/dist/cli.js", "mcp", "--db", "/absolute/path/to/review.db" ] } } } ``` The server tells agents to read the ordered delivery authority before implementation or review, load the substrate, and check ship status separately. It exposes fifteen focused tools: | Tool | Purpose | | --- | --- | | `review_import_contract` | Import behavior children; enforced unless explicitly advisory | | `shape_record` | Persist the explicit proceed, spike, park, or reject shape decision | | `planning_record` | Record a partial or complete pre-review planning profile | | `planning_health` | Read score, five dimensions, blockers, and readiness | | `delivery_readiness` | Read shape → planning → planning-review → implementation → shipping authority | | `planning_review_upsert_finding` | Preserve a stable semantic shape/planning finding | | `planning_review_record_pass` | Record the next independent planning-review pass, limited to 1–3 | | `review_list_issues` | List derived review and shipping states | | `review_substrate` | Read the complete frozen review surface | | `review_upsert_finding` | Preserve one stable row per review root cause | | `review_record_pass` | Record the next pass, limited to 1–3 | | `review_record_evidence` | Attach unit, wired, or live proof | | `review_verify_behavior` | Verify a behavior using attached passing evidence | | `review_create_waiver` | Accept named debt with an approver and rationale | | `review_ship_status` | Read the authoritative ship disposition | The MCP results are TOON text blocks. Run a real client/server handshake with: ```sh pnpm verify:mcp ``` ## Import your own issue Start from [examples/issue-contract.json](examples/issue-contract.json): ```sh node dist/cli.js import examples/issue-contract.json --db my-review.db node dist/cli.js shape APP-42 examples/shape.json --db my-review.db node dist/cli.js health APP-42 --db my-review.db node dist/cli.js readiness APP-42 --db my-review.db node dist/cli.js substrate APP-42 --db my-review.db ``` Every behavior is enforced by default. Set `"advisory": true` only when a behavior genuinely is not part of the ship gate. Once the first review pass is recorded, changing the contract is rejected: parent context can interpret the behavior children, but cannot silently add requirements mid-review. Planning health is deterministic and intentionally conjunctive. The score covers scope, contract quality, work-unit traceability, proof design, and operability. Readiness requires both a score of at least 80 and zero hard blockers. Missing behavior ownership, wired/live proof, production wiring, or rollback cannot be averaged away. Partial profiles are accepted so the tool can return actionable blockers; `loopbreaker health ISSUE` is the structural surface and `loopbreaker readiness ISSUE` is the ordered admission surface. A 100/100 plan still cannot admit implementation until an independent bounded planning review records `approved`. ## The decision model Both planning review and implementation review are bounded to a two-plus-one budget: 1. **Comprehensive** — find the coherent set of issues against the frozen contract. 2. **Repair verification** — check admitted repairs and repair regressions. 3. **Decision only** — ship, ship with debt, split/re-scope, or hold for one named critical risk. There is no automatic pass 4. A passing pass can complete review early. Neither case grants permission to ship. Shipping is derived through ordered authorities: - shape `hold`: the explicit shape is missing, incomplete, or not `proceed`; - planning `hold`: structural planning health is not ready; - planning-review `hold`: semantic review has not independently approved implementation; - verification `hold`: earlier gates are ready but an enforced behavior is unresolved; - `ship`: all earlier gates are ready and every enforced behavior is verified; - `ship_with_debt`: all earlier gates are ready and every unverified enforced behavior has an explicit waiver. This keeps reviewer verdicts as evidence supporting the acceptance contract, instead of creating a hidden parallel gate. ## Architecture ```text CLI (TOON) ─┐ ├── ordered authority + domain rules ── SQLite/WAL MCP (stdio) ┤ │ └── HTTP API ── data-version watcher ── WebSocket │ │ └──────── React Flow workflow canvas ``` The project deliberately uses one domain layer for every interface. The browser cannot call a more permissive mutation than the MCP server, and an agent cannot manufacture a fourth pass through a lower-level endpoint. The UI is a Vite-built React app using React Flow and small local components adapted from the [Vercel AI Elements workflow composition](https://elements.ai-sdk.dev/examples/workflow). Node's HTTP module serves the production bundle and upgrades `/events` to a WebSocket; SQLite `PRAGMA data_version` detects commits from other local processes without introducing a cloud dependency. ## Commands ```text loopbreaker live issue dashboard loopbreaker init initialize SQLite loopbreaker demo seed the synthetic incident loopbreaker import FILE import a behavior contract loopbreaker shape ISSUE FILE record an explicit shape decision loopbreaker plan ISSUE FILE record a planning profile loopbreaker health ISSUE inspect compact planning health loopbreaker readiness ISSUE inspect ordered delivery authority loopbreaker plan-pass ISSUE ... record planning-review pass 1, 2, or 3 loopbreaker plan-finding ISSUE ... preserve one stable planning finding loopbreaker substrate ISSUE inspect the complete substrate loopbreaker pass ISSUE ... record pass 1, 2, or 3 loopbreaker evidence ISSUE ... attach proportionate proof loopbreaker verify BEHAVIOR ... verify with passing evidence loopbreaker waive ISSUE ... accept named debt loopbreaker serve run the visual view loopbreaker mcp run the stdio MCP server ``` Run `loopbreaker help COMMAND` for exact flags. Commands are non-interactive, idempotent where practical, and return structured errors. ## Verify ```sh pnpm verify ``` This runs strict TypeScript checking, domain tests, a production frontend and server build, plugin validation, MCP tool discovery plus a real `review_ship_status` call, and a live-surface check. The live check starts a temporary server, mutates its database through a separate built CLI process, and requires the matching WebSocket event plus updated API state within two seconds. ## Scope Loopbreaker is intentionally a reference implementation, not the full Rordi entity graph or production synchronization layer. SQLite mirrors the important review semantics locally so builders can inspect, reuse, and challenge the pattern without standing up Rordi's Postgres services. MIT licensed.