@namewta/speculo 0.1.18 → 0.1.20

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

@@ -8,19 +8,19 @@
 
 - docs-sync workflow **唯一**的跨 change 持久化状态
 - 每次成功同步后原子化写入
-- 必须跟随仓库提交到 git（作为同步基线的事实来源）
+- 必须跟随仓库提交到 git（作为同步基线和 tracked assets 的事实来源）
 - **不放在 workflow 资产目录内**：workflow 目录是只读知识资产，状态属于项目 `speculo/.speculo/`
 
 **初始化模板**：`../_templates/docs-sync-state-template.json`
 
-## 字段定义
+## 字段定义（schema_version 2）
 
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|:---:|------|
-| `schema_version` | integer | ✓ | 当前 `1`；字段破坏性变化时递增 |
+| `schema_version` | integer | ✓ | 当前 `2`；字段破坏性变化时递增 |
 | `skill` | string | ✓ | 固定为 `"docs-sync"`，便于多技能共用项目根目录时辨识 |
 | `state_path` | string | ✓ | 自描述字段：state 文件相对仓库根的路径；协助协作者理解文件位置 |
-| `tracked_docs` | string[] | ✓ | 本项目纳入同步的文档路径（相对仓库根）；首次运行后由用户确认写入 |
+| `tracked_assets` | string[] | ✓ | 本项目纳入同步的文档和 `.config` 知识资产路径（相对仓库根）；首次空 state 由 `bootstrap` 初始化自动推导写入 |
 | `last_sync_sha` | string (40 hex) \| `null` | ✓ | 上次成功同步后记录的 commit SHA；下次 diff 的起点；首次运行前为 `null` |
 | `last_sync_short` | string (7 hex) \| `null` | ✓ | `last_sync_sha` 的前 7 位，便于日志阅读 |
 | `last_sync_commit_subject` | string \| `null` | ✓ | 上次基线 commit 的 subject 行 |
@@ -28,7 +28,12 @@
 | `last_sync_run_at` | string (ISO 8601 UTC) \| `null` | ✓ | 本次同步**完成写入**时刻；与 `last_sync_commit_date` 不同 —— 前者是"我什么时候做的"，后者是"基线 commit 什么时候创建的" |
 | `previous_sync_sha` | string (40 hex) \| `null` | ✓ | 上一次的 `last_sync_sha`；首次运行时为 `null` |
 | `total_syncs` | integer | ✓ | 累计触发次数（含空同步） |
-| `synced_docs` | string[] | ✓ | 本次**实际被修改**的对外文档文件名数组；空同步时为 `[]` |
+| `synced_assets` | string[] | ✓ | 本次**实际被修改**的 tracked assets；空同步时为 `[]` |
+
+`tracked_assets` 支持两类写法：
+
+- 精确路径：`README.md`、`AGENTS.md`、`speculo/.speculo/.config/RULES.md`
+- 受限 Markdown glob：`docs/**/*.md`、`speculo/.speculo/.config/context/**/*.md`、`speculo/.speculo/.config/adr/**/*.md`
 
 **禁止**放入的字段：
 
@@ -36,6 +41,7 @@
 - 用户个人信息
 - 密钥 / token
 - 绝对路径（影响跨环境协作）
+- archive 提取详情和用户确认原文（写入 report，不写 state）
 
 ## 典型状态
 
@@ -43,10 +49,10 @@
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "skill": "docs-sync",
   "state_path": "speculo/.speculo/dev/docs-sync-state.json",
-  "tracked_docs": [],
+  "tracked_assets": [],
   "last_sync_sha": null,
   "last_sync_short": null,
   "last_sync_commit_subject": null,
@@ -54,37 +60,37 @@
   "last_sync_run_at": null,
   "previous_sync_sha": null,
   "total_syncs": 0,
-  "synced_docs": []
+  "synced_assets": []
 }
 ```
 
-### 建立基线后（首次运行完成）
+### 建立基线后（首次 bootstrap 完成）
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "skill": "docs-sync",
   "state_path": "speculo/.speculo/dev/docs-sync-state.json",
-  "tracked_docs": ["README.md", "CHANGELOG.md"],
+  "tracked_assets": ["README.md", "CHANGELOG.md", "AGENTS.md", "docs/**/*.md", "speculo/.speculo/.config/LESSONS.md"],
   "last_sync_sha": "2d16d7a4d7f5da165c565b9aa3265824be133214",
   "last_sync_short": "2d16d7a",
   "last_sync_commit_subject": "chore: initial release",
   "last_sync_commit_date": "2026-05-10T09:48:14+08:00",
   "last_sync_run_at": "2026-05-10T12:00:00Z",
   "previous_sync_sha": null,
-  "total_syncs": 0,
-  "synced_docs": []
+  "total_syncs": 1,
+  "synced_assets": ["README.md", "CHANGELOG.md", "AGENTS.md"]
 }
 ```
 
-### 常规同步（实际改了两份文档）
+### 常规同步（实际改了两份资产）
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "skill": "docs-sync",
   "state_path": "speculo/.speculo/dev/docs-sync-state.json",
-  "tracked_docs": ["README.md", "CHANGELOG.md"],
+  "tracked_assets": ["README.md", "CHANGELOG.md", "speculo/.speculo/.config/LESSONS.md"],
   "last_sync_sha": "abc1234def5678...",
   "last_sync_short": "abc1234",
   "last_sync_commit_subject": "feat(cli): add --json to status",
@@ -92,18 +98,18 @@
   "last_sync_run_at": "2026-05-15T14:00:00Z",
   "previous_sync_sha": "2d16d7a4d7f5da165c565b9aa3265824be133214",
   "total_syncs": 3,
-  "synced_docs": ["README.md", "CHANGELOG.md"]
+  "synced_assets": ["README.md", "speculo/.speculo/.config/LESSONS.md"]
 }
 ```
 
-### 空同步（diff 全是文档自身）
+### 空同步（diff 与知识审计都无需修改）
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "skill": "docs-sync",
   "state_path": "speculo/.speculo/dev/docs-sync-state.json",
-  "tracked_docs": ["README.md", "CHANGELOG.md"],
+  "tracked_assets": ["README.md", "CHANGELOG.md", "AGENTS.md", "docs/**/*.md"],
   "last_sync_sha": "ffe9876abc5432...",
   "last_sync_short": "ffe9876",
   "last_sync_commit_subject": "docs(readme): fix typo",
@@ -111,7 +117,7 @@
   "last_sync_run_at": "2026-05-16T11:00:00Z",
   "previous_sync_sha": "abc1234def5678...",
   "total_syncs": 4,
-  "synced_docs": []
+  "synced_assets": []
 }
 ```
 
@@ -126,10 +132,11 @@
 
 读取 state 文件时按以下降级链处理：
 
-1. 文件不存在 → 首次运行流程：复制 `../_templates/docs-sync-state-template.json` 到 `speculo/.speculo/dev/docs-sync-state.json`，基线设为当前 HEAD，请用户确认 `tracked_docs`
+1. 文件不存在 → 复制 `../_templates/docs-sync-state-template.json` 到 `speculo/.speculo/dev/docs-sync-state.json`，进入 `bootstrap` 文档初始化；不要立即把基线设为当前 HEAD
 2. JSON 解析失败 → 报错退出，要求用户手动修复或删除
-3. `schema_version > 1` → 报错退出，提示技能版本过旧
-4. `last_sync_sha` 不是 40 字符十六进制且不为 `null` → 视为损坏，回退到首次运行
+3. `schema_version > 2` → 报错退出，提示技能版本过旧
+4. `last_sync_sha` 不是 40 字符十六进制且不为 `null` → 视为损坏，回退到 `bootstrap` 文档初始化
+5. `tracked_assets` 为空或 `last_sync_sha` 为 `null` → 进入 `bootstrap` 文档初始化，自动推导首批 tracked assets 并完成从 0 到 1 的文档建档
 
 ## 版本演进规则
 
@@ -140,6 +147,16 @@
 
 递增时必须在本文件追加"vN → vN+1 迁移"小节，描述如何处理老格式。
 
+## v1 → v2 迁移
+
+v2 把 docs-only 命名扩展为 assets：
+
+- `tracked_docs` → `tracked_assets`
+- `synced_docs` → `synced_assets`
+- `schema_version` → `2`
+
+迁移时保留 baseline 字段、`previous_sync_sha` 和 `total_syncs`。若迁移后仍有有效 `tracked_assets` 和 `last_sync_sha`，不要自动扩大同步范围；若迁移后 `tracked_assets` 为空或 `last_sync_sha` 为 `null`，进入 `bootstrap` 文档初始化。
+
 ## 与 git 的协作
 
 - state 文件**提交到 git**，作为仓库的一部分

package/template/workflows/dev/M-domain-modeling/ADR-FORMAT.md

@@ -16,11 +16,36 @@ ADR 存放在 `speculo/.speculo/.config/adr/` 目录下，使用顺序编号：`
 
 就这些。一个 ADR 可以只是一段话。价值在于记录「做出了某个决策」以及「为什么」——而不是填满各个章节。
 
+## 生命周期元数据
+
+默认 ADR 不需要元数据。只有当决策需要生命周期联动时，在标题下方放极简字段：
+
+```md
+# {决策的简短标题}
+
+Status: accepted
+superseded_by: null
+
+{1-3 句话：背景是什么、我们决定了什么、为什么这样决定。}
+```
+
+允许值：
+
+- `Status: proposed | accepted | deprecated | superseded`
+- `superseded_by: ADR-NNNN | null`
+
+当新 ADR 取代旧 ADR 时：
+
+- 新 ADR 正文说明取代了哪个 ADR 以及原因。
+- 旧 ADR 顶部更新为 `Status: superseded` 和 `superseded_by: ADR-NNNN`。
+- 若项目有 ADR 索引或 README，同步状态和取代链。
+- 任何 CONTEXT、AGENTS、README 或 docs 中的旧 ADR 引用都必须改为新 ADR、删除，或标记为待确认。
+
 ## 可选章节
 
 只有确实能增加价值时才包含以下章节。大多数 ADR 不需要它们。
 
-- **Status** 前置元数据（`proposed | accepted | deprecated | superseded by ADR-NNNN`）—— 当决策被重新审视时很有用
+- **Status** 前置元数据（见「生命周期元数据」）—— 当决策被重新审视时很有用
 - **Considered Options** —— 只有被拒绝的替代方案值得记住时才写
 - **Consequences** —— 只有非显而易见的下游影响需要指出时才写
 

package/template/workflows/dev/_templates/docs-sync-report-template.md

@@ -6,19 +6,35 @@
 
 ## Range
 
-[TODO: 记录 `<LAST_SYNC_SHA>..HEAD`、commit 数、文件数和 shortstat。]
+[TODO: 记录 `<LAST_SYNC_SHA>..HEAD`；bootstrap 模式写 `<bootstrap>..HEAD`，并说明本次为首次文档初始化。]
+
+## Bootstrap Initialization
+
+[TODO: 仅 bootstrap 模式填写：记录项目事实盘点、自动推导的 tracked assets、缺失文档清单和初始化动作；常规同步写 `N/A`。]
 
 ## Diff Summary
 
-[TODO: 记录 git log、name-status 和路径分组摘要。]
+[TODO: 记录 git log、name-status、路径分组、archive/.config 相关 diff 摘要。]
+
+## Archive Sources
+
+[TODO: 列出本次读取的 `speculo/.speculo/archive/` 产物路径；没有相关归档时写 `[]` 和原因。]
+
+## Knowledge Suggestions
+
+[TODO: 记录从归档提取的 ADR / CONTEXT / RULES / LESSONS / 文档漂移候选，包含来源路径和动作。]
+
+## Config Audit
+
+[TODO: 记录 `.config` 审计结果，按 add / update / delete / keep / propose-only 分组；RULES 写入确认单独记录。]
 
 ## Mapping
 
-[TODO: 说明哪些变更映射到哪些 tracked docs。]
+[TODO: 说明哪些变更或 bootstrap 初始化发现映射到哪些 tracked assets。]
 
-## Synced Docs
+## Synced Assets
 
-[TODO: 列出实际修改的文档和一句话说明；空同步时写 `[]`。]
+[TODO: 列出实际创建或修改的资产和一句话说明；空同步时写 `[]`。]
 
 ## Verification
 

package/template/workflows/dev/_templates/docs-sync-state-template.json

@@ -1,8 +1,8 @@
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "skill": "docs-sync",
-  "state_path": ".speculo/dev/docs-sync-state.json",
-  "tracked_docs": [],
+  "state_path": "speculo/.speculo/dev/docs-sync-state.json",
+  "tracked_assets": [],
   "last_sync_sha": null,
   "last_sync_short": null,
   "last_sync_commit_subject": null,
@@ -10,5 +10,5 @@
   "last_sync_run_at": null,
   "previous_sync_sha": null,
   "total_syncs": 0,
-  "synced_docs": []
+  "synced_assets": []
 }

package/template/workflows/dev/_templates/tdd-log-template.md

@@ -7,6 +7,9 @@
 ## 阶段标识
 [TODO: 本阶段 `<phase-id>`（与同目录 `tdd-plan.md` 一致）。]
 
+## Git 状态变化
+[TODO: 记录相对 `tdd-plan.md` 执行前基线新增/变化的 dirty、staged、untracked 文件，以及未知改动的处理结论。]
+
 ## 循环记录
 [TODO: 对每轮 RED/GREEN/REFACTOR 记录切片、行为、测试、实现摘要、重构摘要和验证结果。]
 

package/template/workflows/dev/_templates/tdd-plan-template.md

@@ -10,6 +10,9 @@
 ## 切片来源
 [TODO: 记录来自 PRD、slices、diagnosis 还是用户直接请求。]
 
+## 执行前 Git 基线
+[TODO: 记录当前分支、`git status --short --branch` 摘要、`git diff --stat`、`git diff --cached --stat`。若不是 git 仓库或命令失败，记录原因。]
+
 ## 保留/不动（约束）
 [TODO: 承接本切片「保留/不动」：实现中不能碰的代码/契约/数据（冻结常量、共享依赖、邻近功能）；无则写「无」。]
 

package/template/workflows/doc/{00-INDEX.md → AGENTS.md}

@@ -1,19 +1,27 @@
 ---
 id: doc/index
 category: doc
-name: Doc Workflow Index
-description: 文档写作、塑形、编辑与素材管理的横向工作流导航入口
-keywords: [doc, writing, article, fragments, edit, 文档, 写作]
+name: Doc Workflow AGENTS Guide
+description: 文档写作、塑形、编辑与素材管理的横向工作流导航与渐进披露指引
+keywords: [doc, writing, article, fragments, edit, agents, 文档, 写作]
 ---
 
-# Doc Workflow Index
+# Doc Workflow AGENTS Guide
 
 > ⚠️ **持久化铁律：本文件及所有 doc workflow 的全部产物，必须且只能写入 `speculo/.speculo/doc/<change>/`。绝对禁止写入项目根目录的 `.speculo/`、`temp/` 或其他任何非规范位置。**
 
-本文件是 doc 分类的导航入口。进入时先读取 `speculo/.speculo/doc-status.json`，再按其中 active change 读取 `speculo/.speculo/doc/<change>/.status.json`，根据用户意图推荐横向 workflow。
+本文件是 doc 分类的 AGENTS 导航入口。进入时先读取 `speculo/.speculo/doc-status.json`，再按其中 active change 读取 `speculo/.speculo/doc/<change>/.status.json`，根据用户意图推荐横向 workflow。
 
 > **命名铁律：** 所有 change 目录必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-article-draft`）。不符合此格式的目录视为 `malformed`，仅汇报不自动操作。
 
+## 渐进披露
+
+1. 先读本文件，确认当前 doc change、写作模式和入口别名。
+2. 选定入口后，只读取对应 workflow 入口文件（如 `S-writing-shape/S-writing-shape.md`）。
+3. 进入具体 phase 时，再读取该 phase 文件、模板和被调用 skill wrapper。
+4. 执行中如涉及项目硬约束、跨任务经验、写作上下文、术语定义、ADR 或决策依据，必须参考 `../../.speculo/.config/` 下对应文件；`RULES.md` 的约束高于普通 workflow 文案。
+5. 需要理解状态骨架、archive 或 `.config` 时，读取 `../../.speculo/AGENTS.md` 和相关子目录的 `AGENTS.md`。
+
 ## 入口别名
 
 | 别名 | 入口 | 用途 |
@@ -36,6 +44,7 @@ keywords: [doc, writing, article, fragments, edit, 文档, 写作]
    - 以上三步全部成功后，方可继续推荐入口。
 4. 推荐入口时优先使用用户显式别名；没有别名时按用户意图推荐一个横向 workflow。
 5. 执行任何 workflow 前，读取该 workflow 入口文件、阶段文件和模板。
+6. 执行中一旦需要项目规则、经验、上下文、术语或 ADR，先读取 `../../.speculo/.config/`，再继续判断或写入产物；除非用户明确要求或规则允许，不自动改写 `.config/`。
 
 ## 执行模式
 

package/template/workflows/person/{00-INDEX.md → AGENTS.md}

@@ -1,19 +1,27 @@
 ---
 id: person/index
 category: person
-name: Person Workflow Index
-description: 以人物方法论为底座的工作流导航入口
-keywords: [person, methodology, 人物, 方法论, cognitive, 认知]
+name: Person Workflow AGENTS Guide
+description: 以人物方法论为底座的工作流导航与渐进披露指引
+keywords: [person, methodology, agents, 人物, 方法论, cognitive, 认知]
 ---
 
-# Person Workflow Index
+# Person Workflow AGENTS Guide
 
 > ⚠️ **持久化铁律：本文件及所有 person workflow 的全部产物，必须且只能写入 `speculo/.speculo/person/<change>/`。绝对禁止写入项目根目录的 `.speculo/`、`temp/` 或其他任何非规范位置。**
 
-本文件是 person 分类的导航入口。进入时先读取 `speculo/.speculo/person-status.json`，再按其中 active change 读取 `speculo/.speculo/person/<change>/.status.json`，根据用户意图推荐横向 workflow。
+本文件是 person 分类的 AGENTS 导航入口。进入时先读取 `speculo/.speculo/person-status.json`，再按其中 active change 读取 `speculo/.speculo/person/<change>/.status.json`，根据用户意图推荐横向 workflow。
 
 > **命名铁律：** 所有 change 目录必须为 `YYYY-MM-DD-<kebab-name>`（例：`2026-06-12-mao-strategy-consult`）。不符合此格式的目录视为 `malformed`，仅汇报不自动操作。
 
+## 渐进披露
+
+1. 先读本文件，确认当前 person change、咨询模式和入口别名。
+2. 选定入口后，只读取对应 workflow 入口文件（如 `M-mao-zedong-cognitive-os/M-mao-zedong-cognitive-os.md`）。
+3. 进入具体 phase 时，再读取该 phase 文件、模板和被调用 skill wrapper。
+4. 执行中如涉及项目硬约束、跨任务经验、人物方法论上下文、术语定义、ADR 或决策依据，必须参考 `../../.speculo/.config/` 下对应文件；`RULES.md` 的约束高于普通 workflow 文案。
+5. 需要理解状态骨架、archive 或 `.config` 时，读取 `../../.speculo/AGENTS.md` 和相关子目录的 `AGENTS.md`。
+
 ## 入口别名
 
 | 别名 | 入口 | 用途 |
@@ -28,6 +36,7 @@ keywords: [person, methodology, 人物, 方法论, cognitive, 认知]
 3. 若没有 active change，按用户意图创建新的 change 目录，**目录名必须为 `YYYY-MM-DD-<kebab-name>`**（使用当前日期，`<kebab-name>` 从用户意图提取），并初始化 `.status.json` 与 `speculo/.speculo/person-status.json`。
 4. 推荐入口时优先使用用户显式别名；没有别名时按用户意图推荐一个横向 workflow。
 5. 执行任何 workflow 前，读取该 workflow 入口文件、阶段文件和模板。
+6. 执行中一旦需要项目规则、经验、上下文、术语或 ADR，先读取 `../../.speculo/.config/`，再继续判断或写入产物；除非用户明确要求或规则允许，不自动改写 `.config/`。
 
 ## 执行模式