김경종
93 lines
5.1 KiB
Markdown
93 lines
5.1 KiB
Markdown
# 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.
|