@namewta/speculo 1.0.22 → 2.0.1

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

@@ -0,0 +1,30 @@
+---
+id: archive-and-consolidate
+description: 将用户选择的归档或知识整理请求交给 owning workflow Work，并返回其计划与执行回执。
+---
+
+# Archive and Consolidate
+
+本命令只拥有目标选择、授权核对与调用报告；归档、知识和领域状态由对应 Work 拥有。不以一个通用移动流程代替领域合同。
+
+## 定位与路由
+
+1. 从项目入口或当前目录向上定位字面路径 `.agents/speculo/.speculo/workspace.json`，唯一确定 project_root，验证 path_base 与 roots；之后才使用 alias。SpecDev 无安装时可传明确 projectRoot/methodRoot/stateRoot，由其新根合同验证；其他领域保持原安装/状态语义，缺失仅阻塞依赖的操作。配置 `<Path>{roots.config}</Path>` 缺失可使用领域默认值，不降低授权要求。
+2. 从用户请求和领域 `<Path>{roots.workflows}/{workflow}/SKILL.md</Path>`、manifest 定位真实 Work。已明确的目标和模式直接复用；只有多个合理候选或意图冲突才消歧。
+3. SpecDev 交给 `<Path>{roots.workflows}/specdev/specdev-a-archive-and-consolidate/SKILL.md</Path>`，传入经验证的新根上下文、指定 change/知识主题、dry-run/confirmed 和已批准动作；Work 自己维护完成门、知识网关及恢复。
+4. Learning 按请求交给 `<Path>{roots.workflows}/learning/learning-c-consolidate/SKILL.md</Path>` 或 `<Path>{roots.workflows}/learning/learning-a-archive/SKILL.md</Path>`。C 拥有递归 source/parent lock、relocation 与 synthesis；A 只归档用户 close/confirm 的 root 树，按最新源更新时间选月份，不要求 Homework、R 或 mastery。冷归档树要先经明确恢复才能移动。
+5. OPS、Person、Media 当前没有归档 Work，返回 `unsupported` 和真实入口，不创建或移动通用 change archive。无候选返回 `no-candidates`，不自动启动代码访谈。
+
+## OPS 资源运行记录
+
+OPS 的 host/project/deployment/run 是资源账本，不套用 change 归档。读取 `<Path>{roots.workflows}/ops/SKILL.md</Path>` 定位原资源入口；冷备份证据需独立明确范围并保留哈希和引用，本命令不删除账本、不移动主机/APP 数据、不代写 OPS 状态。
+
+## 授权与报告
+
+先取得 Work 具体计划，统一展示目标、移动/提升/清理动作、输入摘要和恢复边界。同一具体批准由本命令与 Work 核对并复用，不逐层重复确认；新增动作、范围或摘要漂移只阻塞受影响执行。笼统“完成后整理”不替代尚未确定的删除/永久知识计划。
+
+规范报告是 `<Path>{roots.state}/commands/archive-and-consolidate/{date}-{scope}-{topic}[-NN].md</Path>`：scope 为 workflow，topic 为 change 或 batch；从 -01 选最小未用编号，原子写入，不覆盖旧报告。`path_context.commands_root` 必须等于解析后的 `{roots.state}/commands`；报告不写 `{roots.commands}` 或 workflow 私有目录。错误报告路径只阻塞该持久化，不把历史误落盘文件搬迁作为本次无关操作的前置门。
+
+纯 dry-run 在会话返回，零文件写入；用户要求保存计划或已授权执行时，由 Command 保存调用报告，Work 返回结构化回执。报告包括选择、具体授权、输入摘要、relocation/archive locator、知识结果、验证和部分失败恢复点。涉及 DESIGN 时保留 plan/current/candidate 摘要、批准来源、revision 与发布检查点。Command 不成为知识 writer。
+
+完成标准：选定 Work 或明确无候选/不支持；结果符合授权；应执行的领域动作与回读已完成，部分失败如实列出；文件报告只有规范路径。直接调用 Work 不要求创建 Command 报告。

package/template/commands/docs-sync/COMMAND.md

@@ -0,0 +1,25 @@
+---
+id: docs-sync
+description: 用户手动触发的一次全局文档盘点、整理与管理；按授权审计、更新或提交本次目标。
+---
+
+# Docs Sync
+
+本命令管理项目文档、AGENTS、项目 Skills 与指令资源；Git diff 提供变化线索，不限制全局盘点。普通开发任务不自动触发本命令，也不借文档整理执行业务、归档或发布。
+
+## 模式与 owner
+
+- `audit`（默认）：会话报告，零文件、Git 或 state 写入。
+- `update`：用户已要求整理或修改文档，更新授权范围及可选新报告；不暂存、不提交、不推进游标。
+- `commit`：用户明确要求提交本次文档整理，完成更新并仅提交获批目标及必要报告/state。提交不授权 push、tag、stash、清理或历史改写。
+
+同一具体授权由本命令核对并复用；全局分析范围不等于全局写入权限。整文件删除、受保护知识和范围外目标需要相应明确授权，已有覆盖该动作的批准不重复询问。
+
+## 执行
+
+1. 定位项目根及 Git HEAD；需要 runtime 时从项目入口字面路径 `.agents/speculo/.speculo/workspace.json` 解析 roots，再按需读 `<Path>{roots.config}</Path>`。workspace 缺失仅阻塞 runtime 写入，独立审计和获批项目文档编辑继续。
+2. 读取 `<Path>{roots.commands}/docs-sync/references/operation-contract.md</Path>`，传入 mode、项目根、固定输入节点、已有授权和文档 owner，完成全局盘点、处置及验证。
+3. 本命令拥有报告 `<Path>{roots.state}/commands/docs-sync/{date}-{scope}-{topic}[-NN].md</Path>`；从 `-01` 选最小未用编号，原子写入且不覆盖。只有 commit 使用 `<Path>{roots.state}/commands/docs-sync/state.json</Path>` 和实际纳管 workflow 的 `<Path>{roots.state}/{workflow}/docs-sync.json</Path>`，sidecar 不属于 workflow `_state` 种子。
+4. 回读实际结果。audit 返回发现，update 标记 `not-committed`，commit 验证本次提交和无关工作区/暂存内容保持不变。没有实质内容、范围或基线变化时返回 `no-op`，不为运行次数或报告制造提交。
+
+完成标准：全局清单中的每个目标有结论，获批动作完成并验证，未授权候选和阻塞有明确 owner/下一步；仅完整完成的同步范围可推进基线。局部阻塞不停止独立且已授权的工作。

package/template/commands/docs-sync/assets/agents-template.md

@@ -0,0 +1,19 @@
+# <项目或模块> Agent Handbook
+
+此骨架只供新建/重建选择内容。删除无实际信息的占位节，按任务需要合并、排序；子手册仅增加父级没有的规则。
+
+## 项目事实
+
+<本作用域、真实源/生成物、需要知道的运行前提；易变详情指向配置正本。>
+
+## 任务入口
+
+<任务条件 → 入口与直接参考 → 要解决的问题。仅列真实存在且帮助定位的路径。>
+
+## 边界与停止条件
+
+<项目独有的 owner、权限、持久化及恢复边界；复用有效授权，仅阻塞受影响分支。>
+
+## 验证与完成
+
+<按改动风险选择实际可运行的检查；完成证据、未完成项与恢复入口。>

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

@@ -0,0 +1,32 @@
+---
+command: docs-sync
+mode: <audit|update|commit>
+result: <completed|not-committed|no-op|partial|blocked>
+scope: <workspace|explicit-subtree>
+workflows: []
+generated_at: <ISO-8601>
+---
+
+# 文档整理报告
+
+## 输入与覆盖
+
+- 项目、固定 HEAD、FROM_SHA 或 bootstrap/non-git：<实际值>
+- 变化线索复现：<git diff FROM_SHA..INPUT_HEAD，或无基线原因>
+- 全局盘点范围、文档总量、排除/只读目录与理由：<清单>
+- 未提交 overlay 及事实限制：<路径和影响，不抄敏感内容>
+
+## 处置与效果
+
+| 目标 | Owner | 处置 | 事实证据 | 授权 | 实际结果/恢复 |
+|---|---|---|---|---|---|
+
+<覆盖每个纳入目标和新增缺口。audit 全为候选；propose-only 注明原网关；未完成项不写成已执行。>
+
+## 验证
+
+<实际命令、退出码、相关结果、未验证行为；没有变化时说明 no-op。>
+
+## 提交与状态（仅 commit）
+
+<批准路径、提交 SHA/父节点、无关 index/工作区保持情况、state v4 与实际 sidecar v1；无提交或失败时说明原因与候选状态恢复位置。audit/update 不推进游标。>

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

@@ -0,0 +1,27 @@
+# AGENTS 与工具入口
+
+AGENTS 保存项目独有事实、任务入口、作用域边界与验收；不能变成 README 教程、目录百科或通用编程规范。默认增量修正内容；缺手册、实际作用域变化或用户要求重建时读 [发现与重建](handbook-discovery.md)。全局盘点覆盖所有自有手册，增量指修订方式，不是只审查 diff 命中文件。
+
+## 内容选择
+
+保留精确任务命令、难以发现的入口、架构/所有权边界、真实回归陷阱和完成标准。可从工具直接可靠获得的冗长枚举改为事实源指针；必要的短命令与安全提醒可以就近保留。与当前实际全局规则重复的通用要求删除或收敛，无法确认宿主默认行为时不凭模型升级推断规则无用。
+
+参考 [最小骨架](../assets/agents-template.md)，按项目需要组合：项目事实、任务入口、边界与停止条件、验证与完成。没有事实支撑的章节省略，不固定 13 章或字数。模块手册仅说明相对父级的独有内容，父级负责导航；目录划分本身不要求新手册。
+
+规则按任务触发：先定位目标及直接调用方，再读取当前分支资料；已加载且未变化内容不重读。普通修正不强制通读、备份、全源字符统计或全套测试。授权可复用，阻塞限于受影响分支；必要安全边界、数量、工具和恢复义务保留。
+
+## CLAUDE 适配
+
+有独立 AGENTS 作用域且需要 Claude 适配时，新增或明确由工具拥有的 CLAUDE.md 使用三行导入：
+
+```markdown
+# CLAUDE.md
+
+@AGENTS.md
+```
+
+已有用户内容默认保留。只有获批迁移时，完整保留其事实与宿主特定约束到 AGENTS/相应适配说明，再改成导入。已覆盖同一迁移的授权不重复询问。其他宿主不被强制创建 CLAUDE；普通 Markdown 链接不等于宿主导入。
+
+## 完成
+
+事实、路径、命令和作用域与项目一致；README、AGENTS、项目 Skill 之间没有重复权威或冲突。各适用任务能定位必要资料、验证和完成标准，不产生无依据门禁。写入效果服从调用方 audit/update/commit，结构检查不认证宿主实际调用。

package/template/commands/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. 使用调用方本次固定的 FROM_SHA/INPUT_HEAD 读取完整 diff（audit/update 不依赖写回 state；bootstrap 盘点当前事实），而不是把 `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/commands/docs-sync/references/git-state-contract.md

@@ -0,0 +1,39 @@
+# 本次目标的 Git 与 state
+
+仅 `mode=commit` 使用。调用方负责 Git 与持久化，audit/update 不执行任何提交或游标写入。保留 state v4 与 sidecar v1。
+
+## 固定输入与写集
+
+1. 记录仓库、分支和 `INPUT_HEAD`，核对没有未结束的 merge/rebase/cherry-pick/revert/bisect 或冲突。固定输入后 HEAD 变化则停止本次提交，重新确定输入。
+2. 用 `git status --short` 与 staged/unstaged/untracked 清单区分本次写集与无关内容；`git diff --check` 及其 `--cached` 检查只针对显式本次路径，无关文件的格式问题不阻塞提交。记录写集的 before-image 和无关 index 条目/工作区内容；发现密钥只报告位置，不把内容写入报告。
+3. 不创建 checkpoint workspace commit，不要求全仓干净。无关脏文件和暂存内容保留；目标已有用户改动时保留原文，仅在本次授权涵盖拟提交完整内容时纳入，无法区分的重叠写集阻塞。
+4. 文档事实来自固定已提交输入；如果结论依赖未提交业务事实，可完成分析或获批更新，但本次 commit/同步基线阻塞，不能用自动提交业务代码解决。仅作导航、不影响结论的无关脏文件不构成阻塞。
+5. 在独立临时目录导出 `INPUT_HEAD` 的跟踪树，叠加本次候选文档，运行受影响的项目验证；不把无关脏文件带入验证证据。纯链接/格式检查可直接核对本次目标。保存命令、结果及输入摘要。
+
+## State v4 与输入基线
+
+全局路径 `<Path>{roots.state}/commands/docs-sync/state.json</Path>`，字段与 [state 模板](../assets/state-template.json) 一致。
+
+- `baseline.mode=state-file-commit`：`git log -1 --format=%H -- "$STATE_FILE"` 是 FROM_SHA；必须实际找到该文件的提交。
+- `baseline.mode=explicit`：使用 `baseline.sha`，null 表示 bootstrap。
+- 非空 FROM_SHA 必须是 INPUT_HEAD 的祖先；缺失历史、未知 schema 或不合法 SHA 只阻塞提交/游标，保留原数据。
+- `last_range` 保存 `{from_sha: FROM_SHA, to_sha: INPUT_HEAD}`。非 bootstrap 可用 `git diff "$FROM_SHA..$INPUT_HEAD"` 复现变化线索；完整审查证据绑定 INPUT_HEAD 当前树，不局限于 diff。
+- `project_targets` 保存全局管理目标；workflow 目标依据 [范围合同](workflow-scope-contract.md)。owner 转移同时更新有关记录。
+
+仅遇到 v1-v3 state 才迁移：tracked_docs/tracked_assets 放入 pending_legacy_targets，synced_docs 映射 synced_assets，baseline 使用 explicit/旧 last_sync_sha，last_range 使用 previous_sync_sha/last_sync_sha；不将旧路径当授权。核对实际范围并复用当前有效批准，成功提交后清空 pending，切换 state-file-commit。移除旧 short SHA、标题/日期等派生字段。未知版本保留并阻塞。
+
+## 何时持久化
+
+先完成全局清单，再判断：有实际文档变化、确认范围/迁移变化，或已完整审查的新输入基线，才写必要报告、state 和相关 sidecar。更新 last_range、实际 synced_assets、运行时间与 total_syncs；范围改变才增加 scope_revision。没有上述变化时直接返回 no-op，不因时间戳、计数或生成报告制造提交。
+
+新范围的所有必需动作和验证都完成后才推进游标。尚未授权的知识建议可作为 propose-only 交回 owner，不写成已同步资产；必需工作 blocked 时保留分析/获批文档结果，state 与 sidecar 不推进。
+
+## 仅提交本次目标
+
+1. 在同目录临时文件准备 state/sidecar/报告，重验目标摘要、HEAD 与无关 index，原子替换并重读。报告选择新编号不覆盖；state 不保存 diff、批准原文、绝对路径或秘密。
+2. 建立显式项目相对文件列表，包含本次授权文档及必要报告/state/sidecar。对已有和新增文件按字面路径暂存；使用 `git --literal-pathspecs add -A -- <本次文件列表>`，再用 `git --literal-pathspecs commit --only -m <消息> -- <同一文件列表>`，让无关暂存内容留在 index。目标根、glob、`git add .` 不作为文件列表。删除路径必须已有删除授权。
+3. 文档修改使用 `docs(docs-sync): synchronize project documentation`；只有确需记录新基线或范围且无文档变化时，使用 `chore(docs-sync): record no-op synchronization`。这是必要 state 提交，不是每次运行都要求的空提交；不使用 --allow-empty。
+4. 成功后核对提交父节点等于 INPUT_HEAD、变更路径仅在批准列表、提交内容与验证快照一致；比较无关工作区内容与 index 条目保持不变。本次目标与提交一致即可，不要求全仓 status 为空。
+5. 回读 state 与 sidecar，确认其文件历史定位本次输出 commit；下次 FROM_SHA 因而跳过本次文档/报告提交。
+
+提交失败时保留候选文档、暂存内容、原 state before-image 和命令证据，不 reset、stash、clean、amend 或盲目重试。恢复先检查 HEAD/实际提交：若 commit 未创建，未提交的 state/sidecar 仅是候选，不得被下一次运行当作已推进基线；从最近已提交 state（首次运行用 before-image）恢复本次输入后续作，重新核验写集与授权。已创建的 commit 不重复提交；任何不一致只阻塞受影响后续操作。

package/template/commands/docs-sync/references/handbook-discovery.md

@@ -0,0 +1,11 @@
+# 手册发现与重建
+
+仅手册缺失、作用域变化或用户要求重建时读取。manifest 是线索，不是创建/删除手册的许可。
+
+1. 枚举现有自有 AGENTS/CLAUDE、manifest 和项目入口，排除依赖、缓存、生成目录及第三方原件；已跟踪的特殊目录按其真实 owner 判断。典型 manifest 包括 package.json、pom.xml、build.gradle(.kts)、Cargo.toml、go.mod、pyproject.toml、setup.py/setup.cfg、CMakeLists.txt/Makefile、Gemfile、mix.exs、pubspec.yaml、composer.json、build.zig、*.csproj/*.fsproj、Package.swift、*.cabal/stack.yaml、flake.nix/default.nix。同目录多个 manifest 结合真实构建入口判断，保留辅助证据，不硬选与项目实际相反的主 manifest。
+2. 从独有约束确定作用域：根项目、聚合模块、应用、能力/契约模块、scripts/docs 是定位角色，不是必填章节或强制铺设目录。无 manifest 的安全、部署、测试或生成边界也可有手册；无独有规则就复用父级。
+3. 为候选作用域收集直接证据：入口与装配、公开接口、构建/测试脚本、配置、上游消费方、所有权及真实失败记录。能从仓库回答的问题不转交用户；不凭目录名编造职责。
+4. 按实际手册作用域构建父子关系；父级指向最近子级，子级只维护自己的差异。使用 [最小骨架](../assets/agents-template.md)，由具体证据填写、裁剪和排序，不强制章节或引用数量。
+5. 将失效且无独有约束的手册列删除候选，依 [手册合同](agents-contract.md) 处理工具导入。没有 manifest 不是删除依据；用户手册、第三方文件和缓存中的文件不因全局扫描自动清理。
+
+完成标准：每个现有自有手册及新建候选都有处置，必要边界有入口，父子路由可达；所有生成陈述有证据，删除与迁移符合实际授权。

package/template/commands/docs-sync/references/operation-contract.md

@@ -0,0 +1,62 @@
+# 全局文档整理
+
+仅在用户手动调用 docs-sync 或明确要求全局文档整理时使用。调用方拥有 mode、授权、报告和 Git/state；本合同不创建独立 Skill 状态。
+
+## 模式与输入
+
+| Mode | 选择依据 | 允许效果 |
+|---|---|---|
+| audit | 检查/审查请求，或未授权修改 | 只读盘点，结果在会话返回；无文件、checkpoint、sidecar、暂存或提交 |
+| update | 用户要求整理或修改文档 | 写获批文档与可选报告；不推进游标、同步计数或 workflow sidecar |
+| commit | 用户明确要求提交整理结果 | 更新并提交本次目标；仅此模式读取 [Git/state 合同](git-state-contract.md) |
+
+冻结项目身份、HEAD、可用的上次同步节点或用户指定范围；缺少基线时标记 bootstrap，不虚构 SHA。盘点 staged/unstaged/untracked 的路径、内容和归属，将未提交 overlay 与已提交事实分开。非 Git 项目仍可 audit/update，commit 需要可验证的 Git 输入。未知历史或状态只阻塞依赖它的提交/游标，不阻塞独立文档审查。
+
+## 1. 完整盘点
+
+枚举项目自有的 Markdown、MDX、reStructuredText、AsciiDoc、AGENTS/CLAUDE、项目 Skills/Command/Work 入口和其文档 references；包括 Git 跟踪文件及可确认归属的未跟踪文档。显式指定的其他文档格式也纳入。记录生成物、第三方原件、缓存、历史归档、机密或 owner 未明路径的排除/只读理由，不将它们静默遗漏或当作可写源。
+
+Git diff 用于定位变化线索，不能把全局清单缩成差量文件清单。已保存的 targets 是归属和管理记录，不限制本次发现。目录列表、manifest、入口引用和现有文档互相校对；新增的明显缺口也进入清单。全局分析不激活 workflow，不默认整读运行时知识树或归档历史。涉及 workflow 的文档/知识时才读 [workflow 范围](workflow-scope-contract.md)。
+
+<Path>{roots.state}/docs/</Path> 中存在的当前工程正文与导航纳入全局清单；按主题 owner 判断，它不属于 SpecDev 独占知识。与项目既有 docs 重复时确定唯一正文，其余导航；不把目录存在当作可写授权。缺失不创建空骨架，也不触发全面基线。
+
+## 2. 事实与处置
+
+对清单中的每份当前自有文档整份审查，局部事实修订直接使用 <Path>{roots.references}/writing-for-agents/references/current-facts-docs.md</Path>；同一源在摘要未变化时可复用。源码、配置、schema、测试、CI、发布元数据和已验证证据支撑结论，commit 标题仅作导航。为每个目标记录唯一处置：
+
+- `keep`：事实、用途与边界仍有效。
+- `update`：修正失效、不完整或相互冲突的陈述。
+- `add`：已实现事实没有合适承载位置。
+- `merge`：归并重复权威，保留独有理由、证据和来源，修复所有调用方。
+- `delete`：已失效且无保留义务的候选；整文件/目录删除须有具体授权。
+- `propose-only`：范围、语义、owner 或权限待确认，受保护知识交回原网关。
+
+处置动作与执行状态分别记录；audit 的动作均为建议。update/commit 可以修剪授权文档内的过期段落、坏链接和重复说明，不只在末尾追加新事实。合并后需删除原文件时同样核对删除授权。历史 ADR、已发布记录和原始研究不按当前实现反写。
+
+## 3. 按类型整理
+
+- README：读 [README 合同](readme-contract.md)。
+- CHANGELOG：读 [CHANGELOG 合同](changelog-contract.md)。
+- AGENTS/CLAUDE：读 [手册合同](agents-contract.md)；手册缺失、作用域变化或用户要求重建时才展开重建分支。
+- Skill、Command、Work 或其他 Agent 文档：结构、行为、迁移或所有权变化时读 `<Path>{roots.references}/writing-for-agents/writing-contract.md</Path>`，并读取目标资产自己的合同；普通事实修正核对局部源即可。
+
+语言统一：README.md 为英文，README-ZH.md 为中文镜像；其他项目文档默认简体中文，CHANGELOG 沿用既有语言。用户明确的项目语言要求优先。代码实体、URL、命令、版本和固定字段不翻译；语言镜像的事实与约束保持对等。
+
+## 4. 写入与验证
+
+先完成可审查的具体方案；已有请求覆盖的常规编辑直接执行，不额外索要逐文件确认。执行前核对目标身份、内容摘要与 owner；漂移、路径逃逸或链接归属未知只阻塞受影响写集。保护未提交用户内容；以保留链接、模式和必要元数据的方式更新真实源，原子替换普通文件并重读结果。
+
+验证随实际变化选择：
+
+- 文字/事实：格式、链接及命令/路径/版本/配置键对照；可运行的示例做相关验证，无法执行时标记未验证。
+- 指令/路由：元数据、引用、正常与近邻不触发、授权和完成边界。
+- 状态/副作用：相关隔离夹具，覆盖漂移、冲突、失败和恢复。
+- 生成依赖：由源重建并验证重复生成一致；不手改生成物。
+
+仅在变化会影响构建、测试或发布行为时运行对应 build/test/lint；项目明确要求的适用验证仍须通过。重命名/删除时搜索旧引用，其他编辑不机械全仓搜索每个旧措辞。
+
+## 5. 返回与完成
+
+按 [报告模板](../assets/report-template.md) 返回覆盖清单、事实证据、唯一处置及实际状态、授权、输入与未提交限制、命令/退出码和未完成项。audit 只返回会话报告；update 标记 not-committed；commit 再按 Git/state 合同回读提交与游标。
+
+所有纳入清单的目标均有结论且获批动作已验证，才完成相应范围。`propose-only` 候选是已完成分析，不冒充已执行；任何必需写入或验证仍 blocked 时，不推进整个同步游标。继续独立且已授权的工作，最后明确部分完成和恢复路径。

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

@@ -0,0 +1,24 @@
+# README 整理
+
+README 帮助新读者判断用途、开始使用并验证结果。结构服从项目实际规模与读者任务，不强制居中 Header、徽章数量、九段式结构、Tech Stack 表或 Footer。
+
+## 内容与事实
+
+按读者需要检查：名称与具体定位、最小 Quick Start、安装前提、常用入口/配置/限制、详细文档与贡献/许可导航。已有清晰内容保留；项目简单时合并章节，API 详表、架构解释和长教程放到独立文档。目录摘要、截图和徽章仅在帮助使用或定位时保留。
+
+| 事实变化 | 核对内容 |
+|---|---|
+| 包名、定位、公开能力 | 开头、能力说明、限制 |
+| CLI/API/配置 | Quick Start、示例、参考入口 |
+| runtime、依赖、分发 | 安装、平台/版本要求 |
+| 架构、目录、CI、发布或许可 | 相关导航、徽章、贡献与许可证 |
+
+全局整理也检查未出现在 Git diff 的陈旧说明。事实来自当前 manifest、CLI 帮助、schema、代码、测试与 CI。示例给出可复制命令和成功结果，不承诺没有证据的耗时或未来能力。
+
+## 语言镜像
+
+README.md 使用英文（EN），README-ZH.md 是中文镜像；用户明确要求其他语言时按其要求。两份在章节含义、命令、URL、表格与关键约束上对等，顶部互相链接，代码实体不翻译。已授权的同步范围内同时修正两份；缺镜像时将新建纳入目标。镜像未完成时该组不能标为已同步，不阻塞独立文档。
+
+## 验证
+
+核对版本、路径、命令与真实源，检查链接、图片和语言切换；实际运行或静态验证受影响的安装/核心示例。删除无采用或使用价值的重复说明，保留必要边界与许可。无法执行的示例明确未验证，不为文案整理默认运行全部业务测试。

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

@@ -0,0 +1,32 @@
+# Workflow 文档范围与所有权
+
+仅在全局盘点涉及 workflow 管理的项目文档、运行记录或知识时读取。发现入口为 `<Path>{roots.workflows}/{workflow}/SKILL.md</Path>` 与 manifest；需要确认写入 owner 时读取入口指向的相关运行合同，不激活整个 workflow。
+
+## 发现与边界
+
+包存在但 runtime 尚未初始化，或 state 孤立存在时，报告事实；只阻塞需要该状态的操作，继续项目文档整理。全局盘点不要求每个已安装 workflow 都有状态根或 sidecar。
+
+项目文档可归全局或一个 workflow；路径重叠、父子目录交叉或 owner 冲突只阻塞重叠目标。范围从本次请求、实际文档归属与原网关确定，不依赖假定存在的 consumers 字段。
+
+状态、changes 与 archive 保持原 workflow owner。历史归档只作证据，按主题/ID 定位相关产物；不重写归档或把当前事实反写历史。永久 RULES/policy、ADR、CONTEXT、DESIGN、research、synthesis 及其删除/冲突进入 propose-only，由原 workflow 网关取得相应批准并执行；docs-sync 不因发现路径就取得知识写权限。明确 existing-only 的 store 始终只读。
+
+OPS 资源运行记录按 OPS 文档交付合同处理；本命令不调用同名 OPS 恢复操作、不连接服务器或重跑业务，远端文档补交交给原 owning 入口。
+
+## 跨领域当前 docs
+
+<Path>{roots.state}/docs/</Path> 是面向 Agent 的当前工程事实，按实际主题归属维护，不注册为 SpecDev 永久知识 store。命令全局盘点包含其正文/导航与有独立历史价值的 archive（后者只读）；实际获批写入作为 project_targets 的项目相对精确路径管理，不为它创建虚假 workflow 或 sidecar。A/I 的局部维护与基线说明不写本命令游标。
+
+## 可纳管目标
+
+- project_targets：已确认由该 workflow 管理的项目相对文档路径。
+- state_targets：仅原 workflow 明确允许 docs-sync 维护的非知识文档，使用 workflow state 根相对路径；没有明确网关时只提建议。
+- 每项为 `{ "path": "...", "kind": "file | directory" }`。directory 递归覆盖已跟踪的 Markdown/MDX/reStructuredText/AsciiDoc；其他格式或未跟踪文件单独列 file。
+- 路径须规范化、真实包含于已解析根；拒绝绝对路径、反斜杠、`..`、无界 glob、项目根、`.git`、固定 status/changes/archive、sidecar 自身及 CLI-owned 状态。
+
+## 延迟 sidecar v1
+
+仅 commit 且确有已纳管目标时，按 [sidecar 模板](../assets/workflow-scope-template.json) 创建 `<Path>{roots.state}/{workflow}/docs-sync.json</Path>`。audit/update 不创建或更新。没有目标的 workflow 不为凑齐清单创建空文件；既有空 sidecar 原样保留，移除最后一个目标时允许将原文件清单清空，不自动删文件。
+
+全局目标保存在 `<Path>{roots.state}/commands/docs-sync/state.json</Path>`。新增、扩大或转移目标时展示实际范围变化并核对现有授权；只有未覆盖的范围或副作用补充确认，不逐次重新确认相同清单。合法变更增加 scope_revision 和 scope_confirmed_at；整个同步完成并提交后才生效。
+
+完成标准：每个目标有唯一 owner 与合法写入边界；只有实际管理的 workflow 使用 sidecar；受保护候选已交回网关；局部缺失不阻塞无关整理。

package/template/commands/engineering-standards-builder/COMMAND.md

@@ -0,0 +1,163 @@
+---
+id: engineering-standards-builder
+description: Generate or refresh project-specific engineering skills after the user explicitly invokes the builder.
+---
+
+# Engineering Standards Builder
+
+本 Command 只在用户明确调用时运行。它不会在新项目中自动启动，也不把 Builder 自带的通用建议直接复制成项目规范。
+
+目标是先理解当前项目真实的代码、目录、配置、测试、CI 与模板，再生成一组可长期复用的项目专属 Skill：一个稳定的工程规范路由入口，以及零个或多个有独立触发价值的领域 Skill。
+
+```text
+项目事实 + 用户指定的重点范围 + 已确认目标
+  -> 证据审计与冲突收敛
+  -> 最小充分 Skill Set
+  -> .agents/skills/
+```
+
+## 产物与所有权
+
+始终生成根路由：
+
+```text
+.agents/skills/
+├── engineering-standards/
+│   ├── SKILL.md
+│   ├── generated-skill-set.json
+│   └── references/project/
+│       ├── 00-project-profile.md
+│       ├── 01-module-map.md
+│       ├── 02-decisions-and-exceptions.md
+│       ├── 03-skill-map.md
+│       ├── 04-source-and-template-map.md
+│       └── review-checklist.md
+└── <optional-domain-skill>/
+    ├── SKILL.md
+    └── references/...
+```
+
+`engineering-standards` 是规范权威与路由器；领域 Skill 负责可独立触发的实现导航，不重复定义冲突规则。`generated-skill-set.json` 只登记 Builder 拥有的 `.agents/skills/*` 路径。刷新时不得改动或删除清单之外的 Skill。
+
+## 最小原则
+
+- 不按语言、目录或 Agent 数量机械拆 Skill。
+- 能由根路由和少量 references 清楚表达时，不新增领域 Skill。
+- 没有项目证据的规则不生成；Builder references 只提供审计维度与 fallback。
+- 不复制项目源码、FM 模板或脚手架正文；引用其真实路径并说明适用条件、集成步骤和验证方式。
+- 不新增配置文件、参数、时间戳、hash 或模型元数据来制造形式化负担。
+- 扫描深度、文件数和字节限制只是脚本内部资源保护，不是用户需要决策的项目规范。
+
+## 执行流程
+
+### 1. 确定项目根与学习范围
+
+从用户当前工作目录、Git/Workspace 边界和用户指定的代码或目录确定真实项目根。记录需要重点学习的模块、代码、目录、模板或脚手架；未指定时覆盖所有可编辑模块。
+
+读取现有 `AGENTS.md`、`CLAUDE.md`、贡献文档、架构文档和 `.agents/skills/`，但将它们视为待验证证据。识别 generated、vendor、build、cache、fixture 与冻结目录。发现已有 `generated-skill-set.json` 时进入 refresh；只有 legacy `engineering-standards` 时，在计划中声明接管该根 Skill，其他现有 Skill 一律视为非 Builder 所有。
+
+冲突优先级见 [治理与证据优先级](references/rules/00-governance-and-precedence.md)，路径和 scope 见 [证据、拓扑与作用域](references/rules/02-evidence-topology-and-scope.md)。本阶段只读。
+
+**完成标准**：项目根、重点范围、排除范围、现有规范和 Builder 写入边界明确。
+
+### 2. 建立确定性事实基线
+
+运行扫描器并捕获 stdout；默认不在项目中持久化 inventory：
+
+```bash
+node <skill-root>/scripts/discover-project.mjs --root <project-root> --pretty
+```
+
+扫描合同见 [项目发现合同](references/rules/01-project-discovery.md)。扫描器只提供拓扑基线，不能替代源码审计。继续读取真实 manifest/build 配置、CI 命令、公共入口、代表性实现、测试、消费者与项目模板。
+
+**完成标准**：每个可编辑模块有路径、技术栈、入口、质量门禁和证据；扫描限制、冲突与未知项已记录。
+
+存在可机械验证的边界/约束缺口时，读取 [工程约束](references/rules/09-mechanical-guardrails.md)，决定是否提出接入与验证方案。
+
+### 3. 用 Agent Team 分域取证
+
+当运行环境支持 Agent Team 且存在两个以上可独立审计的证据域时，默认由 leader 并行派发只读 scout。证据域按项目真实边界划分，例如架构与公共 API、后端、前端、公共复用、测试与 CI、FM/脚手架；不得套用固定角色表。
+
+leader 是唯一写入者。每个 scout 必须返回同一份精简证据合同：
+
+```text
+Scope
+Observed capability
+Canonical source paths
+Mature implementations
+Template paths
+Consumers and tests
+Applicable conditions
+Legacy/counterexamples
+Conflicts/unknowns
+Recommended skill boundary
+```
+
+leader 必须复读高影响路径，检查跨域冲突，并把同一事实的重复报告合并。Agent Team 不可用或任务不可合理拆分时，leader 按相同合同顺序审计；结果标准不变。
+
+**完成标准**：重要规范均有真实路径、消费者或测试支撑；反例、旧实现和未知项没有被“多数模式”掩盖。
+
+### 4. 收敛规范与 Skill 边界
+
+先识别项目已经声明的 canonical 模板或代码样板，例如 `docs/fm/**`、scaffold、generator assets。模板与成熟代码冲突时，判断它是目标模板、过期模板还是仅负责骨架，并记录 current、target 与 migration；不得静默任选一方。
+
+只有同时满足以下条件才创建领域 Skill：
+
+1. 有可独立描述的触发场景；
+2. 会在多次开发中复用；
+3. 有充分的项目源码、模板、测试或配置证据；
+4. 与根路由或其他领域 Skill 边界清晰；
+5. 独立后能明显减少无关上下文。
+
+否则内容留在 `engineering-standards`。领域 Skill 名称来自项目语义，不使用固定列表或固定数量。高影响未知项按 [决策收敛合同](references/rules/03-interview-and-decisions.md) 询问；用户已授权直接生成时，将无法安全推断的事项记为 `pending-decision`。
+
+只读取与项目事实匹配的 [通用规则索引](references/rules/README.md)、[TypeScript/JavaScript](references/typescript/README.md)、[Java](references/java/README.md)、[Go](references/go/README.md) 或 [Rust](references/rust/README.md) references。内置语言包和 [未内置语言 fallback](references/rules/16-language-adapter-contract.md) 是检查清单，不是高于项目代码的规范来源。
+
+**完成标准**：每个生成 Skill 都有独立价值和证据边界；没有为了覆盖目录或技术栈而过度拆分。
+
+### 5. 计划、生成与刷新
+
+先展示精简计划：模块与证据摘要、Skill Map、每个 Skill 的来源路径、保留/更新/新增/删除项、冲突决策和验证命令。用户已在当前请求中授权实施时，展示后直接执行。
+
+按 [Skill Set 生成合同](references/rules/14-generation-contract.md) 和 [模板索引](templates/README.md) 生成。所有项目引用使用项目根相对路径，并说明：何时读取、它负责什么、输出位置、需要哪些手工集成、运行什么验证。
+
+先准备完整候选内容并校验，再替换 Builder 拥有的文件。刷新规则：
+
+- 只更新或删除旧 `generated-skill-set.json` 登记的路径；
+- 名称与未登记 Skill 冲突时停止覆盖并重新命名或询问；
+- 保留仍有效的用户决策、例外和项目特有知识；
+- 删除或重命名必须在计划中显式列出；
+- 候选验证失败时保留旧 Skill Set；发布后验证失败时恢复旧内容；
+- 相同项目事实与决策重复运行应无无意义 diff。
+
+**完成标准**：根路由、领域 Skill、项目引用与所有权清单一致，清单外 Skill 未发生变化。
+
+### 6. 验证与报告
+
+运行：
+
+```bash
+node <skill-root>/scripts/validate-generated-skill.mjs --root <project-root> --strict
+```
+
+再按 [验证合同](references/rules/15-validation-contract.md) 执行项目已存在且本次允许的质量门禁。不得通过删除测试、放宽编译配置或扩大例外获取通过。
+
+最终报告生成/更新/保留/删除的 Skill，关键证据与模板路径，运行命令及退出码，未验证项、待确认决策和临时例外。
+
+**完成标准**：所有权、frontmatter、Skill 路由、项目内引用、选择性适配和规则字段通过；项目门禁通过或留下可复现阻塞证据。
+
+## Builder 自校验
+
+维护本 Skill 时读取 [fixture 合同](examples/README.md)，并运行：
+
+```bash
+node scripts/sync-manifest.mjs --root . --check
+node scripts/validate-builder.mjs --root .
+node scripts/self-test.mjs --root .
+```
+
+这些脚本无第三方依赖、接受显式根目录、拒绝路径越界，并提供 `--help`。
+
+## 调用报告
+
+需要持久化本次报告时使用 <Path>{roots.state}/commands/engineering-standards-builder/{date}-{scope}-{topic}[-NN].md</Path>。复用当前授权和产物合同，不为只读调用自动创建状态；不覆盖历史报告。