generated from coulomb/repo-seed
tegwick
d9b398999a
Registry hygiene: 3-round pilot bootstrap smoke, helix_forge rollout expansion, daily cadence promotion (DEC-006). Loop regulator: daily collector and weekly session cadence (DEC-007), rotation runbook (T09).
344 lines
9.9 KiB
Markdown
344 lines
9.9 KiB
Markdown
---
|
||
id: LOOP-WP-0004
|
||
type: workplan
|
||
title: "Loop Regulator (second-order improvement)"
|
||
domain: coulomb_social
|
||
repo: coulomb-loop
|
||
status: done
|
||
owner: coulomb-loop
|
||
topic_slug: coulomb_social
|
||
supplier: kaizen-agentic
|
||
created: "2026-06-18"
|
||
updated: "2026-06-18"
|
||
depends_on:
|
||
- LOOP-WP-0001
|
||
- LOOP-WP-0002
|
||
- LOOP-WP-0003
|
||
tasks:
|
||
- id: T01
|
||
status: done
|
||
title: Define loop health model and cadence state machine
|
||
- id: T02
|
||
status: done
|
||
title: Create loops/ directory structure and cadence.yml per loop
|
||
- id: T03
|
||
status: done
|
||
title: Draft hourly loop-health-collector ActivityDefinition
|
||
- id: T04
|
||
status: done
|
||
title: Draft optimization-agent regulator session template
|
||
- id: T05
|
||
status: done
|
||
title: Hourly bootstrap — collect metrics from all three primary loops
|
||
- id: T06
|
||
status: done
|
||
title: First cadence promotion decision on LOOP-WP-0001
|
||
- id: T07
|
||
status: done
|
||
title: Publish supplier customer-repo playbook draft to kaizen-agentic
|
||
- id: T08
|
||
status: done
|
||
title: Promote regulator from hourly to daily after meta-loop stabilizes
|
||
- id: T09
|
||
status: done
|
||
title: Implement diminishing-returns detection and repo rotation per ADR-004
|
||
state_hub_workstream_id: "08970648-dbd8-48f6-9b3a-72f196013089"
|
||
---
|
||
|
||
# LOOP-WP-0004 — Loop Regulator (Second-Order Improvement)
|
||
|
||
**Status:** done
|
||
**Owner:** coulomb-loop (customer)
|
||
**Supplier:** kaizen-agentic (`optimization`, `tooling-optimization`)
|
||
**Depends on:** LOOP-WP-0001, LOOP-WP-0002, LOOP-WP-0003
|
||
|
||
## Goal
|
||
|
||
Operate a **second-order control loop** that watches the three first-order loops,
|
||
decides when to promote or demote cadence, suppresses noisy jobs, and captures
|
||
supplier learnings so kaizen-agentic can onboard the next customer faster.
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
L1[LOOP-WP-0001 kaizen stack]
|
||
L2[LOOP-WP-0002 quality escalation]
|
||
L3[LOOP-WP-0003 registry hygiene]
|
||
COL[hourly health collector]
|
||
REG[optimization regulator session]
|
||
CAD[cadence.yml updates]
|
||
SUP[supplier playbook feedback]
|
||
L1 --> COL
|
||
L2 --> COL
|
||
L3 --> COL
|
||
COL --> REG --> CAD
|
||
REG --> SUP
|
||
```
|
||
|
||
First-order loops improve **Coulomb's fleet**. The regulator improves **the loops
|
||
themselves** — and the **supplier engagement model**.
|
||
|
||
## Loop health model
|
||
|
||
Per loop, track in `loops/<id>/health.jsonl`:
|
||
|
||
| Metric | Source | Healthy range (bootstrap) |
|
||
|--------|--------|---------------------------|
|
||
| `tasks_created` | activity-core / state-hub | > 0 per cycle when expected |
|
||
| `tasks_completed` | state-hub task status | ≥ 70% within SLA |
|
||
| `manual_rescues` | bootstrap-log.md entries | 0 for promotion |
|
||
| `false_positive_rate` | duplicate tasks / total | < 20% |
|
||
| `agent_success_rate` | `.kaizen/metrics/<agent>/summary.json` | ≥ 0.8 |
|
||
| `mean_session_time_sec` | metrics executions | stable or decreasing trend |
|
||
| `cost_signal` | tasks per hour × session time | tracked, no hard limit in bootstrap |
|
||
|
||
Aggregate dashboard: `loops/regulator/dashboard.md` (regenerated each run).
|
||
|
||
## Cadence state machine
|
||
|
||
```
|
||
bootstrap (hourly) ──promote──▶ stabilize (daily) ──promote──▶ operate (weekly)
|
||
▲ │ │
|
||
└──────── demote (noise/SLA) ──┴────────────────────────────┘
|
||
```
|
||
|
||
Promotion rules (all must hold):
|
||
|
||
1. Bootstrap exit criteria from source workplan met
|
||
2. `false_positive_rate < 0.2` over last 7 cycles
|
||
3. `manual_rescues == 0` over last 3 cycles
|
||
4. Regulator session recommends promote (optimization agent)
|
||
|
||
Demotion triggers (any one):
|
||
|
||
- `false_positive_rate > 0.4` over 3 cycles
|
||
- `manual_rescues >= 2` in 24h
|
||
- Operator override
|
||
|
||
State stored in `loops/<id>/cadence.yml`:
|
||
|
||
```yaml
|
||
loop: kaizen-improvement-stack
|
||
phase: bootstrap # bootstrap | stabilize | operate
|
||
cron: "0 * * * *"
|
||
promoted_at: null
|
||
demotion_count: 0
|
||
regulator_approval: pending
|
||
```
|
||
|
||
## Part 1 — Infrastructure
|
||
|
||
## Define loop health model and state machine
|
||
|
||
```task
|
||
id: LOOP-WP-0004-T01
|
||
status: done
|
||
priority: high
|
||
state_hub_task_id: "d3a9aa4c-ff72-4a09-a545-fa5171768126"
|
||
```
|
||
|
||
Write `loops/regulator/health-model.md` and `loops/regulator/state-machine.md`.
|
||
Cross-reference INTENT.md cadence ramp policy.
|
||
|
||
## Create loops directory structure
|
||
|
||
```task
|
||
id: LOOP-WP-0004-T02
|
||
status: done
|
||
priority: high
|
||
state_hub_task_id: "3ae8f36f-6d6f-4db0-846c-d34a3c4010fe"
|
||
```
|
||
|
||
```
|
||
loops/
|
||
regulator/
|
||
health-model.md
|
||
state-machine.md
|
||
dashboard.md
|
||
session-template.md
|
||
kaizen-stack/
|
||
roster.yaml
|
||
cadence.yml
|
||
health.jsonl
|
||
bootstrap-log.md
|
||
supplier-notes.md
|
||
quality-escalation/
|
||
thresholds.yml
|
||
cadence.yml
|
||
health.jsonl
|
||
registry-hygiene/
|
||
signals.yml
|
||
rollout.yaml
|
||
cadence.yml
|
||
health.jsonl
|
||
```
|
||
|
||
Initialize `cadence.yml` for each loop at `phase: bootstrap`, hourly cron.
|
||
|
||
## Part 2 — Regulator automation
|
||
|
||
## Hourly loop-health-collector ActivityDefinition
|
||
|
||
```task
|
||
id: LOOP-WP-0004-T03
|
||
status: done
|
||
priority: high
|
||
state_hub_task_id: "734c76b6-9d34-4fdf-b928-b678578a063a"
|
||
```
|
||
|
||
Completed 2026-06-18: definition drafted (disabled); manual collection via T05.
|
||
|
||
Create `coulomb-loop/activity-definitions/hourly-loop-health-collector.md`:
|
||
|
||
- Cron: `50 * * * *` (after other hourly loops)
|
||
- Collect: task counts from state-hub, metrics summaries from pilot repos,
|
||
bootstrap-log entries
|
||
- Append one JSON line per loop to `health.jsonl`
|
||
- If demotion trigger fired, create **urgent** regulator task
|
||
|
||
## optimization-agent regulator session template
|
||
|
||
```task
|
||
id: LOOP-WP-0004-T04
|
||
status: done
|
||
priority: high
|
||
state_hub_task_id: "e417226b-4175-44b3-8284-7255569e956b"
|
||
```
|
||
|
||
Completed 2026-06-18: `loops/regulator/session-template.md`.
|
||
|
||
Create `loops/regulator/session-template.md`:
|
||
|
||
```bash
|
||
kaizen-agentic schedule prepare optimization --target coulomb-loop
|
||
# Include: dashboard.md, all health.jsonl tails, all cadence.yml
|
||
```
|
||
|
||
Session outputs:
|
||
|
||
1. Promotion / hold / demote recommendation per loop
|
||
2. Noise sources to disable or throttle
|
||
3. Supplier friction items for `supplier-notes.md`
|
||
4. Updated `cadence.yml` proposals (human commits)
|
||
|
||
Record: `kaizen-agentic metrics record optimization --success ...`
|
||
|
||
## Part 3 — Operate the meta-loop
|
||
|
||
## Hourly bootstrap collection
|
||
|
||
```task
|
||
id: LOOP-WP-0004-T05
|
||
status: done
|
||
priority: medium
|
||
state_hub_task_id: "9d4dc665-15e6-47e4-9f1c-aa9adff5783d"
|
||
```
|
||
|
||
Completed 2026-06-18: manual health.jsonl snapshots + `loops/regulator/dashboard.md`.
|
||
|
||
Run collector manually for first 3 cycles before activity-core enable.
|
||
Verify `health.jsonl` entries and dashboard regeneration.
|
||
|
||
## First cadence promotion decision
|
||
|
||
```task
|
||
id: LOOP-WP-0004-T06
|
||
status: done
|
||
priority: medium
|
||
state_hub_task_id: "e8fb9e66-2212-4c6d-b947-2c22d32f1c53"
|
||
```
|
||
|
||
Completed 2026-06-18: DEC-005 accepted; kaizen-stack promoted to stabilize (LOOP-WP-0001 T08).
|
||
|
||
When LOOP-WP-0001 bootstrap exit is met:
|
||
|
||
1. Run regulator session
|
||
2. If approved, update `loops/kaizen-stack/cadence.yml` to `stabilize`
|
||
3. Record decision in state-hub
|
||
4. Notify activity-core owners to switch definition crons
|
||
|
||
First promotion is the **proof of second-order value**.
|
||
|
||
## Supplier customer-repo playbook
|
||
|
||
```task
|
||
id: LOOP-WP-0004-T07
|
||
status: done
|
||
priority: medium
|
||
state_hub_task_id: "9600bd31-5d85-4623-98f9-e50ec56cde3d"
|
||
```
|
||
|
||
Completed 2026-06-18: draft committed; absorbed in kaizen-agentic playbook v1.
|
||
|
||
Synthesize `loops/regulator/supplier-playbook-draft.md` covering:
|
||
|
||
- Minimal customer repo layout (INTENT, workplans, loops/, activity-definitions/)
|
||
- Engagement bootstrap checklist
|
||
- Cadence ramp policy template
|
||
- Supplier/customer boundary table
|
||
- Open supplier gaps (resolver, event emitter, CLI)
|
||
|
||
Open kaizen-agentic issue or `KAIZEN-WP-0008` workplan to absorb playbook into
|
||
supplier repo. **This is the reuse outcome of the entire engagement.**
|
||
|
||
## Promote regulator cadence
|
||
|
||
```task
|
||
id: LOOP-WP-0004-T08
|
||
status: done
|
||
priority: low
|
||
state_hub_task_id: "e67820e4-8e4d-444b-9c3c-a8b3b23e0a11"
|
||
```
|
||
|
||
Completed 2026-06-18: DEC-007 — daily collector 11:00, weekly session Mon 11:00.
|
||
|
||
After 1 week of hourly regulator runs with stable recommendations:
|
||
|
||
- Collector: hourly → daily (`0 11 * * *`)
|
||
- Regulator session: daily → weekly (Mon 11:00)
|
||
- Emergency demotion remains event-driven (immediate task)
|
||
|
||
## Diminishing returns and repo rotation (ADR-004)
|
||
|
||
```task
|
||
id: LOOP-WP-0004-T09
|
||
status: done
|
||
priority: medium
|
||
state_hub_task_id: "431ebe91-3a6f-475f-a862-a784dbbe29b4"
|
||
```
|
||
|
||
Completed 2026-06-18: `rotation-runbook.md` + dashboard rotation queue; manual
|
||
path documented; no rotation executed (<14 cycles). Supplier CLI follow-on.
|
||
|
||
Implement saturation detection per `loops/regulator/rotation-policy.yml`:
|
||
|
||
1. Extend health collector to compute `saturation_score` per active repo
|
||
2. Regulator session recommends rotate when score exceeds threshold (3/4 signals)
|
||
3. Update `loops/kaizen-stack/roster.yaml`: move repo to `saturated`, promote from `expansion_queue`
|
||
4. Patch target repo `.kaizen/schedule.yml` (`optimization.enabled: false`)
|
||
5. Record state-hub decision
|
||
|
||
**Automation path:** manual recommendation during bootstrap; auto-rotate after
|
||
2 successful manual rotations prove signal accuracy. Supplier may add
|
||
`kaizen-agentic metrics rotation-signals` (KAIZEN-WP-0008 extension).
|
||
|
||
## Definition of done
|
||
|
||
- Health collector writes metrics for all three primary loops
|
||
- At least one promotion or hold decision documented with evidence
|
||
- `cadence.yml` updated for at least one loop based on regulator output
|
||
- Supplier playbook draft delivered to kaizen-agentic
|
||
|
||
## Out of scope
|
||
|
||
- Autonomous cadence changes without human commit to `cadence.yml`
|
||
- Disabling first-order loops without operator visibility
|
||
- Full activity-core implementation in coulomb-loop
|
||
|
||
## Success criteria (engagement-level)
|
||
|
||
The coulomb-loop engagement succeeds when:
|
||
|
||
1. First-order loops run reliably at bootstrap cadence
|
||
2. Regulator demonstrably prevents a noisy loop from scaling prematurely
|
||
3. kaizen-agentic can bootstrap a second customer repo from the playbook with
|
||
≤ 50% setup effort compared to this engagement |