@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/packs/sound-design/skills/choose-observable/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: choose-observable
+description: Use when writing a probe, when a measurement is noisy, or when deciding what audio can prove a behaviour.
+---
+
+# Choose the observable (one job: measure the signal that can prove it)
+
+<constraints>
+Always do:
+1. Check preconditions: renders bit-identical, start state checked, stale frames drained, the program found by name.
+2. Take the best rung: a pure gain (exact), pulse width, a stereo difference with a hard zero, pitch through the phase null, a filter, a comb's energy.
+3. On pitch, keep the depth tiny: the law is exponential, and the error accumulates.
+4. On a sampler, take the median of consecutive gaps.
+5. If it cannot see phase, say so. Assert the offset does not move, and log the open item.
+
+Never do:
+- Measure phase through a comb, or trust a filter's lowest point as its vertex.
+</constraints>

package/packs/sound-design/skills/measure-a-law/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: measure-a-law
+description: Use when fitting or checking a law against a machine or a reference recording.
+---
+
+# Measure a law (one job: a fit you can defend)
+
+<constraints>
+Always do:
+1. Use a sine at the frequency you read. A filter slope read on a saw was off by 2.3 dB per octave.
+2. Write a filter's law in the units its procedure uses.
+3. Fix it with two anchors.
+4. Keep fitted constants scripted, tagged, and rerunnable.
+5. Write disproofs down.
+
+Never do:
+- Fit a single point.
+</constraints>

package/packs/sound-design/skills/measure-reverb/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: measure-reverb
+description: Use when measuring or calibrating a reverb or a decay time.
+---
+
+# Measure a reverb (one job: a decay time you can trust)
+
+<constraints>
+Always do:
+1. Mute dry and early reflections, and zero the pre-delay.
+2. Use Schroeder T30, or a least-squares fit of the tail.
+3. Measure over a long enough render for the longest setting.
+4. Read the law in the units its procedure uses.
+5. Compare with the printed figure.
+
+Never do:
+- Read a time off the peak level.
+- Inherit a sibling machine's law: reverb times were once 20 to 45% short that way.
+</constraints>

package/packs/sound-design/skills/spread-probe/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: spread-probe
+description: Use when presets sound alike, when a bank is finished, or when an algorithm list is built.
+---
+
+# Measure the spread (one job: the programs really differ)
+
+<constraints>
+Always do:
+1. Render every program with the same excitations, chosen to excite what differs.
+2. Measure the difference between programs, per algorithm and across the bank, as medians.
+3. Count the effectively distinct sounds, and report it next to the total.
+4. Check the upstream causes first: an invented global, programs loading defaults, an algorithm with min equal to max.
+5. Share one probe across units, so a number means the same on every machine.
+
+Never do:
+- Accept "they all sound the same" as an opinion. It is a testable report: 625 presets once measured as 146.
+</constraints>

package/packs/stellix/checks/no-keyboard-focus.json

@@ -0,0 +1,12 @@
+{
+  "id": "no-keyboard-focus",
+  "why": "Stellix 3a: no dropdown, button or readout ever takes keyboard focus; QWERTY always plays.",
+  "rule": ".claude/rules/stellix-deterministic-world.md",
+  "concepts": [
+    "ui"
+  ],
+  "pattern": "setWantsKeyboardFocus\\s*\\(\\s*true|grabKeyboardFocus\\s*\\(|setMouseClickGrabsKeyboardFocus\\s*\\(\\s*true",
+  "code": true,
+  "bad": "presetBox.setWantsKeyboardFocus (true);",
+  "good": "presetBox.setWantsKeyboardFocus (false);"
+}

package/packs/stellix/checks/one-seeded-random.json

@@ -0,0 +1,16 @@
+{
+  "id": "one-seeded-random",
+  "why": "Stellix rule 4: formulas by default; the only randomness is the world's one seeded generator (RANDOM, 6.6). No other random call may exist in the engine, the world or the drawing.",
+  "rule": ".claude/rules/stellix-deterministic-world.md",
+  "concepts": [
+    "cpp"
+  ],
+  "exclude": [
+    "@seeded_random",
+    "**/tests/**"
+  ],
+  "pattern": "(?<![\\w.])(?:std::)?(?:s?rand|random|drand48|lrand48|arc4random(?:_uniform)?)\\s*\\(|\\b(?:random_device|mt19937(?:_64)?|minstd_rand0?|default_random_engine|ranlux\\w+|knuth_b)\\b|\\b\\w+_distribution\\b|\\bjuce::Random\\b|(?<![\\w:])Random\\s*(?:::|\\w+\\s*[;({=])|\\bgetSystemRandom\\b|\\bSecRandomCopyBytes\\b|\\bRAND_bytes\\b",
+  "code": true,
+  "bad": "float jitter = juce::Random::getSystemRandom().nextFloat();\nstd::mt19937 g (42);\nstd::uniform_real_distribution<float> d (0, 1);\nuint32_t v = arc4random_uniform (8);",
+  "good": "float jitter = world.seeded().next01();\nauto n = randomSource.next(); int operand (int); bool israndom;\ninline float hash (int i) { return std::sin (float (i) * 12.98f) * 43758.5f; }"
+}

package/packs/stellix/checks/world-never-includes-painter.json

@@ -0,0 +1,12 @@
+{
+  "id": "world-never-includes-painter",
+  "why": "Stellix 8: the world is coordinates, not graphics. The audio side includes nothing from the painter or any GPU API; it publishes a plain-data snapshot and nothing else.",
+  "rule": ".claude/rules/stellix-world-snapshot.md",
+  "concepts": [
+    "world",
+    "audio"
+  ],
+  "pattern": "#\\s*(include|import)\\s*[<\"][^>\"]*(painter|Painter|gpu/|render/|Renderer|juce_opengl|OpenGL|Metal/|MetalKit|QuartzCore|bgfx|webgpu)[^>\"]*[>\"]",
+  "bad": "#include \"../painter/PlanetMesh.h\"",
+  "good": "#include \"WorldSnapshot.h\""
+}

package/packs/stellix/checks/world-no-libm.json

@@ -0,0 +1,15 @@
+{
+  "id": "world-no-libm",
+  "why": "libm sin/cos/exp/pow differ in the last bits between Apple, MSVC and glibc; the world must replay bit-identically on Mac and Windows. Use the house world-math functions.",
+  "rule": ".claude/rules/world-fp-determinism.md",
+  "concepts": [
+    "world"
+  ],
+  "exclude": [
+    "@world_math"
+  ],
+  "pattern": "\\bstd::(sin|cos|tan|asin|acos|atan2?|exp2?|expm1|log(2|10|1p)?|pow|sinh|cosh|tanh|hypot|cbrt)\\s*\\(|(?<![\\w:.>])(sinf?|cosf?|tanf?|atan2f?|expf?|logf?|powf?)\\s*\\(",
+  "code": true,
+  "bad": "const double a = std::sin (phase) * radius;",
+  "good": "const double a = wm::sin (phase) * radius;"
+}

package/packs/stellix/checks/world-no-unordered.json

@@ -0,0 +1,10 @@
+{
+  "id": "world-no-unordered",
+  "why": "Hash-container iteration order differs between libc++ and the MSVC STL; the world must be ordered by stable ID to replay identically on every platform.",
+  "rule": ".claude/rules/world-fp-determinism.md",
+  "concepts": ["world"],
+  "pattern": "\\bstd::unordered_(map|set|multimap|multiset)\\b",
+  "code": true,
+  "bad": "std::unordered_map<int, Moon> moonsById;",
+  "good": "std::array<Moon, kMaxMoons> moons; // ordered by stable id"
+}

package/packs/stellix/hooks/no-shipped-images.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// Nothing is ever pre-rendered (Stellix spec 0.2). No image file may be added to the source or
+// resources (fonts are allowed: data, not pictures). Test output and goldens live outside them.
+// A project sets its own scope in .claude/layout.json "guards": { "images": { "guarded": [globs],
+// "allowed": [globs] } }: "guarded" replaces the code folders (["**"]: anywhere in the repo), "allowed"
+// replaces the default allowed folders (Stellix: design/reference/** and build/pictures/** only).
+//   PreToolUse (Write|Edit|MultiEdit|NotebookEdit|Bash): blocks writing, copying or moving an image into a guarded
+//   folder by any route (lib/writes.mjs), and a download or conversion that names one (curl, convert, sips ...).
+//   --git-staged: run from a git pre-commit hook; fails if a staged added file is an image.
+//   --selftest: proves it.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { matchesAny } from './lib/glob.mjs';
+import { codeFolders, readLayout } from './lib/layout.mjs';
+import { claudeRoot, commandLeavesProject, insideProject, relInCheckout } from './lib/project.mjs';
+import { writesOf } from './lib/writes.mjs';
+import { bashOf, runHook, scratchProject, verdicts, writeOf } from './lib/selftest.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+const IMAGE = /\.(png|jpe?g|gif|bmp|tiff?|webp|heic|ico|icns|svg|psd|tga|exr|hdr|ktx2?|dds|astc)$/i;
+// Guarded: every code folder in the layout, plus anything that would be bundled as a resource.
+const guarded = (root) => readLayout(root).guards?.images?.guarded ?? [...new Set(['src/**', 'Resources/**', 'resources/**', 'assets/**', ...codeFolders(readLayout(root)).map((f) => `${f}/**`)])];
+const ALLOWED = ['tests/**', '**/tests/**', 'goldens/**', '**/goldens/**', 'docs/**', 'captures/**', 'build/**'];
+const allowed = (root) => readLayout(root).guards?.images?.allowed ?? ALLOWED;
+
+// A path is judged in its own checkout, so an image written into an agent worktree is caught too.
+const isBlocked = (p, base = ROOT) => {
+  const abs = resolve(base, p);
+  if (!IMAGE.test(abs) || !insideProject(abs)) return false;
+  const rel = relInCheckout(abs).replace(/^\.claude\/worktrees\/[^/]+\//, '');
+  const root = claudeRoot(abs);
+  return !rel.startsWith('.claude/') && matchesAny(rel, guarded(root)) && !matchesAny(rel, allowed(root));
+};
+
+function fail(files) {
+  process.stderr.write(
+    `BLOCKED by no-shipped-images: ${files.join(', ')}\n` +
+      'Nothing is pre-rendered: draw it in code; a picture check renders off-screen, from the app itself, into an allowed folder (guards.images.allowed in .claude/layout.json).\n',
+  );
+  return 2;
+}
+
+function gitStaged() {
+  const out = execFileSync('git', ['diff', '--cached', '--name-only', '--diff-filter=AR'], { cwd: ROOT, encoding: 'utf8' });
+  const bad = out.split('\n').filter((f) => f && isBlocked(f));
+  return bad.length ? (fail(bad), 1) : 0;
+}
+
+function main(text) {
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    return 0;
+  }
+  const input = payload.tool_input ?? {};
+  const bad = writesOf(payload, payload.cwd ?? ROOT).filter((w) => w.op !== 'delete' && isBlocked(w.path)).map((w) => w.path);
+  if (payload.tool_name === 'Bash' && !commandLeavesProject(input.command)) {
+    const tokens = (input.command ?? '').split(/\s+/).map((t) => t.replace(/^['"]|['"]$/g, ''));
+    if (/\b(curl|wget|convert|magick|sips|rsvg-convert|ffmpeg)\b/.test(input.command ?? '')) bad.push(...tokens.filter((t) => t && isBlocked(t, payload.cwd ?? ROOT)));
+  }
+  return bad.length ? fail([...new Set(bad)]) : 0;
+}
+
+function selftest() {
+  const me = fileURLToPath(import.meta.url);
+  const dir = scratchProject({}, { folders: { app: { path: 'lib/app/src', purpose: 'app' }, docs: { path: 'docs', purpose: 'docs' } }, concepts: {} });
+  const w = (file) => runHook(me, dir, writeOf(join(dir, file), 'x'));
+  return verdicts('no-shipped-images', [
+    ['an image in a code folder', w('lib/app/src/logo.png'), 2],
+    ['an image in src/', w('src/icon.svg'), 2],
+    ['an image in resources/', w('resources/knob.webp'), 2],
+    ['a font is data, not a picture', w('resources/Inter.ttf'), 0],
+    ['a golden render under tests/', w('tests/goldens/panel.png'), 0],
+    ['a picture in docs/', w('docs/shot.png'), 0],
+    ['cp of an image into a code folder', runHook(me, dir, bashOf('cp /tmp/a.png lib/app/src/a.png', dir)), 2],
+    ['cp into tests/', runHook(me, dir, bashOf('cp /tmp/a.png tests/goldens/a.png', dir)), 0],
+  ]);
+}
+
+export const hook = main; // run-hooks.mjs calls it with the event's text (KWB-24)
+if (isMain(import.meta.url)) {
+  const arg = process.argv.slice(2);
+  process.exit(arg.includes('--selftest') ? selftest() : arg.includes('--git-staged') ? gitStaged() : await asHook('no-shipped-images', main));
+}

package/packs/stellix/pack.json

@@ -0,0 +1,61 @@
+{
+  "name": "stellix",
+  "version": "1.0.0",
+  "description": "Stellix spec laws: the world, determinism, generated reset, no shipped images.",
+  "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/stellix"
+  },
+  "keywords": [
+    "synth"
+  ],
+  "engines": {
+    "claude-packs": ">=0.19.0"
+  },
+  "folders": {
+    "world": {
+      "path": "src/world",
+      "purpose": "the world: coordinates, travellers, hits, pushes, the snapshot writer, the seeded generator, world maths"
+    },
+    "records": {
+      "path": "records",
+      "purpose": "layout and state records: every piece of state declared once with its starting value"
+    }
+  },
+  "concepts": {
+    "world": [
+      "world"
+    ],
+    "records": [
+      "records"
+    ],
+    "params": [
+      "records"
+    ]
+  },
+  "skillsIn": null,
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/no-shipped-images.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  },
+  "files": {
+    "seeded_random": "src/world/seeded_random.h",
+    "world_math": "src/world/world_math.h",
+    "snapshot": "src/world/snapshot.h"
+  }
+}

package/packs/stellix/rules/stellix-deterministic-world.md

@@ -0,0 +1,29 @@
+---
+# concepts: world, audio, painter, ui, tests
+paths:
+  - "placeholder"
+---
+
+# Same playing from the same state gives the same sound and the same picture
+
+From spec §0 rule 4, §6.1, §6.3, §7.3.
+
+<constraints>
+Always do:
+- Work out every path, bounce, impact and shatter by formula from what was played, where it hits, and the world's settings.
+- Use the world's one seeded generator as the only randomness (RANDOM, opt-in, off in INIT and every factory patch). It may reach modulation and effects only, never pitch, wave, tone, level, filter type or a SOUND choice. Under FOLLOW THE SONG its seed restarts with the song position.
+- Run the world at a fixed 240 Hz tick, independent of buffer size and sample rate. Solve crossings and touches inside the tick and place each event at its exact sample.
+- Keep looking separate from sound: hovering, zooming and moving the camera never change the sound (unless FROM VIEW is on, where the camera becomes patch data).
+
+Never do:
+- Call any random source other than the seeded generator. `.claude/checks/one-seeded-random.json` blocks it.
+- Let the frame rate, the window being open, or the host buffer size change what is heard.
+- Let a control take keyboard focus. QWERTY always plays (`no-keyboard-focus.json`).
+</constraints>
+
+## Check
+Gates, each proven red by a planted fault:
+- **Bounce repeat:** the same MIDI from INIT renders bit-identical twice, at buffer sizes 64, 512 and 2048 and at 44.1, 48 and 96 kHz.
+- **View:** with FROM VIEW off, a camera move or a hover leaves the render bit-identical.
+- **Four tempos:** HITS and BEATS notes land on their exact samples.
+- **Settle:** after a hard passage the world comes to rest once playing stops.

package/packs/stellix/rules/stellix-reset-generated.md

@@ -0,0 +1,24 @@
+---
+# concepts: records, params, world
+paths:
+  - "placeholder"
+---
+
+# Reset is generated from the records, never written by hand
+
+From spec §0 rule 5.
+
+<constraints>
+Always do:
+- Declare every piece of patch state once in the records, with its starting value. The reset is generated from that list, and state without a starting value must not compile.
+- Treat a patch load as a reset followed by an apply, so nothing survives from the previous patch.
+- Make reset clear motion too: every mover, note in flight and shatter piece. Every held note gets its note-off.
+- Keep MAIN volume, octave, the wheel positions, LIMIT and SETTINGS outside the patch, as the patch law says.
+
+Never do:
+- Write a reset by hand, or add a field to a hand-made list.
+- Plant state in a member variable that isn't declared in the records.
+</constraints>
+
+## Check
+Reset gate: move every control and every piece of patch state away from its start, set the world moving with notes in flight, then reset. The render must be bit-identical to a fresh INIT. Plant the fault (one field outside the list) and the gate must show red.

package/packs/stellix/rules/stellix-world-snapshot.md

@@ -0,0 +1,27 @@
+---
+# concepts: world, painter, audio
+paths:
+  - "placeholder"
+---
+
+# The painter sees the world only through one plain-data snapshot
+
+From spec §8 and §7.3.
+
+<constraints>
+Always do:
+- Keep the world as coordinates on the audio side: a traveller is a position and a velocity; a moon is a position, a radius and a border; a planet is a position and a radius. Each 240 Hz tick moves travellers, checks distances and turns hits into pushes, as arithmetic only.
+- Publish one plain-data snapshot per tick (positions, pushes, hits) behind a single atomic index. Use double or triple buffering, whichever keeps the reader from ever seeing a half-written one.
+- Let the painter read only the snapshot, at its own frame rate. It may extrapolate between ticks with the same formulas, but when they differ the snapshot wins.
+- Compute predictions (ghost paths, "cutoff +12%") with the engine's own formula code on a copy of the world's state, never with a second version of the formulas.
+
+Never do:
+- Include anything from the painter, a GPU API or JUCE OpenGL in world, engine or voice code. `.claude/checks/world-never-includes-painter.json` blocks it.
+- Do camera, perspective, lighting, mesh, bloom or path drawing work inside the world tick. The look-only test's 17 ms demo step is the example of what this forbids.
+- Let the audio thread wait for, lock against or allocate for the painter.
+</constraints>
+
+## Check
+- Torn-snapshot gate: a reader hammering the snapshot while the world writes at full rate must never see a mixed one. Plant the fault by writing in place, and the gate goes red.
+- Prediction gate: play a passage; every predicted hit happens, and no unpredicted hit occurs.
+- The realtime-guard hook blocks GPU calls in audio-thread code.

package/packs/stellix/rules/world-continuous-collision.md

@@ -0,0 +1,26 @@
+---
+# concepts: world, tests
+paths:
+  - "placeholder"
+---
+
+# Every hit inside a tick is found exactly once and placed at its sample
+
+From spec 6.0 and 7.3: the tick never quantises time.
+
+<constraints>
+Always do:
+- Sweep each traveller across the tick. A formula curve is split into a fixed number K of substeps (fixed K keeps it deterministic), and each chord is swept against every sphere in reach.
+- Solve segment against sphere with the numerically stable quadratic: `q = −½(b + sign(b)·√disc)`, roots `c'/q` and `q/a` (Ericson, *Real-Time Collision Detection* §5.3). Take the smallest `t` in [0, 1).
+- Keep a contact state per traveller/planet pair. A hit fires on the *entering* transition only; a traveller starting inside counts once, at t = 0.
+- Use a skin tolerance relative to the radius, and settle simultaneous hits by pair ID.
+- Convert `t` to a sample with integer or fixed-point arithmetic: `tickStartSample + floor(t · samplesPerTick)`.
+
+Never do:
+- Test only the end position of a tick (fast travellers tunnel through small moons).
+- Let a resting contact fire again every tick.
+</constraints>
+
+## Check
+- Test: a traveller at 10x the fastest launch speed crosses a sphere of the smallest radius. Exactly one event, at the analytically expected sample, ±0.
+- Test: grazing paths (tangent, ±1 skin) give the same verdict on both platforms (part of the cross-platform event-log gate).

package/packs/stellix/rules/world-fp-determinism.md

@@ -0,0 +1,28 @@
+---
+# concepts: world, build
+paths:
+  - "placeholder"
+---
+
+# The world gives bit-identical results on Mac and Windows
+
+The world (travellers, hits, pushes, event samples) must replay identically on ARM64 and x86-64. Audio DSP only needs to be identical per platform.
+
+<constraints>
+Always do:
+- Build world sources with `-ffp-contract=off` (clang and clang-cl) and `/fp:precise` without `/fp:contract` (MSVC). Clang fuses multiply-adds by default (`-ffp-contract=on`), and Apple clang on ARM64 emits `fmadd`.
+- Use only `+ − × ÷ sqrt` in the world. IEEE-754 rounds those five exactly, so they match everywhere. Build `sin`, `cos`, `exp` and `pow` from the house polynomial versions (range reduction plus Horner) in one world-math file.
+- Keep world state in fixed arrays ordered by stable ID, and break sort ties by ID.
+- Keep time as integers: sample timestamps as `int64`, and the tick phase as an integer ratio (48 kHz/240 Hz is exactly 200 samples, but 44.1 kHz/240 Hz is 183.75, so accumulate the remainder exactly).
+- Design out denormals in the world: snap magnitudes below 1e-30 to zero explicitly rather than relying on CPU flush modes, which differ between ARM and x86.
+- Consider 64-bit fixed point (e.g. Q32.32) for positions. It removes compiler and flag risk entirely (house option, decided in the world plan).
+
+Never do:
+- Call libm (`std::sin`, `std::exp`, `std::pow`…) in world code. Apple libm, the MSVC UCRT and glibc differ in the last bits.
+- Use `std::unordered_*` or iterate anything in hash order in the world.
+- Use fast-math or FMA-contraction flags anywhere (`no-fast-math` check).
+</constraints>
+
+## Check
+- `.claude/checks/world-no-libm.json` and `world-no-unordered.json` block libm calls and unordered containers in world code.
+- Cross-platform gate: render N seconds from a saved state on both CI platforms. The world event log (event, sample index, payload hash) must be byte-identical between Mac and Windows; the audio hash must be identical between runs on each platform.

package/packs/stored-text/checks/no-raw-html-from-data.json

@@ -0,0 +1,31 @@
+{
+  "id": "no-raw-html-from-data",
+  "why": "HTML put on a page by hand skips the sanitize step: stored markdown can carry a script. The only HTML inserted raw is the renderer's output.",
+  "rule": ".claude/rules/stored-text-renders-once.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.tsx",
+    "**/*.js",
+    "**/*.jsx",
+    "**/*.mjs",
+    "**/*.vue",
+    "**/*.svelte",
+    "**/*.html"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**",
+    "**/stored-text.*"
+  ],
+  "strings": true,
+  "pattern": "dangerouslySetInnerHTML=\\{\\{\\s*__html:(?!\\s*renderStored\\()|\\.(?:innerHTML|outerHTML)\\s*\\+?=(?!\\s*(?:renderStored\\(|['\"`]{2}))|\\bv-html=\"(?!renderStored\\()",
+  "bad": "<div dangerouslySetInnerHTML={{ __html: row.body }} />\n",
+  "good": "<StoredText source={row.body} />\n<div dangerouslySetInnerHTML={{ __html: renderStored(row.body) }} />\nel.innerHTML = '';\n"
+}

package/packs/stored-text/checks/stored-text-libs-only-in-renderer.json

@@ -0,0 +1,31 @@
+{
+  "id": "stored-text-libs-only-in-renderer",
+  "why": "A second place that parses markdown or highlights code is a second place that forgets to sanitize, and pages start to differ. These libraries are imported only in stored-text.*.",
+  "rule": ".claude/rules/stored-text-renders-once.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.tsx",
+    "**/*.js",
+    "**/*.jsx",
+    "**/*.mjs",
+    "**/*.vue",
+    "**/*.svelte"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**",
+    "**/stored-text.*",
+    "**/scripts/**"
+  ],
+  "strings": true,
+  "pattern": "(?:\\bfrom\\s+|\\bimport\\s+|\\brequire\\(\\s*|\\bimport\\(\\s*)['\"](?:marked|markdown-it|micromark|react-markdown|remark[\\w-]*|rehype[\\w-]*|shiki|highlight\\.js|prismjs|dompurify|isomorphic-dompurify|sanitize-html)(?:/[^'\"]*)?['\"]",
+  "bad": "import { marked } from 'marked';\nconst html = marked.parse(row.body);\n",
+  "good": "import { renderStored } from '../lib/stored-text.js';\nconst html = renderStored(row.body);\n"
+}

package/packs/stored-text/checks/stored-text-renderer-complete.json

@@ -0,0 +1,24 @@
+{
+  "id": "stored-text-renderer-complete",
+  "why": "The renderer is the one place stored text is made safe and readable, so it does all four jobs: line endings, markdown, highlighted code, sanitizing. One missing means every page shows raw symbols, a grey code block, stray characters or a script.",
+  "rule": ".claude/rules/stored-text-renders-once.md",
+  "concepts": [
+    "stored-text-renderer"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/*.test.*",
+    "**/*.spec.*"
+  ],
+  "strings": true,
+  "mode": "needs",
+  "pattern": "\\bexport\\b",
+  "needs": [
+    "\\\\r",
+    "marked|markdown-it|micromark|remark|react-markdown|unified",
+    "shiki|highlight\\.js|hljs|prism|rehype-highlight|rehype-pretty-code",
+    "sanitize|DOMPurify|dompurify"
+  ],
+  "bad": "import { marked } from 'marked';\nexport const renderStored = (text: string) => marked.parse(text);\n",
+  "good": "import { marked } from 'marked';\nimport { codeToHtml } from 'shiki';\nimport sanitizeHtml from 'sanitize-html';\nexport const renderStored = (text: string) => sanitizeHtml(marked.parse(text.replace(/\\r\\n?/g, '\\n')));\n"
+}

package/packs/stored-text/checks/stored-text-through-renderer.json

@@ -0,0 +1,25 @@
+{
+  "id": "stored-text-through-renderer",
+  "why": "A stored document put straight into markup shows its markdown as symbols, its code as one grey block and its \\r as stray characters. It goes through the renderer. A field that truly is plain gets a `plain text:` comment on its line.",
+  "rule": ".claude/rules/stored-text-renders-once.md",
+  "concepts": [
+    "stored-text-ui"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**",
+    "**/stored-text.*"
+  ],
+  "pattern": "^(?![^\\n]*plain text:)[^\\n]*(?:>\\s*\\{\\s*[\\w$.?]*(?:\\?\\.|\\.)(?:content|body|markdown|transcript|prompt|reply|output|summary)\\s*\\}|\\$\\{\\s*(?:(?:esc\\w*|escapeHtml)\\(\\s*)?[\\w$.?]*(?<!\\breq)(?<!\\brequest)(?:\\?\\.|\\.)(?:content|body|markdown|transcript|prompt|reply|output|summary)\\b[^}\\n]*\\})",
+  "flags": "m",
+  "bad": "<p>{row.body}</p>\nconst h = `<li>${esc(row.note ?? row.tool)}</li>`;\n",
+  "good": "<StoredText source={row.body} />\nconst page = html`<div>${raw(renderStored(row.body))}</div>`;\n<td>{row.title}</td>\n<td>{row.content}</td> {/* plain text: a short label from an enum */}\nconst u = `${req.body}`;\n"
+}

package/packs/stored-text/pack.json

@@ -0,0 +1,41 @@
+{
+  "name": "stored-text",
+  "version": "1.0.0",
+  "description": "Text from a database reaches the page through one renderer: line endings normalised, markdown parsed, code highlighted, HTML sanitized.",
+  "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/stored-text"
+  },
+  "keywords": [
+    "markdown",
+    "sanitize",
+    "ui"
+  ],
+  "engines": {
+    "claude-packs": ">=0.19.0"
+  },
+  "folders": {},
+  "concepts": {
+    "stored-text-ui": [
+      "**/*.tsx",
+      "**/*.jsx",
+      "**/*.vue",
+      "**/*.svelte",
+      "**/ui/**/*.ts",
+      "**/views/**/*.ts",
+      "**/templates/**/*.ts",
+      "**/render*.ts",
+      "**/*.view.ts"
+    ],
+    "stored-text-renderer": [
+      "**/stored-text.*"
+    ]
+  },
+  "skillsIn": null,
+  "hooks": {}
+}

package/packs/stored-text/rules/stored-text-renders-once.md

@@ -0,0 +1,26 @@
+---
+# concepts: stored-text-ui, stored-text-renderer
+paths:
+  - "placeholder"
+---
+
+# Text from a database reaches the page through one renderer
+
+<constraints>
+Always do:
+- Render every field a person or a tool wrote (a message, a note, a description, a transcript, a tool's output) through the project's one renderer, in a file named `stored-text.*` (the `render-stored-text` skill builds it).
+- Keep its order: normalise line endings; parse markdown with raw HTML off; highlight fenced code by its language; sanitize last, with an allowlist.
+- Normalise `\r\n` and a lone `\r` to `\n`. A terminal's output is the exception: there a lone `\r` overwrites the line, so keep what follows the last one.
+- Treat a backslash and an `r` showing as text as a write bug: the value was encoded twice. Fix it where it is written, and repair the stored rows.
+- Highlight on the server, so no highlighter ships to the browser. An unknown language renders as plain, escaped code; never guess one.
+- Keep labels, ids and enum values plain and escaped: they are not documents. Mark such a field with a `plain text:` comment on its line when its name reads like a document.
+
+Never do:
+- Show stored text with `{row.body}` or `${esc(row.body)}`: the markdown shows as symbols and the code as one grey block.
+- Put HTML on a page by `dangerouslySetInnerHTML`, `innerHTML` or `v-html` unless it is the renderer's output. Markdown can carry a script; only the sanitize step stops it.
+- Import a markdown, highlight or sanitize library anywhere but the renderer.
+- Normalise or strip `\r` when saving: the stored text stays as it came.
+</constraints>
+
+## Check
+`stored-text-renderer-complete`, `stored-text-libs-only-in-renderer`, `no-raw-html-from-data` and `stored-text-through-renderer` (lesson checks). The last reads field names, not data flow: a field with another name gets past it, so review what a new page shows.