@skillcap/gdh 0.7.0 → 0.8.0

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

@@ -16,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",
@@ -44,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);
     }
@@ -216,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);
@@ -229,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");
@@ -291,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",
@@ -321,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 });
@@ -522,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);
@@ -770,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({
@@ -834,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 {
@@ -921,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);
@@ -1479,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 });
@@ -1513,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);
@@ -1566,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 {
@@ -1645,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 {
@@ -1879,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 {
@@ -1983,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, {
@@ -2025,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);
@@ -2035,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 {
@@ -2071,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"),
@@ -2197,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,
@@ -2260,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");
@@ -2270,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);
@@ -2329,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");
@@ -2339,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);
@@ -2490,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({
@@ -2542,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);
@@ -2665,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 {
@@ -2941,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({
@@ -2978,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);
@@ -3045,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);
@@ -3104,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, {
@@ -3151,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, {
@@ -3189,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, {
@@ -3229,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({
@@ -3846,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) {
@@ -3912,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,
@@ -3920,7 +3986,7 @@ function parseSingleTargetPathArg(args, options) {
     });
     if (unsupportedOptionsError !== null) {
         return {
-            targetPath: ".",
+            targetPath: path.resolve("."),
             error: unsupportedOptionsError,
         };
     }
@@ -3928,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,
     };
 }
@@ -4032,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"]));
 }