design-playbook 0.24.0 → 0.24.2

package/codex/AGENTS.md

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

package/examples/dogfood/run/craft-guard.md

@@ -26,3 +26,6 @@ Registry: `skills/design-playbook/references/rules.md`, full catalog (P3 run:
 | DECIDE-01@1 | applicable | - | clear | 选中方向为全局 run console 构成重组（candidates/console-region.html 草图 + preview round 1/2 用户确认），非未审视的默认外观收敛 | DD-0001 理由可回溯 l1.scenes（切页续读）与 PERF-01 比较轴及经用户确认的布局段突破；DD-0002 理由可回溯 l6.c4（跨视图状态闭环）与运行中心第一步方向——均引用 brief 具体事实 | 常规方向经比较矩阵沿 brief 轴证成，非未审视默认；无基线默认方向身份声明 | - |
 
 注：2026-08-28 注册批（COPY-01/02/03、A11Y-02、CRAFT-09/10、DECIDE-01）晚于本 run 存档；按三态谓词补记——blocked 行在理由列点名缺失的证据面；DECIDE-01 依归档内可读的决策报告求值为 applicable。
+| STATE-01@1 | applicable | - | clear | 运行 feed 条目级进度持续更新（进行中项逐条指名） | Fill 声明条目级进度 + evidence 进度语义 | - | - |
+| STATE-02@1 | applicable | - | clear | 「无运行时 feed 不渲染」为 spec 声明边界：无 feed 时控制台不呈现空集合区 | Fill 声明边界条目（L 边界对齐） | 例外成立——空呈现即 spec 声明的产品行为 | - |
+| STATE-03@1 | applicable | - | clear | 暂停失败 toast（role=alert）+ 失败项保留并支持圈选批量重试 | Fill 声明（失败 toast + 批量重试操作条） | - | - |

package/examples/export-entry/run/craft-guard.md

@@ -26,3 +26,6 @@ Registry: `skills/design-playbook/references/rules.md`, full catalog (P2 run). S
 | DECIDE-01@1 | applicable | - | clear | 选中方向为按周命名模式（compare 档轻量比较），不落入 2026-08 记录的自默认外观样貌；DD-0001 为 record 档，不在本规则范围 | DD-0002 理由可回溯 l1.target_user 比较轴（周频归档场景下检索是主任务）——引用 brief 具体事实而非通用措辞 | 常规方向经比较矩阵沿 brief 轴证成，非未审视默认；无基线默认方向身份声明 | - |
 
 注：2026-08-28 注册批（COPY-01/02/03、A11Y-02、CRAFT-09/10、DECIDE-01）晚于本 run 存档；按三态谓词补记——blocked 行在理由列点名缺失的证据面；DECIDE-01 依归档内可读的决策报告求值为 applicable。
+| STATE-01@1 | applicable | - | clear | 批量导出触发钮 busy/disabled 守卫（控件自身标签即操作名，pending 区域限于触发钮） | Fill 声明 busy state while exporting + busy/disabled guard | 单帧完成例外不成立（批量导出为长操作） | - |
+| STATE-02@1 | blocked | 静态夹具无数据源，首载空/筛选空均不可达 | - | 表格列表区声明在场，空态分支缺席 | 无数据源可供触发空态 | - | 接入数据面后补评首载空与筛选空呈现 |
+| STATE-03@1 | applicable | - | clear | cap 上限 toast（role=alert + 可读名称含上限值） | Fill 声明 toast 承载上限拒绝 | 上限拒绝为失败路径的可恢复呈现（出口=调整范围后再导出） | - |

package/examples/export-pointfix-upgrade/run/craft-guard.md

@@ -26,3 +26,6 @@ Registry: `skills/design-playbook/references/rules.md`. Seven-column rows; after
 | DECIDE-01@1 | not-applicable | 决策报告仅含 record 档 DD-0101，无 compare/explore 档方向决策条目 | - | - | - | - | - |
 
 注：2026-08-28 注册批（COPY-01/02/03、A11Y-02、CRAFT-09/10、DECIDE-01）晚于本 run 存档；按三态谓词补记，blocked 行在理由列记缺失证据面。
+| STATE-01@1 | applicable | - | clear | 导出触发钮 busy/disabled 守卫（自前次 run 保留） | Fill 声明 busy/disabled guard 保留 | 单帧完成例外不成立 | - |
+| STATE-02@1 | applicable | - | clear | 空数据集预检：数据集为空时触发钮禁用 + toast「无可选行」（指名原因） | Fill 声明 empty-blocked pre-check（R4 修复） | 例外不成立——空数据呈现明确指名原因与出口 | - |
+| STATE-03@1 | applicable | - | clear | cap 上限 toast（自前次 run 保留，role=alert） | Fill 声明 cap-limit toast 保留 | - | - |

package/examples/export-upgrade/run/craft-guard.md

@@ -26,3 +26,6 @@ Registry: `skills/design-playbook/references/rules.md`, full catalog (P3 run:
 | DECIDE-01@1 | applicable | - | clear | 选中方向为启用既有 status region 收纳导出任务（candidates/B.html 草图 + preview round 1/2 用户确认），非未审视的默认外观收敛 | DD-0003 理由可回溯 l1.scenes（导出中切页全局可查）与 PERF-01 比较轴；DD-0004 理由可回溯 l6.c2（跨视图状态闭环）与基线 status region 惯例声明——均引用 brief 具体事实 | 常规方向经比较矩阵沿 brief 轴证成，非未审视默认；基线声明的是 status region 惯例而非默认外观身份 | - |
 
 注：2026-08-28 注册批（COPY-01/02/03、A11Y-02、CRAFT-09/10、DECIDE-01）晚于本 run 存档；按三态谓词补记——blocked 行在理由列点名缺失的证据面；DECIDE-01 依归档内可读的决策报告求值为 applicable。
+| STATE-01@1 | applicable | - | clear | 长导出条目级进度持续更新（30s 窗口 5 次采样） | evidence/L6.1-status-trace.json 进度采样序列 | - | - |
+| STATE-02@1 | blocked | 候选页为静态导出面，无数据供给集合面，空态不可达 | - | 无空态分支呈现 | 无数据源 | - | 接入数据面后补评 |
+| STATE-03@1 | not-applicable | 本 run 升档面未声明异步失败路径（进度轨迹为唯一运行时面） | - | - | 候选页无可触发失败分支 | - | - |

package/mcp/run_console/http_server.py

@@ -139,6 +139,29 @@ class RunConsoleRequestHandler(http.server.BaseHTTPRequestHandler):
     def log_message(self, format: str, *args: object) -> None:
         """Never log: no URL, token, or locator may reach any log."""
 
+    def finish(self) -> None:
+        """Graceful teardown: half-close, drain, then close.
+
+        A client body left unread in the receive buffer (e.g. a POST whose
+        Content-Length is absent: the stray bytes parse as garbage request
+        lines and the connection must die) turns a plain close() into a TCP
+        reset on Windows — the client gets WinError 10053 mid-read instead
+        of the response it was sent.  Flush the response, half-close (FIN),
+        drain the peer's remaining bytes, then close, so teardown is never
+        a reset.
+        """
+        super().finish()
+        try:
+            self.connection.shutdown(socket.SHUT_WR)
+        except OSError:
+            pass
+        try:
+            self.connection.settimeout(0.2)
+            while self.connection.recv(65536):
+                pass
+        except OSError:
+            pass
+
     # -- dispatch ------------------------------------------------------
 
     def do_GET(self) -> None:  # noqa: N802

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "design-playbook",
-  "version": "0.24.0",
+  "version": "0.24.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/scripts/adapter_matrix.py

@@ -115,6 +115,16 @@ _TIER2: tuple[AgentRow, ...] = (
         skills=False,
         rules_target=".github/copilot-instructions.md",
     ),
+    AgentRow(
+        agent="zed",
+        tier=2,
+        rules=True,
+        commands=False,
+        mcp_project=True,
+        hooks=False,
+        skills=False,
+        rules_target=".rules + .zed/settings.json",
+    ),
 )
 
 # Tier 3 — rules floor (generated AGENTS.md + inline MCP guide).

package/scripts/context_budget.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Context budget for design-playbook skills (report-only).
+
+Walks ``skills/*/SKILL.md`` and ``skills/*/references/*.md`` under the
+package root and reports the context weight of the skill surface: the
+always-loaded SKILL.md face per skill, its on-demand references, and the
+worst-case full-pipeline total. Purely informational — no thresholds, no
+gates, no writes, no network.
+
+Token counts are character-level estimates, never tokenizer-exact:
+``ascii_chars / 4 + non_ascii_chars`` (CJK prose runs near one token per
+character; every output carries ``estimate: true``).
+
+Usage:
+  python scripts/context_budget.py            # text view (package root)
+  python scripts/context_budget.py --json     # machine view
+  python scripts/context_budget.py --root <package-root> --top 5
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+_PACKAGE_ROOT = Path(__file__).resolve().parent.parent
+
+_ESTIMATE_NOTE = (
+    "token counts are character-level estimates: ascii/4 + non-ascii chars; "
+    "not tokenizer-exact"
+)
+
+
+def estimate_tokens(text: str) -> int:
+    """Character-level estimate (see module docstring)."""
+    non_ascii = sum(1 for ch in text if ord(ch) > 127)
+    return (len(text) - non_ascii) // 4 + non_ascii
+
+
+def _measure_file(path: Path) -> dict:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    chars = len(text)
+    return {
+        "path": path.name,
+        "chars": chars,
+        "tokens_est": estimate_tokens(text),
+    }
+
+
+def measure_skills(package_root: Path) -> dict:
+    """Measure the whole skill surface under *package_root*. Read-only."""
+    skills_dir = package_root / "skills"
+    skills: list[dict] = []
+    for skill_dir in sorted(p for p in skills_dir.iterdir() if p.is_dir()):
+        skill_file = skill_dir / "SKILL.md"
+        if not skill_file.is_file():
+            continue
+        skill = {
+            "skill": skill_dir.name,
+            "skill_md": _measure_file(skill_file),
+            "references": [
+                _measure_file(p) for p in sorted((skill_dir / "references").glob("*.md"))
+            ],
+        }
+        skill["references_tokens_est"] = sum(
+            ref["tokens_est"] for ref in skill["references"]
+        )
+        skill["skill_tokens_est"] = skill["skill_md"]["tokens_est"]
+        skill["total_tokens_est"] = (
+            skill["skill_tokens_est"] + skill["references_tokens_est"]
+        )
+        skills.append(skill)
+
+    all_files = [
+        {"skill": s["skill"], **ref}
+        for s in skills
+        for ref in s["references"]
+    ] + [{"skill": s["skill"], **s["skill_md"]} for s in skills]
+    heaviest = sorted(all_files, key=lambda f: f["tokens_est"], reverse=True)
+
+    return {
+        "estimate": True,
+        "estimate_note": _ESTIMATE_NOTE,
+        "skills": skills,
+        "total": {
+            "skill_md_tokens_est": sum(s["skill_tokens_est"] for s in skills),
+            "references_tokens_est": sum(s["references_tokens_est"] for s in skills),
+            "worst_case_pipeline_tokens_est": sum(s["total_tokens_est"] for s in skills),
+        },
+        "heaviest_files": heaviest[:10],
+    }
+
+
+def _text_view(report: dict) -> str:
+    lines = [
+        "context budget (estimate: %s)" % report["estimate"],
+        report["estimate_note"],
+        "",
+        f"{'skill':<18} {'skill.md':>10} {'refs':>10} {'total':>10}",
+    ]
+    for s in report["skills"]:
+        lines.append(
+            f"{s['skill']:<18} {s['skill_tokens_est']:>10} "
+            f"{s['references_tokens_est']:>10} {s['total_tokens_est']:>10}"
+        )
+    t = report["total"]
+    lines += [
+        "",
+        f"{'TOTAL':<18} {t['skill_md_tokens_est']:>10} "
+        f"{t['references_tokens_est']:>10} "
+        f"{t['worst_case_pipeline_tokens_est']:>10}",
+        "",
+        "heaviest files (tokens_est):",
+    ]
+    for f in report["heaviest_files"]:
+        lines.append(f"  {f['tokens_est']:>8}  {f['skill']}/{f['path']}")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="context_budget",
+        description="Report the context weight of the skill surface (report-only).",
+    )
+    parser.add_argument(
+        "--root",
+        default=str(_PACKAGE_ROOT),
+        help="package root holding skills/ (default: this package)",
+    )
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+    parser.add_argument("--top", type=int, default=10, metavar="N",
+                        help="heaviest-file list length (default 10)")
+    args = parser.parse_args(argv)
+
+    root = Path(args.root).resolve()
+    report = measure_skills(root)
+    report["heaviest_files"] = report["heaviest_files"][: max(args.top, 0)]
+
+    if args.json:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+    else:
+        print(_text_view(report))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/doctor.py

@@ -59,6 +59,7 @@ _ORPHAN_SCAN_DIRS: dict[str, tuple[str, ...]] = {
     "gemini-cli": (".gemini/commands",),
     "windsurf": (".windsurf/rules", ".windsurf/workflows"),
     "github-copilot": (".github/instructions",),
+    "zed": (".zed",),
 }
 # Whole-file candidates carrying the generated-by marker outside namespaced
 # dirs (marker-block targets are always re-rendered in place, so they are
@@ -68,6 +69,7 @@ _WHOLE_FILE_CANDIDATES = (
     "GEMINI.md",
     ".github/copilot-instructions.md",
     "design-playbook-mcp-setup.md",
+    ".rules",
 )
 
 _LIMITATIONS = (

package/scripts/generate_adapter.py

@@ -649,6 +649,60 @@ def _agents_md_floor_files(version: str, out_dir: Path) -> list[tuple[str, str]]
     return [_marker_entry(out_dir, "AGENTS.md", version, "".join(block_parts))]
 
 
+# ---------------------------------------------------------------------------
+# Zed renderer (Tier 2)
+# ---------------------------------------------------------------------------
+
+# Zed reads project-root rules via a first-match priority list with `.rules`
+# on top, then `.cursorrules`, `.windsurfrules`, `.clinerules`,
+# `.github/copilot-instructions.md`, `CLAUDE.md`, `AGENTS.md`, … (zed.dev
+# agent rules docs, fetched 2026-09-19).  Creating `.rules` when a
+# lower-priority competitor exists would silently shadow the user's own
+# rules, so the renderer refuses to introduce one into that state.
+_ZED_RULES_COMPETITORS = (
+    ".cursorrules",
+    ".windsurfrules",
+    ".clinerules",
+    "CLAUDE.md",
+    ".github/copilot-instructions.md",
+)
+
+
+def _zed_files(version: str, out_dir: Path) -> list[tuple[str, str]]:
+    files: list[tuple[str, str]] = []
+    skills = _read_skills()
+
+    # `.rules` — marker-block (may pre-exist).  Skip creating a *new* `.rules`
+    # while a documented lower-priority competitor is present; an existing
+    # `.rules` (ours or the user's) takes refresh/append semantics instead,
+    # since Zed already reads that exact file.
+    rules_existing = _existing_text(out_dir, ".rules")
+    if rules_existing is not None or not any(
+        (out_dir / c).exists() for c in _ZED_RULES_COMPETITORS
+    ):
+        block_parts = _digest_head(skills)
+        files.append(_marker_entry(out_dir, ".rules", version, "".join(block_parts)))
+
+    # .zed/settings.json — merge-safe context_servers (project-level MCP).
+    # Official docs (fetched 2026-09-19) document the stdio entry as
+    # {"command": "…", "args": […], "env": {…}}; community examples also show
+    # an object form ({"command": {"path": …, "args": […]}}) — the string
+    # form is pinned here per the official page, and the merge keeps any
+    # user-managed entries verbatim.
+    mcp_servers = _mcp_servers_abs()
+    zed_servers: dict = {}
+    for name, srv in mcp_servers.items():
+        entry: dict = {"command": srv["command"], "args": srv["args"]}
+        if "env" in srv and any(v for v in srv["env"].values()):
+            entry["env"] = srv["env"]
+        zed_servers[name] = entry
+    files.append(
+        _merge_json_entry(out_dir, ".zed/settings.json", {"context_servers": zed_servers})
+    )
+
+    return files
+
+
 # ---------------------------------------------------------------------------
 # Renderer dispatch
 # ---------------------------------------------------------------------------
@@ -664,6 +718,7 @@ _SPECIALIZED_RENDERERS: dict[str, Renderer] = {
     "opencode": _opencode_files,
     "windsurf": _windsurf_files,
     "github-copilot": _github_copilot_files,
+    "zed": _zed_files,
 }
 
 

package/skills/craft-guard/references/detectors.md

@@ -1,6 +1,6 @@
 # Craft audit protocol (registry reference layer)
 
-The craft detectors live in the first-party rule registry: [`../../design-playbook/references/rules.md`](../../design-playbook/references/rules.md) (`CRAFT-01` … `CRAFT-08`, all `advisory` / `first-party`, plus the cross-cutting `A11Y-01`, `RESP-01`, and the placeholder `I18N-01`, `PERF-01`, `SEC-01` entries). This file is the thin execution reference: how to evaluate an entry's applicability predicate and how to write its audit row. The registry is the single authority for detector definitions — do not duplicate entry text here.
+The craft detectors live in the first-party rule registry: [`../../design-playbook/references/rules.md`](../../design-playbook/references/rules.md). The registry is the single authority for entry definitions — this file never enumerates or summarizes entries (enumerations here have drifted before; read the registry for the current set, families, statuses, and provenance). This file is the thin execution reference: how to evaluate an entry's applicability predicate and how to write its audit row.
 
 Run every registry craft entry whose applicability predicate evaluates to `applicable` for implemented UI. Inspect rendered UI at declared target viewports and relevant source. Generic registry outcomes never override a verified project baseline; safety, usability, and explicit declarations still do.
 

package/skills/design-playbook/references/rules.md

@@ -607,3 +607,93 @@ fix: answer the self-check inside the DD rationale with brief facts, add at leas
 related:
 history: 1 | 2026-08-28 | docs | initial registry registration, first-party decision-hygiene entry; default-direction examples recorded as dated, refreshable observations (2026-08, dogfood evidence)
 ```
+
+## STATE-01 — Pending feedback
+
+```yaml
+id: STATE-01
+version: 1
+title: Pending feedback
+statement: Asynchronous triggers and data-loading regions present pending feedback that names the operation while it runs (observable); a silent trigger or a bare anonymous spinner leaves users guessing whether the action registered and whether waiting is safe (user impact).
+capability-domain: D4
+executes-in: D4:cross-cutting
+authority: advisory-aesthetic
+applicability-applicable: run has Fill output and the surface contains asynchronous triggers or data-loading regions (form submits, fetch-driven lists, uploads)
+applicability-not-applicable: planning-only run, or every visible operation completes synchronously within the interaction (observable reason required)
+applicability-blocked: pending states cannot be reached or captured with the available evidence surface
+check-type: protocol-check
+check-inputs: rendered pending states per asynchronous path; source request and state handling that gates the pending branch
+signals-rendered: an asynchronous trigger with no visible pending feedback; a pending region that does not name what is loading or processing (a page-wide bare spinner covering one field's request)
+signals-source: request handling with no pending branch bound to a rendered region; a pending flag consumed by nothing visible
+evidence-layers: rendered>=1, source>=1
+evidence-method: expert-review
+severity-default: S2 / fact
+exceptions: operations that complete and surface their result within a single frame on the audited device (the pending state would only flash); background prefetch not tied to a visible user task
+false-positives: progress already carried by a dedicated inline region that names the operation; a verified baseline prescribing silent local mutations
+owner: craft -> R4
+provenance: benchmark-input-only
+status: advisory
+fix: bind each asynchronous path to a pending region that names the operation, keep it scoped to the region it concerns, and resolve it deterministically into the result or failure state (PERF-01 covers the pacing of the feedback itself)
+related: PERF-01@1
+history: 1 | 2026-09-19 | docs | initial registry registration, benchmark-informed state-completeness entry in first-party wording
+```
+
+## STATE-02 — Zero-data presentation
+
+```yaml
+id: STATE-02
+version: 1
+title: Zero-data presentation
+statement: Data-fed collection surfaces declare what users see when the list is empty on first load and after filtering (observable); a blank region forces users to guess whether data is still loading, absent, or broken, and hides the next action (user impact).
+capability-domain: D4
+executes-in: D4:cross-cutting
+authority: advisory-aesthetic
+applicability-applicable: run has Fill output and the surface contains a collection or list display fed by data
+applicability-not-applicable: planning-only run, or no data-fed collection display in the audited scope (observable reason required)
+applicability-blocked: empty states cannot be reached or captured with the available evidence surface
+check-type: protocol-check
+check-inputs: rendered first-load-empty and filtered-empty presentations; source empty-branch handling for the collection's data source
+signals-rendered: the collection region renders with no content and no hint while its data is empty; an empty presentation that offers no next action or explanation
+signals-source: empty-result branches that render no region content; a data source with an empty path unhandled in the UI layer
+evidence-layers: rendered>=1, source>=1
+evidence-method: expert-review
+severity-default: S2 / fact
+exceptions: create-first surfaces whose documented initial state is intentionally the empty canvas itself; the empty presentation is the specified product behavior (spec or verified baseline)
+false-positives: a populated skeleton resolving within the declared loading flow (judged under STATE-01, not here)
+owner: craft -> R4
+provenance: benchmark-input-only
+status: advisory
+fix: give every data-fed collection an explicit empty presentation that says what the region is for and offers the next action, visually distinct from the pending presentation (STATE-01) and from failure feedback (STATE-03)
+related: STATE-01@1, STATE-03@1
+history: 1 | 2026-09-19 | docs | initial registry registration, benchmark-informed state-completeness entry in first-party wording
+```
+
+## STATE-03 — Failure feedback
+
+```yaml
+id: STATE-03
+version: 1
+title: Failure feedback
+statement: Failed asynchronous paths present recoverable feedback that names what failed and the next action — retry, undo, or exit — instead of failing silently to the console or surfacing a raw exception trace (observable); users stranded at a failure without a recovery path abandon the flow or retrigger the damage (user impact).
+capability-domain: D4
+executes-in: D4:cross-cutting
+authority: advisory-aesthetic
+applicability-applicable: run has Fill output and the audited scope declares or triggers failure paths for asynchronous operations
+applicability-not-applicable: run has no asynchronous failure path in the audited scope (observable reason required)
+applicability-blocked: failure states cannot be reached or captured with the available evidence surface
+check-type: protocol-check
+check-inputs: rendered failure states per asynchronous failure path; source error handling bound to request or mutation paths
+signals-rendered: an asynchronous action fails with no rendered feedback beyond the previous state; a raw exception or stack trace rendered to the user; a failure banner offering no retry, undo, or exit action
+signals-source: error branches that only log to the console; a catch path with no bound rendered region or recovery action
+evidence-layers: rendered>=1, source>=1
+evidence-method: expert-review
+severity-default: S2 / fact
+exceptions: diagnostic or operator surfaces where raw detail is the declared point (spec L1 or verified baseline); security-sensitive withholdings — still state what the user can do next even when the cause is withheld
+false-positives: failure feedback deferred by a declared retry policy that still lands in a rendered recovery state; terse diagnostics for a declared expert audience (spec L1)
+owner: craft -> R4
+provenance: benchmark-input-only
+status: advisory
+fix: bind each failure path to a rendered recovery region naming what failed where safe and what to do next, with retry or exit always present; keep the tone even (COPY-03 covers the message wording)
+related: COPY-03@1, STATE-01@1
+history: 1 | 2026-09-19 | docs | initial registry registration, benchmark-informed state-completeness entry in first-party wording
+```