@namewta/speculo 1.0.22 → 1.0.24

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

@@ -16,3 +16,7 @@
 相同根因重试必须记录新证据或与上次的差异；没有差异先停止。不得要求提供 Token 片段作为证明。
 
 错误定位：认证失败核对权限/有效期/OIDC 配置；provenance 核对 runner、repository 和 id-token；E422 核对 tag/Release 已存在与正文；EUSAGE 核对实际 CLI 版本和参数。不要通过默认删 tag、force-push 或删除远程对象处理这些错误。恢复后的 completed 仍需原发布协议的所有目标校验。
+
+## 证据失效与原 owner
+
+恢复原 TRI 和逐目标回执，核对 tag/版本/构件 digest/授权和外部状态。目标或正文漂移先重新确认范围；不凭旧记录重发，不清除他人锁，不把未知结果标失败后无条件重试。

package/template/workflows/specdev/W-wayfinder/W-wayfinder.md

@@ -26,6 +26,10 @@ W 位于 change 形成之前：Initiative → 候选 change → 各自 Grill →
 | 生成地图、问题与答案 | `<Path>{roots.workflows}/specdev/W-wayfinder/wayfinder-map-template.md</Path>`、`<Path>{roots.workflows}/specdev/W-wayfinder/investigation-ticket-template.md</Path>`、`<Path>{roots.workflows}/specdev/W-wayfinder/solution-comment-template.md</Path>` |
 | 选定清晰 change 交给 Goal | `<Path>{roots.workflows}/specdev/W-wayfinder/references/initiative-discovery.md</Path>` 的交接门禁 |
 
+## 调查的决策价值
+
+每张调查说明它影响的决定、已知事实、缺失证据、最小调查、结束条件和下一 owner。只对目的地相关的兼容、迁移、权限、故障、成本和部署约束展开，不把“全面研究”变成无限搜索。答案需有可回读来源；没有依据的候选继续未知，不能以调查完成代替产品完成。
+
 ## 必留纪律
 
 - 目的地约束所有调查；能精确陈述的问题成为调查票，尚不能陈述的留在战争迷雾，目标外内容不自动升级。

package/template/workflows/specdev/W-wayfinder/investigation-ticket-template.md

@@ -14,3 +14,7 @@ resolution: null
 ## 问题
 
 <此 Ticket 要解决的一个决策、调查或解除阻塞工作。>
+
+## 调查价值
+
+本问题影响的决定、已经可查的事实、缺失证据、最小调查、结束条件与下一 owner。只展开与目的地相关的风险；research/prototype/task 不自动转生产实现。

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

@@ -24,6 +24,14 @@
 - 代码库设计：`<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>`

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

@@ -0,0 +1,23 @@
+# 面向 Agent 的工具与 Work 体验
+
+修改工具名称、描述、参数、返回、prompt、Work、Skill 或上下文加载时读取。Work 的具名入口 Markdown 就是本工作流的技能入口；保留原 ID 与文件名，不另建技能注册根，也不要求每个 Work 启动子 Agent。
+
+## 发现、加载与执行分开
+
+description 写真实触发时机、任务范围和相近但不适用的场景，不写“资深专家”式角色自述。先展示用途、可用动作和必要限制，再按模式加载正文或 reference。延后资源必须有可理解的描述、可靠定位和读取条件；不能为减少首轮内容把必要信息藏到不可发现的位置。
+
+已加载同版本正文的同一次任务不重复读取；输入范围、摘要或 owner 变化时重读受影响内容。首次选中只看到摘要时必须读正文，不能从名称推导步骤。实际执行记录继续遵守 <Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>；读过入口不是执行完成。
+
+## 工具描述与结果
+
+参数的范围、默认值、配对和使用条件写在参数定义中。工具说明描述行为与返回，避免复制其他工具或系统段已经拥有的规则。权限、破坏性副作用、不可重复操作和必需验证必须在动作之前可见；描述不是底层权限检查的替代。
+
+返回有界的结果摘要以及可回读的 ID、路径或游标，明确截断、遗漏、分页和证据完整性。包含少量当前动作确实需要的邻近上下文，不整页倒出日志，也不因过度裁剪迫使下一步反复搜索。缺少资源、格式无效和加载失败要能辨认，不伪造可用性。
+
+## 作为行为验证
+
+检查模型真正收到的工具 schema、prompt、结果和诊断，覆盖正常、失败、取消、权限不足、重复调用和恢复中的适用分支。用户直接调用已注入的 Work 不应再次重复加载同一正文。仅宿主支持时才依赖自动/显式调用元数据；文字字段本身不是安全控制。
+
+比较优化前后实际首轮输入、总读取、重复调用、误触发和任务结果。在没有同模型、同工具、同任务的实际使用记录时，只报告文件字符或字节变化，不能宣称 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

@@ -95,3 +95,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/codebase-design.md

@@ -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/documentation-standard.md

@@ -0,0 +1,29 @@
+# 开发文档的归属、保真与验证
+
+在 SpecDev 中新增、修改、审查或整理项目文档时读取。本规则负责开发文档的工程要求，不改写全局写作能力。注释继续使用 <Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>；工件冲突遵守 <Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>。
+
+## 一项事实的负责位置
+
+Work 入口说明如何执行；common 说明跨 Work 判断；项目源码、接口说明与 README 描述当前行为；change ADR 保存已经接受的决定和真实取舍；CONTEXT 保存本 change 已确认领域语义；LOG 保存讨论、待验证解释和被替代结论；Evidence 记录实际验证。永久知识仅经 A 晋升，archive 是只读历史。
+
+按读者与任务区分教程和查询参考。教程按前置知识与操作顺序组织，参考限定自身负责的主题。上层文档只说明下属职责并链接具体 owner，不复制整个子模块实现。用户不需要的内部过程不要挤进入口；详细信息需要可定位而不是被删掉。
+
+## 改写前保留完整命题
+
+逐项保留行动者、动作、条件、时间与顺序、必须/可以/禁止、例外、所有权、副作用、失败保证及后果。删掉这些词可能改变行为，不是简单精简。局部使用点仍要有安全调用所需的完整契约；长篇理由、历史和算法说明链接其 owner。参考或生成内容先改真实源，再重建派生文件，不手工改生成物。
+
+正文描述当前机制，不保留“本轮修改”“下一张 PR”“审查者已认可”或只有某次会话才能解释的编号。必要历史与事故证据留在 LOG/ADR/复盘中；真实 issue、公开规范和可定位历史引用不因出现编号就删除。未知理由保持未知，不补写想象中的设计史。
+
+## 运行声明与升级说明
+
+字段、默认值、命令和平台行为查 owning source，并在有执行条件时运行文档给出的实际操作。仅检查文字或链接不能证明命令成功。缺少网络、凭据、平台或权限时，明确未执行项、风险与验证 owner；不换成模拟后声称真实路径已验证。
+
+外部可感知的破坏性变更在引入时同步升级说明：受影响对象、旧新行为、精确迁移步骤、成功确认和真实恢复限制。用户数据已经发布就不是可随意覆盖的开发数据；预发布名称不解除兼容义务。使用目标项目已有升级文档位置，没有惯例时由当前任务批准的项目文档路径承载，不新建 SpecDev 永久 namespace。
+
+双语或多语仅在目标项目要求时同步。保留未改变的已审文本，核对条款含义、术语、代码及链接；哈希或结构一致不证明翻译正确。不要照搬 DSH 的双语三件套、行数对齐和字数配额。
+
+## 文档维护与可见行为
+
+纯文档可以使用链接、示例、类型片段、生成一致性和事实核对，不伪造 TDD 或 E2E。涉及工具说明、prompt、错误消息或 CLI/UI 输出时按行为变更处理，追加实际模型/用户可见证据或明确未验证。执行入口见 <Path>{roots.workflows}/specdev/I-implement/references/documentation-procedure.md</Path>；C 可仅审查，不获得写入权。
+
+方法参考：<Url>https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/.agents/skills/dsh-prose-standard/SKILL.md</Url> 与 <Url>https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/docs/AGENTS.md</Url>。

package/template/workflows/specdev/common/rules/engineering-evidence.md

@@ -0,0 +1,31 @@
+# 专业分支的工程证据
+
+本规则只约束新运行的 R.performance、I.documentation 和 D.evidence-triage；既有工件与主持久化 schema 不升级。普通 Work 不要求额外记录。记录是某次 checkpoint 的观察，不拥有 Ticket/Goal/change 状态、授权或恢复锁；不能用它代替原 Evidence、诊断和验收。
+
+## 写入原 owner
+
+在原工件正文添加 `Engineering Evidence` 小节及一个标记为 `json specdev-engineering-evidence` 的代码围栏，里面是一个 JSON 对象。performance 位于 <Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>；incident 位于 <Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>；documentation 位于原本票 <Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path> 或原 <Path>{roots.state}/specdev/changes/{change}/evidence/direct-spec.md</Path>。禁止写到另一模式的 owner，旧归档与旧完成证据不回填。
+
+公共字段：`version: 1`、`kind`、实际源码/输入的 `checkpoint`、非空 `evidence` 字符串数组。指针使用原 Path/来源定位约定，不写机器绝对路径、密钥或未脱敏数据。记录每次真实观察，恢复时追加新 checkpoint 的证据；不能更改旧事实来制造成功。
+
+## Performance
+
+`operation` 是用户操作，`outcome` 为 baseline、improved、no-gain 或 inconclusive，`uncertainty` 解释测量局限。没有样本时只能 inconclusive。baseline/candidate 各含实际 `checkpoint`、`entrypoint`、`environment`、`clock`、`workload`、64 位 `workload_digest`、`unit`（ms/bytes/ops/s）、`direction`（lower/higher）、`cache`（cold/warm/not-applicable）、`excluded_costs` 字符串数组和有限非负 `samples` 数组。
+
+普通 R 调查只记录 baseline 或 inconclusive；improved/no-gain 需已有可比较的 baseline 与 candidate。比较除源码 checkpoint 外的工作量、入口、环境、时钟、单位、方向、缓存与排除成本必须一致。improved 还需 `behavior_verification: passed`，并且样本算术均值沿目标方向改善。满足这些必要条件仍不证明超过噪声、具备统计显著性、内存可接受或测量真实，Lead 必须回读数据与行为证据。
+
+## Documentation
+
+记录 `owner_paths`（真实源指针数组）、`outcome`（verified/partial/blocked）、`visible_behavior_changed` 布尔值、`behavior_verification`（passed/failed/not-run/not-applicable），以及非空 `claims` 数组。每项 claim 有 subject、method（command/source/manual）、state（verified/unverified）和 evidence。未验证项必须写 reason；verified 的 command 项还必须有 command、`executed: true`、`exit_code: 0` 和非空 output 原始结果摘要数组。
+
+总体 verified 要求所有声明 verified；可见行为改变时必须有 passed 的行为证据。partial/blocked 是诚实的阶段结果，不授予 Ticket done。工具仍不能认证 Agent 自报，Lead 继续核对真实命令、输出和来源。
+
+## Incident
+
+记录非空 facts、unknowns、next_checks 字符串数组；`feedback_loop_ready: false` 与 `root_cause_confirmed: false` 必须明确。这是事件证据截面，不是根因结论。正式 diagnosis 的红灯、假设和状态仍由原诊断规则验证；未来获得红灯后保留原事件观察，转入正常 D 流程，不把旧观察改写成当时已确认。
+
+## 验证入口
+
+新分支分别执行现有校验器的 `--engineering performance`、`--engineering documentation` 或 `--stage diagnosis --engineering incident`，输入当前 change。可与原 `--repo` 和适用 `--stage` 结合。没有标记记录的历史工件继续按原规则验证；显式专业模式缺少记录会失败，已有标记记录在普通 change 校验中也会检查。
+
+代码块语法是 `json specdev-engineering-evidence`，不是新文件类型。校验器只读，无论成功、失败或不完整都不写状态、不创建缺失工件、不执行命令、不获取授权。源记录、结构校验、真实工具执行和宿主观察是不同证据，报告时分别说明。

package/template/workflows/specdev/common/rules/error-handling.md

@@ -0,0 +1,36 @@
+# 错误、状态保证与恢复
+
+在设计、实现或审查失败、重试、取消、后台任务和恢复时读取。此规则决定失败后的工程判断；既有授权、状态 owner 与远程操作协议仍分别拥有执行权，不在这里创建账本或更换恢复网关。
+
+## 先定义失败后仍成立的事实
+
+预期失败使用可区分的类型或稳定代码，保存必要原因和处理信息；不要解析展示文案来选择恢复分支。无法预期的缺陷可以作为异常报告，但不能被 catch 转成成功。对每个可能改变状态的操作，记录实际处理者、报告者、清理责任及失败后的保证：
+
+| 已知副作用 | 可以作出的判断 | 下一步 |
+|---|---|---|
+| 未开始或确认未发生 | 未产生本次效果 | 仍需核对授权、取消与重试条件 |
+| 已确认全部提交 | 效果已发生 | 回读结果，不能再次创建相同效果 |
+| 已确认部分发生 | 只有已核实部分可信 | 停止依赖完整结果的工作，按 owner 的补偿或继续协议处理 |
+| 结果未知 | 无法保证没发生或已成功 | 保留原操作标识，先对账；不能声称回滚或安全重试 |
+
+捕获异常不撤销已经发生的修改，记录日志不等于完成恢复。只有受影响状态的 owner 能证明后续操作的前置条件仍成立；否则停止依赖该状态的工作、弃用无效实例或升级处理。无关、独立且已授权工作仍可继续。
+
+## 重试、取消与无进展
+
+重试必须说明安全重复的依据、执行 owner、取消途径和预算。只读、可幂等重试和需要先确认副作用的操作分别处理；“发生了超时”本身不能证明可重复。持续监督需要可释放的生命周期和可见降级，不伪装为有限次数操作。
+
+同一输入、同一方法、同一失败且没有新证据时，不通过更换 Agent、清空 attempts 或重复问用户来制造进展。恢复既有 Goal/Ticket 时沿用原失败记录，由 Lead 说明新增证据或方法变化后再派发。远程对账与 marker 去重由 <Path>{roots.workflows}/specdev/T-triage/T-triage.md</Path> 路由到原远程协议；进入远程分支后再读取，不在普通错误审查中加载传输实现。
+
+取消只说明发出了取消请求，不保证远端副作用或子进程已经停止。传播 signal 后仍需等待属于本操作的完成信号；清理失败和业务失败分别报告，不能用后者隐藏前者。
+
+## 面向用户的结果
+
+最终说明必须指出受影响操作、已知影响、尚不确定的结果、系统当前处置和下一安全动作。失效状态持续存在时，提示也应持续可见；错误提示组件不能随已关闭的来源界面一起消失。保留有效数据，不为展示瞬时错误清空它。使用目标项目原有语言和诊断机制；敏感内部信息不进入公开文案。主要报告渠道失败时有独立的安全回退。
+
+S 把适用保证写成行为合同，T-tickets 指定验证，I 落实和记录，D 调查实际失败，C 追踪所有可达路径。验证应观察外部状态、文件、事件、退出或用户可见结果，不只断言异常被捕获。
+
+## 判断示例
+
+请求创建 PR 后超时，应先按稳定 marker 查询原目标；直接重发可能重复创建。读取无副作用的数据遇到临时网络错误，在预算、取消和环境允许时可以重试。这两个场景不能共享无条件 retry。
+
+方法参考：DeepSeek Harness 的错误处理标准，固定参考版本见 <Url>https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/.agents/skills/dsh-error-handling/SKILL.md</Url>；这里采用 SpecDev 原有 owner 和持久化，不导入其运行时实现。

package/template/workflows/specdev/common/rules/evidence-and-verification.md

@@ -53,3 +53,19 @@ Direct Spec Evidence 至少包含：用户批准与轻量合同、Lead、实施
 父实现 change 的 Implementation Orchestration Evidence 不能替代子 Evidence。它至少记录最终 Map revision、全部成员最终状态和子证据指针、dependency/serialization 实际顺序、跨 change 合同检查、aggregate 命令/环境/结果、stale candidate 处理、偏差和残余风险。任何成员未 completed 或整体验证未通过时不得形成父完成证据。
 
 Evidence 原文不出仓库。对 GitHub 的公共投影由 T-triage publish 按公共投影规则生成，不替代本文件的完整记录。
+
+## 6. 按改动选择检查与复用证据
+
+先固定当前真实 base/head、dirty 写集、配置和消费者，选择能在本次回归上失败的最窄检查；动态配置、Worker、子进程、发布构件或跨模块接口需显式选择真实入口。CI 负责目标项目规定的全量矩阵，本地不因 commit/push 机械重跑刚通过且仍有效的检查；原 required Gate 不因此降级。
+
+复用记录须给出原证据、代码/输入/配置/Skill 摘要、命令选择、环境和仍成立的原因。基线合入、head 改变、配置/依赖/生成器或被测输入变化时重估失效范围；不能把不相关改动当作所有证据永久无效，也不能沿用旧 head 的完成结论。readiness、skipped、pending、环境失败和未运行分别报告。
+
+异步、资源、CI 或测试删除使用 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path>；失败后的状态和安全继续使用 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path>。验证结果须关联真实退出、事件、文件或输出，不能只相信组件/Agent 自报。
+
+## 7. 特殊行为与文档证据
+
+纯文档使用可执行示例、链接、类型与生成一致性、源码语义核对；不适用代码 TDD/E2E时明确理由。prompt、工具定义、错误或 UI/CLI 字符串改变属于行为变化，检查真实模型/用户可见内容，不只检查 Markdown。UI 原型、mock、真实服务器演示分别标记；录制证据对应准确提交、环境、运行方式和片段，不能拼接不同运行冒充一次成功，也不强制无关任务录 GIF。
+
+性能测量必须有真实用户操作、可比较工作量/时钟/冷暖状态、原始样本与端到端结论；微基准改善不能代替整体收益。专业分支仅在原报告追加 <Path>{roots.workflows}/specdev/common/rules/engineering-evidence.md</Path>，结构通过不证明测量、翻译或工具执行真实。
+
+删除、合并测试的决定需记录旧行为/错误/兼容/回归到新用例的覆盖承接；无法证明就保留。新准入规则至少有一个从真实执行入口失败的反例，并在恢复基线后确认通过。

package/template/workflows/specdev/common/rules/test-reliability.md

@@ -0,0 +1,33 @@
+# 可重复的测试与有效反例
+
+新增、修改或调查异步、资源、时钟、并发、进程或 CI 易抖动测试时读取。检查选择和执行证据由 <Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path> 拥有；本规则只规定测试怎样可靠地观察目标行为。
+
+## 按真实拓扑设计隔离
+
+从实际测试配置与 CI 定义确认同文件用例、不同 worker、不同测试进程和共享主机的 job 是否可能重叠。进程隔离不隔离端口、可预测目录、数据库、外部服务和继承的子进程。
+
+每个资源都有获取者、原子分配动作、可观察就绪、立即登记的清理和清理完成信号。测试服务器绑定 loopback 的系统分配端口后再读取地址，不先扫描“空闲端口”；目录使用独立临时根，数据库/会话使用独立 namespace。稳定录制 ID 与临时地址在 fixture 内映射，不强迫真实资源复用固定地址。仅作解析输入的 URL 或路径不属于已获取资源。
+
+不得为了掩盖一个 fixture 的冲突把整个套件串行化。共享资源修复涉及跨进程隔离时，使用独立并发进程证明隔离，而不只把同一文件中的测试顺序执行。
+
+## 全局变量、时钟与平台
+
+优先注入依赖而不是修改进程全局状态。必须修改 env、cwd、timer、locale、模块 mock 或 fetch 拦截时，保存“缺失/存在及原值”，立即登记恢复，并在最小作用域用 finally 恢复；必要时增加失败兜底。拦截只覆盖本 fixture 的精确请求。
+
+平台拥有的语义从真实读回结果确认。不要假定时间戳精度、环境变量大小写、信号、权限或文件句柄关闭语义跨平台相同；确实不适用的场景明确跳过并说明原因，不削弱所有平台断言。超时预算依据真实 lane 与被等待操作，setup/teardown 一并考虑。用例预算应明显大于被测试的超时。
+
+## 同步与彻底清理
+
+等待 readiness、handshake、状态、promise 或外部可观察条件；sleep 只可作为已经完成状态的展示停留，不作为正确性的依据。竞态使用 barrier/deferred 明确制造重叠，不靠随机重复碰运气。
+
+清理要停止新工作、解除监听、恢复全局修改，并等待子进程 exit、server close、worker termination 或等价信号。仅调用 abort/close/kill 不代表清理完成。测试需能在断言失败后仍清理，并在存在晚到回调时验证它不能污染下一个测试。
+
+## 有效 red、负向对照与测试删除
+
+有效 red 必须来自目标行为断言。编译错误、没选中测试、fixture 初始化失败、探针未执行、timeout 杀死子进程都不是目标回归证据。强制变异先证明修改落在真实执行路径，观察预期断言失败，再还原并复跑基线。
+
+新增静态或工件准入规则，要从实际顶层 runner 投入故意无效输入并观察预期拒绝；只单测未接入的辅助函数不算落实。对于普通回归，在实际可行且安全时观察修复前失败。无法重现的部分明确未验证。
+
+删除旧测试前逐项核对它所保护的行为、错误、兼容和历史回归在新测试中的承接位置与有效证据。新的公共接口测试存在，不证明旧测试全部冗余；缺失承接则保留或补齐。不要用 sleep、宽断言、吞错、重试、归一化或跳过来制造绿色。真实外部服务允许的有界重试须由该测试政策明确批准，并报告重试与跳过。
+
+方法参考：<Url>https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/.agents/skills/dsh-ci-test-reliability/SKILL.md</Url>。使用目标项目的框架和真实 CI，不照搬 DSH 的工具、覆盖率或超时常量。

package/template/workflows/specdev/common/rules/workflow-routing.md

@@ -30,3 +30,16 @@
 开发环境/流程复盘 → <Path>{roots.workflows}/specdev/R-retro/R-retro.md</Path>。代码讲解仍为 L；Speculo 产品反馈仍为 retro command。CI/安全/PR/包发布 → <Path>{roots.workflows}/specdev/T-triage/T-triage.md</Path> 的对应模式；确定性修复回到 D/I，不由 T 接管代码。
 
 长任务在阶段边界按产物与待决问题选择继续、压缩上下文或 handoff；交接只携带准确 owner、SHA、输入和未闭合动作，不硬编码特定模型的上下文阈值，不自动启动其他会话。
+
+## 专业分支与相邻请求
+
+| 请求 | 入口/分支 | 不因此触发 |
+|---|---|---|
+| 测量哪个用户操作值得优化 | R-review-architecture / performance | 不直接实现，不先发明性能阈值 |
+| 已有性能故障需要确认根因 | D-diagnose-bugs | 不把微基准替代原始症状 |
+| 一次性事件暂时无法重现 | D / evidence-triage | 不标记 root-cause-confirmed，不创建 Ready 修复 |
+| 已批准的文档维护 | I-implement / documentation | 不新建文档 workflow，不伪造 TDD |
+| 只审查文档或某个 commit | C-code-review | 不写项目、不把单 commit 扩大到 HEAD |
+| 理解已实现 change | L-learn-change | 不改 Learning workflow，不永久晋升 |
+
+只读调查或审查不是后续修改授权。清晰的小请求继续走原适用阶段，不因增加专业分支强制进入 W/G/Triage；无差异、无候选和证据不足均可诚实返回，不制造工作量。

package/template/workflows/specdev/common/rules/workflow-state-and-lifecycle.md

@@ -92,3 +92,9 @@
 ## 扩展工件与兼容
 
 W 可写 `<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>`：它只拥有候选 change 边界与目标指针，不复制各 child 的状态。父 Goal 的 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 使用 goal-tickets-map 指针合同，权威仍是父 Implementation Map/Plan。旧 O restore key 不变；旧票继续可读，未完成旧票在新执行前由 Lead 显式补全调用绑定、交付约束并重新过门禁，不自动迁移、重置状态或改写他人事务。
+
+## 专业分支的原位恢复
+
+performance/documentation/evidence-triage 是原 Work 内的模式，不是新的 current_work 或 works_run 值。R 的记录留 architecture-review，I 留原 Evidence，D 留 diagnosis/diagnostics；格式见 <Path>{roots.workflows}/specdev/common/rules/engineering-evidence.md</Path>。普通旧工件不回填，归档和已完成历史不重写，config/status/change/Goal/Spec/Ticket 版本不变。
+
+恢复时先核对原 owner、Lead epoch、输入/Skill/代码 checkpoint 和未决动作。仅使受影响证据失效；不能把“结果未保存”解释为操作未发生，不能清空 attempts 或转移锁来恢复。执行、远程账本和 A 的网关继续由原 owner 管理；只阻塞受影响的依赖闭包。

package/template/workflows/specdev/common/skills/code-review/SKILL.md

@@ -13,7 +13,7 @@ metadata: {"speculo-legacy-name": "specdev-code-review"}
 
 - `fixed_point`：已解析的 commit SHA；
 - `head`：已解析的 HEAD/checkpoint SHA；
-- `diff_command`：固定为三点 diff；
+- `diff_command`：由调用方冻结的实际 argv；legacy 默认三点，显式 range/commit 使用已确认端点，不由 reviewer 换范围；
 - `commit_log`：固定点之后的 commit 列表；
 - `spec_sources`：零个或多个本地权威来源；
 - `standards_sources`：仓库编码标准来源；
@@ -22,7 +22,7 @@ metadata: {"speculo-legacy-name": "specdev-code-review"}
 
 ## 流程
 
-1. 重验 fixed point/head 可解析、三点 diff 非空，失败时不启动 reviewer。
+1. 重验 fixed point/head、实际 diff 语义和摘要；无效引用不启动 reviewer。合法空 diff 由调用方返回 no-diff，不伪造 approved 或复用非空报告。显式范围不得回退为默认三点比较。
 2. 加载 `<Path>{roots.workflows}/specdev/common/skills/code-review/references/source-discovery.md</Path>`，穷尽规范和标准来源。
 3. 发现已有审查并拟复用时，先读取 `<Path>{roots.workflows}/specdev/common/skills/code-review/references/result-reuse.md</Path>`，完整核对输入、两轴隔离与原始证据；能证明相同的轴保留原结果，其余轴按下列步骤运行；未能证明相同就正常重审两轴。
 4. 加载 `<Path>{roots.workflows}/specdev/common/skills/code-review/references/fowler-smells.md</Path>` 作为标准轴最低启发式；仓库明确标准优先。
@@ -51,3 +51,5 @@ Finding 必须包含 severity、项目相对 Path/代码块、具体风险、依
 - 两个 reviewer 上下文没有相互发现污染；
 - 每个发现可定位且说明行为风险；
 - 两轴按固定顺序返回，缺失规范没有掩盖标准审查。
+
+对适用风险先给出可证伪反例，再追踪消费者、实现、测试及恢复；测试覆盖率、配对哈希或 schema 成功不代替语义审查。错误和可靠性分别引用 <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/skills/code-review/references/result-reuse.md

@@ -4,7 +4,7 @@
 
 | 必须相同并可回读 | 核对证据 |
 |---|---|
-| fixed_point、head、三点 diff 与 commit 范围 | 本地不可变 SHA、diff 字节摘要 |
+| fixed_point、head、实际 diff 比较模式（legacy 默认三点）与 commit 范围 | 本地不可变 SHA、diff 字节摘要 |
 | 规范、标准、ADR 和适用项目指令 | 稳定来源路径、原始字节摘要与明确范围 |
 | review Skill 与当前触发的全部参考 | ID、入口/参考字节摘要、风险分支与跳过理由 |
 | 与结论相关的工具、测试环境、配置 | 实际版本/配置摘要与观察证据；未记录不能宣称相同 |

package/template/workflows/specdev/common/tools/README.md

@@ -4,7 +4,7 @@
 
 ```bash
 node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
-  --stage <triage|diagnosis|grill|spec|tickets|goal-plan|implement|learn-change|review|prototype|wayfinder|complete> \
+  --stage <triage|diagnosis|grill|spec|tickets|goal-plan|implement|learn-change|retro|pr-delivery|review|prototype|wayfinder|complete> \
   --repo <project-root> \
   <Path>{roots.state}/specdev/changes/{change}</Path>
 ```
@@ -28,7 +28,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
 ```
 
-工具只依赖 Speculo 已要求的 Node.js 运行时，不使用第三方包。返回码 `0` 表示没有阻塞性结构错误；warning 仍需人工判断。工具不替代项目测试、事实核验、设计审查或用户批准。
+工件结构校验只依赖 Speculo 已要求的 Node.js 运行时，不使用第三方包。真实 Git 检查、review-scope 和包 self-check 中的隔离回归另需 Git；self-check 会在系统临时目录创建并清理测试仓库，不修改用户项目或 workflow 状态。返回码 `0` 表示没有阻塞性结构错误；warning 仍需人工判断。工具不替代项目测试、事实核验、设计审查或用户批准。
 
 ## 从 tickets-map 分析下一轮
 
@@ -43,3 +43,13 @@ node <Path>{roots.workflows}/specdev/common/tools/ticket-control.mjs</Path> --ma
 只读工具不调用 Skill、不执行实现、不检查真实授权/正式记忆网关，不获取锁或自动解锁；Lead 必须在 dispatch 前完成这些检查。结构错误返回非零；局部错误仍可能带独立 frontier，调用方必须检查节点和全局 diagnostics。结构检查成功的退出码 0 不代表任务完成，且业务门禁可能仍阻塞全部票。eligible_for_final_verification 只表示可进入最终验收，不是 Goal completed。
 
 `<Path>{roots.workflows}/specdev/common/tools/plan-contract.mjs</Path>` 是两个工具共用的只读校验库：新 Ticket 的真实 Skill 名称/摘要、必需调用证据、Map 数量合同、父入口与 W 候选图。普通 --repo 仍支持原 Git 事实验证；存在未完成票的真实项目 Skill 绑定时必须提供项目根。旧票可读，开始新实现前必须显式补齐 Plan 合同；已完成历史证据不要求当前 Skill 包仍与历史版本相同。
+
+## 专业分支与审查固定点
+
+原 change 校验支持 `--engineering performance|documentation|incident`，要求对应原 owner 工件中的标记证据；不传时仍检查已经存在的标记。字段见 <Path>{roots.workflows}/specdev/common/rules/engineering-evidence.md</Path>。历史无标记工件不强制回填，所有路径只读。
+
+`--review-scope --repo <project-root> --mode baseline|range|commit|pr` 是独立只读模式，不选择 change、不加载状态、不访问网络。baseline/pr 使用唯一 merge-base；range 比较两个端点；commit 只比较指定提交与其父，不用当前 HEAD。前三种端点模式传 `--base` 与 `--head`；commit 传 `--commit`，多父提交还须 `--parent`。PR 必须传刚读取的完整 base/head SHA。根提交没有现有 CR 所需的 committed fixed point，明确拒绝，不编造父提交。
+
+输出包含固定 SHA、实际 diff argv、内容摘要、路径和 changes/no-diff；无差异退出 0，但不是审查 approved。无效引用、歧义 merge-base、缺参数、重复参数或外部工具失败返回非零。差异不执行外部 diff/textconv，受限输出不会泄漏全日志。
+
+包级 self-check 同时执行内置工程合同回归测试；测试用临时目录和真实 Git fixture，既验证合法输入，也从本顶层入口证明非法记录被拒绝。测试不调用远程、不接管状态、不认证真实模型遵从。