@haaaiawd/loom 0.10.0 → 1.1.0

package/cli/help/loop.md

@@ -1,135 +1,120 @@
-## Intent Loop 详细流程
-
-每个 Intent 独立走一圈。Loop 终止条件：所有 Intent 为 completed 且无 needs_review（不动点达成）。
-
-## Step 1：Keeper 选 Intent
-
-\`\`\`bash
-loom intent next          # 返回下一个可执行 Intent（pending 且依赖都 completed）
-loom context              # 当前状态摘要（进度+下一步+风险）
-\`\`\`
-
-如果没有可执行的 Intent：
-- 全部 completed → 项目阶段完成
-- 有 blocked → 需要人工介入
-- 有 in_progress 但无验证记录 → 可能上次中断，跑 \`loom doctor\` 诊断
-
-## Step 2：更新状态
-
-\`\`\`bash
-loom intent update <id> --status in_progress
-\`\`\`
-
-## Step 3：Forge 实现
-
-\`\`\`bash
-loom activate forge
-\`\`\`
-
-Forge 加载：意图叙事 + 哲学锚点 + 验收契约，在约束下自主实现代码。
-辅助命令（三个命令的分工）：
-- \`loom intent narrative <id>\` — 读意图叙事（"为什么做"）
-- \`loom verify contract <id>\` — 读验收契约（"做成什么样才算数"）
-- \`loom intent trace <id>\` — 完整追溯链（叙事+契约+哲学锚点一次性加载，最常用）
-- \`loom philosophy get <anchor>\` — 读哲学原则（遇到取舍时查）
-
-## Step 4：Keeper 验证
-
-\`\`\`bash
-loom activate keeper
-loom verify contract <id>     # 重新加载验收契约
-\`\`\`
-
-Keeper 独立验证四维度：
-1. 意图忠实度 — 实现是否忠于原始意图叙事
-2. 哲学一致性 — 实现是否符合哲学原则
-3. 底线合规 — 是否违反 BASELINE
-4. 验收达成 — 是否满足验收契约
-
-写入验证记录：
-\`\`\`bash
-loom verify write --json-file verification.json
-\`\`\`
-
-验证记录格式（\`loom verify write\` 的输入）：
-\`\`\`json
-{
-  "intent_id": "INT-001",
-  "verdict": "passed",
-  "timestamp": "2026-06-28T12:00:00.000Z",
-  "summary": "具体证据描述——不是'看起来没问题'",
-  "reproduction_command": "LLM_API_KEY=mock npm test",
-  "dimensions": {
-    "intent_fidelity": {
-      "verdict": "passed",
-      "evidence": "对照意图叙事第 2 段，extract.js 实现了完整编排"
-    },
-    "philosophy_consistency": {
-      "verdict": "passed",
-      "evidence": "AI_PHILOSOPHY 反模式逐条对照：JSON.parse 有 try/catch、fetch 有超时、无硬编码密钥"
-    },
-    "baseline_compliance": {
-      "verdict": "passed",
-      "evidence": "B1-B5 逐条合规"
-    },
-    "acceptance_achievement": {
-      "verdict": "passed",
-      "evidence": "6 条契约全部达成，npm test 6/6 pass"
-    }
-  }
-}
-\`\`\`
-CLI 自动包装成 \`{ intent_id, records: [{ round, ... }] }\` 追加到验证文件。
-\`dimensions\` 每个维度必须是 \`{ verdict, evidence }\` 对象——不允许只写"合规"，必须写具体证据。
-\`reproduction_command\` 是复现验证的命令——别人跑这个命令能复现你的验证结果。L2 必填。
-
-**evidence 写法参考**：
-- 长度：每条 evidence 50-300 字符为宜。太短（"合规"）不达标，太长难读。
-- 哲学一致性维度：按哲学锚点逐条对照反模式（见 keeper.md 的"承诺验证法"）
-- 其他维度：写"对照了什么 + 在代码哪里看到/没看到"
-- \`reproduction_command\` 注意平台差异：
-  - Unix/Mac: \`LLM_API_KEY=mock npm test\`
-  - Windows PowerShell: \`$env:LLM_API_KEY='mock'; npm test\`
-  - Windows cmd: \`set LLM_API_KEY=mock && npm test\`
-- \`node --test\` 在 Windows 上不能用目录路径（\`node --test test/\` 会报错），用 glob：\`node --test test/*.test.js\`
-
-## Step 5：根据判定结果
-
-| verdict | 处理 |
-|---|---|
-| passed | \`loom intent update <id> --status completed\`，回到 Step 1 |
-| deviated | 与 Forge 对话修正，重新实现重新验证。连续 3 轮升级 blocked |
-| blocked | \`loom intent update <id> --status blocked\`，停下报告用户 |
-| pending_human | **手动模式**：等用户补充判定（L3 人类反馈）。7 天超时升级 blocked |
-
-**AUTO 模式下的判定规则**（关键差异）：
-- AUTO 模式开启时（\`loom auto on\`），**不允许 pending_human**
-- Keeper 遇到 L3 verification_method 时，用 L1+L2 能耐自主判定所有维度
-- 要么 passed（有证据），要么 deviated（有偏离说明），不停下等人类
-- **持续运行，除非出意外否则不允许私自停止**
-- "出意外" = blocked（依赖阻塞/契约无法判定/连续 3 轮 deviated 升级）、fatal 错误
-
-## 变更回流
-
-如果 Forge 发现验收契约不合理、或 Architect 的设计需要调整：
-1. Keeper 评估变更范围（微调 vs 结构性变更）
-2. 微调（验收措辞、验证方式）→ Keeper 直接改
-3. 结构性变更（增减 Intent、改依赖）→ 重新激活 Architect
-4. 受影响的已完成 Intent 标记为 needs_review
-
-## 不动点收敛
-
-默认单趟：所有 Intent 按拓扑序验证完毕且全 passed → done。
-
-触发收敛：Pass 1 结束后还有 needs_review 的 Intent → 自动进入 Pass 2。
-- Pass 2: 重验所有 needs_review 的 Intent
-  - deviated → 修 → 重验
-  - 修的时候又影响别的 → 标记 needs_review
-  - passed → completed
-- Pass 2 结束还有 needs_review → Pass 3
-- Pass 3 结束还有 needs_review → blocked，报告"无法收敛"
-
-收敛达成 = 一趟完整 pass 没有产生任何新的 needs_review（不动点）。
-最大 3 趟，超过判定为系统性问题，需 Architect 介入。
-
-详细规则见 .loom/v{N}/ 下的 INTENT_LOOP.md。
+## Intent Loop 与 Quality Engine
+
+每个 Intent 独立运行，直到当前 revision 被证据闭合。
+
+```text
+Select → Compile Expertise → Explore/Direct → Realize
+→ Self-check → Independent Proof → Close/Reflow
+```
+
+## 1. 选择与锁定
+
+```bash
+loom intent next
+loom intent update <id> --status in_progress
+loom activate forge --intent <id>
+```
+
+Context Pack 只注入当前角色和当前 Intent 的相关事实，但不会、也无法清除宿主会话的旧记忆。
+Forge 必须以磁盘事实和当前 Pack 为准，发现冲突时报告。
+
+## 2. Expertise Compiler
+
+Forge 先形成任务级 Expertise Pack：
+
+- 专业问题与任务类型。
+- 卓越判断标准和反模式。
+- 项目事实、硬约束与可变空间。
+- 已实际加载的技能、资料、工具及其用途。
+- Critic 视角与验证方法。
+
+Pack 是临时认知配置，不写成新的长期规范。明显任务可以很短；高质量任务应足以解释为什么
+某个专业手法适合这个项目。
+
+## 3. Quality Arena
+
+完成目标明确且不存在实质质量选择时，走直接路径。
+
+当 `quality_contract` 要求相对提升时：
+
+1. 记录修改前 Baseline。
+2. 产生少量机制不同的候选。
+3. 按完成契约、质量契约、Doctrine 和实际成本比较。
+4. 实现最优候选并观察真实产物。
+5. 不胜过基线就保留原方案或回流契约，不强改。
+
+## 4. Quality Proof
+
+```bash
+loom activate keeper --intent <id>
+loom verify contract <id>
+```
+
+Keeper 独立检查基础四维；有质量契约时增加第五维：
+
+```json
+{
+  "intent_id": "INT-001",
+  "verdict": "passed",
+  "timestamp": "2026-07-28T12:00:00.000Z",
+  "summary": "具体、可定位、可复现的判定摘要",
+  "reproduction_command": "npm test",
+  "dimensions": {
+    "intent_fidelity": {
+      "verdict": "passed",
+      "evidence": "对照 narrative 的用户结果，真实产物保持了目标与非目标"
+    },
+    "philosophy_consistency": {
+      "verdict": "passed",
+      "evidence": "对照引用原则与反模式，关键取舍和例外均有项目依据"
+    },
+    "baseline_compliance": {
+      "verdict": "passed",
+      "evidence": "B1-B5 与项目底线逐项检查，未发现失守"
+    },
+    "acceptance_achievement": {
+      "verdict": "passed",
+      "evidence": "完成契约的可观察行为均已复现"
+    },
+    "quality_achievement": {
+      "verdict": "passed",
+      "evidence": "相对修改前基线，目标信号达到契约阈值且回归保持稳定",
+      "quality_proof_ref": "artifacts/quality-proof.md#INT-001"
+    }
+  }
+}
+```
+
+若 Intent 声明 `continuity_required: true`，Keeper 还必须写入并通过：
+
+```json
+"preservation_achievement": {
+  "verdict": "passed",
+  "evidence": "复现旧状态 → 本轮操作 → 新状态；列出保留的旧值、完成状态或可见行为。"
+}
+```
+
+这不是第二份契约：具体保留规则和操作序列仍写在 `acceptance`。通过快捷命令闭合时，必须显式提供
+`--preservation-evidence "..."`。
+
+存在 `quality_contract` 时强制 `quality_achievement`；只有声明相对提升时才需要
+`quality_proof_ref`。Quality Proof 至少说明基线、主张、候选机制、选择证据、稳定性和代价。
+
+## 5. 判定与回流
+
+| verdict | 动作 |
+|---|---|
+| `passed` | `loom intent done <id>` |
+| `deviated` | 回到真正的问题拥有者，修正后重验 |
+| `blocked` | 标记阻塞并报告缺失条件 |
+| `pending_human` | 只在确需人类感知或授权时使用 |
+
+完成通过但质量未通过时，结果可以保留为可靠完成，但不得声称质量提升；由用户决定继续 Arena、
+降低或修订质量契约，还是接受当前结果。
+
+Intent 语义变化必须递增 revision；任何完成态 Intent 回流也会递增验证 epoch。旧 revision 或旧 epoch 的 passed 记录都不会闭合当前 Intent；修订 Intent 时必须完整分类全部直接和传递下游，已完成下游会一并回流复验。
+
+## 6. Goal 与闭环
+
+把当前 Intent 视为一次 Codex goal 的可闭合单元。goal 只能在“结果、适用时的状态守恒、可复现证据、按需的质量证明”同时成立后完成；
+goal/status 不能替代 Keeper 验证。状态型任务默认保留或合并旧内容，删除和覆盖必须在 acceptance 中显式授权。

package/cli/help/patch.md

@@ -0,0 +1,33 @@
+## Patch 审计工作流
+
+Patch 只处理不改变 Intent 或验收契约的实现修正。`06_CHANGELOG.json` 是唯一权威来源，`06_CHANGELOG.md` 是 CLI 确定性生成的只读投影，不要手工编辑。
+
+```bash
+# 修改并自行运行验证后，准备输入文件
+loom patch record --json-file patch.json
+loom patch list
+loom patch get PATCH-001
+loom patch validate
+```
+
+输入格式：
+
+```json
+{
+  "summary": "修复空输入崩溃",
+  "reason": "解析器遗漏空字符串边界",
+  "affects": ["INT-001"],
+  "files": ["src/parser.js", "test/parser.test.js"],
+  "verification": [
+    { "command": "npm test", "result": "passed" },
+    { "method": "agent-browser screenshot", "result": "passed", "evidence": "浅色和深色背景下均清晰可读" }
+  ]
+}
+```
+
+- `affects` 可省略；提供时每个 ID 必须存在于当前 Intent Map。
+- `files` 必须是安全的项目相对路径。
+- `verification` 每项提供 `command` 或 `method`，可附具体 `evidence`；至少有一个 `passed`。CLI 只记录结果，绝不执行命令。
+- Patch 只能在当前版本全部 Intent 完成后记录；未完成的能力变化必须走 Intent Loop。
+- `id` 和 `timestamp` 由 CLI 分配，输入中不要提供。
+- `loom patch validate` 校验 JSON 全量记录及 Markdown 是否与 JSON 完全一致。

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/proposals.md

@@ -0,0 +1,21 @@
+# Capability Graph Change Proposals
+
+New user requirements, research findings, and implementation discoveries are candidates, not silent changes to the official Capability Graph or current Intent.
+
+```bash
+loom capability proposal submit --json-file ./CGP-NEW-REQUIREMENT.json
+loom capability proposal list
+loom capability proposal get CGP-NEW-REQUIREMENT
+loom capability proposal decide CGP-NEW-REQUIREMENT graph_update --rationale "..."
+loom capability proposal close CGP-NEW-REQUIREMENT --resolution-file ./CGP-NEW-REQUIREMENT-resolution.json
+```
+
+Each proposal records an origin, provenance (source, observation time, concrete evidence), candidate kind, title and why-now. Candidate kinds are `outcome`, `constraint`, `capability`, `risk`, and `evidence`.
+
+Only Architect decides whether it is already covered, needs a Graph update, changes an Intent or acceptance contract, belongs in Minor/Major, or is rejected. A decision still blocks the loop until a structured resolution closes it; an arbitrary path or prose string is not evidence.
+
+The resolution is decision-specific and is checked against the current version after the decision baseline: `graph_update` names changed Graph nodes (which must carry the proposal ID); `intent_change` names changed Intents; `acceptance_change` names Intents whose acceptance artifact changed; `covered` names the already-effective Graph coverage plus a rationale; and `minor`, `major`, or `reject` references a newly written `03_DECISIONS/` artifact naming the proposal. A `constraint` decided as `graph_update` must additionally appear in the formal Graph `constraints` array with its affected node IDs.
+
+For `covered_by`, use both `covered_by: "NODE-ID"` and a `{ "type": "covered_by", "target": "NODE-ID" }` relationship. The target must be a different, currently covered node with a direct route; chained or self-referential coverage is rejected.
+
+Forge and Keeper may submit candidates but cannot use them to expand their active scope.

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 继续
-\`\`\`
+\`\`\`