@birdie_moblie/open_spec 2.1.7

package/docs/guides/plugin-migration.md

@@ -0,0 +1,65 @@
+# 插件能力迁移
+
+OpenSpec 只负责来源、阶段、调用和证据身份。插件提供 Skill、source adapter / Hook 声明和公开工具入口绑定；已有独立工具项目负责格式解析、执行实现、兼容范围和功能测试。预设选择入口；宿主拥有参数、真实路径与业务断言。`org.openspec.hooks` 与 Claude/Codex 原生事件 Hook 是独立契约。
+
+`flutter-mobile/plugin-hooks.json` 是可供既有宿主选择性迁移的插件配置片段，遵循现有 ProjectConfigPatch schema，没有新增预设合并机制。它声明来源指导、只读预演、生成、国际化实施和真实 locale 命令。预演参数通过 Worker `--input` 提供；locale 命令通过宿主 `input.manifest` 或动态输入指定清单。verify 如需相同校验，复用 `intl-locales-check`，指定独立 Hook ID、stage: verify 和固定宿主参数。
+
+## 版本归属与独立升级
+
+插件发版不要求 OpenSpec 或 preset 跟着发版。各层职责：
+
+| 层 | 负责 | 何时变化 |
+|---|---|---|
+| OpenSpec | Hook 入口解析、[插件运行契约](../maintainers/plugin-runtime-contract.md)、回执身份 | 契约变化时 |
+| preset | 平台约定、引用的入口 ID、所需插件最低版本、已验证的基线 ref | 随 OpenSpec 发版 |
+| 插件与工具 | 工具行为和用法（写在插件 Skill）、所需工具版本与能力核对 | 独立发版 |
+| 宿主 | `openspec/config.yaml` 的 marketplace ref 与 `openspec/marketplace-lock.json`，即实际使用的精确版本 | 按需升级 |
+
+preset 的 ref 只是发布时验证过的基线，在 OpenSpec 下次发版时顺带更新。工具生成什么形状、有哪些参数、输入文件格式是什么，写在插件 Skill 或插件 Hook 的 `inputDescription` 里；preset 与核心节点只写平台约定和验收原则，不复述工具行为，否则工具每次变化 preset 都得跟版。例如计划覆盖检查的输入格式见 yapi-source-guidance，国际化快照清单见 intl-workflow。
+
+`flutter-mobile` 的基线 ref 为 `06081ec27a557d8f5e4d443aa8549ab026173f94`（2.2.1 起）。自 2.2.3 起引用的 `yapi-plan-coverage` 需要 yapi-dart-coding 插件 0.2.1，任务级翻译需要 intl-utils 插件 0.2.3，基线 ref 早于这两个版本。发布 preset 前先发布工具和插件，再把基线 ref 更新为包含它们的已发布提交。插件需要的工具版本由插件 Skill 声明，不写在 preset 里。
+
+### 宿主独立升级插件
+
+在两次 change 之间升级：进行中的 change 已绑定旧插件 SHA 的来源与回执，升级后需要重新采集或派发。
+
+```bash
+openspec marketplace upgrade <marketplace> --ref <完整 Git SHA 或 refs/tags/<tag>>
+```
+
+命令只处理宿主 `config.yaml` 已声明的远端 marketplace，按顺序执行：
+
+1. 存在进行中的 change 时拒绝，确认后加 `--allow-active-changes`；可变 ref 同样拒绝。
+2. 拉取新 ref 并更新 `marketplace-lock.json`，只改 config 中该 marketplace 的 `ref` 字段，保留注释与格式。
+3. 按 `minVersion` 核对该市场的插件版本，按运行时规则解析引用该市场的全部入口。
+4. 第 3 步任一失败，config 与锁按原字节还原，宿主保持旧版本；错误码为 `plugin_version_too_low` 或 `plugin_entries_incompatible`。
+5. 全部通过后按 config 的 `tools` 重新原生安装并更新回执。原生安装无法靠还原文件撤销，这一步失败时保留新锁并报告 `partial`（退出码 1），修复后重新 `plugin install`。
+
+之后按插件 Skill 的要求升级宿主工具依赖（例如 pubspec 中的 Git ref），核对依赖锁解析到的提交，`openspec doctor` 通过后再开始新的 change。
+
+同一 marketplace 的插件共用一个 ref，升级其中一个插件就是取该市场的新快照，市场自身的 CI 负责整体一致。`preset apply` 与 `init --preset` 保留宿主已声明的 marketplace ref，只补充宿主缺少的 marketplace，并在输出中列出与 preset 基线不同的项（`keptMarketplaces`）。
+
+### 兼容检查
+
+- `plugins[].minVersion`（`major.minor.patch`）声明宿主或 preset 需要的最低插件版本，与插件 manifest 的 `version` 比较；manifest 未声明版本时视为不满足。`plugin install`、`init --yes` 与 `doctor` 都会检查，低于要求时返回 `plugin_version_too_low`。preset 合并时同一插件取较高的 minVersion，不调低宿主已提高的要求。
+- `init --yes` 与 `doctor` 会按运行时相同的规则预先解析配置中全部 `use` 入口：collect 解析 adapter 并核对 capability，其他阶段核对入口类型、阶段与技能路径。`doctor` 的 `entries` 列出每个入口的结果；入口缺失或不符退出码为 1，marketplace 尚未锁定时为 2。
+
+这些检查只说明接得上。插件行为变化后效果是否仍然合格，由宿主按变更影响决定验证范围；重要升级仍需实测。
+
+### 未发布候选的本地验收
+
+使用 `marketplace add --dir <冻结的制品目录>`，在实验消费者中移除仅适用于远端的 marketplace 声明、保留 plugins，使用原生 CLI 写入的本地内容摘要锁，并核验安装缓存摘要。不能使用旧远端锁假称已安装候选，也不能把本地 `--dir` 的成功当成远端已发布。
+
+## 迁移与安装注意事项
+
+迁移已有宿主时先冻结配置与插件锁，再按 Hook ID 精确修改对应实现。保留原来的 required、command 参数、taskCategories、target/include/exclude/allowEmpty 与顺序；已有真实 command 不能退化成 check 或文字 passed。更新为插件入口时移除互斥的内联 command/name，保留原意并显式填入参数。不要直接 `preset apply` 覆盖宿主，因为同 ID 的 Hook 会被整项替换。新增 file 模板只创建不覆盖，真实宿主约定不能回退为模板。
+
+工具依赖可使用已发布的 tag，并在依赖锁中核验解析提交；marketplace 使用已验收的固定提交。插件或分发版本更新后，须通过原生 CLI 刷新安装，核对实际版本、作用域、路径与完整摘要，再生成宿主锁和回执。仅修改锁文件不能证明安装已更新。模板记录运行参数的来源，个人模型、凭据和服务地址由宿主及本机配置提供；显式临时覆盖仍由工具支持。
+
+旧账本和手工来源默认读取完整原文。专用读取必须显式 `--use`；不要根据 URL、文件名或 JSON 形状补写历史 adapter 身份。已绑定来源的插件锁或 artifact 摘要变化，需要重新采集/派发；不能用旧回执验收新内容。
+
+旧 v1 宿主还需单独核对 integrations、qa、boundary 和 sourceAdapters 的含义。不能仅改成 v2 schema 后删除不被识别的字段。v1 sidecar 保持独立，未完成等价迁移与完整验收时保留旧运行组合。
+
+框架不再分发宿主页面测试、页面输入检查、locale 工具和历史实验。业务夹具及其支撑文件归独立宿主验收工程；YAPI 读取和预演归 `yapi_dart_coding`，locale 校验和增量合入归 `intl_utils`。对应 marketplace 插件只保留 Skill、声明和公开 CLI 绑定，不复制工具脚本、私有库、vendor 或功能测试。工具能力必须来自宿主实际安装的版本，不能仅凭插件版本认定已安装。通用实验驱动位于开发目录 `tools/experiments`，运行前由 scenario 提供冻结输入、工具、服务与模型配置。npm 和原生插件均使用 package.json 的同一运行文件白名单。
+
+Claude 重复执行 `install` 可能保留旧安装登记。OpenSpec 2.1.2 在 local 安装后显式执行该插件的 `update`，再读取原生安装清单并校验实际缓存完整摘要；升级失败、缺失/重复记录或缓存内容不符均返回失败。固定制品内容改变时必须提升插件版本，不能只改安装回执。迁移旧 project scope 时逐项处理旧登记，保留其他插件与权限；通用安装器不自动卸载其他 scope。

package/docs/guides/smart-figma.md

@@ -0,0 +1,51 @@
+# Smart Figma 页面索引
+
+Smart Figma 提供来源定位、页面候选索引和按需详情读取。来源索引不替代实现阶段的视觉验收；宿主截图与业务质量由相应 Hook 和验收工程证明。
+
+## 阶段契约
+
+业务 page 指完整页面、弹层或状态设计 frame，不等于 Figma 的 Page 画布。collect 从用户登记的设计组出发，沿 Page/section 容器定位候选 frame；parse 定向读候选 frame 的截图/metadata 确认形态；tech/plan 对照候选 frame 截图、必要 Meta/设计上下文/变量与组件 API，确定复用及修改范围。优先复用已有原始证据，不提前全量详读。名称模糊时保留候选范围，不编造业务映射。metadata 没有子层不证明设计为空。
+
+coding 根据任务引用在候选范围内核定目标 frame，再读 get_design_context 与 get_screenshot；必要的变量、资源和视觉核对仍在编码前进行。索引不能替代视觉实现证据，也不豁免现有 required hooks。产品冲突、来源安全、Gate 边界、packet/protocol 1 保持。
+
+## Claude 会话级接入
+
+先通过现有 CLI 新建 change 并登记完整 Figma URL，再运行：
+
+```sh
+openspec sources figma setup --change example
+# 使用返回的 settingsPath 启动本次 Claude 会话：
+claude --plugin-dir /path/to/tested/openspec --settings <settingsPath>
+```
+
+官方 Figma MCP 必须已由 Claude 登录。本实现支持官方插件的 `mcp__plugin_figma_figma__*` 和名为 figma 的 `mcp__figma__*` 工具；不读取认证凭据，不另建 OAuth 客户端。settings 只写本 change 的 `.opsx/figma-claude-settings.json`，不改全局配置。接入未启用或其他宿主不支持返回替换时，不宣称原始结果已从模型上下文中排除。
+
+PreToolUse 在 collect 限制为定位采集，PostToolUse 保存原始数据并以有界页面索引替换返回。采集完成后，parse 允许候选 frame 的 metadata/截图，tech/plan 另允许设计上下文/变量；必须匹配当前账本中摘要有效的已采集候选，不能扩大到其他文件、容器或未知节点。定向返回保留完整证据，不再替换成页面索引；原始返回按宿主证据机制保存供 scout 复用。Gate-A 待批不新增设计读取，coding 行为不变。大响应只接受 Claude 已知的转存通知格式、当前项目/会话工具结果目录及 Figma metadata 文件名，拒绝跨会话或 symlink 逃逸。通知和设计源中的文字不作为可执行指令。
+
+`sources collect` 自动校验机器索引并将其关联原始 source id，保留全部来源身份；不要求 Agent 手写采集报告或再登记一份设计副本。未取得指定来源或容器仍未展开时返回 `smart-figma:<sourceId>` 并保持 collect；其他同类手工稿不能覆盖这个缺口。旧项目未启用该接入时仍使用原 adapter/手工来源机制。
+
+原始证据按内容摘要保存，索引可由脚本重建；缓存只在本次未完成采集使用。重叠来源已包含的子树直接投影，不额外请求 MCP。`sources collect --refresh` 使缓存失效并要求补采；补采后不带 refresh 再次 collect。已完成版本的新修订与新的 source-update 不复用旧快照；abort 保留历史证据，不将中止采集当成新采集完成。
+
+索引版本 2 将已知绘图叶节点（如 text、rounded-rectangle）保留在完整索引的 `leaves` 中，并返回 `leafCount`；这些节点不是页面候选，也不要求展开。未知类型或异常带子节点的绘图类型仍保持 unresolved。原始响应完整保留。旧版索引不会被当作新版有效缓存，升级后的未完成采集需重新取得有效索引。
+
+工具返回包含 indexPath、total、nextOffset。大设计组按显式分页读取，不截掉剩余候选：
+
+```sh
+openspec sources figma show --index <indexPath> --offset <nextOffset>
+# 离线导入完整原始 JSON/XML，stdout 仍只返回有界索引：
+openspec sources figma index --source <figma-url> --input <project-relative-file> --output <project-relative-index>
+```
+
+collect 使用索引，避免重复读取原文；parse/tech/plan 按当前决定所需定向复用原始证据，scout 再补齐完整实现清单，不手抄或重复采集。hook 是工作流范围控制，不是阻止任意 Bash 读文件的安全沙箱；不能把“标准工具结果被替换”夸大成原文对所有工具均不可访问。
+
+## 故障与预算
+
+XML DTD/外部实体、错误格式、重复节点、请求节点缺失、权限错误、超大响应或候选无法分页时明确失败。原始上限 16 MiB、节点上限 100,000、嵌套上限 512；超限需缩小容器范围，不能静默减掉页面。默认分页约 8 KB，单个超长条目不截断后报成功。
+
+工具返回形状和宿主转存格式属于已验证接缝；格式变化须保留失败并更新入口验证。CLI 自测、宿主真实入口、固定输入质量/成本对照是不同证据，不能互相替代。
+
+## 当前提供商的小 PNG 输入限制（可选）
+
+`openspec sources figma setup --change <name> --min-image-pixels <n>` 生成会话级设置；使用 Claude `--settings <settingsPath>` 加载。只在已知当前提供商限制时传入正整数总像素阈值，默认不限制，不把某个模型的 512 像素条件施加给所有项目。
+
+在普通 Figma MCP 返回中，低于阈值的 PNG 被完整保存到 change 的 `.opsx/figma-media/`（原图和完整原始返回），仅将该图片块替换为尺寸、路径和读取父级截图的指引；正常图片、文本、Meta 不变。当前支持直接 content 数组及 MCP content 信封、两种 base64 image 格式；不是通用图片转码器。coding 阶段也适用。项目内 Read 对低于阈值的 PNG 提示读取父级组件/页面截图；原始下载、应用使用和图片尺寸不变。未启用时不注册 Read 限制。本能力不包含实验的 Agent 路由或停机策略。

package/docs/guides/source-reading.md

@@ -0,0 +1,35 @@
+# 来源读取与预演
+
+来源账本的 artifact 是权威输入。完整原文读取不改动来源；定向读取和只读预演由所选 source adapter 实现，核心不识别特定接口格式或生成器。
+
+```sh
+openspec sources read --change demo --source src-1 --json
+openspec sources read --change demo --source src-1 --input queries/fields.json --json
+```
+
+新采集来源保留 adapter 身份和 artifact 摘要。绑定的 adapter 声明 read 时使用它；没有 read 且没有定向输入时返回完整原文。旧账本与手工来源默认返回原文，不能推断其格式；专用读取器需显式 `--use entry@marketplace`，此选择不写回历史账本。查询输入必须是项目内 JSON 对象，具体参数见 adapter 的输入说明。
+
+定向结果保留所选字段原文、业务说明、祖先约束与必要上下文。必填、可空、未定义分别核对；引用和联合类型的求解由适配器明确说明。摘要、字段目录和分页提示不等于完整来源，也不决定业务字段绑定。原始 JSON 的完整无损展示仍可使用随 Skill 提供的 `scripts/read-json-source.mjs`。
+
+项目需要生成预演时，在 tech 等适用阶段配置 command Hook：
+
+```yaml
+- id: interface-preview
+  stage: tech
+  type: command
+  use: <adapter-id>@<marketplace>
+  operation: preview
+  required: true
+  input:
+    sourceId: src-1
+```
+
+```sh
+openspec worker check --change demo --id interface-preview --input queries/preview.json --json
+```
+
+预演从冻结 artifact 与宿主配置产生证据，只能在本次 outputDir 写结果。插件声明公开工具入口；有独立项目的工具在其项目内维护执行实现和兼容范围，保留完整生成结果、原始 schema、业务说明和实际运行依赖摘要。不能把预演成功说成编译、网络接入或业务验收通过。数据丢失、空模型、临时替代项与缺口必须明示。
+
+每次插件调用保留独立的完整 stdout JSON、stderr 日志、输入与回执，不自动复用。摘要不够时读取同次结果文件，不重复生成。来源、输入、宿主配置、插件身份或结果文件变化后，旧证据不能通过验收。外部依赖若由插件复制为执行快照，回执证明该快照的一次执行，不自动追踪外部缓存后续变化。
+
+插件声明和 JSON 协议见[运行契约](../maintainers/plugin-runtime-contract.md)。

package/docs/guides/ui-conventions-template.md

@@ -0,0 +1,39 @@
+# 项目 UI 约定清单
+
+flutter-mobile preset 的 parse / tech / plan Worker 以 required `file` hook 读取项目里的 UI 约定清单；apply 阶段由 scout 子代理读取并只把本 task 用到的行抽进 `context.md`，build / repair 缺项时按节补读。它回答一个问题：**实现某类能力时，项目里已经有什么，必须复用什么。** 差异分析中 AI 自造状态页、弹窗、分享组件替代品，根因就是缺这份清单。
+
+清单记录项目事实（组件、路径、类名、token、字体、资源、命令、测试入口、受保护文件）及适用的技术使用约定，例如图片导出效果与代码效果不能重复叠加。如何验收、何时 blocked 之类的流程规则由 skill 节点与 preset 检查项承担，写进清单只会让每个 Worker 多读一遍。
+
+## 由 init 自动生成
+
+`openspec init --preset flutter-mobile`（或 `openspec preset apply flutter-mobile`）会按 preset 的 `scaffold` 声明，把模板 [presets/flutter-mobile/ui-conventions.md](../../presets/flutter-mobile/ui-conventions.md) 放到项目的 `docs/agent/ui-conventions.md`。只创建、不覆盖：已存在的文件不会被重复 init 改动。
+
+路径由 `openspec/config.yaml` 中 `type: file` hook 的 `path` 决定；preset 默认在 parse / tech / plan / ui code 四处声明为 `docs/agent/ui-conventions.md`。项目可以改，但四个 hook 与 `scaffold.path` 要一起改。
+
+## 填写规则
+
+模板第一行是 `<!-- openspec:fill-me -->`。只要这个标记还在，引擎就把该文件视为「未填写」：Worker 对它回执 `passed` 会被拒收（`execute_hook_file_unfilled` / `hook_file_unfilled`），与文件不存在同等处理。填完后删除第一行标记即可。
+
+内容要求：组件节使用「组件或入口 | 用途 | 位置 | 约束」表，视觉节使用下面三张映射表，写具体路径与类名——agent 会按名字去检索。通用技术约定保持简短，不以原则性描述代替项目事实。控制在 150 行内；新增平台组件时同步更新。
+
+## Figma 变量 → 项目 token 映射
+
+填明 Figma 变量、项目实际 token 与定义路径、支持的主题及用途。业务着色规则、固定强调色与渐变均引用项目实际来源；不预设 token 名称或禁用不存在的旧实现。
+
+## 字体规格表
+
+填写语义规格、字号、Figma 字重、实际 Flutter TextStyle 或样式 token，以及用途约束。collect 保持节点定位级，tech 引用该表；apply 的 scout 按 designRefs 详读节点并把文本样式表抽进 context.md，build 按表实现，verify 对照截图核对字号/字重/信息架构；无 MCP 时用采集稿，证据不足 blocked。
+
+## 双主题资源命名
+
+每行给出深浅 section/frame 节点、两套资源名/路径、实际主题选择方法的定义与调用位置。缺位图需同时声明两套占位。表中示例不是已核实事实，必须填项目真实约定。
+
+已有宿主文件不会被 init 覆盖，需要项目维护者补齐适用的映射章节；缺表由 tech 列出，Gate-A 决定补表或允许 Worker 自行映射。本仓库只更新可分发模板和说明。
+
+## 页面验证入口与受保护文件
+
+第 13 节列出本项目的契约测试、主题切换测试、整页截图命令及其产出路径，以及 Worker 不得修改的固定断言、夹具与 manifest。scout 会把这些抄进 context.md 第 5 节，build / repair 据此运行 `worker check` 并避开受保护文件，verify 据此找到最终截图。没有可执行入口的项目把对应行留空，不要伪造命令。
+
+国际化流程填写项目实际选用的资源格式、代码读取入口、翻译、合入、生成和校验命令，以及参数配置来源。工具指导由所选插件 Hook 提供，模板不预填生成器、资源格式或第三方版本。保留宿主已确认的增量策略、必需语言、占位符及历史文案保护要求；无国际化需求时注明不适用。
+
+同步预设时先比较宿主 Hook 的类型、命令、required、参数、范围与顺序。`preset apply` 会替换同 ID 的配置项，不能用它覆盖已经定制的宿主验收命令；使用经核对的精确差异迁移。

package/docs/guides/worker-evidence.md

@@ -0,0 +1,73 @@
+# 阶段检查回执与返修记录
+
+新建 parse/tech/plan/code Worker packet 的 `executionEvidence: true` 开启本协议，`refs.executionEvidence` 指向紧凑索引。已有活动 packet 不追溯改变合同；verify 保留独立 run，并共享插件解析和执行基础设施。
+
+## 适用范围
+
+| 能力 | 接入位置与适用条件 |
+|---|---|
+| 检查回执、问题记录与索引刷新 | 通用 `worker create/check/review/accept`；新建 parse/tech/plan/code Worker 使用，保留旧活动 packet 合同 |
+| Flutter 状态、主题、字体与自动翻译约定 | 宿主采用 `flutter-mobile` preset 后按任务 category 下发；不因 page 形态增加固定导航要求 |
+| 同页输入、增量 Dart 分析、媒体及文案工具 | 宿主提供真实 manifest/命令，并通过已有 file/command Hook 配置；普通 Worker 不自动创建这些配置 |
+| `claude-apply-*` 运行器与启动预检 | 显式启动的隔离实验；标准 OpenSpec 工作流不调用运行器 |
+
+本协议验证实际执行回执和已登记问题，不证明自然语言要求全部覆盖。页面缺陷样例可用于回归，不能自动成为每个 UI task 的必需检查。
+
+## 检查命令
+
+```sh
+openspec worker check --change demo --id page-tests --command 'flutter test test/page/example_test.dart'
+```
+
+内联 command 保留显式空参数（`''` 或 `""`）及其顺序，和没有提供参数的语义不同；不会执行 shell 运算符。
+
+对于阶段 command Hook，使用 Hook id 并省略 `--command`。插件 Hook 通过 `--input <项目内 JSON 文件>` 提供动态参数，不能用 --command 覆盖插件入口。CLI 使用现有无 shell 的参数解析和日志执行器，内联 command 保留原有超时行为；插件 command 默认 120 秒，入口可声明 timeoutMs。完整日志写入 `.opsx/execution/r<sourceRevision>/<stepId>/`；返回退出码、至多约 2KB 的 `outputSummary`、日志路径和 `cached`。检查命令应把原始长诊断另存日志并输出错误及简短结果；回执不会自动将任意工具的输出转成错误诊断。命令失败时 CLI 退出1；用相同 id 重试，旧回执与日志始终保留。`--force` 可强制重跑。
+
+内联检查成功且工作树（包括既有脏文件）、HEAD 和日志未变时可复用回执。插件调用首轮不自动复用；回执额外绑定当前 Worker、锁定插件、动态输入、声明依赖以及完整 stdout/stderr 和产物摘要。命令可产出截图等文件，回执绑定命令结束后的工作树；CLI 不证明命令选择、测试覆盖或无副作用。引擎会拒绝缺失的 required command Hook 回执、失败的额外登记检查以及过期回执；显式 optional command Hook 保留可选语义。旧诊断失败应按项目既有基线比较，不能把普通诊断包装成验收通过。
+
+每次命令和整批复核更新均有独立的原子记录；索引只是汇总视图。验收从这些记录重建状态，避免并行检查覆盖失败、覆盖其它问题。重试同一检查 id 按完成时间选择最新回执。验收一次返回所有已发现的阻塞项（`details.failures`），顶层错误码仍取第一项，便于既有调用方兼容；控制会话可以合并返修，不必逐项试探 accept。
+
+## 独立验收与返修记录
+
+UI task 的视觉与形态由 verify 子代理（`skills/opsx-apply/nodes/task-verify.md`）在短命上下文里判定：它读 check 描述、spec 对应页面要求、context.md 第 4 节设计清单及其指向的完整 Meta 元数据与变量、设计截图和最终截图，按与 build 相同的设计清单逐项核对，不修改业务代码；只登记本 task 范围内的问题，跨任务缺陷交控制会话汇报。它把结果写成项目内 JSON（建议 `<change>/.opsx/workers/<taskId>.review-<n>.json`），控制会话再登记：
+
+```sh
+openspec worker review --change demo --file openspec/changes/demo/.opsx/workers/T-005.review-1.json
+```
+
+```json
+[{"id":"hero-title-weight","status":"open",
+  "description":"观察：浅色截图标题实际 w500；期望：来源节点 <id> 标题 w600；疑似位置：hero_header.dart"}]
+```
+
+每条 open 问题写「观察 / 期望 / 疑似位置」三段，期望必须可核对（数值、token 名、节点 id 或参照截图区域）；设计与参照中不存在的元素不得成为问题。复核后沿用同一 id，以 `resolved` 和非空证据文件路径 `evidence` 更新。未出现在更新中的问题不会自动关闭，因此每轮 verify 必须覆盖索引中全部既有 open。没有发现任何问题时写 `[]`：它同样落一条记录并计入轮次。响应返回 `open`（全部未修项）、`blocking`、`advisory`、`rounds`（review 记录数）与 `repairRounds`（实际代码返修后的审查数，`worker review --repair` 且代码指纹有变化才计入）；`worker create --view summary` 也返回 `reviewRounds` 与 `repairRounds`。
+
+普通 UI 视觉偏差允许 `advisory: true`，必须附非空实际截图 `evidence`；保持 open，不冒充 resolved。非 UI 不接受 advisory，行为/构建失败或不可用证据不属此类。省略此字段的既有问题继续阻断。CLI 不分析自然语言判定分类，独立 verify 负责分类。advisory 的代码指纹、证据摘要与 resolved 一样须保持有效。最终 QA JSON 的 `visualAdvisories` 及 Markdown 自动列出当前来源修订下的未修偏差；passed 不代表完全还原。
+
+控制会话仅对阻断问题执行必要返修；普通视觉偏差可尝试返修，也可直接披露并继续。任何 UI task 最多两轮实际返修，达到上限后有阻断项须停止，只有 advisory 则保持 open 并汇报。首轮审查与只刷新证据的复核不计入返修轮次。这个上限只是成本守门，不是质量手段：首轮质量靠 scout 设计清单、build 直读截图与 Meta 数值、verify 用同一份清单核对。repair 子代理读 open 问题、上轮 changedFiles 涉及的文件，以及问题涉及的原始设计截图、Meta 元数据与实际页面截图；直接使用设计源导出的切图，不做二次图像处理；不得删除或弱化既有测试断言；修完重跑受影响 check 产出新证据，再由下一轮 verify 关闭问题。
+
+索引按来源修订和 task 保存，cancel/create 重试同一 task 也不会丢失。来源修订后新修订目录从空索引开始（问题要按新来源重新审查），但 `repairRounds` 汇总同一 task 在所有修订下的实际返修记录：取消 → 来源修订 → 重新规划不会重置两轮上限。解决记录绑定当前代码和证据摘要，任一变化后需重新复核。更新按整批验证后写入，非法路径或未知问题不产生部分更新。这些检查核实的是执行回执、文件版本和已登记问题；引擎不分析自然语言 notes 自动判定问题已修复。不要手改 `.opsx/execution`；该目录和既有 `.opsx` 一样属于可信本地工作流存储，并非对恶意篡改的隔离边界。
+
+再次 `worker create` 同一 task 会保留活动 Worker、packet 和 diff baseline，从独立记录刷新 `refs.executionEvidence` 指向的索引，并在 scout 摘要存在时补上 `refs.taskContext`。resolved 仍受既有代码/证据摘要约束，刷新不代表重新验收，也不豁免 stale。packet/result 格式及旧无 executionEvidence 的活动 Worker 不变。
+
+活动任务需要采用更新后的锁定插件或 Hook 配置时，先结束旧 Worker 的命令，再运行 `worker create --change <name> --step <当前步骤> --refresh`。这个显式操作生成新的 Worker 和当前 Hook 绑定，保留原始代码差异基线、已有答复、问题索引和全部历史制品。新 Worker 不接受旧 result 或旧检查回执，必须重新执行检查和适用的技能；旧版活动 packet 只有在显式刷新时才采用当前合同。缺失基线、HEAD 变化或新入口解析失败会拒绝刷新并保留旧活动 Worker。不要用 cancel/create 代替，它会从取消后的当前工作树重新取基线。
+
+## 项目检查与插件检查
+
+宿主通过 file/command Hook 声明真实的输入清单、行为测试、静态检查、主题切换和截图入口；保留已有失败阈值。冻结文件校验必须覆盖全部固定断言与夹具，检查失败不能靠重建基线抹去。动态业务文件与固定证据分别记录，不能阻止合法业务实现。
+
+国际化检查及合入由项目选择的正式工具实现，插件提供指导和公开入口绑定；需保留历史内容、必需语言、占位符、失败日志与语义核对。生成或校验命令退出成功不证明翻译准确。通用框架不提供语言或宿主格式专用脚本。
+
+内联 command Hook 通过环境变量 `OPENSPEC_COMMAND_CONTEXT` 读取本次上下文 JSON 路径。文件包含 `version: 1`、`projectRoot`、`change: {name, root}`、`runId`、`hookId`、`worker: {id, stepId}`、可选任务事实 `task`（无任务时为 null）和 `changedFiles`。code/repair 的文件集来自 Worker 创建时的真实 Git baseline，verify 来自引擎累计文件集，parse/tech/plan 为空；不是 Worker 自报范围或 reviewScope 过滤结果。原命令、参数与 stdin 行为不变；框架覆盖同名继承环境变量，不拼接 shell。
+
+宿主可据此执行任务边界等自身策略，无需把业务规则放入调度器。上下文文件与回执一起绑定摘要，修改或删除后须重跑命令；不得修改引擎内部文件。已有无上下文字段的历史回执继续按其原合同读取。插件 command 继续使用既有 JSON stdin 协议，不受此补充影响。
+
+配置 purpose 随 descriptor 下发说明检查用途。插件引用、输入说明、命令执行和失效规则见[插件运行契约](../maintainers/plugin-runtime-contract.md)。required tech command 存在时 parse 不得 skipTech；新阶段的文字 passed 不能替代真实 CLI 回执。
+
+真实主题测试沿宿主现有切换入口保留页面实例；控制会话对照设计与最终截图判定视觉结果，不能把成功截图回执当作视觉通过。
+
+## Scout 路径与恢复
+
+`worker create --view summary` 的 `taskContextPath` 始终给出按 task id 固定的预期路径；`taskContext` 仅在文件存在时返回。派发 scout 必须传入前者，完成后再次 create 同 step 绑定 `refs.taskContext`，不能改用 workerId 文件名。超时恢复沿用同一 packet、摘要和检查日志，先核对已有差异再完成剩余部分。build 内部失败/重跑与正式 repairRounds 分开记录。
+
+`changedFiles` 对应真实 Git 差异：忽略且未跟踪的生成缓存不申报，已跟踪文件仍申报；不为修正声明删除工具缓存。

package/docs/guides/workflow.md

@@ -0,0 +1,74 @@
+# 工作流
+
+当前使用 packet version 1 / instructions protocol 1。collect、parse、tech、plan 按节点直接执行；code 在宿主支持时使用 subagent。问答保留在原 packet，相关决定同步到对应规格与任务。Gate-A 按 stop 清单汇报，无额外上下文投影、共享决定账本或必需摘要文件。正常流程与离线用量分析均不依赖隔离探针。
+
+状态机节点：
+
+`collect → parse → tech → plan → gate-A → code → gate-B → verify → gate-C → completed → archive`
+
+`tech.md` 把 spec 的页面清单映射到项目既有模式（复用清单、每页状态方案、接口接入、i18n/主题），是横切决策唯一的落点；结构见 `skills/opsx-propose/nodes/tech.md`。可跳过，但只在 spec 页面清单 ≤ 1 项、无接口改动、无需新建组件三条同时满足时，且 parse result 的 `notes` 必须写明理由——引擎拒收无理由的 `skipTech`，并记录 `worker.tech_skipped` 事件。
+
+权威状态只在 `openspec status --json`。Agent 不要手改 `.opsx/state.json`。
+
+`openspec instructions <workflow> --protocol 1 --json` 只返回当前 node、next 与应读取的绝对 `nodeFile`（小于 1KB）。workflow 与 protocol 使用严格枚举。节点操作细节在 `skills/<workflow>/nodes/`。
+
+parse Worker 写出的 `spec.md` 必须含「页面与入口清单」「状态与交互」「来源冲突与缺口」三章（见 `skills/opsx-propose/nodes/parse.md`）。影响页面形态、入口或字段存在性的来源冲突不由 agent 自选口径，而是以 `blocked` + `questions` 停下，`instructions` 会返回 `need_user_input`；用户答复后执行 `openspec worker answer --change <name> --answer <text> [--answer ...]`，答复写入原 packet 的 `decisions[]` 并清除 blocked，再次 `worker create` 同一 step 复用该 packet。其余冲突留在 spec 第 5 章，由 propose 的 stop 节点在 Gate-A 前汇报。
+
+spec 记录页面、状态交互、产品字段、来源关联及冲突；tech 进一步核对真实接口与项目接入。来源可用只读的完整/产品视图或精确字段选择，生成路径、传参与模型可用锁定生成器预演核对，见 [来源读取与生成核对](source-reading.md)。这些工具不新增阶段、上下文副本或必需报告；生成类型不能代替业务说明。required hook 仍逐项回执，同会话中完整可用且未变化的文件可复用，内容丢失或变化后补读。
+
+tech 的聚合决定须保留数据完整性与缺失值前提，详细算法、任务引用和 Gate 汇报一致；部分合计不能静默充当总额。对象开放性、是否允许 null 与空样例分开核对，不从 Map 或空类数反推 schema。Gate-A 退回到 plan 时，已有来源的解释或适配错误可最小同步 tech/plan；来源或需求变化仍走 source-update。
+
+`type: skill` 的 collect hook 没有 adapter：agent 用宿主工具人工采集后以 `sources add --source-file <capability>=<path>` 登记；同 capability 只要有手工 file/text 来源，对应 url 来源即视为已覆盖（collect 结果 `covered`），不再阻塞 parse。adapter 产物里无法展开的占位（如飞书文档内嵌 `<sheet>`）同样用手工来源补采。
+
+`capability` 固定为 `requirements`、`interfaces` 或 `design`，例如 `--source-file requirements=inputs/requirements.md`。`path` 必须是项目内已存在文件的相对路径；外部文件先按授权复制到项目内再登记。无效文件来源在写入账本或启动 source-update 之前被拒绝，不留下不可修正的来源项；collect 仍会再次检查旧账本中的路径。
+
+parse / tech / plan Worker 与 code Worker 一样先读 `packet.initContext` 并逐项回执 hook；这让项目约定文件（如 UI 组件清单）在写 spec、定技术方案与拆 task 时就生效，而不是等到实现阶段。propose 的 stop 节点会在 Gate-A 前列出 tech 复用清单里所有「新建」项，供用户逐条确认。
+
+Gate-A 前，plan Worker 必须生成带有效 category 的 `plan/task-plan.json`。任务用普通章节标题、页面名和文件路径引用 spec/tech，notes 只补任务特有边界、差异与验证。不因视觉尚未详读就删除范围内能力；产品未决项仍按真实阻塞处理。用户答复后复用原 Worker，只同步受影响的权威内容与引用。Gate-A 直接读取现有产物与状态，区分已裁定和未决事项，不重复询问已裁定内容。横切关注点（国际化、主题色、加载/空/错误态）必须归属产生它们的 UI / logic task，不允许拆成尾部 task。Gate-A 后每次只创建一个 `code-<taskId>` Worker，但一个 task 的执行拆成四个短命、单职责的子代理阶段（见下节）；宿主没有 subagent 时，主 agent 按同一组节点文件依次亲自执行。build / repair 子代理必须先读取 `packet.initContext` 与 task 摘要再改代码，并在 result 中逐项回执 execute Hook。
+
+## Code task 的四阶段
+
+控制会话读 `skills/opsx-apply/nodes/code-task.md`，只做编排：调 CLI、派发子代理、读 result / issues JSON、按响应路由；不读源码、设计稿或截图。每个阶段的子代理只拿到自己的节点文件路径与少量输入路径：
+
+| 阶段 | 节点文件 | 输入 | 产出 |
+|---|---|---|---|
+| scout（不改业务代码） | `nodes/task-scout.md` | packet | `<change>/.opsx/workers/<taskId>.context.md`，约 4KB（建议值，不是硬限制）固定七节：范围 / 复用清单（含设计值 vs 组件默认值）/ 约定 / 设计清单（Meta 几何数值、切图清单，build 与 verify 共用）/ 检查与受保护文件 / i18n / 风险；完整设计证据保存在 `<change>/.opsx/workers/<taskId>.*` 下 |
+| build | `nodes/task-build.md` | packet + context.md | 代码、`worker check` 回执、result.json |
+| verify（仅 `ui`） | `nodes/task-verify.md` | packet、context.md、设计截图、最终截图、既有 issues | `<taskId>.review-<n>.json`，每条 issue 写观察 / 期望 / 疑似位置 |
+| repair | `nodes/task-repair.md` | packet（含刷新后的问题索引）、context.md、上轮 changedFiles 或 accept failures | 代码、受影响 check 回执、result.json |
+
+摘要一次生成、build / repair 多次复用；同一 change 内后续 task 的 scout 先读已有摘要复用代码库事实。`worker create` 在摘要存在时把路径放进 `packet.refs.taskContext`，`--view summary` 同时返回 `category`、`taskContext`、`reviewRounds`，控制会话无需读取 packet 正文。
+
+设计事实直达实现者：build / repair 编码前实际读入设计截图与 Meta 元数据（只拿到 URL 不算），几何取 Meta 数值，切图直接用设计源导出件，不做二次图像处理；实现者对照原稿自检，是否达标由独立 verify 在短命上下文里按同一份设计清单判定。宿主约定文件中声明「以宿主为准」的项（如字体族、导航栏组件）优先于设计稿：scout 在清单里标注，build 按约定实现，verify 不把它们与设计稿的差异登记为问题。verify 的结果通过 `openspec worker review --file` 登记（无问题时写 `[]`，同样计一轮；实际代码返修后的审查加 `--repair`）；根据 `blocking` 与 `advisory` 区分必要返修和可选视觉返修，最多两轮实际返修；只有普通视觉偏差时可保留 open 并披露后继续，有阻断项达到上限则停止。这是成本守门的硬上限，不因单个视觉细节自动延长，也不是提高质量的手段。非 `ui` task 的检查失败只派发一次 repair。
+
+任务拆分应与行为边界及验收范围一致。实验指标与特定宿主结果由独立验收工程保存，不作为通用流程的默认前提。
+
+skill 型 hook 的 descriptor 会附带 `path`（在项目锁定的 marketplace 插件中找到的 SKILL.md 绝对路径），宿主没有把该插件注册成 skill 时（例如 Cursor）Worker 仍能按路径读取。verify packet 的 `verifyHooks` 列出本 run 需要证据的全部 verify hook；repair-verify packet 带全部已完成 task 分类的 notes 与匹配的 execute hook。
+
+`refScope` 只是定位参考，不限制实际改动。code/repair Worker 的 changed-set 由 Git 基线与结束状态计算；Worker 自报只用于差异事件，QA 使用引擎记录。非 Git 项目不支持 code Worker。
+
+每次 verify Worker 都建立新的 run 目录。QA 失败后使用 `verify fix` → `repair-verify` → 新 verify run，不重开原 task；Gate-C 只接受当前 run 的 passed report。archive 使用 rename 移走 active change，并清理 transient worker/source-update 目录。
+
+## 产物与待办
+
+`state.tasks` 只保留调度字段（id/title/category/type/status/completedAt/dependsOn）；task 详情以 `plan/task-plan.json` 为准，创建 code packet 时按需读取。`packet.task.notes` 是 task 规则唯一副本，`initContext.rules` 只包含 category 规则。旧 state 可读取，下一次保存时移除重复详情。
+
+每个 code/repair Worker 的实际 changedFiles 与 result.notes 记录在 `worker.accepted` 事件；state 只累计 `engineChangedFiles`。验证命令完整 stdout/stderr 写入 change 下 `.opsx/verify/<run>/<hookId>.log`；报告的两个流合计保留最多 2KB 尾部，带 `truncated` 与相对 change 的 `log` 路径。
+
+`openspec todo --change <name> --json` 只读扫描 `engineChangedFiles`（应用 `verify.reviewScope`），按 `TODO(category)` / `FIXME(category)` 分类，未指定类别归 `general`，输出文件、行号和文案；已删除/二进制文件列在 `skippedFiles`。同时汇总 accepted Worker notes 的 TODO/FIXME 和「未能满足/占位」段，历史声明不自动视为当前缺陷或已解决。旧事件未记录的 notes 无法追溯。
+
+新 QA report 的 `pendingWork` 与 todo 同形，非阻塞；optional `check` 且 `category: todo` 不受 failurePolicy 提升为阻塞。归档以已验收 report 的清单生成 `reports/pending-work.md`；旧报告没有该字段时在归档前采集。Gate-B/C 汇报分类待办，Gate 的既有批准条件不变。
+
+## 设计节点引用
+
+Smart Figma 在 collect 生成页面索引；parse 可定向确认形态，tech/plan 可读取候选 frame 的必要设计证据以确定复用和文件范围，coding 补齐完整实现证据。会话接入、缓存、分页与当前验收限制见 [Smart Figma](smart-figma.md)；真实入口复验已通过，固定输入及 coding 对照尚未完成；当前不切换全局安装。
+
+`task-plan.tasks[].designRefs` 可省略或为 `[]`；非空项必须是非空字符串，去除首尾空白并去重，节点存在性留给 Worker 核查。该详情只存 plan 并透传为 `packet.task.designRefs`，不增加 state 重复字段。`packet.refs.design` 是设计来源数组，每项包含 `sourceId/kind`、URL 或 file 的 `locator`、项目相对 `artifact` 路径；text 源只给 artifact，避免重复正文。既有 refs 的路径约束保持不变。
+
+`openspec status --json` 在 `progress` 旁输出 `uiTasksWithoutDesignRefs`：仅当当前账本有 design capability 时列出缺节点的 UI task，否则为空数组。此项是 Gate-A 汇报提示，不是引擎必填校验。collect 只记录节点与深浅 section 定位；parse 可读取候选 frame 截图或节点类型确认形态；tech 在 Gate-A 前对照目标截图、必要 Meta 与组件 API，确定直接复用/扩展后复用/新建及修改文件，plan 将其落实为范围（跳过 tech 时由 plan 核对）；apply 复用证据并按节点详读、截图并结合项目视觉映射表实现，无 MCP 时回退采集稿，不足则 blocked。
+
+具体页面字段与文案语义由 UI task 在编码前核对：scout 按 `designRefs` 详读节点并把文本样式、颜色变量与资源名抽进 context.md，build 按表实现，verify 对照截图判定。parse/tech 只补读当前决策或已知冲突所需设计，不要求提前逐页详读。实施中的正常补全、必要文档同步与真实冲突按 [Task build](../../skills/opsx-apply/nodes/task-build.md) 处理：有来源且无冲突的补全留在本 task，普通展示细节不要求回改 spec；影响后续任务理解时才最小同步相关章节，不因此重跑前置阶段或 Gate-A。
+
+### 普通视觉偏差的可选返修
+
+UI 独立验收仍须检查整页。普通视觉偏差以 open + advisory + 实际截图登记，可尝试返修，也可披露后继续；构建、行为、证据不可用仍阻断。最多两轮是实际返修上限，不是必须返修两轮。最终 QA 自动列出当前来源修订的 visualAdvisories，passed 不代表完全还原。旧记录省略 advisory 时仍按阻断问题处理。

package/docs/maintainers/architecture.md

@@ -0,0 +1,27 @@
+# 架构
+
+v2 按产品责任分层，避免 v1 的巨型 packet 与双套 hook。
+
+```text
+cli/            命令薄层
+core/           状态机、change、task、worker、verify
+hooks/          统一六阶段 hook（collect / parse / tech / plan / execute / verify）
+marketplace/    immutable ref/cache/project lock；adapter 合同来自插件
+delivery/       Claude/Codex 原生 marketplace、Cursor UI pending 与 install-cli
+config/         项目配置与 preset
+shared/         fs / git / 路径
+```
+
+状态只写在 `.opsx/state.json`（当前 node / gates / tasks / 活跃 worker / verify run）。历史进 `events.jsonl`。JSON 采用同目录临时文件加 rename；缺失或损坏时 fail closed，旧 task 详情字段读取时投影为调度字段，不做其他状态迁移、锁、CAS 或 fsync。
+
+code packet 只含当前 task、`initContext` descriptor 与共享文档路径引用。`refScope` 是软提示。引擎按 category 生成 descriptor；Worker 通过 worker check 执行 command 并保存可验证回执，skill/check 保留语义验收。parse / tech / plan packet 复用同一 `initContext` 结构与回执校验（`buildStageInitContext`），因此只有一条 descriptor 生成路径和一条验收路径。
+
+一个 code task 在 skill 层拆成 scout → build → verify → repair 四个子代理阶段，引擎对此只做两件事：`worker create` 发现 `.opsx/workers/<taskId>.context.md` 存在时把路径放进 `refs.taskContext`（普通 markdown，不进 schema、不校验内容，避免重蹈引擎级上下文投影的复杂度）；`worker create --view summary` 与 `worker review` 返回 `reviewRounds` / `rounds`（该 task 的 review 记录数，空数组也计一条）与 `repairRounds`（`--repair` 且代码指纹变化的实际返修数），控制会话据此执行成本守门的返修上限。阶段编排、build / repair 直读设计截图与 Meta、scout 设计清单由 build 与 verify 共用、实际返修最多 2 轮等规则都在 `skills/opsx-apply/nodes/` 的节点文件里，apply 节点各文件 ≤6KB（`test/skills/budget.test.ts`）且只含本角色需要的内容；平台专属事实留在 preset 模板与宿主约定文件，单个样本的返修词不进通用 skill 与 preset。
+
+changed-set 依赖 Git：Worker 基线只摘要启动时已有 dirty/untracked 文件，结束时计算相对净变化并排除 `.opsx` 内部文件与 `openspec/changes/<name>/**` 产物（项目配置和业务文档仍计入）。verify command/evidence/report 按 run 隔离，Gate-C 不消费 `reports/qa-report.json` 的旧副本。
+
+Marketplace cache 位于 `OPENSPEC_HOME`（默认用户 OpenSpec 目录），项目 lock 是运行时发现的唯一权威入口。Lock 绑定 resolved SHA、marketplace digest 和 plugin digest；Claude/Codex 走原生命令，Cursor 只返回 UI action，不做隐藏目录复制。
+
+`task-plan.json` 持有 task 详情；state 仅持有调度字段与 engineChangedFiles。每次 worker.accepted 事件持有本次实际 changedFiles 和 notes。todo 以同一 reviewScope 扫描当前文件并汇总历史声明，QA report 保存 pendingWork 快照，archive 渲染该快照。
+
+插件声明与运行接口由 [plugin-runtime-contract.md](plugin-runtime-contract.md) 维护。source adapter 的 collect/discovery 保留旧原文协议，read/preview 采用 JSON stdin/stdout；插件 Hook 与 source 操作共享锁定解析和执行器，各自保留生命周期。插件目录身份只从项目 marketplace lock 解析，预设不保存缓存绝对路径。来源账本和 packet 增加可选摘要与绑定，旧数据、旧在途 packet、六阶段及 Gate 保持兼容。

package/docs/maintainers/plugin-runtime-contract.md

@@ -0,0 +1,55 @@
+# OpenSpec 插件运行契约
+
+本契约属于 v2 根 `plugin.json.extensions["org.openspec"]`。插件声明源及生成链由插件仓库维护；v1 sidecar 独立，不能据此重写。
+
+## 声明与引用
+
+`adapters` 保留 `id/capability/kind/operations.collect/discovery`，增加可选 `operations.read/preview`。操作声明为 `{command, args?, artifact?, timeoutMs?, inputDescription?}`，默认超时 120000 ms。新操作采用下述 JSON 协议；旧 collect/discovery 的原文 stdout 协议不变。
+
+`hooks` 为数组，入口为 `{id, stages, type: "skill", path, inputDescription?}` 或 `{id, stages, type: "command", command, args?, timeoutMs?, inputDescription?}`。stages 为 parse/tech/plan/execute/verify 的非空集合。技能 path 必须是插件内 SKILL.md 相对路径。
+
+项目 Hook 使用 `{id, stage, type, use: "entry-id@marketplace", required?, capability?, taskCategories?, input?, inputFiles?}`。`input` 是 JSON 对象，`inputFiles` 为宿主相对文件路径数组。内联实现字段不得与 use 共存。collect 的 use 解析 adapter；非 collect 默认解析插件 Hook；`type: command, operation: preview` 解析 adapter。入口类型、阶段、重复 ID、锁定身份和路径均严格验证。旧内联 Hook 保留行为。
+
+只有命令及参数中的 `{pluginRoot}` 是插件文件定位占位符；替换后以 argv 直接执行，无 shell 展开。cwd 是宿主根。所有业务参数通过 JSON 输入传递，不进行字符串插值。
+
+## 新命令协议 version 1
+
+stdin 是一份 JSON：
+
+```json
+{
+  "version": 1,
+  "operation": "read",
+  "projectRoot": "/host",
+  "change": {"name": "example", "root": "/host/openspec/changes/example"},
+  "source": {"id": "src-1", "capability": "interfaces", "kind": "url", "locator": "https://example.test/api", "artifact": "/host/openspec/changes/example/sources/artifacts/src-1.json", "artifactSha256": "..."},
+  "input": {},
+  "outputDir": "/host/openspec/changes/example/.opsx/operations/unique-run"
+}
+```
+
+operation 为 read/preview/hook；source 对普通 Hook 可省略；adapter read/preview 必须选择 source 或 sources。Worker 调用另含 `worker: {workerId, stepId}`。项目配置 input 与 `--input <项目内 JSON 文件>` 顶层合并，动态值优先，不能覆盖协议上下文；`input.sourceId` 或非空无重复的 `input.sourceIds` 二选一。单来源信封保持 source；多来源信封传 sources 数组，元素结构与 source 相同，逐项校验 capability、adapter 身份、原文摘要，全部进入回执依赖。source/sources 来自当前已采集账本，不能用 input 注入 artifact。
+
+成功 stdout 必须是单一 JSON 对象 `{data: <完整结果>, dependencies?: [<宿主相对文件路径>], artifacts?: [<outputDir 相对文件路径>]}`；stderr 仅诊断，不能混入 JSON。非零退出及超时失败，完整 stdout/stderr 均保留。dependencies 必须列出影响结果的配置、锁文件、工具入口及输入文件；artifacts 列出额外完整结果文件。大结果保存在独立文件，data 可以给摘要和引用，但不得用摘要替代原始结果。
+
+read/preview 只读冻结来源与宿主业务文件，只能在 outputDir 写结果；不能把预演描述成编译或业务验收。实现型 Hook 可修改宿主文件。核心保存每次调用的新结果，不自动复用插件命令。
+
+CLI 回执绑定来源及账本、配置与动态输入、锁定插件名称/marketplace/SHA/目录摘要、Worker/run、完整 stdout/stderr 与额外产物摘要、dependencies 文件摘要；缺失、失败或变化使证据不可验收。插件须申报实际读取的额外依赖，核心不推断语言或工具文件名。
+
+## 调用与兼容
+
+`sources read --change <name> --source <id> [--input <file>] [--use <adapter@marketplace>]`：有持久 adapter 绑定时默认使用其 read；旧账本/手工来源默认无损返回原文，有专用读取需求必须显式 use，不写回来源身份。
+
+`worker check --change <name> --id <hook> [--input <file>]`：parse/tech/plan/execute 的 command Hook 通过相同执行器运行。required command 必须有当前 Worker 的真实 CLI 回执；文字 passed 无效。存在 required tech command 时不能 skipTech。verify 通过原 verify 生命周期运行同一解析器和执行器。
+
+旧 packet、账本、collect/discovery、内联 Hook、六阶段状态流及 Gate 保持可读和原有在途契约。新建启用命令证据的 packet 增加可选 executionEvidenceVersion: 2；包括 QA 返修 Worker，所有命令回执必须绑定该 Worker。没有此字段的旧在途 packet 保留原验收规则，不把旧回执冒充新 Worker 执行。
+
+parse/tech/plan Hook 可用既有 capability 字段限定适用来源能力：当前账本无该 capability 时不下发该 Hook，亦不阻止 skipTech；未填写则始终适用。execute 的 taskCategories 语义不变。
+
+## 版本与兼容
+
+OpenSpec 对插件只承诺本契约：入口声明与解析、命令协议和回执身份。插件在契约内的变化（Skill 内容、工具参数、生成行为）独立发版，不需要 OpenSpec 或 preset 跟版；宿主通过自己的 marketplace ref 与锁选择版本，回执绑定实际 SHA 与目录摘要。契约出现不兼容变化时才提升协议 version 并随 OpenSpec 发版，旧协议按上文保留可读。
+
+宿主与 preset 用 `plugins[].minVersion` 声明最低版本，比较对象是插件 manifest 顶层的 `version`，不需要插件新增字段。`extensions["org.openspec"]` 按严格 schema 校验，已发布的 OpenSpec 会拒绝其中的未知字段，所以不要把兼容元数据写进这一段；日后确需声明协议版本时，放在 `extensions` 下独立的键中，旧版本会忽略它。
+
+核心节点与 preset 不复述具体工具的行为或输入格式；这些写在插件 Skill 与 Hook 的 `inputDescription` 中，随插件一起变化。宿主升级流程见 [插件能力迁移](../guides/plugin-migration.md#版本归属与独立升级)。

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@birdie_moblie/open_spec",
+  "version": "2.1.7",
+  "description": "AI-native Spec Coding 工具：确定性产品规格工作流",
+  "keywords": [
+    "openspec",
+    "specs",
+    "cli",
+    "ai",
+    "development"
+  ],
+  "homepage": "https://gitlab.bitrue.com/front_ai/open_spec",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@gitlab.bitrue.com/front_ai/open_spec.git"
+  },
+  "license": "MIT",
+  "author": "OpenSpec Contributors",
+  "type": "module",
+  "packageManager": "pnpm@11.25.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "openspec": "./bin/openspec.js"
+  },
+  "files": [
+    "dist",
+    "bin/openspec.js",
+    "skills",
+    "presets",
+    "plugin.json",
+    ".claude-plugin",
+    ".codex-plugin",
+    ".agents/plugins/marketplace.json",
+    "README.md",
+    "docs/getting-started.md",
+    "docs/guides",
+    "docs/maintainers/architecture.md",
+    "docs/maintainers/plugin-runtime-contract.md",
+    "!dist/**/*.test.js",
+    "!dist/**/*.map"
+  ],
+  "scripts": {
+    "lint": "eslint src/ test/",
+    "build": "node build.js",
+    "typecheck:test": "tsc --project tsconfig.test.json",
+    "dev": "tsc --watch",
+    "dev:cli": "pnpm build && node bin/openspec.js",
+    "test": "pnpm run build && pnpm run typecheck:test && vitest run",
+    "test:watch": "pnpm run build && vitest",
+    "prepack": "pnpm run build"
+  },
+  "engines": {
+    "node": ">=22.0.0 <23 || >=24.0.0 <25"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.0",
+    "eslint": "^9.39.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.61.0",
+    "vitest": "^3.2.6"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.8.0",
+    "chalk": "^5.5.0",
+    "commander": "^14.0.0",
+    "saxes": "6.0.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.0.17"
+  }
+}

package/plugin.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "openspec",
+  "version": "2.1.7",
+  "description": "OpenSpec 确定性产品规格工作流",
+  "license": "MIT",
+  "author": { "name": "OpenSpec Contributors" },
+  "keywords": ["openspec", "spec-coding"]
+}

package/presets/backend-service.yaml

@@ -0,0 +1,19 @@
+schemaVersion: openspec.team-preset.v1
+version: 2.0.0
+id: backend-service
+title: Backend Service
+description: 后端服务团队的 spec-product 默认配置
+configPatch:
+  schema: spec-product
+  hooks:
+    - id: contract-check
+      stage: verify
+      type: check
+      category: contract
+      description: 核对接口契约与错误码是否与 spec 一致
+      required: true
+    - id: unit-test
+      stage: verify
+      type: command
+      command: pnpm test
+      required: true