cowork-flow 0.0.47 → 0.0.49

package/template/.cowork-flow/scripts/services/task_lifecycle.py

@@ -8,7 +8,7 @@ from collections.abc import Callable
 from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Union
 
 from infra.storage.unit_of_work import (
     FaultInjector,
@@ -17,6 +17,12 @@ from infra.storage.unit_of_work import (
 )
 from runtime.session_state import build_active_task_session
 from services.lifecycle_checks import LifecycleCheckResult, LifecycleCheckRunner
+from services.lifecycle_policy import (
+    LifecycleExecutionPolicy,
+    LifecyclePolicyFailure,
+    resolve_execution_policy,
+    start_readiness_failure,
+)
 from kernel.task_state import transition_blockers
 from services.task_repository import TaskRepository, TaskRepositoryError
 
@@ -57,6 +63,15 @@ class LifecyclePreflightFailure:
     hint: str = ""
 
 
+@dataclass(frozen=True)
+class LifecycleTransition:
+    """Stable status transition facts for lifecycle results."""
+
+    previous_status: str | None
+    next_status: str
+    changed: bool
+
+
 @dataclass(frozen=True)
 class LifecycleResult:
     """Structured lifecycle outcome for delivery-layer rendering."""
@@ -71,9 +86,15 @@ class LifecycleResult:
     check_result: object | None = None
     active_task_path: str | None = None
     repository_error: TaskRepositoryError | None = None
+    transition: LifecycleTransition | None = None
+    execution_policy: LifecycleExecutionPolicy | None = None
+    emitted_events: tuple[str, ...] = ()
 
 
-Preflight = Callable[[Path], Optional[LifecyclePreflightFailure]]
+Preflight = Callable[
+    [Path],
+    Optional[Union[LifecyclePreflightFailure, LifecyclePolicyFailure]],
+]
 
 
 class TaskLifecycleService:
@@ -104,12 +125,14 @@ class TaskLifecycleService:
         self,
         task: str | Path,
         *,
-        allow_spec_file_modifications: bool = False,
+        allow_spec_file_modifications: bool | None = None,
+        execution_context: object | None = None,
     ) -> LifecycleResult:
         return self.execute(
             REVIEW_STAGE,
             task,
             allow_spec_file_modifications=allow_spec_file_modifications,
+            execution_context=execution_context,
         )
 
     def complete(
@@ -117,13 +140,15 @@ class TaskLifecycleService:
         task: str | Path,
         *,
         completed_at: str | None = None,
-        allow_spec_file_modifications: bool = False,
+        allow_spec_file_modifications: bool | None = None,
+        execution_context: object | None = None,
     ) -> LifecycleResult:
         return self.execute(
             COMPLETE_STAGE,
             task,
             completed_at=completed_at,
             allow_spec_file_modifications=allow_spec_file_modifications,
+            execution_context=execution_context,
         )
 
     def execute(
@@ -132,20 +157,27 @@ class TaskLifecycleService:
         task: str | Path,
         *,
         preflight: Preflight | None = None,
-        allow_spec_file_modifications: bool = False,
+        allow_spec_file_modifications: bool | None = None,
         completed_at: str | None = None,
+        execution_context: object | None = None,
     ) -> LifecycleResult:
         """Resolve, preflight, validate, check, and persist one transition."""
         task_dir = self.repository.resolve(task)
+        execution_policy = resolve_execution_policy(
+            self.repo_root,
+            execution_context,
+            allow_spec_file_modifications=allow_spec_file_modifications,
+        )
         prepared = self._prepare_transition(stage, task_dir, preflight)
         if isinstance(prepared, LifecycleResult):
             return prepared
-        task_data, already_at_target = prepared
+        task_data, already_at_target, transition = prepared
 
         checked = self._run_stage_checks(
             stage,
             task_dir,
-            allow_spec_file_modifications=allow_spec_file_modifications,
+            transition=transition,
+            execution_policy=execution_policy,
         )
         if isinstance(checked, LifecycleResult):
             return checked
@@ -156,6 +188,8 @@ class TaskLifecycleService:
                 stage,
                 task_dir,
                 check_result,
+                transition=transition,
+                execution_policy=execution_policy,
             )
 
         return self._persist_transition_result(
@@ -164,6 +198,8 @@ class TaskLifecycleService:
             task_data,
             check_result,
             completed_at,
+            transition=transition,
+            execution_policy=execution_policy,
         )
 
     def _prepare_transition(
@@ -171,35 +207,50 @@ class TaskLifecycleService:
         stage: LifecycleStage,
         task_dir: Path,
         preflight: Preflight | None,
-    ) -> tuple[dict, bool] | LifecycleResult:
+    ) -> tuple[dict, bool, LifecycleTransition] | LifecycleResult:
         task_data_or_failure = self._load_transition_task(stage, task_dir)
         if isinstance(task_data_or_failure, LifecycleResult):
             return task_data_or_failure
         task_data = task_data_or_failure
 
-        already_at_target = task_data.get("status") == stage.target_status
+        transition = self._transition_for(stage, task_data)
+        already_at_target = not transition.changed
         idempotent = self._early_idempotent_result(
             stage,
             task_dir,
             already_at_target,
+            transition,
         )
         if idempotent is not None:
             return idempotent
 
-        preflight_failure = self._run_preflight(stage, task_dir, preflight)
+        preflight_failure = self._run_preflight(
+            stage,
+            task_dir,
+            preflight,
+            transition,
+        )
         if preflight_failure is not None:
             return preflight_failure
 
-        transition_failure = self._validate_transition(stage, task_dir, task_data)
+        transition_failure = self._validate_transition(
+            stage,
+            task_dir,
+            task_data,
+            transition,
+        )
         if transition_failure is not None:
             return transition_failure
-        return task_data, already_at_target
+        return task_data, already_at_target, transition
 
     def _validated_idempotent_result(
         self,
         stage: LifecycleStage,
         task_dir: Path,
         check_result: object,
+        *,
+        transition: LifecycleTransition,
+        execution_policy: LifecycleExecutionPolicy,
     ) -> LifecycleResult:
         return LifecycleResult(
             ok=True,
@@ -207,6 +258,9 @@ class TaskLifecycleService:
             stage=stage,
             task_dir=task_dir,
             check_result=check_result,
+            transition=transition,
+            execution_policy=execution_policy,
+            emitted_events=self._success_events(stage),
         )
 
     def _persist_transition_result(
@@ -216,11 +270,15 @@ class TaskLifecycleService:
         task_data: dict,
         check_result: object,
         completed_at: str | None,
+        *,
+        transition: LifecycleTransition,
+        execution_policy: LifecycleExecutionPolicy,
     ) -> LifecycleResult:
         session_state_or_failure = self._build_session_state(
             stage,
             task_dir,
             check_result,
+            transition,
         )
         if isinstance(session_state_or_failure, LifecycleResult):
             return session_state_or_failure
@@ -244,6 +302,9 @@ class TaskLifecycleService:
             task_dir=task_dir,
             check_result=check_result,
             active_task_path=active_task_path,
+            transition=transition,
+            execution_policy=execution_policy,
+            emitted_events=self._success_events(stage),
         )
 
     def _load_transition_task(
@@ -277,6 +338,7 @@ class TaskLifecycleService:
         stage: LifecycleStage,
         task_dir: Path,
         already_at_target: bool,
+        transition: LifecycleTransition,
     ) -> LifecycleResult | None:
         if not already_at_target or stage.name != START_STAGE.name:
             return None
@@ -290,6 +352,8 @@ class TaskLifecycleService:
                 if stage.activates_session
                 else None
             ),
+            transition=transition,
+            emitted_events=self._success_events(stage),
         )
 
     def _run_preflight(
@@ -297,10 +361,14 @@ class TaskLifecycleService:
         stage: LifecycleStage,
         task_dir: Path,
         preflight: Preflight | None,
+        transition: LifecycleTransition,
     ) -> LifecycleResult | None:
-        if preflight is None:
-            return None
-        failure = preflight(task_dir)
+        if preflight is None and stage.name == START_STAGE.name:
+            failure = start_readiness_failure(self.repo_root, task_dir)
+        elif preflight is None:
+            failure = None
+        else:
+            failure = preflight(task_dir)
         if failure is None:
             return None
         return self._failure(
@@ -310,6 +378,7 @@ class TaskLifecycleService:
             title=failure.title,
             blockers=failure.blockers,
             hint=failure.hint,
+            transition=transition,
         )
 
     def _validate_transition(
@@ -317,6 +386,7 @@ class TaskLifecycleService:
         stage: LifecycleStage,
         task_dir: Path,
         task_data: dict,
+        transition: LifecycleTransition,
     ) -> LifecycleResult | None:
         blockers = transition_blockers(
             task_data.get("status"),
@@ -329,6 +399,7 @@ class TaskLifecycleService:
             task_dir,
             "LIFECYCLE-TRANSITION-001",
             blockers=tuple(blockers),
+            transition=transition,
         )
 
     def _run_stage_checks(
@@ -336,19 +407,26 @@ class TaskLifecycleService:
         stage: LifecycleStage,
         task_dir: Path,
         *,
-        allow_spec_file_modifications: bool,
+        transition: LifecycleTransition,
+        execution_policy: LifecycleExecutionPolicy,
     ) -> object | LifecycleResult:
         if stage.name == START_STAGE.name:
             check_result = LifecycleCheckResult(stage=stage.name)
         elif stage.name == REVIEW_STAGE.name:
             check_result = self.check_runner.review(
                 task_dir,
-                allow_spec_file_modifications=allow_spec_file_modifications,
+                allow_spec_file_modifications=(
+                    execution_policy.allow_spec_file_modifications
+                ),
+                execution_policy=execution_policy,
             )
         elif stage.name == COMPLETE_STAGE.name:
             check_result = self.check_runner.complete(
                 task_dir,
-                allow_spec_file_modifications=allow_spec_file_modifications,
+                allow_spec_file_modifications=(
+                    execution_policy.allow_spec_file_modifications
+                ),
+                execution_policy=execution_policy,
             )
         else:
             check_result = LifecycleCheckResult(
@@ -363,6 +441,8 @@ class TaskLifecycleService:
             "LIFECYCLE-CHECK-001",
             blockers=tuple(check_result.blockers),
             check_result=check_result,
+            transition=transition,
+            execution_policy=execution_policy,
         )
 
     def _build_session_state(
@@ -370,6 +450,7 @@ class TaskLifecycleService:
         stage: LifecycleStage,
         task_dir: Path,
         check_result: object,
+        transition: LifecycleTransition,
     ) -> tuple[object | None, str | None] | LifecycleResult:
         if not stage.activates_session:
             return None, None
@@ -384,6 +465,7 @@ class TaskLifecycleService:
                 task_dir,
                 "LIFECYCLE-CONTEXT-001",
                 check_result=check_result,
+                transition=transition,
             )
         return session_state, session_state[2].task_path
 
@@ -435,6 +517,52 @@ class TaskLifecycleService:
             )
         return None
 
+    def start_readiness(self, task: str | Path) -> LifecycleResult:
+        """Check start readiness without mutating task or session state."""
+        task_dir = self.repository.resolve(task)
+        task_data_or_failure = self._load_transition_task(START_STAGE, task_dir)
+        transition = None
+        if isinstance(task_data_or_failure, LifecycleResult):
+            return task_data_or_failure
+        transition = self._transition_for(START_STAGE, task_data_or_failure)
+        failure = start_readiness_failure(self.repo_root, task_dir)
+        if failure is not None:
+            return self._failure(
+                START_STAGE,
+                task_dir,
+                failure.code,
+                title=failure.title,
+                blockers=failure.blockers,
+                hint=failure.hint,
+                transition=transition,
+            )
+        return LifecycleResult(
+            ok=True,
+            code="TASK-READINESS-OK",
+            stage=START_STAGE,
+            task_dir=task_dir,
+            transition=transition,
+        )
+
+    def _transition_for(
+        self,
+        stage: LifecycleStage,
+        task_data: dict,
+    ) -> LifecycleTransition:
+        previous = task_data.get("status")
+        previous_status = previous if isinstance(previous, str) else None
+        return LifecycleTransition(
+            previous_status=previous_status,
+            next_status=stage.target_status,
+            changed=previous_status != stage.target_status,
+        )
+
+    @staticmethod
+    def _success_events(stage: LifecycleStage) -> tuple[str, ...]:
+        if stage.name == START_STAGE.name:
+            return ("after_start",)
+        return ()
+
     def _operation_id(
         self,
         stage: LifecycleStage,
@@ -472,6 +600,9 @@ class TaskLifecycleService:
         title: str = "",
         hint: str = "",
         check_result: object | None = None,
+        transition: LifecycleTransition | None = None,
+        execution_policy: LifecycleExecutionPolicy | None = None,
+        emitted_events: tuple[str, ...] = (),
     ) -> LifecycleResult:
         return LifecycleResult(
             ok=False,
@@ -482,6 +613,9 @@ class TaskLifecycleService:
             title=title,
             hint=hint,
             check_result=check_result,
+            transition=transition,
+            execution_policy=execution_policy,
+            emitted_events=emitted_events,
         )
 
     @staticmethod
@@ -491,6 +625,9 @@ class TaskLifecycleService:
         error: TaskRepositoryError,
         *,
         check_result: object | None = None,
+        transition: LifecycleTransition | None = None,
+        execution_policy: LifecycleExecutionPolicy | None = None,
+        emitted_events: tuple[str, ...] = (),
     ) -> LifecycleResult:
         return LifecycleResult(
             ok=False,

package/template/.cowork-flow/scripts/services/task_routing.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 from pathlib import Path
 
 from infra.skill_manifest import SkillManifestError, action_metadata
@@ -19,38 +20,61 @@ from kernel.workflow_route import (
 )
 
 
-def _run_command(
-    task_path: str | None,
-    *,
-    intent: str | None = None,
-    create: bool = False,
-    commit: bool = False,
-) -> str:
-    parts = ["./.cowork-flow/run", "task", "next"]
-    if task_path:
-        parts.append(task_path)
-    parts.append("--run")
-    if intent:
-        parts.extend(["--intent", intent])
-    if create:
-        parts.extend(["--title", '"<title>"', "--slug", "<task-name>", "--assignee", "<name>"])
-    if commit:
-        parts.append("--commit")
-    return " ".join(parts)
-
-
-def _action_command(action_id: str, task_path: str | None, template: str | None) -> str | None:
-    if template:
-        return template.replace("<task-dir>", task_path or "<task-dir>")
-    if action_id in {"start_task", "implement_change"}:
-        return _run_command(task_path)
-    return None
-
-
-def _diagnostics_command(task_path: str | None, template: str | None) -> str | None:
-    if template:
-        return template.replace("<task-dir>", task_path or "<task-dir>")
-    return None
+@dataclass(frozen=True)
+class ActionContract:
+    """Internal action facts before adapter compatibility aliases are added."""
+
+    action_id: str
+    label: str
+    activated_skill: str | None
+    command: str | None
+    diagnostics_command: str | None
+    mutates_state: bool
+    lifecycle_check: str | None
+    runnable: bool
+    blockers: tuple[str, ...]
+
+    def to_payload(self) -> dict[str, object]:
+        return {
+            "id": self.action_id,
+            "label": self.label,
+            "activatedSkill": self.activated_skill,
+            "command": self.command,
+            "diagnosticsCommand": self.diagnostics_command,
+            "mutatesState": self.mutates_state,
+            "lifecycleCheck": self.lifecycle_check,
+            "runnable": self.runnable,
+            "blockers": list(self.blockers),
+        }
+
+
+@dataclass(frozen=True)
+class RouteContract:
+    """Internal route facts before CLI adapter rendering."""
+
+    status: str
+    allowed_operations: tuple[str, ...]
+    required_artifacts: tuple[str, ...]
+    recommended_skill: str | None
+    blockers: tuple[str, ...]
+    action: ActionContract
+
+    def to_payload(self) -> dict[str, object]:
+        action = self.action.to_payload()
+        return {
+            "status": self.status,
+            "allowedOperations": list(self.allowed_operations),
+            "requiredArtifacts": list(self.required_artifacts),
+            "recommendedSkill": self.recommended_skill,
+            "blockers": list(self.blockers),
+            "nextAction": self.action.action_id,
+            "activatedSkill": self.action.activated_skill,
+            "actionCommand": self.action.command,
+            "diagnosticsCommand": self.action.diagnostics_command,
+            "mutatesState": self.action.mutates_state,
+            "lifecycleCheck": self.action.lifecycle_check,
+            "action": action,
+        }
 
 
 def _action_contract(
@@ -61,7 +85,7 @@ def _action_contract(
     active_target: bool,
     intent: str,
     repo_root: Path | None = None,
-) -> dict[str, object]:
+) -> ActionContract:
     action = _kernel_action_contract(
         status=status,
         blockers=blockers,
@@ -87,25 +111,21 @@ def _action_contract(
     if owner is not None:
         if owner.mutates_state != bool(action["mutatesState"]):
             action_blockers.append(f"Skill owner transition mismatch: {action_id}")
-        if owner.lifecycle_check != action["runtimeGate"]:
+        if owner.lifecycle_check != action["lifecycleCheck"]:
             action_blockers.append(f"Skill owner lifecycle mismatch: {action_id}")
 
-    lifecycle_check = owner.lifecycle_check if owner is not None else action["runtimeGate"]
-    return {
-        "id": action_id,
-        "label": owner.label if owner is not None else action_id,
-        "activatedSkill": owner.skill if owner is not None else None,
-        "command": _action_command(action_id, task_path, owner.command if owner else None),
-        "diagnosticsCommand": _diagnostics_command(
-            task_path,
-            owner.diagnostics_command if owner else None,
-        ),
-        "mutatesState": action["mutatesState"],
-        "lifecycleCheck": lifecycle_check,
-        "runtimeGate": lifecycle_check,
-        "runnable": bool(action["runnable"]) and not action_blockers,
-        "blockers": action_blockers,
-    }
+    lifecycle_check = owner.lifecycle_check if owner is not None else action["lifecycleCheck"]
+    return ActionContract(
+        action_id=action_id,
+        label=owner.label if owner is not None else action_id,
+        activated_skill=owner.skill if owner is not None else None,
+        command=owner.command if owner is not None else None,
+        diagnostics_command=owner.diagnostics_command if owner is not None else None,
+        mutates_state=bool(action["mutatesState"]),
+        lifecycle_check=lifecycle_check,
+        runnable=bool(action["runnable"]) and not action_blockers,
+        blockers=tuple(action_blockers),
+    )
 
 
 def route_request(
@@ -140,20 +160,13 @@ def route_request(
         intent=intent,
         repo_root=repo_root,
     )
-    route_blockers = list(action["blockers"])
-    recommended = action["activatedSkill"] if intent_allowed and not route_blockers else None
-    return {
-        "status": status,
-        "allowedOperations": operations,
-        "requiredArtifacts": _required_artifacts(status),
-        "recommendedSkill": recommended,
-        "blockers": route_blockers,
-        "nextAction": action["id"],
-        "activatedSkill": action["activatedSkill"],
-        "actionCommand": action["command"],
-        "diagnosticsCommand": action["diagnosticsCommand"],
-        "mutatesState": action["mutatesState"],
-        "lifecycleCheck": action["lifecycleCheck"],
-        "runtimeGate": action["runtimeGate"],
-        "action": action,
-    }
+    route_blockers = action.blockers
+    recommended = action.activated_skill if intent_allowed and not route_blockers else None
+    return RouteContract(
+        status=status,
+        allowed_operations=tuple(operations),
+        required_artifacts=tuple(_required_artifacts(status)),
+        recommended_skill=recommended,
+        blockers=route_blockers,
+        action=action,
+    ).to_payload()