design-playbook 0.24.3 → 0.25.0

package/codex/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- generated-by design-playbook v0.24.3 -->
+<!-- generated-by design-playbook v0.25.0 -->
 # design-playbook for Codex
 
 ## Install (path of record)

package/commands/component-distill.md

@@ -0,0 +1,8 @@
+---
+description: Cross-run component backflow — derive recurring components from iterated pages and render a propose-only DESIGN.md promotion proposal (report-only, user-gated)
+---
+
+Cross-run **component backflow** over `.scratch/<run>/` decision reports in the user project. Not a step of a single Design I/O run. Run skill **component-distill**. Proposal header **`component-distill/v1`**; report-only — never writes `DESIGN.md` or any authority; promotion is a user decision recorded in the governance log and executed only by `design_baseline.py promote`.
+
+Output path:
+$ARGUMENTS

package/cordis.patch.yml

@@ -0,0 +1,19 @@
+# design-playbook dsh bundle patch
+#
+# Mounts the design-playbook plugin (this package's lib/index.js), which
+# registers the bundled skills as a provider on ctx.skills. The plugin
+# locates its own skills/ directory via __dirname, so no path expression is
+# needed and no cwd-dependent resolution is involved.
+#
+# Note: the Cordis `!!js` evaluation scope provides no `require` (only Node
+# globals plus ctx-provided values like dshHomePath), so pointing a
+# skill-filesystem customSkillDirs row at package resources via
+# `require.resolve` does not work. The plugin route is the supported way for
+# a package to contribute its own skills.
+#
+# P2 (MCP + commands) will append rows here.
+
+- insert:
+    - id: design-playbook
+      name: 'design-playbook'
+      disabled: false

package/lib/index.js

@@ -8,8 +8,9 @@
  *    `skills/` directory. The plugin locates the directory via `__dirname`,
  *    so no `!!js` expression and no cwd-dependent resolution is involved.
  *
- * 2. Slash commands (ctx.commands) — `design-io`, `doctor`,
- *    `run-handoff`, `run-review`, `run-status`, `ui-review`, `ux-spec` —
+ * 2. Slash commands (ctx.commands) — `component-distill`, `design-io`,
+ *    `doctor`, `run-handoff`, `run-review`, `run-status`, `ui-review`,
+ *    `ux-spec` —
  *    that load the matching `commands/<name>.md` prompt, substitute
  *    `$ARGUMENTS` with the raw trailing input, and inject it as a
  *    user-role follow-up turn via `agent.followup()`.
@@ -87,6 +88,7 @@ exports.createUserMessageFromPrompt = createUserMessageFromPrompt
  * substituted) is injected as a user follow-up turn.
  */
 const COMMAND_NAMES = [
+  'component-distill',
   'design-io',
   'doctor',
   'run-handoff',

package/mcp/evidence/capture_runtime.py

@@ -110,6 +110,10 @@ def _failed(
     }
     if request is not None:
         payload["request"] = request
+    if written_path and _run_root_misrooted():
+        # Same misroot warning as the success payload: a failed write outside
+        # the run tree is exactly where the orchestrator needs the hint.
+        payload["warnings"] = [_MISROOTED_WARNING]
     return payload
 
 
@@ -138,6 +142,10 @@ def _captured(
         "written_path": written_path,
         "request": request,
     }
+    if _run_root_misrooted():
+        # The stderr warning fires once per process and may never reach the
+        # model; the payload is what the orchestrator actually reads.
+        payload["warnings"] = [_MISROOTED_WARNING]
     if probe_artifact:
         payload["probe_artifact"] = probe_artifact
     return payload
@@ -271,19 +279,38 @@ _RUN_MARKERS = ("plan.md", "point-back.md")
 _warned_run_root = False
 
 
+_MISROOTED_WARNING = (
+    "run root resolved to a markerless cwd (DESIGN_PLAYBOOK_RUN_ROOT "
+    "unset or '.'); written_path is outside the run tree — set "
+    "DESIGN_PLAYBOOK_RUN_ROOT to the run root (.scratch/<run>/) "
+    "before binding this artifact"
+)
+
+
+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.
+    """
+    configured = os.environ.get(RUN_ROOT_ENV)
+    if configured and configured != ".":
+        return False
+    root = Path.cwd().resolve()
+    return not any((root / marker).is_file() for marker in _RUN_MARKERS)
+
+
 def _run_root() -> Path:
     configured = os.environ.get(RUN_ROOT_ENV)
     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.
+        # 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
-        ):
+        if not _warned_run_root and _run_root_misrooted():
             _warned_run_root = True
             _log(
                 "WARNING: DESIGN_PLAYBOOK_RUN_ROOT is unset or '.' "

package/mcp/evidence/containment.py

@@ -23,6 +23,11 @@ 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.
 
+ADR-0044 adds the Diagnostic export write boundary as a third specialization:
+``trial_export_write_target`` confines one bare filename under
+``<run_root>/trial-export/`` (the trial-export subtree), with the same
+reason-code discipline and TOCTOU limit.
+
 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
@@ -50,6 +55,9 @@ REASON_RESOLUTION_FAILURE = "resolution_failure"
 REASON_CANONICAL_ESCAPE = "canonical_escape"
 REASON_SYMLINK_ESCAPE = "symlink_escape"
 REASON_NOT_REGULAR_FILE = "not_regular_file"
+# Trial-export targets (ADR-0044) accept bare filenames only; a name that
+# carries any separator or reserved form is rejected before resolution.
+REASON_RESERVED_NAME = "reserved_name"
 
 # Every resolution-time escape reason (the classes the ADR requires both
 # operations to reject at resolution time). The Provider treats all of these
@@ -203,3 +211,86 @@ def read_artifact(artifact_path: str, run_root: Path) -> ContainmentResult:
     must not bind a directory or a missing path).
     """
     return _resolve(artifact_path, run_root, require_existing_file=True)
+
+
+# The Diagnostic export write boundary (ADR-0044): one subtree, sibling of
+# evidence/, owned here so the export transaction cannot disagree with the
+# one containment authority on where trial exports may land.
+TRIAL_EXPORT_SUBDIR = "trial-export"
+
+# Names the export subtree may never carry. ``manifest.jsonl`` is reserved
+# across the run tree (the Evidence Manifest authority); the current-directory
+# name is a no-op write and is refused as malformed rather than silently
+# permitted.
+_TRIAL_EXPORT_RESERVED_NAMES = frozenset({"manifest.jsonl", "", ".", ".."})
+
+# Win32 name quirks that CreateFile folds but Path.resolve does not: a
+# trailing dot or space vanishes on write (the on-disk name would diverge
+# from the reviewed one), and the reserved device names are never regular
+# files. The export writes exactly the reviewed pair, so both classes are
+# rejected as reserved.
+_WIN32_DEVICE_NAMES = frozenset(
+    {"CON", "PRN", "AUX", "NUL",
+     *(f"COM{i}" for i in range(1, 10)),
+     *(f"LPT{i}" for i in range(1, 10))},
+)
+
+
+def trial_export_write_target(filename: str, run_root: Path) -> ContainmentResult:
+    """Resolve a Diagnostic export write target under ``trial-export/``.
+
+    ``filename`` must be a bare filename - no directory separators (native,
+    POSIX, or Windows), no drive form, no ``..`` segment, and not one of the
+    reserved names, Win32 fold forms (trailing dot or space), or reserved
+    device stems - anything the platform would write under a different name
+    than the one reviewed. Same resolution-time escape
+    rejection and TOCTOU limit as every operation in this module; the
+    transaction performs the staged write and rollback around this resolution.
+    """
+    if not isinstance(filename, str) or filename == "":
+        return ContainmentResult(None, REASON_RESERVED_NAME)
+    if filename in _TRIAL_EXPORT_RESERVED_NAMES:
+        return ContainmentResult(None, REASON_RESERVED_NAME)
+    # Bare-filename precondition: any separator, drive, or traversal form
+    # fails before the generic resolver can even see it.
+    if (
+        PurePosixPath(filename).is_absolute()
+        or PureWindowsPath(filename).is_absolute()
+        or "/" in filename
+        or "\\" in filename
+        or any(part == ".." for part in PurePosixPath(filename).parts)
+        or any(part == ".." for part in PureWindowsPath(filename).parts)
+        or ":" in filename
+    ):
+        return ContainmentResult(None, REASON_ABSOLUTE_PATH)
+    # Win32 fold classes: a trailing dot/space or a reserved device stem
+    # would make the on-disk name differ from the reviewed name.
+    if filename != filename.rstrip(" ."):
+        return ContainmentResult(None, REASON_RESERVED_NAME)
+    if filename.split(".", 1)[0].upper() in _WIN32_DEVICE_NAMES:
+        return ContainmentResult(None, REASON_RESERVED_NAME)
+    # The boundary subtree itself must be a real child of the run root: a
+    # ``trial-export`` symlink pointing outside the run root would make the
+    # generic under-boundary check pass while writing outside the selected
+    # run, so the resolved boundary is required to stay inside the resolved
+    # run root before anything else is resolved against it.
+    try:
+        resolved_root = run_root.resolve(strict=False)
+        boundary = (run_root / TRIAL_EXPORT_SUBDIR).resolve(strict=False)
+        Path(os.path.realpath(boundary)).relative_to(
+            Path(os.path.realpath(resolved_root))
+        )
+    except (OSError, ValueError):
+        return ContainmentResult(None, REASON_SYMLINK_ESCAPE)
+    result = _resolve_candidate(
+        run_root,
+        f"{TRIAL_EXPORT_SUBDIR}/{filename}",
+        run_root / TRIAL_EXPORT_SUBDIR,
+        require_existing_file=False,
+    )
+    # The generic resolver also folds "." segments; a name like "a/." or
+    # "a.." is a file name here, but a name that Path normalizes to
+    # something other than itself inside the subtree must not pass.
+    if result.ok and result.path is not None and result.path.name != filename:
+        return ContainmentResult(None, REASON_RESERVED_NAME)
+    return result

package/mcp/evidence/server.py

@@ -32,7 +32,8 @@ def _tool_schema() -> dict[str, Any]:
             "schemaVersion=1 plus explicit viewport, apply deterministic freeze "
             "by default, write one artifact (screenshot / a11y tree / "
             "interaction trace). Returns capture result only (artifact, "
-            "observed_state, result, error, written_path, request) — never "
+            "observed_state, result, error, written_path, request; plus a "
+            "warnings list when the run root looks misconfigured) — never "
             "writes manifest; never judges criteria."
         ),
         "inputSchema": {