@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheDecipherist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,317 @@
-# Temporary Holding Version
+# @thedecipherist/claude-packs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Rules, checks, hooks and skills that hold Claude Code to what a senior engineer would accept, installed per project. A rule tells Claude the law, a hook refuses the write before it reaches the disk, and a skill walks the fix. Everything lives in the project's own `.claude/`, so a team gets it from the repo.
+
+## Start here
+
+Install the package in the project (Node 22+):
+
+```
+npm i -D @thedecipherist/claude-packs
+```
+
+Then four commands:
+
+```
+npx --no-install @thedecipherist/claude-packs suggest      # which packs this project needs, and why
+npx --no-install @thedecipherist/claude-packs init --auto  # install exactly that
+npx --no-install @thedecipherist/claude-packs scan         # everything already wrong, on a copy of the project
+npx --no-install @thedecipherist/claude-packs fix          # the scan as a work order: .claude/fix-plan.md
+```
+
+Then tell Claude to work through `.claude/fix-plan.md`. The `fix-from-scan` skill says how.
+
+`scan` is safe to run before installing anything: it works on a copy in a temp folder and never writes to the project. `suggest` only reads file names and `package.json`.
+
+## What happens when Claude writes code
+
+1. **At the prompt.** `making` asks what is being made and what it reuses. `reuse-hint` shows functions the repo already has when the prompt names them, before a line is drafted.
+2. **Before the first write.** The step's `making:` line goes in `build.md`: what, which concepts, what it reuses.
+3. **At every write.** Hooks judge what the tool call would write, by any route: Write, Edit, a shell redirect, `sed -i`, `cp`, a heredoc, an inline script. A refusal is exit 2 with the reason, and the file never changes.
+4. **At the end of the turn.** `making-check` compares what was written with what was said.
+5. **Before landing.** The whole suite runs once, on committed work, and `land-branch` merges and pushes.
+
+Four kinds of thing do the work:
+
+| Kind | What it is | Lives in |
+|---|---|---|
+| Rule | A short law, loaded only for the files it applies to | `.claude/rules/` |
+| Lesson check | A pattern with a `bad` and a `good` example. It refuses only an edit that adds a match, so old code can be fixed at its own pace | `.claude/checks/` |
+| Hook | Code that judges a tool call and can refuse it | `.claude/hooks/` |
+| Skill | One job's steps, loaded when the situation fits | `.claude/skills/` |
+
+## Repetition is stopped before it is written
+
+AI writes the same thing over and over, so the kit works on it at three points. `reuse-hint` puts what exists in front of Claude at the prompt. The `making:` line makes it say what it reuses. `template-law` refuses at the write, comparing code with names, numbers and strings stripped, so a copy with other names reads the same:
+
+| What it catches | What the refusal says to make |
+|---|---|
+| Markup built by hand again (HTML, JSX, Vue, Svelte, template strings) | One component |
+| An object filled in field by field again | One factory function |
+| A run of statements with one shape, whole or in part | One function, with what differs as parameters |
+| A near copy: most of a stretch matches another file, in order, with lines changed | One function |
+| One call repeated with other arguments | One table and one loop |
+| A function the repo already has, under the same compound name | Call it, or name it for its job |
+
+A refusal names the copies and lists what differs between them, which are the template's parameters. `make-it-a-template` walks the change, with a skill per language for the forms it has. A real exception says so above it: `one-off: <reason>`.
+
+One language table reads C, C++, Objective-C++, JS, TS, Python, shell, Go, Rust, Java, C#, Scala, Dart, Kotlin, Swift, Ruby, PHP and Lua. A new language is one row in `packs/base/hooks/lib/languages.mjs`. A folder of kind `copy`, or a glob in `guards.templates.exclude`, is left alone.
+
+Anything used more than once is one template, and it is tested once. `test-the-template-once` says how: test the behaviour on one instance, and prove the rest are that template with a read of the table. `one-walk-per-template` refuses a test that presses every instance.
+
+## Code stays small in every direction
+
+`code-shape` refuses a write that adds a line over 120 columns of code, a line with more than two statements, a function over 50 statements or over 6 parameters. `file-size-guard` holds a file to 300 lines. Code that already stands is judged only if it gets worse. Limits are in `layout.json`: `"guards": { "codeShape": { "maxLineChars": 120, "maxStatementsPerLine": 2, "maxFunctionStatements": 50, "maxParameters": 6, "exclude": [] } }` and `"maxFileLines"`.
+
+## Packs
+
+`list` shows every pack and preset, with its version and author. `base`, `writing` and `hook-proof` come with every configuration.
+
+| Pack | For | Rules | Checks | Hooks | Skills |
+|---|---|---|---|---|---|
+| `ai` | Code that calls a model: untrusted input, explicit keys, model ids | 2 | 4 | 0 | 0 |
+| `audio-core` | Any JUCE synth or effect: realtime safety, DSP quality, state, parameters | 41 | 8 | 2 | 7 |
+| `base` | Universal engineering, in every configuration | 21 | 7 | 18 | 8 |
+| `ci` | CI workflows: every language run, tools pinned, permissions stated | 2 | 2 | 0 | 0 |
+| `content-site` | Sites that publish: complete page heads, one source per page, defended forms, sized media | 4 | 3 | 0 | 1 |
+| `cpp` | Any C++ project: templates, thread contracts, headers, casts, static analysis | 10 | 14 | 0 | 1 |
+| `docker` | Dockerfiles, Compose and Swarm | 5 | 24 | 0 | 1 |
+| `dynamic-data` | Definition-driven systems: a CMS, an admin generator, a low-code platform | 10 | 9 | 0 | 1 |
+| `fastify` | Fastify servers | 6 | 15 | 0 | 0 |
+| `full-stack` | The stack choice: Fastify and Next.js only | 1 | 1 | 1 | 0 |
+| `go` | Go: errors handled, wrapped and never discarded | 1 | 2 | 0 | 0 |
+| `gpu-painter` | GPU-drawn UI on Dawn, with no OpenGL | 15 | 6 | 1 | 6 |
+| `hook-proof` | A hook that should refuse does refuse | 1 | 5 | 0 | 1 |
+| `host-agent` | Software that runs as root on machines it does not own | 1 | 7 | 0 | 0 |
+| `html-ui` | Server-rendered HTML: every value escaped | 2 | 5 | 0 | 0 |
+| `http-api` | Any HTTP server, in any framework: records tied to their caller, guards that fail closed, versioned routes, three layers | 9 | 31 | 0 | 2 |
+| `instrument-shell` | Instruments on a shared shell: sessions that still load, panels that keep every route | 5 | 1 | 0 | 2 |
+| `js-ts` | JavaScript and TypeScript | 27 | 35 | 0 | 0 |
+| `midi` | Clock, sync and sysex, right on the wire and in the audio | 5 | 9 | 0 | 2 |
+| `mongo` | MongoDB with the native driver | 6 | 18 | 0 | 0 |
+| `multi-tenant` | One system, many customers: no role crosses a tenant | 1 | 2 | 0 | 1 |
+| `nginx` | NGINX in front of containers | 2 | 7 | 0 | 1 |
+| `python` | Python: templates, errors, resources, safe subprocess calls | 2 | 11 | 0 | 1 |
+| `react` | React: failed requests, effects, accessible controls | 2 | 6 | 0 | 0 |
+| `reverse-engineering` | Rebuilding a machine from firmware, manuals and banks: the machine's own names first, two sources before naming, every law sourced | 9 | 4 | 1 | 6 |
+| `shell` | Shell scripts: strict mode, quoting, shared functions | 2 | 9 | 0 | 1 |
+| `shell-hooks` | Shell and Node hooks for Claude Code | 1 | 4 | 0 | 0 |
+| `sound-design` | Sound proved by measuring audio: algorithms as data, neutral is exact, the meter first | 6 | 5 | 0 | 4 |
+| `stellix` | Laws of one synth project | 5 | 5 | 1 | 0 |
+| `stored-text` | Text from a database reaches the page through one renderer | 1 | 4 | 0 | 1 |
+| `synth-creator` | The synth-creator configuration's own laws | 6 | 2 | 9 | 2 |
+| `tui` | Terminal UIs | 1 | 5 | 0 | 1 |
+| `ui-craft` | Application and page design in any web stack | 16 | 24 | 0 | 9 |
+| `web` | Web UI: Next.js, HTML, CSS, Tailwind | 8 | 22 | 0 | 5 |
+| `websocket` | WebSocket services: identity from the connection | 1 | 3 | 0 | 0 |
+| `writing` | Text that goes public reads like a person wrote it | 9 | 11 | 0 | 10 |
+| `zod` | Zod 4 schemas written once, in one folder | 2 | 0 | 1 | 0 |
+
+## APIs are versioned, in any framework
+
+`http-api` holds every route under `/api/v<N>/`: `api-path-versioned` reads mounts and routes in any framework, `next-api-route-versioned` reads Next.js route files, and `client-calls-a-version` reads the calls. `apis-are-versioned` says what a version promises: a published version only grows, and a breaking change is a new one with the old kept working behind `Deprecation` and `Sunset` headers. `change-an-api` walks a change. `/health`, auth callbacks and webhooks are left out, since the platform or the provider owns those paths.
+
+## Configurations
+
+A project is one configuration: a kind of project, as data in `configurations/<name>/config.json`. It holds the packs (`always`, `choose`, `default`), the folder template `init` creates, the order of its hooks, what doctor counts as source, and the house rules of its CLAUDE.md block. `.claude/layout.json` `"configuration"` names the project's. With none named, the install takes the configuration that has a chosen pack by default.
+
+| Configuration | For | `init` adds by default |
+|---|---|---|
+| `base` | Universal engineering only, for a project no other configuration fits | nothing |
+| `cpp` | Any C++ project that is not a synth | `cpp` |
+| `go` | Go projects | `go` |
+| `node` | A Node.js or TypeScript service, web app, CLI, library or MCP server | `js-ts` |
+| `python` | Python projects | `python` |
+| `full-stack` | A Fastify API and a Next.js web app, with one schemas folder and one database gateway. It fixes a folder layout, so it is offered and never assumed. It always takes `full-stack`, `http-api`, `fastify`, `zod` and `docker` | `js-ts`, `stored-text`, `ui-craft` |
+| `synth-creator` | JUCE synths and effects | `cpp`, `audio-core` |
+
+```
+npx --no-install @thedecipherist/claude-packs configs                     list them: packs, counts, folder template
+npx --no-install @thedecipherist/claude-packs init --config <name>        install one
+npx --no-install @thedecipherist/claude-packs config <name> [--dry-run]   switch; prints what changes first
+```
+
+## Presets
+
+`init <preset>` installs the packs a stack needs.
+
+| Preset | Packs |
+|---|---|
+| `node-api` | `js-ts`, `http-api`, `mongo`, `fastify`, `ai`, `docker` |
+| `node-ui` | `js-ts`, `http-api`, `mongo`, `fastify`, `html-ui`, `stored-text`, `ui-craft`, `docker` |
+| `next-app` | `js-ts`, `http-api`, `react`, `mongo`, `web`, `stored-text`, `ui-craft`, `ai`, `docker` |
+| `mcp-server` | `js-ts`, `mongo`, `ai`, `shell-hooks` |
+| `node-cli` | `js-ts`, `tui` |
+| `node-lib` | `js-ts` |
+| `edge` | `nginx`, `docker` |
+| `synth` | `cpp`, `audio-core` |
+| `synth-rebuild` | `cpp`, `audio-core`, `reverse-engineering`, `midi`, `sound-design`, `instrument-shell` |
+| `python-app` | `python`, `shell`, `docker` |
+| `shell-tools` | `shell` |
+| `go-app` | `go`, `shell`, `docker`, `ci` |
+
+## Commands
+
+Each is `npx --no-install @thedecipherist/claude-packs <command>`, with `--dir <project>` for another folder.
+
+| Command | What it does |
+|---|---|
+| `suggest` | The configuration and packs this project needs, with the evidence |
+| `scan [--out <file>]` | On a copy: what to install and everything already wrong. `scan --prompt` prints the review brief for what checks cannot see |
+| `fix [--from <scan.json>] [--out <file>]` | The last scan as a work order, `.claude/fix-plan.md`; scans first if there is none |
+| `init [pack...] [--auto]` | Install packs or a preset. `--auto` takes what `suggest` finds; `--config`, `--profile` and `--layout` choose the start |
+| `add <pack...> [--from <git-url>]` | Add packs, a team's own included |
+| `remove <pack...>` | Remove packs; files you edited are kept |
+| `update` | Re-sync installed packs from this version |
+| `update-all <dir...>` | Update every listed project that has the kit |
+| `logs` | Which hooks earn their place: calls, refusals and verdicts per hook. `logs refusals`, `logs mark <id> right\|wrong "<why>"` |
+| `doctor [--strict] [--fresh]` | Verify the install: paths, hooks, selftests, checks' own examples, hook timing |
+| `new <name>` | A new project: the house files, a git repo on a work branch, the kit installed |
+| `new-pack <name> [--repo <git-url>]` | A new repository for a team's own pack |
+| `list` | The packs and presets |
+| `configs` | The configurations |
+| `config <name> [--dry-run]` | Switch configuration |
+| `planner-skills [--out <dir>]` | One project-layout skill body per configuration |
+| `survey` | Print the prompt that makes Claude write `docs/project.md` for tailoring |
+| `shape scan` | Every instance literal in the repo, against `design/shape.json` |
+| `symmetry gen\|run` | The generated gate: every instance has the same members, and every pair swaps the same |
+| `dup scan` | Every duplicated block, by file |
+| `global add\|remove\|doctor` | The global part, below |
+| `lock status\|take\|release` | This repo's own lock, for work on the kit |
+
+## The hooks every project gets
+
+| Hook | When | What it does |
+|---|---|---|
+| `making` | Prompt | Asks what is being made and what it reuses |
+| `reuse-hint` | Prompt | Shows functions the repo already has when the prompt names them |
+| `lesson-checks` | Write | Runs the installed lesson checks on what a write adds |
+| `template-law` | Write | Refuses a copy, a near copy or a function made again |
+| `once-only` | Write | Refuses a duplicate of code as written |
+| `code-shape` | Write | Refuses wide lines, packed lines, long functions, long parameter lists |
+| `file-size-guard` | Write | Refuses a source file past its line limit |
+| `dispatch-once` | Write | Refuses a `switch` on a kind already switched on in another file |
+| `folder-law` | Write | Refuses a new source file outside the layout |
+| `placement-law` | Write | Refuses a kind of thing in the wrong folder |
+| `shape-law` | Write | Refuses a literal instance of a many concept |
+| `brief-guard` | Write | Refuses a brief that names a fixed instance |
+| `secrets-guard` | Write | Refuses a secret in code, or a secret file in git |
+| `untrusted-boundary` | Write | Refuses a model call with outside text and no per-call boundary |
+| `git-guard` | Bash | Refuses a token in git config, and with `house: true` the git laws: stage by name, no rebase or force, branches from the fetched trunk |
+| `suite-once` | Bash | Refuses the whole test suite on uncommitted work |
+| `repo-litter` | Bash | Refuses `git add` of a big file, a working screenshot in the root, or a debug dump |
+| `making-check` | Stop | Sends a turn back when what it wrote is not what it said |
+
+Packs add their own: `realtime-guard` and `param-id-lock` (`audio-core`), `stack-guard` (`full-stack`), `schemas-only` (`zod`), `firmware-out-of-git` (`reverse-engineering`), `browser-guard` (`gpu-painter`), `no-shipped-images` (`stellix`), and the `synth-creator` set: `build-guard`, `time-guard`, `spec-lock`, `frozen-files`, `protect-vendor`, `stage-guard`, and the opt-in `build-sweep`, `idle-wake` and `user-asks`.
+
+Every hook is timed to `.claude/hooks.log`, and `doctor` is red for a median over 500 ms. Nothing is ever cleared: a log past 1 MB moves to `.claude/logs/` under a dated name (`"guards": { "logs": { "maxKb": 1024 } }`). A hook that crashes lets a call through, so `doctor` is red for that too, and the `hook-proof` pack holds hooks to exit 2. Hooks of one entry run in one Node process, through `run-hooks.mjs`.
+
+## Instruments, proved in the audio
+
+Four packs carry what rebuilding classic machines from firmware taught, and most of it is about failures that pass every test: units deaf to the transport, presets silently on defaults, a list of algorithms behind one DSP path.
+
+`reverse-engineering` starts from the machine's own names: `names-sweep` searches an image for what the manual prints, in the forms a display uses and through every wrapping met so far, and reports the record size, the order, the pools and the tables; `menu-map` joins every parameter to the page that reaches it. It needs two sources before anything is named, a source tag on every law and a debt ledger for what was tuned by ear, and it keeps firmware out of git. `midi` holds the law of clock and sync, and treats a program as records that round-trip byte for byte. `sound-design` proves sound by measuring audio. `instrument-shell` keeps sessions loadable and panels reachable. `init synth-rebuild` takes them all.
+
+A project says what it is, in `"guards": { "instrument": { "kind": "reproduction" } }` or `"original"`, because the laws differ: on a reproduction the machine is the spec, aliasing and all.
+
+## Published text is not code
+
+A content folder (`articles/`, `blog/`, `posts/`, `content/`, `tutorials/`, `examples/`, `samples/`) holds text and samples. The writing laws read it. The code laws, `template-law`, `code-shape`, `once-only` and `file-size-guard` leave it alone, and `scan` lists what it finds there apart, so a tutorial's compose file is never a project fault and a sample key never heads the report. Under a code root the word means nothing: `src/app/blog/page.tsx` is code. `"guards": { "content": ["<glob>"] }` adds a project's own.
+
+Dates are facts in an article. The `no-time-or-date` check is opt-in, for an author who wants none in posts, and even then it leaves articles alone.
+
+## Knowing which hooks earn their place
+
+A bug log only records the refusals somebody complained about, so it cannot say whether a hook works. The kit records them all. Every call is a line of `.claude/logs/events.jsonl`: the session, the tool, the file or command, and each hook's time, exit code and reason. Every refusal and crash is also a line of `refusals.jsonl`, with an id, the branch and commit, the kit's version and the hash of the hook that decided. Secrets are masked, and file contents are not kept.
+
+`logs` adds it all up, over every rotated file. `logs mark <id> right|wrong "<why>"` records a verdict. The logs stay out of git by default.
+
+## Where things apply
+
+- **`.claude/layout.json` is the one source of truth.** It names every folder and concept, and what goes where. Move a folder there, run `update`, and every rule follows.
+- **Rules** declare their concepts (`# concepts: dsp, world`); their `paths:` are generated from the layout.
+- **Lesson checks** resolve their concepts from the same file. `whenDep` limits a check to a dependency's major version.
+- **CLAUDE.md** gets a generated "Project layout" section between `<!-- claude-packs:start -->` markers.
+- **Skills** for one area go into that folder's nested `.claude/skills/`, so they only appear once Claude works there.
+- **Hooks judge only this project's files**, and a file in a git worktree by that worktree.
+- **`doctor --strict`** fails on a rule that matches no file and a source file no rule covers.
+
+## It never overwrites your work
+
+- Your own files in `.claude/` are left alone. If a pack file has the same name, the pack's version goes beside it as `<file>.pack-new`.
+- A pack file you edited is kept on every update, with the new version beside it. `--force` replaces edited pack files, never your own files.
+- In `CLAUDE.md`, only the marked section is written. In `settings.json`, only this package's hooks change. A malformed `settings.json` stops the run before anything changes.
+- `layout.json` keeps your edits, and the keys a project owns survive every update.
+- `CLAUDE.md`, `settings.json`, `layout.json` and the lock are backed up to `.claude/.claude-packs-backup/` before every run.
+- Files that leave a pack are removed only if you never edited them.
+
+## Nothing new switches on unless you chose it
+
+A hook or a check refuses work, so a new one never appears in a project by surprise.
+
+- `init` and `add` bring every hook and check of the packs named, except the opt-in ones.
+- `update` brings a hook or check new to the project only when `.claude/layout.json` `"enable"` names it, as in `"enable": ["hooks/template-law.mjs"]`.
+- `update` prints both lists before it changes anything: what is switching on, and what is held back.
+
+## Custom packs: share your own with your team
+
+```
+npx --no-install @thedecipherist/claude-packs new-pack acme-internal --repo git@git.acme.example:team/acme-internal.git
+# edit packs/acme-internal/, push it, then in any project:
+npx --no-install @thedecipherist/claude-packs add acme-internal --from git@git.acme.example:team/acme-internal.git
+```
+
+A pack is rules, checks, hooks and skills in a folder, in a repository of your own. `update` pulls the newest, and the lock records the commit, so teammates get the same pack. Hooks from a custom pack stay off until `"enable"` names them.
+
+A `pack.json` is a manifest like a `package.json`. `name`, `version`, `description`, `type`, `author`, `license` and `repository.url` are required, and `type` is `stock` for the packs in this package and `custom` for anyone else's:
+
+```json
+{
+  "name": "acme-internal",
+  "version": "1.2.0",
+  "description": "What it is for.",
+  "type": "custom",
+  "author": "Acme Platform Team <platform@acme.example>",
+  "license": "UNLICENSED",
+  "repository": { "type": "git", "url": "git@git.acme.example:platform/claude-packs-acme.git" },
+  "engines": { "claude-packs": ">=0.19.0" }
+}
+```
+
+## Fitting a real repo
+
+Run `survey` and give the printed prompt to Claude Code. It writes `docs/project.md`: the real folder tree, where every concern lives, and how the code is built. The layout, concepts and rules are then tuned to it. A new project starts with `new <name>`.
+
+## Working across projects
+
+- This project's hooks judge only this project's files, so an edit in a sibling project is never refused.
+- `layout.siblings` adds sibling folders to `permissions.additionalDirectories`.
+- `update-all ~/projects/*` updates and doctors every project that has the kit, and skips the rest.
+
+## The global part: exactly three pieces
+
+```
+npx --no-install @thedecipherist/claude-packs global add
+npx --no-install @thedecipherist/claude-packs global doctor
+npx --no-install @thedecipherist/claude-packs global remove   # removes only what it installed and you did not edit
+```
+
+Everything else in this package is per project. `global add` installs these into `~/.claude` and nothing else:
+
+1. **latest-versions**, a skill and its `version-pin-guard` hook. Before Claude adds or pins a dependency, it looks up the current release, because that applies to every project. The hook refuses a pin whose row in `docs/versions.md` is over 14 days old.
+2. **gnu-shell**: bash 5 and the GNU tools first on the Bash tool's PATH on macOS and Linux, with a warning in a zsh session.
+3. **shell-traps**: refuses BSD flags, unsplit zsh words and `;`-chained destructive steps.
+
+Global by design: they fix this machine's shell for Claude, not any project's rules.
+
+## Working on the kit
+
+`CLAUDE.md` is the guide. `CHANGELOG.md` has every release, and [docs/history.md](docs/history.md) keeps the notes from earlier versions, with upgrade notes for old installs. `npm test` runs the whole suite, and `test/readme.test.mjs` fails when this page falls behind the packs, the configurations or the commands.
+
+## Credits
+
+The kit learned from [superpowers](https://github.com/obra/superpowers) (MIT), mddkit and MDD, Vercel's Web Interface Guidelines (MIT), Anthropic's frontend-design (Apache 2.0), Impeccable (Apache 2.0), taste-skill and imagegen-skills (MIT). [docs/ui-craft-sources.md](docs/ui-craft-sources.md) says what came from each UI source.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/bin/claude-packs.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// claude-packs: per-project Claude Code rules, checks, hooks and skills for The Decipherist's synths.
+// Everything installs into the project's own .claude/ (and nested skill folders).
+// The one exception is `global`: latest-versions (skill and hook), gnu-shell and shell-traps.
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { doctor } from '../lib/doctor.mjs';
+import { globalAdd, globalDoctor, globalRemove } from '../lib/global.mjs';
+import { lockCommand } from '../lib/kit-lock.mjs';
+import { readLock } from '../lib/manifest.mjs';
+import { newProject } from '../lib/new.mjs';
+import { dupScan } from '../lib/once-only-report.mjs';
+import { PRESETS, availablePacks, readPack } from '../lib/packs.mjs';
+import { describeConfigs, layoutConfiguration, readConfig, switchConfig } from '../lib/config-cli.mjs';
+import { plannerSkills } from '../lib/planner.mjs';
+import { addCustomPack, loadCustomPacks, newPack } from '../lib/custom-packs.mjs';
+import { fixPlan } from '../lib/fix-plan.mjs';
+import { logsCommand } from '../lib/logs.mjs';
+import { scan } from '../lib/scan.mjs';
+import { suggest, suggestionOf } from '../lib/suggest.mjs';
+import { sync } from '../lib/sync.mjs';
+import { ensureShape, isSynth, shapeCommand } from '../lib/shape-cli.mjs';
+
+const HELP = `usage: npx --no-install @thedecipherist/claude-packs <command> [options]
+
+  new <name>         a new project in <dir>/<name>: the house files (CLAUDE.md, build.md, bugs.md,
+                     workflow-bugs.md, docs/versions.md), a git repo on a work/ branch, the kit installed
+                     --packs <a,b>     the packs (default audio-core); --profile <name>, --config <name> as for init
+  init [pack...]     install packs or presets (e.g. init node-api; list shows them); base is always included
+                     and create the layout folders
+                     --config <name>   the configuration (configs lists them; stored in layout.json
+                                       "configuration"); with no packs named, the ones it takes by default
+                     --profile <name>  start from a tailored layout shipped in the package (e.g. stellix)
+                     --layout <file>   start from your own layout.json
+                     --auto            the configuration and packs suggest finds, so nobody picks them by hand
+  add <pack...>      add packs to an existing install
+                     --from <git-url>  a custom pack from a team's repository; its hooks stay off until "enable" names them
+  new-pack <name> [--repo <git-url>]  a new repository for a team's own pack, ready to edit and push
+  remove <pack...>   remove packs (files you edited are kept)
+  update             re-sync installed packs from this package version, in the project's configuration
+  configs            list the configurations: what each installs, its packs and its folder template
+  config <name>      switch this project to another configuration; prints what changes first
+                     --dry-run         print what would change and stop
+  planner-skills [--out <dir>]   one project-layout skill body per configuration, from its layout template
+                     (printed, or written to <dir>/<configuration>/project-layout/SKILL.md)
+  update-all <dir...>  update every listed project that already has claude-packs
+                     (e.g. update-all ~/projects/*); folders without it are skipped
+  doctor [--strict] [--fresh]  verify the install (paths, folders, hooks, checks' own examples); a hook's selftest that
+                     passed is not run again until the hook changes (--fresh runs them all); --strict also fails
+                     when a rule matches no file or a source file is covered by no rule
+  shape scan         every instance literal in the repo (code, tests, docs, briefs), by file and concept,
+                     with a count, against design/shape.json; exit 1 when any
+  scan [--out <file>]  before installing anything: on a copy of the project, what to install and every issue the checks
+                     find; the project is never touched. scan --prompt prints the review brief for what checks cannot see
+  suggest            which configuration and packs this project needs, read from its own files, with the evidence
+  fix [--from <scan.json>] [--out <file>]  the last scan as a work order for Claude, .claude/fix-plan.md; scans first if there is none
+  logs               which hooks earn their place: calls, refusals and verdicts per hook, over all the history
+                     logs refusals [--hook <h>] [--open]; logs mark <id> right|wrong "<why>"
+  survey             print the prompt that makes Claude write docs/project.md for tailoring
+  list               show available packs
+  symmetry gen --cmake <out.cmake> | --list   the generated gate shape_symmetry: one test per many concept in
+                     design/shape.json (add_test lines a CMakeLists includes at configure time, or plain lines)
+  symmetry run <concept>   that gate for one concept: every instance the same members, every pair swaps the same
+  dup scan           every duplicated block (jscpd, the once-only hook's detector), listed by file
+  lock status|take [--branch <b>]|release [--force]
+                     the claude-packs repo's kit lock, a lease, in each checkout: who holds it, since when, last seen,
+                     live or stale (30 min without renewal); take takes it for this session (a stale one is taken over
+                     and logged); release takes away your own lock or a stale one, never a live lease without --force
+  global add|remove|doctor
+                     the global part, exactly three pieces: latest-versions (skill and
+                     version-pin-guard), gnu-shell, shell-traps, in ~/.claude (never
+                     overwrites; --home <dir> to target another home)
+
+options: --dir <project> (default: current folder)   --force (replace files you edited)`;
+
+function parse(argv) {
+  const opts = { dir: process.cwd(), force: false, strict: false, rest: [], seed: null, home: undefined, packs: null, config: null, dryRun: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--dir') opts.dir = argv[++i];
+    else if (argv[i] === '--packs') opts.packs = argv[++i].split(',').map((p) => p.trim()).filter(Boolean);
+    else if (argv[i] === '--profile') opts.seed = fileURLToPath(new URL(`../profiles/${argv[++i]}.layout.json`, import.meta.url));
+    else if (argv[i] === '--layout') opts.seed = resolve(argv[++i]);
+    else if (argv[i] === '--config') opts.config = argv[++i];
+    else if (argv[i] === '--dry-run') opts.dryRun = true;
+    else if (argv[i] === '--force') opts.force = true;
+    else if (argv[i] === '--strict') opts.strict = true;
+    else if (argv[i] === '--fresh') opts.fresh = true;
+    else if (argv[i] === '--home') opts.home = resolve(argv[++i]);
+    else opts.rest.push(argv[i]);
+  }
+  opts.dir = resolve(opts.dir);
+  return opts;
+}
+
+async function main() {
+  const [command, ...argv] = process.argv.slice(2);
+  const { dir, force, strict, fresh, rest, seed, home, packs, config, dryRun } = parse(argv);
+  const seedLayout = seed ? JSON.parse(readFileSync(seed, 'utf8')) : null;
+  const installed = readLock(resolve(dir, '.claude')).packs;
+  const fromUrl = rest.includes('--from') ? rest.splice(rest.indexOf('--from'), 2)[1] : null;
+  const fetched = ['new-pack', 'scan', 'suggest', 'fix', 'logs', 'global'].includes(command) ? {} : loadCustomPacks(dir, { latest: command === 'update' });
+
+  switch (command) {
+    case 'new':
+      return (await newProject(dir, rest[0], { packs: packs ?? (config ? readConfig(config).packs.default : ['audio-core']), seedLayout, config })).code;
+    case 'init': {
+      if (rest.includes('--auto')) {
+        const pick = suggestionOf(dir);
+        await sync(dir, pick.packs.map((p) => p.pack), { force, mkdirs: true, seedLayout, config: pick.config });
+        return doctor(dir);
+      }
+      if (rest.length === 0 && !config) throw new Error('name at least one pack or a configuration, e.g. `init audio-core` or `init --config base` (`configs` lists them)');
+      const chosen = rest.length ? rest : readConfig(config).packs.default;
+      await sync(dir, chosen, { force, mkdirs: true, seedLayout, config });
+      if (isSynth(chosen) && ensureShape(dir)) console.log('  design/shape.json: written empty; add a row per concept (one or many) before building it');
+      return doctor(dir);
+    }
+    case 'planner-skills':
+      return plannerSkills(rest.includes('--out') ? resolve(rest[rest.indexOf('--out') + 1]) : null);
+    case 'configs':
+      console.log(describeConfigs(layoutConfiguration(dir)));
+      return 0;
+    case 'config':
+      return switchConfig(dir, rest[0], installed, { force, dryRun });
+    case 'add': {
+      const sources = fromUrl ? { ...fetched, [rest[0]]: addCustomPack(rest[0], fromUrl) } : fetched;
+      await sync(dir, [...installed, ...rest], { force, mkdirs: true, sources });
+      return doctor(dir);
+    }
+    case 'remove':
+      await sync(dir, installed.filter((p) => p === 'base' || !rest.includes(p)), { force });
+      return doctor(dir);
+    case 'update':
+      if (installed.length === 0) throw new Error('nothing installed here; run init first');
+      await sync(dir, installed, { force, mkdirs: true, sources: fetched });
+      return doctor(dir);
+    case 'update-all': {
+      let failed = 0;
+      for (const d of rest.map((x) => resolve(x))) {
+        const lockPacks = readLock(resolve(d, '.claude')).packs;
+        if (lockPacks.length === 0) continue;
+        console.log(`\n== ${d}`);
+        try {
+          await sync(d, lockPacks, { force, mkdirs: true });
+          failed += await doctor(d);
+        } catch (e) {
+          failed += 1;
+          console.log(`  PROBLEM: ${e.message}`);
+        }
+      }
+      return failed ? 1 : 0;
+    }
+    case 'doctor':
+      return doctor(dir, console.log, { strict, fresh });
+    case 'shape':
+      return shapeCommand(rest[0], dir);
+    case 'scan':
+      if (rest.includes('--prompt')) { process.stdout.write(readFileSync(fileURLToPath(new URL('../prompts/scan-review.md', import.meta.url)), 'utf8')); return 0; }
+      await scan(dir, { out: rest.includes('--out') ? resolve(rest[rest.indexOf('--out') + 1]) : null });
+      return 0;
+    case 'logs':
+      return logsCommand(dir, rest);
+    case 'suggest':
+      suggest(dir);
+      break;
+    case 'fix':
+      await fixPlan(dir, { from: fromUrl ? resolve(fromUrl) : null, out: rest.includes('--out') ? resolve(rest[rest.indexOf('--out') + 1]) : null });
+      break;
+    case 'new-pack':
+      return newPack(dir, rest[0], { repo: rest.includes('--repo') ? rest[rest.indexOf('--repo') + 1] : null });
+    case 'survey':
+      process.stdout.write(readFileSync(fileURLToPath(new URL('../prompts/survey.md', import.meta.url)), 'utf8'));
+      return 0;
+    case 'global': {
+      const run = { add: globalAdd, remove: globalRemove, doctor: globalDoctor }[rest[0]];
+      if (!run) throw new Error('use `global add`, `global remove` or `global doctor`');
+      return run({ home, force });
+    }
+    case 'symmetry':
+      return (await import('../packs/base/tools/shape-symmetry.mjs')).main([...rest, '--dir', dir]);
+    case 'dup':
+      if (rest[0] !== 'scan') throw new Error('use `dup scan [--dir <project>]`');
+      return dupScan(dir);
+    case 'lock':
+      return lockCommand(rest[0], dir, { force, branch: rest.includes('--branch') ? rest[rest.indexOf('--branch') + 1] : undefined });
+    case 'list':
+      for (const name of availablePacks()) { const p = readPack(name); console.log(`${name.padEnd(14)}${p.version.padEnd(8)}${p.type.padEnd(7)}${p.author}: ${p.description}`); }
+      console.log('\npresets (init <preset> installs the packs that stack needs):');
+      for (const [name, packs] of Object.entries(PRESETS)) console.log(`${name.padEnd(12)} ${packs.join(', ')}`);
+      return 0;
+    default:
+      console.log(HELP);
+      return command ? 2 : 0;
+  }
+}
+
+main().then(
+  (code) => process.exit(code ?? 0),
+  (err) => {
+    console.error(`claude-packs: ${err.message}`);
+    process.exit(2);
+  },
+);

package/configurations/base/config.json

@@ -0,0 +1,85 @@
+{
+  "name": "base",
+  "description": "Universal engineering only: the git laws, the line limit, the folder and placement laws, the shape law, once-only, making, secrets and the untrusted-content boundary. For a project no other configuration fits.",
+  "packs": {
+    "always": [
+      "base",
+      "writing",
+      "hook-proof"
+    ],
+    "choose": [
+      "shell",
+      "ci",
+      "docker",
+      "web",
+      "ui-craft",
+      "content-site", "reverse-engineering"
+    ],
+    "default": []
+  },
+  "layout": {
+    "folders": {
+      "docs": {
+        "path": "docs",
+        "purpose": "spec, laws, licences, work orders, decisions"
+      },
+      "src": {
+        "path": "src",
+        "purpose": "all source code, only inside the subfolders below"
+      },
+      "tests": {
+        "path": "tests",
+        "purpose": "unit tests, gates with planted faults, golden files"
+      },
+      "tools": {
+        "path": "tools",
+        "purpose": "scripts and research tooling (not shipped)"
+      }
+    },
+    "kinds": {
+      "tests": {
+        "what": "tests, gates with planted faults, golden renders",
+        "in": "tests",
+        "concepts": [
+          "tests"
+        ],
+        "files": [
+          "**/*_test.*",
+          "**/*Test.cpp",
+          "**/*Tests.cpp",
+          "**/test_*.*",
+          "**/*.test.*"
+        ]
+      },
+      "docs": {
+        "what": "the spec, laws.md, decisions, research, work orders",
+        "in": "docs",
+        "concepts": [
+          "docs-folder"
+        ],
+        "files": [
+          "**/laws.md",
+          "**/*-spec.md"
+        ]
+      },
+      "tools": {
+        "what": "scripts and research tools that never ship",
+        "in": "tools"
+      }
+    }
+  },
+  "preamble": {
+    "always": [
+      "Ask the user before inventing a new folder. A new folder goes into `.claude/layout.json` first.",
+      "When a hook, check or guard blocks work that is correct, stop and report its exact message. A blocking hook is a red check: fix the hook first, with a selftest, then continue.",
+      "When a command is refused or fails, the step fails loudly. Never report a refused write or a failed command as done.",
+      "claude-packs (`~/projects/claude-packs`) is the source of truth for every rule, check, hook and skill this project's configuration installs. A fix to one of them is made there with its test, committed, pushed and released as a new version, then taken in with `npx --no-install @thedecipherist/claude-packs update`. A project edits its installed copy only to try a fix before it goes into the kit."
+    ],
+    "never": [
+      "Create source files outside these folders, or put a kind of thing anywhere but its place. The folder-law and placement-law hooks refuse both.",
+      "Edit files in `.claude/rules`, `.claude/checks` or `.claude/hooks` to get past a block. Fix the code, or ask the user to change the law.",
+      "Route around a block: no override variables, no writing through the shell after a refusal, no parking files in a scratchpad, no putting new code into an unrelated existing file.",
+      "Point at a document by line number. Cite a fixed anchor (`{#id}`) or a symbol name; lines move."
+    ]
+  }
+}