design-playbook 0.21.0 → 0.21.2

package/README.md

@@ -101,6 +101,17 @@ pi install npm:pi-mcp-adapter
 
 `<pkg>` is the installed package root — `~/.pi/agent/npm/node_modules/design-playbook` for a user install, `.pi/npm/node_modules/design-playbook` for a project install. Evidence also needs `pip install playwright && playwright install chromium`.
 
+## Install on other agents
+
+Generate adapter files for Cursor, Gemini CLI, OpenCode, Windsurf, GitHub Copilot, or any of 22 Tier-3 agents:
+
+```bash
+npx design-playbook init <agent>   # e.g. cursor, gemini-cli, windsurf
+npx design-playbook --list         # all 29 agents, shows which have renderers
+```
+
+See the root [README](../../README.md#install-on-other-agents) for the tier table and capability notes.
+
 ## Stack with other skills
 
 | Package | Use for |

package/codex/AGENTS.md

@@ -1,3 +1,4 @@
+<!-- generated-by design-playbook v0.21.2 -->
 # design-playbook for Codex
 
 ## Install (path of record)

package/commands/run-review.md

@@ -20,7 +20,7 @@ Scan user-side `.scratch/<run>/` (not monorepo `dogfood/*` globs). **Include** o
 Ledger row shape: **ui-evaluator** step 2 (do not restate).
 
 ```
-禁止:
+Prohibited:
 - no new run ledger
 - no prose lessons / narrative "learning"
 - no auto-writeback to baseline

package/commands/ui-review.md

@@ -2,7 +2,7 @@
 description: Dual-track UI review emitting the six-block point-back report (ledger / findings / positives / coverage / limitations / verdict)
 ---
 
-Run skill **ui-evaluator** (pull craft-guard checks when AI slop/motion/loading is in scope). Output issue/source/fix/severity; blocking first.
+Run skill **ui-evaluator** (pull craft-guard checks when AI slop/motion/loading is in scope). Output issue/source/fix/severity/track; blocking first.
 
 Scope:
 $ARGUMENTS

package/examples/dogfood/run/craft-guard.md

@@ -17,3 +17,12 @@ Registry: `skills/design-playbook/references/rules.md`, full catalog (P3 run:
 | I18N-01@1 | not-applicable | 单语控制台（zh-CN），无 i18n 声明（无 i18n.* 契约字段，L1 未声明多语言用户群） | - | - | - | 单语声明成立 | - |
 | PERF-01@1 | applicable | - | clear | 长运行有持续进度感（feed 条目级进度逐 tick 更新；全局暂停 busy 即时反馈） | evidence/L6.2-pause-trace.json 反馈序列 | 反馈相称性未承诺耗时阈值（契约无阈值声明） | - |
 | SEC-01@1 | not-applicable | 声明范围无敏感操作新增（敏感模拟参数默认脱敏沿用；全局暂停非敏感操作） | - | - | - | 无敏感面可查 | - |
+| COPY-01@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档（2026-08-14）；主动语态与动作命名一致性审查所需的全流程文案清单未采集 | - | - | - | - | - |
+| COPY-02@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；用户侧命名审查所需的界面名词与实现命名对照未采集 | - | - | - | - | - |
+| COPY-03@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；错误信息语气审查所需的错误态文案样本未采集 | - | - | - | - | - |
+| A11Y-02@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；可见键盘焦点判定所需的聚焦态截图与键盘走查未采集（a11y 树无法证明视觉属性） | - | - | - | - | - |
+| CRAFT-09@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；归档缺审计面样式源——filled-ui.md 为声明性产物索引不含样式源，candidates/preview 为一次性原型资产而非填充面源码 | - | - | - | - | - |
+| CRAFT-10@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；归档缺审计面源标记与结构装置的视觉捕捉——evidence 仅交互轨迹与 a11y 树 JSON，无填充面标记源归档 | - | - | - | - | - |
+| DECIDE-01@1 | applicable | - | clear | 选中方向为全局 run console 构成重组（candidates/console-region.html 草图 + preview round 1/2 用户确认），非未审视的默认外观收敛 | DD-0001 理由可回溯 l1.scenes（切页续读）与 PERF-01 比较轴及经用户确认的布局段突破；DD-0002 理由可回溯 l6.c4（跨视图状态闭环）与运行中心第一步方向——均引用 brief 具体事实 | 常规方向经比较矩阵沿 brief 轴证成，非未审视默认；无基线默认方向身份声明 | - |
+
+注：2026-08-28 注册批（COPY-01/02/03、A11Y-02、CRAFT-09/10、DECIDE-01）晚于本 run 存档；按三态谓词补记——blocked 行在理由列点名缺失的证据面；DECIDE-01 依归档内可读的决策报告求值为 applicable。

package/examples/export-entry/run/craft-guard.md

@@ -17,3 +17,12 @@ Registry: `skills/design-playbook/references/rules.md`, full catalog (P2 run). S
 | I18N-01@1 | not-applicable | 单语控制台，无 i18n 声明（无 i18n.* 契约字段，L1 未声明多语言用户群） | - | - | - | 单语声明成立 | - |
 | PERF-01@1 | blocked | 性能感知需运行时度量，本 run provider 缺度量面（measurement 层不可采） | - | 导出等待仅观察到 busy 态 | 度量面缺席，无法判定反馈与耗时的相称性 | 无法在不承诺阈值的情况下检查例外 | 补采运行时度量后重评；缺口的证据语义见 point-back 覆盖声明 |
 | SEC-01@1 | not-applicable | 声明范围无敏感操作新增（导出非敏感数据；隐藏敏感列由 column_scope 假设排除） | - | - | - | 无敏感面可查 | - |
+| COPY-01@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档（2026-08-14）；主动语态与动作命名一致性审查所需的全流程文案清单未采集 | - | - | - | - | - |
+| COPY-02@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；用户侧命名审查所需的界面名词与实现命名对照未采集 | - | - | - | - | - |
+| COPY-03@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；错误信息语气审查所需的错误态文案样本未采集 | - | - | - | - | - |
+| A11Y-02@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；可见键盘焦点判定所需的聚焦态截图与键盘走查未采集（a11y 树无法证明视觉属性） | - | - | - | - | - |
+| CRAFT-09@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；归档缺审计面样式源——filled-ui.md 为静态替身描述，无填充面样式源文件归档 | - | - | - | - | - |
+| CRAFT-10@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；归档缺审计面源标记——filled-ui.md 为静态替身描述；既有截图仅覆盖错误态，无结构装置的视觉捕捉 | - | - | - | - | - |
+| DECIDE-01@1 | applicable | - | clear | 选中方向为按周命名模式（compare 档轻量比较），不落入 2026-08 记录的自默认外观样貌；DD-0001 为 record 档，不在本规则范围 | DD-0002 理由可回溯 l1.target_user 比较轴（周频归档场景下检索是主任务）——引用 brief 具体事实而非通用措辞 | 常规方向经比较矩阵沿 brief 轴证成，非未审视默认；无基线默认方向身份声明 | - |
+
+注：2026-08-28 注册批（COPY-01/02/03、A11Y-02、CRAFT-09/10、DECIDE-01）晚于本 run 存档；按三态谓词补记——blocked 行在理由列点名缺失的证据面；DECIDE-01 依归档内可读的决策报告求值为 applicable。

package/examples/export-pointfix-upgrade/run/craft-guard.md

@@ -17,3 +17,12 @@ Registry: `skills/design-playbook/references/rules.md`. Seven-column rows; after
 | I18N-01@1 | not-applicable | 单语控制台，无 i18n 声明（无 i18n.* 契约字段，L1 未声明多语言用户群） | - | - | - | 单语声明成立 | - |
 | PERF-01@1 | blocked | 性能感知需运行时度量，本 run provider 缺度量面（measurement 层不可采） | - | 导出等待仅观察到 busy 态 | 度量面缺席，无法判定反馈与耗时的相称性 | 无法在不承诺阈值的情况下检查例外 | 补采运行时度量后重评；缺口的证据语义见 point-back 覆盖声明 |
 | SEC-01@1 | not-applicable | 声明范围无敏感操作新增（导出非敏感数据；隐藏敏感列由 column_scope 假设排除） | - | - | - | 无敏感面可查 | - |
+| COPY-01@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档（2026-08-14）；主动语态与动作命名一致性审查所需的全流程文案清单未采集 | - | - | - | - | - |
+| COPY-02@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；用户侧命名审查所需的界面名词与实现命名对照未采集 | - | - | - | - | - |
+| COPY-03@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；错误信息语气审查所需的错误态文案样本未采集 | - | - | - | - | - |
+| A11Y-02@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；可见键盘焦点判定所需的聚焦态截图与键盘走查未采集（a11y 树无法证明视觉属性） | - | - | - | - | - |
+| CRAFT-09@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；选择器优先级冲突审查所需的样式源走查未执行 | - | - | - | - | - |
+| CRAFT-10@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；结构装置与内容属性对应关系的走查未执行 | - | - | - | - | - |
+| DECIDE-01@1 | not-applicable | 决策报告仅含 record 档 DD-0101，无 compare/explore 档方向决策条目 | - | - | - | - | - |
+
+注：2026-08-28 注册批（COPY-01/02/03、A11Y-02、CRAFT-09/10、DECIDE-01）晚于本 run 存档；按三态谓词补记，blocked 行在理由列记缺失证据面。

package/examples/export-upgrade/run/craft-guard.md

@@ -17,3 +17,12 @@ Registry: `skills/design-playbook/references/rules.md`, full catalog (P3 run:
 | I18N-01@1 | not-applicable | 单语控制台，无 i18n 声明（无 i18n.* 契约字段，L1 未声明多语言用户群） | - | - | - | 单语声明成立 | - |
 | PERF-01@1 | applicable | - | clear | 长导出有持续进度感（30s 窗口 5 次采样，条目级进度持续更新） | evidence/L6.1-status-trace.json 进度采样序列 | 反馈相称性未承诺耗时阈值（契约无阈值声明） | - |
 | SEC-01@1 | not-applicable | 声明范围无敏感操作新增（导出非敏感数据；隐藏敏感列由 column_scope 假设排除） | - | - | - | 无敏感面可查 | - |
+| COPY-01@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档（2026-08-14）；主动语态与动作命名一致性审查所需的全流程文案清单未采集 | - | - | - | - | - |
+| COPY-02@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；用户侧命名审查所需的界面名词与实现命名对照未采集 | - | - | - | - | - |
+| COPY-03@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；错误信息语气审查所需的错误态文案样本未采集 | - | - | - | - | - |
+| A11Y-02@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；可见键盘焦点判定所需的聚焦态截图与键盘走查未采集（a11y 树无法证明视觉属性） | - | - | - | - | - |
+| CRAFT-09@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；归档缺审计面样式源——无填充产物源文件归档，candidates/preview 为一次性原型资产而非填充面源码 | - | - | - | - | - |
+| CRAFT-10@1 | blocked | 条目 2026-08-28 注册，晚于本 run 存档；归档缺审计面源标记与结构装置的视觉捕捉——evidence 仅交互轨迹 JSON，无填充产物源文件归档 | - | - | - | - | - |
+| DECIDE-01@1 | applicable | - | clear | 选中方向为启用既有 status region 收纳导出任务（candidates/B.html 草图 + preview round 1/2 用户确认），非未审视的默认外观收敛 | DD-0003 理由可回溯 l1.scenes（导出中切页全局可查）与 PERF-01 比较轴；DD-0004 理由可回溯 l6.c2（跨视图状态闭环）与基线 status region 惯例声明——均引用 brief 具体事实 | 常规方向经比较矩阵沿 brief 轴证成，非未审视默认；基线声明的是 status region 惯例而非默认外观身份 | - |
+
+注：2026-08-28 注册批（COPY-01/02/03、A11Y-02、CRAFT-09/10、DECIDE-01）晚于本 run 存档；按三态谓词补记——blocked 行在理由列点名缺失的证据面；DECIDE-01 依归档内可读的决策报告求值为 applicable。

package/lib/cli.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+'use strict'
+/**
+ * design-playbook CLI shim (ADR-0042).
+ *
+ * Locates python3/python and delegates to
+ * packages/design-playbook/scripts/generate_adapter.py with passthrough args.
+ *
+ *   npx design-playbook --list
+ *   npx design-playbook init <agent>
+ *   npx design-playbook <agent> --dry-run
+ */
+const { execFileSync } = require('node:child_process')
+const path = require('node:path')
+
+const SCRIPT = path.join(__dirname, '..', 'scripts', 'generate_adapter.py')
+
+function findPython() {
+  for (const bin of ['python3', 'python']) {
+    try {
+      const out = execFileSync(bin, ['--version'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+      if (/python\s+3\./i.test(out)) return bin
+    } catch {}
+  }
+  return null
+}
+
+const python = findPython()
+if (!python) {
+  process.stderr.write(
+    'error: design-playbook requires Python 3 (python3 or python).\n' +
+    'Install Python 3 from https://python.org and re-run.\n'
+  )
+  process.exit(1)
+}
+
+// Strip leading "init" if invoked as `design-playbook init <agent>` so both
+// forms are equivalent:  `design-playbook init codex` == `design-playbook codex`
+const rawArgs = process.argv.slice(2)
+const args = rawArgs[0] === 'init' ? rawArgs.slice(1) : rawArgs
+
+try {
+  execFileSync(python, [SCRIPT, ...args], { stdio: 'inherit' })
+} catch (err) {
+  process.exit(err.status ?? 1)
+}

package/mcp/evidence/README.md

@@ -8,7 +8,7 @@ Runtime for the optional **observe\*** step. Writes capture artifacts only — *
 | --- | --- |
 | Unset | Artifact paths resolve under the **MCP process cwd** |
 | `"."` (default in package `.mcp.json`) | Same — relative to process cwd, **not** the chat workspace root |
-| Absolute path | Preferred for cross-repo dogfood: set to the run root (e.g. `D:/…/nmg_bup_h5/.scratch/playbook-smoke/<run>`) so `evidence/L6.*.png` lands next to `manifest.jsonl` |
+| Absolute path | Preferred for cross-repo dogfood: set to the run root (e.g. `/path/to/host-app/.scratch/playbook-smoke/<run>`) so `evidence/L6.*.png` lands next to `manifest.jsonl` |
 
 Relative values are resolved with `Path(value).resolve()` at process start semantics (cwd-relative). If captures appear under the plugin monorepo instead of the host run, check cwd and this env — the tool also returns **`written_path`** (absolute) so mis-roots are obvious without a filesystem search.
 
@@ -16,7 +16,7 @@ Example (host run):
 
 ```json
 "env": {
-  "DESIGN_PLAYBOOK_RUN_ROOT": "D:/code_space/app/.scratch/my-run"
+  "DESIGN_PLAYBOOK_RUN_ROOT": "/path/to/app/.scratch/my-run"
 }
 ```
 

package/mcp/evidence/capture_runtime.py

@@ -662,7 +662,7 @@ def matrix_viewport(name: str) -> dict[str, Any]:
 def capture_delivery_matrix(
     *,
     url: str,
-    out_dir: Path | None = None,
+    out_dir: Path,
     freeze: dict[str, Any] | None = None,
     browser_adapter: BrowserAdapter | None = None,
 ) -> dict[str, dict[str, Any]]:
@@ -674,19 +674,19 @@ def capture_delivery_matrix(
     can assemble the ``disclosure-review.json`` matrix and the ``/export-zip``
     package from one pass.
 
-    ``out_dir`` defaults to the spec's canonical delivery path
-    ``output/playwright/static-handoff/`` (spec §5). ``browser_adapter`` uses
-    the same ``BrowserAdapter`` seam as ``execute_capture_plan`` (real
-    Playwright by default, injected fake in tests). Production adapters should
-    expose ``capture_and_probe`` so the snapshot and metrics share one page;
-    adapters without that seam remain explicitly ``unmeasured``.
+    ``out_dir`` is required and carries no default: handoff artifacts live
+    under the run tree (``<run_root>/evidence/static-handoff/``, ADR-0034 §5),
+    never the process CWD, so the caller must pass the run-tree destination
+    explicitly. ``browser_adapter`` uses the same ``BrowserAdapter`` seam as
+    ``execute_capture_plan`` (real Playwright by default, injected fake in
+    tests). Production adapters should expose ``capture_and_probe`` so the
+    snapshot and metrics share one page; adapters without that seam remain
+    explicitly ``unmeasured``.
     """
     freeze = freeze or {"enabled": True, "waitFonts": True, "networkIdle": False}
     if browser_adapter is None:
         browser_adapter = PlaywrightBrowserAdapter()
 
-    if out_dir is None:
-        out_dir = Path("output/playwright/static-handoff")
     out_dir = Path(out_dir)
     out_dir.mkdir(parents=True, exist_ok=True)
     results: dict[str, dict[str, Any]] = {}

package/mcp/evidence/disclosure.py

@@ -19,8 +19,10 @@ Two seams keep the contract builder pure and testable without a browser:
   It only normalizes caller-supplied facts into the §4.2 shape.
 
 ``build_handoff_zip()`` packages the disclosure credential plus any caller-
-supplied snapshot artifacts into a single ZIP for the local ``/export-zip``
-endpoint (Stage 9 delivery mount). It never reads outside the caller-provided
+supplied snapshot artifacts into a single ZIP. The Evidence-side builder
+(``handoff.py``) writes it to disk as ``static-handoff.zip`` next to the
+delivery page under ``<run_root>/evidence/static-handoff/`` (ADR-0034); no
+HTTP delivery endpoint exists. It never reads outside the caller-provided
 file list.
 """
 

package/mcp/evidence/handoff.py

@@ -59,6 +59,7 @@ class StaticHandoffResult:
     json_path: Path
     zip_path: Path
     index_html: Path
+    deliverable_html: Path
 
 
 def _iso_now() -> str:
@@ -691,7 +692,8 @@ def build_static_handoff(
     output (``filled-ui.html``) - the page the five-viewport matrix and the
     layout probe actually target (ADR-0034 §4). Everything is written under
     ``<run_root>/evidence/static-handoff/``: snapshots, the disclosure JSON,
-    the ZIP package, and a self-contained index page.
+    the ZIP package, a same-directory ``deliverable.html`` copy (the page's
+    relative link target, spec A5), and a self-contained index page.
     """
     run_root = Path(run_root)
     deliverable = Path(deliverable)
@@ -707,6 +709,14 @@ def build_static_handoff(
     if gate_runner is None:
         gate_runner = _run_gate_validation
 
+    # Read the deliverable source up front and fail fast: its bytes are the
+    # run identity (hash), the ZIP's prototype member, and the on-disk copy
+    # the delivery page links relatively (#107). A missing or undecodable
+    # source aborts before any capture launches or artifact is written, so a
+    # delivery page can never exist without its link target.
+    deliverable_bytes = deliverable.read_bytes()
+    deliverable_text = deliverable_bytes.decode("utf-8")
+
     # Sample conditional-gate preconditions BEFORE writing anything: this
     # builder's own output lives under evidence/, and a precondition sampled
     # afterwards would be one this run manufactured for itself.
@@ -769,7 +779,6 @@ def build_static_handoff(
     else:
         verdict = "Pending"
 
-    deliverable_bytes = deliverable.read_bytes()
     run_id = (
         f"static-handoff-{round_n}-{hashlib.sha256(deliverable_bytes).hexdigest()[:12]}"
     )
@@ -808,6 +817,13 @@ def build_static_handoff(
     json_path = out_dir / "disclosure-review.json"
     json_path.write_text(disclosure_json(payload), encoding="utf-8")
 
+    # The delivery page links "deliverable.html" as a same-directory relative
+    # anchor (spec A5: disk artifacts, same-directory relative links); the copy
+    # must exist beside index.html, byte-identical to the ZIP member, or the
+    # delivery surface ships a dead link (#107).
+    deliverable_copy = out_dir / "deliverable.html"
+    deliverable_copy.write_bytes(deliverable_bytes)
+
     artifacts: dict[str, str] = {}
     if snap_dir.is_dir():
         for vp in VIEWPORT_ORDER:
@@ -820,7 +836,7 @@ def build_static_handoff(
         artifact_files=artifacts,
         # spec §4.1: the handoff ships "snapshots and prototype code". PNGs
         # alone do not let the recipient rebuild the reviewed page.
-        text_members={"deliverable.html": deliverable_bytes.decode("utf-8")},
+        text_members={"deliverable.html": deliverable_text},
         zip_target=str(zip_path),
     )
 
@@ -835,4 +851,5 @@ def build_static_handoff(
         json_path=json_path,
         zip_path=zip_path,
         index_html=index_html,
+        deliverable_html=deliverable_copy,
     )

package/mcp/evidence/static_handoff_page.html

@@ -12,7 +12,7 @@
   *{box-sizing:border-box}
   body{margin:0;background:var(--bg);color:var(--ink);
     font:14px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC",
-    "Hiragino Sans GB","Microsoft YaHei",sans-serif;}
+    "Hiragino Sans GB","Microsoft YaHei","Noto Sans SC",sans-serif;}
   .wrap{max-width:960px;margin:0 auto;padding:32px 20px 64px;}
   header{border-bottom:2px solid var(--primary);padding-bottom:16px;margin-bottom:24px;}
   h1{margin:0;font-size:22px;letter-spacing:-.01em;}

package/mcp/evidence/test_handoff.py

@@ -195,8 +195,16 @@ class BuildStaticHandoffTests(unittest.TestCase):
             result = self._build(tmp, run_root)
             base = run_root / "evidence" / "static-handoff"
             self.assertEqual(result.out_dir, base)
-            for path in (result.json_path, result.zip_path, result.index_html):
+            for path in (
+                result.json_path,
+                result.zip_path,
+                result.index_html,
+                result.deliverable_html,
+            ):
                 self.assertTrue(path.is_file(), path)
+            # #107: the page's relative "deliverable.html" anchor must resolve
+            # in the same directory as index.html (spec A5).
+            self.assertEqual(result.deliverable_html, base / "deliverable.html")
             self.assertTrue((base / "snapshots" / "viewport-1280x900.png").is_file())
             # nothing outside the run tree
             self.assertFalse((tmp / "output").exists())
@@ -390,6 +398,30 @@ class BuildStaticHandoffTests(unittest.TestCase):
             result = self._build(tmp, run_root)
             self.assertEqual(result.payload["profile"], "unknown")
 
+    def test_missing_deliverable_fails_before_any_artifact_is_written(self) -> None:
+        """#107 coherence: a delivery page must never exist without its link
+        target. A missing Stage 7 source aborts the build up front, so nothing
+        lands under evidence/static-handoff/ - no page, no dead link."""
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as tmp_s:
+            tmp = Path(tmp_s)
+            run_root = _make_run(tmp)
+            missing = tmp / "filled-ui.html"  # never written
+            with self.assertRaises(OSError):
+                handoff.build_static_handoff(
+                    run_root,
+                    missing,
+                    round_n=1,
+                    summary="s",
+                    capture_runner=_fake_capture_runner,
+                    gate_runner=_passing_gate_runner,
+                )
+            self.assertFalse(
+                (run_root / "evidence" / "static-handoff").exists(),
+                "missing source must fail before any artifact is written",
+            )
+
 
 class HandoffPageTests(unittest.TestCase):
     def test_page_template_is_own_content_with_no_cdn(self) -> None:
@@ -430,6 +462,38 @@ class HandoffPageTests(unittest.TestCase):
             # No unsanitized injection from run-controlled text.
             self.assertNotIn("<script>", html[start:end])
 
+    def test_page_deliverable_link_target_exists_beside_the_page(self) -> None:
+        """#107: "Everything below sits next to it on disk" must be true.
+
+        The page links ``deliverable.html`` as a same-directory relative
+        anchor (spec A5), so the builder must write that copy beside
+        index.html, byte-identical to the ZIP member and the Stage 7 source.
+        """
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as tmp_s:
+            tmp = Path(tmp_s)
+            run_root = _make_run(tmp)
+            deliverable = tmp / "filled-ui.html"
+            deliverable.write_text(DELIVERABLE_HTML, encoding="utf-8")
+            result = handoff.build_static_handoff(
+                run_root, deliverable, round_n=1, summary="s",
+                capture_runner=_fake_capture_runner,
+                gate_runner=_passing_gate_runner,
+            )
+            html = result.index_html.read_text(encoding="utf-8")
+            self.assertIn('href="deliverable.html"', html)
+            on_disk = result.index_html.parent / "deliverable.html"
+            self.assertTrue(
+                on_disk.is_file(),
+                "the page's relative deliverable.html link must not dangle",
+            )
+            self.assertEqual(result.deliverable_html, on_disk)
+            with zipfile.ZipFile(result.zip_path) as zf:
+                member = zf.read("deliverable.html")
+            self.assertEqual(on_disk.read_bytes(), member)
+            self.assertEqual(on_disk.read_bytes(), deliverable.read_bytes())
+
 
 class GateNormalizationTests(unittest.TestCase):
     """Ported from the review-session surface; the logic now lives in handoff."""