convez.ai
AgenteAutomaçãoIntermediário
BrianNguyen29

x-harness

BrianNguyen29/x-harness

Gate de verificação que converte a conclusão do agent em decisão auditável

Ver no GitHub
BomPluginScore · de 0 a 100

Um verificador leve e offline para agents de IA que transforma a declaração de conclusão de um agent em uma decisão auditável e documentada. Funciona 100% localmente com base em arquivos, sem infraestrutura remota, MCP ou chamadas de LLM.

Instalação

$npx convez-ai BrianNguyen29/x-harness

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
15
Forks
5
Acompanhando
0
Saúde
100%
Último commit
há 3 meses
Versão
—
Issues abertas
11
Contribuidores
3

Casos de uso

  • Validar conclusão de tarefas de agents de IA antes da entrega
  • Implementar políticas de verificação offline em CI/CD
  • Criar registros auditáveis de decisões de aceitação/rejeição em workflows de agents

Veredito

x-harness é um verificador especializado e minimalista que resolve um problema real: desacoplar a decisão de conclusão da geração de código. Ideal para pipelines que precisam de gates determinísticos e auditáveis sem overhead infraestrutural.

README

A tradução para o português deste README ainda está na fila.

⚡ x-harness

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

Verify CI CodeQL OpenSSF Scorecard License: MIT Node.js ≥ 20 Go 1.22+

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?

ConcernTypical AI toolingx-harness
Who decides "done"?The agent itselfA read-only verification gate in this repo
Where does state live?A remote server / SaaSFiles in your repository
Does it need a runtime?Often a daemon, MCP, or cloud serviceNo. A single static binary
Is the decision auditable?Hidden inside a model or dashboardA structured completion card + JSONL trace
Is verification trusted?Mixed with generationDecoupled. verify never edits the work product
Can it fail closed?Often "best effort"Yes. Anything other than success is withheld

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)

TermWhat it means in x-harness
Completion cardA YAML file (e.g. completion-card.yaml) where an agent records what it claims to have done, with what evidence.
Verify gateThe xh verify command (alias xh check). It runs the read-only admission logic.
AcceptedVerification passed. Exit code 0. The task is officially done.
WithheldAny non-success outcome (failed, blocked, skipped, timeout, error). Exit code 1.
TierOne of light, standard, or deep. Determines how much evidence is required.
PGVPre-Gate Validation. Advisory only. It can suggest things, but it never grants admission.
AdapterA small set of convention files (e.g. CLAUDE.md, .cursor/rules/x-harness.mdc) for a specific agent platform.

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

xh start

Or follow the steps manually:

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

2. Run your first 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.

3. Initialize a new 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.

4. Dispatch a task handoff

xh handoff standard --title "Fix checkout button alignment"

This generates a structured Markdown file with the explicit file set, evidence checklist, and rollback definitions for the standard tier.


Beginner actions

These are the actions you'll use most often. The full list is in xh --help-all.

ActionWhat it does
startGuided onboarding: doctor, examples verify, init wizard, next steps.
learnRead-only concept tour for beginners.
quickNext-action recommender for newcomers.
checkAlias for verify.
prepareCheck whether your workspace is ready for an agent handoff.
recoverGenerate a recovery playbook from an error message or trace.
doctorValidate workspace health (schemas, policies, links, freshness).
actionsList all beginner-friendly actions (this list).
statusShow a trace summary or card metrics.
resetClean generated harness state (requires --confirm).
initInstall harness assets into a target workspace.
addAdd a metadata helper file (claim, evidence, or completion card).
runRun a task file or episode.
ciRun CI-oriented verification and reporting.

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

The advanced commands (handoff, verify, trace, report, clean, examples, context, benchmark, recovery, packet, intake, governance, intervention, prediction, components, evidence, episode, attribution, permissions, evolve, export, import, frozen, federation, approval-risk, agent-profile, cost, contract, explain, conformance, release, boundary, policy, scan, card, readiness, adapters, repair, uninstall, profile, …) are documented under docs/.

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.

TierUse whenMinimum evidence floorHuman approval
lightNarrow, low-ceremony work (1–3 files, near read-only).files_changed + (command_evidence or manual_rationale).Optional
standardNormal multi-step work, bounded synthesis.files_changed + command_evidence + done_checklist + prediction.Optional
deepHigh-stakes work: architectural changes, migrations, multi-dependency.Everything standard requires, plus evidence_scope, untested_regions, remaining_risks, execution_controls, rollback_policy, verification_artifacts, state.read_set, state.write_set.Required

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:

AdapterUse whenKey files
GenericYou want plain Markdown conventions, no platform lock-in.AGENTS.md
Claude CodeYou use Claude Code.CLAUDE.md, worker / verifier agents, skills
CursorYou use Cursor..cursor/rules/x-harness.mdc
OpenCodeYou use OpenCode.verify-agent.md, worker / verifier agents
AntigravityYou use Antigravity.rules + workflows under rules/ and workflows/
CodexYou use Codex.AGENTS.md

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


Documentation

DocumentWhat it covers
docs/GETTING_STARTED.mdConceptual primer: what x-harness solves and core ideas.
docs/QUICKSTART.mdStep-by-step local setup and first verify.
docs/FAQ.mdFrequently asked questions (Go vs TS, LLM usage, etc.).
docs/ARCHITECTURE.mdLayer model, validation cycle, design notes.
docs/VERIFY_GATE.mdHow the read-only verify gate works.
docs/ADMISSION_POLICY.mdFail-closed admission rules and evidence floors.
docs/SCHEMAS.mdJSON schema inventory.
docs/RECOVERY.mdRecovery routing and playbook generation.
docs/ADAPTERS.mdFull adapter guide and tier-selection reference.
docs/BOUNDARY.mdBoundary policy lint, check, and verify integration.
docs/INTAKE.mdTask intake tiering and readiness evaluation.
docs/DECISION.mdDecision-memory records (ADR-lite) and linkage.
docs/CONFORMANCE_STRICT_PROFILE.mdStrict-profile rules and verification criteria.
docs/TYPESCRIPT_MAINTENANCE.mdMaintenance policy for the TypeScript fallback.
docs/CI.mdCI integration and dual-run gates.
docs/RELEASE_SECURITY.mdRelease signing, SBOM, and provenance.
docs/RELEASE_CANDIDATE.mdRelease-candidate checklist.
docs/PACKETS.mdImmutable claim packets and chain integrity.
docs/REPORT_FORMATS.mdReport output formats (Markdown, JSON, HTML).

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: 0.99.0-rc1 (release candidate). The CLI is feature-complete for the v0.x contract, but the project is pre-1.0. Pin your version and expect minor contract changes before 1.0.
  • 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.

Ver o original no GitHub

Bom para

Relacionados