@skillcap/gdh 0.4.1 → 0.6.0

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

@@ -1,18 +1,20 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { buildGdhStatusResult, createGsdSnapshot, getSupportedAgentAdaptersStatus, installSupportedAgentAdapters, } from "@gdh/adapters";
-import { getManagedLspStatus, hasCompleteOnboardingSurface, inspectCacheState, pruneCacheState, readProjectConfig, resolveProjectRoot, readWorktreeState, resolveAuthoringStatus, resolveTargetGodotDocsVersion, runAuthoringCheck, runImportRefresh, runTargetPrepare, runWarmup, } from "@gdh/authoring";
+import { buildGdhStatusResult, CLAUDE_CHECK_COMMAND_RELATIVE_PATH, CLAUDE_CHECK_UPDATE_HOOK_RELATIVE_PATH, CLAUDE_MIGRATE_COMMAND_RELATIVE_PATH, CLAUDE_ONBOARD_COMMAND_RELATIVE_PATH, CLAUDE_PREPARE_COMMAND_RELATIVE_PATH, CLAUDE_STATUS_COMMAND_RELATIVE_PATH, CLAUDE_VERIFY_COMMAND_RELATIVE_PATH, CODEX_CHECK_SKILL_RELATIVE_PATH, CODEX_MIGRATE_SKILL_RELATIVE_PATH, CODEX_ONBOARD_SKILL_RELATIVE_PATH, CODEX_PREPARE_SKILL_RELATIVE_PATH, CODEX_STATUS_SKILL_RELATIVE_PATH, CODEX_VERIFY_SKILL_RELATIVE_PATH, createGsdSnapshot, CURSOR_CHECK_SKILL_RELATIVE_PATH, CURSOR_MIGRATE_SKILL_RELATIVE_PATH, CURSOR_ONBOARD_SKILL_RELATIVE_PATH, CURSOR_PREPARE_SKILL_RELATIVE_PATH, CURSOR_STATUS_SKILL_RELATIVE_PATH, CURSOR_VERIFY_SKILL_RELATIVE_PATH, getSupportedAgentAdaptersStatus, installSupportedAgentAdapters, MCP_LAUNCHER_RELATIVE_PATH, } from "@gdh/adapters";
+import { getManagedLspStatus, hasCompleteOnboardingSurface, inspectCacheState, pruneCacheState, readProjectConfig, resolvePinnedVersion, resolveProjectRoot, readWorktreeState, resolveAuthoringStatus, resolveTargetGodotDocsVersion, runAuthoringCheck, runImportRefresh, runTargetPrepare, runWarmup, } from "@gdh/authoring";
 import { definePackageBoundary, GDH_AUTHORING_DOGFOOD_VERSION, GDH_AUTHORING_SLICE_REPORT_VERSION, GDH_PRODUCT_NAME, resolveCurrentGdhInstall, resolveGdhProductMetadata, } from "@gdh/core";
 import { fetchOfficialGodotDoc, getGuidanceStatus, resolveGuidanceQuery, searchOfficialGodotDocs, } from "@gdh/docs";
 import { createMcpManifest, invokeMcpTool, serveMcpOverStdio } from "@gdh/mcp";
 import { inspectAuthoringEffectiveness, inspectAuthoringSessions, inspectGuidanceAudit, recordAuthoringSessionEvent, } from "@gdh/observability";
 import { checkRuntimeRecipe, inspectRuntimeBridgeSurface, installRuntimeBridgeSurface, listRuntimeRecipes, removeRuntimeBridgeSurface, repairRuntimeBridgeSurface, runRuntimeRecipe, showRuntimeRecipe, } from "@gdh/runtime";
-import { applyRepairableOnboardingWrites, onboardGodotProject, scanGodotProjectInventory, } from "@gdh/scan";
+import { applyRepairableOnboardingWrites, onboardGodotProject, persistInventoryForTarget, readInventoryCacheOrScan, scanGodotProjectInventory, } from "@gdh/scan";
 import { evaluateDonePolicy, exerciseRuntimeCorpusEntry, inspectRuntimeCorpusStatus, inspectRuntimeVerificationBundleState, inspectRuntimeVerificationReadiness, listRuntimeScenarios, materializeRuntimeCorpusEntry, recommendValidationForChange, recordRuntimeCorpusValidation, runRuntimeVerificationScenario, showRuntimeScenario, } from "@gdh/verify";
 import { migrateProjectLifecycleSurface } from "./migrate.js";
 import { presentPublicRuntimeTerms } from "./public-terms.js";
+import { runSelfUpdateCommand } from "./self-update.js";
 import { executeSetupCommand, isSetupCanceledError, renderSetupIntro, renderSetupOutro, renderSetupSummary, } from "./setup.js";
+import { emitUpdateBannerIfStale } from "./update-banner.js";
 export const cliPackage = definePackageBoundary({
     name: "@gdh/cli",
     layer: "surface",
@@ -102,6 +104,9 @@ export async function runCli(args, io = { stdout: process.stdout, stderr: proces
     if (command === "migrate") {
         return runMigrateCommand(rest, io);
     }
+    if (command === "self-update") {
+        return runSelfUpdateCommand(rest, io);
+    }
     if (command === "cache") {
         return runCacheCommand(rest, io);
     }
@@ -111,7 +116,7 @@ export async function runCli(args, io = { stdout: process.stdout, stderr: proces
     io.stderr.write(`Unknown command: ${command}\n\n${renderHelp()}`);
     return 1;
 }
-function writeJsonResult(io, value, options = {}) {
+export function writeJsonResult(io, value, options = {}) {
     const output = options.presentRuntimeTerms ? presentPublicRuntimeTerms(value) : value;
     io.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
 }
@@ -134,12 +139,51 @@ async function runScanCommand(args, io) {
         return 1;
     }
     const targetPath = parsedTarget.targetPath;
+    const commandStartedAtMs = Date.now();
+    let onboardedRoot = null;
     try {
-        const inventory = await scanGodotProjectInventory(targetPath);
-        io.stdout.write(`${JSON.stringify(inventory, null, 2)}\n`);
+        onboardedRoot = await resolveProjectRoot(targetPath);
+        // Use readInventoryCacheOrScan so that a re-scan of an already-persisted, unchanged
+        // filesystem returns the cached inventory byte-for-byte identical to what is on disk.
+        // This lets persistInventoryForTarget detect mode: "unchanged" on repeat invocations,
+        // keeping the semantics idempotent for unmodified projects (REFR-01 TBD-04).
+        // For non-onboarded targets (onboardedRoot === null), fall back to a plain live scan.
+        const inventoryRoot = onboardedRoot ?? targetPath;
+        const inventoryResult = await readInventoryCacheOrScan(inventoryRoot);
+        const inventory = inventoryResult.inventory;
+        if (onboardedRoot !== null) {
+            const persisted = await persistInventoryForTarget(inventory, onboardedRoot);
+            await recordSessionEvent(onboardedRoot, {
+                commandStartedAtMs,
+                kind: "scan",
+                command: "gdh scan",
+                state: "succeeded",
+                summary: `Scanned target and persisted inventory to ${persisted.relativePath} (${persisted.mode}).`,
+                producedArtifacts: persisted.mode !== "unchanged" ? [persisted.relativePath] : [],
+            });
+            io.stdout.write(`${JSON.stringify({ inventory, persisted }, null, 2)}\n`);
+        }
+        else {
+            io.stdout.write(`${JSON.stringify({ inventory, persisted: null }, null, 2)}\n`);
+        }
         return 0;
     }
     catch (error) {
+        // Best-effort: if walk-up hasn't run yet, try it once in the catch path so we can still
+        // emit the session event when an onboarded root exists but the live scan threw.
+        if (onboardedRoot === null) {
+            onboardedRoot = await resolveProjectRoot(targetPath).catch(() => null);
+        }
+        if (onboardedRoot !== null) {
+            await recordSessionEvent(onboardedRoot, {
+                commandStartedAtMs,
+                kind: "scan",
+                command: "gdh scan",
+                state: "failed",
+                summary: "gdh scan failed before completing inventory write.",
+                errorMessage: formatCliError(error),
+            });
+        }
         io.stderr.write(`Failed to scan target "${targetPath}": ${formatCliError(error)}\n`);
         return 1;
     }
@@ -347,6 +391,11 @@ async function runStatusCommand(args, io) {
     }
     const targetPath = parsedTarget.targetPath;
     const commandStartedAtMs = Date.now();
+    // UPD-04: emit the update banner to stderr BEFORE primary work so the
+    // stderr prelude precedes any stdout JSON payload. D-13 scopes the banner
+    // to `gdh status` and `gdh verify` only. Silent when cache is null /
+    // current / offline / dev-mode (D-06).
+    await emitUpdateBannerIfStale(targetPath, io);
     try {
         const status = await buildGdhStatusResult(targetPath);
         await recordSessionEvent(targetPath, {
@@ -1209,6 +1258,8 @@ async function runVerifyCommand(args, io) {
             "                                                  Summarize runtime verification readiness, stale evidence, and recurring runtime feedback for one target.",
             "  corpus <status|record>",
             "                                                  Inspect or record runtime corpus release-readiness evidence as JSON.",
+            "  drift [target]",
+            "                                                  Check whether baked `@skillcap/gdh@<version>` literals (launcher + skills + commands) match .gdh/project.yaml gdh_version.",
             "  recommend [target] --files <path> [--files <path>...]",
             "                                                  Recommend authoring-first validation requirements for the supplied change set.",
             "  done [target] --files <path> [--files <path>...] [--performed <kind>]",
@@ -1216,6 +1267,16 @@ async function runVerifyCommand(args, io) {
         ].join("\n") + "\n");
         return 0;
     }
+    // UPD-04: emit the update banner to stderr BEFORE dispatching to verify
+    // subcommands so the stderr prelude precedes any stdout JSON payload. D-13
+    // scopes the banner to `gdh status` and `gdh verify` only. Target for the
+    // banner's pre-onboard re-check is the first non-flag positional arg
+    // after the subcommand (falling back to "."). The cache itself is per-user,
+    // not per-target, so any resolvable path suffices for the dev-mode check.
+    {
+        const verifyTargetPath = rest.find((arg) => !arg.startsWith("--")) ?? ".";
+        await emitUpdateBannerIfStale(verifyTargetPath, io);
+    }
     if (subcommand === "recommend") {
         return runVerifyRecommendCommand(rest, io);
     }
@@ -1234,6 +1295,9 @@ async function runVerifyCommand(args, io) {
     if (subcommand === "corpus") {
         return runVerifyCorpusCommand(rest, io);
     }
+    if (subcommand === "drift") {
+        return runVerifyDriftCommand(rest, io);
+    }
     io.stderr.write([
         `Unknown verify command: ${subcommand}`,
         "",
@@ -1244,6 +1308,7 @@ async function runVerifyCommand(args, io) {
         "Usage: gdh verify corpus materialize --entry <id> [--manifest <path>] [--workspace-root <path>]",
         "Usage: gdh verify corpus exercise --entry <id> [--manifest <path>] [--workspace-root <path>] [--no-prepare]",
         "Usage: gdh verify corpus record --entry <id> --target <path> [--manifest <path>] [--workspace-root <path>]",
+        "Usage: gdh verify drift [target]",
         "Usage: gdh verify recommend [target] --files <path> [--files <path>...]",
         "Usage: gdh verify done [target] --files <path> [--files <path>...] [--performed <kind>]",
     ].join("\n") + "\n");
@@ -1583,14 +1648,15 @@ async function runRecipeListCommand(args, io) {
         return 1;
     }
     const targetPath = positionalArgs[0] ?? ".";
+    const effectiveTargetPath = await resolveEffectiveTargetPath(targetPath);
     const commandStartedAtMs = Date.now();
     try {
-        const projectConfig = await readProjectConfig(targetPath);
+        const projectConfig = await readProjectConfig(effectiveTargetPath);
         const result = await listRuntimeRecipes({
-            targetPath,
+            targetPath: effectiveTargetPath,
             projectConfig,
         });
-        await recordSessionEvent(targetPath, {
+        await recordSessionEvent(effectiveTargetPath, {
             commandStartedAtMs,
             kind: "recipe_list",
             command: "gdh run-config list",
@@ -1601,7 +1667,7 @@ async function runRecipeListCommand(args, io) {
         return 0;
     }
     catch (error) {
-        await recordSessionEvent(targetPath, {
+        await recordSessionEvent(effectiveTargetPath, {
             commandStartedAtMs,
             kind: "recipe_list",
             command: "gdh run-config list",
@@ -1636,15 +1702,16 @@ async function runRecipeShowCommand(args, io) {
     }
     const targetPath = positionalArgs.length === 1 ? "." : positionalArgs[0];
     const recipeId = positionalArgs.length === 1 ? positionalArgs[0] : positionalArgs[1];
+    const effectiveTargetPath = await resolveEffectiveTargetPath(targetPath);
     const commandStartedAtMs = Date.now();
     try {
-        const projectConfig = await readProjectConfig(targetPath);
+        const projectConfig = await readProjectConfig(effectiveTargetPath);
         const result = await showRuntimeRecipe({
-            targetPath,
+            targetPath: effectiveTargetPath,
             projectConfig,
             recipeId,
         });
-        await recordSessionEvent(targetPath, {
+        await recordSessionEvent(effectiveTargetPath, {
             commandStartedAtMs,
             kind: "recipe_show",
             command: "gdh run-config show",
@@ -1655,7 +1722,7 @@ async function runRecipeShowCommand(args, io) {
         return result.state === "ready" ? 0 : 1;
     }
     catch (error) {
-        await recordSessionEvent(targetPath, {
+        await recordSessionEvent(effectiveTargetPath, {
             commandStartedAtMs,
             kind: "recipe_show",
             command: "gdh run-config show",
@@ -1691,11 +1758,12 @@ async function runRecipeCheckCommand(args, io) {
     }
     const targetPath = positionalArgs.length === 1 ? "." : positionalArgs[0];
     const recipeId = positionalArgs.length === 1 ? positionalArgs[0] : positionalArgs[1];
+    const effectiveTargetPath = await resolveEffectiveTargetPath(targetPath);
     const commandStartedAtMs = Date.now();
     try {
-        const projectConfig = await readProjectConfig(targetPath);
+        const projectConfig = await readProjectConfig(effectiveTargetPath);
         const result = await checkRuntimeRecipe({
-            targetPath,
+            targetPath: effectiveTargetPath,
             projectConfig,
             recipeId,
             provider: readSingleOptionValue(args, "--provider"),
@@ -1705,7 +1773,7 @@ async function runRecipeCheckCommand(args, io) {
             environment: collectAssignmentOptionValues(args, "--env"),
             workspaceMode: "isolated_copy",
         });
-        await recordSessionEvent(targetPath, {
+        await recordSessionEvent(effectiveTargetPath, {
             commandStartedAtMs,
             kind: "recipe_check",
             command: "gdh run-config check",
@@ -1716,7 +1784,7 @@ async function runRecipeCheckCommand(args, io) {
         return result.state === "runnable" ? 0 : 1;
     }
     catch (error) {
-        await recordSessionEvent(targetPath, {
+        await recordSessionEvent(effectiveTargetPath, {
             commandStartedAtMs,
             kind: "recipe_check",
             command: "gdh run-config check",
@@ -1753,11 +1821,12 @@ async function runRecipeRunCommand(args, io) {
     }
     const targetPath = positionalArgs.length === 1 ? "." : positionalArgs[0];
     const recipeId = positionalArgs.length === 1 ? positionalArgs[0] : positionalArgs[1];
+    const effectiveTargetPath = await resolveEffectiveTargetPath(targetPath);
     const commandStartedAtMs = Date.now();
     try {
-        const projectConfig = await readProjectConfig(targetPath);
+        const projectConfig = await readProjectConfig(effectiveTargetPath);
         const result = await runRuntimeRecipe({
-            targetPath,
+            targetPath: effectiveTargetPath,
             projectConfig,
             recipeId,
             provider: readSingleOptionValue(args, "--provider"),
@@ -1767,7 +1836,7 @@ async function runRecipeRunCommand(args, io) {
             environment: collectAssignmentOptionValues(args, "--env"),
             workspaceMode: args.includes("--live-workspace") ? "live_workspace" : "isolated_copy",
         });
-        await recordSessionEvent(targetPath, {
+        await recordSessionEvent(effectiveTargetPath, {
             commandStartedAtMs,
             kind: "recipe_run",
             command: "gdh run-config run",
@@ -1779,7 +1848,7 @@ async function runRecipeRunCommand(args, io) {
         return result.state === "passed" ? 0 : 1;
     }
     catch (error) {
-        await recordSessionEvent(targetPath, {
+        await recordSessionEvent(effectiveTargetPath, {
             commandStartedAtMs,
             kind: "recipe_run",
             command: "gdh run-config run",
@@ -1813,10 +1882,11 @@ async function runScenarioListCommand(args, io) {
         return 1;
     }
     const targetPath = positionalArgs[0] ?? ".";
+    const effectiveTargetPath = await resolveEffectiveTargetPath(targetPath);
     const commandStartedAtMs = Date.now();
     try {
-        const result = await listRuntimeScenarios({ targetPath });
-        await recordSessionEvent(targetPath, {
+        const result = await listRuntimeScenarios({ targetPath: effectiveTargetPath });
+        await recordSessionEvent(effectiveTargetPath, {
             commandStartedAtMs,
             kind: "scenario_list",
             command: "gdh verification-scenario list",
@@ -1827,7 +1897,7 @@ async function runScenarioListCommand(args, io) {
         return result.state === "ready" ? 0 : 1;
     }
     catch (error) {
-        await recordSessionEvent(targetPath, {
+        await recordSessionEvent(effectiveTargetPath, {
             commandStartedAtMs,
             kind: "scenario_list",
             command: "gdh verification-scenario list",
@@ -1862,13 +1932,14 @@ async function runScenarioShowCommand(args, io) {
     }
     const targetPath = positionalArgs.length === 1 ? "." : positionalArgs[0];
     const scenarioId = positionalArgs.length === 1 ? positionalArgs[0] : positionalArgs[1];
+    const effectiveTargetPath = await resolveEffectiveTargetPath(targetPath);
     const commandStartedAtMs = Date.now();
     try {
         const result = await showRuntimeScenario({
-            targetPath,
+            targetPath: effectiveTargetPath,
             scenarioId,
         });
-        await recordSessionEvent(targetPath, {
+        await recordSessionEvent(effectiveTargetPath, {
             commandStartedAtMs,
             kind: "scenario_show",
             command: "gdh verification-scenario show",
@@ -1879,7 +1950,7 @@ async function runScenarioShowCommand(args, io) {
         return result.state === "ready" ? 0 : 1;
     }
     catch (error) {
-        await recordSessionEvent(targetPath, {
+        await recordSessionEvent(effectiveTargetPath, {
             commandStartedAtMs,
             kind: "scenario_show",
             command: "gdh verification-scenario show",
@@ -2106,10 +2177,17 @@ async function runMcpInvokeCommand(args, io) {
         return 1;
     }
 }
-async function buildAuthoringContext(targetPath) {
+async function resolveEffectiveTargetPath(targetPath) {
     const resolvedRoot = await resolveProjectRoot(targetPath);
-    const effectiveTargetPath = resolvedRoot ?? targetPath;
-    const inventory = await scanGodotProjectInventory(effectiveTargetPath);
+    return resolvedRoot ?? targetPath;
+}
+async function buildAuthoringContext(targetPath, io) {
+    const effectiveTargetPath = await resolveEffectiveTargetPath(targetPath);
+    const inventoryResult = await readInventoryCacheOrScan(effectiveTargetPath);
+    if (inventoryResult.degraded && io !== undefined) {
+        io.stderr.write(`Warning: .gdh-state/inventory.json is corrupt or unreadable; fell back to live scan.\n`);
+    }
+    const inventory = inventoryResult.inventory;
     const projectConfig = await readProjectConfig(effectiveTargetPath);
     const worktreeState = await readWorktreeState(effectiveTargetPath);
     const status = resolveAuthoringStatus({
@@ -2311,11 +2389,12 @@ async function runVerifyRunCommand(args, io) {
     }
     const targetPath = positionalArgs.length === 1 ? "." : positionalArgs[0];
     const recipeId = positionalArgs.length === 1 ? positionalArgs[0] : positionalArgs[1];
+    const effectiveTargetPath = await resolveEffectiveTargetPath(targetPath);
     const commandStartedAtMs = Date.now();
     try {
-        const projectConfig = await readProjectConfig(targetPath);
+        const projectConfig = await readProjectConfig(effectiveTargetPath);
         const result = await runRuntimeVerificationScenario({
-            targetPath,
+            targetPath: effectiveTargetPath,
             projectConfig,
             recipeId,
             scenarioId,
@@ -2326,7 +2405,7 @@ async function runVerifyRunCommand(args, io) {
             environment: collectAssignmentOptionValues(args, "--env"),
             workspaceMode: args.includes("--live-workspace") ? "live_workspace" : "isolated_copy",
         });
-        await recordSessionEvent(targetPath, {
+        await recordSessionEvent(effectiveTargetPath, {
             commandStartedAtMs,
             kind: "verify_run",
             command: "gdh verify run",
@@ -2342,7 +2421,7 @@ async function runVerifyRunCommand(args, io) {
         return result.outcome === "passed" || result.outcome === "flaky" ? 0 : 1;
     }
     catch (error) {
-        await recordSessionEvent(targetPath, {
+        await recordSessionEvent(effectiveTargetPath, {
             commandStartedAtMs,
             kind: "verify_run",
             command: "gdh verify run",
@@ -2462,6 +2541,179 @@ async function runVerifyReadinessCommand(args, io) {
         return 1;
     }
 }
+const VERIFY_DRIFT_SCANNED_FILES = [
+    { relativePath: MCP_LAUNCHER_RELATIVE_PATH, description: "managed MCP launcher" },
+    { relativePath: CODEX_ONBOARD_SKILL_RELATIVE_PATH, description: "Codex gdh-onboard skill" },
+    { relativePath: CODEX_STATUS_SKILL_RELATIVE_PATH, description: "Codex gdh-status skill" },
+    { relativePath: CODEX_MIGRATE_SKILL_RELATIVE_PATH, description: "Codex gdh-migrate skill" },
+    { relativePath: CODEX_CHECK_SKILL_RELATIVE_PATH, description: "Codex gdh-check skill" },
+    { relativePath: CODEX_PREPARE_SKILL_RELATIVE_PATH, description: "Codex gdh-prepare skill" },
+    { relativePath: CODEX_VERIFY_SKILL_RELATIVE_PATH, description: "Codex gdh-verify skill" },
+    { relativePath: CURSOR_ONBOARD_SKILL_RELATIVE_PATH, description: "Cursor gdh-onboard skill" },
+    { relativePath: CURSOR_STATUS_SKILL_RELATIVE_PATH, description: "Cursor gdh-status skill" },
+    { relativePath: CURSOR_MIGRATE_SKILL_RELATIVE_PATH, description: "Cursor gdh-migrate skill" },
+    { relativePath: CURSOR_CHECK_SKILL_RELATIVE_PATH, description: "Cursor gdh-check skill" },
+    { relativePath: CURSOR_PREPARE_SKILL_RELATIVE_PATH, description: "Cursor gdh-prepare skill" },
+    { relativePath: CURSOR_VERIFY_SKILL_RELATIVE_PATH, description: "Cursor gdh-verify skill" },
+    { relativePath: CLAUDE_ONBOARD_COMMAND_RELATIVE_PATH, description: "Claude gdh/onboard command" },
+    { relativePath: CLAUDE_STATUS_COMMAND_RELATIVE_PATH, description: "Claude gdh/status command" },
+    { relativePath: CLAUDE_MIGRATE_COMMAND_RELATIVE_PATH, description: "Claude gdh/migrate command" },
+    { relativePath: CLAUDE_CHECK_COMMAND_RELATIVE_PATH, description: "Claude gdh/check command" },
+    { relativePath: CLAUDE_PREPARE_COMMAND_RELATIVE_PATH, description: "Claude gdh/prepare command" },
+    { relativePath: CLAUDE_VERIFY_COMMAND_RELATIVE_PATH, description: "Claude gdh/verify command" },
+    // Phase 12 extension — close the Phase 11 coverage gap (research §Baked Version Surface Inventory rows 26-28).
+    // These files are re-baked at pin time and must be audited by MIG-02's post-condition invariant.
+    //
+    // SessionStart hook: bakes `GDH_PINNED_VERSION: "<semver>"` (not an npx literal). Uses a
+    // dedicated versionRegex to extract the pin from that env-injection pattern.
+    {
+        relativePath: CLAUDE_CHECK_UPDATE_HOOK_RELATIVE_PATH,
+        description: "Claude SessionStart update hook",
+        // The hook body sets GDH_PINNED_VERSION: "<semver>" in the spawned worker's env.
+        // VERIFY_DRIFT_BAKED_VERSION_REGEX matches `@skillcap/gdh@<v>` npx literals; this
+        // supplementary regex extracts the pin from the env-injection literal instead.
+        versionRegex: /GDH_PINNED_VERSION:\s*"(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)"/,
+    },
+    // Intentionally excluded: the Claude background worker (gdh-check-update-worker.js) — the
+    // worker script body reads GDH_PINNED_VERSION from process.env at runtime and does NOT contain
+    // an `@skillcap/gdh@<v>` literal or any other baked-version pattern. Adding it would cause
+    // VERIFY_DRIFT_BAKED_VERSION_REGEX to report `no_baked_version` → false positive. Worker drift
+    // is audited via the `// gdh-hook-version: N` marker through the renderer-layer contract, not
+    // via this version-literal scanner. Covered in integration tests at
+    // packages/adapters/src/claude-update-install-integration.test.ts.
+    //
+    // Intentionally excluded: the Claude statusline (gdh-statusline.js) — the statusline renderer
+    // produces a version-agnostic script (reads the update cache at runtime; no semver literal baked
+    // in the output). Adding it would permanently report `no_baked_version` → false positive. The
+    // statusline IS re-baked on every `gdh adapters install` via the renderer pipeline, which ensures
+    // it stays current with the hook version; pin-literal drift detection is not applicable here.
+    //
+    // Intentionally excluded: the Claude /gdh-update command (.claude/commands/gdh/update.md) —
+    // the rendered command shells out to `npx -y @skillcap/gdh@latest self-update` (LITERAL @latest,
+    // not @<pinnedVersion>). The shellout MUST bake @latest so the NEW CLI performs the update,
+    // not the OLD (potentially buggy) pinned one. Because @latest is not a semver literal, the
+    // VERIFY_DRIFT_BAKED_VERSION_REGEX finds no pinned-version match and would permanently report
+    // `no_baked_version` → false positive. Phase 13 D-13 locks this exclusion; Check 44 in
+    // scripts/validate-docs.mjs enforces both the @latest invariant and the exclusion.
+    //
+    // Intentionally excluded: the Codex gdh-update skill (.codex/skills/gdh-update/SKILL.md) —
+    // same rationale: renders @skillcap/gdh@latest, not @<pinnedVersion>. Phase 13 D-13.
+    //
+    // Intentionally excluded: the Cursor gdh-update skill (.cursor/skills/gdh-update/SKILL.md) —
+    // same rationale: renders @skillcap/gdh@latest, not @<pinnedVersion>. Phase 13 D-13.
+];
+// Mirrors EXACT_SEMVER_PATTERN in @gdh/authoring so only well-formed SemVer
+// values match — drift check does not pick up unrelated doc prose.
+const VERIFY_DRIFT_BAKED_VERSION_REGEX = /@skillcap\/gdh@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)/;
+async function runVerifyDriftCommand(args, io) {
+    if (args.includes("--help") || args.includes("help")) {
+        io.stdout.write([
+            "Usage: gdh verify drift [target]",
+            "",
+            "Compares every baked `@skillcap/gdh@<version>` literal across the managed",
+            "surfaces (.gdh/bin/gdh-mcp.mjs launcher + regenerated Codex/Cursor/Claude",
+            "skill + command files) against .gdh/project.yaml gdh_version. Exits 1 and",
+            "emits a structured JSON result when ANY file's baked version diverges from",
+            "the pinned value. Covers ROADMAP Success Criterion #3 (one source of truth).",
+            "",
+        ].join("\n"));
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh verify drift [target]\n",
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set());
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh verify drift accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const commandStartedAtMs = Date.now();
+    let pinnedVersion;
+    try {
+        pinnedVersion = await resolvePinnedVersion(targetPath);
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "verify_drift",
+            command: "gdh verify drift",
+            state: "failed",
+            summary: "Drift check could not resolve the pinned GDH version for this target.",
+            errorMessage: formatCliError(error),
+        });
+        // D-07: surface the concrete `gdh migrate --apply` guidance that the
+        // resolvePinnedVersion throw already names — write the full error
+        // message to stdout so agents parsing JSON get the fix command and
+        // stderr so operators get an unmistakable failure line.
+        const message = formatCliError(error);
+        io.stdout.write(`${message}\n`);
+        io.stderr.write(`Failed to check managed-surface drift for "${targetPath}": ${message}\n`);
+        return 1;
+    }
+    const fileResults = await Promise.all(VERIFY_DRIFT_SCANNED_FILES.map(async (file) => {
+        const absolutePath = path.join(targetPath, file.relativePath);
+        const content = await fs.readFile(absolutePath, "utf8").catch(() => null);
+        if (content === null) {
+            return {
+                relativePath: file.relativePath,
+                description: file.description,
+                present: false,
+                baked: null,
+                drift: true,
+                reason: "file_missing",
+            };
+        }
+        const match = content.match(file.versionRegex ?? VERIFY_DRIFT_BAKED_VERSION_REGEX);
+        const baked = match?.[1] ?? null;
+        const reason = baked === null
+            ? "no_baked_version"
+            : baked !== pinnedVersion
+                ? "version_mismatch"
+                : "ok";
+        return {
+            relativePath: file.relativePath,
+            description: file.description,
+            present: true,
+            baked,
+            drift: reason !== "ok",
+            reason,
+        };
+    }));
+    const driftFiles = fileResults.filter((file) => file.drift);
+    const overallDrift = driftFiles.length > 0;
+    const result = {
+        ok: !overallDrift,
+        drift: overallDrift,
+        pinned: pinnedVersion,
+        scannedFileCount: fileResults.length,
+        driftFileCount: driftFiles.length,
+        files: fileResults,
+        action: overallDrift
+            ? {
+                kind: "run_repair",
+                summary: `${driftFiles.length} managed-surface file(s) have a baked version that does not match .gdh/project.yaml gdh_version. Run \`gdh adapters install\` to regenerate them.`,
+                command: ["gdh", "adapters", "install", targetPath],
+                autoApplicable: true,
+            }
+            : null,
+    };
+    await recordSessionEvent(targetPath, {
+        commandStartedAtMs,
+        kind: "verify_drift",
+        command: "gdh verify drift",
+        state: overallDrift ? "failed" : "succeeded",
+        summary: overallDrift
+            ? `Detected ${driftFiles.length} managed-surface file(s) with a baked version drifted from gdh_version.`
+            : `All ${fileResults.length} managed-surface file(s) match .gdh/project.yaml gdh_version.`,
+    });
+    writeJsonResult(io, result);
+    return overallDrift ? 1 : 0;
+}
 async function runVerifyCorpusStatusCommand(args, io) {
     if (args.includes("--help")) {
         io.stdout.write([
@@ -3541,7 +3793,7 @@ function renderHelp() {
         "Run `gdh <command> --help` for command-specific usage.",
     ].join("\n") + "\n");
 }
-function formatCliError(error) {
+export function formatCliError(error) {
     return error instanceof Error ? error.message : String(error);
 }
 function resolveCachePruneScope(args) {
@@ -3599,7 +3851,7 @@ function collectAssignmentOptionValues(args, optionName) {
     }
     return assignments;
 }
-function readSingleOptionValue(args, optionName) {
+export function readSingleOptionValue(args, optionName) {
     const index = args.indexOf(optionName);
     if (index === -1) {
         return null;
@@ -3610,7 +3862,7 @@ function readSingleOptionValue(args, optionName) {
     }
     return value;
 }
-function findUnsupportedOptionsError(args, options) {
+export function findUnsupportedOptionsError(args, options) {
     const supportedOptions = new Set([
         ...(options.optionsWithValues ?? []),
         ...(options.booleanOptions ?? []),
@@ -3672,7 +3924,7 @@ function buildGuidanceSnapshot(result) {
         recommendedUnitIds: result.recommendedUnits.map((unit) => unit.id),
     };
 }
-async function recordSessionEvent(targetPath, input) {
+export async function recordSessionEvent(targetPath, input) {
     try {
         const { commandStartedAtMs, ...eventInput } = input;
         const startedAt = typeof commandStartedAtMs === "number" && Number.isFinite(commandStartedAtMs)
@@ -3747,7 +3999,7 @@ function extractGuidanceResolvePositionalArgs(args) {
 function extractRecipePositionalArgs(args) {
     return extractPositionalArgs(args, new Set(["--provider", "--param", "--feature", "--no-feature", "--env"]));
 }
-function extractPositionalArgs(args, optionsWithValues) {
+export function extractPositionalArgs(args, optionsWithValues) {
     const positionalArgs = [];
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];