@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

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.

package/packs/gpu-painter/rules/gpu-hdr-and-tonemap.md

@@ -0,0 +1,23 @@
+---
+# concepts: painter, shaders
+paths:
+  - "placeholder"
+---
+
+# Render in linear HDR, tonemap once with PBR Neutral, output sRGB
+
+<constraints>
+Always do:
+- Render the space into an `rgba16float` target in linear light.
+- Run one final pass: exposure, then Khronos PBR Neutral (identity below its compression start, so the slot colours stay true; only highlights compress), then write to a `BGRA8Unorm` surface encoded as sRGB.
+- Keep the slot colours (amber, cyan, magenta, green, white) defined once, in linear, in the records.
+
+Never do:
+- Use ACES (shifts hues) or AgX (desaturates) on a palette that has to read as exact slot colours.
+- Turn on EDR or wide colour in v1. Dawn currently rejects surface colour management, and very bright output next to a DAW is hostile. Display P3 can come later on Mac through the `CAMetalLayer`'s colour space.
+- Tonemap in more than one place.
+</constraints>
+
+## Check
+- Golden swatch-and-gradient scene: after 8-bit output, Mac and Windows agree within ±1 LSB.
+- Test: PBR Neutral returns its input within 1/255 below 0.76.

package/packs/gpu-painter/rules/gpu-picking-on-cpu.md

@@ -0,0 +1,19 @@
+---
+# concepts: ui, painter
+paths:
+  - "placeholder"
+---
+
+# Hover and drag picking is a CPU ray test against the frame's own transforms
+
+<constraints>
+Always do:
+- Pick with a CPU ray against spheres (or capsules for rings and paths), using the planet and moon transforms of the same frame the renderer drew.
+- Resolve hover within the same frame the mouse moved in.
+
+Never do:
+- Pick by reading back a GPU ID buffer. The readback lands at least a frame late, adds a stall or copy, and buys nothing for about 50 objects.
+</constraints>
+
+## Check
+Unit tests with a fixed camera and positions: hits are exact at sphere edges ±0.5 px, and hover changes in the same frame.

package/packs/gpu-painter/rules/gpu-render-lifecycle.md

@@ -0,0 +1,25 @@
+---
+# concepts: painter, ui
+paths:
+  - "placeholder"
+---
+
+# The painter starts after the window exists, renders only while visible, and stops before anything is freed
+
+<constraints>
+Always do:
+- Create the native view only once the editor's native peer exists and has bounds: on macOS a child `NSView` backed by a `CAMetalLayer` inside an `NSViewComponent`; on Windows a child `HWND` inside an `HWNDComponent`. Make the Dawn surface from it (`WGPUSurfaceSourceMetalLayer` / `WGPUSurfaceSourceWindowsHWND`).
+- Configure the surface in pixels: logical size × `backingScaleFactor` (or the Windows DPI scale). Set the `CAMetalLayer`'s `contentsScale` yourself, because Dawn doesn't. Reconfigure on every resize and screen change.
+- Handle every `GetCurrentTexture` status explicitly: `Outdated`, `Lost` and `SuccessSuboptimal` mean reconfigure; `Timeout` means skip this frame.
+- Stop rendering (0 Hz) when the editor is closed, hidden, minimised or covered.
+- Tear down in this order: stop the render thread and wait for its last frame, release the surface, then destroy the view.
+
+Never do:
+- Create the view in the editor's constructor before the peer exists.
+- Keep rendering with the editor closed. A closed editor costs 0% render CPU.
+- Free the view, layer or surface while the render thread may still present to it.
+</constraints>
+
+## Check
+- `gpu-lifecycle-stress`: open and close the editor 100 times under AddressSanitizer with audio at 96 voices, then 8 copies at once. Pass: no reports, no leaks, render CPU 0 after the last close.
+- Golden test at scale 2.0, plus a test that the surface texture size equals the view bounds × scale.

package/packs/gpu-painter/rules/gpu-text-atlas.md

@@ -0,0 +1,24 @@
+---
+# concepts: painter, shaders
+paths:
+  - "placeholder"
+---
+
+# Text is drawn from a glyph atlas the app builds from the shipped fonts
+
+Spec rule 2 allows fonts as files and runtime caches; this is how text uses both.
+
+<constraints>
+Always do:
+- Build an MTSDF atlas (multi-channel distance field plus a true distance channel) at runtime from the shipped TTF/OTF files with msdfgen and msdf-atlas-gen (MIT), with FreeType under its FTL licence for loading outlines.
+- For small text (under about 12 px on screen), rasterise a hinted grey atlas per scale factor at runtime (FreeType, or JUCE drawing glyphs into an `Image`). Distance fields look soft at that size.
+- Rebuild the atlas when the scale changes (100–200%), never ship one.
+- Credit FreeType in the docs as its FTL licence requires.
+
+Never do:
+- Ship a pre-built atlas image (that's a pre-rendered image; the `no-shipped-images` hook refuses it).
+- Rasterise text on the CPU every frame.
+</constraints>
+
+## Check
+Golden text sheet at 9, 11, 14 and 24 pt × 100, 150 and 200%. Pass (house): FLIP mean below 0.02 against a hinted FreeType reference at small sizes, and no corner rounding visible at 24 pt. Upgrade path if MSDF artefacts show: Slug (patent now public domain, MIT/Apache reference shaders).

package/packs/gpu-painter/rules/gpu-travellers-from-snapshot.md

@@ -0,0 +1,24 @@
+---
+# concepts: painter, shaders, world
+paths:
+  - "placeholder"
+---
+
+# Travellers are drawn from the world snapshot, never simulated on the GPU
+
+Spec §8: the world (on the audio side) decides every position; the painter only shows it.
+
+<constraints>
+Always do:
+- Upload the snapshot's traveller list (up to the TRAVELLERS cap of 1024: notes, shatter pieces, sparks) once per tick into one storage buffer.
+- Draw every traveller with one instanced call: billboards with corners generated from `vertex_index`, no vertex buffer.
+- Draw trails from a ring of each traveller's last positions, as instanced ribbon segments.
+- Smooth motion between ticks by interpolating the last two snapshots on the GPU.
+
+Never do:
+- Integrate traveller physics in a compute shader or anywhere in the painter. A second copy of the formulas in WGSL drifts from the C++ world, and then the picture lies about the sound.
+- Upload per-traveller data more than once per tick.
+</constraints>
+
+## Check
+Frame bench at 1024 travellers with trails. Pass (house): ≤ 2 draw calls for travellers and trails, upload no more than one snapshot per tick, ≤ 0.3 ms GPU.

package/packs/gpu-painter/rules/hover-every-pressable.md

@@ -0,0 +1,25 @@
+---
+# concepts: ui
+paths:
+  - "placeholder"
+---
+
+# Everything the pointer can act on says so: a cursor for the interaction and a small effect on the hovered thing
+
+<constraints>
+Always do:
+- Give every element the pointer can act on (a control, a point or handle, a tab, a list row, a key, a button, a text field) two things when the pointer is over it: (a) a cursor that names the interaction (drag up-down, drag left-right, drag both ways, press, text) and (b) a small visible effect on that element itself (lift, ring, brighten, glow).
+- Find the hovered item with the same function the press uses (one hit test). The press and the hover share it, so a thing drawn as interactive cannot be missing from the hover; never keep a second list of hoverable things.
+- Draw the effect on the hovered item's own pixels, ease it in and out (a glide of about 0.1 s) on the frame clock, and let it come back to rest when the pointer leaves.
+- Give a new control its hover in the same change that gives it its press, and prove it with the hover walk in the skill `hover-state`: the gate moves the pointer over one item of each template and every one-off, and reads that the cursor and the drawn pixels change.
+- Use the disabled look only for what is truly disabled (it does not respond to a press). A control that responds gets the hover.
+
+Never do:
+- Ship a control, handle, tab or row that responds to a press and has no hover (a pointer that does not change and a thing that does not react).
+- Choose one cursor for everything: the cursor names what the interaction is.
+- Let the hover effect spill onto its neighbours (a ring or glow round the item is fine; the items beside it must not change).
+- Wire hover from a separate list, a duplicate of the hit test or a per-control flag that the press does not read.
+</constraints>
+
+## Check
+The project's hover gate (layout.json `gates.hover`): a hover walk over every pressable item, red if any item's cursor or own pixels do not change, or if it does not return to rest. `doctor` is red while UI code exists and no gate is declared.

package/packs/gpu-painter/skills/gpu-capture/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: gpu-capture
+description: Use when a planet, glow, traveller or text renders wrong, or GPU time is high and the frame bench alone doesn't show why.
+---
+
+# GPU capture (one job: get a frame capture of one scene)
+
+## Steps
+1. Build the debug painter with labels on every pipeline and pass (`use_user_defined_labels_in_backend`).
+2. **Mac:** run with `MTL_CAPTURE_ENABLED=1` and `DAWN_TRACE_FILE_BASE=captures/<scene>-<date>`. Dawn writes a `.gputrace` through `MTLCaptureManager`. Load the named scene and trigger the capture for N frames (default 3).
+3. **Windows:** run under PIX with `WinPixEventRuntime.dll` next to the executable; Dawn emits PIX begin/end markers from the labels. Dawn's own D3D12 trace isn't implemented, so PIX is the tool.
+4. Tell the user the capture path, and that it opens in Xcode (Mac) or PIX (Windows).
+
+## Report
+Capture path, scene, frame count, build and backend. Don't analyse the capture in this skill.

package/packs/gpu-painter/skills/gpu-frame-bench/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: gpu-frame-bench
+description: Use when the space stutters or feels slow, after painter or shader changes, or before merging GPU work.
+---
+
+# GPU frame bench (one job: is the renderer inside its budget?)
+
+## Steps
+1. Build Release with the shipping flags, then run the project's `frame-bench` command (CLAUDE.md, Project commands) on the reference scenes, at 1x and 2x scale, with audio running at 96 voices.
+2. Read its JSON: p99 GPU ms (Dawn timestamp queries, opt-in, resolved and read back a frame or two later; the gpu-frame-budget rule), p99 render-thread CPU ms, draw calls per frame, bytes uploaded per frame, and the validity flag of each counter.
+3. Compare against `.claude/rules/gpu-frame-budget.md` (judged on the M1 Pro with 4 copies open; house proposal GPU ≤ 8 ms, painter CPU ≤ 2 ms at p99 until the work order sets numbers) and `gpu-frame-work.md` (≤ 50 draw calls).
+
+## Report
+One row per scene with each figure and PASS/FAIL. Read the pattern before guessing a cause: low GPU but high frame time means sync or present pacing, and times bunched at the display interval mean vsync. Treat an invalid counter as a FAIL, never as 0. Don't change code in this skill.

package/packs/gpu-painter/skills/gpu-golden-check/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: gpu-golden-check
+description: Use after any painter, shader or look change, and before calling visual work done.
+---
+
+# Golden image check (one job: did what the user sees change?)
+
+## Steps
+1. Run the project's `picture-gates` command (CLAUDE.md, Project commands): the golden-image tests (fixed seed, time and size; 1x and 2x; per-platform goldens).
+2. For each failing scene, open the saved diff image and the rendered image.
+
+## Report
+Each scene with its mean and 99th-percentile FLIP and PASS/FAIL (threshold from `gpu-golden-images.md`), and a one-line description of what visibly changed in each failure. Never update goldens here. If the change was intended, say so and stop; the user runs `gpu-golden-update`.

package/packs/gpu-painter/skills/gpu-golden-update/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: gpu-golden-update
+description: Use only when the user confirms a visual change is intended and asks to update the golden images.
+---
+
+# Golden image update (one job: accept an intended visual change)
+
+<constraints>
+Always do:
+- Show the user the old golden, the new render and the diff for every scene that will change, and wait for a yes.
+- Update only the scenes that were approved. Log the change, and why, in the project's changes or bugs file.
+
+Never do:
+- Update goldens to make a failing test pass without the user's approval of the images.
+- Update every scene when only some were meant to change.
+</constraints>

package/packs/gpu-painter/skills/gpu-lifecycle-stress/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: gpu-lifecycle-stress
+description: Use after changing how the view, surface, device or render thread start or stop.
+---
+
+# GPU lifecycle stress (one job: prove the 3D view starts and stops cleanly)
+
+## Steps
+1. Build the AddressSanitizer configuration of the standalone with the project's `build` command (and later the plugin, in a test host).
+2. With audio rendering at 96 voices, open and close the editor 100 times, hide and show it, and change the display scale (1x/2x).
+3. Run 8 instances at once in the host.
+4. Record ASan reports, leaks, audio overruns, and render-thread CPU after the last close.
+
+## Report
+Pass only if: no ASan reports, no leaks, zero audio overruns, and render CPU of 0 with the editor closed (`gpu-render-lifecycle.md`). For any failure give the stack and the lifecycle step it happened in. Don't change code in this skill.

package/packs/gpu-painter/skills/hover-state/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: hover-state
+description: Use when a control, handle, tab, list row, key or button is added or changed in a drawn UI, when a user says something does not react under the mouse, or when a hover gate is written or fails.
+---
+
+# Hover state (one job: every pressable thing answers the pointer, and a gate proves it)
+
+The law is the rule `hover-every-pressable`: a cursor naming the interaction, and a small visible effect on the hovered thing itself. The hover follows the press's own hit test.
+
+## Add the hover to a new control
+1. Find the one function the press uses to find the item under the pointer (the hit test). If there is none, make one and have the press call it.
+2. Have the mouse-move path call that same function and store the result (the hovered id). Do not keep a second list of hoverable things.
+3. Pick the cursor from the interaction, not the look: drag up-down, drag left-right, drag both ways (a 2-D point), press (button, tab, row, key), text. Set it from the hovered id.
+4. Draw the effect on the item's own pixels from the hovered id: a lift, a ring, a brighten. Ease it over about 0.1 s on the frame clock (not the wall clock, or two runs differ). A neighbour must not change.
+5. Disabled looks are for what is truly disabled. If the press works, the hover shows.
+6. Add the item to the hover walk (below) in the same change.
+
+## Prove it: the hover walk
+A gate that runs the real window (or the real page) and, for one item of each template and every one-off the pointer can act on (`test-the-template-once`: a template's other instances are proved by a read that they are built from it):
+1. moves the pointer there through the same function a mouse move calls, and waits the glide on the virtual frame clock;
+2. reads that the hover model found the item the press finds there (the two lists agree);
+3. reads that the cursor is the interaction's;
+4. reads the pixels of the item's box and of a ring round it, hovered against at rest: the box changes by a floor (pixels and share), the ring does not;
+5. moves away and reads that the box came back to rest.
+Rows a press cannot reach (another control covers every point) are listed, not judged. Run it twice and require one digest (a wall-clock hover differs between runs).
+
+Plant its faults so the gate is seen red: hover off altogether, one kind of item with no cursor or effect, one kind drawn interactive but left off the hover list, the wall clock in place of the frame clock. A gate never seen red is not a gate.
+
+## Declare it
+`layout.json`: `"gates": { "hover": "<the command>" }`. `doctor` is red while the project has UI code and no gate is declared, or the declared command names a file that is not there. A project with truly no pointer says `"hover": "none: <reason>"`.
+
+## Worked example
+Stellix: `tools/gates/hover_gate.sh` (the runner and its `--selftest` plants), `lib/app/gates/editor_hoverwalk_read.h` (the walk that hovers every item through the mouse-move path), `tools/gates/hover_judge.py` (the judge: cursor per kind, own pixels change, ring does not, comes back). Read them for the shape; the numbers and names are that project's own.

package/packs/hook-proof/checks/hook-catch-must-not-allow.json

@@ -0,0 +1,16 @@
+{
+  "id": "hook-catch-must-not-allow",
+  "why": "A catch that returns 0 turns a crashed guard into a passed call. Only an event that cannot be parsed may be let through.",
+  "rule": ".claude/rules/a-refusal-is-exit-2.md",
+  "concepts": [
+    "hook-files"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/*.test.*"
+  ],
+  "pattern": "(?<!JSON\\.parse\\([^\\n]*)\\bcatch\\b\\s*(?:\\([^)]*\\))?\\s*\\{\\s*(?:return 0\\b|process\\.exit\\(0\\))|\\bexcept\\b[^\\n]*:\\s*\\n\\s*(?:return 0\\b|sys\\.exit\\(0\\))",
+  "bad": "try {\n  judge(payload);\n} catch (e) {\n  return 0;\n}\n",
+  "good": "try { payload = JSON.parse(text); } catch { return 0; }\ntry {\n  judge(payload);\n} catch (e) {\n  process.stderr.write(String(e));\n  return 2;\n}\n"
+}

package/packs/hook-proof/checks/hook-command-no-pipe.json

@@ -0,0 +1,16 @@
+{
+  "id": "hook-command-no-pipe",
+  "why": "A piped command exits with the pipe's last command, so a hook's exit 2 is lost.",
+  "rule": ".claude/rules/a-refusal-is-exit-2.md",
+  "concepts": [
+    "hook-config"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/*.test.*"
+  ],
+  "pattern": "\"command\":\\s*\"[^\"\\n]*\\.(?:mjs|py|sh|js)[^\"\\n]*\\s\\|\\s",
+  "bad": "{ \"command\": \"node .claude/hooks/guard.mjs | tee /tmp/log\" }\n",
+  "good": "{ \"command\": \"node .claude/hooks/guard.mjs\" }\n"
+}

package/packs/hook-proof/checks/hook-exit-1-does-not-block.json

@@ -0,0 +1,17 @@
+{
+  "id": "hook-exit-1-does-not-block",
+  "why": "Exit 1 is a non-blocking error: the call goes ahead. A refusal is exit 2. Mark a real non-refusal with a `not a refusal` comment on its line.",
+  "rule": ".claude/rules/a-refusal-is-exit-2.md",
+  "concepts": [
+    "hook-files"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/*.test.*"
+  ],
+  "pattern": "^(?![^\\n]*not a refusal)(?:\\s*exit 1\\b|[^\\n]*\\b(?:process|sys)\\.exit\\(1\\))",
+  "bad": "if grep -q \"rm -rf\" \"$cmd\"; then\n  echo \"BLOCKED\" >&2\n  exit 1\nfi\n",
+  "good": "if grep -q \"rm -rf\" \"$cmd\"; then\n  echo \"BLOCKED\" >&2\n  exit 2\nfi\ntest -f x || exit 1  # not a refusal: a usage error\n",
+  "flags": "m"
+}

package/packs/hook-proof/checks/hook-no-or-true.json

@@ -0,0 +1,18 @@
+{
+  "id": "hook-no-or-true",
+  "why": "`|| true` turns any failure into a pass, a guard's included.",
+  "rule": ".claude/rules/a-refusal-is-exit-2.md",
+  "concepts": [
+    "hook-files",
+    "hook-config"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/*.test.*"
+  ],
+  "pattern": "\\|\\|\\s*(?:true\\b|exit 0\\b|:(?=\\s|\"|$))",
+  "bad": "node guard.mjs || true\n",
+  "good": "node guard.mjs\n",
+  "flags": "m"
+}

package/packs/hook-proof/checks/hook-refusal-on-stderr.json

@@ -0,0 +1,17 @@
+{
+  "id": "hook-refusal-on-stderr",
+  "why": "On exit 2 only stderr reaches Claude: a reason echoed to stdout is lost, and the refusal reads as nothing.",
+  "rule": ".claude/rules/a-refusal-is-exit-2.md",
+  "concepts": [
+    "hook-files"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/*.test.*"
+  ],
+  "pattern": "^\\s*echo\\b(?![^\\n]*>&2)[^\\n]*\\b(?:BLOCKED|REFUSED|refused|denied)\\b",
+  "bad": "echo \"BLOCKED: no force push\"\nexit 2\n",
+  "good": "echo \"BLOCKED: no force push\" >&2\nexit 2\n",
+  "flags": "m"
+}

package/packs/hook-proof/pack.json

@@ -0,0 +1,38 @@
+{
+  "name": "hook-proof",
+  "version": "1.0.0",
+  "description": "A hook that should refuse does refuse: exit 2 is the only block, a crash or a swallowed exit lets the call through, and nothing is proved until it is seen red.",
+  "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/hook-proof"
+  },
+  "keywords": [
+    "hooks",
+    "exit-codes"
+  ],
+  "engines": {
+    "claude-packs": ">=0.19.0"
+  },
+  "folders": {},
+  "concepts": {
+    "hook-files": [
+      "**/.claude/hooks/**",
+      "**/hooks/**/*.sh",
+      "**/hooks/**/*.mjs",
+      "**/hooks/**/*.js",
+      "**/hooks/**/*.cjs",
+      "**/hooks/**/*.py"
+    ],
+    "hook-config": [
+      "**/.claude/settings.json",
+      "**/.claude/settings.local.json"
+    ]
+  },
+  "skillsIn": null,
+  "hooks": {}
+}

package/packs/hook-proof/rules/a-refusal-is-exit-2.md

@@ -0,0 +1,28 @@
+---
+# concepts: hook-files, hook-config
+paths:
+  - "placeholder"
+---
+
+# A refusal is exit 2: everything else lets the call through
+
+A guard that fails fails silently: the call goes ahead, and nothing says the guard did not judge it.
+
+<constraints>
+Always do:
+- Refuse with exit 2, the reason on stderr. Exit 2 is the only code that blocks: exit 1 is a non-blocking error, and a hook killed at its timeout does not block either.
+- Decide what a guard does when it cannot judge: say so, in the code. `doctor` turns a crash into a red check, but the call that crashed already went through.
+- Keep a guard fast and small enough to finish inside its timeout.
+- Prove a new hook with the `prove-a-hook` skill: its bad case seen refused, through the real settings entry.
+
+Never do:
+- `exit 1` to refuse (`hook-exit-1-does-not-block`). Mark a real non-refusal with a `not a refusal` comment on its line.
+- A catch that allows (`hook-catch-must-not-allow`): a crashed guard reads as a passed call. An event that cannot be parsed is the one exception.
+- `|| true`, `|| exit 0` or `|| :` on a guard's work (`hook-no-or-true`).
+- Pipe a guard's command in `settings.json` (`hook-command-no-pipe`): the exit code is the pipe's last command's.
+- `echo` a refusal to stdout (`hook-refusal-on-stderr`): on exit 2 only stderr reaches Claude.
+- Leave a hook file that no settings entry runs: it refuses nothing. `doctor` is red for it.
+</constraints>
+
+## Check
+`doctor` is red for a hook that crashed since it last changed (`.claude/hooks.log`) and for one no settings entry runs. It cannot see a hook killed at its timeout: that leaves no line.

package/packs/hook-proof/skills/prove-a-hook/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: prove-a-hook
+description: Use when a hook is new or changed, when a hook seems not to fire, or when something a hook should refuse got through.
+---
+
+# Prove a hook refuses (one job: its bad case seen at exit 2)
+
+<constraints>
+Always do:
+1. Check it runs: the hook is in `.claude/settings.json`, on the right event and matcher. `doctor` says so.
+2. Write the plant: the smallest payload it must refuse, and the nearest one it must allow, as a `--selftest`, with `lib/selftest.mjs` where the kit's helpers are installed.
+3. Run it as Claude Code runs it: the payload on stdin, `CLAUDE_PROJECT_DIR` set, through the same command as the settings entry.
+4. Read the exit code, not the output: 2 for the plant, 0 for the good case. Exit 1 means it crashed or refused wrongly, and the call went through.
+5. See it red: break the hook on purpose, in a scratch copy, and watch the selftest fail. A gate never seen red proves nothing.
+6. When something got through, look in `.claude/hooks.log` for that call first: no line means the hook never ran or was killed at its timeout; code 1 means it crashed; code 0 means it judged and allowed, so the fault is in its logic.
+7. Turn what got through into a selftest case before fixing it.
+
+Never do:
+- Probe a hook by pasting a payload into a shell command: a guard that reads command text can refuse the probe itself.
+- Fix a hook so its selftest passes while the fault gets through.
+</constraints>

package/packs/host-agent/checks/file-path-from-param.json

@@ -0,0 +1,27 @@
+{
+  "id": "file-path-from-param",
+  "why": "A path built from a parameter can leave the folder it was meant for.",
+  "rule": ".claude/rules/root-on-other-machines.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.cjs",
+    "**/*.go"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "pattern": "(?:writeFile|readFile|unlink|rm)\\(\\s*`/[^`\\n]*\\$\\{(?!safe|basename)[^}]+\\}",
+  "bad": "await writeFile(`/etc/bind/zones/${zf.name}`, zf.content);",
+  "good": "await writeFile(join(ZONES, safeName(zf.name)), zf.content);",
+  "kind": "security"
+}

package/packs/host-agent/checks/integrity-check-optional.json

@@ -0,0 +1,27 @@
+{
+  "id": "integrity-check-optional",
+  "why": "An optional check is no check, and this one guards root on customers' hosts.",
+  "rule": ".claude/rules/root-on-other-machines.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.cjs",
+    "**/*.go"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "pattern": "\\bif\\s*\\(\\s*expected\\w*\\s*&&\\s*\\w+\\s*!==\\s*expected",
+  "bad": "if (expectedSha256 && actual !== expectedSha256) return fail();",
+  "good": "if (!expectedSha256 || actual !== expectedSha256) return fail();",
+  "kind": "security"
+}

package/packs/host-agent/checks/quoted-value-into-config.json

@@ -0,0 +1,24 @@
+{
+  "id": "quoted-value-into-config",
+  "why": "Every output format needs its own escaper, as HTML does: a value with a quote in it rewrites the config around it.",
+  "rule": ".claude/rules/root-on-other-machines.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.mjs"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "pattern": "`[^`\\n]*\"\\$\\{(?!esc|quote|validate|sanitize|JSON)[\\w.!\\[\\]]+\\}\"[^`\\n]*;?`",
+  "bad": "lines.push(`add_header ${h.name} \"${h.value}\" always;`);",
+  "good": "lines.push(`add_header ${token(h.name)} ${quoted(h.value)} always;`);",
+  "kind": "security"
+}

package/packs/host-agent/checks/secret-on-argv.json

@@ -0,0 +1,28 @@
+{
+  "id": "secret-on-argv",
+  "why": "A command line is visible to everyone on the box.",
+  "rule": ".claude/rules/root-on-other-machines.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.cjs",
+    "**/*.go"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "pattern": "['\"]-p['\"]\\s*,\\s*\\w*(?:pass|pwd)\\w*|--password[= ]\\$|\\bpwd:\\s*\\\\?\"\\$\\{|PASSWORD '\\$\\{|--api-key\\s+'?\\$\\{",
+  "bad": "await exec(id, ['mongosh', '-u', 'admin', '-p', adminPass]);",
+  "good": "await exec(id, ['mongosh', '--file', '/run/secrets/init.js']);",
+  "flags": "i",
+  "kind": "security"
+}

package/packs/host-agent/checks/ssh-verifies-host-key.json

@@ -0,0 +1,27 @@
+{
+  "id": "ssh-verifies-host-key",
+  "why": "An SSH connection with no host key check trusts whoever answers.",
+  "rule": ".claude/rules/root-on-other-machines.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.cjs",
+    "**/*.go"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "pattern": "\\.connect\\(\\{\\s*host\\b(?:(?!hostVerifier)[\\s\\S]){0,400}?\\}\\)",
+  "bad": "conn.connect({ host, port, username, password });",
+  "good": "conn.connect({ host, port, username, password, hostVerifier: pinned(host) });",
+  "kind": "security"
+}

package/packs/host-agent/checks/system-file-written-in-place.json

@@ -0,0 +1,26 @@
+{
+  "id": "system-file-written-in-place",
+  "why": "A crash between two steps must not leave things worse than before: write a temp file, validate, rename.",
+  "rule": ".claude/rules/root-on-other-machines.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.cjs",
+    "**/*.go"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "pattern": "(?:writeFile|writeFileSync)\\(\\s*[`'\"]/etc/|os\\.WriteFile\\(\\s*(?:\"/etc/|filepath\\.Join\\(\"/etc/)",
+  "bad": "await writeFile('/etc/bind/named.conf', conf, 'utf-8');",
+  "good": "await writeFile(tmp, conf);\nawait rename(tmp, '/etc/bind/named.conf');"
+}