phasegate 0.183.0 → 0.212.0

package/scripts/harness/biome-ast-engine/infrastructure/parsers/comment-density-parser.ts

@@ -11,22 +11,37 @@ export type CommentDensityResult = {
 
 const SINGLE_LINE_COMMENT = /^\s*\/\//;
 const MULTI_LINE_COMMENT_START = /^\s*\/\*/;
+const DOC_COMMENT_START = /^\s*\/\*\*/;
 const MULTI_LINE_COMMENT_END = /\*\//;
 const BLANK_LINE = /^\s*$/;
+// L1 ルール (require-unit-comment / require-layer-comment) が必須化する
+// 先頭メタデータヘッダのタグ行。ファイル冒頭の連続コメント領域でのみ効力を持つ。
+const METADATA_HEADER_TAG = /^\s*\/\/\s*@(unit|layer|work-item-id|story|story-id|issue-id|module|feature|epic)\b/;
 
 /**
  * ソースコードのコメント密度と繰り返しブロック数を算出する。
  *
- * - commentLineCount: コメント行数（単一行・複数行両方）
- * - logicalLineCount: 空行を除いた行数
- * - repeatedCommentBlocks: 連続する同一コメントブロックの検出回数
+ * WI-239: commentLineCount（密度分子）は「密度に寄与する narrative コメント行数」
+ * を表すよう意味を再定義した。次は分子から除外する:
+ *   - 先頭の必須メタデータヘッダ行（`// @unit` / `// @layer` / `// @work-item-id` /
+ *     `// @story` 等。ファイル冒頭の連続コメント領域に限る）
+ *   - `/** … *\/` doc-comment ブロック（ブロック全体）
+ * 分子に残すのは narrative な `//` 行コメントと非 doc の `/* … *\/` ブロックのみ。
+ *
+ * - commentLineCount: 密度分子となる narrative コメント行数
+ * - logicalLineCount: 空行を除いた行数（分母。定義不変）
+ * - repeatedCommentBlocks: 連続する同一 narrative コメントブロックの検出回数
  */
 export const parseCommentDensity = (sourceCode: string): CommentDensityResult => {
-  const lines = sourceCode.split('\n');
+  const lines = sourceCode.split("\n");
 
   let commentLineCount = 0;
   let logicalLineCount = 0;
   let insideBlockComment = false;
+  let insideDocComment = false;
+  // ファイル冒頭の連続したメタデータヘッダ領域内かどうか。
+  // 最初のコード行または非メタデータコメントが現れた時点で false になる。
+  let insideHeaderZone = true;
 
   const commentBlocks: string[] = [];
   let currentBlock: string[] = [];
@@ -41,11 +56,14 @@ export const parseCommentDensity = (sourceCode: string): CommentDensityResult =>
     logicalLineCount += 1;
 
     if (insideBlockComment) {
-      commentLineCount += 1;
-      currentBlock.push(line.trim());
+      if (!insideDocComment) {
+        commentLineCount += 1;
+        currentBlock.push(line.trim());
+      }
 
       if (MULTI_LINE_COMMENT_END.test(line)) {
         insideBlockComment = false;
+        insideDocComment = false;
         flushBlock(currentBlock, commentBlocks);
         currentBlock = [];
       }
@@ -54,25 +72,48 @@ export const parseCommentDensity = (sourceCode: string): CommentDensityResult =>
     }
 
     if (SINGLE_LINE_COMMENT.test(line)) {
+      const isMetadataHeader = insideHeaderZone && METADATA_HEADER_TAG.test(line);
+
+      if (isMetadataHeader) {
+        // メタデータヘッダは分子・反復検出のいずれにも寄与しない。
+        continue;
+      }
+
+      // narrative な行コメントに到達 → ヘッダ領域は終了。
+      insideHeaderZone = false;
       commentLineCount += 1;
       currentBlock.push(line.trim());
       continue;
     }
 
     if (MULTI_LINE_COMMENT_START.test(line)) {
+      insideHeaderZone = false;
+      const isDocComment = DOC_COMMENT_START.test(line);
+      const isClosed = MULTI_LINE_COMMENT_END.test(line);
+
+      if (isDocComment) {
+        // doc-comment ブロックは分子・反復検出のいずれにも寄与しない。
+        if (!isClosed) {
+          insideBlockComment = true;
+          insideDocComment = true;
+        }
+        continue;
+      }
+
       commentLineCount += 1;
-      insideBlockComment = true;
       currentBlock.push(line.trim());
 
-      if (MULTI_LINE_COMMENT_END.test(line)) {
-        insideBlockComment = false;
+      if (isClosed) {
         flushBlock(currentBlock, commentBlocks);
         currentBlock = [];
+      } else {
+        insideBlockComment = true;
       }
 
       continue;
     }
 
+    insideHeaderZone = false;
     flushBlock(currentBlock, commentBlocks);
     currentBlock = [];
   }
@@ -86,7 +127,7 @@ export const parseCommentDensity = (sourceCode: string): CommentDensityResult =>
 
 const flushBlock = (current: string[], blocks: string[]): void => {
   if (current.length > 0) {
-    blocks.push(current.join('\n'));
+    blocks.push(current.join("\n"));
   }
 };
 

package/scripts/harness/ci-governance/application/dto/pin-integrity-input.ts

@@ -0,0 +1,8 @@
+// @unit ci-governance
+// @layer application
+
+export interface PinIntegrityInput {
+  readonly include?: readonly string[];
+  readonly exclude?: readonly string[];
+  readonly dryRun?: boolean;
+}

package/scripts/harness/ci-governance/application/dto/pin-integrity-output.ts

@@ -0,0 +1,9 @@
+// @unit ci-governance
+// @layer application
+
+export interface PinIntegrityOutput {
+  readonly savedPath: string;
+  readonly entryCount: number;
+  readonly dryRun: boolean;
+  readonly files: ReadonlyArray<{ readonly path: string; readonly digest: string }>;
+}

package/scripts/harness/ci-governance/application/dto/verify-integrity-input.ts

@@ -0,0 +1,7 @@
+// @unit ci-governance
+// @layer application
+
+export interface VerifyIntegrityInput {
+  readonly include?: readonly string[];
+  readonly exclude?: readonly string[];
+}

package/scripts/harness/ci-governance/application/dto/verify-integrity-output.ts

@@ -0,0 +1,10 @@
+// @unit ci-governance
+// @layer application
+
+import type { IntegrityDrift } from "../../domain/value-objects/integrity-drift.js";
+
+export interface VerifyIntegrityOutput {
+  readonly manifestPath: string;
+  readonly ok: boolean;
+  readonly drifts: readonly IntegrityDrift[];
+}

package/scripts/harness/ci-governance/application/usecases/pin-integrity-usecase.ts

@@ -0,0 +1,60 @@
+// @unit ci-governance
+// @layer application
+
+import type { FileScannerPort } from "../../domain/ports/file-scanner-port.js";
+import type { IntegrityManifestRepositoryPort } from "../../domain/ports/integrity-manifest-repository-port.js";
+import type { Sha256HasherPort } from "../../domain/ports/sha256-hasher-port.js";
+import { IntegrityManifest } from "../../domain/value-objects/integrity-manifest.js";
+import { IntegrityTarget } from "../../domain/value-objects/integrity-target.js";
+import type { PinIntegrityInput } from "../dto/pin-integrity-input.js";
+import type { PinIntegrityOutput } from "../dto/pin-integrity-output.js";
+
+/**
+ * 指示搭載ファイル群の SHA-256 を再計算して manifest を書き出す。
+ * pin は常に「意図的な更新」なので overwrite 制御は行わない（dry-run のみ温存）。
+ * ADR-030 §Decision.3.①。
+ */
+export class PinIntegrityUseCase {
+  constructor(
+    private readonly scanner: FileScannerPort,
+    private readonly hasher: Sha256HasherPort,
+    private readonly repository: IntegrityManifestRepositoryPort,
+  ) {}
+
+  async execute(input: PinIntegrityInput = {}): Promise<PinIntegrityOutput> {
+    const target = IntegrityTarget.defaultTargets();
+    const include = input.include ?? target.include;
+    const exclude = input.exclude ?? target.exclude;
+    const dryRun = input.dryRun === true;
+
+    const savedPath = this.repository.getPath();
+
+    const scanned = await this.scanner.scan({ include, exclude });
+    const sortedPaths = [...scanned].sort();
+
+    const files = new Map<string, string>();
+    for (const path of sortedPaths) {
+      files.set(path, await this.hasher.hashFile(path));
+    }
+
+    const manifest = IntegrityManifest.create({ files });
+    const outputFiles = manifest.sortedEntries().map(([path, digest]) => ({ path, digest }));
+
+    if (dryRun) {
+      return {
+        savedPath,
+        entryCount: outputFiles.length,
+        dryRun: true,
+        files: outputFiles,
+      };
+    }
+
+    const writtenPath = await this.repository.save(manifest);
+    return {
+      savedPath: writtenPath,
+      entryCount: outputFiles.length,
+      dryRun: false,
+      files: outputFiles,
+    };
+  }
+}

package/scripts/harness/ci-governance/application/usecases/verify-integrity-usecase.ts

@@ -0,0 +1,46 @@
+// @unit ci-governance
+// @layer application
+
+import type { FileScannerPort } from "../../domain/ports/file-scanner-port.js";
+import type { IntegrityManifestRepositoryPort } from "../../domain/ports/integrity-manifest-repository-port.js";
+import type { Sha256HasherPort } from "../../domain/ports/sha256-hasher-port.js";
+import type { IntegrityChecker } from "../../domain/services/integrity-checker.js";
+import { IntegrityTarget } from "../../domain/value-objects/integrity-target.js";
+import type { VerifyIntegrityInput } from "../dto/verify-integrity-input.js";
+import type { VerifyIntegrityOutput } from "../dto/verify-integrity-output.js";
+
+/**
+ * manifest を読み込み、指示搭載ファイルを再計算して照合する。
+ * drift（不一致・追加・欠落・manifest 欠落）を列挙する。ADR-030 §Decision.3.①。
+ */
+export class VerifyIntegrityUseCase {
+  constructor(
+    private readonly scanner: FileScannerPort,
+    private readonly hasher: Sha256HasherPort,
+    private readonly repository: IntegrityManifestRepositoryPort,
+    private readonly checker: IntegrityChecker,
+  ) {}
+
+  async execute(input: VerifyIntegrityInput = {}): Promise<VerifyIntegrityOutput> {
+    const target = IntegrityTarget.defaultTargets();
+    const include = input.include ?? target.include;
+    const exclude = input.exclude ?? target.exclude;
+
+    const manifestPath = this.repository.getPath();
+    const manifest = await this.repository.load();
+
+    const scanned = await this.scanner.scan({ include, exclude });
+    const actual = new Map<string, string>();
+    for (const path of [...scanned].sort()) {
+      actual.set(path, await this.hasher.hashFile(path));
+    }
+
+    const drifts = this.checker.computeDrifts(manifest, actual);
+
+    return {
+      manifestPath,
+      ok: drifts.length === 0,
+      drifts,
+    };
+  }
+}

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();
@@ -84,7 +83,7 @@ export function buildCiGovernance(
   const templateRendererPort = new YamlTemplateRendererAdapter(harnessRoot);
   const fileExistencePort = new FileSystemExistenceAdapter(baseDir);
   const commandExistencePort = new HarnessApiCommandExistenceAdapter();
-  const adrExistencePort = new AdrFoundationExistenceAdapter();
+  const adrExistencePort = new AdrFoundationExistenceAdapter(baseDir);
   const agentsMdPort = new AgentsMdFileAdapter(baseDir);
   const agentContextDocumentPort = new AgentContextFileAdapter(baseDir, harnessRoot);
   const lessonArtifactReaderPort = new LessonArtifactFileReaderAdapter(baseDir);
@@ -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: [],
+    });
+  }
+}