@warren-dean/code-kit 0.8.0 → 0.9.0

package/bin/code-kit.mjs

@@ -53,11 +53,20 @@ import { traceFile } from '../hooks/lib/trace.mjs';
 import { buildStatus, specCheckRows } from '../hooks/lib/plan.mjs';
 import { recordSentBack } from '../hooks/lib/reviews.mjs';
 import { storyTimes } from '../hooks/lib/timeline.mjs';
-import { storyMap, trail } from '../hooks/lib/storymap.mjs';
+import { PROJECT, projectMap, storyMap, trail } from '../hooks/lib/storymap.mjs';
 import { journal } from '../hooks/lib/journal.mjs';
 import { dequeue, enqueue, lastMerged, readQueue, settle, waiting } from '../hooks/lib/queue.mjs';
 import { SETTINGS, parseSetting, settingOf, withSetting } from '../hooks/lib/harness.mjs';
 import { readLoop, writeLoop } from '../hooks/lib/loop-state.mjs';
+import {
+  claimChanges,
+  storyOfBranch,
+  syncBoard,
+  teamOf,
+  teamProvider,
+  whoami,
+} from '../hooks/lib/team.mjs';
+import { codeowners, decisionRecord, slugOf } from '../hooks/lib/teamfacts.mjs';
 import {
   APPROVAL_MINUTES,
   approvalLifetime,
@@ -101,7 +110,9 @@ const via = option('--via');
 const sessionId = option('--session');
 const minutesGiven = option('--minutes');
 const answerGiven = option('--answer');
-const FLAGS = ['--write', '--no-checks', '--json', '--delegated', '--person'];
+const leaseGiven = option('--lease');
+const touchesGiven = option('--touches');
+const FLAGS = ['--write', '--no-checks', '--json', '--delegated', '--person', '--fresh', '--peek'];
 const flag = (name) => args.includes(name);
 const writeBaseline = flag('--write');
 const [command, ...rest] = args.filter((a) => !FLAGS.includes(a));
@@ -148,6 +159,9 @@ function checkJson() {
   report.harnessSet = Object.keys(SETTINGS).filter((k) => settingOf(raw.harness, k) !== undefined);
   // Delegation is the base's, by the rules committed there: a branch can't grant itself merges.
   const delegation = mergeDelegation('.', config, file);
+  // TEAM-1: the team, with its defaults, and who the developer at this machine is.
+  report.team = teamOf(raw);
+  report.me = report.team ? whoami(resolve('.')) : null;
   report.delegatesMerge = delegation.delegated;
   report.firstMerge = delegation.first;
   out(JSON.stringify(report, null, 2));
@@ -164,6 +178,20 @@ function check() {
   for (const c of raw.checks ?? []) out(`Check ${c.name}: ${c.run.join(' && ')}`);
   if (!raw.docs?.specs) out('No docs.specs: lanes are not held to a spec-check report.');
   for (const name of load().config.adapters) out(`Adapter ${name}: active (see \`adapters\`)`);
+  const team = teamOf(raw);
+  if (team) {
+    const me = whoami(resolve('.'));
+    out(
+      `Team: ${team.techLead} is the tech lead; a claim is stale after ${team.staleDays} working day${team.staleDays === 1 ? '' : 's'} without a push; provider ${team.provider === 'github' ? 'GitHub' : team.provider.command}.`,
+    );
+    for (const [lane, owners] of Object.entries(team.owners))
+      out(`Lane ${lane} is owned by ${owners.join(', ')}`);
+    out(
+      me
+        ? `You are ${me}${me === team.techLead ? ', the tech lead' : ''}.`
+        : "You aren't signed in to GitHub (gh auth login), so claims and owners can't be checked.",
+    );
+  }
 }
 
 function who(paths) {
@@ -336,9 +364,82 @@ function configAt(ref) {
   return config ?? null;
 }
 
+/**
+ * SETUP-2: a project set up before setup committed its rules onto the base has none there, so nothing
+ * could be merged by the lead. `queue rules` commits the rules as committed on this branch (the ones the
+ * person approved) onto the base, as setup now does, without checking the base out: a commit of the base
+ * with those files changed, the base moved to it. Only while the base has no rules, and only the lead.
+ */
+function rulesOntoBase(root, config) {
+  const into = intoName ?? config.branches.protected[0];
+  const git = (args, opts = {}) =>
+    execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', ...opts }).trim();
+  const head = git(['rev-parse', '--abbrev-ref', 'HEAD']);
+  if (head === into)
+    die(
+      `You're on ${into}: commit ${file} here as setup does (\`git add ${file} && git commit\`), which the hooks allow while ${into} has no rules.`,
+    );
+  if (configAt(into))
+    return out(
+      `${into} already has code-kit's rules committed; the merge queue merges under them.`,
+    );
+  if (!configAt('HEAD'))
+    die(
+      `${head} has no ${file} committed. Commit the rules the person approved first, then run this again.`,
+    );
+  const used = git(['worktree', 'list', '--porcelain'])
+    .split('\n')
+    .some((l) => l === `branch refs/heads/${into}`);
+  if (used)
+    die(
+      `${into} is checked out in a worktree, so moving it here would leave that checkout behind. Commit ${file} in that checkout instead (the hooks allow it while ${into} has no rules).`,
+    );
+  // The rules, and the baseline of existing violations they were approved with.
+  const files = [file, BASELINE_FILE].filter((f) => {
+    try {
+      execFileSync('git', ['-C', root, 'cat-file', '-e', `HEAD:${f}`], { stdio: 'ignore' });
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  const index = join(tmpdir(), `code-kit-rules-${process.pid}`);
+  const env = { ...process.env, GIT_INDEX_FILE: index };
+  try {
+    git(['read-tree', into], { env });
+    for (const f of files)
+      git(
+        ['update-index', '--add', '--cacheinfo', `100644,${git(['rev-parse', `HEAD:${f}`])},${f}`],
+        {
+          env,
+        },
+      );
+    const tree = git(['write-tree'], { env });
+    const before = git(['rev-parse', into]);
+    const commit = git(
+      [
+        'commit-tree',
+        tree,
+        '-p',
+        before,
+        '-m',
+        `code-kit's rules onto ${into}, as the person approved them on ${head}\n\nFrom now on ${into}'s committed rules decide who merges into it.`,
+      ],
+      { env },
+    );
+    git(['update-ref', `refs/heads/${into}`, commit, before]);
+  } finally {
+    rmSync(index, { force: true });
+  }
+  const now = configAt(into);
+  out(
+    `Committed ${files.join(' and ')} onto ${into}, from ${head}. ${now?.approvals.delegate?.merge ? 'The lead merges the queue from now on (code-kit queue merge --delegated).' : `${into}'s rules don't delegate merges, so the person merges the queue.`}`,
+  );
+}
+
 /** Why the first merge into `into`, which has no config committed yet, is the person's. */
 const firstMerge = (into, branch) =>
-  `${into} has no ${file} committed yet, so it delegates nothing: the first merge, which brings code-kit's rules onto ${into}, is the person's. Ask them to merge ${branch} from the code-kit band (Merge), or to run \`! node "${process.argv[1]}" queue merge --person\`. From then on, ${into}'s committed rules decide who merges.`;
+  `${into} has no ${file} committed yet, so it delegates nothing. Put the approved rules onto it first: \`node "${process.argv[1]}" queue rules\`. Then merge ${branch} again; from then on ${into}'s committed rules decide who merges.`;
 
 /** Why a merge didn't happen: `refused` (the rules), `verify` (problems) or `conflict`. */
 class MergeStop extends Error {
@@ -474,6 +575,10 @@ function mergeOne(branch, config, byPerson) {
         'conflict',
       );
     }
+    // TEAM-1: a merged story's claim ends, whoever merged it.
+    const team = teamOf(config);
+    const story = storyOfBranch(branch);
+    if (team && story) teamProvider(resolve('.'), team).release(story, { merged: true });
     // A lane agent's worktree has done its work once its branch is merged: removed when it holds
     // nothing uncommitted (the branch stays), so finished lanes don't pile up checkouts.
     let removed = '';
@@ -527,6 +632,7 @@ function queue() {
     const place = waiting(readQueue(root)).length;
     return out(`Queued ${branch} to merge${place > 1 ? `, ${place - 1} ahead of it` : ', next'}.`);
   }
+  if (sub === 'rules') return rulesOntoBase(root, config);
   if (sub === 'merge') {
     const byPerson = mergeMode();
     const entries = readQueue(root);
@@ -561,7 +667,7 @@ function queue() {
   }
   if (sub !== undefined)
     die(
-      'code-kit queue [--json] | queue add <branch> | queue drop <branch> | queue merge --delegated|--person',
+      'code-kit queue [--json] | queue add <branch> | queue drop <branch> | queue rules | queue merge --delegated|--person',
     );
   const entries = readQueue(root);
   if (flag('--json')) return out(JSON.stringify(entries, null, 2));
@@ -577,6 +683,18 @@ function queue() {
  */
 function mapCommand(id) {
   const { config, raw } = load();
+  // MAP-5: the whole project, by folder, for when no story is at work.
+  if (id === PROJECT) {
+    const map = projectMap(resolve('.'), config, tracked());
+    if (flag('--json')) return out(JSON.stringify(map, null, 2));
+    out(`The whole project (${map.files.length} folder(s)):`);
+    for (const layer of map.layers) {
+      out(`  ${layer}`);
+      for (const f of map.files.filter((x) => x.layer === layer))
+        out(`    ${f.path} (${f.files})${f.imports.length ? `  → ${f.imports.join(', ')}` : ''}`);
+    }
+    return;
+  }
   const { specs, plan } = config.docs ?? {};
   if (!specs || !plan)
     die('map needs docs.specs and docs.plan in the config. The spec-design skill writes both.');
@@ -1135,6 +1253,230 @@ async function approve(given) {
   );
 }
 
+/** How long ago an ISO time was, in words: "3 hours ago". */
+function ago(iso) {
+  const minutes = Math.max(0, Math.round((Date.now() - Date.parse(iso)) / 60000));
+  if (minutes < 1) return 'just now';
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 48) return `${hours} hour${hours === 1 ? '' : 's'} ago`;
+  return `${Math.round(hours / 24)} days ago`;
+}
+
+/**
+ * The team (TEAM-2, TEAM-3, TEAM-8): `team` says who's on it and what's claimed, intended and open;
+ * `team claim <story> [--lease globs]` and `team release <story>` change a claim through the provider.
+ */
+function teamCommand() {
+  const { raw } = load();
+  const team = teamOf(raw);
+  if (!team)
+    die(
+      'This project has no "team" in its config, so it has no claims or owners. Add "team": { "techLead": "<GitHub handle>" } to share them.',
+    );
+  const provider = teamProvider(resolve('.'), team);
+  const [sub, story] = rest;
+  const holderWords = (h) =>
+    `${h.story} is claimed by ${h.by} (${ago(h.at)}). Ask them, or the tech lead (${team.techLead}), to release it.`;
+  if (sub === 'claim') {
+    if (!story) die('code-kit team claim <story> [--lease "<glob>,<glob>"]');
+    const lease = (leaseGiven ?? '')
+      .split(',')
+      .map((g) => g.trim())
+      .filter(Boolean);
+    const r = provider.claim(story, lease);
+    if (r.holder) die(holderWords(r.holder));
+    if (!r.ok) die(r.why);
+    return out(
+      `Claimed ${story} as ${r.claim.by}${lease.length ? `, leasing ${lease.join(', ')}` : ''}.`,
+    );
+  }
+  // TEAM-12: the plan mirrored onto the team's GitHub Project.
+  if (sub === 'board') {
+    if (!team.board)
+      die(
+        'This team has no board. Add "board": { "owner": "<user or organisation>", "number": <the Project\'s number> } to "team" in the config.',
+      );
+    const { config, raw: rawConfig } = load();
+    if (!rawConfig.docs?.plan)
+      die('The board mirrors the plan, and this project has no docs.plan.');
+    const status = buildStatus('.', config, base(config, false), tracked());
+    const state = provider.state();
+    const r = syncBoard(resolve('.'), team, status.stories, state.claims ?? []);
+    if (!r.ok) die(r.why);
+    return out(
+      `Board ${team.board.owner}/${team.board.number} synced: ${r.created} item${r.created === 1 ? '' : 's'} added, ${r.edited} field${r.edited === 1 ? '' : 's'} changed.`,
+    );
+  }
+  // TEAM-11: GitHub's CODEOWNERS from the config, so GitHub asks the right people to review.
+  if (sub === 'codeowners') {
+    const text = codeowners({
+      techLead: team.techLead,
+      leadPaths: raw.lead.paths,
+      lanes: raw.lanes,
+    });
+    if (!flag('--write')) return out(text.trimEnd());
+    mkdirSync(resolve('.github'), { recursive: true });
+    writeFileSync(resolve('.github/CODEOWNERS'), text);
+    return out(
+      "Wrote .github/CODEOWNERS. Commit it, and require code owners' review in a ruleset on the protected branch, so GitHub holds every pull request to it.",
+    );
+  }
+  // TEAM-9: the holder keeps a stale claim (the clock starts again); the tech lead reassigns one.
+  if (sub === 'keep') {
+    if (!story) die('code-kit team keep <story>');
+    const r = provider.claim(story);
+    if (r.holder) die(holderWords(r.holder));
+    if (!r.ok) die(r.why);
+    return out(
+      `Kept ${story}: it isn't stale until ${team.staleDays} more working day${team.staleDays === 1 ? '' : 's'} without a push.`,
+    );
+  }
+  if (sub === 'reassign') {
+    const to = rest[2];
+    if (!story || !to) die('code-kit team reassign <story> <GitHub handle>');
+    const r = provider.reassign(story, to);
+    if (!r.ok) die(r.why);
+    return out(`Reassigned ${story} from ${r.from} to ${r.to}, with its lease.`);
+  }
+  if (sub === 'release') {
+    if (!story) die('code-kit team release <story>');
+    const r = provider.release(story);
+    if (!r.ok) die(r.why ?? holderWords(r.holder));
+    return out(
+      r.released ? `Released ${story} (${r.claim.by}'s claim).` : `${story} isn't claimed.`,
+    );
+  }
+  // TEAM-6: what everyone did since you last looked; reading it marks it read, unless --peek.
+  if (sub === 'since') {
+    const root = resolve('.');
+    const seenFile = join(root, '.claude/state/team-seen.json');
+    let seen = null;
+    try {
+      seen = JSON.parse(readFileSync(seenFile, 'utf8'));
+    } catch {
+      // never looked: the last day
+    }
+    const from = seen ? Date.parse(seen.at) : Date.now() - 24 * 3600_000;
+    const state = provider.state({ fresh: true });
+    const activity = provider.since(from);
+    const changes =
+      seen && state.reachable !== false ? claimChanges(seen.claims, state.claims) : [];
+    const all = [...(activity ?? []), ...changes].sort((a, b) => a.at - b.at);
+    const people = {};
+    for (const e of all) (people[e.by] ??= []).push(e);
+    if (!flag('--peek')) {
+      mkdirSync(join(root, '.claude/state'), { recursive: true });
+      writeFileSync(
+        seenFile,
+        JSON.stringify({ at: new Date().toISOString(), claims: state.claims ?? [] }) + '\n',
+      );
+    }
+    if (flag('--json'))
+      return out(
+        JSON.stringify(
+          { since: new Date(from).toISOString(), github: activity !== null, people },
+          null,
+          2,
+        ),
+      );
+    out(
+      `Since ${seen ? ago(seen.at) : 'yesterday'}${activity === null ? " (GitHub's activity couldn't be read; claims only)" : ''}:`,
+    );
+    if (!all.length) return out('  Nothing new.');
+    for (const [who, list] of Object.entries(people))
+      out(`  ${who}${who === state.me ? ' (you)' : ''}: ${list.map((e) => e.text).join('; ')}.`);
+    return;
+  }
+  if (sub !== undefined)
+    die(
+      'code-kit team [--json] [--fresh] | team since [--json] [--peek] | team claim|keep|release <story> | team reassign <story> <handle>',
+    );
+  const state = provider.state({ fresh: flag('--fresh') });
+  if (flag('--json')) return out(JSON.stringify(state, null, 2));
+  const you = state.me
+    ? `You are ${state.me}${state.me === team.techLead ? ', the tech lead' : ''}.`
+    : "You aren't signed in to GitHub (gh auth login).";
+  out('Team mode is a preview: report anything that looks wrong.');
+  out(`Tech lead: ${team.techLead}. ${you}`);
+  if (state.reachable === false)
+    out(
+      `${state.why ?? "The shared repository can't be reached"}: claims and leases aren't checked until it can be; every other rule still holds.`,
+    );
+  if (state.github === false) out("GitHub's issues and pull requests couldn't be read (gh).");
+  for (const [lane, owners] of Object.entries(team.owners))
+    out(`Lane ${lane}: ${owners.join(', ')}`);
+  out(state.claims.length ? 'Claims:' : 'Nothing is claimed.');
+  for (const c of state.claims)
+    out(
+      `  ${c.story} by ${c.by}, ${ago(c.at)}${c.stale ? ` · stale, nothing since ${ago(c.active)}` : ''}${c.lease.length ? ` · leases ${c.lease.join(', ')}` : ''}`,
+    );
+  if (state.intents.length) out('Intents:');
+  for (const i of state.intents)
+    out(
+      `  #${i.id} ${i.about} (${i.by})${i.touches.length ? ` · touches ${i.touches.join(', ')}` : ''}`,
+    );
+  if (state.pulls.length) out('Open pull requests:');
+  for (const p of state.pulls)
+    out(`  #${p.number} ${p.title} (${p.by}, ${p.branch}${p.draft ? ', draft' : ''})`);
+}
+
+/**
+ * TEAM-5: `intend "<what and why>" [--touches globs]` raises an intent before any code, so the team sees
+ * a change of direction first; `intend agree|drop|duplicate <id> [--reason "…"]` is the tech lead's answer.
+ */
+function intendCommand() {
+  const { raw } = load();
+  const team = teamOf(raw);
+  if (!team) die('This project has no "team" in its config, so intents have nowhere to go.');
+  const provider = teamProvider(resolve('.'), team);
+  const [first, id] = rest;
+  // TEAM-10: an agreed intent, written where agents read it.
+  if (first === 'record') {
+    if (!/^\d+$/.test(id ?? '')) die('code-kit intend record <discussion number>');
+    const d = provider.intent(Number(id));
+    if (!d) die("GitHub can't be reached, so the intent can't be read.");
+    if (d.missing) die(`There's no intent #${id} in ${team.intents}.`);
+    if (!(d.closed && d.stateReason === 'RESOLVED'))
+      die(`Intent #${id} isn't agreed yet: only an agreed intent becomes a decision record.`);
+    const dir = raw.docs?.decisions ?? 'docs/decisions';
+    mkdirSync(resolve(dir), { recursive: true });
+    const existing = readdirSync(resolve(dir)).filter((f) => f.endsWith('.md'));
+    const already = existing.find((f) => read(join(dir, f)).includes(`**Discussion:** ${d.url}`));
+    if (already) return out(`Intent #${id} is already recorded: ${join(dir, already)}`);
+    const last = Math.max(0, ...existing.map((f) => Number(f.match(/^(\d+)-/)?.[1] ?? 0)));
+    const path = join(dir, `${String(last + 1).padStart(4, '0')}-${slugOf(d.title)}.md`);
+    writeFileSync(resolve(path), decisionRecord(d, team.techLead));
+    return out(
+      `Wrote ${path}. Commit it on a branch (lead/decision-${id}), push it and open a pull request, so it's reviewed and merged like any change; once merged, every agent reads it.`,
+    );
+  }
+  if (first === 'agree' || first === 'drop' || first === 'duplicate') {
+    if (!/^\d+$/.test(id ?? '')) die(`code-kit intend ${first} <issue number> [--reason "…"]`);
+    const outcome = { agree: 'agreed', drop: 'dropped', duplicate: 'duplicate' }[first];
+    const r = provider.settle(Number(id), outcome, reason ?? '');
+    if (!r.ok) die(r.why);
+    return out(
+      first === 'agree'
+        ? `Agreed intent #${id}: it's how the team goes now. Record it so every agent builds on it: code-kit intend record ${id}`
+        : first === 'drop'
+          ? `Dropped intent #${id}.`
+          : `Marked intent #${id} a duplicate.`,
+    );
+  }
+  const about = rest.join(' ').trim();
+  if (!about) die('code-kit intend "<what you\'ll change, and why>" [--touches "<glob>,<glob>"]');
+  const touches = (touchesGiven ?? '')
+    .split(',')
+    .map((t) => t.trim())
+    .filter(Boolean);
+  const r = provider.intend(about, touches);
+  if (!r.ok) die(r.why);
+  out(
+    `Raised intent #${r.intent.id}: ${about}${touches.length ? ` (touches ${touches.join(', ')})` : ''}. The team sees it now; the tech lead (${team.techLead}) agrees or drops it. ${r.intent.url}`,
+  );
+}
+
 /**
  * The lead loop's pause (LOOP-6): `loop` says whether the person paused it; `loop pause|resume`, the
  * person's act from the code-kit band, records it, so other tools' background work pauses with it.
@@ -1167,6 +1509,8 @@ const commands = {
   settings,
   hold: () => (rest.length === 1 ? hold(rest[0]) : usage()),
   queue,
+  team: teamCommand,
+  intend: intendCommand,
   story: () => (rest.length === 1 ? story(rest[0]) : usage()),
   map: () => (rest.length === 1 ? mapCommand(rest[0]) : usage()),
   trail: trailCommand,
@@ -1194,10 +1538,14 @@ function usage() {
       '              | stops [--session id] [--json] | sent-back <branch> [--reason "…"]\n' +
       '              | settings [--json] | settings set <key> <value> --reason "…" [--via pane]\n' +
       '              | hold <id> [--minutes N] | hold <id> --answer approved|refused\n' +
-      '              | queue [--json] | queue add|drop <branch> | queue merge --delegated|--person\n' +
+      '              | queue [--json] | queue add|drop <branch> | queue rules | queue merge --delegated|--person\n' +
       '              | loop [--json] | loop pause|resume\n' +
-      '              | map <story> [--json] | trail [--json] | journal [--json]\n' +
-      '              | story <id> [--json] | timeline [--json]',
+      '              | map <story>|project [--json] | trail [--json] | journal [--json]\n' +
+      '              | story <id> [--json] | timeline [--json]\n' +
+      '              | team [--json] [--fresh] | team since [--json] [--peek]\n' +
+      '              | team claim <story> [--lease globs] | team keep|release <story>\n' +
+      '              | team reassign <story> <handle> | team codeowners [--write] | team board\n' +
+      '              | intend "<what and why>" [--touches globs] | intend agree|drop|duplicate <id> [--reason "…"] | intend record <id>',
   );
 }
 await (commands[command] ?? usage)();

package/hooks/guard-bash.mjs

@@ -12,6 +12,8 @@ import { addedPackages, dependencyApproval, isDependencyFile } from './lib/depen
 import { CODE_KIT, GIT, codeOf, commandsOf, runs } from './lib/shell.mjs';
 import { block, start } from './lib/hook.mjs';
 import { CONFIG_FILE } from './lib/config.mjs';
+import { laneOfBranch, storyOfBranch, teamOf, teamProvider, whoami } from './lib/team.mjs';
+import { matchesAny } from './lib/glob.mjs';
 import { noteBefore } from './lane-audit.mjs';
 import {
   APPROVAL_LOG,
@@ -74,6 +76,7 @@ const packages = addedPackages(cmd);
 const approves = runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+approve\b`));
 const delegatedMerge = runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+(?:queue\s+)?merge\b`));
 const queues = runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+queue\s+(?:add|drop)\b`));
+const rulesOntoBase = runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+queue\s+rules\b`));
 const commits = runs(cmd, new RegExp(String.raw`^${GIT}commit\b`));
 if (error) {
   if (commits) block(`Blocked: ${error}\nFix the config before committing.`);
@@ -165,6 +168,16 @@ if (runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+loop\s+(pause|resume)\b`)))
   block(
     `Blocked: pausing or resuming the lead loop is the person's own act, from the code-kit band or their terminal. Ask them, and stop.\nCommand: ${cmd}`,
   );
+// TEAM-9: handing someone's claim to someone else is the tech lead's own decision too.
+if (runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+team\s+reassign\b`)))
+  block(
+    `Blocked: reassigning a claim is the tech lead's own decision, from their terminal or the code-kit pane. Tell them who holds it, since when, and who you'd suggest, and stop.\nCommand: ${cmd}`,
+  );
+// TEAM-5: agreeing or dropping an intent is the tech lead's own decision, from their terminal or the pane.
+if (runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+intend\s+(agree|drop|duplicate)\b`)))
+  block(
+    `Blocked: agreeing or dropping an intent is the tech lead's own decision, from their terminal or the code-kit pane. Tell them what you'd recommend and why, and stop.\nCommand: ${cmd}`,
+  );
 // The harness settings are the person's to change, from the pane or their terminal.
 if (runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+settings\s+set\b`)))
   block(
@@ -174,6 +187,10 @@ if (queues && actor.kind !== 'lead')
   block(
     `Blocked: only the lead puts branches in the merge queue, after its review passes them. Finish your story and commit it on your branch; the lead reviews it.\nCommand: ${cmd}`,
   );
+if (rulesOntoBase && actor.kind !== 'lead')
+  block(
+    `Blocked: only the lead puts code-kit's rules onto the protected branch. Finish your story and commit it on your branch; the lead takes it from there.\nCommand: ${cmd}`,
+  );
 if (delegatedMerge && actor.kind !== 'lead')
   block(
     `Blocked: only the lead merges into a protected branch. Finish your story and commit it on your branch; the lead reviews and merges it.\nCommand: ${cmd}`,
@@ -261,6 +278,58 @@ if (writesHistory && config.branches.protected.includes(branch) && !settingUp) {
   );
 }
 
+// TEAM-1, TEAM-4: in a team, making a story's branch claims the story (the dispatch), refused when the
+// lane is someone else's or the story is already claimed; a commit on it grows the claim's lease with
+// what the branch changes. When the shared repository can't be reached, nothing here is checked.
+const team = teamOf(config);
+if (team) {
+  const me = whoami(project);
+  const made = commandsOf(cmd)
+    .map((c) =>
+      c.text.match(
+        new RegExp(
+          String.raw`^${GIT}(?:switch\s+(?:-c|--create)|checkout\s+-b|worktree\s+add\b.*?\s-b)\s+(\S+)`,
+        ),
+      ),
+    )
+    .find(Boolean)?.[1];
+  const story = storyOfBranch(made);
+  if (story && me) {
+    const lane = laneOfBranch(made);
+    const owners = team.owners[lane];
+    if (owners && !owners.includes(me))
+      block(
+        `Blocked: the ${lane} lane is ${owners.join(' and ')}'s, so ${story} is theirs to dispatch. Leave it for them, or ask the tech lead (${team.techLead}) to change the lane's owners.\nCommand: ${cmd}`,
+      );
+    const claimed = teamProvider(project, team).claim(story);
+    if (claimed.holder)
+      block(
+        `Blocked: ${story} is already claimed by ${claimed.holder.by}, so someone is building it. Pick another story, or ask ${claimed.holder.by} or the tech lead (${team.techLead}) to release it.\nCommand: ${cmd}`,
+      );
+  }
+  // The branch by name, which also works before its first commit.
+  const named = spawnSync('git', ['-C', root, 'symbolic-ref', '--short', '-q', 'HEAD'], {
+    encoding: 'utf8',
+  }).stdout?.trim();
+  const mine = storyOfBranch(named || branch);
+  if (commits && mine && me) {
+    const provider = teamProvider(project, team);
+    const claim = provider.state().claims?.find((c) => c.story === mine && c.by === me);
+    const base = config.branches.protected[0];
+    const since = spawnSync('git', ['-C', root, 'merge-base', 'HEAD', base], { encoding: 'utf8' });
+    const changed = (args) =>
+      spawnSync('git', ['-C', root, 'diff', '--name-only', ...args], { encoding: 'utf8' })
+        .stdout.split('\n')
+        .filter(Boolean);
+    const files = [
+      ...(since.status === 0 ? changed([since.stdout.trim()]) : []),
+      ...changed(['--cached']),
+    ];
+    const grown = files.filter((f) => !matchesAny(f, claim?.lease ?? []));
+    if (claim && grown.length) provider.claim(mine, grown);
+  }
+}
+
 // Kit files edited through the shell follow the same rule as edits through Write/Edit: a command that
 // names a kit file and writes, judged one simple command at a time, so a redirect elsewhere in the line
 // (`npm install > /tmp/log; ls .claude/skills`) isn't taken for a write to the kit. A write the shell

package/hooks/guard-paths.mjs

@@ -8,6 +8,8 @@ import { loadBaseline, newProblems } from './lib/baseline.mjs';
 import { CONFIG_FILE } from './lib/config.mjs';
 import { layerProblems } from './lib/layers.mjs';
 import { block, start } from './lib/hook.mjs';
+import { teamOf, teamProvider, teamRefusal, whoami } from './lib/team.mjs';
+import { spawnSync } from 'node:child_process';
 import {
   actorFor,
   projectWorktrees,
@@ -35,6 +37,23 @@ if (error) {
 const problem = writeProblem(actorFor(input, root, config), rel, root, config);
 if (problem) block(`Blocked: ${problem}`);
 
+// TEAM-1, TEAM-4: in a team, the tech lead's paths, other people's lanes, claims and leases.
+const team = teamOf(config);
+if (team) {
+  const branch = spawnSync('git', ['-C', root, 'symbolic-ref', '--short', '-q', 'HEAD'], {
+    encoding: 'utf8',
+  }).stdout?.trim();
+  const refusal = teamRefusal({
+    actor: actorFor(input, root, config),
+    rel,
+    branch,
+    config,
+    me: whoami(project),
+    state: teamProvider(project, team).state(),
+  });
+  if (refusal) block(`Blocked: ${refusal}`);
+}
+
 /** The file's text after this call, when the call carries enough to know it. */
 function textAfter(before) {
   const ti = input.tool_input ?? {};

package/hooks/lib/adapters/context-graph.mjs

@@ -120,6 +120,11 @@ export default {
     /** The command that opens Context Graph's pane on a file, given its path. */
     open: { command: 'graph' },
   },
+  // ONB-3: set up before the coding loop, so every lane's first edit already has the why behind it.
+  onboard: {
+    skill: 'context-graph:init',
+    why: 'Context Graph is installed but has no graph in this project yet. Set it up before any code is written, so every lane works from the why behind each file from its first edit.',
+  },
   setup: [
     '.gitignore: .ctx/archive/, .ctx/bench/, .ctx/models/ and .ctx/serve.json (ctx working files, never committed)',
     '.gitattributes: .ctx/decisions.ctx merge=union and .ctx/cards.ctx merge=union (lanes record decisions and cards on parallel branches; merging keeps them all)',

package/hooks/lib/adapters/index.mjs

@@ -11,6 +11,8 @@
 //             shell.block (`person: true` marks a person's act the lead may do for them under
 //             approvals.lead); restricted: commands only the lead and the listed lanes may run
 //   setup     lines for init to apply or tell the person: ignore files, merge drivers, instructions
+//   onboard   { skill, why }: the tool's own setup skill, which `next` runs before any coding when the
+//             config wants the tool ("adapters": { "<name>": true }) but it isn't set up here yet
 //   facts     what the tool knows of the lanes' work, for the mod's combined view: { available(root),
 //             lanes(root, { session }) → { [agent type or 'lead']: { withoutUnderstanding, cardsOwed } },
 //             files(root, paths) → { [path]: { rules } }, open: { command } (its view of a file) }
@@ -40,6 +42,16 @@ export function adapterFacts(raw, root, { session = null, paths = null } = {}) {
     }));
 }
 
+/**
+ * ONB-3: tools the config wants (`"adapters": { "<name>": true }`) that aren't set up in `root` yet,
+ * with each one's setup skill: [{ name, skill, why }].
+ */
+export function pendingSetup(raw, root) {
+  return ADAPTERS.filter(
+    (a) => raw?.adapters?.[a.name] === true && a.onboard && !a.detect(root),
+  ).map((a) => ({ name: a.name, ...a.onboard }));
+}
+
 /** The effective config with every active adapter's contributions merged in. */
 export function applyAdapters(config, raw, root) {
   const active = activeAdapters(raw, root);

package/hooks/lib/config.mjs

@@ -3,6 +3,7 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { harnessProblems, harnessSettings } from './harness.mjs';
+import { teamProblems } from './team.mjs';
 import { join } from 'node:path';
 import { ADAPTERS, applyAdapters } from './adapters/index.mjs';
 
@@ -140,6 +141,13 @@ const isRegExp = (v) => {
   }
 };
 
+/**
+ * ONB-5: the version of init's setup. 2 adds project skills with the lane agents, the design gate for
+ * lanes with screens, a QA lane for end-to-end tests, and companions set up before coding (spec 17). A
+ * project set up before (no `setup`, or a lower one) is told what re-running init adds.
+ */
+export const SETUP_VERSION = 2;
+
 /** Every problem with a parsed config, as readable sentences; empty when it is valid. */
 export function validate(c) {
   if (!isObj(c)) return ['the config must be a JSON object'];
@@ -156,9 +164,14 @@ export function validate(c) {
     );
   };
   need(c.version === 1, '"version" must be 1');
+  need(
+    c.setup === undefined ||
+      (Number.isInteger(c.setup) && c.setup >= 1 && c.setup <= SETUP_VERSION),
+    `"setup" must be a whole number from 1 to ${SETUP_VERSION}: the version of init's setup the project has`,
+  );
   // A brownfield project may have no specs yet: then there is no spec-check gate.
   need(c.docs === undefined || isObj(c.docs), '"docs" must be an object');
-  for (const k of ['specs', 'principles', 'plan'])
+  for (const k of ['specs', 'principles', 'plan', 'decisions'])
     need(c.docs?.[k] === undefined || isStr(c.docs[k]), `"docs.${k}" must be a path`);
   need(isObj(c.lead) && isList(c.lead?.paths), '"lead.paths" must be a list of globs');
   need(
@@ -232,6 +245,7 @@ export function validate(c) {
     '"branches.protected" must be a list of branch names',
   );
   p.push(...harnessProblems(c.harness));
+  p.push(...teamProblems(c));
   return p;
 }