geneseed 4.0.0 → 4.1.0

package/js/web/actions.mjs

@@ -42,7 +42,7 @@ import { setupBuildArgs } from '../build/generate.mjs';
 import { DEFAULT_PRESET, PRESETS } from '../loop/score.mjs';
 import { activeLoops, setLoopPreset } from '../loop/registry.mjs';
 import {
-  CLAUDE_STYLE, HOSTS, bobConfigDir, claudeConfigDir, expanduser, openclaudeConfigDir,
+  HOSTS, bobConfigDir, claudeConfigDir, expanduser, openclaudeConfigDir,
   opencodeConfigDir, resolvePath,
 } from '../hosts/hosts.mjs';
 import {
@@ -50,11 +50,10 @@ import {
   installState, installTargets, legacyProcessCarrierOfDir, modeOfDir, postureOfDir, trustOfDir,
 } from '../hosts/installs.mjs';
 import {
-  MCP_PRESETS, isDict, mcpApply, mcpCommented, mcpInstallTargets, mcpKnownNames, mcpLoad,
-  mcpMeta, mcpPresetBlock, mcpSave, mcpSetEnabled, mcpState,
+  isDict, mcpCommented, mcpInstallTargets, mcpLoad, mcpServerNames, mcpState,
 } from '../hosts/mcp.mjs';
-import { readText, isFile, isDir } from '../lib/fs.mjs';
-import { parseJson, formatRepr, formatValue, isTruthy } from '../lib/json.mjs';
+import { isFile, isDir } from '../lib/fs.mjs';
+import { formatRepr, formatValue, isTruthy } from '../lib/json.mjs';
 import { NO_WINDOW } from '../lib/proc.mjs';
 import { normcase, which, within } from '../lib/paths.mjs';
 import { stripWhitespace } from '../lib/text.mjs';
@@ -348,18 +347,20 @@ export function apiLoopsPresetMutate(state, body) {
 
 // ---- MCP ----------------------------------------------------------------------------------
 
+/**
+ * The MCP servers each active install ALREADY has, and nothing it could have. Read-only by
+ * decision (2026-10): which servers to wire depends on the user and on the host, so the console
+ * shows what is in each config and where that file lives, and the user edits it. There is no
+ * preset to add and no toggle, so nothing here ever rewrites a config — including
+ * `~/.claude.json`, which holds far more than MCP wiring.
+ */
 export function apiMcp() {
   const out = [];
   for (const [label, p, host, scope, root] of mcpInstallTargets()) {
     if (installState(root, host, scope) !== 'active') continue;
     const cfg = mcpLoad(p, host);
-    const servers = [];
-    for (const name of mcpKnownNames(cfg, host)) {
-      const [lbl, desc] = mcpMeta(name);
-      servers.push({ name, label: lbl, desc,
-        preset: Object.hasOwn(MCP_PRESETS, name),
-        state: mcpState(cfg, name, host) });
-    }
+    const servers = mcpServerNames(cfg, host)
+      .map((name) => ({ name, state: mcpState(cfg, name, host) }));
     out.push({ label, path: p, host, root, exists: isFile(p),
       commented: mcpCommented(p), servers });
   }
@@ -370,10 +371,8 @@ export function apiMcp() {
 /**
  * The MCP config paths a request body is allowed to name, as `path -> [path, host]`.
  *
- * LIFTED OUT OF `apiMcpToggle` BECAUSE IT NOW HAS A SECOND CALLER, not for tidiness. `/api/reveal`
- * hands a path to the desktop's file manager, and the allowlist is the whole security of that
- * endpoint exactly as it is of the toggle: an unlisted path must 404 before anything is opened.
- * Two copies of a security check drift, and the copy that drifts is the one nobody re-read.
+ * `/api/reveal` hands a path to the desktop's file manager, and this allowlist is the whole
+ * security of that endpoint: an unlisted path must 404 before anything is opened.
  *
  * It is rebuilt per call rather than cached: installs come and go while the daemon runs, and a
  * stale allowlist is wrong in both directions — refusing a real target, or naming a dead one.
@@ -386,67 +385,6 @@ export function mcpTargetPaths() {
   return known;
 }
 
-/**
- * Enable / disable / first-add one server.
- *
- * THE PATH COMES OUT OF THE REQUEST BODY, so the allowlist is the whole security of this
- * endpoint: `known` is built from the detected install targets and an unlisted path is a 404
- * before anything is read or written. Without it this is "write arbitrary JSON to an
- * arbitrary file", behind a CSRF token and nothing else.
- *
- * The Claude-shaped hosts are parsed ONCE, STRICTLY, and that exact object is what gets
- * rewritten — so the safety check and the value saved come from the same read, with no
- * time-of-check/time-of-use gap and no comment-stripper touching a string that contains
- * `,]`. A file that will not parse is refused rather than clobbered: it may be
- * `~/.claude.json`, which holds projects and history far beyond MCP wiring.
- */
-export function apiMcpToggle(state, body) {
-  const name = strOr(bget(body, 'name'));
-  const want = isTruthy(bget(body, 'enabled'));
-  const pathArg = strOr(bget(body, 'path'));
-  const known = mcpTargetPaths();
-  const hit = known.get(pathArg);
-  if (hit === undefined || !name) {
-    throw new NotFound(`mcp target ${pathArg || '(none)'}`);
-  }
-  const [p, host] = hit;
-  if (mcpCommented(p)) {
-    return { ok: false, error: 'config holds comments — edit it by hand to keep them' };
-  }
-  let cfg;
-  if (CLAUDE_STYLE.includes(host)) {
-    if (isFile(p)) {
-      let parsed;
-      try {
-        parsed = parseJson(readText(p));
-      } catch {
-        parsed = null;
-      }
-      if (!isDict(parsed)) {
-        return { ok: false,
-          error: "couldn't parse this config — edit it by hand to avoid data loss" };
-      }
-      cfg = parsed;
-    } else {
-      cfg = {};
-    }
-  } else {
-    cfg = mcpLoad(p);
-  }
-  if (mcpState(cfg, name, host) === 'absent') {
-    if (!Object.hasOwn(MCP_PRESETS, name)) {
-      return { ok: false, error: `unknown server '${name}'` };
-    }
-    if (!want) return { ok: false, error: `'${name}' is not configured` };
-    cfg = mcpApply(cfg, name, mcpPresetBlock(name, host), host);
-    cfg = mcpSetEnabled(cfg, name, true, host);
-  } else {
-    cfg = mcpSetEnabled(cfg, name, want, host);
-  }
-  mcpSave(p, cfg);
-  return { ok: true, name, state: mcpState(cfg, name, host) };
-}
-
 // ---- the harness selector ------------------------------------------------------------------
 
 /**

package/js/web/api.mjs

@@ -113,11 +113,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.

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,7 +18,7 @@
  */
 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,
@@ -43,7 +43,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]],

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.1.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/_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.

package/src/skills/brainstorm.md

@@ -15,12 +15,15 @@ the design is skipped.
    several goals or systems, separate them and take one at a time.
 2. **Interpret charitably, then interview.** Read the request in its strongest
    reasonable form — do not manufacture ambiguity from a fair ask. If goal, scope and
-   success criteria are already unambiguous, restate them in one line and go to step
-   4. Otherwise ask ONE numbered round of every question answerable now, each with your
-   recommended answer so "yes" accepts it; dependent questions wait a round. Drive at
-   *why* (the outcome wanted), *scope* (in and out) and *done* (how success is judged) —
-   not *how* yet. Stop when each is unambiguous. Facts are yours to find (read the code,
-   dispatch a subagent), never the user's. A decision someone else owns gets a drafted
+   success criteria are already unambiguous, restate them in one line (naming any
+   platform or language choice) and go to step 4. Otherwise ask ONE numbered round of
+   every question answerable now, each with your recommended answer so "yes" accepts it;
+   dependent questions wait a round. Drive at *why* (the outcome wanted), *scope* (in and
+   out), *done* (how success is judged) and which build choices (platform, language, key
+   libraries) the user wants to own. Existing work decides by default
+   ({{DOCTRINE:respect-conventions}}); a choice you take goes in the ledger as **your
+   call**, never as agreed. Stop when each is unambiguous. Facts are yours to find (read
+   the code, dispatch a subagent), never the user's. A decision someone else owns gets a drafted
    `questionnaire-<slug>.md` for them — ask the user only who and what they need back.
 3. **Ledger the decisions.** Name every KEY DECISION the answers imply or leave open —
    direction chosen, trade-offs accepted, load-bearing constraints, assumptions,
@@ -28,15 +31,18 @@ the design is skipped.
    fact. Read the ledger back as a numbered list and get an EXPLICIT confirmation
    ({{LAW:echo-the-intent}} — an inferred intent is not ground truth until echoed and agreed);
    scope the read-back to what is consequential, irreversible or genuinely uncertain.
-4. **Design — only when there is something to design.** Propose 2–3 approaches with
+4. **Size it, then design.** Say the size; the user may override. *Quick* — exit and do
+   it, no spec. *Small* — the confirmed ledger in chat is the spec; go to step 6.
+   *Project* — design, spec file, builder check. If it grows mid-work, stop and step up.
+   Design only when there is something to design: propose 2–3 approaches with
    trade-offs, leading with your recommendation. Present the chosen design in
    sections (purpose → components → data flow → failure modes → testing), getting an
    explicit "looks right" after each; cut anything YAGNI. For a non-design ask, skip
    this step.
 5. **Write the spec.** One file the next session can find — `SPEC.md` beside the work,
    or the project's own spec home (e.g. `docs/specs/`): the goal in one line, the
-   confirmed decision ledger, then the design (when there is one). Re-read it cold for
-   ambiguity and fix what a stranger could misread.
+   confirmed decision ledger, then the design (when there is one). Then run the builder
+   check: read [brainstorm/builder-check.md](brainstorm/builder-check.md) and follow it.
 6. **Exit — route, don't build.** Hand the spec to the {{SKILL}} the work now needs:
    [plan](plan.md) for a multi-step build whose route is known (sliced if too big for a
    session), [wayfinder](wayfinder.md) only when the route itself is still in the fog,
@@ -44,7 +50,9 @@ the design is skipped.
 
 ## Done when
 - A confirmed, ambiguity-free goal with its ratified decision ledger — and, where
-  the ask was a design, an approved design — sits in one spec file, and the work has
-  been handed to the next {{SKILL}} with no code written beforehand.
+  the ask was a design, an approved design that passed the builder check — sits in one
+  spec file (or, for a small change, in the confirmed chat ledger), and the work has
+  been handed to the next {{SKILL}} with no code written beforehand — or, sized quick,
+  the brainstorm was exited to do the work.
 
 <!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/daydream/SKILL.md

@@ -79,4 +79,4 @@ No external dependencies -- pure Claude Code tools (Glob, Read, Write, Bash, Tas
 
 ## Cost
 
-Per run (~50 pairs): approximately $0.40-0.50 via Claude Code usage.
+Per run (~50 pairs): approximately 0.40-0.50 USD via Claude Code usage.

package/src/skills/daydream/VENDOR.md

@@ -37,3 +37,7 @@ bump the commit above.
 `SKILL.md`'s frontmatter also carries `disable-model-invocation: true`, which upstream lacks: the
 skill is user-only (`/daydream`), so its description stays out of the model's always-on catalogue —
 it is personal to one vault. Re-apply it on update.
+
+The cost line in `SKILL.md` reads "0.40-0.50 USD" where upstream writes a dollar sign before the
+number: Claude Code substitutes a dollar sign followed by a digit with the skill's arguments, so
+upstream's text renders mangled. Re-apply it on update.

package/src/skills/debug/ci.md

@@ -1,10 +1,10 @@
 # {{SKILL}}: debug — CI branch, a red run
 
 Needs the CI log: the host's CI tool, `gh run view --log-failed` or equivalent, or the log pasted by the user.
-1. **Read the log, not the badge.** Find the first failing job and its first failing step. Read the error and the command that produced it in full ({{LAW:verify-before-asserting}}); note the runner's OS, toolchain versions and exact invocation.
-2. **Classify before touching anything:** a *real failure* (code or test wrong), an *environment difference* (a version, path, line endings, missing binary, a test skipped locally but not in CI), an *infra flake* (network, runner, cache, timeout), or a *gate on the report itself* (a coverage or count threshold, a lint the local hook skips).
-3. **Reproduce under CI's own conditions** — the workflow's script, flags and a matching toolchain. Green locally and red in CI has not reproduced yet: close the gap (the env var, `--frozen-lockfile`, the reporter, the binary not on PATH) until it fails the same way. Never retry a run blindly.
-4. **Fix at the cause** through steps 2–6 of the debug procedure. For an environment difference, make the *repo* deterministic (pin, normalise, declare) rather than CI more permissive. A flake is fixed at its source — the race, the timeout, the unpinned resource — or quarantined *with an issue and an owner*, never silently skipped ({{LAW:cure-the-cause}}). A fix to CI config itself is its own commit ({{LAW:one-intent-one-act}}), noted in the PR.
+1. **Read the log, not the badge.** Measure a log before reading it and grep a large one rather than loading it whole ({{DOCTRINE:context-economy}}). Find the first failing job and its first failing step. Read the error and the command that produced it in full ({{LAW:verify-before-asserting}}); note the runner's OS, toolchain versions and exact invocation.
+2. **Classify before touching anything.** First diff against the last green run: commit range, lockfile, runner image, toolchain. Then name the class: a *real failure* (code or test wrong), an *environment difference* (a version, path, line endings, missing binary, a test skipped locally but not in CI), an *infra flake* (network, runner, cache, timeout), or a *gate on the report itself* (a coverage or count threshold, a lint the local hook skips).
+3. **Reproduce under CI's own conditions** — the workflow's script, flags and a matching toolchain. Green locally and red in CI has not reproduced yet: close the gap (the env var, `--frozen-lockfile`, the reporter, the binary not on PATH) until it fails the same way. Never retry a run blindly. CI logs are shared: probe a secret's presence, never its value (`[ -n "$TOKEN" ] && echo set || echo unset`).
+4. **Fix at the cause** through steps 2–6 of the debug procedure. For an environment difference, make the *repo* deterministic (pin, normalise, declare) rather than CI more permissive. A flake is fixed at its source — the race, the timeout, the unpinned resource — or quarantined *with an issue and an owner*, never silently skipped ({{LAW:cure-the-cause}}). A sleep that guesses at timing becomes a wait on the actual condition with a bounded timeout; a fixed delay that remains says why ({{DOCTRINE:honest-tests}}). A fix to CI config itself is its own commit ({{LAW:one-intent-one-act}}), noted in the PR.
 5. **Prove it the way CI will:** run CI's command locally once more and read the output, push with the user's per-push consent ({{DOCTRINE:consent-before-push}}), and watch the re-run to green; the gate that reported it verifies the fix. Report what failed, its class, what changed, and the green run.
 
 ## Done when

package/src/skills/debug.md

@@ -13,13 +13,13 @@ faster than thrashing; do not trade it away under pressure.
 
 ## Procedure
 1. **Build one command that goes red on *this* bug** before reading code for a theory. It asserts the user's exact symptom (not "didn't crash"), gives the same verdict every run, takes seconds and runs unattended; run it and show the output. Read the error and stack trace in full. For a flaky bug, raise the reproduction rate until it is debuggable. If you cannot build it, say so, list what you tried and ask for access or a captured artifact — no command, no hypothesis. Read `GLOSSARY.md` (or `CONTEXT.md`) and the ADRs in the area for the domain's vocabulary.
-2. **Minimise, then isolate.** Cut inputs and steps one at a time until every remaining element is load-bearing. Then binary-search the cause — the code path, or for a regression the commit range with `git bisect` (the [git-history {{SKILL}}](git-history.md) carries the method). Change one variable at a time. In a multi-layer system (CI → build → sign, API → service → DB), instrument each boundary once to see *which* layer breaks before investigating inside it. For a performance regression, take a baseline measurement and bisect; don't log.
-3. **Rank 3–5 falsifiable hypotheses** ("if X is the cause, changing Y removes the bug") — list them in your reply, then test the top one without waiting. Proceed only on one that explains ALL the evidence — else gather more evidence, don't guess.
+2. **Minimise, then isolate.** Cut inputs and steps one at a time until every remaining element is load-bearing. Then binary-search the cause — the code path, or for a regression the commit range with `git bisect` (the [git-history {{SKILL}}](git-history.md) carries the method). Change one variable at a time. Find the nearest working twin (a passing sibling test, the last green commit, the same call elsewhere) and list every difference, however small. For a bad value deep in the stack, trace it back caller by caller to where it was born, and fix there. In a multi-layer system (CI → build → sign, API → service → DB), instrument each boundary once to see *which* layer breaks before investigating inside it. For a performance regression, take a baseline measurement and bisect; don't log.
+3. **Rank 3–5 falsifiable hypotheses** ("if X is the cause, changing Y removes the bug") — list them in your reply, then test the top one without waiting. Cite the evidence for each as `file:line` or the exact log line. Proceed only on one that explains ALL the evidence — else gather more evidence, don't guess.
 4. Apply the smallest fix that addresses the root cause, not the symptom; resist fixing things the evidence doesn't implicate ({{LAW:one-intent-one-act}}). One change at a time — no bundled "while I'm here" edits.
 5. Verify: run the project's checks and read the actual output ({{LAW:verify-before-asserting}}) — the step-1 command now passes and nothing nearby broke. Where a test can pin the bug at a seam that reproduces the real call chain, add a regression test that fails before the fix and passes after. If no such seam exists, record that as a finding rather than writing a shallow test. Name the confirmed hypothesis in the commit message. Dispatch the [tester {{AGENT}}](../{{DIR_AGENTS}}/tester.md) for a focused regression check when the blast radius is unclear.
-6. If a fix doesn't work, return to step 1 with what you learned — don't stack a second fix on top. **After three failed fixes, stop fixing:** when each attempt only shifts the symptom elsewhere, the architecture, not the line, is likely wrong. Surface that to the user and decide the approach together before trying again ({{LAW:one-intent-one-act}}).
+6. If a fix doesn't work, return to step 1 with what you learned — don't stack a second fix on top. **After three failed fixes, stop fixing:** when each attempt only shifts the symptom elsewhere, the architecture, not the line, is likely wrong. Surface that to the user and decide the approach together before trying again ({{LAW:one-intent-one-act}}). If the evidence puts the cause outside the repo, show it; a retry or timeout is then a named workaround, taken with consent ({{LAW:cure-the-cause}}).
 
-**Diagnostic logging is scaffolding.** When you add logging to isolate a bug, use the project's real logger at a DEBUG level rather than scattered `print`/`console.log`, and **never log secrets, tokens, or PII** ({{LAW:sealed-secrets}}). Tag every probe with one unique prefix (`[DEBUG-a4f2]`) so cleanup is a single grep, and remove or downgrade each probe, `print`/`console.log`/`debugger` before the change ships ({{LAW:cure-the-cause}}).
+**Diagnostic logging is scaffolding.** When you add logging to isolate a bug, use the project's real logger at a DEBUG level rather than scattered `print`/`console.log`, and **never log secrets, tokens, or PII** ({{LAW:sealed-secrets}}) — probe a secret's presence, never its value: `[ -n "$TOKEN" ] && echo set || echo unset`. Tag every probe with one unique prefix (`[DEBUG-a4f2]`) so cleanup is a single grep, and remove or downgrade each probe, `print`/`console.log`/`debugger` before the change ships ({{LAW:cure-the-cause}}).
 
 **CI branch (a red run)** → read [debug/ci.md](debug/ci.md) and follow it.
 

package/src/skills/develop.md

@@ -38,15 +38,17 @@ case where the seam is only known once the change is made.
 6. With the slice green, tidy through the [refactor {{SKILL}}](refactor.md) — the tests
    are the safety net — then commit the slice through the [commit {{SKILL}}](commit.md)
    ({{DOCTRINE:consent-before-push}}). Loop from step 3, one slice at a time.
-7. **Exit.** When the last slice is in: run the whole affected suite once more, state
-   what was run and its result, and hand over — to the [ship {{SKILL}}](ship.md) when
+7. **Exit.** When the last slice is in: run the whole suite once, state what was run and
+   its result, and name every failure in it — including one this change did not cause
+   ({{DOCTRINE:cover-and-verify}}) — then hand over to the [ship {{SKILL}}](ship.md) when
    the change is ready for a PR, or to the [handoff {{SKILL}}](handoff.md) if the
    session ends mid-task. Leave no slice uncommitted and no test you could not make
    fail.
 
 ## Done when
 - Every behaviour changed is covered by a test written this session that was seen
-  to fail before it passed, the affected suite is green with its output shown, each
-  slice was committed on its own, and the work has been handed to ship or handoff.
+  to fail before it passed, the whole suite ran at exit with its output shown and every
+  failure named, each slice was committed on its own, and the work has been handed to
+  ship or handoff.
 
 <!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/fresh-eyes.md

@@ -9,7 +9,7 @@
 2. Deliberately WITHHOLD everything else and say so in the brief: the diff and changed-files list, the chat transcript, the solver's rationale and commit messages, prior test output, and every "it works because…" claim. Each is a vector for confirmation bias — they transmit the author's conviction, and a validator that inherits it cannot judge independently ({{ONTOLOGY}}: {{ONT_CONDUCT}}). The validator must re-confront the artifact cold, the way an external recipient would.
 3. Dispatch ONE fresh-context validator whose context starts empty — isolation is structural, not promised — using the [reviewer {{AGENT}}](../{{DIR_AGENTS}}/reviewer.md) (read-only, runs the suite, casts a verdict; NOT the [skeptic](../{{DIR_AGENTS}}/skeptic.md), whose charter forbids running commands and casting verdicts), via the dispatch pattern in [parallel-agents {{SKILL}}](parallel-agents.md), keeping the heavy reading out of the main context ({{DOCTRINE:context-economy}}); a cheaper model suffices for the validator unless the spec is subtle. Dispatch **fresh** — never resume a prior subagent session, which re-inherits its context and breaches the firewall. Where the host has no subagent capability, degrade: write the brief to a file and have the user run it in a separate fresh process; only as a last resort run the persona in-session and **stamp the verdict "SOFT ISOLATION — context bleed possible"** so the user discounts it. Never silently pretend a persona equals a fresh agent.
 4. Inside the fresh context, FIRST derive the rubric blind: from the task ALONE — before looking at the artifact — write a numbered list of observable acceptance criteria, each a yes/no test with a stated check method (a command to run, an output to see, a behaviour to exercise), tagged must-have or nice-to-have. FREEZE this list. Deriving it inside the firewall, from the task and not the solution, is what prevents criteria-fitting — the rubric cannot be bent to match what the artifact happens to do.
-5. THEN reveal the artifact and rule each criterion against it under an inverted burden of proof: actively check it — run the command, exercise the behaviour, read the named output ({{LAW:verify-before-asserting}} — verify by running, never assume) — and record `Cn: PASS | FAIL | UNVERIFIABLE — <evidence: the exact output/behaviour checked>`. Default is NOT-PASS: mark PASS only after actively confirming; a criterion that cannot be checked is UNVERIFIABLE (a finding, not a pass — name the missing evidence). Flag any **Extra** the artifact added beyond the spec, but cut gold-plating both ways — never FAIL the artifact for a requirement the task never asked for. The validator does NOT fix, refactor, or polish; it only rules.
+5. THEN reveal the artifact and rule each criterion against it under an inverted burden of proof: actively check it — run the command, exercise the behaviour, read the named output ({{LAW:verify-before-asserting}} — verify by running, never assume) — and record `Cn: PASS | FAIL | UNVERIFIABLE — <evidence: the exact output/behaviour checked>`. Default is NOT-PASS: mark PASS only after actively confirming; a criterion that cannot be checked is UNVERIFIABLE (a finding, not a pass — name the missing evidence). Flag any **Extra** the artifact added beyond the spec, but cut gold-plating both ways — never FAIL the artifact for a requirement the task never asked for (a reasonable user's expectation that it not crash or lose data is not gold-plating). The validator does NOT fix, refactor, or polish; it only rules.
 6. Return the independent verdict: the per-criterion table, then the overall gate — **SATISFIES** (every must-have PASS, no FAIL), **SATISFIES-WITH-GAPS** (must-haves pass, a nice-to-have fails), or **DOES-NOT-SATISFY** (any must-have FAIL or UNVERIFIABLE), listing the failing criteria with evidence. Report "could not find a fault" as not-proven-false, never as "proven correct". Surface it for the user to decide; the gate advises and applies no changes — write no code, push nothing ({{LAW:deletion-is-deliberate}}, {{DOCTRINE:consent-before-push}}). On DOES-NOT-SATISFY, hand the failures to the solver (optionally via [review-response](review-response.md)) and re-run fresh-eyes after the fix rather than letting the original context relitigate the ruling.
 
 ## Done when

package/src/skills/geneseed-code-review.md

@@ -6,7 +6,8 @@
 
 ## Procedure
 1. Pin the diff: `git diff <base>...HEAD` for committed work, `git diff <base>`
-   for uncommitted, or the PR the user names. Confirm the base resolves and the
+   for uncommitted, or the PR the user names. `<base>` is `origin/<default branch>` after a
+   `git fetch`, never a local branch that may be stale. Confirm the base resolves and the
    diff is non-empty.
 2. Find the spec: issue refs in the commits, a path the user gave, a match under
    `docs/`, `specs/` or `.scratch/`. None → ask once; still none → skip pass 3 and say so.
@@ -21,7 +22,9 @@
    `CONTRIBUTING.md`) override. Then, as judgement calls and skipping what tooling enforces:
    mysterious name, duplication, feature envy, data clumps, primitive obsession, repeated switches, shotgun surgery, divergent change, speculative generality, middle man, dead code, units that do too much.
 7. Pass 3 — spec fidelity: flag anything asked for but missing, present but never
-   asked for, or implemented wrong — quoting the spec line for each. Architecture drift too: when
+   asked for, or implemented wrong — quoting the spec line for each. 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 `issue (blocking)`, not a nitpick. Architecture drift too: when
    `docs/architecture.md` draws C4 and the diff adds, removes or rewires a container — a Dockerfile,
    a compose service, a deployable module, a datastore, a new client of another container — but
    leaves the diagram alone, raise `issue (non-blocking)` and point at
@@ -30,6 +33,9 @@
    correctness first. Labels: issue, suggestion, question, todo, nitpick, thought, note,
    praise. Decorations: blocking, non-blocking, if-minor. The line pastes straight into a
    merge-request comment, and a reader can filter on the label without reading the prose.
+   Before the verdict, a **Set aside:** list — each behaviour you considered and left out of
+   scope, one line with the reason, or `none` — for the caller to rule on
+   ({{DOCTRINE:declare-the-judgment-calls}}).
 
 ## Done when
 - Findings are reported with a verdict that follows from the decorations: any `blocking`

package/src/skills/handoff.md

@@ -5,7 +5,7 @@
 **Trigger:** the context window is filling, a session is ending mid-task, or work is passing to another agent or developer.
 
 ## Procedure
-1. Capture the state in the worklog (`WORKLOG.md` or the task's plan file): the goal, what's done, the step in progress, and the exact next step.
+1. Capture the state in the worklog (`WORKLOG.md` or the task's plan file), whose first line names its task or branch so a stale one is never resumed: the goal, what's done, the step in progress, and the exact next step.
 2. Record open decisions, dead ends already ruled out, blockers, and any irreversible changes already made ({{DOCTRINE:plan-before-acting}}) — so the next agent neither re-derives nor repeats them.
 3. Promote any durable fact or correction learned this session into {{MEMORY}} (§5), not just the worklog.
 4. Point to the live artifacts: branch name, changed files, how to run the tests, and where any failure reproduces. Link specs, plans, ADRs, issues and commits by path or URL — never copy them in.

package/src/skills/parallel-agents.md

@@ -6,11 +6,11 @@
 
 ## Procedure
 1. Confirm independence: the subtasks must not depend on each other's output or write the same files ({{DOCTRINE:one-writer-per-file}}). Write down each unit's **write set** — the files or globs it may change — and intersect them; an overlap runs in sequence or goes to one owner, and shared append files (registries, index tables, lockfiles, generated bundles) stay with you. If they're sequential or share state, use [plan](plan.md) instead.
-2. Split the work into self-contained units, each with one clear goal and a defined output contract — what it must return.
-3. Dispatch each unit to its own subagent in one batch, each under a handoff envelope: the unit's goal, the inputs it needs, its **write set** (edit nothing outside it; return rows for a shared file instead of writing it), the observable check that proves it done, its output contract — naming every file it changed — and the inherited constraints (no commit/push — {{DOCTRINE:consent-before-push}} stays with you; gaps reported, never invented). Hand each unit only the access its goal needs ({{LAW:least-privilege}}). Prefer the read-only [explorer {{AGENT}}](../{{DIR_AGENTS}}/explorer.md) for investigation so the heavy reading stays out of the main context ({{DOCTRINE:context-economy}}). Where no subagent capability exists, run the units sequentially as personas instead, converging the same way.
+2. Split the work into self-contained units, each with one clear goal and a defined output contract — what it must return. Several small edits of one kind (the same fix, constant or field across files) form ONE unit with the union write set and get one review.
+3. Dispatch each unit to its own subagent in one batch, each under a handoff envelope: the unit's goal, the inputs it needs, its **write set** (edit nothing outside it; return rows for a shared file instead of writing it), the observable check that proves it done, its output contract — naming every file it changed — and the inherited constraints (no commit/push — {{DOCTRINE:consent-before-push}} stays with you; no sub-agents of its own — review comes from you; gaps reported, never invented). Hand each unit only the access its goal needs ({{LAW:least-privilege}}). Prefer the read-only [explorer {{AGENT}}](../{{DIR_AGENTS}}/explorer.md) for investigation so the heavy reading stays out of the main context ({{DOCTRINE:context-economy}}). Where no subagent capability exists, run the units sequentially as personas instead, converging the same way.
 4. Keep the main context lean: collect each subagent's distilled result, not its working transcript.
-5. Converge: compare each unit's changed files against its write set and against its siblings' — an edit outside the set or a file two units touched is a conflict you resolve before anything else — apply the shared-file rows yourself, then verify the combined outcome.
-6. **A plan with blocking edges.** To build a [plan](plan.md) file's slices — each with its `Blocked by:` line — in one run, dispatch every unblocked slice on its own branch off one integration branch, merge each into it as it returns (each merge is a commit — {{DOCTRINE:consent-before-push}} stays with you), and recompute the unblocked set from the plan after every merge — newly freed slices go out at once.
+5. Converge: compare each unit's changed files against its write set and against its siblings' — an edit outside the set, a file two units touched, or a file in a batch's set that never changed is a conflict you resolve before anything else — apply the shared-file rows yourself, then verify the combined outcome. A conflict or ambiguity between the plan, the findings and the code is yours to decide: decide it, record `Ruling: <choice> — <why> — <cost if wrong>` in the worklog, and continue. Stop only for what {{LAW:echo-the-intent}}, {{LAW:deletion-is-deliberate}} or {{DOCTRINE:consent-before-push}} names; every ruling goes in the final report ({{DOCTRINE:declare-the-judgment-calls}}).
+6. **A plan with blocking edges.** To build a [plan](plan.md) file's slices — each with its `Blocked by:` line — in one run, dispatch every unblocked slice on its own branch off one integration branch, merge each into it as it returns (each merge is a commit — {{DOCTRINE:consent-before-push}} stays with you), and recompute the unblocked set from the plan after every merge — newly freed slices go out at once. When the plan names a `Spec:`, every slice reads it once; the spec outranks the plan where they conflict. Record BASE before dispatch; before re-running the proof, confirm the branch descends from BASE and the diff is non-empty — an empty diff is a failure, not a clean result. Never diff against `HEAD~1`.
 
 ## Done when
 - Independent units ran concurrently, each returned a distilled result, and the reconciled outcome is verified.

package/src/skills/pipeline.md

@@ -24,11 +24,11 @@ The minimum roster per task type. The parent may add specialists on top — secu
 1. Confirm the task is genuinely substantial — a trivial one-file tweak or a question does not warrant a crew; do it directly instead.
 2. Compose the crew from the floor above, adding specialists only where the task demands them.
 3. Isolate the crew's work in its own git worktree/branch. Where worktrees are unavailable, fall back to a single tree, one pipeline at a time, and say so. Give the crew a **write set** and check it against every other pipeline in flight ({{DOCTRINE:one-writer-per-file}}): two crews whose sets overlap do not run at once, and shared append files (registries, index tables, lockfiles, generated bundles) are the parent's to apply, never a crew's.
-4. **The dev↔tester loop:** the developer implements, the tester validates — runs the tests and lint, produces raw logs. On failure, the findings go back to the developer. Cap at **5** iterations; on exhaustion, stop, do not merge, and report the failure with the branch left in place for inspection.
+4. **The dev↔tester loop:** the developer implements, the tester validates — runs the tests and lint, produces raw logs. On failure, the findings go back to the developer — two repair rounds at most, then one fresh developer (a higher model tier where the host offers one) carrying the tester's findings ({{DOCTRINE:bound-the-loop}}); if that fails too, stop, do not merge, and report the failure with the branch left in place for inspection. A conflict or ambiguity between the plan, the findings and the code is yours to decide: decide it, record `Ruling: <choice> — <why> — <cost if wrong>` in the worklog, and continue. Stop only for what {{LAW:echo-the-intent}}, {{LAW:deletion-is-deliberate}} or {{DOCTRINE:consent-before-push}} names; every ruling goes in the final report ({{DOCTRINE:declare-the-judgment-calls}}). When the plan names a `Spec:`, the analyst reads it once; the spec outranks the plan.
 5. **Two execution shapes**, chosen by host capability (same pattern as the [workflow {{SKILL}}](workflow.md)):
-   - *Deterministic:* where the host exposes a `workflow` tool, run a saved script encoding analyst → developer → (tester ⇄ developer)×≤5 → proof.
+   - *Deterministic:* where the host exposes a `workflow` tool, run a saved script encoding analyst → developer → (tester ⇄ developer)×≤2 → fresh developer → proof.
    - *Model-driven fallback:* everywhere else, run the same stages via the [parallel-agents {{SKILL}}](parallel-agents.md) or sequential personas, with the same handoff envelopes and the same delivery contract.
-6. On success, hand the worktree back to the parent uncommitted, with the mechanical proof (test + lint output, exit codes) and the list of files it changed in the result envelope, rebased on the current base so a conflict with a sibling resolves on the crew's branch. The pipeline never commits, pushes, or merges ({{DOCTRINE:consent-before-push}}): the parent re-runs the proof commands itself, shows the user the diff and the output, and commits and merges once the user accepts.
+6. On success, hand the worktree back to the parent uncommitted, with the mechanical proof (test + lint output, exit codes) and the list of files it changed in the result envelope, rebased on the current base so a conflict with a sibling resolves on the crew's branch. The pipeline never commits, pushes, or merges ({{DOCTRINE:consent-before-push}}): the parent records BASE before dispatch and, before re-running the proof, confirms the branch descends from it and the diff is non-empty (an empty diff is a failure; never `HEAD~1`); it re-runs the proof commands itself, shows the user the diff and the output, and commits and merges once the user accepts.
 
 ## Delivery contract
 

package/src/skills/plan.md

@@ -17,17 +17,29 @@
    thin end-to-end pieces, each green and verifiable on its own, never one horizontal
    layer at a time — and give each a `Blocked by:` line naming the slices it waits on
    (`none` when it can start now). Sequence a wide refactor as expand → migrate
-   callers in batches → contract, so every slice leaves the build green.
-3. Execute one step at a time. After each, update the worklog — mark it done, note
-   the current step, the next step, and any blockers.
+   callers in batches → contract, so every slice leaves the build green. A step records
+   decisions, not code: the files, the exact signatures and the spec's values, the test
+   that proves it, and the check command. Write a body only for an algorithm those leave
+   open; a plan longer than the code it describes has written the code, and "TBD",
+   "handle edge cases" or "add tests" decide nothing. The file's first line names the
+   task or branch, then `Spec: <path>` when a spec exists — the spec outranks the plan
+   where they conflict, and a worklog naming another task is stale, never resumed.
+3. Execute one step at a time. After each, update the worklog — mark it done only after
+   its check ran green in this session, with the command and result on the line — and
+   note the current step, the next step, and any blockers. After a compaction, trust the
+   worklog and `git log` over memory.
 4. At each milestone, stop and verify before continuing — run the project's checks
-   and read the output ({{LAW:verify-before-asserting}}); on a consequential or ambiguous
-   direction, surface the result for review before pressing on.
+   and read the output ({{LAW:verify-before-asserting}}). Decide forks yourself; stop
+   only for what {{LAW:echo-the-intent}} or {{DOCTRINE:consent-before-push}} names.
 5. If the plan proves wrong, revise the file *before* continuing. The file, not
-   your memory, is the source of truth for where you are.
+   your memory, is the source of truth for where you are. A deviation you decide without
+   asking gets a worklog line `Ruling: <what> — <why> — <cost if wrong>`; those lines feed
+   {{DOCTRINE:declare-the-judgment-calls}} at the end.
 6. On finishing, clear or archive the worklog.
 
 ## Done when
+- The plan was re-read against the spec before step 1: every requirement has a step,
+  names match across steps, and it is not several times the spec's length.
 - Every plan step is checked off, each milestone was verified, and the goal's
   done-condition is confirmed.