@haaaiawd/loom 0.1.0 → 0.7.0

package/cli/src/verify.js

@@ -3,10 +3,19 @@
 
 import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { extractMdSection, readJsonFile } from './shared/md-utils.js';
 
 /** 合法判定结果 */
 const VALID_VERDICTS = ['passed', 'deviated', 'blocked', 'pending_human'];
 
+/** 四个必须覆盖的验证维度 */
+const REQUIRED_DIMENSIONS = [
+  'intent_fidelity',
+  'philosophy_consistency',
+  'baseline_compliance',
+  'acceptance_achievement',
+];
+
 /**
  * 写入一条验证记录（追加模式——同一 Intent 多次验证保留完整历史）。
  * 文件格式: { intent_id, records: [{ round, verdict, timestamp, ... }] }
@@ -17,6 +26,7 @@ const VALID_VERDICTS = ['passed', 'deviated', 'blocked', 'pending_human'];
  * @param {string} record.timestamp — ISO 8601
  * @param {string} record.summary — 验证摘要
  * @param {object} record.dimensions — 四个维度的验证结果
+ * @param {string} [record.reproduction_command] — 复现验证的命令（如 "LLM_API_KEY=mock npm test"）
  * @param {string} [record.deviation_detail] — 偏离说明（deviated 时）
  * @param {boolean} [record.reset_suggested] — 是否建议重置上下文
  * @returns {{ filePath: string, round: number, deviated_count: number, should_escalate: boolean }}
@@ -29,6 +39,36 @@ export function writeVerification(verificationsDir, record) {
   }
   if (!record.timestamp) errors.push('缺少 timestamp');
   if (!record.dimensions) errors.push('缺少 dimensions（四个维度结果）');
+  // dimensions 结构校验：每个维度必须是 { verdict, evidence } 对象
+  if (record.dimensions) {
+    for (const dim of REQUIRED_DIMENSIONS) {
+      const v = record.dimensions[dim];
+      if (v === undefined) {
+        errors.push(`dimensions.${dim} 缺失（四个维度必须全覆盖）`);
+      } else if (typeof v === 'string') {
+        errors.push(`dimensions.${dim} 是旧格式（枚举值），必须改成 { verdict, evidence } 对象`);
+      } else if (typeof v !== 'object' || v === null) {
+        errors.push(`dimensions.${dim} 必须是 { verdict, evidence } 对象`);
+      } else {
+        if (!VALID_VERDICTS.includes(v.verdict)) {
+          errors.push(`dimensions.${dim}.verdict 非法: "${v.verdict}" (合法: ${VALID_VERDICTS.join('|')})`);
+        }
+        if (!v.evidence || typeof v.evidence !== 'string' || v.evidence.trim() === '') {
+          errors.push(`dimensions.${dim}.evidence 缺失——必须给出具体证据，不能只写"合规"`);
+        } else {
+          // evidence 质量校验：长度 + 废话检测
+          const ev = v.evidence.trim();
+          if (ev.length < 10) {
+            errors.push(`dimensions.${dim}.evidence 太短（${ev.length}字符 < 10）——必须给出具体证据，不能只写"合规"`);
+          }
+          const NONSENSE = ['合规', '通过', 'OK', 'ok', '没问题', '符合要求', '已检查', 'pass', 'passed', 'done'];
+          if (NONSENSE.includes(ev)) {
+            errors.push(`dimensions.${dim}.evidence "${ev}" 是通用评价而非具体证据——必须写"对照了什么 + 在代码哪里看到/没看到"`);
+          }
+        }
+      }
+    }
+  }
   if (errors.length > 0) {
     throw new Error(`验证记录校验失败:\n  - ${errors.join('\n  - ')}`);
   }
@@ -38,7 +78,16 @@ export function writeVerification(verificationsDir, record) {
   // 读取已有记录（如果有）
   let data;
   if (existsSync(filePath)) {
-    data = JSON.parse(readFileSync(filePath, 'utf-8'));
+    data = readJsonFile(filePath, '验证记录');
+    // 结构校验：已有文件必须是 { intent_id, records: [] } 格式
+    if (!data || typeof data !== 'object' || !Array.isArray(data.records)) {
+      throw new Error(
+        `已有验证记录格式错误: ${filePath}\n` +
+        `期望格式: { intent_id, records: [...] }\n` +
+        `实际格式: ${JSON.stringify(data).slice(0, 200)}\n` +
+        `修复: 删除或修正该文件后重试。`
+      );
+    }
   } else {
     data = { intent_id: record.intent_id, records: [] };
   }
@@ -55,6 +104,7 @@ export function writeVerification(verificationsDir, record) {
     timestamp: record.timestamp,
     summary: record.summary,
     dimensions: record.dimensions,
+    reproduction_command: record.reproduction_command,
     deviation_detail: record.deviation_detail,
     reset_suggested: record.reset_suggested,
   });
@@ -77,18 +127,15 @@ export function getVerificationHistory(verificationsDir, intentId) {
   if (!existsSync(filePath)) {
     return null;
   }
-  const raw = readFileSync(filePath, 'utf-8');
-  return JSON.parse(raw);
+  return readJsonFile(filePath, '验证记录');
 }
 
 /**
  * 返回所有待验证的 Intent（有实现产物但还没验证记录的）。
  * 需要传入 Intent Map 来判断哪些 Intent 是 in_progress。
  */
-export function getPendingVerifications(loomDir, verificationsDir) {
-  const intentMap = JSON.parse(
-    readFileSync(join(loomDir, '04_INTENT_MAP.json'), 'utf-8')
-  );
+export function getPendingVerifications(versionDir, verificationsDir) {
+  const intentMap = readJsonFile(join(versionDir, '04_INTENT_MAP.json'), 'Intent Map');
   const pending = [];
   for (const [id, intent] of Object.entries(intentMap.intents)) {
     if (intent.status === 'in_progress') {
@@ -101,11 +148,14 @@ export function getPendingVerifications(loomDir, verificationsDir) {
 
 /**
  * 列出所有验证记录文件。
+ * 只列出正式验证记录——文件名匹配 INT-XXX 格式且内容含 records 字段。
+ * 过滤掉用户写入的临时输入文件（如 INT-001.verify.json、_tmp_*.json）。
  */
 export function listVerifications(verificationsDir) {
   if (!existsSync(verificationsDir)) return [];
   return readdirSync(verificationsDir)
     .filter((f) => f.endsWith('.json'))
+    .filter((f) => /^INT-\d+\.json$/.test(f))
     .map((f) => f.replace('.json', ''));
 }
 
@@ -113,12 +163,12 @@ export function listVerifications(verificationsDir) {
  * 获取某 Intent 的验证契约（acceptance 字段的解析结果）。
  * 如果 acceptance 是内联定义，直接返回。
  * 如果是引用（如 "see 05_VERIFICATION.md#int-001"），解析引用并返回对应章节内容。
- * @param {string} loomDir — .loom/v{N}/ 目录
+ * @param {string} versionDir — .loom/v{N}/ 目录
  * @param {string} intentId — Intent ID
  * @returns {string} 验收契约内容
  */
-export function getVerificationContract(loomDir, intentId) {
-  const intentMap = JSON.parse(readFileSync(join(loomDir, '04_INTENT_MAP.json'), 'utf-8'));
+export function getVerificationContract(versionDir, intentId) {
+  const intentMap = readJsonFile(join(versionDir, '04_INTENT_MAP.json'), 'Intent Map');
   if (!(intentId in intentMap.intents)) {
     throw new Error(`Intent 不存在: ${intentId}`);
   }
@@ -128,72 +178,14 @@ export function getVerificationContract(loomDir, intentId) {
   const refMatch = acceptance.match(/(?:see\s+)?(\w+\.md)#([\w-]+)/i);
   if (refMatch) {
     const [, file, section] = refMatch;
-    const filePath = join(loomDir, file);
+    const filePath = join(versionDir, file);
     if (!existsSync(filePath)) {
       throw new Error(`验证契约引用的文件不存在: ${filePath}`);
     }
     const content = readFileSync(filePath, 'utf-8');
-    return extractMdSection(content, section);
+    return extractMdSection(content, section, '验证契约');
   }
 
   // 内联定义，直接返回
   return acceptance;
 }
-
-/**
- * 从 heading 文本中提取显式锚点。
- * 支持 Pandoc/MDX 风格语法: "## INT-003 {#int-003}"
- */
-function extractExplicitAnchor(headingText) {
-  const match = headingText.match(/\{#([\w-]+)\}\s*$/);
-  return match ? match[1] : null;
-}
-
-/**
- * slugify — 和 philosophy.js 保持一致的逻辑。
- */
-function slugify(text) {
-  return text
-    .replace(/\r/g, '')
-    .replace(/\{#[\w-]+\}\s*$/, '')
-    .toLowerCase()
-    .replace(/[^\w\s-]/g, '')
-    .replace(/\s+/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^-|-$/g, '')
-    .trim();
-}
-
-/**
- * 从 MD 内容中按 heading slug 提取章节。
- * 支持显式锚点 {#slug} 和自动 slugify。
- */
-function extractMdSection(content, sectionSlug) {
-  const lines = content.split('\n');
-  let capturing = false;
-  let targetLevel = 0;
-  const captured = [];
-
-  for (const line of lines) {
-    const cleanLine = line.replace(/\r$/, '');
-    const headingMatch = cleanLine.match(/^(#{1,6})\s+(.+)$/);
-    if (headingMatch) {
-      const level = headingMatch[1].length;
-      const headingText = headingMatch[2];
-      const slug = extractExplicitAnchor(headingText) || slugify(headingText);
-      if (capturing && level <= targetLevel) break;
-      if (slug === sectionSlug) {
-        capturing = true;
-        targetLevel = level;
-        captured.push(cleanLine);
-        continue;
-      }
-    }
-    if (capturing) captured.push(cleanLine);
-  }
-
-  if (captured.length === 0) {
-    throw new Error(`验证契约章节未找到: #${sectionSlug}`);
-  }
-  return captured.join('\n').trim();
-}

package/cli/src/version.js

@@ -122,7 +122,7 @@ function listFilesRelative(dir, base = '') {
   if (!existsSync(dir)) return result;
   for (const entry of readdirSync(dir)) {
     const full = join(dir, entry);
-    const rel = base ? `${base}/${entry}` : entry;
+    const rel = base ? join(base, entry) : entry;
     if (statSync(full).isDirectory()) {
       result.push(...listFilesRelative(full, rel));
     } else {

package/meta/INTENT_LOOP.md

@@ -55,6 +55,7 @@ Intent Map 是 loop 的地图。它不是扁平任务表，是**带依赖关系
 | 字段 | 说明 | 为什么需要 |
 |---|---|---|
 | `id` | 稳定标识（如 `INT-001`） | 全局引用，不随重命名丢失 |
+| `title` | 一句话标题 | `intent next`/`status` 输出时优先展示，让 Agent 不用读完整叙事就能判断当前在做什么 |
 | `narrative_ref` | 意图叙事的引用（指向愿景文档的章节） | Keeper 验证的依据——"为什么存在" |
 | `depends_on` | 前置 Intent ID 列表 | 拓扑序计算、依赖检查 |
 | `acceptance` | 验收契约（什么算"忠实实现"） | Keeper 判定通过/偏离的标准 |
@@ -66,20 +67,41 @@ Intent Map 是 loop 的地图。它不是扁平任务表，是**带依赖关系
 - `acceptance` 的具体形式（Given-When-Then / 用户故事验收 / 自定义）
 - 是否有额外字段（如 `estimated_effort`、`priority`、`sprint`）
 
+**system_id 归属规则**（Architect 设计 Intent Map 时必须遵守）：
+- 每个 Intent 的验收契约只能要求**该 Intent 自己产出的文件**可运行/可验证
+- 如果 Intent A 的契约要求"能启动"，但启动入口文件归 Intent B，这是契约设计错误
+- 正确做法：要么把"最小可启动骨架"划进最早执行的 Intent 的产出范围，要么把契约措辞改为"提供启动入口配置，实际启动在依赖 Intent 完成后验证"
+- Forge 在实现时如果发现契约要求的文件不属于当前 Intent 的产出范围，应该自主判断：要么扩展当前 Intent 的产出（在契约允许的自由空间内），要么标记 `blocked` 报告"契约要求跨 Intent 产出"
+
 **acceptance 质量底线**：`acceptance` 必须具体到可验证——Keeper 读完后能明确判断"满足/不满足"。禁止模糊措辞（如"实现正确即可"、"功能正常"）。如果 Keeper 验证时发现 acceptance 无法判定，必须标记 `blocked`，要求 Architect 重新定义。
 
+**acceptance 承诺分层**：
+
+acceptance 不只是"实现什么功能"，是"这个 Intent 向系统承诺了什么"。分两层：
+1. **功能承诺**：这个 Intent 产出什么可观察行为（Given-When-Then）
+2. **防御承诺**：这个 Intent 不会发生什么（从 `philosophy_anchors` 引用的反模式派生）
+
+防御承诺不是让 Keeper 验证时自己去对照反模式，是 Architect 在设计阶段就把反模式转成可验证的契约。例：`AI_PHILOSOPHY#anti-patterns` "禁止直接 JSON.parse" → 防御契约 "LLM 返回非合法 JSON 时抛明确错误，不返回空数组假装成功"。
+
+**Pre-Mortem 设计法**（Architect 设计时用）：对每个 Intent 做一次 Pre-Mortem——假设这个 Intent 实现后失败了，最可能的失败原因是什么？把那个失败原因变成 acceptance 里的一条防御契约。这让 acceptance 从"描述成功"升级为"防御失败"。
+
 **acceptance 示例**：
 
 ```
-✓ 具体可验证：
+✓ 具体可验证（功能承诺 + 防御承诺）：
 "Given 用户已注册且邮箱已验证
  When 用户输入正确的邮箱和密码
  Then 用户成功登录并跳转到 /dashboard
- And  错误的密码显示'用户名或密码错误'"
+ And  错误的密码显示'用户名或密码错误'
+ And  [防御承诺] 密码错误时不泄露用户是否存在（来自 ENGINEERING_CREED#anti-patterns）"
 
 ✓ 具体可验证（性能）：
 "从 MySQL 抽取 100 万行数据完成时间 < 5 分钟（在标准测试环境下）"
 
+✓ 具体可验证（防御承诺）：
+"LLM 返回非合法 JSON 时抛明确错误，不返回空数组假装成功
+ （Pre-Mortem: LLM 返回乱码导致前端崩溃 → 防御契约来自 AI_PHILOSOPHY#anti-patterns）"
+
 ✗ 模糊不可验证：
 "实现正确即可"
 "功能正常"
@@ -143,6 +165,16 @@ Verification 是 loop 的验证环节。它不是 code review（那是看代码
 - 在人类验证完成前，Intent 的总判定为 `blocked`（不能标记 completed）
 - 如果用户长期不补充判定（默认 7 天），Keeper 将该 Intent 升级为 `blocked`，报告"人类验证超时"
 
+**AUTO 模式下的 L3 规则**（关键差异）：
+- AUTO 模式开启时（`.loom/auto` 存在），**不需要任何 human review**
+- Keeper 遇到 L3 verification_method 时，**自主判定**所有维度，不标 `pending_human`
+- Keeper 用 L1 静态审查 + L2 运行时验证的能耐去覆盖 L3 维度，给出明确判定（passed/deviated）
+- Intent 直接按 Keeper 判定流转，**不停下等人类**
+- AUTO 模式的核心契约：**持续运行，除非出意外否则不允许私自停止**
+- "出意外"定义：blocked（依赖阻塞/契约无法判定/连续 3 轮 deviated 升级）、fatal 错误（Intent Map 损坏/循环依赖）
+- Agent 不允许因为"这个维度我判断不了"就停下来——要么判 passed（有证据），要么判 deviated（有偏离说明），不允许 pending_human
+- **验证记录必须说明**：summary 字段里要写明"AUTO 模式下 L3 维度由 Keeper 自主判定，用 L1+L2 能耐覆盖"，让后续审查者知道这是自主判定而非人类确认
+
 **自由空间**（哲学决定）：
 - 哪些 Intent 用 L1、哪些用 L2、哪些用 L3——由 Architect 在 Intent Map 中通过 `verification_method` 字段声明
 - 验证脚本的具体形式（单元测试 / 集成测试 / 评估集 / 性能基准）由 Architect 和哲学决定
@@ -186,29 +218,98 @@ Verification 是 loop 的验证环节。它不是 code review（那是看代码
 **验证记录格式**：
 
 ```json
-// verifications/INT-{id}.json
+// verifications/INT-{id}.json — 多轮验证追加模式
 {
   "intent_id": "INT-001",
-  "verdict": "passed | deviated | blocked | pending_human",
-  "fidelity": "high | medium | low",
-  "verification_level": "L1 | L2 | L3",
-  "checked_at": "ISO 8601 时间戳",
-  "dimensions_checked": ["intent_fidelity", "philosophy_consistency", "baseline_compliance", "acceptance"],
-  "pending_human_dimensions": ["acceptance"],
-  "notes_ref": "verifications/INT-001.md"
+  "records": [
+    {
+      "round": 1,
+      "verdict": "passed | deviated | blocked | pending_human",
+      "timestamp": "ISO 8601 时间戳",
+      "summary": "验证摘要——具体证据，不是'看起来没问题'",
+      "dimensions": {
+        "intent_fidelity": {
+          "verdict": "passed",
+          "evidence": "对照 01_VISION.md#int-001 意图叙事第 2 段，extract.js 实现了 prompt→LLM→parse→validate 编排，忠实于'把模糊变清晰'"
+        },
+        "philosophy_consistency": {
+          "verdict": "passed",
+          "evidence": "AI_PHILOSOPHY#anti-patterns '禁止直接 JSON.parse' → extract.js L43-47 有 try/catch；'禁止无超时调用' → llm.js L32-33 有 AbortController；ENGINEERING_CREED#anti-patterns '禁止硬编码密钥' → grep sk- 在 src/ 0 命中"
+        },
+        "baseline_compliance": {
+          "verdict": "passed",
+          "evidence": "B1 结构设计→02_ARCHITECTURE.md 有目录结构；B2 禁止硬编码→config.js 集中管理；B3 接口契约→05_VERIFICATION.md 有 schema；B4 决策可追溯→ADR-001 存在；B5 意图回溯→每个文件头有意图注释"
+        },
+        "acceptance_achievement": {
+          "verdict": "passed",
+          "evidence": "契约#1 prompt 约束完整→prompts/extract.js L19-32；契约#2 schema 校验→validate.js L50-62；契约#5 测试 6/6 pass→reproduction_command 可复现"
+        }
+      },
+      "reproduction_command": "LLM_API_KEY=mock npm test",
+      "deviation_detail": "偏离说明（deviated 时必填）",
+      "reset_suggested": false
+    }
+  ]
 }
 ```
 
-```markdown
-<!-- verifications/INT-001.md -->
+**字段说明**：
+- `intent_id`：Intent ID，如 `INT-001`
+- `records`：验证记录数组，每次验证追加一条
+- `round`：轮次，从 1 开始递增
+- `verdict`：总判定，四选一
+- `timestamp`：ISO 8601 时间戳
+- `summary`：验证摘要——具体证据，不是"看起来没问题"
+- `dimensions`：四个维度的判定结果，**每个维度必须是 `{ verdict, evidence }` 对象**——`verdict` 是枚举值，`evidence` 是具体证据字符串。不允许只写"合规"，必须写"对照了什么 + 在代码哪里看到/没看到"
+- `reproduction_command`：复现验证的命令——别人拿到项目后跑这个命令能复现验证结果。如 `LLM_API_KEY=mock npm test`。L2 运行时验证必填，L1 静态审查可选
+- `deviation_detail`：偏离说明（deviated 时必填）
+- `reset_suggested`：是否建议重置上下文（context rot 严重时）
+
+**evidence 的质量底线**：evidence 必须具体到可定位——"在 X 文件 Y 行看到 Z"或"对照哲学锚点 A 的反模式 B，代码里 C 处有/没有对应处理"。模糊的 evidence（"看起来没问题"、"基本合规"）等于未验证。CLI 会校验 evidence 非空，但内容质量由 Keeper 的诚实度保证。
+
+**`loom verify write` 的输入格式**（单条记录，CLI 自动包装成上面的数组格式）：
+```json
+{
+  "intent_id": "INT-001",
+  "verdict": "passed",
+  "timestamp": "2026-06-28T12:00:00.000Z",
+  "summary": "6/6 测试通过，验收契约全部达成",
+  "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 逐条合规，见 summary"
+    },
+    "acceptance_achievement": {
+      "verdict": "passed",
+      "evidence": "6 条契约全部达成，npm test 6/6 pass"
+    }
+  }
+}
+```
+
+**验证叙事 MD 文件**（可选但推荐——JSON 存判定，MD 存详细证据）：
+```
+verifications/INT-001.md
+```
 Keeper 验证 INT-001：
-- 意图忠实度：[判定 + 理由]
-- 哲学一致性：[判定 + 理由]
-- 底线合规：[判定 + 理由]
-- 验收达成：[判定 + 理由]
+- 意图忠实度：[判定 + 具体证据——对照意图叙事第 X 段，实现中……]
+- 哲学一致性：[判定 + 哪条哲学约束合规/违规]
+- 底线合规：[判定 + B1-B5 各条合规情况]
+- 验收达成：[判定 + 契约第 N 条：证据……]
 - 总判定：[passed/deviated/blocked]
+- 复现命令：[reproduction_command]
 - 偏离说明（如有）：[偏离什么、修正方向]
-```
+
+MD 文件不是必须的（JSON 的 summary 字段已包含摘要），但当验证复杂、证据多时，MD 提供更完整的叙事。Keeper 至少要写 JSON，推荐 JSON + MD 都写。
 
 ---
 
@@ -307,9 +408,49 @@ Intent Loop 的固定骨架。底线之上，具体形态由哲学决定。
 
 ### Loop 终止条件
 
-- 所有 Intent 的 `status` 为 `completed` → 项目阶段完成
+- **不动点达成**：所有 Intent 的 `status` 为 `completed`，且没有 `needs_review` → 项目阶段完成
 - 用户主动停止
 - 阻塞无法解决，Keeper 判定 `blocked` 且无法通过对话修正
+- **无法收敛**：收敛趟数超过最大值（默认 3 趟），仍有 `needs_review` → blocked，报告"无法收敛，可能存在系统性问题需要 Architect 介入"
+
+### 不动点收敛机制
+
+Intent Loop 不是单纯的线性推进——它是**收敛到不动点**的过程。
+
+**默认单趟**：大多数项目按拓扑序验证所有 Intent，全部 passed → done。不需要多趟。
+
+**触发收敛**：当 Pass 1 结束后存在 `needs_review` 的 Intent（修某个 Intent 时影响了已完成的 Intent），自动进入收敛趟。
+
+```
+Pass 1（默认）: 按拓扑序验证所有 Intent
+  - 每个 Intent: Forge 实现 → Keeper 验证
+  - deviated → 修 → 重验（最多 3 轮 → blocked）
+  - 修的时候影响已完成的 Intent → 标记 needs_review
+  - passed → 下一个
+
+Pass 1 结束:
+  - 有 needs_review? → Pass 2
+  - 没有? → 不动点达成 → done
+
+Pass 2（收敛趟）: 重验所有 needs_review 的 Intent
+  - needs_review → in_progress → Keeper 重新验证
+  - deviated → 修 → 重验
+  - 修的时候又影响别的 → 标记 needs_review
+  - passed → completed
+
+Pass 2 结束:
+  - 还有 needs_review? → Pass 3
+  - 没有? → done
+
+Pass 3（最大趟数）: 同上
+  - 结束后还有 needs_review? → blocked, 报告"无法收敛"
+```
+
+**收敛趟数怎么数**：一个 Intent 从 `completed` 被标记为 `needs_review` 算一次。同一个 Intent 被标记多次 needs_review 算多次。累计标记次数超过最大趟数（默认 3）→ 无法收敛。
+
+**为什么是不动点**：每趟收敛都解决一些问题，但如果修 A 时引入了影响 B 的问题，B 就需要重验。当一趟完整 pass 没有产生任何新的 needs_review，说明"再验一遍也不会发现新东西"——这就是不动点。
+
+**AUTO 模式下**：收敛自动进行，不需要人类确认每趟 pass。Keeper 在每趟结束时检查 needs_review 数量，决定继续还是结束。
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haaaiawd/loom",
-  "version": "0.1.0",
+  "version": "0.7.0",
   "description": "LOOM — 哲学驱动开发框架。Agent 通过 CLI 访问 Intent Map / 哲学 / 验证记录，不直接读文件",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "cli/bin",
     "cli/src",
+    "cli/help",
     "meta",
     "roles",
     "templates",

package/roles/architect.md

@@ -96,4 +96,16 @@ Intent Map 是你的核心产出。它不是扁平任务表，是带依赖关系
 
 Intent Map 的 `acceptance` 字段是 Keeper 验证的**唯一真相源**。05_VERIFICATION.md 是验收契约的详细展开——如果 `acceptance` 字段空间不够，可以引用 05_VERIFICATION.md 的章节。但 Keeper 验证时读的是 `acceptance` 字段，CLI 会解析引用获取实际内容。验证契约的形式由产品哲学决定（Given-When-Then / 用户故事验收 / 自定义）。
 
+**验收契约设计思想——承诺先于功能**：
+
+acceptance 不只是"实现什么功能"，是"这个 Intent 向系统承诺了什么"。设计 acceptance 时分两层：
+1. **功能承诺**：这个 Intent 产出什么可观察行为（Given-When-Then）
+2. **防御承诺**：这个 Intent 不会发生什么（从哲学反模式派生——"不返回空数组假装成功"、"不硬编码密钥"、"不无超时调用"）
+
+**Pre-Mortem 设计法**：对每个 Intent，设计 acceptance 前先做一次 Pre-Mortem——假设这个 Intent 实现后失败了，最可能的失败原因是什么？把那个失败原因变成 acceptance 里的一条防御性契约。
+
+例：INT-001（todo 提取）Pre-Mortem → "LLM 返回乱码导致前端崩溃" → 防御契约："LLM 返回非合法 JSON 时抛明确错误，不返回空数组假装成功"。
+
+防御承诺来自 `philosophy_anchors` 引用的哲学反模式。Architect 设计 acceptance 时必须从反模式派生防御契约——不是让 Keeper 验证时自己去对照反模式，是在设计阶段就把反模式转成可验证的契约。
+
 **验证方式声明**：对于需要运行时验证的 Intent（如性能验收、数据质量验收、AI/ML 评估集验收），Architect 必须在 Intent 的 `verification_method` 字段中定义验证方式（如 `run tests/perf/test-001.js`）。对于需要人类主观判断的 Intent（如游戏手感、UI 体验），填 `human_review`。未定义时 Keeper 默认用 L1 静态审查。详见 INTENT_LOOP.md V-1.5。

package/roles/keeper.md

@@ -37,6 +37,7 @@ Visionary 在开局定义愿景。你在结局验证实现是否忠于愿景。
 2. **验证意图忠实度**：独立判定实现是否忠实于原始意图
 3. **引导修正**：偏离时与 Forge 对话，引导修正方向
 4. **守护 loop**：确保 loop 按 INTENT_LOOP.md 的控制流运行
+5. **守护不动点收敛**：当有 `needs_review` 的 Intent 时，按收敛趟处理——重验这些 Intent，通过则 completed，偏离则修正。一趟完整 pass 无新 needs_review 即收敛达成。最大 3 趟，超过判定 blocked（"无法收敛，需 Architect 介入"）
 
 ---
 
@@ -93,10 +94,36 @@ Visionary 在开局定义愿景。你在结局验证实现是否忠于愿景。
 | 维度 | 验证问题 | Keeper 怎么验 |
 |---|---|---|
 | 意图忠实度 | "这个实现忠实于原始意图吗？" | 对照 `narrative_ref` 指向的意图叙事 + `acceptance` 验收契约 |
-| 哲学一致性 | "这个实现违反了哲学文档的约束吗？" | 对照 `philosophy_anchors` 指向的哲学章节 + 反模式清单 |
+| 哲学一致性 | "这个实现违反了哲学文档的约束吗？" | 对照 `philosophy_anchors` 指向的哲学章节 + **反模式清单逐条对照**——每个反模式在代码里找证据（有/没有对应处理），不允许笼统说"合规" |
 | 底线合规 | "结构设计/硬编码/接口契约/可追溯——都合规吗？" | 对照 BASELINE.md 逐条检查 |
 | 验收达成 | "验收契约的条件满足了吗？" | 对照 `acceptance` 字段的具体条件 |
 
+**evidence 必填底线**：验证记录的每个维度必须给出 `{ verdict, evidence }`——evidence 是具体证据字符串，写明"对照了什么 + 在代码哪里看到/没看到"。模糊的 evidence（"看起来没问题"、"基本合规"）等于未验证。CLI 会校验 evidence 非空，但内容质量由你的诚实度保证。
+
+**哲学一致性维度——承诺验证法**：
+
+`philosophy_anchors` 引用的不是"参考文档"，是**承诺**。每个哲学锚点是一个视角（Lens），从这个视角看代码是否兑现了承诺。
+
+验证哲学一致性时，对 `philosophy_anchors` 引用的每个哲学文档：
+1. 读出该文档的**反模式清单**——每条反模式是一个"不做某事"的承诺
+2. 在代码里找证据——这条反模式在代码哪里被遵守/违反了
+3. 如果 Architect 在 acceptance 里派生了防御契约（见 architect.md 的 Pre-Mortem 设计法），对照防御契约验证
+4. 如果发现 acceptance 之外的反模式违反，在 evidence 里记录——这是下一趟收敛的输入
+
+evidence 的写法按哲学锚点组织：
+```
+AI_PHILOSOPHY#anti-patterns:
+  - '禁止直接 JSON.parse' → extract.js L43-47 有 try/catch ✓
+  - '禁止无超时调用' → llm.js L32-33 有 AbortController ✓
+ENGINEERING_CREED#anti-patterns:
+  - '禁止硬编码密钥' → grep sk- 在 src/ 0 命中 ✓
+  - '禁止过度抽象' → 无冗余抽象层 ✓
+观察（非契约）:
+  - routes/extract.js L34 用正则匹配 error.message 分类错误——脆弱但不在反模式清单里
+```
+
+最后一类"观察"不一定是 deviated，但记录下来作为下一趟收敛的输入。如果某个观察在后续证据积累下变成了实质问题，升级为 deviated。
+
 ### 验证能力分层（V-1.5）
 
 Keeper 的验证方式不是只有"读代码"。根据 Intent 的 `verification_method` 字段，选择对应层级：

package/templates/INTENT_MAP_TEMPLATE.json

@@ -11,9 +11,10 @@
   "intents": {
     "INT-001": {
       "id": "INT-001",
+      "title": "[必须] 一句话标题，intent next/status 输出时优先展示",
       "narrative_ref": "01_VISION.md#int-001",
       "depends_on": [],
-      "acceptance": "[必须] 什么算忠实实现。这是 Keeper 验证的唯一真相源。可以内联定义，也可以引用 05_VERIFICATION.md 的章节（如 'see 05_VERIFICATION.md#int-001'），但引用时 Keeper 通过 CLI `verify contract <id>` 命令解析引用获取实际内容。",
+      "acceptance": "[必须] 什么算忠实实现。这是 Keeper 验证的唯一真相源。可以内联定义，也可以引用 05_VERIFICATION.md 的章节（如 'see 05_VERIFICATION.md#int-001'），但引用时 Keeper 通过 CLI `verify contract <id>` 命令解析引用获取实际内容。必须包含功能承诺 + 防御承诺（见 architect.md Pre-Mortem 设计法）。",
       "philosophy_anchors": ["PRODUCT_PHILOSOPHY.md#core-belief", "ENGINEERING_CREED.md#anti-patterns"],
       "status": "pending",
       "_optional": {
@@ -26,6 +27,7 @@
     },
     "INT-002": {
       "id": "INT-002",
+      "title": "...",
       "narrative_ref": "01_VISION.md#int-002",
       "depends_on": ["INT-001"],
       "acceptance": "...",
@@ -38,6 +40,7 @@
 
   "_field_reference": {
     "id": "[必须] 稳定标识，项目生命周期内不变",
+    "title": "[必须] 一句话标题，intent next/status 输出时优先展示",
     "narrative_ref": "[必须] 指向愿景文档中意图叙事的章节锚点",
     "depends_on": "[必须] 前置 Intent ID 列表。空数组表示无依赖。",
     "acceptance": "[必须] 验收契约，Keeper 判定 passed/deviated/blocked 的唯一真相源。内联或引用 05_VERIFICATION.md。",

package/templates/VISION_TEMPLATE.md

@@ -24,21 +24,23 @@
 ## 意图清单
 
 [必须] 每个意图带意图叙事。
+[必须] 中文标题必须用显式锚点语法 `{#int-xxx}`，否则 CLI 的章节解析会失败。
 
-### INT-001：{意图名}
+### INT-001：{意图名} {#int-001}
 
 **意图叙事**：
 [必须] 为什么存在。服务于什么北极星。如果砍掉它会损失什么。
 
 **验收契约**：
 [必须] 什么算"忠实实现"。形式由产品哲学决定（Given-When-Then / 用户故事验收 / 自定义）。
+[必须] 包含功能承诺 + 防御承诺（从哲学反模式派生）。见 architect.md 的 Pre-Mortem 设计法。
 
 **哲学锚点**：
 [必须] 这个意图主要受哪些哲学约束。引用格式：`PHILOSOPHY.md#章节锚点`。
 
 ---
 
-### INT-002：{意图名}
+### INT-002：{意图名} {#int-002}
 
 [同上结构]