cowork-flow 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@
 
 ### Added
 
+## [2.4.0] - 2026-10-23
+
+### Added
+
+- **`docs/` 五份文档提供并列英文版**：`docs/index.en.md`、`architecture.en.md`、`hosts.en.md`、`release.en.md`、`direction.en.md` 为对应中文文档的完整英文翻译，中英页面顶部互链，`README.en.md` 的文档入口改指英文版。新增文档门禁（`test/docs.test.js`）：中英文件成对存在、标题层级序列一致、中英索引各自链接本语言全部文档、双向语言链接与相对链接可解析；任一英文版缺失或标题结构漂移都会失败。`docs/` 本就在 npm 发布清单内，英文版随包分发，不引入文档框架。
+- **安装语言选项与任务/计划产物本地化**：`cwf project init --language zh-CN|en-US`（别名 `zh` / `en`，默认 `zh-CN`）把选择写入 `.cowork-flow/config.yaml` 的 `language`；`decision-anchor.md` 新增英文合同变体，计划结构抽为可分发的 `.cowork-flow/templates/plan-template.md` 并提供英文版本。`init`、`sync` 与 `dev refresh` 按 config 语言选择 locale 源，目标路径不变，`locales/` 不进入项目。任务创建始终生成对应语言的 anchor 骨架，`**Goal:**` / `**目标:**` / 表格行三种计划目标均可提取；中文、英文、混合标题的 anchor 都能被 fact view、启动前置检查、strict gate 与证据完成门禁读取。
+- **doctor 语言一致性检查**：`CONFIG-LANGUAGE-001` 报告非法 `language`（error），`LANGUAGE-DRIFT-001` 报告已安装合同/计划模板与配置语言不一致（warning，提示 `cwf project sync`）；缺少 `language` 键或旧安装尚未分发 `plan-template.md` 时保持静默。
+
+### Changed
+
+- **`config.yaml` 成为强制保护文件**：Host Asset Manifest 新增 `syncPolicy.forceProtectedFiles`，`.cowork-flow/config.yaml` 首次创建后不再被 `init --force` 或 `sync --force` 覆盖；切换语言需编辑该文件后运行 `sync`。已有配置中的 `language` 优先于 `--language`，冲突时输出警告但不改写配置。
+
+- **分发 spec 说明文档英文化（第一步）**：`spec/index.md`、`spec/runtime/index.md`、`spec/schemas/index.md` 与 `spec/references/**` 的说明文字改为英文，保留文件列表、相对链接、DoD 的 G5 标记与协作模式约束编号。`decision-anchor.md` 的六个解析标题、`workflow-state-templates.md` 的注入块、`backend/frontend/guides` 与 `template/AGENTS.md` 本步不动，前两项待双语解析迁移。**可达性**：三个索引随 `project sync` 更新；`references/` 仍受项目同步保护，已装项目不会自动收到英文副本，需手动刷新或重新安装。
+
+- **下游 `project sync` 开始同步框架 spec 资产**：`syncPolicy.protectedPrefixes` 从整个 `.cowork-flow/spec/` 收窄为 `spec/backend/`、`spec/frontend/`、`spec/guides/`、`spec/references/`，让 `spec/contracts/`、`spec/runtime/`（含 `contract-registry.json`、`host-assets.json`、`scope-rules.json`）、`spec/schemas/` 与 `spec/index.md` 随普通 `project sync` 更新——下游不再出现“脚本已升级、契约与宿主 manifest 仍停在安装代际”的混合状态，新增契约、宿主与 schema 能到达已装项目。**迁移**：登记在 `obsoleteFiles` 的过期框架 spec（`spec-checks.md`、`entry-contract.md`、`rules.json`、`skill-registry.json` 及对应 schema）会在下一次 sync 被自动删除，不再要求手动清理；本地修改过框架契约或 `scope-rules.json` 的项目会丢失这些改动，项目定制应写入四个受保护的 spec 目录、`AGENTS.md`、`config.yaml` 或项目自有 Skill。`dev refresh`（源码检出刷新）仍镜像整个 `template/.cowork-flow/spec/`：源码检出里的项目自有 spec 目录也是框架模板内容，因此刷新时不受下游保护前缀限制；任务、计划、`config.yaml`、`.developer` 与 `.runtime` 保持受保护。
+
 ## [2.3.0] - 2026-10-21
 
 ### Added
@@ -407,7 +423,8 @@
 
 此版本未保留本地条目正文，详情见 [GitHub Release](https://github.com/fishlikewater/cowork-flow/releases/tag/v0.0.47)。
 
-[Unreleased]: https://github.com/fishlikewater/cowork-flow/compare/v2.3.0...HEAD
+[Unreleased]: https://github.com/fishlikewater/cowork-flow/compare/v2.4.0...HEAD
+[2.4.0]: https://github.com/fishlikewater/cowork-flow/compare/v2.3.0...v2.4.0
 [2.3.0]: https://github.com/fishlikewater/cowork-flow/compare/v2.2.0...v2.3.0
 [2.2.0]: https://github.com/fishlikewater/cowork-flow/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/fishlikewater/cowork-flow/compare/v2.0.0...v2.1.0

package/README.en.md

@@ -16,7 +16,7 @@ Supports Codex, Claude Code, OpenCode, ZCode, Qoder, Kimi Code, and DeepSeek Har
 - Keeps requirements, decisions, plans, and the allowed change scope inside the project.
 - Makes the assistant read the current task before working, instead of continuing from memory.
 - Separates implementation from checking, so a problem sends the work back to implementation.
-- Protects custom configuration, specs, tasks, and plans in an existing project.
+- Protects custom configuration, project-owned specs, tasks, and plans in an existing project.
 
 cowork-flow is not tied to a tech stack and does not rewrite an existing project with a
 scaffold. It only adds a collaboration convention and the files that go with it.
@@ -56,9 +56,15 @@ cwf project init --host codex --developer alice --dry-run
 Drop `--dry-run` once the list looks right:
 
 ```bash
-cwf project init --host codex --developer alice
+cwf project init --host codex --developer alice --language en-US
 ```
 
+Without `--language` the default is `zh-CN`; an interactive terminal asks, and a
+non-interactive run uses the default. The choice is written to
+`.cowork-flow/config.yaml` and affects only task and plan artifacts
+(`.cowork-flow/spec/contracts/decision-anchor.md` and
+`.cowork-flow/templates/plan-template.md`).
+
 Replace `codex` with the host you use:
 
 `codex`, `claude-code`, `opencode`, `zcode`, `qoder`, `kimi-code`, `dsh`.
@@ -76,7 +82,9 @@ not touch application code. An existing `.developer` is never overwritten; on fi
 initialization an explicit `--developer` wins over `git config user.name`. With no git
 identity, an interactive terminal prompts and a non-interactive run fails (`--dry-run`
 only reports `would-skip`). `--platform` / `--platforms` remain accepted aliases of
-`--host`. On an existing project, always run `--dry-run` first.
+`--host`. An existing `.cowork-flow/config.yaml` owns its `language`, even under
+`--force`; edit that file and run `cwf project sync .` to switch languages. On an
+existing project, always run `--dry-run` first.
 
 ### 3. Finish host setup
 
@@ -87,7 +95,7 @@ DeepSeek Harness, and Kimi Code also need a machine-level component:
 cwf host add <host>
 ```
 
-See [host integration](docs/hosts.md) for each host's exact command, restart
+See [host integration](docs/hosts.en.md) for each host's exact command, restart
 requirements, and special cases.
 
 ### 4. Start inside the host
@@ -120,10 +128,16 @@ cwf project sync . --dry-run
 cwf project sync .
 ```
 
-`project sync` only updates files cowork-flow manages. Existing configuration, `spec/`,
-tasks, and plans are kept by default; **retired-asset cleanup** deletes obsolete
-cowork-flow files listed in the release manifest and touches nothing else. For upgrading
-machine-level host components, see [host integration](docs/hosts.md).
+`project sync` only updates files cowork-flow manages. Existing configuration,
+`spec/backend|frontend|guides|references`, tasks, and plans are kept by default;
+framework-managed `spec/contracts|runtime|schemas` and `spec/index.md` follow the
+sync. `.cowork-flow/config.yaml` is project configuration and is never overwritten by
+`sync --force`. Sync reads its `language` and distributes only that language's
+`decision-anchor.md` contract and `.cowork-flow/templates/plan-template.md`; tasks and plans follow that
+language by default, and an explicit user request may override it.
+**Retired-asset cleanup** deletes obsolete cowork-flow files listed in the
+release manifest and touches nothing else. For upgrading machine-level host
+components, see [host integration](docs/hosts.en.md).
 
 ## Troubleshooting
 
@@ -135,15 +149,15 @@ machine-level host components, see [host integration](docs/hosts.md).
 | Skills, plugins, hooks, or project files look wrong | Run `./.cowork-flow/run doctor --all` |
 | You are unsure how to write a command or flag | Run `cwf --help` or `cwf <group> <command> --help` |
 
-For host-specific problems, start with [host integration](docs/hosts.md). To understand
-how the project is organized, see [architecture and extension](docs/architecture.md).
+For host-specific problems, start with [host integration](docs/hosts.en.md). To understand
+how the project is organized, see [architecture and extension](docs/architecture.en.md).
 
 <details>
 <summary>Command reference</summary>
 
 | Command | Purpose |
 |---|---|
-| `cwf project init [target] --host <host> [--developer <name>] [--dry-run] [--force]` | Initialize a project |
+| `cwf project init [target] --host <host> [--developer <name>] [--language zh-CN|en-US] [--dry-run] [--force]` | Initialize a project |
 | `cwf project sync [target] [--dry-run] [--force]` | Update the cowork-flow-managed files in a project |
 | `cwf host add <host> [--component <name>] [--dry-run] [--force] [--prune-old] [--uninstall]` | Install a machine-level host component |
 | `cwf host remove <host> [--component <name>] [--dry-run] [--force]` | Remove a machine-level host component |
@@ -172,16 +186,18 @@ Old command names still work; use the new names in new scripts.
 
 ## Documentation
 
-The detailed documentation is written in Chinese.
+The detailed documentation is available in English and Chinese; each page links to its
+counterpart at the top.
 
 | Document | Contents |
 |---|---|
-| [Documentation index](docs/index.md) | Entry point for every document |
-| [Architecture and extension](docs/architecture.md) | How the project files are organized, how the sync policy and protected files work |
-| [Host integration](docs/hosts.md) | Install, restart, troubleshoot, and uninstall for each host |
-| [Release and maintenance](docs/release.md) | Tests, CI, and maintainer commands |
-| [Contributing](CONTRIBUTING.md) | Local setup, commit conventions, and PR checks |
-| [Changelog](CHANGELOG.md) | What changed in each version |
+| [Documentation index](docs/index.en.md) | Entry point for every document |
+| [Architecture and extension](docs/architecture.en.md) | How the project files are organized, how the sync policy and protected files work |
+| [Host integration](docs/hosts.en.md) | Install, restart, troubleshoot, and uninstall for each host |
+| [Release and maintenance](docs/release.en.md) | Tests, CI, and maintainer commands |
+| [Direction](docs/direction.en.md) | Positioning, settled trade-offs, version line, and open items |
+| [Contributing](CONTRIBUTING.md) | Local setup, commit conventions, and PR checks (Chinese) |
+| [Changelog](CHANGELOG.md) | What changed in each version (Chinese) |
 
 ## License
 

package/README.md

@@ -13,7 +13,7 @@
 - 把需求、决定、计划和允许修改的范围留在项目里。
 - 让助手每次工作前先读取当前任务，不凭印象继续。
 - 把实现和检查分开，发现问题后再回到实现阶段修正。
-- 在已有项目里保护自定义配置、规格、任务和计划。
+- 在已有项目里保护自定义配置、项目自有规格、任务和计划。
 
 cowork-flow 不绑定技术栈，也不会用脚手架改写现有项目。它只在项目中加入一层协作约定和配套文件。
 
@@ -50,16 +50,18 @@ cwf project init --host codex --developer alice --dry-run
 确认无误后去掉 `--dry-run`：
 
 ```bash
-cwf project init --host codex --developer alice
+cwf project init --host codex --developer alice --language en-US
 ```
 
+不传 `--language` 时默认 `zh-CN`；交互终端会询问，非交互环境使用默认值。该选择写入 `.cowork-flow/config.yaml`，只影响任务和计划产物（`.cowork-flow/spec/contracts/decision-anchor.md` 与 `.cowork-flow/templates/plan-template.md`）。
+
 把 `codex` 换成你正在使用的宿主：
 
 `codex`、`claude-code`、`opencode`、`zcode`、`qoder`、`kimi-code`、`dsh`。
 
 命令默认在当前目录初始化；新项目把目标目录作为位置参数传入，例如 `cwf project init ./my-project --host codex`，再进入该目录。省略 `--host` 时，会先按项目里已有的宿主标记（如 `.codex/`、`.claude/`）自动判定；没有标记的交互终端会让你选择，非交互环境则需要显式传入。只有确实会在多个宿主中使用时，才用 `--host all`。
 
-初始化会加入 `AGENTS.md`、`.cowork-flow/` 和对应的宿主文件，不会修改业务代码。已有 `.developer` 不会被覆盖；首次初始化时显式 `--developer` 优先于 `git config user.name`。git 也没有身份时，交互终端会提示，非交互环境报错（`--dry-run` 只报告 `would-skip`，不失败）。`--platform` / `--platforms` 是 `--host` 的兼容别名。已有项目建议始终先跑 `--dry-run`。
+初始化会加入 `AGENTS.md`、`.cowork-flow/` 和对应的宿主文件，不会修改业务代码。已有 `.developer` 不会被覆盖；首次初始化时显式 `--developer` 优先于 `git config user.name`。git 也没有身份时，交互终端会提示，非交互环境报错（`--dry-run` 只报告 `would-skip`，不失败）。`--platform` / `--platforms` 是 `--host` 的兼容别名。已有 `.cowork-flow/config.yaml` 时其中的 `language` 优先，`--force` 也不会重写它；要切换语言请直接编辑该文件后运行 `cwf project sync .`。已有项目建议始终先跑 `--dry-run`。
 
 ### 3. 完成宿主设置
 
@@ -98,7 +100,7 @@ cwf project sync . --dry-run
 cwf project sync .
 ```
 
-`project sync` 只更新 cowork-flow 管理的文件。已有配置、`spec/`、任务和计划默认保留；**正式版旧资产清理** 会按发布清单删除已废弃的 cowork-flow 文件，不触碰其它内容。机器级宿主组件的升级方式见 [宿主接入](docs/hosts.md)。
+`project sync` 只更新 cowork-flow 管理的文件。已有配置、`spec/backend|frontend|guides|references`、任务和计划默认保留；框架维护的 `spec/contracts|runtime|schemas` 与 `spec/index.md` 随 sync 更新。`.cowork-flow/config.yaml` 是项目配置，`sync --force` 也不会覆盖它。sync 会读取其中的 `language`，只分发对应语言的 `decision-anchor.md` 合同与 `.cowork-flow/templates/plan-template.md`；任务和计划默认跟随该语言，用户明确要求时可以覆盖。**正式版旧资产清理** 会按发布清单删除已废弃的 cowork-flow 文件，不触碰其它内容。机器级宿主组件的升级方式见 [宿主接入](docs/hosts.md)。
 
 ## 遇到问题
 
@@ -117,7 +119,7 @@ cwf project sync .
 
 | 命令 | 用途 |
 |---|---|
-| `cwf project init [target] --host <host> [--developer <name>] [--dry-run] [--force]` | 初始化项目 |
+| `cwf project init [target] --host <host> [--developer <name>] [--language zh-CN|en-US] [--dry-run] [--force]` | 初始化项目 |
 | `cwf project sync [target] [--dry-run] [--force]` | 更新项目内由 cowork-flow 管理的文件 |
 | `cwf host add <host> [--component <name>] [--dry-run] [--force] [--prune-old] [--uninstall]` | 安装机器级宿主组件 |
 | `cwf host remove <host> [--component <name>] [--dry-run] [--force]` | 卸载机器级宿主组件 |
@@ -152,6 +154,7 @@ cwf project sync .
 | [架构与扩展](docs/architecture.md) | 项目文件如何组织、同步策略与受保护文件 |
 | [宿主接入](docs/hosts.md) | 各宿主的安装、重启、排障和卸载方式 |
 | [发布与维护](docs/release.md) | 测试、CI 和维护者命令 |
+| [方向规划](docs/direction.md) | 项目定位、已定取舍、版本主线与待决项 |
 | [参与开发](CONTRIBUTING.md) | 本地开发、提交和 PR 检查 |
 | [更新日志](CHANGELOG.md) | 版本变化 |
 

package/docs/architecture.en.md

@@ -0,0 +1,95 @@
+# Architecture and extension
+
+[中文](architecture.md) | English
+
+This document is for developers maintaining cowork-flow. It explains how the project files are layered, where host differences live, and which boundaries to respect when adding capabilities. If you only want to install and use cowork-flow, see [README](../README.en.md); to troubleshoot a specific host, see [Host integration](hosts.en.md).
+
+## Three boundaries to remember first
+
+1. `template/` only holds files that get written into a user project.
+2. `presets/` only holds machine-level payloads that `cwf host add` installs into host configuration directories.
+3. Host differences are declared by `template/.cowork-flow/spec/runtime/host-assets.json` and are not written into the shared runtime.
+
+## Repository responsibilities
+
+| Location | Responsibility |
+|---|---|
+| `template/` | The single distribution source for `project init` and `project sync` |
+| `presets/` | Payload source for plugins, presets, and machine-level hooks |
+| `src/` | Node CLI: command registration, installers, and file sync plans |
+| `scripts/` | Build, test, packaging, and release scripts |
+| `test/` | Node tests and helper modules |
+| `tests/` | Python repository tests and fixtures |
+| `docs/` | User, host, architecture, and maintenance documentation |
+| `.agents/`, `.claude/`, `.codex/`, `.cowork-flow/` | Runtime copies for this source repository; not a distribution source |
+
+### Project distribution source
+
+The content in `template/` that directly relates to a user project includes:
+
+- `AGENTS.md`: the project collaboration entry point.
+- `template/skills/`: the single source for project Skills, distributed per host by `init` / `sync`.
+- `template/.cowork-flow/`: project configuration, the Python runtime, specs, plans, and tasks.
+- `template/.<host>/`: host configuration, hooks, or agents that must be stored with the project.
+
+`cwf project init` / `cwf project sync` must not read content from the source repository's runtime copies.
+
+### Machine-level payloads
+
+`presets/` stores host components that do not belong to a single project:
+
+- Codex, Claude Code, OpenCode, ZCode, Qoder, and Kimi Code plugins.
+- DeepSeek Harness presets and hooks.
+- Plugin branding assets and bootstrap Skills.
+
+Machine-level installers may write into host configuration directories only through `cwf host add` / `cwf host remove`, and must not hard-code user home directory paths into `template/`.
+
+## Runtime layers
+
+Runtime code lives in `template/.cowork-flow/scripts/`. The repository root `scripts/` only handles building and releasing.
+
+| Layer | Location | Responsibility |
+|---|---|---|
+| Command adapters | `scripts/adapters/cli/` | Argument parsing, command output, and CLI exit codes |
+| Task services | `scripts/services/` | Task creation, lifecycle, archiving, context, and the task tree |
+| State storage | `scripts/infra/storage/` | UTF-8 reads and writes, revision checks, operation logs, and recoverable transactions |
+| Host adapters | `scripts/adapters/host/` | Host input, policy differences, and state injection |
+| Shared hook core | `scripts/adapters/host/workflow_state_hook.py` | Workflow state parsing shared by all hosts |
+| Host declarations | `spec/runtime/host-assets.json` | Platforms, assets, sync policy, Skill roots, and the migration manifest |
+
+The workflow kernel keeps a narrow responsibility: the kernel only resolves state facts and actions, Skill ownership is injected by the manifest loader, and hard gates are enforced by the runtime gate. The repository no longer maintains a second workflow hub or a separate Skill registration control plane.
+
+Scripts needed by an individual Skill live in `template/skills/<skill-id>/scripts/` and do not enter the runtime kernel.
+
+## init and sync
+
+Installers and the synchronizer do not read and write incrementally; they execute in the following order:
+
+1. Read the Host Asset Manifest and the sync policy.
+2. Build an immutable Asset Plan.
+3. Stage on the same file system, and verify file hashes and permissions.
+4. Commit according to the backup manifest; on failure, roll back in reverse order.
+5. Update `.cowork-flow/.version` last.
+
+`config.yaml`, `.developer`, specs, tasks, and plans are protected by the sync policy. `--force` widens the overwrite range, but `.cowork-flow/config.yaml` is in `forceProtectedFiles`: once created, neither `init --force` nor `sync --force` overwrites it. For an existing project, run with `--dry-run` first to see the changes.
+
+The installation language is written to `language` in `config.yaml` (`zh-CN` by default, or `en-US`). The `localization` field of the Host Asset Manifest declares which assets have language variants; their source files live under `template/locales/<language>/<canonical-path>`. `init`, `sync`, and `dev refresh` choose the source file through `localizedSource()`, while the target path is always the canonical path, and `locales/` is excluded by `excludedPrefixes` so it never enters the project. Currently only `spec/contracts/decision-anchor.md` and `.cowork-flow/templates/plan-template.md` are localized: the former sets the heading language of a new anchor, the latter sets the language of plan artifacts, and parsers always accept both Chinese and English headings.
+
+`.cowork-flow/spec/` splits its sync policy by ownership. Framework-maintained `spec/contracts/`, `spec/runtime/`, `spec/schemas/`, and `spec/index.md` follow `sync`: contract errata, `contract-registry.json`, `host-assets.json`, `scope-rules.json`, and schemas therefore reach installed projects in the same generation as the scripts, and obsolete framework spec files registered in `obsoleteFiles` are deleted as well. Project-maintained `spec/backend/`, `spec/frontend/`, `spec/guides/`, and `spec/references/` stay protected, and a normal `sync` never overwrites or deletes files there. The cost is that a project which has locally modified a framework contract or `scope-rules.json` loses those changes on the next `sync`; customizations worth keeping should go into the four project directories, `AGENTS.md`, `config.yaml`, or a project-owned Skill.
+
+## Extension rules
+
+- Host specializations may live only in `spec/runtime/host-assets.json`, `scripts/adapters/`, `template/.<host>/`, or an explicit host command module.
+- Plugins provide only fields the host actually supports; do not copy unknown or invalid keys.
+- Project Skills are distributed only from `template/skills/`; machine-level payloads do not copy a project Skill with the same name.
+- Shared planning and copy modules in `scripts/services|runtime|infra` and `src/lib/` must not contain host branches.
+- For a new host, update the Host Asset Manifest and schema first, then add the installer, doctor support, and tests; do not write a separate host list in several files.
+- Write project differences into `AGENTS.md`, `config.yaml`, `spec/backend|frontend|guides|references`, or a project-owned Skill, and do not bring back a second set of workflow documents.
+- When changing a Skill distribution path, update `skillReadRoot`, `skillDiscovery`, and the corresponding host evidence together.
+- When changing a command name, update the command registry, README, doctor hints, Skills, and related tests in one pass.
+
+## Tests and bytecode
+
+Tests and Skill scripts must not leave `__pycache__` or `*.pyc` under `template/` or `presets/`. Node tests redirect the cache through `test/helpers/bytecode-isolation.js`; Skill scripts disable bytecode writing through `runtime_pythonpath_env(cache_bytecode=False)`. `tests/test_no_legacy_template_paths.py` guards this boundary.
+
+`node --test` loads every `.js` file under `test/`, so helper modules must also be free of side effects; on the Python side, tests are collected according to the default discovery rules of pytest or unittest.

package/docs/architecture.md

@@ -1,5 +1,7 @@
 # 架构与扩展
 
+[English](architecture.en.md) | 中文
+
 本文面向维护 cowork-flow 的开发者，说明项目文件如何分层、宿主差异放在哪里，以及新增能力时应遵守的边界。只想安装和使用时，看 [README](../README.md)；排查某个宿主时看 [宿主接入](hosts.md)。
 
 ## 先记住三条边界
@@ -69,9 +71,11 @@
 4. 按备份清单提交；失败时逆序回滚。
 5. 最后更新 `.cowork-flow/.version`。
 
-`config.yaml`、`.developer`、规范、任务和计划按同步策略保护。`--force` 会扩大覆盖范围，因此已有项目应先用 `--dry-run` 查看变更。
+`config.yaml`、`.developer`、规范、任务和计划按同步策略保护。`--force` 会扩大覆盖范围，但 `.cowork-flow/config.yaml` 是 `forceProtectedFiles`：首次创建后 `init --force` 和 `sync --force` 都不再覆盖它。已有项目应先用 `--dry-run` 查看变更。
+
+安装语言写在 `config.yaml` 的 `language`（`zh-CN` 默认，或 `en-US`）。Host Asset Manifest 的 `localization` 声明哪些资产存在语言变体，源文件位于 `template/locales/<language>/<canonical-path>`；`init`、`sync` 与 `dev refresh` 通过 `localizedSource()` 选择源文件，目标路径始终是 canonical path，`locales/` 被 `excludedPrefixes` 排除，不会进入项目。当前只有 `spec/contracts/decision-anchor.md` 与 `.cowork-flow/templates/plan-template.md` 本地化；前者决定新 anchor 的标题语言，后者决定计划产物语言，解析器始终同时接受中英两套标题。
 
-`.cowork-flow/spec/` 前缀整体受同步保护：既有项目里的规范文件不会被 `sync` 覆盖，模板侧的规范更新只对全新 `init` 生效。具名例外是 `spec/runtime/host-assets.json` 中 `syncPolicy.safeFiles` 列出的文件——`spec/contracts/workflow-state-templates.md` 与 `spec/runtime/scope-rules.json`——它们随 `sync` 更新，使契约勘误与预算默认值能到达已装项目；代价是本地调过 `scope-rules.json` 的项目会在下一次 `sync` 丢掉这些改动。
+`.cowork-flow/spec/` 按归属拆分同步策略。框架维护的 `spec/contracts/`、`spec/runtime/`、`spec/schemas/` 与 `spec/index.md` 随 `sync` 更新：契约勘误、`contract-registry.json`、`host-assets.json`、`scope-rules.json` 和 schema 因此能与脚本同代际到达已装项目，`obsoleteFiles` 中登记的过期框架 spec 文件也会被删除。项目维护的 `spec/backend/`、`spec/frontend/`、`spec/guides/`、`spec/references/` 保持保护，普通 `sync` 不会覆盖或删除其中的文件。代价是本地修改过框架契约或 `scope-rules.json` 的项目会在下一次 `sync` 丢掉这些改动；需要保留的定制应写入四个项目目录、`AGENTS.md`、`config.yaml` 或项目自有 Skill。
 
 ## 扩展规则
 
@@ -80,7 +84,7 @@
 - 项目技能只由 `template/skills/` 分发；机器级载荷不复制同名项目技能。
 - `scripts/services|runtime|infra` 和 `src/lib/` 的通用计划、拷贝模块不能出现宿主分支。
 - 新宿主先更新 Host Asset Manifest 与 schema，再补安装器、doctor 和测试；不要在多个文件各写一份宿主清单。
-- 项目差异写入 `AGENTS.md`、`config.yaml`、`spec/` 或项目自有 Skill，不恢复第二套流程文档。
+- 项目差异写入 `AGENTS.md`、`config.yaml`、`spec/backend|frontend|guides|references` 或项目自有 Skill，不恢复第二套流程文档。
 - 修改 Skill 分发路径时，同时更新 `skillReadRoot`、`skillDiscovery` 和对应宿主证据。
 - 修改命令名时，一次更新命令注册表、README、doctor 提示、Skill 和相关测试。
 

package/docs/direction.en.md

@@ -0,0 +1,71 @@
+# cowork-flow direction: agent runtime context and the collaboration fact layer
+
+[中文](direction.md) | English
+
+> Status: **approved** · Created: 2026-08-27 · Last updated: 2026-10-19
+> This document is the authoritative input for starting later phases. Any revision to the direction must update this document first, then start the phase.
+> Implementation details and commit history for completed phases are in the [CHANGELOG](../CHANGELOG.md) (Chinese); this document keeps only the positioning, trade-offs, boundaries, and open items that still hold.
+
+---
+
+## 1. Positioning
+
+> **cowork-flow does not constrain how a model thinks; it guarantees that any agent on any host starts from the same authoritative facts, in any session, at any moment.**
+
+| | Previous positioning | New positioning |
+|---|---|---|
+| Narrative | Help you build a process (process templates) | Runtime context and collaboration fact layer |
+| Means | Task flows, gates, spec documents | State injection, fact consistency, cross-host governance |
+| Purpose | Make collaboration "follow the rules" | Make collaboration "start from the correct state" |
+| When model capability rises | Constraint-type value decreases (models follow the rules on their own) | Fact-type value increases (state is something a model cannot invent) |
+
+The test: a project's consumer is an agent, not a person. So injection formats, fact output, and contracts always follow "machine-parseable first, human-readable as a fallback".
+
+## 2. Settled trade-offs
+
+- **Injection format: option A (structured fact header + human-readable summary body, with graded degradation)** — structured first; when the channel does not allow it, degrade to attribute lines or a plain summary.
+  - Rejected "all-JSON injection": the plain-text channels of dsh / codex waste tokens and break the readability of compact prose breadcrumbs.
+  - Rejected "keep text and only add a `--json` output": the core value proposition would not land in injection itself.
+- **Fact-layer output**: the CLI + JSON protocol comes first (zero dependencies); MCP follows as a thin adapter.
+- **Three-line convergence**: start with "a single protocol spec + three lines implemented against the spec"; code-level sharing is left for later (high cost, and the benefit has already been delivered through protocol consistency).
+
+## 3. What we explicitly do not do
+
+1. No "smarter prompts / AGENTS.md writing craft" — model capability will catch up, and that leaves no data assets.
+2. No home-grown cross-agent communication standard — this is a period of protocol competition; wait for the ecosystem to converge.
+3. No task execution engine — not a substitute for the agent doing the work, only a guarantee that it starts from the correct state.
+4. No deeper process-only gates — keep them as a safety net and stop investing.
+
+## 4. Rejected candidates
+
+| Candidate | Why it was rejected |
+|---|---|
+| AgentOps / observability | No runtime telemetry assets; building from scratch means switching lanes and breaks with the workflow-engine positioning |
+| Task orchestration engine | Overlaps with the orchestration hosts already provide; turning the state model into a distributed system explodes complexity |
+| Pure governance and compliance layer | The value of pure gates decreases as models become more self-directed; no differentiation |
+| ✅ Fact layer + injection | The repository's thickest assets all live here; cross-host consistency is a structural difference no single-host tool can provide |
+
+## 5. Version line
+
+- **1.8.x released**: evidence-based completion (ACs as facts, `evidence.jsonl`, completion gates).
+- **1.9.x released**: collaboration facts for multiple executors — visible board ownership, dependency edges, handoff records.
+- **2.0.0 released**: the spec-check mechanism removed in a breaking change, edit-time out-of-scope warnings on every host, and relaxed injection capacity (Verify 10 items / block budget 3400). See the `[2.0.0]` section of the [CHANGELOG](../CHANGELOG.md) (Chinese).
+- Per-version delivery details always follow the CHANGELOG; this document does not repeat them.
+
+## 6. Open items and deferred work
+
+- **Settled (2026-10-21): detailed documentation stays Chinese; the README stays bilingual.** The English community is the main venue for spec-driven development discussion, but the detailed documentation is currently about 590 lines and ships in the npm package as plain Markdown, so full bilingual coverage would introduce translation drift and documentation-framework cost. Decision: `docs/`, `template/AGENTS.md`, and `CHANGELOG.md` stay Chinese; `README.md` / `README.en.md` are kept in sync in both languages; no VuePress/mkdocs or directory-based bilingual setup is introduced.
+  - **2026-10-22 (step three): English demand confirmed, and `docs/` gains parallel `docs/*.en.md` files.** Five documents (index, architecture, hosts, release, direction) each gain an English version, the Chinese and English pages link to each other at the top, and everything still ships in the npm package as plain Markdown. Translation drift is held down by the pairing and heading-structure gates in `test/docs.test.js`: a missing English file, inconsistent heading levels, or a missing counterpart link all fail.
+  - 2026-10-13 clarification: "documentation language: Chinese" constrains the language of **documents produced** while working in a downstream host; it does not require translating the product payloads shipped with the package (`template/skills/`, `template/.cowork-flow/spec/contracts/`, `presets/`) into Chinese.
+  - 2026-10-21 (step one): the framework spec documentation shipped with the package is unified in English — `spec/index.md`, `spec/runtime/index.md`, `spec/schemas/index.md`, `spec/references/**`. The six parsed headings in `decision-anchor.md`, the injection block in `workflow-state-templates.md`, `backend/frontend/guides`, and `template/AGENTS.md` stay Chinese.
+  - 2026-10-22 (step two): installation can choose `zh-CN` / `en-US`, written to the protected `.cowork-flow/config.yaml` and affecting only `decision-anchor.md` and plan artifacts. The parser permanently accepts both the Chinese and English heading sets; `decision-anchor.md` keeps the Chinese contract and adds an English variant, while `workflow-state-templates.md`, `AGENTS.md`, spec documents, and Skills are not localized by that option. `references/` is still protected by project sync, so an installed project needs a manual refresh to receive the English copies.
+- **Still deferred**: MCP write tools (the `fact-layer-access` contract must be reopened first), new host integrations, and a home-grown cross-agent protocol.
+- **Watch item (trigger reached)**: machine-parseable ACs are the first building block for interoperability with Spec Kit / OpenSpec (spec artifacts ↔ decision-anchor mapping), and fit the "state layer beneath SDD tools" positioning. It was originally "to be discussed once the agent-teams schedule is settled"; since the 1.9.0 multi-executor collaboration mainline is already implemented, it can be put on the discussion schedule.
+
+## 7. Metrics
+
+1. **Cross-host behavioral consistency**: fingerprints and slim triggers on each host are asserted by tests, with 0 drift.
+2. **Cost of integrating a new host**: from days down to hours (a direct measure of protocol-spec completeness).
+3. **Injection token cost**: injected volume in long sessions does not grow linearly with the number of messages.
+4. **Fact freshness incidents**: multi-session task contamination / stomping incidents trend toward zero.
+5. **Adoption**: weekly npm downloads and the number of activated projects — using numbers to verify whether the "deep route" delivers.

package/docs/direction.md

@@ -1,5 +1,7 @@
 # cowork-flow 方向规划：Agent 运行时上下文与协作事实层
 
+[English](direction.en.md) | 中文
+
 > 状态：**已批准** · 创建：2026-08-27 · 最近更新：2026-10-19
 > 本文档是后续阶段立项的权威输入。任何方向的修订必须先更新本文档，再立项。
 > 已完成阶段的实施细节与提交记录见 [CHANGELOG](../CHANGELOG.md)；本文只保留仍然生效的定位、取舍、边界和待决项。
@@ -52,8 +54,11 @@
 
 ## 6. 待决项与缓行
 
-- **已拍板（2026-10-21）：详细文档维持中文，README 保持中英双语。** 英文社区是 spec-driven development 讨论的主场，但当前详细文档约 590 行、随 npm 以纯 Markdown 发布，全量双语会引入翻译漂移与文档框架成本。决定：`docs/`、`template/AGENTS.md`、`CHANGELOG.md` 维持中文；`README.md` / `README.en.md` 双语同步；不引入 VuePress/mkdocs 或目录式双语。未来若英文需求被证实，采用并列 `docs/*.en.md`，只覆盖安装面文档，并新增“英文文件与中文源文件标题集合一致”的漂移门禁后再落地。
+- **已拍板（2026-10-21）：详细文档维持中文，README 保持中英双语。** 英文社区是 spec-driven development 讨论的主场，但当前详细文档约 590 行、随 npm 以纯 Markdown 发布，全量双语会引入翻译漂移与文档框架成本。决定：`docs/`、`template/AGENTS.md`、`CHANGELOG.md` 维持中文；`README.md` / `README.en.md` 双语同步；不引入 VuePress/mkdocs 或目录式双语。
+  - **2026-10-22（第三步）：英文需求被证实，`docs/` 并入并列 `docs/*.en.md`。** 五份文档（index、architecture、hosts、release、direction）各新增英文版，中英页面顶部互链，仍随 npm 以纯 Markdown 发布。翻译漂移由 `test/docs.test.js` 的成对与标题结构门禁守住：英文文件缺失、标题层级不一致或互链缺失都会失败。
   - 2026-10-13 澄清：「文档语言：中文」约束的是下游宿主工作时**产出文档**的语言，不要求把随包分发的产品载荷（`template/skills/`、`template/.cowork-flow/spec/contracts/`、`presets/`）翻译成中文。
+  - 2026-10-21（第一步）：随包分发的框架 spec 说明文档统一为英文——`spec/index.md`、`spec/runtime/index.md`、`spec/schemas/index.md`、`spec/references/**`。`decision-anchor.md` 的六个解析标题、`workflow-state-templates.md` 的注入块、`backend/frontend/guides` 与 `template/AGENTS.md` 仍为中文。
+  - 2026-10-22（第二步）：安装时可选择 `zh-CN` / `en-US`，写入受保护的 `.cowork-flow/config.yaml`，只影响 `decision-anchor.md` 与计划产物。解析器永久接受中英两套标题；`decision-anchor.md` 保留中文合同并新增英文变体，`workflow-state-templates.md`、`AGENTS.md`、spec 文档与 Skill 不随该选项本地化。`references/` 仍受项目同步保护，已装项目需手动刷新才能拿到英文副本。
 - **维持缓行**：MCP 写工具（须先重开 `fact-layer-access` 契约）、新宿主接入、自创跨 agent 协议。
 - **观察项（触发条件已到）**：机器可解析 AC 是与 Spec Kit / OpenSpec 互操作的第一块砖（spec 制品 ↔ decision-anchor 映射），符合「SDD 工具之下的状态层」定位。原定「待 agent-teams 排期落定后议」，而 1.9.0 多执行者协作主线已实现，可排入讨论。