@michaelxwb/code-flow 0.6.3 → 0.6.5

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/*",
 )
 
 
@@ -100,6 +101,7 @@ class RuleBinding:
     enforcement: str
     verifier_ref: str
     stage_status: Mapping[str, RuleStageStatus]
+    verifier_stage: str = "code"
 
 
 @dataclass(frozen=True)
@@ -805,6 +807,7 @@ def _rule_from_data(value: object, path: str) -> RuleBinding:
         _string(data.get("enforcement"), "rules[].enforcement", path),
         _string(data.get("verifier_ref"), "rules[].verifier_ref", path),
         parsed,
+        _string(data.get("verifier_stage", "code"), "rules[].verifier_stage", path),
     )
 
 
@@ -815,6 +818,7 @@ def _rule_data(rule: RuleBinding) -> dict[str, object]:
         "text_sha256": rule.text_sha256,
         "enforcement": rule.enforcement,
         "verifier_ref": rule.verifier_ref,
+        "verifier_stage": rule.verifier_stage,
         "stage_status": {stage: _stage_data(status) for stage, status in rule.stage_status.items()},
     }
 
@@ -989,7 +993,12 @@ def _binding_from_input(selection: BindingInput) -> SpecBinding:
         }
         verifier = verifier_by_rule.get(rule.ref)
         verifier_ref = f"{candidate.spec_id}#{rule.ref}" if verifier is not None else "advisory:none"
-        rules.append(RuleBinding(rule.ref, rule.text, rule.text_sha256, enforcement, verifier_ref, statuses))
+        rules.append(
+            RuleBinding(
+                rule.ref, rule.text, rule.text_sha256, enforcement, verifier_ref, statuses,
+                verifier.stage if verifier is not None else "code",
+            )
+        )
     return SpecBinding(
         candidate.spec_id,
         candidate.path,
@@ -1002,12 +1011,26 @@ def _binding_from_input(selection: BindingInput) -> SpecBinding:
     )
 
 
+def _with_declared_stages(rule: RuleBinding, stages: Sequence[str]) -> RuleBinding:
+    """兼容补齐：绑定旧版本时声明的 stages 缺状态，按声明补 pending。"""
+    missing = [stage for stage in stages if stage not in rule.stage_status]
+    if not missing:
+        return rule
+    statuses = dict(rule.stage_status)
+    for stage in missing:
+        statuses[stage] = RuleStageStatus("pending", (), None, ())
+    return replace(rule, stage_status=statuses)
+
+
 def _rule_from_metadata(spec_id: str, metadata: SpecMetadata, rule: SpecRule) -> RuleBinding:
     enforcement = "advisory" if metadata.enforcement == "advisory" else rule.enforcement
     statuses = {stage: RuleStageStatus("pending", (), None, ()) for stage in metadata.stages}
-    has_verifier = any(item.rule == rule.ref for item in metadata.verifiers)
-    verifier_ref = f"{spec_id}#{rule.ref}" if has_verifier else "advisory:none"
-    return RuleBinding(rule.ref, rule.text, rule.text_sha256, enforcement, verifier_ref, statuses)
+    verifier = next((item for item in metadata.verifiers if item.rule == rule.ref), None)
+    verifier_ref = f"{spec_id}#{rule.ref}" if verifier is not None else "advisory:none"
+    return RuleBinding(
+        rule.ref, rule.text, rule.text_sha256, enforcement, verifier_ref, statuses,
+        verifier.stage if verifier is not None else "code",
+    )
 
 
 def bind_specs(context: SpecContext, selections: Sequence[BindingInput]) -> SpecContext:
@@ -1155,14 +1178,15 @@ def _refresh_existing_rule(
     binding: SpecBinding, existing: RuleBinding, current: SpecRule, metadata: SpecMetadata
 ) -> tuple[RuleBinding, Optional[DriftChange]]:
     enforcement = "advisory" if metadata.enforcement == "advisory" else current.enforcement
-    has_verifier = any(item.rule == current.ref for item in metadata.verifiers)
-    verifier_ref = f"{binding.spec_id}#{current.ref}" if has_verifier else "advisory:none"
+    verifier = next((item for item in metadata.verifiers if item.rule == current.ref), None)
+    verifier_ref = f"{binding.spec_id}#{current.ref}" if verifier is not None else "advisory:none"
     updated = replace(
         existing,
         summary=current.text,
         text_sha256=current.text_sha256,
         enforcement=enforcement,
         verifier_ref=verifier_ref,
+        verifier_stage=verifier.stage if verifier is not None else "code",
     )
     if existing.text_sha256 == current.text_sha256:
         return updated, None
@@ -1199,6 +1223,7 @@ def _refresh_binding(
             rule, change = _refresh_existing_rule(binding, prior, current, metadata)
             if change is not None:
                 changes.append(change)
+        rule = _with_declared_stages(rule, metadata.stages)
         rule, artifact_changes = _refresh_artifacts(binding.spec_id, rule, artifact_root)
         rules.append(rule)
         changes.extend(artifact_changes)
@@ -1314,8 +1339,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 +1540,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)}
 
@@ -1564,11 +1595,13 @@ def _status_command(args: argparse.Namespace) -> dict[str, object]:
         rules = []
         for rule in binding.rules:
             status = rule.stage_status.get("code")
+            stages = {stage: item.status for stage, item in sorted(rule.stage_status.items())}
             rules.append(
                 {
                     "ref": f"{binding.spec_id}#{rule.ref}",
                     "enforcement": rule.enforcement,
                     "status": status.status if status else "missing",
+                    "stages": stages,
                     "verifier": rule.verifier_ref,
                 }
             )
@@ -1589,7 +1622,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"]
@@ -1602,7 +1635,8 @@ def _status_text(data: dict[str, object]) -> str:
     for binding in data["bindings"]:
         lines.append(f"- {binding['spec_id']}（{binding['path']}）— {binding['status']}")
         for rule in binding["rules"]:
-            lines.append(f"  {rule['status']:<12} {rule['ref']}（{rule['verifier']}）")
+            stage_text = " ".join(f"{stage}={value}" for stage, value in rule.get("stages", {}).items())
+            lines.append(f"  {stage_text:<24} {rule['ref']}（{rule['verifier']}）")
     return "\n".join(lines)
 
 
@@ -1643,6 +1677,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] = []
@@ -95,9 +116,11 @@ def _binding_issues(
         status = rule.stage_status.get(stage)
         if status is None:
             continue
+        if stage in ("code", "review") and getattr(rule, "verifier_stage", "code") != stage:
+            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 +136,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_metadata.py

@@ -15,6 +15,7 @@ from typing import Mapping, Optional
 ALLOWED_STAGES = frozenset(("prd", "design", "plan", "code", "review"))
 ALLOWED_ENFORCEMENT = frozenset(("required", "advisory"))
 ALLOWED_VERIFIERS = frozenset(("document", "regex", "ast", "command", "test", "manual"))
+ALLOWED_VERIFIER_STAGES = frozenset(("code", "review"))
 _ID_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
 _RULE_ID_RE = re.compile(r"^RULE-[a-z0-9]+(?:-[a-z0-9]+)*-\d{3}$")
 _EXPLICIT_RULE_RE = re.compile(r"^\[(RULE-[a-z0-9-]+-\d{3})\]\s+(.+)$")
@@ -52,6 +53,8 @@ class SpecVerifier:
     rule: str
     type: str
     config: Mapping[str, object]
+    stage: str = "code"
+    files: tuple[str, ...] = ()
 
 
 @dataclass(frozen=True)
@@ -209,7 +212,26 @@ def _validate_checks(meta: Mapping[str, object], path: str, raw: str) -> tuple[M
     return tuple(value)
 
 
-def _parse_verifiers(meta: Mapping[str, object], path: str, raw: str) -> tuple[SpecVerifier, ...]:
+def _parse_verifier_files(value: object, path: str, raw: str, index: int) -> tuple[str, ...]:
+    line = _verifier_field_line(raw, index, "files")
+    if not isinstance(value, list) or not value:
+        raise SpecMetadataError(path, f"verifiers[{index}].files", line, "必须是非空 glob 字符串数组")
+    files: list[str] = []
+    for item in value:
+        if not isinstance(item, str) or not item.strip():
+            raise SpecMetadataError(path, f"verifiers[{index}].files", line, "glob 必须是非空字符串")
+        text = item.strip().replace("\\", "/")
+        if text.startswith("/") or re.match(r"^[A-Za-z]:/", text):
+            raise SpecMetadataError(path, f"verifiers[{index}].files", line, f"禁止绝对路径: {item!r}")
+        if ".." in text.split("/"):
+            raise SpecMetadataError(path, f"verifiers[{index}].files", line, f"禁止 .. 跳出仓库: {item!r}")
+        files.append(text)
+    return tuple(files)
+
+
+def _parse_verifiers(
+    meta: Mapping[str, object], path: str, raw: str, stages: tuple[str, ...]
+) -> tuple[SpecVerifier, ...]:
     value = meta.get("verifiers", [])
     if not isinstance(value, list) or not all(isinstance(item, dict) for item in value):
         raise SpecMetadataError(path, "verifiers", _field_line(raw, "verifiers"), "必须是 mapping 列表")
@@ -219,6 +241,8 @@ def _parse_verifiers(meta: Mapping[str, object], path: str, raw: str) -> tuple[S
         rule = item.get("rule")
         kind = item.get("type")
         config = item.get("config")
+        explicit_stage = "stage" in item
+        stage = item.get("stage", "code")
         if not isinstance(rule, str) or not _RULE_ID_RE.fullmatch(rule):
             line = _verifier_field_line(raw, index, "rule")
             raise SpecMetadataError(path, f"verifiers[{index}].rule", line, "必须是稳定 RULE ID")
@@ -228,10 +252,17 @@ def _parse_verifiers(meta: Mapping[str, object], path: str, raw: str) -> tuple[S
         if not isinstance(config, dict):
             line = _verifier_field_line(raw, index, "config")
             raise SpecMetadataError(path, f"verifiers[{index}].config", line, "必须是 mapping")
+        if explicit_stage and (not isinstance(stage, str) or stage not in ALLOWED_VERIFIER_STAGES):
+            line = _verifier_field_line(raw, index, "stage")
+            raise SpecMetadataError(path, f"verifiers[{index}].stage", line, f"必须是 {sorted(ALLOWED_VERIFIER_STAGES)} 之一")
+        if explicit_stage and stage not in stages:
+            line = _verifier_field_line(raw, index, "stage")
+            raise SpecMetadataError(path, f"verifiers[{index}].stage", line, f"stage {stage!r} 未在 stages 声明: {', '.join(stages)}")
+        files = _parse_verifier_files(item["files"], path, raw, index) if "files" in item else ()
         if rule in seen:
             raise SpecMetadataError(path, "verifiers", _field_line(raw, "verifiers"), f"重复 verifier: {rule}")
         seen.add(rule)
-        result.append(SpecVerifier(rule=rule, type=kind, config=config))
+        result.append(SpecVerifier(rule=rule, type=kind, config=config, stage=stage, files=files))
     return tuple(result)
 
 
@@ -324,7 +355,7 @@ def parse_spec_metadata(content: str, path: str = "<memory>", raw_bytes: Optiona
     if owner is not None and (not isinstance(owner, str) or not owner.strip()):
         raise SpecMetadataError(path, "owner", _field_line(raw_frontmatter, "owner"), "必须是非空字符串")
     checks = _validate_checks(meta, path, raw_frontmatter)
-    verifiers = _parse_verifiers(meta, path, raw_frontmatter)
+    verifiers = _parse_verifiers(meta, path, raw_frontmatter, header.stages)
     body_line_offset = raw_frontmatter.count("\n") + 3
     rules = _parse_rules(body, path, body_line_offset)
     _validate_links(rules, verifiers, path, raw_frontmatter)

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_spec_verify.py

@@ -4,7 +4,7 @@
 from __future__ import annotations
 
 import ast
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from datetime import datetime, timezone
 import fnmatch
 import hashlib
@@ -59,19 +59,94 @@ def _cache_file(root: str) -> Path:
     return Path(root) / ".code-flow" / ".verifier-cache.json"
 
 
-def _cache_key(metadata: SpecMetadata, rule: SpecRule, verifier: SpecVerifier, scope: VerificationScope, confirmation: Optional[Mapping[str, object]]) -> str:
+def _cache_key(metadata: SpecMetadata, rule: SpecRule, verifier: SpecVerifier, scope: VerificationScope, confirmation: Optional[Mapping[str, object]], stage: str = "code") -> str:
     payload = {
         "spec": metadata.hashes.file_sha256,
         "rule": rule.text_sha256,
         "verifier": {"type": verifier.type, "config": verifier.config},
         "files": scope.files,
         "diff": scope.diff_sha256,
+        "stage": stage,
         "confirmation": confirmation or {},
         "artifact_content": _artifact_fingerprint(verifier, scope),
     }
     return hashlib.sha256(json.dumps(payload, ensure_ascii=False, sort_keys=True, default=str).encode()).hexdigest()
 
 
+def _normalize_scope_path(value: str) -> str:
+    return value.replace("\\", "/").strip()
+
+
+def _matches_scope(path: str, patterns: Sequence[str]) -> bool:
+    for pattern in patterns:
+        if fnmatch.fnmatchcase(path, pattern):
+            return True
+        bare = pattern.rstrip("/")
+        if not any(char in pattern for char in "*?[") and path.startswith(bare + "/"):
+            return True
+    return False
+
+
+def _git_tracked_files(root: str) -> tuple[str, ...]:
+    try:
+        outcome = subprocess.run(
+            ("git", "ls-files"), cwd=root, text=True, encoding="utf-8", capture_output=True, check=False
+        )
+    except OSError:
+        return ()
+    if outcome.returncode != 0:
+        return ()
+    return tuple(_normalize_scope_path(line) for line in outcome.stdout.splitlines() if line.strip())
+
+
+def scoped_files(verifier: SpecVerifier, scope: VerificationScope) -> tuple[str, ...]:
+    """作用域命中的文件集合：git tracked ∪ 任务持有文件，按 verifier.files 过滤。
+
+    决议仓库级集合（而非仅当前任务 diff）才能让未触及作用域的其他任务命中缓存。
+    """
+    if not verifier.files:
+        return ()
+    candidates = {_normalize_scope_path(item) for item in scope.files if item.strip()}
+    candidates.update(_git_tracked_files(scope.root))
+    return tuple(sorted(path for path in candidates if _matches_scope(path, verifier.files)))
+
+
+def _scope_fingerprint(root: str, files: Sequence[str]) -> str:
+    digest = hashlib.sha256()
+    for relative in files:
+        path = Path(root) / relative
+        digest.update(relative.encode("utf-8"))
+        try:
+            digest.update(path.read_bytes() if path.is_file() else b"<deleted>")
+        except OSError:
+            digest.update(b"<unreadable>")
+    return digest.hexdigest()
+
+
+def _scoped_cache_key(
+    metadata: SpecMetadata,
+    rule: SpecRule,
+    verifier: SpecVerifier,
+    scope: VerificationScope,
+    confirmation: Optional[Mapping[str, object]],
+    stage: str,
+) -> Optional[str]:
+    """command/test 仅在声明 files 作用域时缓存；未声明保持全量执行。"""
+    if verifier.type not in ("command", "test") or not verifier.files:
+        return None
+    files = scoped_files(verifier, scope)
+    payload = {
+        "spec": metadata.hashes.file_sha256,
+        "rule": rule.text_sha256,
+        "verifier": {"type": verifier.type, "config": verifier.config, "files": list(verifier.files)},
+        "stage": stage,
+        "scope_files": files,
+        "scope_sha256": _scope_fingerprint(scope.root, files),
+        "confirmation": confirmation or {},
+    }
+    return hashlib.sha256(json.dumps(payload, ensure_ascii=False, sort_keys=True, default=str).encode()).hexdigest()
+
+
 def _artifact_fingerprint(verifier: SpecVerifier, scope: VerificationScope) -> Optional[str]:
     if verifier.type != "document":
         return None
@@ -143,13 +218,32 @@ def _cached_or_run(
     verifier: SpecVerifier,
     scope: VerificationScope,
     confirmation: Optional[Mapping[str, object]],
+    stage: str = "code",
 ) -> VerificationEvidence:
     cacheable = verifier.type in _PURE_VERIFIER_TYPES
-    key = _cache_key(metadata, rule, verifier, scope, confirmation) if cacheable else ""
+    scoped_key: Optional[str] = None
+    if cacheable:
+        key = _cache_key(metadata, rule, verifier, scope, confirmation, stage)
+    else:
+        scoped_key = _scoped_cache_key(metadata, rule, verifier, scope, confirmation, stage)
+        if scoped_key is None:
+            key = ""
+        else:
+            cacheable, key = True, scoped_key
     if cacheable:
         cached = _cached_evidence(key)
         if cached is not None:
-            return cached
+            if scoped_key is None:
+                return cached
+            details = dict(cached.details or {})
+            details["cache_reused"] = True
+            details["scope_files"] = list(scoped_files(verifier, scope))
+            return replace(
+                cached,
+                executed_at=datetime.now(timezone.utc).isoformat(),
+                diff_sha256=scope.diff_sha256,
+                details=details,
+            )
     current = _evidence(metadata, rule, verifier, scope, confirmation)
     if cacheable and current.status == "verified":
         _save_result_cache(key, current)
@@ -400,6 +494,7 @@ def _run_all_verifiers(
     confirmations: Optional[Mapping[str, Mapping[str, object]]] = None,
     skip_command: bool = False,
     timeout_budget: Optional[float] = None,
+    stage: str = "code",
 ) -> VerificationResult:
     verifier_by_rule = {item.rule: item for item in metadata.verifiers}
     confirmation_by_rule = confirmations or {}
@@ -410,12 +505,14 @@ def _run_all_verifiers(
     for rule in metadata.rules:
         if rule.enforcement != "required":
             continue
+        verifier = verifier_by_rule.get(rule.ref)
+        if verifier is not None and verifier.stage != stage:
+            continue
         if timeout_budget is not None:
             remaining = timeout_budget - (time.monotonic() - started)
             if remaining <= 0:
                 evidence_by_ref[rule.ref] = _budget_evidence(metadata, rule, scope, timeout_budget)
                 continue
-        verifier = verifier_by_rule.get(rule.ref)
         if verifier is None:
             evidence_by_ref[rule.ref] = _missing_evidence(metadata, rule, scope)
             continue
@@ -427,11 +524,11 @@ def _run_all_verifiers(
             parallel.append((rule, verifier, confirmation))
             continue
         cap = None if timeout_budget is None else max(0.1, timeout_budget - (time.monotonic() - started))
-        evidence_by_ref[rule.ref] = _cached_or_run(metadata, rule, verifier, scope, confirmation) if cap is None else _evidence(metadata, rule, verifier, scope, confirmation, cap)
+        evidence_by_ref[rule.ref] = _cached_or_run(metadata, rule, verifier, scope, confirmation, stage) if cap is None else _evidence(metadata, rule, verifier, scope, confirmation, cap)
     if parallel:
         with ThreadPoolExecutor(max_workers=min(8, len(parallel))) as pool:
             futures = {
-                rule.ref: pool.submit(_cached_or_run, metadata, rule, verifier, scope, confirmation)
+                rule.ref: pool.submit(_cached_or_run, metadata, rule, verifier, scope, confirmation, stage)
                 for rule, verifier, confirmation in parallel
             }
             evidence_by_ref.update({ref: future.result() for ref, future in futures.items()})
@@ -442,9 +539,10 @@ def _run_all_verifiers(
 
 def run_all_verifiers(metadata: SpecMetadata, scope: VerificationScope,
                       confirmations: Optional[Mapping[str, Mapping[str, object]]] = None,
-                      skip_command: bool = False, timeout_budget: Optional[float] = None) -> VerificationResult:
+                      skip_command: bool = False, timeout_budget: Optional[float] = None,
+                      stage: str = "code") -> VerificationResult:
     with execution_session():
-        return _run_all_verifiers(metadata, scope, confirmations, skip_command, timeout_budget)
+        return _run_all_verifiers(metadata, scope, confirmations, skip_command, timeout_budget, stage)
 
 
 def evidence_is_fresh(

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 并行派发",
     }