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