---
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 permits at most two transport attempts, including the initial attempt, only when its
process wrapper observes a timeout and the Step has not reported a terminal result. A nonzero exit
(including 124) alone is not timeout evidence. Reported `error`/`blocked` results are preserved without
retry even on nonzero exit. Recognized sandbox-helper failures block even on zero exit. These attempts
do not consume or reset the Coordinator's one-correction workflow budget.

## 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",
      "owned_paths": ["src/example.cpp", "tests/example_test.cpp"]
    }
  ]
}
```

Replace the example paths with the Step's approved source/header/test/build/report files. `owned_paths`
is a Planning-owned array of exact repository-relative files, not directories or globs. `[]` permits
no implementation-file changes; it is not equivalent to a missing field. Do not include Git internals
or `phases/` control files. Paths cannot escape through traversal, symlinks or junctions; linked paths
are not supported. Backslashes are normalized and Windows case aliases are treated as the same path.
Existing completed Steps remain readable without this field. Every pending Step must have a valid
list before execution starts; do not infer it from Markdown or automatically migrate historical phases.

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 and immutable `attempt_history` records preserving reported outcomes,
process exits, classifications and diagnostics across retries/recovery. It checks changed paths after
each attempt and before staging, then checks the actual staged paths before committing. The trusted
`owned_paths` snapshot covers tracked/untracked, staged/unstaged changes and both rename endpoints.
Implementation paths and phase metadata are committed separately; raw `stepN-output.json` stays ignored.
An ownership violation stops retry/commit/advancement, records the offending paths, and preserves user
files without reverting or expanding the allowlist. Avoid concurrent edits: these checks are not a
filesystem sandbox or an atomic guarantee against concurrent writers. Commit groups are not one
transaction; a failure after the implementation commit can leave that commit with an error Step.
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. Stop may skip build/test only for a valid same-session/turn record containing solely
repository-local `.md` edits. Missing/corrupt records or non-document edits take the normal validation path;
shell writes and read-only requests without edit records are not guaranteed to skip. A skipped check is not
build/test evidence. Do not manipulate hook state to obtain a skip.

## 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 records the retry decision and preserved failure evidence in `coordination.md`, then
explicitly assigns the Planning Agent a recovery edit of the phase index. With the Executor stopped, that
agent changes only the current failed/blocked Step's status to `pending`; it does not alter other Steps,
top-level phase state, timestamps, or the feature workflow. Coordinator does not edit phase files itself.
The Executor clears stale summary/failure/block fields and timestamps on restart, retaining
`attempt_history`. For a legacy Step missing `owned_paths`, Planning needs a separate explicit assignment
to supply the approved list before execution; the status-only recovery edit does not grant that change.
This is an assigned
file edit, not an automatic recovery command or an additional correction allowance.

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.