Skip to main content

Governed Agent Harness

A local control plane that governs AI-assisted software development: normative phases, fail-closed gates and human decisions bound to the exact change.

ci codeql security docs-smoke Quality gate Coverage Maintainability Security OpenSSF Scorecard release python license

English · Español · Documentation site

Contents

What it is, and what it is not

The harness is not an agent and not a model. It is the environment that governs one: it takes a structured task, drives it through nine normative phases that cannot be removed (INTENT, DISCOVERY, SPECIFICATION, PLANNING, IMPLEMENTATION, VERIFICATION, INDEPENDENT_REVIEW, DECISION, CLOSURE), grants capabilities deny-by-default, runs validators without a shell, computes the exact set of changes owned by the run against a baseline (the ChangeSet), records hash-chained events, evaluates a fail-closed gate and requires a human decision bound to the ChangeSet digest. If the code changes afterwards, the approval no longer applies.

"Run the tests" written in a prompt The same rule applied by the harness
The agent may or may not run them VERIFICATION is a mandatory phase of every run
"Tests passed" is a claim in a transcript python.pytest is a mandatory validator; its exit code and output are stored as content-addressed evidence
A missing tool looks like success, or is ignored Non-success never becomes success: BLOCKED, ERROR, INCONCLUSIVE, TIMED_OUT all keep the gate closed
"Approve" refers to a task or a conversation An approval is bound to the digest of the exact ChangeSet, configuration and policy

It is not a sandbox, not a CI service, not a replacement for Git or pull requests, and it has no native integration with a particular agent or model provider.

Stack: Python ≥ 3.12, Pydantic 2, Typer, FastAPI and Uvicorn (optional api extra), PyYAML, JSON Schema 2020-12, SQLite. License: Apache-2.0.

Concepts

Term Meaning
Harness The control environment around an agent: phases, capabilities, validators, evidence, gates and decisions.
Normative phase One of the nine mandatory phases. A workflow may not remove or reorder them.
Validator A check that returns a normalized status (PASSED, FAILED, BLOCKED, ERROR, TIMED_OUT, INCONCLUSIVE, NOT_APPLICABLE, SKIPPED, …): tests, linters, type checkers, the independent review.
Evidence / artifact An artifact is bytes stored by content digest (a diff, a tool's stdout). Evidence is the record stating what an artifact supports, in which phase, by whom. Artifacts are redacted before they are stored.
ChangeSet The files the run owns (declared patch paths, or metadata.ownedPaths) that changed against the baseline captured at the start, with a canonical digest.
Digest SHA-256 over a canonical representation: of the ChangeSet, of the configuration snapshot, of the policy, of each event (hash chain).
Capability A grant for a class of action (filesystem.write, process.execute, …) scoped to paths or commands; everything else is denied.
Gate The consolidation of the validation results and findings of the current digest into PASSED, FAILED, INCONCLUSIVE, … with reason codes.
Human decision APPROVE, APPROVE_EXCEPTION, REQUEST_CHANGES or REJECT, recorded with actor and rationale and bound to the current ChangeSet digest.

Architecture

flowchart TB
  CLI[CLI] --> APP[Application use cases]
  API[Local API and dashboard] --> APP
  APP --> ORCH[Workflow orchestrator]
  ORCH --> DOMAIN[Domain + state machine]
  ORCH --> GATES[Gate and policy engines]
  ORCH --> PORTS[Ports]
  PORTS --> RUNTIME[Trusted runtime adapters]
  PORTS --> STORES[Event and artifact stores]
  PORTS --> EXT[Extension client/SDK]
  CONFIG[Workflow + profiles + project config + locked policy] --> APP
  EXT --> PY[Python profile/extensions]
  EXT --> NODE[Node profile/extensions]
  EXT --> AGENT[Agent provider]
  EXT --> REPORT[Reporter]
flowchart LR
  I[INTENT] --> D[DISCOVERY] --> S[SPECIFICATION] --> P[PLANNING] --> M[IMPLEMENTATION]
  M --> V[VERIFICATION] --> R[INDEPENDENT_REVIEW] --> C[DECISION]
  C -->|approve| X[CLOSURE]
  C -->|request changes| M
  X -. post-run .-> T[RETROSPECTIVE]

Dependencies point inward: the domain knows no CLI, web framework, profile or provider; validators produce results but only the gate engine decides; reporters never change state. Details in ARCHITECTURE.md, the ADRs and the trust model. Diagram sources: diagrams/.

Quickstart in five minutes

Requires Python ≥ 3.12 and Git. The docs-smoke workflow runs these steps on every push, with the harness installed from source (scripts/demo_flows.py quickstart), and checks every exit code shown.

python3.12 -m venv .venv && source .venv/bin/activate
pip install "governed-agent-harness @ https://github.com/SebasBarrera/harness-engineering/releases/download/v2.0.0/governed_agent_harness-2.0.0-py3-none-any.whl" pytest

# a tiny Python project with a baseline commit
mkdir pricing-demo && cd pricing-demo && mkdir -p src/pricing tests
printf 'def apply_discount(subtotal: float, threshold: float, rate: float) -> float:\n    return subtotal\n' > src/pricing/__init__.py
printf 'from pricing import apply_discount\n\n\ndef test_below_threshold() -> None:\n    assert apply_discount(99, 100, 0.1) == 99\n' > tests/test_pricing.py
printf '[project]\nname = "pricing-demo"\nversion = "0.1.0"\n\n[tool.pytest.ini_options]\npythonpath = ["src"]\n' > pyproject.toml
printf '.harness/\n' > .gitignore
git init -q && git add . && git commit -qm baseline

harness init                                    # exit 0: writes .harness/project.yaml
curl -sSLO https://raw.githubusercontent.com/SebasBarrera/harness-engineering/develop/docs/guides/task.yaml
harness task create --file task.yaml            # exit 0
harness run start --task task_discount_rule     # exit 4: automated phases passed, waiting for you
harness status --run <run-id>                   # phases, gate PASSED, ChangeSet digest
harness gate decide --run <run-id> --decision APPROVE \
  --change-set-digest <sha256:… from status> --actor you --rationale "Criteria covered by tests"
harness trace --run <run-id> --format markdown --output trace.md

The task used here is docs/guides/task.yaml; the greenfield guide walks through the same flow with every output.

Installation

From Command
A release wheel (recommended) pip install <wheel URL from the release page>; verify it with sha256sum -c SHA256SUMS and gh attestation verify <wheel> --repo SebasBarrera/harness-engineering
A release wheel with pipx (isolated CLI) pipx install <wheel URL from the release page>, or pipx install "governed-agent-harness[api] @ <wheel URL>" for the dashboard. The harness then lives in its own environment and the validators keep running the project's python/npm from PATH, so install pytest in the project's environment, not in the pipx one. Not exercised in CI; harness --version confirms the install
Source git clone https://github.com/SebasBarrera/harness-engineering && cd harness-engineering && pip install -e ".[dev,api]"
Docker docker run --rm ghcr.io/sebasbarrera/harness-engineering:2.0.0 --help (published from v2.0.0; runs as a non-root user)

Requirements: Python ≥ 3.12 and Git (baselines and ChangeSets come from the repository). For Node.js projects, Node.js LTS and npm. The optional api extra installs FastAPI and Uvicorn for the dashboard. The harness is a Python package: it is not installed with npm or npx. Releases are on GitHub Releases and GHCR. Publication on PyPI (pip install governed-agent-harness) through a Trusted Publisher is wired into release.yml and stays off until the maintainer configures it (maintainer setup); until then use the release wheel. Spanish installation guides: docs/es/instalacion.md and docs/es/instalacion-avanzada.md.

Greenfield guide

Summary of the full greenfield guide, which shows the real output of every step:

  1. Create the project (pyproject.toml and tests, or package.json with a test script) and commit a baseline: the ChangeSet is computed against it.
  2. harness init, harness inspect (detected profile, confidence and evidence), harness doctor --path ., harness config validate.
  3. Write task.yaml: intent, requirements, acceptance criteria and, for a deterministic run, a patch implementation.
  4. harness task create --file task.yaml, then harness run start --task <id> → exit 4.
  5. harness status --run <id>, harness findings list, harness evidence list.
  6. harness gate decide … --change-set-digest <current digest> → exit 0.
  7. harness verify --run <id> checks the event chain, the records and the artifacts of the run (exit 0 or 6).
  8. harness trace --format markdown|json|jsonl|sarif, harness retrospect (recommendations are never applied automatically; harness recommendation decide records whether a person accepts, edits or rejects each one). The harness never commits: review git diff and commit yourself.

Brownfield guide

The brownfield guide reproduces the thesis case on the real repository pallets/itsdangerous 2.2.0 (GitHub tag archive, SHA-256 7b0c6d41…37f2b). What differs from a new project:

  • Clean tree or known baseline. Changes that exist before the run are part of the baseline and stay out of the ChangeSet.
  • Install the project's test dependencies where the harness runs. In the case, freezegun (declared in requirements/tests.txt) was missing and two test modules fail to collect, outside the ChangeSet: run start exits with 6. The baseline fails the same way, but pytest ran no test, so the baseline comparison that harness init writes does not count it as pre-existing (#190).
  • Fix the environment and run the task again. The failed run's changes are in quarantine (governance.stopTheLine: restore), so a new run start applies the patch: 298 tests pass, the gate PASSED and a plain APPROVE closes the run (122 events, chain valid), or close with APPROVE_EXCEPTION and a written rationale. In the evaluated 0.8.0 cut the case closed by exception.
  • Respect conventions. Detection is read-only (the case: Python, confidence 1.0 from pyproject.toml and tox.ini). Several lock files raise the Node.js confidence, but the profile always runs npm.

examples/brownfield-itsdangerous/reproduce.sh runs the whole case and checks every exit code.

Task file

A task is YAML or JSON: taskId, title, intent, requirements, acceptanceCriteria, constraints, implementation (mode: none | patch | command, patches) and metadata (for example ownedPaths). The task-file reference is generated from schemas/v1/task.schema.json. Always provide title and intent: a missing one is currently stored as the text None (issue #29).

CLI

30 commands (full reference with every option, generated from the code: docs/reference/cli.md):

Group Commands
Project init, inspect, doctor, config validate
Tasks task create, task list, task show, task questions, task clarify
Runs run start, run continue, run cancel, run list, status
Evidence evidence list, findings list, trace, retrospect
Memory memory add, memory list, memory manifest, memory approve, memory invalidate
Recommendations recommendation list, recommendation decide
Decision gate decide
Extensions and benchmarks plugins list, benchmark run, benchmark scenarios
Dashboard api serve

Every command accepts --help; the project commands take --path (default: the current directory).

Exit codes

Code Meaning
0 Success
1 Harness or integration error
2 Configuration error (no or invalid project configuration, unparsable task, failed doctor)
3 Not found (run, task or record)
4 Automated phases passed; a human decision is pending
5 Policy violation (stale digest, APPROVE over a gate that did not pass, decision outside DECISION)
6 Blocked (validation, policy, timeout or inconclusive result)
130 Cancelled

In CI, 4 is not a failure: automation reached the limit of its authority and a person must decide. See exit codes and the CI guide.

Human decisions

Decision When Guard
APPROVE The gate PASSED Refused with 5 if the gate did not pass
APPROVE_EXCEPTION Accept a change whose gate did not pass Requires a rationale; stays visible in the trace
REQUEST_CHANGES Send the run back to IMPLEMENTATION Invalidates verification, review and gate
REJECT Close without accepting

Every decision carries the current ChangeSet digest. If an owned file changes after the gate was evaluated, the old digest is refused with 5 (prior approval is stale); run continue re-evaluates the gate, which becomes INCONCLUSIVE with reason NO_MANDATORY_VALIDATIONS because the validations belong to the previous digest; record REQUEST_CHANGES, continue, and decide again. This sequence is tested on every push (scripts/demo_flows.py later-change).

Configuration

harness init writes .harness/project.yaml: profiles (auto), workflow, capability grants, validators, policies, agent providers and runtime limits. Four policies are locked and cannot be weakened: requireHumanDecision, approvalDigestBinding, mandatoryNonSuccessBlocks (always true) and retrospectiveAutoApply (always false). findingBlockSeverities (default HIGH, CRITICAL) and allowEmptyChangeSet are configurable. runtime.allowNetwork, retention and workspace.units are declarative: nothing enforces them; so is runtime.maxParallel unless governance.enforceWorkflow is on. intake.criteriaPolicy decides what INTENT does with acceptance criteria that cannot be observed ("It works."): enforce (written by init) blocks until a person answers the questions with harness task clarify, warn (a file without the key) records them as evidence and LOW findings, off skips the check. Only enforce accepts a task without acceptance criteria; INTENT then asks for them (rule C0) before anything else runs. verification.requirementTraceability decides what VERIFICATION does with a requirement that carries an identifier (A1. ..., [B12] ... or an explicit requirementId) and that no test names: enforce (written by init) records a HIGH finding, so the gate is FAILED; warn records a LOW finding; off (a file without the key) skips the check. Each acceptance criterion may declare the rung of evidence it requires on the verification ladder (L0 static to L5 human): probes of the program's behaviour, deferred evidence from CI closed with harness evidence attach, and a checklist ticked in the decision; the harness certifies the ChangeSet from recorded evidence only (see docs/guides/verification-ladder.md). Under runtime.stateDir: auto (written by init) the state database and artifacts live under the user's data directory, not in .harness/. A small, risk-free task takes a fast lane, and harness do "TEXT" --pre-approve runs it in one command with an approval given in advance that applies only if the gate passes, there is no risk factor and the task is size S (docs/guides/low-friction.md); harness metrics reports tokens, cost, delivery, time, quality and friction locally, as one self-contained HTML file among other formats, without calling a model (docs/guides/local-metrics.md). Full reference: docs/reference/configuration.md.

Technology profiles

Profile Detected by Mandatory validator Optional (when available)
Python pyproject.toml, requirements.txt, pytest.ini, … python -m pytest -q python -m ruff check --no-fix ., python -m mypy .
Node.js package.json and lock files npm test --silent (needs a test script) npm run lint, npm run typecheck (if defined)
Go, Rust, Java/Kotlin (Gradle, Maven), Swift, Android go.mod, Cargo.toml, build.gradle, pom.xml, Package.swift, AndroidManifest.xml (under toolchain.extendedProfiles) the toolchain's test command its static check

An absent optional validator is NOT_APPLICABLE; an absent mandatory executable is BLOCKED.

External agents

An agent is connected through the command provider: a program registered in agentProviders that receives the task and plan as JSON on stdin and prints one JSON object ({"status": "PASSED" | "FAILED" | "BLOCKED", "summary": "…"}, optionally with the usage the agent reports) on stdout. When the project has governed memory in force, the request also carries it under context (memory guide). examples/structured-command-agent.py is a working example. There is no native integration with Claude Code, Codex or any model API: they are connected through such a wrapper; a template is in the external agents guide. The provider only proposes a change; verification, review, the gate and the decision stay with the harness.

Since 2.0 an agent session can also drive the flow itself (embedded mode: harness mcp serve and harness init --agent-skills, see the embedded mode guide), the run can carry the team's language standards, engineering principles, testing strategy and architecture (guide), and the result can be published on GitHub, GitLab, Bitbucket, Azure DevOps or Gitea (forges and CI templates). The second review is a panel of reviewers by domain with a layered rule catalog, also usable outside a run as harness review-code and a pre-push hook (review panel).

Web dashboard and API

harness api serve --path . --host 127.0.0.1 --port 8765 (requires the api extra) serves the dashboard at / and nine routes: GET /api/health, /api/runs, /api/runs/{id}, /api/runs/{id}/trace, /evidence, /findings, /retrospective, and POST /api/runs/{id}/decision (2.0 adds more routes, listed in the reference). Since 2.0 (#18) the api section that harness init writes requires a bearer token on every route, with the roles viewer, reviewer and admin and users declared by the name of their token's variable; the token of the person who starts the server is printed once on standard error unless HARNESS_API_TOKEN provides it. A project.yaml without the section has no authentication, no roles and no multi-user support, as in 1.0.0. Either way, keep it on loopback. Reference: docs/reference/api.md.

This is not a sandbox

The harness enforces application-level controls: deny-by-default capabilities, path containment (traversal and symlink escapes are rejected), shell-free processes with timeouts, cancellation and output bounds, secret redaction before persistence, digest-bound decisions and a hash-chained event log. It does not isolate the processes it launches: an authorized command keeps the file-system, network, CPU and memory permissions of your OS user. allowNetwork is not enforced. The event chain makes tampering detectable, not impossible. Run untrusted repositories, agents or plugins only inside a container or VM. See SECURITY.md. The one exception is write confinement of agent providers: with runtime.agentSandbox: enforce, written by harness init, an agent CLI cannot write outside the workspace and its declared paths (macOS sandbox-exec, Linux bwrap), and a host without either blocks IMPLEMENTATION instead of running it unconfined.

Metrics and monitoring

Each run reports 20 process metrics (durations, attempts, correction and review cycles, validations, ChangeSets, decisions, tokens, cost) with a declared quality: OBSERVED, DERIVED, REPORTED or NOT_AVAILABLE. There are no per-person metrics, by design, and token and cost values stay NOT_AVAILABLE because no built-in provider reports usage. Read them with harness status, the JSON trace or GET /api/runs/{id}. Details: docs/metrics.md. Repository health signals and what to do with them: docs/monitoring.md.

Benchmarks

Synthetic microbenchmarks of state transitions, gate evaluation, hashing, event appends, artifact storage and governed versus direct process launch, run five times per push to develop and main, with a report and a trend. They measure runtime overhead on shared runners, not productivity or quality. See docs/benchmarks.md.

Troubleshooting

Symptom Cause and fix
run start exits 6 with status BLOCKED; the python.pytest validation says mandatory Python module 'pytest' is not installed for 'python' pytest is not installed in the environment where the harness runs. Install it and harness run continue.
Brownfield run fails with test modules that do not collect Install the project's test dependencies (for example pip install -r requirements/tests.txt) and run continue.
gate decide exits 5: prior approval is stale An owned file changed after the gate. Run harness status for the current digest, or run continue to re-evaluate.
gate decide exits 5: APPROVE is only valid for a passed automatic gate The gate did not pass. Use REQUEST_CHANGES, REJECT, or APPROVE_EXCEPTION with a rationale.
harness init exits 2: configuration already exists The project is already initialized; use --force to replace the configuration.

Limitations and known defects

There are no open behavioral defects. The v0.8.0 tag keeps the cut documented in the thesis, 0.9.0 fixed #1, #2, #9, #19, #29, #30 and #31, 1.0.0 made memory operable (#6), and 2.0.0 closed the rest of the thesis-impact backlog (#3, #4, #5, #7, #8) together with the defects the 2.0.0 evaluation found (#73–#87) (changelog).

Declared limitations: the write sandbox confines the agent's writes (sandbox-exec on macOS, bwrap on Linux) but the harness itself runs without container isolation; only local token authentication in the dashboard (none without the api section); no distributed execution; no external signature of evidence; the built-in agent adapters and the forges are tested against fake CLIs and transports; token and cost metrics only when a provider reports them (an estimated cost when a price table is configured).

Roadmap

  • A container adapter for the harness and its validators, and an external signature of evidence.
  • The built-in agent adapters and the forges exercised against live CLIs and services in CI.
  • The review study with participants planned in the thesis (OE5).

Academic context

This software is the artifact of the master's thesis Diseño y evaluación de una arquitectura de harness engineering para el desarrollo de software asistido por inteligencia artificial, con supervisión humana y retrospectiva basada en evidencia (Juan Sebastián Barrera Pulido, Maestría en Informática, Escuela Colombiana de Ingeniería Julio Garavito). The thesis documents the cut v0.8.0, which reproduces it byte for byte (provenance), and its evaluation reports only version 2.0.0 (campaign in progress, evaluation/campaign/); results of earlier versions are in the git history and the v0.8.0 tag and are not part of that analysis.

Snapshot reported by the thesis for v0.8.0 (the CI badges show the current state):

Fact v0.8.0
Python modules / lines in src/governed_harness 74 / 6,746
JSON Schema contracts · CLI commands · API routes 25 · 21 · 9
Tests 86 (core 79, E2E Python 4, E2E Node.js 1, performance 2)
Core coverage lines 80.60 %, branches 59.29 % (77.48 % combined)
Brownfield case itsdangerous 2.2.0, 298 tests, invariant ChangeSet digest

More in docs/thesis.md. To cite the software, use CITATION.cff ("Cite this repository" on GitHub).

Contributing, security and license

Metadata

Release files for governed-agent-harness 2.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for governed-agent-harness 2.0.0
File Size Uploaded Provenance Actions
governed_agent_harness-2.0.0.tar.gz 843.4 kB With provenance Details for governed_agent_harness-2.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for governed-agent-harness 2.0.0
File Interpreter ABI Platform Actions
governed_agent_harness-2.0.0-py3-none-any.whl Python 3 none any Details for governed_agent_harness-2.0.0-py3-none-any.whl

Total release size: 1.9 MB

Release files / governed_agent_harness-2.0.0.tar.gz

Download URL governed_agent_harness-2.0.0.tar.gz
Size 843.4 kB
Tags Source
SHA-256 checksum
How to use checksums
930ec05fc6840883b5561abccbdba1b37050637510f78d8f792196ea46af4810
BLAKE2b-256 checksum
How to use checksums
6340de9b81460ad09d269b6e9dfa12bd2bc76548cfa7bc9901c50737ddd29b2e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / governed_agent_harness-2.0.0-py3-none-any.whl

Download URL governed_agent_harness-2.0.0-py3-none-any.whl
Size 1.0 MB
Tags Python 3
SHA-256 checksum
How to use checksums
93320fd3ea80222147452deaa615f1ae834cfc02c74fb9b85e6b7e069165c72c
BLAKE2b-256 checksum
How to use checksums
2e481805faf944e3f35c62a81f77d668ae2741e5a822bb8ad8f1f6b0dbae6f4f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for governed-agent-harness 2.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for governed_agent_harness-2.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page