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.

docs/adr/ADR-001-workplan-prefix.md

@@ -0,0 +1,41 @@
+---
+id: ADR-001
+title: Workplan ID Prefix Convention
+status: accepted
+date: "2026-06-18"
+---
+
+# ADR-001 — Workplan ID Prefix Convention
+
+## Status
+
+Accepted
+
+## Context
+
+`register_project.sh` derives the workplan prefix from the repo slug first token:
+`coulomb-loop` → `COULOMB-WP`. The engagement workplans were authored as
+`LOOP-WP-0001` through `LOOP-WP-0004` before registration, and state-hub
+`fix-consistency` indexed them under those IDs.
+
+Renaming to `COULOMB-WP` would churn 4 workstreams, 30 tasks, and cross-references
+in INTENT.md with no functional benefit.
+
+## Decision
+
+Adopt **`LOOP-WP`** as the canonical workplan prefix for `coulomb-loop`.
+
+- File pattern: `workplans/LOOP-WP-NNNN-<slug>.md`
+- Task IDs: `LOOP-WP-NNNN-Tnn`
+- Override the auto-derived `COULOMB-WP` in `.claude/rules/workplan-convention.md`
+
+## Consequences
+
+- Consistent with engagement naming ("loop" operations)
+- state-hub workstream slugs remain `loop-wp-0001-*`
+- Future coulomb_social repos (e.g. product apps) should use their own prefix
+
+## Related
+
+- state-hub ADR-001 (workplans as repo artefacts)
+- `docs/decisions/DEC-001-pilot-roster-scope.md` (separate concern)

docs/adr/ADR-002-customer-supplier-boundary.md

@@ -0,0 +1,62 @@
+---
+id: ADR-002
+title: Customer–Supplier Engagement Boundary
+status: accepted
+date: "2026-06-18"
+---
+
+# ADR-002 — Customer–Supplier Engagement Boundary
+
+## Status
+
+Accepted
+
+## Context
+
+Coulomb hired kaizen-agentic as a **supplier** of agents and improvement
+expertise. Agents must improve Coulomb's fleet without becoming part of Coulomb's
+application codebases or the supplier's product repo.
+
+## Decision
+
+### coulomb-loop (customer) owns
+
+- Engagement INTENT, SCOPE, workplans, decisions
+- Loop rosters (`loops/*/roster.yaml`)
+- ActivityDefinition **copies** tuned for Coulomb cadence
+- Loop health records and cadence state (`loops/*/cadence.yml`, `health.jsonl`)
+- state-hub progress events for the engagement
+
+### kaizen-agentic (supplier) owns
+
+- Agent markdown definitions (`agents/agent-*.md`)
+- CLI (`schedule`, `metrics`, `memory`, `validate`)
+- ADRs for memory, metrics, scheduled execution (ADR-002–005)
+- ActivityDefinition **reference** templates
+- Customer-repo bootstrap playbook (KAIZEN-WP-0008)
+
+### Target repos (fleet) hold runtime state
+
+- `.kaizen/schedule.yml` — opt-in per repo
+- `.kaizen/agents/<name>/memory.md` — project-scoped agent memory
+- `.kaizen/metrics/<name>/` — execution metrics
+
+### Shared operators (not owned by either repo)
+
+| System | Role |
+|--------|------|
+| activity-core | Cron/event → task creation |
+| state-hub | Fleet roster, workstream index |
+| reuse-surface | Capability registry CLI and federation |
+
+## Consequences
+
+- No agent definitions are copied into `coulomb-loop`
+- No scheduling runtime code in `coulomb-loop`
+- Supplier improvements flow back via KAIZEN-WP-0008, not by merging into coulomb-loop
+- Customer may fork ActivityDefinitions without waiting for supplier release
+
+## Related
+
+- `INTENT.md`
+- `docs/adr/ADR-003-cadence-ramp-policy.md`

docs/adr/ADR-003-cadence-ramp-policy.md

@@ -0,0 +1,57 @@
+---
+id: ADR-003
+title: Loop Cadence Ramp Policy
+status: accepted
+date: "2026-06-18"
+---
+
+# ADR-003 — Loop Cadence Ramp Policy
+
+## Status
+
+Accepted
+
+## Context
+
+Self-improvement loops need fast feedback while mechanics are unproven, but
+hourly fleet-wide execution creates task noise and operator fatigue. A explicit
+ramp policy is required before activity-core definitions are enabled.
+
+## Decision
+
+All first-order loops (LOOP-WP-0001–0003) follow a **three-phase cadence ramp**
+governed by the second-order loop (LOOP-WP-0004):
+
+| Phase | Cron | Entry | Exit (promote) |
+|-------|------|-------|----------------|
+| **bootstrap** | hourly | loop workplan `active` | 3 consecutive successful E2E cycles; `manual_rescues == 0` |
+| **stabilize** | daily | bootstrap exit + regulator approval | 14 daily cycles; `false_positive_rate < 0.2` |
+| **operate** | weekly | stabilize exit + regulator approval | — (demote on sustained noise) |
+
+### Demotion triggers (any one)
+
+- `false_positive_rate > 0.4` over 3 cycles
+- `manual_rescues >= 2` in 24 hours
+- Operator override (documented in state-hub decision)
+
+### Authority
+
+- **Promotions:** LOOP-WP-0004 regulator session recommends; human commits `cadence.yml`
+- **Demotions:** regulator may create urgent task; human commits within 24h
+- **No autonomous cron changes** without a committed `cadence.yml` update
+
+### Bootstrap batching (LOOP-WP-0003)
+
+Hourly registry hygiene uses **round-robin** (3 repos/hour), not full-fleet scan.
+
+## Consequences
+
+- activity-core definitions ship with `enabled: false` until bootstrap smoke passes
+- Initial hourly crons are **time-boxed**; regulator must schedule first promotion review
+- Supplier ADR-005 weekly defaults are overridden by engagement `cadence.yml` during bootstrap
+
+## Related
+
+- `INTENT.md` § Cadence Ramp Policy
+- `LOOP-WP-0004-loop-regulator.md`
+- `docs/decisions/DEC-002-event-vs-sweep-quality.md`

docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md

@@ -0,0 +1,85 @@
+---
+id: ADR-004
+title: Repo Rotation on Diminishing Returns
+status: accepted
+date: "2026-06-18"
+decided_by: Bernd Worsch
+implementation: deferred
+---
+
+# ADR-004 — Repo Rotation on Diminishing Returns
+
+## Status
+
+Accepted (design). Implementation deferred to LOOP-WP-0004 T09 after bootstrap
+metrics baseline exists.
+
+## Context
+
+The pilot roster (DEC-001, option A) starts with three custodian repos. Fleet
+expansion will add more repos over time. Running optimization indefinitely on a
+repo that has stopped yielding measurable improvement wastes agent sessions and
+delays under-served repos.
+
+Operator direction (2026-06-18): introduce a method to **detect diminishing
+returns** and **switch optimization focus to another repo**.
+
+## Decision
+
+The loop regulator (LOOP-WP-0004) shall maintain a **rotation policy** alongside
+cadence ramp (ADR-003). When a repo is classified as **saturated**, optimization
+agent runs deprioritize or pause for that repo; the next **queued** repo receives
+focus.
+
+### Saturation signals (evaluate per repo, per agent)
+
+A repo is candidate-saturated when **all** of the following hold over a rolling
+window (default: 14 cycles at current cadence):
+
+| Signal | Threshold |
+|--------|-----------|
+| Quality plateau | `avg_quality` delta < 0.02 vs prior window |
+| Success stable | `success_rate` ≥ 0.85 |
+| Optimizer stall | `recommendations.jsonl` has no new actionable items in window |
+| Marginal gain | Coach/optimization sessions produce no merged PRs or hub progress events |
+
+Configurable in `loops/regulator/rotation-policy.yml`. Regulator may recommend
+saturation when **3 of 4** signals fire (default).
+
+### Rotation actions
+
+1. Set `loops/kaizen-stack/roster.yaml` entry `status: saturated` with `saturated_at`
+2. Disable `optimization` in target repo `.kaizen/schedule.yml` (or set `enabled: false`)
+3. Promote next repo from `expansion_queue` to `active`
+4. Record state-hub decision + progress event
+5. optimization agent session on **new** repo gets elevated priority
+
+Rotation is **recommendation-first** during bootstrap; regulator proposes,
+human commits roster change. Automated rotation after LOOP-WP-0004 T09 proves
+signal accuracy (target: daily phase).
+
+### Expansion queue
+
+`loops/kaizen-stack/roster.yaml` carries:
+
+```yaml
+active: [...]      # currently receiving optimization focus
+expansion_queue:   # ordered candidates after pilot
+saturated: [...]   # repos paused pending new signals or manual revisit
+```
+
+Revisit saturated repos monthly or on external trigger (CI regression, new workstream).
+
+## Consequences
+
+- Optimization effort flows to highest marginal-value repos
+- LOOP-WP-0004 health model gains `marginal_gain` and `saturation_score` fields
+- KAIZEN-WP-0008 may add `metrics rotation-signals` CLI helper (supplier)
+- activity-core definitions must respect roster `status` in resolver filter (future)
+
+## Related
+
+- DEC-001 (pilot roster)
+- ADR-003 (cadence ramp)
+- LOOP-WP-0004 T09
+- `loops/regulator/rotation-policy.yml`

docs/decisions/DEC-001-pilot-roster-scope.md

@@ -0,0 +1,72 @@
+# DEC-001 — Pilot Roster Scope
+
+**Status:** accepted
+**Date:** 2026-06-18
+**Owner:** Bernd (Coulomb operator)
+**Blocks:** LOOP-WP-0001 T02, LOOP-WP-0003 T05
+
+---
+
+## Question
+
+Which repositories should participate in the **bootstrap-phase** self-improvement
+loops before fleet expansion?
+
+## Context
+
+LOOP-WP-0001 proposes three custodian-domain pilots:
+
+- `kaizen-agentic` — supplier dogfood
+- `the-custodian` — state-hub / coordination operator
+- `activity-core` — scheduler owner
+
+The full Coulomb fleet has **57 state-hub repos** across 12 domains. Hourly
+bootstrap on all repos would create unsustainable task volume.
+
+## Options
+
+### A — Custodian pilot only (recommended default)
+
+**3 repos:** `kaizen-agentic`, `the-custodian`, `activity-core`
+
+| Pros | Cons |
+|------|------|
+| All loop infrastructure owners in one batch | Does not exercise coulomb_social domain repos |
+| Minimal noise; fast E2E proof | Fleet improvement delayed |
+| Aligns with supplier WP-0006 pilot design | |
+
+### B — Custodian pilot + one coulomb_social repo
+
+**4 repos:** option A + `vergabe-teilnahme`
+
+| Pros | Cons |
+|------|------|
+| Validates engagement under customer domain | Mixed stack (Django app vs infra repos) |
+| Product-facing dogfood | Extra setup for app-specific agents |
+
+### C — Domain-stratified mini-pilot (5 repos)
+
+**5 repos:** option A + `reuse-surface` + `vergabe-teilnahme`
+
+| Pros | Cons |
+|------|------|
+| Covers helix_forge registry + coulomb_social product | More hourly tasks; slower bootstrap exit |
+| Exercises LOOP-WP-0003 registry hygiene early | |
+
+## Recommendation
+
+**Option A** for bootstrap; expand via LOOP-WP-0003 domain rollout after
+LOOP-WP-0004 approves first promotion to daily.
+
+## Decision record
+
+| Field | Value |
+|-------|-------|
+| Chosen option | **A** — custodian pilot only (3 repos) |
+| Decided by | Bernd Worsch |
+| Decided at | 2026-06-18 |
+| Notes | Fleet expansion via expansion_queue; rotation per ADR-004 when diminishing returns detected |
+
+## On approval
+
+Update `loops/kaizen-stack/roster.yaml` and close LOOP-WP-0001 T02.

docs/decisions/DEC-002-event-vs-sweep-quality.md

@@ -0,0 +1,67 @@
+# DEC-002 — Quality Escalation Trigger Strategy
+
+**Status:** accepted
+**Date:** 2026-06-18
+**Owner:** Bernd
+**Blocks:** LOOP-WP-0002 T03, T05, T07
+
+---
+
+## Question
+
+Should reactive quality escalation (LOOP-WP-0002) use **event-driven** triggers,
+**hourly sweep** polling, or **both**?
+
+## Context
+
+Supplier draft `low-success-rate-review` expects NATS event `kaizen.metrics.recorded`.
+That emitter does not exist in `kaizen-agentic metrics record` today (KAIZEN-WP-0008 T03).
+
+LOOP-WP-0002 proposes hourly sweep as bootstrap scaffolding until events ship.
+
+## Options
+
+### A — Sweep first, events later (recommended)
+
+1. Bootstrap: hourly `discover_kaizen_projects` sweep only
+2. After KAIZEN-WP-0008 ships emitter: enable event definition; demote sweep to daily backup
+
+| Pros | Cons |
+|------|------|
+| Unblocks LOOP-WP-0002 without supplier code | Higher hub load during bootstrap |
+| Proven pattern (activity-core shell resolvers) | Latency up to 1 hour |
+
+### B — Block until event emitter ships
+
+Wait for `metrics record --emit-event` before any LOOP-WP-0002 automation.
+
+| Pros | Cons |
+|------|------|
+| Clean architecture | Delays reactive loop entirely |
+| No duplicate triggers | LOOP-WP-0004 lacks quality signal data |
+
+### C — Dual from day one
+
+Run hourly sweep **and** events when available; dedupe by `(repo, agent, hour)`.
+
+| Pros | Cons |
+|------|------|
+| Fastest signal once events land | Duplicate task risk; complex dedupe |
+| | Harder to tune false-positive rate |
+
+## Recommendation
+
+**Option A.** Document emitter contract now (LOOP-WP-0002 T03); implement in
+KAIZEN-WP-0008; keep sweep as documented backup per ADR-003 stabilize phase.
+
+## Decision record
+
+| Field | Value |
+|-------|-------|
+| Chosen option | **A** — sweep first, events later |
+| Decided by | Bernd Worsch |
+| Decided at | 2026-06-18 |
+
+## On approval
+
+Update `loops/quality-escalation/thresholds.yml` trigger section.

docs/decisions/DEC-003-activity-definition-ownership.md

@@ -0,0 +1,66 @@
+# DEC-003 — ActivityDefinition Copy vs Reference
+
+**Status:** accepted
+**Date:** 2026-06-18
+**Owner:** Bernd
+**Blocks:** LOOP-WP-0001 T04, activity-core sync workflow
+
+---
+
+## Question
+
+How should coulomb-loop ActivityDefinitions relate to kaizen-agentic supplier templates?
+
+## Context
+
+ADR-002 assigns ActivityDefinition **copies** to the customer repo. activity-core
+syncs from its own catalog path (ACT-ADR-002). Two sync models are possible.
+
+## Options
+
+### A — Customer-owned copies (recommended)
+
+Copy supplier templates into `coulomb-loop/activity-definitions/`. activity-core
+syncs from coulomb-loop path (or vendored subtree). Customer edits cron, labels,
+roster params without supplier release.
+
+| Pros | Cons |
+|------|------|
+| Coulomb controls cadence ramp (hourly bootstrap) | Drift from supplier templates |
+| Matches ADR-002 | Manual merge when supplier updates templates |
+
+### B — Supplier catalog only
+
+Reference supplier repo path; activity-core syncs `kaizen-agentic/docs/integrations/activity-definitions/`.
+
+| Pros | Cons |
+|------|------|
+| Single source of truth | Hourly bootstrap crons don't match supplier weekly defaults |
+| Less copy maintenance | Customer cannot tune without supplier PR |
+
+### C — Hybrid manifest
+
+`coulomb-loop/activity-definitions/manifest.yaml` lists supplier source + local overrides (cron, enabled, labels). activity-core merge tool applies patches.
+
+| Pros | Cons |
+|------|------|
+| Drift-aware automation | Requires new activity-core or coulomb-loop tooling |
+| Best long-term for multiple customers | Not available today |
+
+## Recommendation
+
+**Option A** for bootstrap (minimal tooling). Track **Option C** in KAIZEN-WP-0008
+as supplier playbook enhancement for second customer.
+
+## Decision record
+
+| Field | Value |
+|-------|-------|
+| Chosen option | **A** — customer-owned copies |
+| Decided by | Bernd Worsch |
+| Decided at | 2026-06-18 |
+| Notes | Option C hybrid manifest tracked in KAIZEN-WP-0008 T08 |
+
+## On approval
+
+Proceed with LOOP-WP-0001 T04 copy step; document merge procedure in `loops/kaizen-stack/supplier-notes.md`.

docs/decisions/DEC-004-supplier-playbook-priority.md

@@ -0,0 +1,70 @@
+# DEC-004 — Supplier Playbook Delivery Priority
+
+**Status:** accepted
+**Date:** 2026-06-18
+**Owner:** Bernd
+**Blocks:** KAIZEN-WP-0008 sequencing
+
+---
+
+## Question
+
+What should kaizen-agentic (supplier) prioritize **before** vs **after** first
+hourly loop smoke test?
+
+## Context
+
+KAIZEN-WP-0008 bundles supplier obligations: customer-repo template, event emitter,
+engagement CLI, playbook. Full delivery before smoke test delays customer value;
+minimal delivery risks rework.
+
+## Options
+
+### A — Smoke-first, playbook parallel (recommended)
+
+**Before smoke test (KAIZEN-WP-0008 Part 1):**
+
+- Document customer-repo layout (reference: coulomb-loop)
+- Support pilot `schedule init` on target repos (docs only; CLI exists)
+
+**After smoke test (KAIZEN-WP-0008 Part 2):**
+
+- `metrics record --emit-event`
+- `schedule init --engagement` scaffold
+- Playbook v1 in supplier repo
+
+| Pros | Cons |
+|------|------|
+| Fastest proof of LOOP-WP-0001 | Playbook incomplete until smoke passes |
+| Playbook informed by real friction | |
+
+### B — Playbook-first
+
+Complete customer-repo template and engagement CLI before any activity-core enable.
+
+| Pros | Cons |
+|------|------|
+| Second customer ready sooner | Delays all loop automation |
+| | Speculative without smoke data |
+
+### C — Automation-first
+
+Prioritize activity-core resolver + event emitter; defer playbook to LOOP-WP-0004 T07.
+
+| Pros | Cons |
+|------|------|
+| Unblocks LOOP-WP-0002 events | Customer repo conventions undocumented |
+| Cross-repo focus | Harder for humans to operate engagement |
+
+## Recommendation
+
+**Option A.** Record friction in `loops/*/supplier-notes.md` during smoke test;
+feed into playbook draft at LOOP-WP-0004 T07 / KAIZEN-WP-0008 Part 2.
+
+## Decision record
+
+| Field | Value |
+|-------|-------|
+| Chosen option | **A** — smoke-first, playbook parallel |
+| Decided by | Bernd Worsch |
+| Decided at | 2026-06-18 |

docs/integrations/activity-core-handoff.md

@@ -0,0 +1,35 @@
+# activity-core Handoff — coulomb-loop Bootstrap
+
+**Customer:** coulomb-loop
+**Status:** ready for activity-core PR/issue
+
+## Prerequisites (done)
+
+- [x] Pilot roster: `loops/kaizen-stack/roster.yaml`
+- [x] `.kaizen/schedule.yml` on kaizen-agentic, the-custodian, activity-core
+- [x] ActivityDefinition copies in `coulomb-loop/activity-definitions/` (all `enabled: false`)
+
+## activity-core checklist
+
+- [ ] Implement or verify `discover_kaizen_scheduled_repos` with `roster` param
+- [ ] Extend `discover_kaizen_projects` with `roster` filter for pilot scope
+- [ ] Copy definitions from `coulomb-loop/activity-definitions/` to catalog
+- [ ] `make sync-activity-definitions`
+- [ ] Dry-run hourly chain (no `enabled: true` yet)
+- [ ] Enable `hourly-metrics-optimize` first after dry-run pass
+
+## Smoke commands (pilot)
+
+```bash
+kaizen-agentic schedule validate --target /home/worsch/kaizen-agentic
+kaizen-agentic schedule prepare coach --target /home/worsch/kaizen-agentic
+kaizen-agentic metrics optimize --target /home/worsch/kaizen-agentic
+```
+
+## Definition enable order
+
+1. `hourly-metrics-optimize`
+2. `hourly-coach-orientation`
+3. `hourly-optimization-review`
+4. `hourly-metrics-health-sweep`
+5. `low-success-rate-review` (after KAIZEN-WP-0008 T03)