design-playbook 0.20.0 → 0.20.1

package/examples/dogfood/run/shaping/shaping-log.jsonl

@@ -2,7 +2,7 @@
 {"event": "answered", "question_id": "Q1", "answer": "运行状态跨页可查、全局控制可用、失败可批量治理", "ts": "2026-08-14T09:02:00Z"}
 {"event": "asked", "question_id": "Q9", "batch": 2, "tier": "T3", "text": "顶栏计数区升级为全局运行控制台——视觉方向（构成级）？", "impact": "D3 decision-report（成形只登记路由，D3 裁决）", "ts": "2026-08-14T09:03:00Z"}
 {"event": "assumption_staged", "field": "sim.control_scope", "tier": "T2", "reason": "全局暂停的作用范围未答", "risk": "误伤手动单次重试", "fallback": "全局暂停/恢复不作用于手动单次重试", "ts": "2026-08-14T09:04:00Z"}
-{"event": "confirm_presented", "batch": "CP-A", "kind": "intent", "items": ["l1.goal 修订（supersedes D-0001）", "l6.c4-c6 表述"], "ts": "2026-08-14T09:08:00Z"}
+{"event": "confirm_presented", "batch": "CP-A", "kind": "intent", "items": [{"field": "l1.goal", "value": "修订（supersedes D-0001）"}, "l6.c4", "l6.c5", "l6.c6"], "ts": "2026-08-14T09:08:00Z"}
 {"event": "confirm_presented", "batch": "CP-C", "kind": "assumption", "items": ["sim.control_scope"], "ts": "2026-08-14T09:08:00Z"}
 {"event": "item_confirmed", "batch": "CP-A", "field": "l1.goal", "ts": "2026-08-14T09:12:00Z"}
 {"event": "item_confirmed", "batch": "CP-A", "field": "l6.c4", "ts": "2026-08-14T09:12:00Z"}

package/examples/export-entry/run/shaping/shaping-log.jsonl

@@ -8,8 +8,8 @@
 {"event": "assumption_staged", "field": "export.row_cap", "tier": "T1", "reason": "规模上限未答（队列满，转显式风险确认）", "risk": "上限过低阻断真实导出或过高拖垮同步窗口", "fallback": "50000 行", "ts": "2026-08-14T09:34:00Z"}
 {"event": "assumption_staged", "field": "export.sync_window", "tier": "T2", "reason": "同步导出限时未逐字确认", "risk": "超时体验未定义", "fallback": "60 秒", "ts": "2026-08-14T09:34:00Z"}
 {"event": "assumption_staged", "field": "export.column_scope", "tier": "T4", "reason": "文件命名与列范围为局部实现选择", "risk": "隐藏列误出", "fallback": "当前视图列（不含隐藏列）", "ts": "2026-08-14T09:34:00Z"}
-{"event": "confirm_presented", "batch": "CP-A", "kind": "intent", "items": ["l1.goal", "l1.target_user", "l6.c1-c3 表述", "l1.non_goals"], "ts": "2026-08-14T09:40:00Z"}
-{"event": "confirm_presented", "batch": "CP-B", "kind": "structural", "items": ["入口 IA 两案：A 全局工具栏 / B 主列表行内批量"], "ts": "2026-08-14T09:40:00Z"}
+{"event": "confirm_presented", "batch": "CP-A", "kind": "intent", "items": ["l1.goal", "l1.target_user", "l6.c1", "l6.c2", "l6.c3", "l1.non_goals"], "ts": "2026-08-14T09:40:00Z"}
+{"event": "confirm_presented", "batch": "CP-B", "kind": "structural", "items": [{"field": "l2.entry_choice", "value": "入口 IA 两案：A 全局工具栏 / B 主列表行内批量"}], "ts": "2026-08-14T09:40:00Z"}
 {"event": "confirm_presented", "batch": "CP-C", "kind": "assumption", "items": ["export.row_cap", "export.sync_window", "export.column_scope", "l1.scenes"], "ts": "2026-08-14T09:40:00Z"}
 {"event": "item_confirmed", "batch": "CP-A", "field": "l1.goal", "ts": "2026-08-14T09:52:00Z"}
 {"event": "item_confirmed", "batch": "CP-A", "field": "l1.target_user", "ts": "2026-08-14T09:52:00Z"}

package/examples/export-pointfix-upgrade/run/shaping/shaping-log.jsonl

@@ -1,6 +1,6 @@
 {"event": "asked", "question_id": "Q1", "batch": 1, "tier": "T1", "text": "「只导出选中列」的完成判据如何表述？", "impact": "l6.c4", "ts": "2026-08-14T12:41:00Z"}
 {"event": "answered", "question_id": "Q1", "answer": "Given 运营在主列表圈选 2 列 When 触发行内导出 Then CSV 仅含圈选列且顺序与列表一致（证据：交互记录）", "ts": "2026-08-14T12:42:00Z"}
-{"event": "confirm_presented", "batch": "CP-A", "kind": "intent", "items": ["l6.c4 表述"], "ts": "2026-08-14T12:43:00Z"}
+{"event": "confirm_presented", "batch": "CP-A", "kind": "intent", "items": ["l6.c4"], "ts": "2026-08-14T12:43:00Z"}
 {"event": "item_confirmed", "batch": "CP-A", "field": "l6.c4", "ts": "2026-08-14T12:44:00Z"}
 {"event": "projected", "ts": "2026-08-14T12:45:00Z", "order": ["promote_fields", "append_decision", "apply_decisions", "spec", "bind_first"], "decisions": ["D-0101"], "assumed": [], "mappings": [{"decision": "D-0101", "field": "l6.c4", "spec_section": "L6"}]}
 {"event": "archived", "ts": "2026-08-14T12:46:00Z"}

package/examples/export-upgrade/run/shaping/shaping-log.jsonl

@@ -2,7 +2,7 @@
 {"event": "answered", "question_id": "Q1", "answer": "任务全程可见、跨页保持、结果可获知", "ts": "2026-08-14T10:44:00Z"}
 {"event": "asked", "question_id": "Q9", "batch": 2, "tier": "T3", "text": "导出进行中的状态呈现——视觉方向（构成级）？", "impact": "D3 decision-report（成形只登记路由，D3 裁决）", "ts": "2026-08-14T10:46:00Z"}
 {"event": "assumption_staged", "field": "export.task_persist_ttl", "tier": "T2", "reason": "状态条目保留时长未答", "risk": "条目堆积或过早消失", "fallback": "run 内持久（≤10 条）", "ts": "2026-08-14T10:47:00Z"}
-{"event": "confirm_presented", "batch": "CP-A", "kind": "intent", "items": ["l1.goal 修订（supersedes D-0001）", "l6.c4-c6 表述"], "ts": "2026-08-14T10:50:00Z"}
+{"event": "confirm_presented", "batch": "CP-A", "kind": "intent", "items": [{"field": "l1.goal", "value": "修订（supersedes D-0001）"}, "l6.c4", "l6.c5", "l6.c6"], "ts": "2026-08-14T10:50:00Z"}
 {"event": "confirm_presented", "batch": "CP-C", "kind": "assumption", "items": ["export.task_persist_ttl"], "ts": "2026-08-14T10:50:00Z"}
 {"event": "item_confirmed", "batch": "CP-A", "field": "l1.goal", "ts": "2026-08-14T10:55:00Z"}
 {"event": "item_confirmed", "batch": "CP-A", "field": "l6.c4", "ts": "2026-08-14T10:55:00Z"}

package/mcp/evidence/capture_runtime.py

@@ -256,13 +256,12 @@ def _action_wait_for_state(page: Any, action: dict, index: int, do: str) -> None
     if not isinstance(state, str) or not state:
         raise ValueError(f"actions[{index}].state required for wait_for_state")
     selector = action.get("selector")
-    if isinstance(selector, str) and selector:
-        page.wait_for_selector(selector, timeout=10_000)
-    else:
-        page.wait_for_selector(
-            f'[data-state="{state}"]',
-            timeout=10_000,
-        )
+    target = (
+        f'{selector}[data-state="{state}"]'
+        if isinstance(selector, str) and selector
+        else f'[data-state="{state}"]'
+    )
+    page.wait_for_selector(target, timeout=10_000)
 
 
 def _action_wait(page: Any, action: dict, index: int, do: str) -> None:

package/mcp/evidence/test_server_stdio.py

@@ -121,9 +121,37 @@ def _structured(call_response: dict) -> dict:
     return json.loads(text)
 
 
+class _RecordingPage:
+    def __init__(self) -> None:
+        self.waits: list[tuple[str, int]] = []
+
+    def wait_for_selector(self, selector: str, *, timeout: int) -> None:
+        self.waits.append((selector, timeout))
+
+
 class EvidencePurePathTests(unittest.TestCase):
     """No-chromium transport and direct runtime-interface tests."""
 
+    def test_wait_for_state_combines_selector_and_state(self) -> None:
+        page = _RecordingPage()
+        capture_runtime._action_wait_for_state(
+            page,
+            {"do": "wait_for_state", "selector": "body", "state": "ready"},
+            0,
+            "wait_for_state",
+        )
+        self.assertEqual(page.waits, [('body[data-state="ready"]', 10_000)])
+
+    def test_wait_for_state_without_selector_targets_any_matching_state(self) -> None:
+        page = _RecordingPage()
+        capture_runtime._action_wait_for_state(
+            page,
+            {"do": "wait_for_state", "state": "ready"},
+            0,
+            "wait_for_state",
+        )
+        self.assertEqual(page.waits, [('[data-state="ready"]', 10_000)])
+
     def test_parse_capture_contract_requires_schema_and_viewport(self) -> None:
         from design_playbook.mcp.evidence import capture_contract
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "design-playbook",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "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/dd_entries.py

@@ -43,7 +43,20 @@ stay protocol-side. Gate policy lives in ``g10_design_decisions.py``.
 
 Flow-map values inside ``- {k: v, ...}`` items may not contain ASCII commas
 or braces (use full-width punctuation in prose values); this is the declared
-shape, same contract style as the seven-column audit rows.
+shape, same contract style as the seven-column audit rows. Items may fold
+across lines (issue #44): a ``- {`` item that does not close its brace on
+the marker line continues on the following lines until the braces balance —
+single-line items parse exactly as before. Folds break at commas (the
+schema example's shape): a break that does not end the accumulated text
+with a comma (or the opening brace) would merge the next key into the
+previous value, so the join records a :class:`FoldIssue` and G10 reports it
+(:code:`G10.fold_break_not_comma`); a fold that never balances by the end
+of the block records :code:`G10.fold_unterminated` (fail-closed, with the
+remaining shape errors still firing).
+
+``dd:`` is the R3 challenge channel, never an observation link: values
+carried by positive (S0) findings are excluded from the challenge face and
+reported as structural errors by G10 (issue #44).
 """
 from __future__ import annotations
 
@@ -51,6 +64,8 @@ import re
 from dataclasses import dataclass, field
 from typing import Any
 
+from design_playbook.scripts.g2_g4_pointback import _findings
+
 # --- closed enums (design-prototype 4.1 machine face) -----------------------
 
 DD_TIERS = frozenset({"record", "compare", "explore"})
@@ -120,6 +135,7 @@ class DDEntry:
     supersedes: str = ""
     stale: str = ""
     stale_review: dict[str, str] = field(default_factory=dict)
+    fold_issues: tuple["FoldIssue", ...] = ()
     block: str = ""
 
     # -- convenience accessors ------------------------------------------
@@ -168,6 +184,23 @@ class DDEntry:
         return [item.get("id", "") for item in self.candidates]
 
 
+@dataclass(frozen=True)
+class FoldIssue:
+    """A fold defect found while joining folded flow-map items.
+
+    ``kind`` is ``"break_not_comma"`` (the accumulated fold text did not end
+    with a comma — or the opening brace — when a continuation was appended,
+    so the next key merges into the previous value) or ``"unterminated"``
+    (the braces never balanced before the block ended). ``line`` is the
+    1-based line of the fold-opening marker inside the entry block;
+    ``tail`` carries the offending text tail for the error face.
+    """
+
+    kind: str
+    line: int
+    tail: str = ""
+
+
 @dataclass(frozen=True)
 class ESignals:
     """Machine-judgeable E-criterion signals gathered from run artifacts."""
@@ -208,6 +241,55 @@ def _flow_map(item: str) -> dict[str, str]:
     return {"value": _scalar(item)}
 
 
+def _join_folded_flow_maps(
+        lines: list[str]) -> tuple[list[str], tuple[FoldIssue, ...]]:
+    """Join folded ``- {...}`` flow-map items onto their marker line.
+
+    Issue #44: an item that opens a ``{`` without closing it on the marker
+    line continues on the following lines (the fold the entry schema
+    example already shows) until its braces balance; continuation text is
+    appended to the marker line so the rest of the parser sees one logical
+    line. Values never contain ASCII commas or braces (declared shape), so
+    brace balance is an unambiguous fold terminator. Folds break at commas:
+    a continuation appended to accumulated text that does not end with a
+    comma (or the opening brace) would silently merge the next key into the
+    previous value, so the break is recorded as a :class:`FoldIssue`
+    (fail-closed; G10 reports it). An unterminated fold stays joined and
+    records its own issue plus the downstream shape checks (fail-closed).
+    Returns ``(joined lines, fold issues)``.
+    """
+    out: list[str] = []
+    issues: list[FoldIssue] = []
+    fold: str | None = None
+    fold_line = 0
+    for lineno, raw_line in enumerate(lines, 1):
+        stripped = raw_line.strip()
+        if fold is not None:
+            if not fold.rstrip().endswith((",", "{")):
+                issues.append(FoldIssue(
+                    kind="break_not_comma",
+                    line=fold_line,
+                    tail=fold.strip()[-60:],
+                ))
+            fold = fold.rstrip() + " " + stripped
+            if fold.count("{") <= fold.count("}"):
+                out.append(fold)
+                fold = None
+            continue
+        if (
+            stripped.startswith("- ")
+            and stripped.count("{") > stripped.count("}")
+        ):
+            fold = raw_line.rstrip()
+            fold_line = lineno
+            continue
+        out.append(raw_line)
+    if fold is not None:
+        issues.append(FoldIssue(kind="unterminated", line=fold_line))
+        out.append(fold)
+    return out, tuple(issues)
+
+
 def _entry_blocks(text: str) -> list[tuple[str, str]]:
     """Split the report into (id, body) blocks by DD entry heading."""
     matches = list(DD_HEADING.finditer(text))
@@ -231,7 +313,8 @@ def _parse_entry(entry_id: str, body: str) -> DDEntry:
     current_section: str | None = None
     current_list_key: str | None = None
 
-    for raw_line in block.splitlines():
+    joined, fold_issues = _join_folded_flow_maps(block.splitlines())
+    for raw_line in joined:
         stripped = raw_line.strip()
         if not stripped or stripped.startswith("```"):
             continue
@@ -307,6 +390,7 @@ def _parse_entry(entry_id: str, body: str) -> DDEntry:
         supersedes=fields.get("supersedes", ""),
         stale=fields.get("stale", ""),
         stale_review=_scalars("stale_review"),
+        fold_issues=fold_issues,
         block=block,
     )
 
@@ -319,20 +403,74 @@ def parse_dd_entries(text: str) -> list[DDEntry]:
     ]
 
 
+# ``none`` value token for the verbatim top block: a trailing same-line
+# note after the token is tolerated commentary, never a declared change
+# (issue #44). The token must end at whitespace or punctuation so values
+# like ``nonempty`` and ``none_x`` stay fail-closed non-none (underscore
+# joins the lookalike continuation class with ``-``, e.g. ``none-such``).
+NONE_VALUE = re.compile(r"none(?=$|[^0-9A-Za-z_-])", re.I)
+
+
 def top_block_baseline_change(text: str) -> bool:
-    """True when the verbatim top block declares ``baseline-changes != none``."""
+    """True when the verbatim top block declares ``baseline-changes != none``.
+
+    ``none`` may carry a trailing same-line note (anything after the value
+    token); notes never turn ``none`` into a declared change. Substantive
+    commentary belongs on its own line.
+    """
     match = re.search(r"^baseline-changes:[ \t]*(\S.*)$", text, re.M)
     if match is None:
         return False
-    return match.group(1).strip().casefold() != "none"
+    return NONE_VALUE.match(match.group(1).strip()) is None
+
+
+def is_positive_finding(parsed: dict[str, list[str]]) -> bool:
+    """True when a parsed point-back finding sits on the S0 (info) axis."""
+    values = parsed.get("severity") or [""]
+    return values[0].strip().casefold() == "s0"
+
+
+def positive_dd_refs(
+        text: str) -> tuple[tuple[int, tuple[str, ...]], ...]:
+    """``(finding index, dd refs)`` for every positive finding carrying ``dd:``.
+
+    Issue #44: ``dd:`` is the R3 challenge channel and never rides a
+    positive observation. These are structural errors G10 reports
+    (fail-closed) instead of silently reading them as challenges.
+    """
+    out: list[tuple[int, tuple[str, ...]]] = []
+    for index, parsed in enumerate(_findings(text), 1):
+        refs = tuple(
+            value.strip().rstrip(",") for value in parsed.get("dd", [])
+            if value.strip())
+        if refs and is_positive_finding(parsed):
+            out.append((index, refs))
+    return tuple(out)
+
+
+def _positive_dd_block(block: str) -> bool:
+    return any(
+        parsed.get("dd") and is_positive_finding(parsed)
+        for parsed in _findings(block)
+    )
 
 
 def dd_refs_in_pointback(text: str) -> tuple[str, ...]:
-    """Collect ``dd:`` targets from finding field lines / invalidated rows."""
+    """Collect ``dd:`` challenge targets from finding field lines.
+
+    Issue #44: ``dd:`` values carried by positive (S0) findings record
+    observation links, not challenges — their paragraphs are skipped so a
+    positive observation can never fire a false re-entry / E3 signal.
+    Paragraphs that are not findings (e.g. a bare ``dd:`` line) keep the
+    legacy raw face.
+    """
     targets: list[str] = []
-    for match in re.finditer(r"^dd:[ \t]*(\S+)", text, re.I | re.M):
-        ref = match.group(1).strip().rstrip(",")
-        targets.append(ref)
+    for block in re.split(r"\n\s*\n", text):
+        if _positive_dd_block(block):
+            continue
+        for match in re.finditer(r"^dd:[ \t]*(\S+)", block, re.I | re.M):
+            ref = match.group(1).strip().rstrip(",")
+            targets.append(ref)
     return tuple(targets)
 
 

package/scripts/escalation_signals.py

@@ -41,6 +41,7 @@ import re
 from dataclasses import dataclass
 
 from design_playbook.scripts._diagnostics import Finding, finding
+from design_playbook.scripts.dd_entries import is_positive_finding
 from design_playbook.scripts.g2_g4_pointback import _findings
 from design_playbook.scripts.repair_rounds import is_blocking
 
@@ -167,9 +168,16 @@ def check_routes(text: str) -> list[Finding]:
 
 
 def dd_targets(text: str) -> tuple[str, ...]:
-    """dd: references carried by findings (R3 challenge face)."""
+    """dd: references carried by findings (R3 challenge face).
+
+    Issue #44: positive (S0) findings carry observation links, not
+    challenges — their ``dd:`` values never fire E3 (G10 reports the
+    misuse as a structural error instead).
+    """
     targets: list[str] = []
     for parsed in _findings(text):
+        if is_positive_finding(parsed):
+            continue
         targets.extend(value.strip() for value in parsed.get("dd", [])
                        if value.strip())
     return tuple(targets)

package/scripts/g10_design_decisions.py

@@ -6,8 +6,9 @@ declared by the protocol — entry completeness, tier/status enums, tier
 recording obligations (R one-line rationale / C trade-off record / E user
 confirmation), supersedes existence + acyclicity, registry rule-reference
 cross-check, preview transaction linkage (decision_id), R3 re-entry
-resolution (dd: challenges must end invalidated with an E-tier revision),
-and the baseline-drift stale review (three exits: keep / revise / escalate).
+resolution (dd: challenges must end invalidated with an E-tier revision;
+``dd:`` on a positive finding is a shape error, issue #44), and the
+baseline-drift stale review (three exits: keep / revise / escalate).
 
 Comparison-matrix quality, trade-off sufficiency, and tier-grading
 judgement calls (composition change, identity drift beyond declared
@@ -35,6 +36,7 @@ from design_playbook.scripts.dd_entries import (
     is_cross_run_ref,
     local_dd_id,
     parse_dd_entries,
+    positive_dd_refs,
 )
 
 # rules.md ships inside the package (read-only protocol consumption, the
@@ -102,6 +104,11 @@ def _entry_checks(entries: list[DDEntry]) -> list[Finding]:
             ))
         seen[label] = index
 
+        # fold defects first (issue #44 follow-up): a named unterminated /
+        # comma-less fold error outranks the indirect missing_* findings it
+        # causes downstream, so the error face points at the real defect.
+        errs += _fold_checks(entry)
+
         for key in ("id", "tier", "question", "status"):
             if not entry.fields.get(key, "").strip():
                 errs.append(finding(
@@ -143,6 +150,45 @@ def _entry_checks(entries: list[DDEntry]) -> list[Finding]:
     return errs
 
 
+def _fold_checks(entry: DDEntry) -> list[Finding]:
+    """Fold defects on ``- {…}`` items (issue #44 follow-up, fail-closed).
+
+    A fold break without a comma merges the next key into the previous
+    value (the parse alone would accept it silently); a fold that never
+    balances swallows the rest of the block and only indirect missing_*
+    errors would fire. Both get a named error up front, with the block line
+    of the fold-opening marker; the remaining shape errors still fire.
+    """
+    errs: list[Finding] = []
+    for issue in entry.fold_issues:
+        if issue.kind == "unterminated":
+            errs.append(finding(
+                "G10.fold_unterminated",
+                f"G10 decisions: {entry.id} opens a folded flow-map item at "
+                f"block line {issue.line} that never closes its brace — the "
+                "fold swallowed the rest of the entry block",
+                owner=_fmt(entry.id),
+                expected="braces balance inside the entry block",
+                actual=f"unterminated fold from block line {issue.line}",
+                repair="Close the brace, or unfold to the canonical "
+                       "single-line item",
+            ))
+        else:
+            errs.append(finding(
+                "G10.fold_break_not_comma",
+                f"G10 decisions: {entry.id} folds a flow-map item at block "
+                f"line {issue.line} without a comma at the break — the next "
+                "key merges into the previous value",
+                owner=_fmt(entry.id),
+                expected="fold breaks end with a comma (or the opening "
+                         "brace)",
+                actual=f"break after {issue.tail!r}",
+                repair="End the folded line with a comma before continuing "
+                       "the item on the next line",
+            ))
+    return errs
+
+
 def _candidate_checks(entry: DDEntry) -> list[Finding]:
     errs: list[Finding] = []
     label = entry.id
@@ -669,6 +715,31 @@ def _reentry_checks(
     return errs
 
 
+def _positive_dd_checks(pointback_text: str | None) -> list[Finding]:
+    """``dd:`` on a positive (S0) finding is a shape error (issue #44).
+
+    ``dd:`` is the R3 challenge channel; riding it on a positive
+    observation reads as a challenge downstream. Fail closed with a
+    precise error instead of silently ignoring the line.
+    """
+    if not pointback_text:
+        return []
+    errs: list[Finding] = []
+    for index, refs in positive_dd_refs(pointback_text):
+        errs.append(finding(
+            "G10.dd_on_positive_finding",
+            f"G10 decisions: positive finding {index} carries "
+            f"dd: {', '.join(refs)} — dd: is the R3 challenge channel and "
+            "never rides a positive observation",
+            owner=f"point-back.md#finding.{index}",
+            expected="dd: only on non-positive (S1-S3) findings",
+            actual="dd: on severity S0",
+            repair="Drop the dd: line and record the observation link as "
+                   "prose (e.g. an evidence note line)",
+        ))
+    return errs
+
+
 def _preview_link_checks(
         entries: list[DDEntry],
         preview_dir: Path | None) -> list[Finding]:
@@ -929,6 +1000,7 @@ def check_g10(
         report_text=report_text,
     )
     errs += _reentry_checks(entries, signals.dd_targets)
+    errs += _positive_dd_checks(pointback_text)
     errs += _preview_link_checks(entries, preview_dir)
     errs += _stale_checks(entries, baseline_state)
     errs += _signal_checks(entries, signals, run_profile_tier)

package/scripts/learning_candidates.py

@@ -36,9 +36,9 @@ from design_playbook.scripts.g2_g4_pointback import FIELD_LINE
 MIN_DISTINCT_RUNS = 3
 MIN_DISTINCT_CONTEXTS = 2
 MAX_UNEXPLAINED_FALSE_POSITIVES = 0
-# Positive observations (S0) are not defect signals — the derivation
-# never lets them enter the candidate queue.
-EXCLUDED_SEVERITIES = frozenset({"S0"})
+# Candidate derivation fails closed: only defect severities enter history.
+# S0 is a positive observation; blank, legacy, and unknown values are invalid.
+CANDIDATE_SEVERITIES = frozenset({"S3", "S2", "S1"})
 
 UNSPECIFIED_CONTEXT = "(unspecified)"
 
@@ -134,8 +134,8 @@ def derive_candidates(
     """
     groups: dict[str, list[Occurrence]] = {}
     for occurrence in occurrences:
-        if occurrence.severity.strip() in EXCLUDED_SEVERITIES:
-            continue  # positive observations are not defect signals
+        if occurrence.severity.strip() not in CANDIDATE_SEVERITIES:
+            continue
         key = normalize(occurrence.issue)
         if key:
             groups.setdefault(key, []).append(occurrence)

package/scripts/run_profile.py

@@ -28,6 +28,7 @@ from dataclasses import dataclass, field
 RUN_PROFILE_MARKER = re.compile(r"<!--\s*run-profile(?::\s*v(\d+))?\s*-->")
 FENCED_BLOCK = re.compile(r"```[a-zA-Z]*\n(.*?)```", re.S)
 TIERS = frozenset({"P1", "P2", "P3"})
+SUPPORTED_RUN_PROFILE_VERSIONS = frozenset({1})
 
 
 @dataclass(frozen=True)
@@ -105,6 +106,10 @@ def validate_run_profile(profile: RunProfile | None) -> list[str]:
                 "skipping the rest of the plan body is legal, skipping the "
                 "profile block is not)"]
     errors: list[str] = []
+    if profile.version not in SUPPORTED_RUN_PROFILE_VERSIONS:
+        errors.append(
+            f"run-profile version v{profile.version} is unsupported; only v1 is accepted"
+        )
     if profile.tier not in TIERS:
         errors.append(
             f"run-profile tier {profile.tier!r} not in P1|P2|P3 "

package/scripts/run_status.py

@@ -2,12 +2,16 @@
 """Derive Design I/O run status / resume hints from existing artifacts.
 
 Does **not** create a second run-state SSOT. Reads only files agents already
-write under a run root (default: discover newest ``.scratch/*/``).
+write under a run root (default: discover newest ``.scratch/*/``). Fill
+surfaces may live outside the run root: when ``plan.md`` registers them with
+``fill:`` field lines, the fill stage is also judged on those declared paths
+(issue #44; the stage registry itself is unchanged).
 """
 from __future__ import annotations
 
 import argparse
 import json
+import re
 import sys
 from dataclasses import dataclass
 from pathlib import Path
@@ -202,16 +206,63 @@ class StageState:
     evidence: list[str]
 
 
+# Issue #44: fill surfaces may land in the host tree (product side) instead
+# of the run root. When plan.md registers those paths as ``fill:`` field
+# lines, the fill stage is also judged on their existence — one path per
+# line, run-root-relative or host-project-relative (the orchestrating cwd).
+# Only unfenced column-0 field lines are declarations; fenced blocks are
+# prose/examples and are never read as declarations.
+PLAN_FILL_LINE = re.compile(r"^fill:[ \t]*(\S+)")
+
+
+def _plan_fill_artifacts(run_root: Path) -> list[str]:
+    """Declared fill artifact paths from plan.md that exist on disk.
+
+    Fenced code blocks (```` ``` ````) are skipped while scanning: an
+    example or prose block citing ``fill: spec.md`` is not a declaration
+    (fail-closed — the fill stage stays unchecked rather than counting a
+    narrated example).
+    """
+    try:
+        text = (run_root / "plan.md").read_text(encoding="utf-8")
+    except (OSError, UnicodeError):
+        return []
+    found: list[str] = []
+    fenced = False
+    for line in text.splitlines():
+        if line.lstrip().startswith("```"):
+            fenced = not fenced
+            continue
+        if fenced:
+            continue
+        match = PLAN_FILL_LINE.match(line)
+        if match is None:
+            continue
+        declared = match.group(1).strip().rstrip(",")
+        candidate = Path(declared)
+        bases = (
+            [candidate] if candidate.is_absolute()
+            else [run_root / candidate, Path.cwd() / candidate]
+        )
+        if any(base.is_file() for base in bases) and declared not in found:
+            found.append(declared)
+    return found
+
+
 def inspect_run(
     run_root: Path, preview_snapshot: PreviewSnapshot | None = None,
     run_facts: RunFacts | None = None,
 ) -> list[StageState]:
     facts = run_facts or capture_run_facts(run_root=run_root)
     snapshot = preview_snapshot or facts.preview or inspect_preview(run_root / "preview")
+    plan_fills = _plan_fill_artifacts(run_root)
     states: list[StageState] = []
     for stage in STAGES:
         if stage.key == "preview":
             found = [f"preview/{source}" for source in snapshot.occurrence_sources]
+        elif stage.key == "fill":
+            found = [marker for marker in stage.markers if marker in facts.existing_paths]
+            found += [declared for declared in plan_fills]
         else:
             found = [marker for marker in stage.markers if marker in facts.existing_paths]
         states.append(StageState(

package/scripts/shaping_log.py

@@ -93,21 +93,11 @@ def load_shaping_facts(run_root: Path) -> ShapingFacts | None:
     return ShapingFacts(events=tuple(events), queue=queue)
 
 
-def _pending_ids(events: list[dict[str, Any]]) -> set[str]:
-    """Item ids referenced by ask/stage events without a terminal answer."""
-    opened: set[str] = set()
-    closed: set[str] = set()
-    for event in events:
-        kind = event.get("event")
-        item = event.get("question_id") or event.get("item_id")
-        if not isinstance(item, str) or not item:
-            continue
-        if kind in ("asked", "assumption_staged", "confirm_presented"):
-            opened.add(item)
-        elif kind in ("answered", "item_confirmed", "item_rejected",
-                      "item_revised"):
-            closed.add(item)
-    return opened - closed
+def _item_id(item: Any) -> Any:
+    """Identity of a confirmation-batch item (``field`` for dict items)."""
+    if isinstance(item, dict):
+        return item.get("field")
+    return item
 
 
 def derive_queue(events: list[dict[str, Any]]) -> dict[str, Any]:
@@ -116,6 +106,13 @@ def derive_queue(events: list[dict[str, Any]]) -> dict[str, Any]:
     Derived view (shaping-prototype 4.1): pending questions (asked, not
     answered), staged assumptions (staged, not confirmed/rejected/revised),
     and confirmation batches (presented, not fully decided).
+
+    Batches close at item granularity: ``item_confirmed`` /
+    ``item_rejected`` / ``item_revised`` events settle only the presented
+    item whose id (dict ``field`` or the bare string) they carry, so a
+    partially decided batch stays listed with its undecided items and a
+    batch leaves ``open_confirmations`` only once every presented item has
+    a terminal decision.
     """
     pending: list[dict[str, Any]] = []
     staged: list[dict[str, Any]] = []
@@ -154,11 +151,23 @@ def derive_queue(events: list[dict[str, Any]]) -> dict[str, Any]:
                 item for item in staged
                 if item.get("field") != field_path
             ]
-            if isinstance(event.get("batch"), str):
-                confirmations = [
-                    batch for batch in confirmations
-                    if batch.get("batch") != event.get("batch")
-                ]
+            if (
+                isinstance(event.get("batch"), str)
+                and isinstance(field_path, str) and field_path
+            ):
+                batch_name = event.get("batch")
+                settled: list[dict[str, Any]] = []
+                for batch in confirmations:
+                    if batch.get("batch") != batch_name:
+                        settled.append(batch)
+                        continue
+                    remaining = [
+                        item for item in batch.get("items", [])
+                        if _item_id(item) != field_path
+                    ]
+                    if remaining:
+                        settled.append({**batch, "items": remaining})
+                confirmations = settled
     return {
         "derived_from": "shaping-log.jsonl",
         "pending_questions": pending,

package/skills/craft-guard/SKILL.md

@@ -51,6 +51,8 @@ For implemented UI, evaluate the applicability predicates of the registry entrie
 
 `Applicability` is the entry's three-state predicate outcome: `applicable`, `not-applicable`, or `blocked`. **not-applicable and blocked both require an observable reason** (blank is invalid — never a silent skip). `Result` is `clear|hit` only for applicable rows, `-` otherwise; `Positive fix` is required on hit rows. Missing rendered or source proof is `blocked`, not a silent clear. Unknown registry IDs fail at this stage. Audit rows are advisory: record evidence, exception check, and positive fix; leave declaration source, severity, and verdict to `ui-evaluator`.
 
+The host model may have no vision (text-only input): renders stay **path-bound** (the `Rendered evidence` column cites the artifact path; never read the image), and assertions run on the **text face** — HTML/CSS source, `a11y tree` text, interaction-trace JSON. A no-vision run evaluates the same registry protocol this way without degrading it; genuinely missing rendered proof still records `blocked` honestly.
+
 | Push toward | Instead of default sludge |
 | --- | --- |
 | Accent on key noun + primary CTA | Purple–blue gradient wallpaper |

package/skills/design-playbook/SKILL.md

@@ -146,6 +146,8 @@ Implement structure from the decision report + `spec` + confirmed project `DESIG
 
 If a reused host component conflicts with spec L5, record the conflict and recirculate to `spec` via the authoritative map in `ui-evaluator` before choosing a minimal patch or explicit acceptance.
 
+**Fill artifact location:** the Fill surface may live in the host tree (product side) instead of the run root. When it does, register the path(s) in `plan.md` as `fill: <path>` field lines (one per line; run-root-relative or host-project-relative; unfenced column-0 lines — fenced example/prose blocks are never read as declarations) — `run-status` judges the fill stage on those declared paths in addition to `filled-ui.*` in the run root. An out-of-run Fill surface with no registered path leaves the fill stage unchecked.
+
 Load on demand (only if the fill needs them):
 
 - domain / risk / sensitive fields → `ui-picker/references/domain.md`

package/skills/reference-intake/SKILL.md

@@ -47,6 +47,8 @@ Write `manifest.json` under `.scratch/<run>/reference/` using the shape in [`ref
 
 Read the sources. Fill **every required heading** from [`references/contract-template.md`](references/contract-template.md) (SSOT for section names and bullet prompts). Do not invent alternate headings.
 
+The host model may have no vision (text-only input): image sources are registered by **path and metadata only** (locator, `sha256`, `captured_at` in `manifest.json`) — reading the image is never a required intake action. The observed/inferred split then rides the text the session can actually cite (user-provided notes, URL page text, file facts); visual points nobody can verify stay `inferred` or move to Unresolved questions. A no-vision host runs this skill end to end without degrading the protocol.
+
 Mark every claim as **observed** or **inferred**. Unlabeled claims are invalid; rewrite them before emit.
 
 **Done when:**

package/skills/ui-evaluator/SKILL.md

@@ -57,6 +57,8 @@ Evidence is captured, not judged. A manifest entry records that an artifact was
 
 For implemented UI, visible-state proof is a rendered inspection at the declared target viewport; behavior proof is an interaction trace or automated check; code-health proof is the relevant available test, type/lint, or affected build result. Planning-only proof is declaration coverage and must not claim a render or test occurred. Non-L6 declaration checks may be supporting observations or findings; they do not enter the machine ledger.
 
+The host model may have no vision (text-only input). Reading a screenshot would break such a session — never make viewing an artifact a review action. Render artifacts stay bound as path references (manifest + ledger `observed`), and machine assertions judge the **text face**: HTML/CSS source, `a11y tree` text, and interaction-trace JSON. A no-vision run reviews this way end to end without degrading the protocol; note it once in the Limitations statement ("this run was reviewed on text-face evidence").
+
 **Done when:** every bound row was considered; every L6 criterion has exactly one non-empty `criterion / required / observed / result` row keyed as `L6.<n>`; results use only `pass|fail|blocked|N/A`; unavailable required proof is `blocked`, not skipped.
 
 ### 3. Emit point-back findings
@@ -79,7 +81,7 @@ disposition: blocking|advisory|info   (severity x fact/judgment class x confiden
 evidence:    <artifact path or source ref — may repeat>
 assumes:     <assumed contract field paths the finding depends on, if any>
 rule:        <registry ID@version refs, when a registry rule is involved>
-dd:          <decision-report entry ref, when a design decision is involved>
+dd:          <decision-report entry ref, when a design decision is challenged — never on positive (S0) findings>
 ```
 
 Severity and disposition are **two axes**: a judgment-class S3 (subjective / semantic / representativeness) is never directly blocking — list it in the Limitations "pending user adjudication" sub-block with the three options (change declaration / accept risk / promote to the rule-registry queue). Only fact-class S3 (reproducible, evidence-bound) takes `disposition: blocking` and enters G4 closure.
@@ -115,7 +117,9 @@ The report artifact remains `point-back.md` (no new file). The machine face is u
                              explicit unreviewed list; G11 checks existence)
 ## Limitations statement    (judgment-class dimensions, no-user-evidence scope,
                              pass scope, assumed dependencies, machine-face
-                             boundary, pending-user-adjudication sub-block)
+                             boundary, text-face review note when no visual
+                             evidence was read, pending-user-adjudication
+                             sub-block)
 ## Verdict                  (exactly one Pass|Recirculate + closure lines)
 ```
 

package/skills/ui-picker/SKILL.md

@@ -51,6 +51,8 @@ baseline-changes: none | <explicitly approved change>
 risks: …
 ```
 
+`baseline-changes: none` tolerates a trailing same-line note (the machine face reads the `none` value token); substantive commentary goes on its own line instead.
+
 **Done when:** the report exists, records the bound baseline or explicit waiver, and coding has not started without it.
 
 #### DD entry blocks (append after the top block)

package/skills/ui-picker/references/decisions.md

@@ -59,7 +59,7 @@ stale: <reason + ts>             # optional: baseline drift marked this entry
 stale_review: {exit: keep, note: <review line + new sha256>}  # keep | revise | escalate
 ```
 
-Rules: ids are zero-padded `DD-####` and never repeat inside a run; flow-map values must not contain ASCII commas or braces (use full-width punctuation in prose); comparison cells carry facts and statements with source references — **numeric scores, weighted sums, and ranking points are forbidden**; incommensurable axes get an explicit trade-off line instead.
+Rules: ids are zero-padded `DD-####` and never repeat inside a run; flow-map values must not contain ASCII commas or braces (use full-width punctuation in prose); a `- {…}` item may fold onto following lines while its braces stay unbalanced, breaking at a comma — the folded line must end with a comma before the continuation (the schema above shows the fold — single-line items are canonical; a comma-less break or an unterminated fold is a G10 structural error, never a silent merge); comparison cells carry facts and statements with source references — **numeric scores, weighted sums, and ranking points are forbidden**; incommensurable axes get an explicit trade-off line instead.
 
 ## Candidates and providers
 
@@ -71,6 +71,6 @@ E tier is confirmed by the user in batches (≤2 items, 2-3 candidates each, ver
 
 ## Re-entry (R3) and baseline drift
 
-An R3 finding (failed assumption, unrecorded trade-off, baseline conflict) names the challenged entry with an additional field line `dd: DD-0003` (same backward-compatible channel as `rule:` lines). Revision = a new entry with `supersedes: DD-0003`; the old entry is retired (`status: invalidated`) and stays parsable — history is never rewritten. The minimal invalidation set is the entry + the Fill surface consuming it + the evidence depending on its assumptions (recorded in the point-back `invalidated:` block); re-review runs only that set plus adjacent main path, inside the same run. A revision re-grades by current criteria — a challenged direction is still direction-level, so the revision lands at E tier with a fresh user confirmation (a new preview round when riding, `round_n` incremented). Baseline-conflict revisions have exactly two legal exits: pick a baseline-conforming candidate, or take an explicit `baseline-changes` approval.
+An R3 finding (failed assumption, unrecorded trade-off, baseline conflict) names the challenged entry with an additional field line `dd: DD-0003` (same backward-compatible channel as `rule:` lines). The field rides only non-positive findings (S1-S3): a positive observation records its decision link as prose (e.g. an evidence note line) — `dd:` on an S0 finding is a G10 structural error, never a challenge signal. Revision = a new entry with `supersedes: DD-0003`; the old entry is retired (`status: invalidated`) and stays parsable — history is never rewritten. The minimal invalidation set is the entry + the Fill surface consuming it + the evidence depending on its assumptions (recorded in the point-back `invalidated:` block); re-review runs only that set plus adjacent main path, inside the same run. A revision re-grades by current criteria — a challenged direction is still direction-level, so the revision lands at E tier with a fresh user confirmation (a new preview round when riding, `round_n` incremented). Baseline-conflict revisions have exactly two legal exits: pick a baseline-conforming candidate, or take an explicit `baseline-changes` approval.
 
 When `design-baseline verify` detects source-hash drift, entries citing the old sha are marked `stale: <reason>` and re-reviewed under the new baseline with exactly one exit recorded in `stale_review`: **keep** (review line citing the new sha256 — clears the mark), **revise** (a superseding entry, confirmed per its tier), or **escalate** (the drift returns the question to direction level — user decision). No calendar expiry: stale is triggered by structural events only. G10 checks that drifted entries carry the mark and that every marked entry records a valid exit.

package/skills/ux-spec/SKILL.md

@@ -61,6 +61,8 @@ Use the headings in [`references/spec-template.md`](references/spec-template.md)
 
 Evidence is criterion-shaped: visible states require rendered inspection at named target viewports; behavior requires an interaction trace or automated check; implementation health uses the relevant tests, type/lint checks, or affected build when available. Planning-only work names the future proof instead of claiming it exists. Where the proof is a runtime state, name the **capture seed** — the state to capture (e.g. "error-state screenshot") and the capture type. This is the seed the `observe*` step derives a capture plan from (`Given`/`When` → state+actions, `Then` → required); do not write selectors, URLs, or actions here — those are derived later. Capture contract v1 requires `schemaVersion: 1` and an explicit viewport at observe time (ADR-0018).
 
+The host model may have no vision (text-only input): render artifacts are bound by **path reference** (manifest + ledger), never by viewing them. Machine assertions for review use the **text face** — HTML/CSS source, `a11y tree` text, interaction-trace JSON. A no-vision run follows this mode end to end; it is not a protocol downgrade, so do not write L6 proof that requires the composing model to look at a screenshot.
+
 **Done when:** L5 is not a single word (“loading”); every L6 item is a top-level list item that uses `Given -> When -> Then` in that order, can be ticked pass/fail without taste debate, and says what evidence will prove it (naming the capture seed where the proof is a runtime state); every L6 item references a reachable path row; L6 items stay user-risk units rather than one row per evidence type.
 
 ### 4. Emit