phasegate 0.150.1 → 0.151.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.151.0] - 2026-05-12
+
+### Added
+
+- **G4 / WI-132 / WI-133 / WI-136 / WI-137 / WI-138 — contract, boundary, state machine, error contract, and traceability coverage** — adds `L2-015 contract-traceability-coverage`, a semantic model for public contracts, test observations, boundary cases, state machines, error contracts, and traceability graph slices, plus opt-in `@phasegate-contract` / `@phasegate-observation` extraction and L2 result mapping.
+
+## [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.151.0",
   "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/config-foundation/application/mappers/validator-system-config-mapper.ts

@@ -11,7 +11,7 @@ export function toValidatorSystemConfig(resolvedConfig: HarnessConfigV2 | undefi
   return {
     project: { preset: resolvedConfig.project.preset },
     layers: {
-      L2: { enabled: resolvedConfig.layers.L2.enabled, validators: ['L2-001', 'L2-002', 'L2-003', 'L2-013', 'L2-014'] },
+      L2: { enabled: resolvedConfig.layers.L2.enabled, validators: ['L2-001', 'L2-002', 'L2-003', 'L2-013', 'L2-014', 'L2-015'] },
       L3: { enabled: resolvedConfig.layers.L3.enabled },
       L4: { enabled: resolvedConfig.layers.L4.enabled, validators: resolvedConfig.layers.L4.validators },
     },

package/scripts/harness/harness-api/domain/value-objects/harness-status-summary.ts

@@ -1,4 +1,5 @@
 // @layer domain
+// @unit harness-api
 // harness-status-summary.ts — HarnessStatusSummary Value Object
 
 import type { LayerHealth, LayerId } from './layer-health.js';

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

@@ -1,6 +1,7 @@
 /**
  * @layer application
  * @unit phase2-extensions
+ * @work-item-id WI-122
  */
 import type { HarnessErrorContract } from '../../../harness-error/application/dto/harness-error-contract.js';
 
@@ -8,8 +9,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

@@ -1,6 +1,7 @@
 /**
  * @layer application
  * @unit phase2-extensions
+ * @work-item-id WI-122
  */
 import type { FreshnessConfigPort } from '../../domain/ports/freshness-config-port.js';
 import type { DocumentScannerPort } from '../../domain/ports/document-scanner-port.js';
@@ -35,6 +36,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 +47,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 +61,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 +80,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 +108,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

@@ -1,6 +1,7 @@
 /**
  * @layer domain
  * @unit phase2-extensions
+ * @work-item-id WI-122
  */
 import { Phase2ExtensionsDomainError } from '../errors/phase2-extensions-domain-error.js';
 
@@ -8,17 +9,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 +42,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

@@ -1,6 +1,7 @@
 /**
  * @layer domain
  * @unit phase2-extensions
+ * @work-item-id WI-122
  */
 import type { DocFreshnessRule } from '../aggregates/doc-freshness-rule.js';
 import type { DocumentAge, DocumentAgeSource } from '../value-objects/document-age.js';
@@ -10,8 +11,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 +25,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 +44,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

@@ -1,10 +1,11 @@
 /**
  * @layer domain
  * @unit phase2-extensions
+ * @work-item-id WI-122
  */
 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 +26,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

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit phase2-extensions
+ * @work-item-id WI-122
  */
 import type { HarnessConfigV2 } from '../../../config-foundation/domain/harness-config.js';
 import { DocFreshnessRule } from '../../domain/aggregates/doc-freshness-rule.js';
@@ -25,6 +26,8 @@ type Phase2RuleConfig = {
       ruleId: string;
       documentPattern: string;
       failOnBroken?: boolean;
+      owner?: string;
+      pointerPolicies?: Record<string, 'fail' | 'warn' | 'skip'>;
     }>;
   };
 };
@@ -73,6 +76,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 +93,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

@@ -1,6 +1,7 @@
 /**
  * @layer presentation
  * @unit phase2-extensions
+ * @work-item-id WI-122
  */
 import type { ValidateDocPointersOutput } from '../../application/dto/validate-doc-pointers-output.js';
 
@@ -12,7 +13,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/application/use-cases/run-l2-validators-usecase.ts

@@ -3,7 +3,7 @@
  * @unit validator-system
  *
  * RunL2ValidatorsUseCase — H08-01: L2バリデータ実行
- * @work-item-id WI-110 / WI-111 / WI-140
+ * @work-item-id WI-110 / WI-111 / WI-140 / WI-132 / WI-133 / WI-136 / WI-137 / WI-138
  */
 import { readFile } from 'node:fs/promises';
 import { ValidatorId, InvalidValidatorIdError } from '../../domain/value-objects/validator-id.js';
@@ -21,6 +21,8 @@ import type { CliCommandRegistryPort } from '../../domain/ports/cli-command-regi
 import type { E2eTestFileRegistryPort } from '../../domain/ports/e2e-test-file-registry-port.js';
 import { CliE2eTestExistenceService } from '../../domain/services/cli-e2e-test-existence-service.js';
 import type { WorkItemStatusPolicyPort } from '../../domain/ports/work-item-status-policy-port.js';
+import type { ContractTraceabilityPolicyPort } from '../../domain/ports/contract-traceability-policy-port.js';
+import { ContractTraceabilityCoverageService } from '../../domain/services/contract-traceability-coverage-service.js';
 
 export interface RunL2ValidatorsUseCaseDeps {
   validatorRegistry: ValidatorRegistry;
@@ -33,6 +35,7 @@ export interface RunL2ValidatorsUseCaseDeps {
   cliCommandRegistryPort?: CliCommandRegistryPort;
   e2eTestFileRegistryPort?: E2eTestFileRegistryPort;
   workItemStatusPolicyPort?: WorkItemStatusPolicyPort;
+  contractTraceabilityPolicyPort?: ContractTraceabilityPolicyPort;
 }
 
 export class RunL2ValidatorsUseCase {
@@ -46,7 +49,9 @@ export class RunL2ValidatorsUseCase {
   private readonly cliCommandRegistryPort?: CliCommandRegistryPort;
   private readonly e2eTestFileRegistryPort?: E2eTestFileRegistryPort;
   private readonly workItemStatusPolicyPort?: WorkItemStatusPolicyPort;
+  private readonly contractTraceabilityPolicyPort?: ContractTraceabilityPolicyPort;
   private readonly cliE2eTestExistenceService = new CliE2eTestExistenceService();
+  private readonly contractTraceabilityCoverageService = new ContractTraceabilityCoverageService();
 
   constructor(deps: RunL2ValidatorsUseCaseDeps) {
     this.registry = deps.validatorRegistry;
@@ -59,6 +64,7 @@ export class RunL2ValidatorsUseCase {
     this.cliCommandRegistryPort = deps.cliCommandRegistryPort;
     this.e2eTestFileRegistryPort = deps.e2eTestFileRegistryPort;
     this.workItemStatusPolicyPort = deps.workItemStatusPolicyPort;
+    this.contractTraceabilityPolicyPort = deps.contractTraceabilityPolicyPort;
   }
 
   async execute(input: RunL2ValidatorsInput): Promise<readonly ValidationResultContract[]> {
@@ -180,6 +186,28 @@ export class RunL2ValidatorsUseCase {
       }
     }
 
+    if (this.contractTraceabilityPolicyPort) {
+      const l2015Result = overrideMap.get('L2-015');
+      if (l2015Result && !l2015Result.skipped) {
+        const inputModel = await this.contractTraceabilityPolicyPort.collect(input.targetPaths);
+        const report = this.contractTraceabilityCoverageService.check(inputModel);
+        if (report.hasFindings()) {
+          const errors = report.findings.map((finding) => ({
+            code: { value: 'L2-015', toString: () => 'L2-015' },
+            severity: { value: finding.severity, toString: () => finding.severity },
+            message: finding.message,
+            suggestion: finding.suggestion,
+            kind: finding.kind,
+            subject: finding.subject,
+            sourcePath: finding.sourcePath,
+          }));
+          overrideMap.set('L2-015', ValidationResult.fail(ValidatorId.create('L2-015'), errors, 0));
+        } else {
+          overrideMap.set('L2-015', ValidationResult.pass(ValidatorId.create('L2-015'), 0));
+        }
+      }
+    }
+
     const finalResults = definitions.map(
       (definition) => overrideMap.get(definition.validatorId.value) ?? ValidationResult.skip(definition.validatorId),
     );

package/scripts/harness/validator-system/composition-root.ts

@@ -3,7 +3,7 @@
  * @unit validator-system
  *
  * DI 組み立て — validator-system の全依存関係を構築する
- * @work-item-id WI-110 / WI-111
+ * @work-item-id WI-110 / WI-111 / WI-132 / WI-133 / WI-136 / WI-137 / WI-138
  */
 import { ValidatorId } from './domain/value-objects/validator-id.js';
 import { ValidatorDefinition } from './domain/value-objects/validator-definition.js';
@@ -24,6 +24,7 @@ import { SourceFileTextScannerAdapter } from './infrastructure/adapters/source-f
 import { E2eTestFileRegistryAdapter } from './infrastructure/adapters/e2e-test-file-registry-adapter.js';
 import { CliCommandRegistryAdapter } from './infrastructure/adapters/cli-command-registry-adapter.js';
 import { TraceabilityWorkItemStatusPolicyAdapter } from './infrastructure/adapters/traceability-work-item-status-policy-adapter.js';
+import { FileSystemContractTraceabilityPolicyAdapter } from './infrastructure/adapters/file-system-contract-traceability-policy-adapter.js';
 import { PhaseDependencyPhaseGatePolicyAdapter } from './infrastructure/adapters/phase-dependency-phase-gate-policy-adapter.js';
 import { TraceabilityMetadataPolicyAdapter } from './infrastructure/adapters/traceability-metadata-policy-adapter.js';
 import { NyquistAcCoveragePolicyAdapter } from './infrastructure/adapters/nyquist-ac-coverage-policy-adapter.js';
@@ -47,7 +48,7 @@ import { join } from 'node:path';
 const DEFAULT_CONFIG = {
   preset: 'standard' as const,
   layers: {
-    L2: { enabled: true, validators: ['L2-001', 'L2-002', 'L2-003', 'L2-013', 'L2-014'] },
+    L2: { enabled: true, validators: ['L2-001', 'L2-002', 'L2-003', 'L2-013', 'L2-014', 'L2-015'] },
     L3: { enabled: true, validators: ['L3-001', 'L3-002', 'L3-003', 'L3-004'], coverageThreshold: 90, bundleSizeLimit: 512000 },
     L4: { enabled: true, validators: ['L4-001', 'L4-002', 'L4-003', 'L4-004', 'L4-005'] },
   },
@@ -81,6 +82,7 @@ export function buildDefaultRegistry(): ValidatorRegistry {
     createDef('L2-003', 'L2', 'always'),
     createDef('L2-013', 'L2', 'always', 'CliE2eTestExistenceService'),
     createDef('L2-014', 'L2', 'always', 'WorkItemStatusPolicyPort'),
+    createDef('L2-015', 'L2', 'always', 'ContractTraceabilityPolicyPort'),
     createDef('L3-001', 'L3', 'always'),
     createDef('L3-002', 'L3', 'strictOnly'),
     createDef('L3-003', 'L3', 'always'),
@@ -127,6 +129,7 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
   const securityScannerPort = new FileSystemSecurityPatternScannerAdapter();
   const performanceScannerPort = new AstPerformanceScannerAdapter();
   const workItemStatusPolicyPort = new TraceabilityWorkItemStatusPolicyAdapter(process.cwd());
+  const contractTraceabilityPolicyPort = new FileSystemContractTraceabilityPolicyAdapter();
 
   const docsRoot = join(process.cwd(), 'docs/product/construction');
   const cwd = process.cwd();
@@ -151,6 +154,7 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
     e2eTestFileRegistryPort,
     cliCommandRegistryPort,
     workItemStatusPolicyPort,
+    contractTraceabilityPolicyPort,
   });
 
   const runL3ValidatorsUseCase = new RunL3ValidatorsUseCase({

package/scripts/harness/validator-system/domain/ports/contract-traceability-policy-port.ts

@@ -0,0 +1,9 @@
+// @unit validator-system
+// @layer domain
+// @work-item-id WI-132 / WI-133 / WI-136 / WI-137 / WI-138
+
+import type { ContractTraceabilityInput } from '../value-objects/contract-traceability-model.js';
+
+export interface ContractTraceabilityPolicyPort {
+  collect(targetPaths: readonly string[]): Promise<ContractTraceabilityInput>;
+}