cowork-flow 1.2.0 → 1.4.0

package/template/.cowork-flow/spec/contracts/context-injection.md

@@ -3,10 +3,11 @@
 Single source for how every host adapter injects cowork-flow runtime context
 into a session: the transport shape, the event timing matrix, the contract
 digest shape rules (full block vs fingerprint line), and the fingerprint
-serialization norm. All host implementations — zcode JS hook, the Python
-shared core (codex / claude-code / dsh), and the opencode JS plugin — must
-follow this document; cross-host behavior tests lock the three independent
-implementations to it.
+serialization norm. The workflow facts are rendered by ONE Python source —
+`adapters/host/inject.py` over `workflow_state_hook.py` +
+`services.fact_view.py` — consumed by the zcode transport shim (node),
+claude-code, codex, and dsh; the opencode JS plugin remains the one
+independent mirror, locked to the same bytes by cross-host behavior tests.
 
 This document is a meta-protocol: it describes the injection layer itself and
 is intentionally **not** registered in `contract-registry.json` (registering it
@@ -16,9 +17,9 @@ would make the digest self-referential).
 
 | Host | Transport | Shape |
 |---|---|---|
-| zcode | process hook (`inject-context.js`), stdout JSON | `hookSpecificOutput.{hookEventName, additionalContext}` |
-| codex | command hook (Python shell), stdout JSON | same shape |
-| claude-code | command hook (Python shell), stdout JSON | same shape |
+| zcode | process hook shim (`inject-context.js`) → `inject.py --host zcode`, stdout JSON | `hookSpecificOutput.{hookEventName, additionalContext}` |
+| codex | thin wrapper (`inject-workflow-state.py`) → `inject.py --host codex`, stdout JSON | same shape |
+| claude-code | thin wrapper (`inject-workflow-state.py`) → `inject.py --host claude-code`, stdout JSON | same shape |
 | opencode | plugin `experimental.chat.system.transform` + `shell.env` | system-prompt section push / env object |
 | dsh | preset plugin system-prompt section | named section, replace semantics |
 
@@ -27,7 +28,8 @@ runtime preamble, the contract digest (full block or fingerprint line, see
 below), optional `decision-anchor` / `stage-contract` blocks, and the
 `<workflow-state>` block. It is **not** byte-identical across hosts at the
 string level — the digest policy line differs per host wording and zcode
-drops the registry-warning line. Exactly two things are byte-identical and
+drops the registry-warning line; both differences are selected inside the
+single Python source by `--host`. Exactly two things are byte-identical and
 test-locked: the contract digest **fingerprint value** and the
 `<stage-contract>` block.
 
@@ -83,8 +85,13 @@ The `<workflow-state>` open tag carries the machine-readable fact header as
 XML attributes; the body keeps the human-readable breadcrumb prose.
 
 - Attributes: `status` and `source` are always present; `task` (repo-relative
-  task path) appears whenever a task is bound. Attribute values are XML-escaped
-  (`& < > "`).
+  task path) appears whenever a task is bound; `session` (the caller's
+  resolved context key) appears whenever a session identity is resolvable
+  from the hook input or environment and is omitted otherwise (hosts that
+  cannot resolve an identity never guess one — the attribute is the machine
+  handle for re-binding with `COWORK_FLOW_CONTEXT_ID`). Attribute values are
+  XML-escaped (`& < > "`). The opencode JS mirror does not emit `session`
+  (delegated-only transport; documented behavioral difference, not drift).
 - The legacy `Task:` / `Status:` / `Source:` label lines are gone — machines
   parse the attributes, humans read the body. There is no bare `Scope:`
   line in the body: the stage-contract block owns the scope declaration
@@ -92,11 +99,19 @@ XML attributes; the body keeps the human-readable breadcrumb prose.
   as a read-only `[read-only]` reference of the parent task).
 
 ```text
-<workflow-state task=".cowork-flow/tasks/08-28-demo" status="in_progress" source="runtime-session">
+<workflow-state task=".cowork-flow/tasks/08-28-demo" status="in_progress" source="runtime-session" session="zcode_probe">
 活动任务正在执行。...
 </workflow-state>
 ```
 
+- Unbound-session fallback (zcode only, display/warning-only): a hook
+  session with no binding follows another main session's binding only while
+  **exactly one** main-session binding exists (`source="session-fallback"`).
+  With two or more main-session bindings the newest one belongs to some
+  other window, so the fallback refuses: the injection renders
+  `status="no_task"` plus the rebind hints list. The CLI lifecycle commands
+  keep their strict identity semantics regardless (FALLBACK_BINDING_BLOCKER).
+
 ## Decision-anchor injection (stage 1)
 
 For tasks whose status is `planning`, `in_progress`, or `review` (a delegated
@@ -171,16 +186,17 @@ Verify: npm run test:fast; python3 -m pytest tests/ -q
   (min 1) — the closing tag and the Gates row always survive; tests assert
   the block stays well-formed. The scope-filter rules and the stage-contract
   budget/limits come from `.cowork-flow/spec/runtime/scope-rules.json`, the
-  single source consumed by Python and both JS mirrors at runtime; a missing
-  or malformed file degrades to embedded defaults that are byte-identical
-  with the shipped file (locked by `tests/test_scope_rules.py`).
+  single source consumed at runtime; a missing or malformed file degrades to
+  embedded defaults that are byte-identical with the shipped file (locked by
+  `tests/test_scope_rules.py`).
 - Absent for `no_task` / `planning` / `completed` states. Block content is
-  byte-identical across the three host implementations for the whole fixture
-  matrix (`test/fixtures/stage-contract-matrix.json` drives the cross-host
-  equality test: canonical, `./`-prefixed, invalid-boundary, over-budget,
-  emoji, missing-anchor, empty-scope, delegated-readonly). The JS scope
-  filter is a port of the Python rules and is locked by that matrix — a
-  port, not a mechanism, so the matrix list grows whenever the rules grow.
+  byte-identical across host lines for the whole fixture matrix
+  (`test/fixtures/stage-contract-matrix.json` drives the equality test:
+  canonical, `./`-prefixed, invalid-boundary, over-budget, emoji,
+  missing-anchor, empty-scope, delegated-readonly). The zcode line now runs
+  through the same Python source as the python line (transport shim), so the
+  matrix's remaining cross-host assertion is opencode's JS mirror against
+  the single source — a mirror, not a mechanism.
 
 The authoritative per-file verdict lives in the MCP `task_scope` tool
 (`services.fact_view.file_scope_whitelist` — same semantics, live data).
@@ -189,15 +205,16 @@ The authoritative per-file verdict lives in the MCP `task_scope` tool
 
 sha256 over (1) the registry `contracts` array serialized with
 **recursively sorted keys** (Python `json.dumps(..., sort_keys=True,
-ensure_ascii=False)`; the JS implementations use the equivalent
+ensure_ascii=False)`; the opencode plugin uses the equivalent
 `stableStringify`), then (2) each contract file's raw bytes in registry
 order; a missing file hashes as the literal string `missing:<path>`. The
 fingerprint is the first 16 hex chars of the digest.
 
-Serialization must be byte-identical across the three implementations: same
+Serialization must be byte-identical across implementations: same
 key order, same escaping (ASCII-safe content), same UTF-8 encoding. The
 cross-host test (`test/contract-fingerprint.test.js`) asserts this and is the
-regression lock against drift.
+regression lock against drift between the opencode mirror and the Python
+single source.
 
 ## Change guard
 

package/template/.cowork-flow/spec/contracts/fact-layer-access.md

@@ -1,7 +1,19 @@
 # Fact-layer access
 
 How external tools (MCP clients today, other ecosystem protocols as they
-converge) read cowork-flow task facts. Stage 3 of `docs/direction.md`.
+converge) and agents on hosts without injection hooks read cowork-flow task
+facts. Stage 3 of `docs/direction.md`.
+
+## Three channels, one fact layer
+
+All channels consume the same services layer (`services/fact_view.py`) and
+cannot drift on facts:
+
+| Channel | Direction | Role |
+|---|---|---|
+| Hooks (host adapter → `inject.py`) | push | Proactive context injection; host-enforced, agents cannot skip it. |
+| CLI lifecycle commands | write + pull | The only write path; enforces the full gate chain. Pull fallback when MCP is unavailable. |
+| MCP tools | pull | Standardized read access for external clients (IDEs, dashboards) and hosts without hook support. |
 
 ## Stance
 
@@ -25,19 +37,42 @@ stderr is kept log-only).
 
 Global registration: `cowork-flow mcp-state` (npm CLI) resolves the nearest
 `.cowork-flow/` from the client's cwd and execs that project's runner with
-inherited stdio — register it once (`command: cowork-flow, args:
-["mcp-state"]`) and every cowork-flow project works, because the root
-resolution is identical to the server's own (`get_repo_root`). Outside a
-project the passthrough fails with a clear error; inside one, nested
-subdirectories resolve to the project root.
+inherited stdio. Outside a project the passthrough fails with a clear error;
+inside one, nested subdirectories resolve to the project root.
 
 Server info: `cowork-flow-facts`. On `initialize` the server echoes the
 client's requested `protocolVersion` (falling back to `2025-06-18`).
 
 | Tool | Input | Output | Reads |
 |---|---|---|---|
-| `task_state` | `{task?: string}` | The fact view as JSON text (`task`, `decisionAnchor`, `plan`, `sessions`, `snapshot`); without `task`, the session-bound active task, or `{"task": null, "reason": "no-active-task"}` | `services/fact_view.build_fact_view` |
+| `task_state` | `{task?: string}` | The fact view as JSON text (`task`, `decisionAnchor`, `plan`, `sessions`, `snapshot`); without `task`, the session-bound active task when one resolves, or `{"task": null, "reason": "no-active-task"}` | `services/fact_view.build_fact_view` |
 | `task_list` | `{}` | Active tasks overview: name, path, status, assignee, parent/children, active flag | `TaskTreeService.active_nodes` via the list records |
+| `task_scope` | `{task?: string, path?: string}` | The file-scope whitelist summary, or a per-path `inScope` verdict with `path` | `services/fact_view.file_scope_whitelist` / `path_in_scope` |
+| `task_specs` | `{task?: string}` | The spec/skill reading list dispatched by the task's `dev_type` | `services/fact_view.spec_entries_for_task` |
+
+`task_scope` and `task_specs` have CLI fact-command equivalents
+(`task scope`, `task specs`) consuming the same facade — MCP holds no
+exclusive capability.
+
+The MCP server process has no session concept: `task_state` without `task`
+resolves the caller's session only when session identity reaches the server
+through the environment (session-bound env keys). Where it cannot, it returns
+`no-active-task` — pass `task` explicitly for deterministic project-level
+queries. Session-bound facts remain the hook/CLI channels' responsibility.
+
+## Registration map (two tiers)
+
+| Host | Global (supported default) | Project-level opt-in |
+|---|---|---|
+| claude-code | `claude mcp add cowork-flow -- cowork-flow mcp-state` | `.mcp.json` with an `mcpServers` entry |
+| zcode | user config `mcp.servers.cowork-flow = {command: cowork-flow, args: [mcp-state]}` | plugin format has no MCP field — use the global tier |
+| codex | `~/.codex/config.toml` `[mcp_servers.cowork-flow]` | project config cannot enable user-approval-gated capabilities — use the global tier |
+| opencode | `opencode.json` `mcp` entry | — |
+
+`run doctor` reports the registration state (project entry present, absent,
+or duplicated across tiers) as an advisory, read-only health item. Registering
+a new contract changes the digest fingerprint everywhere; see the change
+guard.
 
 Tool failures (unknown task, missing task.json) ride the tool result with
 `isError: true`; the JSON-RPC frame stays valid.
@@ -47,4 +82,4 @@ Tool failures (unknown task, missing task.json) ride the tool result with
 - New fact sources (fields on the fact view) are additive; consumers must
   tolerate unknown keys.
 - Any write-capable tool proposal must re-open this contract first — and is
-  rejected by default under the current stance.
+  rejected by default under the current stance.

package/template/.cowork-flow/spec/contracts/spec-checks.md

@@ -21,9 +21,11 @@ checks:
 
 - `files` 只支持两种形式：目录前缀（`src/`，以 `/` 结尾或自动补齐）与
   扩展名（`*.ts`）。完整 glob 形态（`**`、`[]`）解析为错误，声明不执行，
-  doctor 报告——绝不回退为"匹配一切"。
+  doctor 报告——绝不回退为"匹配一切"。多值形态（如 `files: "src/", "lib/"`）
+  每个 token 按同样的引号规则去引号后生效。
 - `when: edit` 的声明在编辑期（PostToolUse）对命中 `files` 的改动文件
-  就地执行，超时被钳制到 3 秒；慢命令请声明 `when: lifecycle`。
+  就地执行，超时被钳制到 2.5 秒（为解释器启动与 cmd 包装留 spawn 预算）；
+  慢命令请声明 `when: lifecycle`。
 - 引号规则：仅值整体为单对引号时去引号；`"python" -c "..."`
   这类含多对引号的命令值原样保留，由执行器按 shell 规则拆分。
 
@@ -42,12 +44,26 @@ spec 为无检查并进 doctor 报告，不炸流程。
 
 - **编辑期**（zcode/claude）：违规输出单行
   `spec-check[<spec>] violation: <首个违规行>`；同一文件 10 秒内只报一次
-  （节流状态在 `.cowork-flow/.runtime/spec-edit-throttle.json`）；执行器
-  缺失或超时静默，绝不阻断编辑流。
+  （节流状态在 `.cowork-flow/.runtime/spec-edit-throttle.json`，检查完整
+  跑过才写节流——执行器崩溃不消费时间窗，重试仍会执行）；执行器
+  缺失或超时静默，绝不阻断编辑流。delegated 子代理会话同样收到 spec
+  违规反馈（子代理是主力写码者）；scope 警告保持 main-only。zcode 主
+  会话的 hook 身份（对话自身 session id）不会被绑定——激活发生在 Bash
+  侧显式身份下——显示与编辑期警告按最新主会话兜底；claude/codex 保持
+  严格会话身份（其 Bash env 携带同一 session id）。zcode 经
+  shim 转发到单源入口（`inject.py`），scope 警告与 spec 警告合并进同一个
+  additionalContext 载荷；claude 走 exit 2 stderr 反馈。
 - **收口期**（task complete）：全量执行，结果进 `meta.specCheckSummary`
   遥测；阻断消息只列未过项摘要。
 - 手动查询：`./.cowork-flow/run spec-check [--file <path>] [--json]
   [--verbose]`。
+- **edit-only 是 best-effort 提示，不是门禁**：Bash 直写绕过 PostToolUse
+  不会触发编辑期反馈；无编辑期快跑能力的宿主（见能力矩阵）同样没有
+  这层提示，且收口期不会对 `when: edit` 声明补跑。需要硬门禁的检查
+  必须声明 `when: lifecycle` 或默认 `both`。
+- **开放决策**：收口期全量执行没有聚合预算——声明多且慢的仓库 complete
+  会线性变慢；是否给收口加并行/预算上限留给后续产品决策，当前保持
+  简单串行。
 
 ## 归属与 sync 策略
 
@@ -60,15 +76,31 @@ spec 为无检查并进 doctor 报告，不炸流程。
 
 | 宿主 | digest 注入 | 编辑期快跑 | 收口强制 |
 | --- | --- | --- | --- |
-| zcode | 有（Specs 行 h2 digest） | 有（PostToolUse 短路径） | 有 |
+| zcode | 有（Specs 行 h2 digest） | 有（PostToolUse 短路径；**仅主会话**） | 有 |
 | claude-code | 有（Python 单源） | 有（PostToolUse，exit 2 反馈） | 有 |
 | opencode | 有 | **降级：无**（插件无 PostToolUse 短路径） | 有 |
 
+**delegated 子代理编辑期缺口（zcode 实测，2026-09-09 两轮）**：ZCode 的插件
+hook 只在主会话工具流上派发（事件模型七事件均挂主会话；子代理是独立内部
+会话流 `sess_subagent_agent_*`），Agent 子代理的 Edit/Write 收不到
+`spec-check[...] violation` 行——runtime 绑定与检查逻辑均正常，缺的是宿主
+派发。补偿机制（subagent-dispatch.md 契约固化）：
+
+1. 子代理完成前自查：`./.cowork-flow/run spec-check` 全量并修复（拉取路径，
+   实测有效）；
+2. 父会话验收前再查：violation 视为验收阻塞（反馈时点从收口提前到返回）；
+3. 实现类任务 Verify 命令默认含 spec-check 自查；
+4. 收口硬门禁兜底不变（violation 阻断 complete）。
+
+治理方向：向宿主提需求扩展子代理工具流的 hook 派发；落地后第 1 条自动
+退化为冗余保险。
+
 ## digest 注入
 
 进入 in_progress 后，stage-contract 的 Specs 行升级为
-`Specs: <spec>(<h2 标题树>); …`：最多 6 个 h2 条目、每条截断 24 字符、
-剔除 `();` 字符；文件缺失不加注解。digest 是条目名索引不是正文，受
+`Specs: <spec>(<h2 标题树>); …`：最多 6 个 h2 条目、每条截断 24 字符、剔除
+`();` 字符；文件缺失不加注解。digest 是条目名索引不是正文，受
 scope-rules.json `stageContract.budget` 硬顶，超预算整行让位
-（Scope/Gates 行永不丢）。格式由三线逐字相等测试锁定
+（Scope/Gates 行永不丢）。python/zcode 输出同源于单一 Python 入口，
+opencode 镜像与它逐字相等由 matrix 用例锁定
 （`test/stage-contract.test.js` matrix）。

package/template/.cowork-flow/spec/contracts/subagent-dispatch.md

@@ -61,12 +61,33 @@ child output. If binding fails, the child must receive fail-closed subagent stat
 and must not run main-session start/resume, task activation, archive, commit,
 or agent coordination.
 
+## Delegated Spec Self-Check
+
+Delegated subagent tool calls receive no edit-phase hook feedback on hosts
+whose plugin hooks cover only the main session stream (verified on zcode:
+plugin PostToolUse fires for main-session tool calls but never for
+Agent-tool children). The reliable pull path is the CLI: before reporting
+completion, `cowork-implement` (and any child that changes files) runs
+
+```text
+./.cowork-flow/run spec-check
+```
+
+fixes every reported violation, and re-runs until the summary is clean or the
+remaining violations are reported as blockers. This is a protocol behavior,
+not a second lifecycle gate — the closeout gate re-runs the same checks and
+blocks completion regardless.
+
 ## Return Acceptance And Closeout
 
 - Wait for the child result with the adapter wait primitive.
 - Confirm no stray running children with the adapter list primitive.
 - Verify the child report by checking files, commands, and results; do not
   trust completed text alone.
+- Before accepting delegated output, run `./.cowork-flow/run spec-check` in
+  the main session and treat every violation as an acceptance blocker: the
+  child receives no edit-phase hook feedback, so acceptance-time checking is
+  the earliest reliable checkpoint for delegated work.
 - After completion or failure, close the child with the adapter cancel/close
   primitive and clean the runtime context sessions.
 - The child remains a leaf executor and must not dispatch, wait for, list, or

package/template/.cowork-flow/spec/runtime/contract-registry.json

@@ -63,6 +63,18 @@
         "when adding new workflow states"
       ]
     },
+    {
+      "id": "FACT_LAYER_ACCESS_V1",
+      "path": ".cowork-flow/spec/contracts/fact-layer-access.md",
+      "digest": [
+        "Task/scope/spec facts are read-only via MCP tools or CLI; writes only flow through CLI lifecycle gates.",
+        "Prefer MCP task_state/task_scope/task_specs for fact queries when available; CLI is the fallback."
+      ],
+      "readWhen": [
+        "when querying task facts or file scope",
+        "when registering the fact layer for a new host or external client"
+      ]
+    },
     {
       "id": "PARTY_MODE_V2_BOARD_V1",
       "path": ".cowork-flow/spec/contracts/party-mode-v2-board.md",

package/template/.opencode/plugins/cowork-flow.js

@@ -14,6 +14,18 @@ const DEFAULT_CONTRACT_REGISTRY = {
       ],
       readWhen: ["before formal subagent dispatch", "when checking subagent health"],
     },
+    {
+      id: "FACT_LAYER_ACCESS_V1",
+      path: ".cowork-flow/spec/contracts/fact-layer-access.md",
+      digest: [
+        "Task/scope/spec facts are read-only via MCP tools or CLI; writes only flow through CLI lifecycle gates.",
+        "Prefer MCP task_state/task_scope/task_specs for fact queries when available; CLI is the fallback.",
+      ],
+      readWhen: [
+        "when querying task facts or file scope",
+        "when registering the fact layer for a new host or external client",
+      ],
+    },
   ],
 }
 

package/template/.zcode/.zcode-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "AI 协作工作流引擎：任务生命周期、子代理调度、门禁与状态注入。将 cowork-flow 的完整工作流带入 ZCode。",
   "author": {
     "name": "fisklikewater"