docs: design Harness phase step execution roles

2026-08-12 11:19:27 +09:00
parent 60b42f4aec
commit 85cd17da57
1 changed files with 129 additions and 0 deletions
@@ -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.