add docu

2026-06-10 17:09:08 +09:00
parent beb6d61869
commit 98eba54a12
4 changed files with 296 additions and 111 deletions
@@ -1,75 +1,162 @@
-# 아키텍처
+# Architecture: Abaqus User Subroutine Development

 ## 목표
-이 저장소의 현재 책임은 C++/MSVC 프로젝트를 위한 Codex Harness scaffold를 제공하는 것이다. Harness는 phase execution, edit guard, commit validation, workspace validation을 분리해서 관리한다.
+이 저장소는 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/             # Harness planning/review instructions
-docs/                   # Project and Harness guidance
+└── 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          # Phase step executor
+├── execute.py
+├── fortran_toolchain.py
+├── validate_fortran.py
+├── validate_reference_artifacts.py
 ├── validate_workspace.py
-└── test_*.py           # Harness self-tests
-phases/                 # Optional generated phase plans
+└── 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-approved task
-> Harness phase files under phases/
-> scripts/execute.py injects AGENTS.md and docs/*.md
-> Codex executes one step at a time
-> step updates phases/{phase}/index.json
-> validation runs through scripts/validate_workspace.py
+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++ production changes require related tests
+-> C/C++/Fortran production source changes require related tests

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

-## Validation 흐름
+Documents, CMake metadata, reference artifacts, and test files are exempt from the production-source TDD guard where appropriate.
+
+## Optional Supporting CMake / MSVC 흐름
 ```text
-HARNESS_VALIDATION_COMMANDS set
-> run exact commands
-
-Always, unless HARNESS_VALIDATION_COMMANDS overrides:
-> scripts/validate_reference_artifacts.py
-> scripts/validate_fortran.py
-
 CMakePresets.json has msvc-debug configure preset
 -> cmake --preset msvc-debug
 -> cmake --build preset binary dir --config Debug
-> ctest --test-dir preset binary dir -C Debug
+-> ctest --test-dir preset binary dir --output-on-failure -C Debug

-CMakeLists.txt exists
+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
-> print guidance and exit successfully
-
-HARNESS_ABAQUS_VALIDATION=detect
-> report Abaqus executable discovery only
-
-HARNESS_ABAQUS_VALIDATION=run
-> run HARNESS_ABAQUS_VALIDATION_COMMANDS only
-> never generate reference CSVs
+-> skip CMake/CTest after script validations
 ```

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

-Fortran Abaqus UserSubroutine 개발은 thin Abaqus ABI wrapper와 no-Abaqus kernel/fake-driver tests를 분리한다.
-기본 workspace validation은 Abaqus를 실행하지 않으며, Intel oneAPI Fortran compiler가 감지되고 `tests/fortran/manifest.json`이 있을 때만 Fortran compile/run tests를 수행한다.
-Stored reference artifacts under `references/<feature-id>/<model-id>/` are read-only and validated through metadata, source hashes, log tails, and declared CSV files.
+## 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를 기록하고 중단