# Implementation Plan 문서 작성 가이드

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

Implementation Planning Agent는 승인된 요구조건, 연구 브리프, 정식화, 수치 리뷰, I/O 정의, reference model 계약을 C++/MSVC 구현 전 TDD 작업계획으로 변환한다. Agent는 코드, 테스트, CMake 파일을 작성하지 않고, Abaqus/Nastran을 실행하지 않으며, reference HDF5/CSV view 생성이나 solver 결과 비교, release readiness 승인도 하지 않는다.

기본 파일명은 `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로 연결한다.
- `python scripts/validate_workspace.py`를 포함한 validation command를 명시한다.

수행하지 않는다:
- C++ 코드를 구현하지 않는다.
- 테스트 파일을 작성하지 않는다.
- CMake 파일을 수정하지 않는다.
- CMake/CTest를 실행하지 않는다.
- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
- reference HDF5 파일이나 deterministic CSV view를 생성하지 않는다.
- 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 -C Debug -R <feature-or-label>
- workspace_validation: python scripts/validate_workspace.py

## 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, element force, stress, or feature-specific result datasets.
4. Deterministic CSV views are exported from HDF5 only when the I/O contract or comparison command requires them.
5. Reference comparison tests compare solver `results.h5` and CSV views against `references/<feature-id>/<model-id>/` artifacts.

## 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
python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py
ctest -C Debug -R <feature-or-label>
```

## 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 view comparison tests, reference model ids, tolerance mapping, ID matching assumptions>

## Open Issues
- <requirement, formulation, I/O, reference artifact, tolerance, or architecture issue>
```

## 품질 기준

- 모든 `must` requirement는 최소 하나의 task와 test에 연결되어야 한다.
- C++ production 변경마다 선행 테스트 파일 또는 테스트 추가 계획이 있어야 한다.
- reference artifact가 필요한 기능은 `references/<feature-id>/<model-id>/`와 HDF5/CSV view 비교 테스트 계획을 가져야 한다.
- CMake/CTest 계획은 MSVC x64 Debug 검증 경로와 호환되어야 한다.
- 구현 계획은 테스트 작성, 실패 확인, 최소 구현, validation 순서를 명시해야 한다.
- upstream 문서가 불완전하면 값을 임의로 채우지 않고 `needs-upstream-decision` 또는 `blocked`로 표시한다.
- release 완료나 reference tolerance 통과 판정은 하지 않는다.