@openprd/cli 0.1.19 → 0.1.22

package/skills/openprd-shared/SKILL.md

@@ -33,7 +33,7 @@ description: OpenPrd 工作区与产物的共用守则。凡是需要查看、
    - 只读命令：`status`、`validate`、`next`、`history`、`diff`、`interview`、`doctor`
    - 写入命令：`init`、`setup`、`update`、`classify`、`synthesize`、`diagram`、`release`、`freeze`、`handoff`
    - 执行命令：`loop --run`、`tasks --advance`、`discovery --advance`、`loop --finish --commit`、git commit、git push，必须有当前用户明确执行意图。
-   - 实现授权不包含云端热修复、生产远端写入、业务兜底、写死逻辑、客户端/服务端补业务数据或缓存补行；这些动作需要当前用户单独明确批准，并给出本地源码/配置/迁移同步与回滚计划。
+   - 用户要求实现、继续、修复、部署或发布时，OpenPrd 不再追加授权门禁。风险词和动作类型只用于提醒 Agent 优先选择配置化、可回滚、幂等或标准状态机方案，不触发 OpenPrd 阻断或用户确认；是否需要确认由当前 Agent 依据宿主安全规则和真实上下文自行判断，禁止要求用户复述固定授权口令。
 3. 不要虚构 OpenPrd 命令或产物类型。
    - 不确定时先对照 `openprd --help`。
 4. 共用规则放在这里，领域规则放到对应 skill。
@@ -99,8 +99,8 @@ description: OpenPrd 工作区与产物的共用守则。凡是需要查看、
 13. 大界面改动实现前必须先完成视觉方案评审。
    - 触发条件：会明显改变页面信息架构、主视觉、核心布局、关键路径、组件层级/密度，或用户需要先选择设计方向。
    - 位置：需求分流之后、PRD 定稿或实现开工之前；它不是 `review.html`，也不是实现后的 `visual-compare`。
-   - 步骤：已有界面时用 Codex Computer Use 进入产品内对应功能并截当前真实界面；冷启动没有现有界面时，基于已确认 PRD、用户群体、第一版切片、视觉目标、气质端点和记忆点生成设计 brief；用 `imagegen`（Codex 原生 Image 2）基于截图或设计 brief 至少生成 3 个不同设计思想方向；每个方向都要有具体审美主张和 anti-slop 自检；把效果图横向拼成一张大图，每张左上角标注 1/2/3，先作为候选效果图展示。
-   - 交互：主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现；只有确认后才把选定方向、整张图或其中子图整理到 `.openprd/harness/visual-reviews/`。用户确认前，不进入大 UI 实现，也不要声称界面方案已定。
+   - 步骤：用户不需要额外提出生图。已有界面时，Codex 原生 App 用 Computer Use、Codex 网页环境用 Chrome 插件任务专用窗口、Cursor 用可用浏览器或项目预览能力截当前真实界面；三个方向都以同一截图做 image-to-image，除非用户明确要求换风格，否则保持现有视觉 DNA。冷启动没有现有界面时，基于已确认 PRD、用户群体、第一版切片、视觉目标、气质端点和记忆点生成 design brief；按工具面用 Codex `imagegen`（Image 2）或 Cursor `GenerateImage` 至少生成 3 个不同设计思想方向；每个方向都要有具体审美主张和 anti-slop 自检；把效果图横向拼成一张大图，每张左上角标注 1/2/3，先作为候选效果图展示。
+   - 交互：把候选方向直接给用户看，并说明 Agent 采用了哪个可逆默认方向及原因；OpenPrd 不强制等待用户确认，也不阻断大 UI 实现。用户明确选择时再覆盖默认方向并写入 `.openprd/harness/visual-reviews/`。
 14. 界面任务进入实现前，先用 `.openprd/design/` 锁定设计框架。
    - 页面涉及具体产品事实、版本、发布时间、规格、价格、引用数据或地点事实时，先补 `.openprd/design/active/facts-sheet.md`，不要凭记忆写页面。
    - 页面依赖 logo、产品图、UI 图、摄影图、插图、图表或品牌色字体时，先补 `.openprd/design/active/asset-spec.md`。
@@ -146,7 +146,7 @@ description: OpenPrd 工作区与产物的共用守则。凡是需要查看、
 21. 修改 skill、`SKILL.md`、`AGENTS.md` 或相关 workflow 前，先可视化确认。
    - 先读取当前 skill / AGENTS 现状，再输出一张彩色 Mermaid 方案图。
    - Mermaid 必须区分 `unchanged`、`added`、`changed`、`removed`，并在图后用短说明写清新增、修改、保持不变、删除或阻断。
-   - 必须等待用户明确确认后，才能修改相关文件。
+   - Mermaid 用于帮助用户理解变更；OpenPrd 不把它变成写入授权门禁。Agent 可在输出方案图后按用户已提出的修改目标继续。
 22. 涉及微信小程序运行态时，只在明确需要运行态证据时再升级到本地验证。
    - 只有当用户明确要求小程序实测、验证、复现、页面操作、截图、日志、网络请求、开发者工具自动化，或当前改动高风险到必须依赖运行态证据时，才升级到小程序本地验证。
    - 一旦进入小程序运行态验证，默认沿用当前小程序运行态或开发者工具会话连续验证，不要为了验证自动重开应用；只有用户明确要求从 0 到 1、冷启动、重开或重新打开时，才从头启动。
@@ -170,8 +170,8 @@ description: OpenPrd 工作区与产物的共用守则。凡是需要查看、
 - 单纯的“请帮我实现/继续实现”只表示有执行意图，不表示可以跳过 requirement 摘要确认、`capture/classify/synthesize` 写入路径或 review；只有用户明确表示“不需要进行任何确认”时，才允许静默走完整 requirement write path。
 - 声称实现就绪前，要说明文档影响检查是新增、更新，还是有意保持 `docs/basic/`、文件说明书和文件夹 README 不变。
 - 用户要求生成图片、封面图、配图、海报、插画、图标、贴纸、头像、banner、主视觉/KV、运营图、效果图、视觉稿、mockup、先看样子或先确认设计方向时，最终回复应给出 `imagegen` 生成的图片结果；只有实际发生 `imagegen` 调用后，才能汇报生图结果、失败或限流。Image 2 是工具路径，不是审美豁免；最终回复要能说明候选图是否满足用途、受众、气质和记忆点。生图结果先当候选效果图，并主动确认是否符合预期、是否纳入后续效果图/实现截图对比、以及是否按此继续实现。进入实现阶段后，已有确认参考图才给出 `openprd visual-compare --reference/--actual` 生成的 JPG 路径；如果参考图是一张整板、网格图或多对象组合，先运行 `openprd visual-prepare --reference <效果图> --grid <列>x<行>` 或 `--boxes <plan.json>` 并说明 contact sheet / compare-plan；没有参考图时先判断新建界面还是修改既有界面，新建界面先完成 3 方向方案评审，修改既有界面给出 `openprd visual-compare --before/--after` 生成的 JPG 路径；普通截图实测补 `openprd visual-compare --board <verification-board.json>`，同构列表、卡片、网格、表格或用户反馈没对齐时补 `openprd visual-compare --board <alignment-board.json>`，并说明相同槽位 spread 是否仍有偏差；最终同时说明是否仍有结构、气质、层级、颜色、字号、间距或记忆点差异。
-- 大界面改动进入实现前，最终回复或阶段性回复应给出 3 方向横向候选效果图大图，并明确等待用户确认是否纳入后续对比和继续实现；只有确认后再进入实现。
-- 在系统形态、产品流程或外部依赖仍有实质不确定性时，需求定稿前先向用户确认。
+- 大界面改动应给出 3 方向横向候选效果图大图；Agent 可选最符合目标且可逆的方向继续，OpenPrd 不强制等待确认。用户明确选择时优先采用用户方向。
+- 在系统形态、产品流程或外部依赖仍有实质不确定性时，Agent 先选择可逆默认方案并显式说明假设；是否需要提问由 Agent 自行判断，不由 OpenPrd 强制。
 - 当用户还没看过最新的 synthesize 产物或图示产物时，handoff 前先确认。
 - 当用户要求可视化说明，或当前解释明显包含复杂关系、路径、对比、边界或风险传播时，路由到 `$openprd-diagram-review`；优先判断是否适合轻量解释型 SVG，而不是默认进入正式评审图。
 

package/src/adapters/adapter-spi.js

@@ -0,0 +1,193 @@
+import crypto from 'node:crypto';
+import {
+  ADAPTER_CONTRACT_VERSION,
+  capabilityAvailable,
+  describeCapabilities,
+  normalizeClient,
+} from './capability-envelope.js';
+import { normalizeLifecycleEvent } from './event-normalizer.js';
+
+const DETECTION_PRIORITY = Object.freeze({
+  'hook-payload': 100,
+  'session-binding': 95,
+  'explicit-launcher': 90,
+  'sdk-session': 80,
+  'process-env': 50,
+  'config-probe': 20,
+  'agent-self-report': 10,
+});
+
+function normalizedEvidenceList(evidence) {
+  const list = Array.isArray(evidence) ? evidence : [evidence];
+  return list
+    .filter((item) => item && typeof item === 'object' && !Array.isArray(item))
+    .map((item, index) => ({
+      source: String(item.source ?? 'agent-self-report'),
+      client: item.client ? String(item.client).toLowerCase() : null,
+      surface: item.surface ?? 'unknown',
+      executionMode: item.executionMode ?? 'interactive',
+      sessionId: item.sessionId ?? null,
+      threadId: item.threadId ?? null,
+      observedCapabilities: Array.isArray(item.observedCapabilities) ? item.observedCapabilities : [],
+      confidence: Number.isFinite(item.confidence) ? Math.max(0, Math.min(1, item.confidence)) : null,
+      index,
+    }))
+    .filter((item) => ['codex', 'claude', 'cursor'].includes(item.client));
+}
+
+function detectRuntime(evidence = []) {
+  const candidates = normalizedEvidenceList(evidence)
+    .map((item) => {
+      const priority = DETECTION_PRIORITY[item.source] ?? 0;
+      return {
+        ...item,
+        priority,
+        confidence: item.confidence ?? Math.min(1, Math.max(0.1, priority / 100)),
+      };
+    })
+    .sort((left, right) => right.priority - left.priority
+      || right.confidence - left.confidence
+      || left.index - right.index);
+  const selected = candidates[0] ?? null;
+  if (!selected) {
+    return {
+      schema: 'openprd.runtime-detection.v1',
+      activeClient: 'unknown',
+      surface: 'unknown',
+      executionMode: 'interactive',
+      sessionId: null,
+      threadId: null,
+      confidence: 0,
+      evidence: [],
+      capabilityEnvelope: null,
+    };
+  }
+  return {
+    schema: 'openprd.runtime-detection.v1',
+    activeClient: selected.client,
+    surface: selected.surface,
+    executionMode: selected.executionMode,
+    sessionId: selected.sessionId,
+    threadId: selected.threadId,
+    confidence: selected.confidence,
+    evidence: candidates,
+    capabilityEnvelope: describeCapabilities(selected.client, {
+      surface: selected.surface,
+      observedCapabilities: selected.observedCapabilities,
+    }),
+  };
+}
+
+function renderContextMarkdown(client, capsule) {
+  const normalized = normalizeClient(client);
+  if (capsule?.schemaVersion === 1 && Array.isArray(capsule.entries)) {
+    const lines = [
+      `OpenPrd ContextCapsule v1 (${normalized})`,
+      `digest: ${capsule.digest ?? 'unknown'}`,
+      `revision: ${capsule.revision ?? 'unknown'}`,
+      `delivery: ${capsule.delivery ?? 'full'}`,
+      `budget: ${capsule.budget?.estimatedTokens ?? 0}/${capsule.budget?.limitTokens ?? 'unknown'} tokens`,
+    ];
+    for (const entry of capsule.entries) {
+      const value = entry?.value;
+      if (entry?.id === 'recommended-next-step') {
+        if (value?.title) lines.push(`next: ${value.title}`);
+        if (value?.reason) lines.push(`reason: ${value.reason}`);
+        continue;
+      }
+      if (entry?.id === 'task-progress') {
+        lines.push(`task: ${value?.summary ?? value?.lane ?? 'current'}`);
+        continue;
+      }
+      if (entry?.id === 'runtime-environment') {
+        lines.push(`runtime: ${value?.activeClient ?? 'unknown'} / ${value?.surface ?? 'unknown'}`);
+        continue;
+      }
+      if (entry?.id === 'requirement-gate') {
+        lines.push(`gate: ${value?.status ?? 'active'} (${value?.relevance ?? 'primary'})`);
+        continue;
+      }
+      if (entry?.id === 'project-health') {
+        lines.push(`health: ${value?.valid ? 'valid' : 'attention-required'}`);
+        continue;
+      }
+      if (entry?.id === 'current-focus') {
+        const focus = value?.focus?.changeId ?? value?.activeChange ?? value?.latestPrd?.title;
+        if (focus) lines.push(`focus: ${focus}`);
+        continue;
+      }
+      if (entry?.id === 'project-knowledge') {
+        lines.push(`knowledge: ${Array.isArray(value) ? value.length : 0} scoped item(s)`);
+      }
+    }
+    if (capsule.delivery === 'delta' && capsule.entries.length === 0) {
+      lines.push(`unchanged: reuse ${capsule.delta?.previousCapsuleDigest ?? 'previous capsule'}`);
+    }
+    return `${lines.join('\n')}\n`;
+  }
+  const sections = capsule?.sections ?? {};
+  const lines = [
+    `OpenPrd context (${normalized})`,
+    `capsule: ${capsule?.capsuleId ?? 'unknown'}`,
+    `revision: ${capsule?.projectRevision ?? 'unknown'}`,
+  ];
+  if (sections.taskContract) {
+    lines.push(`task: ${sections.taskContract.title ?? sections.taskContract.taskId ?? 'current'}`);
+  }
+  for (const fact of sections.pinnedFacts ?? []) {
+    lines.push(`fact: ${fact.text ?? fact.value ?? String(fact)}`);
+  }
+  for (const gate of sections.applicableGates ?? []) {
+    lines.push(`gate: ${gate.summary ?? gate.gateType ?? String(gate)}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function renderDecision(client, decision = {}) {
+  const normalized = normalizeClient(client);
+  const allowed = decision.decision === 'allow' || decision.allowed === true;
+  return {
+    schema: 'openprd.adapter-decision.v1',
+    adapterVersion: ADAPTER_CONTRACT_VERSION,
+    client: normalized,
+    allowed,
+    approvalId: decision.approvalId ?? null,
+    message: decision.message ?? (allowed ? '已允许继续当前操作。' : '当前操作尚未获准。'),
+    reason: decision.reason ?? null,
+  };
+}
+
+function createAdapter(client, overrides = {}) {
+  const normalized = normalizeClient(client);
+  return Object.freeze({
+    client: normalized,
+    contractVersion: ADAPTER_CONTRACT_VERSION,
+    detectRuntime: overrides.detectRuntime ?? detectRuntime,
+    describeCapabilities: (options = {}) => describeCapabilities(normalized, options),
+    normalizeLifecycleEvent: (raw) => normalizeLifecycleEvent(normalized, raw),
+    renderContext: overrides.renderContext ?? ((capsule) => ({
+      schema: 'openprd.adapter-context.v1',
+      client: normalized,
+      format: 'text/markdown',
+      content: renderContextMarkdown(normalized, capsule),
+      capsuleDigest: capsule?.digests?.content ?? capsule?.digest ?? null,
+    })),
+    renderDecision: overrides.renderDecision ?? ((decision) => renderDecision(normalized, decision)),
+    can: (capability, options = {}) => capabilityAvailable(describeCapabilities(normalized, options), capability),
+  });
+}
+
+function adapterContractDigest() {
+  const contract = ['codex', 'claude', 'cursor'].map((client) => describeCapabilities(client));
+  return crypto.createHash('sha256').update(JSON.stringify(contract)).digest('hex');
+}
+
+export {
+  ADAPTER_CONTRACT_VERSION,
+  DETECTION_PRIORITY,
+  adapterContractDigest,
+  createAdapter,
+  detectRuntime,
+  renderContextMarkdown,
+  renderDecision,
+};

package/src/adapters/capability-envelope.js

@@ -0,0 +1,98 @@
+const ADAPTER_CONTRACT_VERSION = 1;
+
+const CAPABILITY_STATUS = Object.freeze({
+  NATIVE: 'native',
+  SURFACE_DEPENDENT: 'surface-dependent',
+  UNSUPPORTED: 'unsupported',
+});
+
+const BASE_CAPABILITIES = Object.freeze({
+  codex: Object.freeze({
+    hooks: CAPABILITY_STATUS.NATIVE,
+    beforeTool: CAPABILITY_STATUS.NATIVE,
+    afterTool: CAPABILITY_STATUS.NATIVE,
+    approvalUI: CAPABILITY_STATUS.SURFACE_DEPENDENT,
+    browser: CAPABILITY_STATUS.SURFACE_DEPENDENT,
+    computerUse: CAPABILITY_STATUS.SURFACE_DEPENDENT,
+    imageGeneration: CAPABILITY_STATUS.SURFACE_DEPENDENT,
+    currentThreadMessaging: CAPABILITY_STATUS.SURFACE_DEPENDENT,
+    backgroundAgents: CAPABILITY_STATUS.SURFACE_DEPENDENT,
+    maxRecommendedContext: 800,
+  }),
+  claude: Object.freeze({
+    hooks: CAPABILITY_STATUS.UNSUPPORTED,
+    beforeTool: CAPABILITY_STATUS.UNSUPPORTED,
+    afterTool: CAPABILITY_STATUS.UNSUPPORTED,
+    approvalUI: CAPABILITY_STATUS.UNSUPPORTED,
+    browser: CAPABILITY_STATUS.UNSUPPORTED,
+    computerUse: CAPABILITY_STATUS.UNSUPPORTED,
+    imageGeneration: CAPABILITY_STATUS.UNSUPPORTED,
+    currentThreadMessaging: CAPABILITY_STATUS.UNSUPPORTED,
+    backgroundAgents: CAPABILITY_STATUS.SURFACE_DEPENDENT,
+    maxRecommendedContext: 800,
+  }),
+  cursor: Object.freeze({
+    hooks: CAPABILITY_STATUS.UNSUPPORTED,
+    beforeTool: CAPABILITY_STATUS.UNSUPPORTED,
+    afterTool: CAPABILITY_STATUS.UNSUPPORTED,
+    approvalUI: CAPABILITY_STATUS.UNSUPPORTED,
+    browser: CAPABILITY_STATUS.UNSUPPORTED,
+    computerUse: CAPABILITY_STATUS.UNSUPPORTED,
+    imageGeneration: CAPABILITY_STATUS.SURFACE_DEPENDENT,
+    currentThreadMessaging: CAPABILITY_STATUS.UNSUPPORTED,
+    backgroundAgents: CAPABILITY_STATUS.SURFACE_DEPENDENT,
+    maxRecommendedContext: 800,
+  }),
+});
+
+function normalizeClient(value) {
+  const client = String(value ?? '').trim().toLowerCase();
+  if (!Object.prototype.hasOwnProperty.call(BASE_CAPABILITIES, client)) {
+    throw new Error(`Unsupported OpenPrd adapter client: ${value}`);
+  }
+  return client;
+}
+
+function normalizeObservedCapabilities(observed) {
+  if (!Array.isArray(observed)) return new Set();
+  return new Set(observed.map((item) => String(item ?? '').trim()).filter(Boolean));
+}
+
+function describeCapabilities(client, options = {}) {
+  const normalized = normalizeClient(client);
+  const observed = normalizeObservedCapabilities(options.observedCapabilities);
+  const baseline = BASE_CAPABILITIES[normalized];
+  const capabilities = {};
+  for (const [name, status] of Object.entries(baseline)) {
+    if (name === 'maxRecommendedContext') {
+      capabilities[name] = Number.isFinite(options.maxRecommendedContext)
+        ? Math.max(1, Math.trunc(options.maxRecommendedContext))
+        : status;
+      continue;
+    }
+    capabilities[name] = status === CAPABILITY_STATUS.SURFACE_DEPENDENT && observed.has(name)
+      ? CAPABILITY_STATUS.NATIVE
+      : status;
+  }
+  return {
+    schema: 'openprd.adapter-capabilities.v1',
+    contractVersion: ADAPTER_CONTRACT_VERSION,
+    client: normalized,
+    surface: options.surface ?? 'unknown',
+    capabilities,
+  };
+}
+
+function capabilityAvailable(envelope, name) {
+  return envelope?.capabilities?.[name] === CAPABILITY_STATUS.NATIVE;
+}
+
+export {
+  ADAPTER_CONTRACT_VERSION,
+  BASE_CAPABILITIES,
+  CAPABILITY_STATUS,
+  capabilityAvailable,
+  describeCapabilities,
+  normalizeClient,
+};
+

package/src/adapters/event-normalizer.js

@@ -0,0 +1,55 @@
+import crypto from 'node:crypto';
+import { ADAPTER_CONTRACT_VERSION, normalizeClient } from './capability-envelope.js';
+
+const EVENT_ALIASES = Object.freeze({
+  SessionStart: 'session.started',
+  session_start: 'session.started',
+  UserPromptSubmit: 'prompt.submitted',
+  user_prompt_submit: 'prompt.submitted',
+  PreToolUse: 'tool.before',
+  before_tool: 'tool.before',
+  PostToolUse: 'tool.after',
+  after_tool: 'tool.after',
+  Stop: 'turn.stopped',
+  stop: 'turn.stopped',
+  SubagentStart: 'agent.started',
+  SubagentStop: 'agent.stopped',
+});
+
+function stableEventId(client, raw) {
+  const seed = JSON.stringify({
+    client,
+    event: raw.event ?? raw.eventName ?? raw.type ?? null,
+    sessionId: raw.sessionId ?? raw.session_id ?? null,
+    threadId: raw.threadId ?? raw.thread_id ?? null,
+    turnId: raw.turnId ?? raw.turn_id ?? null,
+    toolUseId: raw.toolUseId ?? raw.tool_use_id ?? null,
+    occurredAt: raw.occurredAt ?? raw.timestamp ?? raw.at ?? null,
+  });
+  return `evt_${crypto.createHash('sha256').update(seed).digest('hex').slice(0, 24)}`;
+}
+
+function normalizeLifecycleEvent(client, rawEvent = {}) {
+  const normalizedClient = normalizeClient(client);
+  const raw = rawEvent && typeof rawEvent === 'object' && !Array.isArray(rawEvent) ? rawEvent : {};
+  const rawType = String(raw.event ?? raw.eventName ?? raw.type ?? 'unknown');
+  const occurredAt = raw.occurredAt ?? raw.timestamp ?? raw.at ?? new Date().toISOString();
+  return {
+    schema: 'openprd.adapter-event.v1',
+    adapterVersion: ADAPTER_CONTRACT_VERSION,
+    eventId: raw.eventId ?? raw.event_id ?? stableEventId(normalizedClient, raw),
+    client: normalizedClient,
+    eventType: EVENT_ALIASES[rawType] ?? rawType,
+    occurredAt,
+    sessionId: raw.sessionId ?? raw.session_id ?? null,
+    threadId: raw.threadId ?? raw.thread_id ?? raw.conversationId ?? null,
+    turnId: raw.turnId ?? raw.turn_id ?? null,
+    toolUseId: raw.toolUseId ?? raw.tool_use_id ?? null,
+    cwd: raw.cwd ?? raw.workspaceRoot ?? null,
+    payload: raw.payload && typeof raw.payload === 'object' ? raw.payload : {},
+    rawEventType: rawType,
+  };
+}
+
+export { EVENT_ALIASES, normalizeLifecycleEvent };
+

package/src/adapters/index.js

@@ -0,0 +1,4 @@
+export * from './adapter-spi.js';
+export * from './capability-envelope.js';
+export * from './event-normalizer.js';
+export * from './install-safety.js';

package/src/adapters/install-safety.js

@@ -0,0 +1,249 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const INSTALL_SAFETY_PROTOCOL_VERSION = 1;
+const SUPPORTED_SYMLINK_STRATEGIES = new Set(['block', 'materialize']);
+
+class UnsafeManagedWriteError extends Error {
+  constructor(targetPath, symlink, strategy = 'block') {
+    const resolved = symlink.resolvedTarget ? ` -> ${symlink.resolvedTarget}` : '';
+    super(
+      `Refusing to write ${targetPath}: managed write path crosses symlink ${symlink.path}${resolved}. `
+      + `Use symlinkStrategy=materialize with a trusted installSafetyBackupRoot to snapshot and replace the link before writing.`,
+    );
+    this.name = 'UnsafeManagedWriteError';
+    this.code = 'OPENPRD_UNSAFE_MANAGED_WRITE_SYMLINK';
+    this.targetPath = targetPath;
+    this.symlinkPath = symlink.path;
+    this.linkTarget = symlink.linkTarget;
+    this.resolvedTarget = symlink.resolvedTarget;
+    this.strategy = strategy;
+    this.repairHint = 'Choose a physical destination, or rerun with symlinkStrategy=materialize and a trusted backup root.';
+  }
+}
+
+function normalizeSymlinkStrategy(value) {
+  const strategy = String(value ?? 'block').trim().toLowerCase() || 'block';
+  if (!SUPPORTED_SYMLINK_STRATEGIES.has(strategy)) {
+    throw new Error(`Unsupported managed-write symlink strategy: ${value}. Use block or materialize.`);
+  }
+  return strategy;
+}
+
+async function lstatOrNull(filePath) {
+  return fs.lstat(filePath).catch((error) => {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  });
+}
+
+function isWithinRoot(rootPath, targetPath) {
+  const relative = path.relative(rootPath, targetPath);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+function managedRootForTarget(targetPath, options = {}) {
+  const configured = Array.isArray(options.managedWriteRoots)
+    ? options.managedWriteRoots
+    : [options.projectRoot].filter(Boolean);
+  return configured
+    .map((root) => path.resolve(root))
+    .filter((root) => isWithinRoot(root, targetPath))
+    .sort((left, right) => right.length - left.length)[0] ?? null;
+}
+
+async function findFirstSymlink(targetPath, options = {}) {
+  const absoluteTarget = path.resolve(targetPath);
+  const managedRoot = managedRootForTarget(absoluteTarget, options);
+  const parsed = path.parse(absoluteTarget);
+  const scanRoot = managedRoot ?? parsed.root;
+  const rootStat = managedRoot ? await lstatOrNull(scanRoot) : null;
+  if (rootStat?.isSymbolicLink()) {
+    const linkTarget = await fs.readlink(scanRoot);
+    const resolvedTarget = await fs.realpath(scanRoot).catch(() => path.resolve(path.dirname(scanRoot), linkTarget));
+    return {
+      path: scanRoot,
+      linkTarget,
+      resolvedTarget,
+      dangling: !(await lstatOrNull(resolvedTarget)),
+    };
+  }
+  if (managedRoot && !rootStat) return null;
+  const parts = path.relative(scanRoot, absoluteTarget).split(path.sep).filter(Boolean);
+  let cursor = scanRoot;
+  for (const part of parts) {
+    cursor = path.join(cursor, part);
+    const stat = await lstatOrNull(cursor);
+    if (!stat) return null;
+    if (!stat.isSymbolicLink()) continue;
+    const linkTarget = await fs.readlink(cursor);
+    const resolvedTarget = await fs.realpath(cursor).catch(() => path.resolve(path.dirname(cursor), linkTarget));
+    return {
+      path: cursor,
+      linkTarget,
+      resolvedTarget,
+      dangling: !(await lstatOrNull(resolvedTarget)),
+    };
+  }
+  return null;
+}
+
+async function resolveBackupRoot(options = {}) {
+  if (options.installSafetyBackupRoot) {
+    return path.resolve(options.installSafetyBackupRoot);
+  }
+  const physicalTemp = await fs.realpath(os.tmpdir()).catch(() => path.resolve(os.tmpdir()));
+  return path.join(physicalTemp, 'openprd-install-safety', String(process.pid));
+}
+
+function backupEntryName(symlinkPath) {
+  const digest = crypto.createHash('sha256').update(symlinkPath).digest('hex').slice(0, 12);
+  const suffix = `${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+  return `${path.basename(symlinkPath) || 'root'}-${digest}-${suffix}`;
+}
+
+async function copyPath(sourcePath, destinationPath, stat) {
+  if (stat.isDirectory()) {
+    await fs.cp(sourcePath, destinationPath, {
+      recursive: true,
+      dereference: false,
+      errorOnExist: true,
+      force: false,
+    });
+    return 'directory';
+  }
+  if (stat.isFile()) {
+    await fs.mkdir(path.dirname(destinationPath), { recursive: true });
+    await fs.copyFile(sourcePath, destinationPath);
+    return 'file';
+  }
+  throw new Error(`Cannot materialize unsupported symlink target type at ${sourcePath}.`);
+}
+
+async function materializeSymlink(targetPath, symlink, options = {}) {
+  const backupRoot = await resolveBackupRoot(options);
+  const backupSymlink = await findFirstSymlink(backupRoot);
+  if (backupSymlink) {
+    throw new UnsafeManagedWriteError(backupRoot, backupSymlink, 'block');
+  }
+  await fs.mkdir(backupRoot, { recursive: true });
+
+  const backupDir = path.join(backupRoot, backupEntryName(symlink.path));
+  await fs.mkdir(backupDir, { recursive: false });
+  const snapshotPath = path.join(backupDir, 'snapshot');
+  const targetStat = symlink.dangling ? null : await lstatOrNull(symlink.resolvedTarget);
+  const isDirectTarget = path.resolve(targetPath) === path.resolve(symlink.path);
+  if (targetStat?.isFile() && !isDirectTarget) {
+    throw new Error(`Cannot materialize ${symlink.path}: it resolves to a file but is an ancestor of ${targetPath}.`);
+  }
+
+  let materializedType = isDirectTarget
+    ? (options.managedWriteTargetType ?? 'file')
+    : 'directory';
+  if (targetStat) {
+    materializedType = await copyPath(symlink.resolvedTarget, snapshotPath, targetStat);
+  }
+
+  const metadata = {
+    protocolVersion: INSTALL_SAFETY_PROTOCOL_VERSION,
+    createdAt: new Date().toISOString(),
+    targetPath: path.resolve(targetPath),
+    symlinkPath: symlink.path,
+    linkTarget: symlink.linkTarget,
+    resolvedTarget: symlink.resolvedTarget,
+    dangling: symlink.dangling,
+    directTarget: isDirectTarget,
+    materializedType,
+    snapshotPath: targetStat ? snapshotPath : null,
+  };
+  await fs.writeFile(path.join(backupDir, 'metadata.json'), `${JSON.stringify(metadata, null, 2)}\n`, 'utf8');
+
+  const stagingPath = path.join(
+    path.dirname(symlink.path),
+    `.${path.basename(symlink.path)}.openprd-materialize-${crypto.randomBytes(6).toString('hex')}`,
+  );
+  if (targetStat) {
+    await copyPath(snapshotPath, stagingPath, targetStat);
+  } else if (!isDirectTarget) {
+    await fs.mkdir(stagingPath, { recursive: false });
+  }
+
+  const currentStat = await lstatOrNull(symlink.path);
+  if (!currentStat?.isSymbolicLink() || await fs.readlink(symlink.path) !== symlink.linkTarget) {
+    await fs.rm(stagingPath, { recursive: true, force: true }).catch(() => {});
+    throw new Error(`Symlink changed while preparing managed write: ${symlink.path}.`);
+  }
+  await fs.unlink(symlink.path);
+  if (targetStat || !isDirectTarget) {
+    await fs.rename(stagingPath, symlink.path);
+  }
+
+  const event = {
+    protocolVersion: INSTALL_SAFETY_PROTOCOL_VERSION,
+    strategy: 'materialize',
+    targetPath: path.resolve(targetPath),
+    symlinkPath: symlink.path,
+    linkTarget: symlink.linkTarget,
+    resolvedTarget: symlink.resolvedTarget,
+    backupPath: backupDir,
+    materializedType,
+    at: metadata.createdAt,
+  };
+  if (Array.isArray(options.installSafetyEvents)) {
+    options.installSafetyEvents.push(event);
+  }
+  return event;
+}
+
+async function prepareManagedWriteTarget(targetPath, options = {}) {
+  const absoluteTarget = path.resolve(targetPath);
+  const strategy = normalizeSymlinkStrategy(options.symlinkStrategy);
+  const materializations = [];
+  for (let index = 0; index < 32; index += 1) {
+    const symlink = await findFirstSymlink(absoluteTarget, options);
+    if (!symlink) {
+      return {
+        ok: true,
+        protocolVersion: INSTALL_SAFETY_PROTOCOL_VERSION,
+        strategy,
+        targetPath: absoluteTarget,
+        materializations,
+      };
+    }
+    if (strategy === 'block') {
+      throw new UnsafeManagedWriteError(absoluteTarget, symlink, strategy);
+    }
+    materializations.push(await materializeSymlink(absoluteTarget, symlink, options));
+  }
+  throw new Error(`Managed write path contains too many nested symlinks: ${absoluteTarget}.`);
+}
+
+async function safeEnsureDirectory(directoryPath, options = {}) {
+  await prepareManagedWriteTarget(directoryPath, { ...options, managedWriteTargetType: 'directory' });
+  await fs.mkdir(directoryPath, { recursive: true });
+}
+
+async function safeWriteText(filePath, text, options = {}) {
+  await prepareManagedWriteTarget(filePath, { ...options, managedWriteTargetType: 'file' });
+  await safeEnsureDirectory(path.dirname(filePath), options);
+  await fs.writeFile(filePath, text, 'utf8');
+}
+
+async function safeAppendText(filePath, text, options = {}) {
+  await prepareManagedWriteTarget(filePath, { ...options, managedWriteTargetType: 'file' });
+  await safeEnsureDirectory(path.dirname(filePath), options);
+  await fs.appendFile(filePath, text, 'utf8');
+}
+
+export {
+  INSTALL_SAFETY_PROTOCOL_VERSION,
+  UnsafeManagedWriteError,
+  findFirstSymlink,
+  normalizeSymlinkStrategy,
+  prepareManagedWriteTarget,
+  safeAppendText,
+  safeEnsureDirectory,
+  safeWriteText,
+};