# 아키텍처

## 목표
이 저장소의 현재 책임은 C++/MSVC 프로젝트를 위한 Codex Harness scaffold를 제공하는 것이다. Harness는 phase execution, edit guard, commit validation, workspace validation을 분리해서 관리한다.

## 디렉토리 구조
```text
.codex/
├── hooks/              # Codex hook scripts
└── skills/             # Harness planning/review instructions
docs/                   # Project and Harness guidance
scripts/
├── execute.py          # Phase step executor
├── validate_workspace.py
└── test_*.py           # Harness self-tests
phases/                 # Optional generated phase plans
```

## 데이터 흐름
```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
```

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

git commit command
-> .codex/hooks/pre_commit_checks.py
-> Python Harness self-tests
-> scripts/validate_workspace.py
```

## Validation 흐름
```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

CMakeLists.txt exists
-> 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
```

## Abaqus UserSubroutine 확장

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.