phasegate 0.150.0 → 0.150.2

package/scripts/harness/phase2-extensions/application/usecases/validate-doc-pointers-usecase.ts

@@ -35,6 +35,7 @@ export class ValidateDocPointersUseCase {
 
       const results = [];
       let totalDocuments = 0;
+      let skippedUrlPointers = 0;
 
       for (const rule of filteredRules) {
         const documentPaths = await this.documentScannerPort.scan(rule.documentPattern);
@@ -45,7 +46,13 @@ export class ValidateDocPointersUseCase {
           const validationResults = await this.pointerResolutionService.resolve(pointers);
 
           for (const validationResult of validationResults) {
-            if (validationResult.pointer.isUrl() && !input.includeUrlPointers) {
+            const semanticPointerType = classifyPointerTarget(validationResult.pointer.target, validationResult.pointer.type);
+            const severity = validationResult.pointer.isUrl() && !input.includeUrlPointers
+              ? 'skip'
+              : rule.policyFor(semanticPointerType);
+
+            if (severity === 'skip') {
+              if (validationResult.pointer.isUrl()) skippedUrlPointers += 1;
               continue;
             }
 
@@ -53,8 +60,14 @@ export class ValidateDocPointersUseCase {
               documentPath,
               pointerTarget: validationResult.pointer.target,
               pointerType: validationResult.pointer.type,
+              semanticPointerType,
+              owner: rule.owner,
+              severity,
               isResolvable: validationResult.isResolvable,
               errorMessage: validationResult.errorMessage,
+              nextAction: validationResult.isResolvable
+                ? 'no action required'
+                : `Fix ${semanticPointerType} pointer or change policy for owner ${rule.owner}`,
             });
           }
 
@@ -66,9 +79,7 @@ export class ValidateDocPointersUseCase {
       }
 
       const brokenPointers = results.filter((result) => !result.isResolvable).length;
-      const skippedUrlPointers = results.filter((result) => result.pointerType === 'url').length;
-      const failingRules = filteredRules.filter((rule) => rule.shouldFailOnBroken());
-      const passed = failingRules.length === 0 || brokenPointers === 0;
+      const passed = !results.some((result) => !result.isResolvable && result.severity === 'fail');
 
       return {
         results,
@@ -96,3 +107,11 @@ export class ValidateDocPointersUseCase {
     }
   }
 }
+
+function classifyPointerTarget(target: string, rawType: 'file-path' | 'url'): 'reference' | 'implementation' | 'adr' | 'product-doc' | 'external-url' {
+  if (rawType === 'url') return 'external-url';
+  if (/docs\/ADR\/|ADR-\d{3}/i.test(target)) return 'adr';
+  if (/docs\/product\//.test(target)) return 'product-doc';
+  if (/scripts\/harness\/|\.ts$/.test(target)) return 'implementation';
+  return 'reference';
+}

package/scripts/harness/phase2-extensions/domain/aggregates/pointer-rule.ts

@@ -8,17 +8,23 @@ export interface PointerRuleProps {
   ruleId: string;
   documentPattern: string;
   failOnBroken: boolean;
+  owner?: string;
+  pointerPolicies?: Record<string, 'fail' | 'warn' | 'skip'>;
 }
 
 export class PointerRule {
   readonly ruleId: string;
   readonly documentPattern: string;
   readonly failOnBroken: boolean;
+  readonly owner: string;
+  readonly pointerPolicies: Readonly<Record<string, 'fail' | 'warn' | 'skip'>>;
 
   private constructor(props: PointerRuleProps) {
     this.ruleId = props.ruleId;
     this.documentPattern = props.documentPattern;
     this.failOnBroken = props.failOnBroken;
+    this.owner = props.owner ?? 'unowned';
+    this.pointerPolicies = Object.freeze({ ...(props.pointerPolicies ?? {}) });
     Object.freeze(this);
   }
 
@@ -35,4 +41,11 @@ export class PointerRule {
   shouldFailOnBroken(): boolean {
     return this.failOnBroken;
   }
+
+  policyFor(pointerType: string): 'fail' | 'warn' | 'skip' {
+    if (pointerType === 'external-url' && this.pointerPolicies[pointerType] === undefined) {
+      return 'skip';
+    }
+    return this.pointerPolicies[pointerType] ?? (this.failOnBroken ? 'fail' : 'warn');
+  }
 }

package/scripts/harness/phase2-extensions/domain/services/freshness-check-service.ts

@@ -10,8 +10,10 @@ export interface FreshnessCheckResult {
   documentPath: string;
   ageInDays: number;
   ageSource: DocumentAgeSource;
+  category: 'stable' | 'stale-after-source-change';
   level: 'ok' | 'warn' | 'error';
   message: string;
+  nextAction: string;
 }
 
 export class FreshnessCheckService {
@@ -22,8 +24,10 @@ export class FreshnessCheckService {
         documentPath,
         ageInDays: documentAge.ageInDays,
         ageSource: documentAge.source,
+        category: 'stable',
         level: 'ok',
         message: 'disabled rule skipped',
+        nextAction: 'no action required',
       };
     }
 
@@ -39,8 +43,14 @@ export class FreshnessCheckService {
       documentPath,
       ageInDays: documentAge.ageInDays,
       ageSource: documentAge.source,
+      category: documentAge.source === 'related-source-change' ? 'stale-after-source-change' : 'stable',
       level,
       message: `${documentPath} is ${documentAge.ageInDays} days old`,
+      nextAction: level === 'ok'
+        ? 'no action required'
+        : documentAge.source === 'related-source-change'
+          ? 'Refresh the document against the related WI/product/source change'
+          : 'Review whether this stable document should have a wider freshness threshold',
     };
   }
 }

package/scripts/harness/phase2-extensions/domain/value-objects/document-age.ts

@@ -4,7 +4,7 @@
  */
 import { Phase2ExtensionsDomainError } from '../errors/phase2-extensions-domain-error.js';
 
-export type DocumentAgeSource = 'git-log' | 'file-mtime';
+export type DocumentAgeSource = 'git-log' | 'file-mtime' | 'related-source-change';
 
 export interface DocumentAgeProps {
   ageInDays: number;
@@ -25,7 +25,7 @@ export class DocumentAge {
     if (!Number.isFinite(props.ageInDays) || props.ageInDays < 0) {
       throw new Phase2ExtensionsDomainError('L4-204', 'ageInDays は 0 以上である必要があります');
     }
-    if (props.source !== 'git-log' && props.source !== 'file-mtime') {
+    if (props.source !== 'git-log' && props.source !== 'file-mtime' && props.source !== 'related-source-change') {
       throw new Phase2ExtensionsDomainError('L4-205', 'source が不正です');
     }
     return new DocumentAge({

package/scripts/harness/phase2-extensions/infrastructure/adapters/harness-config-freshness-adapter.ts

@@ -25,6 +25,8 @@ type Phase2RuleConfig = {
       ruleId: string;
       documentPattern: string;
       failOnBroken?: boolean;
+      owner?: string;
+      pointerPolicies?: Record<string, 'fail' | 'warn' | 'skip'>;
     }>;
   };
 };
@@ -73,6 +75,14 @@ export class HarnessConfigFreshnessAdapter implements FreshnessConfigPort {
           ruleId: 'default-pointer-rule',
           documentPattern: `${designDocsRoot}/**/*.md`,
           failOnBroken: true,
+          owner: 'documentation',
+          pointerPolicies: {
+            'product-doc': 'fail',
+            adr: 'fail',
+            implementation: 'warn',
+            reference: 'warn',
+            'external-url': 'skip',
+          },
         }),
       ];
     }
@@ -82,6 +92,8 @@ export class HarnessConfigFreshnessAdapter implements FreshnessConfigPort {
         ruleId: rule.ruleId,
         documentPattern: rule.documentPattern,
         failOnBroken: rule.failOnBroken ?? true,
+        owner: rule.owner,
+        pointerPolicies: rule.pointerPolicies,
       }),
     );
   }

package/scripts/harness/phase2-extensions/presentation/formatters/pointer-result-formatter.ts

@@ -12,7 +12,9 @@ export class PointerResultFormatter {
   formatText(result: ValidateDocPointersOutput): string {
     return [
       `documents=${result.summary.totalDocuments} pointers=${result.summary.totalPointers} broken=${result.summary.brokenPointers}`,
-      ...result.results.map((entry) => `${entry.isResolvable ? 'ok' : 'broken'}: ${entry.pointerTarget}`),
+      ...result.results.map((entry) =>
+        `${entry.isResolvable ? 'ok' : entry.severity}: ${entry.semanticPointerType} ${entry.pointerTarget} owner=${entry.owner} next=${entry.nextAction}`
+      ),
     ].join('\n');
   }
 }

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

@@ -35,26 +35,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

@@ -9,6 +9,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 +24,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 +42,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 +59,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

@@ -11,6 +11,7 @@ export interface MismatchPair {
   readonly expected: string;
   readonly actual: string;
   readonly location: string;
+  readonly nextAction?: string;
 }
 
 export interface ConsistencyReportProps {
@@ -49,7 +50,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 ?? '設計文書間のレイヤー依存方向を統一してください',
     }));
   }
 }

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

@@ -0,0 +1,50 @@
+/**
+ * @layer domain
+ * @unit validator-system
+ * @work-item-id WI-139
+ */
+
+export type SemanticDriftKind =
+  | 'design-behavior-missing-code'
+  | 'design-behavior-missing-test'
+  | 'code-behavior-missing-design'
+  | 'code-behavior-missing-test'
+  | 'test-observation-missing-design';
+
+export interface SemanticDriftReportProps {
+  readonly kind: SemanticDriftKind;
+  readonly behaviorId: string;
+  readonly unitName: string;
+  readonly severity: 'warning' | 'error';
+  readonly location?: string;
+  readonly nextAction: string;
+}
+
+export class SemanticDriftReport {
+  readonly kind: SemanticDriftKind;
+  readonly behaviorId: string;
+  readonly unitName: string;
+  readonly severity: 'warning' | 'error';
+  readonly location: string | null;
+  readonly nextAction: string;
+
+  private constructor(props: SemanticDriftReportProps) {
+    this.kind = props.kind;
+    this.behaviorId = props.behaviorId;
+    this.unitName = props.unitName;
+    this.severity = props.severity;
+    this.location = props.location ?? null;
+    this.nextAction = props.nextAction;
+    Object.freeze(this);
+  }
+
+  static create(props: SemanticDriftReportProps): SemanticDriftReport {
+    if (props.behaviorId.trim().length === 0) {
+      throw new Error('behaviorId is required for semantic drift reports');
+    }
+    if (props.unitName.trim().length === 0) {
+      throw new Error('unitName is required for semantic drift reports');
+    }
+    return new SemanticDriftReport(props);
+  }
+}

package/scripts/harness/validator-system/index.ts

@@ -18,6 +18,7 @@ export { LayerConfig } from './domain/value-objects/layer-config.js';
 export { DriftReport } from './domain/value-objects/drift-report.js';
 export { ConsistencyReport } from './domain/value-objects/consistency-report.js';
 export { DeadCodeReport } from './domain/value-objects/dead-code-report.js';
+export { SemanticDriftReport } from './domain/value-objects/semantic-drift-report.js';
 
 // --- Domain Services ---
 export { ValidatorRegistry, UnknownValidatorError } from './domain/services/validator-registry.js';
@@ -25,6 +26,7 @@ export { ValidatorExecutionService, ValidatorExecutionError } from './domain/ser
 export { DriftDetectionService } from './domain/services/l4/drift-detection-service.js';
 export { ConsistencyCheckService } from './domain/services/l4/consistency-check-service.js';
 export { DeadCodeDetectionService } from './domain/services/l4/dead-code-detection-service.js';
+export { SemanticDriftService } from './domain/services/l4/semantic-drift-service.js';
 
 // --- Application DTOs ---
 export type { ValidationResultContract } from './application/dto/validation-result-contract.js';