docs: make reference metadata optional
This commit is contained in:
KOKO\Mimi
+2
-2
@@ -77,11 +77,11 @@ solution과 test command를 명시한 직접 MSBuild 프로젝트도 검증할
|
||||
**트레이드오프**: 초기 병렬화 범위가 제한된다. MKL 내부 thread와 TBB task arena의 oversubscription 정책을 별도로 문서화해야 한다.
|
||||
|
||||
### ADR-010: Abaqus reference artifact는 사람이 생성하거나 명시 승인된 절차로만 갱신한다
|
||||
**결정**: Agent는 Abaqus, Nastran 또는 reference solver를 직접 실행하지 않는다. reference artifact 생성, 수정, 복원은 명시 승인된 phase에서만 수행한다. 신규 bundle의 provenance는 `metadata.json`에 기록한다. 승인된 `cantilever-beam-b33` legacy baseline은 source commit과 generator, units, coordinate system, schema, tolerance를 설계 및 Reference Model Contract가 대신 기록하므로 이 baseline에 한해서 `metadata.json`과 `README.md`가 N/A다.
|
||||
**결정**: Agent는 Abaqus, Nastran 또는 reference solver를 직접 실행하지 않는다. reference artifact 생성, 수정, 복원은 명시 승인된 phase에서만 수행한다. 모든 bundle의 provenance, generator/version, units, coordinate system, step/frame identity, schema, tolerance와 limitations는 승인된 기능별 Reference Model Contract에 기록한다. `metadata.json`은 선택 reference artifact이며, 부재만으로 bundle을 불완전하다고 판정하지 않는다. 파일이 존재하면 read-only 보조 자료로 inventory하고 계약 및 실제 artifact와 일치하는지 확인하며, 충돌은 숨기지 않고 upstream 계약 문제로 보고한다. 승인된 `cantilever-beam-b33` legacy baseline의 space-containing filename과 `README.md` N/A 예외는 유지한다.
|
||||
|
||||
**이유**: reference 결과는 solver correctness의 기준이다. 생성 절차가 불명확하면 구현 결함과 reference artifact 오류를 구분할 수 없다.
|
||||
|
||||
**트레이드오프**: reference 준비가 느려질 수 있다. Legacy 예외는 일반 artifact 규칙을 복잡하게 하지만 exact path와 source commit을 고정하고 read-only로 취급해 감사 가능성을 유지한다.
|
||||
**트레이드오프**: Reference Model Contract가 필수 provenance의 단일 source of truth가 되어 별도 JSON 파일 없이도 bundle을 사용할 수 있다. 선택 `metadata.json`이 계약과 중복될 수 있으므로 존재 시 일관성 검사가 필요하다. Legacy filename과 `README.md` 예외는 일반 artifact 규칙을 복잡하게 하지만 exact path와 source commit을 고정하고 read-only로 취급해 감사 가능성을 유지한다.
|
||||
|
||||
### ADR-011: 구형 단일 검증 진입점 계약을 폐기한다
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
- 기능 요구조건, 이론 정식화, 코드 구현, 검증, 배포 역할을 분리한다.
|
||||
- 실행 가능성만으로 성공을 판단하지 않고, 레퍼런스 결과와 물리량을 비교해 기능 완료를 판정한다.
|
||||
- 테스트는 구현 전에 준비한다. 개발 대상 솔버 테스트와 레퍼런스 솔버 결과 비교 테스트를 함께 사용한다.
|
||||
- Abaqus나 Nastran을 Agent가 직접 실행하지 않는다. `reference/<model-id>/`에 저장된 `model.inp`, `metadata.json`, Abaqus reference CSV files를 검증 기준으로 사용한다.
|
||||
- Abaqus나 Nastran을 Agent가 직접 실행하지 않는다. `reference/<model-id>/`에 저장된 `model.inp`와 Abaqus reference CSV files를 검증 기준으로 사용하고, 선택 `metadata.json`이 존재하면 read-only 보조 자료로 계약과 대조한다.
|
||||
- 기본 개발 환경은 C++17 이상, MSVC, CMake, CTest이다.
|
||||
- 모든 기능은 tolerance 기준을 명시하고, 기준을 만족할 때만 배포 후보가 된다.
|
||||
- Harness 운영은 `docs/HARNESS_WORKFLOW.md`의 계획, 독립 Step 실행, PreToolUse/Stop 검증 계층을 따른다.
|
||||
@@ -129,7 +129,7 @@ TDD와 검증에 사용할 테스트 모델을 준비하는 Agent이다.
|
||||
reference/
|
||||
<model-id>/
|
||||
model.inp
|
||||
metadata.json
|
||||
metadata.json # optional
|
||||
<model-id>_displacements.csv
|
||||
<model-id>_reactions.csv
|
||||
<model-id>_internalforces.csv
|
||||
@@ -371,6 +371,6 @@ Coordinator Agent는 분류 결과에 따라 Requirement, Formulation, I/O Defin
|
||||
## 운영 메모
|
||||
|
||||
- Agent 산출물은 가능한 한 문서, 테스트, 비교 리포트 형태로 남긴다.
|
||||
- 사람이 생성한 Abaqus reference artifact의 출처와 생성 조건을 `metadata.json`에 기록한다.
|
||||
- 사람이 생성한 Abaqus reference artifact의 출처와 생성 조건은 승인된 기능별 Reference Model Contract에 기록한다. 선택 `metadata.json`이 존재하면 read-only로 참고하고 계약과의 충돌을 보고한다.
|
||||
- reference artifact가 바뀌면 기능 구현 변경과 같은 수준으로 검토한다.
|
||||
- 기능 완료 판정은 코드 실행 성공이 아니라 reference validation과 physics evaluation 통과를 기준으로 한다.
|
||||
|
||||
@@ -89,7 +89,7 @@ Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로
|
||||
|
||||
- smoke, analytical, patch test, benchmark, regression, negative/invalid-input 모델을 구분한다.
|
||||
- `reference/<model-id>/` artifact bundle 계약을 정의한다.
|
||||
- `model.inp`, `metadata.json`, `<model-id>_displacements.csv`, `<model-id>_reactions.csv`, `<model-id>_internalforces.csv`, `<model-id>_stresses.csv`를 기준 artifact로 둔다.
|
||||
- `model.inp`와 요구된 `<model-id>_displacements.csv`, `<model-id>_reactions.csv`, `<model-id>_internalforces.csv`, `<model-id>_stresses.csv`를 기준 artifact로 둔다. 필수 provenance는 Reference Model Contract에 기록하고, 선택 `metadata.json`이 존재하면 read-only로 대조한다.
|
||||
- required Abaqus reference CSV가 없으면 완료 상태가 아니라 `needs-reference-artifacts`로 둔다.
|
||||
|
||||
### `fesa-cpp-msvc-tdd`
|
||||
@@ -118,7 +118,7 @@ uv run --with pytest python -m pytest -v -rs
|
||||
### `fesa-reference-comparison`
|
||||
|
||||
- `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT` 순서로 수행한다.
|
||||
- `metadata.json`, `model.inp`, `results.h5`, Abaqus reference CSV files, schema version, units, coordinate system, step/frame identity, ID matching, output location, tolerance source를 확인한다.
|
||||
- `model.inp`, `results.h5`, Abaqus reference CSV files, Reference Model Contract의 provenance, schema version, units, coordinate system, step/frame identity, ID matching, output location, tolerance source를 확인한다. 선택 `metadata.json`이 존재하면 inventory하고 계약과 대조하되, 부재만으로 비교를 중단하지 않는다.
|
||||
- max absolute error, max relative error, RMS error, norm error, missing rows, extra rows를 보고한다.
|
||||
- Reference pass는 physics validation이나 release readiness를 의미하지 않는다.
|
||||
|
||||
|
||||
@@ -3,7 +3,8 @@
|
||||
> **Historical / Superseded:** 이 문서는 2026-06-10 시점의 초기 조사와 실행 기록이다.
|
||||
> 현재 제품 범위는 `docs/PRD.md`, Harness 운영 계약은 `docs/HARNESS_WORKFLOW.md`와
|
||||
> `docs/HARNESS.md`를 따른다. 아래의 구형 스킬명, 검증 명령, 기능 우선순위는 현재
|
||||
> 지침으로 사용하지 않는다.
|
||||
> 지침으로 사용하지 않는다. 아래의 `metadata.json` 필수 provenance 문구도 ADR-010의
|
||||
> 선택-artifact 정책으로 대체되었다.
|
||||
|
||||
## 메타데이터
|
||||
- 작성일: 2026-06-10
|
||||
|
||||
@@ -302,9 +302,9 @@ Comparison 전에 다음 exact files가 존재하고 변경되지 않았음을
|
||||
Input은 `TYPE=B33`이어야 하고 trim한 CSV header는 아래 mapping 표와 정확히 일치해야
|
||||
한다. 각 projected row key는 unique하고 모든 numeric value는 finite여야 한다. 파일
|
||||
missing/type mismatch는 `needs-reference-artifacts`, header/value/identity mismatch는
|
||||
`schema-mismatch`이며 comparison은 시작하지 않는다. 이 legacy bundle에서
|
||||
`metadata.json`과 `README.md`는 N/A이고 파일을 rename, rewrite, zero-clamp 또는 보정하지
|
||||
않는다.
|
||||
`schema-mismatch`이며 comparison은 시작하지 않는다. `metadata.json` 부재는 프로젝트
|
||||
전역 정책에 따라 허용되고, `README.md`는 이 legacy bundle에서 N/A다. 파일을 rename,
|
||||
rewrite, zero-clamp 또는 보정하지 않는다.
|
||||
|
||||
### Header and component normalization
|
||||
|
||||
|
||||
@@ -460,7 +460,7 @@ solver output nor a reference artifact.
|
||||
|
||||
### 7.1 S4/S4R portfolio separation
|
||||
|
||||
- S4 and S4R use distinct `model_id`, input, metadata, and CSV bundles.
|
||||
- S4 and S4R use distinct `model_id`, input, Reference Model Contract records, and CSV bundles. An optional `metadata.json` does not define bundle identity.
|
||||
- FESA maps both source types to `FESA-MITC4`, but Abaqus S4 and S4R values are not
|
||||
expected to equal each other on a finite mesh.
|
||||
- Reference comparison always compares one FESA run with Abaqus rows generated from
|
||||
@@ -484,7 +484,7 @@ The files were introduced by source commit
|
||||
zero-clamped, normalized, or repaired. A hash mismatch is
|
||||
`needs-reference-artifacts`, not permission to restore or change the bundle.
|
||||
|
||||
The alias is `recognized-legacy-alias-needs-reference-metadata`. Before numerical
|
||||
The alias is `recognized-legacy-alias-needs-reference-contract`. Before numerical
|
||||
comparison, the Reference Model contract must supply or approve externally:
|
||||
|
||||
- generation owner/date and exact provenance;
|
||||
@@ -495,8 +495,8 @@ comparison, the Reference Model contract must supply or approve externally:
|
||||
- CSV schema version and tolerance policy.
|
||||
|
||||
CSV lacks explicit step/frame/unit/coordinate columns. They map to
|
||||
`(Step-1,frame 0)`, global Cartesian, and documented units if and only if approved
|
||||
metadata confirms that exact interpretation. Absence or conflict is a
|
||||
`(Step-1,frame 0)`, global Cartesian, and documented units if and only if the approved
|
||||
Reference Model Contract confirms that exact interpretation. Missing contract data or a conflict is a
|
||||
schema/provenance failure; I/O Definition does not infer values.
|
||||
|
||||
### 7.3 Separate canonical S4R bundle
|
||||
@@ -506,14 +506,15 @@ At least one S4R reference bundle is still required:
|
||||
```text
|
||||
reference/<s4r-model-id>/
|
||||
model.inp
|
||||
metadata.json
|
||||
<s4r-model-id>_displacements.csv
|
||||
```
|
||||
|
||||
`model.inp` must contain the approved subset and `TYPE=S4R`. Metadata records
|
||||
generator/version/provenance, unit system, coordinate system, model/step/frame,
|
||||
material/section/thickness, source element type, schema version, and tolerance
|
||||
policy. Optional reaction/stress artifacts remain nonblocking evidence.
|
||||
`model.inp` must contain the approved subset and `TYPE=S4R`. The approved Reference
|
||||
Model Contract records generator/version/provenance, unit system, coordinate system,
|
||||
model/step/frame, material/section/thickness, source element type, schema version, and
|
||||
tolerance policy. `metadata.json` is optional; if present, it is read-only supplementary
|
||||
evidence and every overlapping field is checked against the contract and stored artifacts.
|
||||
Optional reaction/stress artifacts remain nonblocking evidence.
|
||||
|
||||
`<s4r-model-id>` is a Reference Model-owned schema variable, not an unresolved
|
||||
filename placeholder in this I/O contract.
|
||||
|
||||
@@ -12,7 +12,7 @@ Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반
|
||||
- 기능별 reference model portfolio를 smoke, analytical, patch test, benchmark, regression, negative/invalid-input model로 구분한다.
|
||||
- `model.inp`가 I/O Definition Agent의 supported Abaqus keyword subset 안에 있는지 확인한다.
|
||||
- `reference/<model-id>/` artifact bundle 구조와 필수 파일을 정의한다.
|
||||
- `metadata.json` provenance, 단위, 좌표계, Abaqus version/source, output request, tolerance 정책을 정의한다.
|
||||
- provenance, 단위, 좌표계, Abaqus version/source, output request, tolerance 정책을 기능별 Reference Model Contract에 정의한다. 선택 `metadata.json`이 존재하면 read-only로 inventory하고 계약과 대조한다.
|
||||
- Abaqus reference CSV 파일 요구사항을 정의한다.
|
||||
- requirement와 model, compared quantity, FESA HDF5 dataset, reference CSV, tolerance, artifact status를 연결하는 Coverage Matrix를 작성한다.
|
||||
|
||||
@@ -53,12 +53,12 @@ Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반
|
||||
|
||||
| model_id | category | purpose | status | required_artifacts |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| <model-id> | smoke | <basic parser/solve path> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
|
||||
| <model-id> | analytical | <closed-form comparison> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
|
||||
| <model-id> | patch test | <element consistency check> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
|
||||
| <model-id> | benchmark | <trusted benchmark comparison> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
|
||||
| <model-id> | regression | <known defect guard> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
|
||||
| <model-id> | negative/invalid-input | <unsupported keyword or invalid model diagnostic> | draft | model.inp, metadata.json |
|
||||
| <model-id> | smoke | <basic parser/solve path> | draft | model.inp, required Abaqus reference CSV files |
|
||||
| <model-id> | analytical | <closed-form comparison> | draft | model.inp, required Abaqus reference CSV files |
|
||||
| <model-id> | patch test | <element consistency check> | draft | model.inp, required Abaqus reference CSV files |
|
||||
| <model-id> | benchmark | <trusted benchmark comparison> | draft | model.inp, required Abaqus reference CSV files |
|
||||
| <model-id> | regression | <known defect guard> | draft | model.inp, required Abaqus reference CSV files |
|
||||
| <model-id> | negative/invalid-input | <unsupported keyword or invalid model diagnostic> | draft | model.inp |
|
||||
|
||||
## Model Record
|
||||
|
||||
@@ -90,7 +90,7 @@ Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반
|
||||
reference/
|
||||
<model-id>/
|
||||
model.inp
|
||||
metadata.json
|
||||
metadata.json # optional
|
||||
<model-id>_displacements.csv
|
||||
<model-id>_reactions.csv
|
||||
<model-id>_internalforces.csv
|
||||
@@ -100,7 +100,6 @@ reference/
|
||||
|
||||
Required files:
|
||||
- `model.inp`: Abaqus input file for the reference model.
|
||||
- `metadata.json`: provenance and model contract metadata.
|
||||
- `<model-id>_displacements.csv`: required when nodal displacement is a verification quantity.
|
||||
- `<model-id>_reactions.csv`: required when constrained DOF reactions or global equilibrium are verification quantities.
|
||||
- `<model-id>_internalforces.csv`: required when element internal force is a verification quantity.
|
||||
@@ -108,12 +107,19 @@ Required files:
|
||||
- `README.md`: short description, generation notes, and limitations.
|
||||
|
||||
Optional files:
|
||||
- `metadata.json`: optional machine-readable copy of reference metadata; inspect read-only and cross-check against the approved Reference Model Contract when present.
|
||||
- `<model-id>_strains.csv`: required when strain is part of the acceptance criteria.
|
||||
- `<model-id>_energy_or_residual.csv`: required when energy balance, residual, or convergence data is part of the acceptance criteria.
|
||||
- `<model-id>_<quantity>.csv`: feature-specific reference quantity when upstream contracts require it.
|
||||
- `notes.md`: manual review notes.
|
||||
|
||||
## Metadata JSON Contract
|
||||
## Reference Metadata Contract
|
||||
|
||||
The feature-specific Reference Model Contract is the required source of truth for every field
|
||||
below. A bundle does not need a `metadata.json` file. When the optional file exists, use this
|
||||
schema, inventory it read-only, and compare every overlapping field with the contract and stored
|
||||
artifacts. Absence is `absent-allowed`; a conflict is an upstream contract/provenance issue and
|
||||
must not be resolved by silently preferring either value.
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -180,10 +186,11 @@ Optional files:
|
||||
## Artifact Acceptance Checklist
|
||||
- 모든 `must` requirement가 최소 하나의 `model_id`와 `compared_quantity`에 연결되어 있다.
|
||||
- `model.inp`가 기능별 supported Abaqus keyword subset을 벗어나지 않는다.
|
||||
- `metadata.json`에 provenance, Abaqus version/source, units, coordinate system, tolerance, reference CSV schema version이 기록되어 있다.
|
||||
- Reference Model Contract에 provenance, Abaqus version/source, units, coordinate system, tolerance, reference CSV schema version과 artifact inventory가 기록되어 있다.
|
||||
- 선택 `metadata.json`의 부재는 허용되고, 존재하면 read-only inventory와 계약 일치 검사가 기록되어 있다.
|
||||
- 필요한 Abaqus reference CSV 파일이 존재하거나, 기능상 불필요한 quantity는 명확한 reason과 함께 제외되어 있다.
|
||||
- output request가 필요한 Abaqus reference CSV 물리량을 생성할 수 있도록 정의되어 있다.
|
||||
- required Abaqus reference CSV 또는 metadata provenance가 없으면 status는 `needs-reference-artifacts`다.
|
||||
- required Abaqus reference CSV 또는 Reference Model Contract의 필수 provenance가 없으면 status는 `needs-reference-artifacts`다.
|
||||
- tolerance, source, units, coordinate system이 불명확하면 status는 `needs-user-decision`이다.
|
||||
|
||||
## Open Issues and Downstream Handoff
|
||||
@@ -208,6 +215,7 @@ Optional files:
|
||||
- model data와 history data를 구분해야 한다.
|
||||
- output request와 required Abaqus reference CSV 사이의 연결이 명확해야 한다.
|
||||
- `reference/<model-id>/` 구조와 필수 artifact가 명시되어야 한다.
|
||||
- `metadata.json`에는 provenance, Abaqus version/source, units, coordinate system, tolerance, reference CSV schema version이 포함되어야 한다.
|
||||
- Reference Model Contract에는 provenance, Abaqus version/source, units, coordinate system, tolerance, reference CSV schema version이 포함되어야 한다.
|
||||
- 선택 `metadata.json`은 없어도 되며, 존재할 때만 read-only로 참고하고 계약과 대조한다.
|
||||
- required Abaqus reference CSV가 없으면 완료 상태가 아니라 `needs-reference-artifacts` 상태로 둔다.
|
||||
- 모든 `must` requirement는 Coverage Matrix에서 model, compared quantity, FESA HDF5 dataset, reference CSV, tolerance, verification method로 추적되어야 한다.
|
||||
|
||||
@@ -187,16 +187,16 @@ These files shall not be generated, modified, renamed, corrected or restored by
|
||||
Harness. Their spaces and existing CAE report headers are legacy aliases, not a naming pattern for
|
||||
new models.
|
||||
|
||||
Only for this approved legacy bundle:
|
||||
For this approved legacy bundle:
|
||||
|
||||
- `metadata.json`: N/A
|
||||
- `metadata.json`: absent-allowed under the project-wide optional metadata policy
|
||||
- `README.md`: N/A
|
||||
- stress CSV: N/A because beam stress reference comparison is outside the approved V0 scope
|
||||
|
||||
The approved design and this contract jointly replace those missing files by recording model ID,
|
||||
provenance, generator, source commit, units, coordinate systems, step/frame identity, logical CSV
|
||||
schema, exact inventory, tolerance policy and the stress N/A reason. Their absence therefore does
|
||||
not change the legacy record to `needs-reference-artifacts`.
|
||||
The approved design and this contract record model ID, provenance, generator, source commit,
|
||||
units, coordinate systems, step/frame identity, logical CSV schema, exact inventory, tolerance
|
||||
policy and the stress N/A reason. The optional metadata file's absence and the approved legacy
|
||||
README/stress exclusions therefore do not change the record to `needs-reference-artifacts`.
|
||||
|
||||
### Future reference bundles
|
||||
|
||||
@@ -207,7 +207,7 @@ marks a quantity N/A:
|
||||
reference/
|
||||
<model-id>/
|
||||
model.inp
|
||||
metadata.json
|
||||
metadata.json # optional
|
||||
<model-id>_displacements.csv
|
||||
<model-id>_reactions.csv
|
||||
<model-id>_internalforces.csv
|
||||
@@ -215,14 +215,15 @@ reference/
|
||||
README.md
|
||||
```
|
||||
|
||||
CSV names are canonical `<model-id>_*.csv` names. `metadata.json` and `README.md` are mandatory.
|
||||
A quantity CSV may be omitted only when the upstream acceptance contract explicitly records N/A
|
||||
and gives its verification replacement. Missing required files keep that model at
|
||||
`needs-reference-artifacts`.
|
||||
CSV names are canonical `<model-id>_*.csv` names. `README.md` is mandatory for later bundles;
|
||||
`metadata.json` is optional. A quantity CSV may be omitted only when the upstream acceptance
|
||||
contract explicitly records N/A and gives its verification replacement. Missing required files
|
||||
or required Reference Model Contract provenance keep that model at `needs-reference-artifacts`.
|
||||
|
||||
## Metadata JSON Contract
|
||||
## Reference Metadata Contract
|
||||
|
||||
`metadata.json` is N/A only for `cantilever-beam-b33`. Every later bundle shall include at least:
|
||||
This document is the required source of truth for the following metadata. A later bundle may
|
||||
optionally duplicate it in `metadata.json` using at least this schema:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -250,7 +251,8 @@ and gives its verification replacement. Missing required files keep that model a
|
||||
```
|
||||
|
||||
No agent may invent unknown provenance fields or mark a bundle ready merely because filenames
|
||||
exist.
|
||||
exist. An absent `metadata.json` is allowed. If the file exists, inventory it read-only and report
|
||||
any disagreement with this contract or stored artifacts as an upstream contract/provenance issue.
|
||||
|
||||
## Abaqus Reference CSV Requirements
|
||||
|
||||
@@ -365,7 +367,7 @@ Read-only inventory inspection on `2026-08-09` established the following pre-imp
|
||||
- every projected numeric field is finite and every row has the header arity;
|
||||
- generator, source commit, SI units, coordinates, step/increment/time and tolerance provenance are
|
||||
recorded in the approved design and this contract;
|
||||
- legacy `metadata.json`, `README.md` and stress CSV are accepted N/A exceptions;
|
||||
- absent `metadata.json` is allowed by project-wide policy; legacy `README.md` and stress CSV are accepted N/A exceptions;
|
||||
- no reference value was recalculated and no comparison was performed.
|
||||
|
||||
Before an actual comparison, tooling must repeat all artifact checks, verify the exact Frame and
|
||||
|
||||
@@ -10,7 +10,7 @@ Reference Verification Agent는 Build/Test Executor Agent 통과 후 generated s
|
||||
|
||||
수행한다:
|
||||
- `reference/<model-id>/` artifact bundle과 generated solver `results.h5`를 확인한다.
|
||||
- `metadata.json`, `model.inp`, required Abaqus reference CSV files, reference CSV schema version, FESA HDF5 schema version, units, coordinate system, step/frame identity, node/element ID matching rule, output location, component naming, tolerance policy를 확인한다.
|
||||
- `model.inp`, required Abaqus reference CSV files, Reference Model Contract의 provenance, reference CSV schema version, FESA HDF5 schema version, units, coordinate system, step/frame identity, node/element ID matching rule, output location, component naming, tolerance policy를 확인한다. 선택 `metadata.json`이 존재하면 read-only로 inventory하고 계약과 대조한다.
|
||||
- FESA HDF5 dataset을 normalized row record로 읽고 Abaqus reference CSV row와 직접 비교한다.
|
||||
- comparison command가 FESA `results.h5`에서 deterministic CSV view를 materialize할 수 있지만, 이 파일은 debugging/review용 derived artifact일 뿐 reference artifact가 아니다.
|
||||
- upstream 문서가 요구할 때만 `<model-id>_strains.csv`, `<model-id>_energy_or_residual.csv`, 또는 `<model-id>_<quantity>.csv`를 추가 비교한다.
|
||||
@@ -38,7 +38,6 @@ ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT
|
||||
|
||||
`ARTIFACT CHECK`에서 다음 항목이 없으면 비교를 시작하지 않는다.
|
||||
|
||||
- `metadata.json`
|
||||
- `model.inp`
|
||||
- generated solver `results.h5`
|
||||
- `reference/<model-id>/<model-id>_displacements.csv`
|
||||
@@ -55,6 +54,12 @@ ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT
|
||||
- component naming
|
||||
- tolerance policy
|
||||
|
||||
`metadata.json`은 필수 artifact가 아니다. 파일이 없으면 inventory에 `absent-allowed`로
|
||||
기록하고 비교를 계속한다. 파일이 존재하면 read-only로 읽어 Reference Model Contract와
|
||||
실제 input/CSV의 중복 필드를 대조한다. 충돌은 `needs-upstream-decision` 또는 적절한
|
||||
schema/provenance failure로 분류하며, 파일 부재만으로 `needs-reference-artifacts`를
|
||||
선택하지 않는다.
|
||||
|
||||
## 비교 대상
|
||||
|
||||
| quantity | fesa_hdf5_dataset | reference_csv |
|
||||
@@ -102,7 +107,7 @@ ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT
|
||||
| --- | --- | --- | --- |
|
||||
| reference_model_dir | reference/<model-id>/ | present | missing | <notes> |
|
||||
| reference_input | reference/<model-id>/model.inp | present | missing | <input summary> |
|
||||
| metadata | reference/<model-id>/metadata.json | present | missing | <provenance summary> |
|
||||
| optional_metadata | reference/<model-id>/metadata.json | present / absent-allowed / conflict | <contract cross-check summary> |
|
||||
| reference_displacements_csv | reference/<model-id>/<model-id>_displacements.csv | present | missing | <row/schema summary> |
|
||||
| reference_reactions_csv | reference/<model-id>/<model-id>_reactions.csv | present | missing | <row/schema summary> |
|
||||
| reference_internalforces_csv | reference/<model-id>/<model-id>_internalforces.csv | present | missing | <row/schema summary> |
|
||||
@@ -171,7 +176,7 @@ ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT
|
||||
## 품질 기준
|
||||
|
||||
- 모든 `must` requirement의 reference-comparison 항목은 model id, compared quantity, FESA HDF5 dataset, reference CSV, tolerance에 trace되어야 한다.
|
||||
- reference artifact는 읽기 전용이다. `model.inp`, `metadata.json`, `reference/<model-id>/<model-id>_*.csv`를 수정하지 않는다.
|
||||
- reference artifact는 읽기 전용이다. `model.inp`, 존재하는 `metadata.json`, `reference/<model-id>/<model-id>_*.csv`를 수정하지 않는다.
|
||||
- FESA `results.h5`가 authoritative solver output이고 Abaqus reference CSV files가 authoritative reference result다.
|
||||
- solver debug CSV view는 행 정렬과 사람이 검토 가능한 비교 view일 뿐이며 tolerance에 맞추기 위해 후처리 보정하지 않는다.
|
||||
- stress/strain은 element id, integration point 또는 recovery location, component naming이 일치할 때만 비교한다.
|
||||
|
||||
@@ -23,8 +23,8 @@ B33 reference tolerance. It does not approve physics sanity or release readiness
|
||||
|
||||
The approved B33 exception overrides the generic new-bundle inventory. The exact
|
||||
four legacy files with spaces are the complete read-only reference bundle;
|
||||
`metadata.json`, `README.md`, and a stress CSV are contractually N/A and are not
|
||||
missing artifacts.
|
||||
`metadata.json` is absent-allowed under project-wide policy, while `README.md` and a
|
||||
stress CSV are contractually N/A and are not missing artifacts.
|
||||
|
||||
| item | exact path | status | direct audit evidence |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -33,7 +33,7 @@ missing artifacts.
|
||||
| displacement CSV | `reference/cantilever beam/cantilever beam displacements.csv` | present, valid | Exact 9-column CAE header; 11 unique rows; 66 finite values. |
|
||||
| reaction CSV | `reference/cantilever beam/cantilever beam reactions.csv` | present, valid | Exact 9-column CAE header; 11 unique rows; 66 finite values. |
|
||||
| elemental-force CSV | `reference/cantilever beam/cantilever beam elemental forces.csv` | present, valid | Exact 7-column CAE header; 11 unique rows; 44 finite values. |
|
||||
| legacy metadata | `reference/cantilever beam/metadata.json` | N/A | Approved design, ADR-010, I/O definition, and reference-model contract supply provenance. |
|
||||
| optional metadata | `reference/cantilever beam/metadata.json` | absent-allowed | Approved design, ADR-010, I/O definition, and reference-model contract supply provenance; absence is not a missing artifact. |
|
||||
| legacy README | `reference/cantilever beam/README.md` | N/A | Approved B33 legacy exception. |
|
||||
| reference stress CSV | N/A | N/A | Abaqus beam-stress comparison is outside the approved V0 scope. |
|
||||
| authoritative solver output | `.harness/build/reference/cantilever-beam-b33/results.h5` | present, valid | 25,336 bytes; generated by the fresh exact CTest; HDF5 schema inspected read-only with HDF5 2.1.1 utilities. |
|
||||
|
||||
@@ -173,7 +173,7 @@ disposition. No must requirement is deferred or blocked.
|
||||
| nonlinear/dynamic/contact/thermal | analysis/physics | no geometric/material nonlinearity, dynamics, contact, or thermal response | documented, deferred feature |
|
||||
| shear and warping stress | output/physics | no transverse/torsional shear-stress or warping-stress recovery; no nodal averaging | documented, deferred feature |
|
||||
| beam stress reference | verification | axial `S11` is mandatory and analytically/schema tested, but Abaqus stress reference is N/A | accepted contract N/A |
|
||||
| approved four-file legacy exception | artifacts | spaces and legacy names remain; `metadata.json`, `README.md`, and stress CSV are N/A only for this bundle | read-only accepted exception; not precedent for new bundles |
|
||||
| approved four-file legacy exception | artifacts | spaces and legacy names remain; `metadata.json` is absent-allowed by project-wide policy, while `README.md` and stress CSV are N/A only for this bundle | read-only accepted filename/README exception; not precedent for new bundles |
|
||||
| reference coverage | verification | single identity-axis local-z B33 cantilever does not itself cover axial/torsion/local-y/rotated/prescribed/line-load/nonzero-fiber stress | accepted; complementary analytical/unit portfolio passes |
|
||||
| Euler-Bernoulli applicability | modeling | deep/short beams may be too stiff; no automatic slenderness threshold is approved | documented modeling limit |
|
||||
| energy evidence | output | no HDF5 energy dataset; Step 27 derives positive `0.5*F^T*d` and uses rank/energy tests | accepted evidence limit |
|
||||
|
||||
@@ -77,11 +77,12 @@ Requirement Agent는 솔버 기능 요청을 검증 가능한 요구조건으로
|
||||
Expected location: `reference/<model-id>/`
|
||||
|
||||
- `model.inp`: required | not-applicable
|
||||
- `metadata.json`: required
|
||||
- `metadata.json`: optional; if present, inspect read-only and cross-check against the approved Reference Model Contract
|
||||
- `<model-id>_displacements.csv`: required | not-applicable
|
||||
- `<model-id>_reactions.csv`: required | not-applicable
|
||||
- `<model-id>_internalforces.csv`: required | not-applicable
|
||||
- `<model-id>_stresses.csv`: required | not-applicable
|
||||
- Reference Model Contract metadata: required; record provenance, generator/version, units, coordinate system, step/frame identity, schema, tolerance, artifact inventory, and limitations
|
||||
|
||||
## Requirement Verification Matrix
|
||||
|
||||
|
||||
@@ -134,7 +134,7 @@ The approved logical model is `cantilever-beam-b33`, schema is
|
||||
`Abaqus/CAE Learning Edition 2024`, and the coordinate/output contract is global Cartesian
|
||||
nodal output plus beam-local section-force output at `Step-1`, increment 1, step time 1.0.
|
||||
|
||||
- **FESA-REQ-LS3DEB-040** — The V0 reference baseline shall use the exact read-only files `reference/cantilever beam/cantilever beam.inp`, `reference/cantilever beam/cantilever beam displacements.csv`, `reference/cantilever beam/cantilever beam reactions.csv`, and `reference/cantilever beam/cantilever beam elemental forces.csv` without rename, rewrite, correction, or restoration; `metadata.json` and `README.md` are N/A only for this approved legacy bundle.
|
||||
- **FESA-REQ-LS3DEB-040** — The V0 reference baseline shall use the exact read-only files `reference/cantilever beam/cantilever beam.inp`, `reference/cantilever beam/cantilever beam displacements.csv`, `reference/cantilever beam/cantilever beam reactions.csv`, and `reference/cantilever beam/cantilever beam elemental forces.csv` without rename, rewrite, correction, or restoration; absent `metadata.json` is allowed by project-wide policy and `README.md` is N/A for this approved legacy bundle.
|
||||
- **FESA-REQ-LS3DEB-041** — Before comparison, artifact validation shall confirm all four files, `TYPE=B33`, expected CAE report headers, unique row keys, and finite values; failure shall be classified as `needs-reference-artifacts` or `schema-mismatch` and comparison shall not start.
|
||||
- **FESA-REQ-LS3DEB-042** — Reference verification shall compare displacement by source-node identity (`U1/U2/U3/UR1/UR2/UR3`), reaction by source-node identity (`RF1/RF2/RF3/RM1/RM2/RM3`), and node-station-normalized section resultant by `SF1->N`, `SM1->My`, `SM2->Mz`, `SM3->T`; adjacent interior endpoints shall first agree within approved tolerance and shall not be averaged to hide a mismatch.
|
||||
- **FESA-REQ-LS3DEB-043** — Reference comparison shall run only after build/test passes; physics sanity shall run only after reference comparison passes and shall check global force/moment equilibrium, reaction sign, displacement direction, symmetry, element section-force consistency, and normalized residual; release readiness shall require all prior gate evidence and known limitations.
|
||||
@@ -184,7 +184,7 @@ nodal output plus beam-local section-force output at `Step-1`, increment 1, step
|
||||
| FESA-REQ-LS3DEB-037 | For the approved SI bundle, displacement and rotation shall use `absolute_floor=1e-9`, force and moment shall use `absolute_floor=1e-3`, and a zero component scale shall use the applicable absolute floor alone. | tolerance | Preserve dimensional meaning near zero. | Approved design §11.3; ADR-014 | must | Comparison tests with zero/near-zero rows | Each quantity uses its exact SI floor and zero-scale groups use no relative contribution. | SI `1e-9` displacement/rotation; `1e-3` force/moment | reference-model-agent; reference-verification-agent | approved |
|
||||
| FESA-REQ-LS3DEB-038 | Reference values shall not be zero-clamped and rows shall not be dropped; missing, extra, duplicate, nonfinite, schema-mismatched, or identity-mismatched rows shall fail before tolerance evaluation. | tolerance | Prevent false passes through omission or clamping. | Approved design §§11.3, 12; ADR-014 | must | Negative comparison tests | Every listed invalid case fails before numeric comparison and zero values remain unchanged. | No ignored invalid rows | reference-verification-agent | approved |
|
||||
| FESA-REQ-LS3DEB-039 | The verification report shall record every row decision and maximum absolute error, component-scale normalized error, RMS error, norm error, and worst row/component for each compared quantity. | tolerance | Make the pass/fail decision auditable. | Approved design §11.3; ADR-014 | must | Verification report schema/review | Per-row decisions and all required aggregate/worst metrics are present for every quantity. | Report completeness | reference-verification-agent; release-agent | approved |
|
||||
| FESA-REQ-LS3DEB-040 | The V0 reference baseline shall use the exact read-only files `reference/cantilever beam/cantilever beam.inp`, `reference/cantilever beam/cantilever beam displacements.csv`, `reference/cantilever beam/cantilever beam reactions.csv`, and `reference/cantilever beam/cantilever beam elemental forces.csv` without rename, rewrite, correction, or restoration; `metadata.json` and `README.md` are N/A only for this approved legacy bundle. | reference | Protect the approved correctness baseline. | Approved design §12; ADR-010, ADR-014 | must | Artifact inventory; Git diff review | Exact filenames exist and no reference file is added, removed, renamed, or content-modified. | Exact path/content identity | reference-model-agent; reference-verification-agent; release-agent | approved |
|
||||
| FESA-REQ-LS3DEB-040 | The V0 reference baseline shall use the exact read-only files `reference/cantilever beam/cantilever beam.inp`, `reference/cantilever beam/cantilever beam displacements.csv`, `reference/cantilever beam/cantilever beam reactions.csv`, and `reference/cantilever beam/cantilever beam elemental forces.csv` without rename, rewrite, correction, or restoration; absent `metadata.json` is allowed by project-wide policy and `README.md` is N/A for this approved legacy bundle. | reference | Protect the approved correctness baseline. | Approved design §12; ADR-010, ADR-014 | must | Artifact inventory; Git diff review | Exact filenames exist and no reference file is added, removed, renamed, or content-modified. | Exact path/content identity | reference-model-agent; reference-verification-agent; release-agent | approved |
|
||||
| FESA-REQ-LS3DEB-041 | Before comparison, artifact validation shall confirm all four files, `TYPE=B33`, expected CAE report headers, unique row keys, and finite values; failure shall be classified as `needs-reference-artifacts` or `schema-mismatch` and comparison shall not start. | reference | Detect stale B31 or malformed evidence. | Approved design §§6.3, 12 | must | Artifact-check integration test | All checks pass before comparison and every failure uses an approved classification. | Exact inventory and schema | reference-model-agent; reference-verification-agent | approved |
|
||||
| FESA-REQ-LS3DEB-042 | Reference verification shall compare displacement by source-node identity (`U1/U2/U3/UR1/UR2/UR3`), reaction by source-node identity (`RF1/RF2/RF3/RM1/RM2/RM3`), and node-station-normalized section resultant by `SF1->N`, `SM1->My`, `SM2->Mz`, `SM3->T`; adjacent interior endpoints shall first agree within approved tolerance and shall not be averaged to hide a mismatch. | reference | Compare equivalent quantities despite legacy station rows. | Approved design §§8.2, 12 | must | Reference comparison test/report | All components match by source identity and interior endpoints pass before deterministic representative selection. | Requirements 036 and 037 policy | io-definition-agent; reference-model-agent; reference-verification-agent | approved |
|
||||
| FESA-REQ-LS3DEB-043 | Reference comparison shall run only after build/test passes; physics sanity shall run only after reference comparison passes and shall check global force/moment equilibrium, reaction sign, displacement direction, symmetry, element section-force consistency, and normalized residual; release readiness shall require all prior gate evidence and known limitations. | governance | Keep numerical similarity distinct from physical/release approval. | Approved design §§11, 12, 13 | must | Gate evidence audit | Each downstream report cites the preceding pass and physics evidence covers all six checks before release review. | Relevant upstream tolerances | coordinator-agent; physics-evaluation-agent; release-agent | approved |
|
||||
|
||||
@@ -201,8 +201,8 @@ workspace, so no exact filename, schema, units, generator, step/frame or row inv
|
||||
asserted here. The bundle shall remain read-only when it becomes observable.
|
||||
|
||||
- **FESA-REQ-LSMITC4-065** — Reference Model shall inventory `reference/shell/` without creating, renaming, rewriting or repairing files and shall classify a missing/unobservable candidate as `needs-reference-artifacts` rather than fabricate its content.
|
||||
- **FESA-REQ-LSMITC4-066** — A usable new reference bundle shall contain `model.inp`, `metadata.json` and `<model-id>_displacements.csv`, or shall receive an explicitly approved legacy-alias contract that records its exact existing filenames without rename.
|
||||
- **FESA-REQ-LSMITC4-067** — Reference metadata shall record Abaqus generator/version, creation provenance, source element type, model/step/frame identity, user unit system, global coordinate convention, section/material/thickness data, CSV schema and tolerance policy.
|
||||
- **FESA-REQ-LSMITC4-066** — A usable new reference bundle shall contain `model.inp` and `<model-id>_displacements.csv`, or shall receive an explicitly approved legacy-alias contract that records its exact existing filenames without rename; `metadata.json` is optional and its absence shall not make the bundle unusable.
|
||||
- **FESA-REQ-LSMITC4-067** — The approved Reference Model Contract shall record Abaqus generator/version, creation provenance, source element type, model/step/frame identity, user unit system, global coordinate convention, section/material/thickness data, CSV schema and tolerance policy; if `metadata.json` exists, it shall be inventoried read-only and checked against that contract and the stored artifacts.
|
||||
- **FESA-REQ-LSMITC4-068** — Artifact validation shall confirm an approved single `*STEP, *STATIC` model, expected `S4` or `S4R` source type, supported keyword subset, unique finite displacement rows and exact source-node/component identity before comparison.
|
||||
- **FESA-REQ-LSMITC4-069** — End-to-end mapping evidence shall cover at least one `S4` input and at least one `S4R` input; the declared `reference/shell/` S4R model may satisfy only the S4R side after inventory validation, so separate S4 evidence remains required.
|
||||
- **FESA-REQ-LSMITC4-070** — Reference verification shall compare FESA HDF5 global nodal displacement rows directly against Abaqus displacement CSV rows by model, step/frame, source node and component identity; a FESA-generated CSV view shall not become the authoritative comparison source.
|
||||
|
||||
@@ -4,6 +4,9 @@
|
||||
> 보존한다. 이 문서의 Python `unittest`, 삭제된 workspace validation script, Harness
|
||||
> 환경 변수 관련 검증 절차는 폐기되었으며 현재 운영 계약은
|
||||
> `docs/HARNESS_WORKFLOW.md`와 `docs/HARNESS.md`를 따른다.
|
||||
> 이 문서 아래의 `metadata.json` 필수 문구와 예시는 ADR-010의 2026-08-12 정책으로
|
||||
> 대체되었다. 현재는 Reference Model Contract가 필수 provenance를 소유하고,
|
||||
> `metadata.json`은 존재할 때만 read-only로 참고하는 선택 artifact다.
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
|
||||
@@ -430,8 +430,9 @@ Abaqus `.inp` 자체에는 단위 선언이 없으므로 일반 solver run의 un
|
||||
`user-consistent-unspecified`로 기록하고 solver가 입력 파일만 보고 SI를 추론하지
|
||||
않는다. 승인된 cantilever B33 reference에 한해서는 이 설계와 후속 Reference Model
|
||||
Contract가 입력 수치의 단위계를 SI로 선언하고, reference verification이 동일한 입력으로
|
||||
생성된 FESA 결과에 그 외부 단위 계약을 적용한다. 새 reference model은 별도
|
||||
`metadata.json`에 단위계를 선언해야 한다.
|
||||
생성된 FESA 결과에 그 외부 단위 계약을 적용한다. 새 reference model도 승인된
|
||||
Reference Model Contract에 단위계를 선언한다. 선택 `metadata.json`이 존재하면 그
|
||||
단위 선언을 read-only 보조 자료로 계약과 대조한다.
|
||||
|
||||
- displacement: `[node_count, 6]`
|
||||
- reaction: `[node_count, 6]`
|
||||
@@ -575,11 +576,12 @@ step time 1.0 계약으로 해석한다.
|
||||
| stress | N/A: beam stress reference comparison은 승인 범위에서 제외 |
|
||||
|
||||
이 기존 bundle의 space-containing filename과 CAE report header는 승인된 legacy alias로
|
||||
그대로 지원하며 reference artifact를 rename하거나 rewrite하지 않는다. `metadata.json`과
|
||||
`README.md`는 이 baseline에 한해서 N/A다. 이 설계와 Step 5의 Reference Model Contract가
|
||||
대신 model ID, provenance, units, coordinate system, schema, file inventory, tolerance와
|
||||
stress N/A 사유를 기록한다. 이후 추가하는 reference model에는 canonical artifact 이름,
|
||||
`metadata.json`, `README.md`를 요구한다.
|
||||
그대로 지원하며 reference artifact를 rename하거나 rewrite하지 않는다. `README.md`는 이
|
||||
baseline에 한해서 N/A다. `metadata.json`은 프로젝트 전역에서 선택 artifact이며 이
|
||||
bundle에는 존재하지 않는다. 이 설계와 Step 5의 Reference Model Contract가 model ID,
|
||||
provenance, units, coordinate system, schema, file inventory, tolerance와 stress N/A 사유를
|
||||
기록한다. 이후 추가하는 reference model에는 canonical artifact 이름과 `README.md`를
|
||||
요구하며, 선택 `metadata.json`이 존재하면 계약과 대조한다.
|
||||
|
||||
Reference verification은 build/test gate 통과 후 승인 input으로 FESA `results.h5`를
|
||||
생성하고 다음을 직접 비교한다.
|
||||
@@ -592,8 +594,9 @@ Reference verification은 build/test gate 통과 후 승인 input으로 FESA `re
|
||||
|
||||
Artifact check는 네 파일의 존재, B33 element type, expected header, 유일한 row key,
|
||||
finite value를 확인한다. 하나라도 충족하지 않으면 `needs-reference-artifacts` 또는
|
||||
`schema-mismatch`로 분류하고 comparison을 시작하지 않는다. 현재 baseline은
|
||||
`metadata.json` 또는 `README.md` 부재만으로 차단하지 않는다.
|
||||
`schema-mismatch`로 분류하고 comparison을 시작하지 않는다. `metadata.json` 부재는 모든
|
||||
bundle에서 허용되며, 현재 baseline의 `README.md` 부재도 승인된 legacy 예외로 차단하지
|
||||
않는다.
|
||||
|
||||
Agent와 Harness는 Abaqus를 실행하거나 reference artifact를 생성·수정하지 않는다.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user