@warren-dean/code-kit 0.4.1 → 0.6.0

package/hooks/guard-bash.mjs

@@ -5,19 +5,22 @@
 // approval log on commit and scans commits for secrets. Shell writes are also checked afterwards by
 // lane-audit.mjs. With `approvals.lead` on, the lead may act for the person on what they say in chat:
 // record their approvals (`code-kit approve`) and run blocked commands marked `person`.
-import { appendFileSync } from 'node:fs';
+import { appendFileSync, existsSync, readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { join, resolve } from 'node:path';
-import { addedPackages, dependencyApproval } from './lib/dependencies.mjs';
+import { addedPackages, dependencyApproval, isDependencyFile } from './lib/dependencies.mjs';
+import { CODE_KIT, GIT, codeOf, runs } from './lib/shell.mjs';
 import { block, start } from './lib/hook.mjs';
 import {
   APPROVAL_LOG,
   actorFor,
+  arrivesWithMerge,
   approval,
   approvalHowTo,
   currentBranch,
   dependencyChange,
   dependencyGrants,
+  useApproval,
   owns,
   protectedEntry,
   recordRequest,
@@ -27,28 +30,46 @@ import {
 const { input, project, config, error } = start();
 const cmd = String(input.tool_input?.command || '');
 
-const ALWAYS = [
-  [/\bgit\s+push\b.*(--force\b|\s-f\b|--force-with-lease\b)/, 'Force-push is not allowed.'],
-  [/--no-verify\b/, 'Skipping git hooks is not allowed.'],
+// Commands are recognised where they run (lib/shell.mjs), so a commit message, a heredoc, a quoted
+// --text or a grep pattern that mentions one doesn't trip its rule.
+const RUNS = [
+  [
+    new RegExp(String.raw`^${GIT}push\b.*(--force\b|\s-f\b|--force-with-lease\b)`),
+    'Force-push is not allowed.',
+  ],
+  [new RegExp(String.raw`^${GIT}\S+\b.*\s--no-verify\b`), 'Skipping git hooks is not allowed.'],
   [
-    /\brm\s+-rf?\s+(\/|~|\$HOME|\.\.?)(\s|$)/,
+    /^rm\s+-rf?\s+(\/|~|\$HOME|\.\.?)(\s|$)/,
     'Refusing a destructive delete of a root, home or parent directory.',
   ],
-  [/\b(curl|wget)\b[^|]*\|\s*(sh|bash|zsh)\b/, 'Piping downloads into a shell is not allowed.'],
-  [/\.claude\/approvals/, 'Approvals are created only by a person, with a `!` shell command.'],
+];
+for (const [re, why] of RUNS) {
+  if (runs(cmd, re, { quoted: false })) block(`Blocked: ${why}\nCommand: ${cmd}`);
+}
+// These read the command whole: a pipe spans commands, and an approval or the log can be written
+// through a quoted path.
+const ALWAYS = [
+  [
+    /\b(curl|wget)\b[^|]*\|\s*(sh|bash|zsh)\b/,
+    'Piping downloads into a shell is not allowed.',
+    codeOf(cmd),
+  ],
+  [/\.claude\/approvals/, 'Approvals are created only by a person, with a `!` shell command.', cmd],
   [
     /approval-log\.jsonl/,
     'The approval audit log is appended only by the commit hook; nobody edits it.',
+    cmd,
   ],
 ];
-for (const [re, why] of ALWAYS) {
-  if (re.test(cmd)) block(`Blocked: ${why}\nCommand: ${cmd}`);
+for (const [re, why, text] of ALWAYS) {
+  if (re.test(text)) block(`Blocked: ${why}\nCommand: ${cmd}`);
 }
 const packages = addedPackages(cmd);
-const approves = /\bcode-kit(\.mjs)?["']?\s+approve\b/.test(cmd);
-const delegatedMerge = /\bcode-kit(\.mjs)?["']?\s+merge\b/.test(cmd);
+const approves = runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+approve\b`));
+const delegatedMerge = runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+merge\b`));
+const commits = runs(cmd, new RegExp(String.raw`^${GIT}commit\b`));
 if (error) {
-  if (/\bgit\s+commit\b/.test(cmd)) block(`Blocked: ${error}\nFix the config before committing.`);
+  if (commits) block(`Blocked: ${error}\nFix the config before committing.`);
   if (approves) block(`Blocked: ${error}\nApprovals wait until the config is valid.`);
   if (delegatedMerge) block(`Blocked: ${error}\nMerges wait until the config is valid.`);
   if (packages.length)
@@ -62,23 +83,35 @@ const branches = config.branches.protected
 // The branch is read before the command runs, so a command that switches to a protected branch and then
 // commits or merges in the same breath is judged by what it does, not by where it starts. Moving a
 // protected branch directly (branch -f, update-ref) is a commit on it by another name.
-const writesHistory = /\bgit\s+(commit|merge|cherry-pick|rebase|revert|am)\b/.test(cmd);
-const switchesToProtected = new RegExp(
-  `\\bgit\\s+(?:switch|checkout)\\s+(?:-[^\\s]+\\s+)*(${branches})(?![\\w./-])(?!\\s+--)`,
-).test(cmd);
-const movesProtected =
+const writesHistory = runs(
+  cmd,
+  new RegExp(String.raw`^${GIT}(commit|merge|cherry-pick|rebase|revert|am)\b`),
+);
+const switchesToProtected = runs(
+  cmd,
   new RegExp(
-    `\\bgit\\s+branch\\s+(?:\\S+\\s+)*(?:-f|--force|-M|-C)\\b.*\\b(${branches})(?![\\w./-])`,
-  ).test(cmd) ||
-  new RegExp(
-    `\\bgit\\s+update-ref\\s+(?:-\\S+\\s+)*(?:refs/heads/)?(${branches})(?![\\w./-])`,
-  ).test(cmd);
+    String.raw`^${GIT}(?:switch|checkout)\s+(?:-[^\s]+\s+)*(${branches})(?![\w./-])(?!\s+--)`,
+  ),
+);
+const movesProtected =
+  runs(
+    cmd,
+    new RegExp(
+      String.raw`^${GIT}branch\s+(?:\S+\s+)*(?:-f|--force|-M|-C)\b.*\b(${branches})(?![\w./-])`,
+    ),
+  ) ||
+  runs(
+    cmd,
+    new RegExp(
+      String.raw`^${GIT}update-ref\s+(?:-\S+\s+)*(?:refs/heads/)?(${branches})(?![\w./-])`,
+    ),
+  );
 if ((switchesToProtected && writesHistory) || movesProtected) {
   block(
     `Blocked: never commit to, merge into or move ${config.branches.protected.join(' or ')}, even by switching to it first. Work on a branch; a person merges after review${config.approvals.delegate?.merge ? ', or the lead merges a verified branch with `code-kit merge <branch> --delegated`' : ''}.\nCommand: ${cmd}`,
   );
 }
-if (new RegExp(`\\bgit\\s+push\\b.*\\b(${branches})\\b`).test(cmd)) {
+if (runs(cmd, new RegExp(String.raw`^${GIT}push\b.*\b(${branches})\b`))) {
   block(
     `Blocked: push to your own branch; a person merges to ${config.branches.protected[0]} after review.\nCommand: ${cmd}`,
   );
@@ -107,6 +140,11 @@ if ((delegatedMerge && /\s--person\b/.test(cmd)) || (approves && /\s--via\b/.tes
   block(
     `Blocked: merging or approving as the person is the person's own act, from the code-kit pane or their terminal. Ask them, and stop.\nCommand: ${cmd}`,
   );
+// The harness settings are the person's to change, from the pane or their terminal.
+if (runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+settings\s+set\b`)))
+  block(
+    `Blocked: changing the harness settings is the person's own act, from the code-kit pane (/harness) or their terminal. Tell them what you'd change and why, and stop.\nCommand: ${cmd}`,
+  );
 if (delegatedMerge && actor.kind !== 'lead')
   block(
     `Blocked: only the lead merges into a protected branch. Finish your story and commit it on your branch; the lead reviews and merges it.\nCommand: ${cmd}`,
@@ -180,10 +218,7 @@ try {
 } catch {
   // not a git repository yet
 }
-if (
-  /\bgit\s+(commit|merge|cherry-pick|rebase|revert)\b/.test(cmd) &&
-  config.branches.protected.includes(branch)
-) {
+if (writesHistory && config.branches.protected.includes(branch)) {
   block(
     `Blocked: never commit or merge on ${branch}. Work on a branch; a person merges after review.`,
   );
@@ -253,6 +288,8 @@ function recordApprovals() {
       }),
     );
   for (const file of files) {
+    // Concluding a merge: what arrives as the other branch has it was logged there, with its approvals.
+    if (arrivesWithMerge(root, file, { staged: true })) continue;
     const entry = protectedEntry(file, config);
     const granted = entry && approval(root, entry.approval, actor);
     const byDependency = actor.kind === 'lane' && dependencyChange(actor, file, root, config);
@@ -283,12 +320,30 @@ function recordApprovals() {
         grantedAt: null,
       });
   }
+  // A dependency approval is used up by the commit that adds its package to a manifest or lockfile.
+  const manifests = files.filter((f) => isDependencyFile(f));
+  if (manifests.length && actor.kind !== 'readonly') {
+    // The lines each manifest gains on HEAD, read from the working tree: this hook runs before
+    // `git add … && git commit` has staged anything, and a new manifest isn't tracked yet.
+    const added = manifests
+      .flatMap((f) => {
+        const before = new Set(git('show', `HEAD:${f}`).split('\n'));
+        const now = existsSync(join(root, f)) ? readFileSync(join(root, f), 'utf8') : '';
+        return now.split('\n').filter((l) => !before.has(l));
+      })
+      .join('\n');
+    for (const g of dependencyGrants(root, actor)) {
+      const pkg = g.name.slice('dep-'.length).replaceAll('+', '/');
+      const quoted = pkg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      if (new RegExp(`["'\\s/]${quoted}["'@=:\\s]`).test(added)) useApproval(root, g.name, actor);
+    }
+  }
   if (lines.length === 0) return;
   appendFileSync(join(root, APPROVAL_LOG), `${lines.join('\n')}\n`);
   git('add', APPROVAL_LOG);
 }
 
-if (/\bgit\s+commit\b/.test(cmd)) {
+if (commits) {
   recordApprovals();
   const scan = spawnSync('gitleaks', ['protect', '--staged', '--redact', '--no-banner'], {
     cwd: root,

package/hooks/lane-audit.mjs

@@ -5,7 +5,14 @@
 import { readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { join } from 'node:path';
-import { APPROVAL_LOG, LANE_FILE, actorFor, actorRoot, writeProblem } from './lib/rules.mjs';
+import {
+  APPROVAL_LOG,
+  LANE_FILE,
+  actorFor,
+  actorRoot,
+  arrivesWithMerge,
+  writeProblem,
+} from './lib/rules.mjs';
 
 // The commit hook appends to the approval log and stages it; if that commit then fails, the
 // appended lines are left uncommitted. That is the only change to the log that is not a problem.
@@ -36,11 +43,15 @@ export function auditProblems(input, config) {
   const root = actorRoot(input);
   if (!root) return [];
   const actor = actorFor(input, root, config);
-  return changedFiles(root)
-    .filter((rel) => !(rel === APPROVAL_LOG && appendedOnly(root, rel)))
-    .map((rel) => [rel, writeProblem(actor, rel, root, config)])
-    .filter(([, problem]) => problem)
-    .map(([rel, problem]) => `${rel}: ${problem.split('\n')[0]}`);
+  return (
+    changedFiles(root)
+      .filter((rel) => !(rel === APPROVAL_LOG && appendedOnly(root, rel)))
+      // Mid-merge, the incoming branch's changes are its own, not this actor's writes.
+      .filter((rel) => !arrivesWithMerge(root, rel))
+      .map((rel) => [rel, writeProblem(actor, rel, root, config)])
+      .filter(([, problem]) => problem)
+      .map(([rel, problem]) => `${rel}: ${problem.split('\n')[0]}`)
+  );
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {

package/hooks/lib/config.mjs

@@ -1,6 +1,7 @@
 // The project's rules live in .claude/code-kit.json. The hooks read it from the project the session
 // was opened in; a project without one is not governed by the kit, and an invalid one fails closed.
 import { existsSync, readFileSync } from 'node:fs';
+import { harnessProblems, harnessSettings } from './harness.mjs';
 import { join } from 'node:path';
 import { ADAPTERS, applyAdapters } from './adapters/index.mjs';
 
@@ -31,6 +32,9 @@ export function loadConfig(projectDir) {
 /** The rules the hooks enforce: the project's config, the kit's defaults, and any active adapters. */
 export const effectiveConfig = (raw, root) => applyAdapters(withDefaults(raw), raw, root);
 
+/** An anyActor entry's glob: entries are globs, or { glob, reviewer } naming who reviews changes to it. */
+export const anyActorGlob = (e) => (typeof e === 'string' ? e : e?.glob);
+
 /** The engine's fixed rules, merged into the project's: the kit and Claude's own files belong to the lead. */
 export function withDefaults(c) {
   return {
@@ -39,7 +43,11 @@ export function withDefaults(c) {
       paths: [...c.lead.paths, '.claude/**'],
       outside: [...(c.lead.outside ?? []), ...CLAUDE_OWN],
     },
-    anyActor: [...(c.anyActor ?? []), '.claude/state/**'],
+    anyActor: [...(c.anyActor ?? []).map(anyActorGlob), '.claude/state/**'],
+    // Who reviews changes to files any agent may write; the lead unless an entry names a lane.
+    anyActorReviewers: (c.anyActor ?? [])
+      .filter((e) => typeof e === 'object' && e?.reviewer)
+      .map((e) => ({ glob: e.glob, reviewer: e.reviewer })),
     protected: [KIT, ...(c.protected ?? []).filter((p) => p.glob !== KIT.glob)],
     layers: c.layers ?? [],
     importAliases: c.importAliases ?? {},
@@ -48,6 +56,7 @@ export function withDefaults(c) {
     checks: c.checks ?? [],
     branches: { protected: c.branches?.protected ?? ['main', 'master'] },
     approvals: { lead: c.approvals?.lead === true, delegate: delegateRules(c.approvals?.delegate) },
+    harness: harnessSettings(c.harness),
   };
 }
 
@@ -71,7 +80,12 @@ function delegateRules(d) {
           ],
           minWeeklyDownloads: d.dependencies.minWeeklyDownloads ?? 10_000,
           maxMonthsSinceRelease: d.dependencies.maxMonthsSinceRelease ?? 18,
-          allowInstallScripts: d.dependencies.allowInstallScripts === true,
+          // true (any), false (none), or the kinds allowed: binary, build (lib/registry.mjs).
+          allowInstallScripts:
+            d.dependencies.allowInstallScripts === true ||
+            (Array.isArray(d.dependencies.allowInstallScripts)
+              ? d.dependencies.allowInstallScripts
+              : false),
         }
       : null,
   };
@@ -113,9 +127,20 @@ export function validate(c) {
     c.lead?.outside === undefined || isList(c.lead.outside),
     '"lead.outside" must be a list of globs',
   );
-  need(c.anyActor === undefined || isList(c.anyActor), '"anyActor" must be a list of globs');
   validateLanes(c, need);
   const lanes = Object.keys(isObj(c.lanes) ? c.lanes : {});
+  need(
+    c.anyActor === undefined ||
+      (Array.isArray(c.anyActor) &&
+        c.anyActor.every(
+          (e) =>
+            isStr(e) ||
+            (isObj(e) &&
+              isStr(e.glob) &&
+              (e.reviewer === undefined || e.reviewer === 'lead' || lanes.includes(e.reviewer))),
+        )),
+    '"anyActor" must be a list of globs, or { "glob", "reviewer" } with the lead or a lane as reviewer',
+  );
   each('protected', (e, at) => {
     need(isStr(e.glob) && isStr(e.why), `${at} needs "glob" and "why"`);
     need(
@@ -159,13 +184,16 @@ export function validate(c) {
             (dep.licences === undefined || isList(dep.licences)) &&
             isCount(dep.minWeeklyDownloads) &&
             isCount(dep.maxMonthsSinceRelease) &&
-            [undefined, true, false].includes(dep.allowInstallScripts)))),
-    '"approvals.delegate" must be { protected?: [approval names], merge?: true|false, dependencies?: { licences?, minWeeklyDownloads?, maxMonthsSinceRelease?, allowInstallScripts? } }',
+            ([undefined, true, false].includes(dep.allowInstallScripts) ||
+              (isList(dep.allowInstallScripts) &&
+                dep.allowInstallScripts.every((k) => ['binary', 'build', 'other'].includes(k))))))),
+    '"approvals.delegate" must be { protected?: [approval names], merge?: true|false, dependencies?: { licences?, minWeeklyDownloads?, maxMonthsSinceRelease?, allowInstallScripts?: true|false|["binary","build","other"] } }',
   );
   need(
     c.branches === undefined || isList(c.branches?.protected),
     '"branches.protected" must be a list of branch names',
   );
+  p.push(...harnessProblems(c.harness));
   return p;
 }
 

package/hooks/lib/diff.mjs

@@ -2,6 +2,10 @@
 // lanes, layers and rules added, removed or changed, and which files would change owner.
 import { ownerOf } from './rules.mjs';
 
+/** An anyActor entry in words: its glob, with its reviewer when named. */
+const anyActorText = (e) =>
+  typeof e === 'string' ? e : `${e.glob} (reviewed by ${e.reviewer ?? 'the lead'})`;
+
 const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 const lists = (a = [], b = []) => ({
   added: b.filter((x) => !a.includes(x)),
@@ -95,7 +99,7 @@ export function diffConfigs(before, after) {
   for (const [label, a, b] of [
     ['lead paths', before.lead?.paths, after.lead?.paths],
     ['lead outside paths', before.lead?.outside, after.lead?.outside],
-    ['any-actor paths', before.anyActor, after.anyActor],
+    ['any-actor paths', before.anyActor?.map(anyActorText), after.anyActor?.map(anyActorText)],
     ['protected branches', before.branches?.protected, after.branches?.protected],
   ]) {
     const change = listChange('', a, b);

package/hooks/lib/harness.mjs

@@ -0,0 +1,131 @@
+// The harness's settings (docs/specs/12-settings.md): the `harness` section of .claude/code-kit.json,
+// what the mod's loop, hold, reviewer and usage read. Defaults fill what the section leaves out; a value
+// out of range is a config problem like any other.
+
+export const AUTONOMY = ['autonomous', 'propose', 'off'];
+export const MODELS = ['haiku', 'sonnet', 'opus'];
+
+/** Each setting by its dotted key: its default, and why a value is wrong (or null when it's right). */
+export const SETTINGS = {
+  autonomy: {
+    default: 'autonomous',
+    problem: (v) => (AUTONOMY.includes(v) ? null : `must be one of ${AUTONOMY.join(', ')}`),
+    about: 'How the lead loop acts: on its own, by proposing each step, or not at all',
+  },
+  'hold.minutes': {
+    default: 2,
+    problem: (v) =>
+      Number.isFinite(v) && v >= 0 && v <= 30
+        ? null
+        : 'must be a number of minutes from 0 (off) to 30',
+    about: 'How long a call waiting on your approval is held before it is refused',
+  },
+  'stall.nudgeMinutes': {
+    default: 5,
+    problem: (v) =>
+      Number.isFinite(v) && v >= 1 ? null : 'must be a number of minutes, at least 1',
+    about: 'Minutes without a tool call before a lane agent is nudged',
+  },
+  'stall.restartMinutes': {
+    default: 10,
+    problem: (v) =>
+      Number.isFinite(v) && v >= 1 ? null : 'must be a number of minutes, at least 1',
+    about: 'Minutes without a tool call before a lane agent is restarted',
+  },
+  'stall.maxRestarts': {
+    default: 2,
+    problem: (v) =>
+      Number.isInteger(v) && v >= 0 && v <= 10 ? null : 'must be a whole number from 0 to 10',
+    about: 'Restarts on one story before the lane is flagged for you',
+  },
+  'agents.reviewer.on': {
+    default: false,
+    problem: (v) => (typeof v === 'boolean' ? null : 'must be true or false'),
+    about: 'A background reviewer for each finished branch',
+  },
+  'agents.reviewer.model': {
+    default: null,
+    problem: (v) =>
+      v === null || (typeof v === 'string' && v.length > 0)
+        ? null
+        : `must be a model (${MODELS.join(', ')}, or an id), or null for the session's`,
+    about: "The reviewer's model; none means the session's",
+  },
+  'background.pauseAtPercent': {
+    default: 80,
+    problem: (v) =>
+      Number.isFinite(v) && v > 0 && v <= 100 ? null : 'must be a percentage from 1 to 100',
+    about: "The plan's 5-hour use at which background agents pause",
+  },
+};
+
+const get = (obj, key) =>
+  key.split('.').reduce((o, k) => (o && typeof o === 'object' ? o[k] : undefined), obj);
+const set = (obj, key, value) => {
+  const parts = key.split('.');
+  let o = obj;
+  for (const k of parts.slice(0, -1)) o = o[k] && typeof o[k] === 'object' ? o[k] : (o[k] = {});
+  o[parts.at(-1)] = value;
+  return obj;
+};
+
+/** Every key the section holds, as dotted keys: `stall.nudgeMinutes`, `agents.reviewer.on`… */
+function keysOf(obj, prefix = '') {
+  return Object.entries(obj ?? {}).flatMap(([k, v]) =>
+    v && typeof v === 'object' && !Array.isArray(v) && !(`${prefix}${k}` in SETTINGS)
+      ? keysOf(v, `${prefix}${k}.`)
+      : [`${prefix}${k}`],
+  );
+}
+
+/** The settings in force: the section's values over the defaults, as a nested object. A value that's
+ * wrong (reported by `harnessProblems`) gives way to the default. */
+export function harnessSettings(section) {
+  const out = {};
+  for (const [key, s] of Object.entries(SETTINGS)) {
+    const v = section && typeof section === 'object' ? get(section, key) : undefined;
+    set(out, key, v === undefined || s.problem(v) ? s.default : v);
+  }
+  return out;
+}
+
+/** The section's problems, in the config's words. */
+export function harnessProblems(section) {
+  if (section === undefined) return [];
+  if (!section || typeof section !== 'object' || Array.isArray(section))
+    return ['"harness" must be an object'];
+  const p = [];
+  for (const key of keysOf(section)) {
+    if (!(key in SETTINGS)) {
+      p.push(
+        `"harness.${key}" isn't a harness setting (they are ${Object.keys(SETTINGS).join(', ')})`,
+      );
+      continue;
+    }
+    const why = SETTINGS[key].problem(get(section, key));
+    if (why) p.push(`"harness.${key}" ${why}`);
+  }
+  const h = harnessSettings(section);
+  if (h.stall.restartMinutes <= h.stall.nudgeMinutes)
+    p.push('"harness.stall.restartMinutes" must be more than "harness.stall.nudgeMinutes"');
+  return p;
+}
+
+/** A value typed on the command line, as the setting's type: numbers, true and false, null, or text. */
+export function parseSetting(key, text) {
+  const d = SETTINGS[key]?.default;
+  if (text === 'null') return null;
+  if (typeof d === 'boolean' || text === 'true' || text === 'false')
+    return text === 'true' ? true : text === 'false' ? false : text;
+  if (typeof d === 'number' && /^-?\d+(\.\d+)?$/.test(text)) return Number(text);
+  return text;
+}
+
+/** The raw config with one harness setting changed (a copy). */
+export function withSetting(raw, key, value) {
+  const copy = structuredClone(raw);
+  copy.harness = set(copy.harness ?? {}, key, value);
+  return copy;
+}
+
+export { get as settingOf };

package/hooks/lib/next.mjs

@@ -150,7 +150,9 @@ export function nextStep(root, base) {
     );
 
   const ids = (state) => status.stories.filter((s) => s.state === state).map((s) => s.id);
-  const [review, building, blocked] = ['review', 'in progress', 'blocked'].map(ids);
+  const [review, building, blocked, fixes] = ['review', 'in progress', 'blocked', 'sent back'].map(
+    ids,
+  );
   // A ready story with a gap (unknown lane, a requirement no spec defines) waits for the plan's fix.
   const defined = new Set(status.requirements.map((r) => r.id));
   const buildable = (s) =>
@@ -167,13 +169,22 @@ export function nextStep(root, base) {
       `${unbuildable.join(', ')} can't be dispatched until the plan's gaps are fixed.`,
     );
   const then = [];
-  if (review.length && ready.length) then.push({ step: 'dispatch', args: ready.join(' ') });
+  // A sent-back story goes back to its lane with the review's findings, before new work starts.
+  const toDispatch = [...fixes, ...ready];
+  if (review.length && toDispatch.length)
+    then.push({ step: 'dispatch', args: toDispatch.join(' ') });
   if (forLead.length) then.push({ step: 'lead', args: forLead.join(' ') });
   if (review.length)
     return result('review', `${review.join(', ')} finished and wait for review.`, {
       args: review.join(' '),
       then,
     });
+  if (fixes.length)
+    return result(
+      'dispatch',
+      `${fixes.join(', ')} ${fixes.length === 1 ? 'was' : 'were'} sent back and ${fixes.length === 1 ? 'waits' : 'wait'} for the lane's fix: dispatch ${fixes.length === 1 ? 'it' : 'each'} again with the review's findings${ready.length ? `, then ${ready.join(', ')}` : ''}.`,
+      { args: toDispatch.join(' '), then },
+    );
   if (ready.length)
     return result('dispatch', `${ready.join(', ')} can start: their dependencies are done.`, {
       args: ready.join(' '),

package/hooks/lib/plan.mjs

@@ -7,6 +7,7 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
+import { sentBack } from './reviews.mjs';
 
 export const REQUIREMENT = /\b(?!ST-)([A-Z][A-Z0-9]*-\d+)\b/g;
 const STORY_HEADING = /^###\s+(ST-\d+)\b\s*(.*)$/;
@@ -125,18 +126,22 @@ function worktrees(root) {
  * Where each story is. The plan's `done` stands (the lead marks it after merging, and merged
  * branches are often deleted or squashed). Otherwise git decides: a branch with commits not in
  * `base` is in review; one level with it is in progress, or done once the plan had it in review.
- * Without a branch, the plan's status stands. A todo story is `blocked` until every story it
- * depends on is done, then `ready`.
+ * A branch still at the commit a review sent back is `sent back`, waiting for its lane's fix.
+ * Without a branch, the plan's status stands. A story is `blocked` while a story it depends on
+ * isn't done, whatever its branch holds; a todo story whose dependencies are done is `ready`.
  */
 export function storyStates(root, stories, base) {
   const trees = worktrees(root);
+  const backs = sentBack(root);
   const states = stories.map((story) => {
     const branch = storyBranch(story);
     const ref = story.lane ? branchRef(root, branch) : null;
     const ahead = ref ? Number(git(root, 'rev-list', '--count', `${base}..${ref}`) ?? 0) : 0;
     let state = story.status;
     if (ref && story.status !== 'done') {
-      if (ahead > 0) state = 'review';
+      const head = backs[branch] ? git(root, 'rev-parse', ref) : null;
+      if (head && head === backs[branch].sha) state = 'sent back';
+      else if (ahead > 0) state = 'review';
       else state = story.status === 'review' ? 'done' : 'in progress';
     }
     return {
@@ -151,9 +156,10 @@ export function storyStates(root, stories, base) {
   });
   const done = new Set(states.filter((s) => s.state === 'done').map((s) => s.id));
   for (const s of states) {
-    if (s.state !== 'todo') continue;
+    if (s.state === 'done') continue;
     s.waitingOn = s.dependsOn.filter((d) => !done.has(d));
-    s.state = s.waitingOn.length ? 'blocked' : 'ready';
+    if (s.waitingOn.length) s.state = 'blocked';
+    else if (s.state === 'todo') s.state = 'ready';
   }
   return states;
 }
@@ -200,13 +206,18 @@ export function buildStatus(root, config, base, files) {
     let state = 'no story';
     if (r.removed) state = 'removed';
     else if (covering.length && covering.every((s) => s.state === 'done')) state = 'done';
-    else if (covering.some((s) => ['in progress', 'review', 'done'].includes(s.state)))
+    else if (covering.some((s) => ['in progress', 'review', 'sent back', 'done'].includes(s.state)))
       state = 'in progress';
     else if (covering.length) state = 'todo';
     return { ...r, state, stories: covering.map((s) => s.id), tests: tested[r.id] ?? [] };
   });
   const drift = stories
-    .filter((s) => !['ready', 'blocked'].includes(s.state) && s.state !== s.status)
+    .filter(
+      (s) =>
+        !['ready', 'blocked'].includes(s.state) &&
+        s.state !== s.status &&
+        !(s.state === 'sent back' && s.status === 'in progress'),
+    )
     .map((s) => ({ story: s.id, plan: s.status, actual: s.state }));
   return { stories, requirements: byRequirement, problems, drift };
 }

package/hooks/lib/registry.mjs

@@ -12,7 +12,35 @@ export const packageOf = (approvalName) =>
 
 const INSTALL_SCRIPTS = ['preinstall', 'install', 'postinstall'];
 
-/** { licence, weeklyDownloads, lastRelease (ISO), installScripts } for `pkg`, or { error }. */
+// Kinds of install script, for the rule's allowInstallScripts:
+//   binary  fetches a prebuilt binary for this platform (esbuild, sharp): a prebuild tool, or a script
+//           beside optional dependencies built per platform;
+//   build   compiles native code from source (node-gyp);
+//   other   anything else: code the package runs on install.
+const BINARY_TOOLS =
+  /\b(prebuild-install|node-pre-gyp|node-gyp-build|prebuildify|napi-postinstall)\b/;
+const PLATFORM = /(darwin|linux|win32|windows|freebsd|android|musl|arm64|x64|ia32)/;
+
+/** The kind of install script a package version runs (binary, build or other), or null for none. */
+export function installScriptKind(version) {
+  const scripts = INSTALL_SCRIPTS.map((s) => version?.scripts?.[s]).filter(Boolean);
+  if (!scripts.length) return null;
+  const text = scripts.join(' && ');
+  const perPlatform = Object.keys(version?.optionalDependencies ?? {}).filter((d) =>
+    PLATFORM.test(d),
+  );
+  if (BINARY_TOOLS.test(text) || perPlatform.length >= 2) return 'binary';
+  if (/\bnode-gyp\b|\bcmake-js\b/.test(text)) return 'build';
+  return 'other';
+}
+
+const KIND_WORDS = {
+  binary: 'downloads a prebuilt binary',
+  build: 'compiles native code',
+  other: 'runs its own code',
+};
+
+/** { licence, weeklyDownloads, lastRelease (ISO), installScripts, installScriptKind } for `pkg`, or { error }. */
 export async function npmFacts(pkg) {
   const name = pkg.startsWith('@')
     ? `@${encodeURIComponent(pkg.slice(1))}`
@@ -34,6 +62,7 @@ export async function npmFacts(pkg) {
       weeklyDownloads,
       lastRelease: (latest && doc.time?.[latest]) ?? doc.time?.modified ?? null,
       installScripts: INSTALL_SCRIPTS.some((s) => version?.scripts?.[s]),
+      installScriptKind: installScriptKind(version),
     };
   } catch (e) {
     return { error: `couldn't reach the npm registry (${e.message})` };
@@ -57,7 +86,12 @@ export function dependencyRuleProblems(facts, rule, now = Date.now()) {
     problems.push(
       `its last release was ${Number.isFinite(months) ? `${Math.floor(months)} months` : 'never'} ago, over ${rule.maxMonthsSinceRelease}`,
     );
-  if (facts.installScripts && !rule.allowInstallScripts)
-    problems.push('installing it runs scripts');
+  if (facts.installScripts) {
+    const kind = facts.installScriptKind ?? 'other';
+    const allowed =
+      rule.allowInstallScripts === true ||
+      (Array.isArray(rule.allowInstallScripts) && rule.allowInstallScripts.includes(kind));
+    if (!allowed) problems.push(`installing it runs a script that ${KIND_WORDS[kind]}`);
+  }
   return problems;
 }