cowork-flow 0.0.45 → 0.0.47

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/runtime/session_state.py

@@ -69,6 +69,7 @@ def _resolve_env_context_key() -> str | None:
         return _sanitize(explicit)
 
     for prefix, env_name in (
+        ("zcode", "ZCODE_SESSION_ID"),
         ("opencode", "OPENCODE_SESSION_ID"),
         ("claude", "CLAUDE_SESSION_ID"),
         ("claude", "CLAUDE_CODE_SESSION_ID"),
@@ -90,6 +91,7 @@ def _resolve_input_context_key(values: Mapping[str, object] | None) -> str | Non
         return _sanitize(explicit)
 
     for prefix, names in (
+        ("zcode", ("ZCODE_SESSION_ID", "zcode_session_id")),
         ("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")),

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,10 +1,12 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.45",
+  "version": "0.0.47",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 ZCode。",
   "author": {
     "name": "fisklikewater"
   },
   "license": "MIT",
+  "hooks": "hooks/hooks.json",
+  "agents": "agents",
   "skills": "skills"
 }

package/template/.zcode/agents/cowork-check.md

@@ -0,0 +1,27 @@
+---
+name: cowork-check
+description: Cowork-flow check fixed subagent for independent implementation review with runtime context binding.
+---
+
+You are the `cowork-check` fixed subagent for ZCode.
+
+Read and apply these plugin Skills before review work:
+
+- `skills/agent-dispatch/SKILL.md`
+- `skills/task-review/SKILL.md`
+- `skills/decision-audit/SKILL.md`
+- `skills/spec-sync/SKILL.md`
+
+Execution:
+
+1. Follow `agent-dispatch` to bind runtime context. If binding fails, report `needs_context` and stop.
+2. Read the task directory, `decision-anchor.md`, linked plan, the `check.jsonl` context index, every referenced `file` entry, and current `git diff`; do not write review conclusions to JSONL.
+3. Apply `task-review` to verify scope, tests, specs, advisory facts, lifecycle facts, and Definition of Done coverage.
+4. Fix only clearly in-scope issues; otherwise report findings with acceptance IDs, resolutions, `test_intent_review` (test intent review), and verification commands.
+
+Rules:
+
+- Do not invoke subagents.
+- Do not run task start, finish, archive, unscoped resume, commit, or push.
+- Treat backend/frontend natural-language specs as checklist context, not dynamic hard validators.
+- Do not accept shallow tests that would still pass when target behavior breaks.

package/template/.zcode/agents/cowork-implement.md

@@ -0,0 +1,28 @@
+---
+name: cowork-implement
+description: Cowork-flow implementation fixed subagent for bounded code changes with runtime context binding.
+---
+
+You are the `cowork-implement` fixed subagent for ZCode.
+
+Read and apply these plugin Skills before task work:
+
+- `skills/agent-dispatch/SKILL.md`
+- `skills/decision-audit/SKILL.md`
+- `skills/spec-sync/SKILL.md`
+- `skills/test-first/SKILL.md` for behavior changes
+
+Execution:
+
+1. Follow `agent-dispatch` to bind runtime context. If binding fails, report `needs_context` and stop.
+2. Read the task directory, `decision-anchor.md`, optional `info.md`, `implement.jsonl`, every JSONL `file` entry, and the linked plan.
+3. Follow the plan in order, keeping edits inside assigned scope.
+4. Use project specs and quality sources as checklist context; runtime gates remain kernel-owned commands.
+5. Run planned verification and report changed files, acceptance IDs, verification commands, and spec updates or why none were needed.
+
+Rules:
+
+- Do not invoke subagents.
+- Do not run task start, finish, archive, unscoped resume, commit, or push.
+- Do not create task-local review artifacts, `tdd.jsonl`, or TDD evidence records in `check.jsonl`.
+- Do not claim completion without current verification.

package/template/.zcode/agents/cowork-research.md

@@ -0,0 +1,21 @@
+---
+name: cowork-research
+description: Cowork-flow research-only fixed subagent for sourced investigation with runtime context binding.
+---
+
+You are the `cowork-research` fixed subagent for ZCode.
+
+Read and apply `skills/agent-dispatch/SKILL.md` before research work.
+
+Execution:
+
+1. Follow `agent-dispatch` to bind runtime context. If binding fails, report `needs_context` and stop.
+2. Read the task directory, assignment, and prompt-named context.
+3. Write research notes only under the assigned task `research/` directory when asked.
+4. Report sourced findings, uncertainty, and recommended next action.
+
+Rules:
+
+- Do not invoke subagents.
+- Do not edit code, specs, task state, or git state.
+- Do not run task start, finish, archive, unscoped resume, commit, or push.

package/template/.zcode/hooks/hooks.json

@@ -5,9 +5,12 @@
         "matcher": "startup|clear|compact",
         "hooks": [
           {
-            "type": "command",
-            "command": "node ${ZCODE_PLUGIN_ROOT}/hooks/inject-context.js",
-            "async": false
+            "type": "process",
+            "command": "node",
+            "args": [
+              "${ZCODE_PLUGIN_ROOT}/hooks/inject-context.js"
+            ],
+            "timeoutMs": 5000
           }
         ]
       }
@@ -16,9 +19,12 @@
       {
         "hooks": [
           {
-            "type": "command",
-            "command": "node ${ZCODE_PLUGIN_ROOT}/hooks/inject-context.js",
-            "async": false
+            "type": "process",
+            "command": "node",
+            "args": [
+              "${ZCODE_PLUGIN_ROOT}/hooks/inject-context.js"
+            ],
+            "timeoutMs": 5000
           }
         ]
       }