design-playbook 0.22.1 → 0.22.2

package/codex/AGENTS.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "design-playbook",
-  "version": "0.22.1",
+  "version": "0.22.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/run_facts.py

@@ -81,6 +81,9 @@ class RunFacts:
     shaping_events: tuple[dict[str, Any], ...] | None = None
     shaping_error: str | None = None
     _artifact_states: tuple[tuple[str, str], ...] = ()
+    # fill: lines inside fenced blocks are ignored by declaration parsing;
+    # kept as a fact so run-status can name them instead of hiding the skip.
+    fenced_fill_declarations: tuple[str, ...] = ()
 
     @property
     def manifest_entries(self) -> tuple[dict[str, Any], ...]:
@@ -231,20 +234,36 @@ def _existing_paths(run_root: Path | None) -> frozenset[str]:
     return frozenset(paths)
 
 
-def _plan_fill_declarations(plan_text: str) -> tuple[str, ...]:
-    """Capture every unfenced plan Fill token without checking filesystem state."""
+def _scan_fill_declarations(
+    plan_text: str,
+) -> tuple[tuple[str, ...], tuple[str, ...]]:
+    """Split column-0 ``fill:`` lines into (declared, ignored-inside-fences).
+
+    Declarations inside fenced blocks are a misdeclaration the plan author
+    must fix, not a silent skip: the second tuple feeds the run-status
+    diagnostic that names them and states the column-0 unfenced rule.
+    """
     found: list[str] = []
+    ignored: list[str] = []
     fenced = False
     for line in plan_text.splitlines():
         if line.lstrip().startswith("```"):
             fenced = not fenced
             continue
-        if fenced or not line.startswith("fill:"):
+        if not line.startswith("fill:"):
             continue
         declared = line[5:].strip().split()[0].rstrip(",") if line[5:].strip() else ""
-        if declared and declared not in found:
-            found.append(declared)
-    return tuple(found)
+        if not declared:
+            continue
+        target = ignored if fenced else found
+        if declared not in target:
+            target.append(declared)
+    return tuple(found), tuple(ignored)
+
+
+def _plan_fill_declarations(plan_text: str) -> tuple[str, ...]:
+    """Capture every unfenced plan Fill token without checking filesystem state."""
+    return _scan_fill_declarations(plan_text)[0]
 
 
 def resolve_declared_fill(run_root: Path, declared: str) -> Path | None:
@@ -262,15 +281,15 @@ def resolve_declared_fill(run_root: Path, declared: str) -> Path | None:
 
 def _plan_fill_artifacts(
     run_root: Path | None,
-    plan_text: str,
+    declared: tuple[str, ...],
 ) -> tuple[str, ...]:
     """Capture existing fill declarations while the run snapshot is loaded."""
     if run_root is None:
         return ()
     return tuple(
-        declared
-        for declared in _plan_fill_declarations(plan_text)
-        if resolve_declared_fill(run_root, declared) is not None
+        token
+        for token in declared
+        if resolve_declared_fill(run_root, token) is not None
     )
 
 
@@ -436,6 +455,7 @@ def capture_run_facts(
     manifest_lines, manifest_errors, manifest_state = _read_manifest(evidence_dir)
     preview = inspect_preview(preview_dir) if preview_dir is not None else None
     optional = _read_optional_run_facts(run_root)
+    plan_declared, plan_fenced = _scan_fill_declarations(optional.plan_text)
     return RunFacts(
         run_root=run_root,
         spec_path=spec_path,
@@ -445,7 +465,8 @@ def capture_run_facts(
         spec_text=spec_text,
         pointback_text=pointback_text,
         plan_text=optional.plan_text,
-        plan_fill_artifacts=_plan_fill_artifacts(run_root, optional.plan_text),
+        plan_fill_artifacts=_plan_fill_artifacts(run_root, plan_declared),
+        fenced_fill_declarations=plan_fenced,
         craft_guard_text=optional.craft_guard_text,
         ledger=parse_ledger(pointback_text),
         verdict=parse_verdict(pointback_text),

package/scripts/run_status.py

@@ -101,6 +101,9 @@ def render(run_root: Path, *, as_json: bool) -> int:
             }
             for s in states
         ],
+        # fill: lines inside fenced blocks are ignored by declaration
+        # parsing; surfaced so a silently unmarked fill stage is explainable.
+        "fenced_fill_declarations": list(facts.fenced_fill_declarations),
         "next": action,
         "verdict": verdict_of(run_root, facts),
         # Fail closed: malformed/ambiguous markers project False, while
@@ -150,6 +153,12 @@ def render(run_root: Path, *, as_json: bool) -> int:
         mark = "x" if s.present else " "
         detail = f" ({', '.join(s.evidence)})" if s.evidence else ""
         print(f"  [{mark}] {s.key:10} {s.skill}{detail}")
+    if facts.fenced_fill_declarations:
+        listed = ", ".join(facts.fenced_fill_declarations)
+        print(
+            f"fill: declarations ignored (inside fenced blocks): {listed}; "
+            "declare Fill as column-0 unfenced `fill: <path>` lines in plan.md"
+        )
     if vnext.tier is not None:
         confirmed = "confirmed by user" if (
             vnext.confirmed_by or "").casefold().startswith("user") else (

package/scripts/status_projection.py

@@ -412,8 +412,19 @@ def _baseline_next_action(facts: RunFacts) -> str | None:
     decision = state.get("decision") if isinstance(state.get("decision"), dict) else {}
 
     if status == "needs_confirmation":
-        return ("Design-baseline draft needs confirmation — "
-                "accept/waive via design-baseline confirm before Fill.")
+        # Surface why a draft exists at all: an existing candidate that was
+        # rejected (accepting the draft replaces it) vs. no baseline found.
+        rejection = state.get("baseline_rejection")
+        detail = ""
+        if isinstance(rejection, dict):
+            path = rejection.get("path")
+            reason = rejection.get("reason")
+            if isinstance(path, str) and isinstance(reason, str) and reason.strip():
+                detail = f" (existing {path} was rejected: {reason.strip()})"
+        return (
+            "Design-baseline draft needs confirmation — "
+            f"accept/waive via design-baseline confirm before Fill.{detail}"
+        )
     if status == "ambiguous":
         return ("Design-baseline candidates are ambiguous — "
                 "resolve DESIGN.md vs .stitch/DESIGN.md before Fill.")

package/skills/design-baseline/SKILL.md

@@ -45,7 +45,7 @@ State is a cache, not authority. Every public call resolves paths against the su
 | `status` | Meaning |
 | --- | --- |
 | `ready` | Bound baseline (`decision.kind` = `existing` or `accepted`) |
-| `needs_confirmation` | Provenance-backed draft awaits accept/waive |
+| `needs_confirmation` | Provenance-backed draft awaits accept/waive; `baseline_rejection` records why an existing candidate was not bound (`null` when none existed) |
 | `waived` | Explicit user waiver with non-empty reason |
 | `ambiguous` | Conflicting candidates; human choice required |
 
@@ -70,7 +70,7 @@ Agent work after prepare:
 
 - if `status` is `ready` → cite path + sha256 and continue;
 - if `ambiguous` → stop for the smallest user decision; never invent a third authority;
-- if `needs_confirmation` → review the draft; optionally enrich only material claims with `[inferred confidence=…]` **in the draft file**, then re-run prepare if structure/sources changed (do not hand-edit hashes).
+- if `needs_confirmation` → review the draft; optionally enrich only material claims with `[inferred confidence=…]` **in the draft file**, then re-run prepare if structure/sources changed (do not hand-edit hashes). When `baseline_rejection` is set, an existing `DESIGN.md` was rejected for the stated reason — accepting the draft **replaces** it (a backup is kept; see Confirm).
 
 Never write or overwrite project `DESIGN.md` in this step.
 
@@ -80,7 +80,7 @@ Never write or overwrite project `DESIGN.md` in this step.
 
 Show a compact summary: atmosphere, core tokens, typography, layout, primitives, conflicting evidence, inferred claims. Ask before the durable write.
 
-- **Accept:** `confirm(..., decision="accept")` atomically writes canonical `<project-root>/DESIGN.md` from the bound draft and returns a `ready` state.
+- **Accept:** `confirm(..., decision="accept")` atomically writes canonical `<project-root>/DESIGN.md` from the bound draft and returns a `ready` state. If a differing `DESIGN.md` already exists, the previous content is backed up byte-exact first and the state records it as `replaced_baseline` (`path`, `sha256`, `backup`); the CLI prints an overwrite warning with the backup path.
 - **Waive:** `confirm(..., decision="waive", reason=<user reason>)` does not write `DESIGN.md`. Existing-product Fill may continue only after this explicit waiver.
 - **Revise:** edit only the draft (or fix sources), then `prepare` again.
 
@@ -118,6 +118,7 @@ Third-party or sample `DESIGN.md` files remain `reference-intake` inputs. They n
 .scratch/<run>/design-baseline/state.json           # gate cache (schema design-baseline/v1)
 .scratch/<run>/design-baseline/evidence.json        # extraction evidence (when drafted)
 .scratch/<run>/design-baseline/DESIGN.draft.md      # proposal; never authority by itself
+.scratch/<run>/design-baseline/previous-DESIGN.md   # backup of a replaced DESIGN.md (when overwritten)
 ```
 
 The deep module `prepare`/`confirm`/`verify` is the sole gate surface. An adopted existing `DESIGN.md` only needs to carry verifiable source provenance (path + SHA-256 under `## Source Evidence & Confidence`) to be bound; the other section names in [`references/design-template.md`](references/design-template.md) are draft guidance, not a structural contract imposed on hand-written baselines.

package/skills/design-baseline/scripts/design_baseline.py

@@ -13,6 +13,7 @@ import hashlib
 import json
 import os
 import re
+import shutil
 import sys
 import tempfile
 from datetime import datetime, timezone
@@ -24,6 +25,7 @@ SCHEMA = "design-baseline/v1"
 STATE_RELATIVE = Path("design-baseline/state.json")
 EVIDENCE_RELATIVE = Path("design-baseline/evidence.json")
 DRAFT_RELATIVE = Path("design-baseline/DESIGN.draft.md")
+PREVIOUS_RELATIVE = Path("design-baseline/previous-DESIGN.md")
 CANDIDATES = (Path("DESIGN.md"), Path(".stitch/DESIGN.md"))
 # Provenance-minimal gate: an existing project DESIGN.md only has to carry
 # verifiable source provenance (path + SHA-256) to be bound. The other
@@ -157,6 +159,21 @@ def _atomic_write_json(path: Path, value: dict[str, Any]) -> None:
     _atomic_write_text(path, json.dumps(value, indent=2, ensure_ascii=False) + "\n")
 
 
+def _atomic_copy(source: Path, target: Path) -> None:
+    # Byte-exact copy via atomic replace: the backup of an overwritten
+    # authority must survive a crash mid-write with its content intact.
+    target.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{target.name}.", dir=target.parent)
+    os.close(descriptor)
+    temporary = Path(temporary_name)
+    try:
+        shutil.copyfile(source, temporary)
+        os.replace(temporary, target)
+    finally:
+        if temporary.exists():
+            temporary.unlink()
+
+
 def _candidate_files(project: Path) -> list[Path]:
     candidates: list[Path] = []
     for relative in CANDIDATES:
@@ -548,12 +565,18 @@ def prepare(project_root: Path | str, run_root: Path | str) -> dict[str, Any]:
     # Existing candidates are validated by the same strict parser used by
     # verify().  An incomplete candidate remains untouched while a replacement
     # proposal is generated in the run directory.
+    rejected: dict[str, str] | None = None
     if candidates:
         selected = project / CANDIDATES[0] if (project / CANDIDATES[0]) in candidates else candidates[0]
         try:
             sources = _validate_baseline_document(selected, project)
-        except BaselineError:
+        except BaselineError as error:
+            # Keep the rejection reason visible: the draft generated below is
+            # a *replacement* proposal for this rejected candidate, and
+            # consumers must be able to distinguish an invalid existing
+            # baseline from no baseline at all.
             sources = None
+            rejected = {"path": _relative(selected, project), "reason": str(error)}
         if sources is not None:
             state = {
                 "schema": SCHEMA,
@@ -589,6 +612,10 @@ def prepare(project_root: Path | str, run_root: Path | str) -> dict[str, Any]:
             "decision": None,
             "candidates": candidate_names,
             "candidate_sha256": _candidate_snapshot(project, candidates),
+            # Why a prepared draft exists at all: ``null`` means no existing
+            # candidate was found; a record means one existed but was rejected
+            # for that stated reason (the draft proposes replacing it).
+            "baseline_rejection": rejected,
         },
     )
 
@@ -669,6 +696,26 @@ def confirm(
     if canonical.is_symlink():
         raise BaselineError("canonical DESIGN.md must not be a symlink")
     draft_text = _read_text_capped(draft_path, "baseline draft")
+    # Overwrite protection: accept may legitimately replace an invalid
+    # existing baseline, but the previous authority is never silently lost —
+    # differing content is backed up (byte-exact) and recorded in the state
+    # so the overwrite is explicit and reversible.
+    replaced: dict[str, str] | None = None
+    if canonical.is_file():
+        try:
+            existing_hash = _sha256(canonical)
+        except OSError as error:
+            raise BaselineError(
+                "cannot hash existing canonical DESIGN.md; "
+                f"refusing to overwrite it without a backup: {error}"
+            ) from error
+        if existing_hash != expected_draft_hash:
+            _atomic_copy(canonical, run / PREVIOUS_RELATIVE)
+            replaced = {
+                "path": CANDIDATES[0].as_posix(),
+                "sha256": existing_hash,
+                "backup": PREVIOUS_RELATIVE.as_posix(),
+            }
     _atomic_write_text(canonical, draft_text)
     # Post-write TOCTOU hardening (issue M1): between the pre-write symlink
     # check and os.replace, a concurrent writer could swap DESIGN.md for a
@@ -688,6 +735,8 @@ def confirm(
     state["sources"] = sources
     state["decision"] = {"kind": "accepted", "confirmed_at": _utc_now()}
     state["candidate_sha256"] = _candidate_snapshot(project, _candidate_files(project))
+    if replaced is not None:
+        state["replaced_baseline"] = replaced
     _write_state(run, state)
     return verify(project, run)
 
@@ -773,6 +822,14 @@ def main(argv: list[str] | None = None) -> int:
     except BaselineError as error:
         print(json.dumps({"error": str(error)}, ensure_ascii=False), file=sys.stderr)
         return 2
+    replaced = result.get("replaced_baseline")
+    if isinstance(replaced, dict) and replaced.get("backup"):
+        # The overwrite is explicit in the output, not just in the state.
+        print(
+            f"WARNING: accept replaced the existing {replaced.get('path')}; "
+            f"the previous content is backed up at {replaced['backup']}",
+            file=sys.stderr,
+        )
     print(json.dumps(result, indent=2, ensure_ascii=False))
     return 0