design-playbook 0.20.1 → 0.20.2

package/examples/export-entry/run/evidence/L6.1-usertest-notes.md

@@ -1,15 +1,10 @@
-# User-test session notes — L6.1 supplementary (quarantined)
+# Synthetic user-test example — not evidence
 
-Round 1 usability session, 2026-08-14. Facilitated weekly-report export
-task with 3 operations participants (convenience sample).
+Schema/example material only. No real human-subject session occurred, no
+participant observations or personal data are represented, and this file is
+not registered in `manifest.jsonl`.
 
-Observed behavior: 2 of 3 participants first looked for the export entry
-in the global toolbar, then used the inline batch export after a hint.
-
-Status: **unusable as evidence** — the session ran before the consent /
-anonymisation / retention record was completed, so the manifest entry
-carries `method: user-test` with `population` but no `ethics` key. Per the
-method-semantics gate this entry is quarantined as blocked evidence: it
-cannot support any judgment (the L6.1 pass rests on
-`L6.1-export-trace.json`, not on these notes). Complete the ethics record
-in a newer manifest entry to make the session citable.
+The scenario illustrates what a user-test note might look like during method
+semantics testing. It must not support a run judgment or any claim about user
+behavior. Tests that exercise missing `ethics` construct their own temporary
+manifest entry rather than treating this file as evidence.

package/examples/export-entry/run/evidence/manifest.jsonl

@@ -5,4 +5,3 @@
 {"criterion": "L6.2", "capture": {"type": "a11y tree", "provider": "manual", "state": "cap-blocked-r2", "actions": ["select over-cap range", "open export dialog (post R4 fix)"], "schemaVersion": 1, "request": {"schemaVersion": 1, "viewport": {"width": 1280, "height": 800, "devicePixelRatio": 1.0, "colorScheme": "light"}, "freeze": {"enabled": true, "waitFonts": true, "networkIdle": false}}}, "artifact": "L6.2-a11y-tree-r2.json", "observed_state": "cap-blocked-r2", "result": "captured", "ts": "2026-08-14T11:04:30Z", "request": {"schemaVersion": 1, "viewport": {"width": 1280, "height": 800, "devicePixelRatio": 1.0, "colorScheme": "light"}, "freeze": {"enabled": true, "waitFonts": true, "networkIdle": false}}, "method": "runtime-observation", "observation": "toast 节点带 role=alert 与可读名称（含超限数值 200,000）", "interpretation": "R4 修复后的 a11y 附接证据，印证 L6.2 pass（ADR-0016 附接到既有 user-risk 判据）", "scope": "单次运行, viewport 1280x800, 数据集 week-2026-32", "population": null, "ethics": null}
 {"criterion": "L6.2", "capture": {"type": "screenshot", "provider": "manual", "state": "cap-blocked-r2", "actions": ["select over-cap range", "open export dialog (post R4 fix)"], "schemaVersion": 1, "request": {"schemaVersion": 1, "viewport": {"width": 1280, "height": 800, "devicePixelRatio": 1.0, "colorScheme": "light"}, "freeze": {"enabled": true, "waitFonts": true, "networkIdle": false}}}, "artifact": "L6.2-cap-error-r2.png", "observed_state": "cap-blocked-r2", "result": "captured", "ts": "2026-08-14T11:05:00Z", "request": {"schemaVersion": 1, "viewport": {"width": 1280, "height": 800, "devicePixelRatio": 1.0, "colorScheme": "light"}, "freeze": {"enabled": true, "waitFonts": true, "networkIdle": false}}, "method": "runtime-observation", "observation": "提示含「超出 200,000 行上限」与「按周导出」收窄建议（重评 r2）", "interpretation": "满足 c2 的 Then 子句（剩余量与收窄建议）；依赖 assumed 字段 export.row_cap 成立", "scope": "单次运行, viewport 1280x800, 数据集 week-2026-32", "population": null, "ethics": null}
 {"criterion": "L6.3", "capture": {"type": "interaction trace", "provider": "manual", "state": "return-visible", "actions": ["start export", "navigate away", "navigate back", "read progress and result"], "schemaVersion": 1, "request": {"schemaVersion": 1, "viewport": {"width": 1280, "height": 800, "devicePixelRatio": 1.0, "colorScheme": "light"}, "freeze": {"enabled": true, "waitFonts": true, "networkIdle": false}}}, "artifact": "L6.3-return-trace.json", "observed_state": "return-visible", "result": "captured", "ts": "2026-08-14T11:10:00Z", "request": {"schemaVersion": 1, "viewport": {"width": 1280, "height": 800, "devicePixelRatio": 1.0, "colorScheme": "light"}, "freeze": {"enabled": true, "waitFonts": true, "networkIdle": false}}, "method": "runtime-observation", "observation": "导出中离开 main-list 后返回，exporting 进度态可见，完成后结果可获知（R5 修订 capture plan 后重采）", "interpretation": "满足 c3 的 Then 子句（进度与结果仍可获知）；首轮跨导航 session 丢失记 blocked 已按 invalidated 块登记", "scope": "单次运行, viewport 1280x800, 数据集 week-2026-32", "population": null, "ethics": null}
-{"criterion": "L6.1", "capture": {"type": "session notes", "provider": "manual", "state": "usertest-round1", "actions": ["facilitate weekly-report export task", "record participant behavior"], "schemaVersion": 1, "request": {"schemaVersion": 1, "viewport": {"width": 1280, "height": 800, "devicePixelRatio": 1.0, "colorScheme": "light"}, "freeze": {"enabled": true, "waitFonts": true, "networkIdle": false}}}, "artifact": "L6.1-usertest-notes.md", "observed_state": "usertest-round1", "result": "captured", "ts": "2026-08-14T10:50:00Z", "request": {"schemaVersion": 1, "viewport": {"width": 1280, "height": 800, "devicePixelRatio": 1.0, "colorScheme": "light"}, "freeze": {"enabled": true, "waitFonts": true, "networkIdle": false}}, "method": "user-test", "observation": "3 名运营参与者完成周报导出任务；其中 2 人先在全局工具栏寻找导出入口，经提示后使用行内入口", "interpretation": null, "scope": "单次会话, 3 名运营参与者, 便利抽样", "population": "3 名运营角色参与者（周报任务，便利抽样）", "ethics": null}

package/examples/export-entry/run/point-back.md

@@ -67,7 +67,7 @@ face:     subjective
 basis:    agent-judgment
 confidence: low
 disposition: advisory
-evidence:  rendered 走查（agent-judgment, method=expert-review）；非用户证据——涉人记录见 evidence/L6.1-usertest-notes.md（ethics 缺失，已隔离不可采信）
+evidence:  rendered 走查（agent-judgment, method=expert-review）；非用户证据——evidence/L6.1-usertest-notes.md 仅为合成 schema 示例，未登记到 Manifest，不能支持判断
 ```
 
 ## Positive findings
@@ -107,7 +107,7 @@ evidence:  evidence/L6.1-export-trace.json（跨层：交互轨迹 + 度量计
 ## Limitations statement
 
 - 判断类 advisory：术语适配（task-organization 主观面，agent-judgment 非用户证据，confidence=low，advisory 不阻 verdict）
-- 用户代表性：本 run 无可用 user-test 证据（L6.1-usertest-notes.md 因 ethics 缺失被隔离为 blocked 证据），全部结论不构成任何「用户会」断言
+- 用户代表性：本 run 无真实 user-test evidence；合成 notes 未登记到 Manifest，全部结论不构成任何「用户会」断言
 - pass 范围：L6.1/L6.2/L6.3 pass 限单 viewport 1280x800 / 单数据集 week-2026-32 / 单次运行
 - assumed 依赖：L6.2 pass 依赖 export.row_cap 假设成立
 - 机器面证明声明与事实一致，不证明体验良好

package/package.json

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

@@ -37,7 +37,10 @@ if str(_PKG_ROOT) not in sys.path:
 from design_playbook.scripts import rules_registry  # noqa: E402
 from design_playbook.scripts._diagnostics import Finding, finding  # noqa: E402
 from design_playbook.scripts.rules_registry import RegistryError  # noqa: E402
-from design_playbook.scripts.run_profile import parse_run_profile  # noqa: E402
+from design_playbook.scripts.run_profile import (  # noqa: E402
+    parse_run_profile,
+    validate_run_profile,
+)
 
 REGISTRY_PATH = (
     Path(__file__).resolve().parents[1] / "skills" / "design-playbook"
@@ -144,9 +147,16 @@ def main(argv: list[str]) -> int:
         try:
             profile = parse_run_profile(
                 plan_path.read_text(encoding="utf-8"))
-            tier = profile.tier if profile is not None else None
-        except (OSError, UnicodeError):
-            tier = None
+        except (OSError, UnicodeError) as exc:
+            print(f"G8 INVALID: cannot read {plan_path}: {exc}", file=sys.stderr)
+            return 2
+        profile_errors = validate_run_profile(profile) if profile is not None else []
+        if profile_errors:
+            print("G8 INVALID:")
+            for error in profile_errors:
+                print(f"  FAIL  run-profile invalid: {error}")
+            return 1
+        tier = profile.tier if profile is not None else None
     findings = check_g8_run(craft_text, entries, tier)
     if not findings:
         print("G8 OK: craft audit rows satisfy the run-level registry gate")

package/scripts/run_facts.py

@@ -13,6 +13,12 @@ from typing import Any
 
 from design_playbook.mcp.evidence.ledger_syntax import LedgerFacts, parse_ledger
 from design_playbook.mcp.preview.integrity import PreviewSnapshot, inspect_preview
+from design_playbook.scripts.dd_entries import DDEntry, parse_dd_entries
+from design_playbook.scripts.run_profile import RunProfile, parse_run_profile
+from design_playbook.scripts.shaping_log import (
+    ShapingLogError,
+    parse_shaping_log,
+)
 from design_playbook.scripts.verdict_syntax import VerdictFacts, parse_verdict
 
 
@@ -38,6 +44,10 @@ class RunFacts:
     evidence_dir: Path | None
     spec_text: str
     pointback_text: str
+    plan_text: str
+    plan_fill_artifacts: tuple[str, ...]
+    craft_guard_exists: bool
+    craft_guard_text: str
     ledger: LedgerFacts
     verdict: VerdictFacts
     preview: PreviewSnapshot | None
@@ -46,6 +56,11 @@ class RunFacts:
     _baseline_text: str | None
     baseline_state_error: str | None
     read_errors: tuple[ArtifactReadFact, ...]
+    run_profile: RunProfile | None = None
+    decision_report_text: str = ""
+    decision_entries: tuple[DDEntry, ...] = ()
+    shaping_events: tuple[dict[str, Any], ...] | None = None
+    shaping_error: str | None = None
 
     @property
     def manifest_entries(self) -> tuple[dict[str, Any], ...]:
@@ -60,6 +75,19 @@ class RunFacts:
         return json.loads(self._baseline_text)
 
 
+@dataclass(frozen=True)
+class _OptionalRunFacts:
+    plan_text: str = ""
+    run_profile: RunProfile | None = None
+    decision_report_text: str = ""
+    decision_entries: tuple[DDEntry, ...] = ()
+    shaping_events: tuple[dict[str, Any], ...] | None = None
+    shaping_error: str | None = None
+    craft_guard_exists: bool = False
+    craft_guard_text: str = ""
+    read_errors: tuple[ArtifactReadFact, ...] = ()
+
+
 def _read_manifest(
     evidence_dir: Path | None,
 ) -> tuple[tuple[str, ...], tuple[ArtifactReadFact, ...]]:
@@ -155,6 +183,78 @@ def _existing_paths(run_root: Path | None) -> frozenset[str]:
     return frozenset(paths)
 
 
+def _plan_fill_artifacts(
+    run_root: Path | None,
+    plan_text: str,
+) -> tuple[str, ...]:
+    """Capture existing fill declarations while the run snapshot is loaded."""
+    if run_root is None:
+        return ()
+    found: 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:"):
+            continue
+        declared = line[5:].strip().split()[0].rstrip(",") if line[5:].strip() else ""
+        if not declared:
+            continue
+        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 tuple(found)
+
+
+def _read_optional_run_facts(run_root: Path | None) -> _OptionalRunFacts:
+    """Load optional vNext artifacts into one immutable snapshot."""
+    if run_root is None:
+        return _OptionalRunFacts()
+
+    plan_text, plan_error = _read_text("plan", run_root / "plan.md")
+    profile = parse_run_profile(plan_text) if plan_text else None
+
+    entries: tuple[DDEntry, ...] = ()
+    report_text = ""
+    report = run_root / "decision-report.md"
+    report_text, report_error = _read_text("decision_report", report)
+    if report_text:
+        entries = tuple(parse_dd_entries(report_text))
+
+    shaping_events: tuple[dict[str, Any], ...] | None = None
+    shaping_error: str | None = None
+    shaping_log = run_root / "shaping" / "shaping-log.jsonl"
+    try:
+        if shaping_log.is_file():
+            shaping_events = tuple(
+                parse_shaping_log(shaping_log.read_text(encoding="utf-8"))
+            )
+    except (OSError, UnicodeError, ShapingLogError) as exc:
+        shaping_events = None
+        shaping_error = str(exc)
+    craft_guard_text, craft_error = _read_text(
+        "craft_guard", run_root / "craft-guard.md"
+    )
+    craft_guard_exists = craft_error is None or craft_error.code != "missing"
+    errors = tuple(error for error in (plan_error, report_error, craft_error) if error)
+    return _OptionalRunFacts(
+        plan_text=plan_text,
+        run_profile=profile,
+        decision_report_text=report_text,
+        decision_entries=entries,
+        shaping_events=shaping_events,
+        shaping_error=shaping_error,
+        craft_guard_exists=craft_guard_exists,
+        craft_guard_text=craft_guard_text,
+        read_errors=errors,
+    )
+
+
 def capture_run_facts(
     *,
     spec_path: Path | None = None,
@@ -189,6 +289,7 @@ def capture_run_facts(
     baseline_text, baseline_error = _read_baseline(run_root)
     manifest_lines, manifest_errors = _read_manifest(evidence_dir)
     preview = inspect_preview(preview_dir) if preview_dir is not None else None
+    optional = _read_optional_run_facts(run_root)
     return RunFacts(
         run_root=run_root,
         spec_path=spec_path,
@@ -197,6 +298,10 @@ def capture_run_facts(
         evidence_dir=evidence_dir,
         spec_text=spec_text,
         pointback_text=pointback_text,
+        plan_text=optional.plan_text,
+        plan_fill_artifacts=_plan_fill_artifacts(run_root, optional.plan_text),
+        craft_guard_exists=optional.craft_guard_exists,
+        craft_guard_text=optional.craft_guard_text,
         ledger=parse_ledger(pointback_text),
         verdict=parse_verdict(pointback_text),
         preview=preview,
@@ -208,5 +313,12 @@ def capture_run_facts(
             error
             for error in (spec_error, pointback_error)
             if error is not None
-        ) + manifest_errors,
+        ) + manifest_errors + tuple(
+            error for error in optional.read_errors if error.code != "missing"
+        ),
+        run_profile=optional.run_profile,
+        decision_report_text=optional.decision_report_text,
+        decision_entries=optional.decision_entries,
+        shaping_events=optional.shaping_events,
+        shaping_error=optional.shaping_error,
     )

package/scripts/run_status.py

@@ -11,7 +11,6 @@ from __future__ import annotations
 
 import argparse
 import json
-import re
 import sys
 from dataclasses import dataclass
 from pathlib import Path
@@ -43,22 +42,13 @@ else:
 # its status decision from the shared canonical value.
 from design_playbook.scripts.stages import STAGES, STAGES_BY_KEY  # noqa: E402
 from design_playbook.scripts.run_facts import RunFacts, capture_run_facts  # noqa: E402
-from design_playbook.scripts.run_profile import parse_run_profile  # noqa: E402
-from design_playbook.scripts.shaping_log import (  # noqa: E402
-    ShapingLogError,
-    load_shaping_facts,
-    queue_state,
-)
+from design_playbook.scripts.shaping_log import queue_state  # noqa: E402
 
 # vNext S4 re-entry narration (loop-prototype 7.1): repair rounds, route
 # hit counts, dd supersedes / stale reviews, derived escalation signals,
 # and the close_reason terminal narration, all read from artifacts the
 # gates already consume (additive; plain runs report empty faces).
-from design_playbook.scripts.dd_entries import (  # noqa: E402
-    DD_HEADING,
-    dd_refs_in_pointback,
-    parse_dd_entries,
-)
+from design_playbook.scripts.dd_entries import dd_refs_in_pointback  # noqa: E402
 from design_playbook.scripts.escalation_signals import (  # noqa: E402
     EscalationSignal,
     collect_signals,
@@ -118,25 +108,16 @@ class RepairNarration:
 
 
 def _repair_narration(
-        pointback_text: str, run_root: Path,
-        upgrades: tuple[str, ...]) -> RepairNarration:
+        pointback_text: str,
+        upgrades: tuple[str, ...],
+        decision_entries: tuple,
+) -> RepairNarration:
     """Derive the S4 re-entry faces from artifacts in the run root."""
     rounds = parse_round_facts(pointback_text).max_rounds
     routes = tuple(sorted(route_hits(pointback_text).items()))
     dd_supersedes = len(dd_refs_in_pointback(pointback_text))
-    stale_reviews = 0
-    dd_explore = False
-    report = run_root / "decision-report.md"
-    if report.is_file():
-        try:
-            text = report.read_text(encoding="utf-8")
-        except (OSError, UnicodeError):
-            text = ""
-        if text and DD_HEADING.search(text):
-            entries = parse_dd_entries(text)
-            stale_reviews = sum(
-                1 for entry in entries if entry.stale_review)
-            dd_explore = any(entry.tier == "explore" for entry in entries)
+    stale_reviews = sum(1 for entry in decision_entries if entry.stale_review)
+    dd_explore = any(entry.tier == "explore" for entry in decision_entries)
     signals = list(collect_signals(pointback_text, dd_explore=dd_explore))
     signals.extend(recorded_regrades(upgrades))
     return RepairNarration(
@@ -149,47 +130,36 @@ def _repair_narration(
     )
 
 
-def inspect_vnext(run_root: Path) -> VnextNarration:
-    """Read run-profile (plan.md) and shaping session state (additive)."""
+def inspect_vnext(
+        run_root: Path,
+        run_facts: RunFacts | None = None,
+) -> VnextNarration:
+    """Project vNext facts from one immutable run snapshot."""
+    facts = run_facts or capture_run_facts(run_root=run_root)
     tier = None
     confirmed_by = None
     skipped: tuple[tuple[str, str], ...] = ()
     upgrades: tuple[str, ...] = ()
-    plan_path = run_root / "plan.md"
-    if plan_path.is_file():
-        try:
-            profile = parse_run_profile(
-                plan_path.read_text(encoding="utf-8"))
-        except (OSError, UnicodeError):
-            profile = None
-        if profile is not None:
-            tier = profile.tier or None
-            confirmed_by = profile.confirmed_by or None
-            skipped = profile.skipped
-            upgrades = profile.upgrades
+    profile = facts.run_profile
+    if profile is not None:
+        tier = profile.tier or None
+        confirmed_by = profile.confirmed_by or None
+        skipped = profile.skipped
+        upgrades = profile.upgrades
     shaping: str | None = None
-    try:
-        session = load_shaping_facts(run_root)
-    except (ShapingLogError, OSError, UnicodeError):
+    if facts.shaping_error is not None:
         shaping = "unreadable"
-    else:
-        if session is not None:
-            shaping = queue_state(list(session.events))
-    pointback = run_root / "point-back.md"
-    six_block = False
-    invalidated = False
-    pb_text = ""
-    if pointback.is_file():
-        try:
-            pb_text = pointback.read_text(encoding="utf-8")
-        except (OSError, UnicodeError):
-            pb_text = ""
-        six_block = "## Coverage statement" in pb_text
-        invalidated = "\ninvalidated:" in pb_text or pb_text.startswith(
-            "invalidated:")
+    elif facts.shaping_events is not None:
+        shaping = queue_state(list(facts.shaping_events))
+    pb_text = facts.pointback_text
+    six_block = "## Coverage statement" in pb_text
+    invalidated = "\ninvalidated:" in pb_text or pb_text.startswith(
+        "invalidated:")
     repair = None
     if pb_text:
-        repair = _repair_narration(pb_text, run_root, upgrades)
+        repair = _repair_narration(
+            pb_text, upgrades, facts.decision_entries
+        )
     return VnextNarration(
         tier=tier, confirmed_by=confirmed_by, skipped=skipped,
         upgrades=upgrades, shaping=shaping,
@@ -206,47 +176,7 @@ 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
+# Plan fill declarations are captured by RunFacts; status only projects them.
 
 
 def inspect_run(
@@ -255,7 +185,7 @@ def inspect_run(
 ) -> 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)
+    plan_fills = list(facts.plan_fill_artifacts)
     states: list[StageState] = []
     for stage in STAGES:
         if stage.key == "preview":
@@ -424,24 +354,21 @@ def render(run_root: Path, *, as_json: bool) -> int:
         print(f"RUN STATUS ERROR: not a directory: {run_root}", file=sys.stderr)
         return 2
     facts = capture_run_facts(run_root=run_root)
-    pointback_error = next(
-        (
-            error
-            for error in facts.read_errors
-            if error.artifact == "point_back" and error.code != "missing"
-        ),
+    read_error = next(
+        (error for error in facts.read_errors if error.code != "missing"),
         None,
     )
-    if pointback_error is not None:
+    if read_error is not None:
         print(
-            f"RUN STATUS ERROR: cannot read point-back.md: {pointback_error.message}",
+            f"RUN STATUS ERROR: cannot read {read_error.path.name}: "
+            f"{read_error.message}",
             file=sys.stderr,
         )
         return 2
     snapshot = facts.preview or inspect_preview(run_root / "preview")
     states = inspect_run(run_root, snapshot, facts)
     action = next_action(states, run_root, snapshot, facts)
-    vnext = inspect_vnext(run_root)
+    vnext = inspect_vnext(run_root, facts)
     payload = {
         "run_root": str(run_root),
         "stages": [

package/scripts/validate_run.py

@@ -144,7 +144,7 @@ from design_playbook.scripts.shaping_log import (  # noqa: E402
 from design_playbook.scripts.dd_entries import DD_HEADING  # noqa: E402
 from design_playbook.scripts.g10_design_decisions import check_g10  # noqa: E402
 from design_playbook.scripts.repair_rounds import check_rounds  # noqa: E402
-from design_playbook.scripts.run_profile import parse_run_profile  # noqa: E402
+from design_playbook.scripts.run_profile import validate_run_profile  # noqa: E402
 
 # vNext S3 gates: method-semantics keys (G6-adjacent), interaction-track
 # dimension annotations (G2-adjacent), sampling-matrix gaps (G11), and the
@@ -198,6 +198,17 @@ def run(
         spec_path=Path(spec_path), pointback_path=Path(pb_path),
         preview_dir=pd, evidence_dir=ed, run_root=rr,
     )
+    profile = facts.run_profile
+    if profile is not None:
+        for error in validate_run_profile(profile):
+            errs.append(finding(
+                "G12.run_profile",
+                f"run-profile invalid: {error}",
+                owner="plan.md#run-profile",
+                expected="supported v1 run-profile with valid tier and confirmation",
+                actual=error,
+                repair="Fix the run-profile block before running vNext gates",
+            ))
     operational_errors = tuple(
         error for error in facts.read_errors if error.artifact != "manifest"
     )
@@ -232,7 +243,10 @@ def run(
     # vNext S6: the effective tier P3 makes the matrix block itself
     # mandatory (loop-prototype 1.2 "sampling matrix fully executed").
     errs += check_sampling_matrix(
-        pointback_text, spec_text, evidence_dir=ed, tier=_plan_tier(rr))
+        pointback_text, spec_text, evidence_dir=ed, tier=(
+            effective_tier(profile.tier, profile.upgrades)
+            if profile is not None else None
+        ))
     # G2 dimensions (vNext S3): dimension/face/basis annotations on findings
     # — subjective faces are judgment class (advisory only, source declared).
     errs += check_dimensions(pointback_text)
@@ -309,20 +323,23 @@ def run(
     sd = Path(shaping_dir) if shaping_dir else (
         rr / "shaping" if rr is not None else None
     )
-    shaping_events: list[dict] | None = None
+    shaping_events: list[dict] | None = (
+        list(facts.shaping_events) if facts.shaping_events is not None else None
+    )
     if sd is not None and (sd / Path(SHAPING_LOG).name).is_file():
         errs += check_g9(
             sd,
             project_dir=Path(contract_project) if contract_project else None,
             run_dir=Path(contract_run) if contract_run else rr,
         )
-        # G10 consumes the same session events for the T3 upstream-route
-        # signal; on a malformed log G9 owns the diagnostic and G10 skips.
-        try:
-            shaping_events = parse_shaping_log(
-                (sd / SHAPING_LOG).read_text(encoding="utf-8"))
-        except (OSError, UnicodeError, ShapingLogError):
-            shaping_events = None
+        # Explicit --shaping-dir may point outside the captured run root.
+        # Default discovery already parsed the same log into RunFacts.
+        if shaping_dir is not None:
+            try:
+                shaping_events = parse_shaping_log(
+                    (sd / SHAPING_LOG).read_text(encoding="utf-8"))
+            except (OSError, UnicodeError, ShapingLogError):
+                shaping_events = None
 
     # G10 (conditional): a decision report carrying DD entry blocks engages
     # the design-decision gate (top block stays verbatim; reports without
@@ -330,10 +347,10 @@ def run(
     dr_g10 = dr if dr is not None else (
         rr / "decision-report.md" if rr is not None else None
     )
-    report_text = ""
-    if dr_g10 is not None and dr_g10.is_file():
+    report_text = facts.decision_report_text if dr is None else ""
+    if dr is not None and dr.is_file():
         try:
-            report_text = dr_g10.read_text(encoding="utf-8")
+            report_text = dr.read_text(encoding="utf-8")
         except (OSError, UnicodeError):
             report_text = ""
     if report_text and DD_HEADING.search(report_text):
@@ -343,18 +360,19 @@ def run(
             preview_dir=pd,
             shaping_events=shaping_events,
             pointback_text=pointback_text,
-            baseline_state=_load_json_tolerant(
-                rr / "design-baseline" / "state.json"
-            ) if rr is not None else None,
-            run_profile_tier=_plan_tier(rr),
+            baseline_state=facts.baseline_state,
+            run_profile_tier=(
+                effective_tier(profile.tier, profile.upgrades)
+                if profile is not None else None
+            ),
         )
 
     # G8 run level (vNext S3): a craft-guard.md in the run root is checked
     # against the registry (shared parser). P2/P3 demand one audit row per
     # advisory entry; P1 and tier-less legacy runs keep the subset freedom.
-    if rr is not None and (rr / "craft-guard.md").is_file():
+    if facts.craft_guard_exists:
         try:
-            craft_text = (rr / "craft-guard.md").read_text(encoding="utf-8")
+            craft_text = facts.craft_guard_text
             registry_entries, _ = load_registry()
         except (OSError, UnicodeError):
             errs.append(finding(
@@ -367,13 +385,15 @@ def run(
                 repair="Restore the files or drop the audit log",
             ))
         else:
-            errs += check_g8_run(craft_text, registry_entries, _plan_tier(rr))
+            errs += check_g8_run(craft_text, registry_entries, (
+                effective_tier(profile.tier, profile.upgrades)
+                if profile is not None else None
+            ))
 
     # G12 tier boundary + escalation signals (vNext S4): fires when plan.md
     # carries a run-profile block; legacy runs without the block are not
     # re-checked. The contract diff basis is the G7 bind snapshot; without
     # contract paths the route / decision / blocking faces still fire.
-    profile = _plan_profile(rr)
     if profile is not None:
         touch = None
         bound_criteria = None
@@ -386,10 +406,13 @@ def run(
                     touch = contract_touch(bound, effective)
                     bound_criteria = sum(
                         1 for path in bound if CRITERION_PATH.match(path))
-        dd_explore = bool(
+        dd_explore = any(
+            entry.tier == "explore" for entry in facts.decision_entries
+        ) if dr is None else bool(
             report_text and DD_HEADING.search(report_text)
             and any(entry.tier == "explore"
-                    for entry in parse_dd_entries(report_text)))
+                    for entry in parse_dd_entries(report_text))
+        )
         g12_errs, g12_warns, _signals = check_g12(
             profile,
             pointback_text=pointback_text,
@@ -403,40 +426,6 @@ def run(
     return errs, warns
 
 
-def _load_json_tolerant(path: Path) -> dict | None:
-    try:
-        import json
-
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, ValueError):
-        return None
-    return data if isinstance(data, dict) else None
-
-
-def _plan_profile(run_root: Path | None):
-    """The parsed run-profile block of a run root; None when absent."""
-    if run_root is None:
-        return None
-    plan = run_root / "plan.md"
-    try:
-        return parse_run_profile(plan.read_text(encoding="utf-8"))
-    except (OSError, UnicodeError):
-        return None
-
-
-def _plan_tier(run_root: Path | None) -> str | None:
-    """The run's effective tier: declared tier plus recorded S4 upgrades.
-
-    G8/G10 consume this; after an escalation (run-profile upgrades event)
-    the run walks the new tier's obligations, so the effective tier — not
-    the intake declaration — is the gate input.
-    """
-    profile = _plan_profile(run_root)
-    if profile is None:
-        return None
-    return effective_tier(profile.tier, profile.upgrades)
-
-
 def _parse_args(argv: list[str]) -> argparse.Namespace:
     parser = argparse.ArgumentParser(
         prog="validate_run.py",