generated from coulomb/repo-seed
Bootstrap coulomb-loop engagement: governance, loops, and activity definitions.
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.
This commit is contained in:
329
workplans/LOOP-WP-0004-loop-regulator.md
Normal file
329
workplans/LOOP-WP-0004-loop-regulator.md
Normal file
@@ -0,0 +1,329 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user