design-playbook 0.9.0 → 0.9.2

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "design-playbook",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "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.