cowork-flow 0.0.34 → 0.0.35

package/package.json

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

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.34
+0.0.35

package/template/.cowork-flow/scripts/__init__.py

@@ -0,0 +1 @@
+"""Cowork Flow runtime scripts."""

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

@@ -39,6 +39,7 @@ else:
     import _bootstrap  # noqa: F401
 from common.core.files import (
     read_json_file as _read_json_file,
+    read_text_utf8 as _read_text,
     write_json_file as _write_json_file,
 )
 from common.gates.gates import GateResult, GateRunner
@@ -466,17 +467,6 @@ def _write_jsonl(path: Path, entries: list[dict]) -> None:
     path.write_text("\n".join(lines) + "\n", encoding="utf-8")
 
 
-def _read_text_if_present(path: Path) -> str:
-    """读取文本文件并返回去空白后的内容；不存在或读取失败时返回空字符串。"""
-    if not path.is_file():
-        return ""
-
-    try:
-        return path.read_text(encoding="utf-8").strip()
-    except (OSError, IOError):
-        return ""
-
-
 def _task_start_blockers(task_dir: Path) -> list[str]:
     """返回启动任务前必须处理的准备阻塞项。"""
     blockers: list[str] = []
@@ -486,16 +476,16 @@ def _task_start_blockers(task_dir: Path) -> list[str]:
         blockers.append("task.json is missing")
 
     # 只检查存在性 — R-WF-008 负责章节内容完整性
-    if _read_text_if_present(task_dir / "prd.md"):
+    if _read_text(task_dir / "prd.md"):
         # 旧格式：提示需要迁移（cmd_start 会自动迁移）
-        if not _read_text_if_present(task_dir / "decision-anchor.md"):
+        if not _read_text(task_dir / "decision-anchor.md"):
             blockers.append("prd.md found; task start will auto-migrate to decision-anchor.md")
-    elif not _read_text_if_present(task_dir / "decision-anchor.md"):
+    elif not _read_text(task_dir / "decision-anchor.md"):
         blockers.append("decision-anchor.md is missing or empty")
 
     for jsonl_name in CONTEXT_JSONL_FILES:
         jsonl_file = task_dir / jsonl_name
-        if not _read_text_if_present(jsonl_file):
+        if not _read_text(jsonl_file):
             blockers.append(f"{jsonl_name} is missing or empty")
 
     return blockers
@@ -516,7 +506,7 @@ def _task_context_validation_issues(
 
     for jsonl_name in CONTEXT_JSONL_FILES:
         jsonl_file = task_dir / jsonl_name
-        if not _read_text_if_present(jsonl_file):
+        if not _read_text(jsonl_file):
             continue
 
         error_count = _validate_jsonl(jsonl_file, repo_root, quiet=quiet)

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

@@ -1,5 +1,14 @@
 #!/usr/bin/env python3
-"""TDD evidence validation for task review gates."""
+"""
+TDD 红绿证据校验（task_review / task_complete 阶段）。
+
+读取 <task>/tdd.jsonl，验证每条 evidence 或 exemption 记录的结构完整
+性与业务意图。验证结果分两类出口：
+- validate_tdd_evidence: 全量校验（review 阶段）
+- validate_tdd_red_evidence: 仅检查 red 证据完整性（implement 入口提醒）
+
+acceptanceId 的提取同时支持 AC-001、AC-1、验收标准：1 三种写法。
+"""
 
 from __future__ import annotations
 

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

@@ -1,8 +1,13 @@
 #!/usr/bin/env python3
 """
-Implementation validation script.
+R-AG-002 到 R-AG-009 的门禁检查器。
 
-Validates code changes against forbidden action rules after task implementation.
+在 task_review 阶段运行：通过 git diff 获取工作树的未提交改动，逐项
+检查 forbidden_action 规则。每项规则以 (repo_root, modified_files, diff_output,
+rule_index) 为入参，返回 violation dict 列表。
+
+结果汇总到 GateResult：存在 severity=block 的 violation 时阻断 review 流程，
+warn 级别仅输出警告。
 """
 
 from __future__ import annotations

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

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

package/template/.zcode/hooks/runtime/scripts/__init__.py

@@ -0,0 +1 @@
+"""Cowork Flow zcode plugin runtime scripts."""

package/template/.zcode/hooks/runtime/scripts/commands/task.py

@@ -39,6 +39,7 @@ else:
     import _bootstrap  # noqa: F401
 from common.core.files import (
     read_json_file as _read_json_file,
+    read_text_utf8 as _read_text,
     write_json_file as _write_json_file,
 )
 from common.gates.gates import GateResult, GateRunner
@@ -466,17 +467,6 @@ def _write_jsonl(path: Path, entries: list[dict]) -> None:
     path.write_text("\n".join(lines) + "\n", encoding="utf-8")
 
 
-def _read_text_if_present(path: Path) -> str:
-    """读取文本文件并返回去空白后的内容；不存在或读取失败时返回空字符串。"""
-    if not path.is_file():
-        return ""
-
-    try:
-        return path.read_text(encoding="utf-8").strip()
-    except (OSError, IOError):
-        return ""
-
-
 def _task_start_blockers(task_dir: Path) -> list[str]:
     """返回启动任务前必须处理的准备阻塞项。"""
     blockers: list[str] = []
@@ -486,16 +476,16 @@ def _task_start_blockers(task_dir: Path) -> list[str]:
         blockers.append("task.json is missing")
 
     # 只检查存在性 — R-WF-008 负责章节内容完整性
-    if _read_text_if_present(task_dir / "prd.md"):
+    if _read_text(task_dir / "prd.md"):
         # 旧格式：提示需要迁移（cmd_start 会自动迁移）
-        if not _read_text_if_present(task_dir / "decision-anchor.md"):
+        if not _read_text(task_dir / "decision-anchor.md"):
             blockers.append("prd.md found; task start will auto-migrate to decision-anchor.md")
-    elif not _read_text_if_present(task_dir / "decision-anchor.md"):
+    elif not _read_text(task_dir / "decision-anchor.md"):
         blockers.append("decision-anchor.md is missing or empty")
 
     for jsonl_name in CONTEXT_JSONL_FILES:
         jsonl_file = task_dir / jsonl_name
-        if not _read_text_if_present(jsonl_file):
+        if not _read_text(jsonl_file):
             blockers.append(f"{jsonl_name} is missing or empty")
 
     return blockers
@@ -516,7 +506,7 @@ def _task_context_validation_issues(
 
     for jsonl_name in CONTEXT_JSONL_FILES:
         jsonl_file = task_dir / jsonl_name
-        if not _read_text_if_present(jsonl_file):
+        if not _read_text(jsonl_file):
             continue
 
         error_count = _validate_jsonl(jsonl_file, repo_root, quiet=quiet)
@@ -1520,7 +1510,7 @@ def cmd_next(args: argparse.Namespace) -> int:
         return 0
 
     if status in DONE_STATUSES:
-        print("Next action: finalize, commit, archive, and record session")
+        print("Next action: finalize, archive, commit, and record session")
         print("Command: git status --short")
         linked_changes = _linked_active_changes_for_task(repo_root, task_dir)
         print(f"Then: ./.cowork-flow/run task archive {Path(task_path).name}")

package/template/.zcode/hooks/runtime/scripts/common/gates/tdd_evidence.py

@@ -1,5 +1,14 @@
 #!/usr/bin/env python3
-"""TDD evidence validation for task review gates."""
+"""
+TDD 红绿证据校验（task_review / task_complete 阶段）。
+
+读取 <task>/tdd.jsonl，验证每条 evidence 或 exemption 记录的结构完整
+性与业务意图。验证结果分两类出口：
+- validate_tdd_evidence: 全量校验（review 阶段）
+- validate_tdd_red_evidence: 仅检查 red 证据完整性（implement 入口提醒）
+
+acceptanceId 的提取同时支持 AC-001、AC-1、验收标准：1 三种写法。
+"""
 
 from __future__ import annotations
 

package/template/.zcode/hooks/runtime/scripts/common/gates/validate_implementation.py

@@ -1,8 +1,13 @@
 #!/usr/bin/env python3
 """
-Implementation validation script.
+R-AG-002 到 R-AG-009 的门禁检查器。
 
-Validates code changes against forbidden action rules after task implementation.
+在 task_review 阶段运行：通过 git diff 获取工作树的未提交改动，逐项
+检查 forbidden_action 规则。每项规则以 (repo_root, modified_files, diff_output,
+rule_index) 为入参，返回 violation dict 列表。
+
+结果汇总到 GateResult：存在 severity=block 的 violation 时阻断 review 流程，
+warn 级别仅输出警告。
 """
 
 from __future__ import annotations

package/template/.zcode/hooks/runtime/scripts/common/task/readiness.py

@@ -246,4 +246,22 @@ def task_readiness_blockers(repo_root: Path, task_dir: Path) -> list[str]:
         if not _has_verification_command(plan_text):
             blockers.append(f"L2 readiness ({slug}): linked plan is missing verification commands")
 
+        blockers.extend(_check_doubt_review(task_dir, change_dir))
+
     return blockers
+
+
+def _check_doubt_review(task_dir: Path, change_dir: Path) -> list[str]:
+    """L2 optional check: doubt-review 记录是否存在 (warn 级别, 不阻断)."""
+    doubt_file = Path(task_dir) / "doubt-review.md"
+    if not doubt_file.is_file():
+        return [
+            f"L2 doubt-review 建议: 在 {doubt_file} 中记录关键决策的 "
+            f"CLAIM+CONTRACT（非强制，但强烈推荐）"
+        ]
+    text = _read_text(doubt_file)
+    if "CLAIM:" not in text:
+        return [
+            f"L2 doubt-review: {doubt_file} 存在但没有 CLAIM 记录"
+        ]
+    return []

package/template/.zcode/scaffold/.cowork-flow/run

@@ -0,0 +1,79 @@
+#!/bin/sh
+set -u
+
+MIN_PYTHON_LABEL="Python 3.9+"
+VERSION_CHECK='import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)'
+WORKFLOW_DIR=$(CDPATH= cd "$(dirname "$0")" && pwd) || exit 1
+RUNNER_SCRIPT="$WORKFLOW_DIR/scripts/run.py"
+
+candidate_is_valid() {
+  candidate_cmd=$1
+  candidate_arg=${2:-}
+
+  command -v "$candidate_cmd" >/dev/null 2>&1 || return 1
+
+  if [ -n "$candidate_arg" ]; then
+    "$candidate_cmd" "$candidate_arg" -c "$VERSION_CHECK" >/dev/null 2>&1
+  else
+    "$candidate_cmd" -c "$VERSION_CHECK" >/dev/null 2>&1
+  fi
+}
+
+select_explicit_python() {
+  env_name=$1
+  env_value=$2
+
+  if candidate_is_valid "$env_value"; then
+    SELECTED_PYTHON=$env_value
+    SELECTED_PYTHON_ARG=
+    return 0
+  fi
+
+  echo "Error: $env_name does not point to a usable ${MIN_PYTHON_LABEL} interpreter: $env_value" >&2
+  echo "Set $env_name to an executable ${MIN_PYTHON_LABEL} interpreter path." >&2
+  exit 127
+}
+
+select_python() {
+  SELECTED_PYTHON=
+  SELECTED_PYTHON_ARG=
+
+  if [ -n "${COWORK_FLOW_PYTHON:-}" ]; then
+    select_explicit_python "COWORK_FLOW_PYTHON" "$COWORK_FLOW_PYTHON"
+    return 0
+  fi
+
+  if [ -n "${PYTHON:-}" ]; then
+    select_explicit_python "PYTHON" "$PYTHON"
+    return 0
+  fi
+
+  if candidate_is_valid "python3"; then
+    SELECTED_PYTHON=python3
+    return 0
+  fi
+
+  if candidate_is_valid "python"; then
+    SELECTED_PYTHON=python
+    return 0
+  fi
+
+  if candidate_is_valid "py" "-3"; then
+    SELECTED_PYTHON=py
+    SELECTED_PYTHON_ARG=-3
+    return 0
+  fi
+
+  echo "Error: ${MIN_PYTHON_LABEL} is required, but no usable interpreter was found." >&2
+  echo "Tried: COWORK_FLOW_PYTHON, PYTHON, python3, python, py -3." >&2
+  echo "Set COWORK_FLOW_PYTHON=/path/to/python3 and retry." >&2
+  exit 127
+}
+
+select_python
+
+if [ -n "$SELECTED_PYTHON_ARG" ]; then
+  exec "$SELECTED_PYTHON" "$SELECTED_PYTHON_ARG" "$RUNNER_SCRIPT" "$@"
+fi
+
+exec "$SELECTED_PYTHON" "$RUNNER_SCRIPT" "$@"

package/template/.zcode/scaffold/.cowork-flow/run.cmd

@@ -0,0 +1,88 @@
+@echo off
+setlocal EnableExtensions
+
+set "MIN_PYTHON_LABEL=Python 3.9+"
+set "VERSION_CHECK=import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)"
+set "WORKFLOW_DIR=%~dp0"
+set "RUNNER_SCRIPT=%WORKFLOW_DIR%scripts\run.py"
+set "SELECTED_PYTHON="
+set "SELECTED_PYTHON_ARG="
+
+call :select_python
+if errorlevel 1 exit /b %ERRORLEVEL%
+
+if not "%SELECTED_PYTHON_ARG%"=="" (
+  "%SELECTED_PYTHON%" "%SELECTED_PYTHON_ARG%" "%RUNNER_SCRIPT%" %*
+) else (
+  "%SELECTED_PYTHON%" "%RUNNER_SCRIPT%" %*
+)
+exit /b %ERRORLEVEL%
+
+:candidate_is_valid
+set "CANDIDATE_CMD=%~1"
+set "CANDIDATE_ARG=%~2"
+
+where "%CANDIDATE_CMD%" >nul 2>nul
+if errorlevel 1 (
+  if not exist "%CANDIDATE_CMD%" exit /b 1
+)
+
+if not "%CANDIDATE_ARG%"=="" (
+  "%CANDIDATE_CMD%" "%CANDIDATE_ARG%" -c "%VERSION_CHECK%" >nul 2>nul
+) else (
+  "%CANDIDATE_CMD%" -c "%VERSION_CHECK%" >nul 2>nul
+)
+exit /b %ERRORLEVEL%
+
+:select_explicit_python
+set "ENV_NAME=%~1"
+set "ENV_VALUE=%~2"
+
+call :candidate_is_valid "%ENV_VALUE%" ""
+if not errorlevel 1 (
+  set "SELECTED_PYTHON=%ENV_VALUE%"
+  set "SELECTED_PYTHON_ARG="
+  exit /b 0
+)
+
+echo Error: %ENV_NAME% does not point to a usable %MIN_PYTHON_LABEL% interpreter: %ENV_VALUE% 1>&2
+echo Set %ENV_NAME% to an executable Python 3.9+ interpreter path. 1>&2
+exit /b 127
+
+:select_python
+set "SELECTED_PYTHON="
+set "SELECTED_PYTHON_ARG="
+
+if not "%COWORK_FLOW_PYTHON%"=="" (
+  call :select_explicit_python "COWORK_FLOW_PYTHON" "%COWORK_FLOW_PYTHON%"
+  exit /b %ERRORLEVEL%
+)
+
+if not "%PYTHON%"=="" (
+  call :select_explicit_python "PYTHON" "%PYTHON%"
+  exit /b %ERRORLEVEL%
+)
+
+call :candidate_is_valid "python3" ""
+if not errorlevel 1 (
+  set "SELECTED_PYTHON=python3"
+  exit /b 0
+)
+
+call :candidate_is_valid "python" ""
+if not errorlevel 1 (
+  set "SELECTED_PYTHON=python"
+  exit /b 0
+)
+
+call :candidate_is_valid "py" "-3"
+if not errorlevel 1 (
+  set "SELECTED_PYTHON=py"
+  set "SELECTED_PYTHON_ARG=-3"
+  exit /b 0
+)
+
+echo Error: %MIN_PYTHON_LABEL% is required, but no usable interpreter was found. 1>&2
+echo Tried: COWORK_FLOW_PYTHON, PYTHON, python3, python, py -3. 1>&2
+echo Set COWORK_FLOW_PYTHON=C:\Path\To\python.exe and retry. 1>&2
+exit /b 127