FESADev/docs/README.md

# FESA Documentation Index

## Purpose
This directory is the source of truth for FESA solver planning, architecture, numerical conventions, verification, and future implementation work.

Before changing solver code, read this file, then read the documents listed under "Required Reading".

## Required Reading
1. `../AGENTS.md`
2. `../PROGRESS.md`
3. `../PLAN.md`
4. `PRD.md`
5. `HARNESS_ENGINEERING.md`
6. `ARCHITECTURE.md`
7. `ADR.md`
8. `NUMERICAL_CONVENTIONS.md`
9. `ABAQUS_INPUT_SUBSET.md`
10. `VERIFICATION_PLAN.md`
11. `RESULTS_SCHEMA.md`
12. `MITC4_FORMULATION.md`

`MULTI_AGENT_RESEARCH_PLAN.md` is required when planning delegated research or creating/updating Codex agents.

## Document Roles
| Document | Role |
|---|---|
| `PRD.md` | Product scope, users, phase roadmap, and Phase 1 success criteria |
| `HARNESS_ENGINEERING.md` | Planner/Generator/Evaluator workflow, sprint contract format, and evaluator rubric |
| `ARCHITECTURE.md` | Solver architecture, ownership boundaries, data flow, and extension model |
| `ADR.md` | Durable architecture decisions and tradeoffs |
| `NUMERICAL_CONVENTIONS.md` | DOF, units, coordinate/sign conventions, precision, boundary/reaction policy |
| `ABAQUS_INPUT_SUBSET.md` | Phase 1 Abaqus `.inp` subset, parser behavior, and unsupported features |
| `VERIFICATION_PLAN.md` | Reference folder contract, benchmark matrix, tolerances, and negative tests |
| `RESULTS_SCHEMA.md` | Step/frame/field/history result model and HDF5 layout |
| `MITC4_FORMULATION.md` | MITC4 baseline formulation contract and pre-implementation open decisions |
| `MULTI_AGENT_RESEARCH_PLAN.md` | Codex agent roles, research sequence, and source map |

Root-level coordination files:

| Document | Role |
|---|---|
| `../PLAN.md` | Forward-looking task plan, priorities, owners, and open questions |
| `../PROGRESS.md` | Completed work, verification results, blockers, and current risks |

## Precedence Rules
When documents conflict:

1. `AGENTS.md` critical rules win.
2. `ADR.md` wins for accepted design decisions.
3. `NUMERICAL_CONVENTIONS.md` wins for DOF, units, precision, signs, and reaction recovery.
4. Domain-specific dossier documents win within their area:
   - Abaqus parser: `ABAQUS_INPUT_SUBSET.md`
   - Verification/reference data: `VERIFICATION_PLAN.md`
   - HDF5 results: `RESULTS_SCHEMA.md`
   - MITC4 element formulation: `MITC4_FORMULATION.md`
5. `ARCHITECTURE.md` provides system structure and should be updated when module responsibilities change.
6. `PRD.md` records scope and roadmap, not low-level implementation details.

If a lower-precedence document needs to override a higher-precedence decision, update or add an ADR first.

## Phase 1 Hard Invariants
- Use 6 shell DOFs per node: `UX`, `UY`, `UZ`, `RX`, `RY`, `RZ`.
- Retain drilling DOF and use a small artificial drilling stiffness.
- Use `double` for real values.
- Use signed int64 ids, indices, equation ids, and sparse indices.
- Do not enforce a unit system; require self-consistent Abaqus-style units.
- Follow Abaqus-compatible sign conventions for results.
- Apply essential boundary conditions by constrained DOF elimination.
- Recover reactions from full vectors: `R_full = K_full * U_full - F_full`.
- Map Abaqus `S4` to FESA `MITC4`.
- Defer `S4R`.
- Require singular system diagnostics.
- Defer mesh quality diagnostics.
- Validate against stored reference artifacts under `../references/`; do not require Abaqus execution.
- Treat Abaqus `*.inp` files plus `*_displacements.csv` result files as the initial accepted reference artifact contract.

## Implementation Readiness Checklist
Before creating Phase 1 implementation steps:

- Use `../references/` as the accepted reference artifact folder.
- Use Abaqus `.inp` files plus solved `*_displacements.csv` files as the first automated displacement reference format.
- Keep a compatibility note when a stored Abaqus reference input contains features outside the current Phase 1 parser subset.
- Finalize the MITC4 transverse shear tying-point equations.
- Finalize the MITC4 local shell basis algorithm.
- Finalize the default artificial drilling stiffness scale.
- Decide whether Phase 1 outputs only `U` and `RF`, or also `S`, `E`, and `SF`.
- Decide the build system, with CMake as the recommended default unless project constraints say otherwise.

## Documentation Change Rules
- Keep changes narrow and update every affected document.
- When a change affects future work, update `../PLAN.md`.
- When a meaningful change is completed, update `../PROGRESS.md`.
- When a rule becomes binding, add or update an ADR.
- When a scope changes, update `PRD.md`.
- When module ownership changes, update `ARCHITECTURE.md`.
- When parser behavior changes, update `ABAQUS_INPUT_SUBSET.md`.
- When numerical conventions change, update `NUMERICAL_CONVENTIONS.md`.
- When output layout changes, update `RESULTS_SCHEMA.md`.
- When benchmark or tolerance policy changes, update `VERIFICATION_PLAN.md`.
- When MITC4 math or assumptions change, update `MITC4_FORMULATION.md`.