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

# Step 19: Boundary Condition Policy

## 담당 역할과 필수 스킬

- 담당 역할: `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/cpp-object-oriented-modular-refactoring/implementation-plan.md`
- Step 11 source resolver, Step 13 Domain and Step 15 DofManager files
- `/include/fesa/constraints/essential_constraints.h`
- `/src/fesa/constraints/essential_constraints.cpp`
- `/tests/unit/constraints/essential_constraints_test.cpp`
- `/tests/unit/fem/dof_manager_test.cpp`
- `/src/fesa/io/abaqus/domain_mapper.cpp`
- `/src/fesa/CMakeLists.txt`, `/tests/CMakeLists.txt`
- `/phases/cpp-object-oriented-modular-refactoring/index.json`
- `/phases/cpp-object-oriented-modular-refactoring/step19.md`

## 작업

Requirement `R-BC-001`을 구현한다.

1. `/tests/unit/constraints/boundary_condition_test.cpp`와 policy-focused tests를 먼저 추가한다.
   `C-BC-001` uses a fake BoundaryCondition and concrete prescribed displacement to verify stable
   definitions, duplicates/conflicts/nonfinite rejection and nonzero reconstruction.
2. Missing base/policy API provides RED.
3. Create `/include/fesa/constraints/boundary_condition.h`,
   `/include/fesa/constraints/prescribed_displacement.h`,
   `/include/fesa/constraints/essential_constraint_policy.h`,
   `/src/fesa/constraints/prescribed_displacement.cpp`, and
   `/src/fesa/constraints/essential_constraint_policy.cpp`; register sources/tests in CMake.
4. Candidate interfaces:

```cpp
struct ConstraintDefinition {
  std::size_t source_order;
  std::size_t full_dof_index;
  double prescribed_value;
};

struct BoundaryConditionContext {
  const Domain& domain;
  const DofManager& dof_manager;
  const SourceTargetResolver& target_resolver;
};

class BoundaryCondition {
 public:
  virtual ~BoundaryCondition() = default;
  virtual Result<std::vector<ConstraintDefinition>> ResolveConstraints(
      const BoundaryConditionContext& context) const = 0;
};

class PrescribedDisplacementBoundaryCondition final
    : public BoundaryCondition {
 public:
  PrescribedDisplacementBoundaryCondition(SourceTargetQuery target,
                                          DofComponent component,
                                          double prescribed_value,
                                          std::size_t source_order);
  Result<std::vector<ConstraintDefinition>> ResolveConstraints(
      const BoundaryConditionContext& context) const override;

 private:
  SourceTargetQuery target_;
  DofComponent component_;
  double prescribed_value_;
  std::size_t source_order_;
};

struct PartitionedStiffness {
  SparseMatrix k_ff;
  SparseMatrix k_fc;
  SparseMatrix k_cf;
  SparseMatrix k_cc;
};

class EssentialConstraintPolicy {
 public:
  Result<PartitionedStiffness> Partition(
      const SparseMatrix& full_stiffness,
      const DofManager& dof_manager) const;
  Vector GatherFree(const Vector& full_values,
                    const DofManager& dof_manager) const;
  Vector GatherConstrained(const Vector& full_values,
                           const DofManager& dof_manager) const;
  Vector ReconstructFull(const Vector& free_values,
                         const Vector& constrained_values,
                         const DofManager& dof_manager) const;
};
```

5. Domain StepDefinition owns boundary conditions through `unique_ptr<BoundaryCondition>`.
6. Move the existing `PartitionedStiffness` record plus stable elimination, Kff/Kfc/Kcf/Kcc
   extraction, prescribed vector and full/reduced reconstruction behind
   `EssentialConstraintPolicy` without changing algebra or order.
7. A valid all-constrained model keeps 0x0 Kff semantics. Conflicting definitions fail before
   mutating an accepted candidate.

## Acceptance Criteria

```powershell
cmake --build .harness/build --config Debug --target fesa_unit_tests
ctest --test-dir .harness/build -C Debug `
  -R "BoundaryCondition|EssentialConstraints|DofManager|LoadAssembly" --output-on-failure
& "C:/Program Files/LLVM/bin/clang-format.exe" --dry-run --Werror `
  include/fesa/constraints/boundary_condition.h `
  include/fesa/constraints/prescribed_displacement.h `
  include/fesa/constraints/essential_constraint_policy.h `
  (rg --files src/fesa/constraints -g "*.cpp") `
  tests/unit/constraints/boundary_condition_test.cpp `
  tests/unit/constraints/essential_constraints_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 fake boundary, partition/reconstruction/all-constrained tests and full CTest를 summary에 기록한다.
- Algebra/order or nonzero prescribed behavior regression is `error`.
- 성공 시 현재 Step만 `completed`로 갱신한다.
- timestamp, retry, commit, advancement는 Executor 소유다.

## 금지사항

- MPC, penalty, Lagrange multiplier or new BC keyword를 구현하지 마라.
- BoundaryCondition이 K matrix를 직접 partition하게 하지 마라.
- Prescribed displacement를 bool/enum mega-policy로 future behavior와 합치지 마라.
- 직접 commit하거나 hook script를 수동 실행하지 마라.