cowork-flow 2.2.0 → 2.4.0

package/template/.cowork-flow/spec/schemas/host-assets.schema.json

@@ -56,6 +56,9 @@
     "excludedPrefixes": {
       "$ref": "#/$defs/stringList"
     },
+    "localization": {
+      "$ref": "#/$defs/localization"
+    },
     "syncPolicy": {
       "$ref": "#/$defs/syncPolicy"
     }
@@ -68,6 +71,31 @@
         "minLength": 1
       }
     },
+    "localization": {
+      "description": "Per-language asset overrides. Paths are canonical project-relative paths; the base template is the default language.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "default",
+        "supported",
+        "assets"
+      ],
+      "properties": {
+        "default": {
+          "type": "string",
+          "minLength": 1
+        },
+        "supported": {
+          "$ref": "#/$defs/stringList"
+        },
+        "assets": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/stringList"
+          }
+        }
+      }
+    },
     "capabilities": {
       "type": "object",
       "minProperties": 1,
@@ -342,6 +370,9 @@
         "protectedFiles": {
           "$ref": "#/$defs/stringList"
         },
+        "forceProtectedFiles": {
+          "$ref": "#/$defs/stringList"
+        },
         "protectedPrefixes": {
           "$ref": "#/$defs/stringList"
         },

package/template/.cowork-flow/spec/schemas/index.md

@@ -1,9 +1,9 @@
 # Schema Specs
 
-本目录存放 JSON Schema。
+This directory holds JSON Schemas.
 
-- `adapter.schema.json`: 宿主适配器声明 schema。
-- `host-assets.schema.json`: Host Asset Manifest schema（`runtime/host-assets.json` 的结构约束）。
-- `party-mode-v2-actions.schema.json`: Party Mode V2 action schema。
+- `adapter.schema.json`: host adapter declaration schema.
+- `host-assets.schema.json`: Host Asset Manifest schema (structural constraints for `runtime/host-assets.json`).
+- `party-mode-v2-actions.schema.json`: Party Mode V2 action schema.
 
-Schema 只描述数据合同，不承载流程说明；流程和行为边界写入 `contracts/`、Skill command manifests 或 `AGENTS.md`。
+Schemas describe data contracts only, not workflow guidance; workflow and behavior boundaries belong in `contracts/`, Skill command manifests, or `AGENTS.md`.

package/template/.cowork-flow/templates/plan-template.md

@@ -0,0 +1,91 @@
+# <功能> 实施计划
+
+> 执行规则：本计划用于防止实现漂移，实现者必须按任务顺序推进。
+> 如果计划与当前代码事实冲突、需要计划外文件，或测试因未计划的原因失败，停止并报告，不要扩大范围。
+>
+> 正式固定代理工作：使用 `.cowork-flow/run subagent init` 创建 runtime context，通过当前 Host Adapter 传入 `cowork_runtime_context_id: <runtime_context_id>`，再派发 `cowork-implement` 或 `cowork-check`；验证完成后关闭 runtime context。
+
+| 字段 | 内容 |
+|----|------|
+| **任务类型** | Tiny / Normal / High-risk：<理由> |
+| **执行策略** | Serial / Parallel：<理由> |
+| **成功标准** | AC-001 / AC-002 / AC-003 |
+| **最终验证** | `<command>` → exit 0；逐条核对适用的 `.cowork-flow/spec/<dev_type>/` 规范与项目门禁 → 每条 `pass` / `not_applicable` |
+| **主要风险** | Low / Medium / High：<一句话> |
+
+**目标:** <一句话描述可观察的行为变化>
+
+## 目标
+
+<1-3 句话描述预期可观察行为。>
+
+## 验收标准
+
+- AC-001: <可验证行为>
+- AC-002: <可验证行为>
+
+## 全局约束
+
+- <必须保留的架构边界、兼容要求、命令或输出字段>
+- <明确禁止的范围扩张>
+
+## 文件边界
+
+- `path/a.py`：<职责；只改这个函数或区域>
+- `tests/test_a.py`：<职责；只新增或修改这些测试>
+
+## 任务
+
+Tiny 任务可保留简化 brief，但仍须写明精确文件边界、完成条件和一条验证命令。
+
+### 任务 N：<小目标>
+
+**目的**
+- <本任务完成后的可观察行为>
+
+**代码事实来源**
+- Read: `path/a.py::function_name`
+- Read: `tests/test_a.py::test_existing_behavior`
+
+**文件边界**
+- Create / Modify / Test: `path/a.py`（只改 <函数/区域>）
+- Test: `tests/test_a.py`（只改 <测试/区域>）
+
+**关键符号**
+- Change: `function_name()`、`ClassName.method()`、`<config-key>`
+- Preserve: `existing_helper()`、输出字段 `<field>`
+
+**实现说明**
+```python
+# 核心控制流草图；按现有代码调整名称。
+# 不要把完整实现复制进计划。
+...
+```
+
+**测试证明**
+- `tests/test_a.py::test_x`：证明 <具体行为>
+- 核心断言：<一句话描述断言，不只有测试名>
+
+**验证命令**
+```bash
+<command>
+```
+
+当改动文件受 `.cowork-flow/spec/<dev_type>/` 规则覆盖时，在这里加入决定命令或规范门禁核对行（`pass` / `not_applicable` 并附理由）；这是强复核提醒，不是硬门禁。
+
+**完成条件**
+- <2-4 条可检查条件>
+
+**禁止漂移**
+- <2-5 条明确禁止的改动>
+
+**偏差条件**
+- 如果 <计划外文件/层> 变得必要，必须停止并报告，因为文件边界有误。
+
+## 最终验证
+
+```bash
+<command>
+```
+
+规范核对：逐条核对 `.cowork-flow/spec/<dev_type>/` 适用规范 → <pass / not_applicable + 理由>。

package/template/locales/en-US/.cowork-flow/spec/contracts/decision-anchor.md

@@ -0,0 +1,160 @@
+# Decision Anchor Contract
+
+**Every task must have a `decision-anchor.md`: the single authoritative decision
+source that prevents drift during execution.**
+
+It merges and replaces the former `prd.md`, carrying both "what to do" and "why not
+the alternatives", which compresses the number of task artifacts.
+
+## Schema
+
+These section names are machine-readable. The runtime parser accepts both the
+Chinese and English heading sets, and new anchors use the language configured in
+`.cowork-flow/config.yaml` (`zh-CN` is the default).
+
+```markdown
+# Decision Anchor
+
+## Goal
+<one sentence>
+
+## Acceptance Criteria
+- [ ] AC-001: <verifiable>
+- [ ] AC-002: <verifiable>
+
+## Rejected Options
+- **Option B**: <summary> — rejected because: <why>
+
+## Key Assumptions
+- <assumption 1>
+
+## Scope Boundary
+- In scope: <list>
+- Out of scope: <list>
+
+## Verification Commands
+- `<command>` → <expected>
+- Spec check: clause-by-clause check against applicable `.cowork-flow/spec/<dev_type>/` rules → pass / not_applicable (with reason)
+```
+
+## Section requirements
+
+Both heading columns below are accepted; the right column is the `en-US` output
+and the left column the `zh-CN` output.
+
+| Section | Required | Why |
+|------|------|------|
+| `## Goal` / `## 目标` | required | no goal, no acceptance baseline |
+| `## Acceptance Criteria` / `## 验收标准` | required | `task_start` is blocked without acceptance criteria |
+| `## Rejected Options` / `## 被拒方案` | optional | required for brainstorming tasks, so a rejected option is not reconsidered during execution |
+| `## Key Assumptions` / `## 关键假设` | optional | filled in for complex tasks to surface implicit constraints; not read by the runtime parser |
+| `## Scope Boundary` / `## 范围边界` | optional | prevents scope creep |
+| `## Verification Commands` / `## 验证命令` | optional | filled in for complex tasks, as the basis for automated verification; when the changed files are covered by `.cowork-flow/spec/backend/` or `frontend/` rules, it must also carry the spec/gate check for the task's `dev_type` (deciding command, or clause-by-clause `pass` / `not_applicable` with reason) |
+
+### Machine-readable line formats (for injection)
+
+`## Verification Commands` and `## Scope Boundary` are parsed by stage-contract
+injection and by the MCP fact view (`services/fact_view.parse_decision_anchor`).
+Line-format conventions:
+
+- `## Verification Commands`: one command per line (an optional `- ` prefix),
+  truncated to 120 characters, at most 10 lines; the implementing agent runs them
+  itself (self-declared, self-checked) and the reviewer verifies the execution
+  evidence. When the changed files are covered by `.cowork-flow/spec/<dev_type>/`
+  rules, the section must also carry the spec/gate check for the task's
+  `dev_type`: a deciding command, or a `Spec check:` line reviewed clause by
+  clause (`pass` / `not_applicable` + reason). This is a strong review reminder,
+  not a `spec-check` hard gate.
+- `## Scope Boundary`: only the first non-empty line is taken, truncated to 160
+  characters.
+
+## Scenarios
+
+| Scenario | Source | What gets filled in |
+|------|------|---------|
+| Has brainstorming | extracted from the discussion outcome | every section |
+| No brainstorming (requirements already clear) | extracted from the requirement description and the plan | the minimum: goal + acceptance criteria |
+
+## Artifact compression
+
+Before merging (6 files): `prd.md` + `implement.jsonl` + `check.jsonl` +
+`debug.jsonl` + `task.json`
+
+After merging (5 files): `decision-anchor.md` + `implement.jsonl` + `check.jsonl` +
+`debug.jsonl` + `task.json`
+
+**A net reduction of one file type. Related-file tracking is now owned entirely by
+`implement.jsonl`.**
+
+## Lifecycle check coupling
+
+- The preflight for `task next <dir> --run` checks that `decision-anchor.md` is
+  non-empty and requires the `## Goal` / `## 目标` and `## Acceptance Criteria` /
+  `## 验收标准` sections to be present.
+- **Gate profile `meta.gateProfile`**: a newly created task is written as
+  `"strict"`; an unmarked task is treated as `"legacy"` — existing tasks are not
+  retro-fitted with the stricter gate, and the profile is queryable through the
+  fact view. On top of the section check, a strict task additionally requires: at
+  least one parseable `- [ ] AC-xxx: ...` row in `## Acceptance Criteria` /
+  `## 验收标准`, no duplicate AC ids, no non-AC list rows in that section, and a
+  declared `dev_type` (otherwise `task specs` dev-type dispatch silently comes
+  back shorter).
+- An acceptance row's checkbox state (`- [ ]` / `- [x]`) and the evidence records
+  (the task directory's `evidence.jsonl`) are the fact source of the completion
+  gate: completion is blocked when an unchecked AC exists (`LIFECYCLE-AC-001`), a
+  declared AC has no evidence (`LIFECYCLE-AC-002`), a strict task cannot read any
+  AC row (`LIFECYCLE-AC-003`), or the AC-evidence module is unavailable
+  (`LIFECYCLE-AC-004`). Schema and exemptions are in `evidence-completion.md`.
+- **Review receipt change fingerprint** (a strict task requires its latest receipt
+  to match the current state at completion, `LIFECYCLE-REVIEW-003`). Input = the
+  git-visible change set (paths + content digests) + this anchor's goal and AC text
+  + the content digest of the bound plan + `dev_type` + the **content digest** of
+  every referenced spec + the content digest of `implement.jsonl`. Both `spec/**`
+  and `tasks/**` are gitignored, which is why the last two must enter the
+  fingerprint explicitly — otherwise rewriting a referenced spec's prose, or
+  widening the declared scope, would leave a stale receipt valid.
+- Fingerprint **exclusions** (mechanism): the change set excludes the whole
+  `.cowork-flow/tasks/**` tree, `.cowork-flow/.runtime/**`, and
+  `.cowork-flow/logs/**` — task-directory artifacts (`task.json`,
+  `evidence.jsonl`, `review.jsonl`, `check.jsonl`, `debug.jsonl`, and the anchor's
+  **path entry**) and runtime metadata are not counted, or a receipt would
+  invalidate itself the moment it was recorded. `implement.jsonl`'s path entry is
+  excluded the same way; its **content** is counted instead through the `scope`
+  component.
+  A **consequence** (expected cost, not a defect): **any byte change in
+  `implement.jsonl`** (appending or removing a scope entry, rewording a `reason`,
+  a domain-guide entry) **or a rewrite of a
+  referenced spec's prose invalidates an existing receipt**, requiring one more
+  review run against the final state. Appending evidence, ticking ACs, and runtime
+  metadata are not in that set.
+- **Light profile `meta.taskType: "tiny"`**: applies to `strict` tasks only
+  (`legacy` + `tiny` stays a compatibility path). A light task **is still strict**
+  — what it waives are three things: the review receipt, AC evidence, and
+  `dev_type`. It does **not** waive the file-scope gate or "AC rows
+  are non-empty" (`LIFECYCLE-AC-003`/`004` still apply). Plan-file binding is not
+  among the three, but the pre-existing field-level exemption for tiny applies, so
+  a light task does not require `planFile` either. `tiny` **can only be declared at
+  creation time** (`task next --run --task-type tiny`) with no later edit path; the
+  light profile is visible in `task next --list` (a `[light]` text marker and
+  `lightProfile` in `--json`) and in doctor's task-hygiene output. The single
+  decision source is `task_gate_profiles.is_light_task` (`strict` + the field is
+  `tiny`); the start-preflight plan-file exemption still uses the field-level
+  `declares_light_profile` so existing pre-strict tiny tasks keep behaving as
+  before. The light profile **must not** be used for a task touching runtime /
+  gates / specs — that rule rests on visibility and review, not on a machine gate.
+- Read by `cowork-implement`: see .cowork-flow/spec/contracts/subagent-dispatch.md
+- Read by `cowork-check`: same as above
+- `debug.jsonl` reference: optional; on deviation diagnosis it records the anchor
+  delta
+
+## Formal-release behavior
+
+The formal release does not auto-migrate a legacy `prd.md`. When a task is
+started, only `decision-anchor.md` is recognized as the authoritative decision
+source; if a task directory has only `prd.md` and no `decision-anchor.md`,
+`task next <dir> --run` must fail-closed and report
+`decision-anchor.md is missing or empty`.
+
+An existing legacy task needs a human to convert the `prd.md` content into
+`decision-anchor.md`, fill in `## Goal` / `## 目标` and
+`## Acceptance Criteria` / `## 验收标准`, and only then start.

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; 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.
+
+## 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"])