phasegate 0.149.0 → 0.150.1

package/scripts/harness/harness-api/infrastructure/adapters/harness-config-query-adapter.ts

@@ -1,10 +1,13 @@
 // @layer infrastructure
 // @unit harness-api
+// @work-item-id WI-123
 // harness-config-query-adapter.ts — HarnessConfigQueryAdapter
 
 import * as fs from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
 import type { ConfigQueryPort } from '../../domain/ports/config-query-port.js';
-import type { PresetInfo, ConfigSummary, PhaseGateSummary } from '../../domain/value-objects/harness-status-summary.js';
+import type { PresetInfo, ConfigSummary, PhaseGateSummary, HookHealth, BaselineHealth } from '../../domain/value-objects/harness-status-summary.js';
 import type { LayerId } from '../../domain/value-objects/layer-health.js';
 
 interface HarnessConfigJson {
@@ -18,6 +21,10 @@ interface HarnessConfigJson {
     designDocs?: string;
     integrationTests?: string;
   };
+  baseline?: {
+    enabled?: boolean;
+    path?: string;
+  };
 }
 
 const PRESET_LAYERS: Record<string, LayerId[]> = {
@@ -77,4 +84,87 @@ export class HarnessConfigQueryAdapter implements ConfigQueryPort {
     // wave2-pending: integrate with phase-dependency-model
     return { totalStories: 0, passedStories: 0, pendingStories: 0 };
   }
+
+  async getHookHealth(): Promise<HookHealth> {
+    const rootDir = dirname(this.configPath);
+    const configuredHooks: string[] = [];
+    for (const hookPath of ['.claude/settings.json', '.codex/hooks.json', '.husky/pre-commit', '.husky/pre-push']) {
+      try {
+        await fs.access(join(rootDir, hookPath));
+        configuredHooks.push(hookPath);
+      } catch {
+        // Missing hook files are represented by absence from configuredHooks.
+      }
+    }
+
+    const skipEvents = await readHookSkipEvents(join(rootDir, '.phasegate/hook-skip-events.jsonl'));
+    const skipCountsByReason: Record<string, number> = {};
+    for (const event of skipEvents) {
+      skipCountsByReason[event.reason] = (skipCountsByReason[event.reason] ?? 0) + 1;
+    }
+
+    return {
+      enabled: configuredHooks.length > 0,
+      configuredHooks,
+      latestSkip: skipEvents.at(-1) ?? null,
+      skipCountsByReason,
+      applyPatchBypass: {
+        nativeApplyPatchIntercepted: false,
+        backstop: 'pre-commit',
+        documentationUrl: 'docs/guide/codex-integration.md',
+      },
+    };
+  }
+
+  async getBaselineHealth(): Promise<BaselineHealth> {
+    const config = await this.readConfig();
+    const rootDir = dirname(this.configPath);
+    const enabled = config.baseline?.enabled ?? true;
+    const relativePath = config.baseline?.path ?? '.phasegate/baseline.json';
+    const baselinePath = resolve(rootDir, relativePath);
+
+    if (!enabled) {
+      return { enabled: false, path: relativePath, grandfatheredFileCount: 0, shaMismatchCount: 0, missingFileCount: 0, removalRate: 0 };
+    }
+
+    let raw: string;
+    try {
+      raw = await fs.readFile(baselinePath, 'utf-8');
+    } catch {
+      return { enabled: true, path: relativePath, grandfatheredFileCount: 0, shaMismatchCount: 0, missingFileCount: 0, removalRate: 0 };
+    }
+
+    const parsed = JSON.parse(raw) as { files?: Array<{ path?: string; sha1?: string }>; entries?: Array<{ path?: string; sha1?: string }> };
+    const entries = parsed.files ?? parsed.entries ?? [];
+    let shaMismatchCount = 0;
+    let missingFileCount = 0;
+    for (const entry of entries) {
+      if (typeof entry.path !== 'string' || typeof entry.sha1 !== 'string') continue;
+      try {
+        const current = await fs.readFile(resolve(rootDir, entry.path));
+        const sha1 = createHash('sha1').update(current).digest('hex');
+        if (sha1 !== entry.sha1) shaMismatchCount += 1;
+      } catch {
+        missingFileCount += 1;
+      }
+    }
+    const grandfatheredFileCount = entries.length;
+    const removalRate = grandfatheredFileCount === 0
+      ? 1
+      : (shaMismatchCount + missingFileCount) / grandfatheredFileCount;
+    return { enabled: true, path: relativePath, grandfatheredFileCount, shaMismatchCount, missingFileCount, removalRate };
+  }
+}
+
+async function readHookSkipEvents(filePath: string): Promise<Array<NonNullable<HookHealth['latestSkip']>>> {
+  try {
+    const raw = await fs.readFile(filePath, 'utf-8');
+    return raw
+      .split('\n')
+      .filter((line) => line.trim().length > 0)
+      .map((line) => JSON.parse(line) as HookHealth['latestSkip'])
+      .filter((event): event is NonNullable<HookHealth['latestSkip']> => event !== null);
+  } catch {
+    return [];
+  }
 }

package/scripts/harness/main.ts

@@ -185,6 +185,7 @@ Commands:
   phasegate:lint                Lint via harness-api (--target <path>, --json)
   phasegate:complete-check       Complete L2-L4 check (--json)
   phasegate:impact-analysis      Impact analysis for story (<storyId>, --json)
+  phasegate:generate-matrix      Generate requirement-test matrix (--requirements, --tests, --out, --json)
 
   ci:generate-template         Generate CI template (--preset <id>, default: standard; --type <aidlc-gate|consistency-check|pre-commit|agent-context-refresh>, --render, --json)
   ci:migrate-agents-md         Migrate AGENTS.md (--dry-run, --validate-only, --json)
@@ -1652,6 +1653,21 @@ async function main(): Promise<void> {
         break;
       }
 
+      case "phasegate:generate-matrix": {
+        const { createNyquistValidationModule } = await import("./nyquist-validation/composition-root.js");
+        const mod = createNyquistValidationModule({
+          getStoryIds: async () => [],
+        });
+        const flags: Record<string, boolean | string> = {};
+        if (json) flags.json = true;
+        await mod.handlers.generateMatrixHandler.handle({
+          requirementsPath: parseFlag(args, "--requirements") ?? "docs/product/user_stories.md",
+          testRoot: parseFlag(args, "--tests") ?? "scripts/harness/__tests__",
+          matrixFilePath: parseFlag(args, "--out") ?? ".harness/requirement-test-matrix.json",
+        }, flags);
+        break;
+      }
+
       // ── ci-governance ──
       case "ci:generate-template": {
         if (hasFlag(args, "--help")) {

package/scripts/harness/nyquist-validation/application/dto/generate-matrix-output.ts

@@ -0,0 +1,71 @@
+// @layer application
+// @unit nyquist-validation
+// @work-item-id WI-125
+// @work-item-id WI-131
+
+export interface RequirementSourceDto {
+  readonly storyId: string;
+  readonly acIds: readonly string[];
+}
+
+export interface TestReferenceSourceDto {
+  readonly storyId: string;
+  readonly filePath: string;
+  readonly testType: 'unit' | 'it' | 'scenario';
+  readonly testName?: string;
+}
+
+export interface MatrixTestReferenceDto {
+  readonly filePath: string;
+  readonly testType: 'unit' | 'it' | 'scenario';
+  readonly testName?: string;
+}
+
+export interface MatrixAcMappingDto {
+  readonly acId: string;
+  readonly testReferences: readonly MatrixTestReferenceDto[];
+}
+
+export interface MatrixStoryDto {
+  readonly storyId: string;
+  readonly storyMappings: readonly MatrixAcMappingDto[];
+}
+
+export interface RequirementTestMatrixDto {
+  readonly version: string;
+  readonly generatedAt: string;
+  readonly stories: readonly MatrixStoryDto[];
+}
+
+export interface MissingTestDto {
+  readonly storyId: string;
+  readonly acId: string;
+}
+
+export interface OrphanTestDto {
+  readonly storyId: string;
+  readonly filePath: string;
+  readonly testName?: string;
+}
+
+export type IntentCoverageStatus = 'observed' | 'weakly-observed' | 'unobserved';
+
+export interface IntentCoverageItemDto {
+  readonly storyId: string;
+  readonly acId: string;
+  readonly status: IntentCoverageStatus;
+  readonly warnings: readonly string[];
+}
+
+export interface MatrixGenerationReportDto {
+  readonly missingTests: readonly MissingTestDto[];
+  readonly orphanTests: readonly OrphanTestDto[];
+  readonly unknownStories: readonly string[];
+  readonly preservedReferences: number;
+  readonly intentCoverage: readonly IntentCoverageItemDto[];
+}
+
+export interface GenerateMatrixOutput {
+  readonly matrix: RequirementTestMatrixDto;
+  readonly report: MatrixGenerationReportDto;
+}

package/scripts/harness/nyquist-validation/application/usecases/generate-requirement-test-matrix-usecase.ts

@@ -0,0 +1,161 @@
+// @layer application
+// @unit nyquist-validation
+// @work-item-id WI-125
+// @work-item-id WI-131
+
+import type { RequirementIntentCoverageService } from '../../domain/services/requirement-intent-coverage-service.js';
+import type {
+  GenerateMatrixOutput,
+  MatrixAcMappingDto,
+  MatrixStoryDto,
+  MatrixTestReferenceDto,
+  RequirementSourceDto,
+  RequirementTestMatrixDto,
+  TestReferenceSourceDto,
+} from '../dto/generate-matrix-output.js';
+
+export interface RequirementSourcePort {
+  readRequirements(sourcePath: string): Promise<readonly RequirementSourceDto[]>;
+}
+
+export interface TestReferenceSourcePort {
+  readTestReferences(testRoot: string): Promise<readonly TestReferenceSourceDto[]>;
+}
+
+export interface ExistingMatrixPort {
+  readExistingMatrix(matrixFilePath: string): Promise<RequirementTestMatrixDto | null>;
+  writeMatrix(matrixFilePath: string, matrix: RequirementTestMatrixDto): Promise<void>;
+}
+
+export interface GenerateRequirementTestMatrixInput {
+  readonly requirementsPath: string;
+  readonly testRoot: string;
+  readonly matrixFilePath: string;
+  readonly write: boolean;
+}
+
+export interface GenerateRequirementTestMatrixUseCaseDeps {
+  readonly requirementSourcePort: RequirementSourcePort;
+  readonly testReferenceSourcePort: TestReferenceSourcePort;
+  readonly matrixPort: ExistingMatrixPort;
+  readonly intentCoverageService: RequirementIntentCoverageService;
+  readonly now?: () => Date;
+}
+
+function referenceKey(reference: MatrixTestReferenceDto): string {
+  return `${reference.filePath}\0${reference.testType}\0${reference.testName ?? ''}`;
+}
+
+function mergeReferences(
+  generated: readonly MatrixTestReferenceDto[],
+  existing: readonly MatrixTestReferenceDto[],
+): { references: readonly MatrixTestReferenceDto[]; preserved: number } {
+  const result = [...generated];
+  const keys = new Set(result.map(referenceKey));
+  let preserved = 0;
+  for (const reference of existing) {
+    if (!keys.has(referenceKey(reference))) {
+      result.push(reference);
+      keys.add(referenceKey(reference));
+      preserved += 1;
+    }
+  }
+  return { references: Object.freeze(result), preserved };
+}
+
+function normalizeExistingReferences(
+  existingMatrix: RequirementTestMatrixDto | null,
+  storyId: string,
+  acId: string,
+): readonly MatrixTestReferenceDto[] {
+  const story = existingMatrix?.stories.find((item) => item.storyId === storyId);
+  const mapping = story?.storyMappings.find((item) => item.acId === acId);
+  return mapping?.testReferences ?? [];
+}
+
+export class GenerateRequirementTestMatrixUseCase {
+  private readonly requirementSourcePort: RequirementSourcePort;
+  private readonly testReferenceSourcePort: TestReferenceSourcePort;
+  private readonly matrixPort: ExistingMatrixPort;
+  private readonly intentCoverageService: RequirementIntentCoverageService;
+  private readonly now: () => Date;
+
+  constructor(deps: GenerateRequirementTestMatrixUseCaseDeps) {
+    this.requirementSourcePort = deps.requirementSourcePort;
+    this.testReferenceSourcePort = deps.testReferenceSourcePort;
+    this.matrixPort = deps.matrixPort;
+    this.intentCoverageService = deps.intentCoverageService;
+    this.now = deps.now ?? (() => new Date());
+  }
+
+  async execute(input: GenerateRequirementTestMatrixInput): Promise<GenerateMatrixOutput> {
+    const [requirements, testReferences, existingMatrix] = await Promise.all([
+      this.requirementSourcePort.readRequirements(input.requirementsPath),
+      this.testReferenceSourcePort.readTestReferences(input.testRoot),
+      this.matrixPort.readExistingMatrix(input.matrixFilePath),
+    ]);
+
+    const knownStories = new Set(requirements.map((requirement) => requirement.storyId));
+    const orphanTests = testReferences
+      .filter((reference) => !knownStories.has(reference.storyId))
+      .map((reference) => ({
+        storyId: reference.storyId,
+        filePath: reference.filePath,
+        testName: reference.testName,
+      }));
+    const referencesByStory = new Map<string, TestReferenceSourceDto[]>();
+    for (const reference of testReferences) {
+      if (!knownStories.has(reference.storyId)) continue;
+      const current = referencesByStory.get(reference.storyId) ?? [];
+      current.push(reference);
+      referencesByStory.set(reference.storyId, current);
+    }
+
+    let preservedReferences = 0;
+    const stories: MatrixStoryDto[] = requirements.map((requirement) => {
+      const storyReferences = referencesByStory.get(requirement.storyId) ?? [];
+      const storyMappings: MatrixAcMappingDto[] = requirement.acIds.map((acId) => {
+        const generatedReferences = storyReferences.map((reference) => ({
+          filePath: reference.filePath,
+          testType: reference.testType,
+          testName: reference.testName,
+        }));
+        const existingReferences = normalizeExistingReferences(existingMatrix, requirement.storyId, acId);
+        const merged = mergeReferences(generatedReferences, existingReferences);
+        preservedReferences += merged.preserved;
+        return {
+          acId,
+          testReferences: merged.references,
+        };
+      });
+      return {
+        storyId: requirement.storyId,
+        storyMappings: Object.freeze(storyMappings),
+      };
+    });
+
+    const matrix: RequirementTestMatrixDto = {
+      version: '1.0',
+      generatedAt: this.now().toISOString(),
+      stories: Object.freeze(stories),
+    };
+    const intentCoverage = this.intentCoverageService.evaluate(matrix.stories);
+    const missingTests = matrix.stories.flatMap((story) => story.storyMappings
+      .filter((mapping) => mapping.testReferences.length === 0)
+      .map((mapping) => ({ storyId: story.storyId, acId: mapping.acId })));
+
+    const report = {
+      missingTests,
+      orphanTests,
+      unknownStories: [...new Set(orphanTests.map((test) => test.storyId))],
+      preservedReferences,
+      intentCoverage,
+    };
+
+    if (input.write) {
+      await this.matrixPort.writeMatrix(input.matrixFilePath, matrix);
+    }
+
+    return { matrix, report };
+  }
+}

package/scripts/harness/nyquist-validation/composition-root.ts

@@ -6,6 +6,9 @@
  * 全コンポーネントを生成・配線し、UseCase群を外部に公開する。
  */
 import { FileSystemMatrixFileAdapter } from './infrastructure/adapters/file-system-matrix-file-adapter.js';
+import { FileSystemGeneratedMatrixAdapter } from './infrastructure/adapters/file-system-generated-matrix-adapter.js';
+import { MarkdownRequirementSourceAdapter } from './infrastructure/adapters/markdown-requirement-source-adapter.js';
+import { TypeScriptTestReferenceSourceAdapter } from './infrastructure/adapters/type-script-test-reference-source-adapter.js';
 import { AjvJsonSchemaValidatorAdapter } from './infrastructure/adapters/ajv-json-schema-validator-adapter.js';
 import { ConfigFoundationCoverageThresholdAdapter } from './infrastructure/adapters/config-foundation-coverage-threshold-adapter.js';
 import { TraceabilityModelStoryRegistryAdapter } from './infrastructure/adapters/traceability-model-story-registry-adapter.js';
@@ -13,14 +16,17 @@ import { MatrixValidationService } from './domain/services/matrix-validation-ser
 import { AcCoverageGatePolicy } from './domain/services/ac-coverage-gate-policy.js';
 import { CoverageCalculationService } from './domain/services/coverage-calculation-service.js';
 import { ImpactAnalysisService } from './domain/services/impact-analysis-service.js';
+import { RequirementIntentCoverageService } from './domain/services/requirement-intent-coverage-service.js';
 import { ValidateMatrixUseCase } from './application/usecases/validate-matrix-usecase.js';
 import { CheckAcCoverageGateUseCase } from './application/usecases/check-ac-coverage-gate-usecase.js';
 import { CalculateCoverageUseCase } from './application/usecases/calculate-coverage-usecase.js';
 import { AnalyzeImpactUseCase } from './application/usecases/analyze-impact-usecase.js';
+import { GenerateRequirementTestMatrixUseCase } from './application/usecases/generate-requirement-test-matrix-usecase.js';
 import { ValidateMatrixHandler } from './presentation/handlers/validate-matrix-handler.js';
 import { CheckAcCoverageGateHandler } from './presentation/handlers/check-ac-coverage-gate-handler.js';
 import { CalculateCoverageHandler } from './presentation/handlers/calculate-coverage-handler.js';
 import { AnalyzeImpactHandler } from './presentation/handlers/analyze-impact-handler.js';
+import { GenerateMatrixHandler } from './presentation/handlers/generate-matrix-handler.js';
 
 export interface NyquistValidationModuleDeps {
   /** traceability-model の storyCatalog.getAllStoryIds() を渡す */
@@ -32,6 +38,9 @@ export interface NyquistValidationModuleDeps {
 export function createNyquistValidationModule(deps: NyquistValidationModuleDeps) {
   // Infrastructure adapters
   const matrixFilePort = new FileSystemMatrixFileAdapter();
+  const generatedMatrixPort = new FileSystemGeneratedMatrixAdapter();
+  const requirementSourcePort = new MarkdownRequirementSourceAdapter();
+  const testReferenceSourcePort = new TypeScriptTestReferenceSourceAdapter();
   const ajvValidator = new AjvJsonSchemaValidatorAdapter();
   const coverageThresholdPort = new ConfigFoundationCoverageThresholdAdapter({
     getPreset: deps.getPreset,
@@ -45,6 +54,7 @@ export function createNyquistValidationModule(deps: NyquistValidationModuleDeps)
   const acCoverageGatePolicy = new AcCoverageGatePolicy();
   const coverageCalculationService = new CoverageCalculationService();
   const impactAnalysisService = new ImpactAnalysisService();
+  const intentCoverageService = new RequirementIntentCoverageService();
 
   // Application UseCases
   const validateMatrixUseCase = new ValidateMatrixUseCase({
@@ -75,6 +85,13 @@ export function createNyquistValidationModule(deps: NyquistValidationModuleDeps)
     impactAnalysisService,
   });
 
+  const generateMatrixUseCase = new GenerateRequirementTestMatrixUseCase({
+    requirementSourcePort,
+    testReferenceSourcePort,
+    matrixPort: generatedMatrixPort,
+    intentCoverageService,
+  });
+
   const validateMatrixHandler = new ValidateMatrixHandler({
     validateMatrixUseCase,
   });
@@ -91,18 +108,24 @@ export function createNyquistValidationModule(deps: NyquistValidationModuleDeps)
     analyzeImpactUseCase,
   });
 
+  const generateMatrixHandler = new GenerateMatrixHandler({
+    useCase: generateMatrixUseCase,
+  });
+
   return {
     validateMatrixUseCase,
     checkAcCoverageGateUseCase,
     calculateCoverageUseCase,
     analyzeImpactUseCase,
+    generateMatrixUseCase,
     handlers: {
       validateMatrixHandler,
       checkAcCoverageGateHandler,
       calculateCoverageHandler,
       analyzeImpactHandler,
+      generateMatrixHandler,
     },
   } as const;
 }
 
-// @story-id H08-07
+// @story-id H08-07

package/scripts/harness/nyquist-validation/domain/services/requirement-intent-coverage-service.ts

@@ -0,0 +1,42 @@
+// @layer domain
+// @unit nyquist-validation
+// @work-item-id WI-131
+
+import type {
+  IntentCoverageItemDto,
+  MatrixStoryDto,
+} from '../../application/dto/generate-matrix-output.js';
+
+export class RequirementIntentCoverageService {
+  evaluate(stories: readonly MatrixStoryDto[]): readonly IntentCoverageItemDto[] {
+    return stories.flatMap((story) => story.storyMappings.map((mapping) => {
+      if (mapping.testReferences.length === 0) {
+        return {
+          storyId: story.storyId,
+          acId: mapping.acId,
+          status: 'unobserved' as const,
+          warnings: ['No test reference observes this acceptance criterion.'],
+        };
+      }
+
+      const hasNamedReference = mapping.testReferences.some((reference) => (
+        typeof reference.testName === 'string' && reference.testName.trim().length > 0
+      ));
+      if (!hasNamedReference) {
+        return {
+          storyId: story.storyId,
+          acId: mapping.acId,
+          status: 'weakly-observed' as const,
+          warnings: ['Test reference exists, but testName is missing; observation intent is weak.'],
+        };
+      }
+
+      return {
+        storyId: story.storyId,
+        acId: mapping.acId,
+        status: 'weakly-observed' as const,
+        warnings: ['Test reference and testName exist, but assertion target / expected outcome evidence is not yet attached.'],
+      };
+    }));
+  }
+}

package/scripts/harness/nyquist-validation/index.ts

@@ -22,5 +22,13 @@ export type {
 } from './presentation/handlers/calculate-coverage-handler.js';
 export { AnalyzeImpactHandler } from './presentation/handlers/analyze-impact-handler.js';
 export type { AnalyzeImpactHandlerArgs, AnalyzeImpactHandlerDeps } from './presentation/handlers/analyze-impact-handler.js';
+export { GenerateMatrixHandler } from './presentation/handlers/generate-matrix-handler.js';
+export { GenerateRequirementTestMatrixUseCase } from './application/usecases/generate-requirement-test-matrix-usecase.js';
+export { RequirementIntentCoverageService } from './domain/services/requirement-intent-coverage-service.js';
+export type {
+  GenerateMatrixOutput,
+  RequirementTestMatrixDto,
+  MatrixGenerationReportDto,
+} from './application/dto/generate-matrix-output.js';
 
-// @story-id H08-07
+// @story-id H08-07

package/scripts/harness/nyquist-validation/infrastructure/adapters/file-system-generated-matrix-adapter.ts

@@ -0,0 +1,24 @@
+// @layer infrastructure
+// @unit nyquist-validation
+// @work-item-id WI-125
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { RequirementTestMatrixDto } from '../../application/dto/generate-matrix-output.js';
+import type { ExistingMatrixPort } from '../../application/usecases/generate-requirement-test-matrix-usecase.js';
+
+export class FileSystemGeneratedMatrixAdapter implements ExistingMatrixPort {
+  async readExistingMatrix(matrixFilePath: string): Promise<RequirementTestMatrixDto | null> {
+    try {
+      const raw = await readFile(matrixFilePath, 'utf-8');
+      return JSON.parse(raw) as RequirementTestMatrixDto;
+    } catch {
+      return null;
+    }
+  }
+
+  async writeMatrix(matrixFilePath: string, matrix: RequirementTestMatrixDto): Promise<void> {
+    await mkdir(path.dirname(matrixFilePath), { recursive: true });
+    await writeFile(matrixFilePath, `${JSON.stringify(matrix, null, 2)}\n`, 'utf-8');
+  }
+}

package/scripts/harness/nyquist-validation/infrastructure/adapters/markdown-requirement-source-adapter.ts

@@ -0,0 +1,37 @@
+// @layer infrastructure
+// @unit nyquist-validation
+// @work-item-id WI-125
+
+import { readFile } from 'node:fs/promises';
+import type { RequirementSourcePort } from '../../application/usecases/generate-requirement-test-matrix-usecase.js';
+import type { RequirementSourceDto } from '../../application/dto/generate-matrix-output.js';
+
+const STORY_HEADING = /^###\s+(H\d{2}-\d{2}):/;
+const AC_ITEM = /^\s*-\s+\[[ xX]\]\s+(AC-[1-9][0-9]*):/;
+
+export class MarkdownRequirementSourceAdapter implements RequirementSourcePort {
+  async readRequirements(sourcePath: string): Promise<readonly RequirementSourceDto[]> {
+    const content = await readFile(sourcePath, 'utf-8');
+    const results: RequirementSourceDto[] = [];
+    let current: { storyId: string; acIds: string[] } | null = null;
+
+    for (const line of content.split(/\r?\n/)) {
+      const storyMatch = line.match(STORY_HEADING);
+      if (storyMatch) {
+        if (current) {
+          results.push({ storyId: current.storyId, acIds: Object.freeze([...new Set(current.acIds)]) });
+        }
+        current = { storyId: storyMatch[1], acIds: [] };
+        continue;
+      }
+      const acMatch = line.match(AC_ITEM);
+      if (current && acMatch) {
+        current.acIds.push(acMatch[1]);
+      }
+    }
+    if (current) {
+      results.push({ storyId: current.storyId, acIds: Object.freeze([...new Set(current.acIds)]) });
+    }
+    return Object.freeze(results.filter((result) => result.acIds.length > 0));
+  }
+}

package/scripts/harness/nyquist-validation/infrastructure/adapters/type-script-test-reference-source-adapter.ts

@@ -0,0 +1,54 @@
+// @layer infrastructure
+// @unit nyquist-validation
+// @work-item-id WI-125
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import type { TestReferenceSourcePort } from '../../application/usecases/generate-requirement-test-matrix-usecase.js';
+import type { TestReferenceSourceDto } from '../../application/dto/generate-matrix-output.js';
+
+const STORY_TAG = /@story(?:-id)?\s+(H\d{2}-\d{2})/;
+const TEST_NAME = /\b(?:it|test)(?:\.each\([^)]*\))?\s*\(\s*['"`]([^'"`]+)['"`]/g;
+
+async function collectTestFiles(root: string): Promise<readonly string[]> {
+  const rootStat = await stat(root).catch(() => null);
+  if (rootStat === null) return [];
+  if (rootStat.isFile()) return /\.(test|spec)\.[cm]?[tj]sx?$/.test(root) ? [root] : [];
+
+  const entries = await readdir(root, { withFileTypes: true });
+  const nested = await Promise.all(entries
+    .filter((entry) => entry.name !== 'node_modules' && entry.name !== 'dist' && entry.name !== '.git')
+    .map((entry) => collectTestFiles(path.join(root, entry.name))));
+  return Object.freeze(nested.flat());
+}
+
+function classifyTestType(filePath: string): 'unit' | 'it' | 'scenario' {
+  const normalized = filePath.toLowerCase();
+  if (normalized.includes('/scenario/') || normalized.includes('.scenario.')) return 'scenario';
+  if (normalized.includes('/integration/') || normalized.includes('.it.') || normalized.includes('.integration.')) return 'it';
+  return 'unit';
+}
+
+export class TypeScriptTestReferenceSourceAdapter implements TestReferenceSourcePort {
+  async readTestReferences(testRoot: string): Promise<readonly TestReferenceSourceDto[]> {
+    const files = await collectTestFiles(testRoot);
+    const references: TestReferenceSourceDto[] = [];
+    for (const filePath of files) {
+      const content = await readFile(filePath, 'utf-8');
+      const storyMatch = content.match(STORY_TAG);
+      if (!storyMatch) continue;
+      const storyId = storyMatch[1];
+      const relativePath = path.relative(process.cwd(), filePath).replaceAll(path.sep, '/');
+      const testType = classifyTestType(relativePath);
+      const names = [...content.matchAll(TEST_NAME)].map((match) => match[1]);
+      if (names.length === 0) {
+        references.push({ storyId, filePath: relativePath, testType });
+        continue;
+      }
+      for (const testName of names) {
+        references.push({ storyId, filePath: relativePath, testType, testName });
+      }
+    }
+    return Object.freeze(references);
+  }
+}

package/scripts/harness/nyquist-validation/presentation/handlers/generate-matrix-handler.ts

@@ -0,0 +1,34 @@
+// @layer presentation
+// @unit nyquist-validation
+// @work-item-id WI-125
+// @work-item-id WI-131
+
+import type {
+  GenerateRequirementTestMatrixInput,
+  GenerateRequirementTestMatrixUseCase,
+} from '../../application/usecases/generate-requirement-test-matrix-usecase.js';
+
+export interface GenerateMatrixHandlerDeps {
+  readonly useCase: GenerateRequirementTestMatrixUseCase;
+}
+
+export class GenerateMatrixHandler {
+  private readonly useCase: GenerateRequirementTestMatrixUseCase;
+
+  constructor(deps: GenerateMatrixHandlerDeps) {
+    this.useCase = deps.useCase;
+  }
+
+  async handle(input: Omit<GenerateRequirementTestMatrixInput, 'write'>, flags: Record<string, boolean | string>): Promise<void> {
+    const output = await this.useCase.execute({ ...input, write: true });
+    if (flags.json === true) {
+      console.log(JSON.stringify(output, null, 2));
+      return;
+    }
+    console.log(`Requirement test matrix generated: ${input.matrixFilePath}`);
+    console.log(`Stories: ${output.matrix.stories.length}`);
+    console.log(`Missing tests: ${output.report.missingTests.length}`);
+    console.log(`Orphan tests: ${output.report.orphanTests.length}`);
+    console.log(`Preserved references: ${output.report.preservedReferences}`);
+  }
+}