@michaelxwb/code-flow 0.6.4 → 0.8.1

package/src/core/code-flow/scripts/{cf_spec_router.py → codeflow/spec/cf_spec_router.py}

@@ -4,24 +4,29 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+import hashlib
 import json
 import os
 from pathlib import Path
 import tempfile
+import codeflow.cli.cf_spec_session as cf_spec_session
 from typing import Mapping, Optional, Sequence
 
-from cf_core import (
+from codeflow.core.cf_core import (
     assemble_context,
+    ConfigError,
     build_effective_mapping,
     build_spec_catalog,
-    compress_content,
+    estimate_tokens,
     load_config,
-    parse_spec_frontmatter,
     resolve_compress,
 )
-from cf_spec_context import ContextError, load_active_task, load_context
-from cf_spec_resolver import resolve_candidates
-from cf_spec_session import context_sha256, project_task_session
+from codeflow.core.cf_log import warn
+from codeflow.cli.cf_spec_context import ContextError, SpecContext, load_active_task, load_context
+from codeflow.core.cf_context_cache import load_snapshot
+from codeflow.spec.cf_spec_resolver import resolve_candidate_headers
+from codeflow.spec.cf_spec_context_model import context_sha256
+from codeflow.spec.cf_task_projection import project_task_session
 
 
 _PROJECTION_CACHE_PATH = ".code-flow/.task-projection-state.json"
@@ -33,6 +38,7 @@ class RouteResult:
     text: str
     specs: tuple[str, ...]
     context_sha256: Optional[str] = None
+    expanded_specs: tuple[str, ...] = ()
 
 
 class RouterError(ValueError):
@@ -59,12 +65,21 @@ def _projection_cache_path(root: str) -> Path:
     return Path(root) / _PROJECTION_CACHE_PATH
 
 
+def _context_stat(task_dir: Path) -> list[int]:
+    info = (task_dir / "spec-context.yml").stat()
+    return [info.st_mtime_ns, info.st_ctime_ns, info.st_size]
+
+
 def _load_projection_cache(root: str) -> Mapping[str, object]:
     try:
         value = json.loads(_projection_cache_path(root).read_text(encoding="utf-8"))
     except (OSError, UnicodeError, json.JSONDecodeError):
         return {}
-    return value if isinstance(value, dict) else {}
+    if not isinstance(value, dict):
+        return {}
+    checksum = value.pop("checksum", None)
+    expected = hashlib.sha256(json.dumps(value, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
+    return value if checksum == expected else {}
 
 
 def _cached_projection(
@@ -90,6 +105,12 @@ def _cached_projection(
         return None
     if cache.get("task_dir_mtime_ns") != directory_mtime or cache.get("task_mtime_ns") != task_mtime:
         return None
+    if cache.get("context_stat") != _context_stat(task_dir):
+        return None
+    if cache.get("projector_sha256") != hashlib.sha256(Path(cf_spec_session.__file__).read_bytes()).hexdigest():
+        return None
+    if cache.get("task_sha256") != hashlib.sha256(task_file.read_bytes()).hexdigest():
+        return None
     return str(cache["text"]), bool(cache["truncated"])
 
 
@@ -107,13 +128,17 @@ def _save_projection_cache(
             "version": 1,
             "task_id": task_id,
             "context_sha256": current_hash,
+            "context_stat": _context_stat(task_dir),
+            "projector_sha256": hashlib.sha256(Path(cf_spec_session.__file__).read_bytes()).hexdigest(),
             "task_file": str(task_file),
             "task_dir_mtime_ns": task_dir.stat().st_mtime_ns,
             "task_mtime_ns": task_file.stat().st_mtime_ns,
+            "task_sha256": hashlib.sha256(task_file.read_bytes()).hexdigest(),
             "text": text,
             "truncated": truncated,
         }
         path = _projection_cache_path(root)
+        payload["checksum"] = hashlib.sha256(json.dumps(payload, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
         path.parent.mkdir(parents=True, exist_ok=True)
         temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
         temporary.write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")
@@ -126,23 +151,48 @@ def _save_projection_cache(
                 pass
 
 
-def _active_route(root: str) -> RouteResult:
+def _verify_bound_specs(root: str, context: SpecContext) -> None:
+    spec_root = Path(root) / ".code-flow/specs"
+    for binding in context.bindings:
+        target = spec_root / binding.path
+        try:
+            current = hashlib.sha256(target.read_bytes()).hexdigest()
+        except OSError as exc:
+            raise RouterError("bound_spec_missing", f"{binding.path}: {exc}; refresh Context") from exc
+        if current != binding.hashes.file_sha256:
+            raise RouterError("bound_spec_drift", f"{binding.path} changed; refresh Context before coding")
+
+
+def _scope_expansion(root: str, context: SpecContext, paths: Sequence[str]) -> tuple[str, ...]:
+    bound = {binding.spec_id for binding in context.bindings}
+    candidates = resolve_candidate_headers(
+        root, "code", paths, matched_only=True,
+        excluded_paths=tuple(binding.path for binding in context.bindings),
+    )
+    return tuple(item.spec_id for item in candidates
+                 if item.spec_id not in bound and item.enforcement == "required")
+
+
+def _active_route(root: str, paths: Sequence[str] = (), check_scope: bool = False) -> RouteResult:
     try:
         active = load_active_task(root)
         task_dir = (Path(root) / active.task_dir).resolve()
-        context = load_context(str(task_dir / "spec-context.yml"))
+        context, current_hash = load_snapshot(root, str(task_dir / "spec-context.yml"), load_context)
     except (ContextError, OSError, ValueError) as exc:
         raise RouterError("invalid_active_task", str(exc)) from exc
-    current_hash = context_sha256(context)
     if current_hash != active.context_sha256:
         raise RouterError(
             "active_context_drift",
-            "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`",
+            "active marker Context hash does not match; run `code-flow spec refresh --task-dir <dir> --root <root> --json` to re-sync it (refresh updates the marker hash), or `code-flow spec active doctor --resync` with the hash from `code-flow spec status --json`",
         )
+    _verify_bound_specs(root, context)
     cached = _cached_projection(root, task_dir, active.task_id, current_hash)
     if cached is None:
         task_file = _task_file(task_dir, active.task_id)
-        projection = project_task_session(context, str(task_file), active.task_id)
+        try:
+            projection = project_task_session(context, str(task_file), active.task_id, context_hash=current_hash)
+        except ValueError as exc:
+            raise RouterError("invalid_task_projection", str(exc)) from exc
         _save_projection_cache(
             root, task_dir, task_file, active.task_id, current_hash, projection.text, projection.truncated
         )
@@ -151,30 +201,26 @@ def _active_route(root: str) -> RouteResult:
         text, truncated = cached
     if truncated:
         raise RouterError("task_projection_truncated", "split the TASK before coding")
-    refs = tuple(binding.spec_id for binding in context.bindings)
-    return RouteResult("task", text, refs, current_hash)
+    refs = tuple(binding.spec_id for binding in context.bindings
+                 if any(f"`{binding.spec_id}#{rule.ref}`" in text for rule in binding.rules))
+    expanded = _scope_expansion(root, context, paths) if check_scope else ()
+    return RouteResult("task", text, refs, current_hash, expanded)
 
 
 def _read_candidates(root: str, paths: Sequence[str], compress: bool = True) -> RouteResult:
+    from codeflow.spec.cf_spec_budget import SpecBudgetError, path_specs
     try:
-        candidates = resolve_candidates(root, "code", tuple(paths))
-    except ValueError as exc:
-        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")
-        except OSError as exc:
-            raise RouterError("spec_read_failed", f"{candidate.path}: {exc}") from exc
-        unused_frontmatter, content = parse_spec_frontmatter(raw)
-        del unused_frontmatter
-        final_content = compress_content(content.strip()) if compress else content.strip()
-        specs.append({"path": candidate.path, "content": final_content, "tier": 1})
+        specs = path_specs(root, paths, compress)
+    except SpecBudgetError as exc:
+        raise RouterError(exc.code, str(exc)) from exc
     text = assemble_context(specs, "## Active Specs (path-mapped)") if specs else ""
-    return RouteResult("path", text, tuple(item.path for item in candidates))
+    budget = load_config(root).get("budget", {})
+    if not isinstance(budget, dict):
+        raise RouterError("invalid_budget", "budget must be a mapping")
+    maximum = min(int(budget.get("total", 2500)), int(budget.get("l1_max", 1700)))
+    if maximum <= 0 or estimate_tokens(text) > maximum:
+        raise RouterError("spec_budget_exceeded", f"Matched Specs exceed {maximum} estimated tokens; create a focused TASK Context or split the editing scope. Required constraints were not truncated.")
+    return RouteResult("path", text, tuple(item["path"] for item in specs))
 
 
 def _catalog_path(root: str) -> Path:
@@ -191,6 +237,8 @@ def _load_catalog_state(root: str) -> dict[str, object]:
         raise RouterError("invalid_catalog_state", str(exc)) from exc
     if not isinstance(value, dict) or value.get("version") != 1:
         raise RouterError("invalid_catalog_state", "Catalog state schema must be version 1")
+    if any(type(value.get(key)) is not int or value[key] < 0 for key in ("prompt_count", "last_emitted")):
+        raise RouterError("invalid_catalog_state", "Catalog counters must be nonnegative integers")
     return value
 
 
@@ -208,7 +256,7 @@ def _save_catalog_state(root: str, state: Mapping[str, object]) -> None:
     except OSError as exc:
         if temporary and Path(temporary).exists():
             Path(temporary).unlink()
-        raise RouterError("catalog_state_write_failed", str(exc)) from exc
+        warn(f"Spec Catalog dedup state could not be saved: {exc}")
 
 
 def _catalog_route(root: str, session_id: str, config: Mapping[str, object]) -> RouteResult:
@@ -221,20 +269,32 @@ def _catalog_route(root: str, session_id: str, config: Mapping[str, object]) ->
     window = int(catalog_config.get("dedup_window", 5))
     due = window <= 0 or last == 0 or count - last >= window
     next_state = {"version": 1, "session_id": session_id, "prompt_count": count, "last_emitted": count if due else last}
-    _save_catalog_state(root, next_state)
     if not due:
+        _save_catalog_state(root, next_state)
         return RouteResult("catalog", "", ())
     budget = config.get("budget") if isinstance(config.get("budget"), dict) else {}
     maximum = int(budget.get("catalog_max", 200))
     mapping = build_effective_mapping(root, config.get("path_mapping") or {})
-    return RouteResult("catalog", build_spec_catalog(root, mapping, maximum), ())
+    text = build_spec_catalog(root, mapping, maximum)
+    from codeflow.spec.cf_injection import defer_commit
+    defer_commit(lambda: _save_catalog_state(root, next_state))
+    return RouteResult("catalog", text, ())
+
+
+def route_prompt(root: str, paths: Sequence[str], session_id: str, *, check_scope: bool = False) -> RouteResult:
+    try:
+        return _route_prompt(root, paths, session_id, check_scope)
+    except RouterError:
+        raise
+    except (ConfigError, ContextError, OSError, UnicodeError, ValueError, TypeError) as exc:
+        raise RouterError(getattr(exc, "code", "invalid_routing_input"), str(exc)) from exc
 
 
-def route_prompt(root: str, paths: Sequence[str], session_id: str) -> RouteResult:
+def _route_prompt(root: str, paths: Sequence[str], session_id: str, check_scope: bool) -> RouteResult:
     """Choose exactly one route; an invalid active marker never falls back."""
     marker = Path(root) / ".code-flow/.active-task.json"
     if marker.exists():
-        return _active_route(root)
+        return _active_route(root, paths, check_scope)
     config = load_config(root)
     if not config:
         return RouteResult("none", "", ())

package/src/core/code-flow/scripts/{cf_spec_verify.py → codeflow/spec/cf_spec_verify.py}

@@ -4,21 +4,23 @@
 from __future__ import annotations
 
 import ast
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from datetime import datetime, timezone
 import fnmatch
 import hashlib
 import json
+import os
 from pathlib import Path
-import subprocess
 from threading import Lock
 import time
 from concurrent.futures import ThreadPoolExecutor
+from contextvars import copy_context
 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
+from codeflow.acceptance.cf_checks import run_regex_verifier
+from codeflow.spec.cf_spec_metadata import SpecMetadata, SpecRule, SpecVerifier
+from codeflow.core.cf_exec_base import execution_session, record_report, redact_sensitive_text, report_requested, run_command
+from codeflow.core import cf_git
 
 
 _RESULT_CACHE: dict[str, dict[str, object]] = {}
@@ -59,19 +61,82 @@ 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 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(cf_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 +208,38 @@ def _cached_or_run(
     verifier: SpecVerifier,
     scope: VerificationScope,
     confirmation: Optional[Mapping[str, object]],
+    stage: str = "code",
 ) -> VerificationEvidence:
+    if verifier.type == "regex" and not _regex_scope_files(verifier.config, metadata, scope):
+        # The fallback checks tracked files outside the diff. Do not reuse a
+        # diff-keyed result when those files may have changed independently.
+        return _evidence(metadata, rule, verifier, scope, confirmation)
     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
+            record_report({"kind": "spec_check", "check_id": f"{metadata.id}#{rule.ref}",
+                           "reused": 1, "execution_ms": 0.0})
+            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)
@@ -162,6 +252,8 @@ class _Outcome:
     error_code: Optional[str]
     artifact_sha256: Optional[str]
     details: Mapping[str, object]
+    execution_ms: Optional[float] = None
+    execution_reused: bool = False
 
 
 def _hash_bytes(data: bytes) -> str:
@@ -204,10 +296,31 @@ def _document(config: Mapping[str, object], scope: VerificationScope) -> _Outcom
     except (OSError, UnicodeError) as exc:
         return _Outcome(False, "artifact_read_error", None, {"artifact": relative, "error": str(exc)})
     expected = _config_string(config, "artifact_sha256")
-    present = section in content and item in content
+    from codeflow.spec.cf_rule_readiness import referenced_item, unresolved_text
+    selected = referenced_item(content, section, item)
+    present = bool(selected)
     hash_matches = expected is None or expected == artifact_hash
-    details = {"artifact": relative, "section_present": section in content, "item_present": item in content, "hash_matches": hash_matches}
-    return _Outcome(present and hash_matches, None if present and hash_matches else "document_mismatch", artifact_hash, details)
+    unresolved = unresolved_text(selected)
+    details = {"artifact": relative, "section_present": section in content, "item_present": bool(selected),
+               "hash_matches": hash_matches, "unresolved": unresolved}
+    error = "rule_applied_unresolved" if unresolved else "document_mismatch"
+    passed = present and hash_matches and not unresolved
+    return _Outcome(passed, None if passed else error, artifact_hash, details)
+
+
+def _regex_file_pattern(config: Mapping[str, object], metadata: SpecMetadata) -> str:
+    check_id = _config_string(config, "check_id")
+    check = next((item for item in metadata.checks if item.get("id") == check_id), None)
+    if check is not None and isinstance(check.get("files"), str):
+        return str(check["files"])
+    return _config_string(config, "files") or "*"
+
+
+def _regex_scope_files(config: Mapping[str, object], metadata: SpecMetadata,
+                       scope: VerificationScope) -> tuple[str, ...]:
+    files = _regex_file_pattern(config, metadata)
+    return tuple(relative for relative in scope.files
+                 if fnmatch.fnmatch(relative, files) and (Path(scope.root) / relative).is_file())
 
 
 def _regex(config: Mapping[str, object], metadata: SpecMetadata, scope: VerificationScope) -> _Outcome:
@@ -222,11 +335,16 @@ def _regex(config: Mapping[str, object], metadata: SpecMetadata, scope: Verifica
         files = check.get("files") if isinstance(check.get("files"), str) else "*"
     if pattern is None:
         return _Outcome(False, "invalid_verifier_config", None, {"required": ["pattern"]})
-    selected = tuple(
-        relative
-        for relative in scope.files
-        if fnmatch.fnmatch(relative, files) and (Path(scope.root) / relative).is_file()
-    )
+    selected = _regex_scope_files(config, metadata, scope)
+    if not selected:
+        tracked = tuple(relative for relative in cf_git.tracked_files(scope.root)
+                        if fnmatch.fnmatch(relative, files))
+        if any(not (Path(scope.root) / relative).is_file() for relative in tracked):
+            return _Outcome(False, "no_matching_files", None,
+                            {"checked_files": 0, "files": files, "reason": "tracked_files_missing"})
+        selected = tracked
+    if not selected:
+        return _Outcome(False, "no_matching_files", None, {"checked_files": 0, "files": files})
     contents, error = _read_scope_files(VerificationScope(scope.root, selected, scope.diff_sha256))
     if error is not None:
         return error
@@ -284,6 +402,13 @@ def _command(config: Mapping[str, object], scope: VerificationScope, timeout_cap
     allowed = tuple(item for item in allowed_value if isinstance(item, int)) if isinstance(allowed_value, list) else (0,)
     deadline = None if timeout_cap is None else time.monotonic() + timeout_cap
     completed = run_command(argv, str(Path(scope.root) / cwd), timeout, deadline)
+    outcome = _command_result(completed, argv, timeout, allowed)
+    return replace(outcome, execution_ms=float(completed.get("execution_ms", 0)),
+                   execution_reused=bool(completed.get("execution_reused")))
+
+
+def _command_result(completed: Mapping[str, object], argv: Sequence[str], timeout: float,
+                    allowed: Sequence[int]) -> _Outcome:
     if completed["status"] in ("timeout", "deadline_exceeded"):
         return _Outcome(False, "verifier_timeout", None, {"timeout": timeout, "argv": argv})
     if completed["status"] == "spawn_error":
@@ -293,7 +418,7 @@ def _command(config: Mapping[str, object], scope: VerificationScope, timeout_cap
         "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:],
+        "output": redact_sensitive_text((str(completed["stdout"]) + str(completed["stderr"]))[-4000:]),
     }
     passed = completed["returncode"] in allowed
     return _Outcome(passed, None if passed else "command_failed", None, details)
@@ -339,7 +464,20 @@ def _evidence(
     confirmation: Optional[Mapping[str, object]],
     timeout_cap: Optional[float] = None,
 ) -> VerificationEvidence:
+    started = time.monotonic()
     outcome = _run(verifier, metadata, scope, confirmation, timeout_cap)
+    execution_ms = (time.monotonic() - started) * 1000
+    if outcome.execution_ms is not None:
+        execution_ms = outcome.execution_ms
+    if report_requested():
+        identity_data = [_cache_key(metadata, rule, verifier, scope, confirmation, verifier.stage),
+                         str(Path(scope.root).resolve()), dict(os.environ), timeout_cap]
+        identity = hashlib.sha256(json.dumps(identity_data, sort_keys=True, default=str).encode()).hexdigest()
+        report = {"kind": "spec_check", "check_id": f"{metadata.id}#{rule.ref}",
+                  "reused": int(outcome.execution_reused), "execution_ms": execution_ms}
+        if not outcome.execution_reused:
+            report["identity"] = identity
+        record_report(report)
     status = "verified" if outcome.passed else "unverified"
     diff_hash = None if verifier.type == "document" else scope.diff_sha256
     return VerificationEvidence(
@@ -370,8 +508,47 @@ def _skipped_evidence(metadata: SpecMetadata, rule: SpecRule, scope: Verificatio
     )
 
 
+def _deferral_kind(reason: str) -> str:
+    """Map a task-gate deferral reason to its evidence category.
+
+    Budget and env deferrals are recorded but never treated as a pass: the
+    required check did not actually run. Only review-stage work may move to the
+    requirement-level verify-e2e gate.
+    """
+    if reason in ("out_of_task_scope", "review_stage"):
+        return "review_stage"
+    if reason in ("budget", "over_finish_budget", "verifier_budget_exhausted"):
+        return "budget"
+    if reason in ("env", "env_blocked", "environment_unavailable"):
+        return "env"
+    return "unknown"
+
+
+def _deferred_evidence(metadata: SpecMetadata, rule: SpecRule, scope: VerificationScope,
+                       reason: str) -> VerificationEvidence:
+    """任务级 Done Gate 延后执行（范围外/预算/环境）；需求级 verify-e2e 只补 review-stage。"""
+    kind = _deferral_kind(reason)
+    error_code = {
+        "review_stage": "deferred_to_review",
+        "budget": "verifier_budget_exhausted",
+        "env": "env_blocked",
+    }.get(kind, "deferred_to_review")
+    details = {"reason": reason, "deferral_kind": kind, "deferred_to_review": kind == "review_stage"}
+    return VerificationEvidence(
+        f"{metadata.id}#{rule.ref}",
+        datetime.now(timezone.utc).isoformat(),
+        "unverified",
+        rule.text_sha256,
+        None,
+        scope.diff_sha256,
+        _result_hash("unverified", error_code, details),
+        error_code,
+        details,
+    )
+
+
 def _budget_evidence(metadata: SpecMetadata, rule: SpecRule, scope: VerificationScope, budget: float) -> VerificationEvidence:
-    details = {"budget": budget}
+    details = {"budget": budget, "deferral_kind": "budget"}
     return VerificationEvidence(
         f"{metadata.id}#{rule.ref}",
         datetime.now(timezone.utc).isoformat(),
@@ -394,15 +571,16 @@ def _missing_evidence(metadata: SpecMetadata, rule: SpecRule, scope: Verificatio
     )
 
 
-def _run_all_verifiers(
-    metadata: SpecMetadata,
-    scope: VerificationScope,
+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,
+    stage: Optional[str] = "code",
+    deferred: Optional[Mapping[str, str]] = None,
 ) -> VerificationResult:
     verifier_by_rule = {item.rule: item for item in metadata.verifiers}
     confirmation_by_rule = confirmations or {}
+    deferred_by_rule = deferred or {}
     _load_result_cache(scope.root)
     evidence_by_ref: dict[str, VerificationEvidence] = {}
     parallel: list[tuple[SpecRule, SpecVerifier, Optional[Mapping[str, object]]]] = []
@@ -410,12 +588,17 @@ 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 stage is not None and verifier.stage != stage:
+            continue
+        if rule.ref in deferred_by_rule:
+            evidence_by_ref[rule.ref] = _deferred_evidence(metadata, rule, scope, deferred_by_rule[rule.ref])
+            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 +610,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(copy_context().run, _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 +625,11 @@ 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: Optional[str] = "code",
+                      deferred: Optional[Mapping[str, str]] = None) -> 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, deferred)
 
 
 def evidence_is_fresh(
@@ -459,3 +644,44 @@ def evidence_is_fresh(
         and evidence.artifact_sha256 == artifact_sha256
         and evidence.diff_sha256 == diff_sha256
     )
+
+def store_verification_evidence(
+    metadata: SpecMetadata,
+    scope: VerificationScope,
+    result: VerificationResult,
+    requirement: str = "",
+) -> tuple[dict[str, object], ...]:
+    """Persist verifier runs in the central sidecar (audit/compaction input)."""
+    from codeflow.evidence.cf_evidence_store import EvidenceStore, git_commit
+
+    store = EvidenceStore(scope.root, requirement)
+    commit = git_commit(store.root)
+    outcomes: list[dict[str, object]] = []
+    for item in result.evidence:
+        details = dict(item.details or {})
+        identity = "|".join((
+            item.verifier_ref, item.status, item.result_sha256,
+            item.diff_sha256 or "", item.rule_text_sha256,
+        ))
+        argv = details.get("argv")
+        timeout = details.get("timeout")
+        run = {
+            "run_id": hashlib.sha256(identity.encode("utf-8")).hexdigest()[:32],
+            "check_id": item.verifier_ref,
+            "command": argv if isinstance(argv, list) and all(isinstance(value, str) for value in argv) else [],
+            "cwd": ".",
+            "timeout": timeout if isinstance(timeout, (int, float)) else 0,
+            "input_hash": item.diff_sha256 or item.result_sha256,
+            "exit_code": details.get("exit_code") if isinstance(details.get("exit_code"), int) else (0 if item.status == "verified" else 1),
+            "status": "passed" if item.status == "verified" else "failed",
+            "executed_at": item.executed_at,
+            "source": "local",
+            "commit": commit,
+            "run_url": "",
+            "rule_text_sha256": item.rule_text_sha256,
+            "result_sha256": item.result_sha256,
+            "error_code": item.error_code,
+            "details": details,
+        }
+        outcomes.append(store.write_run(item.verifier_ref, run))
+    return tuple(outcomes)