@namewta/speculo 1.0.21 → 1.0.24

package/template/workflows/specdev/G-grill-with-docs/grilling-protocol.md

@@ -24,3 +24,7 @@
 - 每个已回答、延后或拒绝的节点追加一条 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 记录，并把 `LOG-###` 写回节点的 `log_ref`。
 - 每轮开始前原子更新 `round`，重读设计树后计算 frontier：`status=open` 且全部 `depends_on` 节点为 `answered` 的节点集合。
 - LOG、设计树及已确认的 CONTEXT/ADR 同步只用于恢复和领域建模，不构成实现授权。只有 frontier 为空且用户确认共识后才路由下游 work。
+
+## 生产风险问题
+
+按当前 change 风险选择状态 owner、成功时点、取消后仍在运行的工作、重复/乱序调用、服务端超时的未知副作用、旧数据解释与恢复验证。依据 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path> 定义可观察保证；不要把能查明的代码事实反问用户。

package/template/workflows/specdev/G-grill-with-docs/references/interview-procedure.md

@@ -132,3 +132,7 @@ frontier 为空时，向用户确认设计树的每个分支均已走过且已
 - CONTEXT 格式：`<Path>{roots.workflows}/specdev/common/rules/context-format.md</Path>`
 - LOG 格式：`<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`
 - Stakeholder 问卷：`<Path>{roots.workflows}/specdev/G-grill-with-docs/stakeholder-questionnaire.md</Path>`
+
+## 决策记录的完整性
+
+结晶时区分采纳决定与实际落地；ADR 留真实备选、理由、代价、适用范围和验证义务，未确认解释留 LOG。以后路径/命名变化更新当前事实，决定改变则保留取代关系；永久知识仍经 A，不把提案当作已实现。

package/template/workflows/specdev/I-implement/I-implement.md

@@ -3,8 +3,8 @@ id: specdev/implement
 type: workflow-entry
 workflow: specdev
 name: 实现与验收
-description: 执行已授权的 Ready Ticket 或获批 Direct Spec，产生可回读实现和验收证据；不从模糊需求直接写代码。
-keywords: [implement, Ticket, TDD, Evidence, integration]
+description: 执行已授权的 Ready Ticket 或获批 Direct Spec，覆盖代码实现与文档维护，产生可回读验收证据；不从模糊需求或只读审查直接写入。
+keywords: [implement, Ticket, TDD, Evidence, integration, documentation, 文档维护]
 ---
 
 # 实现与验收
@@ -25,6 +25,12 @@ keywords: [implement, Ticket, TDD, Evidence, integration]
 4. 安全、并发、公共接口、数据迁移或用户要求全面审查时展开 `<Path>{roots.workflows}/specdev/common/skills/code-review/references/risk-review.md</Path>`；不为省上下文删减必要检查或限制发现数量。
 5. 写 Evidence、运行适用校验并回读后才推进状态；必需 Skill 失败、验收失败、越界或归属冲突暂停本票及依赖它的分支。无关工作仍由总控继续，不接管他人事务。
 
+## 专业分支与工程判断
+
+已授权的 documentation Ticket 或获批 Direct Spec，读取 <Path>{roots.workflows}/specdev/I-implement/references/documentation-procedure.md</Path>；它只替换不适用的代码 TDD步骤，不跳过原预检、两轴审查、workspace、授权或完成门。
+
+失败/重试/取消/恢复读取 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path>；异步资源、CI flake、替换测试读取 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path>；工具/prompt/schema/结果变化读取 <Path>{roots.workflows}/specdev/common/rules/agent-experience.md</Path>。沿真实调用入口与消费者两端验证，不能用内部函数或 mock 的通过代替产品路径。检查和证据复用只按原证据规范，不默认重跑全仓。
+
 ## 返回总控
 
 完成、暂停或重规划后返回 `<Path>{roots.workflows}/specdev/P-goal-plan/P-goal-plan.md</Path>` 的当前 Goal；旧父 O 恢复键继续有效。恢复先核对 HEAD、Ticket/Skill 摘要、证据和未闭合动作，避免重复提交、迁移、发布或正式记忆写入。没有不可变实现证据时不得宣称完成。

package/template/workflows/specdev/I-implement/evidence-template.md

@@ -139,3 +139,7 @@ subagent 不写本 Evidence；以上内容由 Lead 从实际 workspace、Git 和
 ## OPS 交付（仅用户请求时）
 
 交付前读取 `<Path>{roots.workflows}/specdev/common/rules/deployment-handoff.md</Path>`，记录当前 change/Ticket、代码 revision、实际构件 digest、AC/Evidence、目标与部署约束；回传时只追加经核对的 Run/Release/receipt 指针。未请求写“不适用”，不为填表创建 OPS 任务。
+
+## 工程检查的选择与失效
+
+记录为什么选择这些定向检查、覆盖哪些消费者与风险；复用时列原 checkpoint/配置/输入/Skill 与有效性，失效时只列受影响项。测试删除列旧风险到新测试的承接；资源清理记录真正完成信号。专业分支按 <Path>{roots.workflows}/specdev/common/rules/engineering-evidence.md</Path> 在本文件追加标记记录；普通实施不要求空白记录，结构通过不认证真实运行。

package/template/workflows/specdev/I-implement/execution-preflight.md

@@ -42,3 +42,7 @@
 - **e2e-owner-invalid**：required 模式 E2E 被安排在 source worktree，或任一模式不是 Lead owner；停止并修 Ticket/Goal Plan。
 - **direct-parent-invalid**：current 模式的 Ticket commit、父 HEAD、验证或 Evidence 不一致；保留最后可信 commit 并阻塞当前 Ticket。
 - **parent-plan-stale**：父 Implementation Map revision、成员 Ticket、serialization、workspace 策略、全局实现配额或 repository/ref 已变化；停止当前派单并返回 P-goal-plan 重算。
+
+## 验证范围与失败保证
+
+冻结本票真实消费者、配置/构建入口、适用文档与验证命令；不把 DSH 命令当项目事实。只复用输入和环境仍有效的证据；失败副作用未知时按 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path> 暂停依赖工作，恢复前沿原 owner 核实，不重放未决动作。

package/template/workflows/specdev/I-implement/references/documentation-procedure.md

@@ -0,0 +1,21 @@
+# 文档维护执行分支
+
+仅在已授权的 Ready documentation Ticket 或满足原条件的 Direct Spec 中使用；当前 Work 仍为 `specdev/implement`，权限、workspace、commit 和验收仍走 I。文档建议或审查请求不授权写入。入口预检和两轴审查不因选择本分支消失。
+
+## 定位事实与修改范围
+
+读取 <Path>{roots.workflows}/specdev/common/rules/documentation-standard.md</Path>，先定位项目的真实源码、当前接口说明、相关 README、生成器和适用写作规范。区分只改说明、修正示例以及改变 prompt/tool/CLI/UI 可见行为。按 Ticket 的获批写集维护项目文档；Evidence 留在原 change 的本票文件或 Direct Spec Evidence，不创建第二份文档状态。
+
+列出每条行为声明的 owner 与验证方法：源码、类型、实际命令、运行场景或人工核对。先修 owner，再同步相应派生物与项目要求的语言侧；禁止手改生成文件。保存行为、条件、否定、例外、失败与所有权，消除仅本会话可理解的叙述。
+
+## 验证与交付
+
+纯说明修改使用相关链接、类型片段、示例、生成一致性和语义核对，不伪造代码 red/green。写入命令实际运行后才记录对应成功结果；缺网络、平台、凭据或权限时保留未验证和责任人，不替换成 mock 后写“真实入口通过”。
+
+可见行为改变时，补充实际输出或目标项目的行为快照/场景证据，并在需要时读取 <Path>{roots.workflows}/specdev/common/rules/agent-experience.md</Path>。默认值、错误、兼容或数据格式变化与代码同改；外部破坏的升级说明在当前改动产生，写清旧新行为、受影响者、迁移验证与真实回退限制。
+
+在原 Evidence 记录 `Engineering Evidence`，kind 为 `documentation`；字段与校验见 <Path>{roots.workflows}/specdev/common/rules/engineering-evidence.md</Path>。每项声明为 verified 或 unverified；总体 partial/blocked 不等于 Ticket done。新分支使用 `--engineering documentation` 校验对应原工件，再完成 I 的适用项目验证、两轴审查、状态回读和交付。
+
+## 失败与恢复
+
+以原 Ticket/Spec、文档 owner、源摘要和已运行证据恢复；输入漂移使相应验证失效，不覆盖旧证据。上层行为合同冲突返回原 owner。required 验证未运行时不能以“只改文档”越过 Gate；不适用须说明原因。结果明确区分修改了什么、实际运行了什么、只核对了什么和仍待验证什么。

package/template/workflows/specdev/I-implement/references/implementation-procedure.md

@@ -16,6 +16,10 @@
 
 只有极小、局部、单一行为、低风险、可逆且无需 Ticket DAG 的工作，才可在用户批准后直接基于 Spec/ADR/CONTEXT 在 current workspace 执行。先确认目标、IN/OUT、唯一写入 owner、可写范围、关键不变量、验证和验收。出现公共 API/schema、迁移、安全、高风险、多个行为或并行需求时返回 T-tickets。
 
+### Documentation 分支
+
+Ready documentation Ticket 或获批 Direct Spec 需要维护项目文档时读取 <Path>{roots.workflows}/specdev/I-implement/references/documentation-procedure.md</Path>。继续执行下方全部适用预检、workspace、commit、双轴审查、Evidence 和完成步骤；仅纯说明变更的代码红绿循环由可运行示例/类型/链接/生成与事实验证替代。prompt/tool/CLI/UI 文案属于可见行为，不能按纯说明豁免。
+
 ## 输入
 
 两种模式都必须读取：
@@ -80,7 +84,7 @@ Ticket 模式下，Lead 根据 Ticket 独立性、路径冲突、上下文、风
 
 ### 4. TDD 红→绿垂直循环
 
-加载 `<Path>{roots.workflows}/specdev/I-implement/tdd-rules.md</Path>`、`<Path>{roots.workflows}/specdev/I-implement/tdd-test-design.md</Path>` 和 `<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`。对每个验收行为或关键风险：
+加载 `<Path>{roots.workflows}/specdev/I-implement/tdd-rules.md</Path>`、`<Path>{roots.workflows}/specdev/I-implement/tdd-test-design.md</Path>` 和 `<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`。纯说明文档按上方 documentation 分支验证；其余对每个验收行为或关键风险：
 
 1. 选择公共接口或稳定接缝；
 2. 编写因目标行为缺失而失败的测试/验证并确认失败原因；
@@ -94,6 +98,8 @@ Ticket 模式下，Lead 根据 Ticket 独立性、路径冲突、上下文、风
 
 新增或修改代码注释时，先判断信息能否由命名、类型或结构表达，并同步维护受行为变化影响的既有注释。
 
+涉及错误、取消、并发或资源释放时，按 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path> 和 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path> 验证实际状态与清理完成。注册、Worker、CLI、配置和发布路径要覆盖真正入口；删除旧测试前核对全部风险承接，不因为新接口测试存在就删除。
+
 ### 5. 实现检查、commit 与 Lead 接收
 
 Ticket 模式的 implementation owner 按 Goal Plan 策略在当前 workspace 或来源 worktree：

package/template/workflows/specdev/I-implement/tdd-mocking.md

@@ -17,3 +17,7 @@ Mock 只位于系统边界：外部 API、不可控时间/随机、必要时文
 - 自有业务行为由真实实现参与测试；
 - mock setup 没有复制生产路由逻辑；
 - 协议兼容、错误和非确定性有可观察验证。
+
+## 替身能证明什么
+
+声明替身替换的外部边界与保留的真实产品路径。mock 通过不证明真实 provider、网络或启动入口可用；要求真实验证却缺环境时仍未验证。不能删除原失败路径测试，只因新的 mock 更容易通过。

package/template/workflows/specdev/I-implement/tdd-rules.md

@@ -19,3 +19,7 @@
 ## 强制变异验证
 
 使用强制变异时，先保存基线 hash/diff，修改后核对实际执行文件的 diff 与测试选择。只有预期行为断言 red 才有效；编译错误、错测或变异未落地均不计。恢复原内容、复跑基线并核对 diff，把全过程记入 Evidence。诊断协议见 <Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>。
+
+## 纯说明与测试承接
+
+纯文档按 <Path>{roots.workflows}/specdev/I-implement/references/documentation-procedure.md</Path> 执行适用验证，不伪造代码红绿；prompt/tool/output 改动仍属行为。旧测试删除必须覆盖其行为、错误、兼容和回归义务，具体按 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path>。

package/template/workflows/specdev/I-implement/tdd-test-design.md

@@ -23,3 +23,7 @@
 - 同义反复地重算预期值；
 - 绕过公共接口验证内部存储；
 - 只覆盖 happy path，遗漏 Ticket 明确的错误与边界行为。
+
+## 测试可靠性
+
+对真实 runner、配置、Worker、子进程和发布构件选择明确入口；运行资源立即登记清理并等待完成。用目标行为失败证明 red，不只断言 mock 次数。并发/时间/全局变量参见 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path>，压力重复不是确定性竞态测试。

package/template/workflows/specdev/I-init-setup/I-init-setup.md

@@ -19,6 +19,10 @@ keywords: [初始化, 配置, status, tracking, 验证命令]
 
 确认项目根 `.gitignore` 已含 `specdev-worktree/` 或 `/specdev-worktree/`；该条目由 `speculo init` 唯一维护，缺失时停止并提示重新运行当前版本 CLI，不由 Work 补写。
 
+## 能力探测的结果
+
+把每项能力区分为可用、未安装、未配置、未授权或当前不适用，并保留仓库依据；未知验证命令仍为 null。先定位真实项目 Skill 和构建/测试/发布入口，不把 DSH 命令或覆盖率搬进配置。探测不自动安装依赖、不运行发布，不创建虚假 change；再次初始化只补缺失骨架，不覆盖原历史。
+
 ## 选择初始化分支
 
 | 当前事实 | 执行 |

package/template/workflows/specdev/INDEX.md

@@ -24,3 +24,7 @@ keywords: [specdev, local-first, 规格驱动开发, decision-complete, prototyp
 ## Work 激活
 
 用户明确激活 SpecDev 或其中某个 Work 后，读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 取得 Work 条目、启动、恢复、状态、所有权和副作用合同，再进入目标 Work。仅发现本索引或读取永久知识不加载该合同。
+
+## 专业能力定位
+
+用户明确激活对应 Work 后再加载其分支：性能测量用 R-review-architecture；获批文档维护用 I-implement；无法复现事件的证据收集用 D-diagnose-bugs。保留原入口，不新增 Work ID 或另一套技能目录；只想了解当前 change 的实现仍用 L-learn-change。

package/template/workflows/specdev/L-learn-change/L-learn-change.md

@@ -19,6 +19,10 @@ keywords: [learn-change, change 学习, 开发后提问, 零基础, 大一新生
 4. **生成与保存**：读取 `<Path>{roots.workflows}/specdev/L-learn-change/references/lesson-format.md</Path>` 的完整格式和命名合同。先画 ASCII 全图，再按实际关系画短小结构/数据/调用/状态图；用短句解释箭头，术语先日常解释再给专业名字。验证零背景读者能复述三个答案；不能时拆图或换词，不灌长文。
 5. **追加而非覆盖**：从 `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 及同目录真实图解的最大编号取下一号；先原子创建 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>` 新图解，再更新索引并回读。重讲同主题仍新增编号，保留旧文件、原顺序和全部历史行。产物仅为纯 Markdown/ASCII，不生成 HTML、CSS、SVG、图片或浏览器依赖，不写 `<Path>{roots.state}/learning/</Path>`、生产代码、永久知识或远程系统。
 
+## 事实、理由与解释
+
+图解中明确已验证实现事实、可定位设计理由、教学类比与未知。讲解失败或恢复时引用实际契约与证据，不编造事故；旧计划与现状不同要指出差异，不把提案当事实。重新讲同主题仍追加新编号，不覆盖历史，不改 Learning workflow，也不把理解总结直接晋升永久知识。
+
 ## 验收与恢复
 
 ```bash

package/template/workflows/specdev/L-learn-change/references/lesson-format.md

@@ -45,3 +45,7 @@
 4. `## 你现在能复述什么`：用短句归纳“它是什么、为什么需要它、它怎样流动或被调用”。
 
 图中的方框名称使用普通名词和动词，不用缩写；箭头必须有方向。一个图只讲一个问题。确有边界、失败或例外时，单独画一张小图说明，不把它塞进主图。
+
+## 解释依据
+
+在原四节中区分已验证事实、可定位理由、教学类比与未知；需要时用原 ASCII 图展示失败和恢复方向。旧 Spec 与实现不一致时说明差异；新理解追加编号，不改旧文件，不增加其他格式产物。

package/template/workflows/specdev/P-goal-plan/P-goal-plan.md

@@ -41,6 +41,12 @@ keywords: [goal, 目标, plan, run, resume, replan, verify, Lead]
 - 他人 owner、资源或事务冲突仅暂停受影响的依赖闭包；继续独立已授权工作，不抢占、解锁或覆盖他人内容。正式记忆仍只走原网关。
 - 调度调用 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>`；调度器不代替实现、审核或授权。长期运行指可恢复，不承诺后台或无限运行。
 
+## 证据复用与停滞恢复
+
+验证复用按 <Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path> 核对代码、配置、输入、Skill、环境和原输出；只使受影响证据失效。升级兼容、迁移、用户可见行为或性能测量仅在风险相关时成为 Goal Gate，不增加普遍必跑流程。
+
+保留原无进展停止：同一 blocker 没有新证据时不重复派发。新 Dispatch 必须说明输入、方法、范围、环境或责任处置的实质变化；换 Agent 或清空 attempts 不是变化。恢复仍核对原授权、owner、Lead epoch 和未决副作用，不接管他人资源。
+
 ## 校验与交付
 
 从 map 运行只读控制检查（它不执行代码或授予写权限）：

package/template/workflows/specdev/P-goal-plan/completion-control.md

@@ -41,3 +41,7 @@ Lead 在每个 Gate 汇总覆盖 Evidence、接口/数据/兼容状态、candida
 Lead 是 Goal Plan change 的唯一完成 owner。没有 Goal Plan 的单 Ticket/Direct Spec 由当前 I-implement owner 按 change completion 规则完成。Archive 不补造完成证据。
 
 **完成标准**：所有通过、阻塞、取消和未验证声明均定位到权威工件、命令与 Git checkpoint；失败不会推进父分支或 Done。
+
+## 完成声明的版本
+
+关闭前核对最终实际代码/配置/构件与证据版本，说明未运行项、行为差异和残余风险。性能微基准、原型或 mock 不替代明确要求的真实路径。PR/Issue/发布分别回读原账本，远程 pending 不伪装已交付。

package/template/workflows/specdev/P-goal-plan/lead-orchestration.md

@@ -36,3 +36,7 @@ Lead 核对基线、路径、commit、dirty 状态、项目事实与非 E2E 结
 只有 Lead 的复盘决定已写入 Evidence，才可将当前 Ticket 的 `attempts` 重置为 `0` 并发出新 Dispatch Packet；新 Packet 必须引用该 Evidence 并明确相较上一轮改变了什么。没有实质变化时不得重新派发同一请求。上限因此是 Lead 复盘触发点，不是 Ticket 的永久失败终态。
 
 **完成标准**：每次写入只有一个 Ticket/owner/worktree；所有 SpecDev 状态由 Lead 落盘；派单、返回与重复失败后的 Lead 决定可从 Evidence 恢复。
+
+## 可解释的再派发
+
+重复 blocker 且没有新证据时保持原停滞停止。新的 Dispatch 明确改变输入、方法、范围、环境或处置的哪一项；仅更换 Agent、重置 attempts、让用户再答相同问题不构成恢复。旧历史保留，按原 owner 和依赖闭包处理。

package/template/workflows/specdev/P-goal-plan/planning-modes.md

@@ -72,3 +72,7 @@ Goal 全局执行门与 Ticket DoR 分开判断。以下任一全局条件未满
 - provider 与派单在执行期决定，不成为 Goal Plan 的静态枚举。
 
 **完成标准**：所有固定字段、适用模式、授权、Lead、父分支和阻塞均可验证；没有替代编排模型或空占位。
+
+## 按风险选择 Gate
+
+兼容、迁移、恢复、性能和用户/模型可见行为仅按真实影响设置 Gate。Gate 说明不可替代的证据、执行环境与失效条件；不要要求所有未来票同时 Ready，也不让局部字段通过替代全局执行授权。

package/template/workflows/specdev/P-prototype/P-prototype.md

@@ -19,6 +19,10 @@ keywords: [prototype, UI 原型, 风格检测, 设计系统, HTML, CSS, 交互,
 
 逻辑/状态/规则验证读取 <Path>{roots.workflows}/specdev/P-prototype/logic-protocol.md</Path>，跳过下方 UI 专属步骤。UI 仍默认离线持久化，默认 3 个、最多 4 个方案。只有用户明确要求项目内预览时读取 <Path>{roots.workflows}/specdev/P-prototype/project-preview-protocol.md</Path>；其临时写集与清理由该分支管理，下方 UI 设计权威与离线交付保持。
 
+## 交互和逻辑状态
+
+按项目风险验证正常、空、加载、失败、取消、重试、权限不足和恢复状态。复用既有 token/组件；主题、窗口边缘、响应式、键盘、focus、遮挡与可访问性均由真实项目需求决定，不搬 DSH 视觉常量。失败反馈遵守 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path>，提示与有效数据有明确生命周期。原型只证明原型路径，不冒充生产或真实 API 验收。
+
 ## 输入与所有权
 
 - 必需输入：目标项目或新产品设想、核心用户任务，以及当前 SpecDev change。

package/template/workflows/specdev/P-prototype/generate-design-package.md

@@ -48,3 +48,7 @@ node <Path>{roots.workflows}/specdev/P-prototype/tools/materialize-prototype.mjs
 随后运行局部 validator、项目可用的 HTML/CSS/JS 检查和浏览器视口检查，把命令、退出码、关键输出与截图相对路径写入 `Validation and Handoff`。
 
 **完成标准**：物化二次运行无 diff；最终页面离线可用；所有验收项有证据而不是口头断言。
+
+## 状态矩阵与证据标记
+
+为适用正常/空/加载/失败/取消/重试/权限不足/恢复场景记录预期反馈与交互。核对主题、窗口边缘、响应式、键盘、focus 和遮挡。每个录制或截图标明原型/真实服务/fixture、准确源码与环境；不同运行不能拼成一次成功，原型不证明生产行为。

package/template/workflows/specdev/P-prototype/style-selection-protocol.md

@@ -39,3 +39,7 @@
 每轮更新 frontmatter、`Style Decision` 中的选择表和拒绝理由，再原子重读。用户尚未看到候选 HTML、回答含糊或多个方向仍会改变核心布局时保持 `status: selecting`。用户不在线时可以继续补充可发现证据和生成候选，但不得替用户选择最终风格。
 
 **完成标准**：八层决策均为 confirmed 或明确 not-applicable；被拒绝候选有原因，组合候选有逐区域边界，最终方向能直接生成 token 与页面。
+
+## 复用与失败反馈
+
+先复用项目已有 token、组件和布局；候选差异对应用户任务，不机械套上游字体/颜色常量。检查失败操作仍保留有效内容，提示 owner 活得足够久，不随已关闭面板消失。偏好已确认且未受影响时不重复询问。

package/template/workflows/specdev/R-retro/R-retro.md

@@ -19,6 +19,10 @@ keywords: [retro, retrospective, 复盘, 环境, 反馈, 改进]
 4. 按 <Path>{roots.workflows}/specdev/R-retro/retro-template.md</Path> 创建 <Path>{roots.state}/specdev/changes/{change}/retro/RETRO-###.md</Path>，选择最小未占用 ID。原子保存并重读，运行 SpecDev --stage retro；修订保留来源与被替代结论。
 5. 验证通过后追加 works_run=specdev/retro 并清空 current_work；证据不足可完成一份 outcome=insufficient-evidence 的诚实报告，不冒充解决问题。只读复盘不创建 Spec/Ticket 或 implementation Evidence。review-only change 按专用完成门关闭。
 
+## 改进必须能被证伪
+
+逐项判断是规则缺失、规则未接入、规则判断错、测试不能失败或环境事实变化。建议说明真正修改位置、owner、正反验收、恢复影响和新增维护成本；不要对每个问题都增加一条提示词。记录已观察因果、尚未验证解释和不采纳理由，复盘报告不等于修复完成。
+
 ## 结果与路由
 
 合法 outcome：findings、no-findings、insufficient-evidence。发现的 disposition 为 file-issue / lesson-only / discard / duplicate；每项记录理由，允许没有发现。

package/template/workflows/specdev/R-retro/retro-template.md

@@ -25,3 +25,7 @@ updated_at: <ISO-8601>
 
 ## Routes
 下一入口、所需授权、未完成项及恢复条件；无后续动作注明原因。
+
+## 预防措施的验证
+
+对每个建议指出缺规则/未接入/判断错误/测试失效/环境变化，给出实际 owner、修改位置、正向验收、目标反例和新增成本。未实施建议不写成修复；无发现和证据不足仍按原 outcome 报告。

package/template/workflows/specdev/R-review-architecture/R-review-architecture.md

@@ -3,8 +3,8 @@ id: specdev/review-architecture
 type: workflow-entry
 workflow: specdev
 name: 架构审查
-description: 从用户指定范围或 Git 热点扫描代码库中的结构性坏味道、代码 judo 机会和维护性风险，以中文 Markdown 记录高置信候选，并对用户选择的一个方案运行设计树访谈。
-keywords: [架构审查, 维护性, 浅模块, 深模块, 局部性, 杠杆, 接缝, code-judo]
+description: 审查指定代码范围的结构与维护成本，或测量真实用户操作的性能并形成候选；只报告或深入用户选定的设计，不直接实施优化。
+keywords: [架构审查, 维护性, 浅模块, 深模块, 局部性, 杠杆, 接缝, code-judo, performance, benchmark, 性能]
 ---
 
 # 架构审查
@@ -36,14 +36,22 @@ keywords: [架构审查, 维护性, 浅模块, 深模块, 局部性, 杠杆, 接
 
 - `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>`
 
-每个候选都必须说明：files、structural problem、code-judo move、deleted complexity、dependency class、strength、ADR conflict、interview state 和 user conclusion。文件若因为本次变化接近或超过 1k lines，必须显式标注 decomposition pressure，不得默默吞掉。
+结构 report 的每个候选都必须说明：files、structural problem、code-judo move、deleted complexity、dependency class、strength、ADR conflict、interview state 和 user conclusion。文件若因为本次变化接近或超过 1k lines，必须显式标注 decomposition pressure，不得默默吞掉。
 
 ## 选择交付分支
 
 - `report`（默认）：用户只请求 review/扫描时完成下方探索与报告，候选保持 `unselected`；没有候选是有效结果，不要求用户先选方案才完成报告。
 - `selected-design`：只有用户已经选择一个候选并请求深入设计，才加载 `<Path>{roots.workflows}/specdev/R-review-architecture/references/selected-design.md</Path>`。输入是可回读报告和所选候选；来源漂移先核对影响，不用旧结论代替当前代码。
 
-两分支均不修改生产代码，报告不授权访谈、建票或实施。
+结构报告、已选设计和性能分支均不修改生产代码，报告不授权访谈、建票或实施。
+
+## Performance 分支
+
+选择 performance 时直接执行此参考，不强制运行下方结构 Report 流程；只读性能报告是有效终点，不要求先选择优化方案。
+
+用户要求定位性能成本或评估优化时读取 <Path>{roots.workflows}/specdev/R-review-architecture/references/performance-review.md</Path>，以真实用户操作、工作量、冷暖状态、时钟、原始样本和端到端结果形成测量与候选。performance 使用原 architecture-review 报告，不新建状态；代码实施仍交 S/T/P/I。无瓶颈、无收益、拒绝优化与证据不足均可诚实返回。需要确认已有性能故障根因时进入 D。
+
+结构/简化候选同时核对 API、状态、配置、重复表示、缓存失效、兼容与测试的实际维护成本、动态加载和真实消费者。单一 provider 不自动等于多余抽象；不要为删行数删除义务。
 
 ## Report 流程
 
@@ -84,6 +92,8 @@ keywords: [架构审查, 维护性, 浅模块, 深模块, 局部性, 杠杆, 接
 
 ## 分支完成、状态与返回
 
+`performance` 完成条件：测量卡、原始样本或明确缺口、可比较性和候选依据完整，工程证据检查已运行；baseline/inconclusive 是调查结果，不代表优化已经交付。报告已回读，后续实施必须另有授权。
+
 `report` 完成条件：范围有依据；高置信候选满足删除测试且每项有当前文件/调用/测试证据、前后对比、收益、强度和 ADR 冲突处理；最佳推荐唯一或明确为“无高置信候选”；Markdown 已原子写入并回读。未选择或拒绝的候选不变成 Ticket。
 
 `selected-design` 完成条件：用户选定的一个候选完成参考中的完整 frontier 访谈，或明确 blocked/rejected；只有接受且达成共识的方案才按原 Ticket 治理交接。其他候选保持未选择，不批量要求决定。

package/template/workflows/specdev/R-review-architecture/architecture-review-template.md

@@ -67,3 +67,7 @@ status: draft
 - 当前请求：report / selected-design。report 到此完成，访谈状态可为 unselected；无高置信候选也可交付。
 - 用户选择原文与候选 ID：仅 selected-design 填写；未选择时不虚构结论、不自动转票。
 - 达成共识的接受项进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`。
+
+## 性能测量（仅 performance 分支）
+
+按 <Path>{roots.workflows}/specdev/R-review-architecture/references/performance-review.md</Path> 填写用户操作、工作量/入口/时钟/环境/冷暖/排除成本、原始样本、内存与端到端边界、最强保留理由、候选及停止条件；无样本明确 inconclusive。使用 <Path>{roots.workflows}/specdev/common/rules/engineering-evidence.md</Path> 的标记记录，不把提案收益当已实施结果。普通结构报告不制造测量数据。

package/template/workflows/specdev/R-review-architecture/references/performance-review.md

@@ -0,0 +1,27 @@
+# 性能测量与优化候选
+
+仅在用户明确要求性能分析，或已有测量指出真实用户操作成本时进入。当前 Work 仍为 `specdev/review-architecture`，结果写回 <Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>；不创建性能状态库，不修改生产实现。已有性能故障需要确认根因时交 D。
+
+## 测量前冻结问题
+
+确认用户操作、可观察完成点、典型与长尾工作量、资源限制、允许的行为差异和停止条件。读取当前源码、构建入口及现有 benchmark；基于真实消费者而不是函数外观提出候选。缺权限或数据时报告无法测量，不估造结果。
+
+测量卡记录操作、代码 checkpoint、输入构造与 digest、入口、环境、单位、方向、时钟起止、冷暖状态、排除的外部模型/网络成本、原始样本、内存保留及判定方式。允许的时间/内存预算需要项目或用户依据，不照搬 DSH 常量。只有零个测量样本时结果必须为 `inconclusive`。
+
+使用脱敏的固定合成输入，不能把用户原始 prompt、路径、身份、密钥或可识别片段放入 fixture。冷启动使用独立进程与临时根；暖态明确保留何种缓存。临时探针、独立 fixture 或基准脚本仍须明确授权及清理，不能把性能调查当成生产重构许可。
+
+## 测量与判断
+
+先保存基线，再按已获授权做最小区分性实验；一次改变一个因果因素。相同输入、入口、环境、时钟、冷暖条件和完成点才能比较。记录全部样本与选择汇总方式的理由，不挑最快一轮；均值下降本身不证明收益超出噪声。端到端操作与局部阶段分别测量；峰值、暂时分配和可达对象保留也分别说明。
+
+优化候选说明真实调用方、重复工作、预计复杂度、可证伪干预、最强保留理由、维护成本和必须保持的行为。缓存需要失效策略、有界保留、独立取消与释放；删除解析/冻结/校验前说明所有权与信任边界。提升吞吐不能隐瞒长尾延迟或内存恶化。
+
+没有瓶颈、没有净收益、证据不够或不值得增加复杂性都是合法结论。报告候选不自动建票；用户接受后按原 S/T/P/I 链执行。只有优化实际实施且行为验证通过，才能把可比较数据作为“已改善”候选证据；R 的普通调查通常只产出基线及提案。
+
+## 可回读记录与验收
+
+在原报告增加 `Engineering Evidence`，记录格式见 <Path>{roots.workflows}/specdev/common/rules/engineering-evidence.md</Path>，kind 为 `performance`。新分支运行现有校验器的 `--engineering performance`，输入当前 change；它会拒绝无样本的测量声明、不可比较记录和与数字相反的改善声明，但不认证时钟、数据真实性或统计显著性。
+
+行为回归和性能反例分开。实际改进交 I 后，检查必须能在原实现或受控成本回引时失败；把预算放宽到退化也通过，不构成保护。汇报原始数据、包含与排除成本、候选、拒绝原因、已执行检查及未覆盖路径。
+
+方法参考：<Url>https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/.agents/skills/dsh-speed-up-perf/SKILL.md</Url>。

package/template/workflows/specdev/R-review-architecture/references/selected-design.md

@@ -21,3 +21,7 @@
 ### 4. 转化为执行工作
 
 只有被接受且有具体变更压力的提案进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`。加载 `<Path>{roots.workflows}/specdev/R-review-architecture/proposal-to-ticket.md</Path>`，按 Prefactor、Standard 或 Deep/expand-contract 建立 Ready 治理；只有能删除复杂性的提案才继续，纯重排和 thin wrapper 不进入 Ticket。
+
+## 从候选到验收
+
+接受的简化必须保持现存消费者、安全、兼容和持久数据义务；若主动放弃能力，交上游明确批准。原测试删除逐项给出承接证据；性能候选把可比较测量和行为保持一并交票，不将估计收益改写为已验证。

package/template/workflows/specdev/R-review-architecture/review-rubric.md

@@ -50,3 +50,7 @@
 ## 报告门槛
 
 不要把报告写成杂音集合。只保留高置信 finding。若没有候选通过门槛，就直接写 `无高置信候选`，不要硬造一个来填模板。
+
+## 维护义务与最强反对理由
+
+候选记录真实生产消费者、动态配置/加载、第三方接口、数据与兼容义务。明确移除了哪些状态、配置、表示、失效路径和测试负担，剩余 glue 的代价是什么，以及最强保留理由。单 provider 或静态零调用不自动证明可删；代码行数只用于发现，不作收益指标。性能提案必须先使用 <Path>{roots.workflows}/specdev/R-review-architecture/references/performance-review.md</Path> 测量。

package/template/workflows/specdev/README.md

@@ -33,7 +33,7 @@ CLI 初始化和刷新保持原 namespace、三方配置合并、schema migrator
 
 ## 状态字段
 
-全局 status/config 保留 v5；change status 与 Goal Plan 保留 v6；Spec/Ticket/Map 保留 v3，新增 Plan 扩展版本 1；父 Map/Plan 保留 v1。详细字段、枚举、worktree Evidence 与旧工件兼容见状态细则，不为压缩文档另建状态库。
+全局 status 保留 v5，config 保留 v6；change status 与 Goal Plan 保留 v6；Spec/Ticket/Map 保留 v3，新增 Plan 扩展版本 1；父 Map/Plan 保留 v1。详细字段、枚举、worktree Evidence 与旧工件兼容见状态细则，不为压缩文档另建状态库。
 
 ## 路径分配
 
@@ -49,22 +49,30 @@ CLI 初始化和刷新保持原 namespace、三方配置合并、schema migrator
 
 不清晰的大需求选 W，单 change 的高影响决定选 G，Ready Spec 拆票选 T-tickets，单个已拆票 change 或多个 Ready change 的 Goal 选 P-goal-plan；来源冻结/远程回写/完成后记账/尚未成 Change 的记事项才选 T-triage。精确条件与全部出口见 `<Path>{roots.workflows}/specdev/common/rules/workflow-routing.md</Path>`。
 
+## Work 能力与专业分支
+
+每个 Work 的具名入口 Markdown 就是可调用技能入口，保持原 id、名称、路径与恢复键；Work 不等同于一个常驻 worker，也不要求启动子 Agent。按用户意图与已有工件进入，不把全部 Work 串成每次必跑流水线。
+
+R 的 performance 分支先测量再给优化候选；I 的 documentation 分支在原 Ready Ticket/获批 Direct Spec 内维护项目文档；D 的 evidence-triage 只收集事件证据，不宣称根因确认。这些分支使用原 Work、原 owner 和原工件，不修改主持久化 schema。T 继续拥有原远程模式和账本，不另设发布状态库。
+
+同一次任务已加载且摘要未变的规则不机械重复读取；必要安全限制仍在动作前核对，范围/摘要/owner 变化时只重读受影响内容。专业证据的结构检查不认证真实工具或模型行为。
+
 ## Work 条目
 
 
 <!-- AUTO-INDEX-START -->
 
 - **A-archive-and-consolidate** — 归档与沉淀：校验本地完成、源 Issue reconcile 门和票级 publish_action 门，复用全局归档能力移动 completed change 并提升当前知识，或从代码访谈形成可归档知识 change。
-- **C-code-review** — 代码审查：将 commit、branch、tag、merge-base 或 PR 解析为本地不可变固定点，执行隔离的标准轴与规范轴审查并持久化可恢复报告。
-- **D-diagnose-bugs** — 诊断 Bug：先建立会在精确症状上变红的紧凑反馈回路，再通过最小化、排名假设和单变量探针确认根因，输出修复契约而不实施生产修复。
+- **C-code-review** — 代码审查：按用户指定的 PR、单 commit、区间或基线冻结真实比较范围，执行隔离的标准轴与规范轴审查；有效空差异诚实返回，不实施修复或发布。
+- **D-diagnose-bugs** — 诊断 Bug：调查故障并建立精确症状的红灯回路，以单变量实验确认根因；无法安全复现时仅收集事件证据，不将解释冒充根因，也不实施生产修复。
 - **G-grill-with-docs** — Change 决策访谈：一个已界定 change 仍有产品、领域或架构决定待确认时进行可恢复访谈；跨 change 边界未清晰时先用 W。
-- **I-implement** — 实现与验收：执行已授权的 Ready Ticket 或获批 Direct Spec，产生可回读实现和验收证据；不从模糊需求直接写代码。
+- **I-implement** — 实现与验收：执行已授权的 Ready Ticket 或获批 Direct Spec，覆盖代码实现与文档维护，产生可回读验收证据；不从模糊需求或只读审查直接写入。
 - **I-init-setup** — 初始化设置：初始化 SpecDev 的语言、配置、全局状态、本地 change 追踪、领域知识布局、验证命令和并发治理。
 - **L-learn-change** — Change 学习：在开发完成后围绕当前 SpecDev change 回答问题，并用面向零专业背景读者的 Markdown 与 ASCII 图解持续记录理解。
 - **P-goal-plan** — Goal 规划与执行：为单个已拆票 change 或多个 Ready change 规划、执行或恢复 Goal；只在用户要求交付编排或已有 map 需推进时使用，不代替需求探索和 Ticket 编写。
 - **P-prototype** — 逻辑与 UI 原型：按需验证离线逻辑模型，或检测现有项目的 UI 事实，按产品任务推荐并逐步选择设计风格，生成持久化设计系统文档、多风格 HTML 对照和可运行 HTML/CSS/JS 原型。
 - **R-retro** — 开发复盘：对指定开发活动、环境或协作流程的已观察摩擦做证据化复盘，形成根因、改进 owner 与可检验提案；代码讲解使用 L-learn-change，Speculo 产品反馈使用 retro 命令。
-- **R-review-architecture** — 架构审查：从用户指定范围或 Git 热点扫描代码库中的结构性坏味道、代码 judo 机会和维护性风险，以中文 Markdown 记录高置信候选，并对用户选择的一个方案运行设计树访谈。
+- **R-review-architecture** — 架构审查：审查指定代码范围的结构与维护成本，或测量真实用户操作的性能并形成候选；只报告或深入用户选定的设计，不直接实施优化。
 - **S-spec** — 编写 Spec：综合已知事实、设计决定、诊断与代码现状，产出以外部行为和验收合同为权威的 Ready Spec。
 - **T-tickets** — 编写计划型 Tickets：将已澄清的 Spec 或等价获批计划拆为可验收的实施 Ticket，并绑定真实项目 Skill；不用于探索未知需求或执行代码。
 - **T-triage** — 请求分诊与 GitHub 交付：摄入与核验外部请求、投影本地完成事实、交付 PR，或按明确目标处理 CI、安全告警、npm/GitHub Release 预检、发布和恢复；清晰的本地需求直接进入对应 Work。
@@ -84,7 +92,7 @@ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --
 node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --self-check
 ```
 
-支持 triage、diagnosis、grill、spec、tickets、goal-plan、implement、learn-change、review、prototype、wayfinder、complete。Goal 总控通过 P 的 map-control 参考使用只读控制器；它不授权或自动执行。只有进行完成转换时必须读取 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`，票全 done 不替代整体验收。
+支持 triage、diagnosis、grill、spec、tickets、goal-plan、implement、learn-change、retro、pr-delivery、review、prototype、wayfinder、complete。Goal 总控通过 P 的 map-control 参考使用只读控制器；它不授权或自动执行。只有进行完成转换时必须读取 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`，票全 done 不替代整体验收。
 
 ## 远程交付、逻辑原型与复盘
 

package/template/workflows/specdev/S-spec/S-spec.md

@@ -19,6 +19,10 @@ keywords: [spec, PRD, 用户故事, 验收合同, 接缝, 范围, readiness]
 4. **绑定验证接缝**：优先复用稳定接缝，通常从用户端到端行为、公共 API/CLI、事件/集成、稳定单元接缝选择；按实际风险与项目先例决定，不机械追求最高测试层级。每个接缝注明入口类型/位置、触发方式、可观察结果、覆盖 AC 和实际测试先例/命令。选择显著改变可测试性、事故半径或范围时聚焦确认；可由已有代码推导时记录依据即可。证据遵守 `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`。
 5. **Readiness**：对照 `<Path>{roots.workflows}/specdev/S-spec/spec-readiness.md</Path>` 与 `<Path>{roots.workflows}/specdev/common/schemas/spec.schema.json</Path>`。高影响未决问题使 `ready_for_tickets: false`；低影响、可逆默认值可作为带验证方式的显式假设。每个 AC 必须可观察、可判定、绑定接缝；不适用影响写明理由。
 
+## 失败与兼容合同
+
+适用时读取 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path>，把未开始/部分发生/已提交/未知结果、重复/乱序/取消、可重试前提、状态有效性和可见诊断写入原 AC/NFR。公共接口与旧数据变更须给出兼容、迁移和恢复限制。每项绑定真实可观察接缝或待建设接缝，不虚构错误码、性能阈值或安全保证。已知低风险变更不为了填表增加无关条款。
+
 ## 验证、状态与交接
 
 ```bash

package/template/workflows/specdev/S-spec/spec-template.md

@@ -93,3 +93,7 @@ sources:
 无。
 
 存在高影响未决问题时，`ready_for_tickets` 必须为 `false`。
+
+## 失败与兼容补充（适用时）
+
+在原 AC/NFR 编号下记录取消/重复/乱序、未开始/部分提交/已提交/未知结果、可安全重试前提、状态 owner、可观察错误和旧数据迁移/恢复限制。这里只补充适用合同，不新增另一套验收编号或实现计划。

package/template/workflows/specdev/T-tickets/T-tickets.md

@@ -35,6 +35,12 @@ node <Path>{roots.workflows}/specdev/common/tools/ticket-control.mjs</Path> --ma
 
 需要正式 Goal、多 change、迁移或跨票 Gate 时交给 `<Path>{roots.workflows}/specdev/P-goal-plan/P-goal-plan.md</Path>`；少量线性票可从 map 按已授权范围调用 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>`。不得以“精简”为理由静默更换默认工具或少交付。
 
+## 工程义务与证据失效
+
+每票按实际影响列明真实生产消费者、接口两端、文档/升级说明、回归与模型可见输出的责任；删除测试要给出原风险在新测试中的承接。风险及证据选择使用 <Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>，失败状态使用 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path>。工具定义或上下文变更才加载 <Path>{roots.workflows}/specdev/common/rules/agent-experience.md</Path>。
+
+将有关检查合并进负责该行为的 Ticket，不为每个检查项创建一票。documentation 仍用现有 kind，性能实施引用 R 的测量基线，不增加分类 schema。每票说明 base/head、配置、输入或 Skill 改变后哪些证据需重新验证。
+
 ## 原型证据
 
 可以引用已验证 LOGIC/UI 原型中的行为、边界与已确认决定，记录具体 locator 和验证证据；源码片段可承载设计选择，但不自动成为生产实现。未闭合高影响产品决定返回 G，S 综合已确认设计而不重新开启无关访谈。

package/template/workflows/specdev/T-tickets/decomposition-rules.md

@@ -54,3 +54,7 @@
 ### Bug fix
 
 已确认根因时，以 `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>` 的修复契约为依据；根因未知时先运行 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>`。
+
+## 工程证据随行为切片
+
+把文档、失败恢复、真实入口与回归检查放入拥有该行为的票，不逐检查项拆票制造交接。复杂迁移保留 Expand → Migrate → Contract 的真实顺序和旧数据核对；低风险文档继续使用现有 documentation kind。

package/template/workflows/specdev/T-tickets/ticket-readiness.md

@@ -48,3 +48,7 @@ status: ready
 ```
 
 未通过时保持 `ready: false`，并在未决问题、阻塞原因或偏差记录中写明原因。
+
+## 适用工程义务
+
+Ready 前确认真实调用方、文档/升级说明、正常与失败验证、恢复条件和证据失效条件。删除测试有风险承接；性能票有测量基线和真实用户操作；文档票分清纯说明与可见行为。缺少 required 验证不因工具暂不可用而标 ready。

package/template/workflows/specdev/T-tickets/ticket-template.md

@@ -149,3 +149,7 @@ E2E 由实际跨边界行为与风险决定，不限于 UI；required 模式不
 - **归属与资源冲突：** 暂停本票和受影响下游，不接管他人状态；独立票由 map 继续。
 - **检查点：** 记录源版本、绑定摘要、已完成步骤、Evidence 和未闭合动作；恢复前回读。
 - **完成出口：** 全部适用验收及实际 Skill 证据通过，再将结果交回 Goal；未完成项明确列出。
+
+## 工程验收补充（适用时）
+
+列明真实消费者/入口、文档和升级说明、错误后的状态保证、恢复责任、旧测试的风险承接，以及代码/输入/配置/Skill 变化时需重验的证据。性能票引用用户操作与基线；documentation 票区分纯说明与模型/用户可见变化。无关项写不适用及理由，不逐项另造 Ticket。

package/template/workflows/specdev/T-triage/T-triage.md

@@ -13,7 +13,7 @@ keywords: [triage, issue, PR, intake, reconcile, publish, capture, queue, releas
 
 ## 选择模式
 
-只读取选中分支，publish 专指 Ticket→Issue，release 专指包/GitHub Release。
+只读取选中分支，publish 专指 Ticket→Issue，release 专指包/GitHub Release。按意图先分组：请求摄入（queue/capture/intake）、完成投影（reconcile/publish）、PR 交付、CI/安全、版本发布（preflight/release）、原记录恢复。组名只是导航，不增加模式或 owner。
 
 | 模式 | 协议 | owner 与结果 |
 |---|---|---|
@@ -38,6 +38,12 @@ capture 不创建也不选择 change，不写 current_work，只使用 <Path>{ro
 
 尚未完成 change 的 intake 在 current_work 为空时登记 specdev/triage，他项占用先恢复或 handoff；成功去重追加 works_run 并清空 current_work，可恢复失败保留。已完成 change 的 reconcile/publish 和 PR 交付只更新各自账本，不占用 current_work，不重开实现状态。PR 不能修改来源关闭、Ticket publish 或 capture 状态。远程失败不能把已完成代码状态改回未完成。
 
+## 远程结果与检查有效期
+
+区分本地完成、push、PR created/ready/merged、Issue closed、npm 和 GitHub Release 的逐目标回执。queued、pending、skipped、未启动或环境失败不能写 passed；只重跑真正失效或失败的检查。PR/依赖交付固定真实 base/head、顺序和授权，改写后重新核对审查及 CI。删除来源分支前确认没有未完成依赖，不硬编码宿主必有某个 stack 扩展。
+
+超时先沿原 marker/目标对账，部分成功恢复原账本，不重建、不把远程失败倒灌为代码未完成。CI 资源问题按需读取 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path>；升级说明与实际构件、已发布基线和用户迁移步骤一起核对，不在 release 当天补造兼容承诺。
+
 ## 验证与返回
 
 使用 <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>：

package/template/workflows/specdev/T-triage/ci-security-protocol.md

@@ -9,3 +9,7 @@ CI：区分代码/类型/测试、工具版本、依赖、构建产物与临时
 安全：按项目政策读取 Dependabot、secret scanning、code scanning 的事实与影响。凭据泄露优先提出撤销/轮换方案，敏感细节保留在受控渠道；公开回复、关闭/删除内容、撤销凭据和修改配置须有准确动作授权。权限不足记 unknown，不能把无法读取当作零告警。修复后依据真实证据关闭，CI 绿不等于依赖安全。
 
 不设默认周期或统一 SLA，不自动合并、安装工具或创建监控。返回分类、证据、待授权动作、路由和恢复位置；只有记录完整并通过 --triage-run 校验才标 completed。
+
+## 区分失败与掩盖
+
+先核对 job 的实际 SHA、配置、执行和跳过原因，再分类产品、基线或环境失败。并发资源/时钟/清理问题按 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path> 设计有效回归，不无依据地增加 retry、sleep、timeout 或串行化。安全事实不清时不扩大权限或吞掉检查。

package/template/workflows/specdev/T-triage/pr-delivery-protocol.md

@@ -11,3 +11,7 @@
 5. 读回 URL、正文、draft 状态与 SHA，原子更新记录并重读，运行 SpecDev --stage pr-delivery。失败保留原记录；超时先按 marker 和分支查询。
 
 requested=false 或 waived 的记录不挡归档；明确请求且 pending/failed 的 PR 交付挡对应交付门，不回退已完成代码事实。创建成功不意味着 merge 或 release 已获授权。返回 PR、记录、验证和下一动作。
+
+## 证据与精确远端
+
+把演示、构件和检查绑定本次 base/head 与真实模式；没有 checks、queued、pending、skipped 或环境失败分别说明。报告 PR 已创建/ready/merged 的真实阶段，不把 API 请求接收当合并完成。依赖 PR 顺序与删除前零依赖都需回读；不假定 gh stack 可用。

package/template/workflows/specdev/T-triage/release-preflight.md

@@ -11,3 +11,7 @@
 7. 需要文档同步时，由 <Path>{roots.commands}/docs-sync.md</Path> 处理其 state、bootstrap 和范围；T 不改 sidecar。
 
 完成条件：记录中的 targets 数组及 Targets 正文列出每个包、registry、版本、dist-tag 与发布判定，Evidence 引用固定 SHA 的检查；unknown/冲突保留 blocked。预检通过并不授权 commit/push/tag/发布。
+
+## 兼容与用户迁移
+
+核对实际已发布基线、待发布构件与适用升级说明。说明受影响者、旧新行为、迁移步骤和确认结果；回退须有真实保证。预发布数据也有兼容义务，不能当作可随意丢弃的开发数据。

package/template/workflows/specdev/T-triage/release-protocol.md

@@ -10,3 +10,7 @@
 6. Release 正文来自已确认版本说明，按需读取 <Path>{roots.workflows}/specdev/T-triage/references/release-notes-injection.md</Path>。需要补记 docs-sync 输入节点时再次调用 docs-sync，由它维护游标；tag 保持不变。
 
 记录最终 SHA/tag/run ID、每个目标读回结果、docs-sync 结果或不适用原因。任一 required 目标未知或失败不得标 completed，保留已发布事实和后续恢复条件。全部通过才将 TRI 标 completed，运行 --triage-run 校验并返回报告。
+
+## 逐目标成功与未知结果
+
+npm、GitHub Release、tag 和其他获批目标各有回执，部分成功只恢复未完成部分。超时先核实原目标，不重复执行已确认效果；缺必需验证仍阻塞，不改本地开发完成状态。