@warren-dean/code-kit 0.7.0 → 0.8.1

package/hooks/lib/journal.mjs

@@ -0,0 +1,224 @@
+// The journal (docs/specs/15-decisions-and-journal.md, JOURNAL-1): the build's lineage in plain
+// sentences, oldest first: what the person asked for, the decisions that shaped it, the specification,
+// the rules being switched on, each story handed out, sent back and merged, each approval and who gave
+// it, and each milestone finished. Read from git and the project's own records, so it's the same for
+// every session and survives a restart.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { APPROVAL_LOG } from './rules.mjs';
+import { sendBacks } from './reviews.mjs';
+import { storyTimes } from './timeline.mjs';
+
+const gitIn =
+  (root) =>
+  (...args) => {
+    try {
+      return execFileSync('git', ['-C', root, ...args], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        maxBuffer: 32 * 1024 * 1024,
+      }).trim();
+    } catch {
+      return '';
+    }
+  };
+
+/** When a file was first committed, in ms, or null. */
+const addedAt = (git, file) => {
+  const t = git('log', '--diff-filter=A', '--format=%ct', '--', file)
+    .split('\n')
+    .filter(Boolean)
+    .at(-1);
+  return t ? Number(t) * 1000 : null;
+};
+
+/** The brief's title and its problem, in a sentence or two: what the person asked for. */
+export function briefRequest(text) {
+  const title = text.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? null;
+  const section = (name) => {
+    const m = text.match(
+      new RegExp(`^##\\s+${name}\\s*\\n([\\s\\S]*?)(?=^##\\s|$(?![\\s\\S]))`, 'm'),
+    );
+    return m ? m[1].trim() : '';
+  };
+  const firstParagraph = (s) =>
+    s
+      .split(/\n\s*\n/)[0]
+      .replace(/\s+/g, ' ')
+      .trim();
+  const problem = firstParagraph(section('Problem')) || firstParagraph(section('Outcome'));
+  return { title, problem: problem || null };
+}
+
+/** The brief's decision log: [{ date, decision, why }], from its `## Decision log` table. */
+export function briefDecisions(text) {
+  const m = text.match(/^##\s+Decision log\s*\n([\s\S]*?)(?=^##\s|$(?![\s\S]))/m);
+  if (!m) return [];
+  return m[1]
+    .split('\n')
+    .filter((l) => /^\|/.test(l) && !/^\|\s*-/.test(l) && !/^\|\s*Date\s*\|/i.test(l))
+    .map((l) => l.split('|').map((c) => c.trim()))
+    .map((c) => ({ date: c[1], decision: c[2], why: c[3] ?? '' }))
+    .filter((d) => /^\d{4}-\d{2}-\d{2}$/.test(d.date) && d.decision);
+}
+
+/** Who gave an approval, from the reason its log entry carries: the person, or the lead within limits. */
+export function approverOf(entry) {
+  const reason = String(entry.reason ?? '');
+  if (/approved by the lead within the delegated rules/.test(reason)) return 'lead';
+  if (entry.approval === 'lead') return 'lead';
+  return 'person';
+}
+
+/** The words an approval's name stands for: "dep-pdfjs-dist" → "adding the package pdfjs-dist". */
+export function approvalWords(name) {
+  if (name.startsWith('dep-')) return `adding the package ${name.slice(4)}`;
+  if (name === 'dependency') return 'adding a new package';
+  if (name === 'kit') return "a change to code-kit's own rules or agents";
+  if (name === 'merge') return 'a merge';
+  return `a change to the protected ${name.replace(/-/g, ' ')}`;
+}
+
+/** The person's own words, without the note the hooks add about how it was given. */
+const ownWords = (reason) =>
+  String(reason ?? '')
+    .replace(
+      /\s*\((given in chat, recorded by the lead|approved in the [\w ]+ pane|approved by the lead within the delegated rules[^)]*)\)\s*$/,
+      '',
+    )
+    .trim();
+
+/**
+ * JOURNAL-1: the events, oldest first: [{ at, kind, text, story? }]. Kinds: request, decision, spec,
+ * setup, dispatch, sentBack, merge, approval, milestone. `status` is buildStatus's; `base` the branch
+ * stories merge into; `docs` the config's docs (brief beside the specs).
+ */
+export function journal(root, status, base, docs = {}) {
+  const git = gitIn(root);
+  const events = [];
+  const at = (iso) => (iso ? Date.parse(`${iso}T12:00:00Z`) : null);
+  // What the person asked for, and the decisions the brief records.
+  const briefPath = ['docs/brief.md', docs.specs ? join(docs.specs, '..', 'brief.md') : null]
+    .filter(Boolean)
+    .find((p) => existsSync(join(root, p)));
+  if (briefPath) {
+    const text = readFileSync(join(root, briefPath), 'utf8');
+    const { title, problem } = briefRequest(text);
+    const when = addedAt(git, briefPath);
+    if (title || problem)
+      events.push({
+        at: when,
+        kind: 'request',
+        text: `You asked for ${title ? `“${title}”` : 'a build'}${problem ? `: ${problem}` : ''}`,
+      });
+    // The decisions were made while the brief was written: they follow the request, in the log's order.
+    briefDecisions(text).forEach((d, n) =>
+      events.push({
+        at: (when ?? at(d.date)) + n + 1,
+        kind: 'decision',
+        text: `Decided: ${d.decision}${d.why ? `, because ${d.why.replace(/\.$/, '').replace(/^./, (c) => c.toLowerCase())}` : ''}.`,
+      }),
+    );
+  }
+  // The specification and the plan.
+  const reqs = status.requirements.filter((r) => !r.removed).length;
+  const milestones = [...new Set(status.stories.map((s) => s.milestone).filter(Boolean))];
+  if (docs.plan && status.stories.length)
+    events.push({
+      at: addedAt(git, docs.plan),
+      kind: 'spec',
+      text: `The specification was written: ${reqs} requirement${reqs === 1 ? '' : 's'}, split into ${status.stories.length} stor${status.stories.length === 1 ? 'y' : 'ies'}${milestones.length ? ` across ${milestones.length} milestone${milestones.length === 1 ? '' : 's'}` : ''}.`,
+    });
+  const switchedOn = addedAt(git, '.claude/code-kit.json');
+  if (switchedOn)
+    events.push({
+      at: switchedOn,
+      kind: 'setup',
+      text: "code-kit's rules were switched on, as you approved them.",
+    });
+  // Each story: handed out, sent back, merged.
+  const times = storyTimes(root, status.stories, base);
+  const byId = new Map(status.stories.map((s) => [s.id, s]));
+  const backs = sendBacks(root);
+  for (const t of times) {
+    const s = byId.get(t.id);
+    const name = `${t.id} ${s?.title ?? ''}`.trim();
+    const reqText = s?.requirements?.length ? ` (${s.requirements.join(', ')})` : '';
+    if (t.started)
+      events.push({
+        at: t.started,
+        kind: 'dispatch',
+        story: t.id,
+        text:
+          t.lane === 'lead'
+            ? `The lead started ${name}${reqText} itself.`
+            : `${name}${reqText} was handed to the ${t.lane} lane.`,
+      });
+    for (const b of backs.filter((x) => x.branch === t.branch))
+      events.push({
+        at: Date.parse(b.at),
+        kind: 'sentBack',
+        story: t.id,
+        text:
+          t.lane === 'lead'
+            ? `${t.id} needed more work from the lead${b.reason ? `: ${b.reason}` : '.'}`
+            : `The lead sent ${t.id} back to the ${t.lane} lane${b.reason ? `: ${b.reason}` : '.'}`,
+      });
+    if (t.merged)
+      events.push({
+        at: t.merged,
+        kind: 'merge',
+        story: t.id,
+        text: `${name} was merged into ${base}.`,
+      });
+  }
+  // Approvals on the base, once each (one approval can log several files), and who gave them.
+  const seen = new Set();
+  for (const line of git('show', `${base}:${APPROVAL_LOG}`).split('\n').filter(Boolean)) {
+    let e;
+    try {
+      e = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!e.approval || e.approval === 'lead') continue;
+    const key = `${e.approval}|${e.grantedAt ?? e.at}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const who = approverOf(e);
+    const words = ownWords(e.reason);
+    events.push({
+      at: Date.parse(e.grantedAt ?? e.at),
+      kind: 'approval',
+      who,
+      text:
+        who === 'lead'
+          ? `The lead approved ${approvalWords(e.approval)}, within the limits you set${words ? `: ${words}` : '.'}`
+          : `You approved ${approvalWords(e.approval)}${words ? `: “${words}”` : '.'}`,
+    });
+  }
+  // Milestones finished: when the last of their stories merged.
+  for (const m of milestones) {
+    const mine = status.stories.filter((s) => s.milestone === m);
+    if (!mine.every((s) => s.state === 'done')) continue;
+    const last = Math.max(...mine.map((s) => times.find((t) => t.id === s.id)?.merged ?? 0));
+    if (last)
+      events.push({
+        at: last + 1,
+        kind: 'milestone',
+        text: `${m} was finished: all ${mine.length} of its stories merged.`,
+      });
+  }
+  // The request, its decisions, the spec and the switch-on come first, whatever the commits' times: work
+  // can start on a branch before the brief that asked for it is committed.
+  const ORDER = ['request', 'decision', 'spec', 'setup'];
+  const opening = events.filter((e) => ORDER.includes(e.kind));
+  const rest = events.filter((e) => !ORDER.includes(e.kind) && e.at);
+  const firstWork = rest.length ? Math.min(...rest.map((e) => e.at)) : Infinity;
+  const opened = opening
+    .filter((e) => e.at)
+    .sort((a, b) => ORDER.indexOf(a.kind) - ORDER.indexOf(b.kind) || a.at - b.at)
+    .map((e, n, all) => ({ ...e, at: Math.min(e.at, firstWork - (all.length - n)) }));
+  return [...opened, ...rest.sort((a, b) => a.at - b.at)];
+}

package/hooks/lib/loop-state.mjs

@@ -0,0 +1,26 @@
+// Whether the person has paused the lead loop (spec 05, LOOP-6), kept beside the merge queue so other
+// tools sharing the project can hold their own background work while it's paused. The mod records it
+// through the CLI; a session that starts begins unpaused.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { projectWorktrees } from './rules.mjs';
+
+export const LOOP_FILE = '.claude/state/loop.json';
+
+const loopFile = (root) => join(projectWorktrees(root)[0] ?? root, LOOP_FILE);
+
+/** { paused, at }: not paused when nothing was recorded. */
+export function readLoop(root) {
+  try {
+    const state = JSON.parse(readFileSync(loopFile(root), 'utf8'));
+    return { paused: state?.paused === true, at: state?.at ?? null };
+  } catch {
+    return { paused: false, at: null };
+  }
+}
+
+export function writeLoop(root, paused, now = Date.now()) {
+  const file = loopFile(root);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify({ paused, at: new Date(now).toISOString() })}\n`);
+}

package/hooks/lib/next.mjs

@@ -180,11 +180,15 @@ export function nextStep(root, base) {
   // the person does, and always the first merge, which brings code-kit's rules onto the base.
   const delegation = queued.length ? mergeDelegation(root, config) : { delegated: false };
   const leadMerges = delegation.delegated && config.harness.autonomy === 'autonomous';
+  // SETUP-2: a base with no rules committed (a project set up before setup committed them there): the
+  // lead puts the approved rules onto it, and the queue merges under them from then on.
   if (queued.length && delegation.first)
-    attention.push(
-      `${queued[0]} passed review and is next to merge. ${delegation.into} has no code-kit config committed yet, so this first merge, which brings the rules onto it, is the person's (code-kit queue merge --person, or Merge in the code-kit band); after it, the lead merges.`,
+    return result(
+      'rules',
+      `${queued[0]} passed review and is next to merge, but ${delegation.into} has no code-kit rules committed yet. Put the rules the person approved onto it (code-kit queue rules); then the queue merges under them.`,
+      { args: delegation.into },
     );
-  else if (queued.length && !leadMerges)
+  if (queued.length && !leadMerges)
     attention.push(
       `${queued.join(', ')} passed review and ${queued.length === 1 ? 'waits' : 'wait'} for the person to merge (code-kit queue merge --person, or Merge in the code-kit band).`,
     );
@@ -227,6 +231,12 @@ export function nextStep(root, base) {
       '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.`,
     );
+  // Stories waiting on branches in the merge queue wait for the merge, not on a broken plan.
+  if (queued.length)
+    return result(
+      'wait',
+      `${queued.join(', ')} passed review and ${queued.length === 1 ? 'waits' : 'wait'} to be merged; the stories that depend on ${queued.length === 1 ? 'it' : 'them'} start after.`,
+    );
   if (unbuildable.length)
     return result(
       'spec-design',

package/hooks/lib/plan.mjs

@@ -47,12 +47,18 @@ const field = (lines, name) =>
     .find(Boolean)?.[1]
     .trim() ?? '';
 
-/** Every story in the plan: [{ id, title, lane, requirements, dependsOn, status }]. */
+/**
+ * Every story in the plan: [{ id, title, lane, requirements, dependsOn, status, milestone }]. A story's
+ * milestone is the `## ` heading above it ("Milestone 5: Your own key"), or null.
+ */
 export function readStories(root, planPath) {
   const stories = [];
   for (const file of markdownFiles(root, planPath)) {
     const lines = readFileSync(join(root, file), 'utf8').split('\n');
+    let milestone = null;
     lines.forEach((line, i) => {
+      const heading = line.match(/^##\s+(.+?)\s*$/);
+      if (heading) milestone = heading[1];
       const m = line.match(STORY_HEADING);
       if (!m) return;
       const end = lines.findIndex((l, j) => j > i && /^#{1,3}\s/.test(l));
@@ -67,6 +73,7 @@ export function readStories(root, planPath) {
         noRequirements: /^none\b/i.test(field(body, 'Requirements')),
         dependsOn: [...field(body, 'Depends on').matchAll(/\bST-\d+\b/g)].map((r) => r[0]),
         status: STATES.includes(status) ? status : 'todo',
+        milestone,
       });
     });
   }

package/hooks/lib/storymap.mjs

@@ -0,0 +1,155 @@
+// A story's code as the pane draws it (docs/specs/14-mission-and-maps.md): the files it changed, by the
+// layer each sits in, with the imports between them (MAP-1); and each requirement's trail to its
+// stories, their files and the tests that name it (TRAIL-1). Read from git, the config and the plan.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { matchesAny } from './glob.mjs';
+import { CODE, importsOf, layerOf, targetOf } from './layers.mjs';
+
+const git = (root, ...args) => {
+  try {
+    return execFileSync('git', ['-C', root, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch {
+    return '';
+  }
+};
+
+/** Files that are the build's own code: not the plan, the specs, or the tools' state. */
+const KIT = /^(\.claude|\.ctx|\.github)\//;
+const isCode = (rel) => CODE.test(rel) && !KIT.test(rel);
+
+/**
+ * The code files a story changed: those in commits whose message names it (on any branch, so a merged
+ * story still has its files) and, while its branch is open, its diff against the base. Only files that
+ * still exist, in path order.
+ */
+export function storyFiles(root, story, from) {
+  const found = new Set();
+  const id = story.id;
+  const log = git(
+    root,
+    'log',
+    '--all',
+    '--no-merges',
+    '-E',
+    // POSIX ERE has no \b: "ST-1" mustn't match "ST-12".
+    `--grep=(^|[^A-Za-z0-9-])${id}([^0-9]|$)`,
+    '--format=',
+    '--name-only',
+  );
+  for (const f of log.split('\n')) if (f) found.add(f);
+  if (story.branchExists && story.branch)
+    for (const f of git(root, 'diff', '--name-only', `${from}...${story.branch}`).split('\n'))
+      if (f) found.add(f);
+  return [...found].filter((f) => isCode(f) && existsSync(join(root, f))).sort();
+}
+
+const EXTENSIONS = [
+  '',
+  '.ts',
+  '.tsx',
+  '.mts',
+  '.js',
+  '.jsx',
+  '.mjs',
+  '/index.ts',
+  '/index.tsx',
+  '/index.js',
+];
+
+/** The file in `files` an import specifier in `rel` points at, or null. */
+function resolveIn(spec, rel, aliases, files) {
+  const target = targetOf(spec, rel, aliases);
+  if (!target) return null;
+  // `./x.js` in TypeScript source names `./x.ts`.
+  const bare = target.replace(/\.(js|mjs|cjs)$/, '');
+  for (const ext of EXTENSIONS) {
+    for (const candidate of [`${target}${ext}`, `${bare}${ext}`])
+      if (files.has(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** The lane that owns `rel`, or `lead`, or null. */
+export function laneOfFile(rel, config) {
+  const lane = Object.keys(config.lanes).find((name) => {
+    const { paths, exclude = [] } = config.lanes[name];
+    return matchesAny(rel, paths) && !matchesAny(rel, exclude);
+  });
+  if (lane) return lane;
+  return matchesAny(
+    rel,
+    config.lead.paths.filter((p) => p !== '*'),
+  )
+    ? 'lead'
+    : null;
+}
+
+const TEST = /(^|\/)(tests?|e2e|__tests__)\/|\.(test|spec)\.[cm]?[jt]sx?$/;
+
+/**
+ * MAP-1: a story's code: { story, layers, files: [{ path, layer, lane, imports }] }. `layers` are the
+ * config's layers in their order, then `tests` and `other` where any file falls there; each file's
+ * imports are the story's other files it imports.
+ */
+export function storyMap(root, story, config, from) {
+  const paths = storyFiles(root, story, from);
+  const set = new Set(paths);
+  const aliases = config.importAliases ?? {};
+  const files = paths.map((rel) => {
+    let source = '';
+    try {
+      source = readFileSync(join(root, rel), 'utf8');
+    } catch {
+      // unreadable: no imports
+    }
+    const imports = [
+      ...new Set(
+        importsOf(source)
+          .map((spec) => resolveIn(spec, rel, aliases, set))
+          .filter((t) => t && t !== rel),
+      ),
+    ];
+    const layer = TEST.test(rel) ? 'tests' : (layerOf(rel, config.layers)?.name ?? 'other');
+    return { path: rel, layer, lane: laneOfFile(rel, config), imports };
+  });
+  const used = new Set(files.map((f) => f.layer));
+  const layers = [...config.layers.map((l) => l.name), 'tests', 'other'].filter((l) => used.has(l));
+  return {
+    story: { id: story.id, title: story.title, lane: story.lane, state: story.state },
+    layers,
+    files,
+  };
+}
+
+/**
+ * TRAIL-1: each requirement's trail: { id, title, spec, state, stories: [{ id, state, lane }],
+ * files, tests }. Files are the code its stories changed, tests aside; tests are the files that name it.
+ */
+export function trail(root, status, from) {
+  const byStory = new Map();
+  const filesOf = (s) => {
+    if (!byStory.has(s.id)) byStory.set(s.id, storyFiles(root, s, from));
+    return byStory.get(s.id);
+  };
+  return status.requirements
+    .filter((r) => !r.removed)
+    .map((r) => {
+      const stories = status.stories.filter((s) => s.requirements.includes(r.id));
+      const files = [...new Set(stories.flatMap((s) => filesOf(s)).filter((f) => !TEST.test(f)))];
+      return {
+        id: r.id,
+        title: r.title,
+        spec: r.file ? posix.basename(r.file) : null,
+        state: r.state,
+        stories: stories.map((s) => ({ id: s.id, state: s.state, lane: s.lane })),
+        files,
+        tests: [...(r.tests ?? [])],
+      };
+    });
+}