@namewta/speculo 0.1.17 → 0.1.19

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

@@ -2,33 +2,39 @@
 id: dev/D-docs-sync
 category: dev
 name: Docs Sync
-description: 基于 git 差异增量同步 README、CHANGELOG、AGENTS 等对外文档
-keywords: [docs-sync, changelog, readme, agents, documentation, 文档同步]
+description: 基于 git 差异、归档产物和 .config 生命周期同步或初始化项目文档与知识资产
+keywords: [docs-sync, changelog, readme, agents, config, archive, adr, context, lessons, rules, documentation, 文档同步]
 ---
 
 # Docs Sync 工作流执行指引
 
-本工作流是 `dev/D` 入口，用于把一段 git 差异映射回对外文档。它只做差量同步，不从零创建文档，也不做整页重写。
+本工作流是 `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` 之间 diff 的情况下修改任何对外文档。
+禁止在不读取 `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` 模式不视为空同步，必须完成初始化审计。
 
-如果 diff 为空，或只有文档自身变动，直接报告无需同步或空同步，并按规则推进 state；不要触碰无关文档。
+文档更新必须是动态生命周期管理：每次同步都判断应新增、删除、修改、保留哪些内容。禁止只追加内容；发现旧事实、旧 ADR 引用、被当前实现反转的说明、空模板或重复沉淀时，必须删除、改写、标记废弃或在 report 中说明为何暂不处理。
 
 ### 输入
 
 - `speculo/.speculo/dev/docs-sync-state.json`
 - 当前 git `HEAD`
-- state 中的 `tracked_docs` 列表
+- 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 docs
+- 初始化或更新后的 tracked assets
 - 更新后的 `speculo/.speculo/dev/docs-sync-state.json`
 
 （`<change>` 格式：`YYYY-MM-DD-<kebab-name>`）
@@ -38,9 +44,14 @@ keywords: [docs-sync, changelog, readme, agents, documentation, 文档同步]
 - `readme-contract.md`：更新 README 类文档时读取。
 - `agents-contract.md`：更新 AGENTS / AI 代理手册类文档时读取。
 - `changelog-contract.md`：更新 CHANGELOG 类文档时读取。
-- `state-json-schema.md`：初始化、读取或写回 docs-sync state 时读取。
+- `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 中提出增删改建议；只有用户明确确认某条规则改动时才写入。
 
 ## 阶段
 
@@ -50,38 +61,51 @@ keywords: [docs-sync, changelog, readme, agents, documentation, 文档同步]
 - 产物：`speculo/.speculo/dev/docs-sync-state.json`
 - 完成准则：
   - 已确定 `LAST_SYNC_SHA` 和 `HEAD_SHA`
-  - 首次运行时已初始化 state 并要求用户确认 `tracked_docs`
+  - v1 state 已迁移或已明确阻塞
+  - 首次空 state 已进入 `bootstrap` 模式，并已生成首批 `tracked_assets` 候选与初始化范围
 
 ### 2. Diff Collect — 收集 git 差异
 - 规范：`docs-sync-diff.md`
 - 模板：无
 - 产物：`docs-sync-report.md`
 - 完成准则：
-  - 已记录 git log、name-status、shortstat 和路径分组
-  - 已判断是否需要修改文档
+  - 常规同步已记录 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` 或标记为待确认
 
-### 3. Docs Update — 差量更新文档
+### 4. Asset Audit & Update — 审计并差量更新资产
 - 规范：`docs-sync-update.md`
 - 模板：`../_templates/docs-sync-report-template.md`
 - 产物：`docs-sync-report.md`
 - 完成准则：
-  - 只修改 `tracked_docs` 中需要同步的文档
+  - 常规同步只修改 `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:]`
 
-### 4. State Write — 验证与写回状态
+### 5. State Write — 验证与写回状态
 - 规范：`docs-sync-finish.md`
 - 模板：`../_templates/docs-sync-report-template.md`
 - 产物：`speculo/.speculo/dev/docs-sync-state.json`
 - 完成准则：
   - 已运行项目级校验或记录无法运行原因
   - state 已原子写入
-  - 已向用户报告范围、改动文档和新基线
+  - 已向用户报告范围、改动资产和新基线
 
 ## 依赖
 
-- 软依赖：无
-- 硬依赖：git 仓库；首次运行需要用户确认 `tracked_docs`
+- 软依赖：`../M-domain-modeling/M-domain-modeling.md`，用于不稳定术语、上下文边界和 ADR 候选确认
+- 硬依赖：git 仓库；首次空 state 默认执行 `bootstrap` 文档初始化。写入 `RULES.md`、删除 `.config` 文件或确认不稳定术语/ADR 时，仍需要用户明确确认
 
 ## 状态扩展字段
 
@@ -89,10 +113,12 @@ keywords: [docs-sync, changelog, readme, agents, documentation, 文档同步]
 
 - `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`
-- `tracked_docs` (array) — 本次纳入同步的文档
-- `synced_docs` (array) — 本次实际修改的文档
-- `docs_sync_status` (first-run | no-op | updating | synced | blocked) — 同步状态
+- `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) — 同步状态
 
 ## 完成与状态更新
 

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

@@ -0,0 +1,75 @@
+# .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` 文件级删除默认进入 `../../../commands/config-prune.md --dry-run` 候选。
+
+可进入 prune 候选的典型情况：
+
+- 被取代超过 30 天且无活跃引用的 ADR。
+- 指向不存在 ADR 的索引行或正文引用。
+- 空置占位文件或只含 TODO 的长期资产。
+- CONTEXT 中已无代码、文档或归档证据支撑的术语。
+- LESSONS 中重复或被 RULES/ADR 吸收的经验。
+
+删除 `.config` 文件或 RULES 条目前必须有用户明确确认。

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

@@ -5,6 +5,7 @@
 - `speculo/.speculo/dev/docs-sync-state.json`
 - `LAST_SYNC_SHA`
 - 当前 `HEAD`
+- state 中的 `tracked_assets`
 
 ## 产物
 
@@ -12,6 +13,31 @@
 
 ## 填写引导
 
+### 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
@@ -20,6 +46,7 @@ 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
 ```
 
 有疑问的具体改动再读取：
@@ -29,7 +56,7 @@ git log -p "$RANGE" -- <specific-path>
 git show <sha> -- <specific-file>
 ```
 
-把变更按对外可见性映射到 `tracked_docs`：
+把变更按资产类型映射到 `tracked_assets`：
 
 - 对外能力变化：README 类 + CHANGELOG
 - 内部重构但行为未变：视情况写 CHANGELOG 或 AGENTS 类约定
@@ -38,13 +65,22 @@ git show <sha> -- <specific-file>
 - 文档自身：仅在对外可见时写 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_docs` 的文档，除非先获得用户确认并更新 state。
+- 常规同步不修改未列入 `tracked_assets` 的资产，除非先获得用户确认并更新 state；`bootstrap` 模式可把基础文档创建候选先纳入初始化 `tracked_assets`，再修改。
+- 不因为某路径出现在 diff 中就自动扩写文档；必须判断旧内容是否仍然成立，是否应该删除或压缩。
+- `bootstrap` 模式不虚构路线图、未实现能力或不存在的命令；无法从项目事实确认的内容进入 `propose-only` 或询问用户。
 
 ## 完成准则
 
-- git 差异素材已记录到 report
-- 已列出要更新的文档和理由，或判定空同步
+- git 差异素材或 `bootstrap` 项目盘点已记录到 report
+- 已列出要新增、删除、修改、保留的资产和理由，或判定空同步
+- archive 与 `.config` 相关 diff 已移交后续阶段

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

@@ -2,7 +2,7 @@
 
 ## 输入
 
-- 更新后的 tracked docs
+- 更新后的 tracked assets
 - `speculo/.speculo/dev/docs-sync-state.json`
 - `speculo/.speculo/dev/<change>/docs-sync-report.md`
 - 当前 `HEAD`
@@ -15,19 +15,23 @@
 ## 填写引导
 
 1. 运行项目级校验；命令根据项目工具链决定。
-2. 如果所有差异都无需文档修改，仍把 `last_sync_sha` 推进到当前 `HEAD`，并把 `synced_docs` 置为 `[]`。
-3. 如果修改了文档，验证通过后再推进 state。
-4. 写回 state 时按 `state-json-schema.md` 字段顺序，2 空格缩进，尾部换行。
-5. 原子化写入：先写 `speculo/.speculo/dev/docs-sync-state.json.tmp`，再 rename。
-6. 按 report 模板向用户报告范围、改动文档、新基线和验证命令。
+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 已包含同步范围、改动文档、验证结果
+- report 已包含同步范围、读取归档、改动资产、`.config` 审计、验证结果
 - `.status.json` 的 `docs_sync_status` 已更新

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

@@ -5,6 +5,7 @@
 - `speculo/.speculo/dev/docs-sync-state.json`
 - `git rev-parse HEAD`
 - `../_templates/docs-sync-state-template.json`
+- `state-json-schema.md`
 
 ## 产物
 
@@ -14,19 +15,33 @@
 ## 填写引导
 
 1. 设置 `STATE_FILE="speculo/.speculo/dev/docs-sync-state.json"`。
-2. 若 state 文件不存在，复制 `../_templates/docs-sync-state-template.json` 为骨架，把 `state_path` 设为 `speculo/.speculo/dev/docs-sync-state.json`。
-3. 读取 `last_sync_sha` 和当前 `HEAD`。
-4. 若 `tracked_docs` 为空，列出候选文档，请用户确认后写入 state；本次不修改对外文档。
-5. 若 `last_sync_sha` 为 `null`，把当前 `HEAD` 建为初始基线；本次不修改对外文档。
-6. 若 `last_sync_sha == HEAD`，报告 docs 已同步，无需操作。
+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 写到仓库根目录。
-- 不在首次运行时猜测 `tracked_docs`。
-- 不修改对外文档。
+- 首次空 state 不等待用户确认 `tracked_assets`；必须自动进入 `bootstrap` 初始化，并在 report 中说明推导依据。
+- 不因 v1 迁移自动扩大已有同步范围；只有迁移后 `tracked_assets` 为空或 `last_sync_sha` 为 `null` 时才进入 `bootstrap`。
+- 不在 State Read 阶段直接推进 `last_sync_sha`；基线只在 Finish 阶段验证通过后写回。
+- 不在未确认时写入 `RULES.md`、删除 `.config` 文件或固化存在语义争议的 CONTEXT / ADR。
 
 ## 完成准则
 
-- 已确定是否首次运行、无需同步或继续进入 diff collect
+- 已确定是否进入 `bootstrap`、无需同步或继续进入 diff collect
+- v1 state 已迁移为 v2，或已明确阻塞原因
 - `.status.json` 的 `docs_sync_status` 已更新

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

@@ -1,35 +1,44 @@
-# Docs Update Phase
+# Asset Audit & Update Phase
 
 ## 输入
 
 - `speculo/.speculo/dev/<change>/docs-sync-report.md`
-- state 中的 `tracked_docs`
+- state 中的 `tracked_assets`
 - git 差异素材
+- archive 知识提取结果
 - 按需读取的 contract 文件
 
 ## 产物
 
-- 更新后的 tracked docs
+- 更新后的 tracked assets
 - `speculo/.speculo/dev/<change>/docs-sync-report.md`
 
 ## 填写引导
 
-1. 更新 README 类文档前读取 `readme-contract.md`。
-2. 更新 AGENTS / AI 代理手册类文档前读取 `agents-contract.md`。
-3. 更新 CHANGELOG 类文档前读取 `changelog-contract.md`。
-4. 所有文档只做差量修改，保留既有结构、语气和字段。
-5. 多语言镜像文档必须结构对等；代码实体不翻译。
-6. CHANGELOG 顶部必须保留 `[Unreleased]`。
-7. AGENTS 类的仓库布局小节必须反映实际顶层目录变化。
+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 或代理手册。
+- 常规同步不整页重写 README 或代理手册；`bootstrap` 模式只在文件缺失时创建完整初始文件，已有文件仍以审计和差量修订为主。
 - 不添加没有对应代码来源的计划中能力。
 - 不把 docs-sync state 放回 skill 或 workflow 目录。
+- 不自动删除 `.config` 文件；删除候选进入 report 或 `../../../commands/config-prune.md` dry-run，执行删除需要用户确认。
+- 不把归档产物正文大段复制到长期文档；只沉淀可复用结论，并保留路径引用。
 
 ## 完成准则
 
-- 需要同步的 tracked docs 已完成差量修改
-- `docs-sync-report.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

@@ -0,0 +1,66 @@
+# 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 路径。
+- 每个知识候选都有来源路径和生命周期动作。
+- 无证据或低信号内容未写入长期资产。
+- 不确定项已标记为待确认或移交领域建模。