@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/packs/go/rules/go-errors-are-handled.md

@@ -0,0 +1,22 @@
+---
+paths:
+  - "**/*.go"
+---
+
+# Every error is handled or returned, wrapped with what was being done
+
+<constraints>
+Always do:
+- Return an error wrapped with `%w` and what was being attempted.
+- Take `ctx context.Context` first in anything that does I/O, and honour it.
+- Use the standard library or a maintained client for a protocol.
+- Run `go vet` and `staticcheck` in CI.
+
+Never do:
+- Discard an error with `_` on a state change or a parse.
+- Start a goroutine with no way to stop it.
+- Write a function again in another package: `template-law` reads Go.
+</constraints>
+
+## Check
+`go-unmarshal-error-ignored`, `go-exec-result-ignored`.

package/packs/gpu-painter/checks/dawn-backends-and-validation.json

@@ -0,0 +1,9 @@
+{
+  "id": "dawn-backends-and-validation",
+  "why": "Only Metal (macOS) and D3D12 (Windows) ship; extra Dawn backends add size and attack surface. skip_validation removes Dawn's safety net and is never used.",
+  "rule": ".claude/rules/dawn-build-and-shaders.md",
+  "concepts": ["build", "painter"],
+  "pattern": "DAWN_(ENABLE_(VULKAN|D3D11|NULL|DESKTOP_GL|OPENGLES)|BUILD_PROTOBUF)[\"']?\\s+(ON|TRUE|1)\\b|skip_validation",
+  "bad": "set(DAWN_ENABLE_VULKAN ON CACHE BOOL \"\" FORCE)",
+  "good": "set(DAWN_ENABLE_VULKAN OFF CACHE BOOL \"\" FORCE)"
+}

package/packs/gpu-painter/checks/dawn-no-spontaneous.json

@@ -0,0 +1,10 @@
+{
+  "id": "dawn-no-spontaneous",
+  "why": "AllowSpontaneous callbacks fire on any thread and re-entering the API from them is undefined; use AllowProcessEvents or WaitAnyOnly and pump events on the render thread.",
+  "rule": ".claude/rules/dawn-device-and-render-thread.md",
+  "concepts": ["painter", "ui", "app"],
+  "pattern": "CallbackMode::AllowSpontaneous|WGPUCallbackMode_AllowSpontaneous",
+  "code": true,
+  "bad": "instance.RequestAdapter (&opts, wgpu::CallbackMode::AllowSpontaneous, onAdapter);",
+  "good": "instance.RequestAdapter (&opts, wgpu::CallbackMode::AllowProcessEvents, onAdapter);"
+}

package/packs/gpu-painter/checks/dawn-present-on-render-thread.json

@@ -0,0 +1,17 @@
+{
+  "id": "dawn-present-on-render-thread",
+  "why": "Getting the surface texture and presenting must happen only on the render thread (Fifo present blocks; encoders are not thread-safe). Keep those calls in the render-thread files.",
+  "rule": ".claude/rules/dawn-device-and-render-thread.md",
+  "concepts": [
+    "painter",
+    "ui",
+    "app"
+  ],
+  "exclude": [
+    "@render_thread"
+  ],
+  "pattern": "\\bwgpuSurface(Present|GetCurrentTexture)\\s*\\(|\\.\\s*(Present|GetCurrentTexture)\\s*\\(",
+  "code": true,
+  "bad": "void Editor::paint (juce::Graphics&) { surface.GetCurrentTexture (&tex); surface.Present(); }",
+  "good": "void Editor::paint (juce::Graphics&) { renderThread.requestFrame(); }"
+}

package/packs/gpu-painter/checks/gpu-no-frame-stalls.json

@@ -0,0 +1,12 @@
+{
+  "id": "gpu-no-frame-stalls",
+  "why": "Blocking waits, sleeps, timer pacing, the message-thread lock or GPU readbacks on the frame path stall the render thread. Pace from the display link; read back only in tests.",
+  "rule": ".claude/rules/gpu-render-lifecycle.md",
+  "concepts": [
+    "painter"
+  ],
+  "pattern": "waitUntilCompleted|waitUntilScheduled|Thread::sleep|std::this_thread::sleep|startTimerHz\\s*\\(|MessageManagerLock|\\.\\s*MapAsync\\s*\\(|wgpuBufferMapAsync\\s*\\(",
+  "code": true,
+  "bad": "void RenderThread::frame() { juce::Thread::sleep (1); buffer.MapAsync (wgpu::MapMode::Read, 0, n, cb); }",
+  "good": "void RenderThread::frame() { encodePasses(); surface.Present(); }"
+}

package/packs/gpu-painter/checks/no-opengl-link.json

@@ -0,0 +1,11 @@
+{
+  "id": "no-opengl-link",
+  "why": "No target of a Dawn-painted app links JUCE's OpenGL module or the OpenGL framework (no-opengl.json holds the sources; Stellix work order F, F7.6).",
+  "rule": ".claude/rules/gpu-frame-work.md",
+  "concepts": [
+    "build"
+  ],
+  "pattern": "juce_opengl|-framework\\s+OpenGL\\b|OpenGL\\.framework|find_package\\s*\\(\\s*OpenGL\\b|OpenGL::",
+  "bad": "target_link_libraries (app_juce INTERFACE \"-framework OpenGL\" juce::juce_opengl)",
+  "good": "target_link_libraries (app_juce INTERFACE \"-framework QuartzCore\")"
+}

package/packs/gpu-painter/checks/no-opengl.json

@@ -0,0 +1,13 @@
+{
+  "id": "no-opengl",
+  "why": "OpenGL is not a drawing path in a Dawn-painted app: Dawn (WebGPU on Metal or D3D12) draws everything through the painter. A GL call, a GL constant, an OpenGL header or JUCE's OpenGL module or classes brings back a second drawing path the picture gates do not judge (Stellix work order F, F7.6, deleted it for good).",
+  "rule": ".claude/rules/gpu-frame-work.md",
+  "concepts": [
+    "cpp",
+    "shaders"
+  ],
+  "pattern": "\\bgl[A-Z][A-Za-z0-9]*\\s*\\(|\\bGL_[A-Z][A-Z0-9_]*\\b|#\\s*include\\s*<\\s*(OpenGL|GL|GLES[0-9]*|juce_opengl)/|\\bjuce_opengl\\b|\\bOpenGL(Context|Renderer|PixelFormat|Version|Profile|ShaderProgram|FrameBuffer|Image|Texture|Helpers|Extensions)\\b",
+  "code": true,
+  "bad": "class Editor : private juce::OpenGLRenderer { void renderOpenGL() override { glClear (GL_COLOR_BUFFER_BIT); } };",
+  "good": "void Frame::draw (const gpu::DrawTarget& t) { beginPass (t.encoder, &rp).End(); }"
+}

package/packs/gpu-painter/hooks/browser-guard.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""browser-guard: a natively drawn app never starts a browser. Its picture checks come from the app itself, drawn off-screen
+by the same code as the window, never through a browser (the house law for
+every GPU-painted synth).
+
+From Tabula 1's browser-guard.py (main 8d5e8b30), made stricter: Tabula allowed one launch script for a batch; this allows
+none. A PreToolUse hook on Bash, Write, Edit and MultiEdit. It exits 2 when the call starts Chrome or Chromium (the binary,
+`open -a`, puppeteer or playwright launching or connecting to one), or writes code that would. Looking at processes (ps,
+pgrep, grep) and words about a browser in .md, .txt, .json pass.
+
+The refusal names the project's own picture command: .claude/layout.json "guards": { "browser": { "pictureCommand" } }.
+
+Run `browser-guard.py --selftest` to see every rule fire on a planted call and every allowed call pass.
+"""
+import json, os, re, sys, time
+T0 = time.perf_counter()
+
+sys.dont_write_bytecode = True
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path[:0] = [os.path.join(HERE, "lib"), os.path.join(HERE, "..", "..", "base", "hooks", "lib")]   # installed; in the package
+import house  # noqa: E402
+
+DEFAULTS = {"pictureCommand": "the app's own off-screen render (the project's shot or picture program)"}
+
+
+def way(cfg=None):
+    c = {**DEFAULTS, **(cfg or {})}
+    return ("This app is drawn natively and never starts a browser. A picture comes from the app's own off-screen render, drawn by "
+            f"the same painter code as the window: {c['pictureCommand']}.")
+
+
+WAY = way()
+
+BIN = r"""(?:["']?[^\s"';|&]*(?:Google Chrome(?: for Testing)?(?:\.app/Contents/MacOS/Google Chrome(?: for Testing)?)?|google-chrome(?:-stable)?|chromium(?:-browser)?|chrome-headless-shell|headless_shell)["']?)"""
+LAUNCH_BASH = [
+    # the binary as the command of a segment (after env assignments, exec, nohup, timeout N, time)
+    re.compile(r"^(?:\s*\w+=\S*\s+)*(?:exec\s+|nohup\s+|time\s+|timeout\s+\S+\s+|/usr/bin/time\s+(?:-p\s+)?)*" + BIN + r"(?:\s|$)", re.I),
+    re.compile(r"\bopen\b[^|;&]*-a\s+[\"']?(?:Google Chrome|Chromium)", re.I),
+    re.compile(r"\.launch(?:PersistentContext|Server)?\s*\(|\bchrome-launcher\b"),
+    re.compile(r"\bnpx\s+(?:puppeteer|playwright)\b"),
+]
+LOOKING = re.compile(r"^\s*(?:ps|pgrep|pkill|kill|killall|grep|egrep|rg|ag|xargs\s+kill|which|ls|stat|file|mdls|defaults\s+read|echo|printf|cat|head|tail|wc|sed|awk)\b")
+# code that starts Chrome: a process call or launcher near a Chrome name or a headless flag
+CODE = [
+    re.compile(r"(?:spawn|spawnSync|execFile|execFileSync|exec|execSync|fork)\s*\([^)]{0,200}(?:chrome|chromium|--headless)", re.I | re.S),
+    re.compile(r"subprocess\.(?:run|Popen|call|check_call|check_output)\s*\([^)]{0,300}(?:chrome|chromium|--headless)", re.I | re.S),
+    re.compile(r"os\.(?:system|popen)\s*\([^)]{0,300}(?:chrome|chromium|--headless)", re.I | re.S),
+    # a driver launching or connecting to a browser
+    re.compile(r"\b(?:chromium|firefox|webkit|puppeteer|browserType)\s*\.\s*launch(?:PersistentContext|Server)?\s*\("),
+    re.compile(r"\bchrome-launcher\b"),
+    re.compile(r"\bconnectOverCDP\b|\bpuppeteer\s*\.\s*connect\s*\("),
+    re.compile(r"""['"]--headless(?:=new)?['"]"""),
+    re.compile(r"""['"]--screenshot(?:=|['"])"""),
+]
+
+def segments(cmd):
+    out, cur, q = [], "", None
+    for ch in cmd:
+        if q:
+            cur += ch
+            if ch == q: q = None
+        elif ch in "'\"":
+            q = ch; cur += ch
+        elif ch in ";|&\n":
+            out.append(cur); cur = ""
+        else:
+            cur += ch
+    out.append(cur)
+    return [s.strip() for s in out if s.strip()]
+
+def blank_heredocs(cmd):
+    """a heredoc's body is text handed to a program, not a command: blanked before the command scan (WB-20: C++ source
+    with w.launch(...) in it, written to a file by cat, was read as a browser launch). A script given to an interpreter
+    (node, python with a heredoc) is still read whole, below."""
+    out, lines, i = [], cmd.split("\n"), 0
+    while i < len(lines):
+        out.append(lines[i]); m = re.search(r"<<-?\s*['\"]?(\w+)['\"]?", lines[i]); i += 1
+        if m:
+            while i < len(lines) and lines[i].strip() != m.group(1): i += 1
+            if i < len(lines): out.append(lines[i]); i += 1
+    return "\n".join(out)
+
+def check_bash(cmd):
+    for seg in segments(blank_heredocs(cmd)):
+        if LOOKING.match(seg): continue
+        for rx in LAUNCH_BASH:
+            if rx.search(seg): return f"browser-guard: this starts Chrome directly (`{seg[:90]}`). {WAY}"
+    # a script handed to an interpreter inline (node -e, python -c, a heredoc)
+    if re.search(r"\b(?:node|python3?|deno|bun)\b", cmd):
+        for rx in CODE:
+            if rx.search(cmd): return f"browser-guard: this script starts Chrome itself. {WAY}"
+    return None
+
+def check_code(path, text):
+    if not text: return None
+    if str(path).endswith("browser-guard.py"): return None          # this file names what it catches
+    if re.search(r"\.(md|txt|json|csv)$", str(path)): return None   # words about Chrome, not code that starts it
+    for rx in CODE:
+        m = rx.search(text)
+        if m: return f"browser-guard: {path} would start Chrome itself (`{m.group(0)[:80]}`). {WAY}"
+    return None
+
+def inside(path, root):
+    """Only this project's files are judged on a write (a worktree's are the project's); a script written in another
+    project, a scratchpad or a test fixture starts nothing here (0.6.0: it refused a test that only names a launch)."""
+    if root is None: return True
+    p = house.main_root(os.path.abspath(os.path.join(root, str(path))))
+    return p == root or p.startswith(root.rstrip("/") + "/")
+
+def added_text(before, after):
+    """The lines a write adds (all of them for a new file), so code that was already there is not judged again."""
+    old = set((before or "").splitlines())
+    return "\n".join(l for l in (after or "").splitlines() if l not in old)
+
+def check(event, root=None):
+    tool, inp = event.get("tool_name", ""), event.get("tool_input", {}) or {}
+    if tool == "Bash":
+        cmd = inp.get("command", "")
+        r = check_bash(cmd)
+        if r: return r
+        # every file the shell writes, by any route (>, >>, tee, sed -i, cp, mv, a heredoc into a file; WB-69)
+        for w in house.shell_writes(cmd, event.get("cwd") or root or os.getcwd()) if re.search(r"[>|]|\b(cp|mv|sed|tee|install|rsync)\b", cmd) else []:
+            if w.get("after") is not None and inside(w["path"], root):
+                r = check_code(w["path"], added_text(w.get("before"), w["after"]))
+                if r: return r
+        return None
+    if tool == "NotebookEdit":
+        return check_code(inp.get("notebook_path", ""), inp.get("new_source", "")) if inside(inp.get("notebook_path", ""), root) else None
+    if not inside(inp.get("file_path", ""), root): return None
+    if tool == "Write": return check_code(inp.get("file_path", ""), inp.get("content", ""))
+    if tool == "Edit": return check_code(inp.get("file_path", ""), inp.get("new_string", ""))
+    if tool == "MultiEdit": return next((r for e in inp.get("edits", []) if (r := check_code(inp.get("file_path", ""), e.get("new_string", "")))), None)
+    return None
+
+def selftest():
+    G = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+    blocked = [
+        ("Bash", {"command": f'"{G}" --headless=new --screenshot=/tmp/a.png file:///tmp/a.html'}),
+        ("Bash", {"command": f"cd /tmp && '{G}' --headless --dump-dom file:///x.html > x"}),
+        ("Bash", {"command": "CHROME=1 google-chrome --headless --screenshot x"}),
+        ("Bash", {"command": "timeout 30 chromium --headless --print-to-pdf a.html"}),
+        ("Bash", {"command": 'open -a "Google Chrome" screenshots/a.png'}),
+        ("Bash", {"command": "node -e \"const p = require('puppeteer'); p.launch()\""}),
+        ("Bash", {"command": "node -e \"import('playwright').then(({chromium}) => chromium.launch())\""}),
+        ("Bash", {"command": "python3 - <<'EOF'\nimport subprocess\nsubprocess.run(['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome','--headless'])\nEOF"}),
+        ("Write", {"file_path": "/x/tools/shot.mjs", "content": "import { execFile } from 'node:child_process';\nexecFile(chrome, ['--headless=new', '--screenshot=a.png'])"}),
+        ("Edit", {"file_path": "/x/kit/synthpanel-creator/src/raster.js", "old_string": "a", "new_string": "execFileSync(chrome, ['--headless=new'])"}),
+        ("Write", {"file_path": "/x/tools/a.py", "content": "import subprocess\nsubprocess.run([CHROME, '--headless', url])"}),
+        ("Write", {"file_path": "/x/tools/b.js", "content": "import puppeteer from 'puppeteer';\nconst br = await puppeteer.launch();"}),
+        ("Write", {"file_path": "/x/onechrome.js", "content": "spawn(chrome, ['--headless=new'])"}),
+        ("Write", {"file_path": "/x/tools/d.mjs", "content": "const browser = await chromium.connectOverCDP(endpoint);"}),
+        ("Write", {"file_path": "/x/tools/c.mjs", "content": "import { chromium } from 'playwright';\nconst browser = await chromium.launch();"}),
+    ]
+    allowed = [
+        ("Bash", {"command": "ps -axo pid,command | grep -E 'Google Chrome.*--headless' | grep -v grep | awk '{print $1}' | xargs kill -KILL"}),
+        ("Bash", {"command": "out/synth_shot --render build/pictures/s3/a.png --size 3584x2016"}),
+        ("Bash", {"command": "grep -rn -- '--headless' kit/ | head"}),
+        ("Bash", {"command": "git commit -m 'B-382: one Chrome (no more google-chrome --headless per sprite)' -- bugs.md"}),
+        ("Write", {"file_path": "/x/bugs.md", "content": "one headless Chrome per sprite, execFile(chrome, ['--headless'])"}),
+        ("Edit", {"file_path": "/x/lib/painter/src/draw.cpp", "old_string": "a", "new_string": "panel.setLit (\"expand\", open);"}),
+        ("Bash", {"command": "cat > probes/reach/r.cpp <<'EOF'\n    w.launch(0, sim::Kind::head, kKey, 1, foot, vel, age);\nEOF\nbash tools/build.sh build r"}),   # WB-20
+    ]
+    blocked.append(("Bash", {"command": "node - <<'EOF'\nconst { chromium } = require('playwright'); await chromium.launch();\nEOF"}))   # WB-20: a heredoc node runs still counts
+    blocked.append(("Write", {"file_path": "/x/.claude/worktrees/agent-a/tools/e.mjs", "content": "await puppeteer.launch();"}))   # a worktree is the project
+    allowed.append(("Write", {"file_path": "/elsewhere/scratch/patch.py", "content": "s = 'await puppeteer.launch();'"}))     # another project's file
+    blocked.append(("Bash", {"command": "cat > /x/tools/s.mjs <<'EOF'\nconst b = await puppeteer.launch();\nEOF"}))           # WB-69: a heredoc into a file
+    blocked.append(("NotebookEdit", {"notebook_path": "/x/tools/n.ipynb", "new_source": "await chromium.launch()"}))
+    bad = 0
+    for tool, inp in blocked:
+        r = check({"tool_name": tool, "tool_input": inp}, "/x")
+        if not r: bad += 1; print(f"NOT BLOCKED: {tool} {json.dumps(inp)[:100]}")
+    for tool, inp in allowed:
+        r = check({"tool_name": tool, "tool_input": inp}, "/x")
+        if r: bad += 1; print(f"WRONGLY BLOCKED: {tool} {json.dumps(inp)[:100]}\n   {r[:120]}")
+    print(f"browser-guard selftest: {len(blocked)} launches blocked, {len(allowed)} other calls passed: {'PASS' if not bad else f'{bad} wrong'}")
+    return 1 if bad else 0
+
+def main(event):
+    global WAY
+    WAY = way(house.guard("browser", DEFAULTS))
+    reason = check(event, house.main_root(house.project_root()))
+    if reason:
+        print(reason, file=sys.stderr)
+        return 2
+    return 0
+
+if __name__ == "__main__":
+    if "--selftest" in sys.argv: sys.exit(selftest())
+    try: event = json.load(sys.stdin)
+    except Exception: sys.exit(0)
+    code = 1
+    try:
+        code = main(event)
+    finally:   # one timing line per call (KWB-24), through the shared helper
+        house.log_hook("browser-guard", event.get("hook_event_name"), (time.perf_counter() - T0) * 1000, code, event.get("tool_name"))
+    sys.exit(code)

package/packs/gpu-painter/pack.json

@@ -0,0 +1,91 @@
+{
+  "name": "gpu-painter",
+  "version": "1.0.0",
+  "description": "GPU-drawn UI on Dawn (Metal on Mac, Direct3D 12 on Windows), drawn natively: no OpenGL, no browser.",
+  "type": "stock",
+  "author": "claude-packs",
+  "license": "MIT",
+  "homepage": "https://github.com/TheDecipherist/claude-packs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheDecipherist/claude-packs.git",
+    "directory": "packs/gpu-painter"
+  },
+  "keywords": [
+    "gpu",
+    "dawn",
+    "webgpu"
+  ],
+  "engines": {
+    "claude-packs": ">=0.19.0"
+  },
+  "folders": {
+    "painter": {
+      "path": "src/painter",
+      "purpose": "the GPU renderer: Dawn device, surfaces, passes, the snapshot reader"
+    },
+    "shaders": {
+      "path": "src/painter/shaders",
+      "purpose": "WGSL shaders"
+    },
+    "ui": {
+      "path": "src/ui",
+      "purpose": "input, gestures, camera, picking, undo (no drawing code)"
+    }
+  },
+  "concepts": {
+    "painter": [
+      "painter"
+    ],
+    "shaders": [
+      "shaders",
+      "**/*.wgsl"
+    ],
+    "ui": [
+      "ui"
+    ]
+  },
+  "skillsIn": "painter",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/browser-guard.py\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  },
+  "files": {
+    "render_thread": "src/painter/render_thread.cpp"
+  },
+  "kinds": {
+    "gpu-code": {
+      "what": "anything that calls Dawn/WebGPU: device, surface, passes, the render thread",
+      "in": "painter",
+      "concepts": [
+        "painter",
+        "tests"
+      ],
+      "content": "\\b(wgpu::|wgpu[A-Z]\\w*\\s*\\(|WGPU[A-Z]\\w+)"
+    },
+    "shader": {
+      "what": "WGSL shaders",
+      "in": "shaders",
+      "concepts": [
+        "painter"
+      ],
+      "files": [
+        "**/*.wgsl"
+      ]
+    },
+    "ui-input": {
+      "what": "input, gestures, camera, picking and undo (no drawing code)",
+      "in": "ui"
+    }
+  }
+}

package/packs/gpu-painter/rules/dawn-build-and-shaders.md

@@ -0,0 +1,27 @@
+---
+# concepts: build, shaders, painter
+paths:
+  - "placeholder"
+---
+
+# Dawn is pinned and built by us; shaders are embedded and validated at build time
+
+<constraints>
+Always do:
+- Pin one Dawn commit, built from source with CMake (`DAWN_BUILD_MONOLITHIC_LIBRARY`, `find_package(Dawn)`, link `dawn::webgpu_dawn`), and sign it with the plugin. Dawn has no semver, its API changes often, and its GitHub nightlies are unsigned.
+- Build only the backends we ship: Metal on macOS, Direct3D 12 on Windows. Turn off Vulkan, D3D11, the null backend, desktop GL, protobuf, and Tint's tests and command-line tools.
+- Measure what Dawn adds to the plugin binary after dead-stripping, and record it in the build notes.
+- Embed WGSL into the binary at build time, and validate every shader offline in CI with the `tint` command-line tool.
+- Wire Dawn's blob cache (a `DawnCacheDeviceDescriptor` with load/store callbacks) with an isolation key that includes the plugin version, so the second launch skips shader compilation.
+- Ship Dawn's BSD-3-Clause notice and its dependencies' licence notices (Abseil, Apache-2.0) in the credits.
+- Debug builds: Full backend validation, `dump_shaders_on_failure`, `use_user_defined_labels_in_backend`, and labels on every pipeline and pass.
+
+Never do:
+- Use the `skip_validation` toggle, even in release builds.
+- Build shader source from strings at runtime.
+- Update the pinned Dawn commit without running the golden-image and frame-bench gates.
+</constraints>
+
+## Check
+- `.claude/checks/dawn-backends-and-validation.json` blocks extra backends and `skip_validation`.
+- CI: `tint` validates every `.wgsl`; the bench shows second-launch pipeline creation under 10% of the first.

package/packs/gpu-painter/rules/dawn-device-and-render-thread.md

@@ -0,0 +1,26 @@
+---
+# concepts: painter
+paths:
+  - "placeholder"
+---
+
+# One Dawn device per process, one render thread, and every GPU call on it
+
+<constraints>
+Always do:
+- Keep one process-wide, reference-counted `wgpu::Instance` and `wgpu::Device` shared by every plugin instance. The last editor or processor to release it destroys the device and joins Dawn's worker threads, before the plugin bundle can unload.
+- Run every command encoder, `GetCurrentTexture` and `Present` on the one render thread. Encoders are never thread-safe, and a Fifo present blocks its thread.
+- Use `CallbackMode::AllowProcessEvents` or `WaitAnyOnly` for every async call, and pump events on the render thread.
+- Install both the device-lost callback and the uncaptured-error callback. On device loss, rebuild the device and every GPU resource, and the frame must come back on its own.
+- Present with `PresentMode::Fifo`. On Metal, Dawn treats Fifo and Mailbox the same.
+
+Never do:
+- Use `CallbackMode::AllowSpontaneous`. Callbacks then fire on any thread, and calling back into the API from them is undefined behaviour.
+- Present or encode on the message thread or the audio thread.
+- Rely on `ImplicitDeviceSynchronization` to make multi-threaded use safe. Dawn's own docs call it heavy-handed, with deadlock risk.
+</constraints>
+
+## Check
+- `.claude/checks/dawn-no-spontaneous.json` and `dawn-present-on-render-thread.json` block the forbidden patterns.
+- Test: force `device.Destroy()` mid-session. Pass: the frame comes back and no errors are left unhandled.
+- `gpu-lifecycle-stress`: zero Dawn threads remain after the last release.

package/packs/gpu-painter/rules/gpu-antialiasing.md

@@ -0,0 +1,20 @@
+---
+# concepts: shaders, painter
+paths:
+  - "placeholder"
+---
+
+# Thin lines are antialiased in the shader; MSAA only for silhouettes
+
+<constraints>
+Always do:
+- Draw orbit rings, ghost paths, border lines and the UI as instanced quads or signed-distance shapes, with analytic coverage: distance divided by `fwidth`, smoothed over about 1 pixel.
+- Use 4x MSAA only for planet and crystal silhouettes (WebGPU allows 1 or 4). On Apple GPUs, give the MSAA colour and depth attachments transient usage so they stay in tile memory.
+
+Never do:
+- Use TAA (ghosting on moving thin lines) or FXAA (blurs text).
+- Draw hairlines as 1-pixel GPU lines and hope.
+</constraints>
+
+## Check
+Golden test: a 0.5–1 px ring at 1x and 2x shows no stair-steps; frame-to-frame FLIP on a slow rotation stays below 0.01 (no shimmer).

package/packs/gpu-painter/rules/gpu-blend-order.md

@@ -0,0 +1,22 @@
+---
+# concepts: painter, shaders
+paths:
+  - "placeholder"
+---
+
+# Draw order: opaque, then additive glows, then sorted transparency, then overlay
+
+<constraints>
+Always do, in this order:
+1. Opaque planet bodies, with depth write.
+2. Emissive glows, travellers, trails and the nebula as additive blending (One, One), with depth test on and depth write off. Addition doesn't care about order, so these need no sorting.
+3. The few truly transparent surfaces (the crystal, tags) sorted back to front per object on the CPU.
+4. The 2D overlay (columns, menus, readouts) last, in its own pass.
+
+Never do:
+- Use alpha blending for glows (they need sorting and still go wrong).
+- Add order-independent transparency. Weighted blended OIT is an approximation with tuning cost, only worth it with many overlapping coloured alpha layers, which Stellix doesn't have.
+</constraints>
+
+## Check
+Golden test: the additive set rendered in permuted order gives an identical image.

package/packs/gpu-painter/rules/gpu-bloom.md

@@ -0,0 +1,20 @@
+---
+# concepts: shaders, painter
+paths:
+  - "placeholder"
+---
+
+# Bloom is a thresholdless mip pyramid with firefly suppression
+
+<constraints>
+Always do:
+- Use the Jimenez (Call of Duty: Advanced Warfare) chain: downsample the HDR target over 5–6 levels from half resolution, with the Karis 1/(1+luma) weighted average on the first downsample only; upsample with a 3×3 tent, adding each level as it goes; composite at low strength (around 0.04).
+- In calm mode, use the cheaper dual-Kawase chain at reduced strength.
+
+Never do:
+- Use a brightness threshold (pops as values cross it), or a single wide Gaussian at full resolution.
+- Skip the Karis weighting. Small hot pixels (travellers, text glows) flicker without it.
+</constraints>
+
+## Check
+`gpu-frame-bench`: bloom p99 ≤ 0.5 ms GPU on the M1 Pro at 2x (house target), and no frame-to-frame flicker in a slowly moving scene (FLIP between frames below 0.01).

package/packs/gpu-painter/rules/gpu-frame-budget.md

@@ -0,0 +1,25 @@
+---
+# concepts: painter, bench
+paths:
+  - "placeholder"
+---
+
+# The space meets its frame budget on the minimum machine, with several copies open
+
+From spec §7.3 and §9.
+
+<constraints>
+Always do:
+- Judge every budget (world, painter, audio) on the **minimum machine, an Apple M1 Pro (2021)**. The development machine (M5 Max) is never the judge. There's no Intel or Rosetta build.
+- Measure the two budgets separately: the world tick against the audio budget (96 held notes, every border open) and the drawing against the frame budget. A test that runs the world inside the frame reports both numbers, never one.
+- Measure with several copies of Stellix open at once. They share one Dawn device and one render thread, so one slow copy delays the others.
+- Measure GPU time with Dawn's `TimestampQuery` feature at pass boundaries, resolved and read back one or two frames later so the read never stalls. Dawn quantises timestamps by default (`timestamp_quantization` toggle); turn that off in bench and dev builds. Measure render-thread CPU time around the frame.
+- Report GPU time and painter-thread CPU time at p99. A counter that didn't run is *invalid*, never 0 ms.
+- Read the pattern: GPU time low but frame time high means sync, driver wait or present pacing. Times bunched at the display interval mean vsync.
+
+Never do:
+- Judge performance on the dev machine, by eye, or by average FPS.
+</constraints>
+
+## Check
+`gpu-frame-bench` on the M1 Pro: p99 within the budget numbers in the work order. House proposal until those are set: GPU ≤ 8 ms and painter CPU ≤ 2 ms at 2x scale, with 4 copies open. The CPU gate from `gpu-frame-work.md` must pass too.

package/packs/gpu-painter/rules/gpu-frame-pacing-and-power.md

@@ -0,0 +1,27 @@
+---
+# concepts: painter, ui
+paths:
+  - "placeholder"
+---
+
+# Frames are drawn only when something changes, at the lowest rate that looks right
+
+<constraints>
+Always do:
+- Render only when something changed: a parameter, live audio data (waveform, spectrum), travellers in flight, idle motion, or hover and drag. With nothing changing, present nothing.
+- Run idle animation at 60 Hz. Allow 120 Hz only while the player is dragging or interacting.
+- On Mac, drive frames from the display link (`CAMetalDisplayLink`, macOS 14+) with a preferred frame-rate range on whole-number divisions (120, 60, 30). Respect Low Power Mode and thermal state.
+- Calm mode: 30 Hz, fewer particles, dual-Kawase bloom. Also honour the OS reduce-motion setting.
+- Stop rendering (0 Hz) for hidden or covered editors.
+
+Never do:
+- Render continuously at the display maximum by default.
+- Keep the GPU busy for a static, unchanged window.
+</constraints>
+
+## Check
+Bench (house targets):
+- A static idle window presents 0 frames per second.
+- Animated idle costs ≤ 2 ms GPU per frame on the M1 Pro.
+- With 8 editors open, render-thread CPU totals ≤ 5%.
+- Compare GPU power at 60 and 120 Hz with `powermetrics`.

package/packs/gpu-painter/rules/gpu-frame-work.md

@@ -0,0 +1,30 @@
+---
+# concepts: painter, shaders
+paths:
+  - "placeholder"
+---
+
+# Everything is drawn on the graphics card; the CPU only hands over the snapshot
+
+From spec §0 rules 1–3 and §9.
+
+<constraints>
+Always do:
+- Draw everything on the card: the space, the columns, the controls, the keyboard band, the menus and text (a glyph atlas on the card, built from the shipped font files).
+- Compute geometry, facets, noise, refraction, particles, bloom and tone mapping in shaders. The CPU's drawing job is one thing: upload the snapshot once a frame.
+- Draw each particle system and object set (travellers, shatter pieces, comets, delay balls) with one instanced draw.
+- Upload only what changed: the snapshot, plus waveform rings by sub-range.
+- Keep frames in flight bounded, with per-frame buffers, so the CPU never overwrites what the card is reading.
+- Compile shaders once (at build, or once at startup from embedded source) and cache the pipelines.
+- Draw static controls once into memory when the window opens or resizes. The cache is made at runtime at that size, never shipped, and leaves motion unchanged.
+
+Never do:
+- Add a software drawing path or a fallback to one (Tabula's D6 doesn't apply to Stellix).
+- Compute anything per vertex or per pixel on the CPU.
+- Ship any image. The `no-shipped-images` hook refuses image files in source and resources; fonts are allowed.
+- Read GPU results back during normal frames (test harness only).
+</constraints>
+
+## Check
+- CPU gate: time the CPU side of a frame. It goes red if it exceeds the snapshot upload by more than a small fixed margin.
+- Frame bench counters: draw calls and uploaded bytes per frame (house choice: ≤ 50 draw calls in the reference scene).

package/packs/gpu-painter/rules/gpu-golden-images.md

@@ -0,0 +1,21 @@
+---
+# concepts: painter, shaders, tests
+paths:
+  - "placeholder"
+---
+
+# What the 3D space looks like is proven by golden images
+
+<constraints>
+Always do:
+- Render fixed scenes offscreen (fixed seed, fixed time, fixed size) at 1x and 2x scale, with fixed time, fixed seed and dithering off. Read them back in the test harness and compare against stored goldens kept per backend (Metal and Direct3D 12 differ in derivatives and precision). Compare with NVIDIA's ꟻLIP (BSD-3, single-header C++), not PSNR. Pass (house): mean FLIP ≤ 0.01 and 99th percentile ≤ 0.1 per scene; on the same machine and driver, repeat renders are bit-identical.
+- Prove visual changes through the real user-facing path: the standalone with the real editor. Logs or JSON saying "rendered" prove nothing about what the user sees.
+- Update goldens only for an intended visual change, with before and after images shown to the user (`gpu-golden-update` skill).
+
+Never do:
+- Mark a visual task done because the code compiles or the logs look right.
+- Regenerate goldens to make a failing test pass.
+</constraints>
+
+## Check
+`gpu-golden-check` skill runs the image-diff tests. They fail over the FLIP thresholds and save the FLIP error heatmap.