cowork-flow 0.0.19 → 0.0.21

package/template/.cowork-flow/scripts/common/active_task.py

@@ -13,7 +13,18 @@ from .paths import DIR_WORKFLOW
 
 DIR_RUNTIME = ".runtime"
 DIR_SESSIONS = "sessions"
+DIR_SUBAGENTS = "subagents"
 FIELD_ACTIVE_TASK_PATH = "active_task_path"
+FIELD_RUNTIME_CONTEXT_ID = "runtime_context_id"
+FIELD_SCOPE = "scope"
+SCOPE_MAIN = "main"
+SCOPE_SUBAGENT = "subagent"
+RUNTIME_CONTEXT_PROMPT_RE = re.compile(
+    r"(?im)^\s*cowork_runtime_context_id\s*:\s*([A-Za-z0-9._-]+)\s*$"
+)
+HOST_CONTEXT_PROMPT_RE = re.compile(
+    r"(?im)^\s*cowork_host_context_key\s*:\s*([A-Za-z0-9._-]+)\s*$"
+)
 
 
 @dataclass(frozen=True)
@@ -38,11 +49,23 @@ def _first_input_value(values: Mapping[str, object] | None, names: tuple[str, ..
     return None
 
 
+def _first_prompt_value(values: Mapping[str, object] | None) -> str | None:
+    return _first_input_value(values, ("prompt", "user_prompt", "userPrompt", "message", "input"))
+
+
 def resolve_context_key(values: Mapping[str, object] | None = None) -> str | None:
     explicit = os.environ.get("COWORK_FLOW_CONTEXT_ID")
     if explicit and explicit.strip():
         return _sanitize(explicit)
 
+    opencode_session = os.environ.get("OPENCODE_SESSION_ID")
+    if opencode_session and opencode_session.strip():
+        return f"opencode_{_sanitize(opencode_session)}"
+
+    claude_session = os.environ.get("CLAUDE_SESSION_ID")
+    if claude_session and claude_session.strip():
+        return f"claude_{_sanitize(claude_session)}"
+
     codex_session = os.environ.get("CODEX_SESSION_ID")
     if codex_session and codex_session.strip():
         return f"codex_{_sanitize(codex_session)}"
@@ -62,6 +85,26 @@ def resolve_context_key(values: Mapping[str, object] | None = None) -> str | Non
     if input_explicit:
         return _sanitize(input_explicit)
 
+    input_opencode_session = _first_input_value(
+        values,
+        (
+            "OPENCODE_SESSION_ID",
+            "opencode_session_id",
+        ),
+    )
+    if input_opencode_session:
+        return f"opencode_{_sanitize(input_opencode_session)}"
+
+    input_claude_session = _first_input_value(
+        values,
+        (
+            "CLAUDE_SESSION_ID",
+            "claude_session_id",
+        ),
+    )
+    if input_claude_session:
+        return f"claude_{_sanitize(input_claude_session)}"
+
     input_session = _first_input_value(
         values,
         (
@@ -92,6 +135,10 @@ def sessions_dir(repo_root: Path) -> Path:
     return repo_root / DIR_WORKFLOW / DIR_RUNTIME / DIR_SESSIONS
 
 
+def subagent_contexts_dir(repo_root: Path) -> Path:
+    return repo_root / DIR_WORKFLOW / DIR_RUNTIME / DIR_SUBAGENTS
+
+
 def _now() -> str:
     return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
 
@@ -100,6 +147,14 @@ def _session_path(repo_root: Path, context_key: str) -> Path:
     return sessions_dir(repo_root) / f"{context_key}.json"
 
 
+def logical_subagent_context_key(runtime_context_id: str) -> str:
+    return f"subagent_{_sanitize(runtime_context_id)}"
+
+
+def runtime_context_path(repo_root: Path, runtime_context_id: str) -> Path:
+    return subagent_contexts_dir(repo_root) / f"{_sanitize(runtime_context_id)}.json"
+
+
 def _read_json(path: Path) -> dict:
     try:
         data = json.loads(path.read_text(encoding="utf-8"))
@@ -113,6 +168,161 @@ def _write_json(path: Path, data: dict) -> None:
     path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
 
 
+def _platform_from_context_key(context_key: str) -> str:
+    if context_key.startswith("codex_"):
+        return "codex"
+    if context_key.startswith("opencode_"):
+        return "opencode"
+    if context_key.startswith("claude_"):
+        return "claude-code"
+    return "manual"
+
+
+def resolve_runtime_context_id(values: Mapping[str, object] | None = None) -> str | None:
+    explicit = os.environ.get("COWORK_FLOW_RUNTIME_CONTEXT_ID")
+    if explicit and explicit.strip():
+        return _sanitize(explicit)
+
+    input_explicit = _first_input_value(
+        values,
+        (
+            "COWORK_FLOW_RUNTIME_CONTEXT_ID",
+            "cowork_runtime_context_id",
+            "runtime_context_id",
+        ),
+    )
+    if input_explicit:
+        return _sanitize(input_explicit)
+
+    prompt = _first_prompt_value(values)
+    if prompt:
+        match = RUNTIME_CONTEXT_PROMPT_RE.search(prompt)
+        if match:
+            return _sanitize(match.group(1))
+
+    return None
+
+def resolve_host_context_key(values: Mapping[str, object] | None = None) -> str | None:
+    explicit = os.environ.get("COWORK_FLOW_HOST_CONTEXT_KEY")
+    if explicit and explicit.strip():
+        return _sanitize(explicit)
+
+    input_explicit = _first_input_value(
+        values,
+        (
+            "cowork_host_context_key",
+            "host_context_key",
+            "COWORK_FLOW_HOST_CONTEXT_KEY",
+        ),
+    )
+    if input_explicit:
+        return _sanitize(input_explicit)
+
+    prompt = _first_prompt_value(values)
+    if prompt:
+        match = HOST_CONTEXT_PROMPT_RE.search(prompt)
+        if match:
+            return _sanitize(match.group(1))
+
+    return None
+
+
+def read_runtime_context(repo_root: Path, runtime_context_id: str) -> dict:
+    return _read_json(runtime_context_path(repo_root, runtime_context_id))
+
+
+def write_runtime_context(repo_root: Path, runtime_context_id: str, data: dict) -> None:
+    _write_json(runtime_context_path(repo_root, runtime_context_id), data)
+
+
+def write_subagent_logical_session(
+    repo_root: Path,
+    runtime_context_id: str,
+    task_path: str | None,
+    platform: str,
+    status: str = "pending_bind",
+) -> str:
+    context_key = logical_subagent_context_key(runtime_context_id)
+    data: dict[str, object] = {
+        "schema_version": 2,
+        FIELD_SCOPE: SCOPE_SUBAGENT,
+        FIELD_RUNTIME_CONTEXT_ID: runtime_context_id,
+        "platform": platform,
+        "status": status,
+        "last_seen_at": _now(),
+    }
+    if task_path:
+        data[FIELD_ACTIVE_TASK_PATH] = task_path.replace("\\", "/")
+    _write_json(_session_path(repo_root, context_key), data)
+    return context_key
+
+
+def bind_runtime_context(
+    repo_root: Path,
+    runtime_context_id: str,
+    host_context_key: str | None = None,
+    values: Mapping[str, object] | None = None,
+) -> dict | None:
+    context = read_runtime_context(repo_root, runtime_context_id)
+    if not context or context.get(FIELD_SCOPE) != SCOPE_SUBAGENT:
+        return None
+    if context.get("status") == "closed":
+        return None
+
+    resolved_key = (
+        _sanitize(host_context_key)
+        if host_context_key
+        else resolve_host_context_key(values) or resolve_context_key(values)
+    )
+    if not resolved_key:
+        return None
+
+    existing_key = context.get("bound_context_key")
+    if isinstance(existing_key, str) and existing_key.strip() and existing_key != resolved_key:
+        return None
+
+    task_path = context.get("task_dir")
+    session: dict[str, object] = {
+        "schema_version": 2,
+        FIELD_SCOPE: SCOPE_SUBAGENT,
+        FIELD_RUNTIME_CONTEXT_ID: runtime_context_id,
+        "platform": _platform_from_context_key(resolved_key),
+        "status": "bound",
+        "last_seen_at": _now(),
+    }
+    if isinstance(task_path, str) and task_path.strip():
+        session[FIELD_ACTIVE_TASK_PATH] = task_path.strip()
+    _write_json(_session_path(repo_root, resolved_key), session)
+
+    context["status"] = "bound"
+    context["bound_context_key"] = resolved_key
+    if not context.get("bound_at"):
+        context["bound_at"] = _now()
+    context["last_seen_at"] = _now()
+    write_runtime_context(repo_root, runtime_context_id, context)
+    return context
+
+
+def close_runtime_context(repo_root: Path, runtime_context_id: str) -> bool:
+    context = read_runtime_context(repo_root, runtime_context_id)
+    if not context:
+        return False
+
+    bound_context_key = context.get("bound_context_key")
+    for context_key in (bound_context_key, logical_subagent_context_key(runtime_context_id)):
+        if isinstance(context_key, str) and context_key.strip():
+            try:
+                _session_path(repo_root, context_key).unlink()
+            except FileNotFoundError:
+                pass
+
+    context["status"] = "closed"
+    context["closed_at"] = _now()
+    context["last_seen_at"] = _now()
+    write_runtime_context(repo_root, runtime_context_id, context)
+    return True
+
+
 def set_active_task(repo_root: Path, task_path: str) -> ActiveTask | None:
     context_key = resolve_context_key()
     if not context_key:
@@ -125,7 +335,8 @@ def set_active_task(repo_root: Path, task_path: str) -> ActiveTask | None:
         _session_path(repo_root, context_key),
         {
             FIELD_ACTIVE_TASK_PATH: normalized,
-            "platform": "codex" if context_key.startswith("codex_") else "manual",
+            FIELD_SCOPE: SCOPE_MAIN,
+            "platform": _platform_from_context_key(context_key),
             "last_seen_at": _now(),
         },
     )

package/template/.cowork-flow/scripts/common/entry_classifier.py

@@ -0,0 +1,122 @@
+"""Classify cowork-flow hook entries before workflow-state injection."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class EntryKind:
+    MAIN_SESSION = "MAIN_SESSION"
+    READ_ONLY = "READ_ONLY"
+    COMMAND_ONLY = "COMMAND_ONLY"
+    UNKNOWN = "UNKNOWN"
+
+
+@dataclass(frozen=True)
+class Classification:
+    entry_kind: str
+    confidence: float
+    source: str
+
+
+PROMPT_KEYS = ("prompt", "user_prompt", "userPrompt", "message", "input")
+
+TASK_TERMS = (
+    "task:",
+    "topic:",
+    "focus:",
+    "任务：",
+    "任务:",
+    "主题：",
+    "目标：",
+    "审视",
+    "讨论",
+    "review",
+    "inspect",
+)
+
+READ_ONLY_TERMS = (
+    "explain",
+    "what does",
+    "what is",
+    "why does",
+    "为什么",
+    "原因",
+    "解释",
+    "说明",
+    "read-only",
+    "inspect only",
+    "analysis only",
+    "只看",
+    "只读",
+    "分析一下",
+)
+
+COMMAND_ONLY_TERMS = (
+    "git status",
+    "git diff",
+    "npm run",
+    ".cowork-flow/run",
+    ".cowork-flow\\run.cmd",
+)
+
+MAIN_SESSION_TERMS = (
+    "main session",
+    "main agent",
+    "not a subagent",
+    "not a sub-agent",
+    "run full cowork-flow start",
+    "run full project start",
+    "继续",
+    "实现",
+    "提交",
+    "归档",
+    "修复",
+    "主会话",
+    "主 agent",
+    "主代理",
+    "不是子代理",
+    "不是子任务",
+    "start task",
+    "resume",
+    "implement",
+    "commit",
+    "archive",
+    "fix",
+)
+
+
+def extract_prompt(hook_input: dict) -> str:
+    values: list[str] = []
+    for key in PROMPT_KEYS:
+        value = hook_input.get(key)
+        if isinstance(value, str) and value.strip():
+            values.append(value)
+    return "\n".join(values)
+
+
+def _contains_any(text: str, terms: tuple[str, ...]) -> bool:
+    return any(term in text for term in terms)
+
+
+def classify_entry(hook_input: dict) -> Classification:
+    prompt = extract_prompt(hook_input)
+    if not prompt.strip():
+        return Classification(EntryKind.UNKNOWN, 0.0, "empty_prompt")
+
+    lowered = prompt.lower()
+    has_task = _contains_any(lowered, TASK_TERMS)
+
+    if _contains_any(lowered, READ_ONLY_TERMS) and not _contains_any(lowered, MAIN_SESSION_TERMS):
+        return Classification(EntryKind.READ_ONLY, 0.6, "read_only")
+
+    if _contains_any(lowered, COMMAND_ONLY_TERMS) and not has_task:
+        return Classification(EntryKind.COMMAND_ONLY, 0.6, "command_only")
+
+    if _contains_any(lowered, MAIN_SESSION_TERMS):
+        return Classification(EntryKind.MAIN_SESSION, 0.55, "main_session_heuristic")
+
+    if has_task:
+        return Classification(EntryKind.UNKNOWN, 0.35, "task_prompt_unbound")
+
+    return Classification(EntryKind.UNKNOWN, 0.3, "unclassified")

package/template/.cowork-flow/scripts/common/execution_context.py

@@ -309,17 +309,15 @@ def build_subagent_resume_text(
     forbidden_actions = context_data.get("forbiddenActions")
     status_file = context_data.get("statusFile")
     events_file = context_data.get("eventsFile")
-    dispatch_id = context_data.get("dispatchId")
-    ack_token = context_data.get("ackToken")
-    dispatch_status = context_data.get("dispatchStatus")
+    runtime_context_id = context_data.get("runtimeContextId") or context_data.get("runtime_context_id")
+    runtime_context_status = context_data.get("runtimeContextStatus")
     agent_type = context_data.get("agentType")
     dispatch_reliability = context_data.get("dispatchReliability")
-    expected_ack = context_data.get("expectedAck")
     lines = [
         "========================================",
         "COWORK-FLOW SUBAGENT RESUME",
         "========================================",
-        "Use this only for a delegated subagent's own scoped recovery.",
+        "Use this only for a runtime-context subagent's own scoped recovery.",
         "Do not switch back into the coordinator workflow from this entrypoint.",
         "",
         "## SUBAGENT CONTEXT",
@@ -328,18 +326,14 @@ def build_subagent_resume_text(
         f"Role: {context.role or 'unknown'}",
         f"Goal: {context.goal or 'unknown'}",
     ]
-    if isinstance(dispatch_id, str) and dispatch_id.strip():
-        lines.append(f"Dispatch ID: {dispatch_id}")
-    if isinstance(dispatch_status, str) and dispatch_status.strip():
-        lines.append(f"Dispatch status: {dispatch_status}")
+    if isinstance(runtime_context_id, str) and runtime_context_id.strip():
+        lines.append(f"Runtime context: {runtime_context_id}")
+    if isinstance(runtime_context_status, str) and runtime_context_status.strip():
+        lines.append(f"Runtime context status: {runtime_context_status}")
     if isinstance(agent_type, str) and agent_type.strip():
         lines.append(f"Agent type: {agent_type}")
     if isinstance(dispatch_reliability, str) and dispatch_reliability.strip():
         lines.append(f"Dispatch reliability: {dispatch_reliability}")
-    if isinstance(ack_token, str) and ack_token.strip():
-        lines.append(f"ACK token: {ack_token}")
-    if isinstance(expected_ack, str) and expected_ack.strip():
-        lines.append(f"Expected ACK: {expected_ack}")
     if context.context_file:
         lines.append(f"Context file: {context.context_file}")
     if isinstance(allowed_context, list) and allowed_context:
@@ -379,10 +373,9 @@ def build_subagent_resume_text(
     lines.extend([
         "",
         "## RULES",
-        "- If you have not acknowledged this dispatch, first return only: COWORK_ACK <dispatch_id> <ack_token>.",
-        "- Execute only after the coordinator sends EXECUTE <dispatch_id> for this same dispatch.",
-        "- If a message names a different dispatch_id, report needs_context and do not execute it.",
-        "- Generic worker dispatch is best-effort only; no ACK means the coordinator must close or retry it.",
+        "- Execute only when the bound runtime context exists, is open, and names this agent type.",
+        "- If runtime context is missing, closed, invalid, or mismatched, report needs_context and do not execute it.",
+        "- Generic worker dispatch is advisory only and cannot complete formal Implement or Check.",
         "- Read only prompt-named files and allowed context unless you ask for more context.",
         "- Do not run task start, task finish, task archive, or unscoped resume.",
         "- Stop only with success, needs_context, or blocked status evidence.",

package/template/.cowork-flow/scripts/common/readiness.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""Readiness checks shared by task lifecycle commands."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .paths import DIR_ARCHIVE, DIR_CHANGES, DIR_TASKS, DIR_WORKFLOW, FILE_TASK_JSON, get_tasks_dir
+from .task_utils import find_task_by_name
+
+REQUIRED_L2_MARKERS = {
+    "goal and user value": (
+        ("## goal", "## problem", "目标"),
+        ("## benefits", "user value", "用户价值", "价值"),
+    ),
+    "non-goals": (("## non-goals", "non-goals", "非目标"),),
+    "key assumptions": (("assumption", "assumptions", "关键假设"),),
+    "scope boundary": (("## scope", "scope boundary", "范围边界", "scope:"),),
+    "acceptance criteria": (("acceptance criteria", "## acceptance", "验收标准", "验收"),),
+}
+
+VERIFICATION_COMMAND_MARKERS = (
+    "python -m unittest",
+    "npm test",
+    "npm run",
+    "git diff --check",
+)
+
+
+def _read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeDecodeError):
+        return ""
+
+
+def _read_json(path: Path) -> dict:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _parse_scalar(value: str) -> object:
+    if value == "null":
+        return None
+    if value == "true":
+        return True
+    if value == "false":
+        return False
+    return value
+
+
+def _read_metadata(path: Path) -> dict[str, object]:
+    data: dict[str, object] = {}
+    text = _read_text(path)
+    if not text:
+        return data
+
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        data[key.strip()] = _parse_scalar(value.strip())
+    return data
+
+
+def _display_path(repo_root: Path, path: Path) -> str:
+    try:
+        return path.resolve().relative_to(repo_root.resolve()).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def _resolve_link(repo_root: Path, base_dir: str, value: object) -> Path | None:
+    if not isinstance(value, str) or not value.strip():
+        return None
+
+    raw_path = Path(value)
+    if raw_path.is_absolute():
+        return raw_path
+
+    direct = repo_root / raw_path
+    workflow_base = Path(DIR_WORKFLOW) / base_dir
+    if direct.exists() or raw_path.parts[:2] == workflow_base.parts:
+        return direct
+    return repo_root / workflow_base / raw_path
+
+
+def _same_path(left: Path, right: Path) -> bool:
+    try:
+        return left.resolve() == right.resolve()
+    except OSError:
+        return left == right
+
+
+def _task_ancestry(repo_root: Path, task_dir: Path) -> list[Path]:
+    tasks_dir = get_tasks_dir(repo_root)
+    ancestry = [task_dir]
+    seen = {task_dir.name}
+    current = task_dir
+
+    while True:
+        data = _read_json(current / FILE_TASK_JSON)
+        parent = data.get("parent")
+        if not isinstance(parent, str) or not parent.strip() or parent in seen:
+            break
+        parent_dir = find_task_by_name(parent, tasks_dir)
+        if parent_dir is None:
+            break
+        ancestry.append(parent_dir)
+        seen.add(parent)
+        current = parent_dir
+
+    return ancestry
+
+
+def _task_tokens(repo_root: Path, ancestry: list[Path]) -> set[str]:
+    tokens: set[str] = set()
+    for path in ancestry:
+        tokens.add(path.name)
+        tokens.add(_display_path(repo_root, path))
+    return {token for token in tokens if token}
+
+
+def _plan_mentions_task(repo_root: Path, plan_path: Path | None, ancestry: list[Path]) -> bool:
+    if plan_path is None or not plan_path.is_file():
+        return False
+    text = _read_text(plan_path)
+    return any(token in text for token in _task_tokens(repo_root, ancestry))
+
+
+def _change_applies_to_task(
+    repo_root: Path,
+    metadata: dict[str, object],
+    task_dir: Path,
+) -> tuple[bool, bool]:
+    ancestry = _task_ancestry(repo_root, task_dir)
+    linked_task = _resolve_link(repo_root, DIR_TASKS, metadata.get("task"))
+    if linked_task is not None and any(_same_path(linked_task, item) for item in ancestry):
+        return True, False
+
+    plan_path = _resolve_link(repo_root, "plans", metadata.get("plan"))
+    if _plan_mentions_task(repo_root, plan_path, ancestry):
+        return True, linked_task is None
+
+    return False, False
+
+
+def _has_all_marker_groups(text: str, groups: tuple[tuple[str, ...], ...]) -> bool:
+    lower = text.lower()
+    return all(any(marker.lower() in lower for marker in group) for group in groups)
+
+
+def _has_verification_command(plan_text: str) -> bool:
+    lower = plan_text.lower()
+    if "verification" not in lower and "验证" not in lower:
+        return False
+    return any(marker in lower for marker in VERIFICATION_COMMAND_MARKERS)
+
+
+def _read_l2_context(repo_root: Path, change_dir: Path, plan_path: Path | None, task_dir: Path) -> str:
+    parts = [
+        _read_text(change_dir / "proposal.md"),
+        _read_text(change_dir / "spec.md"),
+        _read_text(change_dir / "design.md"),
+        _read_text(task_dir / "prd.md"),
+    ]
+    for ancestor in _task_ancestry(repo_root, task_dir)[1:]:
+        parts.append(_read_text(ancestor / "prd.md"))
+    if plan_path is not None:
+        parts.append(_read_text(plan_path))
+    return "\n\n".join(part for part in parts if part)
+
+
+def _append_missing_file_blocker(
+    blockers: list[str],
+    slug: str,
+    path: Path,
+    label: str,
+) -> None:
+    if not _read_text(path):
+        blockers.append(f"L2 readiness ({slug}): {label} is missing or empty")
+
+
+def _iter_change_dirs(repo_root: Path) -> list[Path]:
+    changes_dir = repo_root / DIR_WORKFLOW / DIR_CHANGES
+    if not changes_dir.is_dir():
+        return []
+    return [
+        path
+        for path in sorted(changes_dir.iterdir())
+        if path.is_dir() and path.name != DIR_ARCHIVE
+    ]
+
+
+def task_readiness_blockers(repo_root: Path, task_dir: Path) -> list[str]:
+    """Return readiness blockers for work linked to L2 changes."""
+    blockers: list[str] = []
+
+    for change_dir in _iter_change_dirs(repo_root):
+        metadata = _read_metadata(change_dir / "change.yaml")
+        if metadata.get("level") != "L2" or metadata.get("status") == "archived":
+            continue
+
+        applies, missing_task_link = _change_applies_to_task(repo_root, metadata, task_dir)
+        if not applies:
+            continue
+
+        slug = change_dir.name
+        if missing_task_link:
+            blockers.append(f"L2 readiness ({slug}): change.yaml task link is missing")
+
+        _append_missing_file_blocker(blockers, slug, change_dir / "proposal.md", "proposal.md")
+        _append_missing_file_blocker(blockers, slug, change_dir / "spec.md", "spec.md")
+        _append_missing_file_blocker(blockers, slug, change_dir / "design.md", "design.md")
+
+        plan_path = _resolve_link(repo_root, "plans", metadata.get("plan"))
+        if plan_path is None:
+            blockers.append(f"L2 readiness ({slug}): change.yaml plan link is missing")
+            plan_text = ""
+        elif not plan_path.exists():
+            blockers.append(
+                f"L2 readiness ({slug}): plan points to missing path: {_display_path(repo_root, plan_path)}"
+            )
+            plan_text = ""
+        else:
+            plan_text = _read_text(plan_path)
+            if not plan_text:
+                blockers.append(f"L2 readiness ({slug}): linked plan is empty")
+
+        linked_task = _resolve_link(repo_root, DIR_TASKS, metadata.get("task"))
+        if linked_task is not None and not linked_task.exists():
+            blockers.append(
+                f"L2 readiness ({slug}): task points to missing path: {_display_path(repo_root, linked_task)}"
+            )
+
+        context = _read_l2_context(repo_root, change_dir, plan_path, task_dir)
+        for label, marker_groups in REQUIRED_L2_MARKERS.items():
+            if not _has_all_marker_groups(context, marker_groups):
+                blockers.append(f"L2 readiness ({slug}): missing {label}")
+
+        if not _has_verification_command(plan_text):
+            blockers.append(f"L2 readiness ({slug}): linked plan is missing verification commands")
+
+    return blockers