docs: add 3d euler beam phase

2026-06-12 17:26:01 +09:00
parent 825e03dbaf
commit 13cf2af899
13 changed files with 891 additions and 0 deletions
@@ -0,0 +1,99 @@
+{
+  "project": "FESA Structural Solver",
+  "phase": "euler-beam-3d",
+  "steps": [
+    {
+      "step": 0,
+      "name": "requirements-baseline",
+      "status": "pending",
+      "allowed_paths": [
+        "docs/requirements/euler-beam-3d.md"
+      ]
+    },
+    {
+      "step": 1,
+      "name": "research-evidence",
+      "status": "pending",
+      "allowed_paths": [
+        "docs/research/euler-beam-3d-research.md"
+      ]
+    },
+    {
+      "step": 2,
+      "name": "formulation-spec",
+      "status": "pending",
+      "allowed_paths": [
+        "docs/formulations/euler-beam-3d-formulation.md"
+      ]
+    },
+    {
+      "step": 3,
+      "name": "numerical-review",
+      "status": "pending",
+      "allowed_paths": [
+        "docs/numerical-reviews/euler-beam-3d-review.md"
+      ]
+    },
+    {
+      "step": 4,
+      "name": "io-reference-contract",
+      "status": "pending",
+      "allowed_paths": [
+        "docs/io-definitions/euler-beam-3d-io.md",
+        "docs/reference-models/euler-beam-3d-reference-models.md"
+      ]
+    },
+    {
+      "step": 5,
+      "name": "implementation-plan",
+      "status": "pending",
+      "allowed_paths": [
+        "docs/implementation-plans/euler-beam-3d-implementation-plan.md"
+      ]
+    },
+    {
+      "step": 6,
+      "name": "model-beam-topology",
+      "status": "pending",
+      "allowed_paths": [
+        "src/fesa/model/element.hpp",
+        "src/fesa/model/element.cpp",
+        "tests/unit/model_element_test.cpp"
+      ]
+    },
+    {
+      "step": 7,
+      "name": "local-stiffness-kernel",
+      "status": "pending",
+      "allowed_paths": [
+        "src/fesa/elements/",
+        "tests/unit/euler_beam_3d_*_test.cpp"
+      ]
+    },
+    {
+      "step": 8,
+      "name": "global-transform-recovery",
+      "status": "pending",
+      "allowed_paths": [
+        "src/fesa/elements/",
+        "tests/unit/euler_beam_3d_*_test.cpp"
+      ]
+    },
+    {
+      "step": 9,
+      "name": "build-test-report",
+      "status": "pending",
+      "allowed_paths": [
+        "docs/build-test-reports/euler-beam-3d-build-test.md"
+      ]
+    },
+    {
+      "step": 10,
+      "name": "release-readiness-note",
+      "status": "pending",
+      "allowed_paths": [
+        "docs/releases/euler-beam-3d-release.md"
+      ]
+    }
+  ]
+}
@@ -0,0 +1,63 @@
+# Step 0: requirements-baseline
+
+## Read These Files First
+
+Read the following files before editing:
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/requirements/README.md`
+
+## Task
+
+Create `/docs/requirements/euler-beam-3d.md` for a kernel-first 3D Euler-Bernoulli beam feature.
+
+Scope the first implementable increment narrowly:
+
+- two-node, straight, prismatic, small-displacement 3D Euler-Bernoulli beam element
+- six mechanical DOFs per node in this order: `ux, uy, uz, rx, ry, rz`
+- linear elastic section constants: `E`, `G`, `A`, `J`, `Iy`, `Iz`
+- local and global 12x12 stiffness matrix support
+- local and global element end-force recovery from nodal displacement vectors
+- no shear deformation, warping, end releases, offsets, distributed loads, mass matrix, geometric stiffness, nonlinear kinematics, dynamics, or thermal coupling in this increment
+- no Abaqus reference CSV generation in this increment
+- no full Abaqus compatibility claim
+
+The document must contain:
+
+- metadata: `feature_id: euler-beam-3d`, owner agent, status
+- explicit assumptions and non-goals
+- `must` requirements with stable IDs such as `EB3D-REQ-001`
+- verification quantities: displacement DOFs, reactions/end forces, stiffness symmetry, rigid body modes, local/global transformation consistency
+- acceptance criteria that distinguish kernel completion from full solver release readiness
+- open issues for parser integration, reference artifact availability, and full end-to-end assembly
+
+Do not create C++ files in this step.
+
+## Tests To Write First
+
+- No C++ test is required in this documentation-only step.
+- Still run the harness validation commands in the acceptance criteria.
+
+## Acceptance Criteria
+
+```powershell
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+```
+
+## Verification Notes
+
+1. Confirm the requirements do not claim full Abaqus compatibility.
+2. Confirm each `must` requirement has an acceptance criterion or a downstream verification hook.
+3. Update `phases/euler-beam-3d/index.json` step 0:
+   - success: `"status": "completed"`, `"summary": "3D Euler beam kernel requirements baseline added"`
+   - failure after retries: `"status": "error"`, `"error_message": "<specific error>"`
+   - blocked: `"status": "blocked"`, `"blocked_reason": "<specific reason>"`
+
+## Forbidden
+
+- Do not create or modify reference CSV files.
+- Do not modify source or test files.
@@ -0,0 +1,60 @@
+# Step 1: research-evidence
+
+## Read These Files First
+
+Read the following files before editing:
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/requirements/euler-beam-3d.md`
+- `/docs/research/README.md`
+
+## Task
+
+Create `/docs/research/euler-beam-3d-research.md`.
+
+Summarize the evidence needed to implement the approved kernel-first 3D Euler-Bernoulli beam increment. The document must be implementation-oriented and must include:
+
+- supported theory: straight prismatic Euler-Bernoulli beam, axial, torsion, and two uncoupled bending planes
+- assumptions and applicability limits
+- local DOF ordering and sign convention used by the planned matrix
+- source reliability classification
+- benchmark-style checks that do not require external reference solver execution:
+  - local stiffness symmetry
+  - axial-only response
+  - torsion-only response
+  - bending about local `y`
+  - bending about local `z`
+  - rigid body translation/rotation zero internal forces in local coordinates
+  - global transform identity for an axis-aligned beam
+- risks: orientation vector parallel to element axis, near-zero length, nonpositive section constants, ill-conditioning for very slender elements
+
+If internet access or a FEM wiki is used, cite sources briefly. Do not include long copyrighted excerpts.
+
+Do not create C++ files in this step.
+
+## Tests To Write First
+
+- No C++ test is required in this documentation-only step.
+
+## Acceptance Criteria
+
+```powershell
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+```
+
+## Verification Notes
+
+1. Confirm the research document ties each source or theory point to a planned implementation check.
+2. Confirm unresolved items are listed as risks or open issues instead of silently assumed.
+3. Update `phases/euler-beam-3d/index.json` step 1:
+   - success: `"status": "completed"`, `"summary": "3D Euler beam research evidence added"`
+   - failure after retries: `"status": "error"`, `"error_message": "<specific error>"`
+   - blocked: `"status": "blocked"`, `"blocked_reason": "<specific reason>"`
+
+## Forbidden
+
+- Do not modify source, test, reference, or I/O contract files.
@@ -0,0 +1,60 @@
+# Step 10: release-readiness-note
+
+## Read These Files First
+
+Read the following files before editing:
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ADR.md`
+- `/docs/releases/README.md`
+- `/docs/requirements/euler-beam-3d.md`
+- `/docs/io-definitions/euler-beam-3d-io.md`
+- `/docs/reference-models/euler-beam-3d-reference-models.md`
+- `/docs/build-test-reports/euler-beam-3d-build-test.md`
+
+## Task
+
+Create `/docs/releases/euler-beam-3d-release.md`.
+
+This is a readiness note, not a release approval. It must state:
+
+- status: `not-release-ready-kernel-increment-complete` unless all upstream gates and reference artifacts somehow exist
+- completed scope: local/global stiffness and end-force kernel for two-node 3D Euler-Bernoulli beam
+- missing for full feature release:
+  - parser implementation for the approved Abaqus subset
+  - section/property semantic model integration
+  - assembler/static solver integration
+  - HDF5 result emission for beam quantities
+  - stored Abaqus reference artifacts
+  - reference comparison report
+  - physics sanity report
+- known limitations from requirements
+- next recommended phase or phase dependencies
+
+Do not change source or tests in this step.
+
+## Tests To Write First
+
+- No C++ test is required in this documentation-only step.
+
+## Acceptance Criteria
+
+```powershell
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+```
+
+## Verification Notes
+
+1. Confirm the note does not claim full release readiness.
+2. Confirm all missing gates are explicit.
+3. Update `phases/euler-beam-3d/index.json` step 10:
+   - success: `"status": "completed"`, `"summary": "3D Euler beam release readiness note added"`
+   - failure after retries: `"status": "error"`, `"error_message": "<specific error>"`
+   - blocked: `"status": "blocked"`, `"blocked_reason": "<specific reason>"`
+
+## Forbidden
+
+- Do not create or modify reference artifacts.
+- Do not modify source, tests, requirements, formulations, or I/O contracts.
@@ -0,0 +1,63 @@
+# Step 2: formulation-spec
+
+## Read These Files First
+
+Read the following files before editing:
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/requirements/euler-beam-3d.md`
+- `/docs/research/euler-beam-3d-research.md`
+- `/docs/formulations/README.md`
+
+## Task
+
+Create `/docs/formulations/euler-beam-3d-formulation.md`.
+
+The formulation must define the implementation contract for the C++ kernel. Include:
+
+- local coordinate system: local `x` from node 1 to node 2; local `y` from the user orientation vector projected normal to local `x`; local `z = x cross y`
+- local DOF order: `[u1, v1, w1, rx1, ry1, rz1, u2, v2, w2, rx2, ry2, rz2]`
+- section constants: `E`, `G`, `A`, `J`, `Iy`, `Iz`
+- local 12x12 stiffness matrix terms for:
+  - axial: `EA/L`
+  - torsion: `GJ/L`
+  - bending in local `x-y` using `EIz`
+  - bending in local `x-z` using `EIy`
+- transformation matrix convention and global stiffness equation `K_global = T^T K_local T`
+- end-force recovery equation `f_local = K_local u_local`
+- validation tolerances for unit tests, using deterministic double comparisons
+- singular and invalid input handling:
+  - zero or near-zero length throws `std::invalid_argument`
+  - nonpositive `E`, `G`, `A`, `J`, `Iy`, or `Iz` throws `std::invalid_argument`
+  - orientation vector parallel to beam axis throws `std::invalid_argument`
+
+Use compact matrices and named scalar coefficients so the implementation step can transcribe directly.
+
+Do not create C++ files in this step.
+
+## Tests To Write First
+
+- No C++ test is required in this documentation-only step.
+
+## Acceptance Criteria
+
+```powershell
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+```
+
+## Verification Notes
+
+1. Confirm the matrix is symmetric by construction.
+2. Confirm local/global transformation convention is unambiguous.
+3. Update `phases/euler-beam-3d/index.json` step 2:
+   - success: `"status": "completed"`, `"summary": "3D Euler beam formulation contract added"`
+   - failure after retries: `"status": "error"`, `"error_message": "<specific error>"`
+   - blocked: `"status": "blocked"`, `"blocked_reason": "<specific reason>"`
+
+## Forbidden
+
+- Do not modify requirements, source, tests, or reference artifacts.
@@ -0,0 +1,56 @@
+# Step 3: numerical-review
+
+## Read These Files First
+
+Read the following files before editing:
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/requirements/euler-beam-3d.md`
+- `/docs/research/euler-beam-3d-research.md`
+- `/docs/formulations/euler-beam-3d-formulation.md`
+- `/docs/numerical-reviews/README.md`
+
+## Task
+
+Create `/docs/numerical-reviews/euler-beam-3d-review.md`.
+
+Review the formulation for implementation readiness. The review must include:
+
+- dimension and units check for each stiffness coefficient
+- symmetry and rigid body mode expectations
+- local axis construction risks
+- positive semi-definite local stiffness expectation before constraints
+- test obligations before production code
+- known numerical limits for slender beams and very small section constants
+- pass/fail verdict for kernel implementation planning
+
+If the formulation is not ready, mark the document status as `needs-upstream-decision` and update this phase step as blocked with a concrete reason.
+
+Do not create C++ files in this step.
+
+## Tests To Write First
+
+- No C++ test is required in this documentation-only step.
+
+## Acceptance Criteria
+
+```powershell
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+```
+
+## Verification Notes
+
+1. Confirm the review does not change requirements or formulation.
+2. Confirm implementation-owned risks are turned into concrete tests.
+3. Update `phases/euler-beam-3d/index.json` step 3:
+   - success: `"status": "completed"`, `"summary": "3D Euler beam numerical review added"`
+   - failure after retries: `"status": "error"`, `"error_message": "<specific error>"`
+   - blocked: `"status": "blocked"`, `"blocked_reason": "<specific reason>"`
+
+## Forbidden
+
+- Do not modify requirements, formulation, source, tests, or reference artifacts.
@@ -0,0 +1,68 @@
+# Step 4: io-reference-contract
+
+## Read These Files First
+
+Read the following files before editing:
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/requirements/euler-beam-3d.md`
+- `/docs/formulations/euler-beam-3d-formulation.md`
+- `/docs/numerical-reviews/euler-beam-3d-review.md`
+- `/docs/io-definitions/README.md`
+- `/docs/reference-models/README.md`
+
+## Task
+
+Create two documents:
+
+- `/docs/io-definitions/euler-beam-3d-io.md`
+- `/docs/reference-models/euler-beam-3d-reference-models.md`
+
+The I/O contract must describe the planned Abaqus subset without claiming it is implemented in this kernel increment:
+
+- element keyword mapping candidate: two-node beam topology equivalent to Abaqus `B31`
+- section keyword candidate: beam section constants sufficient for `A`, `J`, `Iy`, `Iz`, `E`, and `G`
+- orientation data requirement for constructing local axes
+- boundary/load DOFs: `1..6` map to `ux, uy, uz, rx, ry, rz`
+- HDF5 output quantities expected after solver integration: nodal displacement, reaction, element internal force, stress placeholders if stress recovery is later approved
+- unsupported input cases and diagnostics
+
+The reference model contract must list required future models without generating artifacts:
+
+- axial cantilever bar-as-beam
+- torsion cantilever
+- bending cantilever about local `y`
+- bending cantilever about local `z`
+- skew-oriented beam transform check
+
+For each future model, specify expected files under `reference/<model-id>/` and which CSV quantities are required. State that Abaqus reference CSVs must not be generated or modified in this phase.
+
+Do not create C++ files in this step.
+
+## Tests To Write First
+
+- No C++ test is required in this documentation-only step.
+
+## Acceptance Criteria
+
+```powershell
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+```
+
+## Verification Notes
+
+1. Confirm reference artifacts are specified, not created.
+2. Confirm unsupported parser or solver paths are explicit open issues.
+3. Update `phases/euler-beam-3d/index.json` step 4:
+   - success: `"status": "completed"`, `"summary": "3D Euler beam I/O and reference model contracts added"`
+   - failure after retries: `"status": "error"`, `"error_message": "<specific error>"`
+   - blocked: `"status": "blocked"`, `"blocked_reason": "<specific reason>"`
+
+## Forbidden
+
+- Do not create or modify files under `/reference/`.
+- Do not modify source or tests.
@@ -0,0 +1,75 @@
+# Step 5: implementation-plan
+
+## Read These Files First
+
+Read the following files before editing:
+
+- `/AGENTS.md`
+- `/docs/PRD.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/SOLVER_AGENT_DESIGN.md`
+- `/docs/implementation-plans/README.md`
+- `/docs/requirements/euler-beam-3d.md`
+- `/docs/research/euler-beam-3d-research.md`
+- `/docs/formulations/euler-beam-3d-formulation.md`
+- `/docs/numerical-reviews/euler-beam-3d-review.md`
+- `/docs/io-definitions/euler-beam-3d-io.md`
+- `/docs/reference-models/euler-beam-3d-reference-models.md`
+- `/src/fesa/model/element.hpp`
+- `/tests/unit/model_element_test.cpp`
+
+## Task
+
+Create `/docs/implementation-plans/euler-beam-3d-implementation-plan.md`.
+
+The implementation plan must be ready for C++ TDD work and must include:
+
+- readiness check for requirements, research, formulation, numerical review, I/O, reference model contract
+- explicit kernel-first implementation scope
+- tasks matching the remaining phase steps:
+  - model beam topology
+  - local stiffness kernel
+  - global transform and end-force recovery
+  - build/test report
+  - release readiness note
+- test IDs and RED/GREEN conditions for each production change
+- candidate files:
+  - `src/fesa/model/element.hpp`
+  - `src/fesa/model/element.cpp`
+  - `tests/unit/model_element_test.cpp`
+  - `src/fesa/elements/euler_beam_3d.hpp`
+  - `src/fesa/elements/euler_beam_3d.cpp`
+  - `tests/unit/euler_beam_3d_local_stiffness_test.cpp`
+  - `tests/unit/euler_beam_3d_transform_recovery_test.cpp`
+- CTest commands:
+  - `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model_element_test`
+  - `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_local_stiffness_test`
+  - `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_transform_recovery_test`
+- acceptance traceability from requirements to tests
+
+Do not create C++ files in this step.
+
+## Tests To Write First
+
+- No C++ test is required in this documentation-only step.
+
+## Acceptance Criteria
+
+```powershell
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+```
+
+## Verification Notes
+
+1. Confirm every production file named in the plan has a related test.
+2. Confirm the plan does not ask Implementation Agent to change requirements, formulation, I/O contracts, reference artifacts, or tolerance policies.
+3. Update `phases/euler-beam-3d/index.json` step 5:
+   - success: `"status": "completed"`, `"summary": "3D Euler beam implementation plan added"`
+   - failure after retries: `"status": "error"`, `"error_message": "<specific error>"`
+   - blocked: `"status": "blocked"`, `"blocked_reason": "<specific reason>"`
+
+## Forbidden
+
+- Do not modify source, tests, reference artifacts, or CMake files.
@@ -0,0 +1,79 @@
+# Step 6: model-beam-topology
+
+## Read These Files First
+
+Read the following files before editing:
+
+- `/AGENTS.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/implementation-plans/euler-beam-3d-implementation-plan.md`
+- `/src/fesa/model/element.hpp`
+- `/src/fesa/model/element.cpp`
+- `/tests/unit/model_element_test.cpp`
+
+## Task
+
+Use TDD to add a semantic model topology for a two-node 3D beam.
+
+Required production behavior:
+
+- Add `beam2` to `fesa::model::ElementTopology`.
+- Preserve existing `truss2`, `bar2`, and `unknown` behavior.
+- Do not store equation IDs on `Element`.
+- Do not add section constants to `Element` in this step.
+
+## Tests To Write First
+
+Modify `/tests/unit/model_element_test.cpp` first.
+
+Add a failing assertion that constructs an element with:
+
+- id `ElementId{10}`
+- topology `ElementTopology::beam2`
+- node ids `{NodeId{1}, NodeId{2}}`
+- property id `PropertyId{7}`
+
+The test must verify:
+
+- `element.topology() == ElementTopology::beam2`
+- `element.node_ids().size() == 2`
+- existing `bar2` behavior still works or the test still covers it
+
+RED command:
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model_element_test
+```
+
+Expected RED: compile failure because `ElementTopology::beam2` is not defined.
+
+Then implement the minimal enum addition.
+
+GREEN command:
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model_element_test
+```
+
+## Acceptance Criteria
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model_element_test
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+```
+
+## Verification Notes
+
+1. Confirm the test failed before editing production code.
+2. Confirm no unrelated model refactor was made.
+3. Update `phases/euler-beam-3d/index.json` step 6:
+   - success: `"status": "completed"`, `"summary": "beam2 model topology added with unit test"`
+   - failure after retries: `"status": "error"`, `"error_message": "<specific error>"`
+   - blocked: `"status": "blocked"`, `"blocked_reason": "<specific reason>"`
+
+## Forbidden
+
+- Do not create parser code.
+- Do not add beam stiffness code in this step.
@@ -0,0 +1,110 @@
+# Step 7: local-stiffness-kernel
+
+## Read These Files First
+
+Read the following files before editing:
+
+- `/AGENTS.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/formulations/euler-beam-3d-formulation.md`
+- `/docs/numerical-reviews/euler-beam-3d-review.md`
+- `/docs/implementation-plans/euler-beam-3d-implementation-plan.md`
+
+Also read any files created by previous steps in this phase.
+
+## Task
+
+Use TDD to create the local 12x12 stiffness kernel for the 3D Euler-Bernoulli beam.
+
+Create:
+
+- `/src/fesa/elements/euler_beam_3d.hpp`
+- `/src/fesa/elements/euler_beam_3d.cpp`
+- `/tests/unit/euler_beam_3d_local_stiffness_test.cpp`
+
+Required API:
+
+```cpp
+namespace fesa::elements {
+
+using Vector12 = std::array<double, 12>;
+using Matrix12 = std::array<double, 144>;
+
+struct EulerBeam3DSection {
+    double young_modulus;
+    double shear_modulus;
+    double area;
+    double torsion_constant;
+    double second_moment_y;
+    double second_moment_z;
+};
+
+Matrix12 euler_beam_3d_local_stiffness(double length, const EulerBeam3DSection& section);
+Vector12 euler_beam_3d_local_end_forces(double length,
+                                        const EulerBeam3DSection& section,
+                                        const Vector12& local_displacements);
+
+} // namespace fesa::elements
+```
+
+Implementation rules:
+
+- Matrix storage is row-major: index `(row, col)` is `row * 12 + col`.
+- Validate `length > 0` and all section constants are positive; throw `std::invalid_argument` otherwise.
+- Use only C++17 standard library.
+- Do not introduce an external linear algebra dependency.
+- Do not edit CMake files; source and test globs should pick up new files.
+
+## Tests To Write First
+
+Create `/tests/unit/euler_beam_3d_local_stiffness_test.cpp` before production code.
+
+Test behavior:
+
+- For `L = 2.0`, `E = 210.0`, `G = 80.0`, `A = 3.0`, `J = 4.0`, `Iy = 5.0`, `Iz = 6.0`, verify representative matrix entries:
+  - axial: `K(0,0) = EA/L`, `K(0,6) = -EA/L`, `K(6,6) = EA/L`
+  - torsion: `K(3,3) = GJ/L`, `K(3,9) = -GJ/L`, `K(9,9) = GJ/L`
+  - local `x-y` bending uses `EIz`: `K(1,1) = 12*E*Iz/L^3`, `K(1,5) = 6*E*Iz/L^2`, `K(5,5) = 4*E*Iz/L`
+  - local `x-z` bending uses `EIy`: `K(2,2) = 12*E*Iy/L^3`, `K(2,4) = -6*E*Iy/L^2`, `K(4,4) = 4*E*Iy/L`
+- Verify all entries are symmetric within `1.0e-10`.
+- Verify `euler_beam_3d_local_end_forces` returns `K * u` for a displacement vector with at least three nonzero components.
+- Verify invalid length and nonpositive section constants throw `std::invalid_argument`.
+
+RED command:
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_local_stiffness_test
+```
+
+Expected RED: test executable missing or compile failure because the header/API does not exist.
+
+Then implement the minimal API.
+
+GREEN command:
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_local_stiffness_test
+```
+
+## Acceptance Criteria
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_local_stiffness_test
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+```
+
+## Verification Notes
+
+1. Confirm RED failed before production code was added.
+2. Confirm no parser, assembly, or results writer code was changed.
+3. Update `phases/euler-beam-3d/index.json` step 7:
+   - success: `"status": "completed"`, `"summary": "local 3D Euler beam stiffness and local end-force kernel added"`
+   - failure after retries: `"status": "error"`, `"error_message": "<specific error>"`
+   - blocked: `"status": "blocked"`, `"blocked_reason": "<specific reason>"`
+
+## Forbidden
+
+- Do not add shear deformation or Timoshenko terms.
+- Do not modify reference artifacts.
@@ -0,0 +1,97 @@
+# Step 8: global-transform-recovery
+
+## Read These Files First
+
+Read the following files before editing:
+
+- `/AGENTS.md`
+- `/docs/ARCHITECTURE.md`
+- `/docs/ADR.md`
+- `/docs/formulations/euler-beam-3d-formulation.md`
+- `/docs/numerical-reviews/euler-beam-3d-review.md`
+- `/docs/implementation-plans/euler-beam-3d-implementation-plan.md`
+- `/src/fesa/elements/euler_beam_3d.hpp`
+- `/src/fesa/elements/euler_beam_3d.cpp`
+- `/tests/unit/euler_beam_3d_local_stiffness_test.cpp`
+
+## Task
+
+Use TDD to add local/global transformation and global end-force recovery to the 3D Euler-Bernoulli beam kernel.
+
+Extend the API in `/src/fesa/elements/euler_beam_3d.hpp`:
+
+```cpp
+using Vector3 = std::array<double, 3>;
+
+struct EulerBeam3DGeometry {
+    Vector3 node1;
+    Vector3 node2;
+    Vector3 orientation;
+};
+
+Matrix12 euler_beam_3d_global_stiffness(const EulerBeam3DGeometry& geometry,
+                                        const EulerBeam3DSection& section);
+Vector12 euler_beam_3d_global_end_forces(const EulerBeam3DGeometry& geometry,
+                                         const EulerBeam3DSection& section,
+                                         const Vector12& global_displacements);
+```
+
+Implementation rules:
+
+- local `x` is normalized `node2 - node1`
+- local `y` is the normalized projection of `orientation` onto the plane normal to local `x`
+- local `z = x cross y`
+- use the same 3x3 rotation block for translational and rotational DOFs
+- compute `K_global = T^T K_local T`
+- compute global end forces by transforming global displacements to local, recovering local forces, then transforming forces back to global
+- throw `std::invalid_argument` for zero-length element, zero orientation vector, or orientation parallel to the beam axis
+
+## Tests To Write First
+
+Create `/tests/unit/euler_beam_3d_transform_recovery_test.cpp` before production code.
+
+Test behavior:
+
+- Axis-aligned beam from `(0,0,0)` to `(2,0,0)` with orientation `(0,1,0)` gives global stiffness equal to local stiffness.
+- A rotated beam preserves stiffness symmetry.
+- A rigid global translation vector produces near-zero global end forces.
+- A simple global axial extension on the axis-aligned beam produces equal and opposite axial end forces.
+- Parallel orientation vector throws `std::invalid_argument`.
+
+RED command:
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_transform_recovery_test
+```
+
+Expected RED: test executable missing or compile failure because the transform API does not exist.
+
+Then implement the minimal API.
+
+GREEN command:
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R euler_beam_3d_transform_recovery_test
+```
+
+## Acceptance Criteria
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R "euler_beam_3d_(local_stiffness|transform_recovery)_test"
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+```
+
+## Verification Notes
+
+1. Confirm RED failed before production code was added.
+2. Confirm local stiffness tests still pass.
+3. Update `phases/euler-beam-3d/index.json` step 8:
+   - success: `"status": "completed"`, `"summary": "global transform and global end-force recovery added for 3D Euler beam"`
+   - failure after retries: `"status": "error"`, `"error_message": "<specific error>"`
+   - blocked: `"status": "blocked"`, `"blocked_reason": "<specific reason>"`
+
+## Forbidden
+
+- Do not add assembly or solver integration in this step.
+- Do not modify reference artifacts.
@@ -0,0 +1,57 @@
+# Step 9: build-test-report
+
+## Read These Files First
+
+Read the following files before editing:
+
+- `/AGENTS.md`
+- `/docs/build-test-reports/README.md`
+- `/docs/implementation-plans/euler-beam-3d-implementation-plan.md`
+- `/src/fesa/elements/euler_beam_3d.hpp`
+- `/src/fesa/elements/euler_beam_3d.cpp`
+- `/tests/unit/euler_beam_3d_local_stiffness_test.cpp`
+- `/tests/unit/euler_beam_3d_transform_recovery_test.cpp`
+
+## Task
+
+Create `/docs/build-test-reports/euler-beam-3d-build-test.md`.
+
+The report must record:
+
+- feature id
+- changed files observed for this phase
+- command log summary with exit codes and short evidence tails
+- validation results for:
+  - harness self-test
+  - CMake configure/build
+  - CTest
+  - feature-specific tests
+- failure classification if anything failed
+- explicit statement that this report does not approve reference verification or release readiness
+
+Do not change source or tests in this step.
+
+## Tests To Write First
+
+- No C++ test is required in this documentation-only step.
+
+## Acceptance Criteria
+
+```powershell
+ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R "model_element_test|euler_beam_3d_(local_stiffness|transform_recovery)_test"
+python -m unittest discover -s scripts -p "test_*.py"
+python scripts/validate_workspace.py
+```
+
+## Verification Notes
+
+1. Record actual command exit codes and concise output evidence.
+2. If validation fails for an environment reason, mark the report `needs-environment-fix` and update this phase step as blocked.
+3. Update `phases/euler-beam-3d/index.json` step 9:
+   - success: `"status": "completed"`, `"summary": "3D Euler beam build/test report added"`
+   - failure after retries: `"status": "error"`, `"error_message": "<specific error>"`
+   - blocked: `"status": "blocked"`, `"blocked_reason": "<specific reason>"`
+
+## Forbidden
+
+- Do not modify source, tests, requirements, formulations, I/O contracts, or reference artifacts.
@@ -3,6 +3,10 @@
    {
      "dir": "solver-core-skeleton",
      "status": "completed"
+    },
+    {
+      "dir": "euler-beam-3d",
+      "status": "pending"
    }
  ]
 }