livepilot 1.12.2 → 1.13.0

package/mcp_server/evaluation/policy.py

@@ -4,10 +4,24 @@ Consistent keep/undo semantics shared across sonic, composition,
 and all future evaluators.
 
 Design: EVALUATION_FABRIC_V1.md, section 8
+
+PR7 adds ``classify_branch_outcome`` — a branch-lifecycle classifier that
+maps a score (and optional hard-rule inputs) to one of three statuses:
+"keep", "undo", "interesting_but_failed". The third status exists for
+exploration mode: a branch that failed technical gates but surfaced a
+novel idea is kept for audit and never re-applied. Protection violations
+still force undo regardless of exploration mode — that's a safety
+invariant, not a taste judgment.
 """
 
 from __future__ import annotations
 
+from dataclasses import asdict, dataclass, field
+from typing import Literal, Optional
+
+
+BranchOutcomeStatus = Literal["keep", "undo", "interesting_but_failed"]
+
 
 def apply_hard_rules(
     goal_progress: float,
@@ -16,11 +30,17 @@ def apply_hard_rules(
     measurable_count: int,
     score: float,
     target_count: int,
+    defer_on_unmeasurable: bool = True,
 ) -> tuple[bool, list[str]]:
     """Enforce hard rules and return (keep_change, failure_reasons).
 
     Rules (evaluated in order):
-    1. All targets unmeasurable + no protection violation -> defer to agent
+    1. (optional) All targets unmeasurable + no protection violation
+       -> defer to agent. Fires only when defer_on_unmeasurable=True
+       (the default). The evaluation fabric relies on this to mark
+       decision_mode="deferred". Score-producing evaluators (branch
+       lifecycle, PR7) pass defer_on_unmeasurable=False because the
+       score IS the judgment — no deferral needed.
     2. Protection violated -> force undo
     3. Measurable delta <= 0 when measurable targets exist -> force undo
     4. Score < 0.40 -> force undo
@@ -32,6 +52,10 @@ def apply_hard_rules(
         measurable_count: how many target dimensions were measurable
         score: composite quality score (0-1)
         target_count: total number of target dimensions
+        defer_on_unmeasurable: when True (default), rule 1 returns
+            (True, [defer message]) as soon as no measurable targets
+            exist. When False, rule 1 is skipped and rules 2-4 run
+            unconditionally.
 
     Returns:
         (keep_change, list_of_rule_failure_reasons)
@@ -39,7 +63,11 @@ def apply_hard_rules(
     failures: list[str] = []
 
     # Rule 1: all unmeasurable + no protection violation -> defer
-    if measurable_count == 0 and not protection_violated:
+    if (
+        defer_on_unmeasurable
+        and measurable_count == 0
+        and not protection_violated
+    ):
         return True, [
             "No measurable target dimensions — deferring keep/undo "
             "to agent musical judgment"
@@ -65,3 +93,102 @@ def apply_hard_rules(
 
     keep_change = len(failures) == 0
     return keep_change, failures
+
+
+# ── PR7 — branch-lifecycle classifier ────────────────────────────────────
+
+
+@dataclass
+class BranchOutcome:
+    """Unified branch evaluation result.
+
+    Fields:
+      status: terminal classification — "keep" | "undo" | "interesting_but_failed"
+      keep_change: True ⇒ status == "keep"; never True for the other statuses.
+      score: the composite score that informed the decision.
+      failure_reasons: human-readable list of failed hard rules (empty on keep).
+      note: optional explanation aimed at the user.
+    """
+
+    status: BranchOutcomeStatus
+    keep_change: bool
+    score: float
+    failure_reasons: list[str] = field(default_factory=list)
+    note: str = ""
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def classify_branch_outcome(
+    score: float,
+    *,
+    protection_violated: bool = False,
+    measurable_count: int = 0,
+    target_count: int = 0,
+    goal_progress: float = 0.0,
+    exploration_rules: bool = False,
+) -> BranchOutcome:
+    """Classify a branch's terminal status from a score + optional hard-rule inputs.
+
+    Delegates to apply_hard_rules with ``defer_on_unmeasurable=False`` — a
+    score-producing evaluator DID make a judgment, so rule 1's deferral
+    path is not appropriate here. The score alone is enough to push a
+    branch toward undo / interesting_but_failed.
+
+    Post-processing:
+      - ``exploration_rules=False`` (technical safety, default):
+        any hard-rule failure ⇒ status="undo".
+      - ``exploration_rules=True`` (creative exploration):
+        protection violations still force undo (safety invariant);
+        all other failures downgrade to "interesting_but_failed".
+
+    Returns a BranchOutcome that callers can plug into branch.score /
+    .status / .evaluation without further interpretation.
+    """
+    keep_change, failures = apply_hard_rules(
+        goal_progress=goal_progress,
+        collateral_damage=0.0,  # not threaded here — branch lifecycle doesn't compute it yet
+        protection_violated=protection_violated,
+        measurable_count=measurable_count,
+        score=score,
+        target_count=target_count,
+        defer_on_unmeasurable=False,
+    )
+
+    if keep_change:
+        return BranchOutcome(
+            status="keep",
+            keep_change=True,
+            score=score,
+            failure_reasons=[],
+            note="",
+        )
+
+    # Failed — decide between undo and interesting_but_failed.
+    protection_failure = any("protected dimension" in f for f in failures)
+
+    if exploration_rules and not protection_failure:
+        return BranchOutcome(
+            status="interesting_but_failed",
+            keep_change=False,
+            score=score,
+            failure_reasons=failures,
+            note=(
+                "Exploration rule: branch failed technical gates but is "
+                "retained for audit. Not re-applied."
+            ),
+        )
+
+    return BranchOutcome(
+        status="undo",
+        keep_change=False,
+        score=score,
+        failure_reasons=failures,
+        note=(
+            "Protection violation — branch rolled back regardless of "
+            "exploration mode."
+            if protection_failure
+            else "Branch rolled back per hard rules."
+        ),
+    )

package/mcp_server/experiment/engine.py

@@ -22,6 +22,7 @@ import time
 from typing import Optional
 
 from .models import ExperimentSet, ExperimentBranch, BranchSnapshot
+from ..branches import BranchSeed, seed_from_move_id
 import logging
 
 logger = logging.getLogger(__name__)
@@ -39,27 +40,43 @@ def _gen_id(prefix: str, seed: str) -> str:
 # ── Create experiments ───────────────────────────────────────────────────────
 
 
-def create_experiment(
+def create_experiment_from_seeds(
     request_text: str,
-    move_ids: list[str],
+    seeds: list[BranchSeed],
     kernel_id: str = "",
+    compiled_plans: Optional[list] = None,
 ) -> ExperimentSet:
-    """Create an experiment set with branches for each semantic move.
+    """Create an experiment set from BranchSeeds (PR3 canonical path).
 
-    Does NOT execute anything — just creates the branch structures.
-    Call run_experiment() to actually trial each branch.
+    seeds: one BranchSeed per desired branch. Can be any source — semantic_move,
+      freeform, synthesis, composer, technique.
+    compiled_plans: optional parallel list; when entry ``i`` is a dict, that
+      plan is attached to branch ``i`` (used by freeform / synthesis / composer
+      producers that do their own compilation). When None or entry is None,
+      run_experiment compiles from the seed at run time — which only succeeds
+      for source="semantic_move" seeds.
+
+    Does NOT execute anything — call run_experiment() to trial each branch.
     """
+    if compiled_plans is not None and len(compiled_plans) != len(seeds):
+        raise ValueError(
+            f"compiled_plans length ({len(compiled_plans)}) must match "
+            f"seeds length ({len(seeds)})"
+        )
+
     exp_id = _gen_id("exp", request_text)
     now = int(time.time() * 1000)
 
     branches = []
-    for i, move_id in enumerate(move_ids):
-        branch = ExperimentBranch(
-            branch_id=_gen_id("br", f"{move_id}_{i}"),
-            name=f"Branch {i+1}: {move_id}",
-            move_id=move_id,
+    for i, seed in enumerate(seeds):
+        plan = compiled_plans[i] if compiled_plans else None
+        display = seed.move_id or (seed.hypothesis[:32] if seed.hypothesis else seed.seed_id)
+        branch = ExperimentBranch.from_seed(
+            seed=seed,
+            branch_id=_gen_id("br", f"{seed.seed_id}_{i}"),
+            name=f"Branch {i+1}: {display}",
             source_kernel_id=kernel_id,
-            status="pending",
+            compiled_plan=plan,
             created_at_ms=now,
         )
         branches.append(branch)
@@ -76,6 +93,25 @@ def create_experiment(
     return experiment
 
 
+def create_experiment(
+    request_text: str,
+    move_ids: list[str],
+    kernel_id: str = "",
+) -> ExperimentSet:
+    """Create an experiment set with one semantic_move branch per move_id.
+
+    Legacy API — kept for back-compat. Internally builds one BranchSeed per
+    move_id via seed_from_move_id and delegates to create_experiment_from_seeds.
+    Branch naming, ids, and lifecycle are unchanged for existing callers.
+    """
+    seeds = [seed_from_move_id(mid) for mid in move_ids]
+    return create_experiment_from_seeds(
+        request_text=request_text,
+        seeds=seeds,
+        kernel_id=kernel_id,
+    )
+
+
 def get_experiment(experiment_id: str) -> Optional[ExperimentSet]:
     """Get an experiment by ID."""
     return _EXPERIMENTS.get(experiment_id)

package/mcp_server/experiment/models.py

@@ -1,8 +1,15 @@
 """Experiment branch data models.
 
-An ExperimentBranch represents one trial of a semantic move against the
-current session state. Multiple branches form an experiment set that can
-be compared and ranked.
+An ExperimentBranch represents one trial against the current session state.
+
+Pre-PR3 every branch was tied to a semantic_move (positional required
+``move_id``). PR3 widens this: a branch may now be built from any
+:class:`mcp_server.branches.BranchSeed` — semantic_move, freeform,
+synthesis, composer, or technique. The ``move_id`` field is retained as
+an optional convenience that mirrors ``seed.move_id`` for back-compat with
+callers that read ``branch.move_id`` directly.
+
+Multiple branches form an experiment set that can be compared and ranked.
 """
 
 from __future__ import annotations
@@ -11,6 +18,8 @@ import time
 from dataclasses import dataclass, field
 from typing import Any, Optional
 
+from ..branches import BranchSeed
+
 
 @dataclass
 class BranchSnapshot:
@@ -37,14 +46,26 @@ class BranchSnapshot:
 
 @dataclass
 class ExperimentBranch:
-    """One trial branch in an experiment set."""
+    """One trial branch in an experiment set.
+
+    move_id is retained as an optional convenience (empty for freeform /
+    synthesis / composer seeds) so pre-PR3 callers that read
+    ``branch.move_id`` directly keep working. The authoritative source of
+    branch intent is ``seed`` when present.
+    """
     branch_id: str
     name: str
-    move_id: str
+    # PR3 — was a required positional; now defaults to "" for seeds whose
+    # source is not "semantic_move". When seed is present, move_id mirrors
+    # seed.move_id (populated by ExperimentBranch.from_seed).
+    move_id: str = ""
     source_kernel_id: str = ""
-    status: str = "pending"  # pending | running | evaluated | committed | discarded
+    status: str = "pending"  # pending | running | evaluated | committed | discarded | interesting_but_failed
 
-    # Compiled plan for this branch
+    # Compiled plan for this branch. Pre-PR3 this was always filled in at
+    # run_experiment time. Post-PR3, freeform / synthesis / composer producers
+    # MAY pre-populate it on the seed path; run_experiment respects a
+    # pre-existing plan and only compiles when it's None.
     compiled_plan: Optional[dict] = None
 
     # Captured snapshots
@@ -65,6 +86,44 @@ class ExperimentBranch:
     created_at_ms: int = 0
     executed_at_ms: int = 0
 
+    # PR3 — branch-native seed. None for legacy move-only branches built via
+    # the bare constructor; populated when built through from_seed() or via
+    # create_experiment_from_seeds.
+    seed: Optional[BranchSeed] = None
+
+    @classmethod
+    def from_seed(
+        cls,
+        seed: BranchSeed,
+        branch_id: str,
+        name: str = "",
+        source_kernel_id: str = "",
+        compiled_plan: Optional[dict] = None,
+        created_at_ms: int = 0,
+    ) -> "ExperimentBranch":
+        """Construct an ExperimentBranch from a BranchSeed.
+
+        ``move_id`` is mirrored from ``seed.move_id`` (empty for freeform /
+        synthesis / composer / technique seeds). When ``compiled_plan`` is
+        provided, the producer has already compiled — run_experiment will
+        skip compilation for this branch. When None, compilation defers to
+        the semantic_moves.compiler at run time and only succeeds for
+        source="semantic_move" seeds.
+        """
+        default_name = (
+            f"Branch ({seed.source}:{seed.move_id or seed.seed_id[:8]})"
+        )
+        return cls(
+            branch_id=branch_id,
+            name=name or default_name,
+            move_id=seed.move_id,
+            source_kernel_id=source_kernel_id,
+            status="pending",
+            compiled_plan=compiled_plan,
+            created_at_ms=created_at_ms,
+            seed=seed,
+        )
+
     def to_dict(self) -> dict:
         d = {
             "branch_id": self.branch_id,
@@ -87,6 +146,12 @@ class ExperimentBranch:
             d["execution_log"] = self.execution_log
             d["steps_ok"] = sum(1 for e in self.execution_log if e.get("ok"))
             d["steps_failed"] = sum(1 for e in self.execution_log if not e.get("ok"))
+        if self.seed is not None:
+            d["seed"] = self.seed.to_dict()
+            d["branch_source"] = self.seed.source
+            d["analytical_only"] = (
+                self.seed.analytical_only or self.compiled_plan is None
+            )
         return d