@namewta/speculo 1.0.24 → 2.0.1

package/template/workflows/specdev/specdev-a-archive-and-consolidate/references/design-knowledge-gateway.md

@@ -0,0 +1,61 @@
+# Project DESIGN write gateway
+
+本协议由 A 唯一拥有，只有两种调用：P 的首次基线 `bootstrap`，以及 A 归档时的 `promotion`。它不接管 ADR/context 网关，不启动 runner，不改变调用方原 owner，不修改业务代码或项目根用户 DESIGN。机械发布使用 <Path>{roots.workflows}/specdev/common/tools/publish-design.mjs</Path>；内容遵守 <Path>{roots.workflows}/specdev/common/schemas/project-design.schema.json</Path>。
+
+## 权威与批准
+
+- <Path>{roots.state}/specdev/design/DESIGN.md</Path> 是唯一当前项目设计规范。
+- <Path>{roots.state}/specdev/design/revisions/DESIGN-NNNN.md</Path> 是不可变历史快照；当前文档必须与所指 revision 逐字相同。已发布快照不得覆盖、删除或借清理重写。
+- <Path>{roots.state}/specdev/design/INDEX.md</Path> 是可重建检索投影，不决定当前版本；缺失或过时只需恢复索引，不重新发布规范。
+- <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path> 由 P 拥有，是该 change 唯一页面设计合同；固定引用项目 revision 与规范 digest。永久基线更新不静默改写活动 change。
+
+文件中的批准字段只是确认的可核验记录，不自行授予权限。调用方必须持有真实用户授权，记录具体目标、内容、范围和时间。字节 SHA-256 用于发布漂移与不可变快照检查；`designDigest` 用于规范内容确认，两者不能混用。
+
+## Bootstrap：HTML 和首次基线一起确认
+
+1. P 先只读探索项目代码与现有设计文档，按任务组合离线模板。首次基线候选留在 <Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/baseline-draft.md</Path>；尚未批准不创建永久 DESIGN。项目根已有用户 DESIGN 时保留原 owner、记录 locator/digest，将其作为现有约束；owner 未知或矛盾未解决只阻塞永久写入。Speculo 基线是其只读派生，重叠规则仍由用户根 DESIGN 约束，不建立矛盾的第二权威，不自动接管根文件。
+2. 向用户一次展示可运行 HTML、change DESIGN、首次基线内容和永久目标。批准范围必须同时包含预览与项目规范写入；只说“页面可以”而未展示永久变更，不是永久写入授权。沿用会话已取得的明确批准，不为同一未变确认包重复询问。
+3. 准备 `DESIGN-0001`，`supersedes: null`；所有规则为 `verification: approved-intent`。这表示已接受规范，不表示已实现。新项目不能伪造代码、生产验证或 implemented 证据。
+4. 调用发布工具 dry-run，确认候选、HTML 字节摘要、根路径和目标仍一致；P 同时核验整个原型的 CSS/JS/资源摘要及独立浏览器证据，批准后有变化则重开受影响确认。获得具体批准后 `--apply`。P 调用 A-owned 网关时保持 P 的实际归属与原证据，不创建虚假 completed change 或启动归档。此时基线尚未发布，不调用要求永久 snapshot 已存在的最终 approved DESIGN 门；发布成功后再完成该门。
+5. 工具原子无覆盖发布首次 current 文件，并返回 revision、字节摘要、规范 digest 与检查点。P 把回执记入原 change LOG/批准证据，回读 current/revision/索引后才完成基线写入。两个 change 同时首次初始化时仅一个发布成功；另一方重读已存在基线，重新合并并针对变化重新确认，不能覆盖胜出者。
+
+## Promotion：完成证据支持的规则提升
+
+1. 从已完成 change 的 DESIGN 按稳定规则 ID 选出跨 change 有用的 token、组件约束和交互模式；同一结论只生成一个候选，LOG/原型/Evidence 提供证据，不重复提取正文。一次性页面、未实施候选和实验仍随归档 change 保留。
+2. 对照已实现代码、测试和 Evidence 逐条评估，记录来源 change、稳定 locator 与字节摘要。`Outcome: completed` 只表示完成门，不能将所有规则自动标为 implemented；缺乏实质证据的规则仍为 approved-intent，或从候选中排除。
+3. 读取当前项目 DESIGN，生成下一连续 revision 和完整新规范，`supersedes` 指向当前 revision。展示规则级 create/merge/supersede/skip 及冲突，不把局部覆盖强推为项目通用约束；仍有效的原规则保持。
+4. 把预期 current 字节摘要、候选摘要、规则证据与新 revision 加入原归档计划，取得该具体 diff 的批准。发布在归档移动之前完成；移动后解析 source change 的最终 archive locator，重新核验来源；可使用稳定 change ID 与 change 内路径，使移动本身不伪造内容变化。
+5. 由原 A 网关调用发布工具。先发布不可变 revision，再替换 current，最后修复索引；每步实际结果写入原报告。索引错误不撤销已成功的规范发布，也不重复分配 revision。
+
+## 工具接口与回执
+
+```text
+node <Path>{roots.workflows}/specdev/common/tools/publish-design.mjs</Path> --repo <project-root> --method-root <method-root> --candidate <candidate.md> --state-root <resolved-specdev-state-root> --approval <approval.json> --mode bootstrap --expect-absent
+node <Path>{roots.workflows}/specdev/common/tools/publish-design.mjs</Path> --repo <project-root> --method-root <method-root> --candidate <candidate.md> --state-root <resolved-specdev-state-root> --approval <approval.json> --mode promotion --expected-current <sha256> --apply
+```
+
+默认 dry-run 不写文件；`--apply` 才发布。此工具 `--state-root` 表示 SpecDev 根（不是 WorkContext 的领域共同父根）；须等于归一后的 context.specdevRoot。已有安装验证 workspace 一致，无安装使用明确 repo/method/state 根，不把 cwd 或另一 worktree 当回退。候选和批准记录由调用方保存在其已拥有的 change 证据或既有报告资源中，工具不选择报告路径。JS 接口为 `publishDesign({repoRoot, methodRoot, stateRoot, candidatePath, approval, mode, expectedCurrent, apply})`（stateRoot 为该工具的 SpecDev 根）；`expectedCurrent: null` 表示预期不存在。
+
+批准记录：`approved: true`、真实用户决定的 `source`、ISO `confirmed_at`、`candidate_sha256`、`current_sha256`（首次为 null）及 新请求 `locator_version: 2` 与 `record: {base: "change", change, path, sha256}`。`record` 必须位于当前 change 或原归档 Command 报告 namespace；推荐 P 在包内保存不可变确认 Markdown，LOG 只引用它。确认正文包含 source、时间、候选摘要及预期 current 摘要（首次写 `absent`），不能用任意非空文档替代；追加日志不得使原确认快照无声漂移。
+
+bootstrap 还必须有 `preview: {base: "change", change, path, sha256, package_path, prototype_digest}`：`package_path` 指向同一 change 的 <Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>，`path` 必须是该包的 <Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/final/index.html</Path>；确认正文也包含这两个摘要。字节摘要绑定已展示 HTML，`prototype_digest` 绑定候选与完整 final/comparison 资源（含 CSS/JS）。发布器直接核验这些摘要，不调用依赖已发布基线的最终包门。
+
+项目根存在用户 DESIGN 时，候选 sources 的 locator 必须为项目根相对 <Path>DESIGN.md</Path>，并记录其完整字节 digest；批准对象增加 `project_design: {owner, disposition: "derived-readonly", sha256}`，确认正文同时包含 owner、disposition 与该摘要。owner 必须已解析，不能为 unknown。工具检查源摘要与声明，不判断语义矛盾；调用方必须先解决冲突并取得同一确认包的批准。用户根 DESIGN 漂移或失踪时停止写入。
+
+路径为项目相对路径或已解析安全 locator，不保存机器绝对路径。工具校验记录与实际文件一致，不声称它能认证真实人类批准、视觉质量或 Evidence 的语义真实性。完整工件合同由 SpecDev 验证入口检查；发布器共用稳定 change 身份、Outcome 与原 owner 读取。bootstrap 核对实际 P 归属和原会话依据；promotion 核对原完成 owner 与完成门，A 仅作为发布网关执行者，不以字符串自封 owner。
+
+stdout 返回检查点 `validated`、`revision-written`、`current-published`、`index-written` 和实际文件摘要；失败返回已完成检查点及恢复信息，调用方立即追加到原 LOG/Command 报告，不伪造整次原子成功。
+
+## 互斥、失败与恢复
+
+发布器在 design store 内使用短期 `.publish-lock` 文件，以原子排他创建序列化单次文件发布；它只保护这一个 store，不是新工作流或通用事务服务。锁记录原 owner、进程、批准来源和操作摘要。其他操作看到锁时停止；年龄不构成删除或接管授权。
+
+- 正常返回或可捕获失败：工具只释放自己创建的锁，已写 revision/current 不回滚覆盖；从回执核验实际状态再继续。
+- 进程中断遗留锁：只有原操作、原批准及 owner 相符，且原本机进程已结束，才能通过显式 `--resume` 恢复；未知主机或进程状态保持阻塞。恢复本身用短期 `.publish-resume` 排他保护，若该保护文件也因进程中断遗留，则保留证据并由原网关人工核验，不再自动接管。不得手工删除他人锁。
+- current 已等于候选且 revision 一致：重试只核验来源并修复 INDEX，不重新发布；current 被另一个 revision 更新则停止，重新准备 diff。
+- 只有 revision 已写而 current 尚未更新：必须确认原批准、expected current 和 snapshot 都一致，继续发布原候选；不得覆盖冲突的 snapshot 或跳过 revision。
+- 归档已移动：只可从归档目标和原报告恢复已经发布的同一知识操作；核对原批准、current/revision 与操作摘要后，修复缺失的 INDEX 或事实回执，不能再次移动。若知识尚未发布，停止该发布分支并保留证据，由原网关处理，不能从归档对象发起新发布。知识成功而报告保存失败：按 current/revision 摘要重建事实回执，不把“未保存结果”当成“操作没发生”。
+
+完整归档仍遵守 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/references/operation-contract.md</Path> 的 dry-run/confirmed、漂移和重读门。归档前检查 completed/cancelled 对应证据（promotion 仍只接受已完成来源）；归档后检查实际位置、目录完整性与知识发布回执，不在 archived 对象上运行只接受 completed 的阶段门。
+
+新 locator_version 2 的 record/preview 将稳定 change 名与对象内 path/package_path 绑定，移动前后使用同一 operation；source 同样优先稳定 change + 对象内 locator。旧 v1 project locator 只读解释，不改快照、批准、摘要或 ID；不能验证移动后仍可解析时保留原位置并阻塞迁移。

package/template/workflows/specdev/specdev-a-archive-and-consolidate/references/knowledge-graduation.md

@@ -0,0 +1,58 @@
+# Knowledge Graduation Criteria
+
+判定 change 中的知识是否值得提取到 workflow state root 声明的持久化 store。默认只提取满足标准的；其余归为 `ephemeral`，留在归档 change 中。
+
+## 毕业标准（三项满足任一即提取）
+
+1. **稳定机制**：知识描述的是持久架构模式、设计原则或系统约束，不是临时实现细节或过渡方案。
+   - ✅ "认证模块使用 JWT + refresh token 双令牌机制"
+   - ❌ "临时绕过了 rate limiter，等待 PR #342 合并后移除"
+
+2. **重复教训**：同一洞察在多个 change 中出现（>1 个 change 引用或触及）。
+   - ✅ 三个不同 change 都遇到"时区转换必须用 UTC 存储、展示层转换"的坑
+   - ❌ 仅在一个 change 的调试过程中发现，未被其他 change 证实
+
+3. **接手者必知**：缺少此知识会导致后续开发者做出错误决策或重复已解决的争论。
+   - ✅ "选择 PostgreSQL 而非 MongoDB 的原因：需要 ACID 事务和 JSONB 的混合查询能力"
+   - ❌ "lint 配置将 max-line-length 设为 120 而非 100"
+
+## 反毕业标准（满足任一项则不提取）
+
+- 仅适用于单次 change 的实现细节（具体行号、临时变量名、中间重构步骤）。
+- 已解决的临时变通方案（workaround 已被正式修复取代）。
+- 调试日志、故障排查过程记录（除非提炼出可复用的诊断方法）。
+- 脱离完整 change 上下文会产生误导的内容。
+- 纯个人偏好且无项目级约束力（"我习惯用 X"）。
+
+## 候选去重
+
+同一决定已由 <Path>{roots.state}/specdev/changes/{change}/ADR.md</Path> 充分捕获时，以该 ADR 作为唯一毕业候选，不再从 LOG、Evidence 或其他工件生成重复候选。这只消除重复，不跳过永久知识毕业评估；通过标准的 change ADR 仍应进入永久 `adr/` 合并计划。
+
+同一设计结论已由 change DESIGN.md 捕获时，以其稳定规则 ID 为唯一设计候选，LOG/原型/Evidence 只作为来源。只有证据明确支持的规则才可标为 implemented；页面批准与 completed 状态都不是生产实现证据。首次基线 bootstrap 是 A 设计网关规定的 approved-intent 例外，不放宽其他知识的毕业标准。
+
+## 决策流程
+
+对每段待评估知识：
+
+```
+1. 满足任一毕业标准？ → 否 → ephemeral（留在归档 change）
+2. 触发任一反毕业标准？ → 是 → ephemeral
+3. 提取 → 进入合并计划
+```
+
+## 知识分类与目标映射
+
+新 ADR/context 对象使用 `YYYY-MM-DD-topic[-NN]` 稳定名称；已有编号/历史名称原位保留，不批量重命名。目标目录须由领域声明。
+
+| 知识类型 | 判定特征 | 目标 store |
+|---------|---------|-----------|
+| **架构决策** | 对未来有持续决策价值，保留真实取舍与依据；不要求三项特征同时满足 | `<Path>{roots.state}/specdev/adr/{date}-{topic}[-NN].md</Path>` |
+| **领域术语** | 项目特有的概念定义，不是通用编程术语 | `context/` 目录（合并到术语文件） |
+| **项目设计规则** | 可跨 change 复用且通过证据评估的 tokens、组件与交互约束 | 仅已声明的 SpecDev `design/`，由 A 设计网关处理 |
+| **领域模型/规则/教训** | 实体关系、显式约束、踩坑经验 | 若 领域 Skill/manifest 声明了对应 store 则映射；否则归入 `adr/`（作为决策记录）或保留 ephemeral |
+
+> **注意**：目标 store 以 领域 Skill/manifest 持久化约定的实际声明为准。上表为默认映射。若 workflow 未声明某个 store，对应知识归入最接近的已声明 store 或保留 ephemeral。
+
+## Ephemeral 分类
+
+被判定为 `ephemeral` 的知识**不删除**。它随归档 change 保留在新 <Path>{roots.state}/specdev/changes/archive/{change}/</Path>；旧月份归档仍原位只读，供未来按需查阅。它不提升到 workflow 级持久化 store。

package/template/workflows/specdev/specdev-a-archive-and-consolidate/references/operation-contract.md

@@ -0,0 +1,48 @@
+# SpecDev 统一收尾操作合同
+
+A 单一拥有本合同；Command 只路由领域入口，不作为通用知识执行器。默认 dry-run 返回会话计划、零文件写入；confirmed 仅执行真实具体批准覆盖的动作。
+
+## 输入、范围与唯一回执
+
+输入是验证过的 WorkContext（projectRoot/methodRoot/stateRoot）、固定目标/主题清单、模式、批准来源和写集。未指定 change 时只读目录/README 候选消歧，不读旧全局索引决定新身份。独立知识审计/维护无需虚构 change。资料缺失或网关不明只阻塞依赖动作。归档没有候选返回 no-candidates；不创建访谈 change 或空回执。
+
+| 调用 | 唯一总回执 | 创建与冻结 |
+|---|---|---|
+| Command 调 A | <Path>{roots.state}/commands/archive-and-consolidate/{date}-{scope}-{topic}[-NN].md</Path> | Command 负责总报告，A 只返回逐项结果 |
+| 直接 A、有 change | <Path>{roots.state}/specdev/changes/{change}/archive-receipt.md</Path> | confirmed 后创建，随目录移至 <Path>{roots.state}/specdev/changes/archive/{change}/archive-receipt.md</Path> |
+| 直接 A、无 change | <Path>{roots.state}/specdev/maintenance/{date}-{topic}[-NN].md</Path> | 仅跨会话/跨对象/恢复需持久化时创建 |
+| dry-run/只读审计 | 会话结果 | 不创建文件 |
+
+新报告无覆盖创建；实际归档的导航、结果段和完整性清单按 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/references/archive-receipt-contract.md</Path>。恢复先核对原 owner、输入摘要、批准范围与已落地结果。原操作未结束时只补真实检查点，不能改原请求/验收/结论。所有检查完成并写完原回执才冻结；后续纠错写外部补充记录引用原件。DESIGN 用不可变批准快照绑定摘要，可变回执只引用它，不能因追加日志使批准失效。
+
+## 计划
+
+1. 归档按 <Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path> 验证 completed/cancelled 原证据、owner、实际 writer 和直接依赖；父子/远程门按实际存在读取。取消不是授权回滚或清理。独立维护只核对本主题事实与原 gateway。
+2. 按 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/references/archive-rules.md</Path> 预检身份、源/目标、链接/模式及来源移动后可解析。batch 全部固定候选预检通过才执行，不扩大到新发现对象。
+3. 对 change、ADR、context、当前 docs 四类逐项写结论，UI 再核对 DESIGN。按候选 ID/关键词定位相关知识与 provenance，不全库扫描。可选工件缺失说明后跳过；已知有关错误不得留到封存后。
+4. 每项计划列源/目标、动作、依据、内容 owner、执行 owner、批准、before-image/输入摘要、结果与恢复点。知识依 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/references/knowledge-graduation.md</Path>、<Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/references/consolidation-rules.md</Path>；清理候选依 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/references/cleanup-rules.md</Path>。没有晋升候选合法，不凑数量。
+5. 用 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/assets/archive-plan-template.md</Path> 承载计划和结果；有知识整合候选时再读 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/assets/consolidation-plan-template.md</Path>，有清理候选时再读 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/assets/cleanup-candidate-template.md</Path>。同一具体批准统一复用，新增副作用或漂移只重开受影响确认。
+
+mechanical-only 复用仍有效的四类核对回执，或明确仅移动授权；必须报告未授权维护与已知相关错误。它免除重复知识读取，不允许把未知写成无需维护；必需维护未完成时移动阻塞。
+
+## 执行顺序与检查点
+
+| 步骤 | 动作与通过条件 |
+|---|---|
+| A0 | 重验原对象/结束证据/owner/依赖/相关事务锁；不接管他人任务 |
+| A1 | 固定四类资产及适用 DESIGN 计划、源目标和候选范围 |
+| A2 | 核对授权、来源摘要、before-image 与实际写入者；保存可恢复原件 |
+| A3 | 执行获批现役 docs/ADR/context 维护，每项写后回读；docs 使用共享 current-facts-docs 方法 |
+| A4 | 必要 DESIGN 通过专用网关发布，记录 candidate、expected current、批准与三类摘要及真实工具检查点 |
+| A5 | 核验当前资产、链接和完整/部分替代承接，执行已批准清理，预检移动后 locator |
+| A6 | 最后整体无覆盖移动 change，重验源字节、目标空缺、同文件系统与单写入者/隔离 |
+| A7 | 原回执 Result=moved；从唯一目标以 archived 验证清单、字节、模式、链接、DESIGN 来源/批准/原型和实际消费者，源不存在；此时未封存 |
+| A8 | 完成原总报告/回执，Result=verified 且 archived --sealed 通过后宣布封存；否则 partial/blocked 并保留精确恢复点 |
+
+A3–A5 任一本次必需动作未完成则不移动。DESIGN 仅用 <Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/references/design-knowledge-gateway.md</Path>，不能通用 append/merge current 或 revision。research/非标准 store 仍归原声明，不从目录名取得权力。A/I 不写 docs-sync state/sidecar、不推进 commit 基线。
+
+## 中断与恢复
+
+普通收尾没有多文件整体原子性。已维护知识或设计发布成功而移动失败，保留已发布事实，按原回执继续；不得自动回滚规范。移动已发生则从目标恢复，只补原操作验证/回执，不再次移动。DESIGN 以 revision/current/INDEX 与原 operation 的真实状态续作，不跳号、覆盖或重复发布；锁按专用原 owner 协议处理，不按年龄清除。
+
+结果不明先检查真实系统，报告缺失不证明动作未发生。跨文件系统失败不降级复制删除；另迁移须独立授权与保真计划。恢复有冲突保留原件，停止重叠写集及依赖，独立已授权工作继续。只有本次获批范围的全部动作和检查有结论才 `verified`。

package/template/workflows/specdev/specdev-c-code-review/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: specdev-c-code-review
+description: "按用户指定文件或 PR、单 commit、区间、基线冻结真实审查范围，执行隔离的标准轴与规范轴审查；有效空差异诚实返回，不实施修复或发布。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/code-review
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# 代码审查
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path>`，再执行本入口。
+
+C 是独立 review 入口，不实施修复。无 change 的明确范围审查可直接返回会话 findings，不创建状态或虚假对象；已有 change 或明确要求保存时才使用相应获批报告路径。它拥有 `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`；I 的最终审查由 I 写入 Evidence，不写本目录。
+
+激活时读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`，按当前步骤定位输入和证据。
+
+## 输入
+
+- 用户明确的本地文件范围，或 commit、branch、tag、merge-base、PR locator；只有比较历史差异的分支才需要 Git 固定点。
+- 可选 source、Spec、Ticket、ADR 和 Goal Plan；UI 范围必须定位已批准 change DESIGN、基线、design_ref 与原型/实现证据。
+- 当前仓库代码、commit log 和编码标准。
+
+## 流程
+
+用户明确要求本地文件只读审查时，先按 <Path>{roots.workflows}/specdev/specdev-c-code-review/references/source-files-review.md</Path> 固定文件快照并调用公共审查 Skill；直接返回会话结果，不运行下面的 Git diff/CR stage。缺少 Git 不成为无关初始化理由。未指定文件或比较范围时才澄清范围；不能把 PR/diff 请求降级成文件阅读。
+
+UI diff 按 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path> 核对批准版本、页面/状态和 `Design Conformance`。标准轴检查可访问性与运行缺陷，规范轴检查设计一致性；未验证渲染不报告视觉已通过，不通过修改设计文件消除 finding。
+
+1. **解析固定点**：先选择 baseline（共同祖先到 head）、range（两个指定端点）、commit（指定提交与其父）或 pr（远程 PR diff）。PR 先通过 <Path>{roots.workflows}/specdev/specdev-t-triage/references/remote-operations.md</Path> 的 pr-read 获得完整 base/head SHA。调用 <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> 的 `--review-scope --repo <project-root> --mode <mode>`；端点模式传 --base/--head，commit 传 --commit，多父提交明确 --parent。此只读工具冻结本地对象，不抓取、不写状态；根提交没有现有 CR 的 committed baseline 时明确报告限制，不编造父提交。
+2. **冻结输入**：保存工具返回的实际 diff argv、fixed_point/head、diff_sha256、路径与 commit log，不把单 commit 扩大到当前 HEAD。引用无效则失败；有效空 diff 返回 no-diff，不启动 reviewer、不造 CR、不声称 approved；正常结束本次 Work 并报告固定输入，change 完成仍按原终点规则判断。有差异才继续。
+3. **发现来源**：调用 `<Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`；规范来源缺失时经确认跳过规范轴，标准轴继续。
+4. **隔离审查**：仅按公共 Skill 的完整输入复用门接受既有结果；需要执行的轴在平台支持时并行 reviewer，否则用两个独立完整输入包顺序执行。两轴不得读取对方 finding。
+5. **持久化（有 change 时）**：选择下一个未占用 `CR-###`，使用 `<Path>{roots.workflows}/specdev/specdev-c-code-review/assets/code-review-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/reviews/CR-###.md</Path>`，原子重读。
+6. **验证与路由**：无 change 时核对实际报告与固定范围直接返回；有 change 时使用 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage review` 校验当前 change。无阻塞 finding 时返回完成或 I；局部修复生成/修订 Ticket；规范冲突返回 S/G；无法确定的 blocker 保持 C 可恢复状态。
+
+## 完成标准
+
+- 有差异分支的 fixed point/head 是本地不可变 SHA，diff 语义与用户选择一致；no-diff 独立返回，不运行要求 CR 的 review stage；
+- 规范和标准来源发现顺序有记录；
+- 两轴隔离、固定顺序、未合并排名；
+- 每个 finding 有路径、风险、依据和满足条件；
+- 报告、状态、验证结果和下一 Work 路径一致；
+- C 未修改项目代码或远程状态。
+
+审查接口双方、生命周期、取消/重试、资源释放、真实执行入口与可绕过路径；项目文档和模型可见内容变化分别按 <Path>{roots.workflows}/specdev/common/rules/documentation-standard.md</Path> 与 <Path>{roots.workflows}/specdev/common/rules/agent-experience.md</Path> 核对。base/head、配置或规范输入变化后重新评估受影响结论，不沿用旧 head 的通过。
+
+## 编排与执行上下文
+
+Lead 自行执行或当前阶段需要交接任务时，读取 <Path>{roots.references}/coordination/coordination-contract.md</Path>，按用户指定的 Lead、Orca、Herdr 或无头 CLI 方式操作。只读取所选工具的当前指南；不固定编程工具或模型。
+
+`lead` 上下文维护原业务状态和 Evidence；`task` 上下文只处理 Lead 指定目标和阶段，执行同一方法并返回候选、findings、检查和未验证项，不修改正式 Ticket、Map、Goal、Evidence，不递归启动 Goal 或交接其他任务。未曝光到宿主列表不影响读取真实入口。
+
+P 在已授权 run/resume 中完成当前实现、审查、验证和同范围修复后继续下一 Ready 任务，不逐票询问“继续”。只读分析或 plan 不执行。独立审查 required 时不能以 Lead 自审替代。

package/template/workflows/specdev/specdev-c-code-review/assets/code-review-template.md

@@ -0,0 +1,53 @@
+---
+schema_version: 1
+artifact: code-review
+change: <YYYY-MM-DD-topic>
+review_id: CR-001
+fixed_point: <sha>
+head: <sha>
+status: request-changes
+standards_result: request-changes
+specification_result: skipped
+spec_sources: []
+standards_sources: []
+created_at: <ISO-8601>
+---
+
+# Code Review CR-001
+
+## Fixed Input
+
+- **Comparison mode:** baseline / range / commit / pr
+- **Diff:** 实际冻结的 argv；legacy 未声明模式时才采用 `git diff <fixed_point>...<head>`
+- **Diff digest:** 实际 diff 字节的 SHA-256
+- **Original base/head:** 原始不可变引用；fixed_point 为实际比较起点
+- **Commits:** `git log <fixed_point>..<head> --oneline`
+- **Scope:**
+
+## 标准
+
+| Severity | Path / block | Finding | Authority | Satisfied when |
+|---|---|---|---|---|
+
+## 规范
+
+| Severity | Requirement | Finding | Source | Satisfied when |
+|---|---|---|---|---|
+
+规范不存在时写 `skipped:no-spec`，不伪造通过。
+
+## Summary
+
+- **Standards findings:**
+- **Specification findings:**
+- **Most severe standards finding:** none / ...
+- **Most severe specification finding:** none / ...
+- **Next Work:** completed / `<Path>{roots.workflows}/specdev/specdev-t-tickets/SKILL.md</Path>` / `<Path>{roots.workflows}/specdev/specdev-s-spec/SKILL.md</Path>`
+
+## 审查证据复用（仅实际发生时填写）
+
+记录原 CR/Evidence locator、fixed/head/diff、规范/标准/指令与 Skill/reference 摘要、工具/环境相关证据、两轴隔离核对、复用或重跑的轴与原因。未发生时写“不适用”；本节不是通过声明，也不改变原始审查结果。
+
+## 比较语义与证据有效期
+
+记录 baseline/range/commit/pr、实际 diff argv/digest、原 base/head 与 fixed point、消费者和相关配置/规范版本。合法 no-diff 不创建本 CR；非法引用和根提交无 committed baseline 明确报告。head 或相关输入变更后，核对受影响审查与验证，不沿用旧通过。

package/template/workflows/specdev/specdev-c-code-review/references/source-files-review.md

@@ -0,0 +1,14 @@
+# 本地文件只读审查
+
+仅用于明确指定文件的只读请求，不替代用户要求的 PR、commit、range 或 baseline 比较，也不冒充 I 的最终 diff 审查。
+
+1. 用下列只读调用固定 projectRoot、用户指定路径和实际原始字节摘要，多个文件重复 `--file`。它不调用 Git、不创建状态，拒绝空范围、重复文件/别名、非文件及越界路径；内部符号链接保留所选路径和实际目标。读取必要直接调用方、测试与适用标准，并把扩展范围及理由列入输入。若文件在审查中变化，重验受影响结论，不沿用原快照结果。无 Git 时如实说明没有 commit/log，不能借外层仓库或伪造 SHA。
+2. 将 `review_mode: source-files`、`source_snapshot`（项目相对路径及 SHA256）、规范/标准来源、review_context 和实际可用隔离方式交给 <Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>。来源发现将 commit 引用步骤记为 not-applicable；其余来源与两轴隔离要求照常。
+3. 规范缺失只阻塞依赖规范的判断，标准轴独立进行；按原规则确认规范缺失后才标记 skipped:no-spec。工具或独立 reviewer 缺失如实报告，不用一次自审宣称两个隔离轴已完成。
+4. 返回固定文件/摘要、两轴结果、实际验证、限制和下一步。会话结果不创建 change、CR、配置或状态文件，不改源文件、永久知识或远程系统。若后来要求正式 diff 审查，转回 C 的真实固定点分支。
+
+本分支的文件摘要只证明输入未变，不证明语义审查质量、用户授权或整个 change 完成。
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --review-scope --repo <project-root> --mode source-files --file <project-relative-file>
+```

package/template/workflows/specdev/specdev-d-diagnose-bugs/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: specdev-d-diagnose-bugs
+description: "调查故障并建立精确症状的红灯回路，以单变量实验确认根因；无法安全复现时仅收集事件证据，不将解释冒充根因，也不实施生产修复。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/diagnose-bugs
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# 诊断 Bug
+
+> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path>`，再执行本入口。
+
+D 的主导词是**红灯**：没有一条已执行且能在此 bug 上变红的紧凑命令，就没有可进入的假设阶段。D 默认只读项目代码，可以创建 change 诊断工件和经授权的临时可撤销探针；生产修复由 Implement 拥有。
+
+激活时读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`，按当前步骤定位输入和证据。
+
+## 输入与所有权
+
+按存在情况读取：
+
+- `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- 相关代码、测试、配置、日志和运行环境事实。
+
+D 拥有：
+
+- `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/diagnostics/</Path>`，仅在需要脚本、捕获物或临时探针结果时延迟创建。
+
+## 流程
+
+### 1. 建立并执行红灯反馈回路
+
+加载 `<Path>{roots.workflows}/specdev/specdev-d-diagnose-bugs/references/feedback-loop.md</Path>`。按其顺序尝试测试、HTTP/CLI、浏览器、追踪回放、夹具、模糊循环、bisect、差分和最终 HITL。保存命令、至少一次真实输出、精确症状断言、运行时间、确定性或复现率，以及 Agent 可运行性。
+
+无法建立回路时使用诊断模板写 `status: blocked`、`feedback_loop_ready: false`、已尝试方式和所需输入；假设表保持为空，在原诊断材料保留接续点。不得继续阅读代码来构造根因理论并据此宣称已确认；可以进入下述事件证据分支收集观察与下一安全检查，但不能直接进入正式假设实验或 Ready 修复。
+
+**完成标准**：一条已运行命令快速、可重复、由 Agent 执行，并能在用户精确症状上变红。
+
+### 2. 复现并最小化
+
+运行回路确认捕获的是用户报告的故障。逐个删除输入、调用者、配置、数据和步骤，每次删除后重跑；只保留对红灯有负载作用的元素。非确定性 bug 通过并行、压力、固定时间/随机或缩小窗口提高到可调试复现率。
+
+**完成标准**：剩余每个元素被移除都会使回路变绿，最小复现和最后红灯证据已持久化。
+
+### 3. 假设与单变量探针
+
+只有前两步完成后才加载 `<Path>{roots.workflows}/specdev/specdev-d-diagnose-bugs/references/hypothesis-and-instrumentation.md</Path>`。生成 3–5 个带预测的可证伪假设，先展示排名；用户 AFK 时保存 checkpoint 后继续。每个探针只检验一个预测，优先 debugger/REPL，其次定向日志；性能问题使用测量和分析器。
+
+**完成标准**：根因由区分性实验确认，其他高排名候选有反证，所有临时探针有唯一清理标记。
+
+### 4. 写入修复契约
+
+使用 `<Path>{roots.workflows}/specdev/specdev-d-diagnose-bugs/assets/diagnosis-template.md</Path>` 写入 diagnosis：触发条件、失败机制、影响范围、漏检原因、必须改变、必须保持、正确 seam、回归测试、非目标、风险和回滚。
+
+存在正确 seam 时，把最小复现定义为 I 必须先观察红灯的回归测试合同；不存在正确 seam 时明确记录架构缺口并路由 R。D 不编写生产修复。
+
+### 5. 清理、验证与路由
+
+重跑原始未最小化回路，确认当前诊断结论可解释症状；搜索唯一 `[DEBUG-...]` 前缀并删除临时插桩，无法删除项登记 owner 与删除条件。运行：
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
+  --stage diagnosis \
+  <Path>{roots.state}/specdev/changes/{change}</Path>
+```
+
+根因确认且证据通过后回读诊断结论，返回 diagnosis 和下一 Work：局部修复进入 Tickets/I，公共行为或高风险进入 S/Tickets，缺 seam 进入 R，仍无根因则保持 blocked 或进入 W。
+
+## 一次性事件与 CI flake
+
+故障不可再次触发或缺安全复现条件时，读取 <Path>{roots.workflows}/specdev/specdev-d-diagnose-bugs/references/incident-evidence.md</Path> 进入 evidence-triage。保持原 D ID、diagnosis/diagnostics 和合法状态；事实收集不等于根因确认，未知解释不写入已确认字段。
+
+涉及并发、时钟、子进程或 CI 易抖动测试时，再读 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path>；核对实际 worker/job 拓扑与资源释放，以显式同步制造竞态，不用无证据的 sleep、宽 timeout、全套串行或重试当根因修复。
+
+## 脱敏与强制变异证据
+
+在日志、报告和重现材料中移除 token、Cookie、认证头、秘密配置、个人数据及机器绝对路径；保留项目相对定位和必要错误形态。原始敏感数据不进入长期工件。
+
+如果使用强制变异检验测试敏感性，先记录未变异文件的 hash/diff，实际修改目标后读取 git diff 与运行路径，证明变异已落到执行文件。只有测试因预期行为断言失败才算有效 red；编译错误、未选中测试、变异未落地均为无效证据。恢复原内容，复跑基线并核对 diff。D 输出诊断及修复不变量，正式修复仍交 I。

package/template/workflows/specdev/specdev-d-diagnose-bugs/references/feedback-loop.md

@@ -0,0 +1,43 @@
+# 红灯反馈回路
+
+本文件只负责阶段 1–2。回路尚未满足完成门时，不加载假设或修复材料。
+
+## 构建顺序
+
+按大致顺序穷尽适用方式：
+
+1. 能触及 bug 的失败测试；
+2. 针对开发服务器的 curl/HTTP 脚本；
+3. 固定输入的 CLI 调用和已知良好输出 diff；
+4. 对 DOM、控制台或网络断言的无头浏览器脚本；
+5. 回放真实请求、负载、事件或追踪捕获物；
+6. 启动最小系统子集的一次性夹具；
+7. 属性或模糊测试循环；
+8. 可供 `git bisect run` 使用的状态检查夹具；
+9. 旧/新版本或配置的差分循环；
+10. 最后手段：复制并定制 `<Path>{roots.workflows}/specdev/specdev-d-diagnose-bugs/scripts/hitl-loop.template.sh</Path>`。
+
+## 收紧
+
+把回路当作需要优化的产品：缩小启动范围和测试目标；断言精确症状而非“没有崩溃”；固定时间、随机、文件系统与网络。记录一次运行耗时和复现率。
+
+非确定性问题先用 barrier、deferred、可控时钟或独立并发进程建立可观察重叠，再用压力运行补充复现率。定时等待只界定观测预算，不作为断言正确或根因修复的依据；不得以注入 sleep 掩盖缺少同步。
+
+## 最小化
+
+看见正确红灯后，逐项删除输入、调用者、配置、数据和步骤，每次只删除一项并重跑。删除后仍红则永久移除；变绿则恢复。完成时剩余每一项都承载故障。
+
+## 无法建立回路
+
+停止并列出尝试过的方式，请求以下之一：可复现环境、HAR/日志/core dump/带时间戳录屏等捕获物，或临时生产插桩授权。没有红灯不得进入假设。
+
+## 完成门
+
+- 命令已至少运行一次并保存调用与输出；
+- 驱动真实 bug 路径并断言用户精确症状；
+- 结果确定，或有稳定且足够高的复现率；
+- 秒级或已证明是当前最短可行回路；
+- Agent 可无人值守运行，或由结构化 HITL 脚本捕获结果；
+- 最小复现的每个剩余元素都有负载作用。
+
+无法复现时可按 <Path>{roots.workflows}/specdev/specdev-d-diagnose-bugs/references/incident-evidence.md</Path> 收集事件事实与下一安全检查；正式假设表和已确认根因保持未就绪。

package/template/workflows/specdev/specdev-d-diagnose-bugs/references/incident-evidence.md

@@ -0,0 +1,21 @@
+# 事件证据调查
+
+当故障只发生过一次、暂时无法复现，或缺少安全的运行环境时读取。此分支允许收集事实，不放宽已确认根因的红灯标准。当前 Work 仍为 `specdev/diagnose-bugs`；原 diagnosis 与 diagnostics 承载结果，不新建事故状态或永久知识。
+
+## 可执行的调查
+
+1. 固定事件、时间区间、受影响对象、版本和读权限。按来源定位脱敏日志、trace、变更、配置和相关源码路径，不全面导出生产数据。
+2. 分开写直接观察、来源之间的矛盾、尚缺证据和待验证解释。只读源码可以帮助确定下一步观测点，但解释不进入“已确认根因”或正式假设实验结果。
+3. 按信息增益和风险排列下一安全检查。生产插桩、重放有副作用请求、真实数据修改或对外调用需要原动作明确授权；缺少授权不代表可以换一个入口执行。
+4. 事件材料仍写入 diagnosis 的现象部分与附加事件证据节。`feedback_loop_ready` 保持 false，`red_command/red_evidence` 不伪造，正式假设表保持为空，状态为 reproducing 或 blocked；已确认根因和修复契约明确“尚未确认”。
+5. 写入 <Path>{roots.workflows}/specdev/common/rules/engineering-evidence.md</Path> 规定的 kind=incident 记录，运行 `--stage diagnosis --engineering incident`。校验通过只证明记录满足条件，不表示 bug 已解决或可以 Ready 实施。
+
+## 转入正常诊断
+
+获得一条确实命中精确症状的已运行红灯回路后，再按 <Path>{roots.workflows}/specdev/specdev-d-diagnose-bugs/references/feedback-loop.md</Path> 最小化并进入正式假设/探针。编译失败、未选中测试或基础设施失败不是红灯；临时 probe 要证明落在真实路径并恢复。
+
+反馈回路与确认实验齐全前，不设置 root-cause-confirmed，不移交声称已确认的 Ready 修复。收集完事件材料不把 D 记成根因诊断成功；在原报告保留缺失证据、owner 和恢复入口。用户选择终止调查时按原取消/交接协议处理，不伪造已完成诊断或重新打开归档来源。
+
+## 示例
+
+部署后出现一次重复扣款：可以检查脱敏请求 ID、时间、部署 diff 和幂等实现，提出“先核对支付方回执”的安全检查；不能在真实支付端重放以求红灯，也不能仅凭某个可疑分支宣称它就是根因。重复端口错误的 CI 则先核对 worker/job 拓扑和资源分配，使用 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path> 建立确定性观察，不用扩大 sleep 代替原因。

package/template/workflows/specdev/specdev-g-grill-with-docs/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: specdev-g-grill-with-docs
+description: "一个已界定 change 仍有产品、领域或架构决定待确认时进行可恢复访谈；跨 change 边界未清晰时先用 W。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/grill-with-docs
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# Change 决策访谈
+
+> 激活后读取 `<Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path>`。
+
+## 读取范围
+
+读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`；定位当前 change 的 `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`、`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 和相关 initiative 决策。先找到相关条目再回读必要原文，不默认整读永久 ADR 或索引。
+
+## 按风险选择问题
+
+涉及失败、重试、取消或恢复时读取 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path>：谁拥有状态，何时算成功，超时后副作用是否未知，谁核实结果，什么可以重复，哪些依赖应停止？涉及工具/prompt/context 时再读取 <Path>{roots.workflows}/specdev/common/rules/agent-experience.md</Path>。问题由当前 change 风险触发，不固定全问；仓库能查明的事实先查，高影响取舍才询问用户。
+
+局部 ADR 保留真实问题、采纳决定、考虑过的替代方案、代价、适用范围和验证义务。未确认方案留 LOG/设计树，不编造备选，也不把已采纳但未实现的决定写成已交付。
+
+## 当前 change 的访谈与共识
+
+进入访谈必须读取 `<Path>{roots.workflows}/specdev/specdev-g-grill-with-docs/references/interview-procedure.md</Path>`，由该过程在出现设计取舍、术语变化、日志写入或外部 stakeholder 缺口时分别读取 grilling、领域建模、日志格式或 questionnaire；不默认加载所有参考。保留完整 frontier、推荐答案和逐轮共识检查，但不替用户回答高影响取舍。
+
+- 先查仓库可发现事实，只询问会改变行为、架构、风险、范围、迁移或验收的决定。
+- W 的每个 materialized change 在自己的目录拥有设计树和文档；共享答案以来源指针引用，不能共用一棵可写设计树。
+- 当前 change 的 LOG/CONTEXT/ADR 可按 Work 授权写入；永久 namespace 对 G 只读，正式知识只能经 A 的原有写入网关提升。
+- 没有未决的高影响决定且证据可定位才标记共识；无法回答时只暂停相关分支，返回明确问题和恢复入口。
+
+完成后使用 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage grill`，回读实际形成的决定与证据工件；无实际内容不为四份数量预建空文件，再交给 `<Path>{roots.workflows}/specdev/specdev-s-spec/SKILL.md</Path>`；若属于 W 调查票，只关闭本票并返回探索地图。