@michaelxwb/code-flow 0.6.1 → 0.6.3

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

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""Lock and validate plan Acceptance Coverage entries."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import shlex
+from pathlib import Path
+import re
+import sys
+from typing import IO, Mapping, Optional, Sequence
+
+from cf_acceptance_schema import load_manifest, validate_scenarios
+
+
+_ROW_RE = re.compile(r"^\|\s*([SEB]-\d+)\s*\|(.+?)\|$")
+
+_MANIFEST_SCHEMA = 2
+
+
+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 _parse_command(cell: str, scenario_id: str) -> Optional[list[str]]:
+    """Parse the optional 命令 column: argv JSON array preferred, else shell words.
+
+    Empty / `-` / `planned` → None (not yet registered, not executable).
+    """
+    text = (cell or "").strip()
+    if not text or text in {"-", "planned", "pending", "TBD", "tbd"}:
+        return None
+    if text.startswith("["):
+        try:
+            value = json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"{scenario_id} 命令列不是合法 argv JSON: {exc}") from exc
+        if not isinstance(value, list) or not value or not all(isinstance(item, str) for item in value):
+            raise ValueError(f"{scenario_id} 命令列必须是 argv 字符串数组")
+        return list(value)
+    return shlex.split(text)
+
+
+def _parse_float(cell: str, default: float) -> float:
+    try:
+        return float((cell or "").strip() or default)
+    except (TypeError, ValueError):
+        return default
+
+
+def _manifest_hash(rows: list[dict[str, object]]) -> str:
+    immutable = [
+        {key: item[key] for key in ("id", "source", "level", "kind", "boundary", "owner", "command", "cwd", "timeout", "depends_on")}
+        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, object]] = []
+    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 match.group(1) in seen:
+            raise ValueError(f"duplicate scenario id: {match.group(1)}")
+        if len(fields) < 5:
+            raise ValueError(f"Acceptance Coverage missing columns: {match.group(1)}")
+        seen.add(match.group(1))
+        depends = [item.strip() for item in (fields[8] if len(fields) > 8 else "").split(",") if item.strip()]
+        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],
+            "command": _parse_command(fields[5], match.group(1)) if len(fields) > 5 else None,
+            "cwd": (fields[6] if len(fields) > 6 else "").strip() or ".",
+            "timeout": _parse_float(fields[7], 60.0) if len(fields) > 7 else 60.0,
+            "depends_on": depends,
+        })
+    if not rows:
+        raise ValueError("Acceptance Coverage 缺失或为空")
+    validate_scenarios(rows)
+    return {"schema": _MANIFEST_SCHEMA, "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
+
+
+_IMMUTABLE_SCENARIO_FIELDS = (
+    "id", "source", "level", "kind", "boundary", "owner", "command", "cwd", "timeout", "depends_on",
+)
+
+
+def validate_manifest(task_file: str, manifest_file: str) -> tuple[bool, str]:
+    try:
+        manifest = load_manifest(Path(manifest_file))
+        expected = extract_manifest(task_file)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        return False, f"acceptance_manifest_invalid: {exc}"
+    if manifest.get("schema") != _MANIFEST_SCHEMA or manifest.get("task_sha256") != expected["task_sha256"]:
+        return False, "acceptance_manifest_drift"
+    stored_task = manifest.get("task_file", "")
+    if not stored_task or (Path(manifest_file).parent / stored_task).resolve() != Path(task_file).resolve():
+        return False, "acceptance_manifest_task_mismatch"
+    if not isinstance(manifest.get("scenarios"), list):
+        return False, "acceptance_manifest_scenarios_changed"
+    stored = {
+        item.get("id"): item
+        for item in manifest["scenarios"]
+        if isinstance(item, Mapping) and isinstance(item.get("id"), str)
+    }
+    required = {item["id"] for item in expected["scenarios"]}
+    if set(stored) != required:
+        return False, "acceptance_manifest_scenarios_changed"
+    for item in expected["scenarios"]:
+        current = stored[item["id"]]
+        for field in _IMMUTABLE_SCENARIO_FIELDS:
+            if current.get(field) != item.get(field):
+                return False, f"acceptance_manifest_field_changed:{item['id']}:{field}"
+    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 = re.search(r"(?m)^- \*\*Acceptance-Refs\*\*:[ \t]*([^\n]*)", section.group(0)) if section else None
+        if not refs or scenario["id"] not in re.findall(r"\b[SEB]-\d+\b", refs.group(1)):
+            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 = load_manifest(path)
+    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:
+    from cf_acceptance_evidence import sync_task_evidence
+    sync_task_evidence(task_file, scenario_id, confirmed_by, evidence, owner)
+
+
+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,192 @@
+#!/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 sys
+from typing import IO, Mapping, Optional, Sequence
+
+from cf_exec_base import execution_key, run_command, invalidate_executions
+from cf_acceptance_schema import load_manifest, validate_execution_baseline
+from cf_acceptance_evidence import persist_results
+
+
+def _run(
+    item: Mapping[str, object], root: Path, include_e2e: bool = False, deadline: Optional[float] = None,
+    only_e2e: bool = False,
+) -> dict[str, object]:
+    scenario_id = str(item.get("id", "unknown"))
+    kind = str(item.get("kind", "functional"))
+    if only_e2e and kind != "e2e":
+        return {"id": scenario_id, "kind": kind, "status": "not_included"}
+    if kind == "manual":
+        return {"id": scenario_id, "kind": kind, "status": "manual_pending"}
+    if kind == "e2e" and not include_e2e and not only_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 "."
+    outcome = run_command(command, str(root / cwd), timeout_value, deadline)
+    if outcome["status"] == "deadline_exceeded":
+        return {"id": scenario_id, "kind": kind, "status": "incomplete", "error": "deadline_exceeded"}
+    if outcome["status"] == "timeout":
+        return {"id": scenario_id, "kind": kind, "status": "failed", "error": "timeout",
+                "output": str(outcome.get("stdout", ""))}
+    if outcome["status"] == "spawn_error":
+        return {"id": scenario_id, "kind": kind, "status": "failed", "error": str(outcome.get("stderr", ""))}
+    if outcome["returncode"] == 0:
+        return {"id": scenario_id, "kind": kind, "status": "passed", "exit_code": 0}
+    output = (str(outcome.get("stdout", "")) + str(outcome.get("stderr", ""))).strip()[-4000:]
+    return {"id": scenario_id, "kind": kind, "status": "failed", "exit_code": outcome["returncode"], "output": output}
+
+
+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 _executable(items: list[Mapping[str, object]]) -> bool:
+    """Draft completeness vs execution gate: at least one scenario must be
+    executable — a functional scenario with a registered command, or a
+    manual / e2e scenario with its own confirmation/deferral path. Zero
+    executable scenarios must block execution acceptance, never pass it."""
+    for item in items:
+        command = item.get("command")
+        if isinstance(command, list) and command and all(isinstance(value, str) for value in command):
+            return True
+        if str(item.get("kind", "")) in ("manual", "e2e"):
+            return True
+    return False
+
+
+def _owned(items: list[Mapping[str, object]], owner: str) -> list[Mapping[str, object]]:
+    """Keep scenarios owned by the active TASK; ownerless legacy scenarios stay
+    included so old manifests keep working. Cross-TASK depends_on edges are
+    pruned: single-TASK ordering is enforced here, whole-demand ordering at
+    the final (archive/E2E) gate."""
+    if not owner:
+        return items
+    kept = [
+        item for item in items
+        if not isinstance(item.get("owner"), str) or not item.get("owner") or item.get("owner") == owner
+    ]
+    kept_ids = {str(item.get("id")) for item in kept}
+    pruned: list[Mapping[str, object]] = []
+    for item in kept:
+        if not isinstance(item, dict):
+            pruned.append(item)
+            continue
+        deps = item.get("depends_on")
+        if isinstance(deps, list):
+            item = {**item, "depends_on": [dep for dep in deps if str(dep) in kept_ids]}
+        pruned.append(item)
+    return pruned
+
+
+def _run_unique(
+    ordered: list[Mapping[str, object]], root: Path, include_e2e: bool, deadline: Optional[float] = None,
+    only_e2e: bool = False,
+) -> list[dict[str, object]]:
+    """Reuse identical execution semantics within a dependency-free batch."""
+    cache: dict[str, Mapping[str, object]] = {}
+    results: list[dict[str, object]] = []
+    for item in ordered:
+        scenario_id = str(item.get("id", "unknown"))
+        command = item.get("command")
+        key: Optional[str] = None
+        if isinstance(command, list) and command and all(isinstance(value, str) for value in command):
+            key = execution_key(command, str(root / str(item.get("cwd", "."))), float(item.get("timeout", 60)))
+            key += json.dumps([item.get("kind", "functional"), include_e2e, only_e2e])
+        if item.get("depends_on"):
+            cache.clear()
+            invalidate_executions()
+        if key is not None and key in cache:
+            shared = dict(cache[key])
+            shared["id"] = scenario_id
+            results.append(shared)
+            continue
+        result = _run(item, root, include_e2e, deadline, only_e2e)
+        if key is not None:
+            cache[key] = result
+        results.append(result)
+    return results
+
+
+def run_manifest(
+    manifest_file: str,
+    root: str,
+    write_evidence: bool = False,
+    include_e2e: bool = False,
+    owner: str = "",
+    deadline: Optional[float] = None,
+    only_e2e: bool = False,
+) -> dict[str, object]:
+    data = load_manifest(Path(manifest_file))
+    validate_execution_baseline(Path(manifest_file), data)
+    scenarios = data["scenarios"]
+    _ordered(scenarios)  # Validate the complete DAG before owner filtering.
+    items = _owned(scenarios, owner)
+    ordered = _ordered(items)
+    results = _run_unique(ordered, Path(root), include_e2e or only_e2e, deadline, only_e2e)
+    if write_evidence:
+        persist_results(Path(manifest_file), data, results)
+    if not _executable(items):
+        return {"decision": "block", "results": results, "error": "no_executable_scenarios"}
+    allowed = ("passed", "manual_pending", "e2e_deferred", "not_included")
+    decision = "pass" if all(item["status"] in allowed for item in results) else "block"
+    error = ""
+    if decision == "block":
+        pending = sorted({str(item["id"]) for item in results if item["status"] == "incomplete"})
+        failed = sorted({str(item["id"]) for item in results if item["status"] not in (*allowed, "incomplete")})
+        error = ",".join((["incomplete:" + ",".join(pending)] if pending else []) + (["failed:" + ",".join(failed)] if failed else [])) or "acceptance scenario failed"
+    outcome: dict[str, object] = {"decision": decision, "results": results}
+    if error:
+        outcome["error"] = error
+    return outcome
+
+
+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)")
+    parser.add_argument("--only-e2e", action="store_true", help="Execute only E2E scenarios; functional/manual are reported not_included")
+    parser.add_argument("--owner", default="", help="Only execute scenarios owned by this TASK (plus ownerless legacy ones)")
+    parser.add_argument("--deadline", type=float, default=0.0, help="Absolute monotonic deadline propagated from the entry gate (0 = unbounded)")
+    args = parser.parse_args(argv)
+    try:
+        result = run_manifest(args.manifest, args.root, args.write_evidence, args.include_e2e, args.owner, args.deadline or None, args.only_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_acceptance_schema.py

@@ -0,0 +1,83 @@
+"""Validated acceptance records shared by execution and lifecycle gates."""
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+from typing import Mapping
+
+
+def verified_evidence(row: Mapping[str, object]) -> bool:
+    evidence = row.get("evidence")
+    if row.get("status") != "verified" or not isinstance(evidence, dict):
+        return False
+    if row.get("kind") != "manual":
+        return evidence.get("status") == "passed" and evidence.get("exit_code") == 0
+    author, detail = evidence.get("confirmed_by"), evidence.get("evidence")
+    agents = {"agent", "assistant", "codex", "claude", "opencode", "costrict"}
+    return (isinstance(author, str) and bool(author.strip())
+            and author.strip().lower().split(":", 1)[0] not in agents
+            and isinstance(detail, str) and bool(detail.strip()))
+
+
+def validate_scenarios(value: object) -> list[dict[str, object]]:
+    if not isinstance(value, list):
+        raise ValueError("invalid manifest scenarios: expected list")
+    seen: set[str] = set()
+    for item in value:
+        if not isinstance(item, dict):
+            raise ValueError("invalid scenario: expected object")
+        scenario_id = item.get("id")
+        if not isinstance(scenario_id, str) or not scenario_id.strip():
+            raise ValueError("scenario id missing")
+        if scenario_id in seen:
+            raise ValueError(f"duplicate scenario id: {scenario_id}")
+        seen.add(scenario_id)
+        for field in ("kind", "owner", "cwd"):
+            if field in item and not isinstance(item[field], str):
+                raise ValueError(f"invalid scenario {scenario_id}:{field}")
+        command = item.get("command")
+        if command is not None and (not isinstance(command, list) or not all(isinstance(x, str) for x in command)):
+            raise ValueError(f"invalid scenario {scenario_id}:command")
+        timeout = item.get("timeout", 60)
+        if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError(f"invalid scenario {scenario_id}:timeout")
+        deps = item.get("depends_on", [])
+        if not isinstance(deps, list) or not all(isinstance(x, str) for x in deps):
+            raise ValueError(f"invalid scenario {scenario_id}:depends_on")
+        if "runs" in item and not isinstance(item["runs"], list):
+            raise ValueError(f"invalid scenario {scenario_id}:runs")
+        revision = item.get("revision", 0)
+        if isinstance(revision, bool) or not isinstance(revision, int) or revision < 0:
+            raise ValueError(f"invalid scenario {scenario_id}:revision")
+    for item in value:
+        unknown = set(item.get("depends_on", [])) - seen
+        if unknown:
+            raise ValueError(f"acceptance scenario dependency missing: {', '.join(sorted(unknown))}")
+    return value
+
+
+def load_manifest(path: Path) -> dict[str, object]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError("invalid acceptance manifest: expected object")
+    validate_scenarios(data.get("scenarios"))
+    if "task_file" in data and not isinstance(data["task_file"], str):
+        raise ValueError("invalid acceptance manifest: task_file")
+    return data
+
+
+def validate_execution_baseline(path: Path, data: Mapping[str, object]) -> None:
+    """Legacy standalone manifests remain usable; locked plans must match."""
+    task_name = data.get("task_file")
+    if not isinstance(task_name, str) or not task_name:
+        return
+    task = Path(task_name)
+    task = task if task.is_absolute() else path.parent / task
+    if not task.is_file():
+        raise ValueError(f"acceptance task file missing: {task}")
+    if "## Acceptance Coverage" in task.read_text(encoding="utf-8"):
+        from cf_acceptance_manifest import validate_manifest
+        valid, reason = validate_manifest(str(task), str(path))
+        if not valid:
+            raise ValueError(reason)

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) ---
 
@@ -12,6 +13,12 @@ _effective_mapping_cache: dict = {}
 _ext_set_cache: dict = {}
 
 
+def project_instruction_file(project_root: str, platform: str = "") -> str:
+    """Select the installed platform's instruction file, with legacy fallback."""
+    names = ("CLAUDE.md", "AGENTS.md") if platform in ("claude", "costrict") else ("AGENTS.md", "CLAUDE.md")
+    return next((name for name in names if os.path.isfile(os.path.join(project_root, name))), names[0])
+
+
 def load_config(project_root: str) -> dict:
     config_path = os.path.join(project_root, ".code-flow", "config.yml")
     if not os.path.exists(config_path):
@@ -665,6 +672,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.