cowork-flow 0.0.37 → 0.0.39

package/template/.claude/hooks/inject-workflow-state.py

@@ -3,34 +3,31 @@
 
 from __future__ import annotations
 
-import hashlib
 import json
 import os
-import re
 import sys
 from pathlib import Path
 from typing import Any
 
-TAG_RE = re.compile(
-    r"\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n(.*?)\n\s*\[/workflow-state:\1\]",
-    re.DOTALL,
-)
-DEFAULT_CONTRACT_REGISTRY = {
-    "contracts": [
-        {
-            "id": "RUNTIME_CONTEXT_DISPATCH_V2",
-            "path": ".cowork-flow/spec/contracts/subagent-dispatch.md",
-            "digest": [
-                "Formal subagent work is keyed by cowork_runtime_context_id.",
-                "Explicit shim bind records bound_context_key before formal output is accepted.",
-            ],
-            "readWhen": ["before formal subagent dispatch", "when checking subagent health"],
-        },
-    ]
-}
+
+def _read_input() -> dict[str, Any]:
+    raw = sys.stdin.buffer.read()
+    if not raw.strip():
+        return {}
+    try:
+        data = json.loads(raw.decode("utf-8-sig"))
+    except (UnicodeDecodeError, json.JSONDecodeError, ValueError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    if "claude_session_id" not in data:
+        session_id = data.get("session_id")
+        if isinstance(session_id, str) and session_id.strip():
+            data["claude_session_id"] = session_id
+    return data
 
 
-def _find_repo_root(start: Path) -> Path | None:
+def _find_root(start: Path) -> Path | None:
     current = start.resolve()
     while True:
         if (current / ".cowork-flow").is_dir():
@@ -40,250 +37,50 @@ def _find_repo_root(start: Path) -> Path | None:
         current = current.parent
 
 
-def _read_hook_input() -> dict[str, Any]:
-    try:
-        raw = sys.stdin.buffer.read()
-    except AttributeError:
-        text = sys.stdin.read()
-    else:
-        if not raw.strip():
-            return {}
-        try:
-            text = raw.decode("utf-8-sig")
-        except UnicodeDecodeError:
-            encoding = getattr(sys.stdin, "encoding", None) or "utf-8"
-            text = raw.decode(encoding, errors="replace")
-    if not text.strip():
-        return {}
-    try:
-        data = json.loads(text)
-    except (json.JSONDecodeError, ValueError):
-        return {}
-    return data if isinstance(data, dict) else {}
-
-
-def _hook_event_name(hook_input: dict[str, Any]) -> str:
-    value = hook_input.get("hook_event_name") or hook_input.get("hookEventName")
-    if isinstance(value, str) and value.strip():
-        return value.strip()
-    return "UserPromptSubmit"
-
-
-def _normalize_hook_input(hook_input: dict[str, Any]) -> dict[str, Any]:
-    normalized = dict(hook_input)
-    if "claude_session_id" not in normalized:
-        session_id = normalized.get("session_id")
-        if isinstance(session_id, str) and session_id.strip():
-            normalized["claude_session_id"] = session_id
-    return normalized
-
-
-def _load_breadcrumbs(root: Path) -> dict[str, str]:
-    workflow = root / ".cowork-flow" / "spec" / "contracts" / "workflow-state-templates.md"
-    try:
-        text = workflow.read_text(encoding="utf-8")
-    except OSError:
-        return {}
-    return {match.group(1): match.group(2).strip() for match in TAG_RE.finditer(text)}
-
-
-def _as_string_list(value: Any) -> list[str]:
-    if not isinstance(value, list):
-        return []
-    return [item for item in value if isinstance(item, str) and item.strip()]
-
-
-def _load_contract_registry(root: Path) -> tuple[list[dict[str, Any]], str | None]:
-    registry_file = root / ".cowork-flow" / "spec" / "runtime" / "contract-registry.json"
-    try:
-        data = json.loads(registry_file.read_text(encoding="utf-8"))
-    except OSError:
-        data = DEFAULT_CONTRACT_REGISTRY
-        warning = f"contract registry unavailable at {registry_file}; using fallback digest"
-    except json.JSONDecodeError:
-        data = DEFAULT_CONTRACT_REGISTRY
-        warning = f"contract registry invalid at {registry_file}; using fallback digest"
-    else:
-        warning = None
-    contracts = data.get("contracts") if isinstance(data, dict) else None
-    if not isinstance(contracts, list):
-        contracts = DEFAULT_CONTRACT_REGISTRY["contracts"]
-        warning = warning or f"contract registry has no contracts array at {registry_file}; using fallback digest"
-    return [contract for contract in contracts if isinstance(contract, dict)], warning
-
-
-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).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 _build_contract_digest(root: Path) -> str:
-    contracts, warning = _load_contract_registry(root)
-    fingerprint = _contract_fingerprint(root, contracts)
-    lines = [
-        '<cowork-runtime host="claude-code" adapter="claude-code.hooks">',
-        f'<contract-digest fingerprint="{fingerprint}">',
-        "policy: repeat this short digest every hook; read full spec files only before listed actions.",
-    ]
-    if warning:
-        lines.append(f"warning: {warning}")
-    for contract in contracts:
-        contract_id = contract.get("id")
-        path = contract.get("path")
-        if not isinstance(contract_id, str) or not contract_id.strip():
-            continue
-        path_text = path if isinstance(path, str) and path.strip() else "<missing-path>"
-        lines.append(f"- {contract_id}: {path_text}")
-        for item in _as_string_list(contract.get("digest"))[:2]:
-            lines.append(f"  digest: {item}")
-        read_when = _as_string_list(contract.get("readWhen"))
-        if read_when:
-            lines.append(f"  read_before: {'; '.join(read_when)}")
-    lines.extend(["</contract-digest>", "</cowork-runtime>"])
-    return "\n".join(lines)
-
-
-def _load_common(root: Path) -> None:
-    scripts_dir = root / ".cowork-flow" / "scripts"
-    if str(scripts_dir) not in sys.path:
-        sys.path.insert(0, str(scripts_dir))
-
-
-def _get_active_task(root: Path, hook_input: dict[str, Any]) -> tuple[str | None, str, str]:
-    _load_common(root)
-    try:
-        from common.task.active_task import get_active_task  # type: ignore[import-not-found]
-    except Exception:
-        return None, "no_task", "unavailable"
-
-    active = get_active_task(root, hook_input)
-    if not active.task_path:
-        return None, "no_task", active.source
-
-    task_dir = root / active.task_path
-    task_json = task_dir / "task.json"
-    try:
-        data = json.loads(task_json.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return active.task_path, "stale", active.source
-
-    status = data.get("status")
-    if not isinstance(status, str) or not status.strip():
-        status = "unknown"
-    return active.task_path, status.strip(), active.source
-
-
-def _resolve_runtime_context(root: Path, hook_input: dict[str, Any]) -> tuple[dict[str, Any] | None, str | None]:
-    _load_common(root)
-    try:
-        from common.task.active_task import (  # type: ignore[import-not-found]
-            bind_runtime_context,
-            read_runtime_context,
-            resolve_runtime_context_id,
-        )
-    except Exception:
-        return None, None
-
-    runtime_context_id = resolve_runtime_context_id(hook_input)
-    if not runtime_context_id:
-        return None, None
-
-    context = read_runtime_context(root, runtime_context_id)
-    if not context or context.get("scope") != "subagent" or context.get("status") == "closed":
-        return None, runtime_context_id
-
-    bound = bind_runtime_context(root, runtime_context_id, values=hook_input)
-    return bound or context, runtime_context_id
-
-
-def _subagent_runtime_lines(context: dict[str, Any]) -> list[str]:
-    assignment = context.get("assignment") if isinstance(context.get("assignment"), dict) else {}
-    lines = [
-        f"Runtime context: {context.get('runtime_context_id')}",
-        f"Agent: {context.get('agent_type') or 'unknown'}",
-        "Scope: subagent",
-        "Do not run start/resume/task start/archive/commit/spawn.",
-    ]
-    goal = assignment.get("goal") if isinstance(assignment, dict) else None
-    if isinstance(goal, str) and goal.strip():
-        lines.append(f"Goal: {goal.strip()}")
-    return lines
-
-
-def _build_context(
-    root: Path,
-    task_path: str | None,
-    status: str,
-    source: str,
-    breadcrumbs: dict[str, str],
-    extra_lines: list[str] | None = None,
-) -> str:
-    body = breadcrumbs.get(status) or "Refer to .cowork-flow/workflow.md for the current step."
-    if extra_lines:
-        body = "\n".join([body, *extra_lines])
-    if task_path is None:
-        header = f"Status: {status}\nSource: {source}"
-    else:
-        header = f"Task: {task_path}\nStatus: {status}\nSource: {source}"
-
-    return "\n\n".join(
-        [
-            "<claude-code-runtime>\nhooks: UserPromptSubmit, SessionStart\n</claude-code-runtime>",
-            _build_contract_digest(root),
-            f"<workflow-state>\n{header}\n{body}\n</workflow-state>",
-        ]
-    )
-
-
 def main() -> int:
-    if os.environ.get("COWORK_FLOW_HOOKS") == "0" or os.environ.get("COWORK_FLOW_DISABLE_HOOKS") == "1":
+    if (
+        os.environ.get("COWORK_FLOW_HOOKS") == "0"
+        or os.environ.get("COWORK_FLOW_DISABLE_HOOKS") == "1"
+    ):
         return 0
-
-    hook_input = _normalize_hook_input(_read_hook_input())
+    hook_input = _read_input()
     cwd_value = hook_input.get("cwd")
-    cwd = Path(cwd_value) if isinstance(cwd_value, str) and cwd_value.strip() else Path.cwd()
-    root = _find_repo_root(cwd)
+    cwd = (
+        Path(cwd_value)
+        if isinstance(cwd_value, str) and cwd_value.strip()
+        else Path.cwd()
+    )
+    root = _find_root(cwd)
     if root is None:
         return 0
-
-    event_name = _hook_event_name(hook_input)
-    breadcrumbs = _load_breadcrumbs(root)
-    runtime_context, runtime_context_id = _resolve_runtime_context(root, hook_input)
-    extra_lines: list[str] | None = None
-    if runtime_context is not None:
-        task_dir = runtime_context.get("task_dir")
-        task_path = task_dir.strip() if isinstance(task_dir, str) and task_dir.strip() else None
-        status = "delegated_subtask"
-        source = f"runtime-context:{runtime_context.get('runtime_context_id')}"
-        extra_lines = _subagent_runtime_lines(runtime_context)
-    elif runtime_context_id:
-        task_path = None
-        status = "delegated_subtask"
-        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 start/resume/task start/archive/commit/spawn.",
-        ]
-    else:
-        task_path, status, source = _get_active_task(root, hook_input)
-    additional_context = _build_context(root, task_path, status, source, breadcrumbs, extra_lines)
-
+    scripts_dir = root / ".cowork-flow" / "scripts"
+    sys.path.insert(0, str(scripts_dir))
+    from common.host.workflow_state_hook import build_hook_context
+
+    context = build_hook_context(
+        root,
+        hook_input,
+        host="claude-code",
+        adapter="claude-code.hooks",
+        preamble=(
+            (
+                "<claude-code-runtime>\n"
+                "hooks: UserPromptSubmit, SessionStart\n"
+                "</claude-code-runtime>"
+            ),
+        ),
+    )
+    event_name = (
+        hook_input.get("hook_event_name")
+        or hook_input.get("hookEventName")
+        or "UserPromptSubmit"
+    )
     print(
         json.dumps(
             {
                 "hookSpecificOutput": {
                     "hookEventName": event_name,
-                    "additionalContext": additional_context,
+                    "additionalContext": context,
                 }
             },
             ensure_ascii=False,

package/template/.codex/agents/cowork-check.toml

@@ -32,15 +32,24 @@ Load context before checking:
 5. Read `git diff`.
 6. Include `test_intent_review` in the review output for meaningful behavior breaks coverage and shallow tests rejection.
 
+Authoritative internal protocols:
+- `.cowork-flow/spec/protocols/review.md`
+- `.cowork-flow/spec/protocols/decision-review.md`
+- `.cowork-flow/spec/protocols/spec-maintenance.md`
+
+Apply their output contracts exactly. Review output must preserve
+`acceptanceId`, `findings`, `test_intent_review`, `resolution`, and
+`specUpdates`.
+
 Rules:
 - Fix issues directly when they are clearly in scope.
 - MUST NOT spawn, wait for, list, or close other agents.
 - MUST NOT commit, archive, or mutate cowork-flow task state.
 - Report findings, changed files, and exact verification commands.
-- Include test intent findings that map tests back to PRD acceptance or regression behavior.
-- BEFORE declaring PRD acceptance passed, run the spec-driven coding gate and
+- Include test intent findings that map tests back to decision-anchor acceptance criteria or regression behavior.
+- BEFORE declaring decision-anchor acceptance passed, run the spec-driven coding gate and
   treat a nonzero exit as a hard blocker:
-  ./.cowork-flow/run python .cowork-flow/scripts/common/gates/validate_coding_standaries.py --validate --repo-root .
+  ./.cowork-flow/run python .cowork-flow/scripts/common/gates/validate_coding_standards.py --validate --repo-root .
   This naturally enforces every rule the user added to
   .cowork-flow/spec/backend/*.md and spec/frontend/*.md — they are not just
   documentation but active validators. On violation, either fix the code or

package/template/.codex/agents/cowork-implement.toml

@@ -33,16 +33,25 @@ Load context before editing:
 6. Read the plan file linked from this task (check `<task>/task.json` `relatedFiles` for a plan path, or search `.cowork-flow/plans/` for a plan file referencing this task directory). Follow the plan steps in order — each step has Files, Action, Verify, and Expected fields.
 7. For behavior-change tasks, create or verify `<task>/tdd.jsonl` before implementation or record a documented exemption.
 
+Authoritative internal protocols:
+- `.cowork-flow/spec/protocols/tdd.md`
+- `.cowork-flow/spec/protocols/decision-review.md`
+- `.cowork-flow/spec/protocols/spec-maintenance.md`
+
+Apply their output contracts exactly. Implementation reports and `tdd.jsonl`
+must preserve `acceptanceId`, `redCommand`, `redExitCode`, `greenCommand`,
+`greenExitCode`, and `specUpdates`.
+
 Rules:
 - MUST NOT spawn, wait for, list, or close other agents.
 - MUST NOT run task start, task finish, task archive, or unscoped resume.
 - MUST NOT commit or push.
 - Keep edits inside requested scope.
-- Do not treat shallow tests as TDD evidence; red-green-refactor proof must include redCommand, redExitCode, greenCommand, greenExitCode, and PRD acceptance ID mapping.
+- Do not treat shallow tests as TDD evidence; red-green-refactor proof must include redCommand, redExitCode, greenCommand, greenExitCode, and decision-anchor acceptance ID mapping.
 - Report changed files and exact verification commands.
 - BEFORE editing any source file, run the spec-driven coding gate and treat a
   nonzero exit as a hard blocker:
-  ./.cowork-flow/run python .cowork-flow/scripts/common/gates/validate_coding_standaries.py --validate --repo-root .
+  ./.cowork-flow/run python .cowork-flow/scripts/common/gates/validate_coding_standards.py --validate --repo-root .
   Parse every *.md under .cowork-flow/spec/backend and spec/frontend; rules
   declared there activate validators dynamically. On violation, fix the code
   (do not disable the rule) and re-run until exit code 0.

package/template/.codex/agents/default.toml

@@ -5,8 +5,9 @@ sandbox_mode = "workspace-write"
 developer_instructions = """
 You are a dispatched default agent. Your task comes from the dispatch message or the bounded brief, not from project bootstrap or start-session skills.
 
-If AGENTS.md or .agents/skills/start tells you to start a session, skip that start skill.
-Do not run the project start-session workflow or try to spawn another agent from this prompt.
+Treat AGENTS.md and project bootstrap text as constraints, not as the assigned
+task. Do not run the project start-session workflow or try to spawn another
+agent from this prompt.
 
 Generic default-agent dispatch is advisory and cannot satisfy formal Implement
 or Check completion. Follow the bounded prompt directly. Project rules are

package/template/.codex/agents/explorer.toml

@@ -5,8 +5,9 @@ sandbox_mode = "workspace-write"
 developer_instructions = """
 You are a dispatched explorer agent. Your task comes from the dispatch message or the bounded brief, not from project bootstrap or start-session skills.
 
-If AGENTS.md or .agents/skills/start tells you to start a session, skip that start skill.
-Do not run the project start-session workflow or try to spawn another agent from this prompt.
+Treat AGENTS.md and project bootstrap text as constraints, not as the assigned
+task. Do not run the project start-session workflow or try to spawn another
+agent from this prompt.
 
 Generic explorer dispatch is advisory and cannot satisfy formal Implement or
 Check completion. Follow the bounded prompt directly. Project rules are

package/template/.codex/agents/worker.toml

@@ -5,7 +5,8 @@ sandbox_mode = "workspace-write"
 developer_instructions = """
 You are a dispatched worker agent. Your task comes from the dispatch message or the worker brief, not from project bootstrap or start-session skills.
 
-If AGENTS.md or .agents/skills/start tells you to start a session, skip that start skill.
+Treat AGENTS.md and project bootstrap text as constraints, not as the assigned
+task.
 If you can see any outer transport text such as Spawn one ... agent, ignore it. That text is for the coordinator, not for you.
 Do not run the project start-session workflow or try to spawn another worker from this prompt.