@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/packs/js-ts/rules/process-lifecycle.md

@@ -0,0 +1,47 @@
+---
+# concepts: entry
+paths:
+  - "placeholder"
+---
+
+# The process shuts down on purpose: server first, then the database, then exit
+
+A service that listens must also stop. `docker stop`, Swarm, K8s and Ctrl-C send SIGTERM/SIGINT; without a handler the pool is dropped mid-query and every deploy's in-flight requests die with connection errors that read as flakiness. A crash with no handler exits uncleanly with the pool open; a crash handler that exits 0 reads as success and the dead service is never restarted.
+
+<constraints>
+Always do:
+- Every entry file that calls `listen(` / `createServer(` / connects a database registers **one** `shutdown(reason, code)` and routes four events through it: `SIGTERM`, `SIGINT`, `uncaughtException`, `unhandledRejection`. The `entry-registers-shutdown` check refuses an entry file that listens without all four.
+- Order inside `shutdown`: stop accepting (`await app.close()` in Fastify, which drains in-flight requests) → `await closeDb()` → other clients → `process.exit(code)`. Server **before** database, always.
+- A hard timeout: `setTimeout(() => process.exit(code || 1), 10_000).unref()` at the top of `shutdown`, so a stuck connection cannot block exit forever.
+- Guard against re-entry: a second signal during shutdown is ignored (`if (closing) return`).
+- Crash handlers (`uncaughtException`, `unhandledRejection`) log with `console.error` (the one allowed use: the async logger may not flush before exit), run the same `shutdown`, and exit **non-zero**.
+- Docker: `ENTRYPOINT`/`CMD` in exec form (a JSON array) and `init: true`, or signals never reach Node (`docker-exec-form`).
+
+Never do:
+- Async cleanup in `process.on('exit')`: the loop has already stopped; nothing awaits.
+- `process.exit(0)` from a crash handler.
+- Trap `SIGUSR1` (Node's debugger signal).
+- A second place that closes the database or calls `process.exit` for a shutdown reason.
+</constraints>
+
+```ts
+// src/lifecycle.ts, imported once by the entry file
+import { closeDb } from './db/gateway.js';
+export function installLifecycle(app: FastifyInstance): void {
+  let closing = false;
+  const shutdown = async (reason: string, code: number): Promise<void> => {
+    if (closing) return;
+    closing = true;
+    setTimeout(() => process.exit(code || 1), 10_000).unref();   // hard stop
+    app.log.info({ reason }, 'shutting down');
+    try { await app.close(); } catch (err: unknown) { app.log.error({ err }, 'server close failed'); code ||= 1; }
+    try { await closeDb(); } catch (err: unknown) { app.log.error({ err }, 'db close failed'); code ||= 1; }
+    process.exit(code);
+  };
+  const run = (reason: string, code: number) => shutdown(reason, code).catch(() => process.exit(1));
+  process.on('SIGTERM', () => run('SIGTERM', 0));
+  process.on('SIGINT', () => run('SIGINT', 0));
+  process.on('uncaughtException', (err) => { console.error('uncaughtException', err); run('uncaughtException', 1); });
+  process.on('unhandledRejection', (err) => { console.error('unhandledRejection', err); run('unhandledRejection', 1); });
+}
+```

package/packs/js-ts/rules/schema-single-source-of-truth.md

@@ -0,0 +1,36 @@
+---
+# concepts: schemas, handlers
+paths:
+  - "placeholder"
+---
+
+# One Zod schema per entity; everything else is derived from it
+
+The failure this kills: the same entity declared at each layer (a frontend interface, a backend interface, a hand-written validator, a manual DB schema), kept in sync by hand, guaranteed to drift the first time a field is added.
+
+<constraints>
+Always do:
+- One file per entity in the project's **one** schemas module (`src/schemas/` or a `packages/schemas` workspace), with a barrel `index.ts`. The barrel carries this header so whoever extends it reads the rule at that moment:
+  ```ts
+  // SCHEMAS MODULE: single source of truth for every data entity.
+  // One file per entity; this barrel re-exports all. Derive types with z.infer and variants with
+  // .omit/.pick/.extend. NEVER hand-write a parallel interface or declare z.object() in a route/handler/adapter.
+  // New entity => new file here + export below. Rule: schema-single-source-of-truth.
+  ```
+- Derive, never restate: `type User = z.infer<typeof UserSchema>`; `CreateUserInput = UserSchema.omit({ _id: true, created_at: true })`; `UserResponse = UserSchema.extend({ _id: z.string() })` built by one `toWire(schema)` helper, not six hand-written response shapes.
+- Parse at every boundary with the same schema: `safeParse` on `req.body`/`query`/`params` (→ 400), the form resolver on the client, the pre-write guard in the gateway, `$jsonSchema` for the collection generated from it in the deploy step.
+- Every `z.string()` carries a `.max()`; every record/array of unknown size carries a bound. Unbounded input is a 16 MB document waiting to happen.
+- Zod 4 top-level formats: `z.email()`, `z.uuid()`, `z.iso.datetime()`, `z.url()`. Never the deprecated `z.string().email()` family.
+- Constants that bound a field (`MAX_STEPS`, a cap, an enum list) live **once**, exported from the schema file, and the validator, the renderer and the `.slice()` all import it.
+
+Never do:
+- `z.object(` in a route, handler, adapter, service or controller file. The `no-inline-zod-outside-schemas` check refuses it: declare it in the schemas module and import it, even "just for this one form".
+- An `interface`/`type` that parallels a schema field-by-field.
+- Merge a partial update by hand and cast the result: `Schema.parse(merged)` after the merge.
+- Read Zod private internals (`schema._zod.def`) without pinning the exact Zod version and a test that walks every schema.
+</constraints>
+
+## Checks
+- `no-inline-zod-outside-schemas`: `z.object(` outside the schemas module.
+- `zod-string-needs-max`: a `z.string()` chain in the schemas module with no `.max(`.
+- `zod-v4-formats`: `z.string().email()`, `.uuid()`, `.url()`, `.datetime()`, `.ip()` → the Zod 4 top-level form.

package/packs/js-ts/rules/secrets-stay-secret.md

@@ -0,0 +1,22 @@
+---
+# concepts: js
+paths:
+  - "placeholder"
+---
+
+# A secret never reaches a log, a default or Math.random
+
+<constraints>
+Always do:
+- Log what happened, never the body: name the fields you log.
+- Make keys and codes with `crypto.randomBytes`.
+- Fail at start-up when a secret is missing.
+
+Never do:
+- Log a request body, a password or a token.
+- Give a secret a default value.
+- Use `Math.random` for anything an attacker would like to guess.
+</constraints>
+
+## Check
+`no-secret-in-log`, `secret-needs-crypto-random`, `secret-has-no-fallback`.

package/packs/js-ts/rules/small-functions.md

@@ -0,0 +1,20 @@
+---
+# concepts: js
+paths:
+  - "placeholder"
+---
+
+# Functions stay under 50 lines
+
+## The law
+A function does one thing and fits on one screen: 50 lines max, blanks and comments excluded. When it grows past that, extract the named steps into their own functions.
+
+## Exceptions
+- React components whose body is mostly JSX markup: split the markup into subcomponents rather than raising the limit.
+- Test files (a `describe` block is a function).
+
+## Check
+```js
+'max-lines-per-function': ['error', { max: 50, skipBlankLines: true, skipComments: true }],
+{ files: ['**/*.test.*', '**/*.spec.*'], rules: { 'max-lines-per-function': 'off' } },
+```

package/packs/js-ts/rules/test-names-describe-behavior.md

@@ -0,0 +1,28 @@
+---
+# concepts: js-tests
+paths:
+  - "placeholder"
+---
+
+# Test names state the behavior; bodies are Arrange-Act-Assert
+
+## The law
+- The title says what happens under which condition: `returns 404 when the user does not exist`, not `test getUser`.
+- The body has three visible parts: arrange, act, assert. One behavior per test.
+- Fix the code, not the test, unless the test itself is wrong. Say which one it is when you change a test.
+
+```ts
+it('rejects an order when the card is expired', async () => {
+  const order = makeOrder({ card: expiredCard });   // arrange
+  const result = await checkout(order);             // act
+  expect(result).toEqual({ ok: false, error: 'card_expired' }); // assert
+});
+```
+
+## Check
+```js
+// @vitest/eslint-plugin
+'vitest/valid-title': 'error',
+'vitest/expect-expect': 'error',
+'vitest/no-identical-title': 'error',
+```

package/packs/js-ts/rules/tests-can-fail.md

@@ -0,0 +1,19 @@
+---
+# concepts: js
+paths:
+  - "placeholder"
+---
+
+# A test imports the code it proves
+
+<constraints>
+Always do:
+- Import the real module under test, and call it.
+- See a new test fail with the code broken.
+
+Never do:
+- Copy the code into the test, or test a hand-made copy of the behaviour.
+</constraints>
+
+## Check
+`test-imports-the-source`.

package/packs/js-ts/rules/tsconfig-strict.md

@@ -0,0 +1,32 @@
+---
+# concepts: tsconfig
+paths:
+  - "placeholder"
+---
+
+# tsconfig is strict and stays strict
+
+## The law
+Every tsconfig keeps:
+```jsonc
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true
+  }
+}
+```
+Never loosen these to make an error go away. Fix the code instead.
+
+## Check
+Resolve the effective config (this handles `extends` and comments) and assert it in the hook:
+```bash
+npx tsc --showConfig -p tsconfig.json | node -e '
+  const c = JSON.parse(require("fs").readFileSync(0)).compilerOptions;
+  const need = ["strict","noUncheckedIndexedAccess","exactOptionalPropertyTypes","noImplicitOverride"];
+  const off = need.filter(k => c[k] !== true);
+  if (off.length) { console.error("tsconfig not strict:", off.join(", ")); process.exit(2); }'
+```
+Exit code 2 makes a Claude Code PostToolUse hook block and report it.

package/packs/js-ts/rules/typed-exports.md

@@ -0,0 +1,27 @@
+---
+# concepts: ts
+paths:
+  - "placeholder"
+---
+
+# Explicit types on exports
+
+## The law
+Every exported function and public method declares its parameter types and return type. Inside a function, let TypeScript infer local variables.
+
+```ts
+// NO
+export function formatUser(user) { return `${user.first} ${user.last}`; }
+
+// YES
+export function formatUser(user: User): string {
+  return `${user.first} ${user.last}`;
+}
+```
+
+Why: the export is the contract. An inferred return type silently changes when the body changes, and that breaks callers in a different file.
+
+## Check
+```js
+'@typescript-eslint/explicit-module-boundary-types': 'error',
+```

package/packs/js-ts/rules/types-once-at-the-edge.md

@@ -0,0 +1,18 @@
+---
+# concepts: js
+paths:
+  - "placeholder"
+---
+
+# A shared type is declared once, not cast at each use
+
+<constraints>
+Always do:
+- Declare the session, the user and the request context once, with module augmentation or one typed accessor.
+
+Never do:
+- Repeat `as { user: ... }` at every use.
+</constraints>
+
+## Check
+`session-user-typed-once`.

package/packs/js-ts/rules/unions-over-enums.md

@@ -0,0 +1,29 @@
+---
+# concepts: ts
+paths:
+  - "placeholder"
+---
+
+# String-literal unions over `enum`
+
+## The law
+Use a union of string literals, or an `as const` object when you also need runtime values. Do not use TypeScript `enum`.
+
+```ts
+// NO
+enum Role { Admin = 'admin', Member = 'member' }
+
+// YES
+export const ROLES = ['admin', 'member'] as const;
+export type Role = (typeof ROLES)[number];
+// Zod: z.enum(ROLES)
+```
+
+Why: enums emit runtime code, can't be erased by type-stripping runtimes (Node's native TS support), and numeric enums accept any number.
+
+## Check
+```js
+'no-restricted-syntax': ['error',
+  { selector: 'TSEnumDeclaration', message: 'Use a string-literal union or as-const array.' }],
+```
+(Merge this selector into any existing `no-restricted-syntax` list; the rule takes one array.)

package/packs/js-ts/rules/zod-at-route-boundaries.md

@@ -0,0 +1,40 @@
+---
+# concepts: routes
+paths:
+  - "placeholder"
+---
+
+# Every Fastify route declares a Zod schema
+
+## The law
+Each route validates its input (`body`, `querystring`, `params`, `headers` as needed) with Zod through Fastify's type provider. Handlers only ever see parsed data. No route reads `request.body` unvalidated.
+
+Make it structural: routes are registered **only** through one helper whose type requires a schema.
+
+```ts
+// lib/define-route.ts (the single base every route comes from)
+export function defineRoute<S extends RouteSchema>(def: {
+  method: HTTPMethods; url: string; schema: S; // required, not optional
+  handler: RouteHandler<S>;
+}) { return def; }
+
+// routes/users.ts
+export default defineRoute({
+  method: 'POST', url: '/users',
+  schema: { body: CreateUserSchema, response: { 201: UserSchema } },
+  handler: async (req) => createUser(req.body), // req.body is typed + validated
+});
+```
+
+## Why
+Untyped input also matters for MongoDB: an unvalidated `{ "email": { "$ne": null } }` body becomes a query operator. Zod forces `email` to stay a string.
+
+## Check
+Ban direct route registration outside the helper:
+```js
+'no-restricted-syntax': ['error', {
+  selector: "CallExpression[callee.property.name=/^(get|post|put|patch|delete|route)$/][callee.object.name=/^(app|fastify|server)$/]",
+  message: 'Register routes through defineRoute() so a schema is required.',
+}],
+```
+Adjust the paths above to match where your routes live.

package/packs/midi/checks/active-sensing-no-pulse.json

@@ -0,0 +1,24 @@
+{
+  "id": "active-sensing-no-pulse",
+  "why": "Treating the whole real-time range as pulses reads active sensing as clock, and reports a nonsense tempo.",
+  "rule": ".claude/rules/clock-is-a-pulse-stream.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**"
+  ],
+  "pattern": ">=\\s*0x[fF]8\\s*\\)\\s*\\{?\\s*(?:\\+\\+\\s*\\w+|\\w*(?:pulse|clock|tick)\\w*\\s*(?:\\+\\+|\\+=|\\())",
+  "bad": "if (b >= 0xF8) ++pulses;",
+  "good": "if (b == 0xF8) ++pulses;",
+  "flags": "i",
+  "code": true
+}

package/packs/midi/checks/clock-not-at-sample-zero.json

@@ -0,0 +1,23 @@
+{
+  "id": "clock-not-at-sample-zero",
+  "why": "A clock byte placed at sample zero jitters by a whole block.",
+  "rule": ".claude/rules/measure-the-clock-in-audio.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**"
+  ],
+  "pattern": "midiClock\\s*\\(\\s*\\)\\s*,\\s*0\\s*\\)",
+  "bad": "buffer.addEvent (MidiMessage::midiClock(), 0);",
+  "good": "buffer.addEvent (MidiMessage::midiClock(), pulseSample);",
+  "code": true
+}

package/packs/midi/checks/midi-realtime-first.json

@@ -0,0 +1,27 @@
+{
+  "id": "midi-realtime-first",
+  "why": "A receive path that masks the channel before testing for real-time bytes eats every clock byte.",
+  "rule": ".claude/rules/clock-is-a-pulse-stream.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**"
+  ],
+  "pattern": "\\b\\w+\\s*&\\s*0x[fF]0\\b",
+  "bad": "int k = b & 0xF0;",
+  "good": "if (b >= 0xF8) { rt (b); return; } int k = b & 0xF0;",
+  "mode": "needs",
+  "needs": [
+    "0x[fF]8|[rR]eal[tT]ime"
+  ],
+  "code": true
+}

package/packs/midi/checks/no-tempo-writeback.json

@@ -0,0 +1,23 @@
+{
+  "id": "no-tempo-writeback",
+  "why": "Writing the resolved tempo into the unit's own BPM field makes internal sync quietly follow the host, and every external test still passes.",
+  "rule": ".claude/rules/measure-the-clock-in-audio.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**"
+  ],
+  "pattern": "\\b\\w*[bB]pm\\w*\\s*(?:\\.|->)\\s*store\\s*\\(\\s*(?:\\w*[tT]empo\\w*|resolved\\w*|host\\w*|pos\\w*\\s*(?:\\.|->))",
+  "bad": "bpm.store (tempo);",
+  "good": "resolveTempo (bpm.load(), transport);",
+  "code": true
+}

package/packs/midi/checks/position-not-integrated.json

@@ -0,0 +1,29 @@
+{
+  "id": "position-not-integrated",
+  "why": "A position added up from tempo is wrong for ever after a locate. Derive it from the host.",
+  "rule": ".claude/rules/measure-the-clock-in-audio.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**",
+    "**/*Clock*",
+    "**/*clock*",
+    "**/tests/**",
+    "**/test/**",
+    "**/*_test.*",
+    "**/*Test.*"
+  ],
+  "pattern": "\\b\\w*(?:[pP]os|[pP]pq|[bB]eat)\\w*\\s*\\+=[^;\\n]*(?:bpm|[tT]empo)",
+  "bad": "posBeats += n * bpm / (60.0 * sr);",
+  "good": "posBeats = clock.blockStartPpq();",
+  "code": true
+}

package/packs/midi/checks/stub-playhead-advances.json

@@ -0,0 +1,27 @@
+{
+  "id": "stub-playhead-advances",
+  "why": "A frozen position pins the clock: invisible to a delay, and it reads as broken modulation.",
+  "rule": ".claude/rules/measure-the-clock-in-audio.md",
+  "globs": [
+    "**/tests/**/*.cpp",
+    "**/test/**/*.cpp",
+    "**/probes/**/*.cpp",
+    "**/*_test.cpp",
+    "**/*Test.cpp"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**"
+  ],
+  "pattern": "(?:ppqPosition\\s*=|setPpqPosition\\s*\\()\\s*[\\d.]+",
+  "bad": "info.ppqPosition = 0.0;",
+  "good": "info.ppqPosition = 0.0;\nppq += beatsPerBlock;",
+  "mode": "needs",
+  "needs": [
+    "[pP]pq\\w*\\s*\\+="
+  ],
+  "code": true
+}

package/packs/midi/checks/sysex-length-literal.json

@@ -0,0 +1,23 @@
+{
+  "id": "sysex-length-literal",
+  "why": "A record's length belongs to its type. 67 presets were really 625 behind a fixed length.",
+  "rule": ".claude/rules/sysex-is-a-record.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**"
+  ],
+  "pattern": "\\bgetSysExDataSize\\s*\\(\\s*\\)\\s*[!=]=\\s*\\d+",
+  "bad": "if (m.getSysExDataSize() != 268) return;",
+  "good": "if (m.getSysExDataSize() != lengthOf (type)) return;",
+  "code": true
+}

package/packs/midi/checks/sysex-not-on-audio.json

@@ -0,0 +1,24 @@
+{
+  "id": "sysex-not-on-audio",
+  "why": "Decoding a dump on the audio thread blocks it. Hand the message off.",
+  "rule": ".claude/rules/sysex-is-a-record.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**"
+  ],
+  "pattern": "(?:parse|load|decode|apply)\\w*\\s*\\([^;\\n]*getSysExData",
+  "bad": "loadPatch (m.getSysExData(), n);",
+  "good": "sysexInbox.push (m);",
+  "flags": "i",
+  "code": true
+}

package/packs/midi/checks/sysex-survives-realtime.json

@@ -0,0 +1,27 @@
+{
+  "id": "sysex-survives-realtime",
+  "why": "A clock byte can land inside a SysEx dump. A parser that assumes F0 to F7 runs clean corrupts it.",
+  "rule": ".claude/rules/clock-is-a-pulse-stream.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/build/**",
+    "**/out/**",
+    "**/_deps/**",
+    "**/JUCE/**",
+    "**/node_modules/**"
+  ],
+  "pattern": "while\\s*\\([^)\\n]*!=\\s*0x[fF]7\\s*\\)",
+  "bad": "while (*p != 0xF7) out.push_back (*p++);",
+  "good": "while (*p != 0xF7) { if (*p >= 0xF8) { rt (*p++); continue; } out.push_back (*p++); }",
+  "mode": "needs",
+  "needs": [
+    "0x[fF]8|[rR]eal[tT]ime"
+  ],
+  "code": true
+}

package/packs/midi/pack.json

@@ -0,0 +1,22 @@
+{
+  "name": "midi",
+  "version": "1.0.0",
+  "description": "MIDI that is right on the wire and in the audio: clock is a pulse stream, sync is a mode, and a program can be several sysex records that round-trip byte for byte. Nine units once shipped deaf to the transport with every test green.",
+  "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/midi"
+  },
+  "keywords": [
+    "midi",
+    "sysex",
+    "clock"
+  ],
+  "engines": {
+    "claude-packs": ">=0.28.0"
+  }
+}

package/packs/midi/rules/clock-is-a-pulse-stream.md

@@ -0,0 +1,30 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.cc"
+  - "**/*.h"
+  - "**/*.hpp"
+  - "**/*.mm"
+  - "**/*.py"
+  - "**/*.ts"
+  - "**/*.js"
+  - "**/*.mjs"
+---
+
+# MIDI clock is a pulse stream with no channel and no tempo message
+
+No byte says "120 BPM". The tempo is the rate the pulses arrive at. The full law is beside the `clock-probe` skill, in `clock-law.md`.
+
+<constraints>
+Always do:
+- Handle real-time bytes (`0xF8` and above) before any channel test. They have no channel.
+- Expect real-time bytes inside any message, a SysEx dump included.
+- Count only `0xF8` as a pulse. `0xFE` is active sensing, and it arrives constantly.
+- Write divisions in ticks at 192 per quarter: a 1/64 is one and a half MIDI clocks.
+- Keep the division list append-only, since a unit stores the index. Sort a copy for the menu.
+
+Never do:
+- Read a "sync channel" setting as a channel: it is usually a port or a device id.
+- Believe a factor of two at once. Suspect the meter first, then a duplicate clock or a pre-MIDI rate, then the divisions.
+- Assume a rate from a brand. Read the machine's manual, and its jack: a pulse count and a step trigger need different models.
+</constraints>

package/packs/midi/rules/imports-count-every-loss.md

@@ -0,0 +1,25 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.cc"
+  - "**/*.h"
+  - "**/*.hpp"
+  - "**/*.mm"
+  - "**/*.py"
+  - "**/*.ts"
+  - "**/*.js"
+  - "**/*.mjs"
+---
+
+# An import counts every loss, and the wire is not the storage
+
+<constraints>
+Always do:
+- Count and print each lossy step of an import. Refuse overflow, and say why a result is empty.
+- Check every UI range holds every corpus value.
+- Treat a controller's edit semantics as separate from the stored byte.
+- Test a published spec against firmware and the corpus.
+
+Never do:
+- Clamp a value in silence: 383 of 433 clamped once, and nothing said so.
+</constraints>