cowork-flow 0.0.26 → 0.0.28

package/template/.claude/skills/writing-plans/SKILL.md

@@ -42,6 +42,7 @@ Start with:
 - Include a failing test before implementation when behavior can be tested.
 - Do not add shallow tests just to satisfy process. Avoid tests that only assert existence, mirror implementation details, count mocks without behavior, or snapshot empty structure.
 - For complex problems, test depth first: cover invariants, cross-layer contracts, state transitions, error boundaries, and real regression paths before narrow unit cases.
+- Map each behavior-changing test to a stable PRD acceptance ID and note where `tdd.jsonl` will record the red-green evidence.
 - Avoid placeholders such as TODO, TBD, "handle edge cases", or "write tests".
 - Keep root/template parity explicit when both copies exist.
 

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

@@ -29,12 +29,14 @@ Load context before checking:
 2. Read `<task>/prd.md`.
 3. Read `<task>/check.jsonl`.
 4. Read `git diff`.
+5. Include `test_intent_review` in the review output for meaningful behavior breaks coverage and shallow tests rejection.
 
 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.
 """
 
 [features]

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

@@ -30,12 +30,14 @@ Load context before editing:
 3. Read `<task>/info.md` if present.
 4. Read `<task>/implement.jsonl`.
 5. Read each JSONL `file` entry.
+6. For behavior-change tasks, create or verify `<task>/tdd.jsonl` before implementation or record a documented exemption.
 
 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.
 - Report changed files and exact verification commands.
 """
 

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

@@ -20,7 +20,7 @@ DEFAULT_CONTRACT_REGISTRY = {
     "contracts": [
         {
             "id": "COWORK_ENTRY_CONTRACT_V1",
-            "path": ".cowork-flow/spec/entry-contract.md",
+            "path": ".cowork-flow/spec/contracts/entry-contract.md",
             "digest": [
                 "Classify main-session requests before task start, resume, archive, or commit.",
                 "Runtime context, not prompt labels, identifies formal subagent sessions.",
@@ -29,7 +29,7 @@ DEFAULT_CONTRACT_REGISTRY = {
         },
         {
             "id": "RUNTIME_CONTEXT_DISPATCH_V2",
-            "path": ".cowork-flow/spec/subagent-dispatch.md",
+            "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.",
@@ -72,7 +72,7 @@ def _read_hook_input() -> dict[str, Any]:
 
 
 def _load_breadcrumbs(root: Path) -> dict[str, str]:
-    workflow = root / ".cowork-flow" / "spec" / "workflow-state-templates.md"
+    workflow = root / ".cowork-flow" / "spec" / "contracts" / "workflow-state-templates.md"
     try:
         text = workflow.read_text(encoding="utf-8")
     except OSError:
@@ -86,16 +86,23 @@ def _as_string_list(value: Any) -> list[str]:
     return [item for item in value if isinstance(item, str) and item.strip()]
 
 
-def _load_contract_registry(root: Path) -> list[dict[str, Any]]:
-    registry_file = root / ".cowork-flow" / "spec" / "registry.json"
+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, json.JSONDecodeError):
+    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"]
-    return [contract for contract in contracts if isinstance(contract, dict)]
+        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:
@@ -113,13 +120,15 @@ def _contract_fingerprint(root: Path, contracts: list[dict[str, Any]]) -> str:
 
 
 def _build_contract_digest(root: Path) -> str:
-    contracts = _load_contract_registry(root)
+    contracts, warning = _load_contract_registry(root)
     fingerprint = _contract_fingerprint(root, contracts)
     lines = [
         '<cowork-runtime host="codex" adapter="codex.spawn_agent">',
         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")

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.26
+0.0.28

package/template/.cowork-flow/config.yaml

@@ -28,6 +28,22 @@ codex:
   # .cowork-flow/.runtime/subagents/<id>.json with the subagent helper, then
   # passes cowork_runtime_context_id through the active host adapter transport.
 
+#-------------------------------------------------------------------------------
+# Party Mode V2 Runtime Board
+#-------------------------------------------------------------------------------
+
+# Party Mode V2 is an advisory, runtime-controlled board discussion mode.
+# The Python runtime owns board state and emits host-neutral next actions; the
+# active host adapter still performs dispatch/wait/close.
+party_mode_v2:
+  min_agents: 3
+  max_agents: 5
+  max_rounds: 5
+  max_rebuttal_targets_per_agent: 2
+  max_drift_warnings: 2
+  fresh_context_per_round: "true"
+  require_current_round_only: "true"
+
 #-------------------------------------------------------------------------------
 # Task Lifecycle Hooks
 #-------------------------------------------------------------------------------

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

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python3
 """Small resumable directory archive helpers."""
 
 from __future__ import annotations

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

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""Coding standards validators for changed files."""
+
+from __future__ import annotations
+
+import ast
+import re
+from pathlib import Path
+from typing import Iterable, Sequence
+
+from .git_snapshot import ChangedFile
+
+TEXT_IO_SUFFIXES = {".py", ".ps1", ".js", ".mjs", ".cjs", ".ts", ".tsx"}
+EXEMPT_PATH_PREFIXES = (
+    "tests/fixtures/coding-standards/",
+    "test/fixtures/coding-standards/",
+)
+
+NODE_TEXT_IO_PATTERN = re.compile(
+    r"\b(readFile|readFileSync|writeFile|writeFileSync)\s*\(",
+)
+POWERSHELL_TEXT_IO_PATTERN = re.compile(
+    r"\b(Get-Content|Set-Content|Out-File)\b",
+    re.IGNORECASE,
+)
+
+
+def validate_changed_files(
+    repo_root: Path,
+    changed_files: Sequence[ChangedFile],
+) -> list[dict]:
+    """Validate coding standards for changed files."""
+    violations: list[dict] = []
+    for changed_file in changed_files:
+        rel_path = changed_file.path
+        if _is_exempt_path(rel_path):
+            continue
+
+        file_path = Path(repo_root) / rel_path
+        if not file_path.is_file() or file_path.suffix.lower() not in TEXT_IO_SUFFIXES:
+            continue
+
+        try:
+            content = file_path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            violations.append(
+                _violation(
+                    "CS-UTF8-READ-001",
+                    rel_path,
+                    "Coding standards: changed text file must be valid UTF-8",
+                    "Rewrite the file as UTF-8 without relying on the system default encoding.",
+                )
+            )
+            continue
+        except OSError:
+            continue
+
+        suffix = file_path.suffix.lower()
+        if suffix == ".py":
+            violations.extend(_validate_python_text_io(rel_path, content))
+        elif suffix == ".ps1":
+            violations.extend(_validate_powershell_text_io(rel_path, content))
+        elif suffix in {".js", ".mjs", ".cjs", ".ts", ".tsx"}:
+            violations.extend(_validate_node_text_io(rel_path, content))
+
+    return violations
+
+
+def _validate_python_text_io(rel_path: str, content: str) -> list[dict]:
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    violations: list[dict] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+
+        function_name = _call_name(node)
+        if function_name in {"open", "read_text", "write_text"}:
+            if _is_binary_python_call(node, function_name):
+                continue
+            if not _has_utf8_encoding(node):
+                violations.append(
+                    _violation(
+                        "CS-UTF8-PY-001",
+                        rel_path,
+                        "Coding standards: Python text IO must pass encoding=\"utf-8\"",
+                        "Add encoding=\"utf-8\" to open(), Path.open(), read_text(), or write_text().",
+                        line=getattr(node, "lineno", None),
+                    )
+                )
+
+    return violations
+
+
+def _validate_node_text_io(rel_path: str, content: str) -> list[dict]:
+    violations: list[dict] = []
+    lines = content.splitlines()
+    for index, line in enumerate(lines):
+        if not NODE_TEXT_IO_PATTERN.search(line):
+            continue
+
+        segment = "\n".join(lines[index : min(index + 5, len(lines))]).lower()
+        if "utf8" in segment or "utf-8" in segment:
+            continue
+
+        violations.append(
+            _violation(
+                "CS-UTF8-NODE-001",
+                rel_path,
+                "Coding standards: Node file IO must specify utf8 encoding",
+                "Pass 'utf8' or { encoding: 'utf8' } to readFile/writeFile calls.",
+                line=index + 1,
+            )
+        )
+
+    return violations
+
+
+def _validate_powershell_text_io(rel_path: str, content: str) -> list[dict]:
+    violations: list[dict] = []
+    for line_number, raw_line in enumerate(content.splitlines(), start=1):
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if POWERSHELL_TEXT_IO_PATTERN.search(line) and "-encoding" not in line.lower():
+            violations.append(
+                _violation(
+                    "CS-UTF8-PS-001",
+                    rel_path,
+                    "Coding standards: PowerShell text IO must specify -Encoding UTF8",
+                    "Add -Encoding UTF8 to Get-Content, Set-Content, or Out-File.",
+                    line=line_number,
+                )
+            )
+
+    return violations
+
+
+def _call_name(node: ast.Call) -> str:
+    function = node.func
+    if isinstance(function, ast.Name):
+        return function.id
+    if isinstance(function, ast.Attribute):
+        return function.attr
+    return ""
+
+
+def _is_binary_python_call(node: ast.Call, function_name: str) -> bool:
+    mode_values: list[str] = []
+    for keyword in node.keywords:
+        if keyword.arg == "mode":
+            mode_values.extend(_literal_strings([keyword.value]))
+
+    positional_mode_index = 1 if function_name == "open" else 0
+    if len(node.args) > positional_mode_index:
+        mode_values.extend(_literal_strings([node.args[positional_mode_index]]))
+
+    return any("b" in value for value in mode_values)
+
+
+def _has_utf8_encoding(node: ast.Call) -> bool:
+    for keyword in node.keywords:
+        if keyword.arg != "encoding":
+            continue
+        values = _literal_strings([keyword.value])
+        return bool(values) and all(_is_utf8(value) for value in values)
+    return False
+
+
+def _literal_strings(nodes: Iterable[ast.AST]) -> list[str]:
+    values: list[str] = []
+    for node in nodes:
+        if isinstance(node, ast.Constant) and isinstance(node.value, str):
+            values.append(node.value.lower())
+    return values
+
+
+def _is_utf8(value: str) -> bool:
+    return value.replace("_", "-").lower() in {"utf-8", "utf8"}
+
+
+def _is_exempt_path(rel_path: str) -> bool:
+    normalized = rel_path.replace("\\", "/")
+    return any(normalized.startswith(prefix) for prefix in EXEMPT_PATH_PREFIXES)
+
+
+def _violation(
+    rule_id: str,
+    file_path: str,
+    message: str,
+    fix_hint: str,
+    *,
+    line: int | None = None,
+) -> dict:
+    violation = {
+        "rule_id": rule_id,
+        "type": "coding_standard",
+        "severity": "block",
+        "passed": False,
+        "message": message,
+        "file": file_path,
+        "fix_hint": fix_hint,
+    }
+    if line is not None:
+        violation["line"] = line
+    return violation

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

@@ -16,6 +16,13 @@ from .paths import DIR_WORKFLOW, get_repo_root
 DEFAULT_SESSION_COMMIT_MESSAGE = "chore: record journal"
 DEFAULT_MAX_JOURNAL_LINES = 2000
 DEFAULT_CODEX_DISPATCH_MODE = "sub-agent"
+DEFAULT_PARTY_MODE_V2_MIN_AGENTS = 3
+DEFAULT_PARTY_MODE_V2_MAX_AGENTS = 5
+DEFAULT_PARTY_MODE_V2_MAX_ROUNDS = 5
+DEFAULT_PARTY_MODE_V2_MAX_REBUTTAL_TARGETS_PER_AGENT = 2
+DEFAULT_PARTY_MODE_V2_MAX_DRIFT_WARNINGS = 2
+DEFAULT_PARTY_MODE_V2_FRESH_CONTEXT_PER_ROUND = True
+DEFAULT_PARTY_MODE_V2_REQUIRE_CURRENT_ROUND_ONLY = True
 
 CONFIG_FILE = "config.yaml"
 
@@ -139,3 +146,89 @@ def get_codex_dispatch_mode(repo_root: Path | None = None) -> str:
     if mode in {"sub-agent", "inline"}:
         return str(mode)
     return DEFAULT_CODEX_DISPATCH_MODE
+
+def _get_section(config: dict, section_name: str) -> dict:
+    section = config.get(section_name)
+    if isinstance(section, dict):
+        return section
+    return {}
+
+def _get_int(section: dict, key: str, default: int, *, minimum: int | None = None) -> int:
+    value = section.get(key, default)
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return default
+    if minimum is not None and parsed < minimum:
+        return default
+    return parsed
+
+def _get_bool(section: dict, key: str, default: bool) -> bool:
+    value = section.get(key, default)
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"true", "1", "yes", "on"}:
+            return True
+        if normalized in {"false", "0", "no", "off"}:
+            return False
+    return default
+
+def get_party_mode_v2_config(repo_root: Path | None = None) -> dict[str, int | bool]:
+    """Get Party Mode V2 runtime-board defaults."""
+    config = _load_config(repo_root)
+    section = _get_section(config, "party_mode_v2")
+    min_agents = _get_int(
+        section,
+        "min_agents",
+        DEFAULT_PARTY_MODE_V2_MIN_AGENTS,
+        minimum=3,
+    )
+    max_agents = _get_int(
+        section,
+        "max_agents",
+        DEFAULT_PARTY_MODE_V2_MAX_AGENTS,
+        minimum=min_agents,
+    )
+    return {
+        "min_agents": min_agents,
+        "max_agents": max_agents,
+        "max_rounds": _get_int(
+            section,
+            "max_rounds",
+            DEFAULT_PARTY_MODE_V2_MAX_ROUNDS,
+            minimum=1,
+        ),
+        "max_rebuttal_targets_per_agent": _get_int(
+            section,
+            "max_rebuttal_targets_per_agent",
+            DEFAULT_PARTY_MODE_V2_MAX_REBUTTAL_TARGETS_PER_AGENT,
+            minimum=1,
+        ),
+        "max_drift_warnings": _get_int(
+            section,
+            "max_drift_warnings",
+            DEFAULT_PARTY_MODE_V2_MAX_DRIFT_WARNINGS,
+            minimum=0,
+        ),
+        "fresh_context_per_round": _get_bool(
+            section,
+            "fresh_context_per_round",
+            DEFAULT_PARTY_MODE_V2_FRESH_CONTEXT_PER_ROUND,
+        ),
+        "require_current_round_only": _get_bool(
+            section,
+            "require_current_round_only",
+            DEFAULT_PARTY_MODE_V2_REQUIRE_CURRENT_ROUND_ONLY,
+        ),
+    }
+
+def get_party_mode_v2_min_agents(repo_root: Path | None = None) -> int:
+    return int(get_party_mode_v2_config(repo_root)["min_agents"])
+
+def get_party_mode_v2_max_agents(repo_root: Path | None = None) -> int:
+    return int(get_party_mode_v2_config(repo_root)["max_agents"])
+
+def get_party_mode_v2_max_rounds(repo_root: Path | None = None) -> int:
+    return int(get_party_mode_v2_config(repo_root)["max_rounds"])

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

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Shared gate result helpers for cowork-flow lifecycle commands."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class GateResult:
+    """Normalized result returned by workflow gates."""
+
+    scope: str
+    task_dir: Path | None = None
+    violations: list[dict] = field(default_factory=list)
+
+    @classmethod
+    def from_violations(
+        cls,
+        scope: str,
+        violations: list[dict],
+        task_dir: Path | None = None,
+    ) -> "GateResult":
+        return cls(scope=scope, task_dir=task_dir, violations=list(violations))
+
+    @property
+    def blockers(self) -> list[dict]:
+        return [
+            violation
+            for violation in self.violations
+            if violation.get("severity") == "block"
+        ]
+
+    @property
+    def blocked(self) -> bool:
+        return bool(self.blockers)
+
+    @property
+    def exit_code(self) -> int:
+        return 1 if self.blocked else 0
+
+
+class GateRunner:
+    """Run existing validators through a common gate interface."""
+
+    def __init__(self, repo_root: Path) -> None:
+        self.repo_root = Path(repo_root)
+
+    def run(self, scope: str, task_dir: Path | None = None) -> GateResult:
+        from .validate_rules import validate_rules
+
+        normalized_task_dir = Path(task_dir) if task_dir is not None else None
+        violations = validate_rules(self.repo_root, scope, normalized_task_dir)
+        if scope in {"task_review", "task_complete"}:
+            from .validate_coding_standards import validate_coding_standards
+
+            violations.extend(
+                validate_coding_standards(self.repo_root, normalized_task_dir)
+            )
+        return GateResult.from_violations(scope, violations, normalized_task_dir)
+
+    def log(self, result: GateResult) -> None:
+        from .validate_rules import log_violations
+
+        log_violations(result.violations, result.scope, result.task_dir, self.repo_root)

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

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Git changed-file snapshot helpers for workflow gates."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .git_context import _run_git_command
+
+
+@dataclass(frozen=True)
+class ChangedFile:
+    """A file currently changed in git status."""
+
+    path: str
+    statuses: tuple[str, ...]
+
+
+def collect_changed_files(repo_root: Path) -> list[ChangedFile]:
+    """Return modified, staged, and untracked files from git status."""
+    rc, stdout, _ = _run_git_command(
+        ["status", "--porcelain=v1", "-uall", "--", "."],
+        cwd=repo_root,
+    )
+    if rc != 0:
+        return []
+
+    changed: dict[str, set[str]] = {}
+    for raw_line in stdout.splitlines():
+        parsed = _parse_status_line(raw_line)
+        if parsed is None:
+            continue
+        path, statuses = parsed
+        changed.setdefault(path, set()).update(statuses)
+
+    return [
+        ChangedFile(path=path, statuses=tuple(sorted(statuses)))
+        for path, statuses in sorted(changed.items())
+    ]
+
+
+def collect_changed_paths(repo_root: Path) -> list[str]:
+    """Return only the relative paths from collect_changed_files."""
+    return [changed.path for changed in collect_changed_files(repo_root)]
+
+
+def _parse_status_line(raw_line: str) -> tuple[str, tuple[str, ...]] | None:
+    if len(raw_line) < 4:
+        return None
+
+    code = raw_line[:2]
+    raw_path = raw_line[3:]
+    if " -> " in raw_path:
+        raw_path = raw_path.split(" -> ", 1)[1]
+
+    path = _normalize_git_path(raw_path)
+    if not path:
+        return None
+
+    statuses: list[str] = []
+    index_status = code[0]
+    worktree_status = code[1]
+
+    if code == "??":
+        statuses.append("untracked")
+    else:
+        if index_status not in (" ", "?"):
+            statuses.append("staged")
+        if worktree_status not in (" ", "?"):
+            statuses.append("modified")
+
+    if not statuses:
+        return None
+
+    return path, tuple(statuses)
+
+
+def _normalize_git_path(raw_path: str) -> str:
+    path = raw_path.strip()
+    if len(path) >= 2 and path[0] == path[-1] == '"':
+        path = path[1:-1]
+    return path.replace("\\", "/")

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

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""Task lifecycle state transition rules."""
+
+from __future__ import annotations
+
+CHECK_STATUSES = ("review", "checking")
+DONE_STATUSES = ("completed", "done")
+
+ALLOWED_TRANSITIONS = {
+    ("planning", "in_progress"),
+    ("in_progress", "review"),
+    ("review", "completed"),
+    ("checking", "completed"),
+}
+
+
+def _normalize_status(status: str | None) -> str:
+    if isinstance(status, str) and status.strip():
+        return status.strip()
+    return "unknown"
+
+
+def transition_blockers(current_status: str | None, target_status: str) -> list[str]:
+    """Return blockers for a task status transition."""
+    current = _normalize_status(current_status)
+    target = _normalize_status(target_status)
+
+    if current == target:
+        return []
+
+    if (current, target) in ALLOWED_TRANSITIONS:
+        return []
+
+    if target == "completed":
+        return [
+            f"Task cannot be completed from status '{current}'. "
+            "Run `task review` first to enter check phase."
+        ]
+
+    if target == "review":
+        return [
+            f"Task cannot enter review from status '{current}'. "
+            "Run `task start` and finish implementation first."
+        ]
+
+    if target == "in_progress" and current in (*CHECK_STATUSES, *DONE_STATUSES):
+        return [
+            f"Task cannot return to in_progress from status '{current}'. "
+            "Create a follow-up task instead of reopening checked work."
+        ]
+
+    return [f"Task transition is not allowed: {current} -> {target}."]
+
+
+def transition_allowed(current_status: str | None, target_status: str) -> bool:
+    """Return whether a task status transition is allowed."""
+    return not transition_blockers(current_status, target_status)