@haaaiawd/loom 0.1.0 → 0.8.0

package/README.md

@@ -57,12 +57,14 @@ Keeper 验证（四维度：意图忠实度 / 哲学一致性 / 底线合规 /
 
 ### 步骤 0：诊断当前阶段
 
-```bash
-loom guide
-```
-
-guide 检测项目当前在哪个阶段，输出"你在阶段 X，下一步做 Y"。
-Agent 每完成一步都跑 guide 确认下一步。
+```bash
+loom guide
+loom guide --dry-run  # 只读诊断，不写 heartbeat
+```
+
+guide 检测项目当前在哪个阶段，输出"你在阶段 X，下一步做 Y"。
+Agent 每完成一步都跑 guide 确认下一步。
+如果只是审计或探测，不希望产生任何状态写入，用 `loom guide --dry-run`。
 
 ### AUTO 模式
 
@@ -145,24 +147,34 @@ loom intent status
 
 ### 步骤 6：人类预览
 
-```bash
-loom preview
-```
-
-输出提示词，Agent 按提示词读 `.loom/` 文件、拆解信息、生成 HTML 可视化预览。
-人类用浏览器打开 `loom-preview.html` 看全局——哲学、愿景、架构、Intent 进度、验证历史。
-这是只读投影，修改请编辑源文件后重新生成。
+```bash
+loom preview status   # 先检查 preview 是否新鲜
+loom preview          # 新鲜则打开；过期则提示重新生成
+loom preview --regen  # 输出生成提示词，让 Agent 重写 loom-preview.html
+```
+
+preview 是人类总览用的只读投影：哲学、愿景、架构、Intent 进度、验证历史。
+`loom preview` 会用 mtime 检查 `.loom/v{N}` 是否比 `loom-preview.html` 更新：
+- 新鲜：直接打开 `loom-preview.html`
+- 过期：不打开旧投影，提示 `loom preview --regen`
+- 强行打开旧投影：`loom preview --stale`
+
+Agent 在用户说"看看进度 / 打开 preview / 看全局"时，先跑 `loom preview status`。
 
 **CLI 命令一览**：
 
 | 命令 | 用途 |
 |---|---|
-| `loom init` | 初始化项目 |
-| `loom guide` | 诊断当前阶段，输出下一步引导 |
-| `loom auto on\|off\|status` | AUTO 模式开关 |
-| `loom activate <role>` | 输出角色激活提示词 |
-| `loom preview` | 输出提示词，AI 生成 HTML 可视化预览 |
-| `loom help <topic>` | 分层指南（workflow\|concepts\|loop\|version\|doctor） |
+| `loom init` | 初始化项目 |
+| `loom guide` | 诊断当前阶段，输出下一步引导 |
+| `loom guide --dry-run` | 只读诊断当前阶段，不写 heartbeat |
+| `loom auto on\|off\|status` | AUTO 模式开关 |
+| `loom activate <role>` | 输出角色激活提示词 |
+| `loom preview` | 打开新鲜 HTML 预览；过期时提示重新生成 |
+| `loom preview status` | 检查 `loom-preview.html` 是否存在、是否新鲜 |
+| `loom preview --regen` | 输出提示词，让 Agent 重写 HTML 预览 |
+| `loom preview --stale` | 强行打开过期预览 |
+| `loom help <topic>` | 分层指南（workflow\|concepts\|loop\|version\|doctor\|preview） |
 | `loom version list` | 列出所有版本（* 标记当前） |
 | `loom version new` | 创建新版本 + 自动切换（Major 升级） |
 | `loom version use <v>` | 切换当前版本 |

package/cli/bin/loom.js

@@ -1,60 +1,37 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 // loom — LOOM 框架的 CLI 传感器层
 // Agent 通过这个 CLI 访问 Intent Map / 哲学 / 验证记录，不直接读文件。
 
 import { argv, cwd, exit } from 'node:process';
-import { resolve, join } from 'node:path';
+import { resolve, join, dirname } from 'node:path';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { findLoomRoot, findVersionDir, readCurrentPointer } from '../src/shared/paths.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 
 import { getNextIntent, getStatus, getDependencyGraph, getIntent, loadIntentMap, updateIntentStatus, getNarrative } from '../src/intent-map.js';
-import { getPhilosophy, listPhilosophyFiles } from '../src/philosophy.js';
+import { getPhilosophy, listPhilosophyFiles, validateInspirationSources, validatePartDecomposition } from '../src/philosophy.js';
 import { writeVerification, getVerificationHistory, getPendingVerifications, listVerifications, getVerificationContract } from '../src/verify.js';
 import { initProject } from '../src/init.js';
 import { activateRole } from '../src/activate.js';
-import { listVersions, readCurrentPointer, newVersion, useVersion, diffVersions } from '../src/version.js';
+import { listVersions, newVersion, useVersion, diffVersions } from '../src/version.js';
 import { doctor, contextSummary, traceIntent, reverseDep, reverseRef } from '../src/diagnostics.js';
 import { getHelpTopic, listHelpTopics } from '../src/help.js';
 import { guideProject } from '../src/guide.js';
 import { isAutoOn, autoOn, autoOff, autoStatus } from '../src/auto.js';
-import { generatePreviewPrompt } from '../src/preview.js';
+import { generatePreviewPrompt, getPreviewStatus } from '../src/preview.js';
 
 // ─── 路径解析 ──────────────────────────────────────────
-// LOOM 项目目录结构: .loom/v{N}/
-// 优先读 .loom/current 指针；不存在则回退到自动探测最新版本。
-// 也接受 --loom-dir 参数直接指定版本目录。
-
-function findLoomRoot() {
-  const flagIdx = argv.indexOf('--loom-dir');
-  if (flagIdx !== -1 && argv[flagIdx + 1]) {
-    // --loom-dir 直接指向版本目录，反推 .loom root
-    const dir = resolve(argv[flagIdx + 1]);
-    return resolve(dir, '..');
-  }
-  return join(cwd(), '.loom');
-}
+// findLoomRoot / findVersionDir / readCurrentPointer 已提取到 shared/paths.js
+// 这里只保留目录辅助函数。
 
-function findLoomDir() {
-  const flagIdx = argv.indexOf('--loom-dir');
-  if (flagIdx !== -1 && argv[flagIdx + 1]) {
-    return resolve(argv[flagIdx + 1]);
-  }
-  const loomRoot = join(cwd(), '.loom');
-  if (!existsSync(loomRoot)) {
-    die(`找不到 .loom 目录: ${loomRoot}`);
-  }
-  const current = readCurrentPointer(loomRoot);
-  if (!current) {
-    die(`.loom 下没有版本目录 (v1, v2, ...)`);
-  }
-  return join(loomRoot, current);
+function getPhilosophyDir(versionDir) {
+  return join(versionDir, '00_PHILOSOPHY');
 }
 
-function getPhilosophyDir(loomDir) {
-  return join(loomDir, '00_PHILOSOPHY');
-}
-
-function getVerificationsDir(loomDir) {
-  return join(loomDir, 'verifications');
+function getVerificationsDir(versionDir) {
+  return join(versionDir, 'verifications');
 }
 
 // ─── 输出工具 ──────────────────────────────────────────
@@ -78,56 +55,66 @@ const [cmd, sub, ...rest] = argv.slice(2);
 
 try {
   switch (cmd) {
+    case '--version':
+    case '-v': {
+      // 从根 package.json 读版本号（cli/bin -> cli -> LOOM root）
+      const pkgPath = resolve(__dirname, '..', '..', 'package.json');
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      console.log(`loom ${pkg.version}`);
+      break;
+    }
+
     case 'intent': {
-      const loomDir = findLoomDir();
+      const versionDir = findVersionDir();
       switch (sub) {
         case 'next':
-          output(getNextIntent(loomDir) ?? '没有可执行的 Intent');
+          output(getNextIntent(versionDir) ?? '没有可执行的 Intent');
           break;
         case 'status': {
-          const s = getStatus(loomDir);
+          const s = getStatus(versionDir);
+          const fmt = (ids) => ids.map((id) => s.titles[id] ? `${id}(${s.titles[id]})` : id).join(', ') || '-';
           console.log(`进度: ${s.counts.completed}/${s.counts.total} 完成`);
-          console.log(`  pending:     ${s.counts.pending}    ${s.ids.pending.join(', ') || '-'}`);
-          console.log(`  in_progress: ${s.counts.in_progress}    ${s.ids.in_progress.join(', ') || '-'}`);
-          console.log(`  completed:   ${s.counts.completed}    ${s.ids.completed.join(', ') || '-'}`);
-          console.log(`  blocked:     ${s.counts.blocked}    ${s.ids.blocked.join(', ') || '-'}`);
+          console.log(`  pending:     ${s.counts.pending}    ${fmt(s.ids.pending)}`);
+          console.log(`  in_progress: ${s.counts.in_progress}    ${fmt(s.ids.in_progress)}`);
+          console.log(`  completed:   ${s.counts.completed}    ${fmt(s.ids.completed)}`);
+          console.log(`  blocked:     ${s.counts.blocked}    ${fmt(s.ids.blocked)}`);
           break;
         }
         case 'graph':
-          output(getDependencyGraph(loomDir));
+          output(getDependencyGraph(versionDir));
           break;
         case 'get': {
           const id = rest[0];
           if (!id) die('用法: loom intent get <id>');
-          output(getIntent(loomDir, id));
+          output(getIntent(versionDir, id));
           break;
         }
         case 'narrative': {
           const id = rest[0];
           if (!id) die('用法: loom intent narrative <id>');
-          output(getNarrative(loomDir, id));
+          output(getNarrative(versionDir, id));
           break;
         }
         case 'validate':
-          loadIntentMap(loomDir);
+          loadIntentMap(versionDir);
           console.log('Intent Map 校验通过');
           break;
         case 'trace': {
           const id = rest[0];
           if (!id) die('用法: loom intent trace <id>');
-          output(traceIntent(loomDir, getVerificationsDir(loomDir), getPhilosophyDir(loomDir), id));
+          output(traceIntent(versionDir, getVerificationsDir(versionDir), getPhilosophyDir(versionDir), id));
           break;
         }
         case 'reverse-dep': {
           const id = rest[0];
           if (!id) die('用法: loom intent reverse-dep <id>');
-          output(reverseDep(loomDir, id));
+          output(reverseDep(versionDir, id));
           break;
         }
         case 'reverse-ref': {
           const anchor = rest[0];
           if (!anchor) die('用法: loom intent reverse-ref <anchor>\n例: loom intent reverse-ref PRODUCT_PHILOSOPHY.md#core-belief');
-          output(reverseRef(loomDir, anchor));
+          output(reverseRef(versionDir, anchor));
           break;
         }
         case 'update': {
@@ -135,7 +122,7 @@ try {
           const statusFlagIdx = argv.indexOf('--status');
           const newStatus = statusFlagIdx !== -1 ? argv[statusFlagIdx + 1] : null;
           if (!id || !newStatus) die('用法: loom intent update <id> --status <pending|in_progress|completed|blocked|needs_review>');
-          updateIntentStatus(loomDir, id, newStatus);
+          updateIntentStatus(versionDir, id, newStatus);
           console.log(`${id} status 已更新为 ${newStatus}`);
           break;
         }
@@ -166,42 +153,77 @@ try {
     case 'activate': {
       const role = sub;
       if (!role) die('用法: loom activate <role>\n角色: weaver | visionary | architect | forge | keeper');
-      // weaver 不需要 loomDir（项目还没初始化时也能激活）
-      let loomDir = null;
+      // weaver 不需要 versionDir（项目还没初始化时也能激活）
+      let versionDir = null;
       if (role !== 'weaver') {
-        try { loomDir = findLoomDir(); } catch { /* 项目还没初始化，weaver 之外的角色会缺少项目上下文 */ }
+        try {
+          versionDir = findVersionDir();
+        } catch (e) {
+          // 只吞"找不到 .loom 目录"——其他错误（权限、磁盘）向上抛
+          if (!String(e.message).includes('找不到 .loom')) throw e;
+        }
       }
-      const prompt = activateRole(role, loomDir);
+      const prompt = activateRole(role, versionDir);
       output(prompt);
       break;
     }
 
     case 'philosophy': {
-      const loomDir = findLoomDir();
+      const versionDir = findVersionDir();
       switch (sub) {
         case 'get': {
           const anchor = rest[0];
           if (!anchor) die('用法: loom philosophy get <anchor>\n例: loom philosophy get PRODUCT_PHILOSOPHY.md#core-belief');
-          output(getPhilosophy(getPhilosophyDir(loomDir), anchor));
+          output(getPhilosophy(getPhilosophyDir(versionDir), anchor));
           break;
         }
         case 'list':
-          output(listPhilosophyFiles(getPhilosophyDir(loomDir)));
+          output(listPhilosophyFiles(getPhilosophyDir(versionDir)));
           break;
+        case 'check': {
+          const philDir = getPhilosophyDir(versionDir);
+          const inspiration = validateInspirationSources(philDir);
+          const decomposition = validatePartDecomposition(philDir);
+          const allIssues = [...inspiration.issues, ...decomposition.issues];
+          const allPassed = inspiration.passed && decomposition.passed;
+
+          if (allPassed) {
+            console.log('✓ 哲学文档校验通过');
+            console.log('  灵感来源:');
+            for (const { file, sources } of inspiration.sources) {
+              console.log(`    ${file}: ${sources.length} 个源`);
+            }
+            console.log('  实现部分拆解:');
+            for (const part of decomposition.parts) {
+              console.log(`    - ${part}`);
+            }
+          } else {
+            const high = allIssues.filter((i) => i.severity === 'high').length;
+            const medium = allIssues.filter((i) => i.severity === 'medium').length;
+            console.log(`✗ 哲学文档校验未通过（${allIssues.length} 个问题: ${high} high, ${medium} medium）`);
+            for (const issue of allIssues) {
+              const icon = issue.severity === 'high' ? '⚠' : '·';
+              console.log(`  ${icon} [${issue.severity}] ${issue.msg}`);
+            }
+            console.log('\n参见 meta/PHILOSOPHY_WEAVER.md + dimensions/PART_DECOMPOSITION.md + dimensions/SEARCH_METHODOLOGY.md。');
+            exit(1);
+          }
+          break;
+        }
         default:
-          die(`未知子命令: philosophy ${sub}\n用法: loom philosophy [get <anchor>|list]`);
+          die(`未知子命令: philosophy ${sub}\n用法: loom philosophy [get <anchor>|list|check]`);
       }
       break;
     }
 
     case 'verify': {
-      const loomDir = findLoomDir();
-      const verificationsDir = getVerificationsDir(loomDir);
+      const versionDir = findVersionDir();
+      const verificationsDir = getVerificationsDir(versionDir);
       switch (sub) {
         case 'contract': {
           const id = rest[0];
           if (!id) die('用法: loom verify contract <id>');
-          output(getVerificationContract(loomDir, id));
+          output(getVerificationContract(versionDir, id));
           break;
         }
         case 'history': {
@@ -212,7 +234,7 @@ try {
           break;
         }
         case 'pending':
-          output(getPendingVerifications(loomDir, verificationsDir));
+          output(getPendingVerifications(versionDir, verificationsDir));
           break;
         case 'list':
           output(listVerifications(verificationsDir));
@@ -224,9 +246,17 @@ try {
           const jsonFlagIdx = argv.indexOf('--json');
           let record;
           if (fileFlagIdx !== -1 && argv[fileFlagIdx + 1]) {
-            record = JSON.parse(readFileSync(argv[fileFlagIdx + 1], 'utf-8'));
+            try {
+              record = JSON.parse(readFileSync(argv[fileFlagIdx + 1], 'utf-8'));
+            } catch (e) {
+              die(`JSON 文件解析失败: ${argv[fileFlagIdx + 1]}\n原因: ${e.message}`);
+            }
           } else if (jsonFlagIdx !== -1 && argv[jsonFlagIdx + 1]) {
-            record = JSON.parse(argv[jsonFlagIdx + 1]);
+            try {
+              record = JSON.parse(argv[jsonFlagIdx + 1]);
+            } catch (e) {
+              die(`JSON 字符串解析失败: ${e.message}`);
+            }
           } else {
             die('用法: loom verify write --json-file <path> | --json <json-string>');
           }
@@ -298,8 +328,8 @@ try {
     }
 
     case 'doctor': {
-      const loomDir = findLoomDir();
-      const { issues, summary } = doctor(loomDir, getVerificationsDir(loomDir), getPhilosophyDir(loomDir));
+      const versionDir = findVersionDir();
+      const { issues, summary } = doctor(versionDir, getVerificationsDir(versionDir), getPhilosophyDir(versionDir));
       if (summary.healthy) {
         console.log('✓ 项目健康，未发现问题');
       } else {
@@ -313,8 +343,8 @@ try {
     }
 
     case 'context': {
-      const loomDir = findLoomDir();
-      output(contextSummary(loomDir, getVerificationsDir(loomDir), getPhilosophyDir(loomDir)));
+      const versionDir = findVersionDir();
+      output(contextSummary(versionDir, getVerificationsDir(versionDir), getPhilosophyDir(versionDir)));
       break;
     }
 
@@ -338,12 +368,16 @@ try {
       break;
     }
 
-    case 'guide': {
-      const result = guideProject(cwd());
-      console.log(`阶段 ${result.stage_num}: ${result.stage}`);
-      if (result.auto) {
-        console.log(`模式: AUTO（自动执行，不等确认）`);
-      } else {
+    case 'guide': {
+      const dryRun = argv.includes('--dry-run');
+      const result = guideProject(cwd(), { dryRun });
+      console.log(`阶段 ${result.stage_num}: ${result.stage}`);
+      if (dryRun) {
+        console.log('诊断: dry-run（不写 heartbeat）');
+      }
+      if (result.auto) {
+        console.log(`模式: AUTO（自动执行，不等确认）`);
+      } else {
         console.log(`模式: 手动（每步需用户确认）`);
       }
       console.log(`\n${result.message}`);
@@ -361,6 +395,9 @@ try {
         case 'on':
           autoOn(loomRoot);
           console.log('AUTO 模式已开启。Agent 将自动连续执行，不等用户确认。');
+          console.log('核心契约: 持续运行，除非出意外否则不允许私自停止。');
+          console.log('  - L3 human_review 由 Keeper 自主判定，不停下等人类');
+          console.log('  - 唯一允许停下的情况: blocked（依赖阻塞/契约无法判定/连续 3 轮 deviated 升级）');
           console.log('关闭: loom auto off');
           break;
         case 'off':
@@ -371,8 +408,18 @@ try {
           const status = autoStatus(loomRoot);
           if (status.on) {
             console.log(`AUTO 模式: 开启（自 ${status.since}）`);
+            console.log('  规则: stage 1-3（哲学/愿景/架构）需人类 review，stage 4+（Intent Loop）自动执行');
+            if (status.heartbeat) {
+              const hb = status.heartbeat;
+              console.log(`  心跳: ${hb.timestamp}`);
+              console.log(`    阶段: ${hb.stage} (stage ${hb.stage_num})`);
+              console.log(`    下一步: ${hb.next_action}`);
+              console.log(`    命令: ${hb.next_command}`);
+            } else {
+              console.log('  心跳: 尚未记录（运行 loom guide 后生成）');
+            }
           } else {
-            console.log('AUTO 模式: 关闭');
+            console.log('AUTO 模式: 关闭（所有阶段都需人类确认）');
           }
           break;
         }
@@ -382,11 +429,56 @@ try {
       break;
     }
 
-    case 'preview': {
-      // 输出提示词，让 AI 读 .loom/ 文件、重组信息、生成 HTML
+    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();
+        } 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('');
@@ -416,9 +508,10 @@ To Human:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 用法:
-  loom init                     初始化项目（创建 .loom/v1/ 骨架 + 模板）
-  loom guide                    诊断当前阶段，输出下一步引导
-  loom auto on|off|status       AUTO 模式开关（on 时 Agent 自动连续执行）
+  loom init                     初始化项目（创建 .loom/v1/ 骨架 + 模板）
+  loom guide                    诊断当前阶段，输出下一步引导
+  loom guide --dry-run          只读诊断当前阶段，不写 heartbeat
+  loom auto on|off|status       AUTO 模式开关（on 时 Agent 自动连续执行）
   loom activate <role>          输出角色激活提示词（weaver|visionary|architect|forge|keeper）
 
   loom version list             列出所有版本（* 标记当前）
@@ -440,11 +533,15 @@ To Human:
 
   loom doctor                   项目健康检查（一致性+孤儿引用+循环依赖+僵尸）
   loom context                  上下文摘要（进度+下一步+待验证+风险）
-  loom preview                  输出提示词+数据，让 AI 生成 HTML 可视化预览
-  loom help <topic>             分层指南（workflow|concepts|loop|version|doctor）
+  loom preview                  打开新鲜 HTML；过期则提示重新生成
+  loom preview status           检查 preview 是否存在、是否新鲜
+  loom preview --regen          强制重新输出提示词（让 AI 重新生成 HTML）
+  loom preview --stale          强行打开过期 preview
+  loom help <topic>             分层指南（workflow|concepts|loop|version|doctor|preview）
 
   loom philosophy get <anchor>  按锚点加载哲学章节
   loom philosophy list          列出哲学文档文件
+  loom philosophy check         校验灵感来源质量（源数量/多样性/理由）
 
   loom verify contract <id>     返回某 Intent 的验收契约（解析引用）
   loom verify history <id>      返回某 Intent 验证历史

package/cli/help/concepts.md

@@ -0,0 +1,72 @@
+## LOOM 核心概念
+
+## 哲学
+
+项目的价值观和工程原则——为什么存在、什么不做、冲突时谁优先。
+由 Philosophy Weaver 从真实思想体系织造，不是模板填空。
+所有角色激活时强制加载哲学作为共同锚点。
+
+相关命令：
+- \`loom philosophy get <anchor>\` — 加载哲学章节
+- \`loom philosophy list\` — 列出哲学文档
+- \`loom intent reverse-ref <anchor>\` — 哪些 Intent 引用了这个哲学锚点
+
+## Intent
+
+一个意图单元——不是"做什么"（任务），是"为什么做"（意图）。
+每个 Intent 携带：
+- narrative_ref — 意图叙事引用（为什么存在）
+- depends_on — 依赖的 Intent（拓扑序）
+- acceptance — 验收契约（Keeper 据此判定）
+- philosophy_anchors — 哲学锚点（引用哪些哲学原则）
+- status — 状态（pending|in_progress|completed|blocked|needs_review）
+- verification_method — 验证方式（L1 静态|L2 运行时|L3 人类反馈，可选）
+
+相关命令：
+- \`loom intent next\` — 下一个可执行 Intent
+- \`loom intent get <id>\` — Intent 详情
+- \`loom intent narrative <id>\` — 意图叙事
+- \`loom intent trace <id>\` — 完整追溯链
+- \`loom intent reverse-dep <id>\` — 谁依赖这个 Intent
+
+## Intent Map
+
+所有 Intent 的依赖图（JSON）。Architect 绘制，定义拓扑序和依赖关系。
+必须是 DAG（有向无环图），不能有循环依赖。
+
+相关命令：
+- \`loom intent validate\` — 校验结构 + 依赖一致性
+- \`loom intent graph\` — Mermaid 依赖图
+- \`loom intent status\` — 进度概览
+
+## Intent Loop
+
+核心循环：Keeper 选 Intent → Forge 实现 → Keeper 验证 → 闭合或修正。
+每个 Intent 独立走一圈。详细流程见 \`loom help loop\`。
+
+## Keeper
+
+独立验证子代理——不继承 Forge 的实现上下文，从磁盘重新加载意图和契约。
+判定四维度：意图忠实度 / 哲学一致性 / 底线合规 / 验收达成。
+判定结果：passed / deviated / blocked / pending_human。
+
+## 底线
+
+不可妥协的约束（BASELINE.md 5 条 + 项目特定底线）。
+角色激活时强制加载，哲学不能覆盖。违反底线必须立即停止。
+
+## 验证记录
+
+Keeper 每次验证写入一条记录（追加模式），包含：
+- verdict（passed/deviated/blocked/pending_human）
+- 四维度判定
+- 证据
+- 偏离说明（如果 deviated）
+
+deviated 连续 3 轮升级 blocked。pending_human 默认 7 天超时升级 blocked。
+
+相关命令：
+- \`loom verify contract <id>\` — 获取验收契约
+- \`loom verify write --json-file <path>\` — 写入验证记录
+- \`loom verify history <id>\` — 验证历史
+- \`loom verify pending\` — 待验证的 Intent