85 lines
2.9 KiB
Markdown
85 lines
2.9 KiB
Markdown
|
---
|
||
|
|
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`
|