FESADev/docs/superpowers/plans/2026-08-10-core-documentation-extension-playbook.md

# FESA Core Documentation Extension Playbook Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 미래 AI Agent가 FESA에 기능을 추가할 때 실제 해석 흐름, 소유권, CMake 설정, 수치 불변식과 검증 경계를 바로 찾을 수 있도록 핵심 문서를 보강한다.

**Architecture:** 같은 사실을 네 문서에 반복하지 않고 문서별 책임을 분리한다. AGENTS는 프로젝트 배경·목적·핵심 개발 원칙, PRD는 사용자 관점의 제품 계약, ARCHITECTURE는 구현 구조·빌드 흐름·확장 지점, ADR은 장기 의사결정을 담당한다.

**Tech Stack:** Markdown, C++17/MSVC, CMake/CTest, Intel oneAPI MKL/TBB, HDF5, Abaqus `.inp` subset

## Global Constraints

- 수정 범위는 `AGENTS.md`, `docs/PRD.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`와 이 작업의 spec/plan 문서뿐이다.
- phase 완료 이력, commit hash, 현재 테스트 총개수는 핵심 문서에 기록하지 않는다.
- 승인되지 않은 Abaqus keyword와 해석 기능을 지원하는 것처럼 서술하지 않는다.
- project hook과 Harness는 실행하지 않는다.
- production, test, CMake, reference artifact는 수정하지 않는다.
- direct 검증은 `git diff --check`와 문서·코드·CMake 사이의 정적 대조만 사용한다.

---

### Task 1: 프로젝트 배경과 핵심 개발 지침 보강

**Files:**
- Modify: `AGENTS.md`

**Interfaces:**
- Consumes: root CMake options, normalized dependency targets, `Analysis::run()` lifecycle, public dependency boundaries
- Produces: FESA의 목적과 개발 판단 기준, 문서 탐색 순서, 최소 검증 진입점

- [x] **Step 1: 프로젝트 목적과 문서 역할을 선명하게 한다**

FESA가 검증 가능한 구조해석 솔버라는 점, full Abaqus clone이 아니라 승인된 feature contract를 누적하는 프로젝트라는 점, PRD/ARCHITECTURE/ADR와 기능별 계약의 역할을 기록한다.

- [x] **Step 2: 개발 시 훼손하면 안 되는 핵심 원칙을 추가한다**

물리·수치 계약 우선, stable identity, 명시적 소유권, 결정론성, backend isolation, failure atomicity, 공식 HDF5와 read-only reference 원칙을 상위 수준 지침으로 추가한다. 상세 lifecycle은 ARCHITECTURE로 연결한다.

- [x] **Step 3: 기능 확장 판단 기준을 추가한다**

입력 계약, semantic model, kernel/assembly, solve/recovery, HDF5/reference/physics evidence가 함께 변경되어야 함을 명시한다.

- [x] **Step 4: 최소 검증 진입점의 부정확한 예제를 정리한다**

`FESA_GTEST_SOURCE_DIR`가 빠진 configure와 실제 target이 아닌 `MyProject.sln` 예제를 제거한다. 상세 package/runtime 설명은 ARCHITECTURE로 연결한다.

- [x] **Step 5: 최소 build 명칭을 실제 CMake 옵션과 대조한다**

Run: `rg -n "FESA_GTEST_SOURCE_DIR|MKL_DIR|TBB_DIR|HDF5_DIR|Fesa::MKL|Fesa::TBB|Fesa::HDF5" CMakeLists.txt cmake/FesaDependencies.cmake src/fesa/CMakeLists.txt tests/CMakeLists.txt AGENTS.md`

Expected: AGENTS의 변수와 target 이름이 실제 CMake 정의와 일치한다.

### Task 2: 제품 계약과 기능 정의 보강

**Files:**
- Modify: `docs/PRD.md`

**Interfaces:**
- Consumes: 승인된 V0 input/output/diagnostic 범위
- Produces: 사용자 관점 end-to-end 흐름과 신규 기능의 완료 정의

- [x] **Step 1: 제품 흐름을 입력→해석→HDF5→검증으로 명확히 한다**

Syntax parse, semantic validation, linear solve, recovery, mandatory HDF5, optional reference comparison의 사용자 관찰 가능 결과를 기록한다.

- [x] **Step 2: 현재 구현과 장기 방향을 구분한다**

현재 concrete V0 model과 backend polymorphism을 정확히 기술하고, runtime-polymorphic element/material 확장은 미래 방향으로 표시한다.

- [x] **Step 3: 신규 제품 기능의 Definition of Done을 추가한다**

입력 노출, semantic mapping, solver lifecycle, result schema, diagnostics, unit/integration/reference/physics evidence가 모두 있어야 제품 기능으로 간주한다고 명시한다.

### Task 3: 실제 아키텍처와 확장 지점 보강

**Files:**
- Modify: `docs/ARCHITECTURE.md`

**Interfaces:**
- Consumes: `src/fesa`와 `tests`의 실제 target/module graph
- Produces: ownership/lifetime, 8-stage lifecycle, CMake/runtime graph, extension playbook

- [x] **Step 1: directory/target 설명에서 구현과 계획을 구분한다**

현재 존재하는 static solver library, CLI, unit/integration/reference test target을 명시하고 계획된 디렉터리는 계획이라고 표시한다.

- [x] **Step 2: 소유권과 8단계 실행 흐름을 표로 추가한다**

각 단계의 입력, 출력, 소유 객체, 실패 범주와 순서 불변식을 기록한다.

- [x] **Step 3: CMake dependency와 Windows runtime staging을 설명한다**

normalized `Fesa::*` targets, shared HDF5 preference, private product linkage, CLI/test executable 옆 runtime DLL staging을 기록한다.

- [x] **Step 4: 기능 유형별 확장 플레이북을 추가한다**

element, load/constraint, analysis procedure, backend, output/reference quantity별 변경 지점과 금지되는 shortcut을 기록한다.

### Task 4: 장기 아키텍처 결정을 추가한다

**Files:**
- Modify: `docs/ADR.md`

**Interfaces:**
- Consumes: 실제 CMake/runtime, deterministic assembly, essential constraints, layered verification behavior
- Produces: 향후 구현이 지켜야 할 결정과 trade-off

- [x] **Step 1: 외부 의존성 정규화와 runtime closure ADR을 추가한다**

Vendor target 이름을 `Fesa::*`로 정규화하고 public header에는 노출하지 않으며 Windows executable runtime closure를 staging하는 결정을 기록한다.

- [x] **Step 2: 결정론성과 failure atomicity ADR을 추가한다**

Stable COO/reduction, state/output candidate-commit, atomic HDF5 finalization이 성능 옵션이 아니라 correctness contract임을 기록한다.

- [x] **Step 3: 구속 제거와 full residual ADR을 추가한다**

`Kff`, `Ff-Kfc*dc`, valid 0x0 system, reaction=`Kd-F`의 결정과 penalty/MPC 비범위를 기록한다.

- [x] **Step 4: 계층형 검증 ADR을 추가한다**

Kernel 존재와 parser/CLI 노출을 구분하고 unit→integration→reference→physics gate가 각기 다른 오류를 검출한다는 결정을 기록한다.

### Task 5: 문서 전용 정적 검증

**Files:**
- Verify: `AGENTS.md`
- Verify: `docs/PRD.md`
- Verify: `docs/ARCHITECTURE.md`
- Verify: `docs/ADR.md`

**Interfaces:**
- Consumes: Tasks 1–4의 문서 변경
- Produces: 문서 범위·형식·사실 일치 evidence

- [x] **Step 1: 변경 범위를 확인한다**

Run: `git status --short`

Expected: production, test, CMake, reference 경로 변경이 없다.

- [x] **Step 2: whitespace 오류를 확인한다**

Run: `git diff --check`

Expected: exit 0.

- [x] **Step 3: stale 예제와 승인되지 않은 범위 암시를 검사한다**

Run: `rg -n "MyProject|full Abaqus compatibility|B31.*지원|현재 테스트.*[0-9]+" AGENTS.md docs/PRD.md docs/ARCHITECTURE.md docs/ADR.md`

Expected: stale solution 예제와 지원 범위 확대 문구가 없다. Full compatibility/B31은 거부 또는 비범위 문맥에서만 나타난다.

- [x] **Step 4: 명령·target·lifecycle 이름을 원본과 대조한다**

Run: `rg -n "FESA_GTEST_SOURCE_DIR|Fesa::MKL|Fesa::TBB|Fesa::HDF5|assembleAndPartitionStiffness|assembleLoadsAndEffectiveRhs|recoverAndWriteResults" AGENTS.md docs/ARCHITECTURE.md cmake/FesaDependencies.cmake src/fesa/analysis/linear_static_analysis.cpp`

Expected: 문서의 명칭과 구현/CMake 명칭이 일치한다.