phasegate 0.150.1 → 0.151.0

package/scripts/harness/validator-system/domain/services/contract-traceability-coverage-service.ts

@@ -0,0 +1,259 @@
+// @unit validator-system
+// @layer domain
+// @work-item-id WI-132 / WI-133 / WI-136 / WI-137 / WI-138
+
+import {
+  type BoundaryCaseKind,
+  type ContractTraceabilityFinding,
+  type ContractTraceabilityInput,
+  ContractTraceabilityReport,
+  type ErrorContract,
+  type PublicContract,
+  type StateMachineModel,
+  type TestObservation,
+  type TraceabilityGraphSlice,
+} from '../value-objects/contract-traceability-model.js';
+
+export class ContractTraceabilityCoverageService {
+  check(input: ContractTraceabilityInput): ContractTraceabilityReport {
+    return ContractTraceabilityReport.create([
+      ...this.checkPublicContracts(input.publicContracts, input.testObservations),
+      ...this.checkErrorContracts(input.errorContracts, input.testObservations),
+      ...this.checkStateMachines(input.stateMachines, input.testObservations),
+      ...this.checkTraceability(input.traceabilitySlices),
+    ]);
+  }
+
+  private checkPublicContracts(
+    contracts: readonly PublicContract[],
+    observations: readonly TestObservation[],
+  ): readonly ContractTraceabilityFinding[] {
+    const findings: ContractTraceabilityFinding[] = [];
+    for (const contract of contracts) {
+      for (const behavior of contract.requiredBehaviors) {
+        if (!this.isCovered(`${contract.id}:${behavior}`, observations)) {
+          findings.push(this.finding(
+            'missing-required-behavior-test',
+            contract.id,
+            contract.sourcePath,
+            `Public contract ${contract.id} requires behavior "${behavior}" but no matching test observation covers it.`,
+            `Add a test observation covering ${contract.id}:${behavior}.`,
+          ));
+        }
+      }
+
+      if (contract.kind === 'port' && !observations.some((observation) => (
+        observation.kind === 'adapter-contract' && observation.covers.includes(contract.id)
+      ))) {
+        findings.push(this.finding(
+          'missing-port-contract-test',
+          contract.id,
+          contract.sourcePath,
+          `Port contract ${contract.id} has no adapter contract test observation.`,
+          `Add an adapter contract test that covers ${contract.id}.`,
+        ));
+      }
+
+      for (const boundaryCase of contract.boundaryCases ?? []) {
+        if (!this.isBoundaryCovered(contract, boundaryCase, observations)) {
+          findings.push(this.finding(
+            'missing-boundary-test',
+            contract.id,
+            contract.sourcePath,
+            `Contract ${contract.id} requires boundary case "${boundaryCase}" but no matching test observation covers it.`,
+            `Add a boundary test observation covering ${contract.id}:boundary:${boundaryCase}.`,
+          ));
+        }
+      }
+    }
+    return findings;
+  }
+
+  private checkErrorContracts(
+    contracts: readonly ErrorContract[],
+    observations: readonly TestObservation[],
+  ): readonly ContractTraceabilityFinding[] {
+    const findings: ContractTraceabilityFinding[] = [];
+    for (const contract of contracts) {
+      const missingShapeFields = [
+        ['code', contract.code],
+        ['severity', contract.severity],
+        ['message', contract.message],
+        ['suggestion', contract.suggestion],
+        ['documentationRef', contract.documentationRef],
+      ].filter(([, value]) => !this.hasUsefulText(value));
+
+      if (missingShapeFields.length > 0) {
+        findings.push(this.finding(
+          'error-contract-shape',
+          contract.id,
+          contract.sourcePath,
+          `Error contract ${contract.id} is missing required fields: ${missingShapeFields.map(([field]) => field).join(', ')}.`,
+          'Provide stable code, severity, message, suggestion, and documentation reference.',
+        ));
+      }
+
+      if (this.isGenericSuggestion(contract.suggestion)) {
+        findings.push(this.finding(
+          'error-contract-shape',
+          contract.id,
+          contract.sourcePath,
+          `Error contract ${contract.id} has a generic or empty recovery suggestion.`,
+          'Replace the suggestion with a concrete next action.',
+        ));
+      }
+
+      if (contract.exitCode !== undefined && contract.severity !== undefined) {
+        const expected = contract.severity === 'error' ? [1, 2] : [0];
+        if (!expected.includes(contract.exitCode)) {
+          findings.push(this.finding(
+            'error-contract-exit-code',
+            contract.id,
+            contract.sourcePath,
+            `Error contract ${contract.id} severity=${contract.severity} is inconsistent with exitCode=${contract.exitCode}.`,
+            'Align warning contracts with exit 0 and error contracts with exit 1 or 2.',
+          ));
+        }
+      }
+
+      if (!this.isCovered(`${contract.id}:error-path`, observations)) {
+        findings.push(this.finding(
+          'missing-error-path-test',
+          contract.id,
+          contract.sourcePath,
+          `Error contract ${contract.id} has no error path test observation.`,
+          `Add a test observation covering ${contract.id}:error-path.`,
+        ));
+      }
+    }
+    return findings;
+  }
+
+  private checkStateMachines(
+    machines: readonly StateMachineModel[],
+    observations: readonly TestObservation[],
+  ): readonly ContractTraceabilityFinding[] {
+    const findings: ContractTraceabilityFinding[] = [];
+    for (const machine of machines) {
+      const codeStates = new Set(machine.codeStates);
+      const docsStates = new Set(machine.docsStates);
+      const mismatchedStates = [
+        ...machine.docsStates.filter((state) => !codeStates.has(state)),
+        ...machine.codeStates.filter((state) => !docsStates.has(state)),
+      ];
+      if (mismatchedStates.length > 0) {
+        findings.push(this.finding(
+          'state-doc-code-mismatch',
+          machine.id,
+          machine.sourcePath,
+          `State machine ${machine.id} has docs/code state mismatch: ${mismatchedStates.join(', ')}.`,
+          'Update docs and code state definitions so they describe the same states.',
+        ));
+      }
+
+      for (const transition of machine.invalidTransitions) {
+        if (machine.terminalStates.includes(transition.from)) {
+          findings.push(this.finding(
+            'state-invalid-terminal-transition',
+            machine.id,
+            machine.sourcePath,
+            `State machine ${machine.id} defines invalid transition from terminal state ${transition.from} to ${transition.to}.`,
+            'Remove terminal-state outgoing transitions or mark them as rejected behavior.',
+          ));
+        }
+      }
+
+      for (const transition of machine.transitions) {
+        const key = `${machine.id}:transition:${transition.from}->${transition.to}`;
+        if (!this.isCovered(key, observations)) {
+          findings.push(this.finding(
+            'missing-transition-test',
+            machine.id,
+            machine.sourcePath,
+            `State transition ${transition.from}->${transition.to} has no success/failure test observation.`,
+            `Add a test observation covering ${key}.`,
+          ));
+        }
+      }
+    }
+    return findings;
+  }
+
+  private checkTraceability(slices: readonly TraceabilityGraphSlice[]): readonly ContractTraceabilityFinding[] {
+    const findings: ContractTraceabilityFinding[] = [];
+    for (const slice of slices) {
+      const productUnits = new Set(slice.productUnits);
+      const missingUnits = slice.affectedUnits.filter((unit) => !productUnits.has(unit));
+      if (missingUnits.length > 0) {
+        findings.push(this.finding(
+          'traceability-unit-mismatch',
+          slice.workItemId,
+          slice.workItemId,
+          `${slice.workItemId} affects units without product reflection: ${missingUnits.join(', ')}.`,
+          `Reflect @work-item-id ${slice.workItemId} in product docs for each affected unit.`,
+        ));
+      }
+
+      if (slice.implementationWorkItemIds.includes(slice.workItemId) && !slice.testWorkItemIds.includes(slice.workItemId)) {
+        findings.push(this.finding(
+          'traceability-test-mismatch',
+          slice.workItemId,
+          slice.workItemId,
+          `${slice.workItemId} has implementation evidence but no matching test observation.`,
+          `Add tests annotated with @work-item-id ${slice.workItemId}.`,
+        ));
+      }
+
+      if (slice.publicDocsChanged !== slice.contractChanged) {
+        findings.push(this.finding(
+          'public-doc-contract-sync',
+          slice.workItemId,
+          slice.workItemId,
+          `${slice.workItemId} public docs and public contract changes are not synchronized.`,
+          'Update public docs and contract declarations in the same WI, or document why only one changed.',
+        ));
+      }
+    }
+    return findings;
+  }
+
+  private isBoundaryCovered(
+    contract: PublicContract,
+    boundaryCase: BoundaryCaseKind,
+    observations: readonly TestObservation[],
+  ): boolean {
+    return this.isCovered(`${contract.id}:boundary:${boundaryCase}`, observations)
+      || this.isCovered(`${contract.id}:${boundaryCase}`, observations);
+  }
+
+  private isCovered(requiredKey: string, observations: readonly TestObservation[]): boolean {
+    return observations.some((observation) => observation.covers.includes(requiredKey));
+  }
+
+  private hasUsefulText(value: unknown): boolean {
+    return typeof value === 'string' && value.trim().length > 0;
+  }
+
+  private isGenericSuggestion(value: unknown): boolean {
+    if (!this.hasUsefulText(value)) return true;
+    const normalized = String(value).trim().toLowerCase();
+    return ['fix it', 'check the error', 'see logs', 'unknown'].includes(normalized);
+  }
+
+  private finding(
+    kind: ContractTraceabilityFinding['kind'],
+    subject: string,
+    sourcePath: string,
+    message: string,
+    suggestion: string,
+  ): ContractTraceabilityFinding {
+    return {
+      kind,
+      severity: 'error',
+      subject,
+      sourcePath,
+      message,
+      suggestion,
+    };
+  }
+}

package/scripts/harness/validator-system/domain/services/l4/consistency-check-service.ts

@@ -1,6 +1,7 @@
 /**
  * @layer domain
  * @unit validator-system
+ * @work-item-id WI-118
  *
  * ConsistencyCheckService ドメインサービス
  * 設計文書間のレイヤー整合性検証（L4-002）
@@ -35,26 +36,24 @@ export class ConsistencyCheckService {
     const mismatchPairs: { expected: string; actual: string; location: string }[] = [];
     const checkTargets = Object.keys(layerAnnotations);
 
-    // レイヤー記述の整合性チェック（全ドキュメントが同じレイヤーを参照していることを確認）
-    const layerValues = Object.values(layerAnnotations);
-    if (layerValues.length > 1) {
-      const referenceLayer = layerValues[0];
-      for (const [docPath, layer] of Object.entries(layerAnnotations)) {
-        if (layer !== referenceLayer) {
-          mismatchPairs.push({
-            expected: referenceLayer,
-            actual: layer,
-            location: docPath,
-          });
-        }
+    for (const [location, annotation] of Object.entries(layerAnnotations)) {
+      if (annotation === 'layer:unknown') {
+        mismatchPairs.push({
+          expected: 'known layer vocabulary',
+          actual: 'unknown layer vocabulary',
+          location,
+        });
+      }
+
+      if (annotation.startsWith('unit:mismatch:')) {
+        mismatchPairs.push({
+          expected: annotation.slice('unit:mismatch:'.length),
+          actual: location.includes('#unit:') ? location.slice(location.indexOf('#unit:') + '#unit:'.length) : 'unknown',
+          location,
+        });
       }
     }
 
-    // ADR実在性確認（ポートが存在する場合）
-    // adrReferencePort.exists を使って参照 ADR の実在を確認する
-    // DesignDocumentPort の layerAnnotations には ADR 参照が含まれないため、
-    // ADR 参照は別途取得する（ここではシンプル実装）
-    // ADR not found => mismatch として扱う
     const knownAdrRefs = checkTargets
       .filter((t) => t.startsWith('ADR-'))
       .map((t) => t);

package/scripts/harness/validator-system/domain/services/l4/drift-detection-service.ts

@@ -1,6 +1,7 @@
 /**
  * @layer domain
  * @unit validator-system
+ * @work-item-id WI-117
  *
  * DriftDetectionService ドメインサービス
  * 設計文書（domain_model.md等）とソースコード実装の双方向乖離検出（L4-001）
@@ -9,6 +10,7 @@ import { DriftReport } from '../../value-objects/drift-report.js';
 
 export interface DriftDetectionDesignDocumentPort {
   getElements(targetUnits?: readonly string[]): Promise<string[]>;
+  getElementRecords?(targetUnits?: readonly string[]): Promise<readonly DriftElementRecord[]>;
   /**
    * WI-095: 設計要素 → 実装ファイル path の明示対応。
    * 実装されていれば element 名完全一致に加えて drift 判定に使う。
@@ -23,6 +25,7 @@ export interface DriftDetectionDesignDocumentPort {
 
 export interface DriftDetectionSourceCodeAnalyzerPort {
   getElements(targetUnits?: readonly string[]): Promise<string[]>;
+  getElementRecords?(targetUnits?: readonly string[]): Promise<readonly DriftElementRecord[]>;
   /**
    * WI-095: export element → 定義ファイル path のマップ。
    * 実装されていれば design pointer と照合する。
@@ -40,6 +43,13 @@ export interface DriftDetectionServiceDeps {
   sourceCodeAnalyzerPort: DriftDetectionSourceCodeAnalyzerPort;
 }
 
+export interface DriftElementRecord {
+  readonly element: string;
+  readonly unitName: string;
+  readonly filePaths?: readonly string[];
+  readonly pointers?: readonly string[];
+}
+
 export class DriftDetectionService {
   private readonly designDocumentPort: DriftDetectionDesignDocumentPort;
   private readonly sourceCodeAnalyzerPort: DriftDetectionSourceCodeAnalyzerPort;
@@ -50,87 +60,122 @@ export class DriftDetectionService {
   }
 
   async detect(targetUnits?: readonly string[]): Promise<readonly DriftReport[]> {
-    const designElements = await this.designDocumentPort.getElements(targetUnits);
-    const codeElements = await this.sourceCodeAnalyzerPort.getElements(targetUnits);
-    const designPointers = this.designDocumentPort.getElementPointers
-      ? await this.designDocumentPort.getElementPointers(targetUnits)
-      : {};
-    const codeFilePathMap = this.sourceCodeAnalyzerPort.getElementFilePathMap
-      ? await this.sourceCodeAnalyzerPort.getElementFilePathMap(targetUnits)
-      : {};
+    const designRecords = await this.loadDesignRecords(targetUnits);
+    const codeRecords = await this.loadCodeRecords(targetUnits);
 
-    // ISSUE-005 P3-9: element → unit のマップを取得し、DriftReport.unitName の解決に使う
-    const designUnitMap = this.designDocumentPort.getElementUnitMap
-      ? await this.designDocumentPort.getElementUnitMap(targetUnits)
-      : {};
-    const codeUnitMap = this.sourceCodeAnalyzerPort.getElementUnitMap
-      ? await this.sourceCodeAnalyzerPort.getElementUnitMap(targetUnits)
-      : {};
+    const designKeys = new Set(designRecords.map(toDriftKey));
+    const codeKeys = new Set(codeRecords.map(toDriftKey));
+    const pointerMatchedDesignKeys = new Set<string>();
+    const pointerMatchedCodeKeys = new Set<string>();
+
+    for (const designRecord of designRecords) {
+      const pointers = designRecord.pointers ?? [];
+      if (pointers.length === 0) continue;
 
-    const resolveUnit = (element: string): string => {
-      return (
-        designUnitMap[element] ??
-        codeUnitMap[element] ??
-        targetUnits?.[0] ??
-        'unknown'
+      const matchingCodeRecords = codeRecords.filter((codeRecord) =>
+        codeRecord.unitName === designRecord.unitName &&
+        (codeRecord.filePaths ?? []).some((filePath) => pointers.some((pointer) => isSameOrNestedPath(filePath, pointer)))
       );
-    };
 
-    const designSet = new Set(designElements);
-    const codeSet = new Set(codeElements);
-    const pointerMatchedDesignElements = new Set<string>();
-    const pointerMatchedCodeElements = new Set<string>();
+      if (matchingCodeRecords.length === 0) continue;
 
-    for (const element of designElements) {
-      const pointers = designPointers[element] ?? [];
-      if (pointers.length === 0) continue;
-      const matchedCodeElements = codeElements.filter((codeElement) =>
-        (codeFilePathMap[codeElement] ?? []).some((filePath) => pointers.some((pointer) => isSameOrNestedPath(filePath, pointer)))
-      );
-      if (matchedCodeElements.length > 0) {
-        pointerMatchedDesignElements.add(element);
-        for (const codeElement of matchedCodeElements) {
-          pointerMatchedCodeElements.add(codeElement);
+      pointerMatchedDesignKeys.add(toDriftKey(designRecord));
+
+      // WI-117: pointer は同一ファイル内の全 export を blanket match しない。
+      // 明示 pointer が名前変更の橋渡しとして使えるのは、当該ファイルの public export が 1 つだけの場合に限定する。
+      if (matchingCodeRecords.length === 1) {
+        pointerMatchedCodeKeys.add(toDriftKey(matchingCodeRecords[0]));
+      } else {
+        for (const codeRecord of matchingCodeRecords) {
+          if (codeRecord.element === designRecord.element) {
+            pointerMatchedCodeKeys.add(toDriftKey(codeRecord));
+          }
         }
       }
     }
 
     const reports: DriftReport[] = [];
 
-    // 設計に存在するがコードに存在しない
-    for (const element of designElements) {
-      if (!codeSet.has(element) && !pointerMatchedDesignElements.has(element)) {
+    for (const designRecord of designRecords) {
+      const key = toDriftKey(designRecord);
+      if (!codeKeys.has(key) && !pointerMatchedDesignKeys.has(key)) {
         reports.push(
           DriftReport.create({
             direction: 'design→code',
-            unitName: resolveUnit(element),
-            element,
-            description: `設計に存在するがコードに存在しない: ${element}`,
-            recommendation: `${element} をコードに実装してください`,
+            unitName: designRecord.unitName,
+            element: designRecord.element,
+            description: `設計に存在するがコードに存在しない: ${designRecord.element}`,
+            recommendation: `${designRecord.element} をコードに実装してください`,
           })
         );
       }
     }
 
-    // コードに存在するが設計に存在しない
-    for (const element of codeElements) {
-      if (!designSet.has(element) && !pointerMatchedCodeElements.has(element)) {
+    for (const codeRecord of codeRecords) {
+      const key = toDriftKey(codeRecord);
+      if (!designKeys.has(key) && !pointerMatchedCodeKeys.has(key)) {
         reports.push(
           DriftReport.create({
             direction: 'code→design',
-            unitName: resolveUnit(element),
-            element,
-            description: `コードに存在するが設計に存在しない: ${element}`,
-            recommendation: `${element} を設計文書に追記するか、コードから削除してください`,
+            unitName: codeRecord.unitName,
+            element: codeRecord.element,
+            description: `コードに存在するが設計に存在しない: ${codeRecord.element}`,
+            recommendation: `${codeRecord.element} を設計文書に追記するか、コードから削除してください`,
           })
         );
       }
     }
 
     return reports.sort((a, b) =>
-      a.direction.localeCompare(b.direction) || a.unitName.localeCompare(b.unitName)
+      a.direction.localeCompare(b.direction) ||
+      a.unitName.localeCompare(b.unitName) ||
+      a.element.localeCompare(b.element)
     );
   }
+
+  private async loadDesignRecords(targetUnits?: readonly string[]): Promise<readonly DriftElementRecord[]> {
+    if (this.designDocumentPort.getElementRecords) {
+      return this.designDocumentPort.getElementRecords(targetUnits);
+    }
+
+    const designElements = await this.designDocumentPort.getElements(targetUnits);
+    const designPointers = this.designDocumentPort.getElementPointers
+      ? await this.designDocumentPort.getElementPointers(targetUnits)
+      : {};
+    const designUnitMap = this.designDocumentPort.getElementUnitMap
+      ? await this.designDocumentPort.getElementUnitMap(targetUnits)
+      : {};
+
+    return designElements.map((element) => ({
+      element,
+      unitName: designUnitMap[element] ?? targetUnits?.[0] ?? 'unknown',
+      pointers: designPointers[element] ?? [],
+    }));
+  }
+
+  private async loadCodeRecords(targetUnits?: readonly string[]): Promise<readonly DriftElementRecord[]> {
+    if (this.sourceCodeAnalyzerPort.getElementRecords) {
+      return this.sourceCodeAnalyzerPort.getElementRecords(targetUnits);
+    }
+
+    const codeElements = await this.sourceCodeAnalyzerPort.getElements(targetUnits);
+    const codeFilePathMap = this.sourceCodeAnalyzerPort.getElementFilePathMap
+      ? await this.sourceCodeAnalyzerPort.getElementFilePathMap(targetUnits)
+      : {};
+    const codeUnitMap = this.sourceCodeAnalyzerPort.getElementUnitMap
+      ? await this.sourceCodeAnalyzerPort.getElementUnitMap(targetUnits)
+      : {};
+
+    return codeElements.map((element) => ({
+      element,
+      unitName: codeUnitMap[element] ?? targetUnits?.[0] ?? 'unknown',
+      filePaths: codeFilePathMap[element] ?? [],
+    }));
+  }
+}
+
+function toDriftKey(record: DriftElementRecord): string {
+  return `${record.unitName}\0${record.element}`;
 }
 
 function normalizePath(path: string): string {

package/scripts/harness/validator-system/domain/services/l4/semantic-drift-service.ts

@@ -0,0 +1,112 @@
+/**
+ * @layer domain
+ * @unit validator-system
+ * @work-item-id WI-139
+ */
+import { SemanticDriftReport } from '../../value-objects/semantic-drift-report.js';
+
+export interface DesignIntent {
+  readonly behaviorId: string;
+  readonly unitName: string;
+  readonly source: string;
+}
+
+export interface ImplementationBehavior {
+  readonly behaviorId: string;
+  readonly unitName: string;
+  readonly source: string;
+  readonly isPublic: boolean;
+}
+
+export interface TestObservation {
+  readonly behaviorId: string;
+  readonly unitName: string;
+  readonly source: string;
+}
+
+export interface SemanticDriftInput {
+  readonly designIntents: readonly DesignIntent[];
+  readonly implementationBehaviors: readonly ImplementationBehavior[];
+  readonly testObservations: readonly TestObservation[];
+}
+
+export class SemanticDriftService {
+  detect(input: SemanticDriftInput): readonly SemanticDriftReport[] {
+    const designKeys = new Set(input.designIntents.map(toBehaviorKey));
+    const codeKeys = new Set(input.implementationBehaviors.filter((entry) => entry.isPublic).map(toBehaviorKey));
+    const testKeys = new Set(input.testObservations.map(toBehaviorKey));
+    const reports: SemanticDriftReport[] = [];
+
+    for (const intent of input.designIntents) {
+      const key = toBehaviorKey(intent);
+      if (!codeKeys.has(key)) {
+        reports.push(SemanticDriftReport.create({
+          kind: 'design-behavior-missing-code',
+          behaviorId: intent.behaviorId,
+          unitName: intent.unitName,
+          severity: 'error',
+          location: intent.source,
+          nextAction: 'Implement the designed behavior or remove the design intent',
+        }));
+      }
+      if (!testKeys.has(key)) {
+        reports.push(SemanticDriftReport.create({
+          kind: 'design-behavior-missing-test',
+          behaviorId: intent.behaviorId,
+          unitName: intent.unitName,
+          severity: 'warning',
+          location: intent.source,
+          nextAction: 'Add a test observation for the design intent',
+        }));
+      }
+    }
+
+    for (const behavior of input.implementationBehaviors.filter((entry) => entry.isPublic)) {
+      const key = toBehaviorKey(behavior);
+      if (!designKeys.has(key)) {
+        reports.push(SemanticDriftReport.create({
+          kind: 'code-behavior-missing-design',
+          behaviorId: behavior.behaviorId,
+          unitName: behavior.unitName,
+          severity: 'warning',
+          location: behavior.source,
+          nextAction: 'Document the public behavior or make it private/internal',
+        }));
+      }
+      if (!testKeys.has(key)) {
+        reports.push(SemanticDriftReport.create({
+          kind: 'code-behavior-missing-test',
+          behaviorId: behavior.behaviorId,
+          unitName: behavior.unitName,
+          severity: 'warning',
+          location: behavior.source,
+          nextAction: 'Add a test observation for the public behavior',
+        }));
+      }
+    }
+
+    for (const observation of input.testObservations) {
+      const key = toBehaviorKey(observation);
+      if (!designKeys.has(key)) {
+        reports.push(SemanticDriftReport.create({
+          kind: 'test-observation-missing-design',
+          behaviorId: observation.behaviorId,
+          unitName: observation.unitName,
+          severity: 'warning',
+          location: observation.source,
+          nextAction: 'Link the test observation to design intent or loosen the test',
+        }));
+      }
+    }
+
+    return reports.sort((a, b) =>
+      a.unitName.localeCompare(b.unitName) ||
+      a.behaviorId.localeCompare(b.behaviorId) ||
+      a.kind.localeCompare(b.kind)
+    );
+  }
+}
+
+function toBehaviorKey(entry: { readonly behaviorId: string; readonly unitName: string }): string {
+  return `${entry.unitName}\0${entry.behaviorId}`;
+}

package/scripts/harness/validator-system/domain/value-objects/consistency-report.ts

@@ -1,6 +1,7 @@
 /**
  * @layer domain
  * @unit validator-system
+ * @work-item-id WI-118
  *
  * ConsistencyReport 値オブジェクト
  * 設計文書間のレイヤー整合性検証結果VO（L4-002専用）
@@ -11,6 +12,7 @@ export interface MismatchPair {
   readonly expected: string;
   readonly actual: string;
   readonly location: string;
+  readonly nextAction?: string;
 }
 
 export interface ConsistencyReportProps {
@@ -49,7 +51,7 @@ export class ConsistencyReport {
       code: { value: 'L4-002', toString: () => 'L4-002' },
       severity: { value: 'warning', toString: () => 'warning' },
       message: `レイヤー整合性違反: expected "${pair.expected}" but got "${pair.actual}" at ${pair.location}`,
-      suggestion: '設計文書間のレイヤー依存方向を統一してください',
+      suggestion: pair.nextAction ?? '設計文書間のレイヤー依存方向を統一してください',
     }));
   }
 }