@warren-dean/code-kit 0.10.0 → 0.11.1

package/hooks/mod/view.mjs

@@ -630,6 +630,31 @@ 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. */
+/**
+ * CARD-2: open requests as the decisions they are: one per approval and lane, with every file (or
+ * command) it was asked for, newest first. Approving it covers them all.
+ */
+export function approvalAsks(open) {
+  const asks = new Map();
+  for (const r of open ?? []) {
+    const key = `${[...r.names].sort().join(',')}|${r.lane ?? r.actor}`;
+    const ask = asks.get(key) ?? { request: r, files: [] };
+    if (!ask.files.includes(r.what)) ask.files.push(r.what);
+    asks.set(key, ask);
+  }
+  return [...asks.values()];
+}
+
+/** What an approval decision covers, in a line: "contract for the platform lane: a.ts, b.ts (2 files)". */
+export function askWords(request, files = [request?.what]) {
+  const who = request.lane ? `the ${request.lane} lane` : request.actor;
+  const list =
+    files.length > 4
+      ? `${files.slice(0, 4).join(', ')} and ${files.length - 4} more`
+      : files.join(', ');
+  return `${request.names.map(approvalLabel).join(', ')} for ${who}: ${list}${files.length > 1 ? ` (${files.length} files)` : ''}`;
+}
+
 export function approvalLabel(name) {
   return name.startsWith('dep-') ? name.slice(4).replaceAll('+', '/') : name;
 }
@@ -745,12 +770,14 @@ export function bandLines({
       actions: [{ id: 'go', label: 'Go' }],
     });
   // A held call's request is asked on its own line above, not again here.
-  const open = (requests?.open ?? []).filter((r) => !held.some((h) => sameAsk(h, r)));
-  if (open.length)
+  // CARD-2: counted as decisions, not files: one approval for a lane covers every file it was asked for.
+  const asks = approvalAsks((requests?.open ?? []).filter((r) => !held.some((h) => sameAsk(h, r))));
+  if (asks.length)
     lines.push({
       kind: 'approvals',
-      text: `${plural(open.length, 'approval', 'approvals')} waiting`,
-      request: open[0],
+      text: `${plural(asks.length, 'approval', 'approvals')} waiting`,
+      request: asks[0].request,
+      files: asks[0].files,
       actions: [{ id: 'approve', label: 'Approve…' }],
     });
   // DECIDE-1: reviewing a lane's work is the lead's. Only with the loop off, where the person runs the
@@ -856,10 +883,22 @@ export function band(lines, { Box, Text, Button }, onAction) {
   };
   const LIVE = { quiet: 'yellow', stalled: 'red' };
   const LABEL = 8;
+  // Two lines can share a kind or an action (two drift findings, each with Team): the second and later
+  // get a number, so every row and button keeps its own key.
+  const counter = () => {
+    const seen = new Map();
+    return (key) => {
+      const n = (seen.get(key) ?? 0) + 1;
+      seen.set(key, n);
+      return n === 1 ? key : `${key}-${n}`;
+    };
+  };
+  const uniqueButton = counter();
+  const uniqueRow = counter();
   const buttons = (line) =>
     line.actions.map((a) =>
       Button({
-        key: `band-${a.id}`,
+        key: uniqueButton(`band-${a.id}`),
         label: a.hotkey ? `${a.hotkey} ${a.label}` : a.label,
         hotkey: a.hotkey,
         onPress: () => onAction(a.id, line),
@@ -900,7 +939,7 @@ export function band(lines, { Box, Text, Button }, onAction) {
     const label = line.mission ? line.label : note ? 'note' : saidYou ? '' : 'you';
     if (!line.mission && !note) saidYou = true;
     return Box({
-      key: `band-${line.kind}`,
+      key: uniqueRow(`band-${line.kind}`),
       flexDirection: 'row',
       columnGap: 1,
       children: [
@@ -1117,12 +1156,13 @@ export function refusalView(card, expanded, { Box, Text, Button }, { onApprove,
 export function approvalsText(requests) {
   const open = requests?.open ?? [];
   const inForce = requests?.inForce ?? [];
+  const history = requests?.history ?? [];
+  const asks = approvalAsks(open);
   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}`,
-    ),
+    asks.length
+      ? `${plural(asks.length, 'approval', 'approvals')} waiting:`
+      : 'No requests waiting.',
+    ...asks.map((a) => `  ${askWords(a.request, a.files)}`),
     inForce.length
       ? `${plural(inForce.length, 'approval', 'approvals')} in force:`
       : 'No approvals in force.',
@@ -1130,6 +1170,14 @@ export function approvalsText(requests) {
       (a) =>
         `  ${approvalLabel(a.name)} for ${a.lane ? `the ${a.lane} lane` : 'any agent'}, ${a.minutesLeft} min left: ${a.reason}`,
     ),
+    // CARD-6: what was given, newest first, whether or not its branch has merged.
+    history.length ? 'Approvals given, newest first:' : 'No approvals given yet.',
+    ...history
+      .slice(0, 20)
+      .map(
+        (h) =>
+          `  ${new Date(h.at).toLocaleString('en-AU', { day: 'numeric', month: 'short', hour: '2-digit', minute: '2-digit' })}  ${approvalLabel(h.name)} for ${h.lane ? `the ${h.lane} lane` : 'any agent'}, by ${h.by}${h.files.length ? ` (${h.files.length} file${h.files.length === 1 ? '' : 's'})` : ''}: ${h.reason}`,
+      ),
   ];
   return lines.join('\n');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warren-dean/code-kit",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "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",

package/skills/dispatch/SKILL.md

@@ -48,7 +48,7 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" team claim ST-<n> --lease "<glob>,
 
 The lease is the paths the story will create or change: its lane's folders for this feature, and any contract it changes. A claim someone else holds is refused with who holds it; pick another story or ask them. Stories in a lane another person owns are theirs to dispatch. Making the story's branch also claims it, and each commit on it adds what it changed to the lease; merging it ends the claim.
 
-Start each story with the Agent tool: `subagent_type` is the lane's agent, `isolation: "worktree"`, and run them in the background. Start every story in the batch in the same message so they run in parallel.
+Start each story with the Agent tool: `subagent_type` is the lane's agent, `isolation: "worktree"`, and run them in the background, with a `description` that starts with the story's id ("ST-12 booking form"): the loop reads it to know the story is in flight, and won't ask for it again while the agent works. Start every story in the batch in the same message so they run in parallel.
 
 The brief is the agent's whole context. Write it so the agent needs nothing else:
 

package/skills/init/SKILL.md

@@ -138,7 +138,8 @@ Once they approve (with any changes):
    - tell the person to make the `code-kit` check required on the protected branches.
 7. Run `check` and `unowned` again, without `--config`.
 8. Commit the setup straight onto the base branch (usually `main`), not a branch: while the base has no `.claude/code-kit.json` committed, the hooks let the lead make that one commit, so the rules the person just approved are in force on `main` and the lead can merge reviewed work from the start, with no first merge for anyone to make. The kit records the protected files in `.claude/approval-log.jsonl`. If the base already has rules (an update, section 4), commit on a branch as usual.
-9. Set up each companion the config now wants (`"adapters": { "<name>": true }`) by running its init skill, for example `/context-graph:init`, which asks nothing. Do it before reporting, so it's in place before the coding loop starts; `code-kit next` also gives `setup` until it is.
+9. **A team, only if there is one.** Not every developer works in a team. Ask once: "Do other developers work in this repository with their own Claude Code sessions?" If yes, run `/code-kit:team-init` now (it asks who the tech lead is and who owns which lanes, and writes the `team` section). If no, or not yet, leave it out and say `/code-kit:team-init` sets it up any time.
+10. Set up each companion the config now wants (`"adapters": { "<name>": true }`) by running its init skill, for example `/context-graph:init`, which asks nothing. Do it before reporting, so it's in place before the coding loop starts; `code-kit next` also gives `setup` until it is.
 
 Report what was set up, what's enforced from now on, how many existing violations the baseline holds, and the open questions. Say who does what from here: the person owns the intent and the rules; the lead owns delivery, so it dispatches, reviews, sends back and merges, and approves within the delegated limits, and only a real decision (scope, something outside those limits, a problem it couldn't solve) comes to the person.
 

package/skills/review/SKILL.md

@@ -57,7 +57,7 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" security --base <base> --branch <b
 
 It does when the diff touches sign-in, permissions, input from outside, personal data, encryption, payments, secrets, or queries and commands built from strings, adds dependencies, or the story cites a security requirement; it says which, and where. When it does:
 
-- Run the `security-reviewer` agent (Agent tool, `subagent_type` `security-reviewer`) with the branch, the base, the story, its requirements, the spec files it touches (their `## Threat model` and `## Security requirements`) and the reasons `security` gave. It reads only, and ends with the same findings block as code-kit's reviewer: each finding graded blocker, concern or nit, with where, the attack and the fix.
+- Run the `security-reviewer` agent (Agent tool, `subagent_type` `security-reviewer`, its `description` naming the branch, such as "Security review web/st-12", so the loop knows the story is under review) with the branch, the base, the story, its requirements, the spec files it touches (their `## Threat model` and `## Security requirements`) and the reasons `security` gave. It reads only, and ends with the same findings block as code-kit's reviewer: each finding graded blocker, concern or nit, with where, the attack and the fix.
 - **A blocker fails the review**, like a failing test: the branch goes back to its lane with the finding (where, the attack, the fix). Concerns are yours to weigh: send back the ones the threat model says matter, and put the rest in the report. Nits go in the report.
 - No `security-reviewer` agent in the project: `security` says so. Review the diff yourself against the same list in `${CLAUDE_PLUGIN_ROOT}/templates/security-reviewer.md`, and tell the person that re-running `/code-kit:init` adds the agent.
 - A background reviewer can't start agents: it lists the security review as due, as a concern with the reasons, and the lead runs it.

package/skills/team-init/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: team-init
+description: Set up a code-kit project for a team of developers, change its team setup, or make it one developer's again. Asks who the tech lead is, who owns which lanes, when a claim goes stale and where intents go, shows the team section before writing it, checks GitHub is ready (gh signed in, the shared repository, the intents' discussion category), and offers CODEOWNERS, the Project board and a hosted team provider. Use when the person says they work in a team, wants teammates to share the project, wants to change the tech lead or lane owners, wants to stop working as a team, or runs /code-kit:team-init. Not every developer works in a team: never set one up unasked.
+---
+
+# Set up the team
+
+A team is several people in one repository, each with their own lead and agents (spec 16). code-kit then claims a story before anyone builds it, leases the files it changes, has intents raised before shared things change, and shows it all in `/team`. One developer needs none of this, and the project works the same without it.
+
+The CLI is `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs"`, run from the project root. Its `team init` shows the team section it would write; with `--write` it writes it, once the person agrees. Only the lead writes it: the hooks refuse it from a lane agent.
+
+## 1. Where things stand
+
+1. `.claude/code-kit.json` must exist and be valid (`check`). If it doesn't, stop: the person runs `/code-kit:init` first.
+2. Run `check --json` and read `team` (null when the project isn't a team's), `me` (who's signed in to gh here) and `lanes`.
+3. The shared repository: `git remote get-url origin` must be on GitHub, and `gh auth status` signed in. Without either, say what's missing; code-kit's own team provider works through both.
+
+Say which applies: **new team**, **change the team**, or **back to one developer** (the person asked to stop working as a team).
+
+## 2. Ask, one question at a time
+
+Ask only what the config can't answer, with the current value as the default on a change.
+
+- **Is this a team?** On a new setup, unless the person already said so: "Do other developers work in this repository with their own Claude Code sessions?" No → stop, and say nothing changed.
+- **Tech lead:** whose GitHub handle owns the plan, specs, contracts and principles, agrees or drops intents, and may release or reassign anyone's claim. Default: `me`.
+- **Lane owners:** for each lane, whose sessions build its stories (GitHub handles), or nobody, in which case whoever claims a story first builds it. `git log --format='%an' -- <lane paths> | sort | uniq -c` and CODEOWNERS suggest people, but ask for handles: names in commits aren't handles.
+- **Stale after:** how many working days without a push before a claim is stale (default 3).
+- **Intents category:** the GitHub Discussions category intents go in (default `Intents`).
+- **Back to one developer:** confirm that claims, owners and intents stop applying, and that teammates' sessions lose them too once it's merged.
+
+## 3. Show, then write
+
+Run it without `--write` and show the person exactly what it prints:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" team init --tech-lead <handle> --owner <lane>=<handle>,<handle> [--stale-days <n>] [--intents <category>]
+node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" team init --off
+```
+
+Give `--owner <lane>=` (nothing after `=`) to take a lane's owners out. Once they agree, run the same command with `--write`. It prints what GitHub still needs; tell the person each, in their words:
+
+- **gh isn't signed in:** they run `! gh auth login`.
+- **Discussions are off, or there's no intents category:** GitHub doesn't let a tool create a category. They turn Discussions on (Settings › Features) and add an "Open-ended discussion" category with the intents' name (Settings › Discussions), once.
+
+## 4. Also offer
+
+Each is optional; ask, and do only what they want:
+
+- **CODEOWNERS** (TEAM-11): `team codeowners --write` writes `.github/CODEOWNERS` from the config, so GitHub asks the tech lead and lane owners to review. Then they require code owners' review in a ruleset on the protected branch.
+- **A Project board** (TEAM-12): with a GitHub Project's owner and number, add `"board": { "owner": "<user or organisation>", "number": <n> }` to `team` in the config; the mod then mirrors the plan onto it.
+- **A hosted team provider:** if a plugin for one is installed (its connect skill is in your skills list, such as `/code-kit-teams:connect`), offer it: it makes claims, leases and intents live, shows who's at work where, and checks each push for drift. Its connect skill sets `team.provider`, with GitHub as the fallback. If none is installed, don't mention one.
+
+## 5. Finish
+
+1. Run `check` and `team` to confirm.
+2. Commit `.claude/code-kit.json` (and CODEOWNERS, if written) on a branch, open a pull request, and merge it as any change to the kit's rules.
+3. Tell the person what each teammate does once: install code-kit, `gh auth login`, pull the change. Their sessions then share the claims, and `/team` shows the team.
+
+Report in three lines: the tech lead and owners as written (or that the project is one developer's again), what GitHub still needs, and what each teammate does.