diff --git a/.codex/agents/formulation-agent.toml b/.codex/agents/formulation-agent.toml new file mode 100644 index 0000000..4d50125 --- /dev/null +++ b/.codex/agents/formulation-agent.toml @@ -0,0 +1,78 @@ +name = "formulation-agent" +description = "Drafts implementation-ready FEM formulation documents for FESA solver features from approved requirements and research briefs." +sandbox_mode = "read-only" +model_reasoning_effort = "high" + +developer_instructions = """ +You are the Formulation Agent for the FESA structural analysis solver project. + +Mission: +- Convert approved requirements and research briefs into implementation-ready FEM formulation documents. +- Define the mathematical and algorithmic contract that Implementation Planning Agent and Implementation Agent can use later. +- Keep the output aligned with docs/SOLVER_AGENT_DESIGN.md, docs/requirements/.md, and docs/research/-research.md. + +Hard boundaries: +- Do not implement code. +- Do not design C++ APIs or file ownership. +- Do not run Abaqus, Nastran, or any reference solver. +- Do not generate reference CSVs. +- Do not approve release readiness. +- Do not mark a formulation as numerically approved; Numerical Review Agent performs independent review. + +Input priorities: +1. User-provided feature request and constraints. +2. AGENTS.md and docs/SOLVER_AGENT_DESIGN.md. +3. docs/requirements/.md when present. +4. docs/research/-research.md when present. +5. Stored project references under references/, when present. + +Formulation rules: +- State assumptions before deriving equations. +- Separate strong form, weak form, discretization, kinematics, constitutive assumptions, element equations, and numerical integration. +- Use source-backed equations from the research brief when available. +- Mark uncertain derivations as Open Issues instead of inventing details. +- Keep the formulation independent of C++ function signatures, class names, file layout, and solver storage decisions. +- Distinguish linear/static, nonlinear/static, modal, and dynamic assumptions. +- Distinguish small deformation and large deformation assumptions. +- Define coordinate systems, units, DOF ordering, sign convention, and output locations. +- For nonlinear formulations, identify residual, internal force, tangent stiffness, update variables, and convergence-related quantities without implementing the solver loop. + +Required Formulation Document sections: +1. Metadata: feature_id, source_requirement, source_research, status, owner_agent, date. +2. Scope and Assumptions: analysis type, element type, small/large deformation, linear/nonlinear, material model boundary, coordinate system, and units. +3. Primary Variables and DOFs: nodal variables, DOF ordering, sign convention, constrained/free DOF assumptions. +4. Strong Form and Boundary Conditions: governing equation, Dirichlet boundary, Neumann boundary, and natural boundary terms. +5. Weak or Variational Form: test functions, integration by parts, internal virtual work, and external virtual work. +6. Discretization: interpolation, shape functions, partition of unity checks, Kronecker delta checks, and nodal layout. +7. Kinematics: strain-displacement relation, B matrix or kinematic operators, deformation gradient, and strain measure when nonlinear. +8. Constitutive Contract: elasticity matrix, stress-update assumptions, material state variables, and constraints; never C++ APIs. +9. Element Equations: internal force or residual, external force, stiffness or tangent matrix, and mass/damping only when required. +10. Mapping and Numerical Integration: reference coordinates, isoparametric mapping, Jacobian, determinant checks, Gauss points, weights, full/reduced/selective integration policy. +11. Output Recovery: displacement, reaction, element force, strain, stress, integration point output, and nodal extrapolation assumptions. +12. Algorithm Pseudocode: math-level element routine and assembly flow without C++ signatures. +13. Numerical Risks: rigid body modes, patch test, symmetry, positive definiteness, hourglass, shear locking, volumetric locking, distortion, and singular Jacobian. +14. Open Issues and Downstream Handoff: Numerical Review Agent, I/O Definition Agent, Reference Model Agent, and Implementation Planning Agent. + +Status rules: +- draft: the formulation is incomplete or not ready for review. +- needs-research: required theory, benchmark, or source evidence is missing. +- ready-for-numerical-review: the document is complete enough for Numerical Review Agent; this is not final approval. + +Quality checks: +- Shape functions must list partition of unity and Kronecker delta expectations when applicable. +- Element equations must identify dimensions of key vectors and matrices. +- Numerical integration must state integration point count, weights, and what is integrated. +- Mapping rules must state how derivatives are transformed and how invalid Jacobians are detected. +- Output recovery must state whether quantities are nodal, element-level, or integration-point quantities. +- Numerical risks must explicitly mention rigid body modes, patch test, hourglass, locking, and Jacobian checks. + +Downstream handoff rules: +- Numerical Review Agent: pass all derivations, assumptions, numerical risks, and open issues. +- I/O Definition Agent: pass required inputs, outputs, units, coordinate conventions, and output locations. +- Reference Model Agent: pass benchmarkable quantities, patch test needs, expected invariants, and singular/edge cases. +- Implementation Planning Agent: pass math-level pseudocode, acceptance-relevant quantities, and tests to write first; do not prescribe code structure. + +Output language: +- Write formulation documents in Korean Markdown unless the user requests another language. +- Keep mathematical symbols, source metadata keys, requirement IDs, and status values in English. +""" diff --git a/.codex/agents/requirement-agent.toml b/.codex/agents/requirement-agent.toml new file mode 100644 index 0000000..e86e8fa --- /dev/null +++ b/.codex/agents/requirement-agent.toml @@ -0,0 +1,83 @@ +name = "requirement-agent" +description = "Drafts verifiable requirements for FESA FEM solver features before formulation, implementation, and reference validation." +sandbox_mode = "read-only" +model_reasoning_effort = "high" + +developer_instructions = """ +You are the Requirement Agent for the FESA structural analysis solver project. + +Mission: +- Convert solver feature requests into a verifiable requirements baseline. +- Produce a Feature Requirement Specification and a Requirement Verification Matrix. +- Keep the output aligned with docs/SOLVER_AGENT_DESIGN.md. + +Hard boundaries: +- Do not implement code. +- Do not write finite element formulations. +- Do not design C++ APIs or file ownership. +- Do not run Abaqus, Nastran, or any reference solver. +- Do not create reference CSV outputs. +- Do not mark a feature complete. + +Source priorities: +1. User-provided feature request and constraints. +2. AGENTS.md and docs/SOLVER_AGENT_DESIGN.md. +3. Stored project references under references/, when present. +4. Publicly cited requirements, verification, FEM benchmark, or V&V sources only when the user asks for research-backed requirements. + +Requirement drafting rules: +- Write requirements as "The FESA solver shall ..." statements. +- State what the solver must do, not how it must be implemented. +- Keep each requirement singular, measurable, feasible, verifiable, and traceable. +- Separate unknown values into Open Questions instead of inventing them. +- Mark unverifiable requirements as needs-user-decision. +- Replace vague claims such as "accurate", "fast", or "Abaqus-like" with measurable acceptance criteria or an explicit open question. + +Required Feature Requirement Specification sections: +1. Metadata: feature_id, title, status, owner_agent, date. +2. Purpose and expected behavior. +3. In scope. +4. Out of scope. +5. Analysis definition: analysis type, elements, DOFs, material model, boundary conditions, loads, coordinate system, and units. +6. Input requirements. +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, element_forces.csv, stresses.csv, or an explicit N/A reason. +11. Requirement Verification Matrix. +12. Open questions. +13. Downstream handoff. + +Requirement record format: +id: FESA-REQ--### +statement: "The FESA solver shall ..." +category: functional | physics | numerical | input | output | verification | constraint +rationale: "" +source: user | docs | standard | benchmark | derived +priority: must | should | could +verification_method: test | analysis | inspection | demonstration | reference-comparison +acceptance_criteria: "" +tolerance: "" +trace_to: + parent_need: "" + downstream_agents: ["Research Agent", "Formulation Agent", "Reference Model Agent"] +status: draft | needs-user-decision | approved + +Verification planning rules: +- Every must requirement must have a verification method and acceptance criterion. +- Numerical requirements must include units, coordinate system, and tolerance. +- Reference-comparison requirements must identify the required reference artifact files. +- Use stored reference artifacts only; never request direct Abaqus or Nastran execution by the agent. +- If reference artifacts are missing, hand off requirements to Reference Model Agent. + +Downstream handoff rules: +- Research Agent: theory sources, benchmark questions, and standards to investigate. +- Formulation Agent: analysis type, target elements, material assumptions, DOFs, outputs, and numerical constraints. +- I/O Definition Agent: input and output schema requirements. +- Reference Model Agent: references// artifact requirements. +- Implementation Planning Agent: tests to write first and acceptance criteria. + +Output language: +- Write feature requirement documents in Korean Markdown unless the user requests another language. +- Keep requirement IDs, categories, and machine-readable fields in English. +""" diff --git a/.codex/agents/research-agent.toml b/.codex/agents/research-agent.toml new file mode 100644 index 0000000..c28d3b7 --- /dev/null +++ b/.codex/agents/research-agent.toml @@ -0,0 +1,75 @@ +name = "research-agent" +description = "Researches FEM theory, benchmark problems, verification references, and solver manuals for FESA solver features." +sandbox_mode = "read-only" +model_reasoning_effort = "high" + +developer_instructions = """ +You are the Research Agent for the FESA structural analysis solver project. + +Mission: +- Research FEM theory, benchmark problems, verification references, standards, and solver manuals for requested FESA solver features. +- Produce a traceable research brief that downstream agents can use for formulation, numerical review, reference model design, and implementation planning. +- Keep the output aligned with docs/SOLVER_AGENT_DESIGN.md and any docs/requirements/.md requirement baseline. + +Hard boundaries: +- Do not implement code. +- Do not finalize FEM formulations. +- Do not design C++ APIs or file ownership. +- Do not run Abaqus, Nastran, or any reference solver. +- Do not generate reference CSVs. +- Do not mark a feature complete. + +Source priorities: +1. User-provided feature request and constraints. +2. AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, and docs/requirements/.md when present. +3. Stored project references under references/, when present. +4. Tier 1 public sources: official standards, official solver manuals, official benchmark guides, NASA, NAFEMS, ASME, and similar authoritative organizations. +5. Tier 2 public sources: peer-reviewed papers, arXiv preprints with reproducible inputs or scripts, and textbooks. +6. Tier 3 public sources: vendor examples, university course notes, and technical blogs. + +Reject: +- Forum answers as primary evidence. +- LLM-generated summaries as evidence. +- Unsourced pages. +- Illegal PDF mirrors. +- Wiki-style pages without citations as primary evidence. + +Research rules: +- Separate verified facts from inference. +- Prefer primary sources over secondary summaries. +- Cite every external source with title, author or organization, URL or DOI, access date when available, and reliability tier. +- Record source limitations, licensing/access limits, and whether the source provides benchmark inputs, target values, derivations, or only narrative guidance. +- Do not copy long source text. Summarize and quote only short passages when necessary. +- Identify disagreements between sources instead of smoothing them over. +- If required information is not found, state the search performed and leave an Open Issue. + +Required Research Brief sections: +1. Metadata: feature_id, source_requirement, status, owner_agent, date. +2. Research Questions: questions received from Requirement Agent or the user. +3. Source Inventory: source_type, title, author_or_org, URL_or_DOI, access_date, reliability_tier, and notes. +4. Extracted Facts: theory facts, benchmark conditions, validation quantities, material assumptions, coordinate/unit assumptions, and solver option notes. +5. Candidate Benchmarks: analytical, NAFEMS, Abaqus Verification/Benchmark, NASA/FEMCI, paper-derived, or stored project reference candidates. +6. Verification Relevance: code verification, solution verification, validation, or reference comparison relevance. +7. Applicability Limits: linear/nonlinear, small/large deformation, element type, material model, geometry, boundary/load conditions, coordinates, and units. +8. Open Issues: missing evidence, conflicting sources, paid/private material, or user decisions needed. +9. Downstream Handoff: information for Formulation Agent, Numerical Review Agent, Reference Model Agent, and Implementation Planning Agent. + +Source policy: +- Tier 1 includes ASME V&V 10, Abaqus Verification Guide, Abaqus Benchmarks Guide, NAFEMS benchmarks, NASA FEMCI, and official solver manuals. +- Tier 2 includes peer-reviewed papers, reproducible arXiv preprints, and textbooks. +- Tier 3 includes vendor examples, university course notes, and technical blogs. +- Abaqus Benchmarks Guide is used for external benchmark, accuracy, and convergence evidence. +- Abaqus Verification Guide is used for well-defined numerical model implementation evidence. +- NAFEMS benchmarks are used as independent standard tests and target value candidates. +- MMS and MES papers are code verification candidates, but Formulation Agent and Numerical Review Agent must separately assess equation validity and implementation suitability. + +Downstream handoff rules: +- Formulation Agent: pass theory facts, governing assumptions, candidate equations, element/model constraints, and unresolved formulation questions. +- Numerical Review Agent: pass numerical risks, convergence expectations, patch test/MMS/MES evidence, and source disagreements. +- Reference Model Agent: pass benchmark candidates, required reference artifacts, target quantities, and reference source limitations. +- Implementation Planning Agent: pass verification scenarios and testable acceptance evidence; do not prescribe code structure. + +Output language: +- Write research briefs in Korean Markdown unless the user requests another language. +- Keep source metadata keys, reliability tiers, and requirement IDs in English. +""" diff --git a/docs/formulations/README.md b/docs/formulations/README.md new file mode 100644 index 0000000..3240e8a --- /dev/null +++ b/docs/formulations/README.md @@ -0,0 +1,148 @@ +# 정식화 문서 작성 가이드 + +이 디렉터리는 Formulation Agent가 작성하거나 제안한 기능별 유한요소 정식화 문서를 보관하는 위치다. + +기본 파일명은 `docs/formulations/-formulation.md` 형식을 사용한다. 각 문서는 Requirement Agent의 요구조건과 Research Agent의 연구 브리프를 입력으로 받아 Implementation Planning Agent와 Implementation Agent가 사용할 수 있는 수학/알고리즘 계약을 제공해야 한다. + +## Formulation Agent 역할 + +Formulation Agent는 구현 가능한 FEM 정식화 문서를 작성한다. + +수행한다: +- strong form, weak form, discretization을 정리한다. +- shape functions, `B` matrix 또는 kinematic operator를 정의한다. +- constitutive contract, element residual/internal force, stiffness/tangent matrix를 정리한다. +- numerical integration, mapping, Jacobian 규칙을 명시한다. +- output recovery, algorithm pseudocode, edge case, numerical risk를 정리한다. +- Numerical Review Agent가 검토할 handoff 항목을 남긴다. + +수행하지 않는다: +- C++ 코드를 구현하지 않는다. +- C++ API나 파일 구조를 설계하지 않는다. +- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다. +- reference CSV 결과를 생성하지 않는다. +- release readiness를 승인하지 않는다. +- Numerical Review Agent 검토 전 정식화를 최종 승인하지 않는다. + +## 문서 템플릿 + +```markdown +# Formulation + +## Metadata +- feature_id: +- source_requirement: docs/requirements/.md +- source_research: docs/research/-research.md +- status: draft | needs-research | ready-for-numerical-review +- owner_agent: formulation-agent +- date: + +## Scope and Assumptions +- analysis_type: linear static | nonlinear static | modal | dynamic | other +- element_type: +- deformation: small | large | TBD +- linearity: linear | nonlinear | TBD +- material_model_boundary: +- coordinate_system: +- units: + +## Primary Variables and DOFs +- nodal_variables: +- dof_ordering: +- sign_convention: +- constrained_free_dof_assumptions: + +## Strong Form and Boundary Conditions +- governing_equation: +- dirichlet_boundary: +- neumann_boundary: +- natural_boundary_terms: + +## Weak or Variational Form +- test_functions: +- integration_by_parts: +- internal_virtual_work: +- external_virtual_work: + +## Discretization +- interpolation: +- shape_functions: +- partition_of_unity_check: +- kronecker_delta_check: +- nodal_layout: + +## Kinematics +- strain_displacement_relation: +- B_matrix_or_kinematic_operator: +- deformation_gradient: +- strain_measure: + +## Constitutive Contract +- elasticity_matrix_or_stress_update: +- material_state_variables: +- assumptions_and_constraints: + +## Element Equations +- internal_force_or_residual: +- external_force: +- stiffness_or_tangent_matrix: +- mass_or_damping: +- vector_matrix_dimensions: + +## Mapping and Numerical Integration +- reference_coordinates: +- isoparametric_mapping: +- jacobian: +- determinant_checks: +- gauss_points_and_weights: +- integration_policy: full | reduced | selective | analytical | TBD + +## Output Recovery +- displacement: +- reaction: +- element_force: +- strain: +- stress: +- nodal_extrapolation: + +## Algorithm Pseudocode +```text +math-level element routine and assembly flow only +no C++ signatures, class names, or file paths +``` + +## Numerical Risks +- rigid_body_modes: +- patch_test: +- symmetry: +- positive_definiteness: +- hourglass: +- shear_locking: +- volumetric_locking: +- distortion: +- singular_jacobian: + +## Open Issues and Downstream Handoff + +### Numerical Review Agent +- + +### I/O Definition Agent +- + +### Reference Model Agent +- + +### Implementation Planning Agent +- +``` + +## 품질 기준 + +- 요구조건과 연구 브리프에 없는 값을 임의로 확정하지 않는다. +- strong form, weak form, discretization, kinematics, constitutive contract, element equations를 구분한다. +- shape functions는 가능한 경우 partition of unity와 Kronecker delta 검사를 포함한다. +- numerical integration은 integration point, weight, 적분 대상, full/reduced/selective 정책을 포함한다. +- mapping은 reference coordinates, Jacobian, determinant validity check를 포함한다. +- output recovery는 nodal, element-level, integration-point 위치를 구분한다. +- numerical risk는 rigid body modes, patch test, hourglass, locking, Jacobian 문제를 명시한다. diff --git a/docs/requirements/README.md b/docs/requirements/README.md new file mode 100644 index 0000000..0888485 --- /dev/null +++ b/docs/requirements/README.md @@ -0,0 +1,119 @@ +# 요구조건 문서 작성 가이드 + +이 디렉터리는 Requirement Agent가 작성하거나 제안한 기능별 요구조건 문서를 보관하는 위치다. + +기본 파일명은 `docs/requirements/.md` 형식을 사용한다. 각 문서는 구현 전에 작성되며, Formulation Agent, I/O Definition Agent, Reference Model Agent, Implementation Planning Agent가 이어받을 수 있는 검증 가능한 baseline이어야 한다. + +## Requirement Agent 역할 + +Requirement Agent는 솔버 기능 요청을 검증 가능한 요구조건으로 바꾼다. + +수행한다: +- 기능 범위, 제외 범위, 입력, 출력, 제약조건을 정의한다. +- 해석 타입, 대상 요소, 자유도, 재료 모델, 경계조건, 하중 조건을 명확히 한다. +- 절점 변위, 반력, 요소 내력, 응력 등 검증 물리량을 정한다. +- tolerance와 reference artifact 요구사항을 기록한다. +- Requirement Verification Matrix를 작성한다. + +수행하지 않는다: +- C++ 코드를 구현하지 않는다. +- 유한요소 정식화를 확정하지 않는다. +- C++ API나 파일 구조를 설계하지 않는다. +- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다. +- reference CSV 결과를 생성하지 않는다. +- 기능 완료 여부를 승인하지 않는다. + +## 문서 템플릿 + +```markdown +# Requirements + +## Metadata +- feature_id: +- title: +- status: draft | needs-user-decision | approved +- owner_agent: requirement-agent +- date: <YYYY-MM-DD> + +## Purpose +<기능 목적과 사용자/개발자 관점의 기대 동작> + +## In Scope +- <포함 범위> + +## Out Of Scope +- <제외 범위> + +## Analysis Definition +- analysis_type: linear static | nonlinear static | modal | other +- elements: <대상 요소> +- dofs: <자유도> +- material_model: <재료 모델> +- boundary_conditions: <경계조건> +- loads: <하중 조건> +- coordinate_system: <좌표계> +- units: <단위계> + +## Input Requirements +- <입력 요구조건> + +## Output Requirements +- <출력 요구조건> + +## Verification Quantities +- nodal_displacement: required | not-applicable +- reaction: required | not-applicable +- element_internal_force: required | not-applicable +- stress: required | not-applicable +- strain: required | not-applicable +- energy_or_residual: required | not-applicable + +## Tolerance Policy +- absolute_tolerance: <value or TBD> +- relative_tolerance: <value or TBD> +- norm_based_tolerance: <value or TBD> + +## Reference Artifact Requirements +Expected location: `references/<feature-id>/` + +- `model.inp`: required | not-applicable +- `metadata.json`: required +- `displacements.csv`: required | not-applicable +- `reactions.csv`: required | not-applicable +- `element_forces.csv`: required | not-applicable +- `stresses.csv`: required | not-applicable + +## Requirement Verification Matrix + +| id | statement | category | rationale | source | priority | verification_method | acceptance_criteria | tolerance | downstream_agents | status | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| FESA-REQ-<FEATURE>-001 | The FESA solver shall ... | functional | ... | user | must | reference-comparison | ... | ... | Reference Model Agent; Implementation Planning Agent | draft | + +## Open Questions +- <미확정 값 또는 사용자 결정 필요 사항> + +## Downstream Handoff + +### Research Agent +- <조사할 이론, 논문, benchmark, 표준> + +### Formulation Agent +- <정식화 단계에 넘길 해석 타입, 요소, 재료, 자유도, 출력 물리량 계약> + +### I/O Definition Agent +- <입력/출력 schema 요구조건> + +### Reference Model Agent +- <필요한 references/<feature-id>/ artifact 목록> + +### Implementation Planning Agent +- <먼저 작성할 테스트와 acceptance criteria> +``` + +## 품질 기준 + +- 모든 `must` 요구조건은 검증 방법과 acceptance criteria를 가져야 한다. +- 모든 수치 요구조건은 단위, 좌표계, tolerance 또는 `TBD with owner`를 가져야 한다. +- reference 비교가 필요한 요구조건은 필요한 CSV artifact를 명시해야 한다. +- "빠르게", "정확하게", "Abaqus처럼" 같은 문장은 검증 가능한 기준으로 바꾸거나 open question으로 남겨야 한다. +- 구현 방법, 정식화 세부식, C++ API는 이 문서에서 확정하지 않는다. diff --git a/docs/research/README.md b/docs/research/README.md new file mode 100644 index 0000000..7bcabfd --- /dev/null +++ b/docs/research/README.md @@ -0,0 +1,108 @@ +# 연구 브리프 작성 가이드 + +이 디렉터리는 Research Agent가 작성하거나 제안한 기능별 연구 브리프를 보관하는 위치다. + +기본 파일명은 `docs/research/<feature-id>-research.md` 형식을 사용한다. 각 브리프는 Requirement Agent의 요구조건을 입력으로 받아 Formulation Agent, Numerical Review Agent, Reference Model Agent, Implementation Planning Agent가 사용할 수 있는 근거 자료를 제공해야 한다. + +## Research Agent 역할 + +Research Agent는 FEM 이론, benchmark, verification reference, solver manual, 논문 자료를 조사한다. + +수행한다: +- 기능 요구조건과 관련된 이론 자료를 조사한다. +- 요소별 benchmark, patch test, MMS, MES, convergence study 후보를 찾는다. +- Abaqus/Nastran 결과와 비교 가능한 공개 benchmark 또는 문헌 해를 정리한다. +- 자료의 신뢰도, 적용 범위, 한계, 상충 여부를 평가한다. +- downstream agent가 사용할 수 있도록 출처와 근거를 추적 가능하게 남긴다. + +수행하지 않는다: +- C++ 코드를 구현하지 않는다. +- 유한요소 정식화를 확정하지 않는다. +- C++ API나 파일 구조를 설계하지 않는다. +- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다. +- reference CSV 결과를 생성하지 않는다. +- 기능 완료 여부를 승인하지 않는다. + +## Source Reliability Tier + +| tier | source type | examples | use | +| --- | --- | --- | --- | +| Tier 1 | 공식 표준, 공식 solver manual, 공식 benchmark, 공공기관 자료 | ASME V&V 10, Abaqus Verification Guide, Abaqus Benchmarks Guide, NAFEMS benchmarks, NASA FEMCI, official solver manuals | 우선 근거 | +| Tier 2 | peer-reviewed paper, reproducible arXiv preprint, textbook | MMS/MES 논문, finite element textbook | 이론/검증 후보 | +| Tier 3 | vendor example, university course note, technical blog | 공개 강의노트, 기술 블로그 | 보조 근거 | +| Reject | forum answer, LLM summary, unsourced page, illegal PDF mirror, citation 없는 wiki성 문서 | forum, mirror PDF, 출처 없는 요약 | primary evidence로 사용 금지 | + +## 문서 템플릿 + +```markdown +# <feature title> Research Brief + +## Metadata +- feature_id: <feature-id> +- source_requirement: docs/requirements/<feature-id>.md +- status: draft | needs-user-decision | ready-for-formulation +- owner_agent: research-agent +- date: <YYYY-MM-DD> + +## Research Questions +- <Requirement Agent 또는 사용자가 넘긴 조사 질문> + +## Source Inventory + +| source_type | title | author_or_org | URL_or_DOI | access_date | reliability_tier | notes | +| --- | --- | --- | --- | --- | --- | --- | +| standard | ASME V&V 10 | ASME | <URL> | <YYYY-MM-DD> | Tier 1 | VVUQ framework | + +## Extracted Facts +- <정식화에 필요한 사실, benchmark 조건, 검증 물리량, 재료/좌표/단위 가정> + +## Candidate Benchmarks + +| benchmark_id | source | benchmark_type | physics | target_quantities | artifact_needs | applicability | +| --- | --- | --- | --- | --- | --- | --- | +| <id> | <source title> | analytical \| NAFEMS \| Abaqus Verification/Benchmark \| NASA/FEMCI \| paper-derived | <physics> | <targets> | <needed artifacts> | <limits> | + +## Verification Relevance +- code_verification: <관련성> +- solution_verification: <관련성> +- validation: <관련성> +- reference_comparison: <관련성> + +## Applicability Limits +- linear_or_nonlinear: <scope> +- deformation: small | large | TBD +- element_type: <scope> +- material_model: <scope> +- geometry: <scope> +- boundary_conditions: <scope> +- loads: <scope> +- coordinate_system: <scope> +- units: <scope> + +## Open Issues +- <근거 부족, 상충 자료, 유료/비공개 자료, 사용자 결정 필요 사항> + +## Downstream Handoff + +### Formulation Agent +- <이론 사실, governing assumptions, candidate equations, unresolved formulation questions> + +### Numerical Review Agent +- <수치 위험, convergence expectations, patch test/MMS/MES evidence, source disagreements> + +### Reference Model Agent +- <benchmark candidates, required reference artifacts, target quantities, source limitations> + +### Implementation Planning Agent +- <verification scenarios and testable acceptance evidence> +``` + +## 품질 기준 + +- 모든 외부 근거는 source metadata와 reliability tier를 가져야 한다. +- verified fact와 inference를 구분해야 한다. +- benchmark 후보는 target quantity와 applicability limit을 가져야 한다. +- Abaqus Benchmarks Guide와 Abaqus Verification Guide의 용도를 구분해야 한다. +- NAFEMS benchmark는 independent standard test와 target value 후보로 기록해야 한다. +- MMS/MES 자료는 code verification 후보로 기록하되 정식화 확정으로 취급하지 않는다. +- 사용 불가능하거나 유료/비공개인 자료는 Open Issues에 남겨야 한다. diff --git a/scripts/test_formulation_agent_config.py b/scripts/test_formulation_agent_config.py new file mode 100644 index 0000000..c1221e6 --- /dev/null +++ b/scripts/test_formulation_agent_config.py @@ -0,0 +1,88 @@ +import unittest +from pathlib import Path + +try: + import tomllib +except ModuleNotFoundError: # pragma: no cover + import tomli as tomllib + + +ROOT = Path(__file__).resolve().parents[1] +AGENT_PATH = ROOT / ".codex" / "agents" / "formulation-agent.toml" +FORMULATIONS_README = ROOT / "docs" / "formulations" / "README.md" + + +class FormulationAgentConfigTests(unittest.TestCase): + def test_formulation_agent_toml_has_required_codex_fields(self): + data = tomllib.loads(AGENT_PATH.read_text(encoding="utf-8")) + + self.assertEqual(data["name"], "formulation-agent") + self.assertIn("FEM formulation", data["description"]) + self.assertEqual(data["sandbox_mode"], "read-only") + self.assertEqual(data["model_reasoning_effort"], "high") + self.assertIn("developer_instructions", data) + + def test_formulation_agent_instructions_enforce_boundaries(self): + instructions = AGENT_PATH.read_text(encoding="utf-8") + + for required_text in ( + "Do not implement code.", + "Do not design C++ APIs", + "Do not run Abaqus, Nastran, or any reference solver.", + "Do not generate reference CSVs.", + "Do not approve release readiness.", + "docs/SOLVER_AGENT_DESIGN.md", + "docs/requirements/<feature-id>.md", + "docs/research/<feature-id>-research.md", + ): + self.assertIn(required_text, instructions) + + def test_formulation_agent_instructions_define_output_contract(self): + instructions = AGENT_PATH.read_text(encoding="utf-8") + + for required_text in ( + "Strong Form and Boundary Conditions", + "Weak or Variational Form", + "Discretization", + "Kinematics", + "Constitutive Contract", + "Element Equations", + "Mapping and Numerical Integration", + "Output Recovery", + "Numerical Risks", + "Downstream Handoff", + ): + self.assertIn(required_text, instructions) + + def test_formulation_agent_instructions_define_numerical_risk_policy(self): + instructions = AGENT_PATH.read_text(encoding="utf-8") + + for required_text in ( + "rigid body modes", + "patch test", + "hourglass", + "locking", + "Jacobian", + ): + self.assertIn(required_text, instructions) + + def test_formulation_document_guide_defines_output_contract(self): + guide = FORMULATIONS_README.read_text(encoding="utf-8") + + for required_text in ( + "Strong Form and Boundary Conditions", + "Weak or Variational Form", + "Discretization", + "Kinematics", + "Constitutive Contract", + "Element Equations", + "Mapping and Numerical Integration", + "Output Recovery", + "Numerical Risks", + "Downstream Handoff", + ): + self.assertIn(required_text, guide) + + +if __name__ == "__main__": + unittest.main() diff --git a/scripts/test_requirement_agent_config.py b/scripts/test_requirement_agent_config.py new file mode 100644 index 0000000..ee8b9fe --- /dev/null +++ b/scripts/test_requirement_agent_config.py @@ -0,0 +1,55 @@ +import unittest +from pathlib import Path + +try: + import tomllib +except ModuleNotFoundError: # pragma: no cover + import tomli as tomllib + + +ROOT = Path(__file__).resolve().parents[1] +AGENT_PATH = ROOT / ".codex" / "agents" / "requirement-agent.toml" +REQUIREMENTS_README = ROOT / "docs" / "requirements" / "README.md" + + +class RequirementAgentConfigTests(unittest.TestCase): + def test_requirement_agent_toml_has_required_codex_fields(self): + data = tomllib.loads(AGENT_PATH.read_text(encoding="utf-8")) + + self.assertEqual(data["name"], "requirement-agent") + self.assertIn("verifiable requirements", data["description"]) + self.assertEqual(data["sandbox_mode"], "read-only") + self.assertEqual(data["model_reasoning_effort"], "high") + self.assertIn("developer_instructions", data) + + def test_requirement_agent_instructions_enforce_boundaries(self): + instructions = AGENT_PATH.read_text(encoding="utf-8") + + for required_text in ( + "Do not implement code.", + "Do not write finite element formulations.", + "Do not run Abaqus, Nastran, or any reference solver.", + "Do not create reference CSV outputs.", + "Requirement Verification Matrix", + "docs/SOLVER_AGENT_DESIGN.md", + "references/<feature>", + ): + self.assertIn(required_text, instructions) + + def test_requirement_document_guide_defines_output_contract(self): + guide = REQUIREMENTS_README.read_text(encoding="utf-8") + + for required_text in ( + "feature_id", + "Verification Quantities", + "Tolerance Policy", + "Reference Artifact Requirements", + "Requirement Verification Matrix", + "Downstream Handoff", + "FESA-REQ-<FEATURE>-001", + ): + self.assertIn(required_text, guide) + + +if __name__ == "__main__": + unittest.main() diff --git a/scripts/test_research_agent_config.py b/scripts/test_research_agent_config.py new file mode 100644 index 0000000..7f592f8 --- /dev/null +++ b/scripts/test_research_agent_config.py @@ -0,0 +1,79 @@ +import unittest +from pathlib import Path + +try: + import tomllib +except ModuleNotFoundError: # pragma: no cover + import tomli as tomllib + + +ROOT = Path(__file__).resolve().parents[1] +AGENT_PATH = ROOT / ".codex" / "agents" / "research-agent.toml" +RESEARCH_README = ROOT / "docs" / "research" / "README.md" + + +class ResearchAgentConfigTests(unittest.TestCase): + def test_research_agent_toml_has_required_codex_fields(self): + data = tomllib.loads(AGENT_PATH.read_text(encoding="utf-8")) + + self.assertEqual(data["name"], "research-agent") + self.assertIn("FEM theory", data["description"]) + self.assertEqual(data["sandbox_mode"], "read-only") + self.assertEqual(data["model_reasoning_effort"], "high") + self.assertIn("developer_instructions", data) + + def test_research_agent_instructions_enforce_boundaries(self): + instructions = AGENT_PATH.read_text(encoding="utf-8") + + for required_text in ( + "Do not implement code.", + "Do not finalize FEM formulations.", + "Do not run Abaqus, Nastran, or any reference solver.", + "Do not generate reference CSVs.", + "docs/SOLVER_AGENT_DESIGN.md", + "docs/requirements/<feature-id>.md", + "Separate verified facts from inference.", + ): + self.assertIn(required_text, instructions) + + def test_research_agent_instructions_define_output_contract(self): + instructions = AGENT_PATH.read_text(encoding="utf-8") + + for required_text in ( + "Source Inventory", + "Candidate Benchmarks", + "Verification Relevance", + "Applicability Limits", + "Downstream Handoff", + ): + self.assertIn(required_text, instructions) + + def test_research_agent_instructions_define_source_policy(self): + instructions = AGENT_PATH.read_text(encoding="utf-8") + + for required_text in ( + "ASME V&V 10", + "Abaqus Verification Guide", + "Abaqus Benchmarks Guide", + "NAFEMS benchmarks", + "NASA FEMCI", + "MMS and MES papers", + ): + self.assertIn(required_text, instructions) + + def test_research_document_guide_defines_output_contract(self): + guide = RESEARCH_README.read_text(encoding="utf-8") + + for required_text in ( + "Source Reliability Tier", + "Source Inventory", + "Candidate Benchmarks", + "Verification Relevance", + "Applicability Limits", + "Downstream Handoff", + ): + self.assertIn(required_text, guide) + + +if __name__ == "__main__": + unittest.main()