@skillcap/gdh 0.7.0 → 0.9.0

package/INSTALL-BUNDLE.json

@@ -1,5 +1,5 @@
 {
   "product": "GDH",
-  "version": "0.7.0",
+  "version": "0.9.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.7.0 setup
+npx -y @skillcap/gdh@0.9.0 setup
 ```
 
-Replace `0.7.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.
+Replace `0.9.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.
 
 The full install and update contract lives in [install-and-update.md](docs/development/install-and-update.md).
 
@@ -30,7 +30,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.7.0 setup
+npx -y @skillcap/gdh@0.9.0 setup
 
 # 2. Open your AI agent (Claude, Cursor, Codex) in the repo
 
@@ -94,7 +94,7 @@ The CLI exists for advanced operators, debugging, and automation. See [Advanced
 
 ## Status
 
-GDH now ships the current `0.7.0` release line and remains ready for broader internal use within the documented support contract. The current release line is `0.7.0` at the `broader_internal_release` stage.
+GDH now ships the current `0.9.0` release line and remains ready for broader internal use within the documented support contract. The current release line is `0.9.0` at the `broader_internal_release` stage.
 
 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/node_modules/@gdh/adapters/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { type GdhAgentAdaptersInstallResult, type GdhAgentAdaptersStatusResult, type GdhGsdSnapshot, type GdhProjectLifecycleCompatibilityResult, type GdhStatusResult, type GdhSupportedAgent, type GdhValidationKind } from "@gdh/core";
+import { type GdhAgentAdaptersInstallResult, type GdhAgentAdaptersStatusResult, type GdhGsdSnapshot, type GdhProjectLifecycleCompatibilityResult, type GdhProjectLifecycleSurfaceStatus, type GdhStatusResult, type GdhSupportedAgent, type GdhValidationKind } from "@gdh/core";
 export declare const adaptersPackage: import("@gdh/core").GdhPackageBoundary;
 export declare const SUPPORTED_AGENTS: readonly ["codex", "claude", "cursor"];
 export declare const CLAUDE_SHIM_RELATIVE_PATH = "CLAUDE.md";
@@ -77,7 +77,9 @@ export declare function renderCodexVerifySkill(pinnedVersion: string): string;
 export declare function renderCursorVerifySkill(pinnedVersion: string): string;
 export declare function renderManagedCodexProjectSection(pinnedVersion: string): string;
 export declare function renderManagedCodexProjectConfig(existingContent: string | null, pinnedVersion: string): string;
+declare function summarizeProjectLifecycleCompatibility(targetPath: string, surfaces: readonly GdhProjectLifecycleSurfaceStatus[]): GdhProjectLifecycleCompatibilityResult;
 export { bumpAndRebakePin, type BumpAndRebakePinResult, } from "./self-update-mechanics.js";
 export { CLAUDE_CHECK_UPDATE_HOOK_RELATIVE_PATH } from "./claude-update-hook-render.js";
 export { CLAUDE_STATUSLINE_RELATIVE_PATH } from "./claude-statusline-render.js";
+export { summarizeProjectLifecycleCompatibility };
 //# sourceMappingURL=index.d.ts.map

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":"AA8BA,OAAO,EAeL,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EACjC,KAAK,cAAc,EAGnB,KAAK,sCAAsC,EAK3C,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,WAAW,CAAC;AAWnB,eAAO,MAAM,eAAe,wCAc1B,CAAC;AAEH,eAAO,MAAM,gBAAgB,wCAAgF,CAAC;AAC9G,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,uCAAuC,CAAC;AACtF,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,sCAAsC,CAAC;AACpF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AACtF,eAAO,MAAM,+BAA+B,qCAAqC,CAAC;AAClF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AACtF,eAAO,MAAM,gCAAgC,sCAAsC,CAAC;AACpF,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,sCAAsC,CAAC;AACpF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AACtF,eAAO,MAAM,iCAAiC,iCAAiC,CAAC;AAChF,eAAO,MAAM,8BAA8B,oCAAoC,CAAC;AAChF,eAAO,MAAM,+BAA+B,qCAAqC,CAAC;AAClF,eAAO,MAAM,8BAA8B,gCAAgC,CAAC;AAC5E,eAAO,MAAM,kCAAkC,uBAAuB,CAAC;AACvE,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAIzC,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,CA0BvC;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,CAgFxC;AAED,wBAAsB,oCAAoC,CACxD,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,sCAAsC,CAAC,CA8DjD;AAED,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC,CAS1B;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,CAqFzB;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAczC;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,CAgCvE;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAwCpE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAsCrE;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,CAgCxE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAuCrE;AAED,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAqCtE;AA0BD,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CA+BxE;AAED,wBAAgB,sBAAsB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAoCrE;AAED,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAkCtE;AAID,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA+BtE;AAED,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAuCnE;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAqCpE;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,CAgCvE;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAwCpE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAsCrE;AAylDD,wBAAgB,gCAAgC,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAM9E;AAED,wBAAgB,+BAA+B,CAC7C,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,aAAa,EAAE,MAAM,GACpB,MAAM,CAiCR;AA8vCD,OAAO,EACL,gBAAgB,EAChB,KAAK,sBAAsB,GAC5B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,sCAAsC,EAAE,MAAM,gCAAgC,CAAC;AACxF,OAAO,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

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

@@ -9,8 +9,8 @@ import { CLAUDE_CHECK_UPDATE_HOOK_RELATIVE_PATH, CLAUDE_CHECK_UPDATE_WORKER_RELA
 import { renderClaudeCheckUpdateWorker } from "./claude-update-worker-render.js";
 import { CLAUDE_STATUSLINE_RELATIVE_PATH, renderClaudeUpdateStatusline, } from "./claude-statusline-render.js";
 import { CLAUDE_SETTINGS_RELATIVE_PATH, patchClaudeSettingsForGdhSessionStart, patchClaudeSettingsForGdhStatusline, } from "./claude-settings-patch.js";
-import { 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, definePackageBoundary, resolveCurrentGdhInstall, resolveGdhProductMetadata, } from "@gdh/core";
-import { createDefaultGuidanceUnits, getGuidanceStatus, resolveGuidanceQuery, } from "@gdh/docs";
+import { 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, assertProjectLifecycleCompatibilityInvariant, definePackageBoundary, resolveCurrentGdhInstall, resolveGdhProductMetadata, } from "@gdh/core";
+import { createDefaultGuidanceUnits, getGuidanceStatus, resolveGuidanceQuery, resolveRecoveryHints, } from "@gdh/docs";
 import { inspectGuidanceAudit } from "@gdh/observability";
 import { inspectRuntimeBridgeSurface } from "@gdh/runtime";
 import { scanGodotProjectInventory } from "@gdh/scan";
@@ -67,6 +67,11 @@ export const CURSOR_SCAN_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-scan/SKILL.md
 export const LOCAL_PATH_HINTS_RELATIVE_PATH = ".gdh-state/local-paths.json";
 export const CODEX_PROJECT_CONFIG_RELATIVE_PATH = ".codex/config.toml";
 export const GDH_MCP_SERVER_NAME = "gdh";
+// Phase 17 UX-01: single source of truth for the `/gdh-status` preview-header
+// literal. The character between "dry-run)" and "not" is em-dash U+2014 (NOT
+// two hyphens). Centralizing here prevents silent drift across the 3
+// `/gdh-status` renderer bodies (Pitfall #5 three-adapter parity).
+const PREVIEW_HEADER_LITERAL = "Preview (dry-run) — not applied";
 const execFile = promisify(execFileCallback);
 export async function getSupportedAgentAdaptersStatus(targetPath, options = {}) {
     const includeUserLocal = options.includeUserLocal ?? true;
@@ -222,10 +227,12 @@ export async function inspectProjectLifecycleCompatibility(targetPath) {
 export async function buildGdhStatusResult(targetPath) {
     const context = await buildAuthoringContext(targetPath);
     const projectLifecycle = await inspectProjectLifecycleCompatibility(targetPath);
+    const recoveryHints = resolveRecoveryHints(projectLifecycle.reasons);
     return {
         ...context.status,
         product: resolveGdhProductMetadata(),
         projectLifecycle,
+        recoveryHints,
     };
 }
 export async function createGsdSnapshot(targetPath, options = {}) {
@@ -470,9 +477,12 @@ export function renderClaudeStatusCommand(pinnedVersion) {
         "Follow this order:",
         "",
         `1. Run \`npx -y @skillcap/gdh@${pinnedVersion} status\` and explain each readiness field.`,
-        `2. Check if migration is needed with \`npx -y @skillcap/gdh@${pinnedVersion} migrate\`.`,
-        "3. Surface any degraded or unavailable capabilities.",
-        "4. Suggest the most productive next step based on current state.",
+        "2. Distinguish `blockingReasons` (needs /gdh-update or manual intervention) from `coupledReasons` (fixable via /gdh-migrate).",
+        `3. Check if migration is needed with \`npx -y @skillcap/gdh@${pinnedVersion} migrate\`.`,
+        `4. ${PREVIEW_HEADER_LITERAL} — migrate output at this step describes planned actions ("would delete …") not applied ones ("deleted").`,
+        "5. If status JSON `recoveryHints` array is non-empty, surface each entry's `{command, skillName}` pair.",
+        "6. Surface any degraded or unavailable capabilities.",
+        "7. Suggest the most productive next step based on current state.",
         "</process>",
         "",
         "<rules>",
@@ -511,7 +521,10 @@ export function renderCodexStatusSkill(pinnedVersion) {
         "Follow this order:",
         "",
         `- run \`npx -y @skillcap/gdh@${pinnedVersion} status\` and explain each readiness field`,
+        "- distinguish `blockingReasons` (needs /gdh-update or manual intervention) from `coupledReasons` (fixable via /gdh-migrate)",
         `- check if migration is needed with \`npx -y @skillcap/gdh@${pinnedVersion} migrate\``,
+        `- ${PREVIEW_HEADER_LITERAL} — migrate output describes planned actions ("would delete …") not applied ones ("deleted")`,
+        "- if status JSON `recoveryHints` array is non-empty, surface each entry's `{command, skillName}` pair",
         "- surface any degraded or unavailable capabilities",
         "- suggest the most productive next step based on current state",
         "</process>",
@@ -550,7 +563,10 @@ export function renderCursorStatusSkill(pinnedVersion) {
         "Follow this order:",
         "",
         `- run \`npx -y @skillcap/gdh@${pinnedVersion} status\` and explain each readiness field`,
+        "- distinguish `blockingReasons` (needs /gdh-update or manual intervention) from `coupledReasons` (fixable via /gdh-migrate)",
         `- check if migration is needed with \`npx -y @skillcap/gdh@${pinnedVersion} migrate\``,
+        `- ${PREVIEW_HEADER_LITERAL} — migrate output describes planned actions ("would delete …") not applied ones ("deleted")`,
+        "- if status JSON `recoveryHints` array is non-empty, surface each entry's `{command, skillName}` pair",
         "- surface any degraded or unavailable capabilities",
         "- suggest the most productive next step based on current state",
         "</process>",
@@ -694,10 +710,11 @@ export function renderClaudeMigrateCommand(pinnedVersion) {
         "<process>",
         "Follow this order:",
         "",
-        `1. Run \`npx -y @skillcap/gdh@${pinnedVersion} migrate\` to preview pending migrations.`,
-        "2. Explain what each migration step will change and why.",
-        `3. Offer to run \`npx -y @skillcap/gdh@${pinnedVersion} migrate --apply\` if the user approves.`,
-        `4. After apply, run \`npx -y @skillcap/gdh@${pinnedVersion} status\` to verify the migration succeeded.`,
+        `1. Run \`npx -y @skillcap/gdh@${pinnedVersion} migrate\` to preview pending migrations (this is a dry-run; the JSON \`mode\` field will be \`"preview"\`).`,
+        "2. Inspect `compatibility.blockingReasons` vs `compatibility.coupledReasons` — if `blockingReasons` is non-empty, STOP: `migrate --apply` cannot fix them (recommend `/gdh-update` or manual intervention per each reason's recovery hint). If only `coupledReasons` is non-empty, proceed.",
+        "3. Explain what each migration step will change and why (use \"would\" verb forms — \"would delete\", \"would create\", \"would refresh\").",
+        `4. Offer to run \`npx -y @skillcap/gdh@${pinnedVersion} migrate --apply\` if the user approves — after apply, the JSON \`mode\` field becomes \`"applied"\` and verbs switch to past tense ("deleted", "created", "refreshed").`,
+        `5. After apply, run \`npx -y @skillcap/gdh@${pinnedVersion} status\` to verify the migration succeeded.`,
         "</process>",
         "",
         "<rules>",
@@ -734,9 +751,10 @@ export function renderCodexMigrateSkill(pinnedVersion) {
         "<process>",
         "Follow this order:",
         "",
-        `- run \`npx -y @skillcap/gdh@${pinnedVersion} migrate\` to preview pending migrations`,
-        "- explain what each migration step will change and why",
-        `- offer to run \`npx -y @skillcap/gdh@${pinnedVersion} migrate --apply\` if the user approves`,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} migrate\` to preview pending migrations (this is a dry-run; the JSON \`mode\` field will be \`"preview"\`)`,
+        "- inspect `compatibility.blockingReasons` vs `compatibility.coupledReasons` — if `blockingReasons` is non-empty, STOP: `migrate --apply` cannot fix them (recommend `/gdh-update` or manual intervention per each reason's recovery hint); if only `coupledReasons` is non-empty, proceed",
+        "- explain what each migration step will change and why (use \"would\" verb forms — \"would delete\", \"would create\", \"would refresh\")",
+        `- offer to run \`npx -y @skillcap/gdh@${pinnedVersion} migrate --apply\` if the user approves — after apply, the JSON \`mode\` field becomes \`"applied"\` and verbs switch to past tense ("deleted", "created", "refreshed")`,
         `- after apply, run \`npx -y @skillcap/gdh@${pinnedVersion} status\` to verify the migration succeeded`,
         "</process>",
         "",
@@ -772,9 +790,10 @@ export function renderCursorMigrateSkill(pinnedVersion) {
         "<process>",
         "Follow this order:",
         "",
-        `- run \`npx -y @skillcap/gdh@${pinnedVersion} migrate\` to preview pending migrations`,
-        "- explain what each migration step will change and why",
-        `- offer to run \`npx -y @skillcap/gdh@${pinnedVersion} migrate --apply\` if the user approves`,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} migrate\` to preview pending migrations (this is a dry-run; the JSON \`mode\` field will be \`"preview"\`)`,
+        "- inspect `compatibility.blockingReasons` vs `compatibility.coupledReasons` — if `blockingReasons` is non-empty, STOP: `migrate --apply` cannot fix them (recommend `/gdh-update` or manual intervention per each reason's recovery hint); if only `coupledReasons` is non-empty, proceed",
+        "- explain what each migration step will change and why (use \"would\" verb forms — \"would delete\", \"would create\", \"would refresh\")",
+        `- offer to run \`npx -y @skillcap/gdh@${pinnedVersion} migrate --apply\` if the user approves — after apply, the JSON \`mode\` field becomes \`"applied"\` and verbs switch to past tense ("deleted", "created", "refreshed")`,
         `- after apply, run \`npx -y @skillcap/gdh@${pinnedVersion} status\` to verify the migration succeeded`,
         "</process>",
         "",
@@ -830,6 +849,7 @@ export function renderClaudeUpdateCommand(_pinnedVersion) {
         "2. Surface the planned version delta and re-bake action count to the human conversationally.",
         "3. Apply: run `npx -y @skillcap/gdh@latest self-update [version]` (omit `[version]` to apply against npm latest; forward whatever positional the user passed to `/gdh-update`).",
         "4. Verify: run `npx -y @skillcap/gdh@latest verify drift` to confirm every baked surface matches the new pin.",
+        "5. Read the `pendingMigration` field in the self-update stdout JSON. When non-null, narrate the chain to the human and run `npx -y @skillcap/gdh@latest migrate --apply` as the next action; when null, confirm no migration is pending and stop.",
         "</process>",
         "",
         "<rules>",
@@ -867,6 +887,7 @@ export function renderCodexUpdateSkill(_pinnedVersion) {
         "2. Surface the planned version delta and re-bake action count to the human conversationally.",
         "3. Apply: run `npx -y @skillcap/gdh@latest self-update [version]` (omit `[version]` to apply against npm latest; forward whatever positional the user passed to `/gdh-update`).",
         "4. Verify: run `npx -y @skillcap/gdh@latest verify drift` to confirm every baked surface matches the new pin.",
+        "5. Read the `pendingMigration` field in the self-update stdout JSON. When non-null, narrate the chain to the human and run `npx -y @skillcap/gdh@latest migrate --apply` as the next action; when null, confirm no migration is pending and stop.",
         "</process>",
         "",
         "<rules>",
@@ -902,6 +923,7 @@ export function renderCursorUpdateSkill(_pinnedVersion) {
         "2. Surface the planned version delta and re-bake action count to the human conversationally.",
         "3. Apply: run `npx -y @skillcap/gdh@latest self-update [version]` (omit `[version]` to apply against npm latest; forward whatever positional the user passed to `/gdh-update`).",
         "4. Verify: run `npx -y @skillcap/gdh@latest verify drift` to confirm every baked surface matches the new pin.",
+        "5. Read the `pendingMigration` field in the self-update stdout JSON. When non-null, narrate the chain to the human and run `npx -y @skillcap/gdh@latest migrate --apply` as the next action; when null, confirm no migration is pending and stop.",
         "</process>",
         "",
         "<rules>",
@@ -3282,14 +3304,35 @@ async function inspectYamlSurfaceDirectory(input) {
 }
 function summarizeProjectLifecycleCompatibility(targetPath, surfaces) {
     const state = resolveProjectLifecycleState(surfaces);
-    const reasons = dedupe(surfaces.flatMap((surface) => surface.reasons).filter((reason) => reason.length > 0));
-    return {
+    const blocking = [];
+    const coupled = [];
+    for (const surface of surfaces) {
+        const bucket = surface.state === "migration_blocked" || surface.state === "compatibility_degraded"
+            ? blocking
+            : surface.state === "migration_needed" || surface.state === "migration_available"
+                ? coupled
+                : null;
+        if (bucket) {
+            for (const reason of surface.reasons) {
+                if (reason.length > 0)
+                    bucket.push(reason);
+            }
+        }
+    }
+    const blockingReasons = dedupe(blocking);
+    const coupledReasons = dedupe(coupled.filter((r) => !blockingReasons.includes(r)));
+    const reasons = [...blockingReasons, ...coupledReasons];
+    const result = {
         targetPath,
         state,
         summary: summarizeProjectLifecycleState(state, surfaces),
         reasons,
+        blockingReasons,
+        coupledReasons,
         surfaces,
     };
+    assertProjectLifecycleCompatibilityInvariant(result);
+    return result;
 }
 function resolveProjectLifecycleState(surfaces) {
     if (surfaces.some((surface) => surface.state === "migration_blocked")) {
@@ -3417,4 +3460,9 @@ function normalizeChangedFiles(files) {
 export { bumpAndRebakePin, } from "./self-update-mechanics.js";
 export { CLAUDE_CHECK_UPDATE_HOOK_RELATIVE_PATH } from "./claude-update-hook-render.js";
 export { CLAUDE_STATUSLINE_RELATIVE_PATH } from "./claude-statusline-render.js";
+// Internal aggregator exposed for Wave 0 unit tests
+// (packages/adapters/src/lifecycle-compatibility.test.ts). Callers outside this
+// package should continue to use inspectProjectLifecycleCompatibility, which
+// wraps this function with filesystem probing and surface discovery.
+export { summarizeProjectLifecycleCompatibility };
 //# sourceMappingURL=index.js.map