@namewta/speculo 0.1.21 → 0.2.0

package/template/workflows/dev/D-docs-sync/agents-contract.md

@@ -1,95 +0,0 @@
-# AI 代理手册类文档同步契约（通用）
-
-AI 代理手册类文档（`AGENTS.md`、`CLAUDE.md`、`.cursorrules`、`.github/copilot-instructions.md` 等）是**给 AI 代理看的工作手册**，不是给用户看的营销页。它的受众是其他 AI 代理（Claude / Cursor / Kiro / Codex / GPT / Gemini 等），内容应是高信息密度的结构化陈述。
-
-本契约给出通用写作与同步规则；具体章节结构由项目自身现有文档决定，同步时保留既有结构做差量更新。
-
-## 文档定位
-
-- 不是用户文档，不需要 Quick Start 式教程
-- 不是营销文，不需要"它多强大"
-- 是**事实手册**：项目身份、目录布局、关键命令、扩展机制、禁止与必须
-- 是**惯例沉淀**：代码风格、测试要求、发布约定、常见陷阱
-
-## 典型章节
-
-以下是 AI 代理手册中**常见**的章节；实际是否存在、顺序如何，由项目决定：
-
-| 常见章节 | 通用同步触发条件 |
-|---------|-----------------|
-| 项目身份 | `package.json` / `pyproject.toml` / `Cargo.toml` 等元信息变化（name / version / runtime 约束 / license） |
-| 核心架构 | 顶层领域模型、核心抽象、关键常量集变化 |
-| 仓库布局 | 顶层目录树变化（新增/删除/重命名） |
-| 开发命令 | 项目任务运行器入口变化（scripts / Makefile / justfile） |
-| CLI / API 速查 | CLI 入口或公共 API 变化 |
-| 扩展机制 | 钩子、插件、生命周期钩子的 public API 变化 |
-| 代理行为规约 | 代码风格、测试要求、发布约定的策略性调整（变化频率低） |
-| 常见陷阱 | CI 失败复盘、重构遗留约定、新成员反复犯错 |
-| 相关文档 | 新增/删除对外文档时 |
-
-## 仓库布局小节的同步规则
-
-如存在"仓库布局 / Repository Layout / 目录结构"章节，它是代码树的 ASCII 快照。**每次同步**都要对照实际顶层目录：
-
-- 列顶层目录 + 关键子目录（建议最多两层）
-- 用 `├──` `└──` `│` 表示树形
-- 右侧注释简短，说明"这个目录是做什么的"
-- 新增 / 删除 / 重命名顶层目录时必须跟进
-
-## 开发命令与 CLI 速查
-
-- 表格形式（两列："场景 / 命令"，或三列："命令 / 作用 / 常用标志"）
-- 命令来自项目任务运行器（`package.json#scripts` / `Makefile` / etc.）或 CLI 入口源码
-- 新增命令 → 加一行；改名 → 改行；删除 → 删行
-- 与 README 的 CLI Reference **同源但更简略**：README 提供完整说明，代理手册只给速查
-
-## 扩展机制
-
-如项目提供钩子、插件、生命周期回调等二次开发入口，对应源文件的 public API 变化时必须同步此章节。代码示例应使用**实际存在的入口**，不要虚构。
-
-## 代理行为规约
-
-这是最稳定的章节。调整的触发条件有限：
-
-- 工具链升级（例如 ESLint flat config / legacy 切换、测试框架替换）
-- 构建 / 发布流水线改造
-- 代码风格或命名约定的全仓级调整
-
-## 常见陷阱
-
-每一条是一个真实踩过的坑或设计隐患。
-
-**添加条目的时机**：
-
-- CI 失败排查后发现某类错误反复出现
-- 重大重构后遗留的临时约定
-- 新团队成员或 AI 代理反复犯的同一错
-
-**删除条目的时机**：工具链或代码结构升级消除了该陷阱。
-
-## 相关文档
-
-指向项目的其他对外文档（README / CHANGELOG / CONTRIBUTING / spec 目录等）。新增顶层文档（如增加 `CONTRIBUTING.md`）时同步本小节。
-
-## 语言与风格
-
-- 全文使用**项目主要贡献者的工作语言**（中文项目用中文，英文项目用英文）
-- 代码实体（命令、路径、字段名、配置键、类名）保持**原文**，不翻译
-- 列表式陈述优先于长段落
-- 表格优先于散文
-- 代码块优先于描述
-- 使用硬约束语言：**禁止 / 必须 / 不得 / 强制**
-- 避免营销语、惊叹号、表情符号
-- 避免模糊词："通常 / 大概 / 可能"改为具体条件
-
-## 长度预算
-
-建议全文控制在 500 行以内（与渐进披露 L2 阈值一致）。超过时把具体细节下沉到 `references/` 子文档并在主文档中引用。
-
-## 不做的事
-
-- 不复述 README 里已讲过的"它解决什么问题"
-- 不写命令的详细 usage（`--help` 已经提供，速查表已经够）
-- 不加 Quick Start 类步骤教程（那是 README 的工作）
-- 不罗列借鉴项目清单（README 的致谢小节已经有了）
-- 不做版本变更历史（那是 CHANGELOG 的工作）

package/template/workflows/dev/D-docs-sync/changelog-contract.md

@@ -1,155 +0,0 @@
-# CHANGELOG 类文档同步契约（通用）
-
-CHANGELOG 类文档（`CHANGELOG.md`、`CHANGELOGS.md`、`HISTORY.md`、`RELEASES.md`）遵循 [Keep a Changelog 1.1.0](https://keepachangelog.com/1.1.0/) 格式与 [SemVer 2.0.0](https://semver.org/)。语言由项目决定（中/英/其他），日期建议采用 ISO 8601（UTC 或带时区偏移）。
-
-## 文档骨架（Keep a Changelog 约定）
-
-```
-# Changelog
-
-<简短介绍段：声明遵循 KaC + SemVer 等约定>
-
----
-
-## [Unreleased]
-
-### Added / 新增
-### Changed / 变更
-### Deprecated / 弃用
-### Removed / 移除
-### Fixed / 修复
-### Security / 安全
-
----
-
-## [x.y.z] — YYYY-MM-DD
-
-<同样的分节>
-
----
-
-## 版本链接 / Links
-
-- [Unreleased](<compare-url>/vLATEST...HEAD)
-- [x.y.z](<releases-url>/tag/vx.y.z)
-- ...
-```
-
-`[Unreleased]` 顶部段落**永远存在**，即使内容为空。
-
-## 标准分节与可选扩展
-
-**Keep a Changelog 标准 6 节**（必须用标准名，语言本地化即可）：
-
-| 标准节 | 语义 |
-|------|------|
-| Added / 新增 | 新功能、新命令、新模板、新技能 |
-| Changed / 变更 | 既有能力的行为/默认值调整 |
-| Deprecated / 弃用 | 将来会移除但本版本仍能用 |
-| Removed / 移除 | 已从代码中删除的能力 |
-| Fixed / 修复 | bug 修复 |
-| Security / 安全 | 安全修复、CVE 响应、鉴权相关调整 |
-
-**常见非标准扩展**（项目可选）：
-
-| 扩展节 | 语义 |
-|-------|------|
-| Planned / 计划中 | 明确声明"即将做但未动工"的事项，用于路线图沟通 |
-| Docs / 文档 | 对外文档的更新（README / AGENTS / references 等） |
-| Performance / 性能 | 性能优化但行为未变 |
-| Dependencies / 依赖 | 依赖升级聚合（非 Security） |
-
-项目一旦采用某扩展节就在整个 CHANGELOG 内一致使用，不要忽隐忽现。**没有内容的分节不要列出空标题**；保留有内容的即可。
-
-## 把 git 变更写成 Changelog 条目
-
-[Conventional Commits](https://www.conventionalcommits.org/) 前缀对应分节（按项目采用的 commit 约定调整）：
-
-| 前缀 | 分节 |
-|------|------|
-| `feat:` / `feat(...):` | Added / 新增 |
-| `fix:` / `fix(...):` | Fixed / 修复 |
-| `refactor:` / `perf:` | Changed / 变更（若有行为影响）或 Performance |
-| `docs:` | Docs / 文档（如项目采用该扩展节）；否则不写 |
-| `chore:` / `ci:` / `build:` / `style:` / `test:` | 默认不写；仅在用户能感知时写入相应分节 |
-| `revert:` | 视被 revert 的内容归类 |
-| 依赖升级（Dependabot 等） | Security（有 CVE） / Dependencies 或 Changed（常规） |
-
-**不要把每一个 commit 都写成一行**。聚合为"主题条目"：
-
-- 同一主题下的多个 commit → 一条 bullet，列出关键细节
-- `chore:` 类型整批的 Dependabot 升级 → 一条"依赖周更"条目
-- 只影响开发体验（测试配置调整、lint 规则微调）通常不进 CHANGELOG
-
-示例（原始 commits → Changelog 条目）：
-
-```
-git log
-  feat(cli): add --json flag to status command
-  fix(status): handle missing config gracefully
-  test(status): cover --json output
-
-→ CHANGELOG 的 [Unreleased] 下：
-### Added
-- **CLI**：`status --json` 支持机器可读输出，缺失配置时给出空结构而非报错
-```
-
-## Tag 发版时的迁移
-
-当检测到区间内发生了版本 tag（即项目元信息中的 version 变化 + 新 `v*` tag）：
-
-1. 确定 tag 创建日期：`git log -1 --format=%aI vX.Y.Z`
-2. 把 `[Unreleased]` 下除"Planned / 计划中"外的所有条目整体移动到新版本段落 `## [X.Y.Z] — YYYY-MM-DD`
-3. 清空 `[Unreleased]`（保留空的"Planned / 计划中"区块，如项目使用该扩展节）
-4. 更新底部版本链接：
-   - 新增 `[X.Y.Z]` 链接行
-   - 把 `[Unreleased]` 的 compare 基线改为 `vX.Y.Z...HEAD`
-5. 如果 tag 之后还有新 commit，按正常流程把这些 commit 写入新的 `[Unreleased]`
-
-## 版本链接契约
-
-底部链接段落固定结构：
-
-```
-- [Unreleased](<repo>/compare/vLATEST...HEAD)
-- [X.Y.Z](<repo>/releases/tag/vX.Y.Z)
-- [X.Y.Z-1](...)
-- ...
-```
-
-每发一个新版本 → 加一行；`[Unreleased]` compare 基线始终指向最新 tag。仓库 URL 由项目决定（GitHub / GitLab / Gitea / Bitbucket）。
-
-## 条目写作规范
-
-- 每个 bullet 以**能力名或模块名**加粗开头，如 `**CLI**：...`、`**API**：...`、`**templates**：...`、`**build**：...`、`**CI**：...`
-- 用户视角描述"发生了什么"，不描述"怎么改的"
-- 路径、命令、标志、版本号保留代码格式（反引号）
-- 不使用表情符号
-- 一条 bullet 不超过两行；更长拆成子列表
-
-## 不做的事
-
-- **不要**重写已发布版本段落的条目措辞 —— 这些是历史档案
-- **不要**在 `[Unreleased]` 里保留已被移入正式版本的条目
-- **不要**反向覆盖：用 GitHub / GitLab 自动生成的 release notes 盖掉人工整理的 CHANGELOG
-- **不要**把文档自身同步写成 `Added / Changed` —— 如项目采用"Docs / 文档"扩展节归入该节；否则不写
-- **不要**把内部重构写成新功能
-
-## 示例：典型同步产物
-
-```markdown
-## [Unreleased]
-
-### Added
-
-- **CLI**：`status --json` 输出机器可读状态
-- **templates**：新增 authentication 模板，覆盖常见登录模式
-
-### Changed
-
-- **doctor**：`--check-deps` 在检测到未知依赖时改为 warn（原 error）
-
-### Docs
-
-- 新增 `.agents/skills/docs-sync/`，用于基于 git diff 同步对外文档
-```

package/template/workflows/dev/D-docs-sync/config-contract.md

@@ -1,75 +0,0 @@
-# .config 知识资产同步契约
-
-本契约用于 `dev/D-docs-sync` 审计和更新 `speculo/.speculo/.config/`。它只规定 docs-sync 的同步边界；术语和 ADR 的格式单一事实源仍是 `../M-domain-modeling/CONTEXT-FORMAT.md` 与 `../M-domain-modeling/ADR-FORMAT.md`。
-
-## 覆盖范围
-
-- `speculo/.speculo/.config/RULES.md`
-- `speculo/.speculo/.config/LESSONS.md`
-- `speculo/.speculo/.config/context/**/*.md`
-- `speculo/.speculo/.config/adr/**/*.md`
-
-## 通用生命周期动作
-
-每次审计都把候选项标记为以下之一：
-
-| 动作 | 含义 |
-|------|------|
-| `add` | 当前代码、文档或归档产物出现了新的稳定知识，应新增 |
-| `update` | 旧内容仍有价值但与当前事实不一致，应改写 |
-| `delete` | 内容已过期、重复、空置或被取代，应删除或转交 prune |
-| `keep` | 内容仍准确且有当前证据支撑 |
-| `propose-only` | 需要用户确认或领域建模确认，暂不写文件 |
-
-禁止只追加内容。旧事实、旧引用、重复条目和空模板必须被审计。
-
-## RULES.md
-
-`RULES.md` 是用户维护的硬约束库。
-
-- docs-sync 必须读取并遵守。
-- docs-sync 可以在 report 中提出增删改建议。
-- 只有用户明确确认具体规则改动时，才可写入 `RULES.md`。
-- 不能把一次性任务偏好、临时 workaround 或尚未验证的经验写成规则。
-
-## LESSONS.md
-
-`LESSONS.md` 记录跨任务可复用经验。
-
-- 可追加来自归档复盘、诊断、发布失败、重复踩坑的高信号经验。
-- 可删除或合并重复、过时、单次任务专属、已被规则/ADR 吸收的条目。
-- 每条经验应能说明“以后遇到什么条件时如何行动”，不要记录流水账。
-- 如果只影响当前 change，把内容留在 change 产物中，不写入 LESSONS。
-
-## CONTEXT
-
-CONTEXT 是项目通用语言，不是实现说明、PRD 或决策日志。
-
-- 只沉淀项目领域特有术语，不写通用编程词。
-- 术语定义最多一到两句话。
-- 同一概念多名、用户用词冲突、上下文边界不清时，必须调用 `../M-domain-modeling/M-domain-modeling.md` 确认。
-- 当前代码或 ADR 反转术语含义时，更新或删除旧定义；不要保留双重定义。
-
-## ADR
-
-ADR 记录难以逆转、缺上下文会令人意外、存在真实权衡的决策。
-
-- ADR 引用必须指向真实存在的 ADR 文件。
-- ADR 被取代时，旧 ADR 顶部必须有 superseded 标注，并指向新 ADR。
-- ADR 索引或 README（若项目存在）必须与实际文件、状态、取代链一致。
-- 已被物理删除的 ADR 引用必须删除、改为新 ADR，或在 report 中标记为阻塞。
-- 新 ADR 或取代链写入前，按 `../M-domain-modeling/ADR-FORMAT.md` 判断是否值得记录。
-
-## 删除与 Prune
-
-docs-sync 可以直接删除 tracked 文档中的过期段落；对 `.config` 文件级删除默认进入 `../../../skills/config-prune/SKILL.md` 审计候选。
-
-可进入 prune 候选的典型情况：
-
-- 被取代超过 30 天且无活跃引用的 ADR。
-- 指向不存在 ADR 的索引行或正文引用。
-- 空置占位文件或只含 TODO 的长期资产。
-- CONTEXT 中已无代码、文档或归档证据支撑的术语。
-- LESSONS 中重复或被 RULES/ADR 吸收的经验。
-
-删除 `.config` 文件或 RULES 条目前必须有用户明确确认。

package/template/workflows/dev/D-docs-sync/docs-sync-diff.md

@@ -1,86 +0,0 @@
-# Diff Collect Phase
-
-## 输入
-
-- `speculo/.speculo/dev/docs-sync-state.json`
-- `LAST_SYNC_SHA`
-- 当前 `HEAD`
-- state 中的 `tracked_assets`
-
-## 产物
-
-- `speculo/.speculo/dev/<change>/docs-sync-report.md`，由 `../_templates/docs-sync-report-template.md` 填写或追加
-
-## 填写引导
-
-### Bootstrap Collect
-
-若 State Read 设置了 `BOOTSTRAP_DOCS_INIT=true`：
-
-1. 把同步范围记为 `<bootstrap>..HEAD`；不要对 `null` 运行 `git diff "$RANGE"`。
-2. 盘点当前项目事实，至少收集：
-
-```bash
-git rev-parse HEAD
-git log --oneline --no-merges --max-count=50
-git ls-files
-git ls-files -- 'README*' 'CHANGELOG*' AGENTS.md CLAUDE.md docs speculo/.speculo/.config .github package.json pnpm-lock.yaml package-lock.json yarn.lock pyproject.toml Cargo.toml go.mod Makefile justfile
-```
-
-3. 按项目实际技术栈读取元数据和入口文件，例如 `package.json` scripts/bin/files、CLI/API 入口、测试目录、CI workflow、release 配置、LICENSE。
-4. 对比现有文档，列出初始化动作：
-   - `add`：缺失但项目应具备的基础文档或章节。
-   - `update`：已有文档与当前项目事实不一致。
-   - `delete`：初始化时发现的空模板、旧事实或重复说明。
-   - `keep`：已有且准确的文档资产。
-   - `propose-only`：`RULES.md` 写入、`.config` 文件删除、不稳定术语或 ADR 候选。
-5. `bootstrap` 不以 git diff 驱动，而以当前项目事实驱动；所有新增内容仍必须有真实文件、配置、命令或代码入口支撑。
-
-### Regular Diff Collect
-
-固定收集以下信息：
-
-```bash
-RANGE="$LAST_SYNC_SHA..HEAD"
-git log --oneline --no-merges "$RANGE"
-git diff --name-status "$RANGE"
-git diff --shortstat "$RANGE"
-git diff --name-only "$RANGE" | awk -F/ '{print $1"/"$2}' | sort | uniq -c | sort -rn
-git diff --name-status "$RANGE" -- speculo/.speculo/archive speculo/.speculo/.config
-```
-
-有疑问的具体改动再读取：
-
-```bash
-git log -p "$RANGE" -- <specific-path>
-git show <sha> -- <specific-file>
-```
-
-把变更按资产类型映射到 `tracked_assets`：
-
-- 对外能力变化：README 类 + CHANGELOG
-- 内部重构但行为未变：视情况写 CHANGELOG 或 AGENTS 类约定
-- 依赖升级：CHANGELOG 聚合；安全 CVE 进 Security
-- CI/CD 变化：CHANGELOG + AGENTS / CONTRIBUTING 的发布约定
-- 文档自身：仅在对外可见时写 CHANGELOG 的文档类条目
-- 测试 / 开发工具链：通常不进 CHANGELOG；AGENTS 的测试要求酌情更新
-- 新增顶层目录 / 顶级文件：如 AGENTS 类存在仓库布局章节则必须同步
-- `template/` 下 framework 资产变化：README 内置入口、quick reference、architecture、AGENTS 资产编辑规则、CHANGELOG
-- `speculo/.speculo/.config/adr/` 变化：ADR README/索引、CONTEXT 相关术语、AGENTS/architecture 中的决策约束
-- `speculo/.speculo/.config/context/` 变化：README/AGENTS 术语、PRD/architecture 中的通用语言
-- `speculo/.speculo/.config/LESSONS.md` 变化：AGENTS 常见陷阱、workflow 规则、retro/diagnose 经验；低信号或重复项应建议删除
-- `speculo/.speculo/.config/RULES.md` 变化：只审计和提出建议；写入必须等用户确认
-- `speculo/.speculo/archive/` 变化：进入 `knowledge-extract.md`，从归档产物提取决策、经验、规则和文档漂移信号
-
-## 边界
-
-- 不把每个 commit 都写成文档条目。
-- 常规同步不修改未列入 `tracked_assets` 的资产，除非先获得用户确认并更新 state；`bootstrap` 模式可把基础文档创建候选先纳入初始化 `tracked_assets`，再修改。
-- 不因为某路径出现在 diff 中就自动扩写文档；必须判断旧内容是否仍然成立，是否应该删除或压缩。
-- `bootstrap` 模式不虚构路线图、未实现能力或不存在的命令；无法从项目事实确认的内容进入 `propose-only` 或询问用户。
-
-## 完成准则
-
-- git 差异素材或 `bootstrap` 项目盘点已记录到 report
-- 已列出要新增、删除、修改、保留的资产和理由，或判定空同步
-- archive 与 `.config` 相关 diff 已移交后续阶段

package/template/workflows/dev/D-docs-sync/docs-sync-finish.md

@@ -1,37 +0,0 @@
-# State Write Phase
-
-## 输入
-
-- 更新后的 tracked assets
-- `speculo/.speculo/dev/docs-sync-state.json`
-- `speculo/.speculo/dev/<change>/docs-sync-report.md`
-- 当前 `HEAD`
-
-## 产物
-
-- 更新后的 `speculo/.speculo/dev/docs-sync-state.json`
-- 完整的 `speculo/.speculo/dev/<change>/docs-sync-report.md`
-
-## 填写引导
-
-1. 运行项目级校验；命令根据项目工具链决定。
-2. 如果当前为 `bootstrap` 模式，验证通过后把推导出的 `tracked_assets`、本次创建/更新的 `synced_assets` 和当前 `HEAD` 一起写入 state，建立首次同步基线。
-3. 如果所有差异都无需资产修改，仍把 `last_sync_sha` 推进到当前 `HEAD`，并把 `synced_assets` 置为 `[]`。
-4. 如果修改了资产，验证通过后再推进 state。
-5. 写回 state 时按 `state-json-schema.md` 字段顺序，2 空格缩进，尾部换行。
-6. 原子化写入：先写 `speculo/.speculo/dev/docs-sync-state.json.tmp`，再 rename。
-7. 按 report 模板向用户报告范围、归档来源、改动资产、新基线和验证命令。
-8. 如果存在 `propose-only` 或 prune 候选，不因候选未执行阻塞基线推进；但必须在 report 中列出后续确认项。
-
-## 边界
-
-- 验证失败时不推进 `last_sync_sha`。
-- `bootstrap` 模式没有成功创建或确认首批 `tracked_assets` 时不推进 `last_sync_sha`。
-- 不把敏感信息、绝对路径或完整 diff 写入 state。
-- 不把 archive 提取详情、用户确认原文或 prune 候选全文写入 state；这些只写 report。
-
-## 完成准则
-
-- state 已原子写入或明确记录阻塞原因
-- report 已包含同步范围、读取归档、改动资产、`.config` 审计、验证结果
-- `.status.json` 的 `docs_sync_status` 已更新

package/template/workflows/dev/D-docs-sync/docs-sync-state.md

@@ -1,47 +0,0 @@
-# State Read Phase
-
-## 输入
-
-- `speculo/.speculo/dev/docs-sync-state.json`
-- `git rev-parse HEAD`
-- `../_templates/docs-sync-state-template.json`
-- `state-json-schema.md`
-
-## 产物
-
-- `speculo/.speculo/dev/docs-sync-state.json`
-- `speculo/.speculo/dev/<change>/docs-sync-report.md`
-
-## 填写引导
-
-1. 设置 `STATE_FILE="speculo/.speculo/dev/docs-sync-state.json"`。
-2. 读取 `state-json-schema.md`，按 schema 校验 state；若文件不存在，复制 `../_templates/docs-sync-state-template.json` 为骨架，把 `state_path` 设为 `speculo/.speculo/dev/docs-sync-state.json`。
-3. 若存在 v1 state（`schema_version: 1` 或含 `tracked_docs` / `synced_docs`），迁移为 v2：
-   - `tracked_assets = tracked_docs`
-   - `synced_assets = synced_docs`
-   - 保留所有 baseline 字段
-   - `schema_version = 2`
-   - 在 report 中记录迁移摘要
-4. 读取 `last_sync_sha` 和当前 `HEAD`。
-5. 若 `tracked_assets` 为空、`last_sync_sha` 为 `null` 或 state 文件刚由模板创建，设置 `BOOTSTRAP_DOCS_INIT=true`，把 `.status.json` 的 `docs_sync_status` 置为 `bootstrap`，本次默认执行从 0 到 1 的完整文档初始化。
-6. `bootstrap` 模式下自动推导首批 `tracked_assets`，不因缺少用户确认而停止；候选至少包括：
-   - 基础文档：`README.md`、`CHANGELOG.md`、`AGENTS.md`，以及项目已存在或明显需要的 `CLAUDE.md` / `.github/copilot-instructions.md`。
-   - 文档目录：已存在的 `docs/**/*.md`；若项目有复杂架构、CLI/API、发布流程或接入说明但缺少承载文档，可把待创建的 `docs/*.md` 纳入初始化候选。
-   - Speculo 知识资产：实际存在的 `speculo/.speculo/.config/RULES.md`、`speculo/.speculo/.config/LESSONS.md`、`speculo/.speculo/.config/context/**/*.md`、`speculo/.speculo/.config/adr/**/*.md`。
-7. `bootstrap` 模式的初始化目标是：基于当前项目真实文件、元数据、命令、入口、测试、CI 和发布配置，创建或补齐首批可维护文档，并把本次创建/更新的路径写入 report 与最终 state。
-8. `RULES.md` 只审计和提出建议，写入需用户明确确认；`.config/context` 和 `.config/adr` 中不稳定、多语义或需要取舍的内容，先交由 `../M-domain-modeling/M-domain-modeling.md` 确认。
-9. 若已存在有效 `tracked_assets` 且 `last_sync_sha == HEAD`，仍执行 archive 和 `.config` 审计；只有审计也无变化时才报告无需操作。
-
-## 边界
-
-- 不把 state 写到仓库根目录。
-- 首次空 state 不等待用户确认 `tracked_assets`；必须自动进入 `bootstrap` 初始化，并在 report 中说明推导依据。
-- 不因 v1 迁移自动扩大已有同步范围；只有迁移后 `tracked_assets` 为空或 `last_sync_sha` 为 `null` 时才进入 `bootstrap`。
-- 不在 State Read 阶段直接推进 `last_sync_sha`；基线只在 Finish 阶段验证通过后写回。
-- 不在未确认时写入 `RULES.md`、删除 `.config` 文件或固化存在语义争议的 CONTEXT / ADR。
-
-## 完成准则
-
-- 已确定是否进入 `bootstrap`、无需同步或继续进入 diff collect
-- v1 state 已迁移为 v2，或已明确阻塞原因
-- `.status.json` 的 `docs_sync_status` 已更新

package/template/workflows/dev/D-docs-sync/docs-sync-update.md

@@ -1,44 +0,0 @@
-# Asset Audit & Update Phase
-
-## 输入
-
-- `speculo/.speculo/dev/<change>/docs-sync-report.md`
-- state 中的 `tracked_assets`
-- git 差异素材
-- archive 知识提取结果
-- 按需读取的 contract 文件
-
-## 产物
-
-- 更新后的 tracked assets
-- `speculo/.speculo/dev/<change>/docs-sync-report.md`
-
-## 填写引导
-
-1. 若当前为 `bootstrap` 模式，先把初始化候选写入 report 的 Mapping，再按候选更新最终 `tracked_assets`；缺失的基础文档可作为 `add` 创建。
-2. 更新 README 类文档前读取 `readme-contract.md`。
-3. 更新 AGENTS / AI 代理手册类文档前读取 `agents-contract.md`。
-4. 更新 CHANGELOG 类文档前读取 `changelog-contract.md`。
-5. 更新 `.config` 前读取 `config-contract.md`；涉及术语或 ADR 语义时读取 `../M-domain-modeling/M-domain-modeling.md`，按需读取其 `CONTEXT-FORMAT.md` / `ADR-FORMAT.md`。
-6. 常规同步只做差量修改，保留既有结构、语气和字段；`bootstrap` 模式创建缺失文档时，可按 contract 生成完整初始骨架。
-7. 每个候选改动都按 `add | update | delete | keep | propose-only` 标记，并写入 report；不允许只追加不审计。
-8. 多语言镜像文档必须结构对等；代码实体不翻译。
-9. CHANGELOG 顶部必须保留 `[Unreleased]`；首次创建 CHANGELOG 时使用 Keep a Changelog 骨架，并只记录当前已存在事实。
-10. AGENTS 类的仓库布局小节必须反映实际顶层目录变化；首次创建 AGENTS 类文档时面向 AI 代理写工作手册，不写用户 Quick Start。
-11. `RULES.md` 只写 report 建议；用户明确确认后才可修改文件。
-12. `LESSONS.md` 只保留可复用、已验证、非重复的经验；空占位、重复项和只适用于单次任务的内容应删除或不写入。
-13. ADR / CONTEXT 更新前先判断是否是领域语义变化；不稳定、多语义或存在冲突时，必须交由 `../M-domain-modeling/M-domain-modeling.md` 询问确认。
-
-## 边界
-
-- 常规同步不整页重写 README 或代理手册；`bootstrap` 模式只在文件缺失时创建完整初始文件，已有文件仍以审计和差量修订为主。
-- 不添加没有对应代码来源的计划中能力。
-- 不把 docs-sync state 放回 skill 或 workflow 目录。
-- 不自动删除 `.config` 文件；删除候选进入 report 或交由 `../../../skills/config-prune/SKILL.md` 审计，执行删除需要用户确认。
-- 不把归档产物正文大段复制到长期文档；只沉淀可复用结论，并保留路径引用。
-
-## 完成准则
-
-- 需要同步的 tracked assets 已完成差量修改、`bootstrap` 初始化创建或明确列为 propose-only
-- `docs-sync-report.md` 记录每个资产的修改理由、生命周期动作和摘要
-- `docs-sync-report.md` 无残留 `[TODO:]`

package/template/workflows/dev/D-docs-sync/knowledge-extract.md

@@ -1,66 +0,0 @@
-# Knowledge Extract Phase
-
-本阶段把 `speculo/.speculo/archive/` 中已完成 change 的高信号产物提取为长期知识候选。归档是证据来源，不是要复制进长期文档的正文仓库。
-
-## 输入
-
-- `LAST_SYNC_SHA..HEAD`
-- `speculo/.speculo/archive/`
-- `speculo/.speculo/dev/<change>/docs-sync-report.md`
-- git diff 中与代码、文档、`.config` 或 archive 相关的路径
-
-## 产物
-
-- `docs-sync-report.md` 的 `Archive Sources` 与 `Knowledge Suggestions` 小节
-
-## 归档扫描
-
-固定先收集：
-
-```bash
-RANGE="$LAST_SYNC_SHA..HEAD"
-git diff --name-status "$RANGE" -- speculo/.speculo/archive
-git diff --name-only "$RANGE" -- speculo/.speculo/archive
-find speculo/.speculo/archive -maxdepth 4 -type f | sort
-```
-
-若项目没有 `speculo/.speculo/archive/`，记录缺失，不阻塞 docs-sync。
-
-## 读取优先级
-
-只深读相关归档，不批量复制全部历史。优先读取：
-
-- 本次 range 中新增或变更的 archive 文件。
-- 文件名为 `decision-log.md`、`domain-model-log.md`、`prd*.md`、`issues-slices.md`、`review-report.md`、`completion-summary.md`、`retro*.md`、`report.md` 的高信号产物。
-- 与本次 diff 触及路径、术语、模块或 ADR 编号同名/同义的归档 change。
-
-低信号产物（日志、快照、纯执行记录）只记录路径，不提取长期知识。
-
-## 提取映射
-
-| 归档信号 | 映射目标 |
-|----------|----------|
-| 已确认、难以逆转、有权衡的 `D-*` 决策 | ADR 候选或现有 ADR 更新 |
-| 新术语、术语冲突、上下文边界变化 | CONTEXT 候选；不稳定时转 `../M-domain-modeling/M-domain-modeling.md` |
-| 反复出现的约束、禁止项 | RULES 建议（propose-only） |
-| 可复用踩坑、验证经验、工作流反模式 | LESSONS 新增/合并/删除候选 |
-| 与当前实现不一致的旧说明 | tracked assets 或 `.config` 更新/删除候选 |
-| 被取代、合并、放弃的方案 | ADR supersession 或 prune 候选 |
-
-## 不确定性处理
-
-以下情况不得直接写入 `.config`：
-
-- 同一术语存在多种含义。
-- 决策是否仍有效无法从代码或归档判断。
-- 归档记录与当前代码相互矛盾。
-- 候选规则会改变用户维护的 `RULES.md`。
-
-处理方式：在 report 中列为 `propose-only`，并调用 `../M-domain-modeling/M-domain-modeling.md` 或等待用户确认。
-
-## 完成准则
-
-- 已列出读取过的 archive 路径。
-- 每个知识候选都有来源路径和生命周期动作。
-- 无证据或低信号内容未写入长期资产。
-- 不确定项已标记为待确认或移交领域建模。