2026-07-16 12:44:56 +02:00
# 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 monorepo’
### 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
2026-08-20 22:43:55 +02:00
- Pilot vault currently sits in the supplier repo (`engagements/pilots/` ) under
transitional custody. The Railiance01 receiving authority is
`railiance-infra` ; transfer requires explicit receiver acceptance before the
supplier copy is removed or reduced to a pointer.
- Manual preparation remains supported. Unattended host duties require an
2026-08-21 08:30:13 +02:00
engagement-specific activity-core definition and an approved versioned Glas
`harness_profile_ref` in addition to the generic `ops_run` intake path.
2026-07-16 12:44:56 +02:00
- Kai is not a payment processor; EUR path remains future work
### Follow-ups
2026-08-20 22:43:55 +02:00
- Complete the proposed pilot transfer to the client-owned `railiance-infra`
evidence path and record its accepted commit
2026-08-21 08:30:13 +02:00
- Register engagement-specific activity-core definitions and a Glas execution
profile reference for daily host-operator preparation when unattended
operation is desired
2026-07-16 12:44:56 +02:00
- EUR commercial FX after 2–
## Pilot evidence
- Engagement: `engagements/pilots/eng-coulomb-railiance01-ho-001/`
- Role: `roles/host-operator/`
- Workplan: KAIZEN-WP-0009 (T01–
- 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 )
