@warren-dean/code-kit 0.18.0 → 0.20.0

package/hooks/mod/view.mjs

@@ -1676,6 +1676,42 @@ export function withUsage(ledger, who, usage) {
   };
 }
 
+/**
+ * HUBR-2: the ledger as a report carries it: [{ story, kind, input, output, cache }], each entry's kind
+ * (lead, lane, reviewer, security-reviewer or background) from who made it and `typeOf(key)`, the agent's
+ * type. Tokens only: no prompt, no message.
+ */
+export function usageForReport(ledger, typeOf = () => null) {
+  return Object.fromEntries(
+    Object.entries(ledger).map(([id, e]) => {
+      const type = e.key === 'lead' ? null : typeOf(e.key);
+      const kind =
+        e.key === 'lead'
+          ? 'lead'
+          : e.lane
+            ? 'lane'
+            : type === 'security-reviewer'
+              ? 'security-reviewer'
+              : /(^|:)reviewer$/.test(type ?? '')
+                ? 'reviewer'
+                : 'background';
+      return [
+        id,
+        { story: e.story ?? null, kind, input: e.input, output: e.output, cache: e.cache },
+      ];
+    }),
+  );
+}
+
+/**
+ * HUBR-6: an agent's presence, by tool name and the branch its lane works on (never what it reads or
+ * writes): { type, tool, branch, at }.
+ */
+export function presenceOf({ agentId, type, tool, lane, lanes, at }) {
+  const branch = lane ? (lanes?.find((l) => l.name === lane)?.branch ?? null) : null;
+  return { type: agentId ? (type ?? null) : 'lead', tool: tool ?? null, branch, at };
+}
+
 const total = (e) => e.input + e.output + e.cache;
 const median = (xs) => {
   const s = [...xs].sort((a, b) => a - b);

package/hooks/team-session.mjs

@@ -0,0 +1,57 @@
+// SessionStart and SessionEnd (code-kit spec 21, HUBR-6): when the team's provider is a hosted one, its
+// adapter holds the session's live link (the event stream and the team's state on disk) from start to
+// end, and the session reports the project's facts once as it starts (HUBR-3). Nothing happens in a
+// project whose team works through GitHub, or that has no team.
+import { execFileSync, spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { providerAdapterOf } from './lib/adapters/index.mjs';
+
+let input = {};
+try {
+  input = JSON.parse(readFileSync(0, 'utf8') || '{}');
+} catch {
+  // no input: nothing to start
+}
+const root = process.env.CLAUDE_PROJECT_DIR ?? input.cwd ?? process.cwd();
+const session = String(input.session_id ?? 'session').replace(/[^\w-]/g, '');
+let raw = null;
+try {
+  raw = JSON.parse(readFileSync(join(root, '.claude', 'code-kit.json'), 'utf8'));
+} catch {
+  // not a code-kit project
+}
+const hosted = providerAdapterOf(raw?.team?.provider);
+if (hosted && !hosted.problem) {
+  const { adapter, url } = hosted;
+  if (process.argv[2] === 'start') {
+    // The link lives as long as the Claude Code process that started this hook.
+    let watch = process.ppid;
+    try {
+      watch =
+        Number(
+          execFileSync('ps', ['-o', 'ppid=', '-p', String(process.ppid)], {
+            encoding: 'utf8',
+          }).trim(),
+        ) || process.ppid;
+    } catch {
+      // the hook's own parent, then
+    }
+    adapter.session.start(root, session, watch, url);
+    // The project's facts as the session starts, in the background: the session doesn't wait on it.
+    if (raw.team.report !== false)
+      spawn(
+        process.execPath,
+        [
+          join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'code-kit.mjs'),
+          'team',
+          'pulse',
+          '--session',
+          session,
+        ],
+        { cwd: root, detached: true, stdio: 'ignore' },
+      ).unref();
+  }
+  if (process.argv[2] === 'end') adapter.session.end(root, session);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warren-dean/code-kit",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Keeps AI coding agents inside your project's rules: lanes, layer rules, protected paths and proof before finish, enforced by Claude Code hooks and in CI",
   "license": "MIT",
   "author": "Warren Langeveldt",

package/skills/dispatch/SKILL.md

@@ -48,6 +48,8 @@ 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.
 
+One agent per story: never send a running lane agent a second story, or a send-back. A story that goes on (sent back, or handed back at its context limit) gets a fresh agent: first run `node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" worktrees release <branch>`, which keeps the branch's commits and moves its report to the main checkout, then start the agent as below with the brief and "Read your earlier report first: `.claude/state/reports/<branch with / as _>.md` in the main checkout". A long-lived agent rereads its whole context on every step, which is most of what a build costs.
+
 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/review/SKILL.md

@@ -38,7 +38,7 @@ Any problem it reports means the branch goes back. Don't fix a lane's code yours
 
 ## 3. Check the work against the story
 
-Read the story, every requirement it cites, and the full diff (`git diff <base>...<branch>`). Read each changed file in full where the diff alone doesn't show the behaviour. Then, for each requirement:
+Read the story and every requirement it cites. Then start from what's already been worked out, not the whole diff: the lane's report (`.claude/state/reports/<branch with / as _>.md`, in its worktree or the main checkout), the reviewer's findings when the background reviewer ran, and `git diff --stat <base>...<branch>`. Open the diff one file at a time (`git diff <base>...<branch> -- <file>`) for the files each requirement depends on and the files a finding names, and a changed file in full only where its diff doesn't show the behaviour. Everything you open stays in your context for the rest of the build, so open what the verdict needs. Then, for each requirement:
 
 | Requirement | Acceptance criterion | Built (where) | Test (which) | Verdict |
 | ----------- | -------------------- | ------------- | ------------ | ------- |
@@ -84,7 +84,7 @@ Report the table, `verify`'s result, the security review's findings (or that non
   node "${CLAUDE_PLUGIN_ROOT}/bin/code-kit.mjs" sent-back <branch> --reason "<the problems, in one line>"
   ```
 
-  Send the list to the same lane agent if it's still running (SendMessage), or dispatch the story again with the list added to the brief. Set the story's status to `in progress`.
+  Dispatch the story again to a fresh agent with the list added to the brief (`/code-kit:dispatch`, which first releases the branch's worktree), never to the agent that built it: its context is already large. Set the story's status to `in progress`.
 
 - **Ask the person.** When the right answer is a product or scope decision (the spec is silent, or the lane found a real conflict), put the question to the person with your recommendation. Don't merge around it.
 

package/skills/spec-check/SKILL.md

@@ -12,7 +12,7 @@ The project's specs are in the folder named by `docs.specs` in `.claude/code-kit
 1. **Find the section.** The task should name its requirement IDs (`BOOK-4`, headings in the specs) or a spec section. If it doesn't, search the specs folder for the domain nouns. Read the whole section, not just the matching lines, plus every section it references.
 2. **Read the principles.** Re-read the parts of `docs.principles` that apply: layers, ports and providers, events, testing and the rules for agents. Note this lane's layer rules from `layers` in the config.
 3. **Make a checklist.** One line per requirement: behaviour, fields, error cases, permissions, states, tests.
-4. **Compare with the code.** For each line, search for where it's implemented, then read those files in full.
+4. **Compare with the code.** For each line, search for where it's implemented, then read what implements it: the functions and types the requirement touches, not every file around them.
 5. **Report** as a table:
 
 | Requirement | Status (done / partial / missing / conflicts) | Where | Note |

package/skills/team-init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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), offers CODEOWNERS and the Project board, and connects a hosted team provider only when the config already names one. 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
@@ -25,7 +25,7 @@ Ask only what the config can't answer, with the current value as the default on
 - **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`).
+- **Intents category:** the GitHub Discussions category intents go in (default `Intents`). Skip it when the config's `team.provider` names a hosted provider (`{ "<name>": "<https address>" }`) and `team.intents` isn't set: that provider keeps the 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
@@ -48,7 +48,7 @@ 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.
+- **A hosted team provider, only when the config already names one:** hosted providers are in preview, so never offer or suggest one. When `team.provider` is `{ "<name>": "<https address>" }` (set by hand), connect this machine: run `team provider status`; if it isn't signed in, run `team provider signin` in the background, give the person the code and the GitHub address it prints, and wait (they enter the code in their browser; never ask for a password or token); then `team provider connect`, which checks the provider can see the repository and adds its MCP server to `.mcp.json`. Commit `.mcp.json` with the config.
 
 ## 5. Finish
 

package/templates/agent.md

@@ -19,7 +19,7 @@ Always:
 
 - Work on the branch the brief names (`<lane>/st-<n>`). Start every task with the spec-check skill and save its report to .claude/state/spec-check/<branch>.md; the path guard blocks code until it exists.
 - Follow `{{docs.principles}}`, including the rules for AI agents. Hooks enforce ownership, layers and the project's checks; if one blocks you, fix the cause, never work around it.
-- Read every file you change in full, plus its imports and its callers.
+- Read every file you change in full. Of what it imports and what calls it, read what your change needs: the definitions it uses and the call sites it changes. A context tool's fresh card for a file stands for reading it whole; read the source where the card is missing, stale or not enough.
 - Search before you build; reuse existing services, providers, components and schemas.
 - Write only in your owned paths. For anything else, write a short change request for the lead and stop.
 - You answer to the lead, never the person. A question the spec doesn't settle (a product choice, UX the spec is silent on, an account): write it for the lead, with the choices and what each does, and carry on with what doesn't depend on it, or stop. The lead decides, or asks the person.
@@ -28,7 +28,9 @@ Always:
 - Prove each acceptance criterion with a test whose title names the requirement ID, e.g. `BOOK-4 …`.
 - Fixing a bug: first write a test that fails because of the bug, through the code that's already there, then fix it. `verify` runs your test without the fix, and it must fail on an assertion, not because it calls something the fix adds.
 - Never weaken a test to get to green: no deleting, skipping or focusing tests, cutting cases or assertions, or rewriting snapshots. The commit is refused without the person's approval. Fix the code; if the test itself is wrong, say why in a change request for the lead.
+- Run the narrowest tests that prove each step, with failures only in the output (a quiet reporter, or `| tail -40` on failure); run the full suite once, before you commit. Long output stays in your context and is paid for on every step after it.
 - Commit your work on your branch before finishing; the stop hook runs the checks and requires it.
 - Don't message the lead while you work: it hears from you once, when you finish. If you're blocked on something only the lead or the person can settle, finish and say so.
+- One story per agent. If you're asked to wrap up because your context is large, finish the step you're on, commit, write your report and hand back: a fresh agent carries the story on from your report.
 - Before you finish, write your full report to `.claude/state/reports/<branch>.md` (the branch with `/` as `_`, as for spec-check): what you did and why, the spec section, the commands you ran with their output, what's left, and anything you need decided, with the choices and any text you'd otherwise paste. The stop hook requires it.
 - Finish with a short hand-back, at most ten lines: the story and branch, done or blocked, any decision the lead must make, and the report's path. No output or code in it: the lead reads the report when it reviews.