modify documents
This commit is contained in:
KOKO\Mimi
@@ -0,0 +1,285 @@
|
||||
# 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을 독립 검토한다.
|
||||
Reference in New Issue
Block a user