@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/bin/claude-packs.mjs

@@ -0,0 +1,212 @@
+#!/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 { detectedConfig, suggest, suggestionOf } from '../lib/suggest.mjs';
+import { newWorkorder } from '../lib/workorder.mjs';
+import { sync } from '../lib/sync.mjs';
+import { ensureShape, isSynth, shapeCommand } from '../lib/shape-cli.mjs';
+
+const INSTALLING = { installing: true }; // doctor at the end of an install: what the project has yet to do is a note
+
+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 base alone); --profile <name>, --config <name> as for init
+  workorder <name>   a work order in docs/workorders/<name>: the steps, the prompt that runs them with nobody
+                     there, and a runner that starts session after session
+  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>"
+                     logs crashes; logs clear <hook>|all fixed|superseded "<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 : ['base']), seedLayout, config })).code;
+    case 'workorder':
+      return newWorkorder(dir, rest[0]);
+    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, console.log, INSTALLING);
+      }
+      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: config ?? detectedConfig(dir, chosen) });
+      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, console.log, INSTALLING);
+    }
+    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, console.log, INSTALLING);
+    }
+    case 'remove':
+      await sync(dir, installed.filter((p) => p === 'base' || !rest.includes(p)), { force });
+      return doctor(dir, console.log, INSTALLING);
+    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, console.log, INSTALLING);
+    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, console.log, INSTALLING);
+        } 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 (`@thedecipherist/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 in the kit, with its test, and comes here 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."
+    ]
+  }
+}

package/configurations/cpp/config.json

@@ -0,0 +1,93 @@
+{
+  "name": "cpp",
+  "description": "Any C++ project that is not a synth: universal engineering and the cpp pack, with what is repeated made one template.",
+  "packs": {
+    "always": [
+      "base",
+      "writing",
+      "hook-proof"
+    ],
+    "choose": [
+      "cpp",
+      "docker",
+      "shell-hooks",
+      "python",
+      "shell",
+      "ci",
+      "go",
+      "rust",
+      "reverse-engineering",
+      "midi",
+      "sound-design"
+    ],
+    "default": [
+      "cpp"
+    ]
+  },
+  "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 (`@thedecipherist/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 in the kit, with its test, and comes here 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."
+    ]
+  },
+  "sourceFiles": "\\.(?:c|cc|cpp|cxx|h|hh|hpp|mm)$"
+}

package/configurations/full-stack/config.json

@@ -0,0 +1,153 @@
+{
+  "name": "full-stack",
+  "description": "A web service: a Fastify API and a Next.js web app in one repo, Zod 4 schemas in one shared folder, one database gateway, one error contract.",
+  "packs": {
+    "always": [
+      "base",
+      "full-stack",
+      "http-api",
+      "fastify",
+      "zod",
+      "docker",
+      "writing",
+      "hook-proof"
+    ],
+    "choose": [
+      "js-ts",
+      "stored-text",
+      "ui-craft",
+      "shell",
+      "react",
+      "multi-tenant",
+      "websocket",
+      "ci",
+      "dynamic-data",
+      "mongo",
+      "postgres",
+      "ai",
+      "nginx",
+      "content-site"
+    ],
+    "default": [
+      "js-ts",
+      "stored-text",
+      "ui-craft"
+    ]
+  },
+  "layout": {
+    "folders": {
+      "core": {
+        "path": "packages/core/src",
+        "purpose": "shared code the API and the web app both import"
+      },
+      "schemas": {
+        "path": "packages/core/src/schemas",
+        "purpose": "every Zod 4 schema: requests, responses, records, forms, the error contract"
+      },
+      "api": {
+        "path": "api/src",
+        "purpose": "the Fastify API: buildServer(), env.ts, the error handler, plugins"
+      },
+      "routes": {
+        "path": "api/src/routes",
+        "purpose": "thin routes: method, path, schemas, one handler call"
+      },
+      "handlers": {
+        "path": "api/src/handlers",
+        "purpose": "the work of each route, through adapters"
+      },
+      "adapters": {
+        "path": "api/src/adapters",
+        "purpose": "the one database gateway and every other outside service"
+      },
+      "auth": {
+        "path": "api/src/auth",
+        "purpose": "authentication and the request's identity (the chain keys come from here)"
+      },
+      "api-tests": {
+        "path": "api/test",
+        "purpose": "API tests through inject()"
+      },
+      "channel": {
+        "path": "channel",
+        "purpose": "the Next.js web app"
+      },
+      "docs": {
+        "path": "docs",
+        "purpose": "the spec, decisions, versions.md"
+      },
+      "tools": {
+        "path": "tools",
+        "purpose": "scripts that never ship"
+      }
+    },
+    "concepts": {
+      "js": [
+        "core",
+        "api",
+        "channel",
+        "api-tests"
+      ]
+    },
+    "kinds": {
+      "schema": {
+        "what": "a Zod schema (z.object) and the error contract",
+        "in": "schemas",
+        "concepts": [
+          "schemas",
+          "env"
+        ],
+        "content": "\\bz\\.(?:object|strictObject|looseObject)\\s*\\(",
+        "extensions": [
+          ".ts",
+          ".tsx",
+          ".mts",
+          ".cts",
+          ".js",
+          ".jsx",
+          ".mjs",
+          ".cjs"
+        ]
+      },
+      "db-gateway": {
+        "what": "the database driver and its one gateway",
+        "in": "adapters",
+        "concepts": [
+          "adapters",
+          "api-tests"
+        ],
+        "content": "\\bfrom\\s+['\"](?:mongodb|pg|mysql2|mongoose|@prisma/client|drizzle-orm[^'\"]*|ioredis|redis)['\"]",
+        "extensions": [
+          ".ts",
+          ".tsx",
+          ".mts",
+          ".cts",
+          ".js",
+          ".jsx",
+          ".mjs",
+          ".cjs"
+        ]
+      },
+      "api-test": {
+        "what": "API tests (inject(), never a bound port)",
+        "in": "api-tests"
+      }
+    }
+  },
+  "sourceFiles": "\\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs)$",
+  "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 (`@thedecipherist/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 in the kit, with its test, and comes here 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.",
+      "Put a database call outside the adapters, a Zod schema outside the schemas folder, or business rules in a route.",
+      "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."
+    ]
+  }
+}

package/configurations/go/config.json

@@ -0,0 +1,98 @@
+{
+  "name": "go",
+  "description": "Go projects: universal engineering and the go pack.",
+  "packs": {
+    "always": [
+      "base",
+      "writing",
+      "hook-proof"
+    ],
+    "choose": [
+      "go",
+      "rust",
+      "shell",
+      "docker",
+      "postgres",
+      "http-api",
+      "multi-tenant",
+      "websocket",
+      "host-agent",
+      "ci",
+      "js-ts",
+      "python",
+      "dynamic-data",
+      "web",
+      "ui-craft",
+      "content-site"
+    ],
+    "default": [
+      "go"
+    ]
+  },
+  "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 (`@thedecipherist/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 in the kit, with its test, and comes here 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."
+    ]
+  },
+  "sourceFiles": "\\.go$"
+}