@namewta/speculo 1.0.22 → 2.0.1

package/template/skills/docs-sync/references/agents/templates/repo-root-AGENTS.md

@@ -1,71 +0,0 @@
-# <project-name>
-
-## Scope
-
-- 说明当前根级 manifest 覆盖的目录范围。
-- 明确哪些更深层 manifest 目录会接管说明。
-
-## Module Positioning
-
-- 标记当前角色为 `repo-root`。
-- 说明根目录在整个项目中承担的总入口职责。
-- 概括顶层模块如何分层（如有 workspace / multi-module）。
-
-## Directory Structure
-
-- 列出顶层直接子目录与关键根级文件。
-- 点明哪些中间层目录本身没有独立 AGENTS.md，事实如何上收。
-
-## Responsibilities
-
-- 说明根级目录负责哪些项目边界、装配边界和阅读路径。
-- 明确不负责的子模块内部实现细节。
-
-## Core Logic
-
-- 解释顶层 manifest 如何组织子模块或 workspace。
-- 解释从根级进入项目时，应该如何定位到聚合层或叶子层。
-- 不要只列模块名，要解释分层理由。
-
-## Key Entry Points
-
-- 顶层 manifest 文件
-- workspace / multi-module 配置
-- 顶层直接子模块的代表性入口
-- 关键根级配置文件
-
-## Usage And Change Notes
-
-- 先用顶层 manifest 与模块分组判断问题落在哪个聚合层或叶子层，不要在根层直接推断子模块细节。
-- 调整顶层模块清单、父依赖或构建插件时，先检查根级配置与子模块导读是否需要同步。
-- 根层只负责边界与导航；涉及具体实现时，必须进入对应子模块继续调查。
-
-## Dependencies And Collaboration
-
-- 说明顶层模块之间的协作关系。
-- 说明哪些问题必须下钻到子模块源码。
-
-## Investigation Rule
-
-- 明确：先用本文件建立范围与导航。
-- 如果本文件无法回答问题，继续深入子模块 AGENTS.md、manifest、关键源码、配置与测试。
-- 文档与代码冲突时以代码事实为准。
-
-## Core Commands
-
-- 根级常用构建、测试、运行命令。
-
-## Verification
-
-- 根级最小可执行校验。
-
-## Routing
-
-- 链接全部子级 manifest 目录（每个附带一句话定位）。
-
-## References
-
-- 顶层 manifest
-- workspace / multi-module 配置
-- 关键根级配置文件
-- 代表性入口文件

package/template/skills/docs-sync/references/agents/templates/runnable-app-AGENTS.md

@@ -1,69 +0,0 @@
-# <module-name>
-
-## Scope
-
-- 说明当前运行型 manifest 覆盖的目录范围。
-
-## Module Positioning
-
-- 标记当前角色为 `runnable-app`。
-- 说明它是运行时装配入口、Web 服务入口、CLI 工具入口或独立应用入口。
-
-## Directory Structure
-
-- 列出直接子目录、关键文件、主源码路径、资源目录和测试目录。
-- 指出最重要的实现分层与配置位置。
-
-## Responsibilities
-
-- 说明当前模块负责的启动、装配、应用入口和运行边界。
-- 明确不负责哪些内部依赖模块的实现细节。
-
-## Core Logic
-
-- 解释启动入口如何组织应用。
-- 解释核心链路（路由/控制器/服务/数据层 或 等价链路）如何协作。
-- 解释内部依赖模块如何接入当前应用。
-
-## Key Entry Points
-
-- 启动入口文件
-- 关键路由/控制器/服务入口
-- 核心配置文件
-- 测试入口
-
-## Usage And Change Notes
-
-- 改启动链路、装配逻辑或运行参数时，先检查启动入口、运行时配置与直接内部依赖模块。
-- 新增或调整应用入口时，优先确认归档位置、配置联动和对应下游模块是否同步。
-- 当前层是运行时装配入口，不要在这里替代内部模块的业务导读。
-
-## Dependencies And Collaboration
-
-- 列出直接内部依赖模块。
-- 说明当前模块作为运行时装配层，如何把这些模块组装起来。
-
-## Investigation Rule
-
-- 明确：先读 manifest，再读启动入口与配置，再顺着核心链路下钻。
-- 如果问题落到业务模块内部，必须跳到对应模块 AGENTS.md 与源码继续调查。
-- 文档与代码冲突时以代码事实为准。
-
-## Core Commands
-
-- 当前模块的开发、构建、测试、运行命令。
-
-## Verification
-
-- 当前模块最小可执行校验。
-
-## Routing
-
-- 上级 manifest
-
-## References
-
-- manifest 文件
-- 启动入口
-- 关键源码目录
-- 关键资源与测试入口

package/template/skills/docs-sync/references/agents/templates/scripts-docs-AGENTS.md

@@ -1,51 +0,0 @@
-# <dir-name>
-
-## Scope
-
-- 说明当前文件只覆盖此脚本/文档根目录。
-- 明确子目录不再下钻生成子级 AGENTS.md。
-
-## Module Positioning
-
-- 标记当前角色为 `scripts-docs`。
-- 说明这是项目脚本资产或文档的总索引，不是标准的 manifest 模块。
-
-## Directory Structure
-
-- 列出一级子目录与关键根级文件。
-- 区分可执行脚本、配置模板、SQL/迁移、任务清单、样例数据与运行时数据目录。
-
-## Responsibilities
-
-- 说明当前目录负责哪些资产索引、阅读路径与维护约束。
-- 明确不负责子目录独立文档拆分。
-
-## Core Assets
-
-- 概括各类子树的用途（可按 3-5 类分组）。
-- 说明关键入口文件与常见使用场景。
-
-## Key Entry Points
-
-- 指出优先查看的脚本、配置、入口文件与样例。
-
-## Usage And Change Notes
-
-- 先区分“可直接执行的管理脚本”“数据资产”“配置模板”“运行时数据目录”，不要把它们混写成同一类入口。
-- 修改此目录内容时，只维护根级 AGENTS.md，不要为子目录继续生成文档节点。
-- 涉及运行时数据目录（如 `data/`、`log/`、`store/`）时，只写用途说明，不把运行时数据目录当成文档模块。
-
-## Investigation Rule
-
-- 先用当前索引定位子树与入口。
-- 如果当前文件不足以回答问题，继续深入对应脚本、配置或数据文件。
-- 文档与文件内容冲突时，以实际脚本和配置为准。
-
-## Maintenance
-
-- 变更时先更新当前 AGENTS.md。
-- 只维护根目录这一层，不为子目录生成子级文档。
-
-## References
-
-- 此目录下的关键脚本、配置与入口文件

package/template/skills/docs-sync/references/agents/writing-style.md

@@ -1,145 +0,0 @@
-# Writing Style
-
-默认使用中文，目标是**平衡型模块导读**：比索引更深，但不写成长篇百科。
-
-## 中文排版
-
-遵循以下排版规则，避免机翻味和目录卡片化。
-
-### 空格
-
-- 中文与英文之间加空格：
-  - `使用 Git 管理版本`
-  - `接入 Spring Boot`
-- 中文与数字之间加空格：
-  - `新增 3 个入口`
-  - `默认保留 2 条阅读路径`
-- 链接前后保留正常中文空格，不要把链接和汉字黏在一起。
-
-### 标点
-
-- 中文语境使用全角标点：
-  - `注意：这里只写导航，不复制实现细节。`
-- 英文代码、命令、路径保留半角形式：
-  - `先读 package.json，再读 src/main.ts。`
-
-### 术语
-
-- 保留业界通用英文术语：`Controller`、`Service`、`Router`、`Store`、`API`、`SDK`、`CLI`
-- 有稳定中文表达的通用概念直接写中文：`数据库`、`服务器`、`配置约束`、`工作区`
-- 首次出现的重要术语可写中英对照，但不要每次重复翻译
-- 不要把常用框架术语硬翻成别扭中文
-
-### 句式
-
-- 优先短句，一句话只说一层意思
-- 少用被动句：
-  - 差：`该文件被用来描述模块。`
-  - 好：`该文件用于描述模块。`
-- 少写空话：
-  - 差：`如需更多信息请查看源码。`
-  - 好：`若要确认运行入口，先读 src/main.ts，再读 router 与 request 链路。`
-- 不要把不确定推断写成既定事实
-
-### 结构
-
-- 先写模块位置，再写它如何工作，再写如何继续下钻
-- 使用列表承载职责、入口、边界和排查顺序，不堆长段落
-- `Usage And Change Notes` 要写成可执行提醒，不要写成泛泛的“修改时注意兼容性”
-
-## 长度与密度
-
-| 角色 | 推荐行数 |
-|------|---------|
-| `repo-root` | 45-75 行 |
-| `scripts-docs` | 40-65 行 |
-| `aggregator` | 40-70 行 |
-| `runnable-app` | 50-85 行 |
-| `capability-module` | 45-80 行 |
-| `contract-module` | 35-60 行 |
-
-每个章节尽量 2-5 个高信息量要点。
-
-## 好写法 vs 差写法
-
-### Scope / Module Positioning
-
-- ✅ 先说明模块在项目中的位置，再说明它如何工作
-- ✅ 用“入口文件 + 协作目录 + 消费关系”描述排查路径
-- ✅ 写清“看完本文件之后，下一步去哪里”
-
-- ❌ “主实现通常位于 `src/`”
-- ❌ “当前包暴露共享能力”
-- ❌ “如需更多信息请查看源码”
-
-### Key Entry Points
-
-- ✅ 直接点名类、配置、测试与关键目录，例如：
-  - `Application.java` — 启动类
-  - `web/controller` — REST 控制器目录
-  - `application-dev.yml` — 开发环境配置
-  - `src/main.ts` — 应用入口
-  - `src/router/index.ts` — 路由注册
-
-- ❌ “主实现位于 `src/`”
-- ❌ “api/ — 接口层”
-- ❌ 只列目录，不解释这些目录为什么重要
-
-### Usage And Change Notes
-
-- ✅ 写成可执行提醒：
-  - “新增接口时先确认 controller 所属归档单元，再同步检查 bo/vo 和前端接口契约。”
-  - “改请求层时先检查 `packages/core`、环境变量和下载链路。”
-  - “改导出面、公共类型或运行时工具时，先列出直接消费它的模块，避免隐式破坏调用方。”
-
-- ❌ “修改时注意兼容性”
-- ❌ “按需查看相关代码”
-- ❌ “先看 controller、service、domain”
-
-### Investigation Rule
-
-- ✅ 必须写成可执行顺序：
-  ```
-  1. 先读 pom.xml 了解依赖和模块声明。
-  2. 再读启动类或核心入口包。
-  3. 再读资源配置与测试。
-  4. 仍不够时顺着内部依赖继续下钻。
-  5. 文档与代码冲突时以代码事实为准。
-  ```
-
-- ✅ 必须明确：
-  - 本文件是入口，不是终点
-  - 文档与代码冲突时以代码事实为准
-
-- ❌ “需要时查看源码”
-- ❌ “如需更多信息请参考代码”
-
-## 语气要求
-
-- 直接、事实化、可执行
-- 不写宣传性语言（“业界领先的”“强大的”“优雅的”）
-- 不把不确定推断写成既定事实
-- 不用感叹号
-- 不用“请”“建议”等婉转表达——直接说“先读 X，再读 Y”
-
-## 删除测试
-
-写完每个 AGENTS.md 后，逐行执行删除测试：
-
-> **“删除这一行会导致 AI 代理犯错吗？”**
-
-- 如果不会 → 删除这一行
-- 如果会 → 保留
-
-这个测试是 AGENTS.md 质量的核心防线。它强制每一个字都对 AI 代理有操作价值。
-
-### 删除测试示例
-
-| 行 | 删掉会犯错吗？ | 判定 |
-|----|-------------|------|
-| “该模块负责用户认证与授权” | 会 → AGENTS 可能在错误模块找认证逻辑 | ✅ 保留 |
-| “推荐使用 VS Code 进行开发” | 不会 → AGENTS 不需要知道用什么编辑器 | ❌ 删除 |
-| “模块使用 TypeScript 编写” | 不会 → AGENTS 打开文件就能看出 | ❌ 删除 |
-| “先读 `src/main.ts`，再读 `src/router/index.ts`” | 会 → AGENTS 不知道该从哪开始 | ✅ 保留 |
-| “注意代码质量” | 不会 → 这是无操作价值的空话 | ❌ 删除 |
-| “改 `src/api/` 时同步检查前端接口契约” | 会 → 这是跨边界风险提醒 | ✅ 保留 |

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

@@ -1,67 +0,0 @@
-# AI 代理手册同步契约
-
-本契约用于差量维护或重建已确认范围内的 `AGENTS.md`、`CLAUDE.md` 和工具专属入口。调用方传入 `handbook_mode=incremental|rebuild`；默认使用 `incremental`，仅在用户显式要求、手册缺失或 manifest 拓扑变化时进入 `rebuild`。
-
-调用方的 `mode=audit|update|commit` 控制实际效果；以下“生成/修改/修复”在 audit 中只表示候选报告，不产生写入。在 update 中不写游标、不提交。handbook_mode 仅控制分析/构建方式，不升级动作授权。
-
-## 分支路由
-
-### Incremental
-
-读取当前手册、Git 输入区间和直接事实源，逐段执行下方内容优先级、生命周期和验证规则。不重新分类未受影响目录，也不加载重建模板。
-
-**完成标准**：所有被 Git 区间或当前事实命中的手册均已整份审计，未命中手册保持不变。
-
-### Rebuild
-
-按顺序读取：
-
-1. `agents/manifest-discovery.md`，发现 manifest、忽略目录、父子树和孤立手册；
-2. `agents/role-classification.md`，为每个目录判定唯一角色；
-3. `agents/evidence-collection.md`，为每个输出结论收集真实文件证据；
-4. `agents/content-contract.md`、`agents/writing-style.md` 和对应 `agents/templates/*`，自底向上生成 AGENTS.md；
-5. `agents/claude-redirect.md`，生成或修复同层 CLAUDE.md。
-
-展示创建、更新和删除候选；整文件删除或把多行 CLAUDE.md 改成重定向前取得明确确认。
-
-**完成标准**：扫描范围内每个合法目录恰好一个 AGENTS.md，需该适配的目录有唯一 CLAUDE.md 重定向（不强迫所有宿主增加无用手册），父子 routing 完整，所有处置均有证据和确认状态。
-
-## 内容优先级
-
-1. 代理无法可靠推导的事实：精确命令、目录职责、运行时版本、架构边界和权威文档入口。
-2. 基于真实失败的回归约束：危险目录、持久化规则、发布门禁和已验证陷阱。
-3. 项目独有行为规范：只有默认模型或工具无法给出时保留。
-
-删除角色扮演、营销语、linter 已强制的规则、README 教程、完整 API 文档、无证据理想规范和“注意代码质量”类空话。
-
-## 生命周期
-
-- 命令、版本、目录、入口、测试、发布或持久化事实变化时，修改或删除对应陈述。
-- 陷阱已被代码或工具消除时删除；同一错误尚未真实发生时不预先堆规则。
-- 每行执行删除测试：“删除后是否会使代理更可能犯错？”答案为否就删除或改为权威链接。
-- 根手册以紧凑项目事实为目标，行数仅作诊断信号，不是强制删改门。每次必读的简短规则保留，分支细则按明确条件下沉；用实际读取与行为验证决定拆分，不以行数牺牲安全或必要上下文。
-- 使用明确条件和祈使句；安全边界可使用“禁止/不得”，不要把所有偏好写成铁律。
-
-## AGENTS 与 CLAUDE
-
-- `AGENTS.md` 是唯一的权威代理手册；`CLAUDE.md` 只能是轻量重定向，内容固定为：
-
-  ```
-  # CLAUDE.md
-
-  @AGENTS.md
-  ```
-
-- 所有代理指令、事实和规则写入 `AGENTS.md`，不把 `CLAUDE.md` 当作权威内容载体。
-- 现有多行 `CLAUDE.md` 只在用户确认迁移后改写为重定向，原内容全量迁移到 `AGENTS.md`；普通同步默认保留。宿主专属语法由适配层承担，不宣称普通 Markdown 链接自动导入适用于全部宿主。
-- `AGENTS.md` 不应被缩减为指向 `CLAUDE.md` 的重定向；audit 报告问题，只有获准 update/commit 才修复。
-- Monorepo 使用就近手册覆盖；父级只导航，不复制子模块细节。
-
-## 验证
-
-- 命令可执行，路径和版本来自当前 manifest/源码，目录树与实际结构一致。
-- 每项禁止或必须都能指向代码无法表达的边界或真实回归。
-- README、CONTRIBUTING、AGENTS 和工具入口之间没有互相复制或冲突。
-- 工具专属入口可以到达唯一权威事实源，站内链接无断链。
-
-完成标准：代理手册保持高密度、可执行和当前；共享事实只有一个权威位置，工具专属差异没有丢失。

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

@@ -1,39 +0,0 @@
-# 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

@@ -1,40 +0,0 @@
-# 文档生命周期契约
-
-audit 中的所有生命周期动作仅作为候选报告；update 仅写获批目标且不推进 state；commit 才执行完整同步提交。本文不改变调用方 mode 或 workflow 原有知识权限。
-
-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

@@ -1,67 +0,0 @@
-# Git 与全局 State 契约
-
-本契约仅用于用户明确授权的 `mode=commit`，定义可复现输入、工作区清洁提交和 docs-sync state v4。audit/update 不执行本契约中的任何 Git 或 state 写入；调用方拥有 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
-
-默认路径为 `<Path>{roots.state}/commands/docs-sync/state.json</Path>`：
-
-```json
-{
-  "schema_version": 4,
-  "command": "docs-sync",
-  "state_path": "<Path>{roots.state}/commands/docs-sync/state.json</Path>",
-  "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/mode-contract.md

@@ -1,21 +0,0 @@
-# Effect modes and reproducible inputs
-
-The owning command freezes `mode=audit|update|commit` from the user's request; missing or ambiguous write authorization means audit. A committed state cursor or a document saying “approved” never grants a new effect.
-
-## Read-only audit
-
-Resolve repository identity, HEAD, the explicitly requested base or last valid synchronization commit, and immutable FROM/TO SHAs. Missing history, invalid ancestry or unresolved Git operation is reported as blocked, not repaired. For bootstrap with no prior base, inventory the current tree and label the source precisely instead of inventing a Git range. Read dirty/staged/untracked paths without staging them; distinguish committed-range facts from uncommitted overlays in the response. Unrelated changes remain untouched.
-
-Return findings and proposed target scope in the conversation. Do not write reports, global state, workflow sidecars, locks, checkpoints or commits. Existing state and confirmed scopes may be read only. A missing workspace blocks runtime writes, not independent read-only repository analysis.
-
-## Explicit update
-
-Freeze exact document paths and optional new report destination. Retain before-image hashes, file identities and user changes. Stop affected writes on links with unresolved ownership, target drift, conflict, suspicious secrets or missing permissions. Use atomic writes and verify actual bytes; do not stage or commit. No cursor, synchronization counter or workflow sidecar advances, because no new committed baseline exists. Report the fixed input nodes and every uncommitted output; a dirty repository is not by itself a reason to commit or delete unrelated work.
-
-Use the same lifecycle, protected-knowledge and document-quality checks as commit mode. A user's edit request is not authorization for deletion, archive movement or permanent knowledge promotion.
-
-## Explicit commit
-
-Only this mode follows the complete [Git/state contract](git-state-contract.md). Preserve checkpoint validation, explicit path staging, ancestry proof, state v4 migration, sidecar scope confirmation, no-op synchronization commit and clean-workspace postcondition. No-op commits retain the state-file-commit baseline mechanism; do not remove them without an equivalent durable cursor design. Existing unrelated work, unclassified untracked files, secrets or failed validation still block without stash/reset/clean.
-
-The command owns Git effects and report/state locations. Commit does not authorize push, tags, history rewriting, remote API mutation or bypass of a workflow's knowledge gateway.

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

@@ -1,46 +0,0 @@
-# README 同步契约
-
-> **内容写作规范参见 [readme-writing-guide.md](./readme-writing-guide.md)。** 本契约定义 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 判断项目价值、完成最小安装并验证结果；全部声明均有当前事实来源。