docs: ADR-007 and FDA playbook; finish WP-0009 (T11)
Some checks failed
CI Smoke / host-smoke (push) Successful in 1s
CI Smoke / container-smoke (push) Successful in 1m12s
ci / test (push) Has been cancelled

Absorb railiance01 pilot supplier notes into the forward-deployed engagement
playbook, accept ADR-007 elevating DEC-FDA-001, promote architecture and
business model to v1.0, and mark KAIZEN-WP-0009 finished.
This commit is contained in:
tegwick 2026-07-16 12:44:56 +02:00
parent 6ca167ce19
commit 97d0739537
9 changed files with 366 additions and 21 deletions

View file

@ -12,10 +12,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
`keepaTodofile` agent remains available for other projects
### Added
- **`engagement` CLI (WP-0009 T08T09)** — forward-deployed engagement lifecycle:
`list`/`show`/`validate`/`checklist`/`phase`/`prepare`/`staff`/`quote`/
`scrub`/`export-handoff`/`close-session` over file-based pilots
(`engagements/pilots/`); close-session wires vault log, metrics, and Kai ledger
- **Forward-deployed agency (WP-0009)** — staffed Role engagements with Kai trial
currency, client vaults, ramp-up/down; pilot host-operator @ railiance01
- **ADR-007** — forward-deployed engagement convention; playbook
`docs/integrations/forward-deployed-engagement-playbook.md`
- **`roles/host-operator`** — Role package (sys-medic craft base)
- **`engagement` CLI** — `list`/`show`/`validate`/`checklist`/`phase`/`prepare`/
`staff`/`quote`/`scrub`/`export-handoff`/`close-session` over
`engagements/pilots/`; close-session wires vault log, metrics, and Kai ledger
- **`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]'`)

View file

@ -0,0 +1,156 @@
# ADR-007: Forward-Deployed Engagement Convention
**Status:** accepted
**Date:** 2026-07-16
**Deciders:** kaizen-agentic maintainers (supplier)
**Workplan:** KAIZEN-WP-0009
**Supersedes for staffing model:** none (complements ADR-006)
**Prior working defaults:** [DEC-FDA-001](../decisions/DEC-FDA-001-working-defaults.md)
## Context
kaizen-agentic evolved from installing coding personas into repos into an
**agentic consulting / forward-deployed agency**: clients request a **Role**,
receive a bound agent definition, and run engagements with ramp-up / operate /
ramp-down while keeping operational knowledge **client-confidential**.
ADR-006 covers **improvement-loop** customer repos (rosters, activity-core
cadence). It does not define:
- Role product packages
- Engagement lifecycle and checklists
- Client vault custody vs supplier craft
- Trial currency (Kai) settlement files
- Host/operator-style Targets (not only git repos)
The railiance01 host-operator pilot (KAIZEN-WP-0009) proved a file-based Phase 1
path. We lock the convention so the next engagement does not re-invent structure.
## Decision
### 1. Two engagement kinds (both valid)
| Kind | Primary artifact | ADR |
|------|------------------|-----|
| **Loop engagement** | Customer loop repo + fleet `.kaizen/schedule.yml` | ADR-006 |
| **Staffed Role engagement** | `engagements/` tree + bound agent + vault | **this ADR** |
A client may run both. They share CLI primitives, confidentiality principles,
and metrics habits, but different primary trees.
### 2. Ownership planes
| Plane | Owner | Contents |
|-------|-------|----------|
| Role package | Supplier (`roles/<role-id>/`) | Prompt craft, protocols, ramp checklists, billing hints |
| Engagement record + bound definition | Client custody (pilot may live under supplier `engagements/pilots/` until exported) | Targets, phase, policy, schedule |
| Engagement vault | **Client confidential** | Memory, baselines, findings, handoff |
| Kai ledger | Settlement (Phase 1: file JSONL under engagement) | Billing metadata only — no secrets |
| Scrubbed lessons | Supplier only after client `contribute_lesson: approved` | Role craft improvements |
### 3. Filesystem layout (Phase 1)
```
roles/<role-id>/
ROLE.yaml
agent-definition.md
memory-template.md
ramp-up.md
ramp-down.md
protocols/
engagements/pilots/<engagement-id>/ # or client-owned path later
ENGAGEMENT.yaml
agent-*.md
access-plan.md
schedule.yml
request.yaml
checklists/
vault/
reports/
commercial/
```
### 4. Lifecycle phases
```
requested → quoting → funded → staffing → ramp_up → operating ⇄ renewing
→ ramp_down → closed
```
Illegal transitions require `--force` (CLI). Ramp-up and ramp-down have
checklist exit criteria (RU-*, RD-*).
### 5. CLI surface
```bash
kaizen-agentic engagement list|show|validate|checklist|phase|prepare|staff
kaizen-agentic engagement close-session|quote|scrub|export-handoff
```
- `prepare` — offline session bundle (no LLM invoke)
- `close-session` — vault log + engagement-scoped metrics + Kai ledger + report
- `scrub` — heuristic gate before any lesson contribution
### 6. Access and privilege
- Credential routing remains ops-warden / OpenBao / ops-bridge (never invent secrets)
- Observe-class work may proceed with verified SSH
- `privileged_ops`, `package_upgrade`, `firewall_change`, `reboot` require
**recorded human approval** in the vault before execution
- Dry-run privileged proposals satisfy ramp-up “approval path tested” (RU-08)
### 7. Metrics placement for staffed engagements
Metrics for a staffed Role duty are stored **under the engagement tree**
(`.kaizen/metrics/<role>/`) so they travel with client vault custody, not the
supplier monorepos global project metrics by default.
### 8. Kai trial currency
Phase 1 settles in **Kai** (file ledger). Seat/duty catalog and FX conversion
rules live in the business model wiki. Empty balance pauses new duties; ramp-down
always allowed.
### 9. Relation to DEC-FDA-001
DEC-FDA-001 working defaults are **elevated** into this ADR. Future overrides
should amend this ADR (or a successor), not re-open DEC-FDA-001 silently.
## Consequences
### Positive
- Second staffed engagement can copy `roles/` + `engagement staff` + RU/RD checklists
- Confidentiality boundary is structural, not only policy text
- Pilot railiance01 is the reference implementation path
### Negative / trade-offs
- Pilot vault currently sits in the supplier repo (`engagements/pilots/`) — must
still be treated as client confidential; export to client repo is recommended
before multi-tenant growth
- activity-core automation for host duties is optional Phase 3 (manual prepare OK)
- Kai is not a payment processor; EUR path remains future work
### Follow-ups
- Export pilot vault to client-owned path when railiance ops repo is ready
- Optional activity-core ActivityDefinitions for daily host-operator prepare
- EUR commercial FX after 23 engagement calibration cycles
## Pilot evidence
- Engagement: `engagements/pilots/eng-coulomb-railiance01-ho-001/`
- Role: `roles/host-operator/`
- Workplan: KAIZEN-WP-0009 (T01T11)
- Live ramp-up: 2026-07-16 (phase `operating`; Critical memory/load findings)
## Related
- [forward-deployed-engagement-architecture.md](../forward-deployed-engagement-architecture.md)
- [forward-deployed-engagement-playbook.md](../integrations/forward-deployed-engagement-playbook.md)
- [wiki/ForwardDeployedAgencyBusinessModel.md](../../wiki/ForwardDeployedAgencyBusinessModel.md)
- [ADR-006](ADR-006-customer-engagement-convention.md)
- [ADR-002](ADR-002-project-memory-convention.md)
- [ADR-005](ADR-005-scheduled-agent-execution.md)

View file

@ -346,7 +346,9 @@ Schema: [integrations/schedule-schema.md](integrations/schedule-schema.md).
- [ADR-004: Project Metrics Convention](adr/ADR-004-project-metrics-convention.md)
- [ADR-005: Scheduled Agent Execution](adr/ADR-005-scheduled-agent-execution.md)
- [ADR-006: Customer Engagement Convention](adr/ADR-006-customer-engagement-convention.md)
- [ADR-007: Forward-Deployed Engagement Convention](adr/ADR-007-forward-deployed-engagement-convention.md)
- [Forward-Deployed Engagement Architecture](forward-deployed-engagement-architecture.md) — client-requestable Roles, ramp-up/down, client vaults
- [Forward-Deployed Engagement Playbook](integrations/forward-deployed-engagement-playbook.md)
- [DEC-FDA-001 working defaults](decisions/DEC-FDA-001-working-defaults.md)
- [roles/host-operator](../roles/host-operator/) — first Role package (pilot)
- [engagements/pilots/eng-coulomb-railiance01-ho-001](../engagements/pilots/eng-coulomb-railiance01-ho-001/) — Phase 1 pilot tree

View file

@ -1,8 +1,8 @@
# DEC-FDA-001 — Forward-deployed agency working defaults
**Status:** accepted (working default; sponsor may override)
**Status:** accepted — elevated into [ADR-007](../adr/ADR-007-forward-deployed-engagement-convention.md)
**Date:** 2026-07-16
**Workplan:** KAIZEN-WP-0009-T02
**Workplan:** KAIZEN-WP-0009-T02 / T11
**Deciders:** kaizen-agentic (implementation default for Phase 1 pilot)
## Context
@ -70,6 +70,10 @@ Observe-class work does not.
- Architecture and business model docs promote to **v0.2 (working accepted)**
- ADR-007 may later elevate these defaults to fleet convention (T11)
## Elevation
T11 promoted these defaults into ADR-007. Amend ADR-007 for future changes.
## Related
- [forward-deployed-engagement-architecture.md](../forward-deployed-engagement-architecture.md)

View file

@ -1,10 +1,12 @@
# Forward-Deployed Engagement Architecture
**Status:** v0.2 working accepted (DEC-FDA-001 defaults)
**Status:** v1.0 accepted (ADR-007)
**Date:** 2026-07-16
**Type:** architecture extension (ADR-007 optional later — WP-0009 T11)
**Type:** architecture extension
**Canon ADR:** [ADR-007](adr/ADR-007-forward-deployed-engagement-convention.md)
**Companion business model:** [wiki/ForwardDeployedAgencyBusinessModel.md](../wiki/ForwardDeployedAgencyBusinessModel.md)
**Decisions:** [docs/decisions/DEC-FDA-001-working-defaults.md](decisions/DEC-FDA-001-working-defaults.md)
**Playbook:** [integrations/forward-deployed-engagement-playbook.md](integrations/forward-deployed-engagement-playbook.md)
**Decisions:** [docs/decisions/DEC-FDA-001-working-defaults.md](decisions/DEC-FDA-001-working-defaults.md) (elevated into ADR-007)
**Extends:** ADR-002 (memory), ADR-003 (protocols), ADR-005 (schedule), ADR-006 (customer engagement)
**Pilot tree:** `engagements/pilots/eng-coulomb-railiance01-ho-001/`
@ -701,6 +703,8 @@ Still open (non-blocking):
## Related documents
- [ADR-007](adr/ADR-007-forward-deployed-engagement-convention.md)
- [forward-deployed-engagement-playbook.md](integrations/forward-deployed-engagement-playbook.md)
- [DEC-FDA-001](decisions/DEC-FDA-001-working-defaults.md)
- [roles/host-operator](../roles/host-operator/)
- [pilot engagement](../engagements/pilots/eng-coulomb-railiance01-ho-001/)

View file

@ -1,10 +1,15 @@
# Customer Engagement Playbook v1 (supplier)
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)
How kaizen-agentic supports a **customer engagement repo** for **improvement
loops** (reference:
[coulomb-loop](https://gitea.coulomb.social/coulomb/coulomb-loop)). Second loop
engagements should copy [customer-engagement-repo-layout.md](customer-engagement-repo-layout.md)
and complete the checklist in one session.
**Staffed Role engagements** (host-operator, forward-deployed agency) use a
different tree — see [forward-deployed-engagement-playbook.md](forward-deployed-engagement-playbook.md)
and [ADR-007](../adr/ADR-007-forward-deployed-engagement-convention.md).
## Roles
| Repo | Role |

View file

@ -0,0 +1,160 @@
# Forward-Deployed Engagement Playbook v1 (supplier)
How to staff a **Role** for a client Target (host, cluster, product area) with
ramp-up / operate / ramp-down. Complements the **loop** playbook
([customer-engagement-playbook.md](customer-engagement-playbook.md) / ADR-006).
**Canon:** [ADR-007](../adr/ADR-007-forward-deployed-engagement-convention.md)
**Reference pilot:** `engagements/pilots/eng-coulomb-railiance01-ho-001/`
**Business model:** [wiki/ForwardDeployedAgencyBusinessModel.md](../../wiki/ForwardDeployedAgencyBusinessModel.md)
---
## When to use this playbook
| Situation | Use |
|-----------|-----|
| Client needs a named digital colleague on a duty (e.g. host operator) | **This playbook** |
| Client wants repo fleet coach/optimizer cadence | ADR-006 loop playbook |
| Both | Both trees; do not mix vaults |
---
## Bootstrap checklist (staffed Role)
### 1. Role package exists (supplier)
```
roles/<role-id>/ROLE.yaml
roles/<role-id>/agent-definition.md
roles/<role-id>/protocols/...
roles/<role-id>/ramp-up.md
roles/<role-id>/ramp-down.md
```
If missing: author Role from craft base (e.g. host-operator from sys-medic).
### 2. Staff engagement
```bash
kaizen-agentic engagement staff \
--id eng-<client>-<target>-<role-short> \
--role <role-id> \
--client <client-id> \
--target <target-id>
kaizen-agentic engagement validate eng-...
```
Or copy the pilot tree and edit `ENGAGEMENT.yaml`.
### 3. Fund / quote (Kai trial)
```bash
kaizen-agentic engagement quote eng-...
# fill commercial/quote.yaml; ledger starts empty or with quote_open note
```
### 4. Access plan (no secrets)
Document SSH alias, user, identity path, bridge tunnels, and verify:
```bash
ssh -o BatchMode=yes <host-alias> 'hostname; uptime'
```
Update `access-plan.md` verification log → mark **RU-01**.
### 5. Ramp-up
```bash
kaizen-agentic engagement phase eng-... --to ramp_up
kaizen-agentic engagement prepare eng-... > /tmp/prepare.md
# run observe session; write baseline + health report
kaizen-agentic engagement checklist eng-... --mark RU-02=done
# ... until RU complete
kaizen-agentic engagement phase eng-... --to operating
```
### 6. Session close (each duty)
```bash
kaizen-agentic engagement close-session eng-... \
--success --duty standard_review \
--summary "<one-line non-secret outcome>" \
--time <s> --quality <0-1> \
--access-class host_observe
```
### 7. Operate cadence
- Enable entries in engagement `schedule.yml` (manual prepare until activity-core)
- Daily: health + load; weekly: OS/security pass (privileged changes still gated)
### 8. Ramp-down (when ending)
```bash
kaizen-agentic engagement phase eng-... --to ramp_down
kaizen-agentic engagement export-handoff eng-...
# complete RD checklist; revoke access; phase closed
kaizen-agentic engagement phase eng-... --to closed
```
---
## Supplier notes — railiance01 host-operator pilot (absorbed 2026-07-16)
Friction and resolutions from `eng-coulomb-railiance01-ho-001` / KAIZEN-WP-0009.
| Observation | Resolution / guidance |
|-------------|----------------------|
| ADR-006 loop layout does not fit host staffing | ADR-007 + this playbook; separate `engagements/` tree |
| Open decisions blocked scaffolding | DEC-FDA-001 → elevated into ADR-007 |
| Forgejo git push intermittent (publickey / pre-receive) | Retry; keep commits local; hub task status can PATCH via API |
| SSH to forgejo `git@` failed; shell SSH as tegwick worked | Document **both** paths; access-plan records what actually works |
| warden inventory sparse vs bridge “connected” | Bridge may use static keys; do not block observe on warden cert status alone |
| Undersized host (2 core / 3.8G / no swap) for full stack | First duty may exit ramp-up with **Critical** health — still valid ramp-up if RU evidence complete |
| `k3s kubectl` ServiceUnavailable under memory pressure | Record as finding; avoid hammering API; re-sample after capacity relief |
| Nested `.kaizen/metrics` under engagement is correct for custody | Root `.gitignore` `.kaizen/metrics/` only ignores repo-root metrics; pilot metrics are commit-able |
| Privileged work tempting on Critical host | RU-08 = **proposal dry-run only** until human approval table filled |
| Pilot vault in supplier repo | Treat as client confidential; export to client ops repo before multi-tenant scale |
| activity-core not required for Phase 1 | Manual `prepare` + `close-session`; schedule.yml documents intent |
| Kai charges felt real only after close-session | Always close-session after live duties; quote alone is not spend |
| High load makes remote `du`/`apt` slow | Prefer short command batches; timeout ≥60s for full assessments |
### Reference commands (pilot)
```bash
kaizen-agentic engagement show eng-coulomb-railiance01-ho-001
kaizen-agentic engagement prepare eng-coulomb-railiance01-ho-001
ssh railiance01 'free -h; uptime; cat /proc/pressure/memory'
kaizen-agentic engagement close-session eng-coulomb-railiance01-ho-001 \
--success --duty standard_review --summary "..." --time 120 --quality 0.8
```
### Open human decisions from pilot (not supplier code)
1. Add RAM and/or temporary swap on railiance01
2. journald vacuum approval
3. Security package upgrade window
4. UFW source restriction for 6443/8472
---
## Optional activity-core wiring (Phase 3)
Not required for operate. When ready:
1. Customer or engagement repo owns ActivityDefinition copies that shell out to
`kaizen-agentic engagement prepare <id>` then start a coding-agent session
2. Resolver points at engagement id / host Target (new work — not WP-0009)
3. Keep privilege gates in the agent definition regardless of cron fire
---
## Related
- [ADR-007](../adr/ADR-007-forward-deployed-engagement-convention.md)
- [forward-deployed-engagement-architecture.md](../forward-deployed-engagement-architecture.md)
- [customer-engagement-playbook.md](customer-engagement-playbook.md) (loops)
- [CLI_CHEAT_SHEET.md](../CLI_CHEAT_SHEET.md) — `engagement` section
- Role: [roles/host-operator](../../roles/host-operator/)

View file

@ -1,9 +1,11 @@
# Forward-Deployed Agency Business Model
**Status:** v0.2 working accepted (DEC-FDA-001)
**Status:** v1.0 accepted (ADR-007; pilot railiance01 complete)
**Date:** 2026-07-16
**Audience:** product owners, coulomb ecosystem operators, early client sponsors
**Companion tech spec:** [docs/forward-deployed-engagement-architecture.md](../docs/forward-deployed-engagement-architecture.md)
**Canon ADR:** [docs/adr/ADR-007-forward-deployed-engagement-convention.md](../docs/adr/ADR-007-forward-deployed-engagement-convention.md)
**Playbook:** [docs/integrations/forward-deployed-engagement-playbook.md](../docs/integrations/forward-deployed-engagement-playbook.md)
**Decisions:** [docs/decisions/DEC-FDA-001-working-defaults.md](../docs/decisions/DEC-FDA-001-working-defaults.md)
**Builds on:** [PricingModel.md](PricingModel.md), [RevenueModel.md](RevenueModel.md), [KaizenAgenticMission.md](KaizenAgenticMission.md), ADR-006
@ -373,7 +375,10 @@ Still open for later:
## Related
- Canon ADR: [ADR-007](../docs/adr/ADR-007-forward-deployed-engagement-convention.md)
- Playbook: [forward-deployed-engagement-playbook.md](../docs/integrations/forward-deployed-engagement-playbook.md)
- Technical architecture: [docs/forward-deployed-engagement-architecture.md](../docs/forward-deployed-engagement-architecture.md)
- Customer engagement convention: [ADR-006](../docs/adr/ADR-006-customer-engagement-convention.md)
- Customer loop convention: [ADR-006](../docs/adr/ADR-006-customer-engagement-convention.md)
- Agency framework: [docs/agency-framework.md](../docs/agency-framework.md)
- Mission: [KaizenAgenticMission.md](KaizenAgenticMission.md)
- Pilot: `engagements/pilots/eng-coulomb-railiance01-ho-001/`

View file

@ -4,7 +4,7 @@ type: workplan
title: "Forward-deployed agency: engagements, Kai ledger, host-operator pilot"
domain: agents
repo: kaizen-agentic
status: active
status: finished
owner: kaizen-agentic
topic_slug: custodian
created: "2026-07-16"
@ -45,14 +45,14 @@ tasks:
status: done
title: Run railiance01 host-operator Phase 1 pilot through ramp-up exit
- id: T11
status: todo
status: done
title: Absorb pilot friction; ADR for engagement convention; docs cross-links
state_hub_workstream_id: "70f7afb1-78f1-4e3b-8437-48840b5b58cc"
---
# KAIZEN-WP-0009 — Forward-Deployed Agency
**Status:** active
**Status:** finished
**Owner:** kaizen-agentic
**Repo:** kaizen-agentic
**Depends on:** WP-0002 (agency memory), WP-0006 (schedule prepare), WP-0008 (customer engagement)
@ -231,14 +231,15 @@ deep_assessment close-session (4900 Kai). No privileged changes applied.
```task
id: KAIZEN-WP-0009-T11
status: todo
status: done
priority: low
state_hub_task_id: "f212949d-de22-46de-9ae0-63fc21e2701f"
```
- Supplier notes → playbook / architecture v0.2
- ADR-007 (or equivalent) for engagement convention if T02 promotes it
- CHANGELOG + wiki links; optional activity-core schedule for daily review
**Delivered 2026-07-16:** ADR-007 accepted; forward-deployed engagement playbook
v1 with railiance01 supplier-notes table; architecture v1.0; business model v1.0;
DEC-FDA-001 elevated; CHANGELOG + cross-links. activity-core host schedule left
optional (Phase 3) — documented in playbook.
## Out of scope
@ -257,6 +258,10 @@ state_hub_task_id: "f212949d-de22-46de-9ae0-63fc21e2701f"
5. No client vault content merged into supplier `agents/` without scrub + license
6. CLI or documented manual procedure can re-run prepare/checklist
## Closure
All tasks T01T11 done. Workplan **finished** 2026-07-16.
## Related
- [ForwardDeployedAgencyBusinessModel.md](../wiki/ForwardDeployedAgencyBusinessModel.md)