Metadata-Version: 2.4
Name: governed-agent-harness
Version: 2.0.0
Summary: Technology-neutral research prototype for governing AI-assisted software development
Author: Juan Sebastián Barrera Pulido
License: Apache-2.0
Project-URL: Homepage, https://github.com/SebasBarrera/harness-engineering
Project-URL: Documentation, https://sebasbarrera.github.io/harness-engineering/
Project-URL: Repository, https://github.com/SebasBarrera/harness-engineering
Project-URL: Issues, https://github.com/SebasBarrera/harness-engineering/issues
Project-URL: Changelog, https://github.com/SebasBarrera/harness-engineering/blob/develop/CHANGELOG.md
Keywords: ai-agents,software-engineering,human-in-the-loop,governance,harness
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3,>=2.8
Requires-Dist: typer<1,>=0.12
Requires-Dist: PyYAML<7,>=6
Requires-Dist: jsonschema<5,>=4.23
Requires-Dist: referencing<1,>=0.35
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: pytest-cov<8,>=5; extra == "dev"
Requires-Dist: ruff<1,>=0.6; extra == "dev"
Requires-Dist: mypy<3,>=1.11; extra == "dev"
Requires-Dist: httpx<1,>=0.27; extra == "dev"
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: types-PyYAML>=6; extra == "dev"
Requires-Dist: types-jsonschema>=4.23; extra == "dev"
Provides-Extra: api
Requires-Dist: fastapi<1,>=0.115; extra == "api"
Requires-Dist: uvicorn<1,>=0.30; extra == "api"
Provides-Extra: all
Requires-Dist: fastapi<1,>=0.115; extra == "all"
Requires-Dist: uvicorn<1,>=0.30; extra == "all"
Dynamic: license-file

# 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](https://github.com/SebasBarrera/harness-engineering/actions/workflows/ci.yml/badge.svg?branch=develop)](https://github.com/SebasBarrera/harness-engineering/actions/workflows/ci.yml)
[![codeql](https://github.com/SebasBarrera/harness-engineering/actions/workflows/codeql.yml/badge.svg?branch=develop)](https://github.com/SebasBarrera/harness-engineering/actions/workflows/codeql.yml)
[![security](https://github.com/SebasBarrera/harness-engineering/actions/workflows/security.yml/badge.svg?branch=develop)](https://github.com/SebasBarrera/harness-engineering/actions/workflows/security.yml)
[![docs-smoke](https://github.com/SebasBarrera/harness-engineering/actions/workflows/docs-smoke.yml/badge.svg?branch=develop)](https://github.com/SebasBarrera/harness-engineering/actions/workflows/docs-smoke.yml)
[![Quality gate](https://sonarcloud.io/api/project_badges/measure?project=SebasBarrera_harness-engineering&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=SebasBarrera_harness-engineering)
[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=SebasBarrera_harness-engineering&metric=coverage)](https://sonarcloud.io/summary/new_code?id=SebasBarrera_harness-engineering)
[![Maintainability](https://sonarcloud.io/api/project_badges/measure?project=SebasBarrera_harness-engineering&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=SebasBarrera_harness-engineering)
[![Security](https://sonarcloud.io/api/project_badges/measure?project=SebasBarrera_harness-engineering&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=SebasBarrera_harness-engineering)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/SebasBarrera/harness-engineering/badge)](https://securityscorecards.dev/viewer/?uri=github.com/SebasBarrera/harness-engineering)
[![release](https://img.shields.io/github/v/release/SebasBarrera/harness-engineering)](https://github.com/SebasBarrera/harness-engineering/releases)
[![python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)](pyproject.toml)
[![license](https://img.shields.io/github/license/SebasBarrera/harness-engineering)](LICENSE)

English · [Español](README.es.md) · [Documentation site](https://sebasbarrera.github.io/harness-engineering/)

> [!WARNING]
> Research beta. **This is not a sandbox**: the commands the harness runs keep the permissions of
> your OS user, and the local dashboard authenticates with a local token only when `project.yaml`
> has the `api` section that `harness init` writes. Read
> [This is not a sandbox](#this-is-not-a-sandbox) before using it on code you do not trust.

## Contents

- [What it is, and what it is not](#what-it-is-and-what-it-is-not)
- [Concepts](#concepts)
- [Architecture](#architecture)
- [Quickstart in five minutes](#quickstart-in-five-minutes)
- [Installation](#installation)
- [Greenfield guide](#greenfield-guide)
- [Brownfield guide](#brownfield-guide)
- [Task file](#task-file)
- [CLI](#cli)
- [Exit codes](#exit-codes)
- [Human decisions](#human-decisions)
- [Configuration](#configuration)
- [Technology profiles](#technology-profiles)
- [External agents](#external-agents)
- [Web dashboard and API](#web-dashboard-and-api)
- [This is not a sandbox](#this-is-not-a-sandbox)
- [Metrics and monitoring](#metrics-and-monitoring)
- [Benchmarks](#benchmarks)
- [Troubleshooting](#troubleshooting)
- [Limitations and known defects](#limitations-and-known-defects)
- [Roadmap](#roadmap)
- [Academic context](#academic-context)
- [Contributing, security and license](#contributing-security-and-license)

## 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

```mermaid
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]
```

```mermaid
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](ARCHITECTURE.md), the [ADRs](docs/adr) and the
[trust model](docs/architecture/trust-model.md). Diagram sources: [`diagrams/`](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.

```bash
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`](docs/guides/task.yaml); the
[greenfield guide](docs/guides/greenfield.md) 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](docs/maintainer-setup.md#pypi)); until then use the release
wheel. Spanish installation guides: [`docs/es/instalacion.md`](docs/es/instalacion.md) and
[`docs/es/instalacion-avanzada.md`](docs/es/instalacion-avanzada.md).

## Greenfield guide

Summary of the [full greenfield guide](docs/guides/greenfield.md), 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](docs/guides/brownfield.md) 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](docs/reference/task-file.md) is generated from
[`schemas/v1/task.schema.json`](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](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](docs/reference/exit-codes.md) and the [CI guide](docs/guides/ci-integration.md).

## 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](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](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](docs/guides/local-metrics.md)).
Full reference: [docs/reference/configuration.md](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](docs/guides/memory.md)).
`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](docs/guides/external-agents.md). 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](docs/guides/embedded-mode.md)),
the run can carry the team's language standards, engineering principles, testing strategy and
architecture ([guide](docs/guides/engineering.md)), and the result can be published on GitHub,
GitLab, Bitbucket, Azure DevOps or Gitea ([forges and CI templates](docs/guides/forges.md)).
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](docs/guides/review-panel.md)).

## 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](docs/reference/api.md#authentication-and-roles).

## 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](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](docs/metrics.md). Repository health
signals and what to do with them: [docs/monitoring.md](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](https://sebasbarrera.github.io/harness-engineering/benchmarks/report/) and a
[trend](https://sebasbarrera.github.io/harness-engineering/benchmarks/trend/). They measure runtime
overhead on shared runners, not productivity or quality. See [docs/benchmarks.md](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](CHANGELOG.md)).

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**](https://github.com/SebasBarrera/harness-engineering/releases/tag/v0.8.0), which reproduces
it byte for byte ([provenance](docs/provenance.md)), and its evaluation reports only version 2.0.0
(campaign in progress, [`evaluation/campaign/`](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](docs/thesis.md). To cite the software, use [CITATION.cff](CITATION.cff)
("Cite this repository" on GitHub).

## Contributing, security and license

- [CONTRIBUTING.md](CONTRIBUTING.md): setup, verification commands, branch flow and the rules that
  protect the evaluated cut. [Code of conduct](CODE_OF_CONDUCT.md). [Support](SUPPORT.md).
- [SECURITY.md](SECURITY.md): report vulnerabilities privately through GitHub.
- Licensed under the [Apache License 2.0](LICENSE).
