phasegate 0.167.0 → 0.172.0

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

@@ -29,6 +29,7 @@ import { FileSystemContractTraceabilityPolicyAdapter } from './infrastructure/ad
 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';
+import { NyquistAcBoundCoveragePolicyAdapter } from './infrastructure/adapters/nyquist-ac-bound-coverage-policy-adapter.js';
 import { JsonCoverageReportAdapter } from './infrastructure/adapters/json-coverage-report-adapter.js';
 import { BiomeAstTestQualityAnalyzerAdapter } from './infrastructure/adapters/biome-ast-test-quality-analyzer-adapter.js';
 import { FileSystemSecurityPatternScannerAdapter } from './infrastructure/adapters/file-system-security-pattern-scanner-adapter.js';
@@ -112,6 +113,9 @@ export function buildDefaultRegistry(): ValidatorRegistry {
     createDef('L3-002', 'L3', 'strictOnly'),
     createDef('L3-003', 'L3', 'always'),
     createDef('L3-004', 'L3', 'always', 'AcCoveragePolicyPort'),
+    // WI-227 / H16-03: L3-005 (ac-bound-coverage) は registry には登録するが
+    // default-OFF（DEFAULT_CONFIG.layers.L3.validators に含めない）。fail-closed / opt-in。
+    createDef('L3-005', 'L3', 'always', 'AcBoundCoveragePolicyPort'),
     createDef('L4-001', 'L4', 'always'),
     createDef('L4-002', 'L4', 'always'),
     createDef('L4-003', 'L4', 'strictOnly'),
@@ -154,6 +158,8 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
   const phaseGatePolicyPort = new PhaseDependencyPhaseGatePolicyAdapter();
   const metadataPolicyPort = new TraceabilityMetadataPolicyAdapter();
   const acCoveragePolicyPort = new NyquistAcCoveragePolicyAdapter();
+  // WI-227 / H16-03: L3-005 (ac-bound-coverage, fail-closed, default-OFF) 用の adapter。
+  const acBoundCoveragePolicyPort = new NyquistAcBoundCoveragePolicyAdapter();
   // L3-003: テストカバレッジレポート（vitest --coverage の json-summary 出力）を読み取る。
   // 未配線だと L3-003 は装飾的な pass になり 90% 閾値が形骸化するため必ず配線する。
   const coverageReportPort = new JsonCoverageReportAdapter(
@@ -193,15 +199,21 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
     contractTraceabilityPolicyPort,
   });
 
+  // WI-227 / H16-03: L3-005 のスコープ対象 story-id を config から取得（既定 []）。
+  const acBoundStories =
+    (configData.layers?.L3 as { acBoundStories?: readonly string[] } | undefined)?.acBoundStories ?? [];
+
   const runL3ValidatorsUseCase = new RunL3ValidatorsUseCase({
     validatorRegistry: registry,
     validatorExecutionService: executionService,
     validatorConfigPort: configPort,
     contractMapper,
     acCoveragePolicyPort,
+    acBoundCoveragePolicyPort,
     coverageReportPort,
     securityScannerPort,
     performanceScannerPort,
+    acBoundStories,
   });
 
   const markdownDesignDocumentPort = new MarkdownDesignDocumentAdapter(docsRoot);

package/scripts/harness/validator-system/domain/ports/ac-bound-coverage-policy-port.ts

@@ -0,0 +1,22 @@
+/**
+ * @layer domain
+ * @unit validator-system
+ * @work-item-id WI-227
+ *
+ * AcBoundCoveragePolicyPort — L3-005（AC-bound coverage, fail-closed, default-OFF）
+ *
+ * L3-004（story-level の AC 網羅ゲート）とは独立した per-AC binding ゲート。
+ * `acBoundStories`（スコープ）内の各 story について、全 linked AC が
+ * ≥1 の `binding:"ac"` テスト参照（fileFallbackOnly===0）を持つことを検査する。
+ */
+import type { HarnessErrorLike } from '../value-objects/validation-result.js';
+
+export interface AcBoundCoveragePolicyPort {
+  checkAcBoundCoverage(context: {
+    matrixFilePath?: string;
+    acBoundStories: readonly string[];
+  }): Promise<{
+    passed: boolean;
+    errors: readonly HarnessErrorLike[];
+  }>;
+}

package/scripts/harness/validator-system/domain/services/validator-execution-service.ts

@@ -5,7 +5,7 @@
  * ValidatorExecutionService ドメインサービス
  * 指定されたValidatorDefinition[]を順次実行し、ValidationResult[]を集約
  */
-import { ValidatorDefinition } from '../value-objects/validator-definition.js';
+import type { ValidatorDefinition } from '../value-objects/validator-definition.js';
 import { ValidationResult, type HarnessErrorLike } from '../value-objects/validation-result.js';
 import { LayerConfig } from '../value-objects/layer-config.js';
 import type { PhaseGatePolicyPort } from '../ports/phase-gate-policy-port.js';

package/scripts/harness/validator-system/domain/services/validator-registry.ts

@@ -5,8 +5,8 @@
  * ValidatorRegistry ドメインサービス
  * L2-L4バリデータ定義のカタログ管理と選択実行インターフェース
  */
-import { ValidatorId } from '../value-objects/validator-id.js';
-import { ValidatorDefinition } from '../value-objects/validator-definition.js';
+import type { ValidatorId } from '../value-objects/validator-id.js';
+import type { ValidatorDefinition } from '../value-objects/validator-definition.js';
 
 export class UnknownValidatorError extends Error {
   readonly validatorId: string;

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

@@ -5,7 +5,7 @@
  * LayerConfig 値オブジェクト
  * HarnessConfigV2から注入されるL2/L3/L4の実行設定VO
  */
-import { ValidatorId } from './validator-id.js';
+import type { ValidatorId } from './validator-id.js';
 
 export interface LayerConfigProps {
   readonly layer: 'L2' | 'L3' | 'L4';

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

@@ -5,7 +5,7 @@
  * ValidationResult 値オブジェクト
  * バリデータ実行結果のスナップショット（不変）
  */
-import { ValidatorId } from './validator-id.js';
+import type { ValidatorId } from './validator-id.js';
 
 /** HarnessError の最小互換型（harness-error Unit の HarnessError との疎結合） */
 export interface HarnessErrorLike {

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

@@ -5,8 +5,8 @@
  * ValidatorDefinition 値オブジェクト
  * 個々のバリデータの不変定義を保持する
  */
-import { ValidatorId } from './validator-id.js';
-import { ValidationRule } from './validation-rule.js';
+import type { ValidatorId } from './validator-id.js';
+import type { ValidationRule } from './validation-rule.js';
 
 export interface ValidatorDefinitionProps {
   readonly validatorId: ValidatorId;

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

@@ -10,6 +10,7 @@
  * WI-132/WI-133/WI-136/WI-137/WI-138 で L2-015 を追加
  * WI-156 で L4-006 を追加
  * WI-222 (HF2-05) で L4-007（ac-level-traceability, default-OFF advisory）を追加
+ * WI-227 (H16-03) で L3-005（ac-bound-coverage, default-OFF fail-closed）を追加
  */
 
 export class InvalidValidatorIdError extends Error {
@@ -37,6 +38,7 @@ const VALIDATOR_NAME_MAP: Record<string, string> = {
   'L3-002': 'performance',
   'L3-003': 'coverage',
   'L3-004': 'nyquist',
+  'L3-005': 'ac-bound-coverage',
   'L4-001': 'drift-detect',
   'L4-002': 'consistency-check',
   'L4-003': 'dead-code',

package/scripts/harness/validator-system/infrastructure/adapters/json-coverage-report-adapter.ts

@@ -33,7 +33,7 @@ export class JsonCoverageReportAdapter implements CoverageReportPort {
     }
 
     const data = JSON.parse(raw) as Record<string, { lines?: { pct?: number } }>;
-    const total = data['total'];
+    const total = data.total;
     const overallCoverage = total?.lines?.pct ?? 0;
 
     const perFileCoverage: { filePath: string; coverage: number }[] = [];

package/scripts/harness/validator-system/infrastructure/adapters/nyquist-ac-bound-coverage-policy-adapter.ts

@@ -0,0 +1,118 @@
+/**
+ * @layer infrastructure
+ * @unit validator-system
+ * @work-item-id WI-227
+ *
+ * NyquistAcBoundCoveragePolicyAdapter — AcBoundCoveragePolicyPort 実装（L3-005）
+ *
+ * FAIL-CLOSED: matrix の不在・parse 不能・例外はいずれも passed=false（不合格）として扱う。
+ * L4-007（advisory / fail-open）とは対照的に、L3-005 は CI を落とす blocking tier である。
+ *
+ * 判定: `acBoundStories`（スコープ）内の各 storyId について、matrix 上の全 linked AC を走査し、
+ * testReferences に `binding:"ac"` を 1 件も持たない AC（fileFallbackOnly）が 1 つでもあれば FAIL。
+ * スコープ外 story は完全に無視する。スコープが空なら検査対象が無いため PASS。
+ *
+ * matrix path は config（layers.L3.requirementMatrixPath）から供給される。CI では
+ * phasegate:generate-matrix で事前生成された最新マトリクスを READ する（L3-004 と同じ規約）。
+ */
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import type { AcBoundCoveragePolicyPort } from '../../domain/ports/ac-bound-coverage-policy-port.js';
+import type { HarnessErrorLike } from '../../domain/value-objects/validation-result.js';
+
+const DEFAULT_MATRIX_PATH = '.harness/requirement-test-matrix.json';
+
+interface MatrixTestReference {
+  readonly binding?: string;
+}
+
+interface MatrixAcMapping {
+  readonly acId?: string;
+  readonly testReferences?: readonly MatrixTestReference[];
+}
+
+interface MatrixStory {
+  readonly storyId?: string;
+  readonly storyMappings?: readonly MatrixAcMapping[];
+  readonly acMappings?: readonly MatrixAcMapping[];
+}
+
+function toL3005Error(message: string, suggestion: string): HarnessErrorLike {
+  return {
+    code: { value: 'L3-005', toString: () => 'L3-005' },
+    severity: { value: 'error', toString: () => 'error' },
+    message,
+    suggestion,
+  };
+}
+
+export class NyquistAcBoundCoveragePolicyAdapter implements AcBoundCoveragePolicyPort {
+  async checkAcBoundCoverage(context: {
+    matrixFilePath?: string;
+    acBoundStories: readonly string[];
+  }): Promise<{ passed: boolean; errors: readonly HarnessErrorLike[] }> {
+    const scope = new Set(context.acBoundStories);
+    // スコープが空 = 検査すべき in-scope AC が存在しない → PASS
+    if (scope.size === 0) {
+      return { passed: true, errors: [] };
+    }
+
+    const rootDir = process.cwd();
+    const relativeOrAbsolute =
+      context.matrixFilePath && context.matrixFilePath.length > 0 ? context.matrixFilePath : DEFAULT_MATRIX_PATH;
+    const matrixFilePath = isAbsolute(relativeOrAbsolute) ? relativeOrAbsolute : join(rootDir, relativeOrAbsolute);
+
+    let parsed: unknown;
+    try {
+      const raw = await readFile(matrixFilePath, 'utf8');
+      parsed = JSON.parse(raw);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      // FAIL-CLOSED: 不在・parse 不能はいずれも不合格
+      return {
+        passed: false,
+        errors: [
+          toL3005Error(
+            `AC-bound マトリクスを読み込めません（L3-005 は fail-closed）: ${relativeOrAbsolute}: ${message}`,
+            `${relativeOrAbsolute} を生成してください（phasegate:generate-matrix）。パスは config の layers.L3.requirementMatrixPath で変更できます`,
+          ),
+        ],
+      };
+    }
+
+    const stories = this.extractStories(parsed);
+    const errors: HarnessErrorLike[] = [];
+
+    for (const story of stories) {
+      const storyId = story.storyId ?? '';
+      if (!scope.has(storyId)) continue; // スコープ外は無視
+
+      const acMappings = story.storyMappings ?? story.acMappings ?? [];
+      for (const ac of acMappings) {
+        const refs = ac.testReferences ?? [];
+        if (refs.length === 0) continue; // 未リンク AC は L3-004 の責務。L3-005 は ac-binding 有無のみ判定
+        const hasAcBound = refs.some((ref) => ref.binding === 'ac');
+        if (!hasAcBound) {
+          errors.push(
+            toL3005Error(
+              `AC-bound coverage 不足: ${storyId}.${ac.acId ?? '?'} は binding:"ac" のテスト参照を持ちません（fileFallbackOnly）`,
+              `${storyId}.${ac.acId ?? '?'} を検証するテストに @ac タグ（絶対 ${storyId}-N / 相対 AC-N）を付与してください`,
+            ),
+          );
+        }
+      }
+    }
+
+    if (errors.length === 0) {
+      return { passed: true, errors: [] };
+    }
+    return { passed: false, errors };
+  }
+
+  private extractStories(parsed: unknown): readonly MatrixStory[] {
+    if (typeof parsed !== 'object' || parsed === null) return [];
+    const obj = parsed as { stories?: unknown; storyMappings?: unknown };
+    const raw = Array.isArray(obj.stories) ? obj.stories : Array.isArray(obj.storyMappings) ? obj.storyMappings : [];
+    return raw as readonly MatrixStory[];
+  }
+}

package/scripts/harness/validator-system/presentation/handlers/report-validation-results-handler.ts

@@ -21,10 +21,10 @@ export function isValidationResultContract(obj: unknown): obj is ValidationResul
   if (typeof obj !== 'object' || obj === null) return false;
   const o = obj as Record<string, unknown>;
   return (
-    typeof o['validatorId'] === 'string' &&
-    typeof o['passed'] === 'boolean' &&
-    Array.isArray(o['errors']) &&
-    typeof o['durationMs'] === 'number'
+    typeof o.validatorId === 'string' &&
+    typeof o.passed === 'boolean' &&
+    Array.isArray(o.errors) &&
+    typeof o.durationMs === 'number'
   );
 }