FESADev/phases/cpp-object-oriented-modular-refactoring/step20.md

Step 20: Analysis Hierarchy

담당 역할과 필수 스킬

• 담당 역할: implementation-agent
• 필수 스킬: harness, fesa-cpp-msvc-tdd
• 이 Step만 RED -> observed failure -> minimal GREEN -> focused/full VERIFY로 수행한다.

읽어야 할 파일

• /AGENTS.md
• /docs/CODINGSTYLE.md
• /docs/ARCHITECTURE.md
• /docs/ADR.md
• /docs/linear-static-3d-euler-beam/requirements.md
• /docs/linear-static-mitc4-shell/requirements.md
• /docs/cpp-object-oriented-modular-refactoring/implementation-plan.md
• Step 15–19 generic element/load/constraint pipeline files
• /include/fesa/analysis/analysis_model.h
• /include/fesa/analysis/analysis_state.h
• /include/fesa/analysis/linear_static_analysis.h
• /src/fesa/analysis/linear_static_analysis.cpp
• /src/fesa/app/fesa_application.cpp
• /tests/integration/analysis/linear_static_analysis_test.cpp
• /tests/integration/app/fesa_application_test.cpp
• /src/fesa/CMakeLists.txt, /tests/CMakeLists.txt
• /phases/cpp-object-oriented-modular-refactoring/index.json
• /phases/cpp-object-oriented-modular-refactoring/step20.md

작업

Requirement R-ANALYSIS-001을 구현한다.

1. /tests/unit/analysis/analysis_test.cpp와 integration cases를 먼저 추가한다. C-ANALYSIS-001 invokes LinearStaticAnalysis through std::unique_ptr<Analysis> and verifies virtual destruction, Status propagation, factorize-before-load, exactly one factorization, 0x0 all-constrained solve, failure atomicity and writer-after-validation.
2. Missing minimal base or old protected-hook contract causes RED.
3. Create /include/fesa/analysis/analysis.h and move the base/request contract there. Keep /include/fesa/analysis/linear_static_analysis.h and /src/fesa/analysis/linear_static_analysis.cpp as the concrete procedure owner; register /tests/unit/analysis/analysis_test.cpp in CMake.
4. Candidate interface:

struct AnalysisRequest {
  std::filesystem::path input_path;
  std::filesystem::path output_path;
};

class Analysis {
 public:
  virtual ~Analysis() = default;
  virtual Status Run(const AnalysisRequest& request) = 0;
};

class LinearStaticAnalysis final : public Analysis {
 public:
  LinearStaticAnalysis(const ParallelFor& parallel_for,
                       LinearSolver& linear_solver,
                       ResultsWriter& results_writer);
  Status Run(const AnalysisRequest& request) override;

 private:
  Status InitializeCandidate(const AnalysisRequest& request);
  Status BuildAnalysisModel();
  Status BuildDofMapAndSparsePattern();
  Status AssembleAndPartitionStiffness();
  Status FactorizeFreeSystem();
  Status AssembleLoadsAndEffectiveRhs();
  Status SubstituteAndReconstruct();
  Status RecoverAndWrite();
};

5. The request keeps the existing input/output path contract and the concrete constructor keeps existing backend dependency injection. The base class exposes only destructor and Run(). Do not place linear-static lifecycle hooks in the base.
6. FesaApplication chooses the current linear-static concrete based on the already validated single *STATIC procedure; it does not accumulate future-procedure conditionals.
7. Remove obsolete duplicated DOF-order validation wrappers after DofManager ownership is proven.

Acceptance Criteria

cmake --build .harness/build --config Debug --target fesa_unit_tests fesa_integration_tests
ctest --test-dir .harness/build -C Debug `
  -R "Analysis$|LinearStaticCli|Mitc4ShellCli|FesaApplication" --output-on-failure
& "C:/Program Files/LLVM/bin/clang-format.exe" --dry-run --Werror `
  include/fesa/analysis/analysis.h `
  include/fesa/analysis/linear_static_analysis.h `
  src/fesa/analysis/linear_static_analysis.cpp `
  tests/unit/analysis/analysis_test.cpp `
  tests/integration/analysis/linear_static_analysis_test.cpp
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug --show-only=json-v1
ctest --test-dir .harness/build -C Debug --output-on-failure

검증 및 상태 갱신

• RED base/lifecycle failure, focused order/count/atomicity and full CTest를 summary에 기록한다.
• Approved lifecycle or output timing regression is error.
• 성공 시 현재 Step만 completed로 갱신한다.
• timestamp, retry, commit, advancement는 Executor 소유다.

금지사항

• Dynamic/eigen/spectrum/random analysis behavior or state를 추가하지 마라.
• Future procedure hooks를 Analysis base에 추가하지 마라.
• Factorization/load order를 변경하지 마라.
• 직접 commit하거나 hook script를 수동 실행하지 마라.