cowork-flow 0.0.47 → 0.0.49

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

@@ -29,12 +29,30 @@ from adapters.host.host_manifest import (
 )
 from infra.paths import get_repo_root
 from infra.skill_manifest import SkillManifestError, action_owners, load_skill_manifests
+from infra.storage.operation_log import OperationLog
+from infra.storage.state_store import DEFAULT_STALE_LOCK_SECONDS, StateStore
 
 
-SOURCE_CHECKOUT_BOOTSTRAP_FILES = (
-    Path(".cowork-flow/scripts/adapters/cli/task_navigation.py"),
-    Path(".cowork-flow/scripts/adapters/cli/task_parser.py"),
-)
+def _issue(
+    *,
+    code: str,
+    severity: str,
+    path: str,
+    message: str,
+    command_hint: str = "",
+    contract: str,
+    **extra: str,
+) -> dict[str, str]:
+    issue = {
+        "code": code,
+        "severity": severity,
+        "path": path,
+        "message": message,
+        "commandHint": command_hint,
+        "contract": contract,
+    }
+    issue.update(extra)
+    return issue
 
 
 def _compare_file(
@@ -84,6 +102,40 @@ def _host_errors(repo_root: Path) -> list[str]:
     return validate_host_assets(distribution_root, platform_ids=platform_ids)
 
 
+def _host_issue(error: str) -> dict[str, str]:
+    path = ""
+    if ":" in error:
+        path = error.rsplit(":", 1)[-1].strip()
+    lowered = error.lower()
+    if "missing command target" in lowered:
+        code = "HOST-ASSET-MISSING-COMMAND-TARGET"
+    elif "missing command config" in lowered:
+        code = "HOST-ASSET-MISSING-COMMAND-CONFIG"
+    elif "invalid command config" in lowered:
+        code = "HOST-ASSET-INVALID-COMMAND-CONFIG"
+    elif "illegal capability" in lowered:
+        code = "HOST-ASSET-ILLEGAL-CAPABILITY"
+    elif "capability mismatch" in lowered:
+        code = "HOST-ASSET-CAPABILITY-MISMATCH"
+    elif "adapter host mismatch" in lowered:
+        code = "HOST-ASSET-HOST-MISMATCH"
+    elif "invalid adapter yaml" in lowered:
+        code = "HOST-ASSET-INVALID-ADAPTER"
+    else:
+        code = "HOST-ASSET-VALIDATION-ERROR"
+    return _issue(
+        code=code,
+        severity="error",
+        path=path,
+        message=error,
+        contract="runtime-health:host-adapters",
+    )
+
+
+def _host_issues(repo_root: Path) -> list[dict[str, str]]:
+    return [_host_issue(error) for error in _host_errors(repo_root)]
+
+
 def _distribution_files(root: Path) -> tuple[Path, ...]:
     files = [
         path
@@ -95,26 +147,31 @@ def _distribution_files(root: Path) -> tuple[Path, ...]:
     return tuple(sorted(files))
 
 
+def _source_checkout_protected_path(relative: Path) -> bool:
+    value = relative.as_posix()
+    if value in {".cowork-flow/config.yaml", ".cowork-flow/.developer"}:
+        return True
+    return value.startswith(".cowork-flow/tasks/") or value.startswith(
+        ".cowork-flow/plans/"
+    ) or value.startswith(".cowork-flow/.runtime/")
+
+
+def _source_checkout_live_files(template: Path) -> tuple[Path, ...]:
+    runtime_root = template / ".cowork-flow"
+    return tuple(
+        source
+        for source in _distribution_files(runtime_root)
+        if not _source_checkout_protected_path(source.relative_to(template))
+    )
+
+
 def check_distribution(repo_root: Path) -> list[str]:
     errors: list[str] = []
     template = repo_root / "template"
     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):
+    for source in _source_checkout_live_files(template):
         relative = source.relative_to(template)
-        if relative in bootstrap:
-            continue
         target = repo_root / relative
         if target.is_file():
             _compare_file(
@@ -123,11 +180,6 @@ def check_distribution(repo_root: Path) -> list[str]:
                 errors,
                 drift="local live runtime drift",
             )
-    for relative in (Path(".cowork-flow/run"), Path(".cowork-flow/run.cmd")):
-        source = template / relative
-        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)
     except HostManifestError as error:
@@ -186,13 +238,19 @@ def _task_hygiene_issue(
     message: str,
     hint: str,
 ) -> dict[str, str]:
-    return {
-        "kind": kind,
-        "task": task,
-        "status": status,
-        "message": message,
-        "hint": hint,
-    }
+    code = f"TASK-HYGIENE-{kind.replace('_', '-').upper()}"
+    return _issue(
+        code=code,
+        severity="warning",
+        path=task,
+        message=message,
+        command_hint=hint,
+        contract="runtime-health:task-hygiene",
+        kind=kind,
+        task=task,
+        status=status,
+        hint=hint,
+    )
 
 
 def _missing_context_files(task_dir: Path) -> tuple[str, ...]:
@@ -257,6 +315,151 @@ def _print_task_hygiene_issues(issues: list[dict[str, str]]) -> None:
         print(f"Hint: {issue['hint']}", file=sys.stderr)
 
 
+def _diagnostic_path(repo_root: Path, path: Path) -> str:
+    try:
+        return path.resolve().relative_to(repo_root.resolve()).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def _state_lock_code(status: str) -> str:
+    return f"STATE-RECOVERY-LOCK-{status.upper().replace('_', '-')}"
+
+
+def _state_lock_command_hint(info) -> str:
+    if info.status != "recoverable":
+        return "Inspect the lock owner facts; do not delete unless the owner PID is missing and the lock is older than the stale threshold."
+    return (
+        "Use an explicit recovery action only after verification, for example "
+        "StateStore().remove_stale_lock(Path(<target>), stale_after_seconds="
+        f"{DEFAULT_STALE_LOCK_SECONDS})"
+    )
+
+
+def _state_lock_issue(repo_root: Path, info) -> dict[str, object]:
+    fields = info.to_dict()
+    fields.update(
+        {
+            "kind": "state_lock",
+            "lockPath": _diagnostic_path(repo_root, info.lock_path),
+            "target": str(info.target),
+        }
+    )
+    if info.age_seconds is not None:
+        fields["ageSeconds"] = round(info.age_seconds, 3)
+    return _issue(
+        code=_state_lock_code(info.status),
+        severity="warning",
+        path=_diagnostic_path(repo_root, info.lock_path),
+        message=info.detail,
+        command_hint=_state_lock_command_hint(info),
+        contract="runtime-health:state-recovery",
+        **fields,
+    )
+
+
+def _operation_command_hint() -> str:
+    return (
+        "Inspect the pending operation record; a trusted recovery command may "
+        "call UnitOfWork.recover_all(repo_root) without interpreting error "
+        "output as instructions."
+    )
+
+
+def _pending_operation_issue(repo_root: Path, fact: dict) -> dict[str, object]:
+    error = fact.get("error")
+    if fact.get("phase") == "unreadable" and isinstance(error, dict):
+        return _issue(
+            code="STATE-RECOVERY-OPERATION-UNREADABLE",
+            severity="warning",
+            path=_diagnostic_path(repo_root, Path(str(fact.get("path") or ""))),
+            message=str(error.get("detail") or "operation record is unreadable"),
+            command_hint="Inspect the operation record manually; Doctor does not mutate recovery state.",
+            contract="runtime-health:state-recovery",
+            kind="pending_operation",
+            operationId=str(fact.get("operation_id") or ""),
+            phase=str(fact.get("phase") or "unreadable"),
+            errorCode=str(error.get("code") or ""),
+        )
+    operation_id = str(fact.get("operation_id") or "")
+    phase = str(fact.get("phase") or "unknown")
+    record_error = fact.get("error")
+    if phase == "conflicted":
+        error_detail = ""
+        error_code = ""
+        if isinstance(record_error, dict):
+            error_code = str(record_error.get("code") or "")
+            error_detail = str(record_error.get("detail") or "")
+        suffix = ": ".join(value for value in (error_code, error_detail) if value)
+        message = (
+            f"conflicted UnitOfWork operation {operation_id}"
+            + (f": {suffix}" if suffix else "")
+        )
+        return _issue(
+            code="STATE-RECOVERY-CONFLICTED-OPERATION",
+            severity="warning",
+            path=_diagnostic_path(repo_root, Path(str(fact.get("path") or ""))),
+            message=message,
+            command_hint=(
+                "Resolve the recorded conflict manually; Doctor does not retry "
+                "or mutate conflicted operation state."
+            ),
+            contract="runtime-health:state-recovery",
+            kind="pending_operation",
+            operationId=operation_id,
+            operationKind=str(fact.get("kind") or "unknown"),
+            phase=phase,
+            participantCount=fact.get("participant_count", 0),
+        )
+    return _issue(
+        code="STATE-RECOVERY-PENDING-OPERATION",
+        severity="warning",
+        path=_diagnostic_path(repo_root, Path(str(fact.get("path") or ""))),
+        message=f"pending UnitOfWork operation {operation_id} is in phase {phase}",
+        command_hint=_operation_command_hint(),
+        contract="runtime-health:state-recovery",
+        kind="pending_operation",
+        operationId=operation_id,
+        operationKind=str(fact.get("kind") or "unknown"),
+        phase=phase,
+        participantCount=fact.get("participant_count", 0),
+    )
+
+
+def check_state_recovery(repo_root: Path) -> list[dict[str, object]]:
+    workflow = repo_root / ".cowork-flow"
+    if not workflow.is_dir():
+        return []
+    store = StateStore()
+    issues: list[dict[str, object]] = []
+    for lock_path in sorted(workflow.rglob("*.lock")):
+        if not lock_path.is_file():
+            continue
+        info = store.inspect_lock_path(
+            lock_path,
+            stale_after_seconds=DEFAULT_STALE_LOCK_SECONDS,
+        )
+        if info.status != "absent":
+            issues.append(_state_lock_issue(repo_root, info))
+    operation_log = OperationLog(repo_root, state_store=store)
+    for fact in operation_log.pending_facts():
+        issues.append(_pending_operation_issue(repo_root, fact))
+    return issues
+
+
+def _print_state_recovery_issues(issues: list[dict[str, object]]) -> None:
+    for issue in issues:
+        print(
+            "WARNING: "
+            f"{issue['kind']}: {issue['path']}: "
+            f"{issue['message']}",
+            file=sys.stderr,
+        )
+        hint = issue.get("commandHint")
+        if hint:
+            print(f"Hint: {hint}", file=sys.stderr)
+
+
 def check_runtime(repo_root: Path) -> list[str]:
     errors: list[str] = []
     try:
@@ -286,22 +489,56 @@ def check_runtime(repo_root: Path) -> list[str]:
     return errors
 
 
-def _run_checks(repo_root: Path) -> int:
-    errors = []
-    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))
+def _all_check_result(repo_root: Path) -> dict[str, object]:
+    host_issues = _host_issues(repo_root)
+    runtime_errors = check_runtime(repo_root)
+    distribution_errors = check_distribution(repo_root)
+    task_hygiene_issues = check_task_hygiene(repo_root)
+    state_recovery_issues = check_state_recovery(repo_root)
+    errors: list[dict[str, object]] = []
+    for issue in host_issues:
+        errors.append({"kind": "host_adapter", **issue})
+    errors.extend(
+        {"kind": "runtime", "message": error}
+        for error in runtime_errors
+    )
+    errors.extend(
+        {"kind": "distribution", "message": error}
+        for error in distribution_errors
+    )
+    return {
+        "ok": not errors,
+        "errors": errors,
+        "issues": {
+            "hostAdapters": host_issues,
+            "taskHygiene": task_hygiene_issues,
+            "stateRecovery": state_recovery_issues,
+        },
+    }
+
+
+def _run_checks(repo_root: Path, *, structured: bool = False) -> int:
+    result = _all_check_result(repo_root)
+    errors = result["errors"]
+    if structured:
+        print(json.dumps(result, ensure_ascii=False))
+        return 1 if errors else 0
+    _print_task_hygiene_issues(result["issues"]["taskHygiene"])
+    _print_state_recovery_issues(result["issues"]["stateRecovery"])
     if errors:
         for error in errors:
-            print(f"ERROR: {error}", file=sys.stderr)
+            print(f"ERROR: {error['message']}", file=sys.stderr)
         return 1
     print("runtime health checks passed")
     return 0
 
 
-def _run_host_checks(repo_root: Path) -> int:
-    errors = _host_errors(repo_root)
+def _run_host_checks(repo_root: Path, *, structured: bool = False) -> int:
+    issues = _host_issues(repo_root)
+    if structured:
+        print(json.dumps({"issues": issues}, ensure_ascii=False))
+        return 1 if issues else 0
+    errors = [issue["message"] for issue in issues]
     if errors:
         for error in errors:
             print(f"ERROR: {error}", file=sys.stderr)
@@ -346,9 +583,9 @@ def main() -> int:
     args = build_parser().parse_args()
     repo_root = get_repo_root()
     if args.all:
-        return _run_checks(repo_root)
+        return _run_checks(repo_root, structured=bool(args.json))
     if args.host_adapters:
-        return _run_host_checks(repo_root)
+        return _run_host_checks(repo_root, structured=bool(args.json))
     if args.subagent_safety:
         return _run_runtime_checks(repo_root)
     if args.task_hygiene:

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

@@ -13,108 +13,151 @@ Before writing a plan, confirm the request has an executable scope, acceptance c
 
 Read:
 
-- Active task decision-anchor.md.
-- Relevant change spec/design files.
+- Active task `decision-anchor.md`.
+- Relevant decision-anchor, design, guide, or spec files.
 - Relevant `.cowork-flow/spec/` indexes and target specs.
+- `.cowork-flow/spec/guides/index.md` for non-trivial, ambiguous, cross-layer, or reusable-work planning.
 - Files that define the contracts being changed.
 
 ## Plan Shape
 
 Save plans to `.cowork-flow/plans/YYYY-MM-DD-<slug>.md` unless the user asks for another path.
 
-Start with:
+### Plan Style: Task Briefs, Not Design Docs
+
+Plans exist to prevent implementation drift. They must guide implementation by pinning task order, file boundaries, key symbols, the core patch shape, test proof, completion conditions, and prohibited drift. They are not architecture essays and must not explain every possible option.
+
+Do not write option-comparison tables unless the user explicitly asks. Do not copy complete implementations into the plan. The plan should expose the core patch shape: where to change, what behavior changes, what key branch or pseudocode should guide the edit, how tests prove it, and which boundaries must not be crossed.
+
+Start with a concise brief:
 
 ```markdown
 # <Feature> Implementation Plan
 
+> Execution rule: this plan exists to prevent implementation drift. The implementer must work through tasks in order.
+> If the plan conflicts with current code facts, a plan-external file becomes necessary, or a test fails for an unplanned reason, stop and report back instead of expanding scope.
+>
 > For formal fixed-agent work: create a runtime context with `.cowork-flow/run subagent init`, pass `cowork_runtime_context_id: <runtime_context_id>` through the active Host Adapter, then dispatch `cowork-implement` or `cowork-check`. Close the runtime context after verification.
 
-| 项 | 内容 |
+| Field | Content |
 |----|------|
-| **目标** | <一句话> |
-| **架构** | <2-3 句> |
-| **验证** | `<命令>` → exit 0；`<命令>` → exit 0 |
-| **策略** | 串行 / 并行（文件所有权：A 组 / B 组） |
-| **范围** | N 步 / N 文件 / N AC |
-| **风险** | 无显著风险 / 见尾部风险表 §高-N |
-
-## 概览
-
-| Step | AC | 标题 | 状态 |
-|------|----|------|------|
-| 1.1 | AC-001 | <标题> | ⬜ |
-| 1.2 | AC-002 | <标题> | ⬜ |
-| 2.1 | — | <标题> | ⬜ |
+| **Goal** | <One sentence describing the observable behavior change> |
+| **Task Type** | Tiny / Normal / High-risk: <reason> |
+| **Strategy** | Serial / Parallel: <why> |
+| **Success Criteria** | AC-001 / AC-002 / AC-003 |
+| **Final Verification** | `<command>` -> exit 0; `<command>` -> exit 0 |
+| **Primary Risk** | Low / Medium / High: <one sentence> |
+
+## Goal
+
+<1-3 sentences describing the expected observable behavior.>
+
+## Acceptance Criteria
+
+- AC-001: <observable behavior>
+- AC-002: <observable behavior>
+
+## Global Constraints
+
+- <Architecture boundary, compatibility requirement, command, or output field that must be preserved>
+- <Explicitly prohibited scope expansion>
+
+## File Boundaries
+
+- `path/a.py`: <responsibility; only change this function or region>
+- `tests/test_a.py`: <responsibility; only add or modify these tests>
+
+## Tasks
 ```
 
-Then list acceptance criteria, then steps.
+Then list task briefs, followed by integrated verification and completion checks.
 
 ## Task Rules
 
+- Classify the plan before writing tasks:
+  - **Tiny**: pure docs, names, comments, or no-behavior cleanup. Use file boundaries, completion conditions, and one verification command.
+  - **Normal**: ordinary behavior, test, or workflow guidance changes. Use the full task brief below.
+  - **High-risk**: workflow, runtime, template, spec, hook, state-machine, migration, or security-sensitive changes. Use the full task brief plus code-fact sources and explicit drift boundaries.
 - Each task names exact files to create, modify, or test.
-- Each step is small enough to execute and verify independently.
-- **Every step MUST follow the executable format below** so subagents never guess:
+- Each task is small enough to execute and verify independently.
+- Every Normal or High-risk task must use this brief format:
 
   ```markdown
-  ### Step N.M [AC-XXX] ⬜: <一句话描述，中文>
+  ### Task N: <small goal>
 
-  - **改动**: `path/a.py`, `path/b.py`（×2 = template + root 两份）
-  - **做了什么**: <一句话具体变更>
-  - **验证**: `<命令>` → exit 0（实现前 exit 1 → 实现后 exit 0 | AC-XXX）
-  - **回滚**: <一句话或"仅增测试，无回滚成本">
-  ```
+  **Purpose**
+  - <Observable behavior after this task is complete>
 
-  For steps covering multiple AC:
+  **Code Fact Sources**
+  - Read: `path/a.py::function_name`
+  - Read: `tests/test_a.py::test_existing_behavior`
 
-  ```markdown
-  - **同时覆盖**: AC-002
-  ```
+  **File Boundaries**
+  - Create / Modify / Test: `path/a.py` (only change <function/region>)
+  - Test: `tests/test_a.py` (only change <test/region>)
 
-  For steps without an AC (e.g. integrated verification):
+  **Key Symbols**
+  - Change: `function_name()`, `ClassName.method()`, `<config-key>`
+  - Preserve: `existing_helper()`, output field `<field>`
 
-  ```markdown
-  ### Step N.M — ⬜: <一句话描述，中文>
+  **Implementation Notes**
+  ```python
+  # Core control-flow sketch; adjust names to match existing code.
+  # Do not copy a complete implementation into the plan.
+  ...
   ```
 
-  In the overview table, fill AC column with `—` for no-AC steps.
+  **Test Proof**
+  - `tests/test_a.py::test_x`: proves <specific behavior>
+  - Core assertion: <one sentence describing the assertion, not only the test name>
 
-- For behavior changes, include concrete verification in Verify parentheses, such as `reproduces before change -> passes after change`. When setup and final verification differ, use two-line form:
-  ```
-  - **验证**: `red command` → exit 1 | `green command` → exit 0 | AC-XXX
-  ```
-- Expected/断言 field is retired. Its responsibility moves into Verify parentheses — describe state changes that exit code alone cannot cover:
+  **Verification Command**
+  ```bash
+  <command>
   ```
-  - **验证**: `pytest tests/test_archive.py -q` → exit 0（覆盖：归档成功的 JSONL 自路径规范化 + 失败路径的字节级回滚）
+
+  **Completion Conditions**
+  - <2-4 checkable conditions>
+
+  **Prohibited Drift**
+  - <2-5 explicit prohibited changes>
+
+  **Deviation Conditions**
+  - If <plan-external file/layer> becomes necessary, must stop and report back because the file boundary is wrong.
   ```
-- Rollback is always local — write recovery directly in the step. No cross-reference to risk table.
-- Include commands and expected results in every step.
-- Include a failing test before implementation when behavior can be tested.
-- Do not add shallow tests just to satisfy process. Avoid tests that only assert existence, mirror implementation details, count mocks without behavior, or snapshot empty structure.
-- For complex problems, test depth first: cover invariants, cross-layer contracts, state transitions, error boundaries, and real regression paths before narrow unit cases.
-- Map each behavior-changing test to a stable decision-anchor.md acceptance ID when useful; do not create `tdd.jsonl` or TDD evidence records in `check.jsonl`.
-- Avoid placeholders such as TODO, TBD, "handle edge cases", or "write tests".
+
+- For Tiny tasks, keep the brief short but still name exact file boundaries, completion conditions, and verification commands.
+- For behavior changes, include a failing test before implementation when behavior can be tested.
+- Do not add shallow tests just to satisfy process. Avoid tests that only assert existence, mirror implementation details, count mock calls without behavior, or snapshot empty structure.
+- For complex problems, test depth first: business invariants, cross-layer contracts, state transitions, error boundaries, and real regression paths before narrow unit cases.
+- Map behavior-changing tests to stable `decision-anchor.md` acceptance IDs when useful; do not create `tdd.jsonl` or write TDD evidence records into `check.jsonl`.
+- Avoid placeholders such as `TODO`, `TBD`, "handle edge cases", or "write tests".
 - Keep root/template parity explicit when both copies exist.
+- When guide material changes the intended approach, capture the selected conclusion in `decision-anchor.md`, the task brief, or explicit prohibited drift; do not leave it as unstated background knowledge.
+- If a task needs more than about 15 lines of implementation pseudocode, split it or narrow the scope. Plans should guide the edit, not replace the implementation.
 
 ### Anti-Rationalization - Planning Phase
 
 | Agent Rationalization | Rebuttal | Alternative |
 |---|---|---|
-| "This task is too small, let's merge it." | Task granularity is determined by acceptance criteria, not line count. Merge only when AC cannot be split; otherwise keep independent. | Split until each step has a distinct AC; keep them as independent steps even when short. |
-| "Write a rough plan first, refine during implementation." | Rough plan = no constraints during implementation. Implementation without constraints = scope creep or rework. | Write the plan to the full executable format (改动 / 做了什么 / 验证 / 回滚) before any code is touched. |
-| "Skip the plan and start directly since we have decision-anchor." | decision-anchor.md defines "what to do"; the plan defines "how to do it and in what order." Tasks without a plan incur doubled rework cost when dependency errors surface midway. | Use decision-anchor.md to derive the AC list, then produce plan steps that map each AC to a concrete file + verify command. |
-| "This task doesn't need a verify command." | No verify = no completion signal. Every task must have an executable verification command. | Add at least one automated check (typecheck, test, lint, build) as the Verify step so completion is observable. |
+| "This task is too small, let's merge it." | Task granularity is determined by acceptance criteria, not line count. Merge only when AC cannot be split. | Split until each step has a distinct AC; keep steps independent even when short. |
+| "Write a rough plan first, refine during implementation." | Rough plans do not constrain implementation. Unconstrained implementation invites scope creep and rework. | Use `decision-anchor.md` to derive acceptance criteria, then write task briefs with file boundaries, key symbols, implementation notes, test proof, completion conditions, and prohibited drift. |
+| "Skip the plan since we already have decision-anchor." | `decision-anchor.md` defines what to do; the plan defines how to do it and in what order. Without a plan, dependency mistakes surface mid-implementation and increase rework. | Derive ACs from `decision-anchor.md`, then map each AC to concrete files and verification commands. |
+| "This task does not need a verification command." | No verification means no completion signal. Every task needs an executable verification command. | Add at least one automated check, such as typecheck, test, lint, or build. |
+| "The plan should explore every alternative." | Heavy option analysis slows routine implementation and hides the path to execute. | State the chosen path and drift boundaries. Add option analysis only when the user asks or the decision is genuinely architectural. |
 
 ## Plan Approval Gate
 
-A plan can be marked as approved only when all conditions hold:
-- Every task in implement.jsonl has clear acceptance criteria
-- Every task has implement steps and verify commands
-- Task dependencies are explicit (parallelizable vs. strictly sequential)
+A plan can be marked approved only when all conditions hold:
+
+- Every task in `implement.jsonl` has clear acceptance criteria.
+- Every task has implementation steps and verification commands.
+- Task dependencies are explicit, including whether work is serial or parallelizable.
 
 ## Post-Approval Options
 
-- **Step-by-task progression** (default path): user runs `task next <task-dir> --run` for the current safe action, completes the task, then runs `task next <next-task-dir> --run` for the next task.
-- **Batch mode**: triggered when the user explicitly says "auto" or "batch" (see skills/batch-execution/SKILL.md). Each task is still verified independently.
+- **Step-by-task progression** (default path): the user runs `task next <task-dir> --run` for the current safe action, completes the task, then runs `task next <next-task-dir> --run` for the next task.
+- **Batch mode**: triggered only when the user explicitly says "auto" or "batch"; see `skills/batch-execution/SKILL.md`. Each task still must be verified independently.
 
 > **Default is step-by-task progression.** Do not enter batch mode unless the user explicitly says "auto".
 
@@ -137,7 +180,8 @@ Execution strategy guide:
 
 Before handoff:
 
-1. Confirm every decision-anchor.md acceptance criterion maps to a plan step.
+1. Confirm every `decision-anchor.md` acceptance criterion maps to a task.
 2. Search the plan for placeholders.
-3. Check names, paths, command syntax, and expected outputs.
-4. Record remaining risks or blocklers.
+3. Confirm every Normal or High-risk task has file boundaries, key symbols, implementation notes, test proof, completion conditions, and prohibited drift.
+4. Check names, paths, command syntax, and expected outputs.
+5. Confirm the plan says to stop and report back when code facts conflict with the plan, a plan-external file becomes necessary, or a test fails for an unplanned reason.

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

@@ -12,7 +12,7 @@ Use this Skill during the check phase, before the `task next --run` completion a
 - Review early enough that fixes are cheap; do not wait until archive/commit to discover blockers.
 - Review the current diff and exact task context, not broad conversation memory.
 - Separate machine-decidable lifecycle facts from human judgment: lifecycle blockers cover state/scope facts; review judgment explains spec, quality, and risk findings.
-- Treat backend/frontend/guides natural-language markdown as user-defined review requirements, not dynamic hard validators.
+- Treat backend/frontend natural-language markdown as user-defined review requirements, not dynamic hard validators.
 - 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.
@@ -28,16 +28,16 @@ Read only what is needed for the current task:
 2. The linked implementation plan, if present.
 3. The check context index (`<task>/check.jsonl`) and each referenced file, if present. Treat it as context only; do not write review conclusions or readiness evidence to it.
 4. Current `git diff` / `git status --short`.
-5. Relevant `.cowork-flow/spec/backend/`, `.cowork-flow/spec/frontend/`, and `.cowork-flow/spec/guides/` files selected by changed paths and task scope.
+5. Relevant `.cowork-flow/spec/backend/` and `.cowork-flow/spec/frontend/` files selected by changed paths and task scope.
 6. Advisory facts from `review-check <task-dir> --json`, when useful.
-7. Lifecycle blocker output, if any, from `task next`, `task review`, or `task complete`.
+7. Lifecycle blocker output, if any, from `task next --json`, `task next <dir> --validate`, or `task next <dir> --run --intent review`.
 
 ## Task Review Checklist
 
 - **Scope**: every changed file is planned or justified; no unrelated cleanup sneaks in.
 - **Behavior**: acceptance criteria are satisfied through observable behavior, not implementation-shaped assertions.
 - **Tests**: test intent is explicit; tests fail for meaningful regressions, reject shallow tests such as existence/mock/snapshot-only checks, and cover boundary/error paths when relevant.
-- **User specs**: every applicable backend/frontend/guides requirement is marked `pass`, `finding`, `not_applicable`, or `needs_user_judgment`.
+- **User specs**: every applicable backend/frontend requirement is marked `pass`, `finding`, `not_applicable`, or `needs_user_judgment`.
 - **Specs**: project specs are updated when behavior/contracts changed, or the review states why no spec update is needed.
 - **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.