phasegate 0.150.1 → 0.150.2

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.150.2] - 2026-05-12
+
+### Added
+
+- **G3 / WI-117 / WI-118 / WI-122 / WI-139 — L4 drift, consistency, docs, and semantic drift semantics** — L4 drift detection now compares unit-scoped records, prefers `@unit` metadata, handles product construction docs and re-export/default export surfaces more precisely, reports real product-doc consistency targets, adds operational pointer/freshness semantics, and introduces semantic drift reports across design intent, implementation behavior, and test observations.
+
 ## [0.150.1] - 2026-05-12
 
 ### Fixed

package/docs/guide/layer-model.md

@@ -253,3 +253,7 @@ Presets control which layers are active. Choose based on project maturity and te
 - **strict** — Full defense. Enables scheduled drift detection (L4). Runtime L0 hooks are configured through the agent and Husky hook files, not through validator presets.
 
 Presets are configured in `phasegate.config.json`, the single source of truth for all quality settings.
+<!-- @work-item-id WI-117, WI-118, WI-122, WI-139 -->
+## G3 L4 Advisory Preconditions
+
+L4 drift / consistency / docs semantic findings are advisory by default. Use fail-on-warning only when reports include Unit-scoped drift keys, real product-doc consistency targets, pointer/freshness owner and policy metadata, and semantic drift behavior coverage. This avoids treating parser limitations as blocking quality gates.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.150.1",
+  "version": "0.150.2",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",

package/scripts/harness/phase2-extensions/application/dto/validate-doc-pointers-output.ts

@@ -8,8 +8,12 @@ export interface PointerValidationResultDto {
   documentPath: string;
   pointerTarget: string;
   pointerType: 'file-path' | 'url';
+  semanticPointerType: 'reference' | 'implementation' | 'adr' | 'product-doc' | 'external-url';
+  owner: string;
+  severity: 'fail' | 'warn' | 'skip';
   isResolvable: boolean;
   errorMessage: string | null;
+  nextAction: string;
 }
 
 export interface ValidateDocPointersOutput {

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';

package/scripts/harness/validator-system/infrastructure/adapters/biome-ast-source-code-analyzer-adapter.ts

@@ -7,6 +7,7 @@
  */
 import * as ts from 'typescript';
 import type { SourceCodeAnalyzerPort, SourceAnalysisResult } from '../../domain/ports/source-code-analyzer-port.js';
+import type { DriftElementRecord } from '../../domain/services/l4/drift-detection-service.js';
 import { readdir } from 'node:fs/promises';
 import { basename, join, relative, sep } from 'node:path';
 
@@ -44,7 +45,7 @@ export class BiomeAstSourceCodeAnalyzerAdapter implements SourceCodeAnalyzerPort
       const sourceFile = program.getSourceFile(filePath);
       if (!sourceFile) continue;
       results.push({
-        unitName: resolveUnitName(this.sourceRoot, filePath),
+        unitName: resolveUnitName(this.sourceRoot, filePath, sourceFile.text),
         filePath,
         exports: extractExports(sourceFile),
         imports: extractImports(sourceFile),
@@ -86,6 +87,17 @@ export class BiomeAstSourceCodeAnalyzerAdapter implements SourceCodeAnalyzerPort
     }
     return map;
   }
+
+  async getElementRecords(targetUnits?: readonly string[]): Promise<readonly DriftElementRecord[]> {
+    const results = await this.analyzeExports(targetUnits);
+    return results.flatMap((result) =>
+      result.exports.map((entry) => ({
+        element: entry.name,
+        unitName: result.unitName,
+        filePaths: [result.filePath],
+      }))
+    );
+  }
 }
 
 type ExportType = SourceAnalysisResult['exports'][number]['type'];
@@ -112,6 +124,19 @@ function extractExports(sourceFile: ts.SourceFile): SourceAnalysisResult['export
           exports.push({ name: decl.name.text, type: 'const' });
         }
       }
+    } else if (ts.isExportDeclaration(node) && node.exportClause) {
+      if (ts.isNamedExports(node.exportClause)) {
+        for (const element of node.exportClause.elements) {
+          exports.push({ name: element.name.text, type: 'type' });
+        }
+      }
+    } else if (ts.isExportDeclaration(node) && !node.exportClause && ts.isStringLiteral(node.moduleSpecifier)) {
+      exports.push({ name: `* from ${node.moduleSpecifier.text}`, type: 'type' });
+    }
+
+    const hasDefault = modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword) ?? false;
+    if (hasDefault) {
+      exports.push({ name: 'default', type: 'type' });
     }
   });
 
@@ -182,7 +207,10 @@ async function walkTsFiles(root: string, excludePattern: RegExp): Promise<string
   }
 }
 
-function resolveUnitName(sourceRoot: string, filePath: string): string {
+function resolveUnitName(sourceRoot: string, filePath: string, sourceText: string): string {
+  const unitMatch = /@unit\s+([a-z0-9-]+)/i.exec(sourceText);
+  if (unitMatch) return unitMatch[1];
+
   const relativePath = relative(sourceRoot, filePath);
   const [firstSegment] = relativePath.split(sep);
   return firstSegment || basename(filePath);

package/scripts/harness/validator-system/infrastructure/adapters/markdown-design-document-adapter.ts

@@ -5,10 +5,20 @@
  * MarkdownDesignDocumentAdapter — DesignDocumentPort実装
  */
 import type { DesignDocumentPort, StructuredDesignDoc } from '../../domain/ports/design-document-port.js';
+import type { DriftElementRecord } from '../../domain/services/l4/drift-detection-service.js';
 import { readFile, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 
 const ADR_PATTERN = /ADR-\d{3}/g;
+const WORK_ITEM_PATTERN = /@work-item-id\s+(WI-\d{3})/g;
+const LAYER_PATTERN = /@layer\s+([a-z0-9-]+)/gi;
+const UNIT_PATTERN = /@unit\s+([a-z0-9-]+)/gi;
+const CONSTRUCTION_DOC_NAMES = [
+  'domain_model.md',
+  'logical_design.md',
+  'unit_test_design.md',
+  'it_test_design.md',
+];
 
 // ISSUE-005 P3-8: メタ見出し / 議論用セクションを drift 対象から除外するマーカー。
 // 見出し行の直後 (同一行末 or 次の非空行) に置かれたコメントを拾う。
@@ -111,26 +121,28 @@ export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
     const results: StructuredDesignDoc[] = [];
 
     for (const unitName of unitNames) {
-      const docPath = join(this.docsRoot, unitName, 'domain_model.md');
-      const cached = this.cache.get(docPath);
-      if (cached) {
-        results.push(cached);
-        continue;
-      }
+      for (const docName of CONSTRUCTION_DOC_NAMES) {
+        const docPath = join(this.docsRoot, unitName, docName);
+        const cached = this.cache.get(docPath);
+        if (cached) {
+          results.push(cached);
+          continue;
+        }
 
-      try {
-        const markdown = await readFile(docPath, 'utf8');
-        const doc: StructuredDesignDoc = {
-          unitName,
-          docPath,
-          concepts: extractConcepts(markdown).map((concept) => ({ ...concept, type: 'class' })),
-          layerDependencies: [],
-          adrRefs: Array.from(new Set(markdown.match(ADR_PATTERN) ?? [])),
-        };
-        this.cache.set(docPath, doc);
-        results.push(doc);
-      } catch {
-        continue;
+        try {
+          const markdown = await readFile(docPath, 'utf8');
+          const doc: StructuredDesignDoc = {
+            unitName,
+            docPath,
+            concepts: extractConcepts(markdown).map((concept) => ({ ...concept, type: 'class' })),
+            layerDependencies: extractLayerDependencies(markdown),
+            adrRefs: Array.from(new Set(markdown.match(ADR_PATTERN) ?? [])),
+          };
+          this.cache.set(docPath, doc);
+          results.push(doc);
+        } catch {
+          continue;
+        }
       }
     }
 
@@ -138,7 +150,32 @@ export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
   }
 
   async getLayerAnnotations(targetDocs?: readonly string[]): Promise<Record<string, string>> {
-    return {};
+    const docs = targetDocs && targetDocs.length > 0
+      ? await this.loadExplicitDocs(targetDocs)
+      : await this.loadDesignDocuments();
+    const annotations: Record<string, string> = {};
+
+    for (const doc of docs) {
+      const markdown = await readFile(doc.docPath, 'utf8');
+      const layers = Array.from(new Set(Array.from(markdown.matchAll(LAYER_PATTERN)).map((match) => match[1])));
+      const units = Array.from(new Set(Array.from(markdown.matchAll(UNIT_PATTERN)).map((match) => match[1])));
+      const workItems = Array.from(new Set(Array.from(markdown.matchAll(WORK_ITEM_PATTERN)).map((match) => match[1])));
+
+      for (const layer of layers) {
+        annotations[`${doc.docPath}#layer:${layer}`] = isKnownLayer(layer) ? 'layer:known' : 'layer:unknown';
+      }
+      for (const unit of units) {
+        annotations[`${doc.docPath}#unit:${unit}`] = unit === doc.unitName ? 'unit:matched' : `unit:mismatch:${doc.unitName}`;
+      }
+      for (const adrRef of doc.adrRefs) {
+        annotations[adrRef] = 'adr:referenced';
+      }
+      for (const workItemId of workItems) {
+        annotations[`${doc.docPath}#work-item:${workItemId}`] = 'work-item:referenced';
+      }
+    }
+
+    return annotations;
   }
 
   async getElements(targetUnits?: readonly string[]): Promise<string[]> {
@@ -146,6 +183,17 @@ export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
     return docs.flatMap((doc) => doc.concepts.map((concept) => concept.name));
   }
 
+  async getElementRecords(targetUnits?: readonly string[]): Promise<readonly DriftElementRecord[]> {
+    const docs = await this.loadDesignDocuments(targetUnits);
+    return docs.flatMap((doc) =>
+      doc.concepts.map((concept) => ({
+        element: concept.name,
+        unitName: doc.unitName,
+        pointers: concept.pointers ?? [],
+      }))
+    );
+  }
+
   async getElementPointers(targetUnits?: readonly string[]): Promise<Record<string, readonly string[]>> {
     const docs = await this.loadDesignDocuments(targetUnits);
     const map: Record<string, readonly string[]> = {};
@@ -176,6 +224,26 @@ export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
     return map;
   }
 
+  private async loadExplicitDocs(targetDocs: readonly string[]): Promise<readonly StructuredDesignDoc[]> {
+    const docs: StructuredDesignDoc[] = [];
+    for (const docPath of targetDocs) {
+      try {
+        const markdown = await readFile(docPath, 'utf8');
+        const unitName = inferUnitNameFromDocPath(this.docsRoot, docPath);
+        docs.push({
+          unitName,
+          docPath,
+          concepts: extractConcepts(markdown).map((concept) => ({ ...concept, type: 'class' })),
+          layerDependencies: extractLayerDependencies(markdown),
+          adrRefs: Array.from(new Set(markdown.match(ADR_PATTERN) ?? [])),
+        });
+      } catch {
+        continue;
+      }
+    }
+    return docs;
+  }
+
   private async listUnitNames(): Promise<string[]> {
     try {
       const entries = await readdir(this.docsRoot, { withFileTypes: true });
@@ -185,3 +253,25 @@ export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
     }
   }
 }
+
+function extractLayerDependencies(markdown: string): Array<{ from: string; to: string }> {
+  const dependencies: Array<{ from: string; to: string }> = [];
+  const dependencyPattern = /([a-z0-9-]+)\s*(?:->|→)\s*([a-z0-9-]+)/gi;
+  for (const match of markdown.matchAll(dependencyPattern)) {
+    dependencies.push({ from: match[1], to: match[2] });
+  }
+  return dependencies;
+}
+
+function isKnownLayer(layer: string): boolean {
+  return ['domain', 'application', 'infrastructure', 'presentation', 'test'].includes(layer);
+}
+
+function inferUnitNameFromDocPath(docsRoot: string, docPath: string): string {
+  const normalizedRoot = docsRoot.replace(/\\/g, '/').replace(/\/+$/, '');
+  const normalizedPath = docPath.replace(/\\/g, '/');
+  const relativePath = normalizedPath.startsWith(`${normalizedRoot}/`)
+    ? normalizedPath.slice(normalizedRoot.length + 1)
+    : normalizedPath;
+  return relativePath.split('/')[0] || 'unknown';
+}