Skip to content

DEV_MODE.md

Latest commit

 

History

History
284 lines (214 loc) · 9.37 KB

DEV_MODE.md

File metadata and controls

284 lines (214 loc) · 9.37 KB

WCM DEV MODE

Date: 2026-04-11 Scope: Daily development operating mode for human contributors and coding agents.

1. Mission

DEV MODE exists to maximize shipping speed while preserving strict WaveIL-first ownership guarantees.

Primary goals:

  • Keep fast iteration for weekend project constraints.
  • Prevent semantic regressions during runtime and policy work.
  • Preserve a stable path to production OS capabilities.

2. Non-Negotiable Guardrails

  1. WaveIL-first ownership remains mandatory.
  2. No new Python policy branches for shell, input, explorer, or service orchestration decisions.
  3. Compatibility-first refactors only:
  • Keep existing opcode names valid during transitions.
  • Keep existing imports from WCM module stable.
  1. Never block feature work behind broad refactor-only phases.
  2. Full CI sweep is checkpoint validation, not every-change validation.

2.1 Chipset Contract (Production Model)

Intent:

  • Python is a simulated chipset, not the OS.
  • WaveIL is the OS control plane.

Python allowed surface (and only this surface):

  1. Substrate simulation and timing.
  2. Device ingress plumbing (keyboard, pointer, input queues, driver boundaries).
  3. Display egress plumbing (surface/frame output).
  4. Storage and HAL effect primitives.
  5. Runtime/interpreter plumbing that executes WaveIL instructions.

Python forbidden surface:

  1. Deciding shell policy outcomes.
  2. Deciding input route/focus semantics.
  3. Deciding explorer/file policy outcomes.
  4. Deciding service orchestration outcomes.
  5. Any fallback branch that changes behavior after WaveIL flow execution.

WaveIL mandatory ownership:

  1. Boot decisions and orchestration rules.
  2. Shell and window manager control semantics.
  3. Input routing and focus semantics.
  4. Explorer/file semantic operations.
  5. App policy and service policy decisions.

Static chipset ABI policy:

  1. Treat the Python chipset interface as production hardware contract.
  2. ABI changes are rare and expensive by default.
  3. New primitive opcodes require explicit justification and compatibility notes.
  4. Existing primitive behavior cannot silently change.

Change control for Python primitives:

  1. Additive changes preferred over mutating semantics.
  2. Any primitive behavior change must include:
  • strict-waveil-first-gate pass,
  • abi-smoke pass,
  • ci-sweep checkpoint pass,
  • migration note in PR summary.
  1. No convenience-only Python shortcuts that bypass WaveIL decision flow.

Depythonization posture:

  1. Convenience Python wrappers are transitional and should be removed over time.
  2. Every migrated behavior should move from Python decision logic to WaveIL flow logic.
  3. If uncertain, split the change into:
  • WaveIL decides what should happen,
  • Python primitive performs how it is applied.

Identity guardrail:

  1. The project target is a WaveIL-owned OS over a simulated chipset.
  2. The project must never drift into a Python OS with WaveIL as cosmetic layer.

2.2 Registry-First Wiring Contract

Canonical source:

  1. sdk_apps/system_policy/policy_registry.json is the source of truth for:
  • boot-required package membership,
  • app kind to package/bind/tick mappings,
  • launcher metadata,
  • policy tick runtime contracts.

Generated outputs:

  1. sdk_apps/system_policy/package_index.json
  2. sdk_apps/system_policy/generated/policy_dispatch.json
  3. sdk_apps/system_policy/generated/opcode_aliases.json
  4. sdk_apps/system_policy/generated/launcher_catalog.json

Rules:

  1. Do not hand-edit generated JSON outputs.
  2. Do not hand-edit generator-owned routing in sdk_apps/system_policy/wave.shell.wpk.json; policy_registry.py generate may rewrite app_create_flow, app_tick_dispatch_flow, and generated helper flows for untyped app-policy entries.
  3. Package wiring changes should go through installer.py or a direct edit to policy_registry.json, followed by regeneration.
  4. Registry or installer changes must run policy_registry.py check before Tier A is considered complete.

3. Validation Tiers

Tier A: Fast Loop (run on almost every change)

Target runtime: about 20-90 seconds.

Commands:

  • c:/Users/lukas/Desktop/WCM/.venv/Scripts/python.exe -m py_compile wcm.py main.py scenarios/scenario_runners.py scenarios/waveil_flow_gates.py
  • c:/Users/lukas/Desktop/WCM/.venv/Scripts/python.exe main.py --scenario strict-waveil-first-gate --ticks 200
  • For registry/installer/policy wiring changes also run: c:/Users/lukas/Desktop/WCM/.venv/Scripts/python.exe policy_registry.py check

Use when:

  • Runtime dispatch edits
  • WaveIL opcode handler changes
  • Policy bridge updates
  • Registry, installer, or generated policy wiring edits

Pass criteria:

  • No syntax errors
  • strict-waveil-first-gate final_ok is true
  • python_owner_delta is 0

Tier B: Medium Loop (run per feature slice)

Target runtime: about 2-3 minutes.

Commands:

  • c:/Users/lukas/Desktop/WCM/.venv/Scripts/python.exe main.py --scenario abi-smoke --ticks 250
  • Plus one domain gate based on changed area:
    • storage-backend-gate or storage-backends-gate for storage work
    • waveil-explorer-flow for explorer/file flow work
    • driver-kpi-gate for driver/input/perf-sensitive work

Use when:

  • New feature slice is complete
  • Behavior changed across subsystem boundary

Pass criteria:

  • All selected checks final_ok true

Tier C: Slow Loop (full checkpoint)

Target runtime: about 5-7 minutes.

Command:

  • c:/Users/lukas/Desktop/WCM/.venv/Scripts/python.exe main.py --scenario ci-sweep

Use when:

  • Before commit
  • Before long break
  • After risky refactor
  • End of day

Pass criteria:

  • sweep_ok true

4. Agent Working Contract

All coding agents should follow this order:

  1. Pick smallest safe change batch.
  2. Apply change.
  3. Run Tier A.
  4. If feature-level behavior changed, run Tier B.
  5. Defer Tier C to checkpoint moments.
  6. Report:
  • Changed files
  • Which tier ran
  • Result summary
  • Next smallest batch

If Tier A fails:

  • Stop new feature work.
  • Fix regression immediately.

If Tier C fails but Tier A and Tier B pass:

  • Triage failing scenario and either:
    • fix now if clear regression,
    • or log as known pre-existing instability with evidence.

5. Interactive Countertesting Mode

Purpose: manual click-around testing of real shell and desktop flows.

Primary interactive boot command:

  • c:/Users/lukas/Desktop/WCM/.venv/Scripts/python.exe main.py --scenario desktop-live-strict --ticks 1200 --frame-ms 33 --live-stride 1

VS Code one-click task:

  • Run Task -> Start Desktop (Strict)

Restore variant:

  • c:/Users/lukas/Desktop/WCM/.venv/Scripts/python.exe main.py --scenario desktop-live-strict-restore --ticks 1600 --restore-tick 700 --frame-ms 33 --live-stride 1

VS Code one-click restore task:

  • Run Task -> Start Desktop (Strict Restore)

Manual checklist for each interactive session:

  1. Launcher toggles and task focus changes work.
  2. Explorer actions complete (list, open, rename, move, delete/restore).
  3. Input routing remains responsive.
  4. No obvious desktop freeze or focus loss.
  5. Session exits cleanly.

Every manual bug found must produce:

  • One reproducible artifact or trace.
  • One new automated regression check in Tier B or Tier C.

6. Next Implementation Plan (Production-Oriented)

Phase 1: Dev Harness and Startup UX

Deliverables:

  1. Quick regression harness scenario that bundles Tier A plus selected Tier B checks.
  2. One command startup flow for interactive desktop countertesting.
  3. Optional VS Code task named Start Desktop (strict).

Exit criteria:

  • Daily work can run quick checks in under 2 minutes.
  • Interactive boot can be launched on demand in one command.

Phase 2: Executable Lifecycle V1

Deliverables:

  1. Validate package entrypoint and capabilities.
  2. Install and uninstall package lifecycle path.
  3. Launch, stop, restart executable process lifecycle.
  4. Capture launch and restart telemetry.

Exit criteria:

  • At least one package can complete install, run, restart cycle deterministically.
  • Capability denies remain enforced.

Phase 3: Service Manager Hardening

Deliverables:

  1. Explicit service dependency model and startup order assertions.
  2. Health state model (running, degraded, failed, restarting).
  3. Restart policy with bounded retries.
  4. Boot summary report surface.

Exit criteria:

  • Injected fault cycles recover deterministically.
  • Service dependency violations are visible in telemetry.

Phase 4: Replay-Driven Regression

Deliverables:

  1. Capture interactive input traces from desktop sessions.
  2. Replay traces in deterministic test mode.
  3. Add replay-based medium gate to default feature loop.

Exit criteria:

  • Manual countertests can be promoted into automated replay checks.

7. Definition of Done Per Feature Slice

A feature slice is complete when:

  1. Tier A passes.
  2. Relevant Tier B checks pass.
  3. At least one short interactive sanity run passes for desktop-facing changes.
  4. No new ownership delta regressions.
  5. Any discovered bug has a follow-up automated check.

8. What Not To Do In DEV MODE

  1. Do not run ci-sweep after every minor change.
  2. Do not batch many unrelated refactors before validation.
  3. Do not remove legacy opcodes during compatibility transition phases.
  4. Do not add policy logic fallback branches in Python host layer.

9. Daily Session Template

  1. Start:
  • Pull context and choose one narrow implementation target.
  1. During coding:
  • Run Tier A often.
  • Run Tier B per completed slice.
  1. Checkpoint:
  • Run Tier C.
  • Record outcomes and next priority.
  1. End of day:
  • Ensure ci-sweep status is known.
  • Leave clear next action for the next session.