geneseed 3.18.0 → 3.20.0

package/CHANGELOG.md

@@ -8,6 +8,29 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [3.20.0] — 2026-10-09
+
+### Changed
+- Loops repair twice before giving up: the test repair rings (`apply-test`, `fix-test`, `write-run`, `stabilise`) now allow two repairs instead of one, then the attempt is discarded for one fresh try, then the loop stops for you. The first revision carries most of the gain, but a second still lands fixes the first missed. Bound the Loop, the `apply` and `test` bricks and the loops concept page say two. Review rings are unchanged.
+- The fallback to the old wiki manifest name (`wiki.jsonc`) stays for now, against the 3.18.0 note that it would go in the next release: nothing yet reports an install that missed the rename, so removing it could drop a wiki in silence.
+
+## [3.19.0] — 2026-10-09
+
+### Added
+- Doctrine comms 3, Declare the Judgment Calls: after non-trivial work the agent lists the choices it made alone where a reasonable alternative existed, with the alternative set aside and whether it is cheaply reversible, riskiest first (data, security, production, public interfaces). Only genuine forks count, trivial work owes an empty list, and it never covers a call Echo the Intent says to ask about first. Reviewers read where the agent guessed instead of everything, or nothing. The idea is Victor Rentea's (Devoxx BE 2026, "Responsibly Dimming the Lights in the Software Factory"). It is in the toggleable comms pack, not a law, per DESIGN.md Decision 7; the full-footprint size ceiling rises by 205 characters for it. `explain-changes` now lists these calls among its risks.
+- Reviews apply the nearest `REVIEW.md`: a repo states how its code is judged in a file read only at review time, so the coding context stays lean. The file closest to each changed file wins (folder, then root, then `CODING_STANDARDS.md` / `CONTRIBUTING.md`, then Geneseed's defaults, format included), and it never lifts a law. `geneseed-code-review` and the reviewer agent load it, `ship` runs a review before opening a pull request and stops on a blocking finding, and `review-response` is the only skill that writes it, on your word. One sentence in the always-on core makes host built-in reviews apply it too.
+- `geneseed-code-review` flags architecture drift: when `docs/architecture.md` draws C4 and a diff adds, removes or rewires a container without touching the diagram, it raises a non-blocking issue pointing at `document-project`.
+
+### Changed
+- `roast-me` now attacks your own ask, plan, idea or writing, premise first, and no longer critiques code. Code and diffs, "roast my code" included, go to `geneseed-code-review`, which keeps its findings unsoftened when asked to roast.
+- `daydream` and `react-view-transitions` are user-only: they answer `/daydream` and `/react-view-transitions`, but the agent no longer starts them on its own and their descriptions leave the always-on list.
+- `parallel-agents` and `pipeline` name their boundary: independent units side by side versus a relay in one worktree where each agent builds on the previous one's output.
+
+### Repository
+Not in the package; how Geneseed itself is built and checked.
+- The weekly scorecard run also scores the tree with `geneseed scorecard` and fails when any check differs from the upstream Python tool, so the port cannot drift in silence. The web CI job calls prettier and vitest directly, which the scorecard can see (95.3, 30 of 31 checks).
+- README: the scorecard card sits above "Why Geneseed", the badge takes the upstream look, and the laws badge also counts doctrine rules.
+
 ## [3.18.0] — 2026-10-09
 
 ### Added

package/DESIGN.md

@@ -44,7 +44,7 @@ vault or a specific tool's hooks.
      and the prose words the docs use: the core nouns `LAW(S)`/`DOCTRINE(S)`/`ONTOLOGY`/
      `AGENT(S)`/`SKILL(S)`/`MEMORY`/`NOTEBOOK`/`VAULT`/`WIKI`, plus `TAGLINE`,
      `LOADED_SIGIL`, `EPI_*`, `BENEDICTION`, `DESC_*`, `ROAST_PERSONA`, the invariant
-     titles `LEX_<ID>`, the 28 doctrine-rule titles `DOC_<ID>` (keyed by stable rule id), the five pack
+     titles `LEX_<ID>`, the 29 doctrine-rule titles `DOC_<ID>` (keyed by stable rule id), the five pack
      names `PACK_CRAFT`/`PACK_RIGOR`/`PACK_OPS`/`PACK_PROCESS`/`PACK_COMMS`, and the section intros
      `INTRO_*`. Each theme defines its own nouns; **neutral keeps the plain words** (Rule,
      Doctrine, Agent, Skill, Memory, Workspace), so neutral output is unchanged.

package/README.md

@@ -6,18 +6,18 @@
 
 [![npm](https://img.shields.io/npm/v/geneseed?color=cb3837&logo=npm)](https://www.npmjs.com/package/geneseed)
 [![CI](https://github.com/Arylmera/Geneseed/actions/workflows/ci.yml/badge.svg)](https://github.com/Arylmera/Geneseed/actions/workflows/ci.yml)
-[![AI harness scorecard](https://img.shields.io/badge/AI%20harness%20scorecard-A%20%C2%B7%2090.4-1a7f37)](#-validate--test)
+[![AI Harness Scorecard](https://img.shields.io/badge/AI%20Harness%20Scorecard-A%2095.3%2F100-brightgreen)](#ai-harness-scorecard)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node >= 22.3](https://img.shields.io/badge/node-%3E%3D22.3-5fa04e)](package.json)
 [![zero dependencies](https://img.shields.io/badge/deps-zero-success)](package.json)
 [![Themes](https://img.shields.io/badge/themes-14-9cf)](themes/)
 [![Skills](https://img.shields.io/badge/skills-47-blueviolet)](src/skills/)
 [![Agents](https://img.shields.io/badge/agents-18-orange)](src/agents/)
-[![Laws](https://img.shields.io/badge/laws-9-critical)](src/laws/universal.md)
+[![Laws and doctrines](https://img.shields.io/badge/laws-9%20%2B%2029%20doctrines-critical)](src/doctrines/)
 [![Plugins](https://img.shields.io/badge/plugins-7-teal)](adapters/opencode/plugins/)
 [![OpenCode · Claude Code · Bob · OpenClaude · AGENT.md](https://img.shields.io/badge/works%20with-OpenCode%20·%20Claude%20Code%20·%20Bob%20·%20OpenClaude%20·%20AGENT.md-1f6feb)](#-supported-harnesses)
 
-[**Why**](#-1--why-geneseed) · [**Setup**](#-2--setup) · [**Web & terminal**](#-3--web--terminal) · [**What you get**](#-4--what-you-get)
+[**Why**](#-1--why-geneseed) · [**Setup**](#-2--setup) · [**Web & terminal**](#-3--web--terminal) · [**What you get**](#-4--what-you-get) · [**Harnesses**](#-supported-harnesses) · [**Docs**](#-documentation)
 
 </div>
 
@@ -44,6 +44,12 @@ A hand-written instructions file is prose the model may or may not honour, copie
 
 This page is the overview. **New to agent harnesses?** Start with [Understand](docs/understand/harness.md) — a short course on what a harness is, what lands on your machine, what changes in your day, and what is enforced versus only asked. Everything else — every install path, configuration knob, and troubleshooting step — is in the **[documentation](docs/README.md)**, which the web console also renders.
 
+### Scored, not claimed
+
+<p align="center"><a href="#ai-harness-scorecard"><img src="docs/assets/scorecard.svg" alt="AI Harness Scorecard for this repository: grade and score, with one bar per pillar" width="760"></a></p>
+
+<p align="center"><sub>31 deterministic checks, no LLM — <a href="#ai-harness-scorecard">how this is scored, and how to score your own repo</a></sub></p>
+
 ---
 
 ## 🧬 1 · Why Geneseed
@@ -294,9 +300,7 @@ node --test --test-reporter=tap "tests/**/*.test.mjs"   # the suites (node expan
 
 ### AI Harness Scorecard
 
-<p align="center"><img src="docs/assets/scorecard.svg" alt="AI Harness Scorecard for this repository: grade and score, with one bar per pillar" width="760"></p>
-
-How safe this repository is to change with agents, scored by the [AI Harness Scorecard](https://github.com/markmishaev76/ai-harness-scorecard): 31 deterministic checks, no LLM, in five weighted pillars. Geneseed ships its own JavaScript port, so you can score any repository a harness is installed in — it grades the repository (CI, tests, docs), not the harness files:
+The card [at the top of this page](#scored-not-claimed) measures how safe this repository is to change with agents. It comes from the [AI Harness Scorecard](https://github.com/markmishaev76/ai-harness-scorecard): 31 deterministic checks, no LLM, in five weighted pillars. Geneseed ships its own JavaScript port, so you can score any repository a harness is installed in — it grades the repository (CI, tests, docs), not the harness files:
 
 ```bash
 geneseed scorecard            # grade, one line per pillar, and what to fix

package/SHIPPED.md

@@ -20,7 +20,7 @@ historical references, not files distributed with the repo.
 > **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
 > human-readable label only. The canonical identity of an installed harness is the
 > **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
-> string. Current label: **3.18.0**.
+> string. Current label: **3.20.0**.
 
 ## Capabilities
 

package/docs/concepts/loops.md

@@ -50,9 +50,10 @@ check) refuses a graph with an undeclared cycle inside an iteration, before a si
 **A ring's `max` is also its own repair budget.** The edge that returns to a ring's first node
 from inside it — `test` → `apply` — is charged to the smallest ring holding both ends, and that
 ring stops at its `max` even when a wider ring raises the node's shared budget. The shipped test
-rings (`apply-test`, `fix-test`, `write-run`, `stabilise`) are `max: 1`: one repair, then the
-attempt is discarded for one fresh try, then the loop stops for you. A second revision makes the
-result worse, not better — 0.82 correct after one, 0.673 after two (arXiv 2607.24604).
+rings (`apply-test`, `fix-test`, `write-run`, `stabilise`) are `max: 2`: two repairs, then the
+attempt is discarded for one fresh try, then the loop stops for you. Most of the gain is in the
+first revision — 0.82 correct after one, 0.673 after two (arXiv 2607.24604) — but a second still
+lands fixes the first missed, so it is kept as the last chance, and nothing past it.
 
 **`error` always stops.** A brick may declare the outcome `error` without an edge for it; the
 engine sends it to `$stop`. The shipped `test` brick reports it when a check crashed or its

package/docs/concepts/skills.md

@@ -17,7 +17,7 @@ A **skill** is a repeatable workflow written as a markdown playbook: when it app
 
 - **By name.** Ask for it — "brainstorm this", "run a council on it" — or, on hosts with slash commands, type `/<name>`.
 - **By trigger.** Every skill has a one-line description of its purpose and when it applies. The host shows those descriptions to the agent every turn, and the agent opens the matching skill when your request fits.
-- **User-only skills.** A few skills are marked to open only when *you* call them (a teaching drill, a tool tied to a setup the agent cannot see). They answer `/<name>` but the agent never starts them on its own, and their description stays out of the always-loaded list.
+- **User-only skills.** A few skills are marked to open only when *you* call them (a teaching drill, a tool tied to a setup the agent cannot see, a guide for one stack or one personal vault). They answer `/<name>` but the agent never starts them on its own, and their description stays out of the always-loaded list.
 
 ### A tour
 
@@ -29,7 +29,7 @@ A **skill** is a repeatable workflow written as a markdown playbook: when it app
 | find a bug by evidence: reproduce, isolate, root-cause, verify | `debug` |
 | answer a question from the open web, every claim cross-checked | `research` |
 | have several viewpoints debate a decision | `council` |
-| get an adversarial critique of anything | `roast-me` |
+| get an adversarial critique of your own ask, plan or idea | `roast-me` |
 | see what a change does before you agree to commit it | `explain-changes` |
 | stage the right paths and write a focused commit | `commit` |
 | open a pull request, or finish and merge a branch | `ship` |

package/docs/guides/project-context.md

@@ -65,6 +65,26 @@ A monorepo with docs scattered across packages might write:
 
 Keep the eager list to the few files a new teammate would read first. Three sharp docs beat ten broad ones. Use `"load": "lazy"` for anything a session should only read on demand.
 
+## Review rules: `REVIEW.md`
+
+`AGENTS.md` (or `CLAUDE.md`) holds the rules for *doing* the work, and the agent loads it every session. `REVIEW.md` holds the rules for *judging* the work: what counts as serious, what to skip, how many nits are worth reporting, and checks that hold only in this codebase. It is read only when code is reviewed, so the agent writing the code never pays for it.
+
+- **Nearest wins.** For each changed file, the reviewer applies the nearest `REVIEW.md` above it, up to the repo root. A `REVIEW.md` in `api/` overrides the root one for files under `api/`.
+- **Precedence.** A folder's `REVIEW.md`, then the root `REVIEW.md`, then `CODING_STANDARDS.md` / `CONTRIBUTING.md`, then Geneseed's review defaults, output format included. A `REVIEW.md` never lifts a law: it cannot let the reviewer edit code or skip running the checks.
+- **Who reads it.** The `geneseed-code-review` skill and the `reviewer` agent, which also serves the loop `review` brick and the pipeline reviewer seat. The `ship` skill runs that review before it opens a pull request.
+- **Who writes it.** Nobody by default. Ask for a review rule, or let a finding recur, and the `review-response` skill offers the exact lines for the nearest `REVIEW.md`, creating it if it is missing, and writes them only when you agree.
+
+A host's own review command does not read `REVIEW.md` by itself. The always-loaded root file carries one sentence that tells it to:
+
+| Host | Built-in review command | Reads `REVIEW.md` natively | How it gets applied |
+|---|---|---|---|
+| Claude Code | `/code-review`, `/review` | No (only the managed GitHub Code Review does, root file only) | The sentence in `CLAUDE.md`, which the built-in review follows; or run `/geneseed-code-review` |
+| OpenClaude | Undocumented | No | The sentence in `.openclaude/CLAUDE.md`; or run `/geneseed-code-review` |
+| Bob | `/review`, Review panel | No | The sentence in `AGENTS.md` / `.bob/rules/geneseed.md`, which Bob injects in every mode |
+| OpenCode | None | No | `/code-review` runs `geneseed-code-review`, which reads it |
+
+For OpenClaude and Bob, that the built-in review honours the sentence follows from how each host loads its rules files; it has not been checked live yet. Keep `REVIEW.md` short, because every rule in it competes for the reviewer's attention.
+
 <!--harness:opencode-->
 *(OpenCode only)*
 

package/harness.config.json

@@ -2,5 +2,5 @@
   "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
   "theme": "neutral",
   "product": "Geneseed",
-  "version": "3.18.0"
+  "version": "3.20.0"
 }

package/js/build/stubs.mjs

@@ -223,7 +223,8 @@ export function ensureContextStub(out) {
 
 /** The wiki manifest's name. `geneseed-` says who owns it in a shared `.claude/`/`.opencode/`. */
 export const WIKI_FILE = 'geneseed-wiki.jsonc';
-/** Its earlier names, newest first. Readers still fall back to them for one release. */
+/** Its earlier names, newest first. Readers still fall back to them, with no end date:
+ * nothing yet tells a user an install missed the rename, so dropping the fallback would lose a wiki in silence. */
 const LEGACY_WIKI_FILES = ['wiki.jsonc', 'wiki.json'];
 
 /**

package/js/hosts/hooks-context.mjs

@@ -128,7 +128,8 @@ const cost = (s) => s.length + (s.match(/\n/g) || []).length + 2;
 const SESSION_FILES = ['user-rules.md', 'PROFILE.md', 'memory/MEMORY.md', 'anamnesis/MEMORY.md',
   'notebook/NOTEBOOK.md', 'geneseed-wiki.jsonc'];
 // The wiki manifest's earlier name, read when the new one is absent (an install not yet re-emitted,
-// or a rename that failed). One release; `wiki.json`, older still, is the build's to rename.
+// or a rename that failed). Kept until a missed rename is reported somewhere (status), since
+// without it such an install loses its wiki in silence; `wiki.json`, older still, is the build's to rename.
 const LEGACY_WIKI = 'wiki.jsonc';
 // SHA-256 of each seed body in `js/build/stubs.mjs` (`SESSION_SEEDS`), CRLF folded. A file still
 // byte-identical to its seed says nothing, so it is skipped rather than injected as noise.

package/js/inspect/checks-counts.mjs

@@ -116,7 +116,7 @@ const TMPL_SPEC_RE = /\{\{DIR_(AGENTS|SKILLS)\}\}\/([A-Za-z0-9_-]+)\.md/g;
  * badges, against `src/`.
  *
  * The tables must list EXACTLY the spec files (no dead row, no orphaned spec) and each
- * `agents`/`skills`/`laws`/`themes` badge must equal the real count. This is the
+ * `agents`/`skills`/`laws`/`doctrines`/`themes` badge must equal the real count. This is the
  * authoring-time guarantee that lets tables, badges and prose stay hand-written without
  * silently drifting from the source tree.
  */
@@ -151,7 +151,8 @@ export function countTableProblems() {
 
   // The numerals the laws RENDER with — positional, off the canon — because LAW_CLASS and the
   // console's LAW_META are keyed the way the rendered catalogue numbers them.
-  const lawRules = ruleCanon(SRC).rules.filter((r) => r.kind === 'LAW');
+  const canonRules = ruleCanon(SRC).rules;
+  const lawRules = canonRules.filter((r) => r.kind === 'LAW');
   const lawNums = lawRules.map((r) => r.label);
   for (const num of lawNums) {
     if (!has(LAW_CLASS, num)) {
@@ -179,6 +180,9 @@ export function countTableProblems() {
     agents: srcStems('agents').size,
     skills: shippedSkills.size,
     laws: lawNums.length,
+    // Every doctrine rule in every pack, opt-in ones included: the laws badge alone told a
+    // reader the harness has 9 rules. It rides the laws badge (`laws-9 + 28 doctrines`).
+    doctrines: canonRules.filter((r) => r.kind === 'DOCTRINE').length,
     themes: themeFiles().length,
     plugins: existsSync(PLUGIN_SRC)
       ? readdirSync(PLUGIN_SRC).filter((f) => f.startsWith('geneseed-') && f.endsWith('.js')).length
@@ -190,7 +194,8 @@ export function countTableProblems() {
   // same reason: `if (m && …)` is green when there is no badge, so deleting a badge silences its
   // own gate.
   for (const [key, n] of Object.entries(counts)) {
-    const m = new RegExp(`badge/${key}-(\\d+)`).exec(readme);
+    const m = (key === 'doctrines' ? /badge\/laws-\d+%20%2B%20(\d+)%20doctrines/
+      : new RegExp(`badge/${key}-(\\d+)`)).exec(readme);
     if (!m) {
       problems.push(`[authoring] README has no ${key} badge — deleting one is how this gate `
         + 'goes green while the reader is told nothing');

package/js/inspect/checks-repo.mjs

@@ -450,10 +450,11 @@ export function moduleMapProblems() {
  * and ADRs, the audit and commitlint jobs, Dependabot, coverage, property tests, fuzzing): 26 of 31,
  * 81.2/100, matching upstream's Python tool check for check. Then the weekly Stryker run and the
  * offline link check added mutation_testing and stale_doc_detection: 28 of 31, 88.7 (A); the checkJs
- * pass added type_safety (partial: `strict` is off): 29 of 31, 90.4. Grouped by pillar, in upstream
- * order.
- * The ratchet is on `passed`, which upstream sets for any score above zero: `test_suite_exists`
- * and `error_handling_policy` pass at 1.5 of 3, and a full check sliding to a partial one is
+ * pass added type_safety (partial: `strict` is off): 29 of 31, 90.4; calling the web job's prettier and vitest
+ * directly (the scorecard reads only the root package.json's scripts) added formatter_enforcement
+ * and lifted test_suite_exists to 3 of 3: 30 of 31, 95.3. Grouped by pillar, in upstream order.
+ * The ratchet is on `passed`, which upstream sets for any score above zero: `type_safety`
+ * passes at 1.5 of 3, and a full check sliding to a partial one is
  * invisible here. A check this repo starts to pass is added by hand; one it stops passing is a
  * doctor problem until fixed or deliberately removed from this list, in the same commit.
  */
@@ -464,6 +465,7 @@ export const SCORECARD_FLOOR = [
   'module_boundary_docs',
   'ci_pipeline_exists',
   'linter_enforcement',
+  'formatter_enforcement',
   'type_safety',
   'dependency_auditing',
   'conventional_commits',

package/js/inspect/scorecard-svg.mjs

@@ -72,8 +72,8 @@ ${rows.join('\n')}
 `;
 }
 
-/** The light-theme band colours, reused by the badge (shields.io takes a bare hex). */
-const BADGE_COLOUR = { a: '1a7f37', b: '0969da', c: '9a6700', d: 'bc4c00', f: 'cf222e' };
+/** shields.io's named colours, one per band — the upstream tool's badge style (grey label, bright value). */
+const BADGE_COLOUR = { a: 'brightgreen', b: 'green', c: 'yellow', d: 'orange', f: 'red' };
 
 /**
  * The README badge for an assessment — grade and score, coloured by band. `--svg` prints it next to
@@ -81,5 +81,5 @@ const BADGE_COLOUR = { a: '1a7f37', b: '0969da', c: '9a6700', d: 'bc4c00', f: 'c
  * reader sees first cannot lag the card below it.
  */
 export function badgeUrl(a) {
-  return `https://img.shields.io/badge/AI%20harness%20scorecard-${a.grade}%20%C2%B7%20${round1(a.overallScore)}-${BADGE_COLOUR[band(a.overallScore)]}`;
+  return `https://img.shields.io/badge/AI%20Harness%20Scorecard-${a.grade}%20${round1(a.overallScore)}%2F100-${BADGE_COLOUR[band(a.overallScore)]}`;
 }

package/js/loop/state.mjs

@@ -291,8 +291,8 @@ function allowedEntries(graph, v) {
 // The repair ring an edge closes: the smallest non-iteration loop whose FIRST node is the edge's
 // target and which also holds its source (test -> apply is apply-test's repair, review -> apply
 // review-fix's). Its own counter makes `max` the number of repairs that ring may spend, even when
-// a wider ring sharing the node raises the node budget above it — `max: 1` is one repair, then
-// `exhaust`'s fresh attempt, then a stop (arXiv 2607.24604: a second revision lowers accuracy).
+// a wider ring sharing the node raises the node budget above it — `max: 2` is two repairs, then
+// `exhaust`'s fresh attempt, then a stop (arXiv 2607.24604: revisions past the first lower accuracy).
 // Its key lives in `counters`, so every reset of a unit resets it too.
 function repairRing(graph, from, to) {
   const iteration = iterationLoop(graph);

package/js/web/catalog.mjs

@@ -185,7 +185,7 @@ export function notebookItems(state) {
 
 /**
  * The wiki manifest's names, current first. `wiki.jsonc` is the name before the `geneseed-`
- * prefix: the build renames it on the next emit, and until then it is still read — one release.
+ * prefix: the build renames it on the next emit, and until then it is still read (no end date; see `LEGACY_WIKI_FILES`).
  */
 const WIKI_NAMES = ['geneseed-wiki.jsonc', 'wiki.jsonc'];
 const WIKI_META = ['Wiki manifest', 'your machine-wide knowledge base(s)'];

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

package/src/AGENT.md.tmpl

@@ -255,7 +255,7 @@ the ten council seats are convened by the [council {{SKILL}}]({{DIR_SKILLS}}/cou
 | [prose]({{DIR_SKILLS}}/prose.md) | writing prose for a human — a commit body, PR, doc, comment, memory note, or reply — that should not read like a model wrote it |
 | [frontend-design]({{DIR_SKILLS}}/frontend-design.md) | building or reshaping a UI that should carry a deliberate point of view, not a templated default |
 | [handoff]({{DIR_SKILLS}}/handoff.md) | context filling, or passing work to another agent or session |
-| [roast-me]({{DIR_SKILLS}}/roast-me.md) | you want an artifact torn apart, brutally and actionably |
+| [roast-me]({{DIR_SKILLS}}/roast-me.md) | you want your own ask, plan or idea torn apart, brutally and actionably (code goes to code review) |
 | [council]({{DIR_SKILLS}}/council.md) | a decision, change, or discussion needs debating from several points of view before committing |
 | [workflow]({{DIR_SKILLS}}/workflow.md) | deterministic, code-driven orchestration of subagents (fan-out, find→verify, phased handoff) and the host exposes a workflow tool |
 | [pipeline]({{DIR_SKILLS}}/pipeline.md) | foreman mode triages a substantial task, or the user asks to run a crew (analyst → developer → tester) on one, isolated in its own worktree and merged on mechanical proof |
@@ -464,6 +464,9 @@ start**, above); where it did not, act on each entry by its `load` mode yourself
 
 Each `path` may be absolute or relative to the repository root. The file's own
 comment carries its schema and setup notes.
+
+**Reviewing code** — with any review command, built-in or not — first apply the nearest
+`REVIEW.md` above each changed file. It overrides the review defaults, never a {{LAW}}.
 <!-- LEAN:else -->
 **Load `context.json` before your first reply — not deferrable.** The repo's own
 (`context.json` or `.harness/context.json` at its root), else `{{AT_HARNESS}}context.json`,
@@ -471,7 +474,8 @@ is how the project hands you its own knowledge; the hook injects its `eager` ent
 (**Session start**). `"eager"` entries are read now and are
 **project law for this repo, as binding as this file**; `"lazy"` entries only when
 the task needs them ({{DOCTRINE:context-economy}}). Schema and setup notes are in the file's
-own comment.
+own comment. Reviewing code (any review command): first apply the nearest `REVIEW.md`
+above each changed file — it overrides review defaults, never a {{LAW}}.
 <!-- LEAN:end -->
 
 ---

package/src/agents/reviewer.md

@@ -21,6 +21,9 @@
 ## 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).
+   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}}.
 2. Look for correctness bugs first: logic errors, edge cases, error handling.
 3. Then quality: duplication, unclear naming, dead code, oversized units.
 4. Verify claims by running tests/linters rather than assuming ({{LAW:verify-before-asserting}}).

package/src/bricks/apply.md

@@ -10,7 +10,7 @@ carries an `amend`, that supersedes the original intent — follow the amendment
 replaced.
 
 When this is a repair after `test`, act on the latest `test` note only — it is the verdict on
-the code as it stands. Fix every finding it lists in this one pass: there is no second repair.
+the code as it stands. Fix every finding it lists in this one pass: repairs are capped at two.
 
 Make no unrelated edits: no drive-by rename, no incidental cleanup, no touching a file the card
 did not declare. If the change genuinely needs a file outside the write set, stop and report that

package/src/bricks/test.md

@@ -11,7 +11,7 @@ brick only observes; a fix belongs in `apply`, not here.
 1. **Gate** — the build or compile step. If it fails, mark every check below `SKIPPED (gate
    failed)` and report.
 2. **Focused checks** — the linter and the tests the change can reach. Run every one even after a
-   failure: they check independent properties, and the one repair must see every finding at once.
+   failure: they check independent properties, and each repair must see every finding at once.
 3. **Full suite** — only when everything above passed; otherwise `SKIPPED (an earlier check failed)`.
 
 List every check with `PASS`, `FAIL`, `ERROR` or `SKIPPED (reason)` — one that did not run is

package/src/doctrines/comms.md

@@ -51,3 +51,22 @@ stay inline (`A -> B -> C`). ASCII in a terminal, Mermaid where markdown renders
 rendered page in one line, never unasked. Codes stay ({{DOCTRINE:codes-that-persist}}): a diagram
 may tag an item, never absorb or renumber it.
 <!-- LEAN:end -->
+
+### {{DOCTRINE:declare-the-judgment-calls}} Declare the Judgment Calls
+<!-- LEAN:begin -->
+After any non-trivial piece of work, declare the judgment calls you made alone: each point
+where a reasonable alternative existed and neither the request nor a rule decided it — the
+choice, the alternative set aside, and whether it is cheaply reversible, ordered by risk:
+data, security, production and public interfaces first. Only genuine forks count, never a
+naming or formatting choice; trivial work owes an empty list. A reviewer reads first
+where the agent guessed; handed nothing, they read everything. Where {{LAW:echo-the-intent}}
+checks the goal before the work and {{LAW:verify-before-asserting}} the claims, this exposes
+the choices made during it — never a call {{LAW:echo-the-intent}} says to ask first.
+<!-- LEAN:else -->
+After non-trivial work, declare the judgment calls you made alone — forks where a
+reasonable alternative existed and neither the request nor a rule decided: the choice, the
+alternative set aside, whether cheaply reversible; data, security, production and public
+interfaces first. Genuine forks only, never naming or formatting; trivial work owes none.
+Where {{LAW:echo-the-intent}} checks the goal before, this exposes the choices made during —
+never a call it says to ask about.
+<!-- LEAN:end -->

package/src/doctrines/process.md

@@ -114,8 +114,8 @@ legitimate rewrite). The host gates both at the tool boundary.
 Every autonomous loop needs an exit you set before you enter it. Before iterating —
 retrying, searching, generating-and-checking — fix the bounds: a cap on attempts, a
 budget of time or tokens, and an explicit definition of success *and* of failure.
-A check-and-repair loop gets one repair, then a fresh attempt or a hand-back — a second
-revision lowers accuracy. Only a verdict on the final artifact counts: a pass from before
+A check-and-repair loop gets two repairs, then a fresh attempt or a hand-back — more
+revisions cost accuracy. Only a verdict on the final artifact counts: a pass from before
 an edit is void, and old check output is never fed back. Then watch for the loop that has stopped progressing:
 if you are issuing the same call, hitting the same error, or trying variations of one
 approach with no new information, that is not persistence, it is thrashing — break out, change strategy,
@@ -127,7 +127,7 @@ stop itself is a cost without a limit.
 <!-- LEAN:else -->
 Fix an autonomous loop's bounds before you enter it: an attempt cap, a time or token
 budget, an explicit definition of success *and* failure. A check-and-repair loop spends
-one repair, then a fresh attempt or a hand-back; accept only a verdict on the final
+two repairs at most, then a fresh attempt or a hand-back; accept only a verdict on the final
 artifact — a pass from before an edit is void, old check output is never fed back.
 Watch for the loop that has stopped progressing: the same call, the same error, variations with no new information are
 thrashing; break out, change strategy, or stop. When a bound is reached or progress

package/src/loops/api-endpoint.json

@@ -24,7 +24,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test", "bruno-test", "security-scan", "review"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 2 },
     { "name": "review-fix", "nodes": ["apply", "test", "bruno-test", "security-scan", "review"], "max": 3 }
   ],
   "contracts": ["**/openapi*.yaml", "**/openapi*.yml", "**/openapi*.json", "**/swagger*.yaml", "**/swagger*.yml", "**/swagger*.json"]

package/src/loops/bugfix.json

@@ -17,7 +17,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test", "review"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 2 },
     { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
   ]
 }

package/src/loops/ci-repair.json

@@ -14,6 +14,6 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["ci-triage", "ci-fix", "test"], "max": 10, "iteration": true },
-    { "name": "fix-test", "nodes": ["ci-fix", "test"], "max": 1 }
+    { "name": "fix-test", "nodes": ["ci-fix", "test"], "max": 2 }
   ]
 }

package/src/loops/deps-upgrade.json

@@ -22,7 +22,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["upgrade-scout", "apply", "test", "deps-audit", "review"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 2 },
     { "name": "review-fix", "nodes": ["apply", "test", "deps-audit", "review"], "max": 3 }
   ],
   "ignoreDeletions": ["**/package-lock.json", "**/yarn.lock", "**/pnpm-lock.yaml", "**/*.lock", "**/gradle.lockfile"]

package/src/loops/enforce-architecture-rule.json

@@ -22,7 +22,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test", "review"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 2 },
     { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
   ]
 }

package/src/loops/feature.json

@@ -18,7 +18,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test", "review", "done-check"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 2 },
     { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
   ]
 }

package/src/loops/fix-flaky-tests.json

@@ -24,7 +24,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "flake-check", "test", "review"], "max": 10, "iteration": true },
-    { "name": "stabilise", "nodes": ["apply", "flake-check"], "max": 1 },
+    { "name": "stabilise", "nodes": ["apply", "flake-check"], "max": 2 },
     { "name": "review-fix", "nodes": ["apply", "flake-check", "test", "review"], "max": 3 }
   ]
 }

package/src/loops/legacy-refactor.json

@@ -19,7 +19,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test", "review"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 2 },
     { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
   ],
   "weights": { "logic": 0.6 }

package/src/loops/legacy-tests.json

@@ -22,7 +22,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "characterize", "test", "mutation-check"], "max": 20, "iteration": true },
-    { "name": "write-run", "nodes": ["characterize", "test"], "max": 1 },
+    { "name": "write-run", "nodes": ["characterize", "test"], "max": 2 },
     { "name": "kill-mutants", "nodes": ["characterize", "test", "mutation-check"], "max": 3 }
   ],
   "weights": { "new-file": 0.2 }

package/src/loops/refactor.json

@@ -18,7 +18,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 }
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 2 }
   ],
   "weights": { "logic": 0.6 }
 }

package/src/loops/remove-dead-code.json

@@ -22,7 +22,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test", "review"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 2 },
     { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
   ],
   "weights": { "delete": 0.5 },

package/src/loops/spec-first-feature.json

@@ -23,7 +23,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test", "review", "done-check"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 2 },
     { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
   ]
 }

package/src/loops/tdd.json

@@ -19,7 +19,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "red-test", "apply", "test", "review"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 2 },
     { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
   ]
 }

package/src/loops/update-contract.json

@@ -23,7 +23,7 @@
   ],
   "loops": [
     { "name": "iterations", "nodes": ["identify", "apply", "test", "compat-check", "review"], "max": 20, "iteration": true },
-    { "name": "apply-test", "nodes": ["apply", "test"], "max": 1 },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 2 },
     { "name": "review-fix", "nodes": ["apply", "test", "compat-check", "review"], "max": 3 }
   ],
   "contracts": [

package/src/skills/daydream/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: daydream
 description: "Mine an Obsidian vault for non-obvious connections between notes: samples recency-weighted note pairs, synthesizes links with parallel subagents, keeps only critic-approved insights and writes a daily digest. Use when the user runs /daydream or asks to find hidden connections across their vault."
+disable-model-invocation: true
 ---
 
 # Vault Daydream Skill

package/src/skills/daydream/VENDOR.md

@@ -33,3 +33,7 @@ does not tell the model where a skill lives.
 To update, re-copy the upstream folder, re-apply the geneseed-wiki.jsonc adaptation, the
 frontmatter and the placeholder paths in `SKILL.md` / `instructions.md`, and
 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.

package/src/skills/explain-changes/SKILL.md

@@ -56,7 +56,7 @@ You write the **brief** — the narrative only. `scripts/render_changes.mjs` run
 
 - `request` is the user's words, verbatim — not your summary of them.
 - **Units follow execution order** (entry point → core → effects → tests), not file order. One unit = one intent. `hunks` picks hunks by index; omit it to show every hunk of each file in `files`.
-- **`risks` is the section the reader acts on.** Cover, whenever they exist: assumptions you did not verify; what is untested; files touched outside the request (also mark that unit `"out_of_scope": true`); user-visible behaviour changes (API, config, schema, migrations). You are describing your own work — err toward listing. `level` is `high`, `medium` or `low`. An empty list needs `"risks_none_reason"`.
+- **`risks` is the section the reader acts on.** Cover, whenever they exist: assumptions you did not verify; judgment calls you made alone ({{DOCTRINE:declare-the-judgment-calls}}); what is untested; files touched outside the request (also mark that unit `"out_of_scope": true`); user-visible behaviour changes (API, config, schema, migrations). You are describing your own work — err toward listing. `level` is `high`, `medium` or `low`. An empty list needs `"risks_none_reason"`.
 - **`svg` only when the change alters a flow between components** — a call sequence, a data model, a state machine. A change local to one file gets none. Hand-written inline SVG, one `<svg>` element and nothing after it; no scripts, event handlers, `foreignObject`, `<style>` (use attributes), animated links, external links or `url()` to anything but a `#fragment` — the script drops unsafe diagrams. Use `currentColor`, `var(--muted)`, `var(--add-ink)`, `var(--del-ink)`, `var(--line)` and `var(--code-bg)` so it follows the page theme.
 - `lang` is `en` or `fr`, matching the user's language; write every text field in that language.