@skillcap/gdh 0.1.2

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

@@ -0,0 +1,3766 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { buildGdhStatusResult, createGsdSnapshot, getSupportedAgentAdaptersStatus, installSupportedAgentAdapters, } from "@gdh/adapters";
+import { getManagedLspStatus, hasCompleteOnboardingSurface, inspectCacheState, pruneCacheState, readProjectConfig, readWorktreeState, resolveAuthoringStatus, resolveTargetGodotDocsVersion, runAuthoringCheck, runImportRefresh, runTargetPrepare, runWarmup, } from "@gdh/authoring";
+import { definePackageBoundary, GDH_AUTHORING_DOGFOOD_VERSION, GDH_AUTHORING_SLICE_REPORT_VERSION, GDH_PRODUCT_NAME, resolveCurrentGdhInstall, resolveGdhProductMetadata, } from "@gdh/core";
+import { fetchOfficialGodotDoc, getGuidanceStatus, resolveGuidanceQuery, searchOfficialGodotDocs, } from "@gdh/docs";
+import { createMcpManifest, invokeMcpTool, serveMcpOverStdio } from "@gdh/mcp";
+import { inspectAuthoringEffectiveness, inspectAuthoringSessions, inspectGuidanceAudit, recordAuthoringSessionEvent, } from "@gdh/observability";
+import { checkRuntimeRecipe, inspectRuntimeBridgeSurface, installRuntimeBridgeSurface, listRuntimeRecipes, removeRuntimeBridgeSurface, repairRuntimeBridgeSurface, runRuntimeRecipe, showRuntimeRecipe, } from "@gdh/runtime";
+import { applyRepairableOnboardingWrites, onboardGodotProject, scanGodotProjectInventory, } from "@gdh/scan";
+import { evaluateDonePolicy, exerciseRuntimeCorpusEntry, inspectRuntimeCorpusStatus, inspectRuntimeVerificationBundleState, inspectRuntimeVerificationReadiness, listRuntimeScenarios, materializeRuntimeCorpusEntry, recommendValidationForChange, recordRuntimeCorpusValidation, runRuntimeVerificationScenario, showRuntimeScenario, } from "@gdh/verify";
+import { migrateProjectLifecycleSurface } from "./migrate.js";
+import { presentPublicRuntimeTerms } from "./public-terms.js";
+import { executeSetupCommand, isSetupCanceledError, renderSetupIntro, renderSetupOutro, renderSetupSummary, } from "./setup.js";
+export const cliPackage = definePackageBoundary({
+    name: "@gdh/cli",
+    layer: "surface",
+    responsibility: "Primary automation surface and top-level composition root for the gdh command.",
+    allowedInternalDependencies: [
+        "@gdh/adapters",
+        "@gdh/core",
+        "@gdh/authoring",
+        "@gdh/docs",
+        "@gdh/mcp",
+        "@gdh/observability",
+        "@gdh/runtime",
+        "@gdh/scan",
+        "@gdh/verify",
+    ],
+});
+export async function runCli(args, io = { stdout: process.stdout, stderr: process.stderr }) {
+    const [command, ...rest] = args;
+    if (!command || command === "--help" || command === "help") {
+        io.stdout.write(renderHelp());
+        return 0;
+    }
+    if (command === "--version" || command === "-v") {
+        io.stdout.write(`${resolveGdhProductMetadata().version}\n`);
+        return 0;
+    }
+    if (command === "version") {
+        return runVersionCommand(rest, io);
+    }
+    if (command === "setup") {
+        return runSetupCommand(rest, io);
+    }
+    if (command === "scan") {
+        return runScanCommand(rest, io);
+    }
+    if (command === "status") {
+        return runStatusCommand(rest, io);
+    }
+    if (command === "adapters") {
+        return runAdaptersCommand(rest, io);
+    }
+    if (command === "authoring") {
+        return runAuthoringCommand(rest, io);
+    }
+    if (command === "lsp") {
+        return runLspCommand(rest, io);
+    }
+    if (command === "warmup") {
+        return runWarmupCommand(rest, io);
+    }
+    if (command === "target") {
+        return runTargetCommand(rest, io);
+    }
+    if (command === "imports") {
+        return runImportsCommand(rest, io);
+    }
+    if (command === "run-config" || command === "recipe") {
+        return runRecipeCommand(rest, io);
+    }
+    if (command === "bridge") {
+        return runBridgeCommand(rest, io);
+    }
+    if (command === "verification-scenario" || command === "scenario") {
+        return runScenarioCommand(rest, io);
+    }
+    if (command === "guidance") {
+        return runGuidanceCommand(rest, io);
+    }
+    if (command === "docs") {
+        return runDocsCommand(rest, io);
+    }
+    if (command === "observability") {
+        return runObservabilityCommand(rest, io);
+    }
+    if (command === "dogfood") {
+        return runDogfoodCommand(rest, io);
+    }
+    if (command === "doctor") {
+        return runDoctorCommand(rest, io);
+    }
+    if (command === "mcp") {
+        return runMcpCommand(rest, io);
+    }
+    if (command === "verify") {
+        return runVerifyCommand(rest, io);
+    }
+    if (command === "migrate") {
+        return runMigrateCommand(rest, io);
+    }
+    if (command === "cache") {
+        return runCacheCommand(rest, io);
+    }
+    if (command === "onboard") {
+        return runOnboardCommand(rest, io);
+    }
+    io.stderr.write(`Unknown command: ${command}\n\n${renderHelp()}`);
+    return 1;
+}
+function writeJsonResult(io, value, options = {}) {
+    const output = options.presentRuntimeTerms ? presentPublicRuntimeTerms(value) : value;
+    io.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+}
+async function runScanCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            `Usage: gdh scan [target]`,
+            "Usage: gdh scan --target <path>",
+            "",
+            "Scan a filesystem target for Godot project roots and print a machine-generated inventory as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const parsedTarget = parseSingleTargetPathArg(args, {
+        usage: "Usage: gdh scan [target]\nUsage: gdh scan --target <path>\n",
+        allowTargetOption: true,
+    });
+    if (parsedTarget.error !== null) {
+        io.stderr.write(parsedTarget.error);
+        return 1;
+    }
+    const targetPath = parsedTarget.targetPath;
+    try {
+        const inventory = await scanGodotProjectInventory(targetPath);
+        io.stdout.write(`${JSON.stringify(inventory, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to scan target "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runSetupCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh setup [target] [--yes] [--project <relative-path>] [--agent <name>] [--all-agents] [--integration-root <path>]",
+            "",
+            "Run the interactive GDH setup wizard for the current repository or target path.",
+            "--yes skips prompts and uses detected defaults unless you override them with --project, --agent, or --all-agents.",
+            "--project selects one detected Godot project relative to the setup root when many are present.",
+            "--all-agents enables every supported agent available on this machine.",
+            "Supported agents: codex, claude, cursor",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh setup [target] [--yes] [--project <relative-path>] [--agent <name>] [--all-agents] [--integration-root <path>]\n",
+        optionsWithValues: ["--agent", "--project", "--integration-root"],
+        booleanOptions: ["--yes", "--all-agents"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const yes = args.includes("--yes");
+    const allAgents = args.includes("--all-agents");
+    const positionalArgs = extractPositionalArgs(args, new Set(["--agent", "--project", "--integration-root"]));
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh setup accepts at most one positional target path.\n");
+        return 1;
+    }
+    const requestedAgents = collectAdapterNames(args);
+    if (requestedAgents === null) {
+        io.stderr.write("Usage error: --agent must be one of codex, claude, or cursor.\n");
+        return 1;
+    }
+    if (allAgents && requestedAgents.length > 0) {
+        io.stderr.write("Usage error: choose either --all-agents or one or more --agent values.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const explicitTargetPath = positionalArgs.length === 1;
+    const selectedProjectRelativePath = readSingleOptionValue(args, "--project");
+    const integrationRootPath = readSingleOptionValue(args, "--integration-root");
+    const commandStartedAtMs = Date.now();
+    const interactive = !yes &&
+        io.stdout === process.stdout &&
+        io.stderr === process.stderr &&
+        process.stdin.isTTY === true &&
+        process.stdout.isTTY === true;
+    if (!interactive && !yes) {
+        io.stderr.write("GDH setup needs an interactive terminal. Re-run `gdh setup` in a TTY or use `gdh setup --yes` with explicit defaults.\n");
+        return 1;
+    }
+    try {
+        if (interactive) {
+            renderSetupIntro();
+        }
+        const result = await executeSetupCommand({
+            targetPath,
+            explicitTargetPath,
+            yes,
+            requestedAgents,
+            allAgents,
+            selectedProjectRelativePath,
+            integrationRootPath,
+        }, { interactive });
+        await recordSessionEvent(result.scanRootPath, {
+            commandStartedAtMs,
+            kind: "onboard",
+            command: "gdh setup",
+            state: "succeeded",
+            summary: result.summary,
+            producedArtifacts: [
+                ...result.onboarding.writes.map((entry) => entry.relativePath),
+                ...result.repoAdapterInstall.actions
+                    .map((action) => action.relativePath)
+                    .filter((entry) => entry !== null),
+                ...(result.codexUserInstall?.actions
+                    .map((action) => action.relativePath)
+                    .filter((entry) => entry !== null) ?? []),
+                ...result.bridgeInstall.actions.map((action) => action.relativePath),
+            ],
+        });
+        if (interactive) {
+            renderSetupOutro(result);
+            return 0;
+        }
+        io.stdout.write(`${renderSetupSummary(result)}\n`);
+        return 0;
+    }
+    catch (error) {
+        if (isSetupCanceledError(error)) {
+            await recordSessionEvent(targetPath, {
+                commandStartedAtMs,
+                kind: "onboard",
+                command: "gdh setup",
+                state: "blocked",
+                summary: "GDH setup was canceled before applying changes.",
+            });
+            return 1;
+        }
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "onboard",
+            command: "gdh setup",
+            state: "failed",
+            summary: "GDH setup failed before completing the repository handoff.",
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to complete GDH setup for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runOnboardCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh onboard [target] [--dry-run]",
+            "",
+            "Generate the initial GDH project surface from scan evidence and print the onboarding result as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh onboard [target] [--dry-run]\n",
+        booleanOptions: ["--dry-run"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const dryRun = args.includes("--dry-run");
+    const positionalArgs = extractGuidanceResolvePositionalArgs(args);
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh onboard accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const commandStartedAtMs = Date.now();
+    try {
+        const result = await onboardGodotProject(targetPath, { dryRun });
+        const adapterInstall = result.status === "ready"
+            ? await installSupportedAgentAdapters(targetPath, {
+                dryRun,
+                devRepoPath: resolveCurrentGdhInstall(import.meta.url).defaultDevRepoPath,
+            })
+            : null;
+        if (!dryRun) {
+            await recordSessionEvent(targetPath, {
+                commandStartedAtMs,
+                kind: "onboard",
+                command: "gdh onboard",
+                state: "succeeded",
+                summary: result.status === "ready"
+                    ? "Onboarding completed durable GDH surfaces for the selected project."
+                    : "Onboarding remained unresolved and surfaced human-required gaps.",
+                producedArtifacts: [
+                    ...result.writes.map((entry) => entry.relativePath),
+                    ...(adapterInstall?.actions
+                        .map((action) => action.relativePath)
+                        .filter((entry) => entry !== null) ?? []),
+                ],
+            });
+        }
+        writeJsonResult(io, {
+            ...result,
+            adapterInstall,
+        }, { presentRuntimeTerms: true });
+        return 0;
+    }
+    catch (error) {
+        if (!dryRun) {
+            await recordSessionEvent(targetPath, {
+                commandStartedAtMs,
+                kind: "onboard",
+                command: "gdh onboard",
+                state: "failed",
+                summary: "GDH onboarding failed before producing a result.",
+                errorMessage: formatCliError(error),
+            });
+        }
+        io.stderr.write(`Failed to onboard target "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runStatusCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh status [target]",
+            "Usage: gdh status --target <path>",
+            "",
+            "Report explicit GDH readiness and capability availability for a target as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const parsedTarget = parseSingleTargetPathArg(args, {
+        usage: "Usage: gdh status [target]\nUsage: gdh status --target <path>\n",
+        allowTargetOption: true,
+    });
+    if (parsedTarget.error !== null) {
+        io.stderr.write(parsedTarget.error);
+        return 1;
+    }
+    const targetPath = parsedTarget.targetPath;
+    const commandStartedAtMs = Date.now();
+    try {
+        const status = await buildGdhStatusResult(targetPath);
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "status",
+            command: "gdh status",
+            state: status.readiness === "undetected" ? "blocked" : "succeeded",
+            summary: status.summary,
+        });
+        io.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "status",
+            command: "gdh status",
+            state: "failed",
+            summary: "GDH status resolution failed before producing a result.",
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to resolve status for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runVersionCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh version",
+            "",
+            "Print the GDH product version, release stage, and managed project-surface versions as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (args.length > 0) {
+        io.stderr.write("Usage error: gdh version does not accept positional arguments.\n");
+        return 1;
+    }
+    io.stdout.write(`${JSON.stringify(resolveGdhProductMetadata(), null, 2)}\n`);
+    return 0;
+}
+async function runAuthoringCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh authoring <command> [target]",
+            "",
+            "Commands:",
+            "  check [target]  Run the current authoring-check entrypoint and print a structured result.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "check") {
+        return runAuthoringCheckCommand(rest, io);
+    }
+    io.stderr.write(`Unknown authoring command: ${subcommand}\n\nUsage: gdh authoring check [target]\n`);
+    return 1;
+}
+async function runLspCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh lsp <command> [target]",
+            "",
+            "Commands:",
+            "  status [target]  Resolve the managed authoring.lsp lifecycle state and print it as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "status") {
+        return runLspStatusCommand(rest, io);
+    }
+    io.stderr.write(`Unknown lsp command: ${subcommand}\n\nUsage: gdh lsp status [target]\n`);
+    return 1;
+}
+async function runDocsCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh docs <command> [target]",
+            "",
+            "Commands:",
+            "  version [target] [--project <relative-path>]  Resolve the effective Godot docs version and official source set as JSON.",
+            "  search <query> [target] [--project <relative-path>] [--limit <n>]  Search official version-aware Godot docs as JSON.",
+            "  fetch <ref-or-url> [target] [--project <relative-path>]  Fetch one official version-aware Godot docs page or section as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "version") {
+        return runDocsVersionCommand(rest, io);
+    }
+    if (subcommand === "search") {
+        return runDocsSearchCommand(rest, io);
+    }
+    if (subcommand === "fetch") {
+        return runDocsFetchCommand(rest, io);
+    }
+    io.stderr.write([
+        `Unknown docs command: ${subcommand}`,
+        "",
+        "Usage: gdh docs version [target] [--project <relative-path>]",
+        "       gdh docs search <query> [target] [--project <relative-path>] [--limit <n>]",
+        "       gdh docs fetch <ref-or-url> [target] [--project <relative-path>]",
+    ].join("\n") + "\n");
+    return 1;
+}
+async function runDocsVersionCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh docs version [target] [--project <relative-path>]",
+            "",
+            "Resolve the effective Godot docs version, winning hint source, and official source set for one target as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh docs version [target] [--project <relative-path>]\n",
+        optionsWithValues: ["--project"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set(["--project"]));
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh docs version accepts at most one positional target path.\n");
+        return 1;
+    }
+    if (args.includes("--project") && readSingleOptionValue(args, "--project") === null) {
+        io.stderr.write("Usage error: --project requires a relative project path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const requestedProjectPath = readSingleOptionValue(args, "--project");
+    try {
+        const context = await buildAuthoringContext(targetPath);
+        const result = resolveTargetGodotDocsVersion({
+            targetPath,
+            inventory: context.inventory,
+            projectConfig: context.projectConfig,
+            requestedProjectPath,
+        });
+        writeJsonResult(io, result);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to resolve docs version for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runDocsSearchCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh docs search <query> [target] [--project <relative-path>] [--limit <n>]",
+            "",
+            "Search the resolved official Godot docs branch and print bounded JSON results.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh docs search <query> [target] [--project <relative-path>] [--limit <n>]\n",
+        optionsWithValues: ["--project", "--limit"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set(["--project", "--limit"]));
+    if (positionalArgs.length === 0 || positionalArgs.length > 2) {
+        io.stderr.write("Usage error: gdh docs search requires a query and accepts at most one optional target path.\n");
+        return 1;
+    }
+    if (args.includes("--project") && readSingleOptionValue(args, "--project") === null) {
+        io.stderr.write("Usage error: --project requires a relative project path.\n");
+        return 1;
+    }
+    if (args.includes("--limit") && readSingleOptionValue(args, "--limit") === null) {
+        io.stderr.write("Usage error: --limit requires a positive integer.\n");
+        return 1;
+    }
+    const limitValue = readSingleOptionValue(args, "--limit");
+    const limit = limitValue === null ? undefined : parsePositiveIntegerOptionValue(limitValue);
+    if (limitValue !== null && limit === null) {
+        io.stderr.write("Usage error: --limit must be a positive integer.\n");
+        return 1;
+    }
+    const query = positionalArgs[0];
+    const targetPath = positionalArgs[1] ?? ".";
+    const requestedProjectPath = readSingleOptionValue(args, "--project");
+    try {
+        const context = await buildAuthoringContext(targetPath);
+        const docsVersion = resolveTargetGodotDocsVersion({
+            targetPath,
+            inventory: context.inventory,
+            projectConfig: context.projectConfig,
+            requestedProjectPath,
+        });
+        const result = await searchOfficialGodotDocs({
+            docsVersion,
+            query,
+            ...(limit === undefined ? {} : { limit }),
+        });
+        writeJsonResult(io, result);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to search official docs for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runDocsFetchCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh docs fetch <ref-or-url> [target] [--project <relative-path>]",
+            "",
+            "Fetch one official version-aware Godot docs page or section and print bounded JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh docs fetch <ref-or-url> [target] [--project <relative-path>]\n",
+        optionsWithValues: ["--project"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set(["--project"]));
+    if (positionalArgs.length === 0 || positionalArgs.length > 2) {
+        io.stderr.write("Usage error: gdh docs fetch requires a ref or URL and accepts at most one optional target path.\n");
+        return 1;
+    }
+    if (args.includes("--project") && readSingleOptionValue(args, "--project") === null) {
+        io.stderr.write("Usage error: --project requires a relative project path.\n");
+        return 1;
+    }
+    const refOrUrl = positionalArgs[0];
+    const targetPath = positionalArgs[1] ?? ".";
+    const requestedProjectPath = readSingleOptionValue(args, "--project");
+    try {
+        const context = await buildAuthoringContext(targetPath);
+        const docsVersion = resolveTargetGodotDocsVersion({
+            targetPath,
+            inventory: context.inventory,
+            projectConfig: context.projectConfig,
+            requestedProjectPath,
+        });
+        const result = await fetchOfficialGodotDoc({
+            docsVersion,
+            refOrUrl,
+        });
+        writeJsonResult(io, result);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to fetch official docs for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runAuthoringCheckCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh authoring check [target]",
+            "Usage: gdh authoring check --target <path>",
+            "",
+            "Run the current GDH authoring-check flow and print a structured result as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const parsedTarget = parseSingleTargetPathArg(args, {
+        usage: "Usage: gdh authoring check [target]\nUsage: gdh authoring check --target <path>\n",
+        allowTargetOption: true,
+    });
+    if (parsedTarget.error !== null) {
+        io.stderr.write(parsedTarget.error);
+        return 1;
+    }
+    const targetPath = parsedTarget.targetPath;
+    const commandStartedAtMs = Date.now();
+    try {
+        const context = await buildAuthoringContext(targetPath);
+        const result = await runAuthoringCheck({
+            targetPath,
+            status: context.status,
+            projectConfig: context.projectConfig,
+        });
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "authoring_check",
+            command: "gdh authoring check",
+            state: result.status === "unavailable" ? "blocked" : "succeeded",
+            summary: result.summary,
+            validation: {
+                changedFiles: [],
+                recommendedKinds: ["authoring_check"],
+                performedKinds: result.status === "passed" ||
+                    result.status === "diagnostics" ||
+                    result.status === "degraded"
+                    ? ["authoring_check"]
+                    : [],
+            },
+        });
+        writeJsonResult(io, result, { presentRuntimeTerms: true });
+        return 0;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "authoring_check",
+            command: "gdh authoring check",
+            state: "failed",
+            summary: "GDH authoring check failed before producing a result.",
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to run authoring check for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runLspStatusCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh lsp status [target]",
+            "Usage: gdh lsp status --target <path>",
+            "",
+            "Resolve the managed authoring.lsp lifecycle state and print a structured result as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const parsedTarget = parseSingleTargetPathArg(args, {
+        usage: "Usage: gdh lsp status [target]\nUsage: gdh lsp status --target <path>\n",
+        allowTargetOption: true,
+    });
+    if (parsedTarget.error !== null) {
+        io.stderr.write(parsedTarget.error);
+        return 1;
+    }
+    const targetPath = parsedTarget.targetPath;
+    try {
+        const context = await buildAuthoringContext(targetPath);
+        const result = await getManagedLspStatus({
+            targetPath,
+            status: context.status,
+            projectConfig: context.projectConfig,
+            owner: "gdh lsp status",
+        });
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to resolve lsp status for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runWarmupCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh warmup [target] [--dry-run]",
+            "",
+            "Inspect worktree-local versus reusable cache state and plan or apply authoring warmup as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh warmup [target] [--dry-run]\n",
+        booleanOptions: ["--dry-run"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const dryRun = args.includes("--dry-run");
+    const positionalArgs = extractGuidanceResolvePositionalArgs(args);
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh warmup accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    try {
+        const context = await buildAuthoringContext(targetPath);
+        const result = await runWarmup({
+            targetPath,
+            status: context.status,
+            projectConfig: context.projectConfig,
+            dryRun,
+        });
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to plan warmup for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runTargetCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh target <command> [target]",
+            "",
+            "Commands:",
+            "  prepare [target] [--source-target <path>] [--dry-run] [--no-refresh-imports]",
+            "                                            Hydrate target-local generated state and plan or apply GDH target preparation.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "prepare") {
+        return runTargetPrepareCommand(rest, io);
+    }
+    io.stderr.write([
+        `Unknown target command: ${subcommand}`,
+        "",
+        "Usage: gdh target prepare [target] [--source-target <path>] [--dry-run] [--no-refresh-imports]",
+    ].join("\n") + "\n");
+    return 1;
+}
+async function runTargetPrepareCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh target prepare [target] [--source-target <path>] [--dry-run] [--no-refresh-imports]",
+            "",
+            "Prepare a target for editor/import-sensitive work by composing GDH warmup, optional .godot hydration from a configured source target, and optional import refresh.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh target prepare [target] [--source-target <path>] [--dry-run] [--no-refresh-imports]\n",
+        optionsWithValues: ["--source-target"],
+        booleanOptions: ["--dry-run", "--no-refresh-imports"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const dryRun = args.includes("--dry-run");
+    const refreshImports = !args.includes("--no-refresh-imports");
+    const positionalArgs = extractPositionalArgs(args, new Set(["--source-target"]));
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh target prepare accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const sourceTargetPath = collectOptionValues(args, "--source-target")[0] ?? null;
+    const commandStartedAtMs = Date.now();
+    try {
+        const context = await buildAuthoringContext(targetPath);
+        const result = await runTargetPrepare({
+            targetPath,
+            status: context.status,
+            projectConfig: context.projectConfig,
+            sourceTargetPath,
+            refreshImports,
+            dryRun,
+        });
+        if (!dryRun) {
+            await recordSessionEvent(targetPath, {
+                commandStartedAtMs,
+                kind: "target_prepare",
+                command: "gdh target prepare",
+                state: result.state === "ready" ? "succeeded" : "blocked",
+                summary: result.summary,
+                producedArtifacts: result.actions
+                    .map((action) => action.targetPath)
+                    .filter((entry) => entry !== null),
+            });
+        }
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        if (!dryRun) {
+            await recordSessionEvent(targetPath, {
+                commandStartedAtMs,
+                kind: "target_prepare",
+                command: "gdh target prepare",
+                state: "failed",
+                summary: "Target preparation failed before producing a result.",
+                errorMessage: formatCliError(error),
+            });
+        }
+        io.stderr.write(`Failed to prepare target "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runImportsCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh imports <command> [target]",
+            "",
+            "Commands:",
+            "  refresh [target] [--dry-run]    Run or plan a headless Godot import refresh for the target's primary project path.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "refresh") {
+        return runImportsRefreshCommand(rest, io);
+    }
+    io.stderr.write([
+        `Unknown imports command: ${subcommand}`,
+        "",
+        "Usage: gdh imports refresh [target] [--dry-run]",
+    ].join("\n") + "\n");
+    return 1;
+}
+async function runImportsRefreshCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh imports refresh [target] [--dry-run]",
+            "",
+            "Run or plan a headless Godot import/update pass for the configured primary project path.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh imports refresh [target] [--dry-run]\n",
+        booleanOptions: ["--dry-run"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const dryRun = args.includes("--dry-run");
+    const positionalArgs = extractPositionalArgs(args, new Set());
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh imports refresh accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const commandStartedAtMs = Date.now();
+    try {
+        const context = await buildAuthoringContext(targetPath);
+        const result = await runImportRefresh({
+            targetPath,
+            status: context.status,
+            projectConfig: context.projectConfig,
+            dryRun,
+        });
+        if (!dryRun) {
+            await recordSessionEvent(targetPath, {
+                commandStartedAtMs,
+                kind: "imports_refresh",
+                command: "gdh imports refresh",
+                state: result.state === "applied"
+                    ? "succeeded"
+                    : result.state === "blocked"
+                        ? "blocked"
+                        : "failed",
+                summary: result.summary,
+            });
+        }
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        if (!dryRun) {
+            await recordSessionEvent(targetPath, {
+                commandStartedAtMs,
+                kind: "imports_refresh",
+                command: "gdh imports refresh",
+                state: "failed",
+                summary: "Import refresh failed before producing a result.",
+                errorMessage: formatCliError(error),
+            });
+        }
+        io.stderr.write(`Failed to refresh imports for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runCacheCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh cache <command> [target]",
+            "",
+            "Commands:",
+            "  inspect [target]                    Inspect namespaced authoring cache state and print it as JSON.",
+            "  prune [target] [--scope <scope>]    Remove authoring cache state for worktree, project, or both.",
+            "",
+            "Supported scopes: worktree, project, all",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "inspect") {
+        return runCacheInspectCommand(rest, io);
+    }
+    if (subcommand === "prune") {
+        return runCachePruneCommand(rest, io);
+    }
+    io.stderr.write(`Unknown cache command: ${subcommand}\n\nUsage: gdh cache inspect [target]\nUsage: gdh cache prune [target] [--scope <scope>] [--dry-run]\n`);
+    return 1;
+}
+async function runAdaptersCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh adapters <command> [target]",
+            "",
+            "Commands:",
+            "  status [target] [--integration-root <path>]      Inspect supported-agent reinforcement status as JSON.",
+            "  install [target] [--dry-run] [--agent <name>] [--user] [--dev-repo <path>] [--integration-root <path>]",
+            "                                                   Install or repair supported-agent reinforcement surfaces.",
+            "  gsd snapshot [target] [--files <path>] [--performed <kind>]  Export a read-mostly GSD projection as JSON.",
+            "",
+            "Supported agents: codex, claude, cursor",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "status") {
+        return runAdaptersStatusCommand(rest, io);
+    }
+    if (subcommand === "install") {
+        return runAdaptersInstallCommand(rest, io);
+    }
+    if (subcommand === "gsd") {
+        return runGsdAdapterCommand(rest, io);
+    }
+    io.stderr.write([
+        `Unknown adapters command: ${subcommand}`,
+        "",
+        "Usage: gdh adapters status [target] [--integration-root <path>]",
+        "Usage: gdh adapters install [target] [--dry-run] [--agent <name>] [--user] [--dev-repo <path>] [--integration-root <path>]",
+        "Usage: gdh adapters gsd snapshot [target] [--files <path>] [--performed <kind>]",
+    ].join("\n") + "\n");
+    return 1;
+}
+async function runGsdAdapterCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh adapters gsd <command> [target]",
+            "",
+            "Commands:",
+            "  snapshot [target] [--files <path>] [--performed <kind>]  Export a read-mostly GSD projection as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "snapshot") {
+        return runGsdSnapshotCommand(rest, io);
+    }
+    io.stderr.write([
+        `Unknown adapters gsd command: ${subcommand}`,
+        "",
+        "Usage: gdh adapters gsd snapshot [target] [--files <path>] [--performed <kind>]",
+    ].join("\n") + "\n");
+    return 1;
+}
+async function runGuidanceCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh guidance <command> [target]",
+            "",
+            "Commands:",
+            "  status [target]                                  Inspect the current durable guidance surface and audit availability.",
+            "  resolve [target] [--task-type <type>] [--capability <id>] [--repo-state <state>] [--keyword <term>]",
+            "                                                  Resolve which deeper guidance units are eligible for the supplied context.",
+            "  audit [target]                                   Inspect stored machine-readable guidance-audit history.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "status") {
+        return runGuidanceStatusCommand(rest, io);
+    }
+    if (subcommand === "resolve") {
+        return runGuidanceResolveCommand(rest, io);
+    }
+    if (subcommand === "audit") {
+        return runGuidanceAuditCommand(rest, io);
+    }
+    io.stderr.write([
+        `Unknown guidance command: ${subcommand}`,
+        "",
+        "Usage: gdh guidance status [target]",
+        "Usage: gdh guidance resolve [target] [--task-type <type>] [--capability <id>] [--repo-state <state>] [--keyword <term>]",
+        "Usage: gdh guidance audit [target]",
+    ].join("\n") + "\n");
+    return 1;
+}
+async function runObservabilityCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh observability <command> [target]",
+            "",
+            "Commands:",
+            "  session [target] [--latest] [--session-id <id>]  Inspect recorded authoring-session observability as JSON.",
+            "  effectiveness [target] [--latest] [--session-id <id>]  Summarize agent effectiveness heuristics from recorded session activity.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "session") {
+        return runObservabilitySessionCommand(rest, io);
+    }
+    if (subcommand === "effectiveness") {
+        return runObservabilityEffectivenessCommand(rest, io);
+    }
+    io.stderr.write(`Unknown observability command: ${subcommand}\n\nUsage: gdh observability session [target] [--latest] [--session-id <id>]\nUsage: gdh observability effectiveness [target] [--latest] [--session-id <id>]\n`);
+    return 1;
+}
+async function runDogfoodCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh dogfood <command>",
+            "",
+            "Commands:",
+            "  authoring --fixtures <path> [--fixtures <path>...] [--pilot <path>]",
+            "                                                  Exercise the current authoring-first slice against fixtures and an optional pilot target as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "authoring") {
+        return runAuthoringDogfoodCommand(rest, io);
+    }
+    io.stderr.write([
+        `Unknown dogfood command: ${subcommand}`,
+        "",
+        "Usage: gdh dogfood authoring --fixtures <path> [--fixtures <path>...] [--pilot <path>]",
+    ].join("\n") + "\n");
+    return 1;
+}
+async function runDoctorCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh doctor <command> [target]",
+            "",
+            "Commands:",
+            "  authoring-slice [target]                        Inspect whether the current authoring-first slice is healthy enough for internal use.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "authoring-slice") {
+        return runAuthoringSliceDoctorCommand(rest, io);
+    }
+    io.stderr.write([
+        `Unknown doctor command: ${subcommand}`,
+        "",
+        "Usage: gdh doctor authoring-slice [target]",
+    ].join("\n") + "\n");
+    return 1;
+}
+async function runMcpCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh mcp <command>",
+            "",
+            "Commands:",
+            "  manifest                                    Print the thin GDH MCP manifest as JSON.",
+            "  serve --target <path>                       Run the real GDH stdio MCP server for one bound target.",
+            "  invoke <tool> [target] [--input-json <json>] Invoke one GDH MCP tool through the local registry.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "manifest") {
+        return runMcpManifestCommand(rest, io);
+    }
+    if (subcommand === "serve") {
+        return runMcpServeCommand(rest, io);
+    }
+    if (subcommand === "invoke") {
+        return runMcpInvokeCommand(rest, io);
+    }
+    io.stderr.write([
+        `Unknown mcp command: ${subcommand}`,
+        "",
+        "Usage: gdh mcp manifest",
+        "Usage: gdh mcp serve --target <path>",
+        "Usage: gdh mcp invoke <tool> [target] [--input-json <json>]",
+    ].join("\n") + "\n");
+    return 1;
+}
+async function runAuthoringDogfoodCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh dogfood authoring --fixtures <path> [--fixtures <path>...] [--pilot <path>]",
+            "",
+            "Run the current authoring-first slice against fixture targets and one optional pilot target as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh dogfood authoring --fixtures <path> [--fixtures <path>...] [--pilot <path>]\n",
+        optionsWithValues: ["--fixtures", "--pilot"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set(["--fixtures", "--pilot"]));
+    if (positionalArgs.length > 0) {
+        io.stderr.write("Usage error: gdh dogfood authoring accepts only --fixtures <path> and optional --pilot <path> targets.\n");
+        return 1;
+    }
+    const fixtureTargets = collectOptionValues(args, "--fixtures");
+    const pilotTarget = readSingleOptionValue(args, "--pilot");
+    if (fixtureTargets.length === 0 && pilotTarget === null) {
+        io.stderr.write("Usage error: gdh dogfood authoring requires at least one --fixtures <path> or an explicit --pilot <path> target.\n");
+        return 1;
+    }
+    if (args.includes("--pilot") && pilotTarget === null) {
+        io.stderr.write("Usage error: --pilot requires a target path.\n");
+        return 1;
+    }
+    try {
+        const result = await runAuthoringDogfood({
+            fixtureTargets,
+            pilotTarget,
+        });
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return result.state === "failed" ? 1 : 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to run authoring dogfood: ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runAuthoringSliceDoctorCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh doctor authoring-slice [target]",
+            "Usage: gdh doctor authoring-slice --target <path>",
+            "",
+            "Inspect whether the current authoring-first slice is healthy enough for internal use as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const parsedTarget = parseSingleTargetPathArg(args, {
+        usage: "Usage: gdh doctor authoring-slice [target]\nUsage: gdh doctor authoring-slice --target <path>\n",
+        allowTargetOption: true,
+    });
+    if (parsedTarget.error !== null) {
+        io.stderr.write(parsedTarget.error);
+        return 1;
+    }
+    const targetPath = parsedTarget.targetPath;
+    try {
+        const result = await runAuthoringSliceDoctor(targetPath);
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return result.state === "failed" ? 1 : 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to inspect authoring slice readiness for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runVerifyCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh verify <command> [target]",
+            "",
+            "Commands:",
+            "  run [target] <run-config-id> --verification-scenario <verification-scenario-id>",
+            "                                                  Execute one verification scenario over a run configuration and print the structured run record as JSON.",
+            "  inspect [target] [--run-record <run-record-id>]",
+            "                                                  Inspect the latest or selected runtime run record as JSON.",
+            "  readiness [target]",
+            "                                                  Summarize runtime verification readiness, stale evidence, and recurring runtime feedback for one target.",
+            "  corpus <status|record>",
+            "                                                  Inspect or record runtime corpus release-readiness evidence as JSON.",
+            "  recommend [target] --files <path> [--files <path>...]",
+            "                                                  Recommend authoring-first validation requirements for the supplied change set.",
+            "  done [target] --files <path> [--files <path>...] [--performed <kind>]",
+            "                                                  Evaluate whether the supplied change set is eligible to be called done.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "recommend") {
+        return runVerifyRecommendCommand(rest, io);
+    }
+    if (subcommand === "done") {
+        return runVerifyDoneCommand(rest, io);
+    }
+    if (subcommand === "run") {
+        return runVerifyRunCommand(rest, io);
+    }
+    if (subcommand === "inspect") {
+        return runVerifyInspectCommand(rest, io);
+    }
+    if (subcommand === "readiness") {
+        return runVerifyReadinessCommand(rest, io);
+    }
+    if (subcommand === "corpus") {
+        return runVerifyCorpusCommand(rest, io);
+    }
+    io.stderr.write([
+        `Unknown verify command: ${subcommand}`,
+        "",
+        "Usage: gdh verify run [target] <run-config-id> --verification-scenario <verification-scenario-id>",
+        "Usage: gdh verify inspect [target] [--run-record <run-record-id>]",
+        "Usage: gdh verify readiness [target]",
+        "Usage: gdh verify corpus status [--manifest <path>] [--workspace-root <path>]",
+        "Usage: gdh verify corpus materialize --entry <id> [--manifest <path>] [--workspace-root <path>]",
+        "Usage: gdh verify corpus exercise --entry <id> [--manifest <path>] [--workspace-root <path>] [--no-prepare]",
+        "Usage: gdh verify corpus record --entry <id> --target <path> [--manifest <path>] [--workspace-root <path>]",
+        "Usage: gdh verify recommend [target] --files <path> [--files <path>...]",
+        "Usage: gdh verify done [target] --files <path> [--files <path>...] [--performed <kind>]",
+    ].join("\n") + "\n");
+    return 1;
+}
+async function runVerifyCorpusCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh verify corpus <command>",
+            "",
+            "Commands:",
+            "  status [--manifest <path>] [--workspace-root <path>]",
+            "                                                  Inspect runtime corpus release-readiness evidence as JSON.",
+            "  materialize --entry <id> [--manifest <path>] [--workspace-root <path>]",
+            "                                                  Materialize one corpus entry into GDH-managed source state as JSON.",
+            "  exercise --entry <id> [--manifest <path>] [--workspace-root <path>] [--no-prepare]",
+            "                                                  Materialize, onboard, and exercise one corpus entry through GDH as JSON.",
+            "  record --entry <id> --target <path> [--manifest <path>] [--workspace-root <path>]",
+            "                                                  Record current runtime verification readiness for one corpus entry as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "status") {
+        return runVerifyCorpusStatusCommand(rest, io);
+    }
+    if (subcommand === "materialize") {
+        return runVerifyCorpusMaterializeCommand(rest, io);
+    }
+    if (subcommand === "exercise") {
+        return runVerifyCorpusExerciseCommand(rest, io);
+    }
+    if (subcommand === "record") {
+        return runVerifyCorpusRecordCommand(rest, io);
+    }
+    io.stderr.write([
+        `Unknown verify corpus command: ${subcommand}`,
+        "",
+        "Usage: gdh verify corpus status [--manifest <path>] [--workspace-root <path>]",
+        "Usage: gdh verify corpus materialize --entry <id> [--manifest <path>] [--workspace-root <path>]",
+        "Usage: gdh verify corpus exercise --entry <id> [--manifest <path>] [--workspace-root <path>] [--no-prepare]",
+        "Usage: gdh verify corpus record --entry <id> --target <path> [--manifest <path>] [--workspace-root <path>]",
+    ].join("\n") + "\n");
+    return 1;
+}
+async function runRecipeCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh run-config <command> [target] [run-config-id]",
+            "",
+            "Commands:",
+            "  list [target]                              List run configurations discovered under .gdh/run-configurations as JSON.",
+            "  show [target] <run-config-id>              Show one run configuration as JSON.",
+            "  check [target] <run-config-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value]",
+            "                                            Evaluate whether a run configuration is runnable, blocked, or misconfigured.",
+            "  run [target] <run-config-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value] [--live-workspace]",
+            "                                            Run one run configuration and emit structured process evidence.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "list") {
+        return runRecipeListCommand(rest, io);
+    }
+    if (subcommand === "show") {
+        return runRecipeShowCommand(rest, io);
+    }
+    if (subcommand === "check") {
+        return runRecipeCheckCommand(rest, io);
+    }
+    if (subcommand === "run") {
+        return runRecipeRunCommand(rest, io);
+    }
+    io.stderr.write([
+        `Unknown run-config command: ${subcommand}`,
+        "",
+        "Usage: gdh run-config list [target]",
+        "Usage: gdh run-config show [target] <run-config-id>",
+        "Usage: gdh run-config check [target] <run-config-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value]",
+        "Usage: gdh run-config run [target] <run-config-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value] [--live-workspace]",
+    ].join("\n") + "\n");
+    return 1;
+}
+async function runBridgeCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh bridge <command> [target]",
+            "",
+            "Commands:",
+            "  status [target]                           Inspect the managed runtime bridge lifecycle state for one target.",
+            "  doctor [target]                           Alias for status with the same structured bridge-health report.",
+            "  install [target] [--dry-run]              Install the managed runtime bridge addon and autoload surfaces.",
+            "  repair [target] [--dry-run]               Rewrite drifted GDH-managed bridge files and autoload state.",
+            "  remove [target] [--dry-run]               Remove the GDH-managed bridge files and autoload entry.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "status") {
+        return runBridgeStatusCommand(rest, io);
+    }
+    if (subcommand === "doctor") {
+        return runBridgeStatusCommand(rest, io);
+    }
+    if (subcommand === "install") {
+        return runBridgeApplyCommand(rest, io, "install");
+    }
+    if (subcommand === "repair") {
+        return runBridgeApplyCommand(rest, io, "repair");
+    }
+    if (subcommand === "remove") {
+        return runBridgeApplyCommand(rest, io, "remove");
+    }
+    io.stderr.write([
+        `Unknown bridge command: ${subcommand}`,
+        "",
+        "Usage: gdh bridge status [target]",
+        "Usage: gdh bridge doctor [target]",
+        "Usage: gdh bridge install [target] [--dry-run]",
+        "Usage: gdh bridge repair [target] [--dry-run]",
+        "Usage: gdh bridge remove [target] [--dry-run]",
+    ].join("\n") + "\n");
+    return 1;
+}
+async function runScenarioCommand(args, io) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "--help" || subcommand === "help") {
+        io.stdout.write([
+            "Usage: gdh verification-scenario <command> [target] [verification-scenario-id]",
+            "",
+            "Commands:",
+            "  list [target]                              List verification scenarios discovered under .gdh/verification-scenarios as JSON.",
+            "  show [target] <verification-scenario-id>   Show one verification scenario as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    if (subcommand === "list") {
+        return runScenarioListCommand(rest, io);
+    }
+    if (subcommand === "show") {
+        return runScenarioShowCommand(rest, io);
+    }
+    io.stderr.write([
+        `Unknown verification-scenario command: ${subcommand}`,
+        "",
+        "Usage: gdh verification-scenario list [target]",
+        "Usage: gdh verification-scenario show [target] <verification-scenario-id>",
+    ].join("\n") + "\n");
+    return 1;
+}
+async function runMigrateCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh migrate [target] [--apply]",
+            "",
+            "Plan or apply the current GDH project-surface migrations for one target.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh migrate [target] [--apply]\n",
+        booleanOptions: ["--apply"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set(["--apply"]));
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh migrate accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const dryRun = !args.includes("--apply");
+    try {
+        const result = await migrateProjectLifecycleSurface({ targetPath, dryRun });
+        writeJsonResult(io, result, { presentRuntimeTerms: true });
+        return result.state === "blocked" ? 1 : 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to migrate "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runBridgeStatusCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh bridge status [target]",
+            "Usage: gdh bridge doctor [target]",
+            "",
+            "Inspect the managed runtime bridge lifecycle state for one target.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh bridge status [target]\nUsage: gdh bridge doctor [target]\n",
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set());
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh bridge status accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const commandStartedAtMs = Date.now();
+    try {
+        const projectConfig = await readProjectConfig(targetPath);
+        const result = await inspectRuntimeBridgeSurface({
+            targetPath,
+            projectConfig,
+        });
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "bridge_status",
+            command: "gdh bridge status",
+            state: result.state === "ready" ? "succeeded" : "blocked",
+            summary: result.summary,
+        });
+        writeJsonResult(io, result);
+        return result.state === "ready" ? 0 : 1;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "bridge_status",
+            command: "gdh bridge status",
+            state: "failed",
+            summary: "Runtime bridge status inspection failed before producing a result.",
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to inspect runtime bridge status for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runBridgeApplyCommand(args, io, operation) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            `Usage: gdh bridge ${operation} [target] [--dry-run]`,
+            "",
+            `Plan or apply the runtime bridge ${operation} flow for one target.`,
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: `Usage: gdh bridge ${operation} [target] [--dry-run]\n`,
+        booleanOptions: ["--dry-run"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set(["--dry-run"]));
+    if (positionalArgs.length > 1) {
+        io.stderr.write(`Usage error: gdh bridge ${operation} accepts at most one positional target path.\n`);
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const dryRun = args.includes("--dry-run");
+    const commandStartedAtMs = Date.now();
+    try {
+        const projectConfig = await readProjectConfig(targetPath);
+        const result = operation === "install"
+            ? await installRuntimeBridgeSurface({
+                targetPath,
+                projectConfig,
+                dryRun,
+            })
+            : operation === "repair"
+                ? await repairRuntimeBridgeSurface({
+                    targetPath,
+                    projectConfig,
+                    dryRun,
+                })
+                : await removeRuntimeBridgeSurface({
+                    targetPath,
+                    projectConfig,
+                    dryRun,
+                });
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: operation === "install"
+                ? "bridge_install"
+                : operation === "repair"
+                    ? "bridge_repair"
+                    : "bridge_remove",
+            command: `gdh bridge ${operation}`,
+            state: result.state === "blocked" ? "blocked" : "succeeded",
+            summary: result.summary,
+            producedArtifacts: dryRun || result.operation === "remove"
+                ? []
+                : result.actions
+                    .filter((action) => action.kind === "write_file")
+                    .map((action) => path.join(targetPath, action.relativePath)),
+        });
+        writeJsonResult(io, result);
+        return result.state === "blocked" ? 1 : 0;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: operation === "install"
+                ? "bridge_install"
+                : operation === "repair"
+                    ? "bridge_repair"
+                    : "bridge_remove",
+            command: `gdh bridge ${operation}`,
+            state: "failed",
+            summary: `Runtime bridge ${operation} failed before producing a result.`,
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to ${operation} runtime bridge for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runRecipeListCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh run-config list [target]",
+            "",
+            "List run configurations discovered under .gdh/run-configurations and print a JSON summary.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh run-config list [target]\n",
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractRecipePositionalArgs(args);
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh run-config list accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const commandStartedAtMs = Date.now();
+    try {
+        const projectConfig = await readProjectConfig(targetPath);
+        const result = await listRuntimeRecipes({
+            targetPath,
+            projectConfig,
+        });
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "recipe_list",
+            command: "gdh run-config list",
+            state: result.state === "ready" ? "succeeded" : "blocked",
+            summary: result.summary,
+        });
+        writeJsonResult(io, result, { presentRuntimeTerms: true });
+        return 0;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "recipe_list",
+            command: "gdh run-config list",
+            state: "failed",
+            summary: "Run-configuration listing failed before producing a result.",
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to list run configurations for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runRecipeShowCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh run-config show [target] <run-config-id>",
+            "",
+            "Show one run configuration and print the parsed result as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh run-config show [target] <run-config-id>\n",
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractRecipePositionalArgs(args);
+    if (positionalArgs.length === 0 || positionalArgs.length > 2) {
+        io.stderr.write("Usage error: gdh run-config show requires <run-config-id> and accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs.length === 1 ? "." : positionalArgs[0];
+    const recipeId = positionalArgs.length === 1 ? positionalArgs[0] : positionalArgs[1];
+    const commandStartedAtMs = Date.now();
+    try {
+        const projectConfig = await readProjectConfig(targetPath);
+        const result = await showRuntimeRecipe({
+            targetPath,
+            projectConfig,
+            recipeId,
+        });
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "recipe_show",
+            command: "gdh run-config show",
+            state: result.state === "ready" ? "succeeded" : "blocked",
+            summary: result.summary,
+        });
+        writeJsonResult(io, result, { presentRuntimeTerms: true });
+        return result.state === "ready" ? 0 : 1;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "recipe_show",
+            command: "gdh run-config show",
+            state: "failed",
+            summary: "Run-configuration inspection failed before producing a result.",
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to show run configuration "${recipeId}" for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runRecipeCheckCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh run-config check [target] <run-config-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value]",
+            "",
+            "Check whether a run configuration is runnable, blocked, or misconfigured and print the structured result as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh run-config check [target] <run-config-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value]\n",
+        optionsWithValues: ["--provider", "--param", "--feature", "--no-feature", "--env"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractRecipePositionalArgs(args);
+    if (positionalArgs.length === 0 || positionalArgs.length > 2) {
+        io.stderr.write("Usage error: gdh run-config check requires <run-config-id> and accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs.length === 1 ? "." : positionalArgs[0];
+    const recipeId = positionalArgs.length === 1 ? positionalArgs[0] : positionalArgs[1];
+    const commandStartedAtMs = Date.now();
+    try {
+        const projectConfig = await readProjectConfig(targetPath);
+        const result = await checkRuntimeRecipe({
+            targetPath,
+            projectConfig,
+            recipeId,
+            provider: readSingleOptionValue(args, "--provider"),
+            parameters: collectAssignmentOptionValues(args, "--param"),
+            enabledFeatures: collectOptionValues(args, "--feature"),
+            disabledFeatures: collectOptionValues(args, "--no-feature"),
+            environment: collectAssignmentOptionValues(args, "--env"),
+            workspaceMode: "isolated_copy",
+        });
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "recipe_check",
+            command: "gdh run-config check",
+            state: result.state === "runnable" ? "succeeded" : "blocked",
+            summary: result.summary,
+        });
+        writeJsonResult(io, result, { presentRuntimeTerms: true });
+        return result.state === "runnable" ? 0 : 1;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "recipe_check",
+            command: "gdh run-config check",
+            state: "failed",
+            summary: "Run-configuration readiness evaluation failed before producing a result.",
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to check run configuration "${recipeId}" for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runRecipeRunCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh run-config run [target] <run-config-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value] [--live-workspace]",
+            "",
+            "Run one run configuration and print structured process evidence as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh run-config run [target] <run-config-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value] [--live-workspace]\n",
+        optionsWithValues: ["--provider", "--param", "--feature", "--no-feature", "--env"],
+        booleanOptions: ["--live-workspace"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractRecipePositionalArgs(args);
+    if (positionalArgs.length === 0 || positionalArgs.length > 2) {
+        io.stderr.write("Usage error: gdh run-config run requires <run-config-id> and accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs.length === 1 ? "." : positionalArgs[0];
+    const recipeId = positionalArgs.length === 1 ? positionalArgs[0] : positionalArgs[1];
+    const commandStartedAtMs = Date.now();
+    try {
+        const projectConfig = await readProjectConfig(targetPath);
+        const result = await runRuntimeRecipe({
+            targetPath,
+            projectConfig,
+            recipeId,
+            provider: readSingleOptionValue(args, "--provider"),
+            parameters: collectAssignmentOptionValues(args, "--param"),
+            enabledFeatures: collectOptionValues(args, "--feature"),
+            disabledFeatures: collectOptionValues(args, "--no-feature"),
+            environment: collectAssignmentOptionValues(args, "--env"),
+            workspaceMode: args.includes("--live-workspace") ? "live_workspace" : "isolated_copy",
+        });
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "recipe_run",
+            command: "gdh run-config run",
+            state: result.state === "passed" ? "succeeded" : result.state === "blocked" ? "blocked" : "failed",
+            summary: result.summary,
+            producedArtifacts: result.artifacts.map((entry) => entry.path),
+        });
+        writeJsonResult(io, result, { presentRuntimeTerms: true });
+        return result.state === "passed" ? 0 : 1;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "recipe_run",
+            command: "gdh run-config run",
+            state: "failed",
+            summary: "Run-configuration execution failed before producing a result.",
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to run run configuration "${recipeId}" for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runScenarioListCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh verification-scenario list [target]",
+            "",
+            "List verification scenarios discovered under .gdh/verification-scenarios and print a JSON summary.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh verification-scenario list [target]\n",
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractRecipePositionalArgs(args);
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh verification-scenario list accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const commandStartedAtMs = Date.now();
+    try {
+        const result = await listRuntimeScenarios({ targetPath });
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "scenario_list",
+            command: "gdh verification-scenario list",
+            state: result.state === "ready" ? "succeeded" : "blocked",
+            summary: result.summary,
+        });
+        writeJsonResult(io, result, { presentRuntimeTerms: true });
+        return result.state === "ready" ? 0 : 1;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "scenario_list",
+            command: "gdh verification-scenario list",
+            state: "failed",
+            summary: "Verification-scenario listing failed before producing a result.",
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to list verification scenarios for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runScenarioShowCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh verification-scenario show [target] <verification-scenario-id>",
+            "",
+            "Show one verification scenario and print the parsed result as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh verification-scenario show [target] <verification-scenario-id>\n",
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractRecipePositionalArgs(args);
+    if (positionalArgs.length === 0 || positionalArgs.length > 2) {
+        io.stderr.write("Usage error: gdh verification-scenario show requires <verification-scenario-id> and accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs.length === 1 ? "." : positionalArgs[0];
+    const scenarioId = positionalArgs.length === 1 ? positionalArgs[0] : positionalArgs[1];
+    const commandStartedAtMs = Date.now();
+    try {
+        const result = await showRuntimeScenario({
+            targetPath,
+            scenarioId,
+        });
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "scenario_show",
+            command: "gdh verification-scenario show",
+            state: result.state === "ready" ? "succeeded" : "blocked",
+            summary: result.summary,
+        });
+        writeJsonResult(io, result, { presentRuntimeTerms: true });
+        return result.state === "ready" ? 0 : 1;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "scenario_show",
+            command: "gdh verification-scenario show",
+            state: "failed",
+            summary: "Verification-scenario inspection failed before producing a result.",
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to show verification scenario "${scenarioId}" for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runAdaptersStatusCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh adapters status [target] [--integration-root <path>]",
+            "",
+            "Inspect Codex, Claude, and Cursor reinforcement status, including repo-local and user-local MCP readiness, as JSON.",
+            "Use --integration-root when the agent-facing repo root differs from the nested GDH target root.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh adapters status [target] [--integration-root <path>]\n",
+        optionsWithValues: ["--integration-root"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set(["--integration-root"]));
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh adapters status accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const integrationRootPath = readSingleOptionValue(args, "--integration-root");
+    try {
+        const result = await getSupportedAgentAdaptersStatus(targetPath, {
+            integrationRootPath,
+        });
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to inspect adapter status for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runAdaptersInstallCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh adapters install [target] [--dry-run] [--agent <name>] [--user] [--dev-repo <path>] [--integration-root <path>]",
+            "",
+            "Install or repair supported-agent reinforcement surfaces while keeping AGENTS.md canonical.",
+            "--user installs user-local agent registration instead of repo-local surfaces.",
+            "Use --integration-root when the agent-facing repo root differs from the nested GDH target root.",
+            "Supported agents: codex, claude, cursor",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh adapters install [target] [--dry-run] [--agent <name>] [--user] [--dev-repo <path>] [--integration-root <path>]\n",
+        optionsWithValues: ["--agent", "--dev-repo", "--integration-root"],
+        booleanOptions: ["--dry-run", "--user"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const dryRun = args.includes("--dry-run");
+    const user = args.includes("--user");
+    const positionalArgs = extractPositionalArgs(args, new Set(["--agent", "--dev-repo", "--integration-root"]));
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh adapters install accepts at most one positional target path.\n");
+        return 1;
+    }
+    const agents = collectAdapterNames(args);
+    if (agents === null) {
+        io.stderr.write("Usage error: --agent must be one of codex, claude, or cursor.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const devRepoPath = readSingleOptionValue(args, "--dev-repo");
+    const integrationRootPath = readSingleOptionValue(args, "--integration-root");
+    try {
+        const result = await installSupportedAgentAdapters(targetPath, {
+            dryRun,
+            agents,
+            user,
+            devRepoPath: devRepoPath ?? resolveCurrentGdhInstall(import.meta.url).defaultDevRepoPath,
+            integrationRootPath,
+        });
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return result.state === "blocked" ? 1 : 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to install adapters for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runGsdSnapshotCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh adapters gsd snapshot [target] [--files <path>] [--performed <kind>]",
+            "",
+            "Export a read-mostly GSD projection over current GDH status, guidance, and validation surfaces as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh adapters gsd snapshot [target] [--files <path>] [--performed <kind>]\n",
+        optionsWithValues: ["--files", "--performed"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set(["--files", "--performed"]));
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh adapters gsd snapshot accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    try {
+        const result = await createGsdSnapshot(targetPath, {
+            files: collectOptionValues(args, "--files"),
+            performed: collectPerformedValidationKinds(args),
+        });
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to create a GSD snapshot for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runMcpManifestCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write(["Usage: gdh mcp manifest", "", "Print the thin GDH MCP manifest as JSON."].join("\n") + "\n");
+        return 0;
+    }
+    io.stdout.write(`${JSON.stringify(createMcpManifest(), null, 2)}\n`);
+    return 0;
+}
+async function runMcpServeCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh mcp serve --target <path>",
+            "",
+            "Run the real GDH stdio MCP server for one bound target path.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh mcp serve --target <path>\n",
+        optionsWithValues: ["--target"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const targetPath = readSingleOptionValue(args, "--target");
+    if (targetPath === null) {
+        io.stderr.write("Usage error: gdh mcp serve requires --target <path>.\n");
+        return 1;
+    }
+    if (extractPositionalArgs(args, new Set(["--target"])).length > 0) {
+        io.stderr.write("Usage error: gdh mcp serve accepts only --target <path>.\n");
+        return 1;
+    }
+    try {
+        await serveMcpOverStdio(targetPath);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to start the GDH MCP server for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runMcpInvokeCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh mcp invoke <tool> [target] [--input-json <json>]",
+            "",
+            "Invoke one GDH MCP tool through the local registry and print the result envelope as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const [toolName, ...rest] = args;
+    if (!toolName) {
+        io.stderr.write("Usage error: gdh mcp invoke requires a <tool> name.\n");
+        return 1;
+    }
+    const manifest = createMcpManifest();
+    if (!manifest.tools.some((tool) => tool.name === toolName)) {
+        io.stderr.write(`Usage error: unknown MCP tool "${toolName}". Run \`gdh mcp manifest\` to inspect supported tools.\n`);
+        return 1;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(rest, {
+        usage: "Usage: gdh mcp invoke <tool> [target] [--input-json <json>]\n",
+        optionsWithValues: ["--input-json"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(rest, new Set(["--input-json"]));
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh mcp invoke accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    try {
+        const result = await invokeMcpTool({
+            toolName: toolName,
+            targetPath,
+            input: parseMcpInputJson(args),
+        });
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return result.state === "succeeded" ? 0 : 1;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to invoke MCP tool "${toolName}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+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,
+    };
+}
+async function runVerifyRecommendCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh verify recommend [target] --files <path> [--files <path>...]",
+            "",
+            "Recommend authoring-first validation requirements for the supplied change set as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh verify recommend [target] --files <path> [--files <path>...]\n",
+        optionsWithValues: ["--files"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set(["--files"]));
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh verify recommend accepts at most one positional target path.\n");
+        return 1;
+    }
+    const files = collectOptionValues(args, "--files");
+    if (files.length === 0) {
+        io.stderr.write("Usage error: gdh verify recommend requires at least one --files <path> argument.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const commandStartedAtMs = Date.now();
+    try {
+        const context = await buildAuthoringContext(targetPath);
+        const result = await recommendValidationForChange({
+            targetPath,
+            inventory: context.inventory,
+            status: context.status,
+            projectConfig: context.projectConfig,
+            files,
+        });
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "verify_recommend",
+            command: "gdh verify recommend",
+            state: result.recommendations.length === 0 ? "blocked" : "succeeded",
+            summary: result.summary,
+            changedFiles: files,
+            guidance: buildGuidanceSnapshot(result.guidance),
+            validation: {
+                changedFiles: files,
+                recommendedKinds: result.recommendations.map((item) => item.kind),
+                performedKinds: [],
+            },
+        });
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "verify_recommend",
+            command: "gdh verify recommend",
+            state: "failed",
+            summary: "Validation recommendation failed before producing a result.",
+            changedFiles: files,
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to recommend validation for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runVerifyDoneCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh verify done [target] --files <path> [--files <path>...] [--performed <kind>]",
+            "",
+            "Evaluate whether the supplied change set is eligible to be called done as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh verify done [target] --files <path> [--files <path>...] [--performed <kind>]\n",
+        optionsWithValues: ["--files", "--performed"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set(["--files", "--performed"]));
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh verify done accepts at most one positional target path.\n");
+        return 1;
+    }
+    const files = collectOptionValues(args, "--files");
+    if (files.length === 0) {
+        io.stderr.write("Usage error: gdh verify done requires at least one --files <path> argument.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const commandStartedAtMs = Date.now();
+    try {
+        const context = await buildAuthoringContext(targetPath);
+        const result = await evaluateDonePolicy({
+            targetPath,
+            inventory: context.inventory,
+            status: context.status,
+            projectConfig: context.projectConfig,
+            files,
+            performed: collectPerformedValidationKinds(args),
+        });
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "verify_done",
+            command: "gdh verify done",
+            state: result.status === "done" ? "succeeded" : "blocked",
+            summary: result.summary,
+            changedFiles: files,
+            guidance: buildGuidanceSnapshot(result.recommendation.guidance),
+            validation: {
+                changedFiles: files,
+                recommendedKinds: result.recommendation.recommendations.map((item) => item.kind),
+                performedKinds: result.performedValidations.map((item) => item.kind),
+            },
+        });
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "verify_done",
+            command: "gdh verify done",
+            state: "failed",
+            summary: "Done-policy evaluation failed before producing a result.",
+            changedFiles: files,
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to evaluate done policy for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runVerifyRunCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh verify run [target] <run-config-id> --verification-scenario <verification-scenario-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value] [--live-workspace]",
+            "",
+            "Execute one verification scenario over a selected run configuration and print the structured run record as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh verify run [target] <run-config-id> --verification-scenario <verification-scenario-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value] [--live-workspace]\n",
+        optionsWithValues: [
+            "--verification-scenario",
+            "--scenario",
+            "--provider",
+            "--param",
+            "--feature",
+            "--no-feature",
+            "--env",
+        ],
+        booleanOptions: ["--live-workspace"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set([
+        "--verification-scenario",
+        "--scenario",
+        "--provider",
+        "--param",
+        "--feature",
+        "--no-feature",
+        "--env",
+    ]));
+    if (positionalArgs.length === 0 || positionalArgs.length > 2) {
+        io.stderr.write("Usage error: gdh verify run requires <run-config-id> and accepts at most one positional target path.\n");
+        return 1;
+    }
+    const scenarioId = readSingleOptionValue(args, "--verification-scenario") ??
+        readSingleOptionValue(args, "--scenario");
+    if (!scenarioId) {
+        io.stderr.write("Usage error: gdh verify run requires --verification-scenario <verification-scenario-id>.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs.length === 1 ? "." : positionalArgs[0];
+    const recipeId = positionalArgs.length === 1 ? positionalArgs[0] : positionalArgs[1];
+    const commandStartedAtMs = Date.now();
+    try {
+        const projectConfig = await readProjectConfig(targetPath);
+        const result = await runRuntimeVerificationScenario({
+            targetPath,
+            projectConfig,
+            recipeId,
+            scenarioId,
+            provider: readSingleOptionValue(args, "--provider"),
+            parameters: collectAssignmentOptionValues(args, "--param"),
+            enabledFeatures: collectOptionValues(args, "--feature"),
+            disabledFeatures: collectOptionValues(args, "--no-feature"),
+            environment: collectAssignmentOptionValues(args, "--env"),
+            workspaceMode: args.includes("--live-workspace") ? "live_workspace" : "isolated_copy",
+        });
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "verify_run",
+            command: "gdh verify run",
+            state: result.outcome === "passed" || result.outcome === "flaky"
+                ? "succeeded"
+                : result.outcome === "blocked"
+                    ? "blocked"
+                    : "failed",
+            summary: result.summary,
+            producedArtifacts: result.artifacts.map((entry) => entry.path),
+        });
+        writeJsonResult(io, result, { presentRuntimeTerms: true });
+        return result.outcome === "passed" || result.outcome === "flaky" ? 0 : 1;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "verify_run",
+            command: "gdh verify run",
+            state: "failed",
+            summary: "Verification-scenario execution failed before producing a result.",
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to run runtime verification for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runVerifyInspectCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh verify inspect [target] [--run-record <run-record-id>]",
+            "",
+            "Inspect the latest or selected runtime run record and print the structured result as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh verify inspect [target] [--run-record <run-record-id>]\n",
+        optionsWithValues: ["--run-record", "--bundle"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set(["--run-record", "--bundle"]));
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh verify inspect accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const commandStartedAtMs = Date.now();
+    try {
+        const result = await inspectRuntimeVerificationBundleState({
+            targetPath,
+            bundleId: readSingleOptionValue(args, "--run-record") ?? readSingleOptionValue(args, "--bundle"),
+        });
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "verify_inspect",
+            command: "gdh verify inspect",
+            state: result.state === "available" ? "succeeded" : "blocked",
+            summary: result.summary,
+            producedArtifacts: result.bundle === null ? [] : [path.join(result.bundle.bundlePath, "bundle.json")],
+        });
+        writeJsonResult(io, result, { presentRuntimeTerms: true });
+        return result.state === "available" ? 0 : 1;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "verify_inspect",
+            command: "gdh verify inspect",
+            state: "failed",
+            summary: "Runtime run-record inspection failed before producing a result.",
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to inspect runtime verification run records for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runVerifyReadinessCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh verify readiness [target]",
+            "",
+            "Summarize runtime verification readiness, stale evidence, and recurring runtime feedback for one target as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh verify readiness [target]\n",
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set());
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh verify readiness accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const commandStartedAtMs = Date.now();
+    try {
+        const projectConfig = await readProjectConfig(targetPath);
+        const result = await inspectRuntimeVerificationReadiness({
+            targetPath,
+            projectConfig,
+        });
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "verify_readiness",
+            command: "gdh verify readiness",
+            state: result.state === "ready" ? "succeeded" : result.state === "blocked" ? "blocked" : "failed",
+            summary: result.summary,
+            producedArtifacts: result.latestBundle?.bundle == null
+                ? []
+                : [path.join(result.latestBundle.bundle.bundlePath, "bundle.json")],
+        });
+        writeJsonResult(io, result, { presentRuntimeTerms: true });
+        return result.state === "ready" ? 0 : 1;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "verify_readiness",
+            command: "gdh verify readiness",
+            state: "failed",
+            summary: "Runtime verification readiness inspection failed before producing a result.",
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to inspect runtime verification readiness for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runVerifyCorpusStatusCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh verify corpus status [--manifest <path>] [--workspace-root <path>]",
+            "",
+            "Inspect runtime corpus release-readiness evidence and print a structured result as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh verify corpus status [--manifest <path>] [--workspace-root <path>]\n",
+        optionsWithValues: ["--manifest", "--workspace-root"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set(["--manifest", "--workspace-root"]));
+    if (positionalArgs.length > 0) {
+        io.stderr.write("Usage error: gdh verify corpus status only accepts --manifest <path> and --workspace-root <path>.\n");
+        return 1;
+    }
+    const workspaceRoot = readSingleOptionValue(args, "--workspace-root") ?? ".";
+    const manifestPath = readSingleOptionValue(args, "--manifest") ?? "fixtures/runtime-corpus.json";
+    try {
+        const result = await inspectRuntimeCorpusStatus({
+            workspaceRoot,
+            manifestPath,
+        });
+        writeJsonResult(io, result, { presentRuntimeTerms: true });
+        return result.state === "ready" ? 0 : 1;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to inspect runtime corpus status: ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runVerifyCorpusMaterializeCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh verify corpus materialize --entry <id> [--manifest <path>] [--workspace-root <path>]",
+            "",
+            "Materialize one runtime corpus entry into GDH-managed source state and print a structured result as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh verify corpus materialize --entry <id> [--manifest <path>] [--workspace-root <path>]\n",
+        optionsWithValues: ["--entry", "--manifest", "--workspace-root"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set(["--entry", "--manifest", "--workspace-root"]));
+    if (positionalArgs.length > 0) {
+        io.stderr.write("Usage error: gdh verify corpus materialize only accepts --entry <id>, optional --manifest <path>, and optional --workspace-root <path>.\n");
+        return 1;
+    }
+    const entryId = readSingleOptionValue(args, "--entry");
+    if (!entryId) {
+        io.stderr.write("Usage error: gdh verify corpus materialize requires --entry <id>.\n");
+        return 1;
+    }
+    const workspaceRoot = readSingleOptionValue(args, "--workspace-root") ?? ".";
+    const manifestPath = readSingleOptionValue(args, "--manifest") ?? "fixtures/runtime-corpus.json";
+    try {
+        const result = await materializeRuntimeCorpusEntry({
+            workspaceRoot,
+            manifestPath,
+            entryId,
+        });
+        writeJsonResult(io, result, { presentRuntimeTerms: true });
+        return result.state === "ready" ? 0 : 1;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to materialize runtime corpus entry: ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runVerifyCorpusExerciseCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh verify corpus exercise --entry <id> [--manifest <path>] [--workspace-root <path>] [--no-prepare]",
+            "",
+            "Materialize, onboard, and exercise one runtime corpus entry through GDH and print a structured result as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh verify corpus exercise --entry <id> [--manifest <path>] [--workspace-root <path>] [--no-prepare]\n",
+        optionsWithValues: ["--entry", "--manifest", "--workspace-root"],
+        booleanOptions: ["--no-prepare"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set(["--entry", "--manifest", "--workspace-root", "--no-prepare"]));
+    if (positionalArgs.length > 0) {
+        io.stderr.write("Usage error: gdh verify corpus exercise only accepts --entry <id>, optional --manifest <path>, optional --workspace-root <path>, and optional --no-prepare.\n");
+        return 1;
+    }
+    const entryId = readSingleOptionValue(args, "--entry");
+    if (!entryId) {
+        io.stderr.write("Usage error: gdh verify corpus exercise requires --entry <id>.\n");
+        return 1;
+    }
+    const workspaceRoot = readSingleOptionValue(args, "--workspace-root") ?? ".";
+    const manifestPath = readSingleOptionValue(args, "--manifest") ?? "fixtures/runtime-corpus.json";
+    try {
+        const result = await exerciseRuntimeCorpusEntry({
+            workspaceRoot,
+            manifestPath,
+            entryId,
+            skipPrepare: args.includes("--no-prepare"),
+        });
+        writeJsonResult(io, result, { presentRuntimeTerms: true });
+        return result.state === "ready" ? 0 : 1;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to exercise runtime corpus entry: ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runVerifyCorpusRecordCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh verify corpus record --entry <id> --target <path> [--manifest <path>] [--workspace-root <path>]",
+            "",
+            "Record the current runtime verification readiness for one corpus entry as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh verify corpus record --entry <id> --target <path> [--manifest <path>] [--workspace-root <path>]\n",
+        optionsWithValues: ["--entry", "--target", "--manifest", "--workspace-root"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set(["--entry", "--target", "--manifest", "--workspace-root"]));
+    if (positionalArgs.length > 0) {
+        io.stderr.write("Usage error: gdh verify corpus record only accepts --entry <id>, --target <path>, optional --manifest <path>, and optional --workspace-root <path>.\n");
+        return 1;
+    }
+    const entryId = readSingleOptionValue(args, "--entry");
+    const targetPath = readSingleOptionValue(args, "--target");
+    if (!entryId || !targetPath) {
+        io.stderr.write("Usage error: gdh verify corpus record requires --entry <id> and --target <path>.\n");
+        return 1;
+    }
+    const workspaceRoot = readSingleOptionValue(args, "--workspace-root") ?? ".";
+    const manifestPath = readSingleOptionValue(args, "--manifest") ?? "fixtures/runtime-corpus.json";
+    try {
+        const projectConfig = await readProjectConfig(targetPath);
+        const result = await recordRuntimeCorpusValidation({
+            workspaceRoot,
+            manifestPath,
+            entryId,
+            targetPath,
+            projectConfig,
+        });
+        writeJsonResult(io, result, { presentRuntimeTerms: true });
+        return result.state === "recorded" ? 0 : 1;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to record runtime corpus validation: ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runCacheInspectCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh cache inspect [target]",
+            "",
+            "Inspect worktree-local and project-scoped authoring cache state and print a structured result as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh cache inspect [target]\n",
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractGuidanceResolvePositionalArgs(args);
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh cache inspect accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    try {
+        const context = await buildAuthoringContext(targetPath);
+        const result = await inspectCacheState({
+            targetPath,
+            status: context.status,
+            projectConfig: context.projectConfig,
+        });
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to inspect cache state for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runGuidanceStatusCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh guidance status [target]",
+            "",
+            "Inspect the current durable guidance surface and guidance-audit availability as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh guidance status [target]\n",
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = args.filter((arg) => !arg.startsWith("--"));
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh guidance status accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const commandStartedAtMs = Date.now();
+    try {
+        const context = await buildAuthoringContext(targetPath);
+        const effectiveRepoState = deriveGuidanceRepoState(context);
+        const [guidance, audit] = await Promise.all([
+            getGuidanceStatus(targetPath),
+            inspectGuidanceAudit(targetPath),
+        ]);
+        const result = {
+            targetPath,
+            projectConfigPresent: context.projectConfig !== null,
+            authoringReadiness: context.status.readiness,
+            effectiveRepoState,
+            guidance,
+            audit,
+        };
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "guidance_status",
+            command: "gdh guidance status",
+            state: guidance.state === "missing" ? "blocked" : "succeeded",
+            summary: guidance.summary,
+            guidance: {
+                effectiveRepoState,
+                requiredUnitIds: [],
+                recommendedUnitIds: [],
+            },
+        });
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "guidance_status",
+            command: "gdh guidance status",
+            state: "failed",
+            summary: "Guidance status inspection failed before producing a result.",
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to inspect guidance status for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runGuidanceResolveCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh guidance resolve [target] [--task-type <type>] [--capability <id>] [--repo-state <state>] [--keyword <term>]",
+            "",
+            "Resolve eligible deeper guidance units for the supplied task and repo-state context as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh guidance resolve [target] [--task-type <type>] [--capability <id>] [--repo-state <state>] [--keyword <term>]\n",
+        optionsWithValues: ["--task-type", "--capability", "--repo-state", "--keyword"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractGuidanceResolvePositionalArgs(args);
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh guidance resolve accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const commandStartedAtMs = Date.now();
+    try {
+        const context = await buildAuthoringContext(targetPath);
+        const derivedRepoState = deriveGuidanceRepoState(context);
+        const repoStateArgs = collectOptionValues(args, "--repo-state");
+        const result = await resolveGuidanceQuery(targetPath, {
+            taskTypes: collectOptionValues(args, "--task-type"),
+            capabilities: collectOptionValues(args, "--capability"),
+            repoState: repoStateArgs.length > 0 ? repoStateArgs : derivedRepoState,
+            keywords: collectOptionValues(args, "--keyword"),
+        });
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "guidance_resolve",
+            command: "gdh guidance resolve",
+            state: result.requiredUnits.length > 0 || result.recommendedUnits.length > 0
+                ? "succeeded"
+                : "blocked",
+            summary: result.status.summary,
+            guidance: buildGuidanceSnapshot(result),
+        });
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            commandStartedAtMs,
+            kind: "guidance_resolve",
+            command: "gdh guidance resolve",
+            state: "failed",
+            summary: "Guidance resolution failed before producing a result.",
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to resolve guidance for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runGuidanceAuditCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh guidance audit [target]",
+            "",
+            "Inspect machine-readable guidance-audit history as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh guidance audit [target]\n",
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = args.filter((arg) => !arg.startsWith("--"));
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh guidance audit accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    try {
+        const result = await inspectGuidanceAudit(targetPath);
+        await recordSessionEvent(targetPath, {
+            kind: "guidance_audit",
+            command: "gdh guidance audit",
+            state: result.state === "available" ? "succeeded" : "blocked",
+            summary: result.summary,
+        });
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        await recordSessionEvent(targetPath, {
+            kind: "guidance_audit",
+            command: "gdh guidance audit",
+            state: "failed",
+            summary: "Guidance-audit inspection failed before producing a result.",
+            errorMessage: formatCliError(error),
+        });
+        io.stderr.write(`Failed to inspect guidance audit for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runObservabilitySessionCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh observability session [target] [--latest] [--session-id <id>]",
+            "",
+            "Inspect recorded authoring-session observability as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh observability session [target] [--latest] [--session-id <id>]\n",
+        optionsWithValues: ["--session-id"],
+        booleanOptions: ["--latest"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set(["--session-id"]));
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh observability session accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const sessionId = readSingleOptionValue(args, "--session-id");
+    try {
+        const result = await inspectAuthoringSessions(targetPath, {
+            latest: args.includes("--latest") || sessionId === null,
+            sessionId,
+        });
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to inspect authoring-session observability for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runObservabilityEffectivenessCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh observability effectiveness [target] [--latest] [--session-id <id>]",
+            "",
+            "Summarize heuristic agent-effectiveness signals from recorded session activity as JSON.",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh observability effectiveness [target] [--latest] [--session-id <id>]\n",
+        optionsWithValues: ["--session-id"],
+        booleanOptions: ["--latest"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const positionalArgs = extractPositionalArgs(args, new Set(["--session-id"]));
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh observability effectiveness accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    const sessionId = readSingleOptionValue(args, "--session-id");
+    try {
+        const result = await inspectAuthoringEffectiveness(targetPath, {
+            latest: args.includes("--latest") || sessionId === null,
+            sessionId,
+        });
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to inspect authoring effectiveness for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runCachePruneCommand(args, io) {
+    if (args.includes("--help")) {
+        io.stdout.write([
+            "Usage: gdh cache prune [target] [--scope <scope>] [--dry-run]",
+            "",
+            "Prune worktree-local or project-scoped authoring cache state and print a structured result as JSON.",
+            "Supported scopes: worktree, project, all",
+        ].join("\n") + "\n");
+        return 0;
+    }
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: "Usage: gdh cache prune [target] [--scope <scope>] [--dry-run]\n",
+        optionsWithValues: ["--scope"],
+        booleanOptions: ["--dry-run"],
+    });
+    if (unsupportedOptionsError !== null) {
+        io.stderr.write(unsupportedOptionsError);
+        return 1;
+    }
+    const dryRun = args.includes("--dry-run");
+    const positionalArgs = extractCachePrunePositionalArgs(args);
+    const scope = resolveCachePruneScope(args);
+    if (scope === null) {
+        io.stderr.write("Usage error: --scope must be one of worktree, project, or all.\n");
+        return 1;
+    }
+    if (positionalArgs.length > 1) {
+        io.stderr.write("Usage error: gdh cache prune accepts at most one positional target path.\n");
+        return 1;
+    }
+    const targetPath = positionalArgs[0] ?? ".";
+    try {
+        const context = await buildAuthoringContext(targetPath);
+        const result = await pruneCacheState({
+            targetPath,
+            status: context.status,
+            projectConfig: context.projectConfig,
+            scope,
+            dryRun,
+        });
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`Failed to prune cache state for "${targetPath}": ${formatCliError(error)}\n`);
+        return 1;
+    }
+}
+async function runAuthoringDogfood(input) {
+    const results = [];
+    for (const fixtureTarget of input.fixtureTargets) {
+        results.push(await executeAuthoringDogfoodTarget({
+            kind: "fixture",
+            sourcePath: fixtureTarget,
+        }));
+    }
+    if (input.pilotTarget !== null) {
+        results.push(await executeAuthoringDogfoodTarget({
+            kind: "pilot",
+            sourcePath: input.pilotTarget,
+        }));
+    }
+    const state = summarizeAuthoringDogfoodState(results);
+    return {
+        version: GDH_AUTHORING_DOGFOOD_VERSION,
+        generatedAt: new Date().toISOString(),
+        state,
+        summary: summarizeAuthoringDogfoodResults(results, state),
+        fixtureTargets: input.fixtureTargets.map((target) => path.resolve(target)),
+        pilotTarget: input.pilotTarget === null ? null : path.resolve(input.pilotTarget),
+        results,
+    };
+}
+async function runAuthoringSliceDoctor(targetPath) {
+    const dogfood = await executeAuthoringDogfoodTarget({
+        kind: "fixture",
+        sourcePath: targetPath,
+    });
+    if (dogfood.state === "failed") {
+        return {
+            version: GDH_AUTHORING_SLICE_REPORT_VERSION,
+            generatedAt: new Date().toISOString(),
+            targetPath: path.resolve(targetPath),
+            state: "failed",
+            summary: "The authoring-first slice report failed before GDH could establish a trustworthy baseline.",
+            failureClass: "harness_gap",
+            reasons: dogfood.errorMessage ? [dogfood.errorMessage] : ["dogfood_failed"],
+            adapters: null,
+            dogfood,
+            authoringCheck: null,
+            donePolicy: null,
+        };
+    }
+    if (dogfood.state === "blocked" ||
+        dogfood.onboarding === null ||
+        dogfood.status === null ||
+        dogfood.validationRecommendation === null) {
+        const classification = classifyBlockedDogfoodResult(dogfood);
+        return {
+            version: GDH_AUTHORING_SLICE_REPORT_VERSION,
+            generatedAt: new Date().toISOString(),
+            targetPath: path.resolve(targetPath),
+            state: "blocked",
+            summary: "The authoring-first slice is blocked before internal-use validation can complete.",
+            failureClass: classification.failureClass,
+            reasons: classification.reasons,
+            adapters: null,
+            dogfood,
+            authoringCheck: null,
+            donePolicy: null,
+        };
+    }
+    const validation = await evaluateAuthoringSliceValidation(targetPath);
+    const classification = classifyAuthoringSliceValidation({
+        dogfood,
+        adapters: validation.adapters,
+        authoringCheck: validation.authoringCheck,
+        donePolicy: validation.donePolicy,
+    });
+    return {
+        version: GDH_AUTHORING_SLICE_REPORT_VERSION,
+        generatedAt: new Date().toISOString(),
+        targetPath: path.resolve(targetPath),
+        state: classification.state,
+        summary: classification.summary,
+        failureClass: classification.failureClass,
+        reasons: classification.reasons,
+        adapters: validation.adapters,
+        dogfood,
+        authoringCheck: validation.authoringCheck,
+        donePolicy: validation.donePolicy,
+    };
+}
+async function executeAuthoringDogfoodTarget(input) {
+    const sourcePath = path.resolve(input.sourcePath);
+    const target = {
+        kind: input.kind,
+        sourcePath,
+        executionStrategy: "temporary_copy",
+    };
+    if (!(await pathExists(sourcePath))) {
+        const summary = input.kind === "pilot"
+            ? `The requested pilot target "${sourcePath}" is unavailable.`
+            : `The requested fixture target "${sourcePath}" does not exist.`;
+        return {
+            target,
+            state: input.kind === "pilot" ? "blocked" : "failed",
+            summary,
+            changedFiles: [],
+            inventory: null,
+            onboarding: null,
+            status: null,
+            guidanceStatus: null,
+            guidanceResolve: null,
+            validationRecommendation: null,
+            sessionInspection: null,
+            blockedReason: input.kind === "pilot" ? "pilot_target_missing" : "fixture_target_missing",
+            errorMessage: null,
+        };
+    }
+    const workingCopy = await createDogfoodWorkingCopy(sourcePath);
+    const sessionId = createDogfoodSessionId(input.kind, sourcePath);
+    try {
+        const projectConfigPresent = await pathExists(path.join(workingCopy.targetPath, ".gdh/project.yaml"));
+        const hasExistingOnboarding = await hasCompleteOnboardingSurface(workingCopy.targetPath);
+        const onboarding = await onboardGodotProject(workingCopy.targetPath, {
+            dryRun: hasExistingOnboarding || projectConfigPresent,
+        });
+        const repairedOnboardingSurface = projectConfigPresent && !hasExistingOnboarding;
+        const appliedRepairWrites = repairedOnboardingSurface
+            ? await applyRepairableOnboardingWrites(onboarding.writes)
+            : [];
+        await recordAuthoringSessionEvent(workingCopy.targetPath, {
+            sessionId,
+            kind: "onboard",
+            command: "gdh onboard",
+            state: onboarding.status === "ready" ? "succeeded" : "blocked",
+            summary: onboarding.status !== "ready"
+                ? "Dogfood onboarding surfaced unresolved gaps for the target."
+                : repairedOnboardingSurface
+                    ? "Dogfood repaired missing GDH surfaces without rewriting existing durable project truth."
+                    : hasExistingOnboarding
+                        ? "Dogfood verified the existing GDH onboarding surfaces without rewriting durable project truth."
+                        : "Dogfood onboarding completed durable GDH surfaces for the target.",
+            producedArtifacts: hasExistingOnboarding
+                ? []
+                : (repairedOnboardingSurface ? appliedRepairWrites : onboarding.writes).map((entry) => entry.relativePath),
+        });
+        if (onboarding.status !== "ready" || onboarding.selectedProject === null) {
+            const sessionInspection = await inspectAuthoringSessions(workingCopy.targetPath, {
+                sessionId,
+            });
+            return {
+                target,
+                state: "blocked",
+                summary: onboarding.status === "ready"
+                    ? "Dogfood could not select a concrete Godot project root for this target."
+                    : "Dogfood onboarding remained unresolved for this target.",
+                changedFiles: [],
+                inventory: onboarding.inventory,
+                onboarding,
+                status: null,
+                guidanceStatus: null,
+                guidanceResolve: null,
+                validationRecommendation: null,
+                sessionInspection,
+                blockedReason: onboarding.status === "ready" ? "selected_project_missing" : "onboarding_unresolved",
+                errorMessage: null,
+            };
+        }
+        const context = await buildAuthoringContext(workingCopy.targetPath);
+        await recordAuthoringSessionEvent(workingCopy.targetPath, {
+            sessionId,
+            kind: "status",
+            command: "gdh status",
+            state: context.status.readiness === "undetected" ? "blocked" : "succeeded",
+            summary: context.status.summary,
+        });
+        const guidanceStatus = await getGuidanceStatus(workingCopy.targetPath);
+        await recordAuthoringSessionEvent(workingCopy.targetPath, {
+            sessionId,
+            kind: "guidance_status",
+            command: "gdh guidance status",
+            state: guidanceStatus.state === "ready" ? "succeeded" : "blocked",
+            summary: guidanceStatus.summary,
+        });
+        const changedFiles = deriveDogfoodChangedFiles(onboarding.selectedProject);
+        if (changedFiles.length === 0) {
+            const sessionInspection = await inspectAuthoringSessions(workingCopy.targetPath, {
+                sessionId,
+            });
+            return {
+                target,
+                state: "blocked",
+                summary: "Dogfood could not derive a representative authoring change set from the detected project inventory.",
+                changedFiles,
+                inventory: onboarding.inventory,
+                onboarding,
+                status: context.status,
+                guidanceStatus,
+                guidanceResolve: null,
+                validationRecommendation: null,
+                sessionInspection,
+                blockedReason: "no_representative_changed_files",
+                errorMessage: null,
+            };
+        }
+        const validationRecommendation = await recommendValidationForChange({
+            targetPath: workingCopy.targetPath,
+            inventory: context.inventory,
+            status: context.status,
+            projectConfig: context.projectConfig,
+            files: changedFiles,
+        });
+        await recordAuthoringSessionEvent(workingCopy.targetPath, {
+            sessionId,
+            kind: "guidance_resolve",
+            command: "gdh guidance resolve",
+            state: validationRecommendation.guidance.requiredUnits.length > 0 ||
+                validationRecommendation.guidance.recommendedUnits.length > 0
+                ? "succeeded"
+                : "blocked",
+            summary: validationRecommendation.guidance.status.summary,
+            guidance: buildGuidanceSnapshot(validationRecommendation.guidance),
+            changedFiles,
+        });
+        await recordAuthoringSessionEvent(workingCopy.targetPath, {
+            sessionId,
+            kind: "verify_recommend",
+            command: "gdh verify recommend",
+            state: validationRecommendation.recommendations.length > 0 ? "succeeded" : "blocked",
+            summary: validationRecommendation.summary,
+            changedFiles,
+            guidance: buildGuidanceSnapshot(validationRecommendation.guidance),
+            validation: {
+                changedFiles,
+                recommendedKinds: validationRecommendation.recommendations.map((item) => item.kind),
+                performedKinds: [],
+            },
+        });
+        const sessionInspection = await inspectAuthoringSessions(workingCopy.targetPath, {
+            sessionId,
+        });
+        const state = isHealthyDogfoodTarget({
+            readiness: context.status.readiness,
+            guidanceState: guidanceStatus.state,
+            recommendationCount: validationRecommendation.recommendations.length,
+            sessionState: sessionInspection.state,
+        })
+            ? "passed"
+            : "blocked";
+        return {
+            target,
+            state,
+            summary: state === "passed"
+                ? "Dogfood exercised onboarding, readiness, guidance, validation recommendation, and session evidence successfully."
+                : "Dogfood exercised the target, but one or more authoring-slice surfaces stayed blocked or incomplete.",
+            changedFiles,
+            inventory: onboarding.inventory,
+            onboarding,
+            status: context.status,
+            guidanceStatus,
+            guidanceResolve: validationRecommendation.guidance,
+            validationRecommendation,
+            sessionInspection,
+            blockedReason: state === "passed" ? null : "authoring_slice_incomplete",
+            errorMessage: null,
+        };
+    }
+    catch (error) {
+        return {
+            target,
+            state: "failed",
+            summary: "Dogfood execution failed before the target report could complete.",
+            changedFiles: [],
+            inventory: null,
+            onboarding: null,
+            status: null,
+            guidanceStatus: null,
+            guidanceResolve: null,
+            validationRecommendation: null,
+            sessionInspection: null,
+            blockedReason: null,
+            errorMessage: formatCliError(error),
+        };
+    }
+    finally {
+        await fs.rm(workingCopy.tempRoot, { recursive: true, force: true });
+    }
+}
+async function createDogfoodWorkingCopy(sourcePath) {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "gdh-dogfood-"));
+    const targetPath = path.join(tempRoot, "target");
+    await fs.cp(sourcePath, targetPath, {
+        recursive: true,
+        verbatimSymlinks: true,
+        filter: async (currentSourcePath) => {
+            const relativePath = path.relative(sourcePath, currentSourcePath);
+            return shouldCopyDisposableTargetPath(relativePath);
+        },
+    });
+    return { tempRoot, targetPath };
+}
+function deriveDogfoodChangedFiles(project) {
+    const prefix = project.relativePath === "." ? "" : `${project.relativePath}/`;
+    const candidate = project.scenes[0]?.path ??
+        project.autoloads[0]?.scriptPath ??
+        project.tests[0]?.path ??
+        path.relative(project.rootPath, project.projectFilePath);
+    if (!candidate) {
+        return [];
+    }
+    return [normalizeRelativePath(`${prefix}${candidate}`)];
+}
+function shouldCopyDisposableTargetPath(relativePath) {
+    const normalized = normalizeRelativePath(relativePath);
+    if (normalized === "") {
+        return true;
+    }
+    if (normalized === ".gdh-state" || normalized === ".gdh-state/local-paths.json") {
+        return true;
+    }
+    return !normalized.split("/").includes(".gdh-state");
+}
+async function evaluateAuthoringSliceValidation(targetPath) {
+    const workingCopy = await createDogfoodWorkingCopy(path.resolve(targetPath));
+    try {
+        const projectConfigPresent = await pathExists(path.join(workingCopy.targetPath, ".gdh/project.yaml"));
+        const hasExistingOnboarding = await hasCompleteOnboardingSurface(workingCopy.targetPath);
+        const onboarding = await onboardGodotProject(workingCopy.targetPath, {
+            dryRun: hasExistingOnboarding || projectConfigPresent,
+        });
+        if (projectConfigPresent && !hasExistingOnboarding) {
+            await applyRepairableOnboardingWrites(onboarding.writes);
+        }
+        if (onboarding.status !== "ready" || onboarding.selectedProject === null) {
+            throw new Error("Authoring-slice validation requires an onboarded target with a selected primary project.");
+        }
+        const context = await buildAuthoringContext(workingCopy.targetPath);
+        const changedFiles = deriveDogfoodChangedFiles(onboarding.selectedProject);
+        if (changedFiles.length === 0) {
+            throw new Error("Authoring-slice validation could not derive a representative authoring change set.");
+        }
+        const adapters = await getSupportedAgentAdaptersStatus(workingCopy.targetPath, {
+            includeUserLocal: false,
+        });
+        const authoringCheck = await runAuthoringCheck({
+            targetPath: workingCopy.targetPath,
+            status: context.status,
+            projectConfig: context.projectConfig,
+        });
+        const donePolicy = await evaluateDonePolicy({
+            targetPath: workingCopy.targetPath,
+            inventory: context.inventory,
+            status: context.status,
+            projectConfig: context.projectConfig,
+            files: changedFiles,
+            performed: [],
+        });
+        return {
+            adapters,
+            authoringCheck,
+            donePolicy,
+        };
+    }
+    finally {
+        await fs.rm(workingCopy.tempRoot, { recursive: true, force: true });
+    }
+}
+function classifyBlockedDogfoodResult(dogfood) {
+    switch (dogfood.blockedReason) {
+        case "pilot_target_missing":
+            return {
+                failureClass: "environment_issue",
+                reasons: ["pilot_target_missing"],
+            };
+        case "onboarding_unresolved":
+        case "selected_project_missing":
+            return {
+                failureClass: "project_issue",
+                reasons: [dogfood.blockedReason],
+            };
+        case "no_representative_changed_files":
+            return {
+                failureClass: "harness_gap",
+                reasons: [dogfood.blockedReason],
+            };
+        case "fixture_target_missing":
+            return {
+                failureClass: "harness_gap",
+                reasons: ["fixture_target_missing"],
+            };
+        default:
+            return {
+                failureClass: "unknown",
+                reasons: dogfood.blockedReason === null ? ["dogfood_blocked"] : [dogfood.blockedReason],
+            };
+    }
+}
+function classifyAuthoringSliceValidation(input) {
+    const codexAdapter = input.adapters.adapters.find((adapter) => adapter.agent === "codex");
+    const codexVisibilityReady = codexAdapter !== undefined &&
+        codexAdapter.surfaces
+            .filter((surface) => surface.scope === "repo")
+            .every((surface) => surface.state === "ready");
+    if (input.adapters.guidance.state !== "ready" || !codexVisibilityReady) {
+        return {
+            state: "blocked",
+            summary: "The authoring-first slice is blocked because supported-agent visibility is not ready enough for internal use.",
+            failureClass: "harness_gap",
+            reasons: [
+                input.adapters.guidance.state !== "ready"
+                    ? `guidance:${input.adapters.guidance.state}`
+                    : null,
+                !codexVisibilityReady ? `adapter:codex:${codexAdapter?.state ?? "missing"}` : null,
+            ].filter((reason) => reason !== null),
+        };
+    }
+    if (input.authoringCheck.status === "passed" && input.donePolicy.status === "done") {
+        return {
+            state: "ready",
+            summary: "The current authoring-first slice is healthy enough for internal use on this target.",
+            failureClass: null,
+            reasons: [],
+        };
+    }
+    if (input.authoringCheck.status === "unavailable") {
+        return {
+            state: "blocked",
+            summary: "The authoring-first slice is blocked by environment setup before static validation can run reliably.",
+            failureClass: input.authoringCheck.reasons.includes("godot_editor_not_configured")
+                ? "environment_issue"
+                : "unknown",
+            reasons: input.authoringCheck.reasons,
+        };
+    }
+    if (input.authoringCheck.status === "diagnostics") {
+        return {
+            state: "blocked",
+            summary: "The authoring-first slice is blocked because the target already reports authoring diagnostics that need to be resolved.",
+            failureClass: "project_issue",
+            reasons: input.authoringCheck.diagnostics.map((diagnostic) => diagnostic.message),
+        };
+    }
+    if (input.donePolicy.status === "not_done") {
+        return {
+            state: "degraded",
+            summary: "The authoring-first slice ran, but the work would still not be eligible to be called done with the current validation evidence.",
+            failureClass: "agent_judgment_issue",
+            reasons: input.donePolicy.reasons,
+        };
+    }
+    if (input.donePolicy.status === "blocked") {
+        return {
+            state: "blocked",
+            summary: "The authoring-first slice remains blocked because a required validation surface is still unavailable.",
+            failureClass: "environment_issue",
+            reasons: input.donePolicy.reasons,
+        };
+    }
+    if (input.authoringCheck.status === "degraded") {
+        return {
+            state: "degraded",
+            summary: "The authoring-first slice ran with degraded validation trust, so the result is not yet strong enough for internal use.",
+            failureClass: "environment_issue",
+            reasons: input.authoringCheck.reasons,
+        };
+    }
+    return {
+        state: "failed",
+        summary: "The authoring-first slice reached an unexpected state that GDH cannot classify confidently yet.",
+        failureClass: "unknown",
+        reasons: ["authoring_slice_unclassified"],
+    };
+}
+function normalizeRelativePath(value) {
+    return value
+        .split(path.sep)
+        .filter((segment) => segment.length > 0 && segment !== ".")
+        .join("/");
+}
+function isHealthyDogfoodTarget(input) {
+    return (input.readiness === "authorable" &&
+        input.guidanceState === "ready" &&
+        input.recommendationCount > 0 &&
+        input.sessionState === "available");
+}
+function summarizeAuthoringDogfoodState(results) {
+    if (results.some((result) => result.state === "failed")) {
+        return "failed";
+    }
+    if (results.some((result) => result.state === "blocked")) {
+        return "degraded";
+    }
+    return "healthy";
+}
+function summarizeAuthoringDogfoodResults(results, state) {
+    const passed = results.filter((result) => result.state === "passed").length;
+    const blocked = results.filter((result) => result.state === "blocked").length;
+    const failed = results.filter((result) => result.state === "failed").length;
+    if (state === "healthy") {
+        return `Authoring dogfood passed for ${passed} target(s).`;
+    }
+    if (state === "degraded") {
+        return `Authoring dogfood completed with ${passed} passed and ${blocked} blocked target(s).`;
+    }
+    return `Authoring dogfood encountered ${failed} failed target(s), ${blocked} blocked target(s), and ${passed} passed target(s).`;
+}
+function createDogfoodSessionId(kind, sourcePath) {
+    return [
+        "dogfood",
+        kind,
+        path.basename(sourcePath).replace(/[^a-zA-Z0-9_-]+/g, "-"),
+        Date.now().toString(36),
+    ].join("-");
+}
+async function pathExists(targetPath) {
+    try {
+        await fs.stat(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function renderHelp() {
+    return ([
+        `${GDH_PRODUCT_NAME} CLI`,
+        "",
+        "Commands:",
+        "  --version      Print the active GDH product version.",
+        "  version        Print GDH product metadata and managed project-surface versions.",
+        "  setup [target]  Run the interactive setup wizard and end with the `/gdh-onboard` handoff.",
+        "  status [target]  Report explicit GDH readiness and capability availability.",
+        "  docs version [target] [--project <relative-path>]  Resolve the effective Godot docs version and official source set.",
+        "  docs search <query> [target] [--project <relative-path>] [--limit <n>]  Search official version-aware Godot docs.",
+        "  docs fetch <ref-or-url> [target] [--project <relative-path>]  Fetch one official version-aware Godot docs page or section.",
+        "  adapters status [target] [--integration-root <path>] Inspect supported-agent reinforcement status.",
+        "  adapters install [target] [--dry-run] [--agent <name>] [--user] [--dev-repo <path>] [--integration-root <path>] Install or repair supported-agent reinforcement.",
+        "  adapters gsd snapshot [target] [--files <path>] [--performed <kind>] Export a read-only GSD projection.",
+        "  authoring check [target] Run the current authoring-check entrypoint.",
+        "  lsp status [target] Resolve the managed authoring.lsp lifecycle state.",
+        "  warmup [target] [--dry-run] Inspect or apply authoring worktree warmup.",
+        "  target prepare [target] [--source-target <path>] [--dry-run] Prepare target-local generated/import state.",
+        "  imports refresh [target] [--dry-run] Run or plan a headless Godot import refresh.",
+        "  run-config list [target] List run configurations.",
+        "  run-config show [target] <run-config-id> Show one run configuration.",
+        "  run-config check [target] <run-config-id> Evaluate run-configuration readiness.",
+        "  run-config run [target] <run-config-id> Execute one run configuration.",
+        "  bridge status [target] Inspect the managed runtime bridge lifecycle state.",
+        "  bridge doctor [target] Alias for bridge status.",
+        "  bridge install [target] [--dry-run] Install the GDH-managed runtime bridge surface.",
+        "  bridge repair [target] [--dry-run] Repair drifted GDH-managed bridge files and autoload state.",
+        "  bridge remove [target] [--dry-run] Remove the GDH-managed runtime bridge surface.",
+        "  verification-scenario list [target] List verification scenarios.",
+        "  verification-scenario show [target] <verification-scenario-id> Show one verification scenario.",
+        "  guidance status [target] Inspect durable guidance and audit availability.",
+        "  guidance resolve [target] Resolve eligible deeper guidance units.",
+        "  guidance audit [target] Inspect stored guidance-audit history.",
+        "  observability session [target] [--latest] Inspect recorded authoring-session history.",
+        "  observability effectiveness [target] [--latest] Summarize heuristic agent-effectiveness signals.",
+        "  dogfood authoring --fixtures <path> [--fixtures <path>...] [--pilot <path>] Run the authoring-first slice report.",
+        "  mcp manifest Print the thin GDH MCP manifest.",
+        "  mcp serve --target <path> Run the real GDH stdio MCP server.",
+        "  mcp invoke <tool> [target] [--input-json <json>] Invoke one GDH MCP tool.",
+        "  verify run [target] <run-config-id> --verification-scenario <verification-scenario-id> Execute one verification scenario.",
+        "  verify inspect [target] [--run-record <run-record-id>] Inspect one runtime run record.",
+        "  verify readiness [target] Summarize runtime verification readiness and recurring runtime feedback.",
+        "  verify corpus status Inspect runtime corpus release-readiness evidence.",
+        "  verify corpus materialize --entry <id> Materialize one runtime corpus entry into GDH-managed source state.",
+        "  verify corpus exercise --entry <id> Exercise one runtime corpus entry through onboarding and runtime verification.",
+        "  verify corpus record --entry <id> --target <path> Record runtime corpus evidence for one target.",
+        "  verify recommend [target] --files <path> Recommend validation requirements.",
+        "  verify done [target] --files <path> Evaluate whether a change is done.",
+        "  cache inspect [target] Inspect namespaced authoring cache state.",
+        "  cache prune [target] [--scope <scope>] Remove namespaced authoring cache state.",
+        "  migrate [target] [--apply] Plan or apply current GDH project-surface migrations.",
+        "  scan [target]    Scan a filesystem target and print a machine-generated Godot inventory.",
+        "  onboard [target] Advanced: generate the low-level GDH project surface from scan evidence as JSON.",
+        "",
+        "Run `gdh <command> --help` for command-specific usage.",
+    ].join("\n") + "\n");
+}
+function formatCliError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function resolveCachePruneScope(args) {
+    const index = args.indexOf("--scope");
+    if (index === -1) {
+        return "all";
+    }
+    const value = args[index + 1];
+    if (value === "worktree" || value === "project" || value === "all") {
+        return value;
+    }
+    return null;
+}
+function extractCachePrunePositionalArgs(args) {
+    const positionalArgs = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg) {
+            continue;
+        }
+        if (arg === "--scope") {
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            continue;
+        }
+        positionalArgs.push(arg);
+    }
+    return positionalArgs;
+}
+function collectOptionValues(args, optionName) {
+    const values = [];
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] !== optionName) {
+            continue;
+        }
+        const value = args[index + 1];
+        if (!value || value.startsWith("--")) {
+            continue;
+        }
+        values.push(value);
+        index += 1;
+    }
+    return values;
+}
+function collectAssignmentOptionValues(args, optionName) {
+    const assignments = {};
+    for (const value of collectOptionValues(args, optionName)) {
+        const separatorIndex = value.indexOf("=");
+        if (separatorIndex <= 0 || separatorIndex === value.length - 1) {
+            continue;
+        }
+        assignments[value.slice(0, separatorIndex)] = value.slice(separatorIndex + 1);
+    }
+    return assignments;
+}
+function readSingleOptionValue(args, optionName) {
+    const index = args.indexOf(optionName);
+    if (index === -1) {
+        return null;
+    }
+    const value = args[index + 1];
+    if (!value || value.startsWith("--")) {
+        return null;
+    }
+    return value;
+}
+function findUnsupportedOptionsError(args, options) {
+    const supportedOptions = new Set([
+        ...(options.optionsWithValues ?? []),
+        ...(options.booleanOptions ?? []),
+    ]);
+    const unknownOptions = args.filter((arg) => arg.startsWith("--") && !supportedOptions.has(arg));
+    if (unknownOptions.length === 0) {
+        return null;
+    }
+    return `Usage error: unsupported option(s): ${unknownOptions.join(", ")}.\n${options.usage}`;
+}
+function parseSingleTargetPathArg(args, options) {
+    const allowTargetOption = options.allowTargetOption ?? false;
+    const unsupportedOptionsError = findUnsupportedOptionsError(args, {
+        usage: options.usage,
+        optionsWithValues: allowTargetOption ? ["--target"] : [],
+    });
+    if (unsupportedOptionsError !== null) {
+        return {
+            targetPath: ".",
+            error: unsupportedOptionsError,
+        };
+    }
+    const targetOptionValue = allowTargetOption ? readSingleOptionValue(args, "--target") : null;
+    const positionalArgs = extractPositionalArgs(args, new Set(allowTargetOption ? ["--target"] : []));
+    if (allowTargetOption && args.includes("--target") && targetOptionValue === null) {
+        return {
+            targetPath: ".",
+            error: `Usage error: --target requires a path value.\n${options.usage}`,
+        };
+    }
+    if (positionalArgs.length > 1) {
+        return {
+            targetPath: ".",
+            error: `Usage error: command accepts at most one target path.\n${options.usage}`,
+        };
+    }
+    if (allowTargetOption && targetOptionValue !== null && positionalArgs.length > 0) {
+        return {
+            targetPath: ".",
+            error: `Usage error: choose either a positional target path or --target <path>.\n${options.usage}`,
+        };
+    }
+    return {
+        targetPath: targetOptionValue ?? positionalArgs[0] ?? ".",
+        error: null,
+    };
+}
+function parsePositiveIntegerOptionValue(value) {
+    if (!/^\d+$/.test(value)) {
+        return null;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return parsed > 0 ? parsed : null;
+}
+function buildGuidanceSnapshot(result) {
+    return {
+        effectiveRepoState: result.effectiveRepoState,
+        requiredUnitIds: result.requiredUnits.map((unit) => unit.id),
+        recommendedUnitIds: result.recommendedUnits.map((unit) => unit.id),
+    };
+}
+async function recordSessionEvent(targetPath, input) {
+    try {
+        const { commandStartedAtMs, ...eventInput } = input;
+        const startedAt = typeof commandStartedAtMs === "number" && Number.isFinite(commandStartedAtMs)
+            ? new Date(commandStartedAtMs).toISOString()
+            : null;
+        await recordAuthoringSessionEvent(targetPath, {
+            sessionId: process.env["GDH_SESSION_ID"] ?? null,
+            startedAt,
+            ...eventInput,
+        });
+    }
+    catch {
+        // Observability is operational state; do not break the primary command if recording fails.
+    }
+}
+function parseMcpInputJson(args) {
+    const value = collectOptionValues(args, "--input-json")[0];
+    if (!value) {
+        return {};
+    }
+    const parsed = JSON.parse(value);
+    if (parsed === null || Array.isArray(parsed) || typeof parsed !== "object") {
+        throw new Error("--input-json must parse to a JSON object.");
+    }
+    return parsed;
+}
+function collectAdapterNames(args) {
+    const values = collectOptionValues(args, "--agent");
+    if (values.length === 0) {
+        return [];
+    }
+    const agents = [];
+    for (const value of values) {
+        if (!isSupportedAgent(value)) {
+            return null;
+        }
+        agents.push(value);
+    }
+    return agents;
+}
+function isSupportedAgent(value) {
+    return value === "codex" || value === "claude" || value === "cursor";
+}
+function deriveGuidanceRepoState(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 collectPerformedValidationKinds(args) {
+    return collectOptionValues(args, "--performed").flatMap((value) => {
+        switch (value) {
+            case "authoring_check":
+            case "unit_tests":
+            case "integration_tests":
+            case "editor_validation":
+            case "runtime_scenario":
+            case "manual_review":
+                return [value];
+            default:
+                return [];
+        }
+    });
+}
+function extractGuidanceResolvePositionalArgs(args) {
+    return extractPositionalArgs(args, new Set(["--task-type", "--capability", "--repo-state", "--keyword"]));
+}
+function extractRecipePositionalArgs(args) {
+    return extractPositionalArgs(args, new Set(["--provider", "--param", "--feature", "--no-feature", "--env"]));
+}
+function extractPositionalArgs(args, optionsWithValues) {
+    const positionalArgs = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg) {
+            continue;
+        }
+        if (optionsWithValues.has(arg)) {
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            continue;
+        }
+        positionalArgs.push(arg);
+    }
+    return positionalArgs;
+}
+//# sourceMappingURL=index.js.map