@skillcap/gdh 0.5.0 → 0.7.0

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

@@ -5,7 +5,11 @@ import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 import { readProjectConfig, resolvePinnedVersion, resolvePinnedVersionOrNull, resolveProjectRoot, readWorktreeState, resolveAuthoringStatus, } from "@gdh/authoring";
-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 { 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_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";
 import { inspectRuntimeBridgeSurface } from "@gdh/runtime";
@@ -48,11 +52,20 @@ 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 CODEX_PROJECT_CONFIG_RELATIVE_PATH = ".codex/config.toml";
 export const GDH_MCP_SERVER_NAME = "gdh";
 const execFile = promisify(execFileCallback);
 export async function getSupportedAgentAdaptersStatus(targetPath, options = {}) {
@@ -203,7 +216,6 @@ export async function inspectProjectLifecycleCompatibility(targetPath) {
         await inspectGuidanceUnitLifecycleSurface(resolvedTargetPath, projectConfig),
         inspectMcpManifestLifecycleSurface(resolvedTargetPath, projectConfig.mcp.enabled, adapterStatus),
         inspectCursorRuleLifecycleSurface(resolvedTargetPath, adapterStatus),
-        inspectMcpLauncherLifecycleSurface(resolvedTargetPath, projectConfig.mcp.enabled, adapterStatus),
         inspectRuntimeBridgeLifecycleSurface(resolvedTargetPath, bridgeStatus),
     ]);
 }
@@ -774,6 +786,133 @@ export function renderCursorMigrateSkill(pinnedVersion) {
         "",
     ].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(pinnedVersion) {
     return [
@@ -1117,34 +1256,26 @@ export function renderCursorVerifySkill(pinnedVersion) {
 async function inspectProjectMcpSupport(targetPath, options) {
     const projectConfig = await readProjectConfig(targetPath);
     const enabled = resolveProjectMcpEnabled(projectConfig);
-    const launcherContent = options.pinnedVersion === null
-        ? null
-        : renderManagedMcpLauncher(options.pinnedVersion);
     const managedMcpEntry = buildManagedMcpServerEntry({
-        targetPath,
-        integrationRootPath: options.integrationRootPath,
-        launcherPathForConfig: path.resolve(options.integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH),
+        pinnedVersion: options.pinnedVersion ?? "latest",
     });
-    const [projectFile, cursorFile, launcherSource, localPathHints] = await Promise.all([
+    const [projectFile, cursorFile, codexProjectContent, localPathHints] = await Promise.all([
         inspectJsonFile(path.join(options.integrationRootPath, PROJECT_MCP_RELATIVE_PATH)),
         inspectJsonFile(path.join(options.integrationRootPath, CURSOR_MCP_RELATIVE_PATH)),
-        fs.readFile(path.join(options.integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH), "utf8").catch(() => null),
+        fs.readFile(path.join(options.integrationRootPath, CODEX_PROJECT_CONFIG_RELATIVE_PATH), "utf8").catch(() => null),
         readLocalPathHints(options.integrationRootPath),
     ]);
-    const launcherBootstrap = await inspectLauncherBootstrap(localPathHints);
     const codexConfigPath = path.join(os.homedir(), ".codex/config.toml");
     const codexServerName = projectConfig === null ? null : createCodexServerName(projectConfig.projectKeySeed);
     return {
         enabled,
         integrationRootPath: options.integrationRootPath,
-        launcherContent,
         localPathHints,
-        launcherBootstrap,
-        launcherFile: inspectLauncherFile(launcherSource, launcherContent, enabled, launcherBootstrap),
         projectFile: inspectManagedMcpFile(projectFile, enabled, PROJECT_MCP_RELATIVE_PATH, "Claude project MCP config", managedMcpEntry),
         cursorFile: inspectManagedMcpFile(cursorFile, enabled, CURSOR_MCP_RELATIVE_PATH, "Cursor project MCP config", managedMcpEntry),
+        codexProjectFile: inspectManagedCodexProjectFile(codexProjectContent, enabled, options.pinnedVersion),
         codexRegistration: options.includeUserLocal
-            ? await inspectCodexRegistration(targetPath, enabled, codexServerName, codexConfigPath, options.integrationRootPath)
+            ? await inspectCodexRegistration(targetPath, enabled, codexServerName, codexConfigPath, options.integrationRootPath, options.pinnedVersion)
             : {
                 present: false,
                 state: "ready",
@@ -1221,71 +1352,52 @@ function inspectManagedMcpFile(file, enabled, relativePath, displayName, expecte
         summary: `${displayName} includes the managed \`${GDH_MCP_SERVER_NAME}\` MCP server entry.`,
     };
 }
-function inspectLauncherFile(launcherSource, expectedContent, enabled, bootstrap) {
+function inspectManagedCodexProjectFile(content, enabled, pinnedVersion) {
+    const relativePath = CODEX_PROJECT_CONFIG_RELATIVE_PATH;
     if (!enabled) {
         return {
-            present: launcherSource !== null,
+            present: content !== null,
             state: "ready",
-            summary: "The managed GDH MCP launcher is disabled for this target.",
+            summary: "Codex project MCP config is disabled for this target.",
         };
     }
-    if (expectedContent === null) {
+    if (pinnedVersion === null) {
         return {
-            present: launcherSource !== null,
+            present: content !== 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.",
+            summary: `Codex project MCP config cannot be validated yet: no \`gdh_version\` is pinned (run \`gdh setup\` or \`gdh migrate --apply\`).`,
         };
     }
-    if (launcherSource === null) {
+    if (content === null) {
         return {
             present: false,
             state: "missing",
-            summary: `The managed GDH MCP launcher is missing and should live at ${MCP_LAUNCHER_RELATIVE_PATH}.`,
+            summary: `Codex project MCP config is missing and should define the managed \`[mcp_servers.${GDH_MCP_SERVER_NAME}]\` entry at ${relativePath}.`,
         };
     }
-    if (launcherSource !== expectedContent) {
+    const existingSection = extractManagedCodexSection(content);
+    const expectedSection = renderManagedCodexProjectSection(pinnedVersion);
+    if (existingSection === null) {
         return {
             present: true,
             state: "misconfigured",
-            summary: "The managed GDH MCP launcher exists but no longer matches the expected launcher content.",
+            summary: `${relativePath} exists but does not contain the managed \`[mcp_servers.${GDH_MCP_SERVER_NAME}]\` section.`,
         };
     }
-    return {
-        present: true,
-        state: bootstrap.state,
-        summary: bootstrap.state === "ready"
-            ? "The managed GDH MCP launcher is present and can resolve the current GDH bootstrap path."
-            : bootstrap.summary,
-    };
-}
-async function inspectLauncherBootstrap(localPathHints) {
-    const envDevRepoPath = process.env["GDH_DEV_REPO"]?.trim() || null;
-    const effectiveDevRepoPath = envDevRepoPath ?? localPathHints.gdhDevRepoPath;
-    if (effectiveDevRepoPath !== null) {
-        const cliEntryPath = path.join(effectiveDevRepoPath, "packages/cli/dist/cli.js");
-        if (await fileExists(cliEntryPath)) {
-            return {
-                state: "ready",
-                summary: `The managed GDH MCP launcher will bootstrap from the current GDH checkout at ${effectiveDevRepoPath}.`,
-            };
-        }
+    if (existingSection !== expectedSection) {
         return {
+            present: true,
             state: "misconfigured",
-            summary: `The configured GDH checkout at ${effectiveDevRepoPath} does not contain packages/cli/dist/cli.js yet. Run \`corepack yarn build\` in the GDH checkout or update the local path hints.`,
-        };
-    }
-    if (await executableExistsOnPath("gdh")) {
-        return {
-            state: "ready",
-            summary: "The managed GDH MCP launcher can resolve `gdh` from PATH.",
+            summary: `${relativePath} managed \`[mcp_servers.${GDH_MCP_SERVER_NAME}]\` section does not match the expected GDH shape.`,
         };
     }
     return {
-        state: "missing",
-        summary: "The managed GDH MCP launcher cannot find `gdh` on PATH and no local GDH checkout hint is recorded. Run `gdh adapters install <target> --dev-repo <path-to-gdh>` or install `gdh` on PATH.",
+        present: true,
+        state: "ready",
+        summary: `Codex project MCP config includes the managed \`[mcp_servers.${GDH_MCP_SERVER_NAME}]\` entry.`,
     };
 }
-async function inspectCodexRegistration(targetPath, enabled, codexServerName, codexConfigPath, integrationRootPath) {
+async function inspectCodexRegistration(targetPath, enabled, codexServerName, codexConfigPath, integrationRootPath, pinnedVersion) {
     if (!enabled || codexServerName === null) {
         return {
             present: false,
@@ -1309,16 +1421,22 @@ async function inspectCodexRegistration(targetPath, enabled, codexServerName, co
             summary: `Codex does not yet have the expected user-local MCP registration \`${codexServerName}\` in ${codexConfigPath}.`,
         };
     }
-    const expectedLauncherPath = path.join(integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH);
+    if (pinnedVersion === null) {
+        return {
+            present: true,
+            state: "misconfigured",
+            summary: `Codex MCP registration \`${codexServerName}\` exists but no \`gdh_version\` is pinned; cannot validate the expected npx invocation.`,
+        };
+    }
     if (!isMatchingCodexRegistration(registration, {
         targetPath,
         integrationRootPath,
-        launcherPath: expectedLauncherPath,
+        pinnedVersion,
     })) {
         return {
             present: true,
             state: "misconfigured",
-            summary: `Codex MCP registration \`${codexServerName}\` exists but does not point at the managed GDH launcher ${expectedLauncherPath}.`,
+            summary: `Codex MCP registration \`${codexServerName}\` exists but does not match the expected \`npx -y @skillcap/gdh@${pinnedVersion} mcp serve\` invocation.`,
         };
     }
     return {
@@ -1440,6 +1558,11 @@ async function inspectCodexAdapter(targetPath, guidance, projectMcp, pinnedVersi
     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);
@@ -1447,6 +1570,7 @@ async function inspectCodexAdapter(targetPath, guidance, projectMcp, pinnedVersi
     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);
@@ -1494,6 +1618,7 @@ async function inspectCodexAdapter(targetPath, guidance, projectMcp, pinnedVersi
         }),
         ...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"),
@@ -1501,14 +1626,14 @@ async function inspectCodexAdapter(targetPath, guidance, projectMcp, pinnedVersi
     ];
     if (projectMcp.enabled) {
         surfaces.push(createSurfaceStatus({
-            kind: "launcher_file",
+            kind: "mcp_file",
             scope: "repo",
             targetPath: projectMcp.integrationRootPath,
-            relativePath: MCP_LAUNCHER_RELATIVE_PATH,
-            present: projectMcp.launcherFile.present,
-            state: projectMcp.launcherFile.state,
-            summary: projectMcp.launcherFile.summary,
-            version: GDH_MCP_LAUNCHER_VERSION,
+            relativePath: CODEX_PROJECT_CONFIG_RELATIVE_PATH,
+            present: projectMcp.codexProjectFile.present,
+            state: projectMcp.codexProjectFile.state,
+            summary: projectMcp.codexProjectFile.summary,
+            version: null,
         }));
         if (options.includeUserLocal) {
             surfaces.push(createSurfaceStatus({
@@ -1533,17 +1658,29 @@ async function inspectClaudeAdapter(targetPath, guidance, projectMcp, pinnedVers
     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);
@@ -1593,22 +1730,17 @@ async function inspectClaudeAdapter(targetPath, guidance, projectMcp, pinnedVers
         }),
         ...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({
-            kind: "launcher_file",
-            scope: "repo",
-            targetPath: projectMcp.integrationRootPath,
-            relativePath: MCP_LAUNCHER_RELATIVE_PATH,
-            present: projectMcp.launcherFile.present,
-            state: projectMcp.launcherFile.state,
-            summary: projectMcp.launcherFile.summary,
-            version: GDH_MCP_LAUNCHER_VERSION,
-        }), createSurfaceStatus({
             kind: "mcp_file",
             scope: "repo",
             targetPath: projectMcp.integrationRootPath,
@@ -1630,6 +1762,11 @@ async function inspectCursorAdapter(targetPath, guidance, projectMcp, pinnedVers
     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);
@@ -1639,6 +1776,7 @@ async function inspectCursorAdapter(targetPath, guidance, projectMcp, pinnedVers
     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);
@@ -1686,6 +1824,7 @@ async function inspectCursorAdapter(targetPath, guidance, projectMcp, pinnedVers
         }),
         ...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"),
@@ -1693,15 +1832,6 @@ async function inspectCursorAdapter(targetPath, guidance, projectMcp, pinnedVers
     ];
     if (projectMcp.enabled) {
         surfaces.push(createSurfaceStatus({
-            kind: "launcher_file",
-            scope: "repo",
-            targetPath: projectMcp.integrationRootPath,
-            relativePath: MCP_LAUNCHER_RELATIVE_PATH,
-            present: projectMcp.launcherFile.present,
-            state: projectMcp.launcherFile.state,
-            summary: projectMcp.launcherFile.summary,
-            version: GDH_MCP_LAUNCHER_VERSION,
-        }), createSurfaceStatus({
             kind: "mcp_file",
             scope: "repo",
             targetPath: projectMcp.integrationRootPath,
@@ -1785,17 +1915,17 @@ async function planInstallActions(targetPath, adapters, requestedAgents, options
     const effectiveDevRepoPath = options.devRepoPath ?? resolveCurrentGdhInstall(import.meta.url).defaultDevRepoPath;
     if (options.user) {
         if (requestedAgents.includes("codex")) {
-            actions.push(...planCodexUserInstallActions(targetPath, projectMcp, options.integrationRootPath));
+            actions.push(...planCodexUserInstallActions(targetPath, projectMcp, options.integrationRootPath, options.pinnedVersion));
         }
         return dedupeInstallActions(actions);
     }
-    actions.push(...planSharedRepoInstallActions(targetPath, projectMcp, requestedAgents[0] ?? "claude", effectiveDevRepoPath, options.integrationRootPath));
+    actions.push(...planSharedRepoInstallActions(targetPath, projectMcp, requestedAgents[0] ?? "claude", effectiveDevRepoPath, options.integrationRootPath, options.pinnedVersion));
     for (const adapter of adapters) {
         if (!requestedAgents.includes(adapter.agent)) {
             continue;
         }
         if (adapter.agent === "codex") {
-            actions.push(...planCodexRepoInstallActions(targetPath, adapter, options.pinnedVersion));
+            actions.push(...planCodexRepoInstallActions(targetPath, adapter, options.pinnedVersion, projectMcp, options.integrationRootPath));
             continue;
         }
         if (adapter.agent === "claude") {
@@ -1808,27 +1938,11 @@ async function planInstallActions(targetPath, adapters, requestedAgents, options
     }
     return dedupeInstallActions(actions);
 }
-function planSharedRepoInstallActions(targetPath, projectMcp, agent, effectiveDevRepoPath, integrationRootPath) {
+function planSharedRepoInstallActions(targetPath, projectMcp, agent, effectiveDevRepoPath, integrationRootPath, pinnedVersion) {
     if (!projectMcp.enabled) {
         return [];
     }
     const actions = [];
-    if (projectMcp.launcherFile.state !== "ready") {
-        actions.push(createInstallAction({
-            agent,
-            kind: "write_file",
-            scope: "repo",
-            targetPath: integrationRootPath,
-            relativePath: MCP_LAUNCHER_RELATIVE_PATH,
-            state: "planned",
-            mode: projectMcp.launcherFile.present ? "replace" : "create",
-            summary: projectMcp.launcherFile.present
-                ? "Replace the managed GDH MCP launcher with the current launcher content."
-                : "Create the managed GDH MCP launcher under .gdh/bin/.",
-            version: GDH_MCP_LAUNCHER_VERSION,
-            content: projectMcp.launcherContent,
-        }));
-    }
     if (projectMcp.projectFile.state !== "ready") {
         actions.push(createInstallAction({
             agent,
@@ -1841,11 +1955,7 @@ function planSharedRepoInstallActions(targetPath, projectMcp, agent, effectiveDe
             summary: projectMcp.projectFile.present
                 ? "Replace the managed `gdh` MCP entry in .mcp.json while preserving any non-GDH servers."
                 : "Create .mcp.json with the managed `gdh` MCP entry.",
-            content: renderManagedMcpConfig(path.join(integrationRootPath, PROJECT_MCP_RELATIVE_PATH), buildManagedMcpServerEntry({
-                targetPath,
-                integrationRootPath,
-                launcherPathForConfig: path.resolve(integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH),
-            })),
+            content: renderManagedMcpConfig(path.join(integrationRootPath, PROJECT_MCP_RELATIVE_PATH), buildManagedMcpServerEntry({ pinnedVersion })),
         }));
     }
     if (projectMcp.cursorFile.state !== "ready") {
@@ -1860,11 +1970,7 @@ function planSharedRepoInstallActions(targetPath, projectMcp, agent, effectiveDe
             summary: projectMcp.cursorFile.present
                 ? "Replace the managed `gdh` MCP entry in .cursor/mcp.json while preserving any non-GDH servers."
                 : "Create .cursor/mcp.json with the managed `gdh` MCP entry.",
-            content: renderManagedMcpConfig(path.join(integrationRootPath, CURSOR_MCP_RELATIVE_PATH), buildManagedMcpServerEntry({
-                targetPath,
-                integrationRootPath,
-                launcherPathForConfig: path.resolve(integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH),
-            })),
+            content: renderManagedMcpConfig(path.join(integrationRootPath, CURSOR_MCP_RELATIVE_PATH), buildManagedMcpServerEntry({ pinnedVersion })),
         }));
     }
     if (projectMcp.localPathHints.gdhDevRepoPath !== effectiveDevRepoPath) {
@@ -1934,28 +2040,53 @@ function agentLabel(agent) {
             return "Cursor";
     }
 }
-function planCodexRepoInstallActions(targetPath, adapter, pinnedVersion) {
-    return [
+function planCodexRepoInstallActions(targetPath, adapter, pinnedVersion, projectMcp, integrationRootPath) {
+    const actions = [
         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),
     ];
+    if (projectMcp.enabled && projectMcp.codexProjectFile.state !== "ready") {
+        const absolutePath = path.join(integrationRootPath, CODEX_PROJECT_CONFIG_RELATIVE_PATH);
+        const existingContent = fsSync.existsSync(absolutePath)
+            ? fsSync.readFileSync(absolutePath, "utf8")
+            : null;
+        actions.push(createInstallAction({
+            agent: "codex",
+            kind: "write_file",
+            scope: "repo",
+            targetPath: integrationRootPath,
+            relativePath: CODEX_PROJECT_CONFIG_RELATIVE_PATH,
+            state: "planned",
+            mode: projectMcp.codexProjectFile.present ? "replace" : "create",
+            summary: projectMcp.codexProjectFile.present
+                ? `Replace the managed \`[mcp_servers.${GDH_MCP_SERVER_NAME}]\` section in .codex/config.toml while preserving any non-GDH content.`
+                : `Create .codex/config.toml with the managed \`[mcp_servers.${GDH_MCP_SERVER_NAME}]\` entry so Codex can discover the project MCP server without a user-global registration.`,
+            content: renderManagedCodexProjectConfig(existingContent, pinnedVersion),
+        }));
+    }
+    return actions;
 }
-function planCodexUserInstallActions(targetPath, projectMcp, integrationRootPath) {
+function planCodexUserInstallActions(targetPath, projectMcp, integrationRootPath, pinnedVersion) {
     if (!projectMcp.enabled || projectMcp.codexServerName === null) {
         return [];
     }
-    const expectedLauncherPath = path.join(integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH);
-    const codexArgs = buildManagedLauncherInvocationArgs({
-        targetPath,
-        integrationRootPath,
-        launcherPath: expectedLauncherPath,
-        useAbsoluteTargetPath: true,
-    });
+    const resolvedTargetPath = path.resolve(targetPath);
+    const resolvedIntegrationRootPath = path.resolve(integrationRootPath);
+    const codexCommandArgs = [
+        "-y",
+        `@skillcap/gdh@${pinnedVersion}`,
+        "mcp",
+        "serve",
+    ];
+    if (resolvedTargetPath !== resolvedIntegrationRootPath) {
+        codexCommandArgs.push("--target", resolvedTargetPath);
+    }
     const actions = [];
     if (projectMcp.codexRegistration.present) {
         actions.push(createInstallAction({
@@ -1967,7 +2098,7 @@ function planCodexUserInstallActions(targetPath, projectMcp, integrationRootPath
             absolutePath: projectMcp.codexConfigPath,
             state: "planned",
             mode: "replace",
-            summary: `Remove the existing Codex MCP registration \`${projectMcp.codexServerName}\` before re-registering it with the managed GDH launcher.`,
+            summary: `Remove the existing Codex MCP registration \`${projectMcp.codexServerName}\` before re-registering it with the managed GDH npx invocation.`,
             command: ["codex", "mcp", "remove", projectMcp.codexServerName],
         }));
     }
@@ -1980,15 +2111,15 @@ function planCodexUserInstallActions(targetPath, projectMcp, integrationRootPath
         absolutePath: projectMcp.codexConfigPath,
         state: "planned",
         mode: projectMcp.codexRegistration.present ? "replace" : "create",
-        summary: `Register the managed GDH launcher with Codex as \`${projectMcp.codexServerName}\`.`,
+        summary: `Register the managed GDH MCP server with Codex as \`${projectMcp.codexServerName}\` via pinned npx invocation.`,
         command: [
             "codex",
             "mcp",
             "add",
             projectMcp.codexServerName,
             "--",
-            "node",
-            ...codexArgs,
+            "npx",
+            ...codexCommandArgs,
         ],
     }));
     return actions;
@@ -2024,7 +2155,55 @@ function planClaudeInstallActions(targetPath, adapter, pinnedVersion) {
             expectedTarget: "AGENTS.md",
         }));
     }
-    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_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));
+    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, pinnedVersion) {
@@ -2060,7 +2239,7 @@ function planCursorInstallActions(targetPath, adapter, pinnedVersion) {
             content: renderCursorRule(),
         }));
     }
-    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_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));
+    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) {
@@ -2158,64 +2337,11 @@ function resolveProjectMcpEnabled(projectConfig) {
 function createCodexServerName(projectKeySeed) {
     return `gdh-${projectKeySeed}`;
 }
-export function renderManagedMcpLauncher(pinnedVersion) {
-    return [
-        "#!/usr/bin/env node",
-        `// GDH MCP launcher v${GDH_MCP_LAUNCHER_VERSION}`,
-        'import fs from "node:fs";',
-        'import path from "node:path";',
-        'import { spawnSync } from "node:child_process";',
-        'import { fileURLToPath } from "node:url";',
-        "",
-        "const launcherPath = fileURLToPath(import.meta.url);",
-        'const integrationRootPath = path.resolve(path.dirname(launcherPath), "../..");',
-        'const targetOptionIndex = process.argv.indexOf("--target");',
-        "const configuredTargetPath =",
-        '  targetOptionIndex >= 0 && typeof process.argv[targetOptionIndex + 1] === "string"',
-        "    ? process.argv[targetOptionIndex + 1]",
-        "    : null;",
-        "const targetPath = configuredTargetPath",
-        "  ? path.resolve(integrationRootPath, configuredTargetPath)",
-        "  : integrationRootPath;",
-        'const hintsPath = path.join(integrationRootPath, ".gdh-state", "local-paths.json");',
-        "",
-        "let gdhDevRepoPath = null;",
-        "try {",
-        '  const raw = fs.readFileSync(hintsPath, "utf8");',
-        "  const parsed = JSON.parse(raw);",
-        '  if (typeof parsed.gdhDevRepoPath === "string" && parsed.gdhDevRepoPath.length > 0) {',
-        "    gdhDevRepoPath = parsed.gdhDevRepoPath;",
-        "  }",
-        "} catch {}",
-        "",
-        "const effectiveDevRepoPath = process.env.GDH_DEV_REPO?.trim() || gdhDevRepoPath;",
-        "if (effectiveDevRepoPath) {",
-        '  const devCliEntryPath = path.join(effectiveDevRepoPath, "packages/cli/dist/cli.js");',
-        "  if (fs.existsSync(devCliEntryPath)) {",
-        '    const result = spawnSync(process.execPath, [devCliEntryPath, "mcp", "serve", "--target", targetPath], { stdio: "inherit" });',
-        "    process.exit(result.status ?? 1);",
-        "  }",
-        "}",
-        "",
-        `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 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);",
-        "",
-    ].join("\n");
-}
 function buildManagedMcpServerEntry(input) {
     return {
         type: "stdio",
-        command: "node",
-        args: buildManagedLauncherInvocationArgs({
-            targetPath: input.targetPath,
-            integrationRootPath: input.integrationRootPath,
-            launcherPath: input.launcherPathForConfig,
-            useAbsoluteTargetPath: true,
-        }),
+        command: "npx",
+        args: ["-y", `@skillcap/gdh@${input.pinnedVersion}`, "mcp", "serve"],
     };
 }
 function getManagedMcpServerEntry(jsonObject) {
@@ -2256,6 +2382,64 @@ function readExistingMcpConfig(absolutePath) {
         return {};
     }
 }
+// Renders the managed [mcp_servers.gdh] section for Codex project-local
+// config. The section body is line-based (no TOML parser) — preserves any
+// other content the user has in the file via regex replacement of the
+// bracketed header span. Exotic forms (inline-table `mcp_servers.gdh = {...}`
+// or dotted-key `mcp_servers.gdh.command = "..."`) are not detected; users
+// with those forms may end up with a duplicate and must migrate manually.
+export function renderManagedCodexProjectSection(pinnedVersion) {
+    return [
+        "[mcp_servers.gdh]",
+        'command = "npx"',
+        `args = ["-y", "@skillcap/gdh@${pinnedVersion}", "mcp", "serve"]`,
+    ].join("\n");
+}
+export function renderManagedCodexProjectConfig(existingContent, pinnedVersion) {
+    const section = renderManagedCodexProjectSection(pinnedVersion);
+    if (existingContent === null || existingContent.trim() === "") {
+        return `${section}\n`;
+    }
+    const lines = existingContent.split("\n");
+    const sectionStart = lines.findIndex((line) => /^\[mcp_servers\.gdh\]\s*$/.test(line));
+    if (sectionStart === -1) {
+        const trailingNewline = existingContent.endsWith("\n") ? "" : "\n";
+        const separator = existingContent.length > 0 ? "\n" : "";
+        return `${existingContent}${trailingNewline}${separator}${section}\n`;
+    }
+    let sectionEnd = lines.length;
+    for (let i = sectionStart + 1; i < lines.length; i++) {
+        if (/^\[/.test(lines[i] ?? "")) {
+            sectionEnd = i;
+            break;
+        }
+    }
+    const before = lines.slice(0, sectionStart).join("\n");
+    const afterLines = lines.slice(sectionEnd);
+    const after = afterLines.join("\n");
+    const beforeJoin = before.length > 0 ? `${before}\n` : "";
+    const afterNonEmpty = after.replace(/^\s+/, "");
+    const afterJoin = afterNonEmpty.length > 0 ? `\n\n${afterNonEmpty}` : "\n";
+    return `${beforeJoin}${section}${afterJoin}`;
+}
+function extractManagedCodexSection(content) {
+    const lines = content.split("\n");
+    const start = lines.findIndex((line) => /^\[mcp_servers\.gdh\]\s*$/.test(line));
+    if (start === -1) {
+        return null;
+    }
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^\[/.test(lines[i] ?? "")) {
+            end = i;
+            break;
+        }
+    }
+    return lines
+        .slice(start, end)
+        .join("\n")
+        .replace(/\s+$/, "");
+}
 function normalizeJson(value) {
     if (Array.isArray(value)) {
         return value.map((entry) => normalizeJson(entry));
@@ -2395,14 +2579,19 @@ async function listCodexMcpServers() {
     }
 }
 function isMatchingCodexRegistration(registration, input) {
-    const expectedArgs = buildManagedLauncherInvocationArgs({
-        targetPath: input.targetPath,
-        integrationRootPath: input.integrationRootPath,
-        launcherPath: input.launcherPath,
-        useAbsoluteTargetPath: true,
-    });
+    const resolvedTargetPath = path.resolve(input.targetPath);
+    const resolvedIntegrationRootPath = path.resolve(input.integrationRootPath);
+    const expectedArgs = [
+        "-y",
+        `@skillcap/gdh@${input.pinnedVersion}`,
+        "mcp",
+        "serve",
+    ];
+    if (resolvedTargetPath !== resolvedIntegrationRootPath) {
+        expectedArgs.push("--target", resolvedTargetPath);
+    }
     return (registration.transport?.type === "stdio" &&
-        registration.transport.command === "node" &&
+        registration.transport.command === "npx" &&
         JSON.stringify(registration.transport.args ?? []) === JSON.stringify(expectedArgs));
 }
 async function inspectProjectConfigLifecycleSurface(targetPath) {
@@ -2835,60 +3024,6 @@ function inspectCursorRuleLifecycleSurface(targetPath, adapterStatus) {
         },
     });
 }
-function inspectMcpLauncherLifecycleSurface(targetPath, mcpEnabled, adapterStatus) {
-    if (!mcpEnabled) {
-        return createLifecycleSurfaceStatus({
-            surface: "mcp_launcher",
-            management: "managed",
-            state: "compatible",
-            summary: "Project-scoped MCP launcher is not required while MCP is disabled.",
-            reasons: [],
-            probes: [],
-            action: null,
-        });
-    }
-    const launcherSurface = findAdapterSurface(adapterStatus, "claude", "launcher_file") ??
-        findAdapterSurface(adapterStatus, "cursor", "launcher_file") ??
-        findAdapterSurface(adapterStatus, "codex", "launcher_file");
-    const probes = launcherSurface === null
-        ? []
-        : [
-            createVersionProbe({
-                targetPath,
-                relativePath: launcherSurface.relativePath ?? MCP_LAUNCHER_RELATIVE_PATH,
-                present: launcherSurface.present,
-                expectedVersion: GDH_MCP_LAUNCHER_VERSION,
-                detectedVersion: launcherSurface.present ? launcherSurface.version : null,
-            }),
-        ];
-    if (launcherSurface?.state === "ready") {
-        return createLifecycleSurfaceStatus({
-            surface: "mcp_launcher",
-            management: "managed",
-            state: "compatible",
-            summary: "Managed MCP launcher file matches the current GDH version.",
-            reasons: [],
-            probes,
-            action: null,
-        });
-    }
-    return createLifecycleSurfaceStatus({
-        surface: "mcp_launcher",
-        management: "managed",
-        state: launcherSurface?.present ? "migration_available" : "migration_needed",
-        summary: "Managed MCP launcher file needs to be created or refreshed through the adapter install flow.",
-        reasons: launcherSurface?.present
-            ? ["mcp_launcher_misconfigured"]
-            : ["mcp_launcher_missing"],
-        probes,
-        action: {
-            kind: "run_repair",
-            summary: "Run GDH migrate or adapters install to refresh the managed MCP launcher file.",
-            command: ["gdh", "adapters", "install", targetPath],
-            autoApplicable: true,
-        },
-    });
-}
 function inspectRuntimeBridgeLifecycleSurface(targetPath, bridgeStatus) {
     const probes = bridgeStatus.managedArtifacts.map((artifact) => createVersionProbe({
         targetPath,
@@ -3279,4 +3414,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