design-playbook 0.25.0 → 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.25.0 -->
+<!-- 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/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/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"
@@ -278,30 +281,78 @@ 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 — set "
-    "DESIGN_PLAYBOOK_RUN_ROOT to the run root (.scratch/<run>/) "
-    "before binding this artifact"
+    "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
-    root = Path.cwd().resolve()
-    return not any((root / marker).is_file() for marker in _RUN_MARKERS)
+    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 == ".":
         # Warn only when cwd does not look like a run dir (no run marker
@@ -318,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()
@@ -792,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:
@@ -824,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/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"]

package/mcp/evidence/path_syntax.py

@@ -31,3 +31,29 @@ def probe_sidecar_rel(artifact_rel: str) -> str:
     if "." in artifact_rel.rsplit("/", 1)[-1]:
         return artifact_rel.rsplit(".", 1)[0] + ".probe.json"
     return artifact_rel + ".probe.json"
+
+
+# On-disk shape of an interaction trace (DEF-6): ``tracing.stop(path=...)``
+# writes a Playwright trace ZIP, so any other extension mislabels binary bytes.
+TRACE_SUFFIX = ".zip"
+TRACE_EXAMPLE = "evidence/<criterion>.trace.zip"
+
+
+def trace_artifact_error(capture_type: str, artifact_rel: str) -> str:
+    """Naming error when a trace capture is not named ``.zip``; "" otherwise.
+
+    One definition for the capture runtime (hard reject) and the static
+    preflight (early fact), so a plan never passes preflight only to fail there.
+    An empty name is left to the required-field check at each call site.
+    """
+    if (
+        capture_type == "interaction trace"
+        and artifact_rel
+        and not artifact_rel.casefold().endswith(TRACE_SUFFIX)
+    ):
+        return (
+            "interaction trace artifacts are Playwright trace ZIP files — name "
+            f"artifact_path with a {TRACE_SUFFIX} extension (e.g. {TRACE_EXAMPLE}); "
+            f"got {artifact_rel!r}"
+        )
+    return ""

package/mcp/evidence/server.py

@@ -49,7 +49,10 @@ def _tool_schema() -> dict[str, Any]:
                         'v1: "screenshot" | "a11y tree" | "interaction trace". '
                         "A screenshot capture also writes a sibling "
                         ".probe.json page-probe artifact (facts, not a "
-                        "judgment) when the adapter can probe."
+                        "judgment) when the adapter can probe. An a11y tree "
+                        "is a JSON envelope {format, tree} whose tree is "
+                        "Playwright aria_snapshot text; an interaction trace "
+                        "is a Playwright trace ZIP (name it .zip)."
                     ),
                     "enum": ["screenshot", "a11y tree", "interaction trace"],
                 },
@@ -79,6 +82,17 @@ def _tool_schema() -> dict[str, Any]:
                         "'evidence/'). Provider only writes this file."
                     ),
                 },
+                "run_root": {
+                    "type": "string",
+                    "description": (
+                        "Optional absolute run root (.scratch/<run>/) for THIS "
+                        "call only, overriding DESIGN_PLAYBOOK_RUN_ROOT / "
+                        "process cwd. Use it when the MCP process was started "
+                        "without the env var and cannot be restarted; the "
+                        "directory must exist and carry a run marker "
+                        "(plan.md or point-back.md)."
+                    ),
+                },
                 "overwrite": {
                     "type": "boolean",
                     "description": (
@@ -110,6 +124,15 @@ def _tool_schema() -> dict[str, Any]:
 
 
 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()
     serve_stdio(
         SERVER_NAME,
         SERVER_VERSION,

package/mcp/preview/control.css

@@ -113,6 +113,8 @@ body.dpb-shell { overflow: hidden; height: 100vh; }
 }
 #dpb-root kbd, .dpb-toasts kbd {
   display: inline-flex; align-items: center; justify-content: center;
+  /* OBS-1: a shortcut badge is a fixed glyph run — never squeeze or fold it. */
+  flex: 0 0 auto; white-space: nowrap;
   font: 600 9px/1.2 ui-monospace, "JetBrains Mono", Consolas, monospace;
   padding: 1px 5px; border-radius: 4px;
   background: var(--dpb-surface); color: var(--dpb-soft);
@@ -548,10 +550,13 @@ body.dpb-tool-ruler .dpb-draw-layer { pointer-events: auto; cursor: crosshair; }
   border-color: var(--dpb-danger) !important;
   box-shadow: 0 0 0 3px var(--dpb-ring-danger) !important;
 }
-.dpb-foot-actions { display: flex; justify-content: flex-end; gap: 10px; }
+.dpb-foot-actions { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: 10px; }
 .dpb-btn {
   appearance: none; cursor: pointer; height: 32px; padding: 0 14px; border-radius: 8px;
   display: inline-flex; align-items: center; justify-content: center; gap: 6px;
+  /* OBS-1: a fixed-height pill must keep one text line; long locale labels
+     (EN "Approve (2 notes)") wrap onto a second row of the actions instead. */
+  flex: 0 0 auto; white-space: nowrap;
   border: 1px solid var(--dpb-line-strong); background: transparent; color: var(--dpb-soft);
   font: 600 12px/1 inherit; transition: all var(--dpb-duration-spring) var(--dpb-ease-spring);
 }

package/mcp/preview/server.py

@@ -155,6 +155,15 @@ def handle_preview_prototype(args: dict[str, Any]) -> dict[str, Any]:
 
 
 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()
     if len(sys.argv) > 1 and sys.argv[1] == "--self-check":
         self_check_floor()
     else:

package/mcp/run_console/snapshot_builder.py

@@ -119,7 +119,8 @@ _RETAINED_FIELDS = (
 # Capture-contract quality findings (G6.capture_*) do not unbind evidence
 # at this boundary.
 _UNBINDABLE_RULES = frozenset(
-    {"G6.artifact_missing", "G6.escape", "G6.no_binding", "G6.unknown_criterion"}
+    {"G6.artifact_missing", "G6.escape", "G6.no_binding", "G6.unknown_criterion",
+     "G6.binding_conflict"}
 )
 _DEGRADING_RULES = frozenset({"G6.artifact_missing", "G6.escape"})
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "design-playbook",
-  "version": "0.25.0",
-  "description": "Design I/O for coding agents: evidence-forced UI acceptance — every criterion bound to a captured artifact, findings pointing back to declarations, verdicts owned by the evaluator, not the implementer. Design-baseline covers existing-product UI work. Use for product UI - console, dashboard, agent-ops, CJK-first apps.",
+  "version": "0.25.1",
+  "description": "Evidence-backed UI delivery for coding agents working on existing Web products: declared criteria, criterion-bound artifacts, findings linked to declarations, and repair guidance. Evaluator review does not replace human semantic approval.",
   "keywords": [
     "pi-package",
     "dsh-plugin",

package/scripts/adapter_matrix.py

@@ -10,8 +10,8 @@ ADR-0042 amendment): the tier encodes the capability class, each renderer
 documents its own output surface, and the published counts are derived
 from this matrix by the validate.py gate.
 
-Authority: docs/specs/2026-08-28-multi-platform-adapter.md §1 and
-           docs/adr/0042-multi-platform-adapter-generator.md.
+Decision authority: docs/adr/0042-multi-platform-adapter-generator.md.
+This module owns the current adapter inventory.
 """
 from __future__ import annotations
 

package/scripts/audit_preferences.py

@@ -597,4 +597,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()
     raise SystemExit(main())