---
id: ADR-004
title: Repo Rotation on Diminishing Returns
status: accepted
date: "2026-06-18"
decided_by: Bernd Worsch
implementation: deferred
---

# ADR-004 — Repo Rotation on Diminishing Returns

## Status

Accepted (design). Implementation deferred to LOOP-WP-0004 T09 after bootstrap
metrics baseline exists.

## Context

The pilot roster (DEC-001, option A) starts with three custodian repos. Fleet
expansion will add more repos over time. Running optimization indefinitely on a
repo that has stopped yielding measurable improvement wastes agent sessions and
delays under-served repos.

Operator direction (2026-06-18): introduce a method to **detect diminishing
returns** and **switch optimization focus to another repo**.

## Decision

The loop regulator (LOOP-WP-0004) shall maintain a **rotation policy** alongside
cadence ramp (ADR-003). When a repo is classified as **saturated**, optimization
agent runs deprioritize or pause for that repo; the next **queued** repo receives
focus.

### Saturation signals (evaluate per repo, per agent)

A repo is candidate-saturated when **all** of the following hold over a rolling
window (default: 14 cycles at current cadence):

| Signal | Threshold |
|--------|-----------|
| Quality plateau | `avg_quality` delta < 0.02 vs prior window |
| Success stable | `success_rate` ≥ 0.85 |
| Optimizer stall | `recommendations.jsonl` has no new actionable items in window |
| Marginal gain | Coach/optimization sessions produce no merged PRs or hub progress events |

Configurable in `loops/regulator/rotation-policy.yml`. Regulator may recommend
saturation when **3 of 4** signals fire (default).

### Rotation actions

1. Set `loops/kaizen-stack/roster.yaml` entry `status: saturated` with `saturated_at`
2. Disable `optimization` in target repo `.kaizen/schedule.yml` (or set `enabled: false`)
3. Promote next repo from `expansion_queue` to `active`
4. Record state-hub decision + progress event
5. optimization agent session on **new** repo gets elevated priority

Rotation is **recommendation-first** during bootstrap; regulator proposes,
human commits roster change. Automated rotation after LOOP-WP-0004 T09 proves
signal accuracy (target: daily phase).

### Expansion queue

`loops/kaizen-stack/roster.yaml` carries:

```yaml
active: [...]      # currently receiving optimization focus
expansion_queue:   # ordered candidates after pilot
saturated: [...]   # repos paused pending new signals or manual revisit
```

Revisit saturated repos monthly or on external trigger (CI regression, new workstream).

## Consequences

- Optimization effort flows to highest marginal-value repos
- LOOP-WP-0004 health model gains `marginal_gain` and `saturation_score` fields
- KAIZEN-WP-0008 may add `metrics rotation-signals` CLI helper (supplier)
- activity-core definitions must respect roster `status` in resolver filter (future)

## Related

- DEC-001 (pilot roster)
- ADR-003 (cadence ramp)
- LOOP-WP-0004 T09
- `loops/regulator/rotation-policy.yml`