# Implementation Plan 문서 작성 가이드

이 디렉터리는 Implementation Planning Agent가 작성하거나 제안한 기능별 구현계획 문서를 보관하는 위치다.

Implementation Planning Agent는 승인된 요구조건, 연구 브리프, 정식화, 수치 리뷰, I/O
정의와 lightweight reference-case inventory를 C++/MSVC 구현 전 TDD 작업계획으로
변환한다. Project-local `$harness`를 사용해 multi-Step 초안을 먼저 제시하고 사용자가
승인한 뒤에만 `phases/` planning files를 생성한다. 계획과 구현 전에
`docs/HARNESS.md`와 `docs/HARNESS_WORKFLOW.md`를 읽는다.

## Harness 실행 handoff

Planning Agent는 draft -> explicit user approval -> planning files만 수행하며 Step을
선택하거나 실행하지 않는다. 별도의 명시적 사용자 요청이 있어야 Executor
(`scripts/execute.py`)가 branch, pending Step, retry, timestamps, commits, advancement와 phase
status를 소유한다.

Implementation Agent는 approved plan, materialized phase indexes, Executor-selected current
`stepN.md` 하나만 사용한다. current Step에서 `RED -> observed failure -> minimal GREEN ->
focused/full VERIFY`를 완료하고 다음 Step을 시작하지 않는다. Agent는 current Step의 `status`
및 `summary`, `error_message`, `blocked_reason` payload만 쓴다. `.codex/hooks.json`의
PreToolUse와 Stop은 자동으로 실행되며 hook entry point를 수동 실행해 대체하지 않는다.

기본 파일명은 `docs/implementation-plans/<feature-id>-implementation-plan.md` 형식을 사용한다. 각 문서는 Implementation Agent가 먼저 작성해야 할 실패 테스트, 최소 구현 순서, CMake/CTest 등록 계획, acceptance traceability를 제공해야 한다.

## Implementation Planning Agent 역할

수행한다:
- upstream 문서가 구현 계획에 충분한지 Readiness Check를 수행한다.
- 요구조건과 정식화를 작은 Work Breakdown task로 나눈다.
- unit, integration, parser/I/O, reference-comparison 테스트를 TDD 순서로 정렬한다.
- CMake/CTest target, `add_test`, label, `ctest -C Debug` 검증 계획을 정의한다.
- candidate source/header/test/CMake 파일과 ownership boundary를 제안한다.
- requirement, task, test, reference model, acceptance criterion을 Acceptance Traceability Matrix로 연결한다.
- `.harness/config.json` 또는 자동 감지 기본값에서 해석되는 MSVC build/test 명령과 feature-specific command를 명시한다.
- 한 Step을 하나의 layer/module로 제한하고 prerequisite files, RED/GREEN/VERIFY, exact
  acceptance commands와 구체적 금지사항을 포함한다.
- 사용자 승인 전에는 `phases/` 파일을 만들지 않고, 승인 뒤에도 planning files만
  materialize한다. 별도 요청 없이는 `scripts/execute.py`를 실행하지 않으며 Step을
  선택하거나 실행하지 않는다.

수행하지 않는다:
- C++ 코드를 구현하지 않는다.
- 테스트 파일을 작성하지 않는다.
- CMake 파일을 수정하지 않는다.
- CMake/CTest를 실행하지 않는다.
- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
- Abaqus reference CSV 파일을 생성하거나 수정하지 않는다.
- solver 결과를 비교하지 않는다.
- release readiness를 승인하지 않는다.
- C++ API, class name, storage layout, file ownership을 확정하지 않는다.

## 문서 템플릿

```markdown
# <feature title> Implementation Plan

## Metadata
- feature_id: <feature-id>
- source_requirement: docs/requirements/<feature-id>.md
- source_research: docs/research/<feature-id>-research.md
- source_formulation: docs/formulations/<feature-id>-formulation.md
- source_numerical_review: docs/numerical-reviews/<feature-id>-review.md
- source_io_definition: docs/io-definitions/<feature-id>-io.md
- source_reference_models: docs/reference-models/<feature-id>-reference-models.md
- status: draft | needs-upstream-decision | ready-for-implementation | blocked
- owner_agent: implementation-planning-agent
- date: <YYYY-MM-DD>

## Readiness Check

| input | required_status | observed_status | decision |
| --- | --- | --- | --- |
| requirement | approved or sufficient draft | <status> | proceed | needs-upstream-decision | blocked |
| formulation | pass-for-implementation-planning or sufficient draft | <status> | proceed | needs-upstream-decision | blocked |
| numerical_review | pass-for-implementation-planning | <status> | proceed | needs-upstream-decision | blocked |
| io_definition | ready-for-implementation-planning or sufficient draft | <status> | proceed | needs-upstream-decision | blocked |
| reference_models | ready-for-implementation-planning or planned artifacts | <status> | proceed | needs-upstream-decision | blocked |

## Implementation Scope
- included_behavior: <behavior to implement>
- excluded_behavior: <behavior explicitly out of scope>
- non_goals: <items not to design or implement in this phase>

## Work Breakdown

| task_id | order | purpose | upstream_trace | depends_on | expected_test_first |
| --- | --- | --- | --- | --- | --- |
| TASK-001 | 1 | <small implementation task> | <requirement/formulation/io/reference id> | none | TEST-001 |

## TDD Test Plan

| test_id | order | test_type | red_condition | green_condition | linked_task | command |
| --- | --- | --- | --- | --- | --- | --- |
| TEST-001 | 1 | unit | test fails because behavior is missing | test passes after minimal implementation | TASK-001 | ctest -C Debug -R <test-name> |
| TEST-002 | 2 | integration | integrated path fails before implementation | integrated path passes | TASK-002 | ctest -C Debug -R <test-name> |
| TEST-003 | 3 | parser/I/O | Abaqus .inp case is not accepted or mapped | input maps to expected semantic model | TASK-003 | ctest -C Debug -R <test-name> |
| TEST-004 | 4 | reference-comparison | solver HDF5/CSV view comparison fails before implementation | comparison is within planned tolerance | TASK-004 | ctest -C Debug -R <test-name> |

## CMake/CTest Plan
- target_candidates: <library/test executable targets>
- add_test_needs: <CTest registration needs>
- labels: unit | integration | reference | parser | io
- msvc_config: Debug
- expected_feature_command: ctest --test-dir .harness/build -C Debug -R <feature-or-label> --output-on-failure
- full_validation_source: .harness/config.json | Harness auto detection

## Candidate Files and Ownership

| file_candidate | purpose | owner_boundary | notes |
| --- | --- | --- | --- |
| include/fesa/<module>/<candidate>.hpp | <candidate public header role> | candidate only, not final API | <notes> |
| src/<module>/<candidate>.cpp | <candidate implementation role> | candidate only, not final API | <notes> |
| tests/<module>/<candidate>_test.cpp | <test role> | required before production change | <notes> |
| CMakeLists.txt | <target/test registration role> | candidate only | <notes> |

## Data Flow Contract
1. Abaqus `.inp` input follows docs/io-definitions/<feature-id>-io.md.
2. Parser/I/O path maps model data and history data into the internal semantic model.
3. Solver path produces authoritative `results.h5` with displacement, reaction, internal force, stress, or feature-specific result datasets.
4. Reference inputs and required CSV files use exact existing paths declared by the feature.
5. Reference comparison tests compare only blocking/warning quantities by source ID/component.

## Acceptance Traceability Matrix

| requirement_id | task_id | test_id | reference_model_id | acceptance_criterion | status |
| --- | --- | --- | --- | --- | --- |
| <req-id> | TASK-001 | TEST-001 | <model-id or N/A> | <criterion> | draft |

## Validation Commands
```powershell
cmake -S . -B .harness/build -A x64
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug -R <feature-or-label> --output-on-failure
ctest --test-dir .harness/build -C Debug --output-on-failure
```

Preset 또는 직접 MSBuild 프로젝트는 `.harness/config.json`에 해석 가능한 명령을 적는다.
Harness Python, Hook, agent config 변경이 계획 범위에 포함되면
`uv run --with pytest python -m pytest -v -rs`도 추가한다. Stop 검증은 Step 종료 전 전체
MSVC build/test를 다시 확인하며, 구현 보고서의 RED 실패 증거를 대체하지 않는다.

## Risks and Downstream Handoff

### Implementation Agent
- <task order, tests to write first, candidate files, acceptance criteria>

### Build/Test Executor Agent
- <validation commands, expected CTest labels, feature-specific commands>

### Correction Agent
- <likely failure classifications and upstream rollback guidance>

### Reference Verification Agent
- <planned HDF5/CSV comparison tests, exact case paths, tolerance mapping, source-ID/component matching>

## Harness Step Draft

| step | name | owned layer/module | prerequisite files | RED/GREEN/VERIFY | acceptance commands | stop condition |
| ---: | --- | --- | --- | --- | --- | --- |
| 0 | <kebab-case> | <one scope> | <exact paths> | <test-first sequence> | <exact commands> | <condition> |

User approval is required before materializing this draft under `phases/`.

## Executor Handoff

- Executor authorization: separate explicit user request for `scripts/execute.py`.
- implementation input: approved plan, materialized phase indexes, and Executor-selected current
  `stepN.md`.
- implementation recipe: `RED -> observed failure -> minimal GREEN -> focused/full VERIFY`.
- metadata ownership: Implementation Agent records only the current Step `status` plus `summary`,
  `error_message`, or `blocked_reason`; Executor records branch, pending-Step selection, retry,
  timestamps, commits, advancement, and phase status.
- hooks: `.codex/hooks.json` automatically invokes PreToolUse and Stop; never manually run hook
  entry points as substitutes.

## Open Issues
- <requirement, formulation, I/O, required comparison file/mapping, tolerance, or architecture issue>
```

## 품질 기준

- 모든 `must` requirement는 최소 하나의 task와 test에 연결되어야 한다.
- C++ production 변경마다 선행 테스트 파일 또는 테스트 추가 계획이 있어야 한다.
- reference comparison이 필요한 기능은 exact existing input/required CSV path와 FESA
  HDF5-to-reference-CSV source-ID/component mapping test 계획을 가져야 한다.
- Implementation Planning Agent는 Harness Step 초안을 사용자에게 승인받은 뒤에만 phase
  index와 step files를 생성하며 executor는 자동 실행하지 않는다.
- CMake/CTest 계획은 MSVC x64 Debug 검증 경로와 호환되어야 한다.
- 구현 계획은 테스트 작성, 실패 확인, 최소 구현, validation 순서를 명시해야 한다.
- upstream 문서가 불완전하면 값을 임의로 채우지 않고 `needs-upstream-decision` 또는 `blocked`로 표시한다.
- release 완료나 reference tolerance 통과 판정은 하지 않는다.