# Harness Agent Step Execution Design

## Status

- date: `2026-08-12`
- status: `approved-approach-awaiting-written-spec-review`
- approved_approach: `executor-centered-single-path`
- scope: Implementation Planning Agent, Implementation Agent, Harness workflow guidance

## Purpose

FESA implementation work shall use one explicit Harness execution path. The
Implementation Planning Agent converts an approved implementation plan into
self-contained phase Steps after user approval. The Step Executor selects and runs
those Steps sequentially. The Implementation Agent executes only the current Step and
does not independently expand its scope to the remaining implementation plan.

## Required Reading

Both the Implementation Planning Agent and Implementation Agent shall read these
documents before Harness planning or execution:

- `AGENTS.md`
- `.agents/skills/harness/SKILL.md`
- `docs/HARNESS.md`
- `docs/HARNESS_WORKFLOW.md`
- `docs/SOLVER_AGENT_DESIGN.md`
- the approved feature implementation plan and applicable upstream feature contracts

The agents shall also inspect `.codex/hooks.json`, `.harness/config.json` when present,
and the relevant `phases/` indexes and Step file for execution work.

## Planning Contract

The Implementation Planning Agent shall:

1. prepare a multi-Step draft from approved upstream contracts;
2. keep one layer or module in each self-contained Step;
3. include required-reading paths, RED/GREEN/VERIFY work, exact acceptance commands,
   status rules, and concrete prohibitions;
4. obtain explicit user approval before creating or updating `phases/` planning files;
5. create only `phases/index.json`, `phases/<task>/index.json`, and approved
   `phases/<task>/stepN.md` files;
6. never run `scripts/execute.py` merely because a plan or phase draft is ready.

Harness execution requires a separate explicit user request.

## Execution Contract

After an explicit Harness execution request, `scripts/execute.py <phase>` is the
single phase runner. It owns branch selection, first-pending-Step selection, Step
session creation, retries, timestamps, commit separation, next-Step advancement, and
top-level phase completion.

The Implementation Agent shall:

1. require an approved implementation plan and materialized phase files;
2. execute only the current `stepN.md` selected and supplied by the Executor;
3. read the Step prerequisites and relevant previous-Step summaries before editing;
4. complete RED, observed expected failure, minimal GREEN, focused VERIFY, and the
   Step's full acceptance commands within the same Step;
5. avoid starting a later pending Step or performing unlisted implementation-plan
   work;
6. update only the current Step's Codex-owned status fields:
   - success: `status=completed` plus one-line `summary`;
   - after the allowed failed correction attempts: `status=error` plus
     `error_message`;
   - user intervention required: `status=blocked` plus `blocked_reason`, then stop;
7. leave `started_at`, `completed_at`, `failed_at`, `blocked_at`, task timestamps,
   next-Step selection, and top-level phase status to the Executor.

If approved phase files are absent or the supplied Step conflicts with an approved
upstream contract, the Implementation Agent shall not fall back to the broad plan. It
shall report `needs-upstream-decision` or `blocked` through the documented handoff.

## Hooks and Scripts

`.codex/hooks.json` is the authoritative hook registration used during Harness Step
sessions:

- PreToolUse calls `scripts/hooks/pre_tool_use.py` to reject dangerous commands and
  enforce the related-test-file guardrail for C++ production edits.
- Stop calls `scripts/hooks/stop_validation.py` to run the discovered whole-project
  MSVC build/test validation before a Step may end.

These hooks run automatically through Codex hook registration. Agents shall inspect
the registration and comply with hook outcomes, but shall not manually invoke the
hook Python entry points as a substitute for actual tool interception or Stop.
PreToolUse is not proof that RED occurred; the Implementation Agent must execute and
record the Step's RED and GREEN commands itself.

The approved script boundary is:

- `scripts/execute.py`: phase runner; run only after a separate explicit user request;
- Step acceptance commands: run by the Implementation Agent as written, resolving
  `.harness/config.json` first and otherwise using documented Harness defaults;
- `uv run --with pytest python -m pytest -v -rs`: additionally required only when
  Harness Python, hook, runner, or Agent/Skill configuration behavior is changed.

## Files to Align

The implementation will make surgical changes to:

- `.codex/agents/implementation-planning-agent.toml`
- `.codex/agents/implementation-agent.toml`
- `.agents/skills/harness/SKILL.md`
- `.codex/skills/fesa-cpp-msvc-tdd/SKILL.md`
- `docs/SOLVER_AGENT_DESIGN.md`
- `docs/implementation-plans/README.md`

`docs/HARNESS.md` and `docs/HARNESS_WORKFLOW.md` already document the runner, hooks,
validation, retry, and state lifecycle. They become mandatory references rather than
being duplicated in full in every Agent or Skill instruction.

## Validation

The change is complete when:

- both Agent TOML files parse;
- the changed skills pass `quick_validate.py`;
- both agents explicitly require `docs/HARNESS.md` and
  `docs/HARNESS_WORKFLOW.md`;
- the Implementation Agent explicitly follows only the Executor-selected current
  Step and respects Executor-owned fields;
- hook behavior and `scripts/execute.py` authorization are consistent across the
  Agent, Skill, and guide documents;
- Harness Python tests pass because hook/Agent/Skill behavior is in scope;
- no phase execution, C++ implementation, reference mutation, or Abaqus execution
  occurs as part of this policy edit.