@michaelxwb/code-flow 0.6.1 → 0.6.2

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

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Lock and validate plan Acceptance Coverage entries."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import re
+import sys
+from typing import IO, Mapping, Optional, Sequence
+
+
+_ROW_RE = re.compile(r"^\|\s*([SEB]-\d+)\s*\|(.+?)\|$")
+
+
+def _kind(level: str) -> str:
+    """Map test level to execution kind.
+
+    - functional: auto-executed in Done Gate (unit, integration)
+    - e2e: deferred until explicit --verify-e2e (needs external dependencies)
+    - manual: user confirmation required, never auto-executed
+    """
+    normalized = level.strip().lower()
+    if normalized == "manual":
+        return "manual"
+    if normalized == "e2e":
+        return "e2e"  # Keep as separate kind, not functional
+    return "functional"
+
+
+def _manifest_hash(rows: list[dict[str, str]]) -> str:
+    immutable = [{key: item[key] for key in ("id", "source", "level", "kind", "boundary", "owner")} for item in rows]
+    payload = json.dumps(immutable, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(payload).hexdigest()
+
+
+def extract_manifest(task_file: str) -> dict[str, object]:
+    path = Path(task_file)
+    text = path.read_text(encoding="utf-8")
+    rows: list[dict[str, str]] = []
+    in_table = False
+    seen: set[str] = set()
+    for line in text.splitlines():
+        if line.startswith("## Acceptance Coverage"):
+            in_table = True
+            continue
+        if in_table and line.startswith("## "):
+            break
+        if not in_table:
+            continue
+        match = _ROW_RE.match(line)
+        if not match or set(match.group(2).replace("|", "").strip()) <= {"-", " "}:
+            continue
+        fields = [item.strip() for item in match.group(2).split("|")]
+        if len(fields) < 5 or match.group(1) in seen:
+            continue
+        seen.add(match.group(1))
+        rows.append({"id": match.group(1), "source": fields[0], "level": fields[1], "kind": _kind(fields[1]), "boundary": fields[2], "owner": fields[3], "status": fields[4]})
+    if not rows:
+        raise ValueError("Acceptance Coverage 缺失或为空")
+    return {"schema": 1, "task_file": str(path), "task_sha256": _manifest_hash(rows), "scenarios": rows}
+
+
+def write_manifest(task_file: str, output: str) -> dict[str, object]:
+    manifest = extract_manifest(task_file)
+    target = Path(output)
+    try:
+        manifest["task_file"] = str(Path(task_file).resolve().relative_to(target.parent.resolve()))
+    except ValueError:
+        manifest["task_file"] = str(Path(task_file).resolve())
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    return manifest
+
+
+def validate_manifest(task_file: str, manifest_file: str) -> tuple[bool, str]:
+    try:
+        manifest = json.loads(Path(manifest_file).read_text(encoding="utf-8"))
+        expected = extract_manifest(task_file)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        return False, f"acceptance_manifest_invalid: {exc}"
+    if manifest.get("schema") != 1 or manifest.get("task_sha256") != expected["task_sha256"]:
+        return False, "acceptance_manifest_drift"
+    actual = {item.get("id") for item in manifest.get("scenarios", []) if isinstance(item, Mapping)}
+    required = {item["id"] for item in expected["scenarios"]}
+    if actual != required:
+        return False, "acceptance_manifest_scenarios_changed"
+    text = Path(task_file).read_text(encoding="utf-8")
+    for scenario in expected["scenarios"]:
+        owner = scenario["owner"]
+        section = re.search(rf"(?ms)^##\s+{re.escape(owner)}:.*?(?=^##\s+TASK-|\Z)", text)
+        refs = section.group(0).partition("Acceptance-Refs")[2] if section else ""
+        if scenario["id"] not in refs:
+            return False, "acceptance_manifest_owner_missing"
+    return True, ""
+
+
+def record_manual_evidence(manifest_file: str, scenario_id: str, confirmed_by: str, evidence: str) -> None:
+    if not confirmed_by or confirmed_by.lower().split(":", 1)[0] in {"agent", "assistant", "codex", "claude", "opencode", "costrict"}:
+        raise ValueError("manual evidence must be confirmed by a user")
+    path = Path(manifest_file)
+    data = json.loads(path.read_text(encoding="utf-8"))
+    scenarios = data.get("scenarios")
+    if not isinstance(scenarios, list):
+        raise ValueError("invalid manifest scenarios")
+    found = False
+    owner = ""
+    task_file = data.get("task_file")
+    for item in scenarios:
+        if isinstance(item, dict) and item.get("id") == scenario_id:
+            if item.get("kind") != "manual":
+                raise ValueError("scenario is not manual")
+            item["status"] = "verified"
+            item["evidence"] = {"confirmed_by": confirmed_by, "evidence": evidence}
+            found = True
+            owner = item.get("owner") if isinstance(item.get("owner"), str) else ""
+    if not found:
+        raise ValueError("scenario not found")
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    if isinstance(task_file, str) and task_file:
+        task_path = Path(task_file)
+        if not task_path.is_absolute():
+            task_path = path.parent / task_path
+        _sync_task_evidence(task_path, scenario_id, confirmed_by, evidence, owner)
+
+
+def _sync_task_evidence(task_file: Path, scenario_id: str, confirmed_by: str, evidence: str, owner: str = "") -> None:
+    text = task_file.read_text(encoding="utf-8")
+    if owner:
+        section_match = re.search(rf"(?ms)^##\s+{re.escape(owner)}:.*?(?=^##\s+TASK-|\Z)", text)
+    else:
+        section_match = re.search(r"(?ms)^##\s+TASK-\d+:.*?(?=^##\s+TASK-|\Z)", text)
+    if section_match is None:
+        return
+    section = section_match.group(0)
+    line = f"- {scenario_id}: verified — {evidence} (confirmed_by: {confirmed_by})"
+    contract_match = re.search(r"(?ms)^### Acceptance Contract\s*$\n(.*?)(?=^### |^## |\Z)", section)
+    if contract_match and scenario_id in contract_match.group(1) and "verified" not in contract_match.group(1).lower():
+        body = contract_match.group(1)
+        body = "\n".join((f"{item} — verified" if scenario_id in item else item) for item in body.splitlines())
+        section = section[:contract_match.start(1)] + body + section[contract_match.end(1):]
+    evidence_match = re.search(r"(?ms)^### Acceptance Evidence\s*$\n(.*?)(?=^### |^## |\Z)", section)
+    if evidence_match:
+        body = evidence_match.group(1)
+        replacement = body.rstrip() + "\n" + line + "\n"
+        section = section[:evidence_match.start(1)] + replacement + section[evidence_match.end(1):]
+    else:
+        section = section.rstrip() + "\n\n### Acceptance Evidence\n" + line + "\n"
+    task_file.write_text(text[:section_match.start()] + section + text[section_match.end():], encoding="utf-8")
+
+
+def main(argv: Optional[Sequence[str]] = None, stdout: IO[str] = sys.stdout) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--task-file", required=True)
+    parser.add_argument("--output", default="")
+    parser.add_argument("--verify-plan", action="store_true")
+    parser.add_argument("--task-dir", default="")
+    parser.add_argument("--record-manual", action="store_true")
+    parser.add_argument("--scenario-id", default="")
+    parser.add_argument("--confirmed-by", default="")
+    parser.add_argument("--evidence", default="")
+    args = parser.parse_args(argv)
+    try:
+        if args.record_manual:
+            if not args.output or not args.scenario_id or not args.evidence:
+                raise ValueError("--record-manual requires --output, --scenario-id and --evidence")
+            record_manual_evidence(args.output, args.scenario_id, args.confirmed_by, args.evidence)
+            stdout.write(json.dumps({"ok": True, "scenario": args.scenario_id}, ensure_ascii=False))
+            return 0
+        if args.verify_plan:
+            if not args.task_dir:
+                raise ValueError("--verify-plan requires --task-dir")
+            from cf_spec_context import load_context
+            from cf_spec_gate import result_to_data, validate_plan_coverage, validate_stage
+
+            context = load_context(str(Path(args.task_dir) / "spec-context.yml"))
+            gate = validate_stage(context, "plan")
+            coverage = validate_plan_coverage(context, args.task_file)
+            result = {
+                "decision": "block" if gate.decision == "block" or coverage.decision == "block" else "pass",
+                "gate": result_to_data(gate),
+                "coverage": result_to_data(coverage),
+            }
+            stdout.write(json.dumps(result, ensure_ascii=False))
+            return 0 if result["decision"] == "pass" else 3
+        if not args.output:
+            raise ValueError("--output is required unless --verify-plan is used")
+        manifest = write_manifest(args.task_file, args.output)
+        stdout.write(json.dumps({"ok": True, "scenarios": len(manifest["scenarios"])}, ensure_ascii=False))
+        return 0
+    except (OSError, ValueError) as exc:
+        stdout.write(json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False))
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""Execute manifest scenarios with deterministic ordering and evidence."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import subprocess
+import sys
+from typing import IO, Mapping, Optional, Sequence
+
+
+def _run(item: Mapping[str, object], root: Path, include_e2e: bool = False) -> dict[str, object]:
+    scenario_id = str(item.get("id", "unknown"))
+    kind = str(item.get("kind", "functional"))
+    if kind == "manual":
+        return {"id": scenario_id, "kind": kind, "status": "manual_pending"}
+    if kind == "e2e" and not include_e2e:
+        return {"id": scenario_id, "kind": kind, "status": "e2e_deferred"}
+    command = item.get("command")
+    if not isinstance(command, list) or not command or not all(isinstance(value, str) for value in command):
+        return {"id": scenario_id, "kind": kind, "status": "not_configured"}
+    timeout = item.get("timeout", 60)
+    timeout_value = float(timeout) if isinstance(timeout, (int, float)) else 60.0
+    cwd = item.get("cwd", ".") if isinstance(item.get("cwd", "."), str) else "."
+    try:
+        result = subprocess.run(command, cwd=str(root / cwd), capture_output=True, timeout=timeout_value, check=False)
+    except subprocess.TimeoutExpired:
+        return {"id": scenario_id, "kind": kind, "status": "failed", "error": "timeout"}
+    except OSError as exc:
+        return {"id": scenario_id, "kind": kind, "status": "failed", "error": str(exc)}
+    return {"id": scenario_id, "kind": kind, "status": "passed" if result.returncode == 0 else "failed", "exit_code": result.returncode}
+
+
+def _ordered(items: list[Mapping[str, object]]) -> list[Mapping[str, object]]:
+    by_id = {str(item.get("id")): item for item in items}
+    pending = set(by_id)
+    ordered: list[Mapping[str, object]] = []
+    while pending:
+        ready: list[str] = []
+        for item_id in by_id:
+            if item_id not in pending:
+                continue
+            deps = by_id[item_id].get("depends_on", [])
+            dep_ids = [str(dep) for dep in deps] if isinstance(deps, list) else []
+            unknown = [dep for dep in dep_ids if dep not in by_id]
+            if unknown:
+                raise ValueError(f"acceptance scenario dependency missing: {', '.join(unknown)}")
+            if all(dep not in pending for dep in dep_ids):
+                ready.append(item_id)
+        if not ready:
+            raise ValueError("acceptance scenario dependency cycle")
+        ordered.extend(by_id[item_id] for item_id in ready)
+        pending.difference_update(ready)
+    return ordered
+
+
+def run_manifest(manifest_file: str, root: str, write_evidence: bool = False, include_e2e: bool = False) -> dict[str, object]:
+    data = json.loads(Path(manifest_file).read_text(encoding="utf-8"))
+    scenarios = data.get("scenarios", [])
+    if not isinstance(scenarios, list):
+        raise ValueError("invalid scenarios")
+    items = [item for item in scenarios if isinstance(item, Mapping)]
+    ordered = _ordered(items)
+    results = [_run(item, Path(root), include_e2e) for item in ordered]
+    configured = any(isinstance(item.get("command"), list) for item in items)
+    allowed = ("passed", "manual_pending", "e2e_deferred", "not_configured") if not configured else ("passed", "manual_pending", "e2e_deferred")
+    decision = "pass" if all(item["status"] in allowed for item in results) else "block"
+    if write_evidence:
+        for item, result in zip(ordered, results):
+            if isinstance(item, dict) and result["status"] == "passed":
+                item["status"] = "verified"
+                item["evidence"] = result
+        Path(manifest_file).write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        task_file = data.get("task_file")
+        if isinstance(task_file, str) and task_file:
+            from cf_acceptance_manifest import _sync_task_evidence
+
+            task_path = Path(task_file)
+            if not task_path.is_absolute():
+                task_path = Path(manifest_file).parent / task_path
+            for item, result in zip(ordered, results):
+                if result["status"] == "passed":
+                    owner = item.get("owner") if isinstance(item.get("owner"), str) else ""
+                    _sync_task_evidence(task_path, str(result["id"]), "runner", "automated command passed", owner)
+    return {"decision": decision, "results": results}
+
+
+def main(argv: Optional[Sequence[str]] = None, stdout: IO[str] = sys.stdout) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--manifest", required=True)
+    parser.add_argument("--root", required=True)
+    parser.add_argument("--write-evidence", action="store_true")
+    parser.add_argument("--include-e2e", action="store_true", help="Execute E2E scenarios (deferred by default)")
+    args = parser.parse_args(argv)
+    try:
+        result = run_manifest(args.manifest, args.root, args.write_evidence, args.include_e2e)
+        stdout.write(json.dumps(result, ensure_ascii=False))
+        return 0 if result["decision"] == "pass" else 3
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        stdout.write(json.dumps({"decision": "block", "error": str(exc)}, ensure_ascii=False))
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -3,6 +3,7 @@ import fnmatch
 import os
 import re
 import sys
+import time
 
 # --- Config cache (fix #3: avoid re-parsing YAML on every hook call) ---
 
@@ -665,6 +666,25 @@ def _log(msg: str) -> None:
     print(msg, file=sys.stderr)
 
 
+_PROCESS_START = time.monotonic()
+
+
+def timing_log(name: str) -> None:
+    """Emit process-elapsed ms to stderr only when CF_DEBUG=1 (diagnostics).
+
+    Never touches stdout, so the hook JSON protocol is unaffected; a default
+    run pays one env lookup and no IO.
+    """
+    if os.environ.get("CF_DEBUG") == "1":
+        _log(f"{name}: {int((time.monotonic() - _PROCESS_START) * 1000)}ms")
+
+
+def phase_timing(name: str, started: float) -> None:
+    """Emit a named phase duration to stderr when CF_DEBUG=1."""
+    if os.environ.get("CF_DEBUG") == "1":
+        _log(f"cf_phase {name}: {int((time.monotonic() - started) * 1000)}ms")
+
+
 def ensure_utf8_io() -> None:
     """Force stdin/stdout/stderr to UTF-8 so Windows hooks don't mojibake.
 

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

@@ -40,6 +40,7 @@ from cf_core import (
     resolve_enforcement,
     resolve_quality_loop,
     resolve_session_id,
+    timing_log,
 )
 
 FEEDBACK_HINT = '如认为误报，直接告诉我"这是误报"，我会标记忽略。'
@@ -191,3 +192,4 @@ def main() -> None:
 
 if __name__ == "__main__":
     main()
+    timing_log("cf_post_hook")

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

@@ -11,10 +11,10 @@ from pathlib import Path
 import sys
 
 import cf_log
-from cf_core import _log, ensure_utf8_io, load_config, normalize_path, resolve_enforcement, resolve_session_id
+from cf_core import _log, ensure_utf8_io, load_config, normalize_path, resolve_enforcement, resolve_session_id, timing_log
 from cf_session_state import load_session_state, save_session_state
 from cf_spec_context import load_active_task, load_context
-from cf_spec_resolver import resolve_candidates
+from cf_spec_resolver import resolve_candidate_headers
 from cf_spec_router import RouterError, route_prompt
 
 _WARN_TEXT = "⚠ Spec Workflow 校验未通过（warn 模式）：{message} — 建议运行 cf-spec doctor 检查。"
@@ -28,8 +28,8 @@ def _active_expansion(root: str, relative: str) -> tuple[str, ...]:
     context = load_context(str(Path(root) / active.task_dir / "spec-context.yml"))
     bound = {item.spec_id for item in context.bindings}
     return tuple(
-        item.spec_id for item in resolve_candidates(root, "code", (relative,))
-        if item.spec_id not in bound and item.metadata.enforcement == "required"
+        item.spec_id for item in resolve_candidate_headers(root, "code", (relative,))
+        if item.spec_id not in bound and item.enforcement == "required"
     )
 
 
@@ -86,3 +86,4 @@ def main() -> None:
 
 if __name__ == "__main__":
     main()
+    timing_log("cf_pre_tool_hook")

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

@@ -14,12 +14,12 @@ from pathlib import Path
 import subprocess
 import sys
 import tempfile
+import time
 from typing import IO, Mapping, Optional, Sequence
 
-import yaml
-
 from cf_spec_metadata import SpecHashes, SpecMetadata, SpecRule, load_spec_metadata
 from cf_spec_resolver import SpecCandidate, resolve_candidates
+from cf_core import phase_timing
 
 
 CONTEXT_VERSION = 1
@@ -28,12 +28,17 @@ STAGE_STATUSES = frozenset(
 )
 DECISION_KINDS = frozenset(("not_applicable", "waived", "manual_verification"))
 _AGENT_IDENTITIES = frozenset(("agent", "assistant", "codex", "claude", "opencode", "costrict"))
+_FILE_HASH_CACHE: dict[str, tuple[int, int, int, str]] = {}
+_PERSISTENT_HASH_CACHE: dict[str, dict[str, object]] = {}
+_PERSISTENT_HASH_PATHS: set[str] = set()
+_MAX_HASH_CACHE_ENTRIES = 4096
 ACTIVE_STATUSES = frozenset(("activating", "active", "paused", "blocked", "completed"))
 DEFAULT_ACTIVE_EXCLUDES = (
     ".code-flow/tasks/*",
     ".code-flow/specs/_session/*",
     ".code-flow/migrations/*",
     ".code-flow/.*state*",
+    ".code-flow/.*cache*",
     ".code-flow/.session-log.jsonl",
     ".code-flow/.active-task.json",
     ".code-flow/.active-task.lock",
@@ -208,7 +213,7 @@ def _active_paths(root: str) -> tuple[Path, Path]:
 def _run_git(root: str, arguments: Sequence[str]) -> str:
     try:
         result = subprocess.run(
-            ("git", *arguments), cwd=root, text=True, capture_output=True, check=False
+            ("git", *arguments), cwd=root, text=True, encoding="utf-8", capture_output=True, check=False
         )
     except OSError as exc:
         raise ContextError("git_unavailable", "git", str(exc), root) from exc
@@ -267,16 +272,6 @@ def _is_excluded(path: str, patterns: Sequence[str]) -> bool:
     return any(fnmatchcase(path, pattern) for pattern in patterns)
 
 
-def _path_hash(root: str, path: str) -> str:
-    target = Path(root) / path
-    digest = hashlib.sha256()
-    if target.is_file():
-        with target.open("rb") as handle:
-            for chunk in iter(lambda: handle.read(65536), b""):
-                digest.update(chunk)
-    return digest.hexdigest()
-
-
 def _active_data(active: ActiveTask) -> dict[str, object]:
     changes = {
         path: {"status": item.status, "content_sha256": item.content_sha256}
@@ -300,9 +295,10 @@ def _active_data(active: ActiveTask) -> dict[str, object]:
 
 def _snapshot_from_data(value: object, path: str) -> PathSnapshot:
     data = _mapping(value, "preexisting_changes[]", path)
+    content_hash = data.get("content_sha256")
     return PathSnapshot(
         _string(data.get("status"), "status", path),
-        _string(data.get("content_sha256"), "content_sha256", path),
+        content_hash if isinstance(content_hash, str) else "",
     )
 
 
@@ -460,8 +456,11 @@ def _new_active(
         raise ContextError("unknown_owned_path", "owned_paths", ", ".join(unknown), root)
     if unowned:
         raise ContextError("unowned_changes", "owned_paths", ", ".join(unowned), root)
+    # content_sha256 was a per-file hash but is never consumed by any gate (only
+    # baseline.head is compared); keep the schema field empty so start never hashes
+    # every uncommitted file.
     snapshots = {
-        path: PathSnapshot(status, _path_hash(root, path)) for path, status in changes.items()
+        path: PathSnapshot(status, "") for path, status in changes.items()
     }
     baseline = ActiveBaseline(_git_head(root), _now(), snapshots)
     return ActiveTask(
@@ -822,6 +821,7 @@ def context_sha256(context: SpecContext) -> str:
     Computed from the stable identity projection (never volatile runtime state),
     so evidence timestamps and stage statuses cannot drift the marker.
     """
+    import yaml
     data = yaml.safe_dump(context_to_identity(context), sort_keys=True, allow_unicode=True).encode()
     return hashlib.sha256(data).hexdigest()
 
@@ -834,6 +834,7 @@ def new_context(task: str, sources: Sequence[tuple[str, str]]) -> SpecContext:
 
 
 def load_context(path: str) -> SpecContext:
+    import yaml
     try:
         loaded = yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {}
     except (OSError, UnicodeError, yaml.YAMLError) as exc:
@@ -862,6 +863,7 @@ def load_context(path: str) -> SpecContext:
 
 
 def save_context(path: str, context: SpecContext) -> None:
+    import yaml
     target = Path(path)
     target.parent.mkdir(parents=True, exist_ok=True)
     text = yaml.safe_dump(context_to_data(context), sort_keys=False, allow_unicode=True)
@@ -965,7 +967,57 @@ def _removed_rule(rule: RuleBinding) -> RuleBinding:
 
 def _file_sha256(path: Path) -> str:
     try:
-        return hashlib.sha256(path.read_bytes()).hexdigest()
+        stat = path.stat()
+        key = str(path)
+        cached = _FILE_HASH_CACHE.get(key)
+        signature = (stat.st_mtime_ns, stat.st_size, stat.st_ino)
+        if cached is not None and cached[:3] == signature:
+            return cached[3]
+        cache_path = next(
+            (parent / ".artifact-hash-cache.json" for parent in path.parents if parent.name == ".code-flow"),
+            None,
+        )
+        cache_key = str(cache_path) if cache_path is not None else ""
+        if cache_key and cache_key not in _PERSISTENT_HASH_PATHS:
+            try:
+                loaded = json.loads(cache_path.read_text(encoding="utf-8"))
+                if isinstance(loaded, dict):
+                    _PERSISTENT_HASH_CACHE.update({str(k): v for k, v in loaded.items() if isinstance(v, dict)})
+            except (OSError, ValueError):
+                pass
+            _PERSISTENT_HASH_PATHS.add(cache_key)
+        persistent = _PERSISTENT_HASH_CACHE.get(key)
+        if (
+            isinstance(persistent, dict)
+            and persistent.get("mtime_ns") == stat.st_mtime_ns
+            and persistent.get("size") == stat.st_size
+            and persistent.get("ino") == stat.st_ino
+        ):
+            digest = persistent.get("sha256")
+            if isinstance(digest, str) and digest:
+                _FILE_HASH_CACHE[key] = (signature[0], signature[1], signature[2], digest)
+                return digest
+        digest = hashlib.sha256(path.read_bytes()).hexdigest()
+        _FILE_HASH_CACHE[key] = (signature[0], signature[1], signature[2], digest)
+        if cache_key:
+            _PERSISTENT_HASH_CACHE[key] = {
+                "mtime_ns": stat.st_mtime_ns,
+                "size": stat.st_size,
+                "ino": stat.st_ino,
+                "sha256": digest,
+            }
+            while len(_PERSISTENT_HASH_CACHE) > _MAX_HASH_CACHE_ENTRIES:
+                _PERSISTENT_HASH_CACHE.pop(next(iter(_PERSISTENT_HASH_CACHE)))
+            try:
+                temporary = cache_path.with_suffix(".json.tmp")
+                temporary.write_text(
+                    json.dumps(_PERSISTENT_HASH_CACHE, ensure_ascii=False, sort_keys=True),
+                    encoding="utf-8",
+                )
+                temporary.replace(cache_path)
+            except OSError:
+                pass
+        return digest
     except OSError as exc:
         raise ContextError("artifact_read_error", "artifact", str(exc), str(path)) from exc
 
@@ -1057,15 +1109,19 @@ def _refresh_binding(
 
 
 def refresh_context(context: SpecContext, root: str, artifact_root: Optional[str] = None) -> DriftResult:
+    started = time.monotonic()
     specs = Path(root) / ".code-flow" / "specs"
     artifacts = Path(artifact_root) if artifact_root is not None else Path(root)
     bindings: list[SpecBinding] = []
     changes: list[DriftChange] = []
     for binding in context.bindings:
+        phase_started = time.monotonic()
         updated, binding_changes = _refresh_binding(binding, specs, artifacts)
+        phase_timing(f"context.refresh.{binding.spec_id}", phase_started)
         bindings.append(updated)
         changes.extend(binding_changes)
     refreshed = replace(context, updated_at=_now(), bindings=tuple(bindings))
+    phase_timing("context.refresh.total", started)
     if refreshed.bindings == context.bindings:
         return DriftResult(context, tuple(changes))
     return DriftResult(refreshed, tuple(changes))
@@ -1309,6 +1365,56 @@ def _active_command(args: argparse.Namespace, payload: Mapping[str, object]) ->
     return {"ok": True, "active": _active_data(active)}
 
 
+def _start_command(args: argparse.Namespace, payload: Mapping[str, object]) -> dict[str, object]:
+    """Run refresh, activation and TASK projection in one guarded process."""
+    context_path = Path(args.task_dir) / "spec-context.yml"
+    refreshed = refresh_context(load_context(str(context_path)), args.root, artifact_root=args.task_dir)
+    save_context(str(context_path), refreshed.context)
+    _resync_after_save(args, context_path)
+    current_hash = context_sha256(refreshed.context)
+    owned = tuple(
+        _string(item, "owned_paths[]", "")
+        for item in _sequence(payload.get("owned_paths", []), "owned_paths", "")
+    )
+    task_file = Path(args.task_file).resolve()
+    task_dir = Path(args.task_dir).resolve()
+    if task_file.parent != task_dir or not task_file.is_file():
+        raise ContextError("invalid_task_file", "task_file", str(task_file), args.task_dir)
+    manifest_file = task_dir / ".acceptance-manifest.json"
+    if "## Acceptance Coverage" in task_file.read_text(encoding="utf-8") and not manifest_file.is_file():
+        raise ContextError(
+            "acceptance_manifest_missing",
+            "acceptance_manifest",
+            "run plan verification and lock the manifest",
+            str(manifest_file),
+        )
+    if manifest_file.is_file():
+        from cf_acceptance_manifest import validate_manifest
+
+        valid, reason = validate_manifest(str(task_file), str(manifest_file))
+        if not valid:
+            raise ContextError(reason, "acceptance_manifest", "run plan verification before coding", str(manifest_file))
+    from cf_spec_session import project_task_session
+
+    projection = project_task_session(refreshed.context, str(task_file), args.task)
+    if projection.truncated:
+        raise ContextError("task_projection_truncated", "task_file", "split the TASK before coding")
+    output = Path(args.session_output) if args.session_output else (
+        Path(args.root) / ".code-flow/specs/_session" / f"task-{task_file.stem}.md"
+    )
+    output.parent.mkdir(parents=True, exist_ok=True)
+    _atomic_text(output, projection.text)
+    active = start_active_task(args.root, args.task_dir, args.task, current_hash, owned)
+    return {
+        "ok": True,
+        "context_sha256": current_hash,
+        "refresh_changes": [item.__dict__ for item in refreshed.changes],
+        "active": _active_data(active),
+        "session_output": str(output),
+        "acceptance_manifest": str(manifest_file) if manifest_file.is_file() else None,
+    }
+
+
 def _status_command(args: argparse.Namespace) -> dict[str, object]:
     """Human-readable Spec Context status: task, marker health, gate, rules."""
     from cf_spec_gate import result_to_data, validate_stage  # local import avoids module cycle
@@ -1413,6 +1519,13 @@ def _parser() -> argparse.ArgumentParser:
         command.add_argument("--task", required=True)
         command.add_argument("--context-sha256", required=True)
         command.add_argument("--json", action="store_true")
+    start = commands.add_parser("start")
+    start.add_argument("--task-dir", required=True)
+    start.add_argument("--root", required=True)
+    start.add_argument("--task", required=True)
+    start.add_argument("--task-file", required=True)
+    start.add_argument("--session-output", default="")
+    start.add_argument("--json", action="store_true")
     return parser
 
 
@@ -1421,6 +1534,8 @@ def _execute(args: argparse.Namespace, stdin: IO[str]) -> dict[str, object]:
         return _catalog_command(args)
     if args.command == "active":
         return _active_command(args, _json_payload(stdin))
+    if args.command == "start":
+        return _start_command(args, _json_payload(stdin))
     context_path = Path(args.task_dir) / "spec-context.yml"
     if args.command == "decision":
         return _decision_command(args, _json_payload(stdin))