geneseed 3.18.0 → 3.19.0

package/CHANGELOG.md

@@ -8,6 +8,23 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [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.19.0**.
 
 ## Capabilities
 

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.19.0"
 }

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/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.19.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/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/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.
 

package/src/skills/fresh-eyes.md

@@ -2,7 +2,7 @@
 
 > {{DESC_FRESH_EYES}}
 
-**Trigger:** work is claimed done and needs a blind check against the original ask. That is before merge or handoff, while the solving session believes the artifact works, or when the user asks to "validate", "fresh eyes", "prove it meets the spec", "did this actually solve it", or "independent sign-off" — and the cost of a confidently-wrong "done" is high. This re-judges the *result* from zero context — distinct from [geneseed-code-review](geneseed-code-review.md), which reviews a *diff* with full knowledge of the change. For an open-ended quality critique use [roast-me](roast-me.md); for a multi-stance debate over an undecided question use [council](council.md).
+**Trigger:** work is claimed done and needs a blind check against the original ask. That is before merge or handoff, while the solving session believes the artifact works, or when the user asks to "validate", "fresh eyes", "prove it meets the spec", "did this actually solve it", or "independent sign-off" — and the cost of a confidently-wrong "done" is high. This re-judges the *result* from zero context — distinct from [geneseed-code-review](geneseed-code-review.md), which reviews a *diff* with full knowledge of the change. To attack the user's own ask or plan use [roast-me](roast-me.md); for a multi-stance debate over an undecided question use [council](council.md).
 
 ## Procedure
 1. Capture the firewall input as TWO things and nothing else: (a) the **verbatim original task/spec** — the raw issue or request text, NOT a solver-written summary or "spec card" (a distilled card launders the solving session's framing into the rubric, the very bias this {{SKILL}} exists to defeat), and (b) a pointer to the **final artifact** as it stands — file paths, built output, or the command to run it. If the raw task is too thin to yield acceptance criteria, have the **user** (never the solver) confirm a one-line acceptance bar, then proceed ({{LAW:echo-the-intent}}); if it is too fuzzy even for that, this is a judgement call — convene [council](council.md) instead.

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

@@ -2,7 +2,7 @@
 
 > {{DESC_CODE_REVIEW}}
 
-**Trigger:** reviewing changes before merge, or the user asks for a review.
+**Trigger:** reviewing changes before merge, or the user asks for a review — including "roast my code": same passes, findings unsoftened. Critiquing the user's own ask or plan is [roast-me](roast-me.md).
 
 ## Procedure
 1. Pin the diff: `git diff <base>...HEAD` for committed work, `git diff <base>`
@@ -10,16 +10,23 @@
    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.
-3. For a large change, consider dispatching the
+3. Load the review rules: for each changed file, the nearest `REVIEW.md` above it, up to the
+   repo root — a deeper one overrides a shallower one. They override everything below,
+   output format included, but never a {{LAW}}.
+4. For a large change, consider dispatching the
    [reviewer {{AGENT}}](../{{DIR_AGENTS}}/reviewer.md) to keep the main context clean.
-4. Pass 1 — correctness: logic errors, edge cases, error handling, race
+5. Pass 1 — correctness: logic errors, edge cases, error handling, race
    conditions. Verify suspect behaviour by running tests, not by assuming.
-5. Pass 2 — quality: the repo's documented standards (`CODING_STANDARDS.md`,
+6. Pass 2 — quality: after `REVIEW.md`, the repo's documented standards (`CODING_STANDARDS.md`,
    `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.
-6. Pass 3 — spec fidelity: flag anything asked for but missing, present but never
-   asked for, or implemented wrong — quoting the spec line for each.
-7. Write each finding as a Conventional Comment, `label (decoration): file:line — problem — fix`,
+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
+   `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
+   [document-project](document-project.md) to redraw L2.
+8. Write each finding as a Conventional Comment, `label (decoration): file:line — problem — fix`,
    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.

package/src/skills/parallel-agents.md

@@ -2,7 +2,7 @@
 
 > {{DESC_PARALLEL_AGENTS}}
 
-**Trigger:** two or more independent subtasks with no shared state or ordering between them — and a tool that can run subagents.
+**Trigger:** two or more independent subtasks with no shared state or ordering between them — and a tool that can run subagents. The units run side by side and never see each other's work; when one agent must build on what the previous one produced, that is a relay — use [pipeline](pipeline.md).
 
 ## 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.

package/src/skills/pipeline.md

@@ -2,7 +2,7 @@
 
 > {{DESC_PIPELINE}}
 
-**Trigger:** [foreman mode](../modes/foreman.md) routes a triaged *substantial* task here; also directly invocable without that mode whenever the user asks to "run a pipeline" for a development, documentation, research, or review task.
+**Trigger:** [foreman mode](../modes/foreman.md) routes a triaged *substantial* task here; also directly invocable without that mode whenever the user asks to "run a pipeline" for a development, documentation, research, or review task. The crew is a relay, not a fan-out: its agents take turns in one worktree, each handed what the previous one produced — for independent subtasks run side by side, use [parallel-agents](parallel-agents.md).
 
 ## What it is
 

package/src/skills/ponytail.md

@@ -2,7 +2,7 @@
 
 > {{DESC_PONYTAIL}}
 
-**Trigger:** the user says "ponytail", "be lazy", "lazy mode", "yagni" or "do less", or complains about over-engineering, bloat, or needless dependencies. Also "simplest/minimal solution", "shortest path", or a complaint about boilerplate. Sets a build *mode* that persists across the session, not a one-shot edit — off by default until invoked. Off again on "stop ponytail" / "normal mode". For restructuring code that already exists use [refactor](refactor.md); to critique an artifact use [roast-me](roast-me.md).
+**Trigger:** the user says "ponytail", "be lazy", "lazy mode", "yagni" or "do less", or complains about over-engineering, bloat, or needless dependencies. Also "simplest/minimal solution", "shortest path", or a complaint about boilerplate. Sets a build *mode* that persists across the session, not a one-shot edit — off by default until invoked. Off again on "stop ponytail" / "normal mode". For restructuring code that already exists use [refactor](refactor.md); to review code for correctness use [geneseed-code-review](geneseed-code-review.md).
 
 ## Procedure
 1. Set the intensity. Ponytail is **off by default**; invoking it turns it on at **full** unless a level is named. **lite** — build what's asked, name the lazier alternative in one line, user picks. **full** — the ladder enforced, shortest diff, shortest explanation. **ultra** — YAGNI extremist, ship the one-liner and challenge the rest of the requirement in the same breath. Switch any time with `/ponytail lite|full|ultra|off` (on OpenCode this command persists the level for the geneseed-ponytail plugin; `off` stops it).

package/src/skills/react-view-transitions/SKILL.md

@@ -5,6 +5,7 @@ license: MIT
 metadata:
   author: vercel
   version: "1.0.0"
+disable-model-invocation: true
 ---
 
 # React View Transitions

package/src/skills/react-view-transitions/VENDOR.md

@@ -30,3 +30,7 @@ only one left in any install's catalogue.
 **Deliberately not copied:** upstream's `README.md` (the repo-facing readme: install
 command and folder tree, nothing an agent reads). `AGENTS.md`, upstream's compiled
 all-in-one copy, IS kept — `SKILL.md`'s closing section points the agent at it.
+
+`SKILL.md`'s frontmatter also carries `disable-model-invocation: true`, which upstream lacks: the
+skill is user-only (`/react-view-transitions`), so its description stays out of the model's always-on catalogue —
+it is the largest skill and serves one stack. Re-apply it on update.

package/src/skills/review-response.md

@@ -3,7 +3,8 @@
 > {{DESC_REVIEW_RESPONSE}}
 
 **Trigger:** review feedback has arrived — from a human or another agent — and is about
-to be acted on.
+to be acted on; or the user wants a review criterion recorded ("add a review rule…",
+"reviews should always check…").
 
 ## Procedure
 1. Read every comment in full before changing anything. Group related comments.
@@ -17,9 +18,14 @@ to be acted on.
    [commit {{SKILL}}](commit.md) so {{DOCTRINE:consent-before-push}}'s per-commit consent holds — then
    re-run the checks ({{LAW:verify-before-asserting}}).
 6. Surface anything the review missed that you noticed while addressing it.
+7. Upgrade the review itself. A finding that recurs, a criterion the user asks for, or a
+   defect a review should have caught becomes a rule in the nearest `REVIEW.md` above the
+   files it governs — create it if missing. Show the exact lines and write them only on
+   the user's word. Rules for *criticising* go here, not into the root file the coder
+   loads every session.
 
 ## Done when
 - Every comment has a reasoned response and either an applied change or a justified
-  decline, and the resulting changes are verified.
+  decline, the resulting changes are verified, and any agreed review rule is in `REVIEW.md`.
 
 <!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/roast-me.md

@@ -2,16 +2,17 @@
 
 > {{DESC_ROAST_ME}}
 
-**Trigger:** the user asks to "roast", "tear apart", "find the fatal flaws", or "be brutally honest" about an artifact — code, design, plan, pitch, or writing. This is the *open-ended quality critique*: for reviewing a diff use [geneseed-code-review](geneseed-code-review.md); for a zero-context does-it-meet-the-spec verdict use [fresh-eyes](fresh-eyes.md).
+**Trigger:** the user wants their own request, plan, idea or writing torn apart, brutally and honestly. Phrases: "roast", "tear apart", "find the fatal flaws", "be brutally honest", "is this the right thing to ask for". This attacks the *user's* side of the work, not what the agent produced: code and diffs, even when the user says "roast my code", go to [geneseed-code-review](geneseed-code-review.md); a zero-context does-it-meet-the-ask verdict is [fresh-eyes](fresh-eyes.md); shaping a raw idea into a design is [brainstorm](brainstorm.md).
 
 ## Procedure
-1. Identify the artifact and the critique axis that matters (correctness, architecture, viability, clarity, security…); if unclear, ask once, then proceed.
-2. Steelman it: state the strongest case FOR the artifact in a sentence, so the attack hits the real thing, not a strawman.
-3. In the voice of {{ROAST_PERSONA}}, write each flaw as one line — `location/claim — what's wrong — what to do instead`. No praise, no hedging, no filler; drop any finding you can't pair with a fix.
-4. Rank findings by severity: fatal → significant → minor.
-5. Close with the single change that would help most.
+1. Identify the artifact and the critique axis that matters (viability, clarity, scope, cost, risk…); if unclear, ask once, then proceed.
+2. Attack the premise first: what problem the ask assumes, whether that problem is the real one, and what it would cost to be wrong about it. A sound answer to the wrong question is the fatal flaw.
+3. Steelman it: state the strongest case FOR the artifact in a sentence, so the attack hits the real thing, not a strawman.
+4. In the voice of {{ROAST_PERSONA}}, write each flaw as one line — `location/claim — what's wrong — what to do instead`. No praise, no hedging, no filler; drop any finding you can't pair with a fix.
+5. Rank findings by severity: fatal → significant → minor.
+6. Close with the single change that would help most.
 
 ## Done when
-- Findings are severity-ranked, every one carries a fix, and the highest-impact change is named.
+- The premise was challenged, findings are severity-ranked, every one carries a fix, and the highest-impact change is named.
 
 <!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/rule.md

@@ -43,7 +43,9 @@ re-derived. Then take exactly one branch.
    the existing rule rather than minting a twin). A *mechanical* rule — a banned
    API, an import shape, a file location — belongs in a lint, hook or CI check the
    team shares, not in prose: propose that instead, and report a repo with no such
-   guardrail as a finding. A failed triage goes back to the
+   guardrail as a finding. A criterion that only matters when *judging* work goes to
+   `REVIEW.md` through the [review-response {{SKILL}}](review-response.md), not here.
+   A failed triage goes back to the
    fork, named and explained; a lean rule set is the feature, not a failure.
 2. **Reformulation.** Have the user state the rule as they would to a colleague on
    their first day. Interrupt the moment they (a) use a term they cannot themselves

package/src/skills/ship.md

@@ -11,31 +11,35 @@ request or merge the branch.
    `context.json`); if it is undefined, ask rather than assume. Run those checks and
    read the actual output ({{LAW:verify-before-asserting}}); state what you ran and its result.
    Never ship on an unproven claim.
-2. Confirm the branch carries only this change's commits and is rebased/updated on
+2. Review the change before anyone else sees it: run the
+   [geneseed-code-review {{SKILL}}](geneseed-code-review.md) on the branch diff (dispatch the
+   [reviewer {{AGENT}}](../{{DIR_AGENTS}}/reviewer.md) for a large one). Any `blocking`
+   finding stops the ship until it is fixed.
+3. Confirm the branch carries only this change's commits and is rebased/updated on
    the base branch; resolve any divergence before opening.
-3. Push the branch only with the user's explicit, per-push acceptance — on every
+4. Push the branch only with the user's explicit, per-push acceptance — on every
    branch, feature branches included ({{DOCTRINE:consent-before-push}}); present the change summary + commit
    message and wait, and never treat an earlier approval as consent for this push.
    Opening a PR or merging is **outward-facing** — get explicit confirmation first too,
    unless already authorized ({{LAW:deletion-is-deliberate}}).
-4. Open the PR with a three-part body. **Summary**: what changed and why, with the
+5. Open the PR with a three-part body. **Summary**: what changed and why, with the
    smallest visual that makes the point (a call tree, diff sketch, file tree or
    Mermaid diagram). **Evidence**: how it was tested, as before/after — the test that
    failed and now passes, the output, a screenshot for a visual change. **Merge
    danger**: one-way or two-way door, the blast radius, and any follow-up. Link the
    issue it closes; keep the title an imperative one-line summary.
-5. If the project merges locally instead, merge into the base branch only after
+6. If the project merges locally instead, merge into the base branch only after
    review/approval, then delete the merged branch.
    If shipping triggers a production deploy, confirm a tested rollback or
    fix-forward path and a retained previous artifact *before* deploying — there must
    be a way back ({{LAW:deletion-is-deliberate}}); dispatch the
    [operator {{AGENT}}](../{{DIR_AGENTS}}/operator.md) when the runtime surface is
    non-trivial.
-6. Make sure documentation shipped with the code ({{DOCTRINE:documentation-in-step}}) — a change
+7. Make sure documentation shipped with the code ({{DOCTRINE:documentation-in-step}}) — a change
    that alters behaviour without its docs is incomplete, not ready to ship.
 
 ## Done when
-- The PR is open (or the branch is merged) with a Summary / Evidence / Merge danger
+- The diff passed review with no `blocking` finding, and the PR is open (or the branch is merged) with a Summary / Evidence / Merge danger
   body, and nothing unrelated rides along.
 
 <!-- INCLUDE: skills/_self-improvement.md -->

package/themes/_TEMPLATE.json

@@ -42,7 +42,7 @@
   "DESC_CODEBASE_DESIGN": "<one-line description: design deep modules and the domain language around them — small interfaces at deliberate seams, a living GLOSSARY.md, an ADR per hard-to-reverse decision>",
   "DESC_WAYFINDER": "<one-line description: map an oversized effort as decision tickets and resolve them until the route is clear>",
   "DESC_PROTOTYPE": "<one-line description: throwaway code that answers a design question>",
-  "DESC_ROAST_ME": "<one-line description: adversarially critique any artifact — brutal, specific, actionable>",
+  "DESC_ROAST_ME": "<one-line description: adversarially critique the user's own ask, plan or idea (not code) — brutal, specific, actionable>",
   "DESC_FRESH_EYES": "<one-line description: a context-free agent derives the acceptance bar blind, then rules the work>",
   "ROAST_PERSONA": "<the persona the roast-me skill adopts, in this theme's voice>",
   "DESC_COUNCIL": "<one-line description: convene distinct viewpoints to debate, then synthesise a verdict>",
@@ -112,6 +112,7 @@
   "DOC_ONE_WRITER_PER_FILE": "<themed title for the process rule One Writer Per File>",
   "DOC_CODES_THAT_PERSIST": "<themed title for the comms rule Codes That Persist>",
   "DOC_STRUCTURE_BESIDE_PROSE": "<themed title for the comms rule Structure Beside Prose>",
+  "DOC_DECLARE_THE_JUDGMENT_CALLS": "<themed title for the comms rule Declare the Judgment Calls>",
   "INTRO_DOC": "<themed intro: this file is the entry point an AI agent reads in this repo>",
   "INTRO_AGENTS": "<themed intro to the Agents section — delegate focused work to a specialist>",
   "INTRO_SKILLS": "<themed intro to the Skills section — run the written procedure before improvising>",

package/themes/biker.json

@@ -42,7 +42,7 @@
   "DESC_CODEBASE_DESIGN": "Build deep modules and the crew's own language — big behaviour behind a small handlebar at a seam placed on purpose, a living GLOSSARY.md, an ADR for every call that's hard to undo.",
   "DESC_WAYFINDER": "Chart a run too big for one ride as a shared map of decision tickets, cleared one at a time until the road's open.",
   "DESC_PROTOTYPE": "Answer a design question with throwaway code — built to learn the road, never to keep.",
-  "DESC_ROAST_ME": "Tear into any work — blunt, exact, always actionable.",
+  "DESC_ROAST_ME": "Tear into the user's own ask, plan or idea, not code — blunt, exact, always actionable.",
   "DESC_FRESH_EYES": "Bring in a fresh rider who's seen neither the route notes nor the miles — only the original orders and the finished bike — to set the bar blind, then call whether it meets the orders, free of the maker's bragging.",
   "ROAST_PERSONA": "a grizzled road captain who has watched this exact mistake put a bike in the ditch",
   "DESC_COUNCIL": "Call a crew of opposed voices to argue a call out, then hand down a verdict with the dissent kept in the roadbook.",
@@ -112,6 +112,7 @@
   "DOC_ONE_WRITER_PER_FILE": "One Wrench on Each Bolt · One Writer Per File",
   "DOC_CODES_THAT_PERSIST": "Tag Every Part on the Bench · Codes That Persist",
   "DOC_STRUCTURE_BESIDE_PROSE": "Draw the Route Only If It Turns · Structure Beside Prose",
+  "DOC_DECLARE_THE_JUDGMENT_CALLS": "Own Up to Every Back Road Taken · Declare the Judgment Calls",
   "INTRO_DOC": "This file is the route briefing a coding rider reads when it joins this repository.",
   "INTRO_AGENTS": "Send the right rider for focused work instead of riding the whole run yourself; each has one job and reports exactly what it did.",
   "INTRO_SKILLS": "A Skill is a move you've drilled for a recurring task. Run the matching move before you wing it.",