@warren-dean/code-kit 0.5.0 → 0.7.0

package/hooks/lib/reviews.mjs

@@ -37,3 +37,21 @@ export function sentBack(root) {
   }
   return found;
 }
+
+/** Every send-back recorded, oldest first: [{ at, branch, sha, reason }]. */
+export function sendBacks(root) {
+  let lines = [];
+  try {
+    lines = readFileSync(reviewsFile(root), 'utf8').split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+  return lines.flatMap((line) => {
+    try {
+      const r = JSON.parse(line);
+      return r.verdict === 'sent back' && r.branch ? [r] : [];
+    } catch {
+      return [];
+    }
+  });
+}

package/hooks/lib/rules.mjs

@@ -2,7 +2,8 @@
 //
 // Actors:
 // - a lane agent (its agent_type is a lane's "agent") writes only that lane's paths;
-// - any other subagent (research, planning, review) is read-only;
+// - any other subagent (research, planning, review) is read-only, but for the paths any actor may write
+//   (a card or a decision it records, code-kit's own state);
 // - the main session in a worktree with a .lane file acts as that lane (a person running a lane);
 // - the main session otherwise is the lead, who writes the lead's paths and delegates the rest.
 // Protected paths are recorded in the approval log whenever they are committed; only the lead may
@@ -219,8 +220,9 @@ function ownedPaths(actor, config) {
 
 /** Whether `rel` is the actor's own to write: its paths, or the paths any actor may write. */
 export function owns(actor, rel, config) {
-  if (actor.kind === 'readonly') return false;
+  // The paths any actor may write are a read-only agent's too: a card or a decision it records.
   if (matchesAny(rel, config.anyActor)) return true;
+  if (actor.kind === 'readonly') return false;
   const excluded = actor.kind === 'lane' ? config.lanes[actor.lane]?.exclude : [];
   return matchesAny(rel, ownedPaths(actor, config)) && !matchesAny(rel, excluded);
 }
@@ -408,8 +410,10 @@ export function protectedEntry(rel, config) {
   return config.protected.find((p) => globToRegExp(p.glob).test(rel));
 }
 
+/** Files that may hold secrets. An env file's template (`.env.example`, `.env.local.sample`) names
+ * the variables without their values, so it's committed like any other file. */
 export const SECRETS = (rel) =>
-  /(^|\/)\.env(\.|$)/.test(rel) ||
+  (/(^|\/)\.env(\.|$)/.test(rel) && !/\.(example|sample|template|dist)$/.test(rel)) ||
   /(^|\/)secrets?\//.test(rel) ||
   /\.(pem|p8|p12|keystore|jks)$/.test(rel);
 
@@ -436,8 +440,8 @@ export function writeProblem(actor, rel, root, config) {
     recordRequest(root, actor, guarded.approval, rel, guarded.why);
     return `${rel} is ${guarded.why} and needs a person's approval. Ask the lead (a person) to run\n${approvalHowTo(guarded.approval, actor, root, undefined, config)}`;
   }
-  if (actor.kind === 'readonly') return `${actor.label} is read-only; it may not write ${rel}.`;
   if (matchesAny(rel, config.anyActor)) return null;
+  if (actor.kind === 'readonly') return `${actor.label} is read-only; it may not write ${rel}.`;
   if (!owns(actor, rel, config)) return ownershipProblem(actor, rel, config);
   const specs = actor.kind === 'lane' && config.docs?.specs;
   return (specs && specCheckProblem(rel, root)) || screenProblem(rel, root, config);

package/hooks/lib/shell.mjs

@@ -33,7 +33,7 @@ export function maskQuotes(text) {
       } else if (c === quote) {
         quote = null;
         out += c;
-      } else out += c === '\n' ? '\n' : '_';
+      } else out += '_'; // a newline inside quotes too: it ends no command
     } else if (c === '\\' && i + 1 < text.length) {
       out += '__';
       i++;

package/hooks/lib/timeline.mjs

@@ -0,0 +1,77 @@
+// When each story's work happened (docs/specs/11-panes.md, VIEW-2), from git and the project's own
+// records: when its branch was made, its commits, its merge into the base, its send-backs and the
+// approvals its commits logged. The mod draws these as a bar per lane on a shared time axis.
+import { execFileSync } from 'node:child_process';
+import { APPROVAL_LOG } from './rules.mjs';
+import { sendBacks } from './reviews.mjs';
+
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * For each story with a branch, or done: { id, lane, branch, state, started, lastCommit, merged,
+ * sentBack: [ms], approvals: [{ at, names }] }, times in milliseconds or null.
+ */
+export function storyTimes(root, stories, base) {
+  const git = (...args) => {
+    try {
+      return execFileSync('git', ['-C', root, ...args], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        maxBuffer: 32 * 1024 * 1024,
+      }).trim();
+    } catch {
+      return '';
+    }
+  };
+  const lines = (text) => text.split('\n').filter(Boolean);
+  const merges = lines(git('log', '--merges', '--format=%ct%x09%s', base)).map((l) => {
+    const [t, ...subject] = l.split('\t');
+    return { at: Number(t) * 1000, subject: subject.join('\t') };
+  });
+  const backs = sendBacks(root);
+  const logged = (ref) => new Set(lines(git('show', `${ref}:${APPROVAL_LOG}`)));
+  const onBase = logged(base);
+  return stories
+    .filter((s) => s.branchExists || s.state === 'done')
+    .map((s) => {
+      const b = s.branch;
+      // The reflog's oldest entry is the branch's making, when it's still there.
+      const made = s.branchExists
+        ? lines(git('reflog', 'show', '--format=%ct', `refs/heads/${b}`))
+        : [];
+      const commits = s.branchExists
+        ? lines(git('log', '--format=%ct', `${base}..${b}`)).map((t) => Number(t) * 1000)
+        : [];
+      const named = new RegExp(`(^|[\\s'"])${escape(b)}($|[\\s'"])`);
+      const merged = merges.find((m) => named.test(m.subject))?.at ?? null;
+      const approvals = s.branchExists
+        ? [...logged(b)]
+            .filter((l) => !onBase.has(l))
+            .flatMap((l) => {
+              try {
+                const e = JSON.parse(l);
+                return e.grantedAt || e.at
+                  ? [{ at: Date.parse(e.grantedAt ?? e.at), names: [e.approval].filter(Boolean) }]
+                  : [];
+              } catch {
+                return [];
+              }
+            })
+        : [];
+      return {
+        id: s.id,
+        lane: s.lane,
+        branch: b,
+        state: s.state,
+        started: made.length
+          ? Number(made.at(-1)) * 1000
+          : commits.length
+            ? Math.min(...commits)
+            : null,
+        lastCommit: commits.length ? Math.max(...commits) : null,
+        merged,
+        sentBack: backs.filter((x) => x.branch === b).map((x) => Date.parse(x.at)),
+        approvals,
+      };
+    });
+}

package/hooks/mod/art.mjs

@@ -0,0 +1,200 @@
+// Panes v2's pictures (docs/specs/11-panes.md, VIEW-2 and VIEW-3): a timeline bar per lane on a
+// shared time axis, and a small pixel character per lane agent whose pose shows its state. The
+// terminal draws characters as half-block cells (a Raster, repainted in place with $.ui.blit while
+// the agent works); Desktop draws them, and the timelines, as SVG. Every state has a glyph too.
+
+// --- the characters (VIEW-3) ---------------------------------------------------------------------
+
+/** Each pose, 6 by 6 pixels: H the lane's tint, E eyes, X stalled eyes, L closed eyes, C a crown. */
+const POSES = {
+  working: [
+    ['..HH..', '.HEEH.', '..HH..', '.HHHH.', 'H.HH.H', '.H..H.'],
+    ['..HH..', '.HEEH.', '..HH..', 'HHHHHH', '..HH..', '..HH..'],
+  ],
+  waiting: [['..HH.H', '.HEEHH', '..HH..', '.HHH..', '..HH..', '.H..H.']],
+  quiet: [['......', '..HH..', '.HLLH.', '..HH..', '.HHHH.', '.H..H.']],
+  stalled: [['..HH..', '.HXXH.', '..HH..', '.HHHH.', '..HH..', '.H..H.']],
+  done: [['H.HH.H', 'HHEEHH', '..HH..', '..HH..', '..HH..', '.H..H.']],
+  idle: [['......', '..HH..', '.HLLH.', '..HH..', '.HHHH.', '.H..H.']],
+};
+/** What a pose reads as without its picture, and in words. */
+export const POSE_GLYPH = {
+  working: '⚙',
+  waiting: '?',
+  quiet: '…',
+  stalled: '✗',
+  done: '✓',
+  idle: '·',
+};
+
+/** Each lane's tint, fixed by its place in the config so the person learns them; the lead's is gold. */
+const TINTS = [0x4aa3ff, 0x5cc85c, 0xd070e0, 0x40c8c8, 0xff9a40, 0xff6070, 0xa0a0ff];
+export function tintOf(lane, lanes) {
+  if (lane === 'lead') return 0xd8a840;
+  const i = lanes.filter((l) => l !== 'lead').indexOf(lane);
+  return TINTS[(i < 0 ? 0 : i) % TINTS.length];
+}
+
+const dim = (rgb) =>
+  (((rgb >> 16) & 0xff) >> 1) * 0x10000 + (((rgb >> 8) & 0xff) >> 1) * 0x100 + ((rgb & 0xff) >> 1);
+
+/** The pose's frame as a grid of colours (null for none), the lead crowned. */
+export function sprite(pose, frame, tint, { lead = false } = {}) {
+  const frames = POSES[pose] ?? POSES.idle;
+  const rows = frames[frame % frames.length].map((r) => [...r]);
+  if (lead) rows[0] = [...'C.CC.C'];
+  const body = pose === 'quiet' || pose === 'idle' ? dim(tint) : tint;
+  const colour = { H: body, E: 0x202020, X: 0xff3030, L: 0x707070, C: 0xffcc00 };
+  return rows.map((r) => r.map((c) => colour[c] ?? null));
+}
+
+const DEFAULT = 0x01000000;
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+function base64(bytes) {
+  let out = '';
+  for (let i = 0; i < bytes.length; i += 3) {
+    const [a, b = 0, c = 0] = [bytes[i], bytes[i + 1], bytes[i + 2]];
+    const n = (a << 16) | (b << 8) | c;
+    out += B64[(n >> 18) & 63] + B64[(n >> 12) & 63];
+    out += i + 1 < bytes.length ? B64[(n >> 6) & 63] : '=';
+    out += i + 2 < bytes.length ? B64[n & 63] : '=';
+  }
+  return out;
+}
+
+/**
+ * A sprite as a Raster's cells (VIEW-3): two pixels a cell, the upper as the half block's colour and
+ * the lower as its background. 6 columns by 3 rows.
+ */
+export function rasterCells(grid) {
+  const words = [];
+  for (let y = 0; y < grid.length; y += 2)
+    for (let x = 0; x < grid[y].length; x++) {
+      const top = grid[y][x];
+      const bottom = grid[y + 1]?.[x] ?? null;
+      if (top === null && bottom === null) words.push(0x20, DEFAULT, DEFAULT);
+      else if (top === null) words.push(0x2584, bottom, DEFAULT);
+      else words.push(0x2580, top, bottom ?? DEFAULT);
+    }
+  const bytes = [];
+  for (const w of words)
+    bytes.push(w & 0xff, (w >>> 8) & 0xff, (w >>> 16) & 0xff, (w >>> 24) & 0xff);
+  return base64(bytes);
+}
+
+const hex = (rgb) => `#${rgb.toString(16).padStart(6, '0')}`;
+
+/** A sprite as SVG for Desktop, the working pose's frames alternating (SMIL), 4 px a pixel. */
+export function spriteSvg(pose, tint, { lead = false } = {}) {
+  const frames = (POSES[pose] ?? POSES.idle).map((_, f) => sprite(pose, f, tint, { lead }));
+  const rects = (grid) =>
+    grid
+      .flatMap((row, y) =>
+        row.map((c, x) =>
+          c === null
+            ? ''
+            : `<rect x="${x * 4}" y="${y * 4}" width="4" height="4" fill="${hex(c)}"/>`,
+        ),
+      )
+      .join('');
+  const groups = frames.map((g, f) =>
+    frames.length > 1
+      ? `<g visibility="${f ? 'hidden' : 'visible'}"><animate attributeName="visibility" values="${f ? 'hidden;visible' : 'visible;hidden'}" dur="0.8s" repeatCount="indefinite" calcMode="discrete"/>${rects(g)}</g>`
+      : `<g>${rects(g)}</g>`,
+  );
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" shape-rendering="crispEdges">${groups.join('')}</svg>`;
+}
+
+/**
+ * A lane's pose (VIEW-3): stalled when flagged or quiet past the restart time, waiting while a call
+ * of its is held or its request is open, working while its agent is at work, quiet when it has
+ * gone quiet, done once its branch is finished, idle otherwise.
+ */
+export function poseOf(
+  lane,
+  { live = null, waiting = false, flagged = false, shown = lane.state } = {},
+) {
+  if (flagged || live?.level === 'stalled') return 'stalled';
+  if (waiting) return 'waiting';
+  if (live?.level === 'quiet') return 'quiet';
+  if (lane.active) return 'working';
+  if (['in review', 'queued'].includes(shown)) return 'done';
+  return 'idle';
+}
+
+// --- the timelines (VIEW-2) ----------------------------------------------------------------------
+
+/** Each cell kind's glyph and colour: the glyph alone reads in a terminal without colour. */
+export const BAR = {
+  building: { glyph: '█', color: 'blue' },
+  review: { glyph: '▒', color: 'yellow' },
+  sentBack: { glyph: '↩', color: 'magenta' },
+  approval: { glyph: '◆', color: 'cyan' },
+  merged: { glyph: '✓', color: 'green' },
+  none: { glyph: ' ', color: undefined },
+};
+
+/** Where the shared axis starts: the earliest start among the lanes' stories, at most a day back. */
+export function axisStart(times, now) {
+  const starts = times.map((t) => t.started).filter((t) => t !== null && t !== undefined);
+  return starts.length ? Math.max(Math.min(...starts), now - 24 * 3600000) : now - 3600000;
+}
+
+/**
+ * A story's bar as `width` cells from `start` to `now` (VIEW-2): building from its start, in review
+ * from its last commit once finished, ending at its merge or now; its send-backs, approvals and
+ * merge marked where they fell. [kind], a kind of BAR's.
+ */
+export function barCells(t, { start, now, width }) {
+  const span = Math.max(1, now - start) / width;
+  const finished =
+    ['review', 'in review', 'queued', 'done'].includes(t.state) && t.lastCommit !== null;
+  const end = t.merged ?? now;
+  const cells = [];
+  for (let i = 0; i < width; i++) {
+    const mid = start + (i + 0.5) * span;
+    if (t.started === null || mid < t.started || mid > end + span / 2) cells.push('none');
+    else if (finished && mid >= t.lastCommit) cells.push('review');
+    else cells.push('building');
+  }
+  const mark = (at, kind) => {
+    if (at === null || at === undefined || at < start || at > now) return;
+    cells[Math.min(width - 1, Math.floor((at - start) / span))] = kind;
+  };
+  for (const at of t.sentBack ?? []) mark(at, 'sentBack');
+  for (const a of t.approvals ?? []) mark(a.at, 'approval');
+  mark(t.merged, 'merged');
+  return cells;
+}
+
+/** Runs of the same kind, to draw as one Text each: [{ kind, n }]. */
+export function runs(cells) {
+  const out = [];
+  for (const kind of cells) {
+    if (out.at(-1)?.kind === kind) out.at(-1).n += 1;
+    else out.push({ kind, n: 1 });
+  }
+  return out;
+}
+
+/** The bars as SVG for Desktop: a row per lane, the same kinds and colours. */
+export function timelineSvg(rows, { width = 480, rowHeight = 10 } = {}) {
+  const FILL = {
+    building: '#4aa3ff',
+    review: '#e0c040',
+    sentBack: '#d070e0',
+    approval: '#40c8c8',
+    merged: '#5cc85c',
+  };
+  const cell = width / Math.max(1, rows[0]?.cells.length ?? 1);
+  const rects = rows
+    .flatMap((r, y) =>
+      r.cells.map((k, x) =>
+        k === 'none'
+          ? ''
+          : `<rect x="${(x * cell).toFixed(1)}" y="${y * (rowHeight + 4)}" width="${cell.toFixed(1)}" height="${rowHeight}" fill="${FILL[k]}"/>`,
+      ),
+    )
+    .join('');
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${rows.length * (rowHeight + 4)}" shape-rendering="crispEdges">${rects}</svg>`;
+}

package/hooks/mod/hold.mjs

@@ -0,0 +1,25 @@
+// Hold and ask (spec 06), the pure parts. The hooks stay the only judge: the mod lets a call run,
+// and when the result is a refusal a person's approval would allow, it holds the call, asks, writes the
+// approval and retries the same call (docs/spikes/harness.md, spike B). This reads such a refusal.
+import { refusalCard } from './view.mjs';
+
+/** The kinds of refusal a person's approval would allow (HOLD-1): a new package, a protected file, the kit. */
+const HOLDABLE = new Set(['dependency', 'approval', 'kit']);
+
+/**
+ * From a refused call's result text, what would let it through: { kind, names, lane, what, title }, or
+ * null when no approval a person can give would allow it (another lane's files, force-push, the log…).
+ */
+export function holdable(resultText) {
+  const card = refusalCard(resultText);
+  if (!card || !HOLDABLE.has(card.kind) || !card.request?.names.length) return null;
+  return { kind: card.kind, title: card.title, ...card.request };
+}
+
+/** A tool call's result as text, whichever shape the engine gave it. */
+export function resultText(result) {
+  if (!result) return '';
+  if (typeof result.deny === 'string') return result.deny;
+  if (typeof result.text === 'string') return result.text;
+  return typeof result.result === 'string' ? result.result : '';
+}

package/hooks/mod/loop.mjs

@@ -0,0 +1,68 @@
+// The lead loop (spec 05), the pure parts: what to prompt the lead with for a step `code-kit next`
+// reports, and what a quiet lane agent is due. The mod watches and prompts; the lead acts, with the
+// existing skills, and the hooks judge every call as before.
+
+/** The steps the loop hands the lead; the rest (spec-design, init, check) wait for the person. */
+const LEAD_STEPS = new Set(['dispatch', 'review', 'lead', 'merge']);
+
+/**
+ * The prompt for a step from `code-kit next --json` (LOOP-1), or null when it isn't the lead's to
+ * take. Every ready story is named: the dispatch skill decides how many lanes go (LOOP-2). A prompt
+ * names the skill rather than starting with it: Claude Code refuses a mod's prompt that begins with
+ * `/`, which would run a command as the person.
+ */
+export function leadPrompt(step, { cli = 'code-kit' } = {}) {
+  if (!step || !LEAD_STEPS.has(step.step)) return null;
+  const ids = (step.args ?? '').split(/\s+/).filter(Boolean);
+  // MQ-2: the head of the merge queue, where the lead merges within the delegated rules.
+  if (step.step === 'merge')
+    return ids.length
+      ? `Merge ${ids[0]}, next in the merge queue: run node "${cli}" queue merge --delegated. It verifies the branch against the base as it is now, and sends it back to its lane if it conflicts or fails.`
+      : null;
+  if (step.step === 'dispatch')
+    return ids.length
+      ? `Dispatch ${ids.join(', ')}: run /code-kit:dispatch ${ids.join(' ')}.`
+      : null;
+  // The review skill takes one story, or none for every story in review.
+  if (step.step === 'review')
+    return ids.length === 1
+      ? `Review ${ids[0]}: run /code-kit:review ${ids[0]}.`
+      : `Review ${ids.join(', ')}: run /code-kit:review.`;
+  if (!ids.length) return null;
+  const branches = ids.map((id) => `lead/${id.toLowerCase()}`).join(', ');
+  return `Build ${ids.join(', ')} yourself: ${ids.length === 1 ? "it is the lead's own story" : "they are the lead's own stories"}. Work on ${branches}, then review ${ids.length === 1 ? 'it' : 'them'} like any branch.`;
+}
+
+/** A step's identity: the loop never submits the same step twice while the project stands still. */
+export const stepKey = (step) => `${step.step}:${step.args ?? ''}`;
+
+/** The band's words for a step (LOOP-5): "Dispatch ST-7, ST-9". */
+export function stepLabel(step) {
+  const ids = (step.args ?? '').split(/\s+/).filter(Boolean).join(', ');
+  const verb =
+    { dispatch: 'Dispatch', review: 'Review', lead: 'Build', merge: 'Merge' }[step.step] ??
+    step.step;
+  return ids ? `${verb} ${ids}` : verb;
+}
+
+/**
+ * What a lane agent with no tool call for `quietMs` is due (LOOP-3): 'nudge' at stall.nudgeMinutes,
+ * 'restart' at stall.restartMinutes, 'flag' once its story has been restarted stall.maxRestarts
+ * times, or null. `agent` holds what was done already: { nudged, stopped }.
+ */
+export function stallDue(quietMs, agent, restarts, stall) {
+  const minutes = quietMs / 60000;
+  if (minutes >= stall.restartMinutes && !agent.stopped)
+    return restarts >= stall.maxRestarts ? 'flag' : 'restart';
+  if (minutes >= stall.nudgeMinutes && !agent.nudged) return 'nudge';
+  return null;
+}
+
+/** The lead's prompt to stop a stalled agent and dispatch its story again (LOOP-3). */
+export function restartPrompt({ type, id, story, minutes }) {
+  return `${type} (agent ${id}) on ${story} has made no tool call for ${minutes} minutes. Stop it with TaskStop, then dispatch ${story} again with the same brief on the same branch: /code-kit:dispatch ${story}`;
+}
+
+/** The message a quiet agent gets (LOOP-3). */
+export const nudgeText = (minutes) =>
+  `No tool call for ${minutes} minutes: report where you are, or carry on.`;