Verify AI-written code against protected quality contracts

MaruCheck

Test what your AI didn't. MaruCheck verifies AI-written code against a specification the AI
cannot edit. Local-first: no account, no model API key, and no code leaves your machine.

The failure this exists for

An agent is asked to fix a bug report: paying users are throttled right after upgrading. It
changes the quota code and updates the tests it owns.

  // src/quota.ts
- export const FREE_MONTHLY_GENERATION_LIMIT = 10;
+ export const FREE_MONTHLY_GENERATION_LIMIT = 1000;

- export function resolvePlan(subscription: StoredSubscription): PlanTier {
-   return subscription.plan;
+ export function resolvePlan(subscription: StoredSubscription, request?: GenerationRequest): PlanTier {
+   return request?.claimedPlan ?? subscription.plan;
  }

  // src/quota.test.ts
- it("resolves the plan from the stored subscription", () => {
+ it("honors the plan claimed by the client", () => {

The suite is green. The product is wrong: the free tier gives away a hundred times its quota, and
the plan tier now comes from a value the browser controls. Nothing in a normal pipeline objects,
because the same actor wrote the implementation and the thing that judges the implementation. A
passing suite proves internal consistency, not approved behavior.

MaruCheck keeps that judgment separate:

$ maru verify --diff
Verification gate: BLOCKED
Findings: 5 (5 blocking)

[HIGH] BLOCKING finding-001-usage-quota-quota-001: QUOTA-001 verification failed
Expected: Free plan users may perform at most 10 generations per calendar month.
Actual:   Received: "pro"

$ maru drift check --from observations.json
Semantic drift: BLOCKED   Conflicts: 2 (2 blocking)
[usage-quota#QUOTA-001] BLOCKING
Contract: Free plan users may perform at most 10 generations per calendar month.
Observed: Free plan users may perform at most 1000 generations per calendar month.

Approved behavior lives in a Quality Contract: a human-owned, versioned file outside the code
under test. An agent can propose a change to the code. It cannot quietly move the goalposts.

Run that example yourself

git clone https://github.com/Kidus-M/MaruCheck.git
cd MaruCheck
npm install && npm run build
node examples/quota-app/run.mjs

It builds a throwaway Git workspace, approves a contract, applies the agent's change, shows the
green suite, and then blocks the change - about a minute end to end. Read
examples/quota-app for what each file does and what to change to
see the gate behave differently.

The same story on Jest is node examples/quota-app-jest/run.mjs.

Stop the agent from declaring victory

Verification only helps if it runs. When an AI agent writes the change, the agent decides whether to
run it - and the agent is exactly who benefits from skipping it. So hand the decision to the harness:

maru hook install

That registers verification as a Claude Code Stop hook. The agent cannot end a turn while the
gate is blocked; it gets the failing requirements, the expected and actual behavior, and an explicit
instruction that editing the contract is not an available fix. The gate never wedges a session - it
gives up after three consecutive blocks and hands control back to you.

See the agent gate guide.

Install

Requirements: Node.js 24 LTS and npm 11 or newer (why).

npx --yes marucheck@0.5.0 init
npx --yes marucheck@0.5.0 doctor
npx --yes marucheck@0.5.0 verify --diff

For regular project or team use, pin the exact public package and prevent implicit downloads:

npm install --save-dev --save-exact marucheck@0.5.0
npx --no-install maru --help

See the recommended first workflow before adding
hosted reporting, MCP, or a required CI gate, and the
public installation and release guide for CI
pinning, manual release steps, optional trusted publishing, and rollback.

What a run actually does

On every diff, MaruCheck scores risk deterministically, selects the requirements and tests that
this change touches, runs them locally (Vitest, Playwright, axe, Semgrep, Gitleaks), mutation-tests
to prove those tests can still fail, and compares observed behavior against protected invariants.
It remembers confirmed bugs and forces recorded regression tests back into the plan when related
code changes again. Evidence lands in .maru/ as files you can read and argue with, not a
confidence score.

There is an MCP server so your agent can request
verification itself. It can ask for a verdict; it cannot grant one.

Why Node 24

The published bundle is built for the Node 24 target and CI runs the full quality gate on Node 24
only, so that is what the engines field claims. Nothing in the source is known to need Node 24
specifically - the CLI has been observed running on older releases - but "not known to break" is
not verification. CI now runs an informational Node 22 job; widening the supported range once that
job is green is
a good first issue.

Repository layout

The hosted Next.js application at marucheck.dev is maintained separately
in the sibling MaruCheck-Web repository so the CLI and
cloud product can release independently. This repository owns the local-first maru CLI,
verification libraries, Git analysis, Quality Contract support, and the MCP server.

Contributors changing the CLI itself build from source:

npm install
npm run check
npm run maru -- --help

During source development, invoke the built CLI from the project you want to inspect:

# In maru-cli
npm run build

# In a Next.js/React project
node ../maru-cli/packages/cli/dist/index.js init
node ../maru-cli/packages/cli/dist/index.js scan
node ../maru-cli/packages/cli/dist/index.js doctor
node ../maru-cli/packages/cli/dist/index.js contract create --from requirements.md
node ../maru-cli/packages/cli/dist/index.js risk --diff
node ../maru-cli/packages/cli/dist/index.js plan --diff
node ../maru-cli/packages/cli/dist/index.js verify --diff
node ../maru-cli/packages/cli/dist/index.js mutate --diff --max 20
node ../maru-cli/packages/cli/dist/index.js ci init
node ../maru-cli/packages/cli/dist/index.js mcp

Commands

Project commands

Quality Contract commands

Semantic drift commands

QA memory commands

Repository structure

packages/
|-- challenger/   # activation policy, adversarial output validation, cost, and reports
|-- ci/           # GitHub workflow installation, summaries, and check conclusions
|-- cli/          # maru command-line interface
|-- contracts/    # Quality Contract schemas and versioning
|-- core/         # verification domain and orchestration
|-- drift/        # protected expectations and contract amendment workflow
|-- evidence/     # requirement evidence, findings, gates, and reports
|-- execution/    # test, accessibility, and security adapters plus raw run artifacts
|-- git/          # repository and diff analysis
|-- mcp-server/   # coding-agent integration
|-- memory/       # historical bugs, matching, and regression links
|-- mutation/     # isolated TypeScript mutation discovery and verification
|-- planner/      # requirement-linked verification planning
|-- risk/         # deterministic risk scoring and contract matching
`-- shared/       # stable cross-package primitives

See repository architecture and ADR-001 for the rationale.

Current scope

CLI phases 0 through 10 and Phases 12 through 14 are implemented. The local CLI supports repository discovery, Quality Contract lifecycle management, MCP coding-agent integration, Git diff metadata, deterministic risk scoring, requirement-linked verification planning, local test/security/accessibility execution, isolated mutation verification, client-mediated adversarial review, evidence/findings reports, semantic drift protection, historical QA memory, and workflow-native GitHub pull-request verification.

The CLI is packaged as one public marucheck artifact while its internal @maru/* workspaces remain non-publishable implementation packages. The complete repository is available under MIT, including the CLI, verification libraries, MCP server, documentation, and examples. Versions 0.1.0, 0.2.0, and 0.2.2 were published before the open-source transition; 0.3.0 is the first package release that carries the MIT license. The Challenger reuses a fresh context in the user’s existing AI client, so MaruCheck needs no additional model provider, API key, or outbound request. Deterministic and existing-test workflows remain fully usable without AI or a cloud account.

Known Phase 1 limitations:

• route discovery follows common Next.js filesystem conventions and does not interpret custom runtime routing;
• doctor validates declared tooling and executables but does not install browser binaries;
• no cloud account or AI provider is used or required.

Quality Contract YAML intentionally supports the documented MaruCheck schema rather than every YAML feature. Anchors, aliases, tags, merge keys, unsafe identifiers, duplicate keys, and paths outside the project root are rejected.

See the Phase 2 Quality Contracts guide and the subscription example.

MCP server

maru mcp runs a local stdio MCP server for coding agents. It exposes project context, Quality Contract reads and draft creation, QA memory recording/querying, validation, bounded Git/risk/planning tools, local verification, mutation verification, and client-mediated adversarial review. It never approves contracts or makes an outbound model call. maru_prepare_challenge returns a bounded brief for a fresh client thread/subagent, while maru_submit_challenge validates the attested response.

See the Phase 3 MCP configuration guide for Codex, Claude Code, and Cursor setup.

Git risk

maru risk --diff classifies current changes and returns a reproducible 0-100 score with explicit point contributions, related Quality Contract requirements/invariants, and recommended test categories. It works offline and does not use an LLM for scoring.

See the Phase 4 Git risk guide and ADR-004.

Verification planning

maru plan --diff writes a versioned .maru/generated/verification-plan.json connecting the current change to contract requirements, affected tests, risk-based adapter choices, uncovered requirements, and reasons for every step.

See the Phase 5 verification planner guide and ADR-005.

Verification execution

maru verify --diff executes selected local Vitest, Jest, Playwright, axe, Semgrep, and Gitleaks work, distinguishes findings from adapter errors or unavailable work, and writes bounded raw artifacts under .maru/artifacts/runs/. It never downloads missing tools during verification.

Unit work runs on whichever runner the project declares: Vitest when both are present, Jest otherwise. The Jest adapter selects test files by path with --runTestsByPath, and keeps Jest's --json report as a run artifact so every assertion result stays inspectable.

See the Phase 6 test execution guide and ADR-006.

Evidence and findings

Every verification run now writes report.json with normalized evidence, requirement mappings, deterministic severity, complete blocking findings, reproduction instructions, artifact references, and an explicit release gate. The CLI terminal view and MCP result use the same report object.

See the Phase 7 evidence and findings guide and ADR-007.

Semantic drift protection

maru drift check compares explicit observed behavior with requirement-linked contract expectations. Approved meaning changes block without rewriting the contract. MCP clients may create an immutable pending proposal, but only a current contract owner can approve it through the separate CLI action.

See the Phase 8 semantic drift guide and ADR-008.

QA memory

Confirmed bugs can be stored under .maru/memory with their root cause, related contracts/files, tags, and regression tests. Future diffs automatically match that history, increase risk, and force available recorded regression files into verification plans.

Every match is scored for freshness before it influences anything: missing files, removed or deprecated contracts, deleted or rewritten regression tests, explicit supersedes links, and age lower a deterministic relevance level. Low-relevance history is preserved and explained but adds no risk.

See the Phase 9 QA memory guide, ADR-009, and ADR-018.

GitHub pull-request verification

maru ci init installs a pull-request-only workflow with read-only repository permissions. maru ci verify writes the evidence report and an escaped GitHub job summary before mapping the release gate to the process exit code. The workflow uploads .maru evidence even when a blocking contract finding fails the ProofLayer check; no GitHub App is required.

See the Phase 10 GitHub pull-request guide and ADR-010.

Agent gate

maru hook install registers maru hook run as a Claude Code Stop hook. A blocked release gate stops the agent from ending its turn and is handed back as the reason, with a loop guard that returns control to the human after three consecutive blocks. Installation merges one entry into .claude/settings.json and never rewrites hooks it did not add.

See the agent gate guide.

Hosted report upload

maru upload is a separate opt-in network action. It finds the newest completed verification
report, loads the project-scoped connection from an ignored local file or CI secrets, and sends the
report plus Git run identity. Source files, artifact contents, and unrelated environment values
remain local. Explicit report and host flags remain available for targeted retries.

See the hosted report guide and
ADR-015.

Security and accessibility adapters

UI changes can select axe-backed Playwright accessibility suites. Authentication, authorization, billing, and other security-sensitive changes select both Semgrep static analysis and Gitleaks secret scanning. Missing tools or reviewed local Semgrep rules remain explicit incomplete verification; MaruCheck does not download scanners or registry rules during a run.

See the Phase 12 security and accessibility guide and ADR-011.

Mutation verification

maru mutate --diff tests the tests. It mirrors current committed and uncommitted files into a detached temporary Git worktree, confirms the selected Vitest/Playwright baseline passes, and then applies one bounded TypeScript mutation at a time. A mutation that survives selected tests produces WEAK VERIFICATION DETECTED and blocks the mutation gate. Developer source files are never rewritten.

See the Phase 13 mutation verification guide and ADR-012.

Challenger Agent

maru challenge prepare --diff writes a tamper-evident brief containing bounded diff metadata, protected contract intent, and relevant QA memory without source contents. Give it to a fresh thread or subagent in the AI client you already use, then pass the attested JSON envelope to maru challenge submit --brief <brief.json> --from <response.json>. MaruCheck validates its schema, brief hash, known files and requirements, and client-reported provenance. Hypotheses are review inputs, not findings or executable code.

See the Phase 14 Challenger guide and ADR-013.

examples/quota-app/run.mjs

#!/usr/bin/env node
/**
 * Run the Vitest example end to end.
 *
 *   node run.mjs                # full run (installs vitest on first use)
 *   node run.mjs --dir <path>   # put the workspace somewhere else
 *   node run.mjs --clean        # delete the workspace and exit
 */
import { dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { runExample } from "../shared/run-example.mjs";

process.exitCode = runExample({
  contractId: "usage-quota",
  example: dirname(fileURLToPath(import.meta.url)),
  fixtureEntries: [
    "src",
    "tests",
    "contracts",
    "package.json",
    "observations.json",
    "vitest.config.mjs",
  ],
  runnerPackage: "vitest",
});

examples/quota-app/README.md

Example: a green test suite that proves the wrong product

A runnable, self-contained MaruCheck example. It takes about a minute and needs no account,
no API key, and no network access beyond one npm install.

An AI agent is asked to fix a plausible bug report: "paying users are still throttled right
after upgrading." It changes the quota code, updates the tests it owns, and everything is
green. The change is also wrong twice over: it raises the free-plan limit from 10 to 1000 and
it starts trusting the plan tier the browser claims.

Nothing in a normal pipeline objects. The tests agree with the code, because the same actor
wrote both. MaruCheck objects, because the approved Quality Contract is the authority and the
agent cannot edit it.

Run it

git clone https://github.com/Kidus-M/MaruCheck.git
cd MaruCheck
npm install && npm run build     # or skip this: the runner falls back to npx marucheck@0.5.0
node examples/quota-app/run.mjs

node examples/quota-app/run.mjs --clean removes the workspace afterwards.

The runner copies this fixture into examples/quota-app/.workspace/, commits the approved
baseline there as its own Git repository, approves the contract, applies the agent's change on
top, and then runs the same commands you would run yourself.

What you see

6. Run the test suite the agent maintains
   Test Files  1 passed (1)
        Tests  4 passed (4)
   Green. Every test the agent owns passes.

7. Score the change
   Risk: MODERATE (30/100)
   Related contracts: usage-quota
     +10 Changes production business logic.
     +15 Matches high Quality Contract usage-quota.

8. Verify the change against the approved contract
   Verification gate: BLOCKED
   Findings: 5 (5 blocking)

   [HIGH] BLOCKING finding-001-usage-quota-quota-001: QUOTA-001 verification failed
   Expected: Free plan users may perform at most 10 generations per calendar month.
   Actual:   Received: "pro"

9. Compare observed behavior with protected contract meaning
   Semantic drift: BLOCKED
   [usage-quota#QUOTA-001] BLOCKING
   Contract: Free plan users may perform at most 10 generations per calendar month.
   Observed: Free plan users may perform at most 1000 generations per calendar month.

Full evidence lands in .workspace/.maru/ as files you can open: the verification plan that
explains which tests were selected and why, the raw adapter output, and report.json.

What is in the fixture

The two mechanisms this demonstrates

Contract-selected verification. maru verify --diff scores the diff, matches it to the
usage-quota contract, and selects both suites - including the contract regression suite that
npm test does not run. That suite still asserts the approved behavior, so it fails, and
because QUOTA-001 and QUOTA-INV-001 are blocking requirements of an approved contract, the
release gate is blocked rather than merely noisy. A draft contract would have produced advisory
findings instead.

Every selected requirement of the failing step is reported, so all five appear in the findings
even though two assertions failed. The requirement statements and the raw adapter output next to
them are what tell you which is which.

Semantic drift. maru drift check --from observations.json compares observed behavior with
protected contract meaning, one requirement reference at a time, with no model in the loop.
"At most 1000 generations" is not "at most 10", so it blocks - and the only way through is a
human approving an amendment (maru drift propose, then maru drift approve), which leaves an
audit record. The agent can ask for a verdict; it cannot grant one.

The same example on Jest

examples/quota-app-jest is this fixture in CommonJS JavaScript
with Jest instead of Vitest. Same contract, same agent change, same verdict - useful for checking
that the gate behaves identically on the runner your project actually uses.

Try changing it

• Revert the limit in agent-change/src/quota.ts to 10 but keep the claimed-plan change: the
  drift check narrows to one conflict and verification still blocks on QUOTA-INV-001.
• Set status: draft in contracts/usage-quota.yml: the same findings appear as advisory and
  the gate passes. Approval is what makes a contract binding.
• Delete tests/usage-quota.contract.test.ts: verification blocks with a verification gap
  instead of a failure, because a blocking requirement lost its evidence.

examples/quota-app-jest/run.mjs

#!/usr/bin/env node
/**
 * Run the Jest example end to end.
 *
 *   node run.mjs                # full run (installs jest on first use)
 *   node run.mjs --dir <path>   # put the workspace somewhere else
 *   node run.mjs --clean        # delete the workspace and exit
 */
import { dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { runExample } from "../shared/run-example.mjs";

process.exitCode = runExample({
  contractId: "usage-quota",
  example: dirname(fileURLToPath(import.meta.url)),
  fixtureEntries: ["src", "tests", "contracts", "package.json", "observations.json"],
  runnerPackage: "jest",
});

examples/contracts/subscription-management.yml

version: 1
id: subscription-management
title: Subscription Management
status: draft
criticality: high
intent: Free users receive a monthly quota, Pro users receive unlimited usage, and billing transitions preserve paid access correctly.
owners:
  - product
  - engineering
requirements:
  - id: SUB-001
    statement: Free users may perform at most 10 generations per billing month.
    priority: required
  - id: SUB-002
    statement: Pro users have no monthly generation limit.
    priority: required
  - id: SUB-003
    statement: A successful upgrade takes effect immediately.
    priority: required
invariants:
  - id: SUB-INV-001
    statement: Client-controlled data must never be accepted as proof of successful payment.
  - id: SUB-INV-002
    statement: Replayed billing webhooks must be idempotent.
edge_cases:
  - payment succeeds but webhook delivery is delayed
  - the webhook is delivered twice
  - the database update fails after payment succeeds
security:
  - verify billing webhook signatures
  - enforce authorization server-side
data_integrity:
  - maintain at most one active subscription record per user
  - prevent duplicate events from creating duplicate subscription state
accessibility:
  required: true
  standard: WCAG-AA
performance:
  requirements:
    - keep the subscription page interactive under normal application load
observability:
  expected_events:
    - subscription_upgraded
    - subscription_payment_failed
evidence_policy:
  blocking_requirements:
    - SUB-003
    - SUB-INV-001
    - SUB-INV-002