generated from coulomb/repo-seed
Bootstrap coulomb-loop engagement: governance, loops, and activity definitions.
Register with state-hub, accept DEC-001–004 and ADR-004 rotation policy, scaffold pilot roster, hourly ActivityDefinition copies, and bootstrap log after schedule init on three custodian pilot repos.
This commit is contained in:
41
docs/adr/ADR-001-workplan-prefix.md
Normal file
41
docs/adr/ADR-001-workplan-prefix.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
id: ADR-001
|
||||
title: Workplan ID Prefix Convention
|
||||
status: accepted
|
||||
date: "2026-06-18"
|
||||
---
|
||||
|
||||
# ADR-001 — Workplan ID Prefix Convention
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
`register_project.sh` derives the workplan prefix from the repo slug first token:
|
||||
`coulomb-loop` → `COULOMB-WP`. The engagement workplans were authored as
|
||||
`LOOP-WP-0001` through `LOOP-WP-0004` before registration, and state-hub
|
||||
`fix-consistency` indexed them under those IDs.
|
||||
|
||||
Renaming to `COULOMB-WP` would churn 4 workstreams, 30 tasks, and cross-references
|
||||
in INTENT.md with no functional benefit.
|
||||
|
||||
## Decision
|
||||
|
||||
Adopt **`LOOP-WP`** as the canonical workplan prefix for `coulomb-loop`.
|
||||
|
||||
- File pattern: `workplans/LOOP-WP-NNNN-<slug>.md`
|
||||
- Task IDs: `LOOP-WP-NNNN-Tnn`
|
||||
- Override the auto-derived `COULOMB-WP` in `.claude/rules/workplan-convention.md`
|
||||
|
||||
## Consequences
|
||||
|
||||
- Consistent with engagement naming ("loop" operations)
|
||||
- state-hub workstream slugs remain `loop-wp-0001-*`
|
||||
- Future coulomb_social repos (e.g. product apps) should use their own prefix
|
||||
|
||||
## Related
|
||||
|
||||
- state-hub ADR-001 (workplans as repo artefacts)
|
||||
- `docs/decisions/DEC-001-pilot-roster-scope.md` (separate concern)
|
||||
62
docs/adr/ADR-002-customer-supplier-boundary.md
Normal file
62
docs/adr/ADR-002-customer-supplier-boundary.md
Normal file
@@ -0,0 +1,62 @@
|
||||
---
|
||||
id: ADR-002
|
||||
title: Customer–Supplier Engagement Boundary
|
||||
status: accepted
|
||||
date: "2026-06-18"
|
||||
---
|
||||
|
||||
# ADR-002 — Customer–Supplier Engagement Boundary
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Coulomb hired kaizen-agentic as a **supplier** of agents and improvement
|
||||
expertise. Agents must improve Coulomb's fleet without becoming part of Coulomb's
|
||||
application codebases or the supplier's product repo.
|
||||
|
||||
## Decision
|
||||
|
||||
### coulomb-loop (customer) owns
|
||||
|
||||
- Engagement INTENT, SCOPE, workplans, decisions
|
||||
- Loop rosters (`loops/*/roster.yaml`)
|
||||
- ActivityDefinition **copies** tuned for Coulomb cadence
|
||||
- Loop health records and cadence state (`loops/*/cadence.yml`, `health.jsonl`)
|
||||
- state-hub progress events for the engagement
|
||||
|
||||
### kaizen-agentic (supplier) owns
|
||||
|
||||
- Agent markdown definitions (`agents/agent-*.md`)
|
||||
- CLI (`schedule`, `metrics`, `memory`, `validate`)
|
||||
- ADRs for memory, metrics, scheduled execution (ADR-002–005)
|
||||
- ActivityDefinition **reference** templates
|
||||
- Customer-repo bootstrap playbook (KAIZEN-WP-0008)
|
||||
|
||||
### Target repos (fleet) hold runtime state
|
||||
|
||||
- `.kaizen/schedule.yml` — opt-in per repo
|
||||
- `.kaizen/agents/<name>/memory.md` — project-scoped agent memory
|
||||
- `.kaizen/metrics/<name>/` — execution metrics
|
||||
|
||||
### Shared operators (not owned by either repo)
|
||||
|
||||
| System | Role |
|
||||
|--------|------|
|
||||
| activity-core | Cron/event → task creation |
|
||||
| state-hub | Fleet roster, workstream index |
|
||||
| reuse-surface | Capability registry CLI and federation |
|
||||
|
||||
## Consequences
|
||||
|
||||
- No agent definitions are copied into `coulomb-loop`
|
||||
- No scheduling runtime code in `coulomb-loop`
|
||||
- Supplier improvements flow back via KAIZEN-WP-0008, not by merging into coulomb-loop
|
||||
- Customer may fork ActivityDefinitions without waiting for supplier release
|
||||
|
||||
## Related
|
||||
|
||||
- `INTENT.md`
|
||||
- `docs/adr/ADR-003-cadence-ramp-policy.md`
|
||||
57
docs/adr/ADR-003-cadence-ramp-policy.md
Normal file
57
docs/adr/ADR-003-cadence-ramp-policy.md
Normal file
@@ -0,0 +1,57 @@
|
||||
---
|
||||
id: ADR-003
|
||||
title: Loop Cadence Ramp Policy
|
||||
status: accepted
|
||||
date: "2026-06-18"
|
||||
---
|
||||
|
||||
# ADR-003 — Loop Cadence Ramp Policy
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
Self-improvement loops need fast feedback while mechanics are unproven, but
|
||||
hourly fleet-wide execution creates task noise and operator fatigue. A explicit
|
||||
ramp policy is required before activity-core definitions are enabled.
|
||||
|
||||
## Decision
|
||||
|
||||
All first-order loops (LOOP-WP-0001–0003) follow a **three-phase cadence ramp**
|
||||
governed by the second-order loop (LOOP-WP-0004):
|
||||
|
||||
| Phase | Cron | Entry | Exit (promote) |
|
||||
|-------|------|-------|----------------|
|
||||
| **bootstrap** | hourly | loop workplan `active` | 3 consecutive successful E2E cycles; `manual_rescues == 0` |
|
||||
| **stabilize** | daily | bootstrap exit + regulator approval | 14 daily cycles; `false_positive_rate < 0.2` |
|
||||
| **operate** | weekly | stabilize exit + regulator approval | — (demote on sustained noise) |
|
||||
|
||||
### Demotion triggers (any one)
|
||||
|
||||
- `false_positive_rate > 0.4` over 3 cycles
|
||||
- `manual_rescues >= 2` in 24 hours
|
||||
- Operator override (documented in state-hub decision)
|
||||
|
||||
### Authority
|
||||
|
||||
- **Promotions:** LOOP-WP-0004 regulator session recommends; human commits `cadence.yml`
|
||||
- **Demotions:** regulator may create urgent task; human commits within 24h
|
||||
- **No autonomous cron changes** without a committed `cadence.yml` update
|
||||
|
||||
### Bootstrap batching (LOOP-WP-0003)
|
||||
|
||||
Hourly registry hygiene uses **round-robin** (3 repos/hour), not full-fleet scan.
|
||||
|
||||
## Consequences
|
||||
|
||||
- activity-core definitions ship with `enabled: false` until bootstrap smoke passes
|
||||
- Initial hourly crons are **time-boxed**; regulator must schedule first promotion review
|
||||
- Supplier ADR-005 weekly defaults are overridden by engagement `cadence.yml` during bootstrap
|
||||
|
||||
## Related
|
||||
|
||||
- `INTENT.md` § Cadence Ramp Policy
|
||||
- `LOOP-WP-0004-loop-regulator.md`
|
||||
- `docs/decisions/DEC-002-event-vs-sweep-quality.md`
|
||||
85
docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md
Normal file
85
docs/adr/ADR-004-repo-rotation-on-diminishing-returns.md
Normal file
@@ -0,0 +1,85 @@
|
||||
---
|
||||
id: ADR-004
|
||||
title: Repo Rotation on Diminishing Returns
|
||||
status: accepted
|
||||
date: "2026-06-18"
|
||||
decided_by: Bernd Worsch
|
||||
implementation: deferred
|
||||
---
|
||||
|
||||
# ADR-004 — Repo Rotation on Diminishing Returns
|
||||
|
||||
## Status
|
||||
|
||||
Accepted (design). Implementation deferred to LOOP-WP-0004 T09 after bootstrap
|
||||
metrics baseline exists.
|
||||
|
||||
## Context
|
||||
|
||||
The pilot roster (DEC-001, option A) starts with three custodian repos. Fleet
|
||||
expansion will add more repos over time. Running optimization indefinitely on a
|
||||
repo that has stopped yielding measurable improvement wastes agent sessions and
|
||||
delays under-served repos.
|
||||
|
||||
Operator direction (2026-06-18): introduce a method to **detect diminishing
|
||||
returns** and **switch optimization focus to another repo**.
|
||||
|
||||
## Decision
|
||||
|
||||
The loop regulator (LOOP-WP-0004) shall maintain a **rotation policy** alongside
|
||||
cadence ramp (ADR-003). When a repo is classified as **saturated**, optimization
|
||||
agent runs deprioritize or pause for that repo; the next **queued** repo receives
|
||||
focus.
|
||||
|
||||
### Saturation signals (evaluate per repo, per agent)
|
||||
|
||||
A repo is candidate-saturated when **all** of the following hold over a rolling
|
||||
window (default: 14 cycles at current cadence):
|
||||
|
||||
| Signal | Threshold |
|
||||
|--------|-----------|
|
||||
| Quality plateau | `avg_quality` delta < 0.02 vs prior window |
|
||||
| Success stable | `success_rate` ≥ 0.85 |
|
||||
| Optimizer stall | `recommendations.jsonl` has no new actionable items in window |
|
||||
| Marginal gain | Coach/optimization sessions produce no merged PRs or hub progress events |
|
||||
|
||||
Configurable in `loops/regulator/rotation-policy.yml`. Regulator may recommend
|
||||
saturation when **3 of 4** signals fire (default).
|
||||
|
||||
### Rotation actions
|
||||
|
||||
1. Set `loops/kaizen-stack/roster.yaml` entry `status: saturated` with `saturated_at`
|
||||
2. Disable `optimization` in target repo `.kaizen/schedule.yml` (or set `enabled: false`)
|
||||
3. Promote next repo from `expansion_queue` to `active`
|
||||
4. Record state-hub decision + progress event
|
||||
5. optimization agent session on **new** repo gets elevated priority
|
||||
|
||||
Rotation is **recommendation-first** during bootstrap; regulator proposes,
|
||||
human commits roster change. Automated rotation after LOOP-WP-0004 T09 proves
|
||||
signal accuracy (target: daily phase).
|
||||
|
||||
### Expansion queue
|
||||
|
||||
`loops/kaizen-stack/roster.yaml` carries:
|
||||
|
||||
```yaml
|
||||
active: [...] # currently receiving optimization focus
|
||||
expansion_queue: # ordered candidates after pilot
|
||||
saturated: [...] # repos paused pending new signals or manual revisit
|
||||
```
|
||||
|
||||
Revisit saturated repos monthly or on external trigger (CI regression, new workstream).
|
||||
|
||||
## Consequences
|
||||
|
||||
- Optimization effort flows to highest marginal-value repos
|
||||
- LOOP-WP-0004 health model gains `marginal_gain` and `saturation_score` fields
|
||||
- KAIZEN-WP-0008 may add `metrics rotation-signals` CLI helper (supplier)
|
||||
- activity-core definitions must respect roster `status` in resolver filter (future)
|
||||
|
||||
## Related
|
||||
|
||||
- DEC-001 (pilot roster)
|
||||
- ADR-003 (cadence ramp)
|
||||
- LOOP-WP-0004 T09
|
||||
- `loops/regulator/rotation-policy.yml`
|
||||
Reference in New Issue
Block a user