tegwick
e783dc9a2b
Register with state-hub, accept DEC-001–004 and ADR-004 rotation policy, scaffold pilot roster, hourly ActivityDefinition copies, and bootstrap log after schedule init on three custodian pilot repos.
329 lines
No EOL
9.3 KiB
Markdown
329 lines
No EOL
9.3 KiB
Markdown
---
|
||
id: LOOP-WP-0004
|
||
type: workplan
|
||
title: "Loop Regulator (second-order improvement)"
|
||
domain: coulomb_social
|
||
repo: coulomb-loop
|
||
status: active
|
||
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: todo
|
||
title: Draft hourly loop-health-collector ActivityDefinition
|
||
- id: T04
|
||
status: todo
|
||
title: Draft optimization-agent regulator session template
|
||
- id: T05
|
||
status: todo
|
||
title: Hourly bootstrap — collect metrics from all three primary loops
|
||
- id: T06
|
||
status: todo
|
||
title: First cadence promotion decision on LOOP-WP-0001
|
||
- id: T07
|
||
status: todo
|
||
title: Publish supplier customer-repo playbook draft to kaizen-agentic
|
||
- id: T08
|
||
status: todo
|
||
title: Promote regulator from hourly to daily after meta-loop stabilizes
|
||
- id: T09
|
||
status: todo
|
||
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:** active
|
||
**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: todo
|
||
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: todo
|
||
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: todo
|
||
priority: high
|
||
state_hub_task_id: "734c76b6-9d34-4fdf-b928-b678578a063a"
|
||
```
|
||
|
||
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: todo
|
||
priority: high
|
||
state_hub_task_id: "e417226b-4175-44b3-8284-7255569e956b"
|
||
```
|
||
|
||
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: todo
|
||
priority: medium
|
||
state_hub_task_id: "9d4dc665-15e6-47e4-9f1c-aa9adff5783d"
|
||
```
|
||
|
||
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: todo
|
||
priority: medium
|
||
state_hub_task_id: "e8fb9e66-2212-4c6d-b947-2c22d32f1c53"
|
||
```
|
||
|
||
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: todo
|
||
priority: medium
|
||
state_hub_task_id: "9600bd31-5d85-4623-98f9-e50ec56cde3d"
|
||
```
|
||
|
||
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: todo
|
||
priority: low
|
||
state_hub_task_id: "e67820e4-8e4d-444b-9c3c-a8b3b23e0a11"
|
||
```
|
||
|
||
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: todo
|
||
priority: medium
|
||
state_hub_task_id: "431ebe91-3a6f-475f-a862-a784dbbe29b4"
|
||
```
|
||
|
||
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 |