KOKO\Mimi
12 KiB
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. 전체 흐름
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를 정확히 한 번 식별한다.
{
"phases": [
{"dir": "linear-solid", "status": "pending"}
]
}
phases/linear-solid/index.json은 directory와 같은 phase, non-empty project와 0부터 연속인
Step을 가진다.
{
"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는 이전 대화 없이 실행 가능한 작업 지시서다.
# 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 실행 전에 다음을 검증한다.
- Harness root와 phase name/path containment 및 exact Git top-level
- Top-level과 phase JSON schema 및 status order
- Implementation Agent profile의 model, reasoning effort와 role instructions
- Sandbox mode와 elevated-run 조건
- 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는 다음을 조합한다.
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 topath를 읽는다.- 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 직전에 실행된다.
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을 반환한다.
{"decision": "block", "reason": "<actionable validation failure>"}
Codex는 같은 session에서 수정할 수 있다. Hook 자체의 malformed payload도 block response이며,
stop_hook_active: true 또는 child reentry는 재귀를 피하기 위해 바로 허용된다.
Project discovery
- Explicit
projectType - Configured CMake source directory의 preset/CMakeLists
- Root의 한 개 solution 또는 project
- C/C++와 metadata가 모두 없으면 no-target success
- 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 errorblocked + 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를 다시 분류한다.
- Selected phase 밖 implementation paths를 feature commit에 stage
- Selected phase index/Step/timestamps와 top-level index를 metadata commit에 stage
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-accessflag- 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을 독립 검토한다.