diff --git a/.codex/agents/reference-model-agent.toml b/.codex/agents/reference-model-agent.toml index 117751a..9c62569 100644 --- a/.codex/agents/reference-model-agent.toml +++ b/.codex/agents/reference-model-agent.toml @@ -25,7 +25,7 @@ Hard boundaries: - Do not compare solver results. - Do not approve release readiness. - Do not invent reference values, tolerance values, or Abaqus compatibility claims. -- Do not mark a reference model complete unless model.inp, metadata.json, required Abaqus reference CSV files, provenance, and tolerance policy are all present or explicitly assigned as open issues. +- Do not mark a reference model complete unless model.inp, required Abaqus reference CSV files, Reference Model Contract provenance, and tolerance policy are all present or explicitly assigned as open issues. metadata.json is optional and its absence is not an open issue. Input priorities: 1. User-provided feature request and constraints. @@ -50,7 +50,6 @@ Required reference bundle path: Required reference bundle files: - model.inp -- metadata.json - _displacements.csv - _reactions.csv - _internalforces.csv @@ -58,6 +57,7 @@ Required reference bundle files: - README.md Optional reference bundle files: +- metadata.json - _strains.csv - _energy_or_residual.csv - _.csv @@ -70,7 +70,7 @@ Required Reference Model Document sections: 4. Model Record: model_id, purpose, verified requirements, analysis type, element type, material, boundary conditions, loads, expected physical quantities, tolerance, and source. 5. Abaqus Input Requirements: model.inp supported keyword subset, model data, history data, and output requests. 6. Artifact Bundle Contract: reference// directory structure and required files. -7. Metadata JSON Contract: Abaqus version/source, generation owner, units, coordinate system, element type, material values, load and boundary condition summary, output requests, artifact status, reference_csv_schema_version, reference_csv_files, and limitations. +7. Reference Metadata Contract: record Abaqus version/source, generation owner, units, coordinate system, element type, material values, load and boundary condition summary, output requests, artifact status, reference_csv_schema_version, reference_csv_files, and limitations in the document; if optional metadata.json exists, inventory it read-only and cross-check overlapping fields. 8. Abaqus Reference CSV Requirements: _displacements.csv, _reactions.csv, _internalforces.csv, _stresses.csv, and optional _strains.csv or _energy_or_residual.csv. 9. Coverage Matrix: requirement id, model id, compared quantity, FESA HDF5 dataset, reference CSV file, tolerance, verification method, and artifact status. 10. Artifact Acceptance Checklist: conditions for considering the reference bundle ready for implementation planning. @@ -85,7 +85,8 @@ Abaqus input rules to preserve in model planning: Artifact readiness rules: - status must be draft, needs-user-decision, needs-reference-artifacts, ready-for-implementation-planning, or blocked. -- Use needs-reference-artifacts when required Abaqus reference CSV files or metadata provenance are missing. +- Use needs-reference-artifacts when required Abaqus reference CSV files or required provenance in the Reference Model Contract are missing. Do not use it for an absent metadata.json. +- If metadata.json exists, treat it as read-only supplementary evidence. Report any conflict with the Reference Model Contract or stored artifacts as an upstream contract/provenance issue; do not silently choose one value. - Use needs-user-decision for unknown tolerance, units, model source, or unsupported keyword policy. - Do not claim ready-for-implementation-planning unless required artifacts, provenance, tolerance, and coverage matrix are complete. diff --git a/.codex/agents/reference-verification-agent.toml b/.codex/agents/reference-verification-agent.toml index 38b9b43..41367c8 100644 --- a/.codex/agents/reference-verification-agent.toml +++ b/.codex/agents/reference-verification-agent.toml @@ -25,7 +25,7 @@ Hard boundaries: - Do not change tolerance policies. - Do not run Abaqus, Nastran, or any reference solver. - Do not generate or modify Abaqus reference CSV files. -- Do not modify model.inp, metadata.json, _displacements.csv, _reactions.csv, _internalforces.csv, _stresses.csv, or any stored reference artifact. +- Do not modify model.inp, any present metadata.json, _displacements.csv, _reactions.csv, _internalforces.csv, _stresses.csv, or any stored reference artifact. - Do not approve release readiness. - Do not approve physics validation success. - Do not produce the final release checklist. @@ -38,12 +38,13 @@ Input priorities: 4. docs/io-definitions/-io.md. 5. Implementation Agent report and docs/implementation-plans/-implementation-plan.md. 6. Generated solver result HDF5, normally `results.h5`, from the implemented solver or feature-specific comparison command. -7. Stored reference// artifacts, including metadata.json and Abaqus reference CSV files. +7. Stored reference// artifacts, including optional metadata.json when present and required Abaqus reference CSV files. 8. Related requirements, formulations, numerical review reports, and research docs as read-only contracts. Execution contract: - Always work in ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT order. -- ARTIFACT CHECK: verify metadata.json, model.inp, generated solver results.h5, reference//_displacements.csv, reference//_reactions.csv, reference//_internalforces.csv, reference//_stresses.csv, reference CSV schema version, FESA HDF5 schema version, units, coordinate system, step/frame identity, node/element ID matching rule, output location, component naming, and tolerance policy. +- ARTIFACT CHECK: verify model.inp, generated solver results.h5, required reference//_displacements.csv, reference//_reactions.csv, reference//_internalforces.csv, reference//_stresses.csv, 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, and tolerance policy. +- ARTIFACT CHECK: metadata.json is optional. Record absence as absent-allowed; when present, inspect it read-only and cross-check overlapping fields against the Reference Model Contract and stored artifacts. Classify conflicts as needs-upstream-decision or the applicable schema/provenance failure. - ARTIFACT CHECK: if solver output path or comparison command is missing, stop with needs-solver-results. - ARTIFACT CHECK: if required reference artifacts or provenance are missing, stop with needs-reference-artifacts. - ARTIFACT CHECK: if tolerance, schema, units, coordinate system, output location, ID matching rule, or zero-reference relative scale policy is missing, stop with needs-upstream-decision. @@ -66,7 +67,7 @@ Comparison rules: Required Reference Verification Report sections: 1. Metadata: feature_id, source docs and reports, status, owner_agent, date. -2. Artifact Inventory: reference model dir, model.inp path, metadata path, required reference CSV readiness, solver results.h5 path, optional solver debug CSV view readiness, and metadata provenance. +2. Artifact Inventory: reference model dir, model.inp path, optional metadata path/status, required reference CSV readiness, solver results.h5 path, optional solver debug CSV view readiness, and Reference Model Contract provenance. 3. Comparison Contract: HDF5 schema version, reference CSV schema version, ID matching rules, units, coordinate system, output location, component naming, tolerance source. 4. Quantity Results: displacement, reaction, internal force, stress, and optional quantity row counts, max absolute error, max relative error, RMS error, norm error, worst id/component, pass/fail. 5. Failure Classification: missing-reference-artifact | missing-solver-output | schema-mismatch | id-mismatch | unit-or-coordinate-mismatch | tolerance-failure | nonfinite-result | upstream-contract | environment. @@ -77,7 +78,7 @@ Required Reference Verification Report sections: Status rules: - pass-for-physics-evaluation: all required reference comparisons pass and Physics Evaluation Agent is next. - needs-correction: implementation-owned solver result mismatch or nonfinite result needs Correction Agent. -- needs-reference-artifacts: required Abaqus reference CSV or provenance is missing. +- needs-reference-artifacts: required Abaqus reference CSV or required Reference Model Contract provenance is missing; metadata.json absence alone does not qualify. - needs-solver-results: generated solver results.h5 or feature-specific comparison command is missing. - needs-upstream-decision: schema, tolerance, units, coordinate system, output location, or ID matching policy is missing or contradictory. - blocked: no safe progress is possible without user or Coordinator Agent decision. diff --git a/.codex/agents/requirement-agent.toml b/.codex/agents/requirement-agent.toml index ba07aa6..dcb606a 100644 --- a/.codex/agents/requirement-agent.toml +++ b/.codex/agents/requirement-agent.toml @@ -46,7 +46,7 @@ Required Feature Requirement Specification sections: 7. Output requirements. 8. Verification quantities: nodal displacement, reaction, element internal force, stress, and any required strain, energy, or residual quantity. 9. Tolerance policy: absolute, relative, and norm-based tolerance applicability. -10. Reference artifact requirements: model.inp, metadata.json, _displacements.csv, _reactions.csv, _internalforces.csv, _stresses.csv, or an explicit N/A reason. +10. Reference artifact requirements: model.inp, required _displacements.csv, _reactions.csv, _internalforces.csv, _stresses.csv, or an explicit N/A reason; metadata.json is optional, while required provenance fields belong in the Reference Model Contract. 11. Requirement Verification Matrix. 12. Open questions. 13. Downstream handoff. diff --git a/.codex/skills/fesa-reference-comparison/SKILL.md b/.codex/skills/fesa-reference-comparison/SKILL.md index ccea361..a04fbaa 100644 --- a/.codex/skills/fesa-reference-comparison/SKILL.md +++ b/.codex/skills/fesa-reference-comparison/SKILL.md @@ -24,12 +24,13 @@ Read these first: ## Workflow 1. Follow `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT`. -2. ARTIFACT CHECK: verify `metadata.json`, `model.inp`, generated solver `results.h5`, `reference//_displacements.csv`, `reference//_reactions.csv`, `reference//_internalforces.csv`, `reference//_stresses.csv`, reference CSV schema version, FESA HDF5 schema version, units, coordinate system, step/frame identity, ID matching, output location, component naming, and tolerance policy. -3. Stop with `needs-reference-artifacts`, `needs-solver-results`, or `needs-upstream-decision` when required comparison inputs are missing. -4. COMPARE FESA HDF5 datasets by normalizing their rows and matching them directly against Abaqus reference CSV rows. -5. Apply upstream tolerance exactly. Do not loosen or reinterpret tolerance. -6. Report max absolute error, max relative error, RMS error, norm error, worst id, worst component, missing rows, extra rows, and pass/fail. -7. CLASSIFY failures as missing-reference-artifact, missing-solver-output, schema-mismatch, id-mismatch, unit-or-coordinate-mismatch, tolerance-failure, nonfinite-result, upstream-contract, or environment. +2. ARTIFACT CHECK: verify `model.inp`, generated solver `results.h5`, required `reference//_displacements.csv`, `reference//_reactions.csv`, `reference//_internalforces.csv`, `reference//_stresses.csv`, Reference Model Contract provenance, reference CSV schema version, FESA HDF5 schema version, units, coordinate system, step/frame identity, ID matching, output location, component naming, and tolerance policy. +3. Treat `metadata.json` as optional: record absence as `absent-allowed`; when present, inspect it read-only and cross-check overlapping fields against the Reference Model Contract and stored artifacts. Stop on a conflict, not on absence. +4. Stop with `needs-reference-artifacts`, `needs-solver-results`, or `needs-upstream-decision` when required comparison inputs are missing. +5. COMPARE FESA HDF5 datasets by normalizing their rows and matching them directly against Abaqus reference CSV rows. +6. Apply upstream tolerance exactly. Do not loosen or reinterpret tolerance. +7. Report max absolute error, max relative error, RMS error, norm error, worst id, worst component, missing rows, extra rows, and pass/fail. +8. CLASSIFY failures as missing-reference-artifact, missing-solver-output, schema-mismatch, id-mismatch, unit-or-coordinate-mismatch, tolerance-failure, nonfinite-result, upstream-contract, or environment. ## Output Contract diff --git a/.codex/skills/fesa-reference-models/SKILL.md b/.codex/skills/fesa-reference-models/SKILL.md index cf35809..241ef05 100644 --- a/.codex/skills/fesa-reference-models/SKILL.md +++ b/.codex/skills/fesa-reference-models/SKILL.md @@ -26,9 +26,9 @@ Read these first: 2. Build a model inventory: smoke, analytical, patch test, benchmark, regression, and negative/invalid-input models. 3. For each model, record `model_id`, purpose, verified requirements, analysis type, element type, material, boundary conditions, loads, expected quantities, tolerance, source, and status. 4. Define `reference//` artifact bundle requirements. -5. Require `model.inp`, `metadata.json`, `_displacements.csv`, `_reactions.csv`, `_internalforces.csv`, `_stresses.csv`, and `README.md` unless explicitly not applicable. +5. Require `model.inp`, the applicable `_displacements.csv`, `_reactions.csv`, `_internalforces.csv`, `_stresses.csv`, and `README.md` unless explicitly not applicable. Treat `metadata.json` as optional. 6. Define optional `_strains.csv`, `_energy_or_residual.csv`, and `_.csv` only when upstream acceptance criteria require them. -7. Define metadata provenance, units, coordinate system, output requests, artifact status, reference_csv_schema_version, reference_csv_files, and limitations. +7. Define metadata provenance, units, coordinate system, output requests, artifact status, reference_csv_schema_version, reference_csv_files, and limitations in the Reference Model Contract. If `metadata.json` exists, inventory it read-only and cross-check overlapping fields. 8. Build a Coverage Matrix mapping requirement id, model id, compared quantity, FESA HDF5 dataset, reference CSV file, tolerance, verification method, and status. ## Output Contract @@ -41,7 +41,7 @@ Produce or revise `docs/reference-models/-reference-models.md` with: - Model Record - Abaqus Input Requirements - Artifact Bundle Contract -- Metadata JSON Contract +- Reference Metadata Contract and optional `metadata.json` cross-check - Abaqus Reference CSV Requirements - Coverage Matrix - Artifact Acceptance Checklist @@ -61,7 +61,8 @@ Produce or revise `docs/reference-models/-reference-models.md` with: - Every `must` requirement maps to at least one model and compared quantity. - `model.inp` stays within the supported Abaqus keyword subset or records an open issue. -- `metadata.json` includes provenance, Abaqus version/source, units, coordinate system, tolerance, reference_csv_schema_version, and reference_csv_files. +- The Reference Model Contract includes provenance, Abaqus version/source, units, coordinate system, tolerance, reference_csv_schema_version, and reference_csv_files. +- An absent `metadata.json` is allowed and does not change readiness. A present file is read-only supplementary evidence; any conflict with the contract or stored artifacts remains visible as an upstream issue. - Missing required Abaqus reference CSV files keep the model at `needs-reference-artifacts`. ## Handoff diff --git a/AGENTS.md b/AGENTS.md index ea7d208..f9cdbcd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,6 +21,7 @@ - 공식 solver output은 HDF5 `results.h5`이다. - reference 결과는 FESA와 같은 Abaqus `.inp` 모델을 Abaqus로 해석해 생성한 CSV 파일이다. - reference artifact의 정확한 경로와 파일명은 기능별 reference model contract를 따른다. 신규 모델은 `reference//_*.csv` canonical 이름을 사용한다. +- `metadata.json`은 선택 reference artifact다. 파일이 없어도 bundle을 불완전하다고 판정하지 않으며, 필수 provenance, units, coordinate system, step/frame, schema, tolerance 정보는 승인된 기능별 reference model contract에 기록한다. 파일이 존재하면 read-only 보조 자료로 inventory하고 계약과 일치하는지 확인한다. - 승인된 B33 baseline은 예외적으로 `reference/cantilever beam/`의 기존 space-containing 파일명을 read-only legacy alias로 사용한다. - CSV는 FESA 공식 output이 아니며, FESA HDF5에서 추출한 deterministic CSV view는 비교 디버깅/검토용 보조 artifact로만 둔다. diff --git a/docs/ADR.md b/docs/ADR.md index dcf976d..1d07052 100644 --- a/docs/ADR.md +++ b/docs/ADR.md @@ -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: 구형 단일 검증 진입점 계약을 폐기한다 diff --git a/docs/SOLVER_AGENT_DESIGN.md b/docs/SOLVER_AGENT_DESIGN.md index 64a4043..d931cd2 100644 --- a/docs/SOLVER_AGENT_DESIGN.md +++ b/docs/SOLVER_AGENT_DESIGN.md @@ -9,7 +9,7 @@ - 기능 요구조건, 이론 정식화, 코드 구현, 검증, 배포 역할을 분리한다. - 실행 가능성만으로 성공을 판단하지 않고, 레퍼런스 결과와 물리량을 비교해 기능 완료를 판정한다. - 테스트는 구현 전에 준비한다. 개발 대상 솔버 테스트와 레퍼런스 솔버 결과 비교 테스트를 함께 사용한다. -- Abaqus나 Nastran을 Agent가 직접 실행하지 않는다. `reference//`에 저장된 `model.inp`, `metadata.json`, Abaqus reference CSV files를 검증 기준으로 사용한다. +- Abaqus나 Nastran을 Agent가 직접 실행하지 않는다. `reference//`에 저장된 `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.inp - metadata.json + metadata.json # optional _displacements.csv _reactions.csv _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 통과를 기준으로 한다. diff --git a/docs/SOLVER_SKILL_DESIGN.md b/docs/SOLVER_SKILL_DESIGN.md index 846f880..518980b 100644 --- a/docs/SOLVER_SKILL_DESIGN.md +++ b/docs/SOLVER_SKILL_DESIGN.md @@ -89,7 +89,7 @@ Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로 - smoke, analytical, patch test, benchmark, regression, negative/invalid-input 모델을 구분한다. - `reference//` artifact bundle 계약을 정의한다. -- `model.inp`, `metadata.json`, `_displacements.csv`, `_reactions.csv`, `_internalforces.csv`, `_stresses.csv`를 기준 artifact로 둔다. +- `model.inp`와 요구된 `_displacements.csv`, `_reactions.csv`, `_internalforces.csv`, `_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를 의미하지 않는다. diff --git a/docs/archive/ProjectInitialPlanNote.md b/docs/archive/ProjectInitialPlanNote.md index 9b7fcaf..e7fac29 100644 --- a/docs/archive/ProjectInitialPlanNote.md +++ b/docs/archive/ProjectInitialPlanNote.md @@ -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 diff --git a/docs/io-definitions/linear-static-3d-euler-beam-io.md b/docs/io-definitions/linear-static-3d-euler-beam-io.md index 91b8ba4..dc34a5f 100644 --- a/docs/io-definitions/linear-static-3d-euler-beam-io.md +++ b/docs/io-definitions/linear-static-3d-euler-beam-io.md @@ -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 diff --git a/docs/io-definitions/linear-static-mitc4-shell-io.md b/docs/io-definitions/linear-static-mitc4-shell-io.md index ae5fdf3..c82e30d 100644 --- a/docs/io-definitions/linear-static-mitc4-shell-io.md +++ b/docs/io-definitions/linear-static-mitc4-shell-io.md @@ -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// model.inp - metadata.json _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. `` is a Reference Model-owned schema variable, not an unresolved filename placeholder in this I/O contract. diff --git a/docs/reference-models/README.md b/docs/reference-models/README.md index 2d49e6b..9469f79 100644 --- a/docs/reference-models/README.md +++ b/docs/reference-models/README.md @@ -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//` 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 | | --- | --- | --- | --- | --- | -| | smoke | | draft | model.inp, metadata.json, required Abaqus reference CSV files | -| | analytical | | draft | model.inp, metadata.json, required Abaqus reference CSV files | -| | patch test | | draft | model.inp, metadata.json, required Abaqus reference CSV files | -| | benchmark | | draft | model.inp, metadata.json, required Abaqus reference CSV files | -| | regression | | draft | model.inp, metadata.json, required Abaqus reference CSV files | -| | negative/invalid-input | | draft | model.inp, metadata.json | +| | smoke | | draft | model.inp, required Abaqus reference CSV files | +| | analytical | | draft | model.inp, required Abaqus reference CSV files | +| | patch test | | draft | model.inp, required Abaqus reference CSV files | +| | benchmark | | draft | model.inp, required Abaqus reference CSV files | +| | regression | | draft | model.inp, required Abaqus reference CSV files | +| | negative/invalid-input | | draft | model.inp | ## Model Record @@ -90,7 +90,7 @@ Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반 reference/ / model.inp - metadata.json + metadata.json # optional _displacements.csv _reactions.csv _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. - `_displacements.csv`: required when nodal displacement is a verification quantity. - `_reactions.csv`: required when constrained DOF reactions or global equilibrium are verification quantities. - `_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. - `_strains.csv`: required when strain is part of the acceptance criteria. - `_energy_or_residual.csv`: required when energy balance, residual, or convergence data is part of the acceptance criteria. - `_.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//` 구조와 필수 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로 추적되어야 한다. diff --git a/docs/reference-models/linear-static-3d-euler-beam-reference-models.md b/docs/reference-models/linear-static-3d-euler-beam-reference-models.md index 819a441..5015db9 100644 --- a/docs/reference-models/linear-static-3d-euler-beam-reference-models.md +++ b/docs/reference-models/linear-static-3d-euler-beam-reference-models.md @@ -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.inp - metadata.json + metadata.json # optional _displacements.csv _reactions.csv _internalforces.csv @@ -215,14 +215,15 @@ reference/ README.md ``` -CSV names are canonical `_*.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 `_*.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 diff --git a/docs/reference-verifications/README.md b/docs/reference-verifications/README.md index a7ebf5d..a7da917 100644 --- a/docs/reference-verifications/README.md +++ b/docs/reference-verifications/README.md @@ -10,7 +10,7 @@ Reference Verification Agent는 Build/Test Executor Agent 통과 후 generated s 수행한다: - `reference//` 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 문서가 요구할 때만 `_strains.csv`, `_energy_or_residual.csv`, 또는 `_.csv`를 추가 비교한다. @@ -38,7 +38,6 @@ ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT `ARTIFACT CHECK`에서 다음 항목이 없으면 비교를 시작하지 않는다. -- `metadata.json` - `model.inp` - generated solver `results.h5` - `reference//_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// | present | missing | | | reference_input | reference//model.inp | present | missing | | -| metadata | reference//metadata.json | present | missing | | +| optional_metadata | reference//metadata.json | present / absent-allowed / conflict | | | reference_displacements_csv | reference//_displacements.csv | present | missing | | | reference_reactions_csv | reference//_reactions.csv | present | missing | | | reference_internalforces_csv | reference//_internalforces.csv | present | missing | | @@ -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//_*.csv`를 수정하지 않는다. +- reference artifact는 읽기 전용이다. `model.inp`, 존재하는 `metadata.json`, `reference//_*.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이 일치할 때만 비교한다. diff --git a/docs/reference-verifications/linear-static-3d-euler-beam-reference-verification.md b/docs/reference-verifications/linear-static-3d-euler-beam-reference-verification.md index d20ae17..d258bdb 100644 --- a/docs/reference-verifications/linear-static-3d-euler-beam-reference-verification.md +++ b/docs/reference-verifications/linear-static-3d-euler-beam-reference-verification.md @@ -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. | diff --git a/docs/releases/linear-static-3d-euler-beam-release.md b/docs/releases/linear-static-3d-euler-beam-release.md index e3309e9..4d78eb5 100644 --- a/docs/releases/linear-static-3d-euler-beam-release.md +++ b/docs/releases/linear-static-3d-euler-beam-release.md @@ -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 | diff --git a/docs/requirements/README.md b/docs/requirements/README.md index ec66aec..87f27fd 100644 --- a/docs/requirements/README.md +++ b/docs/requirements/README.md @@ -77,11 +77,12 @@ Requirement Agent는 솔버 기능 요청을 검증 가능한 요구조건으로 Expected location: `reference//` - `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 - `_displacements.csv`: required | not-applicable - `_reactions.csv`: required | not-applicable - `_internalforces.csv`: required | not-applicable - `_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 diff --git a/docs/requirements/linear-static-3d-euler-beam.md b/docs/requirements/linear-static-3d-euler-beam.md index 4c26d42..ed1999d 100644 --- a/docs/requirements/linear-static-3d-euler-beam.md +++ b/docs/requirements/linear-static-3d-euler-beam.md @@ -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 | diff --git a/docs/requirements/linear-static-mitc4-shell.md b/docs/requirements/linear-static-mitc4-shell.md index 157d46c..7b30554 100644 --- a/docs/requirements/linear-static-mitc4-shell.md +++ b/docs/requirements/linear-static-mitc4-shell.md @@ -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 `_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 `_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. diff --git a/docs/superpowers/plans/2026-06-11-reference-csv-comparison-contract.md b/docs/superpowers/plans/2026-06-11-reference-csv-comparison-contract.md index 986912f..2c938d1 100644 --- a/docs/superpowers/plans/2026-06-11-reference-csv-comparison-contract.md +++ b/docs/superpowers/plans/2026-06-11-reference-csv-comparison-contract.md @@ -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. diff --git a/docs/superpowers/specs/2026-08-08-linear-static-3d-euler-beam-design.md b/docs/superpowers/specs/2026-08-08-linear-static-3d-euler-beam-design.md index 8996c3b..fce7fa0 100644 --- a/docs/superpowers/specs/2026-08-08-linear-static-3d-euler-beam-design.md +++ b/docs/superpowers/specs/2026-08-08-linear-static-3d-euler-beam-design.md @@ -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를 생성·수정하지 않는다. diff --git a/phases/linear-static-3d-euler-beam/step26.md b/phases/linear-static-3d-euler-beam/step26.md index 3ed1d94..0a80d8f 100644 --- a/phases/linear-static-3d-euler-beam/step26.md +++ b/phases/linear-static-3d-euler-beam/step26.md @@ -34,8 +34,9 @@ Artifact check: - exact legacy 네 파일 존재, input `TYPE=B33`, expected CAE CSV headers, unique row keys, finite values를 검사한다. -- 이 bundle은 승인된 예외이므로 `metadata.json`, `README.md`, stress CSV 부재만으로 - 차단하지 않는다. Contract에서 provenance/units/schema/stress N/A를 확인한다. +- `metadata.json` 부재는 프로젝트 전역 정책에 따라 허용한다. 이 bundle의 `README.md`와 + stress CSV 부재는 승인된 legacy 예외이므로 차단하지 않는다. Contract에서 + provenance/units/schema/stress N/A를 확인한다. - generated HDF5 schema/version/units/coordinate/step-frame/source identity를 검사한다. Comparison: diff --git a/phases/linear-static-3d-euler-beam/step5.md b/phases/linear-static-3d-euler-beam/step5.md index 0e1512b..4f90b12 100644 --- a/phases/linear-static-3d-euler-beam/step5.md +++ b/phases/linear-static-3d-euler-beam/step5.md @@ -35,9 +35,11 @@ Metadata status는 `ready-for-implementation-planning`으로 둔다. `Abaqus/CAE Learning Edition 2024`, SI, `Step-1`, increment 1/time 1.0을 기록한다. - exact legacy paths 네 개를 inventory에 기록하고 B33 element type, expected header, unique row key, finite value artifact check를 요구한다. -- 이 legacy bundle에 한해서 `metadata.json`, `README.md`, stress CSV가 N/A이며 설계와 - 이 contract가 provenance/schema/tolerance/stress 사유를 대신 기록한다고 명시한다. -- 이후 reference model에는 canonical file names, metadata.json, README.md를 요구한다. +- `metadata.json` 부재는 프로젝트 전역 선택-artifact 정책에 따라 허용하고, 이 legacy + bundle에 한해서 `README.md`와 stress CSV가 N/A임을 명시한다. 설계와 이 contract가 + provenance/schema/tolerance/stress 사유를 기록한다. +- 이후 reference model에는 canonical file names와 `README.md`를 요구한다. + `metadata.json`이 존재하면 read-only로 contract와 대조한다. - displacement, reaction, section resultant coverage와 HDF5 dataset/CSV/component/tolerance를 연결하는 Coverage Matrix를 작성한다. Stress comparison은 N/A지만 output unit/analytical verification을 연결한다.