@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/lib/logs.mjs

@@ -0,0 +1,69 @@
+// claude-packs logs: which hooks earn their place. Reads every log, rotated ones included, and joins each refusal to its verdict.
+//   logs                                 per hook: calls, refusals, right, wrong, not judged, crashes, time
+//   logs refusals [--hook <h>] [--open]  every refusal with its reason (--open: not judged yet)
+//   logs mark <id> right|wrong "<why>"   the verdict, added to .claude/logs/verdicts.jsonl; nothing is rewritten
+import { appendFileSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const DIR = join('.claude', 'logs');
+
+function linesOf(dir, name) {
+  const logs = join(dir, DIR);
+  let files = [];
+  try { files = readdirSync(logs).filter((f) => f === `${name}.jsonl` || (f.startsWith(`${name}-`) && f.endsWith('.jsonl'))).sort(); } catch { return []; }
+  return files.flatMap((f) => readFileSync(join(logs, f), 'utf8').split('\n').filter(Boolean).flatMap((l) => { try { return [JSON.parse(l)]; } catch { return []; } }));
+}
+
+const verdictsOf = (dir) => new Map(linesOf(dir, 'verdicts').map((v) => [v.id, v]));
+const middle = (list) => [...list].sort((a, b) => a - b)[Math.floor(list.length / 2)] ?? 0;
+
+// A refusal followed by a pass on the same file in the same session: the writer changed something and went on.
+function passedAfter(refusal, events) {
+  return events.some((e) => e.t > refusal.t && e.session === refusal.session && e.file && e.file === refusal.file && e.hooks.some((h) => h.hook === refusal.hook && h.code === 0));
+}
+
+export function logsSummary(dir) {
+  const events = linesOf(dir, 'events');
+  const refusals = linesOf(dir, 'refusals');
+  const verdicts = verdictsOf(dir);
+  const rows = new Map();
+  const row = (hook) => { if (!rows.has(hook)) rows.set(hook, { hook, calls: 0, refused: 0, crashed: 0, right: 0, wrong: 0, open: 0, passedAfter: 0, ms: [] }); return rows.get(hook); };
+  for (const e of events) for (const h of e.hooks ?? []) { const r = row(h.hook); r.calls += 1; r.ms.push(h.ms); }
+  for (const f of refusals) {
+    const r = row(f.hook);
+    if (f.code !== 2) { r.crashed += 1; continue; }
+    r.refused += 1;
+    const v = verdicts.get(f.id)?.verdict;
+    if (v === 'right') r.right += 1; else if (v === 'wrong') r.wrong += 1; else r.open += 1;
+    if (passedAfter(f, events)) r.passedAfter += 1;
+  }
+  return { first: events[0]?.t, last: events.at(-1)?.t, calls: events.length, rows: [...rows.values()].sort((a, b) => b.refused - a.refused || b.calls - a.calls) };
+}
+
+export function logsCommand(dir, rest, log = console.log) {
+  const [sub] = rest;
+  if (sub === 'mark') {
+    const [, id, verdict, ...why] = rest;
+    if (!id || !['right', 'wrong'].includes(verdict) || !why.length) throw new Error('use `logs mark <id> right|wrong "<why>"`');
+    if (!linesOf(dir, 'refusals').some((r) => r.id === id)) throw new Error(`no refusal ${id}: \`logs refusals\` lists them`);
+    mkdirSync(join(dir, DIR), { recursive: true });
+    appendFileSync(join(dir, DIR, 'verdicts.jsonl'), `${JSON.stringify({ id, verdict, why: why.join(' '), t: new Date().toISOString() })}\n`);
+    log(`${id}: ${verdict}`);
+    return 0;
+  }
+  if (sub === 'refusals') {
+    const hook = rest.includes('--hook') ? rest[rest.indexOf('--hook') + 1] : null;
+    const verdicts = verdictsOf(dir);
+    const list = linesOf(dir, 'refusals').filter((r) => (!hook || r.hook === hook) && (!rest.includes('--open') || !verdicts.has(r.id)));
+    for (const r of list) log(`${r.id} ${r.t} ${r.hook} ${verdicts.get(r.id)?.verdict ?? 'not judged'}\n  ${r.file ?? r.command ?? r.tool ?? '-'}\n  ${(r.reason ?? '').split('\n')[0]}`);
+    log(`${list.length} refusal(s)`);
+    return 0;
+  }
+  const s = logsSummary(dir);
+  if (!s.calls) { log('no calls logged yet (.claude/logs/ fills as the hooks run)'); return 0; }
+  log(`${s.calls} calls, ${s.first} to ${s.last}`);
+  log(`${'hook'.padEnd(24)}${'calls'.padStart(7)}${'refused'.padStart(8)}${'right'.padStart(6)}${'wrong'.padStart(6)}${'open'.padStart(6)}${'fixed'.padStart(6)}${'crash'.padStart(6)}${'ms'.padStart(6)}`);
+  for (const r of s.rows) log(`${r.hook.padEnd(24)}${String(r.calls).padStart(7)}${String(r.refused).padStart(8)}${String(r.right).padStart(6)}${String(r.wrong).padStart(6)}${String(r.open).padStart(6)}${String(r.passedAfter).padStart(6)}${String(r.crashed).padStart(6)}${String(middle(r.ms)).padStart(6)}`);
+  log('fixed: the same file passed the same hook later in that session. Judge the open ones: `logs refusals --open`, then `logs mark <id> right|wrong "<why>"`.');
+  return 0;
+}

package/lib/manifest.mjs

@@ -0,0 +1,24 @@
+// Tracks every file the packs installed, with its hash, so updates never overwrite a file
+// The user changed and files removed from a pack are cleaned up.
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const LOCK = 'claude-packs.lock.json';
+
+export const hashFile = (path) => createHash('sha256').update(readFileSync(path)).digest('hex');
+
+export function readLock(claudeDir) {
+  const p = join(claudeDir, LOCK);
+  return existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : { packs: [], files: {} };
+}
+
+export function writeLock(claudeDir, lock) {
+  writeFileSync(join(claudeDir, LOCK), JSON.stringify(lock, null, 2) + '\n');
+}
+
+// A managed file is "modified" when it exists and no longer matches the hash we wrote.
+export function isModified(projectDir, rel, lock) {
+  const abs = join(projectDir, rel);
+  return existsSync(abs) && lock.files[rel] !== undefined && hashFile(abs) !== lock.files[rel];
+}

package/lib/new.mjs

@@ -0,0 +1,49 @@
+// `claude-packs new <name>`: a new project on the house structure, so the rules fire from the first file (it was the
+// global new-project skill; it is a kit command now, and the global part stays at three pieces).
+//   - the folder, the house files (CLAUDE.md, build.md, bugs.md, workflow-bugs.md, docs/versions.md, .gitignore),
+//   - a git repo: the scaffold is the first commit on main, and work goes on from a `work/` branch (the house branch flow),
+//   - the kit installed into it (`init` with the packs named, or a profile), then doctor.
+// A synth or effects unit is made by synthkit's new_synth.py first; `init` (or `new` on an empty folder) follows on it.
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { doctor } from './doctor.mjs';
+import { sync } from './sync.mjs';
+import { ensureShape } from './shape-cli.mjs';
+
+const today = () => new Date().toISOString().slice(0, 10);
+
+function files(name) {
+  return {
+    'CLAUDE.md': `# ${name}\n\nRead \`build.md\` at the start of every session; nothing is worked on unless it is IN PROGRESS there. Every bug is logged in \`bugs.md\` (and every workflow fault in \`workflow-bugs.md\`) before it is fixed. One branch per step (the \`build-step\` skill), never a commit on main.\n`,
+    'build.md': `# ${name}: the build\n\n## Rules for this file\n\n- A step is ticked only when its "done when" was measured or seen in the opened app.\n- Every step is built on its own branch and merged when done; its start and finish are in the log.\n\n## Where we are\n\nStarted ${today()}.\n\n## In progress\n\n## Steps\n\n## Log\n`,
+    'bugs.md': `# ${name}: bugs\n\nLogged first, fixed second. A fixed bug moves to Fixed with its cause, the fix, the date and the gate that catches it.\n\n## Open\n\n## Fixed\n`,
+    'workflow-bugs.md': `# ${name}: workflow bugs\n\nA fault in the workflow (a hook, a tool, a test run) is logged here before it is fixed.\n\n## Open\n\n## Fixed\n`,
+    'docs/versions.md': '| name | latest stable | checked | source | used | decision |\n|---|---|---|---|---|---|\n',
+    '.gitignore': 'build/\nout/\n.DS_Store\n',
+  };
+}
+
+export async function newProject(parent, name, { packs = ['audio-core'], seedLayout = null, config = null, log = console.log } = {}) {
+  if (!name || !/^[\w.-]+$/.test(name)) throw new Error('name the project: `npx --no-install @thedecipherist/claude-packs new <name>` (letters, digits, . _ -)');
+  const dir = join(parent, name);
+  if (existsSync(dir) && readdirSync(dir).length) throw new Error(`${dir} already exists and is not empty; use \`npx --no-install @thedecipherist/claude-packs init\` there`);
+  mkdirSync(join(dir, 'docs'), { recursive: true });
+  for (const [rel, text] of Object.entries(files(name))) writeFileSync(join(dir, rel), text);
+  const git = (...a) => execFileSync('git', a, { cwd: dir, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' });
+  git('init', '-q', '-b', 'main');
+  await sync(dir, packs, { mkdirs: true, seedLayout, config, log });
+  ensureShape(dir); // the shape law: every concept is written down as ONE or MANY before it is built
+  try {
+    // by name: the house files, .claude/, and every file the kit installed elsewhere (nested skills, .clang-tidy)
+    const installed = Object.keys(JSON.parse(readFileSync(join(dir, '.claude', 'claude-packs.lock.json'), 'utf8')).files);
+    git('add', '--', ...Object.keys(files(name)), 'design/shape.json', '.claude', ...installed, ...(existsSync(join(dir, '.clang-tidy')) ? ['.clang-tidy'] : []));
+    git('commit', '-q', '-m', `${name}: the house structure and claude-packs`);
+    git('switch', '-q', '-c', 'work/start');
+    log(`  git: the scaffold is the first commit on main; you are on work/start`);
+  } catch (e) {
+    log(`  git: the scaffold is not committed (${String(e.stderr ?? e.message).trim().split('\n')[0]}); commit it, then work on a work/ branch`);
+  }
+  log(`New project: ${dir}`);
+  return { dir, code: await doctor(dir, log) };
+}

package/lib/once-only-report.mjs

@@ -0,0 +1,54 @@
+// What doctor prints for the making and once-only hooks (0.9.0 items 6 and 9), and `claude-packs dup scan`.
+//   onceOnlyDoctor(projectDir, log) -> [problem]   the making text's cost per turn; the repo's duplicate count, which can
+//       only go down: the lowest count seen is kept in .claude/state/duplicates.json and a higher one is a problem.
+//   dupScan(dir, log) -> exit code                  every duplicate, listed by file (both sides of each), and the count.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { findJscpd, repoClones } from '../packs/base/hooks/lib/dup.mjs';
+import { readShape } from '../packs/base/hooks/lib/shape.mjs';
+
+const layoutOf = (dir) => { try { return JSON.parse(readFileSync(join(dir, '.claude', 'layout.json'), 'utf8')); } catch { return {}; } };
+
+// The project's detector, else the kit's own, for this process and every selftest it starts.
+export function useJscpd(dir) {
+  const found = findJscpd([dir]);
+  if (found) process.env.CLAUDE_PACKS_JSCPD ??= found;
+  return found;
+}
+
+export function onceOnlyDoctor(projectDir, log = console.log) {
+  const problems = [];
+  const hooks = join(projectDir, '.claude', 'hooks');
+  if (existsSync(join(hooks, 'making.mjs'))) {
+    const r = spawnSync(process.execPath, [join(hooks, 'making.mjs'), '--cost'], { encoding: 'utf8', env: { ...process.env, CLAUDE_PROJECT_DIR: projectDir } });
+    log(`  ${(r.stdout || `making: --cost failed (${r.stderr.split('\n')[0]})`).trim()}`);
+  }
+  if (!existsSync(join(hooks, 'once-only.mjs'))) return problems;
+  if (!useJscpd(projectDir)) return [`once-only has no detector: jscpd not found (an optional dependency of the kit; npm install it, or set CLAUDE_PACKS_JSCPD)`];
+  const r = repoClones(projectDir, { layout: layoutOf(projectDir), shape: readShape(projectDir) });
+  if (r.error) return [`once-only: ${r.error}`];
+  const n = r.clones.length;
+  const file = join(projectDir, '.claude', 'state', 'duplicates.json');
+  let st = null;
+  try { st = JSON.parse(readFileSync(file, 'utf8')); } catch { /* first count */ }
+  log(`  duplicates: ${n} (jscpd, ${r.sources} sources, ${r.ms} ms; \`npx --no-install @thedecipherist/claude-packs dup scan\` lists them)${st ? `, lowest seen ${st.lowest}` : ''}`);
+  if (st && n > st.lowest) problems.push(`duplicates went up from ${st.lowest} to ${n}: the count only goes down (\`npx --no-install @thedecipherist/claude-packs dup scan\` lists them)`);
+  if (!st || n < st.lowest) {
+    mkdirSync(join(projectDir, '.claude', 'state'), { recursive: true });
+    writeFileSync(file, `${JSON.stringify({ lowest: n, at: new Date().toISOString() }, null, 2)}\n`);
+  }
+  return problems;
+}
+
+export function dupScan(dir, log = console.log) {
+  if (!useJscpd(dir)) { log('jscpd not found (an optional dependency of the kit; npm install it, or set CLAUDE_PACKS_JSCPD)'); return 2; }
+  const r = repoClones(dir, { layout: layoutOf(dir), shape: readShape(dir) });
+  if (r.error) { log(r.error); return 2; }
+  const byFile = new Map();
+  const add = (s, o, c) => { if (!byFile.has(s.file)) byFile.set(s.file, []); byFile.get(s.file).push(`  ${s.start}-${s.end}  same as ${o.file}:${o.start}-${o.end}  (${c.lines} lines, ${c.tokens} tokens)`); };
+  for (const c of r.clones) { add(c.a, c.b, c); if (c.b.file !== c.a.file) add(c.b, c.a, c); }
+  for (const f of [...byFile.keys()].sort()) { log(f); for (const l of byFile.get(f).sort((x, y) => parseInt(x, 10) - parseInt(y, 10))) log(l); }
+  log(`${r.clones.length} duplicate(s) in ${byFile.size} file(s) (${r.sources} sources scanned; both sides inside copy trees left out)`);
+  return 0;
+}

package/lib/pack-manifest.mjs

@@ -0,0 +1,20 @@
+// A pack.json is a manifest like a package.json (0.19.0: it says stock or custom, has a git url, and who made it). A custom pack comes
+// from somebody else's repository, so these fields are how a project knows what it is running: what it is, who made it, where it lives.
+const TYPES = ['stock', 'custom'];
+const SEMVER = /^\d+\.\d+\.\d+(?:-[\w.]+)?$/;
+const GIT_URL = /^(?:https?:\/\/|ssh:\/\/|file:\/\/|git@)\S+$/;
+
+const FIELDS = {
+  version: (p) => SEMVER.test(p.version ?? '') || 'needs a version like 1.2.0',
+  description: (p) => Boolean(p.description?.trim()) || 'needs a description',
+  type: (p) => TYPES.includes(p.type) || `needs a type: ${TYPES.join(' or ')}`,
+  author: (p) => Boolean(String(p.author?.name ?? p.author ?? '').trim()) || 'needs an author: who made it',
+  license: (p) => Boolean(p.license?.trim()) || 'needs a license',
+  repository: (p) => GIT_URL.test(p.repository?.url ?? '') || 'needs repository.url: the git url it lives at',
+};
+
+// The problems of one manifest; `folder` is where it was found, and its name must say the same.
+export function manifestProblems(pack, folder = pack.name) {
+  const said = Object.values(FIELDS).map((check) => check(pack)).filter((r) => r !== true).map((r) => `pack ${folder} ${r}`);
+  return pack.name === folder ? said : [`pack ${folder} says its name is ${pack.name}`, ...said];
+}

package/lib/packs.mjs

@@ -0,0 +1,107 @@
+// Reads the packs shipped in this npm package and plans which file goes where in a project.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const PACKS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'packs');
+const CLAUDE_DIRS = ['rules', 'checks', 'hooks', 'tools'];
+
+// Packs from a team's own repository (lib/custom-packs.mjs): name -> the folder it was fetched to.
+const CUSTOM = new Map();
+export const registerPack = (name, folder) => CUSTOM.set(name, folder);
+export const customPacks = () => [...CUSTOM.keys()];
+export const packRoot = (name) => CUSTOM.get(name) ?? join(PACKS_DIR, name);
+
+export function availablePacks() {
+  return [...readdirSync(PACKS_DIR).filter((d) => existsSync(join(PACKS_DIR, d, 'pack.json'))), ...CUSTOM.keys()];
+}
+
+export function readPack(name) {
+  const file = join(packRoot(name), 'pack.json');
+  if (!existsSync(file)) throw new Error(`unknown pack "${name}" (available: ${availablePacks().join(', ')})`);
+  const pack = JSON.parse(readFileSync(file, 'utf8'));
+  if (!CUSTOM.has(name)) return pack;
+  // A hook runs code on every tool call, so somebody else's hook is off until the project names it in "enable".
+  const hooks = join(packRoot(name), 'hooks');
+  return { ...pack, optIn: [...(pack.optIn ?? []), ...(existsSync(hooks) ? readdirSync(hooks).filter((f) => /\.(mjs|py)$/.test(f)).map((f) => `hooks/${f}`) : [])] };
+}
+
+// Python's byte-code caches are never pack files (a selftest run inside the package makes them).
+const JUNK = /^(__pycache__|\.DS_Store)$|\.pyc$/;
+
+function walk(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((entry) => !JUNK.test(entry)).flatMap((entry) => {
+    const abs = join(dir, entry);
+    return statSync(abs).isDirectory() ? walk(abs) : [abs];
+  });
+}
+
+// Returns [{ src, rel }] where rel is the destination relative to the project root.
+// Skills go to the pack's own folder (lazy-loaded nested skills) when it declares one.
+export function planFiles(name, layout) {
+  const pack = readPack(name);
+  const root = packRoot(name);
+  const plan = [];
+  // A rule that states a hook's law ("# hook: <file>" in its frontmatter) goes where its hook goes: held or left out with it (0.10.0).
+  const ruleHook = (src) => readFileSync(src, 'utf8').match(/^---\n(?:[^\n]*\n)*?# hook:\s*(\S+)\s*\n(?:[^\n]*\n)*?---/)?.[1];
+  const off = (src) => {
+    const rel = relative(root, src);
+    if (isDisabled(layout, rel)) return true;
+    const hook = /^rules[\\/][^\\/]+\.md$/.test(rel) && ruleHook(src);
+    return Boolean(hook) && isDisabled(layout, `hooks/${hook}`);
+  };
+  for (const dir of CLAUDE_DIRS) {
+    for (const src of walk(join(root, dir))) if (!off(src)) plan.push({ src, rel: join('.claude', relative(root, src)) });
+  }
+  const skillFolder = pack.skillsIn && layout.folders[pack.skillsIn];
+  const skillBase = skillFolder ? join(skillFolder.path, '.claude') : '.claude';
+  for (const src of walk(join(root, 'skills'))) if (!off(src)) plan.push({ src, rel: join(skillBase, relative(root, src)) });
+  const tidy = join(root, 'clang-tidy');
+  if (existsSync(tidy)) plan.push({ src: tidy, rel: '.clang-tidy', userOwned: true });
+  return plan;
+}
+
+// Every hook script any pack ships (node .mjs or python3 .py), by file name. settings.json entries
+// that run one of these are the package's; every other hook entry is the project's own.
+export function kitHookScripts() {
+  const out = new Set();
+  for (const name of availablePacks()) {
+    const dir = join(PACKS_DIR, name, 'hooks');
+    if (existsSync(dir)) for (const f of readdirSync(dir)) if (/\.(mjs|py)$/.test(f)) out.add(f);
+  }
+  return out;
+}
+
+// layout.disable lists pack items a project switches off because it already has its own:
+// "checks/one-seeded-random.json", "hooks/no-shipped-images.mjs", "rules/x.md", "skills/gpu-capture".
+export function isDisabled(layout, packRel) {
+  const p = packRel.replace(/\\/g, '/');
+  return (layout.disable ?? []).some((d) => p === d || p.startsWith(`${d.replace(/\/$/, '')}/`));
+}
+
+// A preset names a stack; `init node-api` installs exactly the packs that stack needs (v7 additions 0.11.0, v8 0.12.0). The
+// configuration is then the smallest one that takes those packs (lib/configs.mjs inferConfig): `node` for the node
+// presets, `synth-creator` for synth.
+export const PRESETS = {
+  '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'],
+};
+
+// Base always first, no duplicates, presets expanded, in the order given.
+export function normalisePacks(names) {
+  const out = ['base'];
+  for (const n of names.flatMap((p) => (Object.hasOwn(PRESETS, p) ? PRESETS[p] : [p]))) if (!out.includes(n)) out.push(n);
+  for (const n of out) readPack(n);
+  return out;
+}

package/lib/planner.mjs

@@ -0,0 +1,59 @@
+// The planner-skills generator (0.10.0, STEP 3 item 5; KWB-35): one project-layout skill body per configuration, made
+// from that configuration's layout template, its packs and its preamble, for a planner that briefs work before any project
+// of that kind exists (or without reading one). `claude-packs planner-skills` prints them; `--out <dir>` writes
+// <dir>/<configuration>/project-layout/SKILL.md.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { availableConfigs, itemsOf, planOf, readConfig } from './configs.mjs';
+
+export function plannerSkill(name) {
+  const c = readConfig(name);
+  const folders = c.layout?.folders ?? {};
+  const where = (k) => (folders[k.in] ? `${folders[k.in].path}/` : k.in);
+  const items = itemsOf(planOf(c, [...c.packs.always, ...c.packs.default]));
+  return [
+    '---',
+    'name: project-layout',
+    `description: Use when planning, briefing or placing work in a ${name} project: where a new file, folder or kind of thing goes, and which laws hold there.`,
+    '---',
+    `# Project layout: ${name}`,
+    '',
+    c.description,
+    '',
+    '## Folders',
+    '',
+    ...Object.values(folders).map((f) => `- \`${f.path}/\`: ${f.purpose}`),
+    '',
+    ...(Object.keys(c.layout?.kinds ?? {}).length ? ['## What goes where', '', ...Object.values(c.layout.kinds).map((k) => `- ${k.what} → \`${where(k)}\``), ''] : []),
+    '## What it installs',
+    '',
+    `- packs: ${c.packs.always.join(', ')}${c.packs.choose.length ? `; to choose: ${c.packs.choose.join(', ')}` : ''}`,
+    `- hooks: ${items.hooks.join(', ')}`,
+    `- skills: ${items.skills.join(', ') || 'none'}`,
+    `- rules: ${items.rules.length} (\`npx --no-install @thedecipherist/claude-packs configs\` lists the configurations)`,
+    '',
+    '## House rules',
+    '',
+    '<constraints>',
+    'Always do:',
+    '- Put every kind of thing in its one place (the folders above); a new folder goes into `.claude/layout.json` first.',
+    ...c.preamble.always.map((l) => `- ${l}`),
+    '',
+    'Never do:',
+    ...c.preamble.never.map((l) => `- ${l}`),
+    '</constraints>',
+    '',
+  ].join('\n');
+}
+
+export function plannerSkills(out = null, log = console.log) {
+  for (const name of availableConfigs()) {
+    const body = plannerSkill(name);
+    if (!out) { log(`==> ${name}/project-layout/SKILL.md\n${body}`); continue; }
+    const dir = join(out, name, 'project-layout');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'SKILL.md'), body);
+    log(`  wrote ${join(dir, 'SKILL.md')}`);
+  }
+  return 0;
+}

package/lib/repeats.mjs

@@ -0,0 +1,65 @@
+// What a project repeats, for `scan`: every shape written by hand more than once, the copies of it, and what it should become. A run seen as
+// many overlapping windows is reported once, from its first window.
+import { extname } from 'node:path';
+import { TEMPLATE, TESTS, copiesNeeded, shapesOf, skippedBy } from '../packs/base/hooks/lib/elements.mjs';
+import { parametersOf } from '../packs/base/hooks/lib/code-shapes.mjs';
+import { languageOf } from '../packs/base/hooks/lib/languages.mjs';
+import { definesOf, fingerprint, nearCopy } from '../packs/base/hooks/lib/near-copies.mjs';
+import { matchesAny } from '../packs/base/hooks/lib/glob.mjs';
+
+const copiesOf = (group) => new Set(group.map((x) => `${x.rel}:${x.line}`)).size;
+const oneName = (group) => new Set(group.map((x) => x.what)).size === 1;
+const isRepeat = (g) => copiesOf(g) >= copiesNeeded(g[0], oneName(g)) && (g[0].kind !== 'setup' || !sameObject(g));
+// One object set up twice in one file is one object.
+const sameObject = (g) => new Set(g.map((x) => `${x.rel} ${x.what}`)).size < 2;
+
+function firstWindows(groups) {
+  const seen = new Set(groups.filter((g) => g[0].kind === 'run').map((g) => g.map((x) => `${x.rel}:${x.at}`).join()));
+  return groups.filter((g) => g[0].kind !== 'run' || !seen.has(g.map((x) => `${x.rel}:${x.at - 1}`).join()));
+}
+
+export function repeatedShapes(texts, layout = {}) {
+  const by = new Map();
+  for (const [rel, text] of texts) {
+    if (matchesAny(rel, [...TESTS, ...skippedBy(layout)])) continue;
+    for (const s of shapesOf(text, extname(rel))) { if (!by.has(s.id)) by.set(s.id, []); by.get(s.id).push({ ...s, rel }); }
+  }
+  const source = new Map(texts);
+  return firstWindows([...by.values()].filter(isRepeat)).sort((a, b) => b.length * b[0].nodes - a.length * a[0].nodes).map((g) => {
+    const [a, b] = g;
+    return { kind: g[0].kind, what: g[0].what, copies: g.length, at: g.map((x) => `${x.rel}:${x.line}`), template: TEMPLATE[g[0].kind],
+      parameters: g[0].kind === 'run' ? parametersOf(a.id, source.get(a.rel), source.get(b.rel), extname(a.rel)).slice(0, 6) : [] };
+  });
+}
+
+export const repeatLine = (r) => `  - ${r.copies}x ${r.what}: ${r.at.slice(0, 4).join(', ')}${r.copies > 4 ? ', ...' : ''}. Make it ${r.template}${r.parameters.length ? ` (differs in: ${r.parameters.join(', ').replace(/`/g, "'")})` : ''}`;
+
+const sourceTexts = (texts, layout) => texts.filter(([rel]) => languageOf(extname(rel)) && !matchesAny(rel, [...TESTS, ...skippedBy(layout)]));
+
+// Files that hold most of another, in order, with other names. A pair is reported once.
+export function nearCopies(texts, layout = {}) {
+  const all = sourceTexts(texts, layout).map(([file, text]) => ({ file, st: fingerprint(text, extname(file)), lang: languageOf(extname(file)) }));
+  const seen = new Set();
+  const out = [];
+  for (const x of all) {
+    const hit = nearCopy(x.st, all.filter((o) => o !== x && o.lang === x.lang));
+    if (!hit || seen.has(`${hit.file} ${x.file}`)) continue;
+    seen.add(`${x.file} ${hit.file}`);
+    out.push({ file: x.file, line: hit.line, other: hit.file, from: hit.from, to: hit.to, matched: hit.matched, of: hit.of });
+  }
+  return out.sort((a, b) => b.matched - a.matched);
+}
+
+// Compound names defined in two or three files: a helper made again. More files than that is a convention.
+export function remadeNames(texts, layout = {}) {
+  const by = new Map();
+  for (const [rel, text] of sourceTexts(texts, layout)) {
+    for (const [name, line] of definesOf(text, extname(rel))) {
+      if (!/[a-z0-9][A-Z]|[a-z0-9]_[a-z0-9]/.test(name)) continue;
+      const key = `${languageOf(extname(rel)).name} ${name}`;
+      if (!by.has(key)) by.set(key, { name, at: [] });
+      by.get(key).at.push(`${rel}:${line}`);
+    }
+  }
+  return [...by.values()].filter((m) => m.at.length >= 2 && m.at.length <= 3 && new Set(m.at.map((a) => a.split(':')[0])).size >= 2);
+}

package/lib/repo-weight.mjs

@@ -0,0 +1,28 @@
+// What a repo carries that is not source: its tracked size, files too big for git, and working screenshots in its root. For `scan`; the `repo-litter`
+// hook stops new ones at `git add`.
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { BIG_MB, isRootImage } from '../packs/base/hooks/repo-litter.mjs';
+
+const MB = 1024 * 1024;
+
+// A build folder is known by what the build leaves in it, whatever it was called: `build-reso/` held 43% of one repo's tracked files.
+const BUILD_MARK = /^(.*?\/)?(?:CMakeFiles\/|CMakeCache\.txt$)/;
+export function buildFolders(files) {
+  const folders = new Set(files.map((f) => f.match(BUILD_MARK)).filter((m) => m?.[1]).map((m) => m[1]));
+  return [...folders].filter((d) => ![...folders].some((o) => o !== d && d.startsWith(o)));
+}
+
+export function repoWeight(dir, files) {
+  const sized = files.flatMap((file) => { try { return [{ file, bytes: statSync(join(dir, file)).size }]; } catch { return []; } });
+  const total = sized.reduce((n, f) => n + f.bytes, 0);
+  const big = sized.filter((f) => f.bytes > BIG_MB * MB).sort((a, b) => b.bytes - a.bytes).map((f) => ({ file: f.file, mb: Math.round(f.bytes / MB) }));
+  const built = buildFolders(files).map((folder) => ({ folder, files: files.filter((f) => f.startsWith(folder)).length }));
+  return { mb: Math.round(total / MB), big, rootImages: files.filter((f) => isRootImage(f, [])), built, files: files.length };
+}
+
+export const weightLines = (w) => [
+  `- ${w.mb} MB tracked; ${w.big.length} file(s) over ${BIG_MB} MB${w.big.length ? `: ${w.big.slice(0, 5).map((b) => `${b.file} (${b.mb} MB)`).join(', ')}` : ''}`,
+  ...w.built.map((b) => `- build output held in git: ${b.folder} (${b.files} of ${w.files} files), left out of this scan`),
+  ...(w.rootImages.length ? [`- ${w.rootImages.length} image(s) in the repo root, which look like working screenshots: ${w.rootImages.slice(0, 5).join(', ')}`] : []),
+];

package/lib/rules.mjs

@@ -0,0 +1,40 @@
+// Regenerates every rule's `paths:` from its `# concepts:` line and the layout.
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { globsForConcepts as kitGlobs } from '../packs/base/hooks/lib/layout.mjs';
+
+// A rule's text with its `paths:` written from its concepts and the layout; null for a rule
+// without a `# concepts:` line, or (unless strict, which throws) whose concepts resolve to nothing.
+export function renderRule(text, layout, globsForConcepts = kitGlobs, strict = false) {
+  const fm = text.match(/^---\n([\s\S]*?)\n---/);
+  const line = fm?.[1].match(/^# concepts:\s*(.+)$/m);
+  if (!fm || !line) return null;
+  const concepts = line[1].split(',').map((s) => s.trim()).filter(Boolean);
+  let globs;
+  try { globs = globsForConcepts(layout, concepts); } catch (e) { if (strict) throw e; return null; }
+  const head = ['---', `# concepts: ${concepts.join(', ')}`, 'paths:', ...globs.map((g) => `  - "${g}"`), '---'].join('\n');
+  return text.replace(fm[0], head);
+}
+
+async function layoutLib(projectDir) {
+  return import(pathToFileURL(join(projectDir, '.claude', 'hooks', 'lib', 'layout.mjs')).href);
+}
+
+export async function applyPaths(projectDir, { checkOnly = false, skip = new Set() } = {}) {
+  const { readLayout, globsForConcepts } = await layoutLib(projectDir);
+  const layout = readLayout(projectDir);
+  const dir = join(projectDir, '.claude', 'rules');
+  if (!existsSync(dir)) return { stale: 0 };
+  let stale = 0;
+  for (const file of readdirSync(dir).filter((f) => f.endsWith('.md'))) {
+    if (skip.has(join('.claude', 'rules', file))) continue; // the user's file or a rule they edited
+    const text = readFileSync(join(dir, file), 'utf8');
+    const next = renderRule(text, layout, globsForConcepts, true);
+    if (next !== null && next !== text) {
+      stale += 1;
+      if (!checkOnly) writeFileSync(join(dir, file), next);
+    }
+  }
+  return { stale };
+}

package/lib/scan-detect.mjs

@@ -0,0 +1,94 @@
+// What a project is, from its files and its dependencies: the configuration and the packs `scan` recommends, each with its evidence.
+// One row per pack: a pack is recommended when its row finds something, and says what it found.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isContent } from '../packs/base/hooks/lib/content.mjs';
+import { readConfig } from './configs.mjs';
+
+const dep = (ctx, ...names) => names.find((n) => ctx.deps.has(n) || [...ctx.deps].some((d) => d.startsWith(`${n}/`)));
+const file = (ctx, re) => ctx.files.find((f) => re.test(f));
+const said = (hit, what) => (hit ? `${what}: ${hit}` : null);
+// The first of a project's files with this name that holds this text: a name says too little where every project has the same files.
+const MOST_READ = 40;
+function holds(ctx, name, text) {
+  return ctx.files.filter((f) => name.test(f)).slice(0, MOST_READ).find((f) => { try { return text.test(readFileSync(join(ctx.dir, f), 'utf8')); } catch { return false; } });
+}
+
+const ROWS = {
+  'js-ts': (c) => said(file(c, /\.(ts|tsx|js|jsx|mjs|cjs)$/), 'JS or TS source'),
+  mongo: (c) => said(dep(c, 'mongodb', 'mongoose'), 'dependency'),
+  fastify: (c) => said(dep(c, 'fastify'), 'dependency'),
+  ai: (c) => said(dep(c, '@anthropic-ai/sdk', 'openai', 'ai', '@ai-sdk'), 'dependency'),
+  docker: (c) => said(file(c, /(^|\/)(Dockerfile[^/]*|[\w.-]*compose[\w.-]*\.ya?ml)$/), 'file'),
+  'shell-hooks': (c) => said(file(c, /(^|\/)hooks\/[^/]+\.(sh|mjs|js|cjs)$/), 'hook file'),
+  'html-ui': (c) => said(file(c, /(^|\/)(ui|views|templates)\/[^/]+\.ts$|\.view\.ts$/), 'server-rendered UI'),
+  web: (c) => said(dep(c, 'next', 'react', 'vue', 'svelte') ?? file(c, /\.(tsx|jsx|vue|svelte|html)$/), 'web UI'),
+  tui: (c) => said(dep(c, 'ink', 'blessed', 'terminal-kit'), 'dependency'),
+  nginx: (c) => said(file(c, /(^|\/)nginx[^/]*\.conf(?:\.template)?$|\/nginx\/.+\.conf$/), 'file'),
+  'stored-text': (c) => (ROWS.web(c) || ROWS['html-ui'](c)) && (ROWS.mongo(c) || dep(c, 'pg', 'mysql2', 'sqlite3', 'better-sqlite3', 'prisma', 'drizzle-orm')) ? 'a UI and a database' : null,
+  'ui-craft': (c) => ROWS.web(c) ?? ROWS['html-ui'](c),
+  cpp: (c) => said(file(c, /\.(?:cc|cpp|cxx|hh|hpp|mm)$/), 'C++ source'),
+  python: (c) => said(file(c, /\.py$/), 'Python source'),
+  go: (c) => said(file(c, /\.go$/), 'Go source'),
+  midi: (c) => said(file(c, /\.(syx|mid)$|(^|\/)\w*(Midi|MIDI|Sysex|SysEx)\w*\.(h|hpp|cpp|cc)$/), 'MIDI file')
+    ?? said(holds(c, /\.(h|hpp|cpp|cc)$/, /\b(MidiMessage|isController|isNoteOn|getSysExData)\b/), 'MIDI handling'),
+  'sound-design': (c) => said(file(c, /(^|\/)\w*(Voice|Oscillator|Filter|Reverb|Envelope|Lfo|LFO)\w*\.(h|hpp|cpp|cc)$/), 'DSP source'),
+  'reverse-engineering': (c) => said(file(c, /(^|\/)[\w-]*(firmware|disasm|disassembl|x86dis|dis8051|reverse[-_]engineer)[\w-]*\.(md|py)$|(^|\/)[\w.-]+[-_]re\.md$|(^|\/)tools\/re\//i), 'reverse-engineering notes')
+    ?? said(holds(c, /(^|\/)(research|laws|provenance)\.md$/, /\[FW\]/), 'firmware findings'),
+  'instrument-shell': (c) => said(file(c, /(^|\/)PluginEditor\.(h|cpp)$/), 'plugin editor'),
+  'content-site': (c) => said(c.published.find((f) => /\.(md|mdx|html)$/.test(f)) ?? file(c, /(^|\/)sitemap\.xml$/), 'published page'),
+  'dynamic-data': (c) => said(file(c, /(^|[/_-])(cms|entity[-_]?definitions?|field[-_]?configs?|page[-_]?builder|admin[-_]?generator)([/_.-]|$)/i), 'definition-driven file'),
+  ci: (c) => said(file(c, /^\.github\/workflows\/[^/]+\.ya?ml$/), 'workflow'),
+  'http-api': (c) => said(dep(c, 'express', 'fastify', 'koa', 'hono', '@nestjs/core', 'next'), 'dependency') ?? said(file(c, /(^|\/)app\/api\/.*route\.ts$|(^|\/)routes\/[^/]+\.[jt]s$/), 'route file'),
+  react: (c) => said(dep(c, 'react'), 'dependency') ?? said(file(c, /\.[jt]sx$/), 'JSX source'),
+  websocket: (c) => said(dep(c, 'ws', 'socket.io', 'uWebSockets.js', '@fastify/websocket'), 'dependency'),
+  'multi-tenant': (c) => said(file(c, /(^|[/_-])(tenants?|compan(?:y|ies)|organi[sz]ations?|workspaces?)([/_.-]|$)/i), 'tenant file'),
+  'host-agent': (c) => said(dep(c, 'ssh2'), 'dependency') ?? said(file(c, /(^|\/)install[-_]agent|\.service$/), 'agent file'),
+  shell: (c) => said(file(c, /\.(?:sh|bash|zsh)$/), 'shell script'),
+  'audio-core': (c) => said(file(c, /(^|\/)(JuceHeader\.h|.*\.jucer)$/) ?? file(c, /PluginProcessor\.(h|cpp)$/), 'JUCE file'),
+  'gpu-painter': (c) => said(file(c, /\.wgsl$/), 'shader'),
+};
+
+// The configuration of the project: a synth; else the language most of its files are in; else base. full-stack is offered, never assumed: it fixes a folder layout.
+const LEADS = [['cpp', /\.(?:c|cc|cpp|cxx|h|hh|hpp|mm)$/, 'C++ sources'], ['node', /\.(?:ts|tsx|js|jsx|mjs|cjs)$/, 'JS or TS sources'], ['python', /\.py$/, 'Python sources'], ['go', /\.go$/, 'Go sources']];
+
+function configFor(ctx) {
+  if (ROWS['audio-core'](ctx)) return { name: 'synth-creator', why: 'JUCE sources' };
+  const [lead] = LEADS.map(([name, re, why]) => ({ name, why, n: ctx.files.filter((f) => re.test(f)).length })).sort((a, b) => b.n - a.n);
+  return lead.n ? lead : { name: 'base', why: 'no stack the kit has a configuration for' };
+}
+
+const INSTALLED = /(^|\/)\.claude\//;
+
+// A project that names its configuration has decided; reading the files again can only disagree with it.
+function namedConfig(projectDir) {
+  try {
+    const name = JSON.parse(readFileSync(join(projectDir, '.claude/layout.json'), 'utf8')).configuration;
+    return name && readConfig(name) ? { name, why: 'named in its layout.json' } : null;
+  } catch { return null; }
+}
+
+export function recommend(projectDir, files) {
+  const deps = new Set();
+  for (const f of files.filter((x) => /(^|\/)package\.json$/.test(x))) {
+    const p = join(projectDir, f);
+    if (!existsSync(p)) continue;
+    try {
+      const j = JSON.parse(readFileSync(p, 'utf8'));
+      for (const k of ['dependencies', 'devDependencies', 'peerDependencies']) for (const n of Object.keys(j[k] ?? {})) deps.add(n);
+    } catch { /* a package.json that does not parse says nothing */ }
+  }
+  const own = files.filter((f) => !INSTALLED.test(f)); // the kit's own files in a project say nothing about the project
+  const ctx = { deps, dir: projectDir, files: own.filter((f) => !isContent(f)), published: own.filter(isContent) };
+  const { name, why } = namedConfig(projectDir) ?? configFor(ctx);
+  const config = readConfig(name);
+  const packs = [];
+  const leftOut = [];
+  for (const pack of config.packs.choose) {
+    const found = ROWS[pack]?.(ctx);
+    if (found) packs.push({ pack, why: found });
+    else leftOut.push(pack);
+  }
+  const fullStack = dep(ctx, 'next') && dep(ctx, 'fastify');
+  return { config: name, why, always: config.packs.always, packs, leftOut, fullStack: Boolean(fullStack) };
+}