@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/lib/hook-proof.mjs

@@ -0,0 +1,45 @@
+// A hook that should refuse and does not (0.18.0: whenever a hook is supposed to exit 2 and it exits 0, it is caught). Only exit 2
+// blocks, so a guard fails open and silently. doctor sees three of the ways: a hook no settings entry runs (dispatch-once was that way for
+// a moment in 0.11.0); a hook that crashed since it last changed, from its exit code in .claude/hooks.log, where "changed" counts every
+// file in hooks/lib/, since most crashes are there (KF-40), and a crash no change answers is cleared by `logs clear` with its reason (KF-18);
+// and param-id-lock holding no ids in a unit with parameters (KF-15). A hook killed at its timeout leaves no line and is not seen.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ANSWERS, clearedAt, clearsOf } from './logs.mjs';
+
+const RUNNER = 'run-hooks.mjs';
+const hookName = (file) => file.replace(/\.(mjs|py)$/, '');
+
+// The time a hook last changed: its own file, or anything it shares in hooks/lib.
+const changedAt = (dir, file, libTimes) => Math.max(statSync(join(dir, file)).mtimeMs, ...libTimes);
+
+export function paramLockProblems(projectDir) {
+  const hook = join(projectDir, '.claude', 'hooks', 'param-id-lock.mjs');
+  if (!existsSync(hook)) return [];
+  const r = spawnSync('node', [hook, '--status'], { encoding: 'utf8', env: { ...process.env, CLAUDE_PROJECT_DIR: projectDir } });
+  return r.status === 0 ? [] : [r.stdout.trim() || r.stderr.trim()];
+}
+
+export async function hookProofProblems(projectDir, settingsText) {
+  const dir = join(projectDir, '.claude', 'hooks');
+  if (!existsSync(dir)) return [];
+  const hooks = readdirSync(dir).filter((f) => /\.(mjs|py)$/.test(f) && f !== RUNNER);
+  const problems = hooks.filter((f) => !settingsText.includes(`.claude/hooks/${f}`)).map((f) => `${f} is in .claude/hooks but no settings entry runs it, so it refuses nothing`);
+  const log = join(dir, 'lib', 'hook-log.mjs');
+  if (!existsSync(log)) return problems;
+  const { readHookLog } = await import(pathToFileURL(log).href);
+  const libTimes = readdirSync(join(dir, 'lib')).map((f) => statSync(join(dir, 'lib', f)).mtimeMs);
+  const clears = clearsOf(projectDir);
+  const crashed = new Map();
+  for (const row of readHookLog(projectDir, { rotated: true })) {
+    const file = hooks.find((f) => hookName(f) === row.hook);
+    if (!file || ANSWERS.has(String(row.code))) continue;
+    if (Date.parse(row.time) > changedAt(dir, file, libTimes) && row.time > clearedAt(clears, row.hook)) crashed.set(file, (crashed.get(file) ?? 0) + 1);
+  }
+  for (const [f, n] of crashed) {
+    problems.push(`${f} crashed on ${n} call(s) since it last changed: those calls were not judged (\`logs crashes\`). Once fixed or superseded: \`logs clear ${hookName(f)} fixed|superseded "<why>"\``);
+  }
+  return problems;
+}

package/lib/hook-timing.mjs

@@ -0,0 +1,42 @@
+// doctor's hook timing (KWB-24): every hook writes one line per call to .claude/hooks.log (packs/base/hooks/lib/hook-log.mjs,
+// lib/house.py's log_hook); per hook, the median and the worst of its last 100 calls. A hook whose MEDIAN is over 500 ms is a
+// red check: the median is what every call pays, so a slow median is a slow hook. The worst is printed, never judged: one
+// call on a loaded machine, or the once-only index built the first time, is a spike and not the hook's cost. A hook with fewer
+// than MIN_CALLS calls logged is printed, not judged.
+// The runner's own line (run-hooks: one process for a settings entry, node's start-up included) is judged the same way.
+import { readHookLog } from '../packs/base/hooks/lib/hook-log.mjs';
+
+export const SLOW_MS = 500;
+export const LAST = 100;
+export const MIN_CALLS = 3; // one or two calls are not a median: printed, not judged
+
+export function median(values) {
+  const s = [...values].sort((a, b) => a - b);
+  const m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m] : Math.round((s[m - 1] + s[m]) / 2);
+}
+
+// -> [{ hook, calls, median, worst }], slowest median first
+export function hookTimes(projectDir, last = LAST) {
+  const by = new Map();
+  for (const r of readHookLog(projectDir)) {
+    if (!by.has(r.hook)) by.set(r.hook, []);
+    by.get(r.hook).push(r.ms);
+  }
+  return [...by].map(([hook, all]) => {
+    const ms = all.slice(-last);
+    return { hook, calls: ms.length, median: median(ms), worst: Math.max(...ms) };
+  }).sort((a, b) => b.median - a.median || a.hook.localeCompare(b.hook));
+}
+
+export function timingProblems(projectDir, log = console.log) {
+  const times = hookTimes(projectDir);
+  if (!times.length) {
+    log('  hook timing: no calls logged yet (.claude/hooks.log fills as the hooks run)');
+    return [];
+  }
+  log(`  hook timing (ms, each hook's last ${LAST} calls at most): ${times.map((t) => `${t.hook} ${t.median}/${t.worst}`).join(', ')} (median/worst)`);
+  return times.filter((t) => t.calls >= MIN_CALLS && t.median > SLOW_MS).map((t) =>
+    `${t.hook}: median ${t.median} ms over its last ${t.calls} calls (worst ${t.worst} ms), over ${SLOW_MS} ms: find what it does on every call ` +
+    '(a scan of the repo, a child process, a whole transcript read) and make it incremental');
+}

package/lib/hover-gate.mjs

@@ -0,0 +1,29 @@
+// 0.10.1 (Stellix B-261): a project with UI code names the gate that proves its hover.
+// layout.json "gates": { "hover": "<command>" }. doctor is red when the hover rule is installed, a file stands under its paths (the
+// ui concept), and no gate is declared; or the command names a file (a word with a "/") that is not there. "none: <reason>" declines.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { projectFiles } from './coverage.mjs';
+
+// One gate: the rule whose paths say where it applies, its key in layout.json "gates", and the skill that builds it.
+async function gateProblems(projectDir, layout, { rule, key, skill }) {
+  const rulesDir = join(projectDir, '.claude', 'rules');
+  const rules = existsSync(rulesDir) ? readdirSync(rulesDir).filter((f) => rule.test(f)) : [];
+  if (!rules.length) return [];
+  const globs = rules.flatMap((f) => [...(readFileSync(join(rulesDir, f), 'utf8').match(/^---\n([\s\S]*?)\n---/)?.[1] ?? '').matchAll(/^\s*-\s*"([^"]+)"/gm)].map((m) => m[1]));
+  if (!globs.length) return [];
+  const { matchesAny } = await import(pathToFileURL(join(projectDir, '.claude', 'hooks', 'lib', 'glob.mjs')).href);
+  const ui = projectFiles(projectDir).filter((f) => matchesAny(f, globs));
+  const gate = layout.gates?.[key];
+  if (typeof gate === 'string' && /^none:\s*\S/.test(gate)) return [];
+  if (ui.length === 0) return []; // no UI code yet: nothing to prove, and a gate named ahead of its file (a profile) is not red
+  const hint = `name it in layout.json as "gates": { "${key}": "<command>" } (the ${skill} skill says how to build it), or "none: <reason>"`;
+  if (typeof gate !== 'string' || !gate.trim() || /^none:/.test(gate)) return [`no ${key} gate declared for the UI code (${ui.slice(0, 3).join(', ')}${ui.length > 3 ? ', …' : ''}): ${hint}`];
+  const missing = gate.split(/\s+/).filter((w) => w.includes('/') && !w.startsWith('-') && !/^[a-z]+:\/\//.test(w)).filter((w) => !existsSync(join(projectDir, w)));
+  return missing.map((w) => `the ${key} gate "${gate}" names ${w}, which is not there`);
+}
+
+export const hoverGateProblems = (projectDir, layout) => gateProblems(projectDir, layout, { rule: /(?:hover-every-pressable|pointer-feedback)\.md$/, key: 'hover', skill: 'hover-state' });
+// 0.17.0: a page is proved rendered (rule page-proved-rendered): the same law for accessibility and layout.
+export const pageGateProblems = (projectDir, layout) => gateProblems(projectDir, layout, { rule: /page-proved-rendered\.md$/, key: 'a11y', skill: 'prove-page' });

package/lib/kit-command.mjs

@@ -0,0 +1,14 @@
+// How this project runs the kit. `npx --no-install` needs the kit in its own node_modules, and a project in another language has none: there npx
+// fetches it, and the --no-install form every installed file names fails with "npx canceled due to missing packages" (KWB-76).
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PACKAGE = '@thedecipherist/claude-packs';
+
+export const hasLocalKit = (dir) => existsSync(join(dir, 'node_modules', PACKAGE, 'package.json'));
+export const kitCommand = (dir) => (hasLocalKit(dir) ? `npx --no-install ${PACKAGE}` : `npx ${PACKAGE}`);
+
+// The line the CLAUDE.md block adds where the installed files' form cannot work: a project with no package.json at all.
+export const noPackageLine = (dir) => (existsSync(join(dir, 'package.json')) || hasLocalKit(dir)
+  ? []
+  : [`This project has no package.json: run the kit as \`npx ${PACKAGE} <command>\`, wherever its files say \`npx --no-install ${PACKAGE}\`.`, '']);

package/lib/kit-lock.mjs

@@ -0,0 +1,149 @@
+// The kit lock (.claude-packs-lock at a checkout's root of the claude-packs repo; the repo's own .claude/hooks/kit-lock.mjs
+// takes it, renews it, and refuses another session's commits, merges and releases). Here: its one format, the lease, and
+// `claude-packs lock status|take|release` (KWB-25: a lock left by a gone session could only be released by an rm by hand).
+//   The form: { version: 2, holder: { session, pid }, branch, started_at, last_seen }, with the old keys session and time beside
+//   them so an older kit-lock reads it. The old forms { session, branch, time } and { session, branch } are read too.
+//   The lock is a LEASE (KWB-29): its holder's hook renews last_seen at most once a minute (RENEW_MS) on every
+//   tool call; a holder whose session runs outside the kit (a Stellix lead and its agents, whose hooks are Stellix's) renews it
+//   by working: its transcript, or a subagent's, written later than last_seen counts as seen. No renewal for LEASE_MIN minutes
+//   and the lease is stale: the next session that starts work takes it over, logged in the main checkout's .claude/kit-lock.log
+//   (who held it, branch, since, last seen). A live lease is never taken or deleted; `lock release --force` is the only way.
+//   lock status                     each checkout's lock: holder, branch, held since, last seen, live or stale
+//   lock take [--branch <b>]        take it for CLAUDE_CODE_SESSION_ID (a session whose own hooks are not the kit's)
+//   lock release [--force]          the caller's own lock and stale ones go; another live lease stays (exit 1) unless --force
+import { execFileSync } from 'node:child_process';
+import { appendFileSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const LOCK = '.claude-packs-lock';
+export const LOG = join('.claude', 'kit-lock.log');
+export const LEASE_MIN = 30;
+export const RENEW_MS = 60000;
+const git = (cwd, ...a) => { try { return execFileSync('git', a, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return ''; } };
+const branchOf = (dir) => git(dir, 'symbolic-ref', '--short', 'HEAD') || git(dir, 'rev-parse', '--abbrev-ref', 'HEAD') || '?';
+const ms = (t) => { const v = Date.parse(t ?? ''); return Number.isFinite(v) ? v : null; };
+
+// Every checkout of the repo dir is in: the main one first, then each worktree.
+export function checkouts(root) {
+  const out = git(root, 'worktree', 'list', '--porcelain').split('\n').filter((l) => l.startsWith('worktree ')).map((l) => l.slice(9));
+  return out.length ? out : [root];
+}
+
+// -> { session, pid, branch, startedAt, lastSeen } | null, from any form; a time the lock lacks is null, never undefined
+export function readLock(dir) {
+  let raw;
+  try { raw = JSON.parse(readFileSync(join(dir, LOCK), 'utf8')); } catch { return null; }
+  if (!raw || typeof raw !== 'object') return null;
+  const startedAt = ms(raw.started_at) !== null ? raw.started_at : ms(raw.time) !== null ? raw.time : null;
+  return { session: raw.holder?.session ?? raw.session ?? 'unknown', pid: raw.holder?.pid ?? null, branch: raw.branch ?? '?', startedAt, lastSeen: ms(raw.last_seen) !== null ? raw.last_seen : startedAt };
+}
+
+const write = (dir, l) => writeFileSync(join(dir, LOCK), `${JSON.stringify({ version: 2, holder: { session: l.session, pid: l.pid }, branch: l.branch, started_at: l.startedAt, last_seen: l.lastSeen, session: l.session, time: l.startedAt }, null, 2)}\n`);
+
+export function takeLock(root, session, branch = branchOf(root), pid = Number(process.env.CLAUDE_PID) || null, now = Date.now()) {
+  const at = new Date(now).toISOString();
+  const lock = { session, pid, branch, startedAt: at, lastSeen: at };
+  write(root, lock);
+  return lock;
+}
+
+// The holder's heartbeat: each checkout's lock held by `session` gets last_seen = now, when it is RENEW_MS old or more.
+export function renew(dirs, session, now = Date.now()) {
+  let renewed = false;
+  for (const d of dirs) {
+    const l = readLock(d);
+    if (!l || l.session !== session || (ms(l.lastSeen) !== null && now - ms(l.lastSeen) < RENEW_MS)) continue;
+    write(d, { ...l, startedAt: l.startedAt ?? new Date(now).toISOString(), lastSeen: new Date(now).toISOString() });
+    renewed = true;
+  }
+  return renewed;
+}
+
+// The latest write of the session's transcript or one of its subagents' (~/.claude/projects/<p>/<session>[.jsonl|/subagents/]).
+export function transcriptSeen(session, home = homedir()) {
+  const projects = join(home, '.claude', 'projects');
+  let latest = null;
+  const see = (f) => { try { latest = Math.max(latest ?? 0, statSync(f).mtimeMs); } catch { /* none */ } };
+  let dirs = [];
+  try { dirs = readdirSync(projects); } catch { /* no transcripts */ }
+  for (const d of dirs) {
+    see(join(projects, d, `${session}.jsonl`));
+    const sub = join(projects, d, session, 'subagents');
+    let files = [];
+    try { files = readdirSync(sub); } catch { /* none */ }
+    for (const f of files) if (f.endsWith('.jsonl')) see(join(sub, f));
+  }
+  return latest;
+}
+
+// -> { live, seenAt, why }
+export function liveness(lock, home = homedir(), now = Date.now()) {
+  const lease = ms(lock.lastSeen);
+  const t = transcriptSeen(lock.session, home);
+  const seenAt = Math.max(lease ?? -Infinity, t ?? -Infinity);
+  if (!Number.isFinite(seenAt)) return { live: false, seenAt: null, why: 'never seen (no last_seen, no transcript)' };
+  const age = (now - seenAt) / 60000;
+  const by = t !== null && (lease === null || t > lease) ? 'its transcript' : 'its lease';
+  return { live: age < LEASE_MIN, seenAt, why: `last seen ${new Date(seenAt).toISOString()}, ${age.toFixed(0)} min ago, by ${by}` };
+}
+
+export const describe = (lock, l) => `held by session ${lock.session} (branch ${lock.branch}, held since ${lock.startedAt ?? 'start unknown'}; ${l.why}): ` +
+  (l.live ? 'live' : `stale (no renewal for ${LEASE_MIN} min)`);
+
+// A stale lease out, the taker's in, the take-over logged in the main checkout's .claude/kit-lock.log.
+export function takeOver(root, where, lock, l, session, now = Date.now()) {
+  const main = checkouts(root)[0];
+  mkdirSync(join(main, '.claude'), { recursive: true });
+  appendFileSync(join(main, LOG), `${new Date(now).toISOString()} took over ${join(where, LOCK)}: ${describe(lock, l)}; by session ${session}\n`);
+  rmSync(join(where, LOCK), { force: true });
+}
+
+// The lock for `session` in checkout `dir`: its own already, none (taken), or a stale one (taken over). Another live lease:
+// { held: { lock, where, l } } and nothing is changed.
+export function acquire(dir, session, { home = homedir(), now = Date.now(), branch } = {}) {
+  const locks = checkouts(dir).map((where) => ({ where, lock: readLock(where) })).filter((x) => x.lock);
+  const mine = locks.find((x) => x.lock.session === session);
+  if (mine) return { mine: mine.where };
+  // The same claude process under a new session id (a reload) is its own holder, never another session (KWB-40).
+  const pid = Number(process.env.CLAUDE_PID) || null;
+  const own = pid && locks.find((x) => x.lock.pid === pid);
+  if (own) { takeLock(own.where, session, own.lock.branch, pid, now); return { mine: own.where }; }
+  const others = locks.map((x) => ({ ...x, l: liveness(x.lock, home, now) }));
+  const live = others.find((x) => x.l.live);
+  if (live) return { held: live };
+  for (const x of others) takeOver(dir, x.where, x.lock, x.l, session, now);
+  return { took: takeLock(dir, session, branch ?? branchOf(dir), undefined, now) };
+}
+
+export function lockCommand(sub, dir, { force = false, branch, session = process.env.CLAUDE_CODE_SESSION_ID ?? null, home = homedir(), log = console.log } = {}) {
+  if (!['status', 'take', 'release'].includes(sub)) throw new Error('use `lock status`, `lock take [--branch <b>]` or `lock release [--force]`');
+  if (sub === 'take') {
+    if (!session) { log('no CLAUDE_CODE_SESSION_ID: run it from the session that takes the lock'); return 1; }
+    const r = acquire(dir, session, { home, branch });
+    if (r.held) { log(`kept ${join(r.held.where, LOCK)}: ${describe(r.held.lock, r.held.l)}. Ask the user; --force on release is the only way to remove a live lease`); return 1; }
+    log(r.mine ? `already yours: ${join(r.mine, LOCK)}` : `took ${join(dir, LOCK)} for session ${session} (branch ${r.took.branch})`);
+    return 0;
+  }
+  let code = 0;
+  let any = false;
+  for (const c of checkouts(dir)) {
+    const lock = readLock(c);
+    if (!lock) continue;
+    any = true;
+    const l = liveness(lock, home);
+    const where = join(c, LOCK);
+    if (sub === 'status') { log(`${where}: ${describe(lock, l)}`); continue; }
+    const mine = session && lock.session === session;
+    if (mine || !l.live || force) {
+      if (!mine && !l.live) takeOver(dir, c, lock, l, `${session ?? 'unknown'} (lock release)`);
+      rmSync(where, { force: true });
+      log(`released ${where}: ${describe(lock, l)}${mine ? ' (your own)' : !l.live ? '' : ' (--force)'}`);
+    } else {
+      log(`kept ${where}: session ${lock.session} is live (${l.why}). It is another session's lease: wait for its release or for it to go stale (${LEASE_MIN} min without renewal), or ask the user; --force is the only way to release a live lease`);
+      code = 1;
+    }
+  }
+  if (!any) log('no kit lock in any checkout');
+  return code;
+}

package/lib/layout.mjs

@@ -0,0 +1,99 @@
+// Builds .claude/layout.json from the installed packs, keeping every edit the user made.
+// The layout may also hold (all project-owned, never overwritten by an update):
+//   "files":     { alias: path }      special files that checks refer to as "@alias"
+//   "protected": [globs]              extra read-only paths (vendored copies)
+//   "buildOutput": [globs]            the build output (default build/**); read-only, as vendored code
+//   "writeOnce": [globs]              evidence: a new file may be added, an existing one never changed or removed (KWB-21)
+//   "keepWorktrees": [names]          agent worktrees build-sweep never sweeps (the build the user plays)
+//   "disable":   ["checks/x.json", "hooks/y.mjs", "rules/z.md", "skills/w"]   pack items this project replaces with its own
+//   "commands":  { name: "shell command" }   how this project builds, tests and benches (skills use these)
+//   "paramIds":  { "extensions", "patterns" }   where param-id-lock reads parameter ids (default: JUCE ParameterID literals)
+//   "enable":    ["hooks/x.py", "checks/y.json"]   pack items this project switches on: opt-in hooks, and hooks or
+//                checks a later package version adds to a pack the project already had (see switches.mjs)
+//   "sourceFiles": "<regex>"   what is source to folder-law and doctor (written once from the configuration's; KWB-37)
+//   "gates":    { "hover": "<command>", "a11y": "<command>" }   the gate that proves the UI's hover (doctor is red for UI code without one; "none: <reason>" declines; 0.10.1)
+//   "ruleTests": { "rule-name": "path/to/its/test" | "none: <reason>" }   what answers a rule's named test when no test names the rule (KF-31)
+//   "followFolders": true   base's language concepts cover every code folder of the layout. A first install writes it; an older project chooses it
+//   "guards":    { "git", "copy", "time", "browser", "images" }   the project's values for the house guards
+//                (repo owner and token, the sanctioned copy tools, ...); each hook has its defaults
+// A seed layout (a profile, or one written from docs/project.md) is used when no layout exists yet.
+// "configuration" names the project's configuration (lib/configs.mjs); its layout template is read like a pack's folders,
+// before the packs', so a project gets the folder structure of its kind (0.10.0).
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { NEW_INSTALL_GIT } from '../packs/base/hooks/lib/git-auth.mjs';
+import { codeFolders } from '../packs/base/hooks/lib/layout.mjs';
+import { readPack } from './packs.mjs';
+
+const OWNED = ['files', 'protected', 'buildOutput', 'writeOnce', 'keepWorktrees', 'disable', 'enable', 'commands', 'siblings', 'maxFileLines', 'paramIds', 'guards', 'sourceFiles', 'gates', 'ruleTests', 'followFolders'];
+const OPTIONAL = ['maxFileLines', 'paramIds', 'guards', 'buildOutput', 'writeOnce', 'keepWorktrees', 'sourceFiles', 'gates', 'ruleTests', 'followFolders'];
+// "complete": true marks a tailored layout; see below.
+
+// Base's language concepts name folders, where every other language's are `**`: a file in a layout folder could be legal and have no rules (KWB-83).
+// `**` would close that and hide a stray file from doctor --strict, so the concept follows the layout instead: a folder in it gets its rules, and one outside stays reported.
+const FOLLOWED = { cpp: ['c', 'cc', 'cpp', 'cxx', 'h', 'hh', 'hpp', 'mm'], js: ['{js,mjs,cjs,jsx,ts,tsx}'] };
+
+function followFolders(layout) {
+  for (const [concept, extensions] of Object.entries(FOLLOWED)) {
+    if (!layout.concepts[concept]) continue;
+    const globs = codeFolders(layout).flatMap((folder) => extensions.map((ext) => `${folder}/**/*.${ext}`));
+    layout.concepts[concept] = [...new Set([...layout.concepts[concept], ...globs])];
+  }
+}
+
+export function buildLayout(claudeDir, packNames, seed = null, config = null) {
+  const file = join(claudeDir, 'layout.json');
+  const firstInstall = !existsSync(file);
+  const current = firstInstall ? (seed ?? {}) : JSON.parse(readFileSync(file, 'utf8'));
+  // A project already installed changes only through "enable": "guards/git-house".
+  if (firstInstall) current.guards = { ...current.guards, git: { ...NEW_INSTALL_GIT, ...current.guards?.git } };
+  // The key is the choice: a new install is held to its rules' named tests, and one already installed is told, until it adds the key.
+  if (firstInstall) current.ruleTests ??= {};
+  if (firstInstall && !current.complete) current.followFolders ??= true;
+  const layout = {
+    _comment: 'Where everything lives. folders = the folders; kinds = what goes where (CLAUDE.md shows it, placement-law enforces it); concepts = which rules fire where. Edit here, then run `npx --no-install @thedecipherist/claude-packs update`.',
+    ...(config ? { configuration: config.name } : current.configuration ? { configuration: current.configuration } : {}),
+    folders: { ...(current.folders ?? {}) },
+    concepts: { ...(current.concepts ?? {}) },
+    kinds: { ...(current.kinds ?? {}) },
+  };
+  for (const key of OWNED) {
+    if (current[key] !== undefined) layout[key] = current[key];
+    else if (!OPTIONAL.includes(key)) layout[key] = key === 'files' || key === 'commands' ? {} : [];
+  }
+  // A kind's content pattern that is exactly a pattern the pack used to ship ("contentWas") is
+  // replaced by the pack's current one; a pattern the project wrote itself is kept.
+  // "sourceFiles" (what folder-law and doctor count as source; KWB-37) comes from the configuration once, then is the project's
+  if (config?.sourceFiles && layout.sourceFiles === undefined) layout.sourceFiles = config.sourceFiles;
+  const sources = [...(config?.layout ? [config.layout] : []), ...packNames.map(readPack)];
+  for (const pack of sources) {
+    for (const [k, v] of Object.entries(pack.kinds ?? {})) {
+      const mine = layout.kinds[k];
+      if (mine && v.contentWas?.includes(mine.content)) layout.kinds[k] = { ...mine, content: v.content };
+    }
+  }
+  // A layout marked "complete" (a tailored project) gets no default folders from the packs. It
+  // still gains new pack concepts made only of raw globs (no folder names), such as "claude",
+  // so a rule added in a later package version always resolves.
+  if (current.complete) {
+    layout.complete = true;
+    for (const pack of sources) {
+      for (const [k, v] of Object.entries(pack.concepts ?? {})) {
+        if (!layout.concepts[k] && v.every((e) => e.startsWith('kind:') || e.includes('/') || e.includes('*') || e.includes('.'))) layout.concepts[k] = v;
+      }
+    }
+    writeFileSync(file, JSON.stringify(layout, null, 2) + '\n');
+    return layout;
+  }
+  for (const pack of sources) {
+    for (const [k, v] of Object.entries(pack.folders ?? {})) layout.folders[k] ??= v;
+    for (const [k, v] of Object.entries(pack.files ?? {})) layout.files[k] ??= v;
+    for (const [k, { contentWas, ...v }] of Object.entries(pack.kinds ?? {})) layout.kinds[k] ??= v;
+    for (const [k, v] of Object.entries(pack.concepts ?? {})) {
+      if (!current.concepts?.[k]) layout.concepts[k] = [...new Set([...(layout.concepts[k] ?? []), ...v])];
+    }
+  }
+  if (layout.followFolders) followFolders(layout);
+  writeFileSync(file, JSON.stringify(layout, null, 2) + '\n');
+  return layout;
+}

package/lib/logs.mjs

@@ -0,0 +1,109 @@
+// claude-packs logs: which hooks earn their place. Reads every log, rotated ones included, and joins each refusal to its verdict.
+//   logs                                 per hook: calls, refusals, right, wrong, not judged, crashes, time
+//   logs refusals [--hook <h>] [--open]  every refusal with its reason (--open: not judged yet)
+//   logs mark <id> right|wrong "<why>"   the verdict, added to .claude/logs/verdicts.jsonl; nothing is rewritten
+//   logs crashes                         every crash, and whether it is cleared (KF-40: a crash is no refusal, and has no verdict)
+//   logs clear <hook>|all fixed|superseded "<why>"   clears the crashes so far, for doctor (KF-18); a later crash is red again
+import { appendFileSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { readHookLog } from '../packs/base/hooks/lib/hook-log.mjs';
+
+const DIR = join('.claude', 'logs');
+const HOW = ['fixed', 'superseded'];
+export const ANSWERS = new Set(['0', '2', '-', 'undefined', 'null']); // the codes of hooks.log that are no crash
+
+function linesOf(dir, name) {
+  const logs = join(dir, DIR);
+  let files = [];
+  try { files = readdirSync(logs).filter((f) => f === `${name}.jsonl` || (f.startsWith(`${name}-`) && f.endsWith('.jsonl'))).sort(); } catch { return []; }
+  return files.flatMap((f) => readFileSync(join(logs, f), 'utf8').split('\n').filter(Boolean).flatMap((l) => { try { return [JSON.parse(l)]; } catch { return []; } }));
+}
+
+// A crash, in its own log or, in an old log, in refusals.jsonl with a code other than 2. Old lines are read as they are, never rewritten.
+const crashesOf = (dir) => [...linesOf(dir, 'crashes'), ...linesOf(dir, 'refusals').filter((r) => r.code !== 2)];
+const refusalsOf = (dir) => linesOf(dir, 'refusals').filter((r) => r.code === 2);
+
+// hook -> the time of its last clear ("all" stands for every hook). doctor counts only a crash after it.
+export function clearsOf(dir) {
+  const clears = new Map();
+  for (const v of linesOf(dir, 'verdicts')) if (v.clear) clears.set(v.clear, v.t);
+  return clears;
+}
+export const clearedAt = (clears, hook) => [clears.get(hook), clears.get('all')].filter(Boolean).sort().at(-1) ?? '';
+
+function clearCrashes(dir, [, hook, how, ...why], log) {
+  if (!hook || !HOW.includes(how) || !why.length) throw new Error('use `logs clear <hook>|all fixed|superseded "<why>"`');
+  const logged = readHookLog(dir, { rotated: true }).filter((r) => !ANSWERS.has(String(r.code)));
+  if (![...crashesOf(dir), ...logged].some((c) => hook === 'all' || c.hook === hook)) throw new Error(`no crash of ${hook}: \`logs crashes\` lists them`);
+  mkdirSync(join(dir, DIR), { recursive: true });
+  appendFileSync(join(dir, DIR, 'verdicts.jsonl'), `${JSON.stringify({ clear: hook, how, why: why.join(' '), t: new Date().toISOString() })}\n`);
+  log(`${hook}: crashes so far cleared as ${how}`);
+  return 0;
+}
+
+function listCrashes(dir, log) {
+  const clears = clearsOf(dir);
+  const list = crashesOf(dir);
+  for (const c of list) {
+    const state = c.t <= clearedAt(clears, c.hook) ? 'cleared' : 'open';
+    log(`${c.id} ${c.t} ${c.hook} ${state}\n  ${c.file ?? c.command ?? c.tool ?? '-'}\n  ${(c.reason ?? '').split('\n')[0]}`);
+  }
+  log(`${list.length} crash(es)`);
+  return 0;
+}
+
+const verdictsOf = (dir) => new Map(linesOf(dir, 'verdicts').map((v) => [v.id, v]));
+const middle = (list) => [...list].sort((a, b) => a - b)[Math.floor(list.length / 2)] ?? 0;
+
+// A refusal followed by a pass on the same file in the same session: the writer changed something and went on.
+function passedAfter(refusal, events) {
+  return events.some((e) => e.t > refusal.t && e.session === refusal.session && e.file && e.file === refusal.file && e.hooks.some((h) => h.hook === refusal.hook && h.code === 0));
+}
+
+export function logsSummary(dir) {
+  const events = linesOf(dir, 'events');
+  const verdicts = verdictsOf(dir);
+  const rows = new Map();
+  const row = (hook) => { if (!rows.has(hook)) rows.set(hook, { hook, calls: 0, refused: 0, crashed: 0, right: 0, wrong: 0, open: 0, passedAfter: 0, ms: [] }); return rows.get(hook); };
+  for (const e of events) for (const h of e.hooks ?? []) { const r = row(h.hook); r.calls += 1; r.ms.push(h.ms); }
+  for (const c of crashesOf(dir)) row(c.hook).crashed += 1;
+  for (const f of refusalsOf(dir)) {
+    const r = row(f.hook);
+    r.refused += 1;
+    const v = verdicts.get(f.id)?.verdict;
+    if (v === 'right') r.right += 1; else if (v === 'wrong') r.wrong += 1; else r.open += 1;
+    if (passedAfter(f, events)) r.passedAfter += 1;
+  }
+  return { first: events[0]?.t, last: events.at(-1)?.t, calls: events.length, rows: [...rows.values()].sort((a, b) => b.refused - a.refused || b.calls - a.calls) };
+}
+
+export function logsCommand(dir, rest, log = console.log) {
+  const [sub] = rest;
+  if (sub === 'mark') {
+    const [, id, verdict, ...why] = rest;
+    if (!id || !['right', 'wrong'].includes(verdict) || !why.length) throw new Error('use `logs mark <id> right|wrong "<why>"`');
+    if (crashesOf(dir).some((r) => r.id === id)) throw new Error(`${id} is a crash, which refused nothing: \`logs clear <hook> fixed|superseded "<why>"\` clears it`);
+    if (!refusalsOf(dir).some((r) => r.id === id)) throw new Error(`no refusal ${id}: \`logs refusals\` lists them`);
+    mkdirSync(join(dir, DIR), { recursive: true });
+    appendFileSync(join(dir, DIR, 'verdicts.jsonl'), `${JSON.stringify({ id, verdict, why: why.join(' '), t: new Date().toISOString() })}\n`);
+    log(`${id}: ${verdict}`);
+    return 0;
+  }
+  if (sub === 'crashes') return listCrashes(dir, log);
+  if (sub === 'clear') return clearCrashes(dir, rest, log);
+  if (sub === 'refusals') {
+    const hook = rest.includes('--hook') ? rest[rest.indexOf('--hook') + 1] : null;
+    const verdicts = verdictsOf(dir);
+    const list = refusalsOf(dir).filter((r) => (!hook || r.hook === hook) && (!rest.includes('--open') || !verdicts.has(r.id)));
+    for (const r of list) log(`${r.id} ${r.t} ${r.hook} ${verdicts.get(r.id)?.verdict ?? 'not judged'}\n  ${r.file ?? r.command ?? r.tool ?? '-'}\n  ${(r.reason ?? '').split('\n')[0]}`);
+    log(`${list.length} refusal(s)`);
+    return 0;
+  }
+  const s = logsSummary(dir);
+  if (!s.calls) { log('no calls logged yet (.claude/logs/ fills as the hooks run)'); return 0; }
+  log(`${s.calls} calls, ${s.first} to ${s.last}`);
+  log(`${'hook'.padEnd(24)}${'calls'.padStart(7)}${'refused'.padStart(8)}${'right'.padStart(6)}${'wrong'.padStart(6)}${'open'.padStart(6)}${'fixed'.padStart(6)}${'crash'.padStart(6)}${'ms'.padStart(6)}`);
+  for (const r of s.rows) log(`${r.hook.padEnd(24)}${String(r.calls).padStart(7)}${String(r.refused).padStart(8)}${String(r.right).padStart(6)}${String(r.wrong).padStart(6)}${String(r.open).padStart(6)}${String(r.passedAfter).padStart(6)}${String(r.crashed).padStart(6)}${String(middle(r.ms)).padStart(6)}`);
+  log('fixed: the same file passed the same hook later in that session. Judge the open ones: `logs refusals --open`, then `logs mark <id> right|wrong "<why>"`.');
+  return 0;
+}

package/lib/manifest.mjs

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

package/lib/new.mjs

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

package/lib/once-only-report.mjs

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