@skillcap/gdh 0.23.0 → 0.25.0

package/node_modules/@gdh/adapters/package.json

@@ -11,13 +11,13 @@
     }
   },
   "dependencies": {
-    "@gdh/authoring": "0.23.0",
-    "@gdh/core": "0.23.0",
-    "@gdh/docs": "0.23.0",
-    "@gdh/observability": "0.23.0",
-    "@gdh/runtime": "0.23.0",
-    "@gdh/scan": "0.23.0",
-    "@gdh/verify": "0.23.0"
+    "@gdh/authoring": "0.25.0",
+    "@gdh/core": "0.25.0",
+    "@gdh/docs": "0.25.0",
+    "@gdh/observability": "0.25.0",
+    "@gdh/runtime": "0.25.0",
+    "@gdh/scan": "0.25.0",
+    "@gdh/verify": "0.25.0"
   },
-  "version": "0.23.0"
+  "version": "0.25.0"
 }

package/node_modules/@gdh/authoring/package.json

@@ -14,7 +14,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@gdh/core": "0.23.0"
+    "@gdh/core": "0.25.0"
   },
-  "version": "0.23.0"
+  "version": "0.25.0"
 }

package/node_modules/@gdh/cli/dist/index.d.ts

@@ -1,4 +1,12 @@
 import { recordAuthoringSessionEvent } from "@gdh/observability";
+/**
+ * Re-export of `runSelfUpdateCommand` so the integration test in
+ * `packages/cli/src/self-update.integration.test.ts` (Plan 73-06) can drive
+ * the dispatcher directly without depending on the self-update module's
+ * surface evolving. The implementation lives in `./self-update.js`; this
+ * is a thin pass-through that preserves identical signature and behavior.
+ */
+export declare function runSelfUpdateCommand(args: readonly string[], io: CliIo): Promise<number>;
 export declare const cliPackage: import("@gdh/core").GdhPackageBoundary;
 export interface CliIo {
     readonly stdout: Pick<NodeJS.WriteStream, "write">;
@@ -8,6 +16,7 @@ export declare function runCli(args: readonly string[], io?: CliIo): Promise<num
 export declare function writeJsonResult(io: CliIo, value: unknown, options?: {
     readonly presentRuntimeTerms?: boolean;
 }): void;
+export declare function runMigrationCommand(args: readonly string[], io: CliIo): Promise<number>;
 export declare function formatCliError(error: unknown): string;
 export declare function readSingleOptionValue(args: readonly string[], optionName: string): string | null;
 export declare function findUnsupportedOptionsError(args: readonly string[], options: {

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAwFA,OAAO,EAIL,2BAA2B,EAC5B,MAAM,oBAAoB,CAAC;AA8C5B,eAAO,MAAM,UAAU,wCAerB,CAAC;AAEH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACpD;AAED,wBAAsB,MAAM,CAC1B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,GAAE,KAA0D,GAC7D,OAAO,CAAC,MAAM,CAAC,CAgIjB;AA+CD,wBAAgB,eAAe,CAC7B,EAAE,EAAE,KAAK,EACT,KAAK,EAAE,OAAO,EACd,OAAO,GAAE;IAAE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAAO,GACvD,IAAI,CAGN;AAmyJD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAErD;AAyDD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAchG;AAED,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IACP,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C,GACA,MAAM,GAAG,IAAI,CAYf;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IACP,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC,GACA;IACD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CA2CA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IACP,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,2BAA2B,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC5D,GACA;IACD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAeA;AAuBD,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,UAAU,CAAC,OAAO,2BAA2B,CAAC,CAAC,CAAC,CAAC,GAAG;IACzD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC,GACA,OAAO,CAAC,IAAI,CAAC,CAoBf;AAiED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,GACrC,SAAS,MAAM,EAAE,CAuBnB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqFA,OAAO,EAIL,2BAA2B,EAC5B,MAAM,oBAAoB,CAAC;AA0C5B;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,GACR,OAAO,CAAC,MAAM,CAAC,CAEjB;AAWD,eAAO,MAAM,UAAU,wCAerB,CAAC;AAEH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACpD;AAED,wBAAsB,MAAM,CAC1B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,GAAE,KAA0D,GAC7D,OAAO,CAAC,MAAM,CAAC,CAoIjB;AA+CD,wBAAgB,eAAe,CAC7B,EAAE,EAAE,KAAK,EACT,KAAK,EAAE,OAAO,EACd,OAAO,GAAE;IAAE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAAO,GACvD,IAAI,CAGN;AA2oED,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,GACR,OAAO,CAAC,MAAM,CAAC,CAoCjB;AAi5FD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAErD;AAyDD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAchG;AAED,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IACP,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C,GACA,MAAM,GAAG,IAAI,CAYf;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IACP,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC,GACA;IACD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CA2CA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IACP,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,2BAA2B,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC5D,GACA;IACD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAeA;AAuBD,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,UAAU,CAAC,OAAO,2BAA2B,CAAC,CAAC,CAAC,CAAC,GAAG;IACzD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC,GACA,OAAO,CAAC,IAAI,CAAC,CAoBf;AAiED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,GACrC,SAAS,MAAM,EAAE,CAuBnB"}

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

@@ -4,7 +4,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { buildGdhStatusResult, CLAUDE_CHECK_SKILL_RELATIVE_PATH, CLAUDE_CHECK_UPDATE_HOOK_RELATIVE_PATH, CLAUDE_MIGRATE_SKILL_RELATIVE_PATH, CLAUDE_ONBOARD_SKILL_RELATIVE_PATH, CLAUDE_PREPARE_SKILL_RELATIVE_PATH, CLAUDE_SCAN_SKILL_RELATIVE_PATH, CLAUDE_STATUS_SKILL_RELATIVE_PATH, CODEX_CHECK_SKILL_RELATIVE_PATH, CODEX_MIGRATE_SKILL_RELATIVE_PATH, CODEX_ONBOARD_SKILL_RELATIVE_PATH, CODEX_PREPARE_SKILL_RELATIVE_PATH, CODEX_SCAN_SKILL_RELATIVE_PATH, CODEX_STATUS_SKILL_RELATIVE_PATH, CURSOR_CHECK_SKILL_RELATIVE_PATH, CURSOR_MIGRATE_SKILL_RELATIVE_PATH, CURSOR_ONBOARD_SKILL_RELATIVE_PATH, CURSOR_PREPARE_SKILL_RELATIVE_PATH, CURSOR_SCAN_SKILL_RELATIVE_PATH, CURSOR_STATUS_SKILL_RELATIVE_PATH, createGsdSnapshot, getSupportedAgentAdaptersStatus, installSupportedAgentAdapters, } from "@gdh/adapters";
+import { buildGdhStatusResult, CLAUDE_CHECK_UPDATE_HOOK_RELATIVE_PATH, CLAUDE_MIGRATE_SKILL_RELATIVE_PATH, CLAUDE_ONBOARD_SKILL_RELATIVE_PATH, CLAUDE_PREPARE_SKILL_RELATIVE_PATH, CLAUDE_SCAN_SKILL_RELATIVE_PATH, CLAUDE_STATUS_SKILL_RELATIVE_PATH, CODEX_MIGRATE_SKILL_RELATIVE_PATH, CODEX_ONBOARD_SKILL_RELATIVE_PATH, CODEX_PREPARE_SKILL_RELATIVE_PATH, CODEX_SCAN_SKILL_RELATIVE_PATH, CODEX_STATUS_SKILL_RELATIVE_PATH, CURSOR_MIGRATE_SKILL_RELATIVE_PATH, CURSOR_ONBOARD_SKILL_RELATIVE_PATH, CURSOR_PREPARE_SKILL_RELATIVE_PATH, CURSOR_SCAN_SKILL_RELATIVE_PATH, CURSOR_STATUS_SKILL_RELATIVE_PATH, createGsdSnapshot, getSupportedAgentAdaptersStatus, installSupportedAgentAdapters, } from "@gdh/adapters";
 import { checkManagedLsp, doctorAuthoringDiagnostics, doctorManagedLsp, getAuthoringDiagnosticsStatus, getCurrentAuthoringDiagnostics, getManagedLspStatus, hasCompleteOnboardingSurface, inspectCacheState, pruneCacheState, pruneAuthoringDiagnostics, pruneManagedLsp, readProjectConfig, readWorktreeState, refreshAuthoringDiagnostics, resolveAuthoringStatus, resolveEffectiveTargetPath, resolvePinnedVersion, resolveProjectRoot, resolveTargetGodotDocsVersion, restartManagedLsp, runAuthoringCheck, runImportRefresh, runTargetPrepare, runWarmup, stopManagedLsp, } 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";
@@ -13,11 +13,21 @@ import { inspectAuthoringEffectiveness, inspectAuthoringSessions, inspectGuidanc
 import { checkRuntimeRecipe, createRuntimeBridgeManager, serveRuntimeBridgeBroker, inspectRuntimeBridgeSurface, installRuntimeBridgeSurface, listRuntimeRecipes, removeRuntimeBridgeSurface, repairRuntimeBridgeSurface, runRuntimeRecipe, showRuntimeRecipe, } from "@gdh/runtime";
 import { applyRepairableOnboardingWrites, onboardGodotProject, persistInventoryForTarget, readInventoryCacheOrScan, scanGodotProjectInventory, } from "@gdh/scan";
 import { exerciseRuntimeCorpusEntry, inspectRuntimeCorpusStatus, inspectRuntimeVerificationBundleState, inspectRuntimeVerificationReadiness, listRuntimeScenarios, materializeRuntimeCorpusEntry, recordRuntimeCorpusValidation, runRuntimeVerificationScenario, showRuntimeScenario, } from "@gdh/verify";
-import { migrateProjectLifecycleSurface } from "./migrate.js";
+import { clearEnvelope, clearMigrationBackups, migrateProjectLifecycleSurface, recordEnvelopeResult, } from "./migrate.js";
 import { runBridgeSessionCommand } from "./bridge-session.js";
 import { cleanupGdhMcpProcesses } from "./mcp-cleanup.js";
 import { presentPublicRuntimeTerms } from "./public-terms.js";
-import { runSelfUpdateCommand } from "./self-update.js";
+import { runSelfUpdateCommand as runSelfUpdateCommandImpl } from "./self-update.js";
+/**
+ * Re-export of `runSelfUpdateCommand` so the integration test in
+ * `packages/cli/src/self-update.integration.test.ts` (Plan 73-06) can drive
+ * the dispatcher directly without depending on the self-update module's
+ * surface evolving. The implementation lives in `./self-update.js`; this
+ * is a thin pass-through that preserves identical signature and behavior.
+ */
+export async function runSelfUpdateCommand(args, io) {
+    return runSelfUpdateCommandImpl(args, io);
+}
 import { executeSetupCommand, isSetupCanceledError, renderDurableTruthCollisionHint, renderSetupIntro, renderSetupOutro, renderSetupSummary, } from "./setup.js";
 import { emitUpdateBannerIfStale } from "./update-banner.js";
 export const cliPackage = definePackageBoundary({
@@ -124,6 +134,9 @@ export async function runCli(args, io = { stdout: process.stdout, stderr: proces
     if (command === "migrate") {
         return runMigrateCommand(rest, io);
     }
+    if (command === "migration") {
+        return runMigrationCommand(rest, io);
+    }
     if (command === "self-update") {
         return runSelfUpdateCommand(rest, io);
     }
@@ -1966,6 +1979,235 @@ async function runMigrateCommand(args, io) {
         return 1;
     }
 }
+export async function runMigrationCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh migration <command>",
+            "",
+            "Commands:",
+            "  clear-backups [target]                                  Remove .gdh-state/backup/ when all deferred-action probes are clean (idempotent).",
+            "  record-envelope-result <slug> --result-file <path>      Record a Phase 73 envelope output_contract from a JSON file.",
+            "  record-envelope-result <slug> --result <inline-json>    Record a Phase 73 envelope output_contract inline (JSON string).",
+            "  clear-envelope <slug> [target]                          Drop the recorded envelopes slot for <slug> from migration.json (testing/debug).",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "clear-backups") {
+        return runMigrationClearBackupsCommand(rest, io);
+    }
+    if (subcommand === "record-envelope-result") {
+        return runMigrationRecordEnvelopeResultCommand(rest, io);
+    }
+    if (subcommand === "clear-envelope") {
+        return runMigrationClearEnvelopeCommand(rest, io);
+    }
+    io.stderr.write([
+        `Unknown migration command: ${subcommand}`,
+        "",
+        "Run `gdh migration --help` for the list of supported subcommands.",
+    ].join("\n") + "\n");
+    return 1;
+}
+async function runMigrationClearBackupsCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh migration clear-backups [target]",
+            "",
+            "Remove .gdh-state/backup/ when all deferred-action probes are clean.",
+            "Exits 0 on cleared and noop, 1 on blocked_by_pending_probes.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh migration clear-backups [target]\n",
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh migration clear-backups [target]\n",
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
+        return 1;
+    }
+    try {
+        const result = await clearMigrationBackups({ targetPath });
+        writeJsonResult(io, result);
+        return result.state === "blocked_by_pending_probes" ? 1 : 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to clear migration backups for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+// ---------------------------------------------------------------------------
+// Phase 73 — gdh migration record-envelope-result (D-07 / D-13)
+// ---------------------------------------------------------------------------
+const RECORD_ENVELOPE_RESULT_USAGE = "Usage: gdh migration record-envelope-result <slug> [--result-file <path> | --result <json>] [--target <path>]\n";
+/**
+ * Subcommand `"record-envelope-result"` for `gdh migration` (Phase 73 D-07).
+ * Mutually-exclusive `--result-file` / `--result` gate; resolves `--target`
+ * via {@link parseSingleTargetPathArg} after stripping the slug positional;
+ * delegates validation and atomic write to {@link recordEnvelopeResult} in
+ * `./migrate.js`. Exit 0 on `recorded`, exit 1 on `blocked`.
+ */
+async function runMigrationRecordEnvelopeResultCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh migration record-envelope-result <slug> --result-file <path> [--target <path>]",
+            "Usage: gdh migration record-envelope-result <slug> --result <inline-json> [--target <path>]",
+            "",
+            "Record a Phase 73 envelope output_contract block. Validates against the",
+            "GdhMigrationEnvelopeOutput typed union (apply / abort / needs_clarification);",
+            "appends to migration.json.envelopes[<slug>] and migration.json.envelopes[<slug>].attempts[].",
+            'Does NOT advance the chain — re-run `gdh self-update` after recording.',
+            "",
+            'Exits 0 on { state: "recorded" }, 1 on { state: "blocked" }.',
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: RECORD_ENVELOPE_RESULT_USAGE,
+        optionsWithValues: ["--result-file", "--result", "--target"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    // Walk argv and skip the value following each value-bearing flag so it is
+    // not misinterpreted as a positional. Boolean flags would belong here too
+    // if any were supported (none currently).
+    const resolvedPositionals = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i] ?? "";
+        if (arg === "--result" || arg === "--result-file" || arg === "--target") {
+            i++; // skip value
+            continue;
+        }
+        if (arg.startsWith("--"))
+            continue;
+        resolvedPositionals.push(arg);
+    }
+    if (resolvedPositionals.length === 0) {
+        io.stderr.write("Usage error: gdh migration record-envelope-result requires a <slug> positional argument.\n");
+        return 1;
+    }
+    if (resolvedPositionals.length > 1) {
+        io.stderr.write(`Usage error: gdh migration record-envelope-result accepts a single <slug>; received ${resolvedPositionals.length}.\n`);
+        return 1;
+    }
+    const slug = resolvedPositionals[0];
+    const resultFile = readSingleOptionValue(args, "--result-file");
+    const resultInline = readSingleOptionValue(args, "--result");
+    // Mutually exclusive: exactly one of the two MUST be present.
+    if ((resultFile === null) === (resultInline === null)) {
+        io.stderr.write("Usage error: provide exactly one of --result-file <path> or --result <inline-json>.\n");
+        return 1;
+    }
+    // Use the canonical helper so --target resolution is symmetric with
+    // runStatusCommand and the other migration dispatchers (no ad-hoc
+    // path.resolve(targetExplicit) here). Strip the slug positional + the
+    // value-bearing flags' values before delegating so the helper sees only
+    // [--target <path>] (or nothing).
+    const argsForTargetParse = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i] ?? "";
+        if (arg === "--target") {
+            argsForTargetParse.push(arg);
+            const next = args[i + 1];
+            if (next !== undefined)
+                argsForTargetParse.push(next);
+            i++;
+            continue;
+        }
+        if (arg === "--result" || arg === "--result-file") {
+            i++; // skip value
+            continue;
+        }
+        if (arg === slug)
+            continue; // strip the consumed positional
+        if (arg.startsWith("--"))
+            continue; // strip help and other flags
+        // Any leftover positional would have been caught above.
+    }
+    const { targetPath, error: targetError } = parseSingleTargetPathArg(argsForTargetParse, {
+        usage: RECORD_ENVELOPE_RESULT_USAGE,
+        allowTargetOption: true,
+    });
+    if (targetError !== null) {
+        io.stderr.write(targetError);
+        return 1;
+    }
+    try {
+        const result = await recordEnvelopeResult({
+            targetPath,
+            envelopeRef: slug,
+            resultSource: resultFile !== null
+                ? { kind: "file", absolutePath: path.resolve(resultFile) }
+                : { kind: "inline", json: resultInline },
+        });
+        writeJsonResult(io, result);
+        return result.state === "blocked" ? 1 : 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to record envelope result for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+// ---------------------------------------------------------------------------
+// Phase 73 — gdh migration clear-envelope (testing/debug)
+// ---------------------------------------------------------------------------
+/**
+ * Subcommand `"clear-envelope"` for `gdh migration` (testing/debug companion).
+ * Removes the per-slug slot from `migration.json.envelopes`; idempotent noop
+ * on missing slot or missing migration state. Does NOT touch
+ * `pending_envelope_resume` (mirrors D-13 isolation in
+ * {@link recordEnvelopeResult}). Exit 0 always.
+ */
+async function runMigrationClearEnvelopeCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh migration clear-envelope <slug> [target]",
+            "",
+            "Remove the recorded envelopes slot for <slug> from migration.json.",
+            "Does NOT touch pending_envelope_resume. Idempotent.",
+            "",
+            "Exits 0 on cleared and noop.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh migration clear-envelope <slug> [target]\n",
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positional = args.filter((a) => !a.startsWith("--"));
+    if (positional.length === 0) {
+        io.stderr.write("Usage error: gdh migration clear-envelope requires a <slug> positional argument.\n");
+        return 1;
+    }
+    if (positional.length > 2) {
+        io.stderr.write("Usage error: gdh migration clear-envelope accepts at most <slug> and an optional [target].\n");
+        return 1;
+    }
+    const slug = positional[0];
+    const targetCandidate = positional[1] ?? null;
+    const targetPath = targetCandidate !== null ? path.resolve(targetCandidate) : process.cwd();
+    try {
+        const result = await clearEnvelope({ targetPath, envelopeRef: slug });
+        writeJsonResult(io, result);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to clear envelope "${slug}" for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
 async function runBridgeStatusCommand(args, io) {
     if (args.includes("--help")) {
         io.stdout.write([
@@ -2989,21 +3231,22 @@ const VERIFY_DRIFT_SCANNED_FILES = [
     { 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_SCAN_SKILL_RELATIVE_PATH, description: "Codex gdh-scan 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_SCAN_SKILL_RELATIVE_PATH, description: "Cursor gdh-scan skill" },
     { relativePath: CLAUDE_ONBOARD_SKILL_RELATIVE_PATH, description: "Claude gdh-onboard skill" },
     { relativePath: CLAUDE_STATUS_SKILL_RELATIVE_PATH, description: "Claude gdh-status skill" },
     { relativePath: CLAUDE_MIGRATE_SKILL_RELATIVE_PATH, description: "Claude gdh-migrate skill" },
-    { relativePath: CLAUDE_CHECK_SKILL_RELATIVE_PATH, description: "Claude gdh-check skill" },
     { relativePath: CLAUDE_PREPARE_SKILL_RELATIVE_PATH, description: "Claude gdh-prepare skill" },
     { relativePath: CLAUDE_SCAN_SKILL_RELATIVE_PATH, description: "Claude gdh-scan skill" },
+    // Intentionally excluded: generated gdh-check skills for Claude, Codex, and Cursor.
+    // v0.25 retires the validation skill surface; validation evidence belongs to hooks,
+    // MCP/CLI status, and explicit authoring-check commands. Scanning the retired paths
+    // reports a false missing-file drift after a correct migration removes them.
     // 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.
     //