cowork-flow 0.0.38 → 0.0.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.38",
+  "version": "0.0.39",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.38
+0.0.39

package/template/.cowork-flow/scripts/application/task_context.py

@@ -21,6 +21,11 @@ from common.core.paths import (
 
 CONTEXT_JSONL_FILES = ("implement.jsonl", "check.jsonl", "debug.jsonl")
 CONTEXT_ENTRY_TYPES = frozenset(("file", "directory", "planned-file"))
+PLANNED_FILE_HINT = (
+    "If this is a planned new file, run "
+    "./.cowork-flow/run task add-planned-file <dir> <jsonl> <path> "
+    '"reason" or add "type": "planned-file" to the JSONL entry.'
+)
 
 
 class TaskContextError(RuntimeError):
@@ -40,6 +45,15 @@ def normalize_context_path(
 ) -> 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",
@@ -47,14 +61,38 @@ def normalize_context_path(
             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
 
-    segments = normalized.split("/")
-    invalid_path = (
+
+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
@@ -62,15 +100,22 @@ def normalize_context_path(
         or any(character in normalized for character in "*?[]")
         or (entry_type == "planned-file" and str(path).endswith(("/", "\\")))
     )
-    if invalid_path:
-        raise TaskContextError(
-            "TASK-CONTEXT-PATH-002",
-            candidate,
-            "context path must be a canonical repository-relative path",
-        )
 
-    repo_root = Path(repo_root).resolve()
-    full_path = repo_root.joinpath(*segments).resolve(strict=False)
+
+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:
@@ -150,31 +195,43 @@ def validate_context_entry(
         )
 
     entry_type = data.get("type", "file")
+    normalized = str(data["file"])
     try:
         normalized_path, full_path = normalize_context_path(
             repo_root,
-            str(data["file"]),
+            normalized,
             entry_type,
         )
     except TaskContextError as error:
-        code = (
-            "invalid_entry_type"
-            if error.code == "TASK-CONTEXT-TYPE-001"
-            else "invalid_path"
-        )
+        code = _context_error_issue_code(error)
         return _context_issue(context_file, line, code, error.detail)
 
     if is_skill_path(normalized_path):
         return None
+    return _validate_context_entry_target(
+        context_file,
+        line,
+        entry_type,
+        normalized_path,
+        full_path,
+    )
+
+
+def _context_error_issue_code(error: TaskContextError) -> str:
+    if error.code == "TASK-CONTEXT-TYPE-001":
+        return "invalid_entry_type"
+    return "invalid_path"
+
+
+def _validate_context_entry_target(
+    context_file: str,
+    line: int,
+    entry_type: str,
+    normalized_path: str,
+    full_path: Path,
+) -> ContextValidationIssue | None:
     if entry_type == "planned-file":
-        if full_path.is_dir():
-            return _context_issue(
-                context_file,
-                line,
-                "invalid_path",
-                f"Planned file is a directory: {normalized_path}",
-            )
-        return None
+        return _planned_file_issue(context_file, line, normalized_path, full_path)
     if entry_type == "directory" and not full_path.is_dir():
         return _context_issue(
             context_file,
@@ -187,11 +244,27 @@ def validate_context_entry(
             context_file,
             line,
             "file_not_found",
-            f"File not found: {normalized_path}",
+            f"File not found: {normalized_path}. {PLANNED_FILE_HINT}",
         )
     return None
 
 
+def _planned_file_issue(
+    context_file: str,
+    line: int,
+    normalized_path: str,
+    full_path: Path,
+) -> ContextValidationIssue | None:
+    if not full_path.is_dir():
+        return None
+    return _context_issue(
+        context_file,
+        line,
+        "invalid_path",
+        f"Planned file is a directory: {normalized_path}",
+    )
+
+
 @dataclass(frozen=True)
 class ContextInitializationResult:
     created: tuple[str, ...]
@@ -463,6 +536,7 @@ class TaskContextService:
             created.append(file_name)
             entry_counts[file_name] = len(entries)
 
+        self.ensure_task_artifact_placeholders(task_dir)
         return ContextInitializationResult(
             created=tuple(created),
             skipped=tuple(skipped),
@@ -607,6 +681,33 @@ class TaskContextService:
                 )
         return tuple(summaries)
 
+    def ensure_task_artifact_placeholders(self, task_dir: Path) -> tuple[str, ...]:
+        """Create empty placeholders for planned task-local context files."""
+        task_dir = Path(task_dir)
+        created: list[str] = []
+        for entry in self.entries(task_dir, "implement"):
+            if entry.get("type") == "planned-file":
+                continue
+            file_path = str(entry.get("file", "")).strip()
+            if not file_path:
+                continue
+            try:
+                normalized, full_path = normalize_context_path(
+                    self.repo_root,
+                    file_path,
+                    "planned-file",
+                )
+            except TaskContextError:
+                continue
+            if not _is_task_local_artifact(task_dir, full_path):
+                continue
+            if full_path.exists():
+                continue
+            full_path.parent.mkdir(parents=True, exist_ok=True)
+            full_path.write_text("", encoding="utf-8")
+            created.append(normalized)
+        return tuple(created)
+
     def _implement_entries(self, dev_type: str) -> list[dict]:
         entries = get_implement_base()
         entries.extend(
@@ -654,3 +755,11 @@ class TaskContextService:
         if context_name.endswith(".jsonl"):
             return context_name
         return f"{context_name}.jsonl"
+
+
+def _is_task_local_artifact(task_dir: Path, full_path: Path) -> bool:
+    try:
+        full_path.resolve(strict=False).relative_to(task_dir.resolve(strict=False))
+    except ValueError:
+        return False
+    return not full_path.exists() or full_path.is_file()

package/template/.cowork-flow/scripts/commands/task.py

@@ -16,6 +16,7 @@ else:
     import _bootstrap  # noqa: F401
 
 from application.task_context import (
+    PLANNED_FILE_HINT,
     TaskContextService,
     detect_installed_platforms as _detect_installed_platforms,
     discover_spec_files as _discover_spec_files,
@@ -42,6 +43,7 @@ from application.batch_execution import (
 )
 from commands.task_archive_commands import cmd_archive
 from commands.task_context_commands import (
+    cmd_add_planned_file,
     cmd_add_context,
     cmd_init_context,
     cmd_list_context,
@@ -205,6 +207,15 @@ def _task_context_validation_issues(
     )
 
 
+def _refresh_task_artifact_placeholders(
+    task_dir: Path,
+    repo_root: Path,
+) -> list[str]:
+    service = TaskContextService(repo_root)
+    service.ensure_task_artifact_placeholders(task_dir)
+    return _task_context_validation_issues(task_dir, repo_root)
+
+
 def _optional_readiness_blockers(
     repo_root: Path,
     task_dir: Path,
@@ -243,6 +254,8 @@ def _start_preflight(
         task_dir,
         repo_root,
     )
+    if validation_issues:
+        validation_issues = _refresh_task_artifact_placeholders(task_dir, repo_root)
     if validation_issues:
         return LifecyclePreflightFailure(
             code="TASK-CONTEXT-001",
@@ -250,7 +263,7 @@ def _start_preflight(
             blockers=tuple(validation_issues),
             hint=(
                 "run ./.cowork-flow/run task validate <dir> and fix the "
-                "reported issues"
+                f"reported issues. {PLANNED_FILE_HINT}"
             ),
         )
 
@@ -302,6 +315,102 @@ def _report_lifecycle_repository_error(
     return 1
 
 
+def _resolve_start_task(
+    task_input: str,
+    repo_root: Path,
+) -> Path | None:
+    full_path = _resolve_task_dir(task_input, repo_root)
+    if full_path.is_dir():
+        return full_path
+    print(
+        colored(
+            f"Error: Task not found: {task_input}",
+            Colors.RED,
+        )
+    )
+    print(
+        "Hint: Use task name (e.g., 'my-task') or full path "
+        f"(e.g., '{DIR_WORKFLOW}/tasks/01-31-my-task')"
+    )
+    return None
+
+
+def _run_auto_start(
+    args: argparse.Namespace,
+    full_path: Path,
+    preflight,
+) -> int:
+    failure = preflight(full_path)
+    if failure is not None:
+        return _report_lifecycle_preflight(failure)
+    from common.task.batch_mode import run_batch_entry
+
+    return run_batch_entry(get_repo_root(), full_path, args)
+
+
+def _report_start_failure(
+    result: LifecycleResult,
+    service: TaskLifecycleService,
+) -> int:
+    if result.title:
+        return _report_lifecycle_preflight(result)
+    if result.code == "LIFECYCLE-TRANSITION-001":
+        _print_transition_blockers(list(result.blockers))
+        return 1
+    if result.code == "LIFECYCLE-GATE-001":
+        return _report_gate_block(
+            "Spec enforcement blocked task start",
+            result.gate_result,
+            service.gate_runner,
+        )
+    if result.code == "LIFECYCLE-CONTEXT-001":
+        return _report_missing_session_context()
+    if result.repository_error is not None:
+        return _report_lifecycle_repository_error(result)
+    print(
+        colored("Error: Task lifecycle failed", Colors.RED),
+        file=sys.stderr,
+    )
+    return 1
+
+
+def _report_missing_session_context() -> int:
+    print(
+        colored(
+            "Error: Missing session context. Set "
+            "COWORK_FLOW_CONTEXT_ID or run inside a "
+            "supported host session.",
+            Colors.RED,
+        ),
+        file=sys.stderr,
+    )
+    return 1
+
+
+def _report_start_success(
+    result: LifecycleResult,
+    repo_root: Path,
+    full_path: Path,
+) -> None:
+    task_dir = result.active_task_path or _display_task_path(
+        repo_root,
+        full_path,
+    )
+    print(
+        colored(
+            f"[OK] Active session task set to: {task_dir}",
+            Colors.GREEN,
+        )
+    )
+    print()
+    print(
+        colored(
+            "Fixed agents will load context from this task's jsonl files.",
+            Colors.BLUE,
+        )
+    )
+
+
 def cmd_start(args: argparse.Namespace) -> int:
     """Set the active task for this session."""
     repo_root = get_repo_root()
@@ -315,18 +424,8 @@ def cmd_start(args: argparse.Namespace) -> int:
         )
         return 1
 
-    full_path = _resolve_task_dir(task_input, repo_root)
-    if not full_path.is_dir():
-        print(
-            colored(
-                f"Error: Task not found: {task_input}",
-                Colors.RED,
-            )
-        )
-        print(
-            "Hint: Use task name (e.g., 'my-task') or full path "
-            f"(e.g., '{DIR_WORKFLOW}/tasks/01-31-my-task')"
-        )
+    full_path = _resolve_start_task(task_input, repo_root)
+    if full_path is None:
         return 1
 
     def preflight(
@@ -335,63 +434,14 @@ def cmd_start(args: argparse.Namespace) -> int:
         return _start_preflight(task_dir, repo_root)
 
     if getattr(args, "auto", False):
-        failure = preflight(full_path)
-        if failure is not None:
-            return _report_lifecycle_preflight(failure)
-        from common.task.batch_mode import run_batch_entry
-
-        return run_batch_entry(repo_root, full_path, args)
+        return _run_auto_start(args, full_path, preflight)
 
     service = TaskLifecycleService(repo_root)
     result = service.start(full_path, preflight=preflight)
     if not result.ok:
-        if result.title:
-            return _report_lifecycle_preflight(result)
-        if result.code == "LIFECYCLE-TRANSITION-001":
-            _print_transition_blockers(list(result.blockers))
-            return 1
-        if result.code == "LIFECYCLE-GATE-001":
-            return _report_gate_block(
-                "Spec enforcement blocked task start",
-                result.gate_result,
-                service.gate_runner,
-            )
-        if result.code == "LIFECYCLE-CONTEXT-001":
-            print(
-                colored(
-                    "Error: Missing session context. Set "
-                    "COWORK_FLOW_CONTEXT_ID or run inside a "
-                    "supported host session.",
-                    Colors.RED,
-                ),
-                file=sys.stderr,
-            )
-            return 1
-        if result.repository_error is not None:
-            return _report_lifecycle_repository_error(result)
-        print(
-            colored("Error: Task lifecycle failed", Colors.RED),
-            file=sys.stderr,
-        )
-        return 1
+        return _report_start_failure(result, service)
 
-    task_dir = result.active_task_path or _display_task_path(
-        repo_root,
-        full_path,
-    )
-    print(
-        colored(
-            f"[OK] Active session task set to: {task_dir}",
-            Colors.GREEN,
-        )
-    )
-    print()
-    print(
-        colored(
-            "Fixed agents will load context from this task's jsonl files.",
-            Colors.BLUE,
-        )
-    )
+    _report_start_success(result, repo_root, full_path)
     _run_hooks("after_start", full_path / FILE_TASK_JSON, repo_root)
     return 0
 
@@ -592,6 +642,60 @@ def cmd_current(args: argparse.Namespace) -> int:
     return 0
 
 
+WORKER_BLOCKED_COMMANDS = frozenset((
+    "create",
+    "init-context",
+    "add-context",
+    "add-planned-file",
+    "start",
+    "batch-resume",
+    "batch-record-result",
+    "review",
+    "complete",
+    "finish",
+    "archive",
+    "add-subtask",
+    "remove-subtask",
+))
+
+COMMANDS = {
+    "create": cmd_create,
+    "init-context": cmd_init_context,
+    "add-context": cmd_add_context,
+    "add-planned-file": cmd_add_planned_file,
+    "validate": cmd_validate,
+    "list-context": cmd_list_context,
+    "start": cmd_start,
+    "batch-resume": cmd_batch_resume,
+    "batch-record-result": cmd_batch_record_result,
+    "current": cmd_current,
+    "review": cmd_review,
+    "complete": cmd_complete,
+    "next": cmd_next,
+    "finish": cmd_finish,
+    "archive": cmd_archive,
+    "add-subtask": cmd_add_subtask,
+    "remove-subtask": cmd_remove_subtask,
+    "list": cmd_list,
+    "list-archive": cmd_list_archive,
+}
+
+
+def _worker_command_blocked(execution_context, command: str) -> bool:
+    if not execution_context.is_worker or command not in WORKER_BLOCKED_COMMANDS:
+        return False
+    print(
+        worker_command_block_message(
+            execution_context,
+            f"task {command}",
+            "Workers must not activate, archive, or mutate "
+            "cowork-flow task state.",
+        ),
+        file=sys.stderr,
+    )
+    return True
+
+
 def main() -> int:
     """CLI entry point."""
     args = build_parser().parse_args()
@@ -600,53 +704,10 @@ def main() -> int:
         show_usage()
         return 1
 
-    worker_blocked_commands = {
-        "create",
-        "init-context",
-        "add-context",
-        "start",
-        "batch-resume",
-        "batch-record-result",
-        "review",
-        "complete",
-        "finish",
-        "archive",
-        "add-subtask",
-        "remove-subtask",
-    }
-    if execution_context.is_worker and args.command in worker_blocked_commands:
-        print(
-            worker_command_block_message(
-                execution_context,
-                f"task {args.command}",
-                "Workers must not activate, archive, or mutate "
-                "cowork-flow task state.",
-            ),
-            file=sys.stderr,
-        )
+    if _worker_command_blocked(execution_context, args.command):
         return 2
 
-    commands = {
-        "create": cmd_create,
-        "init-context": cmd_init_context,
-        "add-context": cmd_add_context,
-        "validate": cmd_validate,
-        "list-context": cmd_list_context,
-        "start": cmd_start,
-        "batch-resume": cmd_batch_resume,
-        "batch-record-result": cmd_batch_record_result,
-        "current": cmd_current,
-        "review": cmd_review,
-        "complete": cmd_complete,
-        "next": cmd_next,
-        "finish": cmd_finish,
-        "archive": cmd_archive,
-        "add-subtask": cmd_add_subtask,
-        "remove-subtask": cmd_remove_subtask,
-        "list": cmd_list,
-        "list-archive": cmd_list_archive,
-    }
-    command = commands.get(args.command)
+    command = COMMANDS.get(args.command)
     if command is None:
         show_usage()
         return 1

package/template/.cowork-flow/scripts/commands/task_context_commands.py

@@ -8,6 +8,7 @@ from pathlib import Path
 
 from application.task_context import (
     CONTEXT_JSONL_FILES,
+    PLANNED_FILE_HINT,
     TaskContextError,
     TaskContextService,
 )
@@ -57,6 +58,15 @@ def cmd_init_context(args: argparse.Namespace) -> int:
         )
         return 1
 
+    _report_init_context_result(target_dir, dev_type, result)
+    return 0
+
+
+def _report_init_context_result(
+    target_dir: Path,
+    dev_type: str,
+    result,
+) -> None:
     print(
         colored(
             "=== Initializing Agent Context Files ===",
@@ -79,7 +89,6 @@ def cmd_init_context(args: argparse.Namespace) -> int:
             f"  {colored('[OK]', Colors.GREEN)} "
             f"{result.entry_counts[file_name]} entries"
         )
-    return 0
 
 
 def cmd_add_context(args: argparse.Namespace) -> int:
@@ -133,6 +142,12 @@ def cmd_add_context(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_add_planned_file(args: argparse.Namespace) -> int:
+    """Add a planned-file entry to a JSONL context file."""
+    args.entry_type = "planned-file"
+    return cmd_add_context(args)
+
+
 def cmd_validate(args: argparse.Namespace) -> int:
     """Validate JSONL context files."""
     repo_root = get_repo_root()
@@ -158,6 +173,8 @@ def cmd_validate(args: argparse.Namespace) -> int:
             print(
                 f"  {colored(f'{jsonl_name}:{issue.line}: {issue.message}', Colors.RED)}"
             )
+            if issue.code == "file_not_found":
+                print(f"    Hint: {PLANNED_FILE_HINT}")
         error_count = len(result.issues)
         total_errors += error_count
         if error_count == 0:

package/template/.cowork-flow/scripts/commands/task_create_command.py

@@ -25,9 +25,30 @@ from common.core.paths import (
 def cmd_create(args: argparse.Namespace) -> int:
     """Create a new task."""
     repo_root = get_repo_root()
+    request = _build_create_request(args, repo_root)
+    if request is None:
+        return 1
+
+    result = _create_task(repo_root, request)
+    if result is None:
+        return 1
+
+    _print_create_result(result)
+    run_hooks(
+        "after_create",
+        result.task_dir / FILE_TASK_JSON,
+        repo_root,
+    )
+    return 0
+
+
+def _build_create_request(
+    args: argparse.Namespace,
+    repo_root,
+) -> TaskCreationRequest | None:
     if not args.title:
         print(colored("Error: title is required", Colors.RED), file=sys.stderr)
-        return 1
+        return None
 
     assignee = args.assignee or get_developer(repo_root)
     if not assignee:
@@ -39,7 +60,7 @@ def cmd_create(args: argparse.Namespace) -> int:
             ),
             file=sys.stderr,
         )
-        return 1
+        return None
 
     creator = get_developer(repo_root) or assignee
     slug = args.slug or slugify(args.title)
@@ -51,21 +72,23 @@ def cmd_create(args: argparse.Namespace) -> int:
             ),
             file=sys.stderr,
         )
-        return 1
+        return None
+
+    return TaskCreationRequest(
+        title=args.title,
+        slug=slug,
+        assignee=assignee,
+        priority=args.priority,
+        description=args.description,
+        creator=creator,
+        parent=args.parent,
+        from_plan=getattr(args, "from_plan", None),
+    )
+
 
+def _create_task(repo_root, request: TaskCreationRequest):
     try:
-        result = TaskCreationService(repo_root).create(
-            TaskCreationRequest(
-                title=args.title,
-                slug=slug,
-                assignee=assignee,
-                priority=args.priority,
-                description=args.description,
-                creator=creator,
-                parent=args.parent,
-                from_plan=getattr(args, "from_plan", None),
-            )
-        )
+        return TaskCreationService(repo_root).create(request)
     except TaskCreationError as error:
         print(
             colored(
@@ -74,8 +97,10 @@ def cmd_create(args: argparse.Namespace) -> int:
             ),
             file=sys.stderr,
         )
-        return 1
+        return None
+
 
+def _print_create_result(result) -> None:
     dir_name = result.task_dir.name
     if result.directory_existed:
         print(
@@ -112,6 +137,11 @@ def cmd_create(args: argparse.Namespace) -> int:
         colored(f"Created task: {dir_name}", Colors.GREEN),
         file=sys.stderr,
     )
+    _print_next_steps()
+    print(f"{DIR_WORKFLOW}/{DIR_TASKS}/{dir_name}")
+
+
+def _print_next_steps() -> None:
     print("", file=sys.stderr)
     print(colored("Next steps:", Colors.BLUE), file=sys.stderr)
     print(
@@ -126,12 +156,9 @@ def cmd_create(args: argparse.Namespace) -> int:
         "  3. Run: ./.cowork-flow/run task start <dir>",
         file=sys.stderr,
     )
-    print("", file=sys.stderr)
-    print(f"{DIR_WORKFLOW}/{DIR_TASKS}/{dir_name}")
-
-    run_hooks(
-        "after_create",
-        result.task_dir / FILE_TASK_JSON,
-        repo_root,
+    print(
+        "  Planned new files: ./.cowork-flow/run task add-planned-file "
+        "<dir> implement <path> \"reason\"",
+        file=sys.stderr,
     )
-    return 0
+    print("", file=sys.stderr)

package/template/.cowork-flow/scripts/commands/task_parser.py

@@ -42,6 +42,8 @@ Usage:
   ./.cowork-flow/run task init-context <dir> <dev_type>      Initialize jsonl files
   ./.cowork-flow/run task add-context <dir> <jsonl> <path> [reason] [--type TYPE]
                                                                   Add entry to jsonl
+  ./.cowork-flow/run task add-planned-file <dir> <jsonl> <path> [reason]
+                                                                  Add planned file entry
   ./.cowork-flow/run task validate <dir>                     Validate jsonl files
   ./.cowork-flow/run task list-context <dir>                 List jsonl entries
   ./.cowork-flow/run task start <dir>                        Set active session task
@@ -69,6 +71,7 @@ Examples:
   ./.cowork-flow/run task next
   ./.cowork-flow/run task add-context <dir> implement .cowork-flow/spec/backend/auth.md "Auth guidelines"
   ./.cowork-flow/run task add-context <dir> implement src/new.py "Planned source" --type planned-file
+  ./.cowork-flow/run task add-planned-file <dir> implement src/new.py "Planned source"
   ./.cowork-flow/run task start .cowork-flow/tasks/01-21-add-login
   ./.cowork-flow/run task review
   ./.cowork-flow/run task complete
@@ -119,6 +122,24 @@ def _add_add_context_command(subparsers: argparse._SubParsersAction) -> None:
     )
 
 
+def _add_add_planned_file_command(subparsers: argparse._SubParsersAction) -> None:
+    add_planned_file = subparsers.add_parser(
+        "add-planned-file",
+        help="Add planned file context entry",
+    )
+    add_planned_file.add_argument("dir", help="Task directory")
+    add_planned_file.add_argument(
+        "file",
+        help="JSONL file (implement|check|debug)",
+    )
+    add_planned_file.add_argument("path", help="Planned file path to add")
+    add_planned_file.add_argument(
+        "reason",
+        nargs="?",
+        help="Reason for adding",
+    )
+
+
 def _add_context_validation_commands(subparsers: argparse._SubParsersAction) -> None:
     validate = subparsers.add_parser(
         "validate",
@@ -136,6 +157,7 @@ def _add_context_validation_commands(subparsers: argparse._SubParsersAction) ->
 def _add_context_commands(subparsers: argparse._SubParsersAction) -> None:
     _add_init_context_command(subparsers)
     _add_add_context_command(subparsers)
+    _add_add_planned_file_command(subparsers)
     _add_context_validation_commands(subparsers)
 
 

package/template/.cowork-flow/scripts/common/gates/validate_coding_standards.py

@@ -39,6 +39,16 @@ _EXTENSIONS = {
 
 _BACKEND_SUFFIXES = re.compile(r"\.(py|java|go|rs|rb|cs|kt|php)$")
 _FRONTEND_SUFFIXES = re.compile(r"\.(tsx|jsx|vue|svelte|ts|js|mjs|cjs|css|scss)$")
+_SECRET_RE = re.compile(
+    r"""(?ix)
+    (?:password|passwd|secret|api[_\s]?key|token|access[_\s]?key)
+    \s*[:=]\s*["'][^"'}{)($]{3,}["']
+    """
+)
+_SILENT_EXCEPT_RE = re.compile(r"^\s*except\b\s*.*:\s*(#.*)?$")
+_BARE_PRINT_RE = re.compile(r"(?<!\w)print\s*\(")
+_CONSOLE_RE = re.compile(r"\bconsole\.(log|info|debug)\s*\(")
+_JS_SUFFIXES = {".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx"}
 
 
 def _is_backend_file(rel_path: str) -> bool:
@@ -80,8 +90,8 @@ def load_spec_rules(
     """Return every natural-language rule declared under ``spec/<category>/``.
 
     Re-reads markdown on every call, so user edits take effect without restart.
-    ``validators`` is preserved as an empty list (legacy field kept so external
-    tooling that inspects the rule dict does not break).
+    The returned rule shape is the current runtime checklist contract:
+    category, source, line, and text.
     """
     out: list[dict] = []
     repo_root = Path(repo_root)
@@ -102,7 +112,6 @@ def load_spec_rules(
                     "source": f".cowork-flow/spec/{category}/{md.name}",
                     "line": lineno,
                     "text": rule,
-                    "validators": [],
                 })
     return out
 
@@ -171,72 +180,105 @@ def collect_machine_checks(
     whether to render them in a gate log, inject them into context, or ignore.
     """
     violations: list[dict] = []
+    for changed_file in _changed_machine_check_files(repo_root):
+        violations.extend(_machine_check_violations_for_file(repo_root, changed_file))
+    return violations
+
+
+def _changed_machine_check_files(repo_root: Path) -> Sequence[object]:
     try:
-        changed_files = collect_changed_files(repo_root)
+        return collect_changed_files(repo_root)
     except Exception:  # noqa: BLE001 — defensively isolate git errors
-        return violations
+        return ()
 
-    secret_re = re.compile(
-        r"""(?ix)
-        (?:password|passwd|secret|api[_\s]?key|token|access[_\s]?key)
-        \s*[:=]\s*["'][^"'}{)($]{3,}["']
-        """
-    )
-    silent_except_re = re.compile(r"^\s*except\b\s*.*:\s*(#.*)?$")
-    bare_print_re = re.compile(r"(?<!\w)print\s*\(")
-    console_re = re.compile(r"\bconsole\.(log|info|debug)\s*\(")
 
-    for changed_file in changed_files:
-        file_path = repo_root / changed_file.path
-        if not file_path.is_file():
-            continue
-        suffix = file_path.suffix.lower()
-        if suffix not in _EXTENSIONS:
-            continue
-        try:
-            content = file_path.read_text(encoding="utf-8")
-        except (OSError, UnicodeDecodeError):
-            continue
-        lines = content.splitlines()
-        for lineno, raw in enumerate(lines, start=1):
-            # Low-signal heuristic: only flag if the line also has an
-            # assignment / call so variable-name mentions do not trip it.
-            if (secret_re.search(raw)
-                    and "process.env" not in raw
-                    and "os.environ" not in raw):
-                violations.append(_adv(
-                    "MACHINE-HARDCODED-SECRET-001",
-                    "Possible hard-coded secret in source",
-                    changed_file.path, lineno,
-                    "Read the value from configuration or environment variables.",
-                ))
-            if suffix == ".py" and bare_print_re.search(raw):
-                violations.append(_adv(
-                    "MACHINE-DEBUG-PRINT-001",
-                    "Debug print on changed line",
-                    changed_file.path, lineno,
-                    "Use a structured logger or remove the print.",
-                ))
-            if suffix in {".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx"} and console_re.search(raw):
-                violations.append(_adv(
-                    "MACHINE-CONSOLE-LOG-001",
-                    "console.{log,info,debug} on changed line",
-                    changed_file.path, lineno,
-                    "Use the project logger or remove the call.",
-                ))
-            if (suffix == ".py"
-                    and silent_except_re.match(raw)
-                    and lineno < len(lines)
-                    and lines[lineno].strip() in {"pass", "...", ""}):
-                violations.append(_adv(
-                    "MACHINE-SILENT-EXCEPT-001",
-                    "Empty exception handler silently swallows errors",
-                    changed_file.path, lineno,
-                    "Log or re-raise the exception, or narrow the except types.",
-                ))
+def _machine_check_violations_for_file(repo_root: Path, changed_file: object) -> list[dict]:
+    file_path = repo_root / changed_file.path
+    if not file_path.is_file():
+        return []
+    suffix = file_path.suffix.lower()
+    if suffix not in _EXTENSIONS:
+        return []
+    try:
+        content = file_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return []
+    return _machine_check_violations_for_lines(changed_file.path, suffix, content.splitlines())
+
+
+def _machine_check_violations_for_lines(
+    rel_path: str,
+    suffix: str,
+    lines: list[str],
+) -> list[dict]:
+    violations: list[dict] = []
+    for lineno, raw in enumerate(lines, start=1):
+        violations.extend(_machine_check_violations_for_line(rel_path, suffix, lines, lineno, raw))
+    return violations
+
+
+def _machine_check_violations_for_line(
+    rel_path: str,
+    suffix: str,
+    lines: list[str],
+    lineno: int,
+    raw: str,
+) -> list[dict]:
+    violations: list[dict] = []
+    if _looks_like_hardcoded_secret(raw):
+        violations.append(_adv(
+            "MACHINE-HARDCODED-SECRET-001",
+            "Possible hard-coded secret in source",
+            rel_path, lineno,
+            "Read the value from configuration or environment variables.",
+        ))
+    if suffix == ".py" and _BARE_PRINT_RE.search(raw):
+        violations.append(_adv(
+            "MACHINE-DEBUG-PRINT-001",
+            "Debug print on changed line",
+            rel_path, lineno,
+            "Use a structured logger or remove the print.",
+        ))
+    if suffix in _JS_SUFFIXES and _CONSOLE_RE.search(raw):
+        violations.append(_adv(
+            "MACHINE-CONSOLE-LOG-001",
+            "console.{log,info,debug} on changed line",
+            rel_path, lineno,
+            "Use the project logger or remove the call.",
+        ))
+    if _is_silent_python_except(suffix, lines, lineno, raw):
+        violations.append(_adv(
+            "MACHINE-SILENT-EXCEPT-001",
+            "Empty exception handler silently swallows errors",
+            rel_path, lineno,
+            "Log or re-raise the exception, or narrow the except types.",
+        ))
     return violations
 
 
+def _looks_like_hardcoded_secret(raw: str) -> bool:
+    # Low-signal heuristic: only flag if the line also has an assignment / call.
+    return (
+        _SECRET_RE.search(raw) is not None
+        and "process.env" not in raw
+        and "os.environ" not in raw
+    )
+
+
+def _is_silent_python_except(
+    suffix: str,
+    lines: list[str],
+    lineno: int,
+    raw: str,
+) -> bool:
+    return (
+        suffix == ".py"
+        and _SILENT_EXCEPT_RE.match(raw) is not None
+        and lineno < len(lines)
+        and lines[lineno].strip() in {"pass", "...", ""}
+    )
+
+
 def _adv(
     rule_id: str,
     message: str,

package/template/.cowork-flow/scripts/common/task/active_task.py

@@ -54,88 +54,50 @@ def _first_prompt_value(values: Mapping[str, object] | None) -> str | None:
 
 
 def resolve_context_key(values: Mapping[str, object] | None = None) -> str | None:
-    explicit = os.environ.get("COWORK_FLOW_CONTEXT_ID")
-    if explicit and explicit.strip():
-        return _sanitize(explicit)
-
-    opencode_session = os.environ.get("OPENCODE_SESSION_ID")
-    if opencode_session and opencode_session.strip():
-        return f"opencode_{_sanitize(opencode_session)}"
-
-    claude_session = os.environ.get("CLAUDE_SESSION_ID")
-    if claude_session and claude_session.strip():
-        return f"claude_{_sanitize(claude_session)}"
+    return _resolve_env_context_key() or _resolve_input_context_key(values)
 
-    claude_code_session = os.environ.get("CLAUDE_CODE_SESSION_ID")
-    if claude_code_session and claude_code_session.strip():
-        return f"claude_{_sanitize(claude_code_session)}"
 
-    codex_session = os.environ.get("CODEX_SESSION_ID")
-    if codex_session and codex_session.strip():
-        return f"codex_{_sanitize(codex_session)}"
+def _prefixed_context_key(prefix: str, raw: str | None) -> str | None:
+    if raw and raw.strip():
+        return f"{prefix}_{_sanitize(raw)}"
+    return None
 
-    codex_thread = os.environ.get("CODEX_THREAD_ID")
-    if codex_thread and codex_thread.strip():
-        return f"codex_{_sanitize(codex_thread)}"
 
-    input_explicit = _first_input_value(
-        values,
-        (
-            "COWORK_FLOW_CONTEXT_ID",
-            "cowork_flow_context_id",
-            "context_id",
-        ),
-    )
-    if input_explicit:
-        return _sanitize(input_explicit)
-
-    input_opencode_session = _first_input_value(
-        values,
-        (
-            "OPENCODE_SESSION_ID",
-            "opencode_session_id",
-            "sessionID",
-            "sessionId",
-        ),
-    )
-    if input_opencode_session:
-        return f"opencode_{_sanitize(input_opencode_session)}"
+def _resolve_env_context_key() -> str | None:
+    explicit = os.environ.get("COWORK_FLOW_CONTEXT_ID")
+    if explicit and explicit.strip():
+        return _sanitize(explicit)
 
-    input_claude_session = _first_input_value(
-        values,
-        (
-            "CLAUDE_SESSION_ID",
-            "claude_session_id",
-            "CLAUDE_CODE_SESSION_ID",
-            "claude_code_session_id",
-        ),
-    )
-    if input_claude_session:
-        return f"claude_{_sanitize(input_claude_session)}"
+    for prefix, env_name in (
+        ("opencode", "OPENCODE_SESSION_ID"),
+        ("claude", "CLAUDE_SESSION_ID"),
+        ("claude", "CLAUDE_CODE_SESSION_ID"),
+        ("codex", "CODEX_SESSION_ID"),
+        ("codex", "CODEX_THREAD_ID"),
+    ):
+        context_key = _prefixed_context_key(prefix, os.environ.get(env_name))
+        if context_key:
+            return context_key
+    return None
 
-    input_session = _first_input_value(
-        values,
-        (
-            "CODEX_SESSION_ID",
-            "codex_session_id",
-            "session_id",
-        ),
-    )
-    if input_session:
-        return f"codex_{_sanitize(input_session)}"
 
-    input_thread = _first_input_value(
+def _resolve_input_context_key(values: Mapping[str, object] | None) -> str | None:
+    explicit = _first_input_value(
         values,
-        (
-            "CODEX_THREAD_ID",
-            "codex_thread_id",
-            "thread_id",
-            "conversation_id",
-        ),
+        ("COWORK_FLOW_CONTEXT_ID", "cowork_flow_context_id", "context_id"),
     )
-    if input_thread:
-        return f"codex_{_sanitize(input_thread)}"
+    if explicit:
+        return _sanitize(explicit)
 
+    for prefix, names in (
+        ("opencode", ("OPENCODE_SESSION_ID", "opencode_session_id", "sessionID", "sessionId")),
+        ("claude", ("CLAUDE_SESSION_ID", "claude_session_id", "CLAUDE_CODE_SESSION_ID", "claude_code_session_id")),
+        ("codex", ("CODEX_SESSION_ID", "codex_session_id", "session_id")),
+        ("codex", ("CODEX_THREAD_ID", "codex_thread_id", "thread_id", "conversation_id")),
+    ):
+        context_key = _prefixed_context_key(prefix, _first_input_value(values, names))
+        if context_key:
+            return context_key
     return None
 
 
@@ -361,12 +323,12 @@ def is_main_session(repo_root: Path, values: Mapping[str, object] | None = None)
         return False
     data = _read_json(_session_path(repo_root, context_key))
     scope = data.get(FIELD_SCOPE)
-    legacy_main_session = (
+    historical_unscoped_main_session = (
         scope is None
         and not context_key.startswith("subagent_")
     )
     return (
-        (scope == SCOPE_MAIN or legacy_main_session)
+        (scope == SCOPE_MAIN or historical_unscoped_main_session)
         and not data.get(FIELD_RUNTIME_CONTEXT_ID)
     )
 

package/template/.zcode/.zcode-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.38",
+  "version": "0.0.39",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 ZCode。",
   "author": {
     "name": "fisklikewater"