coulomb-loop/INTENT.md

# INTENT — coulomb-loop

## Project Name

`coulomb-loop`

## One-Line Intent

`coulomb-loop` is Coulomb's engagement repository for **scheduled self-improvement loops** — operated with kaizen-agentic as supplier, activity-core as scheduler, and state-hub as fleet roster.

## Purpose

Coulomb operates a large, multi-domain software fleet (56+ registered repositories).
Improvement cannot rely on ad-hoc sessions alone. This repository exists to **organize,
contract, and operate recurring agent-driven improvement loops** across that fleet —
without absorbing kaizen agents into Coulomb's own codebase.

The engagement model is deliberate:

| Role | Owner | Responsibility |
|------|-------|----------------|
| **Customer** | Coulomb (`coulomb-loop`) | Defines *what* to improve, *which repos*, *at what cadence*, and *acceptance criteria* |
| **Supplier** | `kaizen-agentic` | Provides agents, CLI tooling, memory/metrics conventions, and engagement playbooks |
| **Scheduler** | `activity-core` | Fires cron/event triggers, resolves fleet roster, creates tasks |
| **Roster** | `state-hub` | Canonical repo list, `host_paths`, workstreams, progress events |
| **Registry** | `reuse-surface` | Capability maturity and registry hygiene signals |

Agents are **not Coulomb employees**. They are supplier-provided personas that
accumulate **project-scoped memory** (`.kaizen/agents/<name>/memory.md`) and
**execution metrics** while working in Coulomb's context. That knowledge stays
portable: it improves supplier efficiency for the next customer engagement.

## Core Idea

> Self-improvement at fleet scale needs a **customer engagement repo**, not more
> agents inside the supplier repo.

`coulomb-loop` holds everything Coulomb needs to run the loops:

- workplans and acceptance criteria for each loop
- fleet roster declarations (which repos participate in which loop)
- ActivityDefinition copies tuned for Coulomb cadence
- loop health records and cadence ramp policy
- decisions and progress events surfaced to state-hub

`kaizen-agentic` holds the reusable supplier IP: agent definitions, CLI, ADRs,
and — after this engagement — a **customer-repo bootstrap playbook** so the next
engagement starts faster.

## The Four Loops

This engagement establishes four coordinated workstreams:

| Workplan | Loop | Primary agents | Target |
|----------|------|----------------|--------|
| LOOP-WP-0001 | **Kaizen improvement stack** | `coach`, `optimization` | Evidence-backed weekly-style improvement (metrics → synthesis → action) |
| LOOP-WP-0002 | **Reactive quality escalation** | `optimization`, `test-maintenance` | Signal-driven tasks when agent or test health degrades |
| LOOP-WP-0003 | **Registry & orientation hygiene** | `scope-analyst`, reuse-surface CLI | Fleet legibility — SCOPE, capability registry, SBOM alignment |
| LOOP-WP-0004 | **Loop regulator** (second-order) | `optimization`, `tooling-optimization` | Monitor, throttle, and optimize the three primary loops |

Loops 1–3 are **first-order** improvement. Loop 4 is **second-order**: it
observes whether the first-order loops are worth their cost and tunes them.

## Cadence Ramp Policy

Loops start **fast** to prove mechanics, then **slow** as noise drops and trust rises.

| Phase | Cadence | Entry condition | Exit / promote condition |
|-------|---------|---------------|--------------------------|
| **Bootstrap** | Hourly | Loop workplan `active`; activity-core definition synced | 3 consecutive successful end-to-end runs without manual rescue |
| **Stabilize** | Daily | Bootstrap exit met for all tasks in the loop | 2 weeks daily runs; false-positive rate &lt; 20%; loop regulator approves |
| **Operate** | Weekly | Stabilize exit met | Loop regulator may demote on sustained noise or missed SLAs |

Cadence is stored per loop in `loops/<loop-id>/cadence.yml` (to be created in
LOOP-WP-0004). The loop regulator owns promotions and demotions; operators
approve demotions below daily.

## Repo rotation (diminishing returns)

When optimization on a repo plateaus, the regulator classifies it **saturated**
and rotates focus to the next repo in `loops/kaizen-stack/roster.yaml`
`expansion_queue` (ADR-004). Coach runs may continue; optimization agent sessions
shift to higher marginal-value targets. Implementation: LOOP-WP-0004 T09.

**Hourly during bootstrap is intentional.** It compresses feedback time while
resolver wiring, task payloads, and session-close metrics are still fragile.
It is not the long-term operating frequency.

## Scope

### In scope

- Operating scheduled improvement loops across the Coulomb fleet
- Declaring fleet participation rosters and per-target-repo opt-in (`.kaizen/schedule.yml` in target repos)
- Committing ActivityDefinition copies scoped to this engagement
- Recording loop health, cadence phase, and supplier feedback for kaizen-agentic reuse
- Progress events and decisions via state-hub once `coulomb-loop` is registered
- Pilot on custodian-domain repos, then expand domain-by-domain

### Out of scope

- Owning kaizen agent definitions (supplier: `kaizen-agentic`)
- Implementing Temporal workers or context resolvers (owner: `activity-core`)
- State-hub schema changes (owner: `the-custodian` / `state-hub`)
- Replacing human approval for high-risk changes (releases, infra remediation)
- Merging agents into Coulomb application repositories

## Fleet Context

The Coulomb cocreation environment today includes:

- **56 repos** registered in state-hub across 12 domains
- **53 repos** with reuse-surface `registry/` federation participation
- **20 kaizen agents** available from supplier (`kaizen-agentic`)
- **activity-core** already runs custodian jobs (e.g. SBOM staleness, coding retro)
- **kaizen ActivityDefinitions** drafted in supplier repo (`enabled: false`; resolver pending)

`coulomb-loop` does not duplicate that inventory. It **consumes** it and declares
which slices participate in which loop.

## Supplier Feedback Loop

This engagement is also a product-development exercise for kaizen-agentic:

1. Document what a minimal **customer engagement repo** must contain
2. Capture friction from bootstrap (missing CLI, unclear handoffs, resolver gaps)
3. Feed findings into a future supplier workplan (`KAIZEN-WP-0008` or equivalent):
   customer-repo template, `schedule init --engagement`, engagement checklist

Success for Coulomb **and** the supplier means the second customer engagement
requires materially less setup than this one.

## Design Principles

1. **Repo-local opt-in** — a target repo joins a loop only with valid `.kaizen/schedule.yml` (or loop-specific roster entry).
2. **Prepare, don't invoke** — scheduled tasks run `kaizen-agentic schedule prepare`; sessions execute agent instructions.
3. **Measure every loop** — session close records metrics; loop regulator reads aggregate health.
4. **Fail loud, fail small** — bootstrap hourly runs surface breakage quickly; one repo per pilot before fleet fan-out.
5. **Second-order before scale** — do not promote cadence or expand roster until LOOP-WP-0004 approves.

## Success Criteria

1. Three first-order loops run end-to-end on ≥3 pilot repos with activity-core task creation and successful `schedule prepare` sessions.
2. Loop regulator (LOOP-WP-0004) produces weekly health summaries and has demoted or promoted cadence at least once based on evidence.
3. Supplier playbook draft exists in `kaizen-agentic` citing `coulomb-loop` as reference engagement.
4. `coulomb-loop` registered in state-hub with workstreams synced from `workplans/`.

## Related Documents

- `workplans/LOOP-WP-0001-kaizen-improvement-stack.md`
- `workplans/LOOP-WP-0002-reactive-quality-escalation.md`
- `workplans/LOOP-WP-0003-registry-orientation-hygiene.md`
- `workplans/LOOP-WP-0004-loop-regulator.md`
- Supplier: `kaizen-agentic` ADR-005, `docs/integrations/activity-core-handoff-wp0006.md`
- Scheduler: `activity-core` ActivityDefinition catalog
- Registry: `reuse-surface` `docs/RegistryFederation.md`