Draft capability entry (reuse-surface REUSE-WP-0017-T04, cohort 2)

Honest first-pass maturity vector grounded in README/docs/tests present
in this repo; no invented evidence. Flagged for human review before
publish. See reuse-surface history/2026-07-06-coverage-classification.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

.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.

.claude/rules/architecture.md

@@ -1,29 +1,8 @@
 ## Architecture
 
-kaizen-agentic has two distinct layers:
+<!-- TODO: Describe the key design decisions and component structure.
+     Key modules, data flows, external integrations, state machines, etc. -->
 
-### 1. Python framework (`src/kaizen_agentic/`)
+## Quick Reference
 
-- **`core.py`** — `Agent` (abstract base) + `AgentConfig` (dataclass). Tracks performance, supports config updates, implements kaizen interface.
-- **`optimization.py`** — `OptimizationLoop` (runs improvement cycles, detects trends, generates recommendations) + `PerformanceMetrics` (execution time, success rate, quality scores).
-- **`metrics.py`** — `MetricsStore` + `OptimizerStore` (project-scoped `.kaizen/metrics/` per ADR-004).
-
-### 2. Agent definitions (`agents/` — 20 files)
-
-Markdown instruction sets read and followed by Claude. Not executables. Naming convention: `agent-{name}.md`.
-Packaged copies live in `src/kaizen_agentic/data/agents/` for `pip install` distribution.
-
-| Category | Agents |
-|----------|--------|
-| Testing | `tdd-workflow`, `test-maintenance`, `testing-efficiency` |
-| Quality | `code-refactoring`, `datamodel-optimization` |
-| Process | `requirements-engineering`, `keepaTodofile`, `keepaChangelog`, `keepaContributingfile`, `project-assistant`, `priority-evaluation`, `scope-analyst` |
-| Infrastructure | `setupRepository`, `tooling-optimization`, `sys-medic` |
-| Release | `releaseManager` |
-| Docs | `claude-documentation` |
-| Support | `wisdom-encouragement` |
-| Meta | `coach`, `optimization` |
-
-### Custodian integration
-
-The state-hub MCP resolves the agents directory via `host_paths[hostname]` → `local_path`. Tools: `list_kaizen_agents(category?)`, `get_kaizen_agent(name)`.
+`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference

.claude/rules/credential-routing.md

@@ -0,0 +1,50 @@
+# Credential and access routing
+
+**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
+for inference. Run this check **before** requesting secrets, API keys, SSH access,
+login tokens, or database passwords — in any repo, not only `ops-warden`.
+
+ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
+other credential need belongs to another subsystem. **Do not** message
+`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key.
+
+### Lookup (do this first)
+
+```bash
+warden route find "<describe your need>" --json
+warden route show <catalog-id> --json
+```
+
+Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`).
+
+| Agent runtime | How to orient |
+| --- | --- |
+| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=kaizen-agentic` is for coordination, not secret vending |
+| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership |
+| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
+
+### Quick routing table
+
+| I need… | Owner | ops-warden executes? |
+| --- | --- | --- |
+| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
+| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
+| Login / OIDC / MFA | key-cape / Keycloak | No — route only |
+| Authorization decision | flex-auth | No — route only |
+| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` |
+| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |
+
+### Anti-patterns (do not do these)
+
+- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
+- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
+- Pasting secrets into Git, State Hub, workplans, logs, or chat
+
+### Other capabilities (reuse-surface)
+
+Non-credential capabilities are usually discovered through **reuse-surface** federation
+(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in
+every repo's agent instructions because it is high-frequency, high-risk, and easy to
+get wrong.
+
+**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`

.claude/rules/first-session.md

@@ -1,11 +1,11 @@
 ## First Session Protocol
 
-Triggered when `get_domain_summary("custodian")` shows **no workstreams**.
+Triggered when `get_domain_summary("agents")` shows **no workstreams**.
 The project is registered but work has not yet been structured.
 
 **Step 1 — Read, don't write**
-- `~/the-custodian/canon/projects/custodian/project_charter_v0.1.md` — purpose, scope
-- `~/the-custodian/canon/projects/custodian/roadmap_v0.1.md` — planned phases
+- `~/the-custodian/canon/projects/agents/project_charter_v0.1.md` — purpose, scope
+- `~/the-custodian/canon/projects/agents/roadmap_v0.1.md` — planned phases
 - Scan repo root: README, directory structure, existing code or docs
 
 **Step 2 — Survey in-progress work**
@@ -17,20 +17,20 @@ roadmap phase. **Wait for approval before creating.**
 
 **Step 4 — Create workplan file first, then DB record (ADR-001)**
 ```
-workplans/kaizen-agentic-WP-NNNN-<slug>.md   ← write this first
+workplans/KAIZEN-WP-NNNN-<slug>.md   ← write this first
 ```
 Then register in the hub:
 ```
-create_workstream(topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", title="...", owner="...", description="...")
+create_workstream(topic_id="64418556-3206-457a-ba29-6884b5b12cf3", title="...", owner="...", description="...")
 create_task(workstream_id="<id>", title="...", priority="high|medium|low")
 ```
 
 **Step 5 — Record the setup**
 ```
 add_progress_event(
-    summary="First session: structured custodian into N workstreams, M tasks",
+    summary="First session: structured agents into N workstreams, M tasks",
     event_type="milestone",
-    topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a",
+    topic_id="64418556-3206-457a-ba29-6884b5b12cf3",
     detail={"workstreams": [...], "tasks_created": M}
 )
 ```

.claude/rules/repo-boundary.md

@@ -2,7 +2,7 @@
 
 This repo owns **kaizen-agentic** only. It does not own:
 
-- State-hub MCP integration code → `the-custodian/state-hub/mcp_server/server.py`
-- Agent discovery tools (`list_kaizen_agents`, `get_kaizen_agent`) → `the-custodian`
-- Custodian coordination and workplan tracking → `the-custodian`
-- Deployment to custodiancore → `ops-bridge`
+<!-- TODO: List what belongs in adjacent repos, e.g.:
+- SSH key management → railiance-infra/
+- State hub code     → state-hub/
+-->

.claude/rules/repo-identity.md

@@ -1,9 +1,5 @@
-## Repo Identity
+**Purpose:** AI-assisted development quality toolchain. Provides pre-commit hooks, CI/CD pipeline automation, usage telemetry, and CLI improvement scaffolding for the custodian domain.
 
-**Purpose:** kaizen-agentic — AI agent development framework embracing kaizen (continuous improvement). Provides 17 specialized Claude Code companion agents plus an OptimizationLoop framework for continuous performance measurement and refinement.
-
-**Domain:** custodian
+**Domain:** agents
 **Repo slug:** kaizen-agentic
-**Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a
-
-**Custodian integration:** This repo is the single source of truth for all kaizen agents. The state-hub MCP exposes `list_kaizen_agents()` and `get_kaizen_agent(name)` tools so any connected session can discover and load agents without a local copy.
+**Topic ID:** 64418556-3206-457a-ba29-6884b5b12cf3

.claude/rules/session-protocol.md

@@ -1,29 +1,50 @@
 ## Session Protocol
 
-State Hub: http://127.0.0.1:8000
+Dev Hub (State Hub API): http://127.0.0.1:8000
+MCP server name in `~/.claude.json`: `dev-hub`
 
 **Step 1 — Orient**
+
+Read the offline-safe brief first — it works without a live hub connection:
+```bash
+cat .custodian-brief.md
 ```
-get_domain_summary("custodian")
+Then call the MCP tool for richer cross-domain context when MCP tools are exposed:
 ```
-If offline: `cd ~/the-custodian/state-hub && make api`
+get_domain_summary("agents")
+```
+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="kaizen-agentic", 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=kaizen-agentic&unread_only=true" \
+  | python3 -m json.tool
+curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
+  -H "Content-Type: application/json" -d '{}'
+```
+
 **Step 3 — Scan workplans**
 ```bash
 ls workplans/
 ```
-For each file with `status: active`, note pending `todo`/`in_progress` tasks.
+For each file with `status: ready`, `active`, or `blocked`, note pending
+`wait`/`todo`/`progress` tasks.
 
 **Step 4 — Present brief**
 
-1. **Active workstreams** for `custodian` — title, task counts, blocking decisions
+1. **Active workstreams** for `agents` — title, task counts, blocking decisions
 2. **Pending tasks** from `workplans/` + any `[repo:kaizen-agentic]` hub tasks
 3. **Goal guidance** — if `goal_guidance` in summary:
    - `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*
@@ -39,10 +60,26 @@ If no workstreams: follow First Session Protocol (`first-session.md`).
 > are First Session Protocol only. Work structure belongs in repo files (ADR-001).
 
 **Session close:**
+With MCP tools:
 ```
-add_progress_event(summary="...", topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", workstream_id="<uuid>")
+add_progress_event(summary="...", topic_id="64418556-3206-457a-ba29-6884b5b12cf3", workstream_id="<uuid>")
 ```
-If workplan files were modified:
+Without MCP tools:
 ```bash
-cd ~/the-custodian/state-hub && make fix-consistency REPO=kaizen-agentic
+curl -s -X POST http://127.0.0.1:8000/progress/ \
+  -H "Content-Type: application/json" \
+  -d '{"topic_id":"64418556-3206-457a-ba29-6884b5b12cf3","workstream_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
 ```
+If workplan files were modified, ensure the local copy is up to date first:
+```bash
+git -C <repo_path> pull --ff-only
+cd ~/state-hub && make fix-consistency REPO=kaizen-agentic
+```
+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=kaizen-agentic
+```
+**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.

.claude/rules/stack-and-commands.md

@@ -1,43 +1,19 @@
-## Stack and Commands
+## Stack
 
-**Language:** Python 3.8+
-**Package manager:** uv / pip (`.venv/`)
-**Test runner:** pytest
-**Linter/formatter:** flake8 (100-char), black (88-char), mypy (strict)
+<!-- TODO: Fill in language, frameworks, and key dependencies -->
+- **Language:**
+- **Key deps:**
 
-### Essential commands
+## Dev Commands
 
 ```bash
-make setup-complete     # First-time setup: venv + package + dev deps
-source .venv/bin/activate
-make test               # Run full test suite
-make lint               # flake8 linting
-make format             # black formatting
-make clean              # Remove build artifacts
+# TODO: Fill in the standard commands for this repo
+
+# Install dependencies
+
+# Run tests
+
+# Lint / type check
+
+# Build / package (if applicable)
 ```
-
-### TDD workflow
-
-```bash
-make tdd-start ISSUE=X  # Start issue with requirements validation
-make tdd-add-test       # Add test to current workspace
-make tdd-status         # Show workspace state
-make tdd-finish         # Move tests to main suite
-```
-
-### Issue management
-
-```bash
-make issue-list         # All issues (Gitea)
-make issue-list-open    # Open backlog
-make issue-show ISSUE=X # Issue detail
-make issue-create TITLE='...' BODY='...'
-```
-
-Run `make help` to see all available targets.
-
-### Core dependencies (pyproject.toml)
-
-- `pyyaml>=6.0` — YAML config
-- `click>=8.0.0` — CLI framework
-- `pydantic>=2.0.0` — Data validation

.claude/rules/workplan-convention.md

@@ -1,12 +1,40 @@
 ## Workplan Convention (ADR-001)
 
-File location: `workplans/kaizen-agentic-WP-NNNN-<slug>.md`
-ID prefix: `KAIZEN-WP`
+File location: `workplans/KAIZEN-WP-NNNN-<slug>.md`
+ID prefix: `KAIZEN-WP-`
 
 Work items originate as files in this repo **before** being registered in the hub.
 
+Canonical workplan/workstream frontmatter statuses are:
+`proposed`, `ready`, `active`, `blocked`, `backlog`, `finished`, `archived`.
+Use `proposed` for a newly drafted plan, `ready` after review against current
+repo state, and `finished` when implementation is complete. `stalled` and
+`needs_review` are derived health labels, not stored statuses.
+
+Closed workplans may be moved to `workplans/archived/` with a completion-date
+prefix: `YYMMDD-KAIZEN-WP-NNNN-<slug>.md`. The frontmatter id remains
+unchanged; the prefix is only for quick visual reference.
+
+Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**:
+`workplans/ADHOC-YYYY-MM-DD.md`, workstream slug `adhoc-YYYY-MM-DD`, and task ids
+`ADHOC-YYYY-MM-DD-T01`, `T02`, etc. Use adhocs only for low-risk work completed
+directly. Promote anything requiring analysis, design, approval, dependencies, or
+multiple planned phases into a normal workplan.
+
 Ecosystem todos from other agents arrive as `[repo:kaizen-agentic]` hub tasks —
 visible at session start. Pick one up by creating the workplan file, then registering
 the workstream.
 
+Task blocks use this shape:
+
+```task
+id: KAIZEN-WP-NNNN-T01
+status: wait | todo | progress | done | cancel
+priority: high | medium | low
+state_hub_task_id: "<uuid>"         # written by fix-consistency — do not edit
+```
+
+Status progression is `todo` → `progress` → `done`; use `wait` for waiting or
+blocked work and `cancel` for stopped work.
+
 <!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->

.custodian-brief.md

@@ -1,29 +1,18 @@
 <!-- custodian-brief: generated by fix-consistency — do not edit manually -->
 # Custodian Brief — kaizen-agentic
 
-**Domain:** custodian
-**Last synced:** 2026-06-18 02:54 UTC
+**Domain:** infotech
+**Last synced:** 2026-07-03 16:44 UTC
 **State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)*
 
 ## Active Workstreams
 
-### Coulomb-loop supplier engagement (customer-repo playbook)
-Progress: 1/10 done  |  workstream_id: `80f473eb-d052-4f50-a633-806f03c469be`
-
-**Open tasks:**
-- · Document customer engagement repo layout  `177bb16c`
-- · Playbook skeleton  `90bd0fc2`
-- · metrics record --emit-event  `26ee0f8d`
-- · schedule init --engagement  `62324bd2`
-- · ADR-006 customer engagement convention  `5c06cdd9`
-- · Tests  `f45077ea`
-- · Absorb supplier-notes into playbook v1  `0ef49fb5`
-- … and 2 more open tasks
+*(none — repo may need first-session setup)*
 
 ---
 ## MCP Orientation (when available)
 
 If the state-hub MCP server is reachable, call:
-`get_domain_summary("custodian")`
+`get_domain_summary("infotech")`
 This provides richer cross-domain context.
 If the MCP call fails, use this file as your orientation source.

.gitignore

@@ -45,3 +45,7 @@ htmlcov/
 
 # Backup directories created by optimization scripts
 agents_backup_*/
+
+# Project-scoped kaizen runtime state (ADR-002, ADR-004)
+.kaizen/agents/
+.kaizen/metrics/

.kaizen/schedule.yml

@@ -1,17 +1,15 @@
-# Kaizen scheduled agent execution (ADR-005)
-# Engagement: coulomb-loop bootstrap — hourly crons, daily cadence enum
-# Regulator promotes to daily/weekly per ADR-003
+# Kaizen scheduled agent execution manifest (ADR-005)
+# Engagement: coulomb-loop bootstrap — weekly cadence
+# Regulator promotes cadence per customer engagement policy (ADR-003).
+# Validate with: kaizen-agentic schedule validate
 version: '1'
 timezone: Europe/Berlin
 agents:
   coach:
-    cadence: daily
-    cron: "15 * * * *"
+    cadence: weekly
+    cron: 0 9 * * 1
     enabled: true
   optimization:
-    cadence: daily
-    cron: "30 * * * *"
+    cadence: weekly
+    cron: 0 10 * * 1
     enabled: true
-  tdd-workflow:
-    cadence: monthly
-    enabled: false

.repo-classification.yaml

@@ -0,0 +1,30 @@
+# Repo classification (Repo Classification Standard v1.0).
+
+repo_classification:
+  standard: Repo Classification Standard
+  version: '1.0'
+  classified_at: '2026-06-22'
+  classified_by: human
+  category: tooling
+  domain: agents
+  secondary_domains:
+  - infotech
+  capability_tags:
+  - orchestration
+  - automation
+  - coordination
+  - knowledge
+  - documentation
+  business_stake:
+  - technology
+  - product
+  - automation
+  - people
+  - intelligence
+  business_mechanics:
+  - intention
+  - coordination
+  - operation
+  - adaptation
+  notes: 'Digital talent-agency framework: agent personas, project memory, improvement loops,
+    CLI tooling. Primary domain agents (AI-native), infotech secondary.'

AGENTS.md

@@ -0,0 +1,219 @@
+# kaizen-agentic — Agent Instructions
+
+## Repo Identity
+
+**Purpose:** AI-assisted development quality toolchain. Provides pre-commit hooks, CI/CD pipeline automation, usage telemetry, and CLI improvement scaffolding for the custodian domain.
+
+**Domain:** agents
+**Repo slug:** kaizen-agentic
+**Topic ID:** `64418556-3206-457a-ba29-6884b5b12cf3`
+**Workplan prefix:** `KAIZEN-WP-`
+
+---
+
+## State Hub Integration
+
+The Custodian State Hub tracks work across all domains. Interact via HTTP REST —
+there is no MCP server for Codex agents.
+
+| Context | URL |
+|---------|-----|
+| Local workstation | `http://127.0.0.1:8000` |
+| Remote via tunnel | `http://127.0.0.1:18000` |
+
+### Orient at session start
+
+```bash
+# Offline brief — works without hub connection
+cat .custodian-brief.md
+
+# Active workstreams for this domain
+curl -s "http://127.0.0.1:8000/workstreams/?topic_id=64418556-3206-457a-ba29-6884b5b12cf3&status=active" \
+  | python3 -m json.tool
+
+# Check inbox
+curl -s "http://127.0.0.1:8000/messages/?to_agent=kaizen-agentic&unread_only=true" \
+  | python3 -m json.tool
+```
+
+Mark a message read:
+```bash
+curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
+  -H "Content-Type: application/json" -d '{}'
+```
+
+### Log progress (required at session close)
+
+```bash
+curl -s -X POST http://127.0.0.1:8000/progress/ \
+  -H "Content-Type: application/json" \
+  -d '{
+    "summary": "what was done",
+    "event_type": "note",
+    "author": "codex",
+    "workstream_id": "<uuid>",
+    "task_id": "<uuid>"
+  }'
+```
+
+Omit `workstream_id` / `task_id` when not applicable.
+
+### Update task status
+
+```bash
+curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
+  -H "Content-Type: application/json" \
+  -d '{"status": "progress"}'
+# values: wait | todo | progress | done | cancel
+```
+
+### Flag a task for human review
+
+```bash
+curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
+  -H "Content-Type: application/json" \
+  -d '{"needs_human": true, "intervention_note": "reason"}'
+```
+
+---
+
+## Session Protocol
+
+**Start:**
+1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe)
+2. Check inbox: `GET /messages/?to_agent=kaizen-agentic&unread_only=true`; mark read
+3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks
+4. Check human-needed tasks: `GET /tasks/?needs_human=true`
+
+**During work:**
+- Update task statuses in workplan files as tasks progress
+- Record significant decisions via `POST /decisions/`
+
+**Close:**
+1. Update workplan file task statuses to reflect progress
+2. Log: `POST /progress/` with a summary of what changed
+3. Note for the custodian operator: after workplan file changes, run from
+   `~/state-hub`:
+   ```bash
+   make fix-consistency REPO=kaizen-agentic
+   ```
+   This syncs task status from files into the hub DB.
+
+---
+
+## Credential and access routing
+
+**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
+for inference. Run this check **before** requesting secrets, API keys, SSH access,
+login tokens, or database passwords — in any repo, not only `ops-warden`.
+
+ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
+other credential need belongs to another subsystem. **Do not** message
+`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key.
+
+### Lookup (do this first)
+
+```bash
+warden route find "<describe your need>" --json
+warden route show <catalog-id> --json
+```
+
+Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`).
+
+| Agent runtime | How to orient |
+| --- | --- |
+| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=kaizen-agentic` is for coordination, not secret vending |
+| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership |
+| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
+
+### Quick routing table
+
+| I need… | Owner | ops-warden executes? |
+| --- | --- | --- |
+| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
+| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
+| Login / OIDC / MFA | key-cape / Keycloak | No — route only |
+| Authorization decision | flex-auth | No — route only |
+| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` |
+| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |
+
+### Anti-patterns (do not do these)
+
+- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
+- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
+- Pasting secrets into Git, State Hub, workplans, logs, or chat
+
+### Other capabilities (reuse-surface)
+
+Non-credential capabilities are usually discovered through **reuse-surface** federation
+(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in
+every repo's agent instructions because it is high-frequency, high-risk, and easy to
+get wrong.
+
+**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
+
+<!-- REPO-AGENTS-EXTENSIONS -->
+<!-- Append repo-specific agent instructions below this marker.
+     The state-hub template sync preserves content after this line. -->
+
+---
+
+## Workplan Convention (ADR-001)
+
+Work items originate as files in this repo — not in the hub. The hub is a
+read/cache/index layer that rebuilds from files.
+
+**File location:** `workplans/KAIZEN-WP-NNNN-<slug>.md`
+
+**Archived location:** finished workplans may move to
+`workplans/archived/YYMMDD-KAIZEN-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
+the completion/archive date; the frontmatter `id` does not change.
+
+**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use
+`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use
+this only for low-risk work completed directly; create a normal workplan for
+anything needing analysis, design, approval, dependencies, or multiple phases.
+
+**Frontmatter:**
+
+```yaml
+---
+id: KAIZEN-WP-NNNN
+type: workplan
+title: "..."
+domain: agents
+repo: kaizen-agentic
+status: proposed | ready | active | blocked | backlog | finished | archived
+owner: codex
+topic_slug: ...
+created: "YYYY-MM-DD"
+updated: "YYYY-MM-DD"
+state_hub_workstream_id: "<uuid>"   # written by fix-consistency — do not edit
+---
+```
+
+Use `proposed` for a new draft, `ready` after review against current repo
+state, and `finished` after implementation. `stalled` and `needs_review` are
+derived health labels, not frontmatter statuses.
+
+**Task block format** (one per `##` section):
+
+```
+## Task Title
+
+` ` `task
+id: KAIZEN-WP-NNNN-T01
+status: wait | todo | progress | done | cancel
+priority: high | medium | low
+state_hub_task_id: "<uuid>"         # written by fix-consistency — do not edit
+` ` `
+
+Task description text.
+```
+
+Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work.
+
+To create a new workplan:
+1. Write the file following the format above
+2. Notify the custodian operator to run `make fix-consistency REPO=kaizen-agentic`
+   (or send a message to the hub agent via `POST /messages/`)

CHANGELOG.md

@@ -7,12 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Removed
+- **`TODO.md`** — work tracking uses `workplans/` and State Hub (ADR-001); the
+  `keepaTodofile` agent remains available for other projects
+
 ### Added
 - **`metrics record --emit-event`** — publishes `kaizen.metrics.recorded` NATS
   envelope for activity-core event-driven definitions (optional `nats-py` via
   `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`
 

CLAUDE.md

@@ -1,5 +1,6 @@
 # kaizen-agentic — Claude Code Instructions
 
+@SCOPE.md
 @.claude/rules/repo-identity.md
 @.claude/rules/session-protocol.md
 @.claude/rules/first-session.md
@@ -7,50 +8,5 @@
 @.claude/rules/stack-and-commands.md
 @.claude/rules/architecture.md
 @.claude/rules/repo-boundary.md
-
-## Installed Agents
-
-This project includes the following specialized agents:
-
-### Documentation
-
-- **claude-documentation**: Specialized assistant for Claude and Claude Code documentation, features, and best practices
-- **keepaContributingfile**: Specialized assistant for maintaining CONTRIBUTING.md files following Keep a Contributing-File V0.0.1 format within the Kaizen Agentic framework
-- **wisdom-encouragement**: Provides encouraging wisdom and guidance for complex implementation tasks and challenging technical work
-
-### Meta
-
-- **coach**: Coaching meta-agent that reads all agent memories in a project and synthesises cross-agent briefs and new-agent orientations
-- **optimization**: Meta-agent that analyzes and optimizes other Claude Code subagents based on their performance data, usage patterns, and effectiveness metrics. Use PROACTIVELY for agent ecosystem improvement.
-
-### Code Quality
-
-- **code-refactoring**: Analyze code structure and quality, identify improvement opportunities, and provide actionable refactoring guidance. Use PROACTIVELY for code quality assessment and improvement.
-- **datamodel-optimization**: Specialized agent that systematically analyzes, optimizes, and enhances dataclasses, models, and data structures within a codebase. Provides comprehensive datamodel improvements including convenience methods, interface consistency, code reduction, and test alignment.
-
-### Project Management
-
-- **keepaChangelog**: Specialized assistant for maintaining CHANGELOG.md files following Keep a Changelog format
-- **keepaTodofile**: Specialized assistant for maintaining TODO.md files following Keep a Todofile V0.0.1 format
-- **priority-evaluation**: Specialized assistant to help evaluate and establish priorities for issues and tasks.
-- **project-assistant**: Specialized assistant for project status, progress tracking, and development planning
-- **releaseManager**: Manages software releases, version control, and publication workflows for Python packages
-- **scope-analyst**: Analyze a repository and produce/improve SCOPE.md for rapid orientation
-
-### Development Process
-
-- **requirements-engineering**: Specialized agent designed to prevent interface compatibility issues and mock object mismatches by ensuring solid foundation planning before implementation. Based on lessons learned from Issue
-- **tdd-workflow**: Expert guidance for the TDD8 workflow methodology, specializing in the comprehensive ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH cycle with sophisticated sidequest management and proper test organization.
-
-### Infrastructure
-
-- **setupRepository**: Specialized assistant for setting up new Python repositories following PythonVibes best practices
-- **sys-medic**: Linux/Kubernetes node health assessment agent — diagnoses process, memory, CPU, disk, network, and kubelet issues with safe, prioritized, evidence-driven guidance
-- **tooling-optimization**: Meta-agent that analyzes and optimizes repository tooling usage to improve development efficiency
-
-### Testing
-
-- **test-maintenance**: Specialized agent for analyzing and fixing failing tests in the project
-- **testing-efficiency**: Specialized agent designed to optimize TDD8 workflow test execution, resolve pytest reliability issues, and enhance overall testing efficiency for red-green iterations. Focuses on smart test selection, parallel execution, and agent integration patterns.
-
-Use these agents by referencing them in your Claude Code interactions.
+@.claude/rules/credential-routing.md
+@.claude/rules/agents.md

CONTRIBUTING.md

@@ -45,7 +45,7 @@ This repository follows PythonVibes best practices:
 - `src/kaizen_agentic/` - Core framework source code
 - `agents/` - Specialized agent definitions (17+ agents)
 - `tests/` - Comprehensive test suite
-- `TODO.md` - Current development tasks (Keep a Todofile format)
+- `workplans/` - Active workstreams and tasks (ADR-001)
 - `CHANGELOG.md` - Version history (Keep a Changelog format)
 
 ### Making Changes
@@ -155,15 +155,15 @@ When reporting bugs, please include:
 1. **Discuss significant changes** in an issue first
 2. **Keep PRs focused** on a single feature or fix
 3. **Write clear commit messages** following conventional commit format
-4. **Update relevant documentation** including TODO.md and CHANGELOG.md
+4. **Update relevant documentation** including workplans and CHANGELOG.md
 5. **Ensure all checks pass** including tests and linting
 6. **Respond to review feedback** promptly and constructively
 
 ## Agent-Assisted Development
 
 This repository includes 17+ specialized agents to assist with development:
-- Use `todo-keeper` for TODO.md maintenance
-- Use `changelog-keeper` for CHANGELOG.md updates
+- Use `keepaChangelog` for CHANGELOG.md updates
+- Use `project-assistant` for workplan and session orientation
 - Use `contributing-keeper` for this file maintenance
 - See CLAUDE.md for complete agent catalog and usage
 

TODO.md

@@ -1,219 +0,0 @@
-# Todofile
-
-This is a "to do next" file, particularly useful to keep the human and a coding assistant in sync.
-
-The format is based on [Keep a Todofile V0.0.1](https://coulomb.social/open/TodoFileGuide).
-
-The structure organizes **future tasks** by their impact, just as a changelog organizes past changes by their impact.
-
-***
-
-## [Unreleased] - *Active Vibe-Coding State* 💡
-
-Tasks in workplan: `workplans/kaizen-agentic-WP-0007-agent-authoring-doc-generation.md` (v1.4.0)
-
-### Implemented (pending v1.4.0 tag)
-* **`create-agent`** — scaffold schema-valid agents
-* **`docs generate [--check]`** — idempotent CLAUDE.md Installed Agents refresh
-* **Frontmatter schema validation** in `validate`
-* **Doc-regeneration idempotency fix** + agent file rename (project-assistant)
-
-### To Add (release)
-* **Tag v1.4.0** — after review
-* **activity-core implementation** — WP-0006 resolver + sync (separate repo; see handoff doc)
-
-### Shipped — v1.3.0 (2026-06-17)
-* **ADR-005 + `.kaizen/schedule.yml`** — scheduled agent execution contract
-* **`kaizen-agentic schedule`** — validate, init, prepare, list
-* **activity-core definitions** — weekly coach + optimization on preselected repos
-
-### Deferred / future
-* Interactive agent selection wizard (multi-step) — `create-agent` covers the
-  single-agent scaffold; a guided multi-agent wizard remains future work
-* Multi-file agent packages / protocol scaffolding
-
-***
-
-## [1.1.0] - Community Engagement — *Shipped 2026-06-18*
-
-See `CHANGELOG.md` [1.1.0] and `workplans/kaizen-agentic-WP-0001-community-engagement.md`.
-
-***
-
-## [COMPLETED] - *Documentation Standards Compliance - Version 0.2.0*
-
-### ✅ Completed: To Add
-* **CLI interface** for agent management and execution - DONE
-  - Full `kaizen-agentic` CLI with 8 commands (init, install, update, remove, list, status, validate, templates)
-  - Console script entry point for global availability
-  - Complete command-line interface with options and help
-* **Comprehensive tests** for optimization module (PerformanceMetrics, OptimizationLoop) - DONE
-  - 24 tests covering all components with 100% pass rate
-  - Test coverage for registry, installer, and core functionality
-  - Automated test execution with make test/test-all targets
-* **Agent registry and installer functionality** - DONE
-  - Complete AgentRegistry with categorization and dependency resolution
-  - AgentInstaller with backup/rollback capabilities
-  - ProjectInitializer with template-based project creation
-* **Comprehensive documentation system** - DONE
-  - GETTING_STARTED.md - Complete setup and usage guide
-  - AGENT_DISTRIBUTION.md - Architecture documentation
-  - CLI_CHEAT_SHEET.md - Quick reference guide
-  - Updated README.md with complete usage examples
-
-### ✅ Completed: To Refactor
-* **Agent definitions** to follow consistent format standards - DONE
-  - All 17+ agents updated to YAML frontmatter format
-  - Consistent categorization system (project-management, development-process, etc.)
-  - Proper dependency declarations and descriptions
-* **Makefile structure** for better user experience - DONE
-  - Reorganized with consistent naming (agents-, setup-, standards- prefixes)
-  - Enhanced help system with examples and clear descriptions
-  - 50+ targets organized into logical sections
-* **Test execution performance** optimization - DONE
-  - Fast execution with all 24 tests completing in <1 second
-  - Parallel execution capabilities
-  - Efficient backup/cleanup in test teardown
-
-### ✅ Completed: To Fix
-* **Makefile targets** compatibility across environments - DONE
-  - Cross-platform compatibility with proper shell detection
-  - Virtual environment handling with fallback mechanisms
-  - Error handling and recovery in setup processes
-* **Linting issues** in core modules - DONE
-  - All flake8 violations resolved across entire codebase
-  - PEP 8 compliance achieved
-  - Consistent code formatting with black
-* **Virtual environment setup** reliability - DONE
-  - Robust venv creation and activation
-  - Dependency installation with upgrade handling
-  - Status checking and validation
-* **CLI installation make target (agents-install-cli)** - DONE
-  - Target is working properly and requires virtual environment activation as documented
-  - Installation process functions correctly with proper venv setup
-* **YAML frontmatter errors in agent files** causing loading failures - DONE
-  - All 16 agents now properly loading without YAML parsing errors
-  - Frontmatter format standardized across all agent definitions
-* **Agent categorization issues** (agents showing as "Unknown" instead of proper categories) - DONE
-  - All 16 agents now properly categorized and displaying correct categories
-  - Category mapping and recognition system functioning correctly
-
-### ✅ Completed: To Secure
-* **Configuration file validation** - DONE
-  - Safe YAML parsing with error handling
-  - Input validation for all CLI parameters
-  - Backup creation before modifications
-* **Agent integrity checks** - DONE
-  - Validation system for agent definitions
-  - Dependency conflict detection
-  - Installation verification
-
-### ✅ Completed: To Remove
-* **Obsolete test fixtures** - DONE
-  - Clean test directory structure
-  - Removed unused imports and variables
-  - Eliminated development scaffolding
-
-***
-
-## [COMPLETED] - *Scenario 1: Greenfield Project Excellence - Version 0.2.1*
-
-### ✅ Completed: Scenario 1 Tasks
-* **Scenario 1 exploration: Establish codebase from scratch** - DONE
-  - Research current onboarding experience with existing setup targets - DONE
-  - Identify gaps in documentation for new project creation - DONE
-  - Test and validate smooth project initialization workflows - DONE
-  - Evaluate agent selection and recommendation systems for new projects - DONE
-  - Document best practices for greenfield project setup - DONE
-
-### ✅ Completed: Additional Scenario 1 Improvements
-* **Agent template name mappings fixed** - DONE
-  - Fixed agent template name mappings to match actual agent names
-  - Ensured consistency between template references and installed agents
-* **ProjectInitializer enhancements** - DONE
-  - Added Makefile creation to ProjectInitializer for complete greenfield setup
-  - Implemented comprehensive project scaffolding
-* **Test framework stability** - DONE
-  - Fixed all failing tests for agent framework updates
-  - Achieved 100% test pass rate across all components
-* **Documentation and tutorial creation** - DONE
-  - Updated documentation with correct agent names
-  - Created HelloWorld tutorial for new users
-  - Comprehensive onboarding experience established
-
-### ✅ Completed: Production Readiness
-* **Scenario 1 state achievement** - DONE
-  - Scenario 1 (establish codebase from scratch) is now excellent and production-ready
-  - Complete end-to-end workflow for greenfield projects
-  - Robust agent selection and project initialization
-
-***
-
-## [COMPLETED] - *Production Release with Release Management - Version 1.0.0*
-
-### ✅ Completed: Release Management System
-* **Complete release management system** with agent-releaseManager - DONE
-  - 6 structured make targets for complete release workflow
-  - `release-check` - Validate release readiness with comprehensive checklist
-  - `release-prepare` - Build packages and prepare for publication
-  - `release-test` - Test publication workflow using TestPyPI
-  - `release-publish` - Publish to production PyPI with safety checks
-  - `release-finalize` - Post-release tasks (tags, GitHub releases, documentation)
-  - `release-rollback` - Emergency rollback procedures and guidance
-* **Local package installation capability** - DONE
-  - `make install-local` target for PyPI-equivalent testing
-  - Local package building and installation workflow
-  - Integration testing with locally built packages
-* **Documentation updates for installation options** - DONE
-  - Updated documentation to reflect all installation methods
-  - PyPI installation guidance and local development setup
-  - Complete user onboarding documentation
-* **Package distribution readiness** - DONE
-  - Full package ready for PyPI publication
-  - All agents included in package data distribution
-  - Console script entry point for global CLI availability
-  - Version 1.0.0 production release achieved
-
-***
-
-## [COMPLETED] - *Scenario 2: Existing Project Integration Excellence - Version 0.2.2*
-
-### ✅ Completed: Scenario 2 Tasks
-* **Scenario 2 exploration: Integration with existing projects having agents** - DONE
-  - Research detection of existing agent systems in projects - DONE
-  - Design conflict resolution strategies for overlapping agent functionality - DONE
-  - Create migration paths for replacing outdated project-specific agents - DONE
-  - Develop extension mechanisms for project-specific kaizen agent customizations - DONE
-  - Define integration patterns that respect existing project structure - DONE
-  - Build tooling for safe agent system transitions - DONE
-
-### ✅ Completed: Major Components Built
-* **Detection system (detection.py)** for analyzing existing agent systems - DONE
-  - Comprehensive agent system detection across multiple formats
-  - Analysis of conflicts and overlap identification
-  - Integration readiness assessment
-* **Migration framework (migration.py)** with 5 migration strategies - DONE
-  - Replace strategy for complete agent replacement
-  - Merge strategy for combining functionalities
-  - Extend strategy for adding new capabilities
-  - Coexist strategy for parallel operation
-  - Archive strategy for deprecation handling
-* **Extension system (extensions.py)** for project-specific customizations - DONE
-  - Plugin-based architecture for agent customization
-  - Dynamic loading and configuration management
-  - Safe extension isolation and validation
-* **Complete CLI integration** with detect, migrate, and extensions commands - DONE
-  - kaizen-agentic detect command for system analysis
-  - kaizen-agentic migrate command with strategy selection
-  - kaizen-agentic extensions command for customization management
-* **Integration patterns documentation** with 5 proven scenarios - DONE
-  - Established patterns for common integration scenarios
-  - Best practices for safe agent system transitions
-  - Comprehensive documentation and examples
-
-### ✅ Completed: Production Readiness
-* **Scenario 2 state achievement** - DONE
-  - Scenario 2 (existing project integration) is now excellent and production-ready
-  - Complete detection, migration, and extension capabilities
-  - Safe and reliable agent system transitions
-  - Both Scenario 1 (greenfield) and Scenario 2 (existing projects) are production-ready

docs/adr/ADR-005-scheduled-agent-execution.md

@@ -105,7 +105,7 @@ Assembles, from **local `.kaizen/` state only** (offline-safe):
 - The agent prompt (`agents/agent-<name>.md`, installed or packaged).
 - Project memory (`.kaizen/agents/<name>/memory.md`) when present.
 - Metrics summary (`.kaizen/metrics/<name>/summary.json`) when present.
-- Repo pointers (`SCOPE.md`, `TODO.md`) when present.
+- Repo pointers (`SCOPE.md`, `workplans/`) when present.
 - Suggested session-close commands (`metrics record`, memory update).
 
 Output is `markdown` (default) or `json` (`--format json`) so activity-core can

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)

docs/integrations/activity-core-handoff-wp0006.md

@@ -21,22 +21,35 @@ execution (WP-0006)"* and track the boxes there.
 
 ## What activity-core must do
 
-- [ ] **Implement resolver** `discover_kaizen_scheduled_repos` per the spec
-      (hub roster ∩ repos with valid `.kaizen/schedule.yml`).
-- [ ] **Add resolver unit tests** using the four fixtures in the spec.
-- [ ] **Copy definitions** from `docs/integrations/activity-definitions/`
+- [x] **Implement resolver** `discover_kaizen_scheduled_repos` per the spec
+      (`activity_core/context_resolvers/kaizen.py`).
+- [x] **Add resolver unit tests** — `tests/test_kaizen_context_resolver.py` (7 passed).
+- [ ] **Copy custodian weekly definitions** from `docs/integrations/activity-definitions/`
       (`weekly-coach-orientation.md`, `weekly-optimization-review.md`) into the
-      activity-core catalog path (per ACT-ADR-002).
-- [ ] **Register** each definition slug in the activity-core index.
-- [ ] **Run** `make sync-activity-definitions` in activity-core.
-- [ ] **Wire cron** triggers (Mon 09:00 / 10:00 Europe/Berlin) to the resolver.
-- [ ] **Smoke test** against a pilot repo (see below) with the definition still
-      `enabled: false` (dry-run task creation).
-- [ ] **Enable gradually** — flip one definition to `enabled: true` in staging
-      after the smoke test passes.
-- [ ] **Verify runner prerequisites** — `kaizen-agentic` on PATH and the Gitea
-      PyPI extra index if the runner installs from registry (see
-      [PACKAGE_RELEASE.md](../PACKAGE_RELEASE.md)).
+      activity-core catalog path (per ACT-ADR-002). *Deferred: coulomb-loop engagement
+      ships customer-owned daily bootstrap definitions instead (LOOP-WP-0001).*
+- [ ] **Register** weekly definition slugs in the activity-core index (when custodian
+      fleet moves off coulomb engagement copies).
+- [x] **Run** `make sync-activity-definitions` — coulomb-loop definitions synced
+      (`coulomb-hourly-coach-orientation`, `coulomb-hourly-optimization-review`, etc.).
+- [x] **Wire cron** triggers — daily stabilize chain on pilot roster (08:00–10:00).
+- [x] **Smoke test** — resolver dry-run returns 6 `scheduled_runs` on coulomb roster;
+      `schedule prepare coach` succeeds on `kaizen-agentic` and `the-custodian`.
+- [x] **Enable gradually** — coulomb bootstrap definitions `enabled: true` on pilot.
+- [x] **Verify runner prerequisites** — `kaizen-agentic` on PATH; `KAIZEN_RUNNER_HOST`
+      set on worker (`bnt-lap001`).
+
+### Supplier closure evidence (2026-06-18)
+
+| Check | Result |
+|-------|--------|
+| Resolver dry-run (coulomb roster, `cadence: daily`) | 6 runs across 3 pilot repos |
+| `tests/test_kaizen_context_resolver.py` | 7 passed |
+| `schedule validate` + `prepare coach` | OK on `kaizen-agentic`, `the-custodian`, `activity-core` |
+| Live definitions using resolver | `f234bb1a` coach, `097fc027` optimization (enabled) |
+
+**Remaining activity-core item:** optional custodian-fleet weekly templates (`enabled: false`
+in kaizen-agentic drafts) when engagement moves beyond coulomb-loop bootstrap copies.
 
 ## State Hub team (the-custodian)
 

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)

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.coulomb.social/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,54 @@ 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. Use atomic promote to
+align all three layers (cadence.yml, activity-definitions, fleet schedule.yml,
+activity-core sync):
 
 ```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 promote \
+  --engagement-repo /path/to/customer-loop \
+  --engagement <slug> \
+  --to-phase operate \
+  --activity-core /path/to/activity-core
 ```
 
+Dry-run: `--dry-run`. Repair fleet drift after a partial promotion: `--fleet-only`.
+
+Legacy per-layer commands still work:
+
+```bash
+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.coulomb.social/coulomb/coulomb-loop/src/branch/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)

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.coulomb.social/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)

docs/integrations/kaizen-metrics-recorded-event.md

@@ -2,6 +2,10 @@
 
 **Status:** implemented — `kaizen-agentic metrics record --emit-event`
 
+**Registry:** `event-types/kaizen.metrics.recorded.md` (producer-owned, synced via
+activity-core `make sync-event-types` with `ACTIVITY_DEFINITION_DIRS` including
+this repo)
+
 Emitted after a successful metrics append when `--emit-event` is set. Default
 off for backward compatibility.
 

docs/integrations/kaizen-schedule-prepared-event.md

@@ -35,7 +35,7 @@ NATS/event-bus subject, sibling to the existing `kaizen.metrics.recorded` and
     "agent_prompt_found": true,
     "has_memory": true,
     "has_metrics": true,
-    "pointers": ["scope", "todo"],
+    "pointers": ["scope", "workplans"],
     "bytes": 8421
   },
   "session_close": [
@@ -60,7 +60,7 @@ NATS/event-bus subject, sibling to the existing `kaizen.metrics.recorded` and
 | `bundle.agent_prompt_found` | bool | Mirrors `schedule prepare --format json` |
 | `bundle.has_memory` | bool | Memory file present |
 | `bundle.has_metrics` | bool | Metrics summary present |
-| `bundle.pointers` | string[] | Repo pointer labels found (`scope`, `todo`) |
+| `bundle.pointers` | string[] | Repo pointer labels found (`scope`, `workplans`) |
 | `bundle.bytes` | int | Rendered bundle size |
 | `session_close` | string[] | Suggested close commands |
 

event-types/kaizen.metrics.recorded.md

@@ -0,0 +1,65 @@
+---
+type_id: kaizen.metrics.recorded
+version: "1.0"
+publisher: kaizen-agentic
+governance: publisher-declared
+status: active
+---
+
+# kaizen.metrics.recorded
+
+## Intent
+
+Emitted when a project records agent execution metrics via
+`kaizen-agentic metrics record --emit-event`. Signals that rolling performance
+summary changed and may trigger quality-escalation ActivityDefinitions.
+
+**Owning repo:** `kaizen-agentic` — schema changes require supplier review.
+
+## When Published
+
+- CLI: `kaizen-agentic metrics record <agent> --emit-event` after successful append
+- Not emitted when append is skipped (duplicate idempotency key)
+- NATS subject: `activity.kaizen.metrics.recorded`
+
+## Attributes
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| agent | string | yes | Agent name from `metrics record <agent>` |
+| project | string | yes | Repo slug (`KAIZEN_PROJECT_SLUG` or directory basename) |
+| summary.success_rate | float | yes | Rolling success rate from `summary.json` after append |
+| summary.execution_count | integer | yes | Total execution count |
+| summary.avg_quality | float | no | Average quality score (maps from `avg_quality_score`) |
+
+## Example Payload
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "type": "kaizen.metrics.recorded",
+  "version": "1.0",
+  "timestamp": "2026-06-18T12:00:00Z",
+  "publisher": "kaizen-agentic",
+  "attributes": {
+    "agent": "coach",
+    "project": "kaizen-agentic",
+    "summary": {
+      "success_rate": 0.75,
+      "execution_count": 12,
+      "avg_quality": 0.81
+    }
+  }
+}
+```
+
+## Consumer Notes
+
+- **activity-core**: `event-payload` resolver binds `attributes` → `context.metrics`
+  for rules such as `flag-low-success-rate`
+- **coulomb-loop**: `low-success-rate-review` (LOOP-WP-0002) — primary reactive path
+
+## Related
+
+- `docs/integrations/kaizen-metrics-recorded-event.md`
+- `coulomb-loop/loops/quality-escalation/event-payload.md`

registry/capabilities/capability.agents.kaizen-framework.md

@@ -0,0 +1,121 @@
+---
+id: capability.agents.kaizen-framework
+name: Kaizen Agentic Framework
+summary: AI agency framework providing 18 specialized deployable agent instruction sets plus persistent,
+  project-scoped memory and cross-agent coordination via a Coach meta-agent.
+owner: kaizen-agentic
+status: draft
+domain: agents
+tags:
+- agents
+- memory
+- coordination
+maturity:
+  discovery:
+    current: D3
+    target: D5
+    confidence: medium
+    rationale: README documents the agent library, the agency framework (persistent memory, Coach meta-agent
+      synthesising fleet-wide patterns), and a versioned release (v1.4.0); has .gitea/workflows CI.
+  availability:
+    current: A2
+    target: A3
+    confidence: medium
+    rationale: Installable via `git clone` + `make setup-complete` + `make agents-install-cli`, with both
+      source and global installation paths documented; pyproject-packaged.
+external_evidence:
+  completeness:
+    level: C1
+    confidence: low
+    basis: scope_vs_intent_and_consumer_expectations
+    satisfied_expectations:
+    - 18 specialized agent instruction sets
+    - persistent project-scoped agent memory
+    - Coach meta-agent for fleet-wide pattern synthesis
+    broken_expectations: []
+    out_of_scope_expectations: []
+  reliability:
+    level: R0
+    confidence: low
+    basis: consumer_quality_signals
+    known_reliability_risks:
+    - no external reuse evidence yet outside the originating project
+discovery:
+  intent: Let agents arrive in a project already informed and improve over time through persistent, project-scoped
+    memory and fleet-wide coordination via a Coach meta-agent.
+  includes:
+  - 18 specialized agent instruction sets
+  - persistent memory and coordination framework
+  - Coach meta-agent pattern synthesis
+  excludes:
+  - the underlying LLM inference itself (agents are instruction sets, not a model)
+  assumptions: []
+  use_cases: []
+  research_memos: []
+availability:
+  current_level: A2
+  target_level: A3
+  current_artifacts:
+  - Python package (`kaizen-agentic`) v1.4.0
+  - CLI (`agents-install-cli`)
+  target_artifacts: []
+  consumption_modes:
+  - cli
+  - library import
+relations:
+  depends_on: []
+  supports: []
+  related_to: []
+evidence:
+  documentation:
+  - README.md
+  tests:
+  - tests/
+  - .gitea/workflows/
+  consumer_feedback: []
+  bug_reports: []
+  incidents: []
+consumer_guidance:
+  recommended_for:
+  - projects wanting a deployable, memory-persistent agent fleet with cross-agent coordination
+  not_recommended_for:
+  - needs for a single stateless agent (framework overhead not justified)
+  known_limitations:
+  - no cross-project reuse evidence recorded yet
+promotion_history: []
+---
+
+# Kaizen Agentic Framework
+
+## Overview
+
+`kaizen-agentic` is an AI agency framework: 18 specialized agents deployable into any project, each gaining persistent project-scoped memory and coordination through a Coach meta-agent that synthesises fleet-wide patterns and briefs incoming agents.
+
+## Assessment notes
+
+### Discovery
+
+README documents the agent library, the agency framework (persistent memory, Coach meta-agent synthesising fleet-wide patterns), and a versioned release (v1.4.0); has .gitea/workflows CI.
+
+### Availability
+
+Installable via `git clone` + `make setup-complete` + `make agents-install-cli`, with both source and global installation paths documented; pyproject-packaged.
+
+### Completeness
+
+First-pass honest assessment from the REUSE-WP-0017 coverage campaign
+(reuse-surface). No external consumer feedback exists yet; levels reflect
+scope-vs-intent documentation quality, not internal code quality.
+
+### Reliability
+
+No production consumer telemetry exists yet; reliability level is
+intentionally conservative pending REUSE-WP-0019 reuse-telemetry evidence.
+
+## Promotion checklist
+
+- [x] ID follows `capability.<domain>.<name>` pattern
+- [x] Maturity enums match `specs/CapabilityMaturityStandard.md`
+- [x] `external_evidence` is populated separately from `maturity`
+- [ ] Relations reference valid capability IDs (none yet)
+- [x] Index entry added in `registry/indexes/capabilities.yaml`

registry/indexes/capabilities.yaml

@@ -1,4 +1,20 @@
 version: 1
-updated: '2026-06-16'
+updated: '2026-07-06'
 domain: helix_forge
-capabilities: []
+capabilities:
+- id: capability.agents.kaizen-framework
+  name: Kaizen Agentic Framework
+  summary: AI agency framework providing 18 specialized deployable agent instruction sets plus persistent,
+    project-scoped memory and cross-agent coordination via a Coach meta-agent.
+  vector: D3 / A2 / C1 / R0
+  domain: agents
+  status: draft
+  owner: kaizen-agentic
+  path: registry/capabilities/capability.agents.kaizen-framework.md
+  tags:
+  - agents
+  - memory
+  - coordination
+  consumption_modes:
+  - cli
+  - library import

src/kaizen_agentic/cli.py

@@ -23,6 +23,7 @@ from .integrations.event_bus import (
 from .integrations.helix import HelixCorrelationAdapter, enrich_helix_correlation
 from .metrics import MetricsStore, OptimizerStore, performance_summary_markdown
 from .optimization import OptimizationLoop, MIN_SAMPLES_FOR_RECOMMENDATIONS
+from .engagement_promote import promote_engagement
 from .schedule import (
     ScheduleError,
     default_schedule_yaml,
@@ -1534,6 +1535,105 @@ def schedule_init(
     click.echo("  Validate with: kaizen-agentic schedule validate")
 
 
+@schedule.command("promote")
+@click.option(
+    "--engagement-repo",
+    "-e",
+    required=True,
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    help="Customer engagement repo (e.g. coulomb-loop)",
+)
+@click.option(
+    "--engagement",
+    default="coulomb-loop",
+    show_default=True,
+    help="Engagement slug written into fleet schedule.yml headers",
+)
+@click.option(
+    "--to-phase",
+    type=click.Choice(["stabilize", "operate"]),
+    default=None,
+    help="Target phase (default: next phase after current)",
+)
+@click.option("--loop", default=None, help="Promote a single loop id only")
+@click.option("--dry-run", is_flag=True, help="Print planned actions without writing")
+@click.option("--skip-cadence", is_flag=True, help="Skip loops/*/cadence.yml updates")
+@click.option(
+    "--skip-definitions", is_flag=True, help="Skip activity-definitions transforms"
+)
+@click.option("--skip-fleet", is_flag=True, help="Skip .kaizen/schedule.yml on roster")
+@click.option("--skip-sync", is_flag=True, help="Skip activity-core definition sync")
+@click.option(
+    "--fleet-only",
+    is_flag=True,
+    help="Only update fleet schedule.yml (+ sync unless --skip-sync)",
+)
+@click.option(
+    "--activity-core",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=None,
+    help="activity-core repo root (or ACTIVITY_CORE_ROOT env)",
+)
+def schedule_promote(
+    engagement_repo: Path,
+    engagement: str,
+    to_phase: Optional[str],
+    loop: Optional[str],
+    dry_run: bool,
+    skip_cadence: bool,
+    skip_definitions: bool,
+    skip_fleet: bool,
+    skip_sync: bool,
+    fleet_only: bool,
+    activity_core: Optional[Path],
+):
+    """Atomically promote cadence across cadence.yml, definitions, fleet, and sync."""
+    if fleet_only:
+        skip_cadence = True
+        skip_definitions = True
+        if to_phase is None:
+            to_phase = "operate"
+
+    result = promote_engagement(
+        engagement_repo,
+        engagement_slug=engagement,
+        to_phase=to_phase,
+        loop=loop,
+        dry_run=dry_run,
+        skip_cadence=skip_cadence,
+        skip_definitions=skip_definitions,
+        skip_fleet=skip_fleet,
+        skip_sync=skip_sync,
+        activity_core_root=activity_core,
+    )
+
+    if dry_run:
+        click.echo("Dry run — planned actions:")
+    else:
+        click.echo("Promotion complete — actions:")
+
+    by_layer: dict[str, list[str]] = {}
+    for action in result.actions:
+        by_layer.setdefault(action.layer, []).append(action.description)
+
+    for layer in ("cadence", "definitions", "fleet", "sync"):
+        items = by_layer.get(layer)
+        if items:
+            click.echo(f"\n[{layer}]")
+            for item in items:
+                click.echo(f"  • {item}")
+
+    if result.errors:
+        click.echo("\nWarnings / errors:", err=True)
+        for err in result.errors:
+            click.echo(f"  ! {err}", err=True)
+        if not result.actions:
+            sys.exit(1)
+
+    if not result.actions and not result.errors:
+        click.echo("Nothing to do — layers already aligned.")
+
+
 @schedule.command("list")
 @click.option("--target", "-t", default=".", help="Project root (default: current)")
 @click.option("--all", "show_all", is_flag=True, help="Include disabled entries")
@@ -1604,10 +1704,12 @@ def _build_prepare_bundle(agent_name: str, project_root: Path) -> dict:
         metrics_summary = metrics_store.write_summary()
 
     pointers = {}
-    for label, filename in (("scope", "SCOPE.md"), ("todo", "TODO.md")):
-        candidate = project_root / filename
-        if candidate.exists():
-            pointers[label] = str(candidate)
+    scope_path = project_root / "SCOPE.md"
+    if scope_path.exists():
+        pointers["scope"] = str(scope_path)
+    workplans_path = project_root / "workplans"
+    if workplans_path.is_dir():
+        pointers["workplans"] = str(workplans_path)
 
     return {
         "agent": agent_name,
@@ -1662,7 +1764,7 @@ def _render_prepare_markdown(bundle: dict) -> str:
         for label, path in pointers.items():
             lines.append(f"- {label}: {path}")
     else:
-        lines.append("- (no SCOPE.md / TODO.md found)")
+        lines.append("- (no SCOPE.md / workplans/ found)")
     lines.append("")
 
     lines.append("## Session Close")

src/kaizen_agentic/engagement_promote.py

@@ -0,0 +1,555 @@
+"""Atomic cadence promotion across engagement contract layers (ADR-003).
+
+Orchestrates three layers that must stay aligned on promotion:
+
+1. Customer policy — ``loops/*/cadence.yml`` in the engagement repo
+2. Scheduler contract — ``activity-definitions/*.md`` → activity-core sync
+3. Fleet opt-in — ``.kaizen/schedule.yml`` on roster target repos
+
+See coulomb-loop ADR-002 / ADR-003 and supplier customer-engagement-playbook.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from dataclasses import dataclass, field
+from datetime import date
+from pathlib import Path
+from typing import Any, Callable
+
+import yaml
+
+from .schedule import ScheduleError, engagement_schedule_yaml, schedule_path
+
+PHASE_ORDER = ("bootstrap", "stabilize", "operate")
+PHASE_FILE_PREFIX = {
+    "bootstrap": "hourly",
+    "stabilize": "daily",
+    "operate": "weekly",
+}
+CADENCE_ENUM = {
+    "bootstrap": "daily",  # hourly crons keep daily enum for resolver filter
+    "stabilize": "daily",
+    "operate": "weekly",
+}
+
+LOOP_DIR_BY_ID = {
+    "kaizen-improvement-stack": "kaizen-stack",
+    "quality-escalation": "quality-escalation",
+    "registry-hygiene": "registry-hygiene",
+    "loop-regulator": "regulator",
+}
+
+# Activity-definition stems per loop (without phase prefix). Crons come from
+# operate_target in cadence.yml when present, else these defaults.
+DEFAULT_OPERATE_CRONS: dict[str, dict[str, str]] = {
+    "kaizen-improvement-stack": {
+        "metrics-optimize": "0 8 * * 1",
+        "coach-orientation": "0 9 * * 1",
+        "optimization-review": "0 10 * * 1",
+    },
+    "registry-hygiene": {
+        "registry-hygiene-sweep": "0 9 * * 1",
+    },
+    "quality-escalation": {
+        "metrics-health-sweep": "0 6 * * 1",
+    },
+    "loop-regulator": {
+        "loop-health-collector": "0 11 * * 1",
+    },
+}
+
+EVENT_DEFINITIONS = frozenset({"low-success-rate-review"})
+
+
+class PromoteError(Exception):
+    """Raised when promotion cannot proceed."""
+
+
+@dataclass
+class PromoteAction:
+    layer: str
+    description: str
+    path: str | None = None
+
+
+@dataclass
+class PromoteResult:
+    actions: list[PromoteAction] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+
+def _next_phase(current: str) -> str | None:
+    try:
+        idx = PHASE_ORDER.index(current)
+    except ValueError:
+        return None
+    if idx + 1 >= len(PHASE_ORDER):
+        return None
+    return PHASE_ORDER[idx + 1]
+
+
+def _loop_paths(engagement_repo: Path) -> dict[str, Path]:
+    loops_root = engagement_repo / "loops"
+    if not loops_root.is_dir():
+        raise PromoteError(f"loops/ not found under {engagement_repo}")
+    mapping: dict[str, Path] = {}
+    for loop_id, dirname in LOOP_DIR_BY_ID.items():
+        path = loops_root / dirname / "cadence.yml"
+        if path.is_file():
+            mapping[loop_id] = path
+    if not mapping:
+        raise PromoteError(f"no loops/*/cadence.yml found under {engagement_repo}")
+    return mapping
+
+
+def _load_yaml(path: Path) -> dict[str, Any]:
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise PromoteError(f"expected mapping in {path}")
+    return data
+
+
+def _write_yaml(path: Path, data: dict[str, Any]) -> None:
+    path.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
+
+
+def _split_markdown_frontmatter(text: str) -> tuple[dict[str, Any], str]:
+    if not text.startswith("---"):
+        raise PromoteError("activity definition missing YAML frontmatter")
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        raise PromoteError("activity definition frontmatter not closed")
+    meta = yaml.safe_load(parts[1])
+    if not isinstance(meta, dict):
+        raise PromoteError("activity definition frontmatter must be a mapping")
+    body = parts[2].lstrip("\n")
+    return meta, body
+
+
+def _render_markdown(meta: dict[str, Any], body: str) -> str:
+    header = yaml.safe_dump(meta, sort_keys=False)
+    return f"---\n{header}---\n\n{body}"
+
+
+def _roster_repos(engagement_repo: Path) -> list[tuple[str, Path, list[str]]]:
+    roster_path = engagement_repo / "loops" / "kaizen-stack" / "roster.yaml"
+    if not roster_path.is_file():
+        return []
+    data = _load_yaml(roster_path)
+    active = data.get("active") or []
+    repos: list[tuple[str, Path, list[str]]] = []
+    for entry in active:
+        if not isinstance(entry, dict):
+            continue
+        slug = str(entry.get("slug", ""))
+        root = entry.get("root")
+        agents = entry.get("agents") or ["coach", "optimization"]
+        if slug and root:
+            repos.append((slug, Path(str(root)), list(agents)))
+    return repos
+
+
+def _operate_crons(loop_id: str, cadence: dict[str, Any]) -> dict[str, str]:
+    target = cadence.get("operate_target")
+    crons = dict(DEFAULT_OPERATE_CRONS.get(loop_id, {}))
+    if not isinstance(target, dict):
+        return crons
+    if loop_id == "kaizen-improvement-stack":
+        chain = target.get("chain")
+        if isinstance(chain, dict):
+            for stem, cron_key in [
+                ("metrics-optimize", "metrics"),
+                ("coach-orientation", "coach"),
+                ("optimization-review", "optimization"),
+            ]:
+                if cron_key in chain:
+                    crons[stem] = str(chain[cron_key])
+    elif loop_id == "registry-hygiene" and "cron" in target:
+        crons["registry-hygiene-sweep"] = str(target["cron"])
+    elif loop_id == "quality-escalation" and "sweep_cron" in target:
+        crons["metrics-health-sweep"] = str(target["sweep_cron"])
+    elif loop_id == "loop-regulator":
+        if "collector_cron" in target:
+            crons["loop-health-collector"] = str(target["collector_cron"])
+    return crons
+
+
+def _apply_operate_target(
+    cadence: dict[str, Any], loop_id: str, promoted_at: str
+) -> None:
+    target = cadence.pop("operate_target", None)
+    cadence["phase"] = "operate"
+    cadence["promoted_at"] = promoted_at
+    if not isinstance(target, dict):
+        target = {}
+
+    if loop_id == "kaizen-improvement-stack":
+        chain = target.get("chain") or DEFAULT_OPERATE_CRONS[loop_id]
+        cadence["cron"] = chain.get("metrics", "0 8 * * 1")
+        cadence["chain"] = {
+            "metrics": chain.get("metrics", "0 8 * * 1"),
+            "coach": chain.get("coach", "0 9 * * 1"),
+            "optimization": chain.get("optimization", "0 10 * * 1"),
+        }
+    elif loop_id == "registry-hygiene":
+        cadence["cron"] = target.get("cron", "0 9 * * 1")
+        cadence["batch_size"] = target.get("batch_size", 2)
+        cadence["domain_rotation"] = target.get("domain_rotation", "weekly")
+    elif loop_id == "quality-escalation":
+        cadence["cron"] = target.get("sweep_cron", "0 6 * * 1")
+        cadence["sweep_fallback"] = "weekly-metrics-health-sweep"
+        cadence.pop("stabilize_target", None)
+    elif loop_id == "loop-regulator":
+        cron = target.get("collector_cron", "0 11 * * 1")
+        cadence["collector_cron"] = cron
+        cadence["regulator_session_cron"] = target.get("regulator_session_cron", cron)
+
+
+def _transform_definition(
+    path: Path,
+    from_prefix: str,
+    to_prefix: str,
+    cron: str,
+    cadence_enum: str,
+) -> Path:
+    meta, body = _split_markdown_frontmatter(path.read_text(encoding="utf-8"))
+    old_id = str(meta.get("id", ""))
+    stem = path.stem.removeprefix(f"{from_prefix}-")
+    new_id = f"coulomb-{to_prefix}-{stem.replace('-', '-')}"
+    if old_id.startswith("coulomb-"):
+        new_id = old_id.replace(f"coulomb-{from_prefix}-", f"coulomb-{to_prefix}-", 1)
+
+    meta["id"] = new_id
+    if isinstance(meta.get("name"), str):
+        meta["name"] = meta["name"].replace(from_prefix.title(), to_prefix.title())
+        meta["name"] = re.sub(
+            rf"\b{from_prefix}\b", to_prefix, meta["name"], flags=re.IGNORECASE
+        )
+
+    trigger = meta.get("trigger")
+    if isinstance(trigger, dict) and trigger.get("type") == "cron":
+        trigger["cron_expression"] = cron
+
+    for source in meta.get("context_sources") or []:
+        if isinstance(source, dict):
+            params = source.get("params")
+            if isinstance(params, dict) and "cadence" in params:
+                params["cadence"] = cadence_enum
+
+    body = body.replace(f"{from_prefix}-", f"{to_prefix}-")
+    body = re.sub(rf"\b{from_prefix}\b", to_prefix, body, flags=re.IGNORECASE)
+
+    dest = path.with_name(f"{to_prefix}-{stem}.md")
+    dest.write_text(_render_markdown(meta, body), encoding="utf-8")
+    if dest != path:
+        path.unlink()
+    return dest
+
+
+def _promote_definitions(
+    engagement_repo: Path,
+    from_phase: str,
+    to_phase: str,
+    loop_crons: dict[str, dict[str, str]],
+    *,
+    dry_run: bool,
+    result: PromoteResult,
+) -> None:
+    from_prefix = PHASE_FILE_PREFIX[from_phase]
+    to_prefix = PHASE_FILE_PREFIX[to_phase]
+    cadence_enum = CADENCE_ENUM[to_phase]
+    defs_dir = engagement_repo / "activity-definitions"
+    if not defs_dir.is_dir():
+        raise PromoteError(f"activity-definitions/ not found under {engagement_repo}")
+
+    for loop_id, crons in loop_crons.items():
+        for stem, cron in crons.items():
+            src = defs_dir / f"{from_prefix}-{stem}.md"
+            if not src.is_file():
+                result.errors.append(f"missing definition file: {src}")
+                continue
+            dest = defs_dir / f"{to_prefix}-{stem}.md"
+            result.actions.append(
+                PromoteAction(
+                    layer="definitions",
+                    description=f"{src.name} → {dest.name} (cron {cron})",
+                    path=str(src),
+                )
+            )
+            if dry_run:
+                continue
+            _transform_definition(src, from_prefix, to_prefix, cron, cadence_enum)
+
+    # Update event-definition fallback references
+    for name in EVENT_DEFINITIONS:
+        path = defs_dir / f"{name}.md"
+        if not path.is_file():
+            continue
+        text = path.read_text(encoding="utf-8")
+        new_text = text.replace(
+            f"{from_prefix}-metrics-health-sweep",
+            f"{to_prefix}-metrics-health-sweep",
+        )
+        new_text = new_text.replace(
+            f"`0 6 * * *`",
+            f"`{loop_crons.get('quality-escalation', {}).get('metrics-health-sweep', '0 6 * * 1')}`",
+        )
+        if new_text != text:
+            result.actions.append(
+                PromoteAction(
+                    layer="definitions",
+                    description=f"update fallback reference in {path.name}",
+                    path=str(path),
+                )
+            )
+            if not dry_run:
+                path.write_text(new_text, encoding="utf-8")
+
+
+def _promote_cadence_files(
+    engagement_repo: Path,
+    to_phase: str,
+    *,
+    loop_filter: str | None,
+    dry_run: bool,
+    result: PromoteResult,
+) -> dict[str, dict[str, str]]:
+    if to_phase != "operate":
+        raise PromoteError(f"promotion to '{to_phase}' not implemented yet")
+
+    promoted_at = date.today().isoformat()
+    loop_crons: dict[str, dict[str, str]] = {}
+    for loop_id, path in _loop_paths(engagement_repo).items():
+        if loop_filter and loop_filter != loop_id:
+            continue
+        data = _load_yaml(path)
+        current = str(data.get("phase", ""))
+        if current == to_phase:
+            loop_crons[loop_id] = _operate_crons(loop_id, data)
+            continue
+        if current != "stabilize":
+            result.errors.append(
+                f"{loop_id}: cannot promote from phase '{current}' to '{to_phase}'"
+            )
+            continue
+        loop_crons[loop_id] = _operate_crons(loop_id, data)
+        result.actions.append(
+            PromoteAction(
+                layer="cadence",
+                description=f"{path.relative_to(engagement_repo)}: {current} → {to_phase}",
+                path=str(path),
+            )
+        )
+        if dry_run:
+            continue
+        _apply_operate_target(data, loop_id, promoted_at)
+        _write_yaml(path, data)
+
+    roster_path = engagement_repo / "loops" / "kaizen-stack" / "roster.yaml"
+    if roster_path.is_file() and (
+        loop_filter is None or loop_filter == "kaizen-improvement-stack"
+    ):
+        roster = _load_yaml(roster_path)
+        if roster.get("phase") != to_phase:
+            result.actions.append(
+                PromoteAction(
+                    layer="cadence",
+                    description=f"roster.yaml phase → {to_phase}",
+                    path=str(roster_path),
+                )
+            )
+            if not dry_run:
+                roster["phase"] = to_phase
+                _write_yaml(roster_path, roster)
+
+    return loop_crons
+
+
+def _sync_roster_phase(
+    engagement_repo: Path,
+    to_phase: str,
+    *,
+    dry_run: bool,
+    result: PromoteResult,
+) -> None:
+    roster_path = engagement_repo / "loops" / "kaizen-stack" / "roster.yaml"
+    if not roster_path.is_file():
+        return
+    roster = _load_yaml(roster_path)
+    if roster.get("phase") == to_phase:
+        return
+    result.actions.append(
+        PromoteAction(
+            layer="cadence",
+            description=f"roster.yaml phase → {to_phase}",
+            path=str(roster_path),
+        )
+    )
+    if not dry_run:
+        roster["phase"] = to_phase
+        _write_yaml(roster_path, roster)
+
+
+def _promote_fleet(
+    engagement_repo: Path,
+    engagement_slug: str,
+    to_phase: str,
+    *,
+    dry_run: bool,
+    result: PromoteResult,
+) -> None:
+    if to_phase != "operate":
+        return
+    _sync_roster_phase(engagement_repo, to_phase, dry_run=dry_run, result=result)
+    for slug, root, agents in _roster_repos(engagement_repo):
+        if not root.is_dir():
+            result.errors.append(f"fleet repo root missing: {root} ({slug})")
+            continue
+        sched = schedule_path(root)
+        result.actions.append(
+            PromoteAction(
+                layer="fleet",
+                description=f"{slug}: .kaizen/schedule.yml → weekly ({', '.join(agents)})",
+                path=str(sched),
+            )
+        )
+        if dry_run:
+            continue
+        yaml_text = engagement_schedule_yaml(
+            engagement_slug,
+            agents=agents,
+            bootstrap_cadence="weekly",
+        )
+        sched.parent.mkdir(parents=True, exist_ok=True)
+        sched.write_text(yaml_text, encoding="utf-8")
+
+
+def _sync_activity_core(
+    engagement_repo: Path,
+    activity_core_root: Path | None,
+    *,
+    dry_run: bool,
+    result: PromoteResult,
+) -> None:
+    ac_root = activity_core_root or Path(os.environ.get("ACTIVITY_CORE_ROOT", ""))
+    if not ac_root or not (ac_root / "src" / "activity_core").is_dir():
+        result.errors.append(
+            "activity-core root not found (set --activity-core or ACTIVITY_CORE_ROOT)"
+        )
+        return
+    if not os.environ.get("ACTCORE_DB_URL"):
+        result.errors.append("ACTCORE_DB_URL not set — skip sync or configure database")
+        return
+
+    cmd = ["uv", "run", "python", "-m", "activity_core.sync_activity_definitions"]
+    result.actions.append(
+        PromoteAction(
+            layer="sync",
+            description="activity-core sync_activity_definitions",
+            path=str(ac_root),
+        )
+    )
+    if dry_run:
+        return
+    env = os.environ.copy()
+    env["ACTIVITY_DEFINITION_DIRS"] = str(engagement_repo.resolve())
+    subprocess.run(cmd, cwd=ac_root, env=env, check=True)
+
+
+def promote_engagement(
+    engagement_repo: Path,
+    *,
+    engagement_slug: str = "coulomb-loop",
+    to_phase: str | None = None,
+    loop: str | None = None,
+    dry_run: bool = False,
+    skip_cadence: bool = False,
+    skip_definitions: bool = False,
+    skip_fleet: bool = False,
+    skip_sync: bool = False,
+    activity_core_root: Path | None = None,
+) -> PromoteResult:
+    """Run atomic cadence promotion (or dry-run plan)."""
+    engagement_repo = engagement_repo.resolve()
+    result = PromoteResult()
+
+    if not engagement_repo.is_dir():
+        result.errors.append(f"engagement repo not found: {engagement_repo}")
+        return result
+
+    # Resolve target phase from first loop if not specified
+    if to_phase is None:
+        for path in _loop_paths(engagement_repo).values():
+            data = _load_yaml(path)
+            nxt = _next_phase(str(data.get("phase", "bootstrap")))
+            if nxt:
+                to_phase = nxt
+                break
+        if to_phase is None:
+            result.errors.append("could not infer target phase (all loops at operate?)")
+            return result
+
+    loop_crons: dict[str, dict[str, str]] = {}
+    from_phase = (
+        PHASE_ORDER[PHASE_ORDER.index(to_phase) - 1]
+        if to_phase in PHASE_ORDER[1:]
+        else "stabilize"
+    )
+
+    try:
+        if not skip_cadence:
+            loop_crons = _promote_cadence_files(
+                engagement_repo,
+                to_phase,
+                loop_filter=loop,
+                dry_run=dry_run,
+                result=result,
+            )
+        else:
+            for loop_id, path in _loop_paths(engagement_repo).items():
+                if loop and loop != loop_id:
+                    continue
+                loop_crons[loop_id] = _operate_crons(loop_id, _load_yaml(path))
+
+        if (
+            not skip_definitions
+            and from_phase in PHASE_FILE_PREFIX
+            and to_phase in PHASE_FILE_PREFIX
+        ):
+            if from_phase != to_phase:
+                _promote_definitions(
+                    engagement_repo,
+                    from_phase,
+                    to_phase,
+                    loop_crons,
+                    dry_run=dry_run,
+                    result=result,
+                )
+
+        if not skip_fleet:
+            _promote_fleet(
+                engagement_repo,
+                engagement_slug,
+                to_phase,
+                dry_run=dry_run,
+                result=result,
+            )
+
+        if not skip_sync:
+            _sync_activity_core(
+                engagement_repo,
+                activity_core_root,
+                dry_run=dry_run,
+                result=result,
+            )
+    except (PromoteError, ScheduleError, subprocess.CalledProcessError) as exc:
+        result.errors.append(str(exc))
+
+    return result

tests/test_engagement_promote.py

@@ -0,0 +1,161 @@
+"""Tests for atomic engagement cadence promotion."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from click.testing import CliRunner
+
+from kaizen_agentic.cli import cli
+from kaizen_agentic.engagement_promote import promote_engagement
+from kaizen_agentic.schedule import schedule_path
+
+
+def _write_cadence(
+    repo: Path,
+    loop_dir: str,
+    loop_id: str,
+    phase: str,
+    *,
+    with_operate_target: bool = True,
+) -> None:
+    data: dict = {"loop": loop_id, "phase": phase, "regulator_approval": "approved"}
+    if phase == "stabilize" and with_operate_target:
+        if loop_id == "kaizen-improvement-stack":
+            data["operate_target"] = {
+                "phase": "operate",
+                "chain": {
+                    "metrics": "0 8 * * 1",
+                    "coach": "0 9 * * 1",
+                    "optimization": "0 10 * * 1",
+                },
+            }
+        elif loop_id == "registry-hygiene":
+            data["operate_target"] = {
+                "phase": "operate",
+                "cron": "0 9 * * 1",
+                "batch_size": 2,
+            }
+    path = repo / "loops" / loop_dir / "cadence.yml"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
+
+
+def _write_definition(repo: Path, name: str, cron: str, cadence: str) -> None:
+    defs_dir = repo / "activity-definitions"
+    defs_dir.mkdir(parents=True, exist_ok=True)
+    stem = name.removeprefix("daily-")
+    content = f"""---
+id: coulomb-daily-{stem}
+name: Daily test {stem}
+enabled: true
+trigger:
+  type: cron
+  cron_expression: "{cron}"
+context_sources:
+  - type: kaizen
+    query: discover_kaizen_scheduled_repos
+    params:
+      cadence: {cadence}
+---
+
+# Daily {stem}
+"""
+    (repo / "activity-definitions" / name).write_text(content, encoding="utf-8")
+
+
+def _engagement_fixture(tmp_path: Path) -> Path:
+    repo = tmp_path / "coulomb-loop"
+    repo.mkdir()
+    _write_cadence(repo, "kaizen-stack", "kaizen-improvement-stack", "stabilize")
+    _write_cadence(repo, "registry-hygiene", "registry-hygiene", "stabilize")
+    _write_definition(repo, "daily-coach-orientation.md", "0 9 * * *", "daily")
+    _write_definition(repo, "daily-metrics-optimize.md", "0 8 * * *", "daily")
+    _write_definition(repo, "daily-optimization-review.md", "0 10 * * *", "daily")
+    _write_definition(repo, "daily-registry-hygiene-sweep.md", "0 7 * * *", "daily")
+
+    roster = {
+        "version": "1",
+        "loop": "kaizen-improvement-stack",
+        "phase": "bootstrap",
+        "active": [
+            {
+                "slug": "pilot-a",
+                "root": str(tmp_path / "pilot-a"),
+                "agents": ["coach", "optimization"],
+            }
+        ],
+    }
+    roster_path = repo / "loops" / "kaizen-stack" / "roster.yaml"
+    roster_path.parent.mkdir(parents=True, exist_ok=True)
+    roster_path.write_text(yaml.safe_dump(roster, sort_keys=False), encoding="utf-8")
+    (tmp_path / "pilot-a").mkdir()
+    return repo
+
+
+class TestEngagementPromote:
+    def test_dry_run_lists_all_layers(self, tmp_path: Path) -> None:
+        repo = _engagement_fixture(tmp_path)
+        result = promote_engagement(
+            repo,
+            to_phase="operate",
+            dry_run=True,
+            skip_sync=True,
+        )
+        layers = {a.layer for a in result.actions}
+        assert "cadence" in layers
+        assert "definitions" in layers
+        assert "fleet" in layers
+        assert result.ok
+
+    def test_promote_updates_cadence_and_definitions(self, tmp_path: Path) -> None:
+        repo = _engagement_fixture(tmp_path)
+        result = promote_engagement(
+            repo,
+            to_phase="operate",
+            skip_fleet=True,
+            skip_sync=True,
+        )
+        assert result.ok
+        cadence = yaml.safe_load(
+            (repo / "loops" / "kaizen-stack" / "cadence.yml").read_text()
+        )
+        assert cadence["phase"] == "operate"
+        assert "operate_target" not in cadence
+        assert (repo / "activity-definitions" / "weekly-coach-orientation.md").is_file()
+        assert not (
+            repo / "activity-definitions" / "daily-coach-orientation.md"
+        ).is_file()
+
+    def test_fleet_only_writes_schedule(self, tmp_path: Path) -> None:
+        repo = _engagement_fixture(tmp_path)
+        # Pre-promote cadence so fleet-only path applies
+        promote_engagement(repo, to_phase="operate", skip_fleet=True, skip_sync=True)
+        result = promote_engagement(
+            repo,
+            to_phase="operate",
+            skip_cadence=True,
+            skip_definitions=True,
+            skip_sync=True,
+        )
+        sched = schedule_path(tmp_path / "pilot-a")
+        assert sched.is_file()
+        assert "cadence: weekly" in sched.read_text()
+
+    def test_cli_fleet_only(self, tmp_path: Path) -> None:
+        repo = _engagement_fixture(tmp_path)
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "schedule",
+                "promote",
+                "--engagement-repo",
+                str(repo),
+                "--fleet-only",
+                "--skip-sync",
+            ],
+        )
+        assert result.exit_code == 0, result.output
+        assert "[fleet]" in result.output

uv.lock

@@ -805,7 +805,7 @@ wheels = [
 
 [[package]]
 name = "kaizen-agentic"
-version = "1.3.0"
+version = "1.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "click", version = "8.1.8", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.10'" },
@@ -835,6 +835,9 @@ dev = [
     { name = "pytest-cov", version = "5.0.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.9'" },
     { name = "pytest-cov", version = "7.1.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.9'" },
 ]
+events = [
+    { name = "nats-py" },
+]
 test = [
     { name = "pytest", version = "8.3.5", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.9'" },
     { name = "pytest", version = "8.4.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.9.*'" },
@@ -852,6 +855,7 @@ requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
     { name = "flake8", marker = "extra == 'dev'", specifier = ">=5.0.0" },
     { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.0.0" },
+    { name = "nats-py", marker = "extra == 'events'", specifier = ">=2.6.0" },
     { name = "pre-commit", marker = "extra == 'dev'", specifier = ">=2.20.0" },
     { name = "pydantic", specifier = ">=2.0.0" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=6.0.0" },
@@ -1149,6 +1153,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/79/7b/2c79738432f5c924bef5071f933bcc9efd0473bac3b4aa584a6f7c1c8df8/mypy_extensions-1.1.0-py3-none-any.whl", hash = "sha256:1be4cccdb0f2482337c4743e60421de3a356cd97508abadd57d47403e94f5505", size = 4963 },
 ]
 
+[[package]]
+name = "nats-py"
+version = "2.15.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/02/f0/fc5e93f2b0dd14a202590ad9d30eda1955ea872039b5204357348d0f4b1e/nats_py-2.15.0.tar.gz", hash = "sha256:6622c547d9a7d2313d9c147d46c386188f4ec2c7b5c9f9a0438a4d1b55f54a93", size = 75995 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/db/a8/b55606c7c621fb813c8ec78baf201d2c78bf6051091ec0c7ada572999e95/nats_py-2.15.0-py3-none-any.whl", hash = "sha256:9f8d36aa52a9926a88b8f1d70cf1fdce0ad387941479b500ee9ab3e51073cefd", size = 90334 },
+]
+
 [[package]]
 name = "nodeenv"
 version = "1.10.0"

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.

workplans/kaizen-agentic-WP-0001-community-engagement.md

@@ -2,7 +2,7 @@
 id: KAIZEN-WP-0001
 type: workplan
 title: "Community Engagement and Advanced Automation (v1.1.0)"
-domain: custodian
+domain: agents
 repo: kaizen-agentic
 status: completed
 owner: kaizen-agentic

workplans/kaizen-agentic-WP-0002-agency-framework.md

@@ -2,7 +2,7 @@
 id: KAIZEN-WP-0002
 type: workplan
 title: "Agency Framework: Project Memory, Coaching, and sys-medic Integration"
-domain: custodian
+domain: agents
 repo: kaizen-agentic
 status: done
 owner: kaizen-agentic

workplans/kaizen-agentic-WP-0003-measurement-loop.md

@@ -2,7 +2,7 @@
 id: KAIZEN-WP-0003
 type: workplan
 title: "Measurement Loop: Metrics Convention, Collection, and Optimizer Integration"
-domain: custodian
+domain: agents
 repo: kaizen-agentic
 status: completed
 owner: kaizen-agentic

workplans/kaizen-agentic-WP-0004-ecosystem-integration.md

@@ -2,7 +2,7 @@
 id: KAIZEN-WP-0004
 type: workplan
 title: "Ecosystem Integration: Helix Forge, activity-core, and artifact-store"
-domain: custodian
+domain: agents
 repo: kaizen-agentic
 status: completed
 owner: kaizen-agentic

workplans/kaizen-agentic-WP-0005-adoption-parity.md

@@ -2,7 +2,7 @@
 id: KAIZEN-WP-0005
 type: workplan
 title: "Adoption Polish and Fleet Parity (v1.2.0)"
-domain: custodian
+domain: agents
 repo: kaizen-agentic
 status: completed
 owner: kaizen-agentic

workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md

@@ -2,7 +2,7 @@
 id: KAIZEN-WP-0006
 type: workplan
 title: "Scheduled Agent Execution via activity-core (v1.3.0)"
-domain: custodian
+domain: agents
 repo: kaizen-agentic
 status: done
 owner: kaizen-agentic
@@ -85,8 +85,7 @@ tasks:
 - id: T18
   state_hub_task_id: 73986472-bf19-4b13-af1b-6505ab944459
   status: done
-  title: Update wiki/EcosystemIntegration.md and CHANGELOG for v1.3.0
----
+  title: Update wiki/EcosystemIntegration.md and CHANGELOG for v1.3.0---
 
 # KAIZEN-WP-0006 — Scheduled Agent Execution via activity-core
 
@@ -130,7 +129,6 @@ flowchart LR
 
 Kaizen-agentic does **not** invoke Claude directly; it **prepares** and **validates**
 the scheduled run contract.
-
 ---
 
 ## Background

workplans/kaizen-agentic-WP-0007-agent-authoring-doc-generation.md

@@ -2,7 +2,7 @@
 id: KAIZEN-WP-0007
 type: workplan
 title: "Agent Authoring & Doc Generation (v1.4.0)"
-domain: custodian
+domain: agents
 repo: kaizen-agentic
 status: done
 owner: kaizen-agentic
@@ -36,8 +36,7 @@ tasks:
 - id: T06
   state_hub_task_id: 6715aa6f-1ee0-4f22-9249-f1cd41763cd1
   status: done
-  title: Docs, CLI cheat sheet, CHANGELOG for v1.4.0
----
+  title: Docs, CLI cheat sheet, CHANGELOG for v1.4.0---
 
 # KAIZEN-WP-0007 — Agent Authoring & Doc Generation
 

workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md

@@ -2,9 +2,9 @@
 id: KAIZEN-WP-0008
 type: workplan
 title: "Coulomb-loop supplier engagement (customer-repo playbook)"
-domain: custodian
+domain: agents
 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"
 ```
@@ -120,7 +120,7 @@ No code — layout contract only.
 
 ```task
 id: KAIZEN-WP-0008-T02
-status: todo
+status: done
 priority: high
 state_hub_task_id: "90bd0fc2-6e49-4a59-9a78-91e749cef8a6"
 ```
@@ -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"
 ```