@openprd/cli 0.1.11 → 0.1.19

package/src/codex-hook-runner-template.mjs

@@ -80,6 +80,37 @@ function ensureHarness(root) {
   if (!fs.existsSync(eventsPath)) {
     fs.writeFileSync(eventsPath, '');
   }
+  const runtimePath = path.join(dir, 'runtime-environment.json');
+  if (!fs.existsSync(runtimePath)) {
+    writeJsonSync(runtimePath, {
+      version: 1,
+      active: {
+        activeClient: 'unknown',
+        surface: 'unknown',
+        executionMode: 'interactive',
+        confidence: 0,
+        sessionId: null,
+        turnId: null,
+        agentType: null,
+        model: null,
+        evidence: [],
+        observedCapabilities: [],
+      },
+      runtimeDetection: {
+        version: 1,
+        activeEvidencePriority: [
+          'hook-session-payload',
+          'explicit-launcher',
+          'sdk-or-headless-session',
+          'child-process-env',
+          'config-or-cli-probe',
+          'agent-self-report',
+        ],
+      },
+      platformCapabilityPacks: [],
+      updatedAt: null,
+    });
+  }
 }
 
 function readJsonSync(filePath, fallback) {
@@ -100,6 +131,98 @@ function appendEvent(root, event) {
   fs.appendFileSync(path.join(harnessDir(root), 'events.jsonl'), JSON.stringify({ at: now(), ...event }) + '\n');
 }
 
+function runtimeEnvironmentPath(root) {
+  return path.join(harnessDir(root), 'runtime-environment.json');
+}
+
+function compactString(value) {
+  const text = String(value ?? '').trim();
+  return text || null;
+}
+
+function runtimeEvidenceForPayload(eventName, payload) {
+  const evidence = ['hook.event_name'];
+  const addIfPresent = (key, label = key) => {
+    if (payload && payload[key] !== undefined && payload[key] !== null && String(payload[key]).trim() !== '') {
+      evidence.push(`hook.${label}`);
+    }
+  };
+  addIfPresent('session_id', 'session_id');
+  addIfPresent('sessionId', 'sessionId');
+  addIfPresent('transcript_path', 'transcript_path');
+  addIfPresent('transcriptPath', 'transcriptPath');
+  addIfPresent('cwd', 'cwd');
+  addIfPresent('model', 'model');
+  addIfPresent('turn_id', 'turn_id');
+  addIfPresent('turnId', 'turnId');
+  addIfPresent('agent_type', 'agent_type');
+  addIfPresent('agentType', 'agentType');
+  addIfPresent('tool_name', 'tool_name');
+  addIfPresent('toolName', 'toolName');
+  if (eventName) {
+    evidence.push(`event.${eventName}`);
+  }
+  return [...new Set(evidence)];
+}
+
+function observedCodexCapabilities(payload) {
+  const observed = ['codex-hooks'];
+  const tool = toolName(payload).toLowerCase();
+  const haystack = `${tool}\n${payloadText(payload)}`;
+  if (/\b(imagegen|image_gen|image-generation|image_generation)\b/i.test(haystack)) {
+    observed.push('native-image-generation');
+  }
+  if (/\b(computer-use|computer_use|browser|chrome)\b/i.test(haystack)) {
+    observed.push('computer-use');
+  }
+  return [...new Set(observed)];
+}
+
+function recordRuntimeEnvironment(root, eventName, payload, sessionId) {
+  ensureHarness(root);
+  const current = readJsonSync(runtimeEnvironmentPath(root), {});
+  const executionSignals = detectExecutionSignals(eventName, payload);
+  const evidence = [...new Set([
+    ...runtimeEvidenceForPayload(eventName, payload),
+    ...executionSignals.evidence,
+    ...executionSignals.optInEvidence,
+  ])];
+  const active = {
+    activeClient: 'codex',
+    surface: 'codex-hook',
+    executionMode: executionSignals.executionMode,
+    confidence: evidence.some((item) => item === 'hook.session_id' || item === 'hook.sessionId' || item === 'hook.transcript_path' || item === 'hook.transcriptPath') ? 0.95 : 0.9,
+    sessionId: sessionId ?? null,
+    turnId: compactString(payload?.turn_id ?? payload?.turnId),
+    agentType: compactString(payload?.agent_type ?? payload?.agentType),
+    model: compactString(payload?.model),
+    evidence,
+    observedCapabilities: observedCodexCapabilities(payload),
+  };
+  const entry = {
+    version: 1,
+    ...current,
+    active,
+    lastEventName: eventName,
+    updatedAt: now(),
+    recentObservations: [
+      ...(Array.isArray(current.recentObservations) ? current.recentObservations : []),
+      {
+        at: now(),
+        eventName,
+        activeClient: active.activeClient,
+        surface: active.surface,
+        executionMode: active.executionMode,
+        sessionId: active.sessionId,
+        evidence: active.evidence,
+        observedCapabilities: active.observedCapabilities,
+      },
+    ].slice(-20),
+  };
+  writeJsonSync(runtimeEnvironmentPath(root), entry);
+  return entry;
+}
+
 function turnStatePath(root) {
   return path.join(harnessDir(root), 'turn-state.json');
 }
@@ -117,6 +240,7 @@ function defaultTurnState() {
     startedAt: null,
     updatedAt: null,
     touchedFiles: [],
+    gateBlockCounts: {},
     reviewSignals: [],
     runtimeEvents: [],
     timeline: [],
@@ -132,6 +256,28 @@ function readTurnState(root) {
   };
 }
 
+// 流程型门禁（需求入口、外部证据、设计预检、Patch Mode）在同一轮内
+// 反复阻断超过该次数时自动熔断降级为提醒放行，避免 Agent 把整轮消耗在
+// 与门禁系统搏斗上；安全型门禁（云端写入、业务写死、secrets）不参与熔断。
+const PROCESS_GATE_FUSE_LIMIT = 3;
+
+function bumpProcessGateBlockCount(root, gateKind) {
+  const turnState = readTurnState(root);
+  const counts = { ...(turnState.gateBlockCounts || {}) };
+  counts[gateKind] = Number(counts[gateKind] || 0) + 1;
+  writeTurnState(root, { ...turnState, gateBlockCounts: counts });
+  return counts[gateKind];
+}
+
+function processGateFuseMessage(gateKind, streak, originalReason) {
+  return [
+    `OpenPrd 门禁熔断: ${gateKind} 门禁本轮已阻断 ${streak - 1} 次，本次自动降级为提醒放行。`,
+    '继续按用户已确认的方向完成实际工作，不要再花动作调试门禁本身，也不要再向用户重复索取同一轮确认。',
+    '收口时补齐这个门禁原本要求的产物（例如需求确认稿、外部证据或设计合同），并在最终回复里说明本轮发生过门禁熔断降级。',
+    originalReason ? `原始门禁提示（供收口对照）:\n${originalReason}` : null,
+  ].filter(Boolean).join('\n');
+}
+
 function writeTurnState(root, next) {
   writeJsonSync(turnStatePath(root), {
     ...defaultTurnState(),
@@ -200,6 +346,7 @@ function beginTurnReview(root, baseEvent, prompt) {
     status: 'needs-attention',
     startedAt: now(),
     touchedFiles: [],
+    gateBlockCounts: {},
     reviewSignals: [],
     runtimeEvents: promptPreview ? [{
       eventName: 'user-prompt',
@@ -231,6 +378,96 @@ function recordTouchedFiles(root, payload) {
   return touchedFiles;
 }
 
+function appendTurnReviewSignals(root, signals) {
+  const normalizedSignals = (Array.isArray(signals) ? signals : [signals])
+    .filter(Boolean)
+    .map((signal) => ({
+      at: now(),
+      ...signal,
+    }));
+  if (normalizedSignals.length === 0) {
+    return [];
+  }
+  const state = readTurnState(root);
+  const existing = Array.isArray(state.reviewSignals) ? state.reviewSignals : [];
+  writeTurnState(root, {
+    ...state,
+    reviewSignals: [...existing, ...normalizedSignals].slice(-80),
+    timeline: [
+      ...(Array.isArray(state.timeline) ? state.timeline : []),
+      ...normalizedSignals.map((signal) => ({
+        event: signal.kind,
+        status: 'pass',
+        message: signal.message ?? signal.preview ?? signal.kind,
+        at: signal.at,
+      })),
+    ].slice(-120),
+  });
+  return normalizedSignals;
+}
+
+function detectVisualEvidenceSignals(payload) {
+  const tool = toolName(payload).toLowerCase();
+  const command = commandText(payload);
+  const text = payloadText(payload);
+  const haystack = `${tool}\n${command}\n${text}`;
+  const signals = [];
+  if (/openprd\s+visual-prepare\b/i.test(haystack)) {
+    signals.push({
+      kind: 'visual-reference-prepared',
+      message: 'visual-prepare reference-set/contact sheet observed',
+      preview: preview(command || text, 180),
+    });
+  }
+  if (/openprd\s+visual-compare\b/i.test(haystack)
+    || /\.openprd\/harness\/visual-reviews\/(?:visual-|reference-sets\/)/i.test(haystack)
+    || /visual-(?:compare|before-after|focus-board|parallel-board|verification-board|alignment-board|centering-board)/i.test(haystack)
+    || /\b(?:reference-actual|before-after|focus-board|parallel-board|verification-board|alignment-board|centering-board|center-board)\b/i.test(haystack)) {
+    signals.push({
+      kind: 'visual-review-artifact',
+      message: 'visual-compare artifact observed',
+      preview: preview(command || text, 180),
+    });
+  }
+  if (/\bverification-board\b|截图实测证据板|visual-verification-board/i.test(haystack)) {
+    signals.push({
+      kind: 'visual-verification-board',
+      message: 'verification-board artifact observed',
+      preview: preview(command || text, 180),
+    });
+  }
+  if (/\balignment-board\b|对齐辅助线证据板|visual-alignment-board/i.test(haystack)) {
+    signals.push({
+      kind: 'visual-alignment-board',
+      message: 'alignment-board artifact observed',
+      preview: preview(command || text, 180),
+    });
+  }
+  if (/\b(?:centering-board|center-board)\b|内部居中证据板|visual-centering-board/i.test(haystack)) {
+    signals.push({
+      kind: 'visual-centering-board',
+      message: 'centering-board artifact observed',
+      preview: preview(command || text, 180),
+    });
+  }
+  const screenshotTool = /(?:^|[_-])(?:screenshot|view_image)(?:$|[_-])/i.test(tool)
+    || /(?:computer|browser|playwright|page|mp|miniprogram|weapp).*screenshot/i.test(tool);
+  const screenshotCommand = /\bscreencapture\b|page\.screenshot|\.screenshot\(|mp_screenshot|browser.*screenshot|computer.*screenshot|playwright.*screenshot/i.test(command);
+  const screenshotText = /(?:普通截图|实测截图|运行态截图|Computer\s*实测|Browser\s*实测|截图证据|screenshot captured|captured screenshot)/i.test(text);
+  if ((screenshotTool || screenshotCommand || screenshotText) && !/openprd\s+visual-compare\b/i.test(haystack)) {
+    signals.push({
+      kind: 'visual-raw-screenshot',
+      message: 'raw screenshot or Computer/Browser visual evidence observed',
+      preview: preview(command || text || tool, 180),
+    });
+  }
+  return signals;
+}
+
+function recordVisualEvidenceSignals(root, payload) {
+  return appendTurnReviewSignals(root, detectVisualEvidenceSignals(payload));
+}
+
 function updateHookState(root, event) {
   ensureHarness(root);
   const statePath = path.join(harnessDir(root), 'hook-state.json');
@@ -248,6 +485,9 @@ function updateHookState(root, event) {
   if (event.fingerprint) {
     state.recentFingerprints[event.fingerprint] = Date.now();
   }
+  if (event.runtimeEnvironment) {
+    state.runtimeEnvironment = event.runtimeEnvironment;
+  }
   for (const [fingerprint, seenAt] of Object.entries(state.recentFingerprints)) {
     if (Date.now() - Number(seenAt) > 300000) {
       delete state.recentFingerprints[fingerprint];
@@ -390,6 +630,203 @@ function sessionRegistryPath() {
   return path.join(openprdHome(), 'registry', 'sessions.jsonl');
 }
 
+function truthyFlag(value) {
+  return /^(1|true|yes|on)$/i.test(String(value ?? '').trim());
+}
+
+function normalizedMode(value) {
+  return String(value ?? '').trim().toLowerCase();
+}
+
+function compactPayloadField(payload, keys) {
+  for (const key of keys) {
+    const value = payload?.[key];
+    if (value === undefined || value === null || value === false) {
+      continue;
+    }
+    const text = typeof value === 'object' ? JSON.stringify(value) : String(value);
+    if (text.trim()) {
+      return { key, value: text.trim() };
+    }
+  }
+  return null;
+}
+
+function automationPromptHeader(prompt) {
+  const header = String(prompt || '').split(/\r?\n/).slice(0, 12).join('\n');
+  if (/^\s*Automation\s*:/im.test(header) && /^\s*Automation\s+(ID|memory)\s*:/im.test(header)) {
+    return 'prompt.automation-header';
+  }
+  if (/^\s*(Scheduled|Cron|Unattended)\s+(task|automation)\s*:/im.test(header)) {
+    return 'prompt.scheduled-header';
+  }
+  return null;
+}
+
+function explicitOpenPrdOptInEvidence(payload) {
+  const evidence = [];
+  const mode = normalizedMode(process.env.OPENPRD_EXECUTION_MODE);
+  if (['openprd', 'openprd-maintenance', 'maintenance'].includes(mode)) {
+    evidence.push(`env.OPENPRD_EXECUTION_MODE=${mode}`);
+  }
+  if (truthyFlag(process.env.OPENPRD_AUTOMATION_OPT_IN) || truthyFlag(process.env.OPENPRD_ENABLE_IN_AUTOMATION)) {
+    evidence.push('env.OPENPRD_AUTOMATION_OPT_IN');
+  }
+  const explicitField = compactPayloadField(payload, [
+    'openprd_automation_opt_in',
+    'openprdAutomationOptIn',
+    'openprd_opt_in',
+    'openprdOptIn',
+    'enable_openprd',
+    'enableOpenPrd',
+  ]);
+  if (explicitField) {
+    evidence.push(`payload.${explicitField.key}`);
+  }
+  const text = `${promptText(payload)}\n${payloadText(payload)}`;
+  const negative = /(不要|不需要|无需|禁止|别|不是|非|不要执行|不要调用|do\s+not|don't|never|without|no|not)\s+.{0,24}\bopen\s*prd\b/i
+    .test(text)
+    || /(不要|不需要|无需|禁止|别|不是|非).{0,24}OpenPrd/i.test(text);
+  if (!negative && /(OpenPrd\s*(维护任务|maintenance|maintain|opt[- ]?in)|显式启用\s*OpenPrd|启用\s*OpenPrd|使用\s*OpenPrd|运行\s*OpenPrd|enable\s+OpenPrd|use\s+OpenPrd|openprd-maintenance)/i.test(text)) {
+    evidence.push('prompt.openprd-opt-in');
+  }
+  return [...new Set(evidence)];
+}
+
+function detectExecutionSignals(eventName, payload) {
+  const evidence = [];
+  const mode = normalizedMode(process.env.OPENPRD_EXECUTION_MODE);
+  if (['automation', 'cron', 'scheduled', 'headless', 'unattended'].includes(mode)) {
+    evidence.push(`env.OPENPRD_EXECUTION_MODE=${mode}`);
+  }
+  if (truthyFlag(process.env.OPENPRD_AUTOMATION)) {
+    evidence.push('env.OPENPRD_AUTOMATION');
+  }
+  if (compactString(process.env.CODEX_AUTOMATION_ID)) {
+    evidence.push('env.CODEX_AUTOMATION_ID');
+  }
+  if (truthyFlag(process.env.CLAUDE_CODE_HEADLESS)) {
+    evidence.push('env.CLAUDE_CODE_HEADLESS');
+  }
+  const field = compactPayloadField(payload, [
+    'automation_id',
+    'automationId',
+    'automation_name',
+    'automationName',
+    'automation',
+    'scheduled_task',
+    'scheduledTask',
+    'cron',
+    'rrule',
+    'headless',
+    'unattended',
+    'is_automation',
+    'isAutomation',
+  ]);
+  if (field) {
+    evidence.push(`payload.${field.key}`);
+  }
+  const runMode = compactPayloadField(payload, [
+    'run_kind',
+    'runKind',
+    'execution_mode',
+    'executionMode',
+    'surface',
+    'agent_surface',
+    'agentSurface',
+  ]);
+  if (runMode && /(automation|cron|scheduled|headless|unattended)/i.test(runMode.value)) {
+    evidence.push(`payload.${runMode.key}=${runMode.value}`);
+  }
+  const agentType = compactString(payload?.agent_type ?? payload?.agentType);
+  if (agentType && /(automation|cron|scheduled|headless|unattended)/i.test(agentType)) {
+    evidence.push(`payload.agentType=${agentType}`);
+  }
+  const promptHeader = automationPromptHeader(promptText(payload));
+  if (promptHeader) {
+    evidence.push(promptHeader);
+  }
+  const transcript = compactString(payload?.transcript_path ?? payload?.transcriptPath);
+  if (transcript && /(?:^|[/-])(automation|automations|cron|scheduled|headless)(?:[/-]|$)/i.test(transcript)) {
+    evidence.push('payload.transcript_path.automation');
+  }
+  const optInEvidence = explicitOpenPrdOptInEvidence(payload);
+  return {
+    eventName,
+    isAutomation: evidence.length > 0,
+    explicitOpenPrdOptIn: optInEvidence.length > 0,
+    evidence: [...new Set(evidence)],
+    optInEvidence,
+    executionMode: optInEvidence.length > 0
+      ? 'automation-openprd-opt-in'
+      : evidence.length > 0
+        ? 'automation'
+        : 'interactive',
+  };
+}
+
+function latestSessionRegistryEntry(root, sessionId) {
+  if (!sessionId) {
+    return null;
+  }
+  const filePath = sessionRegistryPath();
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  const workspaceRoot = path.resolve(root);
+  let latest = null;
+  for (const line of fs.readFileSync(filePath, 'utf8').split(/\r?\n/)) {
+    if (!line.trim()) {
+      continue;
+    }
+    try {
+      const entry = JSON.parse(line);
+      if (entry?.sessionId !== sessionId) {
+        continue;
+      }
+      const entryRoot = entry?.workspaceRoot ? path.resolve(String(entry.workspaceRoot)) : null;
+      if (entryRoot && entryRoot !== workspaceRoot) {
+        continue;
+      }
+      latest = entry;
+    } catch {}
+  }
+  return latest;
+}
+
+function rememberAutomationMode(root, sessionId, payload, signals, laneKind) {
+  if (!sessionId) {
+    return null;
+  }
+  return writeSessionRegistryEntry(root, sessionId, {
+    laneKind,
+    tool: 'openprd-hook',
+    promptPreview: preview(promptText(payload) || payloadText(payload), 500),
+    gateActive: false,
+    gateStatus: laneKind === 'automation' ? 'automation-safe-mode' : 'openprd-opt-in',
+    title: laneKind === 'automation'
+      ? 'Unattended automation bypassed OpenPrd'
+      : 'Unattended automation explicitly enabled OpenPrd',
+    executionEvidence: signals.evidence,
+    optInEvidence: signals.optInEvidence,
+  });
+}
+
+function automationBypassDecision(root, eventName, payload, sessionId) {
+  const signals = detectExecutionSignals(eventName, payload);
+  if (signals.explicitOpenPrdOptIn) {
+    return { bypass: false, optIn: true, remembered: false, signals };
+  }
+  if (signals.isAutomation) {
+    return { bypass: true, optIn: false, remembered: false, signals };
+  }
+  const remembered = eventName === 'UserPromptSubmit' ? null : latestSessionRegistryEntry(root, sessionId);
+  if (remembered?.laneKind === 'automation' && remembered?.gateStatus === 'automation-safe-mode') {
+    return { bypass: true, optIn: false, remembered: true, signals };
+  }
+  return { bypass: false, optIn: false, remembered: false, signals };
+}
+
 function sessionStatePath(root, sessionId = null) {
   if (!sessionId) {
     return null;
@@ -579,7 +1016,28 @@ function readRequirementLaneReview(root, sessionId = null) {
       artifact: binding.reviewPath || binding.stableReviewArtifact || binding.activeReviewPath || binding.reviewArtifact || null,
     };
   }
-  return readCurrentPrdReview(root);
+  const globalReview = readCurrentPrdReview(root);
+  if (sessionId && globalReview.versionId) {
+    // 全局 current.json 里的确认稿可能属于另一个会话的历史需求。
+    // 如果 lane 归属明确不是当前会话，就按“本轮还没有确认稿”自愈，
+    // 避免把其他需求的旧稿卡成本轮的待确认死锁。
+    const laneSessionId = String(readJsonSync(currentStatePath(root), {})?.laneSessionId || '').trim() || null;
+    if (laneSessionId && laneSessionId !== sessionId) {
+      return {
+        versionId: null,
+        digest: null,
+        workUnitId: null,
+        status: 'missing',
+        artifact: null,
+        staleReview: {
+          versionId: globalReview.versionId,
+          workUnitId: globalReview.workUnitId,
+          laneSessionId,
+        },
+      };
+    }
+  }
+  return globalReview;
 }
 
 function reviewCommandMatchesReview(command, review) {
@@ -873,9 +1331,8 @@ function isPatchModeFocusAttempt(root, payload, gate) {
 
 function findChangeDir(root, changeId) {
   const candidates = [
-    path.join(root, 'openprd', 'changes', changeId),
-    path.join(root, 'openspec', 'changes', changeId),
-    path.join(root, 'openprd', 'archive', 'changes', changeId),
+    path.join(root, '.openprd', 'changes', changeId),
+    path.join(root, '.openprd', 'archive', 'changes', changeId),
   ];
   return candidates.find((candidate) => fs.existsSync(candidate)) || candidates[0];
 }
@@ -1186,6 +1643,54 @@ function renderRunContextText(result) {
   return lines.filter(Boolean).join('\n');
 }
 
+function inferLearningGenre(text) {
+  const value = String(text || '');
+  if (/仙侠|修仙|玄幻/.test(value)) {
+    return 'xianxia';
+  }
+  if (/武侠/.test(value)) {
+    return 'wuxia';
+  }
+  if (/童话|寓言/.test(value)) {
+    return 'fairy-tale';
+  }
+  if (/科幻|赛博|cyberpunk|sci[-\s]?fi/i.test(value)) {
+    return 'sci-fi';
+  }
+  if (/互联网产品|产品经理|PM/i.test(value)) {
+    return 'internet-product';
+  }
+  return null;
+}
+
+function detectLearningMaterialIntent(prompt) {
+  const text = stripMarkdown(prompt).trim();
+  if (!text) {
+    return { requested: false, genre: null, reason: null };
+  }
+  const explicitChatOnly = /(只要|仅要|仅需|就|直接).{0,16}(在对话里|回复|回答|写一段|一段文字|短文|纯文本|普通文本)|不要.{0,18}(文件|阅读器|学习包|HTML|html|openprd)/i.test(text);
+  const durableReaderSignal = /(可长期阅读|长期阅读|可回看|阅读器|reader|电子书|学习包|归档)/i.test(text);
+  if (explicitChatOnly && !durableReaderSignal) {
+    return { requested: false, genre: null, reason: 'chat-only-requested' };
+  }
+
+  // This is an intent-shape detector, not a closed keyword table. The hook
+  // looks for a requested learning deliverable, its durability/teaching goal,
+  // and whether the expected output wants reader-like structure.
+  const deliveryAction = /(生成|整理|产出|做一份|做一套|做个|做一个|创建|写一份|准备|沉淀|归档|转成|转换成|变成|输出|构建|给我)/i.test(text);
+  const learningGoal = /(学习|教学|培训|复盘|教程|讲义|教材|课程|知识沉淀|经验沉淀|可回看|可复用|长期阅读|新人入门|onboarding)/i.test(text);
+  const readerShape = /(学习(材料|资料|包|读本|文档)|复盘材料|教学材料|培训材料|教程|讲义|教材|课程|读本|电子书|阅读器|reader|ebook|章节|目录|证据锚点|图文讲解|检索练习|工作示例|可长期阅读|长期阅读)/i.test(text);
+  const workToLearningArtifact = /(把|将|基于|围绕).{0,48}(工作|任务|过程|对话|会话|修复|需求|项目|实现|经验|记录|材料).{0,32}(转成|转换成|整理成|沉淀成|归档成|做成|写成).{0,40}(学习|复盘|教学|教程|讲义|材料|读本|可回看|可复用|长期阅读)/i.test(text);
+  const requested = workToLearningArtifact
+    || (readerShape && (deliveryAction || learningGoal || durableReaderSignal))
+    || (learningGoal && durableReaderSignal);
+  return {
+    requested,
+    genre: requested ? inferLearningGenre(text) : null,
+    reason: workToLearningArtifact ? 'work-to-learning-artifact' : (readerShape ? 'reader-shaped-learning-artifact' : (requested ? 'durable-learning-goal' : null)),
+  };
+}
+
 function analyzePromptIntent(prompt) {
   const text = String(prompt || '').trim();
   const normalized = text.toLowerCase();
@@ -1267,7 +1772,7 @@ function analyzePromptIntent(prompt) {
     /copy/i,
   ];
   const simpleConcretePatterns = [
-    /按钮|文案|颜色|圆角|位置|间距|字号|图标|标题|空格|标点|label|copy/i,
+    /按钮|文案|颜色|圆角|位置|间距|留白|边距|宽度|高度|卡片|字号|图标|标题|空格|标点|对齐|密度|label|copy|padding|margin|spacing|gap/i,
     /从.+(改到|移到|移动到|换到|变成|改成|改为).+/,
   ];
   const l2StructuralScopePatterns = [
@@ -1370,8 +1875,10 @@ function analyzePromptIntent(prompt) {
   ];
   const reviewConfirmPatterns = [
     /认可方案/,
-    /确认(?:当前|这个|这版|该)?(?:PRD|评审稿|评审页|review|需求稿|版本)/i,
-    /(?:PRD|评审稿|评审页|review|需求稿|版本).{0,12}(确认|通过|没问题|认可|可以)/i,
+    // 容忍“确认 v0276 评审稿”这类中间插版本号/空格的自然语言确认。
+    /确认(?:当前|这个|这版|该)?\s*(?:[vV]\d+\s*(?:的)?)?(?:PRD|评审稿|评审页|review|需求稿|版本)/i,
+    /确认\s*[vV]\d+/,
+    /(?:PRD|评审稿|评审页|review|需求稿|版本)\s*(?:[vV]\d+)?.{0,12}(确认|通过|没问题|认可|可以)/i,
     /按这版(?:PRD|评审|需求稿)/i,
   ];
   const reviewNeedsRevisionPatterns = [
@@ -1403,7 +1910,8 @@ function analyzePromptIntent(prompt) {
     || /失败.{0,20}(原因|根因|排查|定位|修|修复|处理|解决)|(?:原因|根因|排查|定位).{0,20}失败/.test(text);
   const tinyEdit = tinyEditPatterns.some((pattern) => pattern.test(text));
   const crossSystemRiskMatched = crossSystemRiskPatterns.some((pattern) => pattern.test(text));
-  const localUiScopeMatched = /(按钮|文案|颜色|圆角|位置|间距|字号|图标|标题|空格|标点|label|copy|toast|placeholder|样式|页面|界面|布局|信息架构|导航|列表|详情页|设置页)/i.test(text);
+  const localUiScopeMatched = hasLightweightUiVisualSignal(text)
+    || /(样式|页面|界面|布局|信息架构|导航|列表|详情页|设置页)/i.test(text);
   const reviewContinuationRequested = reviewContinuationPatterns.some((pattern) => pattern.test(text));
   const explicitExecution = internalOpenPrdExecution
     || continuationVerbMatched
@@ -1414,6 +1922,7 @@ function analyzePromptIntent(prompt) {
   const noReviewRequested = noReviewRequestedPatterns.some((pattern) => pattern.test(text));
   const noConfirmationRequested = noConfirmationRequestedPatterns.some((pattern) => pattern.test(text));
   const reviewDecision = promptReviewCommand?.mark
+    ?? (reviewContinuationRequested ? 'confirmed' : null)
     ?? (reviewConfirmPatterns.some((pattern) => pattern.test(text)) ? 'confirmed' : null)
     ?? (reviewNeedsRevisionPatterns.some((pattern) => pattern.test(text)) ? 'needs-revision' : null);
   const confirmation = implementationConfirmation || Boolean(reviewDecision);
@@ -1424,6 +1933,10 @@ function analyzePromptIntent(prompt) {
   const visualMockupRequest = imageGenerationTerms.test(text)
     && imageGenerationAction.test(text)
     && !codeVisualArtifactRequested;
+  const learningMaterialIntent = detectLearningMaterialIntent(text);
+  const learningMaterialRequest = learningMaterialIntent.requested;
+  const canvasCollaborationRequest = /(画布|canvas|excalidraw)/i.test(text)
+    && /(标注|批注|协同|改图|回填|贴到画布|放到画布|插入画布|插到画布|画布评审|画布反馈|一起看|openprd\s*canvas|annotation)/i.test(text);
   const visualReview = /效果图|实现截图|视觉对比|视觉评审|对标效果图|复刻|不一致|好丑|没对齐|对不上|不像/i.test(text);
   const directBugfixExecution = explicitExecution && bugfixOrDiagnostic;
   const newFeatureVerbMatched = /(新增|增加|新建)/.test(text);
@@ -1441,19 +1954,22 @@ function analyzePromptIntent(prompt) {
   const requirementSignalMatched = requirementRoutingSignalsStrong.some((pattern) => pattern.test(text))
     || (requirementRoutingSignalsWeak.some((pattern) => pattern.test(text))
       && requirementChangeIntentSignals.some((pattern) => pattern.test(text)));
-  const l2FeatureExpansionMatched = !localUiScopeMatched
-    && (
-      (capabilityCreationMatched && (strategicL2ScopeMatched || structuralExpansionMatched))
-      || (newFeatureVerbMatched && text.length > 18)
-    );
+  const l2FeatureExpansionMatched = (capabilityCreationMatched && (strategicL2ScopeMatched || structuralExpansionMatched))
+    || (!localUiScopeMatched && newFeatureVerbMatched && text.length > 18);
   const l2PlanningRequestMatched = !readOnly
     && featurePlanningMatched
     && requirementChangeIntentSignals.some((pattern) => pattern.test(text))
     && (strategicL2ScopeMatched || structuralExpansionMatched);
   const l1OptimizationMatched = l1OptimizationPatterns.some((pattern) => pattern.test(text))
-    && /(页面|界面|视觉|样式|布局|信息架构|交互|体验|流程|入口|导航|表单|设置页|列表|详情页)/i.test(text);
+    && (hasLightweightUiVisualSignal(text) || /(页面|界面|视觉|样式|布局|信息架构|交互|体验|流程|入口|导航|表单|设置页|列表|详情页)/i.test(text));
+  // 改现有脚本、CLI、发布/构建流程、参数或文档这类既有资产优化，
+  // 不应仅因出现“新增/增加/补一个”动词就升级成 L2 重流程；
+  // 只有同时命中真正的结构/战略扩张信号时才保留 L2。
+  const existingAssetOptimizationMatched = /(脚本|script|发布|上传|部署|构建|打包|导出|同步|清理|CLI|命令行|命令|参数|选项|flag|配置文件|文档|README)/i.test(text)
+    && /(补|加|增加|支持|筛选|过滤|优化|调整|收敛|清理|改成|改为|升级|更新|修改|梳理)/.test(text)
+    && !/(新产品|新模块|新平台|新系统|新页面|新界面|新客户端|全新|从零|从\s*0|重写整个|重构整个)/i.test(text);
   const l0AdjustmentMatched = l0AdjustmentPatterns.some((pattern) => pattern.test(text))
-    && /(按钮|文案|颜色|圆角|位置|间距|字号|图标|标题|空格|标点|label|copy|toast|placeholder|样式|一处)/i.test(text);
+    && (hasLightweightUiVisualSignal(text) || /(样式|一处)/i.test(text));
   const publicRepoResearchRequest = githubRepoPattern.test(text)
     && /(github|仓库|repo|项目|参考|对标|复刻|review|学习|架构|模块|流程|构建|测试|扩展点)/i.test(text);
   const externalTechResearchRequest = /(第三方|library|framework|sdk|api|mcp|cli|依赖|包|版本|迁移|弃用|官方文档|参数|返回值|生命周期)/i.test(text)
@@ -1472,8 +1988,12 @@ function analyzePromptIntent(prompt) {
   const l2RequirementCandidate = (bugfixOrDiagnostic && crossSystemRiskMatched)
     || l2FeatureExpansionMatched
     || l2PlanningRequestMatched;
+  const existingAssetDemotionApplies = existingAssetOptimizationMatched
+    && !strategicL2ScopeMatched
+    && structuralL2ScopeMatchCount === 0;
   const requirementTier = !internalOpenPrdExecution
     ? (l2RequirementCandidate
+        && !existingAssetDemotionApplies
         && !tinyEdit
         && !simpleConcrete
         && !visualMockupRequest
@@ -1489,7 +2009,9 @@ function analyzePromptIntent(prompt) {
         ? 'l0'
         : (!visualMockupRequest
             && !readOnly
-            && (l1OptimizationMatched || requirementSignalMatched)
+            && (l1OptimizationMatched
+              || requirementSignalMatched
+              || (l2RequirementCandidate && existingAssetDemotionApplies))
           ? 'l1'
           : null)))
     : null;
@@ -1520,6 +2042,10 @@ function analyzePromptIntent(prompt) {
     weappValidationRequest,
     browserSafetyRequest,
     productCopyRequest,
+    learningMaterialRequest,
+    learningGenre: learningMaterialIntent.genre,
+    learningMaterialReason: learningMaterialIntent.reason,
+    canvasCollaborationRequest,
     shouldInject: requiresIntake
       || requirementTier === 'l1'
       || explicitExecution
@@ -1535,6 +2061,8 @@ function analyzePromptIntent(prompt) {
       || weappValidationRequest
       || browserSafetyRequest
       || productCopyRequest
+      || learningMaterialRequest
+      || canvasCollaborationRequest
       || /openprd/i.test(normalized)
       || /\bprd\b/i.test(normalized),
   };
@@ -1542,7 +2070,7 @@ function analyzePromptIntent(prompt) {
 
 function isShortAffirmativeConfirmation(prompt) {
   const text = stripMarkdown(prompt).trim();
-  return /^(可以|好|行|确认|没问题|OK|ok|yes|Yes|yep|Yep)[。！!,.，s]*$/.test(text);
+  return /^(可以|好|行|确认|确定|没问题|同意|就这样|OK|ok|yes|Yes|yep|Yep)[。！!,.，s]*$/.test(text);
 }
 
 function looksLikeClarificationFollowupReply(prompt, intent = null) {
@@ -1657,6 +2185,32 @@ function authorizeRequirementGateExecution(root, prompt, sessionId = null, optio
   return next;
 }
 
+function escalateRequirementGateApproval(root, prompt, gate, sessionId = null) {
+  // 用户已经确认过一次需求摘要，又再次给出明确肯定/继续意图时，
+  // 把当前 lane 升级为 silent-record + 自动执行授权：后续 review 记录、change、tasks
+  // 都沿已确认范围静默推进，不再向用户反复索取同一轮确认。
+  const approvalPolicy = normalizeRequirementApprovalPolicy({
+    ...(gate?.approvalPolicy ?? {}),
+    reviewPolicy: 'silent-record',
+    executionMode: 'auto-after-review-and-tasks',
+    suppressExtraConfirmation: true,
+  });
+  return updateRequirementGate(root, {
+    approvalPolicy,
+    intent: { ...(gate?.intent ?? {}), explicitExecution: true },
+    executionIntent: {
+      ...(gate?.executionIntent ?? {}),
+      explicitRequested: true,
+      suppressExtraConfirmation: true,
+      source: 'repeated-user-confirmation',
+      latchedAt: now(),
+    },
+    confirmationCount: Number(gate?.confirmationCount ?? 1) + 1,
+    repeatedConfirmationAt: now(),
+    confirmationPreview: preview(prompt, 500),
+  }, sessionId);
+}
+
 function updateRequirementGate(root, patch, sessionId = null) {
   const current = readRequirementGate(root, sessionId);
   if (!current?.active) {
@@ -1935,6 +2489,9 @@ function evaluateRequirementGateProgress(root, sessionId = null) {
     nextStep = 'task-breakdown-required';
     reason = '本次调整范围已经立起来了，但还没拆成可直接执行的后续任务。';
   }
+  if (review.staleReview?.versionId) {
+    reason += ` 另外检测到工作区里残留了一份属于其他会话的历史确认稿（${review.staleReview.versionId}），本轮已自动忽略它；不要尝试确认或复用那份旧稿，直接按当前需求生成新的确认稿。`;
+  }
   return {
     runContext: parsed,
     binding,
@@ -2088,6 +2645,94 @@ function isMutationPayload(payload, risk) {
     || /\*\*\* Begin Patch/.test(text);
 }
 
+function isRuntimeAutonomyRiskFile(file) {
+  const normalized = String(file || '').split(path.sep).join('/');
+  if (!normalized) {
+    return true;
+  }
+  if (/^(docs|test|tests|__tests__|fixtures|examples|templates?)\//i.test(normalized)) {
+    return false;
+  }
+  if (/(^|\/)(AGENTS|CLAUDE|README|CHANGELOG|SKILL)\.md$/i.test(normalized)) {
+    return false;
+  }
+  if (/\.(?:md|mdx|txt|rst)$/i.test(normalized)) {
+    return false;
+  }
+  return true;
+}
+
+function hasExplicitAutonomyRiskApproval(intent = null) {
+  const text = String(intent?.promptText || '');
+  if (!text.trim()) {
+    return false;
+  }
+  const riskTerms = /(云端|线上|生产环境|远端|热修复|hotfix|兜底|临时兜底|fallback|fall\s*back|写死|硬编码|hardcode|hard-coded|hard coded)/i;
+  if (!riskTerms.test(text)) {
+    return false;
+  }
+  const negatedRisk = /(不要|禁止|不允许|不得|不能|避免|默认不|未明确|未经|除非).{0,48}(云端|线上|生产环境|远端|热修复|hotfix|兜底|临时兜底|fallback|fall\s*back|写死|硬编码|hardcode|hard-coded|hard coded)|(云端|线上|生产环境|远端|热修复|hotfix|兜底|临时兜底|fallback|fall\s*back|写死|硬编码|hardcode|hard-coded|hard coded).{0,48}(不要|禁止|不允许|不得|不能|避免|默认不|未明确|未经|除非)/i;
+  if (negatedRisk.test(text)) {
+    return false;
+  }
+  return /(明确)?(允许|批准|同意|确认|可以|请|直接|必须|这次|现在).{0,40}(云端|线上|生产环境|远端|热修复|hotfix|兜底|临时兜底|fallback|fall\s*back|写死|硬编码|hardcode|hard-coded|hard coded)|(云端|线上|生产环境|远端|热修复|hotfix|兜底|临时兜底|fallback|fall\s*back|写死|硬编码|hardcode|hard-coded|hard coded).{0,40}(允许|批准|同意|确认|可以|直接|必须|这次|现在)/i.test(text);
+}
+
+function detectHighRiskAutonomyMutation(root, payload, intent, risk) {
+  if (!isMutationPayload(payload, risk)) {
+    return null;
+  }
+  const command = commandText(payload);
+  const text = [
+    toolName(payload),
+    command,
+    payloadText(payload),
+  ].filter(Boolean).join('\n');
+  const touched = extractTouchedFiles(root, payload);
+  const runtimeTarget = touched.length === 0 || touched.some((file) => isRuntimeAutonomyRiskFile(file));
+  const cloudMutation = /(?:\b(?:ssh|scp|rsync)\b[^\n]*(?:prod|production|线上|生产|云端|server|remote)|\b(?:kubectl|helm)\b[^\n]*(?:apply|patch|set|delete|rollout|scale|exec)[^\n]*(?:prod|production|线上|生产|云端|cluster)|\b(?:vercel|wrangler|fly|flyctl|railway|firebase)\b[^\n]*(?:deploy|up)[^\n]*(?:--prod|prod|production|线上|生产)|\bsupabase\s+db\s+push\b[^\n]*(?:--linked|--db-url|prod|production|线上|生产)|\bcurl\b[^\n]*(?:-X|--request)\s*(?:POST|PUT|PATCH|DELETE)\b[^\n]*(?:prod|production|线上|生产|云端|api\.))/i.test(text);
+  if (cloudMutation) {
+    return {
+      kind: 'cloud-hotfix',
+      title: '云端/生产远端写入',
+      details: preview(command || text, 260),
+    };
+  }
+  if (!runtimeTarget) {
+    return null;
+  }
+  // 只保留真实业务权益/计费类词汇；配置、服务端、客户端、缓存、feature 这类
+  // 基础设施通用词在正常代码里大量出现，叠加“fallback/兜底”会造成海量误拦。
+  const businessTerms = /(业务|权益|会员|额度|价格|计费|订阅|套餐|entitlement|membership|billing|quota|price|paywall|subscription|localstorage)/i;
+  const fallbackTerms = /(兜底|fallback|fall\s*back|临时补|临时插入|补行|补进|本地补|客户端补|服务端补|缓存补|默认插入|补一条|补数据)/i;
+  const hardcodeTerms = /(写死|硬编码|hardcode|hard-coded|hard coded)/i;
+  const fixedBusinessValue = /(unlimited|premium|pro|vip|admin|owner|free|trial|quota|limit|count_limit|free_limit|权益|会员).{0,80}(?:=|:).{0,80}(?:unlimited|premium|pro|vip|admin|owner|free|true|false|999999|Infinity)/i;
+  if ((businessTerms.test(text) && (fallbackTerms.test(text) || hardcodeTerms.test(text))) || fixedBusinessValue.test(text)) {
+    return {
+      kind: 'hardcoded-fallback',
+      title: '业务兜底/写死逻辑',
+      details: preview(touched.length > 0 ? `${touched.join(', ')}\n${command || text}` : command || text, 260),
+    };
+  }
+  return null;
+}
+
+function formatHighRiskAutonomyBlock(detection) {
+  return [
+    `OpenPrd blocked a high-risk autonomy action: ${detection.title}.`,
+    '当前用户消息只授权了本轮实现范围，不等于授权 Agent 私自做云端热修复、生产远端写入、业务兜底、写死逻辑或缓存补行。',
+    detection.details ? `Matched action: ${detection.details}` : null,
+    '默认路径：先改本地源码、配置、迁移或数据修复脚本，让本地与云端保持同一事实源；完成后再按正常发布/部署路径验证。',
+    '如果这次确实必须临时处理，请先让用户明确说“允许这次云端热修复”或“允许这次临时兜底/写死”，并说明影响范围、回滚方式和如何同步回本地源码/配置/迁移。',
+  ].filter(Boolean).join('\n');
+}
+
+const LIGHTWEIGHT_UI_VISUAL_SIGNAL_PATTERN = /(按钮|文案|颜色|圆角|位置|间距|留白|边距|内边距|外边距|宽度|高度|卡片|字号|字体|行高|图标|标题|空格|标点|对齐|密度|阴影|边框|层级|组件|输入框|菜单|侧栏|表格|列表|头像|badge|label|copy|toast|placeholder|padding|margin|spacing|gap|太宽|太窄|太挤|拥挤|松散|留得多|留着有点多|没对齐|好看|美观|审美|气质|记忆点|高级|太丑|丑|视觉风格|上架图|截图优化)/i;
+
+function hasLightweightUiVisualSignal(text = '') {
+  return LIGHTWEIGHT_UI_VISUAL_SIGNAL_PATTERN.test(String(text || ''));
+}
+
 function isFrontendTaskIntent(intent = null) {
   const text = String(intent?.promptText || '').trim();
   if (!text || intent?.visualMockupRequest) {
@@ -2162,7 +2807,7 @@ function frontendDesignPreflightIssues(root, intent, implementationFiles) {
   if (shouldRequireAssetSpec(intent) && designArtifactHasPlaceholder(root, 'asset-spec.md')) {
     issues.push({
       file: 'asset-spec.md',
-      reason: '进入实现前先冻结资产口径；没有官方资产也要写“缺失 / 暂无 / 不适用”，不要留模板占位。',
+      reason: '进入实现前先冻结资产口径；没有官方资产也要写“缺失 / 暂无 / 不适用”，不要留模板占位。新功能出现新入口、按钮、tab、卡片或空态时，同步补“功能图标”行：先复用项目已有图标体系，缺失时按最佳实践路由（Phosphor / Lucide / Tabler / React Icons / LobeHub / Tech Icons / iconfont）选型并登记图标名、来源、用途，不等用户要求。',
     });
   }
   if (shouldRequireImagePreflight(intent) && designArtifactHasPlaceholder(root, 'image-preflight.md')) {
@@ -2458,7 +3103,9 @@ function productCopyMessage(intent) {
   return [
     'OpenPrd 产品内文案提醒:',
     '先检查项目是否已有 i18n、locales、translations、Localizable 或其他语言资源；若已有，多语言要同步维护。',
-    '用户可见文案默认面向普通用户，优先写结果和下一步，不要把 API、SDK、模型、数据库、缓存、错误码或其他实现细节直接暴露给用户。',
+    '产品界面上用户能看到的文案必须站在当前用户视角写：说明用户现在能做什么、会发生什么、为什么值得点、下一步怎么走。',
+    '除非这是面向开发者或专业技术人员的技术型产品，否则默认用普通人能看懂的语言写结果、状态、限制和行动，不要把 API、SDK、模型、数据库、缓存、错误码或其他实现细节直接暴露给用户。',
+    '快速正反例：不要写“适合想保留全部工具入口的用户”，改成“首页会显示所有工具入口，你可以直接选择需要的功能”；不要写“API 请求失败，错误码 500”，改成“暂时保存失败，请稍后再试”。技术型产品可以保留必要术语，但仍要写清用户动作、影响和修复路径。',
   ].join('\n');
 }
 
@@ -2565,13 +3212,25 @@ function devCheckWrapUpMessage(root, turnState) {
   if (!parsed?.wrapUp?.required || !parsed.wrapUp.markdownTable) {
     return null;
   }
+  const autoMode = parsed.wrapUp.mode === 'auto-refactor';
   return [
-    'OpenPrd 后续建议：本轮有改动对象需要主动说明。',
-    '最终回复必须直接复用下面的 Markdown 表格，按 🔴 → 🟠 → 🟡 的顺序帮助产品或业务理解影响对象、本次处理结果和后续建议；不要只用工具名或一段话带过。',
-    '如果你改写了“预警原因 / 本次处理结果 / 后续建议”，先用 `node scripts/dev-check-wrapup-copy.mjs --validate` 校验每格不超过 20 字；若报错，按提示缩短后重试。',
-    '不要把“关注程度”列改写成纯 emoji；必须保留例如“🟠 中风险｜建议优先关注”这类完整标签。',
+    autoMode
+      ? 'OpenPRD 自动优化报告：本轮有超行改动对象，自动优化默认开启。'
+      : 'OpenPrd 后续建议：本轮有改动对象需要主动说明。',
+    autoMode
+      ? '先在本轮按 dev-check 给出的动作完成高内聚低耦合拆分（不丢任何功能、行为不变，拆完重跑测试与 dev-check），把每行“本次处理结果”回填为真实优化产出；最终回复必须以 **OpenPRD 自动优化报告** 为标题直接复用下面的 Markdown 表格，按 🔴 → 🟠 → 🟡 排序，并附一句：“如果下次不需要自动优化代码结构，回复关闭自动优化即可”。用户确认关闭后运行 `openprd dev-check . --auto-refactor off`。'
+      : '最终回复必须以 **后续建议** 为标题直接复用下面的 Markdown 表格，按 🔴 → 🟠 → 🟡 的顺序帮助产品或业务理解影响对象、本次处理结果和后续建议；不要只用工具名或一段话带过。',
+    autoMode
+      ? '如果你改写了“源文件规模 / 优化原因 / 本次处理结果 / 后续建议”，先用 `node scripts/dev-check-wrapup-copy.mjs --validate` 校验每格不超过 20 字；若报错，按提示缩短后重试。'
+      : '如果你改写了“规模信号 / 预警原因 / 本次处理结果 / 后续建议”，先用 `node scripts/dev-check-wrapup-copy.mjs --validate` 校验每格不超过 20 字；若报错，按提示缩短后重试。',
+    autoMode
+      ? '不要把“问题级别”列改写成纯 emoji；必须保留例如“🟠 中风险｜建议优先关注”这类完整标签。'
+      : '不要把“关注程度”列改写成纯 emoji；必须保留例如“🟠 中风险｜建议优先关注”这类完整标签。',
     parsed.wrapUp.markdownBlock ?? parsed.wrapUp.markdownTable,
-  ].join('\n');
+    parsed.visualEvidence?.required
+      ? `视觉证据提醒：${parsed.visualEvidence.reason} 建议命令：${(parsed.visualEvidence.suggestedCommands ?? []).join('；')}。${parsed.visualEvidence.chatEmbedHint ?? ''}`
+      : null,
+  ].filter(Boolean).join('\n');
 }
 
 function shouldRunDoctorForHighRisk(payload) {
@@ -2721,8 +3380,10 @@ function requirementGateMessage(intent, gate) {
       'OpenPrd requirement intake gate is active only for implementation writes.',
       'The user is asking for an image asset such as a cover image, poster, illustration, icon, sticker, visual mockup, or effect image, not code implementation.',
       'For logo, icon, avatar, badge, and similar development assets, default to a standalone asset: full-frame single subject with no extra UI frame, card shell, device mockup, or presentation container unless the user explicitly asked for one.',
+      'If the final development asset should be transparent for UI use, use an icon-asset pipeline: generate three visibly different standalone candidates first, each on a solid #00ff00 chroma-key background with no text, no UI container, centered subject, and enough padding; do not write project files before the user chooses one. After selection, verify the selected source or contact sheet, keep the green-screen source, run remove_chroma_key.py to produce a transparent PNG/WebP, crop and center it, export 384px or required sizes, tune the display ratio per real UI placement, and record the source, transparent output, integration point, and verification in asset-spec.md / selected-direction.md before claiming completion.',
       'Do not create temporary HTML/SVG/CSS files for this image unless the user explicitly requested that format.',
-      'Use `imagegen`, which is Codex native Image 2, to generate the image; keep implementation, PRD review, and visual-compare for later explicit confirmation of whether this generated image should become a reference.',
+      'Image tool routing: on a Codex surface use native `imagegen` (Image 2); on a Cursor surface use the built-in `GenerateImage` tool; both are free inside the conversation tool. If neither surface applies, read the confirmed preference in `.openprd/harness/image-generation-preference.json`; when no preference exists, ask the user which image-generation path to use and persist the answer to that file as the future default. NEVER silently call the user\'s own paid image API. The image tool is the tool path, not an aesthetic exemption, so first state the purpose, audience, intended tone, constraints, and memory point, then put them into the image prompt.',
+      'Before generation, do a quick anti-slop check: without brand or reference support, avoid default purple/blue-purple gradients, generic font taste, white card piles, and context-free decoration.',
     ].join('\n');
   }
   const status = gateBlocksImplementation ? 'active' : 'opened';
@@ -2767,28 +3428,78 @@ function lightweightRequirementMessage(intent) {
   return null;
 }
 
-function visualMockupMessage(intent) {
+function imageGenerationPreferencePath(root) {
+  return path.join(harnessDir(root), 'image-generation-preference.json');
+}
+
+function imageGenerationRoutingLines(root) {
+  const preference = readJsonSync(imageGenerationPreferencePath(root), null);
+  const lines = [
+    '生图路由: 第一层先判断当前对话工具面——Codex 环境用原生 `imagegen`（Image 2），Cursor 环境用内置 `GenerateImage` 工具；两者都是对话工具内免费能力，优先默认使用。',
+    '如果当前既不是 Codex 也不是 Cursor，或内置生图工具面证据不存在，先读 `.openprd/harness/image-generation-preference.json` 里用户已确认的生图偏好；没有已确认偏好时必须先询问用户要用哪种生图方式，并把用户答复以 `{"provider","source":"user-confirmed","updatedAt"}` 写回该文件，下次直接作为默认。',
+    '成本护栏: 绝对不要在用户未明确指定的情况下擅自调用用户本地或自有付费生图 API（如用户自己的 OpenAI / Stability key），避免产生额外成本；只有偏好文件或当前消息明确授权时才可以使用。',
+  ];
+  if (preference?.provider) {
+    lines.push(`当前已保存的用户生图偏好: ${preference.provider}（来源: ${preference.source || 'user-confirmed'}）。内置免费生图工具不可用时优先使用它，不要再重复询问。`);
+  }
+  return lines;
+}
+
+function visualMockupMessage(intent, root = null) {
   if (!intent?.visualMockupRequest) {
     return null;
   }
   return [
     '当前用户要的是图片内容生成，例如图片、封面图、配图、海报、插画、图标、贴纸、头像、banner、主视觉/KV、运营图、效果图、视觉稿或 mockup。',
-    '默认直接调用 `imagegen`，也就是 Codex 原生 Image 2，来生成图片；除非用户明确指定 HTML、SVG、CSS、Canvas、代码稿或可编辑矢量/source artifact，不要改用临时 HTML/SVG/CSS 再截图。',
-    '对 logo、icon、avatar、badge 等开发素材，如果用户没有明确要求 mockup、场景图、设备框、卡片承载、名片/包装展示或参考界面复刻，默认按独立素材输出（standalone asset）处理：使用全画布单主体，不额外添加 UI frame、卡片、设备壳、名片、桌面陈列、手持实拍或其他展示容器。',
+    ...(root ? imageGenerationRoutingLines(root) : []),
+    '按生图路由选定的内置生图工具生成图片（Codex=`imagegen`/Image 2，Cursor=`GenerateImage`）；生图工具是工具路径，不是审美豁免；生图前先写清用途、受众、气质、约束和记忆点，并把这些写进 prompt。',
+    '生图前用 `.openprd/design/anti-slop.md` 做快速自检：没有品牌或参考图依据时，不要默认紫白/蓝紫渐变、通用字体、白底卡片堆叠或无语境装饰。',
+    '除非用户明确指定 HTML、SVG、CSS、Canvas、代码稿或可编辑矢量/source artifact，不要改用临时 HTML/SVG/CSS 再截图。',
+    '对 logo、icon、avatar、badge 等开发素材，如果用户没有明确要求 mockup、场景图、设备框、卡片承载、名片/包装展示或参考界面复刻，默认按独立素材输出（standalone asset）处理：使用全画布单主体，不额外添加 UI frame、卡片、设备壳、名片、桌面陈列、手持实拍或其他展示容器；如果最终要接入 UI 并需要透明背景，先生成 3 个差异足够大的纯 `#00ff00` 绿幕候选方向，用户选定前不写项目文件，选定后再保留源图、抠透明、裁切居中、导出 384px 或多尺寸资产，按真实 UI 场景调显示比例，并把源图、透明产物、接入位置和验证结果写回 `asset-spec.md` / `selected-direction.md`。',
     '只有当用户明确要求 mockup、场景化效果图、容器化呈现，或参考图本身就包含这些承载结构时，才生成对应的容器或场景。',
-    '只有在实际发生 `imagegen` 调用后，才能汇报生图结果、失败或限流；未调用 `imagegen` 前，不要声称“生图限流”或“生图失败”。',
-    '把 `imagegen` 结果先当成候选效果图，不要默认登记到 `.openprd/harness/visual-reviews/`，也不要自动当成后续验收参考。',
+    '只有在实际发生生图工具调用后，才能汇报生图结果、失败或限流；未调用前，不要声称“生图限流”或“生图失败”。',
+    '把生图结果先当成候选效果图，不要默认登记到 `.openprd/harness/visual-reviews/`，也不要自动当成后续验收参考；看图时不仅判断是否生成成功，还要判断气质、层级、字体/色彩/表面角色和记忆点是否成立。',
     '如果用户看完图后还要继续做实现，主动连问三件事：是否符合预期、是否纳入后续效果图/实现截图对比、是否按此继续后续实现。只有用户确认纳入对比或继续实现后，才把这张图、这组图或其中选定子图整理成后续 reference-set；如果用户只是认可图片但暂不实现，就继续把它当候选效果图。',
     '如果一张图里有多个子图、网格、多对象或多个方向，不要把整板直接当成单一参考图；先运行 `openprd visual-prepare . --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>` 生成 reference-set、contact sheet 和 compare-plan，确认 contact sheet 后再逐项对比或统一验收。',
-    'OpenPrd review.html 只用于需求评审，visual-compare 只用于实现阶段视觉证据：已有参考图时做效果图/实现截图对比；没有参考图时先判断新建界面还是修改既有界面，新建界面回到实现前 3 方向方案评审，修改既有界面做修改前/修改后自检；局部细节优先补局部焦点证据板，并行优化方向优先补并行实验证据板。',
+    'OpenPrd review.html 只用于需求评审，visual-compare 只用于实现阶段视觉证据：已有参考图时做效果图/实现截图对比；没有参考图时先判断新建界面还是修改既有界面，新建界面回到实现前 3 方向方案评审，修改既有界面做修改前/修改后自检；局部细节优先补局部焦点证据板，并行优化方向优先补并行实验证据板；同构列表、卡片、网格或表格需要补对齐辅助线证据板，并同时检查容器轨道和内部内容槽位轨道；单个 logo、icon、avatar、badge、按钮图形或图片内部需要居中判定、视觉重心评估或偏心排查时，需要补内部居中证据板，并同时检查画布中心、主体外接框中心和视觉重心偏移。',
   ].join('\n');
 }
 
-function learningReviewMessage() {
+function canvasCollaborationMessage(intent) {
+  if (!intent?.canvasCollaborationRequest) {
+    return null;
+  }
   return [
+    '当前请求涉及 OpenPrd 画布协同（生图上画布、人在画布上标注、标注结果回到对话继续改）。',
+    '打开或复用画布：运行 `openprd canvas .`；无法自动识别当前对话时用 `--thread <id> --thread-title <name>` 或 `--session <id> --session-title <name>` 显式绑定，画布必须绑定当前对话。',
+    '结构化读画布：需要知道用户正在圈哪些元素时，优先 `GET /api/selection` 读取选中元素的 ID、类型、坐标、尺寸和文本，不要只靠截图猜；需要全量场景再读 `GET /api/scene`。',
+    '结构化写画布：把生成的新图放上画布时，优先 `POST /api/insert-image`，用 `anchorElementId` + `placement`（right/left/below/above）把新图放到指定元素旁边，不要覆盖原图；回填 AI 生图占位卡时继续用 `POST /api/images` 带 `placeholderId`。',
+    '标注改图闭环：如果交接记录（handoff）的 `selection` 是 `annotation-edit`，或带有 `sourceImageElementIds` / `annotationElementIds`，说明用户在原图上画了标注要求改图。把截图里的标注当修改指令，生成修改后的新图，再用 `POST /api/insert-image` 以原图为 anchor 放到旁边，方便用户对比原图和新版。',
+    '生图尺寸契约：handoff 或占位卡带 `sizeContract`（width/height/aspectRatio）时，生成图片必须按这个宽高比出图，避免回填时变形拉伸。',
+    '每轮改图后主动确认：新图是否符合标注意图、是否继续下一轮标注迭代；用户可以继续在新图上标注，形成多轮改图闭环。',
+  ].join('\n');
+}
+
+function learningGenreFlag(intent = null) {
+  return intent?.learningGenre ? ` --genre ${intent.learningGenre}` : '';
+}
+
+function learningReviewCommand(intent = null) {
+  return `openprd learn . --topic "<学习主题>"${learningGenreFlag(intent)} --open`;
+}
+
+function learningReviewMessage(intent = null) {
+  const command = learningReviewCommand(intent);
+  const lines = [
     '如果当前交付目标是把一次工作转成可学习、可复用、可回看、可教学或可沉淀的材料，不要先按关键词判断，也不要只停留在普通说明文档。',
     '先判断期望产物形态：是否需要章节结构、证据锚点、图文讲解、检索练习、工作示例或阅读体验。需要这些形态时，优先使用 `openprd learn .` 生成学习包骨架、阅读器和证据清单，再补充正文内容；普通 Markdown 只能作为辅助讲义。',
-  ].join('\n');
+  ];
+  if (intent?.learningMaterialRequest) {
+    lines.unshift('当前输入已被识别为学习型交付物请求：这是按产物形态和长期阅读/教学目的判断，不是固定关键词表。');
+    lines.push(`建议先运行 \`${command}\`。如果用户指定了仙侠、科幻、童话等风格，把它当作学习包题材/文体参数，而不是绕过阅读器流程的理由。`);
+    lines.push('生成骨架后，读取 `.openprd/learning/archive/<packageId>/agent-prompt.md`，由 Agent 基于证据写入 `learning-content.json`，再运行 `openprd learn . --content-json <file> --open` 渲染最终 reader；不要把聊天里的普通 Markdown 成稿当完成。');
+  }
+  return lines.join('\n');
 }
 
 function largeUiVisualDirectionMessage() {
@@ -2796,7 +3507,7 @@ function largeUiVisualDirectionMessage() {
     'OpenPrd 大界面改动视觉方案评审:',
     '位置: 需求分流之后、PRD 定稿或实现开工之前；它不同于 review.html，也不同于实现后的 visual-compare。',
     '判断: 先从用户目标、信息架构变化、视觉决策成本和验收风险判断是否需要方向评审，不用关键词触发。会决定首屏、核心布局、主视觉、关键路径、组件层级/密度，或用户需要先选设计方向时触发。',
-    '步骤: 已有界面时用 Codex Computer Use 进入产品内对应功能并截当前真实界面；冷启动没有现有界面时，基于已确认 PRD、用户画像、第一版切片和视觉目标写设计 brief。然后调用 `imagegen`（Codex 原生 Image 2）生成至少 3 个不同设计思想方向；把效果图横向拼成一张带 1/2/3 序号的大图，先作为候选效果图给用户评审，不要默认写入 `.openprd/harness/visual-reviews/` 当验收参考。',
+    '步骤: 已有界面时用 Codex Computer Use 进入产品内对应功能并截当前真实界面；冷启动没有现有界面时，基于已确认 PRD、用户画像、第一版切片和视觉目标写设计 brief。brief 必须写清用途、受众、气质端点、约束和记忆点，3 个方向要分别说明审美主张和主动避开的模板味。然后按生图路由调用内置生图工具（Codex=`imagegen`/Image 2，Cursor=`GenerateImage`；都不可用时按 `.openprd/harness/image-generation-preference.json` 的用户已确认偏好，没有偏好先问用户）生成至少 3 个不同设计思想方向；把效果图横向拼成一张带 1/2/3 序号的大图，先作为候选效果图给用户评审，不要默认写入 `.openprd/harness/visual-reviews/` 当验收参考。',
     '交互: 主动追问三件事：是否符合预期、是否纳入后续效果图/实现截图对比、是否按此继续后续实现。只有用户确认纳入后续对比或继续实现后，才把选定方向、整张图或其中子图整理成 reference-set 并写入 `.openprd/harness/visual-reviews/`；用户确认前，不进入大 UI 实现，也不要声称界面方案已定。',
     '多对象参考处理: 如果候选效果图是一张图里包含多个子图、网格、多对象或多方向，不要拿整板直接硬比；先运行 `openprd visual-prepare . --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>`，检查 contact sheet，确认 reference-set 后再逐项进入实现和验收。',
   ].join('\n');
@@ -2805,15 +3516,16 @@ function largeUiVisualDirectionMessage() {
 function visualLocalAdjustmentMessage() {
   return [
     '如果这轮验收重点在局部变化，不要只改代码后凭主观判断收尾。',
-    '先判断这是新建界面还是修改既有界面：新建界面走实现前 3 方向方案评审；修改既有界面先保留修改前截图。完成后从同一入口、视口、账号和数据状态截修改后截图，再运行 `openprd visual-compare . --before <修改前截图> --after <修改后截图>`。',
-    '如果局部细节需要放到同一张证据板里审阅，再补一份 `openprd visual-compare . --board <focus-board.json>` 的局部焦点证据板，把局部变化组合到同一张证据板里统一验收。',
+    '修改前先用一句话锁定本次审美意图和记忆点；收口的 visual-compare/focus-board 不只看位置，也要看气质、层级、色彩、字号、间距和表面角色是否被保住。',
+    '先判断这是新建界面还是修改既有界面：新建界面走实现前 3 方向方案评审；修改既有界面先保留修改前截图。完成后从同一入口、视口、账号和数据状态截修改后截图，再运行 `openprd visual-compare . --before <修改前截图> --after <修改后截图> --locale <zh-CN|en>`。',
+    '如果局部细节需要放到同一张证据板里审阅，再补一份 `openprd visual-compare . --board <focus-board.json> --locale <zh-CN|en>` 的局部焦点证据板，把局部变化组合到同一张证据板里统一验收；如果只是普通截图、Computer/Browser/Playwright 实测截图，也要用 `openprd visual-compare . --board <verification-board.json> --locale <zh-CN|en>` 拼成截图实测证据板；如果界面存在同构列表、卡片、网格或表格，或用户反馈元素没有对齐，要用 `openprd visual-compare . --board <alignment-board.json> --locale <zh-CN|en>` 拼成对齐辅助线证据板，且同一张板里同时覆盖容器轨道和标题/副标题/描述/标签/状态/价格/按钮/图标等内部内容槽位；如果单个素材/图标/头像/徽标/按钮图形/图片内部需要居中或视觉重心判定，要用 `openprd visual-compare . --board <centering-board.json> --locale <zh-CN|en>` 拼成内部居中证据板，且同一张板里同时覆盖红色画布中心、绿色主体外接框和黄色视觉重心点，不能把单张截图当最终视觉证据。',
     '如果参考图是一张整板、网格图或多对象组合图，先运行 `openprd visual-prepare . --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>`，确认 contact sheet 后，再决定是逐项 `--reference/--actual` 还是统一做 `focus-board` / `parallel-board`。',
-    '当用户后续说“跟效果图”“不一致”“好丑”“复刻”“没对齐”这类反馈时，不能只口头说已经对比过了；至少先产出一份 `openprd visual-compare`、`focus-board` 或 `parallel-board` 证据图再下结论。'
+    '当用户后续说“跟效果图”“不一致”“好丑”“复刻”“没对齐”“偏心”“不居中”这类反馈时，不能只口头说已经对比过了；至少先产出一份 `openprd visual-compare`、`focus-board`、`parallel-board`、`verification-board`、`alignment-board` 或 `centering-board` 证据图再下结论。'
   ].join('\n');
 }
 
 function codexConfirmationReplyRule() {
-  return 'Codex 回复规则: 只有当前真的还缺人来拍板时，才在 final answer 里停下来请求确认。只要用户已经明确说了“认可并继续”，或已经确认了 mini-plan、范围边界、正式产品边界，就直接沿着已确认路径继续，不要再写“如果你认可”“确认的话我就继续”这类二次索取确认的话。面向用户时，不要直接抛 lane、change、tasks、review artifact、work unit、digest、worker shard、write-scope、worktree、内部版本号、命令或文件路径这些内部词；统一改说“需求确认稿”“本次调整”“后续任务”“继续落地”“完成后检查”。如果后面真的还需要额外授权，再用人话把会做什么、不会做什么、完成后怎么检查说清楚。如果当前仍在 L2 的首轮澄清或需求摘要确认阶段，不要写成“你回我一句我就开始实现”；只能承诺“我先整理需求摘要给你确认，确认后再继续”。如果当前 lane 已进入 silent-record 策略，只能说明用户已经明确说了“不需要进行任何确认”；单纯的“请帮我实现/继续实现”不能把 lane 切到 silent-record。';
+  return 'Codex 回复规则: 只有当前真的还缺人来拍板时，才在 final answer 里停下来请求确认。停下请求确认时执行“一次确认合同”：把本条需求后续本来会出现的全部确认点合并成一段话一次性说清，并告诉用户只要回一句“确认，继续执行”，剩余环节会自动连续推进；同一条需求不允许出现第二个人工确认停顿。绝对不要让用户粘贴 digest、work unit、版本号或任何 openprd 命令——这些值 hook 会自动绑定，需要时由你自己填进命令。只要用户已经明确说了“认可并继续”，或已经确认了 mini-plan、范围边界、正式产品边界，就直接沿着已确认路径继续，不要再写“如果你认可”“确认的话我就继续”这类二次索取确认的话。面向用户时，不要直接抛 lane、change、tasks、review artifact、work unit、digest、worker shard、write-scope、worktree、内部版本号、命令或文件路径这些内部词；统一改说“需求确认稿”“本次调整”“后续任务”“继续落地”“完成后检查”。如果后面真的还需要额外授权，再用人话把会做什么、不会做什么、完成后怎么检查说清楚。如果当前仍在 L2 的首轮澄清或需求摘要确认阶段，不要写成“你回我一句我就开始实现”；只能承诺“我先整理需求摘要给你确认，确认后再继续”。如果当前 lane 已进入 silent-record 策略，只能说明用户已经明确说了“不需要进行任何确认”；单纯的“请帮我实现/继续实现”不能把 lane 切到 silent-record。';
 }
 
 function confirmationGateMessage(gate) {
@@ -2826,7 +3538,7 @@ function confirmationGateMessage(gate) {
   return [
     intro,
     'Implementation may proceed only within the confirmed scope, with docs/basic, file manuals, folder README docs, standards verification, and OpenPrd run verification kept up to date. For backend, script, agent, tooling, service, or data-processing changes, keep CLI and API surface review current in docs/basic/backend-structure.md.',
-    'For UI or visual work with an existing reference image, first confirm the user has accepted that image as a later comparison reference; if one image contains multiple sub-images, grid cells, or objects, run openprd visual-prepare . --reference <effect-image> --grid <columns>x<rows> or --boxes <plan.json>, inspect the contact sheet, and use the generated reference-set / compare-plan before comparing. Then capture the implemented UI and run openprd visual-compare . --reference <effect-image> --actual <implementation-screenshot>; if local detail matters more than the whole screen, add openprd visual-compare . --board <focus-board.json> so the agent can review numbered zoom regions. When there is no reference image, capture the before screenshot first, implement, capture the after screenshot from the same entry, viewport, account, and data state, then run openprd visual-compare . --before <before-screenshot> --after <after-screenshot>; if the agent explored multiple optimization directions, add openprd visual-compare . --board <parallel-board.json> and inspect expected changes plus unintended drift before claiming completion.',
+    'For UI or visual work with an existing reference image, first confirm the user has accepted that image as a later comparison reference; if one image contains multiple sub-images, grid cells, or objects, run openprd visual-prepare . --reference <effect-image> --grid <columns>x<rows> or --boxes <plan.json>, inspect the contact sheet, and use the generated reference-set / compare-plan before comparing. Then capture the implemented UI and run openprd visual-compare . --reference <effect-image> --actual <implementation-screenshot>; if local detail matters more than the whole screen, add openprd visual-compare . --board <focus-board.json> --locale <zh-CN|en> so the agent can review numbered zoom regions. When there is no reference image, capture the before screenshot first, implement, capture the after screenshot from the same entry, viewport, account, and data state, then run openprd visual-compare . --before <before-screenshot> --after <after-screenshot>; if the agent explored multiple optimization directions, add openprd visual-compare . --board <parallel-board.json> --locale <zh-CN|en>. If ordinary screenshots or Computer/Browser/Playwright checks are used as evidence, assemble them with the checked path and checkpoints through openprd visual-compare . --board <verification-board.json> --locale <zh-CN|en> before claiming visual completion. If the UI contains repeated homogeneous cards, lists, grids, or tables, or the user reports misalignment, capture the real screen, overlay guide lines, measure both container-track and internal content-slot x/y/size/baseline spread, and assemble an alignment-board through openprd visual-compare . --board <alignment-board.json> --locale <zh-CN|en>. If a single logo, icon, avatar, badge, button graphic, or image crop needs internal-centering or visual-centroid judgment, crop the target and assemble a centering-board through openprd visual-compare . --board <centering-board.json> --locale <zh-CN|en> before claiming it is centered.',
     'If the user later says the implementation does not match the effect image, looks wrong, or asks for replication, do not rely on subjective narration alone; produce at least one visual evidence artifact before claiming completion.',
   ].join('\n');
 }
@@ -2842,7 +3554,7 @@ function currentRequirementStatusLine(gate, progress) {
   }
   switch (progress?.nextStep) {
     case 'clarification-confirmation-required':
-      return '当前卡点: 先让用户确认当前需求摘要；在此之前不要把核心需求写成既定事实，也不要直接往后推进。';
+      return '当前卡点: 先让用户确认当前需求摘要；在此之前不要把核心需求写成既定事实，也不要直接往后推进。请求确认时按“一次确认合同”表达：明确告诉用户这是本条需求默认唯一的一次人工确认，只要回复“确认，继续执行”，后面的需求稿整理、调整范围、任务拆解和实现都会自动连续推进，不会再逐环节找他确认。';
     case 'clarification-writeback-required':
       return '当前卡点: 用户已经确认这轮需求摘要或默认方案，但 current.json 里还没有把确认后的事实稳定写回。先按 canonical 字段路径用 user-confirmed 回写，再继续 synthesize；不要再回退成泛化 clarify，也不要继续写 agent-inferred。';
     case 'product-type-classification-required':
@@ -2855,7 +3567,7 @@ function currentRequirementStatusLine(gate, progress) {
         : '当前卡点: 当前需求摘要已确认，下一步把已确认内容整理成这版需求确认稿。';
     case 'prd-review-required':
       return progress?.review?.versionId
-        ? '当前卡点: 先等用户确认这版需求确认稿；不要把“继续做”“开落地吧”或单纯的“请帮我实现/继续实现”当成已经认可这版内容。'
+        ? '当前卡点: 先等用户确认这版需求确认稿；不要把“继续做”“开落地吧”或单纯的“请帮我实现/继续实现”当成已经认可这版内容。请求确认时只需要用户回一句自然语言，例如“确认这版，继续执行”；版本、digest、work unit 由 hook 自动绑定，绝对不要让用户粘贴 digest、work unit 或任何 openprd 命令。同时说明这一句确认之后整条链会自动执行到实现，不会再停。'
         : '当前卡点: 先整理出这版需求确认稿，再等待用户确认。';
     case 'review-recording-required':
       return '当前卡点: 这版需求确认稿已经生成，而且用户已明确表示不需要再停下来确认；可以先记录这次确认结果，再继续后面的整理。';
@@ -2957,16 +3669,17 @@ function contextMessage(cwd, intent = null, gate = null, progress = null) {
         knowledgeSkillReminder(run.parsed),
         'OpenPrd 上下文只是建议，不是自动执行指令。请先判断用户当前意图。',
         lightweightRequirementMessage(intent),
-        visualMockupMessage(intent),
-        learningReviewMessage(),
+        visualMockupMessage(intent, cwd),
+        canvasCollaborationMessage(intent),
+        learningReviewMessage(intent),
         largeUiVisualDirectionMessage(),
         visualLocalAdjustmentMessage(),
         requirementRoutingSummary(),
         '如果用户只是要求看看、规划、分析、审查、解释影响或列出文件，请保持只读并基于证据回答；不要运行 OpenPrd loop、任务推进、discovery 推进、commit 或其他写入命令。',
         '只有当用户当前明确要求开发、实现、修复、继续任务、深度调研、对标复刻或提交时，才运行 openprd loop --run、openprd tasks --advance、openprd discovery --advance、commit/push 等执行命令。',
-        '代码修改完成后、最终回复前，针对本轮实际 touched code files 运行 openprd dev-check . <file...>；若出现需要关注的文件，最终回复必须以 **后续建议** 为标题，直接复用 dev-check 生成的 Markdown 表格，列出影响对象、关注程度、规模信号、预警原因、本次处理结果和后续建议，并按 🔴 → 🟠 → 🟡 排序；不要把“关注程度”列改写成纯 emoji，必须保留例如“🟠 中风险｜建议优先关注”这类完整标签；如果你改写了“预警原因 / 本次处理结果 / 后续建议”，先用 `node scripts/dev-check-wrapup-copy.mjs --validate` 校验每格不超过 20 字；若报错，按提示缩短后重试。',
+        '代码修改完成后、最终回复前，针对本轮实际 touched code files 运行 openprd dev-check . <file...>；若出现需要关注的文件：自动优化开启（默认）时，先在本轮完成高内聚低耦合拆分（不丢功能、行为不变、拆完重跑测试），最终回复以 **OpenPRD 自动优化报告** 为标题直接复用 dev-check 生成的 Markdown 表格（列：影响对象、问题级别、源文件规模、优化原因、本次处理结果、后续建议），并附自动优化开关确认一句话；自动优化关闭时，以 **后续建议** 为标题复用表格（列：影响对象、关注程度、规模信号、预警原因、本次处理结果、后续建议）。两种模式都按 🔴 → 🟠 → 🟡 排序；不要把“问题级别／关注程度”列改写成纯 emoji，必须保留例如“🟠 中风险｜建议优先关注”这类完整标签；如果你改写了表格文案，先用 `node scripts/dev-check-wrapup-copy.mjs --validate` 校验每格不超过 20 字；若报错，按提示缩短后重试。',
         '大界面改动的效果图先当候选效果图；出图后主动确认是否符合预期、是否纳入后续效果图/实现截图对比、是否按此继续实现。只有确认后，才把选定方向、整张图或其中子图整理到 `.openprd/harness/visual-reviews/` 并进入大 UI 实现。',
-        '涉及界面、页面、视觉、样式或前端体验时，已有确认参考图才运行 openprd visual-compare . --reference <效果图> --actual <实现截图>；如果一张参考图里有多个子图/对象/网格，先运行 openprd visual-prepare . --reference <效果图> --grid <列>x<行> 或 --boxes <plan.json>，确认 contact sheet 后再逐项对比。没有明确参考图时先判断新建还是修改：新建界面走实现前 3 方向方案评审；修改既有界面则动手前先截修改前截图，完成后运行 openprd visual-compare . --before <修改前截图> --after <修改后截图>；如果并行试了多个优化方向，再补一份 openprd visual-compare . --board <parallel-board.json>。用户后续如果说“跟效果图”“不一致”“好丑”“复刻”，不能只口头说对比过了，至少产出一份 visual-compare / focus-board / parallel-board 证据图。',
+        '涉及界面、页面、视觉、样式或前端体验时，已有确认参考图才运行 openprd visual-compare . --reference <效果图> --actual <实现截图> --locale <zh-CN|en>；如果一张参考图里有多个子图/对象/网格，先运行 openprd visual-prepare . --reference <效果图> --grid <列>x<行> 或 --boxes <plan.json>，确认 contact sheet 后再逐项对比。没有明确参考图时先判断新建还是修改：新建界面走实现前 3 方向方案评审；修改既有界面则动手前先截修改前截图，完成后运行 openprd visual-compare . --before <修改前截图> --after <修改后截图> --locale <zh-CN|en>；如果并行试了多个优化方向，再补一份 openprd visual-compare . --board <parallel-board.json> --locale <zh-CN|en>。普通截图、Computer/Browser/Playwright 实测截图只能作为原始素材，收口前要补 openprd visual-compare . --board <verification-board.json> --locale <zh-CN|en> 的截图实测证据板。新开发或修改同构列表、卡片、网格、表格时，或用户反馈没对齐/排版漂移时，还要补 openprd visual-compare . --board <alignment-board.json> --locale <zh-CN|en> 的对齐辅助线证据板，同时量测容器轨道和标题/副标题/描述/标签/状态/价格/按钮/图标等内部内容槽位的 x/y/宽高/baseline spread。单个素材/图标/头像/徽标/按钮图形/图片内部居中、偏心或视觉重心判断时，还要补 openprd visual-compare . --board <centering-board.json> --locale <zh-CN|en> 的内部居中证据板，同时量测画布中心、主体外接框中心和视觉重心偏移。用户后续如果说“跟效果图”“不一致”“好丑”“复刻”，不能只口头说对比过了，至少产出一份 visual-compare / focus-board / parallel-board / verification-board / alignment-board / centering-board 证据图。',
         '发现可沉淀项时不要中途打断任务：代码扩展识别这类白名单工具补全会自动应用并记录；用户偏好、项目协作规矩和 OpenPrd 默认行为先记录为候选，收工时运行 openprd grow . --review 集中确认。',
         '维护 OpenPrd 本身且涉及配置类能力时，先判断是否应纳入 openprd grow；高置信可成长默认纳入，不确定则主动询问用户。',
         '涉及后端、脚本、Agent、工具链、服务或数据处理变更时，把 CLI 与 API 视为同级接入面：同步检查命令入口、参数、输出契约、help/doctor/dry-run/status 与接口协议、返回结构、身份边界是否受影响，并更新 docs/basic/backend-structure.md 或明确写不适用原因。',
@@ -2979,16 +3692,17 @@ function contextMessage(cwd, intent = null, gate = null, progress = null) {
       knowledgeSkillReminder(run.parsed),
       'OpenPrd 上下文只是建议，不是自动执行指令。请先判断用户当前意图。',
       lightweightRequirementMessage(intent),
-      visualMockupMessage(intent),
-      learningReviewMessage(),
+      visualMockupMessage(intent, cwd),
+      canvasCollaborationMessage(intent),
+      learningReviewMessage(intent),
       largeUiVisualDirectionMessage(),
       visualLocalAdjustmentMessage(),
       requirementRoutingSummary(),
       '如果用户只是要求看看、规划、分析、审查、解释影响或列出文件，请保持只读并基于证据回答；不要运行 OpenPrd loop、任务推进、discovery 推进、commit 或其他写入命令。',
       '只有当用户当前明确要求开发、实现、修复、继续任务、深度调研、对标复刻或提交时，才运行 openprd loop --run、openprd tasks --advance、openprd discovery --advance、commit/push 等执行命令。',
-      '代码修改完成后、最终回复前，针对本轮实际 touched code files 运行 openprd dev-check . <file...>；若出现需要关注的文件，最终回复必须以 **后续建议** 为标题，直接复用 dev-check 生成的 Markdown 表格，列出影响对象、关注程度、规模信号、预警原因、本次处理结果和后续建议，并按 🔴 → 🟠 → 🟡 排序；不要把“关注程度”列改写成纯 emoji，必须保留例如“🟠 中风险｜建议优先关注”这类完整标签；如果你改写了“预警原因 / 本次处理结果 / 后续建议”，先用 `node scripts/dev-check-wrapup-copy.mjs --validate` 校验每格不超过 20 字；若报错，按提示缩短后重试。',
+      '代码修改完成后、最终回复前，针对本轮实际 touched code files 运行 openprd dev-check . <file...>；若出现需要关注的文件：自动优化开启（默认）时，先在本轮完成高内聚低耦合拆分（不丢功能、行为不变、拆完重跑测试），最终回复以 **OpenPRD 自动优化报告** 为标题直接复用 dev-check 生成的 Markdown 表格（列：影响对象、问题级别、源文件规模、优化原因、本次处理结果、后续建议），并附自动优化开关确认一句话；自动优化关闭时，以 **后续建议** 为标题复用表格（列：影响对象、关注程度、规模信号、预警原因、本次处理结果、后续建议）。两种模式都按 🔴 → 🟠 → 🟡 排序；不要把“问题级别／关注程度”列改写成纯 emoji，必须保留例如“🟠 中风险｜建议优先关注”这类完整标签；如果你改写了表格文案，先用 `node scripts/dev-check-wrapup-copy.mjs --validate` 校验每格不超过 20 字；若报错，按提示缩短后重试。',
       '大界面改动的效果图先当候选效果图；出图后主动确认是否符合预期、是否纳入后续效果图/实现截图对比、是否按此继续实现。只有确认后，才把选定方向、整张图或其中子图整理到 `.openprd/harness/visual-reviews/` 并进入大 UI 实现。',
-      '涉及界面、页面、视觉、样式或前端体验时，已有确认参考图才运行 openprd visual-compare . --reference <效果图> --actual <实现截图>；如果一张参考图里有多个子图/对象/网格，先运行 openprd visual-prepare . --reference <效果图> --grid <列>x<行> 或 --boxes <plan.json>，确认 contact sheet 后再逐项对比。没有明确参考图时先判断新建还是修改：新建界面走实现前 3 方向方案评审；修改既有界面则动手前先截修改前截图，完成后运行 openprd visual-compare . --before <修改前截图> --after <修改后截图>；如果并行试了多个优化方向，再补一份 openprd visual-compare . --board <parallel-board.json>。用户后续如果说“跟效果图”“不一致”“好丑”“复刻”，不能只口头说对比过了，至少产出一份 visual-compare / focus-board / parallel-board 证据图。',
+      '涉及界面、页面、视觉、样式或前端体验时，已有确认参考图才运行 openprd visual-compare . --reference <效果图> --actual <实现截图> --locale <zh-CN|en>；如果一张参考图里有多个子图/对象/网格，先运行 openprd visual-prepare . --reference <效果图> --grid <列>x<行> 或 --boxes <plan.json>，确认 contact sheet 后再逐项对比。没有明确参考图时先判断新建还是修改：新建界面走实现前 3 方向方案评审；修改既有界面则动手前先截修改前截图，完成后运行 openprd visual-compare . --before <修改前截图> --after <修改后截图> --locale <zh-CN|en>；如果并行试了多个优化方向，再补一份 openprd visual-compare . --board <parallel-board.json> --locale <zh-CN|en>。普通截图、Computer/Browser/Playwright 实测截图只能作为原始素材，收口前要补 openprd visual-compare . --board <verification-board.json> --locale <zh-CN|en> 的截图实测证据板。新开发或修改同构列表、卡片、网格、表格时，或用户反馈没对齐/排版漂移时，还要补 openprd visual-compare . --board <alignment-board.json> --locale <zh-CN|en> 的对齐辅助线证据板，同时量测容器轨道和标题/副标题/描述/标签/状态/价格/按钮/图标等内部内容槽位的 x/y/宽高/baseline spread。单个素材/图标/头像/徽标/按钮图形/图片内部居中、偏心或视觉重心判断时，还要补 openprd visual-compare . --board <centering-board.json> --locale <zh-CN|en> 的内部居中证据板，同时量测画布中心、主体外接框中心和视觉重心偏移。用户后续如果说“跟效果图”“不一致”“好丑”“复刻”，不能只口头说对比过了，至少产出一份 visual-compare / focus-board / parallel-board / verification-board / alignment-board / centering-board 证据图。',
       '发现可沉淀项时不要中途打断任务：代码扩展识别这类白名单工具补全会自动应用并记录；用户偏好、项目协作规矩和 OpenPrd 默认行为先记录为候选，收工时运行 openprd grow . --review 集中确认。',
       '维护 OpenPrd 本身且涉及配置类能力时，先判断是否应纳入 openprd grow；高置信可成长默认纳入，不确定则主动询问用户。',
       '涉及后端、脚本、Agent、工具链、服务或数据处理变更时，把 CLI 与 API 视为同级接入面：同步检查命令入口、参数、输出契约、help/doctor/dry-run/status 与接口协议、返回结构、身份边界是否受影响，并更新 docs/basic/backend-structure.md 或明确写不适用原因。',
@@ -3006,11 +3720,13 @@ function contextMessage(cwd, intent = null, gate = null, progress = null) {
     next.ok ? next.stdout : '',
     gateMessage,
     lightweightRequirementMessage(intent),
-    visualMockupMessage(intent),
+    visualMockupMessage(intent, cwd),
+    canvasCollaborationMessage(intent),
+    learningReviewMessage(intent),
     largeUiVisualDirectionMessage(intent),
     requirementRoutingSummary(),
     'OpenPrd 下一步只是建议。规划、分析、审查类请求保持只读；只有用户当前明确要求开发、深度调研、对标复刻或继续任务时才执行。',
-    '代码修改完成后、最终回复前，针对本轮实际 touched code files 运行 openprd dev-check . <file...>；若出现需要关注的文件，最终回复必须以 **后续建议** 为标题，直接复用 dev-check 生成的 Markdown 表格，列出影响对象、关注程度、规模信号、预警原因、本次处理结果和后续建议，并按 🔴 → 🟠 → 🟡 排序；不要把“关注程度”列改写成纯 emoji，必须保留例如“🟠 中风险｜建议优先关注”这类完整标签；如果你改写了“预警原因 / 本次处理结果 / 后续建议”，先用 `node scripts/dev-check-wrapup-copy.mjs --validate` 校验每格不超过 20 字；若报错，按提示缩短后重试。',
+    '代码修改完成后、最终回复前，针对本轮实际 touched code files 运行 openprd dev-check . <file...>；若出现需要关注的文件：自动优化开启（默认）时，先在本轮完成高内聚低耦合拆分（不丢功能、行为不变、拆完重跑测试），最终回复以 **OpenPRD 自动优化报告** 为标题直接复用 dev-check 生成的 Markdown 表格（列：影响对象、问题级别、源文件规模、优化原因、本次处理结果、后续建议），并附自动优化开关确认一句话；自动优化关闭时，以 **后续建议** 为标题复用表格（列：影响对象、关注程度、规模信号、预警原因、本次处理结果、后续建议）。两种模式都按 🔴 → 🟠 → 🟡 排序；不要把“问题级别／关注程度”列改写成纯 emoji，必须保留例如“🟠 中风险｜建议优先关注”这类完整标签；如果你改写了表格文案，先用 `node scripts/dev-check-wrapup-copy.mjs --validate` 校验每格不超过 20 字；若报错，按提示缩短后重试。',
     '发现可沉淀项时不要中途打断任务：代码扩展识别这类白名单工具补全会自动应用并记录；用户偏好、项目协作规矩和 OpenPrd 默认行为先记录为候选，收工时运行 openprd grow . --review 集中确认。',
     '维护 OpenPrd 本身且涉及配置类能力时，先判断是否应纳入 openprd grow；高置信可成长默认纳入，不确定则主动询问用户。',
     '涉及后端、脚本、Agent、工具链、服务或数据处理变更时，把 CLI 与 API 视为同级接入面，并同步更新 docs/basic/backend-structure.md 或明确写不适用原因。',
@@ -3037,6 +3753,7 @@ function shouldInjectOpenPrdContext(payload) {
     && !intent.publicRepoResearchRequest
     && !intent.externalTechResearchRequest
     && !intent.skillWorkflowEditRequest
+    && !intent.learningMaterialRequest
   ) {
     return false;
   }
@@ -3091,6 +3808,11 @@ function classifyRisk(payload) {
     /yarn\s+npm\s+publish/,
     /gh\s+release/,
     /rm\s+-rf/,
+    /\b(?:ssh|scp|rsync)\b[^\n]*(?:prod|production|线上|生产|云端|server|remote)/,
+    /\b(?:kubectl|helm)\b[^\n]*(?:apply|patch|set|delete|rollout|scale|exec)[^\n]*(?:prod|production|线上|生产|云端|cluster)/,
+    /\b(?:vercel|wrangler|fly|flyctl|railway|firebase)\b[^\n]*(?:deploy|up)[^\n]*(?:--prod|prod|production|线上|生产)/,
+    /\bsupabase\s+db\s+push\b[^\n]*(?:--linked|--db-url|prod|production|线上|生产)/,
+    /\bcurl\b[^\n]*(?:-x|--request)\s*(?:post|put|patch|delete)\b[^\n]*(?:prod|production|线上|生产|云端|api\.)/,
     /openprd\s+freeze\b/,
     /openprd\s+handoff\b/,
     /openprd\s+change\s+.*--apply/,
@@ -3224,6 +3946,102 @@ function hasRecentArtifacts(root, relativeDir, turnState, matcher) {
   return collectRecentArtifactPaths(dir, startedAtMs, matcher, []).length > 0;
 }
 
+function hasRecentVisualReviewArtifact(root, turnState) {
+  return hasRecentArtifacts(root, '.openprd/harness/visual-reviews', turnState, (artifactPath) => {
+    const normalized = artifactPath.split(path.sep).join('/');
+    return /\.(?:jpe?g|png|webp|json)$/i.test(normalized)
+      && /visual-(?:compare|before-after|focus-board|parallel-board|verification-board|alignment-board|centering-board)|reference-actual|before-after|focus-board|parallel-board|verification-board|alignment-board|centering-board|center-board/i.test(normalized);
+  });
+}
+
+function isVisualEvidenceIntent(intent = null) {
+  const text = String(intent?.promptText || '');
+  return isFrontendTaskIntent(intent)
+    || hasLightweightUiVisualSignal(text)
+    || /(界面|页面|前端|视觉|样式|布局|信息架构|效果图|设计稿|参考图|实现截图|视觉对比|视觉评审|截图|实测|Computer\s*Use|Browser|Playwright|复刻|不一致|好丑|没对齐|没有对齐|不对齐|对不齐|对不上|不像|对齐有问题|对齐问题|排版漂移|布局漂移|左右偏差|上下偏差|横向偏差|竖向偏差|同构|重复单元|列表卡片|卡片列表|卡片网格|网格卡片|网格列表|列表网格|对齐辅助线|内容槽位|内部槽位|内部居中|视觉重心|主体外接框|画布中心|偏心|不居中|没居中|图标内部|图片内部|素材内部)/i.test(text);
+}
+
+function visualEvidenceStopReminder(root, turnState, stopIntent) {
+  if (stopIntent?.visualMockupRequest) {
+    return null;
+  }
+  const touchedFiles = Array.isArray(turnState?.touchedFiles) ? turnState.touchedFiles : [];
+  const frontendTouched = touchedFiles.some((file) => looksLikeFrontendImplementationFile(file));
+  const rawScreenshotObserved = hasTurnReviewSignal(turnState, 'visual-raw-screenshot');
+  const visualArtifactObserved = hasTurnReviewSignal(turnState, 'visual-review-artifact')
+    || hasTurnReviewSignal(turnState, 'visual-verification-board')
+    || hasTurnReviewSignal(turnState, 'visual-alignment-board')
+    || hasTurnReviewSignal(turnState, 'visual-centering-board')
+    || hasRecentVisualReviewArtifact(root, turnState);
+  const needsVisualEvidence = isVisualEvidenceIntent(stopIntent)
+    && (rawScreenshotObserved || frontendTouched || /截图|实测|Computer\s*Use|Browser|Playwright/i.test(String(stopIntent?.promptText || '')));
+  if (!needsVisualEvidence || visualArtifactObserved) {
+    return null;
+  }
+  const preferred = rawScreenshotObserved
+    ? '`openprd visual-compare . --board <verification-board.json> --locale <zh-CN|en>`，把普通截图、Computer/Browser/Playwright 实测路径和检查点拼成截图实测证据板'
+    : '有参考图时用 `--reference/--actual`，无参考且改既有界面用 `--before/--after`，普通截图实测用 `--board <verification-board.json>`，同构列表/卡片/网格/表格用 `--board <alignment-board.json>`，单元素内部居中/视觉重心用 `--board <centering-board.json>`';
+  return [
+    'OpenPrd 在本轮收工回顾里发现 UI/视觉任务已有截图、实测或前端改动，但还没有本轮拼图证据。',
+    '即便只是卡片宽度、间距、留白、对齐、颜色、圆角、字号这类轻量可视优化，也需要留下视觉证据；build、package 和 dev-check 不能替代视觉收口。',
+    '如果这轮新开发或修改了同构列表、卡片、网格、表格，或用户反馈元素没对齐，要截真实页面、叠辅助线，同时量容器轨道和标题/副标题/描述/标签/状态/价格/按钮/图标等内部内容槽位的 spread，并生成 alignment-board；只量外框、列宽或行顶不算完整对齐验收。',
+    '如果这轮判断的是单个素材、图标、头像、徽标、按钮图形或图片内部是否居中，要截取或裁出目标元素，用 centering-board 量画布中心、主体外接框中心和视觉重心偏移；单张截图或主观“看起来居中”不算完整居中验收。',
+    '视觉证据还要检查本轮审美意图是否成立：气质、层级、颜色、字号、间距、表面角色和记忆点不能只靠口头描述。',
+    `普通截图和 Computer 实测截图只能作为原始素材，不能单独替代视觉收口。请先运行 ${preferred}。`,
+    '补齐前不要宣称界面视觉已经完成；可以如实说功能或代码已改，但视觉拼图证据还没补齐。',
+  ].join('\n');
+}
+
+function recentLearningArtifactPaths(root, turnState, matcher) {
+  const dir = path.join(root, '.openprd/learning/archive');
+  const startedAtMs = parseShanghaiTimestamp(turnState?.startedAt);
+  return collectRecentArtifactPaths(dir, startedAtMs, matcher, []);
+}
+
+function hasRecentLearningSkeletonArtifact(root, turnState) {
+  return recentLearningArtifactPaths(root, turnState, (artifactPath) => {
+    const normalized = artifactPath.split(path.sep).join('/');
+    return /\/(?:agent-prompt\.md|reader\.html|learning-package\.json|learning-content\.json)$/i.test(normalized);
+  }).length > 0;
+}
+
+function hasRecentAuthoredLearningReaderArtifact(root, turnState) {
+  const contentPaths = recentLearningArtifactPaths(root, turnState, (artifactPath) => artifactPath.endsWith('learning-content.json'));
+  return contentPaths.some((contentPath) => {
+    const content = readJsonSync(contentPath, null);
+    if (!content || content.authoringStatus !== 'agent-authored') {
+      return false;
+    }
+    if (!Array.isArray(content.chapters) || content.chapters.length === 0) {
+      return false;
+    }
+    const readerPath = path.join(path.dirname(contentPath), 'reader.html');
+    return fs.existsSync(readerPath);
+  });
+}
+
+function learningMaterialStopReminder(root, turnState, stopIntent) {
+  if (!stopIntent?.learningMaterialRequest) {
+    return null;
+  }
+  if (hasRecentAuthoredLearningReaderArtifact(root, turnState)) {
+    return null;
+  }
+  const command = learningReviewCommand(stopIntent);
+  if (!hasRecentLearningSkeletonArtifact(root, turnState)) {
+    return [
+      'OpenPrd 在本轮收工回顾里识别到用户要的是学习型交付物，但还没有看到本轮新生成的学习包阅读器。',
+      '请先运行 `' + command + '`，生成 `.openprd/learning/archive/<packageId>/` 下的证据清单、Agent 写作提示、learning-content.json 骨架和 reader.html。',
+      '这类请求按产物形态和长期阅读/教学目的判断，不是固定关键词表；普通 Markdown 只能作为辅助讲义，不能替代 OpenPrd reader。',
+    ].join('\n');
+  }
+  return [
+    'OpenPrd 在本轮收工回顾里发现学习包骨架已经出现，但还没有本轮 Agent-authored 的最终 reader 内容。',
+    '请读取 `.openprd/learning/archive/<packageId>/agent-prompt.md`，基于证据写入 `learning-content.json`，再运行 `openprd learn . --content-json <file> --open` 重新渲染。',
+    '完成前不要把聊天里的普通 Markdown 成稿当作学习材料交付完成。',
+  ].join('\n');
+}
+
 function closeoutVerificationReminder(root, turnState, stopIntent) {
   const touchedFiles = Array.isArray(turnState?.touchedFiles) ? turnState.touchedFiles : [];
   if (touchedFiles.length === 0) {
@@ -3287,21 +4105,32 @@ function blockHook(reason) {
 
 function handle(eventName, cwd, payload) {
   const root = findProjectRoot(cwd);
+  const sessionId = sessionIdFor(payload);
+  const automationDecision = automationBypassDecision(root, eventName, payload, sessionId);
+  if (automationDecision.optIn) {
+    rememberAutomationMode(root, sessionId, payload, automationDecision.signals, 'openprd-maintenance');
+  } else if (automationDecision.bypass) {
+    rememberAutomationMode(root, sessionId, payload, automationDecision.signals, 'automation');
+    return allowHook();
+  }
   ensureHarness(root);
   const risk = classifyRisk(payload);
   const fingerprint = fingerprintFor(eventName, payload, risk);
   const duplicate = isDuplicate(root, fingerprint);
-  const sessionId = sessionIdFor(payload);
+  const runtimeEnvironment = recordRuntimeEnvironment(root, eventName, payload, sessionId);
   const baseEvent = {
     eventName,
     risk,
     fingerprint,
     duplicate,
     sessionId,
+    runtimeEnvironment: runtimeEnvironment.active,
     preview: preview(payloadText(payload)),
   };
 
   if (eventName === 'SessionStart') {
+    appendEvent(root, { ...baseEvent, outcome: 'session-start' });
+    updateHookState(root, baseEvent);
     return allowHook();
   }
 
@@ -3371,12 +4200,45 @@ function handle(eventName, cwd, payload) {
         updateHookState(root, baseEvent);
         return allowHook(composeHookContext(root, intent, gate, progress, sessionId));
       }
+      const repeatedConfirmationSignal = intent.confirmation
+        || shortAffirmative
+        || (clarificationFollowup && /(确认|继续|落地|开始|推进|按(这个|你的)|就这么|开做)/.test(stripMarkdown(prompt)));
+      if (
+        repeatedConfirmationSignal
+        && intent.reviewDecision !== 'needs-revision'
+        && !intent.reviewCommand
+        && gateHasClarificationConfirmation(gate)
+        && !reviewPolicyAllowsSilentRecord(requirementApprovalPolicy(gate))
+      ) {
+        gate = escalateRequirementGateApproval(root, prompt, gate, sessionId);
+        progress = evaluateRequirementGateProgress(root, sessionId);
+        if (canAutoAuthorizeRequirementExecution(gate, progress)) {
+          gate = authorizeRequirementGateExecution(root, prompt, sessionId, {
+            reason: 'repeated-user-confirmation-after-summary',
+          });
+          progress = null;
+        }
+        appendEvent(root, { ...baseEvent, outcome: 'requirement-gate-approval-escalated' });
+        recordRunHook(root, baseEvent, 'requirement-gate-approval-escalated');
+        updateHookState(root, baseEvent);
+        return allowHook(composeHookContext(root, intent, gate, progress, sessionId));
+      }
       if (intent.reviewDecision) {
         const authorization = reviewActionAuthorizationFor(intent, progress, prompt);
         gate = holdRequirementGate(root, prompt, progress, sessionId, {
           status: authorization ? 'review-confirmation-authorized' : progress.nextStep,
           reviewActionAuthorization: authorization,
         });
+        if (
+          authorization
+          && intent.reviewDecision === 'confirmed'
+          && (authorization.continueAfterReview || gateHasClarificationConfirmation(gate))
+        ) {
+          // 用户确认评审稿时要么同句要求继续执行，要么此前已确认过需求摘要（重复确认）：
+          // 一次确认解锁整条链，后续 change/tasks/实现不再停下索取确认。
+          gate = escalateRequirementGateApproval(root, prompt, gate, sessionId);
+          progress = evaluateRequirementGateProgress(root, sessionId);
+        }
         const outcome = authorization ? 'requirement-gate-review-authorized' : 'requirement-gate-awaiting-review';
         appendEvent(root, {
           ...baseEvent,
@@ -3453,6 +4315,14 @@ function handle(eventName, cwd, payload) {
       ].join('\n'));
     }
     if (researchGate?.active && isMutationPayload(payload, risk) && !authorizedReviewMutation) {
+      const researchBlockStreak = bumpProcessGateBlockCount(root, 'external-evidence');
+      if (researchBlockStreak > PROCESS_GATE_FUSE_LIMIT) {
+        appendEvent(root, { ...baseEvent, outcome: 'research-gate-fuse-open' });
+        recordRunHook(root, baseEvent, 'research-gate-fuse-open');
+        updateHookState(root, baseEvent);
+        recordTouchedFiles(root, payload);
+        return allowHook(processGateFuseMessage('external-evidence', researchBlockStreak, researchGateMessage(researchGate)));
+      }
       appendEvent(root, { ...baseEvent, outcome: 'blocked-research-gate' });
       recordRunHook(root, baseEvent, 'blocked-research-gate');
       updateHookState(root, baseEvent);
@@ -3470,6 +4340,13 @@ function handle(eventName, cwd, payload) {
         'Use the `secrets-vault` skill first and only read the minimum required fields; do not read the original vault file directly.',
       ].join('\n'));
     }
+    const autonomyRisk = detectHighRiskAutonomyMutation(root, payload, turnIntent, risk);
+    if (autonomyRisk && !hasExplicitAutonomyRiskApproval(turnIntent)) {
+      appendEvent(root, { ...baseEvent, outcome: 'blocked-high-risk-autonomy', autonomyRisk });
+      recordRunHook(root, baseEvent, 'blocked-high-risk-autonomy');
+      updateHookState(root, baseEvent);
+      return blockHook(formatHighRiskAutonomyBlock(autonomyRisk));
+    }
     if (isBlockingRequirementGate(gate) && isMutationPayload(payload, risk) && !isAllowedDuringRequirementGate(root, payload, gate, sessionId)) {
       const reviewMark = parseReviewMarkCommand(commandText(payload));
       const approvalPolicy = requirementApprovalPolicy(gate);
@@ -3482,13 +4359,13 @@ function handle(eventName, cwd, payload) {
               : 'OpenPrd blocked review status writing because the current user message did not explicitly confirm this exact PRD review artifact.',
             silentRecord
               ? 'This lane is in silent-record mode: you may record only the exact current version, digest, and work unit, then continue without another user stop.'
-              : 'Only record PRD review confirmation from the copied review command or an explicit review approval tied to the current version, digest, and work unit.',
+              : 'A plain natural-language user confirmation of the current review (for example "确认这版，继续") is sufficient; the hook binds it to the exact version, digest, and work unit automatically. NEVER ask the user to paste a digest, work-unit id, or a full openprd command.',
             progress?.review?.versionId
-              ? `Current review artifact: version ${progress.review.versionId}, digest ${progress.review.digest}, work unit ${progress.review.workUnitId}.`
+              ? `Current review artifact: version ${progress.review.versionId}, digest ${progress.review.digest}, work unit ${progress.review.workUnitId}. Fill these exact values into the review --mark command yourself; do not ask the user for them.`
               : 'Current review artifact has not been synthesized yet. Run openprd synthesize . --open first.',
             silentRecord
               ? 'Do not mark any stale or different review artifact; only the exact current artifact is allowed.'
-              : 'Implementation approval and review confirmation are different gates; do not treat "可以开做", plain "请帮我实现/继续实现", or similar wording as permission to run openprd review --mark confirmed.',
+              : 'Implementation approval and review confirmation are different gates; do not treat "可以开做", plain "请帮我实现/继续实现", or similar wording as permission to run openprd review --mark confirmed. But if the latest user message did confirm this review, retry the mark command with the exact current artifact values above instead of asking the user again.',
           ].filter(Boolean).join('\n')
         : [
             'OpenPrd blocked a mutating action because the requirement gate is still active.',
@@ -3512,6 +4389,14 @@ function handle(eventName, cwd, payload) {
               ? 'Decision-point order: because the user explicitly waived any confirmation stop, you may skip requirement-summary confirmation, write back requirement facts, synthesize the PRD, record the exact stable review artifact, generate the OpenPrd change, prepare the task breakdown, then implement within the confirmed scope.'
               : 'Decision-point order: clarify the requirement, summarize it in chat using 需求判断 / 需求理解 / 功能范围 / 技术方案, prefer Markdown tables for 功能范围 and 技术方案, and if the ask still looks like 0-to-1 validation also surface 第一批最容易触达的社区或种子用户、你为什么算这个社区里的自己人、当前替代方案和痛点证据、先怎么手工交付、手工作战卡怎么写、能不能先用 spreadsheet / 表单 / no-code 跑起来、什么承诺才算真需求、有没有 10 个样本和更强付费信号、最低成本先验证什么、达到什么条件才允许产品化、增长阶段守什么纪律、以及验证阶段怎样先活下来; wait for the user to confirm that requirement summary, write back only confirmed facts, synthesize the PRD, wait for a human review decision on the stable artifact, generate the OpenPrd change, prepare the task breakdown, then implement within the confirmed scope.',
           ].join('\n');
+      const requirementBlockStreak = bumpProcessGateBlockCount(root, 'requirement-intake');
+      if (requirementBlockStreak > PROCESS_GATE_FUSE_LIMIT) {
+        appendEvent(root, { ...baseEvent, outcome: 'requirement-gate-fuse-open' });
+        recordRunHook(root, baseEvent, 'requirement-gate-fuse-open');
+        updateHookState(root, baseEvent);
+        recordTouchedFiles(root, payload);
+        return allowHook(processGateFuseMessage('requirement-intake', requirementBlockStreak, reason));
+      }
       appendEvent(root, { ...baseEvent, outcome: 'blocked-requirement-intake' });
       recordRunHook(root, baseEvent, 'blocked-requirement-intake');
       updateHookState(root, baseEvent);
@@ -3538,6 +4423,18 @@ function handle(eventName, cwd, payload) {
           lastFocusFiles: extractTouchedFiles(root, payload),
         }, sessionId) || patchModeGate;
       } else {
+        const patchModeBlockStreak = bumpProcessGateBlockCount(root, 'patch-mode');
+        if (patchModeBlockStreak > PROCESS_GATE_FUSE_LIMIT) {
+          appendEvent(root, { ...baseEvent, outcome: 'patch-mode-gate-fuse-open' });
+          recordRunHook(root, baseEvent, 'patch-mode-gate-fuse-open');
+          updateHookState(root, baseEvent);
+          recordTouchedFiles(root, payload);
+          return allowHook(processGateFuseMessage(
+            'patch-mode',
+            patchModeBlockStreak,
+            `下一步仍应尽快真实写入 ${patchModeGate.targetFile} 或它的 sibling draft。`,
+          ));
+        }
         appendEvent(root, {
           ...baseEvent,
           outcome: 'blocked-patch-mode-hover',
@@ -3566,6 +4463,18 @@ function handle(eventName, cwd, payload) {
     const frontendTargets = frontendImplementationTargets(root, payload);
     const designIssues = frontendDesignPreflightIssues(root, turnIntent, frontendTargets);
     if (designIssues.length > 0) {
+      const designBlockStreak = bumpProcessGateBlockCount(root, 'frontend-design-preflight');
+      if (designBlockStreak > PROCESS_GATE_FUSE_LIMIT) {
+        appendEvent(root, { ...baseEvent, outcome: 'frontend-design-gate-fuse-open' });
+        recordRunHook(root, baseEvent, 'frontend-design-gate-fuse-open');
+        updateHookState(root, baseEvent);
+        recordTouchedFiles(root, payload);
+        return allowHook(processGateFuseMessage(
+          'frontend-design-preflight',
+          designBlockStreak,
+          designIssues.map((issue) => `- ${issue.file}: ${issue.reason}`).join('\n'),
+        ));
+      }
       appendEvent(root, { ...baseEvent, outcome: 'blocked-frontend-design-preflight' });
       recordRunHook(root, baseEvent, 'blocked-frontend-design-preflight');
       updateHookState(root, baseEvent);
@@ -3598,7 +4507,7 @@ function handle(eventName, cwd, payload) {
       recordRunHook(root, baseEvent, 'allowed-medium-risk');
       updateHookState(root, baseEvent);
       recordTouchedFiles(root, payload);
-      return allowHook('OpenPrd 检测到写入动作。本轮写入完成后、最终回复前，请针对实际 touched code files 运行 openprd dev-check . <file...>；如出现需要关注的文件，最终回复必须以 **后续建议** 为标题，直接复用 dev-check 生成的 Markdown 表格，说明影响对象、关注程度、规模信号、预警原因、本次处理结果和后续建议，并按 🔴 → 🟠 → 🟡 排序；不要把“关注程度”列改写成纯 emoji，必须保留例如“🟠 中风险｜建议优先关注”这类完整标签；如果你改写了“预警原因 / 本次处理结果 / 后续建议”，先用 `node scripts/dev-check-wrapup-copy.mjs --validate` 校验每格不超过 20 字；若报错，按提示缩短后重试；如涉及界面视觉且已有参考效果图并进入实现阶段，阶段性完成后运行 openprd visual-compare . --reference <效果图> --actual <实现截图> 并查看 JPG 对比图；如果参考图来自本轮或前序 `imagegen`，先确认用户已接受它作为后续对比参考；若一张图里有多个子图、对象或网格，先运行 openprd visual-prepare . --reference <效果图> --grid <列>x<行> 或 --boxes <plan.json>，确认 contact sheet 后再逐项对比。若局部细节更重要，再补 openprd visual-compare . --board <focus-board.json>；如无参考图，先判断新建界面还是修改既有界面：新建界面应先完成 3 方向方案评审，修改既有界面确认已先截修改前截图，并在完成后运行 openprd visual-compare . --before <修改前截图> --after <修改后截图> 查看 JPG 自检图；若并行试了多个优化方向，再补 openprd visual-compare . --board <parallel-board.json>；当用户说“跟效果图”“不一致”“好丑”“复刻”时，至少给出一份视觉证据图，不要只口头判断。发现可沉淀项时不要中途打断任务，代码扩展识别这类白名单工具补全会自动应用并记录，用户偏好、项目协作规矩和 OpenPrd 默认行为留到收工时用 openprd grow . --review 集中确认；维护 OpenPrd 本身且涉及配置类能力时，先判断是否应纳入 openprd grow；声明就绪前，请同步维护 docs/basic、文件说明书、文件夹 README，以及相关 OpenPrd change/task 状态；如果涉及后端、脚本、Agent、工具链、服务或数据处理变更，还要把 CLI 与 API 视为同级接入面并更新 docs/basic/backend-structure.md。');
+      return allowHook('OpenPrd 检测到写入动作。本轮写入完成后、最终回复前，请针对实际 touched code files 运行 openprd dev-check . <file...>；如出现需要关注的文件：自动优化开启（默认）时先在本轮完成高内聚低耦合拆分（不丢功能、行为不变），最终回复以 **OpenPRD 自动优化报告** 为标题复用 dev-check 表格（列：影响对象、问题级别、源文件规模、优化原因、本次处理结果、后续建议）并附开关确认；关闭时以 **后续建议** 为标题复用表格（列：影响对象、关注程度、规模信号、预警原因、本次处理结果、后续建议）。两种模式都按 🔴 → 🟠 → 🟡 排序；不要把“问题级别／关注程度”列改写成纯 emoji，必须保留例如“🟠 中风险｜建议优先关注”这类完整标签；如果你改写了表格文案，先用 `node scripts/dev-check-wrapup-copy.mjs --validate` 校验每格不超过 20 字；若报错，按提示缩短后重试；如涉及界面视觉，包括卡片宽度、间距、留白、对齐、颜色、圆角、字号等轻量可视优化，build、package 和 dev-check 只能证明代码或构建状态，不能替代视觉证据；写入前先说明本次审美意图和记忆点，视觉证据也要检查气质、层级、颜色、字号、间距和表面角色是否成立；已有参考效果图并进入实现阶段时，阶段性完成后运行 openprd visual-compare . --reference <效果图> --actual <实现截图> --locale <zh-CN|en> 并查看 JPG 对比图；如果参考图来自本轮或前序 `imagegen`，先确认用户已接受它作为后续对比参考；若一张图里有多个子图、对象或网格，先运行 openprd visual-prepare . --reference <效果图> --grid <列>x<行> 或 --boxes <plan.json>，确认 contact sheet 后再逐项对比。若局部细节更重要，再补 openprd visual-compare . --board <focus-board.json> --locale <zh-CN|en>；如无参考图，先判断新建界面还是修改既有界面：新建界面应先完成 3 方向方案评审，修改既有界面确认已先截修改前截图，并在完成后运行 openprd visual-compare . --before <修改前截图> --after <修改后截图> --locale <zh-CN|en> 查看 JPG 自检图；若并行试了多个优化方向，再补 openprd visual-compare . --board <parallel-board.json> --locale <zh-CN|en>；若普通截图、Computer/Browser/Playwright 实测截图被用作证据，再补 openprd visual-compare . --board <verification-board.json> --locale <zh-CN|en> 的截图实测证据板；若新开发或修改同构列表、卡片、网格、表格，或用户反馈没对齐/排版漂移，再补 openprd visual-compare . --board <alignment-board.json> --locale <zh-CN|en> 的对齐辅助线证据板，截真实页面、叠辅助线，同时量容器轨道和标题/副标题/描述/标签/状态/价格/按钮/图标等内部内容槽位的 x/y/宽高/baseline spread；只量外框、列宽或行顶不算完整对齐验收；当用户说“跟效果图”“不一致”“好丑”“复刻”时，至少给出一份视觉证据图，不要只口头判断。发现可沉淀项时不要中途打断任务，代码扩展识别这类白名单工具补全会自动应用并记录，用户偏好、项目协作规矩和 OpenPrd 默认行为留到收工时用 openprd grow . --review 集中确认；维护 OpenPrd 本身且涉及配置类能力时，先判断是否应纳入 openprd grow；声明就绪前，请同步维护 docs/basic、文件说明书、文件夹 README，以及相关 OpenPrd change/task 状态；如果涉及后端、脚本、Agent、工具链、服务或数据处理变更，还要把 CLI 与 API 视为同级接入面并更新 docs/basic/backend-structure.md。');
     }
     return allowHook();
   }
@@ -3606,6 +4515,9 @@ function handle(eventName, cwd, payload) {
   if (eventName === 'PostToolUse') {
     const text = payloadText(payload);
     const failed = /command not found|no such file|permission denied|failed|error|exception/i.test(text);
+    if (!failed) {
+      recordVisualEvidenceSignals(root, payload);
+    }
     if (!failed) {
       return allowHook();
     }
@@ -3637,8 +4549,8 @@ function handle(eventName, cwd, payload) {
     }
     if (stopIntent.visualMockupRequest && (!Array.isArray(turnState.touchedFiles) || turnState.touchedFiles.length === 0)) {
       return allowHook([
-        'OpenPrd 生图事实对齐提醒：如果这轮要汇报图片结果、失败或限流，请确保它来自一次实际的 `imagegen` 调用。',
-        '未实际调用 `imagegen` 前，不要声称“生图限流”“生图失败”或“已经生成图片结果”；若本轮还没调用，请如实说明仍未开始或尚未完成生图。',
+        'OpenPrd 生图事实对齐提醒：如果这轮要汇报图片结果、失败或限流，请确保它来自一次实际的生图工具调用（Codex=`imagegen`，Cursor=`GenerateImage`，或用户已确认的偏好工具）。',
+        '未实际调用生图工具前，不要声称“生图限流”“生图失败”或“已经生成图片结果”；若本轮还没调用，请如实说明仍未开始或尚未完成生图。',
         '如果这轮确实已经生图，不要默认把结果登记到 `.openprd/harness/visual-reviews/` 或直接当成验收参考；先把它当候选效果图。',
         '若用户还要继续做实现，主动追问三件事：是否符合预期、是否纳入后续效果图/实现截图对比、是否按此继续后续实现；未确认前不要自动进入实现，也不要声称参考图已定。',
       ].join('\n'));
@@ -3664,6 +4576,14 @@ function handle(eventName, cwd, payload) {
         ].join('\n'));
       }
     }
+    const visualReminder = visualEvidenceStopReminder(root, turnState, stopIntent);
+    if (visualReminder) {
+      return allowHook(visualReminder);
+    }
+    const learningReminder = learningMaterialStopReminder(root, turnState, stopIntent);
+    if (learningReminder) {
+      return allowHook(learningReminder);
+    }
     const devCheckMessage = devCheckWrapUpMessage(root, turnState);
     if (devCheckMessage) {
       return allowHook(devCheckMessage);