@namewta/speculo 0.3.0 → 0.3.2

package/template/workflows/specdev/G-grill-with-docs/log-format.md

@@ -1,100 +1,18 @@
-# LOG.md 格式
-
-设计决策日志存放在变更目录的 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 中。它记录设计访谈中已经确认、延后或被替代的具体结论——"当时讨论了什么、最终固定了什么行为以及对应哪个 ADR"。与 CONTEXT.md 的精炼不同，LOG.md 可以记录讨论中的具体场景、边界条件和交互细节。
-
-## 规则
-
-- **记录每一次设计结论。** 无论大小，只要在访谈中确认、延后或被替代，都写入 LOG.md。宁可多记，不要遗漏。
-- **状态驱动。** 每个条目明确标记 `accepted`、`deferred` 或 `superseded`，让读者一眼知道当前有效性。
-- **关联 ADR。** 如果该结论同时满足 ADR 的三个条件，在 LOG 中标注 `Related: ADR-XXXX`，并在对应 ADR 条目中也关联回 LOG。
-- **保持可修订。** 后续决定改变既有结论时，直接更新原条目状态和正文，不要新建一条矛盾的条目。标注 `Superseded by: LOG-XXXX`。
-- **不堆积废弃条目。** 被替代的条目保留但标记清楚；延后（deferred）的条目保留以便后续恢复讨论。
-- **记录具体交互和边界。** 与 CONTEXT.md 的精炼不同，LOG.md 可以记录讨论中的具体场景、边界条件和交互细节。
-
-## 模板
-
-```md
-# 设计决策日志
-
-本文件记录设计访谈中已经确认、延后或被替代的具体结论。它保存"当时讨论了什么、最终固定了什么行为以及对应哪个 ADR"；CONTEXT.md 是规范词汇表，ADR.md 是难以逆转的架构决策，本文件则是可持续增删改的完整设计轨迹。
-
-## 维护规则
-
-- 每次完成一个设计问答，同步更新 LOG.md、CONTEXT.md 与 ADR.md。
-- 已确认结论使用 `accepted`；暂不决定使用 `deferred`；被后续决定替代使用 `superseded`。
-- 后续确认改变既有结论时，直接修订原日志条目，并记录替代关系，不保留互相矛盾的"现行规则"。
-- 日志可以记录具体交互和边界；词汇表保持精炼；ADR 只记录难以逆转、令人意外且存在真实权衡的决定。
-
-## LOG-0001: {状态} — {问题/主题}
-
-Status: accepted
-Related: ADR-0001
-
-{背景：讨论了什么问题，做出了什么决定，以及为什么。可以记录具体的交互过程、边界场景和固定行为。}
-
-## LOG-0002: {状态} — {另一问题/主题}
-
-Status: deferred
-
-{为什么暂不决定，以及后续恢复讨论时应从什么问题开始。}
-
-## LOG-0003: {状态} — {被替代的问题/主题}
-
-Status: superseded
-Superseded by: LOG-0004
-
-{原决策内容，以及为什么被替代。保留作为设计演进的历史上下文。}
+# LOG 格式
+
+```markdown
+## LOG-### — <时间> — <主题>
+- **状态：** confirmed / deferred / rejected / superseded
+- **问题：** 本条只记录一个决策或未知
+- **事实与来源：** 代码、测试、用户确认或外部规范
+- **选项：** 实质可行方案及关键差异
+- **推荐：** 默认建议与理由
+- **结论：**
+- **原因：**
+- **影响工件：** CONTEXT / ADR / Spec / Ticket / Goal Plan
+- **约束或不变量：** 无 / ...
+- **后续：** owner、触发条件或截止门禁
+- **替代/被替代：** LOG-### / 无
 ```
 
-## 状态说明
-
-- **Status: accepted**——已确认的现行结论。这是讨论后用户明确同意的决定，当前仍然有效。
-- **Status: deferred**——暂不决定，留待后续讨论。记录为什么暂不决定以及从什么角度恢复讨论，以便后续接续上下文。
-- **Status: superseded**——被后续决定替代。标注 `Superseded by: LOG-XXXX` 指向替代条目。保留原条目作为设计演进的历史上下文。
-
-## 追加新日志
-
-1. 读取 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`，找到最高现有编号
-2. 编号加 1（从 `0001` 开始，不足四位补零）
-3. 标题格式为 `## LOG-XXXX: {状态} — {问题/主题}`，必须能独立看出该条目回答了什么设计问题
-4. 在文件末尾追加新条目
-
-## 修改已有日志
-
-- **改变结论**——将原条目状态改为 `superseded`，标注 `Superseded by: LOG-XXXX`，在新条目中说明替代原因。不要直接修改原条目的结论内容——保留它让读者能看到设计是如何演进的。
-- **延后决定被重新讨论**——将状态从 `deferred` 改为 `accepted`，或新建条目替代原条目（原条目改为 `superseded`）。如果内容没有变化只是状态升级，可以直接改状态；如果结论发生了变化，使用替代模式。
-- **补充细节**——直接编辑条目正文，不改变状态。可以追加更多场景、边界条件或交互细节。
-- **关联 ADR**——如果后来为该日志创建了 ADR，补充 `Related: ADR-XXXX` 标注。
-- **不要删除**——即使结论被替代，保留条目作为设计演进的历史上下文。
-
-## 示例：被替代的日志
-
-以下示例展示一条日志从 accepted 变为 superseded 的全过程：
-
-原始条目：
-
-```md
-## LOG-0005: accepted — 订单状态机使用三态模型
-
-Status: accepted
-
-订单状态为 pending → confirmed → completed 的三态模型。
-```
-
-讨论后发现需要更细粒度，追加替代条目：
-
-```md
-## LOG-0005: superseded — 订单状态机使用三态模型
-
-Status: superseded
-Superseded by: LOG-0007
-
-订单状态为 pending → confirmed → completed 的三态模型。后续讨论发现 confirmed 状态无法区分"已付款待发货"和"已发货待签收"，因此改为五态模型。
-
-## LOG-0007: accepted — 订单状态机使用五态模型
-
-Status: accepted
-
-订单状态为 pending → paid → shipped → delivered → completed 的五态模型。
-详见 LOG-0005 的讨论背景。
-```
+LOG 追加为主；结论变化时新增条目并引用旧编号，不删除历史。状态为 deferred 的条目必须说明它是否阻止 Spec 或 Ticket Ready。

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

@@ -3,88 +3,204 @@ id: specdev/implement
 type: workflow-entry
 workflow: specdev
 name: 实现
-description: 基于 spec 或 tickets 实现工作——以深层模块设计原则指导架构、以 TDD 红绿循环驱动编码、以双轴审查把关质量。
-keywords: [实现, TDD, 代码审查, 模块设计, 重构]
+description: 基于 Ready Ticket 或获批的小型 Spec 执行设计检查、TDD 红绿循环、持续验证、双轴审查、证据回写和提交。
+keywords: [实现, TDD, 代码审查, 模块设计, 证据, ticket]
 ---
 
 # 实现
 
-基于 spec 或 tickets 实现工作——融合设计检查、TDD、审查、提交的完整实现流程。每一步引用内部子文件，不依赖外部 skill。
+本 work 保留原有完整实现能力：深层模块设计检查、接缝和依赖分类、design-it-twice、TDD 红→绿垂直循环、标准轴与规范轴审查、项目级验证、提交和状态更新。治理升级增加 Ready、路径所有权、Evidence 和偏差门禁，但不把实现退化为机械照单执行。
 
-在开始实现之前，读取变更的上下文与架构决策：
+## 执行模式
 
-- **CONTEXT.md** —— 当前变更的领域术语与概念：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
-- **ADR.md** —— 当前变更的架构决策记录：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
-- **goal-plan.md** —— 如果存在目标规划文档，读取了解里程碑级约束和门禁次序：`<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
-- **永久 ADR** —— 已确认并提升到永久的架构决策，始终反映项目当前架构现状：`<Path>{roots.state}/specdev/adr/</Path>`
-- **永久 CONTEXT** —— 已确认并提升到永久的领域词汇表，始终反映项目当前领域术语现状：`<Path>{roots.state}/specdev/context/</Path>`
+### Ticket 模式（默认）
 
-如果当前 change 下的 CONTEXT.md 或 ADR.md 不存在，先运行 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 或询问用户以建立上下文。永久 ADR 和 CONTEXT 目录可能为空——静默继续，不影响后续流程。
+读取一个 Ready Ticket：
+
+- Ticket：`<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`
+- Tickets Map：`<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- 可选 Goal Plan：`<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
+
+Ticket 模式适用于多 Ticket、Standard/Deep、并行、迁移或需要完整证据治理的工作。
+
+### Direct Spec 模式（保留原能力）
+
+极小、局部、单一行为且不需要独立 Ticket DAG 的工作，可以在用户明确批准后直接基于：
+
+- Spec：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- 架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- 领域上下文：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+
+执行前必须从 Spec 明确提取并向用户确认一个轻量执行契约：目标、IN/OUT、可写范围、关键不变量、验证命令和验收条件。出现公共 API/schema、迁移、安全、高风险、多个独立行为或并行需求时，必须返回 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`，不得使用 Direct Spec 模式绕过治理。
+
+## 通用输入
+
+按存在情况读取：
+
+- 当前 Spec：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- 当前架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- 当前领域上下文：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- 当前设计日志：`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+- 永久架构决策：`<Path>{roots.state}/specdev/adr/</Path>`
+- 永久领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
+- 项目配置：`<Path>{roots.state}/specdev/config.json</Path>`
+
+当前 change 的架构决策或领域上下文缺失，且实现需要这些决定时，先运行 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 或请求用户建立上下文。永久目录可以为空，静默继续。
 
 ## 流程
 
-### 1. 设计检查
+### 1. 执行前预检
 
-在编写任何代码之前，检查当前变更涉及的模块接口设计。使用 `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>` 中的术语表评估：
+加载 `<Path>{roots.workflows}/specdev/I-implement/execution-preflight.md</Path>`。
 
-- 要实现的代码属于哪些**模块**？
-- 每个模块的**接口**是什么？（类型签名、不变量、顺序约束、错误模式）
-- 接口的**深度**如何？调用者是否获得了足够的**杠杆效应**？
-- **接缝**放在哪里？是否有至少两个适配器来证明接缝是真实的？
-- 每个接缝处的依赖属于哪个类别？（进程内、本地可替换、远程但自有、真正的外部依赖——参见 `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>`）
+Ticket 模式检查：
 
-如果需要探索替代接口设计，启动 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>` 流程。
+- `ready: true`；
+- 状态允许开始；
+- `blocked_by` 全部 done；
+- Ticket 与 Spec/ADR/Goal Plan 无冲突；
+- 可写、只读、共享路径明确且无并发冲突；
+- 并行执行时，Ticket 的 worktree 记录为 `active`，`base_sha` 与派单一致；
+- 验证命令和 Evidence 位置可用；
+- 当前代码事实没有使核心契约失效。
 
-若设计检查中遇到不熟悉的库/框架 API、需要了解替代方案的技术细节或外部依赖的能力边界，先调用 `<Path>{roots.workflows}/specdev/common/research/SKILL.md</Path>` 完成探查后再继续接口评估。
+Direct Spec 模式检查：
 
-**完成标准**：模块接口设计已检查——深度、接缝位置、适配器策略合理。每个接缝的依赖类别已分类。
+- 用户已明确批准直接实现；
+- 单一行为、局部、低风险、可逆；
+- 轻量执行契约完整；
+- 不涉及 Deep 条件；
+- 可写范围和验证明确。
 
-### 2. TDD 循环
+失败时停止，标记 `blocked` 或 `deviated`，不得边做边补关键决策。
 
-按照 `<Path>{roots.workflows}/specdev/I-implement/tdd-rules.md</Path>` 执行红→绿循环：
+### 2. 设计检查
 
-1. 确认每个接缝的测试策略（参见 `<Path>{roots.workflows}/specdev/I-implement/tdd-examples.md</Path>` 中的示例）
-2. 在接缝处编写失败的测试——通过公共接口验证行为
-3. 只写足以通过测试的代码
-4. 每个循环一张垂直切片，响应上一个循环的反馈
+加载：
 
-循环重复直到所有 tickets 实现完成。如果审查后发现阻塞性问题（步骤 3），返回此步骤继续循环。
+- `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>`
+- `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>`
 
-**完成标准**：红→绿循环完成——每个接缝一张垂直切片，测试通过公共接口验证行为。所有 tickets 实现完成。
+在写代码前检查：
 
-### 3. 审查
+- 目标代码属于哪些模块；
+- 每个模块的接口、类型、不变量、顺序约束、错误和性能语义；
+- 模块是否有足够深度，是否减少调用者认知；
+- 接缝在哪里，是否有真实适配器或可替换实现；
+- 依赖属于进程内、本地可替换、远程自有或真正外部依赖；
+- 测试应在哪个稳定接缝观察行为；
+- Ticket/Spec 已锁定的公共契约是否被保持。
 
-按照 `<Path>{roots.workflows}/specdev/I-implement/code-review-process.md</Path>` 执行双轴审查：
+存在多个局部接口设计且不改变已锁定契约时，可以运行 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`。若方案会改变外部行为、公共接口、数据、兼容、安全或范围，返回规划工件，不使用 design-it-twice 绕过决策。
 
-- **标准轴** — 代码是否符合编码规范？是否出现 Fowler 代码异味？
-- **规范轴** — 代码是否忠实地实现了 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` 中的要求？
+若不熟悉外部库、框架 API 或依赖能力边界，调用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。
 
-如果审查发现阻塞性问题，返回步骤 2「TDD 循环」修复；否则进入提交。
+**完成标准**：模块深度、接口、不变量、接缝、适配器和依赖策略已检查，局部设计与上层契约一致。
 
-**完成标准**：双轴审查完成——标准轴和规范轴均已通过，无阻塞性问题。
+### 3. TDD 红→绿垂直循环
 
-### 4. 提交
+加载：
 
-1. 运行项目自身的类型/静态检查命令——从项目脚本（package.json scripts、Makefile、CI 配置等）探测，不确定时询问用户
-2. 运行项目自身的完整测试套件命令——探测方式同上
-3. 将更改提交到当前分支：`git add -A && git commit -m "<描述性提交信息>"`
-4. 更新 `<Path>{roots.state}/specdev/changes/{change}/</Path>` 下的状态文件
+- `<Path>{roots.workflows}/specdev/I-implement/tdd-rules.md</Path>`
+- `<Path>{roots.workflows}/specdev/I-implement/tdd-examples.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`
 
-**完成标准**：代码已提交到当前分支，类型检查和测试通过，状态文件已更新。
+对每个验收行为或关键风险：
 
----
+1. 选择公共接口或稳定接缝；
+2. 编写会因目标行为缺失而失败的测试或可重复验证；
+3. 确认失败原因正确；
+4. 只写足以通过当前测试的实现；
+5. 运行定向验证；
+6. 在保持绿色的状态下重构；
+7. 进入下一条窄垂直切片。
 
-## 子文件引用
+本循环新增或修改代码注释时，使用注释规则判断信息是否应由代码表达，并同步维护受行为变更影响的既有注释。
+
+不得通过删除测试、放宽断言、吞错、永久跳过或只测试 Mock 调用次数来制造绿色。
+
+### 4. 持续验证与范围审计
+
+- 每个安全落点运行定向验证；
+- 完成前运行 Ticket 验证矩阵，或 Direct Spec 模式的轻量验证契约；
+- 按 `<Path>{roots.state}/specdev/config.json</Path>` 运行适用的类型检查、lint、测试和构建；
+- Worker 不运行 E2E；若用户界面交互受影响，记录场景与预期结果，交由 Lead 在集成阶段执行；
+- 检查实际修改均在 `writable_paths` 或获批的 Direct Spec 可写范围内；
+- shared path 只由 owner 修改；
+- 越界前停止并提出 ownership change，不先改后报；
+- 记录新失败、既有失败和环境失败的区别。
+
+证据规则见 `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`。
+
+### 5. 双轴审查
+
+加载 `<Path>{roots.workflows}/specdev/I-implement/code-review-process.md</Path>`。
 
-以下子文件包含各步骤的详细规则、示例和参考材料，仅在对应步骤进入时加载：
+- **标准轴**：正确性、模块设计、代码异味、错误处理、安全、性能、并发、资源释放、测试质量和可维护性；
+- **规范轴**：对照 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`、Ticket 的 IN/OUT、实现契约、路径所有权、验证矩阵和 Goal Gate。
 
-| 文件 | 内容 | 触发条件 |
-|------|------|---------|
-| `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>` | 深层模块设计的 8 个术语定义、原则、为可测试性设计 | 步骤 1「设计检查」进入时 |
-| `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>` | 依赖类别、接缝纪律、测试策略 | 设计检查中需要分析依赖时 |
-| `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>` | 并行子 Agent 探索替代接口的三步流程 | 设计检查中需要探索替代方案时 |
-| `<Path>{roots.workflows}/specdev/I-implement/tdd-rules.md</Path>` | 红→绿循环的完整规则、反模式、接缝测试策略 | 步骤 2「TDD 循环」进入时 |
-| `<Path>{roots.workflows}/specdev/I-implement/tdd-examples.md</Path>` | 好的测试 vs 坏的测试、同义反复、Mock 指南、为可 Mock 性设计 | 编写具体测试时参考 |
-| `<Path>{roots.workflows}/specdev/I-implement/code-review-process.md</Path>` | 双轴审查流程、12 个 Fowler 异味基线、子 Agent 提示词模板 | 步骤 3「审查」进入时 |
+标准轴同时复核步骤 3 加载的注释规则：公共 API 契约完整，内部注释只保留非显然的 Why、Invariant 和 Risk，且所有相关注释与当前行为一致。
+
+审查发现局部阻塞问题时回到 TDD 循环；需要改变上层契约时升级 deviation 并返回 Spec/Ticket/ADR。
+
+### 6. Evidence 与状态
+
+Ticket 模式使用 `<Path>{roots.workflows}/specdev/I-implement/evidence-template.md</Path>` 写入：
+
+```text
+<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>
+```
+
+Direct Spec 模式写入：
+
+```text
+<Path>{roots.state}/specdev/changes/{change}/evidence/direct-spec.md</Path>
+```
+
+Evidence 必须包含实际修改范围、命令与结果、验收逐条映射、未运行项、偏差、残余风险和提交引用。
+
+Ticket 状态依次为 `ready → in_progress → review → done`；阻塞使用 `blocked`，实际实现与批准契约不一致使用 `deviated`。验证无法运行或存在未批准偏差时不得标 `done`。
+
+同步：
+
+- Ticket：`<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`
+- Tickets Map：`<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- change 状态：`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`
+- 全局状态：`<Path>{roots.state}/specdev/status.json</Path>`
+
+### 7. 提交与返回
+
+1. 运行项目自身的适用验证；
+2. 仅在 `<Path>{roots.state}/specdev/config.json</Path>` 和用户授权允许时提交；
+3. 提交信息引用 Ticket ID 或 Direct Spec change；
+4. 不自动推送、合并、部署、发布或执行不可逆迁移；
+5. 返回 Ticket ID 与状态、Evidence 完整路径、`workspace_ref`、commit 或 PR 引用，以及仅在用户界面交互受影响时由 Lead 执行的待办 E2E；
+6. Direct Spec 模式返回 change、状态和 `<Path>{roots.state}/specdev/changes/{change}/evidence/direct-spec.md</Path>`。
+
+若由 Lead 编排，遵循 `<Path>{roots.workflows}/specdev/P-goal-plan/orchestration-protocol.md</Path>` 的 Evidence 返回协议。
+
+## 完成标准
+
+- 执行前预检通过；
+- 设计检查保留深层模块、接缝和依赖分类能力；
+- 每个行为通过真实红→绿循环实现；
+- 定向与适用回归验证完成；
+- 双轴审查通过；
+- Evidence 完整；
+- 实际修改未超出授权路径；
+- 无未批准 deviation；
+- 状态已同步；
+- 实现结果可通过 Evidence、状态和代码引用完整定位；
+- 提交遵守用户授权。
+
+## 子文件引用
 
-实现的产物（代码变更）直接写入仓库的源代码目录。变更追踪、spec 和 ADR 仍存放在 `<Path>{roots.state}/specdev/changes/{change}/</Path>` 下。
+- 执行前预检：`<Path>{roots.workflows}/specdev/I-implement/execution-preflight.md</Path>`
+- 代码库设计术语：`<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>`
+- 深化与依赖策略：`<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>`
+- Design It Twice：`<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`
+- TDD 规则：`<Path>{roots.workflows}/specdev/I-implement/tdd-rules.md</Path>`
+- TDD 示例：`<Path>{roots.workflows}/specdev/I-implement/tdd-examples.md</Path>`
+- 代码注释规则：`<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`
+- 双轴审查：`<Path>{roots.workflows}/specdev/I-implement/code-review-process.md</Path>`
+- Evidence 模板：`<Path>{roots.workflows}/specdev/I-implement/evidence-template.md</Path>`

package/template/workflows/specdev/I-implement/code-review-process.md

@@ -1,83 +1,17 @@
-# 代码审查
+# 双轴审查
 
-对 `HEAD` 与实现开始前的某个固定点之间的 diff 进行双轴审查：
+## 标准轴
 
-- **标准** — 代码是否符合此仓库已记录的编码规范？
-- **规范** — 代码是否忠实地实现了原始 spec？
+检查正确性、并发、资源释放、错误处理、安全、性能风险、模块深度、重复知识、测试真实性和可读性。评论必须指向具体行为风险，不做纯风格噪声。
 
-两个轴以**并行子 Agent** 方式运行，以免互相污染上下文，然后本流程汇总它们的发现。
+## 契约轴
 
-## 流程
+逐项核对：contract_ids、IN/REUSE/OUT、锁定决策、不变量、失败/兼容、writable_paths、验证矩阵、Deep 发布恢复和 Goal Gate。
 
-### 1. 确定固定点
+## 结论
 
-实现开始前的 commit SHA、分支名、tag、`main` 或合并基准。通常为开始实现前的 HEAD。如果用户未指定，请询问。
+- `APPROVE`：无阻塞问题；
+- `REQUEST_CHANGES`：列出阻塞问题、证据和应满足的结果；
+- `ESCALATE_DEVIATION`：修复需要改变上层契约。
 
-一次性捕获 diff 命令：`git diff <固定点>...HEAD`（三个点，以便与合并基准比较）。同时通过 `git log <固定点>..HEAD --oneline` 记录 commit 列表。
-
-继续之前，确认固定点可解析（`git rev-parse <固定点>`）且 diff 非空。无效引用或空 diff 应在此处失败 — 而非在两个并行子 Agent 内部。
-
-### 2. 识别规范来源
-
-规范来源为当前变更的 spec 文件：
-
-`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
-
-如果该文件不存在，**规范**子 Agent 将跳过并报告"无可用的规范"。
-
-### 3. 识别标准来源
-
-仓库中所有记录代码应如何编写的文件，如 `CODING_STANDARDS.md` 或 `CONTRIBUTING.md`。
-
-在仓库记录的任何标准之上，标准轴始终携带以下**异味基线** — 一组固定的 Fowler 代码异味（《重构》第 3 章），即使仓库没有任何记录也适用。两条规则约束它：
-
-- **仓库优先。** 已记录的仓库标准始终优先；当它认可基线可能标记的内容时，抑制该异味。
-- **始终是判断。** 每个异味是一个带标签的启发式（"可能的 Feature Envy"），从来不是硬性违规 — 并且，与这里的任何标准一样，跳过工具链已在强制执行的内容。
-
-每个异味读作*它是什么* → *如何修复*；将其与 diff 进行匹配：
-
-- **Mysterious Name** — 函数、变量或类型，其名称不能揭示它做什么或持有什么。→ 重命名；如果没有诚实的名称可用，说明设计不清晰。
-- **Duplicated Code** — 相同的逻辑形态出现在变更中的一个以上代码块或文件中。→ 提取共享形态，从两处调用。
-- **Feature Envy** — 一个方法过多地访问另一个对象的数据，而非自身数据。→ 将该方法移动到它所羡慕的数据上。
-- **Data Clumps** — 相同的几个字段或参数总是一起出现（一个等待诞生的类型）。→ 将它们捆绑成一个类型，传递该类型。
-- **Primitive Obsession** — 一个基本类型或字符串替代了应拥有自己类型的领域概念。→ 为该概念创建自己的小型类型。
-- **Repeated Switches** — 对同一类型的相同 `switch`/`if` 级联在变更中反复出现。→ 用多态替代，或使用两个位置共享的一个映射。
-- **Shotgun Surgery** — 一个逻辑变更迫使在 diff 中跨多个文件进行分散编辑。→ 将一起变更的内容汇聚到一个模块中。
-- **Divergent Change** — 一个文件或模块因多个不相关的原因被编辑。→ 拆分，使每个模块因一个原因变更。
-- **Speculative Generality** — 为 spec 中没有的需求添加的抽象、参数或钩子。→ 删除它；回退内联，直到真实需求出现。
-- **Message Chains** — 调用者不应依赖的长链式 `a.b().c().d()` 导航。→ 在第一个对象上用一个方法隐藏整个链路。
-- **Middle Man** — 一个类或函数大部分只是委托转发。→ 删除它，直接调用真正的目标。
-- **Refused Bequest** — 一个子类或实现者忽略或覆盖了其继承的大部分内容。→ 放弃继承，使用组合。
-
-### 4. 并行启动两个子 Agent
-
-发送一条消息，包含两个 `Agent` 工具调用。两者均使用 `general-purpose` 子 Agent。
-
-**标准子 Agent 提示词** — 包含：
-
-- 完整的 diff 命令和 commit 列表。
-- 在第 3 步中找到的标准来源文件列表，**加上第 3 步中的异味基线全文粘贴** — 子 Agent 没有其他途径获取它。
-- 任务简述："报告 — 在相关时按文件/代码块 — (a) diff 违反已记录标准的每个地方：引用标准（文件 + 规则）；以及 (b) 你发现的任何基线异味：命名并引用代码块。区分硬性违规和判断性调用 — 已记录标准的违规可以是硬性的，但基线异味始终是判断性调用，且已记录的仓库标准覆盖基线。跳过工具链已强制执行的内容。400 词以内。"
-
-**规范子 Agent 提示词** — 包含：
-
-- diff 命令和 commit 列表。
-- spec 的路径或已获取的内容：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`。
-- 任务简述："报告：(a) spec 要求但缺失或不完整的需求；(b) diff 中存在但未被要求的、超出范围的行为；(c) 看起来已实现但实现方式错误的需求。每个发现引用 spec 原文。400 词以内。"
-
-如果 spec 缺失，跳过规范子 Agent 并在最终报告中注明。
-
-### 5. 汇总
-
-在 `## 标准` 和 `## 规范` 标题下呈现两份报告，原文或略微整理。**不要**合并或重新排名发现 — 两个轴故意分离（见*为什么是两个轴*）。
-
-以一行摘要结束：每个轴的发现总数，以及每个轴内_最严重的问题_（如有）。不要在轴之间选一个"赢家" — 那正是分离设计要防止的重新排名。
-
-## 为什么是两个轴
-
-一个变更可能通过一个轴而未通过另一个：
-
-- 代码遵循所有标准但实现了错误的东西 → **标准通过，规范未通过。**
-- 代码完全按 spec 要求做了，但违反了项目的约定 → **规范通过，标准未通过。**
-
-分开报告可以防止一个轴掩盖另一个轴。
+审查者不得通过设计新功能扩大 Ticket。

package/template/workflows/specdev/I-implement/codebase-design-glossary.md

@@ -1,109 +1,12 @@
-# 代码仓设计
-
-设计**深层模块**：通过一个小接口承载大量行为，放置在干净的接缝处，可通过该接口进行测试。在任何设计或重构代码的地方使用这些语言和原则。目标是为调用者提供杠杆效应，为维护者提供局部性，为所有人提供可测试性。
-
-## 术语表
-
-严格使用以下术语 — 不要用 "component"、"service"、"API" 或 "boundary" 替代。一致的语言才是重点。
-
-**Module（模块）** — 任何具有接口和实现的东西。有意识地与规模无关：函数、类、包或跨层切片。_避免使用_：unit、component、service。
-
-**Interface（接口）** — 调用者正确使用模块所需了解的一切：类型签名，还包括不变量、顺序约束、错误模式、必需配置和性能特征。_避免使用_：API、signature（太窄 — 它们仅指类型层面的表面）。
-
-**Implementation（实现）** — 模块内部的内容，它的代码体。区别于 **Adapter（适配器）**：一个东西可以是一个小适配器加一个大实现（Postgres 仓库），也可以是一个大适配器加一个小实现（内存假实现）。当讨论接缝时用 "adapter"；否则用 "implementation"。
-
-**Depth（深度）** — 接口处的杠杆效应：调用者（或测试）每学习一个单位的接口可以驱动的行为量。当大量行为隐藏在小接口后面时，模块是**深层的**；当接口几乎和实现一样复杂时，模块是**浅层的**。
-
-**Seam（接缝）** _(Michael Feathers)_ — 一个可以在不编辑该位置的情况下改变行为的地方；模块接口所在的*位置*。接缝放在哪里本身就是一个设计决策，与接缝后面放什么不同。_避免使用_：boundary（与 DDD 的有界上下文重载）。
-
-**Adapter（适配器）** — 在接缝处满足接口的具体事物。描述的是*角色*（它填充哪个槽位），而非实质（内部是什么）。
-
-**Leverage（杠杆效应）** — 调用者从深度中获得的好处：每学习一个单位的接口获得更多的能力。一个实现为 N 个调用点和 M 个测试带来回报。
-
-**Locality（局部性）** — 维护者从深度中获得的好处：变更、bug、知识和验证集中在一个地方，而非分散在调用者之间。一次修复，处处生效。
-
-## 深层 vs 浅层
-
-**深层模块** = 小接口 + 大量实现：
-
-```
-┌─────────────────────┐
-│   小接口             │  ← 少量方法，简单参数
-├─────────────────────┤
-│                     │
-│  深层实现            │  ← 隐藏的复杂逻辑
-│                     │
-└─────────────────────┘
-```
-
-**浅层模块** = 大接口 + 少量实现（应避免）：
-
-```
-┌─────────────────────────────────┐
-│       大接口                     │  ← 大量方法，复杂参数
-├─────────────────────────────────┤
-│  薄实现                          │  ← 仅仅是透传
-└─────────────────────────────────┘
-```
-
-设计接口时，问自己：
-
-- 我能减少方法数量吗？
-- 我能简化参数吗？
-- 我能隐藏更多内部的复杂性吗？
-
-## 原则
-
-- **深度是接口的属性，而非实现的属性。** 一个深层模块内部可以由小型、可模拟、可替换的部分组成 — 只是它们不属于接口的一部分。一个模块可以拥有**内部接缝**（对其实现私有，用于其自身测试）以及位于其接口处的**外部接缝**。
-- **删除测试。** 想象删除这个模块。如果复杂性消失，它就是个透传层。如果复杂性在 N 个调用者中重新出现，它就在发挥价值。
-- **接口就是测试表面。** 调用者和测试穿过同一个接缝。如果你想测试接口_之外_的内容，模块可能形状不对。
-- **一个适配器意味着假设的接缝。两个适配器意味着真实的接缝。** 除非有东西确实在接缝两侧变化，否则不要引入接缝。
-
-## 为可测试性而设计
-
-良好的接口使测试变得自然：
-
-1. **接收依赖，不要创建依赖。**
-
-   ```typescript
-   // 可测试
-   function processOrder(order, paymentGateway) {}
-
-   // 难以测试
-   function processOrder(order) {
-     const gateway = new StripeGateway();
-   }
-   ```
-
-2. **返回结果，不要产生副作用。**
-
-   ```typescript
-   // 可测试
-   function calculateDiscount(cart): Discount {}
-
-   // 难以测试
-   function applyDiscount(cart): void {
-     cart.total -= discount;
-   }
-   ```
-
-3. **小表面积。** 更少的方法 = 更少的测试需求。更少的参数 = 更简单的测试设置。
-
-## 关系
-
-- 一个 **Module** 恰好有一个 **Interface**（它向调用者和测试呈现的表面）。
-- **Depth** 是一个 **Module** 的属性，对照其 **Interface** 来度量。
-- 一个 **Seam** 是一个 **Module** 的 **Interface** 所在的位置。
-- 一个 **Adapter** 位于 **Seam** 处，满足 **Interface**。
-- **Depth** 为调用者产生 **Leverage**，为维护者产生 **Locality**。
-
-## 已拒绝的框架
-
-- **深度作为实现行数与接口行数之比** (Ousterhout)：奖励填充实现。我们使用深度即杠杆效应来替代。
-- **"Interface" 作为 TypeScript 的 `interface` 关键字或类的公开方法**：太窄 — 此处的接口包括调用者必须了解的每个事实。
-- **"Boundary"**：与 DDD 的有界上下文重载。说 **seam** 或 **interface**。
-
-## 深入阅读
-
-- **给定依赖的情况下深化一个集群** — 见 `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>`：依赖类别、接缝规程、以及替换而非分层的测试。
-- **探索替代接口** — 见 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`：启动并行子 agent，以几种截然不同的方式设计接口，然后在深度、局部性和接缝位置上进行比较。
+# 代码库设计术语
+
+- **模块**：隐藏复杂度并提供稳定接口的单元，不等于目录或类。
+- **深度**：接口简单度相对于模块内部承载复杂度的杠杆。
+- **接口**：调用者必须知道的全部，包括类型、不变量、顺序、错误和性能语义。
+- **接缝**：可以替换、观察或验证行为的位置。
+- **适配器**：把外部变化隔离在稳定接缝外的实现。
+- **信息隐藏**：设计决定只存在于一个权威位置。
+- **局部性**：完成一个行为所需理解和修改的范围尽可能集中。
+- **时间耦合**：调用必须按隐含顺序发生；应显式化或封装。
+
+检查目标：减少调用者认知，而不是单纯减少行数或文件数。