@warren-dean/code-kit 0.8.0 → 0.9.0

package/hooks/lib/teamfacts.mjs

@@ -0,0 +1,187 @@
+// Teams (docs/specs/16-teams.md), the pure parts: names, story branches, staleness and what an intent
+// touches. Shared by the hooks and CLI (team.mjs) and the mod, which runs without Node.
+
+/** A GitHub handle: letters, digits and single hyphens, at most 39 characters. */
+export const isHandle = (h) =>
+  typeof h === 'string' && /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/.test(h);
+
+/** A story id a ref can carry: ST-12, AUTH-3. */
+export const isStoryId = (s) => typeof s === 'string' && /^[A-Za-z][A-Za-z0-9]*-\d+$/.test(s);
+
+/** The paths an intent touches, from its issue's body ("Touches: a/**, b"). */
+export const touchesOf = (body) =>
+  (String(body ?? '').match(/^Touches:\s*(.+)$/m)?.[1] ?? '')
+    .split(',')
+    .map((t) => t.trim().replace(/^`|`$/g, ''))
+    .filter(Boolean);
+
+/** Whole working days (Monday to Friday) from `from` to `to`, both in ms. */
+export function workingDaysBetween(from, to) {
+  let days = 0;
+  const d = new Date(from);
+  d.setUTCHours(0, 0, 0, 0);
+  const end = new Date(to);
+  end.setUTCHours(0, 0, 0, 0);
+  while (d < end) {
+    d.setUTCDate(d.getUTCDate() + 1);
+    if (d.getUTCDay() !== 0 && d.getUTCDay() !== 6) days += 1;
+  }
+  return days;
+}
+
+/** TEAM-9: a claim with when it was last worked on (claimed, or its branch pushed) and whether it's stale. */
+export function withStaleness(claim, lastPush, staleDays, now = Date.now()) {
+  const active = Math.max(Date.parse(claim.at) || 0, lastPush ?? 0);
+  return {
+    ...claim,
+    active: new Date(active).toISOString(),
+    stale: workingDaysBetween(active, now) >= staleDays,
+  };
+}
+
+/** The story a branch is for: web/st-4 → ST-4. Null for any other branch. */
+export const storyOfBranch = (branch) => {
+  const m = String(branch ?? '').match(/^[a-z][a-z0-9-]*\/([a-z][a-z0-9]*-\d+)$/i);
+  return m ? m[1].toUpperCase() : null;
+};
+
+/** The lane a story branch is in: web/st-4 → web. */
+export const laneOfBranch = (branch) => (storyOfBranch(branch) ? branch.split('/')[0] : null);
+
+/** Whether two path globs can name the same file: one's fixed start begins the other's. */
+export function globsOverlap(a, b) {
+  const fixed = (g) => g.split(/[*?{]/)[0];
+  const [x, y] = [fixed(a), fixed(b)];
+  return x.startsWith(y) || y.startsWith(x);
+}
+
+/** An intent from its discussion: { id, by, about, touches, at, url, state }. */
+export const intentOf = (d) => ({
+  id: d.number,
+  by: d.author?.login ?? null,
+  about: d.title,
+  touches: touchesOf(d.body),
+  at: d.createdAt,
+  url: d.url,
+  state: !d.closed
+    ? 'open'
+    : d.stateReason === 'DUPLICATE'
+      ? 'duplicate'
+      : d.stateReason === 'OUTDATED'
+        ? 'dropped'
+        : 'agreed',
+});
+
+/**
+ * TEAM-6: intents raised and settled since `at` (ms), from their discussions: [{ at, by, kind, text }].
+ * A settled one is the tech lead's act; its discussion doesn't say who closed it, so it reads as theirs.
+ */
+export function discussionActivity(nodes, at, techLead = null) {
+  const out = [];
+  for (const d of nodes) {
+    const name = `#${d.number} ${d.title}`;
+    const raised = Date.parse(d.createdAt);
+    if (raised > at)
+      out.push({
+        at: raised,
+        by: d.author?.login ?? 'someone',
+        kind: 'intended',
+        text: `raised intent ${name}`,
+      });
+    const closed = Date.parse(d.closedAt);
+    if (d.closed && closed > at) {
+      const state = intentOf(d).state;
+      out.push({
+        at: closed,
+        by: techLead ?? 'the tech lead',
+        kind: state === 'agreed' ? 'agreed' : 'dropped',
+        text: `${state === 'duplicate' ? 'marked as a duplicate' : state} intent ${name}`,
+      });
+    }
+  }
+  return out;
+}
+
+/** A title as a file name: "Split the report format" → "split-the-report-format". */
+export const slugOf = (title) =>
+  String(title)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 60) || 'decision';
+
+/**
+ * TEAM-10: an agreed intent as a decision record, from its discussion's facts only: { title, body, url,
+ * author, createdAt, closedAt, comments: [{ author, body }] }. The tech lead's words are their comment
+ * agreeing it.
+ */
+export function decisionRecord(d, techLead) {
+  const date = String(d.closedAt ?? d.createdAt).slice(0, 10);
+  const touches = touchesOf(d.body);
+  const why = String(d.body ?? '')
+    .replace(/^Touches:.*$/m, '')
+    .replace(/Raised with code-kit by @\S+ before any code[^\n]*/, '')
+    .trim();
+  const agreed = (d.comments ?? [])
+    .filter((c) => c.author?.login === techLead && /^Agreed by @/.test(c.body))
+    .at(-1)
+    ?.body.replace(/^Agreed by @\S+, the tech lead(: |\.)?/, '')
+    .trim();
+  return [
+    `# ${d.title}`,
+    '',
+    '**Status:** agreed',
+    `**Date:** ${date}`,
+    `**Raised by:** @${d.author?.login ?? 'someone'} · **Agreed by:** @${techLead}`,
+    `**Discussion:** ${d.url}`,
+    '',
+    '## What changes, and why',
+    '',
+    why || '(The intent said no more than its title.)',
+    ...(touches.length ? ['', '## What it touches', '', ...touches.map((t) => `- \`${t}\``)] : []),
+    ...(agreed ? ['', '## Agreed', '', agreed] : []),
+    '',
+  ].join('\n');
+}
+
+/** A config glob as CODEOWNERS patterns, anchored at the root; `{a,b}` becomes one pattern each. */
+export function ownersPatterns(glob) {
+  const alt = glob.match(/\{([^{}]*)\}/);
+  if (alt) return alt[1].split(',').flatMap((x) => ownersPatterns(glob.replace(alt[0], x)));
+  return [glob.startsWith('**') || glob.startsWith('/') ? glob : `/${glob}`];
+}
+
+/**
+ * TEAM-11: CODEOWNERS from the config: the tech lead for the tech lead's paths, then each owned lane's
+ * owners for its paths (later lines win in CODEOWNERS, so lanes come after). `leadPaths` are the
+ * project's own lead paths; `lanes` the config's lanes with their owners.
+ */
+export function codeowners({ techLead, leadPaths, lanes }) {
+  const line = (glob, people) =>
+    ownersPatterns(glob).map((p) => `${p} ${people.map((h) => `@${h}`).join(' ')}`);
+  const out = [
+    '# Generated by `code-kit team codeowners --write` from .claude/code-kit.json.',
+    '# Change the tech lead or the lanes’ owners there, then generate it again.',
+    '',
+    '# The tech lead: the plan, specs and contracts.',
+    ...leadPaths.filter((p) => p !== '*' && p !== '.claude/**').flatMap((p) => line(p, [techLead])),
+  ];
+  for (const [name, lane] of Object.entries(lanes)) {
+    if (!lane.owners?.length) continue;
+    out.push('', `# The ${name} lane.`, ...lane.paths.flatMap((p) => line(p, lane.owners)));
+  }
+  return `${out.join('\n')}\n`;
+}
+
+/** TEAM-12: the board's fields for a story, all text: Lane, Claimed by, Stale and State. */
+export const BOARD_FIELDS = ['Lane', 'Claimed by', 'Stale', 'State'];
+export const boardValues = (story, claim) => ({
+  Lane: story.lane ?? '',
+  'Claimed by': claim?.by ?? '',
+  Stale: claim?.stale ? 'yes' : '',
+  State: story.state ?? '',
+});
+
+/** The fields whose value changed since the last sync: [[field, value]]. */
+export const boardChanges = (before = {}, now) =>
+  BOARD_FIELDS.filter((f) => (before[f] ?? '') !== now[f]).map((f) => [f, now[f]]);

package/hooks/mod/codemap.mjs

@@ -309,13 +309,28 @@ export function neighboursOf(map, path) {
   };
 }
 
+/** MAP-5: the map of the whole project, by folder. */
+export const PROJECT = 'project';
+
+/** Each glowing file shown on the folder holding it, for the project map's folder nodes. */
+export function glowByFolder(glow, folders) {
+  const out = {};
+  const byDepth = [...folders].sort((a, b) => b.length - a.length);
+  for (const [path, g] of Object.entries(glow)) {
+    const folder = byDepth.find((f) => f === '.' || path === f || path.startsWith(`${f}/`));
+    if (folder) out[folder] = g;
+  }
+  return out;
+}
+
 /** The story the code map opens on: the one asked for, else the selected lane's, else one at work. */
 export function mapStoryOf(state, selectedLane, asked = null) {
   if (asked) return asked;
   const lane = state?.lanes?.find((l) => l.name === selectedLane);
   if (lane?.story) return lane.story.id;
   const busy = state?.lanes?.find((l) => l.story && ['building', 'in review'].includes(l.state));
-  return busy?.story.id ?? state?.stories?.find((s) => s.state !== 'done')?.id ?? null;
+  // MAP-5: with no story at work, the whole project, not a story that has no code yet.
+  return busy?.story.id ?? PROJECT;
 }
 
 /** MAP-2, MAP-3: the map's legend: what the colours and words mean, a card being the file's why. */

package/hooks/mod/decisions.mjs

@@ -12,6 +12,10 @@ export const DECISION_KINDS = new Set([
   'queue',
   'review',
   'notice',
+  'teamStale',
+  'teamCollision',
+  'teamIntent',
+  'teamReview',
 ]);
 
 /** What each answer does, in the person's words. */
@@ -29,6 +33,12 @@ const EFFECT = {
   review: 'The lead reviews it against its requirements now.',
   merge: "It's verified and merged now, by you.",
   dismiss: 'Clears this message.',
+  keepClaim: 'Your claim stays, and its clock starts again.',
+  releaseClaim: 'Anyone may claim the story now, and your lease on its files ends.',
+  agreeIntent:
+    'The issue closes as agreed, with your words; then put it in the specs or decisions so every agent builds on it.',
+  dropIntent: 'The issue closes as dropped, and the team carries on as agreed before.',
+  team: 'Opens the Team tab: who is building what, and what changed since you last looked.',
 };
 
 /** Why a line needs the person, when the line itself doesn't say. */
@@ -50,9 +60,18 @@ function whyOf(line, check) {
   if (line.kind === 'proposal') return 'You asked to approve each step before the lead takes it.';
   if (line.kind === 'queue')
     return check?.firstMerge
-      ? 'main has no rules committed yet, so this first merge is yours; after it, the lead merges.'
+      ? 'The loop is off, so merging is yours. main has no rules committed yet: code-kit queue rules puts them there.'
       : "Your rules don't let the lead merge into main, so merges are yours.";
   if (line.kind === 'review') return 'The loop is off, so reviewing finished work is yours.';
+  if (line.kind === 'teamStale')
+    return "It's your claim: nobody else can build it while you hold it, and the tech lead may hand it on.";
+  if (line.kind === 'teamCollision')
+    return `Your agents and ${line.other.by}'s are changing the same files; whoever merges second resolves the conflict. Agree who goes first.`;
+  if (line.kind === 'teamIntent' && line.intent && /touches yours/.test(line.text))
+    return 'It changes what you own or are building: read it before your agents build further on the old way.';
+  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.";
   return null;
 }
 
@@ -130,7 +149,11 @@ export function decisionCards(lines, context = {}) {
         doing:
           line.held?.command ??
           line.request?.what ??
-          (line.proposal?.label ? `Next step: ${line.proposal.label}` : 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(', ')})` : ''}`
+            : null) ??
+          (line.pull ? `Pull request #${line.pull.number} on ${line.pull.branch}` : null),
         settled,
         why: whyOf(line, check),
         options: line.actions.map((a) => ({ ...a, effect: EFFECT[a.id] ?? null })),

package/hooks/mod/loop.mjs

@@ -3,7 +3,7 @@
 // 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']);
+const LEAD_STEPS = new Set(['dispatch', 'review', 'lead', 'merge', 'rules', 'design', 'setup']);
 
 /**
  * The prompt for a step from `code-kit next --json` (LOOP-1), or null when it isn't the lead's to
@@ -19,6 +19,19 @@ export function leadPrompt(step, { cli = 'code-kit' } = {}) {
     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;
+  // SETUP-2: the base has no rules yet; the lead puts the approved ones there, then merges as usual.
+  if (step.step === 'rules')
+    return `Put code-kit's approved rules onto ${ids[0] ?? 'the base'}: run node "${cli}" queue rules. It commits the rules as committed on this branch, without switching branches; after it, merge the queue as usual.`;
+  // ONB-3: a companion set up before any coding.
+  if (step.step === 'setup')
+    return ids.length
+      ? `Before any code is written, set up ${ids[0].split(':')[0]}: run /${ids[0]}. ${step.why ?? ''}`.trim()
+      : null;
+  // ONB-2: the screens designed, and approved by the person, before they're built.
+  if (step.step === 'design')
+    return ids.length
+      ? `Design ${ids.join(', ')} before any of their screens are built: run /code-kit:design ${ids.join(' ')}.`
+      : null;
   if (step.step === 'dispatch')
     return ids.length
       ? `Dispatch ${ids.join(', ')}: run /code-kit:dispatch ${ids.join(' ')}.`
@@ -40,8 +53,15 @@ export const stepKey = (step) => `${step.step}:${step.args ?? ''}`;
 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;
+    {
+      dispatch: 'Dispatch',
+      review: 'Review',
+      lead: 'Build',
+      merge: 'Merge',
+      rules: 'Rules onto',
+      design: 'Design',
+      setup: 'Set up',
+    }[step.step] ?? step.step;
   return ids ? `${verb} ${ids}` : verb;
 }
 

package/hooks/mod/panes.mjs

@@ -1,10 +1,13 @@
 // 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,
+  PROJECT,
   cardOf,
+  glowByFolder,
   mapRows as codeRows,
   mapStoryOf,
   mapSvg,
@@ -29,6 +32,7 @@ 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. */
@@ -242,7 +246,8 @@ export function lanesFrame(view, els, on) {
     key: 'tabs',
     flexDirection: 'row',
     columnGap: 1,
-    children: TABS.map((t) =>
+    // The Team tab is there only for a team (TEAM-7).
+    children: TABS.filter((t) => t.id !== 'team' || view.team).map((t) =>
       Button({
         key: `tab-${t.id}`,
         label: t.label,
@@ -267,48 +272,52 @@ export function lanesFrame(view, els, on) {
 
   const selected = state.lanes.find((l) => l.name === ui.selected) ?? null;
   const body =
-    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 === '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,
+                      }),
+                    ];
   const empty =
-    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 === '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;
 
   // VIEW-6: j/k move between lanes; the selected lane's acts; f filters.
   const opening = selected ? storyToOpen(selected, state) : null;
@@ -841,6 +850,21 @@ export function moveCell(requirements, id, step, { rows = false } = {}) {
   return specs[(row + step + specs.length) % specs.length].requirements[0].id;
 }
 
+/** The engine's limit on a Select's options. */
+export const SELECT_MAX = 64;
+
+/**
+ * TRACE-2: the requirements the picker offers: those in the selected one's spec, at most SELECT_MAX,
+ * a window around the selected one when the spec has more.
+ */
+export function pickerOf(requirements, selected) {
+  const same = requirements.filter((r) => r.file === selected.file);
+  if (same.length <= SELECT_MAX) return same;
+  const at = same.findIndex((r) => r.id === selected.id);
+  const start = Math.max(0, Math.min(at - SELECT_MAX / 2, same.length - SELECT_MAX));
+  return same.slice(start, start + SELECT_MAX);
+}
+
 /**
  * The Map tab (TRACE-1 to TRACE-4): a row per spec, a cell per requirement, a legend, and the
  * selected requirement's stories and tests. `status` is `code-kit status --json`'s.
@@ -946,7 +970,8 @@ export function mapTab(
         key: 'map-select',
         label: 'Requirement',
         value: selected.id,
-        options: requirements.map((r) => ({
+        // A Select holds at most 64 options: the selected requirement's own spec, around it.
+        options: pickerOf(requirements, selected).map((r) => ({
           value: r.id,
           label: `${CELL[cellOf(r)].glyph} ${r.id} ${r.title}`,
         })),
@@ -1080,11 +1105,16 @@ const RUN_STYLE = {
  */
 export function codeTab(view, { Box, Text, Button, Svg }, on) {
   const text = (value, style = {}) => Text({ ...style, children: [value] });
-  const { state, ui = DEFAULT_UI, codeMap: map = null, glow = {}, art = null } = view;
+  const { state, ui = DEFAULT_UI, codeMap: map = null, art = null } = view;
+  let glow = view.glow ?? {};
   const storyId = mapStoryOf(state, ui.selected, ui.mapStory);
-  const choices = (state?.stories ?? []).filter(
-    (s) => s.id === storyId || ['in progress', 'review', 'sent back'].includes(s.state),
-  );
+  const project = { id: PROJECT, title: 'Whole project' };
+  const choices = [
+    project,
+    ...(state?.stories ?? []).filter(
+      (s) => s.id === storyId || ['in progress', 'review', 'sent back'].includes(s.state),
+    ),
+  ];
   const picker = Box({
     key: 'map-stories',
     flexDirection: 'row',
@@ -1093,7 +1123,7 @@ export function codeTab(view, { Box, Text, Button, Svg }, on) {
     children: choices.map((s) =>
       Button({
         key: `map-story-${s.id}`,
-        label: `${s.id} ${s.title}`,
+        label: s.id === PROJECT ? s.title : `${s.id} ${s.title}`,
         ...(s.id === storyId ? { variant: 'primary' } : { plain: true }),
         onPress: () => on.onMapStory(s.id),
       }),
@@ -1101,9 +1131,28 @@ export function codeTab(view, { Box, Text, Button, Svg }, on) {
   });
   if (!storyId) return [text('No story to map yet: the plan has none open.', { dimColor: true })];
   if (!map || map.story?.id !== storyId)
-    return [picker, text(`Reading ${storyId}'s code…`, { dimColor: true })];
+    return [
+      picker,
+      text(storyId === PROJECT ? "Reading the project's code…" : `Reading ${storyId}'s code…`, {
+        dimColor: true,
+      }),
+    ];
   if (!map.files.length)
-    return [picker, text(`${storyId} hasn't changed any code yet.`, { dimColor: true })];
+    return [
+      picker,
+      text(
+        storyId === PROJECT
+          ? 'The project has no code yet.'
+          : `${storyId} hasn't changed any code yet. Whole project shows the code that's there.`,
+        { dimColor: true },
+      ),
+    ];
+  // MAP-5: on the project map, a file at work glows on its folder.
+  if (storyId === PROJECT)
+    glow = glowByFolder(
+      glow,
+      map.files.map((f) => f.path),
+    );
   const selected = map.files.some((f) => f.path === ui.mapFile) ? ui.mapFile : map.files[0].path;
   // The lanes' tints are RGB numbers (the characters' colours); text and SVG take them as hex.
   const tints = Object.fromEntries(

package/hooks/mod/register.mjs

@@ -67,6 +67,10 @@ let reviewTurn = null; // 'next' until the lead's review turn starts, then its i
 let approving = null; // the open Approve… confirmation: { request, reason, error }
 let result = null; // what the last merge reported
 let notice = null; // why the person's last act failed
+let teamSince = null; // TEAM-6: since you last looked, as read when the Team tab opened
+let boardSynced = -Infinity; // TEAM-12: when the board was last synced
+let projectRead = -Infinity; // MAP-5: when the whole project's map was last read
+const BOARD_EVERY_MS = 10 * 60000;
 let act = null; // the session's actions, made at session start
 let settingRows = []; // the harness settings, from `code-kit settings --json`
 let pendingSetting = null; // a change waiting for the person's reason: { key, value, reason, error }
@@ -221,6 +225,15 @@ export function register(on) {
           valid && check.adapters?.length
             ? ((await json('adapters', '--session', session)) ?? [])
             : [];
+        // TEAM-7: the team's claims, intents and pull requests, where the project is a team's.
+        const team = valid && check.team ? await json('team') : null;
+        // TEAM-12: the plan mirrored onto the team's Project board, at most every 10 minutes, in the
+        // background: a slow GitHub never holds up the band.
+        const at = await $.clock.now();
+        if (team && check.team?.board && at - boardSynced >= BOARD_EVERY_MS) {
+          boardSynced = at;
+          $.process.run(['node', cli, 'team', 'board'], { cwd, timeoutMs: 120000 }).catch(() => {});
+        }
         // The agents at work; none where the session has none bound (claude -p before it mounts).
         const atWork = agentsAtWork(await $.agent.list().catch(() => []));
         model = {
@@ -232,6 +245,7 @@ export function register(on) {
           timeline,
           adapters,
           check,
+          team,
           base: status?.base ?? null,
         };
         if (model.state.kind === 'ok') await act.registerReviewer();
@@ -243,9 +257,19 @@ export function register(on) {
         if (model.state?.kind !== 'ok') return;
         if (paneUi.tab === 'code') {
           const id = mapStoryOf(stateNow(), paneUi.selected, paneUi.mapStory);
-          codeMap = id ? ((await json('map', id)) ?? codeMap) : null;
+          // MAP-5: the whole project reads every code file, so at most every 30 seconds.
+          const now = await $.clock.now();
+          const fresh =
+            id === 'project' && codeMap?.story?.id === 'project' && now - projectRead < 30000;
+          if (!fresh) {
+            codeMap = id ? ((await json('map', id)) ?? codeMap) : null;
+            if (id === 'project') projectRead = now;
+          }
         }
         if (paneUi.tab === 'map') trailData = (await json('trail')) ?? trailData;
+        // TEAM-6: since you last looked, read once each time the Team tab opens, which marks it read.
+        if (paneUi.tab === 'team' && model.check?.team && !teamSince)
+          teamSince = (await json('team', 'since')) ?? { people: {} };
         // JOURNAL-1, DECIDE-2: the lineage, for the Journal tab and the decisions' cards.
         const deciding = held.size > 0 || (model.requests?.open ?? []).length > 0;
         if (model.check?.docs?.plan && (['journal', 'decisions'].includes(paneUi.tab) || deciding))
@@ -543,6 +567,47 @@ export function register(on) {
         await $.ui.open({ id: RESULT_ID, title: 'Merge', focus: true, closeOnEscape: true });
         await act.reload();
       },
+      // TEAM-9: the person keeps or releases their stale claim; TEAM-5: the tech lead agrees or drops an
+      // intent. Each is the person's own press, run as them.
+      teamAct: async (args, done) => {
+        const ran = await $.process.run(['node', cli, ...args], { cwd, timeoutMs: 60000 });
+        notice =
+          ran.exitCode === 0
+            ? null
+            : `${done} failed: ${(ran.stderr || ran.stdout).trim().split('\n')[0]}`;
+        await act.reload();
+      },
+      keepClaim: (line) => act.teamAct(['team', 'keep', line.claim.story], 'Keeping the claim'),
+      releaseClaim: (line) =>
+        act.teamAct(['team', 'release', line.claim.story], 'Releasing the claim'),
+      // TEAM-10: agreed, the lead records it where agents read it, through a pull request.
+      agreeIntent: async (line) => {
+        const { id, about } = line.intent;
+        await act.teamAct(
+          ['intend', 'agree', String(id), '--reason', 'agreed in the code-kit pane'],
+          'Agreeing the intent',
+        );
+        if (notice) return;
+        await $.prompt
+          .submit({
+            text: `Intent #${id} (${about}) was agreed. Record it so every agent builds on it: run node "${cli}" intend record ${id}, then commit the decision record on a branch lead/decision-${id}, push it and open a pull request.`,
+          })
+          .catch(() => {});
+      },
+      dropIntent: (line) =>
+        act.teamAct(
+          ['intend', 'drop', String(line.intent.id), '--reason', 'dropped in the code-kit pane'],
+          'Dropping the intent',
+        ),
+      // TEAM-7: the Team tab, opened from the band.
+      team: async () => {
+        paneUi = { ...paneUi, tab: 'team', story: null };
+        if (!(await $.ui.panes()).some((p) => p.id === PANE_ID))
+          await $.ui.open({ id: PANE_ID, title: 'Lanes', focus: true, closeOnEscape: true });
+        await act.readMaps();
+        $.ui.invalidate('ui.render');
+        return {};
+      },
       approvals: async () => {
         await act.reload();
         if (model.state.kind === 'none') return { text: NOT_CODE_KIT };
@@ -1456,6 +1521,7 @@ export function register(on) {
       live: liveNow(now),
       nextStep: loop.nextStep,
       combined: combinedNow(),
+      team: model.team ?? null,
     });
 
   on('ui.render', { component: 'Pane', requestId: PANE_ID }, async ($, e) => {
@@ -1473,6 +1539,8 @@ export function register(on) {
         needs: linesNow(now).filter((l) => !l.mission),
         cards: cardsNow(now),
         journal: journalNow(),
+        team: model.team ?? null,
+        teamSince,
         now,
         live: liveNow(now),
         held: [...held.values()],
@@ -1499,6 +1567,7 @@ export function register(on) {
       $.ui.resolve(e),
       {
         onTab: (tab) => {
+          if (tab !== 'team') teamSince = null;
           paneUi = { ...paneUi, tab };
           $.ui.invalidate('ui.render');
           act?.readMaps().then(() => $.ui.invalidate('ui.render'));