phasegate 0.15.0

package/scripts/harness/harness-api/domain/value-objects/phase-info.ts

@@ -0,0 +1,37 @@
+// phase-info.ts — PhaseInfo Value Object
+
+export interface PhaseInfoProps {
+  unitId: string;
+  currentLevel: number;
+  currentPhase: string;
+  completedGates: readonly string[];
+}
+
+export class PhaseInfo {
+  readonly unitId: string;
+  readonly currentLevel: number;
+  readonly currentPhase: string;
+  readonly completedGates: readonly string[];
+
+  private constructor(props: PhaseInfoProps) {
+    this.unitId = props.unitId;
+    this.currentLevel = props.currentLevel;
+    this.currentPhase = props.currentPhase;
+    this.completedGates = Object.freeze([...props.completedGates]);
+    Object.freeze(this);
+  }
+
+  static create(props: PhaseInfoProps): PhaseInfo {
+    if (!props.unitId || props.unitId.trim() === '') {
+      throw new Error('HarnessApiDomainError: unitId must not be empty');
+    }
+    if (props.currentLevel <= 0 || !Number.isInteger(props.currentLevel)) {
+      throw new Error(`HarnessApiDomainError: currentLevel must be a positive integer, got ${props.currentLevel}`);
+    }
+    return new PhaseInfo(props);
+  }
+
+  hasCompletedGate(gateName: string): boolean {
+    return this.completedGates.includes(gateName);
+  }
+}

package/scripts/harness/harness-api/index.ts

@@ -0,0 +1,29 @@
+// index.ts — harness-api public barrel export
+
+// Composition Root
+export { createHarnessApiModule } from './composition-root.js';
+export type { HarnessApiModule, HarnessApiModuleOptions } from './composition-root.js';
+
+// Domain Value Objects
+export { CliCommandDefinition } from './domain/value-objects/cli-command-definition.js';
+export { HarnessApiResponse } from './domain/value-objects/harness-api-response.js';
+export { CheckReadyResult } from './domain/value-objects/check-ready-result.js';
+export { CiCheckResult } from './domain/value-objects/ci-check-result.js';
+export { DriftReportSummary } from './domain/value-objects/drift-report-summary.js';
+export { HarnessStatusSummary } from './domain/value-objects/harness-status-summary.js';
+export { ArtifactScanResult } from './domain/value-objects/artifact-scan-result.js';
+export { LayerHealth } from './domain/value-objects/layer-health.js';
+export { PhaseInfo } from './domain/value-objects/phase-info.js';
+export { CommandInputSpec } from './domain/value-objects/command-input-spec.js';
+export { ExitCodeSpec } from './domain/value-objects/exit-code-spec.js';
+
+// Domain Services
+export { CommandRegistry } from './domain/services/command-registry.js';
+export { CommandDispatchService } from './domain/services/command-dispatch-service.js';
+export { StatusDerivationService } from './domain/services/status-derivation-service.js';
+
+// Application Use Cases
+export { InitializeCommandRegistryUseCase } from './application/usecases/initialize-command-registry-usecase.js';
+export { DispatchCommandUseCase } from './application/usecases/dispatch-command-usecase.js';
+export { DecideExitCodeUseCase } from './application/usecases/decide-exit-code-usecase.js';
+export { DeriveHarnessStatusUseCase } from './application/usecases/derive-harness-status-usecase.js';

package/scripts/harness/harness-api/infrastructure/adapters/biome-ast-engine-lint-adapter.ts

@@ -0,0 +1,84 @@
+// biome-ast-engine-lint-adapter.ts — BiomeAstEngineLintAdapter
+// Wave 2完了後にリアル実装へ差し替え（旧: @stub: wave2-pending）
+
+import type { BiomeLintPort } from '../../domain/ports/biome-lint-port.js';
+import type { HarnessError } from '../../domain/value-objects/harness-api-response.js';
+
+interface RuleViolation {
+  filePath: string;
+  line: number;
+  column: number;
+  ruleName: string;
+  message: string;
+  severity: string;
+  fix_example?: string;
+}
+
+interface BiomeAstEngineResult {
+  violations: RuleViolation[];
+}
+
+// Override interface preserved for testing
+export interface IBiomeAstEngineStub {
+  runLint(): Promise<BiomeAstEngineResult>;
+}
+
+function violationToHarnessError(v: RuleViolation): HarnessError {
+  return {
+    code: v.ruleName,
+    severity: v.severity,
+    message: `${v.message} (${v.filePath}:${v.line}:${v.column})`,
+    suggestion: v.fix_example,
+  };
+}
+
+export class BiomeAstEngineLintAdapter implements BiomeLintPort {
+  private readonly stub: IBiomeAstEngineStub;
+
+  constructor(stub?: IBiomeAstEngineStub) {
+    this.stub = stub ?? BiomeAstEngineLintAdapter.createRealImpl();
+  }
+
+  private static createRealImpl(): IBiomeAstEngineStub {
+    const rootDir = process.cwd();
+    return {
+      async runLint(): Promise<BiomeAstEngineResult> {
+        const { createBiomeAstEngineModule } = await import('../../../biome-ast-engine/composition-root.js');
+        const biomeModule = createBiomeAstEngineModule(rootDir);
+        const output = await biomeModule.executeLintUseCase.execute();
+        return {
+          violations: output.report.violations.map((v) => ({
+            filePath: v.filePath.toString(),
+            line: v.line,
+            column: v.column,
+            ruleName: v.ruleName.toString(),
+            message: v.message,
+            severity: v.severity,
+            fix_example: v.fixExample ?? undefined,
+          })),
+        };
+      },
+    };
+  }
+
+  async runLint(): Promise<{ passed: boolean; errors: HarnessError[]; warnings: HarnessError[] }> {
+    const result = await this.stub.runLint();
+    const errors: HarnessError[] = [];
+    const warnings: HarnessError[] = [];
+
+    for (const v of result.violations) {
+      const harnessError = violationToHarnessError(v);
+      if (v.severity === 'warning') {
+        warnings.push(harnessError);
+      } else {
+        errors.push(harnessError);
+      }
+    }
+
+    return {
+      passed: errors.length === 0,
+      errors,
+      warnings,
+    };
+  }
+}

package/scripts/harness/harness-api/infrastructure/adapters/file-system-artifact-scanner-adapter.ts

@@ -0,0 +1,131 @@
+// file-system-artifact-scanner-adapter.ts — FileSystemArtifactScannerAdapter
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type { ArtifactScannerPort } from '../../domain/ports/artifact-scanner-port.js';
+import { ArtifactScanResult, type ArtifactPresence } from '../../domain/value-objects/artifact-scan-result.js';
+import type { LayerHealth } from '../../domain/value-objects/layer-health.js';
+
+interface HarnessConfigPaths {
+  designDocs?: string;
+  integrationTests?: string;
+}
+
+interface HarnessConfigJson {
+  paths?: HarnessConfigPaths;
+}
+
+export interface FileSystemArtifactScannerAdapterOptions {
+  basePath?: string;
+  configPath?: string;
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function directoryHasFiles(dirPath: string): Promise<boolean> {
+  try {
+    const entries = await fs.readdir(dirPath, { recursive: true });
+    return entries.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function loadConfig(configPath: string): Promise<HarnessConfigJson> {
+  const content = await fs.readFile(configPath, 'utf-8');
+  return JSON.parse(content) as HarnessConfigJson;
+}
+
+export class FileSystemArtifactScannerAdapter implements ArtifactScannerPort {
+  private readonly basePath: string | undefined;
+  private readonly configPath: string | undefined;
+
+  constructor(options: FileSystemArtifactScannerAdapterOptions = {}) {
+    this.basePath = options.basePath;
+    this.configPath = options.configPath;
+  }
+
+  async scan(): Promise<ArtifactScanResult> {
+    const scannedPaths: string[] = [];
+    const foundArtifacts: ArtifactPresence[] = [];
+
+    if (this.basePath !== undefined) {
+      // Fixture-based scan: check for existence of layer directories/files
+      await this.scanFixtureDirectory(this.basePath, scannedPaths, foundArtifacts);
+    } else if (this.configPath !== undefined) {
+      // Config-based scan
+      await this.scanFromConfig(this.configPath, scannedPaths, foundArtifacts);
+    } else {
+      throw new Error('FileSystemArtifactScannerAdapter: either basePath or configPath must be provided');
+    }
+
+    return ArtifactScanResult.create({
+      scannedPaths,
+      foundArtifacts,
+      derivedLayerHealth: [] as LayerHealth[],
+    });
+  }
+
+  private async scanFixtureDirectory(
+    basePath: string,
+    scannedPaths: string[],
+    foundArtifacts: ArtifactPresence[]
+  ): Promise<void> {
+    // Verify basePath exists
+    const baseExists = await fileExists(basePath);
+    if (!baseExists) {
+      throw new Error(`FileSystemArtifactScannerAdapter: basePath does not exist: ${basePath}`);
+    }
+
+    scannedPaths.push(basePath);
+
+    // Scan for L1 artifacts: docs/product/construction/**
+    const l1Path = path.join(basePath, 'docs', 'product', 'construction');
+    scannedPaths.push(l1Path);
+    const l1Present = await directoryHasFiles(l1Path);
+    foundArtifacts.push({ layer: 'L1', present: l1Present, path: l1Present ? l1Path : null });
+
+    // Scan for L2 artifacts: docs/product/construction/**/logical_design*
+    const l2Present = await fileExists(path.join(l1Path, 'harness-api', 'logical_design.md'));
+    foundArtifacts.push({ layer: 'L2', present: l2Present, path: l2Present ? path.join(l1Path, 'harness-api', 'logical_design.md') : null });
+
+    // Scan for L3 artifacts: scripts/harness/__tests__/integration/**
+    const l3Path = path.join(basePath, 'scripts', 'harness', '__tests__', 'integration');
+    scannedPaths.push(l3Path);
+    const l3Present = await directoryHasFiles(l3Path);
+    foundArtifacts.push({ layer: 'L3', present: l3Present, path: l3Present ? l3Path : null });
+
+    // Scan for L4 artifacts: scripts/harness/__tests__/integration/**/command-dispatch*
+    const l4Path = path.join(l3Path, 'harness-api', 'command-dispatch-integration.test.ts');
+    const l4Present = await fileExists(l4Path);
+    foundArtifacts.push({ layer: 'L4', present: l4Present, path: l4Present ? l4Path : null });
+  }
+
+  private async scanFromConfig(
+    configPath: string,
+    scannedPaths: string[],
+    foundArtifacts: ArtifactPresence[]
+  ): Promise<void> {
+    const config = await loadConfig(configPath);
+    const designDocsPath = config.paths?.designDocs ?? 'docs/product/construction';
+    const integrationTestsPath = config.paths?.integrationTests ?? 'scripts/harness/__tests__/integration';
+
+    scannedPaths.push(designDocsPath);
+    scannedPaths.push(integrationTestsPath);
+
+    // L1: design docs existence
+    const l1Present = await fileExists(designDocsPath);
+    foundArtifacts.push({ layer: 'L1', present: l1Present, path: l1Present ? designDocsPath : null });
+
+    // L3: integration tests existence
+    const l3Present = await fileExists(integrationTestsPath);
+    foundArtifacts.push({ layer: 'L3', present: l3Present, path: l3Present ? integrationTestsPath : null });
+  }
+}

package/scripts/harness/harness-api/infrastructure/adapters/harness-config-query-adapter.ts

@@ -0,0 +1,66 @@
+// harness-config-query-adapter.ts — HarnessConfigQueryAdapter
+
+import * as fs from 'node:fs/promises';
+import type { ConfigQueryPort } from '../../domain/ports/config-query-port.js';
+import type { PresetInfo, ConfigSummary, PhaseGateSummary } from '../../domain/value-objects/harness-status-summary.js';
+import type { LayerId } from '../../domain/value-objects/layer-health.js';
+
+interface HarnessConfigJson {
+  version: number;
+  project: {
+    name: string;
+    preset: 'minimal' | 'standard' | 'strict';
+  };
+  paths?: {
+    designDocs?: string;
+    integrationTests?: string;
+  };
+}
+
+const PRESET_LAYERS: Record<string, LayerId[]> = {
+  minimal: ['L1'],
+  standard: ['L1', 'L2', 'L3'],
+  strict: ['L1', 'L2', 'L3', 'L4'],
+};
+
+export interface HarnessConfigQueryAdapterOptions {
+  configPath: string;
+}
+
+export class HarnessConfigQueryAdapter implements ConfigQueryPort {
+  private readonly configPath: string;
+  private cachedConfig: HarnessConfigJson | null = null;
+
+  constructor(options: HarnessConfigQueryAdapterOptions) {
+    this.configPath = options.configPath;
+  }
+
+  private async readConfig(): Promise<HarnessConfigJson> {
+    if (this.cachedConfig !== null) return this.cachedConfig;
+    const content = await fs.readFile(this.configPath, 'utf-8');
+    this.cachedConfig = JSON.parse(content) as HarnessConfigJson;
+    return this.cachedConfig;
+  }
+
+  async getPresetInfo(): Promise<PresetInfo> {
+    const config = await this.readConfig();
+    const preset = config.project.preset;
+    const enabledLayers = PRESET_LAYERS[preset] ?? ['L1', 'L2', 'L3'];
+    return { name: preset, enabledLayers };
+  }
+
+  async getConfigSummary(): Promise<ConfigSummary> {
+    await this.readConfig();
+    const stat = await fs.stat(this.configPath);
+    return {
+      configPath: this.configPath,
+      lastModified: stat.mtime.toISOString(),
+      version: '2',
+    };
+  }
+
+  async getPhaseGateSummary(): Promise<PhaseGateSummary> {
+    // wave2-pending: integrate with phase-dependency-model
+    return { totalStories: 0, passedStories: 0, pendingStories: 0 };
+  }
+}

package/scripts/harness/harness-api/infrastructure/adapters/nyquist-validation-impact-analysis-adapter.ts

@@ -0,0 +1,61 @@
+// nyquist-validation-impact-analysis-adapter.ts — NyquistValidationImpactAnalysisAdapter
+// Wave 2完了後にリアル実装へ差し替え（旧: @stub: wave2-pending）
+
+import type { ImpactAnalysisPort, ImpactAnalysisResult } from '../../domain/ports/impact-analysis-port.js';
+
+const STORY_ID_REGEX = /^H\d{2}-\d{2}$/;
+
+// Override interface preserved for testing
+export interface INyquistValidationStub {
+  analyzeImpact(storyId: string): Promise<ImpactAnalysisResult | null>;
+}
+
+export class NyquistValidationImpactAnalysisAdapter implements ImpactAnalysisPort {
+  private readonly stub: INyquistValidationStub;
+
+  constructor(stub?: INyquistValidationStub) {
+    this.stub = stub ?? NyquistValidationImpactAnalysisAdapter.createRealImpl();
+  }
+
+  private static createRealImpl(): INyquistValidationStub {
+    const rootDir = process.cwd();
+    const matrixFilePath = '.harness/requirement-test-matrix.json';
+    return {
+      async analyzeImpact(storyId: string): Promise<ImpactAnalysisResult | null> {
+        try {
+          const { createTraceabilityModelModule } = await import('../../../traceability-model/composition-root.js');
+          const traceModule = createTraceabilityModelModule(rootDir);
+          const storyIds = await traceModule.storyCatalog.getAllStoryIds();
+
+          const { createNyquistValidationModule } = await import('../../../nyquist-validation/composition-root.js');
+          const nyquistModule = createNyquistValidationModule({
+            getStoryIds: async () => storyIds.map((s) => s.value),
+          });
+
+          const output = await nyquistModule.analyzeImpactUseCase.execute({
+            storyId,
+            matrixFilePath,
+          });
+
+          if (!output.found) return null;
+
+          const affectedFiles = output.directTests.map((t) => t.filePath);
+          return {
+            storyId: output.storyId,
+            affectedTestCases: affectedFiles,
+            affectedFiles,
+          };
+        } catch {
+          return null;
+        }
+      },
+    };
+  }
+
+  async analyze(storyId: string): Promise<ImpactAnalysisResult | null> {
+    if (!STORY_ID_REGEX.test(storyId)) {
+      throw new Error(`HarnessApiDomainError: invalid storyId format '${storyId}'. Must match HXX-XX`);
+    }
+    return this.stub.analyzeImpact(storyId);
+  }
+}

package/scripts/harness/harness-api/infrastructure/adapters/phase-dependency-model-query-adapter.ts

@@ -0,0 +1,86 @@
+// phase-dependency-model-query-adapter.ts — PhaseDependencyModelQueryAdapter
+// Wave 2完了後にリアル実装へ差し替え（旧: @stub: wave2-pending）
+
+import type { PhaseGateQueryPort } from '../../domain/ports/phase-gate-query-port.js';
+import type { PhaseGateStoryResult } from '../../domain/value-objects/check-ready-result.js';
+import { PhaseInfo } from '../../domain/value-objects/phase-info.js';
+
+// Override interface preserved for testing
+export interface IPhaseDependencyModelStub {
+  queryAllStories(): Promise<PhaseGateStoryResult[]>;
+  queryUnit(unitId: string): Promise<PhaseInfo | null>;
+}
+
+export class PhaseDependencyModelQueryAdapter implements PhaseGateQueryPort {
+  private readonly stub: IPhaseDependencyModelStub;
+
+  constructor(stub?: IPhaseDependencyModelStub) {
+    this.stub = stub ?? PhaseDependencyModelQueryAdapter.createRealImpl();
+  }
+
+  private static createRealImpl(): IPhaseDependencyModelStub {
+    const rootDir = process.cwd();
+    return {
+      async queryAllStories(): Promise<PhaseGateStoryResult[]> {
+        try {
+          const { createTraceabilityModelModule } = await import('../../../traceability-model/composition-root.js');
+          const traceModule = createTraceabilityModelModule(rootDir);
+          const storyIds = await traceModule.storyCatalog.getAllStoryIds();
+
+          const { createPhaseDependencyModelModule } = await import('../../../phase-dependency-model/composition-root.js');
+          const phaseModule = createPhaseDependencyModelModule({ rootDir });
+
+          const results: PhaseGateStoryResult[] = [];
+          for (const sid of storyIds) {
+            try {
+              const output = await phaseModule.checkPhaseGateCommandHandler.execute({
+                targetLevel: 1,
+                storyId: sid.value,
+              });
+              const result = output.result;
+              results.push({
+                storyId: sid.value,
+                passed: result?.passed ?? false,
+                missingPhases: result ? [...result.blockers] : [],
+              });
+            } catch {
+              results.push({ storyId: sid.value, passed: false, missingPhases: [] });
+            }
+          }
+          return results;
+        } catch {
+          return [];
+        }
+      },
+
+      async queryUnit(unitId: string): Promise<PhaseInfo | null> {
+        try {
+          const { createPhaseDependencyModelModule } = await import('../../../phase-dependency-model/composition-root.js');
+          const phaseModule = createPhaseDependencyModelModule({ rootDir });
+          const output = await phaseModule.checkPhaseGateCommandHandler.execute({
+            targetLevel: 1,
+            unitId,
+          });
+          const result = output.result;
+          if (!result) return null;
+          return PhaseInfo.create({
+            unitId,
+            currentLevel: result.targetLevel,
+            currentPhase: `PHASE-${result.targetLevel}`,
+            completedGates: result.passed ? [`level-${result.targetLevel}`] : [],
+          });
+        } catch {
+          return null;
+        }
+      },
+    };
+  }
+
+  async queryAllStories(): Promise<PhaseGateStoryResult[]> {
+    return this.stub.queryAllStories();
+  }
+
+  async queryUnit(unitId: string): Promise<PhaseInfo | null> {
+    return this.stub.queryUnit(unitId);
+  }
+}

package/scripts/harness/harness-api/infrastructure/adapters/validator-system-execution-adapter.ts

@@ -0,0 +1,74 @@
+// validator-system-execution-adapter.ts — ValidatorSystemExecutionAdapter
+// Wave 2完了後にリアル実装へ差し替え（旧: @stub: wave2-pending）
+
+import type { ValidatorExecutionPort } from '../../domain/ports/validator-execution-port.js';
+import type { ValidatorCheckItem } from '../../domain/value-objects/ci-check-result.js';
+import type { DriftItem } from '../../domain/value-objects/drift-report-summary.js';
+
+// Override interface preserved for testing
+export interface IValidatorSystemStub {
+  runL3Validators(): Promise<ValidatorCheckItem[]>;
+  runAllValidators(): Promise<ValidatorCheckItem[]>;
+  runDriftDetection(): Promise<DriftItem[]>;
+}
+
+export class ValidatorSystemExecutionAdapter implements ValidatorExecutionPort {
+  private readonly stub: IValidatorSystemStub;
+
+  constructor(stub?: IValidatorSystemStub) {
+    this.stub = stub ?? ValidatorSystemExecutionAdapter.createRealImpl();
+  }
+
+  private static createRealImpl(): IValidatorSystemStub {
+    return {
+      async runL3Validators(): Promise<ValidatorCheckItem[]> {
+        const { createValidatorSystemModule } = await import('../../../validator-system/composition-root.js');
+        const mod = createValidatorSystemModule();
+        const results = await mod.runL3ValidatorsUseCase.execute({ targetPaths: [] });
+        return results.map((r) => ({
+          validatorId: r.validatorId,
+          passed: r.passed,
+          errors: r.errors.map((e) => ({ code: e.code, severity: e.severity, message: e.message })),
+        }));
+      },
+
+      async runAllValidators(): Promise<ValidatorCheckItem[]> {
+        const { createValidatorSystemModule } = await import('../../../validator-system/composition-root.js');
+        const mod = createValidatorSystemModule();
+        const report = await mod.runFullValidationUseCase.execute({ targetPaths: [], unitName: '', currentPhase: '' });
+        return report.results.map((r) => ({
+          validatorId: r.validatorId,
+          passed: r.passed,
+          errors: r.errors.map((e) => ({ code: e.code, severity: e.severity, message: e.message })),
+        }));
+      },
+
+      async runDriftDetection(): Promise<DriftItem[]> {
+        // validator-system does not implement drift detection
+        return [];
+      },
+    };
+  }
+
+  async runL3Validators(): Promise<ValidatorCheckItem[]> {
+    try {
+      return await this.stub.runL3Validators();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return [{ validatorId: 'L3-error', passed: false, errors: [{ code: 'VALIDATOR_SYSTEM_ERROR', severity: 'error', message }] }];
+    }
+  }
+
+  async runDriftDetection(): Promise<DriftItem[]> {
+    return this.stub.runDriftDetection();
+  }
+
+  async runAllValidators(): Promise<ValidatorCheckItem[]> {
+    try {
+      return await this.stub.runAllValidators();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return [{ validatorId: 'all-error', passed: false, errors: [{ code: 'VALIDATOR_SYSTEM_ERROR', severity: 'error', message }] }];
+    }
+  }
+}

package/scripts/harness/harness-api/presentation/dto/cli-output-options.ts

@@ -0,0 +1,7 @@
+// cli-output-options.ts — CLIOutputOptions DTO
+
+export interface CLIOutputOptions {
+  pretty?: boolean;
+  noColor?: boolean;
+  quiet?: boolean;
+}

package/scripts/harness/harness-api/presentation/formatters/harness-api-json-formatter.ts

@@ -0,0 +1,13 @@
+// harness-api-json-formatter.ts — HarnessApiJsonFormatter
+
+import type { HarnessApiResponseContract } from '../../application/dto/harness-api-response-contract.js';
+import type { CLIOutputOptions } from '../dto/cli-output-options.js';
+
+export class HarnessApiJsonFormatter {
+  static format<T>(response: HarnessApiResponseContract<T>, options: CLIOutputOptions = {}): string {
+    if (options.pretty) {
+      return JSON.stringify(response, null, 2);
+    }
+    return JSON.stringify(response);
+  }
+}

package/scripts/harness/harness-api/presentation/handlers/check-phase-handler.ts

@@ -0,0 +1,42 @@
+// check-phase-handler.ts — CheckPhaseHandler
+
+import type { DispatchCommandUseCase } from '../../application/usecases/dispatch-command-usecase.js';
+import { HarnessApiJsonFormatter } from '../formatters/harness-api-json-formatter.js';
+import type { CLIOutputOptions } from '../dto/cli-output-options.js';
+
+export class CheckPhaseHandler {
+  private readonly dispatchUseCase: Pick<DispatchCommandUseCase, 'execute'>;
+
+  constructor(dispatchUseCase: Pick<DispatchCommandUseCase, 'execute'>) {
+    this.dispatchUseCase = dispatchUseCase;
+  }
+
+  async handle(
+    args: Record<string, string>,
+    flags: Record<string, boolean | string>,
+    options: CLIOutputOptions = {}
+  ): Promise<void> {
+    const unitId = args.unit ?? '';
+    if (!unitId) {
+      const errorResponse = {
+        status: 'error' as const,
+        errors: [{ code: 'MISSING_ARGUMENT', severity: 'error', message: 'unit argument is required' }],
+        summary: 'Missing required argument: unit',
+        data: undefined,
+      };
+      process.stdout.write(HarnessApiJsonFormatter.format(errorResponse, options) + '\n');
+      process.exitCode = 2;
+      return;
+    }
+
+    const result = await this.dispatchUseCase.execute({
+      commandName: 'harness:check-phase',
+      args,
+      flags,
+    });
+
+    const json = HarnessApiJsonFormatter.format(result.response, options);
+    process.stdout.write(json + '\n');
+    process.exitCode = result.exitCode;
+  }
+}

package/scripts/harness/harness-api/presentation/handlers/check-ready-handler.ts

@@ -0,0 +1,29 @@
+// check-ready-handler.ts — CheckReadyHandler
+
+import type { DispatchCommandUseCase } from '../../application/usecases/dispatch-command-usecase.js';
+import { HarnessApiJsonFormatter } from '../formatters/harness-api-json-formatter.js';
+import type { CLIOutputOptions } from '../dto/cli-output-options.js';
+
+export class CheckReadyHandler {
+  private readonly dispatchUseCase: Pick<DispatchCommandUseCase, 'execute'>;
+
+  constructor(dispatchUseCase: Pick<DispatchCommandUseCase, 'execute'>) {
+    this.dispatchUseCase = dispatchUseCase;
+  }
+
+  async handle(
+    args: Record<string, string>,
+    flags: Record<string, boolean | string>,
+    options: CLIOutputOptions = {}
+  ): Promise<void> {
+    const result = await this.dispatchUseCase.execute({
+      commandName: 'harness:check-ready',
+      args,
+      flags,
+    });
+
+    const json = HarnessApiJsonFormatter.format(result.response, options);
+    process.stdout.write(json + '\n');
+    process.exitCode = result.exitCode;
+  }
+}