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의 목적과 개발 판단 기준, 문서 탐색 순서, 최소 검증 진입점

• Step 1: 프로젝트 목적과 문서 역할을 선명하게 한다

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

• Step 2: 개발 시 훼손하면 안 되는 핵심 원칙을 추가한다

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

• Step 3: 기능 확장 판단 기준을 추가한다

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

• Step 4: 최소 검증 진입점의 부정확한 예제를 정리한다

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

• 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 흐름과 신규 기능의 완료 정의

• Step 1: 제품 흐름을 입력→해석→HDF5→검증으로 명확히 한다

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

• Step 2: 현재 구현과 장기 방향을 구분한다

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

• 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

• Step 1: directory/target 설명에서 구현과 계획을 구분한다

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

• Step 2: 소유권과 8단계 실행 흐름을 표로 추가한다

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

• Step 3: CMake dependency와 Windows runtime staging을 설명한다

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

• 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

• Step 1: 외부 의존성 정규화와 runtime closure ADR을 추가한다

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

• Step 2: 결정론성과 failure atomicity ADR을 추가한다

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

• Step 3: 구속 제거와 full residual ADR을 추가한다

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

• 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

• Step 1: 변경 범위를 확인한다

Run: git status --short

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

• Step 2: whitespace 오류를 확인한다

Run: git diff --check

Expected: exit 0.

• 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은 거부 또는 비범위 문맥에서만 나타난다.

• 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 명칭이 일치한다.