coulomb/coulomb-loop
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Bootstrap coulomb-loop engagement: governance, loops, and activity definitions.

Browse Source 
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:
Bernd Worsch
2026-06-18 04:53:51 +02:00
parent d09a5722d5
commit e783dc9a2b
40 changed files with 2783 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
.claude/rules/agents.md Normal file
View File

@@ -0,0 +1,20 @@
## Kaizen Agents
Specialized agent personas available on demand via the state-hub MCP.
**Discover:** `list_kaizen_agents()` — returns all agents with name, description, category
**Load:** `get_kaizen_agent("tdd-workflow")` — returns full instructions; read and follow them
Common agents:
| Agent | Category | When to use |
|-------|----------|-------------|
| `tdd-workflow` | testing | Step-by-step TDD8 workflow for any feature |
| `code-refactoring` | quality | Code quality analysis and safe refactoring |
| `test-maintenance` | testing | Diagnose and fix failing tests |
| `requirements-engineering` | process | Prevent interface/mock mismatches upfront |
| `keepaTodofile` | process | Maintain TODO.md during work |
| `project-management` | process | Track status, determine next steps |
| `datamodel-optimization` | quality | Optimize dataclasses and data structures |
All 17 agents: call `list_kaizen_agents()` for the full list.

25
.claude/rules/architecture.md Normal file
View File

@@ -0,0 +1,25 @@
## Architecture
`coulomb-loop` is a **markdown-first engagement layer** — no application runtime.
```
activity-core (cron/event)
→ state-hub roster + coulomb-loop rosters
→ tasks on target repos
→ kaizen-agentic schedule prepare / metrics CLI
→ coding-agent sessions (supplier agents)
```
### Layers
| Layer | Repo | Role |
|-------|------|------|
| Customer contracts | coulomb-loop | Workplans, ADRs, ActivityDefinition copies, `loops/` |
| Supplier IP | kaizen-agentic | Agents, CLI, ADR-002–006 |
| Scheduler | activity-core | Temporal schedules, resolvers |
| Roster | state-hub | Repo list, workstreams, events |
| Execution state | target repos | `.kaizen/schedule.yml`, memory, metrics |
### Four loops
See `INTENT.md` and LOOP-WP-0001–0004. LOOP-WP-0004 regulates cadence (ADR-003).

38
.claude/rules/first-session.md Normal file
View File

@@ -0,0 +1,38 @@
## First Session Protocol
Triggered when `get_domain_summary("coulomb_social")` shows **no workstreams**.
The project is registered but work has not yet been structured.
**Step 1 — Read, don't write**
- `~/the-custodian/canon/projects/coulomb_social/project_charter_v0.1.md` — purpose, scope
- `~/the-custodian/canon/projects/coulomb_social/roadmap_v0.1.md` — planned phases
- Scan repo root: README, directory structure, existing code or docs
**Step 2 — Survey in-progress work**
Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete.
**Step 3 — Propose workstreams to Bernd**
Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to a
roadmap phase. **Wait for approval before creating.**
**Step 4 — Create workplan file first, then DB record (ADR-001)**
```
workplans/COULOMB-WP-NNNN-<slug>.md ← write this first
```
Then register in the hub:
```
create_workstream(topic_id="36c7421b-c537-4723-bf75-42a3ebc6a1dc", title="...", owner="...", description="...")
create_task(workstream_id="<id>", title="...", priority="high|medium|low")
```
**Step 5 — Record the setup**
```
add_progress_event(
summary="First session: structured coulomb_social into N workstreams, M tasks",
event_type="milestone",
topic_id="36c7421b-c537-4723-bf75-42a3ebc6a1dc",
detail={"workstreams": [...], "tasks_created": M}
)
```
<!-- Delete or archive this file once past first session -->

11
.claude/rules/repo-boundary.md Normal file
View File

@@ -0,0 +1,11 @@
## Repo boundary
This repo owns **coulomb-loop engagement operations** only. It does not own:
- Kaizen agent definitions → `kaizen-agentic`
- activity-core resolvers and Temporal workers → `activity-core`
- State-hub API/MCP → `state-hub` / `the-custodian`
- reuse-surface CLI and federation hub → `reuse-surface`
- Target repo `.kaizen/` state → each fleet repo checkout
Cross-repo handoffs are documented in loop workplans and `docs/adr/ADR-002-customer-supplier-boundary.md`.

15
.claude/rules/repo-identity.md Normal file
View File

@@ -0,0 +1,15 @@
## Repo Identity
**Purpose:** coulomb-loop — Coulomb customer engagement repo for fleet self-improvement loops operated with kaizen-agentic as supplier.
**Domain:** coulomb_social
**Repo slug:** coulomb-loop
**Topic ID:** 36c7421b-c537-4723-bf75-42a3ebc6a1dc
**Supplier:** `kaizen-agentic` (agents, CLI, playbook — not merged into this repo)
**Custodian integration:** Registered in state-hub. Workplans use `LOOP-WP` prefix (ADR-001). Sync after workplan edits:
```bash
cd ~/state-hub && make fix-consistency REPO=coulomb-loop
```

84
.claude/rules/session-protocol.md Normal file
View File

@@ -0,0 +1,84 @@
## Session Protocol
State Hub: http://127.0.0.1:8000
**Step 1 — Orient**
Read the offline-safe brief first — it works without a live hub connection:
```bash
cat .custodian-brief.md
```
Then call the MCP tool for richer cross-domain context when MCP tools are exposed:
```
get_domain_summary("coulomb_social")
```
If MCP tools are unavailable in the current agent session, use the REST API:
```bash
curl -s "http://127.0.0.1:8000/state/summary" | python3 -m json.tool
```
If the hub is offline: `cd ~/state-hub && make api`
**Step 2 — Check inbox**
With MCP tools:
```
get_messages(to_agent="coulomb-loop", unread_only=True)
```
Mark read with `mark_message_read(message_id)`. Reply or act on coordination
requests before proceeding.
Without MCP tools:
```bash
curl -s "http://127.0.0.1:8000/messages/?to_agent=coulomb-loop&unread_only=true" \
| python3 -m json.tool
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
-H "Content-Type: application/json" -d '{}'
```
**Step 3 — Scan workplans**
```bash
ls workplans/
```
For each file with `status: ready`, `active`, or `blocked`, note pending
`wait`/`todo`/`progress` tasks.
**Step 4 — Present brief**
1. **Active workstreams** for `coulomb_social` — title, task counts, blocking decisions
2. **Pending tasks** from `workplans/` + any `[repo:coulomb-loop]` hub tasks
3. **Goal guidance** — if `goal_guidance` in summary:
- `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*
- `alignment_warnings`: flag if active work is not aligned with current goal
4. **Suggested next action** — highest-priority open item
5. **SBOM status** — flag if `last_sbom_at` is unset for this repo
If no workstreams: follow First Session Protocol (`first-session.md`).
**During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()`
> State Hub is a *read model*. Bootstrap tools (`create_workstream`, `create_task`)
> are First Session Protocol only. Work structure belongs in repo files (ADR-001).
**Session close:**
With MCP tools:
```
add_progress_event(summary="...", topic_id="36c7421b-c537-4723-bf75-42a3ebc6a1dc", workstream_id="<uuid>")
```
Without MCP tools:
```bash
curl -s -X POST http://127.0.0.1:8000/progress/ \
-H "Content-Type: application/json" \
-d '{"topic_id":"36c7421b-c537-4723-bf75-42a3ebc6a1dc","workstream_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
```
If workplan files were modified, ensure the local copy is up to date first:
```bash
git -C <repo_path> pull --ff-only
cd ~/state-hub && make fix-consistency REPO=coulomb-loop
```
For repos where implementation runs on a remote machine (e.g. CoulombCore),
use the combined target which pulls before fixing:
```bash
cd ~/state-hub && make fix-consistency-remote REPO=coulomb-loop
```
**C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback
will sync the file to match DB. **C-16** (repo behind remote) blocks all writes
until you pull — intentional to prevent clobbering remote progress.

28
.claude/rules/stack-and-commands.md Normal file
View File

@@ -0,0 +1,28 @@
## Stack and Commands
**Language:** Markdown / YAML coordination artefacts
**Package manager:** none
**Test runner:** none
### Essential commands
```bash
# Sync workplans to state-hub after edits
cd ~/state-hub && make fix-consistency REPO=coulomb-loop
# Validate reuse-surface registry (when entries exist)
reuse-surface validate
# Supplier CLI on target repos (not this repo)
kaizen-agentic schedule validate --target /path/to/target-repo
kaizen-agentic schedule prepare coach --target /path/to/target-repo
```
### Session orientation
```bash
# MCP when available
get_domain_summary("coulomb_social")
```
Fallback: `.custodian-brief.md`

17
.claude/rules/workplan-convention.md Normal file
View File

@@ -0,0 +1,17 @@
## Workplan Convention (ADR-001)
File location: `workplans/LOOP-WP-NNNN-<slug>.md`
ID prefix: `LOOP-WP` (see `docs/adr/ADR-001-workplan-prefix.md`)
Work items originate as files in this repo **before** being registered in the hub.
Ecosystem todos from supplier or other agents arrive as `[repo:coulomb-loop]` hub tasks.
After workplan file updates:
```bash
cd ~/state-hub && make fix-consistency REPO=coulomb-loop
```
Customer loop workplans: LOOP-WP-0000 (bootstrap), LOOP-WP-0001–0004 (loops).
Supplier mirror: `kaizen-agentic` KAIZEN-WP-0008.

11
CLAUDE.md Normal file
View File

@@ -0,0 +1,11 @@
# coulomb-loop — Claude Code Instructions
@SCOPE.md
@.claude/rules/repo-identity.md
@.claude/rules/session-protocol.md
@.claude/rules/first-session.md
@.claude/rules/workplan-convention.md
@.claude/rules/stack-and-commands.md
@.claude/rules/architecture.md
@.claude/rules/repo-boundary.md
@.claude/rules/agents.md

156
INTENT.md Normal file
View File

@@ -0,0 +1,156 @@
# 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`

66
SCOPE.md Normal file
View File

@@ -0,0 +1,66 @@
# SCOPE
## One-liner
Customer engagement repository for Coulomb fleet self-improvement loops — contracts, rosters, and activity definitions; not agent runtime.
## Core Idea
Coulomb hires kaizen-agentic as supplier. `coulomb-loop` organizes **what** runs,
**where**, and **how often**; supplier agents execute in **target fleet repos**
with project-scoped memory and metrics.
## In Scope
- Engagement INTENT, workplans (LOOP-WP-*), ADRs, decision proposals
- Loop rosters, cadence state, health records under `loops/`
- ActivityDefinition copies for activity-core sync
- state-hub workstream and progress event coordination
- History and assessment artefacts
- reuse-surface capability registration for the engagement itself
## Out of Scope
- Kaizen agent definitions (supplier: `kaizen-agentic`)
- Temporal scheduling and context resolvers (owner: `activity-core`)
- State-hub service code (owner: `state-hub` / `the-custodian`)
- Application code for Coulomb products (e.g. `vergabe-teilnahme`)
- `.kaizen/` runtime state in this repo (lives in target repos)
## Relevant When
- Operating or extending Coulomb fleet self-improvement loops
- Onboarding a new loop or cadence phase
- Reviewing supplier engagement health (LOOP-WP-0004)
## Not Relevant When
- Authoring or publishing kaizen agents (use `kaizen-agentic`)
- Implementing activity-core resolvers (use `activity-core`)
- Product feature work in coulomb_social apps
## Current State
- Status: active (bootstrap)
- Implementation: planning artefacts + hub registration complete
- Stability: evolving (hourly cadence bootstrap pending)
- Usage: internal engagement
## How It Fits
- Upstream: `kaizen-agentic` (supplier), `state-hub` (roster), `reuse-surface` (registry signals)
- Downstream: `activity-core` (task factory), target fleet repos (execution)
- Often used with: `the-custodian`, `issue-core`
## Getting Oriented
- Start with: `INTENT.md`, `.custodian-brief.md`
- Key paths: `workplans/`, `docs/adr/`, `docs/decisions/`, `history/`
- Pending decisions: `docs/decisions/DEC-*.md`
## Related Repositories
- `kaizen-agentic` — supplier agents and CLI
- `activity-core` — scheduled task execution
- `reuse-surface` — capability registry federation
- `the-custodian` — coordination and state-hub operator

38
activity-definitions/hourly-coach-orientation.md Normal file
View File

@@ -0,0 +1,38 @@
---
id: coulomb-hourly-coach-orientation
name: Hourly Kaizen Coach Orientation (coulomb-loop bootstrap)
enabled: false
owner: coulomb-loop
governance: coulomb_social
status: proposed
trigger:
type: cron
cron_expression: "15 * * * *"
timezone: Europe/Berlin
misfire_policy: skip
context_sources:
- type: resolver
query: discover_kaizen_scheduled_repos
params:
roster: /home/worsch/coulomb-loop/loops/kaizen-stack/roster.yaml
cadence: daily
bind_to: context.scheduled_runs
---
# Hourly Kaizen Coach Orientation (bootstrap)
```rule
id: run-hourly-coach
for_each: context.scheduled_runs
bind_as: r
condition: 'r.agent == "coach" and r.enabled == true'
action:
task_template: "Hourly coach orientation: {{r.repo}}"
description: |
{{r.prepare_command}}
Load agents/agent-coach.md, execute coach synthesis.
Session close: kaizen-agentic metrics record coach --success --time <s> --quality <0-1>
target_repo: "{{r.repo}}"
priority: medium
labels: ["kaizen", "agent-run", "coach", "coulomb-loop", "bootstrap"]
```

41
activity-definitions/hourly-metrics-health-sweep.md Normal file
View File

@@ -0,0 +1,41 @@
---
id: coulomb-hourly-metrics-health-sweep
name: Hourly Metrics Health Sweep (coulomb-loop bootstrap)
enabled: false
owner: coulomb-loop
governance: coulomb_social
status: proposed
trigger:
type: cron
cron_expression: "45 * * * *"
timezone: Europe/Berlin
misfire_policy: skip
context_sources:
- type: shell
query: discover_kaizen_projects
params:
marker: .kaizen/metrics
roster: /home/worsch/coulomb-loop/loops/kaizen-stack/roster.yaml
bind_to: context.projects
---
# Hourly Metrics Health Sweep
Bootstrap fallback per DEC-002 option A until `kaizen.metrics.recorded` events ship.
```rule
id: flag-low-success-hourly
for_each: context.projects
bind_as: p
condition: 'p.summary.success_rate < 0.8 and p.summary.execution_count >= 5'
action:
task_template: "Review {{p.agent}} success rate on {{p.repo}}"
description: |
Agent metrics below threshold on {{p.repo}}.
kaizen-agentic metrics show <agent>
kaizen-agentic metrics optimize <agent>
Load agents/agent-optimization.md for review.
target_repo: "{{p.repo}}"
priority: high
labels: ["kaizen", "quality-escalation", "coulomb-loop", "bootstrap"]
```

42
activity-definitions/hourly-metrics-optimize.md Normal file
View File

@@ -0,0 +1,42 @@
---
id: coulomb-hourly-metrics-optimize
name: Hourly Kaizen Metrics Optimization (coulomb-loop bootstrap)
enabled: false
owner: coulomb-loop
governance: coulomb_social
status: proposed
trigger:
type: cron
cron_expression: "0 * * * *"
timezone: Europe/Berlin
misfire_policy: skip
context_sources:
- type: shell
query: discover_kaizen_projects
params:
marker: .kaizen/metrics
roster: /home/worsch/coulomb-loop/loops/kaizen-stack/roster.yaml
bind_to: context.projects
---
# Hourly Kaizen Metrics Optimization (bootstrap)
Runs hourly during coulomb-loop bootstrap phase. Limited to pilot roster
(DEC-001 option A). Promote to daily when LOOP-WP-0004 regulator approves.
```rule
id: run-hourly-optimizer
for_each: context.projects
bind_as: p
condition: 'p.has_metrics == true and p.in_pilot_roster == true'
action:
task_template: "Run kaizen metrics optimize on {{p.repo}}"
description: |
cd {{p.root}} && kaizen-agentic metrics optimize
Optional: kaizen-agentic metrics publish (when artifact-store configured)
target_repo: "{{p.repo}}"
priority: medium
labels: ["kaizen", "metrics", "optimizer", "coulomb-loop", "bootstrap"]
```
**Supplier reference:** `kaizen-agentic/docs/integrations/activity-definitions/weekly-metrics-optimize.md`

40
activity-definitions/hourly-optimization-review.md Normal file
View File

@@ -0,0 +1,40 @@
---
id: coulomb-hourly-optimization-review
name: Hourly Kaizen Optimization Review (coulomb-loop bootstrap)
enabled: false
owner: coulomb-loop
governance: coulomb_social
status: proposed
trigger:
type: cron
cron_expression: "30 * * * *"
timezone: Europe/Berlin
misfire_policy: skip
context_sources:
- type: resolver
query: discover_kaizen_scheduled_repos
params:
roster: /home/worsch/coulomb-loop/loops/kaizen-stack/roster.yaml
cadence: daily
bind_to: context.scheduled_runs
---
# Hourly Kaizen Optimization Review (bootstrap)
```rule
id: run-hourly-optimization
for_each: context.scheduled_runs
bind_as: r
condition: 'r.agent == "optimization" and r.enabled == true'
action:
task_template: "Hourly optimization review: {{r.repo}}"
description: |
{{r.prepare_command}}
kaizen-agentic metrics optimize
Load agents/agent-optimization.md; act on recommendations.
Session close: kaizen-agentic metrics record optimization --success --time <s> --quality <0-1>
If saturation signals fire (ADR-004), file regulator rotation recommendation.
target_repo: "{{r.repo}}"
priority: medium
labels: ["kaizen", "agent-run", "optimization", "coulomb-loop", "bootstrap"]
```

32
activity-definitions/low-success-rate-review.md Normal file
View File

@@ -0,0 +1,32 @@
---
id: coulomb-low-success-rate-review
name: Low Agent Success Rate Review (event-driven)
enabled: false
owner: coulomb-loop
governance: coulomb_social
status: proposed
trigger:
type: event
event_type: kaizen.metrics.recorded
context_sources:
- type: event-payload
bind_to: context.metrics
---
# Low Agent Success Rate Review
Activates after KAIZEN-WP-0008 T03 (`metrics record --emit-event`). Until then,
use `hourly-metrics-health-sweep.md`.
```rule
id: flag-low-success-rate
condition: 'context.metrics.summary.success_rate < 0.8 and context.metrics.summary.execution_count >= 5'
action:
task_template: "Review {{context.metrics.agent}} success rate ({{context.metrics.summary.success_rate}})"
description: |
kaizen-agentic metrics show {{context.metrics.agent}}
kaizen-agentic metrics optimize {{context.metrics.agent}}
target_repo: "{{context.metrics.project}}"
priority: high
labels: ["kaizen", "quality-escalation", "coulomb-loop"]
```

41
docs/adr/ADR-001-workplan-prefix.md Normal file
View File

@@ -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)

62
docs/adr/ADR-002-customer-supplier-boundary.md Normal file
View File

@@ -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`

57
docs/adr/ADR-003-cadence-ramp-policy.md Normal file
View File

@@ -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`

85
docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md Normal file
View File

@@ -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 &lt; 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`

72
docs/decisions/DEC-001-pilot-roster-scope.md Normal file
View File

@@ -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.

67
docs/decisions/DEC-002-event-vs-sweep-quality.md Normal file
View File

@@ -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.

66
docs/decisions/DEC-003-activity-definition-ownership.md Normal file
View File

@@ -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`.

70
docs/decisions/DEC-004-supplier-playbook-priority.md Normal file
View File

@@ -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 |

35
docs/integrations/activity-core-handoff.md Normal file
View File

@@ -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)

150
history/2026-06-18-initial-codebase-assessment.md Normal file
View File

@@ -0,0 +1,150 @@
# Initial Codebase Assessment — coulomb-loop
**Date:** 2026-06-18
**Assessor:** kaizen-agentic supplier session (automated + repo scan)
**Domain:** coulomb_social
**State Hub:** registered (`coulomb-loop`, topic `coulomb-social`)
---
## Executive summary
`coulomb-loop` is a **greenfield customer engagement repository** created to
operate Coulomb's fleet self-improvement loops with `kaizen-agentic` as supplier.
At assessment time the repo contains **intent and planning artefacts only** —
no runtime code, no `.kaizen/` state, no synced ActivityDefinitions, and no
active loop executions. That is correct for the engagement model: this repo is a
**contract and operations layer**, not an application.
Registration with state-hub completed on 2026-06-18. Four workplans
(LOOP-WP-0001–0004) are indexed with 30 hub tasks. Automation path is clear;
blockers are cross-repo (activity-core resolver, pilot opt-in on target repos).
---
## Repository inventory
| Path | Present | Notes |
|------|---------|-------|
| `INTENT.md` | yes | Customer/supplier model, four loops, cadence ramp |
| `SCOPE.md` | stub → filled | Was register script stub; now aligned to INTENT |
| `README.md` | yes | One-liner only; sufficient for now |
| `workplans/LOOP-WP-0001..0004` | yes | Synced to state-hub (4 workstreams) |
| `registry/` | yes | reuse-surface scaffold; 0 capabilities |
| `activity-definitions/` | no | Planned in LOOP-WP-0001 T04 |
| `loops/` | no | Planned in LOOP-WP-0004 T02 |
| `docs/adr/` | no | Created in this session |
| `history/` | this file | |
| `.claude/rules/` | yes | Generated by `register_project.sh`; needs content |
| `CLAUDE.md` | yes | Generated; imports rules |
| `.kaizen/` | no | Not expected in customer repo (lives in target repos) |
**Language / stack:** Markdown-first coordination repo. No package manifest.
Verification: `git diff --check`, state-hub `make fix-consistency REPO=coulomb-loop`.
---
## Ecosystem context (assessed 2026-06-18)
### State Hub fleet
- **57 repos** registered (including `coulomb-loop`)
- **12 domains**; `coulomb-loop` under `coulomb_social` alongside `vergabe-teilnahme`
- **49+ repos** document state-hub session protocol in agent instructions
### Reuse-surface
- **53 repos** with `registry/` federation participation
- `coulomb-loop` has empty registry scaffold (expected for engagement repo)
### kaizen-agentic (supplier)
- **20 agents** across 7 categories
- ADR-005 schedule contract shipped (`schedule init|validate|list|prepare`)
- **5 ActivityDefinition drafts** in supplier repo (`enabled: false`)
- `discover_kaizen_scheduled_repos` resolver **not yet** in activity-core
### activity-core (scheduler)
- Active jobs: `weekly-sbom-staleness`, `weekly-coding-retro`
- the-custodian: `daily-statehub-wsjf-triage` (enabled)
- No kaizen loop definitions synced yet
### Target-repo readiness (pilot)
| Repo | `.kaizen/schedule.yml` | `.kaizen/metrics/` | Registry |
|------|------------------------|-------------------|----------|
| `kaizen-agentic` | absent | absent | yes |
| `the-custodian` | absent | absent | yes |
| `activity-core` | absent | absent | yes |
**Gap:** pilot repos need `schedule init` + `memory init` (LOOP-WP-0001 T03).
---
## Workplan status at assessment
| ID | Title | Hub tasks | Blocker |
|----|-------|-----------|---------|
| LOOP-WP-0001 | Kaizen improvement stack | 8 open | activity-core resolver |
| LOOP-WP-0002 | Reactive quality escalation | 7 open | LOOP-WP-0001 metrics scaffold |
| LOOP-WP-0003 | Registry hygiene | 7 open | shell resolver for reuse-surface |
| LOOP-WP-0004 | Loop regulator | 8 open | LOOP-WP-0001–0003 health data |
Supplier track: `KAIZEN-WP-0008` (kaizen-agentic) created in same session.
---
## Automation posture
**Ready for automation today:**
- state-hub registration and workplan sync (`fix-consistency`)
- workplan-driven task tracking (30 hub tasks)
- `kaizen-agentic schedule prepare` on target repos (once schedule exists)
- reuse-surface `validate` / `report gaps` (CLI, manual or shell resolver)
**Requires cross-repo automation (not in coulomb-loop):**
| Capability | Owner | Status |
|------------|-------|--------|
| `discover_kaizen_scheduled_repos` | activity-core | spec only |
| `discover_kaizen_projects` shell resolver | activity-core | referenced, unverified |
| `kaizen.metrics.recorded` NATS event | kaizen-agentic + activity-core | spec only |
| `reuse_surface_report_gaps` resolver | activity-core | proposed in LOOP-WP-0003 |
| Hourly cron definitions | activity-core | drafts in coulomb-loop pending |
**Automation principle adopted:** coulomb-loop commits **definition copies** and
**roster declarations**; activity-core owns trigger firing. No Temporal code in
customer repo (ADR-002).
---
## Risks
1. **Hourly cadence noise** — mitigated by LOOP-WP-0004 regulator and phased ramp.
2. **Workplan prefix mismatch** — register script derived `COULOMB-WP`; engagement uses `LOOP-WP` (ADR-001 documents choice).
3. **topic_id was null at register** — patched to `coulomb-social` topic post-register.
4. **Pilot scope creep** — decision needed on fleet vs custodian-only pilot (DEC-001).
---
## Recommended next actions (automated where possible)
1. ~~Register in state-hub~~ (done)
2. Fill `loops/kaizen-stack/roster.yaml` (LOOP-WP-0001 T02)
3. `kaizen-agentic schedule init` on pilot repos (LOOP-WP-0001 T03)
4. Copy ActivityDefinitions to `activity-definitions/` (LOOP-WP-0001 T04)
5. Open activity-core handoff PR checklist (LOOP-WP-0001 T05)
6. Resolve open decisions in `docs/decisions/` before fleet expansion
---
## Related
- `INTENT.md`
- `docs/adr/ADR-001-workplan-prefix.md`
- `docs/adr/ADR-002-customer-supplier-boundary.md`
- `docs/adr/ADR-003-cadence-ramp-policy.md`
- `docs/decisions/` — pending operator decisions
- Supplier: `kaizen-agentic/workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md`

17
loops/kaizen-stack/bootstrap-log.md Normal file
View File

@@ -0,0 +1,17 @@
# Kaizen Stack Bootstrap Log
| Timestamp (UTC) | Repo | Step | Outcome | Notes |
|-----------------|------|------|---------|-------|
| 2026-06-18T04:52 | kaizen-agentic | schedule init + memory init | pass | 3 agents, 2 enabled |
| 2026-06-18T04:52 | the-custodian | schedule init + memory init | pass | |
| 2026-06-18T04:52 | activity-core | schedule init + memory init | pass | |
| 2026-06-18T04:53 | kaizen-agentic | bootstrap hourly schedule patch | pass | coach :15, optimization :30 |
| 2026-06-18T04:53 | all pilots | schedule validate | pass | |
| 2026-06-18T04:53 | kaizen-agentic | schedule prepare coach | pass | 6947 bytes bundle |
| 2026-06-18T04:53 | kaizen-agentic | metrics optimize | pass | insufficient_data (0 records; expected) |
| 2026-06-18T04:53 | kaizen-agentic | schedule prepare optimization | pass | non-empty bundle |
| 2026-06-18T04:54 | the-custodian | schedule prepare coach+optimization | pass | 6900/9643 bytes |
| 2026-06-18T04:54 | activity-core | schedule prepare coach+optimization | pass | 6900/9643 bytes |
**Bootstrap exit (single repo):** manual smoke pass; 0/3 consecutive hourly E2E cycles (activity-core not wired yet).
**Next:** activity-core handoff (LOOP-WP-0001 T05); seed sample metrics for optimizer threshold.

7
loops/kaizen-stack/cadence.yml Normal file
View File

@@ -0,0 +1,7 @@
loop: kaizen-improvement-stack
phase: bootstrap
cron: "0 * * * *"
promoted_at: null
demotion_count: 0
regulator_approval: pending
notes: Hourly chain — metrics :00, coach :15, optimization :30 (per-repo schedule.yml)

34
loops/kaizen-stack/roster.yaml Normal file
View File

@@ -0,0 +1,34 @@
version: "1"
loop: kaizen-improvement-stack
decision: DEC-001 option A (2026-06-18)
phase: bootstrap
# Repos currently receiving scheduled optimization/coach runs
active:
- slug: kaizen-agentic
root: /home/worsch/kaizen-agentic
agents: [coach, optimization]
status: active
rationale: supplier dogfood
- slug: the-custodian
root: /home/worsch/the-custodian
agents: [coach, optimization]
status: active
rationale: state-hub coordination operator
- slug: activity-core
root: /home/worsch/activity-core
agents: [coach, optimization]
status: active
rationale: scheduler owner
# Ordered candidates after pilot — promoted by regulator (ADR-004)
expansion_queue:
- slug: reuse-surface
agents: [coach, optimization, scope-analyst]
domain: helix_forge
- slug: vergabe-teilnahme
agents: [coach, scope-analyst]
domain: coulomb_social
# Repos paused after diminishing-returns detection (ADR-004)
saturated: []

8
loops/kaizen-stack/supplier-notes.md Normal file
View File

@@ -0,0 +1,8 @@
# Supplier Notes (kaizen-agentic friction log)
| Date | Observation | Suggested supplier fix |
|------|-------------|------------------------|
| 2026-06-18 | `schedule init` defaults weekly; bootstrap needs manual cron patch | KAIZEN-WP-0008 `schedule init --engagement --bootstrap-cadence hourly` |
| 2026-06-18 | `metrics optimize` runs with 0 records (OK) but message could link to engagement | Document bootstrap expectation in playbook |
| 2026-06-18 | No `--emit-event` yet for LOOP-WP-0002 | KAIZEN-WP-0008 T03 |
| 2026-06-18 | Rotation signals need aggregator CLI | KAIZEN-WP-0008 ADR-004 follow-on `metrics rotation-signals` |

4
loops/quality-escalation/cadence.yml Normal file
View File

@@ -0,0 +1,4 @@
loop: quality-escalation
phase: bootstrap
cron: "45 * * * *"
regulator_approval: pending

25
loops/quality-escalation/thresholds.yml Normal file
View File

@@ -0,0 +1,25 @@
version: "1"
decision: DEC-002 option A
triggers:
low_success_rate:
threshold: 0.8
min_executions: 5
agent: optimization
priority: high
quality_decline:
consecutive_declines: 3
agent: optimization
priority: medium
optimizer_unacted:
check: recommendations.jsonl
agent: optimization
priority: medium
bootstrap:
mechanism: hourly_sweep
definition: hourly-metrics-health-sweep
stabilize:
mechanism: event_primary
definition: low-success-rate-review
backup_sweep_cron: "0 6 * * *"

23
loops/regulator/health-model.md Normal file
View File

@@ -0,0 +1,23 @@
# Loop Health Model
Per LOOP-WP-0004 T01. Metrics appended to `loops/<loop-id>/health.jsonl`.
## Per-loop metrics
| Field | Source |
|-------|--------|
| `tasks_created` | state-hub / activity-core |
| `tasks_completed` | state-hub task status |
| `manual_rescues` | `bootstrap-log.md` entries |
| `false_positive_rate` | duplicate tasks / total |
| `agent_success_rate` | `.kaizen/metrics/<agent>/summary.json` |
| `mean_session_time_sec` | metrics executions |
## Per-repo rotation (ADR-004)
| Field | Source |
|-------|--------|
| `saturation_score` | `rotation-policy.yml` signals |
| `marginal_gain` | hub progress events + git activity proxy |
See `rotation-policy.yml` for thresholds.

38
loops/regulator/rotation-policy.yml Normal file
View File

@@ -0,0 +1,38 @@
version: "1"
adr: ADR-004
status: design # implementation in LOOP-WP-0004 T09
window_cycles: 14
signals_required: 3 # of 4 below
signals:
quality_plateau:
metric: avg_quality_delta
threshold: 0.02
comparison: prior_window
success_stable:
metric: success_rate
threshold: 0.85
operator: gte
optimizer_stall:
metric: new_actionable_recommendations
threshold: 0
operator: eq
marginal_gain:
metric: progress_events_or_merged_changes
threshold: 0
operator: eq
actions_on_saturation:
- set_roster_status: saturated
- disable_schedule_agent: optimization
- promote_next_from: expansion_queue
- record_decision: state-hub
- elevate_priority: optimization_session
revisit_saturated:
cadence: monthly
triggers:
- ci_regression
- new_active_workstream
- manual_operator_request

19
loops/regulator/state-machine.md Normal file
View File

@@ -0,0 +1,19 @@
# Cadence State Machine
```
bootstrap (hourly) ──promote──▶ stabilize (daily) ──promote──▶ operate (weekly)
▲ │ │
└──────── demote (noise/SLA) ──┴────────────────────────────┘
```
Promotion requires LOOP-WP-0004 regulator approval + ADR-003 exit criteria.
## Repo rotation (ADR-004, parallel track)
```
active ──saturate──▶ saturated ──revisit/monthly──▶ active
│
└── promote from expansion_queue when saturation frees a slot
```
Rotation is recommendation-first during bootstrap.

150
workplans/LOOP-WP-0000-engagement-bootstrap.md Normal file
View File

@@ -0,0 +1,150 @@
---
id: LOOP-WP-0000
type: workplan
title: "Engagement bootstrap (registration, assessment, governance)"
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: []
tasks:
- id: T01
status: done
title: Register coulomb-loop in state-hub under coulomb_social
- id: T02
status: done
title: Persist initial codebase assessment in history/
- id: T03
status: done
title: Accept ADR-001 ADR-002 ADR-003 and publish decision proposals
- id: T04
status: done
title: Sync workplans to state-hub via fix-consistency
- id: T05
status: done
title: Open supplier track KAIZEN-WP-0008 in kaizen-agentic
- id: T06
status: done
title: Resolve DEC-001 through DEC-004 operator decisions
- id: T07
status: done
title: Fill SCOPE.md and .claude/rules integration stubs
- id: T08
status: todo
title: Register reuse-surface capability entry for loop orchestration
state_hub_workstream_id: "0df6df54-4313-4c2d-93f2-dc6844fe47ec"
---
# LOOP-WP-0000 — Engagement Bootstrap
**Status:** active
**Owner:** coulomb-loop
**Purpose:** One-time (and ongoing governance) setup before loop automation runs.
## Goal
Establish `coulomb-loop` as a registered, governed customer engagement repo with
documented assessment, ADRs, pending decisions, and hub-indexed workplans — minimal
manual steps, maximum automation downstream.
## Register and assess (done 2026-06-18)
```task
id: LOOP-WP-0000-T01
status: done
priority: high
state_hub_task_id: "0d29d8a3-5326-4da2-8e5b-d78af13d7388"
```
`register_project.sh coulomb_social /home/worsch/coulomb-loop`; topic_id and description patched.
```task
id: LOOP-WP-0000-T02
status: done
priority: high
state_hub_task_id: "1ebb94ed-7a44-425f-bd32-862602d77817"
```
`history/2026-06-18-initial-codebase-assessment.md` committed.
```task
id: LOOP-WP-0000-T03
status: done
priority: high
state_hub_task_id: "5c300ba3-7bdf-4db7-96f5-cc3d5454eac1"
```
ADR-001–003 accepted; DEC-001–004 published under `docs/decisions/`.
```task
id: LOOP-WP-0000-T04
status: done
priority: high
state_hub_task_id: "f45e0ea8-ce58-4fee-8d30-f145b0c5beea"
```
`make fix-consistency REPO=coulomb-loop` — LOOP-WP-0001–0004 indexed.
```task
id: LOOP-WP-0000-T05
status: done
priority: high
state_hub_task_id: "0cb1f5be-26ea-4d85-9bd1-b30bb69ea127"
```
`kaizen-agentic/workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md` created and synced.
## Completed (2026-06-18)
- state-hub registration (`coulomb_social`, topic `coulomb-social`)
- Repo description and topic_id patched via API
- `history/2026-06-18-initial-codebase-assessment.md`
- ADR-001 (LOOP-WP prefix), ADR-002 (boundary), ADR-003 (cadence ramp)
- DEC-001–DEC-004 decision proposals
- LOOP-WP-0001–0004 synced (4 workstreams, 30 tasks)
- KAIZEN-WP-0008 opened in kaizen-agentic (supplier)
## Resolve operator decisions
```task
id: LOOP-WP-0000-T06
status: done
priority: high
state_hub_task_id: "97509454-9a93-4a80-a12b-e459f3cd01c5"
```
Accepted option A for DEC-001–004 (2026-06-18). ADR-004 records diminishing-returns
repo rotation for later implementation (LOOP-WP-0004 T09). `loops/kaizen-stack/roster.yaml` created.
## Fill orientation files
```task
id: LOOP-WP-0000-T07
status: done
priority: medium
state_hub_task_id: "663661ef-ee8c-4fc6-a552-845d22163012"
```
SCOPE.md and `.claude/rules/{repo-identity,architecture,repo-boundary,stack-and-commands,workplan-convention}.md` filled.
## reuse-surface capability entry
```task
id: LOOP-WP-0000-T08
status: todo
priority: low
state_hub_task_id: "54f5e683-0081-4db1-abdb-4f57323f840e"
```
Add capability row for fleet loop orchestration engagement (D0 scaffold).
Run `reuse-surface validate` when entry drafted.
## Definition of done
- All DEC-* resolved or explicitly deferred with owner date
- SCOPE and rules files non-stub
- LOOP-WP-0001 unblocked for roster + schedule scaffold

281
workplans/LOOP-WP-0001-kaizen-improvement-stack.md Normal file
View File

@@ -0,0 +1,281 @@
---
id: LOOP-WP-0001
type: workplan
title: "Kaizen Improvement Stack (coach + metrics + optimization)"
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: []
tasks:
- id: T01
status: done
title: Register coulomb-loop in state-hub and sync workplans
- id: T02
status: done
title: Declare pilot roster for kaizen improvement stack
- id: T03
status: done
title: Scaffold .kaizen/schedule.yml on pilot target repos
- id: T04
status: done
title: Copy and tune ActivityDefinitions for hourly bootstrap cadence
- id: T05
status: todo
title: activity-core handoff — enable resolver and sync definitions
- id: T06
status: done
title: Hourly bootstrap smoke test on single pilot repo
- id: T07
status: todo
title: Expand pilot to three repos and record metrics at session close
- id: T08
status: todo
title: Promote cadence to daily after bootstrap exit criteria met
state_hub_workstream_id: "90a05147-7b95-4ce7-96bf-39cdb487b557"
---
# LOOP-WP-0001 — Kaizen Improvement Stack
**Status:** active
**Owner:** coulomb-loop (customer)
**Supplier:** kaizen-agentic
**Repo:** coulomb-loop
## Goal
Establish the **primary self-improvement loop** for the Coulomb fleet: a chained
sequence that turns project metrics into coach synthesis and optimization action.
```mermaid
flowchart LR
AC[activity-core hourly cron]
RES[discover_kaizen_scheduled_repos]
M[metrics optimize]
C[schedule prepare coach]
O[schedule prepare optimization]
AC --> RES --> M --> C --> O
```
This loop generalizes the supplier's Monday Stack (`weekly-metrics-optimize` →
`weekly-coach-orientation` → `weekly-optimization-review`) into a **cadence-ramped**
engagement starting at **hourly** during bootstrap.
## Customer / supplier boundary
| coulomb-loop (customer) | kaizen-agentic (supplier) |
|-------------------------|---------------------------|
| Pilot roster, acceptance criteria, cadence policy | Agent prompts, `schedule` / `metrics` CLI, ADR-005 contract |
| ActivityDefinition copies under `activity-definitions/` | Reference definitions in `docs/integrations/activity-definitions/` |
| Loop health records in `loops/kaizen-stack/` | Customer-repo bootstrap learnings fed back to supplier |
Agents (`coach`, `optimization`) accumulate memory in **target repos**, not in
`coulomb-loop`. This repo holds contracts and operations only.
## Cadence ramp
| Phase | Cron (Europe/Berlin) | ActivityDefinitions |
|-------|----------------------|---------------------|
| Bootstrap | `0 * * * *` (hourly) | `hourly-metrics-optimize`, `hourly-coach-orientation`, `hourly-optimization-review` |
| Stabilize | `0 8 * * *` (daily 08:00) | rename/switch to daily variants |
| Operate | Mon 08:00–10:00 (weekly) | align with supplier weekly templates |
Promotion from hourly → daily requires LOOP-WP-0004 regulator sign-off after
bootstrap exit criteria (see Part 4).
## Part 1 — Engagement bootstrap
## Register coulomb-loop in state-hub
```task
id: LOOP-WP-0001-T01
status: done
priority: high
state_hub_task_id: "c66d2e98-8f3e-4119-89e7-2b6f67b6596d"
```
Completed 2026-06-18: `register_project.sh coulomb_social`, topic_id patched,
`fix-consistency` indexed LOOP-WP-0001–0004. See LOOP-WP-0000.
## Declare pilot roster
```task
id: LOOP-WP-0001-T02
status: done
priority: high
state_hub_task_id: "65994889-2f41-46e3-9c47-00cedc59fd81"
```
DEC-001 option A accepted. `loops/kaizen-stack/roster.yaml` committed with
`active` (3 custodian pilots), `expansion_queue`, and `saturated` per ADR-004.
## Scaffold schedule opt-in on pilot repos
```task
id: LOOP-WP-0001-T03
status: done
priority: high
state_hub_task_id: "2293b8bd-20b1-4d54-bd1c-8311004e59f9"
```
Completed 2026-06-18: `schedule init`, `memory init coach|optimization`, bootstrap
hourly crons (`coach :15`, `optimization :30`) on kaizen-agentic, the-custodian,
activity-core. All `schedule validate` pass.
## Scaffold schedule opt-in on pilot repos (reference)
In each pilot **target repo** (not coulomb-loop):
```bash
kaizen-agentic schedule init --timezone Europe/Berlin
kaizen-agentic schedule validate
```
Override defaults for bootstrap:
```yaml
agents:
coach:
cadence: daily # schema enum; cron carries hourly during bootstrap
cron: "0 * * * *"
enabled: true
optimization:
cadence: daily
cron: "30 * * * *" # offset 30 min after metrics+coach chain
enabled: true
```
Commit `.kaizen/schedule.yml` in each pilot repo. Initialize metrics dirs:
`kaizen-agentic memory init coach` and `memory init optimization` (creates metrics scaffold).
## Part 2 — activity-core integration
## Copy and tune ActivityDefinitions
```task
id: LOOP-WP-0001-T04
status: done
priority: high
state_hub_task_id: "53025f59-f00a-4792-950a-878e867803b2"
```
Five definitions in `coulomb-loop/activity-definitions/` (hourly stack + quality).
Handoff doc: `docs/integrations/activity-core-handoff.md`.
Copy supplier templates into `coulomb-loop/activity-definitions/`:
| File | Based on | Bootstrap cron |
|------|----------|----------------|
| `hourly-metrics-optimize.md` | `weekly-metrics-optimize` | `0 * * * *` |
| `hourly-coach-orientation.md` | `weekly-coach-orientation` | `15 * * * *` |
| `hourly-optimization-review.md` | `weekly-optimization-review` | `30 * * * *` |
Set `owner: coulomb-loop`, `governance: coulomb_social`, `enabled: false` until
smoke test passes. Resolver params: `domain: custodian` for pilot, `cadence: daily`
(schema) with per-repo cron override from schedule.yml.
## activity-core handoff
```task
id: LOOP-WP-0001-T05
status: todo
priority: high
state_hub_task_id: "16c54902-a1c5-4e24-9bc3-5c7b8c30abe3"
```
Open coordination track with activity-core:
1. Implement `discover_kaizen_scheduled_repos` per supplier spec (if not done)
2. `make sync-activity-definitions` with coulomb-loop copies
3. Dry-run resolver against pilot roster
4. Enable one definition at a time (`hourly-metrics-optimize` first)
Reference: `docs/integrations/activity-core-handoff.md` (coulomb-loop) and
`kaizen-agentic/docs/integrations/activity-core-handoff-wp0006.md` (supplier).
## Part 3 — Pilot and promote
## Hourly bootstrap smoke test (single repo)
```task
id: LOOP-WP-0001-T06
status: done
priority: medium
state_hub_task_id: "a5ecda96-f299-421c-b393-ae54bfbf9ae0"
```
Smoke pass on all 3 pilots (prepare bundles 6.9–9.7 KB). Log:
`loops/kaizen-stack/bootstrap-log.md`. activity-core wiring still pending (T05).
On `kaizen-agentic` only:
```bash
kaizen-agentic schedule validate
kaizen-agentic schedule prepare coach
kaizen-agentic metrics optimize
kaizen-agentic schedule prepare optimization
```
Verify non-empty prepare bundles. Manually simulate activity-core task payload.
Record outcome in `loops/kaizen-stack/bootstrap-log.md`.
**Bootstrap exit (single repo):** 3 consecutive hours where all three steps complete
without manual intervention.
## Three-repo pilot with metrics
```task
id: LOOP-WP-0001-T07
status: todo
priority: medium
state_hub_task_id: "e60fa833-9407-460a-b1d1-7e08850fa291"
```
Enable activity-core definitions for full pilot roster. Each session close:
```bash
kaizen-agentic metrics record coach --success --time <s> --quality <0-1>
kaizen-agentic metrics record optimization --success --time <s> --quality <0-1>
```
**Bootstrap exit (fleet pilot):** 3 consecutive hourly cycles across all 3 repos.
## Promote to daily cadence
```task
id: LOOP-WP-0001-T08
status: todo
priority: low
state_hub_task_id: "7c77ec4f-594c-4122-9c64-af5c4071446d"
```
After LOOP-WP-0004 regulator approves:
1. Update pilot `schedule.yml` crons to daily (`0 8`, `0 9`, `0 10`)
2. Switch activity-core definitions to daily variants
3. Record promotion decision in state-hub
## Definition of done
- Hourly loop runs end-to-end on 3 pilot repos via activity-core task creation
- `schedule prepare` bundles are actionable in coding-agent sessions
- Metrics recorded for coach and optimization on each run
- Cadence promotion path documented and ready for regulator approval
## Out of scope
- Fleet-wide rollout beyond pilot (follows LOOP-WP-0004 approval)
- Implementing resolvers in coulomb-loop (activity-core owns runtime)
- Headless LLM invocation
## Supplier feedback (for kaizen-agentic)
Capture in `loops/kaizen-stack/supplier-notes.md`:
- friction from `schedule init` / `prepare` on customer engagement
- missing CLI flags for engagement repos
- template gaps for customer ActivityDefinition copies

233
workplans/LOOP-WP-0002-reactive-quality-escalation.md Normal file
View File

@@ -0,0 +1,233 @@
---
id: LOOP-WP-0002
type: workplan
title: "Reactive Quality Escalation (signal-driven 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
tasks:
- id: T01
status: done
title: Define escalation signals and thresholds
- id: T02
status: done
title: Draft low-success-rate ActivityDefinition for coulomb-loop
- id: T03
status: todo
title: Specify kaizen.metrics.recorded event emitter contract
- id: T04
status: todo
title: Hourly metrics sweep fallback until event bus is live
- id: T05
status: todo
title: Wire activity-core event trigger and smoke test
- id: T06
status: todo
title: Add test-maintenance escalation path for CI-degraded repos
- id: T07
status: todo
title: Promote sweep cadence from hourly to daily after stabilization
state_hub_workstream_id: "d4d3b624-dad3-4e1d-9db3-e84548d133de"
---
# LOOP-WP-0002 — Reactive Quality Escalation
**Status:** active
**Owner:** coulomb-loop (customer)
**Supplier:** kaizen-agentic
**Depends on:** LOOP-WP-0001 (metrics scaffold on pilot repos)
## Goal
Complement calendar-based improvement (LOOP-WP-0001) with **signal-driven**
escalation: when agent performance or test health degrades, activity-core creates
a high-priority task before drift compounds.
```mermaid
flowchart LR
REC[metrics record at session close]
EVT[kaizen.metrics.recorded]
RULE[low-success-rate-review]
TASK[high-priority hub task]
AGT[optimization / test-maintenance session]
REC --> EVT --> RULE --> TASK --> AGT
```
## Escalation signals
| Signal | Threshold | Agent | Priority |
|--------|-----------|-------|----------|
| Agent success rate | &lt; 0.8 over ≥ 5 executions | `optimization` | high |
| Agent quality trend | declining 3 consecutive records | `optimization` | medium |
| Test failure streak | ≥ 2 CI failures in 24h (pilot) | `test-maintenance` | high |
| Optimizer recommends action | `recommendations.jsonl` non-empty + unacted | `optimization` | medium |
Thresholds live in `loops/quality-escalation/thresholds.yml` (created in T01).
## Cadence ramp
| Phase | Mechanism | Cadence |
|-------|-----------|---------|
| Bootstrap | Hourly metrics **sweep** (poll `.kaizen/metrics/`) | `0 * * * *` |
| Stabilize | Event-driven `kaizen.metrics.recorded` primary; sweep daily backup | daily `0 6 * * *` |
| Operate | Event-only; sweep weekly health check | weekly |
Hourly sweep exists because the event emitter may lag LOOP-WP-0001 bootstrap.
The sweep is **temporary scaffolding**, not the long-term design.
## Part 1 — Signal contract
## Define escalation signals and thresholds
```task
id: LOOP-WP-0002-T01
status: todo
priority: high
state_hub_task_id: "f6f549e5-0d67-49b8-8165-346c64000696"
```
Create `loops/quality-escalation/thresholds.yml` and document each signal's
rationale. Align with supplier `low-success-rate-review` defaults (0.8, min 5).
## Draft low-success-rate ActivityDefinition
```task
id: LOOP-WP-0002-T02
status: todo
priority: high
state_hub_task_id: "a19c2ade-029d-4b1c-ba08-8fd82729e649"
```
Copy `kaizen-agentic/docs/integrations/activity-definitions/low-success-rate-review.md`
to `coulomb-loop/activity-definitions/low-success-rate-review.md`.
Adjust:
- `owner: coulomb-loop`
- `trigger.type: event` with `event_type: kaizen.metrics.recorded`
- task `labels` include `coulomb-loop`, `quality-escalation`
- `enabled: false` until smoke test
## Specify event emitter contract
```task
id: LOOP-WP-0002-T03
status: todo
priority: high
state_hub_task_id: "6dbdb335-9c1d-4db0-ad7d-4342c966cd47"
```
Document expected NATS payload in `loops/quality-escalation/event-payload.md`:
```json
{
"agent": "coach",
"project": "kaizen-agentic",
"summary": {
"success_rate": 0.75,
"execution_count": 12,
"avg_quality": 0.81
}
}
```
Supplier action item: emit event from `kaizen-agentic metrics record` when
`--emit-event` flag set (or always in engagement mode). Track in supplier-notes;
implementation stays in kaizen-agentic.
## Part 2 — Bootstrap sweep (hourly)
## Hourly metrics sweep fallback
```task
id: LOOP-WP-0002-T04
status: todo
priority: medium
state_hub_task_id: "604a9515-0f6b-47e4-8a37-6bfc374ca4f3"
```
Draft `coulomb-loop/activity-definitions/hourly-metrics-health-sweep.md`:
- Resolver: shell `discover_kaizen_projects` with marker `.kaizen/metrics`
- Filter: pilot roster from LOOP-WP-0001
- Condition: read `summary.json`; flag `success_rate < 0.8 && execution_count >= 5`
- Action: create review task with `metrics show` + `metrics optimize` commands
Cron: `45 * * * *` (offset from LOOP-WP-0001 hourly chain).
## Wire activity-core and smoke test
```task
id: LOOP-WP-0002-T05
status: todo
priority: medium
state_hub_task_id: "a5d8a6e1-9908-49a5-8976-900c433cd325"
```
1. Sync sweep definition to activity-core
2. Inject test metrics below threshold on one pilot repo
3. Verify task creation within one hourly cycle
4. Run optimization session; confirm metrics improve on next sweep
When event bus is ready, enable `low-success-rate-review` and keep sweep as
backup only.
## Part 3 — Test health path
## test-maintenance escalation for CI-degraded repos
```task
id: LOOP-WP-0002-T06
status: todo
priority: low
state_hub_task_id: "206d33c2-0a8a-4274-8361-f69291f11b94"
```
Draft `hourly-ci-health-escalation.md` (bootstrap) / `daily-ci-health-escalation.md`
(stabilize):
- Context: state-hub or shell resolver listing pilot repos
- Signal: open CI failure indicator (Gitea API or `make test` exit code in scheduled probe)
- Agent: `test-maintenance` via `schedule prepare test-maintenance`
- Scope: pilot repos only in bootstrap
Defer full fleet CI integration until daily phase.
## Promote sweep to daily
```task
id: LOOP-WP-0002-T07
status: todo
priority: low
state_hub_task_id: "fa4205f4-6058-495c-bcaa-40c20f27f9aa"
```
After LOOP-WP-0004 approval and event trigger proven:
1. Disable hourly sweep
2. Enable event-driven `low-success-rate-review`
3. Retain daily backup sweep at `0 6 * * *`
## Definition of done
- Below-threshold metrics on a pilot repo create a task within one bootstrap cycle
- Optimization session closes loop (success rate recovers or recommendation filed)
- Event payload spec handed to kaizen-agentic supplier
- Cadence promotion path documented
## Out of scope
- Full fleet CI integration in bootstrap phase
- Implementing NATS emitter in coulomb-loop (supplier + activity-core)
## Supplier feedback
Note whether `metrics record --emit-event` should become standard for customer
engagements. Feed into kaizen-agentic customer bootstrap playbook.

246
workplans/LOOP-WP-0003-registry-orientation-hygiene.md Normal file
View File

@@ -0,0 +1,246 @@
---
id: LOOP-WP-0003
type: workplan
title: "Registry & Orientation Hygiene (fleet legibility)"
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
tasks:
- id: T01
status: todo
title: Define hygiene signals and domain rollout order
- id: T02
status: todo
title: Create hourly registry gap sweep ActivityDefinition
- id: T03
status: todo
title: Create scope-analyst orientation task template
- id: T04
status: todo
title: Integrate state-hub SBOM staleness with hygiene roster
- id: T05
status: todo
title: Hourly bootstrap on custodian-domain pilot slice
- id: T06
status: todo
title: Expand to next domain batch after pilot exit
- id: T07
status: todo
title: Promote cadence to daily then weekly
state_hub_workstream_id: "f3a4b60a-7bc2-400d-bf8a-e7209a9e45c4"
---
# LOOP-WP-0003 — Registry & Orientation Hygiene
**Status:** active
**Owner:** coulomb-loop (customer)
**Supplier:** kaizen-agentic (`scope-analyst` agent)
**Partner:** reuse-surface (CLI), state-hub (SBOM status)
## Goal
Prevent **fleet legibility drift** across 56 state-hub repos and 53 reuse-surface
registries. Agents and planners can only improve what they can see; this loop
keeps `SCOPE.md`, capability entries, and SBOM metadata current.
```mermaid
flowchart LR
SH[state-hub repo roster]
RS[reuse-surface report gaps]
SBOM[repo_sbom_status]
SA[schedule prepare scope-analyst]
VAL[reuse-surface validate]
SH --> RS
SH --> SBOM
RS --> SA --> VAL
```
## Hygiene signals
| Signal | Source | Action |
|--------|--------|--------|
| Registry gap | `reuse-surface report gaps` | `scope-analyst` + `establish --publish-check` |
| Empty capability scaffold | federation roster `capability_count: 0` | draft capability entry or mark intentional |
| Stale SCOPE | `SCOPE.md` mtime &gt; 90d or missing | `scope-analyst` refresh |
| Stale SBOM | `sbom_age_days > 30` (state-hub) | flag + link to existing activity-core SBOM job |
| Publish check fail | `publish_check: fail` in federation roster | registry fix task |
Signals documented in `loops/registry-hygiene/signals.yml`.
## Domain rollout order
Bootstrap processes **small batches** to avoid task storms:
1. **custodian** (11 repos) — aligns with LOOP-WP-0001 pilots
2. **helix_forge** (4 repos) — reuse-surface home domain
3. **stack** (3 repos) — artifact-store, open-reuse
4. Remaining domains — one per weekly cycle after daily stabilization
## Cadence ramp
| Phase | Cron | Batch size |
|-------|------|------------|
| Bootstrap | `0 * * * *` (hourly) | 3 repos per run (round-robin) |
| Stabilize | `0 7 * * *` (daily) | 1 domain per day |
| Operate | `0 9 * * 1` (weekly Mon) | 1–2 domains per week |
Hourly bootstrap uses **round-robin** across custodian pilot slice (3 repos per
hour), not full fleet scan.
## Part 1 — Signal and template setup
## Define hygiene signals and rollout order
```task
id: LOOP-WP-0003-T01
status: todo
priority: high
state_hub_task_id: "cacc914e-85e6-4067-b39d-cf8a3ae91320"
```
Create:
- `loops/registry-hygiene/signals.yml`
- `loops/registry-hygiene/rollout.yaml` (domain order + repo slugs)
- `loops/registry-hygiene/round-robin-state.json` (cursor for hourly batching)
## Hourly registry gap sweep ActivityDefinition
```task
id: LOOP-WP-0003-T02
status: todo
priority: high
state_hub_task_id: "7c6b15cd-a5ac-4602-956f-61de72a55fef"
```
Create `coulomb-loop/activity-definitions/hourly-registry-hygiene-sweep.md`:
```yaml
trigger:
cron_expression: "20 * * * *"
context_sources:
- type: state-hub
query: repo_sbom_status
bind_to: context.repos
- type: shell
query: reuse_surface_report_gaps
params:
roster: coulomb-loop/loops/registry-hygiene/rollout.yaml
bind_to: context.gaps
```
Rule: for each repo in current hourly batch with any hygiene signal, create task:
```
kaizen-agentic schedule prepare scope-analyst
reuse-surface validate
reuse-surface establish --publish-check # when registry touched
```
`enabled: false` until shell resolver wrapper exists in activity-core.
## scope-analyst orientation template
```task
id: LOOP-WP-0003-T03
status: todo
priority: medium
state_hub_task_id: "e8eb2700-8ef5-43fb-8d2e-ec080fa86f6f"
```
Create `loops/registry-hygiene/session-template.md` — standard task description
for scope-analyst sessions: read SCOPE, compare to INTENT, update registry index,
file state-hub progress event.
## Part 2 — Integration
## Integrate SBOM staleness with hygiene roster
```task
id: LOOP-WP-0003-T04
status: todo
priority: medium
state_hub_task_id: "09cec748-0bfa-4870-b44f-50813f7ed626"
```
Document handoff with existing `activity-core/weekly-sbom-staleness`:
- Do not duplicate SBOM rescans in this loop
- Hygiene task **links** to SBOM job when `sbom_age_days > 30`
- Shared label: `fleet-hygiene`
Add cross-reference in `loops/registry-hygiene/signals.yml`.
## Hourly bootstrap on custodian pilot slice
```task
id: LOOP-WP-0003-T05
status: todo
priority: medium
state_hub_task_id: "76029879-01ed-4db2-afcf-3876db45b395"
```
Pilot batch: `kaizen-agentic`, `the-custodian`, `activity-core`.
Manual smoke test (before activity-core enable):
```bash
reuse-surface report gaps --roster <rollout.yaml>
kaizen-agentic schedule prepare scope-analyst --target /home/worsch/kaizen-agentic
reuse-surface validate # in target repo
```
**Bootstrap exit:** 3 hourly rounds complete without duplicate tasks for same repo+signal.
## Expand domain batch
```task
id: LOOP-WP-0003-T06
status: todo
priority: low
state_hub_task_id: "f6e5a9d5-2c32-439d-9e95-aa6d6fd3c6ab"
```
After regulator approval, add helix_forge domain to rollout. Increase batch size
when false-positive rate stays below 20%.
## Promote cadence
```task
id: LOOP-WP-0003-T07
status: todo
priority: low
state_hub_task_id: "5b6bb667-42e1-4e41-968e-4025ac2e72ce"
```
| Promotion | Condition |
|-----------|-----------|
| hourly → daily | bootstrap exit + LOOP-WP-0004 approval |
| daily → weekly | 2 weeks daily with &lt; 10% repeat tasks for same signal |
Update activity-core definitions and `loops/registry-hygiene/cadence.yml`.
## Definition of done
- Hygiene sweep creates actionable scope-analyst tasks on pilot repos
- reuse-surface validate passes after hygiene session on at least one repo
- SBOM staleness delegated to existing activity-core job (no duplicate work)
- Domain rollout order and cadence ramp documented
## Out of scope
- Implementing `reuse-surface report gaps` resolver in coulomb-loop
- Mandatory capability maturity promotion (planning-only in bootstrap)
- Full 56-repo hourly scan
## Supplier feedback
Document whether `scope-analyst` needs engagement-specific briefing template.
Feed reuse-surface + kaizen-agentic supplier playbook.

329
workplans/LOOP-WP-0004-loop-regulator.md Normal file
View 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 | &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