@skillcap/gdh 0.1.2

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

@@ -0,0 +1,2415 @@
+import { execFile as execFileCallback } from "node:child_process";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { readProjectConfig, readWorktreeState, resolveAuthoringStatus, } from "@gdh/authoring";
+import { GDH_AGENT_CONTRACT_VERSION, GDH_CURSOR_RULE_VERSION, GDH_GUIDANCE_INDEX_VERSION, GDH_GUIDANCE_UNIT_VERSION, GDH_MCP_LAUNCHER_VERSION, GDH_PROJECT_CONFIG_VERSION, GDH_RECIPE_SCHEMA_VERSION, GDH_RULES_SCHEMA_VERSION, GDH_SCENARIO_SCHEMA_VERSION, definePackageBoundary, resolveCurrentGdhInstall, resolveGdhProductMetadata, } from "@gdh/core";
+import { createDefaultGuidanceUnits, getGuidanceStatus, resolveGuidanceQuery, } from "@gdh/docs";
+import { inspectGuidanceAudit } from "@gdh/observability";
+import { inspectRuntimeBridgeSurface } from "@gdh/runtime";
+import { scanGodotProjectInventory } from "@gdh/scan";
+import { evaluateDonePolicy, recommendValidationForChange } from "@gdh/verify";
+export const adaptersPackage = definePackageBoundary({
+    name: "@gdh/adapters",
+    layer: "integration",
+    responsibility: "Optional workflow and agent adapters that consume GDH surfaces without owning core behavior.",
+    allowedInternalDependencies: [
+        "@gdh/core",
+        "@gdh/authoring",
+        "@gdh/docs",
+        "@gdh/observability",
+        "@gdh/runtime",
+        "@gdh/scan",
+        "@gdh/verify",
+    ],
+});
+export const SUPPORTED_AGENTS = ["codex", "claude", "cursor"];
+export const CLAUDE_SHIM_RELATIVE_PATH = "CLAUDE.md";
+export const CLAUDE_ONBOARD_COMMAND_RELATIVE_PATH = ".claude/commands/gdh/onboard.md";
+export const PROJECT_MCP_RELATIVE_PATH = ".mcp.json";
+export const CURSOR_MCP_RELATIVE_PATH = ".cursor/mcp.json";
+export const CURSOR_RULE_RELATIVE_PATH = ".cursor/rules/gdh-agent.mdc";
+export const CURSOR_ONBOARD_SKILL_RELATIVE_PATH = ".cursor/skills/gdh-onboard/SKILL.md";
+export const CODEX_ONBOARD_SKILL_RELATIVE_PATH = ".codex/skills/gdh-onboard/SKILL.md";
+export const LOCAL_PATH_HINTS_RELATIVE_PATH = ".gdh-state/local-paths.json";
+export const MCP_LAUNCHER_RELATIVE_PATH = ".gdh/bin/gdh-mcp.mjs";
+export const GDH_MCP_SERVER_NAME = "gdh";
+const execFile = promisify(execFileCallback);
+export async function getSupportedAgentAdaptersStatus(targetPath, options = {}) {
+    const includeUserLocal = options.includeUserLocal ?? true;
+    const integrationRootPath = resolveIntegrationRootPath(targetPath, options.integrationRootPath);
+    const guidance = await getGuidanceStatus(targetPath);
+    const projectMcp = await inspectProjectMcpSupport(targetPath, {
+        includeUserLocal,
+        integrationRootPath,
+    });
+    const [codex, claude, cursor] = await Promise.all([
+        inspectCodexAdapter(targetPath, guidance, projectMcp, {
+            includeUserLocal,
+        }),
+        inspectClaudeAdapter(targetPath, guidance, projectMcp),
+        inspectCursorAdapter(targetPath, guidance, projectMcp),
+    ]);
+    return {
+        targetPath,
+        guidance,
+        adapters: [codex, claude, cursor],
+    };
+}
+export async function installSupportedAgentAdapters(targetPath, options = {}) {
+    const dryRun = options.dryRun ?? false;
+    const requestedAgents = normalizeRequestedAgents(options.agents);
+    const integrationRootPath = resolveIntegrationRootPath(targetPath, options.integrationRootPath);
+    const status = await getSupportedAgentAdaptersStatus(targetPath, {
+        integrationRootPath,
+    });
+    if (!hasReadyVisibilityChain(status.guidance) && options.allowBootstrap !== true) {
+        return {
+            targetPath,
+            dryRun,
+            state: "blocked",
+            summary: "The canonical GDH visibility chain is not ready, so agent reinforcement cannot be installed safely.",
+            requestedAgents,
+            guidance: status.guidance,
+            adapters: status.adapters,
+            actions: [],
+        };
+    }
+    const actions = await planInstallActions(targetPath, status.adapters, requestedAgents, {
+        user: options.user ?? false,
+        devRepoPath: options.devRepoPath ?? null,
+        integrationRootPath,
+    });
+    if (!dryRun) {
+        for (const action of actions) {
+            if (action.state === "unchanged") {
+                continue;
+            }
+            if (action.kind === "ensure_symlink") {
+                await applySymlinkAction(action);
+                continue;
+            }
+            if (action.kind === "run_command") {
+                await applyRunCommandAction(action);
+                continue;
+            }
+            if (action.command?.[0] === "write_local_hints") {
+                await applyLocalHintsAction(action);
+                continue;
+            }
+            await applyWriteFileAction(action);
+        }
+    }
+    return {
+        targetPath,
+        dryRun,
+        state: dryRun ? "planned" : "applied",
+        summary: actions.length === 0 || actions.every((action) => action.state === "unchanged")
+            ? "Requested agent adapters were already aligned with the canonical GDH visibility chain."
+            : dryRun
+                ? "Planned supported-agent reinforcement actions without mutating the target or user-local agent config."
+                : "Applied supported-agent reinforcement actions against the canonical GDH visibility chain.",
+        requestedAgents,
+        guidance: status.guidance,
+        adapters: status.adapters,
+        actions,
+    };
+}
+export async function inspectProjectLifecycleCompatibility(targetPath) {
+    const resolvedTargetPath = path.resolve(targetPath);
+    const projectConfig = await readProjectConfig(resolvedTargetPath);
+    if (projectConfig === null) {
+        const blockedSurface = createLifecycleSurfaceStatus({
+            surface: "project_config",
+            management: "project_owned",
+            state: "migration_blocked",
+            summary: "Project-surface compatibility is unavailable until the target is onboarded into .gdh/project.yaml.",
+            reasons: ["project_not_onboarded"],
+            probes: [
+                createVersionProbe({
+                    targetPath: resolvedTargetPath,
+                    relativePath: ".gdh/project.yaml",
+                    present: false,
+                    expectedVersion: GDH_PROJECT_CONFIG_VERSION,
+                    detectedVersion: null,
+                }),
+            ],
+            action: {
+                kind: "manual_review",
+                summary: "Run `gdh setup` before attempting lifecycle migration or repair.",
+                command: ["gdh", "setup", resolvedTargetPath],
+                autoApplicable: false,
+            },
+        });
+        return summarizeProjectLifecycleCompatibility(resolvedTargetPath, [
+            blockedSurface,
+        ]);
+    }
+    const guidanceStatus = await getGuidanceStatus(resolvedTargetPath);
+    const bridgeStatus = await inspectRuntimeBridgeSurface({
+        targetPath: resolvedTargetPath,
+        projectConfig,
+    });
+    const adapterStatus = await getSupportedAgentAdaptersStatus(resolvedTargetPath, {
+        includeUserLocal: false,
+    });
+    return summarizeProjectLifecycleCompatibility(resolvedTargetPath, [
+        await inspectProjectConfigLifecycleSurface(resolvedTargetPath),
+        await inspectRunConfigurationLifecycleSurface(resolvedTargetPath),
+        await inspectVerificationScenarioLifecycleSurface(resolvedTargetPath),
+        await inspectRulesLifecycleSurface(resolvedTargetPath),
+        inspectAgentContractLifecycleSurface(resolvedTargetPath, guidanceStatus),
+        await inspectGuidanceIndexLifecycleSurface(resolvedTargetPath),
+        await inspectGuidanceUnitLifecycleSurface(resolvedTargetPath, projectConfig),
+        inspectMcpManifestLifecycleSurface(resolvedTargetPath, projectConfig.mcp.enabled, adapterStatus),
+        inspectCursorRuleLifecycleSurface(resolvedTargetPath, adapterStatus),
+        inspectMcpLauncherLifecycleSurface(resolvedTargetPath, projectConfig.mcp.enabled, adapterStatus),
+        inspectRuntimeBridgeLifecycleSurface(resolvedTargetPath, bridgeStatus),
+    ]);
+}
+export async function buildGdhStatusResult(targetPath) {
+    const context = await buildAuthoringContext(targetPath);
+    const projectLifecycle = await inspectProjectLifecycleCompatibility(targetPath);
+    return {
+        ...context.status,
+        product: resolveGdhProductMetadata(),
+        projectLifecycle,
+    };
+}
+export async function createGsdSnapshot(targetPath, options = {}) {
+    const context = await buildAuthoringContext(targetPath);
+    const effectiveRepoState = deriveRepoState(context);
+    const files = normalizeChangedFiles(options.files ?? []);
+    const performed = [...new Set(options.performed ?? [])];
+    const guidance = await getGuidanceStatus(targetPath);
+    const [audit, guidanceResolve] = await Promise.all([
+        inspectGuidanceAudit(targetPath),
+        resolveGuidanceQuery(targetPath, {
+            taskTypes: ["authoring"],
+            capabilities: context.status.effectiveCapabilities,
+            repoState: effectiveRepoState,
+            keywords: [],
+        }),
+    ]);
+    const guidanceStatus = {
+        targetPath,
+        projectConfigPresent: context.projectConfig !== null,
+        authoringReadiness: context.status.readiness,
+        effectiveRepoState,
+        guidance,
+        audit,
+    };
+    const validationRecommendation = files.length === 0
+        ? {
+            state: "unavailable",
+            summary: "Validation expectations are unavailable until the snapshot is given changed files.",
+            value: null,
+        }
+        : {
+            state: "available",
+            summary: "Validation expectations were projected from the current GDH verify recommendation surface.",
+            value: await recommendValidationForChange({
+                targetPath,
+                inventory: context.inventory,
+                status: context.status,
+                projectConfig: context.projectConfig,
+                files,
+            }),
+        };
+    const donePolicy = validationRecommendation.value === null
+        ? {
+            state: "unavailable",
+            summary: "Done-policy evaluation is unavailable until changed files are supplied for the snapshot.",
+            value: null,
+        }
+        : {
+            state: "available",
+            summary: "Done-policy evaluation was projected from the current GDH verify done surface.",
+            value: await evaluateDonePolicy({
+                targetPath,
+                inventory: context.inventory,
+                status: context.status,
+                projectConfig: context.projectConfig,
+                files,
+                performed,
+            }),
+        };
+    return {
+        targetPath,
+        adapter: {
+            adapter: "gsd",
+            enabledByDefault: false,
+            state: "disabled_by_default",
+            summary: "The GSD bridge is an optional read-mostly adapter over stable GDH outputs and is not required for core GDH behavior.",
+        },
+        files,
+        performed,
+        status: context.status,
+        guidanceStatus,
+        guidanceResolve,
+        validationRecommendation,
+        donePolicy,
+    };
+}
+export function renderCursorRule() {
+    return [
+        "---",
+        "description: GDH visibility reinforcement",
+        "alwaysApply: true",
+        "---",
+        `<!-- GDH CURSOR RULE VERSION: ${GDH_CURSOR_RULE_VERSION} -->`,
+        "# GDH Cursor Rule",
+        "",
+        "This repository uses GDH.",
+        "Follow the canonical repo-local entrypoint in [AGENTS.md](../../AGENTS.md), then load the canonical guidance index at [docs/agent/README.md](../../docs/agent/README.md) before substantive work.",
+        "Do not duplicate or override the canonical GDH guidance chain here.",
+        "",
+    ].join("\n");
+}
+export function renderClaudeOnboardCommand() {
+    return [
+        "---",
+        "name: gdh:onboard",
+        "description: Finish GDH setup handoff and report project readiness",
+        "allowed-tools:",
+        "  - Read",
+        "  - Grep",
+        "  - Glob",
+        "  - Bash",
+        "  - AskUserQuestion",
+        "---",
+        "<objective>",
+        "Finish the first-time GDH handoff after `gdh setup` and turn the generated GDH surface into a trustworthy starting point for real work.",
+        "</objective>",
+        "",
+        "<process>",
+        "Follow this order:",
+        "",
+        "1. Confirm the selected target and current GDH state with `gdh status`.",
+        "2. Read `.gdh/project.yaml`, `docs/agent/README.md`, and `docs/agent/00-gdh-onboarding.md` before asking for facts GDH already knows.",
+        "3. Check immediate readiness with `gdh guidance status` and `gdh target prepare --dry-run`.",
+        "4. If authoring is available, run `gdh authoring check`; if LSP matters, run `gdh lsp status`.",
+        "5. Inspect `gdh run-config list` and `gdh verification-scenario list` and call out anything draft, missing, or blocked.",
+        "6. If GDH reports `godot_editor_not_configured`, explain that the Godot binary path is machine-local and offer to record `.gdh-state/local-paths.json` `godotEditorBinPath` once the human provides the local path.",
+        "7. Ask the human only for narrow unresolved environment or target facts.",
+        "8. End with a concise readiness summary and the exact next development step.",
+        "</process>",
+        "",
+        "<rules>",
+        "- Do not start editing code during `/gdh-onboard` unless the human explicitly asks.",
+        "- Prefer GDH structured surfaces over repo guesswork.",
+        "- Keep the output short, operational, and specific.",
+        "</rules>",
+        "",
+    ].join("\n");
+}
+export function renderCodexOnboardSkill() {
+    return [
+        "---",
+        'name: "gdh-onboard"',
+        'description: "Finish GDH setup handoff and report project readiness"',
+        "metadata:",
+        '  short-description: "Finish GDH setup handoff and report project readiness"',
+        "---",
+        "",
+        "<codex_skill_adapter>",
+        "## Invocation",
+        "- This skill is invoked when the user says `/gdh-onboard` or mentions `$gdh-onboard`.",
+        "- Treat any extra user text as additional onboarding context.",
+        "",
+        "## User questions",
+        "- Ask only narrow follow-up questions when GDH cannot infer the missing setup fact safely.",
+        "- If structured user-input tooling is unavailable, ask concise plain-text questions instead.",
+        "</codex_skill_adapter>",
+        "",
+        "<objective>",
+        "Finish the first-time GDH handoff after `gdh setup` and turn the generated GDH surface into a trustworthy starting point for real work.",
+        "</objective>",
+        "",
+        "<process>",
+        "Follow this order:",
+        "",
+        "- run `gdh status`",
+        "- inspect `.gdh/project.yaml`, `docs/agent/README.md`, and `docs/agent/00-gdh-onboarding.md`",
+        "- run `gdh guidance status`",
+        "- run `gdh target prepare --dry-run`",
+        "- if authoring is available, run `gdh authoring check`",
+        "- if LSP matters, run `gdh lsp status`",
+        "- run `gdh run-config list`",
+        "- run `gdh verification-scenario list`",
+        "- if GDH reports `godot_editor_not_configured`, explain that the Godot binary path is machine-local and offer to record `.gdh-state/local-paths.json` `godotEditorBinPath` once the user provides it",
+        "- ask only for narrow unresolved environment or target facts",
+        "- finish with a concise readiness summary and the exact next development step",
+        "</process>",
+        "",
+        "<rules>",
+        "- Do not start editing code during `/gdh-onboard` unless the human explicitly asks.",
+        "- Prefer GDH structured surfaces over repo guesswork.",
+        "- Keep output short, operational, and specific.",
+        "</rules>",
+        "",
+    ].join("\n");
+}
+export function renderCursorOnboardSkill() {
+    return [
+        "---",
+        "name: gdh-onboard",
+        'description: "Finish GDH setup handoff and report project readiness"',
+        "---",
+        "",
+        "<cursor_skill_adapter>",
+        "## Invocation",
+        "- This skill is invoked when the user says `/gdh-onboard` or mentions `gdh-onboard`.",
+        "- Treat any extra user text as additional onboarding context.",
+        "",
+        "## User questions",
+        "- Ask only narrow follow-up questions when GDH cannot infer the missing setup fact safely.",
+        "- Keep questions conversational and concise.",
+        "</cursor_skill_adapter>",
+        "",
+        "<objective>",
+        "Finish the first-time GDH handoff after `gdh setup` and turn the generated GDH surface into a trustworthy starting point for real work.",
+        "</objective>",
+        "",
+        "<process>",
+        "Follow this order:",
+        "",
+        "- run `gdh status`",
+        "- inspect `.gdh/project.yaml`, `docs/agent/README.md`, and `docs/agent/00-gdh-onboarding.md`",
+        "- run `gdh guidance status`",
+        "- run `gdh target prepare --dry-run`",
+        "- if authoring is available, run `gdh authoring check`",
+        "- if LSP matters, run `gdh lsp status`",
+        "- run `gdh run-config list`",
+        "- run `gdh verification-scenario list`",
+        "- if GDH reports `godot_editor_not_configured`, explain that the Godot binary path is machine-local and offer to record `.gdh-state/local-paths.json` `godotEditorBinPath` once the user provides it",
+        "- ask only for narrow unresolved environment or target facts",
+        "- finish with a concise readiness summary and the exact next development step",
+        "</process>",
+        "",
+        "<rules>",
+        "- Do not start editing code during `/gdh-onboard` unless the human explicitly asks.",
+        "- Prefer GDH structured surfaces over repo guesswork.",
+        "- Keep output short, operational, and specific.",
+        "</rules>",
+        "",
+    ].join("\n");
+}
+async function inspectProjectMcpSupport(targetPath, options) {
+    const projectConfig = await readProjectConfig(targetPath);
+    const enabled = resolveProjectMcpEnabled(projectConfig);
+    const launcherContent = renderManagedMcpLauncher();
+    const managedMcpEntry = buildManagedMcpServerEntry({
+        targetPath,
+        integrationRootPath: options.integrationRootPath,
+        launcherPathForConfig: `./${normalizePathForJson(path.relative(options.integrationRootPath, path.join(options.integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH)))}`,
+    });
+    const [projectFile, cursorFile, launcherSource, localPathHints] = await Promise.all([
+        inspectJsonFile(path.join(options.integrationRootPath, PROJECT_MCP_RELATIVE_PATH)),
+        inspectJsonFile(path.join(options.integrationRootPath, CURSOR_MCP_RELATIVE_PATH)),
+        fs.readFile(path.join(options.integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH), "utf8").catch(() => null),
+        readLocalPathHints(options.integrationRootPath),
+    ]);
+    const launcherBootstrap = await inspectLauncherBootstrap(localPathHints);
+    const codexConfigPath = path.join(os.homedir(), ".codex/config.toml");
+    const codexServerName = projectConfig === null ? null : createCodexServerName(projectConfig.projectKeySeed);
+    return {
+        enabled,
+        integrationRootPath: options.integrationRootPath,
+        launcherContent,
+        localPathHints,
+        launcherBootstrap,
+        launcherFile: inspectLauncherFile(launcherSource, launcherContent, enabled, launcherBootstrap),
+        projectFile: inspectManagedMcpFile(projectFile, enabled, PROJECT_MCP_RELATIVE_PATH, "Claude project MCP config", managedMcpEntry),
+        cursorFile: inspectManagedMcpFile(cursorFile, enabled, CURSOR_MCP_RELATIVE_PATH, "Cursor project MCP config", managedMcpEntry),
+        codexRegistration: options.includeUserLocal
+            ? await inspectCodexRegistration(targetPath, enabled, codexServerName, codexConfigPath, options.integrationRootPath)
+            : {
+                present: false,
+                state: "ready",
+                summary: "Codex user-local MCP registration is intentionally skipped for this target-local status check.",
+            },
+        codexConfigPath,
+        codexServerName,
+    };
+}
+async function inspectJsonFile(absolutePath) {
+    const content = await fs.readFile(absolutePath, "utf8").catch(() => null);
+    if (content === null) {
+        return {
+            present: false,
+            jsonObject: null,
+            parseError: null,
+        };
+    }
+    try {
+        const parsed = JSON.parse(content);
+        if (!isObjectRecord(parsed)) {
+            return {
+                present: true,
+                jsonObject: null,
+                parseError: "JSON root must be an object.",
+            };
+        }
+        return {
+            present: true,
+            jsonObject: parsed,
+            parseError: null,
+        };
+    }
+    catch (error) {
+        return {
+            present: true,
+            jsonObject: null,
+            parseError: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function inspectManagedMcpFile(file, enabled, relativePath, displayName, expectedEntry) {
+    if (!enabled) {
+        return {
+            present: file.present,
+            state: "ready",
+            summary: `${displayName} is disabled for this target.`,
+        };
+    }
+    if (!file.present) {
+        return {
+            present: false,
+            state: "missing",
+            summary: `${displayName} is missing and should define the managed \`${GDH_MCP_SERVER_NAME}\` MCP server entry at ${relativePath}.`,
+        };
+    }
+    if (file.parseError !== null || file.jsonObject === null) {
+        return {
+            present: true,
+            state: "misconfigured",
+            summary: `${relativePath} exists but is not valid JSON object content: ${file.parseError ?? "invalid JSON object"}`,
+        };
+    }
+    if (!isMatchingManagedMcpServerEntry(getManagedMcpServerEntry(file.jsonObject), expectedEntry)) {
+        return {
+            present: true,
+            state: "misconfigured",
+            summary: `${relativePath} exists but the managed \`${GDH_MCP_SERVER_NAME}\` MCP server entry does not match the expected GDH launcher command.`,
+        };
+    }
+    return {
+        present: true,
+        state: "ready",
+        summary: `${displayName} includes the managed \`${GDH_MCP_SERVER_NAME}\` MCP server entry.`,
+    };
+}
+function inspectLauncherFile(launcherSource, expectedContent, enabled, bootstrap) {
+    if (!enabled) {
+        return {
+            present: launcherSource !== null,
+            state: "ready",
+            summary: "The managed GDH MCP launcher is disabled for this target.",
+        };
+    }
+    if (launcherSource === null) {
+        return {
+            present: false,
+            state: "missing",
+            summary: `The managed GDH MCP launcher is missing and should live at ${MCP_LAUNCHER_RELATIVE_PATH}.`,
+        };
+    }
+    if (launcherSource !== expectedContent) {
+        return {
+            present: true,
+            state: "misconfigured",
+            summary: "The managed GDH MCP launcher exists but no longer matches the expected launcher content.",
+        };
+    }
+    return {
+        present: true,
+        state: bootstrap.state,
+        summary: bootstrap.state === "ready"
+            ? "The managed GDH MCP launcher is present and can resolve the current GDH bootstrap path."
+            : bootstrap.summary,
+    };
+}
+async function inspectLauncherBootstrap(localPathHints) {
+    const envDevRepoPath = process.env["GDH_DEV_REPO"]?.trim() || null;
+    const effectiveDevRepoPath = envDevRepoPath ?? localPathHints.gdhDevRepoPath;
+    if (effectiveDevRepoPath !== null) {
+        const cliEntryPath = path.join(effectiveDevRepoPath, "packages/cli/dist/cli.js");
+        if (await fileExists(cliEntryPath)) {
+            return {
+                state: "ready",
+                summary: `The managed GDH MCP launcher will bootstrap from the current GDH checkout at ${effectiveDevRepoPath}.`,
+            };
+        }
+        return {
+            state: "misconfigured",
+            summary: `The configured GDH checkout at ${effectiveDevRepoPath} does not contain packages/cli/dist/cli.js yet. Run \`corepack yarn build\` in the GDH checkout or update the local path hints.`,
+        };
+    }
+    if (await executableExistsOnPath("gdh")) {
+        return {
+            state: "ready",
+            summary: "The managed GDH MCP launcher can resolve `gdh` from PATH.",
+        };
+    }
+    return {
+        state: "missing",
+        summary: "The managed GDH MCP launcher cannot find `gdh` on PATH and no local GDH checkout hint is recorded. Run `gdh adapters install <target> --dev-repo <path-to-gdh>` or install `gdh` on PATH.",
+    };
+}
+async function inspectCodexRegistration(targetPath, enabled, codexServerName, codexConfigPath, integrationRootPath) {
+    if (!enabled || codexServerName === null) {
+        return {
+            present: false,
+            state: "ready",
+            summary: "Codex user-local MCP registration is disabled for this target.",
+        };
+    }
+    const listing = await listCodexMcpServers();
+    if (listing.state !== "available") {
+        return {
+            present: false,
+            state: "missing",
+            summary: "Codex user-local MCP registration could not be inspected. Ensure the `codex` CLI is installed and supports `codex mcp list --json`.",
+        };
+    }
+    const registration = listing.servers.find((server) => server.name === codexServerName);
+    if (!registration) {
+        return {
+            present: false,
+            state: "missing",
+            summary: `Codex does not yet have the expected user-local MCP registration \`${codexServerName}\` in ${codexConfigPath}.`,
+        };
+    }
+    const expectedLauncherPath = path.join(integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH);
+    if (!isMatchingCodexRegistration(registration, {
+        targetPath,
+        integrationRootPath,
+        launcherPath: expectedLauncherPath,
+    })) {
+        return {
+            present: true,
+            state: "misconfigured",
+            summary: `Codex MCP registration \`${codexServerName}\` exists but does not point at the managed GDH launcher ${expectedLauncherPath}.`,
+        };
+    }
+    return {
+        present: true,
+        state: "ready",
+        summary: `Codex has the expected user-local MCP registration \`${codexServerName}\`.`,
+    };
+}
+async function inspectCodexAdapter(targetPath, guidance, projectMcp, options) {
+    const codexSkillPath = path.join(targetPath, CODEX_ONBOARD_SKILL_RELATIVE_PATH);
+    const codexSkillContent = await fs.readFile(codexSkillPath, "utf8").catch(() => null);
+    const surfaces = [
+        createSurfaceStatus({
+            kind: "canonical_entrypoint",
+            scope: "repo",
+            targetPath,
+            relativePath: guidance.agentContract.relativePath,
+            present: guidance.agentContract.present,
+            state: guidance.agentContract.present
+                ? guidance.agentContract.hasManagedBlock &&
+                    guidance.agentContract.version === GDH_AGENT_CONTRACT_VERSION &&
+                    guidance.agentContract.canonicalIndexRelativePath !== null
+                    ? "ready"
+                    : "misconfigured"
+                : "missing",
+            summary: guidance.agentContract.present
+                ? "Codex consumes the canonical AGENTS.md entrypoint directly."
+                : "Codex cannot discover GDH because AGENTS.md is missing.",
+            version: guidance.agentContract.version,
+        }),
+        createSurfaceStatus({
+            kind: "skill_file",
+            scope: "repo",
+            targetPath,
+            relativePath: CODEX_ONBOARD_SKILL_RELATIVE_PATH,
+            present: codexSkillContent !== null,
+            state: codexSkillContent === null
+                ? "missing"
+                : codexSkillContent === renderCodexOnboardSkill()
+                    ? "ready"
+                    : "misconfigured",
+            summary: codexSkillContent === null
+                ? "Codex onboarding handoff is missing and should install `/gdh-onboard` under .codex/skills/."
+                : codexSkillContent === renderCodexOnboardSkill()
+                    ? "Codex can discover the managed `/gdh-onboard` handoff skill."
+                    : "Codex onboarding handoff exists but no longer matches the expected managed GDH skill.",
+            version: null,
+        }),
+    ];
+    if (projectMcp.enabled) {
+        surfaces.push(createSurfaceStatus({
+            kind: "launcher_file",
+            scope: "repo",
+            targetPath: projectMcp.integrationRootPath,
+            relativePath: MCP_LAUNCHER_RELATIVE_PATH,
+            present: projectMcp.launcherFile.present,
+            state: projectMcp.launcherFile.state,
+            summary: projectMcp.launcherFile.summary,
+            version: GDH_MCP_LAUNCHER_VERSION,
+        }));
+        if (options.includeUserLocal) {
+            surfaces.push(createSurfaceStatus({
+                kind: "user_registration",
+                scope: "user",
+                targetPath,
+                relativePath: null,
+                absolutePath: projectMcp.codexConfigPath,
+                present: projectMcp.codexRegistration.present,
+                state: projectMcp.codexRegistration.state,
+                summary: projectMcp.codexRegistration.summary,
+                version: null,
+            }));
+        }
+    }
+    return createAgentStatus("codex", guidance, surfaces);
+}
+async function inspectClaudeAdapter(targetPath, guidance, projectMcp) {
+    const absolutePath = path.join(targetPath, CLAUDE_SHIM_RELATIVE_PATH);
+    const onboardCommandPath = path.join(targetPath, CLAUDE_ONBOARD_COMMAND_RELATIVE_PATH);
+    const lstat = await fs.lstat(absolutePath).catch(() => null);
+    const onboardCommandContent = await fs.readFile(onboardCommandPath, "utf8").catch(() => null);
+    let detectedTarget = null;
+    if (lstat?.isSymbolicLink()) {
+        detectedTarget = await fs.readlink(absolutePath).catch(() => null);
+    }
+    const surfaces = [
+        createSurfaceStatus({
+            kind: "symlink",
+            scope: "repo",
+            targetPath,
+            relativePath: CLAUDE_SHIM_RELATIVE_PATH,
+            present: lstat !== null,
+            state: lstat === null
+                ? "missing"
+                : lstat.isSymbolicLink() && detectedTarget === "AGENTS.md"
+                    ? "ready"
+                    : "misconfigured",
+            summary: lstat === null
+                ? "CLAUDE.md is missing and should be a symlink to AGENTS.md."
+                : lstat.isSymbolicLink() && detectedTarget === "AGENTS.md"
+                    ? "CLAUDE.md is a thin symlink to AGENTS.md."
+                    : "CLAUDE.md exists but is not the expected portable symlink to AGENTS.md.",
+            version: null,
+            expectedTarget: "AGENTS.md",
+            detectedTarget,
+        }),
+        createSurfaceStatus({
+            kind: "command_file",
+            scope: "repo",
+            targetPath,
+            relativePath: CLAUDE_ONBOARD_COMMAND_RELATIVE_PATH,
+            present: onboardCommandContent !== null,
+            state: onboardCommandContent === null
+                ? "missing"
+                : onboardCommandContent === renderClaudeOnboardCommand()
+                    ? "ready"
+                    : "misconfigured",
+            summary: onboardCommandContent === null
+                ? "Claude onboarding handoff is missing and should install `/gdh-onboard` under .claude/commands/."
+                : onboardCommandContent === renderClaudeOnboardCommand()
+                    ? "Claude can discover the managed `/gdh-onboard` handoff command."
+                    : "Claude onboarding handoff exists but no longer matches the expected managed GDH command.",
+            version: null,
+        }),
+    ];
+    if (projectMcp.enabled) {
+        surfaces.push(createSurfaceStatus({
+            kind: "launcher_file",
+            scope: "repo",
+            targetPath: projectMcp.integrationRootPath,
+            relativePath: MCP_LAUNCHER_RELATIVE_PATH,
+            present: projectMcp.launcherFile.present,
+            state: projectMcp.launcherFile.state,
+            summary: projectMcp.launcherFile.summary,
+            version: GDH_MCP_LAUNCHER_VERSION,
+        }), createSurfaceStatus({
+            kind: "mcp_file",
+            scope: "repo",
+            targetPath: projectMcp.integrationRootPath,
+            relativePath: PROJECT_MCP_RELATIVE_PATH,
+            present: projectMcp.projectFile.present,
+            state: projectMcp.projectFile.state,
+            summary: projectMcp.projectFile.state === "ready"
+                ? "Claude can use the managed project MCP configuration in .mcp.json."
+                : projectMcp.projectFile.summary,
+            version: null,
+        }));
+    }
+    return createAgentStatus("claude", guidance, surfaces);
+}
+async function inspectCursorAdapter(targetPath, guidance, projectMcp) {
+    const absolutePath = path.join(targetPath, CURSOR_RULE_RELATIVE_PATH);
+    const onboardSkillPath = path.join(targetPath, CURSOR_ONBOARD_SKILL_RELATIVE_PATH);
+    const content = await fs.readFile(absolutePath, "utf8").catch(() => null);
+    const onboardSkillContent = await fs.readFile(onboardSkillPath, "utf8").catch(() => null);
+    const expectedContent = renderCursorRule();
+    const version = readCursorRuleVersion(content);
+    const surfaces = [
+        createSurfaceStatus({
+            kind: "rule_file",
+            scope: "repo",
+            targetPath,
+            relativePath: CURSOR_RULE_RELATIVE_PATH,
+            present: content !== null,
+            state: content === null
+                ? "missing"
+                : content === expectedContent
+                    ? "ready"
+                    : "misconfigured",
+            summary: content === null
+                ? "Cursor reinforcement is missing and should point back to AGENTS.md."
+                : content === expectedContent
+                    ? "Cursor has a thin always-on rule that points back to the canonical GDH guidance chain."
+                    : "Cursor reinforcement exists but no longer matches the expected managed GDH rule.",
+            version,
+        }),
+        createSurfaceStatus({
+            kind: "skill_file",
+            scope: "repo",
+            targetPath,
+            relativePath: CURSOR_ONBOARD_SKILL_RELATIVE_PATH,
+            present: onboardSkillContent !== null,
+            state: onboardSkillContent === null
+                ? "missing"
+                : onboardSkillContent === renderCursorOnboardSkill()
+                    ? "ready"
+                    : "misconfigured",
+            summary: onboardSkillContent === null
+                ? "Cursor onboarding handoff is missing and should install `/gdh-onboard` under .cursor/skills/."
+                : onboardSkillContent === renderCursorOnboardSkill()
+                    ? "Cursor can discover the managed `/gdh-onboard` handoff skill."
+                    : "Cursor onboarding handoff exists but no longer matches the expected managed GDH skill.",
+            version: null,
+        }),
+    ];
+    if (projectMcp.enabled) {
+        surfaces.push(createSurfaceStatus({
+            kind: "launcher_file",
+            scope: "repo",
+            targetPath: projectMcp.integrationRootPath,
+            relativePath: MCP_LAUNCHER_RELATIVE_PATH,
+            present: projectMcp.launcherFile.present,
+            state: projectMcp.launcherFile.state,
+            summary: projectMcp.launcherFile.summary,
+            version: GDH_MCP_LAUNCHER_VERSION,
+        }), createSurfaceStatus({
+            kind: "mcp_file",
+            scope: "repo",
+            targetPath: projectMcp.integrationRootPath,
+            relativePath: CURSOR_MCP_RELATIVE_PATH,
+            present: projectMcp.cursorFile.present,
+            state: projectMcp.cursorFile.state,
+            summary: projectMcp.cursorFile.summary,
+            version: null,
+        }));
+    }
+    return createAgentStatus("cursor", guidance, surfaces);
+}
+function createAgentStatus(agent, guidance, surfaces) {
+    const state = !hasReadyVisibilityChain(guidance)
+        ? "visibility_broken"
+        : surfaces.every((surface) => surface.state === "ready")
+            ? "ready"
+            : surfaces.some((surface) => surface.state === "misconfigured")
+                ? "misconfigured"
+                : "needs_install";
+    return {
+        agent,
+        state,
+        summary: summarizeAgentState(agent, state),
+        surfaces,
+    };
+}
+function hasReadyVisibilityChain(guidance) {
+    return (guidance.agentContract.present &&
+        guidance.agentContract.hasManagedBlock &&
+        guidance.agentContract.version === GDH_AGENT_CONTRACT_VERSION &&
+        guidance.agentContract.canonicalIndexRelativePath !== null &&
+        guidance.index.present &&
+        guidance.index.version !== null &&
+        guidance.units.count > 0);
+}
+function summarizeAgentState(agent, state) {
+    const displayName = agent[0]?.toUpperCase() + agent.slice(1);
+    switch (state) {
+        case "ready":
+            return `${displayName} reinforcement is aligned with the canonical GDH visibility chain and current MCP install model.`;
+        case "needs_install":
+            return `${displayName} still needs install or repair work to align with the current GDH visibility chain and MCP install model.`;
+        case "misconfigured":
+            return `${displayName} reinforcement exists but does not match the expected managed GDH adapter shape.`;
+        case "visibility_broken":
+            return `${displayName} cannot be trusted until the canonical GDH visibility chain is repaired.`;
+    }
+}
+function createSurfaceStatus(input) {
+    return {
+        kind: input.kind,
+        scope: input.scope,
+        relativePath: input.relativePath,
+        absolutePath: input.absolutePath ??
+            (input.relativePath === null ? null : path.join(input.targetPath, input.relativePath)),
+        present: input.present,
+        state: input.state,
+        summary: input.summary,
+        version: input.version,
+        expectedTarget: input.expectedTarget ?? null,
+        detectedTarget: input.detectedTarget ?? null,
+    };
+}
+function normalizeRequestedAgents(agents) {
+    if (!agents || agents.length === 0) {
+        return SUPPORTED_AGENTS;
+    }
+    return [...new Set(agents)];
+}
+function resolveIntegrationRootPath(targetPath, integrationRootPath) {
+    return path.resolve(integrationRootPath ?? targetPath);
+}
+async function planInstallActions(targetPath, adapters, requestedAgents, options) {
+    const projectMcp = await inspectProjectMcpSupport(targetPath, {
+        includeUserLocal: true,
+        integrationRootPath: options.integrationRootPath,
+    });
+    const actions = [];
+    const effectiveDevRepoPath = options.devRepoPath ?? resolveCurrentGdhInstall(import.meta.url).defaultDevRepoPath;
+    if (options.user) {
+        if (requestedAgents.includes("codex")) {
+            actions.push(...planCodexUserInstallActions(targetPath, projectMcp, options.integrationRootPath));
+        }
+        return dedupeInstallActions(actions);
+    }
+    actions.push(...planSharedRepoInstallActions(targetPath, projectMcp, requestedAgents[0] ?? "claude", effectiveDevRepoPath, options.integrationRootPath));
+    for (const adapter of adapters) {
+        if (!requestedAgents.includes(adapter.agent)) {
+            continue;
+        }
+        if (adapter.agent === "codex") {
+            actions.push(...planCodexRepoInstallActions(targetPath, adapter));
+            continue;
+        }
+        if (adapter.agent === "claude") {
+            actions.push(...planClaudeInstallActions(targetPath, adapter));
+            continue;
+        }
+        if (adapter.agent === "cursor") {
+            actions.push(...planCursorInstallActions(targetPath, adapter));
+        }
+    }
+    return dedupeInstallActions(actions);
+}
+function planSharedRepoInstallActions(targetPath, projectMcp, agent, effectiveDevRepoPath, integrationRootPath) {
+    if (!projectMcp.enabled) {
+        return [];
+    }
+    const actions = [];
+    if (projectMcp.launcherFile.state !== "ready") {
+        actions.push(createInstallAction({
+            agent,
+            kind: "write_file",
+            scope: "repo",
+            targetPath: integrationRootPath,
+            relativePath: MCP_LAUNCHER_RELATIVE_PATH,
+            state: "planned",
+            mode: projectMcp.launcherFile.present ? "replace" : "create",
+            summary: projectMcp.launcherFile.present
+                ? "Replace the managed GDH MCP launcher with the current launcher content."
+                : "Create the managed GDH MCP launcher under .gdh/bin/.",
+            version: GDH_MCP_LAUNCHER_VERSION,
+            content: projectMcp.launcherContent,
+        }));
+    }
+    if (projectMcp.projectFile.state !== "ready") {
+        actions.push(createInstallAction({
+            agent,
+            kind: "write_file",
+            scope: "repo",
+            targetPath: integrationRootPath,
+            relativePath: PROJECT_MCP_RELATIVE_PATH,
+            state: "planned",
+            mode: projectMcp.projectFile.present ? "replace" : "create",
+            summary: projectMcp.projectFile.present
+                ? "Replace the managed `gdh` MCP entry in .mcp.json while preserving any non-GDH servers."
+                : "Create .mcp.json with the managed `gdh` MCP entry.",
+            content: renderManagedMcpConfig(path.join(integrationRootPath, PROJECT_MCP_RELATIVE_PATH), buildManagedMcpServerEntry({
+                targetPath,
+                integrationRootPath,
+                launcherPathForConfig: `./${normalizePathForJson(MCP_LAUNCHER_RELATIVE_PATH)}`,
+            })),
+        }));
+    }
+    if (projectMcp.cursorFile.state !== "ready") {
+        actions.push(createInstallAction({
+            agent,
+            kind: "write_file",
+            scope: "repo",
+            targetPath: integrationRootPath,
+            relativePath: CURSOR_MCP_RELATIVE_PATH,
+            state: "planned",
+            mode: projectMcp.cursorFile.present ? "replace" : "create",
+            summary: projectMcp.cursorFile.present
+                ? "Replace the managed `gdh` MCP entry in .cursor/mcp.json while preserving any non-GDH servers."
+                : "Create .cursor/mcp.json with the managed `gdh` MCP entry.",
+            content: renderManagedMcpConfig(path.join(integrationRootPath, CURSOR_MCP_RELATIVE_PATH), buildManagedMcpServerEntry({
+                targetPath,
+                integrationRootPath,
+                launcherPathForConfig: `./${normalizePathForJson(MCP_LAUNCHER_RELATIVE_PATH)}`,
+            })),
+        }));
+    }
+    if (projectMcp.localPathHints.gdhDevRepoPath !== effectiveDevRepoPath) {
+        actions.push(createInstallAction({
+            agent,
+            kind: "write_file",
+            scope: "repo",
+            targetPath: integrationRootPath,
+            relativePath: LOCAL_PATH_HINTS_RELATIVE_PATH,
+            state: "planned",
+            mode: projectMcp.localPathHints.gdhDevRepoPath === null ? "create" : "replace",
+            summary: effectiveDevRepoPath === null
+                ? "Clear the stored GDH source-checkout override so the managed MCP launcher resolves the packaged GDH install from PATH."
+                : "Record the current GDH source-checkout path in machine-local target hints so the managed MCP launcher can bootstrap from this checkout.",
+            content: renderLocalPathHints({
+                sourceTargets: projectMcp.localPathHints.sourceTargets,
+                gdhDevRepoPath: effectiveDevRepoPath,
+                godotEditorBinPath: projectMcp.localPathHints.godotEditorBinPath,
+            }),
+            command: [
+                "write_local_hints",
+                JSON.stringify({
+                    targetPath: integrationRootPath,
+                    gdhDevRepoPath: effectiveDevRepoPath,
+                }),
+            ],
+        }));
+    }
+    return actions;
+}
+function planCodexRepoInstallActions(targetPath, adapter) {
+    const actions = [];
+    const codexSkillSurface = adapter.surfaces.find((surface) => surface.relativePath === CODEX_ONBOARD_SKILL_RELATIVE_PATH);
+    if (!codexSkillSurface || codexSkillSurface.state === "ready") {
+        actions.push(createInstallAction({
+            agent: "codex",
+            kind: "write_file",
+            scope: "repo",
+            targetPath,
+            relativePath: CODEX_ONBOARD_SKILL_RELATIVE_PATH,
+            state: "unchanged",
+            mode: "unchanged",
+            summary: "The managed Codex `/gdh-onboard` skill already matches the expected GDH content.",
+            content: renderCodexOnboardSkill(),
+        }));
+    }
+    else {
+        actions.push(createInstallAction({
+            agent: "codex",
+            kind: "write_file",
+            scope: "repo",
+            targetPath,
+            relativePath: CODEX_ONBOARD_SKILL_RELATIVE_PATH,
+            state: "planned",
+            mode: codexSkillSurface.present ? "replace" : "create",
+            summary: codexSkillSurface.present
+                ? "Replace the existing Codex `/gdh-onboard` skill with the managed GDH skill."
+                : "Create the managed Codex `/gdh-onboard` skill.",
+            content: renderCodexOnboardSkill(),
+        }));
+    }
+    return actions;
+}
+function planCodexUserInstallActions(targetPath, projectMcp, integrationRootPath) {
+    if (!projectMcp.enabled || projectMcp.codexServerName === null) {
+        return [];
+    }
+    const expectedLauncherPath = path.join(integrationRootPath, MCP_LAUNCHER_RELATIVE_PATH);
+    const codexArgs = buildManagedLauncherInvocationArgs({
+        targetPath,
+        integrationRootPath,
+        launcherPath: expectedLauncherPath,
+        useAbsoluteTargetPath: true,
+    });
+    const actions = [];
+    if (projectMcp.codexRegistration.present) {
+        actions.push(createInstallAction({
+            agent: "codex",
+            kind: "run_command",
+            scope: "user",
+            targetPath,
+            relativePath: null,
+            absolutePath: projectMcp.codexConfigPath,
+            state: "planned",
+            mode: "replace",
+            summary: `Remove the existing Codex MCP registration \`${projectMcp.codexServerName}\` before re-registering it with the managed GDH launcher.`,
+            command: ["codex", "mcp", "remove", projectMcp.codexServerName],
+        }));
+    }
+    actions.push(createInstallAction({
+        agent: "codex",
+        kind: "run_command",
+        scope: "user",
+        targetPath,
+        relativePath: null,
+        absolutePath: projectMcp.codexConfigPath,
+        state: "planned",
+        mode: projectMcp.codexRegistration.present ? "replace" : "create",
+        summary: `Register the managed GDH launcher with Codex as \`${projectMcp.codexServerName}\`.`,
+        command: [
+            "codex",
+            "mcp",
+            "add",
+            projectMcp.codexServerName,
+            "--",
+            "node",
+            ...codexArgs,
+        ],
+    }));
+    return actions;
+}
+function planClaudeInstallActions(targetPath, adapter) {
+    const actions = [];
+    const claudeSurface = adapter.surfaces.find((surface) => surface.relativePath === CLAUDE_SHIM_RELATIVE_PATH);
+    if (!claudeSurface || claudeSurface.state === "ready") {
+        actions.push(createInstallAction({
+            agent: "claude",
+            kind: "ensure_symlink",
+            scope: "repo",
+            targetPath,
+            relativePath: CLAUDE_SHIM_RELATIVE_PATH,
+            state: "unchanged",
+            mode: "unchanged",
+            summary: "CLAUDE.md already points to AGENTS.md through the expected portable symlink.",
+            expectedTarget: "AGENTS.md",
+        }));
+    }
+    else {
+        actions.push(createInstallAction({
+            agent: "claude",
+            kind: "ensure_symlink",
+            scope: "repo",
+            targetPath,
+            relativePath: CLAUDE_SHIM_RELATIVE_PATH,
+            state: "planned",
+            mode: claudeSurface.present ? "replace" : "create",
+            summary: claudeSurface.present
+                ? "Replace the existing CLAUDE.md surface with a symlink to AGENTS.md."
+                : "Create CLAUDE.md as a symlink to AGENTS.md.",
+            expectedTarget: "AGENTS.md",
+        }));
+    }
+    const claudeCommandSurface = adapter.surfaces.find((surface) => surface.relativePath === CLAUDE_ONBOARD_COMMAND_RELATIVE_PATH);
+    if (!claudeCommandSurface || claudeCommandSurface.state === "ready") {
+        actions.push(createInstallAction({
+            agent: "claude",
+            kind: "write_file",
+            scope: "repo",
+            targetPath,
+            relativePath: CLAUDE_ONBOARD_COMMAND_RELATIVE_PATH,
+            state: "unchanged",
+            mode: "unchanged",
+            summary: "The managed Claude `/gdh-onboard` command already matches the expected GDH content.",
+            content: renderClaudeOnboardCommand(),
+        }));
+    }
+    else {
+        actions.push(createInstallAction({
+            agent: "claude",
+            kind: "write_file",
+            scope: "repo",
+            targetPath,
+            relativePath: CLAUDE_ONBOARD_COMMAND_RELATIVE_PATH,
+            state: "planned",
+            mode: claudeCommandSurface.present ? "replace" : "create",
+            summary: claudeCommandSurface.present
+                ? "Replace the existing Claude `/gdh-onboard` command with the managed GDH command."
+                : "Create the managed Claude `/gdh-onboard` command.",
+            content: renderClaudeOnboardCommand(),
+        }));
+    }
+    return actions;
+}
+function planCursorInstallActions(targetPath, adapter) {
+    const actions = [];
+    const cursorRuleSurface = adapter.surfaces.find((surface) => surface.relativePath === CURSOR_RULE_RELATIVE_PATH);
+    if (!cursorRuleSurface || cursorRuleSurface.state === "ready") {
+        actions.push(createInstallAction({
+            agent: "cursor",
+            kind: "write_file",
+            scope: "repo",
+            targetPath,
+            relativePath: CURSOR_RULE_RELATIVE_PATH,
+            state: "unchanged",
+            mode: "unchanged",
+            summary: "The managed Cursor reinforcement rule already matches the expected GDH content.",
+            version: GDH_CURSOR_RULE_VERSION,
+            content: renderCursorRule(),
+        }));
+    }
+    else {
+        actions.push(createInstallAction({
+            agent: "cursor",
+            kind: "write_file",
+            scope: "repo",
+            targetPath,
+            relativePath: CURSOR_RULE_RELATIVE_PATH,
+            state: "planned",
+            mode: cursorRuleSurface.present ? "replace" : "create",
+            summary: cursorRuleSurface.present
+                ? "Replace the existing Cursor reinforcement rule with the managed GDH rule."
+                : "Create the managed Cursor reinforcement rule that points back to AGENTS.md.",
+            version: GDH_CURSOR_RULE_VERSION,
+            content: renderCursorRule(),
+        }));
+    }
+    const cursorSkillSurface = adapter.surfaces.find((surface) => surface.relativePath === CURSOR_ONBOARD_SKILL_RELATIVE_PATH);
+    if (!cursorSkillSurface || cursorSkillSurface.state === "ready") {
+        actions.push(createInstallAction({
+            agent: "cursor",
+            kind: "write_file",
+            scope: "repo",
+            targetPath,
+            relativePath: CURSOR_ONBOARD_SKILL_RELATIVE_PATH,
+            state: "unchanged",
+            mode: "unchanged",
+            summary: "The managed Cursor `/gdh-onboard` skill already matches the expected GDH content.",
+            content: renderCursorOnboardSkill(),
+        }));
+    }
+    else {
+        actions.push(createInstallAction({
+            agent: "cursor",
+            kind: "write_file",
+            scope: "repo",
+            targetPath,
+            relativePath: CURSOR_ONBOARD_SKILL_RELATIVE_PATH,
+            state: "planned",
+            mode: cursorSkillSurface.present ? "replace" : "create",
+            summary: cursorSkillSurface.present
+                ? "Replace the existing Cursor `/gdh-onboard` skill with the managed GDH skill."
+                : "Create the managed Cursor `/gdh-onboard` skill.",
+            content: renderCursorOnboardSkill(),
+        }));
+    }
+    return actions;
+}
+function dedupeInstallActions(actions) {
+    const seen = new Set();
+    const deduped = [];
+    for (const action of actions) {
+        const key = [
+            action.kind,
+            action.scope,
+            action.absolutePath ?? "",
+            action.relativePath ?? "",
+            action.mode,
+            action.expectedTarget ?? "",
+            action.content ?? "",
+            JSON.stringify(action.command ?? []),
+        ].join("::");
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        deduped.push(action);
+    }
+    return deduped;
+}
+function createInstallAction(input) {
+    return {
+        agent: input.agent,
+        kind: input.kind,
+        scope: input.scope,
+        relativePath: input.relativePath,
+        absolutePath: input.absolutePath ??
+            (input.relativePath === null ? null : path.join(input.targetPath, input.relativePath)),
+        state: input.state,
+        mode: input.mode,
+        summary: input.summary,
+        version: input.version ?? null,
+        expectedTarget: input.expectedTarget ?? null,
+        content: input.content ?? null,
+        command: input.command ?? null,
+    };
+}
+async function applySymlinkAction(action) {
+    if (action.absolutePath === null) {
+        throw new Error("Symlink install action is missing an absolute path.");
+    }
+    await fs.rm(action.absolutePath, { force: true });
+    await fs.symlink(action.expectedTarget ?? "AGENTS.md", action.absolutePath);
+}
+async function applyWriteFileAction(action) {
+    if (action.absolutePath === null) {
+        throw new Error("Write-file install action is missing an absolute path.");
+    }
+    await fs.mkdir(path.dirname(action.absolutePath), { recursive: true });
+    await fs.writeFile(action.absolutePath, action.content ?? renderCursorRule(), "utf8");
+}
+async function applyRunCommandAction(action) {
+    const [command, ...args] = action.command ?? [];
+    if (!command) {
+        throw new Error("Run-command install action is missing a command.");
+    }
+    await execFile(command, args, {
+        cwd: path.resolve("."),
+        env: process.env,
+    });
+}
+async function applyLocalHintsAction(action) {
+    const payload = action.command?.[1];
+    if (!payload) {
+        throw new Error("Local-path-hints action is missing its payload.");
+    }
+    const parsed = JSON.parse(payload);
+    if (typeof parsed.targetPath !== "string") {
+        throw new Error("Local-path-hints action payload is missing a target path.");
+    }
+    await writeLocalPathHints(parsed.targetPath, {
+        gdhDevRepoPath: typeof parsed.gdhDevRepoPath === "string" ? parsed.gdhDevRepoPath : null,
+    });
+}
+function readCursorRuleVersion(content) {
+    if (content === null) {
+        return null;
+    }
+    const match = content.match(/<!-- GDH CURSOR RULE VERSION: (\d+) -->/);
+    if (!match?.[1]) {
+        return null;
+    }
+    return Number.parseInt(match[1], 10);
+}
+function resolveProjectMcpEnabled(projectConfig) {
+    if (projectConfig === null) {
+        return false;
+    }
+    return projectConfig.mcp.enabled;
+}
+function createCodexServerName(projectKeySeed) {
+    return `gdh-${projectKeySeed}`;
+}
+function renderManagedMcpLauncher() {
+    return [
+        "#!/usr/bin/env node",
+        `// GDH MCP launcher v${GDH_MCP_LAUNCHER_VERSION}`,
+        'import fs from "node:fs";',
+        'import path from "node:path";',
+        'import { spawnSync } from "node:child_process";',
+        'import { fileURLToPath } from "node:url";',
+        "",
+        "const launcherPath = fileURLToPath(import.meta.url);",
+        'const integrationRootPath = path.resolve(path.dirname(launcherPath), "../..");',
+        'const targetOptionIndex = process.argv.indexOf("--target");',
+        "const configuredTargetPath =",
+        '  targetOptionIndex >= 0 && typeof process.argv[targetOptionIndex + 1] === "string"',
+        "    ? process.argv[targetOptionIndex + 1]",
+        "    : null;",
+        "const targetPath = configuredTargetPath",
+        "  ? path.resolve(integrationRootPath, configuredTargetPath)",
+        "  : integrationRootPath;",
+        'const hintsPath = path.join(integrationRootPath, ".gdh-state", "local-paths.json");',
+        "",
+        "let gdhDevRepoPath = null;",
+        "try {",
+        '  const raw = fs.readFileSync(hintsPath, "utf8");',
+        "  const parsed = JSON.parse(raw);",
+        '  if (typeof parsed.gdhDevRepoPath === "string" && parsed.gdhDevRepoPath.length > 0) {',
+        "    gdhDevRepoPath = parsed.gdhDevRepoPath;",
+        "  }",
+        "} catch {}",
+        "",
+        "const effectiveDevRepoPath = process.env.GDH_DEV_REPO?.trim() || gdhDevRepoPath;",
+        "if (effectiveDevRepoPath) {",
+        '  const devCliEntryPath = path.join(effectiveDevRepoPath, "packages/cli/dist/cli.js");',
+        "  if (fs.existsSync(devCliEntryPath)) {",
+        '    const result = spawnSync(process.execPath, [devCliEntryPath, "mcp", "serve", "--target", targetPath], { stdio: "inherit" });',
+        "    process.exit(result.status ?? 1);",
+        "  }",
+        "}",
+        "",
+        'const result = spawnSync("gdh", ["mcp", "serve", "--target", targetPath], { stdio: "inherit" });',
+        'if (result.error && result.error.code === "ENOENT") {',
+        '  console.error("GDH MCP launcher could not find a usable GDH server. Install `gdh` on PATH or run `gdh adapters install <target> --dev-repo <path-to-gdh>`.");',
+        "  process.exit(1);",
+        "}",
+        "process.exit(result.status ?? 1);",
+        "",
+    ].join("\n");
+}
+function buildManagedMcpServerEntry(input) {
+    return {
+        type: "stdio",
+        command: "node",
+        args: buildManagedLauncherInvocationArgs({
+            targetPath: input.targetPath,
+            integrationRootPath: input.integrationRootPath,
+            launcherPath: input.launcherPathForConfig,
+            useAbsoluteTargetPath: false,
+        }),
+    };
+}
+function getManagedMcpServerEntry(jsonObject) {
+    const servers = isObjectRecord(jsonObject["mcpServers"]) ? jsonObject["mcpServers"] : null;
+    if (servers === null) {
+        return null;
+    }
+    const entry = servers[GDH_MCP_SERVER_NAME];
+    return isObjectRecord(entry) ? entry : null;
+}
+function isMatchingManagedMcpServerEntry(entry, expectedEntry) {
+    if (entry === null) {
+        return false;
+    }
+    return (JSON.stringify(normalizeJson(entry)) ===
+        JSON.stringify(normalizeJson(expectedEntry)));
+}
+function renderManagedMcpConfig(absolutePath, managedEntry) {
+    const existing = readExistingMcpConfig(absolutePath);
+    const next = {
+        ...existing,
+        mcpServers: {
+            ...(isObjectRecord(existing["mcpServers"]) ? existing["mcpServers"] : {}),
+            [GDH_MCP_SERVER_NAME]: managedEntry,
+        },
+    };
+    return `${JSON.stringify(next, null, 2)}\n`;
+}
+function readExistingMcpConfig(absolutePath) {
+    if (!fsSync.existsSync(absolutePath)) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(fsSync.readFileSync(absolutePath, "utf8"));
+        return isObjectRecord(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function normalizeJson(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => normalizeJson(entry));
+    }
+    if (isObjectRecord(value)) {
+        const next = {};
+        for (const key of Object.keys(value).sort()) {
+            next[key] = normalizeJson(value[key]);
+        }
+        return next;
+    }
+    return value;
+}
+function buildManagedLauncherInvocationArgs(input) {
+    const args = [input.launcherPath];
+    const resolvedTargetPath = path.resolve(input.targetPath);
+    const resolvedIntegrationRootPath = path.resolve(input.integrationRootPath);
+    if (resolvedTargetPath === resolvedIntegrationRootPath) {
+        return args;
+    }
+    const targetValue = input.useAbsoluteTargetPath
+        ? resolvedTargetPath
+        : `./${normalizePathForJson(path.relative(resolvedIntegrationRootPath, resolvedTargetPath))}`;
+    return [...args, "--target", targetValue];
+}
+function normalizePathForJson(value) {
+    return value.split(path.sep).join("/");
+}
+function isObjectRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function renderLocalPathHints(hints) {
+    return `${JSON.stringify(hints, null, 2)}\n`;
+}
+async function readLocalPathHints(targetPath) {
+    const hintsPath = path.join(targetPath, LOCAL_PATH_HINTS_RELATIVE_PATH);
+    const raw = await fs.readFile(hintsPath, "utf8").catch(() => null);
+    if (raw === null) {
+        return {
+            sourceTargets: [],
+            gdhDevRepoPath: null,
+            godotEditorBinPath: null,
+        };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return {
+            sourceTargets: Array.isArray(parsed.sourceTargets)
+                ? parsed.sourceTargets.filter((entry) => typeof entry === "string")
+                : [],
+            gdhDevRepoPath: typeof parsed.gdhDevRepoPath === "string" ? parsed.gdhDevRepoPath : null,
+            godotEditorBinPath: typeof parsed.godotEditorBinPath === "string" ? parsed.godotEditorBinPath : null,
+        };
+    }
+    catch {
+        return {
+            sourceTargets: [],
+            gdhDevRepoPath: null,
+            godotEditorBinPath: null,
+        };
+    }
+}
+async function writeLocalPathHints(targetPath, input) {
+    const current = await readLocalPathHints(targetPath);
+    const next = {
+        sourceTargets: current.sourceTargets,
+        gdhDevRepoPath: input.gdhDevRepoPath,
+        godotEditorBinPath: current.godotEditorBinPath,
+    };
+    const absolutePath = path.join(targetPath, LOCAL_PATH_HINTS_RELATIVE_PATH);
+    await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+    await fs.writeFile(absolutePath, renderLocalPathHints(next), "utf8");
+}
+async function executableExistsOnPath(commandName) {
+    const pathValue = process.env["PATH"];
+    if (!pathValue) {
+        return false;
+    }
+    const extensions = process.platform === "win32"
+        ? (process.env["PATHEXT"]?.split(";") ?? [".exe", ".cmd", ".bat"])
+        : [""];
+    for (const segment of pathValue.split(path.delimiter)) {
+        for (const extension of extensions) {
+            const candidate = path.join(segment, `${commandName}${extension}`);
+            if (await fileExists(candidate)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+async function fileExists(filePath) {
+    return fs
+        .access(filePath)
+        .then(() => true)
+        .catch(() => false);
+}
+async function listCodexMcpServers() {
+    try {
+        const result = await execFile("codex", ["mcp", "list", "--json"], {
+            cwd: path.resolve("."),
+            env: process.env,
+        });
+        const parsed = JSON.parse(result.stdout);
+        if (!Array.isArray(parsed)) {
+            return { state: "unavailable" };
+        }
+        return {
+            state: "available",
+            servers: parsed
+                .filter((entry) => isObjectRecord(entry))
+                .map((entry) => {
+                const transport = isObjectRecord(entry["transport"])
+                    ? {
+                        ...(typeof entry["transport"]["type"] === "string"
+                            ? { type: entry["transport"]["type"] }
+                            : {}),
+                        ...(typeof entry["transport"]["command"] === "string"
+                            ? { command: entry["transport"]["command"] }
+                            : {}),
+                        ...(Array.isArray(entry["transport"]["args"])
+                            ? {
+                                args: entry["transport"]["args"].filter((value) => typeof value === "string"),
+                            }
+                            : {}),
+                    }
+                    : null;
+                return {
+                    name: typeof entry["name"] === "string" ? entry["name"] : "",
+                    transport,
+                };
+            }),
+        };
+    }
+    catch {
+        return { state: "unavailable" };
+    }
+}
+function isMatchingCodexRegistration(registration, input) {
+    const expectedArgs = buildManagedLauncherInvocationArgs({
+        targetPath: input.targetPath,
+        integrationRootPath: input.integrationRootPath,
+        launcherPath: input.launcherPath,
+        useAbsoluteTargetPath: true,
+    });
+    return (registration.transport?.type === "stdio" &&
+        registration.transport.command === "node" &&
+        JSON.stringify(registration.transport.args ?? []) === JSON.stringify(expectedArgs));
+}
+async function inspectProjectConfigLifecycleSurface(targetPath) {
+    const relativePath = ".gdh/project.yaml";
+    const content = await fs
+        .readFile(path.join(targetPath, relativePath), "utf8")
+        .catch(() => null);
+    const detectedVersion = readYamlVersionHeader(content);
+    const probes = [
+        createVersionProbe({
+            targetPath,
+            relativePath,
+            present: content !== null,
+            expectedVersion: GDH_PROJECT_CONFIG_VERSION,
+            detectedVersion,
+        }),
+    ];
+    if (content === null) {
+        return createLifecycleSurfaceStatus({
+            surface: "project_config",
+            management: "project_owned",
+            state: "migration_blocked",
+            summary: "Project lifecycle compatibility is blocked because .gdh/project.yaml is missing.",
+            reasons: ["project_config_missing"],
+            probes,
+            action: {
+                kind: "manual_review",
+                summary: "Run `gdh setup` before attempting project-surface migration.",
+                command: ["gdh", "setup", targetPath],
+                autoApplicable: false,
+            },
+        });
+    }
+    if (detectedVersion === GDH_PROJECT_CONFIG_VERSION) {
+        return createLifecycleSurfaceStatus({
+            surface: "project_config",
+            management: "project_owned",
+            state: "compatible",
+            summary: "Project config matches the current GDH schema version.",
+            reasons: [],
+            probes,
+            action: null,
+        });
+    }
+    if (detectedVersion !== null && detectedVersion < GDH_PROJECT_CONFIG_VERSION) {
+        return createLifecycleSurfaceStatus({
+            surface: "project_config",
+            management: "project_owned",
+            state: "migration_available",
+            summary: "Project config uses an older GDH schema and can be normalized through the migration flow.",
+            reasons: ["project_config_version_behind"],
+            probes,
+            action: {
+                kind: "apply_migration",
+                summary: "Run GDH migrate to rewrite the project config to the current schema.",
+                command: ["gdh", "migrate", targetPath],
+                autoApplicable: true,
+            },
+        });
+    }
+    return createLifecycleSurfaceStatus({
+        surface: "project_config",
+        management: "project_owned",
+        state: "compatibility_degraded",
+        summary: "Project config exists, but its version marker is missing or newer than this GDH build understands.",
+        reasons: ["project_config_version_unrecognized"],
+        probes,
+        action: {
+            kind: "manual_review",
+            summary: "Inspect .gdh/project.yaml before applying automated migration or repair.",
+            command: ["gdh", "migrate", targetPath],
+            autoApplicable: false,
+        },
+    });
+}
+async function inspectRunConfigurationLifecycleSurface(targetPath) {
+    return inspectYamlSurfaceDirectory({
+        targetPath,
+        surface: "run_configuration_schema",
+        management: "project_owned",
+        expectedVersion: GDH_RECIPE_SCHEMA_VERSION,
+        currentRelativeDirectory: ".gdh/run-configurations",
+        legacyRelativeDirectory: ".gdh/recipes",
+        emptySummary: "No run configurations are defined yet for this target.",
+        compatibleSummary: "Run configurations match the current GDH schema version.",
+        versionBehindReason: "run_configuration_version_behind",
+        missingVersionReason: "run_configuration_version_unrecognized",
+        conflictReason: "run_configuration_directory_conflict",
+        migrationSummary: "Run configurations use a legacy directory or older schema and can be normalized through the migration flow.",
+    });
+}
+async function inspectVerificationScenarioLifecycleSurface(targetPath) {
+    return inspectYamlSurfaceDirectory({
+        targetPath,
+        surface: "verification_scenario_schema",
+        management: "project_owned",
+        expectedVersion: GDH_SCENARIO_SCHEMA_VERSION,
+        currentRelativeDirectory: ".gdh/verification-scenarios",
+        legacyRelativeDirectory: ".gdh/scenarios",
+        emptySummary: "No verification scenarios are defined yet for this target.",
+        compatibleSummary: "Verification scenarios match the current GDH schema version.",
+        versionBehindReason: "verification_scenario_version_behind",
+        missingVersionReason: "verification_scenario_version_unrecognized",
+        conflictReason: "verification_scenario_directory_conflict",
+        migrationSummary: "Verification scenarios use a legacy directory or older schema and can be normalized through the migration flow.",
+    });
+}
+async function inspectRulesLifecycleSurface(targetPath) {
+    const relativePath = ".gdh/rules.yaml";
+    const content = await fs
+        .readFile(path.join(targetPath, relativePath), "utf8")
+        .catch(() => null);
+    const detectedVersion = readYamlVersionHeader(content);
+    const probes = [
+        createVersionProbe({
+            targetPath,
+            relativePath,
+            present: content !== null,
+            expectedVersion: GDH_RULES_SCHEMA_VERSION,
+            detectedVersion,
+        }),
+    ];
+    if (content === null) {
+        return createLifecycleSurfaceStatus({
+            surface: "rules_schema",
+            management: "project_owned",
+            state: "migration_needed",
+            summary: "Rules are missing from .gdh/rules.yaml, so done-policy and guidance enforcement are incomplete.",
+            reasons: ["rules_missing"],
+            probes,
+            action: {
+                kind: "apply_migration",
+                summary: "Run GDH migrate to create the default rules file for this target.",
+                command: ["gdh", "migrate", targetPath],
+                autoApplicable: true,
+            },
+        });
+    }
+    if (detectedVersion === GDH_RULES_SCHEMA_VERSION) {
+        return createLifecycleSurfaceStatus({
+            surface: "rules_schema",
+            management: "project_owned",
+            state: "compatible",
+            summary: "Rules file matches the current GDH schema version.",
+            reasons: [],
+            probes,
+            action: null,
+        });
+    }
+    return createLifecycleSurfaceStatus({
+        surface: "rules_schema",
+        management: "project_owned",
+        state: "compatibility_degraded",
+        summary: "Rules file exists, but its version marker is missing or no longer matches this GDH build.",
+        reasons: ["rules_version_unrecognized"],
+        probes,
+        action: {
+            kind: "manual_review",
+            summary: "Inspect .gdh/rules.yaml manually before overwriting project-specific rule content.",
+            command: ["gdh", "migrate", targetPath],
+            autoApplicable: false,
+        },
+    });
+}
+function inspectAgentContractLifecycleSurface(targetPath, guidanceStatus) {
+    const status = guidanceStatus.agentContract;
+    const probes = [
+        createVersionProbe({
+            targetPath,
+            relativePath: status.relativePath,
+            present: status.present,
+            expectedVersion: GDH_AGENT_CONTRACT_VERSION,
+            detectedVersion: status.version,
+        }),
+    ];
+    if (status.present &&
+        status.hasManagedBlock &&
+        status.version === GDH_AGENT_CONTRACT_VERSION &&
+        status.canonicalIndexRelativePath !== null) {
+        return createLifecycleSurfaceStatus({
+            surface: "agent_contract",
+            management: "merge_managed",
+            state: "compatible",
+            summary: "AGENTS.md contains the current managed GDH agent contract block.",
+            reasons: [],
+            probes,
+            action: null,
+        });
+    }
+    return createLifecycleSurfaceStatus({
+        surface: "agent_contract",
+        management: "merge_managed",
+        state: status.present ? "migration_available" : "migration_needed",
+        summary: status.present
+            ? "AGENTS.md is present, but the managed GDH contract block needs to be refreshed."
+            : "AGENTS.md is missing the GDH agent contract.",
+        reasons: status.present
+            ? ["agent_contract_outdated_or_incomplete"]
+            : ["agent_contract_missing"],
+        probes,
+        action: {
+            kind: "apply_migration",
+            summary: "Run GDH migrate to merge or refresh the managed agent contract block.",
+            command: ["gdh", "migrate", targetPath],
+            autoApplicable: true,
+        },
+    });
+}
+async function inspectGuidanceIndexLifecycleSurface(targetPath) {
+    const relativePath = "docs/agent/README.md";
+    const content = await fs
+        .readFile(path.join(targetPath, relativePath), "utf8")
+        .catch(() => null);
+    const detectedVersion = readTaggedVersion(content, /<!-- GDH GUIDANCE INDEX VERSION: (\d+) -->/);
+    const probes = [
+        createVersionProbe({
+            targetPath,
+            relativePath,
+            present: content !== null,
+            expectedVersion: GDH_GUIDANCE_INDEX_VERSION,
+            detectedVersion,
+        }),
+    ];
+    if (content === null) {
+        return createLifecycleSurfaceStatus({
+            surface: "guidance_index",
+            management: "project_owned",
+            state: "migration_needed",
+            summary: "The canonical guidance index is missing from docs/agent/README.md.",
+            reasons: ["guidance_index_missing"],
+            probes,
+            action: {
+                kind: "apply_migration",
+                summary: "Run GDH migrate to create the default guidance index for this target.",
+                command: ["gdh", "migrate", targetPath],
+                autoApplicable: true,
+            },
+        });
+    }
+    if (detectedVersion === GDH_GUIDANCE_INDEX_VERSION) {
+        return createLifecycleSurfaceStatus({
+            surface: "guidance_index",
+            management: "project_owned",
+            state: "compatible",
+            summary: "The canonical guidance index matches the current GDH version marker.",
+            reasons: [],
+            probes,
+            action: null,
+        });
+    }
+    return createLifecycleSurfaceStatus({
+        surface: "guidance_index",
+        management: "project_owned",
+        state: "compatibility_degraded",
+        summary: "The canonical guidance index exists, but its GDH version marker is missing or outdated.",
+        reasons: ["guidance_index_version_unrecognized"],
+        probes,
+        action: {
+            kind: "manual_review",
+            summary: "Inspect docs/agent/README.md before overwriting project-specific guidance content.",
+            command: ["gdh", "migrate", targetPath],
+            autoApplicable: false,
+        },
+    });
+}
+async function inspectGuidanceUnitLifecycleSurface(targetPath, projectConfig) {
+    const expectedUnits = projectConfig === null ? [] : createDefaultGuidanceUnits(projectConfig);
+    const probes = [];
+    for (const unit of expectedUnits) {
+        const content = await fs
+            .readFile(path.join(targetPath, unit.relativePath), "utf8")
+            .catch(() => null);
+        probes.push(createVersionProbe({
+            targetPath,
+            relativePath: unit.relativePath,
+            present: content !== null,
+            expectedVersion: GDH_GUIDANCE_UNIT_VERSION,
+            detectedVersion: readFrontmatterVersion(content),
+        }));
+    }
+    if (probes.length === 0) {
+        return createLifecycleSurfaceStatus({
+            surface: "guidance_unit",
+            management: "project_owned",
+            state: "compatible",
+            summary: "No default guidance units are expected until the target is onboarded.",
+            reasons: [],
+            probes,
+            action: null,
+        });
+    }
+    if (probes.every((probe) => probe.present && probe.detectedVersion === probe.expectedVersion)) {
+        return createLifecycleSurfaceStatus({
+            surface: "guidance_unit",
+            management: "project_owned",
+            state: "compatible",
+            summary: "The default GDH guidance units match the current version markers.",
+            reasons: [],
+            probes,
+            action: null,
+        });
+    }
+    const hasMissing = probes.some((probe) => !probe.present);
+    const hasUnexpectedVersion = probes.some((probe) => probe.present &&
+        probe.expectedVersion !== null &&
+        probe.detectedVersion !== probe.expectedVersion);
+    if (hasMissing && !hasUnexpectedVersion) {
+        return createLifecycleSurfaceStatus({
+            surface: "guidance_unit",
+            management: "project_owned",
+            state: "migration_needed",
+            summary: "One or more default GDH guidance units are missing from docs/agent/.",
+            reasons: ["guidance_unit_missing"],
+            probes,
+            action: {
+                kind: "apply_migration",
+                summary: "Run GDH migrate to create the missing default guidance unit files.",
+                command: ["gdh", "migrate", targetPath],
+                autoApplicable: true,
+            },
+        });
+    }
+    return createLifecycleSurfaceStatus({
+        surface: "guidance_unit",
+        management: "project_owned",
+        state: "compatibility_degraded",
+        summary: "One or more guidance units exist with missing or mismatched version markers and need manual review.",
+        reasons: ["guidance_unit_version_unrecognized"],
+        probes,
+        action: {
+            kind: "manual_review",
+            summary: "Inspect docs/agent/*.md before overwriting project-specific guidance content.",
+            command: ["gdh", "migrate", targetPath],
+            autoApplicable: false,
+        },
+    });
+}
+function inspectMcpManifestLifecycleSurface(targetPath, mcpEnabled, adapterStatus) {
+    if (!mcpEnabled) {
+        return createLifecycleSurfaceStatus({
+            surface: "mcp_manifest",
+            management: "managed",
+            state: "compatible",
+            summary: "Project-scoped MCP is disabled in .gdh/project.yaml for this target.",
+            reasons: [],
+            probes: [],
+            action: null,
+        });
+    }
+    const claudeMcp = findAdapterSurface(adapterStatus, "claude", "mcp_file");
+    const cursorMcp = findAdapterSurface(adapterStatus, "cursor", "mcp_file");
+    const probes = [claudeMcp, cursorMcp]
+        .filter((surface) => surface !== null)
+        .map((surface) => createVersionProbe({
+        targetPath,
+        relativePath: surface.relativePath ?? ".mcp.json",
+        present: surface.present,
+        expectedVersion: null,
+        detectedVersion: surface.present ? surface.version : null,
+    }));
+    const states = [claudeMcp?.state, cursorMcp?.state].filter((state) => state !== undefined);
+    if (states.length > 0 && states.every((state) => state === "ready")) {
+        return createLifecycleSurfaceStatus({
+            surface: "mcp_manifest",
+            management: "managed",
+            state: "compatible",
+            summary: "Project MCP config files are aligned for Claude and Cursor.",
+            reasons: [],
+            probes,
+            action: null,
+        });
+    }
+    return createLifecycleSurfaceStatus({
+        surface: "mcp_manifest",
+        management: "managed",
+        state: states.some((state) => state === "misconfigured")
+            ? "migration_available"
+            : "migration_needed",
+        summary: "Project MCP config files need to be created or refreshed through the adapter install flow.",
+        reasons: states.some((state) => state === "misconfigured")
+            ? ["mcp_manifest_misconfigured"]
+            : ["mcp_manifest_missing"],
+        probes,
+        action: {
+            kind: "run_repair",
+            summary: "Run GDH migrate or adapters install to repair the managed project MCP config files.",
+            command: ["gdh", "adapters", "install", targetPath],
+            autoApplicable: true,
+        },
+    });
+}
+function inspectCursorRuleLifecycleSurface(targetPath, adapterStatus) {
+    const surface = findAdapterSurface(adapterStatus, "cursor", "rule_file");
+    const probes = surface === null
+        ? []
+        : [
+            createVersionProbe({
+                targetPath,
+                relativePath: surface.relativePath ?? CURSOR_RULE_RELATIVE_PATH,
+                present: surface.present,
+                expectedVersion: GDH_CURSOR_RULE_VERSION,
+                detectedVersion: surface.present ? surface.version : null,
+            }),
+        ];
+    if (surface?.state === "ready") {
+        return createLifecycleSurfaceStatus({
+            surface: "cursor_rule",
+            management: "managed",
+            state: "compatible",
+            summary: "Cursor rule file matches the current GDH-managed surface.",
+            reasons: [],
+            probes,
+            action: null,
+        });
+    }
+    return createLifecycleSurfaceStatus({
+        surface: "cursor_rule",
+        management: "managed",
+        state: surface?.present ? "migration_available" : "migration_needed",
+        summary: "Cursor rule file needs to be created or refreshed through the adapter install flow.",
+        reasons: surface?.present
+            ? ["cursor_rule_misconfigured"]
+            : ["cursor_rule_missing"],
+        probes,
+        action: {
+            kind: "run_repair",
+            summary: "Run GDH migrate or adapters install to refresh the managed Cursor rule file.",
+            command: ["gdh", "adapters", "install", targetPath],
+            autoApplicable: true,
+        },
+    });
+}
+function inspectMcpLauncherLifecycleSurface(targetPath, mcpEnabled, adapterStatus) {
+    if (!mcpEnabled) {
+        return createLifecycleSurfaceStatus({
+            surface: "mcp_launcher",
+            management: "managed",
+            state: "compatible",
+            summary: "Project-scoped MCP launcher is not required while MCP is disabled.",
+            reasons: [],
+            probes: [],
+            action: null,
+        });
+    }
+    const launcherSurface = findAdapterSurface(adapterStatus, "claude", "launcher_file") ??
+        findAdapterSurface(adapterStatus, "cursor", "launcher_file") ??
+        findAdapterSurface(adapterStatus, "codex", "launcher_file");
+    const probes = launcherSurface === null
+        ? []
+        : [
+            createVersionProbe({
+                targetPath,
+                relativePath: launcherSurface.relativePath ?? MCP_LAUNCHER_RELATIVE_PATH,
+                present: launcherSurface.present,
+                expectedVersion: GDH_MCP_LAUNCHER_VERSION,
+                detectedVersion: launcherSurface.present ? launcherSurface.version : null,
+            }),
+        ];
+    if (launcherSurface?.state === "ready") {
+        return createLifecycleSurfaceStatus({
+            surface: "mcp_launcher",
+            management: "managed",
+            state: "compatible",
+            summary: "Managed MCP launcher file matches the current GDH version.",
+            reasons: [],
+            probes,
+            action: null,
+        });
+    }
+    return createLifecycleSurfaceStatus({
+        surface: "mcp_launcher",
+        management: "managed",
+        state: launcherSurface?.present ? "migration_available" : "migration_needed",
+        summary: "Managed MCP launcher file needs to be created or refreshed through the adapter install flow.",
+        reasons: launcherSurface?.present
+            ? ["mcp_launcher_misconfigured"]
+            : ["mcp_launcher_missing"],
+        probes,
+        action: {
+            kind: "run_repair",
+            summary: "Run GDH migrate or adapters install to refresh the managed MCP launcher file.",
+            command: ["gdh", "adapters", "install", targetPath],
+            autoApplicable: true,
+        },
+    });
+}
+function inspectRuntimeBridgeLifecycleSurface(targetPath, bridgeStatus) {
+    const probes = bridgeStatus.managedArtifacts.map((artifact) => createVersionProbe({
+        targetPath,
+        relativePath: artifact.relativePath,
+        present: artifact.state !== "missing",
+        expectedVersion: artifact.expectedVersion,
+        detectedVersion: artifact.detectedVersion,
+    }));
+    if (bridgeStatus.runtimeBridge?.enabled === false) {
+        return createLifecycleSurfaceStatus({
+            surface: "runtime_bridge_surface",
+            management: "managed",
+            state: "compatible",
+            summary: "Runtime bridge is intentionally disabled in the project config.",
+            reasons: [],
+            probes,
+            action: null,
+        });
+    }
+    if (bridgeStatus.compatibility === "migration_available") {
+        return createLifecycleSurfaceStatus({
+            surface: "runtime_bridge_surface",
+            management: "managed",
+            state: "migration_available",
+            summary: "Runtime bridge configuration or managed files can be normalized through the GDH repair flow.",
+            reasons: bridgeStatus.reasons,
+            probes,
+            action: {
+                kind: "run_repair",
+                summary: "Run GDH migrate or bridge repair to normalize the runtime bridge surface.",
+                command: ["gdh", "bridge", "repair", targetPath],
+                autoApplicable: true,
+            },
+        });
+    }
+    if (bridgeStatus.state === "ready") {
+        return createLifecycleSurfaceStatus({
+            surface: "runtime_bridge_surface",
+            management: "managed",
+            state: "compatible",
+            summary: "Runtime bridge managed files and autoload registration are aligned.",
+            reasons: [],
+            probes,
+            action: null,
+        });
+    }
+    if (bridgeStatus.state === "needs_install") {
+        return createLifecycleSurfaceStatus({
+            surface: "runtime_bridge_surface",
+            management: "managed",
+            state: "migration_needed",
+            summary: "Runtime bridge managed files are missing and can be repaired automatically. After repair, enable the GDH Runtime Bridge plugin in the Godot editor so it can register GDHBridge itself.",
+            reasons: bridgeStatus.reasons,
+            probes,
+            action: {
+                kind: "run_repair",
+                summary: "Run GDH migrate or bridge repair to install the missing runtime bridge files, then enable the GDH Runtime Bridge plugin in the Godot editor.",
+                command: ["gdh", "bridge", "repair", targetPath],
+                autoApplicable: true,
+            },
+        });
+    }
+    if (bridgeStatus.state === "drifted") {
+        if (isRuntimeBridgePluginEnablePending(bridgeStatus)) {
+            return createLifecycleSurfaceStatus({
+                surface: "runtime_bridge_surface",
+                management: "managed",
+                state: "compatibility_degraded",
+                summary: bridgeStatus.summary,
+                reasons: bridgeStatus.reasons,
+                probes,
+                action: {
+                    kind: "manual_review",
+                    summary: "Enable the GDH Runtime Bridge plugin in the Godot editor so it can register GDHBridge, then rerun GDH status or bridge status.",
+                    command: ["gdh", "bridge", "status", targetPath],
+                    autoApplicable: false,
+                },
+            });
+        }
+        return createLifecycleSurfaceStatus({
+            surface: "runtime_bridge_surface",
+            management: "managed",
+            state: "compatibility_degraded",
+            summary: "Runtime bridge managed files are present but drifted from the current GDH surface and need review or repair.",
+            reasons: bridgeStatus.reasons,
+            probes,
+            action: {
+                kind: "run_repair",
+                summary: "Run GDH bridge repair after reviewing the drifted runtime bridge files.",
+                command: ["gdh", "bridge", "repair", targetPath],
+                autoApplicable: true,
+            },
+        });
+    }
+    return createLifecycleSurfaceStatus({
+        surface: "runtime_bridge_surface",
+        management: "managed",
+        state: "migration_blocked",
+        summary: bridgeStatus.summary,
+        reasons: bridgeStatus.reasons,
+        probes,
+        action: {
+            kind: "manual_review",
+            summary: "Inspect the runtime bridge configuration before applying automated repair.",
+            command: ["gdh", "bridge", "status", targetPath],
+            autoApplicable: false,
+        },
+    });
+}
+function isRuntimeBridgePluginEnablePending(bridgeStatus) {
+    return (bridgeStatus.state === "drifted" &&
+        bridgeStatus.managedArtifacts.every((artifact) => artifact.state === "present") &&
+        bridgeStatus.reasons.includes("runtime_bridge_plugin_enable_required"));
+}
+async function inspectYamlSurfaceDirectory(input) {
+    const currentAbsoluteDirectory = path.join(input.targetPath, input.currentRelativeDirectory);
+    const legacyAbsoluteDirectory = path.join(input.targetPath, input.legacyRelativeDirectory);
+    const [currentExists, legacyExists] = await Promise.all([
+        pathExists(currentAbsoluteDirectory),
+        pathExists(legacyAbsoluteDirectory),
+    ]);
+    if (currentExists && legacyExists) {
+        return createLifecycleSurfaceStatus({
+            surface: input.surface,
+            management: input.management,
+            state: "migration_blocked",
+            summary: "Both legacy and current surface directories exist, so migration is blocked until the conflict is resolved.",
+            reasons: [input.conflictReason],
+            probes: [
+                createVersionProbe({
+                    targetPath: input.targetPath,
+                    relativePath: input.currentRelativeDirectory,
+                    present: true,
+                    expectedVersion: input.expectedVersion,
+                    detectedVersion: null,
+                }),
+                createVersionProbe({
+                    targetPath: input.targetPath,
+                    relativePath: input.legacyRelativeDirectory,
+                    present: true,
+                    expectedVersion: input.expectedVersion,
+                    detectedVersion: null,
+                }),
+            ],
+            action: {
+                kind: "manual_review",
+                summary: "Inspect the conflicting surface directories before running GDH migrate.",
+                command: ["gdh", "migrate", input.targetPath],
+                autoApplicable: false,
+            },
+        });
+    }
+    const surfaceDirectory = currentExists
+        ? currentAbsoluteDirectory
+        : legacyExists
+            ? legacyAbsoluteDirectory
+            : null;
+    if (surfaceDirectory === null) {
+        return createLifecycleSurfaceStatus({
+            surface: input.surface,
+            management: input.management,
+            state: "compatible",
+            summary: input.emptySummary,
+            reasons: [],
+            probes: [],
+            action: null,
+        });
+    }
+    const entries = await fs.readdir(surfaceDirectory, { withFileTypes: true }).catch(() => []);
+    const probes = await Promise.all(entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".yaml"))
+        .sort((left, right) => left.name.localeCompare(right.name))
+        .map(async (entry) => {
+        const relativePath = path.relative(input.targetPath, path.join(surfaceDirectory, entry.name));
+        const content = await fs
+            .readFile(path.join(surfaceDirectory, entry.name), "utf8")
+            .catch(() => null);
+        return createVersionProbe({
+            targetPath: input.targetPath,
+            relativePath,
+            present: content !== null,
+            expectedVersion: input.expectedVersion,
+            detectedVersion: readYamlVersionHeader(content),
+        });
+    }));
+    if (legacyExists) {
+        return createLifecycleSurfaceStatus({
+            surface: input.surface,
+            management: input.management,
+            state: "migration_available",
+            summary: input.migrationSummary,
+            reasons: [input.versionBehindReason],
+            probes,
+            action: {
+                kind: "apply_migration",
+                summary: "Run GDH migrate to normalize legacy runtime surface directories.",
+                command: ["gdh", "migrate", input.targetPath],
+                autoApplicable: true,
+            },
+        });
+    }
+    if (probes.length === 0) {
+        return createLifecycleSurfaceStatus({
+            surface: input.surface,
+            management: input.management,
+            state: "compatible",
+            summary: input.emptySummary,
+            reasons: [],
+            probes,
+            action: null,
+        });
+    }
+    const hasOlderVersion = probes.some((probe) => probe.detectedVersion !== null && probe.detectedVersion < input.expectedVersion);
+    const hasUnknownVersion = probes.some((probe) => probe.detectedVersion === null || probe.detectedVersion > input.expectedVersion);
+    if (!hasOlderVersion && !hasUnknownVersion) {
+        return createLifecycleSurfaceStatus({
+            surface: input.surface,
+            management: input.management,
+            state: "compatible",
+            summary: input.compatibleSummary,
+            reasons: [],
+            probes,
+            action: null,
+        });
+    }
+    if (hasOlderVersion && !hasUnknownVersion) {
+        return createLifecycleSurfaceStatus({
+            surface: input.surface,
+            management: input.management,
+            state: "migration_available",
+            summary: input.migrationSummary,
+            reasons: [input.versionBehindReason],
+            probes,
+            action: {
+                kind: "apply_migration",
+                summary: "Run GDH migrate to normalize the affected runtime surfaces.",
+                command: ["gdh", "migrate", input.targetPath],
+                autoApplicable: true,
+            },
+        });
+    }
+    return createLifecycleSurfaceStatus({
+        surface: input.surface,
+        management: input.management,
+        state: "compatibility_degraded",
+        summary: "One or more runtime surface files have missing or unsupported version markers and need manual review.",
+        reasons: [input.missingVersionReason],
+        probes,
+        action: {
+            kind: "manual_review",
+            summary: "Inspect the affected runtime surface files before applying automated migration.",
+            command: ["gdh", "migrate", input.targetPath],
+            autoApplicable: false,
+        },
+    });
+}
+function summarizeProjectLifecycleCompatibility(targetPath, surfaces) {
+    const state = resolveProjectLifecycleState(surfaces);
+    const reasons = dedupe(surfaces.flatMap((surface) => surface.reasons).filter((reason) => reason.length > 0));
+    return {
+        targetPath,
+        state,
+        summary: summarizeProjectLifecycleState(state, surfaces),
+        reasons,
+        surfaces,
+    };
+}
+function resolveProjectLifecycleState(surfaces) {
+    if (surfaces.some((surface) => surface.state === "migration_blocked")) {
+        return "migration_blocked";
+    }
+    if (surfaces.some((surface) => surface.state === "compatibility_degraded")) {
+        return "compatibility_degraded";
+    }
+    if (surfaces.some((surface) => surface.state === "migration_needed")) {
+        return "migration_needed";
+    }
+    if (surfaces.some((surface) => surface.state === "migration_available")) {
+        return "migration_available";
+    }
+    return "compatible";
+}
+function summarizeProjectLifecycleState(state, surfaces) {
+    const affectedCount = surfaces.filter((surface) => surface.state !== "compatible").length;
+    if (state === "compatible") {
+        return "All GDH-managed project surfaces are compatible with the current product version.";
+    }
+    if (state === "migration_available") {
+        return `${affectedCount} GDH-managed project surface(s) can be normalized automatically through the migration flow.`;
+    }
+    if (state === "migration_needed") {
+        return `${affectedCount} GDH-managed project surface(s) are missing and can be created or repaired automatically.`;
+    }
+    if (state === "compatibility_degraded") {
+        return `${affectedCount} GDH-managed project surface(s) need manual review before automatic migration or repair is safe.`;
+    }
+    return `${affectedCount} GDH-managed project surface(s) are blocked and need operator intervention before migration can continue.`;
+}
+function createLifecycleSurfaceStatus(input) {
+    return input;
+}
+function createVersionProbe(input) {
+    return {
+        relativePath: input.relativePath,
+        absolutePath: path.join(input.targetPath, input.relativePath),
+        present: input.present,
+        expectedVersion: input.expectedVersion,
+        detectedVersion: input.detectedVersion,
+    };
+}
+function readYamlVersionHeader(content) {
+    if (content === null) {
+        return null;
+    }
+    const match = content.match(/^version:\s*(\d+)\s*$/m);
+    if (!match?.[1]) {
+        return null;
+    }
+    return Number.parseInt(match[1], 10);
+}
+function readFrontmatterVersion(content) {
+    if (content === null || !content.startsWith("---\n")) {
+        return null;
+    }
+    const endIndex = content.indexOf("\n---\n", 4);
+    if (endIndex < 0) {
+        return null;
+    }
+    return readYamlVersionHeader(content.slice(4, endIndex));
+}
+function readTaggedVersion(content, pattern) {
+    if (content === null) {
+        return null;
+    }
+    const match = content.match(pattern);
+    if (!match?.[1]) {
+        return null;
+    }
+    return Number.parseInt(match[1], 10);
+}
+function findAdapterSurface(adapterStatus, agent, kind) {
+    return (adapterStatus.adapters
+        .find((entry) => entry.agent === agent)
+        ?.surfaces.find((surface) => surface.kind === kind && surface.scope === "repo") ??
+        null);
+}
+async function pathExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function dedupe(values) {
+    return [...new Set(values)];
+}
+async function buildAuthoringContext(targetPath) {
+    const inventory = await scanGodotProjectInventory(targetPath);
+    const projectConfig = await readProjectConfig(targetPath);
+    const worktreeState = await readWorktreeState(targetPath);
+    const status = resolveAuthoringStatus({
+        targetPath,
+        inventory,
+        projectConfig,
+        worktreeState,
+    });
+    return {
+        inventory,
+        projectConfig,
+        worktreeState,
+        status,
+    };
+}
+function deriveRepoState(context) {
+    const repoState = new Set();
+    if (context.projectConfig !== null) {
+        repoState.add("onboarded");
+    }
+    if (context.status.readiness !== "undetected") {
+        repoState.add(context.status.readiness);
+    }
+    return [...repoState];
+}
+function normalizeChangedFiles(files) {
+    return [...new Set(files.map((file) => file.trim()).filter((file) => file.length > 0))];
+}
+//# sourceMappingURL=index.js.map