cowork-flow 1.2.0 → 1.3.0

package/template/.cowork-flow/scripts/adapters/host/zcode_policy.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""zcode host policy: the zcode-specific behaviors of the workflow hook.
+
+Rendering stays in workflow_state_hook.py (single source shared with the
+other hosts); this module owns only what is zcode-specific — the digest
+policy wording, the newest-session fallback for unbound hook sessions, the
+rebind hints and essential-files check ported from the zcode JS hook, the
+merged scope+spec edit warning, and the PostToolUse transport contract the
+zcode shim relies on.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+from adapters.host.workflow_state_hook import HostPolicy
+
+# Digest policy wording frozen by context-injection.md (zcode drops the
+# registry-warning line and asks for the fingerprint on every hook).
+ZCODE_DIGEST_POLICY = (
+    "policy: repeat fingerprint every hook; "
+    "read full spec files only before listed actions."
+)
+
+# The zcode shim (hooks/inject-context.js) pre-filters Bash events with the
+# same rule; this entry keeps the transport contract correct standalone.
+LIFECYCLE_BASH_RE = re.compile(r"\brun(?:\.cmd)?\s+(?:task|subagent|resume)\b")
+
+# Port of the zcode hook's essential-files check (inject-context.js
+# checkEssentialFiles): appended to the zcode context when any guard file of
+# the workflow install is missing.
+ESSENTIAL_FILES = (
+    "AGENTS.md",
+    ".cowork-flow/config.yaml",
+    ".cowork-flow/run",
+    ".cowork-flow/spec/runtime/contract-registry.json",
+    ".cowork-flow/spec/contracts/workflow-state-templates.md",
+)
+
+
+def is_lifecycle_bash(hook_input: dict[str, Any]) -> bool:
+    tool_input = hook_input.get("tool_input")
+    command = (
+        tool_input.get("command") if isinstance(tool_input, dict) else None
+    )
+    if not isinstance(command, str):
+        return False
+    normalized = command.replace("\\", "/")
+    return ".cowork-flow/run" in normalized or bool(
+        LIFECYCLE_BASH_RE.search(normalized)
+    )
+
+
+def zcode_session_alias(data: dict[str, Any]) -> dict[str, Any]:
+    # Ported from the zcode hook's resolveSessionKey candidate order
+    # (env wins inside session_state; input aliases only fill the gap).
+    # Without this, a bare sessionId/session_id would resolve as a codex
+    # session and lose the session's own binding.
+    existing = data.get("zcode_session_id")
+    if isinstance(existing, str) and existing.strip():
+        return data
+    for key in ("ZCODE_SESSION_ID", "sessionId", "session_id"):
+        value = data.get(key)
+        if isinstance(value, str) and value.strip():
+            data["zcode_session_id"] = value
+            break
+    return data
+
+
+def rebind_hints(root: Path) -> str:
+    """Port of the zcode hook's formatRebindHints: one-level task scan for
+    bindable (non-completed) tasks, appended to no_task/missing bodies."""
+    tasks_dir = root / ".cowork-flow" / "tasks"
+    try:
+        children = sorted(tasks_dir.iterdir())
+    except OSError:
+        return ""
+    entries: list[str] = []
+    for child in children:
+        if not child.is_dir():
+            continue
+        relative = f".cowork-flow/tasks/{child.name}"
+        task_json = child / "task.json"
+        if not task_json.is_file():
+            continue
+        try:
+            data = json.loads(task_json.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError, ValueError):
+            status = "unknown"
+        else:
+            status = str(data.get("status") or "unknown").strip() or "unknown"
+        if status == "completed":
+            continue
+        entries.append(f"- {relative} ({status})")
+    if not entries:
+        return ""
+    return (
+        "\n活动任务（可用 ./.cowork-flow/run task next <dir> 改绑）：\n"
+        + "\n".join(entries)
+    )
+
+
+def essential_files_warning(root: Path) -> str:
+    missing = [rel for rel in ESSENTIAL_FILES if not (root / rel).exists()]
+    if not missing:
+        return ""
+    return (
+        "\n\n⚠️ 缺少必要文件："
+        + ", ".join(missing)
+        + "。\n请立即创建这些文件以保障工作流正常运行。"
+    )
+
+
+def edit_scope_warning(root: Path, hook_input: dict[str, Any]) -> str:
+    """Per-edit out-of-scope warning (zcode-only capability). Port of the
+    zcode hook's editScopeWarning: at most one line when the edited file is
+    outside the task's file-scope whitelist. Silence rules match the JS
+    source, including the newest-session display fallback for sessions with
+    no resolvable identity. Never raises."""
+    from adapters.host.workflow_state_hook import (
+        STAGE_CONTRACT_STATES,
+        _get_active_task_with_fallback,
+        _session_scope,
+    )
+
+    try:
+        task_path, status, _source = _get_active_task_with_fallback(
+            root, hook_input, POLICY.fallback_for_unbound
+        )
+    except Exception:
+        return ""
+    if not task_path or status not in STAGE_CONTRACT_STATES:
+        return ""
+    if _session_scope(root, hook_input) == "subagent":
+        return ""
+    tool_input = hook_input.get("tool_input")
+    file_path = (
+        tool_input.get("file_path") if isinstance(tool_input, dict) else None
+    )
+    if not isinstance(file_path, str) or not file_path.strip():
+        return ""
+    # Hosts pass absolute edit paths; whitelist entries are repo-relative.
+    # Same normalization the spec path applies in run_edit_checks.
+    normalized = file_path.replace("\\", "/").strip()
+    try:
+        normalized = (
+            Path(normalized).resolve().relative_to(root.resolve()).as_posix()
+        )
+    except (ValueError, OSError):
+        pass
+    try:
+        from services.fact_view import file_scope_whitelist, path_in_scope
+
+        whitelist = file_scope_whitelist(root, root / task_path)
+        if path_in_scope(whitelist, normalized).get("inScope"):
+            return ""
+    except Exception:
+        return ""
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+    return (
+        f"⚠️ {normalized} is outside the task's declared scope. "
+        "If intended, add it with `task context add` (agent-mutable) "
+        "or revert the edit."
+    )
+
+
+def merged_edit_warning(root: Path, hook_input: dict[str, Any]) -> str:
+    """zcode PostToolUse Edit/Write/MultiEdit context: the scope warning and
+    the spec-check warning merged into one additionalContext payload, at
+    most one line each, joined by a newline (port of the zcode hook's
+    mergedEditWarning)."""
+    from adapters.host.workflow_state_hook import spec_edit_warning
+
+    scope_line = edit_scope_warning(root, hook_input)
+    spec_line = spec_edit_warning(root, hook_input, POLICY)
+    if scope_line and spec_line:
+        return f"{scope_line}\n{spec_line}"
+    return scope_line or spec_line
+
+
+def post_tool_use(root: Path, hook_input: dict[str, Any]) -> tuple[str, int]:
+    """zcode PostToolUse transport: Edit/Write/MultiEdit get the merged
+    edit warning; Bash events refresh the full state only for workflow
+    lifecycle commands (the shim pre-filters the common case, this keeps
+    the entry correct standalone). Edit storms must not multiply the
+    injection payload."""
+    tool_name = str(hook_input.get("tool_name") or "")
+    tool_input = hook_input.get("tool_input")
+    file_path = (
+        tool_input.get("file_path") if isinstance(tool_input, dict) else None
+    )
+    if (
+        tool_name in {"Edit", "Write", "MultiEdit"}
+        and isinstance(file_path, str)
+        and file_path.strip()
+    ):
+        return merged_edit_warning(root, hook_input), 0
+    if not is_lifecycle_bash(hook_input):
+        return "", 0
+    from adapters.host.workflow_state_hook import build_hook_context
+
+    context = build_hook_context(
+        root,
+        hook_input,
+        host=POLICY.host,
+        adapter="zcode.plugin",
+        preamble=(),
+        session_start=False,
+        policy=POLICY,
+    )
+    return context, 0
+
+
+POLICY = HostPolicy(
+    host="zcode",
+    digest_policy=ZCODE_DIGEST_POLICY,
+    digest_warning_silent=True,
+    session_alias=zcode_session_alias,
+    rebind_hints=rebind_hints,
+    essential_files_warning=essential_files_warning,
+    fallback_for_unbound=True,
+    post_tool_use=post_tool_use,
+    emit_indent=True,
+    emit_not_initialized=True,
+)

package/template/.cowork-flow/scripts/adapters/mcp/state_server.py

@@ -166,13 +166,10 @@ def _tool_task_scope(root: Path, arguments: dict) -> dict:
 
 
 def _tool_task_specs(root: Path, arguments: dict) -> dict:
-    from services.context_discovery import implement_spec_entries
-    from services.fact_view import _read_json
+    from services.fact_view import spec_entries_for_task
 
     task_dir = _resolve_task_dir(root, arguments.get("task"))
-    task = _read_json(task_dir / "task.json")
-    dev_type = task.get("dev_type") if isinstance(task, dict) else None
-    specs = implement_spec_entries(root, dev_type)
+    dev_type, specs = spec_entries_for_task(root, task_dir)
     return {
         "taskDir": task_dir.name,
         "devType": dev_type,

package/template/.cowork-flow/scripts/runtime/session_state.py

@@ -34,6 +34,14 @@ RUNTIME_CONTEXT_PROMPT_RE = re.compile(
 HOST_CONTEXT_PROMPT_RE = re.compile(
     r"(?im)^\s*cowork_host_context_key\s*:\s*([A-Za-z0-9._-]+)\s*$"
 )
+# Process-label providers: hosts whose Bash spawns carry only a shared
+# process label (no per-session id). Data-driven like the env mapping tables
+# below — adding a host is one row, no host branches in this module. The
+# identity is process-level shared; consumers must treat it as
+# PROVENANCE_PROCESS_FALLBACK and degrade accordingly.
+PROCESS_LABEL_PROVIDERS: tuple[tuple[str, str], ...] = (
+    ("zcode", "ZCODE_PROCESS_LABEL"),
+)
 
 
 @dataclass(frozen=True)
@@ -76,15 +84,17 @@ def resolve_context_key_with_provenance(
     context_key = _resolve_input_context_key(values)
     if context_key:
         return context_key, PROVENANCE_HOST_SESSION
-    # zcode 主会话（Bash CLI）无任何 host session id：用进程标签兜底，
-    # 保证 task start / session 解析一次成功，不再回落到其它 host。
-    # 该身份是进程级共享的，消费方必须按 PROVENANCE_PROCESS_FALLBACK 降级处理。
-    process_label = os.environ.get("ZCODE_PROCESS_LABEL")
-    if process_label and process_label.strip():
-        return (
-            _prefixed_context_key("zcode", process_label),
-            PROVENANCE_PROCESS_FALLBACK,
-        )
+    # Hosts whose Bash CLI carries no session id fall back to their shared
+    # process label so task start / session resolution succeeds once instead
+    # of dropping to another host's identity. Process-level shared identity —
+    # consumers must degrade per PROVENANCE_PROCESS_FALLBACK.
+    for prefix, env_name in PROCESS_LABEL_PROVIDERS:
+        process_label = os.environ.get(env_name)
+        if process_label and process_label.strip():
+            return (
+                _prefixed_context_key(prefix, process_label),
+                PROVENANCE_PROCESS_FALLBACK,
+            )
     return None, PROVENANCE_MISSING
 
 

package/template/.cowork-flow/scripts/services/context_discovery.py

@@ -85,14 +85,27 @@ def detect_installed_platforms(repo_root: Path | None = None) -> list[str]:
     return platforms
 
 
-def use_claude_skill_context(repo_root: Path | None = None) -> bool:
-    return detect_installed_platforms(repo_root) == ["claude-code"]
+# Platforms that load skills from their own asset dir declare it here; the
+# shared .agents/skills layout is the default for every other platform.
+SKILL_REPLICA_DIR_BY_PLATFORM = {
+    "claude-code": ".claude/skills",
+}
+
+
+def skill_root(repo_root: Path | None = None) -> str:
+    """Neutral rule over platform data: when exactly one platform is
+    installed and that platform declares a dedicated skill replica dir, the
+    skills live there; otherwise the shared .agents/skills layout applies."""
+    platforms = detect_installed_platforms(repo_root)
+    if len(platforms) == 1:
+        dedicated = SKILL_REPLICA_DIR_BY_PLATFORM.get(platforms[0])
+        if dedicated:
+            return dedicated
+    return f"{DIR_AGENTS}/skills"
 
 
 def skill_path(name: str, repo_root: Path | None = None) -> str:
-    if use_claude_skill_context(repo_root):
-        return f".claude/skills/{name}/SKILL.md"
-    return f"{DIR_AGENTS}/skills/{name}/SKILL.md"
+    return f"{skill_root(repo_root)}/{name}/SKILL.md"
 
 
 def get_domain_skill_context(

package/template/.cowork-flow/scripts/services/fact_view.py

@@ -189,6 +189,20 @@ def path_in_scope(
     }
 
 
+def spec_entries_for_task(
+    repo_root: Path, task_dir: Path
+) -> tuple[Any, list[dict]]:
+    """Public facade for the implement reading list: the task's dev_type plus
+    the dispatched spec/skill entries. The MCP task_specs tool and the
+    `task specs` CLI fact command both consume this, so the two channels
+    cannot drift."""
+    from services.context_discovery import implement_spec_entries
+
+    task = _read_json(task_dir / "task.json")
+    dev_type = task.get("dev_type") if isinstance(task, dict) else None
+    return dev_type, implement_spec_entries(repo_root, dev_type)
+
+
 STAGE_CONTRACT_STATES = ("in_progress", "review")
 STAGE_CONTRACT_SCOPE_LIMIT = 8
 STAGE_CONTRACT_SPECS_LIMIT = 4

package/template/.cowork-flow/scripts/services/spec_check.py

@@ -33,10 +33,11 @@ from typing import Iterable
 # is kept free of CLI/process plumbing concerns by architecture tests.
 IS_WINDOWS = os.name == "nt"
 
-# Editor-phase budget: the zcode/claude PostToolUse hook runs on a 5s hard
-# budget including interpreter startup, so edit-phase commands get 3s and
-# nothing more.
-EDIT_PHASE_TIMEOUT = 3.0
+# Editor-phase budget: the zcode/claude PostToolUse hook runs on a ~5s hard
+# budget including interpreter startup, so edit-phase commands get 2.5s —
+# leaving room for Python startup plus cmd.exe wrapper overhead on slow
+# machines. Slow or unfiltered commands belong to the lifecycle phase.
+EDIT_PHASE_TIMEOUT = 2.5
 DEFAULT_TIMEOUT = 30.0
 MAX_TIMEOUT = 120.0
 MAX_FIRST_LINE_CHARS = 200
@@ -215,7 +216,7 @@ def _parse_files(raw: str) -> tuple[tuple[str, ...], list[str]]:
     errors: list[str] = []
     matched: list[str] = []
     for part in raw.split(","):
-        token = part.strip().replace("\\", "/")
+        token = _strip_quotes(part).replace("\\", "/")
         while token.startswith("./"):
             token = token[2:]
         if not token:
@@ -287,12 +288,24 @@ def _first_violation_line(output: Iterable[str]) -> str:
 def _run_command(decl: CheckDecl, repo_root: Path) -> tuple[str, int | None, str, list[str]]:
     """Execute one declaration. Returns (status, exit_code, reason, output)."""
     command = _decl_for_platform(decl)
+    tokens: list[str] = []
     if IS_WINDOWS:
         # Windows: newer runtimes refuse to spawn .cmd shims directly
-        # (EINVAL); route through cmd.exe the way npm shims launch. Failure
-        # to find cmd.exe or the entry degrades to unchecked, never pass.
-        argv = ["cmd.exe", "/c", command]
-        popen_kwargs: dict = {}
+        # (EINVAL), so the command goes through cmd.exe. Passing an argv list
+        # makes list2cmdline escape an already-quoted command into `\"...\"`
+        # — cmd then strips the outer quotes and fails to parse — so the
+        # raw string runs via shell=True, exactly the way npm shims launch.
+        # The entry check keeps "missing command" as unchecked instead of a
+        # cmd.exe rc=1 masquerading as a violation.
+        try:
+            tokens = shlex.split(command, posix=False)
+        except ValueError:
+            tokens = []
+        first_token = tokens[0].strip('"') if tokens else ""
+        if not first_token or shutil.which(first_token) is None:
+            return "unchecked", None, f"command not found: {first_token}", []
+        argv: str | list[str] = command
+        popen_kwargs: dict = {"shell": True}
     else:
         try:
             argv = shlex.split(command)
@@ -309,7 +322,11 @@ def _run_command(decl: CheckDecl, repo_root: Path) -> tuple[str, int | None, str
             argv,
             cwd=str(repo_root),
             capture_output=True,
-            text=True,
+            # Explicit UTF-8 with replacement: command output is process
+            # noise (first violation line only), never allowed to crash the
+            # reader thread or masquerade as a check outcome.
+            encoding="utf-8",
+            errors="replace",
             timeout=decl.timeout,
             check=False,
             **popen_kwargs,
@@ -418,7 +435,9 @@ def normalized_one_line(report: dict) -> str:
 # Per-file throttle for editor-phase runs: an edit storm must not multiply
 # the command cost. State lives in the workflow runtime directory because
 # every hook invocation is a fresh process — in-memory maps cannot throttle
-# across invocations.
+# across invocations. The slot is recorded only after a completed run: an
+# executor crash must not consume the interval, so the next edit within it
+# still runs its checks.
 EDIT_THROTTLE_INTERVAL_SECONDS = 10.0
 EDIT_THROTTLE_FILE = ".cowork-flow" / Path(".runtime") / "spec-edit-throttle.json"
 
@@ -481,11 +500,14 @@ def run_edit_checks(
             and current - state["ts"] < EDIT_THROTTLE_INTERVAL_SECONDS
         ):
             return ""
-        _write_throttle(repo_root, normalized, current)
     try:
         report = run_checks(repo_root, phase="edit", changed_files=[normalized])
     except Exception:
+        # Executor crash (not a check failure): leave the throttle untouched
+        # so a retry within the interval is not silently swallowed.
         return ""
+    if throttled:
+        _write_throttle(repo_root, normalized, time.time() if now is None else now)
     return normalized_one_line(report)
 
 

package/template/.cowork-flow/scripts/services/task_context.py

@@ -18,7 +18,6 @@ from services.context_discovery import (
     implement_spec_entries,
     is_skill_path,
     skill_path,
-    use_claude_skill_context,
 )
 from services.context_jsonl import (
     ContextJsonlEntry,

package/template/.cowork-flow/spec/contracts/context-injection.md

@@ -3,10 +3,11 @@
 Single source for how every host adapter injects cowork-flow runtime context
 into a session: the transport shape, the event timing matrix, the contract
 digest shape rules (full block vs fingerprint line), and the fingerprint
-serialization norm. All host implementations — zcode JS hook, the Python
-shared core (codex / claude-code / dsh), and the opencode JS plugin — must
-follow this document; cross-host behavior tests lock the three independent
-implementations to it.
+serialization norm. The workflow facts are rendered by ONE Python source —
+`adapters/host/inject.py` over `workflow_state_hook.py` +
+`services.fact_view.py` — consumed by the zcode transport shim (node),
+claude-code, codex, and dsh; the opencode JS plugin remains the one
+independent mirror, locked to the same bytes by cross-host behavior tests.
 
 This document is a meta-protocol: it describes the injection layer itself and
 is intentionally **not** registered in `contract-registry.json` (registering it
@@ -16,9 +17,9 @@ would make the digest self-referential).
 
 | Host | Transport | Shape |
 |---|---|---|
-| zcode | process hook (`inject-context.js`), stdout JSON | `hookSpecificOutput.{hookEventName, additionalContext}` |
-| codex | command hook (Python shell), stdout JSON | same shape |
-| claude-code | command hook (Python shell), stdout JSON | same shape |
+| zcode | process hook shim (`inject-context.js`) → `inject.py --host zcode`, stdout JSON | `hookSpecificOutput.{hookEventName, additionalContext}` |
+| codex | thin wrapper (`inject-workflow-state.py`) → `inject.py --host codex`, stdout JSON | same shape |
+| claude-code | thin wrapper (`inject-workflow-state.py`) → `inject.py --host claude-code`, stdout JSON | same shape |
 | opencode | plugin `experimental.chat.system.transform` + `shell.env` | system-prompt section push / env object |
 | dsh | preset plugin system-prompt section | named section, replace semantics |
 
@@ -27,7 +28,8 @@ runtime preamble, the contract digest (full block or fingerprint line, see
 below), optional `decision-anchor` / `stage-contract` blocks, and the
 `<workflow-state>` block. It is **not** byte-identical across hosts at the
 string level — the digest policy line differs per host wording and zcode
-drops the registry-warning line. Exactly two things are byte-identical and
+drops the registry-warning line; both differences are selected inside the
+single Python source by `--host`. Exactly two things are byte-identical and
 test-locked: the contract digest **fingerprint value** and the
 `<stage-contract>` block.
 
@@ -171,16 +173,17 @@ Verify: npm run test:fast; python3 -m pytest tests/ -q
   (min 1) — the closing tag and the Gates row always survive; tests assert
   the block stays well-formed. The scope-filter rules and the stage-contract
   budget/limits come from `.cowork-flow/spec/runtime/scope-rules.json`, the
-  single source consumed by Python and both JS mirrors at runtime; a missing
-  or malformed file degrades to embedded defaults that are byte-identical
-  with the shipped file (locked by `tests/test_scope_rules.py`).
+  single source consumed at runtime; a missing or malformed file degrades to
+  embedded defaults that are byte-identical with the shipped file (locked by
+  `tests/test_scope_rules.py`).
 - Absent for `no_task` / `planning` / `completed` states. Block content is
-  byte-identical across the three host implementations for the whole fixture
-  matrix (`test/fixtures/stage-contract-matrix.json` drives the cross-host
-  equality test: canonical, `./`-prefixed, invalid-boundary, over-budget,
-  emoji, missing-anchor, empty-scope, delegated-readonly). The JS scope
-  filter is a port of the Python rules and is locked by that matrix — a
-  port, not a mechanism, so the matrix list grows whenever the rules grow.
+  byte-identical across host lines for the whole fixture matrix
+  (`test/fixtures/stage-contract-matrix.json` drives the equality test:
+  canonical, `./`-prefixed, invalid-boundary, over-budget, emoji,
+  missing-anchor, empty-scope, delegated-readonly). The zcode line now runs
+  through the same Python source as the python line (transport shim), so the
+  matrix's remaining cross-host assertion is opencode's JS mirror against
+  the single source — a mirror, not a mechanism.
 
 The authoritative per-file verdict lives in the MCP `task_scope` tool
 (`services.fact_view.file_scope_whitelist` — same semantics, live data).
@@ -189,15 +192,16 @@ The authoritative per-file verdict lives in the MCP `task_scope` tool
 
 sha256 over (1) the registry `contracts` array serialized with
 **recursively sorted keys** (Python `json.dumps(..., sort_keys=True,
-ensure_ascii=False)`; the JS implementations use the equivalent
+ensure_ascii=False)`; the opencode plugin uses the equivalent
 `stableStringify`), then (2) each contract file's raw bytes in registry
 order; a missing file hashes as the literal string `missing:<path>`. The
 fingerprint is the first 16 hex chars of the digest.
 
-Serialization must be byte-identical across the three implementations: same
+Serialization must be byte-identical across implementations: same
 key order, same escaping (ASCII-safe content), same UTF-8 encoding. The
 cross-host test (`test/contract-fingerprint.test.js`) asserts this and is the
-regression lock against drift.
+regression lock against drift between the opencode mirror and the Python
+single source.
 
 ## Change guard
 

package/template/.cowork-flow/spec/contracts/fact-layer-access.md

@@ -1,7 +1,19 @@
 # Fact-layer access
 
 How external tools (MCP clients today, other ecosystem protocols as they
-converge) read cowork-flow task facts. Stage 3 of `docs/direction.md`.
+converge) and agents on hosts without injection hooks read cowork-flow task
+facts. Stage 3 of `docs/direction.md`.
+
+## Three channels, one fact layer
+
+All channels consume the same services layer (`services/fact_view.py`) and
+cannot drift on facts:
+
+| Channel | Direction | Role |
+|---|---|---|
+| Hooks (host adapter → `inject.py`) | push | Proactive context injection; host-enforced, agents cannot skip it. |
+| CLI lifecycle commands | write + pull | The only write path; enforces the full gate chain. Pull fallback when MCP is unavailable. |
+| MCP tools | pull | Standardized read access for external clients (IDEs, dashboards) and hosts without hook support. |
 
 ## Stance
 
@@ -25,19 +37,42 @@ stderr is kept log-only).
 
 Global registration: `cowork-flow mcp-state` (npm CLI) resolves the nearest
 `.cowork-flow/` from the client's cwd and execs that project's runner with
-inherited stdio — register it once (`command: cowork-flow, args:
-["mcp-state"]`) and every cowork-flow project works, because the root
-resolution is identical to the server's own (`get_repo_root`). Outside a
-project the passthrough fails with a clear error; inside one, nested
-subdirectories resolve to the project root.
+inherited stdio. Outside a project the passthrough fails with a clear error;
+inside one, nested subdirectories resolve to the project root.
 
 Server info: `cowork-flow-facts`. On `initialize` the server echoes the
 client's requested `protocolVersion` (falling back to `2025-06-18`).
 
 | Tool | Input | Output | Reads |
 |---|---|---|---|
-| `task_state` | `{task?: string}` | The fact view as JSON text (`task`, `decisionAnchor`, `plan`, `sessions`, `snapshot`); without `task`, the session-bound active task, or `{"task": null, "reason": "no-active-task"}` | `services/fact_view.build_fact_view` |
+| `task_state` | `{task?: string}` | The fact view as JSON text (`task`, `decisionAnchor`, `plan`, `sessions`, `snapshot`); without `task`, the session-bound active task when one resolves, or `{"task": null, "reason": "no-active-task"}` | `services/fact_view.build_fact_view` |
 | `task_list` | `{}` | Active tasks overview: name, path, status, assignee, parent/children, active flag | `TaskTreeService.active_nodes` via the list records |
+| `task_scope` | `{task?: string, path?: string}` | The file-scope whitelist summary, or a per-path `inScope` verdict with `path` | `services/fact_view.file_scope_whitelist` / `path_in_scope` |
+| `task_specs` | `{task?: string}` | The spec/skill reading list dispatched by the task's `dev_type` | `services/fact_view.spec_entries_for_task` |
+
+`task_scope` and `task_specs` have CLI fact-command equivalents
+(`task scope`, `task specs`) consuming the same facade — MCP holds no
+exclusive capability.
+
+The MCP server process has no session concept: `task_state` without `task`
+resolves the caller's session only when session identity reaches the server
+through the environment (session-bound env keys). Where it cannot, it returns
+`no-active-task` — pass `task` explicitly for deterministic project-level
+queries. Session-bound facts remain the hook/CLI channels' responsibility.
+
+## Registration map (two tiers)
+
+| Host | Global (supported default) | Project-level opt-in |
+|---|---|---|
+| claude-code | `claude mcp add cowork-flow -- cowork-flow mcp-state` | `.mcp.json` with an `mcpServers` entry |
+| zcode | user config `mcp.servers.cowork-flow = {command: cowork-flow, args: [mcp-state]}` | plugin format has no MCP field — use the global tier |
+| codex | `~/.codex/config.toml` `[mcp_servers.cowork-flow]` | project config cannot enable user-approval-gated capabilities — use the global tier |
+| opencode | `opencode.json` `mcp` entry | — |
+
+`run doctor` reports the registration state (project entry present, absent,
+or duplicated across tiers) as an advisory, read-only health item. Registering
+a new contract changes the digest fingerprint everywhere; see the change
+guard.
 
 Tool failures (unknown task, missing task.json) ride the tool result with
 `isError: true`; the JSON-RPC frame stays valid.
@@ -47,4 +82,4 @@ Tool failures (unknown task, missing task.json) ride the tool result with
 - New fact sources (fields on the fact view) are additive; consumers must
   tolerate unknown keys.
 - Any write-capable tool proposal must re-open this contract first — and is
-  rejected by default under the current stance.
+  rejected by default under the current stance.