FESADev/docs2/HARNESS_WORKFLOW.md

# Harness Execution Workflow

## 1. 목적

Harness는 승인된 구조 FEM feature contract를 작은 test-first Step으로 실행하고, 독립 Codex
session, hook validation, 상태와 local Git commit을 deterministic하게 연결한다. 제품 workflow
상태는 Coordinator가 소유하고, Executor는 선택된 implementation phase의 기계적 실행만
소유한다.

## 2. 전체 흐름

```text
approved feature bundle
  -> Coordinator dispatches Implementation Planning
  -> Planning Agent materializes phase/index/step files
  -> Coordinator checks plan evidence and dispatches local execution
  -> Executor preflight and feature branch
  -> current Step in an independent Codex session
       -> PreToolUse guard before commands/edits
       -> RED -> minimal GREEN -> focused/full VERIFY
       -> Stop hook configured build/test before response completion
  -> Executor validates exit + Step payload
       -> completed: path-scoped commits, next Step
       -> error: stop and return evidence to Coordinator
       -> blocked: stop until environment/user authority changes
  -> all completed: phase closure
  -> Coordinator dispatches physics evaluation
```

승인된 scope 안의 planning materialization과 기본 local execution에는 stage마다 사용자 확인을
반복하지 않는다. Physics/scope/public compatibility/product acceptance, authoritative artifact,
external authority 또는 destructive/remote action만 별도 사용자 결정이다.

## 3. 책임 경계

| Component | Owns | Does not own |
| --- | --- | --- |
| Coordinator | workflow transition, contract revision, `retry_key`, correction budget | Step execution과 Git mechanics |
| Planning Agent | implementation plan과 assigned phase files | source 구현과 Step 선택 |
| Executor | preflight, branch, first pending Step, transport attempts, timestamps, local commits | physics/contract 판단과 correction 분류 |
| Implementation Agent | current Step의 code/test/report와 result payload | 다른 Step, upstream contract와 workflow transition |
| PreToolUse | dangerous-pattern 및 C++ test-path guard | 실제 RED와 correctness 증명 |
| Stop | configured project의 build/test gate | numerical/physics/release 판정 |

## 4. Phase 계약

Top-level `phases/index.json`은 phase를 정확히 한 번 식별한다.

```json
{
  "phases": [
    {"dir": "linear-solid", "status": "pending"}
  ]
}
```

`phases/linear-solid/index.json`은 directory와 같은 `phase`, non-empty project와 0부터 연속인
Step을 가진다.

```json
{
  "project": "Structural FEM Solver",
  "phase": "linear-solid",
  "steps": [
    {"step": 0, "name": "element-kernel", "status": "pending"},
    {"step": 1, "name": "global-assembly", "status": "pending"}
  ]
}
```

허용 status는 `pending`, `completed`, `error`, `blocked`다. Completed Step은 앞쪽의 연속된
prefix여야 하며 `summary`가 필요하다. Error/blocked는 첫 미완료 Step 하나에만 올 수 있고
각각 `error_message`/`blocked_reason`이 필요하다. 뒤 Step은 pending이다.

Phase/Step 이름은 safe slug여야 하며 directory escape, absolute path, noncontiguous number,
unknown status, missing Step file과 duplicate top-level phase는 실행 전에 거부된다.
Phase 안의 허용 파일은 index, 선언된 `stepN.md`와 해당 ignored raw output뿐이며 임의 note나
미선언 Step file은 metadata ownership을 얻지 않는다.

## 5. Step 설계

각 `stepN.md`는 이전 대화 없이 실행 가능한 작업 지시서다.

```markdown
# Step N: <name>

## Required inputs
- architecture와 직접 upstream contract
- 이전 Step에서 소비할 exact artifact

## Owned changes
- exact path, type/function과 observable behavior

## Test-first sequence
- 먼저 만들 test와 예상 RED 원인
- 최소 GREEN 범위

## Acceptance commands
- focused test
- configured build/full test
- required comparison

## Invariants and stop conditions
- units, signs, ordering, state, schema, tolerance와 forbidden scope
```

한 Step 안에서 RED를 실제 관찰하고 GREEN/full validation까지 완료한다. “test만 추가” Step과
“다음 Step에서 구현”을 분리하면 Stop hook과 phase invariants에 맞지 않는다.

Planning Agent는 repository configuration과 실제 target을 조사해 command를 적는다. 존재하지
않는 target을 예시 command로 대신하지 않는다. Upstream physics/schema/tolerance가 불완전하면
Step에 추정값을 넣지 않고 `return-upstream`한다.

## 6. Executor preflight

`python scripts/execute.py <phase>`는 Codex 실행 전에 다음을 검증한다.

1. Harness root와 phase name/path containment 및 exact Git top-level
2. Top-level과 phase JSON schema 및 status order
3. Implementation Agent profile의 model, reasoning effort와 role instructions
4. Sandbox mode와 elevated-run 조건
5. Git repository 및 selected phase 밖의 clean worktree

Pre-existing unrelated tracked, staged 또는 untracked path가 있으면 branch 변경 전에 중단한다.
Selected phase의 선언된 plan 파일은 materialization 직후라 아직 dirty일 수 있으며 metadata commit
owner는 Executor다. 다른 Git repository 안에 중첩된 framework, 외부로 연결된 phase path와 phase
안의 미선언 파일은 거부한다.

## 7. Branch와 prompt

Executor는 `feat-<phase>`를 checkout하거나 생성한다. Prompt는 다음을 조합한다.

```text
Implementation Agent developer instructions
+ AGENTS.md와 repository guardrail docs
+ completed Step summaries
+ prior transport failure diagnostic, if any
+ current stepN.md
```

Role instructions가 단지 model 선택에만 사용되어서는 안 된다. Source/test write boundary,
upstream immutability, skill과 evidence contract가 prompt에 포함된다.

각 Step은 새 `codex exec` process다. 이전 conversation 전체를 전달하지 않고 approved files와
compact summary를 authoritative context로 사용한다.

## 8. PreToolUse

PreToolUse input은 current Codex hook contract의 `tool_name`, `tool_input`, `cwd`를 사용한다.

- Shell 계열은 dangerous command pattern을 검사한다.
- Commit, push, checkout/switch, branch, tag와 history-changing Git command는 Executor ownership
  위반으로 차단한다.
- `apply_patch`는 `tool_input.command`의 `*** Add/Update/Delete File`과 `Move to` path를 읽는다.
- Edit/Write 계열은 direct path/edits를 읽는다.
- Malformed JSON, missing tool/path와 invalid input type은 exit code 2로 fail closed한다.
- Production C/C++ path는 config의 roots/patterns로 mapping되는 test가 있어야 한다.

Hook은 shell redirection 등 모든 write mechanism을 완전하게 인식하지 않는다. Implementation
Agent와 code review가 actual RED/GREEN evidence를 계속 책임진다.

## 9. Stop validation

Stop hook은 response 직전에 실행된다.

```text
payload/root validation
  -> project/config discovery
  -> MSVC toolchain discovery
  -> adapter validation plan
  -> configure/build
  -> test discovery
  -> full tests
```

모든 subprocess는 `shell=False`, repository-contained working directory와 전체 1,800초 deadline을
사용한다. Child process에는 reentry flag를 전달한다.
Config의 command/path 문자열에는 control character를 허용하지 않으며 hook 경계의 예상하지 못한
일반 예외도 traceback 종료 대신 block response로 변환한다.

실패 시 stdout에 다음 protocol을 반환한다.

```json
{"decision": "block", "reason": "<actionable validation failure>"}
```

Codex는 같은 session에서 수정할 수 있다. Hook 자체의 malformed payload도 block response이며,
`stop_hook_active: true` 또는 child reentry는 재귀를 피하기 위해 바로 허용된다.

### Project discovery

1. Explicit `projectType`
2. Configured CMake source directory의 preset/CMakeLists
3. Root의 한 개 solution 또는 project
4. C/C++와 metadata가 모두 없으면 no-target success
5. C/C++만 있으면 orphan-project failure

CMake plan은 MSVC compiler identity와 nonzero CTest inventory를 추가 검사한다. MSBuild plan은
repository-relative test executable을 반드시 요구한다.

## 10. Step result와 transport attempt

Codex process exit가 0인 경우에만 Step payload를 평가한다.

- `completed + summary`: stale error/block field를 제거하고 `completed_at` 기록
- `error + error_message`: `failed_at` 기록 후 phase error
- `blocked + blocked_reason`: `blocked_at` 기록 후 phase blocked
- status 미갱신 또는 invalid payload: error

Nonzero exit가 `completed` payload와 함께 와도 completion을 폐기한다. Authentication/CLI/sandbox
helper처럼 분류 가능한 environment failure는 즉시 중단한다. 그 밖의 process/session failure만
최대 두 번 transport attempt한다.

각 attempt 전의 top-level index와 `stepN.md` byte, phase index metadata와 모든 non-current Step을
snapshot한다. Session은 current Step의 `status`, `summary`, `error_message`, `blocked_reason`만
바꿀 수 있다. 위반 또는 malformed exit payload가 있으면 snapshot을 복원하고 current Step을
trusted error로 기록해 재실행 우회를 차단한다.
Symbolic branch와 HEAD도 같은 방식으로 비교하며 agent-side commit/checkout은 실패다. Control
file read는 link 및 scope escape를 거부하고, 복구와 raw-output write는 atomic replacement로
link target overwrite를 방지한다.

Transport attempt는 implementation correction이 아니다. Implementation/test/reference failure는
새 session에서 세 번 자동 수정하지 않고 Coordinator로 반환한다. Coordinator가 동일
`feature|gate|classification|contract-revision` key의 Correction Agent를 한 번만 사용할 수 있다.

## 11. Git ownership

Step success 시 Executor는 preflight 후 생긴 현재 changes를 다시 분류한다.

1. Selected phase 밖 implementation paths를 feature commit에 stage
2. Selected phase index/Step/timestamps와 top-level index를 metadata commit에 stage
3. `stepN-output.json`은 항상 제외

모든 Git command failure는 fatal이다. Commit 직전에는 working tree를 보존하는 mixed index
reset 후 `git add -A`를 pathspec과 `--` 뒤에서만 사용한다. 따라서 pre-staged 파일이 다른 commit에
섞이지 않는다. Unicode와 space를 포함한 porcelain path 및 rename의 양쪽 identity는 NUL format으로
읽어 ownership을 검증한다.

Raw output은 local diagnostic이며 `.gitignore` 대상이다. Step 종료 후 implementation path가
uncommitted 상태로 남으면 phase finalization을 거부한다.

모든 Step이 completed이면 phase/top-level `completed_at`을 기록하고 final metadata commit을
만든다. `--push`는 사용자가 remote action을 별도로 승인한 경우만 실행한다.

## 12. Elevated sandbox

Default는 `workspace-write`다. `danger-full-access`는 다음 조건을 모두 만족해야 한다.

- 사용자가 exact elevated run을 명시적으로 승인
- `FEM_HARNESS_CODEX_SANDBOX=danger-full-access`
- `--approve-danger-full-access` flag
- primary가 아닌 linked Git worktree
- 완전히 clean worktree

조건 하나라도 없으면 Codex를 실행하지 않는다. Hook trust bypass flag는 등록된 reviewed hook을
automation에서 실행하기 위한 것이며 sandbox bypass 권한이 아니다.

## 13. Recovery

Error/blocked Step을 임의로 pending으로 돌리기 전에 Coordinator가 evidence를 분류한다.

| Classification | Route |
| --- | --- |
| clear implementation defect | bounded implementation fix |
| repeated/unclear implementation defect | one Correction allowance, then rerun |
| formulation/requirement/reference/I/O defect | owning upstream agent |
| toolchain/license/credential | `blocked-environment` or critical user action |
| same retry key after correction | no second correction; route or stop |

재개 시 current Step만 pending으로 변경한다. Executor가 stale summary, failure와 block timestamp를
정리한다. Contract revision 없는 문구 변경으로 새 retry key를 만들지 않는다.

## 14. 검증 evidence

Harness report는 다음을 기록한다.

- selected configuration, sandbox와 worktree condition
- exact command, cwd, exit code, duration과 output tail
- focused RED와 GREEN 결과
- full build/test count와 warning
- comparison identity/precheck/metric/tolerance result when applicable
- commits, ignored raw output와 unexecuted checks

Hook pass, process exit 0와 agent narrative 중 하나만으로 feature gate를 통과시키지 않는다.
Numerical/physics/release owner가 같은 artifact revision을 독립 검토한다.