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. 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.

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 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 registers the five skills and .mcp.json starts the bundled local MCP server. No TypeScript runtime is needed after the repository has been built.

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 starts the bundled MCP server (database at .loopbreaker/loopbreaker.db under the current project), and the five skills under skills/ are auto-discovered as /loopbreaker:<skill-name>.

pnpm install && pnpm build
claude --plugin-dir /path/to/loopbreaker

Or install it persistently from GitHub:

/plugin marketplace add rordi-ai/loopbreaker
/plugin install loopbreaker@loopbreaker

Working inside this repository needs no install at all: the project-scope .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:

{
  "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:

pnpm verify:mcp

Import your own issue

Start from examples/issue-contract.json:

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

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. 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

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

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.