geneseed 3.12.0 → 3.13.0

package/js/loop/score.mjs

@@ -104,23 +104,60 @@ export function parseNumstat(text) {
 
 const slash = (p) => p.replaceAll('\\', '/');
 
-export function actualRisk(declared, files, { writeSet = [], contracts = [], overrides = {} } = {}) {
+// The one glob dialect of the loop — a template's `contracts` and `ignoreDeletions`, and LOOP.md's
+// own `contracts`. `*` and `?` stay inside a path segment; `**` crosses segments, and `**/` may
+// match no directory at all, so `**/yarn.lock` covers the root one too. Both sides are
+// slash-normalised first, so a backslash is a separator, never an escape. Hand-rolled because
+// this module may import nothing but node builtins (see the docblock above); a plain path is a
+// glob that matches only itself, so exact-path contracts keep working.
+// A leading `./` or `/` is dropped on both sides: every path here is repo-relative.
+// ponytail: runs of `**/` and `*` collapse first, so stacked wildcards cannot compound; what
+// remains is the regex engine's backtracking over several separate `**` (O(n^k) on a near miss).
+// Patterns come from the template author or the user, never from untrusted input — a linear
+// matcher is the upgrade if that ever changes.
+const globPath = (p) => slash(String(p)).replace(/^(?:\.?\/)+/, '');
+
+export function globMatch(pattern, file) {
+  const g = globPath(pattern).replace(/\*{3,}/g, '**').replace(/(?:\*\*\/){2,}/g, '**/');
+  let re = '';
+  for (let i = 0; i < g.length; i += 1) {
+    const c = g[i];
+    if (c === '*' && g[i + 1] === '*') {
+      i += 1;
+      if (g[i + 1] === '/') { i += 1; re += '(?:.*/)?'; } else re += '.*';
+    } else if (c === '*') re += '[^/]*';
+    else if (c === '?') re += '[^/]';
+    else re += c.replace(/[.+^${}()|[\]]/g, '\\$&');
+  }
+  return new RegExp(`^${re}$`).test(globPath(file));
+}
+
+const matchesAny = (globs, file) => globs.some((g) => globMatch(g, file));
+
+export function actualRisk(declared, files, {
+  writeSet = [], contracts = [], ignoreDeletions = [], overrides = {},
+} = {}) {
   const w = { ...WEIGHTS, ...overrides };
   let score = declared;
   const reasons = [];
+  // A write-set entry is a glob too (a plain path matches itself): a tool's generated store,
+  // ArchUnit's archunit_store/**, cannot be named file by file before the tool writes it. Only an
+  // entry with a literal segment globs: a wildcard-only one (`**`, `**/*.java`) would declare the
+  // whole repo, so it stays exact-match — matching nothing, the diff fails closed.
   const inSet = new Set(writeSet.map(slash));
-  const outside = files.filter((f) => !inSet.has(slash(f.file)));
+  const globs = writeSet.filter((g) => globPath(g).split('/').some((seg) => seg && !/[*?]/.test(seg)));
+  const outside = files.filter((f) => !inSet.has(slash(f.file)) && !matchesAny(globs, f.file));
   if (outside.length) {
     score = Math.max(score, 0.8);
     reasons.push(`outside the write set: ${outside.map((f) => slash(f.file)).join(', ')}`);
   }
-  const deleted = files.reduce((n, f) => n + f.deleted, 0);
+  // ignoreDeletions only leaves the deletion count: the write-set check above still saw the file.
+  const deleted = files.filter((f) => !matchesAny(ignoreDeletions, f.file)).reduce((n, f) => n + f.deleted, 0);
   if (deleted > DELETION_LINES) {
     score = Math.max(score, w.delete);
     reasons.push(`${deleted} lines deleted`);
   }
-  const contractSet = new Set(contracts.map(slash));
-  const hit = files.filter((f) => contractSet.has(slash(f.file)));
+  const hit = files.filter((f) => matchesAny(contracts, f.file));
   if (hit.length) {
     score = Math.max(score, w.api);
     reasons.push(`contract files: ${hit.map((f) => slash(f.file)).join(', ')}`);
@@ -129,8 +166,10 @@ export function actualRisk(declared, files, { writeSet = [], contracts = [], ove
 }
 
 export function decide(score, preset) {
+  if (!Object.hasOwn(PRESETS, preset)) {
+    throw new Error(`unknown preset ${JSON.stringify(preset)} — one of ${Object.keys(PRESETS).join(', ')}`);
+  }
   const t = PRESETS[preset];
-  if (!t) throw new Error(`unknown preset ${JSON.stringify(preset)} — one of ${Object.keys(PRESETS).join(', ')}`);
   if (score <= t[0]) return 'silent';
   if (score <= t[1]) return 'soft';
   return 'blocking';

package/js/loop/state.mjs

@@ -21,7 +21,23 @@
  * action — is excluded from every score and every read-brick porcelain check: it is never part
  * of the work being scored, and including it would make every action's own bookkeeping look
  * like an undeclared file touch.
+ *
+ * `writeLoopFile` IS THE ONLY WRITER. Every call site that persists LOOP.md — `cli.mjs`'s
+ * `withState` and `init`, and `registry.mjs`'s `setLoopPreset` — writes through it rather than
+ * through a bare `writeText(file, renderLoopFile(state))`, so a process killed mid-write can
+ * never leave a torn, half-written LOOP.md for the next `loop next`/`score`/`record` to choke
+ * on. `LOOP_FILE_TMP` sits BESIDE `LOOP_FILE` in the worktree, not inside the gitdir: the gitdir
+ * is resolved by `gitDirOf`, which can THROW on a malformed worktree link (X6 in `cli.mjs`), and
+ * every one of these three call sites must still be able to rewrite LOOP.md when that resolution
+ * fails or was never attempted (`setLoopPreset` has no gitdir concept at all). A temp file beside
+ * LOOP.md needs no new failure mode to reason about instead — it is exposed to `git status`, but
+ * only for the instant between the write and the rename (ordinarily unobservable; a crash in
+ * that window is the one case it lingers), and `LOOP_FILE_TMP` joins `LOOP_FILE` in both
+ * `filterPorcelain` and `scoreDiff`'s exclusion below for exactly that case: a lingering
+ * `LOOP.md.tmp` is the engine's own bookkeeping too, never scored work.
  */
+import { renameSync, unlinkSync } from 'node:fs';
+import { writeText } from '../lib/fs.mjs';
 import { declaredRisk, actualRisk, decide, worst, PRESETS, DEFAULT_PRESET } from './score.mjs';
 import { iterationLoop, ENGINE_MAX_ITERATIONS } from './graph.mjs';
 
@@ -29,6 +45,7 @@ const BEGIN = '<!-- loop-state:begin -->';
 const END = '<!-- loop-state:end -->';
 export const VERIFY_COMMAND = 'git add -A && git diff --cached --numstat | geneseed loop score --diff';
 export const LOOP_FILE = 'LOOP.md';
+export const LOOP_FILE_TMP = `${LOOP_FILE}.tmp`;
 const slash = (p) => String(p).replaceAll('\\', '/');
 
 export function renderLoopFile(state) {
@@ -38,6 +55,41 @@ export function renderLoopFile(state) {
     + `${BEGIN}\n\`\`\`json\n${JSON.stringify(state, null, 2)}\n\`\`\`\n${END}\n`;
 }
 
+const RETRYABLE_RENAME_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+
+/** Synchronous back-off between rename attempts — `Atomics.wait` on a throwaway
+ * `SharedArrayBuffer`, the stdlib's own blocking sleep with no dependency. */
+function backoff(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Rename `tmp` to `file`, retrying up to 3 attempts total on a transient Windows lock
+ * (EPERM/EACCES/EBUSY — an AV scanner or editor briefly holding the handle open) with a short
+ * back-off between attempts. A non-retryable error, or the 3rd retryable failure, removes the
+ * temp file (best-effort — a cleanup failure must not mask the real error) and rethrows.
+ * `renameFn` is an injectable seam for tests; production never passes it.
+ */
+export function renameWithRetry(tmp, file, renameFn = renameSync) {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      renameFn(tmp, file);
+      return;
+    } catch (e) {
+      if (attempt < 3 && RETRYABLE_RENAME_CODES.has(e.code)) { backoff(25 * attempt); continue; }
+      try { unlinkSync(tmp); } catch { /* best-effort cleanup; the rename error is what matters */ }
+      throw e;
+    }
+  }
+}
+
+/** `<file>.tmp` then `renameWithRetry` — the atomic write every LOOP.md persist goes through. */
+export function writeLoopFile(file, state) {
+  const tmp = `${file}.tmp`;
+  writeText(tmp, renderLoopFile(state));
+  renameWithRetry(tmp, file);
+}
+
 export function parseLoopFile(text) {
   const t = String(text).replace(/\r\n/g, '\n');
   const a = t.indexOf(BEGIN); const b = t.lastIndexOf(END);
@@ -49,11 +101,12 @@ export function parseLoopFile(text) {
 const head = (state) => iterationLoop(state.graph).nodes[0];
 const fmt = (n) => Number(n).toFixed(1);
 
-export function initState({ title, requirement, graph, preset = DEFAULT_PRESET }) {
-  if (!PRESETS[preset]) throw new Error(`unknown preset ${JSON.stringify(preset)}`);
+/** `contracts`: extra globs (`loop init --contracts`), appended after the graph's own. */
+export function initState({ title, requirement, graph, preset = DEFAULT_PRESET, contracts = [] }) {
+  if (!Object.hasOwn(PRESETS, preset)) throw new Error(`unknown preset ${JSON.stringify(preset)}`);
   const loop = iterationLoop(graph);
   const state = {
-    v: 1, title, requirement, preset, contracts: [], graph, node: graph.start,
+    v: 1, title, requirement, preset, contracts: [...(graph.contracts ?? []), ...contracts], graph, node: graph.start,
     status: 'running', awaiting: null, reason: null,
     iteration: loop.nodes.includes(graph.start) ? 1 : 0,
     card: null, validated: false, pendingVerify: false, closing: false, counters: {},
@@ -93,6 +146,7 @@ export function trailers(state) {
     `Loop-Threshold: ${state.preset} ${fmt(silent)}/${fmt(soft)}`,
     `Loop-Decision: ${state.current.decision ?? 'silent'}${state.current.amended ? ' (amended)' : ''}`,
     `Loop-Tests: ${state.tests}`,
+    ...(state.current.gates ? [`Loop-Gates: ${state.current.gates.join(',')}`] : []),
   ].join('\n');
 }
 
@@ -102,6 +156,7 @@ function finishUnit(state, committed) {
       iteration: state.iteration, bricks: [...new Set(state.visited)],
       declared: state.current.declared ?? 0, actual: state.current.actual ?? state.current.declared ?? 0,
       decision: state.current.decision ?? 'silent', tests: state.tests, intent: state.card?.intent ?? '',
+      ...(state.current.gates ? { gates: state.current.gates } : {}),
     });
   }
   // The unit is committed (or was empty): the tree is clean again, so the read-brick check
@@ -139,6 +194,10 @@ export function nextStep(state, bricks) {
     node: state.node, iteration: state.iteration, effect: brick.effect, agent: brick.agent,
     skill: brick.skill, outcomes: brick.outcomes, prompt: brick.body, card: state.card,
     notes: state.notes, validate: brick.effect === 'mutate' && !state.validated,
+    // The template's own rules (a cited proof before a deletion, no retries as a flake fix) are
+    // its `rules` list; every brick gets them, not only the head that reads LOOP.md. Never the
+    // description: that is the catalogue blurb, and sending it would dilute the rules.
+    ...(state.graph.rules?.length ? { rules: state.graph.rules } : {}),
   };
 }
 
@@ -170,9 +229,9 @@ export function scoreDiff(state, files) {
   assertRunning(state);
   if (!state.pendingVerify) throw new Error('no iteration to verify: `geneseed loop next` has not asked for one');
   if (!Array.isArray(state.contracts) || state.contracts.some((c) => typeof c !== 'string')) {
-    throw new Error('LOOP.md: contracts must be a list of file paths');
+    throw new Error('LOOP.md: contracts must be a list of file paths or globs');
   }
-  const scored = files.filter((f) => slash(f.file) !== LOOP_FILE);
+  const scored = files.filter((f) => slash(f.file) !== LOOP_FILE && slash(f.file) !== LOOP_FILE_TMP);
   if (!scored.length) {
     // A closing unit (reached $close with a mutate already visited) finishes as done even
     // when this is its second empty diff in a row: there is nothing left to retry into.
@@ -184,7 +243,8 @@ export function scoreDiff(state, files) {
   }
   state.emptyStreak = 0;
   const { score, reasons } = actualRisk(state.current.declared ?? 0, scored, {
-    writeSet: state.card?.writeSet ?? [], contracts: state.contracts ?? [], overrides: state.graph.weights,
+    writeSet: state.card?.writeSet ?? [], contracts: state.contracts ?? [],
+    ignoreDeletions: state.graph.ignoreDeletions ?? [], overrides: state.graph.weights,
   });
   const decision = decide(score, state.preset);
   state.current.actual = score;
@@ -223,12 +283,13 @@ function allowedEntries(graph, v) {
 }
 
 // Porcelain lines are `XY <path>`; strip the 2-char status + space, slash-normalise, drop
-// LOOP.md rows (the engine rewrites it on every action — it is never part of the scored work).
+// LOOP.md rows (the engine rewrites it on every action — it is never part of the scored work)
+// and a lingering LOOP.md.tmp (the atomic writer's own sibling — see `writeLoopFile`'s docblock).
 function filterPorcelain(porcelain) {
   const lines = porcelain.split(/\r?\n/).filter((line) => {
     if (!line) return false;
     const path = line.slice(3).replace(/^"|"$/g, '');
-    return slash(path) !== LOOP_FILE;
+    return slash(path) !== LOOP_FILE && slash(path) !== LOOP_FILE_TMP;
   });
   return lines.join('\n').trimEnd();
 }
@@ -239,7 +300,7 @@ function isSetupUnit(state) {
   return state.iteration === 0 && !iterationLoop(state.graph).nodes.includes(state.graph.start);
 }
 
-export function recordOutcome(state, bricks, outcome, { card = null, porcelain = null } = {}) {
+export function recordOutcome(state, bricks, outcome, { card = null, porcelain = null, note = '' } = {}) {
   assertRunning(state);
   if (state.pendingVerify) throw new Error('the iteration is closed: run `geneseed loop score --diff` first');
   const from = state.node;
@@ -258,11 +319,33 @@ export function recordOutcome(state, bricks, outcome, { card = null, porcelain =
   if (filteredPorcelain !== null) state.snapshot = filteredPorcelain;
   if (card) state.card = card;
   if (from === 'test') state.tests = outcome;
+  // A finding a brick needs to survive the unit (the ordered plan `plan` produced, `review`'s
+  // `fail` findings) — pushed before the transition below, so it lands in `notes` even when
+  // this call closes the unit, re-splits, or stops the loop. `notes` is never reset mid-run
+  // (only `exhaust`'s own push and `decideAwaiting` add to it otherwise), so it survives
+  // `resetUnit`/`finishUnit` the same way the research's fact 1 says a card does not.
+  if (note) state.notes.push(`iteration ${state.iteration} (${from}): ${note}`);
   state.visited.push(from);
 
   const edge = state.graph.edges.find((e) => e.from === from && e.on === outcome);
   if (!edge) throw new Error(`no edge from ${from} on ${outcome}`);
-  if (edge.to === '$stop') return stop(state, `${from} reported ${outcome}`);
+  if (brick.gate === 'human' && (!brick.gateOn || brick.gateOn.includes(outcome))) {
+    state.status = 'awaiting';
+    state.awaiting = { kind: 'gate', node: from, outcome, ...(note ? { note } : {}) };
+    return { awaiting: state.awaiting };
+  }
+  return transition(state, bricks, from, edge);
+}
+
+/**
+ * Follow `edge` out of `from` — the second half of `recordOutcome`, and what `decide ok` runs on
+ * a held gate. THE GATE HOLDS THE WHOLE TRANSITION: whatever the edge would do (ask for the diff
+ * score, close the unit, stop, count a re-entry and exhaust a ring) happens only here, after the
+ * user's `ok` — never before it, so nothing is scored, committed, re-split or stopped by the
+ * transition while the gate waits. A held `$stop` edge still waits: the user may `amend` it.
+ */
+function transition(state, bricks, from, edge) {
+  if (edge.to === '$stop') return stop(state, `${from} reported ${edge.on}`);
   const mutated = state.visited.some((n) => bricks.get(n)?.effect === 'mutate');
   if (edge.to === '$close') {
     if (mutated) { state.closing = true; state.pendingVerify = true; return { verify: true }; }
@@ -288,8 +371,10 @@ export function recordOutcome(state, bricks, outcome, { card = null, porcelain =
 export function decideAwaiting(state, bricks, verdict, note = '') {
   if (state.status !== 'awaiting') throw new Error('nothing is awaiting a decision');
   if (!['ok', 'no', 'amend'].includes(verdict)) throw new Error(`verdict must be ok, no or amend, not ${JSON.stringify(verdict)}`);
-  const { kind } = state.awaiting;
+  const held = state.awaiting;
+  const { kind } = held;
   state.awaiting = null; state.status = 'running';
+  if (kind === 'gate') return decideGate(state, bricks, verdict, note, held);
   if (note) state.notes.push(`iteration ${state.iteration} (${kind}, ${verdict}): ${note}`);
   if (kind === 'launch') {
     return verdict === 'ok' ? { resumed: true } : stop(state, `graph ${verdict === 'no' ? 'rejected' : 'to amend'}${note ? `: ${note}` : ''}`);
@@ -320,3 +405,32 @@ export function decideAwaiting(state, bricks, verdict, note = '') {
   resetUnit(state); state.node = head(state); state.snapshot = '';
   return { discard: true };
 }
+
+const GATE_MAX_AMENDS = 3;
+
+/**
+ * The answer to a held `gate: human` transition. Every verdict leaves a note — with or without
+ * the user's words — so the run's notes say each gate was answered and how. `ok` follows the held
+ * edge and lists the node under the unit's `Loop-Gates`; `no` stops; `amend` re-runs the same
+ * node with the note in `notes` (its `validated` untouched — a mutate gate need not re-score —
+ * and its `counters` reset),
+ * `GATE_MAX_AMENDS` times per node per iteration (`gateAmends` is keyed `node@iteration` and never
+ * reset, so the next iteration's card — a new ADR, say — gets its own budget), and the next
+ * one stops: three rounds of review that did not converge are a conversation, not a loop.
+ */
+function decideGate(state, bricks, verdict, note, { node, outcome }) {
+  state.notes.push(`iteration ${state.iteration} (gate at ${node}, ${verdict})${note ? `: ${note}` : ''}`);
+  if (verdict === 'no') return stop(state, `gate rejected at ${node}${note ? `: ${note}` : ''}`);
+  if (verdict === 'amend') {
+    const key = `${node}@${state.iteration}`;
+    state.gateAmends = { ...state.gateAmends, [key]: (state.gateAmends?.[key] ?? 0) + 1 };
+    if (state.gateAmends[key] > GATE_MAX_AMENDS) return stop(state, `gate amended ${GATE_MAX_AMENDS} times at ${node}`);
+    // As an `actual` amend: the amendment changes what the unit does, so the ring budget
+    // restarts; the amend cap above still bounds the unit.
+    state.counters = {};
+    state.node = node;
+    return { resumed: true };
+  }
+  state.current.gates = [...new Set([...(state.current.gates ?? []), node])];   // once each, as Loop-Bricks
+  return transition(state, bricks, node, state.graph.edges.find((e) => e.from === node && e.on === outcome));
+}

package/js/maintain/setup.mjs

@@ -519,7 +519,7 @@ export function setupSummaryLines(theme, emit, out, root, ok) {
     lines.push(['ok', `${f.hookGroups} hook groups wired in ${f.settings}`]);
     if (!process.env.GENESEED_LLM) {
       lines.push(['info', 'memory learning is off until you set GENESEED_LLM '
-        + '(see docs/reference/environment.md)']);
+        + '(see docs/reference/env-context.md)']);
     }
   }
   if (emit === 'files') {

package/js/web/actions.mjs

@@ -40,6 +40,7 @@ import { withStdoutSwallowed } from '../inspect/diff.mjs';
 import { excludeAdd, excludeRemove } from '../inspect/excludes.mjs';
 import { setupBuildArgs } from '../build/generate.mjs';
 import { DEFAULT_PRESET, PRESETS } from '../loop/score.mjs';
+import { setLoopPreset } from '../loop/registry.mjs';
 import { frontmatter, memoryDropIndex } from '../hosts/hooks.mjs';
 import {
   HOSTS, bobConfigDir, claudeConfigDir, expanduser, openclaudeConfigDir,
@@ -577,6 +578,30 @@ export function apiExcludesMutate(state, body) {
   return action === 'add' ? excludeAdd(p) : excludeRemove(p);
 }
 
+// ---- loop preset picker ---------------------------------------------------------------------
+
+/**
+ * The Active tab's one write: rewrite a registered worktree's `LOOP.md` `preset` field.
+ * `setLoopPreset` throws for both refusals the brief requires `POST /api/loops/preset` to make —
+ * a `root` the registry does not know (no arbitrary path writes) and a `preset` outside
+ * `PRESETS` — and this is where those two throws are turned into the `NotFound` convention
+ * every other mutating route here already answers in, so the handler's catch (`4xx`, not the
+ * 500 a bare `Error` would fall to) covers this route the same way it covers `apiRulesMutate`'s
+ * unknown id. Anything else `setLoopPreset` throws — a corrupt `LOOP.md` that fails to
+ * parse, say — is not one of those two refusals and is rethrown as-is, so it falls through to
+ * the handler's 500 instead of being misreported as "not found".
+ */
+export function apiLoopsPresetMutate(state, body) {
+  const root = strOr(bget(body, 'root'));
+  const preset = strOr(bget(body, 'preset'));
+  try {
+    return { ok: true, loop: setLoopPreset(root, preset) };
+  } catch (e) {
+    if (e.message === 'unknown loop' || e.message.startsWith('unknown preset ')) throw new NotFound(e.message);
+    throw e;
+  }
+}
+
 // ---- MCP ----------------------------------------------------------------------------------
 
 export function apiMcp() {

package/js/web/api.mjs

@@ -27,6 +27,7 @@ import {
 import { frontmatter } from '../hosts/hooks.mjs';
 import { DEFAULT_PRESET, PRESETS } from '../loop/score.mjs';
 import { loadCatalog, catalogProblems } from '../loop/catalog.mjs';
+import { activeLoops } from '../loop/registry.mjs';
 import {
   SKILL_CLASS, entityStatus, loadRegistry, tuiInventory,
 } from '../inspect/inventory.mjs';
@@ -968,6 +969,17 @@ export function apiLoops(state) {
   };
 }
 
+/**
+ * The Active tab's read: every worktree `geneseed loop init` has registered, with its live
+ * `LOOP.md` state re-read on every call (`activeLoops` itself, not a cached copy — the registry
+ * stores identity only, see `js/loop/registry.mjs`). Takes no `state`-derived filtering: the
+ * registry is machine-wide, not scoped to this install's root, so a loop launched from a
+ * different project still shows up here.
+ */
+export function apiLoopsActive() {
+  return { loops: activeLoops() };
+}
+
 /** The source's release label, or null when it cannot be read. */
 function releaseLabel() {
   const v = sourceReleaseVersion({ config: CONFIG });
@@ -1018,4 +1030,5 @@ export const STATE_ROUTES = {
   '/api/rules': apiRules,
   '/api/mcp': apiMcp,
   '/api/loops': apiLoops,
+  '/api/loops/active': apiLoopsActive,
 };

package/js/web/docs.mjs

@@ -13,7 +13,7 @@
  *
  * THE `?harness=` QUERY PARAM IS the Docs selector, and it is the ONLY input to these
  * endpoints that is not the checkout itself — the one thing a test can vary. Every
- * filtering rule below is exercised by sending both values over one page.
+ * filtering rule below is exercised by sending each host over one page.
  */
 import { readdirSync } from 'node:fs';
 import path from 'node:path';
@@ -105,7 +105,7 @@ export function docGroups() {
     if (group === undefined) continue;
     const order = Object.hasOwn(meta, 'order') ? meta.order : 0;
     delete meta.order;
-    const page = { id, rel, ...meta };
+    const page = { id, rel, ...meta, section: sectionOf(meta) };
     if (body.trim()) page.body = body.replace(/\n+$/, '');
     group.pages.push([order, page]);
   }
@@ -113,15 +113,44 @@ export function docGroups() {
   for (const g of groups) {
     const entry = byId.get(g.id);
     // STABLE sort: equal orders keep filename order.
-    entry.pages = entry.pages
+    entry.pages = bySection(entry.pages
       .map((pair, i) => [pair[0], i, pair[1]])
       .sort((a, b) => (a[0] - b[0]) || (a[1] - b[1]))
-      .map((t) => t[2]);
+      .map((t) => t[2]));
     out.push(entry);
   }
   return out;
 }
 
+/** The heading a page without a `section:` is listed under, inside its part. */
+export const GENERAL_SECTION = 'General';
+
+/**
+ * A page's `section:` frontmatter, or `General`. Anything but a non-empty string falls back
+ * rather than throwing — `tests/unit/docs_tree.test.mjs` is where a bad value goes red.
+ */
+export function sectionOf(meta) {
+  const s = meta.section;
+  return typeof s === 'string' && s.trim() ? s.trim() : GENERAL_SECTION;
+}
+
+/**
+ * Pages already in `order:` order, regrouped so each section's pages sit together.
+ *
+ * SECTION ORDER IS THE SMALLEST `order:` AMONG ITS PAGES — which, on a list already sorted by
+ * order, is simply the order in which sections first appear. Within a section the pages keep
+ * their `order:` order. One rule for the list, the breadcrumb and prev/next alike, so the
+ * console never shows two orders for one part.
+ */
+export function bySection(pages) {
+  const runs = new Map();
+  for (const p of pages) {
+    if (!runs.has(p.section)) runs.set(p.section, []);
+    runs.get(p.section).push(p);
+  }
+  return [...runs.values()].flat();
+}
+
 // ---- markdown tables as data ------------------------------------------------------------
 
 /** One table row's cells; a `\|` inside a cell is kept as a literal bar. */
@@ -259,8 +288,27 @@ function subCounts(state, body) {
 
 // ---- harness filtering -----------------------------------------------------------------
 
-const HARNESSES = ['opencode', 'claude'];
-const HARNESS_OPEN_RE = /^\s*<!--\s*harness:(opencode|claude)\s*-->\s*$/;
+/**
+ * The Docs selector names a HOST; a tag names a host or a FAMILY. Bob and OpenClaude emit
+ * through the Claude engine, so a `claude` tag (page or block) is the Claude family and shows
+ * to all three of them, while `bob` / `openclaude` narrow to the one host. The same mapping as
+ * the console's host table (`web/src/lib/hosts.js`, its `docs` column).
+ */
+export const HOST_FAMILY = { opencode: 'opencode', claude: 'claude', openclaude: 'claude', bob: 'claude' };
+export const HARNESSES = Object.keys(HOST_FAMILY);
+/**
+ * A page or block tagged `tag` shows to `host`. Untagged content shows to every host. One tag
+ * names a host or a family; a LIST names hosts exactly, no family widening, because picking
+ * some hosts of a family is the only thing a list says that one tag cannot:
+ * `["claude", "openclaude"]` is Claude Code and OpenClaude, not Bob.
+ */
+export const harnessShows = (tag, host) => (Array.isArray(tag)
+  ? tag.includes(host)
+  : !tag || tag === host || tag === HOST_FAMILY[host]);
+/** A block's tag: `claude` alone, or `claude,openclaude` — the list, read as above. */
+const harnessTag = (raw) => (raw.includes(',') ? raw.split(/\s*,\s*/) : raw);
+const HOST_ID = '(?:opencode|claude|openclaude|bob)';
+const HARNESS_OPEN_RE = new RegExp(String.raw`^\s*<!--\s*harness:(${HOST_ID}(?:\s*,\s*${HOST_ID})*)\s*-->\s*$`);
 const HARNESS_CLOSE_RE = /^\s*<!--\s*\/harness\s*-->\s*$/;
 /**
  * The cheap presence test for the early-out. It must never be NARROWER than the open
@@ -272,7 +320,9 @@ const HARNESS_HINT_RE = /<!--\s*harness:/;
 export function normHarness(value, state) {
   const v = (value || '').trim().toLowerCase();
   if (HARNESSES.includes(v)) return v;
-  return /^(claude|openclaude)/.test(String(state.emit || '')) ? 'claude' : 'opencode';
+  // Emit names start with their host id (`claude-global`, `bob`, …); `files` reads OpenCode's.
+  const emit = String(state.emit || '');
+  return HARNESSES.find((h) => emit.startsWith(h)) || 'opencode';
 }
 
 /**
@@ -309,7 +359,8 @@ export function harnessBlocksBalanced(lines) {
  * the marker; the console has already filtered the block to the reader's host, so there the
  * label only repeats what the host selector says, and it goes with the marker.
  */
-const HOST_LABEL_RE = /^\s*\*\((OpenCode|Claude Code) only\)\*\s*$/;
+const HOST_NAME = '(?:OpenCode|Claude Code|OpenClaude|IBM Bob)';
+const HOST_LABEL_RE = new RegExp(String.raw`^\s*\*\(${HOST_NAME}(?: and ${HOST_NAME})* only\)\*\s*$`);
 
 export function stripHarnessBlocks(body, harnessName) {
   if (!HARNESS_HINT_RE.test(body)) return body;
@@ -329,7 +380,7 @@ export function stripHarnessBlocks(body, harnessName) {
     }
     if (!inFence) {
       const m = HARNESS_OPEN_RE.exec(line);
-      if (m) { keep = m[1] === harnessName; afterOpen = true; continue; }
+      if (m) { keep = harnessShows(harnessTag(m[1]), harnessName); afterOpen = true; continue; }
       if (HARNESS_CLOSE_RE.test(line)) { keep = true; continue; }
       if (labelSlot && HOST_LABEL_RE.test(line)) continue;
     }
@@ -353,8 +404,8 @@ function splitLines(s) {
 function visibleGroups(harnessName) {
   const groups = [];
   for (const g of docGroups()) {
-    if (g.harness && g.harness !== harnessName) continue;
-    const pages = g.pages.filter((p) => !p.harness || p.harness === harnessName);
+    if (!harnessShows(g.harness, harnessName)) continue;
+    const pages = g.pages.filter((p) => harnessShows(p.harness, harnessName));
     if (pages.length) groups.push({ ...g, pages });
   }
   return groups;
@@ -510,7 +561,8 @@ export function apiDocs(state, harnessName = null) {
   const groups = visibleGroups(hn).map((g) => ({
     id: g.id,
     label: g.label,
-    pages: g.pages.map((p) => ({ id: p.id, title: p.title, kind: p.kind })),
+    pages: g.pages.map((p) => ({ id: p.id, title: p.title, kind: p.kind, section: p.section,
+      ...(typeof p.description === 'string' ? { description: p.description } : {}) })),
   }));
   return { groups, harness: hn };
 }

package/js/web/routes.mjs

@@ -15,7 +15,7 @@
  * expose X?", which has nothing to do with sockets, daemons or gzip.
  */
 import { formatValue, isTruthy, parseJson } from '../lib/json.mjs';
-import { apiExcludesMutate, apiInstallToggle, apiMcpToggle, apiMemoryDelete, apiProfileSave, apiRulesMutate, apiRulesPromote, apiSelectView } from './actions.mjs';
+import { apiExcludesMutate, apiInstallToggle, apiLoopsPresetMutate, apiMcpToggle, apiMemoryDelete, apiProfileSave, apiRulesMutate, apiRulesPromote, apiSelectView } from './actions.mjs';
 import { apiActivityToggle } from './activity.mjs';
 
 /**
@@ -45,6 +45,10 @@ export const POST_ROUTES = new Map([
   ['/api/rules', [apiRulesMutate, true]],
   ['/api/rules/promote', [apiRulesPromote, true]],
   ['/api/profile', [apiProfileSave, true]],
+  // No `ok: false` arm: success returns `{ok: true, loop}`, and both refusals (unknown root,
+  // unknown preset) throw `NotFound`, which `doPost`'s catch answers 404 before this column is
+  // ever consulted — the same shape as `/api/memory/delete` and `/api/activity` above.
+  ['/api/loops/preset', [apiLoopsPresetMutate, false]],
 ]);
 
 /**

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": "3.12.0",
+  "version": "3.13.0",
   "description": "A portable, theme-able harness you implant once and use everywhere to grow a disciplined AI coding agent.",
   "keywords": [
     "ai",

package/src/agents/explorer.md

@@ -3,8 +3,8 @@
 > {{DESC_EXPLORER}}
 
 ## When to dispatch
-- A question needs sweeping many files or directories, but you only want the
-  conclusion — not the file contents in your context.
+- A question needs sweeping many files or directories, but only the conclusion
+  belongs in the main context — not the file contents.
 - Locating where something lives, how a subsystem fits together, or gathering
   facts scattered across the repo.
 - Your main context is small and the expensive reading should happen elsewhere.

package/src/agents/researcher.md

@@ -3,9 +3,9 @@
 > {{DESC_RESEARCHER}}
 
 ## When to dispatch
-- A question needs answers from *outside* the repository — the open web, a
-  vendor's docs, an upgrade guide, a specification — and you want the verified
-  findings, not the pages, in your context ({{DOCTRINE:context-economy}}).
+- A question needs verified answers from *outside* the repository. The open web, a
+  vendor's docs, an upgrade guide, a specification: the main context gets the verified
+  findings, not the pages ({{DOCTRINE:context-economy}}).
 - The research {{SKILL}} is running and the host can run subagents: this seat
   does the fetching and cross-checking so the main context stays small.
 - A migrate, forge-mcp, or ingest run needs a spec or changelog read before

package/src/bricks/README.md

@@ -29,4 +29,6 @@ override rather than hiding it.
 Start from `_template.md`, or ask the `brick-forge` skill to draft one for an agent or skill you
 already have. Keep the body to 4-10 lines of direct instruction, and end it with how the model
 should choose among the outcomes you declared — that sentence is what turns a vague brief into a
-loop that actually terminates.
+loop that actually terminates. If the brick finds something the next brick needs, write it to a
+file in the OS temp directory and report that file's path with the outcome — the loop skill
+records it as a note.

package/src/bricks/adr-challenge.md

@@ -0,0 +1,20 @@
+---
+name: adr-challenge
+description: Attack the ADR this iteration drafted; the user reviews the ADR that survives.
+effect: read
+agent: skeptic
+gate: human
+gateOn: pass
+outcomes: pass, fail
+---
+Read the ADR this iteration wrote as a skeptic reading it cold. Is a decision driver missing? Is
+a rejected option strawmanned? Is a consequence — cost, risk, the way back — left unstated? Does
+it contradict an accepted ADR in the same folder, or the code as it stands? A gate amendment in
+LOOP.md's notes for this ADR is a finding: report `fail` until the ADR answers it.
+
+Never edit any file — findings go back to `adr-draft`, which revises the ADR.
+
+Report `fail` only on findings that would change the decision or its consequences, never on
+wording or style: write each one to a file in the OS temp directory and report that file's path
+with the outcome. Report `pass` otherwise — the user then reviews the ADR before the loop
+continues: write its path and the decision in one line to a temp file and report that path.

package/src/bricks/adr-draft.md

@@ -0,0 +1,15 @@
+---
+name: adr-draft
+description: Write or revise one architecture decision record for the card's decision.
+effect: mutate
+agent: architect
+outcomes: pass
+---
+Write or revise the ADR file the card's write set names, in Nygard form: Status: Proposed,
+Context, Decision, Consequences — the costs as well as the gains — and at least two options
+considered, each with why it lost. Touch only that file; never change code.
+
+If LOOP.md's notes carry `adr-challenge` findings or a gate amendment for this ADR, answer each
+one: change the decision, or record it under Consequences.
+
+Report `pass` once the ADR is written.