agent-evidence-check

中文说明

Package rename: published as agent-evidence-check (formerly @majiturbo/deploy-check). Config file deploy-units.json and MCP tools deploy_check_* are unchanged.

Coding agents treat “right direction / fixed / tests green / it’s live” as settled facts, while the worktree, test exit code, and live units often hold no receipt. Vendor sandboxes stop dangerous commands; agent-evidence-check stops judgments without evidence—closed-registry checks at four moments, not semantic interrogation on every message.

In day-to-day use the model sounds confident: it follows the prompt without naming a nearer path, stays in one failing approach class for eight edits and still says “fixed,” claims green without a recorded exit 0, or ships one unit and announces the whole surface is live. That is not a permissions miss—it is the conclusion arriving before the evidence.

This library is CLI + MCP (same tools) plus optional thin hooks for direction, loop, done, and deploy. It does not scrape chat and is not premise middleware on every message. The caller (or the agent via MCP) submits the record; the checks only ask whether the receipt holds.

Who this is for

• You run Cursor / Claude Code / Codex (or similar) agents and get confident “done / fixed / live” claims without a record

• You want hooks + MCP, not another every-message prompt wrapper

• You care about direction mistakes, repair loops, fake-green tests, and partial deploys—the failure modes sandboxes do not close

Search-ish keywords agents and humans use: coding agent evidence, agent hooks, stop gate, repair loop, test wash, deploy verify, MCP judgment tools.

Related MCP server: Living Stack Community

Features

• Four judgments — direction, loop, done, and deploy (pre / verify)

• Closed check registry — agents pick ids; they cannot invent check names (custom: only for extensions)

• CLI + MCP — same API; tools deploy_check_direction / _loop / _done / _pre / _verify

• Opt-in per repo — hooks may be installed user-wide, but no-op unless the repo has deploy-units.json

• Optional hard gates — Stop / edit / done gates force the matching call when configured

• Post-deploy observe — http_json, http_text, file_sha256, command, literal

• Fail open on hook errors — missing Node / bad JSON / unknown payload → allow + reason

• English default UX — Chinese via "lang": "zh" or DEPLOY_CHECK_LANG=zh

• Host matrix — Cursor, Claude Code, Codex, Trae, Copilot, Qoder, DSH (honest matrix)

Install

npm i -g agent-evidence-check
# or one-shot:
npx agent-evidence-check --help

Note: run npx from outside a checkout of this repo. Inside the clone, npx resolves the local package and there is no .bin link — use node bin/agent-evidence-check.mjs … instead.

Requirements: Node ≥ 22, git on PATH. macOS / Linux / Windows.

Quick start

cd /tmp
npx agent-evidence-check init --cwd /tmp/sample-app

# nearer path identical to current path → blocked
npx agent-evidence-check direction --cwd /tmp/sample-app \
  --moment start \
  --goal 'speed up the slow page' \
  --path 'rewrite the renderer' \
  --nearer 'rewrite the renderer' \
  --why 'keep going' \
  --evidence 'user said the page is slow'

Trimmed result (advisory mode still returns allow: true; open gates to enforce):

{
  "ok": false,
  "findings": [{
    "checkId": "direction_review",
    "severity": "block",
    "premise": "Continuing the current path is justified without writing down another one",
    "evidence": "nearer path is the same as the current path"
  }]
}

Pass by naming a different nearer path:

npx agent-evidence-check direction --cwd /tmp/sample-app \
  --moment start \
  --goal 'speed up the slow page' \
  --path 'rewrite the renderer' \
  --nearer 'profile first, then change the hot path' \
  --why 'no profile data yet' \
  --evidence 'user said the page is slow'

Loop and done

# same approach class + "fixed" → blocked
npx agent-evidence-check loop --cwd /tmp/sample-app \
  --target src/page.tsx --edits 8 --rejections 3 --claims-fixed \
  --tried 'tweak CSS' --next 'tweak CSS'

# leave the class → passes
npx agent-evidence-check loop --cwd /tmp/sample-app \
  --target src/page.tsx --edits 8 --rejections 3 --claims-fixed \
  --tried 'tweak CSS' --next 'drop the effect' --alternative 'drop the effect'

# no green test on the record → blocked
npx agent-evidence-check done --cwd /tmp/sample-app --no-run --exit-code 1

# recorded exit 0 → passes (also scans uncommitted test diffs for wash)
npx agent-evidence-check done --cwd /tmp/sample-app --no-run --exit-code 0

Full contract: docs/judgments.md.

Use it in an app repo

npx agent-evidence-check init --cwd /path/to/your-app
npx agent-evidence-check doctor --cwd /path/to/your-app

# optional user-level hooks (Cursor, Claude Code, Codex, …)
npx agent-evidence-check-install-hooks

init writes deploy-units.json + an AGENTS.md fragment. Edit units and observe blocks — see docs/verify.md and examples/deploy-units.example.json.

Hard gates

"judgments": { "stopGate": true, "editGate": true, "doneGate": true }

Then re-run install-hooks. Stop / edit events require a recent passing direction / loop / done receipt in .deploy-check/. Consumer paste rules: docs/rules/agent-evidence-check.md.

Undo hooks: npx agent-evidence-check-install-hooks --uninstall (or node scripts/install-hooks.mjs --uninstall from a clone).

MCP

npx agent-evidence-check-mcp

Wire stdio MCP in your host; pass { "cwd": "/path/to/your-app" } on each tool call. Fragments: examples/mcp.cursor.fragment.json, examples/mcp.claude-desktop.fragment.json. Details: docs/mcp.md.

Deploy path

npx agent-evidence-check --cwd /path/to/your-app --shadow
npx agent-evidence-check verify --cwd /path/to/your-app

Default mode is advisory. Prefer worktrees + push + CI/GitOps for release; use this when agents still claim “live” without a receipt.

Checks (closed registry)

Agents may only select these ids.

Direction / loop / done (CLI or MCP)

Deploy (shell hooks + pre / verify)

Custom checks: custom: prefix only.

What you get

Non-goals

• Semantic premise interception on every message

• Replacing vendor shell sandboxes / Auto-review

• Invented token-savings or anti-loop marketing numbers

• Claiming a host without a documented hook + smoke payload

Documentation

Status

v0.1, experimental. English UX by default; "lang": "zh" or DEPLOY_CHECK_LANG=zh. Trial with DEPLOY_CHECK_MODE=shadow. Some host UIs need a one-time toggle — see docs/hook-setup.md.

Package: agent-evidence-check
Source: Majiturbo/agent-evidence-check

License

MIT