cowork-flow 1.0.0 → 1.1.3

package/template/.cowork-flow/scripts/adapters/cli/task_parser.py

@@ -140,6 +140,15 @@ def _add_next_runtime_inputs(parser: argparse.ArgumentParser) -> None:
         action="store_true",
         help="Auto git commit after archive_task",
     )
+    parser.add_argument(
+        "--executor",
+        help="Explicit executor identity; enables sessionless (CI) start_task",
+    )
+    parser.add_argument(
+        "--takeover",
+        action="store_true",
+        help="Take the task over from its current executor on start_task",
+    )
 
 
 def _add_next_command(subparsers: argparse._SubParsersAction) -> None:

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

@@ -63,6 +63,7 @@ def build_hook_context(
     host: str,
     adapter: str,
     preamble: tuple[str, ...],
+    session_start: bool | None = None,
 ) -> str:
     breadcrumbs = _load_breadcrumbs(root)
     runtime_context, runtime_context_id = _resolve_runtime_context(
@@ -88,7 +89,6 @@ def build_hook_context(
         source = f"runtime-context-invalid:{runtime_context_id}"
         extra_lines = [
             f"Runtime context: {runtime_context_id}",
-            "Scope: subagent",
             (
                 "Runtime context is missing, closed, or invalid. "
                 "Do not run standalone lifecycle commands, resume, archive, commit, or spawn."
@@ -103,17 +103,187 @@ def build_hook_context(
     )
     if extra_lines:
         body = "\n".join([body, *extra_lines])
-    if task_path is None:
-        header = f"Status: {status}\nSource: {source}"
+    if session_start is None:
+        # No event signal from the host: treat the first injection as a
+        # session start. Session state files appear once a task activation
+        # exists (start), so their absence keeps every injection full.
+        session_start = not _session_has_started(root, hook_input)
+    if session_start:
+        digest_block = _build_contract_digest(root, host, adapter)
     else:
-        header = f"Task: {task_path}\nStatus: {status}\nSource: {source}"
-    return "\n\n".join(
-        [
-            *preamble,
-            _build_contract_digest(root, host, adapter),
-            f"<workflow-state>\n{header}\n{body}\n</workflow-state>",
-        ]
+        contracts, _warning = _load_contract_registry(root)
+        digest_block = (
+            f'<contract-fingerprint value="{contract_fingerprint(root, contracts)}"/>'
+        )
+    anchor_block = _decision_anchor_block(root, task_path, status)
+    blocks = [*preamble, digest_block]
+    if anchor_block:
+        blocks.append(anchor_block)
+    contract_block = _stage_contract_block(root, task_path, status)
+    if contract_block:
+        blocks.append(contract_block)
+    blocks.append(
+        f"<workflow-state{_workflow_state_attrs(task_path, status, source)}>"
+        f"\n{body}\n</workflow-state>"
     )
+    return "\n\n".join(blocks)
+
+
+def _session_has_started(root: Path, hook_input: dict[str, Any]) -> bool:
+    """True once the hook session holds a task activation state file.
+
+    Resolving the context key and probing the session directory keeps this
+    conservative: any resolution failure falls back to the full digest
+    (reported as "not started").
+    """
+    try:
+        from runtime.session_state import resolve_context_key, sessions_dir
+    except Exception:
+        return False
+    try:
+        context_key = resolve_context_key(hook_input)
+    except Exception:
+        return False
+    if not context_key:
+        return False
+    return (sessions_dir(root) / f"{context_key}.json").exists()
+
+
+def _xml_attr(value: Any) -> str:
+    # Delegates to the fact-view implementation: the escaping rules must stay
+    # identical across the decision-anchor and stage-contract blocks.
+    from services.fact_view import xml_attr
+
+    return xml_attr(value)
+
+
+def _workflow_state_attrs(
+    task_path: str | None, status: str, source: str
+) -> str:
+    """Structured fact header (context-injection.md, stage 1): the machine
+    picks task/status/source off the attributes; humans read the body."""
+    attrs = [f'status="{_xml_attr(status)}"', f'source="{_xml_attr(source)}"']
+    if task_path:
+        attrs.insert(0, f'task="{_xml_attr(task_path)}"')
+    return "".join(f" {attr}" for attr in attrs)
+
+
+DECISION_ANCHOR_STATES = ("planning", "in_progress", "review")
+STAGE_CONTRACT_STATES = ("in_progress", "review")
+
+
+def _effective_task_status(
+    root: Path, task_path: str, status: str
+) -> str | None:
+    """Delegated subtasks read the underlying task's status; every other
+    status is already effective."""
+    if status != "delegated_subtask":
+        return status
+    try:
+        data = json.loads(
+            (root / task_path / "task.json").read_text(encoding="utf-8")
+        )
+        effective_status = data.get("status")
+    except (OSError, json.JSONDecodeError):
+        return None
+    return effective_status if isinstance(effective_status, str) else None
+
+
+def _decision_anchor_block(
+    root: Path, task_path: str | None, status: str
+) -> str | None:
+    """Compact decision facts (why this task, what done means, what was
+    rejected) for states where they steer execution. Delegated subtasks read
+    the underlying task's status. Absent anchor file or terminal states
+    inject nothing."""
+    if not task_path:
+        return None
+    effective_status = _effective_task_status(root, task_path, status)
+    if effective_status not in DECISION_ANCHOR_STATES:
+        return None
+    try:
+        from services.fact_view import parse_decision_anchor
+
+        text = (root / task_path / "decision-anchor.md").read_text(
+            encoding="utf-8"
+        )
+        parsed = parse_decision_anchor(text)
+    except (OSError, UnicodeDecodeError):
+        # Absent or undecodable anchors are routine: no block, no noise.
+        return None
+    except Exception as error:
+        # Anything else leaves a trace so silent guard loss stays diagnosable
+        # (stdout is the injection channel, stderr is safe).
+        sys.stderr.write(f"decision-anchor degraded: {error}\n")
+        return None
+    if not parsed["goal"] and not parsed["acceptanceCriteria"]:
+        return None
+    lines = [f'<decision-anchor task="{_xml_attr(task_path)}">']
+    if parsed["goal"]:
+        lines.append(f"Goal: {parsed['goal'].splitlines()[0][:160]}")
+    if parsed["acceptanceCriteria"]:
+        items = "; ".join(
+            f"{item['id']} {item['text'][:80]}"
+            for item in parsed["acceptanceCriteria"][:8]
+        )
+        lines.append(f"Acceptance: {items}")
+    if parsed["rejectedOptions"]:
+        lines.append("Rejected: " + "; ".join(parsed["rejectedOptions"][:6]))
+    lines.append("</decision-anchor>")
+    return "\n".join(lines)
+
+
+def _stage_contract_block(
+    root: Path, task_path: str | None, status: str
+) -> str | None:
+    """Implementation contract (edit scope, specs to read, gates preview,
+    declared verification commands) for states where it steers execution.
+    Data comes from the frozen task artifacts via services.fact_view — the
+    single source shared with the MCP task_scope tool. Delegated subtasks
+    render the parent scope as a read-only reference."""
+    if not task_path:
+        return None
+    effective_status = _effective_task_status(root, task_path, status)
+    if effective_status not in STAGE_CONTRACT_STATES:
+        return None
+    try:
+        from services.context_paths import load_scope_rules
+        from services.fact_view import (
+            build_stage_contract,
+            file_scope_whitelist,
+            parse_decision_anchor,
+            spec_pointer_files,
+        )
+
+        task_dir = root / task_path
+        whitelist = file_scope_whitelist(root, task_dir)
+        spec_files = spec_pointer_files(task_dir)
+        rules = load_scope_rules(root)
+        anchor_path = task_dir / "decision-anchor.md"
+        try:
+            parsed = parse_decision_anchor(
+                anchor_path.read_text(encoding="utf-8")
+            )
+        except (OSError, UnicodeDecodeError):
+            # Absent or undecodable anchor: scope/gates still render; the
+            # verify line is dropped by the empty results.
+            parsed = {"validationCommands": []}
+        except Exception as error:
+            # Never silently kill the guard block: leave a degradation trace
+            # on stderr (stdout is the injection channel).
+            sys.stderr.write(f"stage-contract degraded: {error}\n")
+            return None
+        return build_stage_contract(
+            task_path,
+            whitelist,
+            spec_files,
+            parsed,
+            mutable=status != "delegated_subtask",
+            rules=rules,
+        )
+    except Exception as error:
+        sys.stderr.write(f"stage-contract degraded: {error}\n")
+        return None
 
 
 def _load_breadcrumbs(root: Path) -> dict[str, str]:
@@ -134,6 +304,29 @@ def _load_breadcrumbs(root: Path) -> dict[str, str]:
     }
 
 
+def contract_fingerprint(root: Path, contracts: list[dict[str, Any]]) -> str:
+    digest = hashlib.sha256()
+    digest.update(
+        json.dumps(
+            contracts,
+            ensure_ascii=False,
+            sort_keys=True,
+            # Compact separators keep the bytes identical to the JS
+            # stableStringify implementations (see context-injection.md).
+            separators=(",", ":"),
+        ).encode("utf-8")
+    )
+    for contract in contracts:
+        path = contract.get("path")
+        if not isinstance(path, str) or not path.strip():
+            continue
+        try:
+            digest.update((root / path).read_bytes())
+        except OSError:
+            digest.update(f"missing:{path}".encode("utf-8"))
+    return digest.hexdigest()[:16]
+
+
 def _load_contract_registry(
     root: Path,
 ) -> tuple[list[dict[str, Any]], str | None]:
@@ -172,25 +365,10 @@ def _build_contract_digest(
     adapter: str,
 ) -> str:
     contracts, warning = _load_contract_registry(root)
-    digest = hashlib.sha256()
-    digest.update(
-        json.dumps(
-            contracts,
-            ensure_ascii=False,
-            sort_keys=True,
-        ).encode("utf-8")
-    )
-    for contract in contracts:
-        path = contract.get("path")
-        if not isinstance(path, str) or not path.strip():
-            continue
-        try:
-            digest.update((root / path).read_bytes())
-        except OSError:
-            digest.update(f"missing:{path}".encode("utf-8"))
+    fingerprint = contract_fingerprint(root, contracts)
     lines = [
         f'<cowork-runtime host="{host}" adapter="{adapter}">',
-        f'<contract-digest fingerprint="{digest.hexdigest()[:16]}">',
+        f'<contract-digest fingerprint="{fingerprint}">',
         (
             "policy: repeat this short digest every hook; "
             "read full spec files only before listed actions."
@@ -276,10 +454,12 @@ def _subagent_runtime_lines(context: dict[str, Any]) -> list[str]:
         if isinstance(context.get("assignment"), dict)
         else {}
     )
+    # No "Scope: subagent" line here: the stage-contract block owns the scope
+    # declaration and renders the parent task's scope as a read-only reference
+    # for delegated sessions (build_stage_contract(mutable=False)).
     lines = [
         f"Runtime context: {context.get('runtime_context_id')}",
         f"Agent: {context.get('agent_type') or 'unknown'}",
-        "Scope: subagent",
         "Do not run standalone lifecycle commands, resume, archive, commit, or spawn.",
     ]
     goal = assignment.get("goal")

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

@@ -0,0 +1,14 @@
+"""Allow CLI adapter scripts to import the scripts package when run directly."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+SCRIPTS_DIR = Path(__file__).resolve().parents[2]
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+from adapters.cli.encoding import configure_cli_encoding
+
+configure_cli_encoding()

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

@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Read-only MCP stdio server exposing the cowork-flow fact layer.
+
+Stage 3 of docs/direction.md: any MCP client can query task facts without
+pulling the workflow into a prompt. Deliberately dependency-free — the MCP
+stdio transport is newline-delimited JSON-RPC 2.0, small enough to serve on
+the standard library while the ecosystem settles (see
+spec/contracts/fact-layer-access.md).
+
+Read-only guarantee: both tools only read repository state (fact view and
+the active task tree); there is no write path here. Writes keep flowing
+through the CLI lifecycle gates.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+if __package__:
+    from . import _bootstrap as _bootstrap  # noqa: F401
+else:
+    import _bootstrap  # noqa: F401
+
+from infra.paths import get_repo_root
+
+PROTOCOL_VERSION = "2025-06-18"
+SERVER_INFO = {"name": "cowork-flow-facts", "version": "1.0.0"}
+
+TOOLS = [
+    {
+        "name": "task_state",
+        "description": (
+            "Fact view for one task: task.json (with revision), decision-anchor "
+            "essentials (goal, acceptance criteria, rejected options), plan "
+            "binding, bound sessions, and the trusted state snapshot. Omit "
+            "`task` to use the caller's session-bound active task."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "task": {
+                    "type": "string",
+                    "description": "Task directory or name.",
+                },
+            },
+        },
+    },
+    {
+        "name": "task_list",
+        "description": (
+            "Active tasks overview: name, path, status, assignee, parent/child "
+            "links, and which one the current session has bound."
+        ),
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "task_specs",
+        "description": (
+            "Spec files the implementing agent should read for a task, "
+            "dispatched by its dev_type (base guides + domain skills + "
+            "backend/frontend/spec pointers). Read them before coding."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "task": {
+                    "type": "string",
+                    "description": "Task directory or name.",
+                },
+            },
+        },
+    },
+    {
+        "name": "task_scope",
+        "description": (
+            "Edit-scope verdict for a task. Without `path`: the file-scope "
+            "whitelist summary (only file/planned-file/deleted-file entries "
+            "authorize edits; directories authorize nothing). With `path`: "
+            "an inScope verdict for that one file. Edits outside the scope "
+            "are review blockers."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "task": {
+                    "type": "string",
+                    "description": "Task directory or name.",
+                },
+                "path": {
+                    "type": "string",
+                    "description": "Repo-relative file path to check.",
+                },
+            },
+        },
+    },
+]
+
+
+def _tool_task_state(root: Path, arguments: dict) -> dict:
+    from runtime.session_state import get_active_task
+    from services.fact_view import build_fact_view
+    from services.task_repository import TaskRepository, TaskRepositoryError
+
+    target = arguments.get("task")
+    if not target:
+        target = get_active_task(root).task_path
+        if not target:
+            return {"schemaVersion": 1, "task": None, "reason": "no-active-task"}
+    try:
+        task_dir = TaskRepository(root).resolve(target)
+    except TaskRepositoryError as error:
+        raise ValueError(str(error)) from error
+    if not (Path(task_dir) / "task.json").is_file():
+        raise ValueError(f"task.json not found under {task_dir}")
+    return build_fact_view(root, Path(task_dir))
+
+
+def _tool_task_list(root: Path, _arguments: dict) -> dict:
+    from adapters.cli.task_tree_commands import _list_task_records
+
+    records, error = _list_task_records(root, mine=False, status=None)
+    if error:
+        return {"tasks": [], "count": 0, "error": error}
+    return {"tasks": records, "count": len(records)}
+
+
+def _resolve_task_dir(root: Path, target: str | None) -> Path:
+    from runtime.session_state import get_active_task
+    from services.task_repository import TaskRepository, TaskRepositoryError
+
+    if not target:
+        target = get_active_task(root).task_path
+        if not target:
+            raise ValueError("no-active-task")
+    try:
+        task_dir = TaskRepository(root).resolve(target)
+    except TaskRepositoryError as error:
+        raise ValueError(str(error)) from error
+    try:
+        resolved = Path(task_dir).resolve()
+        resolved.relative_to(Path(root).resolve())
+    except ValueError as error:
+        raise ValueError("task-outside-repo") from error
+    if not (Path(task_dir) / "task.json").is_file():
+        raise ValueError(f"task.json not found under {task_dir}")
+    return Path(task_dir)
+
+
+def _tool_task_scope(root: Path, arguments: dict) -> dict:
+    from services.fact_view import file_scope_whitelist, path_in_scope
+
+    task_dir = _resolve_task_dir(root, arguments.get("task"))
+    whitelist = file_scope_whitelist(root, task_dir)
+    candidate = arguments.get("path")
+    if candidate:
+        verdict = path_in_scope(whitelist, str(candidate))
+        return {"taskDir": task_dir.name, **verdict}
+    return {
+        "taskDir": task_dir.name,
+        "whitelist": whitelist,
+        "count": len(whitelist),
+    }
+
+
+def _tool_task_specs(root: Path, arguments: dict) -> dict:
+    from services.context_discovery import implement_spec_entries
+    from services.fact_view import _read_json
+
+    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)
+    return {
+        "taskDir": task_dir.name,
+        "devType": dev_type,
+        "specs": specs,
+        "count": len(specs),
+    }
+
+
+TOOL_HANDLERS = {
+    "task_state": _tool_task_state,
+    "task_list": _tool_task_list,
+    "task_scope": _tool_task_scope,
+    "task_specs": _tool_task_specs,
+}
+
+
+def handle_request(root: Path, request: dict) -> dict | None:
+    """Dispatch one decoded JSON-RPC message. Notifications (no id member)
+    yield None and are never answered — including initialize/ping/tools/list,
+    which are requests only when an id is present."""
+    method = request.get("method")
+    request_id = request.get("id")
+    if "id" not in request:
+        return None
+    if method == "initialize":
+        requested = (request.get("params") or {}).get("protocolVersion")
+        return {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "result": {
+                "protocolVersion": requested or PROTOCOL_VERSION,
+                "capabilities": {"tools": {"listChanged": False}},
+                "serverInfo": SERVER_INFO,
+            },
+        }
+    if method == "ping":
+        return {"jsonrpc": "2.0", "id": request_id, "result": {}}
+    if method == "tools/list":
+        return {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "result": {"tools": TOOLS},
+        }
+    if method == "tools/call":
+        params = request.get("params") or {}
+        name = params.get("name")
+        handler = TOOL_HANDLERS.get(name)
+        if handler is None:
+            return {
+                "jsonrpc": "2.0",
+                "id": request_id,
+                "result": {
+                    "content": [
+                        {"type": "text", "text": f"unknown tool: {name}"}
+                    ],
+                    "isError": True,
+                },
+            }
+        try:
+            payload = handler(root, params.get("arguments") or {})
+        except Exception as error:  # tool errors ride the result, not the frame
+            return {
+                "jsonrpc": "2.0",
+                "id": request_id,
+                "result": {
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": f"{type(error).__name__}: {error}",
+                        }
+                    ],
+                    "isError": True,
+                },
+            }
+        return {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "result": {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": json.dumps(
+                            payload, ensure_ascii=False, indent=2
+                        ),
+                    }
+                ]
+            },
+        }
+    if request_id is None:
+        return None
+    return {
+        "jsonrpc": "2.0",
+        "id": request_id,
+        "error": {"code": -32601, "message": f"method not found: {method}"},
+    }
+
+
+def main() -> int:
+    root = get_repo_root()
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            request = json.loads(line)
+        except json.JSONDecodeError as error:
+            sys.stdout.write(
+                json.dumps(
+                    {
+                        "jsonrpc": "2.0",
+                        "id": None,
+                        "error": {"code": -32700, "message": str(error)},
+                    }
+                )
+                + "\n"
+            )
+            sys.stdout.flush()
+            continue
+        if not isinstance(request, dict):
+            continue
+        response = handle_request(root, request)
+        if response is None:
+            continue
+        sys.stdout.write(json.dumps(response, ensure_ascii=False) + "\n")
+        sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/template/.cowork-flow/scripts/infra/git_snapshot.py

@@ -58,17 +58,56 @@ def collect_changed_paths(repo_root: Path) -> list[str]:
     return [changed.path for changed in collect_changed_files(repo_root)]
 
 
-def _run_git_command(args: list[str], cwd: Path | None = None) -> tuple[int, str, str]:
-    completed = subprocess.run(
-        ["git", *args],
-        cwd=cwd,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        stdout=subprocess.PIPE,
-        stderr=subprocess.PIPE,
-        check=False,
+def collect_changed_paths_since(
+    repo_root: Path, base_commit: str | None
+) -> tuple[list[str], bool]:
+    """Merge the baseline..HEAD diff with the working-tree status:
+    (paths, degraded). Committing during a task no longer hides changed
+    files from review.
+
+    degraded=True when there is no baseline, HEAD does not exist, or the
+    diff fails (e.g. a rebase orphaned the baseline) — callers fall back to
+    status-only, which is exactly the pre-baseline behavior."""
+    status_paths = collect_changed_paths(repo_root)
+    if not base_commit:
+        return status_paths, True
+    rc, stdout, _ = _run_git_command(
+        ["diff", "--name-only", f"{base_commit}..HEAD"],
+        cwd=repo_root,
     )
+    if rc != 0:
+        return status_paths, True
+    diff_paths = [line.strip() for line in stdout.splitlines() if line.strip()]
+    merged = sorted(set(status_paths) | set(diff_paths))
+    return merged, False
+
+
+def current_head(repo_root: Path) -> str | None:
+    """Full HEAD sha of the repo, or None when no commits exist yet."""
+    rc, stdout, _ = _run_git_command(["rev-parse", "HEAD"], cwd=repo_root)
+    if rc != 0:
+        return None
+    value = stdout.strip()
+    return value or None
+
+
+def _run_git_command(args: list[str], cwd: Path | None = None) -> tuple[int, str, str]:
+    try:
+        completed = subprocess.run(
+            ["git", *args],
+            cwd=cwd,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+    except OSError:
+        # git unavailable (not installed, or PATH stripped): callers degrade
+        # through the existing rc!=0 paths — no HEAD means no baseline, no
+        # changes means status-only review.
+        return 127, "", "git unavailable"
     return completed.returncode, completed.stdout, completed.stderr