cowork-flow 0.0.47 → 0.0.49

package/template/.cowork-flow/scripts/infra/storage/operation_log.py

@@ -70,3 +70,43 @@ class OperationLog:
             if record.get("phase") not in FINAL_PHASES:
                 records.append(record)
         return tuple(records)
+    def pending_facts(self) -> tuple[dict, ...]:
+        """Return read-only facts about non-final operation records."""
+        if not self.operations_dir.is_dir():
+            return ()
+        facts: list[dict] = []
+        for path in sorted(self.operations_dir.glob("*.json")):
+            try:
+                record = self.state_store.load(path).data
+            except StateStoreError as error:
+                facts.append(
+                    {
+                        "path": str(path),
+                        "phase": "unreadable",
+                        "error": {
+                            "code": error.code,
+                            "path": str(error.path),
+                            "detail": error.detail,
+                        },
+                    }
+                )
+                continue
+            phase = record.get("phase")
+            if phase == "committed":
+                continue
+            participants = record.get("participants")
+            facts.append(
+                {
+                    "path": str(path),
+                    "operation_id": str(record.get("operation_id") or path.stem),
+                    "kind": str(record.get("kind") or "unknown"),
+                    "phase": str(phase or "unknown"),
+                    "participant_count": (
+                        len(participants)
+                        if isinstance(participants, list)
+                        else 0
+                    ),
+                    "error": record.get("error"),
+                }
+            )
+        return tuple(facts)

package/template/.cowork-flow/scripts/infra/storage/state_store.py

@@ -3,16 +3,21 @@
 
 from __future__ import annotations
 
+import errno
 import json
+import math
 import os
 import time
 from contextlib import contextmanager
 from dataclasses import dataclass
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Iterator
 
 
 STATE_METADATA_KEY = "_state"
+LOCK_METADATA_SCHEMA_VERSION = 1
+DEFAULT_STALE_LOCK_SECONDS = 30 * 60
 ATOMIC_REPLACE_ATTEMPTS = 5
 ATOMIC_REPLACE_RETRY_SECONDS = 0.01
 
@@ -36,6 +41,46 @@ class StateSnapshot:
     exists: bool
 
 
+@dataclass(frozen=True)
+class LockInfo:
+    """Read-only facts about a StateStore lock file."""
+
+    lock_path: Path
+    target: Path
+    exists: bool
+    pid: int | None
+    created_at: str | None
+    age_seconds: float | None
+    owner_availability: str
+    status: str
+    detail: str
+
+    @property
+    def owner_available(self) -> bool | None:
+        if self.owner_availability == "available":
+            return True
+        if self.owner_availability == "missing":
+            return False
+        return None
+
+    def to_dict(self) -> dict[str, object]:
+        data: dict[str, object] = {
+            "lockPath": str(self.lock_path),
+            "target": str(self.target),
+            "exists": self.exists,
+            "ownerAvailability": self.owner_availability,
+            "status": self.status,
+            "detail": self.detail,
+        }
+        if self.pid is not None:
+            data["pid"] = self.pid
+        if self.created_at is not None:
+            data["createdAt"] = self.created_at
+        if self.age_seconds is not None:
+            data["ageSeconds"] = self.age_seconds
+        return data
+
+
 class StateStore:
     """Read and compare-and-swap JSON state documents."""
 
@@ -117,6 +162,113 @@ class StateStore:
                 ) from error
             return True
 
+    def inspect_lock(
+        self,
+        path: str | Path,
+        *,
+        stale_after_seconds: float = DEFAULT_STALE_LOCK_SECONDS,
+    ) -> LockInfo:
+        target = Path(path)
+        return self.inspect_lock_path(
+            self.lock_path_for(target),
+            target=target,
+            stale_after_seconds=stale_after_seconds,
+        )
+
+    def inspect_lock_path(
+        self,
+        lock_path: str | Path,
+        *,
+        target: str | Path | None = None,
+        stale_after_seconds: float = DEFAULT_STALE_LOCK_SECONDS,
+    ) -> LockInfo:
+        stale_after_seconds = self._validated_stale_threshold(
+            stale_after_seconds
+        )
+        lock = Path(lock_path)
+        target_path = (
+            Path(target)
+            if target is not None
+            else self.target_from_lock_path(lock)
+        )
+        try:
+            raw_text = lock.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return LockInfo(
+                lock_path=lock,
+                target=target_path,
+                exists=False,
+                pid=None,
+                created_at=None,
+                age_seconds=None,
+                owner_availability="unknown",
+                status="absent",
+                detail="state lock is absent",
+            )
+        except (OSError, UnicodeDecodeError) as error:
+            return LockInfo(
+                lock_path=lock,
+                target=target_path,
+                exists=True,
+                pid=None,
+                created_at=None,
+                age_seconds=None,
+                owner_availability="unknown",
+                status="unknown",
+                detail=f"state lock metadata could not be read: {error}",
+            )
+        return self._lock_info_from_text(
+            lock,
+            target_path,
+            raw_text,
+            stale_after_seconds=stale_after_seconds,
+        )
+
+    def remove_stale_lock(
+        self,
+        path: str | Path,
+        *,
+        stale_after_seconds: float = DEFAULT_STALE_LOCK_SECONDS,
+    ) -> bool:
+        stale_after_seconds = self._validated_stale_threshold(
+            stale_after_seconds
+        )
+        target = Path(path)
+        lock_path = self.lock_path_for(target)
+        try:
+            original = lock_path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return False
+        except (OSError, UnicodeDecodeError):
+            return False
+        info = self._lock_info_from_text(
+            lock_path,
+            target,
+            original,
+            stale_after_seconds=stale_after_seconds,
+        )
+        if info.status != "recoverable":
+            return False
+        try:
+            current = lock_path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return False
+        except (OSError, UnicodeDecodeError):
+            return False
+        if current != original:
+            return False
+        try:
+            lock_path.unlink()
+        except FileNotFoundError:
+            return False
+        except OSError as error:
+            raise StateStoreError(
+                "STATE-LOCK-002",
+                target,
+                "stale state lock could not be removed",
+            ) from error
+        return True
+
     def _load_unlocked(
         self,
         path: Path,
@@ -249,12 +401,13 @@ class StateStore:
     @contextmanager
     def _lock(self, path: Path) -> Iterator[None]:
         path.parent.mkdir(parents=True, exist_ok=True)
-        lock_path = path.with_name(f"{path.name}.lock")
+        lock_path = self.lock_path_for(path)
         deadline = time.monotonic() + self.lock_timeout_seconds
         lock_handle = None
         while lock_handle is None:
             try:
                 lock_handle = lock_path.open("x", encoding="utf-8")
+                self._write_lock_payload(lock_handle, path)
             except FileExistsError as error:
                 if time.monotonic() >= deadline:
                     raise StateStoreError(
@@ -264,6 +417,15 @@ class StateStore:
                     ) from error
                 time.sleep(self.lock_poll_seconds)
             except OSError as error:
+                if lock_handle is not None:
+                    try:
+                        lock_handle.close()
+                    except OSError:
+                        pass
+                    try:
+                        lock_path.unlink(missing_ok=True)
+                    except OSError:
+                        pass
                 raise StateStoreError(
                     "STATE-LOCK-001",
                     path,
@@ -277,3 +439,196 @@ class StateStore:
                 lock_path.unlink(missing_ok=True)
             except OSError:
                 pass
+
+    @staticmethod
+    def lock_path_for(path: str | Path) -> Path:
+        target = Path(path)
+        return target.with_name(f"{target.name}.lock")
+
+    @staticmethod
+    def target_from_lock_path(lock_path: str | Path) -> Path:
+        lock = Path(lock_path)
+        if lock.name.endswith(".lock"):
+            return lock.with_name(lock.name[:-5])
+        return lock
+
+    @staticmethod
+    def _write_lock_file(
+        lock_path: Path,
+        target: Path,
+        *,
+        pid: int | None = None,
+        created_at: str | None = None,
+    ) -> None:
+        payload = StateStore._lock_payload(
+            target,
+            pid=pid,
+            created_at=created_at,
+        )
+        lock_path.parent.mkdir(parents=True, exist_ok=True)
+        lock_path.write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+
+    @staticmethod
+    def _write_lock_payload(stream: object, target: Path) -> None:
+        payload = StateStore._lock_payload(target)
+        stream.write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+        stream.flush()
+
+    @staticmethod
+    def _lock_payload(
+        target: Path,
+        *,
+        pid: int | None = None,
+        created_at: str | None = None,
+    ) -> dict[str, object]:
+        return {
+            "schemaVersion": LOCK_METADATA_SCHEMA_VERSION,
+            "pid": os.getpid() if pid is None else pid,
+            "createdAt": created_at or StateStore._now_iso(),
+            "target": str(target),
+        }
+
+    @staticmethod
+    def _validated_stale_threshold(value: float) -> float:
+        threshold = float(value)
+        if not math.isfinite(threshold) or threshold < 0:
+            raise ValueError("stale_after_seconds must be a non-negative finite number")
+        return threshold
+
+    @staticmethod
+    def _now_iso() -> str:
+        return datetime.now(timezone.utc).isoformat(
+            timespec="seconds"
+        ).replace("+00:00", "Z")
+
+    @staticmethod
+    def _parse_created_at(value: object) -> datetime | None:
+        if not isinstance(value, str) or not value.strip():
+            return None
+        try:
+            parsed = datetime.fromisoformat(
+                value.strip().replace("Z", "+00:00")
+            )
+        except ValueError:
+            return None
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=timezone.utc)
+        return parsed.astimezone(timezone.utc)
+
+    @staticmethod
+    def _pid_exists(pid: int) -> bool | None:
+        if pid <= 0:
+            return False
+        if pid == os.getpid():
+            return True
+        if os.name == "nt":
+            return StateStore._windows_pid_exists(pid)
+        try:
+            os.kill(pid, 0)
+        except ProcessLookupError:
+            return False
+        except PermissionError:
+            return True
+        except OSError as error:
+            if getattr(error, "errno", None) == errno.ESRCH:
+                return False
+            if getattr(error, "errno", None) == errno.EPERM:
+                return True
+            return None
+        return True
+
+    @staticmethod
+    def _windows_pid_exists(pid: int) -> bool | None:
+        try:
+            import ctypes
+        except ImportError:
+            return None
+        process_query_limited_information = 0x1000
+        handle = ctypes.windll.kernel32.OpenProcess(
+            process_query_limited_information,
+            False,
+            pid,
+        )
+        if handle:
+            ctypes.windll.kernel32.CloseHandle(handle)
+            return True
+        error = ctypes.windll.kernel32.GetLastError()
+        if error == 87:  # ERROR_INVALID_PARAMETER: PID does not exist.
+            return False
+        if error == 5:  # ERROR_ACCESS_DENIED: process exists but is protected.
+            return True
+        return None
+
+    def _lock_info_from_text(
+        self,
+        lock_path: Path,
+        target: Path,
+        raw_text: str,
+        *,
+        stale_after_seconds: float,
+    ) -> LockInfo:
+        try:
+            raw = json.loads(raw_text) if raw_text.strip() else {}
+        except json.JSONDecodeError:
+            raw = {}
+        if not isinstance(raw, dict):
+            raw = {}
+        pid = raw.get("pid")
+        pid_value = pid if isinstance(pid, int) and not isinstance(pid, bool) else None
+        created_at = raw.get("createdAt")
+        created_at_value = created_at if isinstance(created_at, str) else None
+        created = self._parse_created_at(created_at_value)
+        age_seconds = None
+        if created is not None:
+            age_seconds = max(
+                0.0,
+                (datetime.now(timezone.utc) - created).total_seconds(),
+            )
+        else:
+            try:
+                age_seconds = max(0.0, time.time() - lock_path.stat().st_mtime)
+            except OSError:
+                age_seconds = None
+        target_value = raw.get("target")
+        if isinstance(target_value, str) and target_value.strip():
+            target = Path(target_value)
+
+        if pid_value is None:
+            availability = "unknown"
+            status = "unknown"
+            detail = "state lock owner pid is unknown"
+        else:
+            exists = self._pid_exists(pid_value)
+            if exists is True:
+                availability = "available"
+                status = "active"
+                detail = "state lock owner process is still available"
+            elif exists is False:
+                availability = "missing"
+                if age_seconds is not None and age_seconds >= stale_after_seconds:
+                    status = "recoverable"
+                    detail = "state lock owner process is missing and lock is stale"
+                else:
+                    status = "stale-but-unsafe"
+                    detail = (
+                        "state lock owner process is missing but lock age "
+                        "does not satisfy the stale threshold"
+                    )
+            else:
+                availability = "unknown"
+                status = "unknown"
+                detail = "state lock owner process availability is unknown"
+        return LockInfo(
+            lock_path=lock_path,
+            target=target,
+            exists=True,
+            pid=pid_value,
+            created_at=created_at_value,
+            age_seconds=age_seconds,
+            owner_availability=availability,
+            status=status,
+            detail=detail,
+        )

package/template/.cowork-flow/scripts/kernel/workflow_route.py

@@ -38,20 +38,20 @@ INTENT_OPERATIONS = {
 
 # These are state-transition facts, not Skill metadata.
 ACTION_TRANSITIONS = {
-    "answer_questions": {"runtimeGate": None, "mutatesState": False},
-    "debug_failure": {"runtimeGate": None, "mutatesState": False},
-    "discuss_options": {"runtimeGate": None, "mutatesState": False},
-    "doubt_review": {"runtimeGate": None, "mutatesState": False},
-    "batch_execute": {"runtimeGate": "task_start", "mutatesState": True},
-    "create_task": {"runtimeGate": None, "mutatesState": True},
-    "edit_planning_artifacts": {"runtimeGate": "task_start", "mutatesState": False},
-    "start_task": {"runtimeGate": "task_start", "mutatesState": True},
-    "implement_change": {"runtimeGate": None, "mutatesState": False},
-    "request_review": {"runtimeGate": "task_review", "mutatesState": True},
-    "complete_task": {"runtimeGate": "task_complete", "mutatesState": True},
-    "archive_task": {"runtimeGate": "task_archive", "mutatesState": True},
-    "execute_delegated_work": {"runtimeGate": None, "mutatesState": False},
-    "repair_workflow_state": {"runtimeGate": None, "mutatesState": False},
+    "answer_questions": {"lifecycleCheck": None, "mutatesState": False},
+    "debug_failure": {"lifecycleCheck": None, "mutatesState": False},
+    "discuss_options": {"lifecycleCheck": None, "mutatesState": False},
+    "doubt_review": {"lifecycleCheck": None, "mutatesState": False},
+    "batch_execute": {"lifecycleCheck": "task_start", "mutatesState": True},
+    "create_task": {"lifecycleCheck": None, "mutatesState": True},
+    "edit_planning_artifacts": {"lifecycleCheck": "task_start", "mutatesState": False},
+    "start_task": {"lifecycleCheck": "task_start", "mutatesState": True},
+    "implement_change": {"lifecycleCheck": None, "mutatesState": False},
+    "request_review": {"lifecycleCheck": "task_review", "mutatesState": True},
+    "complete_task": {"lifecycleCheck": "task_complete", "mutatesState": True},
+    "archive_task": {"lifecycleCheck": "task_archive", "mutatesState": True},
+    "execute_delegated_work": {"lifecycleCheck": None, "mutatesState": False},
+    "repair_workflow_state": {"lifecycleCheck": None, "mutatesState": False},
 }
 RUNNABLE_ACTIONS = {
     action_id
@@ -158,7 +158,7 @@ def _action_contract(
     return {
         "id": action_id,
         "mutatesState": spec["mutatesState"],
-        "runtimeGate": spec["runtimeGate"],
+        "lifecycleCheck": spec["lifecycleCheck"],
         "runnable": action_id in RUNNABLE_ACTIONS and not action_blockers,
         "blockers": action_blockers,
     }

package/template/.cowork-flow/scripts/run.py

@@ -22,15 +22,12 @@ configure_cli_encoding()
 COMMAND_SCRIPTS = {
     "resume": "adapters/cli/resume.py",
     "task": "adapters/cli/task.py",
-    "change": "adapters/cli/change.py",
     "get-context": "adapters/cli/get_context.py",
     "get_context": "adapters/cli/get_context.py",
     "get-developer": "adapters/cli/get_developer.py",
     "get_developer": "adapters/cli/get_developer.py",
     "init-developer": "adapters/cli/init_developer.py",
     "init_developer": "adapters/cli/init_developer.py",
-    "add-session": "adapters/cli/add_session.py",
-    "add_session": "adapters/cli/add_session.py",
     "subagent": "adapters/cli/subagent.py",
 }
 RESERVED_COMMAND_NAMES = (*COMMAND_SCRIPTS, "python", "help", "-h", "--help")
@@ -49,11 +46,9 @@ def print_usage() -> None:
 Common commands:
   resume
   task
-  change
   get-context
   get-developer
   init-developer
-  add-session
   subagent
   doctor
   party-v2

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

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""Task context discovery for specs, Skills, and installed platforms."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from infra.quality_sources import quality_source_entries
+from infra.skill_manifest import context_entries
+from infra.paths import (
+    DIR_AGENTS,
+    DIR_SPEC,
+    DIR_WORKFLOW,
+    get_repo_root,
+)
+
+
+def get_implement_base(repo_root: Path | None = None) -> list[dict]:
+    root = Path(repo_root) if repo_root is not None else get_repo_root()
+    entries = [
+        {
+            "file": "AGENTS.md",
+            "reason": "Project collaboration rules and workflow checks",
+        },
+        {
+            "file": f"{DIR_WORKFLOW}/{DIR_SPEC}/guides/index.md",
+            "reason": "Pre-implementation thinking guides",
+        },
+        {
+            "file": (
+                f"{DIR_WORKFLOW}/{DIR_SPEC}/guides/"
+                "pre-implementation-checklist.md"
+            ),
+            "reason": "Mandatory pre-coding checklist",
+        },
+    ]
+    entries.extend(context_entries(root, context="implement"))
+    return entries
+
+
+def get_implement_backend() -> list[dict]:
+    return [
+        {
+            "file": f"{DIR_WORKFLOW}/{DIR_SPEC}/backend/index.md",
+            "reason": "Backend development guide",
+        }
+    ]
+
+
+def get_implement_frontend() -> list[dict]:
+    return [
+        {
+            "file": f"{DIR_WORKFLOW}/{DIR_SPEC}/frontend/index.md",
+            "reason": "Frontend development guide",
+        }
+    ]
+
+
+def get_implement_spec() -> list[dict]:
+    return [
+        {
+            "file": f"{DIR_WORKFLOW}/{DIR_SPEC}/index.md",
+            "reason": "Spec index — read before modifying spec/",
+        },
+        {
+            "file": f"{DIR_WORKFLOW}/{DIR_SPEC}/contracts/index.md",
+            "reason": "Contract definitions",
+        },
+        {
+            "file": f"{DIR_WORKFLOW}/{DIR_SPEC}/schemas/index.md",
+            "reason": "Schema definitions",
+        },
+    ]
+
+
+def detect_installed_platforms(repo_root: Path | None = None) -> list[str]:
+    repo_root = Path(repo_root) if repo_root is not None else get_repo_root()
+    platforms: list[str] = []
+    if (repo_root / ".codex").is_dir():
+        platforms.append("codex")
+    if (repo_root / ".opencode").is_dir():
+        platforms.append("opencode")
+    if (repo_root / ".claude").is_dir() or (repo_root / "CLAUDE.md").is_file():
+        platforms.append("claude-code")
+    return platforms
+
+
+def use_claude_skill_context(repo_root: Path | None = None) -> bool:
+    return detect_installed_platforms(repo_root) == ["claude-code"]
+
+
+def skill_path(name: str, repo_root: Path | None = None) -> str:
+    if use_claude_skill_context(repo_root):
+        return f".claude/skills/{name}/SKILL.md"
+    return f"{DIR_AGENTS}/skills/{name}/SKILL.md"
+
+
+def get_domain_skill_context(
+    repo_root: Path,
+    *,
+    dev_type: str | None = None,
+    paths: tuple[str, ...] = (),
+) -> list[dict]:
+    return context_entries(
+        repo_root,
+        context="implement",
+        dev_type=dev_type,
+        paths=paths,
+        include_wildcard=False,
+    )
+
+
+def is_skill_path(file_path: str) -> bool:
+    return (
+        file_path.startswith(f"{DIR_AGENTS}/skills/")
+        or file_path.startswith(".claude/skills/")
+        or ".skills/" in file_path
+        or "/skills/" in file_path
+    )
+
+
+def discover_spec_files(repo_root: Path, dev_type: str) -> list[str]:
+    if dev_type == "spec":
+        return [f"{DIR_WORKFLOW}/{DIR_SPEC}/index.md"]
+
+    spec_dir = repo_root / DIR_WORKFLOW / DIR_SPEC / dev_type
+    if not spec_dir.is_dir():
+        return []
+    return sorted(
+        f"{DIR_WORKFLOW}/{DIR_SPEC}/{dev_type}/{path.name}"
+        for path in spec_dir.glob("*.md")
+        if path.is_file()
+    )
+
+
+def get_check_context(repo_root: Path, dev_type: str) -> list[dict]:
+    entries = context_entries(repo_root, context="check", dev_type=dev_type)
+    entries.sort(key=lambda entry: entry["file"])
+    if dev_type == "spec":
+        entries.extend(
+            {
+                "file": spec_file,
+                "reason": f"Verify {Path(spec_file).name} compliance",
+            }
+            for spec_file in discover_spec_files(repo_root, dev_type)
+        )
+    entries.extend(quality_source_entries(repo_root, dev_type))
+    return entries
+
+
+def get_debug_context(
+    dev_type: str,
+    repo_root: Path | None = None,
+) -> list[dict]:
+    root = Path(repo_root) if repo_root is not None else get_repo_root()
+    return context_entries(root, context="debug", dev_type=dev_type)