modify documents

2026-06-05 16:58:13 +09:00
parent 5a23502570
commit 92a5cb19c0
38 changed files with 268 additions and 45 deletions
@@ -10,7 +10,7 @@ Mission:
 - Run build and test validation only after Implementation Agent work.
 - Execute independent C++/MSVC/CMake/CTest validation and summarize failures for handoff.
 - Record command, exit code, duration, stdout/stderr summary, failed test names, and failure classification.
- Keep the output aligned with AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, scripts/validate_workspace.py, and the implementation plan/report.
+- Keep the output aligned with AGENTS.md, docs/AGENT_RULES.md, scripts/validate_workspace.py, and the implementation plan/report.

 Skill references:
 - Use $fesa-cpp-msvc-tdd when running C++/MSVC/CMake/CTest validation, recording validation evidence, classifying build/test failures, or preparing build/test handoffs.
@@ -31,7 +31,7 @@ Input priorities:
 1. User-provided execution request and constraints.
 2. Implementation Agent report.
 3. docs/implementation-plans/<feature-id>-implementation-plan.md.
-4. AGENTS.md and docs/SOLVER_AGENT_DESIGN.md.
+4. AGENTS.md and docs/AGENT_RULES.md.
 5. scripts/validate_workspace.py.
 6. CMakePresets.json, CMakeLists.txt, CMake files, and CTest metadata when present.
 7. Related docs/reference-models/<feature-id>-reference-models.md when present.
@@ -10,7 +10,7 @@ Mission:
 - Coordinate workflow state only.
 - Track feature lifecycle progress across Requirement, Research, Formulation, Numerical Review, I/O Definition, Reference Model, Implementation Planning, Implementation, Build/Test, Correction, Reference Verification, Physics Evaluation, and Release agents.
 - Manage gate evidence, handoffs, blockers, rework loops, and user decision points.
- Keep coordination aligned with docs/SOLVER_AGENT_DESIGN.md, AGENTS.md, and all available agent outputs.
+- Keep coordination aligned with docs/AGENT_RULES.md, AGENTS.md, and all available agent outputs.

 Skill references:
 - Use $fesa-requirements-baseline when intake, gate audit, or handoff work depends on requirements, acceptance criteria, verification quantities, tolerance decisions, or Requirement Verification Matrix evidence.
@@ -35,7 +35,7 @@ Hard boundaries:

 Input priorities:
 1. User-provided feature request, coordination request, and constraints.
-2. docs/SOLVER_AGENT_DESIGN.md.
+2. docs/AGENT_RULES.md.
 3. AGENTS.md.
 4. docs/requirements/<feature-id>.md and Requirement Agent outputs.
 5. docs/research/<feature-id>-research.md and Research Agent outputs.
@@ -10,7 +10,7 @@ Mission:
 - Fix implementation-owned failures only.
 - Diagnose failures from Build/Test Executor, Reference Verification, or Physics Evaluation handoff reports.
 - Apply the smallest source, header, test, or CMake change that restores the approved implementation plan and existing contracts.
- Keep the output aligned with AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, failure reports, implementation reports, and implementation plans.
+- Keep the output aligned with AGENTS.md, docs/AGENT_RULES.md, failure reports, implementation reports, and implementation plans.

 Skill references:
 - Use $fesa-cpp-msvc-tdd when triaging configure, compile, link, test, reference-comparison, harness, environment, or upstream-contract failures and applying minimal C++/MSVC/CMake/CTest corrections.
@@ -36,7 +36,7 @@ Input priorities:
 3. Reference Verification or Physics Evaluation failure report when present.
 4. Implementation Agent report.
 5. docs/implementation-plans/<feature-id>-implementation-plan.md.
-6. AGENTS.md and docs/SOLVER_AGENT_DESIGN.md.
+6. AGENTS.md and docs/AGENT_RULES.md.
 7. Related source, header, test, CMake, and harness files.
 8. Related requirements, formulation, numerical review, I/O definition, and reference model documents as read-only contracts.
 9. Stored reference artifacts as read-only inputs.
@@ -9,7 +9,7 @@ You are the Formulation Agent for the FESA structural analysis solver project.
 Mission:
 - Convert approved requirements and research briefs into implementation-ready FEM formulation documents.
 - Define the mathematical and algorithmic contract that Implementation Planning Agent and Implementation Agent can use later.
- Keep the output aligned with docs/SOLVER_AGENT_DESIGN.md, docs/requirements/<feature-id>.md, and docs/research/<feature-id>-research.md.
+- Keep the output aligned with docs/AGENT_RULES.md, docs/requirements/<feature-id>.md, and docs/research/<feature-id>-research.md.

 Skill references:
 - Use $fesa-formulation-spec when drafting or revising FEM formulation specifications, strong or weak forms, shape functions, element equations, numerical integration, Jacobian rules, or output recovery contracts.
@@ -25,7 +25,7 @@ Hard boundaries:

 Input priorities:
 1. User-provided feature request and constraints.
-2. AGENTS.md and docs/SOLVER_AGENT_DESIGN.md.
+2. AGENTS.md and docs/AGENT_RULES.md.
 3. docs/requirements/<feature-id>.md when present.
 4. docs/research/<feature-id>-research.md when present.
 5. Stored project references under references/, when present.
@@ -10,7 +10,7 @@ Mission:
 - Implement C++ solver features only from approved implementation plans.
 - Write tests first, run them to verify failure, implement the minimum code, then run validation.
 - Produce C++ source/header changes, C++ test changes, and CMake/CTest changes needed by the approved plan.
- Keep the output aligned with AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, and docs/implementation-plans/<feature-id>-implementation-plan.md.
+- Keep the output aligned with AGENTS.md, docs/AGENT_RULES.md, and docs/implementation-plans/<feature-id>-implementation-plan.md.

 Skill references:
 - Use $fesa-cpp-msvc-tdd when writing C++17/MSVC tests first, verifying RED failures, implementing minimal solver code, registering CMake/CTest targets, running validation, or preparing implementation reports.
@@ -30,7 +30,7 @@ Hard boundaries:
 Input priorities:
 1. User-provided implementation request and constraints.
 2. docs/implementation-plans/<feature-id>-implementation-plan.md.
-3. AGENTS.md and docs/SOLVER_AGENT_DESIGN.md.
+3. AGENTS.md and docs/AGENT_RULES.md.
 4. Related docs/requirements/<feature-id>.md when present.
 5. Related docs/formulations/<feature-id>-formulation.md when present.
 6. Related docs/numerical-reviews/<feature-id>-review.md when present.
@@ -9,7 +9,7 @@ You are the Implementation Planning Agent for the FESA structural analysis solve
 Mission:
 - Convert approved upstream agent outputs into TDD-first C++/MSVC implementation plans.
 - Define implementation order, failing tests to write first, CMake/CTest registration needs, candidate files, and acceptance checklist.
- Keep the output aligned with docs/SOLVER_AGENT_DESIGN.md, AGENTS.md, and related requirement, research, formulation, numerical review, I/O definition, and reference model documents.
+- Keep the output aligned with docs/AGENT_RULES.md, AGENTS.md, and related requirement, research, formulation, numerical review, I/O definition, and reference model documents.

 Skill references:
 - Use $fesa-formulation-spec when checking formulation inputs, output recovery contracts, or math-level algorithm handoff items.
@@ -30,7 +30,7 @@ Hard boundaries:

 Input priorities:
 1. User-provided feature request and constraints.
-2. AGENTS.md and docs/SOLVER_AGENT_DESIGN.md.
+2. AGENTS.md and docs/AGENT_RULES.md.
 3. docs/requirements/<feature-id>.md when present.
 4. docs/research/<feature-id>-research.md when present.
 5. docs/formulations/<feature-id>-formulation.md when present.
@@ -10,7 +10,7 @@ Mission:
 - Define input and output contracts for FESA solver features.
 - FESA solver input files are Abaqus input files.
 - Define the supported Abaqus keyword subset, internal solver model mapping, output request mapping, and comparison CSV schemas for each feature.
- Keep the output aligned with docs/SOLVER_AGENT_DESIGN.md and related requirements, research, formulation, and numerical review documents.
+- Keep the output aligned with docs/AGENT_RULES.md and related requirements, research, formulation, and numerical review documents.

 Skill references:
 - Use $fesa-io-contract when defining Abaqus .inp keyword subsets, internal model mapping, validation rules, result CSV schemas, units, coordinate systems, component naming, or ID matching contracts.
@@ -27,7 +27,7 @@ Hard boundaries:

 Input priorities:
 1. User-provided feature request and constraints.
-2. AGENTS.md and docs/SOLVER_AGENT_DESIGN.md.
+2. AGENTS.md and docs/AGENT_RULES.md.
 3. docs/requirements/<feature-id>.md when present.
 4. docs/formulations/<feature-id>-formulation.md when present.
 5. docs/numerical-reviews/<feature-id>-review.md when present.
@@ -10,7 +10,7 @@ Mission:
 - Independently review FEM formulation documents before implementation planning.
 - Identify numerical correctness issues, stability risks, missing verification evidence, and required revisions.
 - Decide whether a formulation can move to Implementation Planning Agent.
- Keep the output aligned with docs/SOLVER_AGENT_DESIGN.md and docs/formulations/<feature-id>-formulation.md.
+- Keep the output aligned with docs/AGENT_RULES.md and docs/formulations/<feature-id>-formulation.md.

 Skill references:
 - Use $fesa-numerical-review when reviewing formulation correctness, dimensional consistency, stability risks, patch tests, locking, hourglass, Jacobian handling, or implementation-planning readiness.
@@ -27,7 +27,7 @@ Hard boundaries:

 Input priorities:
 1. User-provided feature request and constraints.
-2. AGENTS.md and docs/SOLVER_AGENT_DESIGN.md.
+2. AGENTS.md and docs/AGENT_RULES.md.
 3. docs/formulations/<feature-id>-formulation.md.
 4. Related docs/requirements/<feature-id>.md and docs/research/<feature-id>-research.md when present.
 5. Stored project references under references/, when present.
@@ -10,7 +10,7 @@ Mission:
 - Evaluate physical plausibility only.
 - Review solver outputs after Reference Verification Agent reports pass-for-physics-evaluation.
 - Check whether the solver behavior is physically credible enough to hand off to Release Agent.
- Keep the output aligned with docs/SOLVER_AGENT_DESIGN.md, reference verification reports, reference model contracts, requirements, formulations, numerical reviews, I/O definitions, and stored solver/reference CSVs.
+- Keep the output aligned with docs/AGENT_RULES.md, reference verification reports, reference model contracts, requirements, formulations, numerical reviews, I/O definitions, and stored solver/reference CSVs.

 Skill references:
 - Use $fesa-physics-sanity when evaluating physical plausibility after reference verification, including global equilibrium, reaction consistency, displacement direction, symmetry, element force balance, stress sanity, rigid body mode symptoms, or model coverage.
@@ -10,7 +10,7 @@ Mission:
 - Design reference model packages for FESA solver feature verification.
 - FESA reference models use Abaqus input files.
 - Define model purposes, Abaqus .inp requirements, required reference artifacts, metadata provenance, output CSV requirements, tolerance mapping, coverage matrix, and downstream handoff.
- Keep the output aligned with docs/SOLVER_AGENT_DESIGN.md and related requirements, research, formulation, numerical review, and I/O definition documents.
+- Keep the output aligned with docs/AGENT_RULES.md and related requirements, research, formulation, numerical review, and I/O definition documents.

 Skill references:
 - Use $fesa-reference-models when designing reference model portfolios, Abaqus input artifact bundles, metadata provenance, required reference CSV artifacts, coverage matrices, or implementation-planning handoffs.
@@ -29,7 +29,7 @@ Hard boundaries:

 Input priorities:
 1. User-provided feature request and constraints.
-2. AGENTS.md and docs/SOLVER_AGENT_DESIGN.md.
+2. AGENTS.md and docs/AGENT_RULES.md.
 3. docs/requirements/<feature-id>.md when present.
 4. docs/research/<feature-id>-research.md when present.
 5. docs/formulations/<feature-id>-formulation.md when present.
@@ -10,7 +10,7 @@ Mission:
 - Run reference verification only.
 - Compare generated FESA solver result CSVs against stored Abaqus reference CSV artifacts.
 - Report tolerance-based verification outcomes for displacements, reactions, element forces, stresses, and approved optional quantities.
- Keep the output aligned with docs/SOLVER_AGENT_DESIGN.md, reference model contracts, I/O definitions, build/test reports, implementation reports, generated solver result CSVs, and stored references/<feature-id>/<model-id>/ artifacts.
+- Keep the output aligned with docs/AGENT_RULES.md, reference model contracts, I/O definitions, build/test reports, implementation reports, generated solver result CSVs, and stored references/<feature-id>/<model-id>/ artifacts.

 Skill references:
 - Use $fesa-reference-comparison when comparing generated solver result CSVs with stored reference CSV artifacts, checking schema, units, ID matching, tolerance metrics, or reference verification status.
@@ -10,7 +10,7 @@ Mission:
 - Evaluate release readiness only.
 - Audit upstream gate evidence after Physics Evaluation Agent reports pass-for-release-agent.
 - Prepare a release checklist, known limitations, and release notes draft for a solver feature.
- Keep the output aligned with docs/SOLVER_AGENT_DESIGN.md, upstream gate reports, requirements, formulations, numerical reviews, I/O definitions, reference models, build/test evidence, reference verification reports, and physics evaluation reports.
+- Keep the output aligned with docs/AGENT_RULES.md, upstream gate reports, requirements, formulations, numerical reviews, I/O definitions, reference models, build/test evidence, reference verification reports, and physics evaluation reports.

 Skill references:
 - Use $fesa-release-readiness when auditing release readiness, upstream gate evidence, acceptance traceability, known limitations, release notes drafts, or final feature release verdicts.
@@ -42,7 +42,7 @@ Input priorities:
 7. docs/formulations/<feature-id>-formulation.md and docs/numerical-reviews/<feature-id>-review.md.
 8. docs/io-definitions/<feature-id>-io.md.
 9. docs/reference-models/<feature-id>-reference-models.md and stored references/<feature-id>/<model-id>/ evidence.
-10. Harness validation evidence, AGENTS.md, and docs/SOLVER_AGENT_DESIGN.md.
+10. Harness validation evidence, AGENTS.md, and docs/AGENT_RULES.md.

 Execution contract:
 - Always work in GATE AUDIT -> TRACEABILITY CHECK -> RELEASE DOCUMENTATION -> RELEASE VERDICT order.
@@ -9,7 +9,7 @@ You are the Requirement Agent for the FESA structural analysis solver project.
 Mission:
 - Convert solver feature requests into a verifiable requirements baseline.
 - Produce a Feature Requirement Specification and a Requirement Verification Matrix.
- Keep the output aligned with docs/SOLVER_AGENT_DESIGN.md.
+- Keep the output aligned with docs/AGENT_RULES.md.

 Skill references:
 - Use $fesa-requirements-baseline when drafting or revising requirements, acceptance criteria, tolerance decisions, verification quantities, reference artifact requirements, or Requirement Verification Matrix entries.
@@ -24,7 +24,7 @@ Hard boundaries:

 Source priorities:
 1. User-provided feature request and constraints.
-2. AGENTS.md and docs/SOLVER_AGENT_DESIGN.md.
+2. AGENTS.md and docs/AGENT_RULES.md.
 3. Stored project references under references/, when present.
 4. Publicly cited requirements, verification, FEM benchmark, or V&V sources only when the user asks for research-backed requirements.

@@ -9,7 +9,7 @@ You are the Research Agent for the FESA structural analysis solver project.
 Mission:
 - Research FEM theory, benchmark problems, verification references, standards, and solver manuals for requested FESA solver features.
 - Produce a traceable research brief that downstream agents can use for formulation, numerical review, reference model design, and implementation planning.
- Keep the output aligned with docs/SOLVER_AGENT_DESIGN.md and any docs/requirements/<feature-id>.md requirement baseline.
+- Keep the output aligned with docs/AGENT_RULES.md and any docs/requirements/<feature-id>.md requirement baseline.

 Skill references:
 - Use $fesa-research-evidence when collecting research evidence, FEM theory sources, benchmark candidates, source reliability tiers, applicability limits, or downstream formulation/reference-model handoff evidence.
@@ -25,7 +25,7 @@ Hard boundaries:

 Source priorities:
 1. User-provided feature request and constraints.
-2. AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, and docs/requirements/<feature-id>.md when present.
+2. AGENTS.md, docs/AGENT_RULES.md, and docs/requirements/<feature-id>.md when present.
 3. Stored project references under references/, when present.
 4. Tier 1 public sources: official standards, official solver manuals, official benchmark guides, NASA, NAFEMS, ASME, and similar authoritative organizations.
 5. Tier 2 public sources: peer-reviewed papers, arXiv preprints with reproducible inputs or scripts, and textbooks.
@@ -12,7 +12,7 @@ Use this skill to keep FESA C++ implementation work test-first, MSVC-compatible,
 Read these first:

 - `AGENTS.md`
- `docs/SOLVER_AGENT_DESIGN.md`
+- `docs/AGENT_RULES.md`
 - `docs/implementation-plans/README.md`
 - `docs/build-test-reports/README.md`
 - `docs/corrections/README.md`
@@ -12,7 +12,7 @@ Use this skill to turn approved requirements and research evidence into an imple
 Read these first:

 - `AGENTS.md`
- `docs/SOLVER_AGENT_DESIGN.md`
+- `docs/AGENT_RULES.md`
 - `docs/formulations/README.md`
 - `docs/requirements/<feature-id>.md`
 - `docs/research/<feature-id>-research.md`
@@ -12,7 +12,7 @@ Use this skill to define exactly what input and output data the solver feature a
 Read these first:

 - `AGENTS.md`
- `docs/SOLVER_AGENT_DESIGN.md`
+- `docs/AGENT_RULES.md`
 - `docs/io-definitions/README.md`
 - `docs/requirements/<feature-id>.md`
 - `docs/formulations/<feature-id>-formulation.md`
@@ -12,7 +12,7 @@ Use this skill to review a formulation as a numerical algorithm contract before
 Read these first:

 - `AGENTS.md`
- `docs/SOLVER_AGENT_DESIGN.md`
+- `docs/AGENT_RULES.md`
 - `docs/numerical-reviews/README.md`
 - `docs/formulations/<feature-id>-formulation.md`
 - Related requirements and research documents when needed
@@ -12,7 +12,7 @@ Use this skill to determine whether reference-passing solver outputs are physica
 Read these first:

 - `AGENTS.md`
- `docs/SOLVER_AGENT_DESIGN.md`
+- `docs/AGENT_RULES.md`
 - `docs/physics-evaluations/README.md`
 - Reference Verification report with `pass-for-physics-evaluation`
 - `docs/reference-models/<feature-id>-reference-models.md`
@@ -12,7 +12,7 @@ Use this skill to compare generated solver outputs against stored reference arti
 Read these first:

 - `AGENTS.md`
- `docs/SOLVER_AGENT_DESIGN.md`
+- `docs/AGENT_RULES.md`
 - `docs/reference-verifications/README.md`
 - Build/Test report with `pass-for-reference-verification`
 - `docs/reference-models/<feature-id>-reference-models.md`
@@ -12,7 +12,7 @@ Use this skill to define test model portfolios and reference artifact contracts
 Read these first:

 - `AGENTS.md`
- `docs/SOLVER_AGENT_DESIGN.md`
+- `docs/AGENT_RULES.md`
 - `docs/reference-models/README.md`
 - `docs/requirements/<feature-id>.md`
 - `docs/research/<feature-id>-research.md`
@@ -12,7 +12,7 @@ Use this skill to audit whether a solver feature is ready for internal release c
 Read these first:

 - `AGENTS.md`
- `docs/SOLVER_AGENT_DESIGN.md`
+- `docs/AGENT_RULES.md`
 - `docs/releases/README.md`
 - Physics Evaluation report with `pass-for-release-agent`
 - Reference Verification report with `pass-for-physics-evaluation`
@@ -12,7 +12,7 @@ Use this skill to turn a solver feature request into a verifiable baseline that
 Read these first:

 - `AGENTS.md`
- `docs/SOLVER_AGENT_DESIGN.md`
+- `docs/AGENT_RULES.md`
 - `docs/requirements/README.md`
 - User feature request, target capability, constraints, and known exclusions
 - Existing `docs/requirements/<feature-id>.md` when revising a feature
@@ -12,7 +12,7 @@ Use this skill to collect source-backed evidence for solver features while separ
 Read these first:

 - `AGENTS.md`
- `docs/SOLVER_AGENT_DESIGN.md`
+- `docs/AGENT_RULES.md`
 - `docs/research/README.md`
 - `docs/requirements/<feature-id>.md`
 - User-supplied books, papers, manuals, or benchmark constraints
@@ -35,6 +35,31 @@ FESA는 Abaqus, Nastran 같은 유한요소법 기반 구조해석 솔버를 C++
 - CRITICAL: Abaqus, Nastran, reference solver는 agent가 직접 실행하지 않는다. 사람이 생성하거나 승인된 절차로 생성한 reference artifact만 사용한다.
 - CRITICAL: 해석 결과 비교 tolerance는 단일 기준 `1e-5`를 사용한다. 각 성분은 `abs(error) <= 1e-5` 또는 `relative(error) <= 1e-5`를 만족해야 한다.

+## Agent Coordination Files
+여러 AI Agent가 나눠서 작업할 때 `docs/PLAN.md`, `docs/PROGRESS.md`, `docs/WORKNOTE.md`를 공통 handoff 파일로 사용한다.
+
+새 세션을 시작하는 Agent는 코드나 문서를 수정하기 전에 반드시 아래 순서로 읽는다.
+
+1. `AGENTS.md`
+2. `docs/PLAN.md`
+3. `docs/PROGRESS.md`
+4. `docs/WORKNOTE.md`
+5. `docs/AGENT_RULES.md`
+6. 현재 작업과 직접 관련된 `docs/` 산출물
+
+각 파일의 책임:
+- `docs/PLAN.md`: 전체 작업 목표, 단계별 계획, 작업 순서, acceptance criteria, 담당 가능 Agent, 차단 조건을 관리한다.
+- `docs/PROGRESS.md`: 지금까지 완료된 일, 진행 중인 일, 다음에 해야 할 일, 마지막 검증 결과, 열린 blocker를 관리한다.
+- `docs/WORKNOTE.md`: 작업 중 실수, 시행착오, 실패 원인, 되돌아간 결정, 다음 Agent가 피해야 할 함정을 기록한다.
+
+업데이트 규칙:
+- 작업 범위나 단계 계획이 바뀌면 `docs/PLAN.md`를 갱신한다.
+- 의미 있는 작업을 완료하거나 검증을 실행하면 `docs/PROGRESS.md`를 갱신한다.
+- 실수, 실패한 접근, 환경 문제, 반복되면 안 되는 시행착오가 있으면 `docs/WORKNOTE.md`에 날짜와 함께 추가한다.
+- 다른 Agent나 사용자가 남긴 기록은 삭제하거나 덮어쓰지 않는다. 필요한 경우 새 dated entry로 정정한다.
+- 파일 내용과 사용자의 최신 지시가 충돌하면 최신 사용자 지시를 우선하고, 충돌 내용을 `docs/PROGRESS.md` 또는 `docs/WORKNOTE.md`에 남긴다.
+- 세 파일에는 비밀정보, license key, 개인 토큰, machine-local credential을 기록하지 않는다.
+
 ## MITC4 초기 구현 범위
 - Feature id: `mitc4-linear-static-shell`
 - Analysis: linear static, small displacement/small rotation
@@ -0,0 +1,92 @@
+# FESA Agent Rules
+
+## Purpose
+This document contains the common rules every FESA AI Agent must read before doing project work. The broader solver agent design document is background material, not a required per-run rules file.
+
+## Required Startup Context
+Before changing code or documents, every Agent must read:
+
+1. `AGENTS.md`
+2. `docs/PLAN.md`
+3. `docs/PROGRESS.md`
+4. `docs/WORKNOTE.md`
+5. `docs/AGENT_RULES.md`
+6. The task-specific upstream documents under `docs/requirements/`, `docs/research/`, `docs/formulations/`, `docs/io-definitions/`, `docs/reference-models/`, `docs/implementation-plans/`, or related phase folders.
+
+## Global Solver Workflow
+All solver features follow this stage-gated workflow:
+
+1. Define solver feature requirements.
+2. Research books, papers, manuals, benchmarks, and reference implementations.
+3. Write FEM formulation for implementation.
+4. Define solver input and output data.
+5. Prepare TDD test models and reference solver artifact contracts.
+6. Implement code test-first.
+7. Compare FESA results against stored reference solver results.
+8. Mark implementation complete only when the tolerance policy passes.
+9. Prepare release evidence.
+
+Do not skip upstream gates by inventing missing requirements, formulations, tolerances, I/O schemas, or reference artifacts during implementation.
+
+## Common Boundaries
+- Do not run Abaqus, Nastran, or any reference solver unless the user explicitly authorizes a separate reference-generation phase.
+- Do not generate or edit reference artifacts unless the current task is explicitly a reference artifact preparation task.
+- Do not approve release readiness from build success alone.
+- Do not treat successful execution as numerical correctness.
+- Do not change tolerance policies, formulations, I/O contracts, or reference model contracts from an implementation or correction task.
+- Do not hide gaps behind words like accurate, Abaqus-like, robust, or production-ready. Convert them into measurable criteria or open issues.
+
+## Required Verification Standard
+- Default validation command: `python scripts/validate_workspace.py`.
+- Harness self-test command: `python -m unittest discover -s scripts -p "test_*.py"`.
+- C++ validation target: CMake + MSVC + x64 + Debug + CTest.
+- C++ production changes require related C++ tests.
+- New behavior must follow RED -> GREEN -> VERIFY unless the task is documentation-only.
+- Current MITC4 comparison tolerance is a single value `1e-5`; each compared scalar passes when `abs(error) <= 1e-5` or `relative(error) <= 1e-5`.
+
+## Handoff Files
+Use the shared handoff files:
+
+- `docs/PLAN.md`: overall plan, sequencing, acceptance criteria, and blockers.
+- `docs/PROGRESS.md`: completed work, current state, next tasks, and latest validation.
+- `docs/WORKNOTE.md`: mistakes, failed approaches, environment traps, and lessons for future Agents.
+
+Update rules:
+- Update `docs/PLAN.md` when scope, ordering, acceptance criteria, or blockers change.
+- Update `docs/PROGRESS.md` after meaningful completion or validation.
+- Update `docs/WORKNOTE.md` after mistakes, failed approaches, repeated failures, environment traps, or decisions that future Agents should not rediscover.
+- Do not delete another Agent's dated note unless the user explicitly requests it.
+- If handoff files conflict with the newest user instruction, follow the newest user instruction and record the conflict.
+
+## Failure Routing
+When work fails, classify the failure before fixing:
+
+- requirements ambiguity
+- research/evidence gap
+- formulation defect
+- numerical review issue
+- I/O schema mismatch
+- missing or invalid reference artifact
+- implementation defect
+- build/configuration failure
+- reference comparison tolerance failure
+- physics plausibility failure
+- release readiness gap
+
+Repeated failures must be routed back to the owning upstream stage instead of continuing an unbounded correction loop.
+
+## Agent Output Discipline
+- Each Agent writes the artifact for its stage and records downstream handoff items.
+- Every must requirement needs a verification method and acceptance criteria.
+- Every formulation needs clear DOF, coordinate, unit, sign, Jacobian, integration, and recovery rules.
+- Every I/O contract needs supported syntax, unsupported behavior, internal mapping, schema, units, component names, and matching rules.
+- Every reference model contract needs model purpose, compared quantities, artifacts, provenance, and limitations.
+- Every implementation plan needs test-first tasks, target commands, candidate files, and traceability to upstream requirements.
+- Every verification report needs compared rows, missing/extra rows, max absolute error, max relative error, worst id/component, pass/fail, and failure classification.
+
+## Current Project Defaults
+- Initial feature id: `mitc4-linear-static-shell`.
+- Initial result/reference format: HDF5.
+- Reference policy: stored Abaqus S4R is primary for pass/fail; Abaqus S4 is diagnostic.
+- Required compared quantities: nodal displacement, reaction, element internal force/resultant, and stress.
+- Agents must preserve OpenSees-inspired architecture while using modern C++17 RAII and FESA ownership boundaries.
@@ -0,0 +1,39 @@
+# FESA Multi-Agent Plan
+
+## Purpose
+This file tells a new AI Agent what work is planned and how to continue without reconstructing project intent from the full conversation.
+
+New Agents must read `AGENTS.md`, this file, `docs/PROGRESS.md`, `docs/WORKNOTE.md`, and `docs/AGENT_RULES.md` before editing files.
+
+## Active Objective
+Build the FESA structural solver foundation around the initial feature `mitc4-linear-static-shell`.
+
+## Current High-Level Plan
+1. Maintain project-level documentation and handoff files.
+2. Define requirements for `mitc4-linear-static-shell`.
+3. Gather research evidence for MITC4, OpenSees `ShellMITC4`, Abaqus S4/S4R, patch tests, and Scordelis-Lo.
+4. Write FEM formulation for the MITC4 linear static shell feature.
+5. Define Abaqus `.inp` input subset and HDF5 output/reference schemas.
+6. Define stored Abaqus S4R/S4 reference model bundles.
+7. Write a TDD implementation plan.
+8. Implement C++17/MSVC code using CMake/CTest, MKL, TBB, and HDF5.
+9. Compare FESA HDF5 results against stored Abaqus S4R reference artifacts using `abs-or-rel 1e-5`.
+10. Prepare release documentation after reference verification passes.
+
+## Acceptance Criteria
+- Every solver feature follows the stage-gated workflow in `AGENTS.md`.
+- C++ production changes are test-first.
+- `python scripts/validate_workspace.py` remains the default validation path.
+- MITC4 reference comparison covers nodal displacement, reaction, element internal force/resultant, and stress.
+- Result comparison uses a single tolerance value `1e-5` with absolute-or-relative pass logic.
+
+## Coordination Rules
+- Update this file when the plan, scope, ordering, or acceptance criteria change.
+- Update `docs/PROGRESS.md` after completing work or running validation.
+- Update `docs/WORKNOTE.md` after mistakes, failed approaches, environment traps, or decisions that future Agents should not rediscover.
+- Keep `.codex/agents/*.toml` and `.codex/skills/*/SKILL.md` pointed at `docs/AGENT_RULES.md` for common operating rules.
+
+## Known Blockers
+- No CMake project exists yet, so `python scripts/validate_workspace.py` currently takes the no-op path.
+- HDF5 is not detected in standard local environment paths; implementation will need `HDF5_ROOT` or `HDF5_DIR`.
+- Abaqus reference artifacts are not generated by Agents and must be supplied by a human-approved process.
@@ -0,0 +1,41 @@
+# FESA Multi-Agent Progress
+
+## Current Status
+- Project documentation has been reframed from a harness-only project to the FESA structural solver project.
+- Initial MITC4 solver implementation plan exists in `docs/project-plan/SOLVER_IMPLEMENT_INITIAL_PLAN.md`.
+- Solver architecture guidance exists in `docs/ARCHITECTURE.md`.
+- ADR and PRD have been updated for MITC4, MKL, TBB, HDF5, tolerance, reference artifacts, and solver state separation.
+- Multi-Agent coordination files live under `docs/`: `docs/PLAN.md`, `docs/PROGRESS.md`, and `docs/WORKNOTE.md`.
+- Project plan/design documents live under `docs/project-plan/`.
+- Common per-run AI Agent rules live in `docs/AGENT_RULES.md`.
+
+## Completed
+- Defined the nine-step solver development workflow.
+- Recorded initial MITC4 feature scope: linear static, MITC4 shell, Abaqus `.inp` subset, HDF5 output, Abaqus S4R primary reference.
+- Recorded tolerance policy: `abs(error) <= 1e-5 OR relative(error) <= 1e-5`.
+- Recorded architecture principles: `Domain`, `AnalysisModel`, `AnalysisState`, `DofManager`, factory/registry, adapter layers, deterministic TBB assembly, MKL PARDISO, HDF5 result model.
+- Moved handoff documents from repository root to `docs/`.
+- Moved solver plan/design documents to `docs/project-plan/` and updated agent, skill, test, and document references.
+- Extracted common per-run rules from the solver agent design into `docs/AGENT_RULES.md`.
+- Updated `.codex/agents/*.toml`, `.codex/skills/*/SKILL.md`, and related tests to reference `docs/AGENT_RULES.md` instead of the solver agent design document.
+
+## In Progress
+- Ready for the next stage: requirements baseline for `mitc4-linear-static-shell`.
+
+## Next Tasks
+1. Create `docs/requirements/mitc4-linear-static-shell.md`.
+2. Create `docs/research/mitc4-linear-static-shell-research.md`.
+3. Create `docs/formulations/mitc4-linear-static-shell-formulation.md`.
+4. Create `docs/io-definitions/mitc4-linear-static-shell-io.md`.
+5. Create `docs/reference-models/mitc4-linear-static-shell-reference-models.md`.
+6. Create `docs/implementation-plans/mitc4-linear-static-shell-implementation-plan.md`.
+
+## Last Validation
+- 2026-06-05: After extracting `docs/AGENT_RULES.md`, `python -m unittest discover -s scripts -p "test_*.py"` passed. 85 tests ran successfully.
+- 2026-06-05: `python scripts/validate_workspace.py` passed through the expected no-op path because no root `CMakeLists.txt` exists yet.
+- 2026-06-05: After document relocation and reference updates, `python -m unittest discover -s scripts -p "test_*.py"` passed. 85 tests ran successfully.
+- 2026-06-05: `python scripts/validate_workspace.py` passed through the expected no-op path because no root `CMakeLists.txt` exists yet.
+
+## Open Questions
+- Exact HDF5 C library installation path is not known.
+- Stored Abaqus S4R/S4 reference artifact generation process is not yet defined.
@@ -0,0 +1,26 @@
+# FESA Multi-Agent Work Notes
+
+## Purpose
+This file records mistakes, failed attempts, environment traps, and lessons learned so future AI Agents do not repeat them.
+
+Add dated entries. Do not delete another Agent's note unless the user explicitly asks.
+
+## Notes
+
+### 2026-06-05 - HDF5 Not Found In Standard Paths
+During planning, standard checks for `HDF5_ROOT`, `HDF5_DIR`, `h5dump`, and obvious Program Files HDF5 folders did not find HDF5. Future implementation should not assume HDF5 is locally installed. Use `HDF5_ROOT` or `HDF5_DIR` and fail CMake configuration with a clear diagnostic if missing.
+
+### 2026-06-05 - Validation Currently Has No CMake Project
+`python scripts/validate_workspace.py` currently exits successfully through the no-op path because there is no root `CMakeLists.txt`. This is expected until the C++ solver project is bootstrapped. Once CMake is introduced, validation must configure, build, and run CTest.
+
+### 2026-06-05 - Reference Solvers Are Not Agent-Run
+Agents must not run Abaqus or Nastran. Reference artifacts must come from a human-approved process and be stored under `references/<feature>/<model-id>/`.
+
+### 2026-06-05 - Keep Reaction Recovery Full-System Based
+For constrained DOF elimination, reactions must be recovered as `K_full * U_full - F_full`. Do not compare reactions computed only from the reduced system.
+
+### 2026-06-05 - Avoid PowerShell UTF-8 BOM For TOML And SKILL.md
+PowerShell `Set-Content -Encoding UTF8` added a UTF-8 BOM to `.codex/agents/*.toml` and `.codex/skills/*/SKILL.md`. That broke `tomllib` with `Invalid statement (at line 1, column 1)` and broke skill frontmatter parsing because files no longer started with `---`. Use BOM-free UTF-8 for mechanical rewrites, for example `[System.Text.UTF8Encoding]::new($false)` with `.NET` `WriteAllText`.
+
+### 2026-06-05 - Mechanical Path Replacement Can Rewrite The New Target File
+When replacing old document references with `docs/AGENT_RULES.md`, the new rules file itself was also included in the replacement set and briefly became self-referential. Future broad path rewrites should exclude the newly created target file or inspect it immediately after replacement.
@@ -11,7 +11,7 @@ Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로
 - Skill은 `.codex/skills/<skill-name>/SKILL.md`에 둔다.
 - 각 skill은 필수 frontmatter `name`, `description`과 UI metadata `agents/openai.yaml`을 가진다.
 - Skill 본문은 agent TOML의 역할 설명을 반복하지 않고, 입력, 절차, 산출물, 금지사항, 품질 gate, handoff를 정의한다.
- Skill은 `AGENTS.md`와 `docs/SOLVER_AGENT_DESIGN.md`를 공통 상위 기준으로 읽는다.
+- Skill은 `AGENTS.md`와 `docs/AGENT_RULES.md`를 공통 상위 기준으로 읽는다.
 - Abaqus, Nastran 또는 reference solver 실행은 skill 범위에 포함하지 않는다.
 - Reference CSV 생성 또는 수정은 skill 범위에 포함하지 않는다.
 - C++ 구현 관련 skill은 C++17 이상, MSVC, CMake, CTest, TDD 원칙을 따른다.
@@ -155,10 +155,10 @@ Skill 구성 검증은 `scripts/test_fesa_solver_skills.py`가 담당한다.
 - 10개 solver skill의 `SKILL.md` 존재 여부
 - YAML frontmatter의 `name`, `description`
 - 공통 섹션: `Inputs`, `Workflow`, `Output Contract`, `Boundaries`, `Quality Gate`, `Handoff`
- `AGENTS.md`와 `docs/SOLVER_AGENT_DESIGN.md` 참조
+- `AGENTS.md`와 `docs/AGENT_RULES.md` 참조
 - skill-specific 핵심 문구와 산출물 경로
 - `agents/openai.yaml` UI metadata
- 이 문서가 아니라 실제 skill 파일이 기준이 되도록 `docs/SOLVER_SKILL_DESIGN.md`에 대한 skill 본문 참조 금지
+- 이 문서가 아니라 실제 skill 파일이 기준이 되도록 `docs/project-plan/SOLVER_SKILL_DESIGN.md`에 대한 skill 본문 참조 금지

 검증 명령:

@@ -256,8 +256,8 @@ class FesaSolverSkillTests(unittest.TestCase):
                for section in COMMON_SECTIONS:
                    self.assertIn(section, body)
                self.assertIn("AGENTS.md", body)
-                self.assertIn("docs/SOLVER_AGENT_DESIGN.md", body)
-                self.assertNotIn("docs/SOLVER_SKILL_DESIGN.md", body)
+                self.assertIn("docs/AGENT_RULES.md", body)
+                self.assertNotIn("docs/project-plan/SOLVER_SKILL_DESIGN.md", body)

    def test_solver_skills_define_skill_specific_contracts(self):
        for skill_name, spec in SKILLS.items():
@@ -31,7 +31,7 @@ class FormulationAgentConfigTests(unittest.TestCase):
            "Do not run Abaqus, Nastran, or any reference solver.",
            "Do not generate reference CSVs.",
            "Do not approve release readiness.",
-            "docs/SOLVER_AGENT_DESIGN.md",
+            "docs/AGENT_RULES.md",
            "docs/requirements/<feature-id>.md",
            "docs/research/<feature-id>-research.md",
        ):
@@ -32,7 +32,7 @@ class NumericalReviewAgentConfigTests(unittest.TestCase):
            "Do not run Abaqus, Nastran, or any reference solver.",
            "Do not generate reference CSVs.",
            "Do not approve release readiness.",
-            "docs/SOLVER_AGENT_DESIGN.md",
+            "docs/AGENT_RULES.md",
            "docs/formulations/<feature-id>-formulation.md",
        ):
            self.assertIn(required_text, instructions)
@@ -31,7 +31,7 @@ class RequirementAgentConfigTests(unittest.TestCase):
            "Do not run Abaqus, Nastran, or any reference solver.",
            "Do not create reference CSV outputs.",
            "Requirement Verification Matrix",
-            "docs/SOLVER_AGENT_DESIGN.md",
+            "docs/AGENT_RULES.md",
            "references/<feature>",
        ):
            self.assertIn(required_text, instructions)
@@ -30,7 +30,7 @@ class ResearchAgentConfigTests(unittest.TestCase):
            "Do not finalize FEM formulations.",
            "Do not run Abaqus, Nastran, or any reference solver.",
            "Do not generate reference CSVs.",
-            "docs/SOLVER_AGENT_DESIGN.md",
+            "docs/AGENT_RULES.md",
            "docs/requirements/<feature-id>.md",
            "Separate verified facts from inference.",
        ):