@warren-dean/code-kit 0.19.0 → 0.20.0

package/hooks/lib/adapters/hub/index.mjs

@@ -0,0 +1,25 @@
+// code-kit hub as a team provider adapter (code-kit spec 21, HUBR-6): chosen by
+// `"team": { "provider": { "hub": "<https address>" } }`, with GitHub as its fallback. Its client
+// (client.mjs) is code-kit's provider command, the session's live link (the event stream and the team's
+// state on disk) and the person's sign-in. In preview (HUBR-8): nothing outside this folder names it,
+// and code-kit only says its name for a project whose config does.
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { recordPresence, startDaemon, stopDaemon } from './client.mjs';
+
+const CLIENT = join(dirname(fileURLToPath(import.meta.url)), 'client.mjs');
+const quoted = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+
+export default {
+  key: 'hub',
+  label: 'code-kit hub',
+  command: (url) => `node ${quoted(CLIENT)} --url ${quoted(url)}`,
+  session: {
+    start: (root, session, watch, url) => startDaemon(root, session, watch, url),
+    end: (root, session) => stopDaemon(root, session),
+  },
+  presence: (root, session, agents) => recordPresence(root, session, agents),
+  run: (args, url) =>
+    spawnSync(process.execPath, [CLIENT, '--url', url, ...args], { stdio: 'inherit' }).status ?? 1,
+};

package/hooks/lib/adapters/index.mjs

@@ -18,9 +18,44 @@
 //             files(root, paths) → { [path]: { rules } }, open: { command } (its view of a file) }
 //
 // The core only ever calls applyAdapters() and activeAdapters(); it never names a tool.
+//
+// Team provider adapters (HUBR-6) are the other kind: a hosted team provider's client, chosen when the
+// config's `team.provider` names it, as `{ "<key>": "<its https address>" }`. Each says:
+//
+//   key       the provider's key in `team.provider`
+//   label     what code-kit calls it, only when a config names it (HUBR-8)
+//   command   (url) => the provider command code-kit runs for each operation (TEAM-2)
+//   session   { start(root, session, watch, url), end(root, session) }: the session's live link
+//   presence  (root, session, agents) => void: the session's agents, for the provider
+//   run       (args, url) => exit code: the client's own commands (sign in, connect, status), for
+//             `code-kit team provider …`
+//
+// The core only ever calls providerAdapterOf(); it never names a provider.
 import contextGraph from './context-graph.mjs';
+import hub from './hub/index.mjs';
 
 export const ADAPTERS = [contextGraph];
+export const PROVIDERS = [hub];
+
+const isAddress = (v) => typeof v === 'string' && /^https?:\/\/[^\s]+$/.test(v);
+
+/**
+ * The team provider adapter `team.provider` names, with its address: { adapter, url }, or null when the
+ * provider isn't an adapter's (GitHub, or a command). `{ problem }` when it names one wrongly.
+ */
+export function providerAdapterOf(provider) {
+  if (provider === null || typeof provider !== 'object' || Array.isArray(provider)) return null;
+  const adapter = PROVIDERS.find((p) => p.key in provider);
+  if (!adapter) return null;
+  const extra = Object.keys(provider).filter((k) => k !== adapter.key && k !== 'fallback');
+  if (
+    !isAddress(provider[adapter.key]) ||
+    extra.length ||
+    ![undefined, 'github'].includes(provider.fallback)
+  )
+    return { problem: true };
+  return { adapter, url: provider[adapter.key].replace(/\/$/, '') };
+}
 
 /** Adapters detected in `root` and not switched off by the config's `adapters` map. */
 export function activeAdapters(raw, root) {

package/hooks/lib/plan.mjs

@@ -86,6 +86,30 @@ export function readStories(root, planPath) {
   return stories;
 }
 
+/**
+ * HUBR-5: each milestone in the plan, in order: [{ name, target }], `name` the `## ` heading a story sits
+ * under, `target` the date a `**Target:** YYYY-MM-DD` line under that heading gives, before its first
+ * story, or null.
+ */
+export function readMilestones(root, planPath) {
+  const found = [];
+  for (const file of markdownFiles(root, planPath)) {
+    let current = null;
+    for (const line of readFileSync(join(root, file), 'utf8').split('\n')) {
+      const heading = line.match(/^##\s+(.+?)\s*$/);
+      if (heading) {
+        current = { name: heading[1], target: null, open: true };
+        found.push(current);
+        continue;
+      }
+      if (/^###\s/.test(line) && current) current.open = false;
+      const target = line.match(/^\*\*Target:\*\*\s*(\d{4}-\d{2}-\d{2})\s*$/i);
+      if (target && current?.open && !current.target) current.target = target[1];
+    }
+  }
+  return found.map(({ name, target }) => ({ name, target }));
+}
+
 export const storyBranch = (story) => `${story.lane}/${story.id.toLowerCase()}`;
 
 /** Requirement IDs each tracked test file names: { id: [file, ...] }. */

package/hooks/lib/snapshot.mjs

@@ -0,0 +1,352 @@
+// HUBR-2: what a project reports to its team provider (docs/specs/21-hub-adapter-and-reports.md): a
+// snapshot of facts code-kit already has (status, timeline, trail, journal's approvals, the merge queue,
+// usage, the rules), as metadata only. SNAPSHOT_SCHEMA is the allow-list: every field a snapshot may
+// hold, and what kind of value it is. A provider validates against the same list, and `validSnapshot`
+// refuses anything else, so file contents, diffs, prompts and messages have nowhere to go.
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { APPROVAL_LOG } from './rules.mjs';
+import { approverOf } from './journal.mjs';
+import { readQueue } from './queue.mjs';
+import { sendBacks } from './reviews.mjs';
+import { readMilestones, specCheckRows } from './plan.mjs';
+import { storyTimes } from './timeline.mjs';
+import { trail } from './storymap.mjs';
+
+export const SNAPSHOT_VERSION = 1;
+
+/** A story's stage, as a report names it. */
+export const STAGES = [
+  'planned',
+  'claimed',
+  'building',
+  'review',
+  'sent-back',
+  'queued',
+  'merged',
+  'done',
+];
+export const AGENT_KINDS = ['lead', 'lane', 'reviewer', 'security-reviewer', 'background'];
+
+/**
+ * The allow-list. A leaf is a kind: `id` (ST-4, API-2), `handle` (a GitHub login), `name` (a lane, a
+ * layer, a milestone, an approval: one line, at most 120 characters), `title` (one line, at most 200),
+ * `line` (a send-back's reason: one line, at most 200), `path` (a file path or glob: one line, at most
+ * 300), `ms` (a time in milliseconds), `date` (YYYY-MM-DD), `count` (a whole number, 0 or more),
+ * `bool`, `enum:a|b`. A trailing `?` allows null. An array holds one shape; an object holds only the
+ * keys it lists.
+ */
+export const SNAPSHOT_SCHEMA = {
+  version: 'count',
+  project: { repository: 'name?', base: 'name', codeKit: 'name', at: 'ms' },
+  milestones: [{ name: 'name', target: 'date?', stories: ['id'] }],
+  stories: [
+    {
+      id: 'id',
+      title: 'title',
+      lane: 'name?',
+      milestone: 'name?',
+      requirements: ['id'],
+      dependsOn: ['id'],
+      stage: `enum:${STAGES.join('|')}`,
+      since: {
+        building: 'ms?',
+        review: 'ms?',
+        sentBack: 'ms?',
+        queued: 'ms?',
+        merged: 'ms?',
+      },
+      claimedBy: 'handle?',
+    },
+  ],
+  sendBacks: [{ story: 'id', at: 'ms', reason: 'line?' }],
+  requirements: [
+    {
+      id: 'id',
+      stories: ['id'],
+      built: ['path'],
+      tested: ['path'],
+      check: 'enum:done|partial|missing|conflicts|none',
+    },
+  ],
+  approvals: [{ what: 'name', path: 'path?', who: 'enum:person|lead', at: 'ms', branch: 'name?' }],
+  usage: [
+    {
+      story: 'id?',
+      kind: `enum:${AGENT_KINDS.join('|')}`,
+      input: 'count',
+      output: 'count',
+      cache: 'count',
+    },
+  ],
+  rules: {
+    layers: [{ name: 'name', mayImport: ['name'] }],
+    protected: [{ glob: 'path', approval: 'name' }],
+    delegated: { protected: ['name'], dependencies: 'bool', merge: 'bool' },
+    designGate: 'bool',
+  },
+};
+
+const ONE_LINE = (max) => (v) => typeof v === 'string' && v.length <= max && !/[\r\n]/.test(v);
+const KINDS = {
+  id: (v) => typeof v === 'string' && /^[A-Za-z][A-Za-z0-9]*-\d+$/.test(v),
+  handle: (v) => typeof v === 'string' && /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/.test(v),
+  name: ONE_LINE(120),
+  title: ONE_LINE(200),
+  line: ONE_LINE(200),
+  path: ONE_LINE(300),
+  ms: (v) => Number.isInteger(v) && v > 0,
+  date: (v) => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(v),
+  count: (v) => Number.isInteger(v) && v >= 0,
+  bool: (v) => typeof v === 'boolean',
+};
+
+/** What's wrong with a snapshot against the allow-list, as `path: problem` lines; empty when valid. */
+export function snapshotProblems(value, shape = SNAPSHOT_SCHEMA, at = 'snapshot') {
+  if (typeof shape === 'string') {
+    const optional = shape.endsWith('?');
+    const kind = optional ? shape.slice(0, -1) : shape;
+    if (value === null || value === undefined) return optional ? [] : [`${at}: missing`];
+    if (kind.startsWith('enum:'))
+      return kind.slice(5).split('|').includes(value) ? [] : [`${at}: not one of ${kind.slice(5)}`];
+    return KINDS[kind](value) ? [] : [`${at}: not a ${kind}`];
+  }
+  if (Array.isArray(shape)) {
+    if (!Array.isArray(value)) return [`${at}: not a list`];
+    return value.flatMap((v, i) => snapshotProblems(v, shape[0], `${at}[${i}]`));
+  }
+  if (value === null || typeof value !== 'object' || Array.isArray(value))
+    return [`${at}: not an object`];
+  const extra = Object.keys(value).filter((k) => !(k in shape));
+  return [
+    ...extra.map((k) => `${at}.${k}: not a field a report may hold`),
+    ...Object.entries(shape).flatMap(([k, s]) => snapshotProblems(value[k], s, `${at}.${k}`)),
+  ];
+}
+
+/** The snapshot's hash, leaving out when it was made: equal snapshots aren't sent twice. */
+export function snapshotHash(snapshot, parts = null) {
+  const { project, ...rest } = snapshot;
+  const kept = parts ? Object.fromEntries(parts.map((p) => [p, rest[p]])) : rest;
+  return createHash('sha256')
+    .update(JSON.stringify({ project: { ...project, at: 0 }, ...kept }))
+    .digest('hex');
+}
+
+/** The parts whose change is sent at once (HUBR-3); usage alone waits for the ten minutes. */
+export const EVENT_PARTS = [
+  'milestones',
+  'stories',
+  'sendBacks',
+  'requirements',
+  'approvals',
+  'rules',
+];
+
+const git = (root, ...args) => {
+  try {
+    return execFileSync('git', ['-C', root, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+};
+
+/** owner/name of the repository's GitHub origin, or null. */
+export function repositoryOf(root) {
+  const remote = git(root, 'config', '--get', 'remote.origin.url');
+  const m = remote.match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?\/?$/);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+/** The main checkout, where the lanes' worktrees share their state. */
+export function mainCheckout(root) {
+  const common = git(root, 'rev-parse', '--path-format=absolute', '--git-common-dir');
+  return common ? dirname(common) : root;
+}
+
+export const USAGE_DIR = '.claude/state/usage';
+
+/** The usage every session recorded (USE-1's ledgers, written by the mod): [{ story, kind, … }]. */
+export function recordedUsage(root) {
+  const dir = join(mainCheckout(root), USAGE_DIR);
+  const sums = new Map();
+  let files = [];
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+  } catch {
+    return [];
+  }
+  for (const f of files) {
+    let entries = [];
+    try {
+      entries = Object.values(JSON.parse(readFileSync(join(dir, f), 'utf8')).entries ?? {});
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (!AGENT_KINDS.includes(e.kind)) continue;
+      const story = KINDS.id(e.story) ? e.story : null;
+      const key = `${story}|${e.kind}`;
+      const was = sums.get(key) ?? { story, kind: e.kind, input: 0, output: 0, cache: 0 };
+      for (const k of ['input', 'output', 'cache'])
+        was[k] += Number.isInteger(e[k]) && e[k] > 0 ? e[k] : 0;
+      sums.set(key, was);
+    }
+  }
+  return [...sums.values()];
+}
+
+/** The spec-check report's status for each requirement of a story, from its branch's report. */
+function checkedRows(root, story) {
+  const name = `${story.branch.replace(/[^\w.-]+/g, '_')}.md`;
+  for (const dir of [story.worktree, root].filter(Boolean)) {
+    const file = join(dir, '.claude/state/spec-check', name);
+    if (existsSync(file)) return specCheckRows(readFileSync(file, 'utf8'));
+  }
+  return [];
+}
+
+const CHECKS = ['done', 'partial', 'missing', 'conflicts'];
+
+/**
+ * The snapshot (HUBR-2) from what code-kit already computed: `status` is buildStatus's, `base` the
+ * branch stories merge into, `claims` the team's claims as last read, `version` code-kit's.
+ */
+export function buildSnapshot({
+  root,
+  config,
+  status,
+  base,
+  claims = [],
+  version,
+  now = Date.now(),
+}) {
+  const times = new Map(storyTimes(root, status.stories, base).map((t) => [t.id, t]));
+  const queued = new Map(
+    readQueue(root)
+      .filter((e) => e.state === 'waiting' || e.state === 'merging')
+      .map((e) => [e.branch, Date.parse(e.passed)]),
+  );
+  const backs = sendBacks(root);
+  const claimed = new Map(claims.map((c) => [c.story, c.by]));
+  const ms = (v) => (Number.isInteger(v) && v > 0 ? v : null);
+  const line = (s) => (s ? String(s).replace(/\s+/g, ' ').trim().slice(0, 200) || null : null);
+
+  const stories = status.stories.map((s) => {
+    const t = times.get(s.id) ?? {};
+    const myBacks = backs.filter((b) => b.branch === s.branch);
+    const lastBack = myBacks.length ? Date.parse(myBacks.at(-1).at) : null;
+    let stage = 'planned';
+    if (s.state === 'done') stage = s.status === 'done' ? 'done' : 'merged';
+    else if (s.state === 'sent back') stage = 'sent-back';
+    else if (s.state === 'review') stage = queued.has(s.branch) ? 'queued' : 'review';
+    else if (s.state === 'in progress') stage = 'building';
+    else if (claimed.has(s.id)) stage = 'claimed';
+    const reached = STAGES.indexOf(stage);
+    return {
+      id: s.id,
+      title: line(s.title) ?? s.id,
+      lane: s.lane || null,
+      milestone: s.milestone ? line(s.milestone).slice(0, 120) : null,
+      requirements: s.requirements,
+      dependsOn: s.dependsOn,
+      stage,
+      since: {
+        building: reached >= STAGES.indexOf('building') ? ms(t.started) : null,
+        review:
+          reached >= STAGES.indexOf('review') && stage !== 'sent-back' ? ms(t.lastCommit) : null,
+        sentBack: ms(lastBack),
+        queued: stage === 'queued' ? ms(queued.get(s.branch)) : null,
+        merged: ms(t.merged),
+      },
+      claimedBy: claimed.get(s.id) ?? null,
+    };
+  });
+
+  const targets = Object.fromEntries(
+    readMilestones(root, config.docs.plan).map((m) => [m.name, m.target]),
+  );
+  const milestones = [...new Set(status.stories.map((s) => s.milestone).filter(Boolean))].map(
+    (m) => ({
+      name: line(m).slice(0, 120),
+      target: targets[m] ?? null,
+      stories: status.stories.filter((s) => s.milestone === m).map((s) => s.id),
+    }),
+  );
+
+  const byBranch = new Map(status.stories.map((s) => [s.branch, s.id]));
+  const sendBackList = backs
+    .filter((b) => byBranch.has(b.branch) && ms(Date.parse(b.at)))
+    .map((b) => ({ story: byBranch.get(b.branch), at: Date.parse(b.at), reason: line(b.reason) }));
+
+  const checks = new Map();
+  for (const s of status.stories)
+    if (s.branchExists)
+      for (const row of checkedRows(root, s))
+        if (CHECKS.includes(row.status)) checks.set(row.requirement, row.status);
+  const requirements = trail(root, status, base).map((r) => ({
+    id: r.id,
+    stories: r.stories.map((s) => s.id),
+    built: r.files.filter((f) => KINDS.path(f)),
+    tested: r.tests.filter((f) => KINDS.path(f)),
+    check: checks.get(r.id) ?? 'none',
+  }));
+
+  const approvals = [];
+  const seen = new Set();
+  for (const raw of git(root, 'show', `${base}:${APPROVAL_LOG}`).split('\n').filter(Boolean)) {
+    let e;
+    try {
+      e = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (!e.approval || e.approval === 'lead') continue;
+    const at = Date.parse(e.grantedAt ?? e.at);
+    const key = `${e.approval}|${e.file ?? ''}|${at}`;
+    if (seen.has(key) || !ms(at) || !KINDS.name(e.approval)) continue;
+    seen.add(key);
+    approvals.push({
+      what: e.approval,
+      path: KINDS.path(e.file) ? e.file : null,
+      who: approverOf(e),
+      at,
+      branch: KINDS.name(e.branch) ? e.branch : null,
+    });
+  }
+
+  const delegate = config.approvals?.delegate ?? null;
+  const snapshot = {
+    version: SNAPSHOT_VERSION,
+    project: {
+      repository: repositoryOf(root),
+      base,
+      codeKit: String(version),
+      at: now,
+    },
+    milestones,
+    stories,
+    sendBacks: sendBackList,
+    requirements,
+    approvals,
+    usage: recordedUsage(root),
+    rules: {
+      layers: (config.layers ?? []).map((l) => ({ name: l.name, mayImport: l.mayImport ?? [] })),
+      protected: (config.protected ?? [])
+        .filter((p) => KINDS.path(p.glob) && KINDS.name(p.approval))
+        .map((p) => ({ glob: p.glob, approval: p.approval })),
+      delegated: {
+        protected: delegate?.protected ?? [],
+        dependencies: Boolean(delegate?.dependencies),
+        merge: Boolean(delegate?.merge),
+      },
+      designGate: Boolean(config.designGate),
+    },
+  };
+  return snapshot;
+}

package/hooks/lib/team.mjs

@@ -4,6 +4,7 @@ import { spawnSync } from 'node:child_process';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { matchesAny } from './glob.mjs';
+import { providerAdapterOf } from './adapters/index.mjs';
 import {
   isHandle,
   isStoryId,
@@ -57,19 +58,24 @@ export function teamProblems(c) {
       );
     if (t.intents !== undefined && !(typeof t.intents === 'string' && t.intents.trim()))
       p.push('"team.intents" must name the discussion category intents go in');
+    const adapter = providerAdapterOf(t.provider);
     if (
       t.provider !== undefined &&
       t.provider !== 'github' &&
+      !(adapter && !adapter.problem) &&
       !(
         isObj(t.provider) &&
+        !adapter &&
         typeof t.provider.command === 'string' &&
         t.provider.command.trim() &&
         (t.provider.fallback === undefined || t.provider.fallback === 'github')
       )
     )
       p.push(
-        '"team.provider" must be "github" or { "command": "<the provider\'s command>", "fallback"?: "github" }',
+        '"team.provider" must be "github" or { "command": "<the provider\'s command>", "fallback"?: "github" }, or a hosted provider in preview: { "<its name>": "<its https address>" }',
       );
+    if (t.report !== undefined && typeof t.report !== 'boolean')
+      p.push('"team.report" must be true or false');
   }
   for (const [name, lane] of Object.entries(isObj(c.lanes) ? c.lanes : {})) {
     if (!isObj(lane) || lane.owners === undefined) continue;
@@ -86,12 +92,26 @@ export function teamProblems(c) {
  */
 export function teamOf(raw) {
   if (!isObj(raw?.team)) return null;
+  // HUBR-6: a hosted provider's adapter runs as a command, with GitHub as its fallback.
+  const adapter = providerAdapterOf(raw.team.provider);
+  const hosted = adapter && !adapter.problem ? adapter : null;
   return {
     techLead: raw.team.techLead,
     staleDays: raw.team.staleDays ?? 3,
-    intents: raw.team.intents ?? 'Intents',
+    // HUBR-7: a hosted provider keeps intents; Discussions only when the team mirrors them there.
+    intents: raw.team.intents ?? (hosted ? null : 'Intents'),
     board: raw.team.board ?? null,
-    provider: raw.team.provider ?? 'github',
+    // HUBR-4: whether the project reports its facts to a provider that isn't GitHub.
+    report: raw.team.report !== false,
+    provider: hosted
+      ? {
+          command: hosted.adapter.command(hosted.url),
+          fallback: 'github',
+          adapter: hosted.adapter.key,
+          url: hosted.url,
+          name: hosted.adapter.label,
+        }
+      : (raw.team.provider ?? 'github'),
     owners: Object.fromEntries(
       Object.entries(raw.lanes ?? {})
         .filter(([, l]) => Array.isArray(l?.owners))
@@ -139,6 +159,9 @@ export function whoami(root, now = Date.now()) {
 // the config, called with the operation's name and its input as JSON on stdin, answering JSON.
 
 const CLAIMS = 'refs/code-kit/claims';
+/** HUBR-7: what an intent waits on while the hosted provider that keeps intents is down. */
+const KEPT =
+  "This team's intents are kept by its hosted provider, which can't be reached: raise or settle it again when it's back, or set team.intents to mirror intents to a GitHub Discussions category.";
 const SEEN = 'refs/code-kit/seen-claims';
 const TEAM_STATE = '.claude/state/team.json';
 const STATE_SECONDS = 60;
@@ -157,7 +180,7 @@ function claimOf(message) {
 
 /**
  * The provider for this project's team: GitHub's, or the config's command. A command with
- * `fallback: "github"` (a hosted provider, such as the code-kit teams hub) hands each operation it
+ * `fallback: "github"` (a hosted provider, such as code-kit hub) hands each operation it
  * can't reach to the GitHub provider, so claims are still checked while it's down (TEAM-8).
  */
 export function teamProvider(root, team) {
@@ -189,6 +212,7 @@ export function teamProvider(root, team) {
         'reassign',
         'intent',
         'since',
+        'report',
       ].map((op) => [op, either(op)]),
     ),
     forget: () => (command.forget(), github.forget()),
@@ -223,8 +247,14 @@ function githubProvider(root, team) {
       return null;
     }
   };
-  /** The repository's discussions, the Intents category among its categories: null when unreadable. */
+  /**
+   * The repository's discussions, the Intents category among its categories: null when unreadable.
+   * HUBR-7: a team whose hosted provider keeps its intents, and that mirrors none to Discussions, has
+   * none here to read (`kept`).
+   */
   const discussions = () => {
+    if (!team.intents)
+      return { repoId: null, enabled: false, category: null, intents: [], kept: true };
     const d = graphql(
       `
         query ($owner: String!, $name: String!) {
@@ -452,13 +482,15 @@ function githubProvider(root, team) {
         provider: {
           name: 'GitHub',
           live: false,
-          detail: `claims are refs on origin, intents are discussions in "${team.intents}"`,
+          detail: team.intents
+            ? `claims are refs on origin, intents are discussions in "${team.intents}"`
+            : 'claims are refs on origin; intents wait for the hosted provider',
         },
         // TEAM-13: what the team still needs set up for its claims and intents to work.
         setup: [
           ...(who ? [] : ["gh isn't signed in on this machine: run gh auth login."]),
           ...(claims ? [] : ["The shared repository (origin) can't be reached."]),
-          ...(found && !found.category
+          ...(found && !found.category && !found.kept
             ? [noCategory(found).replace(/, then raise the intent again\.$/, '.')]
             : []),
         ],
@@ -489,6 +521,7 @@ function githubProvider(root, team) {
       if (!by) return { ok: false, why: 'Sign in to GitHub first (gh auth login).' };
       const found = discussions();
       if (!found) return unreachable("GitHub can't be reached, so the intent wasn't raised.");
+      if (found.kept) return unreachable(KEPT);
       if (!found.category) return { ok: false, why: noCategory(found) };
       const body = `${touches.length ? `Touches: ${touches.join(', ')}\n\n` : ''}Raised with code-kit by @${by} before any code, so the team sees it first. The tech lead agrees, drops or marks it a duplicate here.`;
       const made = graphql(
@@ -585,6 +618,7 @@ function githubProvider(root, team) {
     },
     /** TEAM-10: one intent with its comments, for its decision record; null when unreadable. */
     intent(id) {
+      if (!team.intents) return null;
       const d = graphql(
         `
           query ($owner: String!, $name: String!, $number: Int!) {
@@ -627,6 +661,7 @@ function githubProvider(root, team) {
     },
     /** TEAM-5: the tech lead agrees an intent (resolved), drops it (outdated) or marks it a duplicate. */
     settle(id, outcome, why = '') {
+      if (!team.intents) return unreachable(KEPT);
       const by = me();
       if (by !== team.techLead)
         return {
@@ -689,6 +724,8 @@ function githubProvider(root, team) {
       provider.forget();
       return { ok: true, id: Number(id), outcome };
     },
+    // HUBR-1: the free team mode has no server to report to; nothing is written anywhere.
+    report: () => ({ ok: true, sent: false }),
     forget: () => writeCache(root, null),
   };
   return provider;
@@ -739,6 +776,8 @@ function commandProvider(root, team, command) {
       const r = call('since', { at });
       return Array.isArray(r) ? r : null;
     },
+    // HUBR-1: the project's facts, on stdin as the operation's input.
+    report: (snapshot) => call('report', { snapshot }),
     forget: () => writeCache(root, null),
   };
 }

package/hooks/lib/teamfacts.mjs

@@ -122,17 +122,21 @@ export function decisionRecord(d, techLead) {
     .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();
+  // Who settled it: the provider says (a lane owner whose paths it touches may agree it with a hosted
+  // provider), or the tech lead, who alone settles intents through GitHub.
+  const by = d.settledBy ?? d.settled_by ?? techLead;
+  const agreed =
+    (d.comments ?? [])
+      .filter((c) => c.author?.login === by && /^Agreed by @/.test(c.body))
+      .at(-1)
+      ?.body.replace(/^Agreed by @[\w-]+(?:, [^:.]*)?(: |\.)?/, '')
+      .trim() || (typeof d.why === 'string' ? d.why.trim() : '');
   return [
     `# ${d.title}`,
     '',
     '**Status:** agreed',
     `**Date:** ${date}`,
-    `**Raised by:** @${d.author?.login ?? 'someone'} · **Agreed by:** @${techLead}`,
+    `**Raised by:** @${d.author?.login ?? 'someone'} · **Agreed by:** @${by}`,
     `**Discussion:** ${d.url}`,
     '',
     '## What changes, and why',