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

{
  "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

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

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

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

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:

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

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

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

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

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

$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

$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

$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

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:

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

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