modify documents

.codex/skills/fem-requirements-baseline/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: fem-requirements-baseline
+description: Use when baselining a finite-element structural solver feature before research, formulation, interface definition, or implementation planning.
+---
+
+# FEM Requirements Baseline
+
+Turn a structural-analysis solver request into a stable, verifiable contract without choosing downstream mathematics or implementation.
+
+## Inputs
+
+- Project instructions and architecture decisions
+- User request, constraints, exclusions, and existing feature artifacts
+- Applicable standards or compatibility commitments already selected by the project
+
+## Workflow
+
+1. Use the stable kebab-case `feature_id` and feature folder supplied by Coordinator; define purpose, scope, exclusions, analysis family, assumptions, units, coordinates, and compatibility boundary.
+2. Write atomic `FEM-REQ-<FEATURE>-###` shall-statements. Give each an observable acceptance criterion and verification method.
+3. Define logical verification quantities and required physical behavior. Preserve acceptance fixed by the user or an applicable standard; otherwise delegate quantity details, metric, scale, blocking class, and numerical tolerance to Numerical Review under `docs/TOLERANCE.md`.
+4. Build the requirement-verification matrix and classify open issues using the project workflow.
+
+Read [workflow and decision authority](references/workflow-and-decisions.md) when resolving ambiguity or deciding whether user input is critical. Use [evidence and handoff](references/evidence-and-handoff.md) for the returned envelope.
+
+## Output
+
+Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
+feature context, keep main reports concise, and link necessary owned details in the same feature folder.
+
+Create or revise `docs/<feature-id>/requirements.md` with metadata, scope, analysis definition, requirements, acceptance criteria, verification intent, compatibility boundary, matrix, open decisions, and handoff.
+
+## Evidence
+
+Every requirement traces to its source and an acceptance method. Numerical outputs state quantity, location, units, coordinates, and tolerance source when applicable.
+
+## Boundary
+
+Do not derive the formulation, select a numerical algorithm, design APIs or storage schemas, implement code, calibrate tolerances, or claim compatibility beyond the approved boundary. Route missing theory, reference evidence, or physical acceptance choices to their owning stage.

.codex/skills/fem-requirements-baseline/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "FEM Requirements Baseline"
+  short_description: "Baseline verifiable structural FEM requirements"
+  default_prompt: "Use $fem-requirements-baseline to define verifiable requirements for a structural FEM solver feature."

.codex/skills/fem-requirements-baseline/references/evidence-and-handoff.md

@@ -0,0 +1,26 @@
+# Evidence and Handoff Contract
+
+Use [Feature document management](../../../../docs/FEATURE_DOCUMENTATION.md) for concise main reports,
+linked details, and Coordinator's document inventory. Include main and required detail paths in evidence.
+
+Every stage returns one envelope:
+
+| Field | Required content |
+| --- | --- |
+| `feature_id` | Stable feature identifier |
+| `stage` | `requirements`, `research`, `formulation`, `numerical-review`, `io-definition`, `implementation-planning`, `implementation`, `correction`, `physics-evaluation`, or `release-readiness` |
+| `outcome` | `pass`, `return-upstream`, `retry`, `blocked-environment`, or `needs-user-decision` |
+| `next_owner` | Agent id, or YAML `null` |
+| `evidence_paths` | Repository-relative artifacts used or produced |
+| `evidence_digest` | Concise findings tied to requirement IDs |
+| `failure_classification` | `configure`, `compile`, `link`, `test`, `reference-comparison`, `harness`, `environment`, `upstream-contract`, `physics`, `evidence`, or YAML `null` |
+| `retry_key` | `<feature-id>\|<failing-gate>\|<classification>\|<contract-revision>`, or YAML `null` |
+| `attempt` | Coordinator-managed nonnegative attempt count for the retry key |
+| `escalation_class` | Critical-decision class, or YAML `null` |
+| `blocker` | Actionable blocker, or YAML `null` |
+
+Evidence records include, when applicable: source locator and access date; assumptions; command, exit code, duration, and relevant output; test identity and RED/GREEN result; artifact hash; comparison quantity, tolerance source, and decision; residual risk.
+
+Use repository-relative paths and stable identifiers. Distinguish observed facts, calculations, inferences, and decisions. Never report a pass when a required command failed, evidence is stale, or a blocking acceptance item is unresolved.
+
+Retry is bounded by the coordinator policy. A repeated normalized failure returns to its owning stage; it does not justify changing requirements, formulations, schemas, reference artifacts, or tolerances.

.codex/skills/fem-requirements-baseline/references/workflow-and-decisions.md

@@ -0,0 +1,33 @@
+# Workflow and Decision Authority
+
+## Authority order
+
+Use the first applicable authority:
+
+1. Approved feature contract and explicit user decisions
+2. Governing physics, mathematics, standards, and safety obligations
+3. Official documentation and verification cases for a project-selected reference product or format
+4. Repository architecture decisions, configuration, and established conventions
+5. The simplest deterministic choice that preserves the authorities above
+
+A commercial solver is a behavioral reference only when the project contract selects it. Its public input semantics, output definitions, documented procedures, and verification examples may support decisions; never infer undocumented internals or claim implementation equivalence.
+
+## Autonomous decisions
+
+Proceed without user review for reversible choices within approved contracts: internal naming and data layout, test organization, diagnostics, equivalent implementation mechanics, documentation formatting, and correction of clear build or test defects. Record assumptions that affect interpretation.
+
+## User decisions
+
+Return `needs-user-decision` only for a choice that changes at least one of:
+
+- supported physics, formulation meaning, or analysis scope;
+- public compatibility or an authoritative I/O schema;
+- acceptance choices where reasonable criteria split the same evidence between pass and fail and change product acceptance or a public accuracy promise, or where authoritative requirements and reference evidence cannot be reconciled technically;
+- a material security/trust-boundary or credential-handling change, or acceptance of an unresolved security, legal, licensing, or compliance risk;
+- external reference-solver execution, destructive history changes, publication, deployment, or release.
+
+Everything else follows the authority order. Lack of a preference is not a blocker when a deterministic in-contract choice exists.
+
+## Contract flow
+
+Requirements own acceptance intent; research owns evidence; formulation owns mathematics; numerical review owns independent numerical findings and logical verification coverage; I/O owns external/internal mappings; implementation owns code and tests; physics review owns physical plausibility; release review owns closure evidence. A downstream stage returns a defect to the owning upstream stage instead of silently rewriting its contract.