cowork-flow 0.0.48 → 0.0.49

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

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""Task context repository-relative path policy."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+CONTEXT_ENTRY_TYPES = frozenset(("file", "directory", "planned-file", "deleted-file"))
+
+
+class TaskContextError(RuntimeError):
+    """Raised when a context mutation cannot be performed."""
+
+    def __init__(self, code: str, path: Path, detail: str) -> None:
+        self.code = code
+        self.path = path
+        self.detail = detail
+        super().__init__(f"{code}: {detail}: {path}")
+
+
+def normalize_context_path(
+    repo_root: Path,
+    path: str,
+    entry_type: str,
+) -> tuple[str, Path]:
+    """Return a canonical repo-relative context path and its absolute target."""
+    candidate = Path(repo_root) / str(path)
+    _validate_context_entry_type(candidate, entry_type)
+    normalized = _normalized_context_path(path, entry_type)
+    segments = normalized.split("/")
+    _validate_context_path(candidate, normalized, segments, path, entry_type)
+    repo_root, full_path = _resolved_context_target(repo_root, segments)
+    return _typed_context_path(normalized, full_path, repo_root, entry_type)
+
+
+def _validate_context_entry_type(candidate: Path, entry_type: str) -> None:
+    if entry_type not in CONTEXT_ENTRY_TYPES:
+        raise TaskContextError(
+            "TASK-CONTEXT-TYPE-001",
+            candidate,
+            f"unsupported context entry type: {entry_type}",
+        )
+
+
+def _normalized_context_path(path: str, entry_type: str) -> str:
+    normalized = str(path).replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+    if entry_type == "directory" and normalized.endswith("/"):
+        normalized = normalized[:-1]
+    return normalized
+
+
+def _validate_context_path(
+    candidate: Path,
+    normalized: str,
+    segments: list[str],
+    path: str,
+    entry_type: str,
+) -> None:
+    if not _is_valid_context_path(normalized, segments, path, entry_type):
+        raise TaskContextError(
+            "TASK-CONTEXT-PATH-002",
+            candidate,
+            "context path must be a canonical repository-relative path",
+        )
+
+
+def _is_valid_context_path(
+    normalized: str,
+    segments: list[str],
+    path: str,
+    entry_type: str,
+) -> bool:
+    return not (
+        not normalized
+        or normalized.startswith("/")
+        or re.match(r"^[A-Za-z]:", normalized) is not None
+        or any(segment in ("", ".", "..") for segment in segments)
+        or any(character in normalized for character in "*?[]")
+        or (entry_type in {"planned-file", "deleted-file"} and str(path).endswith(("/", "\\")))
+    )
+
+
+def _resolved_context_target(
+    repo_root: Path,
+    segments: list[str],
+) -> tuple[Path, Path]:
+    resolved_root = Path(repo_root).resolve()
+    return resolved_root, resolved_root.joinpath(*segments).resolve(strict=False)
+
+
+def _typed_context_path(
+    normalized: str,
+    full_path: Path,
+    repo_root: Path,
+    entry_type: str,
+) -> tuple[str, Path]:
+    try:
+        full_path.relative_to(repo_root)
+    except ValueError as error:
+        raise TaskContextError(
+            "TASK-CONTEXT-PATH-002",
+            full_path,
+            "context path resolves outside the repository",
+        ) from error
+
+    if entry_type == "directory":
+        normalized = f"{normalized}/"
+    return normalized, full_path
+
+
+def prepare_context_entry(
+    repo_root: Path,
+    path: str,
+    reason: str,
+    requested_type: str | None,
+) -> tuple[str, str, dict]:
+    """Build one validated context entry without writing it."""
+    entry_type = requested_type
+    if entry_type is None:
+        candidate = Path(repo_root) / path
+        entry_type = "directory" if candidate.is_dir() else "file"
+
+    normalized_path, full_path = normalize_context_path(
+        repo_root,
+        path,
+        entry_type,
+    )
+    valid_target = {
+        "directory": full_path.is_dir(),
+        "planned-file": not full_path.is_dir(),
+        "deleted-file": not full_path.is_dir(),
+        "file": full_path.is_file(),
+    }[entry_type]
+    if not valid_target:
+        raise TaskContextError(
+            "TASK-CONTEXT-PATH-001",
+            full_path,
+            f"context {entry_type} path does not exist or has the wrong type",
+        )
+
+    entry = {"file": normalized_path, "reason": reason}
+    if entry_type != "file":
+        entry["type"] = entry_type
+    return entry_type, normalized_path, entry
+
+
+def normalize_context_file_scope_entry(
+    repo_root: Path,
+    entry: dict,
+) -> tuple[str | None, str | None]:
+    """Return the file-scope path allowed by one context entry.
+
+    Directory entries are valid context, but they do not authorize arbitrary
+    changed files for lifecycle review.
+    """
+    entry_type = entry.get("type", "file")
+    file_path = entry.get("file")
+    if not isinstance(file_path, str) or not file_path:
+        return None, "missing file path"
+    if entry_type == "directory":
+        return _normalize_context_file_scope_path(repo_root, file_path, entry_type)
+    if entry_type not in ("file", "planned-file", "deleted-file"):
+        return None, f"unsupported type {entry_type!r}"
+    return _normalize_context_file_scope_path(repo_root, file_path, entry_type)
+
+
+def _normalize_context_file_scope_path(
+    repo_root: Path,
+    file_path: str,
+    entry_type: str,
+) -> tuple[str | None, str | None]:
+    try:
+        normalized, _full_path = normalize_context_path(
+            repo_root,
+            file_path,
+            entry_type,
+        )
+    except TaskContextError:
+        return None, f"non-canonical path {file_path!r}"
+    if entry_type == "directory":
+        return None, None
+    return normalized, None

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

@@ -13,6 +13,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from infra.git_snapshot import collect_changed_paths
+from services.lifecycle_policy import LifecycleExecutionPolicy
 from services.task_context import (
     normalize_context_file_scope_entry,
     read_context_jsonl_entries,
@@ -71,7 +72,8 @@ class LifecycleCheckRunner:
         self,
         task_dir: Path,
         *,
-        allow_spec_file_modifications: bool = False,
+        allow_spec_file_modifications: bool | None = None,
+        execution_policy: LifecycleExecutionPolicy | None = None,
     ) -> LifecycleCheckResult:
         return LifecycleCheckResult(
             stage="review",
@@ -79,7 +81,10 @@ class LifecycleCheckRunner:
                 _review_completion_issues(
                     self.repo_root,
                     task_dir,
-                    allow_spec_file_modifications=allow_spec_file_modifications,
+                    allow_spec_file_modifications=_policy_allows_spec_changes(
+                        execution_policy,
+                        allow_spec_file_modifications,
+                    ),
                 ),
             ),
         )
@@ -88,7 +93,8 @@ class LifecycleCheckRunner:
         self,
         task_dir: Path,
         *,
-        allow_spec_file_modifications: bool = False,
+        allow_spec_file_modifications: bool | None = None,
+        execution_policy: LifecycleExecutionPolicy | None = None,
     ) -> LifecycleCheckResult:
         return LifecycleCheckResult(
             stage="complete",
@@ -96,12 +102,25 @@ class LifecycleCheckRunner:
                 _review_completion_issues(
                     self.repo_root,
                     task_dir,
-                    allow_spec_file_modifications=allow_spec_file_modifications,
+                    allow_spec_file_modifications=_policy_allows_spec_changes(
+                        execution_policy,
+                        allow_spec_file_modifications,
+                    ),
                 ),
             ),
         )
 
 
+def _policy_allows_spec_changes(
+    execution_policy: LifecycleExecutionPolicy | None,
+    allow_spec_file_modifications: bool | None,
+) -> bool:
+    if execution_policy is not None:
+        return execution_policy.allow_spec_file_modifications
+    return bool(allow_spec_file_modifications)
+
+
+
 def _review_completion_issues(
     repo_root: Path,
     task_dir: Path,

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

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Pure lifecycle policy facts shared by services and delivery adapters."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from runtime.execution_context import ExecutionContext
+from runtime.session_state import is_main_session
+from services.task_context import TaskContextService
+
+
+PLANNED_FILE_HINT = (
+    "If this is a planned new file, add "
+    '"type": "planned-file"; if this is an already-deleted file in scope, add '
+    '"type": "deleted-file" before retrying.'
+)
+
+
+@dataclass(frozen=True)
+class LifecyclePolicyFailure:
+    """Structured lifecycle policy blocker without terminal rendering."""
+
+    code: str
+    title: str
+    blockers: tuple[str, ...]
+    hint: str = ""
+
+
+@dataclass(frozen=True)
+class LifecycleExecutionPolicy:
+    """Execution scope facts used by lifecycle checks."""
+
+    execution_scope: str
+    allow_spec_file_modifications: bool
+
+
+def start_readiness_failure(
+    repo_root: Path,
+    task_dir: Path,
+) -> LifecyclePolicyFailure | None:
+    """Return the first start readiness failure, or None when start is ready."""
+    repo_root = Path(repo_root)
+    task_dir = Path(task_dir)
+    context_service = TaskContextService(repo_root)
+
+    blockers = tuple(context_service.start_blockers(task_dir))
+    if blockers:
+        return LifecyclePolicyFailure(
+            code="TASK-START-001",
+            title="Task is not ready to start yet",
+            blockers=blockers,
+            hint=(
+                "write decision-anchor.md and required context JSONL files, "
+                "then retry `task next <dir> --run`"
+            ),
+        )
+
+    validation_issues = tuple(context_service.validation_issue_summaries(task_dir))
+    if validation_issues:
+        context_service.ensure_task_artifact_placeholders(task_dir)
+        validation_issues = tuple(context_service.validation_issue_summaries(task_dir))
+    if validation_issues:
+        return LifecyclePolicyFailure(
+            code="TASK-CONTEXT-001",
+            title="Task context validation failed",
+            blockers=validation_issues,
+            hint=(
+                "run task next <dir> --validate and fix the "
+                f"reported issues. {PLANNED_FILE_HINT}"
+            ),
+        )
+
+    readiness_blockers = _task_readiness_blockers(repo_root, task_dir)
+    if readiness_blockers:
+        return LifecyclePolicyFailure(
+            code="TASK-READINESS-001",
+            title="Task readiness failed",
+            blockers=readiness_blockers,
+            hint=(
+                "run task next <dir> and complete the "
+                "reported readiness artifacts"
+            ),
+        )
+    return None
+
+
+def resolve_execution_policy(
+    repo_root: Path,
+    execution_context: ExecutionContext | None = None,
+    *,
+    allow_spec_file_modifications: bool | None = None,
+) -> LifecycleExecutionPolicy:
+    """Resolve lifecycle scope capability from execution facts."""
+    if execution_context is None:
+        if allow_spec_file_modifications is not None:
+            return LifecycleExecutionPolicy(
+                execution_scope="explicit",
+                allow_spec_file_modifications=allow_spec_file_modifications,
+            )
+        execution_context = ExecutionContext()
+
+    if allow_spec_file_modifications is not None:
+        allowed = allow_spec_file_modifications
+    elif execution_context.is_worker or execution_context.is_subagent:
+        allowed = False
+    else:
+        allowed = is_main_session(Path(repo_root))
+    return LifecycleExecutionPolicy(
+        execution_scope=execution_context.mode,
+        allow_spec_file_modifications=allowed,
+    )
+
+
+def _task_readiness_blockers(repo_root: Path, task_dir: Path) -> tuple[str, ...]:
+    try:
+        from services.readiness import task_readiness_blockers
+    except Exception:
+        return ()
+    try:
+        blockers = task_readiness_blockers(repo_root, task_dir)
+    except Exception:
+        return (
+            "readiness check failed; run task next <dir> --validate and inspect "
+            "task readiness artifacts",
+        )
+    return tuple(str(blocker) for blocker in blockers if str(blocker).strip())

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

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Shared planFile binding policy for task lifecycle readiness and creation."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from infra.files import read_text_utf8
+from infra.paths import DIR_WORKFLOW
+
+
+PLAN_DIRECTORY = f"{DIR_WORKFLOW}/plans/"
+
+
+@dataclass(frozen=True)
+class BoundPlanFile:
+    normalized: str
+    path: Path
+
+
+class PlanBindingError(RuntimeError):
+    """Raised when a planFile path violates the shared binding policy."""
+
+    def __init__(
+        self,
+        code: str,
+        path: Path,
+        detail: str,
+        normalized: str | None = None,
+    ) -> None:
+        self.code = code
+        self.path = path
+        self.detail = detail
+        self.normalized = normalized
+        super().__init__(f"{code}: {detail}: {path}")
+
+
+def normalize_plan_file(plan_file: str | Path) -> str | None:
+    """Return a canonical repo-relative .cowork-flow/plans path."""
+    normalized = normalize_repo_relative_path(plan_file)
+    if normalized is None or not normalized.startswith(PLAN_DIRECTORY):
+        return None
+    return normalized
+
+
+def normalize_repo_relative_path(path: str | Path) -> str | None:
+    normalized = str(path).replace("\\", "/").strip()
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+    segments = normalized.split("/")
+    if (
+        not normalized
+        or normalized.startswith("/")
+        or re.match(r"^[A-Za-z]:", normalized) is not None
+        or any(segment in ("", ".", "..") for segment in segments)
+    ):
+        return None
+    return normalized
+
+
+def bind_plan_file(
+    repo_root: Path,
+    plan_file: str | Path,
+    *,
+    allow_absolute: bool = False,
+    require_exists: bool = True,
+    require_non_empty: bool = False,
+) -> BoundPlanFile:
+    """Resolve one planFile through the shared canonical path policy."""
+    repo_root = Path(repo_root)
+    raw_path = Path(plan_file)
+    if raw_path.is_absolute():
+        if not allow_absolute:
+            raise PlanBindingError(
+                "invalid_path",
+                raw_path,
+                "plan file must be a repository-relative path",
+            )
+        try:
+            normalized = raw_path.resolve().relative_to(repo_root.resolve()).as_posix()
+        except ValueError as error:
+            raise PlanBindingError(
+                "outside_repository",
+                raw_path,
+                "plan file must be inside the repository",
+            ) from error
+    else:
+        normalized = normalize_repo_relative_path(plan_file)
+        if normalized is None:
+            raise PlanBindingError(
+                "invalid_path",
+                repo_root / raw_path,
+                "plan file must be a canonical repository-relative path",
+            )
+
+    if not normalized.startswith(PLAN_DIRECTORY):
+        raise PlanBindingError(
+            "wrong_location",
+            repo_root / normalized,
+            f"plan file must live under {DIR_WORKFLOW}/plans",
+            normalized,
+        )
+
+    plan_path = repo_root / normalized
+    if require_exists and not plan_path.is_file():
+        raise PlanBindingError(
+            "missing",
+            plan_path,
+            "plan file does not exist",
+            normalized,
+        )
+    if require_non_empty and not read_text_utf8(plan_path).strip():
+        raise PlanBindingError(
+            "empty",
+            plan_path,
+            "plan file is empty",
+            normalized,
+        )
+    return BoundPlanFile(normalized=normalized, path=plan_path)
+
+
+def plan_file_blockers(repo_root: Path, task_data: dict) -> list[str]:
+    """Return lifecycle readiness blockers for task.json meta.planFile."""
+    meta = task_data.get("meta")
+    plan_file = meta.get("planFile") if isinstance(meta, dict) else None
+    if not isinstance(plan_file, str) or not plan_file.strip():
+        return ["planFile is required before implementation starts"]
+    try:
+        bind_plan_file(
+            repo_root,
+            plan_file,
+            allow_absolute=False,
+            require_exists=True,
+            require_non_empty=True,
+        )
+    except PlanBindingError as error:
+        if error.code in {"invalid_path", "outside_repository", "wrong_location"}:
+            return ["planFile must be a repo-relative .cowork-flow/plans path"]
+        if error.code == "missing":
+            return [f"planFile does not exist: {error.normalized}"]
+        if error.code == "empty":
+            return [f"planFile is empty: {error.normalized}"]
+        return [error.detail]
+    return []