@skillcap/gdh 0.13.3 → 0.15.0

package/INSTALL-BUNDLE.json

@@ -1,5 +1,5 @@
 {
   "product": "GDH",
-  "version": "0.13.3",
+  "version": "0.15.0",
   "installMode": "packaged_install"
 }

package/README.md

@@ -12,10 +12,10 @@ GDH detects your Godot project, configures your AI agents, and gives them the co
 ## Install
 
 ```sh
-npx -y @skillcap/gdh@0.13.3 setup
+npx -y @skillcap/gdh@0.15.0 setup
 ```
 
-Replace `0.13.3` with the GDH version you want to pin this project to. `gdh setup` records the pinned version in `.gdh/project.yaml`; every managed surface generated from that config invokes GDH at that exact pinned version, so future sessions stay reproducible.
+Replace `0.15.0` with the GDH version you want to pin this project to. `gdh setup` records the pinned version in `.gdh/project.yaml`; every managed surface generated from that config invokes GDH at that exact pinned version, so future sessions stay reproducible.
 
 From `0.9.0` onward, the shipped package also carries bounded release-span update metadata in `RELEASE-SPAN-UPDATE-CONTRACTS.json` so update flows can explain release-specific migration steps without reading repo-only `docs/releases/` files at target runtime.
 
@@ -36,7 +36,7 @@ The full install and update contract lives in [install-and-update.md](docs/devel
 
 ```sh
 # 1. Run setup in your Godot project
-npx -y @skillcap/gdh@0.13.3 setup
+npx -y @skillcap/gdh@0.15.0 setup
 
 # 2. Open your AI agent (Claude, Cursor, Codex) in the repo
 
@@ -101,7 +101,7 @@ The CLI exists for advanced operators, debugging, and automation. Update preview
 
 ## Status
 
-GDH now ships the current `0.13.3` release line and remains ready for broader internal use within the documented support contract. The current release line is `0.13.3` at the `broader_internal_release` stage.
+GDH now ships the current `0.15.0` release line and remains ready for broader internal use within the documented support contract. The current release line is `0.15.0` at the `broader_internal_release` stage.
 That line includes one first-class Docker-backed rendered runtime provider and bounded screenshot evidence on rendered-capable paths.
 
 The release-stage label applies only to the documented support window in [runtime-support-matrix.md](docs/development/runtime-support-matrix.md) and [runtime-release-readiness.md](docs/development/runtime-release-readiness.md). It is not a blanket claim that every Godot project shape is supported or that this implementation checkout should behave like a GDH-managed target repo.

package/RELEASE-SPAN-UPDATE-CONTRACTS.json

@@ -933,6 +933,164 @@
           }
         ]
       }
+    },
+    {
+      "version": "0.14.0",
+      "releaseTag": "v0.14.0",
+      "migrationStatus": "required",
+      "summary": "v0.14.0 expands state-first runtime verification with node-presence and signal waiters, persists waiter evidence in run records, and refreshes shipped guidance to the canonical rendered-screenshot plus waiter vocabulary. The release changes both GDH_GUIDANCE_UNIT_VERSION (2 -> 3) and GDH_RUNTIME_BRIDGE_SURFACE_VERSION (3 -> 4), so managed targets need release-specific follow-through: bridge-enabled targets repair the runtime bridge and finish plugin/autoload registration, then onboarded targets run `gdh migrate --apply` to regenerate guidance units and return to a healthy lifecycle state.",
+      "releaseHighlights": {
+        "summary": "v0.14.0 pushes GDH runtime verification toward state-first proof instead of ad hoc polling. The managed runtime bridge now supports node-presence and signal-observation waiters, run records preserve waiter evidence and clearer rendered failure classes, and the shipped guidance plus bridge surfaces move to versions `3` and `4`. Because both managed guidance units and the managed runtime bridge surface changed, this release requires a bounded post-update migration path.",
+        "operatorChanges": [
+          "**Bounded waiter coverage expands beyond node-property polling.** The managed runtime bridge now ships the plumbing behind `state.node_presence.await` and `state.signal.await`, so runtime verification can wait on node appearance/disappearance and signal emission through structured bridge evidence instead of open-ended sleep loops.",
+          "**Run records keep waiter evidence and split rendered failures more honestly.** Runtime assertion results now persist waiter evidence and transcripts, inspect surfaces prefer the latest valid run record when local debris exists, and rendered verification feedback now separates screenshot-unavailable, provider/runtime incompatibility, and assertion-failure signals.",
+          "**Project-owned guidance surfaces now reinforce the shipped runtime vocabulary.** Managed guidance units now say `artifact_policy.screenshots: \"rendered\"` is canonical, keep legacy `\"fallback\"` only as a compatibility alias, and carry the bounded `player_reachable` / `internal_route` / `waiter` terminology used by the runtime and verification surfaces.",
+          "**Release safety checks are stricter for maintainers.** `corepack yarn release:preview --json` now refuses stale branch lineages, and required-release migration proof is part of the hard `check:public-release` gate instead of maintainer ceremony only."
+        ]
+      },
+      "updateContract": {
+        "summary": "Managed targets need a release-specific post-update path for v0.14.0 because guidance units move to version 3 and the runtime bridge surface moves to version 4. Bridge-enabled targets repair the managed bridge and finish plugin registration first, then `gdh migrate --apply` refreshes the guidance units and returns the target to a healthy lifecycle state.",
+        "steps": [
+          {
+            "id": "verify_post_update_status",
+            "kind": "mechanical",
+            "summary": "Run the standard post-update lifecycle check.",
+            "detail": "Start with `gdh status` so GDH can tell you whether the target only needs the guidance refresh branch or whether it also entered the bridge-specific repair branch for the v0.14.0 runtime bridge surface update.",
+            "commands": [
+              "gdh status"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          },
+          {
+            "id": "inspect_bridge_specific_branch",
+            "kind": "agent_reasoning",
+            "summary": "Decide whether the target also needs the bridge-specific repair branch.",
+            "detail": "If `gdh status` surfaces `runtime_bridge_*` reasons, inspect `gdh bridge status` and treat that as the v0.14.0 bridge branch. If no runtime-bridge reasons appear, skip the bridge-specific steps and proceed straight to `gdh migrate --apply` for the guidance-unit refresh.",
+            "commands": [
+              "gdh bridge status"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          },
+          {
+            "id": "repair_runtime_bridge_surface",
+            "kind": "mechanical",
+            "summary": "Repair the managed runtime bridge files when the bridge branch is active.",
+            "detail": "Bridge-enabled `v0.13.3` targets drift on the managed bridge files shipped in surface version 4. Run `gdh bridge repair` to rewrite the managed bridge files before attempting the final guidance refresh.",
+            "commands": [
+              "gdh bridge repair"
+            ],
+            "validationCommands": [
+              "gdh bridge status"
+            ]
+          },
+          {
+            "id": "enable_plugin_and_finish_gdhbridge_registration",
+            "kind": "manual_review",
+            "summary": "Enable the GDH Runtime Bridge plugin so GDHBridge registers again.",
+            "detail": "GDH still does not hand-edit `project.godot` for operators. After `gdh bridge repair`, open the project in the Godot editor and enable the `GDH Runtime Bridge` plugin so it can register `GDHBridge` and clear the remaining plugin/autoload reasons.",
+            "commands": [],
+            "validationCommands": [
+              "gdh bridge status",
+              "gdh status"
+            ]
+          },
+          {
+            "id": "refresh_guidance_units_and_validate",
+            "kind": "mechanical",
+            "summary": "Run migrate apply to refresh the guidance units and finish the release hop.",
+            "detail": "Once bridge follow-through is complete, or immediately when the target had no bridge-specific reasons, run `gdh migrate --apply`. This regenerates the managed guidance-unit surfaces at version 3 and should return the target to a healthy lifecycle state.",
+            "commands": [
+              "gdh migrate --apply"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.15.0",
+      "releaseTag": "v0.15.0",
+      "migrationStatus": "required",
+      "summary": "v0.15.0 adds on-demand rendered screenshot capture through the active runtime bridge and refreshes generated guidance so agents use MCP `bridge.entry.invoke` for arbitrary-moment screenshots. The release changes both GDH_GUIDANCE_UNIT_VERSION (3 -> 4) and GDH_RUNTIME_BRIDGE_SURFACE_VERSION (4 -> 5), so managed targets need release-specific follow-through: bridge-enabled targets repair the runtime bridge and finish plugin/autoload registration when required, then onboarded targets run `gdh migrate --apply` to regenerate guidance units and return to a healthy lifecycle state.",
+      "releaseHighlights": {
+        "summary": "v0.15.0 makes rendered screenshots available at the moment an agent needs them. Active runtime bridge sessions now expose a bounded `screenshot.capture` action through MCP `bridge.entry.invoke`, so an agent can launch a game, drive or wait to the target state, and capture the current rendered frame instead of guessing the right screenshot timing at launch. Because the managed guidance units and runtime bridge surface changed, this release requires the bounded post-update migration path.",
+        "operatorChanges": [
+          "**Screenshots are now an on-demand runtime bridge action.** Agents can start a bridge session, use existing bridge entries or waiters to reach the desired state, then invoke `screenshot.capture` to write a PNG plus metadata under the session artifacts.",
+          "**Verification-scenario screenshots stay as supporting run evidence.** `artifact_policy.screenshots: \"rendered\"` still requests one supporting screenshot for a run record, but arbitrary-moment screenshots now use the active bridge session instead of launch-time environment variables.",
+          "**Managed guidance tells agents which screenshot path to use.** Generated `docs/agent/authoring-and-validation.md` now calls out `screenshot.capture` and MCP `bridge.entry.invoke` for interactive runtime work while keeping screenshot scenario truth source-backed.",
+          "**The managed bridge surface moves to the next contract version.** Bridge-enabled targets repair from runtime bridge surface `4` to `5` to receive the `screenshot.capture` entry and matching runtime capture helper."
+        ]
+      },
+      "updateContract": {
+        "summary": "Managed targets need a release-specific post-update path for v0.15.0 because guidance units move to version 4 and the runtime bridge surface moves to version 5. Bridge-enabled targets repair the managed bridge and finish plugin registration first when needed, then `gdh migrate --apply` refreshes the guidance units and returns the target to a healthy lifecycle state.",
+        "steps": [
+          {
+            "id": "verify_post_update_status",
+            "kind": "mechanical",
+            "summary": "Run the standard post-update lifecycle check.",
+            "detail": "Start with `gdh status` so GDH can tell you whether the target only needs the guidance refresh branch or whether it also entered the bridge-specific repair branch for the v0.15.0 runtime bridge surface update.",
+            "commands": [
+              "gdh status"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          },
+          {
+            "id": "inspect_bridge_specific_branch",
+            "kind": "agent_reasoning",
+            "summary": "Decide whether the target also needs the bridge-specific repair branch.",
+            "detail": "If `gdh status` surfaces `runtime_bridge_*` reasons, inspect `gdh bridge status` and treat that as the v0.15.0 bridge branch. If no runtime-bridge reasons appear, skip the bridge-specific steps and proceed straight to `gdh migrate --apply` for the guidance-unit refresh.",
+            "commands": [
+              "gdh bridge status"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          },
+          {
+            "id": "repair_runtime_bridge_surface",
+            "kind": "mechanical",
+            "summary": "Repair the managed runtime bridge files when the bridge branch is active.",
+            "detail": "Bridge-enabled `v0.14.0` targets drift on the managed bridge files shipped in surface version 5. Run `gdh bridge repair` to rewrite the managed bridge files before attempting the final guidance refresh.",
+            "commands": [
+              "gdh bridge repair"
+            ],
+            "validationCommands": [
+              "gdh bridge status"
+            ]
+          },
+          {
+            "id": "enable_plugin_and_finish_gdhbridge_registration",
+            "kind": "manual_review",
+            "summary": "Enable the GDH Runtime Bridge plugin so GDHBridge registers when required.",
+            "detail": "GDH still does not hand-edit `project.godot` for operators. After `gdh bridge repair`, if bridge status still reports plugin/autoload follow-through, open the project in the Godot editor and enable the `GDH Runtime Bridge` plugin so it can register `GDHBridge`.",
+            "commands": [],
+            "validationCommands": [
+              "gdh bridge status",
+              "gdh status"
+            ]
+          },
+          {
+            "id": "refresh_guidance_units_and_validate",
+            "kind": "mechanical",
+            "summary": "Run migrate apply to refresh guidance units and finish the release hop.",
+            "detail": "Once bridge follow-through is complete, or immediately when the target had no bridge-specific reasons, run `gdh migrate --apply`. This regenerates the managed guidance-unit surfaces at version 4 and should return the target to a healthy lifecycle state.",
+            "commands": [
+              "gdh migrate --apply"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
     }
   ]
 }

package/node_modules/@gdh/adapters/package.json

@@ -11,13 +11,13 @@
     }
   },
   "dependencies": {
-    "@gdh/authoring": "0.13.3",
-    "@gdh/core": "0.13.3",
-    "@gdh/docs": "0.13.3",
-    "@gdh/observability": "0.13.3",
-    "@gdh/runtime": "0.13.3",
-    "@gdh/scan": "0.13.3",
-    "@gdh/verify": "0.13.3"
+    "@gdh/authoring": "0.15.0",
+    "@gdh/core": "0.15.0",
+    "@gdh/docs": "0.15.0",
+    "@gdh/observability": "0.15.0",
+    "@gdh/runtime": "0.15.0",
+    "@gdh/scan": "0.15.0",
+    "@gdh/verify": "0.15.0"
   },
-  "version": "0.13.3"
+  "version": "0.15.0"
 }

package/node_modules/@gdh/authoring/package.json

@@ -14,7 +14,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@gdh/core": "0.13.3"
+    "@gdh/core": "0.15.0"
   },
-  "version": "0.13.3"
+  "version": "0.15.0"
 }

package/node_modules/@gdh/cli/package.json

@@ -15,16 +15,16 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.2.0",
-    "@gdh/adapters": "0.13.3",
-    "@gdh/authoring": "0.13.3",
-    "@gdh/core": "0.13.3",
-    "@gdh/docs": "0.13.3",
-    "@gdh/mcp": "0.13.3",
-    "@gdh/observability": "0.13.3",
-    "@gdh/runtime": "0.13.3",
-    "@gdh/scan": "0.13.3",
-    "@gdh/verify": "0.13.3",
+    "@gdh/adapters": "0.15.0",
+    "@gdh/authoring": "0.15.0",
+    "@gdh/core": "0.15.0",
+    "@gdh/docs": "0.15.0",
+    "@gdh/mcp": "0.15.0",
+    "@gdh/observability": "0.15.0",
+    "@gdh/runtime": "0.15.0",
+    "@gdh/scan": "0.15.0",
+    "@gdh/verify": "0.15.0",
     "picocolors": "^1.1.1"
   },
-  "version": "0.13.3"
+  "version": "0.15.0"
 }

package/node_modules/@gdh/core/dist/index.d.ts

@@ -10,7 +10,7 @@ export declare const GDH_SCENARIO_SCHEMA_VERSION = 2;
 export declare const GDH_RULES_SCHEMA_VERSION = 1;
 export declare const GDH_AGENT_CONTRACT_VERSION = 1;
 export declare const GDH_GUIDANCE_INDEX_VERSION = 2;
-export declare const GDH_GUIDANCE_UNIT_VERSION = 2;
+export declare const GDH_GUIDANCE_UNIT_VERSION = 4;
 export declare const GDH_GUIDANCE_AUDIT_VERSION = 1;
 export declare const GDH_AUTHORING_SESSION_VERSION = 2;
 export declare const GDH_AUTHORING_DOGFOOD_VERSION = 1;
@@ -21,7 +21,7 @@ export declare const GDH_UPDATE_HOOK_VERSION = 1;
 export declare const GDH_RUNTIME_RECIPE_RUN_VERSION = 1;
 export declare const GDH_RUNTIME_RUN_BUNDLE_VERSION = 1;
 export declare const GDH_RUNTIME_CORPUS_ARTIFACT_VERSION = 1;
-export declare const GDH_RUNTIME_BRIDGE_SURFACE_VERSION = 3;
+export declare const GDH_RUNTIME_BRIDGE_SURFACE_VERSION = 5;
 export type GdhProductReleaseStage = "targeted_internal_use" | "broader_internal_release" | "external_or_public_preview";
 export type GdhCurrentInstallMode = "development_checkout" | "packaged_install";
 export type GdhProductCompatibilityState = "compatible" | "migration_available" | "migration_needed" | "migration_blocked" | "compatibility_degraded";
@@ -883,6 +883,8 @@ export type GdhRuntimeBridgeSessionStartState = "ready" | "blocked" | "failed";
 export type GdhRuntimeBridgeEntryListState = "ready" | "missing";
 export type GdhRuntimeBridgeStopState = "stopped" | "missing";
 export type GdhRuntimeBridgeInvocationState = "ok" | "unavailable" | "busy" | "failed" | "cancelled";
+export type GdhRuntimeBridgeWaiterId = "state.node_property.await" | "state.node_presence.await" | "state.signal.await";
+export type GdhRuntimeBridgeWaiterOutcome = "satisfied" | "timed_out";
 export type GdhFailureAttribution = "project_issue" | "environment_issue" | "recipe_issue" | "scenario_issue" | "gdh_gap" | "agent_judgment_issue" | "unknown";
 export interface GdhProjectRootReference {
     readonly path: string;
@@ -1359,6 +1361,7 @@ export interface GdhRuntimeBridgeInvocationResult {
     readonly summary: string;
     readonly reasons: readonly string[];
     readonly result: GdhJsonValue | null;
+    readonly waiterEvidence: GdhRuntimeBridgeWaiterEvidence | null;
     readonly transcriptPath: string | null;
 }
 export interface GdhRuntimeBridgeSessionStopResult {
@@ -1449,6 +1452,16 @@ export interface GdhRuntimeRecipeRunResult {
     readonly artifacts: readonly GdhRuntimeArtifactReference[];
     readonly statusPromotion: GdhRuntimeStatusPromotion;
 }
+export interface GdhRuntimeBridgeWaiterEvidence {
+    readonly waiterId: GdhRuntimeBridgeWaiterId;
+    readonly outcome: GdhRuntimeBridgeWaiterOutcome;
+    readonly startedAt: string;
+    readonly finishedAt: string;
+    readonly timeoutMs: number;
+    readonly pollCount: number;
+    readonly target: Readonly<Record<string, GdhJsonValue>>;
+    readonly result: GdhJsonValue | null;
+}
 export interface GdhScenarioAssertionDefinition {
     readonly id: string;
     readonly summary: string;
@@ -1468,6 +1481,13 @@ export interface GdhScenarioExecutionPolicy {
 export interface GdhScenarioRetryPolicy {
     readonly maxAttempts: number;
 }
+export interface GdhScenarioRuntimeAssertionDefinition {
+    readonly id: string;
+    readonly summary: string;
+    readonly waiter: GdhRuntimeBridgeWaiterId;
+    readonly input: Readonly<Record<string, GdhJsonValue>>;
+    readonly required: boolean;
+}
 export interface GdhScenarioDefinition {
     readonly schemaVersion: typeof GDH_SCENARIO_SCHEMA_VERSION;
     readonly id: string;
@@ -1478,6 +1498,7 @@ export interface GdhScenarioDefinition {
     readonly setupSteps: readonly string[];
     readonly actions: readonly string[];
     readonly assertions: readonly GdhScenarioAssertionDefinition[];
+    readonly runtimeAssertions: readonly GdhScenarioRuntimeAssertionDefinition[];
     readonly artifactPolicy: GdhScenarioArtifactPolicy;
     readonly executionPolicy: GdhScenarioExecutionPolicy;
     readonly retryPolicy: GdhScenarioRetryPolicy;
@@ -1550,6 +1571,19 @@ export interface GdhHarnessFeedbackItem {
     readonly summary: string;
     readonly details: readonly string[];
 }
+export interface GdhRuntimeScenarioRuntimeAssertionResult {
+    readonly id: string;
+    readonly summary: string;
+    readonly required: boolean;
+    readonly waiter: GdhRuntimeBridgeWaiterId;
+    readonly input: Readonly<Record<string, GdhJsonValue>>;
+    readonly status: GdhScenarioAssertionStatus;
+    readonly state: GdhRuntimeBridgeInvocationState;
+    readonly reasons: readonly string[];
+    readonly result: GdhJsonValue | null;
+    readonly waiterEvidence: GdhRuntimeBridgeWaiterEvidence | null;
+    readonly transcriptPath: string | null;
+}
 export interface GdhRuntimeScenarioAttemptResult {
     readonly attemptNumber: number;
     readonly startedAt: string;
@@ -1560,6 +1594,7 @@ export interface GdhRuntimeScenarioAttemptResult {
     readonly recipeRun: GdhRuntimeRecipeRunResult;
     readonly inspection: readonly GdhRuntimeInspectionSource[];
     readonly assertions: readonly GdhScenarioAssertionResult[];
+    readonly runtimeAssertions: readonly GdhRuntimeScenarioRuntimeAssertionResult[];
     readonly feedback: readonly GdhHarnessFeedbackItem[];
 }
 export interface GdhRuntimeRunBundle {