@haaaiawd/loom 0.10.0 → 1.1.0

package/cli/help/workflow.md

@@ -1,100 +1,101 @@
-## LOOM 工作流
-
-从零到交付的完整流程。每个阶段有明确的产出和验收标准。
-
-## 第一步：诊断当前阶段
-
-\`\`\`bash
-loom guide
-\`\`\`
-
-guide 检测项目当前在哪个阶段，输出"你在阶段 X，下一步做 Y"。
-Agent 每完成一步都跑 guide 确认下一步。
-审计、预演、子代理探测时用 `loom guide --dry-run`，避免写 `.loom/heartbeat.json`。
-
-## AUTO 模式
-
-\`\`\`bash
-loom auto on      # 开启：Agent 自动连续执行，不等确认
-loom auto off     # 关闭：每步需要用户确认
-\`\`\`
-
-AUTO on 时 Agent 一路跑到底，跑完生成 preview 给人看。
-AUTO off 时每步停下等用户说继续。
-
-## 阶段 1：织造哲学（Weaver）
-
-\`\`\`bash
-loom activate weaver
-\`\`\`
-
-Weaver 根据项目特征从真实思想体系织造定制化哲学。产出：
-- PRODUCT_PHILOSOPHY.md — 产品价值观、反模式清单、决策取舍规则
-- ENGINEERING_CREED.md — 工程原则（按需）
-- DECISION_RUBRIC.md — 冲突时的优先级（按需）
-- PROJECT_BASELINE.md — 项目特定底线（按需）
-
-**验收**：哲学有北极星、有反模式、有决策标准。全是空话就重做。
-
-## 阶段 2：定义愿景（Visionary）
-
-\`\`\`bash
-loom activate visionary
-\`\`\`
-
-基于哲学定义产品愿景，为每个 Intent 写意图叙事（"为什么存在"）。产出：
-- 01_VISION.md — 北极星 + 意图叙事列表
-
-**验收**：叙事是"为什么"不是"做什么"。写成功能列表就重做。
-
-## 阶段 3：设计系统（Architect）
-
-\`\`\`bash
-loom activate architect
-\`\`\`
-
-基于愿景设计系统结构，绘制 Intent Map。产出：
-- 02_ARCHITECTURE.md — 系统设计
-- 04_INTENT_MAP.json — Intent 依赖图 + 验收契约 + 哲学锚点
-
-**验收**：验收契约具体到可验证，依赖无环，每个 Intent 有叙事引用。
-跑 \`loom intent validate\` 校验结构，跑 \`loom doctor\` 检查完整性。
-
-## 阶段 4：Intent Loop
-
-\`\`\`bash
-loom activate keeper    # Keeper 选 Intent、验证
-loom activate forge     # Forge 实现
-loom intent next        # 下一个可执行 Intent
-loom context            # 当前状态摘要
-\`\`\`
-
-每个 Intent 独立走一圈：选 → 实现 → 验证 → 闭合或修正。
-详细流程见 \`loom help loop\`。
-
-## 阶段 5：人类预览
-
-\`\`\`bash
-loom preview status
-loom preview
-loom preview --regen
-\`\`\`
-
-preview 是给人看的只读投影。Agent 应先跑 `loom preview status`：
-- `fresh=true` → 运行 `loom preview` 打开
-- `fresh=false` → 运行 `loom preview --regen`，按提示词重写 `loom-preview.html`，再打开
-- 用户明确要看旧版 → `loom preview --stale`
-
-详细规则见 `loom help preview`。
-
-## 阶段 6：版本演进（按需）
-
-当哲学前提/愿景北极星/架构边界变了，需要 Major 升级。
-详细流程见 \`loom help version\`。
-
-## 核心原则
-
-- **哲学是经线，意图是纬线** — 所有角色共享哲学锚点
-- **底线不可协商** — BASELINE 5 条 + 项目特定底线，角色激活时强制加载
-- **意图可回溯** — 每个 Intent 携带叙事，Keeper 独立验证忠实度
-- **文档开销不超过开发开销** — 小项目可以粗粒度，不必教条
+## LOOM 工作流
+
+## 0. 诊断
+
+```bash
+loom guide
+loom context
+```
+
+只读探测使用 `loom guide --dry-run`。
+
+## 1. Doctrine — Weaver
+
+```bash
+loom activate weaver
+loom philosophy check
+```
+
+输出项目长期判断、卓越标准、决策原则、创作空间、反模式与 Evidence Map。
+研究数量不设配额；只保留真实改变判断、能够追溯的证据。
+
+## 2. Intent — Visionary
+
+```bash
+loom activate visionary
+```
+
+输出产品目标、成功图景、非目标与 Intent narrative。Visionary 不写 acceptance、DAG 或架构。
+
+## 3. Capability Graph — Architect
+
+```bash
+loom activate architect
+loom capability graph
+loom capability frontier
+loom capability coverage
+```
+
+在写 Intent Map 前，Architect 先把愿景展开为项目问题面、能力缺口、风险与证据。图谱不是待办列表：高影响节点必须继续展开、形成项目化 Capability Brief、编译为 Intent，或带理由地延后/排除。每个 Intent 必须回链图谱；只有边界清楚且可独立验证的结果才进入 Intent Map。
+
+## 4. Contract — Architect
+
+```bash
+loom activate architect
+loom intent validate
+loom doctor
+```
+
+Architect 产出系统边界、Intent DAG、完成契约和可选质量契约，并声明
+`capability_needs` 与 `creative_scope`。
+
+完成契约定义 **Reliability Floor**：做到什么才算可靠完成。
+质量契约定义 **Distinctive Ceiling**：什么可观察差异让结果不止合格。
+
+## 5. Quality Engine — Forge 与 Keeper
+
+```bash
+loom intent next
+loom intent update <id> --status in_progress
+loom activate forge --intent <id>
+loom activate keeper --intent <id>
+```
+
+Forge 编译 Expertise Pack，在 Quality Arena 中实现与比较。
+Keeper 从当前磁盘事实和契约独立验证，不继承 Forge 的解释。
+
+无质量契约时，四个基础维度通过即可闭合。存在质量契约时，额外验证
+`quality_achievement`；声明相对提升时，在该维度中链接 Quality Proof：
+
+```bash
+loom verify pass <id> \
+  --summary "<具体证据>" \
+  --reproduction-command "<可复现命令>" \
+  --quality-proof "<基线、比较和稳定性证据的位置>"
+
+loom intent done <id>
+```
+
+复杂或混合判定使用 `loom verify write --json-file <path>`。
+
+## 6. Reflow
+
+验证偏离时，不要把所有问题都扔回 Forge：
+
+- Doctrine 不足 → Weaver
+- 产品目标错误 → Visionary
+- 问题面、能力缺口或 Intent 路由遗漏 → Architect 更新 Capability Graph
+- 契约、边界或依赖错误 → Architect
+- 专业判断或实现不足 → Forge
+- 证据不足 → Keeper 补证或 `pending_human`
+
+连续三次 `deviated` 自动升级为 `blocked`。所有当前 revision 和当前验证 epoch 的 Intent 都有最新 passed
+记录，且没有 `needs_review`、`loom doctor` 没有 fatal/high 风险时，本轮收敛。
+
+## 7. 演进
+
+- Patch：不改变 Intent 语义，验证后记录 changelog。
+- Minor：用 `loom intent add|revise` 创建 draft，经限定作用域的 Visionary/Architect 更新后 finalize。
+- Major：Doctrine、北极星或主要架构边界改变，使用 `loom version new`。
+
+原则只有一句：流程成本必须小于它降低的风险；质量声明必须小于等于它拥有的证据。

package/cli/src/activate.js

@@ -1,73 +1,349 @@
-// activate — 输出角色激活提示词
-// 把角色文件 + 哲学锚点 + 底线拼成激活上下文，供上层编排器使用。
-
-import { readFileSync, existsSync } from 'node:fs';
-import { join, resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { getLoomRoot } from './shared/paths.js';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-/** 合法角色名 */
-const VALID_ROLES = ['weaver', 'visionary', 'architect', 'forge', 'keeper'];
-
-/** 角色文件映射 */
-const ROLE_FILES = {
-  weaver: 'meta/PHILOSOPHY_WEAVER.md',
-  visionary: 'roles/visionary.md',
-  architect: 'roles/architect.md',
-  forge: 'roles/forge.md',
-  keeper: 'roles/keeper.md',
-};
-
-/**
- * 输出角色激活提示词。
- * @param {string} role — 角色名
- * @param {string} versionDir — .loom/v{N} 目录（可选，weaver 不需要）
- * @returns {string} 激活提示词
- */
-export function activateRole(role, versionDir) {
-  if (!VALID_ROLES.includes(role)) {
-    throw new Error(`未知角色: ${role}\n合法角色: ${VALID_ROLES.join(', ')}`);
-  }
-
-  const loomRoot = getLoomRoot();
-  const parts = [];
-
-  // 1. 角色文件
-  const roleFile = join(loomRoot, ROLE_FILES[role]);
-  if (!existsSync(roleFile)) {
-    throw new Error(`角色文件不存在: ${roleFile}`);
-  }
-  parts.push(readFileSync(roleFile, 'utf-8'));
-
-  // 2. BASELINE 摘要（不重复全文——全文见 meta/BASELINE.md）
-  //    5 条底线压缩成摘要，角色需要知道底线存在 + 一句话内容。
-  //    如果角色需要底线细节（如 Weaver 织造哲学时），自行 readFileSync 全文。
-  parts.push('\n---\n\n## 强制加载：BASELINE 摘要\n\n');
-  parts.push('> 完整底线见 `meta/BASELINE.md`。以下是 5 条底线的摘要——\n');
-  parts.push('> 角色激活时必须知道这些底线存在，违反任何一条必须立即停止。\n');
-  parts.push('> Philosophy Weaver 织造哲学时必须读取完整 BASELINE.md 作为硬约束输入。\n\n');
-  parts.push('| 编号 | 底线 | 一句话 |\n');
-  parts.push('|------|------|--------|\n');
-  parts.push('| B1 | 必须有结构设计 | 编码前必须有明确的目录结构 + 模块职责边界 + 显式依赖关系 |\n');
-  parts.push('| B2 | 禁止硬编码 | 密钥/配置/环境特定值/魔法数字不进代码，用环境变量或集中配置 |\n');
-  parts.push('| B3 | 接口契约必须显式 | API/CLI/配置/错误语义/跨系统协议必须有显式定义，变更可追溯 |\n');
-  parts.push('| B4 | 决策必须可追溯 | 影响架构/接口/技术栈/依赖的决策必须记录（ADR 或等效格式） |\n');
-  parts.push('| B5 | 意图必须可回溯 | 每个实现单元有意图叙事（"为什么存在"），可被 Keeper 引用对照 |\n');
-  parts.push('\n> 底线不可被哲学覆盖。如果织造的哲学与底线冲突，底线优先。\n');
-
-  // 3. 项目特定底线（如果有 versionDir）
-  if (versionDir) {
-    const projectBaseline = join(versionDir, '00_PHILOSOPHY/PROJECT_BASELINE.md');
-    if (existsSync(projectBaseline)) {
-      parts.push('\n---\n\n## 强制加载：项目特定底线\n\n' + readFileSync(projectBaseline, 'utf-8'));
-    }
-
-    // 4. 角色激活协议
-    const activationFile = join(loomRoot, 'meta/ROLE_ACTIVATION.md');
-    parts.push('\n---\n\n## 角色激活协议\n\n' + readFileSync(activationFile, 'utf-8'));
-  }
-
-  return parts.join('\n');
-}
+// activate — compile a role- and intent-scoped Context Pack.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getLoomRoot } from './shared/paths.js';
+import { getIntent, getNarrative } from './intent-map.js';
+import { getIntentDraft } from './intent-draft.js';
+import { getPhilosophy } from './philosophy.js';
+import { getVerificationContract } from './verify.js';
+import { extractMdSection } from './shared/md-utils.js';
+import { compileCapabilityInputs } from './capability-graph.js';
+import { getAtelierRecord } from './atelier.js';
+
+const VALID_ROLES = ['weaver', 'visionary', 'architect', 'forge', 'keeper'];
+
+const ROLE_FILES = {
+  weaver: 'meta/PHILOSOPHY_WEAVER.md',
+  visionary: 'roles/visionary.md',
+  architect: 'roles/architect.md',
+  forge: 'roles/forge.md',
+  keeper: 'roles/keeper.md',
+};
+
+const ROLE_PHILOSOPHY_FILES = {
+  visionary: ['PRODUCT_PHILOSOPHY.md', 'DECISION_RUBRIC.md'],
+  architect: ['ENGINEERING_CREED.md', 'DECISION_RUBRIC.md'],
+  forge: ['ENGINEERING_CREED.md'],
+  keeper: ['PRODUCT_PHILOSOPHY.md', 'DECISION_RUBRIC.md'],
+};
+
+const BASELINE_SUMMARY = [
+  '- B1：实质修改前理解真实结构，不创建平行体系。',
+  '- B2：秘密、环境值和可变配置不写死。',
+  '- B3：用户或系统可观察的行为具有显式契约。',
+  '- B4：重要且会影响未来的判断可追溯。',
+  '- B5：完成关联原始意图和当前 revision 证据；质量提升具有基线相对证据。',
+].join('\n');
+
+function section(title, body) {
+  const content = String(body || '').trim();
+  return `## ${title}\n\n${content || '无。'}`;
+}
+
+function readRole(role) {
+  const filePath = join(getLoomRoot(), ROLE_FILES[role]);
+  if (!existsSync(filePath)) throw new Error(`角色文件不存在: ${filePath}`);
+  return readFileSync(filePath, 'utf-8');
+}
+
+function getVerificationMethod(intent) {
+  return intent?.verification_method || intent?._optional?.verification_method || null;
+}
+
+function resolveContractReference(versionDir, value, label) {
+  if (!value) return null;
+  if (typeof value !== 'string') return JSON.stringify(value, null, 2);
+  const match = value.trim().match(/^(?:see\s+)?([^#]+)#([\w-]+)$/i);
+  if (!match) return value;
+  const [, file, anchor] = match;
+  if (file.includes('/') || file.includes('\\') || file !== '05_VERIFICATION.md') {
+    throw new Error(`${label}引用必须位于 05_VERIFICATION.md: ${value}`);
+  }
+  const filePath = join(versionDir, file);
+  if (!existsSync(filePath)) throw new Error(`${label}引用的文件不存在: ${filePath}`);
+  return extractMdSection(readFileSync(filePath, 'utf-8'), anchor, label);
+}
+
+function compileEnvelope(role, intentId) {
+  const scope = intentId ? `仅 ${intentId}` : '当前角色的项目阶段';
+  const lines = [
+    `- role: ${role}`,
+    `- scope: ${scope}`,
+    '- 本 Context Pack 不会清除现有会话记忆。',
+    '- system、developer 与用户指令优先；项目事实冲突时报告，不静默混用。',
+    '- 只在当前角色权限和明确作用域内行动。',
+  ];
+  if (role === 'keeper') {
+    lines.push('- Keeper 必须在新的 Agent thread 中运行；同一会话切换角色不构成独立验证。');
+    lines.push('- 无法获得独立上下文时降低声明，关键判断使用 pending_human。');
+  }
+  return lines.join('\n');
+}
+
+function compileObjective(role, versionDir, intentId) {
+  if (!intentId) {
+    return {
+      body: role === 'weaver'
+        ? '织造当前项目的 Project Doctrine。先读取真实项目与完整 BASELINE，不预写产品或架构。'
+        : `履行 ${role} 的当前项目阶段职责；未指定 Intent，不得自行选择并处理实现任务。`,
+      intent: null,
+      draft: null,
+      narrative: null,
+    };
+  }
+
+  if (role === 'visionary' || role === 'architect') {
+    const draft = getIntentDraft(versionDir, intentId);
+    const match = draft.narrative_ref.match(/^([^#]+)#([\w-]+)$/);
+    if (!match || match[1] !== '01_VISION.md') throw new Error(`draft narrative_ref 非法: ${draft.narrative_ref}`);
+    const narrative = extractMdSection(
+      readFileSync(join(versionDir, match[1]), 'utf-8'),
+      match[2],
+      'draft 意图叙事',
+    );
+    const visibleDraft = role === 'visionary'
+      ? {
+          id: draft.id,
+          revision: draft.revision,
+          title: draft.title,
+          narrative_ref: draft.narrative_ref,
+          depends_on: draft.depends_on,
+        }
+      : draft;
+    return {
+      body: [
+        '只处理下面这个 draft。不要修改官方 Intent Map，不要处理其他 Intent，不要自行 finalize。',
+        '',
+        '### Draft',
+        '',
+        '```json',
+        JSON.stringify(visibleDraft, null, 2),
+        '```',
+        '',
+        '### Narrative',
+        '',
+        narrative,
+      ].join('\n'),
+      intent: null,
+      draft,
+      narrative,
+    };
+  }
+
+  const intent = getIntent(versionDir, intentId);
+  if (['forge', 'keeper'].includes(role)) {
+    const unfinishedDependencies = intent.depends_on.filter((dependencyId) => getIntent(versionDir, dependencyId).status !== 'completed');
+    if (unfinishedDependencies.length) {
+      throw new Error(`Intent ${intentId} 的依赖尚未闭合: ${unfinishedDependencies.join(', ')}。不得通过 activate --intent 绕过执行顺序；先运行 loom intent next 或完成依赖 Intent。`);
+    }
+  }
+  const narrative = getNarrative(versionDir, intentId);
+  const objectiveView = {
+    id: intent.id,
+    revision: intent.revision,
+    title: intent.title,
+    status: intent.status,
+    narrative_ref: intent.narrative_ref,
+    depends_on: intent.depends_on,
+  };
+  return {
+    body: [
+      '只实现或验证下面这个官方 Intent。不得加载或顺便处理其他 Intent。',
+      '',
+      '### Intent',
+      '',
+      '```json',
+      JSON.stringify(objectiveView, null, 2),
+      '```',
+      '',
+      '### Narrative',
+      '',
+      narrative,
+    ].join('\n'),
+    intent,
+    draft: null,
+    narrative,
+  };
+}
+
+function compileInvariants(role, versionDir) {
+  const blocks = [];
+  const baselinePath = join(getLoomRoot(), 'meta/BASELINE.md');
+  blocks.push(role === 'weaver' ? readFileSync(baselinePath, 'utf-8') : BASELINE_SUMMARY);
+  if (versionDir) {
+    const projectBaseline = join(versionDir, '00_PHILOSOPHY', 'PROJECT_BASELINE.md');
+    if (existsSync(projectBaseline)) {
+      blocks.push(`### Project Baseline\n\n${readFileSync(projectBaseline, 'utf-8')}`);
+    }
+  }
+  return blocks.join('\n\n');
+}
+
+function compileContracts(role, versionDir, objective) {
+  const subject = objective.intent || objective.draft;
+  if (!subject || role === 'visionary') {
+    return role === 'visionary'
+      ? 'Visionary 只定义目标、非目标和 narrative；不要编写 acceptance 或架构。'
+      : '按当前角色 Output Contract 交付。';
+  }
+
+  const blocks = [];
+  if (subject.acceptance) {
+    const acceptance = objective.intent
+      ? getVerificationContract(versionDir, subject.id)
+      : resolveContractReference(versionDir, subject.acceptance, 'draft 完成契约');
+    blocks.push(`### Acceptance / Reliability Floor\n\n${acceptance}`);
+  }
+  if (subject.quality_contract) {
+    blocks.push(
+      `### Quality Contract / Distinctive Ceiling\n\n` +
+      resolveContractReference(versionDir, subject.quality_contract, '质量契约'),
+    );
+  }
+  const verificationMethod = getVerificationMethod(subject);
+  blocks.push(`### Verification Method\n\n${verificationMethod || '未声明：Keeper 使用适当的静态检查；需要运行时或人类判断却缺少入口时回流 Architect。'}`);
+  const continuity = subject.continuity_required
+    ? '此 Intent 已启用状态守恒门：通过前必须证明“旧状态 → 本轮操作 → 新状态”的完整序列中，未获明确授权删除或替换的既有价值、数据和可见结果仍被保留。'
+    : '默认不启用状态守恒门；若本 Intent 会变更既有用户数据、持久状态、迁移结果或既有工作流，Architect 必须把 continuity_required 设为 true，并在 acceptance 写出保留项与时序验证。';
+  blocks.push(
+    '### Completion Gate / Codex Goal Alignment\n\n' +
+    '将当前 Intent 视为本轮 Codex goal 的可闭合单元。goal 保持 active，直到结果达成、适用的状态守恒和可复现证据同时成立；goal/status 只是运行记录，不能替代验证证据。\n\n' +
+    continuity,
+  );
+  return blocks.join('\n\n');
+}
+
+function compileProjectJudgment(role, versionDir, objective) {
+  if (!versionDir || role === 'weaver') {
+    return role === 'weaver'
+      ? '从用户目标、仓库事实与决策相关证据建立 Project Doctrine。'
+      : '当前版本目录不可用。';
+  }
+
+  const philosophyDir = join(versionDir, '00_PHILOSOPHY');
+  const blocks = [];
+  const missing = [];
+  const anchors = (objective.intent || objective.draft)?.philosophy_anchors || [];
+
+  if (anchors.length > 0) {
+    for (const anchor of anchors) {
+      blocks.push(`### ${anchor}\n\n${getPhilosophy(philosophyDir, anchor)}`);
+    }
+  } else {
+    for (const file of ROLE_PHILOSOPHY_FILES[role] || []) {
+      const filePath = join(philosophyDir, file);
+      if (!existsSync(filePath)) {
+        missing.push(file);
+        continue;
+      }
+      blocks.push(`### ${file}\n\n${readFileSync(filePath, 'utf-8')}`);
+    }
+    if (missing.length) {
+      blocks.push(
+        `### Context Warning\n\n缺少: ${missing.join(', ')}。` +
+        '不要用通用偏好伪造项目判断；回流 Weaver 或向用户索取必要决定。',
+      );
+    }
+  }
+  return blocks.join('\n\n');
+}
+
+function compileExpertiseInputs(role, versionDir, objective) {
+  const subject = objective.intent || objective.draft;
+  if (!subject || !['architect', 'forge', 'keeper'].includes(role)) {
+    return '当前阶段不编译任务级 Expertise Pack。';
+  }
+  const needs = Array.isArray(subject.capability_needs) ? subject.capability_needs : [];
+  const qualityStrategy = subject.quality_strategy ?? 'adaptive';
+  const lines = [
+    `- capability_needs: ${needs.length ? needs.join(', ') : '未声明；按当前任务发现必要能力'}`,
+    `- creative_scope: ${subject.creative_scope || '未声明；遵循最小完整干预'}`,
+    `- quality_strategy: ${qualityStrategy}`,
+    '- Skill、工具和资产名称只代表可发现入口；实际检查并加载后才进入 Expertise Pack。',
+  ];
+  if (versionDir && objective.intent) {
+    const compiled = compileCapabilityInputs(versionDir, objective.intent.id);
+    if (!compiled.available) {
+      lines.push(`- Capability Graph: ${compiled.warnings.join(' ')}`);
+    } else if (compiled.nodes.length === 0) {
+      lines.push('- Capability Graph: 当前 Intent 没有回链节点；不得凭任务标题猜测能力，回流 Architect 补图谱或明确兼容原因。');
+    } else {
+      lines.push('- Capability Graph: 以下节点是本 Intent 的能力与风险输入：');
+      for (const node of compiled.nodes) {
+        lines.push(`  - ${node.id} [${node.kind}/${node.impact}] ${node.title}${node.question ? ` — ${node.question}` : ''}`);
+      }
+      for (const brief of compiled.briefs) {
+        lines.push(`\n### Capability Brief: ${brief.node_id}\n\n${brief.content.trim()}`);
+      }
+      for (const warning of compiled.warnings) lines.push(`- Capability Graph warning: ${warning}`);
+    }
+  }
+  if (role === 'keeper') {
+    lines.push('- 不继承 Forge Expertise Pack；按契约独立准备验证能力。');
+    if (qualityStrategy === 'atelier') {
+      const record = getAtelierRecord(versionDir, subject.id);
+      lines.push(
+        '- 当前 Intent 使用 Atelier：以下 Record 是创作证据入口，不是通过结论。',
+        `\n### Atelier Record\n\n\`\`\`json\n${JSON.stringify(record, null, 2)}\n\`\`\``,
+      );
+    }
+  }
+  if (role === 'forge' && qualityStrategy === 'atelier') {
+    const authorshipPath = join(getLoomRoot(), 'dimensions', 'AUTHORSHIP.md');
+    if (!existsSync(authorshipPath)) {
+      throw new Error(`Atelier 方法文件不存在: ${authorshipPath}`);
+    }
+    lines.push(
+      '- 当前 Intent 进入 Atelier Path：先冻结基线并形成 Authorial Stance，再生成机制不同的候选。',
+      `- Atelier Record: \`09_ATELIER/${subject.id}.json\`；候选必须绑定 stance_revision。`,
+      '- Author 只能修正局部创作假设；结构性发现提交 provenance-backed Capability Graph proposal，由 Architect 裁决。',
+      `\n### Authorship Method\n\n${readFileSync(authorshipPath, 'utf-8').trim()}`,
+    );
+  }
+  return lines.join('\n');
+}
+
+function compileWorkingFacts(versionDir, objective) {
+  if (!versionDir) return '检查当前仓库、用户输入和可用工具。';
+  const subject = objective.intent || objective.draft;
+  const refs = [
+    '- architecture: `.loom/.../02_ARCHITECTURE.md`（只读取与当前决定相关部分）',
+    '- capability_graph: 从 `07_CAPABILITY_GRAPH.json` 查询与当前 Intent 回链的能力、风险与 Brief；不能用会话记忆补全未路由分支。',
+    '- artifacts: 从真实工作区检查，不从会话记忆猜测。',
+  ];
+  const systemId = subject?._optional?.system_id || subject?.system_id;
+  if (systemId) refs.push(`- system_id: ${systemId}`);
+  if (subject?.quality_contract) refs.push('- baseline: 声明相对提升时，修改前证据必须在实现前保存。');
+  return refs.join('\n');
+}
+
+/**
+ * Compile a role-scoped Context Pack.
+ * @param {string} role
+ * @param {string | null} versionDir
+ * @param {string | null} intentId
+ */
+export function activateRole(role, versionDir, intentId = null) {
+  if (!VALID_ROLES.includes(role)) {
+    throw new Error(`未知角色: ${role}\n合法角色: ${VALID_ROLES.join(', ')}`);
+  }
+  if (intentId && !versionDir) throw new Error('--intent 需要当前 LOOM 版本');
+  if (intentId && !['visionary', 'architect', 'forge', 'keeper'].includes(role)) {
+    throw new Error(`角色 ${role} 不支持 --intent；draft 用 visionary/architect，官方 Intent 用 forge/keeper`);
+  }
+
+  const objective = compileObjective(role, versionDir, intentId);
+  const parts = [
+    '# LOOM Context Pack',
+    section('1. Execution Envelope', compileEnvelope(role, intentId)),
+    section('2. Active Objective', objective.body),
+    section('3. Hard Invariants', compileInvariants(role, versionDir)),
+    section('4. Success Contracts', compileContracts(role, versionDir, objective)),
+    section('5. Project Judgment', compileProjectJudgment(role, versionDir, objective)),
+    section('6. Expertise Inputs', compileExpertiseInputs(role, versionDir, objective)),
+    section('7. Working Facts', compileWorkingFacts(versionDir, objective)),
+    section('8. Role Contract / Output / Reflow / Stop', readRole(role)),
+  ];
+  return `${parts.join('\n\n---\n\n')}\n`;
+}