@namewta/speculo 1.0.2 → 1.0.4

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

@@ -27,3 +27,7 @@ status: active
 ## 超出范围
 
 <!-- 被裁定在目的地之外的工作；已关闭，永不升级。 -->
+
+## Change 边界入口
+
+存在多个候选 change 时，W 创建并按需读取 `<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>`；地图不复制其中的候选或子状态。每个目标 change 的 Grill/Spec/Ticket 独立拥有，交接规则见 `<Path>{roots.workflows}/specdev/W-wayfinder/references/initiative-discovery.md</Path>`。

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

@@ -49,7 +49,7 @@
 - 校验器说明：`<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>`；仅 required Ticket 使用 source → parent-candidate → parent 状态机，current Ticket 使用 current workspace/direct-parent
-- 动态 Agent 交付合同 Skill：`<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`；P-goal-plan 可建立子 change Lead 合同，I-implement 在执行期派单与验收，父实现编排存在时受 O-orchestrate-implementation 的全局门约束
+- 动态 Agent 交付合同 Skill：`<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`；P-goal-plan 可建立子 change Lead 合同，I-implement 在执行期派单与验收，Goal 编排的全局门约束
 - 双轴代码审查 Skill：`<Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`
 
 ## 加载原则

package/template/workflows/specdev/common/rules/activation-and-memory.md

@@ -5,16 +5,20 @@
 ## Locate before read
 
 1. 先解析当前 workflow 的 roots、状态索引和稳定 ID；不存在时静默跳过，不能凭旧路径猜测。
-2. 根据当前请求、Work 分支、关键词、状态和 provenance 定位最小相关 entry。
+2. 根据当前请求、Work 分支、关键词、稳定 ID、状态和 provenance，先搜索相关索引行或目录项，再定位最小相关 entry；不把索引全文默认装入上下文。
 3. 只回读命中的 entry 和直接 provenance；需要恢复、冲突裁决、归档、迁移或执行安全证明时，才读取该阶段声明的完整证据集合。
 4. 没有匹配证据时返回缺失证据并停止依赖该结论的分支，不补造事实。
 
 ## Memory writes
 
-正式知识、永久 context、synthesis 或 archive 写入前，先解析唯一 owner 与 gateway，检查 pending transaction、lock、未完成 promotion 和 recovery evidence。gateway 不明或事务未闭合时，只阻塞记忆写入，继续独立的只读审计、定位和验证。
+正式知识、永久 context、synthesis 或 archive 写入前，先解析唯一 owner 与 gateway，检查 pending transaction、lock、未完成 promotion 和 recovery evidence。gateway 不明或事务未闭合时，只阻塞记忆写入，继续独立且已授权的审计、定位、验证和其他工作。
 
-每次写入必须记录 source IDs、证据定位、验证时间或 digest；写入后重新读取索引和目标 entry，确认 owner、locator、内容和状态投影一致。原始证据不可被派生视图覆盖。
+每次写入必须记录 source IDs、证据定位、验证时间或 digest；写入后定位受影响索引项并重新读取目标 entry，确认 owner、locator、内容和状态投影一致。原始证据不可被派生视图覆盖。
 
 ## Read budget
 
 当前 Work 的权威状态、schema、Map/Plan、当前输入和直接所有权合同可以完整读取；非当前分支的知识树、历史 change、研究库、项目 Skill 和示例只按索引与关键词读取。执行、冲突、恢复和归档 Work 需要完整证据时，以该 Work 的显式合同为准。
+
+## 事务与归属隔离
+
+启动正式写入前检查原网关未闭合事务与写集。属于本任务的事务按原恢复协议处理；属于其他任务的事务不得接管、解锁、清空或覆盖。只暂停资源重叠的写入与依赖分支，继续独立、已授权工作；事务年龄不构成接管授权。写后按变更 ID 定位受影响的索引项并回读目标原文，不为核验默认整读整库。

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

@@ -15,7 +15,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Change 架构决策 | `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` | 已成为本 change 下游合同的架构决策、原因、后果和替代关系 | 永久项目 ADR 或尚未决定的方案集合 |
 | 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>` | 总体实施背景、项目 Skill 最低读取路由、依赖 DAG、合同覆盖、Ready 投影、并行候选和路径冲突 | 单 Ticket 的完整实现契约 |
+| Tickets Map | `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` | 总体实施背景、项目 Skill 最低调用路由、依赖 DAG、合同覆盖、Ready 投影、并行候选和路径冲突 | 单 Ticket 的完整实现契约 |
 | Goal Plan | `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
 | Implementation Map | `<Path>{roots.state}/specdev/changes/{change}/implementation-map.md</Path>` | Ready 成员、组合 Ticket inventory、跨 change dependency/serialization 与 revision | 创建或改写子 Spec、Ticket 或实现细节 |
 | Implementation Plan | `<Path>{roots.state}/specdev/changes/{change}/implementation-plan.md</Path>` | 父 Lead、全局 workspace/实现上限、frontier/Wave/locks/integration queue 和可恢复进度投影 | 改写子 change 权威或伪造完成 |
@@ -28,7 +28,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Wayfinder 地图 | `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
 | Wayfinder Ticket | `<Path>{roots.state}/specdev/changes/{change}/investigation/{investigation-id}.md</Path>` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |
 | Wayfinder solution comment | `<Path>{roots.state}/specdev/changes/{change}/investigation/comments/{investigation-id}/NN-solution.md</Path>` | Ticket 的答案、结果事实和资产指针 | 地图索引或产品实现 |
-| 架构审查 | `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path>` | 深化候选、证据、可视化、选择和访谈状态 | 未经用户选择的执行契约 |
+| 架构审查 | `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>` | 结构性候选、code-judo 机会、证据、选择和访谈状态 | 未经用户选择的执行契约 |
 
 UI 设计包中的 `{design-id}` 由 P-prototype 分配为当前 change 内最小未占用的 `UI-NNN`；设计系统文档是唯一设计权威，comparison 与 final 不建立第二套规则。
 
@@ -78,3 +78,11 @@ Change CONTEXT/ADR 是 active change 内的执行权威，不是 workflow 级永
 7. 重新运行 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>`。
 
 不得仅在下游工件中覆盖上游权威。
+
+## 5. Initiative 与计划调用扩展
+
+W 的 `<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>` 只拥有候选 change 的边界、未知、依赖和目标指针；每个物化 child 的 Grill、Spec、Ticket 和状态仍独立。候选图不是实施 DAG，也不是共享可写设计树。
+
+新 Ticket/普通 Map 保持原 schema_version，并使用 plan_contract_version: 1 扩展。Ticket 拥有经过核实的 Skill 调用绑定、语义资源和执行计划；Map 路由是其投影。规则为 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>`。计划、产物数量与完成证据漂移必须由对应 owner 修订；不能仅改 map 状态。
+
+父 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 是 goal-tickets-map 无状态入口，只引用现有 Implementation Map/Plan；它不能拥有第二份 status、owner 或任务清单。统一 P 拥有生命周期，旧 O 仅保留入口与恢复键。

package/template/workflows/specdev/common/rules/operating-governance.md

@@ -0,0 +1,38 @@
+# 运行治理细则
+
+规划、写入、并发、恢复、验收或归档时读取。
+
+
+1. **先发现、后询问**：仓库、配置、schema、测试和文档能回答的事实先探索；只询问真正影响行为、架构、风险、范围、迁移或验收的偏好。
+2. **规划深度随风险增长**：Lite、Standard、Deep 由复杂度和事故半径决定，不由文档长度决定。
+3. **Ticket 是微型计划**：每个 Ready Ticket 决策完备，但不展开逐行代码。
+4. **Goal Plan 按需出现**：简单单票可沿用既有 I/Direct Spec；用户要求长期目标、多个 change 或总控时由统一 P 显式生成，不以固定章节数量作为质量标准。
+5. **证据优先**：每个验收合同、Ticket 和 Gate 都必须有可重复验证与 Evidence。
+6. **路径所有权**：并发实现者只能修改授权项目路径；shared path 有唯一 owner。
+7. **偏差显式化**：计划与事实冲突时停止、记录、修订，不静默扩大范围或改写契约。
+8. **状态单一来源**：Ticket frontmatter 是单 Ticket 状态权威；Map 和 Goal Plan 是投影与编排。
+9. **知识以当前真相为目标**：归档保留历史，永久知识只保留仍真实且经实现验证的结论。
+10. **恢复依赖权威工件**：跨 Work 或 Agent 边界时同步 active change 的 `current_work`，成功完成后去重更新 `works_run`，返回下一 Work 和权威工件的完整路径。
+11. **本地执行权威**：远程 Issue/PR/URL 只作为来源或完成投影；Spec、Ticket、Map、Goal Plan、Evidence 和状态始终以本地工件为准。
+12. **完成与归档分离**：本地完成按 change completion 合同决定；远程 close 失败不回滚完成，但必须 reconcile 或 waive 后才归档。
+13. **Lead 与隔离正交**：Lead 固定拥有 SpecDev 状态、Evidence 与父分支；是否派遣 subagent 由 Lead 动态决定。Goal Plan 创建时询问 Ticket 是否开启 worktree，默认不开启；选择只作用于当前 Goal Plan。
+14. **策略化验收**：current 模式使用当前 workspace 严格串行、direct-parent 验证；required 模式使用 source worktree 与 parent-candidate。只有 required 模式创建独立 Ticket worktree。
+15. **父子权威隔离**：父实现 change 只拥有 Ready 子 change 的组合 Ticket DAG、serialization、全局 workspace/资源和实现进度投影；子 change 继续拥有全部行为与实现合同。一个未完成子 change 只能属于一个未完成父实现 change。
+
+共享规则：
+
+- `<Path>{roots.workflows}/specdev/common/rules/planning-principles.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.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/codebase-design.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/parent-implementation-orchestration.md</Path>`
+
+
+## 保真与局部暂停
+
+用户明确的交付数量、默认工具、风险门禁和权限不会因为入口精简而改变；行为变化必须显式列出。真实源优先，保留软链接、必要元数据、许可和用户未提交改动；系统或插件缓存不属于可写源。资源冲突只暂停相关写集及其依赖闭包；不接管他人 owner、锁或未闭合事务。正式知识必须走原网关。

package/template/workflows/specdev/common/rules/parent-implementation-orchestration.md

@@ -1,6 +1,6 @@
 # Parent Implementation Orchestration
 
-本规则只约束 Ready Spec/Tickets 之后的跨 change 实现，供 O-orchestrate-implementation、I-implement 与 A-archive-and-consolidate 读取。
+本规则只约束 Ready Spec/Tickets 之后的跨 change 实现，供统一 P-goal-plan、兼容 P-goal-plan、I-implement 与 A-archive-and-consolidate 读取。
 
 ## 输入边界
 
@@ -20,8 +20,12 @@
 
 ## I-implement 调用
 
-父 Plan 可以替代缺失的子 Goal Plan 提供 workspace/integration 策略和全局执行边界。子 Goal Plan 存在时继续拥有子 change 内 Gate，但不得与父策略冲突。I-implement 完成或阻塞一个组合 Ticket 后返回父 O Work，不要求用户重新激活 change。
+父 Plan 可以替代缺失的子 Goal Plan 提供 workspace/integration 策略和全局执行边界。子 Goal Plan 存在时继续拥有子 change 内 Gate，但不得与父策略冲突。I-implement 完成或阻塞一个组合 Ticket 后返回父 P Goal（旧 O 入口保留恢复键），不要求用户重新激活 change。
 
 ## 归档与完成
 
 未完成父实现 change 的成员不得归档。成员满足普通 change completion 时可以先 completed，但不自动归档。父 change 只有全部成员 completed、Map/Plan completed、aggregate Evidence 完整且无 active dispatch/candidate/lock 后才能 completed；完成或归档均不自动级联。
+
+## 局部阻塞不升级为全局停机
+
+父创建前仍全部成员预检且 all-or-nothing。父开始运行后，单票 blocked/deviated、他人资源冲突或必需 Skill 失效只阻塞该票及其依赖闭包，父 Map/Plan 可保持 in_progress 与有效的全局执行门，继续独立已授权 frontier。只有共享的全局门禁失败、计划整体失效或没有合法 frontier 时，才将父运行暂停；不得为继续运行接管其他任务。

package/template/workflows/specdev/common/rules/skill-invocation.md

@@ -0,0 +1,27 @@
+# 可验证的 Skill 调用契约
+
+本规则用于 T 规划、P 调度和 I 执行。Map 维护最低读取路由；每票 `skill_bindings` 才定义本票调用，二者不得互相代替。
+
+## 定位与绑定
+
+1. 从项目 Agent 指令解析真实 Skill 根，先枚举元数据和触发条件，再读取命中入口及当前阶段要求的参考；不整读所有 Skills。
+2. 保留逻辑路径、解析真实源，检查不存在的路径、越界软链接、缓存和入口 `name`。默认不使用插件缓存或 node_modules 充当项目可维护源；用户维护的项目内软链接保持原状。仓库外技能需要先取得明确源域授权并由项目网关处理，控制器不会自行扩大根目录。
+3. 每个绑定必须包含真实 `id`（SKILL 的 name）、Path 标签 `path`、入口字节 `sha256`、`phase`（plan/implement/verify）、`operation`、非空 `inputs`、`outputs`、`required` 与 `on_failure`。引用较长参考时在 references 字段 中记录明确 Path、sha256 与 `when`；相关参考在调用前按条件回读。
+4. 必需绑定失败固定为 `block-ticket`；可选绑定只有说明 `condition` 与不适用原因才允许 `report-and-continue`。可选标记不能覆盖用户要求或技能自身硬门禁。
+5. 在模板 frontmatter 中，数组对象用单行 JSON；不使用自定义 YAML 对象语法。缺失 Skill、摘要漂移、占位符或入口 ID 不符，票不得进入 ready。没有适用项目 Skill 时 `skill_bindings: []`，`skill_scan` 必须写真实扫描范围与不适用理由，Map 同步无适用项。
+
+## 示例形状（生成真实票时全部替换）
+
+```json
+{"id":"project-test","path":"<Path>.agents/skills/project-test/SKILL.md</Path>","sha256":"<真实64位摘要>","phase":"verify","operation":"run-regression","inputs":["当前Ticket与定向diff"],"outputs":["含命令、退出码和验收映射的Evidence"],"required":true,"on_failure":"block-ticket","references":[]}
+```
+
+此示例不是项目已存在的 Skill，不得复制为可执行绑定。SpecDev 自带技能在 Work 中按明确 Path 调用，不能伪装为项目 Skill。
+
+## 执行证据
+
+到相应阶段后，实际调用宿主能力或执行该 Skill 明确的步骤。记录技能 ID、phase、operation、所用摘要、输入定位、执行轨迹、输出与结果。仅展示 `@skill`、复制入口、声明“已读”都不是完成证据。
+
+新版票 done 前，在本票 `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` 增加 `## Skill Execution Records`，紧接一个 JSON 数组代码块。每项有 `id`、`phase`、`operation`、`sha256`、`status`（passed/failed/skipped）、非空 `evidence` 字符串数组。required 项必须 passed；验证器只能检查记录结构与摘要一致，Lead 仍需回读真实工具/过程证据，不能把结构通过称为宿主调用已经被认证。
+
+摘要变更先由 Lead 检查影响、更新绑定和 map 后重验；不自动接受最新文件，不回写已完成旧证据。

package/template/workflows/specdev/common/rules/workflow-routing.md

@@ -0,0 +1,24 @@
+# 场景路由
+
+
+| 场景 | 入口 | 正常出口 |
+|---|---|---|
+| 需要冻结外部来源或审计摄入 | T-triage intake | D / G / W / P / S / C / T |
+| 本地 change 完成且来源可关闭 | T-triage reconcile | A |
+| 疑难 bug 或性能回归 | D-diagnose-bugs | S / T / I / R / W |
+| 模糊但可通过决策访谈收敛 | G-grill-with-docs | P / S / T / W |
+| 大需求包含多个未界定 change 或未知路径 | W-wayfinder | G / P / D / S / T |
+| 需要检测项目 UI、选择设计方向并生成可运行设计包 | P-prototype | G / S / T / I |
+| 固定点 diff、branch 或 PR review | C-code-review | completed / T / S / G |
+| 外部行为已清楚 | S-spec | T-tickets |
+| Ready Spec 需要垂直切片 | T-tickets | P-goal-plan / I |
+| 单个或多个 Ready change 的 Goal 规划、持续实现与恢复 | P-goal-plan | I / verify / completed / blocked |
+| 旧 O 调用或恢复键 | P-goal-plan | 统一 P 多 change 模式 |
+| Ready 执行 | I-implement | Triage / A / blocked / deviation |
+| 开发完成后需要理解当前 change 或追问实现 | L-learn-change | 返回用户 / 继续提问 / Triage / A |
+| 架构健康扫描 | R-review-architecture | G / T |
+
+同 change 下一阶段需要当前一手推理且上下文健康时继续；切换 repo/person/harness 或旁路时使用 `<Path>{roots.commands}/handoff.md</Path>`；严格限定且可独立派单时使用 Dispatch Packet；其他长上下文以权威工件路径恢复。平台不支持 clear/compact 时不虚构操作。
+
+
+本地已清晰请求不强制绕行 Triage。G 是单 change Grill，P-prototype 是 UI 设计，不与统一 P-goal-plan 混淆。W 发现候选后逐个交 G/S/T；只有清晰且 Ready 的 child 才交 P。原缺陷诊断 D、风险分诊和远程 reconcile 职责不删除。

package/template/workflows/specdev/common/rules/workflow-state-and-lifecycle.md

@@ -0,0 +1,93 @@
+# 状态、持久化与恢复细则
+
+创建、恢复、迁移、关闭或归档 change 时读取；普通路由只读激活合同。
+
+## 持久化约定
+
+`speculo init` 创建固定状态骨架：
+
+- 全局状态：`<Path>{roots.state}/specdev/status.json</Path>`
+- 活跃 change：`<Path>{roots.state}/specdev/changes/</Path>`
+- 历史归档：`<Path>{roots.state}/specdev/archive/</Path>`
+
+刷新时 CLI 依据 `<Path>{roots.workflows}/specdev/runtime-contract.json</Path>` 处理持久化数据：配置使用 baseline 三方合并，登记的状态 schema 使用显式 migrator，其他 runtime 文件按字节保留。只有字段删除或结构迁移时才在 `<Path>{roots.state}/back/</Path>` 写入 targeted backup；冲突在替换 active 安装前阻塞。`<Path>{roots.state}/back/</Path>`、`<Path>{roots.state}/install.json</Path>`、`<Path>{roots.state}/managed.json</Path>` 与 `<Path>{roots.state}/baselines/</Path>` 均不属于 SpecDev 写入 namespace。
+
+初始化设置 work 首次运行时生成配置并创建空的永久 namespace：
+
+- 全局配置：`<Path>{roots.state}/specdev/config.json</Path>`
+- 追踪规则：`<Path>{roots.state}/specdev/.config/tracking.md</Path>`
+- 领域布局：`<Path>{roots.state}/specdev/.config/domain-layout.md</Path>`
+- 永久 ADR：`<Path>{roots.state}/specdev/adr/</Path>`
+- 永久领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
+- 永久研究：`<Path>{roots.state}/specdev/research/</Path>`
+
+初始化只保证永久目录存在，不写知识内容。只有 A-archive-and-consolidate 在 change 完成、实现证据验证、毕业评估和用户确认后，才能创建、合并或改写这些永久 namespace 中的内容；其他 Works 只读。
+
+单个 change 可以包含：
+
+- `<Path>{roots.state}/specdev/changes/{change}/.status.json</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}/diagnosis.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/diagnostics/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/implementation-map.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/implementation-plan.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/investigation/comments/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/comparison/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/final/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>`
+
+
+
+## 状态字段
+
+`<Path>{roots.state}/specdev/status.json</Path>` 使用全局 schema v5；Spec/Ticket/Tickets Map 保留各自 schema v3；新 Ticket/Map 使用附加 plan_contract_version: 1，config 使用 schema v5，Goal Plan 使用 schema v6，Implementation Map/Plan 使用 schema v1，`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 使用 schema v6：
+
+- `schema_version`（数字）：全局状态 schema 版本，固定为 `5`。
+- `workflow`（字符串）：workflow 标识，固定为 `"specdev"`。
+- `active`（对象数组）：当前活跃 change 的严格索引；每项只能包含 `change`，格式 `"YYYY-MM-DD-<kebab-topic>"`。
+- `archived`（去重字符串数组）：已归档 change 名称。详细归档时间、路径和 promotion 摘要只存在于 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/.status.json</Path>`。
+
+`active[].change` 必须唯一，且不得同时出现在 `archived`。`current_work`、`works_run` 和 `claimed_investigations` 只存在于 change 自有 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`：开始 Work 时设置 `current_work`；暂停或可恢复阻塞时保留；成功完成时加入 `works_run` 并清空；取消时清空但不加入。逐次时间、结果和审计证据由 change 自有状态、Work 主产物、Evidence 或 LOG 承载，不写入全局索引。
+
+`<Path>{roots.state}/specdev/config.json</Path>` 的 `execution.max_implementation_agents`、`max_integration_attempts` 和 planning UI 设计候选字段均为可配置正整数；候选默认值与上限必须落在 2-4 且默认值不大于上限。仅 implementation subagent 受前者约束且不含 Lead，current workspace 仍保持单 writer 串行安全不变量；只读 review/research/test-observation agent 不设 SpecDev 数字上限。
+
+`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `worktrees` 保存 Ticket 级 `base_sha`、父分支、workspace/implementation/integration owner、workspace locator、implementation/source checkpoint、适用 candidate/result SHA、验证、E2E disposition 与生命周期状态。current 记录使用 `workspace_ref=current` 和 direct-parent；required 记录使用 source/parent-candidate。每个实现 Ticket 都有一条记录；父分支只有在对应策略的验证通过后推进。`removed` 是 required 集成后来源 branch/worktree 完成清理的终态，必须保留全部集成与 E2E 证据。
+
+领域状态枚举：
+
+- change：`active | blocked | completed | archived`
+- Ticket：`draft | ready | in_progress | blocked | review | done | deviated | cancelled`
+- Investigation status：`open | closed`
+- Investigation resolution：`answered | out-of-scope | superseded | cancelled | null`
+- Planning Depth：`lite | standard | deep`
+- Worktree：`planned | active | review | integrating | integrated | removed | blocked`
+
+
+
+## 路径分配
+
+1. workflow 运行状态写入 `<Path>{roots.state}/specdev/</Path>`。
+2. change 产物写入 `<Path>{roots.state}/specdev/changes/{change}/</Path>`。
+3. 项目代码、测试和用户要求的项目文档写入项目路径；Evidence 仅保存项目相对指针。
+4. 长期知识候选先在 change 内形成；只有 A 在完成证据、毕业评估和用户确认全部通过后，才提升到对应永久 namespace。
+
+
+## 扩展工件与兼容
+
+W 可写 `<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>`：它只拥有候选 change 边界与目标指针，不复制各 child 的状态。父 Goal 的 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 使用 goal-tickets-map 指针合同，权威仍是父 Implementation Map/Plan。旧 O restore key 不变；旧票继续可读，未完成旧票在新执行前由 Lead 显式补全调用绑定、交付约束并重新过门禁，不自动迁移、重置状态或改写他人事务。

package/template/workflows/specdev/common/schemas/goal-tickets-map.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:goal-tickets-map:v1",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "artifact",
+    "change",
+    "implementation_map",
+    "implementation_plan"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "artifact": {
+      "const": "goal-tickets-map"
+    },
+    "change": {
+      "type": "string",
+      "minLength": 1
+    },
+    "implementation_map": {
+      "type": "string",
+      "pattern": "^<Path>\\{roots.state\\}/specdev/changes/[^/]+/implementation-map\\.md</Path>$"
+    },
+    "implementation_plan": {
+      "type": "string",
+      "pattern": "^<Path>\\{roots.state\\}/specdev/changes/[^/]+/implementation-plan\\.md</Path>$"
+    }
+  },
+  "additionalProperties": false
+}

package/template/workflows/specdev/common/schemas/initiative.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:initiative:v1",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "artifact",
+    "change",
+    "revision",
+    "destination",
+    "changes"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "artifact": {
+      "const": "initiative"
+    },
+    "change": {
+      "type": "string",
+      "minLength": 1
+    },
+    "revision": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "destination": {
+      "type": "string",
+      "minLength": 1
+    },
+    "changes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "name",
+          "background",
+          "scope",
+          "non_goals",
+          "unknowns",
+          "depends_on",
+          "target"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "background": {
+            "type": "string",
+            "minLength": 1
+          },
+          "scope": {
+            "type": "string",
+            "minLength": 1
+          },
+          "non_goals": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "unknowns": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "depends_on": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "uniqueItems": true
+          },
+          "target": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/template/workflows/specdev/common/schemas/ticket.schema.json

@@ -114,6 +114,157 @@
         "pattern": "^<Path>[^<]+</Path>\\s*=>\\s*[^=].+$"
       },
       "uniqueItems": true
+    },
+    "plan_contract_version": {
+      "const": 1
+    },
+    "skill_scan": {
+      "type": "string",
+      "minLength": 1
+    },
+    "skill_bindings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "path",
+          "sha256",
+          "phase",
+          "operation",
+          "inputs",
+          "outputs",
+          "required",
+          "on_failure"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "path": {
+            "type": "string",
+            "pattern": "^<Path>[^<]+/SKILL\\.md</Path>$"
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          },
+          "phase": {
+            "enum": [
+              "plan",
+              "implement",
+              "verify"
+            ]
+          },
+          "operation": {
+            "type": "string",
+            "minLength": 1
+          },
+          "inputs": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "outputs": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "required": {
+            "type": "boolean"
+          },
+          "on_failure": {
+            "enum": [
+              "block-ticket",
+              "report-and-continue"
+            ]
+          },
+          "condition": {
+            "type": "string",
+            "minLength": 1
+          },
+          "references": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "path",
+                "sha256",
+                "when"
+              ],
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "pattern": "^<Path>[^<]+</Path>$"
+                },
+                "sha256": {
+                  "type": "string",
+                  "pattern": "^[a-f0-9]{64}$"
+                },
+                "when": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "additionalProperties": false
+            }
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "properties": {
+                "required": {
+                  "const": true
+                }
+              },
+              "required": [
+                "required"
+              ]
+            },
+            "then": {
+              "properties": {
+                "on_failure": {
+                  "const": "block-ticket"
+                }
+              }
+            }
+          },
+          {
+            "if": {
+              "properties": {
+                "required": {
+                  "const": false
+                }
+              },
+              "required": [
+                "required"
+              ]
+            },
+            "then": {
+              "required": [
+                "condition"
+              ]
+            }
+          }
+        ],
+        "additionalProperties": false
+      }
+    },
+    "resource_claims": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
     }
   },
   "$defs": {
@@ -126,5 +277,21 @@
       "uniqueItems": true
     }
   },
-  "additionalProperties": true
+  "additionalProperties": true,
+  "allOf": [
+    {
+      "if": {
+        "required": [
+          "plan_contract_version"
+        ]
+      },
+      "then": {
+        "required": [
+          "skill_scan",
+          "skill_bindings",
+          "resource_claims"
+        ]
+      }
+    }
+  ]
 }