@warren-dean/code-kit 0.3.15 → 0.5.0

package/hooks/mod/view.mjs

@@ -0,0 +1,427 @@
+// What the code-kit mod shows, as pure functions of the CLI's JSON: the mod's hooks run the CLI and
+// pass its output here, and pass the elements `$.ui.resolve` gives them. Nothing here touches the mods
+// API, files or processes, so it is tested with node as well as with `claude plugin test`.
+
+export const PANE_ID = 'code-kit-lanes';
+export const NOT_CODE_KIT = "This project doesn't use code-kit.";
+const LEAD = 'lead';
+
+/** A CLI run's stdout as JSON, or null when it printed none. */
+export function parseJson(stdout) {
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+}
+
+/** The agent statuses that mean an agent is at work in the session now. */
+const AT_WORK = new Set(['pending', 'running', 'waiting']);
+
+/** The subagent types at work, from `$.agent.list()`. */
+export function agentsAtWork(agents) {
+  return new Set((agents ?? []).filter((a) => AT_WORK.has(a.status)).map((a) => a.type));
+}
+
+/** The stories `code-kit next --json` says can start now: dispatched to lanes, or the lead's own. */
+export function readyFrom(next) {
+  if (!next) return [];
+  const steps = [next, ...(next.then ?? [])].filter((s) => ['dispatch', 'lead'].includes(s.step));
+  return [...new Set(steps.flatMap((s) => (s.args ?? '').split(/\s+/).filter(Boolean)))];
+}
+
+/**
+ * One lane's row (PANE-2): the story it's on, its branch and its state.
+ *   building   a branch for the story and, if it has commits, the lane's agent still at work on it;
+ *   in review  commits on the branch (status's `review`) and the agent no longer at work;
+ *   sent back  a review sent the branch back, and the lane hasn't committed its fix yet;
+ *   blocked    the lane's next story waits on another;
+ *   idle       none of these.
+ * `status` can't tell a finished branch from one still being built, so the agent at work decides.
+ */
+function laneRow(name, agent, stories, atWork) {
+  const own = stories.filter((s) => s.lane === name);
+  const active = Boolean(agent && atWork.has(agent));
+  const story = own.find((s) => ['in progress', 'review', 'sent back'].includes(s.state));
+  if (story?.state === 'sent back')
+    return { name, agent, active, story, branch: story.branch, state: 'sent back' };
+  if (story) {
+    const state = story.state === 'review' && !active ? 'in review' : 'building';
+    return { name, agent, active, story, branch: story.branch, state };
+  }
+  const waiting = own.find((s) => ['blocked', 'ready', 'todo'].includes(s.state));
+  if (waiting?.state === 'blocked')
+    return { name, agent, active, story: waiting, branch: null, state: 'blocked' };
+  return { name, agent, active, story: null, branch: null, state: 'idle' };
+}
+
+/**
+ * Where the project stands, from `code-kit check --json` and, when the config is valid, `status
+ * --json` and `next --json` (each null when the config names no plan, or the run failed), and the
+ * subagent types at work:
+ *   { kind: 'none' }                             no .claude/code-kit.json
+ *   { kind: 'invalid', problems }                a config that doesn't validate
+ *   { kind: 'ok', lanes, ready, planGaps }       a row per lane, what's ready, the plan's gaps (or null)
+ */
+export function projectState(check, status, next = null, atWork = new Set()) {
+  if (!check || check.exists === false) return { kind: 'none' };
+  if (!check.valid) return { kind: 'invalid', problems: check.problems ?? [] };
+  const stories = status?.stories ?? [];
+  const lanes = [
+    laneRow(LEAD, null, stories, atWork),
+    ...Object.entries(check.lanes ?? {}).map(([name, l]) =>
+      laneRow(name, l.agent, stories, atWork),
+    ),
+  ];
+  const ready = readyFrom(next).map((id) => {
+    const story = stories.find((s) => s.id === id);
+    return { id, title: story?.title ?? '', lane: story?.lane ?? null };
+  });
+  return { kind: 'ok', lanes, ready, planGaps: status ? (status.problems ?? []).length : null };
+}
+
+const STATE_COLOR = {
+  building: 'blue',
+  'in review': 'yellow',
+  'sent back': 'magenta',
+  blocked: 'red',
+  idle: undefined,
+};
+
+/** The Lanes pane's body, drawn with the elements `$.ui.resolve(e)` returned. */
+export function lanesPane(state, { Box, Text }) {
+  const text = (value, style = {}) => Text({ ...style, children: [value] });
+  if (!state || state.kind === 'none') return text(NOT_CODE_KIT, { dimColor: true });
+  if (state.kind === 'invalid')
+    return text('The config is invalid: run code-kit check.', { color: 'red' });
+  const width = Math.max(...state.lanes.map((l) => l.name.length));
+  const rows = state.lanes.map((l) =>
+    Box({
+      key: `lane-${l.name}`,
+      flexDirection: 'column',
+      children: [
+        Box({
+          flexDirection: 'row',
+          columnGap: 2,
+          children: [
+            text(l.active ? '●' : ' ', { color: 'green' }),
+            text(l.name.padEnd(width), { bold: true }),
+            text(l.state.padEnd(9), STATE_COLOR[l.state] ? { color: STATE_COLOR[l.state] } : {}),
+            text(l.agent ?? 'the main session', { dimColor: true }),
+          ],
+        }),
+        ...(l.story
+          ? [
+              text(
+                `    ${l.story.id} ${l.story.title}${l.branch ? ` · ${l.branch}` : ''}${
+                  l.state === 'blocked' ? ` · waits on ${l.story.waitingOn.join(', ')}` : ''
+                }`,
+                { dimColor: true, wrap: 'truncate-end' },
+              ),
+            ]
+          : []),
+      ],
+    }),
+  );
+  const notes = [];
+  if (state.planGaps)
+    notes.push(
+      text(`The plan has ${state.planGaps} gap(s): run code-kit status.`, { color: 'yellow' }),
+    );
+  const ready = state.ready.length
+    ? [
+        text('Ready', { bold: true }),
+        ...state.ready.map((r) =>
+          Box({
+            key: `ready-${r.id}`,
+            flexDirection: 'row',
+            columnGap: 2,
+            children: [
+              text(r.id),
+              text(r.title, { wrap: 'truncate-end' }),
+              text(r.lane === LEAD ? "the lead's own" : (r.lane ?? ''), { dimColor: true }),
+            ],
+          }),
+        ),
+      ]
+    : [text('Nothing is ready to start.', { dimColor: true })];
+  return Box({
+    flexDirection: 'column',
+    rowGap: 1,
+    children: [
+      ...notes,
+      Box({ flexDirection: 'column', children: rows }),
+      Box({ flexDirection: 'column', children: ready }),
+    ],
+  });
+}
+
+// --- the band, and the person's acts -----------------------------------------------------------
+
+export const APPROVE_ID = 'code-kit-approve';
+export const RESULT_ID = 'code-kit-result';
+
+/** An approval name as a person reads it: a dependency approval by its package. */
+export function approvalLabel(name) {
+  return name.startsWith('dep-') ? name.slice(4).replaceAll('+', '/') : name;
+}
+
+/** A command as a person reads it: the part before its pipes, redirects and chained commands. */
+export function commandItself(command) {
+  return String(command)
+    .split(/\s+(?:\d?>>?&?\d*|\|\|?|&&|;)(?:\s|$)/)[0]
+    .trim();
+}
+
+/** The reason an Approve… confirmation starts with (ACT-1). */
+export function prefilledReason(request) {
+  return `Approve ${request.names.map(approvalLabel).join(', ')} for ${
+    request.lane ? `the ${request.lane} lane` : 'any agent'
+  }: ${commandItself(request.what)}`;
+}
+
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+
+/**
+ * The band's lines (BAND-2): one per kind of thing waiting, each with its actions, and none when
+ * nothing waits. `reviewing` holds the stories the person has asked the lead to review (ACT-3);
+ * `notice` is why the person's last act failed, until they dismiss it.
+ */
+export function bandLines({ state, requests, stops, reviewing = new Set(), notice = null }) {
+  const lines = [];
+  if (notice)
+    lines.push({ kind: 'notice', text: notice, actions: [{ id: 'dismiss', label: 'Dismiss' }] });
+  if (!state || state.kind !== 'ok') return lines;
+  const open = requests?.open ?? [];
+  if (open.length)
+    lines.push({
+      kind: 'approvals',
+      text: `${plural(open.length, 'approval', 'approvals')} waiting`,
+      request: open[0],
+      actions: [{ id: 'approve', label: 'Approve…' }],
+    });
+  const inReview = state.lanes.filter((l) => l.state === 'in review').map((l) => l.story);
+  if (inReview.length) {
+    const [story] = inReview;
+    const ids = inReview.map((s) => s.id).join(', ');
+    lines.push(
+      reviewing.has(story.id)
+        ? { kind: 'review', text: `${story.id} being reviewed`, story, actions: [] }
+        : {
+            kind: 'review',
+            text: `${ids} ready for review`,
+            story,
+            actions: [
+              { id: 'review', label: 'Review' },
+              { id: 'merge', label: 'Merge' },
+            ],
+          },
+    );
+  }
+  if (stops?.length)
+    lines.push({
+      kind: 'finish',
+      text: `Finish check failing: ${stops[0].title}${stops.length > 1 ? ` (and ${stops.length - 1} more)` : ''}`,
+      actions: [{ id: 'lanes', label: 'Lanes' }],
+    });
+  // BAND-4: a digit for every action, in the order they're drawn.
+  let digit = 0;
+  for (const line of lines)
+    for (const action of line.actions) action.hotkey = digit < 9 ? String(++digit) : undefined;
+  return lines;
+}
+
+/** The band, drawn with the elements `$.ui.resolve(e)` returned; `onAction(id, line)` acts. */
+export function band(lines, { Box, Text, Button }, onAction) {
+  const COLOR = { notice: 'red', approvals: 'yellow', review: 'blue', finish: 'red' };
+  return Box({
+    flexDirection: 'column',
+    children: lines.map((line) =>
+      Box({
+        key: `band-${line.kind}`,
+        flexDirection: 'row',
+        columnGap: 2,
+        children: [
+          Text({ color: COLOR[line.kind], children: ['code-kit'] }),
+          Text({ children: [line.text] }),
+          ...line.actions.map((a) =>
+            Button({
+              key: `band-${a.id}`,
+              label: a.hotkey ? `${a.hotkey} ${a.label}` : a.label,
+              hotkey: a.hotkey,
+              onPress: () => onAction(a.id, line),
+            }),
+          ),
+        ],
+      }),
+    ),
+  });
+}
+
+/** The Approve… confirmation (ACT-1): what it grants, to whom, for how long, and the reason. */
+export function approvePane(
+  approving,
+  { Box, Text, Input, Button },
+  { onInput, onSubmit, onCancel },
+) {
+  const { request, reason, error } = approving;
+  return Box({
+    flexDirection: 'column',
+    rowGap: 1,
+    children: [
+      Text({ bold: true, children: [`Approve ${request.names.join(', ')}`] }),
+      Text({
+        children: [
+          `For ${request.lane ? `the ${request.lane} lane` : 'any agent'}, ${request.names.every((n) => n.startsWith('dep-')) ? 'until the install is committed (at most 7 days)' : 'for 60 minutes'}. Asked for: ${request.what}`,
+        ],
+      }),
+      Input({
+        key: 'approve-reason',
+        label: 'Reason',
+        value: reason,
+        submitLabel: 'Approve',
+        autoFocus: true,
+        onInput,
+        onSubmit,
+      }),
+      ...(error ? [Text({ color: 'red', children: [error] })] : []),
+      Box({
+        flexDirection: 'row',
+        columnGap: 2,
+        children: [
+          Button({ key: 'approve-confirm', label: 'Approve', onPress: () => onSubmit(reason) }),
+          Button({ key: 'approve-cancel', label: 'Cancel', onPress: onCancel }),
+        ],
+      }),
+    ],
+  });
+}
+
+/** What a merge (or another act run through the CLI) reported. */
+export function resultPane(result, { Box, Text }) {
+  if (!result) return Text({ dimColor: true, children: ['Nothing to show.'] });
+  return Box({
+    flexDirection: 'column',
+    rowGap: 1,
+    children: [
+      Text({ bold: true, color: result.ok ? 'green' : 'red', children: [result.title] }),
+      Text({ children: [result.text.slice(-9000) || '(no output)'] }),
+    ],
+  });
+}
+
+// --- refusal cards and the commands ------------------------------------------------------------
+
+const APPROVAL_LINE =
+  /^\s*! echo "<what you are approving>" > .*?\.claude\/approvals\/(?:([^/\s]+)\/)?([^/\s]+)\s*$/gm;
+
+/**
+ * A code-kit refusal read back from the text its hooks print (CARD-1): what was refused, the rule and
+ * why, what to do, and the approval that would allow it, if any. Null for text it doesn't recognise,
+ * which Claude Code then draws as it would.
+ */
+export function refusalCard(raw) {
+  const at = typeof raw === 'string' ? raw.indexOf('Blocked: ') : -1;
+  if (at < 0) return null;
+  const text = raw.slice(at + 'Blocked: '.length).trim();
+  const [first, ...rest] = text.split('\n');
+  const approvals = [...text.matchAll(APPROVAL_LINE)];
+  const command = text.match(/^Command: (.+)$/m)?.[1] ?? null;
+  const request = (what) =>
+    approvals.length
+      ? { names: approvals.map((m) => m[2]), lane: approvals[0][1] ?? null, what }
+      : null;
+  let m = first.match(/^The (.+?) may not write (\S+?)(?: \(owned by the (.+)\))?\.$/);
+  if (m)
+    return {
+      kind: 'write',
+      title: `Write refused: ${m[2]}`,
+      why: m[3] ? `It's owned by the ${m[3]}, not the ${m[1]}.` : `Nobody may write it.`,
+      todo: rest.find((l) => l.trim()) ?? '',
+      request: null,
+      raw: text,
+    };
+  m = first.match(/^(\S+) is (.+) and needs a person's approval\./);
+  if (m)
+    return {
+      kind: 'approval',
+      title: `Approval needed: ${m[1]}`,
+      why: `It's ${m[2]}.`,
+      todo: 'A person approves it, here or with the `!` command, for 60 minutes.',
+      request: request(`write ${m[1]}`),
+      raw: text,
+    };
+  m = first.match(/^a new dependency \((.+?)\) needs a person's approval\./);
+  if (m)
+    return {
+      kind: 'dependency',
+      title: `Install refused: ${m[1]}`,
+      why: "A new dependency needs a person's approval.",
+      todo: 'A person approves it, here or with the `!` command, until the install is committed (at most 7 days).',
+      request: request(command ?? `install ${m[1]}`),
+      raw: text,
+    };
+  if (command)
+    return {
+      kind: 'command',
+      title: 'Command refused',
+      why: first,
+      todo: rest.filter((l) => l.trim() && !l.startsWith('Command: ')).join(' '),
+      command,
+      request: request(command),
+      raw: text,
+    };
+  return null;
+}
+
+/** A refusal card (CARD-1), with Approve… where an approval would allow it and the raw text a press away. */
+export function refusalView(card, expanded, { Box, Text, Button }, { onApprove, onToggle }) {
+  return Box({
+    flexDirection: 'column',
+    borderStyle: 'round',
+    paddingX: 1,
+    children: [
+      Text({ bold: true, color: 'red', children: [card.title] }),
+      Text({ children: [card.why] }),
+      ...(card.command ? [Text({ dimColor: true, children: [card.command] })] : []),
+      ...(card.todo ? [Text({ dimColor: true, children: [card.todo] })] : []),
+      Box({
+        flexDirection: 'row',
+        columnGap: 2,
+        children: [
+          ...(card.request
+            ? [Button({ key: 'card-approve', label: 'Approve…', onPress: onApprove })]
+            : []),
+          Button({
+            key: 'card-raw',
+            label: expanded ? 'Hide the text' : 'Show the text',
+            plain: true,
+            onPress: onToggle,
+          }),
+        ],
+      }),
+      ...(expanded ? [Text({ dimColor: true, children: [card.raw] })] : []),
+    ],
+  });
+}
+
+/** `/approvals` (CARD-2): the open requests and the approvals in force, from `requests --json`. */
+export function approvalsText(requests) {
+  const open = requests?.open ?? [];
+  const inForce = requests?.inForce ?? [];
+  const lines = [
+    open.length ? `${plural(open.length, 'request', 'requests')} waiting:` : 'No requests waiting.',
+    ...open.map(
+      (r) =>
+        `  ${r.names.map(approvalLabel).join(', ')} for ${r.lane ? `the ${r.lane} lane` : 'any agent'}: ${r.what}`,
+    ),
+    inForce.length
+      ? `${plural(inForce.length, 'approval', 'approvals')} in force:`
+      : 'No approvals in force.',
+    ...inForce.map(
+      (a) =>
+        `  ${approvalLabel(a.name)} for ${a.lane ? `the ${a.lane} lane` : 'any agent'}, ${a.minutesLeft} min left: ${a.reason}`,
+    ),
+  ];
+  return lines.join('\n');
+}

package/hooks/stop-check.mjs

@@ -39,7 +39,18 @@ const blockCounted = (message) => {
   const count = last.message === message ? last.count + 1 : 1;
   if (count > MAX_REPEATS) passed();
   mkdirSync(join(memory, '..'), { recursive: true });
-  writeFileSync(memory, JSON.stringify({ message, count }));
+  // Also what `code-kit stops` shows the person: whose finish was refused, when, and why.
+  writeFileSync(
+    memory,
+    JSON.stringify({
+      message,
+      count,
+      session: input.session_id ?? null,
+      agent: input.agent_id ?? null,
+      agentType: input.agent_type ?? null,
+      at: new Date().toISOString(),
+    }),
+  );
   const final =
     count === MAX_REPEATS
       ? `\n\n(code-kit has reported this ${count} times without progress; it won't block on it again. Tell the lead what is still failing.)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warren-dean/code-kit",
-  "version": "0.3.15",
+  "version": "0.5.0",
   "description": "Keeps AI coding agents inside your project's rules: lanes, layer rules, protected paths and proof before finish, enforced by Claude Code hooks and in CI",
   "license": "MIT",
   "author": "Warren Langeveldt",
@@ -38,6 +38,6 @@
     "node": ">=22"
   },
   "scripts": {
-    "test": "node --test test/units.test.mjs && node test/hooks.test.mjs"
+    "test": "node --test test/units.test.mjs && node test/hooks.test.mjs && node test/mod.mjs"
   }
 }

package/skills/init/SKILL.md

@@ -31,7 +31,7 @@ Say which one applies and why before you start.
    - **Design-first rules:** screens designed before they are built, and where approvals are listed.
    - **Commands:** test, lint, typecheck, database and deploy commands, and which must never run locally.
 2. **The repository.** Map the real layout: `git ls-files | cut -d/ -f1-3 | sort | uniq -c`, package manifests (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`), workspace files, existing lint, format and test scripts, CI workflows and CODEOWNERS.
-3. **Existing kit.** If the project has `.claude/hooks`, agents or skills, read them. The kit replaces local hooks; agents and skills are kept and adapted, not rewritten.
+3. **Existing kit.** If the project has `.claude/hooks`, agents or skills, read them. The kit replaces local hooks; agents and skills are kept and adapted, not rewritten. On an update (section 4), skills that came from the docs' recipes follow those recipes as they are now.
 4. **Other tools.** Run `adapters --config .claude/code-kit.draft.json` once the draft exists. It lists the tools code-kit has an adapter for (such as Context Graph, found by its `.ctx/` folder), what each adds to the rules, and the setup each needs. Don't copy an adapter's paths into the config; they're added automatically while the tool is present.
 
 **Brownfield, in addition:**
@@ -97,6 +97,8 @@ Draft, alongside the config:
   - Drop the spec-check lines if the config has no `docs.specs`.
 - **CLAUDE.md:** add the section from `${CLAUDE_PLUGIN_ROOT}/templates/claude-md.md`.
 - **Project skills** (recipes like "new migration" or "new endpoint"): list the recipes the docs describe step by step, and offer to write them. Don't write them unasked, and never write an empty one.
+  - Write each as `.claude/skills/<name>/SKILL.md`, saying in its description which recipe in which doc it comes from, so an update can find it again.
+  - List it under **Skills to use** on every lane agent whose paths the recipe touches, not only one: a recipe that adds a migration and the endpoint that uses it belongs to both lanes. A recipe only the lead follows goes in the CLAUDE.md section instead.
 
 Show the person:
 
@@ -144,10 +146,16 @@ Re-run whenever the build has moved on: new apps or packages, folders that moved
 
 4. **Also propose:**
    - agent files for new lanes, and updates to agents whose paths changed;
+   - **project skills**, by reading the recipes in the docs again and comparing them with `.claude/skills/`:
+     - a new skill for each recipe the docs now describe that has none;
+     - an update to each skill whose recipe changed, showing what changed;
+     - removing a skill whose recipe is gone from the docs (ask first: the person may want it kept);
+     - the matching **Skills to use** changes on every lane agent whose paths each recipe touches;
+     - skills the person wrote themselves, with no recipe behind them, stay as they are;
    - a smaller baseline when `baseline` shows violations were fixed. It only ever shrinks.
 5. **On approval:**
    1. Replace `.claude/code-kit.json` with the draft and delete the draft.
-   2. Write or update the agents.
+   2. Write or update the agents, and write, update or remove the project skills as approved.
    3. Run `baseline --write` if it shrank.
    4. Run `check` and `unowned`.
    5. Commit on a branch.

package/skills/review/SKILL.md

@@ -50,8 +50,16 @@ Read the story, every requirement it cites, and the full diff (`git diff <base>.
 
 Report the table, `verify`'s result and one of:
 
+- **Files any agent may write** (`anyActor`, such as a lockfile or recorded decisions) have no owning lane, but they have a reviewer: `trace <file>` names it (the lead unless the config names a lane). Review those changes as that reviewer would, or ask that lane's agent.
 - **Merge.** Everything passes. The lead merges the branch into its own branch (`git merge --no-ff <branch>`), sets the story's `**Status:**` to `done` in the plan, and commits. `main` and the other protected branches are merged by a person, through a pull request, after `verify` passes in CI. When the branch is merged, remove its worktree.
-- **Send back.** List each problem, where it is, and what "fixed" looks like. Send the list to the same lane agent if it's still running (SendMessage), or dispatch the story again with the list added to the brief. Set the story's status to `in progress`.
+- **Send back.** List each problem, where it is, and what "fixed" looks like. Record the send-back, so `status` and `next` read the branch as waiting for its fix rather than finished:
+
+  ```bash
+  node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" sent-back <branch> --reason "<the problems, in one line>"
+  ```
+
+  Send the list to the same lane agent if it's still running (SendMessage), or dispatch the story again with the list added to the brief. Set the story's status to `in progress`.
+
 - **Ask the person.** When the right answer is a product or scope decision (the spec is silent, or the lane found a real conflict), put the question to the person with your recommendation. Don't merge around it.
 
 Keep the report short: the verdict first, then the table, then the problems.

package/templates/agent.md

@@ -9,7 +9,7 @@ You are the {{lane}} engineer for this repository.
 **Owned paths:** {{lane paths from .claude/code-kit.json}}
 **Layers:** {{the layers in these paths, and what each may depend on}}
 **Specs:** {{the spec files this lane reads}}
-**Skills to use:** spec-check{{, project skills for this lane}}
+**Skills to use:** spec-check{{, every project skill whose recipe touches this lane's paths}}
 **Prove your work with:** `{{the command that proves this lane's work}}`
 
 Lane rules: