cowork-flow 0.0.27 → 0.0.28

package/README.md

@@ -1,4 +1,4 @@
-# cowork-flow
+# cowork-flow
 
 cowork-flow 是一个用于新项目初始化协作流程的模板仓库。它把项目说明、任务流转、规格治理、开发计划和会话记录放在一套可复制的目录结构里，帮助团队在项目早期就建立清晰的工作闭环。
 
@@ -43,6 +43,12 @@ cowork-flow 是一个用于新项目初始化协作流程的模板仓库。它
         ├── workflow.md
         ├── scripts/
         ├── spec/
+        │   ├── contracts/
+        │   ├── runtime/
+        │   ├── schemas/
+        │   ├── backend/
+        │   ├── frontend/
+        │   └── guides/
         ├── changes/
         ├── plans/
         ├── tasks/
@@ -65,19 +71,19 @@ cowork-flow 是一个用于新项目初始化协作流程的模板仓库。它
 固定角色 agent 定义，包含 `cowork-research`、`cowork-implement` 和 `cowork-check`，以及对 Codex 默认 `worker`、`default`、`explorer` 的项目级防漂移约束。主会话负责计划与收口，并通过 host adapter 派发固定 agent；正式派发必须先创建 runtime context，再把 `cowork_runtime_context_id` 和 `cowork_host_context_key` 传给子代理。
 
 `template/.codex/config.toml`、`template/.codex/hooks.json`、`template/.codex/hooks/`
-Codex 项目级配置与每轮上下文注入入口。hook 会先用共享 entry classifier 判定当前输入，再读取当前 session task、`.cowork-flow/spec/workflow-state-templates.md` 中的 `workflow-state` 片段和 `codex.dispatch_mode`，把流程状态注入到当前轮对话。注入的 `codex-dispatch-mode` 只是主会话调度提示，不代表当前线程身份。
+Codex 项目级配置与每轮上下文注入入口。hook 会先解析 runtime context，再读取当前 session task、`.cowork-flow/spec/contracts/workflow-state-templates.md` 中的 `workflow-state` 片段和 `codex.dispatch_mode`，把流程状态注入到当前轮对话。注入的 `codex-dispatch-mode` 只是主会话调度提示，不代表当前线程身份。
 
 `template/CLAUDE.md`、`template/.claude/settings.json`、`template/.claude/agents/`、`template/.claude/skills/`、`template/.claude/commands/`、`template/.claude/hooks/`
 Claude Code 项目级记忆、hook、固定 agent、skills 和 slash command。`CLAUDE.md` 显式导入 `AGENTS.md`。`.claude/settings.json` 注册 `UserPromptSubmit` 和 `SessionStart` hook，注入当前 workflow state 与 contract digest。固定 agent 通过 `.cowork-flow/run subagent init` 生成 runtime context，并在 prompt、env 或 metadata transport 中传递 `cowork_runtime_context_id`；hook 绑定成功后才进入叶子执行，绑定失败则 fail closed，避免被项目 bootstrap 或无任务首屏上下文拉偏。Claude Code 不自动加载 `.agents/skills/`，所以项目技能要放进 `.claude/skills/`。
 
 `template/.opencode/agents/`、`template/.opencode/commands/`、`template/.opencode/plugins/`
-OpenCode 项目级固定 agent、slash command 和系统上下文注入插件。插件会读取 `.cowork-flow/spec/registry.json`，注入短 contract digest。
+OpenCode 项目级固定 agent、slash command 和系统上下文注入插件。插件会读取 `.cowork-flow/spec/runtime/contract-registry.json`，注入短 contract digest。
 
 `template/.cowork-flow/`
 工作流目录，包含流程说明、任务状态、开发者工作区、项目规范、行为变更规格、实现计划和辅助脚本。`.cowork-flow/config.yaml` 只承载真实接线的 session/journal, Codex hint, and task lifecycle hook settings。
 
 `template/.cowork-flow/spec/`
-项目规范目录，预置了 backend、frontend 和 guides 三类说明。接入时应按项目事实保留、改写或删除对应规范。
+项目规范目录。`contracts/` 存人读 workflow/host/agent 合同，`runtime/` 存运行时读取的规则和 contract registry，`schemas/` 存 JSON Schema，`backend/`、`frontend/`、`guides/` 存工程规范和思考指引。接入时应按项目事实保留、改写或删除对应规范。
 
 `template/.cowork-flow/changes/`
 由 `change.py` 管理 proposal、design、behavior specs 和归档，不维护实现 checklist。
@@ -163,7 +169,7 @@ cowork-flow sync .
 cowork-flow sync . --dry-run
 ```
 
-`sync` 会自动识别目标项目已安装的 host 目录：只有 `.codex/` 时只同步 Codex 资产，只有 `.opencode/` 时只同步 OpenCode 资产，两者都有时同步两者；对应 `.cowork-flow/adapters/<host>/` 也按识别出的平台同步。检测到 Codex 或 OpenCode 时会刷新 `.agents/skills/`；Claude Code-only 项目只刷新 `.claude/settings.json`、`.claude/hooks/`、`.claude/skills/`，不会创建 `.agents/skills/`。通用部分默认刷新 `.cowork-flow/scripts/`、`.cowork-flow/spec/workflow-state-templates.md`，以及 `AGENTS.md` 和 `CLAUDE.md` 中的 `<!-- COWORK-FLOW:START --> ... <!-- COWORK-FLOW:END -->` 托管块，保留托管块之外的项目自定义内容。`.cowork-flow/config.yaml`、`.cowork-flow/workflow.md`、除 `workflow-state-templates.md` 外的 `.cowork-flow/spec/`、任务、计划、变更和 workspace 记录默认受保护。只有明确传入 `--force` 时才整文件覆盖保护文件。
+`sync` 会自动识别目标项目已安装的 host 目录：只有 `.codex/` 时只同步 Codex 资产，只有 `.opencode/` 时只同步 OpenCode 资产，两者都有时同步两者；对应 `.cowork-flow/adapters/<host>/` 也按识别出的平台同步。检测到 Codex 或 OpenCode 时会刷新 `.agents/skills/`；Claude Code-only 项目只刷新 `.claude/settings.json`、`.claude/hooks/`、`.claude/skills/`，不会创建 `.agents/skills/`。通用部分默认刷新 `.cowork-flow/scripts/`、`.cowork-flow/spec/contracts/workflow-state-templates.md`，以及 `AGENTS.md` 和 `CLAUDE.md` 中的 `<!-- COWORK-FLOW:START --> ... <!-- COWORK-FLOW:END -->` 托管块，保留托管块之外的项目自定义内容。`.cowork-flow/config.yaml`、`.cowork-flow/workflow.md`、除 `workflow-state-templates.md` 外的 `.cowork-flow/spec/`、任务、计划、变更和 workspace 记录默认受保护。只有明确传入 `--force` 时才整文件覆盖保护文件。
 
 ## 常用入口
 
@@ -249,7 +255,7 @@ cowork_host_context_key: <host_context_key>
 
 子代理首步执行 `./.cowork-flow/run subagent bind <runtime_context_id> <host_context_key>`；主会话验收前必须确认 runtime context 中 `status=bound` 且 `bound_context_key` 匹配。默认角色为 `cowork-research`、`cowork-implement`、`cowork-check`，任务上下文来自已绑定 runtime context，而不是 prompt 形状。
 
-Codex hook 启用后，每轮会自动注入 `<workflow-state>`，其中包含入口分类、当前任务、状态来源和下一步流程提示。状态文本来自 `.cowork-flow/spec/workflow-state-templates.md`；`workflow.md` 只描述流程，不内联状态片段。hook 不替代主会话验收；它只负责把 task 状态和 workflow gate 放进上下文。
+Codex hook 启用后，每轮会自动注入 `<workflow-state>`，其中包含入口分类、当前任务、状态来源和下一步流程提示。状态文本来自 `.cowork-flow/spec/contracts/workflow-state-templates.md`；`workflow.md` 只描述流程，不内联状态片段。hook 不替代主会话验收；它只负责把 task 状态和 workflow gate 放进上下文。
 
 记录 session：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.27",
+  "version": "0.0.28",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {

package/src/lib/copy-template.js

@@ -1,4 +1,4 @@
-import { constants } from 'node:fs';
+import { constants } from 'node:fs';
 import { access, chmod, copyFile, mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import { dirname, join, relative } from 'node:path';
 
@@ -96,7 +96,7 @@ const SAFE_SYNC_FILES = new Set([
   '.cowork-flow/.version',
   '.cowork-flow/run',
   '.cowork-flow/run.cmd',
-  '.cowork-flow/spec/workflow-state-templates.md'
+  '.cowork-flow/spec/contracts/workflow-state-templates.md'
 ]);
 
 const COWORK_FLOW_START = '<!-- COWORK-FLOW:START -->';

package/template/.agents/skills/before-dev/SKILL.md

@@ -15,6 +15,7 @@ Use this immediately before code edits.
 4. Active task `implement.jsonl`
 5. Relevant `.cowork-flow/spec/*/index.md`
 6. Any exact files named by the task, plan, or user
+7. If the task changes behavior, locate or create `tdd.jsonl` evidence before implementation.
 
 Do not bulk-load unrelated tasks, archived sessions, or every spec file.
 

package/template/.agents/skills/check/SKILL.md

@@ -16,6 +16,7 @@ Use this after implementation and before `finish-work`.
 5. Review test intent: reject shallow tests that do not fail for meaningful behavior breaks.
 6. Run focused tests that would fail if the changed behavior broke.
 7. Run broader validation when the change touches shared runtime, templates, packaging, or public workflow.
+8. Report `test_intent_review` with the key tests that defend PRD acceptance behavior.
 
 ## Report
 

package/template/.agents/skills/party-mode-v2/SKILL.md

@@ -26,6 +26,7 @@ Always use the runtime controller:
 .cowork-flow/run party-v2 post
 .cowork-flow/run party-v2 respond
 .cowork-flow/run party-v2 advance
+.cowork-flow/run party-v2 record-action-result
 .cowork-flow/run party-v2 finalize
 ```
 
@@ -38,6 +39,7 @@ Do not bypass a runtime rejection by manually accepting child output. Runtime va
 - Historical board state is runtime-private and may be used only for audit or final reports.
 - Use at least three child agents unless the effective runtime config explicitly allows a different value.
 - The runtime emits host-neutral next actions. The active Host Adapter or moderator executes them for Codex, Claude Code, or OpenCode.
+- Host action results must be recorded back through `record-action-result` so `agents.json`, audit logs, and action history can prove lifecycle state.
 
 ## Child Response Rules
 

package/template/.agents/skills/tdd/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: tdd
+description: Use when implementing behavior changes, bug fixes, state transitions, protocols, CLI/runtime contracts, data format changes, or error handling that can be tested before implementation.
+---
+
+# TDD
+
+Use this before editing behavior-changing code.
+
+## Red-Green-Refactor
+
+1. Map the task PRD acceptance criteria to stable IDs such as `AC-001`.
+2. Write the smallest meaningful failing test first.
+3. Run the red command and confirm it fails because the target behavior is missing or wrong.
+4. Implement the smallest change that makes the behavior pass.
+5. Run the green command and relevant broader verification.
+6. Refactor only after the behavior is green.
+
+Do not count shallow tests as TDD evidence. Tests that only import code, assert a function exists, assert `True`, count mocks without behavior, or mirror implementation details do not satisfy red-green-refactor.
+
+## Evidence
+
+Record TDD proof in `<task>/tdd.jsonl`. Each evidence line is one JSON object:
+
+```json
+{
+  "acceptanceId": "AC-001",
+  "testFile": "tests/test_example.py",
+  "testName": "test_behavior",
+  "redCommand": "python -m unittest tests.test_example.TestCase.test_behavior -v",
+  "redExitCode": 1,
+  "redOutputExcerpt": "expected failure excerpt",
+  "failureReason": "target behavior was not implemented",
+  "whyThisTestMatters": "explains which user-visible behavior would regress",
+  "greenCommand": "python -m unittest tests.test_example.TestCase.test_behavior -v",
+  "greenExitCode": 0,
+  "broaderVerification": "python -m unittest tests.test_example -v"
+}
+```
+
+Every evidence record must map to a PRD `acceptanceId`. The red failure must be about the target behavior, not syntax, import, environment, fixture, or setup failure.
+
+`testName` must resolve to the exact behavior test in `testFile`. Use one of:
+`test_method`, `ClassName.test_method`, or `module.ClassName.test_method`.
+Do not point evidence at a class, module, or a name that only exists in a command string.
+
+## Exemption
+
+Pure documentation, comment-only, or formatting-only tasks may use an exemption record instead of red/green evidence:
+
+```json
+{
+  "type": "exemption",
+  "acceptanceId": "AC-001",
+  "exemptionType": "docs-only",
+  "reason": "Only documentation wording changed; runtime behavior is untouched.",
+  "verificationCommand": "git diff --check"
+}
+```
+
+Do not use an exemption for runtime, CLI, protocol, state, data format, permission, or error-handling changes.

package/template/.agents/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/.claude/agents/cowork-implement.md

@@ -1,16 +1,10 @@
 ---
 name: cowork-implement
 description: Cowork-flow implementation fixed subagent.
-mode: subagent
-permission:
-  edit: ask
-  bash: ask
-  task: deny
-  todowrite: deny
-  external_directory: deny
+tools: Read, Write, Edit, MultiEdit, Grep, Glob, LS, Bash
 ---
 
-You are the `cowork-implement` fixed subagent for OpenCode.
+You are the `cowork-implement` fixed subagent for Claude Code.
 You are a leaf executor and must not invoke other agents.
 
 Formal `cowork-implement` work requires a bound runtime context. The prompt,
@@ -21,7 +15,7 @@ cowork_runtime_context_id: <runtime_context_id>
 cowork_host_context_key: <host_context_key>
 ```
 
-The plugin may bind that id to
+The hook may bind that id to
 `.cowork-flow/.runtime/subagents/<runtime_context_id>.json` before workflow
 state is injected. The first child step must still run:
 
@@ -194,6 +188,6 @@ Rules:
   and each JSONL `file` entry.
 - Keep edits inside the assigned scope.
 - Report changed files and exact verification commands.
-- Do not use the `task` tool or invoke subagents.
+- Do not use the Task tool or invoke subagents.
 - Do not run task start, task finish, task archive, unscoped resume, commit, or
   push.

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

@@ -19,7 +19,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.",
@@ -28,7 +28,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.",
@@ -88,7 +88,7 @@ def _normalize_hook_input(hook_input: dict[str, Any]) -> 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:
@@ -102,16 +102,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:
@@ -129,13 +136,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="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")

package/template/.claude/skills/before-dev/SKILL.md

@@ -15,6 +15,7 @@ Use this immediately before code edits.
 4. Active task `implement.jsonl`
 5. Relevant `.cowork-flow/spec/*/index.md`
 6. Any exact files named by the task, plan, or user
+7. If the task changes behavior, locate or create `tdd.jsonl` evidence before implementation.
 
 Do not bulk-load unrelated tasks, archived sessions, or every spec file.
 

package/template/.claude/skills/check/SKILL.md

@@ -16,6 +16,7 @@ Use this after implementation and before `finish-work`.
 5. Review test intent: reject shallow tests that do not fail for meaningful behavior breaks.
 6. Run focused tests that would fail if the changed behavior broke.
 7. Run broader validation when the change touches shared runtime, templates, packaging, or public workflow.
+8. Report `test_intent_review` with the key tests that defend PRD acceptance behavior.
 
 ## Report
 

package/template/.claude/skills/party-mode-v2/SKILL.md

@@ -26,6 +26,7 @@ Always use the runtime controller:
 .cowork-flow/run party-v2 post
 .cowork-flow/run party-v2 respond
 .cowork-flow/run party-v2 advance
+.cowork-flow/run party-v2 record-action-result
 .cowork-flow/run party-v2 finalize
 ```
 
@@ -38,6 +39,7 @@ Do not bypass a runtime rejection by manually accepting child output. Runtime va
 - Historical board state is runtime-private and may be used only for audit or final reports.
 - Use at least three child agents unless the effective runtime config explicitly allows a different value.
 - The runtime emits host-neutral next actions. The active Host Adapter or moderator executes them for Codex, Claude Code, or OpenCode.
+- Host action results must be recorded back through `record-action-result` so `agents.json`, audit logs, and action history can prove lifecycle state.
 
 ## Child Response Rules
 

package/template/.claude/skills/tdd/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: tdd
+description: Use when implementing behavior changes, bug fixes, state transitions, protocols, CLI/runtime contracts, data format changes, or error handling that can be tested before implementation.
+---
+
+# TDD
+
+Use this before editing behavior-changing code.
+
+## Red-Green-Refactor
+
+1. Map the task PRD acceptance criteria to stable IDs such as `AC-001`.
+2. Write the smallest meaningful failing test first.
+3. Run the red command and confirm it fails because the target behavior is missing or wrong.
+4. Implement the smallest change that makes the behavior pass.
+5. Run the green command and relevant broader verification.
+6. Refactor only after the behavior is green.
+
+Do not count shallow tests as TDD evidence. Tests that only import code, assert a function exists, assert `True`, count mocks without behavior, or mirror implementation details do not satisfy red-green-refactor.
+
+## Evidence
+
+Record TDD proof in `<task>/tdd.jsonl`. Each evidence line is one JSON object:
+
+```json
+{
+  "acceptanceId": "AC-001",
+  "testFile": "tests/test_example.py",
+  "testName": "test_behavior",
+  "redCommand": "python -m unittest tests.test_example.TestCase.test_behavior -v",
+  "redExitCode": 1,
+  "redOutputExcerpt": "expected failure excerpt",
+  "failureReason": "target behavior was not implemented",
+  "whyThisTestMatters": "explains which user-visible behavior would regress",
+  "greenCommand": "python -m unittest tests.test_example.TestCase.test_behavior -v",
+  "greenExitCode": 0,
+  "broaderVerification": "python -m unittest tests.test_example -v"
+}
+```
+
+Every evidence record must map to a PRD `acceptanceId`. The red failure must be about the target behavior, not syntax, import, environment, fixture, or setup failure.
+
+`testName` must resolve to the exact behavior test in `testFile`. Use one of:
+`test_method`, `ClassName.test_method`, or `module.ClassName.test_method`.
+Do not point evidence at a class, module, or a name that only exists in a command string.
+
+## Exemption
+
+Pure documentation, comment-only, or formatting-only tasks may use an exemption record instead of red/green evidence:
+
+```json
+{
+  "type": "exemption",
+  "acceptanceId": "AC-001",
+  "exemptionType": "docs-only",
+  "reason": "Only documentation wording changed; runtime behavior is untouched.",
+  "verificationCommand": "git diff --check"
+}
+```
+
+Do not use an exemption for runtime, CLI, protocol, state, data format, permission, or error-handling changes.

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.27
+0.0.28