docs: make reference metadata optional

2026-08-12 02:22:01 +09:00
parent f28dbd7e42
commit 2bd297d84b
24 changed files with 127 additions and 95 deletions
@@ -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
 - <model-id>_displacements.csv
 - <model-id>_reactions.csv
 - <model-id>_internalforces.csv
@@ -58,6 +57,7 @@ Required reference bundle files:
 - README.md

 Optional reference bundle files:
+- metadata.json
 - <model-id>_strains.csv
 - <model-id>_energy_or_residual.csv
 - <model-id>_<quantity>.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/<model-id>/ 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: <model-id>_displacements.csv, <model-id>_reactions.csv, <model-id>_internalforces.csv, <model-id>_stresses.csv, and optional <model-id>_strains.csv or <model-id>_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.

@@ -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, <model-id>_displacements.csv, <model-id>_reactions.csv, <model-id>_internalforces.csv, <model-id>_stresses.csv, or any stored reference artifact.
+- Do not modify model.inp, any present metadata.json, <model-id>_displacements.csv, <model-id>_reactions.csv, <model-id>_internalforces.csv, <model-id>_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/<feature-id>-io.md.
 5. Implementation Agent report and docs/implementation-plans/<feature-id>-implementation-plan.md.
 6. Generated solver result HDF5, normally `results.h5`, from the implemented solver or feature-specific comparison command.
-7. Stored reference/<model-id>/ artifacts, including metadata.json and Abaqus reference CSV files.
+7. Stored reference/<model-id>/ 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/<model-id>/<model-id>_displacements.csv, reference/<model-id>/<model-id>_reactions.csv, reference/<model-id>/<model-id>_internalforces.csv, reference/<model-id>/<model-id>_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/<model-id>/<model-id>_displacements.csv, reference/<model-id>/<model-id>_reactions.csv, reference/<model-id>/<model-id>_internalforces.csv, reference/<model-id>/<model-id>_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.
@@ -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, <model-id>_displacements.csv, <model-id>_reactions.csv, <model-id>_internalforces.csv, <model-id>_stresses.csv, or an explicit N/A reason.
+10. Reference artifact requirements: model.inp, required <model-id>_displacements.csv, <model-id>_reactions.csv, <model-id>_internalforces.csv, <model-id>_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.
@@ -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/<model-id>/<model-id>_displacements.csv`, `reference/<model-id>/<model-id>_reactions.csv`, `reference/<model-id>/<model-id>_internalforces.csv`, `reference/<model-id>/<model-id>_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/<model-id>/<model-id>_displacements.csv`, `reference/<model-id>/<model-id>_reactions.csv`, `reference/<model-id>/<model-id>_internalforces.csv`, `reference/<model-id>/<model-id>_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

@@ -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/<model-id>/` artifact bundle requirements.
-5. Require `model.inp`, `metadata.json`, `<model-id>_displacements.csv`, `<model-id>_reactions.csv`, `<model-id>_internalforces.csv`, `<model-id>_stresses.csv`, and `README.md` unless explicitly not applicable.
+5. Require `model.inp`, the applicable `<model-id>_displacements.csv`, `<model-id>_reactions.csv`, `<model-id>_internalforces.csv`, `<model-id>_stresses.csv`, and `README.md` unless explicitly not applicable. Treat `metadata.json` as optional.
 6. Define optional `<model-id>_strains.csv`, `<model-id>_energy_or_residual.csv`, and `<model-id>_<quantity>.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/<feature-id>-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/<feature-id>-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