coulomb-loop/workplans/LOOP-WP-0004-loop-regulator.md

---
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 | &gt; 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 | &lt; 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