@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/lib/coverage.mjs

@@ -0,0 +1,94 @@
+// "Do the rules actually fire?" Two numbers per project: rules whose paths match no file
+// (the folder structure and the rules disagree) and source files no rule covers (code that
+// grew outside the structure). doctor prints both; `doctor --strict` fails on either.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const SKIP = /(^|\/)(\.git|node_modules|build|Builds|_deps|JUCE|JuceLibraryCode|cmake-build[^/]*)(\/|$)/;
+// Inside any .claude/ only the kit's own files are walked: skills, rules and agents, which rules on
+// the `claude` concept aim at (Sub37 WB-1: skipping .claude made those rules look dead in --strict).
+// Worktrees, hooks, state and backups stay out, so a worktree's copy never counts as the project's.
+const CLAUDE_KEEP = new Set(['skills', 'rules', 'agents']);
+export const SOURCE = /\.(c|cc|cpp|cxx|h|hh|hpp|mm|m|wgsl|metal|hlsl)$/i;
+
+// The files git would not ignore (tracked, and untracked but not ignored), relative to root; null
+// when root is not inside a git work tree. Build output a project ignores (Stellix's out/**) is
+// not source, wherever the build folder is and whatever it is called.
+function gitVisible(root) {
+  const ls = (...a) => execFileSync('git', ['ls-files', '-z', ...a], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 256 * 1024 * 1024 }).split('\0').filter(Boolean);
+  try {
+    return { files: new Set(ls('--cached', '--others', '--exclude-standard')), dirs: new Set(ls('--others', '--ignored', '--exclude-standard', '--directory').filter((d) => d.endsWith('/'))) };
+  } catch {
+    return null;
+  }
+}
+
+export function projectFiles(root) {
+  const git = gitVisible(root);
+  const visible = git?.files;
+  const out = [];
+  const walk = (dir) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const abs = join(dir, e.name);
+      const rel = relative(root, abs).replace(/\\/g, '/');
+      if (SKIP.test(rel)) continue;
+      if (e.isDirectory() && git?.dirs.has(`${rel}/`)) continue; // a whole ignored folder (build output): never walked
+      if (e.isDirectory() && dir.endsWith('/.claude') && !CLAUDE_KEEP.has(e.name)) continue;
+      if (e.isDirectory()) walk(abs);
+      else if (!visible || visible.has(rel)) out.push(rel);
+    }
+  };
+  walk(root);
+  return out;
+}
+
+// The project's own .claude/ files (its rules, skills, agents), which rules of the "claude" concept
+// fire on; agent worktrees, backups and run state are not the project's.
+function claudeFiles(projectDir) {
+  const out = [];
+  const walk = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const rel = relative(projectDir, join(dir, e.name)).replace(/\\/g, '/');
+      if (/^\.claude\/(worktrees|\.claude-packs-backup|state)(\/|$)/.test(rel)) continue;
+      if (e.isDirectory()) walk(join(dir, e.name));
+      else out.push(rel);
+    }
+  };
+  walk(join(projectDir, '.claude'));
+  return out;
+}
+
+function rulePaths(claudeDir) {
+  const dir = join(claudeDir, 'rules');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f.endsWith('.md')).map((f) => {
+    const fm = readFileSync(join(dir, f), 'utf8').match(/^---\n([\s\S]*?)\n---/)?.[1] ?? '';
+    return { rule: f, globs: [...fm.matchAll(/^\s*-\s*"([^"]+)"/gm)].map((m) => m[1]) };
+  });
+}
+
+// `source`: what counts as source (the configuration's "sourceFiles"; default C, C++ and shaders). KWB-32: a full-stack project's
+// TypeScript was never counted, so a file outside every rule could not show.
+export async function coverage(projectDir, source = SOURCE) {
+  const claudeDir = join(projectDir, '.claude');
+  const { matchesAny } = await import(pathToFileURL(join(claudeDir, 'hooks', 'lib', 'glob.mjs')).href);
+  const { readLayout } = await import(pathToFileURL(join(claudeDir, 'hooks', 'lib', 'layout.mjs')).href);
+  const all = projectFiles(projectDir);
+  const rules = rulePaths(claudeDir);
+  const reachable = [...all, ...claudeFiles(projectDir)];
+  const matchesNothing = (r) => r.globs.length && !reachable.some((f) => matchesAny(f, r.globs));
+  // A rule whose folder holds nothing yet waits for its first file; only one whose folder holds other files disagrees with the structure (KF-9: a new unit's
+  // empty src/dsp made `doctor --strict` impossible). A glob with no folder of its own (**/*.py) says nothing about the structure either.
+  const folderOf = (glob) => glob.split(/[*?{[]/)[0].replace(/\/?[^/]*$/, '');
+  const holdsFiles = (folder) => Boolean(folder) && reachable.some((f) => f.startsWith(`${folder}/`));
+  const waiting = (r) => !r.globs.some((g) => holdsFiles(folderOf(g)));
+  const deadRules = rules.filter((r) => matchesNothing(r) && !waiting(r)).map((r) => r.rule);
+  const waitingRules = rules.filter((r) => matchesNothing(r) && waiting(r)).map((r) => r.rule);
+  const liveRules = rules.filter((r) => all.some((f) => source.test(f) && matchesAny(f, r.globs))).map((r) => r.rule); // it governs source the project wrote
+  const protectedGlobs = readLayout(projectDir).protected ?? [];
+  const uncovered = all.filter((f) => source.test(f) && !matchesAny(f, protectedGlobs) && !rules.some((r) => matchesAny(f, r.globs)));
+  return { deadRules, waitingRules, liveRules, uncovered, files: all, sourceCount: all.filter((f) => source.test(f)).length };
+}

package/lib/custom-packs.mjs

@@ -0,0 +1,93 @@
+// Custom packs (0.21.0: someone makes a pack for their employer's internals and shares it with their team). A team keeps its packs
+// in a small repository of its own, `packs/<name>/` (or a pack.json at the root), which `new-pack` scaffolds. A project adds one with
+// `add <name> --from <git-url>`: the repository is fetched to a cache, never run, and the lock records its url and commit, so a teammate's
+// checkout restores the same pack and `update` pulls the newest. Who can fetch it is the git host's business. Its hooks stay off until the
+// project's "enable" names them (lib/packs.mjs): a hook runs code on every tool call.
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { readLock } from './manifest.mjs';
+import { manifestProblems } from './pack-manifest.mjs';
+import { readPack, registerPack } from './packs.mjs';
+
+const cacheRoot = () => process.env.CLAUDE_PACKS_CACHE ?? join(homedir(), '.cache', 'claude-packs');
+const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+
+// The repository at a commit, or at its newest: -> { folder, commit }.
+function fetchRepo(url, commit = null) {
+  if (url.startsWith('-')) throw new Error(`not a git url: ${url}`);
+  const folder = join(cacheRoot(), createHash('sha256').update(url).digest('hex').slice(0, 16));
+  if (existsSync(join(folder, '.git'))) git(folder, 'fetch', '--quiet', 'origin');
+  else {
+    mkdirSync(dirname(folder), { recursive: true });
+    git(cacheRoot(), 'clone', '--quiet', '--', url, folder);
+  }
+  git(folder, 'checkout', '--quiet', '--detach', commit ?? 'origin/HEAD');
+  return { folder, commit: git(folder, 'rev-parse', 'HEAD') };
+}
+
+function register(name, folder) {
+  const nested = join(folder, 'packs', name);
+  const root = existsSync(join(nested, 'pack.json')) ? nested : folder;
+  if (!existsSync(join(root, 'pack.json'))) throw new Error(`no pack "${name}" in that repository (looked for packs/${name}/pack.json and pack.json)`);
+  registerPack(name, root);
+  const pack = readPack(name);
+  const problems = [...manifestProblems(pack, name), ...(pack.type === 'custom' ? [] : [`pack ${name} says its type is ${pack.type}, not custom`])];
+  if (problems.length) throw new Error(problems.join('; '));
+  return pack;
+}
+
+export function addCustomPack(name, url) {
+  if (!name) throw new Error('name the pack: `add <name> --from <git-url>`');
+  const { folder, commit } = fetchRepo(url);
+  const pack = register(name, folder);
+  console.log(`  ${name} ${pack.version} by ${pack.author} from ${url}`);
+  return { url, commit };
+}
+
+// The custom packs a project's lock names, at their commits, or at their newest for `update`. -> { name: { url, commit } }.
+export function loadCustomPacks(projectDir, { latest = false } = {}) {
+  const out = {};
+  for (const [name, { url, commit }] of Object.entries(readLock(join(resolve(projectDir), '.claude')).sources ?? {})) {
+    try {
+      const got = fetchRepo(url, latest ? null : commit);
+      const pack = register(name, got.folder);
+      if (latest && got.commit !== commit) console.log(`  ${name}: now ${pack.version} (${got.commit.slice(0, 7)})`);
+      out[name] = { url, commit: got.commit };
+    } catch (e) {
+      throw new Error(`custom pack ${name} could not be fetched from ${url}: ${String(e.stderr ?? e.message).trim().split('\n')[0]}. Check access to that repository.`);
+    }
+  }
+  return out;
+}
+
+const gitConfig = (key) => { try { return git('.', 'config', key); } catch { return ''; } };
+
+const FILES = (name, author, repo) => ({
+  'README.md': `# ${name}\n\nOur own claude-packs. Each folder under \`packs/\` is one pack: rules, checks, hooks, skills.\n\nInstall in a project:\n\n\`\`\`\nnpx --no-install @thedecipherist/claude-packs add ${name} --from ${repo}\n\`\`\`\n\nAfter that, \`update\` pulls the newest. A pack's hooks stay off until the project names them in \`"enable"\` in \`.claude/layout.json\`.\n`,
+  [`packs/${name}/pack.json`]: `${JSON.stringify({ name, version: '0.1.0', description: `What ${name} is for.`, type: 'custom', author, license: 'UNLICENSED', homepage: repo, repository: { type: 'git', url: repo, directory: `packs/${name}` }, keywords: [], engines: { 'claude-packs': '>=0.21.0' }, folders: {}, concepts: {}, skillsIn: null, hooks: {} }, null, 2)}\n`,
+  [`packs/${name}/rules/${name}-example.md`]: '---\n# concepts: js\npaths:\n  - "placeholder"\n---\n\n# State the law in one line\n\n<constraints>\nAlways do:\n- What the rule asks for.\n\nNever do:\n- What it refuses.\n</constraints>\n',
+  [`packs/${name}/checks/${name}-example.json`]: `${JSON.stringify({ id: `${name}-example`, why: 'Why this pattern is refused.', rule: `.claude/rules/${name}-example.md`, concepts: ['js'], globs: [], code: true, pattern: '\\bOLD_API_NAME\\b', bad: 'OLD_API_NAME();\n', good: 'newApiName();\n' }, null, 2)}\n`,
+  [`packs/${name}/skills/${name}-example/SKILL.md`]: `---\nname: ${name}-example\ndescription: Use when the situation this skill is for comes up.\n---\n\n# One job\n\n<constraints>\nAlways do:\n1. The first step.\n\nNever do:\n- What goes wrong without this skill.\n</constraints>\n`,
+});
+
+export function newPack(dir, name, { repo = null } = {}) {
+  if (!/^[a-z][a-z0-9-]*$/.test(name ?? '')) throw new Error('name the pack in lower case: `new-pack acme-internal`');
+  const root = join(dir, name);
+  if (existsSync(root)) throw new Error(`${root} already exists`);
+  const url = repo ?? `git@git.example.com:team/${name}.git`;
+  for (const [rel, text] of Object.entries(FILES(name, gitConfig('user.name') || 'Your team', url))) {
+    mkdirSync(dirname(join(root, rel)), { recursive: true });
+    writeFileSync(join(root, rel), text);
+  }
+  git(root, 'init', '--quiet', '--initial-branch', 'main');
+  git(root, 'add', '.');
+  git(root, '-c', 'user.name=claude-packs', '-c', 'user.email=claude-packs@localhost', 'commit', '--quiet', '-m', `${name}: the scaffold`);
+  console.log(`A new pack repository: ${root}`);
+  console.log(`  1. Edit packs/${name}/ (pack.json says who made it and its git url${repo ? '' : ': set repository.url'}).`);
+  console.log(`  2. Push it to your git host.`);
+  console.log(`  3. In a project: npx --no-install @thedecipherist/claude-packs add ${name} --from ${url}`);
+  return 0;
+}

package/lib/doctor.mjs

@@ -0,0 +1,126 @@
+// Checks a project's install: lock present, rule paths current, lesson checks pass their own
+// examples, every layout folder exists, hooks registered, and which managed files were edited.
+import { execFileSync, spawn } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { isModified, readLock } from './manifest.mjs';
+import { applyPaths } from './rules.mjs';
+import { coverage } from './coverage.mjs';
+import { tokenProblems } from './git-tokens.mjs';
+import { shapeProblems } from './shape-cli.mjs';
+import { symmetryProblems } from './symmetry-doctor.mjs';
+import { onceOnlyDoctor, useJscpd } from './once-only-report.mjs';
+import { proved, remember, selftestKey, sharedHash } from './selftest-cache.mjs';
+import { timingProblems } from './hook-timing.mjs';
+import { configProblems, sourceFilesOf } from './configs.mjs';
+import { hookProofProblems, paramLockProblems } from './hook-proof.mjs';
+import { ruleTestProblems } from './rule-tests.mjs';
+import { buildQueueProblems } from './build-queue.mjs';
+import { manifestProblems } from './pack-manifest.mjs';
+import { readPack } from './packs.mjs';
+import { hoverGateProblems, pageGateProblems } from './hover-gate.mjs';
+
+const SELFTEST_JOBS = Number(process.env.CLAUDE_PACKS_SELFTEST_JOBS ?? 4);
+const SELFTEST_S = Number(process.env.CLAUDE_PACKS_SELFTEST_S ?? 180);
+
+// installing: doctor run at the end of an install. What the project has yet to do (a rule's test, a parameter lock) is a note there: an install on
+// a project with code has not failed. The `doctor` command is red for it.
+export async function doctor(projectDir, log = console.log, { strict = false, fresh = false, installing = false } = {}) {
+  const claudeDir = join(projectDir, '.claude');
+  const lock = readLock(claudeDir);
+  const problems = [];
+  if (lock.packs.length === 0) problems.push('no packs installed (run `npx --no-install @thedecipherist/claude-packs init <packs>`)');
+  else problems.push(...configProblems(projectDir, lock.packs, log)); // the configuration installed, and a pack it does not take (0.10.0)
+
+  const theirs = new Set(
+    readdirSync(join(claudeDir, 'rules'))
+      .map((f) => join('.claude', 'rules', f))
+      .filter((rel) => lock.files[rel] === undefined || isModified(projectDir, rel, lock)),
+  );
+  const { stale } = await applyPaths(projectDir, { checkOnly: true, skip: theirs });
+  if (stale) problems.push(`${stale} rule(s) have paths out of date with layout.json (run update)`);
+
+  const layout = JSON.parse(readFileSync(join(claudeDir, 'layout.json'), 'utf8'));
+  for (const f of Object.values(layout.folders)) if (!f.planned && !existsSync(join(projectDir, f.path))) problems.push(`layout folder missing: ${f.path}/`);
+
+  const settings = existsSync(join(claudeDir, 'settings.json')) ? readFileSync(join(claudeDir, 'settings.json'), 'utf8') : '';
+  if (!settings.includes('.claude/hooks/lesson-checks.mjs')) problems.push('hooks not registered in .claude/settings.json');
+
+  try {
+    execFileSync('node', [join(claudeDir, 'hooks', 'lesson-checks.mjs'), '--selftest'], {
+      env: { ...process.env, CLAUDE_PROJECT_DIR: projectDir },
+      stdio: 'pipe',
+    });
+  } catch (e) {
+    problems.push(`lesson checks fail their own examples:\n${String(e.stderr)}`);
+  }
+
+  useJscpd(projectDir); // once-only's and making-check's selftests need the detector (0.9.0)
+  // Every hook proves its own law (Sub37 WB-4), all at once; a hook without a selftest is noted.
+  const hooks = readdirSync(join(claudeDir, 'hooks')).filter((f) => /\.(mjs|py)$/.test(f) && f !== 'lesson-checks.mjs').sort();
+  // Run SELFTEST_JOBS at a time with SELFTEST_S each: all at once with 60 s each, the heavy ones (git repos and worktrees) were killed
+  // under load and read as failing, with no output (the kit's own suite failed a different few each run while agents built).
+  // A selftest that passed is not run again while what it ran on is the same (lib/selftest-cache.mjs, KWB-41).
+  const shared = sharedHash(claudeDir, JSON.parse(readFileSync(join(claudeDir, 'layout.json'), 'utf8')).guards);
+  const one = (hook) => {
+    const file = join(claudeDir, 'hooks', hook);
+    if (!readFileSync(file, 'utf8').includes('--selftest')) return Promise.resolve({ hook, missing: true });
+    const key = selftestKey(file, shared);
+    if (!fresh && proved(key)) return Promise.resolve({ hook, code: 0, unchanged: true });
+    return new Promise((done) => {
+      const child = spawn(hook.endsWith('.py') ? 'python3' : 'node', [file, '--selftest'], { env: { ...process.env, CLAUDE_PROJECT_DIR: projectDir, PYTHONDONTWRITEBYTECODE: '1' }, stdio: ['ignore', 'pipe', 'pipe'] });
+      let out = '', timedOut = false;
+      const timer = setTimeout(() => { timedOut = true; child.kill(); }, SELFTEST_S * 1000);
+      child.stdout.on('data', (d) => { out += d; });
+      child.stderr.on('data', (d) => { out += d; });
+      child.on('error', (e) => { clearTimeout(timer); done({ hook, code: 1, err: e.message }); });
+      child.on('close', (code) => { clearTimeout(timer); if (code === 0 && !timedOut) remember(key); done({ hook, code, timedOut, err: out.trim().split('\n').slice(-4).join('\n') }); });
+    });
+  };
+  const results = [];
+  for (let i = 0; i < hooks.length; i += SELFTEST_JOBS) results.push(...await Promise.all(hooks.slice(i, i + SELFTEST_JOBS).map(one)));
+  const same = results.filter((r) => r.unchanged).length;
+  if (same) log(`  selftests: ${same} of ${results.length} unchanged, not run again (doctor --fresh runs them all)`);
+  for (const r of results) {
+    if (r.missing) log(`  note: ${r.hook} has no --selftest`);
+    else if (r.timedOut) problems.push(`${r.hook}'s selftest timed out after ${SELFTEST_S} s (the machine is loaded, or the selftest hangs)`);
+    else if (r.code !== 0) problems.push(`${r.hook} fails its selftest${r.err ? `:\n${r.err}` : ''}`);
+  }
+  problems.push(...symmetryProblems(projectDir, log));
+  for (const rel of Object.keys(lock.files).filter((f) => f.endsWith('SKILL.md'))) {
+    const abs = join(projectDir, rel);
+    if (!existsSync(abs)) continue;
+    const text = readFileSync(abs, 'utf8');
+    if (text.length > 8000) problems.push(`${rel} is ${text.length} characters (keep skills under 8,000; compaction cuts at 20,000)`);
+    if (!/^description:\s*Use /m.test(text)) problems.push(`${rel}: description must start with "Use when…" and list triggers only`);
+  }
+
+  for (const name of lock.packs) problems.push(...manifestProblems(readPack(name), name));
+  problems.push(...await hookProofProblems(projectDir, settings)); // a guard that fails open fails silently (0.18.0)
+  const toDo = (found) => (installing ? found.forEach((f) => log(`  note: ${f}`)) : problems.push(...found));
+  toDo(paramLockProblems(projectDir)); // a lock holding no ids protects nothing, and says nothing (KF-15)
+  toDo(buildQueueProblems(projectDir, layout)); // a queue that is not there queues nothing (KF-1)
+  problems.push(...await pageGateProblems(projectDir, layout)); // UI code is proved rendered (0.17.0)
+  problems.push(...await hoverGateProblems(projectDir, layout)); // UI code needs a declared hover gate (0.10.1, Stellix B-261)
+  problems.push(...tokenProblems(projectDir, layout.siblings ?? []));
+  problems.push(...shapeProblems(projectDir, lock.packs)); // the shape law: a synth has design/shape.json, and its rows keep the contract
+  problems.push(...onceOnlyDoctor(projectDir, log)); // making's cost per turn, the duplicate count (0.9.0)
+  problems.push(...timingProblems(projectDir, log)); // each hook's median and worst from .claude/hooks.log; a median over 500 ms is red (KWB-24)
+
+  const cov = await coverage(projectDir, sourceFilesOf(projectDir, lock.packs)); // the configuration says what is source (KWB-32)
+  const ruleTests = ruleTestProblems(projectDir, layout, cov); // a rule's own test can be missing for a whole build (KF-31)
+  if (layout.ruleTests) toDo(ruleTests); // a new law never turns an installed project red: the key in layout.json is the choice
+  else ruleTests.forEach((f) => log(`  note: ${f}\n    To be held to this, add "ruleTests": {} to .claude/layout.json.`));
+  if (cov.sourceCount > 0) {
+    const say = (msg) => (strict ? problems.push(msg) : log(`  note: ${msg}`));
+    if (cov.deadRules.length) say(`${cov.deadRules.length} rule(s) match no file yet, so they never fire: ${cov.deadRules.slice(0, 8).join(', ')}${cov.deadRules.length > 8 ? ', …' : ''}`);
+    if (cov.waitingRules.length) log(`  note: ${cov.waitingRules.length} rule(s) wait for their first file: their folders hold nothing yet`);
+    if (cov.uncovered.length) say(`${cov.uncovered.length} source file(s) no rule covers (outside the structure?): ${cov.uncovered.slice(0, 8).join(', ')}${cov.uncovered.length > 8 ? ', …' : ''}`);
+  }
+
+  const edited = Object.keys(lock.files).filter((rel) => isModified(projectDir, rel, lock));
+  for (const rel of edited) log(`  note: you edited ${rel} (updates keep your version)`);
+  for (const p of problems) log(`  PROBLEM: ${p}`);
+  log(problems.length ? `${problems.length} problem(s)` : `OK: ${lock.packs.join(', ')}`);
+  return problems.length ? 1 : 0;
+}

package/lib/fix-plan.mjs

@@ -0,0 +1,72 @@
+// claude-packs fix: a scan's findings as a work order Claude can follow, step by step, with the kit's own laws. Each finding is a box to tick,
+// in the order a senior engineer would fix them: what can leak first, what loses data next, then the copies, then the rest.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { kitCommand } from './kit-command.mjs';
+import { scan } from './scan.mjs';
+
+const pointerOf = (dir) => join(tmpdir(), `claude-packs-last-scan-${createHash('sha256').update(resolve(dir)).digest('hex').slice(0, 12)}`);
+export const rememberScan = (dir, json) => writeFileSync(pointerOf(dir), json);
+
+const box = (text) => `- [ ] ${text}`;
+const code = (text) => `\`${String(text).replace(/`/g, "'")}\``;
+
+function checksOf(results, kind) {
+  return results.filter((r) => r.kind === kind).sort((a, b) => b.hits.length - a.hits.length)
+    .flatMap((r) => [`### ${r.id} (${r.hits.length})`, '', r.why, r.rule ? `Law: \`${r.rule}\`` : '', '', ...r.hits.map((h) => box(`${h.file}:${h.line}: ${code(h.text)}`)), ''].filter((l, i, a) => l !== '' || a[i - 1] !== ''));
+}
+
+const section = (title, intro, lines) => (lines.length ? [`## ${title}`, '', intro, '', ...lines, ''] : []);
+
+function repeatBox(r) {
+  const differs = r.parameters?.length ? ` Differs in: ${r.parameters.map(code).join(', ')}.` : '';
+  return box(`${r.copies} copies of ${r.what}: ${r.at.join(', ')}. Make it ${r.template}.${differs}`);
+}
+
+export function planText(dir, s) {
+  const CLI = kitCommand(dir);
+  const packs = [...(s.pick?.packs ?? []).map((p) => p.pack)];
+  const howMany = (s.secrets?.length ?? 0) + (s.results ?? []).reduce((n, r) => n + r.hits.length, 0) + (s.repeats?.length ?? 0) + (s.near?.length ?? 0) + (s.remade?.length ?? 0) + (s.longFiles?.length ?? 0);
+  return [
+    '# Fix plan', '',
+    `A work order from the scan of ${dir}: ${howMany} finding(s). Work it from the top; each box is one fix. Skill: \`fix-from-scan\`.`, '',
+    '## How to work this plan', '',
+    '- A finding is a candidate, not a fact. Read the code first. If it is not real, tick the box and say why on its line.',
+    '- One work branch per section, pushed from its first commit. Commit each fix by name.',
+    '- A bug gets a failing test first (`bug-fix-starts-red`). Run only the tests a change reaches; the whole suite once, when the section is done, then land it.',
+    '- Never change a behaviour to quiet a finding. Ask when the fix would change what users see.', '',
+    '## 0. Install the kit', '',
+    box(`${CLI} init --auto${s.pick?.config ? ` (configuration ${s.pick.config}${packs.length ? `, packs ${packs.join(', ')}` : ''})` : ''}`),
+    box('Fit `.claude/layout.json` to the project, then run `doctor --strict`'), '',
+    ...section('1. Secrets', 'Any that is real has leaked: rotate it first, then move it to an ignored `.env` and read it by name.', (s.secrets ?? []).map((x) => box(`${x.file}:${x.line}: ${x.name}`))),
+    ...section('2. Security', 'What an attacker can reach.', checksOf(s.results ?? [], 'security')),
+    ...section('3. Failures and lost data', 'What breaks in production, or loses work silently.', checksOf(s.results ?? [], 'failures and lost data')),
+    ...section('4. Copies become templates', 'Largest first, with `make-it-a-template`: take the copies out, then write the one template, then test it once.', [
+      ...(s.near ?? []).map((n) => box(`${n.file}:${n.line} is close to ${n.other}:${n.from}-${n.to} (${n.matched} of ${n.of} statements). Make it one function.`)),
+      ...(s.repeats ?? []).map(repeatBox),
+      ...(s.remade ?? []).map((m) => box(`${m.name} is defined ${m.at.length} times: ${m.at.join(', ')}. Keep one and call it, or name each for its job.`)),
+    ]),
+    ...section('5. Quality', 'Group by check: one law, fixed everywhere at once.', checksOf(s.results ?? [], 'quality')),
+    ...section('6. Long files', 'Split by what the code does, so each file has one job.', (s.longFiles ?? []).map((f) => box(f))),
+    ...section('7. Repo weight', 'Move these out of git: to object storage, a release, or the bin.', [...(s.weight?.big ?? []).map((b) => box(`${b.file}: ${b.mb} MB`)), ...(s.weight?.rootImages ?? []).map((f) => box(f))]),
+    ...section('8. Public text', 'Read it as the author. Dates and quotes that are facts stay.', checksOf(s.results ?? [], 'public text')),
+    '## 9. What no check can see', '',
+    box(`Run the review: ${code(`${CLI} scan --prompt`)}. Its findings become boxes here.`), '',
+    '## Done when', '',
+    `Every box is ticked, and ${code(`${CLI} scan`)} finds nothing new. What it still lists has its reason written here.`, '',
+  ].join('\n');
+}
+
+export async function fixPlan(dir, { from = null, out = null, log = console.log } = {}) {
+  const pointer = pointerOf(dir);
+  let json = from ?? (existsSync(pointer) ? readFileSync(pointer, 'utf8').trim() : null);
+  if (!json || !existsSync(json)) json = join((await scan(dir, { log: () => {} })).copy, 'claude-packs-scan.json');
+  const file = out ?? join(dir, '.claude/fix-plan.md');
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, planText(dir, JSON.parse(readFileSync(json, 'utf8'))));
+  log(`Fix plan: ${file}`);
+  log('Give it to Claude: "work through .claude/fix-plan.md" (skill: fix-from-scan).');
+  return file;
+}

package/lib/found-folders.mjs

@@ -0,0 +1,25 @@
+// What a first install learns from the project: the folders its source already lives in. A layout written from a template alone leaves them out, and then
+// folder-law refuses a new file in the project's own folder (KWB-83). Only the top level: `lib/`, never `lib/net/`.
+import { SOURCE } from '../packs/base/hooks/lib/dup.mjs';
+import { isContent } from '../packs/base/hooks/lib/content.mjs';
+import { filesOf } from './scan.mjs';
+
+// Not the project's own source: hidden folders, what is built or fetched, what is another project's, and folders the layout already has by name.
+const NOT_THE_PROJECTS = /^(?:\..*|node_modules|vendor|third_party|thirdparty|external|extern|deps|target|build|out|dist|coverage|JUCE|cmake-build.*|docs|tools)$/;
+
+export function foundFolders(projectDir, sourceFiles, known = []) {
+  const source = sourceFiles ? new RegExp(sourceFiles, 'i') : SOURCE;
+  const folders = filesOf(projectDir).filter((f) => f.includes('/') && source.test(f) && !isContent(f)).map((f) => f.split('/')[0]);
+  return [...new Set(folders)].filter((f) => !NOT_THE_PROJECTS.test(f) && !known.includes(f)).sort();
+}
+
+// A seed layout with those folders in it. A complete layout has been fitted by hand, and stays as it is.
+export function withFoundFolders(projectDir, seed, config, log) {
+  if (seed?.complete) return seed;
+  const known = Object.values({ ...config.layout?.folders, ...seed?.folders }).map((f) => f.path.split('/')[0]);
+  const found = foundFolders(projectDir, config.sourceFiles, known);
+  if (!found.length) return seed;
+  log(`  layout: your source is in ${found.map((f) => `${f}/`).join(', ')}, so the layout has ${found.length > 1 ? 'them' : 'it'}`);
+  const folders = Object.fromEntries(found.map((f) => [f, { path: f, purpose: 'source, found at install' }]));
+  return { ...seed, folders: { ...folders, ...seed?.folders } };
+}

package/lib/git-tokens.mjs

@@ -0,0 +1,64 @@
+// Doctor's token sweep (Sub37 WB-3): every git repo that belongs to the project, its nested clones
+// (build/_deps, vendored repos) and the repos in its sibling folders, has its .git/config read for
+// a URL that carries a secret or a bare GitHub token. The token itself is never printed.
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+const SECRET_URL = /\b[a-z][\w+.-]*:\/\/([^\s/@'"]+)@\S*/gi;
+const SECRET_USER = /:|^(gh[pousr]_|github_pat_|glpat-|x-access-token|oauth2)/i;
+const BARE = /\b(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_\w{20,})\b/;
+const SKIP = /^(node_modules|\.git|worktrees|\.claude-packs-backup)$/;
+
+function configOf(dir) {
+  const dotGit = join(dir, '.git');
+  try {
+    if (statSync(dotGit).isDirectory()) return join(dotGit, 'config');
+    const gitdir = resolve(dir, readFileSync(dotGit, 'utf8').match(/^gitdir:\s*(.+)$/m)[1].trim());
+    const common = existsSync(join(gitdir, 'commondir')) ? resolve(gitdir, readFileSync(join(gitdir, 'commondir'), 'utf8').trim()) : gitdir;
+    return join(common, 'config');
+  } catch {
+    return null;
+  }
+}
+
+function repos(dir, depth, out) {
+  if (existsSync(join(dir, '.git'))) out.push(dir);
+  if (depth === 0) return;
+  let entries = [];
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) if (e.isDirectory() && !SKIP.test(e.name)) repos(join(dir, e.name), depth - 1, out);
+}
+
+export function findings(text) {
+  const out = [];
+  for (const line of text.split('\n')) {
+    const url = [...line.matchAll(SECRET_URL)].find((m) => SECRET_USER.test(m[1]));
+    if (url) out.push(`${line.trim().split(/\s*=/)[0]} = ${url[0].replace(/:\/\/[^@]+@/, '://***@')}`);
+    else if (BARE.test(line)) out.push(`${line.trim().split(/\s*=/)[0]} = (a GitHub token)`);
+  }
+  return out;
+}
+
+export function tokenProblems(projectDir, siblings = []) {
+  const found = [];
+  repos(projectDir, 4, found);
+  for (const s of siblings) {
+    const dir = resolve(projectDir, s);
+    if (!existsSync(dir)) continue;
+    if (existsSync(join(dir, '.git'))) found.push(dir);
+    else repos(dir, 1, found);
+  }
+  const seen = new Set();
+  const problems = [];
+  for (const dir of found) {
+    const cfg = configOf(dir);
+    if (!cfg || !existsSync(cfg)) continue;
+    const real = realpathSync(cfg);
+    if (seen.has(real)) continue;
+    seen.add(real);
+    const hits = findings(readFileSync(cfg, 'utf8'));
+    const name = relative(projectDir, join(dir, '.git', 'config')).replace(/\\/g, '/');
+    if (hits.length) problems.push(`${name} holds a token (${hits.join('; ')}); set the URL back to the plain one and rotate the token`);
+  }
+  return problems;
+}

package/lib/global.mjs

@@ -0,0 +1,125 @@
+// `claude-packs global add|remove|doctor`: the only things this package ever puts in ~/.claude. The global
+// part is exactly three pieces; everything else is per project:
+//   - latest-versions: the skill and its version-pin-guard hook ("check for the newest release" applies to every
+//     project, including new ones with no packs yet);
+//   - gnu-shell and shell-traps. Global by design: they fix this machine's shell for Claude, not any project's rules.
+// Same never-overwrite law as project installs. A hook already there, byte for byte the package's, is taken over, and
+// its settings entry with it, never doubled. The house's hand-installed Python forerunners (~/.claude/hooks/
+// shell-traps.py and gnu-shell.py) lose their settings entries to the Node hooks; their files are left where they are.
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const SRC = fileURLToPath(new URL('../global/', import.meta.url));
+export const FILES = [
+  ['skills/latest-versions/SKILL.md', 'skills/latest-versions/SKILL.md'],
+  ['hooks/version-pin-guard.mjs', 'hooks/claude-packs/version-pin-guard.mjs'],
+  ['../packs/base/hooks/lib/shell-writes.mjs', 'hooks/claude-packs/lib/shell-writes.mjs'],
+  ['../packs/base/hooks/lib/program-writes.mjs', 'hooks/claude-packs/lib/program-writes.mjs'],
+  ['../packs/base/hooks/lib/program-read.mjs', 'hooks/claude-packs/lib/program-read.mjs'],
+  ['hooks/shell-traps.mjs', 'hooks/shell-traps.mjs'],
+  ['hooks/gnu-shell.mjs', 'hooks/gnu-shell.mjs'],
+];
+// Each hook's settings entry.
+const HOOKS = [
+  { rel: 'hooks/claude-packs/version-pin-guard.mjs', event: 'PreToolUse', matcher: 'Write|Edit|MultiEdit|Bash', command: (claude) => `node "${join(claude, 'hooks/claude-packs/version-pin-guard.mjs')}"`, timeout: 10 },
+  { rel: 'hooks/shell-traps.mjs', event: 'PreToolUse', matcher: 'Bash', command: () => 'node "$HOME/.claude/hooks/shell-traps.mjs"', timeout: 10 },
+  { rel: 'hooks/gnu-shell.mjs', event: 'SessionStart', command: () => 'node "$HOME/.claude/hooks/gnu-shell.mjs"', timeout: 10 },
+];
+// The Python forerunners: their settings entries are the package's to replace.
+const FORERUNNERS = ['hooks/shell-traps.py', 'hooks/gnu-shell.py'];
+const sha = (p) => createHash('sha256').update(readFileSync(p)).digest('hex');
+
+function paths(home) {
+  const claude = join(home ?? homedir(), '.claude');
+  return { claude, lock: join(claude, 'claude-packs-global.json'), settings: join(claude, 'settings.json') };
+}
+
+function readJson(file, fallback) {
+  if (!existsSync(file)) return fallback;
+  try { return JSON.parse(readFileSync(file, 'utf8')); } catch (e) { throw new Error(`${file} is not valid JSON (${e.message}); fix it first, nothing was changed`); }
+}
+
+const ours = (h) => typeof h?.command === 'string' && [...HOOKS.map((x) => x.rel), ...FORERUNNERS].some((rel) => h.command.includes(`.claude/${rel}`));
+
+function writeSettings(file, settings, add, claude) {
+  settings.hooks = { ...(settings.hooks ?? {}) };
+  for (const event of Object.keys(settings.hooks)) {
+    settings.hooks[event] = (settings.hooks[event] ?? []).map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !ours(h)) })).filter((g) => g.hooks.length > 0);
+  }
+  if (add) {
+    for (const h of HOOKS) {
+      const groups = (settings.hooks[h.event] ??= []);
+      let group = groups.find((g) => g.matcher === h.matcher && g._claudePacks);
+      if (!group) groups.push((group = { ...(h.matcher ? { matcher: h.matcher } : {}), _claudePacks: true, hooks: [] }));
+      group.hooks.push({ type: 'command', command: h.command(claude), ...(h.timeout ? { timeout: h.timeout } : {}) });
+    }
+    for (const groups of Object.values(settings.hooks)) for (const g of groups) delete g._claudePacks;
+  }
+  for (const event of Object.keys(settings.hooks)) if (settings.hooks[event].length === 0) delete settings.hooks[event];
+  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`);
+}
+
+export function globalAdd({ home, force = false, log = console.log } = {}) {
+  const p = paths(home);
+  const settings = readJson(p.settings, {});
+  const lock = readJson(p.lock, { files: {} });
+  for (const [from, to] of FILES) {
+    const src = join(SRC, from);
+    const dest = join(p.claude, to);
+    mkdirSync(dirname(dest), { recursive: true });
+    const theirs = existsSync(dest) && sha(dest) !== sha(src) && lock.files[to] !== sha(dest);
+    if (theirs && !force) {
+      copyFileSync(src, `${dest}.pack-new`);
+      log(`kept your ${to}; the package version is beside it as ${to}.pack-new`);
+      continue;
+    }
+    copyFileSync(src, dest);
+    lock.files[to] = sha(dest);
+  }
+  writeSettings(p.settings, settings, true, p.claude);
+  writeFileSync(p.lock, `${JSON.stringify(lock, null, 2)}\n`);
+  log(`OK: latest-versions (skill and version-pin-guard), gnu-shell and shell-traps installed in ${p.claude}`);
+  return 0;
+}
+
+export function globalRemove({ home, log = console.log } = {}) {
+  const p = paths(home);
+  const settings = readJson(p.settings, {});
+  const lock = readJson(p.lock, { files: {} });
+  for (const [, to] of FILES) {
+    const dest = join(p.claude, to);
+    if (existsSync(dest) && lock.files[to] === sha(dest)) rmSync(dest);
+    else if (existsSync(dest)) log(`kept ${to}: you edited it`);
+  }
+  for (const dir of ['skills/latest-versions', 'hooks/claude-packs/lib', 'hooks/claude-packs']) {
+    const d = join(p.claude, dir);
+    try { rmSync(d, { recursive: false }); } catch { /* not empty or gone */ }
+  }
+  writeSettings(p.settings, settings, false, p.claude);
+  rmSync(p.lock, { force: true });
+  log('OK: global latest-versions removed');
+  return 0;
+}
+
+export function globalDoctor({ home, log = console.log } = {}) {
+  const p = paths(home);
+  const problems = [];
+  for (const [, to] of FILES) if (!existsSync(join(p.claude, to))) problems.push(`missing ${to}`);
+  const settings = readJson(p.settings, {});
+  for (const h of HOOKS) {
+    const wired = (settings.hooks?.[h.event] ?? []).some((g) => (g.hooks ?? []).some((x) => x.command?.includes(`.claude/${h.rel}`)));
+    if (!wired) problems.push(`${h.rel} is not in ~/.claude/settings.json (${h.event})`);
+    const hook = join(p.claude, h.rel);
+    const r = existsSync(hook) && spawnSync(h.rel.endsWith('.py') ? 'python3' : 'node', [hook, '--selftest'], { env: { ...process.env, PYTHONDONTWRITEBYTECODE: '1' } });
+    if (r && r.status !== 0) problems.push(`${h.rel} --selftest fails`);
+  }
+  if (problems.length) { problems.forEach((x) => log(`- ${x}`)); return 1; }
+  log('OK: global latest-versions');
+  return 0;
+}