orcawave-orcaflex-readiness-audit

# OrcaWave / OrcaFlex Readiness Audit

Use this when the user asks questions like:
- what is actually ready in OrcaWave/OrcaFlex?
- where does `spec.yml` generate semantically equivalent solver inputs?
- which issues are stale vs real gaps?
- what structures/families are already represented?
- what do the LLM-wikis still lack for this domain?

## Core lesson

Do NOT treat old issue bodies as current truth.
This domain has multiple issues that still read like greenfield work even though the code, tests, and fixtures already exist.

## Audit sequence

1. Read the three anchor docs first:
   - `docs/maps/digitalmodel-orcawave-orcaflex-operator-map.md`
   - `docs/roadmaps/orcawave-orcaflex-capability-roadmap.md`
   - `docs/reports/digitalmodel-orcawave-orcaflex-issue-reconciliation.md`

2. Query issues from `workspace-hub`, not from `digitalmodel/`.
   - The canonical issue tracker for this domain is the workspace-hub repo.
   - `gh issue view` from `digitalmodel/` may fail with “Could not resolve to an issue” for valid issue numbers.

3. Reconcile issue state against source + tests.
   Important historically stale / already-implemented issues to verify first:
   - `#1588`, `#1596`, `#1598` — DiffractionSpec / parametric-spec pipeline
   - `#1597` — RAO extractor and DB population
   - `#1592`, `#1605`, `#1768` — OrcaWave -> OrcaFlex handoff and validation

4. Verify readiness with focused tests before making claims.
   High-signal test slice:
   - `tests/hydrodynamics/diffraction/test_parametric_spec_generator.py`
   - `tests/hydrodynamics/diffraction/test_orcawave_to_orcaflex_pipeline.py`
   - `tests/hydrodynamics/diffraction/test_orcawave_to_orcaflex_integration.py`
   - `tests/solvers/orcaflex/modular_generator/test_semantic_roundtrip.py`

   In digitalmodel, a strong local command is:
   `PYTHONPATH=src ./.venv/bin/python -m pytest <focused files> -q`

5. Inventory current structure/template families from `docs/domains/orcaflex/` and `docs/domains/orcawave/` rather than relying on roadmap counts alone.

6. Review the wikis separately for:
   - breadth of raw/source coverage
   - synthesis quality for operator use

## Claim-boundary rules

Keep semantic-equivalence claims conservative and solver-specific.

### OrcaWave
Say:
- strong for engineering-significant round-trip fidelity
- not guaranteed literal identity across every strict OrcaWave YAML field

Back this by checking:
- `docs/domains/orcawave/README.md`
- roundtrip/semantic tests in `tests/hydrodynamics/diffraction/`

### OrcaFlex
Say:
- forward `spec.yml -> modular/single YAML` is the strong path
- reverse extraction remains best-effort only

Back this by checking:
- `docs/domains/orcaflex/QUICKSTART_FILE_CONVERSION.md`
- `docs/domains/orcaflex/SEMANTIC_DIFF_TAXONOMY.md`
- semantic roundtrip tests under `tests/solvers/orcaflex/modular_generator/`

### Distinguish these four claims explicitly
Never blur them:
1. engineering-equivalent behavior
2. strict YAML parity
3. solver-loadable parity
4. benchmark-validated parity

## What “ready” usually means in this domain

Classify each workstream into one of these buckets:

1. Ready now
   - implemented in source
   - backed by tests and/or committed fixtures

2. Ready but needs stronger evidence
   - code exists
   - tests exist but mainly benchmark/fixture-based
   - needs licensed-machine or real-project proof

3. Real gap
   - still requires substantive implementation

## Common real gaps even when the core pipeline exists

These often remain open after the base `spec.yml` pipeline is implemented:
- standards-driven DLC matrix generation
- richer hull/structure registries
- more real project families and golden models
- licensed-machine fixture and snapshot proof
- clearer wiki synthesis of the canonical-contract boundary

## LLM-wiki audit shortcut

The engineering wiki already tends to contain seed pages such as:
- OrcaFlex Solver
- OrcaWave Solver
- Diffraction Analysis System
- OrcaWave-to-OrcaFlex Pipeline

But these audits should assume the synthesis layer is still incomplete.

Typical missing pages / weakly synthesized topics:
- `DiffractionSpec` as a first-class canonical contract
- OrcaFlex `ProjectInputSpec` / modular-generator contract
- semantic-equivalence claim-boundary comparison page
- `RAODatabase` provenance page
- hull-registry / structure-registry readiness page
- case-study pages for risers, jumpers, semisubs, turret mooring, and installation families

Specific wiki drift found in the April 2026 readiness review:
- `knowledge/wikis/engineering/wiki/workflows/orcawave-to-orcaflex-pipeline.md` may still describe the handoff as `.owr -> RAO extraction`; the current dev-primary bridge is xlsx sidecar -> `RAOData` -> `DiffractionResults` -> OrcaFlex export.
- The engineering wiki has seed pages for OrcaFlex, OrcaWave, Diffraction Analysis System, and OrcaWave-to-OrcaFlex Pipeline, but it lacks operator-ready pages for the canonical spec contract and structure readiness matrix.
- Recommended wiki synthesis pages: `Canonical Spec Contract: OrcaWave vs OrcaFlex`, `DiffractionSpec Canonical Contract`, `ProjectInputSpec Canonical Contract`, `Semantic Equivalence Taxonomy for Marine Solver Inputs`, `RAODatabase Provenance and xlsx Sidecar Workflow`, `Structure Readiness Matrix`, and case studies for turret-moored FPSO, PLET-to-PLEM rigid jumper, lazy/steep-wave riser, L03 ship benchmark, CALM/SPM, and semi-sub/FOWT.

So always report wiki findings in two layers:
1. raw/source breadth exists
2. operator-ready synthesis does not yet exist

## Good final-output structure

For user-facing readiness reviews, produce:
1. the canonical `spec.yml -> native input` workstreams
2. what is ready now
3. the most important remaining gaps
4. which structure families already exist
5. which structure families should be added next
6. LLM-wiki coverage vs synthesis gaps
7. a ranked next-step issue list

## Recently discovered issue anchors for canonical-spec proof

When auditing current work, include these newer proof-expansion issues if present:
- `#2454` — flagship generic-track OrcaFlex mooring case / turret-moored FPSO semantic proof
- `#2455` — rigid jumper family / PLET-to-PLEM semantic proof
- `#2456` — lazy-wave / steep-wave riser semantic proof
- `#2457` — OrcaWave L03 ship benchmark explicit roundtrip proof

Use these alongside the older foundation issues. The practical order is usually:
1. `#1652` + `#1788` for real OrcaFlex `.sim` fixture/report/snapshot proof
2. `#2454`, `#2455`, `#2456` for OrcaFlex family-level semantic proof
3. `#2457` for named OrcaWave flagship proof
4. `#1586` for queue traceability/repeatability
5. `#1637`, `#1591`, `#1594` for scalable sweeps, hull registry, and standards-driven DLC campaigns