@skillcap/gdh 0.6.0 → 0.8.0

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

@@ -1,7 +1,10 @@
+import { spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
+import fsSync from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { buildGdhStatusResult, CLAUDE_CHECK_COMMAND_RELATIVE_PATH, CLAUDE_CHECK_UPDATE_HOOK_RELATIVE_PATH, CLAUDE_MIGRATE_COMMAND_RELATIVE_PATH, CLAUDE_ONBOARD_COMMAND_RELATIVE_PATH, CLAUDE_PREPARE_COMMAND_RELATIVE_PATH, CLAUDE_STATUS_COMMAND_RELATIVE_PATH, CLAUDE_VERIFY_COMMAND_RELATIVE_PATH, CODEX_CHECK_SKILL_RELATIVE_PATH, CODEX_MIGRATE_SKILL_RELATIVE_PATH, CODEX_ONBOARD_SKILL_RELATIVE_PATH, CODEX_PREPARE_SKILL_RELATIVE_PATH, CODEX_STATUS_SKILL_RELATIVE_PATH, CODEX_VERIFY_SKILL_RELATIVE_PATH, createGsdSnapshot, CURSOR_CHECK_SKILL_RELATIVE_PATH, CURSOR_MIGRATE_SKILL_RELATIVE_PATH, CURSOR_ONBOARD_SKILL_RELATIVE_PATH, CURSOR_PREPARE_SKILL_RELATIVE_PATH, CURSOR_STATUS_SKILL_RELATIVE_PATH, CURSOR_VERIFY_SKILL_RELATIVE_PATH, getSupportedAgentAdaptersStatus, installSupportedAgentAdapters, MCP_LAUNCHER_RELATIVE_PATH, } from "@gdh/adapters";
+import { fileURLToPath } from "node:url";
+import { buildGdhStatusResult, CLAUDE_CHECK_COMMAND_RELATIVE_PATH, CLAUDE_CHECK_UPDATE_HOOK_RELATIVE_PATH, CLAUDE_MIGRATE_COMMAND_RELATIVE_PATH, CLAUDE_ONBOARD_COMMAND_RELATIVE_PATH, CLAUDE_PREPARE_COMMAND_RELATIVE_PATH, CLAUDE_STATUS_COMMAND_RELATIVE_PATH, CLAUDE_VERIFY_COMMAND_RELATIVE_PATH, CODEX_CHECK_SKILL_RELATIVE_PATH, CODEX_MIGRATE_SKILL_RELATIVE_PATH, CODEX_ONBOARD_SKILL_RELATIVE_PATH, CODEX_PREPARE_SKILL_RELATIVE_PATH, CODEX_STATUS_SKILL_RELATIVE_PATH, CODEX_VERIFY_SKILL_RELATIVE_PATH, createGsdSnapshot, CURSOR_CHECK_SKILL_RELATIVE_PATH, CURSOR_MIGRATE_SKILL_RELATIVE_PATH, CURSOR_ONBOARD_SKILL_RELATIVE_PATH, CURSOR_PREPARE_SKILL_RELATIVE_PATH, CURSOR_STATUS_SKILL_RELATIVE_PATH, CURSOR_VERIFY_SKILL_RELATIVE_PATH, getSupportedAgentAdaptersStatus, installSupportedAgentAdapters, } from "@gdh/adapters";
 import { getManagedLspStatus, hasCompleteOnboardingSurface, inspectCacheState, pruneCacheState, readProjectConfig, resolvePinnedVersion, resolveProjectRoot, readWorktreeState, resolveAuthoringStatus, resolveTargetGodotDocsVersion, runAuthoringCheck, runImportRefresh, runTargetPrepare, runWarmup, } from "@gdh/authoring";
 import { definePackageBoundary, GDH_AUTHORING_DOGFOOD_VERSION, GDH_AUTHORING_SLICE_REPORT_VERSION, GDH_PRODUCT_NAME, resolveCurrentGdhInstall, resolveGdhProductMetadata, } from "@gdh/core";
 import { fetchOfficialGodotDoc, getGuidanceStatus, resolveGuidanceQuery, searchOfficialGodotDocs, } from "@gdh/docs";
@@ -13,7 +16,7 @@ import { evaluateDonePolicy, exerciseRuntimeCorpusEntry, inspectRuntimeCorpusSta
 import { migrateProjectLifecycleSurface } from "./migrate.js";
 import { presentPublicRuntimeTerms } from "./public-terms.js";
 import { runSelfUpdateCommand } from "./self-update.js";
-import { executeSetupCommand, isSetupCanceledError, renderSetupIntro, renderSetupOutro, renderSetupSummary, } from "./setup.js";
+import { executeSetupCommand, isSetupCanceledError, renderDurableTruthCollisionHint, renderSetupIntro, renderSetupOutro, renderSetupSummary, } from "./setup.js";
 import { emitUpdateBannerIfStale } from "./update-banner.js";
 export const cliPackage = definePackageBoundary({
     name: "@gdh/cli",
@@ -41,6 +44,18 @@ export async function runCli(args, io = { stdout: process.stdout, stderr: proces
         io.stdout.write(`${resolveGdhProductMetadata().version}\n`);
         return 0;
     }
+    // Internal diagnostic for Plan 15-05 symlink-shape test; not a user-facing feature.
+    if (command === "--print-target-path") {
+        const { targetPath, error } = parseOptionalPositionalTargetPath(rest, {
+            usage: "Usage: gdh --print-target-path [<target-path>]\n",
+        });
+        if (error !== null) {
+            io.stderr.write(error);
+            return 1;
+        }
+        io.stdout.write(`${JSON.stringify({ targetPath })}\n`);
+        return 0;
+    }
     if (command === "version") {
         return runVersionCommand(rest, io);
     }
@@ -213,8 +228,12 @@ async function runSetupCommand(args, io) {
     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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh setup [<target-path>] [--agent <name>] [--all-agents] [--project <path>] [--integration-root <path>] [--yes]\n",
+        additionalOptionsWithValues: new Set(["--agent", "--project", "--integration-root"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
     const requestedAgents = collectAdapterNames(args);
@@ -226,7 +245,6 @@ async function runSetupCommand(args, io) {
         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");
@@ -288,6 +306,22 @@ async function runSetupCommand(args, io) {
             });
             return 1;
         }
+        // Phase 18 plan 03 (UX-02): typed recoveryHint render before the generic
+        // failure branch. Detects DurableTruthCollisionError via the dual-package-
+        // hazard-safe predicate exported by setup.ts, renders the structured
+        // recoveryHint (Suggested fix / Run / Skill) to the CLI stderr sink, and
+        // records a blocked session (mirrors the SetupCanceledError arm shape).
+        if (renderDurableTruthCollisionHint(error, io.stderr)) {
+            await recordSessionEvent(targetPath, {
+                commandStartedAtMs,
+                kind: "onboard",
+                command: "gdh setup",
+                state: "blocked",
+                summary: "GDH setup blocked on durable-truth collision; see recoveryHint.",
+                errorMessage: formatCliError(error),
+            });
+            return 1;
+        }
         await recordSessionEvent(targetPath, {
             commandStartedAtMs,
             kind: "onboard",
@@ -318,12 +352,14 @@ async function runOnboardCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh onboard [target] [--dry-run]\n",
+        additionalOptionsWithValues: new Set(["--task-type", "--capability", "--repo-state", "--keyword"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     const commandStartedAtMs = Date.now();
     try {
         const result = await onboardGodotProject(targetPath, { dryRun });
@@ -519,16 +555,18 @@ async function runDocsVersionCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh docs version [target] [--project <relative-path>]\n",
+        additionalOptionsWithValues: new Set(["--project"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         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);
@@ -767,12 +805,14 @@ async function runWarmupCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh warmup [target] [--dry-run]\n",
+        additionalOptionsWithValues: new Set(["--task-type", "--capability", "--repo-state", "--keyword"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     try {
         const context = await buildAuthoringContext(targetPath);
         const result = await runWarmup({
@@ -831,12 +871,14 @@ async function runTargetPrepareCommand(args, io) {
     }
     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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh target prepare [target] [--source-target <path>] [--dry-run] [--no-refresh-imports]\n",
+        additionalOptionsWithValues: new Set(["--source-target"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     const sourceTargetPath = collectOptionValues(args, "--source-target")[0] ?? null;
     const commandStartedAtMs = Date.now();
     try {
@@ -918,12 +960,13 @@ async function runImportsRefreshCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh imports refresh [target] [--dry-run]\n",
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     const commandStartedAtMs = Date.now();
     try {
         const context = await buildAuthoringContext(targetPath);
@@ -1259,7 +1302,7 @@ async function runVerifyCommand(args, io) {
             "  corpus <status|record>",
             "                                                  Inspect or record runtime corpus release-readiness evidence as JSON.",
             "  drift [target]",
-            "                                                  Check whether baked `@skillcap/gdh@<version>` literals (launcher + skills + commands) match .gdh/project.yaml gdh_version.",
+            "                                                  Check whether baked `@skillcap/gdh@<version>` literals (skills + commands) match .gdh/project.yaml gdh_version.",
             "  recommend [target] --files <path> [--files <path>...]",
             "                                                  Recommend authoring-first validation requirements for the supplied change set.",
             "  done [target] --files <path> [--files <path>...] [--performed <kind>]",
@@ -1476,12 +1519,14 @@ async function runMigrateCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh migrate [target] [--apply]\n",
+        additionalOptionsWithValues: new Set(["--apply"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     const dryRun = !args.includes("--apply");
     try {
         const result = await migrateProjectLifecycleSurface({ targetPath, dryRun });
@@ -1510,12 +1555,13 @@ async function runBridgeStatusCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh bridge status [target]\nUsage: gdh bridge doctor [target]\n",
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     const commandStartedAtMs = Date.now();
     try {
         const projectConfig = await readProjectConfig(targetPath);
@@ -1563,12 +1609,14 @@ async function runBridgeApplyCommand(args, io, operation) {
         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`);
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: `Usage: gdh bridge ${operation} [target] [--dry-run]\n`,
+        additionalOptionsWithValues: new Set(["--dry-run"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     const dryRun = args.includes("--dry-run");
     const commandStartedAtMs = Date.now();
     try {
@@ -1642,12 +1690,14 @@ async function runRecipeListCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh run-config list [target]\n",
+        additionalOptionsWithValues: new Set(["--provider", "--param", "--feature", "--no-feature", "--env"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     const effectiveTargetPath = await resolveEffectiveTargetPath(targetPath);
     const commandStartedAtMs = Date.now();
     try {
@@ -1876,12 +1926,14 @@ async function runScenarioListCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh verification-scenario list [target]\n",
+        additionalOptionsWithValues: new Set(["--provider", "--param", "--feature", "--no-feature", "--env"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     const effectiveTargetPath = await resolveEffectiveTargetPath(targetPath);
     const commandStartedAtMs = Date.now();
     try {
@@ -1980,12 +2032,14 @@ async function runAdaptersStatusCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh adapters status [target] [--integration-root <path>]\n",
+        additionalOptionsWithValues: new Set(["--integration-root"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     const integrationRootPath = readSingleOptionValue(args, "--integration-root");
     try {
         const result = await getSupportedAgentAdaptersStatus(targetPath, {
@@ -2022,9 +2076,12 @@ async function runAdaptersInstallCommand(args, io) {
     }
     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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh adapters install [target] [--dry-run] [--agent <name>] [--user] [--dev-repo <path>] [--integration-root <path>]\n",
+        additionalOptionsWithValues: new Set(["--agent", "--dev-repo", "--integration-root"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
     const agents = collectAdapterNames(args);
@@ -2032,7 +2089,6 @@ async function runAdaptersInstallCommand(args, io) {
         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 {
@@ -2068,12 +2124,14 @@ async function runGsdSnapshotCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh adapters gsd snapshot [target] [--files <path>] [--performed <kind>]\n",
+        additionalOptionsWithValues: new Set(["--files", "--performed"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     try {
         const result = await createGsdSnapshot(targetPath, {
             files: collectOptionValues(args, "--files"),
@@ -2098,29 +2156,30 @@ async function runMcpManifestCommand(args, io) {
 async function runMcpServeCommand(args, io) {
     if (args.includes("--help")) {
         io.stdout.write([
-            "Usage: gdh mcp serve --target <path>",
+            "Usage: gdh mcp serve [--target <path>]",
             "",
-            "Run the real GDH stdio MCP server for one bound target path.",
+            "Run the real GDH stdio MCP server. When --target is omitted, defaults to",
+            "the current working directory and walks up to find the nearest .gdh/project.yaml.",
         ].join("\n") + "\n");
         return 0;
     }
     const unsupportedOptionsError = findUnsupportedOptionsError(args, {
-        usage: "Usage: gdh mcp serve --target <path>\n",
+        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;
     }
+    const targetPath = readSingleOptionValue(args, "--target") ?? process.cwd();
+    const devRepoExitCode = maybeReexecIntoDevRepo(targetPath);
+    if (devRepoExitCode !== null) {
+        return devRepoExitCode;
+    }
     try {
         await serveMcpOverStdio(targetPath);
         return 0;
@@ -2130,6 +2189,42 @@ async function runMcpServeCommand(args, io) {
         return 1;
     }
 }
+function maybeReexecIntoDevRepo(targetPath) {
+    if (process.env["GDH_MCP_DEV_REEXEC"] === "1") {
+        // Already running under a dev-repo re-exec; skip to avoid a loop.
+        return null;
+    }
+    const envDevRepoPath = process.env["GDH_DEV_REPO"]?.trim() || null;
+    const hintsPath = path.join(path.resolve(targetPath), ".gdh-state", "local-paths.json");
+    let hintDevRepoPath = null;
+    try {
+        const raw = fsSync.readFileSync(hintsPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.gdhDevRepoPath === "string" && parsed.gdhDevRepoPath.length > 0) {
+            hintDevRepoPath = parsed.gdhDevRepoPath;
+        }
+    }
+    catch {
+        // No hints file or unparseable — fall through.
+    }
+    const devRepoPath = envDevRepoPath || hintDevRepoPath;
+    if (devRepoPath === null) {
+        return null;
+    }
+    const devCliEntry = path.join(devRepoPath, "packages/cli/dist/cli.js");
+    if (!fsSync.existsSync(devCliEntry)) {
+        return null;
+    }
+    const currentCliPath = path.resolve(fileURLToPath(import.meta.url));
+    const resolvedDevRepoPath = path.resolve(devRepoPath);
+    // Avoid loop if the currently-running CLI source already lives inside the
+    // dev repo (e.g. contributor running the dev CLI directly via tsx).
+    if (currentCliPath.startsWith(`${resolvedDevRepoPath}${path.sep}`)) {
+        return null;
+    }
+    const result = spawnSync(process.execPath, [devCliEntry, "mcp", "serve", "--target", path.resolve(targetPath)], { stdio: "inherit", env: { ...process.env, GDH_MCP_DEV_REEXEC: "1" } });
+    return result.status ?? 1;
+}
 async function runMcpInvokeCommand(args, io) {
     if (args.includes("--help")) {
         io.stdout.write([
@@ -2157,12 +2252,14 @@ async function runMcpInvokeCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(rest, {
+        usage: "Usage: gdh mcp invoke <tool> [target] [--input-json <json>]\n",
+        additionalOptionsWithValues: new Set(["--input-json"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     try {
         const result = await invokeMcpTool({
             toolName: toolName,
@@ -2220,9 +2317,12 @@ async function runVerifyRecommendCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh verify recommend [target] --files <path> [--files <path>...]\n",
+        additionalOptionsWithValues: new Set(["--files"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
     const files = collectOptionValues(args, "--files");
@@ -2230,7 +2330,6 @@ async function runVerifyRecommendCommand(args, io) {
         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);
@@ -2289,9 +2388,12 @@ async function runVerifyDoneCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh verify done [target] --files <path> [--files <path>...] [--performed <kind>]\n",
+        additionalOptionsWithValues: new Set(["--files", "--performed"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
     const files = collectOptionValues(args, "--files");
@@ -2299,7 +2401,6 @@ async function runVerifyDoneCommand(args, io) {
         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);
@@ -2450,12 +2551,14 @@ async function runVerifyInspectCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh verify inspect [target] [--run-record <run-record-id>]\n",
+        additionalOptionsWithValues: new Set(["--run-record", "--bundle"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     const commandStartedAtMs = Date.now();
     try {
         const result = await inspectRuntimeVerificationBundleState({
@@ -2502,12 +2605,13 @@ async function runVerifyReadinessCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh verify readiness [target]\n",
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     const commandStartedAtMs = Date.now();
     try {
         const projectConfig = await readProjectConfig(targetPath);
@@ -2542,7 +2646,6 @@ async function runVerifyReadinessCommand(args, io) {
     }
 }
 const VERIFY_DRIFT_SCANNED_FILES = [
-    { relativePath: MCP_LAUNCHER_RELATIVE_PATH, description: "managed MCP launcher" },
     { relativePath: CODEX_ONBOARD_SKILL_RELATIVE_PATH, description: "Codex gdh-onboard skill" },
     { relativePath: CODEX_STATUS_SKILL_RELATIVE_PATH, description: "Codex gdh-status skill" },
     { relativePath: CODEX_MIGRATE_SKILL_RELATIVE_PATH, description: "Codex gdh-migrate skill" },
@@ -2611,8 +2714,8 @@ async function runVerifyDriftCommand(args, io) {
             "Usage: gdh verify drift [target]",
             "",
             "Compares every baked `@skillcap/gdh@<version>` literal across the managed",
-            "surfaces (.gdh/bin/gdh-mcp.mjs launcher + regenerated Codex/Cursor/Claude",
-            "skill + command files) against .gdh/project.yaml gdh_version. Exits 1 and",
+            "surfaces (regenerated Codex/Cursor/Claude skill + command files) against",
+            ".gdh/project.yaml gdh_version. Exits 1 and",
             "emits a structured JSON result when ANY file's baked version diverges from",
             "the pinned value. Covers ROADMAP Success Criterion #3 (one source of truth).",
             "",
@@ -2626,12 +2729,13 @@ async function runVerifyDriftCommand(args, io) {
         io.stderr.write(unsupportedOptionsError);
         return 1;
     }
-    const positionalArgs = extractPositionalArgs(args, new Set());
-    if (positionalArgs.length > 1) {
-        io.stderr.write("Usage error: gdh verify drift accepts at most one positional target path.\n");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh verify drift [target]\n",
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     const commandStartedAtMs = Date.now();
     let pinnedVersion;
     try {
@@ -2902,12 +3006,14 @@ async function runCacheInspectCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh cache inspect [target]\n",
+        additionalOptionsWithValues: new Set(["--task-type", "--capability", "--repo-state", "--keyword"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     try {
         const context = await buildAuthoringContext(targetPath);
         const result = await inspectCacheState({
@@ -2939,12 +3045,13 @@ async function runGuidanceStatusCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh guidance status [target]\n",
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     const commandStartedAtMs = Date.now();
     try {
         const context = await buildAuthoringContext(targetPath);
@@ -3006,12 +3113,14 @@ async function runGuidanceResolveCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh guidance resolve [target] [--task-type <type>] [--capability <id>] [--repo-state <state>] [--keyword <term>]\n",
+        additionalOptionsWithValues: new Set(["--task-type", "--capability", "--repo-state", "--keyword"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     const commandStartedAtMs = Date.now();
     try {
         const context = await buildAuthoringContext(targetPath);
@@ -3065,12 +3174,13 @@ async function runGuidanceAuditCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh guidance audit [target]\n",
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     try {
         const result = await inspectGuidanceAudit(targetPath);
         await recordSessionEvent(targetPath, {
@@ -3112,12 +3222,14 @@ async function runObservabilitySessionCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh observability session [target] [--latest] [--session-id <id>]\n",
+        additionalOptionsWithValues: new Set(["--session-id"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     const sessionId = readSingleOptionValue(args, "--session-id");
     try {
         const result = await inspectAuthoringSessions(targetPath, {
@@ -3150,12 +3262,14 @@ async function runObservabilityEffectivenessCommand(args, io) {
         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");
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh observability effectiveness [target] [--latest] [--session-id <id>]\n",
+        additionalOptionsWithValues: new Set(["--session-id"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
         return 1;
     }
-    const targetPath = positionalArgs[0] ?? ".";
     const sessionId = readSingleOptionValue(args, "--session-id");
     try {
         const result = await inspectAuthoringEffectiveness(targetPath, {
@@ -3190,17 +3304,19 @@ async function runCachePruneCommand(args, io) {
         return 1;
     }
     const dryRun = args.includes("--dry-run");
-    const positionalArgs = extractCachePrunePositionalArgs(args);
+    const { targetPath, error: targetPathError } = parseOptionalPositionalTargetPath(args, {
+        usage: "Usage: gdh cache prune [target] [--scope <scope>] [--dry-run]\n",
+        additionalOptionsWithValues: new Set(["--scope"]),
+    });
+    if (targetPathError !== null) {
+        io.stderr.write(targetPathError);
+        return 1;
+    }
     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({
@@ -3807,24 +3923,6 @@ function resolveCachePruneScope(args) {
     }
     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) {
@@ -3873,7 +3971,14 @@ export function findUnsupportedOptionsError(args, options) {
     }
     return `Usage error: unsupported option(s): ${unknownOptions.join(", ")}.\n${options.usage}`;
 }
-function parseSingleTargetPathArg(args, options) {
+/**
+ * CLI ingress helper. Returns an ABSOLUTE `targetPath` on both success and error paths.
+ *
+ * Part of the "targetPath is absolute post-ingress" invariant committed in
+ * `docs/architecture/package-boundaries.md#path-contracts`. Uses `path.resolve` — NEVER
+ * `fs.realpath` — to preserve caller-supplied symlink path shapes (worktree invocations).
+ */
+export function parseSingleTargetPathArg(args, options) {
     const allowTargetOption = options.allowTargetOption ?? false;
     const unsupportedOptionsError = findUnsupportedOptionsError(args, {
         usage: options.usage,
@@ -3881,7 +3986,7 @@ function parseSingleTargetPathArg(args, options) {
     });
     if (unsupportedOptionsError !== null) {
         return {
-            targetPath: ".",
+            targetPath: path.resolve("."),
             error: unsupportedOptionsError,
         };
     }
@@ -3889,24 +3994,51 @@ function parseSingleTargetPathArg(args, options) {
     const positionalArgs = extractPositionalArgs(args, new Set(allowTargetOption ? ["--target"] : []));
     if (allowTargetOption && args.includes("--target") && targetOptionValue === null) {
         return {
-            targetPath: ".",
+            targetPath: path.resolve("."),
             error: `Usage error: --target requires a path value.\n${options.usage}`,
         };
     }
     if (positionalArgs.length > 1) {
         return {
-            targetPath: ".",
+            targetPath: path.resolve("."),
             error: `Usage error: command accepts at most one target path.\n${options.usage}`,
         };
     }
     if (allowTargetOption && targetOptionValue !== null && positionalArgs.length > 0) {
         return {
-            targetPath: ".",
+            targetPath: path.resolve("."),
             error: `Usage error: choose either a positional target path or --target <path>.\n${options.usage}`,
         };
     }
     return {
-        targetPath: targetOptionValue ?? positionalArgs[0] ?? ".",
+        targetPath: path.resolve(targetOptionValue ?? positionalArgs[0] ?? "."),
+        error: null,
+    };
+}
+/**
+ * CLI ingress helper for subcommands that accept at most one optional positional
+ * target-path argument (no `--target` option). Returns an ABSOLUTE `targetPath` on both
+ * success and error paths.
+ *
+ * Part of the "targetPath is absolute post-ingress" invariant committed in
+ * `docs/architecture/package-boundaries.md#path-contracts`. Uses `path.resolve` — NEVER
+ * `fs.realpath` — to preserve caller-supplied symlink path shapes (worktree invocations).
+ *
+ * @param args - argv slice starting after the subcommand name.
+ * @param options.usage - usage string embedded in error messages.
+ * @param options.additionalOptionsWithValues - options the subcommand consumes with values
+ *   so they are not misinterpreted as positionals (forwarded to `extractPositionalArgs`).
+ */
+export function parseOptionalPositionalTargetPath(args, options) {
+    const positionalArgs = extractPositionalArgs(args, options.additionalOptionsWithValues ?? new Set());
+    if (positionalArgs.length > 1) {
+        return {
+            targetPath: path.resolve("."),
+            error: `Usage error: command accepts at most one positional target path.\n${options.usage}`,
+        };
+    }
+    return {
+        targetPath: path.resolve(positionalArgs[0] ?? "."),
         error: null,
     };
 }
@@ -3993,9 +4125,6 @@ function collectPerformedValidationKinds(args) {
         }
     });
 }
-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"]));
 }