@michaelxwb/code-flow 0.6.5 → 0.8.1

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

@@ -1,304 +0,0 @@
-#!/usr/bin/env python3
-"""Active-task scope expansion and hash-bound Done verification."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, replace
-import hashlib
-import json
-from pathlib import Path
-import time
-from typing import Mapping, Optional
-
-from cf_spec_context import (
-    BindingInput,
-    RuleBinding,
-    RuleStageStatus,
-    SpecBinding,
-    SpecContext,
-    bind_specs,
-    current_owned_paths,
-    load_active_task,
-    load_context,
-    pause_active_task,
-    resync_active_hash,
-    save_context,
-)
-from cf_spec_gate import validate_stage
-from cf_spec_metadata import load_spec_metadata
-from cf_spec_resolver import resolve_candidates, SpecCandidate
-from cf_spec_session import context_sha256
-from cf_spec_verify import VerificationEvidence, VerificationScope, run_all_verifiers
-from cf_core import load_config, phase_timing, resolve_quality_loop
-from cf_acceptance_schema import load_manifest, validate_execution_baseline, verified_evidence
-from cf_exec_base import execution_session
-
-
-@dataclass(frozen=True)
-class ScopeResult:
-    decision: str
-    files: tuple[str, ...]
-    new_specs: tuple[str, ...]
-    message: str
-
-
-@dataclass(frozen=True)
-class DoneResult:
-    decision: str
-    files: tuple[str, ...]
-    evidence: tuple[Mapping[str, object], ...]
-    message: str = ""
-    deferred_review: int = 0
-
-
-def _context_path(task_dir: str) -> str:
-    return str(Path(task_dir) / "spec-context.yml")
-
-
-def _manual_manifest_issue(task_dir: str, owner: str = "") -> str:
-    path = Path(task_dir) / ".acceptance-manifest.json"
-    if not path.is_file():
-        return ""
-    try:
-        import json
-
-        data = load_manifest(path)
-        pending = [
-            item.get("id", "unknown")
-            for item in data.get("scenarios", [])
-            if item.get("kind") == "manual" and not verified_evidence(item)
-            and (not owner or not isinstance(item.get("owner"), str) or not item.get("owner") or item.get("owner") == owner)
-        ]
-        return f"manual 场景未完成: {', '.join(pending)}" if pending else ""
-    except (OSError, ValueError, TypeError):
-        return "acceptance manifest invalid"
-
-
-def _acceptance_baseline_issue(task_dir: str, owner: str) -> str:
-    from cf_workflow_service import locate_task_file
-    path = Path(task_dir) / ".acceptance-manifest.json"
-    task = locate_task_file(task_dir, owner)
-    try:
-        requires = task is not None and "## Acceptance Coverage" in task.read_text(encoding="utf-8")
-        if not path.is_file():
-            return "acceptance_manifest_missing" if requires else ""
-        data = load_manifest(path)
-        if requires:
-            from cf_acceptance_manifest import validate_manifest
-            valid, reason = validate_manifest(str(task), str(path))
-            if not valid:
-                return reason
-        validate_execution_baseline(path, data)
-        return ""
-    except (OSError, ValueError) as exc:
-        return f"acceptance_manifest_invalid: {exc}"
-
-
-def _required_candidate(candidate: SpecCandidate) -> bool:
-    metadata = candidate.metadata
-    return metadata.enforcement == "required" and any(
-        rule.enforcement == "required" for rule in metadata.rules
-    )
-
-
-def evaluate_scope(root: str, task_dir: str) -> ScopeResult:
-    active = load_active_task(root)
-    files = current_owned_paths(root, active)
-    context = load_context(_context_path(task_dir))
-    candidates = resolve_candidates(root, "code", files)
-    existing = {binding.spec_id for binding in context.bindings}
-    new = tuple(
-        candidate
-        for candidate in candidates
-        if candidate.scope == "path" and candidate.spec_id not in existing
-    )
-    if not new:
-        return ScopeResult("continue", files, (), "scope unchanged")
-    selections = tuple(
-        BindingInput(candidate, "scope:path", f"Git diff matched {','.join(candidate.matched_paths)}")
-        for candidate in new
-    )
-    save_context(_context_path(task_dir), bind_specs(context, selections))
-    # The toolchain expanded the context itself; re-sync the marker so this
-    # automatic change does not surface as active_context_drift with no recovery.
-    resync_active_hash(root, task_dir, context_sha256(load_context(_context_path(task_dir))))
-    required = tuple(candidate.spec_id for candidate in new if _required_candidate(candidate))
-    if required:
-        pause_active_task(root)
-        message = "新增 required Spec 已暂停 TASK；请选择局部 Plan 或回 Align 更新设计"
-        return ScopeResult("pause", files, required, message)
-    return ScopeResult("continue", files, tuple(candidate.spec_id for candidate in new), "advisory scope expanded")
-
-
-def _diff_hash(root: str, files: tuple[str, ...]) -> str:
-    digest = hashlib.sha256()
-    for relative in files:
-        path = Path(root) / relative
-        digest.update(relative.encode())
-        digest.update(path.read_bytes() if path.is_file() else b"<deleted>")
-    return digest.hexdigest()
-
-
-def _evidence_data(evidence: VerificationEvidence) -> Mapping[str, object]:
-    return {
-        "verifier_ref": evidence.verifier_ref,
-        "executed_at": evidence.executed_at,
-        "status": evidence.status,
-        "rule_text_sha256": evidence.rule_text_sha256,
-        "artifact_sha256": evidence.artifact_sha256,
-        "diff_sha256": evidence.diff_sha256,
-        "result_sha256": evidence.result_sha256,
-        "error_code": evidence.error_code,
-        "details": evidence.details,
-    }
-
-
-def _update_rule(rule: RuleBinding, evidence: Mapping[str, object]) -> RuleBinding:
-    stage = rule.verifier_stage or "code"
-    if stage not in rule.stage_status:
-        return rule
-    statuses = dict(rule.stage_status)
-    current = statuses[stage]
-    if current.status in ("not_applicable", "waived"):
-        return rule
-    status = "verified" if evidence.get("status") == "verified" else "unverified"
-    if evidence.get("error_code") == "skipped_in_cheap_gate":
-        signature = (evidence.get("verifier_ref"), evidence.get("result_sha256"), None)
-    else:
-        signature = (evidence.get("verifier_ref"), evidence.get("result_sha256"), evidence.get("diff_sha256"))
-    if any(
-        (item.get("verifier_ref"), item.get("result_sha256"), item.get("diff_sha256")) == signature
-        for item in current.evidence
-    ):
-        statuses[stage] = replace(current, status=status)
-    else:
-        statuses[stage] = replace(current, status=status, evidence=(*current.evidence, evidence))
-    return replace(rule, stage_status=statuses)
-
-
-def _apply_evidence(context: SpecContext, evidence: tuple[Mapping[str, object], ...]) -> SpecContext:
-    by_ref = {str(item["verifier_ref"]): item for item in evidence}
-    bindings: list[SpecBinding] = []
-    for binding in context.bindings:
-        rules = tuple(
-            _update_rule(rule, by_ref[f"{binding.spec_id}#{rule.ref}"])
-            if f"{binding.spec_id}#{rule.ref}" in by_ref else rule
-            for rule in binding.rules
-        )
-        bindings.append(replace(binding, rules=rules))
-    return replace(context, bindings=tuple(bindings))
-
-
-def _rule_manual_confirmation(rule: RuleBinding) -> Optional[Mapping[str, object]]:
-    status = rule.stage_status.get("code")
-    if status is None or status.decision is None or status.decision.kind != "manual_verification":
-        return None
-    decision = status.decision
-    return {
-        "reason": decision.reason,
-        "confirmed_by": decision.confirmed_by,
-        "confirmed_at": decision.confirmed_at,
-        "source": decision.source,
-    }
-
-
-def _run_acceptance(root: str, task_dir: str, owner: str, include_e2e: bool,
-                    deadline: Optional[float], cheap: bool = False) -> str:
-    baseline_issue = _acceptance_baseline_issue(task_dir, owner)
-    if baseline_issue:
-        return baseline_issue
-    manual_issue = _manual_manifest_issue(task_dir, owner)
-    if manual_issue:
-        return manual_issue
-    if cheap:
-        # 轻量门禁：只做 manifest 基线与 manual 检查，不执行 functional 场景；
-        # 场景命令由 finish 的全量 Done Gate 执行。
-        return ""
-    manifest_path = Path(task_dir) / ".acceptance-manifest.json"
-    if manifest_path.is_file():
-        from cf_acceptance_runner import run_manifest
-        scenario_result = run_manifest(str(manifest_path), root, write_evidence=True, include_e2e=include_e2e, owner=owner, deadline=deadline)
-        if scenario_result["decision"] == "block":
-            reason = scenario_result.get("error") or "acceptance scenario failed"
-            return f"acceptance scenario failed: {reason}"
-    return ""
-
-
-def _run_finish_validation(root: str, files: tuple[str, ...]) -> str:
-    """Full validation.yml (including heavy validators) once per TASK finish.
-
-    Stop-time checks stay cheap; this is the single automatic execution point
-    for slow suites (task finish `/cf-validate` scope). `quality_loop.finish_check:
-    false` disables it; projects without validation.yml / package.json scripts are a no-op.
-    """
-    if not resolve_quality_loop(load_config(root)).get("finish_check"):
-        return ""
-    from cf_validation import validate_files
-
-    try:
-        result = validate_files(root, files)
-    except (OSError, ValueError) as exc:
-        return f"finish validation error: {exc}"
-    reason = result.get("reason")
-    if result.get("decision") == "pass" or reason in ("no_changes", "no_validators_configured"):
-        return ""
-    failures = result.get("failures")
-    names = ", ".join(str(item.get("name", "validator")) for item in failures[:3]) if isinstance(failures, list) and failures else "validator"
-    if result.get("incomplete") and not failures:
-        return "finish validation 预算耗尽：部分 validator 未执行"
-    suffix = "（预算耗尽，部分未执行）" if result.get("incomplete") else ""
-    return f"finish validation failed{suffix}: {names}"
-
-
-def _run_done_gate(root: str, task_dir: str, cheap: bool = False, budget: Optional[float] = None, include_e2e: bool = False, task_id: str = "") -> DoneResult:
-    active = load_active_task(root)
-    owner = task_id or active.task_id
-    if owner != active.task_id or (Path(root) / active.task_dir).resolve() != Path(task_dir).resolve():
-        return DoneResult("block", (), (), "active_mismatch: task identity does not match marker")
-    started = time.monotonic()
-    scope_result = evaluate_scope(root, task_dir)
-    phase_timing("done.evaluate_scope", started)
-    if scope_result.decision == "pause":
-        return DoneResult("block", scope_result.files, (), scope_result.message)
-    deadline = started + budget if budget is not None else None
-    issue = _run_acceptance(root, task_dir, owner, include_e2e, deadline, cheap)
-    if issue:
-        return DoneResult("block", scope_result.files, (), issue)
-    phase_started = time.monotonic()
-    context = load_context(_context_path(task_dir))
-    diff_hash = _diff_hash(root, scope_result.files)
-    phase_timing("done.load_context_and_diff", phase_started)
-    all_evidence: list[Mapping[str, object]] = []
-    deferred_review = 0
-    for binding in context.bindings:
-        phase_started = time.monotonic()
-        metadata = load_spec_metadata(str(Path(root) / ".code-flow/specs" / binding.path))
-        deferred_review += sum(1 for rule in binding.rules if rule.verifier_stage == "review")
-        confirmations: dict[str, Mapping[str, object]] = {}
-        for rule in binding.rules:
-            confirmation = _rule_manual_confirmation(rule)
-            if confirmation is not None:
-                confirmations[rule.ref] = confirmation
-        remaining = None if budget is None else budget - (time.monotonic() - started)
-        result = run_all_verifiers(
-            metadata, VerificationScope(root, scope_result.files, diff_hash), confirmations, cheap, remaining,
-            stage="code",
-        )
-        phase_timing(f"done.verify.{binding.spec_id}", phase_started)
-        all_evidence.extend(_evidence_data(item) for item in result.evidence)
-    updated = _apply_evidence(context, tuple(all_evidence))
-    if updated != context:
-        save_context(_context_path(task_dir), updated)
-    gate = validate_stage(updated, "code", diff_sha256=diff_hash, allow_cheap_skips=cheap)
-    if gate.decision == "pass" and not cheap:
-        validation_issue = _run_finish_validation(root, scope_result.files)
-        if validation_issue:
-            return DoneResult("block", scope_result.files, tuple(all_evidence), validation_issue, deferred_review)
-    phase_timing("done.total", started)
-    return DoneResult(gate.decision, scope_result.files, tuple(all_evidence),
-                      "; ".join(issue.message for issue in gate.errors), deferred_review)
-
-
-def run_done_gate(root: str, task_dir: str, cheap: bool = False, budget: Optional[float] = None, include_e2e: bool = False, task_id: str = "") -> DoneResult:
-    with execution_session():
-        return _run_done_gate(root, task_dir, cheap, budget, include_e2e, task_id)

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

@@ -1,3 +0,0 @@
-"""Shared lifecycle predicates without loading the workflow runtime."""
-
-FINISHED_STATUSES = ("done", "verified")

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

@@ -1,366 +0,0 @@
-#!/usr/bin/env python3
-"""Unified workflow state machine: single entry for task state transitions.
-
-Markdown task files are a readable view; the active marker plus Context are
-the facts. Every transition below validates preconditions, mutates the marker
-through cf_spec_context primitives, and syncs the Markdown view in the same
-call with a recovery journal. Interrupted transitions can be rolled forward;
-concurrent user edits block recovery instead of being overwritten.
-"""
-
-from __future__ import annotations
-
-import re
-import json
-from dataclasses import replace
-from datetime import date
-from pathlib import Path
-from typing import Mapping, Optional, Sequence
-from cf_spec_context import ActiveTask, SpecContext
-from cf_workflow_transaction import recover_transition
-from cf_task_state import FINISHED_STATUSES
-
-
-class WorkflowError(ValueError):
-    """Fail-closed transition error with a stable code."""
-
-    def __init__(self, code: str, message: str, details: tuple[str, ...] = ()) -> None:
-        self.code = code
-        self.details = details
-        super().__init__(f"[{code}] {message}" + (f": {'; '.join(details)}" if details else ""))
-
-
-def locate_task_file(task_dir: str, task_id: str) -> Optional[Path]:
-    """Find the unique task file containing the TASK section."""
-    matches: list[Path] = []
-    try:
-        files = sorted(Path(task_dir).glob("*.md"))
-    except OSError:
-        return None
-    for path in files:
-        if path.name.endswith((".prd.md", ".design.md")):
-            continue
-        try:
-            content = path.read_text(encoding="utf-8")
-        except (OSError, UnicodeError):
-            continue
-        if f"## {task_id}:" in content:
-            matches.append(path)
-    return matches[0] if len(matches) == 1 else None
-
-
-def read_task_section(task_file: str, task_id: str) -> str:
-    try:
-        text = Path(task_file).read_text(encoding="utf-8")
-    except (OSError, UnicodeError) as exc:
-        raise WorkflowError("task_read_error", str(exc)) from exc
-    start = text.find(f"## {task_id}:")
-    if start == -1:
-        raise WorkflowError("task_not_found", task_id, (task_file,))
-    end = text.find("\n## TASK-", start)
-    return text[start:] if end == -1 else text[start:end]
-
-
-def section_status(section: str) -> str:
-    """Markdown status; absent Status line means draft (pre-contract tasks)."""
-    match = re.search(r"(?m)^- \*\*Status\*\*:[ \t]*([^\n]+)", section)
-    return match.group(1).strip() if match else "draft"
-
-
-def section_depends(section: str) -> tuple[str, ...]:
-    match = re.search(r"(?m)^- \*\*Depends\*\*:[ \t]*([^\n]*)", section)
-    if match is None:
-        return ()
-    return tuple(part.strip() for part in re.split(r"[,，\s]+", match.group(1).strip()) if re.fullmatch(r"TASK-\d+", part.strip()))
-
-
-def section_notes(section: str) -> tuple[str, ...]:
-    return tuple(
-        line.strip()
-        for line in section.splitlines()
-        if "#NOTES" in line
-    )
-
-
-def _all_statuses(task_file: str) -> Mapping[str, str]:
-    try:
-        text = Path(task_file).read_text(encoding="utf-8")
-    except (OSError, UnicodeError):
-        return {}
-    statuses: dict[str, str] = {}
-    for match in re.finditer(r"(?m)^## (TASK-\d+):[^\n]*$", text):
-        section = read_task_section(task_file, match.group(1))
-        statuses[match.group(1)] = section_status(section)
-    return statuses
-
-
-def check_startable(task_file: str, task_id: str) -> list[str]:
-    """Collectors of start blockers; empty means the TASK may start."""
-    section = read_task_section(task_file, task_id)
-    status = section_status(section)
-    blockers: list[str] = []
-    if status == "blocked":
-        blockers.append(f"{task_id} is blocked; resolve Log BLOCKED entries first")
-    elif status == "done":
-        blockers.append(f"{task_id} is already done; verify contract or reopen explicitly")
-    elif status not in ("draft", "in-progress"):
-        blockers.append(f"{task_id} has unexpected status '{status}'")
-    notes = section_notes(section)
-    if notes:
-        blockers.append(f"{len(notes)} unresolved #NOTES: {notes[0][:80]}")
-    statuses = _all_statuses(task_file)
-    unmet = [dep for dep in section_depends(section) if statuses.get(dep) not in FINISHED_STATUSES]
-    if unmet:
-        rendered = ", ".join(dep + "(" + str(statuses.get(dep, "missing")) + ")" for dep in unmet)
-        blockers.append("unmet depends: " + rendered)
-    return blockers
-
-
-def _today() -> str:
-    return date.today().isoformat()
-
-
-def _set_status(section: str, status: str, log_line: str = "") -> str:
-    if re.search(r"(?m)^- \*\*Status\*\*:", section):
-        section = re.sub(r"(?m)^- \*\*Status\*\*:.*$", f"- **Status**: {status}", section, count=1)
-    else:
-        anchor = re.search(r"(?m)^## TASK-\d+:.*$", section)
-        insert_at = anchor.end() if anchor else 0
-        section = section[:insert_at] + f"\n- **Status**: {status}" + section[insert_at:]
-    if log_line and log_line not in section.splitlines():
-        section = section.rstrip() + ("\n" if "### Log" in section else "\n\n### Log\n") + log_line + "\n"
-    return section
-
-
-def _render_markdown(text: str, task_id: str, status: str, log_line: str = "", prepend: str = "") -> str:
-    match = re.search(rf"(?ms)^## {re.escape(task_id)}:.*?(?=^## |\Z)", text)
-    if match is None:
-        raise WorkflowError("task_not_found", task_id)
-    section = _set_status(match.group(0), status, log_line)
-    if prepend and prepend not in section:
-        section = section.replace("### Log", prepend + "\n### Log", 1) if "### Log" in section else section + "\n" + prepend + "\n"
-    text = text[:match.start()] + section + text[match.end():]
-    return re.sub(r"(?m)^- \*\*Updated\*\*:.*$", f"- **Updated**: {_today()}", text, count=1)
-
-
-def _sync_markdown(task_file: str, task_id: str, status: str, log_line: str = "", prepend: str = "") -> str:
-    from cf_spec_context import _atomic_text
-    target = Path(task_file)
-    text = target.read_text(encoding="utf-8")
-    _atomic_text(target, _render_markdown(text, task_id, status, log_line, prepend))
-    return "synced"
-
-
-def _commit_state(root: str, task_file: str, task_id: str, status: str, previous: Optional[ActiveTask],
-                  updated: Optional[ActiveTask], log_line: str = "", prepend: str = "") -> str:
-    from cf_spec_context import _active_data
-    from cf_workflow_transaction import commit_transition
-    marker = Path(root) / ".code-flow/.active-task.json"
-    marker_before = marker.read_text(encoding="utf-8") if marker.exists() else None
-    actual = json.loads(marker_before) if marker_before is not None else None
-    expected = _active_data(previous) if previous is not None else None
-    if actual != expected:
-        raise WorkflowError("active_mismatch", "active task changed before commit")
-    marker_after = json.dumps(_active_data(updated), ensure_ascii=False, indent=2) + "\n" if updated is not None else None
-    task = Path(task_file)
-    before = task.read_text(encoding="utf-8")
-    after = _render_markdown(before, task_id, status, log_line, prepend)
-    try:
-        commit_transition(root, task, before, after, marker_before, marker_after)
-    except (OSError, ValueError) as exc:
-        raise WorkflowError("transition_failed", str(exc)) from exc
-    return "synced"
-
-
-def _resolve_paths(root: str, task_dir: str, task_file: str) -> tuple[Path, Path]:
-    base = Path(root)
-    directory = Path(task_dir) if Path(task_dir).is_absolute() else base / task_dir
-    candidate = Path(task_file) if Path(task_file).is_absolute() else base / task_file
-    if base.resolve() not in candidate.resolve().parents or candidate.parent.resolve() != directory.resolve() or not candidate.is_file():
-        raise WorkflowError("invalid_task_file", str(candidate), (str(directory),))
-    return directory, candidate
-
-
-def _validate_start_manifest(directory: Path, candidate: Path) -> None:
-    if "## Acceptance Coverage" not in candidate.read_text(encoding="utf-8"):
-        return
-    manifest_file = directory / ".acceptance-manifest.json"
-    if not manifest_file.is_file():
-        raise WorkflowError("acceptance_manifest_missing", str(manifest_file), ("run plan verification and lock the manifest",))
-    from cf_acceptance_manifest import validate_manifest
-    valid, reason = validate_manifest(str(candidate), str(manifest_file))
-    if not valid:
-        raise WorkflowError(reason or "acceptance_manifest_invalid", str(manifest_file), ("run plan verification before coding",))
-
-
-def _write_projection(root: str, candidate: Path, context: SpecContext, task_id: str, session_output: str) -> Path:
-    from cf_spec_context import _atomic_text
-    from cf_spec_session import project_task_session
-    try:
-        projection = project_task_session(context, str(candidate), task_id)
-    except ValueError as exc:
-        raise WorkflowError("task_projection_failed", str(exc)) from exc
-    if projection.truncated:
-        raise WorkflowError("task_projection_truncated", task_id, ("split the TASK before coding",))
-    output = Path(session_output) if session_output else (
-        Path(root) / ".code-flow/specs/_session" / f"task-{candidate.stem}.md"
-    )
-    try:
-        output.parent.mkdir(parents=True, exist_ok=True)
-        _atomic_text(output, projection.text)
-    except (OSError, ValueError) as exc:
-        raise WorkflowError("session_write_failed", str(exc)) from exc
-    return output
-
-
-def start_task(
-    root: str,
-    task_dir: str,
-    task_file: str,
-    task_id: str,
-    owned_paths: Sequence[str] = (),
-    session_output: str = "",
-) -> dict[str, object]:
-    """Full Start Gate: hard preconditions first, then the guarded pipeline
-    (refresh → manifest check → projection → activation), then the Markdown
-    view flips to in-progress in the same call."""
-    from cf_spec_context import load_context, refresh_context, save_context, _new_active
-    from cf_spec_session import context_sha256
-
-    recover_transition(root)
-    directory, candidate = _resolve_paths(root, task_dir, task_file)
-    blockers = check_startable(str(candidate), task_id)
-    marker_active = (Path(root) / ".code-flow" / ".active-task.json").exists()
-    if marker_active:
-        blockers = [f"active_exists: run cf-spec doctor before starting {task_id}"] + blockers
-    if blockers:
-        raise WorkflowError("start_blocked", task_id, tuple(blockers))
-
-    context_path = directory / "spec-context.yml"
-    refreshed = refresh_context(load_context(str(context_path)), root, artifact_root=str(directory))
-    save_context(str(context_path), refreshed.context)
-    # No marker exists at this point (active_exists raised above), so no
-    # re-sync is needed before activation below.
-    current_hash = context_sha256(refreshed.context)
-    owned = tuple(item for item in owned_paths if isinstance(item, str))
-    _validate_start_manifest(directory, candidate)
-    output = _write_projection(root, candidate, refreshed.context, task_id, session_output)
-    try:
-        active = replace(_new_active(root, str(directory), task_id, current_hash, owned), status="active")
-        markdown = _commit_state(root, str(candidate), task_id, "in-progress", None, active, f"- [{_today()}] started")
-    except Exception as exc:
-        code = getattr(exc, "code", "activation_failed") if isinstance(exc, ValueError) else "activation_failed"
-        raise WorkflowError(str(code), str(exc)) from exc
-    from cf_spec_context import _active_data
-
-    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(directory / ".acceptance-manifest.json") if (directory / ".acceptance-manifest.json").is_file() else None,
-        "markdown": markdown,
-    }
-
-
-def _require_marker_task(root: str, task_id: str, task_dir: str, task_file: str) -> None:
-    from cf_spec_context import ContextError, load_active_task
-
-    recover_transition(root)
-    try:
-        active = load_active_task(root)
-    except (ContextError, OSError, ValueError) as exc:
-        raise WorkflowError("no_active_task", str(exc)) from exc
-    directory, candidate = _resolve_paths(root, task_dir, task_file)
-    if active.task_id != task_id or (Path(root) / active.task_dir).resolve() != directory.resolve():
-        raise WorkflowError("active_mismatch", f"marker={active.task_id} requested={task_id}")
-    located = locate_task_file(str(directory), task_id)
-    if located is None or located.resolve() != candidate.resolve():
-        raise WorkflowError("active_mismatch", "TASK file must be unique and match the active demand")
-
-
-def block_task(root: str, task_dir: str, task_file: str, task_id: str, reason: str) -> dict[str, object]:
-    """Block a TASK: marker (when it is ours and active) plus Markdown view."""
-    from cf_spec_context import ContextError, load_active_task
-
-    if not reason.strip():
-        raise WorkflowError("block_reason_required", task_id)
-    recover_transition(root)
-    _, target = _resolve_paths(root, task_dir, task_file)
-    task_file = str(target)
-    section = read_task_section(task_file, task_id)
-    if section_status(section) in FINISHED_STATUSES:
-        raise WorkflowError("task_already_done", task_id, ("completed TASKs cannot be blocked",))
-    marker = "skipped_no_marker"
-    active = None
-    updated = None
-    try:
-        active = load_active_task(root)
-        _require_marker_task(root, task_id, task_dir, task_file)
-        if active.task_id == task_id and active.status == "active":
-            updated = replace(active, status="blocked")
-            marker = "blocked"
-        elif active.task_id == task_id:
-            marker = active.status
-            updated = active
-    except ContextError:
-        if (Path(root) / ".code-flow/.active-task.json").exists():
-            raise
-        marker = "skipped_no_marker"
-    today = _today()
-    markdown = _commit_state(
-        root, task_file, task_id, "blocked", active, updated,
-        f"- [{today}] blocked ({reason})",
-        prepend=f"> BLOCKED: {reason}",
-    )
-    return {"ok": True, "task_id": task_id, "marker": marker, "markdown": markdown}
-
-
-def resume_task(root: str, task_dir: str, task_file: str, task_id: str) -> dict[str, object]:
-    """Resume a blocked/paused TASK after its blockers clear."""
-    from cf_spec_context import load_active_task
-
-    recover_transition(root)
-    _, target = _resolve_paths(root, task_dir, task_file)
-    task_file = str(target)
-    active = None
-    if (Path(root) / ".code-flow/.active-task.json").exists():
-        _require_marker_task(root, task_id, task_dir, task_file)
-        active = load_active_task(root)
-        if active.status not in ("blocked", "paused"):
-            raise WorkflowError("resume_unexpected_state", active.status, (task_id,))
-    section = read_task_section(task_file, task_id)
-    if active is None and section_status(section) != "blocked":
-        raise WorkflowError("resume_unexpected_state", section_status(section), (task_id,))
-    notes = section_notes(section)
-    statuses = _all_statuses(task_file)
-    unmet = [dep for dep in section_depends(section) if statuses.get(dep) not in FINISHED_STATUSES]
-    if notes or unmet:
-        raise WorkflowError(
-            "resume_blocked", task_id,
-            tuple(([f"{len(notes)} unresolved #NOTES"] if notes else []) + ([f"unmet depends: {', '.join(unmet)}"] if unmet else [])),
-        )
-    resumed = replace(active, status="active") if active is not None else None
-    status = "in-progress" if resumed is not None else "draft"
-    markdown = _commit_state(root, task_file, task_id, status, active, resumed, f"- [{_today()}] resumed ({status})")
-    return {"ok": True, "task_id": task_id, "marker": resumed.status if resumed else "absent", "markdown": markdown}
-
-
-def complete_task(root: str, task_dir: str, task_file: str, task_id: str, gate_passed: bool) -> dict[str, object]:
-    """Complete a TASK after its Done Gate passed; syncs both records."""
-    from cf_spec_context import load_active_task
-
-    if not gate_passed:
-        raise WorkflowError("gate_failed", task_id, ("Done Gate 未通过",))
-    _require_marker_task(root, task_id, task_dir, task_file)
-    _, target = _resolve_paths(root, task_dir, task_file)
-    task_file = str(target)
-    active = load_active_task(root)
-    if active.status != "active":
-        raise WorkflowError("invalid_active_transition", active.status)
-    completed = replace(active, status="completed")
-    from cf_spec_context import _active_data
-
-    markdown = _commit_state(root, task_file, task_id, "done", active, None, f"- [{_today()}] completed (done)")
-    return {"ok": True, "task_id": task_id, "active": _active_data(completed), "markdown": markdown}