@skillcap/gdh 0.17.2 → 0.18.1

package/INSTALL-BUNDLE.json

@@ -1,5 +1,5 @@
 {
   "product": "GDH",
-  "version": "0.17.2",
+  "version": "0.18.1",
   "installMode": "packaged_install"
 }

package/RELEASE-SPAN-UPDATE-CONTRACTS.json

@@ -1471,6 +1471,175 @@
           }
         ]
       }
+    },
+    {
+      "version": "0.18.0",
+      "releaseTag": "v0.18.0",
+      "migrationStatus": "required",
+      "summary": "v0.18.0 adds current-scene, whole-tree, and arbitrary-subtree runtime bridge discovery, refreshes managed bridge guidance and agent entrypoints, and refactors generated bridge internals to native Godot APIs. The release changes GDH_AGENT_CONTRACT_VERSION (1 -> 2), GDH_GUIDANCE_UNIT_VERSION (7 -> 8), GDH_CURSOR_RULE_VERSION (1 -> 2), and GDH_RUNTIME_BRIDGE_SURFACE_VERSION (7 -> 10), so managed targets need adapter/guidance migration and bridge repair before they are treated as current.",
+      "releaseHighlights": {
+        "summary": "v0.18.0 improves runtime bridge discoverability for agents and tightens managed agent entrypoints. Agents can now ask the bridge for the current scene, search from the whole SceneTree, or search from an arbitrary node path when the target is outside the active scene. Managed guidance and Cursor/AGENTS entrypoints now point agents directly at the bridge usage guidance, and the generated bridge uses native Godot APIs for node search, inheritance-aware type checks, and indexed property reads.",
+        "operatorChanges": [
+          "**Runtime bridge node discovery is broader and clearer.** `scene.current.get` returns the current scene snapshot, `scene.tree.nodes.find` searches from `SceneTree.root`, and `scene.node.nodes.find` searches below one `rootNodePath`.",
+          "**Existing active-scene search stays stable.** `scene.nodes.find` remains the active-scene scoped query for ordinary scene-local discovery.",
+          "**Bridge guidance is easier to find.** Managed `AGENTS.md` and Cursor rule surfaces now direct agents to `docs/agent/authoring-and-validation.md` for runtime bridge usage.",
+          "**Generated runtime guidance names the discovery boundary.** Agents are told when to use active-scene search, whole-tree search, or bounded arbitrary-subtree search.",
+          "**Bridge internals now lean on native Godot APIs.** Generated bridge code uses `Node.find_children`, `Object.is_class`, GDScript property membership, and `Object.get_indexed` instead of manual tree walking, exact class-string matching, property-list scans, and flat property reads.",
+          "**Maintainer release/publish skills are namespaced.** GDH repo maintainer-only adapters use the `gdh-dev-*` / `/gdh-dev:*` namespace to reduce confusion with target-project GDH skills."
+        ]
+      },
+      "updateContract": {
+        "summary": "Managed targets need release-specific migration for v0.18.0 because agent contract, Cursor rule, guidance, and runtime bridge surfaces changed. Agents should inspect status, rebake adapter surfaces when drift is reported, migrate guidance, repair the runtime bridge when drift is active, complete plugin/autoload follow-through when required, and validate the target lifecycle.",
+        "steps": [
+          {
+            "id": "verify_post_update_status",
+            "kind": "mechanical",
+            "summary": "Run the standard post-update lifecycle check.",
+            "detail": "Start with `gdh status` so GDH can report whether the target needs guidance migration, adapter repair, runtime bridge repair, or plugin/autoload follow-through for v0.18.0.",
+            "commands": [
+              "gdh status"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          },
+          {
+            "id": "rebake_agent_adapters",
+            "kind": "mechanical",
+            "summary": "Re-bake supported-agent entrypoint surfaces when drift is active.",
+            "detail": "When GDH reports adapter drift, run `gdh adapters install <target>` so managed AGENTS.md and Cursor rule surfaces carry the runtime bridge guidance pointer at the current surface versions.",
+            "commands": [
+              "gdh adapters install <target>"
+            ],
+            "validationCommands": [
+              "gdh adapters status <target>",
+              "gdh verify drift <target>"
+            ]
+          },
+          {
+            "id": "apply_guidance_migration",
+            "kind": "mechanical",
+            "summary": "Apply managed guidance migration.",
+            "detail": "When `gdh status` or `gdh migrate` reports guidance migration work, run `gdh migrate --apply` to refresh guidance units with current-scene, whole-tree, and arbitrary-subtree bridge discovery instructions.",
+            "commands": [
+              "gdh migrate --apply"
+            ],
+            "validationCommands": [
+              "gdh guidance status",
+              "gdh status"
+            ]
+          },
+          {
+            "id": "inspect_bridge_repair_branch",
+            "kind": "agent_reasoning",
+            "summary": "Decide whether runtime bridge repair is active for this target.",
+            "detail": "If lifecycle output surfaces runtime-bridge reasons, inspect `gdh bridge status` and treat the surfaced terminal commands as release-specific follow-up. If no runtime-bridge reasons appear, no release-specific bridge repair is needed.",
+            "commands": [
+              "gdh bridge status"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          },
+          {
+            "id": "repair_runtime_bridge_surface",
+            "kind": "mechanical",
+            "summary": "Repair managed runtime bridge files when drift is active.",
+            "detail": "Bridge-enabled targets on older runtime bridge surfaces drift until they are repaired to runtime bridge surface version 10. Run `gdh bridge repair` to rewrite the managed bridge addon with `scene.current.get`, whole-tree node search, arbitrary-subtree node search, and native Godot API internals.",
+            "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 does not hand-edit `project.godot` for operators. After 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": "validate_repaired_lifecycle",
+            "kind": "mechanical",
+            "summary": "Validate guidance, adapter, bridge, and project lifecycle after migration.",
+            "detail": "After migration, adapter rebake, bridge repair, and any plugin follow-through, rerun `gdh guidance status`, `gdh adapters status`, `gdh bridge status`, and `gdh status`. The target should return to the current lifecycle state for the refreshed surfaces.",
+            "commands": [
+              "gdh guidance status",
+              "gdh adapters status <target>",
+              "gdh bridge status",
+              "gdh status"
+            ],
+            "validationCommands": [
+              "gdh guidance status",
+              "gdh adapters status <target>",
+              "gdh bridge status",
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.18.1",
+      "releaseTag": "v0.18.1",
+      "migrationStatus": "no_op",
+      "summary": "v0.18.1 closes Session 8 (TheBeacon 2026-04-25) dogfooding regressions on the upgrade path without changing managed project schema or lifecycle surface versions. Existing targets do not need release-scoped schema migration; the ordinary `gdh migrate --apply` flow now cleans up stale managed `.codex/skills/<skill>/SKILL.md` files and auto-refreshes default-content `.gdh/rules.yaml` whose schema-version header is behind.",
+      "releaseHighlights": {
+        "summary": "v0.18.1 closes Session 8 (TheBeacon 2026-04-25) dogfooding regressions on the upgrade path: stale managed `.codex/skills/<skill>/SKILL.md` files now get cleaned up during migrate regardless of which prior GDH version rendered them, and a `.gdh/rules.yaml` that still carries a prior-version header but matches the current default boilerplate now refreshes automatically through `gdh migrate --apply` instead of blocking behind `manual_review_required`. Real customizations still gate on manual review and now ship actionable `manualSteps` that steer agents away from `/gdh-update` (which only changes the installed GDH version, not the on-disk schema marker).",
+        "operatorChanges": [
+          "**Stale legacy `.codex/skills/<skill>/SKILL.md` files are removed during migrate.** `gdh migrate --apply` now detects managed legacy Codex skills by the `<codex_skill_adapter>` marker every render embeds, so stale-version managed files (e.g. a `.codex/skills/gdh-migrate/SKILL.md` still pinning `0.16.0` after the target moved to `0.18.x`) get cleaned up. User-authored content accidentally placed at a legacy path is preserved.",
+          "**Default-content `.gdh/rules.yaml` upgrades automatically.** When the on-disk rules file is the verbatim default boilerplate (no project-specific edits) but its schema-version header is behind, the lifecycle inspector now reports `state: migration_needed` with `autoApplicable: true`, so `gdh migrate --apply` refreshes it in-place. Targets no longer need to hand-edit a file they never customized.",
+          "**Customized `.gdh/rules.yaml` keeps the manual-review gate, with clearer next steps.** When the rules body really did diverge from the current default, the `manual_review` action now ships explicit `manualSteps` describing the safe options (bump the version header or port custom rules into a fresh file, then rerun `gdh migrate --apply`) and explicitly tells the agent NOT to use `/gdh-update`, which only changes the installed GDH version and cannot edit the on-disk schema marker."
+        ]
+      },
+      "updateContract": {
+        "summary": "No release-scoped managed schema migration is required for v0.18.1. After self-update, running `gdh migrate --apply` on existing targets is enough: it now cleans up stale managed `.codex/skills/<skill>/SKILL.md` files regardless of their pinned-version string, and it auto-refreshes default-content `.gdh/rules.yaml` whose schema-version header is behind. Customized rules files remain on the manual-review path, with clearer `manualSteps` and an explicit anti-recommendation against `/gdh-update`.",
+        "steps": [
+          {
+            "id": "rerun_migrate_for_legacy_codex_cleanup",
+            "kind": "mechanical",
+            "summary": "Run `gdh migrate --apply` to clean up stale managed `.codex/skills/<skill>/SKILL.md` files left over from older GDH onboarding.",
+            "detail": "The pre-fix cleanup planner only deleted legacy files whose body was byte-equal to the current pinned GDH render, so stale-version content survived migration indefinitely. v0.18.1 detects managed legacy files by the `<codex_skill_adapter>` marker that every Codex skill render embeds and removes them. User-authored content at a legacy path without that marker is preserved.",
+            "commands": [
+              "gdh migrate --apply"
+            ],
+            "validationCommands": [
+              "gdh adapters status <target>",
+              "gdh status <target>"
+            ]
+          },
+          {
+            "id": "rerun_migrate_for_default_rules_refresh",
+            "kind": "mechanical",
+            "summary": "Run `gdh migrate --apply` to auto-refresh `.gdh/rules.yaml` when its body is the prior-version default boilerplate.",
+            "detail": "The `rules_schema` lifecycle inspector now structurally compares the on-disk file (parsed back through `readRulesDocument`, which version-normalizes the header) against the current default boilerplate. A match becomes `state: migration_needed, autoApplicable: true` so migrate refreshes the file in place. Customized content stays on the manual-review path.",
+            "commands": [
+              "gdh migrate --apply"
+            ],
+            "validationCommands": [
+              "gdh status <target>"
+            ]
+          },
+          {
+            "id": "follow_manual_steps_for_customized_rules",
+            "kind": "agent_reasoning",
+            "summary": "When the rules surface stays on `manual_review_required`, follow the new `manualSteps`; do NOT use `/gdh-update`.",
+            "detail": "If `gdh migrate --apply` reports `terminal.state: manual_review_required` for the rules surface, the on-disk `.gdh/rules.yaml` is treated as customized. The new `manualSteps` walk the agent through inspecting the file, bumping the schema marker to the current `GDH_RULES_SCHEMA_VERSION` (or porting custom rules into a fresh file), then rerunning `gdh migrate --apply`. `/gdh-update` only changes the installed GDH version; it cannot edit the on-disk schema marker and will not resolve `rules_version_unrecognized`.",
+            "commands": [
+              "gdh migrate --apply"
+            ],
+            "validationCommands": [
+              "gdh status <target>"
+            ]
+          }
+        ]
+      }
     }
   ]
 }

package/node_modules/@gdh/adapters/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAeA,OAAO,EAcL,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EACjC,KAAK,cAAc,EAInB,KAAK,sCAAsC,EAE3C,KAAK,gCAAgC,EAIrC,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EAIvB,MAAM,WAAW,CAAC;AA8BnB,eAAO,MAAM,eAAe,wCAc1B,CAAC;AAEH,eAAO,MAAM,gBAAgB,wCAIoB,CAAC;AAClD,eAAO,MAAM,yBAAyB,cAAc,CAAC;AACrD,eAAO,MAAM,oCAAoC,oCAAoC,CAAC;AACtF,eAAO,MAAM,yBAAyB,cAAc,CAAC;AACrD,eAAO,MAAM,wBAAwB,qBAAqB,CAAC;AAC3D,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AACvE,eAAO,MAAM,kCAAkC,wCAAwC,CAAC;AACxF,eAAO,MAAM,iCAAiC,wCAAwC,CAAC;AACvF,eAAO,MAAM,mCAAmC,mCAAmC,CAAC;AACpF,eAAO,MAAM,oCAAoC,oCAAoC,CAAC;AACtF,eAAO,MAAM,kCAAkC,kCAAkC,CAAC;AAClF,eAAO,MAAM,oCAAoC,oCAAoC,CAAC;AACtF,eAAO,MAAM,mCAAmC,mCAAmC,CAAC;AACpF,eAAO,MAAM,gCAAgC,uCAAuC,CAAC;AACrF,eAAO,MAAM,iCAAiC,wCAAwC,CAAC;AACvF,eAAO,MAAM,+BAA+B,sCAAsC,CAAC;AACnF,eAAO,MAAM,iCAAiC,wCAAwC,CAAC;AACvF,eAAO,MAAM,gCAAgC,uCAAuC,CAAC;AACrF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AACtF,eAAO,MAAM,kCAAkC,wCAAwC,CAAC;AACxF,eAAO,MAAM,gCAAgC,sCAAsC,CAAC;AACpF,eAAO,MAAM,kCAAkC,wCAAwC,CAAC;AACxF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AAOtF,eAAO,MAAM,mCAAmC,mCAAmC,CAAC;AACpF,eAAO,MAAM,gCAAgC,uCAAuC,CAAC;AACrF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AACtF,eAAO,MAAM,iCAAiC,iCAAiC,CAAC;AAChF,eAAO,MAAM,8BAA8B,qCAAqC,CAAC;AAWjF,eAAO,MAAM,+BAA+B,qCAAqC,CAAC;AAClF,eAAO,MAAM,8BAA8B,gCAAgC,CAAC;AAC5E,eAAO,MAAM,kCAAkC,uBAAuB,CAAC;AACvE,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAUzC,wBAAsB,+BAA+B,CACnD,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IACP,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC,GACL,OAAO,CAAC,4BAA4B,CAAC,CAuBvC;AAED,wBAAsB,6BAA6B,CACjD,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IACP,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC9B,GACL,OAAO,CAAC,6BAA6B,CAAC,CA8ExC;AAED,wBAAsB,oCAAoC,CACxD,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,sCAAsC,CAAC,CA2DjD;AAED,wBAAsB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CA0BvF;AAED,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IACP,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC9C,GACL,OAAO,CAAC,cAAc,CAAC,CAoFzB;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAezC;AAED,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAqCxE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA+CrE;AAED,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA6CtE;AAID,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAmCvE;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA2CpE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAyCrE;AAID,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA8BrE;AAED,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAuClE;AAED,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAqCnE;AAID,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAqCxE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA4CrE;AAED,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA0CtE;AA4BD,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CA0CxE;AAED,wBAAgB,sBAAsB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CA+CrE;AAED,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CA6CtE;AAID,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAoCtE;AAED,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA4CnE;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA0CpE;AAID,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAiCxE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAwCrE;AAED,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAsCtE;AAID,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAiCvE;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAyCpE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAuCrE;AA4/DD,wBAAgB,gCAAgC,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAQ9E;AAED,wBAAgB,+BAA+B,CAC7C,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,aAAa,EAAE,MAAM,GACpB,MAAM,CA+BR;AAqpCD,iBAAS,sCAAsC,CAC7C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,SAAS,gCAAgC,EAAE,GACpD,sCAAsC,CAmCxC;AAiPD,OAAO,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAAE,sCAAsC,EAAE,MAAM,gCAAgC,CAAC;AACxF,OAAO,EACL,KAAK,sBAAsB,EAC3B,gBAAgB,GACjB,MAAM,4BAA4B,CAAC;AAMpC,OAAO,EAAE,sCAAsC,EAAE,CAAC"}

package/node_modules/@gdh/adapters/dist/index.js

@@ -6,7 +6,7 @@ import path from "node:path";
 import { promisify } from "node:util";
 import { readProjectConfig, readWorktreeState, resolveAuthoringStatus, resolvePinnedVersion, resolvePinnedVersionOrNull, resolveProjectRoot, } from "@gdh/authoring";
 import { assertProjectLifecycleCompatibilityInvariant, definePackageBoundary, GDH_AGENT_CONTRACT_VERSION, GDH_CURSOR_RULE_VERSION, GDH_GUIDANCE_INDEX_VERSION, GDH_GUIDANCE_UNIT_VERSION, GDH_PROJECT_CONFIG_VERSION, GDH_RECIPE_SCHEMA_VERSION, GDH_RULES_SCHEMA_VERSION, GDH_SCENARIO_SCHEMA_VERSION, resolveConfiguredGodotEditorBin, resolveCurrentGdhInstall, resolveGdhProductMetadata, } from "@gdh/core";
-import { createDefaultGuidanceUnits, getGuidanceStatus, resolveGuidanceQuery, resolveRecoveryHints, } from "@gdh/docs";
+import { createDefaultGuidanceUnits, createDefaultRulesDocument, getGuidanceStatus, readRulesDocument, renderRulesYaml, resolveGuidanceQuery, resolveRecoveryHints, } from "@gdh/docs";
 import { inspectGuidanceAudit } from "@gdh/observability";
 import { inspectRuntimeBridgeSurface, inspectRuntimeKnowledgeSurface } from "@gdh/runtime";
 import { readInventoryCacheOrScan } from "@gdh/scan";
@@ -230,7 +230,7 @@ export async function inspectProjectLifecycleCompatibility(targetPath) {
         await inspectProjectConfigLifecycleSurface(resolvedTargetPath),
         await inspectRunConfigurationLifecycleSurface(resolvedTargetPath),
         await inspectVerificationScenarioLifecycleSurface(resolvedTargetPath),
-        await inspectRulesLifecycleSurface(resolvedTargetPath),
+        await inspectRulesLifecycleSurface(resolvedTargetPath, projectConfig),
         inspectAgentContractLifecycleSurface(resolvedTargetPath, guidanceStatus),
         await inspectGuidanceIndexLifecycleSurface(resolvedTargetPath),
         await inspectGuidanceUnitLifecycleSurface(resolvedTargetPath, projectConfig),
@@ -345,6 +345,7 @@ export function renderCursorRule() {
         "",
         "This repository uses GDH.",
         "Follow the canonical repo-local entrypoint in [AGENTS.md](../../AGENTS.md), then load the canonical guidance index at [docs/agent/README.md](../../docs/agent/README.md) before substantive work.",
+        "For runtime bridge usage, load [docs/agent/authoring-and-validation.md](../../docs/agent/authoring-and-validation.md) and follow its runtime bridge section.",
         "Do not duplicate or override the canonical GDH guidance chain here.",
         "",
     ].join("\n");
@@ -2215,14 +2216,30 @@ function planCodexRepoInstallActions(targetPath, adapter, pinnedVersion, project
     actions.push(...planLegacyCodexSkillCleanupActions(targetPath, pinnedVersion));
     return actions;
 }
-function planLegacyCodexSkillCleanupActions(targetPath, pinnedVersion) {
+// The signature embedded in every codex skill render body via the
+// `<codex_skill_adapter>` block. Detecting this marker lets the legacy
+// cleanup recognize a managed file regardless of which prior GDH version
+// rendered it, so stale-version skills at `.codex/skills/...` get removed
+// during migrate even when their pinned-npx string no longer matches the
+// current `pinnedVersion` (D-22 fix; see Session 7 dogfooding follow-up).
+const CODEX_MANAGED_SKILL_MARKER = "<codex_skill_adapter>";
+function isManagedLegacyCodexSkillContent(content) {
+    return content.includes(CODEX_MANAGED_SKILL_MARKER);
+}
+function planLegacyCodexSkillCleanupActions(targetPath, _pinnedVersion) {
     const actions = [];
-    for (const [relativePath, renderFn, skillName] of LEGACY_CODEX_SKILL_RELATIVE_PATHS) {
+    for (const [relativePath, _renderFn, skillName] of LEGACY_CODEX_SKILL_RELATIVE_PATHS) {
         const absolutePath = path.join(targetPath, relativePath);
         const content = fsSync.existsSync(absolutePath)
             ? fsSync.readFileSync(absolutePath, "utf8")
             : null;
-        if (content === null || content !== renderFn(pinnedVersion)) {
+        if (content === null) {
+            continue;
+        }
+        // Preserve any non-managed file a user may have intentionally placed at
+        // the legacy path. Only remove files we recognize as previously managed
+        // GDH skill renders (any version), not arbitrary user content.
+        if (!isManagedLegacyCodexSkillContent(content)) {
             continue;
         }
         actions.push(createInstallAction({
@@ -2853,7 +2870,7 @@ async function inspectVerificationScenarioLifecycleSurface(targetPath) {
         migrationSummary: "Verification scenarios use a legacy directory or older schema and can be normalized through the migration flow.",
     });
 }
-async function inspectRulesLifecycleSurface(targetPath) {
+async function inspectRulesLifecycleSurface(targetPath, projectConfig) {
     const relativePath = ".gdh/rules.yaml";
     const content = await fs.readFile(path.join(targetPath, relativePath), "utf8").catch(() => null);
     const detectedVersion = readYamlVersionHeader(content);
@@ -2893,11 +2910,42 @@ async function inspectRulesLifecycleSurface(targetPath) {
             action: null,
         });
     }
+    // Detect whether the on-disk file is just a prior-version copy of the
+    // default boilerplate (no project-specific customizations). When that's
+    // true the file is safe to overwrite with the current default during
+    // migrate, so surface it as `migration_needed` + auto-applicable rather
+    // than blocking on manual review. This closes Session 8 (TheBeacon
+    // 2026-04-25): a fresh-installed target's `.gdh/rules.yaml` is the
+    // verbatim default boilerplate, but a rules-schema bump (v1 -> v2) made
+    // the surface gate apply behind a `manual_review_required` terminal,
+    // forcing every dogfood target to hand-edit a file the user never
+    // touched. See `docs/development/dogfooding.md` Session 8.
+    if (await isDefaultRulesBoilerplate(targetPath, projectConfig)) {
+        return createLifecycleSurfaceStatus({
+            surface: "rules_schema",
+            management: "project_owned",
+            state: "migration_needed",
+            summary: "Rules file is a prior-version default boilerplate and can be safely refreshed to the current schema.",
+            reasons: ["rules_version_behind"],
+            probes,
+            action: {
+                kind: "apply_migration",
+                summary: "Run GDH migrate to refresh .gdh/rules.yaml from the prior-version default to the current schema. No project-specific rule edits will be lost.",
+                command: migrateApplyCommand(targetPath),
+                autoApplicable: true,
+            },
+        });
+    }
+    // File exists, version does not match, and content is not recognizable
+    // default boilerplate. Treat as a real customization that GDH must not
+    // silently overwrite. Steer the agent to either bump the version header
+    // or delete-and-remigrate, NOT to `gdh-update` (which only changes the
+    // GDH version, not the on-disk schema marker).
     return createLifecycleSurfaceStatus({
         surface: "rules_schema",
         management: "project_owned",
         state: "compatibility_degraded",
-        summary: "Rules file exists, but its version marker is missing or no longer matches this GDH build.",
+        summary: "Rules file appears customized and its schema version differs from this GDH build, so GDH cannot refresh it automatically.",
         reasons: ["rules_version_unrecognized"],
         probes,
         action: {
@@ -2905,9 +2953,30 @@ async function inspectRulesLifecycleSurface(targetPath) {
             summary: "Inspect .gdh/rules.yaml manually before overwriting project-specific rule content.",
             command: ["gdh", "migrate", targetPath],
             autoApplicable: false,
+            manualSteps: [
+                `Open .gdh/rules.yaml and confirm whether project-specific rules were added beyond the default GDH boilerplate.`,
+                `If the file holds only default boilerplate, bump its first line to \`version: ${GDH_RULES_SCHEMA_VERSION}\` (or delete the file) and rerun \`gdh migrate --apply\` so GDH can refresh it.`,
+                `If the file holds custom rules, port those rules into a fresh \`.gdh/rules.yaml\` whose first line is \`version: ${GDH_RULES_SCHEMA_VERSION}\`, then rerun \`gdh migrate --apply\`.`,
+                `Do NOT use \`/gdh-update\` to resolve this surface: that command only changes the installed GDH version and will not edit the rules schema marker on disk.`,
+            ],
         },
     });
 }
+async function isDefaultRulesBoilerplate(targetPath, projectConfig) {
+    const onDisk = await readRulesDocument(targetPath);
+    if (onDisk === null) {
+        return false;
+    }
+    // `readRulesDocument` always coerces `schemaVersion` to the current
+    // `GDH_RULES_SCHEMA_VERSION` regardless of the file's on-disk version
+    // header (see `coerceRulesDocument` in @gdh/docs). That means the
+    // structural compare below is version-marker-insensitive: it answers
+    // "does the body match the current GDH default?", which is exactly the
+    // signal needed to decide whether overwriting the file is safe.
+    const expected = renderRulesYaml(createDefaultRulesDocument(projectConfig));
+    const actual = renderRulesYaml(onDisk);
+    return actual === expected;
+}
 function inspectAgentContractLifecycleSurface(targetPath, guidanceStatus) {
     const status = guidanceStatus.agentContract;
     const probes = [