phasegate 0.150.2 → 0.151.1

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.151.1] - 2026-05-12
+
+### Fixed
+
+- **G4 post-publish dogfood** — fixes `npx phasegate@0.151.0` failing with `Error: tsx not found` by letting the bin wrapper execute the packaged `tsx` loader via `node --import` when dependency binaries are not linked into PATH.
+
+## [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

package/bin/phasegate

@@ -7,8 +7,13 @@ SCRIPT_PATH="$(realpath "$0" 2>/dev/null || readlink -f "$0" 2>/dev/null || echo
 PACKAGE_DIR="$(cd "$(dirname "$SCRIPT_PATH")/.." && pwd)"
 MAIN_TS="$PACKAGE_DIR/scripts/harness/main.ts"
 
-# tsx を探す: npx経由の場合はnode_modules/.binがPATHに入っているので command -v で見つかる
-if command -v tsx >/dev/null 2>&1; then
+# tsx を探す。npm/npx の一時インストールでは dependency bin が PATH や ../.bin に
+# 出ないことがあるため、tsx loader を直接 node --import できる経路も見る。
+if [ -f "$PACKAGE_DIR/node_modules/tsx/dist/loader.mjs" ]; then
+  exec node --import "$PACKAGE_DIR/node_modules/tsx/dist/loader.mjs" "$MAIN_TS" "$@"
+elif [ -f "$PACKAGE_DIR/../tsx/dist/loader.mjs" ]; then
+  exec node --import "$PACKAGE_DIR/../tsx/dist/loader.mjs" "$MAIN_TS" "$@"
+elif command -v tsx >/dev/null 2>&1; then
   exec tsx "$MAIN_TS" "$@"
 elif [ -f "$PACKAGE_DIR/node_modules/.bin/tsx" ]; then
   exec "$PACKAGE_DIR/node_modules/.bin/tsx" "$MAIN_TS" "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.150.2",
+  "version": "0.151.1",
   "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';
 

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

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

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

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

@@ -1,6 +1,7 @@
 /**
  * @layer domain
  * @unit phase2-extensions
+ * @work-item-id WI-122
  */
 import { Phase2ExtensionsDomainError } from '../errors/phase2-extensions-domain-error.js';
 

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

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

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>;
+}

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）

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）

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専用）

package/scripts/harness/validator-system/domain/value-objects/contract-traceability-model.ts

@@ -0,0 +1,124 @@
+// @unit validator-system
+// @layer domain
+// @work-item-id WI-132 / WI-133 / WI-136 / WI-137 / WI-138
+
+export type PublicContractKind =
+  | 'cli-command'
+  | 'api-endpoint'
+  | 'port'
+  | 'config-option'
+  | 'domain-behavior'
+  | 'error-code';
+
+export type BoundaryCaseKind =
+  | 'empty-input'
+  | 'missing-required'
+  | 'invalid-enum'
+  | 'duplicate-id'
+  | 'unknown-reference'
+  | 'permission-denied'
+  | 'config-disabled'
+  | 'partial-failure'
+  | 'idempotency'
+  | 'backward-compatibility';
+
+export interface PublicContract {
+  readonly id: string;
+  readonly kind: PublicContractKind;
+  readonly sourcePath: string;
+  readonly requiredBehaviors: readonly string[];
+  readonly boundaryCases?: readonly BoundaryCaseKind[];
+}
+
+export interface TestObservation {
+  readonly id: string;
+  readonly kind: 'unit' | 'integration' | 'e2e' | 'adapter-contract';
+  readonly sourcePath: string;
+  readonly covers: readonly string[];
+}
+
+export interface ErrorContract {
+  readonly id: string;
+  readonly sourcePath: string;
+  readonly code?: string;
+  readonly severity?: 'error' | 'warning';
+  readonly message?: string;
+  readonly suggestion?: string;
+  readonly documentationRef?: string;
+  readonly exitCode?: number;
+  readonly machineFields?: readonly string[];
+}
+
+export interface StateTransition {
+  readonly from: string;
+  readonly to: string;
+  readonly guard?: string;
+}
+
+export interface StateMachineModel {
+  readonly id: string;
+  readonly sourcePath: string;
+  readonly docsStates: readonly string[];
+  readonly codeStates: readonly string[];
+  readonly transitions: readonly StateTransition[];
+  readonly terminalStates: readonly string[];
+  readonly invalidTransitions: readonly StateTransition[];
+}
+
+export interface TraceabilityGraphSlice {
+  readonly workItemId: string;
+  readonly affectedUnits: readonly string[];
+  readonly productUnits: readonly string[];
+  readonly implementationWorkItemIds: readonly string[];
+  readonly testWorkItemIds: readonly string[];
+  readonly publicDocsChanged: boolean;
+  readonly contractChanged: boolean;
+}
+
+export interface ContractTraceabilityInput {
+  readonly publicContracts: readonly PublicContract[];
+  readonly testObservations: readonly TestObservation[];
+  readonly errorContracts: readonly ErrorContract[];
+  readonly stateMachines: readonly StateMachineModel[];
+  readonly traceabilitySlices: readonly TraceabilityGraphSlice[];
+}
+
+export type ContractTraceabilityFindingKind =
+  | 'missing-required-behavior-test'
+  | 'missing-port-contract-test'
+  | 'missing-boundary-test'
+  | 'error-contract-shape'
+  | 'error-contract-exit-code'
+  | 'missing-error-path-test'
+  | 'state-doc-code-mismatch'
+  | 'state-invalid-terminal-transition'
+  | 'missing-transition-test'
+  | 'traceability-unit-mismatch'
+  | 'traceability-test-mismatch'
+  | 'public-doc-contract-sync';
+
+export interface ContractTraceabilityFinding {
+  readonly kind: ContractTraceabilityFindingKind;
+  readonly severity: 'error' | 'warning';
+  readonly subject: string;
+  readonly sourcePath: string;
+  readonly message: string;
+  readonly suggestion: string;
+}
+
+export class ContractTraceabilityReport {
+  readonly findings: readonly ContractTraceabilityFinding[];
+
+  private constructor(findings: readonly ContractTraceabilityFinding[]) {
+    this.findings = Object.freeze([...findings]);
+    Object.freeze(this);
+  }
+
+  static create(findings: readonly ContractTraceabilityFinding[]): ContractTraceabilityReport {
+    return new ContractTraceabilityReport(findings);
+  }
+
+  hasFindings(): boolean {
+    return this.findings.length > 0;
+  }
+}

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

@@ -7,6 +7,7 @@
  * L1-001〜L4-005 のバリデータを識別する不変値オブジェクト
  * Wave 2A で L1-017, L1-018, L2-013 を追加
  * WI-140 で L2-014 を追加
+ * WI-132/WI-133/WI-136/WI-137/WI-138 で L2-015 を追加
  */
 
 export class InvalidValidatorIdError extends Error {
@@ -29,6 +30,7 @@ const VALIDATOR_NAME_MAP: Record<string, string> = {
   'L2-003': 'test-quality',
   'L2-013': 'cli-e2e-test-existence',
   'L2-014': 'work-item-status-staleness',
+  'L2-015': 'contract-traceability-coverage',
   'L3-001': 'security',
   'L3-002': 'performance',
   'L3-003': 'coverage',

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

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit validator-system
+ * @work-item-id WI-117
  *
  * BiomeAstSourceCodeAnalyzerAdapter — SourceCodeAnalyzerPort実装
  * TypeScript Compiler API を使用してエクスポートを正確に抽出する（L4-001, L4-003）

package/scripts/harness/validator-system/infrastructure/adapters/file-system-contract-traceability-policy-adapter.ts

@@ -0,0 +1,115 @@
+// @unit validator-system
+// @layer infrastructure
+// @work-item-id WI-132 / WI-133 / WI-136 / WI-137 / WI-138
+
+import { readFile } from 'node:fs/promises';
+import type { ContractTraceabilityPolicyPort } from '../../domain/ports/contract-traceability-policy-port.js';
+import type {
+  BoundaryCaseKind,
+  ContractTraceabilityInput,
+  PublicContract,
+  PublicContractKind,
+  TestObservation,
+} from '../../domain/value-objects/contract-traceability-model.js';
+
+const CONTRACT_KINDS = new Set<PublicContractKind>([
+  'cli-command',
+  'api-endpoint',
+  'port',
+  'config-option',
+  'domain-behavior',
+  'error-code',
+]);
+
+const BOUNDARY_KINDS = new Set<BoundaryCaseKind>([
+  'empty-input',
+  'missing-required',
+  'invalid-enum',
+  'duplicate-id',
+  'unknown-reference',
+  'permission-denied',
+  'config-disabled',
+  'partial-failure',
+  'idempotency',
+  'backward-compatibility',
+]);
+
+export class FileSystemContractTraceabilityPolicyAdapter implements ContractTraceabilityPolicyPort {
+  async collect(targetPaths: readonly string[]): Promise<ContractTraceabilityInput> {
+    const publicContracts: PublicContract[] = [];
+    const testObservations: TestObservation[] = [];
+
+    for (const targetPath of targetPaths) {
+      let content: string;
+      try {
+        content = await readFile(targetPath, 'utf-8');
+      } catch {
+        continue;
+      }
+
+      publicContracts.push(...this.extractContracts(targetPath, content));
+      testObservations.push(...this.extractObservations(targetPath, content));
+    }
+
+    return {
+      publicContracts,
+      testObservations,
+      errorContracts: [],
+      stateMachines: [],
+      traceabilitySlices: [],
+    };
+  }
+
+  private extractContracts(sourcePath: string, content: string): readonly PublicContract[] {
+    return [...content.matchAll(/@phasegate-contract\s+([^\n\r*]+)/g)].flatMap((match) => {
+      const attrs = this.parseAttrs(match[1]);
+      const id = attrs.get('id');
+      const kind = attrs.get('kind');
+      if (!id || !this.isContractKind(kind)) return [];
+
+      return [{
+        id,
+        kind,
+        sourcePath,
+        requiredBehaviors: this.splitList(attrs.get('behaviors')),
+        boundaryCases: this.splitList(attrs.get('boundary')).filter(this.isBoundaryKind),
+      }];
+    });
+  }
+
+  private extractObservations(sourcePath: string, content: string): readonly TestObservation[] {
+    return [...content.matchAll(/@phasegate-observation\s+([^\n\r*]+)/g)].flatMap((match, index) => {
+      const attrs = this.parseAttrs(match[1]);
+      const covers = this.splitList(attrs.get('covers'));
+      if (covers.length === 0) return [];
+      const kind = attrs.get('kind');
+      return [{
+        id: attrs.get('id') ?? `${sourcePath}#observation-${index + 1}`,
+        kind: kind === 'adapter-contract' || kind === 'integration' || kind === 'e2e' ? kind : 'unit',
+        sourcePath,
+        covers,
+      }];
+    });
+  }
+
+  private parseAttrs(raw: string): Map<string, string> {
+    const attrs = new Map<string, string>();
+    for (const match of raw.matchAll(/([a-zA-Z][a-zA-Z0-9_-]*)=("[^"]*"|'[^']*'|[^\s]+)/g)) {
+      attrs.set(match[1], match[2].replace(/^['"]|['"]$/g, ''));
+    }
+    return attrs;
+  }
+
+  private splitList(raw: string | undefined): string[] {
+    if (!raw) return [];
+    return raw.split(',').map((value) => value.trim()).filter((value) => value.length > 0);
+  }
+
+  private isContractKind(value: string | undefined): value is PublicContractKind {
+    return value !== undefined && CONTRACT_KINDS.has(value as PublicContractKind);
+  }
+
+  private isBoundaryKind(value: string): value is BoundaryCaseKind {
+    return BOUNDARY_KINDS.has(value as BoundaryCaseKind);
+  }
+}

package/scripts/harness/validator-system/infrastructure/adapters/harness-config-validator-config-adapter.ts

@@ -38,7 +38,7 @@ export class HarnessConfigValidatorConfigAdapter implements ValidatorConfigPort
     const layerData = this.config.layers?.[layer] ?? {};
 
     const defaultValidators: Record<string, string[]> = {
-      L2: ['L2-001', 'L2-002', 'L2-003', 'L2-013', 'L2-014'],
+      L2: ['L2-001', 'L2-002', 'L2-003', 'L2-013', 'L2-014', 'L2-015'],
       L3: ['L3-001', 'L3-002', 'L3-003', 'L3-004'],
       L4: ['L4-001', 'L4-002', 'L4-003', 'L4-004', 'L4-005'],
     };

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

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit validator-system
+ * @work-item-id WI-117, WI-118
  *
  * MarkdownDesignDocumentAdapter — DesignDocumentPort実装
  */