design-playbook 0.20.2 → 0.21.0

package/codex/AGENTS.md

@@ -71,12 +71,14 @@ adapter spawns it via `--app=`); `observe*` needs Playwright + Chromium.
 
 Native desktop order: `ux-spec` → `native-craft` → `ui-picker` → `fill` → `craft-guard` → `ui-evaluator`.
 
-Conditional entry `reference-intake?` (screenshot/URL/design/product analogy, ADR-0011) runs **before** `ux-spec?` when reference materials are present — fixed orchestrator order, not reorderable. Run `native-craft` only for an explicit native-desktop/native-feel target. Web and mobile Web skip `native-craft`; if the platform is unclear, ask before choosing the order. The orchestrator owns the decision gate, render-surface seam handoff, and fail-closed behavior.
+Conditional entry `design-baseline?` (ADR-0012) runs before `reference-intake?` when the router returns `requires_baseline`. Existing-product Fill requires a valid existing baseline, an accepted generated baseline, or an explicit user waiver.
 
-Conditional entry `design-baseline?` (ADR-0012) runs before `reference-intake?` for UI builds/fixes in repositories with meaningful existing first-party UI. Existing-product Fill requires a valid existing baseline, an accepted generated baseline, or an explicit user waiver.
+Conditional entry `reference-intake?` (screenshot/URL/design/product analogy, ADR-0011) runs **before** `ux-spec?` when the router returns `requires_reference_contract` — fixed orchestrator order, not reorderable. Run `native-craft` only for an explicit native-desktop/native-feel target. Web and mobile Web skip `native-craft`; if the platform is unclear, ask before choosing the order. The orchestrator owns the decision gate, render-surface seam handoff, and fail-closed behavior.
 
 Mirror the orchestrator's skip narration (SKILL.md Steps preamble): when a step is skipped, output one line — step name + reason + how to enable, with the gate label when one applies, e.g. `-> preview*: adapter absent, skipped (G5 not triggered; enable via packages/design-playbook/mcp/preview/ or host MCP)`.
 
+Audit preferences (ADR-0033) apply identically on Codex. Follow `skills/design-playbook/SKILL.md` § *Audit preferences* as sole authority; this bridge adds no host-specific preference rules.
+
 ## Compose
 
 - Style DB → ui-ux-pro-max

package/commands/doctor.md

@@ -10,6 +10,7 @@ One packaged diagnosis entry for install/runtime capability.
 python <plugin>/scripts/doctor.py
 python <plugin>/scripts/doctor.py --json
 python <plugin>/scripts/doctor.py --run-root .scratch/<run>
+python <plugin>/scripts/doctor.py --repo-root <target-repo>
 ```
 
-Reports `ok` / `degraded` / `broken`. Failed checks include a concrete repair. Optional adapters (Playwright, run-root env) degrade rather than hard-fail the install.
+Reports `ok` / `degraded` / `broken`. Failed checks include a concrete repair. Optional adapters (Playwright, run-root env) degrade rather than hard-fail the install. Audit-preference state shows effective stage values, sources, asked status, and corrupt layers for target repository.

package/commands/ux-spec.md

@@ -2,7 +2,7 @@
 description: Six-layer spec.md via the S0-S6 shaping session (question/assumption/confirmation batches + session artifacts); stop before UI shell/code
 ---
 
-Run skill **ux-spec** only. Emit complete `spec.md`. Do not pick templates or write UI.
+Run the ux-spec protocol only. A same-named command in this plugin shadows the `ux-spec` skill in the Skill tool registry, so the Skill tool injects this text instead of the protocol. Locate this plugin's install root (the `--plugin-dir` path, or under `~/.claude/plugins/` for marketplace installs), read `skills/ux-spec/SKILL.md`, and follow its S0-S6 protocol. Emit complete `spec.md`. Do not pick templates or write UI.
 
 Request:
 $ARGUMENTS

package/examples/reference-intake/product-analogy/manifest.json

@@ -9,6 +9,9 @@
       "kind": "product_analogy",
       "locator": "Linear (product analogy; no asset)",
       "sha256": null,
+      "storage": "symbolic",
+      "acquired_via": "analogy",
+      "captured_at": "2026-07-22T10:10:00+08:00",
       "note": "taste anchor only"
     }
   ]

package/examples/reference-intake/screenshot/manifest.json

@@ -9,6 +9,10 @@
       "kind": "screenshot",
       "locator": "assets/ops-alert-list.png",
       "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+      "media_type": "image/png",
+      "storage": "copied",
+      "acquired_via": "local-file",
+      "captured_at": "2026-07-22T10:00:00+08:00",
       "note": "fixture placeholder hash; real runs must hash the file"
     }
   ]

package/examples/reference-intake/url/manifest.json

@@ -9,6 +9,9 @@
       "kind": "url",
       "locator": "https://example.com/docs/settings/notifications",
       "sha256": null,
+      "storage": "remote",
+      "acquired_via": "url",
+      "captured_at": "2026-07-22T10:05:00+08:00",
       "note": "example.com placeholder for fixture shape only"
     }
   ]

package/mcp/evidence/capture_runtime.py

@@ -5,17 +5,24 @@ Never writes manifest.jsonl; never accepts criterion refs (orchestrator binds).
 Returns relative ``artifact`` plus absolute ``written_path`` so RUN_ROOT/cwd
 misconfig is visible to the orchestrator.
 """
+
 from __future__ import annotations
 
 import json
 import os
-import sys
 from pathlib import Path
 from typing import Any, Protocol
 
 from design_playbook.mcp.evidence import containment
 from design_playbook.mcp.evidence.capture_contract import parse_capture_contract
-from design_playbook.mcp.preview.util import _log
+from design_playbook.mcp.evidence.disclosure import (
+    LAYOUT_PROBE_JS,
+    VIEWPORTS,
+    ViewportMetrics,
+    metric_payload,
+    probe_layout,
+)
+from design_playbook.mcp.util import log as _log
 
 CAPTURE_TYPES = frozenset({"screenshot", "a11y tree", "interaction trace"})
 ALLOWED_ARGUMENTS = frozenset(
@@ -50,6 +57,22 @@ class BrowserAdapter(Protocol):
         """Write one artifact and return the observed page state."""
 
 
+class ProbeBrowserAdapter(Protocol):
+    """Optional seam for capturing and probing one browser page."""
+
+    def capture_and_probe(
+        self,
+        *,
+        url: str,
+        capture_type: str,
+        actions: list[dict[str, Any]],
+        out_path: Path,
+        viewport: dict[str, Any],
+        freeze: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Capture an artifact and evaluate the layout probe before teardown."""
+
+
 def _failed(
     artifact: str,
     error: str,
@@ -188,16 +211,11 @@ def _reason_message(reason: str) -> str:
 # payload stays compatible; resolution_failure is the one new surface (the
 # old inline resolver propagated OSError uncaught).
 _REASON_MESSAGES = {
-    containment.REASON_ABSOLUTE_PATH:
-        "artifact_path must be relative to the configured run root",
-    containment.REASON_DOTDOT_SEGMENT:
-        "artifact_path must not contain '..' segments",
-    containment.REASON_RESOLUTION_FAILURE:
-        "artifact_path could not be resolved under the evidence/ subtree",
-    containment.REASON_CANONICAL_ESCAPE:
-        "artifact_path must stay under the evidence/ subtree",
-    containment.REASON_SYMLINK_ESCAPE:
-        "artifact_path symlink escapes the evidence/ subtree",
+    containment.REASON_ABSOLUTE_PATH: "artifact_path must be relative to the configured run root",
+    containment.REASON_DOTDOT_SEGMENT: "artifact_path must not contain '..' segments",
+    containment.REASON_RESOLUTION_FAILURE: "artifact_path could not be resolved under the evidence/ subtree",
+    containment.REASON_CANONICAL_ESCAPE: "artifact_path must stay under the evidence/ subtree",
+    containment.REASON_SYMLINK_ESCAPE: "artifact_path symlink escapes the evidence/ subtree",
 }
 
 
@@ -276,8 +294,7 @@ def _action_select_option(page: Any, action: dict, index: int, do: str) -> None:
     value = action.get("value")
     label = action.get("label")
     if value is None and label is None:
-        raise ValueError(
-            f"actions[{index}].value or label required for select_option")
+        raise ValueError(f"actions[{index}].value or label required for select_option")
     if value is not None:
         page.select_option(selector, value=value, timeout=10_000)
     else:
@@ -339,6 +356,7 @@ def _read_observed_state(page: Any) -> str:
         _log(f"observed_state probe failed: {exc}")
     return "unknown"
 
+
 def _write_screenshot(page: Any, path: Path) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     page.screenshot(path=str(path), full_page=True)
@@ -389,7 +407,7 @@ class PlaywrightBrowserAdapter:
 
         self._sync_playwright = sync_playwright
 
-    def capture(
+    def _capture_page(
         self,
         *,
         url: str,
@@ -398,7 +416,15 @@ class PlaywrightBrowserAdapter:
         out_path: Path,
         viewport: dict[str, Any],
         freeze: dict[str, Any],
-    ) -> str:
+        probe: bool,
+    ) -> tuple[str, ViewportMetrics | None]:
+        """Single Playwright capture path shared by the two adapter seams.
+
+        ``probe=False`` stops after the observed state (the plain
+        :class:`BrowserAdapter` contract); ``probe=True`` additionally
+        evaluates the layout probe on the same page before teardown so the
+        screenshot and its metrics share one browser pass.
+        """
         with self._sync_playwright() as playwright:
             browser = playwright.chromium.launch(headless=True)
             try:
@@ -411,6 +437,8 @@ class PlaywrightBrowserAdapter:
                     color_scheme=viewport["colorScheme"],
                 )
                 page = context.new_page()
+                if viewport.get("media"):
+                    page.emulate_media(media=viewport["media"])
                 wait_until = (
                     "networkidle" if freeze.get("networkIdle") else "domcontentloaded"
                 )
@@ -428,12 +456,62 @@ class PlaywrightBrowserAdapter:
                     elif capture_type == "a11y tree":
                         _write_a11y_tree(page, out_path)
 
-                return _read_observed_state(page)
+                observed = _read_observed_state(page)
+                if not probe:
+                    return observed, None
+                raw = page.evaluate(LAYOUT_PROBE_JS)
+                metrics = probe_layout(lambda _js: raw)
+                return observed, metrics
             finally:
                 browser.close()
 
+    def capture(
+        self,
+        *,
+        url: str,
+        capture_type: str,
+        actions: list[dict[str, Any]],
+        out_path: Path,
+        viewport: dict[str, Any],
+        freeze: dict[str, Any],
+    ) -> str:
+        observed, _metrics = self._capture_page(
+            url=url,
+            capture_type=capture_type,
+            actions=actions,
+            out_path=out_path,
+            viewport=viewport,
+            freeze=freeze,
+            probe=False,
+        )
+        return observed
 
-def _validate_runtime_object(args: dict[str, Any]) -> tuple[str, str, str, list[dict[str, Any]]]:
+    def capture_and_probe(
+        self,
+        *,
+        url: str,
+        capture_type: str,
+        actions: list[dict[str, Any]],
+        out_path: Path,
+        viewport: dict[str, Any],
+        freeze: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Capture and probe the same page before closing its browser."""
+        observed, metrics = self._capture_page(
+            url=url,
+            capture_type=capture_type,
+            actions=actions,
+            out_path=out_path,
+            viewport=viewport,
+            freeze=freeze,
+            probe=True,
+        )
+        return {"observed_state": observed, "metrics": metrics}
+
+
+def _validate_runtime_object(
+    args: dict[str, Any],
+) -> tuple[str, str, str, list[dict[str, Any]]]:
     """Validate Runtime Object fields and return (url, cap_type, state, actions).
 
     Owns the field-level validation that execute_capture_plan previously
@@ -449,7 +527,7 @@ def _validate_runtime_object(args: dict[str, Any]) -> tuple[str, str, str, list[
         raise ValueError("url is required")
     if not isinstance(cap_type, str) or cap_type not in CAPTURE_TYPES:
         raise ValueError(
-            f'type must be one of {sorted(CAPTURE_TYPES)}; got {cap_type!r}'
+            f"type must be one of {sorted(CAPTURE_TYPES)}; got {cap_type!r}"
         )
     if not isinstance(state, str) or not state.strip():
         raise ValueError("state is required")
@@ -509,8 +587,7 @@ def execute_capture_plan(
     if out_path.exists() and not overwrite:
         return _failed(
             rel,
-            f"artifact already exists: {out_path} "
-            "(pass overwrite=true to replace)",
+            f"artifact already exists: {out_path} (pass overwrite=true to replace)",
             abs_written,
             request=request,
         )
@@ -549,3 +626,128 @@ def execute_capture_plan(
         )
 
     return _captured(rel, observed, abs_written, request)
+
+
+# --------------------------------------------------------------------------- #
+# Stage 9 delivery matrix: five-viewport capture + fold/overflow metrics       #
+# --------------------------------------------------------------------------- #
+
+
+def matrix_viewport(name: str) -> dict[str, Any]:
+    """Map a standard delivery viewport name to a capture-contract viewport.
+
+    ``sw``/``innerH`` become the contract ``width``/``height``; device pixels
+    stay at 1.0 with the Light color scheme so the matrix is reproducible.
+    The ``print`` viewport additionally carries ``media: "print"`` so the
+    adapter emulates print media (page breaks, print stylesheets) rather than
+    just resizing the window. Unknown names raise ValueError so a caller cannot
+    silently capture a non-standard viewport into the disclosure matrix.
+    """
+    ref = VIEWPORTS.get(name)
+    if ref is None:
+        raise ValueError(
+            f"unknown delivery viewport {name!r}; expected one of {sorted(VIEWPORTS)}"
+        )
+    viewport = {
+        "width": ref["sw"],
+        "height": ref["innerH"],
+        "devicePixelRatio": 1.0,
+        "colorScheme": "light",
+    }
+    if ref.get("kind") == "print":
+        viewport["media"] = "print"
+    return viewport
+
+
+def capture_delivery_matrix(
+    *,
+    url: str,
+    out_dir: Path | None = None,
+    freeze: dict[str, Any] | None = None,
+    browser_adapter: BrowserAdapter | None = None,
+) -> dict[str, dict[str, Any]]:
+    """Drive the five standard delivery viewports and return their metrics.
+
+    For each of ``VIEWPORTS``, captures one full-page screenshot under
+    ``out_dir`` (``viewport-<name>.png``) and reads the layout probe. The
+    returned dict maps viewport name -> ``{metrics, screenshot}`` so a caller
+    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``.
+    """
+    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]] = {}
+    for name in VIEWPORTS:
+        viewport = matrix_viewport(name)
+        out_path = out_dir / f"viewport-{name}.png"
+        try:
+            capture_and_probe = getattr(browser_adapter, "capture_and_probe", None)
+            if callable(capture_and_probe):
+                captured = capture_and_probe(
+                    url=url,
+                    capture_type="screenshot",
+                    actions=[],
+                    out_path=out_path,
+                    viewport=viewport,
+                    freeze=freeze,
+                )
+                measured = captured.get("metrics") if isinstance(captured, dict) else None
+                if not isinstance(measured, ViewportMetrics):
+                    raise TypeError("capture_and_probe returned no ViewportMetrics")
+                metrics = metric_payload(measured)
+            else:
+                browser_adapter.capture(
+                    url=url,
+                    capture_type="screenshot",
+                    actions=[],
+                    out_path=out_path,
+                    viewport=viewport,
+                    freeze=freeze,
+                )
+                metrics = _unmeasured_metric_payload(name)
+            results[name] = {"metrics": metrics, "screenshot": str(out_path)}
+        except Exception as exc:  # noqa: BLE001 — preserve blocked evidence
+            _log(f"matrix capture/probe failed for {name}: {exc}")
+            results[name] = {
+                "metrics": metric_payload(
+                    ViewportMetrics(
+                        sw=VIEWPORTS[name]["sw"],
+                        innerH=VIEWPORTS[name]["innerH"],
+                        hOverflow=0,
+                        inFold=False,
+                        measurement_status="blocked",
+                        measurement_error=str(exc),
+                    )
+                ),
+                "screenshot": str(out_path),
+                "result": "blocked",
+                "error": str(exc),
+            }
+    return results
+
+
+def _unmeasured_metric_payload(name: str) -> dict[str, Any]:
+    """Return reference dimensions without claiming a layout measurement."""
+    ref = VIEWPORTS[name]
+    return metric_payload(
+        ViewportMetrics(
+            sw=ref["sw"],
+            innerH=ref["innerH"],
+            hOverflow=0,
+            inFold=False,
+            measurement_status="unmeasured",
+        )
+    )

package/mcp/evidence/containment.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Single Evidence artifact containment authority (ADR-0026).
+"""Single Evidence artifact containment authority (ADR-0026, ADR-0039).
 
 This is the one deep module that resolves an artifact path under
 ``<run_root>/evidence/`` and rejects every escape class at resolution time.
@@ -16,6 +16,13 @@ without re-checking containment. Collapsing both callers into one mode-driven
 helper was rejected because it would hide their different existence timing
 and error contracts (ADR-0026).
 
+ADR-0039 extends the same invariant to arbitrary roots: ``read_under``
+exposes the canonical resolution for one existing regular file under any
+directory, and the Run Console's source reads (run root, package root)
+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.
+
 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
@@ -73,22 +80,30 @@ class ContainmentResult:
         return self.reason == ""
 
 
-def _resolve(
-        artifact_path: str,
-        run_root: Path,
+def _resolve_candidate(
+        candidate_root: Path,
+        relpath: str,
+        boundary_root: Path,
         *,
         require_existing_file: bool) -> ContainmentResult:
-    """Canonical containment resolution shared by write_target and read_artifact.
+    """Canonical containment resolution shared by every operation here.
+
+    ``relpath`` joins ``candidate_root`` to form the candidate; the resolved
+    candidate (and its realpath) must stay under ``boundary_root``. The
+    evidence operations pass the run root as the candidate root and the
+    evidence subtree as the boundary (their paths are run-root-relative,
+    including the ``evidence/`` prefix); ``read_under`` passes the same root
+    for both.
 
     Rejects, in order: native/POSIX/Windows absolute paths; any ``..``
     segment (defence in depth before resolution); resolution failures
     (OSError during resolve); canonical escapes (resolved candidate leaves
-    the evidence/ subtree); observed symlink escapes (realpath leaves the
-    evidence/ subtree - Path.resolve and os.path.realpath can disagree on
+    the boundary root); observed symlink escapes (realpath leaves the
+    boundary root - Path.resolve and os.path.realpath can disagree on
     symlink chains across platforms). When ``require_existing_file`` is set,
     a candidate that is not an existing regular file is rejected last.
     """
-    requested = Path(artifact_path)
+    requested = Path(relpath)
 
     # 1. Absolute path rejection: native, POSIX, and Windows forms. Checking
     #    all three means a Windows drive path is rejected on POSIX and a POSIX
@@ -96,8 +111,8 @@ def _resolve(
     #    Path flavour.
     if (
         requested.is_absolute()
-        or PureWindowsPath(artifact_path).is_absolute()
-        or PurePosixPath(artifact_path).is_absolute()
+        or PureWindowsPath(relpath).is_absolute()
+        or PurePosixPath(relpath).is_absolute()
     ):
         return ContainmentResult(None, REASON_ABSOLUTE_PATH)
 
@@ -106,36 +121,35 @@ def _resolve(
     if any(part == ".." for part in requested.parts):
         return ContainmentResult(None, REASON_DOTDOT_SEGMENT)
 
-    # 3. Resolution. Both the evidence root and the candidate are resolved
+    # 3. Resolution. Both the boundary root and the candidate are resolved
     #    here; an OSError (e.g. a pathological symlink chain on a platform
     #    whose resolver raises) is caught and surfaced as a resolution
     #    failure rather than propagated.
     try:
-        evidence_root = (run_root / EVIDENCE_SUBDIR).resolve(strict=False)
-        candidate = (run_root / requested).resolve(strict=False)
+        boundary = boundary_root.resolve(strict=False)
+        candidate = (candidate_root / requested).resolve(strict=False)
     except OSError:
         return ContainmentResult(None, REASON_RESOLUTION_FAILURE)
 
-    # 4. Canonical escape: the resolved candidate must stay under the evidence
-    #    root. Catches ``spec.md`` and ``skills/x`` (siblings of evidence/).
+    # 4. Canonical escape: the resolved candidate must stay under the
+    #    boundary root. For the evidence operations this catches ``spec.md``
+    #    and ``skills/x`` (siblings of evidence/).
     try:
-        candidate.relative_to(evidence_root)
+        candidate.relative_to(boundary)
     except ValueError:
         return ContainmentResult(None, REASON_CANONICAL_ESCAPE)
 
     # 5. Symlink escape (defence in depth): realpath must also stay under the
-    #    evidence root. Path.resolve and os.path.realpath can disagree on
-    #    symlink chains across platforms, so a symlink under evidence/ that
-    #    resolves outside must be rejected even when step 4 passed.
+    #    boundary root. Path.resolve and os.path.realpath can disagree on
+    #    symlink chains across platforms, so a symlink under the boundary
+    #    that resolves outside must be rejected even when step 4 passed.
     try:
-        Path(os.path.realpath(candidate)).relative_to(
-            os.path.realpath(evidence_root)
-        )
+        Path(os.path.realpath(candidate)).relative_to(os.path.realpath(boundary))
     except ValueError:
         return ContainmentResult(None, REASON_SYMLINK_ESCAPE)
 
-    # 6. Read side: require an existing regular file. The write side permits a
-    #    nonexistent suffix and stops here (the Provider's manifest-refusal
+    # 6. Read side: require an existing regular file. The write side permits
+    #    a nonexistent suffix and stops here (the Provider's manifest-refusal
     #    and overwrite checks are separate policy, not containment).
     if require_existing_file and not candidate.is_file():
         return ContainmentResult(None, REASON_NOT_REGULAR_FILE)
@@ -143,6 +157,33 @@ def _resolve(
     return ContainmentResult(candidate, "")
 
 
+def _resolve(
+        artifact_path: str,
+        run_root: Path,
+        *,
+        require_existing_file: bool) -> ContainmentResult:
+    """Resolve an evidence artifact path (run-root-relative) under evidence/."""
+    return _resolve_candidate(
+        run_root,
+        artifact_path,
+        run_root / EVIDENCE_SUBDIR,
+        require_existing_file=require_existing_file,
+    )
+
+
+def read_under(root: Path, relpath: str) -> ContainmentResult:
+    """Resolve one existing regular file under an arbitrary root (ADR-0039).
+
+    The same escape classes as the evidence operations, for callers whose
+    authority root is not the evidence subtree (Run Console source reads
+    under the selected run root or the package root). ``relpath`` is
+    root-relative. Resolution-only, same TOCTOU limit as above.
+    """
+    return _resolve_candidate(
+        root, relpath, root, require_existing_file=True
+    )
+
+
 def write_target(artifact_path: str, run_root: Path) -> ContainmentResult:
     """Resolve a write target under ``<run_root>/evidence/``.