@michaelxwb/code-flow 0.6.3 → 0.6.4

package/src/cli.js

@@ -237,6 +237,56 @@ function mergeSettingsJson(srcFile, destFile) {
   return added;
 }
 
+// OpenCode v2 merge: migrate the v1 `plugin` key to `plugins`, drop the
+// auto-discovered local path (`.opencode/plugins/*` loads without config),
+// and union template `plugins` entries without overwriting user content.
+function mergeOpencodeJson(srcFile, destFile) {
+  const src = JSON.parse(fs.readFileSync(srcFile, 'utf8'));
+  const dest = JSON.parse(fs.readFileSync(destFile, 'utf8'));
+  const added = [];
+  const isLocalEntry = (e) => {
+    const p = typeof e === 'string' ? e : (e && e.package);
+    return typeof p === 'string' && /(^|\/)\.opencode\/plugins\//.test(p);
+  };
+  if (Array.isArray(dest.plugin)) {
+    const carried = dest.plugin.filter((e) => !isLocalEntry(e));
+    delete dest.plugin;
+    added.push(`removed legacy 'plugin' key (v1 → v2)`);
+    if (carried.length > 0 && !Array.isArray(dest.plugins)) dest.plugins = carried;
+  } else if ('plugin' in dest) {
+    delete dest.plugin;
+    added.push(`removed legacy 'plugin' key (v1 → v2)`);
+  }
+  if (Array.isArray(dest.plugins)) {
+    const before = dest.plugins.length;
+    dest.plugins = dest.plugins.filter((e) => !isLocalEntry(e));
+    if (dest.plugins.length !== before) added.push('removed auto-discovered local plugin entry');
+  }
+  if (Array.isArray(src.plugins)) {
+    if (!Array.isArray(dest.plugins)) dest.plugins = [];
+    const seen = new Set(dest.plugins.map((e) => JSON.stringify(e)));
+    for (const entry of src.plugins) {
+      const key = JSON.stringify(entry);
+      if (!seen.has(key)) {
+        dest.plugins.push(entry);
+        seen.add(key);
+        added.push(`plugins +${typeof entry === 'string' ? entry : key}`.slice(0, 80));
+      }
+    }
+  }
+  for (const key of Object.keys(src)) {
+    if (key === 'plugins' || key === 'plugin') continue;
+    if (!(key in dest)) {
+      dest[key] = src[key];
+      added.push(key);
+    }
+  }
+  if (added.length > 0) {
+    fs.writeFileSync(destFile, JSON.stringify(dest, null, 2) + '\n');
+  }
+  return added;
+}
+
 function mergeConfigYml(srcFile, destFile) {
   const srcText = fs.readFileSync(srcFile, 'utf8');
   const destText = fs.readFileSync(destFile, 'utf8');
@@ -781,7 +831,7 @@ function runInit(force, platform, opts) {
       dest: path.join(cwd, 'opencode.json'),
       label: 'opencode.json',
       mode: platformMode,
-      mergeFn: mergeSettingsJson,
+      mergeFn: mergeOpencodeJson,
       toolOnUpgrade: false,
       results,
     });

package/src/core/code-flow/config.yml

@@ -24,7 +24,8 @@ budget:
 quality_loop:
     enabled: true
     post_check: true            # PostToolUse 违规反馈（只提示不阻断）
-    stop_check: true            # Stop 收尾按 validation.yml 校验
+    stop_check: true            # Stop 收尾按 validation.yml 校验（heavy 项跳过）
+    finish_check: true          # 任务 finish 时全量执行 validation.yml（含 heavy，每任务一次）
     correction_capture: true    # 纠正句式采集（喂 cf-learn 候选）
     # 注入时对 spec 内容做保守无损压缩（去行尾空白、折叠多空行、剥 HTML 注释、去重 bullet）
     # 缺省视为 true；仅显式 false 关闭

package/src/core/code-flow/scripts/cf_acceptance_manifest.py

@@ -10,7 +10,7 @@ import shlex
 from pathlib import Path
 import re
 import sys
-from typing import IO, Mapping, Optional, Sequence
+from typing import IO, Callable, Mapping, Optional, Sequence
 
 from cf_acceptance_schema import load_manifest, validate_scenarios
 
@@ -26,12 +26,18 @@ def _kind(level: str) -> str:
     - functional: auto-executed in Done Gate (unit, integration)
     - e2e: deferred until explicit --verify-e2e (needs external dependencies)
     - manual: user confirmation required, never auto-executed
+
+    层级单元格允许带注解（如 `E2E（Playwright）`、`e2e/chrome`、`manual(chrome)`），
+    取分隔符前的词元判定；避免带注解的 E2E 被误判为 functional 而每任务执行。
     """
-    normalized = level.strip().lower()
-    if normalized == "manual":
+    head = level.strip().lower()
+    for separator in ("(", "（", "[", "/", ",", "，", " ", "—", "-"):
+        head = head.split(separator, 1)[0]
+    head = head.strip()
+    if head in ("manual", "手工", "手动"):
         return "manual"
-    if normalized == "e2e":
-        return "e2e"  # Keep as separate kind, not functional
+    if head in ("e2e", "端到端", "end"):
+        return "e2e"
     return "functional"
 
 
@@ -70,7 +76,17 @@ def _manifest_hash(rows: list[dict[str, object]]) -> str:
     return hashlib.sha256(payload).hexdigest()
 
 
-def extract_manifest(task_file: str) -> dict[str, object]:
+def _legacy_kind(level: str) -> str:
+    """v1 精确匹配：仅用于识别旧版锁定的 manifest，不做新语义判定。"""
+    normalized = level.strip().lower()
+    if normalized == "manual":
+        return "manual"
+    if normalized == "e2e":
+        return "e2e"
+    return "functional"
+
+
+def _extract_rows(task_file: str, kind_fn: Callable[[str], str]) -> dict[str, object]:
     path = Path(task_file)
     text = path.read_text(encoding="utf-8")
     rows: list[dict[str, object]] = []
@@ -98,7 +114,7 @@ def extract_manifest(task_file: str) -> dict[str, object]:
             "id": match.group(1),
             "source": fields[0],
             "level": fields[1],
-            "kind": _kind(fields[1]),
+            "kind": kind_fn(fields[1]),
             "boundary": fields[2],
             "owner": fields[3],
             "status": fields[4],
@@ -113,6 +129,10 @@ def extract_manifest(task_file: str) -> dict[str, object]:
     return {"schema": _MANIFEST_SCHEMA, "task_file": str(path), "task_sha256": _manifest_hash(rows), "scenarios": rows}
 
 
+def extract_manifest(task_file: str, kind_fn: Callable[[str], str] = _kind) -> dict[str, object]:
+    return _extract_rows(task_file, kind_fn)
+
+
 def write_manifest(task_file: str, output: str) -> dict[str, object]:
     manifest = extract_manifest(task_file)
     target = Path(output)
@@ -130,14 +150,40 @@ _IMMUTABLE_SCENARIO_FIELDS = (
 )
 
 
+def _heal_legacy_kinds(manifest_file: Path, manifest: dict[str, object], expected: dict[str, object]) -> None:
+    """旧版 `_kind` 精确匹配把带注解的 E2E 锁成 functional；任务内容未变时
+    原地升级 kind 并重锁哈希，保留 execution evidence 等运行态字段。"""
+    by_id: dict[str, dict[str, object]] = {}
+    scenarios = expected.get("scenarios")
+    if isinstance(scenarios, list):
+        for item in scenarios:
+            if isinstance(item, dict) and isinstance(item.get("id"), str):
+                by_id[item["id"]] = item
+    current = manifest.get("scenarios")
+    if isinstance(current, list):
+        for item in current:
+            if not isinstance(item, dict):
+                continue
+            target = by_id.get(item.get("id")) if isinstance(item.get("id"), str) else None
+            if target is not None:
+                item["kind"] = target.get("kind")
+    manifest["task_sha256"] = expected["task_sha256"]
+    manifest_file.write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
 def validate_manifest(task_file: str, manifest_file: str) -> tuple[bool, str]:
     try:
         manifest = load_manifest(Path(manifest_file))
         expected = extract_manifest(task_file)
     except (OSError, ValueError, json.JSONDecodeError) as exc:
         return False, f"acceptance_manifest_invalid: {exc}"
-    if manifest.get("schema") != _MANIFEST_SCHEMA or manifest.get("task_sha256") != expected["task_sha256"]:
+    if manifest.get("schema") != _MANIFEST_SCHEMA:
         return False, "acceptance_manifest_drift"
+    if manifest.get("task_sha256") != expected["task_sha256"]:
+        legacy = extract_manifest(task_file, _legacy_kind)
+        if manifest.get("task_sha256") != legacy["task_sha256"]:
+            return False, "acceptance_manifest_drift"
+        _heal_legacy_kinds(Path(manifest_file), manifest, expected)
     stored_task = manifest.get("task_file", "")
     if not stored_task or (Path(manifest_file).parent / stored_task).resolve() != Path(task_file).resolve():
         return False, "acceptance_manifest_task_mismatch"

package/src/core/code-flow/scripts/cf_core.py

@@ -55,6 +55,31 @@ def normalize_path(path: str) -> str:
     return path.replace("\\", "/")
 
 
+def effective_project_root(project_root: str, absolute_path: str) -> str:
+    """Resolve the project root that owns an edited file.
+
+    Parallel subagents edit `.code-flow/worktrees/<run>/<TASK>/...`; the nearest
+    `.code-flow` ancestor is that worktree's root, not the session root. Files
+    outside the session root and unresolvable paths fall back to `project_root`.
+    Lexical `abspath` (not `realpath`) keeps caller/returned paths in the same
+    coordinates (macOS /var ↔ /private/var symlink).
+    """
+    root = os.path.abspath(project_root)
+    target = os.path.abspath(absolute_path) if absolute_path else root
+    if target != root and not target.startswith(root + os.sep):
+        return root
+    current = target
+    while True:
+        if os.path.isdir(os.path.join(current, ".code-flow")):
+            return current
+        if current == root:
+            return root
+        parent = os.path.dirname(current)
+        if parent == current:
+            return root
+        current = parent
+
+
 def _spec_path_from_entry(entry) -> str:
     cfg = normalize_spec_entry(entry)
     return normalize_path(cfg.get("path", ""))
@@ -474,7 +499,8 @@ def resolve_quality_loop(config: dict) -> dict:
     """
     if not isinstance(config, dict):
         return {"enabled": False, "post_check": False,
-                "stop_check": False, "correction_capture": False,
+                "stop_check": False, "finish_check": False,
+                "correction_capture": False,
                 "compress_reminder": False}
     cfg = config.get("quality_loop")
     cfg = cfg if isinstance(cfg, dict) else {}
@@ -487,6 +513,7 @@ def resolve_quality_loop(config: dict) -> dict:
         "enabled": enabled,
         "post_check": _sub("post_check"),
         "stop_check": _sub("stop_check"),
+        "finish_check": _sub("finish_check"),
         "correction_capture": _sub("correction_capture"),
         "compress_reminder": _sub("compress_reminder"),
     }

package/src/core/code-flow/scripts/cf_post_hook.py

@@ -31,6 +31,7 @@ from cf_checks import (
 from cf_core import (
     _log,
     build_effective_mapping,
+    effective_project_root,
     ensure_utf8_io,
     is_code_file,
     load_config,
@@ -107,7 +108,10 @@ def main() -> None:
         if not isinstance(file_path, str) or not file_path:
             return
 
-        project_root = os.getcwd()
+        session_root = os.getcwd()
+        abs_path = file_path if os.path.isabs(file_path) else os.path.join(session_root, file_path)
+        # 并行子 agent 在 .code-flow/worktrees/... 内编辑时路由到该 worktree 的规格与状态
+        project_root = effective_project_root(session_root, abs_path)
         config = load_config(project_root)
         if not config:
             return
@@ -117,9 +121,6 @@ def main() -> None:
         if not quality_loop["post_check"]:
             return
 
-        abs_path = file_path
-        if not os.path.isabs(abs_path):
-            abs_path = os.path.join(project_root, file_path)
         rel_path = normalize_path(os.path.relpath(abs_path, project_root))
         sid = resolve_session_id(data)
         cf_log.append_event(project_root, "edit", {"file": rel_path, "tool": tool_name}, sid)

package/src/core/code-flow/scripts/cf_pre_tool_hook.py

@@ -11,7 +11,16 @@ from pathlib import Path
 import sys
 
 import cf_log
-from cf_core import _log, ensure_utf8_io, load_config, normalize_path, resolve_enforcement, resolve_session_id, timing_log
+from cf_core import (
+    _log,
+    effective_project_root,
+    ensure_utf8_io,
+    load_config,
+    normalize_path,
+    resolve_enforcement,
+    resolve_session_id,
+    timing_log,
+)
 from cf_session_state import load_session_state, save_session_state
 from cf_spec_context import injection_version, load_active_task, load_context
 from cf_spec_resolver import resolve_candidate_headers
@@ -49,11 +58,13 @@ def main() -> None:
         file_path = (data.get("tool_input") or {}).get("file_path", "")
         if tool_name not in {"Edit", "Write", "MultiEdit"} or not isinstance(file_path, str) or not file_path:
             return
-        root = os.getcwd()
+        session_root = os.getcwd()
+        absolute = file_path if os.path.isabs(file_path) else os.path.join(session_root, file_path)
+        # 并行子 agent 在 .code-flow/worktrees/... 内编辑时路由到该 worktree 的上下文
+        root = effective_project_root(session_root, absolute)
         sid = resolve_session_id(data)
         config = load_config(root)
         enforcement = resolve_enforcement(config) if config else "required"
-        absolute = file_path if os.path.isabs(file_path) else os.path.join(root, file_path)
         relative = normalize_path(os.path.relpath(absolute, root))
         try:
             expanded = _active_expansion(root, relative)

package/src/core/code-flow/scripts/cf_spec_context.py

@@ -42,6 +42,7 @@ DEFAULT_ACTIVE_EXCLUDES = (
     ".code-flow/.session-log.jsonl",
     ".code-flow/.active-task.json",
     ".code-flow/.active-task.lock",
+    ".code-flow/worktrees/*",
 )
 
 
@@ -1314,8 +1315,15 @@ def apply_artifact_ref(
 
 def _json_payload(stream: IO[str]) -> Mapping[str, object]:
     try:
-        loaded = json.load(stream)
-    except (json.JSONDecodeError, UnicodeError) as exc:
+        raw = stream.read()
+    except (OSError, UnicodeError) as exc:
+        raise ContextError("invalid_json", "stdin", str(exc)) from exc
+    if not raw.strip():
+        # 空 stdin = 无 payload（例如 active doctor --resync 全参数走 CLI 开关）。
+        return {}
+    try:
+        loaded = json.loads(raw)
+    except json.JSONDecodeError as exc:
         raise ContextError("invalid_json", "stdin", str(exc)) from exc
     return _mapping(loaded, "stdin", "")
 
@@ -1508,12 +1516,11 @@ def _active_command(args: argparse.Namespace, payload: Mapping[str, object]) ->
             except WorkflowError as exc:
                 raise _reraise(exc) from exc
     else:
-        result = doctor_active_task(
-            args.root,
-            args.context_sha256,
-            payload.get("abandon") is True,
-            payload.get("resync") is True,
-        )
+        abandon = payload.get("abandon") is True or args.abandon
+        resync = payload.get("resync") is True or args.resync
+        if abandon and resync:
+            raise ContextError("conflicting_recovery", "doctor", "abandon 与 resync 不能同时使用", args.task_dir)
+        result = doctor_active_task(args.root, args.context_sha256, abandon, resync)
         return {"ok": True, "action": result.action, "active": _active_data(result.active)}
     return {"ok": True, "active": _active_data(active)}
 
@@ -1589,7 +1596,7 @@ def _status_text(data: dict[str, object]) -> str:
         match = "✓ 一致" if marker["hash_match"] else "✗ 漂移"
         lines.append(f"- TASK {marker['task_id']}（{marker['status']}），marker hash {match}")
         if not marker["hash_match"]:
-            lines.append("  下一步: 运行 cf-spec doctor（resync 可自动重同步）")
+            lines.append("  下一步: 运行 cf-spec refresh 自动重同步 marker hash；仍不一致时用 active doctor --resync（hash 取本命令 --json 的 context_sha256）")
     else:
         lines.append("- 无 active TASK（path/catalog 路由模式）")
     gate = data["gate"]
@@ -1643,6 +1650,9 @@ def _parser() -> argparse.ArgumentParser:
         command.add_argument("--task", required=True)
         command.add_argument("--context-sha256", required=True)
         command.add_argument("--json", action="store_true")
+        if action == "doctor":
+            command.add_argument("--abandon", action="store_true", help="确认放弃无法证明的 marker（需用户确认）")
+            command.add_argument("--resync", action="store_true", help="用 --context-sha256 重新绑定 marker 并恢复 active")
     start = commands.add_parser("start")
     start.add_argument("--task-dir", required=True)
     start.add_argument("--root", required=True)

package/src/core/code-flow/scripts/cf_spec_gate.py

@@ -74,11 +74,28 @@ def _evidence_issue(rule: RuleBinding, status: RuleStageStatus, diff_sha256: Opt
     return "stale_evidence"
 
 
-def _status_issue(rule: RuleBinding, status: RuleStageStatus, now: datetime, diff_sha256: Optional[str]) -> Optional[str]:
+def _cheap_skip(status: RuleStageStatus) -> bool:
+    """Latest evidence is a cheap-gate skip (command/test verifier deferred)."""
+    if not status.evidence:
+        return False
+    latest = status.evidence[-1]
+    return isinstance(latest, Mapping) and latest.get("error_code") == "skipped_in_cheap_gate"
+
+
+def _status_issue(
+    rule: RuleBinding,
+    status: RuleStageStatus,
+    now: datetime,
+    diff_sha256: Optional[str],
+    allow_cheap_skips: bool = False,
+) -> Optional[str]:
     if status.status == "applied":
         return None
     if status.status == "verified":
         return _evidence_issue(rule, status, diff_sha256)
+    if allow_cheap_skips and status.status == "unverified" and _cheap_skip(status):
+        # 轻量门禁（stop 阶段）：命令类 verifier 未执行属预期，留给 finish 全量门禁。
+        return None
     if status.status == "not_applicable":
         return None if _decision_valid(status.decision) else "decision_invalid"
     if status.status == "waived":
@@ -87,7 +104,11 @@ def _status_issue(rule: RuleBinding, status: RuleStageStatus, now: datetime, dif
 
 
 def _binding_issues(
-    binding: SpecBinding, stage: str, now: datetime, diff_sha256: Optional[str]
+    binding: SpecBinding,
+    stage: str,
+    now: datetime,
+    diff_sha256: Optional[str],
+    allow_cheap_skips: bool = False,
 ) -> tuple[list[GateIssue], list[GateIssue]]:
     errors: list[GateIssue] = []
     warnings: list[GateIssue] = []
@@ -97,7 +118,7 @@ def _binding_issues(
             continue
         if rule.enforcement == "advisory" and status.status == "pending":
             continue
-        code = "missing_spec" if binding.status == "missing" else _status_issue(rule, status, now, diff_sha256)
+        code = "missing_spec" if binding.status == "missing" else _status_issue(rule, status, now, diff_sha256, allow_cheap_skips)
         if code is None:
             continue
         issue = GateIssue(code, binding.spec_id, rule.ref, stage, f"{binding.spec_id}#{rule.ref}: {code}")
@@ -113,13 +134,14 @@ def validate_stage(
     task_id: str = "",
     now: Optional[datetime] = None,
     diff_sha256: Optional[str] = None,
+    allow_cheap_skips: bool = False,
 ) -> GateResult:
     del artifact, task_id
     current = now or datetime.now(timezone.utc)
     errors: list[GateIssue] = []
     warnings: list[GateIssue] = []
     for binding in context.bindings:
-        binding_errors, binding_warnings = _binding_issues(binding, stage, current, diff_sha256)
+        binding_errors, binding_warnings = _binding_issues(binding, stage, current, diff_sha256, allow_cheap_skips)
         errors.extend(binding_errors)
         warnings.extend(binding_warnings)
     refs = tuple(sorted({f"{item.spec_id}#{item.rule_ref}" for item in (*errors, *warnings)}))

package/src/core/code-flow/scripts/cf_spec_router.py

@@ -137,7 +137,7 @@ def _active_route(root: str) -> RouteResult:
     if current_hash != active.context_sha256:
         raise RouterError(
             "active_context_drift",
-            "active marker Context hash does not match; run `cf-spec doctor` (resync) to re-sync the marker before continuing",
+            "active marker Context hash does not match; run `cf_spec_context.py refresh --task-dir <dir> --root <root> --json` to re-sync it (refresh updates the marker hash), or `active doctor --resync` with the hash from `status --json`",
         )
     cached = _cached_projection(root, task_dir, active.task_id, current_hash)
     if cached is None:

package/src/core/code-flow/scripts/cf_stop_hook.py

@@ -96,6 +96,34 @@ def session_edited_files(project_root: str, sid: str) -> list:
     return files
 
 
+def _root_scoped_files(project_root: str, files: list) -> list:
+    """Drop worktree-internal / outside-root paths.
+
+    Parallel subagents edit another working copy (.code-flow/worktrees/<run>/<TASK>/);
+    those paths must not trigger this root's validators.
+    """
+    root = os.path.realpath(project_root)
+    scoped = []
+    for rel in files:
+        path = normalize_path(rel)
+        if path.startswith(".code-flow/worktrees/"):
+            continue
+        absolute = os.path.realpath(os.path.join(root, path))
+        if absolute == root or absolute.startswith(root + os.sep):
+            scoped.append(rel)
+    return scoped
+
+
+def _stop_validators(project_root: str) -> list:
+    """Per-stop validators: heavy entries (full tests / e2e suites) are skipped
+    on every Stop and only run via the explicit `cf-validate` command (or CI)."""
+    return [
+        validator
+        for validator in load_validators(project_root)
+        if not (isinstance(validator, dict) and validator.get("heavy") is True)
+    ]
+
+
 def _is_active_task_file(rel_path: str) -> bool:
     path = normalize_path(rel_path)
     if not path.startswith(".code-flow/tasks/") or "/archived/" in path:
@@ -294,7 +322,7 @@ def _main() -> None:
                 active = load_active_task(project_root)
                 task_dir = os.path.join(project_root, active.task_dir)
                 gate_remaining = deadline - time.monotonic()
-                done = run_done_gate(project_root, task_dir, budget=min(GATE_BUDGET_SECONDS, max(gate_remaining, 0.01)))
+                done = run_done_gate(project_root, task_dir, cheap=True, budget=min(GATE_BUDGET_SECONDS, max(gate_remaining, 0.01)))
             except (OSError, ValueError) as exc:
                 if enforcement == "required":
                     payload = {"decision": "block", "reason": f"SPEC_WORKFLOW_BLOCKED: active task is invalid: {exc}"}
@@ -316,11 +344,11 @@ def _main() -> None:
         if not resolve_quality_loop(config)["stop_check"]:
             return
         if not has_active:
-            files = session_edited_files(project_root, sid)
+            files = _root_scoped_files(project_root, session_edited_files(project_root, sid))
         if not files:
             return
         acceptance_failures = task_acceptance_failures(project_root, files)
-        validators = load_validators(project_root)
+        validators = _stop_validators(project_root)
         failures, truncated = run_validators(
             project_root, validators, files, sid, deadline=deadline
         ) if validators else ([], False)

package/src/core/code-flow/scripts/cf_task_index.py

@@ -1,9 +1,10 @@
 #!/usr/bin/env python3
 """Programmatic task-file index: parse TASK statuses/depends, compute DAG batches.
 
-Single worktrees allow one active TASK at a time, so "parallel" below means
-*independently developable* (no dependency path between them) — not
-simultaneously activatable, a distinction `cf-task:graph` used to blur.
+Single worktrees allow one active TASK at a time; batches list *independently
+developable* tasks (no dependency path between them). `cf-task:start` may
+dispatch batch tasks in their own worktrees for parallel subagents — the
+single-active constraint stays per worktree.
 """
 
 from __future__ import annotations
@@ -116,7 +117,7 @@ def index_data(task_file: str) -> dict[str, object]:
         "batches": task_batches(nodes),
         "independent_groups": independent_groups(nodes),
         "dependency_components": dependency_components(nodes),
-        "note": "batches 组内无依赖；dependency_components 仅组间独立（independent_groups 为兼容别名）；单 worktree 一次仅激活一个 TASK",
+        "note": "batches 组内无依赖；dependency_components 仅组间独立（independent_groups 为兼容别名）；单 worktree 一次仅激活一个 TASK，批次内独立任务可由 cf-task:start 在各 worktree 并行派发",
     }