@michaelxwb/code-flow 0.6.2 → 0.6.3

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

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

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

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

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

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

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

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Programmatic task-file index: parse TASK statuses/depends, compute DAG batches.
+
+Single worktrees allow one active TASK at a time, so "parallel" below means
+*independently developable* (no dependency path between them) — not
+simultaneously activatable, a distinction `cf-task:graph` used to blur.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+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",
+    }
+
+
+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
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())