FESADev/docs/superpowers/plans/2026-08-09-linear-static-3d-euler-beam-harness-phase.md

# Linear Static 3D Euler Beam Harness Phase Construction 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:** Create the approved 29-step Harness phase that drives the FESA V0 single-step B33 linear-static solver from upstream contracts through release readiness.

**Architecture:** The phase is a sequence of seven document gates, eighteen TDD implementation steps, and four final verification gates. Each `stepN.md` is self-contained, names its role/skill and owned paths, preserves the approved design as the source of truth, and delegates per-step commits and timestamps to `scripts/execute.py`.

**Tech Stack:** Markdown and JSON phase descriptors; C++17; MSVC x64 Debug; CMake/CTest; GoogleTest from `C:/git/googletest`; Intel oneMKL/oneTBB; HDF5; Python 3 Harness runner.

## Global Constraints

- The approved source of truth is `docs/superpowers/specs/2026-08-08-linear-static-3d-euler-beam-design.md`; phase steps must not silently broaden or reinterpret it.
- The solver scope is one `*STEP, *STATIC` using Abaqus `TYPE=B33`; `TYPE=B31`, multiple steps, instance transforms, nested assemblies, and `*DLOAD` input remain unsupported.
- Runtime order keeps `Kff` factorization before load-vector assembly and separates factorization from substitution.
- Production C++ changes use `RED -> GREEN -> VERIFY`; every production file has a related GoogleTest file.
- Validation uses MSVC x64 Debug and the exact dependency cache variables in the approved design; production CMake must not hardcode the local GoogleTest path.
- `reference/cantilever beam/` is read-only and must not be renamed, rewritten, regenerated, or repaired by the phase.
- Beam stress is written and tested, but Abaqus stress reference comparison is explicitly N/A.
- Harness owns per-step commits and timestamps; a step must update only its phase status and must not invoke `git commit`.
- Before `python scripts/execute.py linear-static-3d-euler-beam`, use a clean worktree or a separate worktree because the current executor stages with `git add -A`.

---

### Task 1: Create Phase Indexes

**Files:**
- Create: `phases/index.json`
- Create: `phases/linear-static-3d-euler-beam/index.json`

**Interfaces:**
- Consumes: approved phase name and 29-step table from the design specification.
- Produces: top-level pending phase registration and contiguous step numbers `0..28` with kebab-case names.

- [ ] **Step 1: Register the phase**

```json
{
  "phases": [
    { "dir": "linear-static-3d-euler-beam", "status": "pending" }
  ]
}
```

- [ ] **Step 2: Create the task index**

Use `project: "FESA Structural Solver"`, `phase: "linear-static-3d-euler-beam"`, and the exact step names from specification section 3. Do not add timestamps; the executor owns them.

- [ ] **Step 3: Validate both JSON files**

```powershell
Get-Content -Raw phases/index.json | ConvertFrom-Json | Out-Null
$phase = Get-Content -Raw phases/linear-static-3d-euler-beam/index.json | ConvertFrom-Json
if ($phase.steps.Count -ne 29) { throw 'Expected 29 steps' }
if (($phase.steps.step -join ',') -ne ((0..28) -join ',')) { throw 'Step numbers are not contiguous' }
```

- [ ] **Step 4: Executor commit checkpoint**

Do not run `git commit`; `scripts/execute.py` commits phase execution results. The phase-construction changes remain for the user to review and commit.

### Task 2: Create Upstream Contract Gate Steps

**Files:**
- Create: `phases/linear-static-3d-euler-beam/step0.md` through `step6.md`

**Interfaces:**
- Consumes: approved design, formulation, root project documents, gate-specific README files, and exact FESA skill contracts.
- Produces: requirements, research, formulation alignment, numerical review, I/O, reference-model, and implementation-plan documents.

- [ ] **Step 1: Define role and skill ownership**

```text
0 requirement-agent / fesa-requirements-baseline
1 research-agent / fesa-research-evidence + fem-theory-query
2 formulation-agent / fesa-formulation-spec
3 numerical-review-agent / fesa-numerical-review
4 io-definition-agent / fesa-io-contract
5 reference-model-agent / fesa-reference-models
6 implementation-planning-agent / fesa-cpp-msvc-tdd
```

- [ ] **Step 2: Make each document gate self-contained**

Each step names required input paths, the exact output path, mandatory sections/status, immutable decisions, executable PowerShell checks, status-update rules, and prohibited changes. Step 2 aligns the existing formulation without changing its approved mathematical meaning; Step 5 documents the approved legacy bundle exception without modifying `reference/`.

- [ ] **Step 3: Verify gate file structure**

```powershell
0..6 | ForEach-Object {
  $path = "phases/linear-static-3d-euler-beam/step$_.md"
  if (-not (Test-Path $path)) { throw "Missing $path" }
  foreach ($section in @('## 읽어야 할 파일','## 작업','## Acceptance Criteria','## 검증 절차','## 금지사항')) {
    if (-not (Select-String -LiteralPath $path -SimpleMatch $section -Quiet)) {
      throw "$path missing $section"
    }
  }
}
```

- [ ] **Step 4: Executor commit checkpoint**

Do not commit manually; the executor will commit each completed gate.

### Task 3: Create C++ TDD Implementation Steps

**Files:**
- Create: `phases/linear-static-3d-euler-beam/step7.md` through `step24.md`

**Interfaces:**
- Consumes: approved upstream documents produced by Steps 0–6.
- Produces: build foundation, core/model/parser/FEM/math/solver/result modules, tests, and `fesa.exe`.

- [ ] **Step 1: Lock module order and interfaces**

```cpp
Matrix EulerBeam3D::localStiffness() const;
Matrix EulerBeam3D::globalStiffness() const;
Vector EulerBeam3D::localEquivalentLoad(const ConstantLocalLineLoad&) const;
BeamRecovery EulerBeam3D::recover(const Vector& globalElementDisplacement) const;

class LinearSolver {
public:
    virtual ~LinearSolver() = default;
    virtual Status factorize(const SparseMatrix& matrix) = 0;
    virtual Status solve(const Vector& rhs, Vector& solution) const = 0;
};
```

The remaining steps define signatures for diagnostics, semantic mapping, active views, DOF numbering, state, deterministic parallel assembly, constraints, load assembly, result recovery, HDF5 writing, and orchestration without exposing MKL/TBB/HDF5 types across adapter boundaries.

- [ ] **Step 2: Encode test-first execution in every production step**

Each Step 8–24 contains these independently verifiable actions:

```text
1. Add the named GoogleTest cases before production edits.
2. Build and run the targeted CTest regex; record the expected missing-behavior RED failure.
3. Add only the production behavior owned by the step.
4. Rebuild and run the targeted test to GREEN.
5. Run CTest discovery and the full CTest suite for VERIFY.
```

Step 7 creates the build/test foundation and proves at least one discovered test. Step 24 also provides the end-to-end CLI and test-only B33 reference comparison command used read-only by Step 26.

- [ ] **Step 3: Use the approved dependency configure command**

```powershell
cmake -S . -B .harness/build -A x64 `
  -DFESA_GTEST_SOURCE_DIR=C:/git/googletest `
  "-DMKL_DIR=C:/Program Files (x86)/Intel/oneAPI/mkl/2026.1/lib/cmake/mkl" `
  "-DTBB_DIR=C:/Program Files (x86)/Intel/oneAPI/tbb/2023.1/lib/cmake/tbb" `
  "-DHDF5_DIR=C:/Program Files/HDF_Group/HDF5/2.1.1/cmake"
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
```

- [ ] **Step 4: Verify all implementation step descriptors**

```powershell
7..24 | ForEach-Object {
  $path = "phases/linear-static-3d-euler-beam/step$_.md"
  if (-not (Test-Path $path)) { throw "Missing $path" }
  foreach ($text in @('MSVC x64 Debug','## Acceptance Criteria','## 금지사항')) {
    if (-not (Select-String -LiteralPath $path -SimpleMatch $text -Quiet)) {
      throw "$path missing $text"
    }
  }
}
```

- [ ] **Step 5: Executor commit checkpoint**

Do not commit manually; the executor creates one feature commit and one metadata commit per completed step.

### Task 4: Create Final Verification Gate Steps

**Files:**
- Create: `phases/linear-static-3d-euler-beam/step25.md` through `step28.md`

**Interfaces:**
- Consumes: completed solver, generated HDF5 result, approved read-only reference CSVs, and all upstream reports.
- Produces: build/test, reference-verification, physics-evaluation, and release-readiness reports.

- [ ] **Step 1: Define strict gate transitions**

```text
25 pass-for-reference-verification
  -> 26 pass-for-physics-evaluation
  -> 27 pass-for-release-agent
  -> 28 ready-for-release
```

Each later step must block or emit the appropriate `needs-*` status when its required predecessor is not passing. Step 26 applies the exact component-scale mixed tolerance, Step 27 checks physical equilibrium and signs, and Step 28 audits traceability and limitations without publishing anything.

- [ ] **Step 2: Enforce read-only boundaries**

Steps 26–28 must not edit source, tests, CMake, upstream contracts, reference artifacts, or tolerance policy. Step 26 must state stress comparison is N/A while requiring the stress output schema/test evidence.

- [ ] **Step 3: Verify the final gate descriptors**

```powershell
25..28 | ForEach-Object {
  $path = "phases/linear-static-3d-euler-beam/step$_.md"
  if (-not (Test-Path $path)) { throw "Missing $path" }
  foreach ($text in @('## Acceptance Criteria','reference')) {
    if (-not (Select-String -LiteralPath $path -SimpleMatch $text -Quiet)) {
      throw "$path missing $text"
    }
  }
}
```

- [ ] **Step 4: Executor commit checkpoint**

Do not commit manually; Harness owns execution commits and timestamps.

### Task 5: Validate the Generated Phase

**Files:**
- Read: `docs/superpowers/plans/2026-08-09-linear-static-3d-euler-beam-harness-phase.md`
- Read: `phases/index.json`
- Read: `phases/linear-static-3d-euler-beam/index.json`
- Read: `phases/linear-static-3d-euler-beam/step0.md` through `step28.md`

**Interfaces:**
- Consumes: all generated planning artifacts.
- Produces: structural and source-contract verification evidence; no solver execution.

- [ ] **Step 1: Parse and cross-check JSON**

```powershell
$top = Get-Content -Raw phases/index.json | ConvertFrom-Json
$task = Get-Content -Raw phases/linear-static-3d-euler-beam/index.json | ConvertFrom-Json
if (($top.phases | Where-Object dir -eq 'linear-static-3d-euler-beam').status -ne 'pending') { throw 'Top-level phase registration is invalid' }
if ($task.project -ne 'FESA Structural Solver') { throw 'Project name mismatch' }
if ($task.phase -ne 'linear-static-3d-euler-beam') { throw 'Phase name mismatch' }
if ($task.steps.Count -ne 29) { throw 'Step count mismatch' }
```

- [ ] **Step 2: Check step/file correspondence and required sections**

```powershell
$task.steps | ForEach-Object {
  $path = "phases/linear-static-3d-euler-beam/step$($_.step).md"
  if (-not (Test-Path $path)) { throw "Missing $path" }
  if ($_.status -ne 'pending') { throw "Non-pending step $($_.step)" }
}
```

- [ ] **Step 3: Scan for placeholders and whitespace errors**

```powershell
$markers = @(('T' + 'BD'), ('T' + 'ODO'), ('FIX' + 'ME'), ('PLACE' + 'HOLDER'),
  ('implement' + ' later'), ('Similar' + ' to Task'))
$unfinished = rg -n ($markers -join '|') `
  docs/superpowers/plans/2026-08-09-linear-static-3d-euler-beam-harness-phase.md `
  phases/linear-static-3d-euler-beam
if ($LASTEXITCODE -eq 0) { throw "Unfinished marker found:`n$unfinished" }
git diff --check
```

Expected: no placeholder matches and no whitespace errors. CRLF conversion warnings without whitespace error lines are acceptable.

- [ ] **Step 4: Confirm reference artifacts are untouched**

```powershell
git diff --name-only -- reference/
```

Expected: no output.

- [ ] **Step 5: Execution handoff**

After the phase-construction files and existing documentation edits are reviewed and committed, execute from a clean worktree:

```powershell
python scripts/execute.py linear-static-3d-euler-beam
```

Use `--push` only when remote publication is explicitly desired.