# v0.28 Copilot MVP Release Checklist

This checklist packages the first public-facing AIENG Copilot MVP demo after
the closed-loop path is runnable.

## Claim boundary

Use this boundary in README, UI demo surfaces, loop reports, and exported
decision reviews:

> This decision review export is a reviewable record of one or two Copilot
> loops. It does not certify either design, does not advance engineering
> claims, and must be reviewed by a qualified engineer before being cited in
> any acceptance decision.
>
> This review export does not certify design safety, does not auto-advance engineering claims, and must be reviewed by a qualified engineer.

## Demo script

Start from the repository root after following the fresh-clone setup in
[README](../README.md).

1. Run the quick gate:

   ```bash
   ./scripts/check_demo_health.sh
   ```

   Windows PowerShell:

   ```powershell
   .\scripts\check_demo_health.ps1
   ```

2. Start the backend:

   ```bash
   cd backend
   uvicorn app.main:app --reload
   ```

3. Start the frontend in a second terminal:

   ```bash
   cd frontend
   npm run dev
   ```

4. Open the Vite URL, usually `http://localhost:5173`.
5. Open **Copilot Loop**.
6. In **Try the Copilot Loop demo**, click **Seed demo project**.
7. Click **Run demo health check**.
8. Confirm the health result passes and shows the claim-boundary snippet.
9. In **Loop history**, select the rejected and approved demo loops.
10. Click **Compare selected (2/2)**.
11. Click **Load report diff** and inspect **What changed**.
12. Click **Export review** and confirm the export preview contains the claim boundary.

## Screenshot or GIF checklist

Capture either one short GIF or these screenshots before release:

- [ ] Copilot Loop tab with the top **Claim boundary** banner visible.
- [ ] **Try the Copilot Loop demo** card before seeding, including the demo data boundary.
- [ ] Demo project seeded, showing project id and two pre-baked loops.
- [ ] Demo health check passed, including the claim-boundary snippet.
- [ ] Loop history with one rejected and one approved loop.
- [ ] Compare panel with **Approval decision** and **Metric delta summary** rows.
- [ ] Report diff after **Load report diff**, including **What changed**.
- [ ] Export review preview with English and Chinese claim-boundary text.
- [ ] Project Health Check result, including suggested actions or ready state.

## Local validation commands

Run the release gate:

```bash
./scripts/check_demo_health.sh --full
```

Windows PowerShell:

```powershell
.\scripts\check_demo_health.ps1 -Full -Frontend
```

Run commands individually when diagnosing failures:

```bash
cd backend
python -m pytest -q -k "smoke_check"
python -m pytest -q

cd ../frontend
npm run build
```

Optional real-environment checks:

```bash
cd backend
python -m pytest tests/test_api.py::test_run_solver_real_ccx_skipped_if_unavailable -v

# Requires AIENG_TEST_REAL_FREECAD=1 and FreeCADCmd.
python -m pytest tests/test_api.py::test_cae_generate_mesh_real_freecad_integration -v

# Requires AIENG_TEST_REAL_FREECAD=1, FreeCADCmd, and ccx.
python -m pytest tests/test_api.py::test_full_real_pipeline_step_to_summary -v -s
```

## Release checklist

- [ ] README fresh-clone path verified by a new user.
- [ ] Backend smoke-check tests pass.
- [ ] Full backend tests pass, with only documented optional skips.
- [ ] Frontend build passes.
- [ ] Demo health check passes.
- [ ] Optional real CalculiX check passes or skips with a clear missing-binary reason.
- [ ] Optional real FreeCAD integration check passes or skips with a clear missing-binary reason.
- [ ] Screenshot or GIF checklist is complete.
- [ ] Docs distinguish fixture, imported, and real solver data.
- [ ] Known limitations are visible before any demo claim.
- [ ] Claim-boundary text is visible in README, UI, loop reports, and exported reviews.
- [ ] CI status is checked on GitHub Actions before tagging or presenting the release.

## CI status

GitHub Actions workflow:
[`AIENG Demo Health`](../.github/workflows/demo-health.yml).

The workflow has two release-relevant jobs:

- **Demo smoke-check gate**: runs `python -m pytest -q -k "smoke_check"` on
  push and pull request.
- **Full backend + frontend build**: runs full backend tests and `npm run build`.

The workflow checks out `aieng` and `legacy/aieng-freecad-mcp` into sibling paths so
CI matches the local three-repo development layout. Real FreeCAD and real
CalculiX checks are not mandatory CI gates; they remain optional local checks
because public runners may not have those binaries.

## Data-source boundaries

| Data category | What it means | What it does not mean |
|---|---|---|
| Fixture demo data | Deterministic values bundled for the public walkthrough | Not real solver output; not evidence of physical correctness |
| Imported metrics | User-provided JSON/CSV/FRD-derived values written into the package | Not a certification or automatic claim acceptance |
| Real solver output | CalculiX/FreeCAD artifacts produced by external tools on the host | Still not a validated engineering claim without review |

## Known limitations

- Requires Python 3.11+ and Node 20+ for the documented path.
- The public Copilot demo uses deterministic fixture data.
- The public Copilot demo does not run FreeCAD, Gmsh, or CalculiX.
- FreeCAD inspection and mesh generation require FreeCADCmd on the host.
- Structural reruns require a CalculiX executable (`ccx`) on the host.
- Mesh quality metrics and convergence proof are not implemented.
- `converged: null` is intentional unless reliable convergence evidence exists.
- Report comparison is textual and structural; it is not a geometry or mesh diff.
- No workflow advances engineering claims automatically.
