docs: design Harness phase step execution roles
This commit is contained in:
KOKO\Mimi
@@ -0,0 +1,129 @@
|
|||||||
|
# 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.
|
||||||
Reference in New Issue
Block a user