@warren-dean/code-kit 0.10.0 → 0.11.1

package/hooks/lib/rules.mjs

@@ -62,6 +62,8 @@ export const RELAYED = '(given in chat, recorded by the lead)';
 export const PANE = '(approved in the code-kit pane)';
 /** Refusals a person's approval would allow, for the mod's band and `code-kit requests`. */
 export const REQUESTS_FILE = '.claude/state/requests.jsonl';
+/** Every approval given through code-kit, and every one used up, kept for the history (CARD-6). */
+export const GIVEN_FILE = '.claude/state/approvals-given.jsonl';
 
 /** The command the lead runs to record approvals a person gave in chat. */
 /** Marks an approval the lead granted on its own, within `approvals.delegate`; `rule` names the rule. */
@@ -107,11 +109,52 @@ export function approvalHowTo(names, actor, root, allows = 'these edits', config
 export function grantApprovals(root, names, lane, reason, marks = {}) {
   const dir = lane ? join(approvalsDir(root), lane) : approvalsDir(root);
   mkdirSync(dir, { recursive: true });
-  return names.map((name) => {
+  const at = new Date().toISOString();
+  const files = names.map((name) => {
     const file = join(dir, name);
     writeFileSync(file, `${reason.trim()} ${marks[name] ?? RELAYED}\n`);
     return file;
   });
+  noteGiven(
+    root,
+    names.map((name) => ({
+      at,
+      name,
+      ...(lane ? { lane } : {}),
+      reason: `${reason.trim()} ${marks[name] ?? RELAYED}`,
+    })),
+  );
+  return files;
+}
+
+const givenFile = (root) => join(projectWorktrees(root)[0] ?? root, GIVEN_FILE);
+
+function noteGiven(root, entries) {
+  try {
+    const file = givenFile(root);
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, entries.map((e) => `${JSON.stringify(e)}\n`).join(''));
+  } catch {
+    // the approval stands; only its history misses it
+  }
+}
+
+/** The approvals given through code-kit (and those used up), oldest first. */
+export function approvalsGiven(root) {
+  try {
+    return readFileSync(givenFile(root), 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .flatMap((l) => {
+        try {
+          return [JSON.parse(l)];
+        } catch {
+          return [];
+        }
+      });
+  } catch {
+    return [];
+  }
 }
 
 /** `path` with symlinks resolved, even if it doesn't exist yet (macOS /var → /private/var). */
@@ -249,8 +292,21 @@ export function useApproval(root, name, actor) {
   for (const file of [
     ...(actor?.kind === 'lane' ? [join(dir, actor.lane, name)] : []),
     join(dir, name),
-  ])
-    if (inForce(file)) return rmSync(file, { force: true });
+  ]) {
+    const a = inForce(file);
+    if (!a) continue;
+    // Kept in the history, and as the answer to the request it was given for, once its file is gone.
+    noteGiven(root, [
+      {
+        at: a.grantedAt,
+        name,
+        ...(file !== join(dir, name) ? { lane: actor.lane } : {}),
+        reason: a.reason,
+        usedAt: new Date().toISOString(),
+      },
+    ]);
+    return rmSync(file, { force: true });
+  }
 }
 
 const requestsFile = (root) => join(projectWorktrees(root)[0] ?? root, REQUESTS_FILE);
@@ -283,6 +339,9 @@ export function readRequests(root) {
  * never changes the refusal, so any failure here is ignored.
  */
 export function recordRequest(root, actor, names, what, why, now = Date.now()) {
+  // A read-only agent (a reviewer) is never approved to write: what it changed goes back, not to the
+  // person as a request.
+  if (actor?.kind === 'readonly') return;
   try {
     const request = {
       at: new Date(now).toISOString(),
@@ -307,16 +366,161 @@ export function recordRequest(root, actor, names, what, why, now = Date.now()) {
 /** Requests from the last 60 minutes that an approval in force doesn't yet answer, newest first. */
 export function openRequests(root, now = Date.now()) {
   const open = [];
+  const given = approvalsGiven(root);
   for (const r of readRequests(root).reverse()) {
     if (now - Date.parse(r.at) >= APPROVAL_MINUTES * 60_000) continue;
     if (open.some((o) => sameRequest(o, r))) continue;
+    // From before read-only agents stopped asking: only the lead and the lanes are ever approved.
+    if (!r.lane && r.actor !== 'lead session') continue;
     const actor = r.lane ? { kind: 'lane', lane: r.lane } : { kind: 'lead' };
     if (r.names.every((n) => approval(root, n, actor))) continue;
+    // Answered already: approved after it was asked (since expired, or used up by the commit it
+    // allowed), or the file it named was committed since by someone who could.
+    if (r.names.every((n) => grantedSince(root, given, n, r))) continue;
+    if (committedSince(root, r)) continue;
     open.push(r);
   }
   return open;
 }
 
+/** Whether `name` was approved for the request's lane (or for everyone) at or after it was asked. */
+function grantedSince(root, given, name, r) {
+  const asked = Date.parse(r.at);
+  if (
+    given.some(
+      (g) => g.name === name && (!g.lane || g.lane === r.lane) && Date.parse(g.at) >= asked,
+    )
+  )
+    return true;
+  const dir = approvalsDir(root);
+  return [...(r.lane ? [join(dir, r.lane, name)] : []), join(dir, name)].some((file) => {
+    try {
+      return statSync(file).isFile() && statSync(file).mtimeMs >= asked;
+    } catch {
+      return false;
+    }
+  });
+}
+
+/** Whether the file a request named has been committed, on any branch, since it was asked. */
+function committedSince(root, r) {
+  const path = String(r.what);
+  if (/\s/.test(path) || (!path.includes('/') && !path.includes('.'))) return false;
+  try {
+    const out = execFileSync(
+      'git',
+      [
+        '-C',
+        root,
+        'log',
+        '--all',
+        '-1',
+        '--format=%ct',
+        `--since=@${Math.floor(Date.parse(r.at) / 1000)}`,
+        '--',
+        path,
+      ],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    );
+    return Boolean(out.trim());
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * CARD-6: every approval given, newest first: { at, name, lane, reason, by, files, branches, used,
+ * expired }. From the approvals given through code-kit, the approvals on disk (a person's own `!` echo
+ * included), and the audit log in every worktree, so an approval shows before its branch merges.
+ */
+export function approvalHistory(root, now = Date.now()) {
+  const grants = [];
+  const near = (a, b) => Math.abs(Date.parse(a) - Date.parse(b)) < 2000;
+  const add = (g) => {
+    const found = grants.find(
+      (x) => x.name === g.name && (x.lane ?? null) === (g.lane ?? null) && near(x.at, g.at),
+    );
+    if (found) {
+      if (g.usedAt) found.used = true;
+      return found;
+    }
+    const grant = {
+      at: g.at,
+      name: g.name,
+      lane: g.lane ?? null,
+      reason: g.reason ?? '',
+      files: [],
+      branches: [],
+      used: Boolean(g.usedAt),
+    };
+    grants.push(grant);
+    return grant;
+  };
+  for (const g of approvalsGiven(root)) add(g);
+  const dir = approvalsDir(root);
+  const look = (folder, lane) => {
+    let names = [];
+    try {
+      names = readdirSync(folder);
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      const file = join(folder, name);
+      const st = statSync(file);
+      if (st.isDirectory()) {
+        if (!lane) look(file, name);
+        continue;
+      }
+      add({
+        at: new Date(st.mtimeMs).toISOString(),
+        name,
+        lane,
+        reason: readFileSync(file, 'utf8').trim(),
+      });
+    }
+  };
+  look(dir, null);
+  const seen = new Set();
+  for (const tree of projectWorktrees(root).length ? projectWorktrees(root) : [root]) {
+    let lines = [];
+    try {
+      lines = readFileSync(join(tree, APPROVAL_LOG), 'utf8').split('\n').filter(Boolean);
+    } catch {
+      continue;
+    }
+    for (const line of lines) {
+      if (seen.has(line)) continue;
+      seen.add(line);
+      let e;
+      try {
+        e = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!e.approval || e.approval === 'lead') continue;
+      const grant =
+        grants.find((x) => x.name === e.approval && near(x.at, e.grantedAt ?? e.at)) ??
+        add({ at: e.grantedAt ?? e.at, name: e.approval, reason: e.reason });
+      if (e.file && !grant.files.includes(e.file)) grant.files.push(e.file);
+      if (e.branch && !grant.branches.includes(e.branch)) grant.branches.push(e.branch);
+    }
+  }
+  return grants
+    .map((g) => ({
+      ...g,
+      by: /within the delegated rules/.test(g.reason)
+        ? 'the lead, within your delegated rules'
+        : /given in chat, recorded by the lead/.test(g.reason)
+          ? 'you, in chat'
+          : /in the [\w -]+ pane/.test(g.reason)
+            ? 'you, in the pane'
+            : 'you',
+      expired: g.used || now - Date.parse(g.at) >= approvalMinutes(g.name) * 60_000,
+    }))
+    .sort((a, b) => Date.parse(b.at) - Date.parse(a.at));
+}
+
 /** Approvals in force now: [{ name, lane?, reason, grantedAt, minutesLeft }]. */
 export function approvalsInForce(root, now = Date.now()) {
   const dir = approvalsDir(root);
@@ -434,6 +638,8 @@ export function writeProblem(actor, rel, root, config) {
   // A package a person approved may change the manifests and lockfiles its install rewrites.
   if (dependencyChange(actor, rel, root, config)) return null;
   const guarded = protectedEntry(rel, config);
+  if (actor.kind === 'readonly' && (guarded || !matchesAny(rel, config.anyActor)))
+    return readonlyProblem(actor, rel);
   // The lead writes protected files without an approval: the person reviews them in the pull request,
   // and every committed change is in the audit log. Anyone else needs a person's approval as well.
   if (guarded && actor.kind !== 'lead' && !approval(root, guarded.approval, actor)) {
@@ -441,12 +647,16 @@ export function writeProblem(actor, rel, root, config) {
     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 (matchesAny(rel, config.anyActor)) return null;
-  if (actor.kind === 'readonly') return `${actor.label} is read-only; it may not write ${rel}.`;
+  if (actor.kind === 'readonly') return readonlyProblem(actor, 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);
 }
 
+/** A read-only agent's write, refused, with how to undo one a command it ran made (a build, a generator). */
+const readonlyProblem = (actor, rel) =>
+  `${actor.label} is read-only; it may not write ${rel}. If a command you ran changed it (a build, a formatter or a code generator), put it back with git restore -- ${rel} (or delete it if it's new), and run such commands only in a throwaway worktree of the branch.`;
+
 function outsideAllowed(actor, rel, root, config) {
   if (actor.kind !== 'lead') return false;
   const target = resolve(root, rel);

package/hooks/lib/team.mjs

@@ -60,9 +60,16 @@ export function teamProblems(c) {
     if (
       t.provider !== undefined &&
       t.provider !== 'github' &&
-      !(isObj(t.provider) && typeof t.provider.command === 'string' && t.provider.command.trim())
+      !(
+        isObj(t.provider) &&
+        typeof t.provider.command === 'string' &&
+        t.provider.command.trim() &&
+        (t.provider.fallback === undefined || t.provider.fallback === 'github')
+      )
     )
-      p.push('"team.provider" must be "github" or { "command": "<the provider\'s command>" }');
+      p.push(
+        '"team.provider" must be "github" or { "command": "<the provider\'s command>", "fallback"?: "github" }',
+      );
   }
   for (const [name, lane] of Object.entries(isObj(c.lanes) ? c.lanes : {})) {
     if (!isObj(lane) || lane.owners === undefined) continue;
@@ -148,11 +155,44 @@ function claimOf(message) {
   }
 }
 
-/** The provider for this project's team: GitHub's, or the config's command. */
+/**
+ * The provider for this project's team: GitHub's, or the config's command. A command with
+ * `fallback: "github"` (a hosted provider, such as the code-kit teams hub) hands each operation it
+ * can't reach to the GitHub provider, so claims are still checked while it's down (TEAM-8).
+ */
 export function teamProvider(root, team) {
-  return team.provider === 'github'
-    ? githubProvider(root, team)
-    : commandProvider(root, team, team.provider.command);
+  if (team.provider === 'github') return githubProvider(root, team);
+  const command = commandProvider(root, team, team.provider.command);
+  if (team.provider.fallback !== 'github') return command;
+  const github = githubProvider(root, team);
+  const down = (r) => Boolean(r?.unreachable) || r?.reachable === false;
+  const either =
+    (op) =>
+    (...args) => {
+      const r = command[op](...args);
+      if (!down(r) && r !== null) return r;
+      const g = github[op](...args);
+      // The state says it came through GitHub, and why, for the band.
+      return op === 'state' && g
+        ? { ...g, fallback: r?.why ?? "The team provider can't be reached." }
+        : g;
+    };
+  return {
+    ...Object.fromEntries(
+      [
+        'whoami',
+        'claim',
+        'release',
+        'state',
+        'intend',
+        'settle',
+        'reassign',
+        'intent',
+        'since',
+      ].map((op) => [op, either(op)]),
+    ),
+    forget: () => (command.forget(), github.forget()),
+  };
 }
 
 function githubProvider(root, team) {
@@ -402,11 +442,26 @@ function githubProvider(root, team) {
           'number,title,author,headRefName,isDraft,updatedAt,url',
         ]) ?? 'null',
       );
+      const who = me();
       const state = {
         at: new Date().toISOString(),
         reachable: Boolean(claims),
         github: Boolean(intents && pulls),
-        me: me(),
+        me: who,
+        // What coordinates the team, for the Team pane: GitHub itself, through refs and discussions.
+        provider: {
+          name: 'GitHub',
+          live: false,
+          detail: `claims are refs on origin, intents are discussions in "${team.intents}"`,
+        },
+        // TEAM-13: what the team still needs set up for its claims and intents to work.
+        setup: [
+          ...(who ? [] : ["gh isn't signed in on this machine: run gh auth login."]),
+          ...(claims ? [] : ["The shared repository (origin) can't be reached."]),
+          ...(found && !found.category
+            ? [noCategory(found).replace(/, then raise the intent again\.$/, '.')]
+            : []),
+        ],
         techLead: team.techLead,
         owners: team.owners,
         staleDays: team.staleDays,

package/hooks/mod/decisions.mjs

@@ -2,6 +2,7 @@
 // the person, each with its lineage. The band's "you" lines say what needs them; a decision card says why:
 // what they asked for, the story and requirements it belongs to, what the agent was doing, what was already
 // settled, why the lead couldn't settle this itself, and each option with what happens next.
+import { askWords } from './view.mjs';
 
 /** The kinds of band line that are the person's to decide; the rest are notes. */
 export const DECISION_KINDS = new Set([
@@ -16,6 +17,7 @@ export const DECISION_KINDS = new Set([
   'teamCollision',
   'teamIntent',
   'teamReview',
+  'teamDrift',
 ]);
 
 /** What each answer does, in the person's words. */
@@ -72,6 +74,8 @@ function whyOf(line, check) {
   if (line.kind === 'teamIntent')
     return "You're the tech lead: a change of direction is agreed or dropped by you, and until then everyone builds on what was agreed.";
   if (line.kind === 'teamReview') return "It's in a lane you own, so its review is yours.";
+  if (line.kind === 'teamDrift')
+    return "The team's drift check found your work building on something that has since changed, or heading into someone else's: settle it before it merges.";
   return null;
 }
 
@@ -148,7 +152,7 @@ export function decisionCards(lines, context = {}) {
         })),
         doing:
           line.held?.command ??
-          line.request?.what ??
+          (line.request ? askWords(line.request, line.files ?? [line.request.what]) : null) ??
           (line.proposal?.label ? `Next step: ${line.proposal.label}` : null) ??
           (line.intent
             ? `Intent #${line.intent.id}: ${line.intent.about}${line.intent.touches.length ? ` (touches ${line.intent.touches.join(', ')})` : ''}`

package/hooks/mod/loop.mjs

@@ -14,6 +14,55 @@ const LEAD_STEPS = new Set([
   'update',
 ]);
 
+/** The steps that name stories, which an agent already at work on one shouldn't be asked to start again. */
+const STORY_STEPS = new Set(['dispatch', 'review', 'lead', 'design']);
+const AT_WORK = new Set(['pending', 'running', 'waiting']);
+
+/**
+ * LOOP-9: the stories agents are at work on now, by the task each was started with: a lane agent is
+ * started as "ST-12 booking form", a reviewer as "Review web/st-12". `code-kit next` reads only the
+ * branches, so it can't tell a branch still being built, or already under review, from one waiting.
+ */
+export function storiesInFlight(agents) {
+  const ids = new Set();
+  for (const a of agents ?? []) {
+    if (!AT_WORK.has(a.status)) continue;
+    const text = `${a.description ?? ''}`;
+    for (const m of text.matchAll(/\bST-(\d+)\b/gi)) ids.add(`ST-${m[1]}`);
+    for (const m of text.matchAll(/\b[\w-]+\/st-(\d+)\b/gi)) ids.add(`ST-${m[1]}`);
+  }
+  return ids;
+}
+
+/**
+ * LOOP-9: the step from `code-kit next`, without the stories already in flight. A step left with none
+ * gives way to the next one `next` listed; with nothing left, the loop waits, saying for what, until an
+ * agent finishes (which moves the project on).
+ */
+export function withoutInFlight(step, inFlight) {
+  if (!step || !inFlight?.size) return step;
+  const chain = [step, ...(step.then ?? [])].map(({ then: _then, ...s }) => s);
+  const kept = [];
+  const busy = [];
+  for (const s of chain) {
+    if (!STORY_STEPS.has(s.step)) {
+      kept.push(s);
+      continue;
+    }
+    const ids = (s.args ?? '').split(/\s+/).filter(Boolean);
+    const free = ids.filter((id) => !inFlight.has(id.toUpperCase()));
+    busy.push(...ids.filter((id) => inFlight.has(id.toUpperCase())));
+    if (free.length) kept.push({ ...s, args: free.join(' ') });
+  }
+  if (kept.length) return { ...kept[0], ...(kept.length > 1 ? { then: kept.slice(1) } : {}) };
+  const names = [...new Set(busy)];
+  return {
+    step: 'wait',
+    why: `${names.join(', ')} ${names.length === 1 ? 'is' : 'are'} still with ${names.length === 1 ? 'its agent' : 'their agents'}; the loop goes on when one finishes`,
+    inFlight: names,
+  };
+}
+
 /**
  * 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

package/hooks/mod/panes.mjs

@@ -1,7 +1,6 @@
 // Panes v2 (docs/specs/11-panes.md): the Lanes pane's frame. A counts header, tabs, what needs the
 // person, the tab's body and the keys, as pure functions of what the mod already holds. The Lanes
 // tab's body is view.mjs's lanesPane; the Queue and Usage tabs reuse its sections.
-import { teamTab } from './teamview.mjs';
 import { trailRows as trailRowsDrawn, trailSvg } from './trail.mjs';
 import {
   MAP_LEGEND,
@@ -32,7 +31,6 @@ export const TABS = [
   { id: 'map', label: 'Trail', hotkey: '5' },
   { id: 'queue', label: 'Queue', hotkey: '6' },
   { id: 'usage', label: 'Usage', hotkey: '7' },
-  { id: 'team', label: 'Team', hotkey: '8' },
 ];
 
 /** The pane's own state, kept by the mod between draws. */
@@ -246,8 +244,7 @@ export function lanesFrame(view, els, on) {
     key: 'tabs',
     flexDirection: 'row',
     columnGap: 1,
-    // The Team tab is there only for a team (TEAM-7).
-    children: TABS.filter((t) => t.id !== 'team' || view.team).map((t) =>
+    children: TABS.map((t) =>
       Button({
         key: `tab-${t.id}`,
         label: t.label,
@@ -272,52 +269,48 @@ export function lanesFrame(view, els, on) {
 
   const selected = state.lanes.find((l) => l.name === ui.selected) ?? null;
   const body =
-    ui.tab === 'team'
-      ? teamTab(view.team ?? null, view.teamSince ?? null, els, on)
-      : ui.tab === 'decisions'
-        ? decisionsTab(view.cards ?? [], ui, els, on)
-        : ui.tab === 'journal'
-          ? journalTab(view.journal ?? [], els, view.now)
-          : ui.tab === 'code'
-            ? codeTab(view, els, on)
-            : ui.tab === 'map'
-              ? mapTab(view.status, ui.cell, els, on, view.trail, {
-                  surface: view.surface,
-                  columns: view.columns,
-                })
-              : ui.tab === 'queue'
-                ? queueSection(loop, text, Box)
-                : ui.tab === 'usage'
-                  ? usageSection(view.usage, plan, text, Box)
-                  : [
-                      lanesPane(state, els, view.usage, plan, loop, {
-                        filter: ui.filter,
-                        search: ui.search,
-                        selected: ui.selected,
-                        live: view.live ?? {},
-                        art: view.art ?? null,
-                        detail: selected
-                          ? {
-                              agent: selected.agent ?? null,
-                              owns: view.paths?.[selected.name] ?? [],
-                              stories: laneStories(selected, state),
-                            }
-                          : null,
-                        combined: view.combined ?? null,
-                      }),
-                    ];
+    ui.tab === 'decisions'
+      ? decisionsTab(view.cards ?? [], ui, els, on)
+      : ui.tab === 'journal'
+        ? journalTab(view.journal ?? [], els, view.now)
+        : ui.tab === 'code'
+          ? codeTab(view, els, on)
+          : ui.tab === 'map'
+            ? mapTab(view.status, ui.cell, els, on, view.trail, {
+                surface: view.surface,
+                columns: view.columns,
+              })
+            : ui.tab === 'queue'
+              ? queueSection(loop, text, Box)
+              : ui.tab === 'usage'
+                ? usageSection(view.usage, plan, text, Box)
+                : [
+                    lanesPane(state, els, view.usage, plan, loop, {
+                      filter: ui.filter,
+                      search: ui.search,
+                      selected: ui.selected,
+                      live: view.live ?? {},
+                      art: view.art ?? null,
+                      detail: selected
+                        ? {
+                            agent: selected.agent ?? null,
+                            owns: view.paths?.[selected.name] ?? [],
+                            stories: laneStories(selected, state),
+                          }
+                        : null,
+                      combined: view.combined ?? null,
+                    }),
+                  ];
   const empty =
-    ui.tab === 'team'
-      ? 'This project has no team in its config.'
-      : ui.tab === 'decisions'
-        ? 'Nothing needs you. The lead is handling the build.'
-        : ui.tab === 'journal'
-          ? 'Nothing recorded yet: the journal starts with the brief.'
-          : ui.tab === 'queue'
-            ? 'The merge queue is empty.'
-            : ui.tab === 'usage'
-              ? 'No usage measured yet this session.'
-              : null;
+    ui.tab === 'decisions'
+      ? 'Nothing needs you. The lead is handling the build.'
+      : ui.tab === 'journal'
+        ? 'Nothing recorded yet: the journal starts with the brief.'
+        : ui.tab === 'queue'
+          ? 'The merge queue is empty.'
+          : ui.tab === 'usage'
+            ? 'No usage measured yet this session.'
+            : null;
 
   // VIEW-6: j/k move between lanes; the selected lane's acts; f filters.
   const opening = selected ? storyToOpen(selected, state) : null;