FESADev/.codex/skills/fesa-cpp-msvc-tdd/SKILL.md

---
name: fesa-cpp-msvc-tdd
description: Use when planning, implementing, build/testing, correcting, or reference-comparing FESA solver C++17 MSVC CMake CTest work with TDD.
---

# FESA C++ MSVC TDD

Use this skill to keep FESA C++ implementation, build/test reporting, correction, and reference comparison test-first, MSVC-compatible, and bounded by approved upstream contracts.

## Inputs

Read these first:

- `AGENTS.md`
- `docs/SOLVER_AGENT_DESIGN.md`
- `docs/HARNESS.md`
- `docs/HARNESS_WORKFLOW.md`
- `docs/<feature-id>/requirements.md`
- `docs/<feature-id>/research.md`
- `docs/<feature-id>/formulation.md`
- `docs/<feature-id>/numerical-review.md`
- `docs/<feature-id>/reference-model.md`
- `docs/<feature-id>/io.md`
- `docs/<feature-id>/implementation-plan.md`
- `docs/<feature-id>/implementation-report.md` when present
- `docs/<feature-id>/build-test.md` when present
- `docs/<feature-id>/reference-comparison.md` when present
- For the final Implementation-owned verification Step/gate, generated FESA `results.h5` and the
  exact feature-declared reference `.inp` and Abaqus CSV paths

For Harness implementation, also read `.agents/skills/harness/SKILL.md`,
`.codex/hooks.json`, the materialized phase indexes, and the Executor-selected current
`stepN.md`.

## Workflow

1. For planning, use the project-local `harness` skill to convert upstream documents into a
   user-approved multi-Step draft. Materialize only planning files after approval; planning never
   selects or runs a Step. Run `scripts/execute.py` only after a separate explicit user request.
2. For implementation, require the approved plan, materialized phase files, and the
   Executor-selected current `stepN.md`. Do not start another pending Step.
3. Execute the current Step as `RED -> observed failure -> minimal GREEN -> focused/full VERIFY`.
   Update only its Codex-owned `status` plus `summary`, `error_message`, or `blocked_reason`.
   The Executor owns branch, pending-Step selection, retry, timestamps, commits, advancement,
   and top-level phase status.
4. Hooks are automatic through `.codex/hooks.json`: PreToolUse intercepts before edits and Stop
   performs whole-project validation. Do not manually run their entry points as substitutes.
5. RED: write the planned unit, integration, parser/I/O, or reference-comparison test first.
6. RED: run the targeted test and verify the expected failure before production code.
7. GREEN: implement the minimum C++17/MSVC-compatible code needed for the task.
8. VERIFY: resolve commands from `.harness/config.json` first, then Harness defaults; run the
   targeted command and any focused/full MSVC x64 Debug build/test commands declared by the current
   Step in order.
9. For C++ production changes, require a related C++ test file in the same patch or already present.
10. Treat PreToolUse as a test-file-existence guardrail, not proof that RED was observed. Record the RED and GREEN commands and results in the implementation report.
11. Let Stop perform the final whole-project MSVC build/test before the Step ends.
12. Record every build/test command, exit code, duration, stdout/stderr tail, failed test names, environment, and project-selection path. Stop after the first decisive failure unless the implementation plan requires another diagnostic command.
13. For failure triage, classify as `configure | compile | link | test | reference-comparison | harness | environment | upstream-contract`.
14. A non-final Step ends after its declared `RED -> observed failure -> minimal GREEN -> focused/full VERIFY` acceptance commands and owned status/summary update. Do not fail it merely because final solver output, reference artifacts, or `reference-comparison.md` are not yet available.
15. Only when the approved implementation plan places the current Step after all prerequisite
    implementation Steps as the final Implementation-owned verification Step/gate, run reference
    comparison in this literal order: `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT`.
16. At that final gate, ARTIFACT CHECK requires exact declared input/CSV paths, generated `results.h5`, the `docs/<feature-id>/io.md` HDF5 projection, source identity/component matching, row uniqueness/finite checks, and approved tolerance.
17. COMPARE matches HDF5 and CSV rows by declared source identity and component, never by row order. Reject missing, extra, duplicate, and nonfinite required rows before tolerance; preserve warning-only behavior.
18. Fix implementation-owned failures only and keep changes traceable to the implementation plan.

## Output Contract

Produce the applicable feature-bundled evidence:

- `docs/<feature-id>/implementation-plan.md`
- `docs/<feature-id>/implementation-report.md`
- `docs/<feature-id>/build-test.md`
- `docs/<feature-id>/reference-comparison.md`
- `docs/<feature-id>/corrections.md`

`docs/<feature-id>/implementation-report.md` records RED/GREEN/VERIFY evidence. `docs/<feature-id>/build-test.md` uses
`owner_agent: implementation-agent` and records the historical build/test sections: metadata,
execution environment, command-log summary, validation results, failure classification, failed
test inventory, handoff recommendation, no-change assertion, and open issues.

`docs/<feature-id>/reference-comparison.md` records the exact input/CSV artifact inventory, `results.h5`, HDF5
projection, source-ID/component matching, row prechecks, approved tolerance, per-quantity
per-row decisions, max absolute error, max relative or component-normalized error, RMS error,
norm error where the approved feature contract makes each metric applicable, classification,
handoff, no-change assertion, and open issues.

Required validation commands:

```powershell
cmake -S . -B .harness/build -A x64
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug -R <feature-or-label> --output-on-failure
ctest --test-dir .harness/build -C Debug --show-only=json-v1
ctest --test-dir .harness/build -C Debug --output-on-failure
```

Use configured CMake presets or direct MSBuild commands instead when
`.harness/config.json` selects them. For Harness Python, Hook, or agent-config
changes, also run:

```powershell
uv run --with pytest python -m pytest -v -rs
```

## Boundaries

- Do not change requirements.
- Do not change formulations.
- Do not change I/O contracts.
- Do not change numerical review reports.
- Do not change reference artifacts.
- Do not change tolerance policies.
- Do not change declared reference inputs.
- Do not modify `docs/<feature-id>/reference-model.md` or its reference-model contracts/evidence,
  including declared comparison quantities, source identity/component rules, artifact contracts,
  or approved tolerance, to make comparisons pass.
- Do not run Abaqus, Nastran, or any reference solver.
- Do not generate or modify Abaqus reference CSV files.
- Do not approve release readiness.
- During planning, do not block on canonical reference naming, README, metadata, provenance, or
  an unrequested reference portfolio. Require only feature-declared input/CSV files, matching, and tolerance.

## Quality Gate

- Every `must` requirement maps to at least one task and one test.
- Each test has a clear RED condition, GREEN condition, linked task, and command.
- CMake/CTest plans remain compatible with MSVC x64 Debug validation.
- Stop validation is green for the whole discovered C/C++ project; a no-project pass is valid only when no C/C++ files and no build metadata exist.
- Build/test reports record command, exit code, duration, stdout/stderr tail, and failure classification.
- Reference comparison rejects missing, extra, duplicate, and nonfinite required rows before tolerance.
- Warning-only quantities never change the blocking pass/fail result.
- Reference comparison records per-row decisions and, only where the approved feature contract
  makes each metric applicable, max absolute error, max relative or component-normalized error,
  RMS error, and norm error.
- Compile, link, test, and reference-comparison failures return to Implementation Agent first.
- Repeated or unclear implementation failures route to Correction Agent through Coordinator Agent.
- Automatic rework stops when the same normalized failure classification reaches two attempts.

## Handoff

Return the applicable canonical outputs, status, evidence summary, and blockers to Coordinator Agent. Implementation Planning returns `docs/<feature-id>/implementation-plan.md` for one Implementation Agent handoff. A non-final Implementation Step returns only its owned status/summary and applicable evidence. The final Implementation-owned verification Step/gate returns `docs/<feature-id>/implementation-report.md`, `docs/<feature-id>/build-test.md`, and `docs/<feature-id>/reference-comparison.md`; send `pass-for-physics-evaluation` to Physics Evaluation Agent through Coordinator Agent. Correction returns `docs/<feature-id>/corrections.md` and a rerun request to Implementation Agent through Coordinator Agent. Return upstream-contract failures to Coordinator Agent for the owning upstream sub-agent.