cowork-flow 2.3.0 → 2.4.1

package/template/locales/en-US/.cowork-flow/templates/plan-template.md

@@ -0,0 +1,91 @@
+# <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 |
+|----|------|
+| **Task Type** | Tiny / Normal / High-risk: <reason> |
+| **Strategy** | Serial / Parallel: <why> |
+| **Success Criteria** | AC-001 / AC-002 / AC-003 |
+| **Final Verification** | `<command>` -> exit 0; clause-by-clause check against applicable `.cowork-flow/spec/<dev_type>/` rules and project gates -> `pass` / `not_applicable` per clause |
+| **Primary Risk** | Low / Medium / High: <one sentence> |
+
+**Goal:** <One sentence describing the observable behavior change>
+
+## 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
+
+Tiny plans may keep a shorter brief, but must still name exact file boundaries, completion conditions, and one verification command.
+
+### Task N: <small goal>
+
+**Purpose**
+- <Observable behavior after this task is complete>
+
+**Code Fact Sources**
+- Read: `path/a.py::function_name`
+- Read: `tests/test_a.py::test_existing_behavior`
+
+**File Boundaries**
+- Create / Modify / Test: `path/a.py` (only change <function/region>)
+- Test: `tests/test_a.py` (only change <test/region>)
+
+**Key Symbols**
+- Change: `function_name()`, `ClassName.method()`, `<config-key>`
+- Preserve: `existing_helper()`, output field `<field>`
+
+**Implementation Notes**
+```python
+# Core control-flow sketch; adjust names to match existing code.
+# Do not copy a complete implementation into the plan.
+...
+```
+
+**Test Proof**
+- `tests/test_a.py::test_x`: proves <specific behavior>
+- Core assertion: <one sentence describing the assertion, not only the test name>
+
+**Verification Command**
+```bash
+<command>
+```
+
+When changed files are covered by `.cowork-flow/spec/<dev_type>/` rules, add the deciding command or a spec/gate check line (`pass` / `not_applicable` with reason) here. Before a strict non-Tiny task starts, replace `<pass / not_applicable + reason>` with the actual result; the start gate rejects the template placeholder.
+
+**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.
+
+## Final Verification
+
+```bash
+<command>
+```
+
+Spec check: clause-by-clause check against applicable `.cowork-flow/spec/<dev_type>/` rules -> <pass / not_applicable + reason>.

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

@@ -6,6 +6,7 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import re
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
@@ -31,6 +32,7 @@ from adapters.host.host_manifest import (
     validate_host_assets,
 )
 from infra.paths import DIR_WORKFLOW, get_repo_root
+from infra.config import UnsupportedLanguageError, get_language
 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
@@ -205,6 +207,101 @@ def check_distribution(repo_root: Path) -> list[str]:
     return errors
 
 
+_ANCHOR_LANGUAGE_CHECKS = {
+    "zh-CN": ("## 目标", "## 验收标准", "## 被拒方案", "## 验证命令"),
+    "en-US": ("## Goal", "## Acceptance Criteria", "## Rejected Options", "## Verification Commands"),
+}
+_PLAN_LANGUAGE_CHECKS = {
+    "zh-CN": re.compile(r"(?m)^\*\*目标(?::\*\*|\*\*:)"),
+    "en-US": re.compile(r"(?m)^\*\*Goal(?::\*\*|\*\*:)"),
+}
+
+
+def _contract_block(text: str) -> str:
+    """The schema example is the machine-readable heading source."""
+    match = re.search(r"```markdown\n(.*?)```", text, re.DOTALL)
+    return match.group(1) if match else text
+
+
+def _asset_language(path: Path, kind: str) -> str | None:
+    """Detected output language, `mixed`, or None when the asset is absent."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+    if kind == "anchor":
+        block = _contract_block(text)
+        present = {
+            language
+            for language, markers in _ANCHOR_LANGUAGE_CHECKS.items()
+            if all(marker in block for marker in markers)
+        }
+    else:
+        present = {
+            language
+            for language, pattern in _PLAN_LANGUAGE_CHECKS.items()
+            if pattern.search(text)
+        }
+    if len(present) > 1:
+        return "mixed"
+    return next(iter(present), None)
+
+
+def check_language(repo_root: Path) -> list[dict[str, str]]:
+    """Report an invalid `language` value and localized-asset drift.
+
+    A missing config key or a missing asset means the project predates the
+    language option: it is not drift, so it stays silent until the first sync.
+    """
+    config_file = repo_root / DIR_WORKFLOW / "config.yaml"
+    try:
+        config_text = config_file.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return []
+    if not re.search(r"(?m)^language\s*:", config_text):
+        return []
+
+    try:
+        language = get_language(repo_root, strict=True)
+    except UnsupportedLanguageError as error:
+        return [
+            _issue(
+                code="CONFIG-LANGUAGE-001",
+                severity="error",
+                path=config_file.relative_to(repo_root).as_posix(),
+                message=str(error),
+                command_hint="Edit .cowork-flow/config.yaml, then run cwf project sync",
+                contract="runtime-health:language",
+            )
+        ]
+
+    issues: list[dict[str, str]] = []
+    assets = (
+        (".cowork-flow/spec/contracts/decision-anchor.md", "anchor"),
+        (".cowork-flow/templates/plan-template.md", "plan"),
+    )
+    for relative, kind in assets:
+        path = repo_root / relative
+        detected = _asset_language(path, kind)
+        if detected is None:
+            continue
+        if detected != language:
+            issues.append(
+                _issue(
+                    code="LANGUAGE-DRIFT-001",
+                    severity="warning",
+                    path=relative,
+                    message=(
+                        f"installed asset language is {detected}, but "
+                        f".cowork-flow/config.yaml selects {language}"
+                    ),
+                    command_hint="cwf project sync",
+                    contract="runtime-health:language",
+                )
+            )
+    return issues
+
+
 def _task_path(repo_root: Path, task_dir: Path) -> str:
     try:
         return task_dir.resolve().relative_to(repo_root.resolve()).as_posix()
@@ -1673,6 +1770,7 @@ 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)
+    language_issues = check_language(repo_root)
     task_hygiene_issues = check_task_hygiene(repo_root)
     state_recovery_issues = check_state_recovery(repo_root)
     session_hygiene_issues = check_session_hygiene(repo_root)
@@ -1697,11 +1795,17 @@ def _all_check_result(repo_root: Path) -> dict[str, object]:
         {"kind": "distribution", "message": error}
         for error in distribution_errors
     )
+    errors.extend(
+        {"kind": "language", **issue}
+        for issue in language_issues
+        if issue["severity"] == "error"
+    )
     return {
         "ok": not errors,
         "errors": errors,
         "issues": {
             "hostAdapters": host_issues,
+            "language": language_issues,
             "taskHygiene": task_hygiene_issues,
             "stateRecovery": state_recovery_issues,
             "sessionHygiene": session_hygiene_issues,
@@ -1725,6 +1829,12 @@ def _run_checks(repo_root: Path, *, structured: bool = False) -> int:
     if structured:
         print(json.dumps(result, ensure_ascii=False))
         return 1 if errors else 0
+    for issue in result["issues"]["language"]:
+        if issue["severity"] == "error":
+            continue
+        print(f"Language ({issue['code']}): {issue['message']}")
+        if issue.get("commandHint"):
+            print(f"  fix: {issue['commandHint']}")
     _print_task_hygiene_issues(result["issues"]["taskHygiene"])
     _print_state_recovery_issues(result["issues"]["stateRecovery"])
     _print_session_hygiene_issues(result["issues"]["sessionHygiene"])

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

@@ -14,6 +14,7 @@ Before writing a plan, confirm the request has an executable scope, acceptance c
 Read:
 
 - Active task `decision-anchor.md`.
+- The installed `.cowork-flow/templates/plan-template.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.
@@ -23,114 +24,32 @@ Read:
 
 Save plans to `.cowork-flow/plans/YYYY-MM-DD-<slug>.md` unless the user asks for another path.
 
-### 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.
+Use the installed `.cowork-flow/templates/plan-template.md` as the plan skeleton. It carries the execution rule, header table, goal and acceptance sections, global constraints, file boundaries, the per-task brief fields, and the final verification section, so this Skill does not restate them.
 
-| Field | Content |
-|----|------|
-| **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; clause-by-clause check against applicable `.cowork-flow/spec/<dev_type>/` rules and project gates -> `pass` / `not_applicable` per clause |
-| **Primary Risk** | Low / Medium / High: <one sentence> |
+If the installed template is missing, stop and report it (run `cwf project sync .` to install it); do not invent a replacement shape.
 
-## Goal
+The template is distributed at install time for the project language configured in `.cowork-flow/config.yaml` (`zh-CN` by default, or `en-US`). Write the plan in that language. Keep the template's machine-readable goal line and `AC-NNN` identifiers unchanged so task creation and workflow gates can parse them. Do not translate paths, commands, code identifiers, or spec file names.
 
-<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
+### Plan Style: Task Briefs, Not Design Docs
 
-- `path/a.py`: <responsibility; only change this function or region>
-- `tests/test_a.py`: <responsibility; only add or modify these tests>
+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.
 
-## Tasks
-```
+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.
 
-Then list task briefs, followed by integrated verification and completion checks.
+Fill the template in order: header table and goal first, then acceptance criteria, global constraints, file boundaries, one task brief per executable step, and a final verification section. Do not add a second plan shape or rename the template sections.
 
 ## 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.
+  - **Normal**: ordinary behavior, test, or workflow guidance changes. Use the full task brief.
   - **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 task is small enough to execute and verify independently.
-- Every Normal or High-risk task must use this brief format:
-
-  ```markdown
-  ### Task N: <small goal>
-
-  **Purpose**
-  - <Observable behavior after this task is complete>
-
-  **Code Fact Sources**
-  - Read: `path/a.py::function_name`
-  - Read: `tests/test_a.py::test_existing_behavior`
-
-  **File Boundaries**
-  - Create / Modify / Test: `path/a.py` (only change <function/region>)
-  - Test: `tests/test_a.py` (only change <test/region>)
-
-  **Key Symbols**
-  - Change: `function_name()`, `ClassName.method()`, `<config-key>`
-  - Preserve: `existing_helper()`, output field `<field>`
-
-  **Implementation Notes**
-  ```python
-  # Core control-flow sketch; adjust names to match existing code.
-  # Do not copy a complete implementation into the plan.
-  ...
-  ```
-
-  **Test Proof**
-  - `tests/test_a.py::test_x`: proves <specific behavior>
-  - Core assertion: <one sentence describing the assertion, not only the test name>
-
-  **Verification Command**
-  ```bash
-  <command>
-  ```
-
-  When changed files are covered by `.cowork-flow/spec/<dev_type>/` rules, add the deciding command or a spec/gate check line (`pass` / `not_applicable` with reason; format example in `decision-anchor.md`) here; it is a strong review reminder, not a hard gate.
-
-  **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.
-  ```
-
+- Every Normal or High-risk task fills every required field in the template's task brief: Purpose, Code Fact Sources, File Boundaries, Key Symbols, Implementation Notes, Test Proof, Verification Command, Completion Conditions, Prohibited Drift, and Deviation Conditions.
 - 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.
-- For implementation tasks whose changed files are covered by `.cowork-flow/spec/` requirements, name the covered spec files in the plan and add the clause check to the task's `Verification Command` and the plan's `Final Verification`: run the deciding command when one exists, otherwise check clause by clause and record `pass` / `not_applicable` with reason. This is a strong review reminder, not a separate hard gate.
+- For implementation tasks whose changed files are covered by `.cowork-flow/spec/` requirements, name the covered spec files in the plan and add the clause check to the task's `Verification Command` and the plan's `Final Verification`: run the deciding command when one exists, otherwise check clause by clause and record `pass` / `not_applicable` with reason. For strict non-Tiny tasks this is a hard start gate: the bound plan and the task anchor must use the configured-language verification heading and carry a filled spec-check result. The template placeholder `<pass / not_applicable + reason>` blocks start; replace it before starting. The content remains self-declared and is reviewed by the check agent.
 - 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`.
@@ -149,6 +68,12 @@ Then list task briefs, followed by integrated verification and completion checks
 | "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. |
 
+## Fixed-Agent Dispatch
+
+> 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.
+
+Use this path when a task is dispatched to a fixed agent. The plan owns the task boundaries; the runtime context binds the dispatched agent to the current task.
+
 ## Plan Approval Gate
 
 A plan can be marked approved only when all conditions hold:
@@ -156,6 +81,7 @@ A plan can be marked approved only when all conditions hold:
 - Every task in the plan has clear acceptance criteria.
 - Every task has implementation steps and verification commands.
 - Task dependencies are explicit, including whether work is serial or parallelizable.
+- The plan uses the installed `.cowork-flow/templates/plan-template.md` shape and the configured output language. For strict non-Tiny tasks, the runtime blocks start when the plan or anchor lacks the configured-language verification section or a filled spec-check result.
 
 `implement.jsonl` is the current task's context index — the files in scope and
 the spec pointers it needs — not the task list. The plan owns the task list.
@@ -189,7 +115,8 @@ Before handoff:
 
 1. Confirm every `decision-anchor.md` acceptance criterion maps to a task.
 2. Search the plan for placeholders.
-3. Confirm every Normal or High-risk task has file boundaries, key symbols, implementation notes, test proof, completion conditions, and prohibited drift.
+3. Confirm every Normal or High-risk task fills every required brief field in the template.
 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.
-6. Confirm Final Verification carries the applicable `.cowork-flow/spec/<dev_type>/` clause check, or states why no spec file applies.
+6. Confirm Final Verification carries the applicable `.cowork-flow/spec/<dev_type>/` clause check with an actual `pass` / `not_applicable` result, or states why no spec file applies. For strict non-Tiny tasks the runtime blocks start when this line is missing or still the template placeholder.
+7. Confirm the plan is written in the configured language and keeps the machine-readable goal line and `AC-NNN` identifiers unchanged.