cowork-flow 0.0.47 → 0.0.49

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 []

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

@@ -3,177 +3,10 @@
 
 from __future__ import annotations
 
-import json
 from pathlib import Path
 
-from infra.paths import DIR_ARCHIVE, DIR_CHANGES, DIR_TASKS, DIR_WORKFLOW, FILE_TASK_JSON, get_tasks_dir
-from services.task_utils import find_task_by_name
-
-from infra.files import read_text_utf8
-
-
-def _read_text(path: Path) -> str:
-    return read_text_utf8(path).strip()
-
-
-def _read_json(path: Path) -> dict:
-    try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return {}
-    return data if isinstance(data, dict) else {}
-
-
-def _parse_scalar(value: str) -> object:
-    if value == "null":
-        return None
-    if value == "true":
-        return True
-    if value == "false":
-        return False
-    return value
-
-
-def _read_metadata(path: Path) -> dict[str, object]:
-    data: dict[str, object] = {}
-    text = _read_text(path)
-    if not text:
-        return data
-
-    for raw_line in text.splitlines():
-        line = raw_line.strip()
-        if not line or line.startswith("#") or ":" not in line:
-            continue
-        key, value = line.split(":", 1)
-        data[key.strip()] = _parse_scalar(value.strip())
-    return data
-
-
-def _display_path(repo_root: Path, path: Path) -> str:
-    try:
-        return path.resolve().relative_to(repo_root.resolve()).as_posix()
-    except ValueError:
-        return str(path)
-
-
-def _resolve_link(repo_root: Path, base_dir: str, value: object) -> Path | None:
-    if not isinstance(value, str) or not value.strip():
-        return None
-
-    raw_path = Path(value)
-    if raw_path.is_absolute():
-        return raw_path
-
-    direct = repo_root / raw_path
-    workflow_base = Path(DIR_WORKFLOW) / base_dir
-    if direct.exists() or raw_path.parts[:2] == workflow_base.parts:
-        return direct
-    return repo_root / workflow_base / raw_path
-
-
-def _same_path(left: Path, right: Path) -> bool:
-    try:
-        return left.resolve() == right.resolve()
-    except OSError:
-        return left == right
-
-
-def _task_ancestry(repo_root: Path, task_dir: Path) -> list[Path]:
-    tasks_dir = get_tasks_dir(repo_root)
-    ancestry = [task_dir]
-    seen = {task_dir.name}
-    current = task_dir
-
-    while True:
-        data = _read_json(current / FILE_TASK_JSON)
-        parent = data.get("parent")
-        if not isinstance(parent, str) or not parent.strip() or parent in seen:
-            break
-        parent_dir = find_task_by_name(parent, tasks_dir)
-        if parent_dir is None:
-            break
-        ancestry.append(parent_dir)
-        seen.add(parent)
-        current = parent_dir
-
-    return ancestry
-
-
-def _change_applies_to_task(
-    repo_root: Path,
-    metadata: dict[str, object],
-    task_dir: Path,
-) -> tuple[bool, bool]:
-    ancestry = _task_ancestry(repo_root, task_dir)
-    linked_task = _resolve_link(repo_root, DIR_TASKS, metadata.get("task"))
-    if linked_task is not None and any(_same_path(linked_task, item) for item in ancestry):
-        return True, False
-
-    if linked_task is None:
-        plan_path = _resolve_link(repo_root, "plans", metadata.get("plan"))
-        if plan_path is not None:
-            return True, True
-
-    return False, False
-
-
-def _append_missing_file_blocker(
-    blockers: list[str],
-    slug: str,
-    path: Path,
-    label: str,
-) -> None:
-    if not _read_text(path):
-        blockers.append(f"L2 readiness ({slug}): {label} is missing or empty")
-
-
-def _iter_change_dirs(repo_root: Path) -> list[Path]:
-    changes_dir = repo_root / DIR_WORKFLOW / DIR_CHANGES
-    if not changes_dir.is_dir():
-        return []
-    return [
-        path
-        for path in sorted(changes_dir.iterdir())
-        if path.is_dir() and path.name != DIR_ARCHIVE
-    ]
-
 
 def task_readiness_blockers(repo_root: Path, task_dir: Path) -> list[str]:
-    """Return readiness blockers for work linked to L2 changes."""
-    blockers: list[str] = []
-
-    for change_dir in _iter_change_dirs(repo_root):
-        metadata = _read_metadata(change_dir / "change.yaml")
-        if metadata.get("level") != "L2" or metadata.get("status") == "archived":
-            continue
-
-        applies, missing_task_link = _change_applies_to_task(repo_root, metadata, task_dir)
-        if not applies:
-            continue
-
-        slug = change_dir.name
-        if missing_task_link:
-            blockers.append(f"L2 readiness ({slug}): change.yaml task link is missing")
-
-        _append_missing_file_blocker(blockers, slug, change_dir / "proposal.md", "proposal.md")
-        _append_missing_file_blocker(blockers, slug, change_dir / "spec.md", "spec.md")
-        _append_missing_file_blocker(blockers, slug, change_dir / "design.md", "design.md")
-
-        plan_path = _resolve_link(repo_root, "plans", metadata.get("plan"))
-        if plan_path is None:
-            blockers.append(f"L2 readiness ({slug}): change.yaml plan link is missing")
-        elif not plan_path.exists():
-            blockers.append(
-                f"L2 readiness ({slug}): plan points to missing path: {_display_path(repo_root, plan_path)}"
-            )
-        else:
-            if not _read_text(plan_path):
-                blockers.append(f"L2 readiness ({slug}): linked plan is empty")
-
-        linked_task = _resolve_link(repo_root, DIR_TASKS, metadata.get("task"))
-        if linked_task is not None and not linked_task.exists():
-            blockers.append(
-                f"L2 readiness ({slug}): task points to missing path: {_display_path(repo_root, linked_task)}"
-            )
-
-    return blockers
+    """Return additional readiness blockers not covered by task context gates."""
+    del repo_root, task_dir
+    return []

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

@@ -12,6 +12,7 @@ from pathlib import Path
 from infra.paths import DIR_ARCHIVE, get_tasks_dir
 from runtime.session_state import clear_task_from_sessions
 from infra.archive_utils import archive_directory_resumable
+from services.context_jsonl import read_context_jsonl_entries
 from services.task_repository import TaskRepository, TaskRepositoryError
 from services.task_utils import find_task_by_name
 
@@ -20,13 +21,37 @@ from kernel.task_state import DONE_STATUSES  # noqa: F401
 ArchiveFinalizer = Callable[[], bool]
 
 
+@dataclass(frozen=True)
+class RollbackIssue:
+    """Best-effort compensation issue that did not replace the primary error."""
+
+    stage: str
+    path: Path
+    detail: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "stage": self.stage,
+            "path": str(self.path),
+            "detail": self.detail,
+        }
+
+
 class TaskArchiveError(RuntimeError):
     """Raised when an archive_task action cannot complete safely."""
 
-    def __init__(self, code: str, path: Path, detail: str) -> None:
+    def __init__(
+        self,
+        code: str,
+        path: Path,
+        detail: str,
+        *,
+        rollback_issues: tuple[RollbackIssue, ...] = (),
+    ) -> None:
         self.code = code
         self.path = path
         self.detail = detail
+        self.rollback_issues = tuple(rollback_issues)
         super().__init__(f"{code}: {detail}: {path}")
 
 
@@ -156,10 +181,10 @@ class TaskArchiveService:
                 raise TaskArchiveError(
                     "TASK-ARCHIVE-FINALIZE-001",
                     destination,
-                    "linked change archive failed",
+                    "archive finalizer failed",
                 )
         except Exception as error:
-            self._rollback(
+            rollback_issues = self._rollback(
                 task_dir,
                 destination,
                 task_data,
@@ -167,17 +192,22 @@ class TaskArchiveService:
                 context_snapshots,
             )
             if isinstance(error, TaskArchiveError):
+                error.rollback_issues = tuple(
+                    (*error.rollback_issues, *rollback_issues)
+                )
                 raise
             if isinstance(error, TaskRepositoryError):
                 raise TaskArchiveError(
                     "TASK-ARCHIVE-WRITE-001",
                     error.path,
                     error.detail,
+                    rollback_issues=rollback_issues,
                 ) from error
             raise TaskArchiveError(
                 "TASK-ARCHIVE-FINALIZE-001",
                 destination,
                 f"archive finalizer failed: {error}",
+                rollback_issues=rollback_issues,
             ) from error
 
     def _relationship_updates(
@@ -258,18 +288,20 @@ class TaskArchiveService:
         source_path: str,
         destination_path: str,
     ) -> None:
-        original = context_file.read_text(encoding="utf-8")
+        with context_file.open("r", encoding="utf-8", newline="") as stream:
+            original = stream.read()
+        entries_by_line = {
+            entry.line: entry
+            for entry in read_context_jsonl_entries(context_file).entries
+        }
         rendered: list[str] = []
         changed = False
-        for line in original.splitlines(keepends=True):
-            content = line.rstrip("\r\n")
-            ending = line[len(content):]
-            try:
-                entry = json.loads(content)
-            except json.JSONDecodeError:
+        for line_number, line in enumerate(original.splitlines(keepends=True), start=1):
+            parsed = entries_by_line.get(line_number)
+            if parsed is None or not isinstance(parsed.data, dict):
                 rendered.append(line)
                 continue
-            file_path = entry.get("file") if isinstance(entry, dict) else None
+            file_path = parsed.data.get("file")
             normalized = TaskArchiveService._archived_context_path(
                 file_path,
                 source_path,
@@ -278,13 +310,15 @@ class TaskArchiveService:
             if normalized == file_path:
                 rendered.append(line)
                 continue
+            entry = dict(parsed.data)
             entry["file"] = normalized
             rendered.append(
-                json.dumps(entry, ensure_ascii=False) + ending
+                json.dumps(entry, ensure_ascii=False) + parsed.line_ending
             )
             changed = True
         if changed:
-            context_file.write_text("".join(rendered), encoding="utf-8")
+            with context_file.open("w", encoding="utf-8", newline="") as stream:
+                stream.write("".join(rendered))
 
     @staticmethod
     def _archived_context_path(
@@ -308,15 +342,23 @@ class TaskArchiveService:
                 self.repository.save(task_dir, changes)
                 applied.append((task_dir, original))
         except TaskRepositoryError as error:
+            rollback_issues: list[RollbackIssue] = []
             for task_dir, original in reversed(applied):
                 try:
                     self.repository.replace(task_dir, original)
-                except TaskRepositoryError:
-                    pass
+                except Exception as rollback_error:
+                    rollback_issues.append(
+                        RollbackIssue(
+                            "relationship_restore",
+                            Path(str(getattr(rollback_error, "path", task_dir / "task.json"))),
+                            str(getattr(rollback_error, "detail", rollback_error)),
+                        )
+                    )
             raise TaskArchiveError(
                 "TASK-ARCHIVE-RELATIONSHIP-001",
                 error.path,
                 error.detail,
+                rollback_issues=tuple(rollback_issues),
             ) from error
 
     def _rollback(
@@ -326,22 +368,71 @@ class TaskArchiveService:
         task_data: dict,
         relationship_updates: list[tuple[Path, dict, dict]],
         context_snapshots: dict[str, bytes],
-    ) -> None:
+    ) -> tuple[RollbackIssue, ...]:
+        issues: list[RollbackIssue] = []
         for task_dir, original, _ in relationship_updates:
             try:
                 self.repository.replace(task_dir, original)
-            except TaskRepositoryError:
-                pass
+            except Exception as error:
+                issues.append(
+                    RollbackIssue(
+                        "relationship_restore",
+                        Path(str(getattr(error, "path", task_dir / "task.json"))),
+                        str(getattr(error, "detail", error)),
+                    )
+                )
 
+        directory_restore_attempted = False
         if destination.is_dir() and not source.exists():
-            archive_directory_resumable(destination, source)
+            directory_restore_attempted = True
+            try:
+                move_result = archive_directory_resumable(destination, source)
+            except Exception as error:  # best-effort compensation boundary
+                issues.append(
+                    RollbackIssue(
+                        "directory_restore",
+                        source,
+                        f"failed to restore archived directory: {error}",
+                    )
+                )
+            else:
+                if not move_result.ok:
+                    issues.append(
+                        RollbackIssue(
+                            "directory_restore",
+                            move_result.destination,
+                            move_result.message,
+                        )
+                    )
         if source.is_dir():
             for name, content in context_snapshots.items():
+                context_path = source / name
                 try:
-                    (source / name).write_bytes(content)
-                except OSError:
-                    pass
+                    context_path.write_bytes(content)
+                except Exception as error:
+                    issues.append(
+                        RollbackIssue(
+                            "context_restore",
+                            context_path,
+                            str(error),
+                        )
+                    )
             try:
                 self.repository.replace(source, task_data)
-            except TaskRepositoryError:
-                pass
+            except Exception as error:
+                issues.append(
+                    RollbackIssue(
+                        "task_json_restore",
+                        Path(str(getattr(error, "path", source / "task.json"))),
+                        str(getattr(error, "detail", error)),
+                    )
+                )
+        elif not source.exists() and not directory_restore_attempted:
+            issues.append(
+                RollbackIssue(
+                    "directory_restore",
+                    source,
+                    "source task directory was not restored",
+                )
+            )
+        return tuple(issues)