docs: ADR practice, PR-size, and Hydra-reference fixes

CONTRIBUTING.md

@@ -37,6 +37,14 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme
 * Make sure your code lints (`composer cs:check`)
 * Create a pull request!
 
+### PR Size
+
+Prefer **one PR per logically-coherent finding or feature**. Each PR's commit message, checkbox, and inline-comment chain should map to a single change unit — reviewers hold a clearer mental model on focused PRs than on large ones.
+
+* When a PR's scope grows past **~10 commits or ~30 files**, consider splitting it before requesting review. The per-finding commits stay; the PR boundary moves.
+* **Exception:** release-promotion PRs (`development → beta`, `beta → main`) aggregate every change since the last cut and are expected to be larger.
+* PRs touching many files across unrelated subsystems tend to get reviewed paragraph-by-paragraph rather than holistically — that's a signal to split, not to push through.
+
 ## Branch Protection & Git Flow
 
 We use a structured branching model to ensure stability across environments. All branches are protected via **organization-wide rulesets** on the ConductionNL GitHub organization — direct pushes are not allowed. Every change flows through a pull request with peer review and CI checks.

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).
 
 ---
 

docs/claude/writing-adrs.md

@@ -152,3 +152,27 @@ Before merging an ADR change:
 - [ ] No paragraphs — bullets only
 - [ ] Total ADR file is under 200 lines
 - [ ] Added rules have been tested by running the agent and verifying it follows them
+
+---
+
+## ADRs in practice — where they live
+
+Every Conduction app repo follows a clean split:
+
+| Location | Scope | Who writes |
+|---|---|---|
+| [`hydra/openspec/architecture/`](https://github.com/ConductionNL/hydra/tree/main/openspec/architecture) | **Org-wide ADRs** — apply to every Conduction app | Humans (architecture-level decisions) |
+| `<app>/openspec/architecture/` | **Repo-specific ADRs** — apply only to that app (data model choices, domain standards, storage decisions) | Authored by Specter during research; evolved by humans |
+
+The authoritative org-wide list is the directory itself — [`hydra/openspec/architecture/`](https://github.com/ConductionNL/hydra/tree/main/openspec/architecture) on `main`. GitHub renders it as a browsable index, so we don't mirror it here (the mirror would drift the moment a new ADR lands).
+
+App repos do **NOT** carry copies of the org-wide ADRs. Earlier they had stale duplicates that drifted (e.g. a copy saying `fetch()` while hydra's master said `axios`) — those copies were removed across every app repo that had them.
+
+**How agents see org-wide ADRs:**
+- Reviewer + builder containers copy the relevant ADRs from the hydra repo at image-build time.
+- Agents operating in an app repo outside a container (IDE humans, manual `/opsx-ff` runs) read them from hydra's `main` branch directly.
+- `specter-prepare-context` surfaces the applicable org-wide ADRs in `context-brief.md` for each spec so the builder sees them pre-loaded.
+
+**Rule of thumb for where a new ADR belongs:**
+- Applies to ≥2 Conduction apps → org-wide, in `hydra/openspec/architecture/`.
+- Applies only to one app's domain/storage/auth choice → app-specific, in `<app>/openspec/architecture/`.

docs/hydra/README.md

@@ -24,29 +24,33 @@ 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
-  │
-  │  fail → Builder fix CRITICAL+WARNING (max 3 retries)
-  │         If fix budget exhausted → needs-input label
+  ▼
+Code Reviewer               — reviews + applies bounded in-scope fixes
+  │                           directly to the PR branch
+  │  fail → needs-input (no loop — ADR-013)
+  ▼
+Security Reviewer           — runs after the code reviewer hands off
+  │                           (sequential — reviewers share git state);
+  │                           same bounded fix authority
+  │  fail → needs-input
   ▼
 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. When the weekly Sonnet quota runs out, the Builder falls back to **Haiku** (cheaper, still good at pattern-following from `tasks.md`/`design.md`); the Reviewers and the Applier fall back to **Opus** (deeper, since judgment work is the last line of defense before human approval). Authoritative configuration lives in each persona's `agents/<persona>/config.yaml` in the hydra repo; runtime overrides via `HYDRA_BUILDER_MODEL`, `HYDRA_REVIEWER_MODEL`, `HYDRA_APPLIER_MODEL`, and their `*_FALLBACK_MODEL` counterparts.
 
 ## How to use Hydra on your PR
 
@@ -58,16 +62,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) — the org-wide ADRs (data layer, API, backend, frontend, security, container pool, and more). GitHub renders the directory as a browsable index; the directory itself is the authoritative list.
 - [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/).