@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/packs/synth-creator/hooks/user-asks.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// user-asks: everything the user asked, back in front of the session, so nothing discussed is forgotten (2026-10-11:
+// "Sometimes you 'forget' certain things we had discussed ... maybe you also need to check memory at this time?").
+//
+// Every message the user sends is in the session's transcript: a turn of their own (type `user`, their text) or a message sent
+// while the session was working (a `queue-operation` enqueue). This reads them back, with their times, two ways:
+//   - a SessionStart hook on `compact`: their asks of the last HOURS hours go back into the context, word for word;
+//   - idle-wake.mjs: the wake after their silence carries the same list.
+// THE LEDGER: each ask has a status and its evidence, beside the project's own memory folder
+// (~/.claude/projects/<the project's path, every character not a letter or digit made a dash>/asks-ledger.json), outside
+// git, so compaction cannot touch it. Only OPEN asks come back word for word; done or answered ones are a count; needs-user
+// and planned ones are one line each. Marking takes evidence (a commit, a bug number, a build.md step, or where it is planned):
+//   node user-asks.mjs --transcript <path> [--hours 24] [--all]
+//   node user-asks.mjs --mark <id> done|answered|planned|needs-user|not-an-ask "<evidence>"
+//   node user-asks.mjs --selftest
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+export const HOURS = Number(process.env.TIMS_ASKS_HOURS ?? 24);
+const STATUSES = new Set(['done', 'answered', 'planned', 'needs-user', 'not-an-ask', 'open']);
+const QUIET = new Set(['done', 'answered', 'not-an-ask']);
+const HEAD = (h, n) => `TIM'S ASKS from the last ${h.toFixed(0)} hours (${n} messages). Compaction may have dropped some of them from what you remember; ` +
+  'the ledger below holds which are done, with evidence. Every OPEN one is work: check it is not already done (then mark it with the evidence), ' +
+  'finish it, or if it needs the user say so in one line and mark it needs-user. Do not wait to be reminded.';
+
+const mainRoot = (p) => p.replace(/\/\.claude\/worktrees\/[^/]+(\/.*)?$/, '');
+export const ledgerFor = (root) => join(homedir(), '.claude', 'projects', mainRoot(resolve(root)).replace(/[^A-Za-z0-9]/g, '-'), 'asks-ledger.json');
+export const LEDGER = process.env.TIMS_ASKS_LEDGER || ledgerFor(process.env.CLAUDE_PROJECT_DIR ?? process.cwd());
+
+// The user's own words in a transcript entry, or null (a tool's result, a hook's or the system's text, an agent's report).
+function textOf(e) {
+  if (e.type === 'queue-operation' && e.operation === 'enqueue') return typeof e.content === 'string' ? e.content : null;
+  if (e.type === 'user' && !e.isMeta && !e.isSidechain) {
+    let c = e.message?.content;
+    if (Array.isArray(c)) c = c.filter((b) => b && b.type === 'text').map((b) => b.text ?? '').join('\n');
+    return typeof c === 'string' ? c : null;
+  }
+  return null;
+}
+const isSystem = (t) => { const s = t.trimStart(); return !s || /^(<|\[SYSTEM|\[Subagent|idle-wake:|This session is being continued|Caveat:)/.test(s); };
+const squash = (t) => t.split(/\s+/).filter(Boolean).join(' ');
+
+export function asks(transcript, hours = HOURS, now = Date.now() / 1000) {
+  let text;
+  try { text = readFileSync(transcript, 'utf8'); } catch { return []; }
+  const out = [];
+  const seen = new Set();
+  for (const line of text.split('\n')) {
+    if (!line.includes('"queue-operation"') && !line.includes('"type":"user"') && !line.includes('"type": "user"')) continue;
+    let e;
+    try { e = JSON.parse(line); } catch { continue; }
+    const t = textOf(e);
+    if (!t || isSystem(t)) continue;
+    const when = e.timestamp ? Date.parse(e.timestamp) / 1000 : null;
+    if (when !== null && !Number.isNaN(when) && now - when > hours * 3600) continue;
+    const key = squash(t);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push([Number.isNaN(when) ? null : when, t.trim()]);
+  }
+  return out;
+}
+
+export const askId = (t) => createHash('sha1').update(squash(t)).digest('hex').slice(0, 8);
+export function loadLedger(path = LEDGER) { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return {}; } }
+
+export function mark(id, status, evidence = '', path = LEDGER) {
+  if (!STATUSES.has(status)) throw new Error(`status is one of ${[...STATUSES].sort().join(', ')}`);
+  if (status !== 'open' && !evidence.trim()) throw new Error('evidence is required: a commit, a bug number, a build.md step, or where it is planned');
+  const led = loadLedger(path);
+  led[id] = { status, evidence: evidence.trim(), marked: new Date().toISOString().slice(0, 19) };
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(`${path}.tmp`, JSON.stringify(led, null, 1));
+  renameSync(`${path}.tmp`, path);
+}
+
+export function render(items, hours = HOURS, ledger = null, every = false) {
+  if (!items.length) return '';
+  const led = ledger ?? loadLedger();
+  const stamp = (w) => (w ? new Date(w * 1000).toISOString().slice(5, 16).replace('T', ' ') : '     ?     ');
+  const rows = items.map(([w, t]) => { const id = askId(t); return { w, t, id, st: led[id]?.status ?? 'open', ev: led[id]?.evidence ?? '' }; });
+  const open = rows.filter((r) => r.st === 'open');
+  const waits = rows.filter((r) => r.st === 'needs-user' || r.st === 'planned');
+  const quiet = rows.filter((r) => QUIET.has(r.st));
+  const lines = [HEAD(hours, items.length),
+    `LEDGER (${LEDGER}): ${quiet.length} done or answered, ${waits.length} waiting on the user or planned, ${open.length} OPEN. Only the open ones are work; ` +
+    'do not redo a done one. When one is done, mark it with its evidence: node .claude/hooks/user-asks.mjs --mark <id> done "<commit / bug / step>" ' +
+    '(or answered, planned, needs-user, not-an-ask).'];
+  if (open.length) { lines.push('OPEN, word for word:'); for (const r of open) lines.push(`- ${r.id} [${stamp(r.w)}] ${squash(r.t).slice(0, 1200)}`); }
+  if (waits.length) { lines.push('WAITING (one line each):'); for (const r of waits) lines.push(`- ${r.id} [${stamp(r.w)}] ${r.st}: ${r.ev.slice(0, 160)} <- ${squash(r.t).slice(0, 90)}`); }
+  if (every && quiet.length) { lines.push('DONE / ANSWERED:'); for (const r of quiet) lines.push(`- ${r.id} [${stamp(r.w)}] ${r.st}: ${r.ev.slice(0, 120)} <- ${squash(r.t).slice(0, 90)}`); }
+  return lines.join('\n');
+}
+
+function selftest() {
+  const now = Date.now() / 1000;
+  const iso = (dt) => new Date((now - dt) * 1000).toISOString();
+  const rows = [
+    { type: 'user', timestamp: iso(3600), message: { content: 'add 20 80s bass arps' } },
+    { type: 'queue-operation', operation: 'enqueue', timestamp: iso(1800), content: 'and make a hook for chrome' },
+    { type: 'queue-operation', operation: 'remove', timestamp: iso(1799), content: 'and make a hook for chrome' },
+    { type: 'user', timestamp: iso(1700), message: { content: [{ type: 'tool_result', content: 'ok' }] } },
+    { type: 'user', timestamp: iso(1600), message: { content: '<task-notification>done</task-notification>' } },
+    { type: 'user', timestamp: iso(1500), isMeta: true, message: { content: 'a meta line' } },
+    { type: 'user', timestamp: iso(90000), message: { content: 'an ask from two days ago' } },
+    { type: 'user', timestamp: iso(60), message: { content: [{ type: 'text', text: 'is it correct the agents still run?' }] } },
+    { type: 'assistant', timestamp: iso(30), message: { content: "Next I'd build P4." } },
+  ];
+  const t = join(tmpdir(), `user-asks-${process.pid}.jsonl`);
+  writeFileSync(t, rows.map((r) => JSON.stringify(r)).join('\n'));
+  const items = asks(t, 24, now);
+  rmSync(t, { force: true });
+  const led = `${t}.ledger.json`;
+  mark(askId('add 20 80s bass arps'), 'done', 'commit abc123', led);
+  const out = render(items, 24, loadLedger(led));
+  rmSync(led, { force: true });
+  const checks = [
+    ['a done ask is counted, not listed; the open ones are listed word for word', out.includes('1 done or answered') && out.includes('2 OPEN') && !out.includes('add 20 80s bass arps') && out.includes('and make a hook for chrome')],
+    ['done without evidence is refused', (() => { try { mark('x', 'done', '', led); return false; } catch { return true; } })()],
+    ["the user's own words, mid-turn ones too, no tool results, system text, meta lines, their old asks or the assistant",
+      JSON.stringify(items.map(([, x]) => x)) === JSON.stringify(['add 20 80s bass arps', 'and make a hook for chrome', 'is it correct the agents still run?'])],
+    ["the ledger is the project's own, beside its memory, and a worktree's is its project's",
+      ledgerFor('/Users/dev/projects/my_synth') === join(homedir(), '.claude/projects/-Users-dev-projects-my-synth/asks-ledger.json') &&
+      ledgerFor('/Users/dev/projects/my_synth/.claude/worktrees/agent-x') === ledgerFor('/Users/dev/projects/my_synth')],
+  ];
+  for (const [name, ok] of checks) if (!ok) console.error(`FAIL  ${name}`);
+  const bad = checks.filter(([, ok]) => !ok).length;
+  console.log(`user-asks selftest: ${bad ? 'FAIL' : 'OK'}`);
+  return bad ? 1 : 0;
+}
+
+function main(argv) {
+  if (argv.includes('--selftest')) return selftest();
+  const i = argv.indexOf('--mark');
+  if (i >= 0) {
+    try { mark(argv[i + 1], argv[i + 2], argv[i + 3] ?? ''); } catch (e) { console.error(e.message); return 1; }
+    console.log(`marked ${argv[i + 1]} ${argv[i + 2]}`);
+    return 0;
+  }
+  const ti = argv.indexOf('--transcript');
+  if (ti >= 0) {
+    const h = argv.includes('--hours') ? Number(argv[argv.indexOf('--hours') + 1]) : HOURS;
+    console.log(render(asks(argv[ti + 1], h), h, null, argv.includes('--all')));
+    return 0;
+  }
+  // A HOOK (SessionStart on compact): what it prints is added to the session's context
+  return asHook('user-asks', hookMain);
+}
+
+function hookMain(input) {
+  let event;
+  try { event = JSON.parse(input); } catch { return 0; }
+  const text = render(asks(event.transcript_path ?? ''));
+  if (text) console.log(text);
+  return 0;
+}
+export const hook = hookMain; // run-hooks.mjs calls it with the event's text (KWB-24)
+
+// Run as a hook or a command (not imported by idle-wake). Real paths: /var and /private/var are one folder on a Mac.
+const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
+if (process.argv[1] && real(process.argv[1]) === real(fileURLToPath(import.meta.url))) process.exit(await main(process.argv.slice(2)));

package/packs/synth-creator/pack.json

@@ -0,0 +1,136 @@
+{
+  "name": "synth-creator",
+  "version": "1.0.0",
+  "description": "The synth-creator configuration's own laws, installed with it and never by another: the build queue (build-guard), the time watch, the spec lock, frozen fixes, read-only vendored code and copy trees, staging by name, the session watches (idle-wake, user-asks, build-sweep), and the rules and skill a synth build lives by.",
+  "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/synth-creator"
+  },
+  "keywords": [
+    "synth",
+    "build"
+  ],
+  "engines": {
+    "claude-packs": ">=0.19.0"
+  },
+  "configurationPack": true,
+  "folders": {},
+  "concepts": {},
+  "skillsIn": null,
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/frozen-files.mjs\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/protect-vendor.mjs\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/spec-lock.mjs\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/stage-guard.mjs\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/build-guard.mjs\"",
+            "timeout": 15
+          }
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/time-guard.mjs\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/time-guard.mjs\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/idle-wake.mjs\"",
+            "asyncRewake": true,
+            "timeout": 1000
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/user-asks.mjs\"",
+            "timeout": 15
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/build-sweep.mjs\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/build-sweep.mjs\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  },
+  "optIn": [
+    "hooks/user-asks.mjs",
+    "hooks/idle-wake.mjs",
+    "hooks/build-sweep.mjs",
+    "checks/ui-drawn-in-code.json"
+  ]
+}

package/packs/synth-creator/rules/copy-trees-read-only.md

@@ -0,0 +1,25 @@
+---
+# concepts: copy-trees
+paths:
+  - "placeholder"
+---
+
+# Copy trees: copied, pinned, read-only
+
+A copy tree is a folder of kind `"copy"` in `.claude/layout.json`: another project's code, copied unchanged and proved
+identical (the `copy-and-prove` skill). This rule loads in every copy tree and in `layout.json`, where one is declared.
+
+<constraints>
+Always do:
+- Treat every file here as a copy of another project's file at a named commit. It changes only through the project's copy tools (`guards.copy.tools` in `layout.json`): from its source, unchanged, or as a pinned change the user said yes to and null tests proved.
+- Give every file its origin before it comes in (repo, path, commit, SHA-256, licence row). The licence row in `docs/licences.md` comes first.
+- Prove the copy before anything uses it: the source's own render fingerprinted, the copy IDENTICAL, one coefficient changed in the copy seen DIFFERENT.
+- Fix the code that uses the copy. If the copy itself must change, ask the user and pin the change.
+- Start a new copy tree only in `.claude/layout.json`, as a folder with `"kind": "copy"`. The guard, this rule and the checks then cover it with no other change.
+- Change a file that measured identical only after it is promoted out of the copy tree into the project's own code (a folder of kind `"own"`), with its origin record kept.
+
+Never do:
+- Edit, write, move or delete a file here by hand or by shell. The `protect-vendor` hook refuses it; only git and the sanctioned copy tools get through.
+- Put a file here without its origin.
+- Copy hardware, brand or machine names into anything that reaches the product: a program name, a label, a string in the binary.
+</constraints>

package/packs/synth-creator/rules/debug-by-measurement.md

@@ -0,0 +1,20 @@
+---
+# concepts: cpp, tests
+paths:
+  - "placeholder"
+---
+
+# Debug by measuring, one hypothesis at a time
+
+<constraints>
+Always do:
+- Reproduce first, then measure: render the case offline, read the numbers (`measure-tone`, a probe, a sanitizer, a log), and only then form a cause.
+- State one falsifiable hypothesis ("the click is the filter state reset at voice steal, because the click lines up with sample N of the steal") and test it with one change.
+- Treat "the host is wrong", "it's JUCE", "it's the driver" as a hypothesis to disprove with a minimal probe, never as the answer. Assume our code is wrong until a probe proves otherwise.
+- After three fixes that didn't work, stop changing code. Report what was tried, what each measurement showed, and whether the design itself is the problem.
+
+Never do:
+- Change several things at once, then listen.
+- Tweak constants until it "sounds right" without a measurement before and after.
+- Start a fourth fix attempt on the same symptom without telling the user.
+</constraints>

package/packs/synth-creator/rules/done-means-fresh-evidence.md

@@ -0,0 +1,18 @@
+---
+# concepts: tests, build
+paths:
+  - "placeholder"
+---
+
+# "Done" means evidence from this turn
+
+<constraints>
+Always do:
+- Before saying done, fixed, passing, faster or "sounds the same", run the command that proves it in this turn and quote its verdict: test-verdict JSON, null-test result in dBFS, benchmark p99, golden-image score.
+- Say exactly what was not verified, and why ("not run on Windows", "listened only, not measured").
+- Treat a subagent's report as a claim. Check its diff and re-run its verdict before passing it on.
+
+Never do:
+- Report success from memory of an earlier run, from a build that only compiled, or from "should work".
+- Report a partial pass as a pass.
+</constraints>

package/packs/synth-creator/rules/hooks-and-gates.md

@@ -0,0 +1,21 @@
+---
+# concepts: tooling
+paths:
+  - "placeholder"
+---
+
+# Hooks, gates and tools: each seen red, each fault logged
+
+<constraints>
+Always do:
+- Give every hook and gate a `--selftest` that plants its fault, and run it from the project's plants script (the `plants` command in `.claude/layout.json`). A new gate goes in there in the same commit. A gate that has never been seen red proves nothing.
+- Log a workflow fault (a hook, a tool, the build queue, a test run) in `workflow-bugs.md` before fixing it (the `workflow-bugs` skill), and close it with cause, fix and what now catches it.
+- Run Python on files that come from outside with `-I`. Measure files with Python, not with BSD or GNU tool flags.
+- Keep a planted fault in the test build only: one macro or `constexpr` flag that is false in the shipped binary, and a release gate that searches the binary for it (`cpp-faults-only-in-the-test-build`).
+- Treat a hook that blocks correct work as a red check: stop, report its exact message, and log it. The hook is fixed first, with a selftest that plants the right case and the wrong one; the work resumes after.
+- Make a fix to a hook, rule, check or skill that every synth uses in claude-packs, with its test, then take it in with `npx --no-install @thedecipherist/claude-packs update`. Only a law that is about this project alone stays in this project's `.claude/`.
+
+Never do:
+- Route around a block: no code put into an unrelated existing file, no file pushed past the line limit, no write through the shell after a refusal, no override variable.
+- Change a hook so that its own selftest passes while the fault it exists for gets through.
+</constraints>

package/packs/synth-creator/rules/long-work-in-the-background.md

@@ -0,0 +1,16 @@
+---
+# hook: time-guard.mjs
+---
+# Long work runs in the background, and a warning about time is acted on
+
+<constraints>
+Always do:
+- Start anything over about two minutes as a background job with its output in a file; you are told when it ends. Do other work meanwhile.
+- When `time-guard` says something is slow, look at it now: find what is running, say so, and stop it if it is not needed.
+- Commit an agent's work when `time-guard` says it has gone unsaved.
+
+Never do:
+- Wait in a `sleep`, `until` or `pgrep` loop, or poll a job's output file.
+- Start a second copy of a job that is still running, or start it again without reading why the first one ended.
+- Treat a slow job as normal because the last one was slow too.
+</constraints>

package/packs/synth-creator/rules/timing-from-synthcore.md

@@ -0,0 +1,16 @@
+---
+# concepts: cpp
+---
+
+# Time and keys come from synthcore: one clock, written once
+
+<constraints>
+Always do:
+- Link `synthcore` for tempo, MIDI clock, transport, sync modes, QWERTY and the focus rule. Subclass `core::CoreHost`, and make `host.readTransport (getPlayHead(), midi, n);` the first line of `processBlock`.
+- Have every tempo-synced thing read the one master clock. Tap tempo sets the same `bpm` parameter the clock reads.
+- Fix a fault in the clock in `synthcore`, once, with its test, and take it in everywhere.
+
+Never do:
+- Read the play head, count MIDI clock bytes or work out a tempo in a unit. `timing-from-synthcore` refuses it.
+- Copy `synthcore`'s code into a unit, or write a second clock because one thing needs it.
+</constraints>

package/packs/synth-creator/skills/build-step/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: build-step
+description: Use when work begins on a step of a synth's build.md, when a step's "done when" may be met, when a session starts or ends in a repo with a build.md, or when someone asks where the build is. Also /build-step.
+---
+
+# One build step: its own branch, from start to merge
+
+The canonical text is the repo's own `build.md` ("Rules for this file") and its `CLAUDE.md`. This file is the operating
+summary. Where they disagree, the repo wins. The step tool is the project's (the `step` command in `.claude/layout.json`,
+usually `python3 tools/step.py`); if the repo has none, copy `tools/step.py` and `tools/hooks/` from a sibling synth that
+has them before doing any of this by hand.
+
+The house rule: **every build task is built in a new branch. Once completed it is merged into the
+trunk. We must not be able to lose any work.** MegaSynth lost two days of panel work to one checkout, more to work nobody
+had written down as started, and more to steps called done because the code compiled. A step is a promise with a
+measurement on the end, and a pushed branch is what a dead session leaves behind.
+
+## 0. Before acting on a paste from the user
+
+- If the project's spec carries an edition line ("Spec edition: ..." at the top of `docs/*-spec.md`) and the paste names an
+  edition, check the file shows it. Older, or no line: **stop and say so**, naming both editions.
+- Every file a paste names must be there. One missing or older: **stop and tell the user**, naming the file and what was found;
+  do not carry on with the parts that do not depend on it.
+
+## 1. At the start of a session
+
+```
+python3 tools/step.py status
+```
+
+It prints the count, the current step, the branch you are on, uncommitted changes and every branch not yet merged, with
+its last commit. An unmerged branch is unfinished work: read its last commit message and its In-progress row before
+starting anything else. Read `bugs.md`'s Open table too.
+
+**If the work in front of you is not a step in build.md, stop and ask the user whether the plan has changed.** A bug fix or a
+change of plan the user has agreed goes on `start --work <name> "task"` and is merged with `land`.
+
+## 2. Start: the branch comes first
+
+```
+python3 tools/step.py start <STEP> "<the task, smaller than the step>"
+```
+
+This makes the step's branch from the trunk, writes the task under "In progress" with its start time (date, time, zone),
+commits and pushes the branch. Nothing is committed straight onto the trunk; `git-guard` refuses it.
+
+Read the step's "done when" now and decide how it will be measured. If it cannot be measured or seen in the opened app,
+say so before building.
+
+### The shape comes first (KWB-1)
+
+Before any code, name every concept the step touches and find its row in `design/shape.json` (ONE with its frozen id, or
+MANY with its count, generator, selectors and declared constants).
+
+- **A concept the step introduces gets its row first, as the step's first commit** (`step.py save "shape: <concept> row"`
+  with only `design/shape.json` in it), before any code that uses it. `shape-law` refuses an instance type with no row.
+- Build for the shape: one loop over every instance, or the generator. Test the behaviour once, on the template (`test-the-template-once`). An instance a bug was seen in goes on a `seen in:`
+  line; a rule that picks one is a selector listed in the row; a fixed one is a named constant there. Anything else is
+  refused with "example, rule, or constant?".
+- **Every subagent brief quotes the manifest row of every concept it touches, word for word**, and names the shape and
+  the generator, never an instance (`brief-guard` refuses "drive slot 2"; "seen in: slot 2, build for all slots" passes).
+- `npx --no-install @thedecipherist/claude-packs shape scan` lists what the repo already names by instance; a step that touches such a file fixes its
+  lines or leaves them as they were, never adds to them.
+
+## 3. While working: save often
+
+```
+python3 tools/step.py save "<what state it is in>" [--paths <new files>]
+```
+
+Commits everything changed and pushes the branch. Run it after every unit of work, before any risky command, and
+**always before a session ends**, saying if the work was interrupted and what is half done. It lists new files it was not
+told about; name them or ignore them, never leave them floating.
+
+- A bug goes into `bugs.md` the moment it is found, before it is fixed.
+- A red tripwire gate stops all other work.
+- Steps that run side by side each have their own branch. Switch with `start`; it refuses to switch over uncommitted work.
+
+## 4. Is it done?
+
+```
+python3 tools/step.py check
+```
+
+It runs the mechanical checks and prints the repo's "Runs through every step" list to walk by eye. Run the project's
+plants script (the `plants` command) before ticking: every planted fault red. Then the step's own "done when":
+
+- **Measured or seen in the opened app.** Rebuilt, opened, pressed. Not "wired", not "compiles", not "the test I just
+  wrote passes".
+- A gate that passed first time is suspect. Plant the fault it exists to catch and watch it fail.
+- Say which artefact was checked: the standalone, a probe, a picture the app rendered itself.
+
+If any part is not met, the step is not done. Say which part, `save`, and keep working or ask. The branch stays open;
+that is what it is for.
+
+## 5. Finish: merge into the trunk
+
+```
+python3 tools/step.py finish <STEP> --proof "<what was measured, with numbers>" [--paths <new files>]
+```
+
+On the step's branch. It brings the trunk into the branch first, ticks and dates the step, moves its In-progress row to
+the log with the finish time and what the step took, updates "Where we are" and the count, commits, merges into the trunk
+with a merge commit, writes that commit's short hash into the log line in a second commit, and pushes the trunk and the
+branch.
+
+It refuses an empty proof, a step that is not the current one (side-by-side steps take `--out-of-order`), and unnamed new
+files. If a merge conflicts it stops with both sides intact: resolve by hand, never by throwing a side away, and ask the user
+if it is not obvious which line is right. If it prints NOT PUSHED, push with the command it shows. A step is not finished
+until the trunk is pushed.
+
+## 6. Tell the user
+
+Conclusion first, in plain language: the step, what proved it, the new count, the next step. Show the changed `build.md`.
+Never claim a step works that has not been built, opened and measured.
+
+## Never
+
+- Delete a branch, here or on GitHub. Rebase, amend, squash or force-push. `git add -A`.
+- `checkout`, `restore`, `stash` or `reset --hard` over uncommitted work. `save` first.
+- Commit straight onto the trunk. Pass `--no-verify`.
+- Delete a step from build.md: strike it through with the reason and the date. A reopened step keeps its line, marked
+  REOPENED.
+- Tick from memory of an earlier session. Measure again.
+- Soften a red test in a commit message.

package/packs/synth-creator/skills/build-through-the-queue/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: build-through-the-queue
+description: Use when about to compile, run ctest, or run a program from a build folder, or when build-guard refused a command.
+---
+
+# Build through the queue (one job: no build takes the whole machine)
+
+<constraints>
+Always do:
+1. Use the project's wrapper first: the `build` and `test` commands in `.claude/layout.json`. Otherwise run `buildq <command>` (`~/.claude/bin/buildq`).
+2. The queue runs two at a time and waits for a slot by itself; `buildq --status` shows the slots. Run it in the foreground, or as a background job.
+3. As an agent, build only the targets the change needs (`--target X --target Y`) and run only its tests (`-R 'pattern'`, at most 30).
+4. An agent started as `KIND: light` does not build or run tests: do the light part, and say in the report what needs building.
+
+Never do:
+- Run `cmake --build`, `ctest`, `make`, `ninja`, `xcodebuild`, or a program from a build folder straight from the shell.
+- Wrap a build in a wait loop.
+- Build every target from an agent: the whole build runs once, before landing.
+</constraints>

package/packs/synth-creator/tools/freeze.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// Freeze the files that define "fixed" before changing the code that must satisfy them.
+//   node .claude/tools/freeze.mjs on "<reason>" <file-or-glob>...
+//   node .claude/tools/freeze.mjs off
+//   node .claude/tools/freeze.mjs status
+// The frozen-files hook refuses edits to anything on the list until it is turned off.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+const STATE = join(ROOT, '.claude', 'state', 'frozen.json');
+const [cmd, reason, ...files] = process.argv.slice(2);
+
+const USAGE = 'usage: freeze.mjs on "<reason>" <files...> | off | status';
+
+function on() {
+  if (!reason || files.length === 0) {
+    console.error('usage: freeze.mjs on "<reason>" <file-or-glob>...');
+    return 2;
+  }
+  mkdirSync(join(ROOT, '.claude', 'state'), { recursive: true });
+  const prev = existsSync(STATE) ? JSON.parse(readFileSync(STATE, 'utf8')).files ?? [] : [];
+  const all = [...new Set([...prev, ...files])];
+  writeFileSync(STATE, `${JSON.stringify({ reason, files: all, since: new Date().toISOString() }, null, 2)}\n`);
+  console.log(`frozen (${reason}):\n${all.map((f) => `  ${f}`).join('\n')}`);
+  return 0;
+}
+
+const COMMANDS = {
+  on,
+  off: () => (rmSync(STATE, { force: true }), console.log('nothing frozen'), 0),
+  status: () => (console.log(existsSync(STATE) ? readFileSync(STATE, 'utf8') : 'nothing frozen'), 0),
+};
+
+const run = Object.hasOwn(COMMANDS, cmd) ? COMMANDS[cmd] : () => (console.error(USAGE), 2);
+process.exit(run());

package/packs/tui/checks/tui-entry-restores-terminal.json

@@ -0,0 +1,27 @@
+{
+  "id": "tui-entry-restores-terminal",
+  "why": "Entering the alternate screen or raw mode without an exit handler that restores them strands the user in a broken terminal after a crash. process.once('exit', restore), registered before the first render.",
+  "rule": ".claude/rules/tui-resize-and-screen.md",
+  "concepts": [
+    "tui",
+    "tui-entry"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/test/**"
+  ],
+  "code": false,
+  "mode": "needs",
+  "pattern": "\\?1049h|setRawMode\\s*\\(\\s*true\\s*\\)",
+  "needs": [
+    "\\?1049l|setRawMode\\s*\\(\\s*(?:false|wasRaw|prev\\w*|was\\w*)\\s*\\)",
+    "process\\.(?:once|on)\\s*\\(\\s*['\\\"](?:exit|SIGINT)['\\\"]"
+  ],
+  "bad": "process.stdout.write('\\x1B[?1049h\\x1B[?25l');\nconst { waitUntilExit } = render(<App />);",
+  "good": "process.stdout.write('\\x1B[?1049h\\x1B[?25l');\nconst restore = () => process.stdout.write('\\x1B[?25h\\x1B[?1049l');\nprocess.once('exit', restore);\nconst { waitUntilExit } = render(<App />);"
+}