@namewta/speculo 1.0.22 → 2.0.1

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

@@ -0,0 +1,170 @@
+# 实现
+
+
+本 work 保留模块设计检查、design-it-twice、TDD 红绿循环、双轴审查和证据治理。Ticket 模式按子 Goal Plan 或父 Implementation Plan 的 `ticket_workspace_policy` 选择 current workspace 串行直接父分支或独立 worktree candidate-merge；Lead 根据实际情况自行实现或动态派单。
+
+若当前 change 是未完成父 Implementation Map 的成员，必须读取 `<Path>{roots.workflows}/specdev/common/rules/parent-implementation-orchestration.md</Path>`、父 Map 与父 Plan。父 Plan 提供跨 change dependency/serialization、全局 workspace 策略、组合派单标识、implementation agent cap 和 integration queue；子 Goal Plan 只能增加子内 Gate，不能放宽或冲突。
+
+
+## 执行模式
+
+### Ticket 模式（默认）
+
+使用下节规定的输入顺序。父 Implementation Plan 存在时采用其 Lead、workspace/integration 与全局 Gate，即使子 Goal Plan 不存在；两者都有时必须一致。没有父计划沿用子计划；两者都没有时当前主会话作为 Lead，按 Direct Spec 的轻量边界执行，不猜测 worktree 策略。
+
+### Direct Spec 模式
+
+只有极小、局部、单一行为、低风险、可逆且无需 Ticket DAG 的工作，才可在用户批准后直接基于 Spec/ADR/CONTEXT 在 current workspace 执行。先确认目标、IN/OUT、唯一写入 owner、可写范围、关键不变量、验证和验收。出现公共 API/schema、迁移、安全、高风险、多个行为或并行需求时返回 T-tickets。
+
+### Documentation 分支
+
+Ready documentation Ticket 或获批 Direct Spec 需要维护项目文档时读取 <Path>{roots.workflows}/specdev/specdev-i-implement/references/documentation-procedure.md</Path>。继续执行下方全部适用预检、workspace、commit、双轴审查、Evidence 和完成步骤；仅纯说明变更的代码红绿循环由可运行示例/类型/链接/生成与事实验证替代。prompt/tool/CLI/UI 文案属于可见行为，不能按纯说明豁免。
+
+## 输入
+
+两种模式都必须读取：
+
+- 当前规格：存在独立 Spec 时读取它；合同允许的轻量模式读取 README scope/acceptance/verification 等价章节，拒绝双权威。
+- 实际执行策略及验证依据；存在 config 时只读取当前分支真实使用的设置，不以缺失 config 阻塞本地工作。
+
+Ticket 模式必须按以下顺序读取：
+
+1. `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 的总体实施背景和完整项目 Skill 读取矩阵；
+2. 矩阵中适用于 `ALL` 或当前 Ticket ID 的全部项目 Skill；
+3. 当前 Ticket `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`；
+4. 存在的 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`，以及父 Implementation Map 声明当前 change 时的父 Map/Plan。
+
+矩阵是发布时确认的最低必读集合，不是 allowlist。项目 Agent 指令或实际实现范围触发新的项目 Skill 时，先读取该 Skill、停止项目写入，由 Lead 更新 Tickets Map 并重新运行 tickets 校验后恢复。Direct Spec 模式必须读取用户对轻量执行合同和直接实现的明确批准。
+
+按存在情况读取：
+
+- 当前 change 架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- 当前 change 领域上下文：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- 当前 change 设计日志：`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+- 当前 change 诊断：`<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
+- 永久架构决策：`<Path>{roots.state}/specdev/adr/</Path>`
+- 永久领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
+
+UI 范围必读 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path> 和 <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path> 的批准版本；Ticket design_ref 与所需页面/AC 一致，Direct Spec 在轻量合同中保存等价绑定。无 UI 影响时不要求 DESIGN。
+
+永久目录可以为空，静默继续。当前 ADR/CONTEXT 缺失且实施需要对应决定时，返回 `<Path>{roots.workflows}/specdev/specdev-g-grill-with-docs/SKILL.md</Path>`；Spec、Ticket 或 Goal Plan 与代码事实冲突时按 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>` 返回真正 owner，不在实现中覆盖。
+
+Git 已处于 merge/rebase 冲突时，先加载 `<Path>{roots.workflows}/specdev/specdev-i-implement/references/merge-conflict-protocol.md</Path>`；不把冲突伪装成普通 TDD。
+
+## 流程
+
+### 1. 执行前预检与 workspace
+
+加载 `<Path>{roots.workflows}/specdev/specdev-i-implement/references/execution-preflight.md</Path>`。
+
+预检参考拥有 Ready、依赖证据、真实 Skill、计划版本、owner、权限、Git 状态与 workspace 的完整检查，不在此复写。
+
+通过预检后：`required` Ticket 以 `purpose=ticket, operation=create|restore` 调用 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`；`current` Ticket 确认当前 branch/HEAD/dirty 状态和单 writer。Lead 设置 Ticket 为 `in_progress` 并按策略登记 active worktree 或 current workspace 记录。Direct Spec 不创建虚假 Ticket/worktree 状态。
+
+**完成标准**：真实 workspace、基线、唯一 owners 和授权与预检一致；代码使合同失效时停止并返回上游 owner，current Ticket 严格串行。
+
+### 2. Lead 决定自行实现或动态派单
+
+Ticket 模式下，Lead 根据 Ticket 独立性、路径冲突、上下文、风险和平台能力决定。派单时读取 `<Path>{roots.references}/coordination/task-brief.md</Path>`。`current` 模式仍可派遣一个 实现执行者 写当前 workspace，但必须等待其返回、Lead 验收并形成 commit 后才进入下一个 Ticket；`required` 模式 实现执行者 绑定独立 Ticket worktree。Direct Spec 模式由 Lead 作为 current workspace 唯一写入 owner，不派遣 实现执行者 写入。
+
+- 实现执行者 同时取适用子 Goal Plan、父 Implementation Plan、实际存在的 config 和平台能力的共同上限；current 模式保持单 writer 串行安全不变量；Lead 参与实现时计入；
+- 父实现编排存在时，派单与返回都使用 `<member-change>::<ticket-id>`，并占用父 Plan 的 task/serialization/integration slot；
+- review/research/test-observation agent 不设置 SpecDev 数字上限，但保持只读；
+- implementation Packet 按策略绑定唯一 Ticket workspace 或 current workspace、checkpoint、Tickets Map、当前 Ticket 的项目 Skill 最低必读集合、路径、非 E2E 检查与 commit 返回；
+- 任务执行者 不写 SpecDev 工件、Evidence、父分支或 E2E 结果；
+- Lead 自行实现时仍遵循相同 worktree、commit 与返回事实合同。
+
+**完成标准**：current 模式只有一个 implementation owner 写当前 workspace；required 模式只有一个 owner 写当前 Ticket worktree；Direct Spec 只有 Lead 写 current workspace；所有 SpecDev 写入仍由 Lead 拥有。
+
+### 3. 设计检查
+
+加载 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`，检查模块、接口、类型、不变量、顺序/错误/性能语义、接缝、适配器、依赖分类、测试观察点和既有公共合同。
+
+存在多个不改变上层契约的局部设计时，可运行 `<Path>{roots.workflows}/specdev/common/rules/design-it-twice.md</Path>`。超出 Ticket 或改变产品/公共合同/数据/兼容/安全时，返回架构审查、Grill、Spec 或 Ticket owner。陌生外部依赖使用 research Skill。
+
+**完成标准**：局部设计与上层契约一致，稳定接缝和依赖策略明确。
+
+UI 的模板、视觉语言、共享组件及交互规则由批准 DESIGN 锁定；局部实现设计不能重新选风格。按页面/状态验收实现并在真实浏览器对照，设计本身无效时返回 P，行为冲突返回 S。
+
+### 4. TDD 红→绿垂直循环
+
+加载 `<Path>{roots.workflows}/specdev/specdev-i-implement/references/tdd-rules.md</Path>`、`<Path>{roots.workflows}/specdev/specdev-i-implement/references/tdd-test-design.md</Path>` 和 `<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`。纯说明文档按上方 documentation 分支验证；其余对每个验收行为或关键风险：
+
+1. 选择公共接口或稳定接缝；
+2. 编写因目标行为缺失而失败的测试/验证并确认失败原因；
+3. 只写足以通过当前测试的实现；
+4. 运行定向非 E2E 验证；
+5. 保存 red/green 事实并进入下一条窄切片。
+
+涉及外部依赖、隔离策略或已有 Mock 时，先读取 `<Path>{roots.workflows}/specdev/specdev-i-implement/references/tdd-mocking.md</Path>`，再决定是否复用真实接缝或替身。
+
+不得删除测试、放宽断言、吞错、永久跳过或只验证 Mock 调用次数来制造绿色。
+
+新增或修改代码注释时，先判断信息能否由命名、类型或结构表达，并同步维护受行为变化影响的既有注释。
+
+涉及错误、取消、并发或资源释放时，按 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path> 和 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path> 验证实际状态与清理完成。注册、Worker、CLI、配置和发布路径要覆盖真正入口；删除旧测试前核对全部风险承接，不因为新接口测试存在就删除。
+
+### 5. 实现检查、commit 与 Lead 接收
+
+Ticket 模式的 implementation owner 按 Goal Plan 策略在当前 workspace 或来源 worktree：
+
+- 运行 Ticket 要求的单元、组件、静态、类型、lint/build 等非 E2E 检查；
+- 审计 writable/shared/read-only 路径和新/既有/环境失败；
+- 在已授权时创建引用 Ticket ID 的实现 commit；current 模式 commit 直接落在父分支，required 模式落在 Ticket branch；
+- 返回 commit、dirty 状态、实际路径、命令/结果、未运行项和恢复条件。
+
+Ticket 模式中，Lead 读取 `<Path>{roots.references}/coordination/result-and-recovery.md</Path>`，重读 Git 状态、branch tip、commit、diff 和命令事实。无改动时将 Ticket 改为 `cancelled` 并记录原因；不得 empty commit 或 Evidence-only Done。required 模式来源 worktree 不运行 E2E；current 模式适用 E2E 留给 Lead 的 direct-parent 验证。
+
+Direct Spec 模式由 Lead 在 current workspace 运行轻量合同要求的定向非 E2E 检查，审计获批可写范围，并在获得 implementation commit 授权后创建引用 change 的非空 commit；无需改动时记录事实并取消直接实现，不创建 empty commit。记录实施前基线、最终 checkpoint、dirty 状态、实际路径、命令结果、未运行项和恢复条件。
+
+**完成标准**：required 模式 Ticket worktree clean 且 `source_checkpoint` 精确等于 branch tip；current 模式 workspace clean 且 Ticket `result_sha` 精确等于父分支上的 implementation commit；或 Direct Spec 的 current workspace checkpoint、路径和轻量合同一致。
+
+### 6. 双轴审查
+
+调用 `<Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`。required Ticket 以 `base_sha` 与 `source_checkpoint` 为固定点；current Ticket 以 Ticket 实施前基线与 implementation commit 为固定点；Direct Spec 以实施前基线与 current workspace 最终 checkpoint 为固定点：
+
+- 标准轴：正确性、模块设计、错误、安全、性能、并发、资源、测试与可维护性；
+- 规范轴：Spec/Ticket IN/OUT、实现合同、路径所有权、验证矩阵与 Goal Gate；UI 还包括已批准 DESIGN、固定基线和页面/状态规则。
+
+标准轴同时复核 `<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`：公共 API 契约完整，内部注释只保留非显然的 Why、Invariant 和 Risk，且相关注释与当前行为一致。
+
+两个轴隔离并按标准轴、规范轴顺序返回 Lead。局部 finding 在当前模式的实现 workspace 修正、创建新 checkpoint 并重跑；改变上层契约则登记 deviation。Ticket 进入 `review` 或 Direct Spec 进入最终验证前，两轴必须通过。
+
+### 7. 最终集成与适用 E2E
+
+`required` Ticket 模式中，Lead 以 `purpose=ticket, operation=finalize` 调用 dev-worktree，并读取 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/references/finalize.md</Path>`。该参考唯一维护最新父分支 candidate 的组合、检查、失败/漂移、重建、fast-forward、回读与尝试上限过程。验证失败或父 HEAD 漂移，父分支不推进；不能凭来源检查通过标记 Done。
+
+E2E 是否需要由 Ticket/Goal Plan 的实际跨边界风险决定，不限于 UI；不适用必须记录原因。
+
+`current` Ticket 模式跳过 source worktree、candidate merge 和 candidate checkout。Lead 在当前 workspace 运行 Ticket 要求的适用集成/回归与 E2E，记录运行环境、命令、退出码和摘要；E2E 不得派给其他 agent。失败时不声明完成，保留 Ticket commit、父 HEAD 和恢复条件。全部通过后重读父 HEAD/tree 并记录 `result_sha`。Direct Spec 模式同样跳过 source worktree、candidate merge 和父分支推进。
+
+无论失败发生在 implementation、review、direct-parent 还是 parent-candidate，同一 Ticket 反复返回相同 blocker、下一轮没有产生新证据，或 integration attempts 达到有效 Plan 上限时，都停止自动退回原 implementation owner。Lead 保留当前 workspace/worktree、implementation/source commit、旧 candidate 和失败命令，在 Ticket Evidence 记录失败历史，并将 Ticket/worktree 标为 `blocked`。当前 change 属于父实现时返回父 O Lead；否则返回 Goal Plan Lead，或无 Goal Plan 时的当前 I Lead。Lead 按 lead-orchestration 完成最小复盘并形成有实质变化的新 Dispatch Packet 后，才可重置 attempts 和重新派发；契约已失效则返回真正 owner。
+
+### 8. Evidence、状态与完成
+
+Lead 使用 `<Path>{roots.workflows}/specdev/specdev-i-implement/assets/evidence-template.md</Path>` 写入 Ticket Evidence；Direct Spec 按该模板的 Direct Spec 适配说明写 `<Path>{roots.state}/specdev/changes/{change}/evidence/direct-spec.md</Path>`。Ticket Evidence 按策略记录 implementation/source、适用 candidate/result SHA、派单/返回、两层验证、双轴审查、E2E disposition、路径审计、失败历史与适用 Lead 复盘、偏差和残余风险；Direct Spec Evidence 使用实施前基线与 current workspace 最终 checkpoint，不伪造 Ticket/worktree/candidate 字段。
+
+UI Evidence 必须包含 `## Design Conformance`，列出 design_ref 的准确 digest、pages 与 acceptance ID，逐项连接实现位置、真实浏览器任务、桌面/窄屏截图和状态观察。对照批准原型说明允许的实现差异；未知与未通过项保持未验证，不能仅凭原型证据完成实施。
+
+Ticket 正常状态：`ready → in_progress → review → done`。`required` 的 `done` 要求 change worktree 已完成集成（`integrated` 或 `removed`）、父 HEAD=result SHA 且包含 source commit；`current` 的 `done` 要求 current workspace clean、direct-parent 验证通过且父 HEAD=result SHA。阻塞使用 `blocked`，契约偏差使用 `deviated`，无需改动使用 `cancelled`。Direct Spec 由当前 I-implement owner 按 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>` 关闭 change。
+
+按实际存在的负责位置更新：Ticket/Evidence 拥有本票进度，Goal 拥有整体 Gate 与集成，Map/README 只导航；轻量输入把当前清单与验证写原 README，Direct Spec 不创建缺失的 Ticket/Map/Goal Plan。最后一个计划内 Ticket 完成后，Goal Plan 的 Lead 按 change completion 关闭；无 Goal Plan 的当前 I owner 承担同一门禁。需要远程 reconcile 或把已完成 Ticket 投影为 GitHub Issue 时返回 T-triage，否则进入 Archive。
+
+当前 change 属于未完成父实现 change 时，单个组合 Ticket 完成、阻塞或触发 Lead 复盘，且子状态与 Evidence 已写入后，必须自动返回 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/SKILL.md</Path>`，由父 Lead 重读全部成员并决定重新派发、返回上游或继续下一 frontier；不得要求用户逐个重新激活，不得直接归档子 change，也不得从本 Work 实现另一个成员。
+
+运行：
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
+  --stage implement \
+  --repo <project-root> \
+  <Path>{roots.state}/specdev/changes/{change}</Path>
+```
+
+### 9. 返回
+
+Ticket 模式返回 Ticket 状态与 README Outcome、Evidence 完整路径、workspace locator、implementation/source、适用 candidate/result SHA、父分支、E2E disposition、适用 Lead 复盘决定、未验证项和下一路由。Direct Spec 返回 README Outcome、`<Path>{roots.state}/specdev/changes/{change}/evidence/direct-spec.md</Path>`、current workspace、实施前/最终 checkpoint、适用 E2E 和下一路由。push、PR、remote merge、deploy、migration、生产动作及来源 branch/worktree cleanup 只在独立授权时执行。
+
+## 计划型票扩展
+
+实施前按 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>` 执行绑定；恢复或上游变化按 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/replan-and-recovery.md</Path>` 核验。不以读取替代调用，不因他人任务冲突暂停独立已授权工作。

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

@@ -0,0 +1,21 @@
+# Merge / Rebase Conflict Protocol
+
+只在 `git status` 证明仓库正处于 merge/rebase 冲突时加载。
+
+## 流程
+
+1. 读取 Git 状态、操作类型、冲突路径、base/ours/theirs SHA、Ticket/Evidence 与匹配的 candidate integration 记录。
+2. 从 commit、source、Spec、Ticket、ADR、测试和调用者追溯双方意图；信息不足时不猜产品行为。
+3. 对每个 hunk 写出双方意图、共同约束和唯一可推导结果；需要新行为或上层决定时停止并登记 deviation。
+4. 在授权路径内解决文本，运行受影响的非 E2E 检查；candidate checkout 中按 finalize 合同运行父状态检查/E2E。
+5. 匹配的 local candidate integration 授权包含 `git add`、candidate merge commit、必要的 `git merge --abort` 和 transient candidate checkout/branch 生命周期；不扩展到来源 branch/worktree cleanup 或远端动作。
+6. 需要改变 Spec/ADR、安全/迁移决定、越过 owner 或无法同时保持既有意图时，在 Lead-created candidate 中执行 `git merge --abort`，记录 blocker 并保留来源 worktree；未知普通冲突现场不擅自 abort。
+7. 重读 Git 状态、parents 与 diff，确认无 marker、无未声明路径、双方合同及验证仍成立。
+
+## 完成标准
+
+- 每个 hunk 可追溯到既有意图；
+- 新产品决定没有藏在冲突解决中；
+- 验证记录命令、运行环境、退出码和摘要；
+- Git 副作用来自明确的 candidate integration 或其他逐动作授权；
+- 完成/暂停可以从 Git、原计划/README 与 Evidence 恢复。

package/template/workflows/specdev/specdev-i-implement/references/tdd-mocking.md

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

package/template/workflows/specdev/specdev-i-implement/references/tdd-rules.md

@@ -0,0 +1,25 @@
+# TDD 红绿规则
+
+1. 从 Ready Ticket/Spec 选择下一条最小可观察行为，并写下已确认 seam。
+2. 只为该行为编写一个会因目标能力缺失而失败的测试或验证。
+3. 运行并观察红灯；失败原因必须是目标行为缺失，而不是语法、夹具或环境错误。
+4. 只写使当前测试通过的最小生产代码，不预测后续切片。
+5. 运行定向测试并观察绿灯，记录命令与结果。
+6. 进入下一条窄垂直切片；周期性运行受影响回归。
+
+重构不属于红绿循环。全部目标行为完成并经过双轴 review 后，才进入独立修正/重构阶段，并重跑受影响 review 轴与验证。
+
+## 完成门
+
+- 每个切片有对应 red 和 green 证据；
+- 一个循环只有一个 seam、一个测试和一个最小实现；
+- 测试没有通过删除、跳过、吞错或放宽断言制造绿色；
+- review 前没有以“顺手重构”扩大切片。
+
+## 强制变异验证
+
+使用强制变异时，先保存基线 hash/diff，修改后核对实际执行文件的 diff 与测试选择。只有预期行为断言 red 才有效；编译错误、错测或变异未落地均不计。恢复原内容、复跑基线并核对 diff，把全过程记入 Evidence。诊断协议见 <Path>{roots.workflows}/specdev/specdev-d-diagnose-bugs/SKILL.md</Path>。
+
+## 纯说明与测试承接
+
+纯文档按 <Path>{roots.workflows}/specdev/specdev-i-implement/references/documentation-procedure.md</Path> 执行适用验证，不伪造代码红绿；prompt/tool/output 改动仍属行为。旧测试删除必须覆盖其行为、错误、兼容和回归义务，具体按 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path>。

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

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

package/template/workflows/specdev/specdev-i-init-setup/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: specdev-i-init-setup
+description: "发现项目事实与必要偏好；仅在明确请求时建立当前工程 docs 基线，不预造业务状态骨架。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/init-setup
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# 初始化设置
+
+读取 <Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path>，按 <Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path> 定位相关条目，明确项目、方法和数据根；直接使用无需 workspace 或 CLI。已有安装验证真实 roots，冲突只阻塞有关写入。普通 Work 不必先经过本入口。
+
+## 流程
+
+1. 只读探测包管理、workspace、构建/测试/类型/lint/CI、默认父分支、实际 worktree 与项目指令；定位真实入口和共享高冲突资源。未知验证命令保持未知，不凭框架名称编造。
+2. 区分可用、未安装、未配置、未授权、不适用并注明依据。复用用户语言、工具、产物数量及已有配置；只问无法从仓库得到且实际影响当前任务的偏好。探测不自动安装依赖、发布或创建虚假 change。
+3. 实际需要写入偏好或工具配置时读取 <Path>{roots.workflows}/specdev/specdev-i-init-setup/references/first-setup.md</Path>。已有真实 GitHub/验证配置继续使用其 schema，不删除未知独有字段。无需求不创建 config、tracking、domain-layout、空知识目录、全局 status 或 change status。
+4. 仅明确要求工程文档基线/全面理解代码时，直接使用 <Path>{roots.references}/writing-for-agents/references/current-facts-docs.md</Path> 的六步与覆盖表。最小 docs README/architecture 或已有负责正文导航，说明 HEAD/未提交或非 Git 范围、覆盖/未知/排除与实际验证；不改永久知识、不推进 docs-sync 基线。
+5. 回读本次实际写入，报告已确认事实、必要偏好来源、验证命令/退出码和未知。只读调用无文件；有 change 的结果写回原 README/Evidence，不登记 Work 调用镜像。
+
+## 停止与保全
+
+未知 schema、旧活动或混合协议保留原件并交显式转换，不从初始化偷偷迁移。CLI 安装元数据与 back 不归本 Work。已有知识、用户配置和历史不覆盖；只读发现不证明方法已安装或业务已验收。
+
+只有确实创建 worktree 时核对 `specdev-worktree/` 的忽略项与 owner：已安装的 CLI-managed 忽略项交 CLI 修复；直接模式按项目 owner 的真实授权维护，不能因没有 CLI 阻塞其他初始化事实发现。
+
+## 可选项目编排选择
+
+只有用户要求持久化编排偏好时，依据 <Path>{roots.references}/coordination/project-facts.schema.json</Path> 写入 <Path>{roots.state}/coordination/project.json</Path>，先读 <Path>{roots.references}/coordination/coordination-contract.md</Path>。配置缺失默认 Lead；不探测、安装或要求外部工具，选择不是授权凭证。只读调用不生成配置。

package/template/workflows/specdev/specdev-i-init-setup/assets/change-readme-template.md

@@ -0,0 +1,32 @@
+# <本次目标>
+
+Outcome: active
+
+<a id="scope"></a>
+## 目的与范围
+
+<当前单一目标、授权写集、IN/OUT、真实请求出处和约束。独立 <Path>{roots.state}/specdev/changes/{change}/spec.md</Path> 已负责规格时删除本模板 scope/acceptance/verification 并改为导航，不维护两套权威。>
+
+<a id="acceptance"></a>
+## 验收
+
+- [ ] AC-1：<可观察、可判定行为及验证方式>
+
+## 当前工作
+
+<简单任务清单与接续点；若使用无票 Goal 或独立 Ticket，则这里只导航其负责清单，不复制进度。>
+
+<a id="verification"></a>
+## 验证依据
+
+<尚未执行时如实描述缺口，不预填 passed。完成后每 AC 一个实际结果行：>
+
+| AC | Result | Evidence |
+|---|---|---|
+| AC-1 | <实际结果> | <#独立证据锚点或对象内文件 locator> |
+
+<需要校验原件摘要时可增加 SHA256 列，填写实际计算结果；非必需。真正执行后才在独立证据段记录 Method、Source、Observed、Result；有 Command 须有真实 Exit。>
+
+## 下一步
+
+<下一 owner、入口、阻塞与恢复限制；没有实际交接不建空 ownership/批准槽。>

package/template/workflows/specdev/specdev-i-init-setup/assets/config-template.json

@@ -0,0 +1,31 @@
+{
+  "schema_version": 7,
+  "interaction_language": "zh-CN",
+  "artifact_language": "zh-CN",
+  "git": {
+    "default_branch": null
+  },
+  "execution": {
+    "max_concurrent_implementations": 3,
+    "max_integration_attempts": 3,
+    "deep_ticket_human_approval": true,
+    "shared_path_owner": "explicit"
+  },
+  "verification": {
+    "test": null,
+    "typecheck": null,
+    "lint": null,
+    "build": null
+  },
+  "planning": {
+    "default_depth": "standard",
+    "require_ready_gate": true,
+    "require_evidence": true,
+    "ui_design_default_candidates": 3,
+    "ui_design_max_candidates": 4
+  },
+  "github": {
+    "include_external_prs": false,
+    "labels": {}
+  }
+}

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

@@ -0,0 +1,29 @@
+# 领域文档布局
+
+## 按当前问题定位
+
+1. 永久领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
+2. 永久架构决策：`<Path>{roots.state}/specdev/adr/</Path>`
+3. 当前领域上下文：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+4. 当前架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+5. 当前 Spec：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+6. 当前 Ticket 目录：`<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+7. 当前 Goal Plan：`<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
+8. 当前设计日志：`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+
+UI 范围先按 scope/规则 ID 定位 <Path>{roots.state}/specdev/design/</Path>，再读取 <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path> 固定的 baseline revision 与批准原型；不展开无关设计规则。
+
+## 职责
+
+- `<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}/DESIGN.md</Path>：当前 change 的已批准视觉/交互合同，P 拥有；原型包只拥有源码和证据。
+- <Path>{roots.state}/specdev/design/DESIGN.md</Path>：A 网关拥有的项目设计基线；仅在批准的首次发布时创建，不预造空目录。
+- `<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 有用且有实现证据的规范术语、合格 ADR 或可复用设计规则才可由 A 提升。首次设计 approved-intent 基线在 HTML 集中确认后经 A 设计网关发布，不能宣称已实现；具体遵循 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path>。
+
+当前工程事实按主题读取 <Path>{roots.state}/docs/README.md</Path> 的负责正文导航；缺失不阻塞普通 Work，只有明确请求才建立基线。

package/template/workflows/specdev/specdev-i-init-setup/assets/tracking-template.md

@@ -0,0 +1,13 @@
+# 变更追踪约定
+
+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 表示一个可独立说明、实现、验证和归档的目标。
+- <Path>{roots.state}/specdev/changes/{change}/README.md</Path> 顶层唯一 Outcome 表示整体 active/completed/cancelled；归档由实际目录位置与回执表示。
+- Ticket 文件是 Ticket 状态权威；`<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 只作导航、依赖和覆盖图，不复制进度。
+- 简单任务由 README 清单负责；无票 Goal 由计划清单负责；有票由 Ticket/Evidence 负责，其他位置仅导航。
+- 完成条件：全部必需 Ticket 为 `done` 或有批准的 `cancelled`，证据齐全，无未批准 deviation，change 级验证通过。
+- 归档后的 `<Path>{roots.state}/specdev/changes/archive/{change}/</Path>` 默认只读；后续纠正通过新 change 和 supersedes 链完成。
+- 可关闭的远程来源在本地完成后由 Triage reconcile；`closed`、显式 `waived` 或 `not-applicable` 后才归档。完成后若要把 Ticket 记到 GitHub，由 T-triage publish 写入 `<Path>{roots.state}/specdev/changes/{change}/publish.md</Path>`；`pending`/`publish-failed` 不可归档。尚未成 Change 的记事项由 T-triage capture 写入 `<Path>{roots.state}/specdev/capture.md</Path>`（缺失合法），Issue 保持 open，不创建 change。发布计数与 inbox 计数都以对应本地账本为准，标签词表见 T-triage classification-map。远程 Issue 仍不是开发权威。

package/template/workflows/specdev/specdev-i-init-setup/references/change-record-examples.md

@@ -0,0 +1,62 @@
+# 按需 owner、验证与取消记录
+
+只在相关动作需要可回读证据时采用；不是每 Work 的默认表单。占位文本不是实际证据，也不创造批准。
+
+## 简单任务的原 owner
+
+无 Goal 时，README 可用以下段落绑定实际会话依据。复杂任务使用原 Goal/Implementation Plan 的 lead，不再复制：
+
+```markdown
+## Ownership
+
+Owner: session:actual-locator
+Evidence: #handoff
+
+<a id="handoff"></a>
+## 本次会话依据
+
+Session: session:actual-locator
+Source: 用户请求或真实交接的可回读来源
+Observed: 实际接受的目标、范围和当前负责关系
+```
+
+需要绑定 P bootstrap 时，Ownership 与原会话依据都保存 `Work: specdev/prototype`；仅此实际动作需要，不逐 Work 更新镜像。Evidence 不得指回 Ownership 自身。
+
+## 真实验证后记录
+
+```markdown
+<a id="verified-ac-1"></a>
+## AC-1 观察
+
+Method: 实际使用的验证方法
+Source: 被检验源码/工件与实际输入的 locator
+Observed: 实际输出、结果与覆盖边界
+Command: 确实执行的命令（未执行命令则省略本项）
+Exit: 0
+Result: passed
+```
+
+README verification 的 AC-1 行引用 `#verified-ac-1`；可以引用原 Evidence 的对应段。不以声明 passed 替代真实运行；提供 SHA256 时工具严格匹配原件字节，缺摘要能力不编造值。
+
+## 整体取消
+
+用户确实取消后，保留独立原请求/交接依据，再按原完成 owner 核对下面字段。实际无某项时写有理由的 none，尚未知不能写 resolved。
+
+```markdown
+<a id="cancellation"></a>
+## 取消说明
+
+Source: #actual-cancellation-request
+Scope: 实际取消范围
+Time: 2026-10-14T10:00:00+08:00
+Confirmed-By: session:actual-locator
+Undelivered: 尚未交付的需求
+Landed: 已落地代码、数据、设计与远程影响
+Writers: none: 实际核验没有活动写入者的依据
+Dependencies: none: 没有父子依赖的依据
+Checkpoints: resolved: 未集成 checkpoint/candidate 的实际处置
+External: waived: 已承诺外部动作经具体决定放弃的依据
+Next: 后续 owner、保留材料和恢复限制
+```
+
+Writers 有过实际写入者时用 `stopped: <证据 locator>`，原件须有 `Writers: stopped` 和真实 Observed；超时不是停止。Dependencies/Checkpoints/External 允许 none/resolved/transferred/waived，但都要具体依据。全部核对通过后才将唯一 Outcome 改 cancelled，不批量改票、不回滚或关闭远程。

package/template/workflows/specdev/specdev-i-init-setup/references/first-setup.md

@@ -0,0 +1,11 @@
+# 必要偏好与真实工具配置
+
+只有当前任务确需持久化偏好或工具设置时读取；不是缺少文件即补全骨架。
+
+语言、用户工具和明确产物数量复用当次请求或现有项目说明。实现并发、worktree、集成尝试上限只在原 Goal/Implementation Plan 真正启用时明确，由计划 `## Execution Policy Source` 记录实际来源；默认 current 单写入者。Lead 自己实现计入实现并发，只读协作者不设新数字上限。UI 缺省 3、配置 2–4、用户明确数量覆盖上限；一次 override 留当前设计包，不改全局偏好。
+
+现有 <Path>{roots.state}/specdev/config.json</Path> 中 GitHub labels/include_external_prs、验证/planning 等真实消费者配置，可按 <Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path> 验证和保留；只有确需该工具时才创建，必要结构参考 <Path>{roots.workflows}/specdev/specdev-i-init-setup/assets/config-template.json</Path>。不把旧配置整份机械改写为 config.md；未知独有字段保留并报告。无标签只阻塞相关远程写入。
+
+任何配置更新先核对实际差异和授权，不保存秘密或凭据，不存全局自动 commit/集成/发布开关。未知验证命令为 null/未知，必须有仓库或真实用户来源。既有无效/未知 schema 不重置、不迁移；显式转换由原 owner 执行。
+
+change/ADR/context/docs/archive/design 等只在真实首次内容写入时创建；不生成 status、change status、空知识树、空批准槽或跟踪镜像。项目说明确需导航时可使用 <Path>{roots.workflows}/specdev/specdev-i-init-setup/assets/tracking-template.md</Path> 与 <Path>{roots.workflows}/specdev/specdev-i-init-setup/assets/domain-layout-template.md</Path> 的相关内容，不要求输出两份配置文档。工程 docs 基线由入口的共享事实方法负责。

package/template/workflows/specdev/specdev-l-learn-change/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: specdev-l-learn-change
+description: "在开发完成后围绕当前 SpecDev change 回答问题，并用面向零专业背景读者的 Markdown 与 ASCII 图解持续记录理解。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/learn-change
+  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 已验证的实现与测试事实，不作产品/架构决定或授予实现权限。
+
+## 执行
+
+1. **选择现有 change**：使用用户指定或唯一未归档 change；没有时返回缺失输入，不创建空 change。只读归档不追加学习材料。恢复依据留原学习索引与当前 README 导航；不把 completed/cancelled 重新打开为开发中。
+2. **确定主题**：使用 `$ARGUMENTS` 调用参数或用户最新问题；缺少时只询问主题。读者是刚入大学、零专业背景的新生，先确定“它是什么、为什么需要、怎样流动或被调用”三个答案。
+3. **定位事实**：按主题读取 Source、Spec、Ticket、Evidence、review、实际代码/测试与可靠来源。区分已验证事实、类比与未知；旧计划和实现冲突时明确差异，以当前代码、测试、Evidence 为实现事实，不让类比代替证据。
+4. **生成与保存**：读取 `<Path>{roots.workflows}/specdev/specdev-l-learn-change/references/lesson-format.md</Path>` 的完整格式和命名合同。先画 ASCII 全图，再按实际关系画短小结构/数据/调用/状态图；用短句解释箭头，术语先日常解释再给专业名字。验证零背景读者能复述三个答案；不能时拆图或换词，不灌长文。
+5. **追加而非覆盖**：从 `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 及同目录真实图解的最大编号取下一号；先原子创建 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>` 新图解，再更新索引并回读。重讲同主题仍新增编号，保留旧文件、原顺序和全部历史行。产物仅为纯 Markdown/ASCII，不生成 HTML、CSS、SVG、图片或浏览器依赖，不写 `<Path>{roots.state}/learning/</Path>`、生产代码、永久知识或远程系统。
+
+## 事实、理由与解释
+
+图解中明确已验证实现事实、可定位设计理由、教学类比与未知。讲解失败或恢复时引用实际契约与证据，不编造事故；旧计划与现状不同要指出差异，不把提案当事实。重新讲同主题仍追加新编号，不覆盖历史，不改 Learning workflow，也不把理解总结直接晋升永久知识。
+
+## 验收与恢复
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --stage learn-change <Path>{roots.state}/specdev/changes/{change}</Path>
+```
+
+图解符合格式参考的四节、至少一个 ASCII 图和连续编号；索引指向真实新文件且主题/简介一致，箭头方向与事实相符。验证通过后回读并返回新图解和索引完整路径，必要接续留原学习载体。失败保留恢复位置与原因，不改变 change 原有开发完成状态。

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

@@ -0,0 +1,51 @@
+# Change 学习图解格式
+
+写图解与分配编号时读取；这是产物格式权威，不是另一套学习状态。
+
+## 输出格式
+
+在当前 change 的 `<Path>{roots.state}/specdev/changes/{change}/learning/</Path>` 内原子写入一份新的 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>`，并原子更新索引 `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>`。这些产物属于 SpecDev change，不写入 `<Path>{roots.state}/learning/</Path>`。文档必须是纯 Markdown，不生成 HTML、CSS、SVG、图片链接或浏览器专属交互。
+
+`<number>` 是两位起始、持续递增的序号：先读取索引和同目录已有的图解文件，取最大序号加一，因此第一次为 `01`，下一次为 `02`；不为旧文件重编号。`<topic>` 是主题的简短、可作文件名的标签，可使用中文、字母、数字、`-` 或 `_`，但不能含空格、`/`、`\\` 或 `..`。同主题再次解释也创建新编号文件。
+
+索引是唯一目录，使用下列 Markdown 表格；每新增一份图解就在表末追加一行，并保留既有行。文件列只写同目录的文件名：
+
+```markdown
+# Change 学习图解索引
+
+| 编号 | 文件 | 主题 | 简介 |
+| --- | --- | --- | --- |
+| 01 | 01_<topic>.md | <主题> | <一句话说明它解释什么> |
+```
+
+按主题选择最贴切的图，但优先用多个短小 ASCII 图代替长文字：
+
+```text
+结构图：
+[系统]
+  |
+  +-- [部件 A]
+  +-- [部件 B]
+
+数据流图：
+[输入] -> [处理] -> [结果]
+
+调用流图：
+[用户动作] -> [入口] -> [服务] -> [回应]
+
+状态变化图：
+[等待] -> [进行中] -> [完成]
+```
+
+每份图解至少包含以下四节：
+
+1. `## 先看全图`：一个能说清“谁和谁有关”的 ASCII 图。
+2. `## 一步一步看`：按箭头顺序解释。流程、数据或调用会移动时，再给对应的 ASCII 图。
+3. `## 术语小词典`：只保留读图必需的词。每个词先用日常语言解释，再给它的专业名字。例如：`临时便签（缓存）`，意思是“把常用结果先放在手边，下一次不用重新找”。
+4. `## 你现在能复述什么`：用短句归纳“它是什么、为什么需要它、它怎样流动或被调用”。
+
+图中的方框名称使用普通名词和动词，不用缩写；箭头必须有方向。一个图只讲一个问题。确有边界、失败或例外时，单独画一张小图说明，不把它塞进主图。
+
+## 解释依据
+
+在原四节中区分已验证事实、可定位理由、教学类比与未知；需要时用原 ASCII 图展示失败和恢复方向。旧 Spec 与实现不一致时说明差异；新理解追加编号，不改旧文件，不增加其他格式产物。