docs(claude): migrate Hydra pipeline info from hydra/CLAUDE.md into .github docs

[WilcoLouwerse]

Background

hydra/CLAUDE.md currently mixes two audiences:

1. Hydra operators — script internals, orchestrator contracts, secrets/.env, slot system, crontab, image builds, watch-list / mechanical-fix retrospectives.
2. All Conduction developers — what the agent personas do, what code-review:fail means on their issue, how labels map to board columns, how retry:queued / rebuild:queued work, the list of org-wide ADRs.

The second audience's info will be removed from hydra/CLAUDE.md (cleanup by a co-worker), so it needs a home in this repo first.

Scope (migrate)

Create docs/claude/hydra-pipeline.md covering:

• Hydra + Specter loop overview
• Four container personas (Al Gorithm, Juan Claude van Damme, Clyde Barcode, Axel Pliér) — role, model, fallback, turn budget (verified against agents/<persona>/config.yaml, not the stale CLAUDE.md table)
• Pipeline flow (build → quality → reviews → applier → merge), no-loop policy (ADR-013)
• Label state machine (stage:state convention, transitions, metadata labels, deprecated labels)
• Canonical label color scheme
• Yolo auto-merge semantics
• Open Specs board stages (the six canonical columns)
• Issue recovery decision order (merge dev→PR / reset review labels / retry:queued / rebuild:queued)
• Hourly auto-update via cron-update-prs.sh
• Pointer to the hydra repo for operator-level docs

Expand docs/claude/writing-adrs.md:

• Ownership split: hydra/openspec/architecture/ = org-wide; <app>/openspec/architecture/ = app-specific
• List of 29 org-wide ADRs (001–025 + 029–032; 026–028 reserved/in-flight) — verified against /home/wilco/hydra/openspec/architecture/

Update docs/claude/README.md:

• Replace stale 3-agent table in Related: Hydra CI/CD Pipeline with a 1-line link to the new doc
• Add hydra-pipeline.md to the Guides list

Update CONTRIBUTING.md:

• Short PR size subsection: prefer one PR per logically-coherent finding/feature; consider splitting past ~10 commits / ~30 files; release-promotion PRs are the exception.

Out of scope (stays in hydra/CLAUDE.md)

Operator-only material: HYDRA_* env var overrides, label-helper / stage-guard contracts, hydra.json schema + record-or-die rule, slot system internals, secrets/.env contract, crontab, image-build flow, watch-list and decidesk retrospective entries.

Verifications

• ADRs on disk in hydra/openspec/architecture/ cross-checked with the CLAUDE.md table — CLAUDE.md claims "024-028 reserved" but ADRs 024 and 025 do exist; reality is 026-028 are reserved.
• Persona configs read directly from hydra/agents/<persona>/config.yaml — Al Gorithm is sonnet (default), not haiku as CLAUDE.md still says; Juan Claude budget is 200 turns, not 150 as CLAUDE.md says.

Branch

docs/migrate-hydra-pipeline-info (off main).

[WilcoLouwerse]

Split into two PRs for staged merge:

PR	Scope	Status
#57 — ADR ownership split + PR-size guidance (docs/adr-ownership-and-pr-size)	docs/claude/writing-adrs.md (+ADR ownership split + linked table of 29 org-wide ADRs), CONTRIBUTING.md (+ PR Size subsection)	Ready for review
#58 — Hydra pipeline developer reference (docs/hydra-pipeline-reference)	docs/claude/hydra-pipeline.md (new), docs/claude/README.md (refreshed Hydra section + Guides entry)	Draft — DO NOT MERGE YET per request; hold until coordinated with the hydra repo's CLAUDE.md trim

Both branches sit on top of current main (19a1af2). None of my files conflict with the 12 upstream commits that landed during work, so both merge cleanly.

PR #58 carries Closes #56, so this issue auto-closes when the Hydra doc lands. PR #57 uses Refs #56 and leaves the issue open.

[WilcoLouwerse]

Update — merged into a single PR:

• docs: ADR practice, PR-size, and Hydra-reference fixes #57 now carries everything: ADR ownership split + 29-ADR list (writing-adrs.md), PR-size subsection (CONTRIBUTING.md), docs/claude/README.md redirect to the existing /hydra/ doc, and stale-fact corrections to docs/hydra/README.md (Builder default model, ADR count, yolo label name, no-loop policy, sequential reviewers).
• docs(hydra): fix stale facts + point Related section at existing /hydra/ doc #58 closed without merging — its single commit (afd4ffd) was cherry-picked onto the docs: ADR practice, PR-size, and Hydra-reference fixes #57 branch.

#57 carries Closes #56, so this issue will auto-close when #57 merges.

Note on docs/hydra/README.md: scope was kept narrow — only factual corrections, no character changes (it's a public-facing entry page on docs.conduction.nl). The broader label-state-machine / four-persona / recovery-flow material from the original draft of docs/claude/hydra-pipeline.md did not make it in; that material stays in hydra/CLAUDE.md for now. We can revisit if a developer-facing label reference turns out to be needed.

[WilcoLouwerse]

Fact-check pass on docs/hydra/README.md (commit e509266 on the #57 branch, not yet pushed).

What was verified against the hydra repo

Claim in the PR	Verdict	Source of truth
Builder default Sonnet	✅	hydra/agents/al-gorithm/config.yaml (model: sonnet); both hydra-supervisor.sh:73 and orchestrate.sh:526 use ${HYDRA_BUILDER_MODEL:-sonnet}
Builder fallback Haiku	✅	hydra-supervisor.sh:78 — BUILDER_FALLBACK_MODEL="${HYDRA_BUILDER_FALLBACK_MODEL:-haiku}"
Reviewer / Applier fallback Opus	✅	hydra-supervisor.sh:1521 — fallback_model="${HYDRA_REVIEWER_FALLBACK_MODEL:-opus}"; orchestrate.sh:519 comment
29 ADRs	✅	ls hydra/openspec/architecture/adr-*.md | wc -l → 29 (gaps: 026, 027, 028)
yolo label name	✅	scripts/create-labels.sh:105 — create_label "yolo" "${C_ORANGE}" "Auto-merge when all phases pass"
retry:queued / rebuild:queued exist	✅	scripts/create-labels.sh:53,58; orchestrator logic in orchestrate.sh:1106,1190
No-loop policy	✅	adr-013-container-pool.md:33 — "Every post-review outcome is terminal: merge or needs-input. There is no fix-iteration loop and no bugfix container."
Sequential reviewers	✅	hydra/CLAUDE.md:71 — "Either verdict triggers → security-review:queued (sequential hand-off)"
Quality / browser fix "bounded, pre-review"	✅	One-shot in orchestrate.sh:552,570 — no retry counter loop

Two issues I introduced that needed fixing (e509266)

1. I wrote "deeper-model fallback (Haiku for the Builder…)" — but Haiku is shallower than Sonnet, not deeper. Builder falls back to Haiku for cap-friendliness; only reviewers/Applier fall back to the deeper Opus. Rewrote the paragraph to make each direction explicit.
2. The pipeline ASCII diagram drew the two reviewers with ├── / └── (visually parallel) while labelling them sequential — internally contradictory. Redrew as two consecutive linear steps with an inline note about shared git state.

One observation worth flagging (not in scope for #57)

ADR-013's Model strategy table in the hydra repo still lists Build = Haiku as the default, but the runtime (agents/al-gorithm/config.yaml, hydra-supervisor.sh, orchestrate.sh) all default to Sonnet with Haiku as the fallback. The persona config comment dates the change to 2026-04-21 (after Haiku was observed skipping gates). Our doc reflects the runtime reality, not ADR-013's stale table. Worth raising with whoever maintains ADR-013 so it stops contradicting the shipped code.

Status

• Local commit e509266 ready on docs/adr-ownership-and-pr-size; awaiting push authorization to land it on docs: ADR practice, PR-size, and Hydra-reference fixes #57.