cnc_wams/PROJECT_COMPLETION_TRACKER.md

Project Completion Tracker

Last updated: 2026-06-15 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: workflow overview embedding mount DOM renderer
• 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

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.
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	In progress	Browser smoke passes; final project needs explicit project-level summary/report.
SDK/API surface	In progress	Many UI helpers exist; final project needs SDK export/readme consolidation.
Browser/UI workflow	In progress	Current focus: workflow overview embedding mount DOM readiness/renderer/mount closure.
Workflow overview embedding	In progress	Report/display/render, DOM contract/readiness/renderer, mount result/display/render, mount DOM contract/readiness/renderer exist.
Host/runtime boundary proof	In progress	Host smoke passes; runtime families below remain blocked.
Documentation/release gate	In progress	text14.txt has roadmap; README/docs final pass still pending.

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:

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:

• Add non-throwing mount workflow wrapper for mount render-state DOM rendering.

Then complete the closure:

• Add mount render-state DOM renderer.
• Add non-throwing mount workflow wrapper.
• 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.
• Export stable helpers that external callers should use.
• Add or update SDK smoke for export shape and manifest compatibility.
• Update runtime/sdk/README.md with usage examples and unsupported areas.

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.
• Include machine files, session snapshot, readonly control status, and handoff readiness.
• Add browser smoke coverage for save -> restore -> readonly status -> shell handoff.
• Document OPFS scope and failure modes.

Completion criteria:

• browser_ini_opfs_smoke=ok remains stable.
• External callers can inspect persistence readiness and failures.

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.

Completion criteria:

• No skipped config lacks a documented reason.
• No blocked runtime family is falsely promoted.

5. Host/Runtime Boundary Reports

Work items:

• Consolidate runtime family proof reports.
• Keep missing host runtime as blocked.
• If real runtime becomes available, validate in native -> Node/WASM -> browser/host order.

Completion criteria:

• verify_host_smokes.sh remains stable.
• Boundaries are documented and machine-readable.

6. Documentation/Release Gate

Work items:

• Update README.md.
• Update docs/panel-entry.md.
• Update docs/source-reuse-map.md.
• Update docs/drift-report.md.
• Add or refresh final acceptance checklist.

Completion criteria:

• A new developer can run validation from README/docs without reading old text1 through text13.

Required Gates

Run these for each implementation batch:

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

Run this if browser interpreter behavior is touched:

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:

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

Final Acceptance Checklist

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