@fooksky/lodestar 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lodestar contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# Lodestar
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+用于统一个人在 DeepSeek Harness 中的开发工作流程，基于 DSH 原生能力和 Agent Teams。
+
+当前开发工作流扩展：skill 负责需求、设计、授权和验收判断；`dev_workflow` 工具维护结构化 change 状态；DSH 原生工具和 Teams 负责执行。[首版设计](docs/design.md) 保留为历史，当前开发中的分支扩展遵循 [分支与 worktree 隔离设计](docs/branch-management.md)，面向 `0.2.0`，暂不公开发布。
+
+## 使用方式
+
+启用核心插件后，在兼容会话中加载 `dev-workflow` skill，以自然语言开始需求、继续 change 或交付。无需切换模式即可使用核心流程。可选“开发工作流”preset 为新会话提供流程入口，配置默认关闭；它复用部署已有的原生工具，不改变默认模式、模型或权限。正在执行的会话不切换 preset。
+
+本仓库的开发和测试不会把插件安装到本地/profile。安装、启用可选模式和发布分别需要明确操作；模式选择本身不构成实施授权。首版没有自动提交、推送、发布、hook 或第二套任务执行器。
+
+## 材料与状态
+
+材料保存在项目 `.dev-docs/changes/<change-id>/`：`intent.md`、`spec.md`、`plan.md` 由 Lead 按阶段编写，`state.json` 由工具原子更新。复用已有 `.dev-docs/index.md` 与 `knowledge/`。状态仅接受 `schemaVersion: 2`，`workspace` 必填；未知或旧 schema、缺失绑定均拒绝，不自动转换或修复。list 中未受管目录显示缺失或非法 state 错误。
+
+一个独立需求默认对应一个 change、一条分支、一个 worktree 和一个 Lead。外部助手或用户负责 Issue 分配、准备 worktree 和启动会话；插件不创建/切换分支、不扫描工作区、不承担跨需求调度。代码、知识、change 材料和需保留的证据全部在本 worktree，知识继承基准提交的快照，不实时读取主 checkout 或共享材料根。
+
+工具每次显式接收 `projectRoot`；action 为 `workspace/list/get/create/update`。先观察外部已准备的工作区：
+
+```json
+{"action":"workspace","projectRoot":"."}
+```
+
+Git 项目的 `projectRoot` 与调用 Agent cwd 必须属于同一 checkout，允许项目子目录；不能从需求 worktree 指向主 checkout。普通目录项目根必须存在且位于 cwd 内。detached HEAD 只读，unborn 命名分支可写，bare 仓库拒绝使用；Git/权限/取消/损坏错误不降级为普通目录。创建例：
+
+```json
+{"action":"create","projectRoot":".","changeId":"20261107-example","title":"示例需求"}
+```
+
+create 自动生成 schemaVersion 2，绑定当前命名分支或普通目录。Git 绑定保存分支、绑定时的 `baseCommit`（unborn 可为 null）及项目相对 checkout 路径；不保存机器绝对路径或可变 HEAD。每个 action 的顶层 workspace 直接返回实时观察，无 current/status 嵌套；workspace action 不返回 bindingStatus。get 顶层 bindingStatus 仅为 matched/mismatch/detached，binding 为已存绑定；list 有效行的 workspace 为已存绑定并附 bindingStatus。历史 change 合入后不会自动改绑。分支改名、明确接管或普通目录初始化为仓库后，用当前 revision 单独重绑：
+
+```json
+{
+  "action":"update","projectRoot":".","changeId":"20261107-existing","expectedRevision":1,
+  "operations":[{"type":"bind-workspace","reason":"分支已重命名，确认当前分支继续负责本需求"}]
+}
+```
+
+bind-workspace 只接受 reason，实际分支/路径/提交由工具观察，不得夹带业务变更，也不能修复缺失绑定或非法 schema。重绑在 workspaceHistory 保留旧绑定、原因和时间，每项 previous 必填；相同绑定重试不增加 revision，普通提交/rebase 不要求 HEAD 相等或刷新 baseCommit。工作区不匹配先核对归属，分支重命名或确认接管后才显式重绑。绑定是状态写入保护，不是工作目录或 Lead 所有权锁；运行期间不外部切分支、搬移或清理 worktree。详细规则见 [工作区参考](skills/dev-workflow/references/workspace.md)。
+
+正文写好后登记：
+
+```json
+{
+  "action":"update","projectRoot":".","changeId":"20261107-example","expectedRevision":1,
+  "operations":[{"type":"register-document","kind":"intent","classification":"semantic","basedOn":{},"reason":"初次登记"}]
+}
+```
+
+其他操作和确切字段参见 [工具输入 schema](src/schema.js) 与 [skill](skills/dev-workflow/SKILL.md)。每次更新最多 32 个操作，全部成功才发布。遇到冲突先 get 再合并；未知回执先核对记录，不盲重试。材料链接不作为写入目标；材料目录与文件拒绝符号链接，项目根可以由宿主解析为规范路径。
+
+确认引用实际用户表达和材料版本；工具只校验结构与前置条件，不声称能够鉴别用户授权语义。正文变化需重新登记，相关验收失效由 Lead 明确标记。原生 Team 进度仍以宿主任务板为准。
+
+PR/MR 地址、源/目标分支、评审/合入结果和证据记录在既有 plan/交付材料中，不新增远端生命周期调度器。交付要求合入时，close 前完成合入及集成验证；交付边界是提交 PR 时不声称已合入。需保留的代码、知识与 change 材料随分支提交，经 PR/MR 集成；知识和 state 冲突须核对语义。提交及清理需相应授权，清理前保留未提交材料与证据。worktree 只隔离文件，端口、数据库、账号等外部资源仍须按需求隔离。
+
+## 开发与验证
+
+需要 Node.js 24+、pnpm（不固定版本）、Git 及宿主 subprocess 服务，核对宿主版本为 DSH `0.2.2-rc.1`；Git 查询遵守调用会话的 sandbox policy，不使用裸 Node child_process 或 shell 绕过宿主。依赖无安装脚本：
+
+```sh
+pnpm install --frozen-lockfile --ignore-scripts
+# prepack 自动执行语法检查和测试，并预览实际发布文件
+npm pack --dry-run
+```
+
+真实宿主集成测试可使用现有 DSH 安装目录，无需 profile 安装：
+
+```sh
+DSH_HOST_ROOT=/absolute/path/to/node_modules/@deepseek-ai/dsh pnpm test
+```
+
+未提供该路径时宿主集成测试会显式跳过；其余单测独立运行。测试覆盖状态转换、版本关系、并发、损坏状态、目录边界、注册及资源。真实模型的授权理解、Team 协作和中断恢复等行为验收见 [场景清单](tests/scenarios.md)；程序测试不能代替这些观察。
+
+## 文档
+
+- [设计](docs/design.md) 与 [提案](docs/proposal.md)
+- [Agent 角色调查](docs/research/agent-presets.md) 与 [开发模式调查](docs/research/development-mode.md)
+- [工作流调研](docs/research/workflow-survey.md) 与 [会话成本案例](docs/research/labwarden-session-cost.md)
+
+## npm 发布与 GitHub Actions
+
+包名为 `@fooksky/lodestar`，采用 [MIT 许可证](LICENSE)，发布到公共 npm registry。[GitHub 源码仓库](https://github.com/urzz/lodestar) 保持私有，npm 包公开，安装公开包无需 GitHub 仓库权限或 npm 登录。直接分发 ESM 源码、bundle patch、Skill、图标和文档，这些发布文件可被公开下载；无需构建产物，`npm pack` 和 `npm publish` 的 `prepack` 钩子会先执行语法检查与测试。
+
+[CI](.github/workflows/ci.yml) 在 `main` 分支推送、PR 和发布前运行，使用 Node.js 24 和最新版 pnpm，并安装固定版本的 DSH `0.2.2-rc.1` 执行真实宿主集成测试及打包预览。临时宿主与项目依赖分开安装，不修改任何本机 profile。
+
+[发布工作流](.github/workflows/publish.yml) 在推送 `v*` 标签时触发，等待完整 CI 通过，然后使用 Node.js 24、pnpm 冻结安装依赖，再通过 npm 11 和 GitHub OIDC Trusted Publishing 发布，无需长期 npm Token。私有源码仓库不支持 npm provenance，因此在 `publishConfig` 中显式关闭，适用于 Actions 和本地发布；仓库无需公开。稳定版本发布到 `latest`，含预发布后缀的版本发布到 `next`；标签必须严格等于包版本的 `v` 前缀形式。
+
+首次发布前需要完成：
+
+1. GitHub origin 和包元数据 `repository.url` 已指向 `urzz/lodestar`，保持两者与 Trusted Publisher 中配置的仓库一致；GitHub 仓库保持私有。
+2. 使用 npm 账号 `fooksky` 发布公开包 `@fooksky/lodestar`（公开 scoped 包免费）。如果 npm 尚无该包，先在受信任本机通过 `npm login --registry=https://registry.npmjs.org/`、`npm publish --access public --registry=https://registry.npmjs.org/` 完成首次发布，再配置自动发布；不要重复发布同一版本。npm 账号与 GitHub owner `urzz` 可以不同。
+3. 在 npm 包设置中添加 GitHub Actions Trusted Publisher：owner 填 `urzz`，仓库名填 `lodestar`，workflow filename 填 `publish.yml`，允许直接使用 `npm publish`。本工作流没有配置 GitHub Environment，该项留空。无需在 GitHub 配置 `NPM_TOKEN`。
+
+后续发布流程：
+
+```sh
+# 更新版本，再同步 pnpm 锁文件；暂不自动创建提交和标签
+npm version patch --no-git-tag-version
+pnpm install --lockfile-only --ignore-scripts
+# 审阅后提交版本文件，并创建匹配标签；示例版本需替换成实际版本
+git add package.json pnpm-lock.yaml
+git commit -m "chore: release v0.2.1"
+git tag v0.2.1
+git push origin main
+git push origin v0.2.1
+```
+
+若用 `npm version prerelease --preid=beta --no-git-tag-version` 更新版本，再按上述步骤同步锁文件、提交和打标签，发布工作流会自动选择 `next`。origin 和 npm Trusted Publisher 配置完成前，本地仍可运行 `npm pack --dry-run` 验证分发内容。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+- insert:
+    - id: dev-workflow
+      name: '@fooksky/lodestar'
+    - id: dev-workflow-preset
+      name: '@fooksky/lodestar/preset'
+      disabled: true

package/docs/branch-management.md

@@ -0,0 +1,60 @@
+# 分支与 worktree 隔离设计
+
+日期：2026-11-07。用户已确认完整 worktree 隔离、PR/MR 集成冲突和插件不承担调度，并明确授权在无新增待决事项时继续实现。本文把这些决定细化为实现契约；不包含安装、提交或推送授权。
+
+## 1. 边界
+
+一个独立需求默认对应一个 change、一条分支、一个 worktree 和一个 Lead。代码、`.dev-docs/knowledge/`、change 正文、state 和需要保留的证据全部位于当前 worktree。创建工作区继承基准提交中的知识快照，后续不实时读取其他 checkout 的材料，不使用共享材料根或符号链接。
+
+外部助手负责 Issue 领取、跨需求分配、创建/选择 worktree 和启动会话。本插件只负责当前分支内的流程与状态；不新增调度器、跨工作区扫描、全局 current change、分支创建/切换/删除、自动 Git 提交或 PR API。既有工作区由用户/外部助手通过 DSH 原生能力准备。同一需求内部仍可用原生 Teams，Lead 单 owner 写主材料。
+
+## 2. 当前工作区观察
+
+`dev_workflow` 增加只读 `action: workspace`。每个 action 在调用 Agent 的实际 cwd 和显式 projectRoot 上识别当前 Git checkout，返回有界 workspace 信息。Git 查询经宿主 subprocess 和调用会话的 sandbox policy 执行；不使用 Node child_process 或 shell，也不绕过文件 backend。Git 是运行依赖，缺少 Git/宿主服务、取消、权限拒绝、仓库损坏均保持错误，不伪装成非 Git。
+
+通过 Git 的明确“not a git repository”诊断识别普通目录；固定查询语言并清除改变仓库发现的 Git 环境变量。普通目录继续支持工作流。bare 仓库拒绝使用。Git 支持标准 checkout、linked worktree、子模块与项目子目录；projectRoot 必须存在。
+
+运行时信息包括实际 projectRoot、checkoutRoot、项目相对 checkout 的路径、分支和当前 HEAD。detached HEAD 可读不可写；unborn 命名分支允许使用，HEAD 为 null。分支和 HEAD 每次读取实际 Git 事实，不用 state 代替。
+
+Git 项目要求 Agent cwd 与 projectRoot 属于同一 checkout，不能从需求 worktree 指向主 checkout 的材料，即使会话有跨目录写权限。普通目录要求 projectRoot 位于 Agent cwd 内；cwd 可以是现有项目下任意目录，但 Git 情形仍按同一 checkout 判定。路径通过宿主 fs 规范化和 contains 比较，避免字符串路径别名绕过。
+
+## 3. 持久绑定与版本
+
+状态格式仅接受 `schemaVersion: 2`，`workspace` 必填，是以下二者之一：
+
+- Git：`{ kind: 'git', branch, baseCommit, projectPath }`。baseCommit 为首次绑定/重新绑定时的 HEAD，可为 null；它只记录来源，不参与 HEAD 相等或祖先检查。
+- 普通目录：`{ kind: 'directory' }`。
+
+不把机器绝对路径、session owner 或可变当前 HEAD 存入版本化 state；移动/重新检出到其他机器或目录无需重写绑定。changeId 保持需求身份，branch 只是工作区关联。相同分支名不构成跨仓库身份或安全证明，复制材料不自动表示已经接管需求。
+
+未知或旧 schema、缺失 workspace 均拒绝，不自动转换。list 不区分未受管目录；缺失或非法 state 的条目显示对应错误，不自动初始化或修复。
+
+`bind-workspace` 参数只有 reason，实际绑定由工具观察，不接受模型填写分支/路径/提交。用于命名分支重命名、确认后的分支接管、普通目录初始化为仓库后的显式重绑，不能修复缺失绑定或非法 schema。绑定作为独立 update，不能夹带业务变更；已有绑定替换时在 workspaceHistory 保留旧绑定、原因及时间，每项的 previous 必填。相同绑定重试不增加 revision；普通提交/rebase 后重复绑定同一分支和项目路径也不更新 baseCommit。
+
+## 4. 读写规则
+
+每个 action 的顶层 workspace 直接返回当前工作区观察，不嵌套 current/status；workspace action 不返回 bindingStatus。get 顶层 bindingStatus 仅为 matched、mismatch、detached，并以 binding 返回已存绑定；list 有效行 workspace 为已存绑定，同时返回 bindingStatus，顶层 workspace 仍为当前观察。历史 change 合入 main 后仍可 get/list，但不会自动把来源分支改为 main。
+
+create 自动绑定当前命名分支或普通目录。常规 update 在读 state 后、读取/发布业务变更前检查绑定。branch、项目相对路径或工作区种类不匹配时拒绝；缺失绑定的状态非法；detached 拒绝所有写入。绑定操作依然遵守 expectedRevision 和宿主 replaceIfVersion。
+
+绑定是状态工具自身的写入保护，不是 Git/工作目录锁，也不能限制其他文件工具。运行期间禁止外部切分支、搬移目录或清理 worktree；同一 checkout 不安排不同需求并发切换分支。同一 change 的多 Lead 业务所有权仍由明确交接保证，CAS 不充当任务锁。
+
+## 5. 工作流
+
+先由外部选择隔离 worktree，再查询 workspace、创建 change；只有做普通解释/调查时可以不建 change。材料始终以当前 worktree 为唯一权威，不能复制后两处继续写。本插件不自动搬移或提交。
+
+计划和委派包使用当前 worktree 的 projectRoot、changeId、预期分支和工作目录。知识只读写该分支的本地快照；跨需求依赖通过明确的 Git 集成引入。恢复先核对 workspace 和 change 绑定，再复用当前材料与授权；分支漂移不按相同 HEAD 猜测归属。分支重命名需要有理由的显式绑定，合入后的历史记录默认只读，不批量重绑。
+
+PR/MR 地址、源/目标分支、待评审/待合入结果及相关证据写入既有 plan/交付材料；状态机不接管远端 PR 生命周期。close 仍按本需求的验收契约：若合入是必需交付条件，合入及集成验证必须先满足；若交付边界是提交 PR，则 close 不声称已合入。PR 反馈修订沿用既有阶段退回、材料版本和证据失效机制。
+
+需要保留的代码、知识与 change 材料随分支提交，通过 PR/MR 集成；同一知识文件和 state 的冲突必须核对语义，不能把文本合并成功当验收通过。worktree 清理前保留未提交材料及证据，清理属于外部明确操作。数据库、端口、测试账号和外部资源按需求隔离，Git worktree 只隔离文件。
+
+## 6. 验证
+
+- 真实 Git 仓库建立两个 linked worktree，相同 change ID 各自保存、更新、知识修改互不影响；不读取主 checkout 实时知识。
+- 从 feature worktree 显式指向 main 材料根被拒绝；子目录项目在同一 checkout 可以使用。
+- 切分支后读显示 mismatch，普通写拒绝；显式绑定保留历史；分支正常提交或 rebase 不误锁。
+- detached 可读不可写，unborn 可写，bare/损坏仓库/缺少 Git/取消/权限错误不降级为普通目录。
+- 仅接受 schemaVersion: 2 且 workspace 必填；未知或旧 schema、缺失绑定拒绝，未受管目录在 list 中显示缺失或非法 state 错误；重绑历史 previous 必填，CAS 失败不发布。
+- 合并包含 change 材料后，目标分支可读历史且不会自动改其归属；移动工作区仍可按分支恢复。
+- 使用实际 DSH 文件、subprocess、sandbox 与注册服务测试；不安装到 profile。模型在真实 Issues/PR/Teams 中的长期行为另列为待观察，不用程序测试冒充。

package/docs/design.md

@@ -0,0 +1,342 @@
+# DSH 原生开发工作流首版设计
+
+> 历史范围：本文保留 `0.1.0` 首版设计和当时的验证记录。开发中的 `0.2.0` 分支扩展以 [分支与 worktree 隔离设计](branch-management.md) 为具体契约；涉及 schemaVersion、工具 action、项目根边界、worktree 与恢复的差异，以该扩展为准。下文的首版字段及“不强制 worktree”等表述不代表扩展后的规则。
+
+日期：2026-11-07。状态：首版设计、按需角色指引及可选开发模式均已获用户确认，用户已授权实施。首版代码已实现，程序及已安装宿主集成测试通过；未安装到本地/profile。真实模型行为验收尚未执行，状态见 [场景记录](../tests/scenarios.md)。
+
+依据：[提案 v0.4](proposal.md)。用户已确认：材料统一在 `.dev-docs/`，复用已有长期知识；首版插件负责 change 状态结构化读写，skill 负责工作流语义判断，DSH 原生能力负责任务执行；未来 hook 复用状态入口。本文已整合这些决定，替代此前纯 skill 与状态全放 plan 的草案。
+
+## 1. 目标和范围
+
+交付独立 DSH bundle，包含一个 `dev-workflow` skill 和一个 `dev_workflow` 状态工具。用户用自然语言开始或继续工作，不需要学习命令族。
+
+主流程：意图澄清及用户确认 → 具体方案及用户审核 → AI 生成 plan → 原生执行与必要验证 → 交付及必要知识更新。新项目按真实可运行的功能切片推进，同样遵循此流程。
+
+插件负责材料关联、change 状态、确认来源引用、验收结论索引和恢复信息；不执行或调度开发任务，不重做 Team、goal、压缩、浏览器、权限系统。首版没有数据库、新 UI、常驻文件 watcher、自动提交、推送、发布或安装。
+
+结构化工具可以阻止自身状态发生非法转换，不能阻止模型通过其他文件工具越过流程实施。确认来源的语义仍由 Lead 判断，不声称宿主级强制审批。自动安装到本地/profile 始终需要独立明确授权。
+
+## 2. 已核对的宿主接口
+
+本机核对基线为 DSH `0.2.2-rc.1`。以下来自公开类型与官方 Host 插件说明，尚不是运行验证结果。
+
+| 能力 | 已核对接口 | 设计用途 |
+|---|---|---|
+| Bundle | `dsh.bundle.patch` | 独立 Host 插件 |
+| Skill | `ctx.skills.register`，返回 disposer | 注册入口及包内资源位置 |
+| Tool | `ctx.tools.register`，返回 disposer | 注册状态工具，声明输入和 canonical output schema |
+| 工具结果观察 | `tools/result(exec, result)` | 后续订阅最终冻结结果；监听器错误由宿主隔离 |
+| 工具策略事件 | `tools/pre-execute`、`tools/execute`、`tools/post-execute` | 当前不使用，不改写其他工具策略或结果 |
+| 文件解析与边界 | `ctx.fs.resolve`、`contains` | 路径解析及材料目录包含关系 |
+| 文件读写 | `stat`、`readText`、`writeText` | 用 `createIfAbsent` 或 `replaceIfVersion` 原子写入 |
+| 原生 Team | 当前可用 `team_task_*`、成员与消息工具 | Agent 直接调用，不包装成第二执行引擎 |
+
+工具注册必须提供 `output.schema` 和 `output.render`；执行函数接收调用上下文并遵守取消信号。项目文件通过调用方对应的宿主文件能力和实际 sandbox policy 访问，不通过裸 Node fs 绕过会话权限。Node 文件读取只用于插件自己的随包只读资源。
+
+已进一步核对原生文件工具调用链：通过 `ctx.workingDirectory.ensure(exec.agent, exec.signal)` 获取调用 Agent 的当前目录，作为 fs.resolve 的 cwd；通过 `ctx.sandboxPolicy.resolve({ session: exec.agent.session })` 获取会话实际策略并传入 writeText。权限中的 workspace root 来自宿主会话策略，不由工具传入的 projectRoot 覆盖。projectRoot 只选择材料位置，不扩大授权边界。
+
+首版工具要求存在调用 Agent，不接受缺少会话身份时退回进程 cwd。需要隔离的服务使用调用 Agent 对应的 scope；集成测试验证不同会话不会串用目录或策略。文件 backend 提供 sandboxMode 时必须有 sandboxPolicy；非沙箱 backend 沿用宿主无策略语义。首版不提供自行提权参数，拒绝写入时原样报告权限问题；不临时换路径或裸 fs 重试。上述来自原生代码核对，尚待运行集成验证。
+
+首版不依赖尚未核对的 Team 专用事件，也不假定 `tools/result` 是持久、可回放或 exactly-once 事件流。
+
+## 3. 模块与数据归属
+
+```text
+用户 ↔ Lead / dev-workflow skill
+          ├─ 原生 Teams、文件、测试、浏览器等工具
+          ├─ Markdown 需求、方案、计划及知识
+          └─ dev_workflow 工具
+                  ↓
+             状态更新模块 ← 后续原生事件适配器
+                  ↓
+             宿主文件能力
+                  ↓
+             state.json
+```
+
+| 模块 | 职责 |
+|---|---|
+| Host 入口 | 注册 skill/tool、依赖与生命周期清理 |
+| Skill 及阶段参考 | 需求与方案判断、确认复用、任务组织、验证与交付 |
+| Tool 边界 | 参数 schema、调用者上下文、错误和有界结果展示 |
+| 状态模块 | 领域操作、前置条件、材料版本关系、状态变更 |
+| 文件仓储 | 路径边界、读写版本、原子发布、读取损坏报告 |
+| 后续 hook 适配器 | 将可识别原生事实映射为有限观察记录，调用同一状态入口 |
+
+状态模块不依赖模型工具调用形式；以后 hook 可以直接调用其内部方法。首版不注册 hook，只建立可复用模块边界。
+
+Markdown 是语义正文的权威；state 是本工作流状态和关联的权威；DSH 是原生执行事实的权威。state 中的原生引用或观察不反向覆盖 Team。程序不会从“任务全部完成”推断“需求已满足”。
+
+## 4. 文件布局与知识复用
+
+```text
+.dev-docs/
+  index.md
+  knowledge/                    # 沿用已有主题，不强制目录模板
+  changes/
+    <change-id>/
+      intent.md
+      spec.md
+      plan.md
+      state.json
+    archive/                    # 保留已有历史
+  artifacts/                    # 按需，避免复制宿主已有大日志
+```
+
+默认 change ID 为 `YYYYMMDD-short-slug`，冲突才增加短后缀。ID 是稳定身份，标题可修改；目录名不表达当前状态。根目录由当前项目及用户范围确定，工具每次显式接收 `projectRoot`，不维护全局“当前 change”。非 Git 项目使用明确工作目录。多候选恢复时先列标题与状态，无法确定再请用户选择。
+
+复用本 worktree 的 `.dev-docs/index.md`、`knowledge/` 和已有项目文档，不重命名或添加强制 frontmatter。工作流确认与完成记录必须引用实际用户表达和验收证据。
+
+项目材料可纳入版本控制，但不自动暂存或提交。完成后保留 change 原路径，状态设为 done；不增加自动搬移归档流程。大截图与日志以引用为主，需要长期保留时才放 artifacts。list 对未受管目录按常规读取规则报告缺失或非法 state 错误，不自动初始化或重建。
+
+## 5. 人可读材料
+
+### 5.1 intent
+
+保存原始诉求或准确引用、真实需求、使用场景、目标、范围/非目标、重要约束及待明确问题。用户纠正后更新当前内容，关键理由就近记录。不把模型猜测当作确认需求。
+
+### 5.2 spec
+
+保存预期行为、影响范围、模块职责和数据流、必要接口/数据变化、关键取舍及验收要求。验收项使用稳定 `A1、A2…`；编号删除后不分配给新含义。spec 引用 intent，不复制背景全文。
+
+### 5.3 plan
+
+保存实施步骤、依赖、写入范围、验证方法及取舍。步骤可用 `P1、P2…`，关联验收 A 编号。原生任务绑定、动态进度与验证结果保存在 state，不手动重复勾选。
+
+Team 模式任务状态只从原生任务板获取；直接执行时 state 可保存步骤进度。两者按步骤明确模式，不把 Team 步骤的 status 再保存一份。
+
+三份正文按规模撰写，每份可只有几行，无强制篇幅。仅 Lead 修改主材料。intent 在澄清时创建，spec 在设计时创建，plan 在实施授权后创建；不预建空模板树。
+
+### 5.4 长期知识
+
+长期知识继续用 Markdown，保存当前稳定事实、约束、架构与运行方法。既有 README/架构文档只引用，不复制。知识入口只路由主题，不维护第二张 changes 列表。
+
+如有真实检索需求，可在新增或实际修改主题中添加少量 YAML frontmatter（稳定 id、关联 change）；首版不要求。未来检索索引应能从正文重建。调试过程、工作进度和临时猜测不沉淀为长期知识。Mnemon 和 BrowserSkill 均可选。
+
+## 6. state.json 的领域结构
+
+采用 JSON，UTF-8、两空格缩进、文件末尾换行；机器写入，不要求用户手工编辑。YAML 留给确有人工配置需求的场景，不同时维护 YAML/JSON 状态副本。
+
+| 字段 | 结构及职责 |
+|---|---|
+| schemaVersion | 仅接受整数 2；未知或旧版本拒绝，不猜测转换 |
+| workspace | 必填；当前分支或普通目录的持久绑定，具体结构见分支隔离设计 |
+| workspaceHistory | 重绑历史；每项的 previous、reason、recordedAt 必填 |
+| id、title | 稳定 change ID 和显示标题 |
+| revision | 每次成功状态变更递增，初始为 1；用于调用方 CAS |
+| createdAt、updatedAt | 由插件生成的 UTC 时间，仅描述写入时间 |
+| documents | intent/spec/plan 的当前登记版本、相对路径、内容摘要与依赖 |
+| workflow | phase、status、reason、nextAction |
+| decisions | 用户确认/审核/实施授权及撤回的引用记录 |
+| acceptance | 当前验收 ID、spec 版本、定位锚点、是否 required |
+| execution | 步骤与验收关联；direct 或 native 模式；原生来源引用 |
+| verification | 验收结论、适用版本、被测对象/环境、证据引用 |
+| blockers | 尚未解决的具体缺口及其解决记录 |
+| closure | done 时的交付说明与证据关联；未完成时缺省 |
+
+不保存工具全文输出、完整聊天或图片。记录数组使用工作项内稳定 ID；修正已有结论用新记录标明 supersedes，避免原结论静默变成另一个事实。首版不建立通用事件日志。
+
+文档登记项包含 `version`（正整数）、`path`、`digest`（规范化换行后正文 SHA-256）、`basedOn`（spec 对 intent，plan 对 intent/spec）。首次为 1，语义变化递增；纯排版修改可更新 digest 并提供理由，不递增语义版本。所有正文应由宿主文件工具写好后再登记，插件不生成或重写正文。
+
+摘要用于发现登记后正文变化，不能判断语义。get 返回检测结果而不偷偷改状态；正文不匹配时，新的确认与推进操作拒绝继续，要求先登记变化。格式修订必须由 Lead 声明，不由程序从 diff 自动推断。
+
+文档修改与 state 更新不是多文件事务；“正文先成功、登记未完成”是允许恢复的中间状态，恢复通过 digest 不匹配识别。重要转换前核对文档版本；不承诺在其他 Agent 同时写正文时实现跨文件隔离，主材料仍为单 owner。
+
+## 7. 确认、版本与验证记录
+
+### 7.1 确认记录
+
+decision 字段：`id`、`kind`、`subjects`（材料及语义版本）、`scope`（全范围或具体差异）、`source`、`recordedAt`、可选 `supersedes/revokes`。kind 为 `intent-confirmation / spec-review / implementation-authorization / revocation`。
+
+source 保存真实用户表达的短摘录，能取得时附 session ID 和 event seq；没有可定位事件时保存当前用户表达与上下文说明，标记为 Agent 记录，不伪造事件号。程序检查结构和版本关联，不声称能证明用户语义或防伪。
+
+同一句“需求和方案没问题，按这个做”可在一个状态更新中登记三类决定，引用同一来源。“设计没问题，先别做”只登记审核，不登记实施授权。用户跳过、沉默、工具审批通过或 goal 续轮都不是决定来源。
+
+语义升版后旧决定保留历史但不适用于新版本；用户已明确批准本次差异时，新增覆盖新版本的决定并引用该表达，无需重问。排版更新不自动撤回确认。恢复可以复用来源明确、范围匹配且未撤回的记录；来源模糊时才定向查询历史或询问。
+
+### 7.2 验收与验证
+
+acceptance 是验收索引，不复制 spec 的全部文字。修改 spec 后 Lead 显式提交当前索引，程序核对 ID 唯一及引用存在，语义对应由 Lead 判断。
+
+verification 字段：`id`、`acceptanceIds`、`specVersion`、`outcome`、`method`、`subject`、`environment`、`evidenceRefs`、`summary`，可选 `supersedes` 或 `carriedFrom`。outcome 为 passed/failed/not-run/not-applicable/stale。时间由插件记录；实际观察时间可单独提供。
+
+passed 必须有依据引用；not-applicable 必须说明原因，并且不能满足仍标为 required 的验收。必需项取消必须修订方案索引，不能靠“不适用”绕开。
+
+需求、相关实现、验证方法或环境变化后，Lead 标记受影响记录 stale。新 spec 下可以显式沿用仍有效的结果，生成引用旧证据的新记录并说明适用理由；版本变化不要求全量重跑。compact、任务重排、无关文档修改不自动失效。
+
+被测对象需要足够定位实际产物：未提交修改不能只用 HEAD，远端页面不能只用 URL。程序不维护全代码依赖图，不自动证明证据仍适用。
+
+## 8. 工具 API
+
+仅暴露 `dev_workflow`，以 action 区分四类操作。每次提供 projectRoot；changeId 是单一路径段，不能包含目录跳转。所有路径经宿主解析，并限定在当前授权项目的 `.dev-docs/changes/<id>/` 内；证据外部路径只作引用，不作为写入目标。不会接受任意 state 文件路径。
+
+| action | 输入 | 输出 |
+|---|---|---|
+| list | projectRoot、可选 limit/cursor | change 标题、ID、阶段、revision；不读取全部正文；默认 20 条 |
+| get | projectRoot、changeId、可选 section | 当前状态或指定部分、材料一致性检查、当前阻断 |
+| create | projectRoot、changeId、title | 创建初始 state；已有目标时报冲突，不覆盖 |
+| update | projectRoot、changeId、expectedRevision、operations | 原子提交全部操作，返回新 revision 和变更摘要 |
+
+update 为一组有类型的领域操作，不接受任意 JSON Patch 或全文件替换：
+
+| operation | 关键输入与约束 |
+|---|---|
+| register-document | kind、semantic/format 分类、basedOn、reason；插件读取固定文件并计算 digest |
+| record-decision | 决定类型、当前 subjects、source、scope；可登记撤回 |
+| set-acceptance | 当前 specVersion 与验收索引；不得引用未登记 spec |
+| bind-step | stepId、acceptanceIds、mode；native 附原生引用，direct 附初始进度 |
+| set-step-progress | 仅 direct 步骤，pending/in-progress/completed 及必要说明 |
+| record-verification | 验证记录及证据引用；只能引用已登记验收 |
+| invalidate-verification | 验证 ID 集合、明确失效原因 |
+| set-blocker | 稳定 blocker ID、说明、open/resolved、解决依据 |
+| set-workflow | 目标 phase/status、reason、nextAction；通过阶段约束才保存 |
+| close | 交付摘要、必需验收关联、需求满足说明与知识处理结论 |
+
+一个 update 可原子登记一条用户表达产生的多项决定。每次最多 32 个操作，防止把完整运行日志作为一次更新。相同记录 ID 且内容相同可视为无变化，不增加 revision；同 ID 不同内容报冲突。不会因失败而部分提交。
+
+成功输出包含 `id/revision/changed/summary`；get 的全文状态按 section 返回，不自动附带 Markdown 正文。失败返回稳定分类及修正信息：NOT_FOUND、ALREADY_EXISTS、REVISION_CONFLICT、DOCUMENT_CHANGED、INVALID_TRANSITION、INVALID_REFERENCE、INVALID_STATE、UNSUPPORTED_SCHEMA。文件权限及取消等宿主错误保留原上下文，不转为默认成功。
+
+修改失败后 Agent 重新 get 并重做所需语义合并，不盲目重发。回执丢失时先 get 核对具体记录 ID 与内容，再决定是否重试。工具不提供删除 change、搬移历史或自动覆盖损坏状态的 action。
+
+## 9. 阶段约束
+
+phase：intent/spec/plan/execute/deliver/done。status：active/waiting-user/blocked/paused；done 时 status 为 active，表示已正常闭环，不另复制 completed 状态。
+
+| 推进 | 工具可检查条件 | Lead 必须判断 |
+|---|---|---|
+| intent → spec | intent 已登记且存在当前版本确认 | 用户真实需求已识别 |
+| spec → plan | 当前 spec 依据当前 intent；当前审核与实施授权存在 | 具体方案足够可实施 |
+| plan → execute | plan 依据当前 I/S；验收索引、步骤及关联有效 | 实施路径和验证合理 |
+| execute → deliver | 所有 required 验收有当前有效 passed；无 open blocker | 真实需求满足、集成完整 |
+| deliver → done | close 材料齐全，前述约束仍满足 | 可交付，无需继续扩张范围 |
+
+任意目标阶段都检查该阶段及其前置阶段的全部条件，不能用 set-workflow 跳过审核。进入 done 只能使用 close；set-workflow 可以退回已完成项，但不能直接设置 done。必需验收集合不得缺失；若任务确实没有适用验收，必须先在已审核 spec 中说明，并登记显式无适用验收的依据，不能靠空集合自动通过。
+
+调查可在确认前进行，但不写业务实现、脚手架或原型。仅要求设计时，到 spec 后交付方案并停止；不创建实施 plan 或使用 goal 推进编码。
+
+重要材料语义升版的同一 update 必须将阶段退回相应层：intent/spec/plan。系统不允许旧阶段留在 done/execute 而依据已经失效；同一更新若也登记了明确的新决定，可在最终校验通过后进入允许阶段。不机械要求固定轮数。
+
+局部修代码或调整分工不更改需求与框架方案，不重新审批。方案改变先暂停受影响成员；用户新增独立需求创建独立 change，只有用户明确纳入当前范围时才修订当前 intent。done 后的新独立需求不自动 reopen 旧项；原交付问题可通过 set-workflow 退回对应阶段并记录原因。
+
+暂停、等待、阻断均保留阶段。用户说“继续”解除的是暂停/恢复执行意图，不自动填补缺失的需求或方案决定。
+
+## 10. 存储一致性与并发
+
+每次 update：解析边界 → 读取有效 state 及宿主版本 → 比较 expectedRevision → 应用领域操作 → 检查最终状态及涉及材料 → revision 加一 → `writeText` 携带 replaceIfVersion 发布。create 使用 createIfAbsent。
+
+读取采用 stat/read/stat 稳定观察，版本变化则返回冲突要求重读，避免把旧正文与新文件版本错误配对。并发写入最终由宿主条件写入裁决。复用宿主原子写入及版本保证，不自行实现锁文件、重试循环或 JSON 双份备份。
+
+插件只能协调遵循接口的写入；人工改 JSON、跨进程外部修改的保护强度服从宿主 backend 的保证。schema 错误或损坏必须可见；不能用空对象重新初始化。首版不支持多个独立 Lead 同时拥有同一 change 的主材料，状态 CAS 不等于业务所有权锁。
+
+仅接受 schemaVersion: 2 且 workspace 完整的状态。未知或旧 schema、缺失绑定均报错，不转换或覆盖；bind-workspace 只能重绑有效状态，不能修复这些错误。
+
+## 11. 原生协作与未来 hook
+
+小任务 Lead 直接执行，有界独立调查使用 subagent，有清楚的并行工作包时使用 Teams；不固定成员数、评审人数或强制 worktree。
+
+原生任务包含目标、A/P 引用、必要资料、交付内容、write_scopes 和依赖。成员按 list/get/claim/update 的 revision 契约工作。write_scopes 只是提示，重叠文件必须指定 owner 或串行交接。依赖就绪不自动唤醒成员，Lead 显式发送消息。inactive 不等于 completed，completed 不等于业务验收通过。
+
+成员通过原生任务/消息返回结果；Lead 更新主材料和 change 状态。状态工具首版不额外实现 Lead 身份鉴权，但 skill 明确单 owner。必要的宿主权限检查仍沿用原生机制。
+
+后续第一类 hook 推荐只观察 `tools/result`，按已绑定 session/call/任务及明确工具类型映射。没有可证明关联的事件忽略，不能按“最新 change”猜归属。首先接入可验证的工具成功/失败与原生查询观察，不截获或替换其他工具结果。
+
+适配器调用内部 `recordObservation`，该方法只更新 namespaced observations，不得创建用户确认、审核、passed 验收或 done。首版无需为此创建空 observations 字段。原生状态只是带来源、观察时间的缓存，关键决策仍查询宿主。
+
+`tools/result` 没有提供持久回放保证：重复按调用身份与结果种类去重；迟到事件不能按到达时间覆盖更新的源 revision；没有可比较 revision 时只标记需要重新查询，不猜全序。漏事件由恢复时原生查询补齐。同步写入失败应留下可见诊断，不改变原工具已经发生的结果，不承诺 exactly-once。
+
+hook 注册必须按 scope 隔离，并在插件卸载时清理；不会扫描其他无关会话。首次 hook 迭代需核对实际 Team 输出契约、来源身份和事件覆盖，再确定映射，不依赖私有日志文件。
+
+## 12. 验证、收敛与恢复
+
+plan 选择与风险相称的静态检查、测试、构建、API/CLI 和浏览器验证。替代方法需证明同一命题；fixture、截图生成、编译通过不能各自冒充真实集成、实际观察或交互验收。
+
+视觉检查只覆盖相关场景，按小包及时记录结论。已有明确全量覆盖要求时必须完成，不能静默抽样。连续两次同类失败无新证据时改变诊断或方法，不降低标准。已满足需求与规格且必需验收通过即收敛，新增想法不扩大范围。
+
+恢复顺序：显式 change 或确定绑定 → get 状态和一致性提示 → 当前 intent/spec 及 plan 相关段 → 必要源代码/产物 → 原生任务与成员 → 缺口对应的历史事件。避免全量读取旧对话与知识。
+
+同会话查询实际任务和仍在写入的成员；跨会话旧 Team 不可达时，核对已有成果并只为未完成部分创建新任务。原任务引用作为历史保留并标明替代关系。无法确认旧成员是否继续写入时先解决归属，不能在同路径重复开工。
+
+读取状态不会自动重验。验证回执未知时先检查 job/日志；证据确实丢失且无法支撑必需结论时才补验。正文已经改而 state 未登记时先核对差异，登记后再推进；不要回滚用户文件来迎合旧状态。
+
+done 必须有当前有效验收及无阻断；缺必需环境只能报告“已实现，验证未完成”。知识处理可以是“无稳定知识变化”，不强制制造总结文档。
+
+## 13. 包结构与实现范围
+
+```text
+package.json / cordis.patch.yml / index.js
+src/tool.js
+src/state.js
+src/store.js
+src/schema.js
+skills/dev-workflow/SKILL.md
+skills/dev-workflow/references/{intent,spec,plan,execute,recover,delegation}.md
+locale/{en,zh}.json / icon.svg
+tests/{registration,state,store,resources}.test.js
+tests/scenarios.md
+```
+
+ESM JavaScript，采用 node:test；无需前端或转译器。schema 模块提供工具输入输出与状态验证，选用宿主兼容的现成 schema 能力，不能自己实现一套通用 schema 解释器。
+
+Host 注入 skills/tools/fs/workingDirectory，并在沙箱文件 backend 下要求 sandboxPolicy；直接使用的宿主依赖按核对版本声明。包名建议 dsh-dev-workflow，开发期 private，版本 0.1.0；license 和公开分发在发布前确定，不阻塞设计。打包范围明确包含 src、入口、patch、skill 参考、locale 和 icon。
+
+实施顺序：状态领域与 schema → 文件仓储与工具边界 → skill 和阶段参考 → 包注册与文档 → 集成及真实场景验收。状态模块先实现并测试，不先搭空 hook 框架。安装测试环境需授权，不将设计确认解释为 profile 安装授权。
+
+## 14. 验收方案
+
+| 层次 | 核心检查 |
+|---|---|
+| 状态单测 | 阶段约束、确认复用/撤回、同回合多决定、版本依赖、验收引用、局部失效、close 阻断 |
+| 存储测试 | 创建冲突、两次并发更新仅一次成功、正文未登记、JSON 损坏、未知版本、路径逃逸、写入失败保持旧状态 |
+| 恢复测试 | 正文已改但登记未完成、状态已提交但回执丢失、原生任务不可达、非法或缺失 state 不自动重建 |
+| 注册与包 | skill/tool 注册及清理、缺资源失败、输出 schema、真实打包资源完整 |
+| 宿主集成 | 正确 cwd/scope/sandbox；skill 可发现及加载；tool 按权限读写；停用后移除本插件贡献 |
+| 真实模型场景 | 四类提案场景，以及只设计、确认复用、Team 协作、中断恢复、浏览器缺失等变体 |
+
+四类核心场景：增量顺序交付；实现满足 spec 但 intent 不足；多轮 intent/spec/plan 变化；从空项目到真实 MVP 闭环。确认前无业务实现、无需重复确认、局部返修和有效证据复用必须在会话行为中观察，静态测试不能替代。
+
+记录具体失败与阻断、交付通过情况，以及可得的 Lead/成员总耗时与 token；指标不可得则明确缺失，不引入私有日志解析依赖。不因成本目标降低验收要求。
+
+## 15. Agent 角色与 preset
+
+调查依据见 [Agent 预设调查](research/agent-presets.md)。用户已认可首版提供 implementer、reviewer、verifier 三种按需角色指引，放在 delegation 参考中；不为每个成员角色注册独立 DSH Agent preset。这与将整套流程提供为一个开发模式不冲突。
+
+Lead 使用当前 Agent，持有流程和状态写入职责。implementer 完成明确工作包；reviewer 针对实质风险独立审查，默认不改文件；verifier 实际检查验收并提供证据，默认不改产品代码。角色不对应强制阶段，小任务仍可由 Lead 完成，不预建固定 Team。
+
+当前 Team spawn_teammate 没有逐成员 preset 参数。普通 subagent 可在宿主配置允许且 provider 支持时选择 preset，但本会话未暴露该参数；不能假设 fork 能独立换能力配置。角色指引由 Lead 连同范围、材料版本、验收、写入范围、停止条件和输出要求传入原生成员 prompt。
+
+角色提示不是权限隔离；真正只读或专用工具集需求出现时，再设计可选原生 preset 和宿主接入。首版不修改用户默认 preset、不固定模型厂商、不另建成员创建工具。
+
+## 16. 可选开发模式
+
+详细证据和取舍见 [开发模式调查](research/development-mode.md)。用户已接受：在核心之后交付一个可选的 dev-workflow preset，显示名“开发工作流”。
+
+模式复用同一 skill/状态工具，增加短入口提示和经过验证的原生能力组合；核心仍可在其他兼容模式使用。利用原生新会话模式选择器，不新增 UI。模式选择不等于实施授权，不创建 change 或预启动成员；受委派成员遵循任务包，不重复进入 Lead 流程。
+
+首个验证组合包含文件/搜索/shell/jobs、skill、用户交互、历史查询与 Team 协作；普通 subagent 仅在实际部署提供时使用。浏览器、记忆及其他集成为按需能力。模型、权限、账号和默认模式保持用户配置。
+
+PresetDefinition 没有直接 extends 字段；不复制整份基础 profile，也不动态修改用户 Standard 模式。采用显式有界声明复用宿主能力，必要的模式贡献在正确 scope 注册；提供服务的子配置必须正确 isolate。全局工具可能仍可见，不宣称 preset 天然隔离工具或权限。
+
+模式仅能在会话首轮前选择。运行中通过核心 skill 使用流程，或新建开发会话恢复既有 change。注册/安装与会话选择分开，不能自动设置为默认或切换现有会话。核心与模式适配入口同仓库分离，先不拆多个包。
+
+增加的验收重点是：实际工具视图、无服务泄漏或重复注册、普通模式不受影响、成员继承和职责正确、只设计请求不越界，以及升级/停用/恢复的实际行为。不在没有运行证据时承诺降低 token 或提高成功率。
+
+## 17. 当前设计状态
+
+架构、目录、状态工具、版本契约、按需角色指引及可选开发模式均已获用户认可。没有阻塞首版实施的产品或架构选择需要用户补充。
+
+剩余工作分为：实现时确定并测试具体 schema、包入口和 preset 配置；通过宿主集成验证 scope、文件策略、实际工具视图、成员继承及升级/恢复；发布前确定 license 和公开分发方式。后续 hook 事件映射不属于首版。技术验证如推翻已确认边界，再报告具体影响，不为常规实现细节重复审批。
+
+首版实施已获授权，具体工具字段以 src/schema.js 为准。实现补充：bind-step 可在提供 reason 后替代原绑定，previousBindings 保留原生任务来源；材料目录/文件拒绝符号链接；可选 preset 显式要求部署提供必要原生能力，缺失时报告配置问题。未修改用户 profile 或默认模式。
+
+## 18. 开发中的分支扩展
+
+完整契约见 [分支与 worktree 隔离设计](branch-management.md)，模型使用规则见 [工作区参考](../skills/dev-workflow/references/workspace.md)。扩展保留既有阶段、授权和验收状态机，增加当前工作区观察及状态写入绑定，不增加调度器。
+
+- 独立需求默认独立 change、分支、worktree 和 Lead。外部助手负责 Issue 领取、分配、准备 worktree 和启动会话；同一需求内仍用原生 Teams。代码、知识、change 和需保留的证据全部位于本 worktree，知识来自基准提交快照，不共享材料根或实时读取其他 checkout。
+- action 增加只读 workspace；每个 action 顶层 workspace 按实际 cwd/projectRoot 直接返回实时工作区，无 current/status 嵌套。workspace action 无 bindingStatus；get 顶层 bindingStatus 仅为 matched/mismatch/detached，binding 为已存绑定；list 有效行 workspace 为已存绑定并附 bindingStatus，未受管目录显示缺失或非法 state 错误。Git 项目根与 cwd 须属同一 checkout，普通目录根须在 cwd 内。detached 只读，unborn 命名分支允许使用，bare 拒绝；Git、宿主、权限、取消或损坏错误不降级成普通目录。
+- 状态格式仅接受 schemaVersion: 2，workspace 必填，Git 绑定为 `{ kind: 'git', branch, baseCommit, projectPath }`，普通目录为 `{ kind: 'directory' }`。未知或旧 schema、缺失绑定拒绝，不自动转换或修复。baseCommit 可为 null，只记绑定来源，不做 HEAD 相等或祖先检查；不持久化机器绝对路径、session owner 或可变当前 HEAD。
+- 分支改名、已有明确接管依据或普通目录初始化为仓库后，单独 update/bind-workspace，仅提供 reason 和当前 expectedRevision，不夹带业务操作。重绑通过 CAS 更新，workspaceHistory 每项的 previous、reason、recordedAt 必填；不能用来修复缺失绑定或非法 schema。相同绑定不增加 revision，普通提交/rebase 不刷新原 baseCommit。mismatch 拒绝普通写；合入历史不自动改归属。
+- 绑定只保护状态工具的写入，不充当 Git 锁或 Lead 所有权锁。运行期间不得外部切分支、搬移或清理 worktree；正文与其他文件工具同样须遵守工作区约定。计划和委派包包含本 worktree 的 projectRoot、changeId、预期分支及工作目录，恢复先核对工作区与绑定。
+- PR/MR 地址、源/目标分支、评审/合入结果和证据沿用 plan/交付材料。合入是否为 close 前提由需求验收决定；PR 反馈沿用阶段退回、版本与证据失效机制。知识/state 冲突需要语义核对，文本合并不等于验收；提交和清理仍需对应授权。端口、数据库、账号等资源按需求另行隔离。
+
+扩展的程序验证和真实行为观察分开记录在 [场景记录](../tests/scenarios.md)；首版通过记录不构成扩展已通过的证据。