@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/sdk/src/query/command-manifest.types.ts

@@ -0,0 +1,13 @@
+export type CommandFamily = 'state' | 'verify' | 'init' | 'phase' | 'phases' | 'validate' | 'roadmap';
+
+export type OutputMode = 'json' | 'raw';
+
+export interface CommandManifestEntry {
+  family: CommandFamily;
+  canonical: string;
+  aliases: string[];
+  mutation: boolean;
+  outputMode: OutputMode;
+  /** Optional explicit handler key (defaults to canonical). */
+  handlerKey?: string;
+}

package/sdk/src/query/command-manifest.validate.ts

@@ -0,0 +1,11 @@
+import type { CommandManifestEntry } from './command-manifest.types.js';
+
+/**
+ * Canonical validate.* command manifest.
+ */
+export const VALIDATE_COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
+  { family: 'validate', canonical: 'validate.consistency', aliases: ['validate consistency'], mutation: false, outputMode: 'json' },
+  { family: 'validate', canonical: 'validate.health', aliases: ['validate health'], mutation: false, outputMode: 'json' },
+  { family: 'validate', canonical: 'validate.agents', aliases: ['validate agents'], mutation: false, outputMode: 'json' },
+  { family: 'validate', canonical: 'validate.context', aliases: ['validate context'], mutation: false, outputMode: 'json' },
+] as const;

package/sdk/src/query/command-manifest.verify.ts

@@ -0,0 +1,15 @@
+import type { CommandManifestEntry } from './command-manifest.types.js';
+
+/**
+ * Canonical verify.* command manifest.
+ */
+export const VERIFY_COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
+  { family: 'verify', canonical: 'verify.plan-structure', aliases: ['verify plan-structure'], mutation: false, outputMode: 'json' },
+  { family: 'verify', canonical: 'verify.phase-completeness', aliases: ['verify phase-completeness'], mutation: false, outputMode: 'json' },
+  { family: 'verify', canonical: 'verify.references', aliases: ['verify references'], mutation: false, outputMode: 'json' },
+  { family: 'verify', canonical: 'verify.commits', aliases: ['verify commits'], mutation: false, outputMode: 'json' },
+  { family: 'verify', canonical: 'verify.artifacts', aliases: ['verify artifacts'], mutation: false, outputMode: 'json' },
+  { family: 'verify', canonical: 'verify.key-links', aliases: ['verify key-links'], mutation: false, outputMode: 'json' },
+  { family: 'verify', canonical: 'verify.schema-drift', aliases: ['verify schema-drift'], mutation: false, outputMode: 'json' },
+  { family: 'verify', canonical: 'verify.codebase-drift', aliases: ['verify codebase-drift'], mutation: false, outputMode: 'json' },
+] as const;

package/sdk/src/query/command-resolution.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest';
+import { createRegistry } from './index.js';
+import { explainQueryCommandNoMatch, resolveQueryCommand, resolveQueryTokens } from './query-command-resolution-strategy.js';
+
+describe('command resolution', () => {
+  it('resolves normalized tokens with metadata', () => {
+    const registry = createRegistry();
+    const resolved = resolveQueryTokens(['state', 'update', 'status', 'X'], registry);
+    expect(resolved).toEqual({
+      cmd: 'state.update',
+      args: ['status', 'X'],
+      matchedBy: 'dotted',
+      expanded: false,
+      source: 'normalized',
+    });
+  });
+
+  it('resolves dotted token directly when canonical is registered', () => {
+    const registry = createRegistry();
+    const resolved = resolveQueryTokens(['init.execute-phase', '1'], registry);
+    expect(resolved).toEqual({
+      cmd: 'init.execute-phase',
+      args: ['1'],
+      matchedBy: 'dotted',
+      expanded: false,
+      source: 'normalized',
+    });
+  });
+
+  it('marks expanded source when only spaced command exists', () => {
+    const registry = {
+      has(command: string) {
+        return command === 'init execute-phase';
+      },
+    };
+    const resolved = resolveQueryTokens(['init.execute-phase', '1'], registry);
+    expect(resolved).toEqual({
+      cmd: 'init execute-phase',
+      args: ['1'],
+      matchedBy: 'spaced',
+      expanded: true,
+      source: 'expanded',
+    });
+  });
+
+  it('resolves from raw command+args using normalize rules', () => {
+    const registry = createRegistry();
+    const resolved = resolveQueryCommand('state', ['json'], registry);
+    expect(resolved?.cmd).toBe('state.json');
+    expect(resolved?.args).toEqual([]);
+    expect(resolved?.source).toBe('normalized');
+  });
+
+  it('returns null for unknown command', () => {
+    const registry = createRegistry();
+    expect(resolveQueryCommand('totally-unknown', ['x'], registry)).toBeNull();
+  });
+
+  it('returns structured no-match metadata', () => {
+    const registry = createRegistry();
+    const noMatch = explainQueryCommandNoMatch('state', ['made-up-op', 'x'], registry);
+    expect(noMatch.normalized).toEqual({
+      command: 'state',
+      args: ['made-up-op', 'x'],
+      tokens: ['state', 'made-up-op', 'x'],
+    });
+    expect(noMatch.attempted.dotted[0]).toBe('state.made-up-op.x');
+    expect(noMatch.attempted.spaced[0]).toBe('state made-up-op x');
+  });
+});

package/sdk/src/query/command-seam-coverage.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect } from 'vitest';
+import { createRequire } from 'node:module';
+
+import { createRegistry } from './index.js';
+import { STATE_COMMAND_MANIFEST } from './command-manifest.state.js';
+import { VERIFY_COMMAND_MANIFEST } from './command-manifest.verify.js';
+import { INIT_COMMAND_MANIFEST } from './command-manifest.init.js';
+import { PHASE_COMMAND_MANIFEST } from './command-manifest.phase.js';
+import { PHASES_COMMAND_MANIFEST } from './command-manifest.phases.js';
+import { VALIDATE_COMMAND_MANIFEST } from './command-manifest.validate.js';
+import { ROADMAP_COMMAND_MANIFEST } from './command-manifest.roadmap.js';
+import {
+  STATE_COMMAND_ALIASES,
+  VERIFY_COMMAND_ALIASES,
+  INIT_COMMAND_ALIASES,
+  PHASE_COMMAND_ALIASES,
+  PHASES_COMMAND_ALIASES,
+  VALIDATE_COMMAND_ALIASES,
+  ROADMAP_COMMAND_ALIASES,
+} from './command-aliases.generated.js';
+
+function subcommandFor(canonical: string, family: 'state' | 'verify' | 'init' | 'phase' | 'phases' | 'validate' | 'roadmap'): string {
+  return canonical.slice(`${family}.`.length);
+}
+
+describe('command seam coverage (manifest -> generated -> adapters)', () => {
+  it('state/verify/init/phase/phases/validate/roadmap manifest canonicals are present in generated alias artifacts', () => {
+    const generated = new Map<string, { aliases: string[]; subcommand: string; mutation: boolean }>();
+    for (const entry of [...STATE_COMMAND_ALIASES, ...VERIFY_COMMAND_ALIASES, ...INIT_COMMAND_ALIASES, ...PHASE_COMMAND_ALIASES, ...PHASES_COMMAND_ALIASES, ...VALIDATE_COMMAND_ALIASES, ...ROADMAP_COMMAND_ALIASES]) {
+      generated.set(entry.canonical, { aliases: [...entry.aliases], subcommand: entry.subcommand, mutation: !!entry.mutation });
+    }
+
+    for (const entry of STATE_COMMAND_MANIFEST) {
+      const g = generated.get(entry.canonical);
+      expect(g, `missing generated canonical ${entry.canonical}`).toBeTruthy();
+      expect(g?.subcommand).toBe(subcommandFor(entry.canonical, 'state'));
+      expect(g?.aliases ?? []).toEqual(entry.aliases);
+      expect(g?.mutation).toBe(entry.mutation);
+    }
+
+    for (const entry of VERIFY_COMMAND_MANIFEST) {
+      const g = generated.get(entry.canonical);
+      expect(g, `missing generated canonical ${entry.canonical}`).toBeTruthy();
+      expect(g?.subcommand).toBe(subcommandFor(entry.canonical, 'verify'));
+      expect(g?.aliases ?? []).toEqual(entry.aliases);
+      expect(g?.mutation).toBe(entry.mutation);
+    }
+
+    for (const entry of INIT_COMMAND_MANIFEST) {
+      const g = generated.get(entry.canonical);
+      expect(g, `missing generated canonical ${entry.canonical}`).toBeTruthy();
+      expect(g?.subcommand).toBe(subcommandFor(entry.canonical, 'init'));
+      expect(g?.aliases ?? []).toEqual(entry.aliases);
+      expect(g?.mutation).toBe(entry.mutation);
+    }
+
+    for (const entry of PHASE_COMMAND_MANIFEST) {
+      const g = generated.get(entry.canonical);
+      expect(g, `missing generated canonical ${entry.canonical}`).toBeTruthy();
+      expect(g?.subcommand).toBe(subcommandFor(entry.canonical, 'phase'));
+      expect(g?.aliases ?? []).toEqual(entry.aliases);
+      expect(g?.mutation).toBe(entry.mutation);
+    }
+
+    for (const entry of PHASES_COMMAND_MANIFEST) {
+      const g = generated.get(entry.canonical);
+      expect(g, `missing generated canonical ${entry.canonical}`).toBeTruthy();
+      expect(g?.subcommand).toBe(subcommandFor(entry.canonical, 'phases'));
+      expect(g?.aliases ?? []).toEqual(entry.aliases);
+      expect(g?.mutation).toBe(entry.mutation);
+    }
+
+    for (const entry of VALIDATE_COMMAND_MANIFEST) {
+      const g = generated.get(entry.canonical);
+      expect(g, `missing generated canonical ${entry.canonical}`).toBeTruthy();
+      expect(g?.subcommand).toBe(subcommandFor(entry.canonical, 'validate'));
+      expect(g?.aliases ?? []).toEqual(entry.aliases);
+      expect(g?.mutation).toBe(entry.mutation);
+    }
+
+    for (const entry of ROADMAP_COMMAND_MANIFEST) {
+      const g = generated.get(entry.canonical);
+      expect(g, `missing generated canonical ${entry.canonical}`).toBeTruthy();
+      expect(g?.subcommand).toBe(subcommandFor(entry.canonical, 'roadmap'));
+      expect(g?.aliases ?? []).toEqual(entry.aliases);
+      expect(g?.mutation).toBe(entry.mutation);
+    }
+  });
+
+  it('registry has every canonical + alias for migrated families', () => {
+    const registry = createRegistry();
+    for (const entry of [...STATE_COMMAND_ALIASES, ...VERIFY_COMMAND_ALIASES, ...INIT_COMMAND_ALIASES, ...PHASE_COMMAND_ALIASES, ...PHASES_COMMAND_ALIASES, ...VALIDATE_COMMAND_ALIASES, ...ROADMAP_COMMAND_ALIASES]) {
+      expect(registry.has(entry.canonical), `missing registry canonical ${entry.canonical}`).toBe(true);
+      for (const alias of entry.aliases) {
+        expect(registry.has(alias), `missing registry alias ${alias}`).toBe(true);
+      }
+    }
+  });
+
+  it('CJS seam adapters export expected router functions', () => {
+    const require = createRequire(import.meta.url);
+    const stateRouter = require('../../../sdd/bin/lib/state-command-router.cjs');
+    const verifyRouter = require('../../../sdd/bin/lib/verify-command-router.cjs');
+    const initRouter = require('../../../sdd/bin/lib/init-command-router.cjs');
+    const phaseRouter = require('../../../sdd/bin/lib/phase-command-router.cjs');
+    const phasesRouter = require('../../../sdd/bin/lib/phases-command-router.cjs');
+    const validateRouter = require('../../../sdd/bin/lib/validate-command-router.cjs');
+    const roadmapRouter = require('../../../sdd/bin/lib/roadmap-command-router.cjs');
+
+    expect(typeof stateRouter.routeStateCommand).toBe('function');
+    expect(typeof verifyRouter.routeVerifyCommand).toBe('function');
+    expect(typeof initRouter.routeInitCommand).toBe('function');
+    expect(typeof phaseRouter.routePhaseCommand).toBe('function');
+    expect(typeof phasesRouter.routePhasesCommand).toBe('function');
+    expect(typeof validateRouter.routeValidateCommand).toBe('function');
+    expect(typeof roadmapRouter.routeRoadmapCommand).toBe('function');
+  });
+});

package/sdk/src/query/command-static-catalog-domain.ts

@@ -0,0 +1,117 @@
+import type { QueryHandler } from './utils.js';
+import { agentSkills } from './skills.js';
+import { requirementsMarkComplete } from './roadmap.js';
+import { todoMatchPhase, statsJson, statsTable, progressBar, progressTable, listTodos, todoComplete } from './progress.js';
+import { milestoneComplete } from './phase-lifecycle.js';
+import { summaryExtract, historyDigest } from './summary.js';
+import { commitToSubrepo } from './commit.js';
+import { workstreamGet, workstreamList, workstreamCreate, workstreamSet, workstreamStatus, workstreamComplete, workstreamProgress } from './workstream.js';
+import { docsInit } from './docs-init.js';
+import { websearch } from './websearch.js';
+import { learningsCopy, learningsQuery, learningsListHandler, learningsPrune, learningsDelete, extractMessages, scanSessions, profileSample, profileQuestionnaire } from './profile.js';
+import { skillManifest } from './skill-manifest.js';
+import { auditOpen } from './audit-open.js';
+import { detectCustomFiles } from './detect-custom-files.js';
+import { uatRenderCheckpoint, auditUat } from './uat.js';
+import { intelStatus, intelDiff, intelSnapshot, intelValidate, intelQuery, intelExtractExports, intelPatchMeta, intelUpdate } from './intel.js';
+import { writeProfile, generateClaudeProfile, generateDevPreferences, generateClaudeMd } from './profile-output.js';
+import { phaseMvpMode, taskIsBehaviorAdding, userStoryValidate } from './mvp.js';
+import { worktreeCleanupWave } from './worktree.js';
+
+export const DOMAIN_STATIC_CATALOG: ReadonlyArray<readonly [string, QueryHandler]> = [
+  ['agent-skills', agentSkills],
+  ['requirements.mark-complete', requirementsMarkComplete],
+  ['requirements mark-complete', requirementsMarkComplete],
+  ['todo.match-phase', todoMatchPhase],
+  ['todo match-phase', todoMatchPhase],
+  ['list-todos', listTodos],
+  ['list.todos', listTodos],
+  ['todo.complete', todoComplete],
+  ['todo complete', todoComplete],
+  ['milestone.complete', milestoneComplete],
+  ['milestone complete', milestoneComplete],
+  ['summary.extract', summaryExtract],
+  ['summary extract', summaryExtract],
+  ['summary-extract', summaryExtract],
+  ['history.digest', historyDigest],
+  ['history digest', historyDigest],
+  ['history-digest', historyDigest],
+  ['stats', statsJson],
+  ['stats.json', statsJson],
+  ['stats json', statsJson],
+  ['stats.table', statsTable],
+  ['stats table', statsTable],
+  ['commit-to-subrepo', commitToSubrepo],
+  ['progress.bar', progressBar],
+  ['progress bar', progressBar],
+  ['progress.table', progressTable],
+  ['progress table', progressTable],
+  ['workstream.get', workstreamGet],
+  ['workstream get', workstreamGet],
+  ['workstream.list', workstreamList],
+  ['workstream list', workstreamList],
+  ['workstream.create', workstreamCreate],
+  ['workstream create', workstreamCreate],
+  ['workstream.set', workstreamSet],
+  ['workstream set', workstreamSet],
+  ['workstream.status', workstreamStatus],
+  ['workstream status', workstreamStatus],
+  ['workstream.complete', workstreamComplete],
+  ['workstream complete', workstreamComplete],
+  ['workstream.progress', workstreamProgress],
+  ['workstream progress', workstreamProgress],
+  ['worktree.cleanup-wave', worktreeCleanupWave],
+  ['worktree cleanup-wave', worktreeCleanupWave],
+  ['docs-init', docsInit],
+  ['websearch', websearch],
+  ['learnings.copy', learningsCopy],
+  ['learnings copy', learningsCopy],
+  ['learnings.query', learningsQuery],
+  ['learnings query', learningsQuery],
+  ['learnings.list', learningsListHandler],
+  ['learnings list', learningsListHandler],
+  ['learnings.prune', learningsPrune],
+  ['learnings prune', learningsPrune],
+  ['learnings.delete', learningsDelete],
+  ['learnings delete', learningsDelete],
+  ['skill-manifest', skillManifest],
+  ['skill manifest', skillManifest],
+  ['audit-open', auditOpen],
+  ['audit open', auditOpen],
+  ['detect-custom-files', detectCustomFiles],
+  ['extract-messages', extractMessages],
+  ['extract.messages', extractMessages],
+  ['audit-uat', auditUat],
+  ['uat.render-checkpoint', uatRenderCheckpoint],
+  ['uat render-checkpoint', uatRenderCheckpoint],
+  ['intel.diff', intelDiff],
+  ['intel diff', intelDiff],
+  ['intel.snapshot', intelSnapshot],
+  ['intel snapshot', intelSnapshot],
+  ['intel.validate', intelValidate],
+  ['intel validate', intelValidate],
+  ['intel.status', intelStatus],
+  ['intel status', intelStatus],
+  ['intel.query', intelQuery],
+  ['intel query', intelQuery],
+  ['intel.extract-exports', intelExtractExports],
+  ['intel extract-exports', intelExtractExports],
+  ['intel.patch-meta', intelPatchMeta],
+  ['intel patch-meta', intelPatchMeta],
+  ['intel.update', intelUpdate],
+  ['intel update', intelUpdate],
+  ['generate-claude-profile', generateClaudeProfile],
+  ['generate-dev-preferences', generateDevPreferences],
+  ['write-profile', writeProfile],
+  ['profile-questionnaire', profileQuestionnaire],
+  ['profile-sample', profileSample],
+  ['scan-sessions', scanSessions],
+  ['generate-claude-md', generateClaudeMd],
+  // ── MVP umbrella (#2826) — centralized resolution seams ──
+  ['phase.mvp-mode', phaseMvpMode],
+  ['phase mvp-mode', phaseMvpMode],
+  ['task.is-behavior-adding', taskIsBehaviorAdding],
+  ['task is-behavior-adding', taskIsBehaviorAdding],
+  ['user-story.validate', userStoryValidate],
+  ['user-story validate', userStoryValidate],
+] as const;

package/sdk/src/query/command-static-catalog-foundation.ts

@@ -0,0 +1,103 @@
+import type { QueryHandler } from './utils.js';
+import { generateSlug, currentTimestamp } from './utils.js';
+import { frontmatterGet } from './frontmatter.js';
+import { configGet, configPath, resolveModel } from './config-query.js';
+import { stateSnapshot } from './state.js';
+import { findPhase, phasePlanIndex } from './phase.js';
+import { planTaskStructure } from './plan-task-structure.js';
+import { requirementsExtractFromPlans } from './requirements-extract-from-plans.js';
+import { progressJson } from './progress.js';
+import { frontmatterSet, frontmatterMerge, frontmatterValidate } from './frontmatter-mutation.js';
+import { configSet, configSetModelProfile, configNewProject, configEnsureSection } from './config-mutation.js';
+import { commit, checkCommit } from './commit.js';
+import { templateFill, templateSelect } from './template.js';
+import { verifySummary, verifyPathExists } from './verify.js';
+import { decisionsParse } from './decisions.js';
+import { checkDecisionCoveragePlan, checkDecisionCoverageVerify } from './check-decision-coverage.js';
+import { commandsList } from './commands-list.js';
+import { checkConfigGates } from './config-gates.js';
+import { checkAutoMode } from './check-auto-mode.js';
+import { checkPhaseReady } from './phase-ready.js';
+import { routeNextAction } from './route-next-action.js';
+import { detectPhaseType } from './detect-phase-type.js';
+import { checkCompletion } from './check-completion.js';
+import { checkGates } from './check-gates.js';
+import { checkVerificationStatus } from './check-verification-status.js';
+import { checkShipReady } from './check-ship-ready.js';
+import { agentClassifyFailure } from './agent-failure-classifier.js';
+
+export const FOUNDATION_STATIC_CATALOG: ReadonlyArray<readonly [string, QueryHandler]> = [
+  ['generate-slug', generateSlug],
+  ['current-timestamp', currentTimestamp],
+  ['frontmatter.get', frontmatterGet],
+  ['config-get', configGet],
+  ['config-path', configPath],
+  ['resolve-model', resolveModel],
+] as const;
+
+export const STATE_SUPPORT_STATIC_CATALOG: ReadonlyArray<readonly [string, QueryHandler]> = [
+  ['state-snapshot', stateSnapshot],
+  ['find-phase', findPhase],
+  ['phase-plan-index', phasePlanIndex],
+  ['plan.task-structure', planTaskStructure],
+  ['plan task-structure', planTaskStructure],
+  ['requirements.extract-from-plans', requirementsExtractFromPlans],
+  ['requirements extract-from-plans', requirementsExtractFromPlans],
+] as const;
+
+export const MUTATION_SURFACES_STATIC_CATALOG: ReadonlyArray<readonly [string, QueryHandler]> = [
+  ['progress', progressJson],
+  ['progress.json', progressJson],
+  ['frontmatter.set', frontmatterSet],
+  ['frontmatter.merge', frontmatterMerge],
+  ['frontmatter.validate', frontmatterValidate],
+  ['frontmatter validate', frontmatterValidate],
+  ['config-set', configSet],
+  ['config-set-model-profile', configSetModelProfile],
+  ['config-new-project', configNewProject],
+  ['config-ensure-section', configEnsureSection],
+  ['commit', commit],
+  ['check-commit', checkCommit],
+  ['template.fill', templateFill],
+  ['template.select', templateSelect],
+  ['template select', templateSelect],
+] as const;
+
+export const VERIFY_DECISION_STATIC_CATALOG: ReadonlyArray<readonly [string, QueryHandler]> = [
+  ['verify-summary', verifySummary],
+  ['verify.summary', verifySummary],
+  ['verify summary', verifySummary],
+  ['verify-path-exists', verifyPathExists],
+  ['verify.path-exists', verifyPathExists],
+  ['verify path-exists', verifyPathExists],
+  ['decisions.parse', decisionsParse],
+  ['decisions parse', decisionsParse],
+  ['check.decision-coverage-plan', checkDecisionCoveragePlan],
+  ['check decision-coverage-plan', checkDecisionCoveragePlan],
+  ['check.decision-coverage-verify', checkDecisionCoverageVerify],
+  ['check decision-coverage-verify', checkDecisionCoverageVerify],
+] as const;
+
+export const DECISION_ROUTING_STATIC_CATALOG: ReadonlyArray<readonly [string, QueryHandler]> = [
+  ['check.config-gates', checkConfigGates],
+  ['check config-gates', checkConfigGates],
+  ['check.auto-mode', checkAutoMode],
+  ['check auto-mode', checkAutoMode],
+  ['check.phase-ready', checkPhaseReady],
+  ['check phase-ready', checkPhaseReady],
+  ['route.next-action', routeNextAction],
+  ['route next-action', routeNextAction],
+  ['detect.phase-type', detectPhaseType],
+  ['detect phase-type', detectPhaseType],
+  ['check.completion', checkCompletion],
+  ['check completion', checkCompletion],
+  ['check.gates', checkGates],
+  ['check gates', checkGates],
+  ['check.verification-status', checkVerificationStatus],
+  ['check verification-status', checkVerificationStatus],
+  ['check.ship-ready', checkShipReady],
+  ['check ship-ready', checkShipReady],
+  ['commands', commandsList],
+  ['agent.classify-failure', agentClassifyFailure],
+  ['agent classify-failure', agentClassifyFailure],
+] as const;

package/sdk/src/query/command-topology.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'vitest';
+import { createRegistry } from './index.js';
+import { createCommandTopology } from './command-topology.js';
+
+describe('command-topology', () => {
+  it('resolves native command with adapter', () => {
+    const registry = createRegistry();
+    const topology = createCommandTopology(registry);
+
+    const out = topology.resolve(['state', 'json']);
+    expect(out.kind).toBe('match');
+    if (out.kind !== 'match') throw new Error('expected match');
+    expect(out.canonical).toBe('state.json');
+    expect(out.args).toEqual([]);
+    expect(typeof out.adapter).toBe('function');
+  });
+
+  it('returns no_match with diagnosis', () => {
+    const registry = createRegistry();
+    const topology = createCommandTopology(registry);
+
+    const out = topology.resolve(['unknown-cmd'], true);
+    expect(out.kind).toBe('no_match');
+    if (out.kind !== 'no_match') throw new Error('expected no_match');
+    expect(out.message).toContain('Unknown command');
+    expect(out.attempted.length).toBeGreaterThanOrEqual(0);
+  });
+});

package/sdk/src/query/command-topology.ts

@@ -0,0 +1,114 @@
+import type { QueryRegistry } from './registry.js';
+import type { QueryHandler } from './utils.js';
+import {
+  resolveQueryCommand,
+  explainQueryCommandNoMatch,
+  type QueryCommandRegistryLike,
+} from './query-command-resolution-strategy.js';
+import { supportsMutationCommand, supportsRawOutputCommand } from './query-policy-capability.js';
+import { UNKNOWN_COMMAND_HINTS } from './query-unknown-command-hints.js';
+import { describeFallbackDisabledPolicy } from './query-fallback-policy.js';
+
+export type CommandTopologyOutputMode = 'json' | 'text' | 'raw';
+
+export interface CommandTopologyMatch {
+  kind: 'match';
+  canonical: string;
+  args: string[];
+  output_mode: CommandTopologyOutputMode;
+  mutation: boolean;
+  adapter: QueryHandler;
+}
+
+export interface CommandTopologyNoMatch {
+  kind: 'no_match';
+  attempted: string[];
+  normalized?: string;
+  hints: string[];
+  message: string;
+}
+
+export type CommandTopologyResult = CommandTopologyMatch | CommandTopologyNoMatch;
+
+export interface CommandTopology {
+  resolve(tokens: string[], fallbackRestricted?: boolean): CommandTopologyResult;
+}
+
+export interface UnknownCommandDiagnosis {
+  normalized: string;
+  attempted: string[];
+  hints: string[];
+  message: string;
+}
+
+export function diagnoseUnknownCommand(
+  command: string,
+  args: string[],
+  registry: QueryCommandRegistryLike,
+  fallbackRestricted: boolean,
+): UnknownCommandDiagnosis {
+  const noMatch = explainQueryCommandNoMatch(command, args, registry);
+  const normalized = [noMatch.normalized.command, ...noMatch.normalized.args].join(' ');
+  const attempted = noMatch.attempted.dotted.slice(0, 2);
+  const hints = [...UNKNOWN_COMMAND_HINTS];
+  const attemptedSuffix = attempted.length > 0 ? ` Attempted dotted: ${attempted.join(' | ')}.` : '';
+  const fallbackClause = fallbackRestricted ? `${describeFallbackDisabledPolicy()} ` : '';
+  const message = `Error: Unknown command: "${normalized}". ${hints[0]} ${hints[1]} ${fallbackClause}${hints[2]}${attemptedSuffix}`;
+
+  return {
+    normalized,
+    attempted,
+    hints,
+    message,
+  };
+}
+
+export function createCommandTopology(registry: QueryRegistry): CommandTopology {
+  return {
+    resolve(tokens: string[], fallbackRestricted = false): CommandTopologyResult {
+      const command = tokens[0];
+      const args = tokens.slice(1);
+      if (!command) {
+        return {
+          kind: 'no_match',
+          attempted: [],
+          hints: [],
+          message: 'Error: "sdd-sdk query" requires a command',
+        };
+      }
+
+      const matched = resolveQueryCommand(command, args, registry);
+      if (!matched) {
+        const diagnosis = diagnoseUnknownCommand(command, args, registry, fallbackRestricted);
+        return {
+          kind: 'no_match',
+          normalized: diagnosis.normalized,
+          attempted: diagnosis.attempted,
+          hints: diagnosis.hints,
+          message: diagnosis.message,
+        };
+      }
+
+      const adapter = registry.getHandler(matched.cmd);
+      if (!adapter) {
+        const diagnosis = diagnoseUnknownCommand(command, args, registry, fallbackRestricted);
+        return {
+          kind: 'no_match',
+          normalized: diagnosis.normalized,
+          attempted: diagnosis.attempted,
+          hints: diagnosis.hints,
+          message: diagnosis.message,
+        };
+      }
+
+      return {
+        kind: 'match',
+        canonical: matched.cmd,
+        args: matched.args,
+        output_mode: supportsRawOutputCommand(matched.cmd) ? 'raw' : 'json',
+        mutation: supportsMutationCommand(matched.cmd),
+        adapter,
+      };
+    },
+  };
+}

package/sdk/src/query/commands-list.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest';
+import { commandsList } from './commands-list.js';
+
+// Regression test for bug #3121.
+// The `commands` verb was missing from the SDK native registry.
+// `sdd-sdk query commands` fell back to sdd-tools.cjs which threw
+// "Unknown command: commands".
+describe('commands-list handler (#3121)', () => {
+  it('returns a non-empty sorted JSON array of command strings', async () => {
+    const result = await commandsList([], '/tmp', undefined);
+    expect(result.data).toBeDefined();
+    expect(Array.isArray(result.data)).toBe(true);
+    expect((result.data as string[]).length).toBeGreaterThan(10);
+  });
+
+  it('includes known canonical commands', async () => {
+    const result = await commandsList([], '/tmp', undefined);
+    const cmds = result.data as string[];
+    expect(cmds).toContain('state.begin-phase');
+    expect(cmds).toContain('check.decision-coverage-plan');
+    expect(cmds).toContain('commands');
+  });
+
+  it('is sorted alphabetically', async () => {
+    const result = await commandsList([], '/tmp', undefined);
+    const cmds = result.data as string[];
+    const sorted = [...cmds].sort((a, b) => a.localeCompare(b));
+    expect(cmds).toEqual(sorted);
+  });
+
+  it('args and workstream are ignored (introspection verb)', async () => {
+    const r1 = await commandsList([], '/tmp', undefined);
+    const r2 = await commandsList(['ignored'], '/other', 'ws');
+    expect(r1.data).toEqual(r2.data);
+  });
+});

package/sdk/src/query/commands-list.ts

@@ -0,0 +1,19 @@
+import type { QueryHandler } from './utils.js';
+import { createRegistry } from './index.js';
+
+/**
+ * `commands` — return the full list of registered query command strings.
+ *
+ * Closes #3121: the `commands` verb was referenced in workflow files
+ * (references/workstream-flag.md) but had no native SDK handler, causing
+ * a fallback to sdd-tools.cjs which threw "Unknown command: commands".
+ *
+ * Returns: JSON array of all canonical + alias command strings the SDK
+ * registry accepts, sorted alphabetically. Suitable for discoverability
+ * and for agent auto-complete when constructing `sdd-sdk query` calls.
+ */
+export const commandsList: QueryHandler<string[]> = async (_args, _projectDir) => {
+  const registry = createRegistry();
+  const cmds = registry.commands().sort((a, b) => a.localeCompare(b));
+  return { data: cmds };
+};