---
name: harness
description: Plan, materialize, or execute bounded agentic implementation phases with test-first steps, validated state, safe Git ownership, and configured C++ verification.
---

# Harness Workflow

Use Harness for multi-step repository implementation. Read `AGENTS.md`, `docs/HARNESS.md`, and
`docs/HARNESS_WORKFLOW.md` before creating phases or executing them. Read the approved upstream feature
bundle and `docs/TOLERANCE.md` when numerical comparison is in scope.
For feature work, read [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md) and the
dispatched feature's `FEATURED_AGENTS.md`, `PRD.md`, and `ADR.md`; keep agent reports in that feature folder.

## Authorization boundary

A Coordinator dispatch based on an approved feature bundle authorizes routine planning-file creation and
bounded local execution with the default `workspace-write` sandbox. Do not add a separate “approve this
plan” or “start implementation?” gate.

Separate explicit user authorization is still required immediately before:

- `danger-full-access`
- `--push`, tag, publish, deploy, package, or release
- destructive Git/history or filesystem operations
- licensed external solver execution, credentials, cost, or non-repository side effects

## Ownership

| Owner | Responsibility |
| --- | --- |
| Coordinator | feature state, normalized `retry_key`, correction budget, dispatch and closure |
| Planning Agent | assigned phase/index/step files and `implementation-plan.md` |
| Executor | branch, current pending Step, transport attempts, timestamps, path-scoped commits and phase advancement |
| Implementation Agent | only the Executor-selected Step, its code/tests/reports, and Step result payload |
| Hooks | pre-edit command/TDD guard and configured whole-project Stop validation |

The Executor owns at most two process/session transport attempts. They do not consume or reset the
Coordinator's one-correction workflow budget. An implementation, upstream-contract, environment, or
physics failure is returned for Coordinator classification rather than automatically looped.

## Plan materialization

Create only the files assigned by Coordinator:

```text
phases/index.json
phases/<phase>/index.json
phases/<phase>/step0.md
phases/<phase>/step1.md
...
```

The top-level entry is:

```json
{"dir": "<phase>", "status": "pending"}
```

The phase index is:

```json
{
  "project": "<project>",
  "phase": "<phase>",
  "steps": [
    {"step": 0, "name": "<kebab-case-name>", "status": "pending"}
  ]
}
```

Use contiguous Step numbers from zero. A Step must be small enough to complete
`RED -> observed failure -> minimal GREEN -> focused VERIFY -> full VERIFY` in one Codex session; do
not leave a red-only Step for a later Step.

Each `stepN.md` is self-contained and contains:

- files and upstream contracts to read, including the exact feature folder and its
  `FEATURED_AGENTS.md`, `PRD.md`, and `ADR.md`
- exact owned files, symbols and behavior
- the expected RED failure and minimal GREEN scope
- executable focused/full acceptance commands resolved from project configuration
- architecture, numerical and reference invariants
- explicit out-of-scope items and stopping conditions

Do not invent missing physics, tolerance, schema, toolchain, or reference data in a Step. Return the
issue to its owner through Coordinator.

## Local execution

Normal execution is:

```powershell
python scripts/execute.py <phase>
```

The Executor requires a valid top-level/phase schema and a worktree clean outside the selected phase
control-file allowlist before branch checkout. It also requires the Git top-level to equal the Harness
root and validates the Implementation Agent profile before changing branch or state. It injects the role,
project guardrails, completed Step summaries and the current Step. It rejects nonzero Codex exits even if
a Step claimed completion.

The Implementation Agent updates only the current Step:

- `completed` plus a non-empty `summary`
- `error` plus `error_message`
- `blocked` plus `blocked_reason`

The Executor adds timestamps. It commits implementation paths and phase metadata separately, ignores raw
`stepN-output.json`, normalizes the index before path-scoped staging, and never stages changes outside the
declared ownership boundary. Top/phase control metadata and non-current Steps are immutable during a
session; a violation is restored to the trusted snapshot and recorded as an error.
The implementation session may not run commit, push, branch, tag, merge/rebase, or history-changing Git
commands. Executor verifies symbolic branch and HEAD around every attempt. Control reads reject links and
scope escape; control/output writes use atomic replacement so a substituted link target is not overwritten.

Do not run hook scripts manually as substitutes for registered hooks. A PreToolUse pass proves neither
RED nor correctness; a Stop pass proves only the configured build/test gate.

## Elevated and remote execution

Use `danger-full-access` only after the user has authorized that exact run, the same command was shown to
fail because of the native sandbox, and execution is in a clean linked Git worktree:

```powershell
$env:FEM_HARNESS_CODEX_SANDBOX = "danger-full-access"
python scripts/execute.py <phase> --approve-danger-full-access
Remove-Item Env:FEM_HARNESS_CODEX_SANDBOX
```

The environment value alone is insufficient. The Executor rejects a primary or dirty worktree.

Use `--push` only when the user explicitly authorized pushing the completed feature branch:

```powershell
python scripts/execute.py <phase> --push
```

## Recovery and handoff

Do not manually erase failure evidence and immediately rerun. Return the exact command/exit, classification,
artifact paths and `retry_key` to Coordinator. After the owning upstream/environment/user decision is
resolved, Coordinator may reset the current Step to `pending`; stale summary/failure/block timestamps are
cleared by the Executor.

Report the final phase state, commits created, commands and exit codes, test counts, ignored/untracked raw
output, unexecuted checks and residual risks. Never call a phase complete when any Step is non-completed.