FESADev/docs/AGENT_RULES.md

# 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.

## Repository Defaults
- Canonical remote repository: `https://teagit.mimi1011.synology.me/baram2584/FESADev.git`
- Use `origin` as the default remote name.
- The current shared baseline branch is `dev`.
- Use `codex/<short-task-name>` for new work branches unless the user requests a different branch.
- At session start, verify repository state with `git status --short --branch` and verify the remote with `git remote -v`.
- If a fresh checkout has no remote, add it with `git remote add origin https://teagit.mimi1011.synology.me/baram2584/FESADev.git`.
- Do not push, tag, release, or publish externally unless the user explicitly requests or approves it.

## Global Solver Workflow
All solver features follow this stage-gated workflow:

1. Analyze new 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, HDF5 result schema or explicitly approved CSV export 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.
- Local HDF5 default install: `C:\Program Files\HDF_Group\HDF5\2.1.1`; use `HDF5_ROOT` for this root or `HDF5_DIR` for `C:\Program Files\HDF_Group\HDF5\2.1.1\cmake`.
- 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.