cowork-flow 0.0.47 → 0.0.49

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

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Task context JSONL codec."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator
+
+
+@dataclass(frozen=True)
+class ContextValidationIssue:
+    context_file: str
+    line: int
+    code: str
+    message: str
+
+
+@dataclass(frozen=True)
+class ContextJsonlEntry:
+    context_file: str
+    line: int
+    data: object
+    text: str
+    line_ending: str
+
+
+@dataclass(frozen=True)
+class ContextJsonlReadResult:
+    context_file: str
+    exists: bool
+    entry_count: int
+    entries: tuple[ContextJsonlEntry, ...]
+    issues: tuple[ContextValidationIssue, ...]
+
+
+def write_jsonl(path: Path, entries: list[dict]) -> None:
+    lines = [json.dumps(entry, ensure_ascii=False) for entry in entries]
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def iter_jsonl_lines(path: Path) -> Iterator[tuple[int, str]]:
+    with path.open("r", encoding="utf-8") as stream:
+        for line_number, line in enumerate(stream, start=1):
+            yield line_number, line.rstrip("\n")
+
+
+def read_context_jsonl_entries(context_file: Path) -> ContextJsonlReadResult:
+    """Parse a context JSONL file into reusable line-level facts."""
+    context_file = Path(context_file)
+    if not context_file.is_file():
+        return ContextJsonlReadResult(
+            context_file=context_file.name,
+            exists=False,
+            entry_count=0,
+            entries=(),
+            issues=(),
+        )
+
+    entries: list[ContextJsonlEntry] = []
+    issues: list[ContextValidationIssue] = []
+    entry_count = 0
+    try:
+        lines: list[tuple[int, str, str]] = []
+        with context_file.open("r", encoding="utf-8", newline="") as stream:
+            for line_number, raw_line in enumerate(stream, start=1):
+                text = raw_line.rstrip("\r\n")
+                line_ending = raw_line[len(text):]
+                lines.append((line_number, text, line_ending))
+    except (OSError, UnicodeDecodeError) as error:
+        return ContextJsonlReadResult(
+            context_file=context_file.name,
+            exists=True,
+            entry_count=0,
+            entries=(),
+            issues=(
+                ContextValidationIssue(
+                    context_file=context_file.name,
+                    line=0,
+                    code="read_error",
+                    message=f"Cannot read {context_file.name}: {error}",
+                ),
+            ),
+        )
+
+    for line_number, line, line_ending in lines:
+        if not line.strip():
+            continue
+        entry_count += 1
+        try:
+            data = json.loads(line)
+        except json.JSONDecodeError:
+            issues.append(
+                ContextValidationIssue(
+                    context_file=context_file.name,
+                    line=line_number,
+                    code="invalid_json",
+                    message="Invalid JSON",
+                )
+            )
+            continue
+        entries.append(
+            ContextJsonlEntry(
+                context_file=context_file.name,
+                line=line_number,
+                data=data,
+                text=line,
+                line_ending=line_ending,
+            )
+        )
+
+    return ContextJsonlReadResult(
+        context_file=context_file.name,
+        exists=True,
+        entry_count=entry_count,
+        entries=tuple(entries),
+        issues=tuple(issues),
+    )

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

@@ -8,12 +8,16 @@ task metadata and the current git snapshot.
 
 from __future__ import annotations
 
-import json
 import re
 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,
+)
 
 
 PROTECTED_WORKFLOW_PATTERNS = (
@@ -24,12 +28,30 @@ PROTECTED_WORKFLOW_PATTERNS = (
 )
 
 
+@dataclass(frozen=True)
+class LifecycleCheckIssue:
+    """Machine-readable lifecycle check issue with stable message compatibility."""
+
+    code: str
+    message: str
+    path: str | None = None
+
+
 @dataclass(frozen=True)
 class LifecycleCheckResult:
     """Result of direct lifecycle fact checks."""
 
     stage: str
     blockers: tuple[str, ...] = ()
+    issues: tuple[LifecycleCheckIssue, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.issues and not self.blockers:
+            object.__setattr__(
+                self,
+                "blockers",
+                tuple(issue.message for issue in self.issues),
+            )
 
     @property
     def blocked(self) -> bool:
@@ -50,16 +72,20 @@ 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",
-            blockers=tuple(
-                _review_completion_blockers(
+            issues=tuple(
+                _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,
+                    ),
+                ),
             ),
         )
 
@@ -67,63 +93,127 @@ 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",
-            blockers=tuple(
-                _review_completion_blockers(
+            issues=tuple(
+                _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 _review_completion_blockers(
+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,
     *,
     allow_spec_file_modifications: bool,
-) -> list[str]:
+) -> list[LifecycleCheckIssue]:
     changed_files = collect_changed_paths(repo_root)
-    blockers: list[str] = []
+    issues: list[LifecycleCheckIssue] = []
     if not allow_spec_file_modifications:
-        blockers.extend(_protected_workflow_file_blockers(changed_files))
-    blockers.extend(_allowed_file_scope_blockers(task_dir, changed_files))
-    return blockers
+        issues.extend(_protected_workflow_file_issues(changed_files))
+    issues.extend(
+        _allowed_file_scope_issues(
+            task_dir,
+            changed_files,
+            repo_root=repo_root,
+        )
+    )
+    return issues
 
 
-def _protected_workflow_file_blockers(changed_files: list[str]) -> list[str]:
-    blockers: list[str] = []
+def _review_completion_blockers(
+    repo_root: Path,
+    task_dir: Path,
+    *,
+    allow_spec_file_modifications: bool,
+) -> list[str]:
+    return [
+        issue.message
+        for issue in _review_completion_issues(
+            repo_root,
+            task_dir,
+            allow_spec_file_modifications=allow_spec_file_modifications,
+        )
+    ]
+
+
+def _protected_workflow_file_issues(changed_files: list[str]) -> list[LifecycleCheckIssue]:
+    issues: list[LifecycleCheckIssue] = []
     for file_path in changed_files:
         normalized = _normalize_git_path(file_path)
         if any(re.search(pattern, normalized) for pattern in PROTECTED_WORKFLOW_PATTERNS):
-            blockers.append(
-                "Protected workflow/spec file changed outside main session: "
-                f"{normalized}"
+            issues.append(
+                LifecycleCheckIssue(
+                    code="protected_workflow_file",
+                    path=normalized,
+                    message=(
+                        "Protected workflow/spec file changed outside main session: "
+                        f"{normalized}"
+                    ),
+                )
             )
-    return blockers
+    return issues
 
 
-def _allowed_file_scope_blockers(task_dir: Path, changed_files: list[str]) -> list[str]:
+def _protected_workflow_file_blockers(changed_files: list[str]) -> list[str]:
+    return [issue.message for issue in _protected_workflow_file_issues(changed_files)]
+
+
+def _allowed_file_scope_issues(
+    task_dir: Path,
+    changed_files: list[str],
+    *,
+    repo_root: Path | None = None,
+) -> list[LifecycleCheckIssue]:
     implement_jsonl = task_dir / "implement.jsonl"
     if not implement_jsonl.exists():
         return []
 
-    allowed_files, scope_blockers = _load_allowed_context_files(implement_jsonl)
-    if scope_blockers:
-        return scope_blockers
+    allowed_files, scope_issues = _load_allowed_context_files(
+        implement_jsonl,
+        repo_root=repo_root,
+    )
+    if scope_issues:
+        return scope_issues
 
-    blockers: list[str] = []
+    issues: list[LifecycleCheckIssue] = []
     for file_path in changed_files:
         normalized = _normalize_git_path(file_path)
         if _is_runtime_metadata_path(normalized):
             continue
         if normalized not in allowed_files:
-            blockers.append(f"Modified file not listed in implement.jsonl: {normalized}")
-    return blockers
+            issues.append(
+                LifecycleCheckIssue(
+                    code="unlisted_changed_file",
+                    path=normalized,
+                    message=f"Modified file not listed in implement.jsonl: {normalized}",
+                )
+            )
+    return issues
+
+
+def _allowed_file_scope_blockers(task_dir: Path, changed_files: list[str]) -> list[str]:
+    return [issue.message for issue in _allowed_file_scope_issues(task_dir, changed_files)]
 
 
 def _is_runtime_metadata_path(file_path: str) -> bool:
@@ -136,55 +226,82 @@ def _is_runtime_metadata_path(file_path: str) -> bool:
     )
 
 
-def _load_allowed_context_files(implement_jsonl: Path) -> tuple[set[str], list[str]]:
+def _context_issue(code: str, message: str) -> LifecycleCheckIssue:
+    return LifecycleCheckIssue(code=code, message=message)
+
+
+def _load_allowed_context_files(
+    implement_jsonl: Path,
+    *,
+    repo_root: Path | None = None,
+) -> tuple[set[str], list[LifecycleCheckIssue]]:
     allowed_files: set[str] = set()
-    blockers: list[str] = []
-    try:
-        lines = implement_jsonl.read_text(encoding="utf-8").splitlines()
-    except (OSError, UnicodeDecodeError) as error:
-        return allowed_files, [f"Cannot read implement.jsonl: {error}"]
-
-    for line_number, line in enumerate(lines, start=1):
-        line = line.strip()
-        if not line:
+    issues: list[LifecycleCheckIssue] = []
+    repo_root = Path(repo_root) if repo_root is not None else _repo_root_from_task_dir(
+        implement_jsonl.parent
+    )
+    parsed = read_context_jsonl_entries(implement_jsonl)
+    for issue in parsed.issues:
+        if issue.code == "read_error":
+            issues.append(
+                _context_issue(
+                    "implement_jsonl_read_error",
+                    issue.message,
+                )
+            )
             continue
-        try:
-            entry = json.loads(line)
-        except json.JSONDecodeError:
-            blockers.append(f"Invalid implement.jsonl JSON at line {line_number}")
+        if issue.code == "invalid_json":
+            issues.append(
+                _context_issue(
+                    "invalid_implement_jsonl_json",
+                    f"Invalid implement.jsonl JSON at line {issue.line}",
+                )
+            )
             continue
+        issues.append(_context_issue(issue.code, issue.message))
+
+    for context_entry in parsed.entries:
+        entry = context_entry.data
         if not isinstance(entry, dict):
-            blockers.append(f"Invalid implement.jsonl entry at line {line_number}: expected object")
+            issues.append(
+                _context_issue(
+                    "invalid_implement_jsonl_entry",
+                    (
+                        "Invalid implement.jsonl entry at line "
+                        f"{context_entry.line}: expected object"
+                    ),
+                )
+            )
             continue
-        normalized, error = _normalize_allowed_context_file(entry)
+        normalized, error = normalize_context_file_scope_entry(repo_root, entry)
         if error is not None:
-            blockers.append(f"Invalid implement.jsonl file scope at line {line_number}: {error}")
+            issues.append(
+                _context_issue(
+                    "invalid_implement_jsonl_file_scope",
+                    (
+                        "Invalid implement.jsonl file scope at line "
+                        f"{context_entry.line}: {error}"
+                    ),
+                )
+            )
             continue
         if normalized is not None:
             allowed_files.add(normalized)
     if not allowed_files:
-        blockers.append("implement.jsonl contains no valid file-scope entries")
-    return allowed_files, blockers
-
-
-def _normalize_allowed_context_file(entry: dict) -> tuple[str | None, str | None]:
-    entry_type = entry.get("type", "file")
-    file_path = entry.get("file")
-    if entry_type == "directory":
-        return None, None
-    if entry_type not in ("file", "planned-file", "deleted-file"):
-        return None, f"unsupported type {entry_type!r}"
-    if not isinstance(file_path, str) or not file_path:
-        return None, "missing file path"
-    normalized = _normalize_git_path(file_path)
-    segments = normalized.split("/")
-    invalid = (
-        normalized.startswith("/")
-        or re.match(r"^[A-Za-z]:", normalized)
-        or any(segment in ("", ".", "..") for segment in segments)
-        or any(character in normalized for character in "*?[]")
-    )
-    return (None, f"non-canonical path {file_path!r}") if invalid else (normalized, None)
+        issues.append(
+            _context_issue(
+                "empty_implement_jsonl_file_scope",
+                "implement.jsonl contains no valid file-scope entries",
+            )
+        )
+    return allowed_files, issues
+
+
+def _repo_root_from_task_dir(task_dir: Path) -> Path:
+    task_dir = Path(task_dir)
+    if task_dir.parent.name == "tasks" and task_dir.parent.parent.name == ".cowork-flow":
+        return task_dir.parent.parent.parent
+    return task_dir.parent
 
 
 def _normalize_git_path(file_path: str) -> str: