162 lines
6 KiB
Markdown
162 lines
6 KiB
Markdown
# 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/`) 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
|
||
engagement-specific activity-core definition and an approved versioned Glas
|
||
`harness_profile_ref` in addition to the generic `ops_run` intake path.
|
||
- Kai is not a payment processor; EUR path remains future work
|
||
|
||
### Follow-ups
|
||
|
||
- Complete the proposed pilot transfer to the client-owned `railiance-infra`
|
||
evidence path and record its accepted commit
|
||
- Register engagement-specific activity-core definitions and a Glas execution
|
||
profile reference for daily host-operator preparation when unattended
|
||
operation is desired
|
||
- 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)
|