feat: add evolution controller and append-only ledger

plugins/openflywheel/program_templates/base.md

@@ -4,8 +4,8 @@ This file is generated by `prepare_workspace`. Do not edit it directly.
 
 ## Mission
 
-Record one evidence-backed hypothesis, execute its isolated candidate under the canonical
-experiment policy, then stop before admission.
+Call `evolution_status`, then `advance_evolution` for exactly one next action under the
+canonical experiment policy. Stop before publication.
 
 The baseline has already been recorded. Begin at step 2; do not rerun the unchanged
 baseline. Its provenance is recorded in the policy (`baseline_reused` is explicit when an
@@ -31,40 +31,22 @@ Target only exact paths allowed by the canonical experiment policy. Edit them on
 candidate worktree returned by `execute_candidate`. Never target the benchmark, held-out tasks,
 verifier, model, reasoning budget, observability identity, or this program.
 
-Keep one focused hypothesis per iteration. Do not mix prompt, tool, middleware, and control
-flow changes unless the evidence requires the combination.
+Keep one focused hypothesis per iteration. The controller owns phase, budgets, stop reasons,
+and ledger truth; never append events or perform generic transitions yourself.
 
-## Optimization loop
+## Controller loop
 
-### 2. Analyze failures
-
-Start from verifier-backed failed outcomes. Use bounded trace queries to locate relevant
-evidence, then inspect only the spans needed to explain the observed behavior. Do not load
-or copy complete traces when filters answer the question, and do not inspect held-out
-trajectory content.
-
-### 3. Form one hypothesis
-
-State the failure pattern, supporting trace and verifier evidence, proposed harness change,
-expected improvement, and possible regressions. Stop if the evidence cannot distinguish
-between materially different changes.
-
-Use `$hypothesis-former` with one curation receipt and group ID plus every exact supported
-pattern and diagnosis receipt ID in that group, explicit predicted task IDs, and at-risk task IDs, then call
-`record_hypothesis`. Retain the stable hypothesis receipt before candidate execution.
-
-### 4. Execute one candidate
-
-Call `execute_candidate` with the prepared workspace, experiment and hypothesis receipts, sibling
-candidate-worktree parent, and Harbor runtime locations. The first call creates the isolated
-worktree from the accepted experiment commit. Edit only the exact hypothesis targets in the
-returned candidate worktree, then call `execute_candidate` again with the identical request.
-
-Poll identical requests while the candidate is running. Retain its candidate ID, Git commit,
-trace-mapping blockers, and authoritative outcome receipts. Do not copy trace payloads locally,
-change frozen controls, rerun an empty candidate, or edit the accepted experiment worktree.
+1. Use bounded trace queries and `$failure-miner`, `record_failure`, `$failure-pattern-miner`,
+   `mine_failure_patterns`, `$failure-curator`, and `record_failure_curation` to retain only
+   typed evidence; do not copy Langfuse trace payloads.
+2. Use `$hypothesis-former` and `record_hypothesis`, then pass the stable hypothesis receipt to
+   `advance_evolution`.
+3. Call `execute_candidate` to create the candidate worktree, edit only its declared targets,
+   then call it again with the identical request; retain candidate and evaluated run receipts.
+4. Pass the existing `PromotionDecision` to `advance_evolution`. Accepted candidates remain
+   `AwaitingPublication` until PR5; do not publish, merge, push, or install.
 
 ## Package boundary
 
-Report the hypothesis, candidate, commit, blocker, and outcome receipts. Stop before admission:
-do not gate, accept, merge, publish, push, or install the candidate.
+Report the hypothesis, candidate, commit, blocker, gate, and outcome receipts. Stop before
+publication: do not publish, merge, push, or install the candidate.

src/ofw/__init__.py

@@ -49,6 +49,7 @@
     VerifierVerdict,
 )
 from ofw.evolution import (
+    AdvanceEvolutionInput,
     CandidateBlockerCode,
     CandidateErrorCode,
     CandidateExecutionInput,
@@ -57,8 +58,23 @@
     CandidateId,
     CandidatePhase,
     CandidateStatus,
+    EvolutionAdvanceAction,
+    EvolutionController,
+    EvolutionControllerErrorCode,
+    EvolutionControllerFailure,
+    EvolutionEvent,
+    EvolutionEventDraft,
+    EvolutionEventPage,
+    EvolutionEventType,
+    EvolutionLedgerErrorCode,
+    EvolutionLedgerFailure,
+    EvolutionObservation,
+    EvolutionPhase,
+    EvolutionStatus,
+    EvolutionStopReason,
     FailurePatternReference,
     FailurePatternReferenceInput,
+    FileEvolutionLedger,
     HarnessChangeTarget,
     HarnessChangeTargetInput,
     HarnessHypothesis,
@@ -96,6 +112,22 @@
     "CandidateId",
     "CandidatePhase",
     "CandidateStatus",
+    "AdvanceEvolutionInput",
+    "EvolutionAdvanceAction",
+    "EvolutionController",
+    "EvolutionControllerErrorCode",
+    "EvolutionControllerFailure",
+    "EvolutionObservation",
+    "EvolutionPhase",
+    "EvolutionStatus",
+    "EvolutionStopReason",
+    "EvolutionEvent",
+    "EvolutionEventDraft",
+    "EvolutionEventPage",
+    "EvolutionEventType",
+    "EvolutionLedgerErrorCode",
+    "EvolutionLedgerFailure",
+    "FileEvolutionLedger",
     "CollectionError",
     "CollectionErrorCode",
     "ComponentKind",

src/ofw/evolution/__init__.py

@@ -13,6 +13,23 @@
 from ofw.evolution.candidate_git import CandidateGitGateway
 from ofw.evolution.candidate_langfuse import LangfuseCandidateTraceLocator
 from ofw.evolution.candidate_service import CandidateExecutionService
+from ofw.evolution.controller import (
+    AdvanceEvolutionInput,
+    EvolutionAdvanceAction,
+    EvolutionController,
+    EvolutionControllerErrorCode,
+    EvolutionControllerFailure,
+    EvolutionObservation,
+    EvolutionPhase,
+    EvolutionStatus,
+    EvolutionStopReason,
+)
+from ofw.evolution.gate import (
+    PromotionDecision,
+    PromotionReason,
+    PromotionStatus,
+    decide_promotion,
+)
 from ofw.evolution.hypothesis import (
     FailurePatternReference,
     FailurePatternReferenceInput,
@@ -28,6 +45,30 @@
     RecordHypothesisInput,
 )
 from ofw.evolution.hypothesis_repository import FileHypothesisRepository
+from ofw.evolution.ledger import (
+    CandidateAccepted,
+    CandidatePrepared,
+    CandidateRejected,
+    CandidateSubmitted,
+    EvolutionEvent,
+    EvolutionEventDraft,
+    EvolutionEventPage,
+    EvolutionEventPayload,
+    EvolutionEventType,
+    EvolutionLedgerErrorCode,
+    EvolutionLedgerFailure,
+    EvolutionStarted,
+    ExternalOperation,
+    ExternalOperationBlocked,
+    ExternalOperationIntent,
+    FileEvolutionLedger,
+    GateDecided,
+    HypothesisLinked,
+    ReleasePublished,
+    ReleaseRolledBack,
+    RunCompleted,
+    RunStarted,
+)
 
 __all__ = [
     "CandidateBlockerCode",
@@ -40,6 +81,40 @@
     "CandidateId",
     "CandidatePhase",
     "CandidateStatus",
+    "AdvanceEvolutionInput",
+    "EvolutionAdvanceAction",
+    "EvolutionController",
+    "EvolutionControllerErrorCode",
+    "EvolutionControllerFailure",
+    "EvolutionObservation",
+    "EvolutionPhase",
+    "EvolutionStatus",
+    "EvolutionStopReason",
+    "EvolutionEvent",
+    "EvolutionEventDraft",
+    "EvolutionEventPayload",
+    "EvolutionEventPage",
+    "EvolutionEventType",
+    "EvolutionStarted",
+    "HypothesisLinked",
+    "CandidatePrepared",
+    "CandidateSubmitted",
+    "RunStarted",
+    "RunCompleted",
+    "GateDecided",
+    "CandidateAccepted",
+    "CandidateRejected",
+    "ReleasePublished",
+    "ReleaseRolledBack",
+    "ExternalOperation",
+    "ExternalOperationIntent",
+    "ExternalOperationBlocked",
+    "EvolutionLedgerErrorCode",
+    "EvolutionLedgerFailure",
+    "FileEvolutionLedger",
+    "PromotionDecision",
+    "PromotionReason",
+    "PromotionStatus",
     "FailurePatternReference",
     "FailurePatternReferenceInput",
     "FileHypothesisRepository",
@@ -54,4 +129,5 @@
     "HypothesisStatus",
     "LangfuseCandidateTraceLocator",
     "RecordHypothesisInput",
+    "decide_promotion",
 ]