generated from coulomb/repo-seed
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.
This commit is contained in:
20
.claude/rules/agents.md
Normal file
20
.claude/rules/agents.md
Normal 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
25
.claude/rules/architecture.md
Normal 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
38
.claude/rules/first-session.md
Normal 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
11
.claude/rules/repo-boundary.md
Normal 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
15
.claude/rules/repo-identity.md
Normal 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
84
.claude/rules/session-protocol.md
Normal 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
28
.claude/rules/stack-and-commands.md
Normal 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
17
.claude/rules/workplan-convention.md
Normal 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
11
CLAUDE.md
Normal 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
156
INTENT.md
Normal 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 < 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
66
SCOPE.md
Normal 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
38
activity-definitions/hourly-coach-orientation.md
Normal 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
41
activity-definitions/hourly-metrics-health-sweep.md
Normal 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
42
activity-definitions/hourly-metrics-optimize.md
Normal 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
40
activity-definitions/hourly-optimization-review.md
Normal 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
32
activity-definitions/low-success-rate-review.md
Normal 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
41
docs/adr/ADR-001-workplan-prefix.md
Normal 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
62
docs/adr/ADR-002-customer-supplier-boundary.md
Normal 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
57
docs/adr/ADR-003-cadence-ramp-policy.md
Normal 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
85
docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md
Normal 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 < 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
72
docs/decisions/DEC-001-pilot-roster-scope.md
Normal 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
67
docs/decisions/DEC-002-event-vs-sweep-quality.md
Normal 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
66
docs/decisions/DEC-003-activity-definition-ownership.md
Normal 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
70
docs/decisions/DEC-004-supplier-playbook-priority.md
Normal 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
35
docs/integrations/activity-core-handoff.md
Normal 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
150
history/2026-06-18-initial-codebase-assessment.md
Normal 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
17
loops/kaizen-stack/bootstrap-log.md
Normal 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
7
loops/kaizen-stack/cadence.yml
Normal 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
34
loops/kaizen-stack/roster.yaml
Normal 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
8
loops/kaizen-stack/supplier-notes.md
Normal 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
4
loops/quality-escalation/cadence.yml
Normal file
@@ -0,0 +1,4 @@
|
|||||||
|
loop: quality-escalation
|
||||||
|
phase: bootstrap
|
||||||
|
cron: "45 * * * *"
|
||||||
|
regulator_approval: pending
|
||||||
25
loops/quality-escalation/thresholds.yml
Normal file
25
loops/quality-escalation/thresholds.yml
Normal 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
23
loops/regulator/health-model.md
Normal 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
38
loops/regulator/rotation-policy.yml
Normal 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
19
loops/regulator/state-machine.md
Normal 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
150
workplans/LOOP-WP-0000-engagement-bootstrap.md
Normal 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
281
workplans/LOOP-WP-0001-kaizen-improvement-stack.md
Normal 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
233
workplans/LOOP-WP-0002-reactive-quality-escalation.md
Normal 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 | < 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
246
workplans/LOOP-WP-0003-registry-orientation-hygiene.md
Normal 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 > 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 < 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
329
workplans/LOOP-WP-0004-loop-regulator.md
Normal 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 | > 0 per cycle when expected |
|
||||||
|
| `tasks_completed` | state-hub task status | ≥ 70% within SLA |
|
||||||
|
| `manual_rescues` | bootstrap-log.md entries | 0 for promotion |
|
||||||
|
| `false_positive_rate` | duplicate tasks / total | < 20% |
|
||||||
|
| `agent_success_rate` | `.kaizen/metrics/<agent>/summary.json` | ≥ 0.8 |
|
||||||
|
| `mean_session_time_sec` | metrics executions | stable or decreasing trend |
|
||||||
|
| `cost_signal` | tasks per hour × session time | tracked, no hard limit in bootstrap |
|
||||||
|
|
||||||
|
Aggregate dashboard: `loops/regulator/dashboard.md` (regenerated each run).
|
||||||
|
|
||||||
|
## Cadence state machine
|
||||||
|
|
||||||
|
```
|
||||||
|
bootstrap (hourly) ──promote──▶ stabilize (daily) ──promote──▶ operate (weekly)
|
||||||
|
▲ │ │
|
||||||
|
└──────── demote (noise/SLA) ──┴────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
Promotion rules (all must hold):
|
||||||
|
|
||||||
|
1. Bootstrap exit criteria from source workplan met
|
||||||
|
2. `false_positive_rate < 0.2` over last 7 cycles
|
||||||
|
3. `manual_rescues == 0` over last 3 cycles
|
||||||
|
4. Regulator session recommends promote (optimization agent)
|
||||||
|
|
||||||
|
Demotion triggers (any one):
|
||||||
|
|
||||||
|
- `false_positive_rate > 0.4` over 3 cycles
|
||||||
|
- `manual_rescues >= 2` in 24h
|
||||||
|
- Operator override
|
||||||
|
|
||||||
|
State stored in `loops/<id>/cadence.yml`:
|
||||||
|
|
||||||
|
```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
|
||||||
Reference in New Issue
Block a user