@skillcap/gdh 0.5.0 → 0.6.0

package/node_modules/@gdh/adapters/dist/self-update-mechanics.js

@@ -0,0 +1,155 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolvePinnedVersion, resolvePinnedVersionOrNull, writePinnedVersion, } from "@gdh/authoring";
+import { resolveEffectiveDevRepoPath } from "@gdh/core";
+// Dynamic import breaks the circular dependency with ./index.ts.
+//
+// self-update-mechanics.ts is re-exported from adapters/index.ts (the barrel).
+// installSupportedAgentAdapters is defined in index.ts. A static import of
+// index.ts from here creates a circular reference that Vite SSR resolves with
+// a partial module object, making some exports undefined at call time.
+//
+// All imports from @gdh/authoring and @gdh/core remain static: the circular dep
+// only applies to ./index.js within the same package. Vite's tsconfig path
+// mapping correctly resolves cross-package static imports to source files.
+// The dynamic import() for ./index.js is the only exception: it defers the
+// intra-package circular resolution to call time, after all modules initialize.
+async function loadInstallSupportedAgentAdapters() {
+    const { installSupportedAgentAdapters } = await import("./index.js");
+    return installSupportedAgentAdapters;
+}
+/**
+ * Phase 12 MIG-01 + MIG-02 orchestrator. Atomically bumps the .gdh/project.yaml
+ * `gdh_version` pin and re-bakes every managed surface at the new pin.
+ *
+ * Sequencing invariant (MIG-02): writePinnedVersion is called BEFORE
+ * installSupportedAgentAdapters. Because installSupportedAgentAdapters reads
+ * the pin from disk once per top-level call (adapters/index.ts:173), pinning
+ * first guarantees every renderer bakes the new value.
+ *
+ * Transactional invariant (MIG-02): on re-bake failure, every captured original
+ * is restored. Partial state is not acceptable.
+ *
+ * SELF-03 leak barrier: dev-mode check gates at the mechanics layer, not only at
+ * Phase 13 entry points. Single source of truth.
+ */
+export async function bumpAndRebakePin(targetPath, options) {
+    // Step 1 (SELF-03 leak barrier): dev-mode short-circuit.
+    const devRepoPath = await resolveEffectiveDevRepoPath(targetPath);
+    if (devRepoPath !== null) {
+        return {
+            state: "skipped_dev_mode",
+            devRepoPath,
+            currentVersion: await resolvePinnedVersionOrNull(targetPath),
+        };
+    }
+    // Step 2: Read current pin (throws with gdh-migrate-apply hint if unonboarded).
+    const fromVersion = await resolvePinnedVersion(targetPath);
+    if (fromVersion === options.targetVersion) {
+        return { state: "noop", currentVersion: fromVersion };
+    }
+    // Step 3: Plan — dry-run to collect actions. File SET is determined by adapter
+    // status + guidance readiness, not by pin value; planning against current pin
+    // tells us which files to capture. Per research recommendation (c).
+    const installSupportedAgentAdapters = await loadInstallSupportedAgentAdapters();
+    const plan = await installSupportedAgentAdapters(targetPath, {
+        dryRun: true,
+        allowBootstrap: true,
+    });
+    // Step 4: Capture originals (including .gdh/project.yaml) before any mutation.
+    const configPath = path.join(targetPath, ".gdh/project.yaml");
+    const originals = await captureOriginals(plan.actions, configPath);
+    if (options.dryRun === true) {
+        return {
+            state: "updated",
+            fromVersion,
+            toVersion: options.targetVersion,
+            actions: plan.actions,
+        };
+    }
+    // Step 5: COMMIT POINT — write new pin first (MIG-02 sequencing).
+    //   Phase 12 Check 43 asserts writePinnedVersion call textually precedes the
+    //   final installSupportedAgentAdapters call in this source file. Both calls
+    //   are inside bumpAndRebakePin; the grep/awk check targets the function body.
+    try {
+        await writePinnedVersion(targetPath, options.targetVersion);
+    }
+    catch (error) {
+        // Nothing else mutated yet — no rollback needed.
+        return { state: "blocked", reason: `Pin write failed: ${formatError(error)}` };
+    }
+    // Step 6: Re-bake — installSupportedAgentAdapters reads the new pin from disk.
+    try {
+        const rebake = await installSupportedAgentAdapters(targetPath, {
+            allowBootstrap: true,
+        });
+        const blocked = rebake.actions.filter((a) => a.state === "blocked");
+        if (blocked.length > 0) {
+            throw new Error(`Re-bake had ${blocked.length} blocked action(s): ${blocked
+                .map((a) => a.summary)
+                .join("; ")}`);
+        }
+        return {
+            state: "updated",
+            fromVersion,
+            toVersion: options.targetVersion,
+            actions: rebake.actions,
+        };
+    }
+    catch (error) {
+        const restoreFailures = await rollbackOriginals(originals);
+        return {
+            state: "rolled_back",
+            fromVersion,
+            attemptedToVersion: options.targetVersion,
+            failureReason: formatError(error),
+            restoreFailures,
+        };
+    }
+}
+/**
+ * Capture current content of every file the planned actions will touch, plus the
+ * pin config. A `null` value means the file did not exist — rollback is `fs.rm`.
+ * Skips actions with null absolutePath (run_command, write_local_hints abstract actions).
+ */
+async function captureOriginals(plannedActions, pinConfigPath) {
+    const originals = new Map();
+    originals.set(pinConfigPath, await fs.readFile(pinConfigPath, "utf8"));
+    for (const action of plannedActions) {
+        if (action.absolutePath === null)
+            continue;
+        if (originals.has(action.absolutePath))
+            continue;
+        const existing = await fs
+            .readFile(action.absolutePath, "utf8")
+            .catch(() => null);
+        originals.set(action.absolutePath, existing);
+    }
+    return originals;
+}
+/**
+ * Best-effort restore. Iterates captured originals; restores content or rm's
+ * previously-absent files. Collects failure messages but continues (rollback-soldier
+ * pattern: partial recovery > aborting mid-rollback).
+ */
+async function rollbackOriginals(originals) {
+    const failures = [];
+    for (const [absolutePath, content] of originals) {
+        try {
+            if (content === null) {
+                await fs.rm(absolutePath, { force: true });
+            }
+            else {
+                await fs.writeFile(absolutePath, content, "utf8");
+            }
+        }
+        catch (error) {
+            failures.push(`${absolutePath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return failures;
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=self-update-mechanics.js.map

package/node_modules/@gdh/adapters/dist/self-update-mechanics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-update-mechanics.js","sourceRoot":"","sources":["../src/self-update-mechanics.ts"],"names":[],"mappings":"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"}

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

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

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

@@ -6,6 +6,7 @@ export declare function runAuthoringCheck(input: {
     readonly projectConfig: GdhProjectConfig | null;
 }): Promise<GdhAuthoringCheckResult>;
 export { hasCompleteOnboardingSurface, parseProjectConfigYaml, readProjectConfig, resolvePinnedVersion, resolvePinnedVersionOrNull, resolveProjectRoot, readWorktreeState, resolveAuthoringStatus, resolveConfiguredCapabilities, resolveTargetGodotDocsVersion, } from "./project.js";
+export { writePinnedVersion } from "./writePinnedVersion.js";
 export { getManagedLspStatus, resetManagedLspTestState, runManagedAuthoringCheck, } from "./lsp.js";
 export { inspectCacheState, pruneCacheState, resolveCacheNamespace } from "./cache.js";
 export { runImportRefresh, runTargetPrepare } from "./prepare.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,EACtB,MAAM,WAAW,CAAC;AAOnB,eAAO,MAAM,gBAAgB,wCAM3B,CAAC;AAEH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE;IAC7C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,QAAQ,CAAC,aAAa,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACjD,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAqBnC;AAED,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,EACtB,MAAM,WAAW,CAAC;AAOnB,eAAO,MAAM,gBAAgB,wCAM3B,CAAC;AAEH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE;IAC7C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,QAAQ,CAAC,aAAa,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACjD,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAqBnC;AAED,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

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

@@ -30,6 +30,7 @@ export async function runAuthoringCheck(input) {
     });
 }
 export { hasCompleteOnboardingSurface, parseProjectConfigYaml, readProjectConfig, resolvePinnedVersion, resolvePinnedVersionOrNull, resolveProjectRoot, readWorktreeState, resolveAuthoringStatus, resolveConfiguredCapabilities, resolveTargetGodotDocsVersion, } from "./project.js";
+export { writePinnedVersion } from "./writePinnedVersion.js";
 export { getManagedLspStatus, resetManagedLspTestState, runManagedAuthoringCheck, } from "./lsp.js";
 export { inspectCacheState, pruneCacheState, resolveCacheNamespace } from "./cache.js";
 export { runImportRefresh, runTargetPrepare } from "./prepare.js";

package/node_modules/@gdh/authoring/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,GAItB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAC;AACnG,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAEzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,qBAAqB,CAAC;IACpD,IAAI,EAAE,gBAAgB;IACtB,KAAK,EAAE,YAAY;IACnB,cAAc,EACZ,kGAAkG;IACpG,2BAA2B,EAAE,CAAC,WAAW,CAAC;CAC3C,CAAC,CAAC;AAEH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAIvC;IACC,MAAM,SAAS,GAAG,MAAM,mBAAmB,CAAC;QAC1C,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,KAAK,EAAE,qBAAqB;KAC7B,CAAC,CAAC;IAEH,MAAM,UAAU,GAAG,MAAM,wBAAwB,CAAC;QAChD,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,SAAS;KACV,CAAC,CAAC;IAEH,OAAO,0BAA0B,CAAC;QAChC,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,MAAM,EAAE,UAAU;KACnB,CAAC,CAAC;AACL,CAAC;AAED,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,GAItB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAC;AACnG,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAEzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,qBAAqB,CAAC;IACpD,IAAI,EAAE,gBAAgB;IACtB,KAAK,EAAE,YAAY;IACnB,cAAc,EACZ,kGAAkG;IACpG,2BAA2B,EAAE,CAAC,WAAW,CAAC;CAC3C,CAAC,CAAC;AAEH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAIvC;IACC,MAAM,SAAS,GAAG,MAAM,mBAAmB,CAAC;QAC1C,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,KAAK,EAAE,qBAAqB;KAC7B,CAAC,CAAC;IAEH,MAAM,UAAU,GAAG,MAAM,wBAAwB,CAAC;QAChD,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,SAAS;KACV,CAAC,CAAC;IAEH,OAAO,0BAA0B,CAAC;QAChC,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,MAAM,EAAE,UAAU;KACnB,CAAC,CAAC;AACL,CAAC;AAED,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/node_modules/@gdh/authoring/dist/writePinnedVersion.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Replaces the EXISTING `gdh_version` line in `.gdh/project.yaml` with a new pin.
+ * Distinct from `rewriteProjectConfig` (packages/cli/src/migrate.ts:843), which
+ * ONLY adds the field when missing. Phase 12 MIG-01: self-update needs the
+ * update-existing path; `gdh migrate` stays pin-preserving.
+ *
+ * Atomicity: writes temp file + fs.rename. POSIX guarantees rename atomicity
+ * within a single filesystem. Keep `.tmp-<pid>` sibling to the final path so
+ * both live in `.gdh/` — crossing filesystems fails with EXDEV.
+ *
+ * Throws:
+ * - Error (/exact SemVer/) when newVersion does not match EXACT_SEMVER_PATTERN
+ * - Error (/gdh migrate --apply/) when .gdh/project.yaml is missing gdh_version
+ * - underlying fs errors (ENOENT on missing .gdh/project.yaml, EACCES, etc.)
+ */
+export declare function writePinnedVersion(targetPath: string, newVersion: string): Promise<void>;
+//# sourceMappingURL=writePinnedVersion.d.ts.map

package/node_modules/@gdh/authoring/dist/writePinnedVersion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writePinnedVersion.d.ts","sourceRoot":"","sources":["../src/writePinnedVersion.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyC9F"}

package/node_modules/@gdh/authoring/dist/writePinnedVersion.js

@@ -0,0 +1,50 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { EXACT_SEMVER_PATTERN } from "./project.js";
+/**
+ * Replaces the EXISTING `gdh_version` line in `.gdh/project.yaml` with a new pin.
+ * Distinct from `rewriteProjectConfig` (packages/cli/src/migrate.ts:843), which
+ * ONLY adds the field when missing. Phase 12 MIG-01: self-update needs the
+ * update-existing path; `gdh migrate` stays pin-preserving.
+ *
+ * Atomicity: writes temp file + fs.rename. POSIX guarantees rename atomicity
+ * within a single filesystem. Keep `.tmp-<pid>` sibling to the final path so
+ * both live in `.gdh/` — crossing filesystems fails with EXDEV.
+ *
+ * Throws:
+ * - Error (/exact SemVer/) when newVersion does not match EXACT_SEMVER_PATTERN
+ * - Error (/gdh migrate --apply/) when .gdh/project.yaml is missing gdh_version
+ * - underlying fs errors (ENOENT on missing .gdh/project.yaml, EACCES, etc.)
+ */
+export async function writePinnedVersion(targetPath, newVersion) {
+    if (!EXACT_SEMVER_PATTERN.test(newVersion)) {
+        throw new Error(`Cannot pin \`gdh_version\`: ${JSON.stringify(newVersion)} is not an exact SemVer. ` +
+            "Ranges (^, ~), dist-tags (latest, next), and local paths are rejected.");
+    }
+    const configPath = path.join(targetPath, ".gdh/project.yaml");
+    const original = await fs.readFile(configPath, "utf8");
+    // Mirror the EXACT regex migrate.ts:843 uses to DETECT the pin; inverted guard here.
+    if (!/^gdh_version:/m.test(original)) {
+        throw new Error(".gdh/project.yaml is missing the `gdh_version` field. " +
+            "Run `gdh migrate --apply` to bootstrap the pin before invoking self-update.");
+    }
+    // JSON.stringify produces "<v>" (double-quoted) — matches migrate.ts:845 wire format
+    // and parseProjectConfigYaml expectations (project.ts:461 parseYamlStringValue).
+    const updated = original.replace(/^gdh_version:.*\n/m, `gdh_version: ${JSON.stringify(newVersion)}\n`);
+    if (updated === original) {
+        // Defense-in-depth no-op: caller (bumpAndRebakePin in Plan 02) must detect
+        // this upstream via resolvePinnedVersion comparison to emit state: "noop".
+        return;
+    }
+    const tempPath = `${configPath}.tmp-${process.pid}`;
+    await fs.writeFile(tempPath, updated, "utf8");
+    try {
+        await fs.rename(tempPath, configPath);
+    }
+    catch (error) {
+        // Best-effort temp-file cleanup on rename failure; swallow secondary errors.
+        await fs.rm(tempPath, { force: true }).catch(() => { });
+        throw error;
+    }
+}
+//# sourceMappingURL=writePinnedVersion.js.map

package/node_modules/@gdh/authoring/dist/writePinnedVersion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writePinnedVersion.js","sourceRoot":"","sources":["../src/writePinnedVersion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,UAAkB,EAAE,UAAkB;IAC7E,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CACb,+BAA+B,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,2BAA2B;YAClF,wEAAwE,CAC3E,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,mBAAmB,CAAC,CAAC;IAC9D,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAEvD,qFAAqF;IACrF,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,wDAAwD;YACtD,6EAA6E,CAChF,CAAC;IACJ,CAAC;IAED,qFAAqF;IACrF,iFAAiF;IACjF,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAC9B,oBAAoB,EACpB,gBAAgB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAC/C,CAAC;IAEF,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzB,2EAA2E;QAC3E,2EAA2E;QAC3E,OAAO;IACT,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,UAAU,QAAQ,OAAO,CAAC,GAAG,EAAE,CAAC;IACpD,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC9C,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,6EAA6E;QAC7E,MAAM,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACvD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

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

@@ -10,8 +10,11 @@
       "import": "./dist/index.js"
     }
   },
+  "scripts": {
+    "test": "vitest run"
+  },
   "dependencies": {
-    "@gdh/core": "0.5.0"
+    "@gdh/core": "0.6.0"
   },
-  "version": "0.5.0"
+  "version": "0.6.0"
 }

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

@@ -1,7 +1,22 @@
+import { recordAuthoringSessionEvent } from "@gdh/observability";
 export declare const cliPackage: import("@gdh/core").GdhPackageBoundary;
 export interface CliIo {
     readonly stdout: Pick<NodeJS.WriteStream, "write">;
     readonly stderr: Pick<NodeJS.WriteStream, "write">;
 }
 export declare function runCli(args: readonly string[], io?: CliIo): Promise<number>;
+export declare function writeJsonResult(io: CliIo, value: unknown, options?: {
+    readonly presentRuntimeTerms?: boolean;
+}): void;
+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: {
+    readonly usage: string;
+    readonly optionsWithValues?: readonly string[];
+    readonly booleanOptions?: readonly string[];
+}): string | null;
+export declare function recordSessionEvent(targetPath: string, input: Parameters<typeof recordAuthoringSessionEvent>[1] & {
+    readonly commandStartedAtMs?: number;
+}): Promise<void>;
+export declare function extractPositionalArgs(args: readonly string[], optionsWithValues: ReadonlySet<string>): readonly string[];
 //# sourceMappingURL=index.d.ts.map

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":"AAsHA,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,CA2GjB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAyEA,OAAO,EAIL,2BAA2B,EAC5B,MAAM,oBAAoB,CAAC;AA2C5B,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,CA+GjB;AAED,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;AAg8ID,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAErD;AAkFD,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,CAcf;AA8ED,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,CAef;AAwFD,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

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { buildGdhStatusResult, CLAUDE_CHECK_COMMAND_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 { 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";
@@ -12,7 +12,9 @@ import { applyRepairableOnboardingWrites, onboardGodotProject, persistInventoryF
 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`);
 }
@@ -386,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, {
@@ -1257,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);
     }
@@ -2541,6 +2561,46 @@ const VERIFY_DRIFT_SCANNED_FILES = [
     { 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.
@@ -2608,7 +2668,7 @@ async function runVerifyDriftCommand(args, io) {
                 reason: "file_missing",
             };
         }
-        const match = content.match(VERIFY_DRIFT_BAKED_VERSION_REGEX);
+        const match = content.match(file.versionRegex ?? VERIFY_DRIFT_BAKED_VERSION_REGEX);
         const baked = match?.[1] ?? null;
         const reason = baked === null
             ? "no_baked_version"
@@ -3733,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) {
@@ -3791,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;
@@ -3802,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 ?? []),
@@ -3864,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)
@@ -3939,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];