cowork-flow 0.0.46 → 0.0.47

package/package.json

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

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.46
+0.0.47

package/template/.cowork-flow/scripts/adapters/cli/task.py

@@ -5,7 +5,6 @@
 from __future__ import annotations
 
 import argparse
-import json
 import sys
 from datetime import datetime
 from pathlib import Path
@@ -48,6 +47,11 @@ from adapters.cli.task_context_commands import (
 from adapters.cli.task_create_command import cmd_create, ensure_tasks_dir
 from adapters.cli import task_navigation
 from adapters.cli.task_parser import build_parser, show_usage
+from adapters.cli.task_next_runner import (
+    NextActionHandlers,
+    namespace_with as _args_with,
+    run_next_action,
+)
 from adapters.cli.task_support import (
     Colors,
     colored,
@@ -57,6 +61,7 @@ from adapters.cli.task_support import (
 from adapters.cli.task_tree_commands import (
     cmd_add_subtask,
     cmd_list,
+    cmd_list_json,
     cmd_list_archive,
     cmd_remove_subtask,
 )
@@ -537,189 +542,6 @@ def cmd_current(args: argparse.Namespace) -> int:
     return 0
 
 
-def _next_target_for_run(args: argparse.Namespace, repo_root: Path):
-    target_input = getattr(args, "dir", None)
-    if target_input:
-        task_dir = _resolve_task_dir(target_input, repo_root)
-        return task_dir, _display_task_path(repo_root, task_dir), False
-
-    active = get_active_task(repo_root)
-    if active.task_path:
-        task_dir = repo_root / active.task_path
-        return task_dir, active.task_path, True
-    return None, None, False
-
-
-def _next_payload_for_run(args: argparse.Namespace, repo_root: Path) -> dict[str, object]:
-    task_dir, task_path, active_target = _next_target_for_run(args, repo_root)
-    if task_dir is None or task_path is None:
-        return task_navigation.build_navigation_payload(
-            args=args,
-            status="no_task",
-            blockers=[],
-            active_target=False,
-            task_path=None,
-        )
-    if not task_dir.is_dir():
-        return task_navigation.build_navigation_payload(
-            args=args,
-            status="stale",
-            blockers=[f"task directory not found: {task_path}"],
-            active_target=active_target,
-            task_path=task_path,
-        )
-    status = task_navigation._status(repo_root, task_dir)
-    blockers = task_navigation._blockers(repo_root, task_dir) if status == "planning" else []
-    return task_navigation.build_navigation_payload(
-        args=args,
-        status=status,
-        blockers=blockers,
-        active_target=active_target,
-        task_path=task_path,
-    )
-
-
-def _args_with(args: argparse.Namespace, **overrides) -> argparse.Namespace:
-    values = vars(args).copy()
-    values.update(overrides)
-    return argparse.Namespace(**values)
-
-
-def _run_create_action(args: argparse.Namespace, action: dict[str, object]) -> int:
-    if not getattr(args, "title", None):
-        print(
-            colored("Error: create_task requires --title", Colors.RED),
-            file=sys.stderr,
-        )
-        print(f"Command: {action.get('command')}", file=sys.stderr)
-        return 1
-    return cmd_create(
-        _args_with(
-            args,
-            title=args.title,
-            slug=getattr(args, "slug", None),
-            assignee=getattr(args, "assignee", None),
-            priority=getattr(args, "priority", "P2"),
-            description=getattr(args, "description", None),
-            parent=getattr(args, "parent", None),
-            from_plan=getattr(args, "from_plan", None),
-        )
-    )
-
-
-def _create_input_names(args: argparse.Namespace) -> list[str]:
-    names = (
-        "title",
-        "slug",
-        "assignee",
-        "description",
-        "parent",
-        "from_plan",
-    )
-    return [name for name in names if getattr(args, name, None)]
-
-
-def _validated_next_action(args: argparse.Namespace) -> tuple[dict[str, object] | None, int]:
-    payload = _next_payload_for_run(args, get_repo_root())
-    action = payload.get("action")
-    if not isinstance(action, dict):
-        print(
-            colored("Error: task next did not return an action", Colors.RED),
-            file=sys.stderr,
-        )
-        return None, 1
-    create_inputs = _create_input_names(args)
-    action_id = action.get("id")
-    if create_inputs and action_id != "create_task":
-        print(
-            colored(
-                f"Error: create_task inputs cannot run {action_id}",
-                Colors.RED,
-            ),
-            file=sys.stderr,
-        )
-        print(
-            "Hint: archive or finish the current task first, then rerun "
-            "`task next --run --title ... --slug ... --assignee <name>`.",
-            file=sys.stderr,
-        )
-        return None, 1
-    if payload.get("blockers") or action.get("blockers"):
-        print(colored("Error: next action is blocked", Colors.RED), file=sys.stderr)
-        for blocker in payload.get("blockers", []) or action.get("blockers", []):
-            print(f"  - {blocker}", file=sys.stderr)
-        return None, 1
-    if not action.get("runnable"):
-        action_id = action.get("id")
-        print(
-            colored(f"Error: next action is not executable: {action_id}", Colors.RED),
-            file=sys.stderr,
-        )
-        if action.get("command"):
-            print(f"Command: {action['command']}", file=sys.stderr)
-        return None, 1
-    return action, 0
-
-
-def _resolved_next_action_task(args: argparse.Namespace, action_id: object) -> str | None:
-    if action_id == "create_task":
-        return None
-    _, task_path_value, _ = _next_target_for_run(args, get_repo_root())
-    if task_path_value is None:
-        print(colored("Error: no task target for action", Colors.RED), file=sys.stderr)
-        return None
-    return task_path_value
-
-
-def _dispatch_next_lifecycle_action(
-    args: argparse.Namespace,
-    action_id: object,
-    task_path: str | None,
-    action: dict[str, object],
-) -> int:
-    if action_id == "create_task":
-        return _run_create_action(args, action)
-    if task_path is None:
-        return 1
-    if action_id == "start_task":
-        return cmd_start(_args_with(
-            args,
-            dir=task_path,
-            auto=bool(getattr(args, "auto", False)),
-            approved=bool(getattr(args, "approved", False)),
-        ))
-    if action_id == "request_review":
-        return cmd_review(_args_with(args, dir=task_path))
-    if action_id == "complete_task":
-        return cmd_complete(_args_with(args, dir=task_path))
-    if action_id == "archive_task":
-        return cmd_archive(_args_with(
-            args,
-            name=Path(str(task_path)).name,
-            commit=bool(getattr(args, "commit", False)),
-        ))
-    if action_id == "batch_execute":
-        return cmd_start(_args_with(
-            args,
-            dir=task_path,
-            auto=True,
-            approved=bool(getattr(args, "approved", False)),
-        ))
-    print(
-        colored(f"Error: unsupported next action: {action_id}", Colors.RED),
-        file=sys.stderr,
-    )
-    return 1
-
-
-def _run_next_action(args: argparse.Namespace) -> int:
-    action, error_code = _validated_next_action(args)
-    if action is None:
-        return error_code
-    action_id = action.get("id")
-    task_path = _resolved_next_action_task(args, action_id)
-    return _dispatch_next_lifecycle_action(args, action_id, task_path, action)
-
 def cmd_next(args: argparse.Namespace) -> int:
     """Show or run the next workflow action."""
     if getattr(args, "list_tasks", False):
@@ -729,6 +551,14 @@ def cmd_next(args: argparse.Namespace) -> int:
                 file=sys.stderr,
             )
             return 1
+        if getattr(args, "json", False):
+            return cmd_list_json(
+                _args_with(
+                    args,
+                    mine=bool(getattr(args, "mine", False)),
+                    status=getattr(args, "status", None),
+                )
+            )
         return cmd_list(
             _args_with(
                 args,
@@ -751,7 +581,16 @@ def cmd_next(args: argparse.Namespace) -> int:
             return 1
         return cmd_validate(_args_with(args, dir=args.dir))
     if getattr(args, "run", False):
-        return _run_next_action(args)
+        return run_next_action(
+            args,
+            NextActionHandlers(
+                create=cmd_create,
+                start=cmd_start,
+                review=cmd_review,
+                complete=cmd_complete,
+                archive=cmd_archive,
+            ),
+        )
     return task_navigation.cmd_next(args)
 
 

package/template/.cowork-flow/scripts/adapters/cli/task_navigation.py

@@ -18,6 +18,13 @@ from services.task_repository import TaskRepository, TaskRepositoryError
 from services.task_routing import _default_intent, route_request
 
 
+RECOVERABLE_TASK_STATUSES = {
+    "in_progress": "active_unbound",
+    "review": "active_unbound",
+    "completed": "completed_unarchived",
+}
+
+
 
 def _display(repo_root: Path, task_dir: Path) -> str:
     try:
@@ -41,6 +48,61 @@ def _blockers(repo_root: Path, task_dir: Path) -> list[str]:
     return blockers
 
 
+def repository_recovery_signals(repo_root: Path) -> list[dict[str, str]]:
+    tasks_dir = repo_root / ".cowork-flow" / "tasks"
+    if not tasks_dir.is_dir():
+        return []
+    signals: list[dict[str, str]] = []
+    for task_dir in sorted(tasks_dir.iterdir()):
+        if not task_dir.is_dir() or task_dir.name == "archive":
+            continue
+        status = _status(repo_root, task_dir)
+        kind = RECOVERABLE_TASK_STATUSES.get(status)
+        if kind is None:
+            continue
+        task = _display(repo_root, task_dir)
+        hint = f"./.cowork-flow/run task next {task} --run"
+        if kind == "completed_unarchived":
+            hint = f"{hint} --intent archive"
+        signals.append(
+            {
+                "kind": kind,
+                "task": task,
+                "status": status,
+                "hint": hint,
+            }
+        )
+    return signals
+
+
+def _attach_recovery(payload: dict[str, object], repo_root: Path) -> dict[str, object]:
+    signals = repository_recovery_signals(repo_root)
+    if signals:
+        payload["recovery"] = {
+            "signals": signals,
+            "listCommand": "./.cowork-flow/run task next --list --json",
+        }
+    return payload
+
+
+def _print_recovery(payload: dict[str, object]) -> None:
+    recovery = payload.get("recovery")
+    if not isinstance(recovery, dict):
+        return
+    signals = recovery.get("signals")
+    if not isinstance(signals, list) or not signals:
+        return
+    print("Recovery:")
+    for signal in signals:
+        if isinstance(signal, dict):
+            print(
+                f"  - {signal.get('kind')}: {signal.get('task')} "
+                f"({signal.get('status')})"
+            )
+            print(f"    Hint: {signal.get('hint')}")
+    print(f"List: {recovery.get('listCommand')}")
+
+
 def _print_blockers(blockers: list[str]) -> None:
     if not blockers:
         print("Blockers: none")
@@ -105,6 +167,9 @@ def _print_text_payload(payload: dict[str, object]) -> None:
     print(f"Next action: {action['label']}")
     print(f"Skill: {action['activatedSkill'] or 'none'}")
     print(f"Command: {action['command'] or 'none'}")
+    diagnostics_command = action.get("diagnosticsCommand")
+    if diagnostics_command:
+        print(f"Diagnostics: {diagnostics_command}")
     blockers = payload["blockers"]
     if not isinstance(blockers, list):
         raise TypeError("navigation payload blockers must be a list")
@@ -123,13 +188,15 @@ def _navigation_target(args, repo_root: Path, structured: bool):
     if active.task_path:
         return repo_root / active.task_path, active.task_path, source, True
     if structured:
-        _print_json_route(
+        payload = build_navigation_payload(
             args=args,
             status="no_task",
             blockers=[],
             active_target=False,
             task_path=None,
         )
+        _attach_recovery(payload, repo_root)
+        print(json.dumps(payload, ensure_ascii=False, sort_keys=False))
     else:
         print("Status: no_task")
         print(f"Source: {source}")
@@ -140,7 +207,9 @@ def _navigation_target(args, repo_root: Path, structured: bool):
             blockers=[],
             active_target=False,
         )
+        _attach_recovery(payload, repo_root)
         _print_text_payload(payload)
+        _print_recovery(payload)
     return None
 
 

package/template/.cowork-flow/scripts/adapters/cli/task_next_runner.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""Delivery runner for deterministic `task next --run` actions."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+from adapters.cli import task_navigation
+from adapters.cli.task_support import Colors, colored, resolve_task_dir
+from infra.paths import get_repo_root
+from runtime.session_state import get_active_task
+
+
+LifecycleCommand = Callable[[argparse.Namespace], int]
+
+
+@dataclass(frozen=True)
+class NextActionHandlers:
+    create: LifecycleCommand
+    start: LifecycleCommand
+    review: LifecycleCommand
+    complete: LifecycleCommand
+    archive: LifecycleCommand
+
+
+def namespace_with(args: argparse.Namespace, **overrides) -> argparse.Namespace:
+    values = vars(args).copy()
+    values.update(overrides)
+    return argparse.Namespace(**values)
+
+
+def _display_task_path(repo_root: Path, task_dir: Path) -> str:
+    try:
+        return task_dir.resolve().relative_to(repo_root.resolve()).as_posix()
+    except ValueError:
+        return str(task_dir)
+
+
+def _next_target_for_run(args: argparse.Namespace, repo_root: Path):
+    target_input = getattr(args, "dir", None)
+    if target_input:
+        task_dir = resolve_task_dir(target_input, repo_root)
+        return task_dir, _display_task_path(repo_root, task_dir), False
+
+    active = get_active_task(repo_root)
+    if active.task_path:
+        task_dir = repo_root / active.task_path
+        return task_dir, active.task_path, True
+    return None, None, False
+
+
+def _next_payload_for_run(args: argparse.Namespace, repo_root: Path) -> dict[str, object]:
+    task_dir, task_path, active_target = _next_target_for_run(args, repo_root)
+    if task_dir is None or task_path is None:
+        return task_navigation.build_navigation_payload(
+            args=args,
+            status="no_task",
+            blockers=[],
+            active_target=False,
+            task_path=None,
+        )
+    if not task_dir.is_dir():
+        return task_navigation.build_navigation_payload(
+            args=args,
+            status="stale",
+            blockers=[f"task directory not found: {task_path}"],
+            active_target=active_target,
+            task_path=task_path,
+        )
+    status = task_navigation._status(repo_root, task_dir)
+    blockers = task_navigation._blockers(repo_root, task_dir) if status == "planning" else []
+    return task_navigation.build_navigation_payload(
+        args=args,
+        status=status,
+        blockers=blockers,
+        active_target=active_target,
+        task_path=task_path,
+    )
+
+
+def _run_create_action(
+    args: argparse.Namespace,
+    action: dict[str, object],
+    handlers: NextActionHandlers,
+) -> int:
+    if not getattr(args, "title", None):
+        print(
+            colored("Error: create_task requires --title", Colors.RED),
+            file=sys.stderr,
+        )
+        print(f"Command: {action.get('command')}", file=sys.stderr)
+        return 1
+    return handlers.create(
+        namespace_with(
+            args,
+            title=args.title,
+            slug=getattr(args, "slug", None),
+            assignee=getattr(args, "assignee", None),
+            priority=getattr(args, "priority", "P2"),
+            description=getattr(args, "description", None),
+            parent=getattr(args, "parent", None),
+            from_plan=getattr(args, "from_plan", None),
+        )
+    )
+
+
+def _create_input_names(args: argparse.Namespace) -> list[str]:
+    names = (
+        "title",
+        "slug",
+        "assignee",
+        "description",
+        "parent",
+        "from_plan",
+    )
+    return [name for name in names if getattr(args, name, None)]
+
+
+def _validated_next_action(args: argparse.Namespace) -> tuple[dict[str, object] | None, int]:
+    payload = _next_payload_for_run(args, get_repo_root())
+    action = payload.get("action")
+    if not isinstance(action, dict):
+        print(
+            colored("Error: task next did not return an action", Colors.RED),
+            file=sys.stderr,
+        )
+        return None, 1
+    create_inputs = _create_input_names(args)
+    action_id = action.get("id")
+    if create_inputs and action_id != "create_task":
+        print(
+            colored(
+                f"Error: create_task inputs cannot run {action_id}",
+                Colors.RED,
+            ),
+            file=sys.stderr,
+        )
+        print(
+            "Hint: archive or finish the current task first, then rerun "
+            "`task next --run --title ... --slug ... --assignee <name>`.",
+            file=sys.stderr,
+        )
+        return None, 1
+    if payload.get("blockers") or action.get("blockers"):
+        print(colored("Error: next action is blocked", Colors.RED), file=sys.stderr)
+        for blocker in payload.get("blockers", []) or action.get("blockers", []):
+            print(f"  - {blocker}", file=sys.stderr)
+        return None, 1
+    if not action.get("runnable"):
+        action_id = action.get("id")
+        print(
+            colored(f"Error: next action is not executable: {action_id}", Colors.RED),
+            file=sys.stderr,
+        )
+        if action.get("command"):
+            print(f"Command: {action['command']}", file=sys.stderr)
+        return None, 1
+    return action, 0
+
+
+def _resolved_next_action_task(args: argparse.Namespace, action_id: object) -> str | None:
+    if action_id == "create_task":
+        return None
+    _, task_path_value, _ = _next_target_for_run(args, get_repo_root())
+    if task_path_value is None:
+        print(colored("Error: no task target for action", Colors.RED), file=sys.stderr)
+        return None
+    return task_path_value
+
+
+def _dispatch_next_lifecycle_action(
+    args: argparse.Namespace,
+    action_id: object,
+    task_path: str | None,
+    action: dict[str, object],
+    handlers: NextActionHandlers,
+) -> int:
+    if action_id == "create_task":
+        return _run_create_action(args, action, handlers)
+    if task_path is None:
+        return 1
+    if action_id == "start_task":
+        return handlers.start(
+            namespace_with(
+                args,
+                dir=task_path,
+                auto=bool(getattr(args, "auto", False)),
+                approved=bool(getattr(args, "approved", False)),
+            )
+        )
+    if action_id == "request_review":
+        return handlers.review(namespace_with(args, dir=task_path))
+    if action_id == "complete_task":
+        return handlers.complete(namespace_with(args, dir=task_path))
+    if action_id == "archive_task":
+        return handlers.archive(
+            namespace_with(
+                args,
+                name=Path(str(task_path)).name,
+                commit=bool(getattr(args, "commit", False)),
+            )
+        )
+    if action_id == "batch_execute":
+        return handlers.start(
+            namespace_with(
+                args,
+                dir=task_path,
+                auto=True,
+                approved=bool(getattr(args, "approved", False)),
+            )
+        )
+    print(
+        colored(f"Error: unsupported next action: {action_id}", Colors.RED),
+        file=sys.stderr,
+    )
+    return 1
+
+
+def run_next_action(args: argparse.Namespace, handlers: NextActionHandlers) -> int:
+    action, error_code = _validated_next_action(args)
+    if action is None:
+        return error_code
+    action_id = action.get("id")
+    task_path = _resolved_next_action_task(args, action_id)
+    return _dispatch_next_lifecycle_action(args, action_id, task_path, action, handlers)

package/template/.cowork-flow/scripts/adapters/cli/task_parser.py

@@ -14,7 +14,7 @@ USAGE_TEXT = """Task workflow router for cowork-flow
 Usage:
   ./.cowork-flow/run task next [dir] [--json] [--intent I]
   ./.cowork-flow/run task next [dir] --validate
-  ./.cowork-flow/run task next --list [--mine] [--status S]
+  ./.cowork-flow/run task next --list [--json] [--mine] [--status S]
   ./.cowork-flow/run task next [dir] --run [--intent I]
 
 Public contract:

package/template/.cowork-flow/scripts/adapters/cli/task_tree_commands.py

@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import json
 import sys
 
 from services.task_tree import TaskTreeError, TaskTreeService
@@ -140,6 +141,73 @@ def cmd_list(args) -> int:
     return 0
 
 
+def _list_task_records(repo_root, *, mine: bool, status: str | None):
+    active_task = get_active_task(repo_root).task_path
+    developer = get_developer(repo_root)
+    if mine and not developer:
+        return None, "No developer set. Run init_developer.py first"
+
+    service = TaskTreeService(repo_root)
+    all_tasks = service.active_nodes()
+    records: list[dict[str, object]] = []
+
+    def append_task(dir_name: str, depth: int = 0) -> None:
+        info = all_tasks[dir_name]
+        if mine and info.assignee != developer:
+            return
+        if status and info.status != status:
+            return
+        relative_path = f"{DIR_WORKFLOW}/{DIR_TASKS}/{dir_name}"
+        done, total = service.children_progress(info.children, all_tasks)
+        records.append(
+            {
+                "name": dir_name,
+                "path": relative_path,
+                "status": info.status,
+                "assignee": info.assignee,
+                "parent": info.parent,
+                "children": list(info.children),
+                "childrenDone": done,
+                "childrenTotal": total,
+                "depth": depth,
+                "active": relative_path == active_task,
+            }
+        )
+        for child_name in info.children:
+            if child_name in all_tasks:
+                append_task(child_name, depth + 1)
+
+    for dir_name in service.root_names(all_tasks):
+        append_task(dir_name)
+    return records, None
+
+
+def cmd_list_json(args) -> int:
+    repo_root = get_repo_root()
+    records, error = _list_task_records(
+        repo_root,
+        mine=bool(getattr(args, "mine", False)),
+        status=getattr(args, "status", None),
+    )
+    if error:
+        print(colored(f"Error: {error}", Colors.RED), file=sys.stderr)
+        return 1
+    print(
+        json.dumps(
+            {
+                "tasks": records or [],
+                "count": len(records or []),
+                "filters": {
+                    "mine": bool(getattr(args, "mine", False)),
+                    "status": getattr(args, "status", None),
+                },
+            },
+            ensure_ascii=False,
+        )
+    )
+    return 0
+
+
 def cmd_list_archive(args) -> int:
     repo_root = get_repo_root()
     month = args.month

package/template/.cowork-flow/scripts/infra/skill_manifest.py

@@ -27,6 +27,7 @@ class SkillAction:
     lifecycle_check: str | None
     mutates_state: bool
     command: str | None
+    diagnostics_command: str | None
 
 
 @dataclass(frozen=True)
@@ -142,7 +143,14 @@ def _parse_manifest(path: Path, raw: dict[str, Any]) -> SkillManifest:
         _reject_unknown_fields(
             item,
             allowed=frozenset(
-                {"id", "label", "lifecycleCheck", "mutatesState", "command"}
+                {
+                    "id",
+                    "label",
+                    "lifecycleCheck",
+                    "mutatesState",
+                    "command",
+                    "diagnosticsCommand",
+                }
             ),
             scope="manifest action",
             path=path,
@@ -162,6 +170,9 @@ def _parse_manifest(path: Path, raw: dict[str, Any]) -> SkillManifest:
         command = item.get("command")
         if command is not None and not isinstance(command, str):
             raise SkillManifestError(f"manifest command is invalid: {path}")
+        diagnostics_command = item.get("diagnosticsCommand")
+        if diagnostics_command is not None and not isinstance(diagnostics_command, str):
+            raise SkillManifestError(f"manifest diagnosticsCommand is invalid: {path}")
         actions.append(
             SkillAction(
                 skill=skill,
@@ -170,6 +181,11 @@ def _parse_manifest(path: Path, raw: dict[str, Any]) -> SkillManifest:
                 lifecycle_check=lifecycle_check.strip() if isinstance(lifecycle_check, str) else None,
                 mutates_state=mutates_state,
                 command=command.strip() if isinstance(command, str) else None,
+                diagnostics_command=(
+                    diagnostics_command.strip()
+                    if isinstance(diagnostics_command, str)
+                    else None
+                ),
             )
         )
 
@@ -333,7 +349,14 @@ def load_skill_manifests(repo_root: Path) -> tuple[SkillManifest, ...]:
 def _manifest_signature(manifest: SkillManifest) -> tuple[object, ...]:
     return (
         tuple(
-            (item.action_id, item.label, item.lifecycle_check, item.mutates_state, item.command)
+            (
+                item.action_id,
+                item.label,
+                item.lifecycle_check,
+                item.mutates_state,
+                item.command,
+                item.diagnostics_command,
+            )
             for item in manifest.actions
         ),
         tuple(

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

@@ -47,6 +47,12 @@ def _action_command(action_id: str, task_path: str | None, template: str | None)
     return None
 
 
+def _diagnostics_command(task_path: str | None, template: str | None) -> str | None:
+    if template:
+        return template.replace("<task-dir>", task_path or "<task-dir>")
+    return None
+
+
 def _action_contract(
     *,
     status: str,
@@ -90,6 +96,10 @@ def _action_contract(
         "label": owner.label if owner is not None else action_id,
         "activatedSkill": owner.skill if owner is not None else None,
         "command": _action_command(action_id, task_path, owner.command if owner else None),
+        "diagnosticsCommand": _diagnostics_command(
+            task_path,
+            owner.diagnostics_command if owner else None,
+        ),
         "mutatesState": action["mutatesState"],
         "lifecycleCheck": lifecycle_check,
         "runtimeGate": lifecycle_check,
@@ -141,6 +151,7 @@ def route_request(
         "nextAction": action["id"],
         "activatedSkill": action["activatedSkill"],
         "actionCommand": action["command"],
+        "diagnosticsCommand": action["diagnosticsCommand"],
         "mutatesState": action["mutatesState"],
         "lifecycleCheck": action["lifecycleCheck"],
         "runtimeGate": action["runtimeGate"],

package/template/.cowork-flow/spec/contracts/skill-owned-actions.md

@@ -7,7 +7,7 @@ not contain Skill ids, prompt wording, CLI commands, or script paths.
 Each Skill may declare its own `manifest.json` with:
 
 - `actions`: action id, display label, lifecycle check, mutation fact, and an
-  optional command description;
+  optional command description plus optional `diagnosticsCommand`;
 - `context`: implement/check/debug activation rules by dev type or path;
 - `commands`: Skill-owned runtime entrypoints.
 
@@ -28,7 +28,9 @@ resume and result recording are also Skill commands rather than task CLI
 handlers.
 
 Review-oriented Skill commands may provide advisory facts, such as changed-file
-coverage, applicable spec sources, and test-intent signals. They must remain
+coverage, applicable spec sources, and test-intent signals. An action-level
+`diagnosticsCommand` may expose these helpers in text and JSON navigation, but
+it does not make the helper runnable as a lifecycle action. They must remain
 read-only helpers: no task-local review evidence file, lifecycle state mutation,
 natural-language spec hard gate, or pass/fail completion verdict.
 
@@ -41,6 +43,13 @@ Skill-id priority tables.
 
 Runtime Health has two scopes. An installed project validates its installed
 runtime, detected host platforms, and installed Skill manifests without
-requiring a `template/` directory. A cowork-flow source checkout additionally
-validates complete template host assets and template-to-live runtime and Skill
-replica parity, including every detected Skill target.
+requiring a `template/` directory. A cowork-flow source checkout distinguishes
+tracked source checkout bootstrap files, ignored local live runtime, and the
+template distribution source. Source checkout health must not force-track the whole `.cowork-flow/` tree: tracked bootstrap files must match the template,
+ignored local live runtime is compared only when present, and Skill replica
+parity is checked for every detected installed Skill target.
+
+Runtime Health also reports stale task hygiene read-only. It may warn about
+completed-unarchived tasks, active-unbound tasks, and missing task context, and
+it may include command hints. These warnings must not mutate task lifecycle
+state, write evidence files, or become completion gates.

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

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

package/template/skills/adversarial-review/SKILL.md

@@ -9,6 +9,9 @@ Use this Skill to stress-test a decision while course correction is still cheap.
 It is advisory and independent from lifecycle start, completion, and archive
 gates.
 
+Prefer precise context over broad narrative: pass only the smallest artifact,
+the contract it must satisfy, and the decision claim under review.
+
 ## Apply When
 
 - The user explicitly asks for doubt review or an adversarial pass.
@@ -30,6 +33,20 @@ gates.
 4. **RECONCILE**: fix actionable findings, accept explicit trade-offs, and discard noise.
 5. **STOP**: stop after trivial findings, three cycles, or user direction.
 
+## Severity
+
+Use severity to keep doubt actionable instead of theatrical.
+
+- `critical`: invalidates correctness, safety, lifecycle boundaries, data integrity, or completion readiness.
+- `important`: likely bug, missing meaningful verification, spec drift, or maintainability risk that should be fixed before completion.
+- `minor`: clarity, naming, or polish that should be noted but does not block progress.
+
+## Verification Discipline
+
+- Use verification-before-completion: do not accept behavioral correctness until current source or command output supports it.
+- Use anti-rationalization: challenge convenient explanations for missing edge cases, tests, or scope checks.
+- State what evidence would change the conclusion; do not turn advisory doubt into a hidden gate.
+
 Pass only ARTIFACT + CONTRACT to the reviewer so the claim does not bias the
 review. Keep the result in the task discussion or review output. No task-local
 evidence file or self-declared acceptance record is required for readiness.

package/template/skills/runtime-health/SKILL.md

@@ -16,12 +16,17 @@ Run diagnostics through the common runner:
 .cowork-flow/run doctor --all
 .cowork-flow/run doctor --host-adapters
 .cowork-flow/run doctor --subagent-safety
+.cowork-flow/run doctor --task-hygiene
+.cowork-flow/run doctor --task-hygiene --json
 ```
 
 ## Boundaries
 
 - Diagnostics may inspect runtime contracts, host assets, hooks, and template files.
 - Installed projects validate only detected host platforms and do not require a source `template/` tree.
-- Source checkouts also validate template-to-live runtime and Skill replica parity.
+- Source checkouts distinguish tracked source checkout bootstrap files, ignored local live runtime, and the template distribution source.
+- Source checkout health must not force-track the whole `.cowork-flow/` tree; ignored local live runtime files are checked only when present.
+- Source checkouts also validate Skill replica parity for detected installed host targets.
+- stale task hygiene reports completed-unarchived tasks, active-unbound tasks, and missing task context with command hints only.
 - Diagnostics must not mutate task lifecycle state.
 - Do not add lifecycle routing rules here; `task next` remains the workflow router.

package/template/skills/runtime-health/scripts/doctor.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import argparse
+import json
 import sys
 from pathlib import Path
 
@@ -30,15 +31,33 @@ from infra.paths import get_repo_root
 from infra.skill_manifest import SkillManifestError, action_owners, load_skill_manifests
 
 
-def _same_file(left: Path, right: Path, errors: list[str]) -> None:
+SOURCE_CHECKOUT_BOOTSTRAP_FILES = (
+    Path(".cowork-flow/scripts/adapters/cli/task_navigation.py"),
+    Path(".cowork-flow/scripts/adapters/cli/task_parser.py"),
+)
+
+
+def _compare_file(
+    left: Path,
+    right: Path,
+    errors: list[str],
+    *,
+    missing_left: str = "missing template asset",
+    missing_right: str = "missing installed asset",
+    drift: str = "distribution drift",
+) -> None:
     if not left.is_file():
-        errors.append(f"missing template asset: {left}")
+        errors.append(f"{missing_left}: {left}")
         return
     if not right.is_file():
-        errors.append(f"missing installed asset: {right}")
+        errors.append(f"{missing_right}: {right}")
         return
     if left.read_bytes() != right.read_bytes():
-        errors.append(f"distribution drift: {left} != {right}")
+        errors.append(f"{drift}: {left} != {right}")
+
+
+def _same_file(left: Path, right: Path, errors: list[str]) -> None:
+    _compare_file(left, right, errors)
 
 
 def _distribution_root(repo_root: Path) -> Path:
@@ -82,19 +101,42 @@ def check_distribution(repo_root: Path) -> list[str]:
     if _distribution_root(repo_root) == repo_root:
         return errors
     runtime_root = template / ".cowork-flow" / "scripts"
+    bootstrap = set(SOURCE_CHECKOUT_BOOTSTRAP_FILES)
+    for relative in SOURCE_CHECKOUT_BOOTSTRAP_FILES:
+        _compare_file(
+            template / relative,
+            repo_root / relative,
+            errors,
+            missing_left="missing template bootstrap asset",
+            missing_right="missing source bootstrap asset",
+            drift="source bootstrap drift",
+        )
     for source in _distribution_files(runtime_root):
         relative = source.relative_to(template)
-        _same_file(source, repo_root / relative, errors)
+        if relative in bootstrap:
+            continue
+        target = repo_root / relative
+        if target.is_file():
+            _compare_file(
+                source,
+                target,
+                errors,
+                drift="local live runtime drift",
+            )
     for relative in (Path(".cowork-flow/run"), Path(".cowork-flow/run.cmd")):
         source = template / relative
-        if source.is_file():
-            _same_file(source, repo_root / relative, errors)
+        target = repo_root / relative
+        if source.is_file() and target.is_file():
+            _compare_file(source, target, errors, drift="local live runtime drift")
     try:
         host_manifest = load_host_manifest(template)
-        installed_platforms = detect_installed_platforms(repo_root)
     except HostManifestError as error:
         errors.append(str(error))
         return errors
+    try:
+        installed_platforms = detect_installed_platforms(repo_root)
+    except HostManifestError:
+        installed_platforms = ()
     skill_targets = {
         host_manifest.platform(platform_id).skill_target
         for platform_id in installed_platforms
@@ -108,6 +150,113 @@ def check_distribution(repo_root: Path) -> list[str]:
     return errors
 
 
+def _task_path(repo_root: Path, task_dir: Path) -> str:
+    try:
+        return task_dir.resolve().relative_to(repo_root.resolve()).as_posix()
+    except ValueError:
+        return str(task_dir)
+
+
+def _task_metadata(path: Path) -> dict[str, object]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _session_task_paths(repo_root: Path) -> set[str]:
+    sessions = repo_root / ".cowork-flow" / ".runtime" / "sessions"
+    active: set[str] = set()
+    if not sessions.is_dir():
+        return active
+    for path in sorted(sessions.glob("*.json")):
+        data = _task_metadata(path)
+        task_path = data.get("active_task_path")
+        if isinstance(task_path, str) and task_path.strip():
+            active.add(task_path.replace("\\", "/"))
+    return active
+
+
+def _task_hygiene_issue(
+    *,
+    kind: str,
+    task: str,
+    status: str,
+    message: str,
+    hint: str,
+) -> dict[str, str]:
+    return {
+        "kind": kind,
+        "task": task,
+        "status": status,
+        "message": message,
+        "hint": hint,
+    }
+
+
+def _missing_context_files(task_dir: Path) -> tuple[str, ...]:
+    required = ("decision-anchor.md", "implement.jsonl", "check.jsonl", "debug.jsonl")
+    return tuple(name for name in required if not (task_dir / name).is_file())
+
+
+def check_task_hygiene(repo_root: Path) -> list[dict[str, str]]:
+    tasks_dir = repo_root / ".cowork-flow" / "tasks"
+    if not tasks_dir.is_dir():
+        return []
+    bound_tasks = _session_task_paths(repo_root)
+    issues: list[dict[str, str]] = []
+    for task_dir in sorted(tasks_dir.iterdir()):
+        if not task_dir.is_dir() or task_dir.name == "archive":
+            continue
+        task = _task_path(repo_root, task_dir)
+        data = _task_metadata(task_dir / "task.json")
+        status = str(data.get("status") or "unknown")
+        if status == "completed":
+            issues.append(
+                _task_hygiene_issue(
+                    kind="completed_unarchived",
+                    task=task,
+                    status=status,
+                    message="completed task remains in the active task tree",
+                    hint=f"./.cowork-flow/run task next {task} --run --intent archive",
+                )
+            )
+        if status in {"in_progress", "review"} and task not in bound_tasks:
+            issues.append(
+                _task_hygiene_issue(
+                    kind="in_progress_unbound",
+                    task=task,
+                    status=status,
+                    message="active task state is not bound to any runtime session",
+                    hint=f"./.cowork-flow/run task next {task} --run",
+                )
+            )
+        missing = _missing_context_files(task_dir)
+        if missing:
+            issues.append(
+                _task_hygiene_issue(
+                    kind="missing_task_context",
+                    task=task,
+                    status=status,
+                    message=f"missing task context file(s): {', '.join(missing)}",
+                    hint=f"./.cowork-flow/run task next {task} --validate",
+                )
+            )
+    return issues
+
+
+def _print_task_hygiene_issues(issues: list[dict[str, str]]) -> None:
+    for issue in issues:
+        print(
+            "WARNING: "
+            f"{issue['kind']}: {issue['task']} ({issue['status']}): "
+            f"{issue['message']}",
+            file=sys.stderr,
+        )
+        print(f"Hint: {issue['hint']}", file=sys.stderr)
+
+
 def check_runtime(repo_root: Path) -> list[str]:
     errors: list[str] = []
     try:
@@ -142,6 +291,7 @@ def _run_checks(repo_root: Path) -> int:
     errors.extend(_host_errors(repo_root))
     errors.extend(check_runtime(repo_root))
     errors.extend(check_distribution(repo_root))
+    _print_task_hygiene_issues(check_task_hygiene(repo_root))
     if errors:
         for error in errors:
             print(f"ERROR: {error}", file=sys.stderr)
@@ -170,11 +320,25 @@ def _run_runtime_checks(repo_root: Path) -> int:
     return 0
 
 
+def _run_task_hygiene_checks(repo_root: Path, *, structured: bool = False) -> int:
+    issues = check_task_hygiene(repo_root)
+    if structured:
+        print(json.dumps({"issues": issues}, ensure_ascii=False))
+        return 0
+    if issues:
+        _print_task_hygiene_issues(issues)
+    else:
+        print("task hygiene checks passed")
+    return 0
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="cowork-flow diagnostics")
     parser.add_argument("--all", action="store_true", help="Run all structured health checks")
     parser.add_argument("--subagent-safety", action="store_true", help="Run runtime safety checks")
     parser.add_argument("--host-adapters", action="store_true", help="Run host asset checks")
+    parser.add_argument("--task-hygiene", action="store_true", help="Report stale task hygiene issues")
+    parser.add_argument("--json", action="store_true", help="Render machine-readable diagnostics where supported")
     return parser
 
 
@@ -187,6 +351,8 @@ def main() -> int:
         return _run_host_checks(repo_root)
     if args.subagent_safety:
         return _run_runtime_checks(repo_root)
+    if args.task_hygiene:
+        return _run_task_hygiene_checks(repo_root, structured=bool(args.json))
     build_parser().print_help()
     return 0
 

package/template/skills/task-review/SKILL.md

@@ -16,6 +16,9 @@ Use this Skill during the check phase, before the `task next --run` completion a
 - Prefer fresh verification from the current checkout over stale prior output.
 - Do not create task-local review artifact files. The review result and command output are the evidence.
 - Use advisory helper output only as review input; it must not become a second lifecycle gate.
+- Use anti-self-proof discipline: do not accept the agent's own summary, checklist, or intended test coverage as proof without exact diff, command output, or source evidence.
+- Use anti-rationalization discipline: treat convenient explanations for missing tests, missing specs, or unchecked lifecycle blockers as findings until verified.
+- Keep verification-before-completion explicit: completion requires current commands from this checkout, not stale logs or advisory helper confidence.
 
 ## Inputs
 
@@ -39,6 +42,8 @@ Read only what is needed for the current task:
 - **Code quality**: naming, layering, error handling, state boundaries, security-sensitive paths, and complexity are reviewed against applicable user specs.
 - **Lifecycle blockers**: state/scope blockers are fixed before acceptance; review does not invent hard blockers for natural-language specs.
 - **Advisory facts**: helper output is used to focus review, not to declare pass/fail or block completion.
+- **Anti-self-proof**: every claimed pass maps to source, diff, test output, or lifecycle output.
+- **Anti-rationalization**: every accepted gap has an explicit user decision or narrow technical reason.
 
 ## Severity
 

package/template/skills/task-review/manifest.json

@@ -7,14 +7,16 @@
       "label": "mark task ready for review",
       "lifecycleCheck": "task_review",
       "mutatesState": true,
-      "command": "./.cowork-flow/run task next <task-dir> --run --intent review"
+      "command": "./.cowork-flow/run task next <task-dir> --run --intent review",
+      "diagnosticsCommand": "./.cowork-flow/run review-check <task-dir> --json"
     },
     {
       "id": "complete_task",
       "label": "complete reviewed task",
       "lifecycleCheck": "task_complete",
       "mutatesState": true,
-      "command": "./.cowork-flow/run task next <task-dir> --run --intent review"
+      "command": "./.cowork-flow/run task next <task-dir> --run --intent review",
+      "diagnosticsCommand": "./.cowork-flow/run review-check <task-dir> --json"
     }
   ],
   "context": [