@ai-is-gonna/get-tasks-done 0.2.0

package/sdk/src/query/query-dispatch.test.ts

@@ -0,0 +1,399 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdir, rm, writeFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { existsSync } from 'node:fs';
+import { createRegistry } from './index.js';
+import { GTDToolsError } from '../gtd-tools-error.js';
+import { runQueryDispatch } from './query-dispatch.js';
+import { createCommandTopology } from './command-topology.js';
+import { COMMAND_MUTATION_SET } from './command-definition.js';
+describe('runQueryDispatch', () => {
+  let tmpDir: string;
+  let fixtureDir: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `query-dispatch-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    fixtureDir = join(tmpDir, 'fixtures');
+    await mkdir(fixtureDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  async function createScript(name: string, code: string): Promise<string> {
+    const scriptPath = join(fixtureDir, name);
+    await writeFile(scriptPath, code, { mode: 0o755 });
+    return scriptPath;
+  }
+
+  it('runs native dispatch and formats json', async () => {
+    const registry = createRegistry();
+    const out = await runQueryDispatch({
+      registry,
+      projectDir: tmpDir,
+      cjsFallbackEnabled: true,
+      resolveGtdToolsPath: () => '',
+      dispatchNative: async () => ({ data: { ok: true } }),
+      topology: createCommandTopology(registry),
+    }, ['state', 'json']);
+
+    expect(out.ok).toBe(true);
+    if (!out.ok) throw new Error('expected success');
+    expect(out.stdout).toBe('{\n  "ok": true\n}\n');
+    expect(out.exit_code).toBe(0);
+  });
+
+  it('applies --pick to native json output', async () => {
+    const registry = createRegistry();
+    const out = await runQueryDispatch({
+      registry,
+      projectDir: tmpDir,
+      cjsFallbackEnabled: true,
+      resolveGtdToolsPath: () => '',
+      dispatchNative: async () => ({ data: { nested: { value: 7 } } }),
+      topology: createCommandTopology(registry),
+    }, ['state', 'json', '--pick', 'nested.value']);
+
+    expect(out.ok).toBe(true);
+    if (!out.ok) throw new Error('expected success');
+    expect(out.stdout).toBe('7\n');
+    expect(out.exit_code).toBe(0);
+  });
+
+  it('returns structured error for unknown command when fallback disabled', async () => {
+    const registry = createRegistry();
+    const out = await runQueryDispatch({
+      registry,
+      projectDir: tmpDir,
+      cjsFallbackEnabled: false,
+      resolveGtdToolsPath: () => '',
+      dispatchNative: async () => ({ data: {} }),
+      topology: createCommandTopology(registry),
+    }, ['unknown-cmd']);
+
+    expect(out.ok).toBe(false);
+    if (out.ok) throw new Error('expected failure');
+    expect(out.error.code).toBe(10);
+    expect(out.error.kind).toBe('unknown_command');
+    expect(out.error.message).toContain('Unknown command: "unknown-cmd"');
+    expect(out.error.message).toContain('Attempted dotted:');
+  });
+
+  it('runs cjs fallback and formats text mode', async () => {
+    const script = await createScript('text.cjs', "process.stdout.write('USAGE: help text');");
+    const registry = createRegistry();
+    const out = await runQueryDispatch({
+      registry,
+      projectDir: tmpDir,
+      cjsFallbackEnabled: true,
+      resolveGtdToolsPath: () => script,
+      dispatchNative: async () => ({ data: {} }),
+      topology: createCommandTopology(registry),
+    }, ['unknown-cmd', '--help']);
+
+    expect(out.ok).toBe(true);
+    if (!out.ok) throw new Error('expected success');
+    expect(out.stdout).toBe('USAGE: help text\n');
+    expect(out.stderr[0]).toContain('falling back to gtd-tools.cjs');
+  });
+
+  it('returns structured fallback failure when resolveGtdToolsPath throws', async () => {
+    const registry = createRegistry();
+    const out = await runQueryDispatch({
+      registry,
+      projectDir: tmpDir,
+      cjsFallbackEnabled: true,
+      resolveGtdToolsPath: () => { throw new Error('path boom'); },
+      dispatchNative: async () => ({ data: {} }),
+      topology: createCommandTopology(registry),
+    }, ['unknown-cmd']);
+
+    expect(out.ok).toBe(false);
+    if (out.ok) throw new Error('expected failure');
+    expect(out.error.kind).toBe('fallback_failure');
+    expect(out.error.code).toBe(1);
+    expect(out.error.message).toContain('path boom');
+    expect(out.error.details).toMatchObject({ command: 'unknown-cmd', backend: 'cjs' });
+  });
+
+  it('returns requires-command error for empty argv', async () => {
+    const registry = createRegistry();
+    const out = await runQueryDispatch({
+      registry,
+      projectDir: tmpDir,
+      cjsFallbackEnabled: true,
+      resolveGtdToolsPath: () => '',
+      dispatchNative: async () => ({ data: {} }),
+      topology: createCommandTopology(registry),
+    }, []);
+    expect(out.ok).toBe(false);
+    if (out.ok) throw new Error('expected failure');
+    expect(out.error.code).toBe(10);
+    expect(out.error.kind).toBe('validation_error');
+    expect(out.error.message).toContain('requires a command');
+    expect(out.error.details).toEqual({ reason: 'missing_command' });
+  });
+
+  it('maps native timeout to native_timeout kind with details', async () => {
+    const registry = createRegistry();
+    const out = await runQueryDispatch({
+      registry,
+      projectDir: tmpDir,
+      cjsFallbackEnabled: true,
+      resolveGtdToolsPath: () => '',
+      dispatchNative: async () => { throw new Error('gtd-tools timed out after 30000ms: state load'); },
+      topology: createCommandTopology(registry),
+    }, ['state', 'load']);
+
+    expect(out.ok).toBe(false);
+    if (out.ok) throw new Error('expected failure');
+    expect(out.error.kind).toBe('native_timeout');
+    expect(out.error.code).toBe(1);
+    expect(out.error.details).toMatchObject({ command: 'state.load', args: [], timeout_ms: 30000 });
+  });
+
+  it('maps typed native timeout to native_timeout kind with details', async () => {
+    const registry = createRegistry();
+    const out = await runQueryDispatch({
+      registry,
+      projectDir: tmpDir,
+      cjsFallbackEnabled: true,
+      resolveGtdToolsPath: () => '',
+      dispatchNative: async () => { throw GTDToolsError.timeout('timed out', 'state', ['load'], '', 30000); },
+      topology: createCommandTopology(registry),
+    }, ['state', 'load']);
+
+    expect(out.ok).toBe(false);
+    if (out.ok) throw new Error('expected failure');
+    expect(out.error.kind).toBe('native_timeout');
+    expect(out.error.code).toBe(1);
+    expect(out.error.details).toMatchObject({ command: 'state.load', args: [], timeout_ms: 30000 });
+  });
+
+  it('maps native error to native_failure kind with details', async () => {
+    const registry = createRegistry();
+    const out = await runQueryDispatch({
+      registry,
+      projectDir: tmpDir,
+      cjsFallbackEnabled: true,
+      resolveGtdToolsPath: () => '',
+      dispatchNative: async () => { throw new Error('boom'); },
+      topology: createCommandTopology(registry),
+    }, ['state', 'json']);
+
+    expect(out.ok).toBe(false);
+    if (out.ok) throw new Error('expected failure');
+    expect(out.error.kind).toBe('native_failure');
+    expect(out.error.code).toBe(1);
+    expect(out.error.details).toMatchObject({ command: 'state.json', args: [] });
+  });
+});
+
+// ─── #3259 help-flag non-mutating guard ──────────────────────────────────────
+
+describe('--help guard: dispatcher short-circuits mutating native handlers', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `qdispatch-help-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(join(tmpDir, '.planning', 'phases'), { recursive: true });
+    // Minimal fixture required for most handlers to not crash on fs reads
+    await writeFile(join(tmpDir, '.planning', 'ROADMAP.md'), '# Roadmap\n\n## Current Milestone: v1.0\n', 'utf-8');
+    await writeFile(
+      join(tmpDir, '.planning', 'STATE.md'),
+      '---\ngtd_state_version: 1.0\nmilestone: v1.0\nstatus: executing\n---\n\n# Project State\n',
+      'utf-8',
+    );
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ model_profile: 'balanced', phase_naming: 'sequential' }),
+      'utf-8',
+    );
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  /**
+   * Collect a digest of all file mtimes under .planning/ so we can compare
+   * pre- and post-invocation state without reading file content.
+   */
+  async function collectPlanningDigest(projectDir: string): Promise<Map<string, number>> {
+    const planningDir = join(projectDir, '.planning');
+    const digest = new Map<string, number>();
+    async function walk(dir: string): Promise<void> {
+      let entries;
+      try {
+        entries = await readdir(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+          await walk(full);
+        } else {
+          try {
+            const s = await stat(full);
+            digest.set(full, s.mtimeMs);
+          } catch {
+            /* ignore */
+          }
+        }
+      }
+    }
+    await walk(planningDir);
+    return digest;
+  }
+
+  it('milestone.complete --help returns non-mutating help stub without writing to .planning/', async () => {
+    const registry = createRegistry();
+    const topology = createCommandTopology(registry);
+
+    const preDig = await collectPlanningDigest(tmpDir);
+
+    const out = await runQueryDispatch({
+      registry,
+      projectDir: tmpDir,
+      cjsFallbackEnabled: false,
+      resolveGtdToolsPath: () => '',
+      topology,
+    }, ['milestone.complete', '--help']);
+
+    expect(out.ok).toBe(true);
+    if (!out.ok) throw new Error('expected success');
+
+    // Response must contain help stub, not a milestone record
+    const parsed = JSON.parse(out.stdout) as Record<string, unknown>;
+    expect(typeof parsed.help).toBe('string');
+    expect(parsed.help).toContain('milestone.complete');
+
+    // .planning/ directory must be byte-identical (no new or modified files)
+    const postDig = await collectPlanningDigest(tmpDir);
+    expect(postDig.size).toBe(preDig.size);
+    for (const [path, mtime] of preDig) {
+      expect(postDig.get(path)).toBe(mtime);
+    }
+    // MILESTONES.md must not have been created
+    expect(existsSync(join(tmpDir, '.planning', 'MILESTONES.md'))).toBe(false);
+  });
+
+  it('milestone.complete -h returns non-mutating help stub without writing to .planning/', async () => {
+    const registry = createRegistry();
+    const topology = createCommandTopology(registry);
+
+    const preDig = await collectPlanningDigest(tmpDir);
+
+    const out = await runQueryDispatch({
+      registry,
+      projectDir: tmpDir,
+      cjsFallbackEnabled: false,
+      resolveGtdToolsPath: () => '',
+      topology,
+    }, ['milestone.complete', '-h']);
+
+    expect(out.ok).toBe(true);
+    if (!out.ok) throw new Error('expected success');
+
+    const parsed = JSON.parse(out.stdout) as Record<string, unknown>;
+    expect(typeof parsed.help).toBe('string');
+
+    const postDig = await collectPlanningDigest(tmpDir);
+    expect(postDig.size).toBe(preDig.size);
+    for (const [path, mtime] of preDig) {
+      expect(postDig.get(path)).toBe(mtime);
+    }
+  });
+
+  it('registry-driven: all native mutating handlers with --help do not modify .planning/', async () => {
+    const registry = createRegistry();
+    const topology = createCommandTopology(registry);
+
+    // Collect all registered mutating commands from the manifest
+    const mutatingCommands = Array.from(COMMAND_MUTATION_SET).filter((cmd) => {
+      // Only canonical forms that are registered in the registry (not aliases)
+      return registry.has(cmd);
+    });
+
+    for (const cmd of mutatingCommands) {
+      // Reset fixture between each command to ensure isolation
+      await rm(join(tmpDir, '.planning'), { recursive: true, force: true });
+      await mkdir(join(tmpDir, '.planning', 'phases'), { recursive: true });
+      await writeFile(join(tmpDir, '.planning', 'ROADMAP.md'), '# Roadmap\n\n## Current Milestone: v1.0\n', 'utf-8');
+      await writeFile(
+        join(tmpDir, '.planning', 'STATE.md'),
+        '---\ngtd_state_version: 1.0\nmilestone: v1.0\nstatus: executing\n---\n\n# Project State\n',
+        'utf-8',
+      );
+      await writeFile(
+        join(tmpDir, '.planning', 'config.json'),
+        JSON.stringify({ model_profile: 'balanced', phase_naming: 'sequential' }),
+        'utf-8',
+      );
+
+      const preDig = await collectPlanningDigest(tmpDir);
+
+      // Invoke via dispatcher with --help in args (after the command token)
+      // argv format: [cmd, '--help'] where cmd may be dotted or spaced
+      const argv = [...cmd.split(' '), '--help'];
+      const out = await runQueryDispatch({
+        registry,
+        projectDir: tmpDir,
+        cjsFallbackEnabled: false,
+        resolveGtdToolsPath: () => '',
+        topology,
+      }, argv);
+
+      // Must succeed (help stub) or fail for validation reasons (e.g. arg rewriting
+      // that produces a non-mutating command) — the invariant is no disk mutation.
+      const postDig = await collectPlanningDigest(tmpDir);
+      expect(postDig.size, `${cmd} --help created new .planning files`).toBe(preDig.size);
+      for (const [path, mtime] of preDig) {
+        expect(postDig.get(path), `${cmd} --help modified ${path}`).toBe(mtime);
+      }
+    }
+  });
+
+  it('preserves #3019 contract: unknown-cmd --help falls through to cjs (not intercepted by guard)', async () => {
+    // The guard only fires when a NATIVE MUTATING handler is matched.
+    // Unknown commands with --help must still fall through to CJS fallback.
+    const script = await (async () => {
+      const scriptPath = join(tmpDir, 'text.cjs');
+      await writeFile(scriptPath, "process.stdout.write('USAGE: help text');", { mode: 0o755 });
+      return scriptPath;
+    })();
+
+    const registry = createRegistry();
+    const out = await runQueryDispatch({
+      registry,
+      projectDir: tmpDir,
+      cjsFallbackEnabled: true,
+      resolveGtdToolsPath: () => script,
+      topology: createCommandTopology(registry),
+    }, ['unknown-cmd', '--help']);
+
+    expect(out.ok).toBe(true);
+    if (!out.ok) throw new Error('expected success');
+    expect(out.stdout).toBe('USAGE: help text\n');
+  });
+
+  it('non-mutating native handlers are unaffected when --help is in args', async () => {
+    // E.g. state.json is non-mutating; --help in args should still dispatch normally.
+    const registry = createRegistry();
+    const out = await runQueryDispatch({
+      registry,
+      projectDir: tmpDir,
+      cjsFallbackEnabled: true,
+      resolveGtdToolsPath: () => '',
+      dispatchNative: async () => ({ data: { ok: true } }),
+      topology: createCommandTopology(registry),
+    }, ['state', 'json', '--help']);
+
+    // state.json is non-mutating, so --help should pass through to the handler
+    // The mock handler returns successfully, so we get a success result.
+    expect(out.ok).toBe(true);
+  });
+});

package/sdk/src/query/query-dispatch.ts

@@ -0,0 +1,275 @@
+import type { QueryRegistry } from './registry.js';
+import { extractField } from './registry.js';
+import { normalizeQueryCommand } from './query-command-resolution-strategy.js';
+import { runCjsFallbackDispatch } from './query-fallback-executor.js';
+import type { QueryDispatchError, QueryDispatchResult } from './query-dispatch-contract.js';
+import type { QueryResult } from './utils.js';
+import type { QueryNativeDispatchAdapter } from './query-native-dispatch-adapter.js';
+import type { CommandTopology, CommandTopologyMatch } from './command-topology.js';
+import { unknownCommandError, validationError, fallbackDispatchErrorFromSignal, nativeDispatchErrorFromSignal } from './query-error-taxonomy.js';
+import { canUseCjsFallback } from './query-fallback-policy.js';
+import { toFailureSignal } from '../query-failure-classification.js';
+import { ErrorClassification, GTDError } from '../errors.js';
+
+export interface QueryDispatchDeps {
+  registry: QueryRegistry;
+  projectDir: string;
+  ws?: string;
+  cjsFallbackEnabled: boolean;
+  resolveGtdToolsPath: (projectDir: string) => string;
+  /** @deprecated use topology */
+  dispatchNative?: (cmd: string, args: string[]) => Promise<QueryResult>;
+  /** @deprecated use topology */
+  nativeAdapter?: QueryNativeDispatchAdapter;
+  topology: CommandTopology;
+}
+
+export type DispatchMode = 'native' | 'cjs' | 'error';
+
+export interface DispatchPlan {
+  mode: DispatchMode;
+  normalized: { command: string; args: string[]; tokens: string[] };
+  matched: CommandTopologyMatch | null;
+  noMatchMessage?: string;
+  noMatchNormalized?: string;
+  noMatchAttempted?: string[];
+  noMatchHints?: string[];
+}
+
+export type DispatchSuccessFormat = 'json' | 'text' | undefined;
+
+export interface DispatchInputValidationResult {
+  queryArgs: string[];
+  pickField?: string;
+  error?: QueryDispatchResult;
+}
+
+export function dispatchFailure(error: QueryDispatchError, stderr: string[] = []): QueryDispatchResult {
+  return {
+    ok: false,
+    error,
+    stderr,
+    exit_code: error.code,
+  };
+}
+
+export function dispatchSuccess(stdout: string, stderr: string[] = []): QueryDispatchResult {
+  return {
+    ok: true,
+    stdout,
+    stderr,
+    exit_code: 0,
+  };
+}
+
+export function toDispatchFailure(error: QueryDispatchError, stderr: string[] = []): QueryDispatchResult {
+  return dispatchFailure(error, stderr);
+}
+
+export function mapNativeDispatchError(error: unknown, command: string, args: string[]): QueryDispatchError {
+  if (error instanceof GTDError && error.classification === ErrorClassification.Validation) {
+    return validationError({
+      message: error.message,
+      details: { command, args },
+    });
+  }
+  return nativeDispatchErrorFromSignal(toFailureSignal(error), command, args);
+}
+
+export function mapFallbackDispatchError(error: unknown, command: string, args: string[]): QueryDispatchError {
+  return fallbackDispatchErrorFromSignal(toFailureSignal(error), command, args);
+}
+
+export function formatPick(data: unknown, pickField?: string): unknown {
+  if (!pickField) return data;
+  return extractField(data, pickField);
+}
+
+export function formatSuccess(data: unknown, format: DispatchSuccessFormat, pickField?: string): string {
+  if (format === 'text' && typeof data === 'string') {
+    if (pickField) {
+      throw new Error('--pick is not supported for text output');
+    }
+    return data.endsWith('\n') ? data : `${data}\n`;
+  }
+  const output = formatPick(data, pickField);
+  return `${JSON.stringify(output === undefined ? null : output, null, 2)}\n`;
+}
+
+export function validateQueryDispatchInput(queryArgv: string[]): DispatchInputValidationResult {
+  const queryArgs = [...queryArgv];
+  const pickIdx = queryArgs.indexOf('--pick');
+  if (pickIdx !== -1) {
+    if (pickIdx + 1 >= queryArgs.length) {
+      return {
+        queryArgs,
+        error: dispatchFailure(validationError({
+          message: 'Error: --pick requires a field name',
+          details: { field: '--pick', reason: 'missing_value' },
+        })),
+      };
+    }
+    const pickField = queryArgs[pickIdx + 1];
+    queryArgs.splice(pickIdx, 2);
+    if (queryArgs.length === 0 || !queryArgs[0]) {
+      return {
+        queryArgs,
+        error: dispatchFailure(validationError({
+          message: 'Error: "gtd-sdk query" requires a command',
+          details: { reason: 'missing_command' },
+        })),
+      };
+    }
+    return { queryArgs, pickField };
+  }
+
+  if (queryArgs.length === 0 || !queryArgs[0]) {
+    return {
+      queryArgs,
+      error: dispatchFailure(validationError({
+        message: 'Error: "gtd-sdk query" requires a command',
+        details: { reason: 'missing_command' },
+      })),
+    };
+  }
+
+  return { queryArgs };
+}
+
+function deprecatedTaskWorkflowCommand(command: string): string | null {
+  const normalized = String(command || '').trim();
+  if (normalized === 'execute-phase') {
+    return 'execute-phase has been removed. Use export-phase-issues, work-task-issue, and orchestrate-tasks for task issue work; use work-task-issue --complete-phase <phase> --execute for phase finalization.';
+  }
+  if (normalized === 'check-ship-ready' || normalized === 'ship') {
+    return `${normalized} has been removed. Use export-phase-issues, work-task-issue, orchestrate-tasks, and work-task-issue --complete-phase <phase> --execute under the task issue workflow.`;
+  }
+  return null;
+}
+
+export function planQueryDispatch(
+  queryArgv: string[],
+  topology: CommandTopology,
+  cjsFallbackEnabled: boolean,
+): DispatchPlan {
+  const queryCommand = queryArgv[0];
+  if (!queryCommand) {
+    return { mode: 'error', normalized: { command: '', args: [], tokens: [] }, matched: null };
+  }
+
+  const [normCmd, normArgs] = normalizeQueryCommand(queryCommand, queryArgv.slice(1));
+  const normalizedTokens = [normCmd, ...normArgs];
+  const resolved = topology.resolve(queryArgv, !cjsFallbackEnabled);
+
+  if (resolved.kind === 'match') {
+    return { mode: 'native', normalized: { command: normCmd, args: normArgs, tokens: normalizedTokens }, matched: resolved };
+  }
+
+  if (cjsFallbackEnabled) {
+    return { mode: 'cjs', normalized: { command: normCmd, args: normArgs, tokens: normalizedTokens }, matched: null };
+  }
+
+  return {
+    mode: 'error',
+    normalized: { command: normCmd, args: normArgs, tokens: normalizedTokens },
+    matched: null,
+    noMatchMessage: resolved.message,
+    noMatchNormalized: resolved.normalized,
+    noMatchAttempted: resolved.attempted,
+    noMatchHints: resolved.hints,
+  };
+}
+
+function fail(error: ReturnType<typeof validationError> | ReturnType<typeof unknownCommandError>, stderr: string[] = []): QueryDispatchResult {
+  return toDispatchFailure(error, stderr);
+}
+
+export async function runQueryDispatch(deps: QueryDispatchDeps, queryArgv: string[]): Promise<QueryDispatchResult> {
+  const validated = validateQueryDispatchInput(queryArgv);
+  if (validated.error) return validated.error;
+
+  const { queryArgs, pickField } = validated;
+
+  const deprecatedGuidance = deprecatedTaskWorkflowCommand(queryArgs[0]);
+  if (deprecatedGuidance) {
+    return fail(unknownCommandError({
+      message: `Error: Unknown command: "${queryArgs[0]}". ${deprecatedGuidance}`,
+      normalized: queryArgs.join(' '),
+      attempted: [queryArgs[0]],
+      hints: [
+        'Use export-phase-issues to create GitHub task issues.',
+        'Use work-task-issue for single-task work and phase finalization.',
+        'Use orchestrate-tasks for exact child issue batches.',
+      ],
+    }));
+  }
+
+  const plan = planQueryDispatch(queryArgs, deps.topology, deps.cjsFallbackEnabled);
+  const normCmd = plan.normalized.command;
+  const normArgs = plan.normalized.args;
+
+  if (!normCmd || !String(normCmd).trim()) {
+    return fail(validationError({ message: 'Error: "gtd-sdk query" requires a command', details: { reason: 'empty_normalized_command' } }));
+  }
+
+  if (plan.mode === 'error') {
+    return fail(unknownCommandError({
+      message: plan.noMatchMessage ?? `Error: Unknown command: "${queryArgs[0] ?? normCmd}"`,
+      normalized: plan.noMatchNormalized ?? [normCmd, ...normArgs].join(' ').trim(),
+      attempted: plan.noMatchAttempted ?? [],
+      hints: plan.noMatchHints ?? [],
+    }));
+  }
+
+  if (plan.mode === 'cjs') {
+    if (canUseCjsFallback({ cjsFallbackEnabled: deps.cjsFallbackEnabled })) {
+      try {
+        const gtdPath = deps.resolveGtdToolsPath(deps.projectDir);
+        return await runCjsFallbackDispatch({
+          projectDir: deps.projectDir,
+          gtdToolsPath: gtdPath,
+          normCmd,
+          normArgs,
+          ws: deps.ws,
+          pickField,
+        });
+      } catch (e) {
+        return toDispatchFailure(mapFallbackDispatchError(e, normCmd, normArgs));
+      }
+    }
+    return toDispatchFailure(mapFallbackDispatchError(new Error('CJS fallback denied by policy'), normCmd, normArgs));
+  }
+
+  const matched = plan.matched;
+  if (!matched) {
+    return toDispatchFailure(mapFallbackDispatchError(new Error('No native match in dispatch plan'), normCmd, normArgs));
+  }
+
+  // #3259: guard — if the invocation contains --help / -h AND the matched
+  // handler is a mutating command (mutation: true in the command manifest),
+  // short-circuit to a non-mutating stub. Mutating handlers are not help-aware
+  // by default (fail-closed). This prevents e.g. `milestone.complete --help`
+  // from writing milestone artifacts to disk.
+  const helpFlagPresent = matched.args.some((a) => a === '--help' || a === '-h');
+  if (helpFlagPresent && matched.mutation) {
+    return dispatchSuccess(
+      formatSuccess(
+        { help: `Usage: gtd-sdk query ${matched.canonical} [args...]` },
+        undefined,
+      ),
+    );
+  }
+
+  const dispatchNative = deps.nativeAdapter
+    ? (cmd: string, args: string[]) => deps.nativeAdapter!.dispatch(cmd, args)
+    : deps.dispatchNative;
+
+  try {
+    const result = dispatchNative
+      ? await dispatchNative(matched.canonical, matched.args)
+      : await matched.adapter(matched.args, deps.projectDir, deps.ws);
+    return dispatchSuccess(formatSuccess(result.data, result.format, pickField));
+  } catch (e) {
+    return toDispatchFailure(mapNativeDispatchError(e, matched.canonical, matched.args));
+  }
+}