Harness

Harness

Harness is an explicit, bounded workflow. The normal path has one human gate. A material Plan Amendment or a paused Repair Resume adds one exact gate.

Plan -> exact y -> executing -> verifying -> reviewing -> Completion
                    ^                         |
                    |-- auto_repairing (max 3) --|

paused_* -> Repair Resume -> exact y -> one bounded continuation
MATERIAL_AMENDMENT -> Plan Amendment -> exact y -> continue

Activation

• Activate only when a non-code, non-quoted prompt line starts with exact $harness, exact $harness:harness, a filesystem Harness skill link, or an exact personal-marketplace app plugin link [@harness](plugin://harness@personal).
• Mentions, examples, escapes, fenced or indented code, blockquotes, HTML comments, raw HTML pre/code/script/textarea blocks, project files, prior tasks, and inferred intent never activate Harness.
• Explicit activation creates planning state for the official session and normalized repository cwd.

Loading

Read the startup pair and only the template required for the current artifact.

[mandatory.startup]
skills/harness/SKILL.md
docs/contracts/harness-contract.md

[phase.planning]
skills/harness/assets/templates/plan.md

[phase.plan_amendment]
skills/harness/assets/templates/plan-amendment.md

[compat.strict_manual_repair_plan]
skills/harness/assets/templates/repair-plan.md

[phase.review]
skills/harness/assets/templates/review.md

[phase.repair_record]
skills/harness/assets/templates/repair-record.md

[phase.pause]
skills/harness/assets/templates/pause-report.md

[phase.repair_resume]
skills/harness/assets/templates/repair-resume.md

[phase.completion]
skills/harness/assets/templates/completion-report.md

[trigger.hook_behavior_or_config_change]
docs/contracts/hook-decision-protocol.md

[trigger.p3_or_write_boundary_change]
docs/contracts/p3-policy-lifecycle.md

[trigger.runtime_acceptance_or_release_validation]
docs/runtime-acceptance.md

Startup reads exactly the mandatory pair. An artifact phase replaces the prior phase template. The compatibility template loads only for an explicitly chosen strict/manual Repair Plan; it is not a default phase. A trigger group is added only while its named concern is active. Trigger references are never part of an always-loaded bundle.

Artifact Format

Canonical generation uses compact exact-heading Markdown from the phase templates. Current v9 runtime dispatch accepts # Plan, # Plan Amendment, # Clean-context Review, # Repair Record, # Repair Resume, and # Completion with their exact ordered H2 sections; structured strategy and evidence objects remain embedded JSON. # Repair Plan has a separate exact parser and template only for strict/manual compatibility. Stop does not dispatch it and it cannot create pending approval, report Approval activated, grant authority, or transition state. Top-level JSON artifacts and historic legacy-verbose shapes such as # Completion Report are unsupported: direct parser validation fails, while the Stop dispatcher leaves those unrecognized shapes inert instead of compatibility-routing them. Older harness.verification-evidence.v1 inside a canonical artifact is rejected rather than migrated implicitly.

Adaptive Team

• The root orchestrator-executor owns the full user context and final Plan. It is the only writer and performs implementation, TDD, integration, bounded Auto Repair, evidence collection, and Completion.
• A read-only planner is optional; a read-only Plan critic is optional under the same conditions. Use one only for ambiguous requirements, multiple credible designs, API/schema/security/database changes, multi-module or high-risk work, or an explicit user request.
• A read-only specialist is optional. Use one only for broad code discovery, test-failure triage, stack-trace or log analysis, API/database/security impact analysis, or independent comparison of hypotheses.
• Optional read-only helpers default to zero, are capped at two, and have maximum delegation depth one. Delegated children never write or spawn deeper.
• Helper output is evidence for root judgment, never authority. No implementer subagent is mandatory; implementer=root and parallel_writers=0 remain canonical.
• Every successful Completion requires a separate fresh clean-context, read-only Review; main-agent self-review does not qualify. This mandatory Reviewer is distinct from the optional helper budget and is always required for behavioral Small and Non-trivial work. Tiny Plans need not declare reviewer topology, but successful Completion still needs the Review.

The Execution strategy selects execution_mode=native or execution_mode=guided. In native, the model decides whether read-only delegation is useful and Harness does not pin a mandatory agent count or role topology; this is suitable for Ultra use. In guided, recommend zero to two helpers only for independent read-heavy work. Legacy mode-less serial Plans remain parseable without inferring a mode. The current official hook payloads do not provide effort, so never auto-detect Ultra from model or another heuristic; Plan metadata selects the mode. Helper limits are root orchestration policy. Hooks neither create nor count agents and do not infer a topology from agent_type.

Root-only writing is an orchestration invariant. Current Codex PreToolUse input does not host-attest root versus child. The hook denies explicit delegation hints but treats provenance-less calls as identity-unknown and keeps them inside the accepted boundary, exact-command, unknown-mutator, and hard-danger checks.

Plan Gate

Emit the canonical # Plan after classifying the task and inspecting local rules. Write Boundary contains repository-relative paths or the exact prose sentinel None. Exact full shell commands are listed only when their writes cannot be modeled.

New Plans include one verification_strategy object. Bug fixes use regression_first, behavior changes use tdd, refactors use characterization, and docs, CI/config, packaging, or migration work uses verification_first. Required verification cannot be weakened during an in-plan repair.

New Plans also include exactly this auto_repair policy object:

{
  "auto_repair": {
    "enabled": true,
    "max_rounds": 3,
    "repeated_finding_limit": 2,
    "no_progress_limit": 2,
    "same_write_boundary_only": true,
    "verification_must_not_weaken": true,
    "material_delta_requires_approval": true
  }
}

The object is part of the exact accepted Plan bytes and hash. Its fields map to the bounded v9 repair counters, subset authority, and circuit breakers.

The gate is exactly:

Proceed with this Plan? [y/N]

Only the logical lowercase token y approves. Transport may append exactly one LF or CRLF. Spaces, case variants, extra lines, and other tokens do not approve. Continue only after runtime reports Approval activated.

Execution And Repair

The initial exact Plan approval covers bounded Auto Repair without another y. Runtime stores immutable accepted authority in accepted_policy and the currently effective authority in active_policy, bound by active_policy_id. Root mutation is permitted only in executing and permitted auto_repairing states. Auto Repair uses a child policy bound to the parent Plan hash and accepted policy id; paths, exact commands, and capabilities remain subsets, and verification is unchanged or stronger.

The default repair policy is:

• max_repair_rounds=3
• repeated_finding_limit=2
• no_progress_limit=2
• same write boundary only
• verification non-weakening
• material delta requires Plan Amendment approval

Classify a finding as IN_PLAN_REPAIR only when all of these remain true:

• objective and acceptance criteria are unchanged;
• scope and write boundary are unchanged, and every changed file was planned and remains inside that boundary;
• the accepted public-contract/API/schema/dependency/configuration/deployment deltas and exact command allowlist are unchanged;
• no new security, secret, database, data, production, or other material risk appears;
• accepted verification is retained or strengthened; and
• root remains the only writer, there is no parallel-writer overlap, and the accepted Plan approach is retained.

If any condition is false or uncertain, classify it as MATERIAL_AMENDMENT. The initial approval never bypasses the hard dangerous command guard or a distinct human gate required for secrets, databases, data, or production. Where the host/product cannot provide such a gate, pause or block; do not claim the hook can execute a native slash command to obtain it.

TDD iterations and repeated test commands are not repair rounds. A round is consumed only when an actual fix cycle begins from a Verification finding or a canonical Clean Review REPAIR_REQUIRED finding.

A canonical Repair Record binds the accepted Plan, source Review round, Repair round, finding IDs, changed files, fresh verification, and progress fingerprints. Repair Record is evidence, never approval authority. It may consume an already verified counter and moves valid work to revoked verifying; the following matching Review may enter reviewing, start another bounded repair, or pause. It cannot grant, widen, or resume authority. No-progress is measured from the Record's bound before/after diff and semantic verification progress fingerprints; summary-only wording changes do not count as progress. The following Review repeating the post-repair evidence does not count as a second no-progress cycle.

Clean Review

The mandatory Reviewer runs in a separate clean context and stays read-only. Root must stop mutation before starting the Reviewer and remain quiescent until the exact Review relay completes. In revoked verifying and reviewing, runtime permits only a root spawn whose task and prompt explicitly identify a clean-context read-only Reviewer. This is a review-only orchestration exception, not mutation authority; delegated-child, unqualified, and paused-state spawns remain denied. Its canonical Review arrives through SubagentStop; runtime records a session/state/artifact-bound non-authority attestation. Root then relays the exact artifact through Stop without changing its verdict, findings, diff revision, or evidence fingerprints. An unattested root-authored Review is denied. Verdicts are PASS, PASS_WITH_NOTES, REPAIR_REQUIRED, and BLOCKED.

• PASS or PASS_WITH_NOTES enters reviewing with authority revoked.
• REPAIR_REQUIRED starts the next Repair only when budget and progress limits allow it and only with a same-or-narrower Auto Repair child policy.
• The fourth Repair is never started under the default budget.
• A second consecutive observation of the same finding enters paused_no_progress.
• A second consecutive Repair Record with unchanged diff and verification enters paused_no_progress.
• BLOCKED or unavailable required verification enters paused_blocked.

Every post-repair Review uses fresh verification and the latest diff revision.

Pause And Repair Resume

Every paused_* state has authority_status=revoked and rejects mutation. A paused mutation policy is inactive, successful Completion is forbidden, and the only continuations are additional Repair Resume budget, Plan Amendment, or Cancel. A Pause Report records completed rounds, remaining findings, verification trend, latest diff revision, repeated/no-progress evidence, and these choices: Repair Resume, Plan Amendment, or Cancel. Pause never creates pending approval or successful Completion by itself.

A Repair Resume binds the accepted Plan hash, exact paused-state revision, latest diff revision, and verification fingerprint. Stale bindings are rejected. Additional budget is applied only after:

Proceed with this Repair Resume? [y/N]

Only the logical lowercase token y, with at most one LF or CRLF, resumes the same boundary and non-weakened verification policy through a derived subset child. Runtime must report Approval activated with gate Repair Resume.

Strict/Manual Repair Plan Compatibility

Keep # Repair Plan only for an explicitly selected strict/manual workflow. Its exact Repair Context declares the source Plan hash, finding, exhaustive no-delta classification evidence, unchanged or strengthened verification, root-only topology, retained approach, and bounded Repair Scope. It ends with:

Proceed with this Repair Plan? [y/N]

This prompt is a compatibility/manual human gate, not a current runtime gate. The direct parser validates it fail-closed, but Stop leaves it inert. Parsing the artifact or receiving y does not create a pending artifact, emit Approval activated, grant authority, or change state. The default workflow uses the initial Plan approval instead. Use Plan Amendment for material or ambiguous deltas and Repair Resume for additional budget.

Material Amendment

Use MATERIAL_AMENDMENT for any objective or acceptance-criteria change, scope/write-boundary expansion, file outside the accepted Plan, API/public contract/schema/dependency/configuration/deployment change beyond the accepted delta, new security/secret/database/data/production risk, reduced or replaced verification, parallel-writer overlap, or abandonment of the accepted Plan approach. Ambiguity is material.

The canonical Amendment binds the source Plan hash and declares exactly these deltas: objective, acceptance criteria, scope, write boundary, verification, and risk. Its Write Boundary and Verification sections contain the complete effective policy after approval. At least one declared delta must be material.

The gate is exactly:

Proceed with this Plan Amendment? [y/N]

Only exact lowercase y replaces the accepted policy, records parent policy lineage, and returns to executing. Stale Amendment bindings grant nothing.

Completion

Successful Completion requires a fresh canonical PASS or PASS_WITH_NOTES Review, matching accepted Plan hash, current accepted Amendment hash or null, diff revision, verification integrity fingerprint, and structured evidence. reviewing authority is already revoked; terminal Completion preserves that revocation. Missing, blocked, skipped-required, weakened, tampered, or stale evidence cannot complete.

Runtime

• $PLUGIN_DATA/runs/<session_id>/state.json is the sole authority commit.
• v9 validates accepted_plan_hash, active_policy_id, accepted/effective policy lineage, repair counters, latest finding IDs, integrity and progress fingerprints, pause reason, Review round, and explicit authority_status atomically.
• A v8 state cannot authorize v9 writes. Explicit activation migrates it to fresh planning state with authority revoked; older schemas stay fail-closed.
• SessionStart is a no-op.
• UserPromptSubmit, PreToolUse, SubagentStop, and Stop directly execute $PLUGIN_ROOT/hooks/harness_guard.py.
• UserPromptSubmit runtime diagnostics add context but never block prompt submission and never manufacture authority.
• PreToolUse denies explicit delegated identity hints and enforces accepted write paths, exact approved unmodeled commands, and hard-danger rules. It also pauses and revokes authority for a newly observed boundary expansion, unmodeled mutation target, or dangerous risk. It does not claim host-attested caller identity.
• Host interception covers documented Bash, apply_patch, and MCP call surfaces; current unified_exec shell interception is incomplete. Synthetic Edit/Write aliases are regression inputs, not claimed native payloads.
• SubagentStop leaves planner, critic, specialist, and unclassified helper output inert. Only a canonical Clean Review may create $PLUGIN_DATA/runs/<session_id>/evidence/pending-review-attestation.json. The sidecar contains evidence bindings only, never policy or authority, and cannot change state.json.
• Root Stop requires an exact current attestation before Review transition and consumes it on the successful state write. Missing, modified, stale, replayed, or cross-session evidence is denied as self-review.
• Any subsequently permitted intercepted mutation removes the pending attestation before the tool runs, so changed work requires a new Review. Failure to invalidate it denies the mutation.
• The registered surface has no Reviewer-start event. It cannot detect a Root mutation that happens after the Reviewer reads the diff but before SubagentStop; reviewer-window quiescence remains an orchestration invariant, not a runtime-attested guarantee.
• agent_type is a runtime profile, not a planner/implementer/reviewer role. Hooks neither infer effort nor directly execute native slash commands.

Direct hook execution requires the installed PLUGIN_ROOT to survive for the task lifetime. Do not reinstall or rotate the plugin during an active task; start a new task after reinstall.

Runtime authority is never reconstructed from conversation, git state, project files, prior sessions, cache digests, or installed-path assumptions.