cowork-flow 2.4.0 → 2.4.2

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
@@ -51,9 +105,32 @@ into `in_progress`:
 - `decision-anchor.md` contains `## Goal`/`## 目标` and
   `## Acceptance Criteria`/`## 验收标准`.
 - `implement.jsonl` passes the existing context validation.
-
-A Tiny task may have no planFile, but must still satisfy the existing anchor and
-implement-scope requirements.
+- For a strict non-Tiny task, the plan title contains the configured-language
+  marker (`实施计划` / `Implementation Plan`).
+- The plan contains the six configured-language `##` template headings in
+  template order: `目标` / `验收标准` / `全局约束` / `文件边界` / `任务` /
+  `最终验证`, or their `en-US` equivalents. Extra custom sections are allowed;
+  fenced code is ignored; a known template heading from the other language is
+  rejected.
+- Any `### 任务` / `### Task` task heading uses the configured-language prefix.
+- `## 最终验证` / `## Final Verification` contains a line starting with
+  `规范核对：` / `Spec check:` and carrying an actual `pass` or
+  `not_applicable` result. The template placeholder (`<pass / not_applicable +
+  理由>` / `<pass / not_applicable + reason>`) does not satisfy the gate.
+- 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. 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
+historical checks; this contract does not retro-fit either profile.
 
 ## Implementation recovery
 
@@ -77,9 +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 plan-approval data model.
+- No semantic validation of the spec-check result or reason; the structural
+  check only requires an actual `pass` / `not_applicable` token.
+- 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

@@ -108,7 +108,9 @@
       "digest": [
         "Plan binding records repo-relative task.json.meta.planFile.",
         "Task start blocks clear missing plan facts for non-Tiny tasks.",
-        "V1 does not parse plan steps, AC text, or verification evidence."
+        "Strict non-Tiny start requires the configured-language plan template shape and a filled spec-check line.",
+        "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/.cowork-flow/templates/plan-template.md

@@ -71,7 +71,7 @@ Tiny 任务可保留简化 brief，但仍须写明精确文件边界、完成条
 <command>
 ```
 
-当改动文件受 `.cowork-flow/spec/<dev_type>/` 规则覆盖时，在这里加入决定命令或规范门禁核对行（`pass` / `not_applicable` 并附理由）；这是强复核提醒，不是硬门禁。
+当改动文件受 `.cowork-flow/spec/<dev_type>/` 规则覆盖时，在这里加入决定命令或规范门禁核对行（`pass` / `not_applicable` 并附理由）。strict 非 Tiny 任务启动前必须把 `<pass / not_applicable + 理由>` 替换为实际核对结果；保留模板占位符会被 start 门禁阻断。
 
 **完成条件**
 - <2-4 条可检查条件>

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

@@ -49,7 +49,7 @@ and the left column the `zh-CN` output.
 | `## 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) |
+| `## Verification Commands` / `## 验证命令` | required for strict non-Tiny; optional for legacy/Tiny | filled in for complex tasks, as the basis for automated verification; a strict non-Tiny task also needs the configured-language section and a filled 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)
 
@@ -60,11 +60,13 @@ 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.
+  evidence. A strict non-Tiny task must also carry a `Spec check:` line in the
+  configured language's section, with the actual `pass` / `not_applicable` result
+  and a reason. The template placeholder (`<pass / not_applicable + reason>`) does
+  not satisfy the start gate. This line is a hard start gate for strict non-Tiny
+  tasks, while its content remains self-declared and is reviewed by the check
+  agent. The fact view recognizes the line and does not return it as a shell
+  command.
 - `## Scope Boundary`: only the first non-empty line is taken, truncated to 160
   characters.
 
@@ -99,6 +101,13 @@ After merging (5 files): `decision-anchor.md` + `implement.jsonl` + `check.jsonl
   `## 验收标准`, 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).
+- A strict non-Tiny task also requires the configured-language
+  `## Verification Commands` / `## 验证命令` section with a filled
+  `Spec check:` / `规范核对：` line. A missing section, the other-language
+  heading, or the template placeholder blocks start. Tiny tasks and legacy tasks
+  are exempt. The bound plan's `## Final Verification` / `## 最终验证` section
+  carries the same filled check; plan structure and language are covered by
+  `plan-binding.md`.
 - 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

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

@@ -71,7 +71,7 @@ Tiny plans may keep a shorter brief, but must still name exact file boundaries,
 <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.
+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>

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.
@@ -49,7 +71,7 @@ Fill the template in order: header table and goal first, then acceptance criteri
 - 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`.
@@ -81,7 +103,8 @@ 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.
+- 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.
@@ -118,5 +141,6 @@ Before handoff:
 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.
+8. Run `plan finalize <task-dir>` and fix every reported blocker before handing the plan to the user for review.