feat: complete KAIZEN-WP-0008 customer engagement supplier deliverables

Add repo layout doc, ADR-006 convention, playbook v1 with supplier-notes, override manifest design, and wiki integration. Mark workplan done (10/10).
2026-06-18 11:02:09 +02:00
parent 4a8f842a37
commit dda49cd821
7 changed files with 280 additions and 36 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  `pip install 'kaizen-agentic[events]'`)
 - **`schedule init --engagement`** — bootstrap presets for customer engagements
  (`--bootstrap-cadence hourly|daily|weekly`)
+- **ADR-006** — customer engagement convention (supplier/customer split, playbook)
+- **Playbook v1** — `docs/integrations/customer-engagement-playbook.md`,
+  `customer-engagement-repo-layout.md`, override manifest design
 - **Event contract** — `docs/integrations/kaizen-metrics-recorded-event.md`
 - **Engagement handoff** — `docs/integrations/activity-core-handoff-engagement.md`

--- a/docs/adr/ADR-006-customer-engagement-convention.md
+++ b/docs/adr/ADR-006-customer-engagement-convention.md
@@ -0,0 +1,74 @@
+# ADR-006: Customer Engagement Convention
+
+**Status:** accepted
+**Date:** 2026-06-18
+**Deciders:** kaizen-agentic maintainers (supplier)
+**Customer reference:** coulomb-loop / LOOP-WP-0000
+
+## Context
+
+Coulomb's `coulomb-loop` engagement introduced a **customer/supplier split**:
+the customer repo holds contracts and operations; `kaizen-agentic` ships agents
+and CLI; target repos hold `.kaizen/` runtime state. We need a durable convention
+so the second customer engagement reuses ≤50% of coulomb-loop setup effort.
+
+## Decision
+
+### 1. Repo roles
+
+| Role | Owns |
+|------|------|
+| **Customer engagement repo** | INTENT, workplans, ADRs, rosters, ActivityDefinition copies, loop health |
+| **Supplier (kaizen-agentic)** | Agent prompts, CLI, integration specs, playbook, supplier workplans |
+| **Target repos** | `.kaizen/schedule.yml`, `agents/`, `metrics/`, memory |
+| **activity-core** | Cron/event orchestration, resolvers, task creation |
+
+### 2. `.kaizen/` placement
+
+Project-scoped kaizen state **never** lives in the customer engagement repo.
+It lives only in repos where agents execute (fleet pilots).
+
+### 3. Supplier CLI engagement mode
+
+```bash
+kaizen-agentic schedule init --engagement <customer-slug> \
+  --agents coach,optimization --bootstrap-cadence hourly
+```
+
+Writes bootstrap schedule with engagement comment and hourly cron presets.
+See [customer-engagement-playbook.md](../integrations/customer-engagement-playbook.md).
+
+### 4. Event emission (opt-in)
+
+```bash
+kaizen-agentic metrics record <agent> --success --time <s> --quality <0-1> --emit-event
+```
+
+Publishes `kaizen.metrics.recorded` for activity-core event definitions.
+Default off for backward compatibility.
+
+### 5. Playbook lifecycle
+
+1. **Bootstrap** — customer LOOP-WP-0000; supplier KAIZEN-WP-0008 Part 1
+2. **Smoke** — hourly E2E on pilot roster (LOOP-WP-0001)
+3. **Automate** — emit-event, activity-core definitions enabled incrementally
+4. **Generalize** — supplier-notes → playbook v1; ADR-006 + layout docs
+5. **Second customer** — copy layout; swap roster and definitions
+
+### 6. ActivityDefinition ownership
+
+Bootstrap uses **customer-owned copies** (coulomb DEC-003 option A).
+Hybrid override manifest (option C) is design-only — see
+[activity-definition-override-manifest.md](../integrations/activity-definition-override-manifest.md).
+
+## Consequences
+
+- New engagements follow [customer-engagement-repo-layout.md](../integrations/customer-engagement-repo-layout.md)
+- Supplier friction is logged in customer `loops/*/supplier-notes.md` and absorbed into playbook
+- activity-core handoff requirements are documented per engagement wave
+
+## Related
+
+- coulomb-loop `docs/adr/ADR-002-customer-supplier-boundary.md`
+- [ADR-005](ADR-005-scheduled-agent-execution.md) — schedule contract
+- [KAIZEN-WP-0008](../../workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md)
--- a/docs/integrations/activity-definition-override-manifest.md
+++ b/docs/integrations/activity-definition-override-manifest.md
@@ -0,0 +1,72 @@
+# ActivityDefinition Override Manifest (design)
+
+**Status:** design-only (DEC-003 option C future)
+**Implements:** KAIZEN-WP-0008 T08
+**Runtime:** none in v1 — customer-owned copies (option A) during bootstrap
+
+## Problem
+
+Customer repos copy supplier ActivityDefinitions and tune cron, labels, and
+`enabled` flags. When supplier templates change, manual merge is error-prone.
+A manifest declares **source + overrides** without duplicating full definition bodies.
+
+## Proposed file
+
+`activity-definitions/manifest.yaml` in the customer repo:
+
+```yaml
+version: "1"
+supplier_repo: kaizen-agentic
+supplier_path: docs/integrations/activity-definitions
+engagement: coulomb-loop
+
+definitions:
+  - supplier_id: kaizen-weekly-coach-orientation
+    customer_id: coulomb-hourly-coach-orientation
+    source: ../../kaizen-agentic/docs/integrations/activity-definitions/weekly-coach-orientation.md
+    overrides:
+      id: coulomb-hourly-coach-orientation
+      name: Hourly Kaizen Coach Orientation (coulomb-loop bootstrap)
+      owner: coulomb-loop
+      governance: coulomb_social
+      enabled: true
+      trigger:
+        cron_expression: "15 * * * *"
+      context_sources:
+        - params:
+            roster: /home/worsch/coulomb-loop/loops/kaizen-stack/roster.yaml
+            cadence: daily
+
+  - supplier_id: kaizen-low-success-rate-review
+    customer_id: coulomb-low-success-rate-review
+    overrides:
+      enabled: false
+      owner: coulomb-loop
+```
+
+## Merge rules (future tooling)
+
+1. Parse supplier definition markdown (frontmatter + body)
+2. Deep-merge `overrides` (customer wins on conflict)
+3. Write customer copy to `activity-definitions/<customer_id>.md`
+4. `sync_activity_definitions` reads customer copies only (unchanged today)
+
+## Ownership
+
+| Layer | Owner |
+|-------|-------|
+| Manifest schema | kaizen-agentic (supplier ADR/extension) |
+| Manifest instance | customer repo |
+| Merge CLI | TBD — `coulomb-loop` or `activity-core` |
+| Sync runtime | activity-core (unchanged) |
+
+## Bootstrap path (today)
+
+Use **option A**: hand-copy definitions, edit cron/labels, track drift in
+`loops/kaizen-stack/supplier-notes.md`. Revisit manifest when a second customer
+engagement starts.
+
+## Related
+
+- coulomb-loop `docs/decisions/DEC-003-activity-definition-ownership.md`
+- [customer-engagement-playbook.md](customer-engagement-playbook.md)
--- a/docs/integrations/customer-engagement-playbook.md
+++ b/docs/integrations/customer-engagement-playbook.md
@@ -1,14 +1,16 @@
-# Customer Engagement Playbook (supplier)
+# Customer Engagement Playbook v1 (supplier)

-How kaizen-agentic supports a **customer engagement repo** (e.g. coulomb-loop)
-that orchestrates improvement loops across a pilot roster.
+How kaizen-agentic supports a **customer engagement repo** (reference:
+[coulomb-loop](https://gitea.example/coulomb/coulomb-loop)). Second engagements
+should copy [customer-engagement-repo-layout.md](customer-engagement-repo-layout.md)
+and complete the checklist in one session.

 ## Roles

 | Repo | Role |
 |------|------|
 | Customer (coulomb-loop) | Roster, ActivityDefinition copies, cadence policy, loop health |
-| Supplier (kaizen-agentic) | Agents, CLI, integration contracts |
+| Supplier (kaizen-agentic) | Agents, CLI, integration contracts, this playbook |
 | Target repos | `.kaizen/` state (schedule, memory, metrics) |
 | activity-core | Cron + event orchestration, task creation |

@@ -16,10 +18,12 @@ that orchestrates improvement loops across a pilot roster.

 ### 1. Customer repo

- Register engagement in state-hub
- Commit pilot roster (`loops/kaizen-stack/roster.yaml`)
- Copy ActivityDefinitions to `activity-definitions/`
- Enable definitions incrementally (metrics → coach → optimization)
+- Register engagement in state-hub (`register_project.sh`)
+- Write `INTENT.md`, `SCOPE.md`, LOOP-WP-0000–0004 workplans
+- Accept ADRs and DEC-* decisions; run `fix-consistency REPO=<customer>`
+- Copy ActivityDefinitions to `activity-definitions/` (DEC-003 option A)
+- Register reuse-surface capability (LOOP-WP-0000 T08)
+- Enable definitions incrementally: metrics → coach → optimization

 ### 2. Target repos (per pilot)

@@ -31,7 +35,7 @@ kaizen-agentic memory init coach
 kaizen-agentic memory init optimization
 ```

-Hourly bootstrap writes `cadence: daily` with hourly `cron` overrides — see
+Hourly bootstrap uses `cadence: daily` with hourly `cron` overrides — see
 [activity-core-handoff-engagement.md](activity-core-handoff-engagement.md) R2.

 ### 3. Session close (each agent run)
@@ -41,26 +45,40 @@ kaizen-agentic metrics record <agent> --success --time <s> --quality <0-1>
 kaizen-agentic metrics record <agent> --success --time <s> --quality <0-1> --emit-event
 ```

+Requires `pip install 'kaizen-agentic[events]'` for `--emit-event`.
+
 ### 4. activity-core

-Hand off [activity-core-handoff-engagement.md](activity-core-handoff-engagement.md)
-requirements before enabling event-driven quality escalation.
+- Sync definitions from customer `activity-definitions/`
+- Implement handoff requirements in [activity-core-handoff-engagement.md](activity-core-handoff-engagement.md)
+- Manual trigger smoke before enabling hourly crons
+
+## Lessons from coulomb-loop (supplier-notes absorbed)
+
+| Observation | Resolution (shipped) |
+|-------------|----------------------|
+| `schedule init` weekly defaults unsuitable for bootstrap | `schedule init --engagement --bootstrap-cadence hourly` (KAIZEN-WP-0008 T04) |
+| No metrics event for LOOP-WP-0002 | `metrics record --emit-event` (T03) |
+| `metrics optimize` with 0 records confusing during bootstrap | Expected — document in bootstrap log; optimizer needs ≥10 records for recommendations |
+| ActivityDefinition drift from supplier templates | Customer copies (DEC-003 A); hybrid manifest design for v2 ([override manifest](activity-definition-override-manifest.md)) |
+| Rotation saturation signals | Future: `metrics rotation-signals` CLI (ADR-004 follow-on) |

 ## Cadence promotion

-Customer regulator (LOOP-WP-0004) approves promotion. Re-init or patch schedules:
+Customer regulator (LOOP-WP-0004) approves promotion. Re-init schedules:

 ```bash
-# Stabilize phase
-kaizen-agentic schedule init --engagement <slug> \
-  --bootstrap-cadence daily --force
-
-# Operate phase
-kaizen-agentic schedule init --engagement <slug> \
-  --bootstrap-cadence weekly --force
+kaizen-agentic schedule init --engagement <slug> --bootstrap-cadence daily --force
+kaizen-agentic schedule init --engagement <slug> --bootstrap-cadence weekly --force
 ```

+## Reference implementation
+
+- Customer: [coulomb-loop INTENT](https://gitea.example/coulomb/coulomb-loop/blob/main/INTENT.md)
+- Supplier workplan: [KAIZEN-WP-0008](../../workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md)
+- Convention: [ADR-006](../adr/ADR-006-customer-engagement-convention.md)
+
 ## Related

- [KAIZEN-WP-0008](../../workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md)
- coulomb-loop `INTENT.md` and `workplans/LOOP-WP-*`
+- [INTEGRATION_PATTERNS.md](../INTEGRATION_PATTERNS.md) Pattern 2
+- [activity-core-handoff-wp0006.md](activity-core-handoff-wp0006.md)
--- a/docs/integrations/customer-engagement-repo-layout.md
+++ b/docs/integrations/customer-engagement-repo-layout.md
@@ -0,0 +1,65 @@
+# Customer Engagement Repo Layout
+
+Contract for a **customer engagement repository** that orchestrates kaizen
+improvement loops across a fleet roster. Reference implementation:
+[coulomb-loop](https://gitea.example/coulomb/coulomb-loop) (`coulomb_social` domain).
+
+Supplier agents and CLI live in `kaizen-agentic`. Runtime `.kaizen/` state lives
+in **target repos**, not in the customer repo.
+
+## Directory tree
+
+```
+customer-repo/
+├── INTENT.md                 # Engagement purpose, loop map, cadence policy summary
+├── SCOPE.md                  # In/out of scope; supplier boundaries
+├── CLAUDE.md                 # Session protocol + rules includes
+├── .claude/rules/            # repo-identity, architecture, workplan-convention, …
+├── workplans/
+│   ├── <PREFIX>-WP-0000-*    # Bootstrap (registration, ADRs, decisions)
+│   ├── <PREFIX>-WP-0001-*    # Primary improvement stack
+│   ├── <PREFIX>-WP-0002-*    # Reactive quality escalation
+│   ├── <PREFIX>-WP-0003-*    # Registry / orientation hygiene
+│   └── <PREFIX>-WP-0004-*    # Loop regulator (cadence promotion, rotation)
+├── docs/
+│   ├── adr/                  # Customer ADRs (boundary, cadence, ownership)
+│   ├── decisions/            # DEC-* proposals awaiting operator acceptance
+│   └── integrations/         # activity-core handoff, event payloads
+├── history/                  # Assessments, milestone snapshots
+├── activity-definitions/     # Customer-owned copies (DEC-003 option A)
+├── loops/
+│   └── <loop-id>/
+│       ├── roster.yaml       # Pilot + expansion_queue + saturated
+│       ├── bootstrap-log.md  # E2E cycle evidence
+│       ├── supplier-notes.md # Friction fed back to kaizen-agentic
+│       └── rotation-policy.yml  # ADR-004 diminishing-returns (optional)
+└── registry/                 # reuse-surface capability index (engagement D0)
+    ├── indexes/capabilities.yaml
+    └── capabilities/
+```
+
+## Naming
+
+| Artifact | coulomb-loop example |
+|----------|----------------------|
+| Workplan prefix | `LOOP-WP-NNNN` |
+| Hub topic slug | `coulomb_social` |
+| Engagement slug in schedules | `coulomb-loop` |
+| Supplier workplan | `KAIZEN-WP-0008` (kaizen-agentic) |
+
+## What does not live here
+
+- `agents/agent-*.md` — supplier (`kaizen-agentic`)
+- `.kaizen/schedule.yml` on customer repo — target fleet repos only
+- Temporal workers / resolvers — `activity-core`
+- state-hub service code — `the-custodian`
+
+## Bootstrap sequence
+
+See [customer-engagement-playbook.md](customer-engagement-playbook.md).
+
+## Related
+
+- coulomb-loop `docs/adr/ADR-002-customer-supplier-boundary.md`
+- [ADR-006](../adr/ADR-006-customer-engagement-convention.md)
+- [KAIZEN-WP-0008](../../workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md)
--- a/wiki/EcosystemIntegration.md
+++ b/wiki/EcosystemIntegration.md
@@ -111,6 +111,17 @@ runs `kaizen-agentic schedule prepare <agent>`.

 **Workplan:** KAIZEN-WP-0004 Part 2 + KAIZEN-WP-0006. Patterns: [docs/INTEGRATION_PATTERNS.md](../docs/INTEGRATION_PATTERNS.md).

+**Customer engagement (WP-0008, ADR-006)** — a customer repo (e.g. coulomb-loop)
+orchestrates loops across a fleet roster; supplier ships playbook + CLI:
+
+- [customer-engagement-playbook](../docs/integrations/customer-engagement-playbook.md)
+- [customer-engagement-repo-layout](../docs/integrations/customer-engagement-repo-layout.md)
+- [ADR-006](../docs/adr/ADR-006-customer-engagement-convention.md)
+- CLI: `schedule init --engagement`, `metrics record --emit-event`
+- activity-core handoff: [activity-core-handoff-engagement](../docs/integrations/activity-core-handoff-engagement.md)
+
+Reference customer: coulomb-loop `INTENT.md` (coulomb_social domain).
+
 ### artifact-store (P1)

 **Evidence retention** — durable registry for generated outputs.
--- a/workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md
+++ b/workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md
@@ -4,7 +4,7 @@ type: workplan
 title: "Coulomb-loop supplier engagement (customer-repo playbook)"
 domain: custodian
 repo: kaizen-agentic
-status: active
+status: done
 owner: kaizen-agentic
 topic_slug: custodian
 customer_repo: coulomb-loop
@@ -15,7 +15,7 @@ depends_on:
  - KAIZEN-WP-0004
 tasks:
  - id: T01
-    status: todo
+    status: done
    title: Document customer engagement repo layout from coulomb-loop reference
  - id: T02
    status: done
@@ -30,26 +30,26 @@ tasks:
    status: done
    title: Support pilot schedule init on kaizen-agentic the-custodian activity-core
  - id: T06
-    status: todo
+    status: done
    title: Draft ADR-006 customer engagement convention
  - id: T07
-    status: todo
+    status: done
    title: Absorb coulomb-loop supplier-notes into playbook v1
  - id: T08
-    status: todo
+    status: done
    title: ActivityDefinition override manifest design for hybrid sync
  - id: T09
-    status: todo
+    status: done
    title: Tests for emit-event and engagement init
  - id: T10
-    status: todo
+    status: done
    title: Update CHANGELOG wiki and cross-link coulomb-loop INTENT
 state_hub_workstream_id: "80f473eb-d052-4f50-a633-806f03c469be"
 ---

 # KAIZEN-WP-0008 — Coulomb-loop Supplier Engagement

-**Status:** active
+**Status:** done
 **Owner:** kaizen-agentic (supplier)
 **Customer:** `coulomb-loop` (coulomb_social domain)
 **Depends on:** WP-0006 (schedule contract), WP-0004 (activity-core integration)
@@ -96,7 +96,7 @@ Part 3 (T07–T08, T10)  ── after LOOP-WP-0004 supplier-notes available

 ```task
 id: KAIZEN-WP-0008-T01
-status: todo
+status: done
 priority: high
 state_hub_task_id: "177bb16c-6239-43f2-8d99-f4498c31d74a"
 ```
@@ -206,7 +206,7 @@ Writes hourly crons per ADR-003; documents engagement slug in schedule comment.

 ```task
 id: KAIZEN-WP-0008-T06
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "5c06cdd9-655d-4837-b725-1f89b83db6d4"
 ```
@@ -218,12 +218,13 @@ split, `.kaizen/` placement in target repos, playbook lifecycle.

 ```task
 id: KAIZEN-WP-0008-T09
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "f45077ea-5d24-4a85-bac2-ab9a3f61c20b"
 ```

-Unit tests: `--emit-event` payload shape; `--engagement` schedule output.
+Covered by `tests/test_metrics_emit_event.py` and `tests/test_schedule_cli.py`
+(engagement init + module presets).

 ---

@@ -233,7 +234,7 @@ Unit tests: `--emit-event` payload shape; `--engagement` schedule output.

 ```task
 id: KAIZEN-WP-0008-T07
-status: todo
+status: done
 priority: low
 state_hub_task_id: "0ef49fb5-af2f-4adf-aa90-1ea2cf389d00"
 ```
@@ -245,7 +246,7 @@ Target: second customer can copy template repo and run checklist in one session.

 ```task
 id: KAIZEN-WP-0008-T08
-status: todo
+status: done
 priority: low
 state_hub_task_id: "c9bee570-89b5-43e5-aabc-23c7dcc4e30c"
 ```
@@ -257,7 +258,7 @@ definition id → customer cron/labels/enabled overrides. No runtime in v1.

 ```task
 id: KAIZEN-WP-0008-T10
-status: todo
+status: done
 priority: low
 state_hub_task_id: "052a592b-ae7c-4213-9e09-eb8b37119d5e"
 ```