codex-flow 2.1.13__py3-none-any.whl

codex_flow/data/scripts/strategies/__init__.py

@@ -0,0 +1,28 @@
+"""Built-in strategy registry for codex-flow."""
+from __future__ import annotations
+
+from .balanced import STRATEGY as BALANCED
+from .base import StrategySpec
+from .efficient import STRATEGY as EFFICIENT
+from .quality import STRATEGY as QUALITY
+from .speed import STRATEGY as SPEED
+
+_REGISTRY: dict[str, StrategySpec] = {
+    spec.name: spec
+    for spec in (EFFICIENT, BALANCED, QUALITY, SPEED)
+}
+
+
+def names() -> tuple[str, ...]:
+    return tuple(_REGISTRY)
+
+
+def get(name: str) -> StrategySpec:
+    try:
+        return _REGISTRY[name]
+    except KeyError as exc:
+        raise ValueError(f"invalid strategy: {name}") from exc
+
+
+def all_specs() -> tuple[StrategySpec, ...]:
+    return tuple(_REGISTRY.values())

codex_flow/data/scripts/strategies/balanced.py

@@ -0,0 +1,115 @@
+"""Balanced quality/quota/latency strategy."""
+from __future__ import annotations
+
+from .base import (
+    StagePolicy,
+    StrategySpec,
+    TaskBudgetPolicy,
+    WorkerBudget,
+    never,
+    small_low_risk_is_direct,
+    standard_effort,
+)
+
+
+def adaptive_route(task) -> str:
+    if small_low_risk_is_direct(task):
+        return "direct"
+    return "delegate" if task.complexity in {"routine", "complex", "critical"} and task.iteration_intensity != "one-shot" else "direct"
+
+
+def worker_budget(task) -> WorkerBudget:
+    if task.complexity in {"complex", "critical"} or task.scope == "repo-wide":
+        return WorkerBudget(3, 3, 1, 5, "medium")
+    if task.uncertainty == "high" or task.iteration_intensity == "heavy-loop":
+        return WorkerBudget(3, 2, 1, 4, "medium")
+    return WorkerBudget(2, 2, 1, 4, "medium")
+
+
+def implementation_soft_timeout(task) -> int:
+    if task.complexity == "critical" or task.risk == "critical":
+        return 1800
+    if task.complexity == "complex" or task.scope == "repo-wide" or task.iteration_intensity == "heavy-loop":
+        return 1500
+    return 1200
+
+
+def implementation_checkpoint_rearm_seconds(task) -> int:
+    if task.complexity == "critical" or task.risk == "critical":
+        return 360
+    if task.complexity == "complex" or task.scope in {"cross-module", "repo-wide"} or task.iteration_intensity == "heavy-loop":
+        return 300
+    return 240
+
+
+def implementation_repair_attempts(task) -> int:
+    if task.complexity in {"complex", "critical"} or task.risk == "critical" or task.scope == "repo-wide" or task.iteration_intensity == "heavy-loop":
+        return 2
+    return 1
+
+
+def implementation_maximum_work_units(task) -> int:
+    if task.scope == "repo-wide" or task.iteration_intensity == "heavy-loop":
+        semantic_maximum = 3
+    elif task.complexity in {"complex", "critical"} or task.scope == "cross-module" or task.risk == "critical":
+        semantic_maximum = 2
+    else:
+        semantic_maximum = 1
+    topology_floor = min(task.writable_workstreams, worker_budget(task).max_implementers)
+    return max(semantic_maximum, topology_floor)
+
+
+def task_budget(task) -> TaskBudgetPolicy:
+    maximum_work_units = implementation_maximum_work_units(task)
+    if task.complexity == "critical" or task.risk == "critical" or task.scope == "repo-wide" or task.iteration_intensity == "heavy-loop":
+        soft_timeout, hard_timeout = 3000, 3600
+    elif task.complexity == "complex" or task.scope == "cross-module" or task.risk == "high":
+        soft_timeout, hard_timeout = 2700, 3300
+    else:
+        soft_timeout, hard_timeout = 2400, 3000
+    return TaskBudgetPolicy(
+        soft_timeout_seconds=soft_timeout,
+        hard_timeout_seconds=hard_timeout,
+        max_work_units=maximum_work_units,
+        max_implementation_attempts=maximum_work_units + 2,
+        max_replans=2,
+        max_replacements=2,
+        max_review_attempts=2,
+        parent_finalization_seconds=180,
+    )
+
+
+def lifecycle(task, stage: str) -> StagePolicy:
+    if stage == "exploration":
+        return StagePolicy("quorum", 1, 180, 1200, True, True, "parent_delta")
+    if stage == "implementation":
+        maximum_work_units = implementation_maximum_work_units(task)
+        bounded_mode = maximum_work_units > 1
+        return StagePolicy(
+            "required", 1, 240, 2400, False, False, "replan",
+            soft_timeout_seconds=implementation_soft_timeout(task),
+            checkpoint_rearm_seconds=implementation_checkpoint_rearm_seconds(task),
+            max_worker_repair_attempts=implementation_repair_attempts(task),
+            work_unit_mode="bounded" if bounded_mode else "single",
+            minimum_work_units=1,
+            join_between_work_units=bounded_mode,
+            maximum_work_units=maximum_work_units,
+            require_write_paths=bounded_mode,
+        )
+    if stage == "review":
+        return StagePolicy("required", 1, 180, 1800, True, False, "retry_review")
+    raise ValueError(f"invalid lifecycle stage: {stage}")
+
+
+STRATEGY = StrategySpec(
+    name="balanced",
+    description="balance quality, quota consumption, and latency with moderate safe worker fan-out",
+    adaptive_route=adaptive_route,
+    effort=standard_effort,
+    worker_budget=worker_budget,
+    independent_review=never,
+    lifecycle=lifecycle,
+    allow_parallel_write=True,
+    quota_sensitive=True,
+    task_budget=task_budget,
+)

codex_flow/data/scripts/strategies/base.py

@@ -0,0 +1,363 @@
+"""Shared contracts for built-in codex-flow strategy modules."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Tuple
+
+Task = Any
+RouteFn = Callable[[Task], str]
+EffortFn = Callable[[Task, str], str]
+BudgetFn = Callable[[Task], "WorkerBudget"]
+PredicateFn = Callable[[Task], bool]
+CapabilityFn = Callable[[Task, str], str]
+DemandFn = Callable[[Task], int]
+NotesFn = Callable[[Task], Tuple[str, ...]]
+LifecycleFn = Callable[[Task, str], "StagePolicy"]
+TaskBudgetFn = Callable[[Task], "TaskBudgetPolicy | None"]
+ReasoningRolloutFn = Callable[
+    [Task, str, "ReasoningRolloutPolicy", str, str], "ReasoningRolloutDecision"
+]
+
+STAGES = ("exploration", "implementation", "review")
+JOIN_POLICIES = ("opportunistic", "quorum", "required")
+FALLBACK_POLICIES = ("continue_partial", "parent_delta", "replan", "retry_review", "fail")
+WORK_UNIT_MODES = ("single", "bounded")
+
+
+def worker_capability(_task: Task, _role: str) -> str:
+    """Use the configured efficient-worker capability for this role."""
+    return "worker"
+
+
+def zero_demand(_task: Task) -> int:
+    return 0
+
+
+def no_notes(_task: Task) -> tuple[str, ...]:
+    return ()
+
+
+@dataclass(frozen=True)
+class WorkerBudget:
+    """Strategy preference envelope before Runtime safety/ceiling enforcement."""
+
+    max_explorers: int
+    max_implementers: int
+    max_reviewers: int
+    max_total_workers: int
+    speculation: str = "medium"
+
+    def validate(self) -> None:
+        for name, value in (
+            ("max_explorers", self.max_explorers),
+            ("max_implementers", self.max_implementers),
+            ("max_reviewers", self.max_reviewers),
+            ("max_total_workers", self.max_total_workers),
+        ):
+            if value < 0:
+                raise ValueError(f"{name} cannot be negative")
+        if self.max_implementers < 1:
+            raise ValueError("max_implementers must be positive")
+        if self.max_total_workers < 1:
+            raise ValueError("max_total_workers must be positive")
+        if self.speculation not in {"low", "medium", "high"}:
+            raise ValueError(f"invalid speculation level: {self.speculation}")
+
+
+@dataclass(frozen=True)
+class TaskBudgetPolicy:
+    """Cumulative task budget carried across Worker attempts and replans.
+
+    Stage lifecycle limits describe one Worker stage. These task-level counters
+    are durable reservations across attempts/replans. `max_review_attempts`
+    counts read-only reviewer Worker starts independently from implementation
+    replans/replacements. `parent_finalization_seconds` is a deterministic tail
+    reserved after the review-stage hard window whenever reviewers are planned.
+    """
+
+    soft_timeout_seconds: int
+    hard_timeout_seconds: int
+    max_work_units: int
+    max_implementation_attempts: int
+    max_replans: int
+    max_replacements: int
+    max_review_attempts: int = 0
+    parent_finalization_seconds: int = 120
+
+    @classmethod
+    def from_dict(cls, value: Any) -> "TaskBudgetPolicy":
+        if type(value) is not dict:
+            raise ValueError("task budget policy must be an object")
+        required = (
+            "soft_timeout_seconds",
+            "hard_timeout_seconds",
+            "max_work_units",
+            "max_implementation_attempts",
+            "max_replans",
+            "max_replacements",
+            "max_review_attempts",
+            "parent_finalization_seconds",
+        )
+        missing = [name for name in required if name not in value]
+        if missing:
+            raise ValueError(f"task budget policy missing fields: {missing}")
+        unknown = sorted(set(value).difference(required))
+        if unknown:
+            raise ValueError(f"task budget policy has unknown fields: {unknown}")
+        policy = cls(**{name: value[name] for name in required})
+        policy.validate()
+        return policy
+
+    def validate(self) -> None:
+        for name, value in (
+            ("soft_timeout_seconds", self.soft_timeout_seconds),
+            ("hard_timeout_seconds", self.hard_timeout_seconds),
+            ("max_work_units", self.max_work_units),
+            ("max_implementation_attempts", self.max_implementation_attempts),
+            ("max_replans", self.max_replans),
+            ("max_replacements", self.max_replacements),
+            ("max_review_attempts", self.max_review_attempts),
+            ("parent_finalization_seconds", self.parent_finalization_seconds),
+        ):
+            if type(value) is not int:
+                raise ValueError(f"{name} must be an integer")
+            if value < 0:
+                raise ValueError(f"{name} cannot be negative")
+        if self.soft_timeout_seconds < 1:
+            raise ValueError("soft_timeout_seconds must be positive")
+        if self.hard_timeout_seconds <= self.soft_timeout_seconds:
+            raise ValueError("hard_timeout_seconds must be greater than soft_timeout_seconds")
+        if self.max_work_units < 1:
+            raise ValueError("max_work_units must be positive")
+        if self.max_implementation_attempts < 1:
+            raise ValueError("max_implementation_attempts must be positive")
+        if self.parent_finalization_seconds < 1:
+            raise ValueError("parent_finalization_seconds must be positive")
+
+
+REASONING_ROLLOUT_MODES = ("legacy", "shadow", "adaptive")
+REASONING_EFFORTS = ("high", "xhigh", "max")
+
+
+@dataclass(frozen=True)
+class ReasoningRolloutPolicy:
+    """Optional efficient-worker reasoning rollout configuration."""
+
+    mode: str = "shadow"
+    minimum: str = "high"
+    routine: str = "high"
+    complex: str = "xhigh"
+    critical: str = "max"
+
+    @classmethod
+    def from_dict(cls, value: Any) -> "ReasoningRolloutPolicy":
+        if type(value) is not dict:
+            raise ValueError("reasoning rollout policy must be an object")
+        fields = ("mode", "minimum", "routine", "complex", "critical")
+        unknown = sorted(set(value).difference(fields))
+        if unknown:
+            raise ValueError(f"reasoning rollout policy has unknown fields: {unknown}")
+        policy = cls(**{name: value[name] for name in fields if name in value})
+        policy.validate()
+        return policy
+
+    def validate(self) -> None:
+        if type(self.mode) is not str or self.mode not in REASONING_ROLLOUT_MODES:
+            raise ValueError(f"invalid reasoning rollout mode: {self.mode}")
+        for name, value in (
+            ("minimum", self.minimum),
+            ("routine", self.routine),
+            ("complex", self.complex),
+            ("critical", self.critical),
+        ):
+            if type(value) is not str or value not in REASONING_EFFORTS:
+                raise ValueError(f"invalid reasoning rollout {name}: {value}")
+
+
+@dataclass(frozen=True)
+class ReasoningRolloutDecision:
+    """Planner output comparing legacy and rollout-selected Worker effort."""
+
+    mode: str
+    legacy_worker_reasoning: str
+    proposed_worker_reasoning: str
+    selected_worker_reasoning: str
+    applied: bool
+
+    def validate(self) -> None:
+        if type(self.mode) is not str or self.mode not in REASONING_ROLLOUT_MODES:
+            raise ValueError(f"invalid reasoning rollout mode: {self.mode}")
+        for name, value in (
+            ("legacy_worker_reasoning", self.legacy_worker_reasoning),
+            ("proposed_worker_reasoning", self.proposed_worker_reasoning),
+            ("selected_worker_reasoning", self.selected_worker_reasoning),
+        ):
+            if type(value) is not str or value not in REASONING_EFFORTS:
+                raise ValueError(f"invalid {name}: {value}")
+        if type(self.applied) is not bool:
+            raise ValueError("reasoning rollout applied must be boolean")
+
+
+@dataclass(frozen=True)
+class StagePolicy:
+    """Strategy-owned lifecycle preference for one delegated execution stage.
+
+    Soft timeout is advisory convergence/checkpoint budget and never implies
+    cancellation by itself. `max_worker_repair_attempts` bounds Worker-local
+    validation/fix loops independently from Parent-level repair cycles.
+
+    `work_unit_mode=bounded` describes logical acceptance-bounded transactions,
+    not permission for overlapping writers. `retry_review` is a read-only review
+    fallback and must never reopen writable implementation scope.
+    """
+
+    join_policy: str
+    min_successful_workers: int
+    idle_timeout_seconds: int
+    hard_timeout_seconds: int
+    cancel_if_superseded: bool = True
+    cancel_stragglers_after_quorum: bool = False
+    fallback_policy: str = "parent_delta"
+    soft_timeout_seconds: int | None = None
+    checkpoint_rearm_seconds: int | None = None
+    max_worker_repair_attempts: int | None = None
+    work_unit_mode: str = "single"
+    minimum_work_units: int = 1
+    join_between_work_units: bool = False
+    maximum_work_units: int | None = None
+    require_write_paths: bool = False
+
+    def validate(self) -> None:
+        for name, value in (
+            ("min_successful_workers", self.min_successful_workers),
+            ("idle_timeout_seconds", self.idle_timeout_seconds),
+            ("hard_timeout_seconds", self.hard_timeout_seconds),
+            ("minimum_work_units", self.minimum_work_units),
+        ):
+            if type(value) is not int:
+                raise ValueError(f"{name} must be an integer")
+        if self.join_policy not in JOIN_POLICIES:
+            raise ValueError(f"invalid join policy: {self.join_policy}")
+        if self.min_successful_workers < 0:
+            raise ValueError("min_successful_workers cannot be negative")
+        if self.join_policy == "opportunistic" and self.min_successful_workers != 0:
+            raise ValueError("opportunistic stages must use min_successful_workers=0")
+        if self.join_policy in {"quorum", "required"} and self.min_successful_workers < 1:
+            raise ValueError(f"{self.join_policy} stages require at least one successful worker")
+        if self.idle_timeout_seconds < 1:
+            raise ValueError("idle_timeout_seconds must be positive")
+        if self.hard_timeout_seconds < self.idle_timeout_seconds:
+            raise ValueError("hard_timeout_seconds must be >= idle_timeout_seconds")
+        if self.soft_timeout_seconds is not None:
+            if type(self.soft_timeout_seconds) is not int:
+                raise ValueError("soft_timeout_seconds must be an integer when set")
+            if self.soft_timeout_seconds < 1:
+                raise ValueError("soft_timeout_seconds must be positive when set")
+            if self.soft_timeout_seconds >= self.hard_timeout_seconds:
+                raise ValueError("soft_timeout_seconds must be lower than hard_timeout_seconds")
+        if self.checkpoint_rearm_seconds is not None:
+            if type(self.checkpoint_rearm_seconds) is not int:
+                raise ValueError("checkpoint_rearm_seconds must be an integer when set")
+            if self.checkpoint_rearm_seconds < 1:
+                raise ValueError("checkpoint_rearm_seconds must be positive when set")
+            if self.checkpoint_rearm_seconds >= self.hard_timeout_seconds:
+                raise ValueError("checkpoint_rearm_seconds must be lower than hard_timeout_seconds")
+            if (
+                self.soft_timeout_seconds is not None
+                and self.soft_timeout_seconds + self.checkpoint_rearm_seconds >= self.hard_timeout_seconds
+            ):
+                raise ValueError(
+                    "checkpoint_rearm_seconds must leave time for a second checkpoint before hard_timeout_seconds"
+                )
+        if self.max_worker_repair_attempts is not None:
+            if type(self.max_worker_repair_attempts) is not int:
+                raise ValueError("max_worker_repair_attempts must be an integer when set")
+            if self.max_worker_repair_attempts < 0:
+                raise ValueError("max_worker_repair_attempts cannot be negative")
+        if self.work_unit_mode not in WORK_UNIT_MODES:
+            raise ValueError(f"invalid work_unit_mode: {self.work_unit_mode}")
+        if self.minimum_work_units < 1:
+            raise ValueError("minimum_work_units must be positive")
+        if type(self.join_between_work_units) is not bool:
+            raise ValueError("join_between_work_units must be boolean")
+        if self.maximum_work_units is not None:
+            if type(self.maximum_work_units) is not int:
+                raise ValueError("maximum_work_units must be an integer when set")
+            if self.maximum_work_units < 1:
+                raise ValueError("maximum_work_units must be positive when set")
+        if self.work_unit_mode == "single":
+            if self.minimum_work_units != 1:
+                raise ValueError("single work-unit mode requires minimum_work_units=1")
+            if self.join_between_work_units:
+                raise ValueError("single work-unit mode cannot join between work units")
+            if self.maximum_work_units is not None and self.maximum_work_units != 1:
+                raise ValueError("single work-unit mode requires maximum_work_units=1")
+        elif not self.join_between_work_units:
+            raise ValueError("bounded work-unit mode requires a Parent join between work units")
+        elif self.maximum_work_units is not None and self.maximum_work_units < self.minimum_work_units:
+            raise ValueError("bounded work-unit mode requires maximum_work_units >= minimum_work_units")
+        if type(self.require_write_paths) is not bool:
+            raise ValueError("require_write_paths must be boolean")
+        if self.fallback_policy not in FALLBACK_POLICIES:
+            raise ValueError(f"invalid fallback policy: {self.fallback_policy}")
+
+
+def standard_lifecycle(_task: Task, stage: str) -> StagePolicy:
+    """V11-safe balanced lifecycle baseline for future strategies."""
+    if stage == "exploration":
+        return StagePolicy("quorum", 1, 180, 1200, True, True, "parent_delta")
+    if stage == "implementation":
+        return StagePolicy(
+            "required",
+            1,
+            240,
+            2400,
+            False,
+            False,
+            "replan",
+            soft_timeout_seconds=1200,
+            checkpoint_rearm_seconds=240,
+            max_worker_repair_attempts=1,
+            work_unit_mode="single",
+            minimum_work_units=1,
+            join_between_work_units=False,
+            maximum_work_units=1,
+            require_write_paths=False,
+        )
+    if stage == "review":
+        return StagePolicy("required", 1, 180, 1800, True, False, "retry_review")
+    raise ValueError(f"invalid lifecycle stage: {stage}")
+
+
+@dataclass(frozen=True)
+class StrategySpec:
+    name: str
+    description: str
+    adaptive_route: RouteFn
+    effort: EffortFn
+    worker_budget: BudgetFn
+    independent_review: PredicateFn
+    capability: CapabilityFn = worker_capability
+    exploration_bonus: DemandFn = zero_demand
+    reviewer_bonus: DemandFn = zero_demand
+    notes: NotesFn = no_notes
+    lifecycle: LifecycleFn = standard_lifecycle
+    allow_parallel_write: bool = False
+    quota_sensitive: bool = False
+    task_budget: TaskBudgetFn | None = None
+    reasoning_rollout: ReasoningRolloutFn | None = None
+
+
+def standard_effort(task: Task, role: str) -> str:
+    """Cheap-parent / strong-worker baseline."""
+    if task.complexity == "critical" or task.risk == "critical":
+        return "xhigh" if role == "parent" else "max"
+    return "high" if role == "parent" else "xhigh"
+
+
+def never(_task: Task) -> bool:
+    return False
+
+
+def small_low_risk_is_direct(task: Task) -> bool:
+    return task.complexity == "small" and task.risk in {"low", "medium"}

codex_flow/data/scripts/strategies/efficient.py

@@ -0,0 +1,158 @@
+"""Quota-efficient strategy."""
+from __future__ import annotations
+
+from .base import (
+    StagePolicy,
+    ReasoningRolloutDecision,
+    StrategySpec,
+    TaskBudgetPolicy,
+    WorkerBudget,
+    never,
+    small_low_risk_is_direct,
+    standard_effort,
+)
+
+
+_EFFORT_RANK = {"high": 0, "xhigh": 1, "max": 2}
+
+
+def _max_effort(*values: str) -> str:
+    return max(values, key=lambda value: _EFFORT_RANK[value])
+
+
+def adaptive_route(task) -> str:
+    if small_low_risk_is_direct(task):
+        return "direct"
+    return "delegate" if task.iteration_intensity != "one-shot" or task.scope in {"cross-module", "repo-wide"} else "direct"
+
+
+def worker_budget(task) -> WorkerBudget:
+    if task.complexity == "critical" or task.scope == "repo-wide" or task.iteration_intensity == "heavy-loop":
+        return WorkerBudget(2, 2, 1, 5, "low")
+    if task.uncertainty == "high" or task.exploration_need == "high":
+        return WorkerBudget(2, 2, 1, 5, "low")
+    return WorkerBudget(1, 1, 1, 2, "low")
+
+
+def implementation_soft_timeout(task) -> int:
+    if task.complexity == "critical" or task.risk == "critical":
+        return 1200
+    if task.complexity == "complex" or task.scope == "repo-wide" or task.iteration_intensity == "heavy-loop":
+        return 900
+    return 600
+
+
+def implementation_checkpoint_rearm_seconds(task) -> int:
+    if task.complexity == "critical" or task.risk == "critical":
+        return 300
+    if (
+        task.complexity == "complex"
+        or task.scope in {"cross-module", "repo-wide"}
+        or task.iteration_intensity == "heavy-loop"
+    ):
+        return 240
+    return 180
+
+
+def implementation_repair_attempts(task) -> int:
+    if (
+        task.complexity in {"complex", "critical"}
+        or task.risk == "critical"
+        or task.scope == "repo-wide"
+        or task.iteration_intensity == "heavy-loop"
+    ):
+        return 2
+    return 1
+
+
+def implementation_minimum_work_units(_task) -> int:
+    return 1
+
+
+def implementation_maximum_work_units(task) -> int:
+    if task.scope == "repo-wide" or task.iteration_intensity == "heavy-loop":
+        semantic_maximum = 3
+    elif task.complexity in {"complex", "critical"} or task.scope == "cross-module" or task.risk == "critical":
+        semantic_maximum = 2
+    else:
+        semantic_maximum = 1
+    topology_floor = min(task.writable_workstreams, worker_budget(task).max_implementers)
+    return max(semantic_maximum, topology_floor)
+
+
+def task_budget(task) -> TaskBudgetPolicy:
+    max_work_units = implementation_maximum_work_units(task)
+    return TaskBudgetPolicy(
+        soft_timeout_seconds=1500,
+        hard_timeout_seconds=1800,
+        max_work_units=max_work_units,
+        max_implementation_attempts=max_work_units + 1,
+        max_replans=1,
+        max_replacements=1,
+        max_review_attempts=2,
+        parent_finalization_seconds=150,
+    )
+
+
+def reasoning_rollout(task, _role: str, policy, parent_reasoning: str, legacy_worker_reasoning: str) -> ReasoningRolloutDecision:
+    policy.validate()
+    if task.complexity == "critical" or task.risk == "critical":
+        class_target = policy.critical
+    elif task.complexity == "complex" or task.risk == "high":
+        class_target = policy.complex
+    else:
+        class_target = policy.routine
+    proposed = _max_effort(class_target, policy.minimum, parent_reasoning)
+    selected = proposed if policy.mode == "adaptive" else legacy_worker_reasoning
+    decision = ReasoningRolloutDecision(
+        mode=policy.mode,
+        legacy_worker_reasoning=legacy_worker_reasoning,
+        proposed_worker_reasoning=proposed,
+        selected_worker_reasoning=selected,
+        applied=policy.mode == "adaptive",
+    )
+    decision.validate()
+    return decision
+
+
+def lifecycle(task, stage: str) -> StagePolicy:
+    if stage == "exploration":
+        return StagePolicy("quorum", 1, 120, 900, True, True, "parent_delta")
+    if stage == "implementation":
+        minimum_work_units = implementation_minimum_work_units(task)
+        maximum_work_units = implementation_maximum_work_units(task)
+        bounded_mode = maximum_work_units > 1
+        return StagePolicy(
+            "required", 1, 180, 1800, False, False, "replan",
+            soft_timeout_seconds=implementation_soft_timeout(task),
+            checkpoint_rearm_seconds=implementation_checkpoint_rearm_seconds(task),
+            max_worker_repair_attempts=implementation_repair_attempts(task),
+            work_unit_mode="bounded" if bounded_mode else "single",
+            minimum_work_units=minimum_work_units,
+            join_between_work_units=bounded_mode,
+            maximum_work_units=maximum_work_units,
+            require_write_paths=bounded_mode,
+        )
+    if stage == "review":
+        return StagePolicy("quorum", 1, 150, 1200, True, True, "retry_review")
+    raise ValueError(f"invalid lifecycle stage: {stage}")
+
+
+STRATEGY = StrategySpec(
+    name="efficient",
+    description="minimize expensive parent usage and total waste while offloading deep execution to efficient workers",
+    adaptive_route=adaptive_route,
+    effort=standard_effort,
+    worker_budget=worker_budget,
+    independent_review=never,
+    lifecycle=lifecycle,
+    # Efficient workers are deliberately cheap enough that proven parallel
+    # implementation should not require an aggressive fan-out override.
+    allow_parallel_write=True,
+    # Keep quota pressure focused on expensive Parent usage. The strategy's own
+    # low-speculation WorkerBudget remains the hard envelope (2 implementers,
+    # 5 total Workers at the largest task classes).
+    quota_sensitive=False,
+    task_budget=task_budget,
+    reasoning_rollout=reasoning_rollout,
+)