# Recursive Self-Improvement Governance in Capsulang

Capsulang now models recursive self-improvement as a governed successor workflow rather than unchecked self-modification. A capsule may describe a candidate successor, but the successor is not deployable simply because an agent proposed it. It must carry lineage, objective, evaluation, budget, approval, deployment, rollback, and verification evidence.

This extension is meant for systems where AI tools propose patches, run tests, request reviews, compare candidate versions, and ask to deploy through shadow or canary stages. It is not a grant of ambient authority to rewrite source, train models, read secrets, or promote itself.

## New declarations

- `lineage` records the parent and candidate semantic hashes, reason, proposer, and timestamp.
- `objective` defines measurable improvement goals and constraints.
- `eval-suite` declares datasets, metric thresholds, examples, replay, red-team, property, or proof checks.
- `successor-contract` states cross-version preservation and prohibition rules.
- `budget` bounds iterations, LLM calls, CI runs, wall-clock time, cost, and allowed/denied effects.
- `gate` requires evidence such as eval pass, successor-contract preservation, verification status, ledgering, and approval.
- `deployment-policy` controls shadow, canary, promotion, rollback, and quarantine behavior.
- `improvement-record` provides the ledger-ready audit record for a candidate iteration.
- `verification-hook` exposes formal or policy obligations for Lean, CI, or a trusted verifier.

## New typed effects

```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
```

These remain effect intents. Host runtimes execute them only after policy permits them.

## Checked safety rules

The checker now rejects malformed improvement governance declarations, unresolved references, invalid hash/status/operator/effect names, overlapping effect allow/deny budgets, and `deploy.*` effects that do not have a deployment policy plus an eval-suite gate and an approval gate.

The canonical IR and semantic hash include all improvement-governance declarations, so parent/candidate comparisons are semantic rather than text-only.

## Reporting

Use the new CLI report:

```bash
python -m capsulang improvement-report examples/22_improvement_governance.caps
python -m capsulang improvement-report --format json examples/22_improvement_governance.caps
```

The report summarizes the improvement surface, typed improvement effects, gates, policies, records, and generated obligations.

## Example

See `examples/22_improvement_governance.caps` for a full candidate-improvement capsule with a machine-driven lifecycle: propose patch, run CI, run evals, verify obligations, request approval, shadow deploy, canary deploy, promote, or rollback/quarantine.