cowork-flow 0.0.27 → 0.0.29

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。
@@ -93,7 +99,7 @@ OpenCode 项目级固定 agent、slash command 和系统上下文注入插件。
 npx cowork-flow init ./my-project --platform codex
 ```
 
-`init` 会显式要求平台和开发者身份。平台可选 `codex`、`opencode`、`claude-code`、`all`，其中 `both` 仍作为兼容别名表示 `codex,opencode`。交互式终端会提示输入；脚本或 CI 请传入：
+`init` 会显式要求平台和开发者身份。平台可选 `codex`、`opencode`、`claude-code`、`all`。交互式终端会提示输入；脚本或 CI 请传入：
 
 ```bash
 npx cowork-flow init ./my-project --platform codex --developer <your-name>
@@ -128,7 +134,7 @@ npx cowork-flow --help
 cowork-flow init ./my-project --platform codex
 ```
 
-`init` 会直接复制模板中的通用 `.cowork-flow/`，并按 `--platform` 只复制对应 host 资产：`codex` 复制 `.codex/`、`.agents/skills/` 与 `.cowork-flow/adapters/codex/`，`opencode` 复制 `.opencode/`、`.agents/skills/` 与 `.cowork-flow/adapters/opencode/`，`claude-code` 复制 `CLAUDE.md`、`.claude/`（含 `.claude/settings.json`、`.claude/hooks/`、`.claude/skills/`）与 `.cowork-flow/adapters/claude-code/`，不复制 `.agents/skills/`。`all` 或 `--platform codex,opencode,claude-code` 同时复制三者和 `.agents/skills/`。`both` 保持兼容，只复制 Codex 和 OpenCode。它还会初始化 `.cowork-flow/.developer` 与 `.cowork-flow/workspace/<developer>/`。交互式终端会先显示 checkbox 多选界面选择平台，再提示开发者名称；非交互式环境必须传入 `--platform <codex|opencode|claude-code|all>` 与 `--developer <name>`。`init` 不会复制额外技能包。
+`init` 会直接复制模板中的通用 `.cowork-flow/`，并按 `--platform` 只复制对应 host 资产：`codex` 复制 `.codex/`、`.agents/skills/` 与 `.cowork-flow/adapters/codex/`，`opencode` 复制 `.opencode/`、`.agents/skills/` 与 `.cowork-flow/adapters/opencode/`，`claude-code` 复制 `CLAUDE.md`、`.claude/`（含 `.claude/settings.json`、`.claude/hooks/`、`.claude/skills/`）与 `.cowork-flow/adapters/claude-code/`，不复制 `.agents/skills/`。`all` 或 `--platform codex,opencode,claude-code` 同时复制三者和 `.agents/skills/`。它还会初始化 `.cowork-flow/.developer` 与 `.cowork-flow/workspace/<developer>/`。交互式终端会先显示 checkbox 多选界面选择平台，再提示开发者名称；非交互式环境必须传入 `--platform <codex|opencode|claude-code|all>` 与 `--developer <name>`。`init` 不会复制额外技能包。
 
 初始化到当前项目：
 
@@ -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` 时才整文件覆盖保护文件。
 
 ## 常用入口
 
@@ -179,6 +185,16 @@ cowork-flow sync . --dry-run
 下面示例使用 macOS / Linux 写法；Windows 原生命令行中把
 `./.cowork-flow/run` 替换为 `.\.cowork-flow\run.cmd`。
 
+当前主流程以 `.cowork-flow/workflow.md` 为准。默认路径是：
+
+```text
+changes -> brainstorming -> read spec -> plan -> tasks -> implement -> check -> complete
+```
+
+L0 文档、格式、小范围重构或测试补充可简化为
+`brainstorming -> read spec -> implement -> check -> complete`；L1/L2 在完成后继续
+`archive -> add session`。
+
 初始化或查看开发者身份：
 
 ```bash
@@ -190,7 +206,6 @@ cowork-flow sync . --dry-run
 
 ```bash
 ./.cowork-flow/run get-context
-./.cowork-flow/run project-context refresh
 ./.cowork-flow/run task list
 ./.cowork-flow/run task next
 ```
@@ -210,18 +225,35 @@ cowork-flow sync . --dry-run
 ./.cowork-flow/run task start <task-dir>
 ```
 
-`task next` is read-only. It reports the active task, status, blockers, and the
-next safe command before the main session starts work, dispatches fixed agents,
-checks, archives, or records the session.
-
-`project-context refresh` 会创建或刷新 `.cowork-flow/project-context.md`。生成块由
-本地项目文件确定，`Manual Notes` 区保留人工补充；该文件是项目索引，不替代
-`AGENTS.md`、`.cowork-flow/workflow.md` 或 `.cowork-flow/spec/`。
+`task next` 只读，不推进状态。它根据当前会话任务和 `task.json.status`
+报告当前任务、阻塞项和下一条安全命令；主会话在启动工作、派发固定代理、
+进入检查、归档或记录 session 前都应先看它。
 
 L2 任务的 readiness gate 会在 `task start` 前阻塞缺失的 proposal/spec/design、
 计划、任务链接、边界、假设、验收标准或 verification commands；同一 blocker
 会出现在 `task next` 输出中。
 
+任务状态流转：
+
+```mermaid
+stateDiagram-v2
+    [*] --> NoTask
+    state "无当前任务" as NoTask
+    state "planning" as Planning
+    state "in_progress" as InProgress
+    state "review" as Review
+    state "completed" as Completed
+    state "已归档" as Archived
+
+    NoTask --> Planning: task create
+    Planning --> InProgress: task start
+    InProgress --> Review: task review
+    Review --> Completed: task complete
+    Completed --> Archived: task archive
+    Completed --> NoTask: task finish
+    Archived --> [*]
+```
+
 任务状态由阶段命令推进，`task next` 只读取状态：
 
 | 阶段 | 命令 | `task.json.status` |
@@ -230,11 +262,13 @@ L2 任务的 readiness gate 会在 `task start` 前阻塞缺失的 proposal/spec
 | 开始执行 | `task start <task-dir>` | `in_progress` |
 | 进入检查 | `task review [task-dir]` | `review` |
 | 检查完成 | `task complete [task-dir]` | `completed` |
+| 归档任务 | `task archive <task-name>` | 归档副本保持 `completed` |
 | 清会话指针 | `task finish` | 不改变状态 |
 
 执行 plan 时使用固定 cowork agents：
 
-主会话负责创建/启动任务、维护计划与收口验证；可并行的实现或检查工作通过 Codex subagent 交给固定角色 agent。
+主会话负责创建/启动任务、维护计划与收口验证；实现和检查默认通过当前 Host Adapter
+派发给固定角色 agent。固定 agent 是叶子执行者，不能再派发其他 agent，也不能替代主会话完成归档、记录 session 或提交。
 
 ```text
 ./.cowork-flow/run subagent init --role implement --agent-type cowork-implement --execution-task-dir <task-dir> --title "<title>"
@@ -249,7 +283,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 放进上下文。
+Host hook/plugin 启用后，每轮会自动注入 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.29",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {

package/src/commands/init.js

@@ -195,7 +195,7 @@ function initialIndexContent(name) {
 - Sessions are appended to the journal file
 - A new journal file is created automatically after the current file exceeds 2000 lines
 - Use \`add_session.py\` to record sessions
-- New records use English text; legacy records can remain as they are
+- New records use English text; existing records can remain as they are
 `;
 }
 

package/src/commands/update.js

@@ -6,10 +6,8 @@ import {
 } from '../lib/package-info.js';
 
 function validateUpdateArgs(args) {
-  for (const arg of args) {
-    if (arg !== '--global' && arg !== '--yes') {
-      throw new Error(`Unknown update option: ${arg}`);
-    }
+  if (args.length > 0) {
+    throw new Error(`Unknown update option: ${args[0]}`);
   }
 }
 

package/src/lib/copy-template.js

@@ -1,5 +1,5 @@
-import { constants } from 'node:fs';
-import { access, chmod, copyFile, mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { access, chmod, copyFile, mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, join, relative } from 'node:path';
 
 import { templateRoot } from './paths.js';
@@ -96,7 +96,42 @@ 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 OBSOLETE_SYNC_FILES = new Set([
+  '.cowork-flow/project-context.md',
+  '.cowork-flow/scripts/add_session.py',
+  '.cowork-flow/scripts/change.py',
+  '.cowork-flow/scripts/doctor.py',
+  '.cowork-flow/scripts/get_context.py',
+  '.cowork-flow/scripts/get_developer.py',
+  '.cowork-flow/scripts/init_developer.py',
+  '.cowork-flow/scripts/party_mode_v2.py',
+  '.cowork-flow/scripts/project_context.py',
+  '.cowork-flow/scripts/resume.py',
+  '.cowork-flow/scripts/subagent.py',
+  '.cowork-flow/scripts/task.py',
+  '.cowork-flow/scripts/common/active_task.py',
+  '.cowork-flow/scripts/common/archive_utils.py',
+  '.cowork-flow/scripts/common/coding_standards.py',
+  '.cowork-flow/scripts/common/config.py',
+  '.cowork-flow/scripts/common/developer.py',
+  '.cowork-flow/scripts/common/execution_context.py',
+  '.cowork-flow/scripts/common/files.py',
+  '.cowork-flow/scripts/common/gates.py',
+  '.cowork-flow/scripts/common/git_context.py',
+  '.cowork-flow/scripts/common/git_snapshot.py',
+  '.cowork-flow/scripts/common/paths.py',
+  '.cowork-flow/scripts/common/readiness.py',
+  '.cowork-flow/scripts/common/state_machine.py',
+  '.cowork-flow/scripts/common/task_utils.py',
+  '.cowork-flow/scripts/common/tdd_evidence.py',
+  '.cowork-flow/scripts/common/test_intent.py',
+  '.cowork-flow/scripts/common/validate_coding_standards.py',
+  '.cowork-flow/scripts/common/validate_implementation.py',
+  '.cowork-flow/scripts/common/validate_rules.py',
+  '.cowork-flow/spec/contracts/entry-contract.md'
 ]);
 
 const COWORK_FLOW_START = '<!-- COWORK-FLOW:START -->';
@@ -200,6 +235,13 @@ export async function buildSyncPlan(targetDir, options = {}) {
     }
   }
 
+  for (const file of OBSOLETE_SYNC_FILES) {
+    const destination = join(targetDir, file);
+    if (await pathExists(destination)) {
+      actions.push({ action: 'delete', source: null, destination, relativePath: file });
+    }
+  }
+
   actions.push({
     action: 'update',
     source: null,
@@ -226,7 +268,7 @@ export async function detectInstalledPlatforms(targetDir) {
 }
 
 export function summarizePlan(actions, dryRun = false) {
-  const counts = { create: 0, update: 0, skip: 0, protected: 0 };
+  const counts = { create: 0, update: 0, skip: 0, protected: 0, delete: 0 };
   for (const action of actions) {
     counts[action.action] += 1;
   }
@@ -234,7 +276,8 @@ export function summarizePlan(actions, dryRun = false) {
   const prefix = dryRun ? 'dry-run ' : '';
   const createLabel = dryRun ? 'would-create' : 'created';
   const updateLabel = dryRun ? 'would-update' : 'updated';
-  return `${prefix}${createLabel}=${counts.create} ${updateLabel}=${counts.update} skipped=${counts.skip} protected=${counts.protected}\n`;
+  const deleteLabel = dryRun ? 'would-delete' : 'deleted';
+  return `${prefix}${createLabel}=${counts.create} ${updateLabel}=${counts.update} ${deleteLabel}=${counts.delete} skipped=${counts.skip} protected=${counts.protected}\n`;
 }
 
 export async function applyPlan(actions, options = {}) {
@@ -246,6 +289,10 @@ export async function applyPlan(actions, options = {}) {
     if (item.action === 'skip' || item.action === 'protected') {
       continue;
     }
+    if (item.action === 'delete') {
+      await rm(item.destination, { force: true });
+      continue;
+    }
 
     await mkdir(dirname(item.destination), { recursive: true });
     if (item.content !== undefined) {

package/src/lib/platforms.js

@@ -1,10 +1,7 @@
 export const SUPPORTED_PLATFORMS = ['codex', 'opencode', 'claude-code'];
 
-const LEGACY_BOTH_PLATFORMS = ['codex', 'opencode'];
-
 const PLATFORM_ALIASES = new Map([
   ['all', SUPPORTED_PLATFORMS],
-  ['both', LEGACY_BOTH_PLATFORMS],
   ['codex', ['codex']],
   ['opencode', ['opencode']],
   ['claude', ['claude-code']],

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-check.md

@@ -24,9 +24,9 @@ state is injected. The first child step must still run:
 ```
 
 If the explicit bind fails, or if the bound context is missing, closed, invalid,
-or names another agent type, report `needs_context` and stop. Do not use
-`COWORK_ENTRY_CONTRACT_V1` to infer subagent identity; that contract classifies
-main-session prompts only.
+or names another agent type, report `needs_context` and stop. Do not infer
+subagent identity from prompt shape; runtime context binding is the only formal
+signal.
 
 Rules:
 

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:
 
@@ -30,9 +24,9 @@ state is injected. The first child step must still run:
 ```
 
 If the explicit bind fails, or if the bound context is missing, closed, invalid,
-or names another agent type, report `needs_context` and stop. Do not use
-`COWORK_ENTRY_CONTRACT_V1` to infer subagent identity; that contract classifies
-main-session prompts only.
+or names another agent type, report `needs_context` and stop. Do not infer
+subagent identity from prompt shape; runtime context binding is the only formal
+signal.
 
 ---
 
@@ -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/agents/cowork-research.md

@@ -24,9 +24,9 @@ state is injected. The first child step must still run:
 ```
 
 If the explicit bind fails, or if the bound context is missing, closed, invalid,
-or names another agent type, report `needs_context` and stop. Do not use
-`COWORK_ENTRY_CONTRACT_V1` to infer subagent identity; that contract classifies
-main-session prompts only.
+or names another agent type, report `needs_context` and stop. Do not infer
+subagent identity from prompt shape; runtime context binding is the only formal
+signal.
 
 Rules:
 

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

@@ -17,18 +17,9 @@ TAG_RE = re.compile(
 )
 DEFAULT_CONTRACT_REGISTRY = {
     "contracts": [
-        {
-            "id": "COWORK_ENTRY_CONTRACT_V1",
-            "path": ".cowork-flow/spec/entry-contract.md",
-            "digest": [
-                "Classify main-session requests before task start, resume, archive, or commit.",
-                "Runtime context, not prompt labels, identifies formal subagent sessions.",
-            ],
-            "readWhen": ["before task start/resume/archive", "when prompt and bootstrap text conflict"],
-        },
         {
             "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 +79,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 +93,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 +127,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")
@@ -161,7 +161,7 @@ def _load_common(root: Path) -> None:
 def _get_active_task(root: Path, hook_input: dict[str, Any]) -> tuple[str | None, str, str]:
     _load_common(root)
     try:
-        from common.active_task import get_active_task  # type: ignore[import-not-found]
+        from common.task.active_task import get_active_task  # type: ignore[import-not-found]
     except Exception:
         return None, "no_task", "unavailable"
 
@@ -185,7 +185,7 @@ def _get_active_task(root: Path, hook_input: dict[str, Any]) -> tuple[str | None
 def _resolve_runtime_context(root: Path, hook_input: dict[str, Any]) -> tuple[dict[str, Any] | None, str | None]:
     _load_common(root)
     try:
-        from common.active_task import (  # type: ignore[import-not-found]
+        from common.task.active_task import (  # type: ignore[import-not-found]
             bind_runtime_context,
             read_runtime_context,
             resolve_runtime_context_id,

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