phasegate 0.150.0 → 0.150.1

package/CHANGELOG.md

@@ -7,11 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.150.1] - 2026-05-12
+
+### Fixed
+
+- **WI-125 post-publish dogfood** — republish patch for `phasegate:generate-matrix` after `phasegate@0.150.0` dogfood showed the published tarball did not include the new command.
+
 ## [0.150.0] - 2026-05-12
 
 ### Added
 
 - **G1 / WI-123 / WI-124 / WI-127 / WI-128 — Gate reliability and operational transparency** — `phasegate:status --json` now reports hook/baseline operational health, CI template validator IDs are derived from the live validator-system registry, L4 scheduled audit docs/templates use canonical L4 commands, and README/guide feature inventory matches the shipped 30 skills.
+- **G2 / WI-125 / WI-129 / WI-130 / WI-131 — L2 test-quality core and Nyquist matrix generation** — `L2-003 test-quality` uses semantic AAA / assertion strength analysis, and `phasegate:generate-matrix` generates `requirement-test-matrix.json` from product ACs and test metadata with missing/orphan/intent coverage reporting.
 
 ## [0.147.0] - 2026-05-12
 

package/README.ja.md

@@ -498,7 +498,7 @@ reports/
 |---|---|
 | **[WI-128](docs/inception/_cross/WI-128/description.md)** | L4 運用ロールアウトの仕上げ。`doc-freshness` / `pointer-validation` は L4-004 / L4-005 として登録済みで、`p2:*` 互換コマンドも維持。WI-033 は完了済みとして閉じ、残りの scheduling / default / 運用 docs は後続 WI で扱う。@work-item-id WI-128 |
 
-L3 Nyquist Validation の `requirement-test-matrix.json` 自動生成はまだ未自動化です。[WI-125](docs/inception/_cross/WI-125/description.md) と L3 guide を参照してください。現時点では手動セットアップで利用できます。
+L3 Nyquist Validation の `requirement-test-matrix.json` は `phasegate:generate-matrix` で product docs の受け入れ基準と test metadata から生成できます。`--json` では missing tests / orphan tests / preserved references / intent coverage warnings を確認できます。
 
 ---
 

package/README.md

@@ -559,7 +559,7 @@ The main path is ready for project use, but a few documented behaviors still req
 |---|---|---|
 | **[WI-128](docs/inception/_cross/WI-128/description.md)** | Finish L4 operational rollout | `doc-freshness` and `pointer-validation` are registered as L4-004/L4-005 and also remain available through `p2:*` compatibility commands. WI-033 is closed; remaining rollout polish around scheduling, defaults, and operational docs is tracked separately. @work-item-id WI-128 |
 
-`requirement-test-matrix.json` auto-generation for L3 Nyquist Validation is not automated yet; see [WI-125](docs/inception/_cross/WI-125/description.md) and the L3 guide for the current manual setup.
+`requirement-test-matrix.json` can be generated with `phasegate:generate-matrix` from product acceptance criteria and test metadata, then consumed by L3 Nyquist Validation. Use `--json` to inspect missing tests, orphan tests, preserved references, and intent coverage warnings.
 
 ---
 

package/docs/guide/cli-reference.md

@@ -362,3 +362,16 @@ ISSUE-005 P3-10 で明確化された境界:
 | `p2:check-freshness` | `--pattern <glob>` `--dry-run` `--format text\|json` | Compatibility entry point for L4-004 doc freshness; canonical L4 execution is `validate --layer L4` |
 | `p2:validate-pointers` | `--include-urls` `--format text\|json` | Compatibility entry point for L4-005 pointer validation; canonical L4 execution is `validate --layer L4` |
 | `p2:generate-e2e-template` | `--phase <phase>` `--output <path>` | Generate E2E test template |
+
+### `phasegate:generate-matrix`
+
+<!-- @work-item-id WI-125, WI-131 -->
+
+Generates `.harness/requirement-test-matrix.json` from product acceptance criteria and test metadata.
+
+```bash
+phasegate phasegate:generate-matrix --requirements docs/product/user_stories.md --tests scripts/harness/__tests__ --out .harness/requirement-test-matrix.json
+phasegate validate --layer L3
+```
+
+Use `--json` to inspect `missingTests`, `orphanTests`, preserved references, and intent coverage.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.150.0",
+  "version": "0.150.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/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}`);
+  }
+}