phasegate 0.165.0 → 0.171.0

package/scripts/harness/validator-system/domain/services/l4/ac-level-traceability-service.ts

@@ -0,0 +1,102 @@
+/**
+ * @layer domain
+ * @unit validator-system
+ * @work-item-id WI-222
+ *
+ * HF2-05 / L4-007: AC 単位トレーサビリティ advisory サービス。
+ *
+ * このサービスは fileFallbackOnly な AC（story-level では linked だが、個別 AC を検証する
+ * @ac 注釈付きテストが 1 件も無い AC）と orphanAcTags（解決に失敗した @ac）を
+ * warning severity の finding へ変換する。**error は一切出さない**（ADR-019 §5: advisory tier は
+ * non-blocking でなければならない）。fileFallbackOnly が 0 かつ orphanAcTags が空なら PASS。
+ *
+ * L3-004 の二値 pass/fail 判定には一切関与しない（verdict 不変）。
+ */
+
+export interface AcLevelCoverageSummary {
+  readonly total: number;
+  readonly acBound: number;
+  readonly fileFallbackOnly: number;
+}
+
+export interface FileFallbackOnlyAc {
+  readonly storyId: string;
+  readonly acId: string;
+}
+
+export interface OrphanAcTag {
+  readonly storyId: string;
+  readonly filePath: string;
+  readonly testName?: string;
+  readonly rawTag: string;
+  readonly reason: 'ac-not-in-story' | 'relative-multi-story';
+}
+
+export interface AcLevelTraceabilitySnapshot {
+  readonly acLevelCoverage: AcLevelCoverageSummary;
+  readonly fileFallbackOnlyAcs: readonly FileFallbackOnlyAc[];
+  readonly orphanAcTags: readonly OrphanAcTag[];
+}
+
+export interface AcLevelTraceabilityFinding {
+  readonly kind: 'file-fallback-only-ac' | 'orphan-ac-tag';
+  readonly message: string;
+  readonly suggestion: string;
+}
+
+export class AcLevelTraceabilityReport {
+  readonly findings: readonly AcLevelTraceabilityFinding[];
+
+  constructor(findings: readonly AcLevelTraceabilityFinding[]) {
+    this.findings = Object.freeze([...findings]);
+    Object.freeze(this);
+  }
+
+  hasFindings(): boolean {
+    return this.findings.length > 0;
+  }
+
+  toHarnessErrors(): readonly {
+    readonly code: { readonly value: string; toString(): string };
+    readonly severity: { readonly value: string; toString(): string };
+    readonly message: string;
+    readonly suggestion: string;
+    readonly kind: string;
+  }[] {
+    return this.findings.map((finding) => ({
+      code: { value: 'L4-007', toString: () => 'L4-007' },
+      severity: { value: 'warning', toString: () => 'warning' },
+      message: finding.message,
+      suggestion: finding.suggestion,
+      kind: finding.kind,
+    }));
+  }
+}
+
+export class AcLevelTraceabilityService {
+  check(snapshot: AcLevelTraceabilitySnapshot): AcLevelTraceabilityReport {
+    const findings: AcLevelTraceabilityFinding[] = [];
+
+    for (const ac of snapshot.fileFallbackOnlyAcs) {
+      findings.push({
+        kind: 'file-fallback-only-ac',
+        message: `${ac.storyId} ${ac.acId} is linked only via file-fallback (no @ac-bound test asserts it individually).`,
+        suggestion: `Add an "// @ac ${ac.storyId}-${ac.acId.replace(/^AC-/, '')}" annotation to the test case that specifically asserts ${ac.acId}, or accept this as a known file-level gap.`,
+      });
+    }
+
+    for (const orphan of snapshot.orphanAcTags) {
+      const location = orphan.testName ? `${orphan.filePath} ("${orphan.testName}")` : orphan.filePath;
+      const reasonText = orphan.reason === 'relative-multi-story'
+        ? 'relative @ac cannot be resolved because the file declares multiple @story tags'
+        : 'the referenced AC does not belong to the file\'s story';
+      findings.push({
+        kind: 'orphan-ac-tag',
+        message: `${location}: @ac "${orphan.rawTag}" is unresolved — ${reasonText}.`,
+        suggestion: 'Use an absolute @ac (HXX-YY-N) that matches the file\'s @story, or split multi-story test files so relative AC-N resolves unambiguously.',
+      });
+    }
+
+    return new AcLevelTraceabilityReport(findings);
+  }
+}

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

@@ -9,6 +9,8 @@
  * WI-140 で L2-014 を追加
  * 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 {
@@ -36,12 +38,14 @@ 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',
   'L4-004': 'doc-freshness',
   'L4-005': 'pointer-validation',
   'L4-006': 'skill-catalog-drift',
+  'L4-007': 'ac-level-traceability',
 };
 
 /** バリデータ名 -> バリデータID の逆引きマップ */
@@ -53,6 +57,7 @@ const NAME_TO_ID_MAP: Record<string, string> = {
   'doc-freshness-checker': 'L4-004',
   'pointer-validator': 'L4-005',
   'skill-catalog-drift': 'L4-006',
+  'ac-level-traceability': 'L4-007',
 };
 
 /** 有効なValidatorID集合 */

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/infrastructure/adapters/nyquist-ac-level-traceability-adapter.ts

@@ -0,0 +1,104 @@
+/**
+ * @layer infrastructure
+ * @unit validator-system
+ * @work-item-id WI-222
+ *
+ * HF2-05 / L4-007: nyquist-validation の generate-matrix usecase を実行し、
+ * AC 単位トレーサビリティの snapshot（acLevelCoverage / fileFallbackOnlyAcs / orphanAcTags）を
+ * 収集して AcLevelTraceabilityPort として提供する adapter。
+ *
+ * advisory 用途のため、収集に失敗しても throw せず「所見なし」snapshot を返す（fail-open）。
+ * これは L3-004（fail-closed な AC 網羅ゲート）とは独立した advisory tier であり、
+ * 収集失敗が CI を落とすことは意図しない（ADR-019 §5: advisory は non-blocking）。
+ */
+import type { AcLevelTraceabilityPort } from '../../domain/ports/ac-level-traceability-port.js';
+import type {
+  AcLevelTraceabilitySnapshot,
+  FileFallbackOnlyAc,
+  OrphanAcTag,
+} from '../../domain/services/l4/ac-level-traceability-service.js';
+
+const EMPTY_SNAPSHOT: AcLevelTraceabilitySnapshot = Object.freeze({
+  acLevelCoverage: { total: 0, acBound: 0, fileFallbackOnly: 0 },
+  fileFallbackOnlyAcs: Object.freeze([]),
+  orphanAcTags: Object.freeze([]),
+});
+
+export interface NyquistAcLevelTraceabilityAdapterOptions {
+  readonly requirementsPath?: string;
+  readonly testRoot?: string;
+  readonly matrixFilePath?: string;
+}
+
+export class NyquistAcLevelTraceabilityAdapter implements AcLevelTraceabilityPort {
+  private readonly requirementsPath: string;
+  private readonly testRoot: string;
+  private readonly matrixFilePath: string;
+
+  constructor(options: NyquistAcLevelTraceabilityAdapterOptions = {}) {
+    this.requirementsPath = options.requirementsPath ?? 'docs/product/user_stories.md';
+    this.testRoot = options.testRoot ?? 'scripts/harness/__tests__';
+    this.matrixFilePath = options.matrixFilePath ?? '.harness/requirement-test-matrix.json';
+  }
+
+  async collect(): Promise<AcLevelTraceabilitySnapshot> {
+    try {
+      const storyIds = await this.loadValidStoryIds();
+      const { createNyquistValidationModule } = await import('../../../nyquist-validation/composition-root.js');
+      const mod = createNyquistValidationModule({ getStoryIds: async () => storyIds });
+      const output = await mod.generateMatrixUseCase.execute({
+        requirementsPath: this.requirementsPath,
+        testRoot: this.testRoot,
+        matrixFilePath: this.matrixFilePath,
+        write: false,
+      });
+
+      const fileFallbackOnlyAcs: FileFallbackOnlyAc[] = [];
+      for (const story of output.matrix.stories) {
+        for (const mapping of story.storyMappings) {
+          if (mapping.testReferences.length === 0) continue;
+          const hasAcBound = mapping.testReferences.some((ref) => ref.binding === 'ac');
+          if (!hasAcBound) {
+            fileFallbackOnlyAcs.push({ storyId: story.storyId, acId: mapping.acId });
+          }
+        }
+      }
+
+      const orphanAcTags: OrphanAcTag[] = output.report.orphanAcTags.map((tag) => ({
+        storyId: tag.storyId,
+        filePath: tag.filePath,
+        testName: tag.testName,
+        rawTag: tag.rawTag,
+        reason: tag.reason,
+      }));
+
+      return {
+        acLevelCoverage: {
+          total: output.report.acLevelCoverage.total,
+          acBound: output.report.acLevelCoverage.acBound,
+          fileFallbackOnly: output.report.acLevelCoverage.fileFallbackOnly,
+        },
+        fileFallbackOnlyAcs: Object.freeze(fileFallbackOnlyAcs),
+        orphanAcTags: Object.freeze(orphanAcTags),
+      };
+    } catch {
+      return EMPTY_SNAPSHOT;
+    }
+  }
+
+  private async loadValidStoryIds(): Promise<readonly string[]> {
+    try {
+      const { createConfigFoundationModule } = await import('../../../config-foundation/composition-root.js');
+      const configModule = createConfigFoundationModule();
+      const resolvedConfig = await configModule.usecases.loadResolvedConfigUseCase.execute();
+      const { createTraceabilityModelModule } = await import('../../../traceability-model/composition-root.js');
+      const traceModule = createTraceabilityModelModule(process.cwd(), {
+        pathRoots: { designDocsRoot: resolvedConfig.config.paths.designDocs },
+      });
+      const storyIds = await traceModule.storyCatalog.getAllStoryIds();
+      return storyIds.map((s) => s.value);
+    } catch {
+      return [];
+    }
+  }
+}

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