@warren-dean/code-kit 0.19.0 → 0.20.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "code-kit",
       "source": "./",
       "description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
-      "version": "0.19.0",
+      "version": "0.20.0",
       "category": "development",
       "tags": ["guardrails", "architecture", "lanes", "layers", "spec-driven", "ci", "multi-agent"],
       "license": "MIT"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "code-kit",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
   "author": {
     "name": "Warren Langeveldt"

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 What changed in each release of code-kit, newest first. Versions follow the plugin manifest and the npm package `@warren-dean/code-kit`. Each release is also on [GitHub Releases](https://github.com/warrendeanlangeveldt/code-kit/releases).
 
+## 0.20.0 (2026-10-21)
+
+A team provider can now receive a report of a project's facts, and a hosted provider's adapter is in preview.
+
+- A team provider can receive a report of the project: each story's stage and when it changed, milestones and their targets, send-backs, the requirement trail, approvals, token use by kind of agent, and the project's rules. A report never holds code, diffs or prompts; its fields are a fixed list, and anything else is refused before it's sent. With GitHub as the provider, nothing is sent anywhere.
+- `code-kit team report --dry-run` shows exactly what would be sent, and `team.report: false` turns reports off.
+- A milestone in the plan can have a target date: `**Target:** 2026-11-30` under its heading.
+- A hosted provider's adapter is in preview. It runs only for a project whose config names one, connects through code-kit's own hooks with GitHub as its fallback, and doesn't need a Discussions category for intents.
+- A decision record now names whoever agreed the intent, not always the tech lead.
+
 ## 0.19.0 (2026-10-19)
 
 A build uses far fewer tokens. In two days of two builds, output was under 1% of the tokens: nearly all of it was agents rereading large contexts on every request.

package/README.md

@@ -468,6 +468,9 @@ code-kit team claim <story> [--lease globs] | team release <story>   # claim a s
 code-kit team keep <story> | team reassign <story> <handle>   # keep your stale claim (its clock starts again); the tech lead hands a claim to someone else
 code-kit team codeowners [--write]                            # .github/CODEOWNERS from the config: the tech lead for their paths, each lane's owners for its paths
 code-kit team board                                           # mirror the plan onto the team's GitHub Project: each story with Lane, Claimed by, Stale and State
+code-kit team report [--dry-run] [--json]                     # report the project's facts to the team provider; --dry-run prints exactly what would be sent (spec 21)
+code-kit team provider signin|signout|status|connect          # a hosted team provider the config names (preview): sign this machine in, connect the repository
+code-kit team pulse --session <id>                            # used by the mod with a hosted provider: the session's agents and token use, on stdin, and the report when something changed
 code-kit intend "<what and why>" [--touches globs]            # raise a change of direction before any code, as a discussion in the repository's Intents category
 code-kit intend agree|drop|duplicate <id> [--reason "…"]     # the tech lead's answer, from their terminal or the pane
 code-kit intend record <id>                                   # write an agreed intent as a numbered decision record in docs.decisions, for a pull request
@@ -508,7 +511,7 @@ code-kit approve <name>... --reason "…" [--lane name] [--delegated [--story ST
 | `approvals.lead`               | no                | `true` lets the lead act on what the person says in chat, for when `!` isn't available (on a phone, say): it records their approvals with `code-kit approve`, and runs `shell.block` commands marked `person`. Default `false`. See [Approvals](#approvals).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `approvals.delegate`           | no                | `{ protected?: [approval names], merge?: true, dependencies?: { licences?, minWeeklyDownloads?, maxMonthsSinceRelease?, allowInstallScripts?: true \| false \| [kinds] } }`: what the lead decides, inside the guardrails you keep: the protected approvals it grants, and packages it approves for a story, with `code-kit approve --delegated`; with `merge`, merges into a protected branch with `code-kit merge --delegated`. Lanes ask the lead for these, never you. npm packages are also checked against the registry; the defaults are MIT, Apache-2.0, BSD and ISC, 10,000 weekly downloads, a release within 18 months, and no install scripts. See [Approvals](#approvals).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `setup`                        | no                | The version of init's setup the project has (3 now). Without it, or lower, `next` names what the project is missing (the design gate, design stories before screens, a QA lane, a security reviewer) and starts no new story until re-running init adds it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `team`                         | no                | Preview. For several people in one repository: `{ techLead, staleDays?, intents?, board?, provider? }`. `techLead` is the GitHub handle of the person who owns the plan, specs and contracts; `staleDays` is how many working days without a push make a claim stale (default 3); `intents` is the discussion category intents go in (default `Intents`; create it once in the repository's Settings › Discussions); `board` is `{ owner, number }`, a GitHub Project the plan is mirrored onto; `provider` is `"github"` (default) or `{ command, fallback? }` for another team provider, such as the code-kit teams hub; with `fallback: "github"`, claims go through GitHub whenever that provider can't be reached. See docs/specs/16-teams.md.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `team`                         | no                | Preview. For several people in one repository: `{ techLead, staleDays?, intents?, board?, provider?, report? }`. `techLead` is the GitHub handle of the person who owns the plan, specs and contracts; `staleDays` is how many working days without a push make a claim stale (default 3); `intents` is the discussion category intents go in (default `Intents`; create it once in the repository's Settings › Discussions); `board` is `{ owner, number }`, a GitHub Project the plan is mirrored onto; `provider` is `"github"` (default), `{ command, fallback? }` for another team provider, or, in preview, a hosted provider's adapter as `{ "<name>": "<https address>" }`, which keeps the intents (Discussions only when `intents` is set) and has GitHub as its fallback; with `fallback: "github"`, claims go through GitHub whenever that provider can't be reached; `report` (default true) is whether the project reports its facts (stories' stages, send-backs, the requirement trail, approvals, token use and the rules; never code) to a provider that isn't GitHub. See docs/specs/16-teams.md and docs/specs/21-hub-adapter-and-reports.md.                                                                                                           |
 | `branches.protected`           | no                | Default `["main", "master"]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `harness`                      | no                | What the mod's harness does in the session: `autonomy` (`autonomous`, `propose` or `off`; default `autonomous`), `hold.minutes` (how long a call waiting on your approval is held, 0 to 10; default 2), `stall.nudgeMinutes` and `stall.restartMinutes` (default 5 and 10), `stall.maxRestarts` (default 2), `agents.reviewer.on` (default `false`) and `agents.reviewer.model` (code-kit's reviewer and the security reviewer; default `sonnet`), `agents.lanes.model` (the model each lane agent starts on, unless the lead's call or the lane's agent file names one; default the session's), `background.pauseAtPercent` (default 80), `compact.at` (compact the lead's context between turns once it's past this share of its window; default 40, 0 for never), `compact.milestone` (when a milestone finishes, compact the lead's context: `ask`, `auto` or `off`; default `ask`), `agents.lanes.contextLimit` (the context a lane agent may reach before it hands its story to a fresh agent; default 250,000 tokens), `notify.on` (a system notification when something new needs you; default `true`) and `report.on` (agents draft bug reports for code-kit, which you send or discard; default `false`). Change them with `/harness` or `code-kit settings set`. |
 

package/bin/code-kit.mjs

@@ -57,7 +57,20 @@ import {
 } from '../hooks/lib/config.mjs';
 import { diffConfigs, ownershipMoves } from '../hooks/lib/diff.mjs';
 import { CODE, importsOf, layerOf, layerProblems, targetOf } from '../hooks/lib/layers.mjs';
-import { ADAPTERS, activeAdapters, adapterFacts } from '../hooks/lib/adapters/index.mjs';
+import {
+  ADAPTERS,
+  activeAdapters,
+  adapterFacts,
+  providerAdapterOf,
+} from '../hooks/lib/adapters/index.mjs';
+import {
+  EVENT_PARTS,
+  USAGE_DIR,
+  buildSnapshot,
+  mainCheckout,
+  snapshotHash,
+  snapshotProblems,
+} from '../hooks/lib/snapshot.mjs';
 import { nextStep } from '../hooks/lib/next.mjs';
 import { discardReport, draftReport, readReports, sendReport } from '../hooks/lib/report.mjs';
 import {
@@ -92,6 +105,7 @@ import {
   claimChanges,
   storyOfBranch,
   syncBoard,
+  readCache,
   teamOf,
   teamProvider,
   whoami,
@@ -172,6 +186,7 @@ const FLAGS = [
   '--off',
   '--blocks',
   '--take',
+  '--dry-run',
 ];
 const flag = (name) => args.includes(name);
 const writeBaseline = flag('--write');
@@ -242,7 +257,7 @@ function check() {
   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}.`,
+      `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.name ?? team.provider.command)}.`,
     );
     for (const [lane, owners] of Object.entries(team.owners))
       out(`Lane ${lane} is owned by ${owners.join(', ')}`);
@@ -1461,8 +1476,12 @@ function teamCommand() {
     die(
       'This project has no "team" in its config, so it has no claims or owners. Add "team": { "techLead": "<GitHub handle>" } to share them.',
     );
+  // HUBR-6: a hosted provider's own commands (sign in, connect, status), through its adapter.
+  if (rest[0] === 'provider') return providerCommand(raw);
   const provider = teamProvider(resolve('.'), team);
   const [sub, story] = rest;
+  if (sub === 'report') return teamReport(team, provider);
+  if (sub === 'pulse') return pulseCommand(raw, team, provider);
   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') {
@@ -1577,7 +1596,7 @@ function teamCommand() {
   }
   if (sub !== undefined)
     die(
-      'code-kit team [--json] [--fresh] | team init … | team since [--json] [--peek] | team claim|keep|release <story> | team reassign <story> <handle>',
+      'code-kit team [--json] [--fresh] | team init … | team since [--json] [--peek] | team claim|keep|release <story> | team reassign <story> <handle> | team report [--dry-run] [--json]',
     );
   const state = provider.state({ fresh: flag('--fresh') });
   if (flag('--json')) return out(JSON.stringify(state, null, 2));
@@ -1608,6 +1627,128 @@ function teamCommand() {
     out(`  #${p.number} ${p.title} (${p.by}, ${p.branch}${p.draft ? ', draft' : ''})`);
 }
 
+// --- what a project reports (docs/specs/21-hub-adapter-and-reports.md) ----------------------------
+
+const REPORT_SENT = '.claude/state/report-sent.json';
+const REPORT_MINUTES = 10;
+
+/** HUBR-2: the snapshot, from what status, timeline, trail, the journal and the config already know. */
+function snapshotNow(team) {
+  const { config } = load();
+  if (!config.docs?.specs || !config.docs?.plan) return null;
+  const from = base(config, false);
+  const status = buildStatus('.', config, from, tracked());
+  const claims = (readCache(resolve('.')) ?? {}).claims ?? [];
+  return buildSnapshot({
+    root: resolve('.'),
+    config,
+    status,
+    base: from,
+    claims,
+    version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version,
+  });
+}
+
+/**
+ * HUBR-3: sends the snapshot when what happened changed (stages, approvals, send-backs, merges), or when
+ * only usage changed and ten minutes have passed; never the same snapshot twice. A provider that can't
+ * be reached is tried again with the next change. `{ sent, why }`.
+ */
+function sendSnapshot(team, provider, snapshot, { force = false } = {}) {
+  if (team.provider === 'github') return { sent: false, why: 'GitHub keeps no reports.' };
+  if (!team.report) return { sent: false, why: 'team.report is false.' };
+  const problems = snapshotProblems(snapshot);
+  if (problems.length) return { sent: false, why: `The report isn't valid: ${problems[0]}.` };
+  const file = join(mainCheckout(resolve('.')), REPORT_SENT);
+  let last = {};
+  try {
+    last = JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    // nothing sent yet
+  }
+  const events = snapshotHash(snapshot, EVENT_PARTS);
+  const all = snapshotHash(snapshot);
+  const due =
+    force ||
+    events !== last.events ||
+    (all !== last.all && Date.now() - (last.at ?? 0) >= REPORT_MINUTES * 60_000);
+  if (!due) return { sent: false, why: 'Nothing new to report.' };
+  const r = provider.report(snapshot);
+  if (!r || r.ok === false)
+    return { sent: false, why: r?.why ?? 'The provider refused the report.' };
+  mkdirSync(join(mainCheckout(resolve('.')), '.claude/state'), { recursive: true });
+  writeFileSync(file, `${JSON.stringify({ events, all, at: Date.now() })}\n`);
+  return { sent: true };
+}
+
+/** HUBR-2, HUBR-4: `team report` sends what's new; `--dry-run` prints exactly what would be sent. */
+function teamReport(team, provider) {
+  const snapshot = snapshotNow(team);
+  if (!snapshot)
+    die(
+      'A report needs docs.specs and docs.plan in the config. The spec-design skill writes both.',
+    );
+  if (flag('--dry-run')) return out(JSON.stringify(snapshot, null, 2));
+  const r = sendSnapshot(team, provider, snapshot, { force: true });
+  if (flag('--json')) return out(JSON.stringify(r, null, 2));
+  out(
+    r.sent
+      ? `Reported this project's facts to ${team.provider.name ?? 'the team provider'}.`
+      : r.why,
+  );
+}
+
+/**
+ * The mod's pulse (HUBR-3, HUBR-6), every 30 seconds while a session runs, only for a hosted provider:
+ * stdin is `{ agents, usage }`, the session's agents by tool and branch and its token ledger (USE-1).
+ * Keeps both for the provider's client and the report, and reports when something new happened.
+ */
+async function pulseCommand(raw, team, provider) {
+  const hosted = providerAdapterOf(raw.team?.provider);
+  if (!hosted || hosted.problem || !sessionId) return;
+  let input = {};
+  try {
+    let raw = '';
+    for await (const chunk of process.stdin) raw += chunk;
+    input = raw.trim() ? JSON.parse(raw) : {};
+  } catch {
+    input = {};
+  }
+  const root = resolve('.');
+  const id = sessionId.replace(/[^\w-]/g, '');
+  if (input.agents) hosted.adapter.presence(root, id, input.agents);
+  if (input.usage && typeof input.usage === 'object') {
+    const dir = join(mainCheckout(root), USAGE_DIR);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      join(dir, `${id}.json`),
+      `${JSON.stringify({ at: Date.now(), entries: input.usage })}\n`,
+    );
+  }
+  // Building the snapshot reads git: at most once a minute.
+  const built = join(mainCheckout(root), '.claude/state/report-built.json');
+  let at = 0;
+  try {
+    at = JSON.parse(readFileSync(built, 'utf8')).at ?? 0;
+  } catch {
+    // never built
+  }
+  if (Date.now() - at < 60_000) return;
+  writeFileSync(built, `${JSON.stringify({ at: Date.now() })}\n`);
+  const snapshot = snapshotNow(team);
+  if (snapshot) sendSnapshot(team, provider, snapshot);
+}
+
+/** HUBR-6: `team provider signin|signout|status|connect|drift-model …`, run by the provider's client. */
+function providerCommand(raw) {
+  const hosted = providerAdapterOf(raw.team?.provider);
+  if (!hosted || hosted.problem)
+    die(
+      "This team's provider isn't a hosted one: claims and intents go through GitHub, and there's nothing to sign in to.",
+    );
+  process.exit(hosted.adapter.run(rest.slice(1), hosted.url));
+}
+
 /**
  * TEAM-13: `team init` sets the project up as a team's, or (`--off`) as one developer's again. Without
  * `--write` it shows the team section it would write; with it, it writes the config and says what the
@@ -1671,7 +1812,7 @@ function teamInit(raw) {
   if (flag('--json'))
     return out(JSON.stringify({ written: true, ...section, me: state.me ?? null, setup }, null, 2));
   out(
-    `Wrote the team to ${file}: ${team.techLead} is the tech lead; a claim is stale after ${team.staleDays} working day${team.staleDays === 1 ? '' : 's'} without a push; intents go in "${team.intents}".`,
+    `Wrote the team to ${file}: ${team.techLead} is the tech lead; a claim is stale after ${team.staleDays} working day${team.staleDays === 1 ? '' : 's'} without a push; ${team.intents ? `intents go in "${team.intents}"` : `${team.provider.name ?? 'the provider'} keeps intents`}.`,
   );
   for (const [lane, owners] of Object.entries(team.owners))
     out(`Lane ${lane}: ${owners.join(', ')}`);

package/hooks/hooks.json

@@ -46,6 +46,28 @@
         ]
       }
     ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/team-session.mjs\" start",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/team-session.mjs\" end",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "hooks": [