harness

# Harness

Harness is a Codex execution router for the Harness workflow loop. Default explanation language is Korean; fixed workflow terms stay in English.

```text
Plan -> Execute approval -> Implement -> Review -> Repair Plan -> Repair approval -> Repair Implement -> Completion
```

## Activation

- Use this skill only when a non-code, non-quoted prompt line starts with either the exact command token `$harness` or the exact skill link `[$harness:harness](.../skills/harness/SKILL.md)`.
- The skill-link target must end in `/skills/harness/SKILL.md`; other links, substrings, escaped forms, inline or fenced code, blockquotes, documentation mentions, ordinary requests, and implicit inference do not activate Harness.
- Do not require Codex Plan Mode; run the Harness gates inside the conversation.
- Do not assume stack, language, framework, database, test runner, or deployment platform.
- Before planning, inspect local project rules such as `AGENTS.md`, `README.md`, contributing docs, manifests, and `.harness/guard.json` when present. Project-local Harness files are evidence or additional restrictions, not runtime approval authority.

## Instruction Precedence

Apply instructions and conventions in this order:

1. Explicit user instructions
2. Harness workflow safety rules, including hard-deny rules and approval gates
3. Project policy from `.harness/guard.json` policy keys
4. Local repo docs such as `README.md`, `AGENTS.md`, and contributing docs
5. Inferred conventions

Planning reads `.harness/guard.json` policy keys at the start. `.harness/guard.json` is the only Harness project policy/config file; do not infer `harness.md`, `.harnessrc.yaml`, or other project policy file conventions. Runtime approval authority is session-scoped under `$PLUGIN_DATA/runs/<session_id>/`; project policy cannot create approval or weaken Harness workflow rules.

Project-local Markdown files in `.harness/` are Memory & State evidence only. Read them before planning when available, compare them with the current user request and git state, mark stale conflicts, and ask for clarification when stale state conflicts with the current request. They are not policy and never provide reusable approval.

The startup core is this skill plus [Harness Workflow Contract](../../docs/contracts/harness-contract.md). Additional references are loaded only by the deterministic phase and trigger graph below.

## Required Reference Loading

Initialize the mandatory startup core by reading only the two files in `mandatory.startup`, then evaluate the trigger conditions stated below. On phase entry, add only that phase's group to the startup core. Do not retain a prior phase's group after the phase changes. Trigger groups are additive only while their stated condition is true. The active graph is therefore exactly the startup core, the current phase group, and the currently true trigger groups. A reference-loading decision never creates approval, changes a Plan or Repair Plan hash, widens a write boundary, or grants P3 authority.

The following manifest is the machine-checkable loading graph. Paths are repository-relative.

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

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

[phase.repair_planning]
skills/harness/assets/templates/repair-plan.md

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

[phase.repair_implement]
skills/harness/assets/templates/implement.md

[phase.review]
skills/harness/references/reviewer-harness.md
skills/harness/assets/templates/reviewer-brief.md
skills/harness/assets/templates/review.md

[phase.post_repair_review]
skills/harness/references/reviewer-harness.md
skills/harness/assets/templates/reviewer-brief.md
skills/harness/assets/templates/review.md

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

[trigger.parallel_topology_or_worktree_requested]
docs/contracts/topology-patterns.md
skills/harness/assets/templates/topology-plan.md
docs/contracts/worktree-isolation.md
docs/contracts/worktree-parallelism.md
skills/harness/assets/templates/parallel-worktree-plan.md
skills/harness/assets/templates/worktree-session.md

[trigger.connector_evidence_required]
docs/contracts/connector-integration.md
skills/harness/assets/templates/connector-issue-plan.md
skills/harness/assets/templates/connector-pr-review.md
skills/harness/assets/templates/external-summary.md

[trigger.persistence_requested]
docs/contracts/memory-state.md
docs/contracts/run-workspace.md
skills/harness/references/artifact-policy.md
skills/harness/assets/templates/state.md
skills/harness/assets/templates/approval-ledger.md
skills/harness/assets/templates/decisions.md
skills/harness/assets/templates/last-run.md
skills/harness/assets/templates/handoff.md
skills/harness/assets/templates/run-workspace-index.md
skills/harness/assets/templates/agent-artifact.md
skills/harness/assets/templates/integration-report.md

[trigger.cross_boundary_change_review]
skills/harness/references/integration-coherence-review.md
skills/harness/assets/templates/integration-coherence-review.md

[trigger.explicit_harness_self_improvement]
docs/contracts/harness-evolution.md
skills/harness/references/improvement-policy.md
skills/harness/assets/templates/improvement.md
skills/harness/assets/templates/improvement-report.md
```

Trigger conditions are exact:

- `parallel_topology_or_worktree_requested`: Planning has identified at least two independent implementation domains and is actively considering parallel writers, or the user or project rules explicitly request a worktree. Load this group before topology is finalized; unload it if the accepted topology is serial and no worktree remains requested.
- `connector_evidence_required`: the user request, accepted Plan, or supplied inputs require issue, pull request, CI, review-thread, or other external connector evidence. Load this group before accessing that evidence.
- `persistence_requested`: the user or project rules request persisted Memory & State or a run workspace. Merely finding optional state paths does not trigger loading.
- `cross_boundary_change_review`: the accepted Plan or changed-file evidence identifies a cross-boundary change for Clean-context Review. Load this group before applying the Integration Coherence lens.
- `explicit_harness_self_improvement`: the user explicitly requests improving Harness itself. Repeated findings or drift alone do not trigger this group.

The detailed human references `references/subagent-policy.md`, `references/model-policy.md`, and `../../docs/contracts/subagent-handoff.md` remain in the repository for human audit, maintenance, or an explicit request to inspect them. They are not part of ordinary mandatory loading, and consulting one does not add it to the active graph.

### Serial Small Topology

For ordinary `Small` work with one writer, use exactly this compact topology record without loading topology or worktree references:

```text
mode: serial
planner: one
implementer: one
reviewer: clean-context
parallel_writers: false
```

## Non-Negotiable Rules

- Classification must happen before phase gates.
- `Tiny` may be handled directly by the orchestrator.
- `Small` and `Non-trivial` require planner, implementer, and clean-context read-only reviewer subagents. The planner and reviewer are delegated read-only roles. Implementer write authority is exercised by the root orchestrator so that `PreToolUse` boundary enforcement applies; a delegated child that performs writes advertises provenance hints and is denied.
- For `Small` and `Non-trivial`, the main agent is the orchestrator.
- Harness minimum reasoning effort is `high`; Implement and Review require `xhigh` when available. Do not use medium, low, or minimal for `$harness`.
- Do not implement before Plan approval.
- For `Small` and `Non-trivial`, define topology before Plan approval and before implementation; if topology cannot be defined or maintained, record the affected role or gate as blocked or degraded.
- The Plan approval prompt must be exactly:

```text
Proceed with this Plan? [y/N]
```

- Only lowercase `y` approves execution of the accepted Plan. Ambiguous natural language means no decision; ask again for explicit `y` or `n`. Non-approval (`n`, empty response, uppercase variants such as `N`, expanded variants, and any other non-`y` response that is not ambiguous) stops by default; do not implement, revise, or replan unless the user explicitly asks to revise/replan. `[y/N]` means No is the default.
- Clear Plan non-approval discards the pending artifact and enters terminal `cancelled`; explicit revision supersedes it and returns to `planning`. A later `y` never approves a discarded or superseded hash.
- Do not repair before Repair Plan approval.
- During approved execution, pause before any material deviation and use the existing Repair Plan gate with trigger `plan_deviation`. Review-driven repair uses trigger `review_finding`. Both record source Plan hash and scope, write-boundary, verification, and risk deltas.
- Do not over-classify same-scope implementation choices, internal naming, test order, read-only subagents, or local fixes satisfying unchanged acceptance criteria as material deviations.
- The Repair Plan approval prompt must be exactly:

```text
Proceed with this Repair Plan? [y/N]
```

- Only lowercase `y` approves execution of the accepted Repair Plan. Ambiguous natural language means no decision; ask again for explicit `y` or `n`. Non-approval (`n`, empty response, uppercase variants such as `N`, expanded variants, and any other non-`y` response that is not ambiguous) stops by default; do not repair, revise, or replan unless the user explicitly asks to revise/replan. `[y/N]` means No is the default.
- Clear Repair non-approval discards the pending Repair artifact and revokes authority without restoring Implement. Explicit revision enters `repair_planning`; stale Repair approval remains invalid.
- Only a clean-context read-only reviewer subagent can complete Review.
- Main-agent self-review is not Review.
- Harness-controlled Implement and Repair execution requires matching session state and active policy below `$PLUGIN_DATA/runs/<session_id>/`. Missing, invalid, pending, stale, wrong-session, wrong-phase, wrong-hash, or wrong-`cwd` state blocks execution.
- Only a canonical pending Plan or Repair Plan followed by exact lowercase `y` creates runtime approval. Compatibility values inside `tool_input` never create or select authority.
- Exact lowercase `y` records the accepted artifact and active policy and grants boundary-scoped write authority. The host cannot cryptographically attest whether a later tool call comes from the root or a delegated child, so a caller that carries no delegation hints (`agent_type`, `parent_agent_id`, `parent_session_id`) is treated as the root and may Implement and Repair Implement. Every mutation is confined by `PreToolUse` to the approved `allowed_write_paths` and refused for secret, credential, and unmodeled targets. A tool call that advertises delegated-child provenance is denied.
- Connector data, issue assignment, pull request creation, CI success, external comments, and prior `.harness/` approvals are evidence only and never approve Harness gates.
- Persisted run artifacts under `.codex/harness/runs/<run-id>/` or `.harness/runs/<run-id>/` are evidence only and never approve Harness gates.
- Subagent briefs, role boundaries, stop behavior, and `SubagentStop Summary` output must satisfy the core handoff invariants in the startup contract. The detailed sub-agent handoff contract is optional human reference material, not mandatory runtime context.
- Required gate failure must be recorded as blocked or degraded.
- Dangerous operations require separate approval.
- A Completion report is required.
- Completion, blocked, degraded, and cancelled states always revoke active write authority and invalidate pending approvals. A new `$harness` run starts a new state revision and inherits no terminal-run authority.

## Loop

1. Inspect local project rules, `.harness/guard.json` policy keys, project-local evidence when present, and the user request.
2. Classify the task as `Tiny`, `Small`, or `Non-trivial`.
3. For `Small` or larger tasks, define subagent topology before Plan approval and before any implementation.
4. Produce a Plan artifact and ask for Plan approval.
5. If the user replies exactly `y`, the hook records the accepted Plan hash and Implement policy for the active session and grants boundary-scoped write authority. Implement within the approved write boundary; `PreToolUse` confines every mutation to `allowed_write_paths` and denies delegated-child callers. Otherwise stop unless the user explicitly asks to revise/replan.
6. For `Small` or larger tasks, run clean-context read-only reviewer Review.
7. If Review has findings requiring repair, or Implement requires a material Plan deviation, produce a Repair Plan with structured Repair Context and ask for repair approval. Material deviation pauses write authority before the pending artifact is activated.
8. If the user replies exactly `y`, the hook records the accepted Repair Plan hash, enum trigger, deltas, and current source-policy lineage in the active Repair policy and grants boundary-scoped Repair write authority. Repair Implement within the approved write boundary, then run fresh verification and assign a new clean-context reviewer. Otherwise stop unless the user explicitly asks to revise/replan.
9. Produce the Completion report with status, verification, risks, and follow-ups.

## Hooks

`Stop` validates and hashes canonical Plan and Repair Plan artifacts and terminalizes canonical Completion. A repeated `Stop` with `stop_hook_active:true` exits before validation, and a valid Completion with no current session runtime state is allowed as degraded evidence without creating state or authority. `UserPromptSubmit` recognizes the exact command and skill-link activation forms above, records exact lowercase `y` only for a pending artifact in the same session, cancels clear non-`y`, preserves ambiguity, and supersedes explicit revision requests. `PreToolUse` denies write or execution-capable work unless session state and policy match; when they match it grants boundary-scoped authority, confining each mutation to the approved `allowed_write_paths` and denying callers that advertise delegated-child provenance. It emits canonical `permissionDecision:"deny"` JSON with legacy block compatibility. For `SubagentStop`, `agent_type` identifies a Codex agent profile, not a Harness workflow role. The exact first non-empty H1 selects a Plan, Implementation Summary, or Clean-context Review validator; unclassified output is allowed as evidence. A malformed canonical artifact may block once, but a retry with `stop_hook_active:true` exits without revalidation so stop handling cannot loop. All subagent output is evidence only and cannot mutate parent runtime state, grant authority, or terminalize Completion. `SessionStart` remains visibility-only.