diff --git a/.claude/rules/agents.md b/.claude/rules/agents.md new file mode 100644 index 0000000..0e8a5d9 --- /dev/null +++ b/.claude/rules/agents.md @@ -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. diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md new file mode 100644 index 0000000..5cb3602 --- /dev/null +++ b/.claude/rules/architecture.md @@ -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). \ No newline at end of file diff --git a/.claude/rules/first-session.md b/.claude/rules/first-session.md new file mode 100644 index 0000000..86f5ad2 --- /dev/null +++ b/.claude/rules/first-session.md @@ -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-.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="", 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} +) +``` + + diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md new file mode 100644 index 0000000..724854f --- /dev/null +++ b/.claude/rules/repo-boundary.md @@ -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`. \ No newline at end of file diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md new file mode 100644 index 0000000..9a1d87c --- /dev/null +++ b/.claude/rules/repo-identity.md @@ -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 +``` \ No newline at end of file diff --git a/.claude/rules/session-protocol.md b/.claude/rules/session-protocol.md new file mode 100644 index 0000000..41aa985 --- /dev/null +++ b/.claude/rules/session-protocol.md @@ -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//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="") +``` +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":"","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 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. diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md new file mode 100644 index 0000000..ab14597 --- /dev/null +++ b/.claude/rules/stack-and-commands.md @@ -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` \ No newline at end of file diff --git a/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md new file mode 100644 index 0000000..be1ba7f --- /dev/null +++ b/.claude/rules/workplan-convention.md @@ -0,0 +1,17 @@ +## Workplan Convention (ADR-001) + +File location: `workplans/LOOP-WP-NNNN-.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. \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..e075dd5 --- /dev/null +++ b/CLAUDE.md @@ -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 diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..a38a645 --- /dev/null +++ b/INTENT.md @@ -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//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//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` \ No newline at end of file diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..269ea45 --- /dev/null +++ b/SCOPE.md @@ -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 \ No newline at end of file diff --git a/activity-definitions/hourly-coach-orientation.md b/activity-definitions/hourly-coach-orientation.md new file mode 100644 index 0000000..faf3306 --- /dev/null +++ b/activity-definitions/hourly-coach-orientation.md @@ -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 --quality <0-1> + target_repo: "{{r.repo}}" + priority: medium + labels: ["kaizen", "agent-run", "coach", "coulomb-loop", "bootstrap"] +``` \ No newline at end of file diff --git a/activity-definitions/hourly-metrics-health-sweep.md b/activity-definitions/hourly-metrics-health-sweep.md new file mode 100644 index 0000000..c0cd699 --- /dev/null +++ b/activity-definitions/hourly-metrics-health-sweep.md @@ -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 + kaizen-agentic metrics optimize + Load agents/agent-optimization.md for review. + target_repo: "{{p.repo}}" + priority: high + labels: ["kaizen", "quality-escalation", "coulomb-loop", "bootstrap"] +``` \ No newline at end of file diff --git a/activity-definitions/hourly-metrics-optimize.md b/activity-definitions/hourly-metrics-optimize.md new file mode 100644 index 0000000..d7976ab --- /dev/null +++ b/activity-definitions/hourly-metrics-optimize.md @@ -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` \ No newline at end of file diff --git a/activity-definitions/hourly-optimization-review.md b/activity-definitions/hourly-optimization-review.md new file mode 100644 index 0000000..568c072 --- /dev/null +++ b/activity-definitions/hourly-optimization-review.md @@ -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 --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"] +``` \ No newline at end of file diff --git a/activity-definitions/low-success-rate-review.md b/activity-definitions/low-success-rate-review.md new file mode 100644 index 0000000..0b3e931 --- /dev/null +++ b/activity-definitions/low-success-rate-review.md @@ -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"] +``` \ No newline at end of file diff --git a/docs/adr/ADR-001-workplan-prefix.md b/docs/adr/ADR-001-workplan-prefix.md new file mode 100644 index 0000000..f275ad2 --- /dev/null +++ b/docs/adr/ADR-001-workplan-prefix.md @@ -0,0 +1,41 @@ +--- +id: ADR-001 +title: Workplan ID Prefix Convention +status: accepted +date: "2026-06-18" +--- + +# ADR-001 — Workplan ID Prefix Convention + +## Status + +Accepted + +## Context + +`register_project.sh` derives the workplan prefix from the repo slug first token: +`coulomb-loop` → `COULOMB-WP`. The engagement workplans were authored as +`LOOP-WP-0001` through `LOOP-WP-0004` before registration, and state-hub +`fix-consistency` indexed them under those IDs. + +Renaming to `COULOMB-WP` would churn 4 workstreams, 30 tasks, and cross-references +in INTENT.md with no functional benefit. + +## Decision + +Adopt **`LOOP-WP`** as the canonical workplan prefix for `coulomb-loop`. + +- File pattern: `workplans/LOOP-WP-NNNN-.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) \ No newline at end of file diff --git a/docs/adr/ADR-002-customer-supplier-boundary.md b/docs/adr/ADR-002-customer-supplier-boundary.md new file mode 100644 index 0000000..8ecb018 --- /dev/null +++ b/docs/adr/ADR-002-customer-supplier-boundary.md @@ -0,0 +1,62 @@ +--- +id: ADR-002 +title: Customer–Supplier Engagement Boundary +status: accepted +date: "2026-06-18" +--- + +# ADR-002 — Customer–Supplier Engagement Boundary + +## Status + +Accepted + +## Context + +Coulomb hired kaizen-agentic as a **supplier** of agents and improvement +expertise. Agents must improve Coulomb's fleet without becoming part of Coulomb's +application codebases or the supplier's product repo. + +## Decision + +### coulomb-loop (customer) owns + +- Engagement INTENT, SCOPE, workplans, decisions +- Loop rosters (`loops/*/roster.yaml`) +- ActivityDefinition **copies** tuned for Coulomb cadence +- Loop health records and cadence state (`loops/*/cadence.yml`, `health.jsonl`) +- state-hub progress events for the engagement + +### kaizen-agentic (supplier) owns + +- Agent markdown definitions (`agents/agent-*.md`) +- CLI (`schedule`, `metrics`, `memory`, `validate`) +- ADRs for memory, metrics, scheduled execution (ADR-002–005) +- ActivityDefinition **reference** templates +- Customer-repo bootstrap playbook (KAIZEN-WP-0008) + +### Target repos (fleet) hold runtime state + +- `.kaizen/schedule.yml` — opt-in per repo +- `.kaizen/agents//memory.md` — project-scoped agent memory +- `.kaizen/metrics//` — 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` \ No newline at end of file diff --git a/docs/adr/ADR-003-cadence-ramp-policy.md b/docs/adr/ADR-003-cadence-ramp-policy.md new file mode 100644 index 0000000..cf2bc29 --- /dev/null +++ b/docs/adr/ADR-003-cadence-ramp-policy.md @@ -0,0 +1,57 @@ +--- +id: ADR-003 +title: Loop Cadence Ramp Policy +status: accepted +date: "2026-06-18" +--- + +# ADR-003 — Loop Cadence Ramp Policy + +## Status + +Accepted + +## Context + +Self-improvement loops need fast feedback while mechanics are unproven, but +hourly fleet-wide execution creates task noise and operator fatigue. A explicit +ramp policy is required before activity-core definitions are enabled. + +## Decision + +All first-order loops (LOOP-WP-0001–0003) follow a **three-phase cadence ramp** +governed by the second-order loop (LOOP-WP-0004): + +| Phase | Cron | Entry | Exit (promote) | +|-------|------|-------|----------------| +| **bootstrap** | hourly | loop workplan `active` | 3 consecutive successful E2E cycles; `manual_rescues == 0` | +| **stabilize** | daily | bootstrap exit + regulator approval | 14 daily cycles; `false_positive_rate < 0.2` | +| **operate** | weekly | stabilize exit + regulator approval | — (demote on sustained noise) | + +### Demotion triggers (any one) + +- `false_positive_rate > 0.4` over 3 cycles +- `manual_rescues >= 2` in 24 hours +- Operator override (documented in state-hub decision) + +### Authority + +- **Promotions:** LOOP-WP-0004 regulator session recommends; human commits `cadence.yml` +- **Demotions:** regulator may create urgent task; human commits within 24h +- **No autonomous cron changes** without a committed `cadence.yml` update + +### Bootstrap batching (LOOP-WP-0003) + +Hourly registry hygiene uses **round-robin** (3 repos/hour), not full-fleet scan. + +## Consequences + +- activity-core definitions ship with `enabled: false` until bootstrap smoke passes +- Initial hourly crons are **time-boxed**; regulator must schedule first promotion review +- Supplier ADR-005 weekly defaults are overridden by engagement `cadence.yml` during bootstrap + +## Related + +- `INTENT.md` § Cadence Ramp Policy +- `LOOP-WP-0004-loop-regulator.md` +- `docs/decisions/DEC-002-event-vs-sweep-quality.md` \ No newline at end of file diff --git a/docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md b/docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md new file mode 100644 index 0000000..af12300 --- /dev/null +++ b/docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md @@ -0,0 +1,85 @@ +--- +id: ADR-004 +title: Repo Rotation on Diminishing Returns +status: accepted +date: "2026-06-18" +decided_by: Bernd Worsch +implementation: deferred +--- + +# ADR-004 — Repo Rotation on Diminishing Returns + +## Status + +Accepted (design). Implementation deferred to LOOP-WP-0004 T09 after bootstrap +metrics baseline exists. + +## Context + +The pilot roster (DEC-001, option A) starts with three custodian repos. Fleet +expansion will add more repos over time. Running optimization indefinitely on a +repo that has stopped yielding measurable improvement wastes agent sessions and +delays under-served repos. + +Operator direction (2026-06-18): introduce a method to **detect diminishing +returns** and **switch optimization focus to another repo**. + +## Decision + +The loop regulator (LOOP-WP-0004) shall maintain a **rotation policy** alongside +cadence ramp (ADR-003). When a repo is classified as **saturated**, optimization +agent runs deprioritize or pause for that repo; the next **queued** repo receives +focus. + +### Saturation signals (evaluate per repo, per agent) + +A repo is candidate-saturated when **all** of the following hold over a rolling +window (default: 14 cycles at current cadence): + +| Signal | Threshold | +|--------|-----------| +| Quality plateau | `avg_quality` delta < 0.02 vs prior window | +| Success stable | `success_rate` ≥ 0.85 | +| Optimizer stall | `recommendations.jsonl` has no new actionable items in window | +| Marginal gain | Coach/optimization sessions produce no merged PRs or hub progress events | + +Configurable in `loops/regulator/rotation-policy.yml`. Regulator may recommend +saturation when **3 of 4** signals fire (default). + +### Rotation actions + +1. Set `loops/kaizen-stack/roster.yaml` entry `status: saturated` with `saturated_at` +2. Disable `optimization` in target repo `.kaizen/schedule.yml` (or set `enabled: false`) +3. Promote next repo from `expansion_queue` to `active` +4. Record state-hub decision + progress event +5. optimization agent session on **new** repo gets elevated priority + +Rotation is **recommendation-first** during bootstrap; regulator proposes, +human commits roster change. Automated rotation after LOOP-WP-0004 T09 proves +signal accuracy (target: daily phase). + +### Expansion queue + +`loops/kaizen-stack/roster.yaml` carries: + +```yaml +active: [...] # currently receiving optimization focus +expansion_queue: # ordered candidates after pilot +saturated: [...] # repos paused pending new signals or manual revisit +``` + +Revisit saturated repos monthly or on external trigger (CI regression, new workstream). + +## Consequences + +- Optimization effort flows to highest marginal-value repos +- LOOP-WP-0004 health model gains `marginal_gain` and `saturation_score` fields +- KAIZEN-WP-0008 may add `metrics rotation-signals` CLI helper (supplier) +- activity-core definitions must respect roster `status` in resolver filter (future) + +## Related + +- DEC-001 (pilot roster) +- ADR-003 (cadence ramp) +- LOOP-WP-0004 T09 +- `loops/regulator/rotation-policy.yml` \ No newline at end of file diff --git a/docs/decisions/DEC-001-pilot-roster-scope.md b/docs/decisions/DEC-001-pilot-roster-scope.md new file mode 100644 index 0000000..8b56817 --- /dev/null +++ b/docs/decisions/DEC-001-pilot-roster-scope.md @@ -0,0 +1,72 @@ +# DEC-001 — Pilot Roster Scope + +**Status:** accepted +**Date:** 2026-06-18 +**Owner:** Bernd (Coulomb operator) +**Blocks:** LOOP-WP-0001 T02, LOOP-WP-0003 T05 + +--- + +## Question + +Which repositories should participate in the **bootstrap-phase** self-improvement +loops before fleet expansion? + +## Context + +LOOP-WP-0001 proposes three custodian-domain pilots: + +- `kaizen-agentic` — supplier dogfood +- `the-custodian` — state-hub / coordination operator +- `activity-core` — scheduler owner + +The full Coulomb fleet has **57 state-hub repos** across 12 domains. Hourly +bootstrap on all repos would create unsustainable task volume. + +## Options + +### A — Custodian pilot only (recommended default) + +**3 repos:** `kaizen-agentic`, `the-custodian`, `activity-core` + +| Pros | Cons | +|------|------| +| All loop infrastructure owners in one batch | Does not exercise coulomb_social domain repos | +| Minimal noise; fast E2E proof | Fleet improvement delayed | +| Aligns with supplier WP-0006 pilot design | | + +### B — Custodian pilot + one coulomb_social repo + +**4 repos:** option A + `vergabe-teilnahme` + +| Pros | Cons | +|------|------| +| Validates engagement under customer domain | Mixed stack (Django app vs infra repos) | +| Product-facing dogfood | Extra setup for app-specific agents | + +### C — Domain-stratified mini-pilot (5 repos) + +**5 repos:** option A + `reuse-surface` + `vergabe-teilnahme` + +| Pros | Cons | +|------|------| +| Covers helix_forge registry + coulomb_social product | More hourly tasks; slower bootstrap exit | +| Exercises LOOP-WP-0003 registry hygiene early | | + +## Recommendation + +**Option A** for bootstrap; expand via LOOP-WP-0003 domain rollout after +LOOP-WP-0004 approves first promotion to daily. + +## Decision record + +| Field | Value | +|-------|-------| +| Chosen option | **A** — custodian pilot only (3 repos) | +| Decided by | Bernd Worsch | +| Decided at | 2026-06-18 | +| Notes | Fleet expansion via expansion_queue; rotation per ADR-004 when diminishing returns detected | + +## On approval + +Update `loops/kaizen-stack/roster.yaml` and close LOOP-WP-0001 T02. \ No newline at end of file diff --git a/docs/decisions/DEC-002-event-vs-sweep-quality.md b/docs/decisions/DEC-002-event-vs-sweep-quality.md new file mode 100644 index 0000000..a382b64 --- /dev/null +++ b/docs/decisions/DEC-002-event-vs-sweep-quality.md @@ -0,0 +1,67 @@ +# DEC-002 — Quality Escalation Trigger Strategy + +**Status:** accepted +**Date:** 2026-06-18 +**Owner:** Bernd +**Blocks:** LOOP-WP-0002 T03, T05, T07 + +--- + +## Question + +Should reactive quality escalation (LOOP-WP-0002) use **event-driven** triggers, +**hourly sweep** polling, or **both**? + +## Context + +Supplier draft `low-success-rate-review` expects NATS event `kaizen.metrics.recorded`. +That emitter does not exist in `kaizen-agentic metrics record` today (KAIZEN-WP-0008 T03). + +LOOP-WP-0002 proposes hourly sweep as bootstrap scaffolding until events ship. + +## Options + +### A — Sweep first, events later (recommended) + +1. Bootstrap: hourly `discover_kaizen_projects` sweep only +2. After KAIZEN-WP-0008 ships emitter: enable event definition; demote sweep to daily backup + +| Pros | Cons | +|------|------| +| Unblocks LOOP-WP-0002 without supplier code | Higher hub load during bootstrap | +| Proven pattern (activity-core shell resolvers) | Latency up to 1 hour | + +### B — Block until event emitter ships + +Wait for `metrics record --emit-event` before any LOOP-WP-0002 automation. + +| Pros | Cons | +|------|------| +| Clean architecture | Delays reactive loop entirely | +| No duplicate triggers | LOOP-WP-0004 lacks quality signal data | + +### C — Dual from day one + +Run hourly sweep **and** events when available; dedupe by `(repo, agent, hour)`. + +| Pros | Cons | +|------|------| +| Fastest signal once events land | Duplicate task risk; complex dedupe | +| | Harder to tune false-positive rate | + +## Recommendation + +**Option A.** Document emitter contract now (LOOP-WP-0002 T03); implement in +KAIZEN-WP-0008; keep sweep as documented backup per ADR-003 stabilize phase. + +## Decision record + +| Field | Value | +|-------|-------| +| Chosen option | **A** — sweep first, events later | +| Decided by | Bernd Worsch | +| Decided at | 2026-06-18 | + +## On approval + +Update `loops/quality-escalation/thresholds.yml` trigger section. \ No newline at end of file diff --git a/docs/decisions/DEC-003-activity-definition-ownership.md b/docs/decisions/DEC-003-activity-definition-ownership.md new file mode 100644 index 0000000..f9c6875 --- /dev/null +++ b/docs/decisions/DEC-003-activity-definition-ownership.md @@ -0,0 +1,66 @@ +# DEC-003 — ActivityDefinition Copy vs Reference + +**Status:** accepted +**Date:** 2026-06-18 +**Owner:** Bernd +**Blocks:** LOOP-WP-0001 T04, activity-core sync workflow + +--- + +## Question + +How should coulomb-loop ActivityDefinitions relate to kaizen-agentic supplier templates? + +## Context + +ADR-002 assigns ActivityDefinition **copies** to the customer repo. activity-core +syncs from its own catalog path (ACT-ADR-002). Two sync models are possible. + +## Options + +### A — Customer-owned copies (recommended) + +Copy supplier templates into `coulomb-loop/activity-definitions/`. activity-core +syncs from coulomb-loop path (or vendored subtree). Customer edits cron, labels, +roster params without supplier release. + +| Pros | Cons | +|------|------| +| Coulomb controls cadence ramp (hourly bootstrap) | Drift from supplier templates | +| Matches ADR-002 | Manual merge when supplier updates templates | + +### B — Supplier catalog only + +Reference supplier repo path; activity-core syncs `kaizen-agentic/docs/integrations/activity-definitions/`. + +| Pros | Cons | +|------|------| +| Single source of truth | Hourly bootstrap crons don't match supplier weekly defaults | +| Less copy maintenance | Customer cannot tune without supplier PR | + +### C — Hybrid manifest + +`coulomb-loop/activity-definitions/manifest.yaml` lists supplier source + local overrides (cron, enabled, labels). activity-core merge tool applies patches. + +| Pros | Cons | +|------|------| +| Drift-aware automation | Requires new activity-core or coulomb-loop tooling | +| Best long-term for multiple customers | Not available today | + +## Recommendation + +**Option A** for bootstrap (minimal tooling). Track **Option C** in KAIZEN-WP-0008 +as supplier playbook enhancement for second customer. + +## Decision record + +| Field | Value | +|-------|-------| +| Chosen option | **A** — customer-owned copies | +| Decided by | Bernd Worsch | +| Decided at | 2026-06-18 | +| Notes | Option C hybrid manifest tracked in KAIZEN-WP-0008 T08 | + +## On approval + +Proceed with LOOP-WP-0001 T04 copy step; document merge procedure in `loops/kaizen-stack/supplier-notes.md`. \ No newline at end of file diff --git a/docs/decisions/DEC-004-supplier-playbook-priority.md b/docs/decisions/DEC-004-supplier-playbook-priority.md new file mode 100644 index 0000000..83d5137 --- /dev/null +++ b/docs/decisions/DEC-004-supplier-playbook-priority.md @@ -0,0 +1,70 @@ +# DEC-004 — Supplier Playbook Delivery Priority + +**Status:** accepted +**Date:** 2026-06-18 +**Owner:** Bernd +**Blocks:** KAIZEN-WP-0008 sequencing + +--- + +## Question + +What should kaizen-agentic (supplier) prioritize **before** vs **after** first +hourly loop smoke test? + +## Context + +KAIZEN-WP-0008 bundles supplier obligations: customer-repo template, event emitter, +engagement CLI, playbook. Full delivery before smoke test delays customer value; +minimal delivery risks rework. + +## Options + +### A — Smoke-first, playbook parallel (recommended) + +**Before smoke test (KAIZEN-WP-0008 Part 1):** + +- Document customer-repo layout (reference: coulomb-loop) +- Support pilot `schedule init` on target repos (docs only; CLI exists) + +**After smoke test (KAIZEN-WP-0008 Part 2):** + +- `metrics record --emit-event` +- `schedule init --engagement` scaffold +- Playbook v1 in supplier repo + +| Pros | Cons | +|------|------| +| Fastest proof of LOOP-WP-0001 | Playbook incomplete until smoke passes | +| Playbook informed by real friction | | + +### B — Playbook-first + +Complete customer-repo template and engagement CLI before any activity-core enable. + +| Pros | Cons | +|------|------| +| Second customer ready sooner | Delays all loop automation | +| | Speculative without smoke data | + +### C — Automation-first + +Prioritize activity-core resolver + event emitter; defer playbook to LOOP-WP-0004 T07. + +| Pros | Cons | +|------|------| +| Unblocks LOOP-WP-0002 events | Customer repo conventions undocumented | +| Cross-repo focus | Harder for humans to operate engagement | + +## Recommendation + +**Option A.** Record friction in `loops/*/supplier-notes.md` during smoke test; +feed into playbook draft at LOOP-WP-0004 T07 / KAIZEN-WP-0008 Part 2. + +## Decision record + +| Field | Value | +|-------|-------| +| Chosen option | **A** — smoke-first, playbook parallel | +| Decided by | Bernd Worsch | +| Decided at | 2026-06-18 | \ No newline at end of file diff --git a/docs/integrations/activity-core-handoff.md b/docs/integrations/activity-core-handoff.md new file mode 100644 index 0000000..16ac604 --- /dev/null +++ b/docs/integrations/activity-core-handoff.md @@ -0,0 +1,35 @@ +# activity-core Handoff — coulomb-loop Bootstrap + +**Customer:** coulomb-loop +**Status:** ready for activity-core PR/issue + +## Prerequisites (done) + +- [x] Pilot roster: `loops/kaizen-stack/roster.yaml` +- [x] `.kaizen/schedule.yml` on kaizen-agentic, the-custodian, activity-core +- [x] ActivityDefinition copies in `coulomb-loop/activity-definitions/` (all `enabled: false`) + +## activity-core checklist + +- [ ] Implement or verify `discover_kaizen_scheduled_repos` with `roster` param +- [ ] Extend `discover_kaizen_projects` with `roster` filter for pilot scope +- [ ] Copy definitions from `coulomb-loop/activity-definitions/` to catalog +- [ ] `make sync-activity-definitions` +- [ ] Dry-run hourly chain (no `enabled: true` yet) +- [ ] Enable `hourly-metrics-optimize` first after dry-run pass + +## Smoke commands (pilot) + +```bash +kaizen-agentic schedule validate --target /home/worsch/kaizen-agentic +kaizen-agentic schedule prepare coach --target /home/worsch/kaizen-agentic +kaizen-agentic metrics optimize --target /home/worsch/kaizen-agentic +``` + +## Definition enable order + +1. `hourly-metrics-optimize` +2. `hourly-coach-orientation` +3. `hourly-optimization-review` +4. `hourly-metrics-health-sweep` +5. `low-success-rate-review` (after KAIZEN-WP-0008 T03) \ No newline at end of file diff --git a/history/2026-06-18-initial-codebase-assessment.md b/history/2026-06-18-initial-codebase-assessment.md new file mode 100644 index 0000000..e85dbfa --- /dev/null +++ b/history/2026-06-18-initial-codebase-assessment.md @@ -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` \ No newline at end of file diff --git a/loops/kaizen-stack/bootstrap-log.md b/loops/kaizen-stack/bootstrap-log.md new file mode 100644 index 0000000..f3a7010 --- /dev/null +++ b/loops/kaizen-stack/bootstrap-log.md @@ -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. \ No newline at end of file diff --git a/loops/kaizen-stack/cadence.yml b/loops/kaizen-stack/cadence.yml new file mode 100644 index 0000000..55a1097 --- /dev/null +++ b/loops/kaizen-stack/cadence.yml @@ -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) \ No newline at end of file diff --git a/loops/kaizen-stack/roster.yaml b/loops/kaizen-stack/roster.yaml new file mode 100644 index 0000000..2ab7e02 --- /dev/null +++ b/loops/kaizen-stack/roster.yaml @@ -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: [] \ No newline at end of file diff --git a/loops/kaizen-stack/supplier-notes.md b/loops/kaizen-stack/supplier-notes.md new file mode 100644 index 0000000..d98e4d1 --- /dev/null +++ b/loops/kaizen-stack/supplier-notes.md @@ -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` | \ No newline at end of file diff --git a/loops/quality-escalation/cadence.yml b/loops/quality-escalation/cadence.yml new file mode 100644 index 0000000..a3ac9ed --- /dev/null +++ b/loops/quality-escalation/cadence.yml @@ -0,0 +1,4 @@ +loop: quality-escalation +phase: bootstrap +cron: "45 * * * *" +regulator_approval: pending \ No newline at end of file diff --git a/loops/quality-escalation/thresholds.yml b/loops/quality-escalation/thresholds.yml new file mode 100644 index 0000000..fb5ccbf --- /dev/null +++ b/loops/quality-escalation/thresholds.yml @@ -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 * * *" \ No newline at end of file diff --git a/loops/regulator/health-model.md b/loops/regulator/health-model.md new file mode 100644 index 0000000..553aa0c --- /dev/null +++ b/loops/regulator/health-model.md @@ -0,0 +1,23 @@ +# Loop Health Model + +Per LOOP-WP-0004 T01. Metrics appended to `loops//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//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. \ No newline at end of file diff --git a/loops/regulator/rotation-policy.yml b/loops/regulator/rotation-policy.yml new file mode 100644 index 0000000..a94e5d5 --- /dev/null +++ b/loops/regulator/rotation-policy.yml @@ -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 \ No newline at end of file diff --git a/loops/regulator/state-machine.md b/loops/regulator/state-machine.md new file mode 100644 index 0000000..b27632f --- /dev/null +++ b/loops/regulator/state-machine.md @@ -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. \ No newline at end of file diff --git a/workplans/LOOP-WP-0000-engagement-bootstrap.md b/workplans/LOOP-WP-0000-engagement-bootstrap.md new file mode 100644 index 0000000..addf745 --- /dev/null +++ b/workplans/LOOP-WP-0000-engagement-bootstrap.md @@ -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 \ No newline at end of file diff --git a/workplans/LOOP-WP-0001-kaizen-improvement-stack.md b/workplans/LOOP-WP-0001-kaizen-improvement-stack.md new file mode 100644 index 0000000..0c759d0 --- /dev/null +++ b/workplans/LOOP-WP-0001-kaizen-improvement-stack.md @@ -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 --quality <0-1> +kaizen-agentic metrics record optimization --success --time --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 \ No newline at end of file diff --git a/workplans/LOOP-WP-0002-reactive-quality-escalation.md b/workplans/LOOP-WP-0002-reactive-quality-escalation.md new file mode 100644 index 0000000..9aff6d2 --- /dev/null +++ b/workplans/LOOP-WP-0002-reactive-quality-escalation.md @@ -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. \ No newline at end of file diff --git a/workplans/LOOP-WP-0003-registry-orientation-hygiene.md b/workplans/LOOP-WP-0003-registry-orientation-hygiene.md new file mode 100644 index 0000000..1f912a1 --- /dev/null +++ b/workplans/LOOP-WP-0003-registry-orientation-hygiene.md @@ -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 +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. \ No newline at end of file diff --git a/workplans/LOOP-WP-0004-loop-regulator.md b/workplans/LOOP-WP-0004-loop-regulator.md new file mode 100644 index 0000000..efce520 --- /dev/null +++ b/workplans/LOOP-WP-0004-loop-regulator.md @@ -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//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//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//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 \ No newline at end of file