phasegate 0.191.0 → 0.212.0

package/scripts/harness/ci-governance/composition-root.ts

@@ -5,53 +5,54 @@
  * Composition Root - 依存性の組み立て
  */
 
-import { TemplateGenerator } from './domain/services/template-generator.js';
-import { RepetitionDetector } from './domain/services/repetition-detector.js';
-import { PointerValidator } from './domain/services/pointer-validator.js';
-import { LessonAggregator } from './domain/services/lesson-aggregator.js';
-import { ClaudeMdComposer } from './domain/services/claude-md-composer.js';
-
-import { GenerateCiTemplateUseCase } from './application/usecases/generate-ci-template-usecase.js';
-import { RenderCiTemplateUseCase } from './application/usecases/render-ci-template-usecase.js';
-import { RecordErrorOccurrenceUseCase } from './application/usecases/record-error-occurrence-usecase.js';
-import { CheckEscalationUseCase } from './application/usecases/check-escalation-usecase.js';
-import { ResetRepetitionUseCase } from './application/usecases/reset-repetition-usecase.js';
-import { MigrateAgentsMdUseCase } from './application/usecases/migrate-agents-md-usecase.js';
-import { RefreshAgentContextUseCase } from './application/usecases/refresh-agent-context-usecase.js';
-import { RefreshClaudeMdUseCase } from './application/usecases/refresh-claude-md-usecase.js';
-import { CheckAgentContextUseCase } from './application/usecases/check-agent-context-usecase.js';
-import { AggregateLessonsUseCase } from './application/usecases/aggregate-lessons-usecase.js';
-import { ValidatePointersUseCase } from './application/usecases/validate-pointers-usecase.js';
-
-import { ValidatorIdRegistryAdapter } from './infrastructure/adapters/validator-id-registry-adapter.js';
-import { PresetConfigAdapter } from './infrastructure/adapters/preset-config-adapter.js';
-import { ErrorRepetitionJsonRepository } from './infrastructure/adapters/error-repetition-json-repository.js';
-import { EscalationLogExecutorAdapter } from './infrastructure/adapters/escalation-log-executor-adapter.js';
-import { YamlTemplateRendererAdapter } from './infrastructure/adapters/yaml-template-renderer-adapter.js';
-import { FileSystemExistenceAdapter } from './infrastructure/adapters/file-system-existence-adapter.js';
-import { AgentsMdFileAdapter } from './infrastructure/adapters/agents-md-file-adapter.js';
-import { AgentContextFileAdapter } from './infrastructure/adapters/agent-context-file-adapter.js';
-import { LessonArtifactFileReaderAdapter } from './infrastructure/adapters/lesson-artifact-file-reader-adapter.js';
-import { HarnessApiCommandExistenceAdapter } from './infrastructure/adapters/harness-api-command-existence-adapter.js';
-import { AdrFoundationExistenceAdapter } from './infrastructure/adapters/adr-foundation-existence-adapter.js';
-
-import { GenerateCiTemplateHandler } from './presentation/handlers/generate-ci-template-handler.js';
-import { MigrateAgentsMdHandler } from './presentation/handlers/migrate-agents-md-handler.js';
-import { RefreshAgentContextHandler } from './presentation/handlers/refresh-agent-context-handler.js';
-import { RefreshClaudeMdHandler } from './presentation/handlers/refresh-claude-md-handler.js';
-import { CheckAgentContextHandler } from './presentation/handlers/check-agent-context-handler.js';
-import { CheckRepetitionHandler } from './presentation/handlers/check-repetition-handler.js';
-import { CreateBaselineHandler } from './presentation/handlers/create-baseline-handler.js';
-
-import { CreateBaselineUseCase } from './application/usecases/create-baseline-usecase.js';
-import { GlobFileScannerAdapter } from './infrastructure/adapters/glob-file-scanner-adapter.js';
-import { FileSystemSha1HasherAdapter } from './infrastructure/adapters/file-system-sha1-hasher-adapter.js';
-import { BaselineJsonRepositoryAdapter } from './infrastructure/adapters/baseline-json-repository-adapter.js';
-
-import { ScaffoldDesignUseCase } from './application/usecases/scaffold-design-usecase.js';
-import { FileSystemTemplateRepositoryAdapter } from './infrastructure/adapters/file-system-template-repository-adapter.js';
-import { FileSystemDesignDocWriterAdapter } from './infrastructure/adapters/file-system-design-doc-writer-adapter.js';
-import { ScaffoldDesignHandler } from './presentation/handlers/scaffold-design-handler.js';
+import { AggregateLessonsUseCase } from "./application/usecases/aggregate-lessons-usecase.js";
+import { CheckAgentContextUseCase } from "./application/usecases/check-agent-context-usecase.js";
+import { CheckEscalationUseCase } from "./application/usecases/check-escalation-usecase.js";
+import { CreateBaselineUseCase } from "./application/usecases/create-baseline-usecase.js";
+import { GenerateCiTemplateUseCase } from "./application/usecases/generate-ci-template-usecase.js";
+import { MigrateAgentsMdUseCase } from "./application/usecases/migrate-agents-md-usecase.js";
+import { PinIntegrityUseCase } from "./application/usecases/pin-integrity-usecase.js";
+import { RecordErrorOccurrenceUseCase } from "./application/usecases/record-error-occurrence-usecase.js";
+import { RefreshAgentContextUseCase } from "./application/usecases/refresh-agent-context-usecase.js";
+import { RefreshClaudeMdUseCase } from "./application/usecases/refresh-claude-md-usecase.js";
+import { RenderCiTemplateUseCase } from "./application/usecases/render-ci-template-usecase.js";
+import { ResetRepetitionUseCase } from "./application/usecases/reset-repetition-usecase.js";
+import { ScaffoldDesignUseCase } from "./application/usecases/scaffold-design-usecase.js";
+import { ValidatePointersUseCase } from "./application/usecases/validate-pointers-usecase.js";
+import { VerifyIntegrityUseCase } from "./application/usecases/verify-integrity-usecase.js";
+import { ClaudeMdComposer } from "./domain/services/claude-md-composer.js";
+import { IntegrityChecker } from "./domain/services/integrity-checker.js";
+import { LessonAggregator } from "./domain/services/lesson-aggregator.js";
+import { PointerValidator } from "./domain/services/pointer-validator.js";
+import { RepetitionDetector } from "./domain/services/repetition-detector.js";
+import { TemplateGenerator } from "./domain/services/template-generator.js";
+import { AdrFoundationExistenceAdapter } from "./infrastructure/adapters/adr-foundation-existence-adapter.js";
+import { AgentContextFileAdapter } from "./infrastructure/adapters/agent-context-file-adapter.js";
+import { AgentsMdFileAdapter } from "./infrastructure/adapters/agents-md-file-adapter.js";
+import { BaselineJsonRepositoryAdapter } from "./infrastructure/adapters/baseline-json-repository-adapter.js";
+import { ErrorRepetitionJsonRepository } from "./infrastructure/adapters/error-repetition-json-repository.js";
+import { EscalationLogExecutorAdapter } from "./infrastructure/adapters/escalation-log-executor-adapter.js";
+import { FileSystemDesignDocWriterAdapter } from "./infrastructure/adapters/file-system-design-doc-writer-adapter.js";
+import { FileSystemExistenceAdapter } from "./infrastructure/adapters/file-system-existence-adapter.js";
+import { FileSystemSha1HasherAdapter } from "./infrastructure/adapters/file-system-sha1-hasher-adapter.js";
+import { FileSystemSha256HasherAdapter } from "./infrastructure/adapters/file-system-sha256-hasher-adapter.js";
+import { FileSystemTemplateRepositoryAdapter } from "./infrastructure/adapters/file-system-template-repository-adapter.js";
+import { GlobFileScannerAdapter } from "./infrastructure/adapters/glob-file-scanner-adapter.js";
+import { HarnessApiCommandExistenceAdapter } from "./infrastructure/adapters/harness-api-command-existence-adapter.js";
+import { IntegrityManifestJsonRepositoryAdapter } from "./infrastructure/adapters/integrity-manifest-json-repository-adapter.js";
+import { LessonArtifactFileReaderAdapter } from "./infrastructure/adapters/lesson-artifact-file-reader-adapter.js";
+import { PresetConfigAdapter } from "./infrastructure/adapters/preset-config-adapter.js";
+import { ValidatorIdRegistryAdapter } from "./infrastructure/adapters/validator-id-registry-adapter.js";
+import { YamlTemplateRendererAdapter } from "./infrastructure/adapters/yaml-template-renderer-adapter.js";
+import { CheckAgentContextHandler } from "./presentation/handlers/check-agent-context-handler.js";
+import { CheckRepetitionHandler } from "./presentation/handlers/check-repetition-handler.js";
+import { CreateBaselineHandler } from "./presentation/handlers/create-baseline-handler.js";
+import { GenerateCiTemplateHandler } from "./presentation/handlers/generate-ci-template-handler.js";
+import { IntegrityHandler } from "./presentation/handlers/integrity-handler.js";
+import { MigrateAgentsMdHandler } from "./presentation/handlers/migrate-agents-md-handler.js";
+import { RefreshAgentContextHandler } from "./presentation/handlers/refresh-agent-context-handler.js";
+import { RefreshClaudeMdHandler } from "./presentation/handlers/refresh-claude-md-handler.js";
+import { ScaffoldDesignHandler } from "./presentation/handlers/scaffold-design-handler.js";
 
 export interface CiGovernanceCompositionRoot {
   generateCiTemplateHandler: GenerateCiTemplateHandler;
@@ -70,12 +71,10 @@ export interface CiGovernanceCompositionRoot {
   validatePointersUseCase: ValidatePointersUseCase;
   createBaselineUseCase: CreateBaselineUseCase;
   scaffoldDesignUseCase: ScaffoldDesignUseCase;
+  integrityHandler: IntegrityHandler;
 }
 
-export function buildCiGovernance(
-  baseDir: string,
-  harnessRoot: string = baseDir,
-): CiGovernanceCompositionRoot {
+export function buildCiGovernance(baseDir: string, harnessRoot: string = baseDir): CiGovernanceCompositionRoot {
   // Infrastructure adapters
   const validatorIdRegistryAdapter = new ValidatorIdRegistryAdapter();
   const presetConfigAdapter = new PresetConfigAdapter();
@@ -118,25 +117,15 @@ export function buildCiGovernance(
   const fileScanner = new GlobFileScannerAdapter(baseDir);
   const fileHasher = new FileSystemSha1HasherAdapter(baseDir);
   const baselineRepository = new BaselineJsonRepositoryAdapter(baseDir);
-  const createBaselineUseCase = new CreateBaselineUseCase(
-    fileScanner,
-    fileHasher,
-    baselineRepository,
-  );
+  const createBaselineUseCase = new CreateBaselineUseCase(fileScanner, fileHasher, baselineRepository);
 
   // Scaffold design adapters & use case (ISSUE-007 Wave 4)
   const templateRepository = new FileSystemTemplateRepositoryAdapter(harnessRoot);
   const designDocWriter = new FileSystemDesignDocWriterAdapter(baseDir);
-  const scaffoldDesignUseCase = new ScaffoldDesignUseCase(
-    templateRepository,
-    designDocWriter,
-  );
+  const scaffoldDesignUseCase = new ScaffoldDesignUseCase(templateRepository, designDocWriter);
 
   // Handlers
-  const generateCiTemplateHandler = new GenerateCiTemplateHandler(
-    generateCiTemplateUseCase,
-    renderCiTemplateUseCase,
-  );
+  const generateCiTemplateHandler = new GenerateCiTemplateHandler(generateCiTemplateUseCase, renderCiTemplateUseCase);
   const migrateAgentsMdHandler = new MigrateAgentsMdHandler(migrateAgentsMdUseCase);
   const refreshAgentContextHandler = new RefreshAgentContextHandler(refreshAgentContextUseCase);
   const refreshClaudeMdHandler = new RefreshClaudeMdHandler(refreshClaudeMdUseCase);
@@ -145,6 +134,19 @@ export function buildCiGovernance(
   const createBaselineHandler = new CreateBaselineHandler(createBaselineUseCase);
   const scaffoldDesignHandler = new ScaffoldDesignHandler(scaffoldDesignUseCase);
 
+  // Integrity pin adapters & handler (WI-254 / ADR-030 §Decision.3.①)
+  const integrityChecker = new IntegrityChecker();
+  const sha256Hasher = new FileSystemSha256HasherAdapter(baseDir);
+  const integrityManifestRepository = new IntegrityManifestJsonRepositoryAdapter(baseDir);
+  const pinIntegrityUseCase = new PinIntegrityUseCase(fileScanner, sha256Hasher, integrityManifestRepository);
+  const verifyIntegrityUseCase = new VerifyIntegrityUseCase(
+    fileScanner,
+    sha256Hasher,
+    integrityManifestRepository,
+    integrityChecker,
+  );
+  const integrityHandler = new IntegrityHandler(pinIntegrityUseCase, verifyIntegrityUseCase);
+
   return {
     generateCiTemplateHandler,
     migrateAgentsMdHandler,
@@ -161,5 +163,6 @@ export function buildCiGovernance(
     validatePointersUseCase,
     createBaselineUseCase,
     scaffoldDesignUseCase,
+    integrityHandler,
   };
 }

package/scripts/harness/ci-governance/domain/ports/integrity-manifest-repository-port.ts

@@ -0,0 +1,14 @@
+// @unit ci-governance
+// @layer domain
+
+import type { IntegrityManifest } from "../value-objects/integrity-manifest.js";
+
+/**
+ * phasegate.integrity.json の読み書きポート。
+ */
+export interface IntegrityManifestRepositoryPort {
+  getPath(): string;
+  exists(): Promise<boolean>;
+  load(): Promise<IntegrityManifest | null>;
+  save(manifest: IntegrityManifest): Promise<string>;
+}

package/scripts/harness/ci-governance/domain/ports/sha256-hasher-port.ts

@@ -0,0 +1,10 @@
+// @unit ci-governance
+// @layer domain
+
+/**
+ * ファイルの SHA-256 digest（64 桁小文字 hex）を返すポート。
+ * 既存の sha1 用 FileHasherPort とは別ポート（アルゴリズムが異なるため混同回避）。
+ */
+export interface Sha256HasherPort {
+  hashFile(relativePath: string): Promise<string>;
+}

package/scripts/harness/ci-governance/domain/services/integrity-checker.ts

@@ -0,0 +1,42 @@
+// @unit ci-governance
+// @layer domain
+
+import type { IntegrityDrift } from "../value-objects/integrity-drift.js";
+import type { IntegrityManifest } from "../value-objects/integrity-manifest.js";
+
+/** manifest 欠落時に返す drift の path（manifest ファイルの相対パス） */
+export const INTEGRITY_MANIFEST_PATH = "phasegate.integrity.json";
+
+/**
+ * pin された manifest と、現在の再計算結果 (actual) を突き合わせて drift を列挙する
+ * 純ドメインサービス（状態なし・I/O なし）。ADR-030 §Decision.3.①。
+ */
+export class IntegrityChecker {
+  computeDrifts(manifest: IntegrityManifest | null, actual: ReadonlyMap<string, string>): IntegrityDrift[] {
+    if (manifest === null) {
+      return [{ path: INTEGRITY_MANIFEST_PATH, kind: "manifest-absent" }];
+    }
+
+    const drifts: IntegrityDrift[] = [];
+
+    // manifest の各 path: actual に無ければ missing、不一致なら mismatch
+    for (const [path, expected] of manifest.sortedEntries()) {
+      const actualDigest = actual.get(path);
+      if (actualDigest === undefined) {
+        drifts.push({ path, kind: "missing" });
+      } else if (actualDigest !== expected) {
+        drifts.push({ path, kind: "mismatch" });
+      }
+    }
+
+    // actual の各 path: manifest に無ければ added
+    for (const path of actual.keys()) {
+      if (manifest.digestOf(path) === undefined) {
+        drifts.push({ path, kind: "added" });
+      }
+    }
+
+    // path 昇順で決定的に返す
+    return drifts.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  }
+}

package/scripts/harness/ci-governance/domain/value-objects/integrity-drift.ts

@@ -0,0 +1,16 @@
+// @unit ci-governance
+// @layer domain
+
+/**
+ * verify で検出した整合性差分の種別。
+ * - mismatch: digest 不一致
+ * - added: 実在するが manifest に無い
+ * - missing: manifest にあるが実在しない
+ * - manifest-absent: manifest ファイル自体が欠落
+ */
+export type IntegrityDriftKind = "mismatch" | "added" | "missing" | "manifest-absent";
+
+export interface IntegrityDrift {
+  readonly path: string;
+  readonly kind: IntegrityDriftKind;
+}

package/scripts/harness/ci-governance/domain/value-objects/integrity-manifest.ts

@@ -0,0 +1,49 @@
+// @unit ci-governance
+// @layer domain
+
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
+
+export interface IntegrityManifestProps {
+  readonly files: ReadonlyMap<string, string>;
+}
+
+/**
+ * 指示搭載ファイル群の SHA-256 pin を表す不変 VO（pin 集約ルート）。
+ * version は 1 固定、algorithm は 'sha256' 固定（ADR-030 §Decision.3.①）。
+ */
+export class IntegrityManifest {
+  readonly version = 1 as const;
+  readonly algorithm = "sha256" as const;
+  private readonly files: ReadonlyMap<string, string>;
+
+  private constructor(files: ReadonlyMap<string, string>) {
+    this.files = new Map(files);
+    Object.freeze(this);
+  }
+
+  static create(props: IntegrityManifestProps): IntegrityManifest {
+    for (const [path, digest] of props.files) {
+      if (path.length === 0) {
+        throw new Error("IntegrityManifest: path must not be empty");
+      }
+      if (!SHA256_HEX_RE.test(digest)) {
+        throw new Error(`IntegrityManifest: digest must be 64 lowercase hex chars, got: ${digest} (path: ${path})`);
+      }
+    }
+    return new IntegrityManifest(props.files);
+  }
+
+  /** path 昇順の [path, digest] 一覧（決定的） */
+  sortedEntries(): Array<[string, string]> {
+    return [...this.files.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  }
+
+  /** path 昇順の path 一覧 */
+  paths(): readonly string[] {
+    return this.sortedEntries().map(([p]) => p);
+  }
+
+  digestOf(path: string): string | undefined {
+    return this.files.get(path);
+  }
+}

package/scripts/harness/ci-governance/domain/value-objects/integrity-target.ts

@@ -0,0 +1,40 @@
+// @unit ci-governance
+// @layer domain
+
+export interface IntegrityTargetProps {
+  readonly include: readonly string[];
+  readonly exclude: readonly string[];
+}
+
+/**
+ * 整合性 pin の対象ファイル集合を表す不変 VO（include / exclude glob）。
+ * v1 固定の既定対象は ADR-030 §Decision.3.① の指示搭載ファイル群。
+ */
+export class IntegrityTarget {
+  readonly include: readonly string[];
+  readonly exclude: readonly string[];
+
+  private constructor(props: IntegrityTargetProps) {
+    this.include = Object.freeze([...props.include]);
+    this.exclude = Object.freeze([...props.exclude]);
+    Object.freeze(this);
+  }
+
+  static create(props: IntegrityTargetProps): IntegrityTarget {
+    return new IntegrityTarget(props);
+  }
+
+  /** v1 固定の既定 pin 対象（指示搭載ファイル群） */
+  static defaultTargets(): IntegrityTarget {
+    return new IntegrityTarget({
+      include: [
+        "skills/*/SKILL.md",
+        ".claude/settings.json",
+        ".claude/scripts/*.sh",
+        ".husky/*",
+        "docs/templates/agent-context/**",
+      ],
+      exclude: [],
+    });
+  }
+}

package/scripts/harness/ci-governance/infrastructure/adapters/file-system-sha256-hasher-adapter.ts

@@ -0,0 +1,17 @@
+// @unit ci-governance
+// @layer infrastructure
+
+import * as crypto from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { Sha256HasherPort } from "../../domain/ports/sha256-hasher-port.js";
+
+export class FileSystemSha256HasherAdapter implements Sha256HasherPort {
+  constructor(private readonly baseDir: string) {}
+
+  async hashFile(relativePath: string): Promise<string> {
+    const absPath = path.isAbsolute(relativePath) ? relativePath : path.join(this.baseDir, relativePath);
+    const content = await fs.readFile(absPath);
+    return crypto.createHash("sha256").update(content).digest("hex");
+  }
+}

package/scripts/harness/ci-governance/infrastructure/adapters/harness-api-command-existence-adapter.ts

@@ -1,81 +1,15 @@
 // @unit ci-governance
 // @layer infrastructure
+// @work-item-id WI-250
 
+import { KNOWN_HARNESS_COMMANDS } from '../../../harness-api/domain/value-objects/known-harness-commands.js';
 import type { CommandExistencePort } from '../../domain/ports/command-existence-port.js';
 
-const KNOWN_HARNESS_COMMANDS: readonly string[] = [
-  'baseline',
-  'bypass:audit',
-  'check-change-category',
-  'check-phase-gate',
-  'ci-check',
-  'ci:auto-refresh-agent-context',
-  'ci:check-repetition',
-  'ci:generate-template',
-  'ci:migrate-agents-md',
-  'commit-msg',
-  'complete-check',
-  'config:plan',
-  'delegate-sonnet',
-  'disable-feature',
-  'doctor',
-  'emit-agent-rules',
-  'enable-feature',
-  'hook',
-  'init',
-  'install',
-  'lint',
-  'list-adrs',
-  'list-errors',
-  'list-features',
-  'migrate',
-  'p2:check-agent-context',
-  'p2:check-freshness',
-  'p2:check-initial-creation',
-  'p2:generate-e2e-template',
-  'p2:validate-pointers',
-  'phasegate:attest',
-  'phasegate:check-phase',
-  'phasegate:check-ready',
-  'phasegate:ci-check',
-  'phasegate:complete-check',
-  'phasegate:detect-drift',
-  'phasegate:generate-matrix',
-  'phasegate:impact-analysis',
-  'phasegate:lint',
-  'phasegate:status',
-  'phasegate:verify-attestation',
-  'pre-commit',
-  'reconcile',
-  'refresh-claude-md',
-  'regression:analyze-migration',
-  'regression:configure-ci-gate',
-  'regression:migrate-v0-tests',
-  'regression:run-agent-guard',
-  'regression:run-gng-gate',
-  'regression:run-k-requirements',
-  'regression:run-k14-k15',
-  'render-errors',
-  'scaffold-design',
-  'scaffold-wi',
-  'session',
-  'setup:agent',
-  'skill:apply-cascade-update',
-  'skill:check-coverage',
-  'skill:collect-lessons',
-  'skill:execute-tdd-cycle',
-  'skill:validate-structure',
-  'skills',
-  'status',
-  'uninstall',
-  'update-skills',
-  'validate',
-  'validate-adr',
-  'validate-fix',
-  'validate-metadata',
-  'work-items:status',
-];
-
+/**
+ * WI-250: 既知コマンドのデフォルトは harness-api domain の canonical 定数
+ * `KNOWN_HARNESS_COMMANDS` を配線する（infra ローカルの重複定義は持たない）。
+ * main.ts dispatch との乖離検出は harness-api 側の conformance テストが担う。
+ */
 export class HarnessApiCommandExistenceAdapter implements CommandExistencePort {
   private readonly knownCommands: Set<string>;
 

package/scripts/harness/ci-governance/infrastructure/adapters/integrity-manifest-json-repository-adapter.ts

@@ -0,0 +1,83 @@
+// @unit ci-governance
+// @layer infrastructure
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { IntegrityManifestRepositoryPort } from "../../domain/ports/integrity-manifest-repository-port.js";
+import { IntegrityManifest } from "../../domain/value-objects/integrity-manifest.js";
+
+interface IntegrityJsonV1 {
+  readonly version: 1;
+  readonly algorithm: "sha256";
+  readonly files: Readonly<Record<string, string>>;
+}
+
+/**
+ * phasegate.integrity.json（ルート）の読み書きアダプタ。
+ * files は path 昇順キーで決定的に書き出す。
+ */
+export class IntegrityManifestJsonRepositoryAdapter implements IntegrityManifestRepositoryPort {
+  private readonly filePath: string;
+
+  constructor(baseDir: string, relativePath = "phasegate.integrity.json") {
+    this.filePath = path.isAbsolute(relativePath) ? relativePath : path.join(baseDir, relativePath);
+  }
+
+  getPath(): string {
+    return this.filePath;
+  }
+
+  async exists(): Promise<boolean> {
+    try {
+      await fs.access(this.filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async save(manifest: IntegrityManifest): Promise<string> {
+    const files: Record<string, string> = {};
+    for (const [p, digest] of manifest.sortedEntries()) {
+      files[p] = digest;
+    }
+    const data: IntegrityJsonV1 = {
+      version: 1,
+      algorithm: "sha256",
+      files,
+    };
+    await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+    await fs.writeFile(this.filePath, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
+    return this.filePath;
+  }
+
+  async load(): Promise<IntegrityManifest | null> {
+    let content: string;
+    try {
+      content = await fs.readFile(this.filePath, "utf-8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw err;
+    }
+
+    let parsed: IntegrityJsonV1;
+    try {
+      parsed = JSON.parse(content) as IntegrityJsonV1;
+    } catch (err) {
+      throw new Error(`Invalid integrity JSON at ${this.filePath}: ${String(err)}`);
+    }
+
+    if (
+      !parsed ||
+      parsed.version !== 1 ||
+      parsed.algorithm !== "sha256" ||
+      typeof parsed.files !== "object" ||
+      parsed.files === null
+    ) {
+      throw new Error(`Invalid integrity JSON schema at ${this.filePath}`);
+    }
+
+    const files = new Map<string, string>(Object.entries(parsed.files));
+    return IntegrityManifest.create({ files });
+  }
+}

package/scripts/harness/ci-governance/presentation/handlers/integrity-handler.ts

@@ -0,0 +1,76 @@
+// @unit ci-governance
+// @layer presentation
+
+import type { PinIntegrityUseCase } from "../../application/usecases/pin-integrity-usecase.js";
+import type { VerifyIntegrityUseCase } from "../../application/usecases/verify-integrity-usecase.js";
+import type { IntegrityDriftKind } from "../../domain/value-objects/integrity-drift.js";
+
+export interface IntegrityPinArgs {
+  readonly dryRun?: boolean;
+  readonly format?: "human" | "json";
+}
+
+export interface IntegrityVerifyArgs {
+  readonly format?: "human" | "json";
+}
+
+export interface IntegrityHandlerResult {
+  readonly exitCode: number;
+  readonly output: string;
+}
+
+const DRIFT_LABEL: Record<IntegrityDriftKind, string> = {
+  mismatch: "MISMATCH (digest 不一致)",
+  added: "ADDED (manifest 未登録)",
+  missing: "MISSING (実ファイル欠落)",
+  "manifest-absent": "MANIFEST-ABSENT (manifest 欠落)",
+};
+
+export class IntegrityHandler {
+  constructor(
+    private readonly pinUseCase: PinIntegrityUseCase,
+    private readonly verifyUseCase: VerifyIntegrityUseCase,
+  ) {}
+
+  async pin(args: IntegrityPinArgs): Promise<IntegrityHandlerResult> {
+    const format = args.format ?? "human";
+    const result = await this.pinUseCase.execute({ dryRun: args.dryRun });
+
+    if (format === "json") {
+      return { exitCode: 0, output: JSON.stringify(result, null, 2) };
+    }
+
+    const header = result.dryRun
+      ? `[dry run] integrity manifest を生成しました（保存先想定: ${result.savedPath}）`
+      : `integrity manifest を保存しました: ${result.savedPath}`;
+    return {
+      exitCode: 0,
+      output: [header, `エントリ数: ${result.entryCount}`].join("\n"),
+    };
+  }
+
+  async verify(args: IntegrityVerifyArgs): Promise<IntegrityHandlerResult> {
+    const format = args.format ?? "human";
+    const result = await this.verifyUseCase.execute();
+    const exitCode = result.ok ? 0 : 2;
+
+    if (format === "json") {
+      return { exitCode, output: JSON.stringify(result, null, 2) };
+    }
+
+    if (result.ok) {
+      return {
+        exitCode: 0,
+        output: `integrity 照合 OK: drift はありません（${result.manifestPath}）`,
+      };
+    }
+
+    const lines = [
+      `integrity drift を ${result.drifts.length} 件検出しました（${result.manifestPath}）:`,
+      ...result.drifts.map((d) => `- [${DRIFT_LABEL[d.kind]}] ${d.path}`),
+      "",
+      "意図的な変更であれば `phasegate integrity:pin` で manifest を更新してください。",
+    ];
+    return { exitCode: 2, output: lines.join("\n") };
+  }
+}