phasegate 0.163.0 → 0.165.0

package/scripts/harness/attestation/domain/value-objects/digest.ts

@@ -0,0 +1,51 @@
+// @unit attestation
+// @layer domain
+
+/**
+ * `sha256:<64 lowercase hex>` に適合しない digest を拒否する例外。
+ * errorCode: L1-050（横断決定事項 §3 / logical_design §2.4）
+ */
+export class InvalidDigestError extends Error {
+  readonly errorCode = "L1-050";
+
+  constructor(raw: string) {
+    super(`Invalid digest: "${raw}". Must match sha256:<64 lowercase hex chars> [L1-050]`);
+    this.name = "InvalidDigestError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * content-addressed self-digest を表す値オブジェクト。
+ * attestation Unit がローカルに所有する（domain_model §1 所有判断 — cross-unit coupling 回避）。
+ * INV-7: すべての Digest は `sha256:` prefix + 64桁 hex に適合する。
+ */
+export class Digest {
+  private static readonly PATTERN = /^sha256:[0-9a-f]{64}$/;
+
+  readonly value: string;
+
+  private constructor(value: string) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static create(raw: string): Digest {
+    if (!Digest.PATTERN.test(raw)) {
+      throw new InvalidDigestError(raw);
+    }
+    return new Digest(raw);
+  }
+
+  static fromSha256Hex(hex: string): Digest {
+    return Digest.create(`sha256:${hex}`);
+  }
+
+  equals(other: Digest): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}

package/scripts/harness/attestation/domain/value-objects/granularity-claim.ts

@@ -0,0 +1,89 @@
+// @unit attestation
+// @layer domain
+
+export type GranularityLevel = "file" | "ac";
+
+export interface GranularityClaimProps {
+  readonly validator: string;
+  readonly level: GranularityLevel;
+  readonly claim: string;
+  readonly knownLimitations: readonly string[];
+}
+
+/**
+ * validator set から機械導出される検査粒度の主張を表す値オブジェクト。
+ * L3-004 の file-level 制約（既知制約テキスト）を保持できる。
+ */
+export class GranularityClaim {
+  readonly validator: string;
+  readonly level: GranularityLevel;
+  readonly claim: string;
+  readonly knownLimitations: readonly string[];
+
+  private constructor(props: GranularityClaimProps) {
+    this.validator = props.validator;
+    this.level = props.level;
+    this.claim = props.claim;
+    this.knownLimitations = Object.freeze([...props.knownLimitations]);
+    Object.freeze(this);
+  }
+
+  static create(props: GranularityClaimProps): GranularityClaim {
+    if (typeof props.validator !== "string" || props.validator.length === 0) {
+      throw new Error("GranularityClaim: validator must not be empty");
+    }
+    if (props.level !== "file" && props.level !== "ac") {
+      throw new Error(`GranularityClaim: level must be "file" or "ac", got: ${String(props.level)}`);
+    }
+    if (typeof props.claim !== "string") {
+      throw new Error("GranularityClaim: claim must be a string");
+    }
+    if (!Array.isArray(props.knownLimitations)) {
+      throw new Error("GranularityClaim: knownLimitations must be an array");
+    }
+    return new GranularityClaim(props);
+  }
+
+  equals(other: GranularityClaim): boolean {
+    return (
+      this.validator === other.validator &&
+      this.level === other.level &&
+      this.claim === other.claim &&
+      this.knownLimitations.length === other.knownLimitations.length &&
+      this.knownLimitations.every((v, i) => v === other.knownLimitations[i])
+    );
+  }
+}
+
+/**
+ * validatorId → 検査粒度の静的定義。anti-laundering の中核。
+ * 生成（H16-01）と検証（H16-02 再導出）で同一の粒度主張を返すため domain 定数として固定する。
+ */
+export interface GranularityDefinition {
+  readonly validator: string;
+  readonly level: GranularityLevel;
+  readonly claim: string;
+  readonly knownLimitations: readonly string[];
+}
+
+export const L3_004_FILE_LEVEL_KNOWN_LIMITATION =
+  "L3-004 traceability is FILE-LEVEL, not per-AC — a green means each AC has >=1 referencing test FILE, " +
+  "not that each AC is individually asserted";
+
+/**
+ * traceability 検査（L3-004）の静的粒度定義。
+ * L3-004 が validator set に含まれる場合、level "file" と file-level known-limitation を必ず付与する。
+ */
+export const KNOWN_LIMITATIONS_REGISTRY: Readonly<Record<string, GranularityDefinition>> = Object.freeze({
+  "L3-004": Object.freeze({
+    validator: "L3-004",
+    level: "file",
+    claim:
+      "Traceability (L3-004) verifies that every acceptance criterion is referenced by at least one " +
+      "test file. This is a FILE-LEVEL guarantee.",
+    knownLimitations: Object.freeze([L3_004_FILE_LEVEL_KNOWN_LIMITATION]),
+  }),
+});
+
+/** traceability 検査に対応する validatorId。 */
+export const TRACEABILITY_VALIDATOR_ID = "L3-004";

package/scripts/harness/attestation/domain/value-objects/signature-block.ts

@@ -0,0 +1,87 @@
+// @unit attestation
+// @layer domain
+
+import { Digest } from "./digest.js";
+
+export type SignatureMode = "unsigned-poc" | "signed";
+
+/**
+ * 未対応 signature mode（`signed`）の生成/検証要求で送出される例外。
+ * errorCode: L1-052（logical_design §2.4）
+ */
+export class UnsupportedSignatureModeError extends Error {
+  readonly errorCode = "L1-052";
+
+  constructor(mode: string) {
+    super(`Unsupported signature mode: "${mode}" (not yet implemented) [L1-052]`);
+    this.name = "UnsupportedSignatureModeError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export interface SignatureBlockProps {
+  readonly mode: SignatureMode;
+  readonly attestationDigest: Digest;
+  readonly algorithm: string | null;
+  readonly keyId: string | null;
+  readonly value: string | null;
+}
+
+/**
+ * mode discriminator を持つ署名ブロック値オブジェクト。
+ * unsigned-poc は INTEGRITY のみを証明し、algorithm/keyId/value はすべて null（INV-6）。
+ */
+export class SignatureBlock {
+  readonly mode: SignatureMode;
+  readonly attestationDigest: Digest;
+  readonly algorithm: string | null;
+  readonly keyId: string | null;
+  readonly value: string | null;
+
+  private constructor(props: SignatureBlockProps) {
+    this.mode = props.mode;
+    this.attestationDigest = props.attestationDigest;
+    this.algorithm = props.algorithm;
+    this.keyId = props.keyId;
+    this.value = props.value;
+    Object.freeze(this);
+  }
+
+  static create(props: SignatureBlockProps): SignatureBlock {
+    if (props.mode === "signed") {
+      throw new UnsupportedSignatureModeError("signed");
+    }
+    if (props.mode !== "unsigned-poc") {
+      throw new UnsupportedSignatureModeError(String(props.mode));
+    }
+    // INV-6: unsigned-poc のとき algorithm/keyId/value はすべて null
+    if (props.algorithm !== null || props.keyId !== null || props.value !== null) {
+      throw new UnsupportedSignatureModeError("unsigned-poc must have null algorithm/keyId/value");
+    }
+    if (!(props.attestationDigest instanceof Digest)) {
+      throw new Error("SignatureBlock: attestationDigest must be a Digest");
+    }
+    return new SignatureBlock(props);
+  }
+
+  /** unsigned-poc モードのブロックを構築する（algorithm/keyId/value を null で固定）。 */
+  static unsignedPoc(digest: Digest): SignatureBlock {
+    return new SignatureBlock({
+      mode: "unsigned-poc",
+      attestationDigest: digest,
+      algorithm: null,
+      keyId: null,
+      value: null,
+    });
+  }
+
+  equals(other: SignatureBlock): boolean {
+    return (
+      this.mode === other.mode &&
+      this.attestationDigest.equals(other.attestationDigest) &&
+      this.algorithm === other.algorithm &&
+      this.keyId === other.keyId &&
+      this.value === other.value
+    );
+  }
+}

package/scripts/harness/attestation/domain/value-objects/validator-outcome.ts

@@ -0,0 +1,44 @@
+// @unit attestation
+// @layer domain
+
+export interface ValidatorOutcomeProps {
+  readonly validatorId: string;
+  readonly passed: boolean;
+  readonly skipped?: boolean;
+}
+
+/**
+ * ci-check の1バリデータ結果を写す値オブジェクト。
+ * `{ validatorId, passed, skipped }`。skipped 未指定は false に正規化する。
+ */
+export class ValidatorOutcome {
+  readonly validatorId: string;
+  readonly passed: boolean;
+  readonly skipped: boolean;
+
+  private constructor(validatorId: string, passed: boolean, skipped: boolean) {
+    this.validatorId = validatorId;
+    this.passed = passed;
+    this.skipped = skipped;
+    Object.freeze(this);
+  }
+
+  static create(props: ValidatorOutcomeProps): ValidatorOutcome {
+    if (typeof props.validatorId !== "string" || props.validatorId.length === 0) {
+      throw new Error("ValidatorOutcome: validatorId must not be empty");
+    }
+    if (typeof props.passed !== "boolean") {
+      throw new Error("ValidatorOutcome: passed must be a boolean");
+    }
+    return new ValidatorOutcome(props.validatorId, props.passed, props.skipped === true);
+  }
+
+  /** allPassed 規則: passed または skipped ならグリーン。 */
+  isGreen(): boolean {
+    return this.passed || this.skipped;
+  }
+
+  equals(other: ValidatorOutcome): boolean {
+    return this.validatorId === other.validatorId && this.passed === other.passed && this.skipped === other.skipped;
+  }
+}

package/scripts/harness/attestation/index.ts

@@ -0,0 +1,18 @@
+// @layer infrastructure
+// @unit attestation
+// index.ts — attestation Unit の公開バレルエクスポート
+
+// Public DTO types
+export type { AttestationDocument } from "./application/dto/attestation-document.js";
+export type { VerifyAttestationOutput } from "./application/dto/verify-attestation-output.js";
+export type { AttestationModule, AttestationModuleOptions } from "./composition-root.js";
+// Composition Root
+export { createAttestationModule } from "./composition-root.js";
+export type { AttestHandlerArgs, AttestHandlerResult } from "./presentation/handlers/attest-handler.js";
+// Presentation Handlers
+export { AttestHandler } from "./presentation/handlers/attest-handler.js";
+export type {
+  VerifyAttestationHandlerArgs,
+  VerifyAttestationHandlerResult,
+} from "./presentation/handlers/verify-attestation-handler.js";
+export { VerifyAttestationHandler } from "./presentation/handlers/verify-attestation-handler.js";

package/scripts/harness/attestation/infrastructure/adapters/ci-check-gate-result-adapter.ts

@@ -0,0 +1,164 @@
+// @unit attestation
+// @layer infrastructure
+
+import { spawn } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { GateResultSourcePort, GateValidatorResult } from "../../application/ports/gate-result-source-port.js";
+
+interface CiCheckSubprocessResult {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/**
+ * GateResultSourcePort の subprocess 実装（black-box observation）。
+ * `npx tsx <main.ts> phasegate:ci-check --json` を子プロセス実行し、
+ * stdout JSON の `data` から `{ allPassed, validatorResults[] }` を抽出する。
+ *
+ * ci-check の内部（harness-api）を import しない。gate fail でも ci-check は
+ * parseable JSON（allPassed:false）を出力するため、非0 exit は即エラーとせず
+ * stdout の JSON を解析する。JSON が解析不能／shape 不正のときのみ本物のクラッシュとして throw。
+ */
+export class CiCheckGateResultAdapter implements GateResultSourcePort {
+  /** ci-check subprocess の最大待機時間（ms）。 */
+  private readonly timeoutMs: number;
+  /** テスト用のオーバーライド。既定は本 adapter が解決する main.ts。 */
+  private readonly mainTsPath: string;
+
+  constructor(options?: { readonly timeoutMs?: number; readonly mainTsPath?: string }) {
+    this.timeoutMs = options?.timeoutMs ?? 300_000;
+    this.mainTsPath = options?.mainTsPath ?? resolveMainTsPath();
+  }
+
+  async fetchGateResult(): Promise<{
+    readonly allPassed: boolean;
+    readonly validatorResults: readonly GateValidatorResult[];
+  }> {
+    const result = await this.runCiCheck();
+    const parsed = this.parseResponse(result);
+    return parsed;
+  }
+
+  private parseResponse(result: CiCheckSubprocessResult): {
+    allPassed: boolean;
+    validatorResults: GateValidatorResult[];
+  } {
+    const json = extractJsonObject(result.stdout);
+    if (json === null) {
+      throw new Error(
+        `ci-check produced no parseable JSON (exit ${result.exitCode}). stderr: ${result.stderr.slice(0, 500)}`,
+      );
+    }
+    const data = (json as Record<string, unknown>).data;
+    if (typeof data !== "object" || data === null) {
+      throw new Error(`ci-check JSON has no "data" field (exit ${result.exitCode})`);
+    }
+    const dataRecord = data as Record<string, unknown>;
+    const rawValidators = dataRecord.validatorResults;
+    if (!Array.isArray(rawValidators)) {
+      throw new Error('ci-check JSON "data.validatorResults" is not an array');
+    }
+    if (typeof dataRecord.allPassed !== "boolean") {
+      throw new Error('ci-check JSON "data.allPassed" is not a boolean');
+    }
+    const validatorResults: GateValidatorResult[] = rawValidators.map((raw, i) => {
+      if (typeof raw !== "object" || raw === null) {
+        throw new Error(`ci-check validatorResults[${i}] is not an object`);
+      }
+      const item = raw as Record<string, unknown>;
+      if (typeof item.validatorId !== "string") {
+        throw new Error(`ci-check validatorResults[${i}].validatorId is not a string`);
+      }
+      if (typeof item.passed !== "boolean") {
+        throw new Error(`ci-check validatorResults[${i}].passed is not a boolean`);
+      }
+      return {
+        validatorId: item.validatorId,
+        passed: item.passed,
+        skipped: typeof item.skipped === "boolean" ? item.skipped : false,
+      };
+    });
+    return { allPassed: dataRecord.allPassed, validatorResults };
+  }
+
+  private runCiCheck(): Promise<CiCheckSubprocessResult> {
+    return new Promise((resolvePromise, reject) => {
+      const child = spawn("npx", ["tsx", this.mainTsPath, "phasegate:ci-check", "--json"], {
+        stdio: ["pipe", "pipe", "pipe"],
+        shell: false,
+        env: process.env,
+      });
+
+      let stdout = "";
+      let stderr = "";
+      let timedOut = false;
+
+      const timer = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+        reject(new Error(`ci-check subprocess timed out after ${this.timeoutMs}ms`));
+      }, this.timeoutMs);
+
+      child.stdout?.on("data", (chunk: Buffer) => {
+        stdout += chunk.toString();
+      });
+      child.stderr?.on("data", (chunk: Buffer) => {
+        stderr += chunk.toString();
+      });
+      child.on("error", (error) => {
+        clearTimeout(timer);
+        if (!timedOut) reject(error);
+      });
+      child.on("close", (code) => {
+        clearTimeout(timer);
+        if (timedOut) return;
+        resolvePromise({ exitCode: code ?? 0, stdout, stderr });
+      });
+      child.stdin?.end();
+    });
+  }
+}
+
+function resolveMainTsPath(): string {
+  // infrastructure/adapters/ から 3 階層上が scripts/harness/。
+  return resolve(dirname(fileURLToPath(import.meta.url)), "../../../main.ts");
+}
+
+/**
+ * stdout から最初の JSON オブジェクトを抽出する。ci-check は他ログを stdout に混ぜ得るため、
+ * 各行を試し、失敗時は最初の `{` から最後の `}` までを試す。
+ */
+function extractJsonObject(stdout: string): unknown {
+  const trimmed = stdout.trim();
+  if (trimmed.length === 0) return null;
+
+  const direct = tryParse(trimmed);
+  if (direct !== undefined) return direct;
+
+  const lines = trimmed.split("\n");
+  for (const line of lines) {
+    const candidate = line.trim();
+    if (candidate.startsWith("{") && candidate.endsWith("}")) {
+      const parsed = tryParse(candidate);
+      if (parsed !== undefined) return parsed;
+    }
+  }
+
+  const first = trimmed.indexOf("{");
+  const last = trimmed.lastIndexOf("}");
+  if (first !== -1 && last > first) {
+    const parsed = tryParse(trimmed.slice(first, last + 1));
+    if (parsed !== undefined) return parsed;
+  }
+  return null;
+}
+
+function tryParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}

package/scripts/harness/attestation/infrastructure/adapters/file-system-attestation-repository-adapter.ts

@@ -0,0 +1,32 @@
+// @unit attestation
+// @layer infrastructure
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import type { AttestationDocument } from "../../application/dto/attestation-document.js";
+import type { AttestationRepositoryPort } from "../../application/ports/attestation-repository-port.js";
+
+/**
+ * AttestationRepositoryPort の node:fs 実装。
+ * write は親ディレクトリを作成し、2スペース整形 JSON + 改行で書き出す。
+ * read は readFile + JSON.parse。不在/parse 失敗はそのまま throw し usecase が exitCode 2 へ変換する。
+ */
+export class FileSystemAttestationRepositoryAdapter implements AttestationRepositoryPort {
+  constructor(private readonly baseDir: string) {}
+
+  async write(path: string, doc: AttestationDocument): Promise<void> {
+    const absPath = this.resolvePath(path);
+    await mkdir(dirname(absPath), { recursive: true });
+    await writeFile(absPath, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
+  }
+
+  async read(path: string): Promise<unknown> {
+    const absPath = this.resolvePath(path);
+    const raw = await readFile(absPath, "utf8");
+    return JSON.parse(raw);
+  }
+
+  private resolvePath(path: string): string {
+    return isAbsolute(path) ? path : resolve(this.baseDir, path);
+  }
+}

package/scripts/harness/attestation/infrastructure/adapters/file-system-source-digester-adapter.ts

@@ -0,0 +1,27 @@
+// @unit attestation
+// @layer infrastructure
+
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import type { SourceDigesterPort } from "../../application/ports/source-digester-port.js";
+import { Digest } from "../../domain/value-objects/digest.js";
+
+/**
+ * SourceDigesterPort の node:fs 実装。
+ * source パスの「現在の」内容を読み、sha256 Digest を返す。
+ * ci-governance の file-system-sha1-hasher-adapter をミラーするが、アルゴリズムは sha256。
+ *
+ * 不在ファイルは readFile が throw する。verify 時は usecase が本 throw を捕捉し
+ * inputHashes チェックの失敗（mismatch）として扱う（クラッシュではない）。
+ */
+export class FileSystemSourceDigesterAdapter implements SourceDigesterPort {
+  constructor(private readonly baseDir: string) {}
+
+  async digestFile(path: string): Promise<Digest> {
+    const absPath = isAbsolute(path) ? path : resolve(this.baseDir, path);
+    const content = await readFile(absPath);
+    const hex = createHash("sha256").update(content).digest("hex");
+    return Digest.fromSha256Hex(hex);
+  }
+}

package/scripts/harness/attestation/infrastructure/adapters/node-crypto-content-hasher-adapter.ts

@@ -0,0 +1,18 @@
+// @unit attestation
+// @layer infrastructure
+
+import { createHash } from "node:crypto";
+import type { ContentHasherPort } from "../../domain/ports/content-hasher-port.js";
+import { Digest } from "../../domain/value-objects/digest.js";
+
+/**
+ * ContentHasherPort の node:crypto 実装。
+ * canonical payload / source content の sha256 を `sha256:<64hex>` Digest として返す。
+ * installation の node-crypto-hash-adapter をミラーし、アルゴリズムは sha256 に固定する。
+ */
+export class NodeCryptoContentHasherAdapter implements ContentHasherPort {
+  sha256(content: string): Digest {
+    const hex = createHash("sha256").update(content, "utf8").digest("hex");
+    return Digest.fromSha256Hex(hex);
+  }
+}

package/scripts/harness/attestation/presentation/handlers/attest-handler.ts

@@ -0,0 +1,71 @@
+// @unit attestation
+// @layer presentation
+
+import type { ProduceAttestationInput } from "../../application/dto/produce-attestation-input.js";
+import type { ProduceAttestationUseCase } from "../../application/usecases/produce-attestation-usecase.js";
+import type { SignatureMode } from "../../domain/value-objects/signature-block.js";
+
+export interface AttestHandlerArgs {
+  /** record 出力先。既定は presentation 呼び出し側で `.harness/attestation.json`。 */
+  readonly out?: string;
+  readonly requirePass?: boolean;
+  readonly emitJson?: boolean;
+  /** 署名モード（既定 unsigned-poc）。`signed` は not-yet-implemented。 */
+  readonly mode?: string;
+}
+
+export interface AttestHandlerResult {
+  readonly output: string;
+  readonly exitCode: 0 | 1 | 2;
+}
+
+const DEFAULT_OUT = ".harness/attestation.json";
+
+/**
+ * H16-01: phasegate:attest の CLI ハンドラ。
+ * flags を ProduceAttestationInput に解釈し UseCase を呼び、output + exitCode に整形する。
+ * 終了コード: 0 成功 / 1 --require-pass 下で gate fail / 2 usage error（未知 mode・signed）。
+ */
+export class AttestHandler {
+  constructor(private readonly useCase: ProduceAttestationUseCase) {}
+
+  async handle(args: AttestHandlerArgs): Promise<AttestHandlerResult> {
+    const rawMode = args.mode ?? "unsigned-poc";
+    if (rawMode !== "unsigned-poc" && rawMode !== "signed") {
+      return { output: `Error: unknown --mode "${rawMode}" (expected unsigned-poc | signed)`, exitCode: 2 };
+    }
+    const mode: SignatureMode = rawMode;
+
+    const input: ProduceAttestationInput = {
+      out: args.out && args.out.length > 0 ? args.out : DEFAULT_OUT,
+      requirePass: args.requirePass === true,
+      emitJson: args.emitJson === true,
+      mode,
+    };
+
+    const result = await this.useCase.execute(input);
+
+    if (result.exitCode === 2) {
+      // 唯一の usecase 由来 2 は mode === "signed"。
+      return { output: 'Error: --mode "signed" is not yet implemented (only unsigned-poc is supported)', exitCode: 2 };
+    }
+
+    if (result.exitCode === 1) {
+      return {
+        output: 'Gate result is not "pass"; --require-pass suppressed attestation output.',
+        exitCode: 1,
+      };
+    }
+
+    // exitCode 0: 生成成功
+    if (result.document === null) {
+      // 型上は起こり得ないが安全側で扱う。
+      return { output: "Error: attestation produced no document.", exitCode: 2 };
+    }
+
+    if (input.emitJson) {
+      return { output: JSON.stringify(result.document, null, 2), exitCode: 0 };
+    }
+    return { output: `Attestation written to ${input.out}`, exitCode: 0 };
+  }
+}

package/scripts/harness/attestation/presentation/handlers/verify-attestation-handler.ts

@@ -0,0 +1,74 @@
+// @unit attestation
+// @layer presentation
+
+import type { VerifyAttestationInput } from "../../application/dto/verify-attestation-input.js";
+import type { VerifyAttestationOutput } from "../../application/dto/verify-attestation-output.js";
+import type { VerifyAttestationUseCase } from "../../application/usecases/verify-attestation-usecase.js";
+
+export interface VerifyAttestationHandlerArgs {
+  /** 検証対象 attestation ファイルパス（位置引数）。 */
+  readonly file?: string;
+  readonly emitJson?: boolean;
+}
+
+export interface VerifyAttestationHandlerResult {
+  readonly output: string;
+  readonly exitCode: 0 | 1 | 2;
+}
+
+/**
+ * H16-02: phasegate:verify-attestation のハンドラ。
+ * 位置引数 <file> + --json を解釈し UseCase を呼び、機械的 5 チェックを整形する。
+ * 終了コード: 0 全合格 / 1 mismatch / 2 不在・malformed・非対応 mode。
+ */
+export class VerifyAttestationHandler {
+  constructor(private readonly useCase: VerifyAttestationUseCase) {}
+
+  async handle(args: VerifyAttestationHandlerArgs): Promise<VerifyAttestationHandlerResult> {
+    if (!args.file || args.file.trim().length === 0) {
+      return { output: "Error: <file> is required. Usage: phasegate:verify-attestation <file> [--json]", exitCode: 2 };
+    }
+
+    const input: VerifyAttestationInput = {
+      filePath: args.file,
+      emitJson: args.emitJson === true,
+    };
+
+    const result = await this.useCase.execute(input);
+
+    if (input.emitJson) {
+      return { output: JSON.stringify(result.output, null, 2), exitCode: result.exitCode };
+    }
+    return { output: renderHuman(result.output, result.exitCode), exitCode: result.exitCode };
+  }
+}
+
+function mark(ok: boolean): string {
+  return ok ? "PASS" : "FAIL";
+}
+
+function renderHuman(output: VerifyAttestationOutput, exitCode: 0 | 1 | 2): string {
+  const c = output.checks;
+  const lines: string[] = [];
+  lines.push(`schema           : ${mark(c.schema)}`);
+  lines.push(`mode             : ${mark(c.mode)}`);
+  lines.push(`attestationDigest: ${mark(c.attestationDigest)}`);
+  lines.push(`inputHashes      : ${mark(c.inputHashes)}`);
+  lines.push(`granularity      : ${mark(c.granularity)}`);
+  if (output.mismatches.length > 0) {
+    lines.push("");
+    lines.push("Mismatches:");
+    for (const m of output.mismatches) {
+      lines.push(`  - ${m}`);
+    }
+  }
+  lines.push("");
+  if (exitCode === 0) {
+    lines.push("Result: OK (all checks passed)");
+  } else if (exitCode === 1) {
+    lines.push("Result: MISMATCH (attestation integrity check failed)");
+  } else {
+    lines.push("Result: ERROR (missing, malformed, or unsupported attestation)");
+  }
+  return lines.join("\n");
+}