design-playbook 0.24.4 → 0.25.1

package/README.md

@@ -1,6 +1,12 @@
 # design-playbook
 
-Agent plugin: **Design I/O** for product UI (Claude Code / Codex).
+Agent plugin for **evidence-backed UI delivery** in existing Web products
+(Claude Code / Codex). **Design I/O** is the declaration and contract mechanism.
+
+The project is in maintainer self-use and maintenance. Catalog submissions
+and recruitment are paused; installed paths remain available. Missing required
+proof stays `blocked`; an explicitly skipped evaluator records `audited: false`,
+not an audited Pass. Evaluator review does not replace human semantic approval.
 
 Declarations + contracts — not a style CSV pack. Compose with [ui-ux-pro-max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) and Anthropic `frontend-design` for aesthetics; this package owns pipeline and acceptance.
 
@@ -52,6 +58,7 @@ After install, skills and commands are **namespaced** by the plugin name:
 | `/design-playbook:craft-guard` | Craft / anti-slop skill |
 | `/design-playbook:native-craft` | Native-feel desktop declaration skill |
 | `/design-playbook:ui-evaluator` | Point-back acceptance skill |
+| `/design-playbook:component-distill` | Cross-run component/token proposal skill and command; report-only, promotion requires a user decision |
 | `/design-playbook:design-io` | Full pipeline command |
 | `/design-playbook:ux-spec` | Spec-only command |
 | `/design-playbook:ui-review` | Review command |
@@ -75,8 +82,8 @@ pi has no plugin namespace — skills are `/skill:<name>`, commands are bare `/<
 | Invoke | Role |
 | --- | --- |
 | `/skill:design-playbook` | Orchestrator skill (model-invoked) |
-| `/skill:ux-spec` … `/skill:ui-evaluator` | Same eight skills as above |
-| `/design-io` · `/ux-spec` · `/ui-review` · `/run-review` · `/run-status` · `/run-handoff` · `/doctor` | Pipeline / spec-only / review / cross-run / status / handoff / health commands |
+| `/skill:ux-spec` … `/skill:component-distill` | Same nine skills as above |
+| `/design-io` · `/ux-spec` · `/ui-review` · `/run-review` · `/run-status` · `/run-handoff` · `/doctor` · `/component-distill` | Pipeline / spec-only / review / cross-run / status / handoff / health / proposal commands |
 
 pi ships no built-in MCP, so `preview*` and `observe*` skip by default (ADR-0009 absent→skip; the pipeline still runs spec → picker → fill → craft → accept). To enable both gates, install an MCP adapter and register the bundled servers in your project `.mcp.json`:
 
@@ -113,7 +120,7 @@ npx design-playbook init <agent>   # e.g. cursor, gemini-cli, windsurf
 npx design-playbook --list         # all 30 agents, shows which have renderers
 ```
 
-See the root [README](../../README.md#install-on-other-agents) for the tier table and capability notes.
+See the root [README](../../README.md#-install-on-other-agents) for the tier table and capability notes.
 
 ## Stack with other skills
 
@@ -131,7 +138,7 @@ See the root [README](../../README.md#install-on-other-agents) for the tier tabl
 .mcp.json              ← bundled MCP servers, launched via ${CLAUDE_PLUGIN_ROOT} (ADR-0009)
 mcp/{preview,evidence}/← MCP adapter runtimes (preview_prototype / execute_capture_plan)
 skills/<name>/SKILL.md ← model-invoked skills
-commands/<name>.md     ← slash commands (design-io, ux-spec, ui-review, run-review, run-status, run-handoff, doctor)
+commands/<name>.md     ← slash commands; see invocation tables above
 codex/AGENTS.md        ← Codex bridge notes
 examples/              ← self-authored onboarding samples
 LICENSE · NOTICE       ← authored-only scope
@@ -159,6 +166,13 @@ python <pkg>/scripts/run_status.py --list                  # newest runs under .
 
 The status command reuses the packaged validator’s G5 confirm rules. It is part of the installed package — not monorepo-only tooling. For an eligible run it also reports an explicit `open-console` continuation command for the local Run Console (it never starts a server itself), with the blocking reason and a safe fallback when the run or Console prerequisites are ineligible. The Console’s current claim is **local, experimental, and trial-gated** — `run-status --json` reports the same capability receipt (`publicClaim: experimental`) — and no authorized external trial or public release is claimed until the separately authorized read-only trial gate passes (ADR-0043).
 
+The source checkout adds a bounded self-use report:
+`python <pkg>/scripts/run_status.py <run> --scope path:P1 --json`.
+It links explicit declarations, summarizes evidence gaps, and retains the original
+owner's re-verification requirements. Unknown impact cannot safely narrow that
+scope. See [scope inputs, source refresh, and limits](commands/run-status.md).
+This is not a release or measured productivity claim.
+
 ### Static handoff
 
 ```text
@@ -176,7 +190,7 @@ python <pkg>/scripts/doctor.py --json
 
 One packaged diagnosis for interpreter, package surface, optional Playwright, and run-root configuration. Distinguishes `ok` / `degraded` / `broken` with repair actions. Those three states describe **install and runtime health** of what is present locally — they are not a public capability-maturity verdict; maturity vocabulary (`stable` / `experimental` / `blocked-by-gate` / `not-shipped`) stays with the `run-status` capability receipt, and doctor reads existing facts rather than adding a new health or capability-state authority.
 
-**Bundled MCP (v0.3+):** Preview (`mcp/preview/`) and Evidence (`mcp/evidence/`) runtimes ship inside this package and are registered by `.mcp.json` (`${CLAUDE_PLUGIN_ROOT}`). Sibling monorepo dirs remain compatibility launchers/docs. The orchestrator still **probes** MCP `tools/list` and skips `preview*` / `observe*` when tools are absent. Evidence provider writes artifacts only — never the manifest. **`DESIGN_PLAYBOOK_RUN_ROOT`:** default `"."` in `.mcp.json` is the **MCP process cwd**, not the chat workspace — for a host-app dogfood, set an **absolute** path to `.scratch/<run>/` (see [`mcp/evidence/README.md`](mcp/evidence/README.md)). Capture responses include `written_path` (absolute) so mis-rooted writes are visible without a filesystem search.
+**Bundled MCP (v0.3+):** Preview (`mcp/preview/`) and Evidence (`mcp/evidence/`) runtimes ship inside this package and are registered by `.mcp.json` (`${CLAUDE_PLUGIN_ROOT}`). Sibling monorepo dirs remain compatibility launchers/docs. The orchestrator still **probes** MCP `tools/list` and skips `preview*` / `observe*` when tools are absent. Evidence provider writes artifacts only — never the manifest. **`DESIGN_PLAYBOOK_RUN_ROOT`:** `.mcp.json` passes this variable through without pinning a default. With no explicit root, artifacts resolve under the **MCP process cwd**, not necessarily the chat workspace. For a host-app run, use an absolute `.scratch/<run>/` root; per-call overrides and marker requirements are documented in [`mcp/evidence/README.md`](mcp/evidence/README.md). Capture responses include `written_path` (absolute) so mis-rooted writes are visible without a filesystem search.
 
 What is **deterministically enforced** today: repository install/structure CI checks and the run-artifact shape (`scripts/validate_run.py` — L1–L6 present; every top-level L6 item ordered `Given -> When -> Then`; one non-empty four-field evidence ledger row per `L6.<n>` with allowed results; four non-empty finding fields with non-empty source; exactly one explicit `## Verdict` of `Pass` or `Recirculate`; Pass requires every evidence result to be `pass` and exactly one issue-linked `0 blocking` closure per blocking finding; exit 0/`RUN OK`, exit 1/`RUN INVALID`, exit 2/`RUN ERROR`; regression-tested by `tests/test_validate_run.py`, which also validates the showcase artifacts directly; **G5** is a *conditional* preview-confirm gate — enforced only when preview artifacts exist / `--preview-dir` is used; **G6** is a *conditional* evidence-binding gate — enforced only when a ledger `observed` references an `evidence/` artifact / `--evidence-dir` is used; opt-in **strict mode** via `--require-preview` / `--require-evidence` / `--strict`). The `observe*` step probes MCP tool `execute_capture_plan` and is skipped when absent. Everything else in the pipeline is agent-executed craft judgment, not a machine gate.
 

package/codex/AGENTS.md

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

package/codex/install_skills.py

@@ -66,4 +66,13 @@ def main(argv: list[str] | None = None) -> int:
 
 
 if __name__ == "__main__":
+    # One pipe-encoding seam (T-105): UTF-8 on piped stdout/stderr
+    # regardless of the host code page. See scripts/stdio_encoding.py.
+    for _candidate in Path(__file__).resolve().parents:
+        if (_candidate / "design_playbook.py").is_file():
+            sys.path.insert(0, str(_candidate))
+            break
+    from design_playbook.scripts.stdio_encoding import configure_piped_utf8
+
+    configure_piped_utf8()
     sys.exit(main())

package/commands/component-distill.md

@@ -0,0 +1,8 @@
+---
+description: Cross-run component backflow — derive recurring components from iterated pages and render a propose-only DESIGN.md promotion proposal (report-only, user-gated)
+---
+
+Cross-run **component backflow** over `.scratch/<run>/` decision reports in the user project. Not a step of a single Design I/O run. Run skill **component-distill**. Proposal header **`component-distill/v1`**; report-only — never writes `DESIGN.md` or any authority; promotion is a user decision recorded in the governance log and executed only by `design_baseline.py promote`.
+
+Output path:
+$ARGUMENTS

package/commands/run-status.md

@@ -18,6 +18,90 @@ python <plugin>/scripts/run_status.py [.scratch/<run>] [--json] [--list] [--scra
 
 For an eligible run the continuation names an explicit `open-console` command for the local, experimental, trial-gated Run Console — no authorized external trial or public release is claimed until the separately authorized read-only trial gate passes (ADR-0043). `run-status` never starts a server, daemon, or background process itself; an ineligible run reports the blocking reason and a safe fallback instead. On Windows the emitted command line is PowerShell syntax (single-quoted literals behind the `&` call operator) — paste it into PowerShell, not cmd.exe.
 
+## Explicit frontend scope review
+
+The source checkout also provides a bounded, read-only report for self-use. It
+has no separate Console panel or persistent mapping, and no measured time-saving
+or released-package claim.
+
+```text
+python <plugin>/scripts/run_status.py <run> --scope path:P1 --scope page:checkout
+python <plugin>/scripts/run_status.py <run> --scope component:Retry --json
+python <plugin>/scripts/run_status.py <run> --scope path:P1 --git-root <repo> --base-revision <base> --head-revision <head> --json
+python <plugin>/scripts/run_status.py <run> --scope path:P1 --git-root <repo> --base-revision <base> --worktree --json
+```
+
+- A run path and at least one `--scope` are required. Scope mode does not discover
+  runs and cannot combine with `--list`; `--scratch` only applies to discovery.
+  Its JSON is a scope report, not the legacy status JSON or Run Snapshot v1. It
+  carries `schemaVersion: 1`; every member of `evidence_gaps[].bindings[]` has the
+  same keys `integrity`, `reasons`, `source`, `content_hash`, and an unbound or
+  unreadable entry reports `source: null` / `content_hash: null` rather than
+  dropping those keys.
+- Repeated scopes accept `path:P1`, `page:<id>`, `component:<id>`, and
+  `file:<relative/path>`. Paths must stay within the explicit Git root, or the
+  selected run if no Git root was given. Absolute paths and traversal are rejected.
+- Known links require an L3 `Path | Steps` row and an L6 `(path: P1)` reference.
+  Page links additionally require an exact L2 `Page | Duty` entry and an exact
+  step token separated by `->` or an arrow. Free-form prose is not a code
+  dependency map. Assumptions stay `assumed`; component and file clues currently
+  remain `unknown`. No association means unknown, never unaffected.
+- Git is optional. When requested, supply the actual repository root, a base,
+  and exactly one of a head revision or `--worktree`. Worktree mode includes
+  untracked paths. The report neither guesses a base nor scans source code.
+
+Evidence requirements are read only where an L6 item already declares a precise
+continuation, for example:
+
+```text
+- Given checkout fails When retry is offered Then recovery is visible (path: P1)
+  Required evidence: screenshot; state=error; viewport=390x844
+```
+
+The recognized proof values are `screenshot`, `a11y_tree`, and
+`interaction_trace`; `state` and `viewport` are optional and appear in that order.
+This optional read convention adds no mandatory spec field. Missing or
+unrecognized prose stays `unknown`; conflicting declarations stay `inconsistent`.
+The separate sampling summary enumerates only nonblank L5 state cells.
+`reported` means a sampling claim, not a verified proof binding.
+
+The report separates source availability, binding integrity, evidence gaps, and
+the original evaluator result. Missing required proof is `blocked`; skipping the
+evaluator remains `unaudited`. An owner ledger that exists but cannot be
+projected is never read as an absent one: every gap gains the
+`pointback-malformed` reason, and sources that are still current report the
+evaluation as `inconsistent` rather than `unknown`. Binding timestamps order
+by instant, so mixed `Z` / `+HH:MM` stamps pick the real latest capture: a
+stamp that is missing, offset-less, or not ISO-8601 reports
+`invalid-binding-timestamp`, and two distinct entries sharing the latest
+instant report `conflicting-bindings`; both leave the binding `inconsistent`.
+Not-applicable and unreviewed reasons are referenced at their source, not
+copied as private prose.
+It does not start a Provider, read browser login state, emit capture URLs or
+source code, write run artifacts, or grant semantic approval. Treat scope names
+and relative file paths as local data.
+
+Reverification candidates retain the original Repair Packet's invalidated set,
+owner, resume stage, and recapture requirement. **They cannot safely narrow the
+original owner scope**: declaration links do not prove exhaustive code impact.
+No repair or acceptance command is executed.
+
+Before copying an owner command from an earlier report, repeat the same inputs
+with its `source_hash`:
+
+```text
+python <plugin>/scripts/run_status.py <run> --scope path:P1 --expected-source-hash sha256:<previous-hash> --json
+```
+
+Changed or owner-unverified sources make the report `stale` and remove the copyable command.
+Unavailable contracts also suppress it. Refresh the report and use the existing
+owner workflow; a source check does not lock files against later edits.
+Exit 0 means a report was produced, not that the run passed acceptance.
+Invalid inputs or unreadable/out-of-root sources exit 2.
+
 ## Done when
 
 The command names completed stage markers, any active blocker (preview floor, baseline gate, recirculate verdict), and the single next valid resume action. It reuses `validate_run` judgments for G5 confirm validity rather than inventing a second state machine. Stale, partial, hash-mismatched, malformed, or inconsistent runs stay visible as those states and are never replaced by an older successful snapshot.
+
+In scope mode, known links are traceable to their declaration and hash, uncertain
+links remain explicit, and diagnostic gaps never replace the evaluator verdict.

package/lib/index.js

@@ -8,8 +8,9 @@
  *    `skills/` directory. The plugin locates the directory via `__dirname`,
  *    so no `!!js` expression and no cwd-dependent resolution is involved.
  *
- * 2. Slash commands (ctx.commands) — `design-io`, `doctor`,
- *    `run-handoff`, `run-review`, `run-status`, `ui-review`, `ux-spec` —
+ * 2. Slash commands (ctx.commands) — `component-distill`, `design-io`,
+ *    `doctor`, `run-handoff`, `run-review`, `run-status`, `ui-review`,
+ *    `ux-spec` —
  *    that load the matching `commands/<name>.md` prompt, substitute
  *    `$ARGUMENTS` with the raw trailing input, and inject it as a
  *    user-role follow-up turn via `agent.followup()`.
@@ -87,6 +88,7 @@ exports.createUserMessageFromPrompt = createUserMessageFromPrompt
  * substituted) is injected as a user follow-up turn.
  */
 const COMMAND_NAMES = [
+  'component-distill',
   'design-io',
   'doctor',
   'run-handoff',

package/mcp/evidence/README.md

@@ -6,11 +6,21 @@ Runtime for the optional **observe\*** step. Writes capture artifacts only — *
 
 | Setting | Meaning |
 | --- | --- |
-| Unset | Artifact paths resolve under the **MCP process cwd** |
-| `"."` (default in package `.mcp.json`) | Same — relative to process cwd, **not** the chat workspace root |
+| Unset | Artifact paths resolve under the **MCP process cwd** (the packaged `.mcp.json` passes the variable through, it does not pin a value) |
+| `"."` (a host config that pins it) | Same — relative to process cwd, **not** the chat workspace root |
 | 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.
+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) plus a `warnings` entry so mis-roots are obvious without a filesystem search.
+
+**Cannot restart the server (`--plugin-dir` dev load)?** Pass `run_root` on the tool call — an absolute `.scratch/<run>/` that already carries a run marker (`plan.md` / `point-back.md`). Resolution order is `run_root` → `DESIGN_PLAYBOOK_RUN_ROOT` → process cwd, and the argument binds only that one call, so a mistyped or markerless root fails the capture instead of scattering evidence.
+
+## What each capture type writes
+
+| `type` | Bytes | Name it |
+| --- | --- | --- |
+| `screenshot` | PNG (plus a `<stem>.probe.json` sidecar when the adapter can probe) | `evidence/<leaf>.png` |
+| `a11y tree` | JSON envelope `{"format": "aria_snapshot", "tree": "…"}` — `tree` is Playwright's indentation text, not a node/role tree | `evidence/<leaf>.json` |
+| `interaction trace` | Playwright trace **ZIP** (actions + snapshots inside) | `evidence/<leaf>.trace.zip` — the Provider refuses a non-`.zip` name |
 
 Example (host run):
 
@@ -20,7 +30,7 @@ Example (host run):
 }
 ```
 
-Plugin auto-load: [`../.mcp.json`](../.mcp.json) (under `packages/design-playbook/`).  
+Plugin auto-load: [`../../.mcp.json`](../../.mcp.json) (under `packages/design-playbook/`).
 Codex / manual: sibling [`mcp.example.toml`](../../../design-playbook-evidence/mcp.example.toml).
 
 ## Return shape

package/mcp/evidence/capture_runtime.py

@@ -11,7 +11,8 @@ from __future__ import annotations
 import json
 import math
 import os
-from pathlib import Path
+from contextvars import ContextVar
+from pathlib import Path, PurePosixPath, PureWindowsPath
 from typing import Any, Protocol
 
 from design_playbook.mcp.evidence import containment
@@ -22,6 +23,7 @@ from design_playbook.mcp.evidence.action_params import (
 from design_playbook.mcp.evidence.capture_contract import parse_capture_contract
 from design_playbook.mcp.evidence.path_syntax import (
     probe_sidecar_rel,
+    trace_artifact_error,
     trimmed_relpath,
 )
 from design_playbook.mcp.evidence.disclosure import (
@@ -50,6 +52,7 @@ ALLOWED_ARGUMENTS = frozenset(
         "viewport",
         "freeze",
         "storage_state",
+        "run_root",
     }
 )
 RUN_ROOT_ENV = "DESIGN_PLAYBOOK_RUN_ROOT"
@@ -110,6 +113,10 @@ def _failed(
     }
     if request is not None:
         payload["request"] = request
+    if written_path and _run_root_misrooted():
+        # Same misroot warning as the success payload: a failed write outside
+        # the run tree is exactly where the orchestrator needs the hint.
+        payload["warnings"] = [_MISROOTED_WARNING]
     return payload
 
 
@@ -138,6 +145,10 @@ def _captured(
         "written_path": written_path,
         "request": request,
     }
+    if _run_root_misrooted():
+        # The stderr warning fires once per process and may never reach the
+        # model; the payload is what the orchestrator actually reads.
+        payload["warnings"] = [_MISROOTED_WARNING]
     if probe_artifact:
         payload["probe_artifact"] = probe_artifact
     return payload
@@ -270,20 +281,87 @@ def _apply_freeze(page: Any, freeze: dict[str, Any]) -> None:
 _RUN_MARKERS = ("plan.md", "point-back.md")
 _warned_run_root = False
 
+# Per-call run root (DEF-4): a `--plugin-dir` dev host cannot edit the shipped
+# DESIGN_PLAYBOOK_RUN_ROOT after the MCP process starts, so
+# `execute_capture_plan` accepts a `run_root` argument that binds the
+# resolution for the duration of one call and nothing longer.
+_CALL_RUN_ROOT: ContextVar["Path | None"] = ContextVar(
+    "design_playbook_call_run_root", default=None
+)
+
+_MISROOTED_WARNING = (
+    "run root resolved to a markerless cwd (DESIGN_PLAYBOOK_RUN_ROOT "
+    "unset or '.'); written_path is outside the run tree — pass "
+    "run_root=<abs .scratch/<run>/> on the recapture (no server restart "
+    "needed) or set DESIGN_PLAYBOOK_RUN_ROOT before launch"
+)
+
+
+def _has_run_marker(root: Path) -> bool:
+    """True when ``root`` carries one of the run's own marker artifacts."""
+    return any((root / marker).is_file() for marker in _RUN_MARKERS)
+
+
+def _validated_call_run_root(value: object) -> Path:
+    """Normalize an explicit ``run_root`` argument.
+
+    Absolute, existing, and marker-carrying: a mistyped root must fail the
+    call rather than scatter evidence into a directory that is not a run.
+    """
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError("run_root must be a non-empty absolute path string")
+    raw = value.strip()
+    if not (
+        Path(raw).is_absolute()
+        or PureWindowsPath(raw).is_absolute()
+        or PurePosixPath(raw).is_absolute()
+    ):
+        raise ValueError(f"run_root must be an absolute path (got {raw!r})")
+    root = Path(raw).expanduser().resolve()
+    if not root.is_dir():
+        raise ValueError(
+            f"run_root {root} is not an existing directory; pass the run root "
+            ".scratch/<run>/"
+        )
+    if not _has_run_marker(root):
+        raise ValueError(
+            f"run_root {root} carries no run marker "
+            f"({' / '.join(_RUN_MARKERS)}); pass the run root, not the "
+            "workspace root or the evidence/ directory"
+        )
+    return root
+
+
+def _run_root_misrooted() -> bool:
+    """True when the run root fell back to a markerless cwd.
+
+    The shipped .mcp.json default (DESIGN_PLAYBOOK_RUN_ROOT=".") makes the
+    server resolve artifacts under its process cwd; in a host workspace that
+    cwd is the repo root, so captures silently land outside the run tree.
+    A per-call ``run_root`` is marker-validated before use, so it is never
+    misrooted.
+    """
+    if _CALL_RUN_ROOT.get() is not None:
+        return False
+    configured = os.environ.get(RUN_ROOT_ENV)
+    if configured and configured != ".":
+        return False
+    return not _has_run_marker(Path.cwd().resolve())
+
 
 def _run_root() -> Path:
+    explicit = _CALL_RUN_ROOT.get()
+    if explicit is not None:
+        return explicit
     configured = os.environ.get(RUN_ROOT_ENV)
     if not configured or configured == ".":
-        # cwd-relative default silently mis-roots multi-run workspaces (the
-        # root .mcp.json ships DESIGN_PLAYBOOK_RUN_ROOT="."). Warn only when
-        # cwd does not look like a run dir (no run marker file) — the shipped
-        # default resolving to a real run dir is correct usage, not a
-        # misconfig — and only once per process to avoid per-capture spam.
+        # Warn only when cwd does not look like a run dir (no run marker
+        # file) — the shipped default resolving to a real run dir is correct
+        # usage, not a misconfig — and only once per process to avoid
+        # per-capture spam.
         root = Path.cwd().resolve()
         global _warned_run_root
-        if not _warned_run_root and not any(
-            (root / marker).is_file() for marker in _RUN_MARKERS
-        ):
+        if not _warned_run_root and _run_root_misrooted():
             _warned_run_root = True
             _log(
                 "WARNING: DESIGN_PLAYBOOK_RUN_ROOT is unset or '.' "
@@ -291,7 +369,8 @@ def _run_root() -> Path:
                 f"({' / '.join(_RUN_MARKERS)}); artifacts resolve under "
                 f"{root}/evidence/. Set DESIGN_PLAYBOOK_RUN_ROOT to the run "
                 "root when the host workspace is not the intended run "
-                "directory."
+                "directory, or pass run_root=<abs run root> on the capture "
+                "call when the server cannot be restarted."
             )
         return root
     return Path(configured).resolve()
@@ -765,6 +844,34 @@ def _validate_runtime_object(
 def execute_capture_plan(
     args: dict[str, Any],
     browser_adapter: BrowserAdapter | None = None,
+) -> dict[str, Any]:
+    """Capture one artifact, then report the result (never a verdict).
+
+    Run root resolution order: an explicit ``run_root`` argument (bound to
+    this call only) → ``DESIGN_PLAYBOOK_RUN_ROOT`` → process cwd. The explicit
+    root is marker-validated before use, so a dev host that cannot restart the
+    MCP server still lands evidence inside the run tree (DEF-4).
+    """
+    raw_run_root = args.get("run_root")
+    if raw_run_root is None:
+        return _capture(args, browser_adapter)
+    artifact = args.get("artifact_path")
+    label = artifact if isinstance(artifact, str) else ""
+    try:
+        root = _validated_call_run_root(raw_run_root)
+    except (ValueError, OSError) as exc:
+        # OSError is in range: Path.resolve() rejects host-illegal characters.
+        return _failed(label, str(exc))
+    token = _CALL_RUN_ROOT.set(root)
+    try:
+        return _capture(args, browser_adapter)
+    finally:
+        _CALL_RUN_ROOT.reset(token)
+
+
+def _capture(
+    args: dict[str, Any],
+    browser_adapter: BrowserAdapter | None,
 ) -> dict[str, Any]:
     unknown = sorted(set(args) - ALLOWED_ARGUMENTS)
     if unknown:
@@ -797,6 +904,9 @@ def execute_capture_plan(
         raise ValueError("storage_state must be a string path when provided")
 
     rel = artifact_path.strip()
+    trace_error = trace_artifact_error(cap_type, rel)
+    if trace_error:
+        return _failed(rel, trace_error, request=request)
     try:
         out_path = _resolve_artifact_path(rel)
     except ValueError as exc:

package/mcp/evidence/containment.py

@@ -23,6 +23,11 @@ consume it instead of mirroring the escape classes. The ``evidence/``
 operations remain the ADR-0026 contract surface - same reason codes, same
 existence timing - now expressed as specializations of the one resolver.
 
+ADR-0044 adds the Diagnostic export write boundary as a third specialization:
+``trial_export_write_target`` confines one bare filename under
+``<run_root>/trial-export/`` (the trial-export subtree), with the same
+reason-code discipline and TOCTOU limit.
+
 Threat-model limit (ADR-0026, explicit): this module resolves and validates
 the path; it does NOT perform the write. Path resolution alone cannot close
 the TOCTOU gap - a concurrent untrusted filesystem actor that replaces a
@@ -50,6 +55,9 @@ REASON_RESOLUTION_FAILURE = "resolution_failure"
 REASON_CANONICAL_ESCAPE = "canonical_escape"
 REASON_SYMLINK_ESCAPE = "symlink_escape"
 REASON_NOT_REGULAR_FILE = "not_regular_file"
+# Trial-export targets (ADR-0044) accept bare filenames only; a name that
+# carries any separator or reserved form is rejected before resolution.
+REASON_RESERVED_NAME = "reserved_name"
 
 # Every resolution-time escape reason (the classes the ADR requires both
 # operations to reject at resolution time). The Provider treats all of these
@@ -203,3 +211,86 @@ def read_artifact(artifact_path: str, run_root: Path) -> ContainmentResult:
     must not bind a directory or a missing path).
     """
     return _resolve(artifact_path, run_root, require_existing_file=True)
+
+
+# The Diagnostic export write boundary (ADR-0044): one subtree, sibling of
+# evidence/, owned here so the export transaction cannot disagree with the
+# one containment authority on where trial exports may land.
+TRIAL_EXPORT_SUBDIR = "trial-export"
+
+# Names the export subtree may never carry. ``manifest.jsonl`` is reserved
+# across the run tree (the Evidence Manifest authority); the current-directory
+# name is a no-op write and is refused as malformed rather than silently
+# permitted.
+_TRIAL_EXPORT_RESERVED_NAMES = frozenset({"manifest.jsonl", "", ".", ".."})
+
+# Win32 name quirks that CreateFile folds but Path.resolve does not: a
+# trailing dot or space vanishes on write (the on-disk name would diverge
+# from the reviewed one), and the reserved device names are never regular
+# files. The export writes exactly the reviewed pair, so both classes are
+# rejected as reserved.
+_WIN32_DEVICE_NAMES = frozenset(
+    {"CON", "PRN", "AUX", "NUL",
+     *(f"COM{i}" for i in range(1, 10)),
+     *(f"LPT{i}" for i in range(1, 10))},
+)
+
+
+def trial_export_write_target(filename: str, run_root: Path) -> ContainmentResult:
+    """Resolve a Diagnostic export write target under ``trial-export/``.
+
+    ``filename`` must be a bare filename - no directory separators (native,
+    POSIX, or Windows), no drive form, no ``..`` segment, and not one of the
+    reserved names, Win32 fold forms (trailing dot or space), or reserved
+    device stems - anything the platform would write under a different name
+    than the one reviewed. Same resolution-time escape
+    rejection and TOCTOU limit as every operation in this module; the
+    transaction performs the staged write and rollback around this resolution.
+    """
+    if not isinstance(filename, str) or filename == "":
+        return ContainmentResult(None, REASON_RESERVED_NAME)
+    if filename in _TRIAL_EXPORT_RESERVED_NAMES:
+        return ContainmentResult(None, REASON_RESERVED_NAME)
+    # Bare-filename precondition: any separator, drive, or traversal form
+    # fails before the generic resolver can even see it.
+    if (
+        PurePosixPath(filename).is_absolute()
+        or PureWindowsPath(filename).is_absolute()
+        or "/" in filename
+        or "\\" in filename
+        or any(part == ".." for part in PurePosixPath(filename).parts)
+        or any(part == ".." for part in PureWindowsPath(filename).parts)
+        or ":" in filename
+    ):
+        return ContainmentResult(None, REASON_ABSOLUTE_PATH)
+    # Win32 fold classes: a trailing dot/space or a reserved device stem
+    # would make the on-disk name differ from the reviewed name.
+    if filename != filename.rstrip(" ."):
+        return ContainmentResult(None, REASON_RESERVED_NAME)
+    if filename.split(".", 1)[0].upper() in _WIN32_DEVICE_NAMES:
+        return ContainmentResult(None, REASON_RESERVED_NAME)
+    # The boundary subtree itself must be a real child of the run root: a
+    # ``trial-export`` symlink pointing outside the run root would make the
+    # generic under-boundary check pass while writing outside the selected
+    # run, so the resolved boundary is required to stay inside the resolved
+    # run root before anything else is resolved against it.
+    try:
+        resolved_root = run_root.resolve(strict=False)
+        boundary = (run_root / TRIAL_EXPORT_SUBDIR).resolve(strict=False)
+        Path(os.path.realpath(boundary)).relative_to(
+            Path(os.path.realpath(resolved_root))
+        )
+    except (OSError, ValueError):
+        return ContainmentResult(None, REASON_SYMLINK_ESCAPE)
+    result = _resolve_candidate(
+        run_root,
+        f"{TRIAL_EXPORT_SUBDIR}/{filename}",
+        run_root / TRIAL_EXPORT_SUBDIR,
+        require_existing_file=False,
+    )
+    # The generic resolver also folds "." segments; a name like "a/." or
+    # "a.." is a file name here, but a name that Path normalizes to
+    # something other than itself inside the subtree must not pass.
+    if result.ok and result.path is not None and result.path.name != filename:
+        return ContainmentResult(None, REASON_RESERVED_NAME)
+    return result

package/mcp/evidence/disclosure.py

@@ -1,8 +1,7 @@
 """Static-handoff disclosure review builder (Stage 9 evidence).
 
 Produces the ``disclosure-review.json`` delivery credential defined by the
-Static Handoff spec (docs/specs/2026-08-22-interactive-review-and-static-handoff
--implementation-plan.md §4.2): a single authoritative payload binding the run
+Static Handoff contract (ADR-0034): a single authoritative payload binding the run
 identity, verdict, profile, decision authority, the five standard viewport
 layout metrics (``sw`` / ``innerH`` / ``hOverflow`` / ``disclosure.inFold``),
 and the G1–G8 gate count — so a front-end/QA consumer can reproduce and audit
@@ -16,7 +15,7 @@ Two seams keep the contract builder pure and testable without a browser:
   The probe JS string is also exposed (``LAYOUT_PROBE_JS``) for a static
   syntax/structure check.
 * ``build_disclosure(...)`` — deterministic pure builder: no I/O, no browser.
-  It only normalizes caller-supplied facts into the §4.2 shape.
+  It only normalizes caller-supplied facts into the disclosure shape.
 
 ``build_handoff_zip()`` packages the disclosure credential plus any caller-
 supplied snapshot artifacts into a single ZIP. The Evidence-side builder

package/mcp/evidence/evidence_preflight.py

@@ -25,6 +25,7 @@ import json
 import re
 import sys
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Any
 
 try:
@@ -37,8 +38,10 @@ try:
         parse_capture_contract,
     )
     from design_playbook.mcp.evidence.path_syntax import (  # noqa: E402
+        TRACE_SUFFIX,
         lexical_posix_key,
         probe_sidecar_rel,
+        trace_artifact_error,
         trimmed_relpath,
     )
 except ImportError:  # standalone execution: same-dir seam (rules_registry pattern)
@@ -52,8 +55,10 @@ except ImportError:  # standalone execution: same-dir seam (rules_registry patte
     )
     from capture_contract import parse_capture_contract  # noqa: E402
     from path_syntax import (  # noqa: E402
+        TRACE_SUFFIX,
         lexical_posix_key,
         probe_sidecar_rel,
+        trace_artifact_error,
         trimmed_relpath,
     )
 
@@ -133,6 +138,14 @@ def preflight_entry(request: object, entry: int) -> list[PreflightFact]:
                                 expected="relative path starting with "
                                          f"{ARTIFACT_PREFIX!r}",
                                 actual=artifact))
+        elif isinstance(capture_type, str) and (
+            name_error := trace_artifact_error(capture_type, artifact)
+        ):
+            # Same rule the Provider rejects with (path_syntax), reported here
+            # before a browser starts (DEF-6).
+            facts.append(_error("bad_artifact_extension", name_error, entry,
+                                expected=f"name ending in {TRACE_SUFFIX}",
+                                actual=artifact))
 
     actions = request.get("actions")
     if actions is not None:
@@ -291,8 +304,15 @@ def preflight_plan(plan: object) -> list[PreflightFact]:
 
 
 def main(argv: list[str] | None = None) -> int:
-    if sys.stdout and hasattr(sys.stdout, "reconfigure"):
-        sys.stdout.reconfigure(encoding="utf-8")  # Windows GBK consoles
+    # One pipe-encoding seam (T-105): UTF-8 on piped stdout/stderr
+    # regardless of the host code page. See scripts/stdio_encoding.py.
+    for _candidate in Path(__file__).resolve().parents:
+        if (_candidate / "design_playbook.py").is_file():
+            sys.path.insert(0, str(_candidate))
+            break
+    from design_playbook.scripts.stdio_encoding import configure_piped_utf8
+
+    configure_piped_utf8()
     args = sys.argv[1:] if argv is None else argv
     md = "--md" in args
     paths = [a for a in args if a != "--md"]