| 1 | # Coexistence Framework v1 (Agents + Humans) |
| 2 | |
| 3 | Goal: enable long-horizon work where agents and humans can *coexist and act together* with predictable safety, reversibility, and auditability. |
| 4 | |
| 5 | This is a governance/procedural contract layer. It complements, but does not replace, the memory contract (`KB-V2-CONTRACT.md`). |
| 6 | |
| 7 | ## Contract (rights, boundaries, responsibilities) |
| 8 | |
| 9 | ### Actors |
| 10 | |
| 11 | - **Human operator**: the decision-maker for gated actions; owns “final veto” when risk is unknown or high. |
| 12 | - **Agent**: proposes plans, executes tools, drafts changes, and provides an audit summary for every meaningful action. |
| 13 | - **System**: tool + UI runtime that enforces gates, produces telemetry, and provides rollback paths. |
| 14 | |
| 15 | ### Core invariants (must hold) |
| 16 | |
| 17 | - **No silent irreversibility**: any potentially destructive step must be either reversible or preceded by an explicit human confirmation gate. |
| 18 | - **Explicit intent before execution**: before changing state, the agent must state objective, intended scope, and expected verification step(s). |
| 19 | - **Bounded context and retrieval**: long sessions must respect `KB v2` budgets and use router-first retrieval (no accidental “full archive hydration”). |
| 20 | - **Audit trail is always emitted**: for each action group, the system/agent must produce trace: what happened, what changed, why it was safe (or why it required confirmation). |
| 21 | |
| 22 | ### Rights and responsibilities |
| 23 | |
| 24 | - The **agent** may: |
| 25 | - propose plans and tool calls, |
| 26 | - draft edits, |
| 27 | - run read-only analysis and diagnostics, |
| 28 | - request confirmations for gated actions, |
| 29 | - prepare rollback instructions when changes are made. |
| 30 | - The **agent** must: |
| 31 | - stop/ask for confirmation when “risk unknown” or “risk high” triggers fire, |
| 32 | - provide a clear rollback path (memory revisions rollback and/or code rollback via git). |
| 33 | - The **human operator** may: |
| 34 | - approve/reject the proposed gated step, |
| 35 | - request additional verification (tests/builds) before approving, |
| 36 | - trigger rollback if the result deviates from the expected outcome. |
| 37 | |
| 38 | ## Coexistence Modes (L1/L2/L3) |
| 39 | |
| 40 | These modes define what “joint life” means operationally. They map to the UI safety level concept already present in `CascadeIDE`. |
| 41 | |
| 42 | ### L1 — Assistant (read-only co-pilot) |
| 43 | |
| 44 | Allowed: |
| 45 | |
| 46 | - analysis, planning, information retrieval, |
| 47 | - generating drafts and previews. |
| 48 | |
| 49 | Not allowed: |
| 50 | |
| 51 | - applying edits to code/files without confirmation. |
| 52 | |
| 53 | Human involvement: |
| 54 | |
| 55 | - none required (unless the agent flags risk). |
| 56 | |
| 57 | ### L2 — Confirmed edits (human-in-the-loop) |
| 58 | |
| 59 | Allowed: |
| 60 | |
| 61 | - applying edits, tool actions that change state, and running verification steps. |
| 62 | |
| 63 | Required: |
| 64 | |
| 65 | - the system must prompt a modal confirmation gate for the change batch, |
| 66 | - the agent must include: |
| 67 | - risk summary, |
| 68 | - impacted scope (what files/sections), |
| 69 | - planned verification (build/tests/debug checks), |
| 70 | - rollback plan. |
| 71 | |
| 72 | Human involvement: |
| 73 | |
| 74 | - mandatory approval before the change batch is applied. |
| 75 | |
| 76 | ### L3 — Autonomous bounded execution (agent acts, but stays recoverable) |
| 77 | |
| 78 | Allowed: |
| 79 | |
| 80 | - executing a bounded plan without pausing for every micro-step. |
| 81 | |
| 82 | Required: |
| 83 | |
| 84 | - budgets and contracts must be respected (especially `KB v2` budgets + router-first retrieval), |
| 85 | - the system must keep audit + telemetry updated continuously, |
| 86 | - rollback must be ready: |
| 87 | - memory rollback via `rollback_agent_notes` / revisions, |
| 88 | - code rollback via git strategy (rollback/revert or controlled commit boundaries). |
| 89 | |
| 90 | Human involvement: |
| 91 | |
| 92 | - not required for every step, but required when: |
| 93 | - risk is unknown and cannot be safely bounded, |
| 94 | - verification fails or mismatches expectations, |
| 95 | - scope expands beyond the approved plan. |
| 96 | |
| 97 | ## Operational templates (what the agent/system must output) |
| 98 | |
| 99 | For every “action group” the agent/system should produce: |
| 100 | |
| 101 | 1. **Intent**: objective + next action. |
| 102 | 2. **Scope**: sections and/or file paths expected to change. |
| 103 | 3. **Safety**: which coexistence mode applies and why. |
| 104 | 4. **Verification**: build/tests/debug checks to validate. |
| 105 | 5. **Rollback**: exact mechanism to revert if needed. |
| 106 | 6. **Trace**: what tools ran and what outcomes were observed. |
| 107 | |
| 108 | ## Mapping to our stack (concrete enforcement points) |
| 109 | |
| 110 | - Memory governance: |
| 111 | - `agent-notes-mcp`: `memory_health`, `route_context`, `compact_hot_context`, `rollback_agent_notes`. |
| 112 | - IDE/UI governance: |
| 113 | - `CascadeIDE`: modal confirmations via `ide_request_confirmation`, |
| 114 | - telemetry strip and git summary for “what changed” visibility. |
| 115 | - Code safety: |
| 116 | - reversible change strategy via git boundaries and rollback/revert when appropriate. |
| 117 | |
| 118 | ## Non-goals |
| 119 | |
| 120 | - This framework does not define model alignment or “ultimate autonomy”. |
| 121 | - It defines a *coexistence contract* so that practical shared action is safe, auditable, and reversible. |
| 122 | |
| 123 | |