Cursor rule

1---
2description: StelluxOS engineering conventions for commits, code style, stacked-commit review, and verification gates
3alwaysApply: true
4---
5 
6# StelluxOS Engineering Conventions
7 
8## Commit style
9 
10- Google style with domain scopes from repo history: `feat(sched):`, `feat(sysstat):`, `feat(client):`, `feat(userland):`, `feat(syscall):`, `fix(signals):`. Client = userland graphics/desktop.
11- Subject verbs in past tense: "added", "implemented", "rendered", "accounted".
12- Body: 2-4 sentences on WHY (the problem that existed, why this approach). No implementation play-by-play. Timeless wording, no "this PR/commit", no Linux mentions.
13- Work lands as a stack of small self-contained commits, each independently buildable and testable. Lib primitives may land with their first consumer.
14 
15## Code style
16 
17- Struct definitions and file-scope globals belong at the top of the file, above all function definitions, in both headers and .c/.cpp files.
18- Kernel modules use `namespace <module> { namespace { ... } }` for internals (see `kernel/random/random.cpp` as the template for devfs drivers).
19- Kernel test files use file-scope `static`, never anonymous namespaces (match `kernel/tests/sched/preemption.test.cpp`). Per-test globals sit adjacent to their test.
20- Comments: ASCII only, 1-2 lines, explain intent not mechanics. Headers use doxygen blocks with `@note Privilege: **required**` for privileged functions.
21- Public kernel APIs carry `__PRIVILEGED_CODE`; follow existing error-constant patterns (`fs::ERR_*`, per-module `OK`/`ERR`).
22- Userland apps: `APP_NAME := x` Makefile + `include ../../mk/app.mk`, register in `userland/apps/Makefile` APP_DIRS.
23 
24## Stacked-commit review workflow
25 
26- The user reviews commit-by-commit and comments in chat; feedback is folded into the commit where the code was born, not fixup commits.
27- To edit mid-stack: create `backup/<name>-vN` branch, `git reset --hard <base>`, then per commit `git cherry-pick -n <sha>`, edit, commit with the original message (updated if the change warrants). Never `git rebase -i`, never amend pushed commits.
28- After rebuilding a stack, verify `git diff backup/... HEAD` shows only the intended change, then rebuild and re-run the suite.
29- Work directly on master only when the user says so; they push themselves. Delete backup branches only after the user pushes.
30 
31## Verification gates
32 
33- Every kernel-touching stack: `make test ARCH=x86_64` and `ARCH=aarch64` fully green plus compile checks on both arches for every commit.
34- Userland/visual changes: live QEMU verification with before/after screenshots (see the stellux-qemu-testing skill). Present zoomed comparison crops in chat.
35- Delegate realistic interactive/visual testing to the user when they offer; they orchestrate GUI sessions better. Prepare diagnostic flags or builds for them instead of guessing.
36- `make test` leaves a test-flavored build; run `make clean && make image ARCH=x86_64` afterward so the shipped image matches committed code.
37