@haaaiawd/loom 0.9.0 → 1.0.0

package/cli/help/preview.md

@@ -43,7 +43,8 @@ preview_mtime >= source_latest_mtime → fresh
 - `03_DECISIONS/`
 - `04_INTENT_MAP.json`
 - `05_VERIFICATION.md`
-- `06_CHANGELOG.md`
+- `06_CHANGELOG.json`（Patch 唯一权威来源）
+- `06_CHANGELOG.md`（确定性生成投影）
 - `verifications/`
 
 ## 为什么不直接打开旧 preview

package/cli/help/version.md

@@ -2,23 +2,95 @@
 
 LOOM 用 .loom/v{N}/ 目录支持多版本共存与演进。
 
-## 什么时候升级版本
-
-| 变更类型 | 判定标准 | 处理方式 |
-|---|---|---|
-| Minor | 不改哲学前提、不改愿景北极星、不改架构边界 | 当前版本内改（变更回流机制） |
-| Major | 哲学前提变了、愿景北极星变了、架构边界变了 | 创建新版本 |
-
-判定由用户 + Agent 对话完成，CLI 不做决策。
-
-## Major 升级流程
+## 什么时候演进版本
+
+| 变更类型 | 判定标准 | 处理方式 |
+|---|---|---|
+| Patch | 不触及 Intent，不改变验收契约，只修 bug / 样式 / 实现细节 | 当前版本内修正，跑验证并记录 changelog；不进入 Intent Loop |
+| Minor | 新增或修改 Intent，但不改哲学前提、不改愿景北极星、不改架构边界 | 当前版本内改（变更回流机制），相关 Intent 进入 pending / needs_review |
+| Major | 哲学前提变了、愿景北极星变了、架构边界变了 | 创建新版本 |
+
+判定由用户 + Agent 对话完成，CLI 不做决策。
+
+哲学修订可用 CLI 做后果分析和审计记录，但 CLI 不自动编辑哲学正文：
+
+```bash
+loom philosophy impact <anchor>
+loom philosophy revise <anchor> --classification clarification --reason "<why>"
+loom philosophy revise <anchor> --classification minor --reason "<why>"
+loom philosophy revise <anchor> --classification major --reason "<why>"
+```
+
+前两条 revise 在没有 `--confirm` 时严格只读，并返回精确确认命令。确认 clarification 时 `--review` 必须为空，所有直接引用和传递影响均归入 `--unaffected`。确认 minor 时每个影响必须恰好一次归入 `--review` 或 `--unaffected`；review 中仅 `completed` 转为 `needs_review`，其余状态原样报告。两者均不改 acceptance，并写入下一个 `03_DECISIONS/PHIL-REV-NNN.md`。Major 即使带 `--confirm` 也不改当前版本，只提示 `loom version new`。哲学正文随后由 Weaver/用户单独编辑。
+
+## Patch 流程
+
+Patch 用于纯实现修正：bugfix、样式微调、文案 typo、测试补强。它不改变 Intent，也不改变验收契约。
+
+```bash
+# 1. 确认当前 Intent 都已完成
+loom guide
+
+# 2. 修改实现细节后，按项目约定跑测试 / lint
+
+# 3. 如修复影响已有承诺，补一条验证记录
+loom verify write --json-file <path>
+
+# 4. 通过 CLI 写入权威 JSON 并生成 Markdown 投影
+loom patch record --json-file <path>
+loom patch validate
+```
+
+Patch 不应使用 `loom version new`，也不应新增 Intent。如果变更需要改验收契约，它已经不是 Patch。
+完整输入契约见 `loom help patch`。
+
+## Minor 流程
+
+Minor 用于当前哲学和架构边界内的能力演进。
+
+常见情况：
+- 新增功能 → 由 Visionary 补叙事，Architect 增加 Intent，再进入 Intent Loop
+- 修改已有功能承诺 → 将相关 Intent 标记为 `needs_review`，重新验证 / 实现
+- 一个改动影响已完成 Intent → 通过反向依赖 / 哲学引用找影响面，标记 `needs_review`
+- 当前版本能力退出但仍需保留历史与依赖图 → 用 `intent deprecate` 记录 lifecycle，不虚构 `deprecated` status
+
+```bash
+# 新增：先创建 draft，再分别由 Visionary / Architect 补齐叙事、契约和锚点
+loom intent add --title "<title>" --depends-on INT-001,INT-002
+loom activate visionary --intent INT-003
+loom activate architect --intent INT-003
+loom intent finalize INT-003
+
+# 修订：revision 自动递增，并返回直接/传递反向依赖
+loom intent revise <id> --reason "<why>"
+loom activate visionary --intent <id>
+loom activate architect --intent <id>
+# 必须完整分类所有直接与传递下游；review 会使已完成下游回流复验
+loom intent finalize <id> --review <ids> --unaffected <ids>
+
+# 弃用：先评估，确认时完整分类所有直接和传递依赖方
+loom intent deprecate <id> --reason "<why>"
+loom intent deprecate <id> --reason "<why>" --confirm --review <ids> --unaffected <ids>
+
+# 继续按 guide 进入收敛趟
+loom guide
+```
+
+`add` / `revise` 在 finalize 前不修改官方 `04_INTENT_MAP.json` 和 `topo_order`。`add` 还会向愿景和验证文档追加明确标记的 draft 章节；finalize 通过后提升这些章节并删除 draft。新增 Intent 是 `pending`；修订保留 `pending` / `in_progress` / `blocked` / `needs_review`，原 `completed` 变为 `needs_review`，旧 revision 的验证自动失效。
+
+当前版本内演进不是偷懒；只要哲学前提、北极星、架构边界没变，Minor 就应该留在当前版本。
+
+弃用要求目标已完成。它写入 `lifecycle.deprecation = { deprecated_at, reason, replacement }`，不改变目标的 `completed` status，也不删除节点、依赖或契约。可选 replacement 必须是另一个当前版本 Intent。所有直接和传递依赖方必须在 review/unaffected 中恰好分类一次；叶子无需分类。重复确认会失败，避免不同参数被误认为已应用。
+
+## Major 升级流程
 
 \`\`\`bash
 # 1. 创建新版本（空目录 + 模板，自动切换为当前）
 loom version new
 
-# 2. 看看旧版本有什么（Agent 决定参考什么）
-loom version diff v1 v2
+# 2. 看文件变化与显式 Intent 沿革
+loom version diff v1 v2
+loom intent diff v1 v2
 
 # 3. Weaver 读旧哲学，织造新哲学
 loom activate weaver
@@ -39,7 +111,9 @@ loom activate architect
 
 - **空目录 + 模板**：\`loom version new\` 不自动复制旧版本内容。强制重新思考——参考 ≠ 复制。
 - **旧版本只读**：当前指针指向的版本是当前真相，旧版本保留作历史参考。
-- **Intent ID 重新编号**：v2 的 INT-001 和 v1 的 INT-001 没有关系。追溯靠 Git history 和 \`loom version diff\`。
+- **显式 Intent lineage**：可用 `lineage: { predecessors: [{ version: "v1", intent_id: "INT-003" }], change_summary, change_ref? }` 表达修订、拆分或合并。它不属于 `depends_on`；同 ID/标题不会自动映射。
+- **版本元数据**：脚手架写入真实 `_loom_version`，并写入 `_parent_version`（v1 为 `null`，新版本为创建前的当前版本）。
+- **历史只读**：`v1:INT-003` 可用于 `intent get/narrative/trace` 和 `verify history`，写命令仍只操作当前版本。
 
 ## 版本管理命令
 
@@ -48,13 +122,15 @@ loom version list              # 列出所有版本（* 标记当前）
 loom version current           # 显示当前版本
 loom version new               # 创建 v{N+1} + 自动切换
 loom version use <v>           # 切换当前版本
-loom version diff <v1> <v2>    # 对比文件差异
+loom version diff <v1> <v2>    # 对比文件差异
+loom intent diff <v1> <v2>     # 对比显式 lineage 与语义字段
+loom verify history v2:INT-007 --across-versions
 \`\`\`
 
 ## 切换回旧版本
 
 \`\`\`bash
 loom version use v1            # 切回 v1 查看历史
-loom intent trace <id>         # 在 v1 中追溯 Intent 历史
+loom intent trace v1:INT-003   # 无需切换即可只读历史 Intent
 loom version use v2            # 切回 v2 继续
-\`\`\`
+\`\`\`

package/cli/help/workflow.md

@@ -1,100 +1,89 @@
-## LOOM 工作流
-
-从零到交付的完整流程。每个阶段有明确的产出和验收标准。
-
-## 第一步：诊断当前阶段
-
-\`\`\`bash
-loom guide
-\`\`\`
-
-guide 检测项目当前在哪个阶段，输出"你在阶段 X，下一步做 Y"。
-Agent 每完成一步都跑 guide 确认下一步。
-审计、预演、子代理探测时用 `loom guide --dry-run`，避免写 `.loom/heartbeat.json`。
-
-## AUTO 模式
-
-\`\`\`bash
-loom auto on      # 开启：Agent 自动连续执行，不等确认
-loom auto off     # 关闭：每步需要用户确认
-\`\`\`
-
-AUTO on 时 Agent 一路跑到底，跑完生成 preview 给人看。
-AUTO off 时每步停下等用户说继续。
-
-## 阶段 1：织造哲学（Weaver）
-
-\`\`\`bash
-loom activate weaver
-\`\`\`
-
-Weaver 根据项目特征从真实思想体系织造定制化哲学。产出：
-- PRODUCT_PHILOSOPHY.md — 产品价值观、反模式清单、决策取舍规则
-- ENGINEERING_CREED.md — 工程原则（按需）
-- DECISION_RUBRIC.md — 冲突时的优先级（按需）
-- PROJECT_BASELINE.md — 项目特定底线（按需）
-
-**验收**：哲学有北极星、有反模式、有决策标准。全是空话就重做。
-
-## 阶段 2：定义愿景（Visionary）
-
-\`\`\`bash
-loom activate visionary
-\`\`\`
-
-基于哲学定义产品愿景，为每个 Intent 写意图叙事（"为什么存在"）。产出：
-- 01_VISION.md — 北极星 + 意图叙事列表
-
-**验收**：叙事是"为什么"不是"做什么"。写成功能列表就重做。
-
-## 阶段 3：设计系统（Architect）
-
-\`\`\`bash
-loom activate architect
-\`\`\`
-
-基于愿景设计系统结构，绘制 Intent Map。产出：
-- 02_ARCHITECTURE.md — 系统设计
-- 04_INTENT_MAP.json — Intent 依赖图 + 验收契约 + 哲学锚点
-
-**验收**：验收契约具体到可验证，依赖无环，每个 Intent 有叙事引用。
-跑 \`loom intent validate\` 校验结构，跑 \`loom doctor\` 检查完整性。
-
-## 阶段 4：Intent Loop
-
-\`\`\`bash
-loom activate keeper    # Keeper 选 Intent、验证
-loom activate forge     # Forge 实现
-loom intent next        # 下一个可执行 Intent
-loom context            # 当前状态摘要
-\`\`\`
-
-每个 Intent 独立走一圈：选 → 实现 → 验证 → 闭合或修正。
-详细流程见 \`loom help loop\`。
-
-## 阶段 5：人类预览
-
-\`\`\`bash
-loom preview status
-loom preview
-loom preview --regen
-\`\`\`
-
-preview 是给人看的只读投影。Agent 应先跑 `loom preview status`：
-- `fresh=true` → 运行 `loom preview` 打开
-- `fresh=false` → 运行 `loom preview --regen`，按提示词重写 `loom-preview.html`，再打开
-- 用户明确要看旧版 → `loom preview --stale`
-
-详细规则见 `loom help preview`。
-
-## 阶段 6：版本演进（按需）
-
-当哲学前提/愿景北极星/架构边界变了，需要 Major 升级。
-详细流程见 \`loom help version\`。
-
-## 核心原则
-
-- **哲学是经线，意图是纬线** — 所有角色共享哲学锚点
-- **底线不可协商** — BASELINE 5 条 + 项目特定底线，角色激活时强制加载
-- **意图可回溯** — 每个 Intent 携带叙事，Keeper 独立验证忠实度
-- **文档开销不超过开发开销** — 小项目可以粗粒度，不必教条
+## LOOM 工作流
+
+## 0. 诊断
+
+```bash
+loom guide
+loom context
+```
+
+只读探测使用 `loom guide --dry-run`。
+
+## 1. Doctrine — Weaver
+
+```bash
+loom activate weaver
+loom philosophy check
+```
+
+输出项目长期判断、卓越标准、决策原则、创作空间、反模式与 Evidence Map。
+研究数量不设配额；只保留真实改变判断、能够追溯的证据。
+
+## 2. Intent — Visionary
+
+```bash
+loom activate visionary
+```
+
+输出产品目标、成功图景、非目标与 Intent narrative。Visionary 不写 acceptance、DAG 或架构。
+
+## 3. Contract — Architect
+
+```bash
+loom activate architect
+loom intent validate
+loom doctor
+```
+
+Architect 产出系统边界、Intent DAG、完成契约和可选质量契约，并声明
+`capability_needs` 与 `creative_scope`。
+
+完成契约定义 **Reliability Floor**：做到什么才算可靠完成。
+质量契约定义 **Distinctive Ceiling**：什么可观察差异让结果不止合格。
+
+## 4. Quality Engine — Forge 与 Keeper
+
+```bash
+loom intent next
+loom intent update <id> --status in_progress
+loom activate forge --intent <id>
+loom activate keeper --intent <id>
+```
+
+Forge 编译 Expertise Pack，在 Quality Arena 中实现与比较。
+Keeper 从当前磁盘事实和契约独立验证，不继承 Forge 的解释。
+
+无质量契约时，四个基础维度通过即可闭合。存在质量契约时，额外验证
+`quality_achievement`；声明相对提升时，在该维度中链接 Quality Proof：
+
+```bash
+loom verify pass <id> \
+  --summary "<具体证据>" \
+  --reproduction-command "<可复现命令>" \
+  --quality-proof "<基线、比较和稳定性证据的位置>"
+
+loom intent done <id>
+```
+
+复杂或混合判定使用 `loom verify write --json-file <path>`。
+
+## 5. Reflow
+
+验证偏离时，不要把所有问题都扔回 Forge：
+
+- Doctrine 不足 → Weaver
+- 产品目标错误 → Visionary
+- 契约、边界或依赖错误 → Architect
+- 专业判断或实现不足 → Forge
+- 证据不足 → Keeper 补证或 `pending_human`
+
+连续三次 `deviated` 自动升级为 `blocked`。所有当前 revision 和当前验证 epoch 的 Intent 都有最新 passed
+记录，且没有 `needs_review`、`loom doctor` 没有 fatal/high 风险时，本轮收敛。
+
+## 6. 演进
+
+- Patch：不改变 Intent 语义，验证后记录 changelog。
+- Minor：用 `loom intent add|revise` 创建 draft，经限定作用域的 Visionary/Architect 更新后 finalize。
+- Major：Doctrine、北极星或主要架构边界改变，使用 `loom version new`。
+
+原则只有一句：流程成本必须小于它降低的风险；质量声明必须小于等于它拥有的证据。