@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/lib/scan.mjs

@@ -0,0 +1,168 @@
+// claude-packs scan (0.16.0: a project owner runs it before choosing to install anything). A real install's review found bugs that
+// "could have been super bad on production", so the scan is that review, on a copy:
+//   1. the project's files are copied to a temp folder (what git tracks or would track; never .env, keys, node_modules or build output),
+//      so the project itself, its .git included, is never written to;
+//   2. the recommended packs are installed into the copy (lib/scan-detect.mjs says which, with the evidence);
+//   3. every check runs over every file, and the secret patterns, the line limit and coverage with them;
+//   4. the report and every hit go beside the copy. A hit is a candidate, not a bug: a real install's run had 189 real of 302 counted.
+// The bugs that hurt most are the ones no check sees, so the report ends with the review step: `scan --prompt` (prompts/scan-review.md).
+import { execFileSync } from 'node:child_process';
+import { copyFileSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { isContent } from '../packs/base/hooks/lib/content.mjs';
+import { readLayout } from '../packs/base/hooks/lib/layout.mjs';
+import { isSecretFile } from '../packs/base/hooks/secrets-guard.mjs';
+import { sourceFilesOf } from './configs.mjs';
+import { SOURCE, coverage } from './coverage.mjs';
+import { onceOnlyDoctor } from './once-only-report.mjs';
+import { PACKS_DIR, availablePacks } from './packs.mjs';
+import { nearCopies, remadeNames, repeatLine, repeatedShapes } from './repeats.mjs';
+import { rememberScan } from './fix-plan.mjs';
+import { repoWeight, weightLines } from './repo-weight.mjs';
+import { recommend } from './scan-detect.mjs';
+import { sync } from './sync.mjs';
+
+const SKIP = /(^|\/)(\.git|node_modules|dist|build|out|coverage|\.next|\.claude|_deps|JUCE|cmake-build[^/]*)(\/|$)/;
+const MAX_BYTES = 1_000_000;
+const SHOWN = 5;
+const TEXT = 'public text';
+const KINDS = [
+  ['security', /\b(?:secrets?|tokens?|xss|injection|credentials?|passwords?|csrf|redirects?|sanitize\w*|escape[sd]?|untrusted|helmet|cookies?)\b/i],
+  ['failures and lost data', /\b(?:swallow\w*|lost|silently|crash\w*|shutdown|unhandled\w*|delete\w*|drops?|transaction\w*|floating|never stops?)\b/i],
+  ['quality', /./],
+];
+
+function walk(root, dir = root) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+    const abs = join(dir, e.name);
+    if (SKIP.test(relative(root, abs))) return [];
+    return e.isDirectory() ? walk(root, abs) : [relative(root, abs).replace(/\\/g, '/')];
+  });
+}
+
+export function filesOf(dir) {
+  try {
+    return execFileSync('git', ['-C', dir, 'ls-files', '-co', '--exclude-standard', '-z'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 1 << 28 }).split('\0').filter(Boolean);
+  } catch {
+    return walk(dir);
+  }
+}
+
+const copyable = (dir, rel) => {
+  if (SKIP.test(rel) || isSecretFile(rel)) return false;
+  try { const s = lstatSync(join(dir, rel)); return s.isFile() && s.size <= MAX_BYTES; } catch { return false; }
+};
+
+function snapshot(dir, files) {
+  const copy = mkdtempSync(join(tmpdir(), 'claude-packs-scan-'));
+  for (const rel of files) {
+    mkdirSync(dirname(join(copy, rel)), { recursive: true });
+    copyFileSync(join(dir, rel), join(copy, rel));
+  }
+  return copy;
+}
+
+// A line as it may be shown: long tokens masked, so a report can be passed around.
+const shown = (text) => text.replace(/[A-Za-z0-9_+/=-]{24,}/g, '[masked]').slice(0, 110);
+const packOf = (file) => availablePacks().find((p) => { try { return lstatSync(join(PACKS_DIR, p, 'checks', file)).isFile(); } catch { return false; } }) ?? '?';
+
+async function runChecks(copy, files) {
+  const hook = (name) => import(pathToFileURL(join(copy, '.claude/hooks', name)).href);
+  const { loadChecks, hitsOf } = await hook('lesson-checks.mjs');
+  const { matchesAny } = await hook('lib/glob.mjs');
+  const { SECRETS } = await hook('secrets-guard.mjs');
+  const texts = files.map((rel) => [rel, readFileSync(join(copy, rel), 'utf8')]).filter(([, t]) => !t.includes('\0'));
+  const results = [];
+  let samples = 0;
+  for (const c of loadChecks(copy)) {
+    const hits = texts.filter(([rel]) => matchesAny(rel, c.globs) && !matchesAny(rel, c.exclude ?? []))
+      .flatMap(([rel, text]) => hitsOf(c, text).map((h) => ({ file: rel, line: h.line, text: shown(h.text) })));
+    const pack = packOf(c.file);
+    const own = pack === 'writing' ? hits : hits.filter((h) => !isContent(h.file));
+    samples += hits.length - own.length;
+    if (own.length) results.push({ id: c.id, why: c.why, rule: c.rule, pack, kind: pack === 'writing' ? TEXT : c.kind ?? KINDS.find(([, re]) => re.test(`${c.id} ${c.why}`))[0], hits: own });
+  }
+  const secrets = texts.flatMap(([rel, text]) => SECRETS.flatMap(([name, re]) => [...text.matchAll(re)].map((m) => ({ file: rel, line: text.slice(0, m.index).split('\n').length, name }))));
+  return { results, secrets, texts, samples };
+}
+
+function report({ dir, copy, pick, results, secrets, skipped, longFiles, cov, dups, handBuilt, near, remade, samples, weight, count }) {
+  const code = results.filter((r) => r.kind !== TEXT);
+  const total = code.reduce((n, r) => n + r.hits.length, 0);
+  const inText = results.filter((r) => r.kind === TEXT).reduce((n, r) => n + r.hits.length, 0);
+  const packs = [...pick.always, ...pick.packs.map((p) => p.pack)];
+  const out = ['# claude-packs scan', '', `${dir}: ${count} files read, on a copy. Nothing in the project was changed.`, ''];
+  const inTests = (s) => /(^|\/)(tests?|__tests__|fixtures?)\/|\.(test|spec)\./.test(s.file) || isContent(s.file);
+  const live = secrets.filter((s) => !inTests(s));
+  if (live.length) out.push(`**Look at this first: ${live.length} possible secret(s) in the code, listed below. Any that is real is leaked: rotate it.**`, '');
+  out.push(`${total} check hits in ${new Set(code.flatMap((r) => r.hits.map((h) => h.file))).size} files${inText ? `, and ${inText} in public text, listed last` : ''}${samples ? `. ${samples} more in content folders are samples, left out` : ''}. A hit is a candidate, not a confirmed bug: someone has to read it. The worst bugs are usually the ones no check can see, so the review step at the end matters more than this list.`, '');
+  out.push('## What to install', '', `Configuration \`${pick.config}\` (${pick.why}), packs: ${packs.join(', ')}.`, '');
+  for (const p of pick.packs) out.push(`- \`${p.pack}\`: ${p.why}`);
+  if (pick.leftOut.length) out.push('', `Left out, nothing found for them: ${pick.leftOut.join(', ')}.`);
+  if (pick.fullStack) out.push('', 'Next.js and Fastify are both here: the `full-stack` configuration may fit, but it fixes a folder layout and has fewer checks. Compare before choosing.');
+  out.push('', '```', `npx --no-install @thedecipherist/claude-packs init ${pick.packs.map((p) => p.pack).join(' ')} --config ${pick.config}`, '```', '');
+  if (secrets.length) {
+    out.push('## Secrets', '', 'Values are never shown. Secret-shaped text in test files and content folders is usually an example, and is listed apart.', '');
+    for (const s of live) out.push(`- ${s.file}:${s.line}: ${s.name}`);
+    const planted = secrets.filter(inTests);
+    if (planted.length) out.push('', `In test files and content folders (${planted.length}):`, ...planted.map((s) => `- ${s.file}:${s.line}: ${s.name}`));
+    out.push('');
+  }
+  out.push('## Check hits', '', 'Grouped by a keyword match on what each check is for, so the groups are rough.', '');
+  for (const kind of [...KINDS.map(([k]) => k), TEXT]) {
+    const rows = results.filter((r) => r.kind === kind).sort((a, b) => b.hits.length - a.hits.length);
+    if (!rows.length) continue;
+    out.push(`### ${kind}`, '');
+    for (const r of rows) {
+      out.push(`**${r.id}** (${r.pack}): ${r.hits.length}. ${r.why}`, '');
+      for (const h of r.hits.slice(0, SHOWN)) out.push(`- ${h.file}:${h.line}: \`${h.text.replace(/`/g, "'")}\``);
+      if (r.hits.length > SHOWN) out.push(`- and ${r.hits.length - SHOWN} more (all in claude-packs-scan.json)`);
+      out.push('');
+    }
+  }
+  out.push('## Structure', '', `- ${longFiles.length} source file(s) over 300 lines${longFiles.length ? `: ${longFiles.slice(0, 8).join(', ')}` : ''}`, `- ${dups}`, `- ${handBuilt.length} repeat(s) written by hand, each of which should be one template${handBuilt.length ? ':' : ''}`, ...handBuilt.slice(0, 12).map(repeatLine), `- ${near.length} near cop(ies), the same code with lines changed${near.length ? ':' : ''}`, ...near.slice(0, 8).map((n) => `  - ${n.file}:${n.line} ~ ${n.other}:${n.from}-${n.to} (${n.matched} of ${n.of} statements)`), `- ${remade.length} function(s) made again under the same name${remade.length ? ':' : ''}`, ...remade.slice(0, 8).map((m) => `  - ${m.name}: ${m.at.join(', ')}`));
+  out.push(...weightLines(weight));
+  out.push(`- ${cov.uncovered.length} source file(s) no rule covers yet; the layout is fitted to the project at install`, '');
+  if (skipped.length) out.push(`Not read: ${skipped.length} file(s), secret files, symlinks or over 1 MB. ${skipped.filter(isSecretFile).length} of them are secret files, left out on purpose.`, '');
+  out.push('## Next step', '', 'The checks find patterns. For runaway loops, security holes between files and work that disappears silently, run the review on the copy:', '', '```', `cd ${copy}`, 'npx --no-install @thedecipherist/claude-packs scan --prompt   # give what it prints to Claude Code here', '```', '', `The copy holds your code: delete ${copy} when you are done.`, '');
+  return out.join('\n');
+}
+
+export async function scan(projectDir, { out = null, log = console.log } = {}) {
+  const listed = filesOf(projectDir);
+  const weight = repoWeight(projectDir, listed);
+  const built = weight.built.map((b) => b.folder);
+  const files = listed.filter((rel) => copyable(projectDir, rel) && !built.some((folder) => rel.startsWith(folder)));
+  const pick = recommend(projectDir, files);
+  const copy = snapshot(projectDir, files);
+  await sync(copy, pick.packs.map((p) => p.pack), { config: pick.config, mkdirs: true, log: () => {} });
+  const { results, secrets, texts: all, samples } = await runChecks(copy, files);
+  const texts = all.filter(([rel]) => !isContent(rel));
+  const source = sourceFilesOf(copy, [...pick.always, ...pick.packs.map((p) => p.pack)]) ?? SOURCE; // base and synths name none
+  const cov = await coverage(copy, source);
+  const longFiles = texts.filter(([rel, t]) => source.test(rel) && t.split('\n').length - 1 > 300).map(([rel]) => rel);
+  const said = [];
+  onceOnlyDoctor(copy, (l) => said.push(l.trim()));
+  const layout = readLayout(projectDir);
+  const handBuilt = repeatedShapes(texts, layout);
+  const near = nearCopies(texts, layout);
+  const remade = remadeNames(texts, layout);
+  const dups = said.find((l) => l.startsWith('duplicates')) ?? 'duplicates: not measured (jscpd not found)';
+  const skipped = listed.filter((rel) => !files.includes(rel));
+  const text = report({ dir: projectDir, copy, pick, results, secrets, skipped, longFiles, cov, dups, handBuilt, near, remade, samples, weight, count: files.length });
+  const file = out ?? join(copy, 'claude-packs-scan.md');
+  writeFileSync(file, text);
+  const json = join(copy, 'claude-packs-scan.json');
+  writeFileSync(json, `${JSON.stringify({ pick, results, secrets, repeats: handBuilt, near, remade, longFiles, weight }, null, 2)}\n`);
+  rememberScan(projectDir, json);
+  log(`Scanned ${files.length} files on a copy; the project was not changed.`);
+  log(`  ${pick.config}: ${[...pick.always, ...pick.packs.map((p) => p.pack)].join(', ')}`);
+  const inCode = secrets.filter((s) => !isContent(s.file)).length;
+  log(`  ${results.filter((r) => r.kind !== TEXT).reduce((n, r) => n + r.hits.length, 0)} check hits, ${inCode} possible secret(s)${samples ? `; ${samples} sample hits in content folders left out` : ''}`);
+  log(`Report: ${file}`);
+  log(`Copy:   ${copy} (delete it when you are done; it holds your code)`);
+  log('Next:   `fix` turns this into a work order for Claude; `init --auto` installs what it suggests.');
+  return { file, copy, pick, results, secrets };
+}

package/lib/selftest-cache.mjs

@@ -0,0 +1,39 @@
+// doctor's memory of proved hooks (0.13.0, KWB-41): a hook's selftest proves the hook, so a hook that has not changed has nothing new
+// to prove. One install took 0.1 s and its doctor 7.4 s, all of it hooks proving what they had already proved, on every init,
+// update and test. A selftest that PASSED is remembered by the hash of what it ran: the hook, every file of hooks/lib, the runner,
+// node's version, the platform, the detector and the project's guards. Change any of those and it runs again; a failure is never
+// remembered; `doctor --fresh` runs them all. The memory is a folder of empty files, safe to delete.
+//   CLAUDE_PACKS_SELFTEST_CACHE: the folder (default: claude-packs-selftests in the system temp folder)
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const folder = () => process.env.CLAUDE_PACKS_SELFTEST_CACHE ?? join(tmpdir(), 'claude-packs-selftests');
+
+function filesUnder(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((e) => e !== '__pycache__' && !e.endsWith('.pyc')).sort().flatMap((e) => {
+    const abs = join(dir, e);
+    return statSync(abs).isDirectory() ? filesUnder(abs) : [abs];
+  });
+}
+
+// What every selftest of this install runs on, hashed once: the shared libs, the runner, the machine, the project's guards.
+export function sharedHash(claudeDir, guards = {}) {
+  const h = createHash('sha256');
+  for (const f of [...filesUnder(join(claudeDir, 'hooks', 'lib')), join(claudeDir, 'hooks', 'run-hooks.mjs')]) if (existsSync(f)) h.update(readFileSync(f));
+  h.update(`${process.version}\0${process.platform}\0${process.env.CLAUDE_PACKS_JSCPD ?? ''}\0${JSON.stringify(guards)}`);
+  return h.digest('hex');
+}
+
+export const selftestKey = (file, shared) => createHash('sha256').update(shared).update(readFileSync(file)).digest('hex');
+export const proved = (key) => existsSync(join(folder(), key));
+
+// Never throws: a memory that cannot be written only means the selftest runs again next time.
+export function remember(key) {
+  try {
+    mkdirSync(folder(), { recursive: true });
+    writeFileSync(join(folder(), key), '');
+  } catch { /* nothing to remember with */ }
+}

package/lib/settings.mjs

@@ -0,0 +1,138 @@
+// Merges the packs' hooks into .claude/settings.json. Hooks this package owns (a command that runs
+// a script some pack ships, or one the last install put in .claude/hooks/) are rebuilt from the
+// installed packs on every run; every other hook entry, the project's own, stays as it is.
+// Kit hooks are node (.mjs); browser-guard.py is the one Python hook left (see README).
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isDisabled, kitHookScripts, readPack } from './packs.mjs';
+
+const SCRIPT = /\.claude\/hooks\/([\w-]+\.(?:mjs|py))\b/;
+// Hooks a project carried by hand that the kit has taken over elsewhere: copy-tree-guard is merged into
+// protect-vendor; shell-traps and gnu-shell are global by design (`claude-packs global add`); git-guard, build-guard,
+// time-guard, user-asks and idle-wake were Python and are Node now. A project entry for one only runs it twice, or runs
+// a file the project no longer has. Their entries go, and update says so.
+// user-asks had a person's name until 0.25.0. A project's settings and `enable` list may still say it.
+export const OLD_ASKS = 'tims-asks.mjs';
+export const FORERUNNERS = ['git-guard.py', 'build-guard.py', 'time-guard.py', OLD_ASKS.replace('.mjs', '.py'), 'idle-wake.py'];
+export const RETIRED = ['copy-tree-guard.py', 'shell-traps.py', 'gnu-shell.py', 'shell-traps.mjs', 'gnu-shell.mjs', OLD_ASKS, ...FORERUNNERS];
+
+// One node process per settings entry, not one per hook (KWB-24): a group's kit node hooks become one run-hooks.mjs command
+// that names them (`node ".../run-hooks.mjs" .claude/hooks/a.mjs .claude/hooks/b.mjs`), in their order, at the first one's
+// place, its timeout their sum (60 s at most). An async hook (idle-wake waits for minutes) keeps its own entry, as does
+// every hook that is not the kit's node hook (browser-guard.py, the project's own).
+export const RUNNER = 'run-hooks.mjs';
+const NODE_HOOK = /^node "\$CLAUDE_PROJECT_DIR\/\.claude\/hooks\/([\w-]+\.mjs)"$/;
+// Only a hook written for the runner (it exports hook(text)) is folded in; any other node hook keeps its own entry: the kit
+// repo's own kit-lock was folded in, failed there as exit 1 and never refused (KWB-26).
+const HOOK_EXPORT = /export\s+(?:const|let|function|async\s+function)\s+hook\b|export\s*\{[^}]*\bhook\b[^}]*\}/;
+export const runnable = (claudeDir) => (name) => { try { return HOOK_EXPORT.test(readFileSync(join(claudeDir, 'hooks', name), 'utf8')); } catch { return false; } };
+export function throughRunner(hooks, canRun = () => true) {
+  const runs = (h) => !h.async && !h.asyncRewake && NODE_HOOK.test(h.command ?? '') && h.command.match(NODE_HOOK)[1] !== RUNNER && canRun(h.command.match(NODE_HOOK)[1]);
+  const kit = hooks.filter(runs);
+  if (!kit.length) return hooks;
+  const at = hooks.indexOf(kit[0]);
+  const runner = {
+    type: 'command',
+    command: `node "$CLAUDE_PROJECT_DIR/.claude/hooks/${RUNNER}" ${kit.map((h) => `.claude/hooks/${h.command.match(NODE_HOOK)[1]}`).join(' ')}`,
+    timeout: Math.min(60, kit.reduce((a, h) => a + (h.timeout ?? 10), 0)),
+  };
+  const rest = hooks.filter((h) => !runs(h));
+  rest.splice(Math.min(at, rest.length), 0, runner);
+  return rest;
+}
+
+// A runner command back into one entry per hook it names, so the project's own hooks in it survive the rebuild below (the
+// runner itself is the kit's, so its whole command was dropped, and the project's kit-lock with it: KWB-26).
+const RUNS = new RegExp(`^node "\\$CLAUDE_PROJECT_DIR/\\.claude/hooks/${RUNNER.replace('.', '\\.')}"((?:\\s+\\S+)+)$`);
+export function unfold(hooks) {
+  return hooks.flatMap((h) => {
+    const m = (h.command ?? '').match(RUNS);
+    if (!m) return [h];
+    return m[1].trim().split(/\s+/).map((p) => ({ type: 'command', command: `node "$CLAUDE_PROJECT_DIR/.claude/hooks/${p.split('/').pop()}"`, timeout: 15 }));
+  });
+}
+
+export function readSettings(claudeDir) {
+  const file = join(claudeDir, 'settings.json');
+  if (!existsSync(file)) return {};
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch (e) {
+    throw new Error(`.claude/settings.json is not valid JSON (${e.message}); fix it first, nothing was changed`);
+  }
+}
+
+// A configuration's "hookOrder" ({ "<event> <matcher>": [script, ...] }; no matcher: "<event>") puts the kit hooks of an entry
+// in that order, in the places kit hooks had there; the project's own hooks keep theirs; a script it does not list keeps its
+// pack order after the listed ones (0.10.0: moving a hook into another pack does not reorder a project's settings).
+export function orderHooks(hooks, order, isOurs) {
+  if (!order?.length) return hooks;
+  const at = hooks.map((h, i) => (isOurs(h.command) ? i : -1)).filter((i) => i >= 0);
+  const rank = (h) => { const i = order.indexOf(h.command.match(SCRIPT)?.[1]); return i < 0 ? order.length : i; };
+  const sorted = at.map((i) => hooks[i]).map((h, n) => ({ h, n })).sort((a, b) => rank(a.h) - rank(b.h) || a.n - b.n).map((x) => x.h);
+  const out = [...hooks];
+  at.forEach((i, n) => { out[i] = sorted[n]; });
+  return out;
+}
+
+// `previous`: the paths the last install managed (its lock), so a hook a pack dropped is removed too.
+export function syncSettings(claudeDir, packNames, layout = {}, previous = [], hookOrder = {}) {
+  const file = join(claudeDir, 'settings.json');
+  const settings = readSettings(claudeDir);
+  settings.hooks ??= {};
+  const ours = new Set([...kitHookScripts(), ...RETIRED]);
+  for (const rel of previous) {
+    const m = rel.replace(/\\/g, '/').match(/^\.claude\/hooks\/([\w-]+\.(?:mjs|py))$/);
+    if (m) ours.add(m[1]);
+  }
+  const isOurs = (command = '') => ours.has(command.match(SCRIPT)?.[1]);
+
+  for (const groups of Object.values(settings.hooks)) for (const g of groups) g.hooks = unfold(g.hooks ?? []);
+  const retired = new Set();
+  for (const groups of Object.values(settings.hooks)) for (const g of groups) for (const h of g.hooks ?? []) {
+    const s = h.command?.match(SCRIPT)?.[1];
+    if (RETIRED.includes(s)) retired.add(s);
+  }
+  for (const event of Object.keys(settings.hooks)) {
+    settings.hooks[event] = settings.hooks[event]
+      .map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !isOurs(h.command)) }))
+      .filter((g) => g.hooks.length > 0);
+  }
+
+  for (const name of packNames) {
+    for (const [event, groups] of Object.entries(readPack(name).hooks ?? {})) {
+      settings.hooks[event] ??= [];
+      for (const group of groups) {
+        let target = settings.hooks[event].find((g) => g.matcher === group.matcher);
+        if (!target) settings.hooks[event].push((target = { matcher: group.matcher, hooks: [] }));
+        for (const h of group.hooks) {
+          const script = h.command.match(SCRIPT)?.[1];
+          if (script && isDisabled(layout, `hooks/${script}`)) continue;
+          if (!target.hooks.some((x) => x.command === h.command)) target.hooks.push(h);
+        }
+      }
+    }
+  }
+  for (const [event, groups] of Object.entries(settings.hooks)) for (const g of groups) g.hooks = orderHooks(g.hooks, hookOrder?.[g.matcher === undefined ? event : `${event} ${g.matcher}`], isOurs);
+  if (!isDisabled(layout, `hooks/${RUNNER}`)) for (const groups of Object.values(settings.hooks)) for (const g of groups) g.hooks = throughRunner(g.hooks, runnable(claudeDir));
+  for (const event of Object.keys(settings.hooks)) {
+    settings.hooks[event] = settings.hooks[event].filter((g) => g.hooks.length > 0);
+    if (settings.hooks[event].length === 0) delete settings.hooks[event];
+  }
+  // the events in the order the configuration's hookOrder names them (a fresh install of 0.10.0 writes them as 0.9.x did)
+  const events = [...new Set(Object.keys(hookOrder ?? {}).map((k) => k.split(' ')[0]))];
+  if (events.length) {
+    const rank = (e) => (events.includes(e) ? events.indexOf(e) : events.length);
+    settings.hooks = Object.fromEntries(Object.entries(settings.hooks).map((x, n) => [x, n]).sort(([[a], i], [[b], j]) => rank(a) - rank(b) || i - j).map(([x]) => x));
+  }
+  // layout.siblings: the folders Claude may read and edit besides this project (e.g. "../" for
+  // every sibling project), so rolling a lesson out to other projects never stalls on access.
+  // Added only; entries the user put there themselves are never removed.
+  if (Array.isArray(layout.siblings) && layout.siblings.length) {
+    settings.permissions ??= {};
+    const dirs = (settings.permissions.additionalDirectories ??= []);
+    for (const d of layout.siblings) if (!dirs.includes(d)) dirs.push(d);
+  }
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { retired: [...retired] };
+}

package/lib/shape-cli.mjs

@@ -0,0 +1,76 @@
+// The kit's side of the shape law (0.9.0, KWB-1): the empty manifest `new` and `init` write, what doctor fails, and
+// `claude-packs shape scan`: every instance literal already in a repo, by file and concept, with a count.
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { matchesAny } from '../packs/base/hooks/lib/glob.mjs';
+import { readPack } from './packs.mjs';
+import { EMPTY_SHAPE, SHAPE_FILE, findInstanceLiterals, findSelectorDefs, findUnknownTypes, formatFinding, isExcluded, readShape, validateShape } from './shape.mjs';
+
+export const isSynth = (packs) => packs.some((p) => { try { return readPack(p).synth === true; } catch { return false; } });
+
+// Writes design/shape.json with no concepts when there is none; returns true when it wrote one.
+export function ensureShape(dir) {
+  const file = join(dir, SHAPE_FILE);
+  if (existsSync(file)) return false;
+  mkdirSync(join(dir, 'design'), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(EMPTY_SHAPE, null, 2)}\n`);
+  return true;
+}
+
+export function shapeProblems(dir, packs) {
+  if (!existsSync(join(dir, SHAPE_FILE))) {
+    return isSynth(packs) ? [`no ${SHAPE_FILE}: a synth writes down, before it builds, whether each concept is ONE or MANY (its generator, selectors and declared constants); start from \`{"concepts": {}, "exclude": []}\` and add a row per concept`] : [];
+  }
+  return validateShape(readShape(dir));
+}
+
+const SKIP = ['.git/**', '**/node_modules/**', '.claude/worktrees/**', '.claude/.claude-packs-backup/**', '.claude/claude-packs.lock.json', '.claude/usage.log', '.claude/hooks.log'];
+
+function files(dir) {
+  try {
+    const out = execFileSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], { cwd: dir, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+    return out.split('\0').filter(Boolean);
+  } catch {
+    const walk = (d) => readdirSync(join(dir, d)).flatMap((e) => {
+      const rel = d ? `${d}/${e}` : e;
+      if (matchesAny(rel, SKIP) || matchesAny(`${rel}/x`, SKIP)) return [];
+      return statSync(join(dir, rel)).isDirectory() ? walk(rel) : [rel];
+    });
+    return walk('');
+  }
+}
+
+// Every finding in the repo, code, tests, docs and briefs alike; the files the kit installed are the kit's, not the repo's.
+export function scanRepo(dir, shape = readShape(dir)) {
+  if (!shape) throw new Error(`no ${SHAPE_FILE} in ${dir}`);
+  if (shape.error) throw new Error(shape.error);
+  let kit = new Set();
+  try { kit = new Set(Object.keys(JSON.parse(readFileSync(join(dir, '.claude/claude-packs.lock.json'), 'utf8')).files)); } catch { /* not installed */ }
+  const findings = [];
+  for (const rel of files(dir)) {
+    if (kit.has(rel) || matchesAny(rel, SKIP) || isExcluded(rel, shape)) continue;
+    let text;
+    try { if (statSync(join(dir, rel)).size > 4 * 1024 * 1024) continue; text = readFileSync(join(dir, rel), 'utf8'); } catch { continue; }
+    if (text.includes('\0')) continue;
+    for (const f of [...findInstanceLiterals(text, rel, shape), ...findSelectorDefs(text, rel, shape), ...findUnknownTypes(text, rel, shape)]) findings.push({ ...f, file: rel });
+  }
+  return findings;
+}
+
+export function shapeCommand(sub, dir, log = console.log) {
+  if (sub !== 'scan') throw new Error('use `npx --no-install @thedecipherist/claude-packs shape scan [--dir D]`');
+  const findings = scanRepo(dir);
+  const byConcept = new Map();
+  for (const f of findings) {
+    log(formatFinding(f, f.file).split('\n')[0] + (f.kind ? '' : `  [${f.why}]`));
+    const k = f.concept ?? 'new type (no row)';
+    const e = byConcept.get(k) ?? { n: 0, files: new Set() };
+    e.n += 1; e.files.add(f.file);
+    byConcept.set(k, e);
+  }
+  log('');
+  for (const [k, e] of byConcept) log(`${k}: ${e.n} finding(s) in ${e.files.size} file(s)`);
+  log(findings.length ? `${findings.length} finding(s) in ${relative(process.cwd(), dir) || '.'}: each is an example, a rule or a constant, or it is fixed` : 'no findings');
+  return findings.length ? 1 : 0;
+}

package/lib/shape.mjs

@@ -0,0 +1,4 @@
+// The shape law's one reader lives with the hooks (packs/base/hooks/lib/shape.mjs), because every project gets it
+// installed beside them; the kit's own commands (doctor, `shape scan`, new) read it through this file.
+export * from '../packs/base/hooks/lib/shape.mjs';
+export { findSelectorDefs, findUnknownTypes } from '../packs/base/hooks/lib/shape-code.mjs';

package/lib/suggest.mjs

@@ -0,0 +1,18 @@
+// claude-packs suggest: which packs this project needs, read from its own files, so nobody picks them by hand. `init --auto` installs exactly this.
+// Fast and read-only: it reads file names and package.json, nothing else. `scan` goes further and runs the checks on a copy.
+import { filesOf } from './scan.mjs';
+import { recommend } from './scan-detect.mjs';
+
+export const suggestionOf = (dir) => recommend(dir, filesOf(dir));
+
+export function suggest(dir, { log = console.log } = {}) {
+  const pick = suggestionOf(dir);
+  log(`configuration: ${pick.config} (${pick.why})`);
+  log(`always: ${pick.always.join(', ')}`);
+  if (pick.packs.length) log('suggested:');
+  for (const p of pick.packs) log(`  ${p.pack.padEnd(14)} ${p.why}`);
+  if (pick.leftOut.length) log(`left out, nothing here needs them: ${pick.leftOut.join(', ')}`);
+  if (pick.fullStack) log('this looks like the full-stack configuration: `init --config full-stack` fixes its folder layout, so it is offered and never assumed');
+  log('\nInstall exactly this: npx --no-install @thedecipherist/claude-packs init --auto');
+  return pick;
+}

package/lib/switches.mjs

@@ -0,0 +1,44 @@
+// What an install switches on. A hook or a lesson check is behaviour: it refuses work. So a new one never
+// switches on in a project that did not choose it:
+//   - a pack the project is choosing now (init, add) brings all its hooks and checks, except its opt-in ones
+//     (pack.json "optIn", e.g. user-asks and idle-wake), which wait for the project's "enable" list;
+//   - a pack the project already had brings a NEW hook or check (one it never had: not in the lock, not on disk, not
+//     run by its settings.json) only when layout.json "enable" names it ("hooks/git-guard.mjs", "checks/x.json");
+//   - what the project already had stays on.
+// `update` prints both lists before it changes anything.
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { packRoot, planFiles, readPack } from './packs.mjs';
+import { OLD_ASKS, readSettings } from './settings.mjs';
+
+const SWITCH = /^(hooks\/[\w-]+\.(mjs|py)|checks\/[\w-]+\.json)$/;
+const renamed = (d) => (d === `hooks/${OLD_ASKS}` ? 'hooks/user-asks.mjs' : d);
+const listed = (list, packRel) => (list ?? []).map(renamed).some((d) => packRel === d || packRel.startsWith(`${d.replace(/\/$/, '')}/`));
+
+export function switches(projectDir, packNames, layout, lock) {
+  const hooks = JSON.stringify(readSettings(join(projectDir, '.claude')).hooks ?? {});
+  const on = [];
+  const held = [];
+  for (const name of packNames) {
+    const optIn = readPack(name).optIn ?? [];
+    const onByDefault = readPack(name).onByDefault ?? []; // the law (pack.json "onByDefault"): on in every project, new or updated
+    for (const { src, rel } of planFiles(name, layout)) {
+      const packRel = relative(packRoot(name), src).replace(/\\/g, '/');
+      if (!SWITCH.test(packRel)) continue;
+      // A hook counts as had under either of its names: a Node hook's Python forerunner (git-guard.py) is the same hook.
+      const names = packRel.startsWith('hooks/') ? [packRel, packRel.replace(/\.(mjs|py)$/, '.py'), packRel.replace(/\.(mjs|py)$/, '.mjs')] : [packRel];
+      if (packRel === 'hooks/user-asks.mjs') names.push(`hooks/${OLD_ASKS}`, `hooks/${OLD_ASKS.replace('.mjs', '.py')}`);
+      const had = names.some((n) => lock.files[`.claude/${n}`] !== undefined || existsSync(join(projectDir, '.claude', n)) ||
+        (n.startsWith('hooks/') && hooks.includes(`.claude/${n}`))) || lock.files[rel] !== undefined;
+      if (had) continue;
+      const chosen = names.some((n) => listed(layout.enable, n)) || onByDefault.includes(packRel) || (!lock.packs.includes(name) && !optIn.includes(packRel));
+      (chosen ? on : held).push(packRel);
+    }
+  }
+  return { on, held };
+}
+
+export function reportSwitches({ on, held }, log) {
+  if (on.length) log(`  switching on (new to this project): ${on.join(', ')}`);
+  if (held.length) log(`  held back, not switched on (name them in "enable" in .claude/layout.json to switch them on): ${held.join(', ')}`);
+}

package/lib/symmetry-doctor.mjs

@@ -0,0 +1,26 @@
+// doctor's part for the generated gate shape_symmetry: the installed tool proves itself (its selftest plants a missing member
+// and a swap difference), and every many concept in design/shape.json without a symmetry block is named (its generated test
+// is red until it has one).
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function symmetryProblems(projectDir, log = console.log) {
+  const problems = [];
+  const tool = join(projectDir, '.claude', 'tools', 'shape-symmetry.mjs');
+  if (existsSync(tool)) {
+    try {
+      execFileSync('node', [tool, '--selftest'], { env: { ...process.env, CLAUDE_PROJECT_DIR: projectDir }, stdio: 'pipe' });
+    } catch (e) {
+      problems.push(`shape-symmetry.mjs fails its selftest:\n${String(e.stdout)}${String(e.stderr)}`.trim());
+    }
+  }
+  const file = join(projectDir, 'design', 'shape.json');
+  if (existsSync(file)) {
+    let shape;
+    try { shape = JSON.parse(readFileSync(file, 'utf8')); } catch (e) { return [...problems, `design/shape.json is not JSON: ${e.message}`]; }
+    const bare = Object.entries(shape.concepts ?? {}).filter(([, c]) => c.shape === 'many' && !(c.symmetry?.members && c.symmetry?.swap)).map(([n]) => n);
+    if (bare.length) log(`  note: many concept(s) with no symmetry commands, so shape_symmetry is red for them: ${bare.join(', ')}`);
+  }
+  return problems;
+}