@namewta/speculo 0.7.4 → 0.7.5

package/README.md

@@ -60,7 +60,7 @@ After initialization, the target project gains the following AI agent-callable a
 | `migrate-runtime-state` | Validate backups, lock source/target fingerprints, and apply runtime migration plans with rollback |
 | `optimize-codex-config` | Audit and optimize local Codex configuration, custom Responses providers, permissions, and compaction failures |
 | `speculo-retro` | Retrospective analysis |
-| `typescript-standards-builder` | Interview-driven generator that produces a project-specific TypeScript/JS/React/Node standards skill |
+| `engineering-standards-builder` | Interview-driven generator that produces a project-specific TypeScript/JS/React/Node standards skill |
 | `writing-great-skills` | Authoring guidance for agent skills |
 
 ### 2 Workflow Packages
@@ -68,7 +68,7 @@ After initialization, the target project gains the following AI agent-callable a
 | Workflow | Work Entries | Description |
 |---|---:|---|
 | **specdev** | 14 | Local-first specification-driven development: archive, code review, diagnosis, mentoring, grilling, implementation, setup, goal planning, prototyping, architecture review, specs, tickets, triage, and wayfinding |
-| **person** | 1 | Persona-methodology-based consulting workflow (Mao Zedong Cognitive OS) |
+| **person** | 2 | Persona-methodology and rigorous deliberation workflows (Mao Zedong Cognitive OS; Bidirectional Steelman Deliberation) |
 
 Every workflow ships an `INDEX.md` as its auto-generated work catalog. Work entries follow `<Letter>-<work_name>/<Letter>-<work_name>.md` naming with progressive-disclosure sub-files, and resolve runtime paths via `<Path>{roots.xxx}/...</Path>` pointers in `workspace.json`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "Workflow-packaged specification-driven development assets with state-safe refresh tooling.",
   "type": "module",
   "bin": {

package/template/canonical/README.md

@@ -1,95 +1,240 @@
-# Canonical — AI 平台单文件分发格式
+# Canonical — 独立能力与可移植持久化规范
 
-Canonical 格式将 Speculo 多文件能力（skill、command、workflow）合并为**自包含的单 MD 文档**，可直接上传到仅支持单文件的 AI 平台（ChatGPT Projects、Claude Projects、NotebookLM 等），上传后平台即可获得该能力的完整定义与知识背景。
+项目地址：https://github.com/NAMEWTA/Speculo
 
-## 与源文件的关系
+Canonical 是可以单独上传到网页 AI 平台的 Markdown 能力文档。每一份文档都必须像一个完整运行单元：不依赖源仓库或第二份能力定义，同时把运行过程产生的状态、分析、决定和交付物写入统一的便携目录，支持暂停、恢复、交接和审计。
 
-| | 源文件（`skills/`、`commands/`） | Canonical 文档 |
-|---|---|---|
-| 形态 | 多文件目录结构 | 单文件 MD |
-| 内容 | 原始分片文件 + 跨文件引用 | 主入口 + 所有引用文件内联合并 |
-| 用途 | Speculo 运行时加载与组合 | AI 平台上传分发 |
-| 更新 | `speculo init` 覆盖刷新 | 按需从源文件重新生成 |
+## 两个同等重要的目标
 
-Canonical 文档是源文件的**透明容器**——去除 Speculo 内部元数据（YAML frontmatter、`<Path>` 标签），用简单 XML 隔离标签区分不同来源文件的内容。
+### 定义隔离
 
-## 文档结构
+最终文档只描述能力本身，不暴露生成它的目录、源文件、脚本、内部路由、安装方式或维护者约定。读者只凭当前文档和自己的材料即可开始使用。
 
-```markdown
-# <能力名称>
+### 运行持久化
 
-<主入口文件正文（已去除 YAML frontmatter）。其中：
-- 所有 <Path> 标签已替换为纯文本描述
-- 所有文件引用已替换为"参见下方 <xxx> 标签"
-- 标准 Markdown 书写规范>
+最终文档不能退化成一次性聊天提示。凡能力会生成产物、等待用户回答、跨轮推进或在中断后继续，都必须定义真实文件输出和恢复依据。
 
----
+统一持久化根为：
 
-## 参考内容
+```text
+ai-workspace/
+```
 
-<子文件名>
+这是文档自身定义的便携输出命名空间，不是任何源仓库目录。用户可以把它放在自己的项目目录、平台可写工作区、挂载文件区或任意本地保存位置。
+
+## 标准目录结构
+
+```text
+ai-workspace/
+├── status.json
+├── changes/
+│   └── YYYY-MM-DD-<topic>/
+│       ├── .status.json
+│       ├── source.md
+│       ├── LOG.md
+│       └── <能力拥有的工件>
+├── knowledge/
+│   ├── decisions/
+│   ├── context/
+│   └── research/
+└── archive/
+```
 
-<子文件的完整正文（已去除 YAML frontmatter，保留 Markdown 格式）>
+目录职责：
 
-</子文件名>
+| 路径 | 职责 |
+|---|---|
+| `ai-workspace/status.json` | 全局 active change 索引和当前阶段，不替代权威工件 |
+| `ai-workspace/changes/{change}/.status.json` | 单次 change 的状态、阶段、owned artifacts、阻塞与更新时间 |
+| `ai-workspace/changes/{change}/source.md` | 原始请求、初始材料和不可丢失上下文 |
+| `ai-workspace/changes/{change}/LOG.md` | 高价值决定、替代关系、偏差和恢复事件的追加记录 |
+| `ai-workspace/changes/{change}/...` | 各能力自己的主工件和子工件 |
+| `ai-workspace/knowledge/decisions/` | 跨 change 的稳定决定 |
+| `ai-workspace/knowledge/context/` | 可复用领域上下文与术语 |
+| `ai-workspace/knowledge/research/` | 可复用研究结果与证据摘要 |
+| `ai-workspace/archive/` | 经明确规则或授权归档的完成记录 |
 
-<另一子文件>
+所有路径使用正斜杠相对路径。不得使用机器绝对路径、反斜杠、空路径段或 `..`。
 
-<另一子文件的完整正文>
+## change 命名与选择
 
-</另一子文件>
+change 使用：
+
+```text
+YYYY-MM-DD-<kebab-topic>
 ```
 
-### 关键规则
+选择顺序：
+
+1. 用户显式指定合法 change；
+2. 未指定时，从 `ai-workspace/status.json` 恢复与当前能力匹配的唯一 active change；
+3. 没有候选时创建新 change；
+4. 同名存在时追加最小数字后缀；
+5. 多个候选无法消歧时列出候选并停止，不自行猜测。
 
-- **纯 Markdown 文档**：不使用 `<canonical>` 或 `<source-file>` 包裹标签。它就是一份普通 MD 文件。
-- **无 YAML frontmatter**：去除所有源文件的 `---` 元数据块。这是 Speculo 内部标记，AI 平台不需要。
-- **无 `<Path>` 标签**：将 `<Path>{roots.xxx}/path/</Path>` 替换为自然语言描述。
-- **子文件 XML 隔离**：被引用的子文件用 `<filename>...</filename>` 包裹，标签名取文件名去 `.md` 扩展名。
-- **单文件自包含**：所有引用内容全量内联，无外部依赖，无渐进式披露。
+恢复必须读取 `.status.json` 和该能力的权威工件。模型记忆、聊天摘要或“继续上次”不能替代文件证据。
 
-## 文件处理规则
+## 最小状态格式
+
+全局状态至少包含：
+
+```json
+{
+  "schema_version": 1,
+  "active": [
+    {
+      "change": "2026-08-18-example",
+      "capability": "能力名称",
+      "phase": "active",
+      "updated_at": "2026-08-18T00:00:00Z"
+    }
+  ]
+}
+```
+
+change 状态至少包含：
+
+```json
+{
+  "schema_version": 1,
+  "change": "2026-08-18-example",
+  "status": "active",
+  "current_capability": "能力名称",
+  "phase": "active",
+  "owned_artifacts": [],
+  "updated_at": "2026-08-18T00:00:00Z",
+  "blockers": []
+}
+```
 
-| 文件类型 | 处理方式 |
-|----------|----------|
-| 主入口文件（SKILL.md / INDEX.md / work .md） | 作为文档主体，去除 frontmatter |
-| `references/*.md` | 内联至文末，用 XML 标签隔离 |
-| `routes/*.md` | 内联至文末，用 XML 标签隔离 |
-| `atomic-skills/*.md` | 内联至文末，用 XML 标签隔离 |
-| `assets/*.json` | 内联至文末，用 XML 标签隔离 |
-| `_state/`、`.speculo/`、`.gitkeep` | 排除——运行时状态，非能力定义 |
+每份能力文档会进一步规定自己的 phase、owned artifacts 和 completed 条件。读取—合并—写入时保留未知字段，也不得覆盖其他能力的 active 条目。
 
-## 生成方法
+## 持久化写入顺序
 
-SpecDev 的设计、规格、Tickets、Goal Plan 和 Wayfinder canonical 使用 Node 脚本从当前模板统一生成：
+每次状态变化使用固定顺序：
 
-```bash
-pnpm generate-canonical
+```text
+形成完整候选工件
+→ 按文内门禁自检
+→ 替换正式工件
+→ 更新 change .status.json
+→ 最后更新全局 status.json
+→ 返回写入证据
 ```
 
-其他 canonical 按 `speculo-write-canonical` skill 的流程手动拼接：
+工件与状态冲突时保持阻塞，列出冲突和恢复动作。不能为了继续流程而猜测哪个版本正确。
+
+## 平台可写与不可写
+
+### 平台可直接写文件
+
+实际创建或更新 `ai-workspace/`，完成后返回：
+
+- change；
+- 当前 phase；
+- 实际写入的相对路径；
+- 已执行的内容门禁与结果；
+- 阻塞项或下一步。
+
+只有工具确认成功后才能声称“已持久化”。
+
+### 平台无法直接写入文件
+
+仍必须形成完整持久化交付。每个发生状态变化的回复都输出所有更新文件的完整内容，而不是只给摘要或 diff：
+
+## 持久化交付
+
+- 持久化状态：需要保存
+- change：`<change>`
+- 更新文件：列出全部路径
+
+### FILE: ai-workspace/status.json
+
+```json
+{
+  "schema_version": 1,
+  "active": []
+}
+```
+
+### FILE: ai-workspace/changes/<change>/.status.json
+
+```json
+{
+  "schema_version": 1,
+  "change": "<change>",
+  "status": "active",
+  "phase": "<phase>"
+}
+```
+
+### FILE: ai-workspace/changes/<change>/<artifact>.md
+
+```markdown
+# 工件标题
+
+完整工件内容。
+```
+
+这类 FILE bundle 是运行产物的运输形式，不是第二份能力定义。下一轮必须先读取用户保存后重新提供的文件，再继续；不能只依赖对话记忆。
+
+## 每份文档必须说明的内容
+
+一份合格能力文档应直接回答：
+
+1. 解决什么问题，何时使用与不使用；
+2. 用户至少需要提供什么；
+3. 事实、推断、偏好与未知如何区分；
+4. 必须按什么顺序工作；
+5. 拥有哪些路径，读取哪些路径，不得修改哪些路径；
+6. 首次运行怎样创建 change；
+7. 暂停时写入哪些文件，恢复时读取哪些文件；
+8. 完成时产生哪些工件，怎样更新状态；
+9. 平台不可写时怎样输出完整文件包；
+10. 高风险、证据不足、并发冲突和验证失败时怎样阻塞。
+
+## 定义隔离规则
+
+每份文档只保留一次项目地址。除此之外：
+
+- 不出现其他网址；
+- 不出现源项目名称或内部体系名称；
+- 不出现源目录、源文件名、内部路径映射或内部脚本；
+- 不出现来源清单、内容哈希、生成时间或源码标签；
+- 不要求上传第二份能力文件；
+- 不把源实现路径当作运行输出路径；
+- 允许并要求出现 canonical 自己定义的 `ai-workspace/`、状态文件和运行工件。
+
+## 多轮能力的要求
+
+需要多轮交互时必须明确：
 
-1. 读取能力源目录，识别主入口和所有被引用文件
-2. 去除所有 YAML frontmatter
-3. 替换所有 `<Path>` 为纯文本描述
-4. 将子文件内容内联至文末，用 XML 隔离标签包裹
-5. 质量检查：无 `<Path>` 残留、无 frontmatter 残留、所有引用已内联
+- 第一轮创建或更新哪些文件；
+- 在哪里强制停止；
+- 用户下一条消息需要回答什么；
+- 恢复时读取哪些文件；
+- 哪些内容不得提前输出；
+- 用户已在初始输入中给出答案时如何跳过重复追问；
+- 状态与工件不一致时如何阻塞；
+- 完成后如何保留历史并清理 active 条目。
 
-详细说明见 `.agents/skills/speculo-write-canonical/SKILL.md`，格式示例见该 skill 的 `references/canonical-example.md`。
+不能把“恢复快照”当作唯一状态。可复制快照只能在平台不可写时作为完整文件包的一部分。
 
-## 上传到 AI 平台
+## 内容质量门禁
 
-| 平台 | 上传方式 |
-|------|----------|
-| **Claude Projects** | 项目设置 → Knowledge → 上传文件，或将内容粘贴到 Project Instructions |
-| **ChatGPT 自定义 GPT** | Configure → Knowledge → Upload files |
-| **NotebookLM** | 新建笔记本 → 添加来源 → 上传文件 |
-| **其他平台** | 查找"上传知识库""添加文档""自定义指令"等功能入口 |
+交付前逐项确认：
 
-上传 canonical 文档后，平台即可基于完整的能力定义回答问题或执行任务。
+- 第一条非空行是一级标题；
+- 项目地址恰好出现一次，没有其他网址；
+- 没有源项目目录、文件名、命令、脚本、来源标签或生成清单；
+- 已定义 `ai-workspace/status.json` 与 change `.status.json`；
+- 已列出能力拥有的具体工件路径；
+- 已定义首次运行、暂停、恢复和完成状态；
+- 已定义平台不可写时的完整 FILE bundle；
+- 输出不是通用建议，而是可保存、可验证、可继续运行的工件；
+- 无法执行的动作没有被写成已经完成；
+- 正常、缺失输入、多个候选、证据不足和高风险场景都有明确处理。
 
-## 注意事项
+## 使用方式
 
-- **Workflow 体积**：workflow 文件较多，生成的 canonical 文档较长。这属于预期行为——自包含性优先于简洁性。
-- **跨 workflow 引用**：如果能力引用了其他 workflow 的文件，在文档开头注明建议的配套上传文件和 GitHub 仓库地址。
-- **canonical-teach.md**：源在仓库外 vendor 目录（`temp/matt-pocock-skills/.../teach/`），不在 `template/` 内，不参与与 template 源文件的同步校验。
+选择与任务匹配的一份能力文档，将它作为项目知识或对话指令上传，然后提供真实问题和材料。模型应先创建或恢复 `ai-workspace/` change，再按能力协议推进。每次状态变化都必须留下实际写入文件或完整可保存文件包。