design-playbook 0.8.0 → 0.9.1

package/mcp/evidence/server.py

@@ -142,9 +142,34 @@ def _captured(
     }
 
 
+_RUN_MARKERS = ("plan.md", "point-back.md")
+_warned_run_root = False
+
+
 def _run_root() -> Path:
     configured = os.environ.get(RUN_ROOT_ENV)
-    return Path(configured).resolve() if configured else Path.cwd().resolve()
+    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.
+        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
+        ):
+            _warned_run_root = True
+            _log(
+                "WARNING: DESIGN_PLAYBOOK_RUN_ROOT is unset or '.' "
+                f"(cwd-relative) and {root} has no run marker "
+                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."
+            )
+        return root
+    return Path(configured).resolve()
 
 
 def _resolve_artifact_path(artifact_path: str) -> Path:

package/mcp/evidence/test_server_stdio.py

@@ -18,6 +18,7 @@ whose names did not match any keyword. See review item M3.
 from __future__ import annotations
 
 import json
+import os
 import subprocess
 import sys
 import tempfile
@@ -50,6 +51,7 @@ def _run_stdio(
     *,
     cwd: Path | None = None,
     no_site: bool = False,
+    env: dict[str, str] | None = None,
 ) -> subprocess.CompletedProcess[str]:
     wire_input = "".join(
         json.dumps(request, ensure_ascii=False) + "\n" for request in requests
@@ -67,6 +69,7 @@ def _run_stdio(
         timeout=timeout,
         check=False,
         cwd=cwd,
+        env=env,
     )
 
 
@@ -204,6 +207,57 @@ class EvidencePurePathTests(unittest.TestCase):
                     self.assertEqual(payload["observed_state"], "unknown")
             self.assertFalse(outside.exists())
 
+    def test_run_root_warning_only_without_run_marker_and_once(self) -> None:
+        """Default RUN_ROOT ('.'/unset) must not warn when cwd is a run dir.
+
+        Shipped defaults (root .mcp.json RUN_ROOT="." / external installs
+        unset) are correct usage when cwd is the run dir — warning there is a
+        100% false positive. Warn only when cwd lacks a run marker
+        (plan.md / point-back.md), and only once per process.
+        """
+        def _call(request_id: int) -> dict:
+            return {
+                "jsonrpc": "2.0",
+                "id": request_id,
+                "method": "tools/call",
+                "params": {
+                    "name": "execute_capture_plan",
+                    "arguments": {
+                        "url": "about:blank",
+                        "type": "screenshot",
+                        "state": "ok",
+                        "actions": [],
+                        # Rejected before Playwright import, but after
+                        # _run_root() — cheap way to reach the warning path.
+                        "artifact_path": "spec.md",
+                    },
+                },
+            }
+
+        requests = [
+            {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}},
+            _call(2),
+            _call(3),
+        ]
+        env = {k: v for k, v in os.environ.items() if k != "DESIGN_PLAYBOOK_RUN_ROOT"}
+
+        with tempfile.TemporaryDirectory() as tmp:
+            bare = Path(tmp)
+            completed = _run_stdio(requests, timeout=15, cwd=bare, env=env)
+            self.assertEqual(completed.returncode, 0, completed.stderr)
+            self.assertEqual(
+                completed.stderr.count("DESIGN_PLAYBOOK_RUN_ROOT is unset or '.'"),
+                1,
+                completed.stderr,
+            )
+
+        with tempfile.TemporaryDirectory() as tmp:
+            run_dir = Path(tmp)
+            (run_dir / "plan.md").write_text("# plan", encoding="utf-8")
+            completed = _run_stdio(requests, timeout=15, cwd=run_dir, env=env)
+            self.assertEqual(completed.returncode, 0, completed.stderr)
+            self.assertNotIn("DESIGN_PLAYBOOK_RUN_ROOT is unset", completed.stderr)
+
     def test_provider_rejects_non_evidence_subtree_paths(self) -> None:
         """G6 containment: artifact_path must already live under evidence/."""
         with tempfile.TemporaryDirectory() as tmp:

package/mcp/preview/browser.py

@@ -12,6 +12,7 @@ import html
 import json
 import os
 import re
+import secrets
 import shutil
 import subprocess
 import sys
@@ -23,14 +24,68 @@ from pathlib import Path
 from typing import Any
 from urllib.parse import parse_qs
 
-from confirm import (
-    _DecisionSession,
-    _generate_decision_token,
-    prototype_html_digest,
-)
 from control import _build_control
 from i18n import lang, t
-from util import _log
+from util import _log, prototype_html_digest
+
+
+def _generate_decision_token() -> str:
+    """One-time URL-safe decision token (G5 trust boundary).
+
+    Proves a POST to /decide originated from the trusted parent control bar
+    (which renders the hidden field) rather than from prototype scripts running
+    inside the sandboxed iframe, which cannot read the parent DOM. Bound to a
+    single preview round via :class:`_DecisionSession`.
+    """
+    return secrets.token_urlsafe(32)
+
+
+class _DecisionSession:
+    """First-decision-wins token lock for a single preview round (G5).
+
+    ``validate`` returns ``True`` only for the first POST whose token matches
+    (constant-time) AND whose round matches. Every other POST — missing token,
+    reused token, mismatched round, or wrong token — is rejected so the caller
+    can fail the decision closed. The session grants at most one valid decision.
+    """
+
+    def __init__(self, round_n: int, token: str) -> None:
+        self.round_n = round_n
+        self._token = token
+        self._locked = False
+        self._lock = threading.Lock()
+        self.last_rejection: str = ""
+
+    @property
+    def locked(self) -> bool:
+        return self._locked
+
+    def validate(self, posted_round: int, posted_token: str | None) -> bool:
+        # LOW-1 (secure-ship-0.4.4): the check-then-set on ``_locked`` must
+        # be atomic. ThreadingHTTPServer handles each POST on its own
+        # thread, so two concurrent valid-token POSTs could both pass the
+        # ``if self._locked`` check and each consume the session. Hold the
+        # lock for the whole decision so first-decision-wins holds under
+        # real concurrency; the lock is uncontended in the single-POST
+        # happy path, so the cost is a no-op acquire/release.
+        with self._lock:
+            if not posted_token:
+                self.last_rejection = "missing"
+                return False
+            if posted_round != self.round_n:
+                self.last_rejection = "round_mismatch"
+                return False
+            if self._locked:
+                # First valid decision already consumed the session; every
+                # later POST (even with the correct token) is a replay.
+                self.last_rejection = "reuse"
+                return False
+            if not secrets.compare_digest(posted_token, self._token):
+                self.last_rejection = "invalid_token"
+                return False
+            self._locked = True
+            self.last_rejection = ""
+            return True
 
 
 def _screen_size() -> tuple[int, int]:

package/mcp/preview/server.py

@@ -24,9 +24,12 @@ sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 from _transport import ToolError, serve_stdio  # noqa: E402
 
 import browser
-from confirm import _self_check_floor
 from i18n import default_options
-from transaction import PreviewTransactionError, run_preview_transaction
+from transaction import (
+    PreviewTransactionError,
+    _self_check_floor,
+    run_preview_transaction,
+)
 
 TOOL_NAME = "preview_prototype"
 

package/mcp/preview/test_browser_control.py

@@ -33,11 +33,11 @@ from urllib.parse import urlencode
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 import browser  # noqa: E402
 import control as preview_control  # noqa: E402
-from confirm import (  # noqa: E402
+from browser import (  # noqa: E402
     _DecisionSession,
     _generate_decision_token,
-    prototype_html_digest,
 )
+from util import prototype_html_digest  # noqa: E402
 
 
 # --------------------------------------------------------------------------- #

package/mcp/preview/transaction.py

@@ -17,20 +17,97 @@ from contextlib import contextmanager
 from pathlib import Path
 from typing import Any, Callable, Iterator
 
-from confirm import (
-    _check_feedback_floor,
-    _ensure_prototype,
-    _preview_dir_for,
-    prototype_html_digest,
-)
 from control import _format_feedback
 from i18n import CONFIRM_LABELS
-from util import _now_iso
+from util import _now_iso, prototype_html_digest
 
 BrowserCollector = Callable[[Path, str, list[str], int], dict[str, Any]]
 ENTRY_SCHEMA_VERSION = 1
 
 
+def _preview_dir_for(path: Path | None) -> Path:
+    if path is not None:
+        return path.parent
+    scratch = Path.cwd() / ".scratch" / "preview-adapter" / "preview"
+    scratch.mkdir(parents=True, exist_ok=True)
+    return scratch
+
+
+def _ensure_prototype(path_arg: str | None, html: str | None, round_n: int,
+                      preview_dir: Path) -> Path:
+    if path_arg:
+        p = Path(path_arg)
+        if not p.is_file():
+            raise ValueError(f"prototype path does not exist: {path_arg}")
+        return p
+    if not html:
+        raise ValueError("path or html is required")
+    preview_dir.mkdir(parents=True, exist_ok=True)
+    target = preview_dir / f"round-{round_n}.html"
+    target.write_text(html, encoding="utf-8")
+    return target
+
+
+def _check_feedback_floor(feedback: str,
+                          anchors: list[dict[str, Any]]) -> tuple[bool, str]:
+    """ADR-0008 preview feedback floor (structural, machine-checkable).
+
+    Passes when:
+    - (non-empty feedback OR >=1 anchor present) as trigger, AND
+    - every present anchor (if any) has non-empty selector AND non-empty comment.
+
+    Deliberately structural, no minimum length: short CJK feedback like
+    "太挤了" is substantive; semantic junk (ADR-0008's "安师大" case) is
+    ui-evaluator's job (G6), not the floor's.
+    Returns (floor_pass, floor_failure_reason).
+    """
+    feedback = (feedback or "").strip()
+    trigger = bool(feedback) or bool(anchors)
+    if not trigger:
+        return False, "confirm with no substantive feedback: empty feedback and no anchor"
+    if anchors:
+        for a in anchors:
+            if not isinstance(a, dict):
+                return False, "anchor is not an object"
+            sel = str(a.get("selector") or "").strip()
+            note = str(a.get("comment") or "").strip()
+            if not sel or not note:
+                return False, (
+                    "anchor missing non-empty selector and comment: "
+                    f"selector={sel!r} comment={note!r}")
+    return True, ""
+
+
+def _self_check_floor() -> None:
+    """ADR-0008 floor branch logic self-check (ponytail: one runnable check)."""
+    cases = [
+        ("empty + no anchors", "", [], False),
+        ("whitespace-only feedback", "   \n  ", [], False),
+        ("short feedback passes (structural floor)", "ok", [], True),
+        ("short CJK feedback passes ('太挤了' is substantive)", "太挤了", [], True),
+        ("'安师大' passes floor; semantic junk is G6's job (ADR-0008)", "安师大", [], True),
+        ("longer feedback passes", "fix it", [], True),
+        ("anchor with comment", "", [{"selector": "h2", "comment": "x"}], True),
+        ("anchor no comment (0015 garbage)", "",
+         [{"selector": "h2", "comment": ""}], False),
+        ("anchor empty selector", "",
+         [{"selector": "", "comment": "x"}], False),
+        ("non-dict anchor", "", ["not-a-dict"], False),
+        ("feedback + incomplete anchor still fails", "ok",
+         [{"selector": "h2", "comment": ""}], False),
+        ("two anchors one incomplete fails", "",
+         [{"selector": "h2", "comment": "x"}, {"selector": "p", "comment": ""}], False),
+        ("two anchors both complete passes", "",
+         [{"selector": "h2", "comment": "x"}, {"selector": "p", "comment": "y"}], True),
+        ("short feedback + good anchor passes", "hi",
+         [{"selector": "h2", "comment": "x"}], True),
+    ]
+    for label, fb, anc, want in cases:
+        got, _ = _check_feedback_floor(fb, anc)
+        assert got == want, f"{label}: want {want}, got {got}"
+    print("FLOOR SELF-CHECK PASSED")
+
+
 class PreviewTransactionError(ValueError):
     """Recoverable transaction failure with actionable artifact context."""
 

package/mcp/preview/util.py

@@ -1,10 +1,11 @@
-"""Shared leaf helpers for the preview adapter (logging, timestamps).
+"""Shared leaf helpers for the preview adapter (logging, timestamps, digest).
 
-Sibling to i18n.py; imported by server.py, browser.py, confirm.py.
+Sibling to i18n.py; imported by server.py, browser.py, transaction.py.
 No third-party deps.
 """
 from __future__ import annotations
 
+import hashlib
 import sys
 from datetime import datetime, timezone
 
@@ -13,6 +14,21 @@ def _log(msg: str) -> None:
     print(msg, file=sys.stderr, flush=True)
 
 
+def prototype_html_digest(raw: bytes) -> str:
+    """SHA-256 of prototype bytes with newlines normalized to LF.
+
+    Windows ``core.autocrlf`` rewrites working-tree bytes on checkout; a raw
+    digest then disagrees between the machine that wrote the confirm record
+    and a Linux CI runner validating the same git blob. Line-ending noise is
+    not a prototype content change for G5 integrity (issue 02 / T01).
+
+    Must stay in lockstep with ``scripts/_preview_integrity.prototype_html_digest``.
+    """
+    return hashlib.sha256(
+        raw.replace(b"\r\n", b"\n").replace(b"\r", b"\n")
+    ).hexdigest()
+
+
 
 def _now_iso() -> str:
     return datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "design-playbook",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Design I/O for coding agents: controllable UI generation via declarations (spec/domain/craft/design/components/template) and contracts (skill/evaluator). Use for product UI—console, dashboard, agent-ops, CJK-first apps.",
   "keywords": [
     "pi-package",

package/skills/design-playbook/SKILL.md

@@ -159,7 +159,7 @@ After craft, probe MCP `tools/list` for **`execute_capture_plan`**.
 - **Absent** → skip; `ui-evaluator` ledger `observed` stays free-text (current behavior). G6 not triggered.
 - **Present** → for each L6 criterion whose proof is a runtime state, run the evidence loop in this orchestrator (not inside any skill):
   1. **Derive** a capture plan from L6 `Given -> When -> Then` (in memory, not on disk): `Given`/`When` → `state` + `actions`; `Then` → required proof (already in the ledger `required` field). Do not add or remove verification intent; L6 wins on conflict.
-  2. **Execute**: call `execute_capture_plan({url, type, state, actions, artifact_path})`. The provider returns `{artifact, observed_state, result, error, written_path}` and never sees the criterion. Prefer `written_path` (absolute) when locating the file; if it points outside `.scratch/<run>/`, fix `DESIGN_PLAYBOOK_RUN_ROOT` / cwd before binding. `artifact_path` must start with `evidence/` (e.g., `evidence/empty-state.png`, not `empty-state.png`) — the provider resolves it under `<run_root>/evidence/` and refuses absolute paths, `..` segments, or anything that escapes that subtree (`mcp/evidence/server.py` `_resolve_artifact_path`); a bare filename is rejected because it would land outside the evidence subtree.
+  2. **Execute**: call `execute_capture_plan({url, type, state, actions, artifact_path})`. The provider returns `{artifact, observed_state, result, error, written_path}` and never sees the criterion. Prefer `written_path` (absolute) when locating the file; if it points outside `.scratch/<run>/`, fix `DESIGN_PLAYBOOK_RUN_ROOT` / cwd before binding. `artifact_path` must start with `evidence/` (e.g., `evidence/empty-state.png`, not `empty-state.png`) — the provider resolves it under `<run_root>/evidence/` and refuses absolute paths, `..` segments, or anything that escapes that subtree (`mcp/evidence/server.py` `_resolve_artifact_path`); a bare filename is rejected because it would land outside the evidence subtree. **Async-init timing**: when the page has an async init (skeleton/loading before `body[data-state]` reaches the target state), include a `wait_for_state` action for that state before the capture action. A capture that lands mid-init records the loading state honestly (`observed_state: loading`), which proves the wrong criterion (dogfood 2026-08-01 settings run).
   3. **Bind** (orchestrator owns the manifest; provider never writes it). After **each** successful or failed capture, **immediately append** one line to `.scratch/<run>/evidence/manifest.jsonl` — do not batch-rewrite the file at the end. Rules:
      - **`observed_state` / `result` / `error`**: copy the provider return **verbatim**. If the provider returns `unknown`, write `unknown` — never overwrite with the requested `state` (request intent lives only under `capture.state`).
      - **Embedded capture snapshot**: store the full call parameters used (`url` including query string, `type`, `state`, `actions`, `artifact_path`). Omit nothing that would be needed to re-run the capture.

package/mcp/preview/confirm.py

@@ -1,183 +0,0 @@
-"""ADR-0008 floor logic, G5 trust token, and prototype target resolution.
-
-Sibling module split from server.py; behavior unchanged. Holds the
-feedback-floor check, the G5 one-time decision token + first-decision-wins
-session, the prototype html digest primitive, and the ``--self-check``
-floor cases.
-"""
-from __future__ import annotations
-
-import hashlib
-import secrets
-import sys
-import threading
-from pathlib import Path
-from typing import Any
-
-
-def prototype_html_digest(raw: bytes) -> str:
-    """SHA-256 of prototype bytes with newlines normalized to LF.
-
-    Windows ``core.autocrlf`` rewrites working-tree bytes on checkout; a raw
-    digest then disagrees between the machine that wrote the confirm record
-    and a Linux CI runner validating the same git blob. Line-ending noise is
-    not a prototype content change for G5 integrity (issue 02 / T01).
-
-    Must stay in lockstep with ``scripts/_preview_integrity.prototype_html_digest``.
-    """
-    return hashlib.sha256(
-        raw.replace(b"\r\n", b"\n").replace(b"\r", b"\n")
-    ).hexdigest()
-
-
-def _preview_dir_for(path: Path | None) -> Path:
-    if path is not None:
-        return path.parent
-    scratch = Path.cwd() / ".scratch" / "preview-adapter" / "preview"
-    scratch.mkdir(parents=True, exist_ok=True)
-    return scratch
-
-
-
-def _ensure_prototype(path_arg: str | None, html: str | None, round_n: int,
-                      preview_dir: Path) -> Path:
-    if path_arg:
-        p = Path(path_arg)
-        if not p.is_file():
-            raise ValueError(f"prototype path does not exist: {path_arg}")
-        return p
-    if not html:
-        raise ValueError("path or html is required")
-    preview_dir.mkdir(parents=True, exist_ok=True)
-    target = preview_dir / f"round-{round_n}.html"
-    target.write_text(html, encoding="utf-8")
-    return target
-
-
-def _check_feedback_floor(feedback: str,
-                          anchors: list[dict[str, Any]]) -> tuple[bool, str]:
-    """ADR-0008 preview feedback floor (structural, machine-checkable).
-
-    Passes when:
-    - (non-empty feedback OR >=1 anchor present) as trigger, AND
-    - every present anchor (if any) has non-empty selector AND non-empty comment.
-
-    Deliberately structural, no minimum length: short CJK feedback like
-    "太挤了" is substantive; semantic junk (ADR-0008's "安师大" case) is
-    ui-evaluator's job (G6), not the floor's.
-    Returns (floor_pass, floor_failure_reason).
-    """
-    feedback = (feedback or "").strip()
-    trigger = bool(feedback) or bool(anchors)
-    if not trigger:
-        return False, "confirm with no substantive feedback: empty feedback and no anchor"
-    if anchors:
-        for a in anchors:
-            if not isinstance(a, dict):
-                return False, "anchor is not an object"
-            sel = str(a.get("selector") or "").strip()
-            note = str(a.get("comment") or "").strip()
-            if not sel or not note:
-                return False, (
-                    "anchor missing non-empty selector and comment: "
-                    f"selector={sel!r} comment={note!r}")
-    return True, ""
-
-
-
-def _generate_decision_token() -> str:
-    """One-time URL-safe decision token (G5 trust boundary).
-
-    Proves a POST to /decide originated from the trusted parent control bar
-    (which renders the hidden field) rather than from prototype scripts running
-    inside the sandboxed iframe, which cannot read the parent DOM. Bound to a
-    single preview round via :class:`_DecisionSession`.
-    """
-    return secrets.token_urlsafe(32)
-
-
-class _DecisionSession:
-    """First-decision-wins token lock for a single preview round (G5).
-
-    ``validate`` returns ``True`` only for the first POST whose token matches
-    (constant-time) AND whose round matches. Every other POST — missing token,
-    reused token, mismatched round, or wrong token — is rejected so the caller
-    can fail the decision closed. The session grants at most one valid decision.
-    """
-
-    def __init__(self, round_n: int, token: str) -> None:
-        self.round_n = round_n
-        self._token = token
-        self._locked = False
-        self._lock = threading.Lock()
-        self.last_rejection: str = ""
-
-    @property
-    def locked(self) -> bool:
-        return self._locked
-
-    def validate(self, posted_round: int, posted_token: str | None) -> bool:
-        # LOW-1 (secure-ship-0.4.4): the check-then-set on ``_locked`` must
-        # be atomic. ThreadingHTTPServer handles each POST on its own
-        # thread, so two concurrent valid-token POSTs could both pass the
-        # ``if self._locked`` check and each consume the session. Hold the
-        # lock for the whole decision so first-decision-wins holds under
-        # real concurrency; the lock is uncontended in the single-POST
-        # happy path, so the cost is a no-op acquire/release.
-        with self._lock:
-            if not posted_token:
-                self.last_rejection = "missing"
-                return False
-            if posted_round != self.round_n:
-                self.last_rejection = "round_mismatch"
-                return False
-            if self._locked:
-                # First valid decision already consumed the session; every
-                # later POST (even with the correct token) is a replay.
-                self.last_rejection = "reuse"
-                return False
-            if not secrets.compare_digest(posted_token, self._token):
-                self.last_rejection = "invalid_token"
-                return False
-            self._locked = True
-            self.last_rejection = ""
-            return True
-
-
-def _self_check_floor() -> None:
-    """ADR-0008 floor branch logic self-check (ponytail: one runnable check)."""
-    cases = [
-        ("empty + no anchors", "", [], False),
-        ("whitespace-only feedback", "   \n  ", [], False),
-        ("short feedback passes (structural floor)", "ok", [], True),
-        ("short CJK feedback passes ('太挤了' is substantive)", "太挤了", [], True),
-        ("'安师大' passes floor; semantic junk is G6's job (ADR-0008)", "安师大", [], True),
-        ("longer feedback passes", "fix it", [], True),
-        ("anchor with comment", "", [{"selector": "h2", "comment": "x"}], True),
-        ("anchor no comment (0015 garbage)", "",
-         [{"selector": "h2", "comment": ""}], False),
-        ("anchor empty selector", "",
-         [{"selector": "", "comment": "x"}], False),
-        ("non-dict anchor", "", ["not-a-dict"], False),
-        ("feedback + incomplete anchor still fails", "ok",
-         [{"selector": "h2", "comment": ""}], False),
-        ("two anchors one incomplete fails", "",
-         [{"selector": "h2", "comment": "x"}, {"selector": "p", "comment": ""}], False),
-        ("two anchors both complete passes", "",
-         [{"selector": "h2", "comment": "x"}, {"selector": "p", "comment": "y"}], True),
-        ("short feedback + good anchor passes", "hi",
-         [{"selector": "h2", "comment": "x"}], True),
-    ]
-    for label, fb, anc, want in cases:
-        got, _ = _check_feedback_floor(fb, anc)
-        assert got == want, f"{label}: want {want}, got {got}"
-    print("FLOOR SELF-CHECK PASSED")
-
-
-if __name__ == "__main__":
-    if len(sys.argv) > 1 and sys.argv[1] == "--self-check":
-        _self_check_floor()
-    else:
-        raise SystemExit(
-            "usage: confirm.py --self-check (the MCP server entry is server.py)")
-