@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/packs/base/hooks/template-law.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+// PreToolUse (Write|Edit|MultiEdit|NotebookEdit|Bash): anything "component" used more than once is a template (0.23.0: html, c++ and apps;
+// a change, an update or a test is then made once, never per copy). A write that adds an element built by hand, in the shape of one that already
+// exists in this file or another of this checkout, is refused (lib/elements.mjs: names and text stripped). A line marked `one-off:` with its
+// reason is left alone, and so are tests, `protected` globs, generated and built code. The other files' shapes are kept between calls, keyed by
+// time and size, so a write reads only what changed. `--selftest` proves it.
+import { readFileSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { parametersOf } from './lib/code-shapes.mjs';
+import { isContent } from './lib/content.mjs';
+import { languageOf } from './lib/languages.mjs';
+import { nearCopy } from './lib/near-copies.mjs';
+import { EXTS, readText, repoIndex } from './lib/repo-index.mjs';
+import { TEMPLATE, TESTS, copiesNeeded, skippedBy } from './lib/elements.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+import { judgeEvent } from './lib/writes.mjs';
+import { checkoutRoot, claudeRoot } from './lib/project.mjs';
+import { readLayout } from './lib/layout.mjs';
+import { matchesAny } from './lib/glob.mjs';
+import { bashOf, editOf, runHook, scratchProject, verdicts, writeOf } from './lib/selftest.mjs';
+
+
+// { id: [{ file, line, what }] } over every other file.
+function copiesElsewhere(entries, rel) {
+  const by = new Map();
+  for (const [file, e] of Object.entries(entries)) {
+    if (file === rel) continue;
+    for (const [id, line, what] of e.shapes) { if (!by.has(id)) by.set(id, []); by.get(id).push({ file, line, what }); }
+  }
+  return by;
+}
+
+const AGAIN = { markup: (s) => `${s.what} built by hand again, the same element with other names and text`, setup: (s) => `${s.what} set up by hand again, the same set-up with other names`,
+  run: () => 'code the repo already has, the same statements with other names', rows: (s) => `${s.nodes} calls of ${s.what} in a row, a table written as code` };
+
+function refusal(s, w, rel, root, elsewhere, after) {
+  const where = [...after.filter((x) => x.id === s.id).map((x) => `${rel}:${x.line}`), ...elsewhere.map((x) => `${x.file}:${x.line}`)];
+  const differs = s.kind === 'run' && elsewhere.length ? parametersOf(s.id, w.after, readFileSync(join(root, elsewhere[0].file), 'utf8'), extname(rel)) : [];
+  const params = s.kind !== 'run' || !elsewhere.length ? '' : differs.length ? `It differs only in: ${differs.slice(0, 6).join(', ')}. Those are the parameters.\n` : 'It is the same, every name: move it to one place and call it.\n';
+  return `this is ${AGAIN[s.kind](s)}:\n  ${where.slice(0, 6).join('\n  ')}\n${params}` +
+    `Anything used more than once is one template: make it ${TEMPLATE[s.kind]}, so a change or a test is made once (skill: make-it-a-template).\n` +
+    'Take the copies out first, then write the template: it is refused while they stand. If this one truly differs, say so above it: `one-off: <reason>`.\n';
+}
+
+const sameLanguage = (rel, file) => languageOf(extname(rel)) === languageOf(extname(file));
+const COMPOUND = /[a-z0-9][A-Z]|[a-z0-9]_[a-z0-9]/;   // a plain word (`count`, `read`) is in many files by chance
+const CONVENTION = 3;                                  // a name in this many other files is a convention: `selftest`, `handler`
+
+// What the write adds that was not there: the statements, in order, and the new definitions.
+function addedTo(before, after) {
+  const left = before.st.reduce((m, [h]) => m.set(h, (m.get(h) ?? 0) + 1), new Map());
+  const statements = after.st.filter(([h]) => { const n = left.get(h) ?? 0; left.set(h, n - 1); return n <= 0; });
+  const had = new Set(before.defs.map(([name]) => name));
+  return { statements, defs: after.defs.filter(([name]) => !had.has(name) && COMPOUND.test(name)) };
+}
+
+function nearRefusal(hit) {
+  return `this is close to code the repo already has: ${hit.matched} of ${hit.of} statements from line ${hit.line} match ${hit.file}:${hit.from}-${hit.to}, in order, with other names.\n` +
+    `Anything used more than once is one template: make it ${TEMPLATE.run}, so a change or a test is made once (skill: make-it-a-template).\n` +
+    'Take the copies out first, then write the template. If this one truly differs, say so above it: `one-off: <reason>`.\n';
+}
+
+function remadeRefusal(name, line, where) {
+  return `${name} (line ${line}) already exists: ${where.map((x) => `${x.file}:${x.line}`).join(', ')}.\nCall it, and move it somewhere both can reach if it cannot be reached. ` +
+    'If it does a different job, give it a name that says so. If it truly must exist twice, say so above it: `one-off: <reason>`.\n';
+}
+
+function remade(defs, entries, rel) {
+  for (const [name, line] of defs) {
+    const where = Object.entries(entries).filter(([f]) => f !== rel && sameLanguage(rel, f)).flatMap(([file, e]) => (e.defs ?? []).filter(([n]) => n === name).map(([, l]) => ({ file, line: l })));
+    if (where.length && where.length < CONVENTION) return remadeRefusal(name, line, where);
+  }
+  return null;
+}
+
+function judgeWrite(w, rel) {
+  if (w.op === 'delete' || w.after === null || w.after === undefined || !EXTS.has(extname(w.path)) || matchesAny(rel, TESTS)) return null;
+  const before = readText(w.before ?? '', rel);
+  const after = readText(w.after, rel);
+  const count = (list) => list.reduce((m, s) => m.set(s.id, (m.get(s.id) ?? 0) + 1), new Map());
+  const was = count(before.shapes);
+  const here = count(after.shapes);
+  const fresh = after.shapes.filter((s, i) => after.shapes.findIndex((x) => x.id === s.id) === i && here.get(s.id) > (was.get(s.id) ?? 0));
+  const { statements, defs } = addedTo(before, after);
+  if (!fresh.length && !statements.length && !defs.length) return null;
+  const layout = readLayout(claudeRoot(w.path));
+  const skip = skippedBy(layout);
+  if (matchesAny(rel, skip) || isContent(rel, layout)) return null;
+  const root = checkoutRoot(w.path);
+  const entries = repoIndex(root, [...TESTS, ...skip], layout);
+  const others = copiesElsewhere(entries, rel);
+  for (const s of fresh) {
+    const elsewhere = others.get(s.id) ?? [];
+    const oneName = new Set([s.what, ...elsewhere.map((x) => x.what)]).size === 1;
+    if (here.get(s.id) + elsewhere.length >= copiesNeeded(s, oneName)) return refusal(s, w, rel, root, elsewhere, after.shapes);
+  }
+  const near = nearCopy(statements, Object.entries(entries).filter(([f]) => f !== rel && sameLanguage(rel, f)).map(([file, e]) => ({ file, st: e.st ?? [] })));
+  return near ? nearRefusal(near) : remade(defs, entries, rel);
+}
+
+const main = (text) => judgeEvent(text, { name: 'template-law', write: judgeWrite });
+
+function selftest() {
+  const hook = new URL(import.meta.url).pathname;
+  const card = (t) => `<div class="card"><h3 class="t">${t}</h3><p>${t} text</p><button type="button">Go</button></div>\n`;
+  const knob = (n) => `  ${n}.setRange (0.0, 1.0);\n  ${n}.setValue (0.5);\n  ${n}.setSliderStyle (Rotary);\n  addAndMakeVisible (${n});\n`;
+  // Stellix's way: many statements on one line, and a helper copied from file to file with other names.
+  const oneLine = (n) => `  ${n}.setRange (0.0, 1.0); ${n}.setValue (0.5); ${n}.setSliderStyle (Rotary); addAndMakeVisible (${n});\n`;
+  const reader = (f, id) => `auto ${f} = [this](const std::string& ${id}) {\n  const auto& L = shown(); float best = 0.0f;\n  for (const auto& c : L.controls) if (c.id == ${id}) best = c.box.getCentreX() * float(getWidth());\n  if (best > 10.0f) log(best, "${id}");\n  const auto p = at(best, 2.5f); pressAt(p); releaseAt(p); return best;\n};\n`;
+  const rows = (s) => `void seed(Entry& e) {\n${[...'abcdef'].map((k) => `  set(e, "${s}.${k}", 0.0f);\n`).join('')}}\n`;
+  const table = (t) => `const Row ${t}[] = {\n  { "a", 1, 2, 3 },\n  { "b", 4, 5, 6 },\n  { "c", 7, 8, 9 },\n  { "d", 1, 2, 3 },\n  { "e", 4, 5, 6 },\n  { "f", 7, 8, 9 },\n};\n`;
+  // A near copy: the same steps with a line changed every few lines, so no stretch of it is exact.
+  const steps = (n, odd) => `def ${n}(rows, limit):\n${[0, 1, 2, 3, 4, 5, 6, 7, 8, 9].map((i) => `    value_${i} = compute_step(rows[${i}], limit, scale=${i}, name="k${i}") + other(rows, ${i})\n${i % 3 === 2 && odd ? `    note_${i}(limit)\n` : ''}`).join('')}    return rows\n`;
+  const dir = scratchProject({ 'src/steps.py': steps('load_all', false), 'src/dates.ts': 'export function formatDateRange(a, b) {\n  return a + b;\n}\n', 'src/a.html': card('One'), 'src/ctl.cpp': `void build() {\n${knob('cutoff')}}\n`, 'tests/t.cpp': `void t() {\n${knob('probe')}}\n`, 'src/gate_a.h': reader('pressOf', 'id'), 'src/rows.cpp': table('kOne'), 'vendored/gate.h': reader('tapOf', 'key'), 'kept/gate.h': reader('holdOf', 'key'),
+    '.claude/layout.json': JSON.stringify({ folders: { vendored: { path: 'vendored', kind: 'copy' } }, guards: { templates: { exclude: ['kept/**'] } } }) });
+  const w = (file, content) => runHook(hook, dir, writeOf(join(dir, file), content));
+  return verdicts('template-law', [
+    ['a second card, in another file', w('src/b.html', card('Two')), 2],
+    ['two cards in one new file', w('src/c.tsx', card('A') + card('B')), 2],
+    ['a second hand-built control, other names', w('src/more.cpp', `void more() {\n${knob('resonance')}}\n`), 2],
+    ['the same control twice in one file', w('src/two.cpp', `void two() {\n${knob('a1')}\n  int x;\n${knob('b1')}}\n`), 2],
+    ['the same control, many statements on a line', w('src/line.cpp', `void line() {\n${oneLine('drive')}}\n`), 2],
+    ['a helper copied with other names', w('src/gate_b.h', reader('tapOf', 'key')), 2],
+    ['a table written as calls', w('src/seed.cpp', rows('seed')), 2],
+    ['a table as data rows', w('src/rows2.cpp', table('kTwo')), 0],
+    ['a copy tree', w('vendored/more.h', reader('dropOf', 'name')), 0],
+    ['a tree the layout excludes', w('kept/more.h', reader('dropOf', 'name')), 0],
+    ['a tutorial sample in a content folder', w('articles/guide/gate.h', reader('tapOf', 'key')), 0],
+    ['a near copy, with a line added every few lines', w('src/steps2.py', steps('load_more', true)), 2],
+    ['a function the repo already has, written again', w('src/other.ts', 'export function formatDateRange(x, y) {\n  return `${x} to ${y}`;\n}\n'), 2],
+    ['a plain-word name is not judged', w('src/plain.ts', 'export function render(x) {\n  return x;\n}\n'), 0],
+    ['the same name in another language', w('src/dates.py', 'def formatDateRange(a, b):\n    return a\n'), 0],
+    ['the component used three times', w('src/use.tsx', '<Card t="a" />\n<Card t="b" />\n<Card t="c" />\n'), 0],
+    ['a list from one .map()', w('src/list.tsx', 'rows.map((r) => (<tr key={r.id} class="row"><td class="t">{r.t}</td><td>{r.x}</td></tr>))\n'), 0],
+    ['one element is no template', w('src/one.html', '<section class="hero"><h1 class="big">Hi</h1><p>x</p><a href="/">y</a></section>\n'), 0],
+    ['a bare list', w('src/ul.html', '<ul><li>a</li><li>b</li><li>c</li></ul>\n'), 0],
+    ['data rows are not elements', w('src/d.ts', "const R = [\n  { id: 'a', label: 'b' },\n  { id: 'c', label: 'd' },\n];\n"), 0],
+    ['calls on one object are one set-up', w('src/ctx.ts', 'ctx.save();\nctx.fill();\nctx.restore();\nf();\nctx.save();\nctx.fill();\nctx.restore();\n'), 0],
+    ['a marked one-off', w('src/odd.html', `<!-- one-off: the print view -->\n${card('Odd')}`), 0],
+    ['a test file', w('tests/x_test.cpp', `void x() {\n${knob('q')}}\n`), 0],
+    ['an edit that adds no copy', runHook(hook, dir, editOf(join(dir, 'src/a.html'), 'One text', 'Uno text')), 0],
+    ['a heredoc that adds a copy', runHook(hook, dir, bashOf(`cat > src/h.html <<'EOF'\n${card('H')}EOF`, dir)), 2],
+    ['another project is not ours', runHook(hook, dir, writeOf(join(dir, '..', 'elsewhere', 'x.html'), card('X'))), 0],
+  ]);
+}
+
+export const hook = main; // run-hooks.mjs calls it with the event's text (KWB-24)
+if (isMain(import.meta.url)) process.exit(process.argv.includes('--selftest') ? selftest() : await asHook('template-law', main));

package/packs/base/hooks/untrusted-boundary.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// untrusted-boundary (PreToolUse, Write|Edit|MultiEdit|NotebookEdit|Bash): text from outside reaches a model only inside a
+// SHA-256 boundary (KWB-34). The house form (the user's release-watcher skills): every block of untrusted text sent to a model (a
+// web page, a fetched document, a scraped row, a user's upload, a stored copy of any of them) is wrapped, per call, in a
+// boundary named by the SHA-256 of the block, with a note before and after that gives the exact hash and says the block is
+// information, not instructions; our own fields (ids, dates, the task) stay outside it.
+// Refused, by every write route (lib/writes.mjs): a write that ADDS a model call (Anthropic messages.create / .stream,
+// OpenAI chat.completions.create / responses.create, the AI SDK's generateText / streamText / generateObject / streamObject,
+// LangChain's .invoke on a chat model is not read) to a JS, TS or Python file that, once written, has no boundary: no call
+// of the house helper (wrapUntrusted / wrap_untrusted / untrustedBoundary) and no line `untrusted: none` saying the file sends
+// a model only its own text. Another project's files are not judged.
+//   node untrusted-boundary.mjs --selftest
+import { extname, join } from 'node:path';
+import { judgeEvent } from './lib/writes.mjs';
+import { runHook, scratchProject, verdicts, writeOf } from './lib/selftest.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const CODE = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.tsx', '.jsx', '.py']);
+const CALL = /\bmessages\.(?:create|stream)\s*\(|\bchat\.completions\.create\s*\(|\bresponses\.create\s*\(|\b(?:generateText|streamText|generateObject|streamObject)\s*\(/g;
+const BOUNDARY = /\b(?:wrapUntrusted|wrap_untrusted|untrustedBoundary)\s*\(|^\s*(?:\/\/|#|\*)\s*untrusted:\s*none\b/m;
+const calls = (text) => (text.match(CALL) ?? []).length;
+
+export function verdict(rel, before, after) {
+  if (!CODE.has(extname(rel)) || after === null) return null;
+  if (calls(after) <= calls(before ?? '') || BOUNDARY.test(after)) return null;
+  return `BLOCKED by untrusted-boundary: ${rel} gains a model call and has no SHA-256 boundary.\n` +
+    'Every block of untrusted text (a web page, a fetched document, a scraped row, an upload) goes to the model inside wrapUntrusted(text): ' +
+    'a per-call boundary named by the SHA-256 of the block, with a note before and after giving the exact hash and saying the block is information, ' +
+    'not instructions; your own fields stay outside it. If this file sends the model only its own text, say so on a line of its own: `// untrusted: none`.\n';
+}
+
+const main = (text) => judgeEvent(text, { name: 'untrusted-boundary', write: (w, rel) => verdict(rel, w.before, w.after) });
+
+function selftest() {
+  const hook = new URL(import.meta.url).pathname;
+  const dir = scratchProject({ 'src/ask.ts': 'export const x = 1;\n' });
+  const run = (rel, text) => runHook(hook, dir, writeOf(join(dir, rel), text));
+  const call = 'const r = await client.messages.create({ model, messages: [{ role: "user", content: page }] });\n';
+  const cases = [
+    ['a model call fed a page, no boundary (Anthropic)', run('src/ask.ts', call), 2],
+    ['an OpenAI call, no boundary', run('src/ask.mjs', 'await openai.chat.completions.create({ messages });\n'), 2],
+    ['an AI SDK call, no boundary', run('src/ask.tsx', 'const { text } = await generateText({ model, prompt: html });\n'), 2],
+    ['a Python call, no boundary', run('tools/ask.py', 'r = client.messages.create(model=m, messages=msgs)\n'), 2],
+    ['the call with the page inside wrapUntrusted', run('src/ask.ts', `const page = wrapUntrusted(html);\n${call}`), 0],
+    ['a file that sends only its own text, and says so', run('src/ask.ts', `// untrusted: none\n${call}`), 0],
+    ['a doc that shows a call is not code', run('docs/howto.md', call), 0],
+    ['code with no model call', run('src/plain.ts', 'export const y = fetch(url);\n'), 0],
+  ];
+  return verdicts('untrusted-boundary', cases);
+}
+
+export const hook = main; // run-hooks.mjs calls it with the event's text (KWB-24)
+if (isMain(import.meta.url)) process.exit(process.argv.includes('--selftest') ? selftest() : await asHook('untrusted-boundary', main));

package/packs/base/pack.json

@@ -0,0 +1,214 @@
+{
+  "name": "base",
+  "version": "1.0.0",
+  "description": "Universal engineering every configuration gets: the git laws, the line limit, the folder and placement laws, the shape law (shape-law, brief-guard, making, making-check), once-only, lesson checks, secrets-guard and the untrusted-content boundary.",
+  "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/base"
+  },
+  "keywords": [
+    "universal",
+    "git",
+    "hooks"
+  ],
+  "engines": {
+    "claude-packs": ">=0.19.0"
+  },
+  "concepts": {
+    "cpp": [
+      "src/**/*.cpp",
+      "src/**/*.h",
+      "src/**/*.hpp",
+      "src/**/*.mm",
+      "tests/**/*.cpp",
+      "tests/**/*.h"
+    ],
+    "tests": [
+      "tests"
+    ],
+    "build": [
+      "**/CMakeLists.txt",
+      "**/*.cmake",
+      "CMakePresets.json"
+    ],
+    "claude": [
+      ".claude/skills/**",
+      "**/.claude/skills/**",
+      ".claude/agents/**",
+      ".claude/rules/**"
+    ],
+    "notes": [
+      "bugs.md",
+      "workflow-bugs.md",
+      "**/known-issues*.md",
+      "docs/**/*.md"
+    ],
+    "docs-folder": [
+      "docs"
+    ],
+    "tooling": [
+      "tools/**",
+      ".claude/hooks/**",
+      ".claude/settings.json"
+    ],
+    "plan": [
+      "build.md",
+      "**/build.md"
+    ],
+    "copy-trees": [
+      "kind:copy",
+      ".claude/layout.json"
+    ],
+    "js": [
+      "src/**/*.{js,mjs,cjs,jsx,ts,tsx}",
+      "tests/**/*.{js,mjs,cjs,ts,tsx}",
+      "test/**/*.{js,mjs,cjs,ts,tsx}"
+    ]
+  },
+  "skillsIn": null,
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/lesson-checks.mjs\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/file-size-guard.mjs\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/placement-law.mjs\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/folder-law.mjs\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/shape-law.mjs\"",
+            "timeout": 15
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/brief-guard.mjs\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/once-only.mjs\"",
+            "timeout": 20
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/secrets-guard.mjs\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/untrusted-boundary.mjs\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/dispatch-once.mjs\"",
+            "timeout": 15
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/template-law.mjs\"",
+            "timeout": 15
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/code-shape.mjs\"",
+            "timeout": 15
+          }
+        ]
+      },
+      {
+        "matcher": "Agent|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/brief-guard.mjs\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/git-guard.mjs\"",
+            "timeout": 15
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/suite-once.mjs\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/repo-litter.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/making-check.mjs\"",
+            "timeout": 60
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/git-guard.mjs\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/making.mjs\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/reuse-hint.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  },
+  "onByDefault": [
+    "hooks/shape-law.mjs",
+    "hooks/brief-guard.mjs",
+    "hooks/once-only.mjs",
+    "hooks/making.mjs",
+    "hooks/making-check.mjs",
+    "hooks/run-hooks.mjs"
+  ],
+  "optIn": []
+}

package/packs/base/rules/a-control-is-seen-to-fire.md

@@ -0,0 +1,27 @@
+---
+# concepts: cpp, js, tests
+paths:
+  - "placeholder"
+---
+
+# A control is seen to fire, and a test can fail for the reason that matters
+
+<constraints>
+Always do:
+- Prove a control (a guard, an audit log, a limiter) through the real path, and see it refuse.
+- Make a mock return what the real function returns.
+- Keep one test per data layer against the real store.
+- Fail a test when its setup failed.
+- Break every check on purpose, and write to the state you inject: an injection that passes means dead code or a missing check.
+- Establish which artefact you are looking at before diagnosing: check the binary's time and the server's age.
+
+Never do:
+- Return success from a stub, or leave `// for now` in front of `success: true`.
+- Declare a security dependency and never use it.
+- Skip a test because an earlier step made nothing.
+- Let a check recompute its own subject: it holds by construction.
+- Leave a local workaround with no test that fails the day upstream is fixed.
+</constraints>
+
+## Check
+`stub-reports-success`, `test-skip-on-failed-setup`.

package/packs/base/rules/behaviour-lives-with-its-kind.md

@@ -0,0 +1,51 @@
+---
+# concepts: cpp, js
+paths:
+  - "placeholder"
+---
+
+# Behaviour lives with its kind: objects and tables, not branches
+
+<constraints>
+Always do:
+- When behaviour varies by a **kind** (mode, type, action, tool, message, format), each kind owns its behaviour in **one place**:
+  - **JS/TS:** a table of handler objects `{ kind: { label, build(), validate() } }` typed `satisfies Record<Kind, Handler>`. Or classes implementing one interface, chosen once from a registry.
+  - **C++:** an interface with one class per kind, created once from a registry or factory. Or `std::variant` + `std::visit`, where the compiler checks every kind is handled. Or a `constexpr` table of plain data per kind.
+- Choose the object **once**, when the kind is set (a setting changes, a request arrives, a file is opened), then call it, so no code asks "which kind?" again.
+- A new kind is **one new entry** (one class or one table row), with nothing else edited. If adding a kind needs edits in several files, the design is wrong; fix the design.
+
+Never do:
+- Branch on the same kind in more than one place (`switch (mode)` in the renderer, the label code and the config loader). The `dispatch-once` hook refuses the second one.
+- Grow a `switch` or an if-chain past three cases where a table or an object belongs (`lookup-over-if-chains`, `field-map-over-if-runs`).
+
+The one exception is **a hot inner loop** (per element, per pixel, per sample: an audio callback is one; audio-core's `per-sample-code-inlinable` says why). There a virtual call or a `std::function` can't be inlined and costs on every iteration. The kind's object is still chosen once, but its inner loop may be:
+- a non-virtual member function chosen when the kind is set;
+- a `constexpr` table;
+- or one exhaustive `switch` on an `enum class` **inside that kind's owner**, never repeated elsewhere.
+</constraints>
+
+```ts
+// NO: the same question asked in three places, and a new kind means three edits
+switch (tool.kind) { case 'search': … case 'fetch': … }   // run
+switch (tool.kind) { case 'search': … case 'fetch': … }   // label
+switch (tool.kind) { case 'search': … case 'fetch': … }   // validate
+
+// YES: each kind answers for itself
+const TOOLS = {
+  search: { label: 'Search', schema: SearchArgs, run: runSearch },
+  fetch:  { label: 'Fetch',  schema: FetchArgs,  run: runFetch },
+} satisfies Record<ToolKind, ToolHandler>;
+const tool = TOOLS[kind];            // chosen once
+tool.schema.parse(args); return tool.run(args);
+```
+
+```cpp
+// YES (outside a hot inner loop): one class per kind, chosen once
+struct Shape { virtual ~Shape() = default; virtual std::string label() const = 0; virtual void prepare (const Settings& s) = 0; };
+std::unique_ptr<Shape> makeShape (Mode m);   // the one factory: the only place that names every kind
+```
+
+## Check
+- `dispatch-once` (hook) refuses an edit that adds a `switch` on a kind already switched on in another file.
+- `lookup-over-if-chains` and `field-map-over-if-runs` (lesson checks) refuse new if-chains and field runs.
+- If branching on a kind ever slips through in a new shape (a ternary ladder, a `match`, an `if` on `typeid`), add that shape to a check.

package/packs/base/rules/bug-fix-starts-red.md

@@ -0,0 +1,25 @@
+---
+# concepts: tests, cpp
+paths:
+  - "placeholder"
+---
+
+# A bug fix starts with a test that fails for that bug
+
+<constraints>
+Always do:
+- Before touching the code, write the smallest test or probe that reproduces the bug: a render, a parameter sequence, a MIDI file, a state load.
+- Run it and see it fail for the reported reason: `node .claude/tools/test-verdict.mjs --red <test-name>` must say `RED_CONFIRMED`.
+- Freeze what defines "fixed" before the fix, where the project has `freeze.mjs`: `node .claude/tools/freeze.mjs on "bug <id>" <test file> <golden files>`.
+- Fix the code until the same test passes, then run the full suite once, then unfreeze.
+- Keep the test in the suite forever. That is what stops the bug coming back.
+
+Never do:
+- Fix first and write the test after. A test written against the fix proves nothing.
+- Edit the test, the golden render or the fingerprint to make the fix pass. If the target is wrong, stop and ask.
+- Call a bug fixed because the symptom went away once by ear.
+</constraints>
+
+## Check
+- The `frozen-files` hook refuses edits to frozen files.
+- `test-verdict.mjs --red` exits 1 if a test that must fail passes.

package/packs/base/rules/field-map-over-if-runs.md

@@ -0,0 +1,47 @@
+---
+# concepts: cpp, js
+paths:
+  - "placeholder"
+---
+
+# Three ifs in a row on one object's fields: a field table and one loop
+
+<constraints>
+Always do:
+- When **3 or more `if`s in a row** test fields of the same object (`args.filter?.flag`, `args.filter?.kind`, `args.filter?.path`…) to copy, map or build something, write a **field table** and **one loop**:
+  - **JS/TS:** a module-scope object from field name to what to do with it, typed against the input (`satisfies Record<keyof Filter, …>`), and one `for … of Object.entries(TABLE)` that applies it. A new field is one new row.
+  - **C++:** a `constexpr std::array` of `{ name, member pointer / setter }`, and one loop.
+- **Validation of required fields** is the same law: a list of required keys, and one loop that names the first one missing.
+- Use the schema as the table when one exists (Zod `pick`/`partial`, a Mongo filter builder), rather than a hand-written list.
+
+Never do:
+- Write `if (src.a !== undefined) dst.a = …; if (src.b !== undefined) dst.b = …; if (src.c …` one field per line. It grows by one line per field until it's fifteen.
+- Hide the run by putting an unrelated line between the ifs.
+
+`if` is still right for:
+- two fields;
+- fields of different objects;
+- conditions on different things.
+</constraints>
+
+```ts
+// NO
+if (args.filter?.flag !== undefined) filter.flags = args.filter.flag;
+if (args.filter?.kind !== undefined) filter.kind = args.filter.kind;
+if (args.filter?.path !== undefined) filter.path = { $regex: escapeRe(args.filter.path) };
+
+// YES: one row per field, one loop
+const FILTER_FIELDS = {
+  flag: (v) => ({ flags: v }),
+  kind: (v) => ({ kind: v }),
+  path: (v) => ({ path: { $regex: escapeRe(v) } }),
+} satisfies Record<keyof NonNullable<Args['filter']>, (v: never) => Partial<Filter>>;
+
+for (const [key, put] of Object.entries(FILTER_FIELDS)) {
+  const value = args.filter?.[key];
+  if (value !== undefined) Object.assign(filter, put(value));
+}
+```
+
+## Check
+`.claude/checks/field-map-over-if-runs.json` refuses an edit that **adds** three ifs on fields of the same object within a few lines of each other. It covers `!== undefined`, `!= null`, truthy tests, `?.`, `.` and `->`. Its companion is `lookup-over-if-chains`, for branches on one value. If a run ever slips through in a new shape, tighten the check rather than fixing the one case.

package/packs/base/rules/finished-work-lands.md

@@ -0,0 +1,17 @@
+---
+# hook: git-guard.mjs
+---
+# Finished work lands: a finished branch is merged into the trunk and pushed
+
+<constraints>
+Always do:
+- When a work branch's "done when" is measured and the whole suite is green, land it in the same turn with the `land-branch` skill. The trunk is always up to date.
+- Land stacked branches in order, or land the top one when it holds them all.
+- Say what landed, and the commit the remote now has.
+
+Never do:
+- Leave finished work on a branch waiting for someone to ask.
+- Land work that is unfinished, or has a red test. A branch that cannot land yet says why.
+- Ask before pushing a work branch: a work branch always pushes, from its first commit, with no yes needed.
+- Land on the trunk over a project's own law: only the trunk can need a yes. Where its CLAUDE.md says so, ask once, with the branch pushed and ready.
+</constraints>

package/packs/base/rules/git-right-first-time.md

@@ -0,0 +1,19 @@
+---
+# hook: git-guard.mjs
+---
+# Git in the form the guard takes, the first time
+
+<constraints>
+Always do:
+- Stage by name: `git add <paths>`, then `git commit -m "..." -- <paths>`.
+- Push every commit before the next one, and every branch from its first commit: a later commit and the session's end both wait for it. A work branch never needs a yes to push; only the trunk can.
+- Push to the repo by name: a remote whose URL is the owner's SSH URL, or the token form with the token as `$VARIABLE`, never pasted.
+- Name the token on every `gh` call, when the project's guards ask for it.
+- Commit before undoing anything: a work-in-progress commit on a branch, then undo.
+- Start work on a branch from the fetched remote trunk.
+
+Never do:
+- `git add -A`, `git add .` or `commit -a`.
+- Rebase, amend, force a push or use `--no-verify`: make a new commit.
+- Put a command that a guard judges in the same call as the step it depends on: a guard reads the whole command before any of it runs.
+</constraints>