@haaaiawd/loom 0.9.0 → 1.0.0

package/cli/src/preview-prompt.md

@@ -42,8 +42,10 @@
 | `00_PHILOSOPHY/*.md` | 北极星、核心信念、反模式、决策原则 |
 | `01_VISION.md` | 北极星、问题空间、意图叙事、不做什么 |
 | `02_ARCHITECTURE.md` | 关键决策、trade-offs |
-| `04_INTENT_MAP.json` | 依赖关系、状态分布、验收契约 |
-| `verifications/*.json` | 验证时间轴、通过/偏离、证据 |
+| `04_INTENT_MAP.json` | 依赖关系、状态、完成/质量契约、专业能力需求 |
+| `verifications/*.json` | 验证时间轴、基础维度、按需的质量维度与 Quality Proof |
+| `06_CHANGELOG.json` | Patch 历史（唯一权威来源）；不要从生成的 Markdown 反推数据 |
+| `06_CHANGELOG.md` | JSON 的确定性只读投影，仅用于交叉检查 |
 
 文件还是模板（含 `<!-- LOOM_TEMPLATE -->` 标记）时，对应区域显示提示："等待 {角色} 填充"。
 
@@ -149,7 +151,7 @@ SVG 折线，横轴时间，纵轴剩余数。
 - **SVG 依赖图**：依赖链和阻塞点
 - **看板列**：按状态分组的 Intent 卡片（待执行/进行中/完成/阻塞）
 - **过滤面板**：状态过滤 + 模糊搜索（Intent 多时）
-- **点击下钻**：点击节点或卡片 → 侧边详情面板（叙事、验收契约、哲学锚点、验证历史）
+- **点击下钻**：点击节点或卡片 → 侧边详情面板（叙事、完成/质量契约、能力需求、验证历史）
 
 ### 哲学区域
 
@@ -178,13 +180,18 @@ SVG 折线，横轴时间，纵轴剩余数。
 - **关键决策对比表**：每个决策两列对比（选了什么 / 放弃了什么）
 - **trade-offs 清单**：每条一句话
 
-### 验证历史区域（如果有）
+### 验证历史区域（如果有）
 
 "质量怎么样"——拆解：
 
 - **时间轴**：每次验证一个节点，通过/偏离用颜色区分，点击看证据
 - **热力图网格**（Intent 多时）：Intent × 验证轮次矩阵，一眼看出哪个反复偏离
-- **偏离清单**：哪些 Intent 偏离了，证据是什么
+- **偏离清单**：哪些 Intent 偏离了，证据是什么
+
+### Patch 历史区域（如果有）
+
+- 从 `06_CHANGELOG.json` 展示 Patch 时间轴：摘要、原因、影响的 Intent、文件和已记录的验证结果
+- 明确区分 Patch 与 Intent 验证；`06_CHANGELOG.md` 是生成文件，不是另一份真相
 
 ### 底部
 
@@ -201,7 +208,7 @@ SVG 折线，横轴时间，纵轴剩余数。
 - 北极星 → 全页最大字号
 - 进度数字 → 大数字 + 颜色
 - Intent ID → 中等字号，等宽字体
-- 验收契约正文 → 小字，可展开才显示
+- 完成契约正文 → 小字，可展开才显示；质量契约与 Quality Proof 使用相邻但可区分的区域
 - 辅助说明 → 最小字，灰色
 
 不要所有文字一样大。人类靠大小判断重要性。

package/cli/src/preview.js

@@ -11,6 +11,7 @@ const SOURCE_FILE_NAMES = new Set([
   '02_ARCHITECTURE.md',
   '04_INTENT_MAP.json',
   '05_VERIFICATION.md',
+  '06_CHANGELOG.json',
   '06_CHANGELOG.md',
 ]);
 

package/cli/src/shared/intent-ref.js

@@ -0,0 +1,38 @@
+// intent-ref.js — Resolve current and version-qualified Intent read references.
+
+import { existsSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+
+export const VERSION_PATTERN = /^v\d+$/;
+export const INTENT_ID_PATTERN = /^INT-\d+$/;
+
+export function formatIntentRef(version, intentId) {
+  return `${version}:${intentId}`;
+}
+
+/** Resolve INT-003 against the current version or v1:INT-003 against .loom/v1. */
+export function resolveIntentRef(currentVersionDir, input) {
+  const currentVersion = basename(currentVersionDir);
+  if (!VERSION_PATTERN.test(currentVersion)) {
+    throw new Error(`无法从目录确定当前 LOOM 版本: ${currentVersionDir}`);
+  }
+
+  const parts = String(input || '').split(':');
+  if (parts.length > 2) throw new Error(`Intent 引用格式非法: ${input}`);
+  const qualified = parts.length === 2;
+  const version = qualified ? parts[0] : currentVersion;
+  const intentId = qualified ? parts[1] : parts[0];
+  if (!VERSION_PATTERN.test(version) || !INTENT_ID_PATTERN.test(intentId)) {
+    throw new Error(`Intent 引用格式非法: ${input}（应为 INT-003 或 v1:INT-003）`);
+  }
+
+  const versionDir = qualified ? join(dirname(currentVersionDir), version) : currentVersionDir;
+  if (!existsSync(versionDir)) throw new Error(`版本不存在: ${version}`);
+  return {
+    ref: formatIntentRef(version, intentId),
+    version,
+    intentId,
+    versionDir,
+    historical: version !== currentVersion,
+  };
+}

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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,32 @@
+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

@@ -3,56 +3,75 @@
 
 import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { extractMdSection, readJsonFile } from './shared/md-utils.js';
+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';
 
 /** 合法判定结果 */
 const VALID_VERDICTS = ['passed', 'deviated', 'blocked', 'pending_human'];
 
-/** 四个必须覆盖的验证维度 */
-const REQUIRED_DIMENSIONS = [
-  'intent_fidelity',
-  'philosophy_consistency',
-  'baseline_compliance',
-  'acceptance_achievement',
-];
+/** 每个 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} verificationsDir — verifications/ 目录路径
+ * @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 — 四个维度的验证结果
+ * @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(verificationsDir, record) {
-  const errors = [];
-  if (!record.intent_id) errors.push('缺少 intent_id');
+export function writeVerification(versionDir, verificationsDir, record) {
+  const errors = [];
+  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（四个维度结果）');
-  // dimensions 结构校验：每个维度必须是 { verdict, evidence } 对象
-  if (record.dimensions) {
-    for (const dim of REQUIRED_DIMENSIONS) {
-      const v = record.dimensions[dim];
-      if (v === undefined) {
-        errors.push(`dimensions.${dim} 缺失（四个维度必须全覆盖）`);
+  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);
+  // 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 (!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 {
@@ -66,12 +85,28 @@ export function writeVerification(verificationsDir, record) {
             errors.push(`dimensions.${dim}.evidence "${ev}" 是通用评价而非具体证据——必须写"对照了什么 + 在代码哪里看到/没看到"`);
           }
         }
-      }
-    }
-  }
-  if (errors.length > 0) {
-    throw new Error(`验证记录校验失败:\n  - ${errors.join('\n  - ')}`);
-  }
+      }
+    }
+  }
+  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 (errors.length > 0) {
+    throw new Error(`验证记录校验失败:\n  - ${errors.join('\n  - ')}`);
+  }
+
+  const intentRevision = getEffectiveIntentRevision(intent);
 
   const filePath = join(verificationsDir, `${record.intent_id}.json`);
 
@@ -92,24 +127,26 @@ export function writeVerification(verificationsDir, record) {
     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++;
-  }
+  // 计算轮次和连续 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,
+  data.records.push({
+    round,
+    intent_revision: intentRevision,
+    verification_epoch: getEffectiveVerificationEpoch(intent),
     verdict: record.verdict,
     timestamp: record.timestamp,
     summary: record.summary,
     dimensions: record.dimensions,
-    reproduction_command: record.reproduction_command,
-    deviation_detail: record.deviation_detail,
+    reproduction_command: record.reproduction_command,
+    deviation_detail: record.deviation_detail,
     reset_suggested: record.reset_suggested,
   });
 
@@ -126,29 +163,145 @@ export function writeVerification(verificationsDir, record) {
  * 读取某 Intent 的验证历史。
  * @returns {{ intent_id: string, records: array } | null}
  */
-export function getVerificationHistory(verificationsDir, intentId) {
+export function getVerificationHistory(verificationsDir, intentId) {
   const filePath = join(verificationsDir, `${intentId}.json`);
   if (!existsSync(filePath)) {
     return null;
   }
-  return readJsonFile(filePath, '验证记录');
-}
+  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。
+ * 内部用 summary 填充适用维度的 evidence，生成标准记录格式。
+ * @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,
+    deviation_detail: extras.deviation_detail || null,
+  });
+}
 
 /**
  * 返回所有待验证的 Intent（有实现产物但还没验证记录的）。
  * 需要传入 Intent Map 来判断哪些 Intent 是 in_progress。
  */
-export function getPendingVerifications(versionDir, verificationsDir) {
+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') {
-      const hasRecord = existsSync(join(verificationsDir, `${id}.json`));
-      if (!hasRecord) pending.push(id);
-    }
+    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);
+}
 
 /**
  * 列出所有验证记录文件。

package/cli/src/version.js

@@ -48,14 +48,15 @@ export function readCurrentPointer(loomRoot) {
  * @param {string} projectDir — 项目根目录
  * @returns {{ version: string, created: string[], skipped: string[] }}
  */
-export function newVersion(projectDir) {
-  const loomRoot = join(projectDir, '.loom');
-  const { versions } = listVersions(loomRoot);
+export function newVersion(projectDir) {
+  const loomRoot = join(projectDir, '.loom');
+  const { versions } = listVersions(loomRoot);
+  const parentVersion = readCurrentPointer(loomRoot);
   const nextNum = versions.length === 0
     ? 1
     : parseInt(versions[versions.length - 1].slice(1)) + 1;
   const nextV = `v${nextNum}`;
-  const result = createVersionStructure(projectDir, nextV);
+  const result = createVersionStructure(projectDir, nextV, parentVersion);
   // 自动切换为当前版本
   writeFileSync(join(loomRoot, 'current'), nextV, 'utf-8');
   result.created.push('.loom/current');