@skillcap/gdh 0.4.1 → 0.6.0

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

@@ -4,7 +4,11 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
-import { readProjectConfig, resolveProjectRoot, readWorktreeState, resolveAuthoringStatus, } from "@gdh/authoring";
+import { readProjectConfig, resolvePinnedVersion, resolvePinnedVersionOrNull, resolveProjectRoot, readWorktreeState, resolveAuthoringStatus, } from "@gdh/authoring";
+import { CLAUDE_CHECK_UPDATE_HOOK_RELATIVE_PATH, CLAUDE_CHECK_UPDATE_WORKER_RELATIVE_PATH, renderClaudeCheckUpdateHook, } from "./claude-update-hook-render.js";
+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_MCP_LAUNCHER_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 { inspectGuidanceAudit } from "@gdh/observability";
@@ -48,6 +52,18 @@ export const CURSOR_MIGRATE_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-migrate/SK
 export const CURSOR_CHECK_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-check/SKILL.md";
 export const CURSOR_PREPARE_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-prepare/SKILL.md";
 export const CURSOR_VERIFY_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-verify/SKILL.md";
+// Phase 13 SELF-01: /gdh-update skill surface path constants. The rendered
+// bodies shell out to `npx -y @skillcap/gdh@latest self-update` (LITERAL
+// @latest, not the pinned version — D-10) so the NEW CLI performs the update,
+// not the (potentially pre-Phase-12) OLD pinned one. These constants are
+// INTENTIONALLY excluded from VERIFY_DRIFT_SCANNED_FILES (D-13) because the
+// rendered bodies are version-agnostic by design.
+export const CLAUDE_UPDATE_COMMAND_RELATIVE_PATH = ".claude/commands/gdh/update.md";
+export const CODEX_UPDATE_SKILL_RELATIVE_PATH = ".codex/skills/gdh-update/SKILL.md";
+export const CURSOR_UPDATE_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-update/SKILL.md";
+export const CLAUDE_SCAN_COMMAND_RELATIVE_PATH = ".claude/commands/gdh/scan.md";
+export const CODEX_SCAN_SKILL_RELATIVE_PATH = ".codex/skills/gdh-scan/SKILL.md";
+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 MCP_LAUNCHER_RELATIVE_PATH = ".gdh/bin/gdh-mcp.mjs";
 export const GDH_MCP_SERVER_NAME = "gdh";
@@ -56,16 +72,18 @@ export async function getSupportedAgentAdaptersStatus(targetPath, options = {})
     const includeUserLocal = options.includeUserLocal ?? true;
     const integrationRootPath = resolveIntegrationRootPath(targetPath, options.integrationRootPath);
     const guidance = await getGuidanceStatus(targetPath);
+    const pinnedVersion = await resolvePinnedVersionOrNull(targetPath);
     const projectMcp = await inspectProjectMcpSupport(targetPath, {
         includeUserLocal,
         integrationRootPath,
+        pinnedVersion,
     });
     const [codex, claude, cursor] = await Promise.all([
-        inspectCodexAdapter(targetPath, guidance, projectMcp, {
+        inspectCodexAdapter(targetPath, guidance, projectMcp, pinnedVersion, {
             includeUserLocal,
         }),
-        inspectClaudeAdapter(targetPath, guidance, projectMcp),
-        inspectCursorAdapter(targetPath, guidance, projectMcp),
+        inspectClaudeAdapter(targetPath, guidance, projectMcp, pinnedVersion),
+        inspectCursorAdapter(targetPath, guidance, projectMcp, pinnedVersion),
     ]);
     return {
         targetPath,
@@ -80,6 +98,7 @@ export async function installSupportedAgentAdapters(targetPath, options = {}) {
     const status = await getSupportedAgentAdaptersStatus(targetPath, {
         integrationRootPath,
     });
+    const pinnedVersion = await resolvePinnedVersion(targetPath);
     if (!hasReadyVisibilityChain(status.guidance) && options.allowBootstrap !== true) {
         return {
             targetPath,
@@ -96,26 +115,41 @@ export async function installSupportedAgentAdapters(targetPath, options = {}) {
         user: options.user ?? false,
         devRepoPath: options.devRepoPath ?? null,
         integrationRootPath,
+        pinnedVersion,
     });
+    let appliedActions = actions;
     if (!dryRun) {
+        const newActions = [];
         for (const action of actions) {
             if (action.state === "unchanged") {
+                newActions.push(action);
                 continue;
             }
-            if (action.kind === "ensure_symlink") {
-                await applySymlinkAction(action);
-                continue;
-            }
-            if (action.kind === "run_command") {
-                await applyRunCommandAction(action);
-                continue;
+            try {
+                if (action.kind === "ensure_symlink") {
+                    await applySymlinkAction(action);
+                }
+                else if (action.kind === "run_command") {
+                    await applyRunCommandAction(action);
+                }
+                else if (action.command?.[0] === "write_local_hints") {
+                    await applyLocalHintsAction(action);
+                }
+                else {
+                    await applyWriteFileAction(action);
+                }
+                newActions.push({ ...action, state: "applied" });
             }
-            if (action.command?.[0] === "write_local_hints") {
-                await applyLocalHintsAction(action);
-                continue;
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                newActions.push({
+                    ...action,
+                    state: "blocked",
+                    summary: `${action.summary} (failed: ${errorMessage})`,
+                });
             }
-            await applyWriteFileAction(action);
         }
+        appliedActions = newActions;
     }
     return {
         targetPath,
@@ -129,7 +163,7 @@ export async function installSupportedAgentAdapters(targetPath, options = {}) {
         requestedAgents,
         guidance: status.guidance,
         adapters: status.adapters,
-        actions,
+        actions: appliedActions,
     };
 }
 export async function inspectProjectLifecycleCompatibility(targetPath) {
@@ -285,7 +319,7 @@ export function renderCursorRule() {
         "",
     ].join("\n");
 }
-export function renderClaudeOnboardCommand() {
+export function renderClaudeOnboardCommand(pinnedVersion) {
     return [
         "---",
         "name: gdh:onboard",
@@ -298,17 +332,17 @@ export function renderClaudeOnboardCommand() {
         "  - AskUserQuestion",
         "---",
         "<objective>",
-        "Finish the first-time GDH handoff after `gdh setup` and turn the generated GDH surface into a trustworthy starting point for real work.",
+        `Finish the first-time GDH handoff after \`npx -y @skillcap/gdh@${pinnedVersion} setup\` and turn the generated GDH surface into a trustworthy starting point for real work.`,
         "</objective>",
         "",
         "<process>",
         "Follow this order:",
         "",
-        "1. Confirm the selected target and current GDH state with `gdh status`.",
+        `1. Confirm the selected target and current GDH state with \`npx -y @skillcap/gdh@${pinnedVersion} status\`.`,
         "2. Read `.gdh/project.yaml`, `docs/agent/README.md`, and `docs/agent/00-gdh-onboarding.md` before asking for facts GDH already knows.",
-        "3. Check immediate readiness with `gdh guidance status` and `gdh target prepare --dry-run`.",
-        "4. If authoring is available, run `gdh authoring check`; if LSP matters, run `gdh lsp status`.",
-        "5. Inspect `gdh run-config list` and `gdh verification-scenario list` and call out anything draft, missing, or blocked.",
+        `3. Check immediate readiness with \`npx -y @skillcap/gdh@${pinnedVersion} guidance status\` and \`npx -y @skillcap/gdh@${pinnedVersion} target prepare --dry-run\`.`,
+        `4. If authoring is available, run \`npx -y @skillcap/gdh@${pinnedVersion} authoring check\`; if LSP matters, run \`npx -y @skillcap/gdh@${pinnedVersion} lsp status\`.`,
+        `5. Inspect \`npx -y @skillcap/gdh@${pinnedVersion} run-config list\` and \`npx -y @skillcap/gdh@${pinnedVersion} verification-scenario list\` and call out anything draft, missing, or blocked.`,
         "6. If GDH reports `godot_editor_not_configured`, explain that the Godot binary path is machine-local and offer to record `.gdh-state/local-paths.json` `godotEditorBinPath` once the human provides the local path.",
         "7. Ask the human only for narrow unresolved environment or target facts.",
         "8. End with a concise readiness summary and the exact next development step.",
@@ -318,11 +352,12 @@ export function renderClaudeOnboardCommand() {
         "- Do not start editing code during `/gdh-onboard` unless the human explicitly asks.",
         "- Prefer GDH structured surfaces over repo guesswork.",
         "- Keep the output short, operational, and specific.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
         "</rules>",
         "",
     ].join("\n");
 }
-export function renderCodexOnboardSkill() {
+export function renderCodexOnboardSkill(pinnedVersion) {
     return [
         "---",
         'name: "gdh-onboard"',
@@ -342,20 +377,20 @@ export function renderCodexOnboardSkill() {
         "</codex_skill_adapter>",
         "",
         "<objective>",
-        "Finish the first-time GDH handoff after `gdh setup` and turn the generated GDH surface into a trustworthy starting point for real work.",
+        `Finish the first-time GDH handoff after \`npx -y @skillcap/gdh@${pinnedVersion} setup\` and turn the generated GDH surface into a trustworthy starting point for real work.`,
         "</objective>",
         "",
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh status`",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} status\``,
         "- inspect `.gdh/project.yaml`, `docs/agent/README.md`, and `docs/agent/00-gdh-onboarding.md`",
-        "- run `gdh guidance status`",
-        "- run `gdh target prepare --dry-run`",
-        "- if authoring is available, run `gdh authoring check`",
-        "- if LSP matters, run `gdh lsp status`",
-        "- run `gdh run-config list`",
-        "- run `gdh verification-scenario list`",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} guidance status\``,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} target prepare --dry-run\``,
+        `- if authoring is available, run \`npx -y @skillcap/gdh@${pinnedVersion} authoring check\``,
+        `- if LSP matters, run \`npx -y @skillcap/gdh@${pinnedVersion} lsp status\``,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} run-config list\``,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} verification-scenario list\``,
         "- if GDH reports `godot_editor_not_configured`, explain that the Godot binary path is machine-local and offer to record `.gdh-state/local-paths.json` `godotEditorBinPath` once the user provides it",
         "- ask only for narrow unresolved environment or target facts",
         "- finish with a concise readiness summary and the exact next development step",
@@ -365,11 +400,12 @@ export function renderCodexOnboardSkill() {
         "- Do not start editing code during `/gdh-onboard` unless the human explicitly asks.",
         "- Prefer GDH structured surfaces over repo guesswork.",
         "- Keep output short, operational, and specific.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
         "</rules>",
         "",
     ].join("\n");
 }
-export function renderCursorOnboardSkill() {
+export function renderCursorOnboardSkill(pinnedVersion) {
     return [
         "---",
         "name: gdh-onboard",
@@ -387,20 +423,20 @@ export function renderCursorOnboardSkill() {
         "</cursor_skill_adapter>",
         "",
         "<objective>",
-        "Finish the first-time GDH handoff after `gdh setup` and turn the generated GDH surface into a trustworthy starting point for real work.",
+        `Finish the first-time GDH handoff after \`npx -y @skillcap/gdh@${pinnedVersion} setup\` and turn the generated GDH surface into a trustworthy starting point for real work.`,
         "</objective>",
         "",
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh status`",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} status\``,
         "- inspect `.gdh/project.yaml`, `docs/agent/README.md`, and `docs/agent/00-gdh-onboarding.md`",
-        "- run `gdh guidance status`",
-        "- run `gdh target prepare --dry-run`",
-        "- if authoring is available, run `gdh authoring check`",
-        "- if LSP matters, run `gdh lsp status`",
-        "- run `gdh run-config list`",
-        "- run `gdh verification-scenario list`",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} guidance status\``,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} target prepare --dry-run\``,
+        `- if authoring is available, run \`npx -y @skillcap/gdh@${pinnedVersion} authoring check\``,
+        `- if LSP matters, run \`npx -y @skillcap/gdh@${pinnedVersion} lsp status\``,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} run-config list\``,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} verification-scenario list\``,
         "- if GDH reports `godot_editor_not_configured`, explain that the Godot binary path is machine-local and offer to record `.gdh-state/local-paths.json` `godotEditorBinPath` once the user provides it",
         "- ask only for narrow unresolved environment or target facts",
         "- finish with a concise readiness summary and the exact next development step",
@@ -410,12 +446,13 @@ export function renderCursorOnboardSkill() {
         "- Do not start editing code during `/gdh-onboard` unless the human explicitly asks.",
         "- Prefer GDH structured surfaces over repo guesswork.",
         "- Keep output short, operational, and specific.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
         "</rules>",
         "",
     ].join("\n");
 }
 // --- gdh-status skill renders ---
-export function renderClaudeStatusCommand() {
+export function renderClaudeStatusCommand(pinnedVersion) {
     return [
         "---",
         "name: gdh:status",
@@ -433,8 +470,8 @@ export function renderClaudeStatusCommand() {
         "<process>",
         "Follow this order:",
         "",
-        "1. Run `gdh status` and explain each readiness field.",
-        "2. Check if migration is needed with `gdh migrate`.",
+        `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.",
         "</process>",
@@ -443,11 +480,12 @@ export function renderClaudeStatusCommand() {
         "- Do not start editing code.",
         "- Prefer structured GDH surfaces over repo guesswork.",
         "- Keep output short and operational.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
         "</rules>",
         "",
     ].join("\n");
 }
-export function renderCodexStatusSkill() {
+export function renderCodexStatusSkill(pinnedVersion) {
     return [
         "---",
         'name: "gdh-status"',
@@ -473,8 +511,8 @@ export function renderCodexStatusSkill() {
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh status` and explain each readiness field",
-        "- check if migration is needed with `gdh migrate`",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} status\` and explain each readiness field`,
+        `- check if migration is needed with \`npx -y @skillcap/gdh@${pinnedVersion} migrate\``,
         "- surface any degraded or unavailable capabilities",
         "- suggest the most productive next step based on current state",
         "</process>",
@@ -483,11 +521,12 @@ export function renderCodexStatusSkill() {
         "- Do not start editing code.",
         "- Prefer structured GDH surfaces over repo guesswork.",
         "- Keep output short and operational.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
         "</rules>",
         "",
     ].join("\n");
 }
-export function renderCursorStatusSkill() {
+export function renderCursorStatusSkill(pinnedVersion) {
     return [
         "---",
         "name: gdh-status",
@@ -511,8 +550,8 @@ export function renderCursorStatusSkill() {
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh status` and explain each readiness field",
-        "- check if migration is needed with `gdh migrate`",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} status\` and explain each readiness field`,
+        `- check if migration is needed with \`npx -y @skillcap/gdh@${pinnedVersion} migrate\``,
         "- surface any degraded or unavailable capabilities",
         "- suggest the most productive next step based on current state",
         "</process>",
@@ -521,12 +560,123 @@ export function renderCursorStatusSkill() {
         "- Do not start editing code.",
         "- Prefer structured GDH surfaces over repo guesswork.",
         "- Keep output short and operational.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
+        "</rules>",
+        "",
+    ].join("\n");
+}
+// --- gdh-scan skill renders ---
+export function renderClaudeScanCommand(pinnedVersion) {
+    return [
+        "---",
+        "name: gdh:scan",
+        "description: Refresh inventory cache and explain persistence effect",
+        "allowed-tools:",
+        "  - Read",
+        "  - Grep",
+        "  - Glob",
+        "  - Bash",
+        "---",
+        "<objective>",
+        "Refresh the inventory cache and explain the persistence effect of the scan.",
+        "</objective>",
+        "",
+        "<process>",
+        "Follow this order:",
+        "",
+        `1. Run \`npx -y @skillcap/gdh@${pinnedVersion} scan\` and parse the \`persisted\` field from the envelope.`,
+        "2. Check the `mode` field: `create`, `unchanged`, `overwrite`, or `null`.",
+        "3. Explain the persistence effect; if `null`, the target is not onboarded and no disk write occurred.",
+        "</process>",
+        "",
+        "<rules>",
+        "- Do not edit the persisted inventory directly.",
+        "- Prefer the cached inventory for status reads; re-run scan only when freshness is in question.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
+        "</rules>",
+        "",
+    ].join("\n");
+}
+export function renderCodexScanSkill(pinnedVersion) {
+    return [
+        "---",
+        'name: "gdh-scan"',
+        'description: "Refresh inventory cache and explain persistence effect"',
+        "metadata:",
+        '  short-description: "Refresh inventory cache and explain persistence effect"',
+        "---",
+        "",
+        "<codex_skill_adapter>",
+        "## Invocation",
+        "- This skill is invoked when the user says `/gdh-scan` or mentions `$gdh-scan`.",
+        "- Treat any extra user text as additional scan context.",
+        "",
+        "## User questions",
+        "- Ask only narrow follow-up questions when GDH cannot infer the missing fact safely.",
+        "- If structured user-input tooling is unavailable, ask concise plain-text questions instead.",
+        "</codex_skill_adapter>",
+        "",
+        "<objective>",
+        "Refresh the inventory cache and explain the persistence effect of the scan.",
+        "</objective>",
+        "",
+        "<process>",
+        "Follow this order:",
+        "",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} scan\``,
+        "- parse the `persisted` field from the envelope",
+        "- check `mode`: `create`, `unchanged`, `overwrite`, or `null`",
+        "- explain the persistence effect; if `null`, explain the target is not onboarded",
+        "</process>",
+        "",
+        "<rules>",
+        "- Do not edit the persisted inventory directly.",
+        "- Prefer the cached inventory for status reads; re-run scan only when freshness is in question.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
+        "</rules>",
+        "",
+    ].join("\n");
+}
+export function renderCursorScanSkill(pinnedVersion) {
+    return [
+        "---",
+        "name: gdh-scan",
+        'description: "Refresh inventory cache and explain persistence effect"',
+        "---",
+        "",
+        "<cursor_skill_adapter>",
+        "## Invocation",
+        "- This skill is invoked when the user says `/gdh-scan` or mentions `gdh-scan`.",
+        "- Treat any extra user text as additional scan context.",
+        "",
+        "## User questions",
+        "- Ask only narrow follow-up questions when GDH cannot infer the missing fact safely.",
+        "- Keep questions conversational and concise.",
+        "</cursor_skill_adapter>",
+        "",
+        "<objective>",
+        "Refresh the inventory cache and explain the persistence effect of the scan.",
+        "</objective>",
+        "",
+        "<process>",
+        "Follow this order:",
+        "",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} scan\``,
+        "- parse the `persisted` field from the envelope",
+        "- check `mode`: `create`, `unchanged`, `overwrite`, or `null`",
+        "- explain the persistence effect; if `null`, explain the target is not onboarded",
+        "</process>",
+        "",
+        "<rules>",
+        "- Do not edit the persisted inventory directly.",
+        "- Prefer the cached inventory for status reads; re-run scan only when freshness is in question.",
+        "- For cache/persistence behavior of scan, status, onboard: see `docs/agent/persistence-semantics.md`.",
         "</rules>",
         "",
     ].join("\n");
 }
 // --- gdh-migrate skill renders ---
-export function renderClaudeMigrateCommand() {
+export function renderClaudeMigrateCommand(pinnedVersion) {
     return [
         "---",
         "name: gdh:migrate",
@@ -545,10 +695,10 @@ export function renderClaudeMigrateCommand() {
         "<process>",
         "Follow this order:",
         "",
-        "1. Run `gdh migrate` to preview pending migrations.",
+        `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 `gdh migrate --apply` if the user approves.",
-        "4. After apply, run `gdh status` to verify the migration succeeded.",
+        `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.`,
         "</process>",
         "",
         "<rules>",
@@ -559,7 +709,7 @@ export function renderClaudeMigrateCommand() {
         "",
     ].join("\n");
 }
-export function renderCodexMigrateSkill() {
+export function renderCodexMigrateSkill(pinnedVersion) {
     return [
         "---",
         'name: "gdh-migrate"',
@@ -585,10 +735,10 @@ export function renderCodexMigrateSkill() {
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh migrate` to preview pending migrations",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} migrate\` to preview pending migrations`,
         "- explain what each migration step will change and why",
-        "- offer to run `gdh migrate --apply` if the user approves",
-        "- after apply, run `gdh status` to verify the migration succeeded",
+        `- offer to run \`npx -y @skillcap/gdh@${pinnedVersion} migrate --apply\` if the user approves`,
+        `- after apply, run \`npx -y @skillcap/gdh@${pinnedVersion} status\` to verify the migration succeeded`,
         "</process>",
         "",
         "<rules>",
@@ -599,7 +749,7 @@ export function renderCodexMigrateSkill() {
         "",
     ].join("\n");
 }
-export function renderCursorMigrateSkill() {
+export function renderCursorMigrateSkill(pinnedVersion) {
     return [
         "---",
         "name: gdh-migrate",
@@ -623,10 +773,10 @@ export function renderCursorMigrateSkill() {
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh migrate` to preview pending migrations",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} migrate\` to preview pending migrations`,
         "- explain what each migration step will change and why",
-        "- offer to run `gdh migrate --apply` if the user approves",
-        "- after apply, run `gdh status` to verify the migration succeeded",
+        `- offer to run \`npx -y @skillcap/gdh@${pinnedVersion} migrate --apply\` if the user approves`,
+        `- after apply, run \`npx -y @skillcap/gdh@${pinnedVersion} status\` to verify the migration succeeded`,
         "</process>",
         "",
         "<rules>",
@@ -637,8 +787,135 @@ export function renderCursorMigrateSkill() {
         "",
     ].join("\n");
 }
+// --- gdh-update skill renders (Phase 13 SELF-01) ---
+//
+// D-10 invariant: every rendered body shells out to the LITERAL string
+// `@skillcap/gdh@latest` in every npx line (dry-run, apply, verify drift).
+// The `pinnedVersion` parameter is accepted for planSkillInstallAction
+// signature symmetry with every other renderer, but MUST NOT be interpolated
+// into the shellout — running the OLD pinned CLI (potentially pre-Phase-12
+// and lacking bumpAndRebakePin entirely) to perform its own update is the
+// failure mode Phase 13 exists to close. Check 44 in scripts/validate-docs.mjs
+// enforces both the @latest presence AND the @${pinnedVersion} absence.
+//
+// D-11: preview-then-apply flow WITHOUT a confirmation gate — the human's
+// original intent ("update GDH") IS the approval. No AskUserQuestion for
+// Claude; no `## User questions` H2 for Codex/Cursor. Differs from /gdh-migrate
+// which DOES gate on explicit approval.
+//
+// D-12: accept an optional positional version forwarded verbatim to the CLI.
+// `/gdh-update` = latest; `/gdh-update 0.6.0` = pin that version.
+//
+// D-13: the three rendered skill files are EXCLUDED from VERIFY_DRIFT_SCANNED_FILES
+// because @latest is not a semver literal — the baked-version scanner would
+// permanently report no_baked_version. See rationale comments adjacent to the
+// VERIFY_DRIFT_SCANNED_FILES declaration in packages/cli/src/index.ts.
+export function renderClaudeUpdateCommand(_pinnedVersion) {
+    return [
+        "---",
+        "name: gdh:update",
+        "description: Update GDH to npm latest (bump pinned version + re-bake managed surfaces)",
+        "allowed-tools:",
+        "  - Read",
+        "  - Bash",
+        "---",
+        "<objective>",
+        "Update this project's GDH pinning to npm latest and re-bake every managed surface at the new pin.",
+        "Treat any positional argument (e.g., `/gdh-update 0.6.0`) as an explicit version; otherwise default to npm latest.",
+        "</objective>",
+        "",
+        "<process>",
+        "Follow this order:",
+        "",
+        "1. Preview: run `npx -y @skillcap/gdh@latest self-update [version] --dry-run` (omit `[version]` to preview against npm latest).",
+        "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.",
+        "</process>",
+        "",
+        "<rules>",
+        "- Do NOT ask the user to confirm apply — their original intent (\"update GDH\") IS the approval.",
+        "- Bake literal `@latest` in the shellout so the new CLI performs the update, not the old one.",
+        "- If `self-update` returns `rolled_back` or `blocked`, surface the failure reason and stop (do not retry).",
+        "- If `self-update` returns `skipped_dev_mode`, explain that dev-from-source mode bypasses pinning; no action needed.",
+        "</rules>",
+        "",
+    ].join("\n");
+}
+export function renderCodexUpdateSkill(_pinnedVersion) {
+    return [
+        "---",
+        'name: "gdh-update"',
+        'description: "Update GDH to npm latest (bump pinned version + re-bake managed surfaces)"',
+        "metadata:",
+        '  short-description: "Update GDH to npm latest"',
+        "---",
+        "",
+        "<codex_skill_adapter>",
+        "## Invocation",
+        "- This skill is invoked when the user says `/gdh-update` or mentions `$gdh-update`.",
+        "- Treat any positional argument (e.g., `/gdh-update 0.6.0`) as an explicit version; otherwise default to npm latest.",
+        "</codex_skill_adapter>",
+        "",
+        "<objective>",
+        "Update this project's GDH pinning to npm latest and re-bake every managed surface at the new pin.",
+        "</objective>",
+        "",
+        "<process>",
+        "Follow this order:",
+        "",
+        "1. Preview: run `npx -y @skillcap/gdh@latest self-update [version] --dry-run` (omit `[version]` to preview against npm latest).",
+        "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.",
+        "</process>",
+        "",
+        "<rules>",
+        "- Do NOT ask the user to confirm apply — their original intent (\"update GDH\") IS the approval.",
+        "- Bake literal `@latest` in the shellout so the new CLI performs the update, not the old one.",
+        "- If `self-update` returns `rolled_back` or `blocked`, surface the failure reason and stop (do not retry).",
+        "- If `self-update` returns `skipped_dev_mode`, explain that dev-from-source mode bypasses pinning; no action needed.",
+        "</rules>",
+        "",
+    ].join("\n");
+}
+export function renderCursorUpdateSkill(_pinnedVersion) {
+    return [
+        "---",
+        "name: gdh-update",
+        'description: "Update GDH to npm latest (bump pinned version + re-bake managed surfaces)"',
+        "---",
+        "",
+        "<cursor_skill_adapter>",
+        "## Invocation",
+        "- This skill is invoked when the user says `/gdh-update` or mentions `gdh-update`.",
+        "- Treat any positional argument (e.g., `gdh-update 0.6.0`) as an explicit version; otherwise default to npm latest.",
+        "</cursor_skill_adapter>",
+        "",
+        "<objective>",
+        "Update this project's GDH pinning to npm latest and re-bake every managed surface at the new pin.",
+        "</objective>",
+        "",
+        "<process>",
+        "Follow this order:",
+        "",
+        "1. Preview: run `npx -y @skillcap/gdh@latest self-update [version] --dry-run` (omit `[version]` to preview against npm latest).",
+        "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.",
+        "</process>",
+        "",
+        "<rules>",
+        "- Do NOT ask the user to confirm apply — their original intent (\"update GDH\") IS the approval.",
+        "- Bake literal `@latest` in the shellout so the new CLI performs the update, not the old one.",
+        "- If `self-update` returns `rolled_back` or `blocked`, surface the failure reason and stop (do not retry).",
+        "- If `self-update` returns `skipped_dev_mode`, explain that dev-from-source mode bypasses pinning; no action needed.",
+        "</rules>",
+        "",
+    ].join("\n");
+}
 // --- gdh-check skill renders ---
-export function renderClaudeCheckCommand() {
+export function renderClaudeCheckCommand(pinnedVersion) {
     return [
         "---",
         "name: gdh:check",
@@ -656,7 +933,7 @@ export function renderClaudeCheckCommand() {
         "<process>",
         "Follow this order:",
         "",
-        "1. Run `gdh authoring check`.",
+        `1. Run \`npx -y @skillcap/gdh@${pinnedVersion} authoring check\`.`,
         "2. Explain each diagnostic finding with severity and provenance.",
         "3. Surface any import-state caveats or editor-side warnings.",
         "4. If issues found, suggest concrete remediation steps.",
@@ -670,7 +947,7 @@ export function renderClaudeCheckCommand() {
         "",
     ].join("\n");
 }
-export function renderCodexCheckSkill() {
+export function renderCodexCheckSkill(pinnedVersion) {
     return [
         "---",
         'name: "gdh-check"',
@@ -696,7 +973,7 @@ export function renderCodexCheckSkill() {
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh authoring check`",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} authoring check\``,
         "- explain each diagnostic finding with severity and provenance",
         "- surface any import-state caveats or editor-side warnings",
         "- if issues found, suggest concrete remediation steps",
@@ -710,7 +987,7 @@ export function renderCodexCheckSkill() {
         "",
     ].join("\n");
 }
-export function renderCursorCheckSkill() {
+export function renderCursorCheckSkill(pinnedVersion) {
     return [
         "---",
         "name: gdh-check",
@@ -734,7 +1011,7 @@ export function renderCursorCheckSkill() {
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh authoring check`",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} authoring check\``,
         "- explain each diagnostic finding with severity and provenance",
         "- surface any import-state caveats or editor-side warnings",
         "- if issues found, suggest concrete remediation steps",
@@ -749,7 +1026,7 @@ export function renderCursorCheckSkill() {
     ].join("\n");
 }
 // --- gdh-prepare skill renders ---
-export function renderClaudePrepareCommand() {
+export function renderClaudePrepareCommand(pinnedVersion) {
     return [
         "---",
         "name: gdh:prepare",
@@ -768,11 +1045,11 @@ export function renderClaudePrepareCommand() {
         "<process>",
         "Follow this order:",
         "",
-        "1. Run `gdh target prepare --dry-run` first to preview planned actions.",
+        `1. Run \`npx -y @skillcap/gdh@${pinnedVersion} target prepare --dry-run\` first to preview planned actions.`,
         "2. Explain what hydration and import refresh will do.",
-        "3. If the user approves, run `gdh target prepare`.",
+        `3. If the user approves, run \`npx -y @skillcap/gdh@${pinnedVersion} target prepare\`.`,
         "4. If a `--source-target` is relevant, explain when and why to use it.",
-        "5. Verify preparation succeeded with `gdh status`.",
+        `5. Verify preparation succeeded with \`npx -y @skillcap/gdh@${pinnedVersion} status\`.`,
         "</process>",
         "",
         "<rules>",
@@ -783,7 +1060,7 @@ export function renderClaudePrepareCommand() {
         "",
     ].join("\n");
 }
-export function renderCodexPrepareSkill() {
+export function renderCodexPrepareSkill(pinnedVersion) {
     return [
         "---",
         'name: "gdh-prepare"',
@@ -809,11 +1086,11 @@ export function renderCodexPrepareSkill() {
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh target prepare --dry-run` first to preview planned actions",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} target prepare --dry-run\` first to preview planned actions`,
         "- explain what hydration and import refresh will do",
-        "- if the user approves, run `gdh target prepare`",
+        `- if the user approves, run \`npx -y @skillcap/gdh@${pinnedVersion} target prepare\``,
         "- if a `--source-target` is relevant, explain when and why to use it",
-        "- verify preparation succeeded with `gdh status`",
+        `- verify preparation succeeded with \`npx -y @skillcap/gdh@${pinnedVersion} status\``,
         "</process>",
         "",
         "<rules>",
@@ -824,7 +1101,7 @@ export function renderCodexPrepareSkill() {
         "",
     ].join("\n");
 }
-export function renderCursorPrepareSkill() {
+export function renderCursorPrepareSkill(pinnedVersion) {
     return [
         "---",
         "name: gdh-prepare",
@@ -848,11 +1125,11 @@ export function renderCursorPrepareSkill() {
         "<process>",
         "Follow this order:",
         "",
-        "- run `gdh target prepare --dry-run` first to preview planned actions",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} target prepare --dry-run\` first to preview planned actions`,
         "- explain what hydration and import refresh will do",
-        "- if the user approves, run `gdh target prepare`",
+        `- if the user approves, run \`npx -y @skillcap/gdh@${pinnedVersion} target prepare\``,
         "- if a `--source-target` is relevant, explain when and why to use it",
-        "- verify preparation succeeded with `gdh status`",
+        `- verify preparation succeeded with \`npx -y @skillcap/gdh@${pinnedVersion} status\``,
         "</process>",
         "",
         "<rules>",
@@ -864,7 +1141,7 @@ export function renderCursorPrepareSkill() {
     ].join("\n");
 }
 // --- gdh-verify skill renders ---
-export function renderClaudeVerifyCommand() {
+export function renderClaudeVerifyCommand(pinnedVersion) {
     return [
         "---",
         "name: gdh:verify",
@@ -883,8 +1160,8 @@ export function renderClaudeVerifyCommand() {
         "Follow this order:",
         "",
         "1. Identify changed files from git diff or user input.",
-        "2. Run `gdh verify recommend` with those files to get recommended validation kinds.",
-        "3. Run `gdh verify done` with performed validations to check done eligibility.",
+        `2. Run \`npx -y @skillcap/gdh@${pinnedVersion} verify recommend\` with those files to get recommended validation kinds.`,
+        `3. Run \`npx -y @skillcap/gdh@${pinnedVersion} verify done\` with performed validations to check done eligibility.`,
         "4. Summarize gaps between recommended and performed validation.",
         "5. Suggest specific next verification steps.",
         "</process>",
@@ -897,7 +1174,7 @@ export function renderClaudeVerifyCommand() {
         "",
     ].join("\n");
 }
-export function renderCodexVerifySkill() {
+export function renderCodexVerifySkill(pinnedVersion) {
     return [
         "---",
         'name: "gdh-verify"',
@@ -924,8 +1201,8 @@ export function renderCodexVerifySkill() {
         "Follow this order:",
         "",
         "- identify changed files from git diff or user input",
-        "- run `gdh verify recommend` with those files to get recommended validation kinds",
-        "- run `gdh verify done` with performed validations to check done eligibility",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} verify recommend\` with those files to get recommended validation kinds`,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} verify done\` with performed validations to check done eligibility`,
         "- summarize gaps between recommended and performed validation",
         "- suggest specific next verification steps",
         "</process>",
@@ -938,7 +1215,7 @@ export function renderCodexVerifySkill() {
         "",
     ].join("\n");
 }
-export function renderCursorVerifySkill() {
+export function renderCursorVerifySkill(pinnedVersion) {
     return [
         "---",
         "name: gdh-verify",
@@ -963,8 +1240,8 @@ export function renderCursorVerifySkill() {
         "Follow this order:",
         "",
         "- identify changed files from git diff or user input",
-        "- run `gdh verify recommend` with those files to get recommended validation kinds",
-        "- run `gdh verify done` with performed validations to check done eligibility",
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} verify recommend\` with those files to get recommended validation kinds`,
+        `- run \`npx -y @skillcap/gdh@${pinnedVersion} verify done\` with performed validations to check done eligibility`,
         "- summarize gaps between recommended and performed validation",
         "- suggest specific next verification steps",
         "</process>",
@@ -980,7 +1257,9 @@ export function renderCursorVerifySkill() {
 async function inspectProjectMcpSupport(targetPath, options) {
     const projectConfig = await readProjectConfig(targetPath);
     const enabled = resolveProjectMcpEnabled(projectConfig);
-    const launcherContent = renderManagedMcpLauncher();
+    const launcherContent = options.pinnedVersion === null
+        ? null
+        : renderManagedMcpLauncher(options.pinnedVersion);
     const managedMcpEntry = buildManagedMcpServerEntry({
         targetPath,
         integrationRootPath: options.integrationRootPath,
@@ -1090,6 +1369,13 @@ function inspectLauncherFile(launcherSource, expectedContent, enabled, bootstrap
             summary: "The managed GDH MCP launcher is disabled for this target.",
         };
     }
+    if (expectedContent === null) {
+        return {
+            present: launcherSource !== null,
+            state: "missing",
+            summary: "The managed GDH MCP launcher is pending project onboard: no `gdh_version` is pinned yet, so there is no expected launcher content to compare against.",
+        };
+    }
     if (launcherSource === null) {
         return {
             present: false,
@@ -1182,6 +1468,20 @@ async function inspectCodexRegistration(targetPath, enabled, codexServerName, co
     };
 }
 function inspectCodexSkillSurface(targetPath, relativePath, content, expectedContent, skillName) {
+    if (expectedContent === null) {
+        return [
+            createSurfaceStatus({
+                kind: "skill_file",
+                scope: "repo",
+                targetPath,
+                relativePath,
+                present: content !== null,
+                state: "missing",
+                summary: `Codex ${skillName} skill cannot be validated yet: no \`gdh_version\` is pinned (run \`gdh setup\` or \`gdh migrate --apply\`).`,
+                version: null,
+            }),
+        ];
+    }
     return [
         createSurfaceStatus({
             kind: "skill_file",
@@ -1204,6 +1504,20 @@ function inspectCodexSkillSurface(targetPath, relativePath, content, expectedCon
     ];
 }
 function inspectClaudeCommandSurface(targetPath, relativePath, content, expectedContent, commandName) {
+    if (expectedContent === null) {
+        return [
+            createSurfaceStatus({
+                kind: "command_file",
+                scope: "repo",
+                targetPath,
+                relativePath,
+                present: content !== null,
+                state: "missing",
+                summary: `Claude ${commandName} command cannot be validated yet: no \`gdh_version\` is pinned (run \`gdh setup\` or \`gdh migrate --apply\`).`,
+                version: null,
+            }),
+        ];
+    }
     return [
         createSurfaceStatus({
             kind: "command_file",
@@ -1226,6 +1540,20 @@ function inspectClaudeCommandSurface(targetPath, relativePath, content, expected
     ];
 }
 function inspectCursorSkillSurface(targetPath, relativePath, content, expectedContent, skillName) {
+    if (expectedContent === null) {
+        return [
+            createSurfaceStatus({
+                kind: "skill_file",
+                scope: "repo",
+                targetPath,
+                relativePath,
+                present: content !== null,
+                state: "missing",
+                summary: `Cursor ${skillName} skill cannot be validated yet: no \`gdh_version\` is pinned (run \`gdh setup\` or \`gdh migrate --apply\`).`,
+                version: null,
+            }),
+        ];
+    }
     return [
         createSurfaceStatus({
             kind: "skill_file",
@@ -1247,14 +1575,28 @@ function inspectCursorSkillSurface(targetPath, relativePath, content, expectedCo
         }),
     ];
 }
-async function inspectCodexAdapter(targetPath, guidance, projectMcp, options) {
+async function inspectCodexAdapter(targetPath, guidance, projectMcp, pinnedVersion, options) {
     const codexSkillPath = path.join(targetPath, CODEX_ONBOARD_SKILL_RELATIVE_PATH);
     const codexSkillContent = await fs.readFile(codexSkillPath, "utf8").catch(() => null);
     const codexStatusContent = await fs.readFile(path.join(targetPath, CODEX_STATUS_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
     const codexMigrateContent = await fs.readFile(path.join(targetPath, CODEX_MIGRATE_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
+    // Phase 13 Plan 13-03 deliverable — /gdh-update skill for Codex. Inspection
+    // wiring is required so planSkillInstallAction can see the surface state;
+    // otherwise the planner returns `unchanged` for a missing file and install
+    // becomes a no-op (Plan 13-05 integration-test Rule 2 fix).
+    const codexUpdateContent = await fs.readFile(path.join(targetPath, CODEX_UPDATE_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
     const codexCheckContent = await fs.readFile(path.join(targetPath, CODEX_CHECK_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
     const codexPrepareContent = await fs.readFile(path.join(targetPath, CODEX_PREPARE_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
     const codexVerifyContent = await fs.readFile(path.join(targetPath, CODEX_VERIFY_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
+    const codexScanContent = await fs.readFile(path.join(targetPath, CODEX_SCAN_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
+    const expectedCodexOnboardSkill = pinnedVersion === null ? null : renderCodexOnboardSkill(pinnedVersion);
+    const expectedCodexStatusSkill = pinnedVersion === null ? null : renderCodexStatusSkill(pinnedVersion);
+    const expectedCodexMigrateSkill = pinnedVersion === null ? null : renderCodexMigrateSkill(pinnedVersion);
+    const expectedCodexUpdateSkill = pinnedVersion === null ? null : renderCodexUpdateSkill(pinnedVersion);
+    const expectedCodexCheckSkill = pinnedVersion === null ? null : renderCodexCheckSkill(pinnedVersion);
+    const expectedCodexPrepareSkill = pinnedVersion === null ? null : renderCodexPrepareSkill(pinnedVersion);
+    const expectedCodexVerifySkill = pinnedVersion === null ? null : renderCodexVerifySkill(pinnedVersion);
+    const expectedCodexScanSkill = pinnedVersion === null ? null : renderCodexScanSkill(pinnedVersion);
     const surfaces = [
         createSurfaceStatus({
             kind: "canonical_entrypoint",
@@ -1282,21 +1624,27 @@ async function inspectCodexAdapter(targetPath, guidance, projectMcp, options) {
             present: codexSkillContent !== null,
             state: codexSkillContent === null
                 ? "missing"
-                : codexSkillContent === renderCodexOnboardSkill()
-                    ? "ready"
-                    : "misconfigured",
+                : expectedCodexOnboardSkill === null
+                    ? "missing"
+                    : codexSkillContent === expectedCodexOnboardSkill
+                        ? "ready"
+                        : "misconfigured",
             summary: codexSkillContent === null
                 ? "Codex onboarding handoff is missing and should install `/gdh-onboard` under .codex/skills/."
-                : codexSkillContent === renderCodexOnboardSkill()
-                    ? "Codex can discover the managed `/gdh-onboard` handoff skill."
-                    : "Codex onboarding handoff exists but no longer matches the expected managed GDH skill.",
+                : expectedCodexOnboardSkill === null
+                    ? "Codex onboarding handoff cannot be validated yet: no `gdh_version` is pinned (run `gdh setup` or `gdh migrate --apply`)."
+                    : codexSkillContent === expectedCodexOnboardSkill
+                        ? "Codex can discover the managed `/gdh-onboard` handoff skill."
+                        : "Codex onboarding handoff exists but no longer matches the expected managed GDH skill.",
             version: null,
         }),
-        ...inspectCodexSkillSurface(targetPath, CODEX_STATUS_SKILL_RELATIVE_PATH, codexStatusContent, renderCodexStatusSkill(), "gdh-status"),
-        ...inspectCodexSkillSurface(targetPath, CODEX_MIGRATE_SKILL_RELATIVE_PATH, codexMigrateContent, renderCodexMigrateSkill(), "gdh-migrate"),
-        ...inspectCodexSkillSurface(targetPath, CODEX_CHECK_SKILL_RELATIVE_PATH, codexCheckContent, renderCodexCheckSkill(), "gdh-check"),
-        ...inspectCodexSkillSurface(targetPath, CODEX_PREPARE_SKILL_RELATIVE_PATH, codexPrepareContent, renderCodexPrepareSkill(), "gdh-prepare"),
-        ...inspectCodexSkillSurface(targetPath, CODEX_VERIFY_SKILL_RELATIVE_PATH, codexVerifyContent, renderCodexVerifySkill(), "gdh-verify"),
+        ...inspectCodexSkillSurface(targetPath, CODEX_STATUS_SKILL_RELATIVE_PATH, codexStatusContent, expectedCodexStatusSkill, "gdh-status"),
+        ...inspectCodexSkillSurface(targetPath, CODEX_MIGRATE_SKILL_RELATIVE_PATH, codexMigrateContent, expectedCodexMigrateSkill, "gdh-migrate"),
+        ...inspectCodexSkillSurface(targetPath, CODEX_UPDATE_SKILL_RELATIVE_PATH, codexUpdateContent, expectedCodexUpdateSkill, "gdh-update"),
+        ...inspectCodexSkillSurface(targetPath, CODEX_CHECK_SKILL_RELATIVE_PATH, codexCheckContent, expectedCodexCheckSkill, "gdh-check"),
+        ...inspectCodexSkillSurface(targetPath, CODEX_PREPARE_SKILL_RELATIVE_PATH, codexPrepareContent, expectedCodexPrepareSkill, "gdh-prepare"),
+        ...inspectCodexSkillSurface(targetPath, CODEX_VERIFY_SKILL_RELATIVE_PATH, codexVerifyContent, expectedCodexVerifySkill, "gdh-verify"),
+        ...inspectCodexSkillSurface(targetPath, CODEX_SCAN_SKILL_RELATIVE_PATH, codexScanContent, expectedCodexScanSkill, "gdh-scan"),
     ];
     if (projectMcp.enabled) {
         surfaces.push(createSurfaceStatus({
@@ -1325,20 +1673,40 @@ async function inspectCodexAdapter(targetPath, guidance, projectMcp, options) {
     }
     return createAgentStatus("codex", guidance, surfaces);
 }
-async function inspectClaudeAdapter(targetPath, guidance, projectMcp) {
+async function inspectClaudeAdapter(targetPath, guidance, projectMcp, pinnedVersion) {
     const absolutePath = path.join(targetPath, CLAUDE_SHIM_RELATIVE_PATH);
     const onboardCommandPath = path.join(targetPath, CLAUDE_ONBOARD_COMMAND_RELATIVE_PATH);
     const lstat = await fs.lstat(absolutePath).catch(() => null);
     const onboardCommandContent = await fs.readFile(onboardCommandPath, "utf8").catch(() => null);
     const claudeStatusContent = await fs.readFile(path.join(targetPath, CLAUDE_STATUS_COMMAND_RELATIVE_PATH), "utf8").catch(() => null);
     const claudeMigrateContent = await fs.readFile(path.join(targetPath, CLAUDE_MIGRATE_COMMAND_RELATIVE_PATH), "utf8").catch(() => null);
+    // Phase 13 Plan 13-03 deliverable — /gdh-update slash command for Claude.
+    // Inspection wiring is required so planSkillInstallAction can see the surface
+    // state; otherwise the planner returns `unchanged` for a missing file and
+    // install becomes a no-op (Plan 13-05 integration-test Rule 2 fix).
+    const claudeUpdateContent = await fs.readFile(path.join(targetPath, CLAUDE_UPDATE_COMMAND_RELATIVE_PATH), "utf8").catch(() => null);
     const claudeCheckContent = await fs.readFile(path.join(targetPath, CLAUDE_CHECK_COMMAND_RELATIVE_PATH), "utf8").catch(() => null);
     const claudePrepareContent = await fs.readFile(path.join(targetPath, CLAUDE_PREPARE_COMMAND_RELATIVE_PATH), "utf8").catch(() => null);
     const claudeVerifyContent = await fs.readFile(path.join(targetPath, CLAUDE_VERIFY_COMMAND_RELATIVE_PATH), "utf8").catch(() => null);
+    const claudeScanContent = await fs.readFile(path.join(targetPath, CLAUDE_SCAN_COMMAND_RELATIVE_PATH), "utf8").catch(() => null);
+    const claudeCheckUpdateHookContent = await fs.readFile(path.join(targetPath, CLAUDE_CHECK_UPDATE_HOOK_RELATIVE_PATH), "utf8").catch(() => null);
+    const claudeCheckUpdateWorkerContent = await fs.readFile(path.join(targetPath, CLAUDE_CHECK_UPDATE_WORKER_RELATIVE_PATH), "utf8").catch(() => null);
+    const claudeStatuslineContent = await fs.readFile(path.join(targetPath, CLAUDE_STATUSLINE_RELATIVE_PATH), "utf8").catch(() => null);
     let detectedTarget = null;
     if (lstat?.isSymbolicLink()) {
         detectedTarget = await fs.readlink(absolutePath).catch(() => null);
     }
+    const expectedClaudeOnboardCommand = pinnedVersion === null ? null : renderClaudeOnboardCommand(pinnedVersion);
+    const expectedClaudeCheckUpdateHook = pinnedVersion === null ? null : renderClaudeCheckUpdateHook(pinnedVersion);
+    const expectedClaudeCheckUpdateWorker = pinnedVersion === null ? null : renderClaudeCheckUpdateWorker(pinnedVersion);
+    const expectedClaudeStatusline = pinnedVersion === null ? null : renderClaudeUpdateStatusline(pinnedVersion);
+    const expectedClaudeStatusCommand = pinnedVersion === null ? null : renderClaudeStatusCommand(pinnedVersion);
+    const expectedClaudeMigrateCommand = pinnedVersion === null ? null : renderClaudeMigrateCommand(pinnedVersion);
+    const expectedClaudeUpdateCommand = pinnedVersion === null ? null : renderClaudeUpdateCommand(pinnedVersion);
+    const expectedClaudeCheckCommand = pinnedVersion === null ? null : renderClaudeCheckCommand(pinnedVersion);
+    const expectedClaudePrepareCommand = pinnedVersion === null ? null : renderClaudePrepareCommand(pinnedVersion);
+    const expectedClaudeVerifyCommand = pinnedVersion === null ? null : renderClaudeVerifyCommand(pinnedVersion);
+    const expectedClaudeScanCommand = pinnedVersion === null ? null : renderClaudeScanCommand(pinnedVersion);
     const surfaces = [
         createSurfaceStatus({
             kind: "symlink",
@@ -1368,21 +1736,30 @@ async function inspectClaudeAdapter(targetPath, guidance, projectMcp) {
             present: onboardCommandContent !== null,
             state: onboardCommandContent === null
                 ? "missing"
-                : onboardCommandContent === renderClaudeOnboardCommand()
-                    ? "ready"
-                    : "misconfigured",
+                : expectedClaudeOnboardCommand === null
+                    ? "missing"
+                    : onboardCommandContent === expectedClaudeOnboardCommand
+                        ? "ready"
+                        : "misconfigured",
             summary: onboardCommandContent === null
                 ? "Claude onboarding handoff is missing and should install `/gdh-onboard` under .claude/commands/."
-                : onboardCommandContent === renderClaudeOnboardCommand()
-                    ? "Claude can discover the managed `/gdh-onboard` handoff command."
-                    : "Claude onboarding handoff exists but no longer matches the expected managed GDH command.",
+                : expectedClaudeOnboardCommand === null
+                    ? "Claude onboarding handoff cannot be validated yet: no `gdh_version` is pinned (run `gdh setup` or `gdh migrate --apply`)."
+                    : onboardCommandContent === expectedClaudeOnboardCommand
+                        ? "Claude can discover the managed `/gdh-onboard` handoff command."
+                        : "Claude onboarding handoff exists but no longer matches the expected managed GDH command.",
             version: null,
         }),
-        ...inspectClaudeCommandSurface(targetPath, CLAUDE_STATUS_COMMAND_RELATIVE_PATH, claudeStatusContent, renderClaudeStatusCommand(), "gdh-status"),
-        ...inspectClaudeCommandSurface(targetPath, CLAUDE_MIGRATE_COMMAND_RELATIVE_PATH, claudeMigrateContent, renderClaudeMigrateCommand(), "gdh-migrate"),
-        ...inspectClaudeCommandSurface(targetPath, CLAUDE_CHECK_COMMAND_RELATIVE_PATH, claudeCheckContent, renderClaudeCheckCommand(), "gdh-check"),
-        ...inspectClaudeCommandSurface(targetPath, CLAUDE_PREPARE_COMMAND_RELATIVE_PATH, claudePrepareContent, renderClaudePrepareCommand(), "gdh-prepare"),
-        ...inspectClaudeCommandSurface(targetPath, CLAUDE_VERIFY_COMMAND_RELATIVE_PATH, claudeVerifyContent, renderClaudeVerifyCommand(), "gdh-verify"),
+        ...inspectClaudeCommandSurface(targetPath, CLAUDE_STATUS_COMMAND_RELATIVE_PATH, claudeStatusContent, expectedClaudeStatusCommand, "gdh-status"),
+        ...inspectClaudeCommandSurface(targetPath, CLAUDE_MIGRATE_COMMAND_RELATIVE_PATH, claudeMigrateContent, expectedClaudeMigrateCommand, "gdh-migrate"),
+        ...inspectClaudeCommandSurface(targetPath, CLAUDE_UPDATE_COMMAND_RELATIVE_PATH, claudeUpdateContent, expectedClaudeUpdateCommand, "gdh-update"),
+        ...inspectClaudeCommandSurface(targetPath, CLAUDE_CHECK_COMMAND_RELATIVE_PATH, claudeCheckContent, expectedClaudeCheckCommand, "gdh-check"),
+        ...inspectClaudeCommandSurface(targetPath, CLAUDE_PREPARE_COMMAND_RELATIVE_PATH, claudePrepareContent, expectedClaudePrepareCommand, "gdh-prepare"),
+        ...inspectClaudeCommandSurface(targetPath, CLAUDE_VERIFY_COMMAND_RELATIVE_PATH, claudeVerifyContent, expectedClaudeVerifyCommand, "gdh-verify"),
+        ...inspectClaudeCommandSurface(targetPath, CLAUDE_SCAN_COMMAND_RELATIVE_PATH, claudeScanContent, expectedClaudeScanCommand, "gdh-scan"),
+        ...inspectClaudeCommandSurface(targetPath, CLAUDE_CHECK_UPDATE_HOOK_RELATIVE_PATH, claudeCheckUpdateHookContent, expectedClaudeCheckUpdateHook, "gdh-check-update-hook"),
+        ...inspectClaudeCommandSurface(targetPath, CLAUDE_CHECK_UPDATE_WORKER_RELATIVE_PATH, claudeCheckUpdateWorkerContent, expectedClaudeCheckUpdateWorker, "gdh-check-update-worker"),
+        ...inspectClaudeCommandSurface(targetPath, CLAUDE_STATUSLINE_RELATIVE_PATH, claudeStatuslineContent, expectedClaudeStatusline, "gdh-statusline"),
     ];
     if (projectMcp.enabled) {
         surfaces.push(createSurfaceStatus({
@@ -1409,18 +1786,32 @@ async function inspectClaudeAdapter(targetPath, guidance, projectMcp) {
     }
     return createAgentStatus("claude", guidance, surfaces);
 }
-async function inspectCursorAdapter(targetPath, guidance, projectMcp) {
+async function inspectCursorAdapter(targetPath, guidance, projectMcp, pinnedVersion) {
     const absolutePath = path.join(targetPath, CURSOR_RULE_RELATIVE_PATH);
     const onboardSkillPath = path.join(targetPath, CURSOR_ONBOARD_SKILL_RELATIVE_PATH);
     const content = await fs.readFile(absolutePath, "utf8").catch(() => null);
     const onboardSkillContent = await fs.readFile(onboardSkillPath, "utf8").catch(() => null);
     const cursorStatusContent = await fs.readFile(path.join(targetPath, CURSOR_STATUS_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
     const cursorMigrateContent = await fs.readFile(path.join(targetPath, CURSOR_MIGRATE_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
+    // Phase 13 Plan 13-03 deliverable — /gdh-update skill for Cursor. Inspection
+    // wiring required so planSkillInstallAction sees the surface state; otherwise
+    // the planner returns `unchanged` for a missing file and install becomes a
+    // no-op (Plan 13-05 integration-test Rule 2 fix).
+    const cursorUpdateContent = await fs.readFile(path.join(targetPath, CURSOR_UPDATE_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
     const cursorCheckContent = await fs.readFile(path.join(targetPath, CURSOR_CHECK_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
     const cursorPrepareContent = await fs.readFile(path.join(targetPath, CURSOR_PREPARE_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
     const cursorVerifyContent = await fs.readFile(path.join(targetPath, CURSOR_VERIFY_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
+    const cursorScanContent = await fs.readFile(path.join(targetPath, CURSOR_SCAN_SKILL_RELATIVE_PATH), "utf8").catch(() => null);
     const expectedContent = renderCursorRule();
     const version = readCursorRuleVersion(content);
+    const expectedCursorOnboardSkill = pinnedVersion === null ? null : renderCursorOnboardSkill(pinnedVersion);
+    const expectedCursorStatusSkill = pinnedVersion === null ? null : renderCursorStatusSkill(pinnedVersion);
+    const expectedCursorMigrateSkill = pinnedVersion === null ? null : renderCursorMigrateSkill(pinnedVersion);
+    const expectedCursorUpdateSkill = pinnedVersion === null ? null : renderCursorUpdateSkill(pinnedVersion);
+    const expectedCursorCheckSkill = pinnedVersion === null ? null : renderCursorCheckSkill(pinnedVersion);
+    const expectedCursorPrepareSkill = pinnedVersion === null ? null : renderCursorPrepareSkill(pinnedVersion);
+    const expectedCursorVerifySkill = pinnedVersion === null ? null : renderCursorVerifySkill(pinnedVersion);
+    const expectedCursorScanSkill = pinnedVersion === null ? null : renderCursorScanSkill(pinnedVersion);
     const surfaces = [
         createSurfaceStatus({
             kind: "rule_file",
@@ -1448,21 +1839,27 @@ async function inspectCursorAdapter(targetPath, guidance, projectMcp) {
             present: onboardSkillContent !== null,
             state: onboardSkillContent === null
                 ? "missing"
-                : onboardSkillContent === renderCursorOnboardSkill()
-                    ? "ready"
-                    : "misconfigured",
+                : expectedCursorOnboardSkill === null
+                    ? "missing"
+                    : onboardSkillContent === expectedCursorOnboardSkill
+                        ? "ready"
+                        : "misconfigured",
             summary: onboardSkillContent === null
                 ? "Cursor onboarding handoff is missing and should install `/gdh-onboard` under .cursor/skills/."
-                : onboardSkillContent === renderCursorOnboardSkill()
-                    ? "Cursor can discover the managed `/gdh-onboard` handoff skill."
-                    : "Cursor onboarding handoff exists but no longer matches the expected managed GDH skill.",
+                : expectedCursorOnboardSkill === null
+                    ? "Cursor onboarding handoff cannot be validated yet: no `gdh_version` is pinned (run `gdh setup` or `gdh migrate --apply`)."
+                    : onboardSkillContent === expectedCursorOnboardSkill
+                        ? "Cursor can discover the managed `/gdh-onboard` handoff skill."
+                        : "Cursor onboarding handoff exists but no longer matches the expected managed GDH skill.",
             version: null,
         }),
-        ...inspectCursorSkillSurface(targetPath, CURSOR_STATUS_SKILL_RELATIVE_PATH, cursorStatusContent, renderCursorStatusSkill(), "gdh-status"),
-        ...inspectCursorSkillSurface(targetPath, CURSOR_MIGRATE_SKILL_RELATIVE_PATH, cursorMigrateContent, renderCursorMigrateSkill(), "gdh-migrate"),
-        ...inspectCursorSkillSurface(targetPath, CURSOR_CHECK_SKILL_RELATIVE_PATH, cursorCheckContent, renderCursorCheckSkill(), "gdh-check"),
-        ...inspectCursorSkillSurface(targetPath, CURSOR_PREPARE_SKILL_RELATIVE_PATH, cursorPrepareContent, renderCursorPrepareSkill(), "gdh-prepare"),
-        ...inspectCursorSkillSurface(targetPath, CURSOR_VERIFY_SKILL_RELATIVE_PATH, cursorVerifyContent, renderCursorVerifySkill(), "gdh-verify"),
+        ...inspectCursorSkillSurface(targetPath, CURSOR_STATUS_SKILL_RELATIVE_PATH, cursorStatusContent, expectedCursorStatusSkill, "gdh-status"),
+        ...inspectCursorSkillSurface(targetPath, CURSOR_MIGRATE_SKILL_RELATIVE_PATH, cursorMigrateContent, expectedCursorMigrateSkill, "gdh-migrate"),
+        ...inspectCursorSkillSurface(targetPath, CURSOR_UPDATE_SKILL_RELATIVE_PATH, cursorUpdateContent, expectedCursorUpdateSkill, "gdh-update"),
+        ...inspectCursorSkillSurface(targetPath, CURSOR_CHECK_SKILL_RELATIVE_PATH, cursorCheckContent, expectedCursorCheckSkill, "gdh-check"),
+        ...inspectCursorSkillSurface(targetPath, CURSOR_PREPARE_SKILL_RELATIVE_PATH, cursorPrepareContent, expectedCursorPrepareSkill, "gdh-prepare"),
+        ...inspectCursorSkillSurface(targetPath, CURSOR_VERIFY_SKILL_RELATIVE_PATH, cursorVerifyContent, expectedCursorVerifySkill, "gdh-verify"),
+        ...inspectCursorSkillSurface(targetPath, CURSOR_SCAN_SKILL_RELATIVE_PATH, cursorScanContent, expectedCursorScanSkill, "gdh-scan"),
     ];
     if (projectMcp.enabled) {
         surfaces.push(createSurfaceStatus({
@@ -1552,6 +1949,7 @@ async function planInstallActions(targetPath, adapters, requestedAgents, options
     const projectMcp = await inspectProjectMcpSupport(targetPath, {
         includeUserLocal: true,
         integrationRootPath: options.integrationRootPath,
+        pinnedVersion: options.pinnedVersion,
     });
     const actions = [];
     const effectiveDevRepoPath = options.devRepoPath ?? resolveCurrentGdhInstall(import.meta.url).defaultDevRepoPath;
@@ -1567,15 +1965,15 @@ async function planInstallActions(targetPath, adapters, requestedAgents, options
             continue;
         }
         if (adapter.agent === "codex") {
-            actions.push(...planCodexRepoInstallActions(targetPath, adapter));
+            actions.push(...planCodexRepoInstallActions(targetPath, adapter, options.pinnedVersion));
             continue;
         }
         if (adapter.agent === "claude") {
-            actions.push(...planClaudeInstallActions(targetPath, adapter));
+            actions.push(...planClaudeInstallActions(targetPath, adapter, options.pinnedVersion));
             continue;
         }
         if (adapter.agent === "cursor") {
-            actions.push(...planCursorInstallActions(targetPath, adapter));
+            actions.push(...planCursorInstallActions(targetPath, adapter, options.pinnedVersion));
         }
     }
     return dedupeInstallActions(actions);
@@ -1667,7 +2065,7 @@ function planSharedRepoInstallActions(targetPath, projectMcp, agent, effectiveDe
     }
     return actions;
 }
-function planSkillInstallAction(agent, targetPath, adapter, relativePath, renderFn, skillName) {
+function planSkillInstallAction(agent, targetPath, adapter, relativePath, renderFn, skillName, pinnedVersion) {
     const surface = adapter.surfaces.find((s) => s.relativePath === relativePath);
     if (!surface || surface.state === "ready") {
         return createInstallAction({
@@ -1679,7 +2077,7 @@ function planSkillInstallAction(agent, targetPath, adapter, relativePath, render
             state: "unchanged",
             mode: "unchanged",
             summary: `The managed ${agentLabel(agent)} \`/${skillName}\` ${agent === "claude" ? "command" : "skill"} already matches the expected GDH content.`,
-            content: renderFn(),
+            content: renderFn(pinnedVersion),
         });
     }
     return createInstallAction({
@@ -1693,7 +2091,7 @@ function planSkillInstallAction(agent, targetPath, adapter, relativePath, render
         summary: surface.present
             ? `Replace the existing ${agentLabel(agent)} \`/${skillName}\` ${agent === "claude" ? "command" : "skill"} with the managed GDH ${agent === "claude" ? "command" : "skill"}.`
             : `Create the managed ${agentLabel(agent)} \`/${skillName}\` ${agent === "claude" ? "command" : "skill"}.`,
-        content: renderFn(),
+        content: renderFn(pinnedVersion),
     });
 }
 function agentLabel(agent) {
@@ -1706,14 +2104,16 @@ function agentLabel(agent) {
             return "Cursor";
     }
 }
-function planCodexRepoInstallActions(targetPath, adapter) {
+function planCodexRepoInstallActions(targetPath, adapter, pinnedVersion) {
     return [
-        planSkillInstallAction("codex", targetPath, adapter, CODEX_ONBOARD_SKILL_RELATIVE_PATH, renderCodexOnboardSkill, "gdh-onboard"),
-        planSkillInstallAction("codex", targetPath, adapter, CODEX_STATUS_SKILL_RELATIVE_PATH, renderCodexStatusSkill, "gdh-status"),
-        planSkillInstallAction("codex", targetPath, adapter, CODEX_MIGRATE_SKILL_RELATIVE_PATH, renderCodexMigrateSkill, "gdh-migrate"),
-        planSkillInstallAction("codex", targetPath, adapter, CODEX_CHECK_SKILL_RELATIVE_PATH, renderCodexCheckSkill, "gdh-check"),
-        planSkillInstallAction("codex", targetPath, adapter, CODEX_PREPARE_SKILL_RELATIVE_PATH, renderCodexPrepareSkill, "gdh-prepare"),
-        planSkillInstallAction("codex", targetPath, adapter, CODEX_VERIFY_SKILL_RELATIVE_PATH, renderCodexVerifySkill, "gdh-verify"),
+        planSkillInstallAction("codex", targetPath, adapter, CODEX_ONBOARD_SKILL_RELATIVE_PATH, renderCodexOnboardSkill, "gdh-onboard", pinnedVersion),
+        planSkillInstallAction("codex", targetPath, adapter, CODEX_STATUS_SKILL_RELATIVE_PATH, renderCodexStatusSkill, "gdh-status", pinnedVersion),
+        planSkillInstallAction("codex", targetPath, adapter, CODEX_MIGRATE_SKILL_RELATIVE_PATH, renderCodexMigrateSkill, "gdh-migrate", pinnedVersion),
+        planSkillInstallAction("codex", targetPath, adapter, CODEX_UPDATE_SKILL_RELATIVE_PATH, renderCodexUpdateSkill, "gdh-update", pinnedVersion),
+        planSkillInstallAction("codex", targetPath, adapter, CODEX_CHECK_SKILL_RELATIVE_PATH, renderCodexCheckSkill, "gdh-check", pinnedVersion),
+        planSkillInstallAction("codex", targetPath, adapter, CODEX_PREPARE_SKILL_RELATIVE_PATH, renderCodexPrepareSkill, "gdh-prepare", pinnedVersion),
+        planSkillInstallAction("codex", targetPath, adapter, CODEX_VERIFY_SKILL_RELATIVE_PATH, renderCodexVerifySkill, "gdh-verify", pinnedVersion),
+        planSkillInstallAction("codex", targetPath, adapter, CODEX_SCAN_SKILL_RELATIVE_PATH, renderCodexScanSkill, "gdh-scan", pinnedVersion),
     ];
 }
 function planCodexUserInstallActions(targetPath, projectMcp, integrationRootPath) {
@@ -1764,7 +2164,7 @@ function planCodexUserInstallActions(targetPath, projectMcp, integrationRootPath
     }));
     return actions;
 }
-function planClaudeInstallActions(targetPath, adapter) {
+function planClaudeInstallActions(targetPath, adapter, pinnedVersion) {
     const actions = [];
     const claudeSurface = adapter.surfaces.find((surface) => surface.relativePath === CLAUDE_SHIM_RELATIVE_PATH);
     if (!claudeSurface || claudeSurface.state === "ready") {
@@ -1795,10 +2195,58 @@ function planClaudeInstallActions(targetPath, adapter) {
             expectedTarget: "AGENTS.md",
         }));
     }
-    actions.push(planSkillInstallAction("claude", targetPath, adapter, CLAUDE_ONBOARD_COMMAND_RELATIVE_PATH, renderClaudeOnboardCommand, "gdh-onboard"), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_STATUS_COMMAND_RELATIVE_PATH, renderClaudeStatusCommand, "gdh-status"), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_MIGRATE_COMMAND_RELATIVE_PATH, renderClaudeMigrateCommand, "gdh-migrate"), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_CHECK_COMMAND_RELATIVE_PATH, renderClaudeCheckCommand, "gdh-check"), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_PREPARE_COMMAND_RELATIVE_PATH, renderClaudePrepareCommand, "gdh-prepare"), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_VERIFY_COMMAND_RELATIVE_PATH, renderClaudeVerifyCommand, "gdh-verify"));
+    actions.push(planSkillInstallAction("claude", targetPath, adapter, CLAUDE_ONBOARD_COMMAND_RELATIVE_PATH, renderClaudeOnboardCommand, "gdh-onboard", pinnedVersion), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_STATUS_COMMAND_RELATIVE_PATH, renderClaudeStatusCommand, "gdh-status", pinnedVersion), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_MIGRATE_COMMAND_RELATIVE_PATH, renderClaudeMigrateCommand, "gdh-migrate", pinnedVersion), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_UPDATE_COMMAND_RELATIVE_PATH, renderClaudeUpdateCommand, "gdh-update", pinnedVersion), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_CHECK_COMMAND_RELATIVE_PATH, renderClaudeCheckCommand, "gdh-check", pinnedVersion), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_PREPARE_COMMAND_RELATIVE_PATH, renderClaudePrepareCommand, "gdh-prepare", pinnedVersion), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_VERIFY_COMMAND_RELATIVE_PATH, renderClaudeVerifyCommand, "gdh-verify", pinnedVersion), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_SCAN_COMMAND_RELATIVE_PATH, renderClaudeScanCommand, "gdh-scan", pinnedVersion), 
+    // UPD-01 managed hook surfaces baked at the pinned version.
+    planSkillInstallAction("claude", targetPath, adapter, CLAUDE_CHECK_UPDATE_HOOK_RELATIVE_PATH, renderClaudeCheckUpdateHook, "gdh-check-update-hook", pinnedVersion), planSkillInstallAction("claude", targetPath, adapter, CLAUDE_CHECK_UPDATE_WORKER_RELATIVE_PATH, renderClaudeCheckUpdateWorker, "gdh-check-update-worker", pinnedVersion), 
+    // UPD-02 managed statusline surface baked at the pinned version. The .js
+    // file is ALWAYS baked, even when settings.json statusLine is not owned
+    // by GDH (write-if-absent below) — users can manually point their config
+    // at gdh-statusline.js later; the baked file is a no-op until wired.
+    planSkillInstallAction("claude", targetPath, adapter, CLAUDE_STATUSLINE_RELATIVE_PATH, renderClaudeUpdateStatusline, "gdh-statusline", pinnedVersion));
+    // UPD-01 + UPD-02 .claude/settings.json composite patch action.
+    //   - Plan 02 (Strategy A, planner-lock #1): patch-merge the SessionStart
+    //     hook entry by exact command-literal match, preserving siblings.
+    //   - Plan 03 (write-if-absent, planner-lock #2 / D-18): add the statusLine
+    //     entry ONLY when no existing statusLine is configured (e.g. GSD-owned
+    //     or user-owned). Silent no-op for UPD-02 on targets where another
+    //     tool already owns the slot; the universal surface is MCP _meta.
+    //
+    // Synchronous read via fsSync is intentional: planClaudeInstallActions is
+    // called without `await`, and making it async would ripple to every sibling
+    // planner (Codex, Cursor). The composed patches are idempotent and
+    // commutative (proven in Task 1 Test J) so application order is irrelevant.
+    let existingSettingsContent = "";
+    try {
+        existingSettingsContent = fsSync.readFileSync(path.join(targetPath, CLAUDE_SETTINGS_RELATIVE_PATH), "utf8");
+    }
+    catch {
+        existingSettingsContent = "";
+    }
+    const patchedSettings = patchClaudeSettingsForGdhStatusline(patchClaudeSettingsForGdhSessionStart(existingSettingsContent));
+    const settingsIsUnchanged = existingSettingsContent === patchedSettings;
+    const settingsExistedOnDisk = existingSettingsContent.length > 0;
+    actions.push(createInstallAction({
+        agent: "claude",
+        kind: "write_file",
+        scope: "repo",
+        targetPath,
+        relativePath: CLAUDE_SETTINGS_RELATIVE_PATH,
+        state: settingsIsUnchanged ? "unchanged" : "planned",
+        mode: settingsIsUnchanged
+            ? "unchanged"
+            : settingsExistedOnDisk
+                ? "replace"
+                : "create",
+        summary: settingsIsUnchanged
+            ? "GDH SessionStart hook + statusline already registered in .claude/settings.json."
+            : settingsExistedOnDisk
+                ? "Register the GDH SessionStart hook and statusline (write-if-absent) in .claude/settings.json while preserving sibling content (patch-merge)."
+                : "Create .claude/settings.json with the GDH SessionStart hook + statusline registration.",
+        content: patchedSettings,
+    }));
     return actions;
 }
-function planCursorInstallActions(targetPath, adapter) {
+function planCursorInstallActions(targetPath, adapter, pinnedVersion) {
     const actions = [];
     const cursorRuleSurface = adapter.surfaces.find((surface) => surface.relativePath === CURSOR_RULE_RELATIVE_PATH);
     if (!cursorRuleSurface || cursorRuleSurface.state === "ready") {
@@ -1831,7 +2279,7 @@ function planCursorInstallActions(targetPath, adapter) {
             content: renderCursorRule(),
         }));
     }
-    actions.push(planSkillInstallAction("cursor", targetPath, adapter, CURSOR_ONBOARD_SKILL_RELATIVE_PATH, renderCursorOnboardSkill, "gdh-onboard"), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_STATUS_SKILL_RELATIVE_PATH, renderCursorStatusSkill, "gdh-status"), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_MIGRATE_SKILL_RELATIVE_PATH, renderCursorMigrateSkill, "gdh-migrate"), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_CHECK_SKILL_RELATIVE_PATH, renderCursorCheckSkill, "gdh-check"), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_PREPARE_SKILL_RELATIVE_PATH, renderCursorPrepareSkill, "gdh-prepare"), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_VERIFY_SKILL_RELATIVE_PATH, renderCursorVerifySkill, "gdh-verify"));
+    actions.push(planSkillInstallAction("cursor", targetPath, adapter, CURSOR_ONBOARD_SKILL_RELATIVE_PATH, renderCursorOnboardSkill, "gdh-onboard", pinnedVersion), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_STATUS_SKILL_RELATIVE_PATH, renderCursorStatusSkill, "gdh-status", pinnedVersion), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_MIGRATE_SKILL_RELATIVE_PATH, renderCursorMigrateSkill, "gdh-migrate", pinnedVersion), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_UPDATE_SKILL_RELATIVE_PATH, renderCursorUpdateSkill, "gdh-update", pinnedVersion), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_CHECK_SKILL_RELATIVE_PATH, renderCursorCheckSkill, "gdh-check", pinnedVersion), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_PREPARE_SKILL_RELATIVE_PATH, renderCursorPrepareSkill, "gdh-prepare", pinnedVersion), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_VERIFY_SKILL_RELATIVE_PATH, renderCursorVerifySkill, "gdh-verify", pinnedVersion), planSkillInstallAction("cursor", targetPath, adapter, CURSOR_SCAN_SKILL_RELATIVE_PATH, renderCursorScanSkill, "gdh-scan", pinnedVersion));
     return actions;
 }
 function dedupeInstallActions(actions) {
@@ -1929,7 +2377,7 @@ function resolveProjectMcpEnabled(projectConfig) {
 function createCodexServerName(projectKeySeed) {
     return `gdh-${projectKeySeed}`;
 }
-function renderManagedMcpLauncher() {
+export function renderManagedMcpLauncher(pinnedVersion) {
     return [
         "#!/usr/bin/env node",
         `// GDH MCP launcher v${GDH_MCP_LAUNCHER_VERSION}`,
@@ -1968,9 +2416,9 @@ function renderManagedMcpLauncher() {
         "  }",
         "}",
         "",
-        'const result = spawnSync("gdh", ["mcp", "serve", "--target", targetPath], { stdio: "inherit" });',
+        `const result = spawnSync("npx", ["-y", "@skillcap/gdh@${pinnedVersion}", "mcp", "serve", "--target", targetPath], { stdio: "inherit", cwd: targetPath });`,
         'if (result.error && result.error.code === "ENOENT") {',
-        '  console.error("GDH MCP launcher could not find a usable GDH server. Install `gdh` on PATH or run `gdh adapters install <target> --dev-repo <path-to-gdh>`.");',
+        `  console.error("GDH MCP launcher could not launch npx for @skillcap/gdh@${pinnedVersion}. Ensure Node.js 20+ is installed (npx ships with Node), or configure the contributor dev escape hatch via the GDH_DEV_REPO env var or .gdh-state/local-paths.json gdhDevRepoPath.");`,
         "  process.exit(1);",
         "}",
         "process.exit(result.status ?? 1);",
@@ -3050,4 +3498,7 @@ function deriveRepoState(context) {
 function normalizeChangedFiles(files) {
     return [...new Set(files.map((file) => file.trim()).filter((file) => file.length > 0))];
 }
+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";
 //# sourceMappingURL=index.js.map