@namewta/speculo 0.3.0 → 0.3.2

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

@@ -0,0 +1,46 @@
+---
+artifact: wayfinder-map
+change: <YYYY-MM-DD-topic>
+status: active
+---
+
+# Wayfinder Map: <目标>
+
+- **共享地图：** `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
+- **调查目录：** `<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
+- **领取状态：** `<Path>{roots.state}/specdev/status.json</Path>`
+
+## 1. 最终目标与当前边界
+
+## 2. 调查清单
+
+| ID | Type | 问题 | 为什么高影响 | Blocked By | Owner/Claim | 状态 | Result |
+|---|---|---|---|---|---|---|---|
+| INV-01 | research | ... | ... | — | unassigned | open | `<Path>{roots.state}/specdev/changes/{change}/investigation/INV-01-<name>.md</Path>` |
+
+## 3. 调查 DAG
+
+```text
+INV-01
+  ├─→ INV-02
+  └─→ INV-03
+```
+
+## 4. 并行与领取规则
+
+- 最大并发来自 `<Path>{roots.state}/specdev/config.json</Path>`。
+- 当前领取集合以 `<Path>{roots.state}/specdev/status.json</Path>` 为权威。
+- 同一调查 Ticket 只能有一个 owner/session。
+- 共享地图是状态投影，领取变更后必须同步。
+
+## 5. 决策收敛
+
+| 未知项 | 当前结论 | 置信度 | 消费工件 | 是否仍阻塞 |
+|---|---|---|---|---|
+
+## 6. 停止条件
+
+- [ ] 所有高影响未知项已 confirmed、disproved，或明确转为用户/owner 决策。
+- [ ] 可以形成 Ready Spec、Ticket、诊断契约或架构决策。
+- [ ] 没有把产品实现留在调查 Ticket 中。
+- [ ] 所有 claim 已释放或转为明确 blocked。

package/template/workflows/specdev/_state/status.json

@@ -1,5 +1,5 @@
 {
-  "schema_version": 2,
+  "schema_version": 3,
   "workflow": "specdev",
   "active": [],
   "work_history": [],

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

@@ -0,0 +1,47 @@
+# SpecDev Common
+
+`<Path>{roots.workflows}/specdev/common/</Path>` 是 SpecDev 的共享治理层。所有 work 复用这里的规则、Schema、工具和 Skill，不在各自目录复制冲突版本。
+
+## 目录
+
+- 共享规则：`<Path>{roots.workflows}/specdev/common/rules/</Path>`
+- 工件 Schema：`<Path>{roots.workflows}/specdev/common/schemas/</Path>`
+- 自动化工具：`<Path>{roots.workflows}/specdev/common/tools/</Path>`
+- 可复用 Skill：`<Path>{roots.workflows}/specdev/common/skills/</Path>`
+
+## 规则权威
+
+- 工件职责与冲突裁决：`<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`
+- 规划原则：`<Path>{roots.workflows}/specdev/common/rules/planning-principles.md</Path>`
+- 规划深度与就绪：`<Path>{roots.workflows}/specdev/common/rules/readiness-and-depth.md</Path>`
+- 路径所有权：`<Path>{roots.workflows}/specdev/common/rules/path-ownership.md</Path>`
+- 证据与验证：`<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`
+- 偏差控制：`<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>`
+- 路径引用：`<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`
+- 代码注释：`<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`
+
+## 结构化工件 Schema
+
+- 全局配置：`<Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path>`
+- 全局状态：`<Path>{roots.workflows}/specdev/common/schemas/status.schema.json</Path>`
+- 单 change 生命周期状态：`<Path>{roots.workflows}/specdev/common/schemas/change-status.schema.json</Path>`
+- Spec：`<Path>{roots.workflows}/specdev/common/schemas/spec.schema.json</Path>`
+- Ticket：`<Path>{roots.workflows}/specdev/common/schemas/ticket.schema.json</Path>`
+- Tickets Map：`<Path>{roots.workflows}/specdev/common/schemas/tickets-map.schema.json</Path>`
+- Goal Plan：`<Path>{roots.workflows}/specdev/common/schemas/goal-plan.schema.json</Path>`
+
+## 工具与 Skill
+
+- 包与 change 校验器：`<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>`
+- 校验器说明：`<Path>{roots.workflows}/specdev/common/tools/README.md</Path>`
+- 外部技术研究 Skill：`<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`
+- 并行 Ticket worktree Skill：`<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`
+
+## 加载原则
+
+1. 入口 work 只加载当前步骤需要的共享文件。
+2. 共享规则是规范性要求；work 子文件只能细化，不得降低。
+3. Schema 检查结构，不替代事实核验、设计判断和用户批准。
+4. 工具只自动判断可判定条件；校验成功不代表需求、设计或实现正确。
+5. Skill 提供横跨 work 的可复用能力，不应把专属 work 职责吸收到公共层。
+6. 所有具体文件与目录引用都必须遵守 `<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`。

package/template/workflows/specdev/common/rules/artifact-contract.md

@@ -0,0 +1,57 @@
+# 工件职责与权威裁决
+
+SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个工件只承担自己的权威边界。
+
+## 1. 工件职责
+
+| 工件 | 具体位置 | 必须决定 | 不应决定 |
+|---|---|---|---|
+| 分诊 | `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>` | 请求类别、影响、风险、缺失输入和下一 work | 详细实现方案 |
+| 诊断 | `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</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>` | 已接受架构决策、原因、后果和替代关系 | 尚未决定的方案集合 |
+| Spec | `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` | 用户问题、外部行为、范围、验收合同、非功能要求和已锁定实现约束 | 文件级施工步骤 |
+| Ticket | `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>` | 单一垂直切片的行为、决策、范围、路径所有权、执行路线和验证证据 | 跨 Ticket 里程碑治理 |
+| Tickets Map | `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` | 依赖 DAG、合同覆盖、Ready 投影、并行候选和路径冲突 | 单 Ticket 的完整实现契约 |
+| Goal Plan | `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
+| Evidence | `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
+
+## 2. 权威顺序
+
+同一事项冲突时按下列顺序裁决：
+
+1. 用户最新明确决定；
+2. 当前已接受架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`；
+3. 当前外部行为权威：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`；
+4. 当前 Ticket 契约：`<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`；
+5. 当前跨 Ticket 编排：`<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`；
+6. 当前代码与运行事实；
+7. 旧计划、旧日志和未经确认的推断。
+
+代码事实可以证明计划已过时，但不能静默改写用户目标或已接受契约。出现这种情况时，按 `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>` 退回相应工件修订。
+
+## 3. 来源追踪
+
+高影响条目应带来源标识：
+
+- `USER-DECISION:<date-or-summary>`；
+- `ADR-###`；
+- `US-###` 或 `AC-###`；
+- `CODE:<Path>project/relative/path</Path>`；
+- `RESEARCH:<Url>https://example.com/source</Url>`；
+- `DIAG-###`。
+
+来源追踪解释“为什么这样决定”，不要求为普通描述逐句加标签。
+
+## 4. 冲突处理
+
+1. 指明冲突事项和双方来源；
+2. 判断冲突属于事实过时、产品取舍、架构取舍、Ticket 范围还是调度问题；
+3. 按本规则的权威顺序提出裁决；
+4. 若改变外部行为、公共契约、数据、安全、范围、迁移或验收，必须获得用户或指定批准人决定；
+5. 更新真正拥有该决策的工件；
+6. 在 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 保留被替代结论和原因；
+7. 重新运行 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>`。
+
+不得仅在下游工件中覆盖上游权威。

package/template/workflows/specdev/common/rules/code-commenting-rule.md

@@ -0,0 +1,39 @@
+# Code Commenting Rule
+
+注释只用于记录**代码本身无法清晰表达，但对正确使用或安全修改至关重要的信息**。
+
+## Requirements
+
+- 优先通过命名、类型、结构、断言和测试表达意图；不要用注释掩盖复杂或含糊的代码。
+- 公共 API 应说明调用契约，包括重要的输入限制、返回语义、错误、副作用、并发、所有权和安全要求。
+- 内部实现仅在必要时解释非显然的：
+  - 设计原因与取舍；
+  - 不变量；
+  - 顺序约束；
+  - 安全或并发风险；
+  - 兼容、迁移或 workaround 的原因与退出条件。
+- 单位、时区、精度、哨兵值、生命周期等无法由类型或名称表达时必须说明。
+- TODO 必须包含可追踪标识、具体动作以及完成或删除条件。
+- 修改代码行为时，必须同步检查并更新相关注释。
+
+## Do Not
+
+- 不要为每个函数或方法机械添加注释。
+- 不要逐行复述代码。
+- 不要解释名称和类型已经表达的信息。
+- 不要保留注释掉的旧代码。
+- 不要记录修改历史或临时开发过程。
+- 不要猜测“为了性能”“为了兼容”等设计原因。
+- 不要使用注释数量或覆盖率衡量质量。
+
+## Decision Rule
+
+添加注释前确认：
+
+1. 这条信息是否无法由代码清晰表达？
+2. 缺少它是否可能导致错误使用或错误修改？
+3. 它是否在正常重构后仍然有效？
+
+只有答案均为“是”时才添加注释。
+
+> 公共接口记录 Contract；内部实现记录非显然的 Why、Invariant 和 Risk。

package/template/workflows/specdev/common/rules/deviation-control.md

@@ -0,0 +1,43 @@
+# 偏差控制
+
+偏差是“当前事实或实现需要偏离已批准工件”的显式事件。偏差不是普通进度说明，也不能作为先改后补文档的许可证。
+
+## 1. 偏差等级
+
+- **local**：只改变局部实现，不改变 Ticket 的行为、范围、公共契约、路径所有权或验证；记录到 Evidence 后可继续。
+- **ticket**：改变 Ticket 的执行路线、可写范围、局部契约或验收映射，但不改变 Spec；必须停止相关修改、更新 Ticket 并获得 owner 或 Lead 批准。
+- **spec**：改变外部行为、范围、用户故事、验收合同或非功能要求；必须返回 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`。
+- **architecture**：改变已接受架构决策或公共架构约束；必须返回 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 并更新 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`。
+- **release**：改变迁移、兼容窗口、发布门禁、回滚或不可逆批准点；必须停止并获得明确人工批准。
+
+## 2. 触发条件
+
+以下任一情况必须建立偏差：
+
+- 当前代码事实使批准路线不可行；
+- 需要修改 Ticket 未授权的项目路径；
+- 需要修改 shared path，但当前实现者不是 owner；
+- 验证接缝无法证明验收合同；
+- 发现新的安全、数据、兼容、性能或迁移风险；
+- 依赖、合同或外部参考权威已变化；
+- 实际行为将与 Spec 或 ADR 不一致。
+
+## 3. 偏差记录
+
+偏差记录写入对应 Evidence：`<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`，并至少包含：
+
+- 偏差 ID 与等级；
+- 触发事实和证据；
+- 受影响工件与路径；
+- 继续、回退、修订或拆分的选项；
+- 推荐方案和风险；
+- 批准人、批准时间和批准范围；
+- 最终处理结果。
+
+需要改变上层工件时，Evidence 只记录事件；真正的权威变更必须写回对应 Spec、Ticket、ADR 或 Goal Plan。
+
+## 4. 停止规则
+
+- 未批准的 ticket、spec、architecture 或 release 偏差不得继续实现。
+- 不得通过扩大 `writable_paths`、删除测试、降低断言或把风险改写成“已知限制”来绕过停止。
+- 偏差影响并发 Agent 时，Lead 必须暂停受影响 Wave，重新计算路径所有权、依赖和 Gate。

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

@@ -0,0 +1,57 @@
+# 证据与验证规范
+
+验证回答“怎样证明行为已经正确发生”，Evidence 回答“实际运行了什么、结果是什么、仍有什么风险”。
+
+## 1. 验证矩阵
+
+每一行绑定一个行为、合同或风险：
+
+| 行为或风险 | 验证接缝 | 方法或命令 | 预期结果 | Evidence |
+|---|---|---|---|---|
+| 正常路径 | 公共接口 | 项目定向测试 | 指定外部行为成立 | `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` |
+| 无效输入 | schema 或公共接口 | 定向失败测试 | 稳定错误行为成立 | `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` |
+| 回归 | 现有测试套件 | 项目回归命令 | 相关既有行为保持 | `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` |
+
+命令引用项目脚本时，项目文件路径使用项目相对 Path 标签，例如 `<Path>package.json</Path>` 或 `<Path>Makefile</Path>`。
+
+## 2. 最小充分验证
+
+选择最接近目标行为的稳定接缝：
+
+1. 公共接口或契约集成测试；
+2. 稳定接缝上的单元测试；
+3. 类型检查、静态分析、lint 和构建；
+4. 可重复手动步骤、截图或查询结果；
+5. 代码阅读推断。
+
+E2E 仅在变更影响用户界面交互时加入验证矩阵，并且只由 Lead 在集成阶段执行。Worker 只记录场景、预期结果和待执行状态。API、CLI、后端、库或数据变更默认使用其稳定接缝，不追加 E2E。
+
+低层证据不能替代明确要求的用户行为证据。高风险迁移还需要 dry-run、调用点扫描、数据核对、监控信号或回滚演练。
+
+## 3. 失败分类
+
+每个失败必须分类为：
+
+- 本 Ticket 引入的新失败；
+- 基线已存在的失败；
+- 环境、权限或基础设施失败；
+- 验证本身无效或无法观察目标行为。
+
+不得通过跳过测试、放宽断言、吞错、删除用例或把命令移出验证矩阵来制造绿色。
+
+## 4. Evidence 最低内容
+
+每个完成 Ticket 在 `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` 记录：
+
+- 基线、分支或 worktree；
+- 实际修改的项目路径；
+- 每条命令、退出状态和结果摘要；
+- 每条验收合同的证据映射；
+- 未运行项与原因；
+- 新失败、既有失败和环境失败；
+- 偏差及批准；
+- 残余风险；
+- worktree、提交或 PR 引用；
+- 最终结论。
+
+无法运行关键验证、存在未批准偏差或 Evidence 不完整时，Ticket 不得标为 `done`。

package/template/workflows/specdev/common/rules/path-ownership.md

@@ -0,0 +1,35 @@
+# 路径所有权与并发规则
+
+路径所有权是并行执行的硬边界，不是文件预测清单。
+
+## 1. 四类路径
+
+- `expected_changes`：预计修改的项目路径，仅用于导航；每项写成项目相对 Path 标签。
+- `writable_paths`：实现者获准修改的项目路径或 glob，是硬约束。
+- `read_only_paths`：建立上下文但不得修改的项目路径。
+- `shared_paths`：多个 Ticket 可能需要修改的项目路径，必须指定唯一 owner。
+
+示例：
+
+```yaml
+expected_changes: ["<Path>src/auth/session.ts</Path>"]
+writable_paths: ["<Path>src/auth/**</Path>"]
+read_only_paths: ["<Path>src/users/**</Path>"]
+shared_paths: ["<Path>package.json</Path>"]
+```
+
+## 2. 所有权规则
+
+1. 可能并行的 Ticket，其 `writable_paths` 不得相交。
+2. glob 与具体路径按覆盖关系判断，不得只比较字符串。
+3. 根依赖清单、锁文件、根导出、共享 schema、迁移索引、全局路由和跨 Ticket 合同文件默认视为 shared。
+4. shared path 只能由 Lead 或专用 owner Ticket 修改；消费者 Ticket 只读。
+5. 需要越界时先停止，按 `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>` 提出 ownership change；不得先改后报。
+6. 前置 Ticket 改变目录结构后，后续 Ticket 开始前重新解析项目路径；若授权范围语义未改变，可只更新导航路径。
+7. 不得把“最后解决合并冲突”当作所有权方案。
+
+## 3. Worktree 与分支
+
+并行写代码的 Ready Ticket 使用隔离 worktree；只读调查和顺序执行默认共用当前工作区。Worktree 防止工作区污染，路径所有权防止逻辑冲突，两者不能互相替代。
+
+生命周期由 Lead 按 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>` 管理，编排规则位于 `<Path>{roots.workflows}/specdev/P-goal-plan/orchestration-protocol.md</Path>`。

package/template/workflows/specdev/common/rules/path-reference-contract.md

@@ -0,0 +1,116 @@
+# SpecDev 路径引用契约
+
+本规则是 SpecDev 中“文件、目录、工件与工具引用”的唯一规范。入口 work、子流程、模板、规则、Schema、Skill、工具说明和治理文档均必须遵守。
+
+## 1. 工作流目录中的引用
+
+引用 `<Path>{roots.workflows}/specdev/</Path>` 下的任何文件或目录时，必须写出完整根变量与完整相对路径：
+
+```text
+<Path>{roots.workflows}/specdev/<relative-path></Path>
+```
+
+正确示例：
+
+- `<Path>{roots.workflows}/specdev/I-init-setup/config-template.json</Path>`
+- `<Path>{roots.workflows}/specdev/P-goal-plan/orchestration-protocol.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/schemas/ticket.schema.json</Path>`
+- `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>`
+- `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`
+
+不得使用：
+
+- 裸文件名；
+- 相对路径；
+- 仅写目录名；
+- 指向内部文件的 Markdown 相对链接；
+- 省略 Path 标签的反引号路径。
+
+## 2. 状态目录中的引用
+
+引用 `<Path>{roots.state}/specdev/</Path>` 下的任何持久化工件或目录时，必须写成：
+
+```text
+<Path>{roots.state}/specdev/<relative-path></Path>
+```
+
+正确示例：
+
+- `<Path>{roots.state}/specdev/config.json</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`
+- `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/</Path>`
+
+目录引用必须以 `/` 结束；文件引用不得以 `/` 结束。
+
+## 3. 项目代码路径
+
+SpecDev 不假定运行时一定提供项目根变量。Ticket、Evidence、诊断与架构审查中的项目代码路径统一使用项目相对路径，并仍置于 Path 标签中：
+
+```text
+<Path>src/example/module.ts</Path>
+<Path>packages/example/**</Path>
+```
+
+禁止写入机器绝对路径。行号只能作为近似导航信息，不能成为长期契约。
+
+## 4. 外部来源
+
+外部网页或仓库 URL 使用 Url 标签：
+
+```text
+<Url>https://example.com/reference</Url>
+```
+
+外部 URL 不能伪装成 SpecDev 内部路径；内部文件也不能用 URL 代替完整 Path 标签。
+
+## 5. 工件名称与工件引用
+
+可以在概念层面写“Spec”“Ticket”“Goal Plan”“Evidence”。一旦语句指向具体文件、目录、模板、Schema、工具或状态工件，就必须给出完整 Path 标签。
+
+例如：
+
+- 概念：Ticket 是单一垂直切片的执行契约。
+- 具体引用：当前 Ticket 位于 `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`。
+
+## 6. 模板、代码块与机器可读文件
+
+路径规范同样适用于：
+
+- Markdown 表格；
+- YAML frontmatter 示例；
+- JSON 示例中的 SpecDev 工件值；
+- 命令代码块中的 SpecDev 输入或输出路径；
+- HTML 模板中的说明文本；
+- Skill 的持久化输出模板。
+
+命令需要真实运行时路径时，由执行环境解析 Path 标签内容；规范文件不得将根变量提前展开成机器绝对路径。
+
+以下机器协议字段不属于叙述性文件引用，可以保留其协议原生格式：
+
+- JSON Schema 的 `$schema` 与 `$id` URI；
+- Python、Shell 或其他工具源码中的模块名、常量、文件匹配模式和运行时路径运算；
+- 语言本身要求的 import、package、namespace 或协议标识；
+- 仅存在于进程内部、不会写入 SpecDev 工件的实现字符串。
+
+这些例外不得被用于绕过治理：一旦工具向 Markdown、JSON 状态或其他持久化工件输出具体 SpecDev 引用，输出值仍必须符合本契约。
+
+## 7. 引用与所有权是两件事
+
+完整 Path 只解决“引用对象是谁”，不授予修改权限。执行者必须同时遵守 `<Path>{roots.workflows}/specdev/common/rules/path-ownership.md</Path>` 中的 writable、read-only 与 shared owner 约束。
+
+## 8. 自动检查
+
+`<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的包级自检至少检查：
+
+- 工作流引用是否使用完整 `<Path>{roots.workflows}/specdev/...</Path>`；
+- 状态引用是否使用完整 `<Path>{roots.state}/specdev/...</Path>`；
+- 项目路径示例是否使用 Path 标签；
+- 是否存在指向内部文件的相对 Markdown 链接；
+- 工作流引用目标是否真实存在；
+- 是否仍引用已移除目录或文件；
+- Path 标签是否闭合；
+- 目录引用是否以 `/` 结束且文件引用是否不以 `/` 结束。
+
+路径检查通过仅表示引用结构正确，不代表工件语义、需求、设计或实现正确。

package/template/workflows/specdev/common/rules/planning-principles.md

@@ -0,0 +1,57 @@
+# 规划原则
+
+SpecDev 的规划目标是“决策完备、细节最小充分、能够验证”，不是把每个任务写成逐行施工脚本。
+
+## 1. 先探索，后提问
+
+先读取相关入口、配置、schema、类型、测试、相邻实现、当前工件和历史决策。未知项分为：
+
+- **可发现事实**：通过只读探索解决，不询问用户；
+- **高影响偏好或取舍**：无法从仓库推导，且会改变行为、架构、风险、范围、迁移或验收时才询问；
+- **低影响实现细节**：由实现者遵循现有惯例决定。
+
+外部事实研究使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。
+
+## 2. 决策完备
+
+一个 Plan 或 Ticket 达到以下状态才可执行：
+
+- 目标和成功标准明确；
+- IN、REUSE、OUT 与不变量明确；
+- 公共接口、数据和兼容策略已锁定或明确不变化；
+- 失败行为和关键边界有结论；
+- 依赖、路径所有权和批准点明确；
+- 验证方式和 Evidence 位置明确；
+- 不存在会改变上述内容的高影响未决问题。
+
+决策完备不要求逐文件穷举、逐函数步骤、逐行代码、重复代码库事实或虚构未来路径。
+
+## 3. 最小充分细节
+
+- 局部、低风险、沿用现有模式的切片使用 Lite。
+- 多文件或跨层垂直切片使用 Standard。
+- 公共契约、迁移、安全、不可逆操作、共享核心路径或复杂协作使用 Deep。
+
+详细条件位于 `<Path>{roots.workflows}/specdev/common/rules/readiness-and-depth.md</Path>`。
+
+## 4. 计划与执行分离
+
+规划阶段可以读取、搜索、静态分析和执行只读或非修改性验证，不实现产品代码。执行阶段不重新决定已锁定的产品和架构事项。计划与代码事实冲突时，按 `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>` 退回修订。
+
+## 5. 以可验证目标委托
+
+每个交付物至少有一种可重复证据：测试、类型检查、lint、构建、API 示例、截图对比、迁移 dry-run、查询结果或手动步骤。验证绑定外部行为或稳定接缝，不把私有实现细节当作唯一证据。
+
+## 6. 委托而非微操
+
+Ticket 告诉执行者：做什么、为什么、不能改变什么、按什么顺序形成安全落点、怎样证明。执行者决定：在现有代码惯例内怎样组织局部实现。只有高风险或非显然的接口、迁移和顺序需要写入执行路线。
+
+## 7. 分层规划
+
+- Spec 决定外部行为。
+- Ticket 是决策完备的微型执行计划。
+- Tickets Map 决定依赖和覆盖投影。
+- Goal Plan 只在协调复杂度需要时决定跨 Ticket 编排。
+- Implement 在既定契约内完成代码和 Evidence。
+
+职责细节见 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`。

package/template/workflows/specdev/common/rules/readiness-and-depth.md

@@ -0,0 +1,51 @@
+# 规划深度与执行就绪
+
+## 1. Planning Depth
+
+### Lite
+
+适用条件通常全部满足：范围局部、行为明确、沿用既有模式、无公共接口或数据迁移、无安全或高事故半径影响、易回滚、无需并行协调。
+
+最低内容：目标、范围、项目路径授权、1–3 条执行路线、验收标准和验证方法。
+
+### Standard
+
+适用于大多数跨多个文件或技术层的垂直切片。
+
+额外要求：锁定决策与假设、接口接缝、输入输出、不变量、失败行为、有序执行路线、验证矩阵和路径所有权。
+
+### Deep
+
+任一条件触发：公共 API、schema、wire format、数据迁移、认证授权、隐私、资金、不可逆操作、expand-contract、共享核心路径、多 Agent 复杂协作、多个实质架构方案或高事故半径。
+
+额外要求：数据流或状态转换、兼容窗口、迁移顺序、可观测性、回滚、风险缓解、收缩条件和人工批准点。
+
+## 2. Ticket Definition of Ready
+
+Ticket 只有同时满足以下适用条件才可设置 `ready: true`：
+
+- 外部行为和可观察产出明确；
+- IN、REUSE、OUT 无冲突；
+- 高影响决策已锁定；
+- 没有会改变行为、接口、数据、兼容、安全、范围或验收的未决问题；
+- 依赖存在且无循环；
+- `writable_paths`、`read_only_paths` 和 `shared_paths` 使用项目相对 Path 标签；
+- shared path 有唯一 owner；
+- 验收标准可判定；
+- 验证矩阵覆盖正常、失败和回归风险，或有可信的不适用理由；
+- Standard 或 Deep Ticket 有有序执行路线；
+- Deep Ticket 有迁移、兼容、监控、回滚和批准点，或逐项说明不适用；
+- 单个全新上下文可以完成，否则必须拆分。
+
+详细检查位于 `<Path>{roots.workflows}/specdev/T-tickets/ticket-readiness.md</Path>`。
+
+## 3. Spec Readiness
+
+`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` 只有在外部行为、范围、公共接口、数据、安全、兼容、迁移和验收合同不存在高影响未知项时，才可设置 `ready_for_tickets: true`。
+
+## 4. 假设规则
+
+- 低影响、可逆的默认值可以作为显式假设继续；
+- 高影响假设不得用于强行通过 Ready；
+- 实现者发现假设不成立时，按 `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>` 处理；
+- 假设必须有适用范围和验证方式。