npm - @namewta/speculo - Versions diffs - 1.0.22 → 2.0.1 - Mend

@namewta/speculo 1.0.22 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1079) hide show

package/template/workflows/specdev/common/README.md CHANGED Viewed

@@ -24,10 +24,18 @@
 - 代码库设计：`<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`
 - 父实现编排：`<Path>{roots.workflows}/specdev/common/rules/parent-implementation-orchestration.md</Path>`
+## 按风险加载工程标准
+- 设计或执行失败、重试、取消、未知结果时读取 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path>。
+- 异步、并发资源、CI flake 或删除替换测试时读取 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path>。
+- 项目文档的当前事实、归属、升级说明和语义保真使用 <Path>{roots.workflows}/specdev/common/rules/documentation-standard.md</Path>，注释仍由原注释规则负责。
+- 工具定义、prompt、Work/Skill 或上下文加载变化时读取 <Path>{roots.workflows}/specdev/common/rules/agent-experience.md</Path>。
+- 仅新专业分支记录 <Path>{roots.workflows}/specdev/common/rules/engineering-evidence.md</Path>；它是原报告中的观察，不是新的任务状态。
 ## 结构化工件 Schema
 - 全局配置：`<Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path>`
-- 全局状态：`<Path>{roots.workflows}/specdev/common/schemas/status.schema.json</Path>`
+- 新业务工件生命周期：<Path>{roots.workflows}/specdev/common/rules/workflow-state-and-lifecycle.md</Path>；旧 status schema 只用于历史/显式转换，普通 Work 不读写镜像。
 - 单 change 生命周期状态：`<Path>{roots.workflows}/specdev/common/schemas/change-status.schema.json</Path>`
 - Spec：`<Path>{roots.workflows}/specdev/common/schemas/spec.schema.json</Path>`
 - Ticket：`<Path>{roots.workflows}/specdev/common/schemas/ticket.schema.json</Path>`
@@ -43,7 +51,7 @@
 - 捕获账本：`<Path>{roots.workflows}/specdev/common/schemas/capture.schema.json</Path>`
 - 诊断：`<Path>{roots.workflows}/specdev/common/schemas/diagnosis.schema.json</Path>`
 - 代码审查：`<Path>{roots.workflows}/specdev/common/schemas/code-review.schema.json</Path>`
-- UI 设计包：`<Path>{roots.workflows}/specdev/P-prototype/design-package.schema.json</Path>`
+- UI 设计包：`<Path>{roots.workflows}/specdev/specdev-p-prototype/assets/design-package.schema.json</Path>`
 ## 工具与 Skill
@@ -51,7 +59,7 @@
 - 校验器说明：`<Path>{roots.workflows}/specdev/common/tools/README.md</Path>`
 - 外部技术研究 Skill：`<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`
 - Ticket worktree Skill：`<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`；仅 required Ticket 使用 source → parent-candidate → parent 状态机，current Ticket 使用 current workspace/direct-parent
-- 动态 Agent 交付合同 Skill：`<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`；P-goal-plan 可建立子 change Lead 合同，I-implement 在执行期派单与验收，Goal 编排的全局门约束
+- 动态 Agent 交付合同 Skill：`<Path>{roots.references}/coordination/task-brief.md</Path>`；P-goal-plan 可建立子 change Lead 合同，I-implement 在执行期派单与验收，Goal 编排的全局门约束
 - 双轴代码审查 Skill：`<Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`
 ## 加载原则

package/template/workflows/specdev/common/rules/activation-and-memory.md CHANGED Viewed

@@ -4,11 +4,15 @@
 ## Locate before read
-1. 先打开 `<Path>{roots.state}/workspace.json</Path>`，从中解析当前 workflow 的 roots、状态索引和稳定 ID；roots 必须来自该文件，不得凭字面猜测。不存在时静默跳过，不能凭旧路径猜测。
+1. 复用当前入口已经明确的项目、方法和数据根。已安装时验证 workspace roots；未安装时使用明确根参数与 Skill 内相对资源，不猜旧路径。根不明只阻塞依赖它的写入；按稳定名称定位所需对象。
 2. 根据当前请求、Work 分支、关键词、稳定 ID、状态和 provenance，先搜索相关索引行或目录项，再定位最小相关 entry；不把索引全文默认装入上下文。
 3. 只回读命中的 entry 和直接 provenance；需要恢复、冲突裁决、归档、迁移或执行安全证明时，才读取该阶段声明的完整证据集合。
 4. 没有匹配证据时返回缺失证据并停止依赖该结论的分支，不补造事实。
+## Design retrieval
+UI 工作先按 <Path>{roots.state}/specdev/design/</Path> 的索引条目或 scope/规则 ID 定位，再读取命中的 DESIGN revision 和来源。已有 change DESIGN 按它固定的 baseline revision/digest 回读，不静默换成最新版本。永久设计的唯一 owner 是 A，网关为 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/references/design-knowledge-gateway.md</Path>；首次批准和归档提升遵守 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path>。
 ## Memory writes
 正式知识、永久 context、synthesis 或 archive 写入前，先解析唯一 owner 与 gateway，检查 pending transaction、lock、未完成 promotion 和 recovery evidence。gateway 不明或事务未闭合时，只阻塞记忆写入，继续独立且已授权的审计、定位、验证和其他工作。

package/template/workflows/specdev/common/rules/adr-format.md CHANGED Viewed

@@ -2,13 +2,13 @@
 本格式用于 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`。这里的 ADR 是当前 change 的架构决定合同，不是已经提升到永久 `<Path>{roots.state}/specdev/adr/</Path>` 的项目 ADR。
-只有一个决定同时满足以下三个条件才写 ADR：
+决定对未来有持续价值时写 ADR，以下特征是判断线索，不要求同时满足：
 1. 难以逆转；
 2. 没有上下文会令后续维护者惊讶；
 3. 来自真实可行方案之间的权衡。
-局部、可逆或没有实质替代方案的选择留在 Ticket/代码。一个 ADR 只表达一个决定。
+局部且无持续价值的选择留在 Ticket/代码；可逆不是拒绝保存重要理由的充分条件。没有真实替代方案时写明事实，不编造权衡。一个 ADR 只表达一个决定。
 ```markdown
 ## ADR-###: <标题>
@@ -35,4 +35,4 @@
 `accepted` 只表示用户已接受该决定作为当前 change 的下游合同；它不证明实现已经落地，也不代表永久知识毕业。修改已接受决定时新建 change ADR 并建立 supersedes 链，不重写历史。
-只有 A 在 change 完成后对照代码、测试和 Evidence 重新验证，并通过毕业评估与用户确认，才能把决定写为永久 ADR；不通过的决定随归档 change 保留。
+只有 A 对照真实来源重新验证，并通过适用价值评估与具体批准，才能提升或独立维护永久 ADR；完成来源以代码、测试和 Evidence 核对，取消来源不能把未实现计划写成现状；不通过的决定随归档 change 保留。

package/template/workflows/specdev/common/rules/agent-experience.md ADDED Viewed

@@ -0,0 +1,29 @@
+# 面向 Agent 的工具与 Work 体验
+修改工具名称、描述、参数、返回、prompt、Work、Skill 或上下文加载时读取。Work 的具名入口 Markdown 就是本工作流的技能入口；保留原 ID 与文件名，不另建技能注册根，也不要求每个 Work 启动任务执行者。
+普通代码修改不自动触发全库提示词审查。
+## 发现、加载与执行分开
+description 写真实触发时机、任务范围和相近但不适用的场景，不写“资深专家”式角色自述。先展示用途、可用动作和必要限制，再按模式加载正文或 reference。延后资源必须有可理解的描述、可靠定位和读取条件；不能为减少首轮内容把必要信息藏到不可发现的位置。
+已加载同版本正文的同一次任务不重复读取；输入范围、摘要或 owner 变化时重读受影响内容。首次选中只看到摘要时必须读正文，不能从名称推导步骤。实际执行记录继续遵守 <Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>；读过入口不是执行完成。
+## 工具描述与结果
+参数的范围、默认值、配对和使用条件写在参数定义中。工具说明描述行为与返回，避免复制其他工具或系统段已经拥有的规则。权限、破坏性副作用、不可重复操作和必需验证必须在动作之前可见；描述不是底层权限检查的替代。
+返回有界的结果摘要以及可回读的 ID、路径或游标，明确截断、遗漏、分页和证据完整性。包含少量当前动作确实需要的邻近上下文，不整页倒出日志，也不因过度裁剪迫使下一步反复搜索。缺少资源、格式无效和加载失败要能辨认，不伪造可用性。
+要能区分无结果、读取失败、权限不足和不完整视图。分页未完整不能报告穷尽；有结果句柄不意味着结果已读。
+## 作为行为验证
+检查模型真正收到的工具 schema、prompt、结果和诊断，覆盖正常、失败、取消、权限不足、重复调用和恢复中的适用分支。用户直接调用已注入的 Work 不应再次重复加载同一正文。仅宿主支持时才依赖自动/显式调用元数据；文字字段本身不是安全控制。
+增加空结果、截断后继续读取等真实行为场景。相同请求反复工具调用、换问法但没有进展时，记录已尝试方法与新增证据；使用原 I/P 的停止和恢复规则，不新建无限自动循环。失败后的副作用与安全动作按 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path>。
+比较优化前后实际首轮输入、总读取、重复调用、误触发和任务结果。在没有同模型、同工具、同任务的实际使用记录时，只报告文件字符或字节变化，不能宣称 token、费用或配额节省。已有正反任务观察与结构检查分别报告。
+方法参考：<Url>https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/.agents/skills/agent-experience/SKILL.md</Url>。SpecDev 不因此获得 DSH 的运行时 Skill 加载器。

package/template/workflows/specdev/common/rules/artifact-contract.md CHANGED Viewed

@@ -2,6 +2,12 @@
 SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个工件只承担自己的权威边界。
+## 轻量输入与唯一事实
+整体结论仅在 change README 顶层唯一 `Outcome: active | completed | cancelled` 行；简单任务的范围、可判定 AC、当前清单、真实验证与下一步也由 README 负责。被工具引用的章节使用唯一显式 `<a id="scope"></a>`、`<a id="acceptance"></a>`、`<a id="verification"></a>` 锚点。无 Ticket 的 Goal 只在原计划维护清单；有独立 Ticket 的进度在票及 Evidence，README/Goal/Map 不复制状态。
+工具用临时 `{path, section?}` 定位原文，不创建登记表。存在独立 Spec 默认读取它；仅当前合同允许且 README 等价章节完整时读取 README。两份都自称规格权威时停止裁决，不按时间挑一份。跨 change 集成、Deep、真实并行或复杂设计依赖使用完整工件，迁出位置改成导航；用户明确要求 Spec/Ticket/Goal 时照办。UI 小任务同样保留 DESIGN、具体批准及真实浏览器；LOGIC-only 保留独立验证。无需拆票的轻量任务不制造 Ticket/Map。
 ## 1. 工件职责
 | 工件 | 具体位置 | 必须决定 | 不应决定 |
@@ -17,7 +23,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Change 架构决策 | `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` | 已成为本 change 下游合同的架构决策、原因、后果和替代关系 | 永久项目 ADR 或尚未决定的方案集合 |
 | Spec | `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` | 用户问题、外部行为、范围、验收合同、非功能要求和已锁定实现约束 | 文件级施工步骤 |
 | Ticket | `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>` | 单一垂直切片的行为、决策、范围、路径所有权、执行路线和验证证据 | 跨 Ticket 里程碑治理或远程 Issue 编号 |
-| Tickets Map | `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` | 总体实施背景、项目 Skill 最低调用路由、依赖 DAG、合同覆盖、Ready 投影、并行候选和路径冲突 | 单 Ticket 的完整实现契约 |
+| Tickets Map | `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` | 总体实施背景、项目 Skill 最低调用路由、依赖 DAG、合同覆盖、Gate 导航、并行候选和路径冲突 | 单 Ticket 的完整实现契约、Ready、状态或执行 owner 副本 |
 | Goal Plan | `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
 | Implementation Map | `<Path>{roots.state}/specdev/changes/{change}/implementation-map.md</Path>` | Ready 成员、组合 Ticket inventory、跨 change dependency/serialization 与 revision | 创建或改写子 Spec、Ticket 或实现细节 |
 | Implementation Plan | `<Path>{roots.state}/specdev/changes/{change}/implementation-plan.md</Path>` | 父 Lead、全局 workspace/实现上限、frontier/Wave/locks/integration queue 和可恢复进度投影 | 改写子 change 权威或伪造完成 |
@@ -25,32 +31,33 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Evidence | `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策或远程 Issue 正文 |
 | Change 学习图解 | `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>` | 面向零专业背景读者解释当前 change 的已验证工件、实现和测试事实；索引按序号持续追加 | 产品决定、架构决定、实现授权或 Learning workflow 知识 |
 | 代码审查 | `<Path>{roots.state}/specdev/changes/{change}/reviews/CR-###.md</Path>` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
-| UI 设计包 | `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/comparison/</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/final/</Path>` | 项目 UI 证据、功能风格候选、逐层用户决定、设计 token、交互合同和可运行 HTML/CSS/JS 投影 | 生产 UI 实现或替用户确认高影响偏好 |
+| 项目设计基线 | <Path>{roots.state}/specdev/design/DESIGN.md</Path> | 跨 change 的语义 token、组件/交互规范、版本及来源；A 唯一正式写入 | 单次页面设计或未批准提案 |
+| Change 设计合同 | <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path> | 本 change 已批准的页面、状态、视觉/交互、基线版本和例外；P 拥有 | 改写永久基线或替代 Spec/ADR |
+| UI 设计包 | `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/comparison/</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/final/</Path>` | 项目 UI 检测、模板组合、集中批准证据、可运行 HTML/CSS/JS 源码与浏览器证据 | 生产 UI 实现或替用户确认高影响偏好 |
 | Stakeholder 问卷 | `<Path>{roots.state}/specdev/changes/{change}/questionnaires/{slug}.md</Path>` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
 | Wayfinder 地图 | `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `<Path>{roots.state}/specdev/changes/{change}/investigation/{investigation-id}.md</Path>` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |
 | Wayfinder solution comment | `<Path>{roots.state}/specdev/changes/{change}/investigation/comments/{investigation-id}/NN-solution.md</Path>` | Ticket 的答案、结果事实和资产指针 | 地图索引或产品实现 |
 | 架构审查 | `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>` | 结构性候选、code-judo 机会、证据、选择和访谈状态 | 未经用户选择的执行契约 |
-UI 设计包中的 `{design-id}` 由 P-prototype 分配为当前 change 内最小未占用的 `UI-NNN`；设计系统文档是唯一设计权威，comparison 与 final 不建立第二套规则。
+UI 设计包中的 `{design-id}` 由 P-prototype 分配为当前 change 内最小未占用的 `UI-NNN`；design-system.md 保留文件名但只拥有源码与证据，change DESIGN 是当前设计合同；comparison 与 final 不建立第二套规则。UI 分支按 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path> 处理继承、确认、失效与下游硬引用。
-Change CONTEXT/ADR 是 active change 内的执行权威，不是 workflow 级永久知识。G 和其他设计/执行 Works 只读 `<Path>{roots.state}/specdev/context/</Path>` 与 `<Path>{roots.state}/specdev/adr/</Path>`；只有 A 在 change 完成、实现证据验证、毕业评估和用户确认后才能写入永久 namespace。未毕业内容随归档 change 保留，不能从 change 工件消失。
+Change CONTEXT/ADR/DESIGN 是 active change 内各自领域的执行权威，不是 workflow 级永久知识。G 和其他设计/执行 Works 只读 `<Path>{roots.state}/specdev/context/</Path>` 与 `<Path>{roots.state}/specdev/adr/</Path>`；ADR/context 的正式写入只有 A 在适用证据、价值评估和具体授权通过后执行；独立维护无需虚构 change，research/非标准 store 仍按实际声明及原 owner 判断，不能自动纳管；design 的首次批准意图发布与归档提升均只经 A 设计网关，按 design-contract 执行。未毕业内容随归档 change 保留，不能从 change 工件消失。
 ## 2. 权威顺序
-同一事项冲突时按下列顺序裁决：
+先确定问题类型，不以一个万能优先级覆盖全部事实：
+- 原始请求由 source 负责；产品目标和真实授权来自用户决定，当前 Spec/README 负责已确认外部行为。
+- 当前实现是什么，以真实源码、运行与验证为证；代码不静默授权修改已批准目标。
+- 长期取舍由 ADR 负责，领域含义和兼容范围由 context 负责；当前工程用法由负责 docs/源码维护，不复制决策全文。
+- 当前 change 的已接受 ADR 约束本次架构；与永久知识冲突必须显式记录替代范围，未通过 A 网关不改永久版本。
+- Ticket 拥有本票范围/依赖/写集/实现证据；Goal 和父 Implementation Map/Plan 拥有各自的 Gate、组合依赖、workspace 与集成安排，不能覆盖子行为合同。
+- 日志与历史解释出处，未确认推断不能提升为当前事实。
-1. 用户最新明确决定；
-2. 当前 change 已接受的架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`；
-3. 永久 ADR 与领域上下文：`<Path>{roots.state}/specdev/adr/</Path>`、`<Path>{roots.state}/specdev/context/</Path>`；
-4. 当前外部行为权威：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`；
-5. 当前 Ticket 契约：`<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`；
-6. 当前跨 Ticket 编排：`<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`；
-7. 若当前 change 属于父实现 change，父 Implementation Map 对组合 Ticket dependency/serialization 具有权威，父 Implementation Plan 拥有全局 workspace、frontier 与 integration queue；
-8. 当前代码与运行事实；
-9. 旧计划、旧日志和未经确认的推断。
+视觉/交互事项先读取已批准 change DESIGN 和其引用的项目设计 revision；它不能覆盖 Spec 的外部行为或 ADR 的架构决定。缺少确认、内容漂移或规则冲突时返回 P，不由下游重新选择设计。
-当前 change 决定与永久知识冲突时，必须在 LOG/ADR 中显式说明替代关系；它只约束当前 change，直到 A 决定是否提升并更新永久版本。
+当前 change 决定与永久知识冲突时，必须在 LOG/ADR（设计事项为 DESIGN overrides）中显式说明替代关系；它只约束当前 change，直到 A 决定是否提升并更新永久版本。
 `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>` 只对“原始输入是什么”具有权威；后续用户决定、ADR 和 Spec 可以显式演进该意图。远程来源在摄入后发生变化不会自动改写本地合同，必须重新 Triage。GitHub 上由 publish 投影出的 Issue 不是开发权威；发布计数以 `<Path>{roots.state}/specdev/changes/{change}/publish.md</Path>` 为准。GitHub 上由 capture 记下的 inbox Issue 也不是开发权威；inbox 计数以 `<Path>{roots.state}/specdev/capture.md</Path>` 为准，缺失该文件视为空 inbox。
@@ -95,3 +102,9 @@ W 的 `<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>` 只
 - R-retro：<Path>{roots.state}/specdev/changes/{change}/retro/RETRO-###.md</Path> 拥有活动复盘建议和来源；不成为永久知识。
 - P：<Path>{roots.state}/specdev/changes/{change}/prototypes/LOGIC-NNN/logic.md</Path> 记录逻辑模型与浏览器证据；index.html 是可运行原型，ready 时 hash 与记录一致。
 - 来源更新：<Path>{roots.state}/specdev/changes/{change}/source.md</Path> 冻结后保持不变。T 将后续读取写入 <Path>{roots.state}/specdev/changes/{change}/sources/SRC-###.md</Path>，记录 replaces、固定 SHA/hash、完整性和原 locator，triage 正文选择有效快照；不得把新远程事实自动升级为已接受 Spec。
+## 专业分支的证据归属
+R.performance 的测量卡、原始样本引用和优化候选仍由 architecture-review 拥有，不直接修改生产代码。I.documentation 修改获批项目文档并在原本票或 Direct Spec Evidence 保存验证；不另造文档状态。D.evidence-triage 在 diagnosis 的现象/事件节记录观察、未知与下一检查；它不是已经接受的根因或修复合同。具体记录见 <Path>{roots.workflows}/specdev/common/rules/engineering-evidence.md</Path>。
+代码、运行证据可以证明计划尚未实现或已过时，但不能改写用户目标。ADR 记录采纳与真实备选；未确认解释属于 LOG/设计树，未完成计划不能进入当前事实摘要。实际文档职责遵守 <Path>{roots.workflows}/specdev/common/rules/documentation-standard.md</Path>。

package/template/workflows/specdev/common/rules/change-completion.md CHANGED Viewed

@@ -1,20 +1,22 @@
 # Change Completion
-本规则是 change 从 active/blocked 转为 completed 的唯一合同。
+本规则是 change 整体完成或取消的唯一合同。README 的 Outcome 只是结论，必须能沿原工件重建证据；结束不等于已归档。
 ## 完成门
 一个 change 只有同时满足以下条件才能 completed：
 1. 所有计划内 Ticket 为 done，或因权威事实无需改动而记录为 cancelled；Direct Spec/非实现流程有等价验收。
-2. required Ticket 有 source commit、passed candidate、父分支 result SHA，且父分支包含 source commit；current Ticket 有 implementation commit、passed direct-parent 验证和父分支 result SHA；对应 workspace 记录均为完成状态。
+2. required Ticket 有 source commit、passed candidate、父分支 result SHA，且父分支包含 source commit；current Ticket 有 implementation commit、passed direct-parent 验证和父分支 result SHA；对应 Ticket Evidence 的 workspace/集成记录均完整；不要求 JSON 镜像。
 3. 每个行为有 Lead Evidence，全部 Spec 合同与 Goal Gate 可定位。
 4. current Ticket 的 current-workspace 检查/回归和适用 E2E，或 required Ticket 的 source-worktree 非 E2E 检查、parent-candidate 集成/回归和 required E2E 已通过；not-required 有理由。
 5. 迁移、发布、监控、恢复和不可逆批准已完成或明确不适用。
 6. 没有未批准 deviation、blocker、unverified、活动 candidate 或未集成 source checkpoint。
-7. Ticket、Map、Goal Plan、Evidence、change status 与实际 Git 一致。
+7. Ticket、Map 的依赖/导航、Goal Plan、Evidence、README 与实际 Git 一致；不复制单票状态。
-Evidence-only Done 和 empty commit 不满足完成门。
+UI 实施还需 Evidence 对照已批准 change DESIGN、固定基线与页面/状态验收；原型截图不代替实现的真实渲染。设计漂移或未确认例外按 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path> 返回 owner，不能以票全 done 消除缺口。
+Evidence-only Done 和 empty commit 不满足完成门.
 父实现 change 还必须满足 `<Path>{roots.workflows}/specdev/common/rules/parent-implementation-orchestration.md</Path>`：全部成员 completed，Implementation Map 与 Implementation Plan completed 且 revision 一致，跨 change 全套验证通过，`<Path>{roots.state}/specdev/changes/{change}/evidence/implementation-orchestration.md</Path>` 完整，没有活动派单、candidate、serialization lock 或未裁决冲突。父完成不自动归档或移动任何成员。
@@ -25,7 +27,7 @@ Evidence-only Done 和 empty commit 不满足完成门。
 - 非实现型终点：最终验收工件 owner 使用本规则。
 - 父实现 change：Implementation Plan 的唯一 Lead 在全部成员与 aggregate gate 关闭后拥有转换。
-Owner 原子更新 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `change_status`、`completed_at`、`updated_at` 和 `current_work`，然后重读。全局 status 只维护 active/archived 索引。
+Owner 依据来自原 Goal/Implementation Plan、I 的真实会话或非实现验收工件，不由调用方任意声明。门全部通过后，重验 README 旧字节和证据，由同一 owner 原子更新 <Path>{roots.state}/specdev/changes/{change}/README.md</Path> 唯一 `Outcome: completed` 行并链接完成依据，再重读；不连带改票时间戳或复制进度。轻量任务由 README 的范围、逐 AC 实际结果、适用验证和下一步承接等价证据；用户要求的独立工件和复杂实现门不得省略。
 ## 远程来源与归档
@@ -38,3 +40,20 @@ Owner 原子更新 `<Path>{roots.state}/specdev/changes/{change}/.status.json</P
 仅有 R-retro（可先经 T intake）的 review-only change，以 completed 的 RETRO 报告作为等价验收；不能同时存在 Spec、Ticket、Map、Goal Plan、implementation 工件、Evidence 或 worktree。报告 sources 非空、结果诚实、全部验收完成，owner 按原完成转换规则更新状态；存在实现工件时仍走原实现完成门。insufficient-evidence 仅表示报告完整，不表示问题已解决。
 PR requested=true 且 status=planned/failed 时阻塞归档；delivery_target=ready 时 draft 也保持未闭合。draft 目标可由 draft/ready 满足，ready 目标只由 ready 满足；waived 须记录放弃交付的授权与原因。创建成功不等于已授权 merge。独立 TRI 不因关联 change 就参与完成/归档门。
+## 整体取消
+只有真实用户取消请求发生时，由原完成 owner 核对并记录：决定来源、范围和时间；未交付内容与已落地代码/数据/设计/远程影响；活动 writer 已停止或明确交接的证据；父子依赖、未集成 checkpoint/candidate 的处置；已承诺外部动作的结果或明确放弃/转交依据；后续 owner、保留材料和恢复限制。记录放 README 或原 Goal 决定章节并链接，齐全后重验旧字节，写入唯一 `Outcome: cancelled` 并重读。
+A 只验证取消结果，不代替用户取消。单 Ticket cancelled 不推导整体取消；不批量改票为 done/cancelled，不自动回滚、远程关闭或删除 branch/worktree。未知外部结果继续阻塞归档；超时/无响应不能证明 writer 结束。已发布 DESIGN revision 保留，未实现候选随 change 保存；cancelled 不满足 promotion 的 implemented 完成来源门。
+## 轻量证据与取消的只读语法
+轻量 README 使用唯一 scope/acceptance/verification 显式锚点，acceptance 列可观察的 AC-n。完成时 verification 表使用 `AC | Result | Evidence`（可选 SHA256 列），每个 AC 恰一行 `passed` 和可回读实际证据 locator；提供摘要时必须匹配真实字节。证据可用 #anchor 指向同 README 的独立证据段，不能指向 Outcome/Ownership 或该结果声明自身，记录 `Method`、`Source`、`Observed`、`Result: passed`；有 `Command` 时须 `Exit: 0`。实际运行后才形成，不为 active 任务先造空证据；静态字段只供回读，不认证语义真实性或授权。
+无 Goal 的 owner 在 README `## Ownership` 写 `Owner` 与 `Evidence`；后者指向实际会话/交接原文或同 README 的独立证据锚点，其 `Owner` 或 `Session` 必须匹配。若动作绑定 `Work`，原证据必须同值；不是每 Work 调用登记。
+取消在 README `<a id="cancellation"></a>` 下保留 `Source`、`Scope`、`Time`（实际 ISO 时间）、`Confirmed-By`（原 owner）、`Undelivered`、`Landed`、`Writers`、`Dependencies`、`Checkpoints`、`External`、`Next`。Source 指向真实取消决定原件或同 README 的独立原请求锚点，不能以取消结论自证。Writers 为 `none: <依据>` 或 `stopped: <停止/交接证据 locator>`；后者原件须有 `Writers: stopped` 与真实 Observed。Dependencies/Checkpoints/External 使用 `none|resolved|transferred|waived: <处置依据>`，不能把未知写成已解决。活动/review/integrating/blocked 的执行记录仍须原 owner 处置，不由取消声明抹掉。
+独立 Spec 的无票 Direct Spec 使用原 evidence/direct-spec 的 `## Acceptance Verification` JSON array 逐 AC 回读实际结果：id/result/method/source/observed；command 存在时 exit 为 0，外部 evidence 引用须有匹配 sha256，内联观察无需另建文件。空 Evidence、仅标题或 passed 自评不通过。`--stage complete` 只判本地完成；A 移动前使用 `--stage archive-ready` 同时核对对应 completed/cancelled 门和已承诺远程交付，目标移动后再使用 archived。

package/template/workflows/specdev/common/rules/codebase-design.md CHANGED Viewed

@@ -6,17 +6,17 @@
 ## 术语表
-严格使用以下术语 — 不要用 "component"、"service"、"API" 或 "boundary" 替代。一致的语言才是重点。
+以下术语用于讨论设计的共同含义，不是词语禁令。项目已有精确的 API、service、component、process/security boundary 等概念时使用其原名；不要为了套用词汇掩盖真实工程语义。
-**Module（模块）** — 任何具有接口和实现的东西。有意识地与规模无关：函数、类、包或跨层切片。_避免使用_：unit、component、service。
+**Module（模块）** — 任何具有接口和实现的东西。有意识地与规模无关：函数、类、包或跨层切片。unit、component 或 service 可以是项目内具体模块类型，不要求改名。
-**Interface（接口）** — 调用者正确使用模块所需了解的一切：类型签名，还包括不变量、顺序约束、错误模式、必需配置和性能特征。_避免使用_：API、signature（太窄 — 它们仅指类型层面的表面）。
+**Interface（接口）** — 调用者正确使用模块所需了解的一切：类型签名，还包括不变量、顺序约束、错误模式、必需配置和性能特征。API/signature 只覆盖部分调用知识时，补充遗漏的约束，而不是禁止这些准确名称。
 **Implementation（实现）** — 模块内部的内容，它的代码体。区别于 **Adapter（适配器）**：一个东西可以是一个小适配器加一个大实现（Postgres 仓库），也可以是一个大适配器加一个小实现（内存假实现）。当讨论缝合点时用 "adapter"；否则用 "implementation"。
 **Depth（深度）** — 接口处的杠杆效应：调用者（或测试）每学习一个单位的接口可以驱动的行为量。当大量行为隐藏在小接口后面时，模块是**深层的**；当接口几乎和实现一样复杂时，模块是**浅层的**。
-**Seam（缝合点）** _(Michael Feathers)_ — 一个可以在不编辑该位置的情况下改变行为的地方；模块接口所在的*位置*。缝合点放在哪里本身就是一个设计决策，与缝合点后面放什么不同。_避免使用_：boundary（与 DDD 的有界上下文重载）。
+**Seam（缝合点）** _(Michael Feathers)_ — 一个可以在不编辑该位置的情况下改变行为的地方；模块接口所在的*位置*。缝合点放在哪里本身就是一个设计决策，与缝合点后面放什么不同。process、security、transaction boundary 与 DDD bounded context 各有明确含义，不统称为 seam。
 **Adapter（适配器）** — 在缝合点处满足接口的具体事物。描述的是*角色*（它填充哪个槽位），而非实质（内部是什么）。
@@ -59,13 +59,13 @@
 - **深度是接口的属性，而非实现的属性。** 一个深层模块内部可以由小型、可模拟、可替换的部分组成 — 只是它们不属于接口的一部分。一个模块可以拥有**内部缝合点**（对其实现私有，用于其自身测试）以及位于其接口处的**外部缝合点**。
 - **删除测试。** 想象删除这个模块。如果复杂性消失，它就是个透传层。如果复杂性在 N 个调用者中重新出现，它就在发挥价值。
 - **接口就是测试表面。** 调用者和测试穿过同一个缝合点。如果你想测试接口_之外_的内容，模块可能形状不对。
-- **一个适配器意味着假设的缝合点。两个适配器意味着真实的缝合点。** 除非有东西确实在缝合点两侧变化，否则不要引入缝合点。
+- **适配器数量不是设计门槛。** 用真实消费者、测试隔离、安全、生命周期或扩展义务证明接缝价值；一个生产实现也可能需要稳定接口，两个实现也可能只是无价值间接层。不要为满足数量发明第二个适配器。
 ## 为可测试性而设计
 良好的接口使测试变得自然：
-1. **接收依赖，不要创建依赖。**
+1. **需要替换、测试隔离或独立资源生命周期时显式接收依赖。** 在组装入口创建实例是正常职责；不为注入无状态常量或没有变化依据的对象增加配置。下面比较需要替换外部支付依赖的情形：
    ```typescript
    // 可测试
@@ -77,7 +77,7 @@
    }
    ```
-2. **返回结果，不要产生副作用。**
+2. **纯计算优先返回结果；必要副作用明确由谁拥有。** 写文件、发请求等业务行为不能为了纯函数形式被删除，需声明失败后的状态保证、重试与清理。以下示例只比较计算函数的局部设计：
    ```typescript
    // 可测试
@@ -89,7 +89,7 @@
    }
    ```
-3. **小表面积。** 更少的方法 = 更少的测试需求。更少的参数 = 更简单的测试设置。
+3. **小而明确的调用接口。** 减少调用者必须理解的独立选择；方法变少不保证测试变少，隐藏分支、不明确的可选参数与隐式默认仍需要验证。
 ## 关系
@@ -103,7 +103,7 @@
 - **深度作为实现行数与接口行数之比** (Ousterhout)：奖励填充实现。我们使用深度即杠杆效应来替代。
 - **"Interface" 作为 TypeScript 的 `interface` 关键字或类的公开方法**：太窄 — 此处的接口包括调用者必须了解的每个事实。
-- **"Boundary"**：与 DDD 的有界上下文重载。说 **seam** 或 **interface**。
+- **模糊地互换 boundary、seam、interface**：分别说清进程/安全边界、可替换点或调用契约，不禁止具有准确语义的工程术语。
 ## 深化
@@ -115,11 +115,11 @@
 #### 1. 进程内
-纯计算、内存状态、无 I/O。始终可深化 — 合并模块并通过新接口直接测试。不需要适配器。
+纯计算、内存状态、无 I/O。先检查合并能否集中相关变化而保留独立职责；通过稳定调用接口测试。不要仅因进程内运行就合并不同领域或生命周期。
 #### 2. 本地可替换
-具有本地测试替代品的依赖（PGLite 替代 Postgres、内存文件系统）。如果存在替代品则可深化。深化后的模块在测试套件中使用运行的替代品进行测试。接缝是内部的；在模块的外部接口处不需要端口。
+具有本地测试替代品的依赖（PGLite 替代 Postgres、内存文件系统）。先验证替代品覆盖目标契约，尤其是事务、并发、权限及失败语义；有替代品本身不证明等价。深化后的模块在测试套件中使用运行的替代品进行测试。接缝是内部的；在模块的外部接口处不需要端口。
 #### 3. 远程但自有（端口与适配器）
@@ -133,16 +133,18 @@
 ### 接缝纪律
-- **一个适配器意味着假设性接缝。两个适配器意味着真正的接缝。** 除非至少有两个适配器是合理的（通常是生产 + 测试），否则不要引入端口。单一适配器的接缝只是间接层。
+- **证明接缝承担的义务，不按适配器计数。** 生产消费者、可靠测试、第三方扩展或安全隔离可以证明单实现接缝的价值；缺少这些依据时再质疑端口。不得仅凭数量删除已发布接口，也不发明第二实现来为抽象辩护。
 - **内部接缝 vs 外部接缝。** 一个深模块可以既有内部接缝（对其实现私有，供其自身的测试使用），也有其接口处的外部接缝。不要仅仅因为测试使用了内部接缝就通过接口暴露它们。
 ### 测试策略：替换，而非叠加
-- 一旦深化后模块接口的测试存在，旧有浅模块上的单元测试就变成了废料 — 删除它们。
+- 删除旧测试前，逐项列出其行为、错误路径、兼容约束和历史回归，并定位新测试的承接证据。仅仅存在新的深模块接口测试，不证明覆盖等价；不能证明时保留旧测试或补齐缺口。删除决定与必要反例记录在本票 Evidence。
 - 在深化后模块的接口处编写新测试。**接口就是测试表面**。
 - 测试通过接口断言可观察的结果，而非内部状态。
-- 测试应经受住内部重构 — 它们描述的是行为，而非实现。如果测试在实现改变时必须更改，那它就是在测试接口之后的东西。
+- 测试优先描述可观察行为并经受内部重构；实现变化使某个测试需要调整，是复核其保护义务的信号，不自动证明测试冗余。生命周期、安全和性能约束可能需要内部观测，理由与公共行为证据分别说明。
 ## SpecDev 应用边界
 扫描前先划定范围并遵循 YAGNI。用户指定 module、子系统或痛点时直接采用；否则从足够长的 Git 历史识别反复变化的热点，只有热点不明确时才扩大范围。实现中的局部设计遵守 Ticket/Spec；需要改变公共契约、数据、安全、兼容、范围、迁移或验收时返回拥有该决定的上游工件。
+涉及生命周期、失败和重试时读取 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path>；涉及测试替换或并发资源时读取 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path>。简化以减少实际维护义务为目标，不以删除行数、接口数或测试数为配额。

package/template/workflows/specdev/common/rules/design-contract.md ADDED Viewed

@@ -0,0 +1,51 @@
+# UI 设计权威、批准与继承
+P 创建 UI 包，或 S/T/I/C/W 消费 UI 决定时读取。纯 LOGIC 和没有 UI 影响的 change 不强制生成 DESIGN；不能以缺少 UI 工件阻塞独立的后端工作。
+## 三层产物与 owner
+| 层 | 位置 | 权威与 owner |
+|---|---|---|
+| 项目设计基线 | <Path>{roots.state}/specdev/design/DESIGN.md</Path> | 跨 change 的视觉语言、语义 token、组件与交互规范；唯一正式写入 owner 为 A |
+| Change 设计合同 | <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path> | 本 change 的页面、任务流、状态、响应式、基线引用与已批准例外；P 写入并维护 |
+| 原型源码与证据 | <Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path> | P 拥有项目检测、候选来源、HTML/CSS/JS 源码、验证和批准证据；不再重复拥有设计规则 |
+`design-id` 为当前 change 内最小未用的 `UI-NNN`。每个 UI 包引用同一 change DESIGN 的适用页面/规则；不能以新包覆盖其他已批准页面。comparison 与 final 是源码投影，项目内预览是有明确写集的临时验证。CONTEXT 拥有产品事实，ADR 拥有架构决定，Spec 拥有外部行为；DESIGN 不夺取这些职责。
+初始化只创建空的 <Path>{roots.state}/specdev/design/</Path>，不从模板预填品牌或创建已批准 DESIGN。根项目已有 <Path>DESIGN.md</Path> 或其他设计规范时记录实际 locator 和 owner；不得自动覆盖或同步出第二套可写基线。
+## 基线生命周期
+1. 先按 design 索引的 app、页面、关键词或规则 ID 定位，再读取相关原文与 provenance。已有基线时核验 revision/digest 与代码；未声明 rebrand 的局部变更继承它。
+2. 没有基线时先检测现有 token、组件和真实页面；新项目明确没有既有事实。P 在 change 内准备 baseline draft，观察值、用户约束与待验证建议分开。持久化草案不等于永久知识。
+3. 默认先自动组合模板并生成 HTML，再把基线差异、候选、推荐最终页、关键交互和提升范围作为一次初始批准包展示。用户可以选择、组合、修改或拒绝；不逐项追问可由代码或模板推导的 CSS 偏好。首次批准前，将候选基线的确定 revision/designDigest 预绑定到 draft DESIGN，以 draft 状态及包内发布记录明确它尚未发布，并连同候选完整字节 SHA-256、HTML 摘要及当前基线 CAS 条件一并展示。这样批准涵盖最终规范内容；发布后仅验证同一内容落盘。临时发布状态保存在包/回执中，不写入会改变 designDigest 的规范正文。
+4. 包获批后，P 通过 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/references/design-knowledge-gateway.md</Path> 请求 A 创建首次永久基线；该嵌入网关保持调用方原 owner，不执行整项归档。P 无永久目录直写权。已有基线的普通 change 仅记录 delta，不能借初始批准覆盖永久基线。正式 baseline 的不可变快照保存到 <Path>{roots.state}/specdev/design/revisions/{revision}.md</Path>，`revision` 来自网关验证的 DESIGN-NNNN；恢复和历史 change 按引用版本读取，不静默替换为 current。
+5. 实施与验证后，A 在归档阶段按同一网关评估共享规则，生成 promotion diff 并在原授权范围内写入；一次性页面内容、未采纳方向、纯原型设想不提升。保持原 ID、来源和替代关系；未提升内容随 change 归档。
+基线冲突、未知 owner、未闭合事务或相关锁只阻塞永久写入及依赖分支。仍可完成独立的检测、草案和候选，但不得把未成功发布的基线当作已存在。正式写入前后遵循 activation-and-memory 的定位、事务检查、原子写入与回读。
+## 批准与失效
+用户批准绑定具体 change DESIGN 内容、基线版本和原型文件摘要，并记录可回读的确认来源。发布批准的 record.path/sha256 绑定不可追加改写的本次确认快照；LOG 追加其定位和回执。项目根已有设计规范时保留原 owner，以 derived-readonly 和根文件字节摘要明确只读派生关系。模板推荐和 Agent 自评不构成人类批准。用户已指定方向或已授权自主组合时直接完成 HTML；仍需取得最终 HTML/交互与设计合同的集中确认，不额外要求重复的风格选单。
+HTML、交互、设计合同、引用基线或影响布局的输入变化时，旧批准只对原摘要有效。先标记受影响部分待重新确认，完成新证据后再批准；无关页面不重新访谈。多个原型包与历史失败包并存时按 `--prototype-id UI-NNN` 选择本次目标，不能以任意一个 ready 包掩盖当前包失败。
+## 下游硬引用
+- **S**：UI 范围的 Spec 明确引用 change DESIGN、项目基线版本与原型 ID；将页面/状态映射到 AC。设计未批准或漂移时 UI 合同不可 Ready，返回 P。
+- **T**：UI Ticket 使用 ui_change=true、design_ref={revision,digest,pages,acceptance}，Map 引用同一版本和适用规则；实现票明确只读设计来源、组件复用边界与视觉/交互验收。不可让执行者重新选风格。
+- **I**：预检重算 design_ref 引用和摘要；按已批准设计实现，在 Evidence 的 Design Conformance 记录 digest/page/AC 与真实页面、原型差异、视口及任务证据。发现设计无效返回 P，行为冲突返回 S，不能修改设计文件给实现偏差补票。
+- **C**：规范轴读取适用 DESIGN 与批准证据，区分规则偏离、未验证 UI 与可接受实现差异；审查不代替用户确认。
+- **W**：solution comment 只保留 change DESIGN、指定 UI 包和 comparison/final 的定位与证据。探索原型不是 child change 的默认批准；child 复用时必须绑定自身范围并验证引用。
+下游必须实际读取引用内容；仅写路径或模板中的 `approved` 文本不算已消费。纯 LOGIC 仍用自身 logic.md/hash/浏览器合同，不生成虚假 UI DESIGN。
+## 质量与证据
+先做独立的视觉/任务 critique，再做可机械验证的 audit，最后按严重程度修复和 polish。检查产品特征、层级、字体、密度、色彩语义、完整状态、键盘/focus、缩放、触屏、长文案、响应式和 reduced motion。审美反模式是诊断提示，用户约束与已批准项目体系优先；检测器无告警不证明设计优秀。
+浏览器证据必须来自实际打开的本次产物，保存工具、环境、视口、操作、结果和截图相对路径。至少覆盖桌面与窄屏，适用手势单独操作；模拟 viewport 不证明真实触屏。无浏览器时可交付 draft，但不能 ready。原型 mock 只证明原型，不证明真实服务、生产性能或真实用户研究。
+schema 与 hash 校验由 <Path>{roots.workflows}/specdev/common/tools/design-artifacts.mjs</Path> 和 <Path>{roots.workflows}/specdev/specdev-p-prototype/scripts/validate-design-package.mjs</Path> 承担；通过结构校验后仍需上述人工批准及运行证据。归档引用按 `--stage archived` 验证，不能用活动 change 的路径判断历史失效。

package/template/workflows/specdev/common/rules/design-it-twice.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # 设计两次
-当用户想要为选定的深化候选探索替代接口时，使用此并行子 Agent 模式。基于 "Design It Twice"（Ousterhout）— 你的第一个想法不太可能是最好的。
+当用户想要为选定的深化候选探索替代接口时，使用此并行任务执行者 模式。基于 "Design It Twice"（Ousterhout）— 你的第一个想法不太可能是最好的。
 使用 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>` 中的词汇 — **module**（模块）、**interface**（接口）、**seam**（接缝）、**adapter**（适配器）、**leverage**（杠杆）。
@@ -8,28 +8,28 @@
 ### 1. 界定问题空间
-在启动子 Agent 之前，为选定候选编写一份面向用户的问题空间说明：
+在启动任务执行者 之前，为选定候选编写一份面向用户的问题空间说明：
 - 任何新接口需要满足的约束条件
 - 它将依赖的依赖项，以及它们属于哪个类别（参见 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>` 的“依赖类别”）
 - 一个粗略的示例代码草图来使约束具体化 — 不是提案，只是让约束变得具体的一种方式
-将此展示给用户，然后立即进入第 2 步。用户在子 Agent 并行工作时阅读和思考。
+将此展示给用户，随后进入第 2 步；有工具派遣时用户可同时阅读和思考。
-### 2. 启动子 Agent
+### 2. 启动任务执行者
-使用 Agent 工具并行启动 3+ 个子 Agent。每个子 Agent 必须为深化后的模块生成一个**截然不同的**接口。
+按共享编排方法选择执行方式：可派遣时建立至少 3 个独立候选；Lead 模式按相同约束依次完成至少 3 个候选。每个任务执行者 必须为深化后的模块生成一个**截然不同的**接口。
-为每个子 Agent 提供一份独立的技术简报（文件路径、耦合细节、来自共享设计规则的依赖类别、接缝背后的内容）。简报独立于第 1 步中面向用户的问题空间说明。给每个 Agent 一个不同的设计约束：
+为每个任务执行者 提供一份独立的技术简报（文件路径、耦合细节、来自共享设计规则的依赖类别、接缝背后的内容）。简报独立于第 1 步中面向用户的问题空间说明。给每个 Agent 一个不同的设计约束：
 - Agent 1："最小化接口 — 目标 1–3 个入口点。最大化每个入口点的杠杆。"
 - Agent 2："最大化灵活性 — 支持多种用例和扩展。"
 - Agent 3："为最常见的调用方优化 — 让默认情况变得简单。"
 - Agent 4（如适用）："围绕接缝设计端口与适配器，以处理跨接缝依赖。"
-在简报中同时包含共享设计规则的词汇和 CONTEXT 词汇，以便每个子 Agent 能使用架构语言和项目的领域语言一致地命名事物。
+在简报中同时包含共享设计规则的词汇和 CONTEXT 词汇，以便每个任务执行者 能使用架构语言和项目的领域语言一致地命名事物。
-每个子 Agent 输出：
+每个任务执行者 输出：
 1. 接口（类型、方法、参数 — 以及不变量、排序、错误模式）
 2. 使用示例，展示调用方如何使用它
@@ -45,4 +45,4 @@
 ## SpecDev 门禁
-本模式只探索接口，不修改代码。只有 Ticket 允许局部设计自由且候选不改变已锁定契约时可由实现者选择；涉及公共接口、数据、兼容、安全、范围或验收时停止并升级到 Ticket/ADR，暴露更广架构问题时返回 `<Path>{roots.workflows}/specdev/R-review-architecture/R-review-architecture.md</Path>`。
+本模式只探索接口，不修改代码。只有 Ticket 允许局部设计自由且候选不改变已锁定契约时可由实现者选择；涉及公共接口、数据、兼容、安全、范围或验收时停止并升级到 Ticket/ADR，暴露更广架构问题时返回 `<Path>{roots.workflows}/specdev/specdev-r-review-architecture/SKILL.md</Path>`。

package/template/workflows/specdev/common/rules/design-portability.md ADDED Viewed

@@ -0,0 +1,48 @@
+# 设计合同的离线消费、导出与恢复
+单文件能力消费 UI 决定、需要首次基线发布或归档提升，而宿主不具备原项目工具时使用。本文保留相同 owner、摘要和批准门；不能把不可执行工具的名称当作已执行能力。纯 LOGIC 与无 UI 影响的工作独立继续。
+## 工件与能力检查
+项目基线位于 <Path>{roots.state}/specdev/design/DESIGN.md</Path>，不可变版本位于 <Path>{roots.state}/specdev/design/revisions/{revision}.md</Path>，检索投影位于 <Path>{roots.state}/specdev/design/INDEX.md</Path>。当前 change 的合同位于 <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path>，原型、确认和浏览器证据位于 <Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/</Path>。change DESIGN 是规范，源码包不是第二份规则来源；跨 change 发布仍由项目设计知识网关唯一负责，消费方不能直写基线。
+先确定宿主能否读取全部相关文件、保留原始字节、计算 SHA-256、解析无重复键的 YAML/JSON、实际打开浏览器、写入文件，以及调用原 owner 的发布网关。缺少某能力只阻塞需要它的门。不能计算摘要时输出原始材料和待计算清单，不能编造 64 位字符串；没有真实浏览器时原型保持 draft/blocked；不能调用网关时导出待执行发布包，不宣称基线已发布。
+使用本文内联的项目设计、change 设计、UI 源码包和浏览器证据 schema 核对字段、类型、必需值和枚举；字段表不是许可。路径必须是所属根内的正斜杠相对 locator，不含绝对路径、反斜杠、空段、点段或符号链接。已有用户根设计文件保留原 owner，记录只读派生来源，冲突未解决不发布。
+## 可移植的摘要算法
+拥有确定性解析和加密工具时按以下算法计算；对话推测和人工抄写不能代替它们。
+1. `byte SHA-256` 对文件原始字节计算，保留换行和编码差异；用于候选、确认快照、实际 HTML、根设计文件和 current 的并发比较。
+2. `designDigest`：解析 Markdown YAML 头部及正文；删除头部顶层 confirmation、status、updated_at；递归按键名排序对象，数组次序保持不变；对排序结果生成无额外空白的 JSON，再连接一个换行和将 CRLF 换成 LF、首尾 trim 后的正文；以 UTF-8 计算 SHA-256。同一算法用于项目基线与 change 合同，不能用全文字节摘要替代。
+3. `prototype digest`：递归枚举该包 final/ 和 comparison/ 中全部普通文件，拒绝符号链接和其他文件类型；按路径排序，形成 `[包内相对路径, 文件字节SHA-256]` 数组。将 `{candidates, selected_candidate, files}` 递归按对象键排序后生成无额外空白 JSON，以 UTF-8 计算 SHA-256。候选内容、选择或任一运行文件变化都会使旧确认失效。所有运行依赖必须位于这两个目录中，离线运行，不能通过其他目录或网络旁路摘要。
+token 引用必须可解析且无循环；页面/规则/来源 ID 唯一。正式合同的 confirmation.digest 等于 designDigest，confirmation.record_digest 等于固定确认快照的字节 SHA-256，快照正文必须包含当前 designDigest、prototype_ref.digest 与 baseline.digest。baseline 指向存在的不可变 revision 且其 digest 相同；prototype_ref 与当前选中的包 ID、prototype digest 和 selection 一致。不得静默更新历史 change 所引用的基线。
+## 初始设计与下游消费门
+1. 已有项目先读代码中的 token、组件和真实页面，再继承已批准基线；没有基线时准备 change 内的 baseline-draft。默认自动组合候选并生成同任务 HTML，再集中展示。默认 3 个候选，配置范围 2–4 个；用户明确指定数量则记录 candidate_count_override 并严格按该数量生成。候选结构需要实质差异，不用换色复制冒充选择。
+2. 源码包保留 final/index.html、final/styles.css、final/app.js 三个具名源码块；提取后与实际文件逐字一致。comparison 索引能访问每个候选，候选和 final 内容、控制与状态完整，所有资源存在且离线。源码、候选、资源先全部生成，包仍处于 awaiting-confirmation。
+3. 浏览器证据对应当前 prototype digest。inspected_files 包含所有 candidate.entry 与 final/index.html；每个候选及 final 都至少有 390px、1440px case，case.entry 与实际入口相同，保存真实 PNG，final cases.states 覆盖每个页面的 `page-id:state`。实际检查操作、键盘/focus、溢出、长文案、缩放、reduced motion，记录 console_errors、offline、设计审查、技术审查及修复复核。模板或布尔标记不证明真实执行。
+4. 预览门先核对全部资源、源码一致性、页面状态与浏览器证据。首次批准前，将候选基线的确定 revision/designDigest 预绑定到 draft change DESIGN；一次展示最终 HTML、change 合同、候选基线、永久目标、来源和例外。批准绑定上述原始字节与规范摘要，固定用户决定为 approval.md；后续 LOG 只追加定位。首次批准范围必须包含永久规范写入，原有同范围批准可继续使用。
+5. 首次基线经原 owner 网关成功发布后回读 current、revision 和回执，确认与获批候选一致；再登记同一次 change confirmation。完整 approved 门通过后才能 ready。内容或摘要漂移时保持 blocked，先修订证据并重新确认受影响内容；不得用 pending 发布包满足 ready。
+6. S 的 UI 行为/页面/状态 AC 引用 change 合同和基线版本。T 的 UI Ticket 使用 ui_change 和 design_ref 的 revision/digest/pages/acceptance；I/C 在开始时重新计算并实际读取对应内容，在 Design Conformance 中逐页逐 AC 记录实现证据。仅引用路径或标记 approved 不算消费。W 探索材料复用于子 change 时重新绑定其范围；历史包保留，消费的是 change prototype_ref 指定的包。
+## 待执行网关包
+无法调用原 owner 网关或无法写项目时，在 <Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/gateway-request.json</Path> 输出完整请求，状态为 `pending`；这是交接记录，不是新写入网关。请求明确 owner、mode（bootstrap/promotion）、候选路径、目标 current、预期 current 字节摘要（首次为 null）、批准对象、所需但尚未运行的门、已经完成的检查点。批准对象保留 approved、source、confirmed_at、candidate_sha256、current_sha256 和 新 `locator_version: 2`、`record: {base: "change", change, path, sha256}`；bootstrap 的 `preview: {base: "change", change, path, sha256, package_path, prototype_digest}` 绑定同一包实际 final HTML 和所有候选/运行资源。根项目已有设计规范时添加 `project_design: {owner, disposition: derived-readonly, sha256}`，候选 sources 保留相同 locator/digest。
+按稳定路径顺序输出完整 FILE 文件包：README 与原负责计划/owner 依据、原始请求、draft change DESIGN、候选 baseline、源码包、comparison/各候选/final 全部运行文件、浏览器证据和截图、固定确认、gateway-request、LOG。二进制截图保留为可下载原文件；若宿主不能导出则明确缺失并保持 blocked，不用 Markdown 假装 PNG。不要只提供 diff 或摘要，不导出并声称已经发布永久 current。若缺少真实批准，approval 为 null 且请求保持 draft，不伪造批准字段。
+答复必须区分“已实际保存”“待保存”“待网关执行”和“已验证/未验证”，列出每个完整相对路径、当前 phase、阻塞条件与下一步。只有工具成功回执才能宣称持久化或发布；消费方可以在依赖未满足时完成独立非 UI 工作。
+## 原 owner 恢复与归档提升
+恢复先重新读取用户保存或工具实际写入的状态、gateway-request、固定批准快照、全部候选与资源；检查原 pending transaction、相关锁、owner 和 recovery evidence。重新计算候选/确认/current/HTML/prototype 摘要，任一变化停止该发布并重备具体 diff。未知锁不接管，不因年龄删除，不改其他任务状态。
+由原 owner 先 dry-run，再按同一明确批准 apply；写入顺序是不可变 revision、current、INDEX，逐步保存 validated/revision-written/current-published/index-written 的真实回执。current 已是相同候选且 snapshot 一致时只修复缺失索引/回执，不重复发布；只有 snapshot 存在时核验原批准和 expected current 后继续；current 已被其他发布更新则停止合并。调用方原 owner 保持不变。
+实施完成后，归档仅提升有跨 change 价值并有来源的规则。一次性页面与未采用候选留在原 change；implemented 必须有实质实现证据，只有设计确认的规则保持 approved-intent。promotion 展示下一连续 revision、保留规则、merge/supersede/skip、证据和 current 并发条件，取得该具体 diff 的授权后交给同一网关。promotion 在移动前完成；若原操作已移动，则从 archive 实际位置恢复，只补原批准操作缺失步骤、不再次移动。移动后核验唯一位置、未变 Outcome、原型/合同/批准 locator 与原发布回执，完成原回执后冻结。
+请求 v2 的 path/package_path 相对稳定 change 根；旧请求 v1 保持 project locator 只读解释。移动不可变材料前后须能解析相同原字节，不能为修路径重算批准或另建 operation。

package/template/workflows/specdev/common/rules/deviation-control.md CHANGED Viewed

@@ -6,8 +6,8 @@
 - **local**：只改变局部实现，不改变 Ticket 的行为、范围、公共契约、路径所有权或验证；记录到 Evidence 后可继续。
 - **ticket**：改变 Ticket 的执行路线、可写范围、局部契约或验收映射，但不改变 Spec；必须停止相关修改、更新 Ticket 并获得该 Ticket 或计划明确的批准 owner 同意。
-- **spec**：改变外部行为、范围、用户故事、验收合同或非功能要求；必须返回 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`。
-- **architecture**：改变已接受架构决策或公共架构约束；必须返回 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 并更新 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`。
+- **spec**：改变外部行为、范围、用户故事、验收合同或非功能要求；必须返回 `<Path>{roots.workflows}/specdev/specdev-s-spec/SKILL.md</Path>`。
+- **architecture**：改变已接受架构决策或公共架构约束；必须返回 `<Path>{roots.workflows}/specdev/specdev-g-grill-with-docs/SKILL.md</Path>` 并更新 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`。
 - **release**：改变迁移、兼容窗口、发布门禁、回滚或不可逆批准点；必须停止并获得明确人工批准。
 ## 2. 触发条件
@@ -41,5 +41,5 @@
 - 未批准的 ticket、spec、architecture 或 release 偏差不得继续实现。
 - 不得通过扩大 `writable_paths`、删除测试、降低断言或把风险改写成“已知限制”来绕过停止。
-- 偏差影响并行执行、source checkpoint 或 candidate 集成时，Lead 必须暂停受影响 Wave，重新计算路径所有权、依赖、Gate 与父分支顺序；任何 subagent 都不能自行改写上层合同。
+- 偏差影响并行执行、source checkpoint 或 candidate 集成时，Lead 必须暂停受影响 Wave，重新计算路径所有权、依赖、Gate 与父分支顺序；任何 任务执行者 都不能自行改写上层合同。
 - 偏差跨越多个成员时，父 Lead 先递增 Implementation Map revision，再重算 Implementation Plan；旧派单和 candidate 全部标记 stale。