# Capsulang Improvement Governance

Capsulang now has a first-class governance layer for AI-generated candidate successors. The extension is designed for controlled recursive improvement loops: an agent may propose a candidate, but the language records lineage, objectives, evals, successor contracts, budgets, gates, deployment policy, approvals, and rollback evidence before a host may promote it.

This is intentionally not an unchecked self-modification feature. Effects such as `repo.propose_patch`, `ci.run`, `eval.run`, `proof.verify`, `deploy.canary`, and `deploy.promote` remain declared effect intents. A runtime or Apple/host SDK must still enforce policy and execute adapters.

## New module declarations

| Declaration | Purpose |
|---|---|
| `lineage` | Parent/candidate semantic hashes, reason, proposer, and timestamp. |
| `objective` | Metrics, maximize/minimize directions, and constraints that define safe improvement. |
| `eval-suite` | Datasets, thresholds, and must-pass checks such as examples and replay. |
| `successor-contract` | Cross-version rules such as preserving contracts or forbidding authority expansion without approval. |
| `budget` | Iteration, call, CI, wall-clock, cost, and effect allow/deny bounds. |
| `gate` | Evidence requirements and pass/fail actions for promotion, quarantine, rollback, and human approval. |
| `deployment-policy` | Shadow/canary/live policy, promotion gate, rollback target, and quarantine triggers. |
| `improvement-record` | Ledger-ready record of candidate hashes, eval/proof/policy results, approvals, outcomes, and rollback pointer. |
| `verification-hook` | Explicit proof obligations for Lean, policy engines, or trusted external verifiers. |

## Effect domains

The improvement governance checker recognizes these typed effect domains:

```text
llm.call
repo.diff
repo.propose_patch
repo.apply_patch.sandboxed
ci.run
eval.run
proof.emit
proof.verify
model.finetune
model.eval
deploy.shadow
deploy.canary
deploy.promote
deploy.rollback
approval.request
risk.review
```

Portable/proof profiles forbid these external prefixes unless the host profile allows them. Any `deploy.*` effect is rejected unless the capsule also declares a deployment policy and gates containing eval-suite and approval requirements.

## Example

See `examples/22_improvement_governance.caps` for a checked capsule that declares lineage, a measurable objective, regression evals, a successor contract, budget, deployment gate, deployment policy, and an improvement record.

The example checks with:

```bash
python -m capsulang check examples/22_improvement_governance.caps
```

## Conformance

The standard now defines `CPS-8 Improvement-Governed`. A CPS-8 implementation must parse, check, canonicalize, and make ledger-ready all improvement governance declarations. Formal verification remains CPS-7; CPS-8 can add verification hooks that generate or track proof obligations, but the hooks are not proof by themselves.