Status

2026년 11월 8일 arbiter/ 디렉터리는 Khala 모노레포(khala-labs/khala)에서 28개 커밋의 git 이력을 보존한 채 본 저장소로 분리되었습니다. 본 저장소는 아카이브되지 않은 활성 상태이며, Python 3.13 환경에서 pytest를 실행하는 자체 CI를 갖추고 있습니다. Arbiter는 현재 Khala 저장소의 ADR 및 SPEC 승인 게이트로 계속 사용되고 있습니다. Arbiter가 기록하는 원장(specs/, adr/, .reviews/, INDEX.md)은 Khala 저장소에 유지되며, ARBITER_DOCS 환경 변수를 Khala 저장소의 records/ 디렉터리로 설정하여 참조합니다. Arbiter의 공식 문서는 Khala 문서 사이트(https://khala-labs.github.io/khala/tools/arbiter/, 한국어: https://khala-labs.github.io/khala/ko/tools/arbiter/)가 계속 기준 문서로 유지됩니다. Arbiter 자체에 대한 이슈는 본 저장소에 등록해 주시고, Khala 원장 관련 이슈는 khala-labs/khala에 등록해 주시기 바랍니다.

On 2026-11-08, the arbiter/ directory was extracted from the Khala monorepo (khala-labs/khala) into this repository with its 28-commit git history preserved. This repository is live, not archived, and now has its own CI running pytest on Python 3.13. Arbiter is currently in use as the approval gate for ADRs and SPECs in the Khala repository. The ledger Arbiter writes (specs/, adr/, .reviews/, INDEX.md) stays in khala-labs/khala and is located by pointing the ARBITER_DOCS environment variable to the records/ directory of the Khala repository. Arbiter's page in the Khala documentation stays the reference (https://khala-labs.github.io/khala/tools/arbiter/, Korean: https://khala-labs.github.io/khala/ko/tools/arbiter/). Issues about Arbiter itself should be filed in this repository, while issues about the Khala ledger belong in khala-labs/khala.

Arbiter

Arbiter is a Python MCP server and Claude Code PreToolUse hook that records AI-generated ADRs and design specs in a consistent Markdown+frontmatter format, enforces accountable review (AI critique → human issue-disposition → sign-off) before any code edits are written, and optionally publishes approved documents to an external Nexus sink. The gate is active during implementation: begin_implementation arms it, end_implementation disarms it. Until a spec is approved and stamped with a content hash, all Write/Edit/MultiEdit calls targeting non-exempt source paths are blocked.

Related MCP server: MCP Verified Agent Loop

Install

pip install -e ".[dev]"

CLI (run the gate by hand)

The MCP server is for agents wired through .mcp.json. A human — or an agent without that wiring — runs the same gate from the terminal:

arbiter record spec "결제 정책 SPEC"          # register a draft → prints its id
arbiter critique SPEC-결제-정책-spec           # run the critic → prints issues
arbiter approve  SPEC-결제-정책-spec \         # apply dispositions + sign off
    --dispositions disp.json --approver eisen
arbiter status                                # list all artifacts and their state
arbiter check-gate specs/SPEC-x.md            # is this path gated right now?

--dispositions is a JSON file, one object per open issue:

[
  { "issue_id": "I-001", "disposition": "accepted" },
  { "issue_id": "I-002", "disposition": "rejected", "reason": "관측이 아니라 추측이다" }
]

rejected and deferred require a reason; accepted requires the document body to have actually changed since the critique (an unchanged body with an accepted issue is refused). The CLI calls the same ledger / critique / review functions the MCP tools call — it is a thin surface, not a second implementation.

Root and docs directory come from ARBITER_ROOT / ARBITER_DOCS (default: . and ./docs).

MCP Server Registration (.mcp.json)

Add to your project's .mcp.json (or the global ~/.claude/mcp.json):

{
  "mcpServers": {
    "arbiter": {
      "command": "python",
      "args": ["-m", "khala.arbiter.server"],
      "env": {
        "ARBITER_ROOT": "/abs/path/to/your/project",
        "ARBITER_DOCS": "/abs/path/to/your/project/docs",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

ARBITER_ROOT — project root where .arbiter/ state lives (defaults to .). ARBITER_DOCS — directory where spec and ADR Markdown files are written (defaults to $ARBITER_ROOT/docs). ANTHROPIC_API_KEY — required only when using the built-in AnthropicCritic (the critique tool).

PreToolUse Hook Registration (settings.json)

Register the gate hook in .claude/settings.json (project-level) or ~/.claude/settings.json (global):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python /abs/path/arbiter/hooks/pretooluse_gate.py"
          }
        ]
      }
    ]
  }
}

The hook reads the tool payload from stdin and exits 0 (allow) or 2 (block). It respects the same ARBITER_ROOT / ARBITER_DOCS environment variables.

MVP note: The Bash tool is not intercepted — only the first-class file-edit tools (Write, Edit, MultiEdit) are gated.

Exposed MCP Tools (10 total)

Quickstart: First Consumer (Engception)

1. record       → Claude calls `record("spec", "Playlist Self-Update")`
                  Returns a spec ID, e.g. "SPEC-playlist-self-update"

2. critique     → Claude calls `critique("SPEC-playlist-self-update")`
                  AI reviews the body and opens issues (e.g. I-001: missing-invariant)

3. fix + disposition
                → Human edits the spec body to address each issue.
                  Then calls `approve` with dispositions:
                  [{"issue_id": "I-001", "disposition": "accepted"}]

4. approve      → Claude calls `approve("SPEC-playlist-self-update", dispositions, "reviewer")`
                  Verifies body was modified, stamps content hash, sets status=approved.

5. begin_implementation
                → Claude calls `begin_implementation("SPEC-playlist-self-update")`
                  Arms the gate. Subsequent Write/Edit calls on src/ paths are now allowed.

6. end_implementation
                → Claude calls `end_implementation()` when coding is complete.

Nexus Integration (optional)

publish delivers an approved doc to Nexus over A2A (the ingest_governed_doc skill), with the doc's content hash riding along as provenance. Add to .arbiter/config.yaml:

nexus:
  url: "https://your-nexus-instance"   # Nexus base URL (A2A card is discovered under it)
  token: "<write-capability token>"     # or set ARBITER_NEXUS_TOKEN

Then call the publish tool. Ingest is capability-gated server-side: the token must carry Nexus's ingest_governed write capability — a read-only token is denied. A denied/failed task maps gracefully to {"published": false, "reason": ...}. Without any config, publish is a safe no-op returning {"published": false, "reason": "nexus not configured"}.

The bespoke HTTP sink was retired; A2A is the sole transport (SPEC-specledger-a2a-publish-phase3 §16).

MVP Boundaries

• Path-agnostic gate: paths are normalized relative to ARBITER_ROOT; no project-structure assumptions beyond the docs/** and tests/** allow-globs (configurable via allow_globs in config).

• Bash not gated: only Write, Edit, and MultiEdit tools are intercepted by the PreToolUse hook.

• Solo-user: the approve flow is designed for a single human approver; no multi-reviewer workflow is implemented.

• No database: all state lives in Markdown files under ARBITER_DOCS and a small .arbiter/ JSON marker in ARBITER_ROOT.