design-playbook 0.25.2 → 0.25.3

package/README.md

@@ -149,6 +149,17 @@ LICENSE · NOTICE       ← authored-only scope
 
 Only authored content in this package (skills, pipeline commands, metadata, self-written examples, self-authored bundled MCP adapters). See `NOTICE` and repo ADRs 0003–0006, 0009. Repo-maintainer polish commands live in the monorepo root `.claude/commands/`, not in this package.
 
+## Runtime behavior & data
+
+Everything this plugin runs is local and disclosed here (directory-submission review):
+
+- **MCP servers** (stdio, launched from `${CLAUDE_PLUGIN_ROOT}` in `.mcp.json`):
+  - `design-playbook-preview` — `python mcp/preview/server.py`. Renders a caller-supplied HTML prototype in a local window and collects a confirm/revise decision. No third-party dependencies.
+  - `design-playbook-evidence` — `python mcp/evidence/server.py`. Drives a local browser (Playwright + Chromium, user-installed) to the URL named in each capture call and writes screenshot / a11y-tree / trace artifacts under `<run_root>/evidence/`. It never uploads artifacts (no HTTP delivery endpoint exists).
+- **Network:** the plugin makes no outbound request of its own — no telemetry, analytics, or reporting. The only fetch is the browser navigating to the target URL you pass to a capture call (and whatever that page loads).
+- **Environment:** `DESIGN_PLAYBOOK_RUN_ROOT` is forwarded to the evidence server via `env` interpolation to locate the run tree; no credentials or tokens are read. Unset → artifacts resolve under the MCP process cwd.
+- **Interpreter:** servers run under `python` (Python 3); the evidence path also needs `playwright` + a Chromium install. Hosts without these skip `preview*` / `observe*` (absent→skip, ADR-0009).
+
 ## Contract vs enforcement
 
 Evidence exists only to satisfy a declared criterion — an observation without a binding to an L6 acceptance item is telemetry, not evidence. Runtime capture is done by external providers; design-playbook owns the binding (manifest) and the verdict (ledger), never the runtime.
@@ -191,7 +202,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`:** `.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.
+**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` forwards this variable via a standard `env` interpolation (`${DESIGN_PLAYBOOK_RUN_ROOT:-}`), 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.2 -->
+<!-- generated-by design-playbook v0.25.3 -->
 # design-playbook for Codex
 
 ## Install (path of record)

package/commands/component-distill.md

@@ -6,3 +6,11 @@ Cross-run **component backflow** over `.scratch/<run>/` decision reports in the
 
 Output path:
 $ARGUMENTS
+
+## Project target (resolve before any project read or write)
+
+- Pass the target explicitly as `project="<absolute-directory>"` and, for a workbench task, `request="<request-id>"`. Values may contain spaces and CJK characters; they are data, never shell text.
+- Resolve it with `python "${CLAUDE_PLUGIN_ROOT}/scripts/project_target.py" --arguments "<the same text>"`. That script answers from the local workbench service, which owns the project bindings.
+- A project-level install binds the project that carries the install marker. A user-level install must name the target on every call: an absolute directory, or a project already registered in the local workbench. The home directory, this plugin's install directory, the current working directory, and the previously used target are never used as a fallback.
+- Without a `request`, an explicit absolute directory still resolves while the service is stopped: the script reports that directory and creates no offline copy of the project's assets or a second identity. With a `request` the service must be running and must match the project; if it is not, the script exits `unavailable` — stop.
+- If resolution is refused (`invalid-target`, `disconnected`) or the request does not belong to the resolved project, stop and say which input is missing. Read and write nothing in that case.

package/commands/design-io.md

@@ -6,3 +6,11 @@ Run skill **design-playbook** in full. Honor each step’s completion criterion
 
 User request:
 $ARGUMENTS
+
+## Project target (resolve before any project read or write)
+
+- Pass the target explicitly as `project="<absolute-directory>"` and, for a workbench task, `request="<request-id>"`. Values may contain spaces and CJK characters; they are data, never shell text.
+- Resolve it with `python "${CLAUDE_PLUGIN_ROOT}/scripts/project_target.py" --arguments "<the same text>"`. That script answers from the local workbench service, which owns the project bindings.
+- A project-level install binds the project that carries the install marker. A user-level install must name the target on every call: an absolute directory, or a project already registered in the local workbench. The home directory, this plugin's install directory, the current working directory, and the previously used target are never used as a fallback.
+- Without a `request`, an explicit absolute directory still resolves while the service is stopped: the script reports that directory and creates no offline copy of the project's assets or a second identity. With a `request` the service must be running and must match the project; if it is not, the script exits `unavailable` — stop.
+- If resolution is refused (`invalid-target`, `disconnected`) or the request does not belong to the resolved project, stop and say which input is missing. Read and write nothing in that case.

package/commands/run-handoff.md

@@ -25,3 +25,11 @@ The user asked for a handoff; `index.html` exists under the selected run tree; a
 
 Scope:
 $ARGUMENTS
+
+## Project target (resolve before any project read or write)
+
+- Pass the target explicitly as `project="<absolute-directory>"` and, for a workbench task, `request="<request-id>"`. Values may contain spaces and CJK characters; they are data, never shell text.
+- Resolve it with `python "${CLAUDE_PLUGIN_ROOT}/scripts/project_target.py" --arguments "<the same text>"`. That script answers from the local workbench service, which owns the project bindings.
+- A project-level install binds the project that carries the install marker. A user-level install must name the target on every call: an absolute directory, or a project already registered in the local workbench. The home directory, this plugin's install directory, the current working directory, and the previously used target are never used as a fallback.
+- Without a `request`, an explicit absolute directory still resolves while the service is stopped: the script reports that directory and creates no offline copy of the project's assets or a second identity. With a `request` the service must be running and must match the project; if it is not, the script exits `unavailable` — stop.
+- If resolution is refused (`invalid-target`, `disconnected`) or the request does not belong to the resolved project, stop and say which input is missing. Read and write nothing in that case.

package/commands/run-review.md

@@ -30,3 +30,11 @@ Prohibited:
 
 Scope:
 $ARGUMENTS
+
+## Project target (resolve before any project read or write)
+
+- Pass the target explicitly as `project="<absolute-directory>"` and, for a workbench task, `request="<request-id>"`. Values may contain spaces and CJK characters; they are data, never shell text.
+- Resolve it with `python "${CLAUDE_PLUGIN_ROOT}/scripts/project_target.py" --arguments "<the same text>"`. That script answers from the local workbench service, which owns the project bindings.
+- A project-level install binds the project that carries the install marker. A user-level install must name the target on every call: an absolute directory, or a project already registered in the local workbench. The home directory, this plugin's install directory, the current working directory, and the previously used target are never used as a fallback.
+- Without a `request`, an explicit absolute directory still resolves while the service is stopped: the script reports that directory and creates no offline copy of the project's assets or a second identity. With a `request` the service must be running and must match the project; if it is not, the script exits `unavailable` — stop.
+- If resolution is refused (`invalid-target`, `disconnected`) or the request does not belong to the resolved project, stop and say which input is missing. Read and write nothing in that case.

package/commands/run-status.md

@@ -105,3 +105,11 @@ The command names completed stage markers, any active blocker (preview floor, ba
 
 In scope mode, known links are traceable to their declaration and hash, uncertain
 links remain explicit, and diagnostic gaps never replace the evaluator verdict.
+
+## Project target (resolve before any project read or write)
+
+- Pass the target explicitly as `project="<absolute-directory>"` and, for a workbench task, `request="<request-id>"`. Values may contain spaces and CJK characters; they are data, never shell text.
+- Resolve it with `python "${CLAUDE_PLUGIN_ROOT}/scripts/project_target.py" --arguments "<the same text>"`. That script answers from the local workbench service, which owns the project bindings.
+- A project-level install binds the project that carries the install marker. A user-level install must name the target on every call: an absolute directory, or a project already registered in the local workbench. The home directory, this plugin's install directory, the current working directory, and the previously used target are never used as a fallback.
+- Without a `request`, an explicit absolute directory still resolves while the service is stopped: the script reports that directory and creates no offline copy of the project's assets or a second identity. With a `request` the service must be running and must match the project; if it is not, the script exits `unavailable` — stop.
+- If resolution is refused (`invalid-target`, `disconnected`) or the request does not belong to the resolved project, stop and say which input is missing. Read and write nothing in that case.

package/commands/ui-review.md

@@ -6,3 +6,11 @@ Run skill **ui-evaluator** (pull craft-guard checks when AI slop/motion/loading
 
 Scope:
 $ARGUMENTS
+
+## Project target (resolve before any project read or write)
+
+- Pass the target explicitly as `project="<absolute-directory>"` and, for a workbench task, `request="<request-id>"`. Values may contain spaces and CJK characters; they are data, never shell text.
+- Resolve it with `python "${CLAUDE_PLUGIN_ROOT}/scripts/project_target.py" --arguments "<the same text>"`. That script answers from the local workbench service, which owns the project bindings.
+- A project-level install binds the project that carries the install marker. A user-level install must name the target on every call: an absolute directory, or a project already registered in the local workbench. The home directory, this plugin's install directory, the current working directory, and the previously used target are never used as a fallback.
+- Without a `request`, an explicit absolute directory still resolves while the service is stopped: the script reports that directory and creates no offline copy of the project's assets or a second identity. With a `request` the service must be running and must match the project; if it is not, the script exits `unavailable` — stop.
+- If resolution is refused (`invalid-target`, `disconnected`) or the request does not belong to the resolved project, stop and say which input is missing. Read and write nothing in that case.

package/commands/ux-spec.md

@@ -6,3 +6,11 @@ Run the ux-spec protocol only. A same-named command in this plugin shadows the `
 
 Request:
 $ARGUMENTS
+
+## Project target (resolve before any project read or write)
+
+- Pass the target explicitly as `project="<absolute-directory>"` and, for a workbench task, `request="<request-id>"`. Values may contain spaces and CJK characters; they are data, never shell text.
+- Resolve it with `python "${CLAUDE_PLUGIN_ROOT}/scripts/project_target.py" --arguments "<the same text>"`. That script answers from the local workbench service, which owns the project bindings.
+- A project-level install binds the project that carries the install marker. A user-level install must name the target on every call: an absolute directory, or a project already registered in the local workbench. The home directory, this plugin's install directory, the current working directory, and the previously used target are never used as a fallback.
+- Without a `request`, an explicit absolute directory still resolves while the service is stopped: the script reports that directory and creates no offline copy of the project's assets or a second identity. With a `request` the service must be running and must match the project; if it is not, the script exits `unavailable` — stop.
+- If resolution is refused (`invalid-target`, `disconnected`) or the request does not belong to the resolved project, stop and say which input is missing. Read and write nothing in that case.

package/mcp/evidence/capture_runtime.py

@@ -332,19 +332,30 @@ def _validated_call_run_root(value: object) -> Path:
     return root
 
 
+def _is_unset_run_root(value: str | None) -> bool:
+    """True when an env value must fall back to process cwd.
+
+    Unset/empty and the literal ``"."`` both mean "no explicit root". A value
+    that still contains ``"${"`` is an interpolation token the launching host
+    did not expand — e.g. the ``.mcp.json`` ``${DESIGN_PLAYBOOK_RUN_ROOT:-}``
+    passthrough on a host that does not resolve ``${…}`` (ADR-0009) — so treat
+    it as unset rather than resolving a literal ``"${…}"`` into a bogus root.
+    """
+    return not value or value == "." or "${" in value
+
+
 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.
+    The shipped .mcp.json forwards ``${DESIGN_PLAYBOOK_RUN_ROOT:-}`` (empty when
+    the host has no run root set), so the server resolves 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 != ".":
+    if not _is_unset_run_root(os.environ.get(RUN_ROOT_ENV)):
         return False
     return not _has_run_marker(Path.cwd().resolve())
 
@@ -354,7 +365,7 @@ def _run_root() -> Path:
     if explicit is not None:
         return explicit
     configured = os.environ.get(RUN_ROOT_ENV)
-    if not configured or configured == ".":
+    if _is_unset_run_root(configured):
         # 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

package/package.json

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

package/scripts/project_target.py

@@ -0,0 +1,397 @@
+#!/usr/bin/env python3
+"""Resolve the target project for a slash invocation (R02).
+
+Slash commands are prompt text, so the *resolution* has to be a real,
+checkable step rather than a sentence an agent may interpret loosely.
+This script is that step:
+
+- the install scope is decided from adapter metadata or an explicit
+  configuration file -- never from the current working directory;
+- a project-level install binds the project that carries the marker;
+- a user-level install refuses to guess: an explicit absolute directory
+  (or an explicit registered project id) is required, and the home
+  directory, the plugin install directory, the current working
+  directory, and any previous target are never used as a fallback;
+- the answer comes from the local workbench service, which is the
+  authority for bindings. Without a request, an explicit absolute
+  directory also resolves while the service is stopped, so the
+  pre-workbench slash workflow keeps working; nothing is registered and no
+  competing, offline asset directory is ever created. With a request, or a
+  registered project id, the service must be running -- otherwise the
+  result is ``unavailable`` and the command stops.
+
+Usage::
+
+    python project_target.py --project "<absolute-directory>" [--request <id>]
+    python project_target.py --project-id "<uuid>"
+    python project_target.py --describe-scope
+
+Exit codes: 0 resolved, 3 target refused (invalid/disconnected/unknown),
+4 service unavailable.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+SCOPE_PROJECT = "project-level"
+SCOPE_USER = "user-level"
+SCOPE_UNKNOWN = "unknown"
+
+EXIT_OK = 0
+EXIT_REFUSED = 3
+EXIT_UNAVAILABLE = 4
+
+#: Marker files that identify a project-level install without asking the
+#: current working directory anything: the adapter metadata lives inside
+#: the project the plugin was installed into.
+PROJECT_MARKERS: tuple[str, ...] = (
+    ".claude/settings.json",
+    ".claude-plugin/plugin.json",
+    ".design-playbook/project.json",
+)
+
+DEFAULT_DATA_DIR_ENV = "DESIGN_PLAYBOOK_WORKBENCH_DATA_DIR"
+RECORD_RELATIVE = ("session", "session.json")
+
+SERVICE_TIMEOUT_SECONDS = 10
+
+
+class TargetRefused(Exception):
+    """The caller must stop: no project may be read or written."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+class ServiceUnavailable(Exception):
+    """The local workbench service is not running (or has no live record)."""
+
+
+def _workbench_data_dir(environ: dict | None = None) -> Path:
+    env = os.environ if environ is None else environ
+    override = env.get(DEFAULT_DATA_DIR_ENV)
+    if override:
+        return Path(override)
+    if os.name == "nt":
+        base = env.get("LOCALAPPDATA") or env.get("APPDATA")
+        if base:
+            return Path(base) / "design-playbook-workbench"
+    xdg = env.get("XDG_DATA_HOME")
+    if xdg:
+        return Path(xdg) / "design-playbook-workbench"
+    return Path.home() / ".local" / "share" / "design-playbook-workbench"
+
+
+def read_session_record(data_dir: Path | str | None = None) -> dict:
+    """The OS-protected credential record, or ``ServiceUnavailable``."""
+    root = Path(data_dir) if data_dir is not None else _workbench_data_dir()
+    path = root.joinpath(*RECORD_RELATIVE)
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError:
+        raise ServiceUnavailable(
+            "the workbench service is not running (no session record)"
+        ) from None
+    try:
+        record = json.loads(raw)
+    except json.JSONDecodeError:
+        raise ServiceUnavailable("the session record is not readable") from None
+    if not isinstance(record, dict) or not record.get("authority"):
+        raise ServiceUnavailable("the session record is incomplete")
+    return record
+
+
+def detect_install_scope(
+    *,
+    plugin_root: Path | str | None,
+    cwd: Path | str | None,
+    environ: dict | None = None,
+    explicit_scope: str | None = None,
+) -> tuple[str, str | None]:
+    """Decide the install scope from metadata, never from ``cwd`` alone.
+
+    Returns ``(scope, project_root)``. A project-level install is detected
+    by an adapter marker inside the project directory itself, and the
+    reported project root is the directory that carries the marker.
+    """
+    env = os.environ if environ is None else environ
+    configured = explicit_scope or env.get("DESIGN_PLAYBOOK_INSTALL_SCOPE")
+    if configured in (SCOPE_PROJECT, SCOPE_USER):
+        root = env.get("DESIGN_PLAYBOOK_PROJECT_ROOT")
+        if configured == SCOPE_PROJECT:
+            if not root:
+                raise TargetRefused(
+                    "invalid-target",
+                    "a project-level install must declare DESIGN_PLAYBOOK_PROJECT_ROOT",
+                )
+            return SCOPE_PROJECT, str(Path(root).expanduser().resolve())
+        return SCOPE_USER, None
+    if configured is not None:
+        raise TargetRefused(
+            "invalid-input",
+            "DESIGN_PLAYBOOK_INSTALL_SCOPE must be 'project-level' or 'user-level'",
+        )
+
+    candidates: list[Path] = []
+    if plugin_root is not None:
+        candidates.append(Path(plugin_root).expanduser().resolve().parent)
+    if cwd is not None:
+        candidates.append(Path(cwd).expanduser().resolve())
+    seen: set[str] = set()
+    for candidate in candidates:
+        for marker in PROJECT_MARKERS:
+            marker_path = candidate / marker
+            if not marker_path.is_file():
+                continue
+            text = marker_path.read_text(encoding="utf-8", errors="replace")
+            if "design-playbook" not in text:
+                continue
+            key = str(candidate)
+            if key in seen:
+                continue
+            seen.add(key)
+            return SCOPE_PROJECT, key
+    return SCOPE_USER, None
+
+
+def parse_request_arguments(text: str) -> dict:
+    """Parse the ``project="..." request="..."`` text convention.
+
+    Only those two names are recognised, values may contain spaces and
+    CJK characters, and the result is never assembled into a shell
+    string: the caller passes the value as an argument.
+    """
+    result: dict[str, str] = {}
+    index = 0
+    length = len(text)
+    while index < length:
+        while index < length and text[index].isspace():
+            index += 1
+        if index >= length:
+            break
+        match = None
+        for name in ("project", "request"):
+            if text.startswith(name, index):
+                after = index + len(name)
+                if after < length and text[after] == "=":
+                    match = (name, after + 1)
+                    break
+        if match is None:
+            index += 1
+            continue
+        name, value_start = match
+        if value_start < length and text[value_start] in "\"'":
+            quote = text[value_start]
+            end = text.find(quote, value_start + 1)
+            if end == -1:
+                raise TargetRefused("invalid-input", f"unterminated {name} value")
+            result[name] = text[value_start + 1 : end]
+            index = end + 1
+            continue
+        end = value_start
+        while end < length and not text[end].isspace():
+            end += 1
+        result[name] = text[value_start:end]
+        index = end
+    return result
+
+
+def _http_get(record: dict, path: str, query: str) -> dict:
+    url = record["authority"] + path + ("?" + query if query else "")
+    request = urllib.request.Request(url, method="GET")
+    request.add_header("Authorization", "Bearer " + str(record.get("sessionToken", "")))
+    opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+    try:
+        with opener.open(request, timeout=SERVICE_TIMEOUT_SECONDS) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as error:
+        payload = None
+        try:
+            payload = json.loads(error.read().decode("utf-8"))
+        except Exception:
+            payload = None
+        code = (
+            payload.get("error", {}).get("code")
+            if isinstance(payload, dict)
+            else None
+        )
+        raise TargetRefused(code or "invalid-target", "the service refused the target")
+    except (urllib.error.URLError, OSError, ValueError):
+        raise ServiceUnavailable(
+            "the workbench service is not reachable on its bound address"
+        ) from None
+
+
+def _resolve_offline(project: str) -> dict:
+    """Resolve one explicit absolute directory without the service.
+
+    Only reachable when no request is named and the service is not running:
+    an existing workflow keeps its explicit directory. Nothing is registered
+    and no asset directory is created -- the directory alone is the answer.
+    """
+    if not isinstance(project, str) or not project.strip():
+        raise TargetRefused(
+            "invalid-target", "an explicit project directory is required"
+        )
+    path = Path(project).expanduser()
+    if not path.is_absolute():
+        raise TargetRefused("invalid-target", "an absolute directory is required")
+    if not path.is_dir():
+        raise TargetRefused("invalid-target", "the target directory is not reachable")
+    canonical = path.resolve()
+    return {
+        "resolved": True,
+        "mode": "offline",
+        "authority": None,
+        "project": {
+            "projectId": None,
+            "name": canonical.name,
+            "canonicalPath": str(canonical),
+        },
+        "requestId": None,
+        "taskState": None,
+    }
+
+
+def resolve_target(
+    *,
+    project: str | None = None,
+    project_id: str | None = None,
+    request_id: str | None = None,
+    data_dir: Path | str | None = None,
+) -> dict:
+    """Ask the local service to resolve one explicit target.
+
+    A request, or a registered project id, is always the service's answer:
+    without the service it is ``unavailable``. A bare explicit directory
+    with no request still resolves while the service is stopped, so the
+    pre-workbench slash workflow keeps working.
+    """
+    if bool(project) == bool(project_id):
+        raise TargetRefused(
+            "invalid-target",
+            "an explicit project directory or project id is required",
+        )
+    if project_id:
+        query = "projectId=" + urllib.parse.quote(project_id, safe="")
+    else:
+        query = "project=" + urllib.parse.quote(str(project), safe="")
+    if request_id:
+        query += "&request=" + urllib.parse.quote(request_id, safe="")
+    try:
+        record = read_session_record(data_dir)
+        payload = _http_get(record, "/api/v1/resolve", query)
+    except ServiceUnavailable:
+        if project_id or request_id:
+            raise
+        return _resolve_offline(str(project))
+    payload["authority"] = record["authority"]
+    payload["bootId"] = record.get("bootId")
+    return payload
+
+
+def describe_scope(
+    *, plugin_root: Path | str | None = None, cwd: Path | str | None = None
+) -> dict:
+    scope, project_root = detect_install_scope(
+        plugin_root=plugin_root, cwd=cwd
+    )
+    return {
+        "installScope": scope,
+        "projectRoot": project_root,
+        "explicitTargetRequired": scope == SCOPE_USER,
+    }
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="project_target",
+        description=(
+            "Resolve the project target for a design-playbook slash command. "
+            "Never falls back to the home directory, the plugin install "
+            "directory, the current working directory, or a previous target."
+        ),
+    )
+    parser.add_argument("--project", help="Absolute project directory.")
+    parser.add_argument("--project-id", dest="project_id", help="Registered project id.")
+    parser.add_argument("--request", help="Work request id bound to the project.")
+    parser.add_argument(
+        "--arguments",
+        help=(
+            "Raw slash argument text; project= and request= values are read "
+            "from it when the matching flags are absent."
+        ),
+    )
+    parser.add_argument(
+        "--data-dir", help="Workbench data directory (default: per-user location)."
+    )
+    parser.add_argument(
+        "--describe-scope",
+        action="store_true",
+        help="Report the detected install scope and exit.",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = build_parser().parse_args(argv)
+    stream = sys.stdout
+    try:
+        if arguments.describe_scope:
+            payload = describe_scope(
+                plugin_root=os.environ.get("CLAUDE_PLUGIN_ROOT"),
+                cwd=os.getcwd(),
+            )
+            stream.write(json.dumps(payload, ensure_ascii=False) + "\n")
+            return EXIT_OK
+        project = arguments.project
+        request_id = arguments.request
+        if arguments.arguments:
+            parsed = parse_request_arguments(arguments.arguments)
+            if not project:
+                project = parsed.get("project")
+            if not request_id:
+                request_id = parsed.get("request")
+        payload = resolve_target(
+            project=project,
+            project_id=arguments.project_id,
+            request_id=request_id,
+            data_dir=arguments.data_dir,
+        )
+        stream.write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+        return EXIT_OK
+    except TargetRefused as refusal:
+        stream.write(
+            json.dumps(
+                {"resolved": False, "code": refusal.code, "message": refusal.message},
+                ensure_ascii=False,
+            )
+            + "\n"
+        )
+        return EXIT_REFUSED
+    except ServiceUnavailable as unavailable:
+        stream.write(
+            json.dumps(
+                {
+                    "resolved": False,
+                    "code": "unavailable",
+                    "message": str(unavailable),
+                },
+                ensure_ascii=False,
+            )
+            + "\n"
+        )
+        return EXIT_UNAVAILABLE
+
+
+if __name__ == "__main__":  # pragma: no cover - script entry
+    raise SystemExit(main())

package/scripts/publish_owner_projection.py

@@ -0,0 +1,429 @@
+#!/usr/bin/env python3
+"""Owner-side projection publisher: the R12 thin typed interface.
+
+The workbench (``packages/design-playbook-workbench``) reads a typed
+projection document at ``<project>/.design-playbook/runs/<run>/projection.json``
+and rebuilds its own view of the *owner's* facts. Owner runs did not publish
+that document, so this script is the thin, bounded writer for it. Specification
+R12 allows exactly this shape of integration: an existing owner that lacks a
+typed entry gets "薄接口及负例测试" from an integration ticket, and the web side
+must never copy the owner's domain judgement.
+
+What it does -- transcribe, never judge:
+
+* ``evidence[]`` comes from the run's own ``evidence/manifest.jsonl`` (written
+  by ``scripts/evidence_manifest.py``). The artifact name, its sha256, and its
+  criterion binding are copied verbatim.
+* ``criteria[]`` comes from the evaluator's evidence ledger text
+  (``criterion:`` / ``required:`` / ``observed:`` / ``result:`` rows), parsed by
+  the single Evidence ledger parser (``mcp/evidence/ledger_syntax.py``). The
+  verdict is the owner's own ``result:`` value. ``N/A`` (not applicable) is
+  recorded as ``unknown``: not applicable is not a pass.
+* ``findings[]`` comes from an explicit ``--findings`` JSON file when one is
+  given, and is empty otherwise. This script never invents a finding.
+
+It refuses rather than guesses. An unknown verdict, a row without a criterion
+or result, two rows for one criterion, a ledger with no rows, a non-hex
+manifest digest, or a missing owner all abort with a non-zero exit and write
+nothing.
+
+Authority bounds: it writes exactly one file, inside
+``<project-root>/.design-playbook/runs/<run-id>/``; the run id is validated so
+it cannot escape that tree; it reads only the run's own evidence manifest, the
+ledger file, and the findings file it was given; it opens no socket and runs no
+process.
+
+Usage::
+
+    python scripts/publish_owner_projection.py <run-dir> \\
+        --project-root <target repo> --run-id <run> --owner ui-evaluator \\
+        --ledger <ledger text file> [--findings <findings.json>] \\
+        [--runner "design-playbook ui-evaluator"]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path, PurePosixPath, PureWindowsPath
+
+# One import seam (ADR-0022): package root on sys.path once, then absolute
+# design_playbook.* imports below, exactly like scripts/evidence_manifest.py.
+_PKG_ROOT = Path(__file__).resolve().parent.parent
+if str(_PKG_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PKG_ROOT))
+
+from design_playbook.mcp.evidence.ledger_syntax import (  # noqa: E402
+    parse_ledger,
+)
+
+#: The projection document version the workbench understands.
+PROJECTION_VERSION = "owner-projection/v1"
+#: Where the workbench looks for a run projection, relative to the project root.
+PROJECTION_ROOT = ".design-playbook/runs"
+#: The manifest the Evidence write side owns.
+MANIFEST_NAME = "manifest.jsonl"
+
+#: Owner result vocabulary -> workbench verdict vocabulary.
+#: ``N/A`` is deliberately ``unknown``: not applicable is not a pass.
+_VERDICT_MAP = {"pass": "pass", "fail": "fail", "blocked": "blocked", "n/a": "unknown"}
+
+_HEX64 = re.compile(r"^[0-9a-f]{64}$")
+_RESERVED_RUN_IDS = {"", ".", ".."}
+
+
+class ProjectionPublishError(ValueError):
+    """Rejected publish: the inputs cannot be transcribed faithfully."""
+
+
+# -- pure helpers --------------------------------------------------------
+
+
+def check_run_id(run_id: object) -> str:
+    """Validate a run id as one safe path segment.
+
+    A run id reaches the filesystem, so it is treated as hostile input: only a
+    single segment with no separators, no drive designator and no traversal is
+    accepted.
+    """
+    if not isinstance(run_id, str) or not run_id.strip():
+        raise ProjectionPublishError("run id is required")
+    if run_id in _RESERVED_RUN_IDS:
+        raise ProjectionPublishError("run id is not a usable directory name")
+    if "\x00" in run_id:
+        raise ProjectionPublishError("run id contains a NUL byte")
+    posix, windows = PurePosixPath(run_id), PureWindowsPath(run_id)
+    if (
+        len(posix.parts) != 1
+        or len(windows.parts) != 1
+        or posix.parts[0] != run_id
+        or windows.parts[0] != run_id
+        or windows.drive
+        or "/" in run_id
+        or "\\" in run_id
+    ):
+        raise ProjectionPublishError("run id must be a single path segment")
+    return run_id
+
+
+def check_owner(owner: object) -> str:
+    """The owner is never invented: a missing owner is a hard refusal."""
+    if not isinstance(owner, str) or not owner.strip():
+        raise ProjectionPublishError("owner is required (the workbench invents none)")
+    return owner.strip()
+
+
+def prefixed_digest(raw: object) -> str:
+    """Normalise a manifest sha256 into the workbench's ``sha256:<hex>`` form."""
+    if not isinstance(raw, str) or not _HEX64.match(raw.strip().lower()):
+        raise ProjectionPublishError("manifest digest is not a sha256 hex digest")
+    return "sha256:" + raw.strip().lower()
+
+
+def map_verdict(result: object) -> str:
+    """The owner's own result value, mapped; an unknown value is refused."""
+    if not isinstance(result, str):
+        raise ProjectionPublishError("ledger row has no result value")
+    verdict = _VERDICT_MAP.get(result.strip().lower())
+    if verdict is None:
+        raise ProjectionPublishError(f"unknown ledger result {result!r}")
+    return verdict
+
+
+def artifact_basename(token: str) -> str:
+    """The bare artifact filename a ledger ``observed`` token points at."""
+    text = token.strip()
+    for prefix in ("evidence/", "evidence\\"):
+        if text.lower().startswith(prefix):
+            text = text[len(prefix):]
+            break
+    return text
+
+
+def read_manifest(run_dir: Path) -> list[dict]:
+    """Read the run's ``evidence/manifest.jsonl``; refuse a malformed line."""
+    path = run_dir / "evidence" / MANIFEST_NAME
+    if not path.is_file():
+        raise ProjectionPublishError(f"missing evidence manifest: {path}")
+    entries: list[dict] = []
+    for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+        if not line.strip():
+            continue
+        try:
+            entry = json.loads(line)
+        except json.JSONDecodeError as error:
+            raise ProjectionPublishError(
+                f"manifest line {number} is not JSON: {error.msg}"
+            ) from None
+        if not isinstance(entry, dict):
+            raise ProjectionPublishError(f"manifest line {number} is not an object")
+        entries.append(entry)
+    return entries
+
+
+def evidence_rows(entries: list[dict]) -> list[dict]:
+    """Transcribe manifest bindings into workbench evidence rows."""
+    rows: list[dict] = []
+    for entry in entries:
+        artifact = entry.get("artifact")
+        criterion = entry.get("criterion")
+        if not isinstance(artifact, str) or not artifact:
+            raise ProjectionPublishError("manifest entry has no artifact")
+        if not isinstance(criterion, str) or not criterion:
+            raise ProjectionPublishError("manifest entry has no criterion")
+        row: dict[str, object] = {
+            "evidenceId": artifact,
+            "hash": prefixed_digest(entry.get("sha256")),
+            "criterionId": criterion,
+            "capturedAt": entry.get("ts") or "",
+        }
+        # Only fields the owner actually stated are carried; nothing is derived.
+        for key in ("kind", "mediaType", "role"):
+            value = entry.get(key)
+            if isinstance(value, str) and value:
+                row[key] = value
+        rows.append(row)
+    return rows
+
+
+def _manifest_index(entries: list[dict]) -> dict[str, str]:
+    """artifact filename -> ``sha256:<hex>`` for one run."""
+    index: dict[str, str] = {}
+    for entry in entries:
+        artifact = entry.get("artifact")
+        if isinstance(artifact, str) and artifact:
+            index[artifact] = prefixed_digest(entry.get("sha256"))
+    return index
+
+
+def criteria_rows(ledger_text: str, entries: list[dict]) -> list[dict]:
+    """Transcribe ledger rows into workbench criterion rows.
+
+    One ledger row per criterion is the evaluator's own contract, so a missing
+    or duplicated criterion id is refused instead of resolved arbitrarily.
+    """
+    facts = parse_ledger(ledger_text)
+    if not facts.rows:
+        raise ProjectionPublishError("ledger carries no criterion rows")
+    bindings: dict[str, list[str]] = {}
+    index = _manifest_index(entries)
+    for entry in entries:
+        criterion = entry.get("criterion")
+        if isinstance(criterion, str) and criterion:
+            bindings.setdefault(criterion, []).append(
+                prefixed_digest(entry.get("sha256"))
+            )
+
+    rows: list[dict] = []
+    seen: set[str] = set()
+    for ledger_row in facts.rows:
+        criteria = ledger_row.values("criterion")
+        results = ledger_row.values("result")
+        if not criteria:
+            raise ProjectionPublishError("ledger row has no criterion id")
+        criterion_id = criteria[0]
+        if len(criteria) > 1:
+            raise ProjectionPublishError(
+                f"ledger row for {criterion_id} repeats its criterion id"
+            )
+        if criterion_id in seen:
+            raise ProjectionPublishError(f"duplicate ledger row for {criterion_id}")
+        seen.add(criterion_id)
+        if not results:
+            raise ProjectionPublishError(f"ledger row {criterion_id} has no result")
+        row = {
+            "criterionId": criterion_id,
+            "verdict": map_verdict(results[0]),
+            "evidenceHashes": list(bindings.get(criterion_id, [])),
+        }
+        # A criterion's source hash is the digest the owner already bound to
+        # the artifact its own ledger names. When the owner bound nothing, the
+        # field is omitted rather than invented, and the workbench reports the
+        # fact as unverifiable ("unknown") instead of fresh. The semantic role
+        # is omitted for the same reason: the ledger states none.
+        observed = ledger_row.artifact_token
+        if observed:
+            digest = index.get(artifact_basename(observed))
+            if digest is not None:
+                row["sourceHash"] = digest
+        rows.append(row)
+    return rows
+
+
+def finding_rows(raw: object) -> list[dict]:
+    """Validate and transcribe an explicit findings list; never invent one."""
+    if raw is None:
+        return []
+    if not isinstance(raw, list):
+        raise ProjectionPublishError("findings must be a JSON list")
+    rows: list[dict] = []
+    for item in raw:
+        if not isinstance(item, dict):
+            raise ProjectionPublishError("finding is not an object")
+        finding_id = item.get("findingId")
+        if not isinstance(finding_id, str) or not finding_id:
+            raise ProjectionPublishError("finding has no findingId")
+        pointer = item.get("pointBack")
+        if pointer is not None and not isinstance(pointer, dict):
+            raise ProjectionPublishError("finding pointBack is not an object")
+        row: dict[str, object] = {
+            "findingId": finding_id,
+            "severity": item.get("severity") or "info",
+            "summary": item.get("summary") or "",
+        }
+        if isinstance(item.get("criterionId"), str):
+            row["criterionId"] = item["criterionId"]
+        if isinstance(item.get("sourceHash"), str):
+            row["sourceHash"] = item["sourceHash"]
+        if isinstance(item.get("role"), str):
+            row["role"] = item["role"]
+        if isinstance(pointer, dict):
+            row["pointBack"] = {
+                "kind": pointer.get("kind") or "unknown",
+                "path": pointer.get("path"),
+                "note": pointer.get("note") or "",
+                "repairOwner": pointer.get("repairOwner") or "",
+            }
+        rows.append(row)
+    return rows
+
+
+def build_projection(
+    *,
+    run_id: str,
+    owner: str,
+    project_id: str | None,
+    runner: str,
+    entries: list[dict],
+    ledger_text: str | None,
+    findings: object = None,
+    generated_at: str | None = None,
+) -> dict:
+    """Assemble the projection document from owner-decided facts only."""
+    check_run_id(run_id)
+    check_owner(owner)
+    document: dict[str, object] = {
+        "version": PROJECTION_VERSION,
+        "runId": run_id,
+        "owner": owner,
+        "projectId": project_id,
+        "runner": runner,
+        "generatedAt": generated_at
+        or datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "evidence": evidence_rows(entries),
+        "criteria": criteria_rows(ledger_text or "", entries),
+        "findings": finding_rows(findings),
+    }
+    return document
+
+
+def projection_path(project_root: Path, run_id: str) -> Path:
+    """The one file this script may write."""
+    return project_root / PROJECTION_ROOT / check_run_id(run_id) / "projection.json"
+
+
+def publish(project_root: Path, run_id: str, document: dict) -> Path:
+    """Write the projection atomically; leave no partial file behind."""
+    target = projection_path(project_root, run_id)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    payload = json.dumps(document, ensure_ascii=False, indent=2) + "\n"
+    handle = tempfile.NamedTemporaryFile(
+        "w",
+        encoding="utf-8",
+        dir=target.parent,
+        prefix=".projection-",
+        suffix=".tmp",
+        delete=False,
+    )
+    try:
+        with handle:
+            handle.write(payload)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(handle.name, target)
+    except BaseException:
+        Path(handle.name).unlink(missing_ok=True)
+        raise
+    return target
+
+
+def _read_text(path: str) -> str:
+    return Path(path).read_text(encoding="utf-8")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="publish_owner_projection.py",
+        description=(
+            "Publish the typed owner projection the workbench reads (R12)."
+        ),
+    )
+    parser.add_argument("run_dir", help="The run root containing evidence/.")
+    parser.add_argument(
+        "--project-root", required=True, help="Target repository root."
+    )
+    parser.add_argument("--run-id", required=True)
+    parser.add_argument("--owner", required=True, help="Owner name (never invented).")
+    parser.add_argument("--ledger", required=True, help="Evaluator ledger text file.")
+    parser.add_argument("--findings", default=None, help="Optional findings JSON.")
+    parser.add_argument(
+        "--runner", default="", help="Owner runner description (optional)."
+    )
+    parser.add_argument(
+        "--project-id",
+        default=None,
+        help=(
+            "Workbench project id to bind. Omit when the workbench project is "
+            "not the owner's project id (the workbench then skips the check)."
+        ),
+    )
+    parser.add_argument(
+        "--stdout",
+        action="store_true",
+        help="Print the document instead of writing it (dry run).",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        run_dir = Path(args.run_dir)
+        entries = read_manifest(run_dir)
+        ledger_text = _read_text(args.ledger)
+        findings = (
+            json.loads(_read_text(args.findings)) if args.findings else None
+        )
+        document = build_projection(
+            run_id=args.run_id,
+            owner=args.owner,
+            project_id=args.project_id,
+            runner=args.runner,
+            entries=entries,
+            ledger_text=ledger_text,
+            findings=findings,
+        )
+        if args.stdout:
+            print(json.dumps(document, ensure_ascii=False, indent=2))
+            return 0
+        target = publish(Path(args.project_root), args.run_id, document)
+    except ProjectionPublishError as error:
+        print(f"publish_owner_projection: refused: {error}", file=sys.stderr)
+        return 2
+    except (OSError, json.JSONDecodeError) as error:
+        print(f"publish_owner_projection: {error}", file=sys.stderr)
+        return 3
+    print(
+        f"published {document['owner']} run {document['runId']} "
+        f"({len(document['criteria'])} criteria, "
+        f"{len(document['evidence'])} evidence) -> {target}"
+    )
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover - CLI entry
+    raise SystemExit(main())