@namewta/speculo 1.0.24 → 2.0.1

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 判断项目价值、完成最小安装并验证结果；全部声明均有当前事实来源。

package/template/skills/docs-sync/references/readme-writing-guide.md

@@ -1,294 +0,0 @@
-# README 写作指南
-
-README 面向首次接触项目的读者，需要在约 5 秒内回答三个问题：**这是什么、怎么用、值不值得用**。本指南定义 Speculo 项目的通用 README 结构与写作规范，供 `docs-sync` 及其他命令在生成或审计 README 时引用。
-
-> **同步规则参见 [readme-contract.md](./readme-contract.md)。** 本指南定义"写什么内容"（内容规范）；readme-contract.md 定义"何时同步、如何验证"（同步契约）。两者互补。
-
-## 九段式结构
-
-项目简单时合并相邻章节，README 很长时把 API、架构解释和贡献流程移到对应文档。以下九段覆盖从"吸引注意"到"引导参与"的完整认知漏斗。
-
-| # | 段落 | 用途 | 缺失后果 |
-|---|------|------|----------|
-| 1 | **Header** | 项目名 + 一句话定位 + 徽章栏 + 语言切换 | 读者不知道项目是否活跃、能否跨语言阅读 |
-| 2 | **About** | 价值主张 + 内容概览 + 独特卖点 | 读者无法快速判断项目是否解决他的问题 |
-| 3 | **Quick Start** | 前置条件 → 安装命令 → 预期输出 | 读者放弃尝试 |
-| 4 | **Project Structure** | ASCII 目录树 + 命名规范 | 读者不知道从哪里入手改代码 |
-| 5 | **How to Study / Use** | 分步学习或使用方法 | 读者不知道怎么消化内容 |
-| 6 | **Tech Stack** | 组件-包名-用途三列表 | 读者不知道需要什么依赖 |
-| 7 | **Contributing** | Fork → Branch → Convention → Test → PR | 潜在贡献者不知道流程而放弃 |
-| 8 | **License** | 类型 + LICENSE 文件链接 | 读者不确定能否合法使用 |
-| 9 | **Footer** | 社区链接 + 跨语言导航 | 读者不知道怎么联系或获取更多信息 |
-
----
-
-### 1. Header
-
-**应包含：**
-- 项目名居中（`<h1 align="center">Project Name</h1>`）
-- 一句话 tagline —— 说明输入、输出或解决什么问题，删除空泛营销语
-- 徽章栏：License、语言版本、包管理器、Stars、PRs、CI 状态等
-- 语言切换链接：`[中文](./README-ZH.md)` ← → `[English](./README.md)`
-
-**不应包含：**
-- 超过一行的冗长描述（放到 About 段）
-- 失效或状态无价值的徽章
-
-**示例：**
-
-```markdown
-<h1 align="center">My Project</h1>
-<p align="center"><em>A one-line description of what it does.</em></p>
-<p align="center">
-  <a href="./README-ZH.md">中文</a>
-</p>
-<p align="center">
-  <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT">
-  <img src="https://img.shields.io/badge/Python-3.10+-green.svg" alt="Python 3.10+">
-  <img src="https://img.shields.io/github/stars/owner/repo?style=flat" alt="Stars">
-</p>
-```
-
----
-
-### 2. About
-
-**应包含：**
-- 一段清晰的价值主张：这个项目解决什么痛点、为谁解决
-- 内容/功能概览表（若为学习型仓库：模块列表；若为工具型：核心功能）
-- 1-3 个独特卖点（why this project over alternatives）
-
-**不应包含：**
-- 实现细节（放到项目结构或文档链接）
-- 安装步骤（放到 Quick Start）
-- 与其他项目逐行对比（冗长且容易过时）
-
-**示例（学习型仓库）：**
-
-```markdown
-## About
-
-My Project 是一套从零到生产就绪的 XYZ 学习路线，每个模块以"带注释的可运行脚本"而非教程形式呈现 — 代码即教材。
-
-| # | 模块 | 覆盖内容 |
-|---|------|----------|
-| 01 | Getting Started | 环境搭建、Hello World |
-| 02 | Core Concepts | 核心抽象与生命周期 |
-| ... | ... | ... |
-```
-
----
-
-### 3. Quick Start
-
-**应包含：**
-- **前置条件**：运行时版本、系统依赖、必需的 API key 等
-- **一步安装命令**：`npx`、`git clone`、`pip install` 等，可复制粘贴
-- **预期输出**：读者执行后应该看到什么才算成功
-- 预计耗时在 60 秒以内
-
-**不应包含：**
-- 长篇背景解释
-- 多分支安装路径（初学者只需一条"最快路径"）
-
-**示例：**
-
-```markdown
-## Quick Start
-
-**前置条件：** Node.js >= 22、npm >= 10
-
-```bash
-npx my-package init
-```
-
-预期输出：
-
-```
-✔ Project initialized at ./my-project
-✔ 3 files created
-```
-```
-
----
-
-### 4. Project Structure
-
-**应包含：**
-- ASCII 目录树（第一层级，不超过 2 层深度）
-- 关键命名规范说明（文件前缀、目录约定等）
-- 每个顶级目录的一句话用途
-
-**不应包含：**
-- 完整展开的文件树（冗长且随 commit 快速过时）
-- 每个文件的详细说明（放到各自模块的文档中）
-
-**示例：**
-
-```markdown
-## Project Structure
-
-```
-.
-├── src/            # 源代码
-├── tests/          # 测试（文件名 = test_<module>.py）
-├── docs/           # 详细文档
-├── scripts/        # 运维/CI 辅助脚本
-├── pyproject.toml  # 项目元数据与依赖
-└── README.md
-```
-
-命名规范：源文件使用 `snake_case.py`，测试文件使用 `test_` 前缀。
-```
-
----
-
-### 5. How to Study / Use
-
-此节因项目类型而异：
-
-**学习型仓库：** 四步学习法
-```markdown
-## How to Study
-
-1. **选择模块** — 按编号顺序，每模块构建在前一模块之上
-2. **阅读注释** — 每个脚本包含详尽的中文注释，解释每行代码的"为什么"
-3. **运行脚本** — `python main-<NN>-<topic>.py`，观察输出
-4. **动手实验** — 修改参数、打破代码、修复它
-```
-
-**工具/库型仓库：**
-```markdown
-## Usage
-
-```python
-from mylib import Thing
-t = Thing(config)
-result = t.do("input")
-```
-
-详见 [docs/](./docs/)。
-```
-
----
-
-### 6. Tech Stack
-
-**格式：** 组件-包名-用途三列表，按层或类别分组。
-
-**应包含：**
-- 核心运行时与框架
-- 关键依赖（用户需要知道的，不是全部 `node_modules`）
-
-**示例：**
-
-```markdown
-## Tech Stack
-
-| 组件 | 包名 | 用途 |
-|------|------|------|
-| Runtime | Python 3.10+ | 主运行环境 |
-| Package Manager | uv | 依赖管理与虚拟环境 |
-| LLM Framework | langchain | 大语言模型编排 |
-| Vector Store | chromadb | 嵌入式向量存储与检索 |
-```
-
----
-
-### 7. Contributing
-
-**应包含：**
-- Fork → Branch → Convention → Test → PR 简洁流程
-- Commit 规范（如 Conventional Commits）
-- 在哪提 issue、讨论设计
-
-**不应包含：**
-- 完整的 CLA 法律文本（链接到 CONTRIBUTING.md）
-
-**示例：**
-
-```markdown
-## Contributing
-
-1. Fork 本仓库
-2. 从 `main` 分支创建功能分支：`git checkout -b feat/my-feature`
-3. 提交遵循 [Conventional Commits](https://www.conventionalcommits.org/)
-4. 确保现有测试通过并添加新测试
-5. 提交 PR 并描述改动原因
-
-欢迎提 issue 讨论新功能或报告 bug。
-```
-
----
-
-### 8. License
-
-**格式：** 一句话 + LICENSE 文件链接。
-
-```markdown
-## License
-
-MIT © [Author] — 详见 [LICENSE](./LICENSE) 文件。
-```
-
----
-
-### 9. Footer
-
-**应包含：**
-- 社区/联系链接（GitHub Discussions、Discord、Twitter 等）
-- 跨语言 README 跳转链接（与 Header 的徽章栏中的语言切换呼应）
-
-```markdown
----
-
-<p align="center">
-  <a href="./README-ZH.md">中文文档</a>
-  &nbsp;·&nbsp;
-  <a href="https://github.com/owner/repo/discussions">Discussions</a>
-  &nbsp;·&nbsp;
-  <a href="https://github.com/owner/repo/issues">Report Bug</a>
-</p>
-```
-
----
-
-## 双语言原则
-
-遵循 [readme-contract.md](./readme-contract.md) 中的铁律：
-
-- **`README.md` 始终为英文（EN）。** 与之配对的是 `README-ZH.md`，为一对一的中文翻译镜像。
-- 两文件顶部互相提供可点击跳转链接。
-- 结构完全对称，内容一一对应。标题顺序、命令、代码块、URL、表格字段保持对等；代码实体不翻译。
-- `README.md` 内容变更时，`README-ZH.md` 必须在同一次同步中完成对应更新。
-
----
-
-## 与其他资产的关系
-
-| 资产 | 路径 | 关系 |
-|------|------|------|
-| readme-contract.md | `./readme-contract.md` | 同步规则与验证契约 —— 定义**何时更新**、触发条件、多语言铁律 |
-| document-lifecycle-contract.md | `./document-lifecycle-contract.md` | 文档生命周期 —— 定义**如何决定** add/update/delete/merge |
-| docs-sync SKILL.md | `../SKILL.md` | 编排 skill —— 调用本指南与 readme-contract.md 协同完成 README 审计 |
-| 项目文档创建与维护规范 | `temp/项目文档创建与维护规范.md` | 背景参考 —— 综合 50+ 来源的文档规范研究（非运行时依赖） |
-
----
-
-## 验证清单
-
-生成或审计 README 时逐项检查：
-
-- [ ] Header 有项目名、tagline、徽章栏（至少 License + 语言版本）、语言切换链接
-- [ ] About 在 3 秒内回答"这个项目是做什么的"
-- [ ] Quick Start 可在 60 秒内完成并看到预期输出
-- [ ] 安装命令可复制粘贴执行
-- [ ] Project Structure 树与实际目录布局一致
-- [ ] Tech Stack 表与 `package.json` / `pyproject.toml` 等 manifest 文件中的核心依赖一致
-- [ ] Contributing 有可执行步骤
-- [ ] License 类型与实际 LICENSE 文件一致
-- [ ] Footer 有语言切换和社区链接
-- [ ] 无过期命令、路径、参数、徽章、链接
-- [ ] `README-ZH.md` 与 `README.md` 同步更新
-
-逐段删除测试：删掉后不影响采用决策或正确使用的内容应压缩、下沉或删除。

package/template/skills/docs-sync/references/workflow-scope-contract.md

@@ -1,52 +0,0 @@
-# Workflow 范围契约
-
-docs-sync 必须遵循每个 workflow 的 `INDEX.md`。`docs-sync.json` 是 command 拥有的标准延迟 sidecar，不属于 workflow `_state` 固定骨架。
-
-模式边界：audit 只报告候选；update 只使用本次明确批准的目标且不写 sidecar；以下所有 sidecar 创建、迁移和确认持久化仅用于 commit。
-
-## 发现
-
-1. 从 `<Path>{roots.workflows}/{workflow}/INDEX.md</Path>` 发现已安装 workflow。
-2. 每个包必须有匹配的 `<Path>{roots.state}/{workflow}/</Path>` 状态根；包或状态根单边缺失时阻塞，不猜测归属。
-3. 读取 `INDEX.md` 的发现声明；仅需解析合同或写入 owner 时，再按该入口显式指向的 README/contract 读取对应部分，不假设每个 INDEX 都包含运行合同。
-4. 状态根存在但没有已安装 package 时只报告 orphan，不创建 sidecar。
-
-## Sidecar v1
-
-每个已安装 workflow 首次获准的 commit 同步才创建：
-
-```json
-{
-  "schema_version": 1,
-  "workflow": "example",
-  "manifest_path": "<Path>{roots.state}/example/docs-sync.json</Path>",
-  "project_targets": [],
-  "state_targets": [],
-  "scope_revision": 1,
-  "scope_confirmed_at": "ISO-8601"
-}
-```
-
-目标使用 `{ "path": "...", "kind": "file | directory" }`：
-
-- `project_targets` 使用项目相对路径，记录该 workflow 负责维护的项目文档。
-- `state_targets` 使用 workflow 状态根相对路径，只能位于 `consumers` 包含 `docs-sync` 的已声明 store。
-- Directory 目标递归覆盖其中已跟踪的 Markdown、MDX、reStructuredText 和 AsciiDoc；其他格式必须作为 file 明确列出。
-- 禁止绝对路径、反斜杠、`..`、项目根目录、无界 glob、`.git`、固定 `status.json/changes/archive` 和 sidecar 自身。
-
-## 首次确认与修订
-
-1. Bootstrap 同时展示全局候选，以及每个 workflow 的 project/state 候选、来源和风险。
-2. 用户一次确认后写入全局 state 与全部 sidecar；没有候选的 workflow 也写空清单。
-3. 一个目标只能归属全局或一个 workflow；重叠、父子目录交叉或同一路径多 owner 必须先消歧。
-4. 后续新增、扩大、移除或转移目标必须再次展示完整新范围；确认后增加 `scope_revision` 并更新时间。
-5. 首次确认只授予范围内常规创建和改写，不授权整文件/目录删除或受保护知识写入。
-
-## Archive 与知识
-
-- 固定 archive 始终可作为只读证据；优先读取本次区间新增或变更、且与受影响模块或术语相关的高信号产物。
-- 归档中的稳定决策、术语、经验和文档漂移信号只提炼结论并保留来源路径，不复制大段正文。
-- `existing-only` store 永远只读。RULES/policy、ADR、CONTEXT、语义冲突和任何知识文件删除均进入 `propose-only`，按目标 workflow 规则取得逐次确认。
-- 不跨 workflow 搬运知识；共享结论必须先确认唯一归属。
-
-完成标准：commit 模式所有已安装 workflow 都有有效 sidecar；audit/update 不产生 sidecar；每个有效目标都有唯一 owner、声明边界和确认记录；所有受保护动作均未越权。