From 1b1e9d727e4d41b9bb4508dc58e946670d82f02e Mon Sep 17 00:00:00 2001
From: Jimmy <git@jimmy.nz>
Date: Tue, 14 Apr 2026 21:50:55 +1200
Subject: [PATCH] chore(rules): enforce strict user-scoped changes

---
 .cursor/rules/led-driver.mdc        | 45 +++++++++++++++++++++++++++++
 .cursor/rules/strict-user-scope.mdc | 16 ++++++++++
 .gitmodules                         |  3 ++
 led-simulator                       |  1 +
 4 files changed, 65 insertions(+)
 create mode 100644 .cursor/rules/led-driver.mdc
 create mode 100644 .cursor/rules/strict-user-scope.mdc
 create mode 160000 led-simulator

diff --git a/.cursor/rules/led-driver.mdc b/.cursor/rules/led-driver.mdc
new file mode 100644
index 0000000..99fae3c
--- /dev/null
+++ b/.cursor/rules/led-driver.mdc
@@ -0,0 +1,45 @@
+---
+description: led-driver — MicroPython ESP32: mpremote, imports, layout, I/O, no pycache in src
+globs: led-driver/**
+alwaysApply: false
+---
+
+# led-driver (MicroPython / ESP32)
+
+## Device and tests
+
+1. Validate **MicroPython behaviour** under **`led-driver/`** with **`mpremote connect <PORT> …`** on the chip. Host **`python3`** does **not** prove the firmware build.
+
+2. **Execution target is fixed:** treat **`led-driver/`** code as firmware that runs **only on MicroPython ESP32 devices**. Do **not** run `led-driver/src/main.py` (or other firmware modules) with host CPython as a normal execution path.
+
+3. **Flow:** `mpremote connect <PORT> cp <local> :<on-flash>` then `run <script>.py`. Inline commands only — no **`.sh`** wrappers unless the user asks. Default serial placeholder: **`/dev/ttyACM0`**.
+
+4. Checks that **import and run** code from **`led-driver/src/`** belong in **`led-driver/tests/`** and run with **`mpremote run …`**. **Do not** add **`pytest`** under **`led-controller/tests/`** that **`sys.path`**-loads **`led-driver/src`** and runs those modules on CPython.
+
+## Import layout
+
+4. **No** **`sys.path.insert`**, **`__file__`** path stitching, or other import-path hacks under **`led-driver/`**. Use device flash search path, or host **`PYTHONPATH`** / layout you control.
+
+5. **No** “import fixer” code — fix copy order, flash paths, or env instead.
+
+## Imports (fail loudly)
+
+6. If a dependency does not load, **crash** and fix deployment or filesystem. **Do not** catch **`ImportError`** / **`ModuleNotFoundError`** around **`import`** / **`from … import`** for app/firmware modules (`settings`, `utils`, `network`, `machine`, …).
+
+7. **Allowed — stdlib name pairs only** (MicroPython vs CPython): one **`except ImportError`**, then **one** fallback import, **no** extra logic in **`except`**:
+   - `uos` → `os`
+   - `ubinascii` → `binascii`
+   - `utime` → `time`  
+   Not for “maybe the file exists on flash” — only different **stdlib** names.
+
+8. **No** large inline reimplementations after **`except ImportError`** — deploy the real module.
+
+## I/O
+
+9. Non-blocking **recv** / **accept**: use plain **`except OSError:`** (or **break** on empty). **No** errno / EAGAIN / EWOULDBLOCK tables or **`getattr(errno, …)`** unless fixing a **documented** target bug.
+
+10. Minimal **`try` / `except OSError`** around optional socket options (e.g. **`SO_REUSEADDR`**) is fine.
+
+## Host Python and `src/`
+
+11. **Do not** leave **`__pycache__/`** or **`.pyc`** under **`led-driver/src/`** from host runs. Remove if created; **`.gitignore`** already ignores it. Prefer **`PYTHONDONTWRITEBYTECODE=1`** or **`-B`** when host Python must touch **`led-driver/src/`**.
diff --git a/.cursor/rules/strict-user-scope.mdc b/.cursor/rules/strict-user-scope.mdc
new file mode 100644
index 0000000..87333ec
--- /dev/null
+++ b/.cursor/rules/strict-user-scope.mdc
@@ -0,0 +1,16 @@
+---
+description: enforce strict user-scoped changes only
+alwaysApply: true
+---
+
+# Strict User Scope
+
+1. Only implement exactly what the user asked for in the current message.
+
+2. Do not add extra refactors, cleanups, renames, architecture changes, or behavioural changes unless the user explicitly asked for them.
+
+3. If a potential improvement is noticed, mention it briefly and ask before changing code.
+
+4. For revert/undo requests, perform the narrowest possible revert and do not modify anything else.
+
+5. Keep edits minimal and local to the requested area.
diff --git a/.gitmodules b/.gitmodules
index 4a2c583..c06557f 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -4,3 +4,6 @@
 [submodule "led-tool"]
 	path = led-tool
 	url = git@git.technical.kiwi:technicalkiwi/led-tool.git
+[submodule "led-simulator"]
+	path = led-simulator
+	url = git@git.technical.kiwi:technicalkiwi/led-simulator.git
diff --git a/led-simulator b/led-simulator
new file mode 160000
index 0000000..7ce56b6
--- /dev/null
+++ b/led-simulator
@@ -0,0 +1 @@
+Subproject commit 7ce56b64df6d154d5d4cf103a9ab8b291e85c248