@haaaiawd/loom 1.3.1 → 2.0.0

package/cli/src/shared/md-utils.js

@@ -1,125 +0,0 @@
-// shared/md-utils.js — MD 章节解析的公共工具
-// 提取自 philosophy.js / intent-map.js / verify.js 三处重复实现。
-// 统一 slugify + extractMdSection + 显式锚点逻辑，修中文标题 bug。
-
-import { readFileSync, existsSync } from 'node:fs';
-
-/**
- * 从 heading 文本中提取显式锚点。
- * 支持 Pandoc/MDX 风格语法: "## 核心信念 {#core-belief}"
- * @param {string} headingText — heading 文本（不含 # 前缀）
- * @returns {string|null} 显式锚点 slug，或 null（无显式锚点时）
- */
-export function extractExplicitAnchor(headingText) {
-  const match = headingText.match(/\{#([\w-]+)\}\s*$/);
-  return match ? match[1] : null;
-}
-
-/**
- * 从 heading 文本生成 slug（fallback，无显式锚点时用）。
- * 规则：小写、去除 \r、空格转连字符、去除非 [a-z0-9_-] 字符。
- *
- * 中文标题处理：\w 不匹配中文，所以纯中文标题 slugify 后是空字符串。
- * 这是设计约束——中文标题必须用显式锚点 {#anchor} 标注。
- * slugify 返回空字符串时，调用方应给出明确错误提示。
- *
- * @param {string} text — heading 文本
- * @returns {string} slug（可能为空字符串——纯中文标题无显式锚点时）
- */
-export function slugify(text) {
-  return text
-    .replace(/\r/g, '')           // strip CRLF 的 \r
-    .replace(/\{#[\w-]+\}\s*$/, '') // 去掉显式锚点标记
-    .toLowerCase()
-    .replace(/[^\w\s-]/g, '')     // \w = [a-zA-Z0-9_]
-    .replace(/\s+/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^-|-$/g, '')
-    .trim();
-}
-
-/**
- * 从 MD 内容中提取指定 section 的内容（到下一个同级或更高级 heading 为止）。
- * 如果 sectionSlug 为 null/空，返回整个文件。
- * 支持显式锚点 {#slug} 和自动 slugify 两种方式匹配。
- *
- * @param {string} content — MD 文件内容
- * @param {string} sectionSlug — 目标 section 的 slug
- * @param {string} contextLabel — 错误信息里的上下文标签（如 "意图叙事"、"验证契约"）
- * @returns {string} 提取的章节内容
- * @throws {Error} 章节未找到时抛错，错误信息包含 contextLabel 和 slug
- */
-export function extractMdSection(content, sectionSlug, contextLabel = '章节') {
-  if (!sectionSlug) return content;
-
-  const lines = content.split('\n');
-  let capturing = false;
-  let targetLevel = 0;
-  const captured = [];
-
-  for (const line of lines) {
-    // strip \r 以兼容 Windows CRLF
-    const cleanLine = line.replace(/\r$/, '');
-    const headingMatch = cleanLine.match(/^(#{1,6})\s+(.+)$/);
-    if (headingMatch) {
-      const level = headingMatch[1].length;
-      const headingText = headingMatch[2];
-      // 优先用显式锚点，没有再 fallback 到 slugify
-      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(
-      `${contextLabel}章节未找到: #${sectionSlug}\n` +
-      `可能原因：\n` +
-      `  1. 章节标题用了中文但没加显式锚点 {#anchor}\n` +
-      `  2. 锚点 slug 拼写错误\n` +
-      `  3. 引用的文件不存在该章节`
-    );
-  }
-  return captured.join('\n').trim();
-}
-
-/**
- * 安全读取并解析 JSON 文件。
- * 统一错误处理——文件不存在、JSON 解析失败时给出明确错误信息。
- *
- * @param {string} filePath — JSON 文件绝对路径
- * @param {string} contextLabel — 错误信息里的上下文标签（如 "Intent Map"、"验证记录"）
- * @returns {object} 解析后的 JSON 对象
- * @throws {Error} 文件不存在或 JSON 解析失败时抛错，错误信息包含文件路径和原因
- */
-export function readJsonFile(filePath, contextLabel = 'JSON 文件') {
-  if (!existsSync(filePath)) {
-    throw new Error(`${contextLabel}文件不存在: ${filePath}`);
-  }
-  let raw;
-  try {
-    raw = readFileSync(filePath, 'utf-8');
-  } catch (e) {
-    throw new Error(`${contextLabel}文件读取失败: ${filePath}\n原因: ${e.message}`);
-  }
-  try {
-    return JSON.parse(raw);
-  } catch (e) {
-    throw new Error(
-      `${contextLabel}文件 JSON 解析失败: ${filePath}\n` +
-      `原因: ${e.message}\n` +
-      `请检查文件内容是否为合法 JSON（多余逗号、缺少引号等）。`
-    );
-  }
-}

package/cli/src/shared/paths.js

@@ -1,73 +0,0 @@
-// shared/paths.js — LOOM 路径解析的公共工具
-// 统一 getLoomRoot / findLoomRoot / findVersionDir 的命名和实现。
-
-import { resolve, join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { argv, cwd } from 'node:process';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-/**
- * 获取 LOOM 框架根目录（cli/src/shared 的上上上级）。
- * cli/src/shared/paths.js -> cli/src/shared -> cli/src -> cli -> LOOM root
- * @returns {string} LOOM 框架根目录绝对路径
- */
-export function getLoomRoot() {
-  return resolve(__dirname, '..', '..', '..');
-}
-
-/**
- * 从命令行参数或 cwd 推断 .loom 目录路径。
- * 优先级：--loom-dir 参数（指向版本目录，反推 .loom root）> cwd/.loom
- * @returns {string} .loom 目录绝对路径
- */
-export 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');
-}
-
-/**
- * 从命令行参数或 .loom/current 指针推断当前版本目录。
- * @returns {string} .loom/v{N} 目录绝对路径
- * @throws {Error} .loom 不存在或没有版本目录时抛错
- */
-export function findVersionDir() {
-  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)) {
-    throw new Error(`找不到 .loom 目录: ${loomRoot}`);
-  }
-  const current = readCurrentPointer(loomRoot);
-  if (!current) {
-    throw new Error(`.loom 下没有版本目录 (v1, v2, ...)`);
-  }
-  return join(loomRoot, current);
-}
-
-/**
- * 读取当前版本指针。
- * 优先读 .loom/current 文件；不存在则回退到自动探测最新版本。
- * @param {string} loomRoot — .loom 目录路径
- * @returns {string|null} 版本号如 'v1'，或 null
- */
-export function readCurrentPointer(loomRoot) {
-  const pointerPath = join(loomRoot, 'current');
-  if (existsSync(pointerPath)) {
-    const v = readFileSync(pointerPath, 'utf-8').trim();
-    if (/^v\d+$/.test(v) && existsSync(join(loomRoot, v))) return v;
-  }
-  if (!existsSync(loomRoot)) return null;
-  const versions = readdirSync(loomRoot)
-    .filter((d) => /^v\d+$/.test(d) && statSync(join(loomRoot, d)).isDirectory())
-    .sort((a, b) => parseInt(b.slice(1)) - parseInt(a.slice(1)));
-  return versions[0] ?? null;
-}

package/cli/src/shared/proof-reference.js

@@ -1,19 +0,0 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { isAbsolute, relative, resolve } from 'node:path';
-import { extractMdSection } from './md-utils.js';
-
-/** Resolve a root-relative Markdown proof reference without allowing path escape. */
-export function resolveQualityProofReference(versionDir, ref) {
-  if (typeof ref !== 'string' || !ref.trim()) throw new Error('quality_proof_ref 必须是非空字符串');
-  const match = ref.trim().match(/^([^#]+)#([\w-]+)$/);
-  if (!match) throw new Error('quality_proof_ref 必须是项目相对路径加 Markdown 锚点，例如 verifications/INT-001-quality-proof.md#int-001');
-  const [, file, anchor] = match;
-  if (isAbsolute(file)) throw new Error('quality_proof_ref 不得使用绝对路径');
-  const projectDir = resolve(versionDir, '..', '..');
-  const filePath = resolve(projectDir, file);
-  const relation = relative(projectDir, filePath);
-  if (relation.startsWith('..') || isAbsolute(relation)) throw new Error('quality_proof_ref 不得越出项目目录');
-  if (!existsSync(filePath)) throw new Error(`quality_proof_ref 指向的文件不存在: ${file}`);
-  extractMdSection(readFileSync(filePath, 'utf-8'), anchor, 'Quality Proof');
-  return { filePath, anchor, ref: ref.trim() };
-}

package/cli/src/shared/verification-method.js

@@ -1,32 +0,0 @@
-export function getIntentVerificationMethod(intent) {
-  return intent?.verification_method || intent?._optional?.verification_method || null;
-}
-
-function normalize(command) {
-  return String(command || '')
-    .replace(/^\s*(?:run|exec)\s+/i, '')
-    .replace(/\s+/g, ' ')
-    .trim();
-}
-
-function normalizePackageManager(command) {
-  return ['npm', 'pnpm', 'bun', 'yarn'].reduce(
-    (result, manager) => result.replace(new RegExp(`\\b${manager}\\b`, 'g'), '<PM>'),
-    command,
-  );
-}
-
-/** Whether a recorded reproduction command covers the Architect-declared method. */
-export function commandCoversVerificationMethod(actualCommand, expectedMethod) {
-  const actual = normalize(actualCommand);
-  const expected = normalize(expectedMethod);
-  if (!actual || !expected) return false;
-  return expected.split('&&').every((part) => {
-    const expectedPart = normalize(part);
-    if (!expectedPart || actual.includes(expectedPart)) return true;
-    const actualNorm = normalizePackageManager(actual);
-    const expectedNorm = normalizePackageManager(expectedPart);
-    if (actualNorm.includes(expectedNorm)) return true;
-    return expectedPart.startsWith('node --test') && actualNorm.includes('<PM> test');
-  });
-}

package/cli/src/verify.js

@@ -1,394 +0,0 @@
-// verify.js — 验证记录的读写和查询
-// 验证记录存放在 .loom/v{N}/verifications/ 下，每个 Intent 一份 JSON + 一份 MD。
-
-import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { extractMdSection, readJsonFile } from './shared/md-utils.js';
-import { getIntent, getEffectiveVerificationEpoch, hasLegacyIntentRevision } from './intent-map.js';
-import { formatIntentRef, resolveIntentRef } from './shared/intent-ref.js';
-import { resolveQualityProofReference } from './shared/proof-reference.js';
-import { validateAtelierRecord } from './atelier.js';
-import { assertExpertiseReady } from './expertise-pack.js';
-
-/** 合法判定结果 */
-const VALID_VERDICTS = ['passed', 'deviated', 'blocked', 'pending_human'];
-const VALID_VERIFICATION_CONTEXTS = ['independent_thread', 'human_review'];
-
-/** 每个 Intent 都必须覆盖的基础验证维度。 */
-const BASE_DIMENSIONS = [
-  'intent_fidelity',
-  'philosophy_consistency',
-  'baseline_compliance',
-  'acceptance_achievement',
-];
-
-function getRequiredDimensions(intent) {
-  const dimensions = [...BASE_DIMENSIONS];
-  if (intent?.continuity_required) dimensions.push('preservation_achievement');
-  if (intent?.quality_contract) dimensions.push('quality_achievement');
-  return dimensions;
-}
-
-/**
- * 写入一条验证记录（追加模式——同一 Intent 多次验证保留完整历史）。
- * 文件格式: { intent_id, records: [{ round, verdict, timestamp, ... }] }
- * @param {string} versionDir — 当前 .loom/v{N}/ 目录，用于可信读取 Intent revision
- * @param {string} verificationsDir — verifications/ 目录路径
- * @param {object} record — 验证记录
- * @param {string} record.intent_id — 如 "INT-001"
- * @param {string} record.verdict — passed | deviated | blocked
- * @param {string} record.timestamp — ISO 8601
- * @param {string} record.summary — 验证摘要
- * @param {object} record.dimensions — 基础维度，以及质量契约存在时的 quality_achievement
- * @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 }}
- */
-export function writeVerification(versionDir, verificationsDir, record) {
-  const errors = [];
-  let atelierEvidence = null;
-  let expertiseEvidence = null;
-  if (!record.intent_id) errors.push('缺少 intent_id');
-  if (!record.verdict || !VALID_VERDICTS.includes(record.verdict)) {
-    errors.push(`verdict 非法: "${record.verdict}" (合法: ${VALID_VERDICTS.join('|')})`);
-  }
-  if (!record.timestamp) errors.push('缺少 timestamp');
-  if (!record.dimensions) errors.push('缺少 dimensions（适用验证维度结果）');
-  const intent = record.intent_id ? getIntent(versionDir, record.intent_id) : null;
-  if (intent && !['in_progress', 'needs_review'].includes(intent.status)) {
-    errors.push(`Intent ${record.intent_id} 当前状态为 ${intent.status}；只能为 in_progress 或 needs_review 的 Intent 写入验证记录`);
-  }
-  const requiredDimensions = getRequiredDimensions(intent);
-  if (record.verdict === 'passed') {
-    const provenance = record.verification_provenance;
-    if (!provenance || typeof provenance !== 'object') {
-      errors.push('passed 必须声明 verification_provenance（verified_by + context）；实现者自检不能单独闭合 Intent');
-    } else {
-      if (typeof provenance.verified_by !== 'string' || !provenance.verified_by.trim()) errors.push('verification_provenance.verified_by 必须是非空验证者标识');
-      if (!VALID_VERIFICATION_CONTEXTS.includes(provenance.context)) errors.push(`verification_provenance.context 非法: ${provenance.context}（合法: ${VALID_VERIFICATION_CONTEXTS.join('|')}）`);
-    }
-  }
-  // dimensions 结构校验：每个维度必须是 { verdict, evidence } 对象
-  if (record.dimensions) {
-    for (const dim of requiredDimensions) {
-      const v = record.dimensions[dim];
-      if (v === undefined) {
-        errors.push(`dimensions.${dim} 缺失（当前 Intent 的适用维度必须全覆盖）`);
-      } 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 (record.verdict === 'passed' && v.verdict !== 'passed') {
-          errors.push(`整体 verdict 为 passed 时，dimensions.${dim}.verdict 也必须是 passed`);
-        }
-        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}" 是通用评价而非具体证据——必须写"对照了什么 + 在代码哪里看到/没看到"`);
-          }
-        }
-      }
-    }
-  }
-  const qualityProofRef = record.dimensions?.quality_achievement?.quality_proof_ref;
-  if (intent?.quality_contract && record.verdict === 'passed' && !qualityProofRef) {
-    errors.push('声明 quality_contract 的 Intent 通过时必须提供 dimensions.quality_achievement.quality_proof_ref');
-  }
-  if (qualityProofRef !== undefined
-    && (typeof qualityProofRef !== 'string' || qualityProofRef.trim() === '')) {
-    errors.push('dimensions.quality_achievement.quality_proof_ref 必须是非空字符串');
-  } else if (qualityProofRef !== undefined) {
-    try {
-      resolveQualityProofReference(versionDir, qualityProofRef);
-    } catch (error) {
-      errors.push(error.message);
-    }
-  }
-  if (record.verdict === 'passed' && intent) {
-    try {
-      expertiseEvidence = assertExpertiseReady(versionDir, record.intent_id);
-    } catch (error) {
-      errors.push(`passed 前必须闭合外部能力获取强门: ${error.message}`);
-    }
-  }
-  if (intent?.quality_strategy === 'atelier' && record.verdict === 'passed') {
-    try {
-      atelierEvidence = validateAtelierRecord(versionDir, record.intent_id);
-      if (!['selected', 'baseline_retained'].includes(atelierEvidence.status)) {
-        errors.push(`quality_strategy=atelier 通过前，Atelier Record 必须是 selected 或 baseline_retained（当前: ${atelierEvidence.status}）`);
-      }
-    } catch (error) {
-      errors.push(`quality_strategy=atelier 通过前必须有当前且合法的 Atelier Record: ${error.message}`);
-    }
-  }
-  if (errors.length > 0) {
-    throw new Error(`验证记录校验失败:\n  - ${errors.join('\n  - ')}`);
-  }
-
-  const intentRevision = getEffectiveIntentRevision(intent);
-
-  const filePath = join(verificationsDir, `${record.intent_id}.json`);
-
-  // 读取已有记录（如果有）
-  let data;
-  if (existsSync(filePath)) {
-    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: [] };
-  }
-
-  // 计算轮次和连续 deviated 计数。规范要求中间出现 passed/blocked 后重置。
-  const round = data.records.length + 1;
-  const recordsWithCurrent = [...data.records, record];
-  let deviatedCount = 0;
-  for (let i = recordsWithCurrent.length - 1; i >= 0; i--) {
-    if (recordsWithCurrent[i].verdict !== 'deviated') break;
-    deviatedCount++;
-  }
-
-  // 追加新记录
-  data.records.push({
-    round,
-    intent_revision: intentRevision,
-    verification_epoch: getEffectiveVerificationEpoch(intent),
-    verdict: record.verdict,
-    timestamp: record.timestamp,
-    summary: record.summary,
-    verification_provenance: record.verification_provenance,
-    dimensions: record.dimensions,
-    atelier: atelierEvidence ? {
-      record_ref: `09_ATELIER/${record.intent_id}.json`,
-      stance_revision: atelierEvidence.stance_revision,
-      status: atelierEvidence.status,
-    } : undefined,
-    expertise: expertiseEvidence ? {
-      record_ref: `10_EXPERTISE_PACKS/${record.intent_id}.json`,
-      intent_revision: expertiseEvidence.intent_revision,
-      required_node_ids: expertiseEvidence.required_node_ids,
-      source_count: expertiseEvidence.source_count,
-      capsule_count: expertiseEvidence.capsule_count,
-      pack_digest: expertiseEvidence.pack_digest,
-    } : undefined,
-    reproduction_command: record.reproduction_command,
-    deviation_detail: record.deviation_detail,
-    reset_suggested: record.reset_suggested,
-  });
-
-  writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
-
-  // 检查是否应该升级 blocked（连续 3 轮 deviated，默认值）
-  const DEVIATED_LIMIT = 3;
-  const shouldEscalate = record.verdict === 'deviated' && deviatedCount >= DEVIATED_LIMIT;
-
-  return { filePath, round, deviated_count: deviatedCount, should_escalate: shouldEscalate };
-}
-
-/**
- * 读取某 Intent 的验证历史。
- * @returns {{ intent_id: string, records: array } | null}
- */
-export function getVerificationHistory(verificationsDir, intentId) {
-  const filePath = join(verificationsDir, `${intentId}.json`);
-  if (!existsSync(filePath)) {
-    return null;
-  }
-  return readJsonFile(filePath, '验证记录');
-}
-
-/** Read each owning version's local records along the explicit predecessor graph. */
-export function getAcrossVersionVerificationHistory(currentVersionDir, inputRef) {
-  const root = resolveIntentRef(currentVersionDir, inputRef);
-  const histories = [];
-  const visited = new Set();
-  const active = new Set();
-
-  function walk(resolved) {
-    if (active.has(resolved.ref)) throw new Error(`Intent lineage 存在循环: ${[...active, resolved.ref].join(' -> ')}`);
-    if (visited.has(resolved.ref)) return;
-    active.add(resolved.ref);
-    const intent = getIntent(resolved.versionDir, resolved.intentId);
-    const local = getVerificationHistory(join(resolved.versionDir, 'verifications'), resolved.intentId);
-    histories.push({
-      ref: resolved.ref,
-      source_version: resolved.version,
-      source_intent: resolved.intentId,
-      source_intent_id: resolved.intentId,
-      records: (local?.records || []).map((record) => ({
-        ...record,
-        source_version: resolved.version,
-        source_intent: resolved.intentId,
-        source_intent_id: resolved.intentId,
-      })),
-    });
-    for (const predecessor of intent.lineage?.predecessors || []) {
-      walk(resolveIntentRef(currentVersionDir, formatIntentRef(predecessor.version, predecessor.intent_id)));
-    }
-    active.delete(resolved.ref);
-    visited.add(resolved.ref);
-  }
-
-  walk(root);
-  return { intent_ref: root.ref, across_versions: true, histories };
-}
-
-/**
- * 快捷创建验证记录——Agent 不用手动构造完整 JSON。
- * 快捷记录只能用于低风险的结构化核验；passed 仍必须显式声明独立验证来源。
- * @param {string} versionDir — 当前 .loom/v{N}/ 目录
- * @param {string} verificationsDir — verifications/ 目录路径
- * @param {string} intentId — 如 "INT-001"
- * @param {string} verdict — 'passed' | 'deviated' | 'blocked'
- * @param {string} summary — 验证摘要（也会作为所有适用维度的 evidence）
- * @param {object} [extras]
- * @param {string} [extras.reproduction_command] — 复现命令
- * @param {string} [extras.quality_proof_ref] — Quality Proof 证据引用
- * @param {string} [extras.preservation_evidence] — 对既有状态守恒的独立证据
- * @param {string} [extras.deviation_detail] — 偏离说明（deviated 时）
- * @returns {{ filePath: string, round: number, deviated_count: number, should_escalate: boolean }}
- */
-export function createQuickVerification(versionDir, verificationsDir, intentId, verdict, summary, extras = {}) {
-  const timestamp = new Date().toISOString();
-  const intent = getIntent(versionDir, intentId);
-  // 用 summary 填充适用维度的 evidence——快捷命令不要求 Agent 逐维度写
-  const dimensions = {};
-  for (const dim of getRequiredDimensions(intent)) {
-    dimensions[dim] = {
-      verdict,
-      evidence: dim === 'preservation_achievement'
-        ? (extras.preservation_evidence || summary)
-        : summary,
-    };
-  }
-  if (extras.quality_proof_ref && dimensions.quality_achievement) {
-    dimensions.quality_achievement.quality_proof_ref = extras.quality_proof_ref;
-  }
-  return writeVerification(versionDir, verificationsDir, {
-    intent_id: intentId,
-    verdict,
-    timestamp,
-    summary,
-    dimensions,
-    reproduction_command: extras.reproduction_command || null,
-    verification_provenance: extras.verification_provenance || null,
-    deviation_detail: extras.deviation_detail || null,
-  });
-}
-
-/**
- * 返回所有待验证的 Intent（有实现产物但还没验证记录的）。
- * 需要传入 Intent Map 来判断哪些 Intent 是 in_progress。
- */
-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' || intent.status === 'needs_review') {
-      const history = getVerificationHistory(verificationsDir, id);
-      if (!hasCurrentPassedVerification(intent, history)) pending.push(id);
-    }
-  }
-  return pending;
-}
-
-/** Missing Intent revisions are revision 1 without mutating the map. */
-export function getEffectiveIntentRevision(intent) {
-  return intent.revision ?? 1;
-}
-
-/**
- * Legacy records count as revision 1 only while the Intent itself is legacy.
- * Once revision is explicit, an untagged record cannot prove freshness.
- */
-export function getVerificationIntentRevision(intent, record) {
-  if (Number.isInteger(record?.intent_revision) && record.intent_revision >= 1) {
-    return record.intent_revision;
-  }
-  return hasLegacyIntentRevision(intent) ? 1 : null;
-}
-
-export function isVerificationCurrent(intent, record) {
-  return getVerificationIntentRevision(intent, record) === getEffectiveIntentRevision(intent)
-    && getVerificationEpoch(intent, record) === getEffectiveVerificationEpoch(intent);
-}
-
-export function getVerificationEpoch(intent, record) {
-  if (Number.isInteger(record?.verification_epoch) && record.verification_epoch >= 1) {
-    return record.verification_epoch;
-  }
-  return intent?.verification_epoch === undefined ? 1 : null;
-}
-
-export function getLatestPassedVerification(history) {
-  if (!Array.isArray(history?.records)) return null;
-  return [...history.records].reverse().find((record) => record.verdict === 'passed') ?? null;
-}
-
-export function hasCurrentPassedVerification(intent, history) {
-  const latest = history?.records?.[history.records.length - 1];
-  return latest?.verdict === 'passed' && isVerificationCurrent(intent, latest);
-}
-
-/**
- * 列出所有验证记录文件。
- * 只列出正式验证记录——文件名匹配 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', ''));
-}
-
-/**
- * 获取某 Intent 的验证契约（acceptance 字段的解析结果）。
- * 如果 acceptance 是内联定义，直接返回。
- * 如果是引用（如 "see 05_VERIFICATION.md#int-001"），解析引用并返回对应章节内容。
- * @param {string} versionDir — .loom/v{N}/ 目录
- * @param {string} intentId — Intent ID
- * @returns {string} 验收契约内容
- */
-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}`);
-  }
-  const acceptance = intentMap.intents[intentId].acceptance;
-
-  // 检测是否是引用格式: "see 05_VERIFICATION.md#section" 或 "05_VERIFICATION.md#section"
-  const refMatch = acceptance.match(/(?:see\s+)?(\w+\.md)#([\w-]+)/i);
-  if (refMatch) {
-    const [, file, section] = refMatch;
-    const filePath = join(versionDir, file);
-    if (!existsSync(filePath)) {
-      throw new Error(`验证契约引用的文件不存在: ${filePath}`);
-    }
-    const content = readFileSync(filePath, 'utf-8');
-    return extractMdSection(content, section, '验证契约');
-  }
-
-  // 内联定义，直接返回
-  return acceptance;
-}