⚡ x-harness

Completion is admitted, not claimed.
A lightweight, file-first verification harness for AI-agent workflows.

English | Tiếng Việt

New to x-harness? Read docs/GETTING_STARTED.md for a conceptual primer, then try the Quickstart.

What is x-harness?

x-harness is a small, opinionated verification harness for AI coding agents. It does not run your agents, replace your CI, or guarantee that code is correct. It does one bounded job:

Turn an AI agent's "I'm done" claim into an auditable admission decision — accepted or withheld — against a repository policy.

It works locally, offline, and file-first. No daemon, no database, no server, no MCP service, no LLM calls, no network credentials. The source of truth is the files in your repository: schemas, policies, templates, and completion cards.

How is it different from existing tools?

In short: x-harness is not an agent runtime, an issue tracker, a planning system, an LLM gateway, or a deployment engine. It is a policy gate that decides whether an agent's claim of completion should be admitted.

The core idea in 60 seconds

   Agent writes code
        │
        ▼
   Agent writes a "completion card" (a small YAML file)
        │
        ▼
   xh verify --card completion-card.yaml
         │
         ▼
    Read-only verification gate evaluates the card
    against schemas + policies (no source mutation)
         │
         ▼
    ┌───────────────────────────────────────────┐
    │  acceptance_status: accepted   → exit 0  │   ✅ done
    │  acceptance_status: withheld   → exit 1  │   🚧 not done, with a recovery path
    └───────────────────────────────────────────┘

check is an alias for verify — both run the same read-only gate.

The verifier is read-only. It inspects your card and evidence; it never edits your source to "fix" things while checking. The agent must produce a passing card itself.

Beginner concepts (read this first)

Install (from source checkout)

x-harness ships a native Go CLI (recommended) and a TypeScript compatibility CLI (source-checkout fallback only).

Option A — Native Go CLI (recommended)

# Build a single static binary
go build ./cmd/x-harness

# Verify
./x-harness --version

Requires Go 1.22+. The resulting ./x-harness binary is self-contained.

Option B — TypeScript compatibility CLI (source checkout)

Use this only when you want to run the parity baseline from source:

npm install
npm run build
node packages/cli/dist/index.js --version

Requires Node.js ≥ 20. The published x-harness npm package is a Go-only wrapper; the Node fallback only works from a source checkout where dist/ exists.

Pre-built release binaries

Pre-built native binaries for linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64, and windows/arm64 are attached to each GitHub release. Download the binary that matches your platform, place it on your PATH, and rename it to xh (or x-harness).

Package managers (Windows / macOS / Linux)

Scoop and Homebrew manifests are generated automatically at release time from packaging/ and scripts/. They will appear in their respective buckets once those buckets are published; until then, please use the pre-built binaries above or build from source.

Quick start (5 minutes)

Fast track

Run this in the project where you want to use x-harness:

xh init --minimal
xh doctor --root . --json
xh verify --card completion-card.yaml

Or try the repository fixtures first:

xh doctor --root . --json
xh verify --card examples/golden/regression/success-light/completion-card.yaml

1. Initialize a workspace

To start using x-harness in another project, run init at its root:

xh init --minimal        # default: contracts, templates, policies, schemas
# xh init --standard     # adds schemas and example solo-agent scenarios
# xh init --full         # adds multi-agent examples, adapters, and a GitHub Action

init stops with a blocked summary if it finds conflicting files; re-run with --force only when you intentionally want to overwrite them.

2. Health-check the workspace

./x-harness doctor

This validates that schemas, policies, templates, and adapter links are present and consistent. Look for "healthy": true in JSON output (./x-harness doctor --json).

3. Run verification

The repo ships with 28 golden scenario directories across regression, capability, adversarial, conformance-strict, and recovery suites — 26 card-backed fixtures plus 2 conformance-strict reference scenarios (README-only, no completion card). Try a known-good one:

xh verify --card examples/golden/regression/success-light/completion-card.yaml

Expected output:

outcome: success
acceptance_status: accepted
checks: 2 passed, 0 failed

Now try one that is missing required evidence:

xh verify --card examples/golden/regression/blocked-missing-evidence/completion-card.yaml
# exit code 1

Expected output:

outcome: failed
acceptance_status: withheld
checks: 0 passed, 5 failed

The task is withheld, not silently marked as done. This is the fail-closed default.

Daily core commands

Most users should start with this narrow loop. The full command matrix is in docs/CLI_COMMANDS.md and xh --help-all.

Terminal: xh <action> (e.g. xh check)
Agent chat: /xh:<action> (e.g. /xh:check) — see docs/ADAPTERS.md

Use handoff, recover, report, trace, and benchmark when you need more workflow structure. Governance, federation, cost, evolution, attribution, and other experimental commands are intentionally kept out of the default onboarding path; see docs/CLI_COMMANDS.md for maturity labels.

Boundary checks (xh boundary)

xh boundary runs deterministic, path-glob + import-regex checks against policies/boundaries.yaml (V1 scope; no AST, no semgrep, no LLM). Subcommands:

xh boundary lint                              # validate the policy file against the schema
xh boundary check --all                       # scan the whole repo
xh boundary check --changed                   # scan only files in `git diff --name-only`
xh boundary explain <file>                    # show which rules apply to a single file

When policies/boundaries.yaml is absent, xh boundary check exits 0 with a warning (opt-in feature). See docs/BOUNDARY.md and schemas/boundary-policy.schema.json for the rule shape (id, from, to_import, action, severity, intermediate?, allow?, applies_to_languages?).

Canonical handoff tiers

Task delegation uses only these three tiers. The labels small, medium, and large are not allowed in active runtime handoffs.

See docs/ADMISSION_POLICY.md for the full rules.

How a verify run flows

┌──────────────┐
│ Agent worker │  writes code + writes a completion card
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ xh verify ...│  loads schema, loads policy, evaluates evidence floor
└──────┬───────┘
       │  read-only
       ▼
┌──────────────┐
│   Outcome    ├─── accepted   (exit 0)
│              ├─── withheld   (exit 1, with recovery routing)
└──────────────┘

Optional, opt-in verify stages (off by default):

• xh verify --contract-oracles — rule-based line-level assertions (grep_rules, dependency_rules).
• xh verify --context-floor — minimal file/ref presence checks.
• xh verify --context-enforce off|advisory|block — enforce context-manifest alignment.
• xh verify --boundary-enforce off|advisory|block_high|block_all — enforce boundary policy.
• xh verify --decision-enforce off|advisory|block — enforce decision-memory linkage.
• xh verify --intent-enforce off|advisory|block — enforce product-intent declaration.
• xh verify --strict — strict-schema mode for withheld_reason output.
• xh verify --mutation-guard — detect any verifier-side source mutation.

When verification fails, the engine emits a structured recovery object routing the work back to the right owner (e.g. evidence_missing → implementation-worker, approval_missing → user).

Platform adapters

x-harness is adapter-agnostic. Pick the one that matches how you already work:

You only need one. Adapters are thin wrappers around the same CLI; they do not fork the contract.

Documentation

The authoritative contract is X_HARNESS.md.

Examples at a glance

• 28 golden scenario directories — 26 card-backed fixtures plus 2 conformance-strict reference scenarios (README-only) across regression, capability, adversarial, conformance-strict, and recovery suites under examples/golden/.
• Real-world examples — Next.js app and monorepo boundary setups under examples/real-world/.

Project status

• Version: 1.0.0 (stable). The CLI is feature-complete for the v1.0 contract.
• Native runtime: Go CLI (recommended). The TypeScript CLI is a source-checkout compatibility baseline only and is no longer shipped in the published npm package.
• No production claims: A passing xh verify is not a guarantee of correctness. It means your card matches the policy. See docs/VERIFY_GATE.md for what the gate does and does not check.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md first.

Harness-sensitive changes (admission policy, schemas, templates, CLI verify, adapters, skills) must include a completed templates/HARNESS_CHANGE_CONTRACT.md and pass ./x-harness doctor, ./x-harness examples verify, and ./x-harness benchmark --filter adversarial --gate locally.

All contributors are expected to follow CODE_OF_CONDUCT.md.

Security

Please do not open public issues for suspected vulnerabilities. Use GitHub private vulnerability reporting or contact the maintainer privately. See SECURITY.md for the full disclosure process and supported versions.

License

MIT — Copyright (c) 2026 Brian Nguyen.