kaizen-agentic/docs/adr/ADR-007-forward-deployed-engagement-convention.md

# 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’s 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 2–3 engagement calibration cycles

## Pilot evidence

- Engagement: `engagements/pilots/eng-coulomb-railiance01-ho-001/`
- Role: `roles/host-operator/`
- Workplan: KAIZEN-WP-0009 (T01–T11)
- 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)