@michaelxwb/code-flow 0.6.4 → 0.8.1

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

@@ -1,381 +1,11 @@
 #!/usr/bin/env python3
-"""Stop Hook: run validation.yml checks on session-edited files (FEAT-03).
-
-Flow: session edit events (cf_log) → match validator triggers → run commands
-serially under a total budget → failures surface as {"decision": "block",
-"reason": ...} so the agent fixes them before the session truly ends.
-
-Protocol notes (deviation from the injection-hook contract, recorded in
-TASK-010): the Stop event's feedback channel is decision/reason — there is no
-additionalContext for Stop. `stop_hook_active` is respected so an already
-continued session is never re-blocked (no loops). All-pass → silent exit 0.
-"""
-import fnmatch
-import json
-import math
-import os
-import re
+"""Path-frozen entry shim: implementation lives in codeflow.hooks.cf_stop_hook."""
 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,
-    load_config,
-    normalize_path,
-    resolve_enforcement,
-    resolve_quality_loop,
-    resolve_session_id,
-    timing_log,
-)
-
-TOTAL_BUDGET_SECONDS = 30.0
-GATE_BUDGET_SECONDS = 25.0
-_BRACE_RE = re.compile(r"\{([^{}]+)\}")
-_TASK_SECTION_RE = re.compile(
-    r"(?ms)^## (TASK-\d+):.*?(?=^## TASK-\d+:|\Z)"
-)
-_SCENARIO_RE = re.compile(r"\b[SEB]-\d+\b")
-_UNVERIFIED_RE = re.compile(r"\b(?:planned|pending|tbd)\b", re.IGNORECASE)
-
-
-def expand_braces(pattern: str) -> list:
-    """Expand one level of `{a,b}` alternation → list of fnmatch patterns."""
-    match = _BRACE_RE.search(pattern)
-    if not match:
-        return [pattern]
-    head, tail = pattern[: match.start()], pattern[match.end():]
-    out = []
-    for option in match.group(1).split(","):
-        out.extend(expand_braces(head + option + tail))
-    return out
-
-
-def trigger_matches(trigger: str, rel_path: str) -> bool:
-    """fnmatch with brace expansion; `**/` prefix also matches root files."""
-    rel_path = normalize_path(rel_path)
-    for pattern in expand_braces(trigger or ""):
-        candidates = [pattern]
-        if pattern.startswith("**/"):
-            candidates.append(pattern[3:])
-        if any(fnmatch.fnmatch(rel_path, p) for p in candidates):
-            return True
-    return False
-
-
-def load_validators(project_root: str) -> list:
-    path = os.path.join(project_root, ".code-flow", "validation.yml")
-    if not os.path.exists(path):
-        return []
-    try:
-        import yaml
-        with open(path, "r", encoding="utf-8") as f:
-            data = yaml.safe_load(f) or {}
-        validators = data.get("validators")
-        return validators if isinstance(validators, list) else []
-    except Exception as exc:
-        _log(f"cf_stop_hook validation.yml parse failed: {exc}")
-        return []
-
-
-def session_edited_files(project_root: str, sid: str) -> list:
-    files = []
-    seen = set()
-    for event in cf_log.read_events(project_root, days=2, events=("edit",)):
-        if event.get("sid") != sid:
-            continue
-        rel = (event.get("data") or {}).get("file")
-        if rel and rel not in seen:
-            seen.add(rel)
-            files.append(rel)
-    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:
-        return False
-    return path.endswith(".md") and not path.endswith((".design.md", ".prd.md"))
-
-
-def _subsection(section: str, heading: str) -> str:
-    match = re.search(
-        rf"(?ms)^### {re.escape(heading)}\s*$\n(.*?)(?=^### |^## |\Z)",
-        section,
-    )
-    return match.group(1) if match else ""
-
-
-def _acceptance_gap(task_id: str, section: str, coverage: str) -> str:
-    status = re.search(r"(?m)^- \*\*Status\*\*: ([^\n]+)", section)
-    # 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:
-        return f"{task_id} 缺少 Acceptance-Refs"
-    refs = refs_match.group(1).strip()
-    if refs.upper().startswith("N/A"):
-        return ""
-    scenarios = sorted(set(_SCENARIO_RE.findall(refs)))
-    if not scenarios:
-        return f"{task_id} Acceptance-Refs 未引用 S/E/B 场景"
-    contract = _subsection(section, "Acceptance Contract")
-    evidence = _subsection(section, "Acceptance Evidence")
-    if not contract or not evidence:
-        return f"{task_id} 缺少 Acceptance Contract 或 Acceptance Evidence"
-    for scenario in scenarios:
-        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 ""
-
-
-def task_acceptance_failures(project_root: str, files: list) -> list:
-    """Check new-format task files; legacy tasks without coverage are ignored."""
-    failures = []
-    for rel_path in files:
-        if not _is_active_task_file(rel_path):
-            continue
-        path = os.path.join(project_root, normalize_path(rel_path))
-        try:
-            with open(path, "r", encoding="utf-8") as f:
-                text = f.read()
-        except OSError as exc:
-            _log(f"cf_stop_hook task read failed: {exc}")
-            continue
-        if "## Acceptance Coverage" not in text:
-            continue
-        coverage = text.split("## Acceptance Coverage", 1)[1].split("## TASK-", 1)[0]
-        for match in _TASK_SECTION_RE.finditer(text):
-            detail = _acceptance_gap(match.group(1), match.group(0), coverage)
-            if detail:
-                failures.append({
-                    "name": "任务验收契约",
-                    "on_fail": "补齐设计场景的测试映射与执行证据后再完成任务",
-                    "detail": detail,
-                })
-    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:
-    """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 = remaining_seconds(deadline)
-        if remaining is not None and remaining <= 0:
-            failures.append(_validator_failure(validator, "预算耗尽未执行", True))
-            truncated = True
-            continue
-        try:
-            argv = _validator_argv(project_root, validator, matched, strict)
-        except ValueError as exc:
-            failures.append(_validator_failure(validator, f"validator 配置错误: {exc}"))
-            continue
-        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:
-        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:
-        lines.append("（总预算 30s 已用尽，以上为已完成部分）")
-    lines.append("请修复后再结束。")
-    return "\n".join(lines)
-
-
-def _main() -> None:
-    try:
-        ensure_utf8_io()
-        raw = sys.stdin.read()
-        if not raw.strip():
-            return
-        data = json.loads(raw)
-        if data.get("stop_hook_active"):
-            return  # 已因本 hook 续跑过一轮，避免循环
-        project_root = os.getcwd()
-        sid = resolve_session_id(data)
-        config = load_config(project_root)
-        if not config:
-            return
-        enforcement = resolve_enforcement(config)
-        if enforcement == "inject":
-            return  # 轻量模式：只注入不门禁，停止会话不受限
-        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)
-                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}"}
-                    sys.stdout.write(json.dumps(payload, ensure_ascii=False))
-                    return
-                cf_log.append_event(project_root, "stop_check", {"gate": "invalid_active_nonfatal", "error": str(exc)}, sid)
-                files = []
-            else:
-                if done.decision != "pass":
-                    reason = done.message or "当前 TASK required Spec verifier/Evidence 未通过；修复或重新对齐后再 Done。"
-                    if any(item.get("error_code") == "verifier_budget_exhausted" for item in done.evidence):
-                        reason += "（验证预算不足，部分 verifier 未运行，请拆分 TASK 或减少验证命令）"
-                    if enforcement == "required":
-                        payload = {"decision": "block", "reason": reason}
-                        sys.stdout.write(json.dumps(payload, ensure_ascii=False))
-                        return
-                    cf_log.append_event(project_root, "stop_check", {"gate": "blocked_nonfatal", "reason": reason}, sid)
-                files = list(done.files)
-        if not resolve_quality_loop(config)["stop_check"]:
-            return
-        if not has_active:
-            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 = _stop_validators(project_root)
-        failures, truncated = run_validators(
-            project_root, validators, files, sid, deadline=deadline
-        ) if validators else ([], False)
-        failures = acceptance_failures + failures
-        if not failures:
-            return  # 全过或无 validation.yml 且无验收缺口时静默
-        if enforcement == "warn":
-            cf_log.append_event(
-                project_root, "stop_check",
-                {"failures": [item["name"] for item in failures], "nonfatal": True},
-                sid,
-            )
-            return
-        payload = {"decision": "block", "reason": _reason_text(failures, truncated)}
-        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()
 
+from codeflow.hooks import cf_stop_hook as _impl
 
 if __name__ == "__main__":
-    main()
-    timing_log("cf_stop_hook")
+    _impl.main()
+    _impl.timing_log("cf_stop_hook")
+else:
+    sys.modules[__name__] = _impl

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

@@ -1,140 +1,10 @@
 #!/usr/bin/env python3
-"""cf-sync: one-command canonical → deploy sync for dual-copy artifacts.
-
-Pairs (canonical source → deployed live copy), each with an explicit include
-prefix list — project-owned trees (specs/, tasks/) and deploy-only files
-(config.toml, CLAUDE.md, opencode.json) are never touched:
-
-  src/core/code-flow         → .code-flow        (scripts/, config.yml, .version, validation.yml, .gitignore)
-  src/adapters/claude        → .claude           (commands/, settings.local.json)
-  src/adapters/codex         → .codex            (hooks.json)
-  src/adapters/codex/skills  → .agents/skills    (everything)
-  src/adapters/costrict      → .costrict         (commands/, settings.local.json)
-  src/adapters/opencode      → .opencode         (commands/, plugins/)
-
-`check` (default) reports drift; `sync` copies canonical → deploy. Deploy-only
-files are never deleted (use --prune to remove files whose source side no
-longer contains them within the include prefixes).
-"""
-
-import argparse
-import filecmp
-import os
-from pathlib import Path
-import shutil
+"""Path-frozen entry shim: implementation lives in codeflow.cli.cf_sync."""
 import sys
-from typing import IO, Optional, Sequence
-
-
-PAIRS = (
-    ("src/core/code-flow", ".code-flow", ("scripts/", ".version", ".gitignore")),
-    ("src/adapters/claude", ".claude", ("commands/",)),
-    ("src/adapters/codex", ".codex", ("hooks.json",)),
-    ("src/adapters/codex/skills", ".agents/skills", ("*",)),
-    ("src/adapters/costrict", ".costrict", ("commands/",)),
-    ("src/adapters/opencode", ".opencode", ("commands/", "plugins/")),
-)
-
-_IGNORED_DIRS = {"__pycache__", ".git", "node_modules", "dist", "build"}
-
-
-def _included(relative: str, prefixes: Sequence[str]) -> bool:
-    return any(prefix == "*" or relative.startswith(prefix) for prefix in prefixes)
-
-
-def _walk(source: Path) -> list[str]:
-    files = []
-    for current, dirs, names in os.walk(source):
-        dirs[:] = sorted(item for item in dirs if item not in _IGNORED_DIRS)
-        base = Path(current)
-        for name in names:
-            files.append(str((base / name).relative_to(source)))
-    return sorted(files)
-
-
-def _relative(relative: str) -> str:
-    return relative.replace("\\", "/")
-
-
-def _pair_diffs(root: Path, source_rel: str, deploy_rel: str, prefixes: Sequence[str]) -> tuple[list[str], list[str], list[str]]:
-    """Return (differ, missing_in_deploy, deploy_only_within_prefixes)."""
-    source = root / source_rel
-    deploy = root / deploy_rel
-    differ: list[str] = []
-    missing: list[str] = []
-    for relative in _walk(source):
-        if not _included(_relative(relative), prefixes):
-            continue
-        source_file = source / relative
-        deploy_file = deploy / relative
-        if not deploy_file.exists():
-            missing.append(relative)
-        elif not filecmp.cmp(source_file, deploy_file, shallow=False):
-            differ.append(relative)
-    deploy_only: list[str] = []
-    if deploy.is_dir():
-        deploy_relative = set(_walk(deploy))
-        source_relative = {_relative(item) for item in _walk(source) if _included(_relative(item), prefixes)}
-        deploy_only = sorted(item for item in deploy_relative if item not in source_relative and _included(item, prefixes))
-    return differ, missing, deploy_only
-
-
-def _report(stdout: IO[str], root: Path, verbose: bool) -> int:
-    drift = 0
-    for source_rel, deploy_rel, prefixes in PAIRS:
-        differ, missing, deploy_only = _pair_diffs(root, source_rel, deploy_rel, prefixes)
-        status = "OK " if not (differ or missing) else "DRIFT"
-        stdout.write(f"{status} {source_rel} -> {deploy_rel}\n")
-        for relative in differ:
-            stdout.write(f"  diff  {deploy_rel}/{relative}\n")
-            drift += 1
-        for relative in missing:
-            stdout.write(f"  miss  {deploy_rel}/{relative}\n")
-            drift += 1
-        if verbose and deploy_only:
-            stdout.write(f"  only-in-deploy ({len(deploy_only)}):\n")
-            for relative in deploy_only[:10]:
-                stdout.write(f"    {deploy_rel}/{relative}\n")
-    return drift
-
-
-def _sync(root: Path, stdout: IO[str]) -> int:
-    copied = 0
-    for source_rel, deploy_rel, prefixes in PAIRS:
-        source = root / source_rel
-        deploy = root / deploy_rel
-        for relative in _walk(source):
-            if not _included(_relative(relative), prefixes):
-                continue
-            source_file = source / relative
-            deploy_file = deploy / relative
-            if deploy_file.exists() and filecmp.cmp(source_file, deploy_file, shallow=False):
-                continue
-            deploy_file.parent.mkdir(parents=True, exist_ok=True)
-            shutil.copy2(source_file, deploy_file)
-            stdout.write(f"sync  {deploy_rel}/{relative}\n")
-            copied += 1
-    return copied
-
-
-def main(argv: Optional[Sequence[str]] = None, stdout: IO[str] = sys.stdout) -> int:
-    parser = argparse.ArgumentParser(prog="cf_sync.py")
-    parser.add_argument("action", choices=("check", "sync"), nargs="?", default="check")
-    parser.add_argument("--root", default=".")
-    parser.add_argument("--verbose", action="store_true")
-    args = parser.parse_args(argv)
-    root = Path(args.root).resolve()
-    if args.action == "check":
-        drift = _report(stdout, root, args.verbose)
-        if drift:
-            stdout.write(f"{drift} file(s) drifted; run `cf_sync.py sync` to deploy.\n")
-            return 1
-        stdout.write("all pairs in sync.\n")
-        return 0
-    copied = _sync(root, stdout)
-    stdout.write(f"{copied} file(s) deployed.\n")
-    return 0
 
+from codeflow.cli import cf_sync as _impl
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    raise SystemExit(_impl.main())
+else:
+    sys.modules[__name__] = _impl

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

@@ -1,148 +1,10 @@
 #!/usr/bin/env python3
-"""Programmatic task-file index: parse TASK statuses/depends, compute DAG batches.
-
-Single worktrees allow one active TASK at a time; batches list *independently
-developable* tasks (no dependency path between them). `cf-task:start` may
-dispatch batch tasks in their own worktrees for parallel subagents — the
-single-active constraint stays per worktree.
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import re
+"""Path-frozen entry shim: implementation lives in codeflow.cli.cf_task_index."""
 import sys
-from dataclasses import dataclass
-from pathlib import Path
-from typing import IO, Mapping, Optional, Sequence
-
-
-from cf_task_state import FINISHED_STATUSES as _DONE_STATUSES
-
-
-@dataclass(frozen=True)
-class TaskNode:
-    task_id: str
-    status: str
-    depends: tuple[str, ...]
-
-
-def parse_task_file(task_file: str) -> tuple[TaskNode, ...]:
-    """Parse every `## TASK-xxx` section into status/depends nodes.
-
-    Unknown statuses are preserved verbatim (e.g. `verified` from the E2E
-    flow) — the parser never rejects them, completion checks treat done and
-    verified as finished.
-    """
-    try:
-        text = Path(task_file).read_text(encoding="utf-8")
-    except (OSError, UnicodeError) as exc:
-        raise ValueError(f"task_read_error: {exc}") from exc
-    nodes: list[TaskNode] = []
-    matches = list(re.finditer(r"(?m)^## (TASK-\d+):[^\n]*$", text))
-    for index, match in enumerate(matches):
-        end = matches[index + 1].start() if index + 1 < len(matches) else len(text)
-        section = text[match.start():end]
-        status_match = re.search(r"(?m)^- \*\*Status\*\*:[ \t]*([^\n]+)", section)
-        status = status_match.group(1).strip() if status_match else "draft"
-        depends_match = re.search(r"(?m)^- \*\*Depends\*\*:[ \t]*([^\n]*)", section)
-        depends: tuple[str, ...] = ()
-        if depends_match:
-            depends = tuple(
-                part.strip()
-                for part in re.split(r"[,，\s]+", depends_match.group(1).strip())
-                if re.fullmatch(r"TASK-\d+", part.strip())
-            )
-        nodes.append(TaskNode(match.group(1), status, depends))
-    if not nodes:
-        raise ValueError("no TASK sections found")
-    return tuple(nodes)
-
-
-def task_batches(nodes: Sequence[TaskNode]) -> list[list[str]]:
-    """Topological batches over unfinished TASKs; unknown deps and cycles raise."""
-    ids = {node.task_id for node in nodes}
-    for node in nodes:
-        unknown = [dep for dep in node.depends if dep not in ids]
-        if unknown:
-            raise ValueError(f"unknown depends: {node.task_id} -> {', '.join(unknown)}")
-    pending = {node.task_id for node in nodes if node.status not in _DONE_STATUSES}
-    finished = {node.task_id for node in nodes if node.status in _DONE_STATUSES}
-    deps = {node.task_id: set(node.depends) for node in nodes}
-    batches: list[list[str]] = []
-    while pending:
-        ready = sorted(task for task in pending if deps[task] <= finished)
-        if not ready:
-            raise ValueError(f"dependency cycle among: {', '.join(sorted(pending))}")
-        batches.append(ready)
-        finished.update(ready)
-        pending.difference_update(ready)
-    return batches
-
-
-def dependency_components(nodes: Sequence[TaskNode]) -> list[list[str]]:
-    """Connected dependency components; different components are independent."""
-    parent = {node.task_id: node.task_id for node in nodes}
-
-    def find(task: str) -> str:
-        while parent[task] != task:
-            parent[task] = parent[parent[task]]
-            task = parent[task]
-        return task
-
-    for node in nodes:
-        for dep in node.depends:
-            left, right = find(node.task_id), find(dep)
-            if left != right:
-                parent[left] = right
-    groups: dict[str, list[str]] = {}
-    for node in nodes:
-        groups.setdefault(find(node.task_id), []).append(node.task_id)
-    return [sorted(members) for members in groups.values()]
-
-
-def independent_groups(nodes: Sequence[TaskNode]) -> list[list[str]]:
-    """Compatibility alias: groups are independent of each other, not within."""
-    return dependency_components(nodes)
-
-
-def index_data(task_file: str) -> dict[str, object]:
-    nodes = parse_task_file(task_file)
-    return {
-        "tasks": [
-            {"id": node.task_id, "status": node.status, "depends": list(node.depends)}
-            for node in nodes
-        ],
-        "batches": task_batches(nodes),
-        "independent_groups": independent_groups(nodes),
-        "dependency_components": dependency_components(nodes),
-        "note": "batches 组内无依赖；dependency_components 仅组间独立（independent_groups 为兼容别名）；单 worktree 一次仅激活一个 TASK，批次内独立任务可由 cf-task:start 在各 worktree 并行派发",
-    }
-
-
-def main(argv: Optional[Sequence[str]] = None, stdout: IO[str] = sys.stdout) -> int:
-    parser = argparse.ArgumentParser(prog="cf_task_index.py")
-    parser.add_argument("--task-file", required=True)
-    parser.add_argument("--dag", action="store_true", help="输出拓扑批次与独立分组")
-    parser.add_argument("--json", action="store_true")
-    args = parser.parse_args(argv)
-    try:
-        data = index_data(args.task_file)
-    except (OSError, ValueError) as exc:
-        stdout.write(json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False))
-        return 2
-    if args.json or args.dag:
-        stdout.write(json.dumps(data, ensure_ascii=False))
-    else:
-        lines = ["TASK 索引:"]
-        for item in data["tasks"]:
-            lines.append(f"  - {item['id']}: {item['status']} (依赖: {', '.join(item['depends']) or '无'})")
-        for index, batch in enumerate(data["batches"], 1):
-            lines.append(f"批次 {index}（可独立开发）: {', '.join(batch)}")
-        stdout.write("\n".join(lines) + "\n")
-    return 0
 
+from codeflow.cli import cf_task_index as _impl
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    raise SystemExit(_impl.main())
+else:
+    sys.modules[__name__] = _impl