@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/packs/reverse-engineering/skills/gather-sources/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: gather-sources
+description: Use when starting work on a machine, or before disassembling anything.
+---
+
+# Gather the sources in the right order (one job: read what exists before reading code)
+
+<constraints>
+Always do:
+1. Read the folder: text files, filenames, the shape of the dump set.
+2. Read the owner's manual (`pdf-to-md`) for what the machine calls things, and search the image for those names (`names-first`). This is the fastest step there is: do it before everything below.
+3. Read the maker's sysex document.
+4. Read the service manual, and check the scan is whole. Check for a real text layer first; where there is none, or a cell is in dispute, read the rendered page, not the OCR.
+5. Read other people's conversions as `[PUB]` leads.
+6. Read the disk OS's own strings.
+7. Check the tool table before writing a disassembler.
+8. Take ratios from a redrawn trace, never absolutes.
+
+Never do:
+- Start the disassembly before steps 1 to 4.
+</constraints>

package/packs/reverse-engineering/skills/menu-map/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: menu-map
+description: Use when mapping where each parameter is reached on the machine, when a control has no byte in the patch map, or before building effects or a panel from a decoded record.
+---
+
+# Map the menus (one job: every parameter joined to the page that reaches it, and every mismatch listed)
+
+A patch map says what byte N means. A menu map says how you reach byte N from the panel, and it names what you can edit that is no byte in a patch at all. On one machine the chorus and delay TYPE selectors sat outside the patch block, and that blocked the effects work for a day.
+
+<constraints>
+Always do:
+1. Write the tree from the manual's own section order, page by page, with the printed page number each page is cited from, one tree per algorithm or mode where the pages differ. This is the only part edited by hand: a script looks up everything else and regenerates the table.
+2. Tag each name by its source: `[FW]` in the firmware's display pools (`names-first`), `[MAN]` printed. Page membership and page order are usually `[MAN]` alone, and the map says so.
+3. Join the two with the manual's own display drawings: the page name on the top line, the parameter on the bottom. Find each half in the firmware's pools. That is the two-source check for the whole tree.
+4. Give every parameter its home: patch, multi or performance, global, or stored nowhere.
+5. Print both mismatch lists, because they are the point of the file:
+   - on a page but not in the patch map: multi and global parameters, and anything with no published index;
+   - in the patch map but no page reaches it: dead, reserved, live and set by presets only, or a page still to find. A parameter list describes the control surface, not the engine: an algorithm with no knob for something usually has it, fixed.
+6. Check whether every parameter that shapes the sound is in the dump. One that is not must be sent another way, and a rebuild that loads only the dump loses it.
+7. Write down what changes the map. Menus are dynamic: a page hidden while its effect is off still exists. Pages re-label themselves: one byte can carry two names, by mode, so list both.
+8. Keep corrections in the file, and end it with what is not established.
+
+Never do:
+- Conclude a parameter does not exist, or does nothing, because no page shows it.
+- Give one byte one name when a mode re-labels it.
+- Edit the generated table by hand.
+- Build effects or a panel before the first mismatch list is read.
+</constraints>

package/packs/reverse-engineering/skills/names-first/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: names-first
+description: Use when starting on a firmware image, an OS update or a sysex dump, before any disassembly, or when a table or a record has no name yet.
+---
+
+# Map the machine by its own names (one job: names found, tables located, before reading any code)
+
+A machine has to print what it calls things, so its names sit in the image as text. A name found is usually a table found, and a table usually leads to the record and the code. Not always: compiled-out debug strings have nothing pointing at them, far pointers and `push seg; push off` pairs need their own scan, and one string led to the wrong table. On one machine the descriptors found this way named every byte of the patch and carried the factory CC numbers, which matched the manual's chart 40 for 40.
+
+<constraints>
+Always do:
+1. Write the names file from the manual first, one name per line with its group: patch and preset names, arp patterns, delay and reverb programs, effect types, menus and pages, parameters, value lists, messages. Add the factory bank's names from any dump. Keep the manual's order: order is evidence. Fold curly apostrophes and trailing spaces, and count what joins. Check for a text layer, and render any table that is a picture: OCR dropped noteheads and shuffled a parameter table, and cost one repo two wrong conclusions.
+2. Run `node .claude/tools/names-sweep.mjs <image> --names names.txt`, with `--pair` for two EPROMs, `--base` for a known load address, and `--banked` when the ROM is larger than the CPU's address space. It searches each name as printed, squeezed and cut to a display column (`Decay Time` is `Decaytime`, `Filter Balance` is `FilterBalanc`), then tries the misses with vowels dropped (`BrickWll`, `ARP SWNG`). When nothing reads and entropy is high and flat, read what loads the image; if nothing does, record that the text is not in these files and stop.
+3. Read the wrapping it reports. Text is rarely encrypted but often wrapped: an interleaved pair, scrambled address lines, 7-bit packing and its bit order, nibbles, swapped or reversed words, one header per sysex message, three bytes per word, a header in each bank, a ZIP, a custom character set. Many names reading finds the unwrapping; one or two prove nothing, because chance does that. Names are not the last word: an unpacker that lost two bytes per file still read names while 63% of the image was wrong. Where an EPROM exists, compare the decoded update with it byte for byte. The header length reported is an alignment, so check it against the message format.
+4. Read each group as a map:
+   - stride between patch names: the record size and the name's place in it, when most gaps agree. Records can be variable, so find them by their marker over the whole image. ROM presets are often the internal record, smaller than the sysex one; compare value distributions to tie the two;
+   - order held: the parameter order, and the table index of every entry;
+   - stride between parameter names: a fixed-width table; look beside each name for its range, its control id, its CC. A field can change meaning partway down a table, so re-derive it per block;
+   - pointers: follow what reads them to the code that draws the page or handles the value.
+5. Read a pool whole. A display is built from name pools: page names for the top line, long and short parameter names for the bottom. A value list is a blob of N fields of W characters with no separators, and W is the column the LCD reserves. Split a pool on its terminator, never by stride: a name that fills its field has no terminator.
+6. Complete the manual from the firmware. A manual cuts a long list with `..`; the firmware holds all of it, in the machine's own order. Keep that order, however odd, and move the row's tag to `[FW]`.
+7. Use the count. A list's item count says which parameter owns it: two menus of 14 and 18 items were swapped until the counts were read. A list of N names beside a table of N numbers pairs one for one, and that pairing gives the unit: 22 clock names against a 22-word table fixed a unit that had been wrong by a factor of two.
+8. Search a sysex dump the same way. A factory patch's name gives the record's start and length, and the packing that makes it read.
+9. Scan for what the manual does not list: the entries after the last hit, compiled-out debug strings, format strings. A compiler emits string literals in source order, so a block of them is a struct's order.
+10. Check an abrupt name: look at the byte after it. A table may be dictionary-compressed, a high byte standing for another string.
+11. Prove a table across images: the same blob byte-identical in other OS versions and sibling machines.
+12. Write each located table into the research record with its address and which space it is in, its stride, count and the names that proved it, then map the menus (`menu-map`).
+13. Before counting a named byte as done, find what reads it. A name in a patch map is not a consumer: one named byte nothing read was wrong on 48% of a bank.
+
+Never do:
+- Start disassembling while the names search has not run.
+- Call an image empty of text because a plain `strings` found nothing. Say which wrappings were tried.
+- Assign names by the order of the manual's prose. It put five right names in the wrong five slots and invented a sixth. Use the address table, the range and the item count.
+- Trust a table built by walking the manual's names: it inherits the manual's errors and has no row for a slot the manual never lists. Read the machine's own slot table too.
+- Name a reserved byte from its position. Unnamed stays unnamed.
+- Look for storage offsets in a panel or menu table. It holds names, control ids and range pointers, and two sessions went into proving that. Offsets come from the code that reads the record.
+- Take a name as a law. It says what a value is called, never its unit or curve.
+- Trust a printed range over a firmware clamp. The corpus decides, and a range too small is data loss: a manual printed 0..19, the firmware clamps at 21, and real patches use 20 and 21.
+</constraints>
+
+Where the ROM and the manual disagree, the machine's own ROM says what it has (a sibling's ROM does not), and the disagreement is a finding: a manual's "Undefined" rows were named by the ROM's display strings, and a printed MIDI chart had two waveforms transposed.

package/packs/reverse-engineering/skills/re-deliverables/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: re-deliverables
+description: Use when closing a machine, or when asked what a finished reverse-engineering leaves behind.
+---
+
+# Leave the record (one job: the next reader can check every claim)
+
+<constraints>
+Always do:
+1. The research record, with withdrawn findings in place.
+2. CSV maps of every parameter, with provenance.
+3. The names file, and every table it located: address, stride, count, and the names that proved it. The menu map, with both mismatch lists.
+4. The laws reference: each law, its source, and where the code is.
+5. The debt ledger of `[EAR]` values, with leads.
+6. Tests, including a byte-exact round trip of every patch.
+7. The non-negotiables list.
+8. State which tags cannot exist here, and which check is lost with no corpus.
+
+Never do:
+- Leave a verdict with no number behind it.
+</constraints>

package/packs/reverse-engineering/skills/tripwire-the-law/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: tripwire-the-law
+description: Use before changing a law, a coefficient or a formula that has a source.
+---
+
+# Tripwire the law (one job: the source and the engine cannot silently part)
+
+<constraints>
+Always do:
+1. Write the source's sum longhand, as a separate function, with its citation.
+2. Assert the engine against it, off the easy point.
+3. Change the engine.
+4. Re-anchor before re-scaling.
+5. Take expected values from the printed source. A worked example is the first test.
+
+Never do:
+- Fit by ear when a term is missing. A 0.35 fudge once hid a whole term.
+- Compare a function with itself.
+</constraints>

package/packs/reverse-engineering/tools/lib/unwrap.mjs

@@ -0,0 +1,115 @@
+// Every way a firmware image or a dump has been seen to wrap its text. Text is rarely encrypted, but it is often wrapped, and a name a manual prints is
+// the test of an unwrapping: if the name reads, the unwrapping is right. A new wrapping is one row.
+//   wrappings() -> [{ name, open(buffer) -> buffer }]     interleave(a, b) -> one image from an even and an odd EPROM
+//   entropyOf(buffer) -> bits per byte
+//   shiftedHits(buffer, text) -> [{ at, shift }]           a custom character set: the letters keep their distances, whatever the code of 'A'
+
+const eachByte = (b, fn) => Buffer.from(b.map(fn));
+
+function everyOther(b, from) {
+  const out = Buffer.alloc(Math.ceil((b.length - from) / 2));
+  for (let i = from, o = 0; i < b.length; i += 2, o += 1) out[o] = b[i];
+  return out;
+}
+
+// Each word of `width` bytes reversed, the first whole word starting at `phase`.
+function reversedWords(b, width, phase) {
+  const out = Buffer.from(b);
+  for (let i = phase; i + width <= b.length; i += width) for (let k = 0; k < width; k += 1) out[i + k] = b[i + width - 1 - k];
+  return out;
+}
+
+// MIDI's 8-to-7 packing: seven data bytes and one byte of their high bits, that byte first or last, and its bit k for data byte k or for data byte 6-k.
+// Roland's updates are high bits first with bit k for byte k; the wrong order reads as noise, so both are tried.
+function unpacked7(b, phase, highFirst, bitK) {
+  const out = [];
+  const take = (high, from, count) => { for (let k = 0; k < count; k += 1) out.push((b[from + k] & 0x7f) | (((high >> (bitK ? k : 6 - k)) & 1) << 7)); };
+  let i = phase;
+  for (; i + 8 <= b.length; i += 8) take(b[highFirst ? i : i + 7], highFirst ? i + 1 : i, 7);
+  if (highFirst && b.length - i >= 2) take(b[i], i + 1, b.length - i - 1); // a message's last group is short, and dropping it shifts everything after
+  return Buffer.from(out);
+}
+
+// One byte sent as two: the nibble in the low four bits of each.
+function joinedNibbles(b, phase, highFirst) {
+  const out = Buffer.alloc(Math.floor((b.length - phase) / 2));
+  for (let i = phase, o = 0; i + 1 < b.length; i += 2, o += 1) {
+    const [first, second] = [b[i] & 15, b[i + 1] & 15];
+    out[o] = highFirst ? (first << 4) | second : (second << 4) | first;
+  }
+  return out;
+}
+
+// A 16-bit word as three bytes, marker first: 0x40 | top four bits, then two groups of six. Not 7-in-8, and a CPU guess fails until it is undone.
+function threeByteWords(b, bigEndian) {
+  const out = [];
+  for (let i = 0; i + 3 <= b.length; i += 3) {
+    const word = ((b[i] & 0x0f) << 12) | ((b[i + 1] & 0x3f) << 6) | (b[i + 2] & 0x3f);
+    out.push(...(bigEndian ? [word >> 8, word & 255] : [word & 255, word >> 8]));
+  }
+  return Buffer.from(out);
+}
+
+// An OS update is many sysex messages, in a MIDI file or not, each with its own header, so packed groups restart at every message. Data bytes are below 0x80, so F0 and F7 end them.
+function sysexMessages(b) {
+  const out = [];
+  for (let start = b.indexOf(0xf0); start !== -1; start = b.indexOf(0xf0, start + 1)) {
+    const end = b.indexOf(0xf7, start);
+    if (end === -1) break;
+    out.push(b.subarray(start + 1, end));
+    start = end;
+  }
+  return out;
+}
+
+const perMessage = (b, header, open) => Buffer.concat(sysexMessages(b).map((m) => open(m.subarray(header))));
+const LONGEST_HEADER = 20;
+const SEVEN_BIT = [true, false].flatMap((first) => [true, false].map((bitK) => ({ first, bitK, name: `7-bit packed, high bits ${first ? 'first' : 'last'}, bit ${bitK ? 'k' : '6-k'}` })));
+const PACKINGS = [
+  ...SEVEN_BIT.map((p) => ({ name: p.name, open: (m) => unpacked7(m, 0, p.first, p.bitK) })),
+  ...SEVEN_BIT.filter((p) => p.first).map((p) => ({ name: `${p.name}, checksum last`, open: (m) => unpacked7(m.subarray(0, -1), 0, p.first, p.bitK) })),
+  { name: 'nibbles, high first', open: (m) => joinedNibbles(m, 0, true) },
+  { name: 'nibbles, low first', open: (m) => joinedNibbles(m, 0, false) },
+  { name: 'three bytes per word, high byte first', open: (m) => threeByteWords(m, true) },
+  { name: 'three bytes per word, low byte first', open: (m) => threeByteWords(m, false) },
+];
+
+const phases = (n) => Array.from({ length: n }, (_, i) => i);
+
+export function wrappings() {
+  return [
+    { name: 'as stored', open: (b) => b },
+    { name: 'high bit set', open: (b) => eachByte(b, (x) => x & 0x7f) },
+    { name: 'even bytes only', open: (b) => everyOther(b, 0) },
+    { name: 'odd bytes only', open: (b) => everyOther(b, 1) },
+    ...phases(2).map((p) => ({ name: `16-bit words swapped, from ${p}`, open: (b) => reversedWords(b, 2, p) })),
+    ...phases(3).map((p) => ({ name: `24-bit words reversed, from ${p}`, open: (b) => reversedWords(b, 3, p) })),
+    ...phases(4).map((p) => ({ name: `32-bit words reversed, from ${p}`, open: (b) => reversedWords(b, 4, p) })),
+    ...phases(8).flatMap((p) => SEVEN_BIT.map((s) => ({ name: `${s.name}, from ${p}`, open: (b) => unpacked7(b, p, s.first, s.bitK) }))),
+    ...phases(2).flatMap((p) => [true, false].map((first) => ({ name: `nibbles, ${first ? 'high' : 'low'} first, from ${p}`, open: (b) => joinedNibbles(b, p, first) }))),
+    ...phases(LONGEST_HEADER + 1).flatMap((h) => PACKINGS.map((p) => ({ name: `sysex messages, ${h}-byte header, ${p.name}`, open: (b) => perMessage(b, h, p.open) }))),
+  ];
+}
+
+export function interleave(even, odd) {
+  const out = Buffer.alloc(even.length + odd.length);
+  for (let i = 0; i < even.length; i += 1) out[i * 2] = even[i];
+  for (let i = 0; i < odd.length; i += 1) out[i * 2 + 1] = odd[i];
+  return out;
+}
+
+const distances = (b) => { const out = Buffer.alloc(Math.max(0, b.length - 1)); for (let i = 1; i < b.length; i += 1) out[i - 1] = (b[i] - b[i - 1]) & 255; return out; };
+
+export function shiftedHits(buffer, text) {
+  const hay = distances(buffer);
+  const needle = distances(Buffer.from(text, 'latin1'));
+  const hits = [];
+  for (let at = hay.indexOf(needle); at !== -1 && hits.length < 64; at = hay.indexOf(needle, at + 1)) hits.push({ at, shift: (buffer[at] - text.charCodeAt(0)) & 255 });
+  return hits;
+}
+
+export function entropyOf(b) {
+  const counts = new Array(256).fill(0);
+  for (const x of b) counts[x] += 1;
+  return counts.filter(Boolean).reduce((bits, n) => bits - (n / b.length) * Math.log2(n / b.length), 0);
+}

package/packs/reverse-engineering/tools/names-sweep.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+// The fastest way into a firmware image or a dump: search it for the names the manual prints. Patch names, arp patterns, delay and reverb programs, menus,
+// parameters. One name gives a table, the table's stride gives a record size, its order gives the parameter order, and what points at it leads to the code.
+//   node names-sweep.mjs <image> [<image>...] --names <file> [--pair] [--base 0x8000,...] [--banked] [--min 4] [--json]
+// The names file has one name per line, `group<TAB>name` to keep kinds apart (patch, arp, reverb, menu, parameter), `#` for a comment.
+// --pair reads two images as one interleaved EPROM pair. Every wrapping in lib/unwrap.mjs is tried, and the one that reads the most names wins.
+// Names reading prove the unwrapping. Exit 1 when too few read under any wrapping, and the report says what was searched.
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { entropyOf, interleave, shiftedHits, wrappings } from './lib/unwrap.mjs';
+
+const MAX_HITS = 2048; // a common word is everywhere, and the cap must not cut off the one hit in the table
+const SPAN_PER_NAME = 640; // bytes a name may take: a preset record's stride can be 512
+const MAX_SPAN = 32768;
+const FLAT = 7.5; // bits per byte: past this no text is showing and no structure either
+const PROOF = 3; // names: one or two can read by chance in a large image, so fewer proves nothing
+const POINTERS = [
+  { name: 'u16 big-endian', width: 2, write: 'writeUInt16BE', top: 0xffff },
+  { name: 'u16 little-endian', width: 2, write: 'writeUInt16LE', top: 0xffff },
+  { name: 'u32 big-endian', width: 4, write: 'writeUInt32BE', top: 0xffffffff },
+  { name: 'u32 little-endian', width: 4, write: 'writeUInt32LE', top: 0xffffffff },
+];
+
+export function readNames(text, min = 4) {
+  return text.split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#')).map((l) => {
+    const [group, name] = l.includes('\t') ? l.split('\t').map((s) => s.trim()) : ['name', l];
+    return { group, name };
+  }).filter((n) => n.name.length >= min);
+}
+
+function hitsIn(view, text) {
+  const hits = [];
+  for (let at = view.indexOf(text); at !== -1 && hits.length < MAX_HITS; at = view.indexOf(text, at + 1)) hits.push(at);
+  return hits;
+}
+
+// A display does not print what a manual prints: it changes case, drops spaces and cuts a name to its column ("Decay Time" is `Decaytime`, "Filter Balance" `FilterBalanc`).
+// So a name is searched as printed, squeezed, and cut to each column width. A cut under eight characters would match by chance.
+const COLUMNS = [16, 15, 12, 10, 8];
+export function displayForms(name) {
+  const squeezed = name.replace(/\s+/g, '');
+  const cuts = COLUMNS.filter((w) => w < squeezed.length).map((w) => squeezed.slice(0, w));
+  return [...new Set([name, squeezed, ...cuts].map((f) => f.toLowerCase()))];
+}
+
+// Firmware also drops vowels and stops early (`BrickWll`, `ARP SWNG`, `MinWool`), so a name that did not read is tried loosely: a word's first three letters stand, vowels may go, and it may end early.
+const VOWEL = /[aeiou]/;
+const letter = (c, kept) => { const safe = c.replace(/[^a-z0-9]/g, '\\$&'); return kept && VOWEL.test(c) ? `${safe}?` : safe; };
+function wordPattern(word) {
+  const letters = [...word];
+  const tail = letters.slice(3).reverse().reduce((inner, c) => `(?:${letter(c, true)}${inner})?`, '');
+  return letters.slice(0, 3).map((c, i) => letter(c, i > 0)).join('') + tail;
+}
+export function abbreviationOf(name) {
+  const words = name.toLowerCase().split(/\s+/).filter(Boolean);
+  return new RegExp(`(?<![a-z])${words.map(wordPattern).join('[ .]?')}(?![a-z])`, 'g');
+}
+
+function abbreviated(view, names) {
+  const text = view.toString('latin1').toLowerCase();
+  return names.filter((n) => n.name.length >= 5).map((n) => {
+    const hits = [...text.matchAll(abbreviationOf(n.name))].filter((m) => m[0].length >= Math.max(5, n.name.length / 2)).slice(0, MAX_HITS);
+    return { ...n, hits: hits.map((m) => m.index), abbreviated: hits[0]?.[0] };
+  }).filter((n) => n.hits.length);
+}
+
+const folded = (view) => Buffer.from(view.toString('latin1').toLowerCase(), 'latin1');
+function found(names, view) {
+  const low = folded(view);
+  const hitsOf = (n) => { for (const form of displayForms(n.name)) { const hits = hitsIn(low, Buffer.from(form, 'latin1')); if (hits.length) return { hits, form }; } return null; };
+  return names.map((n) => ({ ...n, ...hitsOf(n) })).filter((n) => n.hits?.length);
+}
+
+// A custom character set: only names long enough for the letters' distances to mean anything, in each case the display might use.
+function foundShifted(names, view) {
+  const shifted = names.filter((n) => n.name.length >= 6).map((n) => {
+    const all = [n.name, n.name.toUpperCase(), n.name.toLowerCase()].flatMap((form) => shiftedHits(view, form));
+    return { ...n, hits: all.map((h) => h.at), shift: all[0]?.shift };
+  }).filter((n) => n.hits.length);
+  const counts = new Map();
+  for (const n of shifted) counts.set(n.shift, (counts.get(n.shift) ?? 0) + 1);
+  const best = [...counts].sort((a, b) => b[1] - a[1])[0];
+  return best ? { shift: best[0], names: shifted.filter((n) => n.shift === best[0]) } : { names: [] };
+}
+
+function mostCommonGap(offsets) {
+  const counts = new Map();
+  for (let i = 1; i < offsets.length; i += 1) { const gap = offsets[i] - offsets[i - 1]; counts.set(gap, (counts.get(gap) ?? 0) + 1); }
+  const [gap, count] = [...counts].sort((a, b) => b[1] - a[1])[0] ?? [0, 0];
+  return count >= 2 && count >= (offsets.length - 1) / 5 ? { gap, count, of: offsets.length - 1 } : null; // a gap a few pairs share is no stride, and reading one invents a table
+}
+
+// How many neighbours in the names file's order also sit in that order in the image.
+function orderHeld(hits) {
+  let held = 0;
+  for (let i = 1; i < hits.length; i += 1) if (hits[i].hits[0] > hits[i - 1].hits[0]) held += 1;
+  return { held, of: Math.max(0, hits.length - 1) };
+}
+
+// Where the most different names sit closest: the table itself. A common word also turns up in presets and messages, so the first hit is not the table.
+function densest(hits, span) {
+  const all = hits.flatMap((n) => n.hits.map((at) => ({ at, name: n.name }))).sort((a, b) => a.at - b.at);
+  const held = new Map();
+  const drop = (name) => { if (held.get(name) > 1) held.set(name, held.get(name) - 1); else held.delete(name); };
+  let best = null;
+  let from = 0;
+  for (let to = 0; to < all.length; to += 1) {
+    held.set(all[to].name, (held.get(all[to].name) ?? 0) + 1);
+    while (all[to].at - all[from].at > span || held.get(all[from].name) > 1) { drop(all[from].name); from += 1; } // a stray earlier copy of a name is no part of the table
+    const width = all[to].at - all[from].at;
+    if (held.size > (best?.names ?? 1) || (held.size === best?.names && width < best.to - best.from)) best = { names: held.size, from: all[from].at, to: all[to].at, first: from, last: to };
+  }
+  return best && withNeighbours(all, best);
+}
+
+// The tightest window drops a first entry whose name comes again later in the table, so it takes back any hit as close as the table's own entries. A stray copy is further off.
+function withNeighbours(all, { names, first, last }) {
+  const gaps = all.slice(first + 1, last + 1).map((h, i) => h.at - all[first + i].at).sort((a, b) => a - b);
+  const reach = 2 * (gaps[Math.floor(gaps.length / 2)] ?? 0);
+  let [from, to] = [first, last];
+  while (from > 0 && all[from].at - all[from - 1].at <= reach) from -= 1;
+  while (to < all.length - 1 && all[to + 1].at - all[to].at <= reach) to += 1;
+  return { names, from: all[from].at, to: all[to].at };
+}
+
+// Every place an address of one of the hits is stored, in this pointer format.
+function seatsOf(view, offsets, base, kind) {
+  const encoded = (o) => { const b = Buffer.alloc(kind.width); b[kind.write](o + base); return b; };
+  return offsets.filter((o) => o + base >= 0 && o + base <= kind.top).flatMap((o) => hitsIn(view, encoded(o))).sort((a, b) => a - b);
+}
+
+// Where addresses of the hits sit close together: that run is the table the code indexes.
+function pointerTable(view, offsets, bases) {
+  let best = null;
+  for (const base of bases) {
+    for (const kind of POINTERS.filter((k) => base >= 0 || k.width === 2)) { // a bank is reached through a 16-bit address
+      let run = [];
+      for (const seat of seatsOf(view, offsets, base, kind)) {
+        run = run.length && seat - run[run.length - 1] <= kind.width * 4 ? [...run, seat] : [seat];
+        if (run.length >= 4 && run.length > (best?.entries ?? 0)) best = { at: run[0], entries: run.length, kind: kind.name, base };
+      }
+    }
+  }
+  return best;
+}
+
+// Printable runs after the last hit: the entries of the table the manual does not list.
+function nextRuns(view, from, count = 3) {
+  const text = view.subarray(from, from + 512).toString('latin1');
+  return (text.match(/[\x20-\x7e]{4,}/g) ?? []).slice(1, count + 1);
+}
+
+// Hits in one unbroken printable run are a pool or a fixed-width blob with no separators: read the run whole, because a name that fills its field has no terminator.
+function poolOf(view, offsets) {
+  const printable = (x) => x >= 0x20 && x < 0x7f;
+  const runs = new Map();
+  for (const at of offsets) {
+    let from = at;
+    let to = at;
+    while (from > 0 && printable(view[from - 1])) from -= 1;
+    while (to < view.length && printable(view[to])) to += 1;
+    runs.set(from, { from, to, hits: (runs.get(from)?.hits ?? 0) + 1 });
+  }
+  const best = [...runs.values()].sort((a, b) => b.hits - a.hits)[0];
+  return best?.hits >= 2 ? best : null;
+}
+
+function groupsOf(hits, view, bases, wanted) {
+  return [...new Set(wanted.map((n) => n.group))].map((group) => {
+    const mine = hits.filter((n) => n.group === group);
+    const offsets = [...new Set(mine.flatMap((n) => n.hits))].sort((a, b) => a - b);
+    const last = offsets[offsets.length - 1];
+    const dense = densest(mine, Math.min(MAX_SPAN, mine.length * SPAN_PER_NAME));
+    const inTable = dense ? mine.map((n) => ({ ...n, hits: n.hits.filter((at) => at >= dense.from && at <= dense.to) })).filter((n) => n.hits.length) : mine;
+    return {
+      group, found: mine.length, of: wanted.filter((n) => n.group === group).length, first: offsets[0], last, dense,
+      stride: mostCommonGap(offsets), order: orderHeld(inTable), pointers: offsets.length >= 4 ? pointerTable(view, offsets, bases) : null,
+      next: offsets.length ? nextRuns(view, last) : [], pool: poolOf(view, offsets),
+    };
+  });
+}
+
+export function sweep(image, names, { bases = [0] } = {}) {
+  const tried = wrappings().map((w) => { const view = w.open(image); return { name: w.name, view, hits: found(names, view) }; });
+  const relative = foundShifted(names, image);
+  tried.push({ name: `custom character set, shift ${relative.shift ?? '-'}`, view: image, hits: relative.names });
+  tried.sort((a, b) => b.hits.length - a.hits.length);
+  const best = tried[0];
+  const read = new Set(best.hits.map((n) => n.name));
+  const shortened = best.hits.length >= PROOF ? abbreviated(best.view, names.filter((n) => !read.has(n.name))) : [];
+  best.hits.push(...shortened);
+  const seen = new Set(best.hits.map((n) => n.name));
+  return {
+    names: names.length, wrapping: best.hits.length ? best.name : null, reads: best.hits.length, entropy: entropyOf(image), shortened: shortened.map((n) => [n.name, n.abbreviated]),
+    proven: best.hits.length >= Math.min(PROOF, names.length),
+    tried: tried.map((t) => ({ name: t.name, reads: t.hits.length })),
+    groups: best.hits.length ? groupsOf(best.hits, best.view, bases, names) : [],
+    missing: names.filter((n) => !seen.has(n.name)).map((n) => n.name),
+  };
+}
+
+const hex = (n) => `0x${n.toString(16).toUpperCase()}`;
+function groupLine(g) {
+  if (!g.found) return `  ${g.group}: 0 of ${g.of}`;
+  const parts = [`  ${g.group}: ${g.found} of ${g.of}, ${hex(g.first)}..${hex(g.last)}`];
+  if (g.dense) parts.push(`densest ${g.dense.names} names at ${hex(g.dense.from)}..${hex(g.dense.to)}`);
+  if (g.stride) parts.push(`stride ${g.stride.gap} (${g.stride.count} of ${g.stride.of} gaps)`);
+  if (g.order.of) parts.push(`the manual's order holds ${g.order.held} of ${g.order.of}`);
+  if (g.pointers) parts.push(`pointers at ${hex(g.pointers.at)} (${g.pointers.entries}, ${g.pointers.kind}, base ${g.pointers.base < 0 ? '-' : ''}${hex(Math.abs(g.pointers.base))})`);
+  if (g.pool) parts.push(`${g.pool.hits} in one run ${hex(g.pool.from)}..${hex(g.pool.to)} (${g.pool.to - g.pool.from} bytes, read it whole)`);
+  if (g.next.length) parts.push(`then ${g.next.map((s) => JSON.stringify(s)).join(' ')}`);
+  return parts.join('; ');
+}
+
+function nothingRead(label, r) {
+  const searched = r.tried.map((t) => t.name).join(', ');
+  const said = r.reads ? `only ${r.reads} of ${r.names} names read, which chance can do, under` : `none of ${r.names} names reads under`;
+  const flat = r.entropy >= FLAT ? ' It looks compressed or encrypted: read what loads it, and if nothing does, record that the text is not in these files and stop.' : '';
+  return `${label}: ${said} any of ${r.tried.length} wrappings. Searched: ${searched}.\n` +
+    `The image is still wrapped some other way, or the names file is wrong. This says nothing about what the machine holds. Entropy ${r.entropy.toFixed(2)} bits per byte.${flat}`;
+}
+
+export function report(label, r) {
+  if (!r.proven) return nothingRead(label, r);
+  const others = r.tried.filter((t) => t.reads && t.name !== r.wrapping).slice(0, 4).map((t) => `${t.name} ${t.reads}`).join(', ');
+  const more = r.missing.length > 8 ? `, and ${r.missing.length - 8} more` : '';
+  return [
+    `${label}: ${r.reads} of ${r.names} names read ${r.wrapping} (${r.tried.length} wrappings tried${others ? `; also ${others}` : ''})`,
+    ...r.groups.map(groupLine),
+    ...(r.shortened.length ? [`  abbreviated: ${r.shortened.slice(0, 8).map(([name, as]) => `${name} as "${as}"`).join(', ')}`] : []),
+    r.missing.length ? `  not found: ${r.missing.slice(0, 8).join(', ')}${more}` : '  every name found',
+  ].join('\n');
+}
+
+// A CPU sees a bank of a larger ROM through a window, so an address is the file offset less the bank plus the window: every plausible pairing, as a base.
+const BANK_STEP = 0x4000;
+const WINDOWS = [0x0000, 0x4000, 0x8000, 0xc000];
+function bankedBases(size) {
+  const bases = new Set([0]);
+  for (let bank = 0; bank < size; bank += BANK_STEP) for (const window of WINDOWS) bases.add(window - bank);
+  return [...bases];
+}
+
+function imagesOf(files, pair) {
+  if (!pair) return files.map((f) => [basename(f), readFileSync(f)]);
+  return [[`${basename(files[0])}+${basename(files[1])}`, interleave(readFileSync(files[0]), readFileSync(files[1]))]];
+}
+
+function main(argv) {
+  const value = (flag) => { const i = argv.indexOf(flag); return i === -1 ? undefined : argv[i + 1]; };
+  const files = argv.filter((a, i) => !a.startsWith('--') && !['--names', '--base', '--min'].includes(argv[i - 1]));
+  if (!files.length || !value('--names')) {
+    console.error('usage: names-sweep.mjs <image>... --names <file> [--pair] [--base 0x8000,...] [--banked] [--min 4] [--json]');
+    return 2;
+  }
+  const names = readNames(readFileSync(value('--names'), 'utf8'), Number(value('--min') ?? 4));
+  const given = (value('--base') ?? '0').split(',').map((b) => Number.parseInt(b));
+  const basesFor = (image) => (argv.includes('--banked') ? bankedBases(image.length) : given);
+  const results = imagesOf(files, argv.includes('--pair')).map(([label, image]) => [label, sweep(image, names, { bases: basesFor(image) })]);
+  console.log(argv.includes('--json') ? JSON.stringify(Object.fromEntries(results), null, 2) : results.map(([label, r]) => report(label, r)).join('\n\n'));
+  return results.some(([, r]) => r.proven) ? 0 : 1;
+}
+
+if (process.argv[1] && import.meta.url.endsWith(basename(process.argv[1]))) process.exit(main(process.argv.slice(2)));

package/packs/shell/checks/sh-mktemp.json

@@ -0,0 +1,18 @@
+{
+  "id": "sh-mktemp",
+  "why": "A fixed path in /tmp collides with another run, and another user can plant it.",
+  "rule": ".claude/rules/shell-strict-and-quoted.md",
+  "concepts": [
+    "shell"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**"
+  ],
+  "pattern": ">>?\\s*\\\"?/tmp/\\w",
+  "flags": "m",
+  "bad": "echo x > /tmp/out.txt",
+  "good": "out=$(mktemp)\necho x > \"$out\""
+}

package/packs/shell/checks/sh-no-backticks.json

@@ -0,0 +1,18 @@
+{
+  "id": "sh-no-backticks",
+  "why": "Backticks do not nest and hide in quoted text. $(...) does the same thing, and reads.",
+  "rule": ".claude/rules/shell-strict-and-quoted.md",
+  "concepts": [
+    "shell"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**"
+  ],
+  "pattern": "^[^#'\\n]*`[^`\\n]+`",
+  "flags": "m",
+  "bad": "now=`date`",
+  "good": "now=$(date)"
+}

package/packs/shell/checks/sh-no-eval.json

@@ -0,0 +1,18 @@
+{
+  "id": "sh-no-eval",
+  "why": "eval runs whatever a variable holds, with the script's rights.",
+  "rule": ".claude/rules/shell-strict-and-quoted.md",
+  "concepts": [
+    "shell"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**"
+  ],
+  "pattern": "^[^#\\n]*(?:^|[;&|\\s])eval\\s",
+  "flags": "m",
+  "bad": "eval \"$cmd\"",
+  "good": "\"$@\""
+}

package/packs/shell/checks/sh-no-parse-ls.json

@@ -0,0 +1,18 @@
+{
+  "id": "sh-no-parse-ls",
+  "why": "ls output breaks on spaces and newlines. A glob does not.",
+  "rule": ".claude/rules/shell-strict-and-quoted.md",
+  "concepts": [
+    "shell"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**"
+  ],
+  "pattern": "\\bfor\\s+\\w+\\s+in\\s+\\$\\(\\s*ls\\b|\\bls\\b[^|\\n]*\\|\\s*(?:while|xargs)\\b",
+  "flags": "m",
+  "bad": "for f in $(ls *.txt); do echo \"$f\"; done",
+  "good": "for f in *.txt; do echo \"$f\"; done"
+}

package/packs/shell/checks/sh-no-pipe-to-shell.json

@@ -0,0 +1,18 @@
+{
+  "id": "sh-no-pipe-to-shell",
+  "why": "A download piped into a shell runs whatever the server sends, unread.",
+  "rule": ".claude/rules/shell-strict-and-quoted.md",
+  "concepts": [
+    "shell"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**"
+  ],
+  "pattern": "\\b(?:curl|wget)\\b[^\\n|]*\\|\\s*(?:sudo\\s+)?(?:ba|z|da)?sh\\b",
+  "flags": "m",
+  "bad": "curl -fsSL https://example.com/i.sh | sh",
+  "good": "curl -fsSL -o i.sh https://example.com/i.sh"
+}

package/packs/shell/checks/sh-no-program-in-heredoc.json

@@ -0,0 +1,18 @@
+{
+  "id": "sh-no-program-in-heredoc",
+  "why": "A program in a heredoc cannot be linted, tested or reused. Give it its own file and call it.",
+  "rule": ".claude/rules/shell-strict-and-quoted.md",
+  "concepts": [
+    "shell"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**"
+  ],
+  "pattern": "\\b(?:python3?|node|ruby|perl)\\s+(?:-\\w+\\s+)*-(?:\\s[^\\n]*)?<<",
+  "flags": "m",
+  "bad": "python3 - \"$out\" <<'EOF'\nprint(1)\nEOF",
+  "good": "python3 tools/read_out.py \"$out\""
+}