geneseed 3.12.0 → 3.14.0

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,36 @@ 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. `name` is how a
+ * host-only passage's visible label spells the host. One row per host: the family table, the
+ * host list and both marker patterns below are read off it.
+ */
+const DOC_HOSTS = {
+  opencode: { family: 'opencode', name: 'OpenCode' },
+  claude: { family: 'claude', name: 'Claude Code' },
+  openclaude: { family: 'claude', name: 'OpenClaude' },
+  bob: { family: 'claude', name: 'IBM Bob' },
+};
+export const HOST_FAMILY = Object.fromEntries(
+  Object.entries(DOC_HOSTS).map(([id, h]) => [id, h.family]));
+export const HARNESSES = Object.keys(DOC_HOSTS);
+const anyOf = (words) => `(?:${words.join('|')})`;
+/**
+ * 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 = anyOf(HARNESSES);
+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,15 +329,17 @@ 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';
 }
 
 /**
  * Every open has a matching close, with no nesting.
  *
- * A marker inside a ``` fence is example text, not a marker (the same rule `sliceSection`
- * uses). Its purpose is to FAIL OPEN: an unbalanced marker leaves the body untouched, so a
- * typo can never blank the rest of a page.
+ * A marker inside a ``` fence is example text, not a marker (the same rule the frontend's
+ * outline uses). Its purpose is to FAIL OPEN: an unbalanced marker leaves the body untouched,
+ * so a typo can never blank the rest of a page.
  *
  * EXPORTED FOR THE AUTHORING GATE, in the shape `installAgentEntryOf` established: failing
  * open means a typo is INVISIBLE in the rendered output — the page simply shows everything,
@@ -309,7 +368,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 = anyOf(Object.values(DOC_HOSTS).map((h) => h.name));
+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 +389,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,23 +413,21 @@ 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;
 }
 
-// ---- slugs and section slicing ----------------------------------------------------------
+// ---- heading slugs -----------------------------------------------------------------------
 
 const SLUG_STRIP_RE = new RegExp(`[^a-z0-9${WHITESPACE}-]`, 'g');
 const SLUG_WS_RE = new RegExp(`[${WHITESPACE}]+`, 'g');
 const SLUG_DASH_RE = /-+/g;
-const HEADING_RE = /^(#{1,6})\s+(.+?)\s*$/;
 
 /**
- * The same rules the frontend's `slug()` uses, so a registry `anchor` written against a
- * heading matches the id the renderer assigns.
+ * The same rules the frontend's `slug()` uses for the id it gives a rendered heading.
  *
  * `WHITESPACE` and `stripWhitespace` rather than `\s` and `trim()` — see `WHITESPACE`'s own
  * docblock for the measured set of characters where this matters.
@@ -380,45 +438,6 @@ export function slugifyHeading(text) {
   return s.replace(/^-+|-+$/g, '');
 }
 
-/**
- * The body trimmed to one heading's section.
- *
- * Returns `[body, ok]`; `ok === false` (with the ORIGINAL body) when the anchor is
- * missing, so the caller falls back to the whole document. An H1 slice stops at the first
- * H2 — `max(level, 2)` — so it captures an intro paragraph rather than the whole file.
- */
-export function sliceSection(body, anchor) {
-  const lines = splitLines(body);
-  let start = -1;
-  let startLevel = 0;
-  let inFence = false;
-  for (let i = 0; i < lines.length; i += 1) {
-    const ln = lines[i];
-    if (ln.startsWith('```')) { inFence = !inFence; continue; }
-    if (inFence) continue;
-    const m = HEADING_RE.exec(ln);
-    if (!m) continue;
-    if (slugifyHeading(m[2]) === anchor) {
-      start = i;
-      startLevel = Math.max(m[1].length, 2);
-      break;
-    }
-  }
-  if (start < 0) return [body, false];
-  const out = [lines[start]];
-  inFence = false;
-  for (let j = start + 1; j < lines.length; j += 1) {
-    const ln = lines[j];
-    if (ln.startsWith('```')) { inFence = !inFence; out.push(ln); continue; }
-    if (inFence) { out.push(ln); continue; }
-    const m = HEADING_RE.exec(ln);
-    if (m && m[1].length <= startLevel) break;
-    out.push(ln);
-  }
-  while (out.length && out[out.length - 1].trim() === '') out.pop();
-  return [`${out.join('\n')}\n`, true];
-}
-
 // ---- the endpoints -----------------------------------------------------------------------
 
 function findDocPage(pageId) {
@@ -472,23 +491,20 @@ function glossary(state, page) {
  * what gates the github-shaped deep links in the UI. Both come from `originDisplay()`,
  * which shells out to `git remote get-url` (the `git` row in `ALLOWED_SPAWNS`).
  *
- * `version` IS NOT WHAT IT LOOKS LIKE, and it is the shape this page has always had rather than
- * a shortcut here. It reads a `version` key off the status snapshot and THERE IS NO SUCH KEY —
- * the snapshot spells the fingerprints `source_fp` / `installed_fp` / `version_verdict`. So the
- * field is `{}`, always, and `sd.version || {}` reproduces the EXPRESSION rather than the
- * constant: if the key ever appears, the page gains it without another edit.
+ * `version` carries the status snapshot's fingerprints under the names the About page reads.
+ * It used to read a `version` key the snapshot never had, so the page's build rows were
+ * always empty; the snapshot spells them `installed_fp` / `source_fp` / `version_verdict`.
  *
  * THERE IS NO INTERPRETER FIELD, and the absence is deliberate — see `apiSetup` in
  * `api.mjs`, which spells the same absence for the same reason.
- *
- * `statusData()` is called for one dead field, and deliberately: this page has always paid that
- * cost, and skipping it would answer faster in a way no gate measures and no user asked for.
  */
 function about(state) {
   const sd = statusData();
   const od = originDisplay();
   return {
-    version: sd.version || {},
+    version: {
+      installed_fp: sd.installed_fp, source_fp: sd.source_fp, verdict: sd.version_verdict,
+    },
     theme: state.theme,
     emit: state.emit,
     deployed: deployed(state),
@@ -510,7 +526,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 };
 }
@@ -538,18 +555,10 @@ export function apiDocsPage(state, pageId, harnessName = null) {
  */
 const KIND_ROUTES = {
   markdown: (state, pageId, page, hn) => {
-    let body = readDocSource(page.source);
-    let anchor = page.anchor ?? null;
-    // A successful slice drops the anchor: the heading is already at the top, so the
-    // client must not also try to scroll to it.
-    if (anchor && page.slice) {
-      const [sliced, ok] = sliceSection(body, anchor);
-      body = sliced;
-      if (ok) anchor = null;
-    }
-    body = rewriteDocLinks(stripHarnessBlocks(body, hn), page.source, idsByRel());
+    const body = rewriteDocLinks(stripHarnessBlocks(readDocSource(page.source), hn),
+      page.source, idsByRel());
     return { id: pageId, title: page.title, kind: 'markdown', body,
-      source: page.source, anchor, links: resolveLinks(state, body) };
+      source: page.source, links: resolveLinks(state, body) };
   },
   concept: (state, pageId, page, hn) => {
     const body = rewriteDocLinks(subCounts(state, stripHarnessBlocks(page.body ?? '', 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.14.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.

package/src/bricks/characterize.md

@@ -0,0 +1,17 @@
+---
+name: characterize
+description: Pin what legacy code does today with characterization tests, touching tests only.
+effect: mutate
+agent: tester
+outcomes: pass, fail
+---
+For the card's change point (with no card, the code the requirement names), write tests that pin
+what the code DOES today, not what it should do: assert a value you expect to be wrong, run it,
+and copy the observed value in. Touch only test files — never production code.
+
+Pin odd behaviour as it is and name it in the test's title; do not fix it here. If LOOP.md's notes
+list surviving mutants for this card, add the assertions that kill them.
+
+Report `pass` once the new tests run green against the unchanged code.
+Report `fail` if the code cannot be put under test without breaking a dependency first — that is
+a refactor in its own right — naming the dependency.

package/src/bricks/ci-fix.md

@@ -11,7 +11,8 @@ guess from the check's title, before changing anything.
 Touch only what that failure requires; this is a repair, not a chance to improve the pipeline
 along the way.
 
-Report `pass` once the named check is fixed and green.
+Report `pass` once the named check is fixed and green LOCALLY — CI itself is re-read after the
+push, not here.
 
 Report `fail` if the check cannot be fixed from this repo alone (an infra outage, a flake with no
 reproducible cause, a required secret that is missing), naming why.

package/src/bricks/ci-triage.md

@@ -0,0 +1,20 @@
+---
+name: ci-triage
+description: Read the failing CI checks for this commit and pick one code failure to fix, or stop.
+effect: read
+agent: explorer
+outcomes: more, done
+---
+Key on the commit, not the branch: `gh run list --commit <HEAD sha> --json databaseId,status,conclusion`.
+A commit pushed moments ago may not have a run yet — poll that command for up to ~2 minutes
+before concluding none exists. Wait on a pending run with `gh run watch <id>`, then read
+`gh run view <id> --log-failed` — never guess from a check's title. Classify each failure as
+code, flaky or infra. Never edit any file. `ci-repair` needs CI to run on `loop/*` branches: if
+still no run after that poll, write "CI does not run for <sha>" to a file in the OS temp
+directory and report `done` with that file's path — never as green.
+
+Write the classification, one failure per line, to a file in the OS temp directory and report
+that file's path with the outcome. Report `more` with a card for ONE code failure:
+{"intent": "<fix check X: cause>", "writeSet": ["<files the fix touches>"],
+ "actions": ["<each of: format, imports, rename, logic, new-file, api, delete, architecture>"]}
+Report `done` when CI is green for HEAD, or only flaky or infra failures remain — naming them.

package/src/bricks/compat-check.md

@@ -0,0 +1,16 @@
+---
+name: compat-check
+description: Confirm consumers of the old and the new interface both still work after this iteration.
+effect: read
+agent: tester
+outcomes: pass, fail
+---
+Run the tests of every consumer this change can reach — those still on the old shape as well as
+those already moved — and, where the repo records consumer contracts (Pact, Spring Cloud
+Contract), the provider verification against them. In a contract step, where the old shape is
+removed on purpose, check instead that no consumer still uses it. Never edit any file: send
+reports to the OS temp directory.
+
+Report `pass` if every consumer works. Report `fail` naming the broken consumer, the check and
+its raw failure, written to a file in the OS temp directory — report that file's path with the
+outcome.

package/src/bricks/done-check.md

@@ -0,0 +1,16 @@
+---
+name: done-check
+description: Verify the requirement is met — every acceptance criterion proven by a passing test or a stated manual check.
+effect: read
+agent: reviewer
+outcomes: pass, fail
+---
+Read the requirement's acceptance criteria — `specs/<slug>/spec.md` when the branch has one, else
+the requirement in LOOP.md — and the branch's full diff against its base. Run the suite. For
+every criterion, name the test that proves it, or the manual check (what to do, what to see) when
+no test can. Never edit any file. Judge only the stated criteria — never style or extras.
+
+Report `pass` only if every criterion maps to a passing test or a stated manual check.
+Report `fail` otherwise: write each unmet criterion, one per line, with what is missing (no test,
+a failing test, a half-built behaviour) to a file in the OS temp directory and report that file's
+path — the next iteration's `identify` builds from it.

package/src/bricks/fitness-define.md

@@ -0,0 +1,22 @@
+---
+name: fitness-define
+description: Encode the requirement's architecture rule as a test, with an allowlist of today's violations.
+effect: mutate
+agent: architect
+gate: human
+outcomes: pass, fail
+---
+Turn the requirement's architecture rule into an executable test in the suite, with the repo's
+own tools first: ArchUnit for Java (a `FreezingArchRule`, whose violation store is the
+allowlist), then dependency-cruiser, import-linter, eslint-plugin-boundaries or size-limit.
+Record today's violations in an allowlist beside the test so the suite stays green — each later
+iteration removes one entry. Touch only the test, its allowlist and the tool's test-scoped setup,
+and declare the tool's generated store as a glob in the write set (`--write-set '**/archunit_store/**'`
+— single-quote it, the same as any glob in `--write-set`).
+
+The user reviews the rule before the loop continues: write the rule in one sentence, the test's
+path, the allowlist's path and its entry count to a file in the OS temp directory and report that
+file's path with the outcome.
+
+Report `pass` once the test runs green with the allowlist in place. Report `fail` if the rule
+cannot be checked deterministically, with the note file naming what is ambiguous.

package/src/bricks/flake-check.md

@@ -0,0 +1,17 @@
+---
+name: flake-check
+description: Rerun the card's test until it proves stable — a retry or a sleep is not a fix.
+effect: read
+agent: tester
+outcomes: stable, flaky
+---
+Rerun the card's test 20 times alone, then 20 with its suite, as `flake-repro` did (Maven: a
+loop of `mvn test -Dtest=<Class>#<method>`, shuffled). Never edit any file.
+
+Read this iteration's diff first. Polling on the awaited condition (Awaitility
+`await().atMost(…).until(…)`, `waitFor`) in place of a fixed sleep is a fix; adding a sleep or
+raising an existing timeout is not, and neither is a retry (`rerunFailingTestsCount`,
+`@RetryingTest`, `jest.retryTimes`) — report `flaky` naming it, whatever the runs say.
+
+Report `stable` only on 0 failures in all runs. Report `flaky` otherwise, with the failure count
+and one failure's output in a file in the OS temp directory — report that file's path.

package/src/bricks/flake-repro.md

@@ -0,0 +1,18 @@
+---
+name: flake-repro
+description: Confirm which suspected tests are flaky by repeated runs, before anything is fixed.
+effect: read
+agent: tester
+outcomes: flaky, stable, broken
+---
+Run each suspected test the requirement names 20 times (or the N it gives) alone, then 20 with
+its suite in a shuffled order — no code change, no retry option. Maven: loop `mvn test
+-Dtest=<Class>#<method>` (multi-module: add `-pl <module> -Dsurefire.failIfNoSpecifiedTests=false`),
+shuffled with `-Dsurefire.runOrder=random` and, under JUnit 5,
+`-Djunit.jupiter.testmethod.order.default=org.junit.jupiter.api.MethodOrderer$Random`. Never
+`-Dsurefire.rerunFailingTestsCount`: it hides the failures you count. Never edit any file. Write
+each test as `<test>: <failures>/<runs>` with one failure's output to a file in the OS temp
+directory and report that file's path.
+
+Report `broken` if any test fails every run — a bug for `bugfix`, not a flake. Report `flaky` if a
+test failed some runs, listing the confirmed ones. Report `stable` if none failed.

package/src/bricks/identify.md

@@ -9,12 +9,15 @@ Read the requirement and the loop's history (LOOP.md, `git log --format=%(traile
 branch). If the requirement is fully met and the suite is green, report `done`.
 
 Otherwise pick the SMALLEST next change that moves the requirement forward and can be tested on
-its own. Report `more` with a card, as JSON:
-{"intent": "<one line>", "writeSet": ["<every file you expect to touch>"],
+its own — when the branch has `specs/*/spec.md`, its next unfinished task. If the latest note is
+`done-check`'s unmet criteria, report `more` with a card for one of them, never `done`. Report
+`more` with a card, as JSON:
+{"intent": "<one line>", "writeSet": ["<every file ANY brick this iteration writes, tests/docs too>"],
  "actions": ["<each of: format, imports, rename, logic, new-file, api, delete, architecture>"]}
 
 Declare every action honestly: the diff is scored again before commit, and anything outside the
 write set or under-declared escalates to a blocking stop. If LOOP.md's notes say the previous
-attempt was re-split, make this card strictly smaller than that one.
+attempt was re-split, make this card strictly smaller than that one. The card obeys every
+instruction in the template's `rules` (e.g. its intent cites the proof that code is unused).
 
 Never edit, create or delete any file: this brick only reads.

package/src/bricks/migration-plan.md

@@ -0,0 +1,21 @@
+---
+name: migration-plan
+description: Plan a breaking interface change as expand, migrate each consumer, contract — for the user to review.
+effect: read
+skill: migrate
+gate: human
+outcomes: pass, fail
+---
+Following the migrate skill, plan the change as ordered steps: expand (add the new shape beside
+the old), migrate (one consumer or call-site group per step), contract (remove the old shape).
+Every step must leave the system deployable and fit one `identify` card. Name the contract files
+the expand and contract steps touch — API specs, schema migrations, event schemas. Never edit any
+file.
+
+The user reviews the plan before the loop continues: write the steps, one per line, then the
+contract files, to a file in the OS temp directory and report that file's path with the outcome.
+Those files belong in LOOP.md's `contracts`, so the expand and contract steps stop for a human:
+the user adds any the template's defaults miss to LOOP.md's `contracts` before answering ok.
+
+Report `pass` with the plan. Report `fail` if no backward-compatible path exists, naming what
+forces the break.

package/src/bricks/mutation-check.md

@@ -0,0 +1,18 @@
+---
+name: mutation-check
+description: Prove the new tests bite, by mutation testing scoped to the code the card names.
+effect: read
+agent: tester
+outcomes: pass, fail, unavailable
+---
+Run the project's mutation tool scoped to the production code the card's intent names. Java: PIT
+first — `mvn test-compile org.pitest:pitest-maven:mutationCoverage -DtargetClasses=<fq.Class*>
+-DreportsDirectory=<OS temp dir> -DtimestampedReports=false`, or Gradle's `pitest` task; else
+Stryker, mutmut or cargo-mutants. Never edit any file — reports and caches (.mutmut-cache,
+mutants.out/, .stryker-tmp/) go to the OS temp dir, or are removed.
+
+Report `pass` if no surviving mutant sits on a line the new tests target. Report `fail` with each
+survivor as `file:line`, the mutation, and the assertion that would kill it, in a file in the OS
+temp directory — report its path. Report `unavailable` when no tool is configured — the pom lacks
+`pitest-junit5-plugin` under JUnit 5, or Gradle does not apply `info.solidsoft.pitest`: never add
+it to the build; write what you checked to a temp file and report its path.

package/src/bricks/plan.md

@@ -8,10 +8,10 @@ outcomes: pass
 Read the requirement and survey the code it touches. Split the work into an ordered list of
 small iterations, each one sized to a single `identify` card — one testable change apiece.
 
-Do not edit any code; this brick only plans it. Report `pass` with a card whose intent carries
-the ordered list, one iteration per line, so it lands in LOOP.md's notes for `identify` to work
-through one at a time:
-{"intent": "<iteration 1>\n<iteration 2>\n...", "writeSet": [], "actions": []}
+Do not edit any code; this brick only plans it. `plan` is not an iteration head, so its card is
+never recorded — write the ordered list, one iteration per line, to a file in the OS temp
+directory (never inside the worktree) and report that file's path with the outcome, so it is
+recorded into LOOP.md's notes. Report `pass`.
 
-If the requirement cannot be split — it is already one atomic change — say so in the intent and
-let the loop proceed with a single iteration.
+If the requirement cannot be split — it is already one atomic change — say so in the note file
+and let the loop proceed with a single iteration.

package/src/bricks/red-test.md

@@ -0,0 +1,16 @@
+---
+name: red-test
+description: Write the failing test for the card's intent before any production code changes.
+effect: mutate
+agent: tester
+outcomes: red, green, untestable
+---
+Write the smallest test that expresses the card's intent at its seam, touching only the test
+files in the card's `writeSet` — never production code; making it pass is `apply`'s job. Run it.
+
+Report `red` if it fails FOR THE REASON the intent states — not an import error, a typo, or a
+broken fixture in the test itself.
+Report `green` if it already passes: the behaviour exists, so keep the test as coverage.
+Report `untestable` if no seam lets a test reach the behaviour without changing production code
+first, naming what blocks it. If the card's `writeSet` names no test file, report `untestable`
+and say so.