@michaelxwb/code-flow 0.6.2 → 0.6.4

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

@@ -18,7 +18,7 @@ from cf_spec_metadata import (
 )
 
 
-SCOPE_PRIORITY = {"global": 1, "path": 2, "task": 3}
+SCOPE_PRIORITY = {"unmatched": 0, "global": 1, "path": 2, "task": 3}
 _config_cache: dict[str, tuple[int, int, Mapping[str, object]]] = {}
 _metadata_cache: dict[str, tuple[int, int, SpecMetadata]] = {}
 
@@ -174,7 +174,12 @@ def _candidate_scope(relative: str, patterns: Sequence[str], paths: Sequence[str
     if relative.startswith("_session/"):
         return "task", ()
     matched = tuple(path for path in paths if any(fnmatch.fnmatch(path, pattern) for pattern in patterns))
-    return ("path", matched) if matched else ("global", ())
+    if matched:
+        return "path", matched
+    # A domain without patterns is truly global. A domain WITH patterns that
+    # match nothing is irrelevant to these paths ("unmatched") — discovery
+    # keeps it, but injection and scope expansion must not consume it.
+    return ("global", ()) if not patterns else ("unmatched", ())
 
 
 def _candidate_for(

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:
@@ -162,6 +162,8 @@ def _read_candidates(root: str, paths: Sequence[str], compress: bool = True) ->
         raise RouterError("invalid_spec_metadata", str(exc)) from exc
     specs = []
     for candidate in candidates:
+        if candidate.scope == "unmatched":
+            continue
         target = Path(root) / ".code-flow/specs" / candidate.path
         try:
             raw = target.read_text(encoding="utf-8")

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

@@ -36,7 +36,8 @@ def _task_section(text: str, task_id: str) -> str:
 
 
 def _refs(section: str) -> tuple[str, ...]:
-    match = re.search(r"(?m)^- \*\*Spec-Refs\*\*:\s*(.+)$", section)
+    # [ \t]* 而非 \s*：空 Spec-Refs 不得跨行吞掉下一字段（Acceptance-Refs 等）
+    match = re.search(r"(?m)^- \*\*Spec-Refs\*\*:[ \t]*(.*)$", section)
     if match is None:
         raise ValueError("spec_refs_missing")
     return tuple(item.strip() for item in match.group(1).split(",") if item.strip())
@@ -83,7 +84,7 @@ def project_task_session(
         if len(header + "".join(lines) + candidate + footer) > max_chars:
             break
         lines.append(candidate)
-    truncated = len(lines) < len(refs)
+    truncated = len(lines) < len(refs) or len(header + "".join(lines) + footer) > max_chars
     if truncated:
         footer = "\n> 投影超过预算；完整 Context 保留在需求目录，请拆分 TASK。\n" + footer
     text = (header + "".join(lines) + footer)[:max_chars]

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

@@ -18,6 +18,7 @@ from typing import Mapping, Optional, Sequence
 
 from cf_checks import run_regex_verifier
 from cf_spec_metadata import SpecMetadata, SpecRule, SpecVerifier
+from cf_exec_base import execution_session, run_command
 
 
 _RESULT_CACHE: dict[str, dict[str, object]] = {}
@@ -66,10 +67,23 @@ def _cache_key(metadata: SpecMetadata, rule: SpecRule, verifier: SpecVerifier, s
         "files": scope.files,
         "diff": scope.diff_sha256,
         "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 _artifact_fingerprint(verifier: SpecVerifier, scope: VerificationScope) -> Optional[str]:
+    if verifier.type != "document":
+        return None
+    relative = verifier.config.get("artifact")
+    if not isinstance(relative, str):
+        return "invalid"
+    try:
+        return hashlib.sha256((Path(scope.root) / relative).read_bytes()).hexdigest()
+    except OSError as exc:
+        return f"unreadable:{exc}"
+
+
 def _load_result_cache(root: str) -> None:
     global _RESULT_CACHE_ROOT, _RESULT_CACHE, _RESULT_CACHE_DIRTY
     if _RESULT_CACHE_ROOT == root:
@@ -266,30 +280,22 @@ def _command(config: Mapping[str, object], scope: VerificationScope, timeout_cap
     cwd = _config_string(config, "cwd") or "."
     timeout_value = config.get("timeout", 30)
     timeout = float(timeout_value) if isinstance(timeout_value, (int, float)) else 30.0
-    if timeout_cap is not None:
-        timeout = min(timeout, timeout_cap)
     allowed_value = config.get("allowed_exit_codes", [0])
     allowed = tuple(item for item in allowed_value if isinstance(item, int)) if isinstance(allowed_value, list) else (0,)
-    try:
-        completed = subprocess.run(
-            argv,
-            cwd=str(Path(scope.root) / cwd),
-            capture_output=True,
-            text=True,
-            timeout=timeout,
-            check=False,
-        )
-    except subprocess.TimeoutExpired:
+    deadline = None if timeout_cap is None else time.monotonic() + timeout_cap
+    completed = run_command(argv, str(Path(scope.root) / cwd), timeout, deadline)
+    if completed["status"] in ("timeout", "deadline_exceeded"):
         return _Outcome(False, "verifier_timeout", None, {"timeout": timeout, "argv": argv})
-    except OSError as exc:
-        return _Outcome(False, "command_unavailable", None, {"argv": argv, "error": str(exc)})
+    if completed["status"] == "spawn_error":
+        return _Outcome(False, "command_unavailable", None, {"argv": argv, "error": completed["stderr"]})
     details = {
         "argv": argv,
-        "exit_code": completed.returncode,
-        "stdout_sha256": _hash_bytes(completed.stdout.encode()),
-        "stderr_sha256": _hash_bytes(completed.stderr.encode()),
+        "exit_code": completed["returncode"],
+        "stdout_sha256": _hash_bytes(str(completed["stdout"]).encode()),
+        "stderr_sha256": _hash_bytes(str(completed["stderr"]).encode()),
+        "output": (str(completed["stdout"]) + str(completed["stderr"]))[-4000:],
     }
-    passed = completed.returncode in allowed
+    passed = completed["returncode"] in allowed
     return _Outcome(passed, None if passed else "command_failed", None, details)
 
 
@@ -379,7 +385,16 @@ def _budget_evidence(metadata: SpecMetadata, rule: SpecRule, scope: Verification
     )
 
 
-def run_all_verifiers(
+def _missing_evidence(metadata: SpecMetadata, rule: SpecRule, scope: VerificationScope) -> VerificationEvidence:
+    details = {"rule": rule.ref}
+    return VerificationEvidence(
+        f"{metadata.id}#{rule.ref}", datetime.now(timezone.utc).isoformat(),
+        "unverified", rule.text_sha256, None, scope.diff_sha256,
+        _result_hash("unverified", "verifier_missing", details), "verifier_missing", details,
+    )
+
+
+def _run_all_verifiers(
     metadata: SpecMetadata,
     scope: VerificationScope,
     confirmations: Optional[Mapping[str, Mapping[str, object]]] = None,
@@ -402,18 +417,7 @@ def run_all_verifiers(
                 continue
         verifier = verifier_by_rule.get(rule.ref)
         if verifier is None:
-            details = {"rule": rule.ref}
-            evidence_by_ref[rule.ref] = VerificationEvidence(
-                    f"{metadata.id}#{rule.ref}",
-                    datetime.now(timezone.utc).isoformat(),
-                    "unverified",
-                    rule.text_sha256,
-                    None,
-                    scope.diff_sha256,
-                    _result_hash("unverified", "verifier_missing", details),
-                    "verifier_missing",
-                    details,
-                )
+            evidence_by_ref[rule.ref] = _missing_evidence(metadata, rule, scope)
             continue
         if skip_command and verifier.type in ("command", "test"):
             evidence_by_ref[rule.ref] = _skipped_evidence(metadata, rule, scope)
@@ -436,6 +440,13 @@ def run_all_verifiers(
     return VerificationResult(result, bool(result) and all(item.status == "verified" for item in result))
 
 
+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:
+    with execution_session():
+        return _run_all_verifiers(metadata, scope, confirmations, skip_command, timeout_budget)
+
+
 def evidence_is_fresh(
     evidence: VerificationEvidence,
     rule_text_sha256: str,

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

@@ -12,6 +12,7 @@ from cf_core import (
     compress_content,
     estimate_tokens,
     load_config,
+    project_instruction_file,
     non_injectable_specs,
     resolve_quality_loop,
 )
@@ -21,6 +22,7 @@ def _violation_fixed(index: int, events: list) -> bool:
     """修正口径：违规后同会话同文件有后续编辑，且其后无同 check 再违规。
 
     用日志追加顺序判先后（ts 仅秒级精度，同秒事件无法靠时间戳排序）。
+    保留单点查询语义；批量聚合请用 violation_fixed_batch（一次线性扫描）。
     """
     violation = events[index]
     v_data = violation.get("data") or {}
@@ -41,6 +43,37 @@ def _violation_fixed(index: int, events: list) -> bool:
     return later_edit
 
 
+def violation_fixed_batch(events: list) -> list[bool]:
+    """Batch twin of _violation_fixed: one reverse pass, identical semantics.
+
+    Segments the timeline per (session, file) at edits: a violation is fixed
+    iff an edit exists after it and no same-check violation exists in a later
+    segment. No slicing, no per-violation rescan: O(n) time.
+    """
+    fixed: dict[int, bool] = {}
+    edit_right: set[tuple[str, str]] = set()
+    current: dict[tuple[str, str], set[str]] = {}
+    later: dict[tuple[str, str], set[str]] = {}
+    for index in range(len(events) - 1, -1, -1):
+        event = events[index]
+        if not isinstance(event, dict):
+            continue
+        kind = event.get("event")
+        data = event.get("data")
+        if not isinstance(data, dict):
+            data = {}
+        key = (str(event.get("sid")), str(data.get("file")))
+        if kind == "edit":
+            later.setdefault(key, set()).update(current.get(key, ()))
+            current[key] = set()
+            edit_right.add(key)
+        elif kind == "violation":
+            check = str(data.get("check_id"))
+            fixed[index] = key in edit_right and check not in later.get(key, ())
+            current.setdefault(key, set()).add(check)
+    return [fixed[index] for index, event in enumerate(events) if isinstance(event, dict) and event.get("event") == "violation"]
+
+
 def quality_loop_summary(project_root: str, config: dict) -> dict:
     """FEAT-05/02 度量聚合：Top 违规榜 / 修正率 / 误报与停用 / 降级组件。"""
     switches = resolve_quality_loop(config)
@@ -61,13 +94,10 @@ def quality_loop_summary(project_root: str, config: dict) -> dict:
         key=lambda item: -item["count"],
     )[:10]
 
-    fixed = sum(
-        1 for i, event in enumerate(events)
-        if event.get("event") == "violation" and _violation_fixed(i, events)
-    )
+    fixed = violation_fixed_batch(events)
     summary["violation_total"] = len(violations)
     summary["fix_rate"] = (
-        f"{round(fixed * 100 / len(violations))}%" if violations else "n/a"
+        f"{round(sum(fixed) * 100 / len(violations))}%" if violations else "n/a"
     )
 
     state = load_check_state(project_root)
@@ -273,7 +303,9 @@ def main() -> None:
     except Exception:
         total_budget = l0_budget + l1_budget
 
-    claude_path = os.path.join(project_root, "CLAUDE.md")
+    platform = next((arg.split("=", 1)[1] for arg in sys.argv if arg.startswith("--platform=")), "")
+    instruction_file = project_instruction_file(project_root, platform)
+    claude_path = os.path.join(project_root, instruction_file)
     l0_tokens = 0
     if os.path.exists(claude_path):
         l0_tokens = estimate_tokens(read_text(claude_path))
@@ -374,7 +406,7 @@ def main() -> None:
     workflow_summary = spec_workflow_summary(project_root)
 
     output = {
-        "l0": {"file": "CLAUDE.md", "tokens": l0_tokens, "budget": l0_budget},
+        "l0": {"file": instruction_file, "tokens": l0_tokens, "budget": l0_budget},
         "l1": l1,
         "total_tokens": total_tokens,
         "total_budget": total_budget,
@@ -394,7 +426,7 @@ def main() -> None:
     }
     if audit_mode:
         from cf_scan import build_report
-        scan = build_report(project_root)
+        scan = build_report(project_root, platform)
         output["audit"] = {
             "files": [e for e in scan["files"] if e.get("issues")],
             "review": scan["review"],
@@ -404,7 +436,7 @@ def main() -> None:
         print(json.dumps(output, ensure_ascii=False))
         return
 
-    print("L0 (CLAUDE.md):", f"{l0_tokens} / {l0_budget}")
+    print(f"L0 ({instruction_file}):", f"{l0_tokens} / {l0_budget}")
     for domain, items in l1.items():
         total_domain = sum(i["tokens"] for i in items if i.get("injectable", True))
         print(f"L1 {domain}:", total_domain)

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

@@ -12,14 +12,17 @@ continued session is never re-blocked (no loops). All-pass → silent exit 0.
 """
 import fnmatch
 import json
+import math
 import os
 import re
-import subprocess
 import sys
+import time
 
 import cf_log
+from cf_exec_base import build_argv, remaining_seconds, run_command, execution_session
 from cf_spec_context import load_active_task
 from cf_task_runtime import run_done_gate
+from cf_acceptance_evidence import line_status, scenario_line
 from cf_core import (
     _log,
     ensure_utf8_io,
@@ -93,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:
@@ -110,7 +141,9 @@ def _subsection(section: str, heading: str) -> str:
 
 def _acceptance_gap(task_id: str, section: str, coverage: str) -> str:
     status = re.search(r"(?m)^- \*\*Status\*\*: ([^\n]+)", section)
-    if not status or status.group(1).strip() != "done":
+    # done = implementation finished; verified = E2E/final acceptance closed.
+    # Both enter the same contract checks; anything else is still in flight.
+    if not status or status.group(1).strip() not in ("done", "verified"):
         return ""
     refs_match = re.search(r"(?m)^- \*\*Acceptance-Refs\*\*: ([^\n]+)", section)
     if not refs_match:
@@ -125,17 +158,17 @@ def _acceptance_gap(task_id: str, section: str, coverage: str) -> str:
     evidence = _subsection(section, "Acceptance Evidence")
     if not contract or not evidence:
         return f"{task_id} 缺少 Acceptance Contract 或 Acceptance Evidence"
-    if _UNVERIFIED_RE.search(contract) or _UNVERIFIED_RE.search(evidence):
-        return f"{task_id} 验收契约仍有 planned/pending/TBD"
     for scenario in scenarios:
-        contract_ok = any(scenario in line and "verified" in line.lower()
-                          for line in contract.splitlines())
-        evidence_ok = any(scenario in line and "verified" in line.lower()
-                          for line in evidence.splitlines())
-        coverage_ok = any(scenario in line and "verified" in line.lower()
-                          for line in coverage.splitlines())
-        if not contract_ok or not evidence_ok or not coverage_ok:
-            return f"{task_id} 的 {scenario} 未在覆盖表、契约和证据中全部 verified"
+        coverage_rows = [line for line in coverage.splitlines() if scenario_line(line, scenario)]
+        cells = coverage_rows[0].strip().strip("|").split("|") if coverage_rows else []
+        deferred = status.group(1).strip() == "done" and len(cells) >= 3 and cells[2].strip().lower() == "e2e"
+        allowed = {"verified", "e2e_deferred"} if deferred else {"verified"}
+        states = []
+        for body in (contract, evidence, coverage):
+            found = [line_status(line, scenario) for line in body.splitlines() if scenario_line(line, scenario)]
+            states.append(found[-1] if found else "")
+        if not all(state in allowed for state in states):
+            return f"{task_id} 的 {scenario} 状态未闭环（planned/pending/TBD/failed 或缺少 verified；仅实现阶段 E2E 可 e2e_deferred）"
     return ""
 
 
@@ -166,70 +199,92 @@ def task_acceptance_failures(project_root: str, files: list) -> list:
     return failures
 
 
+def _validator_failure(validator: dict, detail: str, incomplete: bool = False) -> dict:
+    result = {"name": validator.get("name", "validator"),
+              "on_fail": validator.get("on_fail", ""), "detail": detail}
+    if incomplete:
+        result["incomplete"] = True
+    return result
+
+
+def _validator_argv(root: str, validator: dict, matched: list, strict: bool) -> list:
+    existing = [name for name in matched if os.path.isfile(os.path.join(root, name))]
+    template = str(validator.get("command", ""))
+    if "{files}" in template and not existing:
+        return []
+    argv = build_argv(template, existing)
+    if not argv and strict:
+        raise ValueError("validator command missing")
+    return argv
+
+
+def _validator_result(root: str, validator: dict, argv: list, sid: str,
+                      deadline: float, strict: bool) -> tuple[list, bool]:
+    try:
+        timeout = float(validator.get("timeout", 30000)) / 1000.0
+    except (ValueError, TypeError):
+        if strict:
+            return [_validator_failure(validator, "invalid validator timeout")], False
+        timeout = 30.0
+    if not math.isfinite(timeout) or timeout <= 0:
+        return [_validator_failure(validator, "invalid validator timeout")], False
+    outcome = run_command(argv, root, timeout, deadline)
+    passed = outcome["status"] == "ok" and outcome["returncode"] == 0
+    if outcome["status"] == "deadline_exceeded":
+        return [_validator_failure(validator, "预算耗尽未执行", True)], True
+    timed_out = outcome["status"] == "timeout"
+    detail = (f"超时（>{timeout:.0f}s），未完成" if timed_out else
+              (str(outcome.get("stdout", "")) + str(outcome.get("stderr", ""))).strip()[-400:])
+    if outcome["status"] == "spawn_error":
+        cf_log.degrade(root, "stop_check", f"{validator.get('name')}:{outcome['stderr']}", sid)
+        if not strict:
+            return [], False
+    cf_log.append_event(root, "stop_check",
+                        {"trigger": validator.get("trigger", ""),
+                         "cmd": str(validator.get("command", ""))[:120], "passed": passed}, sid)
+    return ([] if passed else [_validator_failure(validator, detail)]), timed_out
+
+
 def run_validators(
     project_root: str, validators: list, files: list, sid: str,
     total_budget: float = TOTAL_BUDGET_SECONDS,
+    deadline: float = 0.0,
+    strict: bool = False,
 ) -> tuple:
-    """Run matching validators serially → (failures, truncated)."""
-    import time
-    failures = []
-    truncated = False
-    deadline = time.monotonic() + total_budget
+    """Match validators, execute argv under one deadline, report unrun work."""
+    failures, truncated = [], False
+    deadline = deadline or time.monotonic() + total_budget
     for validator in validators:
         if not isinstance(validator, dict):
+            if strict:
+                failures.append(_validator_failure({}, "invalid validator record"))
             continue
         matched = [f for f in files if trigger_matches(validator.get("trigger", ""), f)]
         if not matched:
             continue
-        remaining = deadline - time.monotonic()
-        if remaining <= 0:
+        remaining = remaining_seconds(deadline)
+        if remaining is not None and remaining <= 0:
+            failures.append(_validator_failure(validator, "预算耗尽未执行", True))
             truncated = True
-            break
-        try:
-            timeout = min(float(validator.get("timeout", 30000)) / 1000.0, remaining)
-        except (ValueError, TypeError):
-            timeout = remaining
-        command = str(validator.get("command", "")).replace(
-            "{files}", " ".join(matched)
-        )
-        if not command.strip():
             continue
-        passed = False
-        detail = ""
         try:
-            proc = subprocess.run(
-                command, shell=True, cwd=project_root,
-                capture_output=True, text=True, timeout=timeout,
-            )
-            passed = proc.returncode == 0
-            if not passed:
-                detail = (proc.stdout + proc.stderr).strip()[-400:]
-        except subprocess.TimeoutExpired:
-            detail = f"超时（>{timeout:.0f}s），跳过"
-            truncated = True
-        except Exception as exc:
-            # 命令在环境中不可用等：降级跳过，不打扰（E 场景）
-            cf_log.degrade(project_root, "stop_check", f"{validator.get('name')}:{exc}", sid)
+            argv = _validator_argv(project_root, validator, matched, strict)
+        except ValueError as exc:
+            failures.append(_validator_failure(validator, f"validator 配置错误: {exc}"))
             continue
-        cf_log.append_event(
-            project_root, "stop_check",
-            {"trigger": validator.get("trigger", ""),
-             "cmd": str(validator.get("command", ""))[:120], "passed": passed},
-            sid,
-        )
-        if not passed:
-            failures.append({
-                "name": validator.get("name", "validator"),
-                "on_fail": validator.get("on_fail", ""),
-                "detail": detail,
-            })
+        if not argv:
+            continue
+        errors, incomplete = _validator_result(project_root, validator, argv, sid, deadline, strict)
+        failures.extend(errors)
+        truncated = truncated or incomplete
     return failures, truncated
 
 
 def _reason_text(failures: list, truncated: bool) -> str:
     lines = ["收尾校验未通过（cf-stop）："]
     for item in failures:
-        lines.append(f"✗ {item['name']}：{item['on_fail']}")
+        tag = "（未执行）" if item.get("incomplete") else ""
+        lines.append(f"✗ {item['name']}{tag}：{item['on_fail']}")
         if item["detail"]:
             lines.append(f"  输出片段: {item['detail'][:200]}")
     if truncated:
@@ -238,7 +293,7 @@ def _reason_text(failures: list, truncated: bool) -> str:
     return "\n".join(lines)
 
 
-def main() -> None:
+def _main() -> None:
     try:
         ensure_utf8_io()
         raw = sys.stdin.read()
@@ -258,11 +313,16 @@ def main() -> None:
         marker = os.path.join(project_root, ".code-flow", ".active-task.json")
         has_active = os.path.exists(marker)
         files = []
+        # Single entry deadline constrains the whole chain (Done + validators),
+        # so long checks end as `incomplete` instead of being killed by the
+        # host without a verdict.
+        deadline = time.monotonic() + TOTAL_BUDGET_SECONDS
         if has_active:
             try:
                 active = load_active_task(project_root)
                 task_dir = os.path.join(project_root, active.task_dir)
-                done = run_done_gate(project_root, task_dir, budget=GATE_BUDGET_SECONDS)
+                gate_remaining = deadline - time.monotonic()
+                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}"}
@@ -284,13 +344,13 @@ 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
+            project_root, validators, files, sid, deadline=deadline
         ) if validators else ([], False)
         failures = acceptance_failures + failures
         if not failures:
@@ -306,9 +366,16 @@ def main() -> None:
         sys.stdout.write(json.dumps(payload, ensure_ascii=False))
     except Exception as exc:
         _log(f"cf_stop_hook error: {exc}")
+        if locals().get("enforcement") == "required":
+            sys.stdout.write(json.dumps({"decision": "block", "reason": f"SPEC_WORKFLOW_BLOCKED: {exc}"}, ensure_ascii=False))
         return
 
 
+def main() -> None:
+    with execution_session():
+        _main()
+
+
 if __name__ == "__main__":
     main()
     timing_log("cf_stop_hook")