@warren-dean/code-kit 0.3.4

package/hooks/lib/diff.mjs

@@ -0,0 +1,122 @@
+// What a proposed config changes compared with the live one, in words a person can approve:
+// lanes, layers and rules added, removed or changed, and which files would change owner.
+import { ownerOf } from './rules.mjs';
+
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const lists = (a = [], b = []) => ({
+  added: b.filter((x) => !a.includes(x)),
+  removed: a.filter((x) => !b.includes(x)),
+});
+
+/** "+ x, y; - z" for a list field, or null when it didn't change. */
+function listChange(name, a, b) {
+  const { added, removed } = lists(a, b);
+  const parts = [
+    added.length && `+ ${added.join(', ')}`,
+    removed.length && `- ${removed.join(', ')}`,
+  ].filter(Boolean);
+  return parts.length ? `${name} ${parts.join('; ')}` : null;
+}
+
+/** Lines for a keyed collection: `+` added, `-` removed, `~` changed (with `describe` for the detail). */
+function keyed(label, before = {}, after = {}, describe) {
+  const lines = [];
+  for (const key of Object.keys(after)) {
+    if (!(key in before)) lines.push(`+ ${label} ${key}: ${describe.summary(after[key])}`);
+    else if (!same(before[key], after[key]))
+      lines.push(`~ ${label} ${key}: ${describe.change(before[key], after[key])}`);
+  }
+  for (const key of Object.keys(before)) if (!(key in after)) lines.push(`- ${label} ${key}`);
+  return lines;
+}
+
+const byName = (items = [], key = 'name') => Object.fromEntries(items.map((i) => [i[key], i]));
+
+const fieldChanges = (a, b, fields) =>
+  fields
+    .map((f) =>
+      Array.isArray(a[f]) || Array.isArray(b[f])
+        ? listChange(f, a[f], b[f])
+        : same(a[f], b[f])
+          ? null
+          : `${f} ${JSON.stringify(a[f])} → ${JSON.stringify(b[f])}`,
+    )
+    .filter(Boolean)
+    .join('; ');
+
+const LANE = {
+  summary: (l) =>
+    `${l.agent}, ${l.paths.join(', ')}${l.exclude?.length ? ` (except ${l.exclude.join(', ')})` : ''}`,
+  change: (a, b) => fieldChanges(a, b, ['agent', 'paths', 'exclude']),
+};
+const LAYER = {
+  summary: (l) => `${l.paths.join(', ')} → may import ${l.mayImport.join(', ') || 'nothing'}`,
+  change: (a, b) => fieldChanges(a, b, ['paths', 'mayImport', 'denyPackages']),
+};
+const CHECK = {
+  summary: (c) => `${c.run.join(' && ')} when ${c.files.join(', ')} change`,
+  change: (a, b) =>
+    fieldChanges(a, b, [
+      'files',
+      'exclude',
+      'run',
+      'each',
+      'owners',
+      'ifMissing',
+      'timeoutSeconds',
+    ]),
+};
+const RULE = {
+  summary: (r) => r.why ?? r.glob ?? JSON.stringify(r),
+  change: (a, b) => `${JSON.stringify(a)} → ${JSON.stringify(b)}`,
+};
+
+/** Every difference between two raw configs (as written in the file, before defaults). */
+export function diffConfigs(before, after) {
+  const lines = [
+    ...keyed('lane', before.lanes, after.lanes, LANE),
+    ...keyed('layer', byName(before.layers), byName(after.layers), LAYER),
+    ...keyed('check', byName(before.checks), byName(after.checks), CHECK),
+    ...keyed('protected', byName(before.protected, 'glob'), byName(after.protected, 'glob'), RULE),
+    ...keyed(
+      'blocked command',
+      byName(before.shell?.block, 'pattern'),
+      byName(after.shell?.block, 'pattern'),
+      RULE,
+    ),
+    ...keyed(
+      'restricted command',
+      byName(before.shell?.restricted, 'pattern'),
+      byName(after.shell?.restricted, 'pattern'),
+      RULE,
+    ),
+    ...keyed('per-file check', byName(before.postEdit, 'run'), byName(after.postEdit, 'run'), RULE),
+  ];
+  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],
+    ['protected branches', before.branches?.protected, after.branches?.protected],
+  ]) {
+    const change = listChange('', a, b);
+    if (change) lines.push(`~ ${label}:${change}`);
+  }
+  for (const key of ['docs', 'designGate', 'importAliases']) {
+    if (!same(before[key], after[key]))
+      lines.push(
+        `~ ${key}: ${JSON.stringify(before[key] ?? null)} → ${JSON.stringify(after[key] ?? null)}`,
+      );
+  }
+  return lines;
+}
+
+/** Files whose owner differs between two configs (with defaults applied): { file, from, to }. */
+export function ownershipMoves(files, before, after) {
+  return files
+    .map((file) => ({
+      file,
+      from: ownerOf(file, before) ?? 'nobody',
+      to: ownerOf(file, after) ?? 'nobody',
+    }))
+    .filter((m) => m.from !== m.to);
+}

package/hooks/lib/glob.mjs

@@ -0,0 +1,42 @@
+// Path globs as used in .claude/code-kit.json: `*` within one segment, `**` across segments,
+// `**/` for zero or more directories, `?` for one character and `{a,b}` for alternatives.
+
+function source(glob) {
+  let out = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*' && glob[i + 1] === '*') {
+      i++;
+      if (glob[i + 1] === '/') {
+        i++;
+        out += '(?:.*/)?';
+      } else {
+        out += '.*';
+      }
+    } else if (c === '*') {
+      out += '[^/]*';
+    } else if (c === '?') {
+      out += '[^/]';
+    } else if (c === '{' && glob.indexOf('}', i) > i) {
+      const end = glob.indexOf('}', i);
+      out += `(?:${glob
+        .slice(i + 1, end)
+        .split(',')
+        .map(source)
+        .join('|')})`;
+      i = end;
+    } else {
+      out += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return out;
+}
+
+const cache = new Map();
+
+export function globToRegExp(glob) {
+  if (!cache.has(glob)) cache.set(glob, new RegExp(`^${source(glob)}$`));
+  return cache.get(glob);
+}
+
+export const matchesAny = (path, globs = []) => globs.some((g) => globToRegExp(g).test(path));

package/hooks/lib/hook.mjs

@@ -0,0 +1,19 @@
+// What every hook starts with: the tool call from stdin, the project and its config.
+import { readFileSync } from 'node:fs';
+import { loadConfig } from './config.mjs';
+import { projectDir } from './rules.mjs';
+
+/** Exit 2 with a message: Claude Code blocks the call and shows Claude the reason. */
+export function block(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(2);
+}
+
+/** The hook input, project and config; exits quietly when the project does not use the kit. */
+export function start() {
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  const project = projectDir();
+  const { config, error } = loadConfig(project);
+  if (!config && !error) process.exit(0);
+  return { input, project, config, error };
+}

package/hooks/lib/layers.mjs

@@ -0,0 +1,57 @@
+// Layer rules: each layer lists the layers it may depend on, and optionally packages it may not use.
+// Imports are read from JavaScript and TypeScript source; a file outside every layer is not checked.
+import { posix } from 'node:path';
+import { matchesAny } from './glob.mjs';
+
+export const CODE = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
+
+const SPECIFIERS = [
+  /\bfrom\s*['"]([^'"\n]+)['"]/g, // import … from 'x', export … from 'x'
+  /^\s*import\s*['"]([^'"\n]+)['"]/gm, // import 'x'
+  /\b(?:require|import)\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g, // require('x'), import('x')
+];
+
+export function importsOf(source) {
+  const found = new Set();
+  for (const re of SPECIFIERS) for (const m of source.matchAll(re)) found.add(m[1]);
+  return [...found];
+}
+
+export const layerOf = (rel, layers) => layers.find((l) => matchesAny(rel, l.paths));
+
+/** The repository path an import points at, or null for a package. */
+export function targetOf(spec, rel, aliases) {
+  if (spec.startsWith('./') || spec.startsWith('../'))
+    return posix.normalize(posix.join(posix.dirname(rel), spec));
+  const prefix = Object.keys(aliases)
+    .sort((a, b) => b.length - a.length)
+    .find((a) => spec === a || spec.startsWith(`${a}/`));
+  return prefix === undefined
+    ? null
+    : posix.normalize(posix.join(aliases[prefix], spec.slice(prefix.length)));
+}
+
+/** Every import in `source` (the file at repo path `rel`) that breaks the layer rules. */
+export function layerProblems(rel, source, config) {
+  if (!CODE.test(rel) || config.layers.length === 0) return [];
+  const layer = layerOf(rel, config.layers);
+  if (!layer) return [];
+  const allowed = new Set([layer.name, ...layer.mayImport]);
+  const problems = [];
+  for (const spec of importsOf(source)) {
+    const target = targetOf(spec, rel, config.importAliases);
+    if (target === null) {
+      if (matchesAny(spec, layer.denyPackages))
+        problems.push(`${rel} (${layer.name}) may not import the package ${spec}.`);
+      continue;
+    }
+    const to = layerOf(target, config.layers) ?? layerOf(`${target}/index`, config.layers);
+    if (to && !allowed.has(to.name)) {
+      const may = layer.mayImport.length ? layer.mayImport.join(', ') : 'no other layer';
+      problems.push(
+        `${rel} (${layer.name}) imports ${spec} (${to.name}); ${layer.name} may depend on ${may}.`,
+      );
+    }
+  }
+  return problems;
+}

package/hooks/lib/next.mjs

@@ -0,0 +1,197 @@
+// What to do next, from the project's state alone: no docs → spec-design; a spec still being shaped →
+// spec-design; a ready spec or existing code without the kit → init; then, from the plan and git:
+// review finished stories, dispatch ready ones, wait on running ones, or plan the next milestone.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { loadConfig } from './config.mjs';
+import { buildStatus, readStories } from './plan.mjs';
+
+export const DRAFT_FILE = '.claude/code-kit.draft.json';
+export const BRIEF_STATES = ['framed', 'explored', 'scoped', 'specified', 'planned', 'ready'];
+
+const git = (root, ...args) => {
+  try {
+    return execFileSync('git', ['-C', root, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return null;
+  }
+};
+
+/** The spec-design brief: { path, status, openQuestions: [question, ...] }, or null. */
+export function readBrief(root, config) {
+  const specs = config?.docs?.specs;
+  const candidates = [specs && `${posix.dirname(specs)}/brief.md`, 'docs/brief.md'].filter(Boolean);
+  const path = candidates.find((p) => existsSync(join(root, p)));
+  if (!path) return null;
+  const lines = readFileSync(join(root, path), 'utf8').split('\n');
+  const status = lines
+    .map((l) => l.match(/^\*\*Status:\*\*\s*([a-z ]+?)\s*$/i)?.[1]?.toLowerCase())
+    .find((s) => BRIEF_STATES.includes(s));
+  const start = lines.findIndex((l) => /^##\s+Open questions/i.test(l));
+  const section = start < 0 ? [] : lines.slice(start + 1);
+  const end = section.findIndex((l) => /^##\s/.test(l));
+  const openQuestions = section
+    .slice(0, end < 0 ? undefined : end)
+    .filter((l) => /^\|/.test(l) && !/^\|\s*-/.test(l) && !/^\|\s*Question\s*\|/i.test(l))
+    .map((l) => l.split('|')[1].trim())
+    .filter((q) => q && !q.startsWith('{{'));
+  return { path, status: status ?? null, openQuestions };
+}
+
+const hasMarkdown = (dir) => {
+  try {
+    return readdirSync(dir, { recursive: true }).some((f) => String(f).endsWith('.md'));
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * { step, why, args, then, attention }. `step` is a skill (spec-design, init, check, dispatch,
+ * review), `wait` (lanes are building) or `done`. `base(config)` resolves the branch lanes merge into.
+ */
+export function nextStep(root, base) {
+  const attention = [];
+  const result = (step, why, extra = {}) => ({
+    step,
+    why,
+    args: '',
+    then: [],
+    attention,
+    ...extra,
+  });
+  const isRepo = git(root, 'rev-parse', '--is-inside-work-tree') === 'true';
+  if (!isRepo)
+    attention.push('This folder is not a git repository yet; run `git init` before init.');
+  const files = isRepo ? (git(root, 'ls-files') ?? '').split('\n').filter(Boolean) : [];
+
+  const { config, error } = loadConfig(root);
+  if (error)
+    return result(
+      'check',
+      `The config is invalid, so nothing but the config can be written: ${error.split('\n')[0]}`,
+    );
+  const brief = readBrief(root, config);
+  if (brief?.openQuestions.length)
+    attention.push(`${brief.openQuestions.length} open question(s) in ${brief.path}.`);
+
+  if (!config) {
+    if (existsSync(join(root, DRAFT_FILE)))
+      return result(
+        'init',
+        'A draft config is waiting for your approval; nothing is enforced until you approve it.',
+      );
+    if (brief && brief.status !== 'ready')
+      return result(
+        'spec-design',
+        `The spec is ${brief.status ? `at "${brief.status}"` : 'started'}; spec-design picks up from there.`,
+      );
+    if (brief)
+      return result('init', 'The spec is ready; init turns it into enforced lanes and layers.', {
+        args: posix.dirname(brief.path),
+      });
+    const code = files.filter(
+      (f) =>
+        !f.startsWith('docs/') &&
+        !f.endsWith('.md') &&
+        !f.split('/').some((p) => p.startsWith('.')),
+    );
+    if (code.length)
+      return result(
+        'init',
+        `This is existing code (${code.length} tracked files) without code-kit; init works the rules out from the code.`,
+      );
+    if (hasMarkdown(join(root, 'docs')))
+      return result(
+        'init',
+        'There are docs but no code-kit yet; init drafts the rules from them.',
+        {
+          args: 'docs/',
+        },
+      );
+    return result(
+      'spec-design',
+      'Nothing here yet; spec-design turns your idea into a specification.',
+    );
+  }
+
+  const { specs, plan } = config.docs ?? {};
+  if (!specs || !plan)
+    return result(
+      'spec-design',
+      'code-kit is on, but there are no specs and plan to build from; spec-design writes them.',
+    );
+  if (brief?.status && !['planned', 'ready'].includes(brief.status))
+    return result(
+      'spec-design',
+      `The spec is at "${brief.status}"; spec-design picks up from there.`,
+    );
+  if (!readStories(root, plan).length)
+    return result(
+      'spec-design',
+      `${plan} has no stories in the \`### ST-n\` form yet; spec-design writes the plan.`,
+    );
+
+  const from = base(config);
+  if (!from)
+    attention.push('The base branch has no commits yet, so story branches are read against HEAD.');
+  const status = buildStatus(root, config, from ?? 'HEAD', files);
+  if (status.problems.length)
+    attention.push(
+      `${status.problems.length} gap(s) between the specs and the plan (see \`code-kit status\`).`,
+    );
+  if (status.drift.length)
+    attention.push(
+      `The plan's status lines are out of date for ${status.drift.map((d) => d.story).join(', ')}.`,
+    );
+
+  const ids = (state) => status.stories.filter((s) => s.state === state).map((s) => s.id);
+  const [review, building, blocked] = ['review', 'in progress', 'blocked'].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) =>
+    Boolean(config.lanes[s.lane]) &&
+    s.requirements.length > 0 &&
+    s.requirements.every((r) => defined.has(r));
+  const readyStories = status.stories.filter((s) => s.state === 'ready');
+  const ready = readyStories.filter(buildable).map((s) => s.id);
+  const unbuildable = readyStories.filter((s) => !buildable(s)).map((s) => s.id);
+  if (unbuildable.length)
+    attention.push(
+      `${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(' ') });
+  if (review.length)
+    return result('review', `${review.join(', ')} finished and wait for review.`, {
+      args: review.join(' '),
+      then,
+    });
+  if (ready.length)
+    return result('dispatch', `${ready.join(', ')} can start: their dependencies are done.`, {
+      args: ready.join(' '),
+    });
+  if (building.length)
+    return result(
+      'wait',
+      `${building.join(', ')} ${building.length === 1 ? 'is' : 'are'} being built; nothing else can start until one finishes. A lane that stopped without finishing is dispatched again.`,
+    );
+  if (unbuildable.length)
+    return result(
+      'spec-design',
+      `${unbuildable.join(', ')} ${unbuildable.length === 1 ? 'is' : 'are'} next, but the plan has gaps to fix first.`,
+    );
+  if (blocked.length)
+    return result(
+      'spec-design',
+      `${blocked.join(', ')} wait on stories that can't finish: the plan has a dependency cycle or a missing story.`,
+    );
+  return result(
+    'done',
+    `All ${status.stories.length} stories are done; spec-design plans the next milestone or feature.`,
+  );
+}

package/hooks/lib/plan.mjs

@@ -0,0 +1,206 @@
+// Requirements and stories, read from the project's docs. Specs (docs.specs) hold requirements as
+// headings `### BOOK-4 Short name` (`(removed)` at the end drops one); the plan (docs.plan) holds
+// stories as `### ST-12 Title` followed by `**Lane:**`, `**Requirements:**`, `**Depends on:**` and
+// `**Status:**` lines. A lane builds a story on the branch `<lane>/st-12`.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const REQUIREMENT = /\b(?!ST-)([A-Z][A-Z0-9]*-\d+)\b/g;
+const STORY_HEADING = /^###\s+(ST-\d+)\b\s*(.*)$/;
+const REQUIREMENT_HEADING = /^###\s+((?!ST-)[A-Z][A-Z0-9]*-\d+)\b\s*(.*)$/;
+export const STATES = ['todo', 'in progress', 'review', 'done'];
+// Test files, by the usual conventions. Tests name the requirement IDs they prove.
+const TEST =
+  /(^|\/)(tests?|__tests__|e2e)\/|\.(test|spec)\.[^/]+$|_test\.(go|py)$|(^|\/)test_[^/]+\.py$/;
+
+const markdownFiles = (root, path) => {
+  const full = join(root, path);
+  if (!existsSync(full)) return [];
+  if (statSync(full).isFile()) return path.endsWith('.md') ? [path] : [];
+  return readdirSync(full, { recursive: true })
+    .map((f) => join(path, String(f)).split('\\').join('/'))
+    .filter((f) => f.endsWith('.md') && statSync(join(root, f)).isFile())
+    .sort();
+};
+
+/** Every requirement in the specs: [{ id, title, file, removed }]. */
+export function readRequirements(root, specsPath) {
+  const found = [];
+  for (const file of markdownFiles(root, specsPath)) {
+    for (const line of readFileSync(join(root, file), 'utf8').split('\n')) {
+      const m = line.match(REQUIREMENT_HEADING);
+      if (m)
+        found.push({ id: m[1], title: m[2].trim(), file, removed: /\(removed\)\s*$/i.test(m[2]) });
+    }
+  }
+  return found;
+}
+
+const field = (lines, name) =>
+  lines
+    .map((l) => l.match(new RegExp(`^\\*\\*${name}:\\*\\*\\s*(.*)$`, 'i')))
+    .find(Boolean)?.[1]
+    .trim() ?? '';
+
+/** Every story in the plan: [{ id, title, lane, requirements, dependsOn, status }]. */
+export function readStories(root, planPath) {
+  const stories = [];
+  for (const file of markdownFiles(root, planPath)) {
+    const lines = readFileSync(join(root, file), 'utf8').split('\n');
+    lines.forEach((line, i) => {
+      const m = line.match(STORY_HEADING);
+      if (!m) return;
+      const end = lines.findIndex((l, j) => j > i && /^#{1,3}\s/.test(l));
+      const body = lines.slice(i + 1, end < 0 ? undefined : end);
+      const status = field(body, 'Status').toLowerCase();
+      stories.push({
+        id: m[1],
+        title: m[2].trim(),
+        file,
+        lane: field(body, 'Lane'),
+        requirements: [...field(body, 'Requirements').matchAll(REQUIREMENT)].map((r) => r[1]),
+        dependsOn: [...field(body, 'Depends on').matchAll(/\bST-\d+\b/g)].map((r) => r[0]),
+        status: STATES.includes(status) ? status : 'todo',
+      });
+    });
+  }
+  return stories;
+}
+
+export const storyBranch = (story) => `${story.lane}/${story.id.toLowerCase()}`;
+
+/** Requirement IDs each tracked test file names: { id: [file, ...] }. */
+export function testedRequirements(root, files, specsPath) {
+  const tested = {};
+  for (const file of files) {
+    if (!TEST.test(file) || file.endsWith('.md') || file.startsWith(`${specsPath}/`)) continue;
+    let body;
+    try {
+      body = readFileSync(join(root, file), 'utf8');
+    } catch {
+      continue; // deleted in the working tree, or not a text file
+    }
+    for (const [, id] of body.matchAll(REQUIREMENT)) (tested[id] ??= new Set()).add(file);
+  }
+  return Object.fromEntries(Object.entries(tested).map(([id, s]) => [id, [...s]]));
+}
+
+const git = (root, ...args) => {
+  try {
+    return execFileSync('git', ['-C', root, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return null;
+  }
+};
+
+/** The ref of a branch, local first, then on origin; null when neither exists. */
+function branchRef(root, branch) {
+  for (const ref of [`refs/heads/${branch}`, `refs/remotes/origin/${branch}`])
+    if (git(root, 'rev-parse', '--verify', '--quiet', ref) !== null) return ref;
+  return null;
+}
+
+/** Worktree path of each checked-out branch: { branch: path }. */
+function worktrees(root) {
+  const out = git(root, 'worktree', 'list', '--porcelain') ?? '';
+  const found = {};
+  let path;
+  for (const line of out.split('\n')) {
+    if (line.startsWith('worktree ')) path = line.slice('worktree '.length);
+    if (line.startsWith('branch refs/heads/'))
+      found[line.slice('branch refs/heads/'.length)] = path;
+  }
+  return found;
+}
+
+/**
+ * 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`.
+ */
+export function storyStates(root, stories, base) {
+  const trees = worktrees(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';
+      else state = story.status === 'review' ? 'done' : 'in progress';
+    }
+    return {
+      ...story,
+      branch,
+      branchExists: Boolean(ref),
+      ahead,
+      worktree: trees[branch] ?? null,
+      state,
+      waitingOn: [],
+    };
+  });
+  const done = new Set(states.filter((s) => s.state === 'done').map((s) => s.id));
+  for (const s of states) {
+    if (s.state !== 'todo') continue;
+    s.waitingOn = s.dependsOn.filter((d) => !done.has(d));
+    s.state = s.waitingOn.length ? 'blocked' : 'ready';
+  }
+  return states;
+}
+
+/** Gaps between specs, plan and tests, as sentences. */
+export function traceProblems(requirements, stories, lanes) {
+  const problems = [];
+  const ids = new Set(requirements.map((r) => r.id));
+  const seen = new Set();
+  for (const r of requirements) {
+    if (seen.has(r.id)) problems.push(`${r.id} is defined more than once (${r.file})`);
+    seen.add(r.id);
+  }
+  const storyIds = new Set();
+  for (const s of stories) {
+    if (storyIds.has(s.id)) problems.push(`${s.id} is in the plan more than once`);
+    storyIds.add(s.id);
+    if (!s.lane) problems.push(`${s.id} has no **Lane:**`);
+    else if (!lanes.includes(s.lane)) problems.push(`${s.id} names an unknown lane "${s.lane}"`);
+    if (!s.requirements.length) problems.push(`${s.id} cites no requirements`);
+    for (const r of s.requirements)
+      if (!ids.has(r)) problems.push(`${s.id} cites ${r}, which no spec defines`);
+    for (const d of s.dependsOn)
+      if (!stories.some((o) => o.id === d))
+        problems.push(`${s.id} depends on ${d}, which isn't in the plan`);
+  }
+  const covered = new Set(stories.flatMap((s) => s.requirements));
+  for (const r of requirements)
+    if (!r.removed && !covered.has(r.id)) problems.push(`${r.id} is in no story (${r.file})`);
+  return problems;
+}
+
+/** The whole picture for `code-kit status` and `code-kit next`: stories, requirements, gaps, drift. */
+export function buildStatus(root, config, base, files) {
+  const { specs, plan } = config.docs;
+  const requirements = readRequirements(root, specs).filter((r) => r.file !== plan);
+  const stories = storyStates(root, readStories(root, plan), base);
+  const tested = testedRequirements(root, files, specs);
+  const problems = traceProblems(requirements, stories, Object.keys(config.lanes));
+  const byRequirement = requirements.map((r) => {
+    const covering = stories.filter((s) => s.requirements.includes(r.id));
+    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)))
+      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)
+    .map((s) => ({ story: s.id, plan: s.status, actual: s.state }));
+  return { stories, requirements: byRequirement, problems, drift };
+}