Add promotion gate observability and abort visibility

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,9 +1,5 @@
 MODEL: GPT-5.4-codex
 REASONING: high
-
 COMMAND:
-Execute exactly docs/pr/BUILD_PR_PROMOTION_GATE_56_AUTHORITATIVE_PASSIVE_HANDOFF_BOUNDARY.md.
-Modify only the exact target files listed in the PR doc.
-Do not expand scope.
-Package the delta zip to:
-<project folder>/tmp/BUILD_PR_PROMOTION_GATE_56_AUTHORITATIVE_PASSIVE_HANDOFF_BOUNDARY_delta.zip
+Execute docs/pr/BUILD_PR_PROMOTION_GATE_57_OBSERVABILITY_ABORT.md exactly.
+Package to <project folder>/tmp/BUILD_PR_PROMOTION_GATE_57_OBSERVABILITY_ABORT_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-Make the promotion-gate authoritative/passive handoff boundary explicit across the exact gate/state/snapshot files.
+Add promotion gate observability and abort visibility

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-After commit, inspect the delta and build the next exact promotion-gate slice only if observability/abort files are explicit.
+Next: validation closeout

docs/dev/reports/change_summary.txt

@@ -1,3 +1 @@
-- narrow promotion-gate BUILD focused on authoritative/passive handoff boundary only
-- exact target files limited to promotion gate + world game state system + promotion snapshot
-- explicitly excludes replay/timeline/sample/game/debug widening
+narrow slice

docs/dev/reports/file_tree.txt

@@ -1,10 +1,3 @@
-docs/pr/BUILD_PR_PROMOTION_GATE_56_AUTHORITATIVE_PASSIVE_HANDOFF_BOUNDARY.md
-docs/dev/codex_commands.md
-docs/dev/commit_comment.txt
-docs/dev/next_command.txt
-docs/dev/reports/file_tree.txt
-docs/dev/reports/change_summary.txt
-docs/dev/reports/validation_checklist.txt
 src/advanced/promotion/createPromotionGate.js
-src/advanced/state/createWorldGameStateSystem.js
-src/shared/state/createPromotionStateSnapshot.js
+src/engine/debug/panels/PromotionGatePanel.js
+src/shared/state/createPromotionStateSnapshot.js

docs/dev/reports/validation_checklist.txt

@@ -1,6 +1 @@
-- single PR purpose only
-- exact target files only
-- executable BUILD with Codex command included
-- no roadmap edits
-- no docs-only commit intent
-- no replay/timeline/sample/game/debug scope expansion
+exact files only

docs/pr/BUILD_PR_PROMOTION_GATE_57_OBSERVABILITY_ABORT.md

@@ -0,0 +1,15 @@
+# BUILD PR — Promotion Gate Observability + Abort Visibility
+
+## Files
+- src/advanced/promotion/createPromotionGate.js
+- src/engine/debug/panels/PromotionGatePanel.js
+- src/shared/state/createPromotionStateSnapshot.js
+
+## Actions
+- expose gate status (mode, handoff, abort flag)
+- surface minimal data to debug panel (no new subsystem)
+- add explicit abort/rollback visibility path
+
+## Constraints
+- exact files only
+- no replay/timeline/sample changes

docs/pr/BUILD_PR_PROMOTION_GATE_58_VALIDATION_CLOSEOUT.md

@@ -0,0 +1,13 @@
+# BUILD PR — Promotion Gate Validation + Closeout
+
+## Files
+- src/advanced/promotion/createPromotionGate.js
+- src/shared/state/createPromotionStateSnapshot.js
+
+## Actions
+- add validation hooks/checklist alignment
+- ensure gate can run full cycle (passive→authoritative→abort)
+- no feature expansion
+
+## Constraints
+- exact files only

src/advanced/promotion/createPromotionGate.js

@@ -48,6 +48,20 @@ function createHandoffDecision({ promoted, promotedNow }) {
   };
 }
 
+function resolveGateMode({ promoted }) {
+  return promoted ? 'authoritative' : 'passive';
+}
+
+function createAbortVisibility({ rollbackTriggered, promoted, reason }) {
+  const aborted = Boolean(rollbackTriggered) && !promoted;
+  return {
+    decisionPath: 'PROMOTION_GATE_ABORT_VISIBILITY',
+    rollbackTriggered: Boolean(rollbackTriggered),
+    aborted,
+    reason: aborted ? 'ROLLBACK_ABORTED_PROMOTION' : String(reason || '')
+  };
+}
+
 function createPromotionGate(options = {}) {
   const now = typeof options.now === 'function' ? options.now : () => Date.now();
   const requiredCriteria = sanitizeRequiredCriteria(options.requiredCriteria);
@@ -136,12 +150,19 @@ function createPromotionGate(options = {}) {
     const readiness = promoted
       ? 'authoritative'
       : (allCriteriaMet ? 'stabilizing' : 'passive');
+    const mode = resolveGateMode({ promoted });
     const handoff = createHandoffDecision({ promoted, promotedNow });
+    const abort = createAbortVisibility({
+      rollbackTriggered,
+      promoted,
+      reason: lastReason
+    });
     const evaluation = {
       transitionName: String(transitionName || ''),
       frame: frame !== undefined && frame !== null ? Number(frame) : null,
       timestampMs,
       readiness,
+      mode,
       promoted,
       promotedNow,
       rollbackTriggered: Boolean(rollbackTriggered),
@@ -155,6 +176,7 @@ function createPromotionGate(options = {}) {
         allMet: allCriteriaMet
       },
       handoff,
+      abort,
       reason: lastReason,
       metrics: getMetrics()
     };

src/engine/debug/panels/PromotionGatePanel.js

@@ -0,0 +1,59 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/09/2026
+PromotionGatePanel.js
+*/
+
+import { drawPanel } from '../DebugPanel.js';
+
+function asObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function resolvePromotionStatus(source) {
+  const snapshot = asObject(source);
+  const evaluation = asObject(snapshot.lastEvaluation);
+  const status = asObject(snapshot.status);
+  const handoff = asObject(status.handoff).toMode ? status.handoff : asObject(evaluation.handoff);
+  const abort = asObject(status.abort).decisionPath ? status.abort : asObject(evaluation.abort);
+  const mode = typeof status.mode === 'string' && status.mode
+    ? status.mode
+    : (typeof evaluation.mode === 'string' && evaluation.mode ? evaluation.mode : 'passive');
+  return {
+    mode,
+    handoff,
+    abort,
+    reason: String(snapshot.lastReason || evaluation.reason || ''),
+    stability: asObject(evaluation.stability)
+  };
+}
+
+export function getPromotionGatePanelLines(promotionState) {
+  const status = resolvePromotionStatus(promotionState);
+  const handoffLabel = status.handoff.toMode
+    ? `${String(status.handoff.fromMode || 'passive')} -> ${String(status.handoff.toMode)}`
+    : 'n/a';
+  const abortVisible = status.abort.rollbackTriggered === true || status.abort.aborted === true;
+  const abortLabel = abortVisible
+    ? `${status.abort.aborted === true ? 'ABORTED' : 'VISIBLE'} (${String(status.abort.reason || 'rollback')})`
+    : 'no';
+
+  return [
+    `Mode: ${status.mode}`,
+    `Handoff: ${handoffLabel}`,
+    `Abort: ${abortLabel}`,
+    `Stable: ${Number(status.stability.currentFrames || 0)}/${Number(status.stability.requiredFrames || 0)}`,
+    `Reason: ${status.reason || 'n/a'}`
+  ];
+}
+
+export function drawPromotionGatePanel(renderer, promotionState, {
+  x = 620,
+  y = 184,
+  width = 300,
+  height = 146,
+  title = 'Promotion Gate'
+} = {}) {
+  drawPanel(renderer, x, y, width, height, title, getPromotionGatePanelLines(promotionState));
+}