@namewta/speculo 0.1.21 → 0.2.0

package/template/commands/status.md

@@ -1,58 +1,15 @@
 ---
 id: status
 type: command
-name: Global Status
-description: 按需聚合全局工作流状态（替代物理 STATUS.json）
-keywords: [status, 状态, 进度]
+name: Status
+description: 汇总已安装 workflow、active changes、异常状态与下一步
+keywords: [status, 状态, active, blocked]
 ---
 
 # Status 命令
 
-## 归档路径模式
-
-可选产物目录：`speculo/.speculo/commands/<YYYY-MM-DD>-status-<topic>/`
-
-快照文件：`speculo/.speculo/commands/<YYYY-MM-DD>-status-<topic>/snapshot.md`
-
-- `<YYYY-MM-DD>` 使用当前日期。
-- `<topic>` 从状态范围或用户主题提取，使用小写 kebab-case；无法判断时使用 `snapshot`。
-- 禁止把状态快照写入 `temp/`、系统临时目录或工作区内其他非规范位置。
-
-（若仅是回显报告、不需要持久化时可不归档）
-
-## 调用的 skills
-
-无
-
-## 执行步骤
-
-1. 读取已存在的 `speculo/.speculo/<cat>-status.json`，当前内置分类至少包括 `dev`、`doc` 与 `person`。缺失时报告缺失路径，建议重新运行 `speculo init`，或创建空索引 `{"active":[]}`。
-2. 对每个索引的 `active[]` 条目，读取 `speculo/.speculo/<cat>/<change>/.status.json`。读取失败时把该 change 标记为 `broken-index`，不要擅自删除索引项。
-3. 扫描 `speculo/.speculo/<cat>/*/.status.json`，找出 `change_status: completed` 且尚未位于 `speculo/.speculo/archive/` 的待归档 change。
-4. 聚合输出：
-   - 各分类 active 数量、completed 待归档数量、broken-index 数量
-   - 最近更新的 5 个 change（按 `updated_at` 倒序）
-   - 当前可能阻塞项：`phase_history` 最后一项为 `blocked`，或 `updated_at` 超过 14 天未变化
-   - 推荐下一步：优先处理 broken-index，其次处理 blocked，再推荐继续最近 active change 的 `current_phase`
-5. 用户要求持久化快照时，把报告写入 `speculo/.speculo/commands/<YYYY-MM-DD>-status-<topic>/snapshot.md`；否则只在对话中返回。
-
-## 产物模板（snapshot.md，可选）
-
-> **服务命令：** `status.md`
-> **产物文件名：** `snapshot.md`
-
-```markdown
-# Status Snapshot
-
-## 快照时间
-[TODO: ISO 8601 时间戳。]
-
-## 分类汇总
-[TODO: 按分类列出 active 数量、completed 待归档数量和 broken-index 数量]
-
-## 最近活跃 Changes
-[TODO: 列出最近 5 个更新的 change + 分类 + 当前 phase]
-
-## 可能僵尸 Changes
-[TODO: 超过 14 天未更新的 change 清单]
-```
+1. 扫描 `speculo/workflows/*/WORKFLOW.md`，得到已安装 workflow ids。
+2. 对每个 id 读取 `speculo/.speculo/<workflow>/status.json`，再读取 `changes/<change>/.status.json`。
+3. 报告 active 数量、current route/phase、最近更新时间、blocked/stale changes 与 malformed 目录。
+4. 报告没有 workflow 资产的孤立状态根，以及缺少状态根的已安装 workflow；不自动修复。
+5. 用户要求持久化时写入 `speculo/.speculo/commands/status/<YYYY-MM-DD>-workspace-<topic>[-NN].md`，并在报告中列出本次扫描的 workflow 选择。

package/template/skills/agents-md-builder/SKILL.md

@@ -2,116 +2,29 @@
 id: agents-md-builder
 type: skill
 name: AGENTS.md Builder
-description: 为任意项目扫描 manifest 目录、判定角色、收集证据并生成极简 AGENTS.md 与 CLAUDE.md 重定向文件，形成完整父子导航树；当用户要求为项目生成/刷新 AGENTS.md、构建模块文档导航树、初始化 AI 代理可读的项目导读文档时使用。
+description: 扫描 manifest 目录并生成有证据、极简且形成父子导航树的 AGENTS.md 与 CLAUDE.md。
 ---
 
 # AGENTS.md Builder
 
-## 何时使用
-
-当用户要求为项目生成或维护 `AGENTS.md` 文档时使用。典型触发：
-
-- “为这个项目生成 AGENTS.md”
-- “构建项目的模块文档导航树”
-- “刷新所有模块的 AGENTS.md”
-- “为 src/ 下每个目录生成 AI 可读的导读文档”
-- “初始化项目的 agent 文档”
-
-## 设计理念
-
-每个 AGENTS.md 是一个**模块导读**，不是目录卡片。它回答：这个模块是什么、如何工作、从哪里开始读、看完之后去哪里。
-
-每一行必须通过**删除测试**：*“删除这一行会导致 AI 代理犯错吗？”* 如果不会，就删掉。
+每份 AGENTS.md 是模块导读。逐行执行删除测试：删除后不会使代理犯错的内容不进入产物。
 
 ## 输入
 
-- 项目根路径（默认当前工作目录）
-- 可选：目标子目录（只处理该子树）
-- 可选：manifest 类型过滤（只处理特定生态，如 `package.json`）
-- 可选：AGENTS.md 语言偏好（默认中文）
-
-本 skill 自带全部规范，**不外读仓库 `docs/`**。
-
-## 输出
-
-- 每个 manifest 目录的 `AGENTS.md`（模块导读）
-- 每个 manifest 目录的 `CLAUDE.md`（一行重定向至 AGENTS.md）
-- 生成清单与变更统计
-- 已清理的非法 AGENTS.md 清单（若有）
-
-## 执行步骤
-
-### 步骤 1：确定扫描范围
-
-1. 确认项目根路径。若用户未指定，使用当前工作目录。
-2. 若用户指定了目标子目录，仅处理该子树。
-3. 若用户指定了 manifest 类型过滤（如“只看 package.json”），仅匹配该类型。
+- 项目根（默认 runtime context 的 project root）与可选目标子树。
+- 可选 manifest 类型过滤和输出语言（默认中文）。
 
-### 步骤 2：发现 manifest 目录
+## 流程
 
-1. 读取 `references/manifest-discovery.md`，确认支持的 manifest 文件列表与忽略目录。
-2. 从项目根递归扫描（排除忽略目录），找到所有含 manifest 文件的目录。
-3. 一个目录有多个 manifest 时，按优先级选主 manifest。
-4. 构建 manifest 目录的父子树：子目录的 manifest 继承最近的祖先 manifest 目录。
-5. 标记无 manifest 但已存在 AGENTS.md 的目录（待清理）。
+1. 读取 `references/manifest-discovery.md`，发现 manifest 目录、忽略目录和父子树；同时列出无 manifest 却存在代理手册的目录。完成标准：扫描范围内每个 manifest 恰好出现一次，所有孤立手册已列为候选而未直接删除。
+2. 读取 `references/role-classification.md`，按优先级为每个目录判定唯一角色。完成标准：所有目录都有角色及支持证据，没有多重分类。
+3. 读取 `references/evidence-collection.md`，收集 manifest、入口、依赖、消费方和测试。完成标准：每个将写入的结论都能指向真实文件。
+4. 读取 `references/content-contract.md`、`references/writing-style.md` 和对应 `references/templates/*`，自底向上生成或更新 AGENTS.md。完成标准：父子 routing 完整、内容不跨模块重复且逐行通过删除测试。
+5. 读取 `references/claude-redirect.md` 生成同层 CLAUDE.md；展示创建、更新和删除候选，确认后再写入。完成标准：每个合法 AGENTS.md 有唯一重定向，非法候选的处置有记录。
 
-### 步骤 3：清理非法文档
-
-1. 无 manifest 目录下的 AGENTS.md → 列出并删除。
-2. 无 manifest 目录下的 CLAUDE.md → 列出并删除。
-
-### 步骤 4：判定角色
-
-1. 读取 `references/role-classification.md`。
-2. 按 6 种角色的优先级顺序，为每个 manifest 目录判定唯一角色。
-3. 命中即停止，不继续匹配。
-
-### 步骤 5：收集证据
-
-1. 读取 `references/evidence-collection.md`。
-2. 对每个 manifest 目录，按角色对应的取证顺序收集：
-   - Manifest 文件内容
-   - 关键目录结构
-   - 关键入口文件
-   - 依赖与消费关系
-   - 测试入口
-3. 遵循证据转写原则：结论必须被文件支撑，禁止虚构。
-
-### 步骤 6：生成 AGENTS.md
-
-1. 读取 `references/content-contract.md` 确认必填章节与禁止项。
-2. 读取 `references/writing-style.md` 确认排版、长度与语气。
-3. 读取 `references/templates/` 中对应角色的模板作为骨架。
-4. 自底向上（子 → 父）生成每个 AGENTS.md：
-   - 先写子级 → 父级的 Routing 可引用已确定的子级路径
-   - 每个 AGENTS.md 只负责自己所在模块
-   - 不重复父级或子级已说明的内容
-5. 每个 AGENTS.md 生成后执行删除测试：逐行检查是否冗余。
-
-### 步骤 7：生成 CLAUDE.md
-
-1. 读取 `references/claude-redirect.md`。
-2. 对每个已生成 AGENTS.md 的目录，生成 CLAUDE.md。
-3. CLAUDE.md 只有一行：`读取同层级的AGENTS.md文档。`
-
-### 步骤 8：报告
-
-1. 列出所有生成/更新的 AGENTS.md 路径。
-2. 列出所有生成的 CLAUDE.md 路径。
-3. 列出所有清理的非法文档路径。
-4. 按角色统计：根 x1、聚合 xN、可运行 xN、能力模块 xN、契约模块 xN。
+## 输出
 
-## 渐进披露
+- 生成/更新的 AGENTS.md 与 CLAUDE.md 清单。
+- 按角色统计、证据缺口和经确认清理的孤立文件清单。
 
-- `references/manifest-discovery.md`：扫描项目确定 manifest 目录列表时读取。
-- `references/role-classification.md`：为每个 manifest 目录判定角色时读取。
-- `references/evidence-collection.md`：按角色收集证据时读取。
-- `references/content-contract.md`：生成 AGENTS.md 必填章节与禁止项时读取。
-- `references/claude-redirect.md`：生成 CLAUDE.md 重定向文件时读取。
-- `references/writing-style.md`：确认中文排版、长度密度、语气要求时读取。
-- `references/templates/repo-root-AGENTS.md`：角色为 `repo-root` 时读取。
-- `references/templates/aggregator-AGENTS.md`：角色为 `aggregator` 时读取。
-- `references/templates/runnable-app-AGENTS.md`：角色为 `runnable-app` 时读取。
-- `references/templates/capability-module-AGENTS.md`：角色为 `capability-module` 时读取。
-- `references/templates/contract-module-AGENTS.md`：角色为 `contract-module` 时读取。
-- `references/templates/scripts-docs-AGENTS.md`：角色为 `scripts-docs` 时读取。
+本 skill 不自行选择 Speculo 报告路径；需要持久化时由调用方提供。

package/template/skills/change-lifecycle/SKILL.md

@@ -0,0 +1,25 @@
+---
+id: change-lifecycle
+type: skill
+name: Change Lifecycle
+description: 验证、完成和归档任意 Speculo workflow change，返回可确认的状态与目录移动计划。
+---
+
+# Change Lifecycle
+
+## 输入
+
+- `runtime-context` 返回的 workflow、state、changes、archive 和可选 change 根。
+- `mode: finalize-active | archive-completed`。
+- 当前 route/phase 完成准则、change 状态与可选 worktree 状态。
+
+## 流程
+
+1. `finalize-active` 按 `references/completion-gate.md` 收集新鲜证据；任一关键结论缺证据即返回 blocked。
+2. 两种模式均按 `references/finalize-archive.md` 验证名称、状态、索引和目标冲突。
+3. 返回状态修改、移动、索引更新和可选 worktree 清理计划，等待调用方取得用户确认。
+4. 调用方执行后重新读取源、目标、change 状态和 workflow 索引；存在部分完成即返回 blocked。
+
+完成标准：返回 `verified | blocked | archived` 中唯一裁决及完整证据；本 skill 未自行持久化或执行未确认的破坏性动作。
+
+报告模板见 `assets/completion-verification-template.md` 与 `assets/completion-summary-template.md`。

package/template/{workflows/dev/_templates → skills/change-lifecycle/assets}/completion-summary-template.md

@@ -1,4 +1,4 @@
-> **服务工作流：** `../04-finalize/04-finalize.md`
+> **服务命令：** `../../../commands/finalize.md`
 > **产物文件名：** `completion-summary.md`
 > **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 
@@ -22,4 +22,4 @@
 
 ## 归档记录
 
-[TODO: 归档时间、源路径 → `speculo/.speculo/archive/dev/<YYYY-MM>/<change>/`、用户确认记录。]
+[TODO: 归档时间、源路径 → `speculo/.speculo/<workflow>/archive/<YYYY-MM>/<change>/`、用户确认记录。]

package/template/{workflows/dev/_templates → skills/change-lifecycle/assets}/completion-verification-template.md

@@ -1,4 +1,4 @@
-> **服务工作流：** `../04-finalize/04-finalize.md`
+> **服务命令：** `../../../commands/finalize.md`
 > **产物文件名：** `completion-verification.md`
 > **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
 

package/template/skills/change-lifecycle/references/completion-gate.md

@@ -0,0 +1,19 @@
+# Completion Verification
+
+本门控只服务 `finalize-active`。没有本次运行的新鲜证据时返回 blocked。
+
+## 输入与产物
+
+- 输入：当前 change 产物、route/phase 完成准则、需求来源、VCS diff 和项目验证命令。
+- 产物：当前 change 下的 `completion-verification.md`，使用 `../assets/completion-verification-template.md`。
+
+## 门控
+
+1. 运行相关测试、类型检查、lint 和构建，逐条记录命令、退出码与通过/失败计数。
+2. 重读 PRD、issue、spec 或用户任务，逐项标记 `satisfied | missing | partial` 并引用来源。
+3. Bug 修复确认回归测试经过红、绿、回退修复再红、恢复再绿；无法证明时记录缺口。
+4. 子代理参与时以 VCS diff 和实际文件为证据，不使用代理自报结论。
+5. 搜索调试日志、一次性脚本、DEBUG 标记和未启用功能，清理或记录阻塞。
+6. 全部关键项有证据时写 `verification_status: verified`，否则写 `blocked` 并停止归档。
+
+完成标准：需求清单与每项结论均有新鲜证据，产物无 `[TODO:]`，change 状态已记录验证命令、需求清单和裁决。

package/template/skills/change-lifecycle/references/finalize-archive.md

@@ -0,0 +1,32 @@
+# Finalize And Archive
+
+归档是破坏性目录移动，调用方必须先展示完整计划并取得明确确认。
+
+## 共同预检
+
+- change 名称符合日期 kebab 规则，且 `.status.json` 可解析。
+- 源位于 runtime context 的 `changes_root`，目标位于 `archive_root/<YYYY-MM>/<change>`。
+- 目标不存在，workflow `status.json` 与 change 状态一致。
+- worktree 模式已经合并回目标分支并清理，或调用方明确记录 blocked。
+
+## finalize-active
+
+1. 要求 `verification_status: verified`。
+2. 在当前 change 写 `completion-summary.md`，记录交付边界、证据指针和遗留事项。
+3. 将 `change_status` 置为 `completed`；若 workflow 允许沉淀经验，只写入其声明的 knowledge store。
+4. 展示归档计划并等待确认，随后执行共同归档步骤。
+
+## archive-completed
+
+1. 仅接受 `change_status: completed`，不重新运行完成门控。
+2. 批量模式先为全部候选完成共同预检；任一冲突、malformed 或 broken change 会阻塞整批动作。
+3. 展示逐项计划并等待一次明确确认，随后按稳定顺序执行共同归档步骤。
+
+## 共同归档步骤
+
+1. 创建 archive 月目录并移动整个 change。
+2. 从 workflow `status.json#active` 删除该 change。
+3. 更新已移动的 `.status.json`：`change_status: archived`、`archived: true`、project-relative `archive_path`。
+4. 重新读取目标、索引和状态；失败时返回已完成/未完成清单，不猜测成功。
+
+完成标准：源不存在、目标完整、active 索引已移除且归档状态字段一致。

package/template/skills/docs-sync/SKILL.md

@@ -0,0 +1,22 @@
+---
+id: docs-sync
+type: skill
+name: Docs Sync
+description: 基于可复现 Git 区间、用户确认范围和 workflow 规则，清洁工作区并全量审计同步项目文档与知识资产。
+---
+
+# Docs Sync
+
+调用方提供 runtime context、command 报告路径、全局 state 路径和 Git 副作用责任；本 skill 只使用这些已校验路径。
+
+**全局语言规则：所有项目文档默认使用简体中文书写，除非特定文档类型另有规定（如 `README.md` 固定为英文、`CHANGELOG.md` 跟随项目既有语言）。代码实体、命令、URL 和版本号不翻译。**
+
+## 流程
+
+1. 读取 `references/git-state-contract.md`，清理并提交可验证的既有工作区改动，解析上次基线与本次输入节点。完成标准：输入工作区干净，或已无损阻塞。
+2. 读取 `references/workflow-scope-contract.md`，发现全部已安装 workflow，并解析全局范围与每个 workflow 的确认清单。完成标准：首次运行已统一确认范围，每个 workflow 状态根都有合法 sidecar。
+3. 读取 `references/document-lifecycle-contract.md`，把输入区间和 workflow 证据映射为 `add | update | delete | merge | keep | propose-only`。完成标准：每个受影响资产已整份审计，而非只追加新段落。
+4. 更新 README 时读取 `references/readme-contract.md`；更新 CHANGELOG 时读取 `references/changelog-contract.md`；更新代理手册时读取 `references/agents-contract.md`。需要创建或重建多层代理手册树时改用 `../agents-md-builder/SKILL.md`。
+5. 验证项目和文档，按 `assets/report-template.md`、`assets/state-template.json` 与 `assets/workflow-scope-template.json` 返回原子写入内容。调用方提交显式文件列表并再次确认工作区干净。
+
+完成标准：项目文档与当前事实一致，过期和重复内容已删除或合并；报告可复现输入区间；state 与 sidecar 已提交；没有未确认的越权写入或遗留工作区改动。

package/template/skills/docs-sync/assets/report-template.md

@@ -0,0 +1,45 @@
+---
+command: docs-sync
+mode: <bootstrap|incremental|no-op>
+scope: <workspace|multi-workflow|workflow>
+workflows: []
+changes: []
+generated_at: <ISO-8601>
+---
+
+# Docs Sync Report
+
+## Git Range
+
+- From: `<FROM_SHA|null>`
+- To: `<INPUT_HEAD>`
+- Replay: `git diff <FROM_SHA>..<INPUT_HEAD>` 或 `bootstrap current facts`
+
+## Workspace Cleanup
+
+[记录 checkpoint commit、显式文件清单和运行前验证；无需 checkpoint 时写 `none`。]
+
+## Confirmed Scopes
+
+[记录全局 project targets、各 workflow project/state targets、scope revision 和本次确认变化。]
+
+## Evidence And Lifecycle
+
+| Target | Action | Evidence | Result |
+|---|---|---|---|
+
+## Workflow Sources
+
+[按 workflow 记录读取的 WORKFLOW、archive、声明 store 和受保护候选；空集合写 `[]`。]
+
+## Synced Assets
+
+[列出实际新增、修改、合并或删除的文档与知识资产；no-op 写 `[]`。]
+
+## Verification
+
+[记录实际运行的命令、结果与未运行原因。]
+
+## State
+
+[记录全局 state 与 sidecar 的 schema、revision、pending 迁移项和原子写入结果。]

package/template/skills/docs-sync/assets/state-template.json

@@ -0,0 +1,20 @@
+{
+  "schema_version": 4,
+  "command": "docs-sync",
+  "state_path": "speculo/.speculo/commands/docs-sync/state.json",
+  "baseline": {
+    "mode": "explicit",
+    "sha": null
+  },
+  "last_range": {
+    "from_sha": null,
+    "to_sha": null
+  },
+  "project_targets": [],
+  "pending_legacy_targets": [],
+  "scope_revision": 0,
+  "scope_confirmed_at": null,
+  "last_sync_run_at": null,
+  "total_syncs": 0,
+  "synced_assets": []
+}

package/template/skills/docs-sync/assets/workflow-scope-template.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "workflow": "{workflow}",
+  "manifest_path": "speculo/.speculo/{workflow}/docs-sync.json",
+  "project_targets": [],
+  "state_targets": [],
+  "scope_revision": 1,
+  "scope_confirmed_at": "{ISO-8601}"
+}

package/template/skills/docs-sync/references/agents-contract.md

@@ -0,0 +1,43 @@
+# AI 代理手册同步契约
+
+本契约用于差量维护已确认范围内的 `AGENTS.md`、`CLAUDE.md` 和工具专属入口。创建或重建多层手册树时调用 `../../agents-md-builder/SKILL.md`，不要在 docs-sync 中复制其扫描和模板逻辑。
+
+## 内容优先级
+
+1. 代理无法可靠推导的事实：精确命令、目录职责、运行时版本、架构边界和权威文档入口。
+2. 基于真实失败的回归约束：危险目录、持久化规则、发布门禁和已验证陷阱。
+3. 项目独有行为规范：只有默认模型或工具无法给出时保留。
+
+删除角色扮演、营销语、linter 已强制的规则、README 教程、完整 API 文档、无证据理想规范和“注意代码质量”类空话。
+
+## 生命周期
+
+- 命令、版本、目录、入口、测试、发布或持久化事实变化时，修改或删除对应陈述。
+- 陷阱已被代码或工具消除时删除；同一错误尚未真实发生时不预先堆规则。
+- 每行执行删除测试：“删除后是否会使代理更可能犯错？”答案为否就删除或改为权威链接。
+- 根手册以约 200 行为目标；超过 300 行必须拆到就近手册或权威文档，而不是继续追加。
+- 使用明确条件和祈使句；安全边界可使用“禁止/不得”，不要把所有偏好写成铁律。
+
+## AGENTS 与 CLAUDE
+
+- **铁律：`AGENTS.md` 始终是唯一的权威代理手册。`CLAUDE.md` 永远只能是轻量重定向文件，内容固定为：**
+
+  ```
+  # CLAUDE.md
+
+  Speculo agent handbook: see [AGENTS.md](./AGENTS.md).
+  ```
+
+- 无论项目是单工具还是多工具、纯 Claude 还是跨平台，均不得将 `CLAUDE.md` 作为权威内容载体。所有代理指令、事实和规则必须写入 `AGENTS.md`。
+- 现有多行 `CLAUDE.md` 必须在此次同步中改写为重定向；改变权威来源、删除内容或创建符号链接前必须确认，但确定重定向后立即执行全量迁移。
+- 反之亦然：`AGENTS.md` 不得被缩减为指向 `CLAUDE.md` 的重定向。`AGENTS.md` 重定向到其他文件一律视为错误状态，必须修复。
+- Monorepo 使用就近手册覆盖；父级只导航，不复制子模块细节。
+
+## 验证
+
+- 命令可执行，路径和版本来自当前 manifest/源码，目录树与实际结构一致。
+- 每项禁止或必须都能指向代码无法表达的边界或真实回归。
+- README、CONTRIBUTING、AGENTS 和工具入口之间没有互相复制或冲突。
+- 工具专属入口可以到达唯一权威事实源，站内链接无断链。
+
+完成标准：代理手册保持高密度、可执行和当前；共享事实只有一个权威位置，工具专属差异没有丢失。

package/template/skills/docs-sync/references/changelog-contract.md

@@ -0,0 +1,39 @@
+# CHANGELOG 同步契约
+
+CHANGELOG 面向评估升级风险的人类读者。优先服从项目既有发布约定；首次创建时采用 Keep a Changelog 与项目实际版本方案。
+
+## 结构
+
+- `[Unreleased]` 位于所有已发布版本之前。
+- 已发布版本按新到旧排列，标题包含项目采用的版本号与 ISO 日期。
+- 使用 `Added | Changed | Deprecated | Removed | Fixed | Security` 中实际有内容的分类；空分类不保留。
+- 项目已有稳定扩展分类时继续使用，不为单次条目新造分类。
+- 版本链接或 compare 链接必须指向真实仓库、最新 tag 和正确范围。
+
+已发布条目是历史记录，不根据当前实现重写其措辞。只修复客观错误的版本号、日期或链接，并在报告中说明。
+
+## 从 Git 区间提炼
+
+1. 使用 state 的 `last_range.from_sha/to_sha` 读取完整 diff，而不是把 `git log` 逐条倾倒。
+2. 按用户可感知的能力、行为、兼容性、修复和安全影响聚合主题；测试、格式化和纯内部重构默认不写。
+3. 每条回答“用户之前会遇到什么，现在发生了什么”；实现细节只在解释影响所必需时出现。
+4. 删除 `[Unreleased]` 中已被撤销、被替代、重复或已进入正式版本的内容。
+5. 依赖升级只有在安全、兼容性或用户环境受影响时记录；已知 CVE 进入 `Security`。
+
+Conventional Commit 只是导航信号，最终分类必须由实际 diff 和公共行为决定。
+
+## 破坏性变更与发版
+
+- 破坏性变更放在目标版本最显眼位置，明确影响范围、旧行为、新行为和可执行迁移步骤。
+- 弃用必须给出替代入口和移除条件；没有迁移路径时不得只写“已弃用”。
+- 只有真实版本变更和 tag 存在时，才把 `[Unreleased]` 内容迁移到正式版本；tag 后的新 commit 留在新的 `[Unreleased]`。
+- Release notes 可以从 CHANGELOG 派生，但不能反向覆盖人工维护的历史。
+
+## 条目质量
+
+- 使用项目语言、主动语态和具体模块/能力名。
+- 命令、标志、路径、配置键和版本号使用代码格式。
+- 合并同一主题的多个 commit；删除 merge、WIP、格式化和“多项改进”等噪音。
+- 文档自身变化只有在影响用户采用、迁移或接口理解时才记录。
+
+完成标准：读者可以判断是否升级、会受什么影响以及如何迁移；区间内全部用户可感知变化已覆盖，内部噪音未进入历史。

package/template/skills/docs-sync/references/document-lifecycle-contract.md

@@ -0,0 +1,38 @@
+# 文档生命周期契约
+
+Diff 只负责发现变化；文档结论必须来自当前源码、配置、测试、CI、发布元数据、workflow 声明和已确认归档证据。
+
+## 映射与整份审计
+
+1. 把输入区间按对外能力、CLI/API、配置、架构、依赖、测试、发布、workflow 和文档自身分组。
+2. 映射到确认范围内的文档；没有 owner 的候选先进入 `propose-only`，不得临时扩大范围。
+3. 一旦文档被命中，读取整份文件和直接事实源，逐段判断是否仍准确、仍有读者价值、是否与别处重复。
+4. 为每个资产选择唯一动作：
+   - `add`：存在已实现事实但没有承载位置。
+   - `update`：当前说明错误、不完整或接口已变化。
+   - `delete`：内容已失效且没有历史保留价值。
+   - `merge`：多个位置表达同一事实，收敛为一个权威来源。
+   - `keep`：复核后仍准确。
+   - `propose-only`：范围、语义、所有权或破坏性动作未确认。
+5. 报告记录动作、证据、目标和验证，不把每个 commit 机械转成文档条目。
+
+同一文档内删除过期段落、旧命令、坏链接和重复说明属于常规同步；删除整个文件或目录必须逐次确认。禁止只在末尾追加新事实而保留被推翻的旧内容。
+
+## 文档类型
+
+- 教程回答“如何学习”，操作指南回答“如何完成任务”，参考回答“接口是什么”，解释回答“为什么如此设计”。单篇文档保持主导类型，跨类型内容改成链接。
+- API、配置、架构、迁移和发布说明必须与可执行入口或 schema 逐项核对。
+- 示例必须可复制执行并展示必要的预期结果；不能运行时明确记录原因和静态证据。
+- 多语言镜像保持章节、代码实体、命令、URL 和关键约束对等；只翻译说明文字。
+- 历史版本、ADR 和已发布记录按项目规则归档，不把当前实现反写成虚假历史。
+
+## 验证
+
+至少执行：
+
+- 项目声明的 build/test/lint 或等价质量闸。
+- Markdown 相对链接、标题层级和代码块完整性检查。
+- 文档中的命令、版本、路径、环境变量、配置键、CLI/API 表与事实源交叉检查。
+- 全局搜索旧名称、删除路径、过期版本和被替换措辞，确认没有残留或重复事实源。
+
+完成标准：所有命中资产已穷尽审计且动作唯一；新增、修改和删除均有当前证据；验证通过或运行已无损阻塞。

package/template/skills/docs-sync/references/git-state-contract.md

@@ -0,0 +1,67 @@
+# Git 与全局 State 契约
+
+本契约定义可复现输入、工作区清洁提交和 docs-sync state v4。调用方拥有 Git 与持久化副作用。
+
+## 运行前清洁
+
+1. 确认当前目录属于唯一 Git 仓库，且不处于 merge、rebase、cherry-pick、revert 或 bisect。
+2. 收集 `git status --short --branch`、`git diff --check`、staged、unstaged 与 untracked 路径；逐项读取内容和归属。
+3. 运行仓库声明的最小完整校验。缺少校验命令时记录事实，不虚构命令。
+4. 若存在冲突、校验失败、疑似密钥、异常大文件、无法判断用途的 untracked 文件或不相关用户改动，停止且不改变 Git 状态。
+5. 其余改动按显式路径暂存，并创建一个 `chore(docs-sync): checkpoint workspace` commit。禁止使用 `git add .`、stash、reset、clean、amend、rebase 或丢弃内容。
+6. 重新读取 `git status --short`；非空即继续分类，无法安全收敛时阻塞。
+
+完成标准：`INPUT_HEAD=$(git rev-parse HEAD)` 已记录，工作区为空，checkpoint 的文件清单与验证结果进入报告。
+
+## State v4
+
+默认路径为 `speculo/.speculo/commands/docs-sync/state.json`：
+
+```json
+{
+  "schema_version": 4,
+  "command": "docs-sync",
+  "state_path": "speculo/.speculo/commands/docs-sync/state.json",
+  "baseline": { "mode": "explicit", "sha": null },
+  "last_range": { "from_sha": null, "to_sha": null },
+  "project_targets": [],
+  "pending_legacy_targets": [],
+  "scope_revision": 0,
+  "scope_confirmed_at": null,
+  "last_sync_run_at": null,
+  "total_syncs": 0,
+  "synced_assets": []
+}
+```
+
+- `project_targets` 只保存不归属具体 workflow 的已确认项目文档目标。
+- `baseline.mode` 为 `state-file-commit | explicit`。正常运行使用前者；迁移暂存使用后者。
+- `last_range` 保存本次审计输入的两个 commit；`from_sha` 仅在 bootstrap 时可为 `null`。
+- `pending_legacy_targets` 只用于迁移后等待用户重新确认的旧路径。
+- state 不保存 diff、用户确认原文、绝对路径、个人信息或密钥。
+
+## 基线解析
+
+1. `state-file-commit`：运行 `git log -1 --format=%H -- "$STATE_FILE"`，把最后修改 state 的 commit 作为 `FROM_SHA`。
+2. `explicit`：使用 `baseline.sha`；为 `null` 时进入 bootstrap。
+3. 非空 `FROM_SHA` 必须是 `INPUT_HEAD` 的祖先；浅克隆缺历史、分支分叉或损坏 SHA 均阻塞。
+4. 常规范围固定为 `FROM_SHA..INPUT_HEAD`；bootstrap 盘点当前项目事实，不对 `null` 执行 git diff。
+5. 固定收集 log、name-status、shortstat 和具体文件 diff；commit 标题只用于导航，结论必须回到文件事实。
+
+`last_range.from_sha/to_sha` 必须支持直接运行 `git diff "$FROM_SHA..$INPUT_HEAD"` 复现输入。
+
+## v1-v3 迁移
+
+- `tracked_docs`、`tracked_assets` 原样放入 `pending_legacy_targets`，不得自动转成授权。
+- `synced_docs` 映射为 `synced_assets`；移除 short SHA、commit subject/date 等派生字段。
+- `baseline` 使用 `explicit` 和旧 `last_sync_sha`；`last_range` 使用旧 `previous_sync_sha/last_sync_sha`。
+- 首次 v4 运行统一展示、分类并确认 pending targets；成功后清空 pending，切换为 `state-file-commit`。
+
+## 写回与提交
+
+1. 验证通过后写同目录临时文件，再原子 rename state、报告和 sidecar；JSON 使用 2 空格和尾部换行。
+2. 更新 `last_range={from_sha: FROM_SHA, to_sha: INPUT_HEAD}`、运行时间、计数和实际同步资产；正常输出将 baseline 设为 `{mode: "state-file-commit", sha: null}`。
+3. 显式暂存本次文档、报告、state 和 sidecar。实际修改使用 `docs(docs-sync): synchronize project documentation`；no-op 使用 `chore(docs-sync): record no-op synchronization`。
+4. commit 失败时保留证据并阻塞，不重写历史或丢弃文件。成功后 `git status --short` 必须为空。
+
+下次运行通过 state 文件的 Git 历史定位本次输出 commit，因此不会把本次报告和文档提交重复纳入输入范围。

package/template/skills/docs-sync/references/readme-contract.md

@@ -0,0 +1,44 @@
+# README 同步契约
+
+README 面向首次接触项目、正在判断是否采用以及准备立即试用的读者。保留项目既有语言和风格，不强塞不适用的标准章节。
+
+## 事实顺序
+
+按认知漏斗审计现有结构：
+
+1. 名称与一句具体定位：说明输入、输出或解决的问题，删除空泛营销语。
+2. 必要的截图、演示和功能性徽章：链接失效或状态无价值时修复或删除。
+3. 可复制的最小 Quick Start：尽量前置，并给出判断成功所需的预期结果。
+4. 安装与前置条件：版本、平台、包名和验证命令必须来自当前元数据。
+5. 核心用法、配置和限制：从最常用场景开始，诚实说明未支持边界。
+6. 详细文档、贡献与许可证：已有独立文档时只保留导航。
+
+项目简单时合并相邻章节；README 很长时把 API、架构解释和贡献流程移到对应文档，保留读者完成首次采用所需内容。
+
+## 同步触发
+
+| 事实变化 | 必查内容 |
+|---|---|
+| package 描述、定位或对外能力 | 开头描述、特性、限制 |
+| CLI/API/配置入口 | Quick Start、使用、参考表、示例 |
+| runtime、依赖或发布渠道 | 安装、前置条件、徽章 |
+| 顶层结构或架构边界 | 必要的结构摘要与文档链接 |
+| CI/release/license | 状态徽章、发布说明、License |
+
+从源码、manifest、CLI `--help`、schema、测试和 CI 枚举真实入口。删除被移除的命令、路径、参数、徽章、链接和旧架构，不保留“未来能力”填补空白。
+
+## 多语言
+
+- **铁律：`README.md` 始终为英文（EN）。与之配对的是 `README-ZH.md`，为一对一的中文翻译镜像，两文件内容对等、同步更新。**
+- 标题顺序、命令、代码块、URL、表格字段和关键约束保持对等；代码实体不翻译。
+- `README.md` 内容变更时，`README-ZH.md` 必须在同一次同步中完成对应更新。某语言版本无法同步时阻塞该组修改，不能让镜像继续漂移。
+- 除 README 外的项目文档（如 CONTRIBUTING、架构说明）默认使用中文，除非项目明确要求多语言。
+
+## 验证
+
+- 实际运行或静态验证 Quick Start、安装和核心示例。
+- 对照代码枚举 CLI/API/配置条目，确认没有漏项或幽灵入口。
+- 检查站内链接、图片、徽章和语言切换。
+- 逐段删除测试：删掉后不影响采用决策或正确使用的内容应压缩、下沉或删除。
+
+完成标准：新读者可以从 README 判断项目价值、完成最小安装并验证结果；全部声明均有当前事实来源。