modify documents

docs/ABAQUS_INPUT_SUBSET.md

@@ -45,6 +45,20 @@ FESA parser rules:
 - Include files through `INPUT=` are not supported in Phase 1.
 - Part/Assembly/Instance syntax is not supported in Phase 1 unless added by ADR.
 
+## Stored Reference Inputs vs Supported Subset
+Files under `references/` are allowed to preserve the exact Abaqus input used to generate reference results, even when the file contains features outside the current Phase 1 parser subset.
+
+Rules:
+- A stored reference input is not automatically a supported FESA input.
+- Unsupported reference features must be documented as compatibility notes.
+- Parser implementation must still reject unsupported features until this document and ADRs explicitly add support.
+- Test harnesses may use normalized or reduced derivative inputs for Phase 1 parser tests, but must keep the original Abaqus reference artifact unchanged.
+
+Current initial reference note:
+- `references/quad_01.inp` was generated by Abaqus/CAE Learning Edition 2024.
+- It uses `TYPE=S4R`, `Part`, `Assembly`, `Instance`, `*Density`, and `NLGEOM=YES`, all of which are outside the current Phase 1 parser/solver subset.
+- Its paired `references/quad_01_displacements.csv` is still valid as a stored displacement reference artifact for future compatibility and regression work.
+
 ## Labels and Names
 Rules:
 - Set and material labels are stored case-insensitively by default.
@@ -206,6 +220,18 @@ Required parser diagnostics:
 
 Diagnostic messages should include file path, line number, keyword, and offending token.
 
+## Minimum Parser Acceptance
+Before Phase 1 parser work is considered ready for solver integration:
+- Parse `*Node`, `*Element`, `*Nset`, `*Elset`, `*Material`, `*Elastic`, `*Shell Section`, `*Boundary`, `*Cload`, `*Step`, `*Static`, and `*End Step` smoke cases.
+- Preserve original labels for diagnostics while resolving labels case-insensitively.
+- Accept explicit and `GENERATE` node/element sets.
+- Reject `TYPE=S4R` with an unsupported element diagnostic.
+- Reject `NLGEOM=YES`.
+- Reject unsupported Part/Assembly/Instance and Include syntax.
+- Resolve shell section material and element set references.
+- Resolve boundary/load node set references.
+- Produce line-numbered diagnostics for malformed numeric fields and invalid DOF ids.
+
 ## Explicit Non-Goals
 - Abaqus `Part`, `Assembly`, `Instance`, and instance-qualified labels.
 - `*Include`.

docs/ADR.md

@@ -119,3 +119,30 @@
 **이유**: FEM solver는 DOF, 좌표계, 부호, parser subset, result schema, benchmark 기준이 조금만 흔들려도 구현이 불안정해진다. 구현자가 따를 수 있는 technical dossier를 먼저 고정한다.
 
 **트레이드오프**: 문서 유지 비용이 증가한다. 하지만 문서와 구현이 어긋날 때는 ADR 또는 해당 dossier를 먼저 갱신하여 설계 drift를 관리한다.
+
+---
+
+### ADR-014: Documentation Index and Implementation Readiness Gate
+**결정**: `docs/README.md`를 프로젝트 문서 index와 문서 우선순위의 entry point로 둔다. Phase 1 implementation plan을 작성하기 전 `docs/README.md`의 Implementation Readiness Checklist 미결 항목을 명시한다.
+
+**이유**: FESA는 수치 규약, Abaqus subset, MITC4 formulation, HDF5 schema, reference verification이 강하게 결합되어 있다. 구현 전에 어떤 문서가 어느 결정을 소유하는지 분명히 하지 않으면 작은 구현 선택이 전체 solver convention을 흔들 수 있다.
+
+**트레이드오프**: 계획 단계에서 문서 확인 비용이 늘어난다. 대신 이후 Codex 세션과 multi-agent 작업이 같은 규칙을 공유하고, 미결 결정을 숨기지 않는다.
+
+---
+
+### ADR-015: Reference-Artifact-Only Validation Baseline
+**결정**: Phase 1 검증은 저장된 `references/` artifact와 비교한다. Abaqus 실행은 로컬 개발, CI, 기본 validation의 요구사항으로 두지 않는다.
+
+**이유**: 사용자는 Abaqus input과 해석 결과를 `references/` 폴더로 제공하며, 현재 개발 환경에서 Abaqus 실행은 사용할 수 없다. 저장 artifact 기반 검증이 재현성과 자동화에 더 적합하다.
+
+**트레이드오프**: reference artifact 생성과 갱신은 수동 절차에 의존한다. 따라서 reference manifest, Abaqus version, unit note, tolerance, 비교 대상 output path를 명확히 기록해야 한다.
+
+---
+
+### ADR-016: References Folder and CSV Displacement Artifact Contract
+**결정**: 저장 reference의 공식 루트는 `references/`이다. 초기 자동 변위 검증은 Abaqus 해석 입력 `*.inp`와 Abaqus에서 export한 `*_displacements.csv` 파일 쌍을 사용한다. CSV column은 `Node Label`, `U-U1`, `U-U2`, `U-U3`, `UR-UR1`, `UR-UR2`, `UR-UR3`를 기본 형식으로 한다.
+
+**이유**: 사용자가 첫 reference case로 `references/quad_01.inp`와 `references/quad_01_displacements.csv`를 제공했다. CSV는 사람이 검토하기 쉽고, 초기 parser/solver 검증 harness에서 HDF5 writer가 완성되기 전에도 `U` field 비교를 자동화하기 좋다.
+
+**트레이드오프**: CSV는 HDF5보다 metadata 표현력이 약하다. 따라서 Abaqus version, unit note, unsupported keyword note, tolerance는 `references/README.md`, case manifest, 또는 추후 metadata 파일에 보강해야 한다. `quad_01.inp`처럼 `S4R`, `Part/Assembly/Instance`, `NLGEOM=YES`를 포함하는 reference input은 저장 reference로 보존하되 Phase 1 parser 지원 범위를 자동으로 확장하지 않는다.

docs/ARCHITECTURE.md

@@ -5,6 +5,8 @@ FESA는 MITC4 Shell 요소 기반 구조해석에서 시작해 비선형 정적
 
 초기 구현은 정확도와 테스트 가능성을 우선한다. 단, 대규모 모델을 목표로 하므로 자유도 관리, 희소 행렬 조립, 선형 솔버, 병렬 실행 계층은 초기부터 성능 확장이 가능하도록 분리한다.
 
+문서 우선순위와 구현 전 준비 기준은 `docs/README.md`를 따른다.
+
 ## 설계 원칙
 - Domain 객체는 입력 모델의 의미를 보존하고 가능한 한 불변에 가깝게 유지한다.
 - 해석 중 변하는 물리량과 반복 상태는 AnalysisState에 명시적으로 분리한다.
@@ -243,6 +245,18 @@ Abaqus input file
 -> 다음 step 진행
 ```
 
+## Phase 1 실행 경계
+Phase 1 solver path는 다음 경계를 구현 단위로 삼는다.
+
+1. `InputParser`는 `docs/ABAQUS_INPUT_SUBSET.md`의 subset만 받아 `Domain`을 만든다.
+2. `DomainValidator` 또는 동등한 검증 계층은 missing reference, unsupported feature, singular-prone model 상태를 조기에 진단한다.
+3. `AnalysisModelBuilder`는 현재 step의 active element/load/boundary/property/material view를 구성한다.
+4. `DofManager`는 6 DOF node model, constrained/free partition, equation numbering, sparse pattern input, full/reduced vector reconstruction을 소유한다.
+5. `Assembler`는 full reaction recovery에 필요한 full-space stiffness/load 정보를 보존하거나 재구성 가능한 형태로 유지한다.
+6. `LinearStaticAnalysis`는 reduced free-DOF system을 풀고 `AnalysisState`에 full `U`, `Fext`, `Fint`, `R`을 갱신한다.
+7. `ResultsWriter`는 `docs/RESULTS_SCHEMA.md`의 최소 Phase 1 outputs를 쓴다.
+8. `ReferenceComparator` 또는 테스트 harness는 `docs/VERIFICATION_PLAN.md`의 reference artifact와 비교한다. 초기 reference 입력은 `references/*.inp`와 Abaqus-exported `references/*_displacements.csv`이다.
+
 ## Phase 1 구현 범위
 - MITC4 Shell 요소
 - 선형 탄성 재료
@@ -257,7 +271,7 @@ Abaqus input file
 - step/frame 기반 결과 저장의 최소 구조
 - double precision과 int64 indexing
 - singular system 진단
-- reference 모델 결과 비교 테스트
+- `references/`의 Abaqus `.inp`와 `*_displacements.csv` 기반 reference 모델 결과 비교 테스트
 
 ## 성능 확장 방향
 - 행렬 조립은 element 단위 병렬화를 고려해 설계한다.
@@ -268,8 +282,9 @@ Abaqus input file
 - 정확도 검증이 끝나기 전에는 MITC4 element formulation을 과도하게 최적화하지 않는다.
 
 ## 상세 설계 문서
+- `docs/README.md`: 문서 index, 우선순위, Phase 1 hard invariants, implementation readiness checklist
 - `docs/NUMERICAL_CONVENTIONS.md`: DOF, 좌표계, 단위, 부호, precision, reaction recovery, singular diagnostics
 - `docs/ABAQUS_INPUT_SUBSET.md`: Phase 1 Abaqus input keyword subset과 unsupported feature
-- `docs/VERIFICATION_PLAN.md`: reference 폴더 구조, benchmark matrix, tolerance 정책
+- `docs/VERIFICATION_PLAN.md`: `references/` 폴더 구조, benchmark matrix, CSV reference result 형식, tolerance 정책
 - `docs/RESULTS_SCHEMA.md`: HDF5 step/frame/field/history schema
 - `docs/MITC4_FORMULATION.md`: MITC4 baseline formulation 계약과 open decisions

docs/HARNESS_ENGINEERING.md

@@ -0,0 +1,169 @@
+# Harness Engineering
+
+## Purpose
+This document defines how FESA uses long-running agent harnesses for planning, implementation, and evaluation.
+
+The goal is not to maximize agent count. The goal is to keep long solver work coherent, testable, and reference-verified across context resets and independent sessions.
+
+## Default Harness Shape
+Use the smallest harness that can safely handle the task.
+
+For meaningful solver implementation or phase execution, use:
+
+```text
+Planner -> Generator -> Evaluator
+```
+
+Roles:
+- `Planner`: turns project docs and `PLAN.md` tasks into a testable sprint contract or phase step.
+- `Generator`: implements exactly one accepted contract using TDD.
+- `Evaluator`: independently checks the result against the contract, docs, tests, reference artifacts, and validation commands.
+
+Do not use multi-agent ceremony for tiny documentation edits or obvious mechanical changes. Do use the full harness when a task touches solver behavior, numerical conventions, reference comparison, parser compatibility, result schema, or phase execution.
+
+## Sprint Contract
+Every implementation sprint must have a contract before code changes begin.
+
+Recommended location:
+- `phases/{phase}/stepN.md` for phase execution.
+- `phases/{phase}/contracts/stepN-contract.md` only when a separate negotiation artifact is useful.
+
+Required sections:
+
+````markdown
+# Sprint Contract: {name}
+
+## Objective
+{one concise outcome}
+
+## Required Reading
+- /AGENTS.md
+- /PROGRESS.md
+- /PLAN.md
+- /docs/README.md
+- /docs/HARNESS_ENGINEERING.md
+- {topic docs}
+
+## Scope
+- {what may be changed}
+
+## Allowed Files
+- {paths or modules}
+
+## Explicit Non-Goals
+- {what must not be done}
+
+## Tests To Write First
+- {test files or test cases}
+
+## Reference Artifacts
+- {references/*.inp or references/*_displacements.csv, or "none"}
+
+## Acceptance Commands
+```bash
+python scripts/validate_workspace.py
+```
+
+## Evaluator Checklist
+- {contract-specific checks}
+
+## Handoff Requirements
+- Update PROGRESS.md for completed work.
+- Update PLAN.md for future work or changed blockers.
+````
+
+Contract quality rules:
+- The contract must be testable.
+- The contract must identify unsupported Abaqus features rather than expanding support implicitly.
+- The contract must state whether reference data is used.
+- The contract must name file ownership boundaries to reduce conflicts.
+- The contract must not prescribe formulas that are not present in `docs/MITC4_FORMULATION.md` or a cited source.
+
+## Generator Rules
+The Generator implements one contract at a time.
+
+Required behavior:
+- Read the contract and required docs before editing.
+- Write or update tests before implementation.
+- Keep changes inside allowed files unless the contract is updated first.
+- Preserve architecture boundaries from `docs/ARCHITECTURE.md` and `docs/ADR.md`.
+- Preserve numerical conventions from `docs/NUMERICAL_CONVENTIONS.md`.
+- Run acceptance commands.
+- Update `PROGRESS.md` and `PLAN.md` only for factual state changes.
+
+Generator failure modes to avoid:
+- Broad refactors outside the contract.
+- Implementing parser support because a stored reference `.inp` contains unsupported Abaqus features.
+- Comparing only reduced vectors when full-vector reaction recovery is required.
+- Treating a passing compile as sufficient without tests or reference checks.
+
+## Evaluator Rules
+The Evaluator is independent from the Generator.
+
+Evaluation order:
+1. Read the sprint contract.
+2. Read `AGENTS.md`, `PROGRESS.md`, `PLAN.md`, and the topic docs.
+3. Inspect the changed files.
+4. Run or review the acceptance commands.
+5. Check tests, reference artifacts, and documented conventions.
+6. Return pass/fail findings with concrete file references.
+
+The Evaluator must fail the sprint if any of these are true:
+- Required tests were not written first or are missing.
+- `python scripts/validate_workspace.py` fails without explanation.
+- A CRITICAL rule in `AGENTS.md` is violated.
+- A change drifts from `docs/ARCHITECTURE.md`, `docs/ADR.md`, or `docs/NUMERICAL_CONVENTIONS.md`.
+- `references/*_displacements.csv` comparison is required but not implemented or not checked.
+- `RF` is computed from reduced quantities when full-vector recovery is required.
+- Unsupported Abaqus features are silently accepted.
+- Completed work is not recorded in `PROGRESS.md`, or future tasks are not recorded in `PLAN.md`.
+
+If the sprint fails, the Evaluator should produce a concise feedback artifact:
+
+```markdown
+# Evaluation Feedback: {contract}
+
+## Verdict
+fail
+
+## Findings
+- {severity}: {file} - {risk}
+
+## Required Fixes
+- {minimal fix}
+
+## Verification To Rerun
+- {commands}
+```
+
+## FESA Evaluation Rubric
+Use this rubric for implementation review.
+
+| Criterion | Pass Condition |
+|---|---|
+| Contract compliance | Changes stay within scope and allowed files |
+| Architecture | Domain, AnalysisModel, AnalysisState, DofManager, adapters, and factories follow documented ownership |
+| Numerical conventions | DOF order, units, signs, double precision, int64 ids, constrained/free mapping, and full-vector reactions are preserved |
+| Reference verification | Stored `references/` artifacts are used when required; CSV column mapping is correct |
+| Tests | Tests exist before implementation and cover failure modes, not only happy paths |
+| Diagnostics | Unsupported input and singular systems produce actionable diagnostics |
+| Results schema | Outputs follow step/frame/field/history and HDF5 schema rules |
+| Handoff | `PLAN.md` and `PROGRESS.md` reflect the new state |
+
+## Harness Complexity Policy
+Add harness complexity only when it catches real risk.
+
+Use a single agent for:
+- small wording changes.
+- mechanical docs updates.
+- metadata-only corrections.
+
+Use Planner -> Generator -> Evaluator for:
+- C++ solver implementation.
+- parser behavior changes.
+- result schema or HDF5 writer changes.
+- reference comparator changes.
+- MITC4 formulation-dependent work.
+- phase generation or execution.
+
+Review the harness periodically. If an agent role no longer adds value, simplify it.

docs/MITC4_FORMULATION.md

@@ -164,6 +164,17 @@ Before integration with the global solver:
 - bending-dominated sanity case.
 - drilling stiffness sensitivity check.
 
+## Pre-Implementation Gate
+Do not implement `MITC4Element` until these decisions are recorded in this document or a linked ADR:
+- exact transverse shear tying point equations.
+- exact local shell basis algorithm for flat and non-flat quadrilaterals.
+- exact default drilling stiffness scale and parameter name.
+- exact integration point ordering.
+- whether Phase 1 reports only `U` and `RF`, or also element stress/strain/resultant fields.
+- stress/strain recovery locations if `S`, `E`, or `SF` are included in Phase 1.
+
+If implementation starts before all optional stress/resultant decisions are closed, limit Phase 1 mandatory outputs to `U` and `RF`.
+
 ## Reference Benchmarks
 MITC4 baseline acceptance should include:
 - single-element membrane test.
@@ -176,6 +187,15 @@ MITC4 baseline acceptance should include:
 
 Distorted mesh tests should be added after the baseline passes, but Phase 1 does not implement general mesh quality diagnostics.
 
+Current stored reference artifact:
+- `references/quad_01.inp`
+- `references/quad_01_displacements.csv`
+
+Compatibility note:
+- `quad_01.inp` is an Abaqus-generated S4R/NLGEOM reference input and is not a Phase 1 MITC4 parser acceptance case.
+- It should be used as an external reference artifact and future compatibility target unless a normalized Phase 1 `S4` input is added.
+- The displacement CSV can still exercise `U` field comparison infrastructure once node ids and component mapping are supported.
+
 ## Future Extensions
 Geometric nonlinearity:
 - Add updated geometry, current frame handling, tangent stiffness, and Newton-Raphson integration.

docs/MULTI_AGENT_RESEARCH_PLAN.md

@@ -8,10 +8,12 @@ No solver code should be implemented from this plan directly. Each agent should
 ## Project Context
 FESA is a C++17 finite element structural analysis solver. Phase 1 targets a linear static MITC4 shell solver with linear elastic material, nodal loads, fixed boundary conditions, an Abaqus input subset, HDF5-oriented results, and reference-result comparison.
 
-The user will provide Abaqus input files and solved reference result files under a repository `reference/` folder. Abaqus is not available locally, so validation must compare against stored reference artifacts.
+The user provides Abaqus input files and solved reference result files under the repository `references/` folder. Abaqus is not available locally, so validation must compare against stored reference artifacts.
 
 ## Current Architecture Constraints
-- Follow `AGENTS.md`, `docs/ARCHITECTURE.md`, and `docs/ADR.md`.
+- Follow `AGENTS.md`, `PROGRESS.md`, `PLAN.md`, `docs/README.md`, `docs/HARNESS_ENGINEERING.md`, `docs/ARCHITECTURE.md`, and `docs/ADR.md`.
+- Use `PLAN.md` for future task ownership, priority, and open questions.
+- Use `PROGRESS.md` for completed work, verification notes, blockers, and risks.
 - Follow the technical dossier documents:
   - `docs/NUMERICAL_CONVENTIONS.md`
   - `docs/ABAQUS_INPUT_SUBSET.md`
@@ -36,6 +38,7 @@ The user will provide Abaqus input files and solved reference result files under
 - Require singular system diagnostics.
 - Defer mesh quality diagnostics in Phase 1.
 - Map Abaqus `S4` to FESA `MITC4`; defer `S4R`.
+- Use the Planner -> Generator -> Evaluator harness from `docs/HARNESS_ENGINEERING.md` for nontrivial implementation and phase execution.
 
 ## Created Codex Agents
 The first recommended batch has been created under `.codex/agents/`.
@@ -46,7 +49,7 @@ The first recommended batch has been created under `.codex/agents/`.
 
 2. `verification_benchmark_researcher`
    - File: `.codex/agents/verification-benchmark-researcher.toml`
-   - Role: research benchmark cases, reference folder contracts, comparison methods, and acceptance criteria.
+   - Role: research benchmark cases, `references/` contracts, comparison methods, and acceptance criteria.
 
 3. `mitc4_formulation_researcher`
    - File: `.codex/agents/mitc4-formulation-researcher.toml`
@@ -56,6 +59,18 @@ The first recommended batch has been created under `.codex/agents/`.
    - File: `.codex/agents/abaqus-compatibility-researcher.toml`
    - Role: research the Phase 1 Abaqus input subset and parser compatibility rules.
 
+5. `harness_sprint_planner`
+   - File: `.codex/agents/harness-sprint-planner.toml`
+   - Role: convert PLAN.md tasks and phase steps into testable sprint contracts.
+
+6. `implementation_generator`
+   - File: `.codex/agents/implementation-generator.toml`
+   - Role: implement exactly one accepted sprint contract using TDD.
+
+7. `harness_sprint_evaluator`
+   - File: `.codex/agents/harness-sprint-evaluator.toml`
+   - Role: independently pass/fail sprint output against the contract, docs, tests, and reference artifacts.
+
 ## Recommended Agent Execution Order
 1. Run `fem_literature_researcher`.
 2. Run `verification_benchmark_researcher`.
@@ -64,6 +79,8 @@ The first recommended batch has been created under `.codex/agents/`.
 
 This order keeps theory, verification targets, element formulation, and input compatibility aligned before implementation planning.
 
+Before asking `phase_planner` or `harness_sprint_planner` to create implementation steps, review `PROGRESS.md`, `PLAN.md`, `docs/README.md`, and `docs/HARNESS_ENGINEERING.md`; list any unchecked Implementation Readiness Checklist items in the planning output.
+
 ## Later Agent Candidates
 These agents should be created after the first four produce dossiers.
 
@@ -85,16 +102,21 @@ These agents should be created after the first four produce dossiers.
 6. `architecture_guardrail_reviewer`
    - Reviews dossiers, phase plans, and future implementation against project rules and ADRs.
 
+7. `reference_artifact_curator`
+   - Reviews user-provided `references/` artifacts for CSV/manifest completeness, result schema consistency, source solver metadata, tolerance clarity, and comparison path validity.
+
+8. `numerical_conventions_reviewer`
+   - Reviews implementation plans for drift from DOF, unit, sign, precision, reaction recovery, and singular diagnostic rules.
+
 ## User-Provided Inputs Needed
 The following inputs should be requested from the user as the research matures:
 
-1. Confirmation or revision of the proposed `reference/` folder layout in `docs/VERIFICATION_PLAN.md`.
-2. At least one simple Abaqus `.inp` file and its solved reference result artifact.
-3. Preferred reference result format if available: `.dat`, `.rpt`, exported `.csv`, JSON, HDF5, or another structured format.
-4. Preferred numerical tolerances for reference comparison, or permission for agents to propose initial tolerances per benchmark.
-5. The Abaqus version used to generate reference artifacts.
-6. Whether the first implementation plan should target CMake, another build system, or a project-specific build layout.
-7. The final default scale for artificial drilling stiffness, after formulation research.
+1. Additional small Abaqus `.inp` files and solved result artifacts under `references/`.
+2. Reaction-force reference exports when available, preferably using a documented `*_reactions.csv` convention.
+3. Preferred numerical tolerances for reference comparison, or permission for agents to propose initial tolerances per benchmark.
+4. The Abaqus version used to generate each reference artifact when it is not evident from the `.inp` file header.
+5. Whether the first implementation plan should target CMake, another build system, or a project-specific build layout.
+6. The final default scale for artificial drilling stiffness, after formulation research.
 
 ## Seed Sources
 - Abaqus input syntax rules: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-inputsyntax.htm

docs/NUMERICAL_CONVENTIONS.md

@@ -19,7 +19,8 @@ When a convention here conflicts with a lower-level implementation note, this do
 - Result sign conventions follow Abaqus conventions.
 - Essential boundary conditions are applied by constrained DOF elimination.
 - Reaction forces are recovered from the full system vectors, not from the reduced system alone.
-- Reference comparison uses stored Abaqus inputs and stored solved reference results under `reference/`.
+- Reference comparison uses stored Abaqus inputs and stored solved reference results under `references/`.
+- Initial displacement reference comparison uses Abaqus-exported `*_displacements.csv` files.
 - Mesh quality diagnostics are not part of Phase 1.
 - Singular system diagnostics are required.
 - Floating-point values use `double` by default.
@@ -104,6 +105,25 @@ Stress and strain component ordering follows the Abaqus convention:
 
 Shear strain output should be documented as engineering shear strain when matched to Abaqus-style output.
 
+## Abaqus Displacement CSV Mapping
+The initial reference displacement CSV format maps Abaqus exported columns to FESA `U` components:
+
+| CSV Column | FESA Component | Meaning |
+|---|---|---|
+| `Node Label` | `entity_id` | Node id, stored as int64 |
+| `U-U1` | `UX` | Translation in global 1/x direction |
+| `U-U2` | `UY` | Translation in global 2/y direction |
+| `U-U3` | `UZ` | Translation in global 3/z direction |
+| `UR-UR1` | `RX` | Rotation about global 1/x direction, radians |
+| `UR-UR2` | `RY` | Rotation about global 2/y direction, radians |
+| `UR-UR3` | `RZ` | Rotation about global 3/z direction, radians |
+
+Rules:
+- CSV numeric values are parsed as `double`.
+- Node labels are matched to FESA result entity ids exactly.
+- Missing nodes, duplicate node labels, missing columns, or nonnumeric values are reference artifact errors.
+- CSV comparison uses the same absolute/relative tolerance policy as other reference artifacts.
+
 ## Boundary Conditions
 Phase 1 uses constrained DOF elimination:
 
@@ -178,8 +198,17 @@ pass if abs(actual - expected) <= abs_tol
 
 Initial defaults may be proposed per benchmark in `docs/VERIFICATION_PLAN.md`. Final tolerances should be tied to stored reference data and solver maturity.
 
+## Implementation Gate
+Before implementing solver modules that depend on numerical conventions:
+- Define the `Real`, id, equation id, and sparse index aliases in one shared core header.
+- Define a single DOF enum or equivalent mapping for `UX`, `UY`, `UZ`, `RX`, `RY`, `RZ`.
+- Add tests proving Abaqus DOF numbers `1..6` map to the same internal components.
+- Add tests proving constrained/free vector reconstruction preserves original full-space DOF order.
+- Add at least one reaction recovery test that computes `K_full * U_full - F_full`.
+- Ensure singular diagnostics can reference node id, DOF component, element id, property id, and set name.
+
 ## Open Decisions
 - The exact default drilling stiffness scale.
 - The final MITC4 local basis algorithm for warped quadrilateral elements.
 - Which shell stress/strain/resultant outputs are mandatory in Phase 1.
-- The first accepted reference result file format under `reference/`.
+- Optional non-displacement CSV formats, such as reaction force or stress/resultant exports.

docs/PRD.md

@@ -6,12 +6,15 @@ MITC4 Shell 요소를 사용해 구조 해석을 하는 유한요소 솔버를
 ## 사용자
 구조해석을 원하는 엔지니어
 
+## 제품 방향
+FESA는 Abaqus input subset을 읽고 `references/`에 저장된 Abaqus reference 결과와 비교 가능한 구조해석 결과를 생성하는 검증 중심 solver이다. Phase 1은 "많은 기능"보다 "작은 선형 정적 MITC4 모델들을 정확하게 풀고 반복 검증할 수 있는 기반"을 목표로 한다.
+
 ## 핵심 기능
 1. MITC4 Shell 요소를 사용한 구조해석
 2. Parallel 연산을 통한 계산 성능 향상
 3. Abaqus Input format 사용을 통해 다른 상용 소프트웨어와 호환성 높음
 4. step/frame/history 기반 해석 결과 관리
-5. reference 모델 결과 비교를 통한 정확도 검증
+5. `references/*.inp`와 `references/*_displacements.csv` 등 reference 모델 결과 비교를 통한 정확도 검증
 6. singular system 진단을 통한 해석 실패 원인 추적
 
 ## 개발 계획
@@ -23,13 +26,14 @@ MITC4 Shell 요소를 사용해 구조 해석을 하는 유한요소 솔버를
    - Abaqus input subset: *Node, *Element, *Nset, *Elset, *Material, *Elastic, *Shell Section, *Boundary, *Cload, *Step
    - 선형 정적 해석
    - step/frame 기반 결과 저장의 최소 구조
-   - reference 모델 결과 비교 테스트
+   - `references/`의 Abaqus input/result artifact 기반 reference 모델 결과 비교 테스트
    - 6자유도 shell node: UX, UY, UZ, RX, RY, RZ
    - drilling 자유도에는 작은 인공 강성 적용
    - constrained DOF 제거 방식
    - full vector 기반 reaction force 계산
    - double precision 및 int64 id/index/equation numbering
    - singular system 진단
+   - Abaqus 실행 없이 저장된 reference artifact와 비교
 2. Phase 2
    - 압력하중
    - RBE2, RBE3 경계조건
@@ -47,3 +51,23 @@ MITC4 Shell 요소를 사용해 구조 해석을 하는 유한요소 솔버를
 5. Phase 5
    - 1D, 3D 요소 구현
    - 기타 하중, 경계조건 구현
+
+## Phase 1 성공 기준
+- Phase 1 Abaqus input subset을 파싱하여 `Domain`과 `AnalysisModel`을 일관되게 구성할 수 있다.
+- `DofManager`가 6자유도 shell node, constrained/free mapping, full/reduced vector reconstruction을 검증 가능한 방식으로 처리한다.
+- 최소 MITC4 element-level test가 통과한다: shape function, stiffness symmetry, rigid body behavior, drilling stiffness sensitivity.
+- 선형 정적 해석에서 `U`와 `RF`를 결과 schema에 맞게 저장한다.
+- `RF = K_full * U_full - F_full` 기반 reaction recovery가 reference 또는 평형 테스트로 검증된다.
+- singular system negative test가 원인을 설명하는 진단 메시지를 낸다.
+- 최소 3개 stored reference case가 통과한다: single-element case, simple multi-element plate/shell case, curved shell benchmark. 초기 자동 displacement 비교 형식은 `*_displacements.csv`이다.
+
+## Phase 1 제외 범위
+- Abaqus `S4R` 및 hourglass control
+- pressure load
+- RBE2/RBE3
+- nonzero prescribed displacement
+- geometric/material nonlinearity
+- dynamic analysis
+- heat transfer 및 thermal-stress coupling
+- composite shell section
+- mesh quality diagnostics

docs/README.md

@@ -0,0 +1,100 @@
+# 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`.

docs/RESULTS_SCHEMA.md

@@ -187,6 +187,20 @@ component_labels = ["SF1", "SF2", "SF12", "SM1", "SM2", "SM12", "SS13", "SS23"]
 
 The final component labels should be cross-checked with the accepted Abaqus reference output variables.
 
+## Phase 1 Mandatory Outputs
+The first complete linear static solver path must write:
+- root metadata attributes: `schema_name`, `schema_version`, `solver_name`, `dof_convention`, `sign_convention`.
+- `/model/nodes/ids`
+- `/model/nodes/coordinates`
+- `/model/elements/ids`
+- `/model/elements/types`
+- `/model/elements/connectivity`
+- `/results/steps/<step>/frames/0/fieldOutputs/U`
+- `/results/steps/<step>/frames/0/fieldOutputs/RF`
+- frame attributes for `frame_id`, `step_time`, `total_time`, `increment`, `iteration`, and `converged`.
+
+Stress, strain, and section force outputs may remain optional until the MITC4 displacement/reaction benchmarks are stable.
+
 ## Frame Attributes
 Attach these attributes to each frame group:
 
@@ -248,6 +262,40 @@ Attributes:
 - `comparison_status`
 - `comparison_timestamp_utc`
 
+## CSV Reference Input Mapping
+FESA solver outputs remain HDF5-oriented, but early verification may compare HDF5 field outputs against stored Abaqus CSV artifacts under `references/`.
+
+Initial accepted displacement reference naming:
+
+```text
+references/<case_name>.inp
+references/<case_name>_displacements.csv
+```
+
+`*_displacements.csv` maps to:
+
+```text
+/results/steps/<step>/frames/<frame>/fieldOutputs/U
+```
+
+Required CSV columns:
+
+| CSV Column | HDF5 Field Component |
+|---|---|
+| `Node Label` | `entity_ids` |
+| `U-U1` | `UX` |
+| `U-U2` | `UY` |
+| `U-U3` | `UZ` |
+| `UR-UR1` | `RX` |
+| `UR-UR2` | `RY` |
+| `UR-UR3` | `RZ` |
+
+Rules:
+- CSV files are reference inputs for tests, not the primary FESA result storage format.
+- The comparator must preserve node-label matching and must not rely on row order alone.
+- The comparison report may be stored under `/referenceComparison`.
+- Reaction CSV, stress CSV, or section force CSV formats must be documented before automated use.
+
 ## Naming Rules
 - Use stable ASCII group and dataset names.
 - Use original input labels as attributes when names contain spaces or nonportable characters.
@@ -266,3 +314,4 @@ For large models:
 - Exact mandatory stress/strain/resultant output variables in Phase 1.
 - Whether result files always mirror the model or only store output entity ids.
 - Whether reference comparison results are stored in solver output files or separate reports.
+- Exact naming and column contracts for non-displacement Abaqus CSV reference files.

docs/VERIFICATION_PLAN.md

@@ -19,7 +19,7 @@ FESA verification uses multiple layers:
 3. Assembly tests for small known systems.
 4. Solver tests for constrained/reduced systems and reaction recovery.
 5. Input-to-result integration tests using Abaqus-style `.inp` files.
-6. Reference comparisons against stored Abaqus result artifacts under `reference/`.
+6. Reference comparisons against stored Abaqus result artifacts under `references/`.
 
 A single large benchmark is not enough. Phase 1 should use many small models that isolate failure causes.
 
@@ -29,31 +29,56 @@ Abaqus is not available locally and must not be required by CI.
 Rules:
 - The user provides `.inp` files and solved reference result artifacts.
 - FESA tests compare against stored artifacts only.
-- Reference artifacts are treated as the numerical source of truth once accepted into `reference/`.
+- Reference artifacts are treated as the numerical source of truth once accepted into `references/`.
 
-## Proposed Reference Folder Contract
-Recommended layout:
+## Accepted Reference Folder Contract
+The repository uses `references/` as the durable root for stored Abaqus inputs and solved output artifacts.
+
+Initial flat-file convention:
 
 ```text
-reference/
+references/
+  README.md
+  <case_name>.inp
+  <case_name>_displacements.csv
+```
+
+Accepted initial case:
+
+```text
+references/
+  quad_01.inp
+  quad_01_displacements.csv
+```
+
+`quad_01_displacements.csv` contains 121 nodal rows with these columns:
+
+```text
+Node Label, U-U1, U-U2, U-U3, UR-UR1, UR-UR2, UR-UR3
+```
+
+Future manifest-driven layout is still recommended as the case set grows:
+
+```text
+references/
   README.md
   phase1-linear-static/
     manifest.json
     single-element-membrane/
       model.inp
-      expected.json
+      displacements.csv
       notes.md
     single-element-bending/
       model.inp
-      expected.json
+      displacements.csv
       notes.md
     cantilever-strip/
       model.inp
-      expected.json
+      displacements.csv
       notes.md
     scordelis-lo-roof/
       model.inp
-      expected.json
+      displacements.csv
       notes.md
 ```
 
@@ -66,47 +91,76 @@ reference/
     {
       "name": "single-element-membrane",
       "input": "single-element-membrane/model.inp",
-      "expected": "single-element-membrane/expected.json",
+      "displacements": "single-element-membrane/displacements.csv",
       "analysis_type": "linear_static",
       "element": "MITC4",
       "source_solver": "Abaqus",
       "source_solver_version": "provided-by-user",
       "unit_system_note": "self-consistent",
+      "result_format": "abaqus_displacement_csv_v1",
       "tags": ["phase1", "element", "membrane"]
     }
   ]
 }
 ```
 
-## Expected Result Artifact
-Preferred `expected.json` structure:
+## Displacement CSV Artifact
+Initial automated displacement comparison uses Abaqus-exported CSV files named:
 
-```json
-{
-  "schema_version": 1,
-  "case_name": "single-element-membrane",
-  "source": {
-    "solver": "Abaqus",
-    "version": "provided-by-user",
-    "created_by": "provided-by-user"
-  },
-  "units": {
-    "note": "self-consistent"
-  },
-  "comparisons": [
-    {
-      "path": "/results/steps/Step-1/frames/0/fieldOutputs/U",
-      "entity": {"type": "node", "id": 4},
-      "component": "UX",
-      "expected": 0.0,
-      "abs_tol": 1e-9,
-      "rel_tol": 1e-7
-    }
-  ]
-}
+```text
+<case_name>_displacements.csv
 ```
 
-CSV or `.rpt` files may be stored as raw source artifacts, but structured JSON or HDF5 comparison artifacts should be used by automated tests.
+Required columns:
+
+| CSV Column | FESA Field | Component |
+|---|---|---|
+| `Node Label` | `U` | entity id |
+| `U-U1` | `U` | `UX` |
+| `U-U2` | `U` | `UY` |
+| `U-U3` | `U` | `UZ` |
+| `UR-UR1` | `U` | `RX` |
+| `UR-UR2` | `U` | `RY` |
+| `UR-UR3` | `U` | `RZ` |
+
+Rules:
+- Column matching is by exact normalized header text after trimming whitespace.
+- `Node Label` is parsed as int64.
+- All displacement and rotation values are parsed as `double`.
+- The comparator must match rows by node id, not by row order alone.
+- Missing nodes in FESA output, duplicate CSV node labels, missing columns, or nonnumeric values are reference artifact errors.
+- CSV displacement comparison maps to `/results/steps/<step>/frames/<frame>/fieldOutputs/U`.
+- If the `.inp` has multiple steps or frames, the case metadata must state which step/frame the CSV represents.
+
+Structured JSON or HDF5 comparison artifacts may be added later, but `*_displacements.csv` is the accepted first automated reference format.
+
+## Other Result Artifacts
+Additional Abaqus result exports may be added as the solver grows. Recommended naming:
+
+| File Pattern | Purpose | Status |
+|---|---|---|
+| `*_displacements.csv` | Nodal `U` displacement/rotation comparison | Accepted initial format |
+| `*_reactions.csv` | Nodal `RF` force/moment comparison | Recommended future format |
+| `*_stresses.csv` | Stress output comparison | Future, after `S` output is documented |
+| `*_strains.csv` | Strain output comparison | Future, after `E` output is documented |
+| `*_section_forces.csv` | Shell resultant comparison | Future, after `SF` output is documented |
+
+Each new CSV type must define required columns, component mapping, position, basis, and tolerances before automated use.
+
+## Stored Reference Compatibility Notes
+Stored Abaqus `.inp` files are preserved as generated, even when they include features outside the current FESA parser subset. This preserves provenance but does not expand Phase 1 support.
+
+Current initial case:
+
+| Case | Files | Notes |
+|---|---|---|
+| `quad_01` | `quad_01.inp`, `quad_01_displacements.csv` | Abaqus/CAE Learning Edition 2024 input; 121 displacement rows; includes `S4R`, `Part/Assembly/Instance`, `*Density`, and `NLGEOM=YES`, which are outside the current Phase 1 parser/solver subset |
+
+Rules:
+- Original `.inp` files under `references/` should not be modified just to fit FESA Phase 1.
+- If a normalized Phase 1-compatible input is needed, add it as a separate file with a clear name and note its relationship to the original.
+- Unsupported features in stored reference inputs must be reported by compatibility checks, not silently accepted by parser tests.
+- A reference case may be useful for future compatibility even before it is executable by the current Phase 1 solver.
 
 ## Tolerance Policy
 Use absolute and relative tolerance:
@@ -122,7 +176,7 @@ Initial guidance:
 - DOF mapping tests: exact integer match.
 - Small linear algebra tests: `abs_tol = 1e-12`, `rel_tol = 1e-10`.
 - Element stiffness symmetry: matrix norm tolerance around `1e-10` to `1e-9`, adjusted by stiffness scale.
-- Reference displacement tests: start with `rel_tol = 1e-5` and refine after baseline agreement.
+- Reference displacement CSV tests: start with `rel_tol = 1e-5` and refine after baseline agreement.
 - Reaction equilibrium tests: use force-scale-based tolerances.
 
 Final benchmark tolerances must be stored with each reference case.
@@ -151,6 +205,20 @@ Before MITC4 Phase 1 is considered credible:
 - MITC4 element stiffness is symmetric within tolerance for linear elastic Phase 1.
 - Rigid body modes do not create artificial membrane/bending stiffness beyond documented drilling stabilization effects.
 - At least three stored Abaqus reference models pass: one single-element case, one simple multi-element plate/shell case, and one curved shell benchmark.
+- At least one automated `*_displacements.csv` comparison passes against a stored Abaqus reference case.
+
+## Reference Onboarding Checklist
+Every accepted reference case should include:
+- an Abaqus `.inp` file.
+- at least one solved result artifact, initially `*_displacements.csv`.
+- raw Abaqus output when available, such as `.dat`, `.rpt`, `.csv`, or exported table files.
+- `notes.md` describing model purpose, unit system note, Abaqus version, expected dominant behavior, and known limitations.
+- comparison paths matching `docs/RESULTS_SCHEMA.md`.
+- absolute and relative tolerances for each compared quantity.
+- tags that identify phase, feature, benchmark family, and expected failure mode if negative.
+- compatibility notes for unsupported Abaqus keywords or analysis options.
+
+Reference artifacts should not be overwritten silently. If reference values change, record why they changed in `notes.md` or the manifest.
 
 ## Singular System Verification
 Required negative tests:
@@ -169,8 +237,8 @@ Required negative tests:
 - Thermal-stress coupling.
 
 ## User Inputs Needed
-- First accepted `reference/` folder layout.
-- At least one Abaqus `.inp` with solved displacement and reaction output.
-- Preferred raw reference format: `.dat`, `.rpt`, `.csv`, `.json`, or `.h5`.
-- Abaqus version used to generate the reference.
-- Whether reference files are generated from Abaqus `S4` only for Phase 1.
+- Additional small Abaqus `.inp` files and solved result CSV files under `references/`.
+- Reaction output artifacts when available, preferably a documented `*_reactions.csv`.
+- Abaqus version used to generate each reference when it is not evident from the `.inp`.
+- Unit system notes and tolerances for each case.
+- Whether future Phase 1-compatible reference files will use Abaqus `S4`, while `S4R` remains deferred.