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/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/ 파일을 만들지 않고, 별도 요청 없이는 scripts/execute.py를 실행하지 않는다.

수행하지 않는다:

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

문서 템플릿

# <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

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

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

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 통과 판정은 하지 않는다.

9.0 KiB Raw Blame History