# Project Completion Tracker

Last updated: 2026-06-16 CST

This file tracks the overall completion state of the LinuxCNC WASM/browser port.
Use it for project-level status and acceptance tracking. Use `text14.txt` for
turn-by-turn continuation notes and next-batch execution records.

## Current Status

- Active continuation file: `text14.txt`
- Latest completed batch: INI panel shell API surface inventory
- Latest relevant commit: use `git log -1 --oneline` after each committed batch
- Working tree at tracker creation: clean
- Required policy: LinuxCNC remains the only CNC semantic source
- Current scope status: complete after final clean-tree release validation

## Completion Definition

The project is complete for the current scope when all of the following are true:

- Browser UI workflows are usable and validated:
  - INI panel
  - control page
  - workflow overview
  - external shell handoff
  - OPFS/session persistence
- SDK/API surface exposes stable helpers for external callers.
- Sim config coverage has clear pass/skip/promotion state.
- Host/runtime blocked families are explicitly documented and not falsely promoted.
- All required gates pass.
- Documentation explains what is supported, blocked, and how to verify it.
- `text14.txt` contains the final completion record and the working tree is clean.

## Area Status

| Area | Status | Notes |
| --- | --- | --- |
| LinuxCNC semantic boundary | Stable | JS/browser remains glue, staging, OPFS, WASM/browser boundary, docs, and tests only. |
| Vendor/source guard | Stable | `verify_vendor_sync.sh` and standalone semantic guard are required every batch. |
| Interpreter WASM smoke | Stable | `interp_wasm_node_smoke=ok`. |
| Sim config inventory | Stable with skips | `executed=28`, `passed=28`, `skipped=131`, `unexpected_fail=0`; `docs/sim-configs-coverage-handoff.md` records the release-gate baseline. |
| Native nc_files baseline | Stable | Last recorded Layer 1: `total 107`, `pass 101`, `expected_fail 6`, `unexpected_fail 0`. |
| Native sim configs baseline | Stable | Last recorded Layer 2: `total 159`, `pass 151`, `expected_fail 8`, `unexpected_fail 0`. |
| OPFS/session persistence | Stable for current scope | Browser smoke passes, SDK re-exports OPFS/session helpers including `readMachineSessionReadiness()`, and `docs/opfs-session-persistence.md` defines the project-level release gate. |
| SDK/API surface | Stable for current scope | SDK re-exports core, OPFS/session readiness/load helpers, sim-config staging, INI panel shell/workflow overview helpers, the session readiness workflow report, and the shell API surface inventory with a Node surface smoke. |
| Browser/UI workflow | Stable for current scope | Workflow overview embedding mount DOM closure is complete, and INI panel session workflows plus read-only control/shell handoff expose, render, and report OPFS/session readiness before loading or reading WASM session state. |
| Workflow overview embedding | Stable for current scope | Report/display/render, DOM contract/readiness/renderer, mount result/display/render, mount DOM contract/readiness/renderer/wrapper exist. |
| Host/runtime boundary proof | Stable blocked state | Host smoke passes; runtime families remain blocked and `docs/host-runtime-boundary-handoff.md` records host readiness, promotion blockers, dispatch, and evidence gates. |
| Documentation/release gate | Stable for current scope | `docs/project-release-handoff.md` links README, panel entry, SDK, OPFS/session, sim-config, host/runtime, source reuse, drift, and tracker acceptance paths. |
| Project release gate wrapper | Stable | `tests/host/verify_project_release_gate.sh` runs the documented minimum release validation commands and ends with `project_release_gate=ok`. |

## Blocked Runtime Families

Do not promote these without real LinuxCNC-owned runtime proof and the required
native -> Node/WASM -> browser/host validation sequence:

- `L4-USER-M-PROCESS`
- `L4-TOOL-DB`
- `L4-PYTHON-REMAP`

Do not run these unless the host environment actually provides the needed
LinuxCNC runtime:

```bash
ENABLE_MILLTURN_USER_M_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_millturn_user_m_runtime.sh
ENABLE_TOOL_DB_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_tool_db_runtime.sh
ENABLE_PYTHON_REMAP_RUNTIME_PROBE=1 bash wasm-port/tests/native/probe_python_remap_runtime.sh
```

## Remaining Work

Execute these in order unless a later user request explicitly changes priority.

### 1. Browser/UI Workflow Closure

Current next task:

- No required work remains for the current scope. Future work should start from
  a new scope request or from a real LinuxCNC host runtime becoming available
  for the blocked runtime families.

Then complete the closure:

- Mount render-state DOM renderer is complete.
- Non-throwing mount workflow wrapper is complete.
- Expose each helper through:
  - `createIniPanelLaunchApiManifest().methods`
  - `createIniPanelShellViewModel()`
  - `window.linuxCncIniPanelLaunchApi`
  - `window.linuxCncIniPanelWorkflowOverviewApi`
- Cover each helper in:
  - UI Node smoke
  - launch API manifest test
  - shell integration manifest test
  - entry docs test
  - workflow overview browser smoke
  - launch browser smoke
  - shell integration browser smoke
  - `docs/panel-entry.md`

Completion criteria:

- External shell can render workflow overview embedding mount state with a
  custom DOM contract.
- Missing DOM returns structured blocked results where applicable.
- No control buttons or CNC semantic parsing are added.

### 2. SDK/API Surface Consolidation

Work items:

- Audit `runtime/sdk/src/index.js`. Done.
- Export stable helpers that external callers should use. Done for core, OPFS/session, sim-config staging, and INI panel shell/workflow overview helpers.
- Add or update SDK smoke for export shape and manifest compatibility. Done via `tests/sdk/node/verify_sdk_surface.sh`.
- Update `runtime/sdk/README.md` with usage examples and unsupported areas. Initial SDK surface update done; final docs pass still pending.

Completion criteria:

- SDK exports match documented browser/UI helper surface.
- SDK tests pass in Node.
- No CNC semantics are implemented in JS.

### 3. OPFS/Session Persistence Summary

Work items:

- Add a project-level OPFS/session workflow summary helper or report. Done as `docs/opfs-session-persistence.md`.
- Include machine files, session snapshot, readonly control status, and handoff
  readiness. Done through linked UI docs plus browser and host gate references.
- Add browser smoke coverage for save -> restore -> readonly status -> shell
  handoff. Existing browser smoke remains the gate for this workflow.
- Document OPFS scope and failure modes. Done.
- Add docs smoke for the project-level handoff. Done via `tests/docs/node/verify_opfs_session_docs.sh`.

Completion criteria:

- `browser_ini_opfs_smoke=ok` remains stable.
- External callers can inspect persistence readiness and failures.
- `opfs_session_docs_node_smoke=ok` is included in the host aggregate gate.

### 4. Sim Config Coverage Promotion Matrix

Work items:

- Keep inventory `unexpected_fail=0`.
- Make skip reasons machine-readable and documented:
  - `ASSET_ONLY`
  - `L4_PYTHON_REMAP`
  - `L4_TOOL_DB`
  - `L4_USER_M_PROCESS`
  - `NON_MAIN_CLASS`
  - `UPSTREAM_DEMO`
- Promote only configs with LinuxCNC-owned proof.
- Add short release handoff for current inventory baseline. Done via `docs/sim-configs-coverage-handoff.md`.
- Add docs smoke for inventory baseline and skip reason map. Done via `tests/docs/node/verify_sim_configs_coverage_docs.sh`.

Completion criteria:

- No skipped config lacks a documented reason.
- No blocked runtime family is falsely promoted.
- `sim_configs_coverage_docs_node_smoke=ok` is included in the host aggregate gate.

### 5. Host/Runtime Boundary Reports

Work items:

- Consolidate runtime family proof reports. Done via `docs/host-runtime-boundary-handoff.md`.
- Keep missing host runtime as blocked. Done; current status remains `host_blocked_for_all_opt_in_native_probes`.
- If real runtime becomes available, validate in native -> Node/WASM -> browser/host order.
- Add docs smoke for host/runtime boundary handoff. Done via `tests/docs/node/verify_host_runtime_boundary_docs.sh`.

Completion criteria:

- `verify_host_smokes.sh` remains stable.
- Boundaries are documented and machine-readable.
- `host_runtime_boundary_docs_node_smoke=ok` is included in the host aggregate gate.

### 6. Documentation/Release Gate

Work items:

- Update `README.md`. Done.
- Update `docs/panel-entry.md`. Done.
- Update `docs/source-reuse-map.md`. Done.
- Update `docs/drift-report.md`. Done.
- Add or refresh final acceptance checklist. Done via
  `docs/project-release-handoff.md`.
- Add docs smoke for project release handoff. Done via
  `tests/docs/node/verify_project_release_handoff_docs.sh`.

Completion criteria:

- A new developer can run validation from README/docs without reading old
  `text1` through `text13`.
- `project_release_handoff_docs_node_smoke=ok` is included in the host
  aggregate gate.

## Required Gates

Run these for each implementation batch:

```bash
git diff --check
wasm-port/tools/verify_vendor_sync.sh
wasm-port/tools/verify_no_standalone_cnc_semantics.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_interp_wasm.sh
SKIP_INTERP_BUILD=1 wasm-port/tests/wasm/node/verify_sim_configs_inventory_wasm.sh
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_ini_panel_browser.sh
wasm-port/tests/ui/node/verify_ui_node_smokes.sh
wasm-port/tests/host/verify_host_smokes.sh
```

Or run the same current-scope minimum gate through:

```bash
wasm-port/tests/host/verify_project_release_gate.sh
```

Run this if browser interpreter behavior is touched:

```bash
SKIP_INI_BUILD=1 SKIP_INTERP_BUILD=1 wasm-port/tests/browser/verify_interp_browser.sh
```

Run these for native/source/staging or promotion work:

```bash
wasm-port/tests/native/verify_nc_files.sh
wasm-port/tests/native/verify_sim_configs.sh
```

## Final Acceptance Checklist

- [x] Working tree is clean.
- [x] Latest `text14.txt` record says the project is complete for current scope.
- [x] `git diff --check` passes.
- [x] Vendor sync guard passes.
- [x] Standalone CNC semantics guard passes.
- [x] Interpreter WASM Node smoke passes.
- [x] Sim config WASM inventory has `unexpected_fail=0`.
- [x] UI Node smoke passes.
- [x] Browser INI panel smoke passes.
- [x] Host aggregate smoke passes.
- [x] Project release gate wrapper passes.
- [x] Runtime blocked families remain documented.
- [x] Project release handoff docs smoke passes.
- [x] README/docs explain supported workflows and blocked items.