@haaaiawd/loom 1.2.1 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 1.3.1 — 2026-08-01
+
+### Fixed
+
+- Capability Graph 1.3 新增前置 **Impact Gate**：每个具体 capability 都必须说明影响的用户结果、错判代价、外部知识是否会改变决定与理由。若代价不可逆或外部知识会改变设计/验证，CLI 强制标为 high，并只允许 `external_required`，防止 Agent 通过写成 medium/low 或 `adaptive` 跳过检索。
+- Architect 初判后必须让新的 Agent thread / 子代理通过 `loom activate impact-reviewer` 独立逐项审查；high capability 必须至少占具体 capability 的 30%（向上取整，至少一个），防止整张图谱被大量普通节点稀释。
+- `guide` 与 `doctor` 会将缺失或试图绕过 Impact Gate 的图谱明确指回 Architect，而非让其继续进入 Intent 阶段。
+- Coverage 现在区分“已设计可观察验证入口”与“已完成 Intent 的证据产物已落盘”：规划阶段不再被要求伪造 artifact，完成后缺文件仍是高优先级缺口。
+
+### Compatibility
+
+- Graph 1.0–1.2 保持可读；新建模板使用 1.3。迁移既有图谱时应由 Architect 补 Impact Gate，不由 Forge 静默改写。
+
+## 1.3.0 — 2026-08-01
+
+### Added
+
+- Capability Graph 1.2 引入 `lens_contract` 与 `capability_domains`：Architect 必须审视用户旅程、交互与可访问性、视觉与信息表达、内容与沟通、系统与数据、横切质量与风险；再按项目事实声明 UI/UX、3D 光影、网络安全、心理学、生物学等会改变方案或验证方法的专业领域。两者都必须回链具体 Graph 节点。
+- `loom capability graph`、coverage 与 Forge/Keeper Context Pack 现在暴露与当前 Intent 相关的透镜和专业领域，避免图谱只在磁盘上存在。
+- 新增 `templates/CAPABILITY_GRAPH_EXAMPLE.json`，展示共享 capability、横切 risk/evidence 与 Lens Contract，而非把 Intent 一一镜像成能力节点。
+- `loom atlas` 取代并移除 Preview：CLI 先编译当前版本的架构与决策资料模型，再以 command-assembled Composer Pack 生成必交付的 `loom-atlas.html`。Atlas 固定呈现原则、结构、能力图谱、关键决策与审查入口，不承载项目进度或验证历史。
+- Intent 全部闭合后，`guide` 与 `doctor` 将缺少、过期或结构不完整的 Atlas 视为高优先级交付缺口。
+
+### Compatibility
+
+- 既有 Graph 1.0/1.1 保持可读；新 Graph 1.2 缺失 Lens Contract 或 Capability Domain Contract 时，coverage/doctor 会明确阻断并引导 Architect 补全。既有项目迁移应先走 Capability Graph Proposal，不由 Forge 静默改写。
+- `loom preview` 及 `loom-preview.html` 不再是 LOOM 功能或合格交付物；迁移到 `loom atlas --regen`。
+
+## 1.2.2 — 2026-07-31
+
+### Fixed
+
+- `guide` 只输出下一步命令、Context Pack 提示与完成校验，不再展示文件输入/输出清单；当下一步是角色激活时，由该命令装配 Context Pack。
+- `activate weaver` 直接注入检索方法与哲学维度目录；`activate architect` 在无 Intent 的设计阶段直接注入愿景、当前 Capability Graph、Intent Map 与未闭合 proposal。
+- Capability Graph 未闭合或 proposal 待裁决时，`guide` 重新指向可推进工作的 Architect Context Pack，而不是重复运行只读检查。
+- `loom intent next` 返回开始该 Intent 和获取 Forge Context Pack 的明确后续命令。
+
 ## 1.2.1 — 2026-07-31
 
 ### Fixed

package/README.md

@@ -28,7 +28,7 @@ LOOM 的核心机制：
 | **哲学** | 项目的价值观和工程原则——为什么存在、什么不做、冲突时谁优先。由 Weaver 从真实思想体系织造，不是模板填空 |
 | **Intent** | 一个意图单元——不是"做什么"（任务），是"为什么做"（意图）。每个 Intent 有验收契约，Keeper 据此判定实现是否忠实 |
 | **Intent Map** | 所有 Intent 的依赖图（JSON）。Architect 绘制，定义拓扑序和依赖关系 |
-| **Capability Graph** | 在 Intent 前展开项目问题面、能力缺口、风险和证据；高影响节点必须路由，并回链到 Intent |
+| **Capability Graph** | 先用 Lens Contract 审视用户旅程、交互、视觉、内容、系统与风险，再用 Capability Domains 声明 UI/UX、3D 光影、安全、心理学等真正相关的专业来源；每个 capability 经 Architect 初判与独立子代理的 Impact Gate 审查，high 至少占 30%，不能靠降级影响等级跳过外部获取，最后才展开问题面、能力缺口、风险和证据并回链 Intent |
 | **Expertise Pack** | Forge 通过真实外部检索为当前 Intent 编译的来源化核心信息组；绑定 revision，不成为永久规则 |
 | **Authorial Stance** | 针对单个 Intent 编译的创作命题、选择、拒绝项、媒介语法和验证视角，不是 Persona 扮演 |
 | **Atelier Path** | 可选创作深路径：冻结基线、形成机制不同候选、比较或保留原版，并把证据写入唯一 Atelier Record |
@@ -87,6 +87,9 @@ loom guide --dry-run  # 只读诊断，不写 heartbeat
 guide 检测项目当前在哪个阶段，输出"你在阶段 X，下一步做 Y"。
 Agent 每完成一步都跑 guide 确认下一步。
 如果只是审计或探测，不希望产生任何状态写入，用 `loom guide --dry-run`。
+
+当 `guide` 的下一步是 `loom activate <role>` 时，先运行这条命令：它会把该阶段需要的
+规范与版本化输入编译为 Context Pack。`guide` 只负责导航，不输出待阅读文件清单。
 
 ### AUTO 模式
 
@@ -168,23 +171,20 @@ loom intent update INT-001 --status blocked      # blocked
 loom intent status
 ```
 
-**Loop 结束**：`loom intent status` 显示所有 Intent 为 completed。
+**Loop 结束**：所有 Intent 为 completed，且 `loom atlas validate` 通过当前版本的决策图谱交付门。
 
-### 步骤 6：人类预览
+### 步骤 6：决策图谱交付
 
 ```bash
-loom preview status   # 先检查 preview 是否新鲜
-loom preview          # 新鲜则打开；过期则提示重新生成
-loom preview --regen  # 输出生成提示词，让 Agent 重写 loom-preview.html
+loom atlas build      # 编译当前版本的架构与决策资料模型
+loom atlas --regen    # 输出已装配资料的 Composer Pack，生成 loom-atlas.html
+loom atlas validate   # 校验 Atlas 是否是当前版本合格交付物
+loom atlas            # 打开合格的决策图谱
 ```
 
-preview 是人类总览用的只读投影：哲学、愿景、架构、Intent 进度、验证历史。
-`loom preview` 会用 mtime 检查 `.loom/v{N}` 是否比 `loom-preview.html` 更新：
-- 新鲜：直接打开 `loom-preview.html`
-- 过期：不打开旧投影，提示 `loom preview --regen`
-- 强行打开旧投影：`loom preview --stale`
+Atlas 是当前版本的必交付 H5：它解释哲学、愿景、架构、Capability Graph、专业领域、Intent 契约、验证设计与关键决策，不承载项目进度或验证历史。CLI 为资料建立内容 digest；`loom-atlas.html` 必须绑定该 digest 和五个固定审查章节，才能被打开或视为收尾完成。
 
-Agent 在用户说"看看进度 / 打开 preview / 看全局"时，先跑 `loom preview status`。
+视觉 Agent 可以自由选择风格和叙事节奏，但内容结构与来源回链固定。所有 Intent 完成后，`loom guide` 会先要求 Atlas，不能跳过。
 
 **版本演进三档**：
 
@@ -206,11 +206,11 @@ Agent 在用户说"看看进度 / 打开 preview / 看全局"时，先跑 `loom
 | `loom auto on\|off\|status` | AUTO 模式开关 |
 | `loom activate <role>` | 输出角色激活提示词 |
 | `loom activate <role> --intent <id>` | 输出仅含指定 draft/官方 Intent 的角色上下文 |
-| `loom preview` | 打开新鲜 HTML 预览；过期时提示重新生成 |
-| `loom preview status` | 检查 `loom-preview.html` 是否存在、是否新鲜 |
-| `loom preview --regen` | 输出提示词，让 Agent 重写 HTML 预览 |
-| `loom preview --stale` | 强行打开过期预览 |
-| `loom help <topic>` | 分层指南（含 workflow、concepts、loop、capability、atelier、version、patch、doctor、preview） |
+| `loom atlas build` | 编译当前版本的 Atlas Model |
+| `loom atlas --regen` | 输出 command-assembled Composer Pack，生成 `loom-atlas.html` |
+| `loom atlas status\|validate` | 检查资料与 HTML 是否新鲜、完整且可交付 |
+| `loom atlas` | 打开通过校验的决策图谱 |
+| `loom help <topic>` | 分层指南（含 workflow、concepts、loop、capability、atelier、version、patch、doctor、atlas） |
 | `loom version list` | 列出所有版本（* 标记当前） |
 | `loom version new` | 创建新版本 + 自动切换（Major 升级） |
 | `loom version use <v>` | 切换当前版本 |
@@ -294,7 +294,8 @@ LOOM/
     ├── CAPABILITY_BRIEF_TEMPLATE.md   Capability Brief 起点
     ├── ASSET_LIBRARY_MANIFEST_TEMPLATE.json Asset Library 起点
     ├── EXPERTISE_PACK_TEMPLATE.json   外部能力获取记录起点
-    └── ATELIER_RECORD_TEMPLATE.json   Atelier Record 起点
+    ├── ATELIER_RECORD_TEMPLATE.json   Atelier Record 起点
+    └── ATLAS_TEMPLATE.html             决策图谱 H5 起点
 ```
 
 ### 文档导航
@@ -313,9 +314,10 @@ LOOM/
 | Keeper 做什么 | `roles/keeper.md` |
 | 哲学文档长什么样 | `templates/PHILOSOPHY_TEMPLATE.md` |
 | 愿景文档长什么样 | `templates/VISION_TEMPLATE.md` |
-| Capability Graph 与 Brief 长什么样 | `cli/help/capability.md`、`templates/CAPABILITY_GRAPH_TEMPLATE.json` |
+| Capability Graph、Lens Contract 与 Brief 长什么样 | `cli/help/capability.md`、`templates/CAPABILITY_GRAPH_TEMPLATE.json`、`templates/CAPABILITY_GRAPH_EXAMPLE.json` |
 | 为什么必须外部检索、Expertise Pack 怎么闭合 | `cli/help/expertise.md`、`EXTERNAL_ACQUISITION_DESIGN.md` |
 | Author 与 Atelier 怎么工作 | `cli/help/atelier.md`、`dimensions/AUTHORSHIP.md` |
+| 决策图谱如何生成、怎样验收 | `cli/help/atlas.md`、`templates/ATLAS_TEMPLATE.html` |
 | Intent Map 长什么样 | `templates/INTENT_MAP_TEMPLATE.json` |
 | 怎么搜索高质量参考 | `dimensions/SEARCH_METHODOLOGY.md` |
 
@@ -433,7 +435,7 @@ Agent 通过 **CLI 访问** JSON，不直接读文件——省 token、更高效
    → 基于哲学写愿景 → 每个意图带意图叙事 → 识别需要的哲学维度
 
 3. Architect 先展开 Capability Graph，再设计系统
-   → 基于愿景检查问题面、能力缺口、风险与证据 → 路由高影响节点 → 绘制 Intent Map → 定义验证契约
+   → 基于愿景检查问题面、能力缺口、风险与证据 → Impact Gate 经独立子代理复审 → 路由高影响节点并外部获取 → 绘制 Intent Map → 定义验证契约
 
 4. LOOM Quality Engine
    → Forge 编译 Expertise Pack → 按需编译 Authorial Stance / 进入 Atelier
@@ -446,7 +448,7 @@ Agent 通过 **CLI 访问** JSON，不直接读文件——省 token、更高效
 ## 当前状态
 
 - [x] `meta/` 元规范（4 个文件）
-- [x] `roles/` 角色原型（4 个角色）
+- [x] `roles/` 角色契约（6 个角色，含独立 Impact Reviewer）
 - [x] `templates/` 起点骨架
 - [x] `README.md` 系统总览
 - [x] `dimensions/SEARCH_METHODOLOGY.md` 检索方法论
@@ -456,4 +458,4 @@ Agent 通过 **CLI 访问** JSON，不直接读文件——省 token、更高效
 
 ---
 
-> **LOOM 的信条**：编排而非控制。给 Agent 价值观和边界，让它在边界内自主发挥。底线守住不会崩，哲学填充边界内的内容，loop 确保实现忠实于意图。
+> **LOOM 的信条**：编排而非控制。给 Agent 价值观和边界，让它在边界内自主发挥。底线守住不会崩，哲学填充边界内的内容，loop 确保实现忠实于意图。

package/cli/bin/loom.js

@@ -20,7 +20,7 @@ import { doctor, contextSummary, traceIntent, reverseDep, reverseRef } from '../
 import { getHelpTopic, listHelpTopics } from '../src/help.js';
 import { guideProject } from '../src/guide.js';
 import { isAutoOn, autoOn, autoOff, autoStatus, getAutoMode } from '../src/auto.js';
-import { generatePreviewPrompt, getPreviewStatus } from '../src/preview.js';
+import { generateAtlasComposerPack, getAtlasStatus, validateAtlas, writeAtlasModel } from '../src/atlas.js';
 import { getPatch, listPatches, recordPatch, validatePatches } from '../src/patch.js';
 import { addIntentDraft, finalizeIntentDraft, getIntentDraft, reviseIntentDraft } from '../src/intent-draft.js';
 import { resolveIntentRef } from '../src/shared/intent-ref.js';
@@ -274,9 +274,19 @@ try {
           }));
           break;
         }
-        case 'next':
-          output(getNextIntent(versionDir) ?? '没有可执行的 Intent');
-          break;
+        case 'next':
+          {
+            const next = getNextIntent(versionDir);
+            output(next ? {
+              ...next,
+              suggested_flow: {
+                start: `loom intent update ${next.id} --status in_progress`,
+                forge_context: `loom activate forge --intent ${next.id}`,
+                note: '先显式开始 Intent，再由 activate 命令装配该 Intent 的叙事、契约、图谱路由与专业输入。',
+              },
+            } : '没有可执行的 Intent');
+          }
+          break;
         case 'status': {
           const s = getStatus(versionDir);
           const fmt = (ids) => ids.map((id) => s.titles[id] ? `${id}(${s.titles[id]})` : id).join(', ') || '-';
@@ -425,7 +435,7 @@ try {
 
     case 'activate': {
       const role = sub;
-      if (!role) die('用法: loom activate <role>\n角色: weaver | visionary | architect | forge | keeper');
+      if (!role) die('用法: loom activate <role>\n角色: weaver | visionary | architect | impact-reviewer | forge | keeper');
       // weaver 不需要 versionDir（项目还没初始化时也能激活）
       let versionDir = null;
       if (role !== 'weaver') {
@@ -518,7 +528,7 @@ try {
               const icon = issue.severity === 'high' ? '⚠' : '·';
               console.log(`  ${icon} [${issue.severity}] ${issue.msg}`);
             }
-            console.log('\n参见 meta/PHILOSOPHY_WEAVER.md + dimensions/SEARCH_METHODOLOGY.md。');
+            console.log('\n下一步: 运行 loom activate weaver；命令会重新输出哲学阶段所需的 Context Pack。');
             exit(1);
           }
           break;
@@ -738,7 +748,7 @@ try {
             console.log(`    → 修复: ${issue.fix_hint}`);
           }
         }
-        console.log(`\n参见 meta/PHILOSOPHY_WEAVER.md + dimensions/SEARCH_METHODOLOGY.md。`);
+        console.log('\n下一步: 运行 loom guide；它会根据当前状态给出可执行动作与所需 Context Pack。');
       }
       break;
     }
@@ -788,17 +798,12 @@ try {
       };
       console.log(`模式: ${modeDesc[result.auto_mode] || result.auto_mode}`);
       console.log(`\n${result.message}`);
-      console.log(`\n下一步: ${result.next_action}`);
-      console.log(`  → ${result.next_command}`);
-      if (result.inputs && result.inputs.length > 0) {
-        console.log(`\n需要读取:`);
-        for (const f of result.inputs) console.log(`  - ${f}`);
-      }
-      if (result.outputs && result.outputs.length > 0) {
-        console.log(`\n需要产出:`);
-        for (const f of result.outputs) console.log(`  - ${f}`);
-      }
-      if (result.verify_command) {
+      console.log(`\n下一步: ${result.next_action}`);
+      console.log(`  → ${result.next_command}`);
+      if (result.input_delivery === 'context_pack') {
+        console.log('\n上下文: 直接运行这条命令；它会输出当前阶段所需的 Context Pack。');
+      }
+      if (result.verify_command) {
         console.log(`\n完成后校验: ${result.verify_command}`);
       }
       if (result.auto_mode === 'manual' && result.stage_num > 0 && result.stage_num < 6) {
@@ -864,62 +869,63 @@ try {
       break;
     }
 
-    case 'preview': {
-      const previewFile = join(cwd(), 'loom-preview.html');
-      if (argv.includes('--help') || argv.includes('-h')) {
-        console.log(`用法:
-  loom preview              打开新鲜 preview；过期时提示重新生成
-  loom preview --regen      输出生成提示词，让 Agent 重写 loom-preview.html
-  loom preview status       检查 preview 是否存在、是否新鲜
-  loom preview --stale      强行打开过期 preview
-  loom preview --help       显示本帮助`);
-        break;
-      }
-      const status = getPreviewStatus(cwd());
-      const hasPreview = status.exists;
-      const regenOnly = argv.includes('--regen') || argv.includes('-r');
-      const openStale = argv.includes('--stale');
-
-      if (sub === 'status') {
-        output(status);
-        break;
-      }
-
-      // 已有 HTML 且没指定 --regen：直接打开浏览器
-      if (hasPreview && !regenOnly) {
-        if (!status.fresh && !openStale) {
-          console.log('preview 已过期：.loom 源文件比 loom-preview.html 更新。');
-          console.log(`  preview: ${status.preview_mtime || '未知'}`);
-          console.log(`  最新源: ${status.source_latest_mtime || '未知'} ${status.latest_source_file ? `(${status.latest_source_file})` : ''}`);
-          console.log('\n下一步: loom preview --regen');
-          console.log('强行打开旧 preview: loom preview --stale');
-          break;
-        }
-        const { spawn } = await import('node:child_process');
-        const target = previewFile.replace(/\\/g, '/');
-        if (process.platform === 'win32') {
-          spawn('cmd', ['/c', 'start', target], { detached: true, stdio: 'ignore' }).unref();
+    case 'atlas': {
+      const versionDir = findVersionDir();
+      const projectDir = cwd();
+      if (argv.includes('--help') || argv.includes('-h')) {
+        console.log(`用法:
+  loom atlas build          编译当前版本的 Atlas Model
+  loom atlas --regen        输出 command-assembled Composer Pack，让 Agent 生成 loom-atlas.html
+  loom atlas status         检查 loom-atlas.html 与 Model 是否齐全、新鲜
+  loom atlas validate       校验 Atlas 是否为当前版本的必交付物
+  loom atlas                打开通过校验的 loom-atlas.html
+  loom atlas --help         显示本帮助`);
+        break;
+      }
+      if (sub === 'status') {
+        output(getAtlasStatus(projectDir, versionDir));
+        break;
+      }
+      if (sub === 'build') {
+        output(writeAtlasModel(versionDir));
+        break;
+      }
+      if (sub === 'validate') {
+        const result = validateAtlas(projectDir, versionDir);
+        if (!result.valid) die(`Atlas 校验失败:\n  - ${result.errors.join('\n  - ')}`);
+        output(result);
+        break;
+      }
+      if (argv.includes('--regen') || argv.includes('-r')) {
+        writeAtlasModel(versionDir);
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        console.log('To Agent: 以下 Composer Pack 已直接装配当前架构与决策资料；生成项目根目录的 loom-atlas.html。');
+        console.log('To Human: 把以下内容交给负责视觉实现的 Agent。');
+        console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+        console.log(generateAtlasComposerPack(versionDir));
+        break;
+      }
+      const validation = validateAtlas(projectDir, versionDir);
+      if (!validation.valid) {
+        console.log('Atlas 尚未成为当前版本的合格交付物：');
+        validation.errors.forEach((error) => console.log(`  - ${error}`));
+        console.log('\n下一步: loom atlas --regen');
+        break;
+      }
+      {
+        const { spawn } = await import('node:child_process');
+        const target = validation.atlas_path.replace(/\\/g, '/');
+        if (process.platform === 'win32') {
+          spawn('cmd', ['/c', 'start', target], { detached: true, stdio: 'ignore' }).unref();
         } else if (process.platform === 'darwin') {
           spawn('open', [target], { detached: true, stdio: 'ignore' }).unref();
-        } else {
-          spawn('xdg-open', [target], { detached: true, stdio: 'ignore' }).unref();
-        }
-        console.log(`已打开浏览器: ${previewFile}`);
-        console.log(status.fresh ? `重新生成: loom preview --regen` : `已打开旧 preview。重新生成: loom preview --regen`);
-        break;
-      }
-
-      // 没有 HTML 或指定 --regen：输出提示词让 AI 生成
-      const prompt = generatePreviewPrompt();
-      console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-      console.log('To Agent: 按以下提示词读 .loom/ 文件并生成 loom-preview.html');
-      console.log('  生成完成后再次运行 loom preview 会自动打开浏览器');
-      console.log('To Human: 把以下内容给你的 AI agent');
-      console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-      console.log('');
-      console.log(prompt);
-      break;
-    }
+        } else {
+          spawn('xdg-open', [target], { detached: true, stdio: 'ignore' }).unref();
+        }
+        console.log(`已打开决策图谱: ${validation.atlas_path}`);
+      }
+      break;
+    }
 
     case '--help':
     case '-h':
@@ -992,10 +998,11 @@ To Human:
 
   loom doctor                   项目健康检查（一致性+孤儿引用+循环依赖+僵尸）
   loom context                  上下文摘要（进度+下一步+待验证+风险）
-  loom preview                  打开新鲜 HTML；过期则提示重新生成
-  loom preview status           检查 preview 是否存在、是否新鲜
-  loom preview --regen          强制重新输出提示词（让 AI 重新生成 HTML）
-  loom preview --stale          强行打开过期 preview
+  loom atlas build              编译当前版本的决策图谱资料模型
+  loom atlas --regen            输出已装配资料的 Composer Pack，生成 loom-atlas.html
+  loom atlas status             检查决策图谱资料与 HTML 是否新鲜
+  loom atlas validate           校验决策图谱是否为当前版本合格交付物
+  loom atlas                    打开通过校验的 loom-atlas.html
   loom help <topic>             分层指南（含 patch 工作流）
 
   loom philosophy get <anchor>  按锚点加载哲学章节

package/cli/help/atlas.md

@@ -0,0 +1,48 @@
+## 决策图谱 Atlas
+
+Atlas 是当前版本的必交付 H5：它把 Doctrine、Vision、Architecture、Capability Graph、Capability Domains、Intent 契约、验证设计和 ADR 讲成可审查的结构。它不是项目进度页。
+
+```bash
+loom atlas build
+loom atlas --regen
+loom atlas validate
+loom atlas
+```
+
+## 固定内容，开放风格
+
+`loom atlas --regen` 会直接装配 Atlas Model 与 Composer Pack。视觉 Agent 可以自主决定视觉语言、字体、排版、图形和转场，但不得改动以下内容结构：
+
+1. `#atlas-origin`：原则、北极星和非目标。
+2. `#atlas-structure`：愿景、架构边界与 Intent 结构。
+3. `#atlas-capabilities`：Outcome / Concern / Capability、Lens Contract 与 Capability Domains。
+4. `#atlas-decisions`：关键取舍与决策记录。
+5. `#atlas-review`：结构性缺口、未决问题与每项的 source refs。
+
+页面必须同时提供“放映”和“审查地图”读法。放映帮助普通人逐章理解；审查地图让人从目标、能力、专业领域、Intent 与验证设计之间追溯关系。不要展示看板、完成百分比、Intent 状态、燃尽图、验证轮次或 Patch 时间线。
+
+## 图形不是装饰
+
+Atlas 应把资料变成可审查的图，而不是把文字塞进有颜色的卡片。每章只用一张回答明确问题的 SVG / 图形：原则与非目标的张力、架构层与 Intent 依赖、能力链、ADR 分叉、或结构断线。节点、标签、连线和 source refs 必须来自 Atlas Model；不确定的地方明确标为待确认，不得用编造的数据填满画面。
+
+审查地图中的节点必须可点击和键盘访问，选中后在同屏检查台说明其作用、关联对象和来源。每个 SVG 都要有可读描述，不能只靠颜色表达含义；动效只帮助关系出现、章节切换和节点选中，并在减少动态效果时保持可读。
+
+## 视觉质量循环
+
+Composer 先选择一个贯穿全页的视觉母题，再完成一个方向，不交付多份半成品，也不把 Atlas 做成通用 SaaS 看板。默认方向是可翻阅的“决策日报”：暖米色纸张、墨黑正文、砖红强调、报纸式标题层级、细线分栏，以及主报道区与侧栏图表/边注的非对称排布。它借用日报的阅读逻辑，不复制任何真实报纸的报头、标识或报道内容。
+
+五章的构图必须各自回答问题而非重复卡片：起点建立张力，结构解释边界，能力展示网络，决策展示分叉，审查暴露缺口。
+
+Atlas 的目标是“可翻阅的图文决策日报”，不是稀疏展览海报：每页应同时有关键结论、三到五条由 Model 提炼的事实或取舍、有标签的主图、一到两条短读图/边注和来源入口。桌面优先使用主报道区加侧栏图表/边注；窄屏按标题、事实栏、图表、读图注、来源重排，页面本身可纵向阅读，切章控件始终可达。信息密度来自结构化事实与图形，而不是缩小字体或贴整段 Markdown。
+
+交付前须在 390px 触屏宽度和 1440px 桌面宽度检查：切章、滑动、键盘、章节定位、放映/地图切换、节点选择、来源显示和减少动态效果。无法实际检查时，必须保留未验证项，不能假装已经通过。首屏没有信息图形、只有标题加孤立图形、长文堆叠、五章同构、图形只有装饰、关键内容只能 hover 读取、手机要双指缩放、对比度不足或动效妨碍审查，均应返工。
+
+## 交付门
+
+`loom atlas build` 写入 `.loom/vN/11_DECISION_ATLAS/atlas-model.json`，其中包含当前资料的 source digest。生成的项目根 `loom-atlas.html` 必须在 head 内带同一个：
+
+```html
+<meta name="loom-atlas-source-digest" content="...">
+```
+
+`loom atlas validate` 校验资料模型、HTML、digest 与五个章节。全部 Intent 闭合后，缺少或过期的 Atlas 会让 `loom guide` 停在 `need_decision_atlas`；它不是可选美化。

package/cli/help/capability.md

@@ -16,6 +16,50 @@ loom capability compile <intent-id>
 Visionary 给出 outcome、角色、非目标与项目事实。Architect 用项目类型相符的透镜检查用户旅程、
 体验、系统、资产、横切质量和未知；每个透镜必须被展开、覆盖或明确排除。
 
+## Lens Contract：先检查，再命名能力
+
+新建 Graph 必须先写 `lens_contract`。它要求 Architect 对用户旅程、交互与可访问性、视觉与信息表达、内容与沟通、系统与数据、横切质量与风险逐项做出判断：
+
+- 适用：用 `node_refs` 连到具体的 outcome、concern、capability、risk 或 evidence；
+- 不适用：写明基于项目事实的理由；
+- 需要额外维度：可以增补自定义透镜，但不能删掉六项必审方向。
+
+透镜不是能力节点。`CAP-UI`、`CAP-UX`、`CAP-视觉优化` 这类标题没有用户结果，不能代替能力边界。应写成可观察、可取舍的结果，例如“让错误状态与恢复入口保持可理解”或“让长报告中的证据层级能在窄屏扫读”。一个 capability 可以被多个透镜引用，也可以支持多个 outcome；这正是 Graph 不应退化为 Intent 镜像的原因。
+
+## Capability Domains：专业能力从哪里来
+
+`capability_domains` 记录的不是产品功能，而是会改变设计、实现或验证方法的专业领域。UI/UX、3D 建模、光影与材质、网络安全、心理学、生物学等都可以是 domain；是否进入图谱只看一个问题：**若不了解这个领域，当前方案或判断会不会实质不同？**
+
+每个 domain 必须写清专业问题、为什么现在需要，并用 `node_refs` 连接具体 capability；每个 capability 也用 `domain_refs` 回链领域。这样：
+
+- `DOMAIN-INTERACTION-DESIGN` 可以支撑“状态与恢复可理解”；
+- `DOMAIN-3D-LIGHTING` 可以支撑“光影与材质传达空间尺度”；
+- `DOMAIN-WEB-SECURITY` 可以支撑“敏感操作具备可恢复的授权边界”；
+- `DOMAIN-BEHAVIORAL-PSYCHOLOGY` 可以支撑“敏感沟通不以操控性暗示替代用户选择”。
+
+领域不是“我们已经拥有专家”的声明，也不是固定分类表。它只让 Forge 知道：这项具体能力需要什么专业问题、是否应进入外部获取，以及 Keeper 应按什么角度反证。
+
+完整、有共享关系的最小例子见 `templates/CAPABILITY_GRAPH_EXAMPLE.json`。它不是可以照抄的产品方案，而是展示如何让 outcome、concern、capability、risk、evidence 和 capability domain 交叉连接。
+
+## Impact Gate：先判断代价，后写 Intent
+
+在 Graph schema 1.3 中，每个具体 capability 都必须有 `impact_assessment`。它不是形式化打分，而是先把容易被偷懒跳过的问题说清：它影响哪个用户结果？省略或误判的代价是什么？外部知识会不会改变方案或验证？理由是什么？Architect 完成初判后，必须开一个新的 Agent thread / 子代理运行 `loom activate impact-reviewer`，由它将逐项结论写入根级 `impact_review`；同一上下文里的自我复述不算独立审查。
+
+若代价为 `hard_to_reverse`，或外部知识会改变决定，CLI 会要求 `impact: high`；这种节点只允许 `external_required`（或省略该字段、采用默认值）。不能把关键能力标为 medium/low，或写 `adaptive`，来绕过外部获取。并且 `high` 必须至少占具体 capability 的 **30%**（向上取整，至少一个）；分母不包含 outcome、risk、evidence 等节点，避免靠增加陪跑节点稀释比例。
+
+```json
+{
+  "impact": "high",
+  "impact_assessment": {
+    "affected_user_result": "用户能以键盘和文字理解时间带，而非只能依赖颜色与拖拽",
+    "failure_cost": "material",
+    "external_knowledge_changes_decision": true,
+    "rationale": "可访问数据表达会改变交互、备用文本和验收方式；普通图表经验不足以替代。"
+  },
+  "acquisition_mode": "external_required"
+}
+```
+
 高影响节点不能停在 `open`。它必须继续展开、生成 Capability Brief、编译为 Intent，或带理由地
 延后/排除。`loom capability frontier` 显示尚未路由的高影响节点；`loom capability coverage` 检查
 图谱与 Intent 的双向追溯。
@@ -24,7 +68,8 @@ Visionary 给出 outcome、角色、非目标与项目事实。Architect 用项
 `verification` 对象必须包含 `method`、`target`、`procedure`、`pass_criteria` 和 `artifact`，并以
 `intent_refs` 回链负责产出该证据的 Intent。`target` 写结果真正要被看见、接收或使用的位置，例如目标
 宿主的渲染面、用户拿到的导出文件、外部系统的接收端或人工验收现场。不要把“HTTP 200”“URL 可访问”或
-“本地生成了文件”当作用户已得到结果。
+“本地生成了文件”当作用户已得到结果。设计阶段可以先声明计划中的本地 `artifact` 路径；只有负责它的
+Intent completed 后，CLI 才要求该证据文件实际存在，避免用空占位文件伪造验证。
 
 不新增媒体、平台或版权专用节点类型：目标宿主与交付链路用 `concern` / `capability` 表达，许可、来源、
 隐私或平台限制用 `risk` 和 `constrains` 关系表达；只有需要项目化判断时才为相关节点创建 Brief，并在其
@@ -68,6 +113,6 @@ Intent 时会获得同一份输入；发现新依赖、风险或能力缺口时
 扩展实现。Keeper 以图谱回链检查高影响问题是否真的被兑现。
 
 Capability 节点可选声明 `acquisition_mode: adaptive | external_required | project_only`。
-`project_only` 必须附 `acquisition_rationale`。未声明时，高影响 capability 自动提升为
-`external_required`。Graph 只保存获取必要性，不保存网站、Skill 名称或
+schema 1.3 的 high capability 只允许 `external_required` 或省略（默认即为 `external_required`）；
+较低影响的 `project_only` 必须附 `acquisition_rationale`。Graph 只保存获取必要性，不保存网站、Skill 名称或
 搜索词；Forge 在本轮 Expertise Pack 中按项目信号派生查询并记录真实来源。

package/cli/help/concepts.md

@@ -37,6 +37,8 @@ Capability Graph 位于 Vision 和 Intent Map 之间。它将项目初衷展开
 
 它不是执行 DAG，也不替代 Intent Map：Graph 保留未知、研究与分叉；Intent 只保留边界明确、能独立验收的承诺。高影响节点必须有明确路由（继续展开、Brief、Intent、延后或排除），每个 Intent 必须回链至少一个图谱节点。只有需要专业方法、调研或即将进入当前 Intent 的节点才创建短小的项目化 Capability Brief。
 
+在 schema 1.3 中，每个具体 capability 先经过 **Impact Gate**：Architect 说明它影响的用户结果、错判代价、外部知识是否会改变决定与理由；新的 Agent thread / 子代理通过 `loom activate impact-reviewer` 独立复审并写入 `impact_review`。若错判不可逆或外部知识会改变决定，节点必须是 high、必须外部获取；high 至少占 capability 的 30%（向上取整，至少一个），不能用大量普通节点稀释。
+
 ## System Boundary
 
 LOOM 不假装能够清除宿主 Agent 的既有记忆。`loom activate` 生成有序 Context Pack，

package/cli/help/doctor.md

@@ -12,7 +12,12 @@ loom context
 | 类型 | 严重度 | 含义 |
 |---|---|---|
 | `cycle` | fatal | Intent DAG 有环 |
+| `project_document_missing` | high | Vision、Architecture、Verification 或哲学三件套缺失 |
+| `project_document_template` | high | 必需文档仍是初始化模板，尚未成为项目判断 |
 | `orphan_philosophy_ref` | high | Doctrine 引用不存在 |
+| `orphan_philosophy_anchor` | high | Doctrine 文件存在，但 Intent 指向的章节锚点不存在 |
+| `intent_narrative_invalid` | high | Intent 的 narrative_ref 无法解析到当前 Vision |
+| `intent_contract_invalid` | high | Intent 的 acceptance 或其 Verification 引用无法解析 |
 | `orphan_dependency` | high | Intent 依赖不存在 |
 | `completed_no_record` | high | completed 没有验证记录 |
 | `completed_verification_not_passed` | high | 最新记录不能闭合当前 revision |
@@ -21,6 +26,7 @@ loom context
 | `preservation_dimension_missing` | high | 启用了状态守恒门，但缺少通过的守恒维度 |
 | `inspiration_source` | high/medium | Doctrine 证据不可追溯、缺理由或仍是模板 |
 | `verification_method_drift` | high | 声明的验证方式与复现证据不一致 |
+| `capability_impact_gate_missing` | high | Capability Graph 未完成独立 Impact Review，或试图绕过 high / 外部获取门禁 |
 | `in_progress_no_record` | medium | 工作可能中断 |
 | `zombie` | medium | Intent 长时间无活动 |
 
@@ -60,8 +66,9 @@ loom verify pass <id> --summary "<证据>" --quality-proof "<ref>" \
 
 - Forge 中断：检查真实产物后继续，或把 Intent 回退到 `pending`。
 - Intent Map 损坏：从 Git 恢复，再运行 `loom intent validate`。
+- 哲学锚点失效：运行 `loom philosophy get <file#anchor>`，修正 Intent 引用到实际存在的章节，而不是只确认 Markdown 文件还在。
 - 验证记录丢失：重新独立验证，不从旧会话记忆补写。
-- Preview 过期：`loom preview status` 后使用 `loom preview --regen`。
+- 所有 Intent 已完成但 Atlas 缺失或过期：运行 `loom atlas --regen` 生成 `loom-atlas.html`，再运行 `loom atlas validate`。
 
 追溯入口：
 

package/cli/help/expertise.md

@@ -15,19 +15,20 @@ loom activate forge --intent <intent-id>
 ## 什么时候强制
 
 - capability 显式声明 `acquisition_mode: external_required`；
-- 或高影响 capability 没有显式声明其他模式。
+- 或高影响 capability 没有显式声明模式（默认即为 `external_required`）。
 
-中低影响任务默认为 `adaptive`。高影响任务只有在 Architect 明确写 `adaptive` 时才按证据
-决定是否检索；仅依赖未公开内部协议、外部知识不会改变做法的机械任务可以用 `project_only`，
-但必须写 `acquisition_rationale`。
+Graph schema 1.3 中，高影响 capability 不允许 `adaptive` 或 `project_only`：它必须实际检索。
+中低影响任务默认为 `adaptive`；仅依赖未公开内部协议、外部知识不会改变做法的机械任务可以用
+`project_only`，但必须写 `acquisition_rationale`。若外部知识仍可能改变方案，应回流 Impact Gate 上调，
+而不是把检索省掉。
 
 ## Search Plan
 
 Forge 根据 capability question、Capability Brief、Intent narrative、质量契约、creative
-scope、媒介约束和基线缺口派生查询。关键词是运行时证据，不写回 Graph。
+scope、媒介约束和基线缺口派生查询。每个 `external_required` capability 都是一项主动探索：先写清它需要回答的专业决定，再记录哪一条来源会让设计、实现或验证路径不同。关键词是运行时证据，不写回 Graph。
 
 必须实际使用 Skill registry、网络、官方文档或研究资料。模型自行生成的原则、没有打开的
-搜索摘要和只看标题的结果都不能登记为来源。每个计划必须写停止条件，避免无边界浏览。
+搜索摘要和只看标题的结果都不能登记为来源。首个来源如果只是通用建议、无法改变具体决定或与另一来源冲突，继续探索或回流，不得把它凑成 Capsule。每个计划必须写停止条件，避免无边界浏览。
 
 ## Capability Capsule
 

package/cli/help/workflow.md

@@ -9,6 +9,9 @@ loom context
 
 只读探测使用 `loom guide --dry-run`。
 
+若 `guide` 指向 `loom activate <role>`，直接运行该命令。它会输出已经装配的 Context Pack；
+`guide` 只负责给出当前动作，不要求 Agent 逐个寻找文件。
+
 ## 1. Doctrine — Weaver
 
 ```bash
@@ -36,7 +39,9 @@ loom capability frontier
 loom capability coverage
 ```
 
-在写 Intent Map 前，Architect 先把愿景展开为项目问题面、能力缺口、风险与证据。图谱不是待办列表：高影响节点必须继续展开、形成项目化 Capability Brief、编译为 Intent，或带理由地延后/排除。每个 Intent 必须回链图谱；只有边界清楚且可独立验证的结果才进入 Intent Map。
+在写 Intent Map 前，Architect 先完成 Lens Contract：对用户旅程、交互与可访问性、视觉与信息表达、内容与沟通、系统与数据、横切质量与风险逐项判断，并将适用项连接到具体图谱节点。随后才把愿景展开为项目问题面、能力缺口、风险与证据。图谱不是待办列表：高影响节点必须继续展开、形成项目化 Capability Brief、编译为 Intent，或带理由地延后/排除。每个 Intent 必须回链图谱；只有边界清楚且可独立验证的结果才进入 Intent Map。
+
+在创建 Intent Map 前还要通过 Impact Gate：Architect 为每个具体 capability 写影响判断；随后在**新的 Agent thread / 子代理**中运行 `loom activate impact-reviewer`，逐项复审 high/medium/low 和外部获取必要性，并写回 `impact_review`。高影响 capability 至少占全部具体 capability 的 30%（向上取整，至少一个）；通过 `loom capability coverage` 后才能进入 Contract。
 
 ## 4. Contract — Architect
 
@@ -100,7 +105,7 @@ loom intent done <id>
 - 证据不足 → Keeper 补证或 `pending_human`
 
 连续三次 `deviated` 自动升级为 `blocked`。所有当前 revision 和当前验证 epoch 的 Intent 都有最新 passed
-记录，且没有 `needs_review`、`loom doctor` 没有 fatal/high 风险时，本轮收敛。
+记录，且没有 `needs_review`、`loom doctor` 没有 fatal/high 风险、`loom atlas validate` 通过当前版本的决策图谱交付门时，本轮收敛。
 
 ## 7. 演进