@openprd/cli 0.1.11 → 0.1.18

package/README_EN.md

@@ -130,9 +130,18 @@ one human-readable quality surface before handoff, release, or publish.
 Put the reference and implementation into one side-by-side artifact for staged
 UI review, especially for auth-entry redesign, localized legal pages, and modal
 replication work.
+Visual evidence follows the current task language by default: Chinese requests
+produce Chinese labels, English requests produce English labels, and
+`--locale zh-CN` or `--locale en` can pin the output language for side-by-side labels,
+board titles, summaries, and checks.
 
 ![Auto-optimized reference-to-screenshot comparison](https://raw.githubusercontent.com/mileson/openprd/main/docs/assets/openprd-visual-compare-case-study-en.png)
 
+```bash
+openprd visual-compare . --reference ref.png --actual actual.png --locale zh-CN
+openprd visual-compare . --board verification-board.json --locale en
+```
+
 ## Self-Evolving Collaboration
 
 OpenPrd gets easier to work with over time through two visible loops. One loop
@@ -172,6 +181,7 @@ automatically.
 - **Project-level benchmark registry**: support `benchmark add / observe / approve / verify` so repeatedly adopted external sources can become durable project references
 - **Diagram review artifacts**: generate both architecture and product-flow diagrams
 - **UI visual comparison artifacts**: combine reference images and implementation screenshots into side-by-side JPG reviews for visual replication work
+- **Language-aware visual evidence**: localize comparison labels and board copy from the active request language, with `--locale` / `--lang` overrides when a project needs a fixed output language
 - **Contract-driven diagrams**: render from validated JSON contracts
 - **Review status tracking**: use `pending-confirmation`, `confirmed`, and `needs-revision`
 - **Project release/version ledger**: optionally track project versions such as `0.1.23`, version-scoped change items, and local git tag coordination without mixing them with internal PRD `v000x` versions
@@ -355,16 +365,23 @@ openprd review /path/to/project --mark confirmed --version <id> --digest <sha256
 
 `review.html` is the stable review artifact for the current PRD, but the default
 approval policy is `decision-points`, not “always stop here”. In a normal lane,
-the user reviews that stable artifact first and then the exact copied
-`--version`, `--digest`, and `--work-unit` tuple is recorded. In a
-`silent-record` lane, OpenPrd can record the exact current artifact without an
-extra stop only when the user already made direct execution intent explicit and
-explicitly opted out of additional review confirmation. Do not treat
-implementation approval as permission to mark a different review artifact, and
-do not treat review recording as execution authorization. After the current
-artifact is recorded, generate the OpenPrd change and task breakdown. If the
-user originally asked to implement, execution can continue once tasks are ready;
-otherwise wait for an explicit execution request:
+one plain natural-language confirmation (for example “确认这版，继续”, including
+wording with an inline version id such as “确认 v0276 评审稿”) is enough: the
+hook binds it to the exact current `--version`, `--digest`, and `--work-unit`
+tuple automatically, and the agent must never ask the user to paste a digest,
+work-unit id, or a full command. When that confirmation also carries a
+continue-execution intent, or a requirement summary was already confirmed
+earlier, one confirmation authorizes the whole chain: review recording, change,
+tasks, and implementation proceed without further stops (the one-time
+confirmation contract). In a `silent-record` lane, OpenPrd can record the exact
+current artifact without an extra stop only when the user already made direct
+execution intent explicit and explicitly opted out of additional review
+confirmation. Do not treat implementation approval as permission to mark a
+different review artifact, and do not treat review recording as execution
+authorization. After the current artifact is recorded, generate the OpenPrd
+change and task breakdown. If the user originally asked to implement, execution
+can continue once tasks are ready; otherwise wait for an explicit execution
+request:
 
 ```bash
 openprd change /path/to/project --generate --change <change-id>
@@ -501,6 +518,25 @@ the change affects responsibilities, flows, structure, dependencies, or product
 behavior. If no documentation update is needed, agents should say the check was
 performed and why the existing docs still match the code.
 
+## Image-generation routing: pick the right free tool automatically
+
+Image requests (covers, mockups, icons, effect images) follow a three-layer
+routing protocol, so users never have to specify a provider:
+
+1. **Surface built-ins first**: Codex uses native `imagegen` (Image 2), Cursor
+   uses the built-in `GenerateImage` tool — both are free inside their surfaces.
+2. **Persisted preference**: when no built-in tool is available, OpenPrd reads
+   the user-confirmed preference from
+   `.openprd/harness/image-generation-preference.json` and reuses it silently.
+3. **Ask once, persist**: only when no preference exists does OpenPrd ask the
+   user once, then writes the answer back with a `user-confirmed` source as the
+   future default.
+
+Cost guardrail: OpenPrd never silently calls the user’s own paid image APIs
+(for example OpenAI or Stability keys) unless the user explicitly picked one.
+The routing contract ships in the install manifest and
+`.openprd/harness/runtime-environment.json` under `imageGenerationRouting`.
+
 ## Auto-optimized reference-to-screenshot comparison
 
 When UI work already has a reference effect image, design image, user-provided
@@ -547,6 +583,71 @@ obvious visual differences. The final response for reference-driven UI work
 should include the generated review image path and note whether differences
 remain.
 
+When a new feature or visible change contains repeated homogeneous lists, cards,
+grids, or tables, or when the user reports misalignment, the agent should also
+capture the real UI, overlay guide lines, and measure both container-track and
+internal content-slot coordinate spread in one alignment evidence board:
+
+```bash
+openprd visual-compare /path/to/project \
+  --board alignment-board.json
+```
+
+Use `mode: "alignment-board"` in the board JSON. Include the screenshot, guide
+lines, container groups, content-slot groups, and x/y/width/height/baseline
+spread. Container tracks include card edges, columns, row tops, and gaps.
+Internal content slots include titles, subtitles, tags, descriptions, status,
+prices, buttons, icons, and action areas. Repeated card lists, card grids, and
+tables are default triggers even when the user did not explicitly complain
+about alignment; measuring only outer frames, columns, or row tops is not enough.
+
+When a single logo, icon, avatar, badge, button graphic, or image crop needs
+internal centering review, or when the user reports that its visual weight feels
+off-center, crop the target if needed and generate a centering evidence board:
+
+```bash
+openprd visual-compare /path/to/project \
+  --board centering-board.json
+```
+
+Minimal syntax:
+
+```json
+{
+  "mode": "centering-board",
+  "title": "Logo internal centering check",
+  "image": ".openprd/harness/screenshots/logo.png",
+  "thresholdPx": 8,
+  "subject": {
+    "mode": "auto",
+    "weight": "contrast"
+  }
+}
+```
+
+If the automatic mask includes background, shadow, or transparent padding, use
+explicit color ranges:
+
+```json
+{
+  "mode": "centering-board",
+  "image": ".openprd/harness/screenshots/logo.png",
+  "subject": {
+    "mode": "range",
+    "ranges": [
+      { "r": [180, 255], "g": [140, 255], "b": [0, 120] },
+      { "r": [210, 255], "g": [210, 255], "b": [200, 255] }
+    ],
+    "weight": "luma"
+  }
+}
+```
+
+`centering-board` draws the red canvas center, green active subject bounds, and
+yellow visual centroid, then stores bounding-box center offset and
+visual-centroid offset in metadata. A raw screenshot or subjective “looks
+centered” note is not a substitute for this board.
+
 ## Quality Regression Reports
 
 `openprd init` also creates a quality contract:
@@ -584,8 +685,14 @@ scope for the scenario.
 
 For UI work with an existing reference image, visual readiness also requires a
 current `openprd visual-compare` artifact under `.openprd/harness/visual-reviews/`.
-If the combined image still shows obvious differences, the task should return to
-implementation instead of treating the gap as ready.
+Before/after UI changes require a before/after artifact, screenshot-based
+runtime checks require a verification board, and homogeneous lists, cards,
+grids, or tables require an alignment board that covers both container tracks
+and internal content slots. Single-logo, icon, avatar, badge, button graphic, or
+image-crop internal-centering reviews require a centering board. If the combined image still shows
+obvious differences, coordinate drift, or layout spread beyond the intended
+threshold, the task should return to implementation instead of treating the gap
+as ready.
 
 After a fix has been verified and reviewed, promote the abstract pattern into
 project knowledge:
@@ -688,7 +795,11 @@ task, and can commit that task before moving on.
 For UI tasks, the loop prompt and generated guidance require the agent to run
 `openprd visual-compare` before finishing: use `--reference/--actual` when a
 reference image exists, or `--before/--after` when the agent must verify a UI
-change without an explicit reference image.
+change without an explicit reference image. Use `--board <verification-board.json>`
+for screenshot-based runtime evidence, and `--board <alignment-board.json>` for
+homogeneous lists, cards, grids, or tables; the alignment board must cover both
+outer tracks and internal content slots. Use `--board <centering-board.json>` for
+single-element internal-centering or visual-centroid checks.
 
 `openprd run --context` may surface loop commands as execution commands, but they
 are not automatic instructions. Agents should run `openprd loop --run`,
@@ -736,6 +847,13 @@ without launching an agent. Use `--agent codex` or `--agent claude` for the defa
 CLI integrations. Use `--agent-command "<custom command>"` only when you want to
 pipe the OpenPrd prompt into a project-specific wrapper.
 
+User-facing generated docs, progress logs, proposals, prompts, test reports, and
+agent-produced specs/tasks follow the primary language of the current request
+and PRD snapshot. Chinese contexts use Simplified Chinese, English contexts stay
+English, and ambiguous contexts fall back to `zh-CN`; command names, field names,
+paths, APIs, product names, and explicitly `zh-CN` diagram contracts remain
+unchanged.
+
 For historical projects, use `fleet` instead of hand-writing shell loops. By
 default it scans and reports only, while also telling you how many known
 OpenPrd workspaces already exist in the global registry and how many are outside

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openprd/cli",
-  "version": "0.1.11",
+  "version": "0.1.18",
   "description": "AI-native PRD workspace and lifecycle CLI",
   "type": "module",
   "license": "MIT",

package/scripts/dev-check-wrapup-copy.mjs

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
 
 export const DEV_CHECK_WRAPUP_COPY_LIMIT = 20;
-const WRAPUP_FIELDS = ['规模信号', '预警原因', '本次处理结果', '后续建议'];
-const VALIDATE_USAGE = 'Usage: echo \'{"rows":[{"影响对象":"src/example.js","规模信号":"701 行（> 700 行/文件）","预警原因":"文件偏大，维护成本升","本次处理结果":"本轮小改，未扩职责","后续建议":"继续改前先拆小"}]}\' | node scripts/dev-check-wrapup-copy.mjs --validate';
+// 自动优化模式（默认）与仅推荐模式使用不同表头；字段别名成对等价。
+const WRAPUP_FIELD_ALIASES = [
+  ['源文件规模', '规模信号'],
+  ['优化原因', '预警原因'],
+  ['本次处理结果'],
+  ['后续建议'],
+];
+const VALIDATE_USAGE = 'Usage: echo \'{"rows":[{"影响对象":"src/example.js","源文件规模":"701 行（> 700 行/文件）","优化原因":"文件偏大，维护成本升","本次处理结果":"本轮小改，未扩职责","后续建议":"继续改前先拆小"}]}\' | node scripts/dev-check-wrapup-copy.mjs --validate（仅推荐模式对应字段为“规模信号 / 预警原因”）';
 
 function countChars(value) {
   return Array.from(String(value ?? ''));
@@ -11,14 +17,15 @@ function countChars(value) {
 function validateCompactRows(rows = [], limit = DEV_CHECK_WRAPUP_COPY_LIMIT) {
   for (const [index, row] of rows.entries()) {
     const rowLabel = row?.影响对象 ? String(row.影响对象) : (row?.影响位置 ? String(row.影响位置) : `第 ${index + 1} 行`);
-    for (const field of WRAPUP_FIELDS) {
-      const value = row?.[field];
-      if (typeof value !== 'string') {
-        throw new Error(`后续建议校验失败：${rowLabel} 缺少字段“${field}”。${VALIDATE_USAGE}`);
+    for (const aliases of WRAPUP_FIELD_ALIASES) {
+      const field = aliases.find((name) => typeof row?.[name] === 'string');
+      if (!field) {
+        throw new Error(`收口表格校验失败：${rowLabel} 缺少字段“${aliases.join('／')}”。${VALIDATE_USAGE}`);
       }
+      const value = row[field];
       const actual = countChars(value).length;
       if (actual > limit) {
-        throw new Error(`后续建议校验失败：${rowLabel} 的“${field}”有 ${actual} 个字，超过 ${limit} 字上限。当前内容：“${value}”。请缩短后重试。`);
+        throw new Error(`收口表格校验失败：${rowLabel} 的“${field}”有 ${actual} 个字，超过 ${limit} 字上限。当前内容：“${value}”。请缩短后重试。`);
       }
     }
   }
@@ -56,29 +63,45 @@ function reasonText(file) {
   return '待补充';
 }
 
-function currentResultText(file) {
-  if (file.status === 'warning') return '这次先完成需求，暂不拆分';
-  if (file.status === 'attention') return '本轮小改，未扩职责';
+function currentResultText(file, autoRefactor) {
+  if (file.status === 'warning') {
+    return autoRefactor ? '本轮执行拆分后回填' : '这次先完成需求，暂不拆分';
+  }
+  if (file.status === 'attention') {
+    return autoRefactor ? '按需小步拆分后回填' : '本轮小改，未扩职责';
+  }
   if (file.status === 'error') return '本轮失败，未收口';
   if (file.status === 'ok') return '本轮已回顾';
   return '待确认';
 }
 
-function followUpText(file) {
-  if (file.status === 'warning') return '优先拆出独立职责';
-  if (file.status === 'attention') return '继续改前先拆小';
+function followUpText(file, autoRefactor) {
+  if (file.status === 'warning') {
+    return autoRefactor ? '拆完重跑测试验证' : '优先拆出独立职责';
+  }
+  if (file.status === 'attention') {
+    return autoRefactor ? '保持职责边界清晰' : '继续改前先拆小';
+  }
   if (file.status === 'error') return '先修复后重跑';
   if (file.status === 'ok') return '无需额外动作';
   return '待确认';
 }
 
-export function buildCompactDevCheckWrapUpRows(files = []) {
-  return files.map((file) => ({
-    规模信号: thresholdText(file),
-    预警原因: reasonText(file),
-    本次处理结果: currentResultText(file),
-    后续建议: followUpText(file),
-  }));
+export function buildCompactDevCheckWrapUpRows(files = [], options = {}) {
+  const autoRefactor = Boolean(options.autoRefactor);
+  return files.map((file) => (autoRefactor
+    ? {
+      源文件规模: thresholdText(file),
+      优化原因: reasonText(file),
+      本次处理结果: currentResultText(file, autoRefactor),
+      后续建议: followUpText(file, autoRefactor),
+    }
+    : {
+      规模信号: thresholdText(file),
+      预警原因: reasonText(file),
+      本次处理结果: currentResultText(file, autoRefactor),
+      后续建议: followUpText(file, autoRefactor),
+    }));
 }
 
 async function readStdin() {
@@ -95,7 +118,9 @@ async function main() {
   const payload = raw.trim() ? JSON.parse(raw) : {};
   const rows = validateOnly
     ? (Array.isArray(payload.rows) ? payload.rows : [])
-    : buildCompactDevCheckWrapUpRows(Array.isArray(payload.files) ? payload.files : []);
+    : buildCompactDevCheckWrapUpRows(Array.isArray(payload.files) ? payload.files : [], {
+      autoRefactor: Boolean(payload.autoRefactor),
+    });
   validateCompactRows(rows);
   process.stdout.write(JSON.stringify({
     ok: true,

package/skills/openprd-diagram-review/SKILL.md

@@ -1,25 +1,37 @@
 ---
 name: openprd-diagram-review
-description: 生成并迭代 OpenPrd 图示产物，供用户确认。适用于架构图、产品流程图、用户旅程、流程图、系统边界图、依赖图，以及 freeze 前的可视化评审场景。
+description: 生成并迭代 OpenPrd 图示产物，供用户确认或理解。适用于解释型 SVG、架构图、产品流程图、用户旅程、流程图、系统边界图、依赖图，以及 freeze 前的可视化评审场景。
 ---
 
 # OpenPrd Diagram Review
 
 ## 概览
 
-这份 skill 用来判断当前需要哪种图、生成可渲染的 diagram contract、调用 OpenPrd 当前支持的渲染能力，并把结果变成和用户往返确认的评审循环，而不是一次性出图。
+这份 skill 用来判断当前需要哪种图：轻量解释图、正式 diagram contract，或需要用户往返确认的评审循环。不要把所有图都当成 freeze 前评审图；很多时候用户只是需要先看懂问题。
 
 ## 动手前
 
 1. 读取 `skills/openprd-shared/SKILL.md`
 2. 重建当前工作区状态，判断用户究竟想确认什么
 3. 决定用户需要的是：
+   - `explanation-svg` 轻量解释图
    - `architecture` 视图
    - `product-flow` 视图
 4. 不要虚构今天还不存在的 OpenPrd diagram 命令
 
 ## 图示类型选择
 
+当用户在问这些内容时，优先选 `explanation-svg`：
+
+- 为什么会这样
+- 这两个方案差在哪里
+- 当前状态怎么走到目标状态
+- 过去、现在、未来的关系
+- 因果、依赖、边界、风险传播
+- Agent 要向用户解释需求场景、问题结构、决策取舍或下一步路径
+
+`explanation-svg` 是对话辅助。它可以用内联 SVG、HTML 片段或 Markdown 中的 SVG 代码块表达；它不需要写入 `.openprd/engagements/active/`，也不替代 `openprd diagram`、`review.html`、`visual-compare` 或测试证据。
+
 当用户在问这些内容时，选 `architecture`：
 
 - 模块
@@ -41,6 +53,17 @@ description: 生成并迭代 OpenPrd 图示产物，供用户确认。适用于
 
 - 当用户行为和流程仍不清楚时，先做 `product-flow` contract
 - 流程清楚后，再做架构评审
+- 如果只是为了让用户先理解取舍，不进入定稿评审，先给 `explanation-svg`
+
+## 解释型 SVG 规则
+
+- 输出顺序优先是：一句结论、SVG 图、最多 3 条补充说明或开放问题。
+- 图中每个节点只放短标签和 1 行例子；正文解释放到图下，不要把 SVG 变成文字墙截图。
+- 优先使用 2 到 5 个节点、明确箭头、颜色分组、虚线边界、少量图例；避免复杂渐变、装饰背景和难读小字。
+- 适合的图形包括：双栏对比、时间线、状态转移、边界/责任图、决策树、风险传播、因果反推。
+- 图中用户可见文案跟随用户当前主语言；中文语境用简体中文，专有名词可保留，但不要在中文语境下整句英文。
+- 如果没有足够事实支撑图中的节点或箭头，先把缺口写成“待确认”，不要把推测画成事实。
+- 需要模板时读取 `references/explanation-svg-patterns.md`。
 
 ## 当前工具能力
 
@@ -52,6 +75,7 @@ description: 生成并迭代 OpenPrd 图示产物，供用户确认。适用于
 
 因此：
 
+- 对 `explanation-svg`，直接在对话或临时 HTML/SVG artifact 中生成轻量图，不声称已进入正式 diagram 评审
 - 对 `architecture`，直接调用内置命令
 - 对 `product-flow`，即使还没有专门渲染器，也先生成结构化 contract 和评审清单
 - 如果工具还没有专用流程渲染器，就不要假装它已经存在
@@ -87,5 +111,6 @@ description: 生成并迭代 OpenPrd 图示产物，供用户确认。适用于
 ## 需要时阅读这些参考资料
 
 - `references/diagram-contracts.md`：架构图和产品流程图 contract
+- `references/explanation-svg-patterns.md`：解释型 SVG 的触发场景、图形模板和文案边界
 - `references/review-checklist.md`：渲染后应该问用户什么
 - `references/cocoon-patterns.md`：从 `Cocoon-AI/architecture-diagram-generator` 借来的可复用模式

package/skills/openprd-diagram-review/references/explanation-svg-patterns.md

@@ -0,0 +1,131 @@
+# Explanation SVG Patterns
+
+## Purpose
+
+Use explanation SVGs when the user needs to understand a relationship before they need a formal artifact. These diagrams are optimized for comprehension in the conversation, not for approval gates.
+
+An explanation SVG should reduce text. The preferred shape is:
+
+1. One sentence conclusion
+2. One compact SVG
+3. Up to three short notes or open questions
+
+## When To Use
+
+Use an explanation SVG for:
+
+- state transitions
+- before / after comparisons
+- current state to target state paths
+- cause and effect chains
+- responsibility or boundary splits
+- risk propagation
+- decision trees
+- trade-off comparisons
+- requirement scenarios with multiple actors or steps
+
+Do not use an explanation SVG for:
+
+- a single factual answer
+- exact command output or error text
+- legal, security, or compliance wording that must be precise
+- proof of implementation
+- visual acceptance evidence
+- formal PRD review sign-off
+
+## Visual Grammar
+
+- Keep the canvas compact, usually 900 to 1200 px wide.
+- Use 2 to 5 main nodes.
+- Put short labels inside nodes; keep supporting text outside the SVG.
+- Use arrows to show direction, not paragraphs.
+- Use dashed outlines for scope or uncertainty.
+- Use muted gray for background or irrelevant history.
+- Use green/teal for target, current, or healthy path.
+- Use amber/red only for risk, blockage, or failure.
+- Keep labels in the user's language. For zh-CN, use Simplified Chinese.
+
+## Pattern Library
+
+### Two-Side Comparison
+
+Use when explaining why two approaches feel different.
+
+```svg
+<svg viewBox="0 0 980 360" role="img" aria-label="两种方案对比">
+  <rect x="24" y="28" width="440" height="290" rx="18" fill="#f8fafc" stroke="#cbd5e1" stroke-dasharray="8 6"/>
+  <rect x="516" y="28" width="440" height="290" rx="18" fill="#ecfdf5" stroke="#14b8a6" stroke-dasharray="8 6"/>
+  <text x="52" y="76" font-size="24" font-weight="700" fill="#1f2937">文字优先</text>
+  <text x="544" y="76" font-size="24" font-weight="700" fill="#065f46">图解优先</text>
+  <rect x="76" y="132" width="280" height="76" rx="12" fill="#fff7ed" stroke="#fdba74"/>
+  <text x="216" y="164" text-anchor="middle" font-size="20" font-weight="700" fill="#7c2d12">先解释很多概念</text>
+  <text x="216" y="192" text-anchor="middle" font-size="16" fill="#9a3412">用户自己拼结构</text>
+  <rect x="568" y="132" width="280" height="76" rx="12" fill="#d1fae5" stroke="#10b981"/>
+  <text x="708" y="164" text-anchor="middle" font-size="20" font-weight="700" fill="#065f46">先看到关系</text>
+  <text x="708" y="192" text-anchor="middle" font-size="16" fill="#047857">文字只补结论</text>
+  <path d="M356 170 H568" stroke="#64748b" stroke-width="3" marker-end="url(#arrow)"/>
+  <defs>
+    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L0,6 L9,3 z" fill="#64748b"/>
+    </marker>
+  </defs>
+</svg>
+```
+
+### State Transition
+
+Use when explaining how the current state moves to a future state, and whether history matters.
+
+```svg
+<svg viewBox="0 0 1080 360" role="img" aria-label="状态转移说明">
+  <rect x="34" y="40" width="1012" height="250" rx="22" fill="#ffffff" stroke="#cbd5e1" stroke-dasharray="8 6"/>
+  <rect x="90" y="130" width="230" height="88" rx="14" fill="#f1f5f9" stroke="#cbd5e1"/>
+  <text x="205" y="164" text-anchor="middle" font-size="21" font-weight="700" fill="#64748b">过去状态</text>
+  <text x="205" y="194" text-anchor="middle" font-size="16" fill="#94a3b8">不一定重要</text>
+  <rect x="424" y="130" width="230" height="88" rx="14" fill="#ccfbf1" stroke="#14b8a6"/>
+  <text x="539" y="164" text-anchor="middle" font-size="21" font-weight="700" fill="#0f766e">当前状态</text>
+  <text x="539" y="194" text-anchor="middle" font-size="16" fill="#0f766e">决策起点</text>
+  <rect x="758" y="130" width="230" height="88" rx="14" fill="#dcfce7" stroke="#22c55e"/>
+  <text x="873" y="164" text-anchor="middle" font-size="21" font-weight="700" fill="#166534">未来状态</text>
+  <text x="873" y="194" text-anchor="middle" font-size="16" fill="#15803d">下一步结果</text>
+  <path d="M320 174 H424" stroke="#cbd5e1" stroke-width="3" marker-end="url(#mutedArrow)"/>
+  <path d="M654 174 H758" stroke="#0f766e" stroke-width="5" marker-end="url(#greenArrow)"/>
+  <text x="706" y="214" text-anchor="middle" font-size="17" fill="#0f766e">关键转移</text>
+  <defs>
+    <marker id="mutedArrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L0,6 L9,3 z" fill="#cbd5e1"/>
+    </marker>
+    <marker id="greenArrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
+      <path d="M0,0 L0,6 L9,3 z" fill="#0f766e"/>
+    </marker>
+  </defs>
+</svg>
+```
+
+### Boundary Map
+
+Use when explaining what belongs in scope, what is adjacent, and what remains outside.
+
+```svg
+<svg viewBox="0 0 980 420" role="img" aria-label="范围边界说明">
+  <rect x="46" y="44" width="888" height="310" rx="24" fill="#f8fafc" stroke="#94a3b8" stroke-dasharray="9 7"/>
+  <text x="76" y="90" font-size="24" font-weight="700" fill="#334155">本次范围</text>
+  <rect x="120" y="142" width="220" height="92" rx="14" fill="#dbeafe" stroke="#3b82f6"/>
+  <text x="230" y="178" text-anchor="middle" font-size="20" font-weight="700" fill="#1d4ed8">核心问题</text>
+  <text x="230" y="207" text-anchor="middle" font-size="16" fill="#2563eb">必须解决</text>
+  <rect x="380" y="142" width="220" height="92" rx="14" fill="#dcfce7" stroke="#22c55e"/>
+  <text x="490" y="178" text-anchor="middle" font-size="20" font-weight="700" fill="#166534">可执行动作</text>
+  <text x="490" y="207" text-anchor="middle" font-size="16" fill="#15803d">这轮落地</text>
+  <rect x="640" y="142" width="220" height="92" rx="14" fill="#fff7ed" stroke="#f59e0b"/>
+  <text x="750" y="178" text-anchor="middle" font-size="20" font-weight="700" fill="#92400e">开放问题</text>
+  <text x="750" y="207" text-anchor="middle" font-size="16" fill="#b45309">需要确认</text>
+  <text x="490" y="300" text-anchor="middle" font-size="18" fill="#64748b">边界外内容只记录，不混成本次失败</text>
+</svg>
+```
+
+## Copy Rules
+
+- The sentence before the diagram should state the takeaway, not repeat every label.
+- The notes after the diagram should explain only what the user must decide or notice.
+- Avoid file names, function names, raw route codes, schema names, and internal gate names unless the user asked for implementation detail.
+- Do not hide uncertainty inside the diagram. Use "待确认" or a dashed node when a claim is inferred.

package/skills/openprd-discovery-loop/SKILL.md

@@ -173,8 +173,8 @@ hook harness 还会写入：
 
 - 使用 `openprd tasks <path> --change <id>` 查看进度和下一个依赖已满足的任务
 - 当某项任务已经可以通过自己的 `verify` 命令完成时，使用 `openprd tasks <path> --change <id> --advance --verify --item <task-id>`
-- 使用 `openprd change <path> --apply --change <id>` 把完成的 change specs 推进到 `openprd/specs`
-- 使用 `openprd change <path> --archive --change <id>` 把完成的 change 文件移动到 `openprd/archive/changes`
+- 使用 `openprd change <path> --apply --change <id>` 把完成的 change specs 推进到 `.openprd/specs`
+- 使用 `openprd change <path> --archive --change <id>` 把完成的 change 文件移动到 `.openprd/archive/changes`
 - 当任务或 discovery pass 改动了基线文档、文件说明书或文件夹 README 时，运行 `openprd standards <path> --verify`
 - 在声明单个任务完成前，运行本任务最小足够验证并留下 evidence；在阶段收口或声明整体实现就绪前，运行 `openprd quality <path> --verify`；当某个已验证修复应该沉淀为项目级复用经验时，运行 `openprd quality <path> --learn --from <report>`
 - 如果任务被依赖阻塞，先完成更早的任务 id；不要人工跳过依赖顺序