FESADev/docs/superpowers/plans/2026-08-15-agent-skill-workflow-consolidation.md

# FESA Agent/Skill Workflow Consolidation Implementation Plan

> **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.

**Goal:** Consolidate the FESA development workflow into eight stages, merge three redundant agents and two redundant skills into their approved owners, make `coordinator-agent` the main orchestrator, and group all feature evidence under `docs/<feature-id>/`.

**Architecture:** Keep one main Coordinator and ten specialist sub-agents. Merge reference-model preparation into Numerical Review and merge build/test plus reference comparison into Implementation, while retaining separate evidence documents for auditability. Migrate existing feature documents without rewriting historical owners or verdicts, and protect the resulting structure with repository-level Python contract tests.

**Tech Stack:** Codex agent TOML, project-local Codex `SKILL.md` and `agents/openai.yaml`, Markdown workflow contracts, Python 3 standard library (`pathlib`, `tomllib`), pytest, PowerShell, Git.

## Global Constraints

- The approved design is `docs/superpowers/specs/2026-08-15-agent-skill-workflow-consolidation-design.md`.
- All new feature evidence lives under exactly `docs/<feature-id>/`.
- Keep separate `implementation-report.md`, `build-test.md`, and `reference-comparison.md` files even though one Implementation Agent owns them.
- Keep separate `numerical-review.md` and `reference-model.md` files even though one Numerical Review Agent owns them.
- `coordinator-agent` is the only main agent; every other `.codex/agents/*.toml` profile is a sub-agent.
- Keep `correction-agent` as an on-demand rework sub-agent outside the eight numbered stages.
- Preserve `model_reasoning_effort = "extra high"` in every agent profile.
- Preserve historical document content, `owner_agent`, status, and numerical verdict; only relocate files and repair path references.
- Do not create empty evidence files for outputs that never existed. Create `corrections.md` only after a real correction.
- Do not modify solver C++ source, C++ tests, CMake/CTest configuration, `.codex/hooks.json`, Harness executor behavior, phase status/result content, or `reference/` artifacts.
- Keep project-local `harness` planning/execution boundaries unchanged.
- Use conventional commit messages.

---

## Final File Map

### Create

- `tests/test_agent_skill_workflow_contract.py`: static contract tests for agent inventory, skill inventory, hierarchy, merged responsibilities, output layout, and live-path cleanup.
- `docs/linear-static-3d-euler-beam/coordination.md`: migrated feature worklist and closure inventory.
- `docs/linear-static-mitc4-shell/coordination.md`: migrated feature worklist and closure inventory.

### Modify

- `AGENTS.md`: eight-stage process, consolidated agent/skill table, main/sub-agent policy, and `docs/<feature-id>/` layout.
- `.codex/agents/coordinator-agent.toml`: main-agent orchestration, dispatch loop, worklist, gate decisions, and rework control.
- `.codex/agents/requirement-agent.toml`: sub-agent contract, new paths, and Numerical Review handoff for reference evidence.
- `.codex/agents/research-agent.toml`: sub-agent contract, new paths, and Numerical Review handoff for reference candidates.
- `.codex/agents/formulation-agent.toml`: sub-agent contract, new paths, and consolidated Numerical Review handoff.
- `.codex/agents/numerical-review-agent.toml`: numerical review plus reference-model ownership.
- `.codex/agents/io-definition-agent.toml`: sub-agent contract and final HDF5 projection ownership after merged review.
- `.codex/agents/implementation-planning-agent.toml`: new paths, consolidated skill inputs, and Implementation-only downstream validation handoff.
- `.codex/agents/implementation-agent.toml`: TDD implementation, MSVC build/CTest, reference comparison, and three-document evidence ownership.
- `.codex/agents/correction-agent.toml`: on-demand rework from Implementation evidence and return to Implementation.
- `.codex/agents/physics-evaluation-agent.toml`: consume Implementation-owned reference comparison and route model gaps to Numerical Review.
- `.codex/agents/release-agent.toml`: audit consolidated Implementation evidence and new paths.
- `.codex/skills/fesa-numerical-review/SKILL.md`: absorb reference-case inventory and readiness workflow.
- `.codex/skills/fesa-numerical-review/agents/openai.yaml`: describe consolidated numerical/reference review.
- `.codex/skills/fesa-cpp-msvc-tdd/SKILL.md`: absorb build/test reporting and reference comparison workflow.
- `.codex/skills/fesa-cpp-msvc-tdd/agents/openai.yaml`: describe consolidated implementation/verification work.
- `.codex/skills/fesa-requirements-baseline/SKILL.md`: new output path and Numerical Review handoff.
- `.codex/skills/fesa-research-evidence/SKILL.md`: new output path and Numerical Review handoff.
- `.codex/skills/fesa-formulation-spec/SKILL.md`: new output path and consolidated handoff.
- `.codex/skills/fesa-io-contract/SKILL.md`: new output path and final HDF5/reference mapping responsibility.
- `.codex/skills/fesa-physics-sanity/SKILL.md`: new paths and consolidated failure routing.
- `.codex/skills/fesa-release-readiness/SKILL.md`: new paths and consolidated gate evidence.
- `docs/SOLVER_AGENT_DESIGN.md`: surviving roles, eight-stage flowchart, gates, status transitions, and output layout.
- `docs/SOLVER_SKILL_DESIGN.md`: eight workflow skills and consolidated agent-to-skill mapping.
- Moved feature documents and tracked plan/spec/phase documents containing old feature-document paths: repair path references only.

### Delete after absorption

- `.codex/agents/reference-model-agent.toml`
- `.codex/agents/build-test-executor-agent.toml`
- `.codex/agents/reference-verification-agent.toml`
- `.codex/skills/fesa-reference-models/`
- `.codex/skills/fesa-reference-comparison/`
- Agent-oriented output-folder README files under `docs/coordination/`, `docs/requirements/`, `docs/research/`, `docs/formulations/`, `docs/numerical-reviews/`, `docs/io-definitions/`, `docs/reference-models/`, `docs/implementation-plans/`, `docs/build-test-reports/`, `docs/corrections/`, `docs/reference-verifications/`, `docs/physics-evaluations/`, and `docs/releases/`.

---

### Task 1: Add RED workflow-contract tests

**Files:**

- Create: `tests/test_agent_skill_workflow_contract.py`
- Read: `docs/superpowers/specs/2026-08-15-agent-skill-workflow-consolidation-design.md`

**Interfaces:**

- Consumes: approved agent names, skill names, feature folders, artifact filenames, and mandatory contract phrases from the design.
- Produces: pytest functions used as acceptance gates by Tasks 2–6.

- [ ] **Step 1: Create the static contract test module**

Add this complete test module:

```python
from pathlib import Path
import tomllib


ROOT = Path(__file__).resolve().parents[1]
AGENT_DIR = ROOT / ".codex" / "agents"
SKILL_DIR = ROOT / ".codex" / "skills"

EXPECTED_AGENTS = {
    "coordinator-agent",
    "correction-agent",
    "formulation-agent",
    "implementation-agent",
    "implementation-planning-agent",
    "io-definition-agent",
    "numerical-review-agent",
    "physics-evaluation-agent",
    "release-agent",
    "requirement-agent",
    "research-agent",
}

EXPECTED_SKILLS = {
    "fem-theory-query",
    "fesa-cpp-msvc-tdd",
    "fesa-formulation-spec",
    "fesa-io-contract",
    "fesa-numerical-review",
    "fesa-physics-sanity",
    "fesa-release-readiness",
    "fesa-requirements-baseline",
    "fesa-research-evidence",
}

LEGACY_OUTPUT_DIRS = {
    "coordination",
    "requirements",
    "research",
    "formulations",
    "numerical-reviews",
    "io-definitions",
    "reference-models",
    "implementation-plans",
    "build-test-reports",
    "corrections",
    "reference-verifications",
    "physics-evaluations",
    "releases",
}

FEATURE_FILES = {
    "linear-static-3d-euler-beam": {
        "coordination.md",
        "requirements.md",
        "research.md",
        "formulation.md",
        "numerical-review.md",
        "reference-model.md",
        "io.md",
        "implementation-plan.md",
        "implementation-report.md",
        "build-test.md",
        "reference-comparison.md",
        "physics-evaluation.md",
        "release.md",
    },
    "linear-static-mitc4-shell": {
        "coordination.md",
        "requirements.md",
        "research.md",
        "formulation.md",
        "numerical-review.md",
        "reference-model.md",
        "io.md",
        "implementation-plan.md",
        "build-test.md",
        "reference-comparison.md",
        "physics-evaluation.md",
        "release.md",
    },
}

LIVE_CONTRACT_FILES = (
    ROOT / "AGENTS.md",
    ROOT / "docs" / "SOLVER_AGENT_DESIGN.md",
    ROOT / "docs" / "SOLVER_SKILL_DESIGN.md",
)

RETIRED_TOKENS = (
    "reference-model-agent",
    "reference model agent",
    "build-test-executor-agent",
    "build/test executor agent",
    "reference-verification-agent",
    "reference verification agent",
    "fesa-reference-models",
    "fesa-reference-comparison",
    "docs/coordination/",
    "docs/requirements/",
    "docs/research/",
    "docs/formulations/",
    "docs/numerical-reviews/",
    "docs/io-definitions/",
    "docs/reference-models/",
    "docs/implementation-plans/",
    "docs/build-test-reports/",
    "docs/corrections/",
    "docs/reference-verifications/",
    "docs/physics-evaluations/",
    "docs/releases/",
)


def read(path: Path) -> str:
    return path.read_text(encoding="utf-8")


def live_contract_text() -> str:
    paths = list(LIVE_CONTRACT_FILES)
    paths.extend(sorted(AGENT_DIR.glob("*.toml")))
    paths.extend(sorted(SKILL_DIR.glob("*/SKILL.md")))
    return "\n".join(read(path) for path in paths)


def test_agent_inventory_is_consolidated():
    actual = {path.stem for path in AGENT_DIR.glob("*.toml")}
    assert actual == EXPECTED_AGENTS


def test_project_skill_inventory_is_consolidated():
    actual = {
        path.name
        for path in SKILL_DIR.iterdir()
        if path.is_dir() and (path / "SKILL.md").is_file()
    }
    assert actual == EXPECTED_SKILLS


def test_existing_feature_artifacts_are_bundled():
    docs_dir = ROOT / "docs"
    for legacy_dir in LEGACY_OUTPUT_DIRS:
        assert not (docs_dir / legacy_dir).exists(), legacy_dir

    for feature_id, expected_files in FEATURE_FILES.items():
        feature_dir = docs_dir / feature_id
        actual_files = {path.name for path in feature_dir.glob("*.md")}
        assert actual_files == expected_files


def test_numerical_review_absorbs_reference_model_contract():
    assert not (AGENT_DIR / "reference-model-agent.toml").exists()
    assert not (SKILL_DIR / "fesa-reference-models").exists()
    text = read(SKILL_DIR / "fesa-numerical-review" / "SKILL.md").lower()
    for marker in (
        "numerical-review.md",
        "reference-model.md",
        "reference case inventory",
        "source identity",
        "row precheck",
        "tolerance",
        "pass-for-io-definition",
    ):
        assert marker in text


def test_implementation_absorbs_build_test_and_reference_comparison():
    assert not (AGENT_DIR / "build-test-executor-agent.toml").exists()
    assert not (AGENT_DIR / "reference-verification-agent.toml").exists()
    assert not (SKILL_DIR / "fesa-reference-comparison").exists()
    text = read(SKILL_DIR / "fesa-cpp-msvc-tdd" / "SKILL.md").lower()
    for marker in (
        "implementation-report.md",
        "build-test.md",
        "reference-comparison.md",
        "artifact check -> compare -> classify -> report",
        "pass-for-physics-evaluation",
    ):
        assert marker in text


def test_agent_hierarchy_is_explicit():
    coordinator = read(AGENT_DIR / "coordinator-agent.toml").lower()
    assert "main agent" in coordinator
    assert "docs/<feature-id>/coordination.md" in coordinator
    assert "worklist" in coordinator
    assert "sub-agent dispatch" in coordinator

    for path in sorted(AGENT_DIR.glob("*.toml")):
        if path.name == "coordinator-agent.toml":
            continue
        text = read(path).lower()
        assert "sub-agent" in text, path.name
        assert "coordinator agent" in text, path.name


def test_live_contracts_have_no_retired_names_or_paths():
    text = live_contract_text().lower()
    assert "docs/<feature-id>/" in text
    for token in RETIRED_TOKENS:
        assert token not in text, token


def test_live_guidance_declares_eight_stage_workflow():
    for path in LIVE_CONTRACT_FILES:
        text = read(path)
        assert "8단계" in text, path
        assert "docs/<feature-id>/" in text, path


def test_agent_toml_and_skill_ui_metadata_are_parseable():
    for path in sorted(AGENT_DIR.glob("*.toml")):
        parsed = tomllib.loads(read(path))
        assert parsed["name"] == path.stem
        assert parsed["model_reasoning_effort"] == "extra high"

    for skill_name in EXPECTED_SKILLS:
        skill_dir = SKILL_DIR / skill_name
        skill_text = read(skill_dir / "SKILL.md")
        ui_text = read(skill_dir / "agents" / "openai.yaml")
        assert f"name: {skill_name}" in skill_text
        assert f"${skill_name}" in ui_text
```

- [ ] **Step 2: Run each new behavior test and record RED evidence**

Run:

```powershell
uv run --with pytest python -m pytest tests/test_agent_skill_workflow_contract.py -v
```

Expected: `test_agent_toml_and_skill_ui_metadata_are_parseable` passes. The other eight tests fail because the old agents, old skills, old document folders, old paths, old stage count, and non-hierarchical agent contracts still exist.

- [ ] **Step 3: Commit the RED contract tests**

```powershell
git add tests/test_agent_skill_workflow_contract.py
git commit -m "test: define consolidated agent workflow contract"
```

---

### Task 2: Migrate existing evidence into feature folders

**Files:**

- Create: `docs/linear-static-3d-euler-beam/coordination.md`
- Create: `docs/linear-static-mitc4-shell/coordination.md`
- Move: the 23 existing feature evidence files listed below.
- Delete: the 13 old agent-oriented README files after their common policy is covered by the approved design and later live-contract updates.
- Test: `tests/test_agent_skill_workflow_contract.py::test_existing_feature_artifacts_are_bundled`

**Interfaces:**

- Consumes: existing Markdown evidence with historical statuses and the final filename map.
- Produces: canonical `docs/<feature-id>/` bundles consumed by every surviving agent and skill.

- [ ] **Step 1: Create and verify the two explicit target directories**

Run:

```powershell
$targets = @(
  (Resolve-Path -LiteralPath 'docs').Path + '\linear-static-3d-euler-beam',
  (Resolve-Path -LiteralPath 'docs').Path + '\linear-static-mitc4-shell'
)
$docsRoot = (Resolve-Path -LiteralPath 'docs').Path
foreach ($target in $targets) {
  if (-not $target.StartsWith($docsRoot + '\')) { throw "Target escaped docs: $target" }
  New-Item -ItemType Directory -Path $target -Force | Out-Null
}
```

Expected: both resolved targets are direct children of `C:\git\FESADev\docs`.

- [ ] **Step 2: Move the Euler beam evidence using this exact mapping**

```powershell
Move-Item -LiteralPath 'docs\requirements\linear-static-3d-euler-beam.md' -Destination 'docs\linear-static-3d-euler-beam\requirements.md'
Move-Item -LiteralPath 'docs\research\linear-static-3d-euler-beam-research.md' -Destination 'docs\linear-static-3d-euler-beam\research.md'
Move-Item -LiteralPath 'docs\formulations\3d-isoparametric-euler-beam-formulation.md' -Destination 'docs\linear-static-3d-euler-beam\formulation.md'
Move-Item -LiteralPath 'docs\numerical-reviews\linear-static-3d-euler-beam-review.md' -Destination 'docs\linear-static-3d-euler-beam\numerical-review.md'
Move-Item -LiteralPath 'docs\reference-models\linear-static-3d-euler-beam-reference-models.md' -Destination 'docs\linear-static-3d-euler-beam\reference-model.md'
Move-Item -LiteralPath 'docs\io-definitions\linear-static-3d-euler-beam-io.md' -Destination 'docs\linear-static-3d-euler-beam\io.md'
Move-Item -LiteralPath 'docs\implementation-plans\linear-static-3d-euler-beam.md' -Destination 'docs\linear-static-3d-euler-beam\implementation-plan.md'
Move-Item -LiteralPath 'docs\implementation-plans\linear-static-3d-euler-beam-implementation-report.md' -Destination 'docs\linear-static-3d-euler-beam\implementation-report.md'
Move-Item -LiteralPath 'docs\build-test-reports\linear-static-3d-euler-beam.md' -Destination 'docs\linear-static-3d-euler-beam\build-test.md'
Move-Item -LiteralPath 'docs\reference-verifications\linear-static-3d-euler-beam-reference-verification.md' -Destination 'docs\linear-static-3d-euler-beam\reference-comparison.md'
Move-Item -LiteralPath 'docs\physics-evaluations\linear-static-3d-euler-beam-physics-evaluation.md' -Destination 'docs\linear-static-3d-euler-beam\physics-evaluation.md'
Move-Item -LiteralPath 'docs\releases\linear-static-3d-euler-beam-release.md' -Destination 'docs\linear-static-3d-euler-beam\release.md'
```

Expected: all 12 sources disappear and all 12 destinations exist without content rewriting.

- [ ] **Step 3: Move the MITC4 evidence using this exact mapping**

```powershell
Move-Item -LiteralPath 'docs\requirements\linear-static-mitc4-shell.md' -Destination 'docs\linear-static-mitc4-shell\requirements.md'
Move-Item -LiteralPath 'docs\research\linear-static-mitc4-shell-research.md' -Destination 'docs\linear-static-mitc4-shell\research.md'
Move-Item -LiteralPath 'docs\formulations\mitc4-shell-formulation.md' -Destination 'docs\linear-static-mitc4-shell\formulation.md'
Move-Item -LiteralPath 'docs\numerical-reviews\linear-static-mitc4-shell-review.md' -Destination 'docs\linear-static-mitc4-shell\numerical-review.md'
Move-Item -LiteralPath 'docs\reference-models\linear-static-mitc4-shell-reference-models.md' -Destination 'docs\linear-static-mitc4-shell\reference-model.md'
Move-Item -LiteralPath 'docs\io-definitions\linear-static-mitc4-shell-io.md' -Destination 'docs\linear-static-mitc4-shell\io.md'
Move-Item -LiteralPath 'docs\implementation-plans\linear-static-mitc4-shell-implementation-plan.md' -Destination 'docs\linear-static-mitc4-shell\implementation-plan.md'
Move-Item -LiteralPath 'docs\build-test-reports\linear-static-mitc4-shell-build-test.md' -Destination 'docs\linear-static-mitc4-shell\build-test.md'
Move-Item -LiteralPath 'docs\reference-verifications\linear-static-mitc4-shell-reference-verification.md' -Destination 'docs\linear-static-mitc4-shell\reference-comparison.md'
Move-Item -LiteralPath 'docs\physics-evaluations\linear-static-mitc4-shell-physics-evaluation.md' -Destination 'docs\linear-static-mitc4-shell\physics-evaluation.md'
Move-Item -LiteralPath 'docs\releases\linear-static-mitc4-shell-release.md' -Destination 'docs\linear-static-mitc4-shell\release.md'
```

Expected: all 11 sources disappear and all 11 destinations exist. Do not create `implementation-report.md` because no historical MITC4 implementation report exists.

- [ ] **Step 4: Add the Euler beam coordination inventory**

Create `docs/linear-static-3d-euler-beam/coordination.md` with this evidence, preserving the already-approved release verdict:

```markdown
# Linear Static 3D Euler Beam Coordination Report

## Metadata

- feature_id: linear-static-3d-euler-beam
- status: completed
- owner_agent: coordinator-agent
- date: 2026-08-15
- migration_note: Existing evidence was relocated without rerunning workflow gates.

## Worklist

| stage | owner | status | evidence |
| --- | --- | --- | --- |
| 1. requirements | requirement-agent | passed | `requirements.md` |
| 2. research | research-agent | passed | `research.md` |
| 3. formulation | formulation-agent | passed | `formulation.md` |
| 4. numerical and reference | numerical-review-agent | passed | `numerical-review.md`; `reference-model.md` |
| 5. I/O | io-definition-agent | passed | `io.md` |
| 6. implementation and verification | implementation-planning-agent; implementation-agent | passed | `implementation-plan.md`; `implementation-report.md`; `build-test.md`; `reference-comparison.md` |
| 7. physics | physics-evaluation-agent | passed | `physics-evaluation.md` |
| 8. release | release-agent | passed | `release.md` |

## Current Progress

- active_sub_agent: none
- next_handoff: none
- closure_evidence: `release.md` status `ready-for-release`
- workflow_disposition: completed

## Decision Log

| date | decision | evidence | rationale |
| --- | --- | --- | --- |
| 2026-08-15 | Record migrated workflow as completed | `release.md` | Preserve the existing release verdict without retroactive gate execution. |

## Blockers and Rework

- active_blockers: none
- correction_attempt_count: 0
- needs_user_decision: false
```

- [ ] **Step 5: Add the MITC4 coordination inventory**

Create `docs/linear-static-mitc4-shell/coordination.md` with this content:

```markdown
# Linear Static MITC4 Shell Coordination Report

## Metadata

- feature_id: linear-static-mitc4-shell
- status: completed
- owner_agent: coordinator-agent
- date: 2026-08-15
- migration_note: Existing evidence was relocated without rerunning workflow gates.

## Worklist

| stage | owner | status | evidence |
| --- | --- | --- | --- |
| 1. requirements | requirement-agent | passed | `requirements.md` |
| 2. research | research-agent | passed | `research.md` |
| 3. formulation | formulation-agent | passed | `formulation.md` |
| 4. numerical and reference | numerical-review-agent | passed | `numerical-review.md`; `reference-model.md` |
| 5. I/O | io-definition-agent | passed | `io.md` |
| 6. implementation and verification | implementation-planning-agent; implementation-agent | passed | `implementation-plan.md`; `build-test.md`; `reference-comparison.md` |
| 7. physics | physics-evaluation-agent | passed | `physics-evaluation.md` |
| 8. release | release-agent | passed | `release.md` |

## Current Progress

- active_sub_agent: none
- next_handoff: none
- closure_evidence: `release.md` status `ready-for-release`
- workflow_disposition: completed
- historical_gap: No standalone `implementation-report.md` existed before migration; no replacement was fabricated.

## Decision Log

| date | decision | evidence | rationale |
| --- | --- | --- | --- |
| 2026-08-15 | Record migrated workflow as completed | `release.md` | Preserve the existing release verdict without retroactive gate execution. |

## Blockers and Rework

- active_blockers: none
- correction_attempt_count: 0
- needs_user_decision: false
```

- [ ] **Step 6: Remove the old output-folder README files**

Delete only these files with `apply_patch`; do not recursively delete directories:

```text
docs/coordination/README.md
docs/requirements/README.md
docs/research/README.md
docs/formulations/README.md
docs/numerical-reviews/README.md
docs/io-definitions/README.md
docs/reference-models/README.md
docs/implementation-plans/README.md
docs/build-test-reports/README.md
docs/corrections/README.md
docs/reference-verifications/README.md
docs/physics-evaluations/README.md
docs/releases/README.md
```

- [ ] **Step 7: Run the bundle contract test**

Run:

```powershell
uv run --with pytest python -m pytest tests/test_agent_skill_workflow_contract.py::test_existing_feature_artifacts_are_bundled -v
```

Expected: PASS. Broken links are allowed temporarily and are repaired in Task 6.

- [ ] **Step 8: Commit the evidence migration**

```powershell
git add -A docs/linear-static-3d-euler-beam docs/linear-static-mitc4-shell docs/coordination docs/requirements docs/research docs/formulations docs/numerical-reviews docs/io-definitions docs/reference-models docs/implementation-plans docs/build-test-reports docs/corrections docs/reference-verifications docs/physics-evaluations docs/releases
git commit -m "docs: group solver evidence by feature"
```

---

### Task 3: Merge Reference Model into Numerical Review

**Files:**

- Modify: `.codex/agents/numerical-review-agent.toml:1`
- Delete: `.codex/agents/reference-model-agent.toml`
- Modify: `.codex/skills/fesa-numerical-review/SKILL.md:1`
- Modify: `.codex/skills/fesa-numerical-review/agents/openai.yaml:1`
- Delete: `.codex/skills/fesa-reference-models/SKILL.md`
- Delete: `.codex/skills/fesa-reference-models/agents/openai.yaml`
- Test: `tests/test_agent_skill_workflow_contract.py::test_numerical_review_absorbs_reference_model_contract`

**Interfaces:**

- Consumes: `requirements.md`, `research.md`, `formulation.md`, stored `reference/` artifacts, and the approved tolerance contract.
- Produces: `numerical-review.md` and `reference-model.md` with status `pass-for-io-definition` when both reviews pass.

- [ ] **Step 1: Expand the Numerical Review Agent mission and inputs**

In `.codex/agents/numerical-review-agent.toml`, retain all math/numerical checks and add these exact responsibilities:

```text
- Act as a sub-agent dispatched by Coordinator Agent for the consolidated numerical/reference gate.
- Inventory exact existing reference input and required CSV paths without modifying them.
- Define blocking and warning-only quantities, source identity/components, row prechecks, and approved tolerance.
- Produce docs/<feature-id>/numerical-review.md and docs/<feature-id>/reference-model.md.
- Hand both reports to I/O Definition Agent through Coordinator Agent.
```

Use this input order:

```text
1. Coordinator handoff and user constraints.
2. AGENTS.md and docs/SOLVER_AGENT_DESIGN.md.
3. docs/<feature-id>/requirements.md.
4. docs/<feature-id>/research.md.
5. docs/<feature-id>/formulation.md.
6. Existing stored reference artifacts under reference/, read-only.
```

The agent must not require `io.md`. It defines logical quantities and source identity; I/O Definition owns the final HDF5 dataset projection.

- [ ] **Step 2: Define the two-document output and statuses**

Keep the existing Numerical Review report sections and add a separate Reference Model report contract with:

```text
Metadata
Reference Acceptance Scope
Reference Case Inventory
Source Identity and Component Contract
Row Prechecks
Tolerance and Blocking/Warning Policy
Open Issues and I/O Handoff
```

Use only these consolidated statuses:

```text
pass-for-io-definition
needs-formulation-revision
needs-research
needs-reference-artifacts
needs-user-decision
blocked
```

- [ ] **Step 3: Merge the two skill workflows**

Update `.codex/skills/fesa-numerical-review/SKILL.md` so its frontmatter description triggers for both numerical review and reference-case readiness. Its workflow must include:

```text
FORMULATION REVIEW -> REFERENCE CASE INVENTORY -> CLASSIFY -> REPORT -> I/O HANDOFF
```

The Output Contract must name:

```text
docs/<feature-id>/numerical-review.md
docs/<feature-id>/reference-model.md
```

Absorb exact-path inventory, blocking/warning quantities, source identity/component matching,
missing/extra/duplicate/nonfinite row prechecks, approved tolerance, and read-only artifact boundaries
from the retiring skill. Do not include final HDF5 dataset paths; route that mapping to I/O Definition.

- [ ] **Step 4: Regenerate the consolidated skill UI metadata**

Run:

```powershell
$generator = Join-Path $env:USERPROFILE '.codex\skills\.system\skill-creator\scripts\generate_openai_yaml.py'
python $generator '.codex\skills\fesa-numerical-review' `
  --interface 'display_name=FESA Numerical and Reference Review' `
  --interface 'short_description=Review numerical and reference readiness' `
  --interface 'default_prompt=Use $fesa-numerical-review to review FESA numerical and reference-model readiness.'
```

Expected: `agents/openai.yaml` contains the three quoted interface values and the default prompt names `$fesa-numerical-review`.

- [ ] **Step 5: Delete the absorbed agent and skill files**

Delete the three retiring files with `apply_patch`:

```text
.codex/agents/reference-model-agent.toml
.codex/skills/fesa-reference-models/SKILL.md
.codex/skills/fesa-reference-models/agents/openai.yaml
```

The empty `.codex/skills/fesa-reference-models/` directory then disappears from Git.

- [ ] **Step 6: Run the focused consolidation test**

Run:

```powershell
uv run --with pytest python -m pytest tests/test_agent_skill_workflow_contract.py::test_numerical_review_absorbs_reference_model_contract -v
```

Expected: PASS.

- [ ] **Step 7: Commit the numerical/reference consolidation**

```powershell
git add -A .codex/agents/numerical-review-agent.toml .codex/agents/reference-model-agent.toml .codex/skills/fesa-numerical-review .codex/skills/fesa-reference-models
git commit -m "refactor: merge reference model into numerical review"
```

---

### Task 4: Merge Build/Test and Reference Comparison into Implementation

**Files:**

- Modify: `.codex/agents/implementation-agent.toml:1`
- Delete: `.codex/agents/build-test-executor-agent.toml`
- Delete: `.codex/agents/reference-verification-agent.toml`
- Modify: `.codex/skills/fesa-cpp-msvc-tdd/SKILL.md:1`
- Modify: `.codex/skills/fesa-cpp-msvc-tdd/agents/openai.yaml:1`
- Delete: `.codex/skills/fesa-reference-comparison/SKILL.md`
- Delete: `.codex/skills/fesa-reference-comparison/agents/openai.yaml`
- Test: `tests/test_agent_skill_workflow_contract.py::test_implementation_absorbs_build_test_and_reference_comparison`
- Test: `tests/test_agent_skill_workflow_contract.py::test_agent_inventory_is_consolidated`
- Test: `tests/test_agent_skill_workflow_contract.py::test_project_skill_inventory_is_consolidated`

**Interfaces:**

- Consumes: `implementation-plan.md`, all upstream feature documents, generated `results.h5`, exact reference input/CSV paths, `.harness/config.json`, and the unchanged Harness execution contract.
- Produces: `implementation-report.md`, `build-test.md`, and `reference-comparison.md`; success hands `pass-for-physics-evaluation` to Coordinator.

- [ ] **Step 1: Expand the Implementation Agent execution contract**

In `.codex/agents/implementation-agent.toml`, preserve the current Harness Step ownership rules and replace the downstream-only validation handoff with this full sequence:

```text
RED -> OBSERVED FAILURE -> MINIMAL GREEN -> FOCUSED VERIFY
    -> FULL MSVC BUILD/CTEST -> ARTIFACT CHECK
    -> COMPARE -> CLASSIFY -> REPORT
```

Add exact ownership of:

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

The agent remains forbidden from modifying requirements, formulation, numerical/reference contracts,
I/O contracts, tolerance policies, declared inputs, or Abaqus reference CSV files.

- [ ] **Step 2: Absorb Build/Test reporting**

Move these requirements from the retiring Build/Test profile into Implementation:

```text
- Resolve commands from .harness/config.json first, then project defaults.
- Record command, exit code, duration, stdout/stderr tail, failed test names, and environment.
- Classify configure, compile, link, test, reference-comparison, harness, environment, and upstream-contract failures.
- Stop after the first decisive failure unless the implementation plan explicitly requires another diagnostic command.
- Preserve MSVC x64 Debug and CTest command order.
```

`build-test.md` keeps the historical Build/Test report sections but sets `owner_agent: implementation-agent`.

- [ ] **Step 3: Absorb Reference Comparison reporting**

Move these requirements from the retiring Reference Verification profile into Implementation:

```text
ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT
```

Require exact declared input/CSV paths, generated `results.h5`, HDF5 projection from `io.md`,
source identity/component matching, row uniqueness/finite checks, and approved tolerance. Reject
missing, extra, duplicate, and nonfinite required rows before tolerance. Preserve warning-only behavior.

Use these final statuses:

```text
in-progress
pass-for-physics-evaluation
needs-correction
needs-reference-artifacts
needs-environment-fix
needs-upstream-decision
blocked
```

- [ ] **Step 4: Expand `fesa-cpp-msvc-tdd`**

Update its frontmatter and body to cover planning, TDD implementation, build/test reporting,
correction, and reference comparison. The Output Contract must name:

```text
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
```

Include the literal workflow marker used by the test:

```text
ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT
```

Send `pass-for-physics-evaluation` evidence to Physics Evaluation Agent through Coordinator Agent.

- [ ] **Step 5: Regenerate the consolidated skill UI metadata**

Run:

```powershell
$generator = Join-Path $env:USERPROFILE '.codex\skills\.system\skill-creator\scripts\generate_openai_yaml.py'
python $generator '.codex\skills\fesa-cpp-msvc-tdd' `
  --interface 'display_name=FESA C++ TDD and Verification' `
  --interface 'short_description=Implement and verify FESA C++ work' `
  --interface 'default_prompt=Use $fesa-cpp-msvc-tdd to plan, implement, build, test, and reference-verify FESA C++ work.'
```

Expected: the default prompt explicitly names `$fesa-cpp-msvc-tdd`.

- [ ] **Step 6: Delete the absorbed agent and skill files**

Delete with `apply_patch`:

```text
.codex/agents/build-test-executor-agent.toml
.codex/agents/reference-verification-agent.toml
.codex/skills/fesa-reference-comparison/SKILL.md
.codex/skills/fesa-reference-comparison/agents/openai.yaml
```

- [ ] **Step 7: Run focused agent/skill inventory tests**

Run:

```powershell
uv run --with pytest python -m pytest `
  tests/test_agent_skill_workflow_contract.py::test_implementation_absorbs_build_test_and_reference_comparison `
  tests/test_agent_skill_workflow_contract.py::test_agent_inventory_is_consolidated `
  tests/test_agent_skill_workflow_contract.py::test_project_skill_inventory_is_consolidated -v
```

Expected: all three tests PASS.

- [ ] **Step 8: Commit the implementation/verification consolidation**

```powershell
git add -A .codex/agents/implementation-agent.toml .codex/agents/build-test-executor-agent.toml .codex/agents/reference-verification-agent.toml .codex/skills/fesa-cpp-msvc-tdd .codex/skills/fesa-reference-comparison
git commit -m "refactor: merge implementation verification workflow"
```

---

### Task 5: Make Coordinator the main orchestrator and normalize all sub-agent contracts

**Files:**

- Modify: `.codex/agents/coordinator-agent.toml:1`
- Modify: every ten surviving sub-agent TOML files under `.codex/agents/`.
- Modify: all eight surviving `fesa-*` `SKILL.md` files under `.codex/skills/`.
- Test: `tests/test_agent_skill_workflow_contract.py::test_agent_hierarchy_is_explicit`

**Interfaces:**

- Consumes: consolidated stage owners and canonical feature-document paths from Tasks 2–4.
- Produces: one main-agent dispatch protocol and ten bounded sub-agent return contracts.

- [ ] **Step 1: Rewrite the Coordinator mission and execution loop**

In `.codex/agents/coordinator-agent.toml`, identify it with the exact phrase `main agent` and define:

```text
INTAKE -> STATE AUDIT -> WORKLIST UPDATE -> SUB-AGENT DISPATCH
       -> EVIDENCE CHECK -> GATE DECISION -> STATUS REPORT
```

Require `docs/<feature-id>/coordination.md`, the eight-stage worklist, and these work-item statuses:

```text
pending | in-progress | passed | needs-rework | blocked
```

Each dispatch package must contain:

```text
feature_id
target_sub_agent
required_inputs
expected_outputs
acceptance_gate
stop_condition
missing_evidence
```

Coordinator must update `coordination.md` before dispatch and after evidence return. It must not
perform specialist math review, code implementation, build/test, comparison, physics, or release
judgment itself.

- [ ] **Step 2: Replace obsolete Coordinator states and routes**

Remove these intermediate routes and statuses:

```text
needs-reference-model
needs-build-test
needs-reference-verification
pass-for-reference-verification
```

Use this live workflow state set:

```text
intake
needs-requirements
needs-research
needs-formulation
needs-numerical-review
needs-io-definition
needs-implementation-plan
ready-for-implementation
needs-implementation
needs-correction
needs-physics-evaluation
needs-release
ready-for-release
completed
needs-user-decision
blocked
```

Route reference artifact/tolerance gaps to Numerical Review, HDF5 projection gaps to I/O Definition,
compile/test/comparison failures to Implementation first, and repeated or unclear implementation
failures to Correction. Stop automatic rework when the same classification reaches two attempts.

- [ ] **Step 3: Mark all specialist profiles as sub-agents**

Add this invariant to every surviving non-Coordinator TOML:

```text
- You are a sub-agent dispatched by Coordinator Agent.
- Work only on the assigned stage and declared docs/<feature-id>/ outputs.
- Do not dispatch peer agents or advance the workflow yourself.
- Return output paths, status, evidence summary, and blockers to Coordinator Agent.
```

Preserve each profile's technical hard boundaries and `model_reasoning_effort = "extra high"`.

- [ ] **Step 4: Normalize surviving agent paths and handoffs**

Apply these exact path/owner changes:

| Agent | Reads | Writes or returns |
| --- | --- | --- |
| Requirement | `docs/<feature-id>/requirements.md` when revising | `requirements.md`; theory to Research; reference acceptance to Numerical Review |
| Research | `requirements.md` | `research.md`; formulation evidence to Formulation; benchmark/reference evidence to Numerical Review |
| Formulation | `requirements.md`, `research.md` | `formulation.md`; all review evidence to Numerical Review |
| Numerical Review | `requirements.md`, `research.md`, `formulation.md` | `numerical-review.md`, `reference-model.md`; both to I/O Definition |
| I/O Definition | upstream bundle documents including `reference-model.md` | `io.md`; final HDF5 projection to Implementation Planning |
| Implementation Planning | all upstream bundle documents | `implementation-plan.md`; one handoff to Implementation |
| Implementation | all upstream bundle documents and `implementation-plan.md` | `implementation-report.md`, `build-test.md`, `reference-comparison.md` |
| Correction | Implementation-owned reports and code/test/CMake evidence | `corrections.md`; rerun request to Implementation |
| Physics Evaluation | `reference-comparison.md`, `reference-model.md`, physics contracts | `physics-evaluation.md`; model gaps to Numerical Review |
| Release | all feature bundle evidence | `release.md`; closure recommendation to Coordinator |

- [ ] **Step 5: Normalize all surviving FESA skill paths and handoffs**

Update the Inputs, Output Contract, Quality Gate, and Handoff sections of these files:

```text
.codex/skills/fesa-requirements-baseline/SKILL.md
.codex/skills/fesa-research-evidence/SKILL.md
.codex/skills/fesa-formulation-spec/SKILL.md
.codex/skills/fesa-numerical-review/SKILL.md
.codex/skills/fesa-io-contract/SKILL.md
.codex/skills/fesa-cpp-msvc-tdd/SKILL.md
.codex/skills/fesa-physics-sanity/SKILL.md
.codex/skills/fesa-release-readiness/SKILL.md
```

Every feature-document path must start with `docs/<feature-id>/`. Remove all handoffs to retired
agents and skills. Preserve `fem-theory-query` and project-local `harness` usage where already valid.

- [ ] **Step 6: Run the hierarchy test**

Run:

```powershell
uv run --with pytest python -m pytest tests/test_agent_skill_workflow_contract.py::test_agent_hierarchy_is_explicit -v
```

Expected: PASS.

- [ ] **Step 7: Commit the Coordinator and sub-agent contracts**

```powershell
git add .codex/agents .codex/skills
git commit -m "refactor: make coordinator the main workflow agent"
```

---

### Task 6: Align repository guidance and repair document links

**Files:**

- Modify: `AGENTS.md:1`
- Modify: `docs/SOLVER_AGENT_DESIGN.md:1`
- Modify: `docs/SOLVER_SKILL_DESIGN.md:1`
- Modify: moved files under `docs/linear-static-3d-euler-beam/` and `docs/linear-static-mitc4-shell/` only where old paths appear.
- Modify: tracked Markdown under `docs/superpowers/plans/`, `docs/superpowers/specs/`, and `phases/` only where an old feature-document path must be repaired.
- Test: `tests/test_agent_skill_workflow_contract.py::test_live_contracts_have_no_retired_names_or_paths`
- Test: `tests/test_agent_skill_workflow_contract.py::test_live_guidance_declares_eight_stage_workflow`
- Test: `tests/test_agent_skill_workflow_contract.py::test_agent_toml_and_skill_ui_metadata_are_parseable`

**Interfaces:**

- Consumes: canonical agent/skill contracts and bundle paths from Tasks 2–5.
- Produces: one consistent human-readable workflow with no retired live references and valid historical links.

- [ ] **Step 1: Rewrite the AGENTS workflow sections**

In `AGENTS.md`:

1. Replace agent-oriented source-of-truth folders with `docs/<feature-id>/`.
2. Replace the numbered process with the approved eight stages.
3. Replace the Agent/Skill Workflow table with the exact stage/owner/skill/output mapping from the design.
4. State that Coordinator is the main agent and every other profile is a sub-agent.
5. Keep Correction outside the numbered stages as on-demand rework.
6. Keep the Implementation Planning Agent's project-local `harness` approval/materialization contract unchanged.
7. Remove retired agent names, retired skill names, and retired output paths.

- [ ] **Step 2: Rewrite `docs/SOLVER_AGENT_DESIGN.md` around the surviving roles**

The document must contain:

```text
Coordinator main-agent orchestration
10 surviving sub-agent roles
8-stage development-process table
8-stage Mermaid workflow
Numerical/reference merged gate
I/O-owned final HDF5 projection
Implementation-owned TDD/build/test/reference comparison gate
Correction rework loop
docs/<feature-id>/ artifact tree
```

Remove standalone Reference Model, Build/Test Executor, and Reference Verification sections.

- [ ] **Step 3: Rewrite `docs/SOLVER_SKILL_DESIGN.md` around eight workflow skills**

List the eight surviving `fesa-*` skills exactly as specified in the design. Document that:

- `fesa-numerical-review` owns both numerical and reference readiness procedures.
- `fesa-cpp-msvc-tdd` owns implementation planning, TDD, MSVC validation, correction, and reference comparison procedures.
- `fem-theory-query`, project-local `harness`, and `review` remain supporting skills.
- Skill output paths use only `docs/<feature-id>/`.

Update the validation count from ten workflow skills to eight.

- [ ] **Step 4: Repair exact feature-document paths in moved and historical Markdown**

Use `rg` to inventory references before editing:

```powershell
rg -n --hidden --glob '!.git/**' --glob '*.md' `
  'docs/(requirements|research|formulations|numerical-reviews|io-definitions|reference-models|implementation-plans|build-test-reports|corrections|reference-verifications|physics-evaluations|releases|coordination)/' `
  AGENTS.md docs phases
```

Apply the Task 2 filename mapping with `apply_patch`. Update only path strings in historical
evidence and phase/spec/plan records; preserve their agent names, statuses, timestamps, commands,
results, and verdict prose. The current consolidation design and this plan may retain old paths
inside migration descriptions because those references describe sources being removed.

- [ ] **Step 5: Run live-contract and metadata tests**

Run:

```powershell
uv run --with pytest python -m pytest `
  tests/test_agent_skill_workflow_contract.py::test_live_contracts_have_no_retired_names_or_paths `
  tests/test_agent_skill_workflow_contract.py::test_live_guidance_declares_eight_stage_workflow `
  tests/test_agent_skill_workflow_contract.py::test_agent_toml_and_skill_ui_metadata_are_parseable -v
```

Expected: all three tests PASS.

- [ ] **Step 6: Commit the live workflow documentation**

```powershell
git add AGENTS.md docs phases
git commit -m "docs: align consolidated solver workflow"
```

---

### Task 7: Run full validation and close the refactor

**Files:**

- Verify: all files changed in Tasks 1–6.
- Do not modify: solver C++, C++ tests, CMake/CTest files, Harness hooks/executor, or reference artifacts unless a validation check reveals an accidental edit that must be reverted from this task's own changes.

**Interfaces:**

- Consumes: the complete consolidated workflow.
- Produces: fresh validation evidence and a clean implementation handoff.

- [ ] **Step 1: Run the focused workflow-contract suite**

```powershell
uv run --with pytest python -m pytest tests/test_agent_skill_workflow_contract.py -v
```

Expected: 9 tests PASS, 0 fail.

- [ ] **Step 2: Run the complete Python suite**

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

Expected: all repository Python tests PASS.

- [ ] **Step 3: Validate every remaining project-local skill**

```powershell
$validator = Join-Path $env:USERPROFILE '.codex\skills\.system\skill-creator\scripts\quick_validate.py'
$validationFailed = $false
Get-ChildItem -LiteralPath '.codex\skills' -Directory | Sort-Object Name | ForEach-Object {
  python $validator $_.FullName
  if ($LASTEXITCODE -ne 0) { $validationFailed = $true }
}
if ($validationFailed) { exit 1 }
```

Expected: every remaining skill reports valid frontmatter and naming.

- [ ] **Step 4: Check the final agent/skill inventory and working-tree scope**

```powershell
Get-ChildItem -LiteralPath '.codex\agents' -Filter '*.toml' | Sort-Object Name | Select-Object -ExpandProperty Name
Get-ChildItem -LiteralPath '.codex\skills' -Directory | Sort-Object Name | Select-Object -ExpandProperty Name
git diff --check
git status --short
```

Expected:

- 11 agent TOMLs: one Coordinator plus ten sub-agents.
- 9 project-local skill directories: eight FESA workflow skills plus `fem-theory-query`.
- `git diff --check` exits 0.
- No solver C++, C++ test, CMake, hook, executor, or `reference/` artifact appears in the task diff.

- [ ] **Step 5: Confirm no final C++ validation is required**

Inspect the changed-file list:

```powershell
git diff --name-only HEAD~6..HEAD
```

Expected: only agent/skill configuration, Markdown, and the Python contract test changed. Record
that MSVC build and CTest were not run because no C++ production, C++ test, or CMake/CTest file
changed.

- [ ] **Step 6: Commit only validation-driven corrections if any were required**

If Steps 1–5 required corrections, stage only those corrections and commit:

```powershell
git add -A
git commit -m "fix: correct consolidated workflow contracts"
```

If no corrections were required, do not create an empty commit.

---

## Acceptance Traceability

| Approved requirement | Implemented by | Verified by |
| --- | --- | --- |
| Merge reference-model stage into numerical review | Task 3 | `test_numerical_review_absorbs_reference_model_contract` |
| Merge Build/Test and Reference Comparison into Implementation | Task 4 | `test_implementation_absorbs_build_test_and_reference_comparison` |
| Merge the corresponding skills | Tasks 3–4 | focused merge tests and skill validation |
| Store evidence by feature under `docs/<feature-id>/` | Task 2 | `test_existing_feature_artifacts_are_bundled` |
| Make Coordinator the main orchestrator | Task 5 | `test_agent_hierarchy_is_explicit` |
| Focus Coordinator output on worklist and progress | Tasks 2 and 5 | coordination documents and hierarchy test |
| Preserve historical evidence | Tasks 2 and 6 | migration diff review and bundle inventory |
| Remove stale live references | Tasks 5–6 | `test_live_contracts_have_no_retired_names_or_paths` |
| Keep configs and skill metadata valid | Tasks 3–7 | TOML/metadata pytest and `quick_validate.py` |