@namewta/speculo 0.6.0 → 0.7.0

package/template/workflows/specdev/G-grill-with-docs/domain-modeling-rules.md

@@ -1,7 +1,12 @@
 # 领域建模规则
 
-- 使用业务语言定义概念，避免用当前类名代替领域定义。
-- 每个术语包含：定义、边界、示例、反例、相关不变量、代码映射。
-- 同义词选择一个规范词，其余标别名；一词多义必须拆分。
-- CONTEXT 描述当前真相；讨论历史只留在 LOG。
-- 与代码不一致时同时记录“期望领域模型”和“当前实现差距”，不得假装已实现。
+本规则只规范当前 change 内的候选领域知识。G 和 A 的 consolidate-from-code 模式都可以用它整理 change 工件，但它不授权写入永久 namespace；永久知识只能由 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>` 在完成证据、毕业评估和用户确认全部通过后提升。
+
+- 当前 change 的 CONTEXT 只保存已确认、供本 change 下游使用的项目规范语言，不保存普通编程概念、代码导航、一次性状态或讨论历史。
+- 每个术语使用规范名称和 1–2 句定义；不推荐的同义词写入 `_Avoid_`。
+- 一词多义必须拆分；多个 bounded context 使用独立 Context Map 描述关系，不把关系塞进术语定义。
+- 讨论、替代和历史只留在 LOG；稳定行为进入 Spec；符合准入条件的取舍写入当前 change 的 ADR，`accepted` 只表示已成为本 change 的下游合同。
+- 当前代码位置按需从仓库发现。只有发现成本被证明很高时，另建有 owner 和刷新策略的缓存工件，CONTEXT 不承担该职责。
+- G 只读永久 `<Path>{roots.state}/specdev/context/</Path>` 与 `<Path>{roots.state}/specdev/adr/</Path>`，用于发现冲突和避免重复；不得创建、合并或改写其中内容。
+
+完成标准：每个 change CONTEXT 条目都是本 change 下游必须使用的项目规范语言；每个 change ADR 都有明确来源和当前 change 的适用范围；没有把候选结论写成永久知识。

package/template/workflows/specdev/G-grill-with-docs/stakeholder-questionnaire.md

@@ -0,0 +1,45 @@
+# Stakeholder Questionnaire
+
+只有阻塞决定无法从仓库/外部事实发现、当前用户无法回答、且另一个明确 stakeholder 掌握答案时加载。问卷是输入收集工具，不是决策权威。
+
+## 流程
+
+1. 只询问当前用户“发给谁”和“需要对方回什么”：接收者角色/背景/关系，以及用户必须据此行动的具体事实或决定。
+2. 写入 `<Path>{roots.state}/specdev/changes/{change}/questionnaires/{slug}.md</Path>`。问题按重要性排序，每个问题只表达一个差距；超过合理数量时按主题分组。
+3. 把 change 置为 blocked，记录接收者、发送 owner、恢复条件和问卷 Path。Spec/Ticket 不得在答案回来前伪装成 Ready。
+4. 回收答案后逐项验证覆盖情况，把事实和决定分别写入 LOG/design-tree 节点；问卷本身保留原始回答，不直接成为 ADR/Spec 权威。
+5. 未回答项继续 blocked；已解决项不重复询问。
+
+## 模板
+
+```markdown
+# <问卷标题>
+
+**目的：** <承载的决定>
+**来自：** <用户> — **送达：** <接收者>
+**回答将用于：** <Spec/ADR/design-tree 路径>
+
+## 背景
+<足以给出可靠回答的一段上下文>
+
+## 如何回答
+<截止时间、投入量；允许部分回答和“不知道”>
+
+## <主题>
+
+### <一个事实或决定差距>
+_为什么重要：<对行为/风险/范围的影响>_
+
+>
+
+## 还有别的吗？
+<遗漏但接收者认为应知道的事项>
+```
+
+## 完成标准
+
+- 用户要求的每个事实/决定恰有至少一个问题覆盖；
+- 不询问仓库可发现事实；
+- 问题不复合且按重要性排序；
+- blocked/resume 条件可从本地工件恢复；
+- 回答被转录到真正 owning 工件后才解除 blocker。

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

@@ -9,7 +9,7 @@ keywords: [实现, TDD, 代码审查, 模块设计, 证据, ticket]
 
 # 实现
 
-本 work 保留原有完整实现能力：深模块设计检查、接缝和依赖分类、design-it-twice、TDD 红→绿垂直循环、标准轴与规范轴审查、项目级验证、提交和状态更新。治理升级增加 Ready、路径所有权、Evidence 和偏差门禁，但不把实现退化为机械照单执行。
+本 work 保留深模块设计检查、接缝和依赖分类、design-it-twice、TDD 红→绿垂直循环、隔离双轴审查、项目级验证、提交和状态更新。治理升级增加 Ready、路径所有权、Evidence、完成所有权和偏差门禁。
 
 ## 执行模式
 
@@ -23,7 +23,7 @@ keywords: [实现, TDD, 代码审查, 模块设计, 证据, ticket]
 
 Ticket 模式适用于多 Ticket、Standard/Deep、并行、迁移或需要完整证据治理的工作。
 
-若 Goal Plan 的 Delivery Contract 选择 `native-subagent` 或 `external-web-subagent`，这是 Ticket 模式的 delegated execution 分支。Lead 在派单、恢复或验收候选交付时调用 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`；Worker 的局部实现仍完整遵循本 work，不由 provider 改写。
+Goal Plan 只有包含完整 `## Delegated Execution Addendum` 时才进入 delegated execution 分支。Lead 在派单、恢复或验收候选交付时调用 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`；普通 Goal Plan 不建立 Lead/Worker 角色，也不调用该 Skill。
 
 ### Direct Spec 模式（保留原能力）
 
@@ -51,6 +51,8 @@ Ticket 模式适用于多 Ticket、Standard/Deep、并行、迁移或需要完
 
 ## 流程
 
+Git 已处于 merge/rebase 冲突时，先加载 `<Path>{roots.workflows}/specdev/I-implement/merge-conflict-protocol.md</Path>` 并完成或可恢复地暂停该分支；不要把冲突伪装成普通 TDD 切片。
+
 ### 1. 执行前预检
 
 加载 `<Path>{roots.workflows}/specdev/I-implement/execution-preflight.md</Path>`。
@@ -63,7 +65,7 @@ Ticket 模式检查：
 - Ticket 与 Spec/ADR/Goal Plan 无冲突；
 - 可写、只读、共享路径明确且无并发冲突；
 - 并行执行时，Ticket 的 worktree 记录为 `active`，`base_sha` 与派单一致；
-- delegated execution 时，派单块的 execution model、Lead、checkpoint、workspace/session locator、路径合同、修正上限和授权矩阵与当前事实一致；
+- 存在委派附录时，派单块的 execution model、Lead、checkpoint、workspace/session locator、路径合同、修正上限和授权矩阵与当前事实一致；
 - 验证命令和 Evidence 位置可用；
 - 当前代码事实没有使核心契约失效。
 
@@ -102,7 +104,8 @@ Direct Spec 模式检查：
 加载：
 
 - `<Path>{roots.workflows}/specdev/I-implement/tdd-rules.md</Path>`
-- `<Path>{roots.workflows}/specdev/I-implement/tdd-examples.md</Path>`
+- `<Path>{roots.workflows}/specdev/I-implement/tdd-test-design.md</Path>`
+- `<Path>{roots.workflows}/specdev/I-implement/tdd-mocking.md</Path>`
 - `<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`
 
 对每个验收行为或关键风险：
@@ -112,8 +115,7 @@ Direct Spec 模式检查：
 3. 确认失败原因正确；
 4. 只写足以通过当前测试的实现；
 5. 运行定向验证；
-6. 在保持绿色的状态下重构；
-7. 进入下一条窄垂直切片。
+6. 保存 red/green 证据并进入下一条窄垂直切片。
 
 本循环新增或修改代码注释时，使用注释规则判断信息是否应由代码表达，并同步维护受行为变更影响的既有注释。
 
@@ -124,24 +126,32 @@ Direct Spec 模式检查：
 - 每个安全落点运行定向验证；
 - 完成前运行 Ticket 验证矩阵，或 Direct Spec 模式的轻量验证契约；
 - 按 `<Path>{roots.state}/specdev/config.json</Path>` 运行适用的类型检查、lint、测试和构建；
-- Worker 不运行 E2E；若用户界面交互受影响，记录场景与预期结果，交由 Lead 在集成阶段执行；
+- 普通 Goal Plan 下由当前实现者运行适用 E2E；存在委派附录时 Worker 只记录场景与预期结果，由 Lead 在集成阶段执行；
 - 检查实际修改均在 `writable_paths` 或获批的 Direct Spec 可写范围内；
 - shared path 只由 owner 修改；
 - 越界前停止并提出 ownership change，不先改后报；
 - 记录新失败、既有失败和环境失败的区别。
 
+完成当前实现审查前运行：
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
+  --stage implement \
+  <Path>{roots.state}/specdev/changes/{change}</Path>
+```
+
 证据规则见 `<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.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`，把当前 Ticket 基线和实现 checkpoint 固定为本地 SHA。
 
 - **标准轴**：正确性、模块设计、代码异味、错误处理、安全、性能、并发、资源释放、测试质量和可维护性；
 - **规范轴**：对照 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`、Ticket 的 IN/OUT、实现契约、路径所有权、验证矩阵和 Goal Gate。
 
 标准轴同时复核步骤 3 加载的注释规则：公共 API 契约完整，内部注释只保留非显然的 Why、Invariant 和 Risk，且所有相关注释与当前行为一致。
 
-审查发现局部阻塞问题时回到 TDD 循环；需要改变上层契约时升级 deviation 并返回 Spec/Ticket/ADR。
+两个轴使用隔离上下文并按标准轴、规范轴顺序写入 Evidence，不合并或跨轴重排。审查发现局部问题时进入独立修正/重构阶段，随后重跑受影响验证和 review 轴；需要改变上层契约时升级 deviation 并返回 Spec/Ticket/ADR。
 
 ### 6. Evidence 与状态
 
@@ -159,10 +169,12 @@ Direct Spec 模式写入：
 
 Evidence 必须包含实际修改范围、命令与结果、验收逐条映射、未运行项、偏差、残余风险和提交引用。
 
-delegated execution 还必须记录 execution model、provider、派单与最终 checkpoint、workspace/session locator、候选交付核对、修正轮次和未验证声明。Lead 使用 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>` 的 `operation=execute` 分支完成核对；provider 自报结果不能直接标记为 `pass`。
+存在委派附录时，加载 `<Path>{roots.workflows}/specdev/I-implement/delegated-evidence-template.md</Path>`，补充 execution model、provider、派单与最终 checkpoint、workspace/session locator、候选交付核对、修正轮次和未验证声明。Lead 使用 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>` 的 `operation=execute` 分支完成核对；provider 自报结果不能直接标记为 `pass`。普通 Evidence 不包含这些字段或空占位。
 
 Ticket 状态依次为 `ready → in_progress → review → done`；阻塞使用 `blocked`，实际实现与批准契约不一致使用 `deviated`。验证无法运行或存在未批准偏差时不得标 `done`。
 
+最后一个计划内 Ticket 完成后加载 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`：没有 Goal Plan 或 Goal Plan 不含委派附录时，完成门全部通过后由本 Work 原子设置 change 为 completed；存在完整委派附录时只返回 Evidence，由 Lead 独立验收并关闭 change。若 triage 显示 `pending-close` 或 `close-failed`，下一 Work 为 `<Path>{roots.workflows}/specdev/T-triage/T-triage.md</Path>`；否则进入 Archive。
+
 同步：
 
 - Ticket：`<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`
@@ -176,10 +188,10 @@ Ticket 状态依次为 `ready → in_progress → review → done`；阻塞使
 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；
+5. 返回 Ticket ID 与状态、Evidence 完整路径、`workspace_ref`、commit 或 PR 引用和适用 E2E 结果；委派 Worker 返回待 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 返回协议；delegated execution 同时返回稳定 workspace/session locator、最终 checkpoint、修正轮次和未验证项。
+普通 Goal Plan 遵循 `<Path>{roots.workflows}/specdev/P-goal-plan/orchestration-protocol.md</Path>` 的 Evidence 返回协议；存在委派附录时遵循 `<Path>{roots.workflows}/specdev/P-goal-plan/delegated-execution.md</Path>`，同时返回稳定 workspace/session locator、最终 checkpoint、修正轮次和未验证项。
 
 ## 完成标准
 
@@ -201,8 +213,11 @@ Ticket 状态依次为 `ready → in_progress → review → done`；阻塞使
 - 代码库设计规则：`<Path>{roots.workflows}/specdev/common/rules/codebase-design.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>`
+- TDD 测试设计：`<Path>{roots.workflows}/specdev/I-implement/tdd-test-design.md</Path>`
+- TDD Mocking：`<Path>{roots.workflows}/specdev/I-implement/tdd-mocking.md</Path>`
 - 代码注释规则：`<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`
-- 双轴审查：`<Path>{roots.workflows}/specdev/I-implement/code-review-process.md</Path>`
+- 双轴审查：`<Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`
 - Evidence 模板：`<Path>{roots.workflows}/specdev/I-implement/evidence-template.md</Path>`
+- 委派 Evidence 附录：`<Path>{roots.workflows}/specdev/I-implement/delegated-evidence-template.md</Path>`，仅 Goal Plan 含委派附录时加载
 - Agent 交付合同：`<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`
+- Merge/rebase 冲突：`<Path>{roots.workflows}/specdev/I-implement/merge-conflict-protocol.md</Path>`

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

@@ -0,0 +1,11 @@
+# Delegated Evidence Addendum
+
+Goal Plan 含完整 `## Delegated Execution Addendum` 时，把以下字段加入对应 Ticket Evidence；普通执行不生成本附录或空占位。
+
+- **Execution model / Provider：** native-subagent / external-web-subagent；`<provider>`
+- **Session/Package locator：** `<portable-locator>`
+- **Dispatch / Final checkpoint：** `<sha-or-fixed-baseline>` / `<sha-or-fixed-baseline>`
+- **Correction rounds：** `<count>`
+- **Candidate delivery verification：** 范围、附件 hash、声明与独立核对结果
+- **Lead E2E：** 不适用 / 待执行：场景与预期 / 通过 / 失败
+- **Unverified claims：** 无 / `<items-and-reason>`

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

@@ -7,10 +7,6 @@
 - **Goal Plan：** `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` / 不适用
 - **基线/分支：**
 - **Worktree 引用：** 不适用 / `<workspace_ref>`
-- **执行模型/Provider：** direct / native-subagent / external-web-subagent；provider 或不适用
-- **Session/Package locator：** 不适用 / `<portable-locator>`
-- **派单/最终 Checkpoint：** `<sha-or-local-baseline>` / `<sha-or-local-baseline>`
-- **修正轮次：** 0 / `<count>`
 - **实现者：**
 - **开始/结束：**
 - **状态：** review / done / blocked / deviated
@@ -41,11 +37,29 @@
 
 - **失败后修复与重跑：** 无 / ...
 - **未运行检查：** 无 / 原因与风险 ...
-- **Lead E2E：** 不适用 / 待执行：场景与预期 / 通过 / 失败
+- **E2E：** 不适用 / 场景、执行者与结果
 - **反向验证：** 不适用 / 受控失败信号与恢复结果
 - **外部声明：** 无 / 已核对 / `unverified`：原因
 
-## 5. 路径所有权审计
+## 5. 双轴审查
+
+### 标准轴
+
+- **结果：** pass / request-changes
+- **来源：** 仓库标准 + Fowler baseline
+- **Findings：** 无 / ...
+- **修正与重跑：** 不适用 / ...
+
+### 规范轴
+
+- **结果：** pass / request-changes / skipped:no-spec
+- **来源：** Spec / Ticket / source / 无
+- **Findings：** 无 / ...
+- **修正与重跑：** 不适用 / ...
+
+两轴保持独立顺序，不合并或跨轴重排 finding。
+
+## 6. 路径所有权审计
 
 - **writable 内修改：**
 - **shared 修改与 owner 批准：** 无 / ...
@@ -53,7 +67,7 @@
 - **未声明路径：** 无
 - **生成文件或锁文件：** 无 / 来源与 owner ...
 
-## 6. 偏差与决策
+## 7. 偏差与决策
 
 - **偏差：** 无 / `<deviation-id>`
 - **偏差记录：** `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` / 不适用
@@ -62,15 +76,15 @@
 
 偏差处理遵守 `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>`，不得静默修改 Ticket 目标或验收。
 
-## 7. 残余风险与后续
+## 8. 残余风险与后续
 
 - **残余风险：** 无 / ...
 - **已知限制：** 无 / ...
 - **后续 Ticket：** 无 / `<ticket-id>`
 - **监控或回滚触发条件：** 不适用 / ...
 
-## 8. 交付定位
+## 9. 交付定位
 
 - **Commit / PR：**
-- **最终 Workspace/Session locator：** 不适用 / `<portable-locator>`
+- **最终 Workspace 引用：** 不适用 / `<workspace_ref>`
 - **Evidence 文件：** `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`

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

@@ -8,9 +8,9 @@
 - [ ] 当前代码入口、接口和路径仍与 Ticket 假设一致。
 - [ ] writable_paths 无并发 owner 冲突。
 - [ ] 并行执行时，`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `worktrees` 中本 Ticket 为 `active`，`base_sha`、分支和 `workspace_ref` 与派单一致。
-- [ ] delegated execution 时，Goal Plan 只有一个 execution model 和 Lead，派单 checkpoint 与当前源码一致，workspace/session locator 可恢复。
-- [ ] delegated execution 的授权矩阵逐项覆盖 local changes、commit、push、PR、merge、deploy、migration 和生产动作；未授权动作不会执行。
-- [ ] 外部候选交付的附件 hash、修改范围和事实声明可由 Lead 独立核对。
+- [ ] Goal Plan 含 `## Delegated Execution Addendum` 时，只有一个 execution model 和 Lead，派单 checkpoint 与当前源码一致，workspace/session locator 可恢复。
+- [ ] 委派附录的授权矩阵逐项覆盖 local changes、commit、push、PR、merge、deploy、migration 和生产动作；未授权动作不会执行。
+- [ ] 委派候选交付的附件 hash、修改范围和事实声明可由 Lead 独立核对。
 - [ ] 验证命令/环境可用。
 - [ ] 可静默失效的关键门禁定义了受控反向验证；普通测试不为形式追加破坏性检查。
 - [ ] Deep Ticket 的批准点已满足。
@@ -22,5 +22,5 @@
 - **ticket-invalid**：范围、接口、依赖、验证或路径契约失效；停止并修 Ticket。
 - **spec-invalid**：外部行为/合同需改变；停止并修 Spec。
 - **adr-conflict**：架构决策冲突；停止并处理 ADR。
-- **checkpoint-drift**：派单基线、源码包或当前代码已经漂移；暂停并由 Lead 重放、重派或建立新 checkpoint。
+- **checkpoint-drift**：委派派单基线、源码包或当前代码已经漂移；暂停并由 Lead 重放、重派或建立新 checkpoint。
 - **delivery-unverified**：候选交付、provider 声明或附件无法独立核对；保持 `unverified`，不得推进 `done`。

package/template/workflows/specdev/I-implement/merge-conflict-protocol.md

@@ -0,0 +1,20 @@
+# Merge / Rebase Conflict Protocol
+
+只在 `git status` 证明仓库正处于 merge 或 rebase 冲突时加载。普通集成设计冲突继续按 deviation/upstream owner 处理。
+
+## 流程
+
+1. 读取 Git 状态、操作类型、冲突文件、base/ours/theirs commit 和当前 Ticket/Evidence。
+2. 追溯双方意图：commit message、冻结的 source、Spec、Ticket、ADR、测试和调用者。二者缺失时不凭代码表面猜测产品行为。
+3. 逐 conflict hunk 写出双方意图、共同约束和建议结果。只合并既有意图；需要发明新行为或改变上层合同则停止并登记 deviation。
+4. 在获授权可写范围内解决文本，运行受影响测试、typecheck、lint 和项目要求的验证。
+5. 分别展示并确认 `git add`、`git merge/rebase --continue` 和最终 commit 动作。没有授权时保存已分析方案、剩余文件和精确恢复命令，不擅自继续。
+6. 重读 Git 状态和 diff，确认无 marker、无未声明路径、双方要求及测试仍成立。
+
+## 完成标准
+
+- 每个 hunk 的结果可追溯到双方意图；
+- 新产品决定没有藏在冲突解决中；
+- 项目验证有命令、退出码和关键输出；
+- Git 副作用逐动作获得授权；
+- 完成或暂停状态可以从 Evidence 和 Git 状态恢复。

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

@@ -0,0 +1,19 @@
+# TDD Mocking
+
+Mock 只位于系统边界：外部 API、不可控时间/随机、必要时文件系统，以及无法使用测试实例的数据库。优先真实测试数据库或轻量实现。
+
+不 Mock 自有模块、内部协作者或可在进程内运行的真实逻辑。Mock 调用本身只有在协议明确把该调用定义为外部行为时才可断言。
+
+## Boundary Design
+
+- 通过依赖注入传入外部 client，不在业务函数内部创建；
+- 使用按操作命名的 SDK 风格接口，例如 `getUser`、`createOrder`，避免要求 mock 内再次实现路由条件的通用 `fetch(endpoint)`；
+- 每个 fake/mock 返回具体协议形态并验证错误、超时和资源清理；
+- 适配器负责第三方 wire format，领域代码测试稳定内部接口。
+
+## 完成门
+
+- 每个 mock 对应真实系统边界；
+- 自有业务行为由真实实现参与测试；
+- mock setup 没有复制生产路由逻辑；
+- 协议兼容、错误和非确定性有可观察验证。

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

@@ -1,15 +1,17 @@
-# TDD 规则
+# TDD 红绿规则
 
-1. 从 Ticket 验收或验证矩阵选择下一条最小行为。
-2. 通过稳定接缝写失败测试，并确认失败原因正确。
-3. 只写使该行为通过的最小生产代码。
-4. 运行定向测试；通过后重构，保持绿色。
-5. 周期性运行受影响回归，完成时运行完整要求。
+1. 从 Ready Ticket/Spec 选择下一条最小可观察行为，并写下已确认 seam。
+2. 只为该行为编写一个会因目标能力缺失而失败的测试或验证。
+3. 运行并观察红灯；失败原因必须是目标行为缺失，而不是语法、夹具或环境错误。
+4. 只写使当前测试通过的最小生产代码，不预测后续切片。
+5. 运行定向测试并观察绿灯，记录命令与结果。
+6. 进入下一条窄垂直切片；周期性运行受影响回归。
 
-## 禁止
+重构不属于红绿循环。全部目标行为完成并经过双轴 review 后，才进入独立修正/重构阶段，并重跑受影响 review 轴与验证。
 
-- 先写大段实现再补测试；
-- Mock 被测对象内部实现；
-- 断言私有调用次数而非外部效果（除非调用本身是合同）；
-- 为通过测试而吞错、降低断言、跳过用例；
-- 把旧失败无证据地归因于环境。
+## 完成门
+
+- 每个切片有对应 red 和 green 证据；
+- 一个循环只有一个 seam、一个测试和一个最小实现；
+- 测试没有通过删除、跳过、吞错或放宽断言制造绿色；
+- review 前没有以“顺手重构”扩大切片。

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

@@ -0,0 +1,25 @@
+# TDD Test Design
+
+## Seam Agreement
+
+测试 seam 必须来自 Ready Ticket/Spec。合同已锁定时直接采用并记录来源；缺失且选择会改变范围、公共接口或事故半径时，先返回上游或请求用户决定。局部且不改变合同的 seam 可按仓库先例选择。
+
+## 行为与独立真相
+
+- 通过公共 API/CLI/HTTP/事件或稳定集成接缝验证调用者可观察行为；
+- 测试名称描述 WHAT，不描述私有 HOW；
+- 预期值来自字面量、手工算例、规范或已知正确夹具，不能用生产实现的同一算法重新计算；
+- 通过被测接口观察结果，不旁路查询内部数据库或私有状态；
+- 一个测试表达一个逻辑行为，但可以包含证明该行为所需的多个断言。
+
+## 垂直切片
+
+一个测试、一个最小实现、一次反馈。不要先批量写出所有测试再批量实现；水平切片会在理解真实实现前锁定想象中的结构。
+
+## 反模式
+
+- Mock 内部协作者或被测对象；
+- 测试私有方法、调用次数或内部顺序；
+- 同义反复地重算预期值；
+- 绕过公共接口验证内部存储；
+- 只覆盖 happy path，遗漏 Ticket 明确的错误与边界行为。

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

@@ -3,7 +3,7 @@ id: specdev/init-setup
 type: workflow-entry
 workflow: specdev
 name: 初始化设置
-description: 初始化 SpecDev 的语言、配置、全局状态、追踪约定、领域知识布局、验证命令和并发治理。
+description: 初始化 SpecDev 的语言、配置、全局状态、本地 change 追踪、领域知识布局、验证命令和并发治理。
 keywords: [初始化, 配置, status, tracking, 验证命令]
 ---
 
@@ -46,6 +46,8 @@ keywords: [初始化, 配置, status, tracking, 验证命令]
 - 共享高冲突路径的类型，例如根依赖清单、锁文件、全局导出、共享 schema、迁移索引和全局路由；
 - 项目中已有的提交、分支和发布约定。
 
+同时确认项目根 `.gitignore` 存在且包含 `specdev-worktree/`（`/specdev-worktree/` 视为等价）。该条目由 `speculo init` 单一维护；缺失时停止并提示用户以当前 Speculo 版本重新运行 `speculo init`，本 Work 不作为第二写入者修改它。
+
 ### 3. 询问不可发现偏好
 
 仅在上下文未提供时询问：
@@ -54,7 +56,6 @@ keywords: [初始化, 配置, status, tracking, 验证命令]
 - 是否允许自动提交；
 - 最大并发数；
 - Deep Ticket 的迁移、发布和不可逆操作是否必须人工批准；
-- 外部任务系统标签是否需要映射。
 
 不询问可由仓库事实回答的文件位置、脚本名或默认分支。
 
@@ -82,11 +83,12 @@ keywords: [初始化, 配置, status, tracking, 验证命令]
 - `<Path>{roots.state}/specdev/research/</Path>`
 - `<Path>{roots.state}/specdev/archive/</Path>`
 
+若全局状态已存在，先检查 `schema_version`。版本未知、JSON 不可解析或状态与当前 workflow 契约不一致时，停止当前 Work，并提示用户重新运行 `speculo init` 刷新受 Speculo 管理的状态；不得在 Work 内迁移、兼容或猜测旧状态。只有状态不存在时才从 schema v4 模板创建。
+
 从模板生成：
 
 - `<Path>{roots.workflows}/specdev/I-init-setup/tracking-template.md</Path>` → `<Path>{roots.state}/specdev/.config/tracking.md</Path>`
 - `<Path>{roots.workflows}/specdev/I-init-setup/domain-layout-template.md</Path>` → `<Path>{roots.state}/specdev/.config/domain-layout.md</Path>`
-- `<Path>{roots.workflows}/specdev/I-init-setup/status-labels-template.md</Path>` → `<Path>{roots.state}/specdev/.config/status-labels.md</Path>`
 
 已有永久知识不得被初始化过程清空。已有配置应先验证和展示差异，再按用户授权更新。
 
@@ -96,8 +98,9 @@ keywords: [初始化, 配置, status, tracking, 验证命令]
 2. 对照 `<Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path>` 与 `<Path>{roots.workflows}/specdev/common/schemas/status.schema.json</Path>`；
 3. 确认 `<Path>{roots.workflows}/specdev/I-init-setup/change-status-template.json</Path>` 的字段与 `<Path>{roots.workflows}/specdev/common/schemas/change-status.schema.json</Path>` 对齐；实际创建 change 时替换模板占位符后再执行 Schema 验证；
 4. 确认所有必需目录存在；
-5. 确认三个配置文档均已从对应模板生成；
-6. 运行：
+5. 确认两个配置文档均已从对应模板生成；
+6. 确认项目根 `.gitignore` 已忽略 `specdev-worktree/`；
+7. 运行：
 
 ```bash
 node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --self-check
@@ -105,17 +108,18 @@ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --
 
 ### 7. 更新状态并汇报
 
-在 `<Path>{roots.state}/specdev/status.json</Path>` 中记录本 work 的开始、完成时间和结果。向用户汇报：状态根、语言、验证命令、并发策略、人工批准策略和任何仍为 `null` 的配置项。
+若本 Work 由某个 active change 调用，开始时把该 entry 的 `current_work` 设为 `specdev/init-setup`，完成时将该 id 去重加入 `works_run` 并清空；纯工作流初始化没有 active change 时不创建虚假的 change。时间和验证结果写入本次回复或 change 自有 Evidence/LOG，不写入全局索引。向用户汇报：状态根、语言、验证命令、并发策略、人工批准策略和任何仍为 `null` 的配置项。
 
 ## 完成标准
 
 - `<Path>{roots.state}/specdev/config.json</Path>` 与 `<Path>{roots.state}/specdev/status.json</Path>` 可解析且满足 Schema；
 - 状态目录、永久知识目录和归档目录齐全；
-- 三个配置文档已就位；
+- 两个配置文档已就位；
 - 验证命令与并发规则有来源；
+- 项目根 `.gitignore` 已包含 `specdev-worktree/`；
 - 无敏感值被写入；
 - 包级自检无 error；
-- `<Path>{roots.state}/specdev/status.json</Path>` 已记录本 work 完成。
+- 存在调用 change 时，其 `works_run` 已包含本 work且 `current_work` 已清空；纯初始化时全局 active 保持真实为空。
 
 ## 子文件引用
 
@@ -124,4 +128,3 @@ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --
 - `<Path>{roots.workflows}/specdev/I-init-setup/change-status-template.json</Path>`
 - `<Path>{roots.workflows}/specdev/I-init-setup/tracking-template.md</Path>`
 - `<Path>{roots.workflows}/specdev/I-init-setup/domain-layout-template.md</Path>`
-- `<Path>{roots.workflows}/specdev/I-init-setup/status-labels-template.md</Path>`

package/template/workflows/specdev/I-init-setup/config-template.json

@@ -10,7 +10,7 @@
   "execution": {
     "max_parallel": 3,
     "deep_ticket_human_approval": true,
-    "shared_path_owner": "lead"
+    "shared_path_owner": "explicit"
   },
   "verification": {
     "test": null,

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

@@ -13,11 +13,11 @@
 
 ## 职责
 
-- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`：当前术语、不变量、概念关系和代码映射。
+- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`：当前 bounded context 的项目规范术语和 `_Avoid_` 同义词；不保存代码导航或 change 历史。
 - `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`：当前 change 已接受、被替代或废弃的架构决策。
 - `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`：设计讨论轨迹，不作为当前架构的最终权威。
 - `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`：用户问题、外部行为、范围与验收合同。
 - `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`：单个垂直切片的执行契约。
 - `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`：跨 Ticket 的门禁、调度和治理。
 
-change 完成后，只有仍真实、长期有效且有实现证据的知识才能提升到永久目录。
+change 完成后，只有仍真实、跨 change 有用且有实现证据的规范术语或符合三项准入条件的 ADR 才能提升到永久目录。

package/template/workflows/specdev/I-init-setup/status-template.json

@@ -1,7 +1,6 @@
 {
-  "schema_version": 3,
+  "schema_version": 4,
   "workflow": "specdev",
   "active": [],
-  "work_history": [],
-  "completed": []
+  "archived": []
 }

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

@@ -1,5 +1,7 @@
 # 变更追踪约定
 
+SpecDev 只使用本地 Markdown/JSON 工件跟踪开发。远程 Issue、URL 或指定内容必须先由 Triage 冻结为 `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`；远程状态、label、assignee 和 dependency 不替代本地 change、Ticket、Map、Goal Plan 或 Evidence。
+
 - change 根：`<Path>{roots.state}/specdev/changes/</Path>`。
 - 单个 change：`<Path>{roots.state}/specdev/changes/{change}/</Path>`，其中 `{change}` 使用 `<YYYY-MM-DD>-<kebab-topic>`。
 - 一个 change 表示一个可独立说明、实现、验证和归档的目标。
@@ -8,3 +10,4 @@
 - 工件状态应在同一次操作中同步，避免入口状态、Ticket 状态与 Map 状态漂移。
 - 完成条件：全部必需 Ticket 为 `done` 或有批准的 `cancelled`，证据齐全，无未批准 deviation，change 级验证通过。
 - 归档后的 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/</Path>` 默认只读；后续纠正通过新 change 和 supersedes 链完成。
+- 可关闭的远程来源在本地完成后由 Triage reconcile；`closed`、显式 `waived` 或 `not-applicable` 后才归档。