design-playbook 0.22.0 → 0.22.2

package/mcp/run_console/test_repair_packet.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 from copy import deepcopy
 import hashlib
 import json
+import re
 import sys
 import unittest
 from pathlib import Path
@@ -26,6 +27,8 @@ from design_playbook.mcp.run_console.contract import (  # noqa: E402
     validate_snapshot,
 )
 from design_playbook.mcp.run_console.repair_packet import (  # noqa: E402
+    MSG_ABSENT_ASSERTION,
+    MSG_DISPOSITION_UNKNOWN,
     MSG_NO_BLOCKING,
     MSG_NO_COMMAND,
     MSG_NO_INVALIDATED,
@@ -46,6 +49,33 @@ _HTML = (_DIR / "app.html").read_text(encoding="utf-8")
 _CSS = (_DIR / "app.css").read_text(encoding="utf-8")
 _COMMAND = "qoder run --resume run_example --next ui-evaluator"
 
+# Cross-implementation locks: app.js carries a second copy of the packet
+# derivation and copy renderer, including the seven shared gap messages.
+# The zh-CN strings pin the localized reason copy; the tuple pins every
+# shared message constant so a one-sided edit fails a gate.
+_ZH_NO_INVALIDATED = "快照未投影失效证据集。"
+_ZH_NO_RECAPTURE = "快照未投影重采要求。"
+_ZH_NO_RESUME_STAGE = "快照未投影明确的恢复阶段；最新观测阶段并非恢复目标。"
+_ZH_NO_COMMAND = "本次快照中该动作未携带可复制的智能体指令。"
+_ZH_NO_BLOCKING = "本次快照未投影任何阻塞性发现。"
+_ZH_DISPOSITION_UNKNOWN = "存在发现，但其是否阻塞并非责任方已知。"
+_ZH_ASSERTION_ABSENT = "此断言在快照中缺失。"
+_ZH_COPY_HEADING = "修复包（派生视图；仅复制；绝不执行）"
+
+_JS_MSG_TO_PY = (
+    ("PACKET_MSG_ABSENT", MSG_ABSENT_ASSERTION),
+    ("PACKET_MSG_NO_BLOCKING", MSG_NO_BLOCKING),
+    ("PACKET_MSG_DISPOSITION_UNKNOWN", MSG_DISPOSITION_UNKNOWN),
+    ("PACKET_MSG_NO_INVALIDATED", MSG_NO_INVALIDATED),
+    ("PACKET_MSG_NO_RECAPTURE", MSG_NO_RECAPTURE),
+    ("PACKET_MSG_NO_RESUME_STAGE", MSG_NO_RESUME_STAGE),
+    ("PACKET_MSG_NO_COMMAND", MSG_NO_COMMAND),
+)
+
+_COPY_LINE_SHAPE = re.compile(
+    r"^([^(]+) \((known|unknown|stale|inconsistent)\): (.*)$"
+)
+
 _PLAYWRIGHT = None
 _BROWSER = None
 
@@ -117,6 +147,74 @@ def _blocking_snapshot(*, command: str | None = None) -> dict[str, object]:
         label="Verdict is Recirculate — repair from point-back findings.",
         owner={"actor": "agent", "role": None},
         copyableAgentCommand=command,
+        invalidatedEvidence=["L6.3"],
+        resumeStage="ui-evaluator",
+        recaptureRequirement=(
+            "Recapture only invalidated evidence, then re-run ui-evaluator."
+        ),
+    )
+    return document
+
+
+def _js_packet_message_constants() -> dict[str, str]:
+    """Extract the PACKET_MSG_* constants from the shipped app.js source."""
+    pattern = re.compile(r'var (PACKET_MSG_\w+) =((?:\s*"[^"]*"(?:\s*\+)*)+\s*);')
+    return {
+        name: "".join(re.findall(r'"([^"]*)"', expression))
+        for name, expression in pattern.findall(_JS)
+    }
+
+
+def _stale_inconsistent_snapshot() -> dict[str, object]:
+    """Degraded snapshot: a stale intent plus an inconsistent verdict."""
+    document = _valid()
+    document["identity"]["snapshot"]["buildState"] = "degraded"  # type: ignore[index]
+    document["sources"]["items"][0].update(  # type: ignore[index]
+        verifiedHash=contract_fixtures._HASH_2, freshness="changed"
+    )
+    _bind_source_set_hash(document)
+    summary = document["intent"]["summary"]  # type: ignore[index]
+    summary.update(
+        availability="stale",
+        reason=_reason(
+            "source-changed-during-build",
+            ["source.common"],
+            observed_hashes=[contract_fixtures._HASH_1],
+            verified_hashes=[contract_fixtures._HASH_2],
+        ),
+    )
+    summary["source"].update(verifiedSetHash=contract_fixtures._HASH_2)  # type: ignore[union-attr]
+    verdict = document["evaluation"]["verdict"]  # type: ignore[index]
+    verdict.update(
+        availability="inconsistent",
+        result=None,
+        reason=_reason(
+            "conflicting-authorities",
+            ["source.common", "source.evaluator-report"],
+            observed_hashes=[contract_fixtures._HASH_1, contract_fixtures._HASH_3],
+            verified_hashes=[contract_fixtures._HASH_1, contract_fixtures._HASH_3],
+            conflicts=[
+                {
+                    "sourceRef": "source.evaluator-report",
+                    "hash": contract_fixtures._HASH_3,
+                    "summary": "verdict contradicts the findings ledger",
+                }
+            ],
+        ),
+    )
+    verdict["source"]["refs"] = ["source.common", "source.evaluator-report"]  # type: ignore[union-attr]
+    return document
+
+
+def _unreadable_finding_snapshot() -> dict[str, object]:
+    """Degraded snapshot: the only finding has an owner-unknown disposition."""
+    document = _valid()
+    document["identity"]["snapshot"]["buildState"] = "degraded"  # type: ignore[index]
+    finding = document["evaluation"]["findings"][0]  # type: ignore[index]
+    finding.update(
+        availability="unknown",
+        result=None,
+        reason=_reason("owner-unmapped", ["source.common"]),
     )
     return document
 
@@ -165,8 +263,13 @@ class RepairPacketProjectionTest(unittest.TestCase):
         self.assertEqual(packet["nextCommand"]["reason"]["code"], NOT_PRODUCED)
         label = "Verdict is Recirculate — repair from point-back findings."
         self.assertNotEqual(packet["nextCommand"]["value"], label)
-        self.assertEqual(packet["invalidatedEvidence"]["availability"], "unknown")
-        self.assertEqual(packet["recaptureRequirement"]["availability"], "unknown")
+        self.assertEqual(packet["invalidatedEvidence"]["availability"], "known")
+        self.assertEqual(packet["invalidatedEvidence"]["value"], ["L6.3"])
+        self.assertEqual(packet["recaptureRequirement"]["availability"], "known")
+        self.assertEqual(
+            packet["recaptureRequirement"]["value"],
+            "Recapture only invalidated evidence, then re-run ui-evaluator.",
+        )
 
     def test_owner_supplied_command_is_copied_verbatim(self) -> None:
         packet = derive_repair_packet(_blocking_snapshot(command=_COMMAND))
@@ -174,18 +277,17 @@ class RepairPacketProjectionTest(unittest.TestCase):
         self.assertEqual(packet["nextCommand"]["value"], _COMMAND)
         self.assertIn(_COMMAND, packet["copyText"])
 
-    def test_resume_stage_is_a_gap_not_inferred_from_progress_or_command(self) -> None:
+    def test_resume_stage_is_owner_explicit_and_not_inferred_from_progress(self) -> None:
         """Spec rule 19: latest observed stage is not a resume target."""
         document = _blocking_snapshot(command=_COMMAND)
         progress = document["execution"]["progress"]  # type: ignore[index]
         progress["result"]["latestObservedStage"] = "fill"  # type: ignore[index]
         packet = derive_repair_packet(document)
-        self.assertEqual(packet["resumeStage"]["availability"], "unknown")
-        self.assertIsNone(packet["resumeStage"]["value"])
-        self.assertEqual(packet["resumeStage"]["reason"]["code"], NOT_PRODUCED)
-        self.assertEqual(packet["resumeStage"]["reason"]["message"], MSG_NO_RESUME_STAGE)
+        self.assertEqual(packet["resumeStage"]["availability"], "known")
+        self.assertEqual(packet["resumeStage"]["value"], "ui-evaluator")
+        self.assertIsNone(packet["resumeStage"]["reason"])
         rendered = json.dumps(packet["resumeStage"])
-        self.assertNotIn("fill", rendered)
+        self.assertNotIn('"fill"', rendered)
         self.assertNotIn("--resume", rendered)
 
     def test_stale_intent_is_stale_context_not_current(self) -> None:
@@ -305,10 +407,16 @@ class RepairPacketRenderContractTest(unittest.TestCase):
         self.assertNotIn("/api/v1/actions/rerun", _JS)
         self.assertNotIn("executeRepair", _JS)
 
-    def test_resume_stage_is_a_static_gap_not_derived_from_progress(self) -> None:
-        self.assertIn("packetGap(PACKET_MSG_NO_RESUME_STAGE)", _JS)
+    def test_resume_stage_comes_from_owner_next_action_not_progress(self) -> None:
+        # Owner-produced resumeStage rides nextActions.primary; the JS
+        # helper keeps the gap message when the owner did not produce it.
+        # Never invent a packetResumeStage parser over progress.
+        self.assertIn("packetNextActionField(", _JS)
+        self.assertIn('"resumeStage"', _JS)
+        self.assertIn("PACKET_MSG_NO_RESUME_STAGE", _JS)
         self.assertIn("packet_not_produced_resume_stage", _JS)
         self.assertNotIn("packetResumeStage", _JS)
+        self.assertNotIn("execution.progress", _JS.split("function deriveRepairPacket")[1].split("function ")[0])
 
     def test_ui_route_table_is_unchanged(self) -> None:
         resources = UIResources()
@@ -375,8 +483,12 @@ class RepairPacketBrowserTest(browser_harness.BrowserTestCase):
         self.assertIn("add a consequence-confirmation dialog", packet)
         self.assertIn("declaration", self._field("declarationOwner").inner_text())
         self.assertIn("agent", self._field("nextOwner").inner_text())
-        self.assertIn("not project an invalidated-evidence set", packet)
-        self.assertIn("not project a recapture requirement", packet)
+        self.assertIn("L6.3", self._field("invalidatedEvidence").inner_text())
+        self.assertIn("ui-evaluator", self._field("resumeStage").inner_text())
+        self.assertIn(
+            "Recapture only invalidated evidence",
+            self._field("recaptureRequirement").inner_text(),
+        )
         self.assertNotIn("Pass", self._field("verdict").inner_text())
 
     def test_blocked_run_copy_advances_the_journey_with_owner_command(self) -> None:
@@ -548,3 +660,181 @@ class RepairPacketBrowserTest(browser_harness.BrowserTestCase):
         expect(self._packet()).to_be_visible()
         width = self.page.evaluate("() => document.scrollingElement.scrollWidth")
         self.assertLessEqual(width, 320 + 2)
+
+
+class RepairPacketCrossImplementationTest(browser_harness.BrowserTestCase):
+    """JS and Python must derive and render the same packet.
+
+    app.js re-implements the projection and copy renderer from
+    repair_packet.py, including the seven shared gap messages. A silent
+    drift would flip the localized UI back to English reasons with no
+    failing gate, so every assertion here is a fail-direction lock: the
+    same snapshot is rendered through the real browser and its copied
+    summary is compared against the Python projection. Interface labels
+    may differ per locale, so the comparison splits each copy line into
+    label, availability, and reason parts instead of raw equality.
+    """
+
+    def _open_via_route(self, snapshot: dict[str, object]) -> None:
+        def fulfill(route):
+            route.fulfill(
+                status=200,
+                content_type="application/json",
+                body=json.dumps(snapshot),
+            )
+
+        # A repeated goto to the identical URL is a same-document no-op, so
+        # leave the document first: every variant must render from a clean
+        # page (fresh language state, single active route handler).
+        self.page.goto("about:blank")
+        self.page.unroute("**/api/v1/snapshot")
+        self.page.route("**/api/v1/snapshot", fulfill)
+        self.page.goto(self.console.url(f"#token={self.console.token}"))
+        expect(self.page.locator("#view-ready")).to_be_visible()
+
+    def _copy_summary(self, *, status_text: str = "plain text") -> str:
+        self.context.grant_permissions(["clipboard-read", "clipboard-write"])
+        self.page.locator("#packet-copy-summary").click()
+        expect(self.page.locator("#packet-copy-summary-status")).to_contain_text(
+            status_text
+        )
+        text = self.page.evaluate("() => navigator.clipboard.readText()")
+        # Chromium normalizes written LF to CRLF on the Windows clipboard.
+        return text.replace("\r\n", "\n").replace("\r", "\n")
+
+    def _assert_copy_summary_matches(self, packet, summary: str) -> None:
+        py_lines = packet["copyText"].split("\n")
+        js_lines = summary.split("\n")
+        self.assertEqual(len(js_lines), len(py_lines))
+        self.assertEqual(js_lines[0], py_lines[0])
+        for index, key in enumerate(PACKET_KEYS, start=1):
+            py_match = _COPY_LINE_SHAPE.match(py_lines[index])
+            js_match = _COPY_LINE_SHAPE.match(js_lines[index])
+            self.assertIsNotNone(py_match, py_lines[index])
+            self.assertIsNotNone(js_match, js_lines[index])
+            self.assertEqual(js_match.group(1), py_match.group(1), f"{key} label")
+            self.assertEqual(
+                js_match.group(2), py_match.group(2), f"{key} availability"
+            )
+            reason = packet[key]["reason"]
+            if not (
+                isinstance(reason, dict) and (reason.get("code") or reason.get("message"))
+            ):
+                # Known facts carry no reason, so the whole line must agree.
+                self.assertEqual(js_lines[index], py_lines[index], f"{key} line")
+                continue
+            code = reason.get("code") or ""
+            message = reason.get("message") or ""
+            separator = ": " if code and message else ""
+            expected_tail = f" ({code}{separator}{message})"
+            self.assertTrue(
+                js_match.group(3).endswith(expected_tail),
+                f"{key}: JS reason drifted from the Python projection: "
+                f"{js_lines[index]!r} does not end with {expected_tail!r}",
+            )
+
+    def _zh_reason(self, key: str) -> str:
+        return self.page.locator(
+            f'#repair-packet-grid [data-packet-field="{key}"] .reason-block'
+        ).inner_text()
+
+    def _switch_to_zh(self) -> None:
+        self.page.locator("#lang-toggle-button").click()
+        expect(self.page.locator("html")).to_have_attribute("lang", "zh-CN")
+
+    def _disposition_unknown_snapshot(self) -> dict[str, object]:
+        # Unknown assertions in valid snapshots always carry a reason, so
+        # the fallback message is only reachable through the browser copy.
+        snapshot = self.console.snapshot()
+        snapshot["evaluation"]["findings"] = [deepcopy(
+            contract_fixtures._valid_snapshot()["evaluation"]["findings"][0]
+        )]
+        finding = snapshot["evaluation"]["findings"][0]
+        finding["availability"] = "unknown"
+        finding["result"] = None
+        finding["reason"] = None
+        return snapshot
+
+    def _absent_summary_snapshot(self) -> dict[str, object]:
+        snapshot = self.console.snapshot()
+        snapshot["intent"]["summary"] = None
+        return snapshot
+
+    def test_js_and_python_gap_message_constants_are_identical(self) -> None:
+        js_constants = _js_packet_message_constants()
+        for js_name, py_message in _JS_MSG_TO_PY:
+            with self.subTest(constant=js_name):
+                self.assertIn(js_name, js_constants)
+                self.assertEqual(js_constants[js_name], py_message)
+
+    def test_real_server_copy_summary_matches_python_projection(self) -> None:
+        # Completed (Pass) and blocked (Recirculate with an owner command)
+        # snapshots both come from the real server, covering the known
+        # value lines and the no-blocking/no-command gap messages.
+        for point_back in ("point-back-pass-closed.md", "point-back-recirculate.md"):
+            with self.subTest(point_back=point_back):
+                self.console.close()
+                self.console = browser_harness.ConsoleHarness(point_back=point_back)
+                self.addCleanup(self.console.close)
+                self.open()
+                summary = self._copy_summary()
+                packet = derive_repair_packet(self.console.snapshot())
+                self._assert_copy_summary_matches(packet, summary)
+
+    def test_fulfilled_variants_copy_summary_match_python_projection(self) -> None:
+        # Degraded snapshots a real server never produces are injected by
+        # same-origin route interception, matching the harness convention.
+        for name, snapshot in (
+            ("stale-intent-and-inconsistent-verdict", _stale_inconsistent_snapshot()),
+            ("unreadable-finding-disposition", _unreadable_finding_snapshot()),
+        ):
+            with self.subTest(variant=name):
+                packet = derive_repair_packet(snapshot)
+                self._open_via_route(snapshot)
+                summary = self._copy_summary()
+                self._assert_copy_summary_matches(packet, summary)
+
+    def test_zh_ui_renders_localized_reasons_not_english_fallback(self) -> None:
+        self.open()
+        self._switch_to_zh()
+        for key, zh_message, en_message in (
+            ("invalidatedEvidence", _ZH_NO_INVALIDATED, MSG_NO_INVALIDATED),
+            ("recaptureRequirement", _ZH_NO_RECAPTURE, MSG_NO_RECAPTURE),
+            ("resumeStage", _ZH_NO_RESUME_STAGE, MSG_NO_RESUME_STAGE),
+            ("nextCommand", _ZH_NO_COMMAND, MSG_NO_COMMAND),
+            ("finding", _ZH_NO_BLOCKING, MSG_NO_BLOCKING),
+        ):
+            with self.subTest(field=key):
+                text = self._zh_reason(key)
+                self.assertIn(zh_message, text)
+                self.assertNotIn(en_message, text)
+        summary = self._copy_summary(status_text="纯文本")
+        self.assertIn(_ZH_COPY_HEADING, summary)
+        for zh_message, en_message in (
+            (_ZH_NO_INVALIDATED, MSG_NO_INVALIDATED),
+            (_ZH_NO_RECAPTURE, MSG_NO_RECAPTURE),
+            (_ZH_NO_RESUME_STAGE, MSG_NO_RESUME_STAGE),
+            (_ZH_NO_COMMAND, MSG_NO_COMMAND),
+            (_ZH_NO_BLOCKING, MSG_NO_BLOCKING),
+        ):
+            with self.subTest(copy=zh_message):
+                self.assertIn(zh_message, summary)
+                self.assertNotIn(en_message, summary)
+
+    def test_zh_ui_localizes_reasons_only_reachable_in_the_browser(self) -> None:
+        # The Python contract always demands a reason on unknown assertions,
+        # so these two fallback messages exist only on the browser side and
+        # cannot be cross-checked through a valid snapshot.
+        scenarios = (
+            ("disposition-unknown", self._disposition_unknown_snapshot(),
+             "finding", _ZH_DISPOSITION_UNKNOWN, MSG_DISPOSITION_UNKNOWN),
+            ("absent-summary", self._absent_summary_snapshot(),
+             "intent", _ZH_ASSERTION_ABSENT, MSG_ABSENT_ASSERTION),
+        )
+        for name, snapshot, key, zh_message, en_message in scenarios:
+            with self.subTest(scenario=name):
+                self._open_via_route(snapshot)
+                self._switch_to_zh()
+                text = self._zh_reason(key)
+                self.assertIn(zh_message, text)
+                self.assertNotIn(en_message, text)

package/mcp/run_console/test_snapshot_builder.py

@@ -35,6 +35,9 @@ from design_playbook.mcp.preview.integrity import (  # noqa: E402
 from design_playbook.mcp.run_console.contract import (  # noqa: E402
     validate_snapshot,
 )
+from design_playbook.mcp.run_console.repair_packet import (  # noqa: E402
+    derive_repair_packet,
+)
 from design_playbook.mcp.run_console.snapshot_builder import (  # noqa: E402
     BuiltSnapshot,
     SnapshotBuildError,
@@ -547,6 +550,67 @@ class DegradingBuildTest(_BuilderTestCase):
         verdict = _assertion(document, "evaluation.verdict")
         self.assertEqual(verdict["availability"], "known")
         self.assertEqual(verdict["result"], "Recirculate")
+        result = document["nextActions"]["primary"]["result"]
+        self.assertEqual(result["invalidatedEvidence"], ["L6.3"])
+        self.assertEqual(result["resumeStage"], "ui-evaluator")
+        self.assertEqual(
+            result["recaptureRequirement"],
+            "Recapture only invalidated evidence, then re-run ui-evaluator.",
+        )
+
+    def test_recirculate_missing_invalidation_stays_unknown_in_packet(self) -> None:
+        (self.run_root / "point-back.md").write_text(
+            _RECIRCULATE_POINTBACK.split("invalidated:", 1)[0], encoding="utf-8"
+        )
+
+        document = self._rebuild()
+        packet = derive_repair_packet(document)
+
+        self.assertIsNone(
+            document["nextActions"]["primary"]["result"]["invalidatedEvidence"]
+        )
+        self.assertEqual(packet["invalidatedEvidence"]["availability"], "unknown")
+        self.assertIsNone(packet["invalidatedEvidence"]["value"])
+        self.assertEqual(
+            packet["invalidatedEvidence"]["reason"]["code"], "not-produced"
+        )
+        self.assertEqual(packet["resumeStage"]["value"], "ui-evaluator")
+
+    def test_recirculate_malformed_invalidation_preserves_packet_gap(self) -> None:
+        malformed_entries = (
+            "  - criterion: L6.4 extra-token\n",
+            "  - criterion:\n",
+            "  - criterion L6.4\n",
+            "  - unknown: L6.4\n",
+            "  -\n",
+            "  - criterion: ../private\n",
+            "  criterion: L6.4\n",
+            "invalidated:\n",
+        )
+        for malformed_entry in malformed_entries:
+            with self.subTest(entry=malformed_entry):
+                (self.run_root / "point-back.md").write_text(
+                    _RECIRCULATE_POINTBACK.split("invalidated:", 1)[0]
+                    + "invalidated:\n  - criterion: L6.3\n"
+                    + malformed_entry
+                    + "  - criterion: L6.5\n",
+                    encoding="utf-8",
+                )
+
+                document = self._rebuild()
+                packet = derive_repair_packet(document)
+
+                self.assertIsNone(
+                    document["nextActions"]["primary"]["result"]["invalidatedEvidence"]
+                )
+                self.assertEqual(
+                    packet["invalidatedEvidence"]["availability"], "unknown"
+                )
+                self.assertIsNone(packet["invalidatedEvidence"]["value"])
+                self.assertEqual(
+                    packet["invalidatedEvidence"]["reason"]["code"], "not-produced"
+                )
+                self.assertEqual(packet["resumeStage"]["value"], "ui-evaluator")
 
     def test_truncated_contract_bind_is_partial_write(self) -> None:
         (self.run_root / "contract-bind.json").write_text(

package/mcp/ui_locale.py

@@ -8,7 +8,14 @@ EN = "en"
 
 
 def resolve_ui_locale(locale: str | None = None) -> str:
-    """Explicit locale wins; keep the adapter's documented CJK-first env policy."""
+    """Explicit locale wins; keep the adapter's documented CJK-first env policy.
+
+    A blank explicit locale means "unspecified" (forms and MCP callers
+    encode absence as an empty string) and falls back like ``None``;
+    anything else still fails closed with ``ValueError``.
+    """
+    if locale is not None and not locale.strip():
+        locale = None
     raw = locale if locale is not None else (
         os.environ.get("DPB_PREVIEW_LANG") or os.environ.get("LANG") or ZH
     )

package/package.json

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

@@ -26,6 +26,7 @@ PublicClaim = Literal[
     "not-shipped",
 ]
 FallbackKind = Literal["safe-path", "evidence-gap"]
+GateState = Literal["not-satisfied", "satisfied", "unknown"]
 
 _IMPLEMENTATION_VALUES = frozenset(("absent", "present", "unknown"))
 _VALIDATION_VALUES = frozenset(
@@ -35,6 +36,7 @@ _AVAILABILITY_VALUES = frozenset(("local", "distributed", "unsupported", "unknow
 _PUBLIC_CLAIM_VALUES = frozenset(
     ("stable", "experimental", "blocked-by-gate", "not-shipped")
 )
+_GATE_STATE_VALUES = frozenset(("not-satisfied", "satisfied", "unknown"))
 
 
 class CapabilityReceiptError(ValueError):
@@ -56,10 +58,14 @@ class CapabilitySourceFacts:
     availability: AvailabilityState | None = None
     entrypoint: str | None = None
     prerequisites: tuple[str, ...] = ()
+    inputs: tuple[str, ...] = ()
     fallback: str | None = None
     evidence_gap: str | None = None
     public_claim: PublicClaim | None = None
     gate_blocked: bool = False
+    gate_id: str | None = None
+    gate_state: GateState | None = None
+    gate_detail: str | None = None
 
 
 @dataclass(frozen=True)
@@ -91,6 +97,18 @@ class FallbackProjection:
         return {"kind": self.kind, "detail": self.detail}
 
 
+@dataclass(frozen=True)
+class GateProjection:
+    """Named gate outcome supplied by an existing gate authority."""
+
+    id: str
+    state: GateState
+    detail: str | None
+
+    def to_dict(self) -> dict[str, str | None]:
+        return {"id": self.id, "state": self.state, "detail": self.detail}
+
+
 @dataclass(frozen=True)
 class CapabilityReceipt:
     """Immutable, read-time capability receipt."""
@@ -99,8 +117,10 @@ class CapabilityReceipt:
     status: CapabilityStatus
     entrypoint: str | None
     prerequisites: tuple[str, ...]
+    inputs: tuple[str, ...]
     fallback: FallbackProjection | None
     evidence_gap: str | None
+    gate: GateProjection | None
 
     def to_dict(self) -> dict[str, object]:
         return {
@@ -108,9 +128,11 @@ class CapabilityReceipt:
             "status": self.status.to_dict(),
             "entrypoint": self.entrypoint,
             "prerequisites": list(self.prerequisites),
+            "inputs": list(self.inputs),
             "fallback": self.fallback.to_dict() if self.fallback else None,
             "publicClaim": self.status.public_claim,
             "evidenceGap": self.evidence_gap,
+            "gate": self.gate.to_dict() if self.gate else None,
         }
 
 
@@ -135,6 +157,16 @@ def _normalise_text(name: str, value: str | None) -> str | None:
     return value.strip()
 
 
+def _normalise_gate(facts: CapabilitySourceFacts) -> GateProjection | None:
+    if facts.gate_id is None and facts.gate_state is None:
+        return None
+    gate_id = _normalise_text("gate-id", facts.gate_id)
+    if gate_id is None or facts.gate_state not in _GATE_STATE_VALUES:
+        raise CapabilityReceiptError("gate-invalid")
+    detail = _normalise_text("gate-detail", facts.gate_detail)
+    return GateProjection(id=gate_id, state=facts.gate_state, detail=detail)
+
+
 def _normalise_facts(facts: CapabilitySourceFacts) -> tuple[
     str,
     ImplementationState,
@@ -159,6 +191,14 @@ def _normalise_facts(facts: CapabilitySourceFacts) -> tuple[
         if normalized is None:
             raise CapabilityReceiptError("prerequisite-invalid")
         prerequisites.append(normalized)
+    if not isinstance(facts.inputs, tuple):
+        raise CapabilityReceiptError("inputs-invalid")
+    inputs: list[str] = []
+    for source_input in facts.inputs:
+        normalized = _normalise_text("input", source_input)
+        if normalized is None:
+            raise CapabilityReceiptError("input-invalid")
+        inputs.append(normalized)
     public_claim = facts.public_claim
     if public_claim is not None and (
         not isinstance(public_claim, str)
@@ -180,6 +220,7 @@ def _normalise_facts(facts: CapabilitySourceFacts) -> tuple[
         ),
         _normalise_text("entrypoint", facts.entrypoint),
         tuple(prerequisites),
+        tuple(inputs),
         _normalise_text("fallback", facts.fallback),
         _normalise_text("evidence-gap", facts.evidence_gap),
         public_claim,
@@ -226,10 +267,12 @@ def build_capability_receipt(
         availability,
         entrypoint,
         prerequisites,
+        inputs,
         fallback_text,
         supplied_gap,
-        requested_claim,
+    requested_claim,
     ) = _normalise_facts(facts)
+    gate = _normalise_gate(facts)
     public_claim = _derive_public_claim(
         implementation=implementation,
         validation=validation,
@@ -262,6 +305,10 @@ def build_capability_receipt(
         gaps.append("surface is unsupported")
     if facts.gate_blocked or requested_claim == "blocked-by-gate":
         gaps.append("capability is blocked by gate")
+    if gate is not None and gate.state == "not-satisfied":
+        gaps.append(f"{gate.id} is not satisfied")
+        if gate.detail:
+            gaps.append(gate.detail)
     if requested_claim == "stable" and public_claim != "stable":
         gaps.append("stable public claim rejected by incomplete readiness evidence")
     if supplied_gap:
@@ -284,8 +331,8 @@ def build_capability_receipt(
         ),
         entrypoint=entrypoint,
         prerequisites=prerequisites,
+        inputs=inputs,
         fallback=fallback,
         evidence_gap=evidence_gap,
+        gate=gate,
     )
-
-