@thedecipherist/claude-packs 1.0.0 → 1.1.0

package/lib/fix-plan.mjs

@@ -4,9 +4,9 @@ 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 CLI = 'npx --no-install @thedecipherist/claude-packs';
 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);
 
@@ -26,6 +26,7 @@ function repeatBox(r) {
 }
 
 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 [

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/global.mjs

@@ -17,9 +17,9 @@ 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'],
-  ['hooks/lib/shell-writes.mjs', 'hooks/claude-packs/lib/shell-writes.mjs'],
-  ['hooks/lib/program-writes.mjs', 'hooks/claude-packs/lib/program-writes.mjs'],
-  ['hooks/lib/program-read.mjs', 'hooks/claude-packs/lib/program-read.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'],
 ];

package/lib/hook-proof.mjs

@@ -1,13 +1,26 @@
 // 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 two of the ways: a hook no settings entry runs (dispatch-once was that way for
-// a moment in 0.11.0), and a hook that crashed since it last changed, from its exit code in .claude/hooks.log. A hook killed at its
-// timeout leaves no line and is not seen.
+// 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 ANSWERS = new Set(['0', '2', '-', 'undefined', 'null']);
+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');
@@ -17,12 +30,16 @@ export async function hookProofProblems(projectDir, settingsText) {
   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) => f.replace(/\.(mjs|py)$/, '') === row.hook);
+    const file = hooks.find((f) => hookName(f) === row.hook);
     if (!file || ANSWERS.has(String(row.code))) continue;
-    if (Date.parse(row.time) > statSync(join(dir, file)).mtimeMs) crashed.set(file, (crashed.get(file) ?? 0) + 1);
+    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>"\``);
   }
-  for (const [f, n] of crashed) problems.push(`${f} crashed on ${n} call(s) since it last changed: those calls were not judged, and went through (.claude/hooks.log, .claude/logs/)`);
   return problems;
 }

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/layout.mjs

@@ -12,6 +12,8 @@
 //                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.
@@ -19,14 +21,35 @@
 // 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'];
+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 current = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : (seed ?? {});
+  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 } : {}),
@@ -36,7 +59,7 @@ export function buildLayout(claudeDir, packNames, seed = null, config = null) {
   };
   for (const key of OWNED) {
     if (current[key] !== undefined) layout[key] = current[key];
-    else if (!['maxFileLines', 'paramIds', 'guards', 'buildOutput', 'writeOnce', 'keepWorktrees', 'sourceFiles', 'gates'].includes(key)) layout[key] = key === 'files' || key === 'commands' ? {} : [];
+    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.
@@ -70,6 +93,7 @@ export function buildLayout(claudeDir, packNames, seed = null, config = null) {
       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

@@ -2,10 +2,15 @@
 //   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);
@@ -14,6 +19,39 @@ function linesOf(dir, name) {
   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;
 
@@ -24,14 +62,13 @@ function passedAfter(refusal, events) {
 
 export function logsSummary(dir) {
   const events = linesOf(dir, 'events');
-  const refusals = linesOf(dir, 'refusals');
   const verdicts = verdictsOf(dir);
   const rows = new Map();
   const row = (hook) => { if (!rows.has(hook)) rows.set(hook, { hook, calls: 0, refused: 0, crashed: 0, right: 0, wrong: 0, open: 0, passedAfter: 0, ms: [] }); return rows.get(hook); };
   for (const e of events) for (const h of e.hooks ?? []) { const r = row(h.hook); r.calls += 1; r.ms.push(h.ms); }
-  for (const f of refusals) {
+  for (const c of crashesOf(dir)) row(c.hook).crashed += 1;
+  for (const f of refusalsOf(dir)) {
     const r = row(f.hook);
-    if (f.code !== 2) { r.crashed += 1; continue; }
     r.refused += 1;
     const v = verdicts.get(f.id)?.verdict;
     if (v === 'right') r.right += 1; else if (v === 'wrong') r.wrong += 1; else r.open += 1;
@@ -45,16 +82,19 @@ export function logsCommand(dir, rest, log = console.log) {
   if (sub === 'mark') {
     const [, id, verdict, ...why] = rest;
     if (!id || !['right', 'wrong'].includes(verdict) || !why.length) throw new Error('use `logs mark <id> right|wrong "<why>"`');
-    if (!linesOf(dir, 'refusals').some((r) => r.id === id)) throw new Error(`no refusal ${id}: \`logs refusals\` lists them`);
+    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 = linesOf(dir, 'refusals').filter((r) => (!hook || r.hook === hook) && (!rest.includes('--open') || !verdicts.has(r.id)));
+    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;

package/lib/new.mjs

@@ -45,5 +45,5 @@ export async function newProject(parent, name, { packs = ['audio-core'], seedLay
     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) };
+  return { dir, code: await doctor(dir, log, { installing: true }) };
 }

package/lib/packs.mjs

@@ -5,6 +5,8 @@ import { fileURLToPath } from 'node:url';
 
 export const PACKS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'packs');
 const CLAUDE_DIRS = ['rules', 'checks', 'hooks', 'tools'];
+// A tool's own config, read from the project's root: the project's once written, so a pack's file never replaces it.
+const PROJECT_ROOT_FILES = [['clang-tidy', '.clang-tidy'], ['clippy.toml', 'clippy.toml']];
 
 // Packs from a team's own repository (lib/custom-packs.mjs): name -> the folder it was fetched to.
 const CUSTOM = new Map();
@@ -57,8 +59,7 @@ export function planFiles(name, layout) {
   const skillFolder = pack.skillsIn && layout.folders[pack.skillsIn];
   const skillBase = skillFolder ? join(skillFolder.path, '.claude') : '.claude';
   for (const src of walk(join(root, 'skills'))) if (!off(src)) plan.push({ src, rel: join(skillBase, relative(root, src)) });
-  const tidy = join(root, 'clang-tidy');
-  if (existsSync(tidy)) plan.push({ src: tidy, rel: '.clang-tidy', userOwned: true });
+  for (const [file, rel] of PROJECT_ROOT_FILES) if (existsSync(join(root, file))) plan.push({ src: join(root, file), rel, userOwned: true });
   return plan;
 }
 
@@ -96,6 +97,7 @@ export const PRESETS = {
   'python-app': ['python', 'shell', 'docker'],
   'shell-tools': ['shell'],
   'go-app': ['go', 'shell', 'docker', 'ci'],
+  'rust-app': ['rust', 'shell', 'docker', 'ci'],
 };
 
 // Base always first, no duplicates, presets expanded, in the order given.

package/lib/rule-tests.mjs

@@ -0,0 +1,42 @@
+// KF-31: a rule's Check can name a test, and an install reads as if the test exists. Three rules of the MPX 500 named tests that were never written, and
+// the gap held four real bugs while every hook, scan and doctor stayed quiet. doctor is red for a live rule (one that matches a file of the project)
+// whose Check names a test nothing answers to. A test answers by naming the rule (`proves: <rule>`, in a test, bench or gate file), or layout.json
+// "ruleTests" points the rule at a file, or declines it with "none: <reason>".
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+const TEST_PLACE = /(^|\/)(tests?|specs?|e2e|bench|benches|benchmarks?|gates?)(\/|$)|(^|[._-])(test|spec)[._-][^/]*$|_test\.[^/]+$/i;
+const MAX_BYTES = 2 * 1024 * 1024;
+const checkOf = (text) => text.split(/^## Check[ \t]*$/m)[1]?.split(/^## /m)[0] ?? '';
+
+// "Test:", "Tests:", "- Unit test:", "ThreadSanitizer stress test:", "Benchmark test, offline render:" at the head of a line of the Check.
+export const namesATest = (text) => /^[ \t]*(?:(?:[-*]|\d+\.)[ \t]+)?(?:[\w'-]+[ \t]+){0,3}tests?(?:,[^:\n]*)?:/im.test(checkOf(text));
+
+// A file's text, or '' for one too big to be a test or gone since it was listed.
+const smallFileText = (file) => { try { return statSync(file).size > MAX_BYTES ? '' : readFileSync(file, 'utf8'); } catch { return ''; } };
+const inTestFolder = (rel, folders) => TEST_PLACE.test(rel) || folders.some((f) => rel === f || rel.startsWith(`${f}/`));
+
+export function ruleTestProblems(projectDir, layout, { liveRules, files }) {
+  const dir = join(projectDir, '.claude', 'rules');
+  if (!existsSync(dir)) return [];
+  const named = readdirSync(dir).filter((f) => liveRules.includes(f) && namesATest(smallFileText(join(dir, f)))).map((f) => basename(f, '.md'));
+  if (!named.length) return [];
+  const folders = (layout.concepts?.tests ?? []).map((f) => layout.folders?.[f]?.path ?? f).filter((f) => !f.includes('*'));
+  const tests = files.filter((f) => inTestFolder(f, folders)).map((f) => smallFileText(join(projectDir, f)));
+  const declared = layout.ruleTests ?? {};
+  const problems = [];
+  const open = named.filter((rule) => {
+    const said = declared[rule];
+    if (/^none:\s*\S/.test(said ?? '')) return false;
+    if (said && said !== 'none') {
+      if (!existsSync(join(projectDir, said))) problems.push(`${rule}: ruleTests names ${said}, which does not exist`);
+      return false;
+    }
+    return !tests.some((t) => t.includes(rule));
+  });
+  if (open.length) {
+    const how = 'Write the test its Check names, and put `proves: <rule>` in it. Or set layout.json "ruleTests": { "<rule>": "<path>" }, or "none: <reason>".';
+    problems.push(`${open.length} rule(s) name a test nothing in this project answers to: ${open.join(', ')}\n    ${how}`);
+  }
+  return problems;
+}

package/lib/scan-detect.mjs

@@ -14,9 +14,42 @@ function holds(ctx, name, text) {
   return ctx.files.filter((f) => name.test(f)).slice(0, MOST_READ).find((f) => { try { return text.test(readFileSync(join(ctx.dir, f), 'utf8')); } catch { return false; } });
 }
 
+// A project at its start has no source, and only its notes say what it will be (KF-3: a JUCE plugin's first `suggest` said base, with no warning). Once code
+// exists the code decides, and a word in a README adds nothing.
+const NOTES = /(^|\/)(?:README|PROMPT|BRIEF|SPEC|PLAN)[^/]*\.md$|^docs\/(?:[^/]+\/)*[^/]+\.md$/i;
+const NOTED = {
+  'audio-core': /\bJUCE\b|\bVST3?\b|\baudio plug-?in\b/i,
+  cpp: /\bC\+\+/,
+  midi: /\bMIDI\b/,
+  'sound-design': /\b(?:reverb|synth|synthesi[sz]er|oscillator)\b/i,
+  'instrument-shell': /\b(?:front panel|plug-?in editor)\b/i,
+  'reverse-engineering': /\bfirmware\b|\breverse[- ]engineer/i,
+  python: /\bPython\b/,
+  rust: /\bRust\b/,
+};
+function noted(ctx, pack) {
+  if (!ctx.early || !NOTED[pack]) return null;
+  const notes = [...ctx.files, ...ctx.published].filter((f) => NOTES.test(f)).slice(0, MOST_READ);
+  const hit = notes.find((f) => { try { return NOTED[pack].test(readFileSync(join(ctx.dir, f), 'utf8')); } catch { return false; } });
+  return said(hit, 'named in the notes');
+}
+
+// A driver alone says Postgres; a tool that speaks several databases says it only with this second signal in its own file.
+const POSTGRES_FILES = [
+  [/(^|\/)(?:requirements[^/]*\.txt|pyproject\.toml|Pipfile)$/, /\b(?:psycopg2?(?:-binary)?|asyncpg)\b/],
+  [/(^|\/)go\.mod$/, /jackc\/pgx|lib\/pq\b|gorm\.io\/driver\/postgres/],
+  [/(^|\/)Cargo\.toml$/, /\b(?:tokio-postgres|deadpool-postgres)\b|\b(?:sqlx|diesel|sea-orm)\b[^\n]*postgres/],
+  [/(^|\/)Gemfile$/, /^\s*gem\s+['"]pg['"]/m],
+  [/\.prisma$/, /provider\s*=\s*"postgresql"/],
+  [/(^|\/)drizzle\.config\.[cm]?[jt]s$/, /dialect:\s*['"]postgresql['"]/],
+  [/(^|\/)[\w.-]*compose[\w.-]*\.ya?ml$/, /image:\s*['"]?[\w./-]*(?:postgres|postgis|pgvector|timescale)/],
+];
+
 const ROWS = {
   'js-ts': (c) => said(file(c, /\.(ts|tsx|js|jsx|mjs|cjs)$/), 'JS or TS source'),
   mongo: (c) => said(dep(c, 'mongodb', 'mongoose'), 'dependency'),
+  postgres: (c) => said(dep(c, 'pg', 'postgres', 'pg-promise', '@neondatabase/serverless', '@vercel/postgres'), 'dependency')
+    ?? said(POSTGRES_FILES.map(([name, text]) => holds(c, name, text)).find(Boolean), 'Postgres named in'),
   fastify: (c) => said(dep(c, 'fastify'), 'dependency'),
   ai: (c) => said(dep(c, '@anthropic-ai/sdk', 'openai', 'ai', '@ai-sdk'), 'dependency'),
   docker: (c) => said(file(c, /(^|\/)(Dockerfile[^/]*|[\w.-]*compose[\w.-]*\.ya?ml)$/), 'file'),
@@ -30,6 +63,7 @@ const ROWS = {
   cpp: (c) => said(file(c, /\.(?:cc|cpp|cxx|hh|hpp|mm)$/), 'C++ source'),
   python: (c) => said(file(c, /\.py$/), 'Python source'),
   go: (c) => said(file(c, /\.go$/), 'Go source'),
+  rust: (c) => said(file(c, /(^|\/)Cargo\.toml$/) ?? file(c, /\.rs$/), 'Rust crate'),
   midi: (c) => said(file(c, /\.(syx|mid)$|(^|\/)\w*(Midi|MIDI|Sysex|SysEx)\w*\.(h|hpp|cpp|cc)$/), 'MIDI file')
     ?? said(holds(c, /\.(h|hpp|cpp|cc)$/, /\b(MidiMessage|isController|isNoteOn|getSysExData)\b/), 'MIDI handling'),
   'sound-design': (c) => said(file(c, /(^|\/)\w*(Voice|Oscillator|Filter|Reverb|Envelope|Lfo|LFO)\w*\.(h|hpp|cpp|cc)$/), 'DSP source'),
@@ -50,15 +84,16 @@ const ROWS = {
 };
 
 // The configuration of the project: a synth; else the language most of its files are in; else base. full-stack is offered, never assumed: it fixes a folder layout.
-const LEADS = [['cpp', /\.(?:c|cc|cpp|cxx|h|hh|hpp|mm)$/, 'C++ sources'], ['node', /\.(?:ts|tsx|js|jsx|mjs|cjs)$/, 'JS or TS sources'], ['python', /\.py$/, 'Python sources'], ['go', /\.go$/, 'Go sources']];
+const LEADS = [['cpp', /\.(?:c|cc|cpp|cxx|h|hh|hpp|mm)$/, 'C++ sources'], ['node', /\.(?:ts|tsx|js|jsx|mjs|cjs)$/, 'JS or TS sources'], ['python', /\.py$/, 'Python sources'], ['go', /\.go$/, 'Go sources'], ['rust', /\.rs$|(^|\/)Cargo\.toml$/, 'Rust sources']];
 
 function configFor(ctx) {
   if (ROWS['audio-core'](ctx)) return { name: 'synth-creator', why: 'JUCE sources' };
+  if (noted(ctx, 'audio-core')) return { name: 'synth-creator', why: 'named in the notes' };
   const [lead] = LEADS.map(([name, re, why]) => ({ name, why, n: ctx.files.filter((f) => re.test(f)).length })).sort((a, b) => b.n - a.n);
   return lead.n ? lead : { name: 'base', why: 'no stack the kit has a configuration for' };
 }
 
-const INSTALLED = /(^|\/)\.claude\//;
+const INSTALLED = /(^|\/)(\.claude|node_modules)\//;
 
 // A project that names its configuration has decided; reading the files again can only disagree with it.
 function namedConfig(projectDir) {
@@ -78,17 +113,18 @@ export function recommend(projectDir, files) {
       for (const k of ['dependencies', 'devDependencies', 'peerDependencies']) for (const n of Object.keys(j[k] ?? {})) deps.add(n);
     } catch { /* a package.json that does not parse says nothing */ }
   }
-  const own = files.filter((f) => !INSTALLED.test(f)); // the kit's own files in a project say nothing about the project
+  const own = files.filter((f) => !INSTALLED.test(f)); // the kit's own files and installed dependencies say nothing about the project
   const ctx = { deps, dir: projectDir, files: own.filter((f) => !isContent(f)), published: own.filter(isContent) };
+  ctx.early = !LEADS.some(([, re]) => ctx.files.some((f) => re.test(f)));
   const { name, why } = namedConfig(projectDir) ?? configFor(ctx);
   const config = readConfig(name);
   const packs = [];
   const leftOut = [];
   for (const pack of config.packs.choose) {
-    const found = ROWS[pack]?.(ctx);
+    const found = ROWS[pack]?.(ctx) ?? noted(ctx, pack);
     if (found) packs.push({ pack, why: found });
     else leftOut.push(pack);
   }
   const fullStack = dep(ctx, 'next') && dep(ctx, 'fastify');
-  return { config: name, why, always: config.packs.always, packs, leftOut, fullStack: Boolean(fullStack) };
+  return { config: name, why, always: config.packs.always, packs, leftOut, early: ctx.early, fullStack: Boolean(fullStack) };
 }

package/lib/scan.mjs

@@ -20,6 +20,7 @@ import { onceOnlyDoctor } from './once-only-report.mjs';
 import { PACKS_DIR, availablePacks } from './packs.mjs';
 import { nearCopies, remadeNames, repeatLine, repeatedShapes } from './repeats.mjs';
 import { rememberScan } from './fix-plan.mjs';
+import { kitCommand } from './kit-command.mjs';
 import { repoWeight, weightLines } from './repo-weight.mjs';
 import { recommend } from './scan-detect.mjs';
 import { sync } from './sync.mjs';
@@ -102,7 +103,7 @@ function report({ dir, copy, pick, results, secrets, skipped, longFiles, cov, du
   for (const p of pick.packs) out.push(`- \`${p.pack}\`: ${p.why}`);
   if (pick.leftOut.length) out.push('', `Left out, nothing found for them: ${pick.leftOut.join(', ')}.`);
   if (pick.fullStack) out.push('', 'Next.js and Fastify are both here: the `full-stack` configuration may fit, but it fixes a folder layout and has fewer checks. Compare before choosing.');
-  out.push('', '```', `npx --no-install @thedecipherist/claude-packs init ${pick.packs.map((p) => p.pack).join(' ')} --config ${pick.config}`, '```', '');
+  out.push('', '```', `${kitCommand(dir)} init ${pick.packs.map((p) => p.pack).join(' ')} --config ${pick.config}`, '```', '');
   if (secrets.length) {
     out.push('## Secrets', '', 'Values are never shown. Secret-shaped text in test files and content folders is usually an example, and is listed apart.', '');
     for (const s of live) out.push(`- ${s.file}:${s.line}: ${s.name}`);
@@ -126,7 +127,9 @@ function report({ dir, copy, pick, results, secrets, skipped, longFiles, cov, du
   out.push(...weightLines(weight));
   out.push(`- ${cov.uncovered.length} source file(s) no rule covers yet; the layout is fitted to the project at install`, '');
   if (skipped.length) out.push(`Not read: ${skipped.length} file(s), secret files, symlinks or over 1 MB. ${skipped.filter(isSecretFile).length} of them are secret files, left out on purpose.`, '');
-  out.push('## Next step', '', 'The checks find patterns. For runaway loops, security holes between files and work that disappears silently, run the review on the copy:', '', '```', `cd ${copy}`, 'npx --no-install @thedecipherist/claude-packs scan --prompt   # give what it prints to Claude Code here', '```', '', `The copy holds your code: delete ${copy} when you are done.`, '');
+  const why = 'The checks find patterns. For runaway loops, security holes between files and work that disappears silently, run the review on the copy:';
+  const review = `${kitCommand(dir)} scan --prompt   # give what it prints to Claude Code here`;
+  out.push('## Next step', '', why, '', '```', `cd ${copy}`, review, '```', '', `The copy holds your code: delete ${copy} when you are done.`, '');
   return out.join('\n');
 }
 

package/lib/suggest.mjs

@@ -1,5 +1,8 @@
 // claude-packs suggest: which packs this project needs, read from its own files, so nobody picks them by hand. `init --auto` installs exactly this.
-// Fast and read-only: it reads file names and package.json, nothing else. `scan` goes further and runs the checks on a copy.
+// Fast and read-only: it reads file names and dependency files, nothing else. `scan` goes further and runs the checks on a copy.
+import { allowedPacks, readConfig } from './configs.mjs';
+import { kitCommand } from './kit-command.mjs';
+import { normalisePacks } from './packs.mjs';
 import { filesOf } from './scan.mjs';
 import { recommend } from './scan-detect.mjs';
 
@@ -8,11 +11,21 @@ export const suggestionOf = (dir) => recommend(dir, filesOf(dir));
 export function suggest(dir, { log = console.log } = {}) {
   const pick = suggestionOf(dir);
   log(`configuration: ${pick.config} (${pick.why})`);
+  if (pick.early) log('no source yet: this comes from the notes alone. Run `suggest` again once code exists, and `add` what it finds.');
   log(`always: ${pick.always.join(', ')}`);
   if (pick.packs.length) log('suggested:');
   for (const p of pick.packs) log(`  ${p.pack.padEnd(14)} ${p.why}`);
-  if (pick.leftOut.length) log(`left out, nothing here needs them: ${pick.leftOut.join(', ')}`);
+  if (pick.leftOut.length) log(`${pick.early ? 'not named yet' : 'left out, nothing here needs them'}: ${pick.leftOut.join(', ')}`);
   if (pick.fullStack) log('this looks like the full-stack configuration: `init --config full-stack` fixes its folder layout, so it is offered and never assumed');
-  log('\nInstall exactly this: npx --no-install @thedecipherist/claude-packs init --auto');
+  log(`\nInstall exactly this: ${kitCommand(dir)} init --auto`);
   return pick;
 }
+
+// The configuration of an `init <pack>` that names none: the project's own, when it takes those packs. A Node project that asks for one pack must not
+// land in whichever configuration is smallest. With no code yet nothing says what the project is, so the packs decide.
+export function detectedConfig(dir, requested) {
+  const pick = suggestionOf(dir);
+  if (pick.early) return null;
+  const allowed = allowedPacks(readConfig(pick.config));
+  return normalisePacks(requested).every((p) => allowed.includes(p)) ? pick.config : null;
+}

package/lib/sync.mjs

@@ -10,6 +10,7 @@ import { backup, ensureGitignore } from './backup.mjs';
 import { writeClaudeMd } from './claude-md.mjs';
 import { listedPacks, packsFor, resolveConfig } from './configs.mjs';
 import { buildLayout } from './layout.mjs';
+import { withFoundFolders } from './found-folders.mjs';
 import { hashFile, isModified, readLock, writeLock } from './manifest.mjs';
 import { normalisePacks, planFiles } from './packs.mjs';
 import { applyPaths, renderRule } from './rules.mjs';
@@ -103,7 +104,8 @@ export async function sync(projectDir, requested, { force = false, mkdirs = fals
   if (hadClaude) log(`  backup: ${backup(projectDir)}`);
   ensureGitignore(projectDir);
 
-  const layout = buildLayout(claudeDir, packNames, seedLayout, config);
+  const seed = existsSync(join(claudeDir, 'layout.json')) ? seedLayout : withFoundFolders(projectDir, seedLayout, config, log);
+  const layout = buildLayout(claudeDir, packNames, seed, config);
   if (mkdirs) createFolders(projectDir, layout);
   // New hooks and checks switch on only where the project chose them; the lists are printed first. A configuration's own
   // packs count as had while the project keeps its configuration (before 0.10.0 their files were base's).
@@ -124,7 +126,8 @@ export async function sync(projectDir, requested, { force = false, mkdirs = fals
     files[rel] = hashFile(join(projectDir, rel));
   }
   const fetched = Object.fromEntries(Object.entries({ ...lock.sources, ...sources }).filter(([name]) => listed.includes(name)));
-  writeLock(claudeDir, { kit: KIT_VERSION, packs: listed, ...(Object.keys(fetched).length ? { sources: fetched } : {}), updated: new Date().toISOString(), files });
+  // packs: what was asked for, which an update reads back; installed: every pack whose files are here, the configuration's own too (KF-4)
+  writeLock(claudeDir, { kit: KIT_VERSION, packs: listed, installed: [...new Set([...listed, ...config.packs.always])], ...(Object.keys(fetched).length ? { sources: fetched } : {}), updated: new Date().toISOString(), files });
   log(`Packs: ${listed.join(', ')}. ${Object.keys(files).length} files managed, ${stale} rule paths refreshed.`);
   return { packNames: listed, layout, config };
 }

package/lib/workorder.mjs

@@ -0,0 +1,26 @@
+// `claude-packs workorder <name>`: the three files a project needs to build on its own, from what two whole builds taught: the order, the prompt that runs
+// it with nobody there, and the runner that starts session after session. The steps are the author's; the `write-a-workorder` skill says how to write them.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { kitCommand } from './kit-command.mjs';
+
+const TEMPLATES = fileURLToPath(new URL('../prompts/workorder/', import.meta.url));
+const FILES = ['workorder.md', 'PROMPT.md', 'run.sh'];
+
+export function newWorkorder(dir, name, { log = console.log } = {}) {
+  if (!name || !/^[\w.-]+$/.test(name)) throw new Error(`name the work order: \`${kitCommand(dir)} workorder <name>\``);
+  const folder = join(dir, 'docs', 'workorders', name);
+  if (existsSync(folder)) throw new Error(`docs/workorders/${name} already exists: nothing was written`);
+  mkdirSync(folder, { recursive: true });
+  const date = new Date().toISOString().slice(0, 10);
+  for (const file of FILES) {
+    const text = readFileSync(join(TEMPLATES, file), 'utf8').replaceAll('{{name}}', name).replaceAll('{{date}}', date);
+    writeFileSync(join(folder, file), text, { mode: file.endsWith('.sh') ? 0o755 : 0o644 });
+  }
+  log(`Work order: docs/workorders/${name}/`);
+  log('  1. Write the steps in workorder.md, with Claude if you like: the write-a-workorder skill says how.');
+  log(`  2. To watch it, type in Claude Code: Run docs/workorders/${name}/PROMPT.md`);
+  log(`  3. To leave it running, read run.sh, then: bash docs/workorders/${name}/run.sh`);
+  return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thedecipherist/claude-packs",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Per-project Claude Code rules, lesson checks, hooks and skills that hold code to what a senior engineer would accept, in every language. Stops repetition before it is written, scans a project on a copy, and turns what it finds into a work order.",
   "type": "module",
   "bin": {