@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/packs/react/checks/dialog-needs-role.json

@@ -0,0 +1,28 @@
+{
+  "id": "dialog-needs-role",
+  "why": "A modal with no role is a blank page to a screen reader.",
+  "rule": ".claude/rules/react-accessible-controls.md",
+  "globs": [
+    "**/*.tsx",
+    "**/*.jsx"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "strings": true,
+  "pattern": "\\bfixed inset-0\\b",
+  "mode": "needs",
+  "needs": [
+    "role=[\\\"'{]+dialog|<dialog\\b|<Dialog\\b"
+  ],
+  "bad": "<div className=\"fixed inset-0 z-50\"><div>x</div></div>",
+  "good": "<div role=\"dialog\" aria-modal=\"true\" className=\"fixed inset-0\"></div>"
+}

package/packs/react/checks/effect-not-for-derived-state.json

@@ -0,0 +1,24 @@
+{
+  "id": "effect-not-for-derived-state",
+  "why": "The screen shows data for the filter the user left, with no sign that it is wrong.",
+  "rule": ".claude/rules/react-state-and-effects.md",
+  "globs": [
+    "**/*.tsx",
+    "**/*.jsx"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "code": true,
+  "pattern": "useEffect\\(\\s*\\(\\)\\s*=>\\s*\\{?\\s*set[A-Z]\\w*\\([^;\\n]*\\)\\s*;?\\s*\\}?\\s*,\\s*\\[[^\\]]+\\]\\s*\\)",
+  "bad": "useEffect(() => { setPage(1); }, [filter]);",
+  "good": "const onFilter = (f) => { setFilter(f); setPage(1); };"
+}

package/packs/react/checks/icon-button-needs-name.json

@@ -0,0 +1,24 @@
+{
+  "id": "icon-button-needs-name",
+  "why": "A button with only an icon has no name for anyone who cannot see it.",
+  "rule": ".claude/rules/react-accessible-controls.md",
+  "globs": [
+    "**/*.tsx",
+    "**/*.jsx"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "strings": true,
+  "pattern": "<button\\b(?![^>]*(?:aria-label|title=))[^>]*>\\s*<[A-Z]\\w*\\b[^>]*/>\\s*</button>",
+  "bad": "<button onClick={f}><X className=\"w-4\" /></button>",
+  "good": "<button aria-label=\"Close\" onClick={f}><X /></button>"
+}

package/packs/react/checks/label-needs-a-field.json

@@ -0,0 +1,24 @@
+{
+  "id": "label-needs-a-field",
+  "why": "A label tied to no field neither names it nor focuses it on a click.",
+  "rule": ".claude/rules/react-accessible-controls.md",
+  "globs": [
+    "**/*.tsx",
+    "**/*.jsx"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "strings": true,
+  "pattern": "<label\\b(?![^>]*htmlFor)[^>]*>[^<]*</label>",
+  "bad": "<label className=\"x\">Email</label><input />",
+  "good": "<label htmlFor=\"e\">Email</label><input id=\"e\" />"
+}

package/packs/react/checks/ui-failed-fetch-says-so.json

@@ -0,0 +1,23 @@
+{
+  "id": "ui-failed-fetch-says-so",
+  "why": "An empty screen after a failure tells the customer their data is gone, and nobody hears about it.",
+  "rule": ".claude/rules/react-state-and-effects.md",
+  "globs": [
+    "**/*.tsx"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "strings": true,
+  "pattern": "catch\\s*(?:\\(\\s*\\w*\\s*\\))?\\s*\\{\\s*console\\.\\w+\\([^;{}]*\\);?\\s*\\}",
+  "bad": "try { await load(); } catch (e) { console.error(e); }",
+  "good": "try { await load(); } catch (e) { setError(message(e)); }"
+}

package/packs/react/checks/ui-ok-branch-has-an-else.json

@@ -0,0 +1,23 @@
+{
+  "id": "ui-ok-branch-has-an-else",
+  "why": "An empty screen after a failure tells the customer their data is gone, and nobody hears about it.",
+  "rule": ".claude/rules/react-state-and-effects.md",
+  "globs": [
+    "**/*.tsx"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "strings": true,
+  "pattern": "\\bif\\s*\\(\\s*\\w+\\.ok\\s*\\)\\s*\\{(?:[^{}]|\\{(?:[^{}]|\\{[^{}]*\\})*\\})*\\}\\s*(?!else\\b)(?=[\\n}])",
+  "bad": "if (res.ok) { setData(await res.json()); }\n}",
+  "good": "if (!res.ok) { setError('x'); return; }\nsetData(await res.json());"
+}

package/packs/react/pack.json

@@ -0,0 +1,20 @@
+{
+  "name": "react",
+  "version": "1.0.0",
+  "description": "React: a failed request says so, a slow response never overwrites a newer one, effects are not used for derived state, and controls have names.",
+  "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/react"
+  },
+  "keywords": [
+    "react"
+  ],
+  "engines": {
+    "claude-packs": ">=0.25.0"
+  }
+}

package/packs/react/rules/react-accessible-controls.md

@@ -0,0 +1,20 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+---
+
+# Every control has a name, and every dialog says it is one
+
+<constraints>
+Always do:
+- Give an icon-only button an `aria-label`.
+- Tie every label to its field with `htmlFor`.
+- Give a modal `role="dialog"` and `aria-modal`, and move focus into it.
+
+Never do:
+- Use a clickable `div` where a `button` belongs.
+</constraints>
+
+## Check
+`dialog-needs-role`, `icon-button-needs-name`, `label-needs-a-field`.

package/packs/react/rules/react-state-and-effects.md

@@ -0,0 +1,23 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+---
+
+# A failed request says so, and a slow response never overwrites a newer one
+
+<constraints>
+Always do:
+- Give every request three states on screen: loading, failed, done.
+- Cancel an effect's request in its cleanup with `AbortController`, or ignore a stale response by id.
+- Derive a value during render when it comes from props or state.
+- Use a data library's cache where the project has one, not a `useEffect` per fetch.
+
+Never do:
+- Catch a failed request and render nothing.
+- Copy props into state with an effect.
+- Branch on `res.ok` with no `else`.
+</constraints>
+
+## Check
+`ui-failed-fetch-says-so`, `ui-ok-branch-has-an-else`, `effect-not-for-derived-state`.

package/packs/reverse-engineering/checks/ear-constant-tagged.json

@@ -0,0 +1,23 @@
+{
+  "id": "ear-constant-tagged",
+  "why": "A value tuned by ear with no tag leaves the ledger unaware of a debt.",
+  "rule": ".claude/rules/every-law-has-a-source.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**"
+  ],
+  "pattern": "(?:\\/\\/|#)(?![^\\n]*\\[EAR\\])[^\\n]*\\b(?:by ear|sounds? (?:right|good|fine|about right)|eyeballed)\\b",
+  "bad": "kDrive = 1.7f; // sounds right",
+  "good": "kDrive = 1.7f; // [EAR] ledger row 12: tuned by ear",
+  "flags": "i"
+}

package/packs/reverse-engineering/checks/no-default-on-distrust.json

@@ -0,0 +1,24 @@
+{
+  "id": "no-default-on-distrust",
+  "why": "Falling back to a default for a value you distrust loads the wrong sound with no error: 272 of 625 presets did. Report it.",
+  "rule": ".claude/rules/account-every-term.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**"
+  ],
+  "pattern": "if\\s*\\(\\s*!\\s*\\w*(?:trusted|valid|decoded)\\w*\\s*\\)[^;\\n]*=\\s*[^;\\n]*default",
+  "bad": "if (! trusted) v = algo.defaults();",
+  "good": "if (! trusted) report.add (name);",
+  "flags": "i",
+  "code": true
+}

package/packs/reverse-engineering/checks/no-rom-table-literal.json

@@ -0,0 +1,29 @@
+{
+  "id": "no-rom-table-literal",
+  "why": "A long numeric table in source is usually bytes lifted from a ROM. Regenerate it from its formula, with a tolerance test.",
+  "rule": ".claude/rules/firmware-stays-out.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**",
+    "**/generated/**",
+    "**/*.generated.*",
+    "**/*_data.*",
+    "**/*Data.*",
+    "**/*Tables.*",
+    "**/*Table.*"
+  ],
+  "pattern": "\\{\\s*(?:-?(?:0x[0-9a-fA-F]+|\\d+(?:\\.\\d+)?)[uUlLfF]*\\s*,\\s*){31,}",
+  "bad": "const uint8_t curve[] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39};",
+  "good": "const int steps[] = {1, 2, 4, 8};",
+  "code": true
+}

package/packs/reverse-engineering/checks/prose-never-decides.json

@@ -0,0 +1,22 @@
+{
+  "id": "prose-never-decides",
+  "why": "A substring of a description decides nothing: \"turned off\" once switched echoes on, and 93 reverbs measured as delays. Use the record field.",
+  "rule": ".claude/rules/account-every-term.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**"
+  ],
+  "pattern": "[\"'][^\"'\\n]+[\"']\\s+in\\s+\\w*(?:desc|comment|prose)\\w*|\\b\\w*(?:desc|comment|prose)\\w*\\.(?:contains|find|includes|indexOf)\\s*\\(",
+  "bad": "is_echo = \"echo\" in desc",
+  "good": "is_echo = rec.keyword == KW_ECHO"
+}

package/packs/reverse-engineering/hooks/firmware-out-of-git.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// PreToolUse (Bash): firmware stays out of git. ROM images, DSP blobs, disassemblies and vendor banks are other people's bytes, and git keeps them for ever, so `git add`
+// of one is refused. A small test fixture is named in layout.json "guards": { "firmware": { "fixtures": ["<glob>"] } }. This is a house policy, not legal advice.
+// `--selftest` proves it.
+import { spawnSync } from 'node:child_process';
+import { join, relative, resolve } from 'node:path';
+import { gitAdds } from './lib/git-adds.mjs';
+import { matchesAny } from './lib/glob.mjs';
+import { readLayout } from './lib/layout.mjs';
+import { checkoutRoot, claudeRoot } from './lib/project.mjs';
+import { bashOf, git, runHook, scratchProject, verdicts } from './lib/selftest.mjs';
+import { judgeEvent } from './lib/writes.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const FIRMWARE = /\.(bin|rom|eprom|epr|hex|srec|s19|mot|ic\d+|lod|syx|mid|dis|disasm|asm\.txt|lst|wiz|mfw|raf)$/i;
+const OWN_BUILD = /(^|\/)(build|out|dist|target)\//;
+
+const staged = (dir, arg) => (spawnSync('git', ['ls-files', '--others', '--modified', '--exclude-standard', '--', arg], { cwd: dir, encoding: 'utf8' }).stdout ?? '').split('\n').filter(Boolean).map((f) => resolve(dir, f));
+
+function judgeAdd(command, cwd) {
+  for (const { dir, args } of gitAdds(command, cwd)) {
+    const root = checkoutRoot(join(dir, 'x'));
+    const fixtures = readLayout(claudeRoot(join(dir, 'x'))).guards?.firmware?.fixtures ?? [];
+    for (const abs of args.filter((a) => !a.startsWith('-')).flatMap((a) => staged(dir, a))) {
+      const rel = relative(root, abs).replace(/\\/g, '/');
+      if (FIRMWARE.test(rel) && !OWN_BUILD.test(rel) && !matchesAny(rel, fixtures)) return `${rel} looks like firmware, a disassembly or a sound bank, which stays out of git. Keep it local, and ship derived facts. A small test fixture is named in guards.firmware.fixtures.\n`;
+    }
+  }
+  return null;
+}
+
+const main = (text) => judgeEvent(text, { name: 'firmware-out-of-git', command: judgeAdd });
+
+function selftest() {
+  const hook = new URL(import.meta.url).pathname;
+  const dir = scratchProject({ 'roms/os.bin': 'x', 'banks/factory.syx': 'x', 'test/fixtures/one.syx': 'x', 'src/a.cpp': 'x', '.claude/layout.json': JSON.stringify({ guards: { firmware: { fixtures: ['test/fixtures/**'] } } }) });
+  git(dir, 'init', '-q');
+  const add = (p) => runHook(hook, dir, bashOf(`git add ${p}`, dir));
+  return verdicts('firmware-out-of-git', [
+    ['a ROM image', add('roms/os.bin'), 2],
+    ['a folder holding one', add('roms'), 2],
+    ['a sound bank', add('banks/factory.syx'), 2],
+    ['a named fixture', add('test/fixtures/one.syx'), 0],
+    ['source', add('src/a.cpp'), 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('firmware-out-of-git', main));

package/packs/reverse-engineering/pack.json

@@ -0,0 +1,35 @@
+{
+  "name": "reverse-engineering",
+  "version": "1.0.0",
+  "description": "Rebuilding a machine from its firmware, manuals and sound banks: two sources before naming anything, every law carries its source, a negative names what was scanned, every term of a sum is accounted for, and firmware stays out of git.",
+  "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/reverse-engineering"
+  },
+  "keywords": [
+    "reverse-engineering",
+    "firmware"
+  ],
+  "engines": {
+    "claude-packs": ">=0.28.0"
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/firmware-out-of-git.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/packs/reverse-engineering/rules/a-negative-names-what-was-scanned.md

@@ -0,0 +1,19 @@
+---
+# concepts: cpp, js, notes, tooling
+---
+
+# A negative result names what was scanned, and a positive one its noise floor
+
+<constraints>
+Always do:
+- List every segment and base searched before writing "not found", and record the search so nobody repeats it.
+- Check an extracted count against an outside statement. A walk that stops early gives a clean, wrong number and no error.
+- Measure the noise floor of any scoring test: random bytes must fail it. Strip erased space first.
+- Fix the origin and descramble before comparing. A stride gives spacing, not an origin.
+- Read filenames, READMEs and part numbers first. A "blocked" note is a claim.
+- Quote a ratio, never "works".
+
+Never do:
+- Ship "no table exists" as an `[EAR]` law because one search missed it.
+- Close an item as "does not exist" when the truth is "not yet read".
+</constraints>

package/packs/reverse-engineering/rules/account-every-term.md

@@ -0,0 +1,20 @@
+---
+# concepts: cpp, js, notes, tooling
+---
+
+# A computed value is a sum: account for every term
+
+One missing term was 2.3 octaves, and it had no parameter to find.
+
+<constraints>
+Always do:
+- Read what reaches the accumulator in the routine that writes the coefficient, not the parameter handlers, and name each term's source. The terms missed have no stored byte.
+- Prove slope and anchor separately. Anchors come from calibration procedures and autotune targets.
+- After a load, compare every field of every program with the engine's copy, and report the count.
+- Take ranges from the source's arithmetic, not a manual's rounded print.
+- Decide from the record's field, never from words in a description.
+
+Never do:
+- Hide a missing term behind a fudge factor: fix the term, then re-anchor.
+- Let a value the loader distrusts fall back to a default in silence. Hundreds of presets sounded fine while being the wrong sound.
+</constraints>

package/packs/reverse-engineering/rules/addresses-name-their-space.md

@@ -0,0 +1,22 @@
+---
+# concepts: cpp, js, notes, tooling
+---
+
+# Every address names its space, and a table its bounds
+
+<constraints>
+Always do:
+- Say what each address is: a file offset, a CPU address, a physical address, `seg:off`, a DSP `P:`, `X:` or `Y:` address, or a word index. Record the load map, and prove a base by scoring.
+- Read a strictly rising run of 16-bit values as a pointer table or paired bytes until shown otherwise, never as a curve: check whether its values are CPU addresses in its own bank first.
+- Find a table's own start and end before reading it. A `[FW]` tag covers the bytes, the boundary and the role separately.
+- Index records by their marker over the whole image, and state the count and the gaps. A scan of one range found 47 of 174.
+- Make an unpacked image answer "was this address ever written?". A zero read past where the loader stopped is unknown, and one blocked a law for a whole phase.
+- Print a table and check a known parameter before publishing what a field means. A compare instruction alone got min and max backwards.
+- Re-derive a field per block: one table's bytes can change meaning partway through.
+
+Never do:
+- Read a stride across a segment: that invented a 2469-entry table.
+- Trust "exactly twice" from two or three points. A wrong index looks like a scale factor.
+- Call a block compressed or empty before reading what loads it. A 3-byte header in each bank had shifted the alignment.
+- Take "it disassembles" as proof of code: count the undecodable words against a baseline.
+</constraints>

package/packs/reverse-engineering/rules/every-law-has-a-source.md

@@ -0,0 +1,18 @@
+---
+# concepts: cpp, js, notes, tooling
+---
+
+# Every law carries its source, and a guess is a debt
+
+<constraints>
+Always do:
+- Tag each constant and law with its source on its line: `[FW]` firmware with an address, `[SCH]` a schematic, `[MAN]` a manual page, `[MIDI]` the spec, `[PUB]` a published source, `[COR]` the corpus, `[EAR]` fitted by ear.
+- Keep every `[EAR]` value in a ledger, with a lead to what would close it.
+- Replace an `[EAR]` value only with evidence. An ear will approve a wrong constant.
+- Say which tags cannot exist on a machine: a chip whose program was never dumped can have no `[FW]`.
+- Keep a list of non-negotiable constants, each with a test that fails if someone corrects it.
+
+Never do:
+- Let a sourced fact launder a guess in the same formula.
+- Tag a block you wrote yourself as firmware-exact. Say what it is: the right kind of effect, not a clone.
+</constraints>

package/packs/reverse-engineering/rules/findings-are-withdrawn-in-place.md

@@ -0,0 +1,17 @@
+---
+# concepts: cpp, js, notes, tooling
+---
+
+# A finding is withdrawn in place, with the same evidence a claim needs
+
+<constraints>
+Always do:
+- Mark a withdrawn finding where it stands, with what overturned it.
+- Hold a withdrawal to the bar of a claim: run the mapping over the whole table, and every source again.
+- Treat a flat distribution as a sign the decode is wrong.
+- Follow a withdrawal to everything built on it: code that still includes the table, and other repos' copies of the finding.
+
+Never do:
+- Delete a wrong finding: the next reader will make the same mistake.
+- Withdraw on two rows.
+</constraints>

package/packs/reverse-engineering/rules/firmware-stays-out.md

@@ -0,0 +1,18 @@
+---
+# concepts: cpp, js, notes, tooling
+---
+
+# Firmware stays out of git: ship facts, never bytes
+
+<constraints>
+This is a house policy, not legal advice.
+
+Always do:
+- Keep ROM images, DSP blobs, disassemblies and vendor banks out of every repo.
+- Ship original code and derived facts. Regenerate a table from its formula, with a tolerance test.
+- Name each small test fixture in `"guards": { "firmware": { "fixtures": ["<glob>"] } }`.
+
+Never do:
+- Paste table bytes into source, not even a 128-byte curve.
+- Commit a sound bank to make a test pass, unless it is a named fixture.
+</constraints>

package/packs/reverse-engineering/rules/names-before-code.md

@@ -0,0 +1,19 @@
+---
+# loads: at launch. It applies before any file is opened, so no path could trigger it.
+---
+
+# The machine's own names come first: the manual, then the strings, then the code
+
+<constraints>
+Always do:
+- Before any disassembly, list every name the manual prints (patches, arp patterns, delay and reverb programs, effect types, menus, parameters) and search the image and the dumps for them (`names-first`, `names-sweep`).
+- Treat a manual's name as the test of an unpacking: when it reads, the unwrapping is right.
+- Take the stride between names as a record size and their order as the parameter order, then prove both.
+- Complete a manual's cut lists from the firmware, and map the menus (`menu-map`): what the panel reaches and no dump holds is a finding.
+
+Never do:
+- Open a disassembler on an image whose names have not been searched for.
+- Read "no strings" as "no text". The image is still wrapped until known names read, and one or two reading is chance.
+- Assign names by the order of the manual's prose: use the address table, the range and the item count.
+- Name a parameter from a string alone when it is a law: a name says what a value is called, never how it behaves.
+</constraints>

package/packs/reverse-engineering/rules/reproduction-or-original.md

@@ -0,0 +1,18 @@
+---
+# concepts: cpp, js, notes, tooling
+---
+
+# Say whether this is a reproduction or an original: the laws differ
+
+<constraints>
+Declare it in layout.json: `"guards": { "instrument": { "kind": "reproduction" } }`, or `"original"`.
+
+Always do:
+- On a reproduction, the machine is the spec. Its naive saw, its aliasing and its linear pan are the instrument, each with a `[FW]`, `[SCH]` or `[MAN]` source.
+- On an original, the law is good engineering: band-limited, click-free, and yours to design.
+- Default a control the original lacks to "does nothing": a wet/dry at 0.5 once made every preset half wet.
+
+Never do:
+- Invent a global control on a reproduction. It rewrites every preset.
+- Copy the machine's artwork, unless the brief asks for it and `"guards": { "instrument": { "artwork": "verbatim" } }` says so. By default a reproduction has the same sections, positions and labels, drawn your own way. With `"artwork": "verbatim"` the picture is the spec, and whoever ships it decides whether they may: log that as an open question.
+</constraints>

package/packs/reverse-engineering/rules/two-sources-before-naming.md

@@ -0,0 +1,21 @@
+---
+# concepts: cpp, js, notes, tooling
+---
+
+# Two independent sources before anything is named
+
+A value read from a routine looks exactly as confident as a guess. Read what consumes it before naming it: a portamento table was once read as an LFO.
+
+<constraints>
+Always do:
+- Write nothing into the model until two independent sources agree. A wrong name corrupts every patch and is worse than a blank.
+- Count as one source: agreement on a class, a matching count, or a value fed into a table.
+- Run a law over the whole corpus, in both directions, before writing or removing a name. One bank proves nothing.
+- Say how sources arbitrate: firmware wins on mechanism, the manual on stated absolutes, the corpus decides between them. Keep a real contradiction; never average it.
+- Treat a sibling machine's law or layout as a hypothesis. A shared name is not a shared layout.
+- Name a peripheral or a CPU from its own manual, never from what it seems to do.
+
+Never do:
+- Trust a published spec, an editor export or a datasheet alone: each has been wrong for a build.
+- Change an attribution without running every source again.
+</constraints>

package/packs/reverse-engineering/skills/bank-census/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: bank-census
+description: Use when a law seems wrong, when presets sound alike or too dark, or before calling a filter or level law finished.
+---
+
+# Take a census of the bank (one job: see where a value settles across every program)
+
+<constraints>
+Always do:
+1. Render the whole factory bank, and record the value in question for every program.
+2. Read the distribution, at rest and at peak together: a patch dark at rest can open wide. Bunched dark at both, or pinned bright, means a term is missing or invented.
+3. If it is clean, count the programs that set each byte: a term that is zero at rest leaves no trace.
+4. Flag any program 40 dB under its neighbours.
+5. Compare with what the machine's own bank was voiced for.
+
+Never do:
+- Run this on your own starter bank. It proves nothing.
+</constraints>

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

@@ -0,0 +1,22 @@
+---
+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.
+9. A source that exists and cannot be fetched (the host refuses automated access, the file is behind a login): record its name, where it is, what refused, and what it would have settled, in the project's decisions. Mark what rests on its absence as a `[gap]`, ask the user for the file when a person is there, and go on with the next source.
+
+Never do:
+- Start the disassembly before steps 1 to 4.
+</constraints>