geneseed 4.0.0 → 4.2.0

package/js/web/api.mjs

@@ -1,6 +1,6 @@
 /**
  * The web console's dashboard and settings reads — `overview`, `recent`, `themes`, `setup`,
- * `doctor`, `diff`, `installs`, `excludes` and the two `loops` reads.
+ * `doctor`, `diff`, `installs`, `fleet`, `update`, `excludes` and the two `loops` reads.
  *
  * WHAT IS NOT HERE, AND WHERE IT WENT: the Library read model (catalog sections, items, wiki,
  * memory, `NotFound`) is `catalog.mjs`; the `WebState` every endpoint reads from is `state.mjs`;
@@ -11,12 +11,14 @@
 import { statSync } from 'node:fs';
 import path from 'node:path';
 
-import { CONFIG, ROOT, THEMES, discoverNames } from '../build/source.mjs';
+import { CONFIG, ROOT, THEMES, discoverNames, makeCfg } from '../build/source.mjs';
+import { readVersion, sourceFingerprint } from '../build/version.mjs';
 import { sourceReleaseVersion } from '../hosts/opencode.mjs';
+import { alwaysOnCost } from '../inspect/cost.mjs';
 import { diffCollect } from '../inspect/diff.mjs';
 import { doctorCollect } from '../inspect/doctor.mjs';
 import { excludesSnapshot } from '../inspect/excludes.mjs';
-import { CLAUDE_STYLE, HOSTS, resolvePath } from '../hosts/hosts.mjs';
+import { CLAUDE_STYLE, HOSTS, VERSION_MARKER, resolvePath } from '../hosts/hosts.mjs';
 import {
   footprintOfDir, installState, installTargets, modeOfDir, trustOfDir,
   postureOfDir, readJsonMaybe, themeOfDir,
@@ -32,6 +34,7 @@ import {
   configItems, deployed, dget, memoryItems, notebookItems, wikiItems,
 } from './catalog.mjs';
 import { stampMinute } from './state.mjs';
+import { updateStatus } from './update-check.mjs';
 
 /**
  * `js/web/docs.mjs` imports these three from HERE, and that file is outside this split — so
@@ -113,11 +116,18 @@ export function viewCfg(host, scope, root) {
   return root;
 }
 
+/**
+ * The row `id` carries the ROOT, not only `host:scope`: two project installs of one host (two
+ * repos on Bob, say) are both `bob:project`, and the console keys its selection, its React rows
+ * and its per-install picks on this id — with a shared one, both rows read as selected and every
+ * pick resolved to whichever came first. `installTargets()` de-duplicates on (host, root), so
+ * this is unique by construction.
+ */
 export function apiInstalls(state) {
   const out = [];
   for (const [host, scope, root] of installTargets()) {
     out.push({
-      id: `${host}:${scope}`, host, scope, path: root,
+      id: `${host}:${scope}:${root}`, host, scope, path: root,
       state: installState(root, host, scope),
       // Narrowed to this row's own host (host-compat B1): a shared repo otherwise answers
       // every row with whichever host's carrier the host-agnostic scan favours.
@@ -134,6 +144,63 @@ export function apiInstalls(state) {
 }
 
 
+/**
+ * EVERY INSTALLED HARNESS ON THE MACHINE, EACH JUDGED ON ITS OWN — the Overview's fleet table.
+ *
+ * Installed means `active` or `disabled`: a host with nothing installed is not listed, because
+ * installing belongs to the Installs page with its other settings (user, 2026-10-13).
+ *
+ * Its own route, not more fields on `/api/installs`: the sidebar refetches that list on every
+ * data revision, and the drift check below re-renders a whole emit per global install.
+ * ponytail: one `diffCollect` render per global install per request, fine for the handful a
+ * machine carries; cache per (root, build mtime) if a fleet ever grows past that.
+ *
+ * Each row reads ITS OWN `.geneseed-version`. `statusData().installed_fp` is the first carrier
+ * a fixed walk finds, which describes the wrong install as soon as two hosts are deployed.
+ * Every unknown stays `null` — `verdict: 'unknown'`, `drift: null` — never a reassuring zero.
+ */
+export function apiFleet(state) {
+  const sourceFp = sourceFingerprint(makeCfg());
+  const installs = [];
+  for (const [host, scope, root] of installTargets()) {
+    const st = installState(root, host, scope);
+    if (st !== 'active' && st !== 'disabled') continue;
+    const dir = viewCfg(host, scope, root);
+    const fp = readVersion(dir);
+    let drift = null;
+    if (st === 'active') {
+      try {
+        const { files } = diffCollect({ target: dir });
+        if (files !== null) {
+          drift = {
+            edited: files.filter((f) => f.status === 'edited').length,
+            added: files.filter((f) => f.status === 'added').length,
+            missing: files.filter((f) => f.status === 'missing').length,
+          };
+        }
+      } catch { /* an install that cannot be re-rendered reports no drift figure, not zero */ }
+    }
+    let built = null;
+    try { built = Math.floor(statSync(path.join(dir, VERSION_MARKER)).mtimeMs / 1000); } catch { /* never built */ }
+    installs.push({
+      id: `${host}:${scope}:${root}`, host, scope, path: root, state: st,
+      theme: themeOfDir(root, host),
+      footprint: footprintOfDir(root),
+      installed_fp: fp,
+      verdict: fp === null ? 'unknown' : fp === sourceFp ? 'synced' : 'behind',
+      // A project install has no drift check at all (`diffCollect` answers `files: null`), which
+      // the console must say as "not checkable" — so the fact travels apart from the figure.
+      diffable: drift !== null,
+      drift,
+      built_epoch: built,
+      // What this install injects every session, by part (characters); null when its carrier
+      // is missing, so the console says "not measured" rather than drawing an empty bar.
+      cost: alwaysOnCost({ host, root, dir, footprint: footprintOfDir(root) }),
+    });
+  }
+  return { installs, source_fp: sourceFp, doctor: state.doctor };
+}
+
 /** The dashboard aggregate. */
 export function apiOverview(state) {
   const inv = state.inventory;
@@ -347,6 +414,9 @@ export function apiLoopsActive() {
 }
 
 /** The source's release label, or null when it cannot be read. */
+/** Is a newer release on npm than the source this console serves? See update-check.mjs. */
+export const apiUpdate = (state) => updateStatus(state, releaseLabel());
+
 function releaseLabel() {
   const v = sourceReleaseVersion({ config: CONFIG });
   return v && v !== '0.0.0' ? v : null;

package/js/web/gates-api.mjs

@@ -0,0 +1,44 @@
+/**
+ * GET /api/gates — gate asks per rule per day over the last 30 days, across every installed
+ * harness: the Overview's "Gates" sparklines. The ledger (`notebook/gates.jsonl`, written by
+ * js/hosts/hooks.mjs and the OpenCode guard plugin) already stamps each ask with an ISO `ts`
+ * and a `rule` (`law-1`, `process-1`, `wiki`…); this only reads it. `gateSummary` keeps its
+ * count-only shape for the CLI's status panel.
+ *
+ * `{ days: ['YYYY-MM-DD' × 30], rules: [{ rule, n, per_day[30] }] }`, busiest rule first.
+ * Garbage lines are skipped; nothing here writes (the writers already trim at 1000 lines).
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { GATE_LEDGER } from '../hosts/hosts.mjs';
+import { installState, installTargets } from '../hosts/installs.mjs';
+import { viewCfg } from './api.mjs';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WINDOW = 30;
+
+export function gateDays({ now = Date.now(), targets = installTargets() } = {}) {
+  const days = Array.from({ length: WINDOW }, (_, i) =>
+    new Date(now - (WINDOW - 1 - i) * DAY_MS).toISOString().slice(0, 10));
+  const index = new Map(days.map((d, i) => [d, i]));
+  const by = new Map();
+  for (const [host, scope, root] of targets) {
+    if (installState(root, host, scope) !== 'active') continue;
+    let raw;
+    try { raw = readFileSync(path.join(viewCfg(host, scope, root), GATE_LEDGER), 'utf8'); } catch { continue; }
+    for (const line of raw.split('\n')) {
+      let e;
+      try { e = JSON.parse(line); } catch { continue; }
+      const i = typeof e?.ts === 'string' ? index.get(e.ts.slice(0, 10)) : undefined;
+      if (i === undefined || typeof e.rule !== 'string') continue;
+      const row = by.get(e.rule) || { rule: e.rule, n: 0, per_day: new Array(WINDOW).fill(0) };
+      row.n += 1;
+      row.per_day[i] += 1;
+      by.set(e.rule, row);
+    }
+  }
+  return { days, rules: [...by.values()].sort((a, b) => b.n - a.n || a.rule.localeCompare(b.rule)) };
+}
+
+export const apiGates = () => gateDays();

package/js/web/handler.mjs

@@ -371,8 +371,8 @@ export function makeHandler(state, jm, token, dist, holder = null) {
           try {
             return doPost(req, res, path, ae, buf);
           } catch (e) {
-            // `apiMcpToggle`, `apiSelectView`, `apiMemoryDelete`, `apiRulesMutate` and
-            // `apiRulesPromote` all raise `NotFound` for an unknown target, mapped to 404
+            // `apiSelectView`, `apiMemoryDelete`, `apiRulesMutate` and `apiRulesPromote` all
+            // raise `NotFound` for an unknown target, mapped to 404
             // here; anything else falls to the 500 arm below, carrying its own message.
             if (e instanceof NotFound) {
               return sendJson(res, { error: `not found: ${e.message}` }, 404, ae);

package/js/web/routes.mjs

@@ -18,13 +18,15 @@
  */
 import { formatValue, isTruthy, parseJson } from '../lib/json.mjs';
 import { percentDecode } from '../lib/text.mjs';
-import { apiExcludesMutate, apiInstallToggle, apiLoopsPresetMutate, apiMcp, apiMcpToggle, apiMemoryDelete, apiSelectView } from './actions.mjs';
+import { apiExcludesMutate, apiInstallToggle, apiLoopsPresetMutate, apiMcp, apiMemoryDelete, apiSelectView } from './actions.mjs';
 import { apiActivity, apiActivityDetail, apiActivityToggle } from './activity.mjs';
 import {
-  apiDiff, apiDoctor, apiExcludes, apiInstalls, apiLoops, apiLoopsActive, apiOverview,
-  apiRecent, apiSetup, apiThemes,
+  apiDiff, apiDoctor, apiExcludes, apiFleet, apiInstalls, apiLoops, apiLoopsActive, apiOverview,
+  apiRecent, apiSetup, apiThemes, apiUpdate,
 } from './api.mjs';
 import { NotFound, apiCatalog, apiItem } from './catalog.mjs';
+import { apiUsage } from './usage-api.mjs';
+import { apiGates } from './gates-api.mjs';
 import { apiProfile, apiProfileSave, apiRules, apiRulesMutate, apiRulesPromote } from './user-files.mjs';
 
 /**
@@ -43,7 +45,6 @@ import { apiProfile, apiProfileSave, apiRules, apiRulesMutate, apiRulesPromote }
  */
 /** @type {Map<string, [(state: any, body: any) => any, boolean]>} */
 export const POST_ROUTES = new Map([
-  ['/api/mcp', [apiMcpToggle, true]],
   ['/api/install', [apiInstallToggle, true]],
   ['/api/excludes', [apiExcludesMutate, true]],
   ['/api/view', [apiSelectView, true]],
@@ -147,6 +148,10 @@ export const STATE_ROUTES = {
   '/api/setup': apiSetup,
   '/api/doctor': apiDoctor,
   '/api/installs': apiInstalls,
+  '/api/fleet': apiFleet,
+  '/api/update': apiUpdate,
+  '/api/usage': apiUsage,
+  '/api/gates': apiGates,
   '/api/excludes': apiExcludes,
   '/api/profile': apiProfile,
   '/api/diff': apiDiff,

package/js/web/update-check.mjs

@@ -0,0 +1,61 @@
+/**
+ * IS A NEWER GENESEED RELEASED? — the Overview's "4.2.0 available" chip.
+ *
+ * Route handlers answer synchronously, so this never waits on the network: it answers from the
+ * last result it holds and, when that is missing or a day old, starts ONE background fetch whose
+ * answer the next poll reads. The console refetches after every mutation and on mount, so the
+ * chip appears within a poll or two of the daemon starting.
+ *
+ * Every failure is `latest: null` and says nothing more: a corporate proxy, an offline laptop and
+ * a registry outage all read "update check unavailable", never an error. `GENESEED_NO_UPDATE_CHECK`
+ * turns the fetch off for a machine that must not phone out at all.
+ *
+ * ponytail: the cache lives on the daemon's state, in memory. A restart costs one more request;
+ * a disk cache would be a file to version for a figure that is free to re-ask.
+ */
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** A failed ask is retried sooner than a good answer is refreshed: a proxy hiccup is not a day. */
+const RETRY_MS = 60 * 60 * 1000;
+const REGISTRY = 'https://registry.npmjs.org/geneseed/latest';
+
+/** x.y.z only; a pre-release tag or a malformed label compares as nothing newer. */
+export function semverGreater(a, b) {
+  const parse = (v) => (/^(\d+)\.(\d+)\.(\d+)$/.exec(String(v || '').trim()) || []).slice(1).map(Number);
+  const x = parse(a);
+  const y = parse(b);
+  if (x.length !== 3 || y.length !== 3) return false;
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i];
+  return false;
+}
+
+async function npmLatest() {
+  const res = await fetch(REGISTRY, { signal: AbortSignal.timeout(3000) });
+  if (!res.ok) return null;
+  const body = await res.json();
+  return typeof body?.version === 'string' ? body.version : null;
+}
+
+/**
+ * `{ current, latest, available, checked_at }`. `available` is true only when `latest` is
+ * semver-greater than `current`, so a checkout ahead of the last release never shows one;
+ * null when either side is unknown. `fetcher` and `now` are injectable for the tests, which
+ * must never reach the network.
+ */
+export function updateStatus(state, current, { fetcher = npmLatest, now = Date.now() } = {}) {
+  const c = state._update || (state._update = { latest: null, checked_at: null, inflight: false });
+  const stale = c.checked_at === null
+    || now - c.checked_at > (c.latest === null ? RETRY_MS : DAY_MS);
+  // Under `node --test` (NODE_TEST_CONTEXT) the real registry is never asked: the route probes in
+  // tests/unit/web_server.test.mjs reach this handler, and a suite must not depend on the network.
+  const off = process.env.GENESEED_NO_UPDATE_CHECK
+    || (fetcher === npmLatest && process.env.NODE_TEST_CONTEXT);
+  if (stale && !c.inflight && !off) {
+    c.inflight = true;
+    Promise.resolve()
+      .then(fetcher)
+      .then((v) => { c.latest = v ?? null; }, () => { c.latest = null; })
+      .finally(() => { c.checked_at = now; c.inflight = false; });
+  }
+  const available = current && c.latest ? semverGreater(c.latest, current) : null;
+  return { current: current ?? null, latest: c.latest, available, checked_at: c.checked_at };
+}

package/js/web/usage-api.mjs

@@ -0,0 +1,95 @@
+/**
+ * GET /api/usage — the Overview's "What fires" chart, read off every installed harness's
+ * `notebook/usage.jsonl` (the writer is js/hosts/usage.mjs, and the OpenCode guard plugin's copy).
+ *
+ * `{ enabled, since, days_counted, per_day[30], rows[{install, kind, name, n}],
+ *    never[{install, kind, name}] }`, the window being the last 30 days including today.
+ *
+ * `since` is the oldest day any ledger holds and `days_counted` how many of the 30 it covers:
+ * the console keeps the never-fired claim back until a full 30 are counted, so a fresh install
+ * is not told every skill is unused. `never` lists installed skills and agents with no call in
+ * the window, alias stubs included (an alias that never fires is exactly what to prune).
+ *
+ * Lines older than 90 days are dropped from the ledger when it is read — the daemon prunes, so
+ * the hook path only ever appends. Garbage lines are skipped, never fatal.
+ */
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { USAGE_LEDGER, USAGE_OFF } from '../hosts/usage.mjs';
+import { installState, installTargets } from '../hosts/installs.mjs';
+import { viewCfg } from './api.mjs';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WINDOW = 30;
+const KEEP_DAYS = 90;
+const day = (ms) => new Date(ms).toISOString().slice(0, 10);
+
+const listOr = (dir) => { try { return readdirSync(dir); } catch { return []; } };
+
+/** The ledger's parsed lines, pruned to `KEEP_DAYS` (rewritten only when something was dropped). */
+function readLedger(file, cutoff) {
+  let raw;
+  try { raw = readFileSync(file, 'utf8'); } catch { return []; }
+  const lines = raw.split('\n').filter(Boolean);
+  const kept = [];
+  const out = [];
+  for (const line of lines) {
+    let e;
+    try { e = JSON.parse(line); } catch { continue; }
+    if (!e || typeof e.ts !== 'string' || typeof e.name !== 'string'
+      || (e.kind !== 'skill' && e.kind !== 'agent')) continue;
+    if (e.ts < cutoff) continue;
+    kept.push(line);
+    out.push(e);
+  }
+  if (kept.length !== lines.length) {
+    try { writeFileSync(file, kept.length ? `${kept.join('\n')}\n` : ''); } catch { /* read-only: keep serving */ }
+  }
+  return out;
+}
+
+export function usageSummary({ now = Date.now(), targets = installTargets() } = {}) {
+  const days = Array.from({ length: WINDOW }, (_, i) => day(now - (WINDOW - 1 - i) * DAY_MS));
+  const first = days[0];
+  const perDay = new Array(WINDOW).fill(0);
+  const counts = new Map();
+  const never = [];
+  let since = null;
+  let enabled = !process.env.GENESEED_NO_USAGE;
+  for (const [host, scope, root] of targets) {
+    if (installState(root, host, scope) !== 'active') continue;
+    const dir = viewCfg(host, scope, root);
+    const install = `${host}:${scope}:${root}`;
+    if (existsSync(path.join(dir, USAGE_OFF))) enabled = false;
+    const entries = readLedger(path.join(dir, USAGE_LEDGER), day(now - KEEP_DAYS * DAY_MS));
+    const fired = new Set();
+    for (const e of entries) {
+      if (since === null || e.ts < since) since = e.ts;
+      if (e.ts < first) continue;
+      const i = days.indexOf(e.ts);
+      if (i >= 0) perDay[i] += 1;
+      const key = `${install}\u0000${e.kind}\u0000${e.name}`;
+      counts.set(key, (counts.get(key) || 0) + 1);
+      fired.add(`${e.kind}\u0000${e.name}`);
+    }
+    for (const name of listOr(path.join(dir, 'skills'))) {
+      if (existsSync(path.join(dir, 'skills', name, 'SKILL.md')) && !fired.has(`skill\u0000${name}`)) {
+        never.push({ install, kind: 'skill', name });
+      }
+    }
+    for (const f of listOr(path.join(dir, 'agents'))) {
+      const name = f.endsWith('.md') ? f.slice(0, -3) : null;
+      if (name && !fired.has(`agent\u0000${name}`)) never.push({ install, kind: 'agent', name });
+    }
+  }
+  const rows = [...counts].map(([key, n]) => {
+    const [install, kind, name] = key.split('\u0000');
+    return { install, kind, name, n };
+  }).sort((a, b) => b.n - a.n || a.name.localeCompare(b.name));
+  const daysCounted = since === null ? 0
+    : Math.min(WINDOW, Math.floor((Date.parse(day(now)) - Date.parse(since)) / DAY_MS) + 1);
+  return { enabled, since, days_counted: daysCounted, per_day: perDay, rows, never };
+}
+
+export const apiUsage = () => usageSummary();

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "Every field here is argued and gated in tests/unit/package_manifest.test.mjs. `files`, `bin` and `engines` each have a test that fails when reality drifts from this file; `version` mirrors harness.config.json and is gated too. Read that docblock before editing this one.",
   "name": "geneseed",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "A portable, theme-able harness you implant once and use everywhere to grow a disciplined AI coding agent.",
   "keywords": [
     "ai",

package/registry.json

@@ -72,11 +72,11 @@
       "last_verified": ""
     },
     "agents/researcher": {
-      "status": "experimental",
+      "status": "approved",
       "version": "1.0.0",
       "owner": "Guillaume Lemer",
       "added": "2026-09-06",
-      "last_verified": ""
+      "last_verified": "2026-10-13"
     },
     "agents/reviewer": {
       "status": "approved",
@@ -184,11 +184,11 @@
       "last_verified": "2026-09-06"
     },
     "skills/dependencies": {
-      "status": "experimental",
+      "status": "approved",
       "version": "1.0.0",
       "owner": "Guillaume Lemer",
       "added": "2026-10-08",
-      "last_verified": ""
+      "last_verified": "2026-10-13"
     },
     "skills/develop": {
       "status": "approved",
@@ -205,11 +205,11 @@
       "last_verified": "2026-09-06"
     },
     "skills/explain-changes": {
-      "status": "experimental",
+      "status": "approved",
       "version": "1.0.0",
       "owner": "Guillaume Lemer",
       "added": "2026-09-30",
-      "last_verified": ""
+      "last_verified": "2026-10-13"
     },
     "skills/forge-mcp": {
       "status": "approved",
@@ -247,11 +247,11 @@
       "last_verified": "2026-09-06"
     },
     "skills/git-history": {
-      "status": "experimental",
+      "status": "approved",
       "version": "1.0.0",
       "owner": "Guillaume Lemer",
       "added": "2026-10-08",
-      "last_verified": ""
+      "last_verified": "2026-10-13"
     },
     "skills/handoff": {
       "status": "approved",
@@ -260,13 +260,6 @@
       "added": "2026-06-03",
       "last_verified": "2026-09-06"
     },
-    "skills/herdr": {
-      "status": "approved",
-      "version": "1.0.0",
-      "owner": "Guillaume Lemer",
-      "added": "2026-06-13",
-      "last_verified": "2026-09-06"
-    },
     "skills/ingest": {
       "status": "approved",
       "version": "1.0.0",
@@ -387,18 +380,18 @@
       "last_verified": "2026-09-06"
     },
     "skills/rule": {
-      "status": "experimental",
+      "status": "approved",
       "version": "1.0.0",
       "owner": "Guillaume Lemer",
       "added": "2026-07-07",
-      "last_verified": ""
+      "last_verified": "2026-10-13"
     },
     "skills/security-audit": {
-      "status": "experimental",
+      "status": "approved",
       "version": "1.0.0",
       "owner": "Guillaume Lemer",
       "added": "2026-09-06",
-      "last_verified": ""
+      "last_verified": "2026-10-13"
     },
     "skills/ship": {
       "status": "approved",
@@ -408,11 +401,11 @@
       "last_verified": "2026-09-06"
     },
     "skills/skill-forge": {
-      "status": "experimental",
+      "status": "approved",
       "version": "1.0.0",
       "owner": "Guillaume Lemer",
       "added": "2026-09-06",
-      "last_verified": ""
+      "last_verified": "2026-10-13"
     },
     "skills/teach": {
       "status": "experimental",
@@ -422,11 +415,11 @@
       "last_verified": ""
     },
     "skills/token-report": {
-      "status": "experimental",
+      "status": "approved",
       "version": "1.0.0",
       "owner": "Guillaume Lemer",
       "added": "2026-07-29",
-      "last_verified": ""
+      "last_verified": "2026-10-13"
     },
     "skills/wayfinder": {
       "status": "approved",
@@ -450,11 +443,11 @@
       "last_verified": "2026-09-06"
     },
     "skills/worktree": {
-      "status": "experimental",
+      "status": "approved",
       "version": "1.0.0",
       "owner": "Guillaume Lemer",
       "added": "2026-09-06",
-      "last_verified": ""
+      "last_verified": "2026-10-13"
     }
   }
 }

package/src/AGENT.md.tmpl

@@ -262,7 +262,6 @@ the ten council seats are convened by the [council {{SKILL}}]({{DIR_SKILLS}}/cou
 | [loop]({{DIR_SKILLS}}/loop.md) | the user asks to run a loop |
 | [brick-forge]({{DIR_SKILLS}}/brick-forge.md) | a new or adapted loop brick |
 | [wiki]({{DIR_SKILLS}}/wiki.md) | consulting or growing the user's machine-wide knowledge base declared in `geneseed-wiki.jsonc` (§8) |
-| [herdr]({{DIR_SKILLS}}/herdr.md) | running inside a [herdr](https://herdr.dev) pane (`HERDR_ENV=1`) and a task needs another pane — a sibling server, a watched build, a spawned agent |
 | [rule]({{DIR_SKILLS}}/rule.md) | anything the user wants to outlive this session — a standing rule of their own (§1) or a durable fact to remember (§5); also tending the {{MEMORY}} set — duplicates, stale facts, a recurring lesson due for promotion |
 | [profile]({{DIR_SKILLS}}/profile.md) | the user wants the agent to know who they are — creating or refreshing the `PROFILE.md` identity file (§1) through a short interview |
 | [skill-forge]({{DIR_SKILLS}}/skill-forge.md) | a repeated task has no {{SKILL}}, a self-improvement loop produced an edit, or two {{SKILLS}} should merge |

package/src/agents/_template.md

@@ -28,7 +28,8 @@
 ## Inputs
 - What the caller must provide (files, diff, scope, acceptance criteria).
 - Dispatches arrive as an envelope: goal, inputs, output contract, inherited
-  constraints (never commit/push; report gaps instead of inventing). When an
+  constraints (never commit/push; dispatch no sub-agents — review comes from the caller;
+  report gaps instead of inventing). When an
   envelope arrives incomplete, hold the caller to it via `spec-feedback:`.
 
 ## Allowed tools

package/src/agents/researcher.md

@@ -21,7 +21,8 @@
 - The question, what a complete answer must contain, and any source the caller
   already trusts or distrusts.
 - Dispatches arrive as an envelope: goal, inputs, output contract, inherited
-  constraints (never commit/push; report gaps instead of inventing). When an
+  constraints (never commit/push; dispatch no sub-agents — review comes from the caller;
+  report gaps instead of inventing). When an
   envelope arrives incomplete, hold the caller to it via `spec-feedback:`.
 
 ## Allowed tools

package/src/agents/reviewer.md

@@ -11,16 +11,19 @@
 - Pure design questions — use [architect](architect.md).
 
 ## Inputs
-- The diff or list of changed files, and the task the change was meant to satisfy.
+- The base..head range (or the diff), and the task the change was meant to satisfy.
 
 ## Allowed tools
 - **Read-only.** May read code, run the test suite and linters, inspect history.
-- Does not edit code; it reports.
+- Does not edit code; it reports. Never moves HEAD, the index or the working tree — to see
+  another revision, use `git show` or a separate worktree. Never dispatches another reviewer.
 <!-- bash: allow -->
 
 ## Procedure
 0. If `{{DIR_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
-1. Confirm the change actually does what the task required (read the spec/issue).
+1. Confirm the change actually does what the task required (read the spec/issue). Where
+   the spec is silent, judge by what a reasonable user would expect: a crash, hang or data
+   loss on an input the spec implies but never names is blocking, not a nitpick.
    Then read, for each changed file, the nearest `REVIEW.md` above it — a deeper one
    overrides a shallower one, and they override this procedure and the output contract,
    never a {{LAW}}.
@@ -31,7 +34,9 @@
 ## Output contract
 - A list of findings, each a Conventional Comment, `label (decoration): file:line — problem
   — suggested fix`, ordered correctness-first. Labels: issue, suggestion, question, todo,
-  nitpick, thought, note, praise; decorations: blocking, non-blocking, if-minor. End with a
+  nitpick, thought, note, praise; decorations: blocking, non-blocking, if-minor. Then a
+  **Set aside:** list — each behaviour considered and left out of scope, one line with the
+  reason, or `none` — for the caller to rule on. End with a
   one-line verdict that follows from the decorations: any blocking → block, any if-minor
   and nothing blocking → fix-then-ship, otherwise ship.
 - If a check was impossible — no diff, no task statement, a suite that will not

package/src/agents/tester.md

@@ -42,11 +42,11 @@ to recruit; it changes nothing about how this {{AGENT}} behaves when dispatched
 independently.)*
 
 - **Seat(s):** tester — the development floor's validator, the other half of
-  the dev↔tester loop (capped at 5 iterations).
+  the dev↔tester loop (two repairs, then one fresh developer).
 - **Receives:** the developer's changed worktree.
 - **Delivers:** raw test + lint output with exit codes — the mechanical proof.
-  On failure, findings go back to the developer seat; on the 5th failure, the
-  pipeline stops and reports instead of looping again.
+  On failure, findings go back to the developer seat; when the fresh
+  developer fails too, the pipeline stops and reports instead of looping again.
 
 ## Self-improvement
 

package/src/doctrines/rigor.md

@@ -44,7 +44,8 @@ Code you author is not done until its behaviour is covered by a test you wrote
 and the affected tests run green. New behaviour ships with the test that pins it,
 a bug fix with the test that reproduces it first (the develop {{SKILL}} drives this).
 After each change run the tests that change could affect — the ones you touched,
-not the whole suite ({{DOCTRINE:context-economy}}) — and read the output before moving on.
+not the whole suite ({{DOCTRINE:context-economy}}) — and read the output before moving on;
+once at the end, run the whole suite and name every failure, even one you did not cause.
 Verify against the project's real runner and show the result as evidence ({{LAW:verify-before-asserting}});
 assert on observable behaviour, deterministically ({{DOCTRINE:honest-tests}}). Where the
 project has no suite or the change is genuinely untestable — a doc, a constant, a
@@ -52,12 +53,12 @@ config — say so rather than invent a test; where a real test is out of scope,
 the gap and stop rather than ship untested behaviour in silence ({{LAW:one-intent-one-act}},
 {{LAW:cure-the-cause}}).
 <!-- LEAN:else -->
-Code is not done until its behaviour is covered by a test you wrote and the affected tests
-run green. New behaviour ships with its test, a bug fix with the reproducing test first
-(run the develop {{SKILL}}). Run them on the real runner, read the output, show it as
-evidence ({{LAW:verify-before-asserting}}). Where the change is untestable, say so and name the gap rather than
-invent a test; where a real test is out of scope, stop rather than ship untested behaviour in
-silence ({{LAW:one-intent-one-act}}, {{LAW:cure-the-cause}}).
+Code is done when a test you wrote covers its behaviour and the affected tests run green.
+New behaviour ships with its test, a bug fix with the reproducing test first (run the
+develop {{SKILL}}). Run them on the real runner, the whole suite once at the end, and show
+the output, every failure named ({{LAW:verify-before-asserting}}). Untestable: name the gap,
+never invent a test; a real test out of scope: stop rather than ship untested behaviour
+silently ({{LAW:one-intent-one-act}}, {{LAW:cure-the-cause}}).
 <!-- LEAN:end -->
 
 ### {{DOCTRINE:prove-the-gate}} Prove the Gate

package/src/skills/brainstorm/builder-check.md

@@ -0,0 +1,16 @@
+# {{SKILL}}: brainstorm — builder check
+
+The spec's author cannot read it cold: a re-read inherits the framing that wrote it. So a
+fresh reader does.
+
+1. **Dispatch one fresh subagent** — never resume one; isolation and the no-subagent
+   fallback are as in [fresh-eyes](../fresh-eyes.md) step 3. Brief it with the spec file
+   alone: *"You are a capable builder in this domain who must plan the work from this
+   document and cannot reach its author. List, most important first, the questions where a
+   wrong guess would cost real rework. Skip what a builder may rightly decide."*
+2. **Sort its questions into three piles.** *Answered* — the answer exists (the code, the
+   chat, the docs): write it into the spec. *Minor* — settle it yourself and mark it
+   **your call** in the ledger ({{DOCTRINE:declare-the-judgment-calls}}). *Theirs* — only the
+   user can decide: ask ONE numbered round, most important first, then update the spec.
+3. **One round only.** Do not re-run the check on the updated spec; what is still open
+   after the user's answers stays in the ledger as open.