design-playbook 0.23.0 → 0.24.0

package/codex/AGENTS.md

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

package/package.json

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

@@ -3,6 +3,9 @@
 
 Runs against the installed plugin package root (this file's grandparents),
 not the monorepo. Reports capability level and concrete repairs.
+
+Also reports drifted ``npx design-playbook init <agent>`` artifacts in the
+target repository (report-only; the refresh action is re-running init).
 """
 from __future__ import annotations
 
@@ -10,6 +13,7 @@ import argparse
 import importlib.util
 import json
 import os
+import re
 import sys
 from pathlib import Path
 
@@ -21,6 +25,8 @@ from design_playbook.scripts.audit_preferences import (  # noqa: E402
     effective_plan,
     resolve_preferences,
 )
+from design_playbook.scripts.adapter_matrix import MATRIX  # noqa: E402
+from design_playbook.scripts.generate_adapter import render_entries  # noqa: E402
 
 LEVELS = ("ok", "degraded", "broken")
 
@@ -35,6 +41,237 @@ def _check(name: str, ok: bool, repair: str, *, required: bool = True) -> dict:
     }
 
 
+# ---------------------------------------------------------------------------
+# Adapter lifecycle (CONTEXT.md "Adapter lifecycle check", 2026-09-19).
+# Report-only: drift means re-running `npx design-playbook init <agent>` with
+# the installed package would change the file. Never writes; never blocks.
+# ---------------------------------------------------------------------------
+
+_MARKER_RE = re.compile(r"generated-by design-playbook v(\d[^\s\"']*)")
+_MARKER_NORM_RE = re.compile(r"generated-by design-playbook v\d[^\s\"']*")
+
+# Namespaced output roots that can hold orphaned generated files, per agent.
+# Kept honest by tests/test_adapter_lifecycle.py: every non-native agent's
+# fresh init must be discovered through this map plus _WHOLE_FILE_CANDIDATES.
+_ORPHAN_SCAN_DIRS: dict[str, tuple[str, ...]] = {
+    "codex": (".codex-plugin", "codex"),
+    "cursor": (".cursor/rules",),
+    "gemini-cli": (".gemini/commands",),
+    "windsurf": (".windsurf/rules", ".windsurf/workflows"),
+    "github-copilot": (".github/instructions",),
+}
+# Whole-file candidates carrying the generated-by marker outside namespaced
+# dirs (marker-block targets are always re-rendered in place, so they are
+# discovered here rather than via orphan scanning).
+_WHOLE_FILE_CANDIDATES = (
+    "AGENTS.md",
+    "GEMINI.md",
+    ".github/copilot-instructions.md",
+    "design-playbook-mcp-setup.md",
+)
+
+_LIMITATIONS = (
+    "marker-less JSON merge targets (.mcp.json, opencode.json, "
+    "settings.json) are never attributed; re-init may still merge into them"
+)
+
+
+def _read_text_safe(path: Path) -> str | None:
+    try:
+        return path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+
+
+def _normalize_generation(text: str) -> str:
+    """Marker-version and CRLF normalization for byte comparison."""
+    return _MARKER_NORM_RE.sub(
+        "generated-by design-playbook vNORM", text.replace("\r\n", "\n")
+    )
+
+
+def _iter_orphan_candidates(repo_root: Path):
+    """Yield (agent, path, rel) for every file under a namespaced output
+    root — the single walk behind both the discovery gate and the orphan
+    scan, so _ORPHAN_SCAN_DIRS has exactly one interpretation."""
+    for agent, dirs in _ORPHAN_SCAN_DIRS.items():
+        for d in dirs:
+            base = repo_root / d
+            if not base.is_dir():
+                continue
+            for f in sorted(base.iterdir()):
+                if f.is_file():
+                    yield agent, f, f.relative_to(repo_root).as_posix()
+
+
+def _lifecycle_findings(repo_root: Path, package_version: str | None) -> dict:
+    """Classify generated init artifacts under *repo_root*. Read-only and
+    fail-open per agent: a renderer that cannot compute content (malformed
+    JSON merge target, undecodable marker file) degrades to a render_error
+    finding instead of crashing the doctor report.
+
+    Only files carrying the generated-by marker are judged; marker-less
+    files (user-authored content, marker-less JSON merge targets) are never
+    attributed — an unreadable file counts as unattributed for the same
+    reason (it cannot be judged as ours).
+    """
+    files: list[dict] = []
+    counts = {
+        "drifted": 0,
+        "orphaned": 0,
+        "clean": 0,
+        "absent": 0,
+        "unattributed": 0,
+        "render_error": 0,
+    }
+
+    def record(agent: str, rel: str, cls: str, marker_version: str | None = None) -> None:
+        counts[cls] += 1
+        if cls in ("drifted", "orphaned"):
+            files.append({
+                "agent": agent,
+                "path": rel,
+                "cls": cls,
+                "marker_version": marker_version,
+                "repair": (
+                    f"npx design-playbook init {agent}"
+                    if cls == "drifted"
+                    else f"delete {rel} then npx design-playbook init {agent}"
+                ),
+            })
+
+    # Discovery gate: without any generated-by marker anywhere there is
+    # nothing to attribute — skip the per-agent renders entirely. One walk
+    # over the namespaced roots feeds both this gate and the orphan scan.
+    orphan_candidates = list(_iter_orphan_candidates(repo_root))
+    discovered = False
+    for rel in _WHOLE_FILE_CANDIDATES:
+        text = _read_text_safe(repo_root / rel)
+        if text is not None and _MARKER_RE.search(text):
+            discovered = True
+            break
+    if not discovered:
+        for _agent, path, _rel in orphan_candidates:
+            text = _read_text_safe(path)
+            if text is not None and _MARKER_RE.search(text):
+                discovered = True
+                break
+    if not discovered:
+        return {
+            "status": "not-initialized",
+            "counts": counts,
+            "files": [],
+            "package_version": package_version,
+            "limitations": _LIMITATIONS,
+        }
+
+    # One render pass over all non-native agents, grouped by target path.
+    # AGENTS.md is a shared target (opencode + every tier-3 floor agent), so
+    # a file is clean when it matches ANY current candidate render; drift is
+    # "matches no current renderer", never "differs from one agent's render".
+    renders: dict[str, list[tuple[str, str]]] = {}
+    rendered_by_agent: dict[str, set[str]] = {}
+    render_failed: set[str] = set()
+    for row in MATRIX:
+        if row.native:
+            continue
+        try:
+            _version, _out_dir, entries = render_entries(row.agent, repo_root)
+        except (ValueError, OSError) as exc:
+            # Fail-loud renderer inputs (malformed merge JSON, undecodable
+            # marker file) degrade to a finding; the other agents still
+            # classify and the doctor keeps reporting. No rendered set means
+            # the orphan scan must skip this agent too — flagging its
+            # marker'd files orphaned would be a false positive.
+            counts["render_error"] += 1
+            render_failed.add(row.agent)
+            files.append({
+                "agent": row.agent,
+                "path": None,
+                "cls": "render_error",
+                "marker_version": None,
+                "reason": str(exc),
+                "repair": (
+                    f"fix or remove the unreadable config, then "
+                    f"npx design-playbook init {row.agent}"
+                ),
+            })
+            continue
+        rendered_by_agent[row.agent] = {rel for rel, _content in entries}
+        for rel, content in entries:
+            renders.setdefault(rel, []).append((row.agent, content))
+
+    for rel in sorted(renders):
+        candidates = renders[rel]
+        path = repo_root / rel
+        if not path.is_file():
+            counts["absent"] += 1
+            continue
+        actual = _read_text_safe(path)
+        m = _MARKER_RE.search(actual) if actual is not None else None
+        if m is None:
+            counts["unattributed"] += 1
+            continue
+        if any(
+            _normalize_generation(content) == _normalize_generation(actual)
+            for _agent, content in candidates
+        ):
+            counts["clean"] += 1
+            continue
+        agents = [agent for agent, _content in candidates]
+        if len(agents) == 1:
+            agent: str | None = agents[0]
+            repair = f"npx design-playbook init {agent}"
+        else:
+            agent = None
+            repair = (
+                f"npx design-playbook init <your-agent> "
+                f"({rel} is shared by: {', '.join(agents)})"
+            )
+        counts["drifted"] += 1
+        files.append({
+            "agent": agent,
+            "path": rel,
+            "cls": "drifted",
+            "marker_version": m.group(1),
+            "repair": repair,
+        })
+
+    for agent, path, rel in orphan_candidates:
+        if agent in render_failed or rel in rendered_by_agent.get(agent, set()):
+            continue
+        text = _read_text_safe(path)
+        m = _MARKER_RE.search(text) if text is not None else None
+        if m is not None:
+            record(agent, rel, "orphaned", m.group(1))
+
+    return {
+        "status": "scanned",
+        "counts": counts,
+        "files": files,
+        "package_version": package_version,
+        "limitations": _LIMITATIONS,
+    }
+
+
+def _adapter_lifecycle_check(repo_root: Path, package_version: str | None) -> dict:
+    report = _lifecycle_findings(repo_root, package_version)
+    findings = report["files"]
+    return {
+        "name": "adapter_lifecycle",
+        "ok": not findings,
+        "required": False,
+        "repair": (
+            "Refresh drifted init artifacts: "
+            + "; ".join(dict.fromkeys(f["repair"] for f in findings))
+            if findings
+            else ""
+        ),
+        "level": "degraded" if findings else "ok",
+        "detail": report,
+    }
+
+
 def run_checks(
     *,
     run_root: str | None = None,
@@ -114,6 +351,10 @@ def run_checks(
             required=False,
         ))
 
+    # Unconditional: a nonexistent root classifies as not-initialized rather
+    # than omitting the check entirely (uniform skip entry).
+    checks.append(_adapter_lifecycle_check(preference_root, version))
+
     # Optional: Playwright for evidence capture.
     playwright_ok = importlib.util.find_spec("playwright") is not None
     checks.append(_check(

package/scripts/generate_adapter.py

@@ -679,18 +679,19 @@ def _renderer_for(row: AgentRow) -> Renderer | None:
     return _SPECIALIZED_RENDERERS.get(row.agent, _agents_md_floor_files)
 
 
-def render(agent: str, out_dir: Path | None = None, *, dry_run: bool = False) -> dict:
-    """Render adapter artifacts for *agent*. Returns the manifest dict.
-
-    When *dry_run* is True, no files are written.
-    Tier-1 agents default out_dir to PKG; Tier-2/3 default to cwd.
+def render_entries(
+    agent: str, out_dir: Path | None = None
+) -> tuple[str, Path, list[tuple[str, str]]]:
+    """Read-only seam: ``(version, out_dir, [(rel, content)])`` for *agent*.
+
+    Resolves the identical renderer path as render() but never touches the
+    filesystem — the single read seam behind the doctor adapter-lifecycle
+    check (CONTEXT.md "Adapter lifecycle check", 2026-09-19).
     """
     row = get_agent(agent)
     if row is None:
         raise ValueError(f"unknown agent: {agent!r}")
 
-    version = _get_version()
-
     renderer = _renderer_for(row)
     if renderer is None:
         raise NotImplementedError(
@@ -701,7 +702,17 @@ def render(agent: str, out_dir: Path | None = None, *, dry_run: bool = False) ->
     if out_dir is None:
         out_dir = _PKG_DIR if row.tier == 1 else Path.cwd()
 
-    files = renderer(version, out_dir)
+    version = _get_version()
+    return version, out_dir, renderer(version, out_dir)
+
+
+def render(agent: str, out_dir: Path | None = None, *, dry_run: bool = False) -> dict:
+    """Render adapter artifacts for *agent*. Returns the manifest dict.
+
+    When *dry_run* is True, no files are written.
+    Tier-1 agents default out_dir to PKG; Tier-2/3 default to cwd.
+    """
+    version, out_dir, files = render_entries(agent, out_dir)
 
     manifest = {
         "agent": agent,