@michaelxwb/code-flow 0.6.2 → 0.6.4

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

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Shared execution substrate: deadline-aware argv subprocess runner.
+
+All check executors (acceptance scenarios, Spec verifiers, session
+validators) funnel through here so one entry deadline constrains the whole
+chain, commands never pass through a shell, and unrun work is reported as
+`incomplete` instead of silently skipped or falsely passed.
+"""
+
+from __future__ import annotations
+
+import shlex
+import json
+import subprocess
+import time
+from contextlib import contextmanager
+from contextvars import ContextVar
+from pathlib import Path
+from typing import Iterator, Mapping, Optional, Sequence
+
+_EXECUTIONS: ContextVar[Optional[dict[str, dict[str, object]]]] = ContextVar("cf_executions", default=None)
+
+
+@contextmanager
+def execution_session() -> Iterator[None]:
+    """Share results only inside one validation operation, never across turns."""
+    if _EXECUTIONS.get() is not None:
+        yield
+        return
+    token = _EXECUTIONS.set({})
+    try:
+        yield
+    finally:
+        _EXECUTIONS.reset(token)
+
+
+def invalidate_executions() -> None:
+    cache = _EXECUTIONS.get()
+    if cache is not None:
+        cache.clear()
+
+
+def execution_key(argv: Sequence[str], cwd: str, timeout: float) -> str:
+    """Identity of a command under the current process environment."""
+    return json.dumps([list(argv), str(Path(cwd).resolve()), float(timeout)], ensure_ascii=False)
+
+
+def remaining_seconds(deadline: Optional[float]) -> Optional[float]:
+    """Seconds left until the absolute monotonic deadline (None = unbounded)."""
+    if deadline is None:
+        return None
+    return deadline - time.monotonic()
+
+
+def build_argv(template: str, files: Sequence[str]) -> list[str]:
+    """Expand a validator command template into argv without a shell.
+
+    `{files}` must be a standalone token and expands to one argv entry per
+    file (spaces/metachars safe). Embedded usage is a config error — refusing
+    is safer than reintroducing shell splitting.
+    """
+    tokens = shlex.split(template or "")
+    if not tokens:
+        return []
+    argv: list[str] = []
+    for token in tokens:
+        if token == "{files}":
+            argv.extend(files)
+        elif "{files}" in token:
+            raise ValueError(f"validator command must keep {{files}} as a standalone token: {template!r}")
+        else:
+            argv.append(token)
+    return argv
+
+
+def run_command(
+    argv: Sequence[str],
+    cwd: str,
+    timeout: float,
+    deadline: Optional[float] = None,
+) -> dict[str, object]:
+    """Run argv synchronously under timeout+deadline. Never uses a shell."""
+    key = execution_key(argv, cwd, timeout)
+    cache = _EXECUTIONS.get()
+    if cache is not None and key in cache:
+        return dict(cache[key])
+    result = _execute(argv, cwd, timeout, deadline)
+    if cache is not None and result["status"] == "ok":
+        cache[key] = result
+    return result
+
+
+def _execute(argv: Sequence[str], cwd: str, timeout: float, deadline: Optional[float]) -> dict[str, object]:
+    remaining = remaining_seconds(deadline)
+    if remaining is not None and remaining <= 0:
+        return {"status": "deadline_exceeded", "returncode": None, "stdout": "", "stderr": ""}
+    effective = min(timeout, remaining) if remaining is not None else timeout
+    try:
+        proc = subprocess.run(
+            list(argv), cwd=cwd, capture_output=True, text=True, timeout=max(effective, 0.01)
+        )
+    except subprocess.TimeoutExpired as exc:
+        out = exc.stdout
+        return {
+            "status": "timeout",
+            "returncode": None,
+            "stdout": (out.decode() if isinstance(out, bytes) else (out or ""))[-4000:],
+            "stderr": "",
+        }
+    except OSError as exc:
+        return {"status": "spawn_error", "returncode": None, "stdout": "", "stderr": str(exc)}
+    return {"status": "ok", "returncode": proc.returncode, "stdout": proc.stdout or "", "stderr": proc.stderr or ""}

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

@@ -31,6 +31,7 @@ from cf_checks import (
 from cf_core import (
     _log,
     build_effective_mapping,
+    effective_project_root,
     ensure_utf8_io,
     is_code_file,
     load_config,
@@ -107,7 +108,10 @@ def main() -> None:
         if not isinstance(file_path, str) or not file_path:
             return
 
-        project_root = os.getcwd()
+        session_root = os.getcwd()
+        abs_path = file_path if os.path.isabs(file_path) else os.path.join(session_root, file_path)
+        # 并行子 agent 在 .code-flow/worktrees/... 内编辑时路由到该 worktree 的规格与状态
+        project_root = effective_project_root(session_root, abs_path)
         config = load_config(project_root)
         if not config:
             return
@@ -117,9 +121,6 @@ def main() -> None:
         if not quality_loop["post_check"]:
             return
 
-        abs_path = file_path
-        if not os.path.isabs(abs_path):
-            abs_path = os.path.join(project_root, file_path)
         rel_path = normalize_path(os.path.relpath(abs_path, project_root))
         sid = resolve_session_id(data)
         cf_log.append_event(project_root, "edit", {"file": rel_path, "tool": tool_name}, sid)

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

@@ -11,9 +11,18 @@ from pathlib import Path
 import sys
 
 import cf_log
-from cf_core import _log, ensure_utf8_io, load_config, normalize_path, resolve_enforcement, resolve_session_id, timing_log
+from cf_core import (
+    _log,
+    effective_project_root,
+    ensure_utf8_io,
+    load_config,
+    normalize_path,
+    resolve_enforcement,
+    resolve_session_id,
+    timing_log,
+)
 from cf_session_state import load_session_state, save_session_state
-from cf_spec_context import load_active_task, load_context
+from cf_spec_context import injection_version, load_active_task, load_context
 from cf_spec_resolver import resolve_candidate_headers
 from cf_spec_router import RouterError, route_prompt
 
@@ -30,6 +39,7 @@ def _active_expansion(root: str, relative: str) -> tuple[str, ...]:
     return tuple(
         item.spec_id for item in resolve_candidate_headers(root, "code", (relative,))
         if item.spec_id not in bound and item.enforcement == "required"
+        and getattr(item, "scope", "path") != "unmatched"
     )
 
 
@@ -48,11 +58,13 @@ def main() -> None:
         file_path = (data.get("tool_input") or {}).get("file_path", "")
         if tool_name not in {"Edit", "Write", "MultiEdit"} or not isinstance(file_path, str) or not file_path:
             return
-        root = os.getcwd()
+        session_root = os.getcwd()
+        absolute = file_path if os.path.isabs(file_path) else os.path.join(session_root, file_path)
+        # 并行子 agent 在 .code-flow/worktrees/... 内编辑时路由到该 worktree 的上下文
+        root = effective_project_root(session_root, absolute)
         sid = resolve_session_id(data)
         config = load_config(root)
         enforcement = resolve_enforcement(config) if config else "required"
-        absolute = file_path if os.path.isabs(file_path) else os.path.join(root, file_path)
         relative = normalize_path(os.path.relpath(absolute, root))
         try:
             expanded = _active_expansion(root, relative)
@@ -70,12 +82,15 @@ def main() -> None:
         text = result.text
         if result.mode == "task" and result.context_sha256:
             # The projection is already in context from the prompt route unless
-            # the bound rules changed; skip per-edit re-injection.
+            # the session/task/contract version changed; skip per-edit
+            # re-injection. Same version key as the prompt hook so a TASK
+            # switch re-injects here too.
             state = load_session_state(root)
-            if state.get("injected_sha256") == result.context_sha256:
+            version = injection_version(root, sid, result.context_sha256)
+            if state.get("injected_version") == version:
                 text = ""
             else:
-                state["injected_sha256"] = result.context_sha256
+                state["injected_version"] = version
                 save_session_state(root, state)
         if text:
             sys.stdout.write(json.dumps(_inject(text), ensure_ascii=False))

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

@@ -11,6 +11,7 @@ from cf_core import (
     build_spec_catalog,
     estimate_tokens,
     load_config,
+    project_instruction_file,
     non_injectable_specs,
     parse_spec_frontmatter,
 )
@@ -120,19 +121,20 @@ def find_missing_paths(text: str, project_root: str, base_dir: str = "") -> list
     return sorted(missing)
 
 
-def build_report(project_root: str) -> dict:
+def build_report(project_root: str, platform: str = "") -> dict:
     """规范质量审计数据（cf-scan 引擎，亦供 cf-stats --audit 复用）。
 
     files 含 issues / template 标记，review 为待复审清单；展示层负责过滤与渲染。"""
     files = []
     total_tokens = 0
 
-    claude_path = os.path.join(project_root, "CLAUDE.md")
+    instruction_file = project_instruction_file(project_root, platform)
+    claude_path = os.path.join(project_root, instruction_file)
     if os.path.exists(claude_path):
         content = read_text(claude_path)
         tokens = estimate_tokens(content)
         total_tokens += tokens
-        files.append({"path": "CLAUDE.md", "tokens": tokens, "issues": []})
+        files.append({"path": instruction_file, "tokens": tokens, "issues": []})
 
     specs_root = os.path.join(project_root, ".code-flow", "specs")
     specs = []
@@ -142,14 +144,14 @@ def build_report(project_root: str) -> dict:
                 if not name.endswith(".md"):
                     continue
                 full_path = os.path.join(root, name)
+                rel = os.path.relpath(full_path, specs_root)
+                if rel.replace(os.sep, "/").startswith("_session/"):
+                    continue
                 content = read_text(full_path)
                 if not content:
                     continue
                 tokens = estimate_tokens(content)
                 total_tokens += tokens
-                rel = os.path.relpath(full_path, specs_root)
-                if rel.replace(os.sep, "/").startswith("_session/"):
-                    continue  # 会话级临时约束（FEAT-08）不参与审计与预算
                 rel_path = os.path.join("specs", rel).replace(os.sep, "/")
                 spec_entry = {
                     "path": rel_path,

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

@@ -42,6 +42,7 @@ DEFAULT_ACTIVE_EXCLUDES = (
     ".code-flow/.session-log.jsonl",
     ".code-flow/.active-task.json",
     ".code-flow/.active-task.lock",
+    ".code-flow/worktrees/*",
 )
 
 
@@ -159,6 +160,10 @@ class ActiveBaseline:
     head: Optional[str]
     captured_at: str
     preexisting_changes: Mapping[str, PathSnapshot]
+    # head is frozen at start and never rewritten: task scope is the union of
+    # everything committed since head plus all working-tree changes.
+    # last_seen_head is observation-only (diagnostics), never scope input.
+    last_seen_head: Optional[str] = None
 
 
 @dataclass(frozen=True)
@@ -285,6 +290,7 @@ def _active_data(active: ActiveTask) -> dict[str, object]:
         "context_sha256": active.context_sha256,
         "baseline": {
             "head": active.baseline.head,
+            "last_seen_head": active.baseline.last_seen_head,
             "captured_at": active.baseline.captured_at,
             "preexisting_changes": changes,
         },
@@ -319,6 +325,7 @@ def _active_from_data(value: object, path: str) -> ActiveTask:
         head,
         _string(baseline_data.get("captured_at"), "captured_at", path),
         {key: _snapshot_from_data(item, path) for key, item in raw_changes.items()},
+        baseline_data.get("last_seen_head") if isinstance(baseline_data.get("last_seen_head"), str) else None,
     )
     return ActiveTask(
         1,
@@ -351,6 +358,58 @@ def load_active_task(root: str) -> ActiveTask:
         raise ContextError("invalid_active_marker", "active", str(exc), str(marker)) from exc
 
 
+def task_contract_digest(root: str, task_dir: str, task_id: str) -> str:
+    """Digest of the active TASK's acceptance contract (Refs + Contract + Evidence).
+
+    Two TASKs may share one Context hash while owning different scenarios; the
+    digest separates their injection versions so switching TASKs re-injects.
+    Returns "" when the TASK section cannot be located (fail-open to the
+    legacy context-hash-only key rather than crashing the hook hot path).
+    """
+    try:
+        files = sorted((Path(root) / task_dir).glob("*.md"))
+    except OSError:
+        return ""
+    for path in files:
+        if path.name.endswith((".prd.md", ".design.md")):
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeError):
+            continue
+        start = text.find(f"## {task_id}:")
+        if start == -1:
+            continue
+        end = text.find("\n## TASK-", start)
+        section = text[start:] if end == -1 else text[start:end]
+        chunks: list[str] = []
+        for heading in ("Acceptance-Refs", "Acceptance Contract", "Acceptance Evidence"):
+            index = section.find(heading)
+            if index == -1:
+                chunks.append(f"{heading}:missing")
+                continue
+            end = section.find("\n### ", index)
+            chunks.append(section[index:] if end == -1 else section[index:end])
+        return hashlib.sha256("\n".join(chunks).encode("utf-8")).hexdigest()
+    return ""
+
+
+def injection_version(root: str, session_id: str, context_sha: str) -> str:
+    """Version key for hook injection dedup.
+
+    Covers session + task_dir + task_id + context hash + TASK contract digest,
+    so a TASK switch (or an in-place contract edit) always re-injects while a
+    repeated prompt on the same contract stays suppressed.
+    """
+    try:
+        active = load_active_task(root)
+    except (ContextError, OSError, ValueError):
+        return f"none:{session_id}:{context_sha}"
+    digest = task_contract_digest(root, active.task_dir, active.task_id)
+    raw = "\n".join((session_id, active.task_dir, active.task_id, context_sha, digest))
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
 def resync_active_hash(root: str, task_dir: str, current_sha256: str) -> bool:
     """Re-sync the active marker's context hash after toolchain-initiated
     context edits (bind/decision/refresh) so they never surface as
@@ -433,6 +492,42 @@ def _release_active_lock(lock: Path) -> None:
         return
 
 
+def _committed_since(root: str, base_head: Optional[str]) -> Mapping[str, str]:
+    """Paths committed between the frozen baseline head and current HEAD.
+
+    Returns {} when there is no baseline (pre-commit repo) or the range is
+    unresolvable (rewritten/pruned history) — working-tree changes still
+    flow through _business_changes, so scope never goes fully blind.
+    """
+    if not base_head:
+        return {}
+    try:
+        output = _run_git(root, ("diff", "--name-status", "-z", base_head, "HEAD", "--"))
+    except ContextError:
+        return {}
+    names: dict[str, str] = {}
+    tokens = output.split("\0")
+    index = 0
+    while index < len(tokens) and tokens[index]:
+        status, index = tokens[index], index + 1
+        code = status[:1]
+        if code in ("R", "C"):
+            if index + 1 >= len(tokens):
+                break
+            new_path, old_path = tokens[index], tokens[index + 1]
+            index += 2
+            if new_path:
+                names[new_path] = "renamed"
+            if old_path:
+                names[old_path] = "deleted"
+            continue
+        if index >= len(tokens) or not tokens[index]:
+            break
+        names[tokens[index]] = {"M": "modified", "A": "added", "D": "deleted"}.get(code, "changed")
+        index += 1
+    return names
+
+
 def _business_changes(root: str, excludes: Sequence[str]) -> Mapping[str, str]:
     return {
         path: status
@@ -462,7 +557,8 @@ def _new_active(
     snapshots = {
         path: PathSnapshot(status, "") for path, status in changes.items()
     }
-    baseline = ActiveBaseline(_git_head(root), _now(), snapshots)
+    head = _git_head(root)
+    baseline = ActiveBaseline(head, _now(), snapshots, head)
     return ActiveTask(
         1, task_dir, task_id, "activating", context_sha256, baseline, owned, DEFAULT_ACTIVE_EXCLUDES
     )
@@ -498,9 +594,10 @@ def _transition_active(root: str, expected: Sequence[str], target: str) -> Activ
             raise ContextError("invalid_active_transition", "status", f"{active.status} -> {target}", root)
         current_head = _git_head(root)
         if active.baseline.head != current_head:
-            # Mid-task commits are a normal workflow; re-baseline instead of
-            # bricking pause/resume/complete on any unrelated commit.
-            active = replace(active, baseline=replace(active.baseline, head=current_head))
+            # Mid-task commits are a normal workflow. The baseline head stays
+            # frozen so committed work never drops out of scope; only the
+            # observation field advances for diagnostics.
+            active = replace(active, baseline=replace(active.baseline, last_seen_head=current_head))
         updated = replace(active, status=target)
         save_active_task(root, updated)
         return updated
@@ -522,7 +619,12 @@ def resume_active_task(root: str) -> ActiveTask:
 
 def current_owned_paths(root: str, active: ActiveTask) -> tuple[str, ...]:
     changes = _business_changes(root, active.excluded_paths)
-    return tuple(sorted(set(active.owned_paths).union(changes)))
+    committed = {
+        path: status
+        for path, status in _committed_since(root, active.baseline.head).items()
+        if not _is_excluded(path, active.excluded_paths)
+    }
+    return tuple(sorted(set(active.owned_paths).union(changes).union(committed)))
 
 
 def complete_active_task(root: str, gate_passed: bool) -> ActiveTask:
@@ -1213,8 +1315,15 @@ def apply_artifact_ref(
 
 def _json_payload(stream: IO[str]) -> Mapping[str, object]:
     try:
-        loaded = json.load(stream)
-    except (json.JSONDecodeError, UnicodeError) as exc:
+        raw = stream.read()
+    except (OSError, UnicodeError) as exc:
+        raise ContextError("invalid_json", "stdin", str(exc)) from exc
+    if not raw.strip():
+        # 空 stdin = 无 payload（例如 active doctor --resync 全参数走 CLI 开关）。
+        return {}
+    try:
+        loaded = json.loads(raw)
+    except json.JSONDecodeError as exc:
         raise ContextError("invalid_json", "stdin", str(exc)) from exc
     return _mapping(loaded, "stdin", "")
 
@@ -1337,82 +1446,104 @@ def _bind_command(args: argparse.Namespace, payload: Mapping[str, object]) -> di
 
 
 def _active_command(args: argparse.Namespace, payload: Mapping[str, object]) -> dict[str, object]:
+    from cf_workflow_service import WorkflowError, locate_task_file
+    from cf_workflow_transaction import recover_transition
+
+    recover_transition(args.root)
+    if args.active_action in ("pause", "resume", "block", "complete"):
+        marker, _ = _active_paths(args.root)
+        if marker.exists():
+            current = load_active_task(args.root)
+            if (current.task_id != args.task or
+                    (Path(args.root) / current.task_dir).resolve() != (Path(args.root) / args.task_dir).resolve()):
+                raise ContextError("active_mismatch", "active", "requested TASK does not match marker", str(marker))
+
+    def _directory() -> str:
+        return args.task_dir if Path(args.task_dir).is_absolute() else str(Path(args.root) / args.task_dir)
+
+    def _reraise(exc: WorkflowError) -> ContextError:
+        return ContextError(exc.code, "workflow", str(exc), args.task_dir)
+
+    task_file = locate_task_file(_directory(), args.task)
     if args.active_action == "start":
         owned = tuple(
             _string(item, "owned_paths[]", "")
             for item in _sequence(payload.get("owned_paths", []), "owned_paths", "")
         )
-        active = start_active_task(
-            args.root, args.task_dir, args.task, args.context_sha256, owned
-        )
-        return {"ok": True, "active": _active_data(active)}
+        if task_file is None:
+            active = start_active_task(
+                args.root, args.task_dir, args.task, args.context_sha256, owned
+            )
+            return {"ok": True, "active": _active_data(active)}
+        from cf_workflow_service import start_task
+
+        try:
+            return start_task(args.root, args.task_dir, str(task_file), args.task, owned)
+        except WorkflowError as exc:
+            raise _reraise(exc) from exc
     if args.active_action == "pause":
         active = pause_active_task(args.root)
     elif args.active_action == "resume":
-        active = resume_active_task(args.root)
+        if task_file is None:
+            active = resume_active_task(args.root)
+        else:
+            from cf_workflow_service import resume_task
+
+            try:
+                return resume_task(args.root, _directory(), str(task_file), args.task)
+            except WorkflowError as exc:
+                raise _reraise(exc) from exc
     elif args.active_action == "block":
-        active = block_active_task(args.root)
+        if task_file is None:
+            active = block_active_task(args.root)
+        else:
+            from cf_workflow_service import block_task
+
+            reason = payload.get("reason", "")
+            try:
+                return block_task(args.root, _directory(), str(task_file), args.task, reason if isinstance(reason, str) else "")
+            except WorkflowError as exc:
+                raise _reraise(exc) from exc
     elif args.active_action == "complete":
-        active = complete_active_task(args.root, payload.get("gate_passed") is True)
+        gate = payload.get("gate_passed") is True
+        if task_file is None:
+            active = complete_active_task(args.root, gate)
+        else:
+            from cf_workflow_service import complete_task
+
+            try:
+                return complete_task(args.root, _directory(), str(task_file), args.task, gate)
+            except WorkflowError as exc:
+                raise _reraise(exc) from exc
     else:
-        result = doctor_active_task(
-            args.root,
-            args.context_sha256,
-            payload.get("abandon") is True,
-            payload.get("resync") is True,
-        )
+        abandon = payload.get("abandon") is True or args.abandon
+        resync = payload.get("resync") is True or args.resync
+        if abandon and resync:
+            raise ContextError("conflicting_recovery", "doctor", "abandon 与 resync 不能同时使用", args.task_dir)
+        result = doctor_active_task(args.root, args.context_sha256, abandon, resync)
         return {"ok": True, "action": result.action, "active": _active_data(result.active)}
     return {"ok": True, "active": _active_data(active)}
 
 
 def _start_command(args: argparse.Namespace, payload: Mapping[str, object]) -> dict[str, object]:
-    """Run refresh, activation and TASK projection in one guarded process."""
-    context_path = Path(args.task_dir) / "spec-context.yml"
-    refreshed = refresh_context(load_context(str(context_path)), args.root, artifact_root=args.task_dir)
-    save_context(str(context_path), refreshed.context)
-    _resync_after_save(args, context_path)
-    current_hash = context_sha256(refreshed.context)
+    """Run refresh, activation and TASK projection in one guarded process.
+
+    Delegates to the unified workflow service: hard preconditions (status,
+    NOTES, depends, marker) are enforced before any state changes, and the
+    Markdown view flips to in-progress in the same call.
+    """
+    from cf_workflow_service import WorkflowError, start_task
+
     owned = tuple(
         _string(item, "owned_paths[]", "")
         for item in _sequence(payload.get("owned_paths", []), "owned_paths", "")
     )
-    task_file = Path(args.task_file).resolve()
-    task_dir = Path(args.task_dir).resolve()
-    if task_file.parent != task_dir or not task_file.is_file():
-        raise ContextError("invalid_task_file", "task_file", str(task_file), args.task_dir)
-    manifest_file = task_dir / ".acceptance-manifest.json"
-    if "## Acceptance Coverage" in task_file.read_text(encoding="utf-8") and not manifest_file.is_file():
-        raise ContextError(
-            "acceptance_manifest_missing",
-            "acceptance_manifest",
-            "run plan verification and lock the manifest",
-            str(manifest_file),
+    try:
+        return start_task(
+            args.root, args.task_dir, args.task_file, args.task, owned, args.session_output
         )
-    if manifest_file.is_file():
-        from cf_acceptance_manifest import validate_manifest
-
-        valid, reason = validate_manifest(str(task_file), str(manifest_file))
-        if not valid:
-            raise ContextError(reason, "acceptance_manifest", "run plan verification before coding", str(manifest_file))
-    from cf_spec_session import project_task_session
-
-    projection = project_task_session(refreshed.context, str(task_file), args.task)
-    if projection.truncated:
-        raise ContextError("task_projection_truncated", "task_file", "split the TASK before coding")
-    output = Path(args.session_output) if args.session_output else (
-        Path(args.root) / ".code-flow/specs/_session" / f"task-{task_file.stem}.md"
-    )
-    output.parent.mkdir(parents=True, exist_ok=True)
-    _atomic_text(output, projection.text)
-    active = start_active_task(args.root, args.task_dir, args.task, current_hash, owned)
-    return {
-        "ok": True,
-        "context_sha256": current_hash,
-        "refresh_changes": [item.__dict__ for item in refreshed.changes],
-        "active": _active_data(active),
-        "session_output": str(output),
-        "acceptance_manifest": str(manifest_file) if manifest_file.is_file() else None,
-    }
+    except WorkflowError as exc:
+        raise ContextError(exc.code, "workflow", str(exc), args.task_dir) from exc
 
 
 def _status_command(args: argparse.Namespace) -> dict[str, object]:
@@ -1465,7 +1596,7 @@ def _status_text(data: dict[str, object]) -> str:
         match = "✓ 一致" if marker["hash_match"] else "✗ 漂移"
         lines.append(f"- TASK {marker['task_id']}（{marker['status']}），marker hash {match}")
         if not marker["hash_match"]:
-            lines.append("  下一步: 运行 cf-spec doctor（resync 可自动重同步）")
+            lines.append("  下一步: 运行 cf-spec refresh 自动重同步 marker hash；仍不一致时用 active doctor --resync（hash 取本命令 --json 的 context_sha256）")
     else:
         lines.append("- 无 active TASK（path/catalog 路由模式）")
     gate = data["gate"]
@@ -1519,6 +1650,9 @@ def _parser() -> argparse.ArgumentParser:
         command.add_argument("--task", required=True)
         command.add_argument("--context-sha256", required=True)
         command.add_argument("--json", action="store_true")
+        if action == "doctor":
+            command.add_argument("--abandon", action="store_true", help="确认放弃无法证明的 marker（需用户确认）")
+            command.add_argument("--resync", action="store_true", help="用 --context-sha256 重新绑定 marker 并恢复 active")
     start = commands.add_parser("start")
     start.add_argument("--task-dir", required=True)
     start.add_argument("--root", required=True)