# Architecture: Abaqus User Subroutine Development

## 목표
이 저장소는 Abaqus User Subroutine 개발을 위한 agent-driven workflow와 검증 체계를 제공한다. 핵심 아키텍처는 단계별 specialist agent, gate 문서, no-Abaqus Fortran TDD, opt-in Abaqus validation, reference artifact metadata validation으로 구성된다.

## 주요 원칙
- Abaqus User Subroutine 개발이 프로젝트의 중심이다.
- Fortran source는 Abaqus ABI wrapper와 testable kernel/driver logic을 가능한 한 분리한다.
- 기본 검증은 Abaqus를 실행하지 않는다.
- Abaqus 실행과 reference artifact 생성은 명시적으로 승인된 환경에서만 수행한다.
- Requirements, research, formulation, interface, test model, implementation, validation 산출물을 섞지 않는다.

## 디렉토리 구조
```text
.codex/
├── agents/             # Abaqus User Subroutine specialist agent definitions
├── hooks/              # Codex hook scripts
└── skills/             # Abaqus workflow, review, TDD, validation instructions
docs/
├── requirements/       # Feature requirement specs and verification matrices
├── research/           # Source-backed research briefs
├── formulations/       # FEM formulation specs
├── numerical-reviews/  # Independent numerical reviews
├── io-definitions/     # Abaqus ABI and CSV schema contracts
├── reference-models/   # TDD model and reference artifact plans
├── implementation-plans/
├── build-test-reports/
├── reference-verifications/
├── physics-evaluations/
└── releases/
scripts/
├── execute.py
├── fortran_toolchain.py
├── validate_fortran.py
├── validate_reference_artifacts.py
├── validate_workspace.py
└── test_*.py
tests/
└── fortran/manifest.json       # Optional no-Abaqus Fortran test manifest
references/
└── <feature-id>/<model-id>/    # Optional approved Abaqus reference artifacts
phases/
└── <phase-id>/                 # Optional staged execution plans
```

## Gate 흐름
```text
User request
-> Requirement gate
-> Research gate
-> Formulation gate
-> Numerical review gate
-> Interface gate
-> Test model gate
-> Implementation planning gate
-> RED -> GREEN -> VERIFY Fortran implementation
-> Build/test evidence
-> Reference verification
-> Physics sanity
-> Readiness audit
```

각 gate는 다음 gate가 사용할 수 있는 explicit handoff를 남긴다. Blocking issue는 downstream에서 임의 해결하지 않고 owning upstream gate로 되돌린다.

## Agent / Skill 구조
- `docs/ABAQUS_SUBROUTINE_AGENT_DESIGN.md`는 7단계 개발 프로세스와 agent/skill mapping의 기준 문서다.
- Agent definitions는 `.codex/agents/*.toml`에 있고, 각 agent는 자신의 hard boundary를 가진다.
- Skill instructions는 `.codex/skills/*/SKILL.md`에 있고, 각 skill은 input, workflow, output contract, quality gate, handoff를 정의한다.
- Coordinator Agent는 workflow state와 blocker routing만 담당하고 specialist work를 직접 수행하지 않는다.

## Fortran TDD 구조
```text
Fortran production change
-> related no-Abaqus test must exist or be added first
-> RED: targeted test fails for the expected reason
-> GREEN: minimum Fortran code change
-> VERIFY:
   python scripts/validate_fortran.py
   python scripts/validate_reference_artifacts.py
   python scripts/validate_workspace.py
```

`scripts/validate_fortran.py`는 `tests/fortran/manifest.json`이 있을 때 Intel oneAPI Fortran compiler를 찾아 test executable을 compile/run한다. Compiler discovery는 `ifx`를 우선하고 `ifort`를 fallback으로 사용한다.

## Abaqus ABI 설계
- Abaqus ABI wrapper는 manual signature와 include convention을 보존한다.
- Abaqus/Standard Fortran wrapper는 `aba_param.inc` convention을 따른다.
- Abaqus/Explicit Fortran wrapper는 `vaba_param.inc` convention을 따른다.
- UMAT family는 stress, state variable, `DDSDDE`, time/increment, material constants, tensor ordering을 interface contract에 명시해야 한다.
- VUMAT family는 `nblock` vector loop, old/new arrays, corotational quantity, energy/state update responsibility를 명시해야 한다.
- UEL family는 `RHS`, `AMATRX`, `SVARS`, `ENERGY`, DOF layout, `LFLAGS` requested contribution을 명시해야 한다.

## Reference Artifact 구조
```text
references/<feature-id>/<model-id>/
├── metadata.json
├── model.inp
├── job.msg.tail.txt
├── job.dat.tail.txt
├── job.log.tail.txt
└── *.csv
```

`metadata.json` schema version은 `abaqus-user-subroutine-artifact-v1`이다. `artifact_status=ready-for-comparison`인 artifact는 Abaqus version, precision, command, compiler vendor/name/version, entry points, source file hashes, input file, output tails, declared CSV files를 모두 가져야 한다.

Reference artifacts는 생성 후 검증 입력으로 취급한다. Validation agent는 source code, tests, tolerances, reference artifacts를 임의 수정하지 않는다.

## Validation 흐름
```text
HARNESS_VALIDATION_COMMANDS set
-> run exact commands only

Default workspace validation:
-> scripts/validate_reference_artifacts.py
-> scripts/validate_fortran.py
-> optional CMake/CTest path if CMake project exists
-> optional Abaqus command path only when HARNESS_ABAQUS_VALIDATION=run
```

`HARNESS_ABAQUS_VALIDATION=detect`는 Abaqus executable 탐지만 보고한다. `HARNESS_ABAQUS_VALIDATION=run`은 `HARNESS_ABAQUS_VALIDATION_COMMANDS`가 없으면 configuration error로 실패한다.

## Hook 흐름
```text
apply_patch/Edit/Write
-> .codex/hooks/tdd-guard.py
-> C/C++/Fortran production source changes require related tests

git commit command
-> .codex/hooks/pre_commit_checks.py
-> python -m unittest discover -s scripts -p "test_*.py"
-> python scripts/validate_workspace.py
```

Documents, CMake metadata, reference artifacts, and test files are exempt from the production-source TDD guard where appropriate.

## Optional Supporting CMake / MSVC 흐름
```text
CMakePresets.json has msvc-debug configure preset
-> cmake --preset msvc-debug
-> cmake --build preset binary dir --config Debug
-> ctest --test-dir preset binary dir --output-on-failure -C Debug

CMakeLists.txt exists without preset
-> cmake -S . -B build/msvc-debug -G "Visual Studio 17 2022" -A x64
-> cmake --build build/msvc-debug --config Debug
-> ctest --test-dir build/msvc-debug --output-on-failure -C Debug

No CMake project
-> skip CMake/CTest after script validations
```

이 경로는 supporting native components를 위한 optional validation path이며 프로젝트 정체성을 C++ project로 바꾸지 않는다.

## Failure Routing
- `fortran-compile` 또는 `link`: Implementation 또는 Correction Agent
- `no-abaqus-test`: Implementation 또는 Test Model owner
- `reference-artifact`: Reference Model 또는 Reference Verification Agent
- `schema-mismatch`, `unit-or-coordinate-mismatch`: I/O Definition Agent
- `tolerance-failure`, `nonfinite-result`: Correction Agent 또는 Numerical Review Agent
- `physics-implausible`: Physics Evaluation Agent
- `upstream-contract`: owning upstream gate로 회송
- `environment`: Build/Test Executor Agent가 환경 evidence를 기록하고 중단