ConductionNL · WilcoLouwerse · May 11, 2026
diff --git a/docs/claude/README.md b/docs/claude/README.md
@@ -512,15 +512,7 @@ See [usage-tracker/README.md](../../usage-tracker/README.md) for full documentat
 
 [Hydra](https://github.com/ConductionNL/hydra) is Conduction's agentic CI/CD platform that runs the same spec-driven workflow autonomously in Docker containers. It transforms OpenSpec change proposals into validated, security-scanned code on feature branches — with final human approval before merging.
 
-Hydra maintains its own skills, personas, and OpenSpec workflows in its repository, running them through three specialized agent containers:
-
-| Agent | Role | Permissions |
-|-------|------|-------------|
-| **Al Gorithm** (Builder) | Reads OpenSpec change, implements code, opens draft PR | Full: Read, Write, Edit, Bash |
-| **Juan Claude van Damme** (Reviewer) | Code review for correctness, style, architecture | Read-only |
-| **Clyde Barcode** (Security) | SAST analysis, secret detection, security hardening | Read-only |
-
-The workflow and commands documented in this guide apply to both interactive development and Hydra's automated agents. See the [Hydra repository](https://github.com/ConductionNL/hydra) for container architecture, agent configuration, deployment models, and operational guides.
+For an overview of the pipeline stages, the label-based triggers (`ready-to-build`, `code-review:queued`, `security-review:queued`), and how to put Hydra to work on your PR, see the **[Hydra docs](../hydra/README.md)**. For container architecture, image builds, orchestrator internals, and operator-level material, see the [Hydra repository](https://github.com/ConductionNL/hydra).
 
 ---
 

diff --git a/docs/hydra/README.md b/docs/hydra/README.md
@@ -24,29 +24,28 @@ Builder                     — implements the change, pushes branch early,
 Quality tests               — lint, phpcs, phpmd, psalm, phpstan,
   │                           phpmetrics, composer audit, eslint,
   │                           stylelint, npm audit, PHPUnit, Newman
-  │  fail → Builder fix-quality (max 2 retries)
+  │  fail → Builder fix-quality (bounded, pre-review)
   │
   ▼
 Browser UI tests            — Playwright MCP runs the GIVEN/WHEN/THEN
   │                           acceptance criteria against a live NC
-  │  fail → Builder fix-browser (max 2 retries)
+  │  fail → Builder fix-browser (bounded, pre-review)
   │
   ├── Code Reviewer        ─┐
-  └── Security Reviewer    ─┘ parallel — halves wall time
+  └── Security Reviewer    ─┘ sequential — reviewers hold bounded fix authority
   │
-  │  fail → Builder fix CRITICAL+WARNING (max 3 retries)
-  │         If fix budget exhausted → needs-input label
+  │  either fails → needs-input (no loop — ADR-013)
   ▼
 Draft PR (ready-for-review) — human reviews and merges
-  │  with full-auto label: pipeline approves and merges automatically
+  │  with the `yolo` label: pipeline approves and merges automatically
   │
   ▼ (after human merge)
 Archive — sync specs, generate test scenarios, update changelog
 ```
 
 **Traceability.** Every line of code traces to its spec via two paths: a `@spec` PHPDoc tag pointing at `openspec/changes/{name}/tasks.md#task-N`, and `git blame` → commit `(#N)` → PR `Closes #N` → issue → spec. Branch naming is `feature/{issue-number}/{change-name}` and every commit includes `(#N)`.
 
-**Model selection.** Builder uses Opus for implementation and Sonnet for fix modes. Reviewers and the Browser UI Tester use Sonnet.
+**Model selection.** Default model for every persona is Sonnet, with a deeper-model fallback (Haiku for the Builder; Opus for the reviewers and the Applier) when the weekly Sonnet quota runs out. Authoritative configuration lives in each persona's `agents/<persona>/config.yaml` in the hydra repo.
 
 ## How to use Hydra on your PR
 
@@ -58,16 +57,16 @@ You don't run Hydra yourself — you trigger it with labels.
    - `security-review:queued` — queue a security review.
 
    Reviews are **sequential** by design (the security review consumes the code review's git state). Setting both queued labels at once is not supported and will produce conflicts. Trigger them one at a time.
-3. **Crashes escalate to `needs-input`** rather than auto-retrying. If a Hydra container fails, you'll see a `needs-input` label so a human can investigate the root cause instead of looping.
-4. **PRs that only touch Markdown auto-merge.** Documentation-only changes don't need the full review cycle.
+3. **Crashes escalate to `needs-input`** rather than auto-retrying. If a Hydra container fails, or either reviewer emits a fail verdict, you'll see a `needs-input` label so a human can investigate. There is no retry loop ([ADR-013](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-013-container-pool.md)) — recovery is explicit via the `retry:queued` (fix the flagged findings) or `rebuild:queued` (start over) labels.
+4. **The `yolo` label means auto-merge after the pipeline passes.** All phases still run; `yolo` only removes the human approval gate at the end.
 
 ## Where to learn more
 
 The deep technical detail stays in the [hydra repo](https://github.com/ConductionNL/hydra):
 
 - [hydra/README.md](https://github.com/ConductionNL/hydra/blob/main/README.md) — quickstart and full pipeline overview.
 - [hydra/docs/](https://github.com/ConductionNL/hydra/tree/main/docs) — pipeline-overview, agentic-workflow, container-architecture, github-workflow, deployment-models, agent-configuration.
-- [hydra/openspec/architecture/](https://github.com/ConductionNL/hydra/tree/main/openspec/architecture) — 20+ ADRs covering data layer, API, backend, frontend, security, metrics, i18n, testing, docs, NL Design, schema standards, deduplication, container pool, licensing, common patterns, routes, component composition, widget header actions, integration registry, gate scope.
+- [hydra/openspec/architecture/](https://github.com/ConductionNL/hydra/tree/main/openspec/architecture) — 29 ADRs covering data layer, API, backend, frontend, security, metrics, i18n, testing, docs, NL Design, schema standards, deduplication, container pool (model selection, no-loop policy), licensing, common patterns, routes, component composition, widget header actions, integration registry, gate scope, bounded fix scope, app manifest, journeydoc, schema-declarative business logic, and spec sizing.
 - [hydra/.claude/skills/](https://github.com/ConductionNL/hydra/tree/main/.claude/skills) — every gate (`hydra-gate-*`), every opsx command (`opsx-*`), and the Hydra-specific tooling.
 
 For how Hydra fits into the broader Claude-driven development workflow, see [Claude workflow](/claude/).