# Project: Abaqus User Subroutine Development

## 프로젝트 정체성

- 이 저장소의 목적은 Abaqus User Subroutine을 요구조건 분석부터 검증까지 일관되게 개발하는 것이다.
- User Subroutine production code는 Fortran을 기본 언어로 작성한다.
- Intel oneAPI Fortran compiler를 기본 컴파일러 체계로 사용한다. 자동 탐지는 `ifx`를 우선하고, 없으면 `ifort`를 사용한다.
- 이 프로젝트는 Abaqus job 해석을 직접 실행하지 않는다. 해석은 사용자가 다른 Abaqus PC에서 수행하고, 이 저장소는 ODB에서 추출된 CSV와 provenance artifact를 검증 입력으로 사용한다.
- `.codex/agents/`와 `.codex/skills/`는 Abaqus User Subroutine 개발 단계별 전문 agent와 작업 규칙의 기준이다.

## 기술 스택

- Abaqus User Subroutine in Fortran
- Intel oneAPI Fortran compiler on Windows
- Python 3 validation and automation scripts
- Codex custom agents and skills
- Optional CMake + CTest validation path when a CMake project exists
- Optional MSVC/x64/Debug validation path for supporting native components only

## 개발 워크플로우

1. Subroutine 요구조건 분석
2. `fem-theory-query`를 통한 FEM 이론 조사와 로컬 Abaqus User Subroutine Manual 근거 확인
3. 코드 구현을 위한 유한요소 정식화
4. Subroutine 입출력 파라미터와 Abaqus ABI 계약 정의
5. TDD 방법을 사용하는 no-Abaqus test model 및 외부 생성 reference artifact 계약 작성
6. Fortran 코드 구현
7. `references/<feature-id>/`의 사용자 제공 CSV와 provenance artifact를 통한 결과 검증

## Agent / Skill 운영 규칙

- 장기 작업은 위 7단계 gate로 나누고, 각 gate는 독립적으로 검토 가능한 문서 산출물을 남긴다.
- Agent mapping과 gate 정의는 `docs/ABAQUS_SUBROUTINE_AGENT_DESIGN.md`를 기준으로 한다.
- Requirement Agent는 `docs/requirements/<feature-id>.md`에 요구조건과 Requirement Verification Matrix를 작성한다.
- Research Agent는 `fem-theory-query`와 로컬 Abaqus manual 원문을 사용하고, `docs/research/<feature-id>-research.md`에 source-backed fact, inference, applicability limit를 분리해 기록한다.
- Formulation Agent와 Numerical Review Agent는 FEM 지식이 필요할 때 `fem-theory-query`를 사용하고 formulation, tangent, state variable, numerical risk를 구현 전 검토한다.
- I/O Definition Agent는 로컬 Abaqus manual 원문을 근거로 ABI argument, update responsibility, tensor order, unit, ODB 추출 CSV schema를 명시한다.
- Reference Model Agent는 `tests/fortran/manifest.json` 계획과 `references/<feature-id>/<model-id>/` artifact 계약을 정의한다. 최소 artifact는 `model.inp`, extracted CSV, `.msg/.dat/.log/.sta` tail files를 포함해야 한다.
- Implementation Agent는 승인된 implementation plan만 구현하며 RED -> GREEN -> VERIFY 순서를 지킨다.
- Validation, Physics Evaluation, Release Agent는 source code, tests, reference artifacts, tolerances를 임의로 변경하지 않는다.

## 근거 탐색 규칙

- 유한요소 정식화, residual/tangent, constitutive integration, benchmark, 수치 검증 등 FEM 관련 지식은 반드시 `fem-theory-query`를 통해 탐색한다.
- Abaqus User Subroutine의 ABI, argument 의미, update responsibility, product applicability, utility routine은 먼저 `docs/AbaqusUserSubroutineManual/INDEX_MAP.md`에서 항목 위치를 찾고, `INDEX.md`의 해당 record를 읽은 뒤, record에 열거된 모든 `source_ranges` 원문을 순서대로 읽어 확인한다.
- `INDEX.md`의 `summary`, keyword, content anchor는 탐색 metadata이며 구현 또는 interface 결정의 단독 근거가 아니다. 매뉴얼 source span을 authoritative evidence로 취급한다.
- Solver-result verification은 사용자가 다른 Abaqus PC에서 생성해 첨부한 변위, 응력 또는 feature별 결과 CSV와 provenance metadata를 입력으로 사용한다.

## 작업 상태 공유 파일

- 모든 agent는 새 작업을 시작할 때 `AGENTS.md`를 읽은 뒤 루트의 `PLAN.md`, `PROGRESS.md`, `WORKNOTE.md`를 확인해 현재 목표, 진행 상태, 알려진 시행착오를 파악한다.
- `PLAN.md`는 현재 목표, phase/step 분해, 성공 기준, 범위 제외, 미해결 결정을 관리한다. 계획이 바뀌면 구현 전에 먼저 갱신한다.
- `PROGRESS.md`는 완료된 일, 진행 중인 일, 막힌 일, 다음 agent가 바로 수행해야 할 next action, 마지막 검증 명령 결과를 관리한다. step 시작/완료/blocked/error 전환 시 갱신한다.
- `WORKNOTE.md`는 실수, 실패한 명령, 잘못된 가정, 우회 방법, 재발 방지 메모를 기록한다. 단순 진행 로그를 중복하지 말고 다음 agent에게 도움이 되는 시행착오만 남긴다.
- 여러 agent가 나눠 작업할 때는 `PROGRESS.md`의 현재 owner/active step을 먼저 확인하고, 자신이 맡은 범위와 변경 파일을 기록한 뒤 작업한다.
- phase 파일(`phases/<phase>/stepN.md`)과 세 공유 파일이 충돌하면 더 구체적인 phase step 지시를 우선하되, 충돌 사실과 처리 결정을 `WORKNOTE.md`에 기록한다.
- 작업을 마치기 전에는 `PROGRESS.md`에 실제 수행한 검증 명령과 결과를 남기고, 새 시행착오가 있으면 `WORKNOTE.md`를 갱신한다.

## 아키텍처 규칙

- CRITICAL: 기본 검증 경로는 `python scripts/validate_workspace.py`이다.
- CRITICAL: 이 프로젝트의 수치 검증은 Abaqus job 실행이 아니라 사용자 제공 extracted result validation이다. ODB는 직접 파싱하지 않고, 사용자가 다른 Abaqus PC에서 ODB로부터 추출한 변위·응력 등 CSV를 schema/tolerance로 비교한다.
- CRITICAL: 새 기능 또는 동작 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다.
- CRITICAL: Fortran user subroutine production file을 바꿀 때는 관련 no-Abaqus Fortran/Python driver test가 있어야 한다.
- CRITICAL: Abaqus reference artifact 등록, 갱신, 승인된 extracted result 복원은 명시적으로 요청된 phase에서만 수행한다.
- Abaqus ABI wrapper는 얇게 유지하고, 테스트 가능한 계산 로직은 no-Abaqus kernel 또는 driver에서 검증 가능하게 분리한다.
- Reference artifacts는 승인 후 read-only evidence로 취급한다.
- Codex custom agent의 `model_reasoning_effort` 기본값은 `extra high`로 둔다.
- Codex hook 정책은 `.codex/hooks/`에 둔다.
- Abaqus User Subroutine planning/review instructions는 `.codex/skills/`에 둔다.
- Generated phase execution outputs remain ignored under `phases/**/step*-output.json`.

## 검증 명령어

```bash
python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py
python scripts/validate_fortran.py
python scripts/validate_reference_artifacts.py
python scripts/execute.py <phase-dir>
python scripts/execute.py <phase-dir> --push
```

## Fortran / External Result 검증 기본값

- `HARNESS_FORTRAN_VALIDATION=auto`: `tests/fortran/manifest.json`이 있으면 Intel Fortran no-Abaqus tests를 실행한다.
- `HARNESS_FORTRAN_VALIDATION=off`: Fortran validation을 건너뛴다.
- `HARNESS_FORTRAN_VALIDATION=detect`: manifest와 compiler 감지만 수행하고 compile/run command를 만들지 않는다.
- `HARNESS_FORTRAN_COMPILER=auto`: `ifx`를 우선 사용하고, 없으면 `ifort`를 사용한다.
- `HARNESS_ONEAPI_VARS_BAT`: Intel oneAPI 환경 설정 batch file override.
- Abaqus job 실행 관련 환경 변수는 legacy/diagnostic capability로만 취급한다. 새 validation workflow는 저장소 내부 Abaqus 해석 실행을 요구하거나 권장하지 않는다.
- Reference validation의 기본 입력은 사용자가 외부 Abaqus 해석 후 ODB에서 추출해 첨부한 CSV와 provenance metadata이다.

## Supporting CMake / MSVC 검증 기본값

- CMake project가 존재할 때만 CMake/CTest 경로를 실행한다.
- Generator: `Visual Studio 17 2022`
- Platform: `x64`
- Config: `Debug`
- Build directory: `build/msvc-debug`
- Override variables:
  - `HARNESS_VALIDATION_COMMANDS`
  - `HARNESS_CMAKE_GENERATOR`
  - `HARNESS_CMAKE_PLATFORM`
  - `HARNESS_CMAKE_CONFIG`
  - `HARNESS_BUILD_DIR`

## 개발 프로세스 규칙

- 문서 변경은 관련 구현을 대신하지 않는다. Requirements, research, formulation, interface, test model, implementation, validation evidence를 구분한다.
- 모든 must requirement는 verification method, acceptance criteria, tolerance 또는 decision owner를 가져야 한다.
- FEM 및 Abaqus manual 기반 claim은 사용한 skill 또는 manual section과 source span까지 추적 가능해야 한다.
- Public example repository는 layout과 학습 자료로만 사용한다. Acceptance evidence로 쓰려면 source, license, version, generated artifact provenance를 별도로 기록한다.
- Abaqus `model.inp`, extracted CSV, `.msg/.dat/.log/.sta` tail files는 reference artifact contract에 맞춰 저장한다. ODB 자체는 직접 파싱 대상이 아니며, 필요하면 opaque artifact 또는 hash/provenance로만 기록한다.
- 커밋 전 hook은 Python self-test와 workspace validation을 실행해야 한다.
- 커밋 메시지는 conventional commits 형식을 따른다: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`.
- 작업이 완료되고 필수 검증이 통과하면 변경 사항을 conventional commit으로 커밋한 뒤 원격 저장소에 push한다.
