Skip to content

Python API

The CLI and the local API are thin layers over HarnessApplication. Scripts that need the same behavior (for example scripts/metrics_report.py) should use it instead of reading the SQLite state directly. The package ships a py.typed marker. The API below is generated from the source code and follows the version of this documentation; it is not a stability guarantee for the research beta.

governed_harness.application.HarnessApplication

Bases: ReviewCodeCommands

notices = [] instance-attribute

Warnings for the person (the CLI prints them on standard error).

init(path, *, force=False, gitignore=False, example_task=False, agent_skills=False, ignore_file=IgnoreFile.EXCLUDE)

Write .harness/project.yaml. The CLI also asks for the ignore entry and the example task (gitignore/example_task); the Python API leaves the workspace untouched beyond .harness/ unless asked. The entry goes to the repository's info/exclude (ignore_file, #86: the tree of an existing repository stays clean), or to the .gitignore outside a Git repository or with IgnoreFile.GITIGNORE. agent_skills (#56) also writes the skill of the governed flow for Claude Code and Codex.

validate_config(path)

The resolved configuration, the settings that are declared but not applied (declarative) and a warning for each one this project relies on.

clarify_task(path, *, task_id, answers_file, actor_id=None, actor_type=ActorType.HUMAN, relayed=False)

Answer the clarification questions INTENT asked about a task.

relayed (embedded mode, #56): the person's answers reached the harness through an agent session (the MCP server); the record names the person and says so.

The answers file maps question ids to answers and may replace criteria, add criteria and add requirements. The harness stores the revised task and a clarification record (actor, questions, answers, previous and new task digest) on the event chain of the run that asked; continue_run then assesses the revised task in INTENT.

Only a human actor may answer. Unknown question ids and empty answers are rejected (exit code 2), as is a task with a run past INTENT (exit code 5).

list_clarifications(path, task_id)

The clarification requests asked about a task, the answers recorded for them and the open request: the latest one asked about the current revision of the task.

start_run(path, task_id, provider=None, *, isolate=None)

Create a run and execute the phases. With isolate worktree (or workspace.isolation.mode: worktree) the run happens in a Git worktree of its own on a new branch (#55).

cleanup_run(path, execution_id)

Remove the worktree of a finished isolated run (never its branch, #55).

verification(path, execution_id)

The verification plan, preflight, certification, deferred items and checklist of a run.

decide_verification(path, *, execution_id, rationale, actor_id=None, continue_after=True)

A person decides to continue a run whose preflight is UNAVAILABLE, uncertified for what cannot be verified here.

confirm_contract(path, *, task_id, digest, actor_id=None, pre_approve=False, hours=None, rationale='')

A person confirms the operational contract of a task's revision (#55) and, with pre_approve (friction.preAuthorization, #58), approves the run in advance under the condition gate passed, no risk factor, size S, until hours from now.

attach_evidence(path, *, file, execution_id=None, task_id=None, item=None, manual=False, evidence_format='auto', case=None, commit=None, note=None, actor_id=None)

Close a deferred verification with external evidence, or attach a person's evidence to a run (checklist) or a task (intake context) (#55).

config_lint(path)

Contradictions between the configuration and the agent instruction files (#55).

registry()

The projects whose run registry lives in the state directory (runtime.stateDir: auto), with their latest runs: one dashboard for several repositories (#55).

routing_calibration(path)

Cost per approved task of the routing decisions recorded in the project (#44).

agent_calls(path, execution_id, kind=None, iteration=None)

The agent calls of a run, the iterations each agent used and, for one call, exactly what was sent and what the parent received (#97).

budget(path, execution_id)

Usage of a run and its task against the budget limits (#42).

raise_budget(path, *, execution_id, scope, metric, limit, rationale, actor_id=None)

Raise a budget limit of a run (a person, recorded); run continue resumes it.

acceptance(path, execution_id)

The acceptance tests proposed or frozen for a run (#52).

decide_acceptance(path, *, execution_id, decision, digest, rationale, actor_id=None, continue_after=True)

Approve or reject the proposed acceptance tests (digest-bound, a person).

decide_acceptance_dispute(path, *, execution_id, decision, digest, rationale, actor_id=None, continue_after=True)

Uphold or revise the frozen acceptance tests an agent disputes (digest-bound, a person; #94).

plan(path, execution_id)

The decomposition of a run and the progress of its sub-tasks (#39).

decide_plan(path, *, execution_id, decision, digest, rationale, actor_id=None, continue_after=True)

Approve or reject the decomposition PLANNING proposed (digest-bound, a person).

check(path, execution_id=None)

harness check: the gate's validators and diff checks on the workspace, with nothing recorded (it reads the configuration and the run's check state only).

quarantine_run(path, execution_id, actor_id=None)

Quarantine the changes of a stopped run and restore the baseline (governance.stopTheLine); a person only.

rule_health(path, *, since_days=None)

How each rule and validator behaved across the runs of the project.

record_outcome(path, *, execution_id, kind, summary, actor_id=None, reference=None, observed_at=None)

Link an incident, revert, hotfix or regression to a run (a person only).

do(path, text, *, criteria=(), owned_paths=(), title=None, provider=None, pre_approve=False, hours=None, actor_id=None)

harness do: create a task from text, run it and, with pre_approve, approve it in advance under the condition gate passed, no risk factor, size S. Returns the task, the run, the lane and what waits for the person (questions or the decision).

answer_questions(path, *, task_id, answers, actor_id=None)

Answers typed on the terminal by harness do (as task clarify with a file).

decide_batch(path, items, *, rationale, actor_id=None, continue_after=True)

Decisions on several runs of the inbox, each bound to its own ChangeSet digest: a stale digest or a refused decision is reported for that run and the others are still recorded.

metrics(path, *, filters, prices_file=None, narrative=False)

harness metrics: the report (zero model calls) and its settings; with narrative one call to metrics.narrative.command, on demand.

inbox(path)

Runs of the project waiting for a person (decision or clarification answers) and, since #55, deferred verifications waiting for evidence and preflights waiting for a decision; since #73 every other wait before DECISION (plan approval, decomposition, acceptance tests, architecture, operational contract).

decide_gate(path, *, execution_id, decision, change_set_digest, actor_id=None, rationale, continue_after=True, default_actor=DEFAULT_CLI_ACTOR, exception=None, acknowledged_risks=(), change_requests=(), checked_items=())

Record a human decision. Under review.exceptions an APPROVE_EXCEPTION also records an exception with an expiry (expires_in/expires_at, else review.exceptionDays), a scope (rule[:path] entries, else the blocking findings of the gate), alternative evidence and a follow-up (exception).

Without actor_id the decider is the Git user under governance.deciderIdentity: git (default_actor with a notice when Git has no identity) and default_actor otherwise; an actor id of an agent, a validator or the harness is refused (exit 5).

decision_summary(path, execution_id)

What a person is about to decide on: the phase, the gate result and the ChangeSet the decision would be bound to (read-only; used by the interactive confirmation).

verify(path, execution_id=None)

Verify one run, or every run of the workspace when execution_id is None: the event chain, the anchor of its head, the records against the events and the artifacts against their digests. Never raises on a failed check; valid is false.

export_bundle(path, execution_id, output)

Write the portable evidence bundle of a run (delivery.bundle). Under governance.verifyRecords the run is verified first, as for trace.

verify_bundle(bundle) staticmethod

Verify a bundle without a workspace or a project configuration.

verify_approval(path, *, base, head='HEAD', bundles=(), use_workspace=True) staticmethod

Whether the range base..head is a ChangeSet a person approved (delivery.approval); needs a Git repository, not a project configuration.

publish_pull_request(path, execution_id, *, pull_request, repository=None, transport=None, sarif=None, commit_sha=None, transport_override=None, forge=None)

Post the decision brief of a run on a pull request and upload its SARIF report.

Since #56 any forge: with forge (or delivery.forge), or when origin is not a GitHub remote, the forge layer posts the comment and the forge's quality report.

create_pull_request(path, execution_id, *, head=None, base=None, title=None, labels=(), draft=None, forge=None, repository=None, transport=None, transport_override=None)

Open a pull or merge request from the run's closure branch on its forge (#56).

pull_request_status(path, execution_id, *, commit_sha, target_url=None, forge=None, repository=None, transport=None, transport_override=None)

Set the commit status of the run on its forge (#56).

standards(path, *, pack=None, files=())

The language standards packs of the project (#56): detected and effective packs, their cards, the tools the repository configures and, for files, the cards an implement call and the review checklist would get. Works without a project too.

architecture(path)

The architecture of the project: configuration, survey or ADR, rules in force.

decide_architecture(path, *, execution_id, digest, rationale, decision=None, option=None, actor_id=None, continue_after=True, style=None)

Approve or reject inferred layer rules, or choose an architecture option (#56) or, under architecture.catalogue: experts, a style of the catalogue (#97).

project(path)

New or existing, packs, testing strategy, architecture and forge, without a call.

forge(path)

The forge the workspace resolves to, without calling it.

trace(path, execution_id, format='markdown')

Export the trace of a run. Under governance.verifyRecords the run is verified first and a run that does not verify is not exported (exit code 6).

gc(path, *, apply=False)

Apply retention.artifactDays and retention.eventDays to the runs that ended; without apply only report what would be removed.

add_memory(path, *, level, key, value, actor_id=None, task_id=None, execution_id=None, valid_until=None, supersedes=None, sensitive=False, approved=False)

Record a memory entry. Normative, project and retrospective entries only enter a context once approved; the approval is an explicit act of the recorded actor.

list_memory(path, *, task_id=None, execution_id=None)

List every memory record of the project with its status for the given task and run: active, superseded, expired, unapproved, limit or out_of_scope.

memory_manifest(path, execution_id)

Return the context manifest recorded for a run: the memory it applied and the candidates it left out, as they were when the run was planned.

approve_memory(path, *, memory_id, actor_id=None)

Approve a normative, project or retrospective record. The approval is a new record that supersedes the proposal, so the proposal and its approver both stay on record.

invalidate_memory(path, *, memory_id, actor_id=None, reason)

Invalidate a record without deleting it: an approved, already expired record supersedes it and keeps who invalidated it and why.

list_recommendations(path, execution_id)

List the recommendations of a run with the decision recorded for each, if any.

decide_recommendation(path, *, execution_id, recommendation_id, decision, actor_id=None, rationale, statement=None)

Record the decision of a person on a retrospective recommendation.

The decision is kept as retrospective memory. An accepted or edited recommendation is approved and enters the context of later runs; a rejected one is kept as history and never enters a context. Nothing else changes: rules, gates and configuration are only modified by a person through a versioned change.

resolve_run(path, reference)

The run id a reference names: an exact id, latest or a unique prefix.

review(path, execution_id, *, include_diff=False)

The decision brief of a run (see application.review).

list_exceptions(path, *, status='all', expiring_within=None)

The exceptions of the project with their status (ACTIVE or EXPIRED), days left and the runs whose gate relied on them.

show_artifact(path, reference)

An artifact's descriptor and its content, read with digest verification. The reference is artifact://sha256/<hex>, sha256:<hex> or a unique hex prefix of at least 6 characters.

Exit-code errors

governed_harness.domain.errors

HarnessError

Bases: Exception

Base error with a stable exit code for CLI/API translation.

NonHumanActorError

Bases: PolicyViolationError

A human act (a decision, an approval, an answer) named an agent, validator or harness actor; exit code 5.

IntegrityError

Bases: HarnessError

The record of a run did not verify (event chain, records, artifacts or anchor) and the command refuses to use it; exit code 6.