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

id, type, title, domain, repo, status, owner, topic_slug, supplier, created, updated, depends_on, tasks, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	supplier	created	updated	depends_on	tasks	state_hub_workstream_id
LOOP-WP-0004	workplan	Loop Regulator (second-order improvement)	coulomb_social	coulomb-loop	active	coulomb-loop	coulomb_social	kaizen-agentic	2026-06-18	2026-06-18	LOOP-WP-0001 LOOP-WP-0002 LOOP-WP-0003	id status title T01 done Define loop health model and cadence state machine id status title T02 done Create loops/ directory structure and cadence.yml per loop id status title T03 todo Draft hourly loop-health-collector ActivityDefinition id status title T04 todo Draft optimization-agent regulator session template id status title T05 todo Hourly bootstrap — collect metrics from all three primary loops id status title T06 todo First cadence promotion decision on LOOP-WP-0001 id status title T07 todo Publish supplier customer-repo playbook draft to kaizen-agentic id status title T08 todo Promote regulator from hourly to daily after meta-loop stabilizes id status title T09 todo Implement diminishing-returns detection and repo rotation per ADR-004	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.

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:

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

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

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

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

id: LOOP-WP-0004-T04
status: todo
priority: high
state_hub_task_id: "e417226b-4175-44b3-8284-7255569e956b"

Create loops/regulator/session-template.md:

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

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

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

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

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)

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