@skillcap/gdh 0.23.0 → 0.25.0

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

@@ -1,4 +1,4 @@
-import type { GdhLifecycleTerminalResult, GdhManagedProjectSurfaceId, GdhProjectLifecycleCompatibilityResult } from "@gdh/core";
+import type { GdhLifecycleTerminalResult, GdhManagedProjectSurfaceId, GdhProjectLifecycleCompatibilityResult, GdhHostHarnessIntrospect, GdhProcessRestartProbe, GdhMigrationEnvelopeOutput } from "@gdh/core";
 export declare const GDH_PROJECT_SURFACE_MIGRATION_ID = "project_surface_lifecycle_v1";
 type MigrationActionKind = "rewrite_file" | "rename_directory" | "delete_file" | "validate_surface" | "run_command" | "manual_review";
 type MigrationActionState = "planned" | "applied" | "unchanged" | "blocked";
@@ -62,5 +62,156 @@ export declare function deriveLifecycleTerminalResult(input: {
     readonly state: MigrationRunState;
 }): GdhLifecycleTerminalResult;
 export declare function rewriteProjectConfig(content: string): string;
+/**
+ * Discriminated result of {@link clearMigrationBackups} (D-17 / STA-04).
+ *
+ * - `cleared`: every probe was clean, the staging dir was absent, and
+ *   `.gdh-state/backup/` was removed from disk. Idempotent retry returns `noop`.
+ * - `noop`: nothing to do — either no migration state and no backup
+ *   (`no_migration_state`), or a migration state exists but no backup is
+ *   present (`no_backup_present`). Both safe to ignore.
+ * - `blocked_by_pending_probes`: cleanup refused. Either at least one probed
+ *   deferred action returned `pending` or `stale` (`deferred_actions_pending`,
+ *   `pending` carries the action ids), or `.gdh-state/backup.new/` exists
+ *   indicating an interrupted migration (`migration_in_progress`, `pending`
+ *   is empty).
+ */
+export type GdhClearBackupsResult = {
+    readonly state: "cleared";
+    readonly cleared_backup_path: string;
+} | {
+    readonly state: "noop";
+    readonly reason: "no_backup_present" | "no_migration_state";
+} | {
+    readonly state: "blocked_by_pending_probes";
+    readonly pending: readonly string[];
+    readonly reason: "deferred_actions_pending" | "migration_in_progress";
+};
+export interface GdhClearMigrationBackupsInput {
+    readonly targetPath: string;
+    readonly adapters?: {
+        readonly hostHarnessIntrospect?: GdhHostHarnessIntrospect;
+        readonly processProbe?: GdhProcessRestartProbe;
+    };
+}
+/**
+ * Idempotent backup-cleanup command (D-17 / STA-04).
+ *
+ * Three-gate truth table:
+ *   1. Refuse if `.gdh-state/backup.new/` exists (interrupted migration:
+ *      `migration_in_progress`).
+ *   2. Noop if neither backup nor migration state exist (`no_migration_state`),
+ *      or if no backup but migration state exists (`no_backup_present`).
+ *   3. For each deferred action, run the probe; if any probe is not `clean`,
+ *      refuse with `deferred_actions_pending` and the pending action ids.
+ *   4. Otherwise remove `.gdh-state/backup/` recursively and return `cleared`.
+ *
+ * The migration.json file is NOT modified. Deferred actions are independent of
+ * the backup directory; they may have been satisfied previously.
+ *
+ * Threat mitigations:
+ * - T-72-05-03 (TOCTOU): re-reads migration.json AND backup state freshly per
+ *   call; no cached probe results consumed across calls. Same handler used by
+ *   the advisory gate in `buildGdhStatusResult` (Plan 05 Task 03).
+ * - T-72-05-05 (silent deletion under pending probes): probe-gate is mandatory
+ *   and `state: "blocked_by_pending_probes"` is exit code 1 with structured
+ *   `pending` ids; idempotent retry is safe.
+ * - T-72-05-07 (clear during interrupted migration): staging-dir check at
+ *   step 1 returns `migration_in_progress` and refuses cleanup.
+ *
+ * Defaults: `adapters.hostHarnessIntrospect = null` and `adapters.processProbe
+ * = null` so probes degrade to `pending` when the host cannot evaluate the
+ * deferred conditions; cleanup then refuses safely instead of spuriously
+ * clearing.
+ */
+export declare function clearMigrationBackups(input: GdhClearMigrationBackupsInput): Promise<GdhClearBackupsResult>;
+/**
+ * Discriminated result of {@link recordEnvelopeResult}.
+ *
+ * - `recorded`: payload validated, marker triple matched, slot written
+ *   atomically. `pending_envelope_resume` is preserved by D-13 — the calling
+ *   agent re-runs `gdh self-update` to advance the chain past the envelope.
+ * - `blocked`: validation gate failed. Each `reason` corresponds to a typed
+ *   failure mode the dispatcher surfaces with exit code 1 (Pitfall 4 — never
+ *   let JSON.parse / readFile / schema-mismatch escape as raw exceptions).
+ *
+ * The seven blocked reasons enumerated cover every gate executed by
+ * `recordEnvelopeResult`. `input_required` is reserved for the dispatcher's
+ * usage-error surface (mutually-exclusive --result / --result-file gate).
+ */
+export type GdhRecordEnvelopeResultResult = {
+    readonly state: "recorded";
+    readonly envelope_ref: string;
+    readonly recorded_at: string;
+    readonly from_pin: string;
+    readonly to_pin: string;
+    readonly output_contract_state: GdhMigrationEnvelopeOutput["state"];
+} | {
+    readonly state: "blocked";
+    readonly reason: "envelope_not_found" | "no_pending_chain" | "envelope_ref_mismatch" | "parse_failed" | "schema_violation" | "result_file_unreadable" | "input_required";
+    readonly details: string;
+};
+export interface GdhRecordEnvelopeResultInput {
+    readonly targetPath: string;
+    readonly envelopeRef: string;
+    readonly resultSource: {
+        readonly kind: "inline";
+        readonly json: string;
+    } | {
+        readonly kind: "file";
+        readonly absolutePath: string;
+    };
+    /** Deterministic clock injection for tests. */
+    readonly nowIso?: () => string;
+}
+/**
+ * Record an envelope output_contract block to `.gdh-state/migration.json` per
+ * D-07 / D-08 / D-13.
+ *
+ * Gate sequence (fail-closed, no exception propagates to caller):
+ *   1. Slug shape (path-traversal defense via {@link isEnvelopeSlug}).
+ *   2. Read --result-file (or use --result inline).
+ *   3. JSON.parse (Pitfall 4 — caught and surfaced as `parse_failed`).
+ *   4. Schema validation against {@link isEnvelopeOutput} typed union.
+ *   5. Read migration.json; require `pending_envelope_resume` marker
+ *      (D-09 / D-11 / D-13 — chain must be paused before record).
+ *   6. Triple match: marker.envelope_ref === input.envelopeRef.
+ *   7. Append prior slot to `attempts[]` (Pitfall 2 — outer fields become a
+ *      new attempt; existing attempts[] history accumulates).
+ *   8. Atomic write through {@link writeMigrationState}; D-13 preserves
+ *      `pending_envelope_resume` (record does NOT clear it).
+ *
+ * The function NEVER calls `bumpAndRebakePin` and NEVER advances the chain
+ * (D-13 lock). The agent re-runs `gdh self-update` to resume.
+ */
+export declare function recordEnvelopeResult(input: GdhRecordEnvelopeResultInput): Promise<GdhRecordEnvelopeResultResult>;
+/**
+ * Discriminated result of {@link clearEnvelope}.
+ *
+ * - `cleared`: the per-slug slot was removed from `migration.json.envelopes`.
+ *   `pending_envelope_resume` is NOT touched (mirrors D-13 isolation).
+ * - `noop` with `slot_not_present`: state exists but no slot for this slug.
+ * - `noop` with `no_migration_state`: no migration.json on disk.
+ *
+ * Idempotent — re-running on a missing slot returns `noop`, not `blocked`.
+ */
+export type GdhClearEnvelopeResult = {
+    readonly state: "cleared";
+    readonly envelope_ref: string;
+} | {
+    readonly state: "noop";
+    readonly reason: "slot_not_present" | "no_migration_state";
+};
+export interface GdhClearEnvelopeInput {
+    readonly targetPath: string;
+    readonly envelopeRef: string;
+}
+/**
+ * Remove the per-slug slot from `migration.json.envelopes`. Testing/debug
+ * companion to {@link recordEnvelopeResult}; does NOT touch
+ * `pending_envelope_resume` (deliberate isolation — clearing the slot does
+ * not unpause a chain).
+ */
+export declare function clearEnvelope(input: GdhClearEnvelopeInput): Promise<GdhClearEnvelopeResult>;
 export {};
 //# sourceMappingURL=migrate.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,0BAA0B,EAC1B,0BAA0B,EAG1B,sCAAsC,EAEvC,MAAM,WAAW,CAAC;AAOnB,eAAO,MAAM,gCAAgC,iCAAiC,CAAC;AAE/E,KAAK,mBAAmB,GACpB,cAAc,GACd,kBAAkB,GAClB,aAAa,GACb,kBAAkB,GAClB,aAAa,GACb,eAAe,CAAC;AACpB,KAAK,oBAAoB,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;AAC5E,KAAK,iBAAiB,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEpE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,0BAA0B,GAAG,IAAI,CAAC;IACpD,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,kBAAkB,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IAC5D,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,CAAC;AACrD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,wBAAwB,EAAE,eAAe,CAAC;IACnD,QAAQ,CAAC,yBAAyB,EAAE,sBAAsB,CAAC;IAC3D,QAAQ,CAAC,cAAc,EAAE,YAAY,CAAC;IACtC,QAAQ,CAAC,qBAAqB,EAAE,KAAK,CAAC;IACtC,QAAQ,CAAC,oBAAoB,EAAE,KAAK,CAAC;IACrC,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAMD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,OAAO,gCAAgC,CAAC;IAC9D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,aAAa,EAAE,sCAAsC,CAAC;IAC/D,QAAQ,CAAC,UAAU,EAAE,sCAAsC,GAAG,IAAI,CAAC;IACnE,QAAQ,CAAC,gBAAgB,EAAE,mCAAmC,CAAC;IAC/D,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAChD,QAAQ,CAAC,YAAY,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAC1D,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,CAAC;CAC/C;AAkED,wBAAsB,8BAA8B,CAAC,KAAK,EAAE;IAC1D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAgL9B;AA6SD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,sCAAsC,CAAC;IAC/D,QAAQ,CAAC,UAAU,EAAE,sCAAsC,GAAG,IAAI,CAAC;IACnE,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC,GAAG,0BAA0B,CAgE7B;AAglBD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAwB5D"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"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"}

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

@@ -2,8 +2,9 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import * as gdhCore from "@gdh/core";
 import { readProjectConfig, resolveProjectRoot } from "@gdh/authoring";
-import { inspectProjectLifecycleCompatibility, installSupportedAgentAdapters, } from "@gdh/adapters";
+import { BACKUP_RELATIVE_PATH, BACKUP_STAGING_RELATIVE_PATH, inspectProjectLifecycleCompatibility, installSupportedAgentAdapters, readBackupManifest, } from "@gdh/adapters";
 import { planAgentContractWrite, planGuidanceArtifactWrites, planRulesArtifactWrite } from "@gdh/docs";
+import { isEnvelopeOutput, isEnvelopeSlug, readMigrationState, runDeferredActionProbe, writeMigrationState, } from "@gdh/core";
 import { inspectRuntimeBridgeSurface, repairRuntimeBridgeSurface, } from "@gdh/runtime";
 import { applyRepairableOnboardingWrites } from "@gdh/scan";
 export const GDH_PROJECT_SURFACE_MIGRATION_ID = "project_surface_lifecycle_v1";
@@ -117,11 +118,19 @@ export async function migrateProjectLifecycleSurface(input) {
         if (launcherAction !== null) {
             actions.push(launcherAction);
         }
-        const runtimeTerminology = await migrateRuntimeTerminologySurface({
-            targetPath,
-            dryRun: input.dryRun,
-        });
-        actions.push(...translateRuntimeTerminologyActions(runtimeTerminology.actions));
+        // Phase 72 Plan 02: the schema/contract orchestration that
+        // migrateRuntimeTerminologySurface drove (recipes→run-configurations
+        // rename, scenarios→verification-scenarios rename, project.yaml
+        // schema-2→schema-3 rewrite, legacy project_entries.gd copy) is dead
+        // code in the v0.18+ supported range. Per the audit at
+        // .planning/phases/72-migration-workflow-internals-registry-inventory-durable-back/72-02-AUDIT.md,
+        // the only real class-2/3 migration in the supported range is the
+        // s2c2→s2c3 rules-schema bump, now owned by the registry entry
+        // entry_s2c2_to_s2c3_rules_schema in @gdh/core. Plan 03's inventory
+        // sweep deletes the unreachable sub-functions and their pre-v0.18
+        // regression tests atomically. WFL-03 (D-20/D-21) makes pre-v0.18
+        // pins unreachable for self-update consumers; the schema/contract
+        // rewrite paths are no longer driven by any post-v0.18 invocation.
         let projectConfig = await readProjectConfig(targetPath);
         if (projectConfig !== null) {
             const repairableWrites = await planRepairableProjectSurfaceWrites(targetPath, projectConfig, compatibility);
@@ -131,6 +140,11 @@ export async function migrateProjectLifecycleSurface(input) {
                     allowDurableTruthOverwrites: true,
                 });
             }
+            actions.push(...(await migrateLegacyDocsAgentGuidance({
+                targetPath,
+                projectConfig,
+                dryRun: input.dryRun,
+            })));
             if (shouldRepairAdapterSurfaces()) {
                 const adaptersResult = await installSupportedAgentAdapters(targetPath, {
                     dryRun: input.dryRun,
@@ -240,6 +254,64 @@ function shouldRepairAdapterSurfaces() {
     // surfaces gracefully and ensures new skills are installed on upgrade.
     return true;
 }
+const LEGACY_GUIDANCE_RELATIVE_PATHS = [
+    "docs/agent/README.md",
+    "docs/agent/00-gdh-onboarding.md",
+    "docs/agent/gdh-glossary.md",
+    "docs/agent/authoring-and-validation.md",
+    "docs/agent/project-migration.md",
+    "docs/agent/project-surfaces.md",
+    "docs/agent/persistence-semantics.md",
+];
+async function migrateLegacyDocsAgentGuidance(input) {
+    const legacyGuidanceRoot = input.projectConfig.primaryGodotProjectPath === "."
+        ? input.targetPath
+        : path.resolve(input.targetPath, input.projectConfig.primaryGodotProjectPath);
+    const actions = [];
+    for (const legacyRelativePath of LEGACY_GUIDANCE_RELATIVE_PATHS) {
+        const absolutePath = path.join(legacyGuidanceRoot, legacyRelativePath);
+        const content = await fs.readFile(absolutePath, "utf8").catch(() => null);
+        if (content === null || !isGdhManagedLegacyGuidance(legacyRelativePath, content)) {
+            continue;
+        }
+        if (!input.dryRun) {
+            await fs.rm(absolutePath, { force: true });
+        }
+        const workspaceRelativePath = path.relative(input.targetPath, absolutePath).split(path.sep).join("/");
+        actions.push({
+            id: `delete-legacy-guidance-${workspaceRelativePath}`,
+            surface: legacyRelativePath === "docs/agent/README.md" ? "guidance_index" : "guidance_unit",
+            kind: "delete_file",
+            state: input.dryRun ? "planned" : "applied",
+            relativePath: workspaceRelativePath,
+            summary: "Remove legacy GDH-managed docs/agent guidance after writing the canonical .gdh/guidance surface.",
+            command: null,
+            validationCommands: [],
+            manualSteps: [],
+        });
+    }
+    if (!input.dryRun && actions.length > 0) {
+        await removeEmptyLegacyGuidanceDirectories(legacyGuidanceRoot);
+    }
+    return actions;
+}
+function isGdhManagedLegacyGuidance(relativePath, content) {
+    if (relativePath === "docs/agent/README.md") {
+        return content.includes("<!-- GDH GUIDANCE INDEX VERSION:");
+    }
+    return (content.includes("id: ") &&
+        /^version:\s+\d+$/m.test(content) &&
+        content.includes("when:"));
+}
+async function removeEmptyLegacyGuidanceDirectories(legacyGuidanceRoot) {
+    for (const relativePath of ["docs/agent", "docs"]) {
+        const absolutePath = path.join(legacyGuidanceRoot, relativePath);
+        const entries = await fs.readdir(absolutePath).catch(() => null);
+        if (entries !== null && entries.length === 0) {
+            await fs.rmdir(absolutePath).catch(() => { });
+        }
+    }
+}
 function createBrokerTransitionMigrationSummary() {
     return {
         state: "supported",
@@ -512,10 +584,10 @@ function mapWriteSurface(relativePath) {
     if (relativePath === ".gdh/rules.yaml") {
         return "rules_schema";
     }
-    if (relativePath === "docs/agent/README.md") {
+    if (relativePath === ".gdh/guidance/README.md") {
         return "guidance_index";
     }
-    if (relativePath.startsWith("docs/agent/")) {
+    if (relativePath.startsWith(".gdh/guidance/")) {
         return "guidance_unit";
     }
     if (relativePath === ".cursor/rules/gdh-agent.mdc") {
@@ -594,6 +666,28 @@ async function migrateLegacyLauncher(input) {
         manualSteps: [],
     };
 }
+// TODO(72-Plan-03): unreachable from migrateProjectLifecycleSurface as of
+// Phase 72 Plan 02. Preconditions (.gdh/recipes/, .gdh/scenarios/, legacy
+// project_entries.gd) never match the v0.18+ supported range. Plan 03's
+// inventory sweep deletes this function and its descendants
+// (migrateLegacyProjectBridgeEntry,
+// rewriteRunConfiguration, rewriteVerificationScenario, rewriteVersionHeader,
+// extractPrimaryGodotProjectPath, ensureProjectAllowedProviders,
+// isDockerWideningEligibleRunConfiguration, ensureYamlStringListValues,
+// ensureRuntimeBridgeProjectEntryPath, ensureRuntimeKnowledgePath) plus the
+// pre-v0.18 regression test groups in migrate.test.ts atomically. See
+// .planning/phases/72-migration-workflow-internals-registry-inventory-durable-back/72-02-AUDIT.md
+// "Disposition Table" for the full deletion set.
+//
+// WR-09: `rewriteProjectConfig` is RETAINED — do NOT delete in the Plan-03
+// sweep even though it appears in the descendant chain above. It has a live
+// caller at `preHealMissingGdhVersionField` (this file) AND is exported and
+// imported directly by `migrate.test.ts`. The audit's deletion set was
+// computed from the dead-code reachability graph rooted in
+// `migrateRuntimeTerminologySurface`; the live preheal caller arrived later
+// (D-06 minimal pre-heal) and was not re-checked. See the "RETAINED" guard
+// comment immediately above `export function rewriteProjectConfig` for the
+// in-place marker.
 async function migrateRuntimeTerminologySurface(input) {
     const targetPath = path.resolve(input.targetPath);
     const configPath = path.join(targetPath, PROJECT_CONFIG_PATH);
@@ -908,6 +1002,18 @@ async function applyMinimalDryRunPreHeal(targetPath) {
         await fs.writeFile(configPath, originalContent, "utf8");
     };
 }
+// WR-09: RETAINED — do NOT delete in the Plan-03 dead-code sweep. Despite
+// appearing in the TODO(72-Plan-03) deletion set at line ~923 (which
+// references the dead-code chain rooted in migrateRuntimeTerminologySurface),
+// this function has TWO live consumers in the v0.18+ supported range:
+//   1. `preHealMissingGdhVersionField` at line ~1266 (D-06 auto-heal of
+//      missing `gdh_version:` field on unmigrated projects).
+//   2. Direct import in `packages/cli/src/migrate.test.ts` for the
+//      pre-v0.18 regression test groups (those groups themselves remain
+//      live regression coverage for the auto-heal branch).
+// The Plan-03 sweep MUST distinguish this function from the genuinely dead
+// helpers in the same chain. See the WR-09 note above the
+// migrateRuntimeTerminologySurface TODO block.
 export function rewriteProjectConfig(content) {
     let next = rewriteVersionHeader(content, 3);
     next = next.replace(/^default_recipe:/m, "default_run_configuration:");
@@ -1098,4 +1204,245 @@ async function directoryExists(directoryPath) {
         return false;
     }
 }
+/**
+ * Idempotent backup-cleanup command (D-17 / STA-04).
+ *
+ * Three-gate truth table:
+ *   1. Refuse if `.gdh-state/backup.new/` exists (interrupted migration:
+ *      `migration_in_progress`).
+ *   2. Noop if neither backup nor migration state exist (`no_migration_state`),
+ *      or if no backup but migration state exists (`no_backup_present`).
+ *   3. For each deferred action, run the probe; if any probe is not `clean`,
+ *      refuse with `deferred_actions_pending` and the pending action ids.
+ *   4. Otherwise remove `.gdh-state/backup/` recursively and return `cleared`.
+ *
+ * The migration.json file is NOT modified. Deferred actions are independent of
+ * the backup directory; they may have been satisfied previously.
+ *
+ * Threat mitigations:
+ * - T-72-05-03 (TOCTOU): re-reads migration.json AND backup state freshly per
+ *   call; no cached probe results consumed across calls. Same handler used by
+ *   the advisory gate in `buildGdhStatusResult` (Plan 05 Task 03).
+ * - T-72-05-05 (silent deletion under pending probes): probe-gate is mandatory
+ *   and `state: "blocked_by_pending_probes"` is exit code 1 with structured
+ *   `pending` ids; idempotent retry is safe.
+ * - T-72-05-07 (clear during interrupted migration): staging-dir check at
+ *   step 1 returns `migration_in_progress` and refuses cleanup.
+ *
+ * Defaults: `adapters.hostHarnessIntrospect = null` and `adapters.processProbe
+ * = null` so probes degrade to `pending` when the host cannot evaluate the
+ * deferred conditions; cleanup then refuses safely instead of spuriously
+ * clearing.
+ */
+export async function clearMigrationBackups(input) {
+    const backupAbs = path.join(input.targetPath, BACKUP_RELATIVE_PATH);
+    const stagingAbs = path.join(input.targetPath, BACKUP_STAGING_RELATIVE_PATH);
+    // Gate 1: refuse during in-progress migration (D-17, T-72-05-07)
+    const stagingExists = await fs
+        .stat(stagingAbs)
+        .then(() => true)
+        .catch(() => false);
+    if (stagingExists) {
+        return {
+            state: "blocked_by_pending_probes",
+            pending: [],
+            reason: "migration_in_progress",
+        };
+    }
+    const manifest = await readBackupManifest(input.targetPath);
+    const backupExists = manifest !== null;
+    const migrationState = await readMigrationState(input.targetPath);
+    // Gate 2: noop discriminator
+    if (!backupExists && migrationState === null) {
+        return { state: "noop", reason: "no_migration_state" };
+    }
+    if (!backupExists) {
+        return { state: "noop", reason: "no_backup_present" };
+    }
+    // Gate 3: probe-gate (T-72-05-05)
+    const pending = [];
+    for (const action of migrationState?.deferred_actions ?? []) {
+        const result = await runDeferredActionProbe(action, {
+            targetPath: input.targetPath,
+            hostHarnessIntrospect: input.adapters?.hostHarnessIntrospect ?? null,
+            processProbe: input.adapters?.processProbe ?? null,
+        });
+        if (result.status !== "clean") {
+            pending.push(action.id);
+        }
+    }
+    if (pending.length > 0) {
+        return {
+            state: "blocked_by_pending_probes",
+            pending,
+            reason: "deferred_actions_pending",
+        };
+    }
+    // Gate 4: clear (does NOT modify migration.json)
+    await fs.rm(backupAbs, { recursive: true, force: true });
+    return { state: "cleared", cleared_backup_path: backupAbs };
+}
+/**
+ * Record an envelope output_contract block to `.gdh-state/migration.json` per
+ * D-07 / D-08 / D-13.
+ *
+ * Gate sequence (fail-closed, no exception propagates to caller):
+ *   1. Slug shape (path-traversal defense via {@link isEnvelopeSlug}).
+ *   2. Read --result-file (or use --result inline).
+ *   3. JSON.parse (Pitfall 4 — caught and surfaced as `parse_failed`).
+ *   4. Schema validation against {@link isEnvelopeOutput} typed union.
+ *   5. Read migration.json; require `pending_envelope_resume` marker
+ *      (D-09 / D-11 / D-13 — chain must be paused before record).
+ *   6. Triple match: marker.envelope_ref === input.envelopeRef.
+ *   7. Append prior slot to `attempts[]` (Pitfall 2 — outer fields become a
+ *      new attempt; existing attempts[] history accumulates).
+ *   8. Atomic write through {@link writeMigrationState}; D-13 preserves
+ *      `pending_envelope_resume` (record does NOT clear it).
+ *
+ * The function NEVER calls `bumpAndRebakePin` and NEVER advances the chain
+ * (D-13 lock). The agent re-runs `gdh self-update` to resume.
+ */
+export async function recordEnvelopeResult(input) {
+    // Gate 1: slug shape (path-traversal defense). isEnvelopeSlug rejects
+    // non-string, uppercase, dashes, and traversal segments.
+    if (!isEnvelopeSlug(input.envelopeRef)) {
+        return {
+            state: "blocked",
+            reason: "envelope_not_found",
+            details: `invalid slug shape: ${input.envelopeRef}`,
+        };
+    }
+    // Gate 2: read --result-file or use --result inline.
+    let rawJson;
+    if (input.resultSource.kind === "file") {
+        const read = await fs
+            .readFile(input.resultSource.absolutePath, "utf8")
+            .catch(() => null);
+        if (read === null) {
+            return {
+                state: "blocked",
+                reason: "result_file_unreadable",
+                details: input.resultSource.absolutePath,
+            };
+        }
+        rawJson = read;
+    }
+    else {
+        rawJson = input.resultSource.json;
+    }
+    // Gate 3: JSON parse (Pitfall 4 — never let JSON.parse throw out of the CLI).
+    let parsed;
+    try {
+        parsed = JSON.parse(rawJson);
+    }
+    catch (error) {
+        return {
+            state: "blocked",
+            reason: "parse_failed",
+            details: error instanceof Error ? error.message : String(error),
+        };
+    }
+    // Gate 4: schema validation against typed union.
+    if (!isEnvelopeOutput(parsed)) {
+        const preview = JSON.stringify(parsed).slice(0, 120);
+        return {
+            state: "blocked",
+            reason: "schema_violation",
+            details: `expected GdhMigrationEnvelopeOutput, got ${preview}`,
+        };
+    }
+    // Gate 5: read migration.json; require pending_envelope_resume marker.
+    const state = await readMigrationState(input.targetPath);
+    const marker = state?.pending_envelope_resume ?? null;
+    if (marker === null) {
+        return {
+            state: "blocked",
+            reason: "no_pending_chain",
+            details: "no pending_envelope_resume marker in migration.json",
+        };
+    }
+    if (marker.envelope_ref !== input.envelopeRef) {
+        return {
+            state: "blocked",
+            // WR-02: this is a slug/marker mismatch, NOT a pin pair mismatch. The
+            // pin-staleness check (D-10) lives in applyMigrationChain via
+            // isEnvelopeRecordValid. Use a discriminant that names what actually
+            // failed so dispatcher messages and dogfooding log scrapers don't
+            // mislead operators.
+            reason: "envelope_ref_mismatch",
+            details: `pending_envelope_resume.envelope_ref is "${marker.envelope_ref}", not "${input.envelopeRef}"`,
+        };
+    }
+    // Gate 6: append prior slot to attempts[] (Pitfall 2). The prior slot's OWN
+    // outer fields become a new attempt; we ALSO carry forward the prior slot's
+    // existing attempts[] so history accumulates across re-records.
+    const priorSlot = state?.envelopes?.[input.envelopeRef] ?? null;
+    const nowIso = (input.nowIso ?? (() => new Date().toISOString()))();
+    const newAttempts = priorSlot
+        ? [
+            ...priorSlot.attempts,
+            {
+                recorded_at: priorSlot.recorded_at,
+                from_pin: priorSlot.from_pin,
+                to_pin: priorSlot.to_pin,
+                output_contract: priorSlot.output_contract,
+            },
+        ]
+        : [];
+    const newSlot = {
+        recorded_at: nowIso,
+        from_pin: marker.from_pin,
+        to_pin: marker.to_pin,
+        output_contract: parsed,
+        attempts: newAttempts,
+    };
+    // Gate 7: atomic write through writeMigrationState (Pitfall 6).
+    // D-13: do NOT clear pending_envelope_resume here. The next bumpAndRebakePin
+    // run reads the recorded slot, advances the chain, and clears the marker
+    // on success.
+    //
+    // WR-05: `state` is guaranteed non-null past Gate 5 (line 1869-1875 returns
+    // `blocked: no_pending_chain` when `state?.pending_envelope_resume` is null,
+    // which transitively requires `state` to be non-null). The previous fallback
+    // (`state ?? {... last_applied_at: { schema: 0, agentContract: 0 } ...}`)
+    // was unreachable AND would have written invalid (0, 0) bumps to disk if a
+    // refactor ever weakened Gate 5. We assert non-null here so a future weaken
+    // of Gate 5 fails type-check rather than corrupting last_applied_at.
+    const baseState = state;
+    await writeMigrationState(input.targetPath, {
+        ...baseState,
+        envelopes: { ...(baseState.envelopes ?? {}), [input.envelopeRef]: newSlot },
+        pending_envelope_resume: marker, // preserve — D-13
+    });
+    return {
+        state: "recorded",
+        envelope_ref: input.envelopeRef,
+        recorded_at: nowIso,
+        from_pin: marker.from_pin,
+        to_pin: marker.to_pin,
+        output_contract_state: parsed.state,
+    };
+}
+/**
+ * Remove the per-slug slot from `migration.json.envelopes`. Testing/debug
+ * companion to {@link recordEnvelopeResult}; does NOT touch
+ * `pending_envelope_resume` (deliberate isolation — clearing the slot does
+ * not unpause a chain).
+ */
+export async function clearEnvelope(input) {
+    const state = await readMigrationState(input.targetPath);
+    if (state === null) {
+        return { state: "noop", reason: "no_migration_state" };
+    }
+    if (!state.envelopes || !(input.envelopeRef in state.envelopes)) {
+        return { state: "noop", reason: "slot_not_present" };
+    }
+    const { [input.envelopeRef]: _drop, ...rest } = state.envelopes;
+    void _drop;
+    await writeMigrationState(input.targetPath, {
+        ...state,
+        envelopes: rest,
+    });
+    return { state: "cleared", envelope_ref: input.envelopeRef };
+}
 //# sourceMappingURL=migrate.js.map