cowork-flow 0.0.39 → 0.0.41

package/template/.cowork-flow/scripts/common/gates/gates.py

@@ -28,6 +28,7 @@ STAGE_GATES = {
         "complexity",
     ),
     "task_complete": (
+        "implementation",
         "tdd_evidence",
         "test_intent",
         "runtime_rules",
@@ -37,9 +38,8 @@ STAGE_GATES = {
 }
 
 
-def build_default_registry() -> GateRegistry:
-    registry = GateRegistry()
-    for binding in (
+def _validator_bindings() -> tuple[ValidatorBinding, ...]:
+    return (
         ValidatorBinding(
             key="runtime_rules",
             module="validate_rules",
@@ -79,10 +79,11 @@ def build_default_registry() -> GateRegistry:
             function="validate_complexity_signals",
             positional=("repo_root", "task_dir"),
         ),
-    ):
-        registry.register_validator(binding)
+    )
+
 
-    definitions = (
+def _gate_definitions() -> tuple[GateDefinition, ...]:
+    return (
         GateDefinition(
             id="runtime_rules",
             validator_key="runtime_rules",
@@ -94,7 +95,7 @@ def build_default_registry() -> GateRegistry:
             id="implementation",
             validator_key="implementation",
             required=True,
-            block_message="Implementation gate blocked task review",
+            block_message="Implementation gate blocked lifecycle transition",
             warning_message="Implementation violations detected",
         ),
         GateDefinition(
@@ -124,7 +125,13 @@ def build_default_registry() -> GateRegistry:
             warning_message="Complexity review warnings",
         ),
     )
-    for definition in definitions:
+
+
+def build_default_registry() -> GateRegistry:
+    registry = GateRegistry()
+    for binding in _validator_bindings():
+        registry.register_validator(binding)
+    for definition in _gate_definitions():
         registry.register_gate(definition)
     return registry
 
@@ -151,61 +158,57 @@ def _pipeline_violation(
     ).to_dict()
 
 
+def _normalize_violation(
+    raw_violation: object,
+    context: GateContext,
+    definition: GateDefinition,
+) -> dict:
+    if not isinstance(raw_violation, Mapping):
+        return _pipeline_violation(
+            rule_id="GATE-PROTOCOL-001",
+            context=context,
+            definition=definition,
+            message=f"Gate {definition.id} returned a non-object violation",
+            fix_hint="Return violation dictionaries with stable metadata.",
+        )
+    try:
+        return Violation.from_mapping(
+            raw_violation,
+            scope=context.scope,
+            gate_id=definition.id,
+        ).to_dict()
+    except ValueError as error:
+        return _pipeline_violation(
+            rule_id="GATE-PROTOCOL-001",
+            context=context,
+            definition=definition,
+            message=f"Gate {definition.id} returned invalid metadata: {error}",
+            fix_hint="Return violations with rule_id, severity, and message.",
+        )
+
+
 def _normalize_violations(
     raw_result: object,
     context: GateContext,
     definition: GateDefinition,
 ) -> list[dict]:
-    if not isinstance(raw_result, list):
+    if isinstance(raw_result, list):
         return [
-            _pipeline_violation(
-                rule_id="GATE-PROTOCOL-001",
-                context=context,
-                definition=definition,
-                message=(
-                    f"Gate {definition.id} returned "
-                    f"{type(raw_result).__name__}; expected a list of violations"
-                ),
-                fix_hint="Return list[dict] from the registered gate validator.",
-            )
+            _normalize_violation(item, context, definition)
+            for item in raw_result
         ]
-
-    normalized: list[dict] = []
-    for raw_violation in raw_result:
-        if not isinstance(raw_violation, Mapping):
-            normalized.append(
-                _pipeline_violation(
-                    rule_id="GATE-PROTOCOL-001",
-                    context=context,
-                    definition=definition,
-                    message=(
-                        f"Gate {definition.id} returned a non-object violation"
-                    ),
-                    fix_hint="Return violation dictionaries with stable metadata.",
-                )
-            )
-            continue
-        try:
-            normalized.append(
-                Violation.from_mapping(
-                    raw_violation,
-                    scope=context.scope,
-                    gate_id=definition.id,
-                ).to_dict()
-            )
-        except ValueError as error:
-            normalized.append(
-                _pipeline_violation(
-                    rule_id="GATE-PROTOCOL-001",
-                    context=context,
-                    definition=definition,
-                    message=f"Gate {definition.id} returned invalid metadata: {error}",
-                    fix_hint=(
-                        "Return violations with rule_id, severity, and message."
-                    ),
-                )
-            )
-    return normalized
+    return [
+        _pipeline_violation(
+            rule_id="GATE-PROTOCOL-001",
+            context=context,
+            definition=definition,
+            message=(
+                f"Gate {definition.id} returned "
+                f"{type(raw_result).__name__}; expected a list of violations"
+            ),
+            fix_hint="Return list[dict] from the registered gate validator.",
+        )
+    ]
 
 
 class GatePipeline:
@@ -214,62 +217,65 @@ class GatePipeline:
     def __init__(self, registry: GateRegistry | None = None) -> None:
         self.registry = registry or build_default_registry()
 
-    def run(self, context: GateContext) -> GateResult:
-        executions: list[GateExecution] = []
-        priority_violations: list[dict] = []
-        ordinary_violations: list[dict] = []
-
-        for gate_id in STAGE_GATES[context.scope]:
-            definition = self.registry.gate(gate_id)
-            try:
-                raw_result = self.registry.invoke(definition, context)
-            except GateLoadError as error:
-                violations = [
-                    _pipeline_violation(
-                        rule_id="GATE-LOAD-001",
-                        context=context,
-                        definition=definition,
-                        message=f"Gate {definition.id} could not load: {error}",
-                        fix_hint=(
-                            "Restore the required validator module and function."
-                        ),
-                    )
-                ]
-            except Exception as error:
-                violations = [
-                    _pipeline_violation(
-                        rule_id="GATE-EXEC-001",
-                        context=context,
-                        definition=definition,
-                        message=f"Gate {definition.id} failed during execution: {error}",
-                        fix_hint=(
-                            "Fix the validator exception; lifecycle gates fail closed."
-                        ),
-                    )
-                ]
-            else:
-                violations = _normalize_violations(
-                    raw_result,
-                    context,
-                    definition,
+    def _execute_gate(
+        self,
+        context: GateContext,
+        gate_id: str,
+    ) -> GateExecution:
+        definition = self.registry.gate(gate_id)
+        try:
+            raw_result = self.registry.invoke(definition, context)
+        except GateLoadError as error:
+            violations = [
+                _pipeline_violation(
+                    rule_id="GATE-LOAD-001",
+                    context=context,
+                    definition=definition,
+                    message=f"Gate {definition.id} could not load: {error}",
+                    fix_hint="Restore the required validator module and function.",
                 )
-
-            gate_result = GateResult.from_violations(
+            ]
+        except Exception as error:
+            violations = [
+                _pipeline_violation(
+                    rule_id="GATE-EXEC-001",
+                    context=context,
+                    definition=definition,
+                    message=f"Gate {definition.id} failed during execution: {error}",
+                    fix_hint="Fix the validator exception; lifecycle gates fail closed.",
+                )
+            ]
+        else:
+            violations = _normalize_violations(raw_result, context, definition)
+        return GateExecution(
+            definition=definition,
+            result=GateResult.from_violations(
                 context.scope,
                 violations,
                 context.task_dir,
-            )
-            executions.append(
-                GateExecution(
-                    definition=definition,
-                    result=gate_result,
-                )
-            )
-            for violation in gate_result.violations:
-                if str(violation.get("rule_id", "")).startswith("GATE-"):
-                    priority_violations.append(violation)
-                else:
-                    ordinary_violations.append(violation)
+            ),
+        )
+
+    def run(self, context: GateContext) -> GateResult:
+        executions = [
+            self._execute_gate(context, gate_id)
+            for gate_id in STAGE_GATES[context.scope]
+        ]
+        violations = [
+            violation
+            for execution in executions
+            for violation in execution.result.violations
+        ]
+        priority_violations = [
+            violation
+            for violation in violations
+            if str(violation.get("rule_id", "")).startswith("GATE-")
+        ]
+        ordinary_violations = [
+            violation
+            for violation in violations
+            if not str(violation.get("rule_id", "")).startswith("GATE-")
+        ]
 
         return GateResult(
             scope=context.scope,

package/template/.cowork-flow/scripts/common/gates/validate_implementation.py

@@ -18,6 +18,8 @@ import subprocess
 import sys
 from pathlib import Path
 
+from common.git.git_snapshot import collect_changed_paths
+
 try:
     from .validate_rules import (
         config_violation,
@@ -71,7 +73,15 @@ def validate_implementation(
         )
     )
     violations.extend(_check_premature_abstraction(repo_root, diff_output, rule_index))
-    violations.extend(_check_unrequested_features(repo_root, diff_output, task_dir, rule_index))
+    violations.extend(
+        _check_unrequested_features(
+            repo_root,
+            diff_output,
+            task_dir,
+            rule_index,
+            modified_files=modified_files,
+        )
+    )
 
     return violations
 
@@ -86,38 +96,44 @@ def _missing_rule(repo_root: Path, rule_id: str) -> dict:
 
 
 def _get_modified_files(repo_root: Path) -> list[str]:
-    """Get git-tracked modified files under repo_root."""
-    try:
-        result = subprocess.run(
-            ["git", "diff", "--name-only", "--", "."],
-            cwd=repo_root,
-            capture_output=True,
-            text=True,
-            encoding="utf-8",
-            errors="replace",
-        )
-        if result.returncode == 0:
-            return [file_path for file_path in result.stdout.strip().split("\n") if file_path]
-        return []
-    except Exception:
-        return []
+    """Get staged, unstaged, and untracked files under repo_root."""
+    changed_files = collect_changed_paths(repo_root)
+    return [
+        file_path
+        for file_path in changed_files
+        if _is_implementation_relevant(file_path)
+    ]
+
+
+def _is_implementation_relevant(file_path: str) -> bool:
+    normalized = file_path.replace("\\", "/")
+    if not normalized.startswith(".cowork-flow/"):
+        return True
+    return (
+        normalized.startswith(".cowork-flow/spec/")
+        or normalized == ".cowork-flow/workflow.md"
+    )
 
 
 def _get_git_diff(repo_root: Path, files: list[str]) -> str:
-    """Get git diff output"""
+    """Get unstaged and staged diff output for changed files."""
     if not files:
         return ""
 
     try:
-        diff_result = subprocess.run(
-            ["git", "diff", "--", *files],
-            cwd=repo_root,
-            capture_output=True,
-            text=True,
-            encoding="utf-8",
-            errors="replace",
-        )
-        return diff_result.stdout
+        outputs = []
+        for extra_args in ((), ("--cached",)):
+            diff_result = subprocess.run(
+                ["git", "diff", *extra_args, "--", *files],
+                cwd=repo_root,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+            )
+            if diff_result.returncode == 0:
+                outputs.append(diff_result.stdout)
+        return "\n".join(outputs)
     except Exception:
         return ""
 
@@ -229,6 +245,8 @@ def _check_unrequested_features(
     diff_output: str,
     task_dir: Path,
     rule_index: dict[str, dict],
+    *,
+    modified_files: list[str] | None = None,
 ) -> list[dict]:
     """R-AG-005: Require modified files to be explicitly listed."""
     del diff_output
@@ -242,8 +260,12 @@ def _check_unrequested_features(
         return violations
 
     # Get modified project files (exclude .cowork-flow/ metadata)
-    modified_files = _get_modified_files(repo_root)
-    for file_path in modified_files:
+    changed_files = (
+        modified_files
+        if modified_files is not None
+        else _get_modified_files(repo_root)
+    )
+    for file_path in changed_files:
         # Skip .cowork-flow metadata files and template files
         if ".cowork-flow/" in file_path:
             continue

package/template/.cowork-flow/scripts/common/git/git_snapshot.py

@@ -19,6 +19,14 @@ class ChangedFile:
 
 def collect_changed_files(repo_root: Path) -> list[ChangedFile]:
     """Return modified, staged, and untracked files from git status."""
+    prefix_rc, prefix_stdout, _ = _run_git_command(
+        ["rev-parse", "--show-prefix"],
+        cwd=repo_root,
+    )
+    if prefix_rc != 0:
+        return []
+    repo_prefix = prefix_stdout.strip().replace("\\", "/")
+
     rc, stdout, _ = _run_git_command(
         ["status", "--porcelain=v1", "-uall", "--", "."],
         cwd=repo_root,
@@ -32,6 +40,12 @@ def collect_changed_files(repo_root: Path) -> list[ChangedFile]:
         if parsed is None:
             continue
         path, statuses = parsed
+        if repo_prefix:
+            if not path.startswith(repo_prefix):
+                continue
+            path = path[len(repo_prefix):]
+        if not path:
+            continue
         changed.setdefault(path, set()).update(statuses)
 
     return [

package/template/.cowork-flow/spec/protocols/decision-review.md

@@ -2,18 +2,39 @@
 
 > Internal protocol enforced by workflow readiness; it is not a public Skill.
 
+## Purpose
+
+`decision-review` is the mandatory L2 evidence gate for non-trivial decisions.
+It preserves the adversarial doubt cycle from `doubt-review` while keeping the
+runtime authority in `decision-review.jsonl`.
+
 ## Enforcement
 
 - L2 tasks: mandatory before task start.
 - L0/L1 tasks: advisory and never blocked by missing decision review evidence.
 - The runtime authority is `decision-review.jsonl`; prose notes do not satisfy the gate.
 
+## Doubt Cycle
+
+Every accepted L2 decision review must be derived from this bounded cycle:
+
+1. CLAIM: state the decision and why being wrong would be costly.
+2. EXTRACT: isolate the minimal reviewable artifact or design statement.
+3. DOUBT: ask a fresh context to find problems in ARTIFACT + CONTRACT, not CLAIM.
+4. RECONCILE: classify each finding as contract misunderstanding, actionable,
+   accepted trade-off, or noise.
+5. STOP: stop after trivial or already-considered findings, three cycles, or the
+   user explicitly says enough.
+
+The reviewer receives ARTIFACT + CONTRACT, not CLAIM. CLAIM is recorded for
+traceability, but it must not bias the adversarial review prompt.
+
 ## Evidence
 
 Write one UTF-8 JSON object per line to `<task>/decision-review.jsonl`:
 
 ```json
-{"acceptanceId":"AC-007A","claim":"The selected direction is safe.","contract":"The invariant that must hold.","reviewerContext":"fresh","findings":[],"resolution":"accepted"}
+{"acceptanceId":"AC-007A","claim":"The selected direction is safe.","contract":"The invariant that must hold.","reviewerContext":"fresh","findings":[],"resolution":"accepted","artifact":"Focused diff or design statement reviewed via ARTIFACT + CONTRACT.","reconciliation":[],"cycleCount":1}
 ```
 
 Required fields:
@@ -25,4 +46,10 @@ Required fields:
 - `findings`: JSON array
 - `resolution`: exactly `accepted`
 
+Recommended fields:
+
+- `artifact`: minimal EXTRACT artifact reviewed.
+- `reconciliation`: how each finding was classified.
+- `cycleCount`: number of completed doubt cycles, never greater than 3.
+
 Missing, malformed, stale-context, or unaccepted records block L2 task start.

package/template/.cowork-flow/spec/protocols/spec-maintenance.md

@@ -8,6 +8,25 @@ Update `.cowork-flow/spec/` when a change introduces or changes a reusable comma
 
 Do not add one-off implementation narration. Prefer the narrowest existing spec and update its index when a new topic is introduced.
 
+## Choose Location
+
+- `backend/` or `frontend/`: implementation contracts, signatures, examples, validation behavior, and test points.
+- `guides/`: short thinking checklists and pointers to deeper specs.
+- `contracts/`: cross-agent, runtime, host-adapter, or persisted-state contracts.
+- `runtime/` or `schemas/`: machine-readable rules, registries, and schema-owned metadata.
+- `workflow.md` or `AGENTS.md`: process rules, phase gates, collaboration rules, or task routing behavior.
+
+## Write
+
+Keep each update concrete:
+
+- State the trigger and scope.
+- Show the contract or command shape.
+- Include good/bad cases when useful.
+- State tests or checks that protect the behavior.
+- Update the matching `index.md` when adding a new topic.
+- Check for duplicate guidance and remove stale wording before finishing.
+
 ## Output
 
 Every Host reports `specUpdates` as one of:

package/template/.cowork-flow/spec/protocols/tdd.md

@@ -28,3 +28,16 @@ Write one JSON object per line to `<task>/tdd.jsonl` with:
 - `greenCommand`, `greenExitCode`, `broaderVerification`
 
 Only docs/comment/format-only work may use a documented `exemption`.
+
+## Anti-Rationalization
+
+The following excuses do not exempt the TDD evidence requirement:
+
+| Excuse | Why It Fails | Required Alternative |
+|---|---|---|
+| "This logic is simple, no test needed" | Simple logic still breaks on edge cases and later edits. | Write the smallest behavior test for the acceptance ID. |
+| "Other tests already cover this" | Invisible coverage is not red-green evidence. | Point to the exact redCommand and acceptanceId in `tdd.jsonl`. |
+| "I'll add tests after implementation" | Post-implementation tests are not a red-green cycle. | Red first, then green; record both commands. |
+| "It looks correct" | Visual inspection misses scenarios that tests can pin down. | Turn the expected behavior and edge case into assertions. |
+| "I've written similar tests" | Similar structure is not the same behavior. | Re-run the redCommand for this acceptanceId. |
+| "This is internal only" | Internal behavior still affects callers and workflow state. | Test through the public entry point, or directly test the internal contract when that is the narrowest stable surface. |

package/template/.cowork-flow/spec/references/definition-of-done.md

@@ -10,7 +10,7 @@
 | G2 | L1/L2: tdd.jsonl 有 red-green evidence | ./cowork-flow/run task validate |
 | G3 | check phase 完成，无 unresolved blocker | check.jsonl status=pass |
 | G4 | 无新引入 lint/type/build 警告 | lint / build 命令通过 |
-| G5 | git diff 仅含任务相关变更 | git diff --name-only |
+| G5 | Git status snapshot 仅含任务相关变更，包括 staged、unstaged、untracked | git status --porcelain=v1 -uall |
 
 ## L0 专属（docs/format/comments only）
 

package/template/.cowork-flow/spec/runtime/host-assets.json

@@ -190,7 +190,6 @@
       ".agents/skills/before-dev",
       ".agents/skills/check",
       ".agents/skills/continue",
-      ".agents/skills/doubt-review",
       ".agents/skills/entry-boundary",
       ".agents/skills/finish-work",
       ".agents/skills/party-mode-v2",
@@ -201,7 +200,6 @@
       ".claude/skills/before-dev",
       ".claude/skills/check",
       ".claude/skills/continue",
-      ".claude/skills/doubt-review",
       ".claude/skills/entry-boundary",
       ".claude/skills/finish-work",
       ".claude/skills/party-mode-v2",

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

@@ -149,12 +149,40 @@
       "source": ".cowork-flow/spec/protocols/decision-review.md",
       "managedPaths": []
     },
+    {
+      "id": "doubt-review",
+      "displayName": "Doubt Review",
+      "aliases": [
+        "adversarial-review"
+      ],
+      "kind": "protocol",
+      "visibility": "public",
+      "status": "active",
+      "statuses": [
+        "planning",
+        "in_progress",
+        "review",
+        "delegated_subtask"
+      ],
+      "intents": [
+        "doubt_review"
+      ],
+      "enforcement": "advisory",
+      "runtimeGate": null,
+      "runtimeCommand": null,
+      "evidenceArtifact": "decision-review.jsonl",
+      "source": "skills/doubt-review/SKILL.md",
+      "managedPaths": [
+        ".agents/skills/doubt-review/",
+        ".claude/skills/doubt-review/"
+      ]
+    },
     {
       "id": "game-design",
       "displayName": "Game Design",
       "aliases": [],
       "kind": "domain",
-      "visibility": "internal",
+      "visibility": "public",
       "status": "active",
       "statuses": [
         "planning",

package/template/.cowork-flow/workflow.md

@@ -216,7 +216,7 @@ L2 任务在 `task start` 前必须通过 readiness gate；同一 blocker 列表
     - 所有声明通过的验证都有命令输出依据。
     - 规格已更新，或明确判断无需更新。
     - 计划状态、任务状态、`change` 元数据不冲突。
-    - 先归档，再记录会话，然后提交。
+    - 先归档并提交实现，再用真实实现提交哈希记录会话；会话元数据使用 follow-up metadata commit 提交。
     - 不纳入无关脏改。
 
 2. 顺序：
@@ -226,11 +226,15 @@ L2 任务在 `task start` 前必须通过 readiness gate；同一 blocker 列表
     git diff --check
     npm run test:all
     ./.cowork-flow/run task archive <task-name>
-    ./.cowork-flow/run add-session --title "<title>" --commit "-" --summary "<summary>"
     git status --short
     git add <expected files>
     git commit -m "<message>"
+    implementation_commit="$(git rev-parse HEAD)"
+    ./.cowork-flow/run add-session --title "<title>" --commit "$implementation_commit" --summary "<summary>"
+    git add .cowork-flow/workspace/<developer>/
+    git commit -m "docs(session): record <title>"
     ```
+   第二个提交是明确的 follow-up metadata commit；session 中的 `commit` 始终指向前一个真实实现提交，不使用永久占位值。
    `task archive <task-name>` 会归档 task，并自动归档 `change.yaml.task`
    指向该 task 的 active change；无法通过 `change validate` 的 change 不会被自动归档。
 

package/template/.zcode/.zcode-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 ZCode。",
   "author": {
     "name": "fisklikewater"

package/template/.zcode/scaffold/.cowork-flow/workflow.md

@@ -216,7 +216,7 @@ L2 任务在 `task start` 前必须通过 readiness gate；同一 blocker 列表
     - 所有声明通过的验证都有命令输出依据。
     - 规格已更新，或明确判断无需更新。
     - 计划状态、任务状态、`change` 元数据不冲突。
-    - 先归档，再记录会话，然后提交。
+    - 先归档并提交实现，再用真实实现提交哈希记录会话；会话元数据使用 follow-up metadata commit 提交。
     - 不纳入无关脏改。
 
 2. 顺序：
@@ -226,11 +226,15 @@ L2 任务在 `task start` 前必须通过 readiness gate；同一 blocker 列表
     git diff --check
     npm run test:all
     ./.cowork-flow/run task archive <task-name>
-    ./.cowork-flow/run add-session --title "<title>" --commit "-" --summary "<summary>"
     git status --short
     git add <expected files>
     git commit -m "<message>"
+    implementation_commit="$(git rev-parse HEAD)"
+    ./.cowork-flow/run add-session --title "<title>" --commit "$implementation_commit" --summary "<summary>"
+    git add .cowork-flow/workspace/<developer>/
+    git commit -m "docs(session): record <title>"
     ```
+   第二个提交是明确的 follow-up metadata commit；session 中的 `commit` 始终指向前一个真实实现提交，不使用永久占位值。
    `task archive <task-name>` 会归档 task，并自动归档 `change.yaml.task`
    指向该 task 的 active change；无法通过 `change validate` 的 change 不会被自动归档。