cowork-flow 2.4.1 → 2.4.2

package/template/.cowork-flow/scripts/services/plan_scaffold.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""Template-driven plan skeleton generation."""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from pathlib import Path
+
+from infra.paths import DIR_WORKFLOW
+
+
+PLAN_TEMPLATE_PATH = f"{DIR_WORKFLOW}/templates/plan-template.md"
+PLAN_DIRECTORY = f"{DIR_WORKFLOW}/plans"
+SLUG_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+H1_RE = re.compile(r"^#(?!#)\s+(.+?)\s*$")
+
+
+class PlanScaffoldError(RuntimeError):
+    """Raised when a plan skeleton cannot be generated."""
+
+    def __init__(self, code: str, path: Path, detail: str) -> None:
+        self.code = code
+        self.path = path
+        self.detail = detail
+        super().__init__(f"{code}: {detail}: {path}")
+
+
+class PlanScaffoldService:
+    """Create a plan file from the installed, localized plan template."""
+
+    def __init__(self, repo_root: Path) -> None:
+        self.repo_root = Path(repo_root)
+
+    def create(
+        self,
+        title: str,
+        slug: str,
+        *,
+        force: bool = False,
+        date_prefix: str | None = None,
+    ) -> Path:
+        normalized_title = title.strip()
+        normalized_slug = slug.strip()
+        if not normalized_title:
+            raise PlanScaffoldError(
+                "PLAN-NEW-TITLE-001",
+                self.repo_root,
+                "plan title is required",
+            )
+        if not SLUG_RE.match(normalized_slug):
+            raise PlanScaffoldError(
+                "PLAN-NEW-SLUG-001",
+                self.repo_root,
+                "plan slug must contain lowercase ASCII letters, digits, and hyphens",
+            )
+
+        template = self.repo_root / PLAN_TEMPLATE_PATH
+        if not template.is_file():
+            raise PlanScaffoldError(
+                "PLAN-NEW-TEMPLATE-001",
+                template,
+                "installed plan template is missing; run `cwf project sync .`",
+            )
+
+        plans_dir = self.repo_root / PLAN_DIRECTORY
+        day = date_prefix or datetime.now().strftime("%Y-%m-%d")
+        if not re.fullmatch(r"\d{4}-\d{2}-\d{2}", day):
+            raise PlanScaffoldError(
+                "PLAN-NEW-DATE-001",
+                plans_dir,
+                "plan date must use YYYY-MM-DD",
+            )
+        plan_path = plans_dir / f"{day}-{normalized_slug}.md"
+        if plan_path.exists() and not force:
+            raise PlanScaffoldError(
+                "PLAN-NEW-EXISTS-001",
+                plan_path,
+                "plan already exists; pass --force to overwrite",
+            )
+
+        try:
+            text = template.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as error:
+            raise PlanScaffoldError(
+                "PLAN-NEW-TEMPLATE-002",
+                template,
+                "installed plan template cannot be read as UTF-8",
+            ) from error
+
+        rendered = self._render_title(text, normalized_title, template)
+        try:
+            plans_dir.mkdir(parents=True, exist_ok=True)
+            with plan_path.open("w", encoding="utf-8", newline="\n") as handle:
+                handle.write(rendered)
+        except OSError as error:
+            raise PlanScaffoldError(
+                "PLAN-NEW-WRITE-001",
+                plan_path,
+                "plan file could not be written",
+            ) from error
+        return plan_path
+
+    @staticmethod
+    def _render_title(text: str, title: str, template: Path) -> str:
+        lines = text.splitlines()
+        for index, line in enumerate(lines):
+            match = H1_RE.match(line.strip())
+            if match is None:
+                continue
+            heading = match.group(1)
+            if "<功能>" in heading:
+                if title.endswith("实施计划"):
+                    lines[index] = f"# {title}"
+                else:
+                    lines[index] = f"# {heading.replace('<功能>', title)}"
+                return "\n".join(lines) + "\n"
+            if "<Feature>" in heading:
+                if title.endswith("Implementation Plan"):
+                    lines[index] = f"# {title}"
+                else:
+                    lines[index] = f"# {heading.replace('<Feature>', title)}"
+                return "\n".join(lines) + "\n"
+            raise PlanScaffoldError(
+                "PLAN-NEW-TITLE-002",
+                template,
+                "plan template title is missing the <功能>/<Feature> placeholder",
+            )
+        raise PlanScaffoldError(
+            "PLAN-NEW-TITLE-003",
+            template,
+            "plan template has no top-level title",
+        )

package/template/.cowork-flow/scripts/services/plan_schema.py

@@ -52,6 +52,15 @@ H1_RE = re.compile(r"^#(?!#)\s+(.+?)\s*$")
 H2_RE = re.compile(r"^##(?!#)\s+(.+?)\s*$")
 H3_RE = re.compile(r"^###\s+(.+?)\s*$")
 
+GOAL_LINE_RE = re.compile(r"^\*\*(?:Goal|目标):\*\*\s*(.+?)\s*$")
+GOAL_BOLD_COLON_RE = re.compile(r"^\*\*(?:Goal|目标)\*\*:\s*(.+?)\s*$")
+GOAL_TABLE_RE = re.compile(
+    r"^\|\s*\*\*(?:Goal|目标)\*\*\s*\|\s*(.+?)\s*\|\s*$"
+)
+PLAN_AC_RE = re.compile(
+    r"^\s*-\s*(?:\[[ xX]\]\s*)?(AC-\d{3})\s*[:：]\s*(.+?)\s*$"
+)
+
 
 def _language(language: str) -> str:
     return language if language in PLAN_SECTION_HEADINGS else DEFAULT_LANGUAGE
@@ -106,6 +115,37 @@ def _task_prefix_blocker(heading: str, language: str, prefix: str) -> str | None
     )
 
 
+def plan_goal(text: str) -> str | None:
+    """First machine-readable plan goal line, then the legacy table row."""
+    for raw in structural_lines(text):
+        line = raw.strip()
+        for pattern in (GOAL_LINE_RE, GOAL_BOLD_COLON_RE, GOAL_TABLE_RE):
+            match = pattern.match(line)
+            if match:
+                return match.group(1).strip()
+    return None
+
+
+def plan_acceptance_criteria(
+    text: str,
+    language: str,
+) -> list[dict[str, str]]:
+    """Acceptance rows declared by the plan, in document order."""
+    resolved = _language(language)
+    heading = PLAN_SECTION_HEADINGS[resolved][1]
+    rows: list[dict[str, str]] = []
+    for raw in _section_lines(structural_lines(text), heading):
+        match = PLAN_AC_RE.match(raw)
+        if match:
+            rows.append({"id": match.group(1), "text": match.group(2).strip()})
+    return rows
+
+
+def section_body(text: str, heading: str) -> list[str]:
+    """Raw lines under one `##` heading, excluding fenced code."""
+    return _section_lines(structural_lines(text), heading)
+
+
 def plan_template_blockers(
     text: str,
     language: str,

package/template/.cowork-flow/scripts/services/task_context.py

@@ -49,6 +49,7 @@ from services.plan_binding import (
     plan_file_blockers,
     plan_template_blockers,
 )
+from services.plan_readiness import plan_ready_snapshot_blockers
 from services.task_gate_profiles import (
     GATE_PROFILE_STRICT,
     acceptance_row_blockers,
@@ -376,6 +377,17 @@ class TaskContextService:
                 blockers.extend(
                     plan_template_blockers(self.repo_root, task_data, language)
                 )
+        if strict and not light:
+            meta = task_data.get("meta")
+            meta = meta if isinstance(meta, dict) else {}
+            blockers.extend(
+                plan_ready_snapshot_blockers(
+                    self.repo_root,
+                    task_dir,
+                    task_data,
+                    required=meta.get("planReadyRequired") is True,
+                )
+            )
         if strict:
             blockers.extend(dev_type_blocker(task_data))
         return tuple(blockers)

package/template/.cowork-flow/scripts/services/task_creation.py

@@ -6,7 +6,6 @@ from __future__ import annotations
 from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
-import re
 
 from infra.config import get_language
 from services.decision_anchor_schema import (
@@ -16,6 +15,7 @@ from services.decision_anchor_schema import (
     heading_for,
     spec_check_placeholder,
 )
+from services.plan_schema import plan_acceptance_criteria, plan_goal
 from services.task_tree import TaskTreeError, TaskTreeService
 from services import task_graph
 from infra.paths import (
@@ -24,16 +24,10 @@ from infra.paths import (
     get_tasks_dir,
 )
 from services.plan_binding import PlanBindingError, bind_plan_file
-from services.task_gate_profiles import GATE_PROFILE_STRICT
+from services.task_gate_profiles import GATE_PROFILE_STRICT, LIGHT_TASK_TYPE
 from services.task_repository import TaskRepository, TaskRepositoryError
 
 
-_GOAL_LINE_RE = re.compile(r"^\*\*(?:Goal|目标):\*\*\s*(.+?)\s*$")
-_GOAL_BOLD_COLON_RE = re.compile(r"^\*\*(?:Goal|目标)\*\*:\s*(.+?)\s*$")
-_GOAL_TABLE_RE = re.compile(
-    r"^\|\s*\*\*(?:Goal|目标)\*\*\s*\|\s*(.+?)\s*\|\s*$"
-)
-
 _ANCHOR_PLACEHOLDERS = {
     ("zh-CN", GOAL): "<!-- 用一句话描述可观察的目标。 -->",
     ("zh-CN", ACCEPTANCE): "<!-- 至少一条，例如：- [ ] AC-001: ... -->",
@@ -92,17 +86,6 @@ class TaskCreationResult:
     generated_anchor_from_plan: bool
 
 
-def _extract_plan_goal(plan_text: str) -> str | None:
-    """First machine-readable goal line, then the legacy table row."""
-    for raw in plan_text.splitlines():
-        line = raw.strip()
-        for pattern in (_GOAL_LINE_RE, _GOAL_BOLD_COLON_RE, _GOAL_TABLE_RE):
-            match = pattern.match(line)
-            if match:
-                return match.group(1).strip()
-    return None
-
-
 def _anchor_placeholder(section: str, language: str) -> str:
     return _ANCHOR_PLACEHOLDERS.get(
         (language, section),
@@ -110,6 +93,12 @@ def _anchor_placeholder(section: str, language: str) -> str:
     )
 
 
+def _render_acceptance(rows: list[dict[str, str]]) -> str:
+    return "\n".join(
+        f"- [ ] {row['id']}: {row['text']}" for row in rows
+    )
+
+
 def ensure_tasks_dir(repo_root: Path) -> Path:
     """Ensure active and archived task directories exist."""
     tasks_dir = get_tasks_dir(repo_root)
@@ -192,6 +181,10 @@ class TaskCreationService:
         created_at = request.created_at or datetime.now().strftime("%Y-%m-%d")
         meta = dict(plan_metadata) if isinstance(plan_metadata, dict) else {}
         meta.setdefault("gateProfile", GATE_PROFILE_STRICT)
+        if meta.get("gateProfile") == GATE_PROFILE_STRICT and (
+            request.task_type != LIGHT_TASK_TYPE
+        ):
+            meta["planReadyRequired"] = True
         # The light profile is declarable at creation only: this is the sole
         # write of the field, and no lifecycle command changes it later.
         if request.task_type:
@@ -368,15 +361,17 @@ class TaskCreationService:
     ) -> tuple[bool, bool]:
         """Create a language-specific anchor scaffold.
 
-        A bound plan's goal line (or legacy table row) fills the goal section;
-        otherwise the scaffold carries a localized placeholder. An anchor that
+        A bound plan's goal and AC rows fill the corresponding sections;
+        otherwise each section carries a localized placeholder. An anchor that
         already exists is never overwritten.
         """
         anchor_file = task_dir / "decision-anchor.md"
         if anchor_file.exists():
             return False, False
 
+        language = get_language(self.repo_root)
         goal: str | None = None
+        acceptance_rows: list[dict[str, str]] = []
         if plan_path is not None and plan_path.is_file():
             try:
                 plan_text = plan_path.read_text(encoding="utf-8")
@@ -386,14 +381,18 @@ class TaskCreationService:
                     plan_path,
                     "plan cannot be read as UTF-8",
                 ) from error
-            goal = _extract_plan_goal(plan_text)
+            goal = plan_goal(plan_text)
+            acceptance_rows = plan_acceptance_criteria(plan_text, language)
 
-        language = get_language(self.repo_root)
         goal_heading = heading_for(GOAL, language)
         acceptance_heading = heading_for(ACCEPTANCE, language)
         verification_heading = heading_for(VERIFICATION, language)
         goal_body = goal or _anchor_placeholder(GOAL, language)
-        acceptance_body = _anchor_placeholder(ACCEPTANCE, language)
+        acceptance_body = (
+            _render_acceptance(acceptance_rows)
+            if acceptance_rows
+            else _anchor_placeholder(ACCEPTANCE, language)
+        )
         verification_comment = (
             "<!-- strict 任务启动前：把 <dev_type> 和 "
             "<pass / not_applicable + 理由> 替换为实际核对结果；"

package/template/.cowork-flow/spec/contracts/plan-binding.md

@@ -28,6 +28,60 @@ the plan into a second workflow kernel.
 }
 ```
 
+- A newly created strict non-Tiny task also records
+  `meta.planReadyRequired: true`. Existing tasks without that marker are not
+  retroactively required to have a snapshot; if they are finalized, the
+  snapshot is recorded and validated, but a missing snapshot is not a new
+  blocker for them.
+
+## Skeleton generation
+
+- `./.cowork-flow/run plan new --title <title> --slug <slug>` reads the
+  installed localized `.cowork-flow/templates/plan-template.md` and writes a
+  plan skeleton to `.cowork-flow/plans/YYYY-MM-DD-<slug>.md`.
+- The title placeholder (`<功能>` / `<Feature>`) is replaced; the rest of the
+  template shape is preserved. The file is written as UTF-8 with LF endings.
+- An existing plan is never overwritten unless `--force` is explicit.
+- Generation is optional; a planning agent may still fill the installed
+  template directly. `plan finalize` remains the completeness gate.
+
+## Plan finalize
+
+- `./.cowork-flow/run plan finalize [task-dir]` is allowed only on a planning
+  task. It does not edit the plan or anchor.
+- It requires the bound plan, the configured-language template shape, a
+  machine-readable concrete goal line, at least one concrete `AC-NNN` row,
+  content in `## 目标` / `## 全局约束` / `## 文件边界` beyond the installed
+  template body, complete task briefs (full fields for Normal/High-risk; file
+  boundaries, verification command, and completion conditions for Tiny), a
+  concrete command inside the task's fenced verification block, a non-empty
+  `implement.jsonl`, anchor acceptance rows matching the plan IDs/text, an
+  anchor goal matching the plan goal, and the filled anchor spec-check result.
+  Template bodies are read from the installed localized template at finalize
+  time, so placeholder matching follows template changes instead of a copied
+  sentinel list.
+- On success it writes `task.json.meta.planReady`:
+
+```json
+{
+  "meta": {
+    "planReady": {
+      "planDigest": "<sha256>",
+      "anchorDigest": "<sha256>",
+      "readyAt": "2026-10-23T00:00:00Z",
+      "devType": "backend"
+    }
+  }
+}
+```
+
+- A failed finalize writes nothing. A successful finalize is the handoff point
+  for human review: the reviewer sees the complete plan and anchor.
+- A new strict non-Tiny task requires the snapshot at start. Start rejects a
+  missing snapshot and rejects any snapshot whose digests no longer match the
+  current plan or anchor; editing either file after review requires another
+  finalize and another review. Unmarked old tasks remain exempt.
+
 ## Binding during planning
 
 - A planning task not bound at creation time can bind a plan later with
@@ -66,10 +120,13 @@ into `in_progress`:
 - The strict non-Tiny anchor carries the configured-language `## 验证命令` /
   `## Verification Commands` section with the same filled spec-check result;
   see `decision-anchor.md`.
+- The plan passes `plan finalize`; the anchor acceptance IDs/text match the
+  plan, and the stored plan-ready digests still match both files.
 
 Creation and `--from-plan` binding stay permissive: a planning task may create
-and bind a plan before its structure is final. These checks run only at the
-planning → `in_progress` start gate.
+and bind a plan before its structure is final. The completeness checks run at
+`plan finalize`; the start gate repeats the structural backstop and verifies the
+reviewed snapshot.
 
 A Tiny task may have no planFile and is exempt from the plan-shape and anchor
 spec-check gates. A legacy task (no `meta.gateProfile: "strict"`) keeps the
@@ -97,11 +154,12 @@ The recovery output lists paths only and never expands the plan prose.
 
 - No parsing of plan step status.
 - No Markdown AST or DSL.
-- No comparing AC text against plan task prose.
+- No semantic validation of plan prose beyond the completeness checks above.
 - No matching verification commands against evidence records.
 - No semantic validation of the spec-check result or reason; the structural
   check only requires an actual `pass` / `not_applicable` token.
-- No plan-approval data model.
+- No approval record beyond the plan-ready digest snapshot; human approval is
+  still a process step, not a separate workflow state.
 
 These capabilities are considered only after warning noise and real payoff have been
 validated.

package/template/.cowork-flow/spec/runtime/contract-registry.json

@@ -109,7 +109,8 @@
         "Plan binding records repo-relative task.json.meta.planFile.",
         "Task start blocks clear missing plan facts for non-Tiny tasks.",
         "Strict non-Tiny start requires the configured-language plan template shape and a filled spec-check line.",
-        "V1 does not parse plan steps, AC text, or verification evidence."
+        "New strict non-Tiny tasks require a plan-ready snapshot from `plan finalize`; edits after finalize invalidate it.",
+        "V1 does not parse plan step status or verification evidence; AC text is only compared between plan and anchor."
       ],
       "readWhen": [
         "when changing task creation plan binding",

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

@@ -30,6 +30,28 @@ If the installed template is missing, stop and report it (run `cwf project sync
 
 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.
 
+### Skeleton Generation
+
+Generate the first version from the installed template instead of retyping its structure:
+
+```bash
+./.cowork-flow/run plan new --title "<plan title>" --slug <ascii-slug>
+```
+
+`plan new` replaces the title placeholder, writes `.cowork-flow/plans/YYYY-MM-DD-<slug>.md`, and refuses to overwrite an existing plan unless `--force` is explicit. Fill the generated skeleton; do not invent a second plan shape. If the installed template is missing, the command stops with a `cwf project sync .` hint.
+
+### Plan Readiness Gate
+
+After filling the plan and anchor, finalize them before human review:
+
+```bash
+./.cowork-flow/run plan finalize <task-dir>
+```
+
+`plan finalize` checks the plan and anchor for template shape, concrete section content, AC rows, complete task briefs, verification commands, matching goal/AC text, the spec-check result, and a non-empty `implement.jsonl`. On success it writes `task.json.meta.planReady` with plan/anchor digests.
+
+New strict non-Tiny tasks require this snapshot at start. Present the finalized plan and anchor for human review; start only verifies that the reviewed files have not changed. If either file changes after finalize, run `plan finalize` again and re-review before starting. Tiny and legacy tasks keep their existing exemptions.
+
 ### 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.
@@ -82,6 +104,7 @@ A plan can be marked approved only when all conditions hold:
 - 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.
+- For new strict non-Tiny tasks, the plan and anchor have passed `plan finalize` and the human has reviewed that snapshot. Any later edit requires another finalize and review.
 
 `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.
@@ -120,3 +143,4 @@ Before handoff:
 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 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.
+8. Run `plan finalize <task-dir>` and fix every reported blocker before handing the plan to the user for review.