@namewta/speculo 1.0.22 → 2.0.1

package/template/workflows/specdev/specdev-w-wayfinder/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: specdev-w-wayfinder
+description: "大需求的 change 边界或实施路线尚不可见时建立探索地图，并分别澄清各 change；已有清晰 Spec 时不触发。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/wayfinder
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# 探索大需求与 Change 边界
+
+> 激活后读取 `<Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path>`。
+
+W 位于 change 形成之前：Initiative → 候选 change → 各自 Grill → Spec → Tickets → 一个或多个 change 的 Goal。探索载体继续使用普通 change 目录，不增加另一套全局状态根；它不等于最终产品 change。
+
+## 读取范围
+
+先读 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`；先从共享地图定位当前调查 ID，再读当前问题、直接依赖及其 solution comment 原文；共享答案只引用 provenance。低分辨率地图不缓存所有开放票正文。
+
+## 按当前调查选择参考
+
+| 当前需要 | 按需读取 |
+|---|---|
+| 初次绘制问题空间，或划分多个 change | `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/references/initiative-discovery.md</Path>` |
+| 领取并解决一个调查问题，或恢复既有地图 | `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/references/map-traversal.md</Path>` 和 `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/references/local-tracker-contract.md</Path>` |
+| 生成地图、问题与答案 | `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/wayfinder-map-template.md</Path>`、`<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/investigation-ticket-template.md</Path>`、`<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/solution-comment-template.md</Path>` |
+| 选定清晰 change 交给 Goal | `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/references/initiative-discovery.md</Path>` 的交接门禁 |
+
+## 调查的决策价值
+
+每张调查说明它影响的决定、已知事实、缺失证据、最小调查、结束条件和下一 owner。只对目的地相关的兼容、迁移、权限、故障、成本和部署约束展开，不把“全面研究”变成无限搜索。答案需有可回读来源；没有依据的候选继续未知，不能以调查完成代替产品完成。
+
+## 必留纪律
+
+- 目的地约束所有调查；能精确陈述的问题成为调查票，尚不能陈述的留在战争迷雾，目标外内容不自动升级。
+- 默认每个会话最多解决一个调查 Ticket；绘图会话不关闭调查票。这个限制约束 W，不限制 P 的长期 Goal 调度；不静默减少用户明确要求的交付数量。
+- 四类保持 `wayfinder:research`、`wayfinder:prototype`、`wayfinder:grilling`、`wayfinder:task`。HITL 必须真人参与，Agent 不代答；Task 仅解除调查阻塞，不偷做目的地实现。
+- 调查认领保存在各 investigation Ticket 的实际 Assignment；不建中央镜像。先领取后执行；他人已领取的问题跳过，不接管；只暂停有归属冲突的部分。
+- 每个 materialized change 拥有自己的 design-tree、LOG、CONTEXT、ADR、Spec 与 tickets-map；涉及 UI 时也拥有经批准的 DESIGN。共享探索答案通过 solution comment 引用，不复制成多个可写事实源。
+- 缺失关键决定或必需证据时保持该 change 未就绪；其他独立清晰 change 可以交接，不要求整个大需求一次揭完迷雾。
+
+UI 调查调用 P 时按 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path> 继承永久基线并在 HTML 后集中确认。solution comment 只保存设计合同/版本、指定原型与实际证据；探索包复用到 child change 必须核对新范围，不复制出多个永久写入 owner，也不把父探索批准自动视作 child 批准。
+
+## 校验与交接
+
+存在多个候选 change 时，由 W 写 `<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>`；使用 `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/references/initiative-template.json</Path>` 和 `<Path>{roots.workflows}/specdev/common/schemas/initiative.schema.json</Path>`。目标 change 只在用户接受边界后创建，不能挪用已属于其他任务的状态。
+
+运行 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage wayfinder` 校验地图、claim、评论和 initiative；选定成员必须分别满足 Grill 共识、Ready Spec 和 Ready Tickets，再转交 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/SKILL.md</Path>`。W 不把“地图完成”宣称为产品已经交付。

package/template/workflows/specdev/specdev-w-wayfinder/assets/investigation-ticket-template.md

@@ -0,0 +1,20 @@
+---
+artifact: wayfinder-ticket
+id: INV-01
+name: <精确问题名称>
+parent_map: <Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>
+label: wayfinder:grilling
+status: open
+blocked_by: []
+resolution: null
+---
+
+# <精确问题名称>
+
+## 问题
+
+<此 Ticket 要解决的一个决策、调查或解除阻塞工作。>
+
+## 调查价值
+
+本问题影响的决定、已经可查的事实、缺失证据、最小调查、结束条件与下一 owner。只展开与目的地相关的风险；research/prototype/task 不自动转生产实现。

package/template/workflows/specdev/specdev-w-wayfinder/assets/wayfinder-map-template.md

@@ -0,0 +1,33 @@
+---
+artifact: wayfinder-map
+change: <YYYY-MM-DD-topic>
+status: active
+---
+
+# Wayfinder Map: <地图名称>
+
+## 目的地
+
+<到达此地图终点时的样子——此工作正在寻路的 spec、决策或变更。一到两行；每个会话在挑选 Ticket 之前以其为定位。>
+
+## 说明
+
+<领域；每个会话应咨询的 skills；此工作的常设偏好；是否明确把执行带入地图。>
+
+## 已做出的决策
+
+<!-- 索引——每个已关闭 Ticket 一行：足以判断相关性，然后放大链接查看 solution comment 持有的详细信息。开放 Tickets 通过本地 tracker 查询，不列在这里。 -->
+
+- **<已关闭 Ticket 标题>：** `<Path>{roots.state}/specdev/changes/{change}/investigation/comments/INV-01/01-solution.md</Path>` —— <答案的一句话概括>
+
+## 尚未明确
+
+<!-- 范围内但尚无法精确表述为 Ticket 的战争迷雾；随着前沿推进而升级。 -->
+
+## 超出范围
+
+<!-- 被裁定在目的地之外的工作；已关闭，永不升级。 -->
+
+## Change 边界入口
+
+存在多个候选 change 时，W 创建并按需读取 `<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>`；地图不复制其中的候选或子状态。每个目标 change 的 Grill/Spec/Ticket 独立拥有，交接规则见 `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/references/initiative-discovery.md</Path>`。

package/template/workflows/specdev/specdev-w-wayfinder/references/initiative-discovery.md

@@ -0,0 +1,29 @@
+# Initiative：从大需求到独立 Change
+
+## 结构与所有权
+
+探索载体是现有 change 目录；W 在其中拥有 `<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>` 与 wayfinder 地图/调查票。`<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>` 只记录候选边界、关系和 materialized target，不缓存子 change 的状态、Spec、设计树或票正文。
+
+候选 `id` 是稳定 kebab 标识，`target` 为 null 或实际 sibling change 名；同一个 target 不能重复，也不能指向探索载体本身或父 implementation change。其他任务的现存 change 只能在核验归属并获得明确关联授权后引用，不接管其工作。
+
+## 探索顺序
+
+1. 命名大目标、用户指定数量和排除项；按行为、领域边界、风险、接口与发布独立性广度扫描。
+2. 能描述边界的部分成为候选 change；不能描述的留在迷雾。候选至少写背景、目标、非目标和未知项，不预造实施步骤。
+3. 在探索地图建立共享调查问题；每个问题仍遵循 research/prototype/grilling/task、HITL/AFK 和每会话一个调查票的原纪律。
+4. 用户接受候选边界后，创建或明确关联 target change。共享答案以 solution comment/source 引用导入，不复制成新的永久知识。
+5. 对每个 target 调用 `<Path>{roots.workflows}/specdev/specdev-g-grill-with-docs/SKILL.md</Path>`；该 target 独立拥有 design-tree、LOG、CONTEXT、ADR。已确认共享决定可引用复用，不能要求用户机械回答同一问题。
+6. 单个 target 的关键决定清晰后分别进入 S/T；无关 target 继续探索。一个 target 的 blocker 不应阻塞其独立 sibling。
+
+## 校验与交接门禁
+
+- 候选 DAG 无环，依赖 ID 存在；目标与来源有证据，未创建 target 的候选不宣称 Ready。
+- `--stage wayfinder` 验证 initiative 结构、目标存在性与禁止自引用；它不等于子 change 已就绪。
+- 交接时对**选定** target 分别执行 `--stage grill` 与 `--stage tickets --repo <project-root>`，检查设计树 consensus、Spec `ready_for_tickets`、所有待执行票 Ready。
+- 选定范围的跨 change 依赖须同时选择或有已完成基线证据，不用未完成/已取消票虚假满足依赖。
+- 一个 target 交给 P 的单 change 分支；两个或以上 Ready target 交给 P 的多 change 分支。P 不接手剩余迷雾，也不为这些未知部分伪造计划。
+- 用户明确要求全部 change 时，报告全部候选与各自阻塞；交接已清晰部分不等于少交付其他部分或宣布整个大需求完成。
+
+## 版本与恢复
+
+变更候选边界或依赖时递增 `revision`，在探索 LOG 记录来源和替代关系。原 claim、评论编号和低分辨率地图仍是原协议；不改写其他任务，不把探索载体迁成父实现 change。两者可以关联，但职责和 owner 分开。

package/template/workflows/specdev/specdev-w-wayfinder/references/local-tracker-contract.md

@@ -0,0 +1,33 @@
+# Wayfinder 本地 Tracker 适配
+
+最新版 Wayfinder 以 issue tracker 为物理载体。SpecDev 的默认 tracker 是 change state 内的本地 Markdown/JSON；本文件只映射物理原语，不改写 Wayfinder 的地图、Ticket、战争迷雾或遍历语义。
+
+| Tracker 原语 | 本地实现 |
+|---|---|
+| 地图 issue | `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>` |
+| 子 issue | `<Path>{roots.state}/specdev/changes/{change}/investigation/{investigation-id}.md</Path>` |
+| label | Ticket frontmatter 的 `wayfinder:research|prototype|grilling|task` |
+| 阻塞关系 | Ticket frontmatter 的 `blocked_by` |
+| assignment | 原 investigation Ticket 的 `## Assignment` 实际领取记录 |
+| solution comment | `<Path>{roots.state}/specdev/changes/{change}/investigation/comments/{investigation-id}/NN-solution.md</Path>` |
+| 关闭 issue | Ticket frontmatter 的 `status: closed` 与 `resolution` |
+
+## 查询前沿
+
+扫描当前地图的全部子 Ticket。一个 Ticket 同时满足以下条件时属于**前沿**：
+
+1. `status: open`；
+2. `blocked_by` 中的每个 Ticket 都是 `status: closed`；
+3. 该 Ticket 没有仍有效的实际 Assignment。
+
+按文件名中的数字 ID 升序返回。地图正文不缓存开放 Ticket 列表；每次选择前沿都从 Ticket 与 claim 事实重新查询。
+
+## 原子领取
+
+实际领取时在该 Ticket 的 `## Assignment` 写 Owner、Session、Claimed-At 与依据，缺省单 writer；并发必须由真实单写入者协调或有可证明隔离，普通文件 rename 不证明互斥。重读确认未被他人领取，冲突选下一前沿。完成/释放时记录真实处置，不因超时删除他人领取。未领取不建空槽，地图只导航，不建中央 claim registry。
+
+## 解决方案评论
+
+Ticket 正文只保存问题。答案写入下一个未占用的 solution comment 文件，资产从评论链接，不粘贴进 Ticket。关闭 Ticket 后，地图的“已做出的决策”只追加名称链接和一句概括；`out-of-scope` 不进入决策索引。
+
+**完成标准**：地图、Ticket、claim、阻塞和 solution comment 可以重建相同前沿；同一事实没有第二份可写副本。

package/template/workflows/specdev/specdev-w-wayfinder/references/map-traversal.md

@@ -0,0 +1,120 @@
+# 寻路
+
+
+一个模糊的想法出现了——太大而无法放入单个 Agent 会话，且从当前状态到**目的地**的路径尚不可见。寻路就是找到那条路，而非冲向目标。此 work 在 change state 中绘制一张**共享地图**，然后逐个处理其 Tickets，直到路径变得清晰。
+
+目的地可能是一份待移交和迭代的 Spec、一个在规划开始前需锁定的决策，或一项经说明允许在地图中完成的变更。命名目的地是第一步，它塑造每个 Ticket。
+
+
+## 核心纪律
+
+### 规划，而非执行
+
+Wayfinder 默认进行**规划**：每个 Ticket 解决一个决策，当地图完成时路径就清晰了——在某人动手之前没有任何剩余决定。想要直接动手通常说明已经到达地图边缘，是时候移交。只有地图“说明”明确覆盖此行为时，task 才能把解除阻塞的执行带入地图。
+
+### 用名称引用
+
+每张地图和每个 Ticket 都有一个名称。人类阅读的叙述和“已做出的决策”始终用名称引用；ID 和路径包裹在名称链接里，不以裸 `INV-01` 墙代替名称。
+
+### 每会话一个 Ticket
+
+无论绘制还是遍历，**每个会话绝不解决超过一个 Ticket**。绘制地图的会话不解决任何 Ticket；并行 research 的每个独立 Agent 也只负责一个 Ticket。
+
+## 产物与适配
+
+- 地图：`<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
+- 子 Tickets：`<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
+- solution comments：`<Path>{roots.state}/specdev/changes/{change}/investigation/comments/</Path>`
+- assignment：原 investigation Ticket 的实际领取/交接依据，不建全局镜像
+
+每次绘制或遍历前加载 `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/references/local-tracker-contract.md</Path>`。Ticket 和地图模板：
+
+- `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/investigation-ticket-template.md</Path>`
+- `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/wayfinder-map-template.md</Path>`
+- `<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/solution-comment-template.md</Path>`
+
+## Ticket 类型
+
+每个 Ticket 要么是 **HITL**，与一个代表自己发言的人类一起工作；要么是 **AFK**，由 Agent 独立驱动。HITL Ticket 只能通过实时交流解决，Agent 绝不代替人类一方发言。
+
+- **Research（AFK）**：阅读文档、第三方 API 或知识库等资源，揭示某个决策等待的事实。调用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。当需要当前工作目录之外的知识时使用。
+- **Prototype（HITL）**：调用 `<Path>{roots.workflows}/specdev/specdev-p-prototype/SKILL.md</Path>` 继承项目基线、组合模板并先生成 HTML，再集中确认设计。把 <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path>、其 revision/digest、`<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>`、comparison/final 和浏览器证据链接为 solution comment 资产；`{design-id}` 使用 P 返回的 `UI-NNN`，P 不实现目的地。
+- **Grilling（HITL）**：对话。调用 `<Path>{roots.workflows}/specdev/specdev-g-grill-with-docs/SKILL.md</Path>` 的 grilling 与 domain-modeling 能力，但本会话只关闭当前 Wayfinder Ticket。
+- **Task（HITL 或 AFK）**：在决策做出前必须完成的手动工作。它通过为决策解除阻塞赢得位置，不以交付目的地为目标。Agent 能独立驱动时使用 AFK，否则给人类精确清单。
+
+Ticket label 只能是 `wayfinder:research | wayfinder:prototype | wayfinder:grilling | wayfinder:task`。
+
+## 战争迷雾与范围
+
+地图刻意不完整：不要绘制还看不到的内容。活跃 Tickets 之外是**战争迷雾**——能感觉即将到来、但依赖尚未解决问题而无法精确陈述的决策和调查。
+
+**迷雾还是 Ticket？** 判断标准是现在能否精确陈述问题，而非现在能否回答：
+
+- 问题已经清晰时做成 Ticket，即使仍被阻塞；
+- 还无法精确表述时留在“尚未明确”，不预先切成 Ticket 大小碎片。
+
+目的地固定范围。目标之外的工作进入**超出范围**，不是战争迷雾。范围之外永不升级；只有重新命名目的地并创建新 change 时才重新考虑。越界 Ticket 关闭为 `out-of-scope`，链接进“超出范围”，不进入“已做出的决策”。
+
+## 调用模式
+
+### 绘制地图
+
+用户带着模糊想法调用：
+
+1. **命名目的地。** 运行一轮 G 的 grilling/domain-modeling，确定正在寻路的 Spec、决策或变更。
+2. **绘制前沿。** 再次质询，这次广度优先，在整个空间展开而非深入一条线索。如果没有浮现任何迷雾，停下并询问用户如何继续，不创建地图。
+3. **创建地图。** 使用模板填写目的地和说明；“已做出的决策”为空，迷雾写入“尚未明确”。
+4. **创建现在可明确的 Tickets。** 先创建全部 Ticket，再第二遍连接 `blocked_by`，因为 ID 必须先存在。
+5. **派出 research Agent。** 每个 research Ticket 使用独立上下文和 claim，各自只解决一个 Ticket；需要 Git 分支时先取得对应授权。
+6. 停止。绘制地图是一个会话的工作，它不亲手解决任何 Ticket。
+
+**完成标准**：目的地、地图、当前可表述 Tickets、阻塞边和战争迷雾已持久化；绘图会话没有关闭 Ticket。
+
+### 遍历地图
+
+用户带来地图，可选指定 Ticket：
+
+1. 加载地图的低分辨率视图，不加载每个 Ticket 正文。
+2. 用户指定 Ticket 时使用它；否则按本地 tracker contract 查询并选择第一个 frontier Ticket。
+3. 在任何工作前领取 Ticket。已领取时跳过并选择其他 frontier。
+4. 按需缩放：只读取当前 Ticket、相关或已关闭 Ticket 的详情，以及“说明”指定的能力。
+5. 解决当前唯一 Ticket，使用下一个未占用编号写 solution comment，原子关闭 Ticket 并释放 claim。
+6. 在地图“已做出的决策”追加名称链接和一句概括；越界则写入“超出范围”。
+7. 创建新浮现的 Tickets，第二遍连接阻塞；从“尚未明确”删除每个已升级补丁；更新或关闭被答案判定无效的 Tickets。
+
+写回前重读地图、Ticket 与 claims，预期其他会话并发编辑。
+
+**完成标准**：本会话只关闭一个 Ticket；Ticket、solution comment、claim、地图和新 frontier 一致。
+
+## 收敛与路由
+
+当前沿为空且“尚未明确”不再包含阻塞目的地的内容时，路径清晰：
+
+路由前使用 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage wayfinder`；Ticket、claim、comment 或地图不一致时保持 blocked。
+
+- 需要产品或架构取舍：`<Path>{roots.workflows}/specdev/specdev-g-grill-with-docs/SKILL.md</Path>`；
+- 外部行为已清楚：`<Path>{roots.workflows}/specdev/specdev-s-spec/SKILL.md</Path>`；
+- Spec Ready、只需拆分：`<Path>{roots.workflows}/specdev/specdev-t-tickets/SKILL.md</Path>`；
+- Bug 根因路线收敛：`<Path>{roots.workflows}/specdev/specdev-d-diagnose-bugs/SKILL.md</Path>`；
+- 仍有高影响未知项：保持 active/blocked 并返回下一 frontier Ticket 名称。
+
+## 完成标准
+
+- 目的地塑造每个 Ticket 并固定范围；
+- 地图是低分辨率索引，不列开放 Tickets，不复制答案详情；
+- 四类 Ticket 与 HITL/AFK 语义正确；
+- frontier 由 open、unblocked、unclaimed 事实查询；
+- 名称用于人类叙述，裸 ID 只作内部标识；
+- 战争迷雾、Ticket 与超出范围按可精确表述性和范围区分；
+- 每会话最多解决一个 Ticket，HITL 用户没有被 Agent 代答；
+- 每个关闭 Ticket 有 solution comment，资产通过链接引用；
+- claim、阻塞、地图与 Ticket 状态一致；
+- 路径清晰时返回下一 work，不把产品实现藏进寻路。
+
+## 子文件引用
+
+- 本地 Tracker：`<Path>{roots.workflows}/specdev/specdev-w-wayfinder/references/local-tracker-contract.md</Path>`
+- Ticket 模板：`<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/investigation-ticket-template.md</Path>`
+- Solution comment：`<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/solution-comment-template.md</Path>`
+- 地图模板：`<Path>{roots.workflows}/specdev/specdev-w-wayfinder/assets/wayfinder-map-template.md</Path>`
+- Ticket schema：`<Path>{roots.workflows}/specdev/common/schemas/wayfinder-ticket.schema.json</Path>`

package/scripts/validate-skills.mjs

@@ -1,56 +0,0 @@
-#!/usr/bin/env node
-import { readFile, readdir } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-
-const allowed = new Set(["name", "description", "license", "compatibility", "metadata", "allowed-tools", "disable-model-invocation"]);
-/** Validator for the deliberately small emitted YAML profile; unsupported YAML is rejected, not guessed. */
-export function validateSkill(content, directory) {
-  const errors = [], fields = Object.create(null);
-  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
-  if (!match) return ["missing YAML frontmatter"];
-  for (const line of match[1].split(/\r?\n/).filter((s) => s.trim())) {
-    const m = /^([a-z][a-z-]*):\s*(.*)$/.exec(line);
-    if (!m) { errors.push("use single-line fields and a JSON-flow metadata map in emitted Skills"); continue; }
-    const [, key, raw] = m;
-    if (!allowed.has(key)) errors.push("unexpected field: " + key);
-    if (key in fields) errors.push("duplicate field: " + key);
-    try { fields[key] = key === "metadata" || raw.startsWith('"') ? JSON.parse(raw) : raw.startsWith("'") && raw.endsWith("'") ? raw.slice(1, -1).replaceAll("''", "'") : raw; }
-    catch { errors.push("invalid scalar or metadata JSON: " + key); }
-  }
-  if (typeof fields.name !== "string" || fields.name.length > 64 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(fields.name) || fields.name !== directory) errors.push("name must be a lowercase kebab identifier matching the directory (1..64)");
-  if (typeof fields.description !== "string" || !fields.description.trim() || fields.description.length > 1024 || ["|", ">"].includes(fields.description)) errors.push("description must be a single-line string (1..1024)");
-  if (fields.compatibility !== undefined && (typeof fields.compatibility !== "string" || !fields.compatibility || fields.compatibility.length > 500)) errors.push("invalid compatibility");
-  if (fields.metadata !== undefined && (!fields.metadata || typeof fields.metadata !== "object" || Array.isArray(fields.metadata) || Object.values(fields.metadata).some((v) => typeof v !== "string"))) errors.push("metadata must map string keys to string values");
-  if (fields["disable-model-invocation"] !== undefined && !["true", "false"].includes(fields["disable-model-invocation"])) errors.push("disable-model-invocation must be a YAML boolean");
-  if (fields.metadata?.["speculo-invocation"] === "user-only" && fields["disable-model-invocation"] !== "true") errors.push("user-only skills require Claude disable-model-invocation: true");
-  return errors;
-}
-export async function validateSkills(root) {
-  const errors = []; let checked = 0;
-  async function walk(dir) {
-    for (const entry of await readdir(dir, { withFileTypes: true })) {
-      const path = join(dir, entry.name);
-      if (entry.isSymbolicLink()) { errors.push(`${path}: unexpected symlink in skill source`); continue; }
-      if (entry.isDirectory()) await walk(path);
-      else if (entry.name === "SKILL.md") {
-        checked++;
-        const content = await readFile(path, "utf8");
-        for (const error of validateSkill(content, basename(dirname(path)))) errors.push(`${path}: ${error}`);
-        if (/"speculo-invocation"\s*:\s*"user-only"/.test(content)) {
-          try {
-            const profile = await readFile(join(dirname(path), "agents/openai.yaml"), "utf8");
-            if (!/^policy:\r?\n  allow_implicit_invocation: false\s*$/m.test(profile)) errors.push(`${path}: user-only skill lacks Codex explicit invocation policy`);
-          } catch { errors.push(`${path}: missing agents/openai.yaml`); }
-        }
-      }
-    }
-  }
-  await walk(join(root, "template"));
-  return { checked, errors };
-}
-if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
-  const result = await validateSkills(resolve(process.argv[2] ?? "."));
-  if (result.errors.length) { console.error(result.errors.join("\n")); process.exitCode = 1; }
-  else console.log(`Agent Skills emitted-profile validation: ${result.checked} passed (not a host behavior certification)`);
-}

package/template/commands/archive-and-consolidate.md

@@ -1,72 +0,0 @@
----
-id: archive-and-consolidate
-type: command
-name: Archive and Consolidate
-description: Archive or consolidate a user-selected completed change and its knowledge under the owning workflow contract.
-keywords: [archive, consolidate, learning, topic, cold-archive, 归档, 综合]
----
-
-# Archive and Consolidate 命令
-
-## 持久化契约
-
-唯一报告路径：
-
-```text
-<Path>{roots.state}/commands/archive-and-consolidate/{date}-{scope}-{topic}[-NN].md</Path>
-```
-
-实际路径必须通过 `<Path>{roots.state}/workspace.json</Path>` 的 `roots.state` 解析。解析后同时记下：
-
-- `commands_def_root` = `{roots.commands}`：只放命令定义
-- `commands_root` = `{roots.state}/commands`：只放 command 报告
-
-`{roots.commands}` 不是报告根。禁止把 `YYYY-MM-DD-*.md` 写入 `{roots.commands}/archive-and-consolidate/` 或任何定义目录旁边。
-
-POSIX 规范化后：
-
-- `commands_root` 必须等于 `{roots.state}/commands`
-- `commands_root` 等于 `{roots.commands}`，或报告路径落在 `{roots.commands}` 下 → **blocked，不写文件**
-- `{roots.commands}/archive-and-consolidate/` 已存在 `YYYY-MM-DD-*.md` → **blocked**；列出误落盘文件，要求先搬到 `<Path>{roots.state}/commands/archive-and-consolidate/</Path>`。目标同名则加 `-NN`，不覆盖正文
-
-规则：
-
-- `<scope>`：目标 workflow 名
-- `<topic>`：change 名或 `batch`
-- 同日同 scope/topic 冲突时，从 `-01` 选择最小未占用编号
-- 禁止覆盖已有报告
-- 禁止把正式报告写入 `temp/`、系统临时目录、`{roots.commands}/`、`{roots.state}/{workflow}/` 或其他位置
-- 报告记录 workflow、source/root IDs、dry-run 清单、用户确认、relocation manifest、synthesis revision 或 archive locator、`path_context.commands_root` 和验证结果
-
-## 运行时解析
-
-1. 从当前目录向上寻找 `<Path>{roots.state}/workspace.json</Path>`；无法唯一确定时停止并提示 `speculo init`。
-2. 读取并验证 `path_base` 与 roots，再读取 `<Path>{roots.config}</Path>`（不存在时静默降级）。
-3. 在调用任何 skill 或 Work 之前完成上面的 `commands_root` 校验。
-4. 把 `commands_root` 作为报告 owner 路径传给后续 skill/Work；返回的 `path_context.commands_root` 若不等于 `{roots.state}/commands`，停止且不写文件。
-
-无论走 Learning Work 还是其他 workflow，Command 报告都只写 `<Path>{roots.state}/commands/archive-and-consolidate/</Path>`。
-
-## Learning 路由
-
-目标 workflow 为 Learning 时，读取 `<Path>{roots.workflows}/learning/README.md</Path>`，由用户明确选择一个 Work：
-
-- `C-consolidate`：生成 source manifest 和 dry-run；确认后调用 `<Path>{roots.workflows}/learning/common/tools/relocate-learning.mjs</Path>` 物理移动 active/closed Change 到父 Change 的 `children/`，再生成带 provenance 的 synthesis。未确认时不得移动或更新 context。
-- `A-archive`：只处理用户 close/confirm 的 root Change 树，以最新源更新时间决定 `archive/YYYY-MM/`，不要求 Homework、R 或 mastery，也不写 context。
-
-不得把 Learning 交给共享的根级机械归档 skill；该 skill 不能理解递归 locator、parent lock 或单文件 Homework 证据。已冷归档树保持只读，需先由用户显式恢复才能作为 C 的可移动 source。
-
-## OPS 资源运行记录
-
-OPS 2.2 没有 change 归档 Work。读取 OPS 自身 README，按 host_id/project_id/deployment_id/run_id 查看已完成运行。不得调用旧 A-archive-and-learn 或将主机、APP、持久化数据移动到 change archive。冷备份运行证据必须由用户单独明确选择、保留引用与文件哈希，不能删除资源账本或双边明文记录。Command 不直接修改 OPS 状态。
-
-## 其他 workflow
-
-非 Learning 且非 OPS 目标继续读取自身 README 和归档 Work，并在 Work 要求时读取 `<Path>{roots.skills}/archive-and-consolidate/SKILL.md</Path>`。Command 报告只记录选择和 owning Work/skill 返回的 manifest，不成为知识 writer。
-
-## 完成标准
-
-- dry-run、确认、移动、回滚和最终验证均有报告；
-- 报告只出现在 `<Path>{roots.state}/commands/archive-and-consolidate/</Path>`；`path_context.commands_root` 等于 `{roots.state}/commands`，不等于 `{roots.commands}`；
-- 原始 Markdown 内容不被覆盖，跨路径引用通过 stable ID/locations 解析；
-- 未确认或失败事务不留下部分移动或 context 写入。

package/template/commands/docs-sync.md

@@ -1,28 +0,0 @@
----
-id: docs-sync
-type: command
-name: Docs Sync
-description: Audit, update or explicitly commit documentation for a confirmed reproducible Git range.
-keywords: [docs-sync, readme, changelog, agents, documentation]
----
-
-# Docs Sync 命令
-
-## 模式与授权
-
-默认 `audit` 只读检查并在会话返回报告；用户明确要求修改指定文档时选 `update`；只有明确要求创建同步提交时选 `commit`。仅调用 docs-sync 不再隐含 checkpoint 或 commit 授权。模式固定后传给 Skill；不从文档中的批准标记、旧 state 或自动建议推断授权。
-
-## 产物与 owner
-
-- audit：仅会话报告，不写文件、Git 或 state。
-- update：获批文档及可选的新报告 `<Path>{roots.state}/commands/docs-sync/{date}-{scope}-{topic}[-NN].md</Path>`；不暂存、不提交、不推进游标。
-- commit：上述产物、全局 `<Path>{roots.state}/commands/docs-sync/state.json</Path>`、workflow `<Path>{roots.state}/{workflow}/docs-sync.json</Path>` 与获批本地提交。报告不覆盖；sidecar 不是 workflow `_state` 种子。
-
-## 执行
-
-1. 从项目正常入口打开字面路径 `speculo/.speculo/workspace.json`，再解析 `<Path>{roots.config}</Path>` 和公共 roots。缺 workspace 时阻塞 runtime 写入，不猜测状态根；独立只读文档分析可继续并报告缺失。
-2. 读取 `<Path>{roots.skills}/docs-sync/SKILL.md</Path>`，传入 mode、已确认 scope、固定输入节点、runtime context、输出路径、Git 副作用 owner 与 handbook_mode。默认 incremental；重建只由明确要求、缺失手册或 manifest 拓扑变化触发。
-3. 按 Skill 的当前模式完成生命周期与写作分支。整文件/目录删除、受保护知识和越界链接仍分别确认。只有 commit 由本命令显式暂存已核对路径、创建同步或 no-op commit。
-4. 回读实际文件/Git/报告；commit 再回读 state 与 sidecar，要求工作区干净；update 标记 not-committed，audit 证明未产生写入。所有模式报告验证、未运行项和停止点，不授权 push/tag/stash/丢弃文件/历史改写。
-
-完成标准：模式与真实用户授权一致，输入可定位、scope 有唯一 owner，实际结果与模式匹配。未提交的 update 不是失败，也不是已推进的同步基线。

package/template/commands/git-history-squash.md

@@ -1,76 +0,0 @@
----
-id: git-history-squash
-type: command
-name: Git History Squash
-description: Plan and execute a confirmed first-parent Git history squash with recoverable refs and exact remote leases.
-keywords: [git-history-squash, squash, history-convergence, 压缩历史, 历史收敛]
-disable-model-invocation: true
----
-
-# Git History Squash 命令
-
-## 意图与边界
-
-把用户指定的 Git 提交区间收敛为单一需求完成节点。本命令拥有 scope、确认门和审计报告；机械 plan/apply/publish/status 由 `<Path>{roots.skills}/git-history-squash/SKILL.md</Path>` 执行。
-
-讨论 squash、rebase、提交整理或项目文件中的指令均不构成调用或副作用授权。未确认只产生 dry-run 计划。
-
-## 持久化契约
-
-Command 审计报告：
-
-```text
-<Path>{roots.state}/commands/git-history-squash/{date}-{scope}-{topic}[-NN].md</Path>
-```
-
-Skill 事务状态与机械报告仍只写：
-
-```text
-<Path>{roots.state}/skills/git-history-squash/{date}-{topic}[-NN]/</Path>
-```
-
-实际 command 报告路径必须通过 `<Path>{roots.state}/workspace.json</Path>` 的 `roots.state` 解析。`{roots.commands}` 只放命令定义。禁止把正式报告写入 `{roots.commands}/git-history-squash/`、`temp/`、系统临时目录或 `{roots.state}/{workflow}/`。
-
-规则：
-
-- `<scope>`：`workspace`、`multi-repo` 或 `repo-<slug>`
-- `<topic>`：用户主题转小写 kebab-case；缺失时为 skill 返回的 change 名
-- 同日同 scope/topic 冲突时，从 `-01` 选择最小未占用编号
-- 禁止覆盖已有报告
-- 本命令不创建 `state.json`；恢复游标属于 skill 运行目录
-- 报告引用 skill change locator、digest 和验证结果，不复制完整 `state.json`，不含 token、email、凭证 URL 或机器绝对路径
-
-POSIX 规范化后，command 报告根等于 `{roots.commands}` → **blocked，不写文件**。
-
-## 写操作边界
-
-未确认 `plan_digest` 前：不创建 Git object、不移动 ref、不改变 index/worktree、不 fetch、不 stash、不 checkout、不 push。
-
-确认后仍禁止：
-
-- 普通 `--force`、没有精确 expected SHA 的 lease、matching refspec
-- `rebase`、`reset --hard`、交互式 rebase
-- 自动删除 source/integration worktree、branch、backup ref、stash 或 reflog
-
-远端更新是第二道确认门，只允许精确 `--force-with-lease=<ref>:<old-sha>` 和单一显式 refspec。
-
-## 执行
-
-1. 从当前目录向上寻找 `<Path>{roots.state}/workspace.json</Path>`；无法唯一确定时停止并提示 `speculo init`。读取并验证 roots，再读取 `<Path>{roots.config}</Path>`（不存在时静默降级）。
-2. 读取 `<Path>{roots.skills}/git-history-squash/SKILL.md</Path>`，再按其 entry procedure 读取当前分支 reference。
-3. 用户必须逐仓库明确 repository、完整 local branch ref、start、end、`inclusive | exclusive`、commit message、签名选择和远端发布选择；不得猜测缺失值。用 `<Path>{roots.skills}/git-history-squash/assets/request-template.json</Path>` 生成临时 request JSON。
-4. 运行 skill `plan`。展示旧/新拓扑、将被替换的提交数、merge 数、受影响本地/远端 refs、backup ref 和预计提交信息。有 blocker 时保持 dry-run，不进入确认。
-5. 只有用户在当前对话中明确确认该本地 manifest 和 `plan_digest` 后运行 `apply`。执行前重验计划仍与确认相同。
-6. 脚本返回 `confirm-publish` 时，展示远端 manifest（repository、remote、remote branch、冻结 old SHA、local new SHA、保护策略、发布顺序）。只有用户明确确认该 manifest 和 `publish_digest` 后运行 `publish`。
-7. 多层 submodule 先压缩并发布子仓库，再更新父仓库 gitlink；部分成功时记录已完成/未完成仓库和恢复步骤，不伪装原子成功。
-8. 将选择、确认、验证、远端结果和恢复信息原子写入本次 command 报告，并重读报告、skill state 与目标 refs。
-
-中断或重入时先运行 skill `status`；实际 refs 与 state 一致才用返回的下一 digest 回到步骤 5 或 6。漂移时 blocked，生成新的精确恢复计划并重新取得授权。本命令不自动执行恢复或清理。
-
-## 完成标准
-
-- dry-run 模式不移动任何 ref、不创建提交、不推送远端
-- 压缩成功后旧 HEAD 与新 HEAD 的 tree 等价（父仓库 gitlink 按 skill submodule 合同），基线到新 HEAD 恰好一个提交，并存在可恢复 backup ref
-- 远端在确认前零写入；lease 漂移时拒绝推送
-- 旧 worktree/branch/backup ref 未被本命令删除
-- 报告位于唯一 command 路径；skill 运行目录可恢复；失败不伪装成部分成功

package/template/commands/git-repository-audit.md

@@ -1,83 +0,0 @@
----
-id: git-repository-audit
-type: command
-name: Git Repository Audit
-description: Produce a read-only reproducible audit for explicitly selected local Git repositories.
-keywords: [git-audit, git-inventory, repository, commit, merge, contribution, 仓库盘点, 代码审计, 团队评估]
----
-
-# Git Repository Audit 命令
-
-## 意图与边界
-
-执行一次性、只读、可复现的 Git 仓库盘点：
-
-- 发现 `project_root` 下的 Git 仓库；
-- 按用户选择的时间、仓库、refs、作者名字和路径范围采集本地 Git 历史；
-- 分析 commit、merge、功能迭代、bug 修复、提交节奏、代码增减、热点模块、团队协作和个人贡献；
-- 将完整选择、Git 快照、原始指标、关键证据、结论和复核命令写入唯一 Markdown 报告。
-
-本命令是单次短编排，不维护 workflow 状态机，不调用外部 API，不补抓远端数据。
-
-## 持久化契约
-
-唯一持久化产物：
-
-```text
-<Path>{roots.state}/commands/git-repository-audit/{date}-{scope}-{topic}[-NN].md</Path>
-```
-
-实际路径必须通过 `<Path>{roots.state}/workspace.json</Path>` 的 `roots.state` 解析：
-
-```text
-<Path>{roots.state}/commands/git-repository-audit/{date}-{scope}-{topic}[-NN].md</Path>
-```
-
-规则：
-
-- `<scope>`：
-  - `workspace`：全部发现仓库；
-  - `multi-repo`：多个但非全部仓库；
-  - `repo-<slug>`：单个仓库。
-- `<topic>`：用户主题转小写 kebab-case；缺失时为 `git-audit`。
-- 同日同 scope/topic 冲突时，从 `-01` 开始选择最小未占用编号。
-- 禁止覆盖已有报告。
-- 禁止把正式报告写入 `temp/`、系统临时目录或其他位置。
-- 本命令不创建 `state.json`、sidecar、CSV、JSON、数据库或长期缓存。
-- 临时数据只存在于内存或 `tempfile.TemporaryDirectory()`，结束时清理。
-- 报告内所有路径使用 POSIX 项目根相对路径；不持久化绝对路径。
-
-## 写操作边界
-
-只允许创建 command 专属目录并原子写入、重读本次报告。
-
-不得修改仓库、工作区、索引、refs、远端或 Python 项目环境。不得执行：
-
-```text
-git add/commit/checkout/switch/reset/restore/clean/merge/rebase/cherry-pick/revert
-git branch -d/-D
-git tag/stash/fetch/pull/push/gc
-uv sync/add/lock
-```
-
-不得修改项目源码、测试、文档、Git 配置、`.git/`、`pyproject.toml`、`uv.lock` 或项目内 `.venv`。
-
-## Python 运行契约
-
-所有 Python 采集和计算统一使用：
-
-```bash
-uv run --no-project python -
-```
-
-- 脚本从标准输入传入；
-- 仅使用 Python 标准库；
-- 不直接调用 `python`、`python3`、`pip` 或 `poetry`；
-- 不创建项目内虚拟环境；
-- `uv` 不可用时停止，不切换管理方式。
-
-## 按需执行
-
-本命令选中后，采集或生成报告前必须读取 `<Path>{roots.commands}/references/git-repository-audit-procedure.md</Path>`，按其输入选择、身份处理、固定点采集、计算、交叉校验、报告结构和原子持久化顺序执行。用户未明确的范围按原选择协议确认；不得先扩大分析范围。
-
-默认运行工具仍是 `uv run --no-project python -`；不可用即停止，不静默切换。仍只交付一个完整 Markdown 报告，包含原始指标、证据、限制和复核命令；不另建 CSV/JSON/sidecar。采集不可复现、交叉校验失败、来源不可读或报告路径冲突时停止受影响报告，不猜测数据、不覆盖已有结果。完成后回读报告，再按参考的返回合同交付。