@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/global/skills/latest-versions/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: latest-versions
+description: Use when starting a new project, or adding, choosing, pinning or upgrading any library, tool, compiler, runtime, SDK, GitHub Action or container image.
+---
+
+# Latest versions
+
+Your knowledge of versions is out of date by definition. Every version Stellix and every other project uses is looked up today, from the project's own release source, and written down before it is used.
+
+<constraints>
+Always do:
+- Look up the current stable release before you choose, add, pin or upgrade anything: a library, framework, tool, compiler, runtime, SDK, GitHub Action or container base image.
+- Take the version from a primary source, in this order:
+  1. the project's GitHub releases or tags page;
+  2. its official site or changelog;
+  3. its registry page (npm, PyPI, crates.io, pkg.go.dev, Homebrew, Docker Hub).
+  Blog posts, tutorials and AI answers are not sources.
+- Record every lookup in `docs/versions.md`, in the project being worked on, one row per dependency:
+  `| name | latest stable | date checked YYYY-MM-DD | source URL | version used | decision |`
+- Use the latest stable release unless there is a stated reason not to. Write that reason in the decision column (for example "9.0.4 latest; staying on 8.0.4 until F4").
+- Read the release notes between the version used and the latest. Name any breaking change in the decision column.
+- Pin exact versions: a full tag, release or commit, never a range or `latest`, in build files (CMake `GIT_TAG`, Docker `FROM`, Actions `uses`). Lockfiles do the pinning for package managers.
+- At the start of a new project, run this for the whole stack before the first build file is written.
+
+Never do:
+- Write a version number from memory, from an older project, or from an example in docs.
+- Pick a pre-release, beta, RC or nightly unless the user asks for one.
+- Treat a row older than 14 days as current. Look it up again and update the date.
+- Edit a version pin before its row exists. The `version-pin-guard` hook refuses pins that `docs/versions.md` has not checked within 14 days.
+</constraints>
+
+## How
+
+1. List what the change needs: each dependency, tool and image.
+2. For each one, fetch its releases page (WebFetch, or `gh release list -R owner/repo -L 5` / `gh api repos/owner/repo/releases/latest`). Note the newest non-pre-release and its date.
+3. Add or update its row in `docs/versions.md`. Create the file with this header if it is missing:
+
+   ```
+   # Versions
+   Checked by the latest-versions skill. One row per dependency; re-check after 14 days.
+
+   | name | latest stable | checked | source | used | decision |
+   |---|---|---|---|---|---|
+   ```
+
+4. Then write the pin.
+5. Tell the user, in one line per dependency, which version you chose and why, and flag any major jump.
+
+The name in the row must be the name the pin uses: the npm package name, the CMake FetchContent name, the image name or the Action `owner/repo`. That's how the hook matches the pin to its row.

package/lib/backup.mjs

@@ -0,0 +1,34 @@
+// Before every install or update, copies the files the package writes into (CLAUDE.md,
+// settings.json, layout.json, the lock) to .claude/.claude-packs-backup/<timestamp>/.
+// Keeps the last 5 backups.
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+const DIR = join('.claude', '.claude-packs-backup');
+const KEEP = 5;
+const FILES = ['CLAUDE.md', '.claude/settings.json', '.claude/layout.json', '.claude/claude-packs.lock.json'];
+
+export function backup(projectDir) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const target = join(projectDir, DIR, stamp);
+  for (const rel of FILES) {
+    const src = join(projectDir, rel);
+    if (!existsSync(src)) continue;
+    mkdirSync(join(target, rel, '..'), { recursive: true });
+    copyFileSync(src, join(target, rel));
+  }
+  const all = existsSync(join(projectDir, DIR)) ? readdirSync(join(projectDir, DIR)).sort() : [];
+  for (const old of all.slice(0, Math.max(0, all.length - KEEP))) rmSync(join(projectDir, DIR, old), { recursive: true, force: true });
+  return join(DIR, stamp);
+}
+
+// Adds the backup folder, the hooks' run state (.claude/state: frozen list, last test log) and brief-guard's refusal counter
+// (.claude/usage.log, 0.9.2) to .gitignore (appends; never rewrites the file).
+export function ensureGitignore(projectDir) {
+  const file = join(projectDir, '.gitignore');
+  for (const line of [`${DIR.replace(/\\/g, '/')}/`, '.claude/state/', '.claude/usage.log', '.claude/hooks.log', '.claude/logs/']) {
+    const text = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    if (text.split('\n').includes(line)) continue;
+    appendFileSync(file, `${text && !text.endsWith('\n') ? '\n' : ''}${line}\n`);
+  }
+}

package/lib/claude-md.mjs

@@ -0,0 +1,58 @@
+// Writes the generated layout section into the project's CLAUDE.md, between markers.
+// Everything outside the markers is the user's and is never touched.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const START = '<!-- claude-packs:start -->';
+const END = '<!-- claude-packs:end -->';
+
+// The house rules after the folders are the configuration's preamble (configurations/<name>/config.json, 0.10.0).
+function section(layout, packNames, preamble) {
+  // Folders no kind points at are listed by purpose; the rest appear once, in the kinds list.
+  const used = new Set(Object.values(layout.kinds ?? {}).map((k) => k.in));
+  const folders = Object.entries(layout.folders)
+    .filter(([name]) => !used.has(name) && name !== 'src')
+    .sort(([, a], [, b]) => a.path.localeCompare(b.path))
+    .map(([, f]) => `  - \`${f.path}/\`: ${f.purpose}`);
+  return [
+    START,
+    '<!-- Generated by claude-packs from .claude/layout.json. Edit that file and run `npx --no-install @thedecipherist/claude-packs update`; edits here are replaced. -->',
+    '## Project layout',
+    '',
+    '<constraints>',
+    'Always do:',
+    '- Put every kind of thing in its one place. The rules, checks and skills for it load only there:',
+    ...kindLines(layout),
+    ...(folders.length ? ['- The other folders:', ...folders] : []),
+    ...preamble.always.map((l) => `- ${l}`),
+    '',
+    'Never do:',
+    ...preamble.never.map((l) => `- ${l}`),
+    '</constraints>',
+    '',
+    ...commandLines(layout),
+    `Installed packs: ${packNames.join(', ')}.`,
+    END,
+  ].join('\n');
+}
+
+function kindLines(layout) {
+  return Object.values(layout.kinds ?? {}).map((k) => `  - ${k.what} → \`${layout.folders?.[k.in] ? `${layout.folders[k.in].path}/` : k.in}\``);
+}
+
+function commandLines(layout) {
+  const entries = Object.entries(layout.commands ?? {});
+  if (entries.length === 0) return [];
+  return ['## Project commands', '', 'Skills and checks run these; use them, not the raw tools:', ...entries.map(([k, v]) => `- ${k}: \`${v}\``), ''];
+}
+
+export function writeClaudeMd(projectDir, layout, packNames, preamble) {
+  const file = join(projectDir, 'CLAUDE.md');
+  const block = section(layout, packNames, preamble);
+  let text = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  const s = text.indexOf(START);
+  const e = text.indexOf(END);
+  if (s !== -1 && e > s) text = text.slice(0, s) + block + text.slice(e + END.length);
+  else text = `${text.trimEnd()}${text.trim() ? '\n\n' : ''}${block}\n`;
+  writeFileSync(file, text);
+}

package/lib/config-cli.mjs

@@ -0,0 +1,36 @@
+// The `configs` and `config <name>` commands, and doctor's configuration line (0.10.0, STEP 3 item 1).
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { allowedPacks, describeConfigs, describeSwitch, packsFor, readConfig, resolveConfig } from './configs.mjs';
+import { doctor } from './doctor.mjs';
+import { readLock } from './manifest.mjs';
+import { sync } from './sync.mjs';
+
+export { describeConfigs, readConfig };
+
+const layoutOf = (dir) => {
+  const file = join(dir, '.claude', 'layout.json');
+  return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : null;
+};
+
+export const layoutConfiguration = (dir) => layoutOf(dir)?.configuration ?? null;
+
+// Switch a project to configuration `name`: the packs it has that the new one takes stay; with none left, the new one's
+// default packs. What changes is printed first; --dry-run stops there.
+export async function switchConfig(dir, name, installed, { force = false, dryRun = false, log = console.log } = {}) {
+  if (!name) throw new Error('name the configuration: `config <name>` (`configs` lists them)');
+  if (installed.length === 0) throw new Error('nothing installed here; run `init --config <name>` first');
+  const to = readConfig(name);
+  const layout = layoutOf(dir) ?? { folders: {} };
+  const { config: from } = resolveConfig({ layout, packs: installed });
+  const fromSources = packsFor(from, installed);
+  const kept = installed.filter((p) => p === 'base' || (allowedPacks(to).includes(p) && !from.packs.always.includes(p)));
+  const chosen = kept.some((p) => p !== 'base') ? kept : [...kept, ...to.packs.default];
+  const toSources = packsFor(to, chosen);
+  const lines = describeSwitch(from, fromSources, to, toSources, { ...layout, disable: [...(layout.disable ?? [])] }, Object.keys(readLock(join(dir, '.claude')).files));
+  for (const l of lines) log(l);
+  if (dryRun) { log('dry run: nothing changed'); return 0; }
+  if (lines.at(-1) === '  no change' && layout.configuration === to.name) return 0;
+  await sync(dir, chosen, { force, mkdirs: true, config: name, log });
+  return doctor(dir, log);
+}

package/lib/configs.mjs

@@ -0,0 +1,145 @@
+// Configurations (0.10.0, STEP 3; KWB-31): a kind of project, as data. configurations/<name>/config.json holds
+//   "packs":     { "always": [...], "choose": [...], "default": [...] }  the packs it always installs (base first), the ones
+//                a project may add, and the ones `init --config <name>` takes when none are named
+//   "layout":    { "folders", "concepts", "kinds" }   the layout template: the folder structure of that kind of project
+//   "hookOrder": { "<event> <matcher>": ["a.mjs", ...] }   the order its hooks run in, per settings entry (optional)
+//   "leaveOut":  ["rules/x.md", "hooks/y.mjs", ...]   pack items this configuration does not install (optional)
+//   "sourceFiles": "<regex>"   what doctor's coverage counts as source (optional; default C, C++ and shaders)
+//   "preamble":  { "always": [...], "never": [...] }  the house rules of its CLAUDE.md block
+// Its rules, hooks, checks and skills are its packs' (`configs` lists them). layout.json "configuration" names the one a
+// project has; `update` applies it; an install from before 0.10.0 gets the smallest configuration that takes its packs.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { customPacks, planFiles, readPack } from './packs.mjs';
+
+export const CONFIGS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'configurations');
+
+export function availableConfigs() {
+  return readdirSync(CONFIGS_DIR).filter((d) => existsSync(join(CONFIGS_DIR, d, 'config.json'))).sort();
+}
+
+export function readConfig(name) {
+  const file = join(CONFIGS_DIR, String(name), 'config.json');
+  if (!existsSync(file)) throw new Error(`unknown configuration "${name}" (available: ${availableConfigs().join(', ')})`);
+  return JSON.parse(readFileSync(file, 'utf8'));
+}
+
+// Every pack a configuration takes, always-installed first.
+export const allowedPacks = (config) => [...config.packs.always, ...config.packs.choose, ...customPacks()]; // a team's own pack goes with any configuration
+
+// The packs a project names, checked against its configuration: base first, then the configuration's own, then the chosen.
+export function packsFor(config, requested) {
+  const allowed = allowedPacks(config);
+  const bad = requested.filter((p) => !allowed.includes(p));
+  if (bad.length) throw new Error(`${bad.join(', ')} ${bad.length > 1 ? 'are' : 'is'} not in configuration ${config.name} (it takes: ${allowed.join(', ')})`);
+  const out = [...config.packs.always];
+  for (const p of requested) if (!out.includes(p)) out.push(p);
+  return out;
+}
+
+// The packs written in the lock and named in CLAUDE.md: base and the chosen ones; a configuration's own packs come with it.
+export const listedPacks = (config, sources) => sources.filter((p) => p === 'base' || !config.packs.always.includes(p));
+
+// The configuration of an install that names none: the smallest one that takes all its packs.
+export function inferConfig(packs) {
+  const fits = availableConfigs().map(readConfig).filter((c) => packs.every((p) => allowedPacks(c).includes(p)));
+  if (!fits.length) throw new Error(`no configuration takes the packs ${packs.join(', ')}; name one with --config`);
+  // The configuration that has a pack by default first, then one with no folder layout of its own, then the smallest.
+  const rank = (c) => [packs.some((p) => c.packs.default.includes(p)) ? 0 : 1, c.packs.always.length, allowedPacks(c).length];
+  return fits.sort((a, b) => rank(a).map((v, i) => v - rank(b)[i]).find(Boolean) ?? 0)[0];
+}
+
+// Which configuration an install uses: the one named now (--config), else layout.json's, else its packs'.
+export function resolveConfig({ named = null, layout = {}, packs = [] } = {}) {
+  if (named) return { config: readConfig(named), how: 'named' };
+  if (layout.configuration) return { config: readConfig(layout.configuration), how: 'layout' };
+  return { config: inferConfig(packs), how: 'packs' };
+}
+
+// What a configuration installs with these packs: every file, by its place in the project, and the items by kind.
+export function planOf(config, sources, layout = { folders: {}, disable: [] }) {
+  const optIn = sources.flatMap((s) => readPack(s).optIn ?? []).filter((i) => !(layout.enable ?? []).includes(i)); // opt-in: only when enabled
+  const lay = { ...layout, disable: [...(layout.disable ?? []), ...(config.leaveOut ?? []), ...optIn] };
+  const files = new Set();
+  for (const name of sources) for (const { rel } of planFiles(name, lay)) files.add(rel);
+  return files;
+}
+
+export function itemsOf(files) {
+  const by = { rules: [], hooks: [], checks: [], skills: [] };
+  for (const rel of files) {
+    const p = rel.replace(/\\/g, '/');
+    const skill = p.match(/(?:^|\/)\.claude\/skills\/([^/]+)\/SKILL\.md$/);
+    if (skill) by.skills.push(skill[1]);
+    else if (/^\.claude\/rules\/[^/]+\.md$/.test(p)) by.rules.push(p.split('/').pop());
+    else if (/^\.claude\/hooks\/[^/]+\.(mjs|py)$/.test(p)) by.hooks.push(p.split('/').pop());
+    else if (/^\.claude\/checks\/[^/]+\.json$/.test(p)) by.checks.push(p.split('/').pop());
+  }
+  for (const k of Object.keys(by)) by[k].sort();
+  return by;
+}
+
+export function describeConfigs(current = null) {
+  return availableConfigs().map((name) => {
+    const c = readConfig(name);
+    const all = [...c.packs.always, ...c.packs.choose];
+    const n = itemsOf(planOf(c, all));
+    const choose = c.packs.choose.length ? `; ${c.packs.choose.join(', ')} (to choose)` : '';
+    return [
+      `${name}${name === current ? '  (this project)' : ''}`,
+      `  ${c.description}`,
+      `  packs: ${c.packs.always.join(', ')} (always)${choose}${c.packs.default.length ? `; init takes ${c.packs.default.join(', ')}` : ''}`,
+      `  with every pack: rules ${n.rules.length}, hooks ${n.hooks.length}, checks ${n.checks.length}, skills ${n.skills.length}`,
+      `  folders: ${Object.values(c.layout?.folders ?? {}).map((f) => `${f.path}/`).join(' ') || '(its packs\')'}`,
+    ].join('\n');
+  }).join('\n\n');
+}
+
+// The lines `config <name>` prints: what the switch adds and takes away.
+// `installed`: the files the project's lock names (what it has now); without it, what `from` would install.
+export function describeSwitch(from, fromSources, to, toSources, layout, installed = null) {
+  const before = itemsOf(installed ? new Set(installed) : planOf(from, fromSources, layout));
+  const after = itemsOf(planOf(to, toSources, layout));
+  const lines = [`  ${from.name} -> ${to.name}`];
+  const fromListed = listedPacks(from, fromSources), toListed = listedPacks(to, toSources);
+  const added = toListed.filter((p) => !fromListed.includes(p)), dropped = fromListed.filter((p) => !toListed.includes(p));
+  if (added.length) lines.push(`  packs added: ${added.join(', ')}`);
+  if (dropped.length) lines.push(`  packs dropped: ${dropped.join(', ')}`);
+  for (const kind of Object.keys(before)) {
+    const plus = after[kind].filter((x) => !before[kind].includes(x)), minus = before[kind].filter((x) => !after[kind].includes(x));
+    if (plus.length) lines.push(`  ${kind} added (${plus.length}): ${plus.join(', ')}`);
+    if (minus.length) lines.push(`  ${kind} removed (${minus.length}): ${minus.join(', ')}`);
+  }
+  if (JSON.stringify(from.preamble) !== JSON.stringify(to.preamble)) lines.push('  CLAUDE.md preamble: changes');
+  const missing = Object.values(to.layout?.folders ?? {}).filter((f) => !Object.values(layout.folders ?? {}).some((g) => g.path === f.path));
+  if (missing.length && !layout.complete) lines.push(`  folders added from its template: ${missing.map((f) => `${f.path}/`).join(' ')}`);
+  return lines.length > 1 ? lines : [...lines, '  no change'];
+}
+
+// doctor's lines: the configuration installed, and what does not fit it.
+export function configProblems(dir, lockPacks, log) {
+  const file = join(dir, '.claude', 'layout.json');
+  if (!existsSync(file)) return [];
+  const layout = JSON.parse(readFileSync(file, 'utf8'));
+  let config;
+  try {
+    config = resolveConfig({ layout, packs: lockPacks }).config;
+  } catch (e) {
+    return [layout.configuration ? `layout.json names configuration "${layout.configuration}", which this kit does not have (${e.message})` : e.message];
+  }
+  log(`  configuration: ${config.name}${layout.configuration ? '' : ' (from its packs; `update` writes it into layout.json)'}`);
+  return lockPacks.filter((p) => !allowedPacks(config).includes(p)).map((p) => `pack ${p} is installed but configuration ${config.name} does not take it (\`config <name>\` switches; \`configs\` lists them)`);
+}
+
+// The configuration's "sourceFiles" as a RegExp, or undefined (coverage's default) when it names none or cannot be read.
+export function sourceFilesOf(dir, lockPacks) {
+  try {
+    const file = join(dir, '.claude', 'layout.json');
+    const layout = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+    const re = layout.sourceFiles ?? resolveConfig({ layout, packs: lockPacks }).config.sourceFiles;
+    return re ? new RegExp(re, 'i') : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/lib/coverage.mjs

@@ -0,0 +1,86 @@
+// "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 deadRules = rules.filter((r) => r.globs.length && !reachable.some((f) => matchesAny(f, r.globs))).map((r) => r.rule);
+  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, uncovered, 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,115 @@
+// 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 } from './hook-proof.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);
+
+export async function doctor(projectDir, log = console.log, { strict = false, fresh = 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 (!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)
+  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)
+  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.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;
+}