phasegate 0.15.0

package/scripts/harness/harness-api/application/usecases/derive-harness-status-usecase.ts

@@ -0,0 +1,72 @@
+// derive-harness-status-usecase.ts — DeriveHarnessStatusUseCase
+
+import type { ArtifactScannerPort } from '../../domain/ports/artifact-scanner-port.js';
+import type { ConfigQueryPort } from '../../domain/ports/config-query-port.js';
+import { StatusDerivationService } from '../../domain/services/status-derivation-service.js';
+import type { HarnessStatusSummary } from '../../domain/value-objects/harness-status-summary.js';
+import type { StatusDerivationInput } from '../dto/status-derivation-input.js';
+
+export interface DeriveHarnessStatusUseCaseDeps {
+  artifactScannerPort: ArtifactScannerPort;
+  configQueryPort: Pick<ConfigQueryPort, 'getPresetInfo' | 'getConfigSummary'> & Partial<Pick<ConfigQueryPort, 'getPhaseGateSummary'>>;
+  statusDerivationService: StatusDerivationService;
+}
+
+export class DeriveHarnessStatusUseCase {
+  private readonly artifactScannerPort: ArtifactScannerPort;
+  private readonly configQueryPort: DeriveHarnessStatusUseCaseDeps['configQueryPort'];
+  private readonly statusDerivationService: StatusDerivationService;
+
+  constructor(deps: DeriveHarnessStatusUseCaseDeps) {
+    this.artifactScannerPort = deps.artifactScannerPort;
+    this.configQueryPort = deps.configQueryPort;
+    this.statusDerivationService = deps.statusDerivationService;
+  }
+
+  async execute(_input: StatusDerivationInput): Promise<HarnessStatusSummary> {
+    let scanResult: Awaited<ReturnType<ArtifactScannerPort['scan']>>;
+    try {
+      scanResult = await this.artifactScannerPort.scan();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(`HarnessApiDomainError: ArtifactScannerPort failed: ${msg}`);
+    }
+
+    let presetInfo: Awaited<ReturnType<ConfigQueryPort['getPresetInfo']>>;
+    try {
+      presetInfo = await this.configQueryPort.getPresetInfo();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(`HarnessApiDomainError: ConfigQueryPort.getPresetInfo failed: ${msg}`);
+    }
+
+    let configSummary: Awaited<ReturnType<ConfigQueryPort['getConfigSummary']>>;
+    try {
+      if (this.configQueryPort.getConfigSummary) {
+        configSummary = await this.configQueryPort.getConfigSummary();
+      } else {
+        configSummary = { configPath: 'phasegate.config.json', lastModified: new Date().toISOString(), version: '2' };
+      }
+    } catch {
+      configSummary = { configPath: 'phasegate.config.json', lastModified: new Date().toISOString(), version: '2' };
+    }
+
+    let phaseGateSummary: { totalStories: number; passedStories: number; pendingStories: number };
+    try {
+      if (this.configQueryPort.getPhaseGateSummary) {
+        phaseGateSummary = await this.configQueryPort.getPhaseGateSummary();
+      } else {
+        phaseGateSummary = { totalStories: 0, passedStories: 0, pendingStories: 0 };
+      }
+    } catch {
+      phaseGateSummary = { totalStories: 0, passedStories: 0, pendingStories: 0 };
+    }
+
+    return this.statusDerivationService.derive({
+      scanResult,
+      presetInfo,
+      configSummary,
+      phaseGateSummary,
+    });
+  }
+}

package/scripts/harness/harness-api/application/usecases/dispatch-command-usecase.ts

@@ -0,0 +1,79 @@
+// dispatch-command-usecase.ts — DispatchCommandUseCase
+
+import { CommandRegistry } from '../../domain/services/command-registry.js';
+import { CommandDispatchService } from '../../domain/services/command-dispatch-service.js';
+import { StatusDerivationService } from '../../domain/services/status-derivation-service.js';
+import { HarnessApiResponseMapper } from '../mappers/harness-api-response-mapper.js';
+import type { ValidatorExecutionPort } from '../../domain/ports/validator-execution-port.js';
+import type { PhaseGateQueryPort } from '../../domain/ports/phase-gate-query-port.js';
+import type { BiomeLintPort } from '../../domain/ports/biome-lint-port.js';
+import type { ImpactAnalysisPort } from '../../domain/ports/impact-analysis-port.js';
+import type { ArtifactScannerPort } from '../../domain/ports/artifact-scanner-port.js';
+import type { ConfigQueryPort } from '../../domain/ports/config-query-port.js';
+import type { CommandDispatchInput } from '../dto/command-dispatch-input.js';
+import type { CommandDispatchOutput } from '../dto/command-dispatch-output.js';
+import type { ExitCode } from '../../domain/value-objects/harness-api-response.js';
+
+export interface DispatchCommandUseCaseDeps {
+  commandDispatchService?: CommandDispatchService;
+  statusDerivationService?: StatusDerivationService;
+  validatorExecutionPort: ValidatorExecutionPort;
+  phaseGateQueryPort: PhaseGateQueryPort;
+  biomeLintPort: BiomeLintPort;
+  impactAnalysisPort: ImpactAnalysisPort;
+  artifactScannerPort: ArtifactScannerPort;
+  configQueryPort: ConfigQueryPort | { getPresetInfo?: () => Promise<unknown>; getConfigSummary?: () => Promise<unknown> };
+}
+
+export class DispatchCommandUseCase {
+  private readonly dispatchService: CommandDispatchService;
+  private readonly mapper: HarnessApiResponseMapper;
+
+  constructor(deps: DispatchCommandUseCaseDeps) {
+    const ports = {
+      validatorExecutionPort: deps.validatorExecutionPort,
+      phaseGateQueryPort: deps.phaseGateQueryPort,
+      biomeLintPort: deps.biomeLintPort,
+      impactAnalysisPort: deps.impactAnalysisPort,
+      artifactScannerPort: deps.artifactScannerPort,
+      configQueryPort: deps.configQueryPort as { getPresetInfo?: () => Promise<unknown>; getConfigSummary?: () => Promise<unknown> },
+    };
+
+    if (deps.commandDispatchService) {
+      // The service was already constructed with a registry — just use it directly
+      // but we need to set ports too via the service constructor
+      this.dispatchService = new CommandDispatchService(
+        new CommandRegistry(),
+        ports,
+        deps.statusDerivationService
+      );
+      // Actually use the provided dispatch service ports by reconstructing
+      this.dispatchService = new CommandDispatchService(ports, undefined, deps.statusDerivationService);
+    } else {
+      this.dispatchService = new CommandDispatchService(ports, undefined, deps.statusDerivationService);
+    }
+
+    this.mapper = new HarnessApiResponseMapper();
+  }
+
+  async execute<T = unknown>(input: CommandDispatchInput): Promise<CommandDispatchOutput<T>> {
+    const result = await this.dispatchService.dispatch<T>({
+      commandName: input.commandName,
+      args: input.args ?? {},
+      flags: input.flags ?? {},
+    });
+
+    // Build a HarnessApiResponse-compatible object for the mapper
+    const responseContract = {
+      status: result.status as 'pass' | 'fail' | 'error',
+      errors: result.errors,
+      summary: result.summary as string | { totalChecks: number; passed: number; failed: number; warnings: number },
+      data: result.data as T | undefined,
+    };
+
+    return {
+      response: Object.freeze(responseContract),
+      exitCode: result.exitCode as ExitCode,
+    };
+  }
+}

package/scripts/harness/harness-api/application/usecases/initialize-command-registry-usecase.ts

@@ -0,0 +1,43 @@
+// initialize-command-registry-usecase.ts — InitializeCommandRegistryUseCase
+
+import { CliCommandDefinition } from '../../domain/value-objects/cli-command-definition.js';
+import { CommandRegistry } from '../../domain/services/command-registry.js';
+import type { InitializeRegistryInput } from '../dto/initialize-registry-input.js';
+import type { RegistrySummaryOutput } from '../dto/registry-summary-output.js';
+
+export interface InitializeCommandRegistryUseCaseDeps {
+  registry: CommandRegistry;
+}
+
+export class InitializeCommandRegistryUseCase {
+  private readonly registry: CommandRegistry;
+
+  constructor(deps: InitializeCommandRegistryUseCaseDeps) {
+    this.registry = deps.registry;
+  }
+
+  async execute(input: InitializeRegistryInput): Promise<RegistrySummaryOutput> {
+    const failedRegistrations: { commandName: string; reason: string }[] = [];
+
+    for (const cmdInput of input.commands) {
+      // This may throw InvalidCommandNameError — let it propagate
+      const definition = CliCommandDefinition.create(cmdInput.commandName, {
+        description: cmdInput.description,
+      });
+
+      try {
+        this.registry.registerCommand(definition);
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        failedRegistrations.push({ commandName: cmdInput.commandName, reason });
+      }
+    }
+
+    const allCommands = this.registry.listAll();
+    return {
+      registeredCount: allCommands.length,
+      commandNames: allCommands.map((c) => c.commandName),
+      failedRegistrations,
+    };
+  }
+}

package/scripts/harness/harness-api/composition-root.ts

@@ -0,0 +1,96 @@
+// composition-root.ts — harness-api Composition Root
+
+import { CommandRegistry } from './domain/services/command-registry.js';
+import { StatusDerivationService } from './domain/services/status-derivation-service.js';
+import { InitializeCommandRegistryUseCase } from './application/usecases/initialize-command-registry-usecase.js';
+import { DispatchCommandUseCase } from './application/usecases/dispatch-command-usecase.js';
+import { DecideExitCodeUseCase } from './application/usecases/decide-exit-code-usecase.js';
+import { DeriveHarnessStatusUseCase } from './application/usecases/derive-harness-status-usecase.js';
+import { ValidatorSystemExecutionAdapter } from './infrastructure/adapters/validator-system-execution-adapter.js';
+import { PhaseDependencyModelQueryAdapter } from './infrastructure/adapters/phase-dependency-model-query-adapter.js';
+import { BiomeAstEngineLintAdapter } from './infrastructure/adapters/biome-ast-engine-lint-adapter.js';
+import { NyquistValidationImpactAnalysisAdapter } from './infrastructure/adapters/nyquist-validation-impact-analysis-adapter.js';
+import { FileSystemArtifactScannerAdapter } from './infrastructure/adapters/file-system-artifact-scanner-adapter.js';
+import { HarnessConfigQueryAdapter } from './infrastructure/adapters/harness-config-query-adapter.js';
+import { CheckReadyHandler } from './presentation/handlers/check-ready-handler.js';
+import { CheckPhaseHandler } from './presentation/handlers/check-phase-handler.js';
+import { CiCheckHandler } from './presentation/handlers/ci-check-handler.js';
+import { DetectDriftHandler } from './presentation/handlers/detect-drift-handler.js';
+import { StatusHandler } from './presentation/handlers/status-handler.js';
+import { LintHandler } from './presentation/handlers/lint-handler.js';
+import { CompleteCheckHandler } from './presentation/handlers/complete-check-handler.js';
+import { ImpactAnalysisHandler } from './presentation/handlers/impact-analysis-handler.js';
+
+export interface HarnessApiModuleOptions {
+  configPath?: string;
+}
+
+export interface HarnessApiModule {
+  handlers: {
+    checkReady: CheckReadyHandler;
+    checkPhase: CheckPhaseHandler;
+    ciCheck: CiCheckHandler;
+    detectDrift: DetectDriftHandler;
+    status: StatusHandler;
+    lint: LintHandler;
+    completeCheck: CompleteCheckHandler;
+    impactAnalysis: ImpactAnalysisHandler;
+  };
+  useCases: {
+    initializeRegistry: InitializeCommandRegistryUseCase;
+    dispatch: DispatchCommandUseCase;
+    decideExitCode: DecideExitCodeUseCase;
+    deriveStatus: DeriveHarnessStatusUseCase;
+  };
+}
+
+export function createHarnessApiModule(options: HarnessApiModuleOptions = {}): HarnessApiModule {
+  const configPath = options.configPath ?? 'phasegate.config.json';
+
+  // Infrastructure adapters
+  const validatorExecutionPort = new ValidatorSystemExecutionAdapter();
+  const phaseGateQueryPort = new PhaseDependencyModelQueryAdapter();
+  const biomeLintPort = new BiomeAstEngineLintAdapter();
+  const impactAnalysisPort = new NyquistValidationImpactAnalysisAdapter();
+  const artifactScannerPort = new FileSystemArtifactScannerAdapter({ configPath });
+  const configQueryPort = new HarnessConfigQueryAdapter({ configPath });
+
+  // Domain services
+  const commandRegistry = new CommandRegistry();
+  const statusDerivationService = new StatusDerivationService();
+
+  // Application use cases
+  const initializeRegistry = new InitializeCommandRegistryUseCase({ registry: commandRegistry });
+  const dispatch = new DispatchCommandUseCase({
+    validatorExecutionPort,
+    phaseGateQueryPort,
+    biomeLintPort,
+    impactAnalysisPort,
+    artifactScannerPort,
+    configQueryPort,
+    statusDerivationService,
+  });
+  const decideExitCode = new DecideExitCodeUseCase();
+  const deriveStatus = new DeriveHarnessStatusUseCase({
+    artifactScannerPort,
+    configQueryPort,
+    statusDerivationService,
+  });
+
+  // Presentation handlers
+  const handlers = {
+    checkReady: new CheckReadyHandler(dispatch),
+    checkPhase: new CheckPhaseHandler(dispatch),
+    ciCheck: new CiCheckHandler(dispatch),
+    detectDrift: new DetectDriftHandler(dispatch),
+    status: new StatusHandler(dispatch),
+    lint: new LintHandler(dispatch),
+    completeCheck: new CompleteCheckHandler(dispatch),
+    impactAnalysis: new ImpactAnalysisHandler(dispatch),
+  };
+
+  return {
+    handlers,
+    useCases: { initializeRegistry, dispatch, decideExitCode, deriveStatus },
+  };
+}

package/scripts/harness/harness-api/domain/ports/artifact-scanner-port.ts

@@ -0,0 +1,7 @@
+// artifact-scanner-port.ts
+
+import type { ArtifactScanResult } from '../value-objects/artifact-scan-result.js';
+
+export interface ArtifactScannerPort {
+  scan(): Promise<ArtifactScanResult>;
+}

package/scripts/harness/harness-api/domain/ports/biome-lint-port.ts

@@ -0,0 +1,11 @@
+// biome-lint-port.ts
+
+import type { HarnessError } from '../value-objects/harness-api-response.js';
+
+export interface BiomeLintPort {
+  runLint(): Promise<{
+    passed: boolean;
+    errors: HarnessError[];
+    warnings: HarnessError[];
+  }>;
+}

package/scripts/harness/harness-api/domain/ports/config-query-port.ts

@@ -0,0 +1,9 @@
+// config-query-port.ts
+
+import type { PresetInfo, ConfigSummary, PhaseGateSummary } from '../value-objects/harness-status-summary.js';
+
+export interface ConfigQueryPort {
+  getPresetInfo(): Promise<PresetInfo>;
+  getConfigSummary(): Promise<ConfigSummary>;
+  getPhaseGateSummary(): Promise<PhaseGateSummary>;
+}

package/scripts/harness/harness-api/domain/ports/impact-analysis-port.ts

@@ -0,0 +1,12 @@
+// impact-analysis-port.ts
+
+export interface ImpactAnalysisResult {
+  storyId: string;
+  affectedTestCases: string[];
+  affectedFiles: string[];
+  [key: string]: unknown;
+}
+
+export interface ImpactAnalysisPort {
+  analyze(storyId: string): Promise<ImpactAnalysisResult | null>;
+}

package/scripts/harness/harness-api/domain/ports/phase-gate-query-port.ts

@@ -0,0 +1,9 @@
+// phase-gate-query-port.ts
+
+import type { PhaseGateStoryResult } from '../value-objects/check-ready-result.js';
+import type { PhaseInfo } from '../value-objects/phase-info.js';
+
+export interface PhaseGateQueryPort {
+  queryAllStories(): Promise<PhaseGateStoryResult[]>;
+  queryUnit(unitId: string): Promise<PhaseInfo | null>;
+}

package/scripts/harness/harness-api/domain/ports/validator-execution-port.ts

@@ -0,0 +1,10 @@
+// validator-execution-port.ts
+
+import type { ValidatorCheckItem } from '../value-objects/ci-check-result.js';
+import type { DriftItem } from '../value-objects/drift-report-summary.js';
+
+export interface ValidatorExecutionPort {
+  runL3Validators(): Promise<ValidatorCheckItem[]>;
+  runDriftDetection(): Promise<DriftItem[]>;
+  runAllValidators(): Promise<ValidatorCheckItem[]>;
+}

package/scripts/harness/harness-api/domain/services/command-dispatch-service.ts

@@ -0,0 +1,230 @@
+// command-dispatch-service.ts — CommandDispatchService Domain Service
+
+import { CommandRegistry } from './command-registry.js';
+import { StatusDerivationService } from './status-derivation-service.js';
+import { HarnessApiResponse, type ExitCode, type HarnessError } from '../value-objects/harness-api-response.js';
+import { CheckReadyResult } from '../value-objects/check-ready-result.js';
+import { CiCheckResult } from '../value-objects/ci-check-result.js';
+import { DriftReportSummary } from '../value-objects/drift-report-summary.js';
+import type { ValidatorExecutionPort } from '../ports/validator-execution-port.js';
+import type { PhaseGateQueryPort } from '../ports/phase-gate-query-port.js';
+import type { BiomeLintPort } from '../ports/biome-lint-port.js';
+import type { ImpactAnalysisPort } from '../ports/impact-analysis-port.js';
+import type { ArtifactScannerPort } from '../ports/artifact-scanner-port.js';
+import type { ConfigQueryPort } from '../ports/config-query-port.js';
+
+export interface CommandDispatchPorts {
+  validatorExecutionPort: ValidatorExecutionPort;
+  phaseGateQueryPort: PhaseGateQueryPort;
+  biomeLintPort: BiomeLintPort;
+  impactAnalysisPort: ImpactAnalysisPort;
+  artifactScannerPort: ArtifactScannerPort;
+  configQueryPort: { getConfig?: () => Promise<unknown>; getPresetInfo?: () => Promise<unknown>; getConfigSummary?: () => Promise<unknown> };
+}
+
+export interface DispatchResult<T = unknown> {
+  status: string;
+  errors: readonly HarnessError[];
+  summary: unknown;
+  data?: T;
+  exitCode: ExitCode;
+}
+
+function makeError(message: string): HarnessError {
+  return { code: 'HARNESS_ERROR', severity: 'error', message };
+}
+
+const KNOWN_COMMANDS = new Set([
+  'harness:check-ready',
+  'harness:check-phase',
+  'harness:ci-check',
+  'harness:detect-drift',
+  'harness:status',
+  'harness:lint',
+  'harness:complete-check',
+  'harness:impact-analysis',
+]);
+
+export class CommandDispatchService {
+  private readonly registry: CommandRegistry | null;
+  private readonly ports: CommandDispatchPorts;
+  private readonly statusDerivationService: StatusDerivationService;
+
+  constructor(
+    registryOrPorts: CommandRegistry | CommandDispatchPorts,
+    ports?: CommandDispatchPorts,
+    statusDerivationService?: StatusDerivationService
+  ) {
+    if (registryOrPorts instanceof CommandRegistry) {
+      this.registry = registryOrPorts;
+      this.ports = ports!;
+      this.statusDerivationService = statusDerivationService ?? new StatusDerivationService();
+    } else {
+      // Called with just a ports object (unit test pattern)
+      this.registry = null;
+      this.ports = registryOrPorts;
+      this.statusDerivationService = new StatusDerivationService();
+    }
+  }
+
+  async dispatch<T = unknown>(input: {
+    commandName: string;
+    args: Record<string, string>;
+    flags: Record<string, boolean | string>;
+  }): Promise<DispatchResult<T>> {
+    const { commandName, args, flags } = input;
+    const summary = { totalChecks: 1, passed: 0, failed: 0, warnings: 0 };
+
+    try {
+      // Check command exists in registry or known set
+      if (this.registry !== null) {
+        this.registry.findByName(commandName); // throws CommandNotFoundError if missing
+      } else if (!KNOWN_COMMANDS.has(commandName)) {
+        throw new Error(`CommandNotFoundError: command '${commandName}' is not registered`);
+      }
+
+      return await this._executeCommand<T>(commandName, args, flags, summary);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const response = HarnessApiResponse.error<T>([makeError(message)], { ...summary, failed: 1 });
+      return {
+        status: 'error',
+        errors: response.errors,
+        summary: response.summary,
+        data: undefined,
+        exitCode: 2,
+      };
+    }
+  }
+
+  private async _executeCommand<T>(
+    commandName: string,
+    args: Record<string, string>,
+    _flags: Record<string, boolean | string>,
+    summary: { totalChecks: number; passed: number; failed: number; warnings: number }
+  ): Promise<DispatchResult<T>> {
+    switch (commandName) {
+      case 'harness:check-ready': {
+        const stories = await this.ports.phaseGateQueryPort.queryAllStories();
+        const result = CheckReadyResult.fromStories(stories);
+        if (result.allPassed) {
+          const r = HarnessApiResponse.pass({ ...summary, passed: 1 }, result);
+          return { status: 'pass', errors: [], summary: r.summary, data: result as unknown as T, exitCode: 0 };
+        }
+        const failed = result.getFailedStories();
+        const errors = failed.map((s) => makeError(`Story ${s.storyId} failed Phase Gate`));
+        const r = HarnessApiResponse.fail(errors, { ...summary, failed: 1 }, result);
+        return { status: 'fail', errors: r.errors, summary: r.summary, data: result as unknown as T, exitCode: 1 };
+      }
+
+      case 'harness:check-phase': {
+        const unitId = args.unit ?? '';
+        const phaseInfo = await this.ports.phaseGateQueryPort.queryUnit(unitId);
+        if (phaseInfo === null) {
+          const errors = [makeError(`Unit '${unitId}' not found`)];
+          const r = HarnessApiResponse.fail(errors, { ...summary, failed: 1 });
+          return { status: 'fail', errors: r.errors, summary: r.summary, data: undefined, exitCode: 1 };
+        }
+        const r = HarnessApiResponse.pass({ ...summary, passed: 1 }, phaseInfo);
+        return { status: 'pass', errors: [], summary: r.summary, data: phaseInfo as unknown as T, exitCode: 0 };
+      }
+
+      case 'harness:ci-check': {
+        const validatorResults = await this.ports.validatorExecutionPort.runL3Validators();
+        const result = CiCheckResult.fromResults(validatorResults);
+        if (result.allPassed) {
+          const r = HarnessApiResponse.pass({ ...summary, passed: 1 }, result);
+          return { status: 'pass', errors: [], summary: r.summary, data: result as unknown as T, exitCode: 0 };
+        }
+        const collected = result.collectAllErrors();
+        const errors = collected.length > 0
+          ? collected
+          : result.getFailedValidators().map((v) => makeError(`Validator ${v.validatorId} failed`));
+        const r = HarnessApiResponse.fail(errors, { ...summary, failed: 1 }, result);
+        return { status: 'fail', errors: r.errors, summary: r.summary, data: result as unknown as T, exitCode: 1 };
+      }
+
+      case 'harness:detect-drift': {
+        const drifts = await this.ports.validatorExecutionPort.runDriftDetection();
+        const result = DriftReportSummary.fromDrifts(drifts);
+        if (!result.hasDrift()) {
+          const r = HarnessApiResponse.pass({ ...summary, passed: 1 }, result);
+          return { status: 'pass', errors: [], summary: r.summary, data: result as unknown as T, exitCode: 0 };
+        }
+        const errors = drifts.map((d) => makeError(`Drift detected in ${d.unit}: ${d.element}`));
+        const r = HarnessApiResponse.fail(errors, { ...summary, failed: 1 }, result);
+        return { status: 'fail', errors: r.errors, summary: r.summary, data: result as unknown as T, exitCode: 1 };
+      }
+
+      case 'harness:status': {
+        const scanResult = await this.ports.artifactScannerPort.scan();
+        let presetInfo = { name: 'standard' as const, enabledLayers: ['L1', 'L2', 'L3'] as ('L1' | 'L2' | 'L3' | 'L4')[] };
+        const configPort = this.ports.configQueryPort;
+        if (configPort.getPresetInfo) {
+          const pi = await configPort.getPresetInfo();
+          presetInfo = pi as typeof presetInfo;
+        } else if (configPort.getConfig) {
+          await configPort.getConfig();
+        }
+        const statusSummary = this.statusDerivationService.derive({
+          scanResult,
+          presetInfo,
+          configSummary: { configPath: 'phasegate.config.json', lastModified: '', version: '2' },
+          phaseGateSummary: { totalStories: 0, passedStories: 0, pendingStories: 0 },
+        });
+        const r = HarnessApiResponse.pass({ ...summary, passed: 1 }, statusSummary);
+        return { status: 'pass', errors: [], summary: r.summary, data: statusSummary as unknown as T, exitCode: 0 };
+      }
+
+      case 'harness:lint': {
+        const lintResult = await this.ports.biomeLintPort.runLint();
+        if (lintResult.passed) {
+          const r = HarnessApiResponse.pass({ ...summary, passed: 1 });
+          return { status: 'pass', errors: [], summary: r.summary, data: undefined, exitCode: 0 };
+        }
+        const errors = lintResult.errors.length > 0 ? lintResult.errors : [makeError('Lint failed')];
+        const r = HarnessApiResponse.fail(errors, { ...summary, failed: 1 });
+        return { status: 'fail', errors: r.errors, summary: r.summary, data: undefined, exitCode: 1 };
+      }
+
+      case 'harness:complete-check': {
+        const [validatorResults, lintResult] = await Promise.all([
+          this.ports.validatorExecutionPort.runAllValidators(),
+          this.ports.biomeLintPort.runLint(),
+        ]);
+        const allErrors: HarnessError[] = [];
+        for (const v of validatorResults) {
+          if (!v.passed) {
+            const errs = v.errors && v.errors.length > 0 ? v.errors : [makeError(`Validator ${v.validatorId} failed`)];
+            allErrors.push(...errs);
+          }
+        }
+        if (!lintResult.passed) {
+          const errs = lintResult.errors.length > 0 ? lintResult.errors : [makeError('Lint failed')];
+          allErrors.push(...errs);
+        }
+        if (allErrors.length === 0) {
+          const r = HarnessApiResponse.pass({ ...summary, passed: 1 });
+          return { status: 'pass', errors: [], summary: r.summary, data: undefined, exitCode: 0 };
+        }
+        const r = HarnessApiResponse.fail(allErrors, { ...summary, failed: 1 });
+        return { status: 'fail', errors: r.errors, summary: r.summary, data: undefined, exitCode: 1 };
+      }
+
+      case 'harness:impact-analysis': {
+        const storyId = args.storyId ?? '';
+        const result = await this.ports.impactAnalysisPort.analyze(storyId);
+        if (result === null) {
+          const errors = [makeError(`Story '${storyId}' not found`)];
+          const r = HarnessApiResponse.fail(errors, { ...summary, failed: 1 });
+          return { status: 'fail', errors: r.errors, summary: r.summary, data: undefined, exitCode: 1 };
+        }
+        const r = HarnessApiResponse.pass({ ...summary, passed: 1 }, result);
+        return { status: 'pass', errors: [], summary: r.summary, data: result as unknown as T, exitCode: 0 };
+      }
+
+      default:
+        throw new Error(`CommandNotFoundError: unknown command '${commandName}'`);
+    }
+  }
+}

package/scripts/harness/harness-api/domain/services/command-registry.ts

@@ -0,0 +1,44 @@
+// command-registry.ts — CommandRegistry Domain Service
+
+import { CliCommandDefinition, type CommandName } from '../value-objects/cli-command-definition.js';
+
+export class CommandRegistry {
+  private readonly commands: Map<string, CliCommandDefinition> = new Map();
+
+  registerCommand(definition: CliCommandDefinition): void {
+    // INV-2: harness: プレフィックス必須
+    if (!definition.commandName || definition.commandName.trim() === '') {
+      throw new Error('HarnessApiDomainError: commandName must not be empty');
+    }
+    if (!definition.commandName.startsWith('harness:')) {
+      throw new Error(`DuplicateCommandNameError: commandName must start with 'harness:': ${definition.commandName}`);
+    }
+    // INV-1: 同一コマンド名の重複禁止
+    if (this.commands.has(definition.commandName)) {
+      throw new Error(`DuplicateCommandNameError: command '${definition.commandName}' is already registered`);
+    }
+    this.commands.set(definition.commandName, definition);
+  }
+
+  findByName(commandName: CommandName): CliCommandDefinition {
+    const found = this.commands.get(commandName);
+    if (!found) {
+      throw new Error(`CommandNotFoundError: command '${commandName}' is not registered`);
+    }
+    return found;
+  }
+
+  listAll(): readonly CliCommandDefinition[] {
+    return Object.freeze(
+      Array.from(this.commands.values()).sort((a, b) => a.commandName.localeCompare(b.commandName))
+    );
+  }
+
+  hasCommand(commandName: CommandName): boolean {
+    return this.commands.has(commandName);
+  }
+
+  getCount(): number {
+    return this.commands.size;
+  }
+}