phasegate 0.163.0 → 0.167.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/value-objects/validator-id.ts

@@ -9,6 +9,7 @@
  * 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）を追加
  */
 
 export class InvalidValidatorIdError extends Error {
@@ -42,6 +43,7 @@ const VALIDATOR_NAME_MAP: Record<string, string> = {
   'L4-004': 'doc-freshness',
   'L4-005': 'pointer-validation',
   'L4-006': 'skill-catalog-drift',
+  'L4-007': 'ac-level-traceability',
 };
 
 /** バリデータ名 -> バリデータID の逆引きマップ */
@@ -53,6 +55,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/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 [];
+    }
+  }
+}