fix(release): decouple promotion readiness from project goals (#2727)

* fix(release): record promotion readiness outside goals

* test(release): cover runtime readiness ledger

* docs(release): define runtime readiness evidence

* fix(release): make runtime readiness authoritative

Author: huangruiteng

docs/guides/getting-started.md

@@ -963,6 +963,11 @@ loopx promotion-gate --format json
 loopx upgrade-plan --format json
 ```
 
+When the dashboard source is present, the readiness smoke requires its npm
+dependencies so a dependency skip cannot be recorded as a pass. Use
+`--dashboard-mode=skip` only when intentionally qualifying a release boundary
+that omits dashboard validation; the runtime evidence records that skip.
+
 ## Documentation Map
 
 Start here:

docs/quota-allocation.md

@@ -799,8 +799,9 @@ When the status payload has missing, stale, or unknown canary promotion
 readiness evidence, `quota should-run` also includes
 `promotion_readiness_warning`. This warning is additive: it does not change
 `should_run`, but it lets heartbeat workers and dashboards report release
-readiness blockers from the shared run-history projection without parsing
-`doctor`, dashboard copy, or chat reports. Before promoting the local release
+readiness blockers from the shared runtime release ledger without parsing
+`doctor`, dashboard copy, or chat reports. New evidence is stored there rather
+than in a project Goal. Before promoting the local release
 snapshot, run `python3 examples/canary/canary-promotion-readiness-smoke.py` and
 confirm fresh evidence in status or doctor output. The
 `--no-write-evidence` form remains the non-mutating validation path and therefore

docs/status-data-contract.md

@@ -376,8 +376,10 @@ goals must stay out of the eligible lane even when they have a high
   },
   "promotion_readiness_summary": {
     "available": true,
-    "source": "run_history",
-    "goal_id": "loopx-meta",
+    "source": "runtime_release_ledger",
+    "evidence_scope": "runtime_release",
+    "goal_id": null,
+    "dashboard_readiness": "passed",
     "generated_at": "2026-06-01T00:08:00+00:00",
     "classification": "canary_promotion_readiness_smoke_group",
     "delivery_batch_scale": "multi_surface",
@@ -391,7 +393,7 @@ goals must stay out of the eligible lane even when they have a high
     "age_seconds": 120,
     "age_hours": 0.03,
     "sample_run_count": 1,
-    "proxy_note": "canary promotion-readiness projection from append-only run history; exact evidence stays in run artifacts"
+    "proxy_note": "canary promotion-readiness projection from the runtime release ledger with legacy goal-history fallback; exact evidence stays in append-only artifacts"
   },
   "promotion_gate": {
     "ok": true,
@@ -527,6 +529,18 @@ the stable fields.
 consume one state contract instead of re-deriving release-readiness state
 separately.
 
+After the release checks pass, the canary uses the explicit write boundary:
+
+```bash
+loopx promotion-readiness record \
+  --dashboard-readiness passed \
+  --execute
+```
+
+Without `--execute`, this command only previews the runtime-level append. The
+canary supplies `skipped` only for an explicit dashboard omission; dependency
+failures on a present dashboard source must not be recorded as `passed`.
+
 Fresh shape:
 
 ```json
@@ -542,7 +556,10 @@ Fresh shape:
   "recommended_action": "promotion readiness is fresh",
   "readiness": {
     "available": true,
-    "goal_id": "loopx-meta",
+    "source": "runtime_release_ledger",
+    "evidence_scope": "runtime_release",
+    "goal_id": null,
+    "dashboard_readiness": "passed",
     "classification": "canary_promotion_readiness_smoke_group",
     "freshness_status": "fresh",
     "requires_readiness_run": false,
@@ -2170,10 +2187,14 @@ leaderboard claim.
 ## Promotion Readiness Summary
 
 `promotion_readiness_summary` is an optional release-control projection over the
-same sampled run history. It finds the latest
+runtime release ledger, with legacy Goal run-history events retained as a
+read-compatible fallback only when the runtime ledger has no valid readiness
+event. It finds the latest
 `canary_promotion_readiness_smoke_group` event and reports whether that evidence
 is fresh enough to trust before promoting a live checkout into the default local
-release snapshot.
+release snapshot. New evidence is runtime-scoped because release readiness is
+shared by every Goal using that local installation; it does not require or
+mutate a project Goal.
 
 The summary reports:
 
@@ -2185,8 +2206,11 @@ The summary reports:
   parseable.
 - `json_exists` / `markdown_exists`: whether the latest evidence artifacts still
   exist.
+- `dashboard_readiness`: `passed` or `skipped` for runtime-level evidence, so a
+  deliberate omission is never indistinguishable from a successful check.
 
-This projection does not promote anything and does not replace the run artifact.
+This projection does not promote anything and does not replace the append-only
+release artifact under the LoopX runtime root.
 `scripts/install-local.sh` consumes the same readiness fact only to print a
 non-blocking warning; operators should still run `loopx doctor` or the
 canary-promotion readiness smoke for exact local release evidence.
@@ -2234,8 +2258,8 @@ not rolling the repository or project back to the old chat context.
 evidence is missing, stale, or unknown. The warning is a release-readiness guard
 surface, not a scheduling decision: it does not flip `should_run`, but it lets a
 heartbeat worker report that the release snapshot should not be promoted until
-fresh canary promotion-readiness evidence is written back to the shared
-run-history projection. This keeps release readiness in queryable control-plane
+fresh canary promotion-readiness evidence is written to the shared runtime
+release ledger. This keeps release readiness in queryable control-plane
 state instead of relying on dashboard prose, `doctor` output, or a chat thread.
 The warning message names the writeback command,
 `python3 examples/canary/canary-promotion-readiness-smoke.py`. A run with

examples/canary/canary-promotion-no-write-contract-smoke.py

@@ -5,7 +5,6 @@
 
 from pathlib import Path
 
-
 REPO_ROOT = Path(__file__).resolve().parents[2]
 CANARY_SMOKE = REPO_ROOT / "examples" / "canary" / "canary-promotion-readiness-smoke.py"
 DASHBOARD_DEMO_SMOKE = REPO_ROOT / "examples" / "dashboard-demo-readiness-smoke.py"
@@ -30,12 +29,13 @@ def main() -> int:
     dashboard_source = DASHBOARD_DEMO_SMOKE.read_text(encoding="utf-8")
 
     assert_contains(canary_source, "--no-write-evidence", "canary no-write flag")
-    assert_contains(canary_source, "--goal-id", "canary refresh-state goal id flag")
-    assert_contains(canary_source, "DEFAULT_READINESS_GOAL_ID", "canary default writeback goal")
-    assert_contains(canary_source, "--agent-id", "canary refresh-state agent id flag")
-    assert_contains(canary_source, "DEFAULT_READINESS_AGENT_ID", "canary default writeback agent")
-    assert_contains(canary_source, "DEFAULT_READINESS_AGENT_LANE", "canary default writeback lane")
+    assert_contains(canary_source, '"promotion-readiness"', "runtime release evidence command")
+    assert_contains(canary_source, '"record"', "promotion-readiness record action")
+    assert_contains(canary_source, '"--execute"', "explicit evidence write flag")
+    if "refresh-state" in canary_source or "--goal-id" in canary_source:
+        raise AssertionError("promotion readiness evidence must not require a project Goal")
     assert_contains(canary_source, "dashboard-demo-readiness-smoke.py", "canary dashboard demo-readiness command")
+    assert_contains(canary_source, "--require-dependencies", "dashboard dependency fail-closed flag")
     assert_contains(canary_source, 'commands.append(("dashboard demo readiness", dashboard_command))', "canary grouped path append")
     assert_before(
         canary_source,

examples/canary/canary-promotion-readiness-boundary-smoke.py

@@ -10,6 +10,7 @@
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
 CANARY_PATH = REPO_ROOT / "examples" / "canary" / "canary-promotion-readiness-smoke.py"
+DASHBOARD_PATH = REPO_ROOT / "examples" / "dashboard-demo-readiness-smoke.py"
 
 
 def load_canary_module():
@@ -23,8 +24,22 @@ def load_canary_module():
     return module
 
 
+def load_dashboard_module():
+    spec = importlib.util.spec_from_file_location(
+        "dashboard_demo_readiness_smoke",
+        DASHBOARD_PATH,
+    )
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
 def main() -> int:
     canary = load_canary_module()
+    dashboard = load_dashboard_module()
+    assert dashboard.missing_dependency_exit_code(require_dependencies=False) == 0
+    assert dashboard.missing_dependency_exit_code(require_dependencies=True) == 1
     with tempfile.TemporaryDirectory() as tmp:
         root = Path(tmp)
         release_dashboard = root / "release" / "apps" / "presentation" / "dashboard"
@@ -58,13 +73,15 @@ def main() -> int:
 
         source_plan = canary.dashboard_readiness_plan(dashboard_dir=source_dashboard)
         assert source_plan["status"] == "run", source_plan
-        assert source_plan["command"][-1] == "--skip-browser", source_plan
+        assert "--require-dependencies" in source_plan["command"], source_plan
+        assert "--skip-browser" in source_plan["command"], source_plan
 
         source_browser_plan = canary.dashboard_readiness_plan(
             dashboard_dir=source_dashboard,
             include_browser=True,
         )
         assert source_browser_plan["status"] == "run", source_browser_plan
+        assert "--require-dependencies" in source_browser_plan["command"], source_browser_plan
         assert "--skip-browser" not in source_browser_plan["command"], source_browser_plan
 
     print("canary-promotion-readiness-boundary-smoke ok")

examples/canary/canary-promotion-readiness-smoke.py

@@ -5,9 +5,9 @@
 local release snapshot. It validates the public boundary, status projections,
 installer wrappers, and dashboard demo-readiness path without mutating the
 installed release. By default, a successful run appends one public-safe
-promotion-readiness evidence event to the LoopX run history so status,
-doctor, and quota guards can clear stale or missing readiness warnings from the
-append-only ledger.
+promotion-readiness evidence event to the runtime release ledger so status,
+doctor, and quota guards can clear stale or missing readiness warnings without
+requiring a project Goal.
 """
 
 from __future__ import annotations
@@ -18,27 +18,13 @@
 import sys
 from pathlib import Path
 
-
 REPO_ROOT = Path(__file__).resolve().parents[2]
 DASHBOARD_DIR = REPO_ROOT / "apps" / "presentation" / "dashboard"
 
 COMMON_NODE_PATHS = [
     "/opt/homebrew/bin",
     "/usr/local/bin",
 ]
-DEFAULT_READINESS_GOAL_ID = "loopx-meta"
-DEFAULT_READINESS_AGENT_ID = "codex-product-capability"
-DEFAULT_READINESS_AGENT_LANE = "product_capability_catalog_canary"
-READINESS_CLASSIFICATION = "canary_promotion_readiness_smoke_group"
-READINESS_DELIVERY_OUTCOME = "surface_only"
-READINESS_RECOMMENDED_ACTION = (
-    "Canary promotion-readiness smoke passed; promotion may proceed after doctor/status reports fresh evidence."
-)
-READINESS_RECOMMENDED_ACTION_DASHBOARD_SKIPPED = (
-    "Canary promotion-readiness smoke passed for the installed release boundary; "
-    "dashboard readiness was skipped because apps/presentation/dashboard is not shipped in the release snapshot."
-)
-
 BASE_COMMANDS = [
     (
         "public boundary contract",
@@ -71,30 +57,6 @@ def parse_args() -> argparse.Namespace:
         action="store_true",
         help="Run checks only; do not append the promotion-readiness evidence event.",
     )
-    parser.add_argument(
-        "--goal-id",
-        default=os.environ.get("LOOPX_GOAL_ID") or DEFAULT_READINESS_GOAL_ID,
-        help=(
-            "Registered goal id used for the readiness evidence writeback. "
-            "Defaults to LOOPX_GOAL_ID or loopx-meta."
-        ),
-    )
-    parser.add_argument(
-        "--agent-id",
-        default=os.environ.get("LOOPX_AGENT_ID") or DEFAULT_READINESS_AGENT_ID,
-        help=(
-            "Registered agent id used for the readiness evidence writeback. "
-            "Defaults to LOOPX_AGENT_ID or codex-product-capability."
-        ),
-    )
-    parser.add_argument(
-        "--agent-lane",
-        default=os.environ.get("LOOPX_AGENT_LANE") or DEFAULT_READINESS_AGENT_LANE,
-        help=(
-            "Public-safe agent lane label used for the readiness evidence writeback. "
-            "Defaults to LOOPX_AGENT_LANE or product_capability_catalog_canary."
-        ),
-    )
     return parser.parse_args()
 
 
@@ -117,44 +79,17 @@ def write_readiness_evidence(
     env: dict[str, str],
     *,
     dashboard_skipped: bool,
-    goal_id: str | None = None,
-    agent_id: str | None = None,
-    agent_lane: str | None = None,
 ) -> None:
-    recommended_action = (
-        READINESS_RECOMMENDED_ACTION_DASHBOARD_SKIPPED
-        if dashboard_skipped
-        else READINESS_RECOMMENDED_ACTION
-    )
-    resolved_agent_id = (
-        agent_id or os.environ.get("LOOPX_AGENT_ID") or DEFAULT_READINESS_AGENT_ID
-    ).strip()
-    resolved_goal_id = (
-        goal_id or os.environ.get("LOOPX_GOAL_ID") or DEFAULT_READINESS_GOAL_ID
-    ).strip()
-    resolved_agent_lane = (
-        agent_lane or os.environ.get("LOOPX_AGENT_LANE") or DEFAULT_READINESS_AGENT_LANE
-    ).strip()
     command = [
         sys.executable,
         "-m",
         "loopx.cli",
-        "refresh-state",
-        "--goal-id",
-        resolved_goal_id,
-        "--classification",
-        READINESS_CLASSIFICATION,
-        "--recommended-action",
-        recommended_action,
-        "--delivery-batch-scale",
-        "multi_surface",
-        "--delivery-outcome",
-        READINESS_DELIVERY_OUTCOME,
+        "promotion-readiness",
+        "record",
+        "--dashboard-readiness",
+        "skipped" if dashboard_skipped else "passed",
+        "--execute",
     ]
-    if resolved_agent_id:
-        command.extend(["--agent-id", resolved_agent_id])
-    if resolved_agent_lane:
-        command.extend(["--agent-lane", resolved_agent_lane])
     run_command(
         "promotion readiness evidence writeback",
         command,
@@ -176,7 +111,11 @@ def dashboard_readiness_plan(
             "command": None,
         }
     if has_dashboard:
-        command = [sys.executable, "examples/dashboard-demo-readiness-smoke.py"]
+        command = [
+            sys.executable,
+            "examples/dashboard-demo-readiness-smoke.py",
+            "--require-dependencies",
+        ]
         if not include_browser:
             command.append("--skip-browser")
         return {
@@ -229,9 +168,6 @@ def main() -> int:
         write_readiness_evidence(
             env,
             dashboard_skipped=dashboard_plan["status"] == "skip",
-            goal_id=args.goal_id,
-            agent_id=args.agent_id,
-            agent_lane=args.agent_lane,
         )
         evidence_suffix = " with evidence writeback"