@namewta/speculo 0.1.20 → 0.2.0

package/template/workflows/dev/AGENTS.md

@@ -1,87 +0,0 @@
----
-id: dev/index
-category: dev
-name: Dev Workflow AGENTS Guide
-description: 开发工作流导航、状态汇报、下一步推荐与渐进披露指引
-keywords: [dev, 开发, workflow, index, agents, 状态]
----
-
-# Dev Workflow AGENTS Guide
-
-> ⚠️ **持久化铁律：本文件及所有 dev workflow 的全部产物，必须且只能写入 `speculo/.speculo/dev/<change>/`。绝对禁止写入项目根目录的 `.speculo/`、`temp/` 或其他任何非规范位置。**
-
-本文件是 dev 分类的 AGENTS 导航入口。进入时先读取 `speculo/.speculo/dev-status.json`，再按其中 active change 读取 `speculo/.speculo/dev/<change>/.status.json`，根据用户意图推荐下一步。
-
-> **命名铁律：** 所有 change 目录必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-user-auth`）。不符合此格式的目录视为 `malformed`，仅汇报不自动操作。
-
-## 渐进披露
-
-1. 先读本文件，确认当前 dev change、执行模式和入口别名。
-2. 选定入口后，只读取对应 workflow 入口文件（如 `03-tdd/03-tdd.md`）。
-3. 进入具体 phase 时，再读取该 phase 文件、模板和被调用 skill wrapper。
-4. 执行中如涉及项目硬约束、跨任务经验、领域上下文、术语定义、ADR 或决策依据，必须参考 `../../.speculo/.config/` 下对应文件；`RULES.md` 的约束高于普通 workflow 文案。
-5. 需要理解状态骨架、archive 或 `.config` 时，读取 `../../.speculo/AGENTS.md` 和相关子目录的 `AGENTS.md`。
-
-## 入口别名
-
-| 别名 | 入口 | 用途 |
-|------|------|------|
-| `dev/01` | `01-grill-with-docs/01-grill-with-docs.md` | 领域术语、CONTEXT、ADR 与方案拷问 |
-| `dev/02` | `02-prd/02-prd.md` | zoom-out 全景理解与 PRD 综合 |
-| `dev/03` | `03-tdd/03-tdd.md` | 垂直切片 TDD 实现 |
-| `dev/04` | `04-finalize/04-finalize.md` | 完成前验证、状态收尾与归档 |
-| `dev/I` | `I-to-issues/I-to-issues.md` | 垂直切片 issue 分解，可嵌入其他 dev workflow，也可独立进入 |
-| `dev/H` | `H-diagnose/H-diagnose.md` | hotfix / bug / 性能回退诊断，零依赖，可独立进入 |
-| `dev/R` | `R-review/R-review.md` | Spec / Engineering / Standards 三维度 diff 审查，零依赖，可独立进入 |
-| `dev/D` | `D-docs-sync/D-docs-sync.md` | 基于 git diff、归档产物和 `.config` 生命周期同步文档/知识资产 |
-| `dev/M` | `M-domain-modeling/M-domain-modeling.md` | 主动领域建模：挑战术语、压测边界，沉淀 CONTEXT 通用语言与 ADR；格式单一事实源，可嵌入其他 dev workflow，也可独立进入 |
-| `dev/A` | `A-improve-architecture/A-improve-architecture.md` | 深化机会扫描 + HTML 架构审查 + 质询，基于 `vendor/codebase-design` 词汇，零依赖，可独立进入 |
-
-## 进入协议
-
-1. 若用户未指定 change，扫描 `speculo/.speculo/dev-status.json` 和 `speculo/.speculo/dev/*/.status.json`，列出 active changes。
-   - **命名校验**：扫描时仅处理符合 `YYYY-MM-DD-<kebab-name>` 格式的目录。不符合的目录标记为 `malformed`，单独列出路径并提示用户修复或手动清理，不自动删除或重命名。
-2. 若只有一个 active change，默认继续该 change；若有多个 active change，要求用户选择。
-3. 若没有 active change，按用户意图创建新的 change。**以下三步为原子操作，不可跳过，前一步失败时停止后续并报告：**
-   - **3a. 创建 change 目录** —— `speculo/.speculo/dev/<YYYY-MM-DD>-<kebab-name>/`（使用当前日期，`<kebab-name>` 从用户意图提取，不超过 5 个词）。
-   - **3b. 写入 `.status.json`** —— 在 change 目录下创建 `.status.json`，按 `docs/persistence-contract.md` §2.2 最小初始化模板填入所有必填字段（`name`、`category: "dev"`、`change_status: "active"`、`created_at`、`updated_at`、`current_phase: "00-init"`、`phase_history`）。
-   - **3c. 更新 `dev-status.json`** —— 读取 `speculo/.speculo/dev-status.json`，在 `active[]` 中追加该 change 的索引条目（`name`、`current_phase: "00-init"`、`updated_at`），写回文件。
-   - 以上三步全部成功后，方可继续推荐入口。
-4. 推荐入口时优先使用用户显式别名；没有别名时按执行模式推荐。
-5. 执行任何 workflow 前，读取该 workflow 入口文件、阶段文件、模板和被调用 skill wrapper。
-6. 执行中一旦需要项目规则、经验、领域术语、上下文或 ADR，先读取 `../../.speculo/.config/`，再继续判断或写入产物；除非用户明确要求或规则允许，不自动改写 `.config/`。
-7. **Worktree 隔离（可选，默认 off）**：仅当用户**显式请求**隔离时，新 change 在 `dev/01` 的 Phase 0 经 `../../skills/worktree-isolation/SKILL.md` 建立隔离分支 `speculo/dev/<change>` 与 `.worktree/<change>/` 工作树，并把 `base_branch`、`change_branch` 记入 `.status.json`。扫描 active changes 时，对 `worktree_enabled` 为真者可结合 `git worktree list` 核对工作树是否存在。
-
-## 执行模式
-
-- `full`：`dev/01` -> `dev/02` -> `dev/I` -> `dev/03` -> `dev/04`。
-- `planning-only`：`dev/01` -> `dev/02` -> `dev/I`，不进入实现。
-- `implementation-only`：已有 PRD、issue 或明确任务时，从 `dev/03` 开始。
-- `hotfix`：Bug、异常、性能回退时，从 `dev/H` 开始（零依赖，无需上游工作流产物）；修复阶段可嵌入 `dev/03` 的 TDD 回归循环。
-- `review`：已有 fixed point 或用户要求审查时，从 `dev/R` 开始（零依赖，无需上游工作流产物）。
-- `finalize`：实现完成、需要完成前验证与状态收尾归档时，从 `dev/04` 开始。
-- `docs-sync`：需要基于 git 差异刷新对外文档时，从 `dev/D` 开始。
-- `domain-modeling`：需要主动澄清/锐化领域术语、维护 CONTEXT 与 ADR 时，从 `dev/M` 开始（零依赖；也被 `dev/01`、`dev/02`、`dev/04`、`dev/D`、`dev/A` 引用）。
-- `improve-architecture`：需要系统性发现并落实架构深化机会时，从 `dev/A` 开始（零依赖；建立在 `vendor/codebase-design` 词汇与 `dev/M` 领域模型之上）。
-
-> **独立入口说明：** `dev/H`、`dev/I`、`dev/R`、`dev/M`、`dev/A` 五个横向工作流均为零硬依赖设计。用户可直接从任一入口进入，无需预先执行 `dev/01`、`dev/02` 等主线工作流。当同 change 目录下缺少上游产物时，各工作流会自行通过代码库探索（git 考古、grep 搜索、文档扫描）采集所需上下文，仅在代码库无法确定的决策点上询问用户。
->
-> **横向工作流的共享底座：** `dev/M`（领域模型）拥有 CONTEXT / ADR 格式的单一事实源；`dev/A`（架构深化）与 `dev/03`（TDD）共享 `vendor/codebase-design` 的设计词汇（模块 / 接口 / 接缝 / 适配器 / 深度 / 杠杆 / 局部性）。引用方一律不复制这些规范。
-
-## 状态汇报
-
-输出 dev 状态时至少包含：
-
-- active change 数量与每个 change 的 `current_phase`
-- malformed 目录清单（不符合 `YYYY-MM-DD-<kebab-name>` 格式的目录）
-- 最近更新的 change，按 `updated_at` 倒序
-- `phase_history` 最后一项为 `blocked` 或 `updated_at` 超过 14 天未变化的 change
-- worktree 模式 change 额外汇报 `base_branch` / `change_branch` / `worktree_status`
-- 推荐下一步入口和原因
-
-## 完成与状态更新
-
-- 所有 dev workflow 必须维护同一 change 的 `.status.json`。
-- 进入 phase 时更新 `current_phase`，并在 `phase_history` 追加 `in-progress` 记录。
-- phase 完成时写入 `completed_at` 和 `status: completed`。
-- 只有完成当前 change 的最终交付边界时，才把 `change_status` 置为 `completed`。

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

@@ -1,127 +0,0 @@
----
-id: dev/D-docs-sync
-category: dev
-name: Docs Sync
-description: 基于 git 差异、归档产物和 .config 生命周期同步或初始化项目文档与知识资产
-keywords: [docs-sync, changelog, readme, agents, config, archive, adr, context, lessons, rules, documentation, 文档同步]
----
-
-# Docs Sync 工作流执行指引
-
-本工作流是 `dev/D` 入口，用于把一段 git 差异、归档产物和项目知识资产生命周期映射回 README、CHANGELOG、AGENTS、`docs/` 与 `speculo/.speculo/.config/`。常规状态下它只做基于事实的差量同步，不做整页重写，也不堆积没有当前代码或归档证据支撑的内容。
-
-当 `speculo/.speculo/dev/docs-sync-state.json` 没有同步内容（例如 `tracked_assets: []`、`last_sync_sha: null` 或 state 文件不存在）时，默认进入 `bootstrap` 模式：面向当前项目执行一次从 0 到 1 的完整文档初始化，自动盘点项目事实、推导首批 `tracked_assets`、创建缺失的基础文档，并在验证通过后建立首次同步基线。
-
-## 内置指引
-
-### Iron Law
-
-禁止在不读取 `speculo/.speculo/dev/docs-sync-state.json` 的 `last_sync_sha`、当前 `HEAD`、`speculo/.speculo/archive/` 相关归档产物与 `tracked_assets` 的情况下修改任何文档或 `.config` 知识资产。若 state 不存在或为空，也必须先按 `state-json-schema.md` 识别为 `bootstrap`，完成项目事实盘点后再创建或修改文档。
-
-已建立基线后，如果 diff 为空且归档/`.config` 审计没有 stale、missing 或 prune 信号，直接报告无需同步或空同步，并按规则推进 state；不要触碰无关资产。`bootstrap` 模式不视为空同步，必须完成初始化审计。
-
-文档更新必须是动态生命周期管理：每次同步都判断应新增、删除、修改、保留哪些内容。禁止只追加内容；发现旧事实、旧 ADR 引用、被当前实现反转的说明、空模板或重复沉淀时，必须删除、改写、标记废弃或在 report 中说明为何暂不处理。
-
-### 输入
-
-- `speculo/.speculo/dev/docs-sync-state.json`
-- 当前 git `HEAD`
-- state 中的 `tracked_assets` 列表
-- `speculo/.speculo/archive/` 中与本次 diff、路径、术语或决策相关的归档 change
-- `speculo/.speculo/.config/RULES.md`、`LESSONS.md`、`context/`、`adr/`
-- 当前 change 目录：`speculo/.speculo/dev/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-docs-sync`）
-
-### 输出
-
-- `speculo/.speculo/dev/<change>/docs-sync-report.md`
-- 初始化或更新后的 tracked assets
-- 更新后的 `speculo/.speculo/dev/docs-sync-state.json`
-
-（`<change>` 格式：`YYYY-MM-DD-<kebab-name>`）
-
-### 渐进披露
-
-- `readme-contract.md`：更新 README 类文档时读取。
-- `agents-contract.md`：更新 AGENTS / AI 代理手册类文档时读取。
-- `changelog-contract.md`：更新 CHANGELOG 类文档时读取。
-- `config-contract.md`：更新或审计 `speculo/.speculo/.config/` 时读取。
-- `knowledge-extract.md`：从 `speculo/.speculo/archive/` 提取知识沉淀时读取。
-- `state-json-schema.md`：初始化、迁移、读取或写回 docs-sync state 时读取。
-- `../M-domain-modeling/M-domain-modeling.md`：术语、ADR、上下文边界不稳定或一词多义时读取并调用其确认流程；写 CONTEXT / ADR 前还要按需读取 `../M-domain-modeling/CONTEXT-FORMAT.md` 或 `../M-domain-modeling/ADR-FORMAT.md`。
-
-> **通用语言对齐**：对外文档（README / AGENTS）中的领域术语以 `speculo/.speculo/.config/context/CONTEXT.md` 为准；同步中若发现文档与 CONTEXT 术语漂移，交由 `../M-domain-modeling/M-domain-modeling.md` 沉淀，docs-sync 本身不另立或重定义领域术语。
->
-> **RULES 写入边界**：`speculo/.speculo/.config/RULES.md` 是用户维护资产。docs-sync 可以读取、审计并在 report 中提出增删改建议；只有用户明确确认某条规则改动时才写入。
-
-## 阶段
-
-### 1. State Read — 读取同步状态
-- 规范：`docs-sync-state.md`
-- 模板：`../_templates/docs-sync-state-template.json`
-- 产物：`speculo/.speculo/dev/docs-sync-state.json`
-- 完成准则：
-  - 已确定 `LAST_SYNC_SHA` 和 `HEAD_SHA`
-  - v1 state 已迁移或已明确阻塞
-  - 首次空 state 已进入 `bootstrap` 模式，并已生成首批 `tracked_assets` 候选与初始化范围
-
-### 2. Diff Collect — 收集 git 差异
-- 规范：`docs-sync-diff.md`
-- 模板：无
-- 产物：`docs-sync-report.md`
-- 完成准则：
-  - 常规同步已记录 git log、name-status、shortstat、路径分组和 archive/.config 相关 diff
-  - `bootstrap` 模式下已完成项目文件、元数据、命令、入口、文档缺口和 `.config` 的全量盘点
-  - 已判断哪些资产需要新增、删除、修改或保留
-
-### 3. Knowledge Extract — 归档知识沉淀
-- 规范：`knowledge-extract.md`
-- 模板：`../_templates/docs-sync-report-template.md`
-- 产物：`docs-sync-report.md`
-- 完成准则：
-  - 已读取本次范围内新增/变更的 archive 高信号产物
-  - 已把归档中的决策、术语、规则、经验和文档漂移信号映射到 tracked assets
-  - 不确定或多语义项已转交 `../M-domain-modeling/M-domain-modeling.md` 或标记为待确认
-
-### 4. Asset Audit & Update — 审计并差量更新资产
-- 规范：`docs-sync-update.md`
-- 模板：`../_templates/docs-sync-report-template.md`
-- 产物：`docs-sync-report.md`
-- 完成准则：
-  - 常规同步只修改 `tracked_assets` 中需要同步的资产；`bootstrap` 模式可先把推导出的基础文档纳入 `tracked_assets` 并创建缺失资产
-  - README / CHANGELOG / AGENTS 类文档遵守对应 contract
-  - `.config` 资产遵守 `config-contract.md`
-  - ADR / CONTEXT 语义不稳定时已调用 `../M-domain-modeling/M-domain-modeling.md`
-  - `docs-sync-report.md` 无残留 `[TODO:]`
-
-### 5. State Write — 验证与写回状态
-- 规范：`docs-sync-finish.md`
-- 模板：`../_templates/docs-sync-report-template.md`
-- 产物：`speculo/.speculo/dev/docs-sync-state.json`
-- 完成准则：
-  - 已运行项目级校验或记录无法运行原因
-  - state 已原子写入
-  - 已向用户报告范围、改动资产和新基线
-
-## 依赖
-
-- 软依赖：`../M-domain-modeling/M-domain-modeling.md`，用于不稳定术语、上下文边界和 ADR 候选确认
-- 硬依赖：git 仓库；首次空 state 默认执行 `bootstrap` 文档初始化。写入 `RULES.md`、删除 `.config` 文件或确认不稳定术语/ADR 时，仍需要用户明确确认
-
-## 状态扩展字段
-
-本工作流需在同 change 的 `.status.json` 追加：
-
-- `dev_entry` (string) — 固定为 `dev/D`
-- `docs_sync_state_path` (string) — 固定为 `speculo/.speculo/dev/docs-sync-state.json`
-- `docs_sync_range` (string) — 常规同步为 `<LAST_SYNC_SHA>..HEAD`，`bootstrap` 模式为 `<bootstrap>..HEAD`
-- `tracked_assets` (array) — 本次纳入同步的文档和 `.config` 资产
-- `synced_assets` (array) — 本次实际修改的资产
-- `archive_sources` (array) — 本次读取的归档产物路径
-- `config_audit_status` (none | proposed | confirmed | updated | blocked) — `.config` 审计/写入状态
-- `docs_sync_status` (bootstrap | first-run | no-op | extracting | updating | synced | blocked) — 同步状态
-
-## 完成与状态更新
-
-- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
-- 只有验证完成后才原子写回 `speculo/.speculo/dev/docs-sync-state.json`。
-- 本 workflow 不自动完成 change；用户要求仅同步文档时，可在报告完成后把 `change_status` 置为 `completed`。

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 已移交后续阶段