Status: proposal (does not describe shipped behavior; paths below are targets rather than citations and are skipped by check_doc_paths.py)

Governed Self-Evolution

Goal

Allow vak-capable agents to propose and apply code changes to their own behavior — subject to human review gates and the narrowing invariant (docs/design/47-commitment-kernel.md). Self-evolution must never escalate authority.

Architecture

┌─────────────┐    ┌──────────────┐    ┌──────────────┐
│   Agent     │───▶│   Intent     │───▶│   Proposal   │
│   (model)   │    │   Kernel     │    │   Engine     │
└─────────────┘    └──────────────┘    └──────┬───────┘
                                           │ submit
                                           ▼
                               ┌─────────────────────┐
                               │   Skill Proposal    │
                               │   (docs/design/26)  │
                               └────────┬────────────┘
                                        │ reviewed
                                        ▼
                              ┌──────────────────┐
                              │   Capability     │
                              │   Registry       │
                              │  (docs/design/41)│
                              └──────────────────┘

Proposal Lifecycle

1. Generate: The agent proposes a change as a skill proposal (crates/vak-plugin/src/lib.rs: manifest + capability declaration).
2. Scope: The intent kernel (crates/vak-intent) narrows the proposal. Intent narrows, never widens (rule 32). A proposal cannot add tools, extend ladders, or raise caps.
3. Validate: The capability registry (crates/vak-core/src/capability/) resolves the proposal against the host's capability vocabulary. Only proposals that fall within the existing authority are admissible.
4. Review: Skill proposals with network, secret, or external-effect impact require human approval (rule 25). Presentation/skill/evidence proposals may be auto-admitted only inside an existing envelope.
5. Promote: Approved proposals take effect via the level-triggered reconcile loop (rule 31). No restart required.
6. Revoke: Revocations take effect immediately (rule 31).

Constraints

• Authority ceiling: The proposal engine cannot grant authority the submitting agent does not itself possess.
• Append-only ledger: All proposals and their outcomes are recorded in the session JSONL (rule 2: append-only sessions).
• No ambient escalation: A self-evolution proposal that would widen authority is rejected at admission by PermissionEngine (rule 16: every execution path authorizes before dispatch).

Security

• All proposed changes are signed with the operator's Ed25519 key (see crates/vak-plugin/src/lib.rs catalog-signature verification).
• A revoked key prevents any further self-evolution proposals from that source.
• The proposal engine is itself a capability — governed_self_evolution — that must be explicitly admitted; it is never on by default.

Open Questions

• How does self-evolution interact with the frozen route ladder? (Rule 7: retries honor the frozen ladder. Self-evolution proposals must not modify a session's frozen route, only propose new ones for future sessions.)
• How do we prevent recursive self-modification? (A proposal cannot modify the proposal engine itself without a fresh human approval cycle.)