phasegate 0.165.0 → 0.171.0

package/scripts/harness/attestation/infrastructure/adapters/file-system-matrix-source-adapter.ts

@@ -0,0 +1,25 @@
+// @unit attestation
+// @layer infrastructure
+
+import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import type { MatrixSourcePort } from "../../application/ports/matrix-source-port.js";
+
+/**
+ * MatrixSourcePort の node:fs 実装（H16-03 / WI-227）。
+ * requirement-test-matrix.json を読み込み parse して返す。
+ * 不在・parse 不能は throw する（呼び出し側 usecase が fail-closed / [] に変換する）。
+ */
+export class FileSystemMatrixSourceAdapter implements MatrixSourcePort {
+  constructor(
+    private readonly baseDir: string,
+    private readonly defaultMatrixPath = ".harness/requirement-test-matrix.json",
+  ) {}
+
+  async load(matrixFilePath?: string): Promise<unknown> {
+    const rel = matrixFilePath && matrixFilePath.length > 0 ? matrixFilePath : this.defaultMatrixPath;
+    const absPath = isAbsolute(rel) ? rel : resolve(this.baseDir, rel);
+    const raw = await readFile(absPath, "utf8");
+    return JSON.parse(raw);
+  }
+}

package/scripts/harness/attestation/presentation/handlers/verify-attestation-handler.ts

@@ -55,6 +55,7 @@ function renderHuman(output: VerifyAttestationOutput, exitCode: 0 | 1 | 2): stri
   lines.push(`attestationDigest: ${mark(c.attestationDigest)}`);
   lines.push(`inputHashes      : ${mark(c.inputHashes)}`);
   lines.push(`granularity      : ${mark(c.granularity)}`);
+  lines.push(`acBoundScope     : ${mark(c.acBoundScope)}`);
   if (output.mismatches.length > 0) {
     lines.push("");
     lines.push("Mismatches:");

package/scripts/harness/ci-governance/infrastructure/adapters/validator-id-registry-adapter.ts

@@ -1,6 +1,7 @@
 // @unit ci-governance
 // @layer infrastructure
 // @work-item-id WI-124 / WI-128
+// @work-item-id WI-222
 
 import type { ValidatorIdRegistryPort } from '../../domain/ports/validator-id-registry-port.js';
 import { buildDefaultRegistry } from '../../../validator-system/composition-root.js';
@@ -8,6 +9,11 @@ import type { ValidatorDefinition } from '../../../validator-system/domain/value
 
 type PresetId = 'minimal' | 'standard' | 'strict';
 
+// WI-222 / HF2-05: default-OFF な advisory-only バリデータ。scheduled audit metadata や
+// preset 導出リストには含めない（default-OFF の不変条件を保つ）。runtime では
+// DEFAULT_CONFIG.layers.L4.validators に含まれないことで skip される。
+const ADVISORY_DEFAULT_OFF_IDS = new Set<string>(['L4-007']);
+
 export class ValidatorIdRegistryAdapter implements ValidatorIdRegistryPort {
   constructor(private readonly registryUrl?: string) {}
 
@@ -30,6 +36,8 @@ function normalizePreset(presetId: string): PresetId {
 }
 
 function isIncludedForPreset(definition: ValidatorDefinition, preset: PresetId, templateType: string): boolean {
+  // WI-222 / HF2-05: default-OFF advisory バリデータは全 preset で除外する。
+  if (ADVISORY_DEFAULT_OFF_IDS.has(definition.validatorId.value)) return false;
   if (preset === 'minimal') return false;
   if (definition.layer === 'L4') {
     if (templateType === 'consistency-check') return true;

package/scripts/harness/config-foundation/application/mappers/validator-system-config-mapper.ts

@@ -15,6 +15,7 @@ export function toValidatorSystemConfig(resolvedConfig: HarnessConfigV2 | undefi
     performance: 'L3-002',
     coverage: 'L3-003',
     nyquist: 'L3-004',
+    'ac-bound-coverage': 'L3-005',
   }, /^L3-\d{3}$/);
   const l4Validators = normalizeValidators(resolvedConfig.layers.L4.validators, {
     'drift-detect': 'L4-001',
@@ -49,6 +50,8 @@ export function toValidatorSystemConfig(resolvedConfig: HarnessConfigV2 | undefi
         validators: l3Validators.length > 0 ? l3Validators : ['L3-001', 'L3-002', 'L3-003', 'L3-004'],
         coverageThreshold: resolvedConfig.layers.L3.coverageThreshold,
         requirementMatrixPath: resolvedConfig.layers.L3.requirementMatrixPath,
+        // WI-227 / H16-03: L3-005 のスコープ（additive-safe。未設定は []）
+        acBoundStories: resolvedConfig.layers.L3.acBoundStories ?? [],
       },
       L4: {
         enabled: resolvedConfig.layers.L4.enabled,

package/scripts/harness/config-foundation/domain/harness-config.ts

@@ -83,6 +83,7 @@ export interface HarnessConfigResolvedDocument {
       validators: string[];
       coverageThreshold: number;
       requirementMatrixPath?: string;
+      acBoundStories?: readonly string[];
     };
     L4: {
       enabled: boolean;

package/scripts/harness/config-foundation/domain/value-objects/l3-config.ts

@@ -11,6 +11,7 @@ interface L3ConfigProps {
   readonly validators: string[];
   readonly coverageThreshold: number;
   readonly requirementMatrixPath?: string;
+  readonly acBoundStories?: readonly string[];
 }
 
 export class L3Config {
@@ -18,6 +19,7 @@ export class L3Config {
   readonly validators: readonly string[];
   readonly coverageThreshold: number;
   readonly requirementMatrixPath?: string;
+  readonly acBoundStories?: readonly string[];
 
   constructor(props: L3ConfigProps) {
     if (props.coverageThreshold < 0) {
@@ -40,6 +42,7 @@ export class L3Config {
     this.validators = Object.freeze([...props.validators]);
     this.coverageThreshold = props.coverageThreshold;
     this.requirementMatrixPath = props.requirementMatrixPath;
+    this.acBoundStories = props.acBoundStories ? Object.freeze([...props.acBoundStories]) : undefined;
     Object.freeze(this);
   }
 
@@ -48,6 +51,7 @@ export class L3Config {
     validators: string[];
     coverageThreshold: number;
     requirementMatrixPath?: string;
+    acBoundStories?: readonly string[];
   }): L3Config {
     return new L3Config(raw);
   }

package/scripts/harness/config-foundation/domain/value-objects/layers-config.ts

@@ -13,7 +13,7 @@ import { L4Config } from './l4-config.js';
 interface ResolvedLayersDocument {
   L1: { enabled: boolean; rules: Record<string, string> };
   L2: { enabled: boolean; validators: string[] };
-  L3: { enabled: boolean; validators: string[]; coverageThreshold: number; requirementMatrixPath?: string };
+  L3: { enabled: boolean; validators: string[]; coverageThreshold: number; requirementMatrixPath?: string; acBoundStories?: readonly string[] };
   L4: { enabled: boolean; validators: string[]; schedule: string };
 }
 

package/scripts/harness/config-foundation/infrastructure/schemas/harness-config-v2.schema.json

@@ -130,6 +130,13 @@
             "requirementMatrixPath": {
               "type": "string",
               "minLength": 1
+            },
+            "acBoundStories": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "uniqueItems": true
             }
           }
         },

package/scripts/harness/config-foundation/infrastructure/schemas/harness-config-v3.schema.json

@@ -140,6 +140,13 @@
             "requirementMatrixPath": {
               "type": "string",
               "minLength": 1
+            },
+            "acBoundStories": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "uniqueItems": true
             }
           }
         },

package/scripts/harness/harness-error/domain/errors/severity-downgrade-violation-error.ts

@@ -6,7 +6,7 @@ import { HarnessErrorDomainError } from './harness-error-domain-error.js';
 export class SeverityDowngradeViolationError extends HarnessErrorDomainError {
   constructor(requested: string, defaultSeverity: string) {
     super(
-      `severity の格下げは禁止されています: default="${defaultSeverity}" に対して "${requested}" が要求されました。`
+      `severity の格下げは禁止されています: default="${defaultSeverity}" に対して "${requested}" が要求されました。根拠: ADR-021`
     );
     this.name = 'SeverityDowngradeViolationError';
   }

package/scripts/harness/main.ts

@@ -2150,8 +2150,8 @@ async function main(): Promise<void> {
           force: hasFlag(args, "--force"),
           includeClaude,
           includeCodex,
-          includeHusky: personal ? false : true,
-          includeCi: personal ? false : true,
+          includeHusky: !personal,
+          includeCi: !personal,
           skillSet: skillSetRaw,
           workflow: parseWorkflowMode(workflowRaw),
           agent,

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

@@ -15,17 +15,43 @@ export interface RequirementSourceDto {
   readonly acIds: readonly string[];
 }
 
+/**
+ * HF2-05: @ac が story 外の AC を指した／複数 @story のため相対 AC が解決できなかった等の
+ * 「解決に失敗した @ac タグ」を advisory として記録する（error ではない）。
+ */
+export interface OrphanAcTagDto {
+  readonly storyId: string;
+  readonly filePath: string;
+  readonly testName?: string;
+  /** 解決できなかった生の @ac 表記（絶対 HXX-YY-N / 相対 AC-N のいずれか） */
+  readonly rawTag: string;
+  readonly reason: 'ac-not-in-story' | 'relative-multi-story';
+}
+
 export interface TestReferenceSourceDto {
   readonly storyId: string;
   readonly filePath: string;
   readonly testType: 'unit' | 'it' | 'scenario';
   readonly testName?: string;
+  /**
+   * HF2-05: このテストケースが個別に検証する AC の id 群（`AC-N` 形式）。
+   * @ac 注釈が無いテストは undefined（従来どおり file-fallback で全 AC にファンアウトする）。
+   */
+  readonly acIds?: readonly string[];
+  /** HF2-05: 解決に失敗した @ac タグ（advisory）。 */
+  readonly orphanAcTags?: readonly OrphanAcTagDto[];
 }
 
 export interface MatrixTestReferenceDto {
   readonly filePath: string;
   readonly testType: 'unit' | 'it' | 'scenario';
   readonly testName?: string;
+  /**
+   * HF2-05: この参照が AC 単位で紐づいたか（`"ac"`）、
+   * @ac 注釈が無く file-fallback で全 AC にファンアウトしたか（`"file"`）。
+   * 1.0 マトリクス（binding 無し）は `"file"` と等価に扱う（dedup 正規化）。
+   */
+  readonly binding?: 'ac' | 'file';
 }
 
 export interface MatrixAcMappingDto {
@@ -59,12 +85,28 @@ export type IntentCoverageStatus = DomainIntentCoverageStatus;
 
 export type IntentCoverageItemDto = DomainIntentCoverageItem;
 
+/**
+ * HF2-05: AC 単位トレーサビリティの advisory 集計。
+ * - total: マトリクス上の全 AC 数
+ * - acBound: 少なくとも 1 件の binding="ac" 参照を持つ AC 数
+ * - fileFallbackOnly: binding="ac" 参照を持たない（file-fallback のみで linked な）AC 数
+ */
+export interface AcLevelCoverageDto {
+  readonly total: number;
+  readonly acBound: number;
+  readonly fileFallbackOnly: number;
+}
+
 export interface MatrixGenerationReportDto {
   readonly missingTests: readonly MissingTestDto[];
   readonly orphanTests: readonly OrphanTestDto[];
   readonly unknownStories: readonly string[];
   readonly preservedReferences: number;
   readonly intentCoverage: readonly IntentCoverageItemDto[];
+  /** HF2-05: AC 単位カバレッジ集計（advisory）。 */
+  readonly acLevelCoverage: AcLevelCoverageDto;
+  /** HF2-05: 解決に失敗した @ac タグ（advisory）。 */
+  readonly orphanAcTags: readonly OrphanAcTagDto[];
 }
 
 export interface GenerateMatrixOutput {

package/scripts/harness/nyquist-validation/application/mappers/coverage-result-mapper.ts

@@ -7,19 +7,17 @@
 import type { CoverageResult } from '../../domain/value-objects/coverage-result.js';
 import type { CalculateCoverageOutput } from '../dto/calculate-coverage-output.js';
 
-export class CoverageResultMapper {
-  static toOutput(
-    result: CoverageResult,
-    threshold: { active: number } | null
-  ): CalculateCoverageOutput {
-    return {
-      coveredAcCount: result.coveredAcCount,
-      totalAcCount: result.totalAcCount,
-      ratePercent: result.toPercentage(),
-      uncoveredAcIds: result.uncoveredAcIds,
-      threshold: threshold?.active ?? null,
-      meetsThreshold:
-        threshold !== null ? result.meetsThreshold(threshold.active) : null,
-    };
-  }
+export function toCalculateCoverageOutput(
+  result: CoverageResult,
+  threshold: { active: number } | null
+): CalculateCoverageOutput {
+  return {
+    coveredAcCount: result.coveredAcCount,
+    totalAcCount: result.totalAcCount,
+    ratePercent: result.toPercentage(),
+    uncoveredAcIds: result.uncoveredAcIds,
+    threshold: threshold?.active ?? null,
+    meetsThreshold:
+      threshold !== null ? result.meetsThreshold(threshold.active) : null,
+  };
 }

package/scripts/harness/nyquist-validation/application/mappers/impact-analysis-result-mapper.ts

@@ -7,16 +7,16 @@
 import type { ImpactAnalysisResult } from '../../domain/value-objects/impact-analysis-result.js';
 import type { AnalyzeImpactOutput } from '../dto/analyze-impact-output.js';
 
-export class ImpactAnalysisResultMapper {
-  static toOutput(result: ImpactAnalysisResult): AnalyzeImpactOutput {
-    return {
-      storyId: result.storyId,
-      directTests: result.directTests.map((ref) => ({
-        filePath: ref.filePath,
-        testType: ref.testType,
-      })),
-      directMappingOnly: true,
-      found: !result.isEmpty(),
-    };
-  }
+export function toAnalyzeImpactOutput(
+  result: ImpactAnalysisResult
+): AnalyzeImpactOutput {
+  return {
+    storyId: result.storyId,
+    directTests: result.directTests.map((ref) => ({
+      filePath: ref.filePath,
+      testType: ref.testType,
+    })),
+    directMappingOnly: true,
+    found: !result.isEmpty(),
+  };
 }

package/scripts/harness/nyquist-validation/application/usecases/analyze-impact-usecase.ts

@@ -12,7 +12,7 @@ import { RequirementTestMatrix } from '../../domain/aggregates/requirement-test-
 import { StoryMapping } from '../../domain/entities/story-mapping.js';
 import { AcMapping } from '../../domain/value-objects/ac-mapping.js';
 import { TestReference } from '../../domain/value-objects/test-reference.js';
-import { ImpactAnalysisResultMapper } from '../mappers/impact-analysis-result-mapper.js';
+import { toAnalyzeImpactOutput } from '../mappers/impact-analysis-result-mapper.js';
 import type { AnalyzeImpactInput } from '../dto/analyze-impact-input.js';
 import type { AnalyzeImpactOutput } from '../dto/analyze-impact-output.js';
 
@@ -25,29 +25,29 @@ export interface AnalyzeImpactUseCaseDeps {
 
 function buildMatrix(data: unknown): RequirementTestMatrix {
   const obj = data as Record<string, unknown>;
-  const rawStories = Array.isArray(obj['stories']) ? obj['stories'] : (Array.isArray(obj['storyMappings']) ? obj['storyMappings'] : []);
+  const rawStories = Array.isArray(obj.stories) ? obj.stories : (Array.isArray(obj.storyMappings) ? obj.storyMappings : []);
 
   const storyMappings = (rawStories as unknown[]).map((s) => {
     const story = s as Record<string, unknown>;
-    const rawAcMappings = Array.isArray(story['storyMappings'])
-      ? story['storyMappings']
-      : (Array.isArray(story['acMappings']) ? story['acMappings'] : []);
+    const rawAcMappings = Array.isArray(story.storyMappings)
+      ? story.storyMappings
+      : (Array.isArray(story.acMappings) ? story.acMappings : []);
 
     const acMappings = (rawAcMappings as unknown[]).map((a) => {
       const acm = a as Record<string, unknown>;
-      const rawRefs = Array.isArray(acm['testReferences']) ? acm['testReferences'] : [];
+      const rawRefs = Array.isArray(acm.testReferences) ? acm.testReferences : [];
       const testReferences = (rawRefs as unknown[]).map((r) => {
         const ref = r as Record<string, unknown>;
         return TestReference.create({
-          filePath: String(ref['filePath'] ?? ''),
-          testType: String(ref['testType'] ?? ''),
+          filePath: String(ref.filePath ?? ''),
+          testType: String(ref.testType ?? ''),
         });
       });
-      return AcMapping.create({ acId: String(acm['acId'] ?? ''), testReferences });
+      return AcMapping.create({ acId: String(acm.acId ?? ''), testReferences });
     });
 
     return StoryMapping.create({
-      storyId: String(story['storyId'] ?? ''),
+      storyId: String(story.storyId ?? ''),
       acMappings,
     });
   });
@@ -77,6 +77,6 @@ export class AnalyzeImpactUseCase {
     const matrix = buildMatrix(rawData);
     const result = this.impactAnalysisService.analyze(matrix, input.storyId);
 
-    return ImpactAnalysisResultMapper.toOutput(result);
+    return toAnalyzeImpactOutput(result);
   }
 }

package/scripts/harness/nyquist-validation/application/usecases/calculate-coverage-usecase.ts

@@ -13,7 +13,7 @@ import { RequirementTestMatrix } from '../../domain/aggregates/requirement-test-
 import { StoryMapping } from '../../domain/entities/story-mapping.js';
 import { AcMapping } from '../../domain/value-objects/ac-mapping.js';
 import { TestReference } from '../../domain/value-objects/test-reference.js';
-import { CoverageResultMapper } from '../mappers/coverage-result-mapper.js';
+import { toCalculateCoverageOutput } from '../mappers/coverage-result-mapper.js';
 import type { CalculateCoverageInput } from '../dto/calculate-coverage-input.js';
 import type { CalculateCoverageOutput } from '../dto/calculate-coverage-output.js';
 
@@ -27,29 +27,29 @@ export interface CalculateCoverageUseCaseDeps {
 
 function buildMatrix(data: unknown): RequirementTestMatrix {
   const obj = data as Record<string, unknown>;
-  const rawStories = Array.isArray(obj['stories']) ? obj['stories'] : (Array.isArray(obj['storyMappings']) ? obj['storyMappings'] : []);
+  const rawStories = Array.isArray(obj.stories) ? obj.stories : (Array.isArray(obj.storyMappings) ? obj.storyMappings : []);
 
   const storyMappings = (rawStories as unknown[]).map((s) => {
     const story = s as Record<string, unknown>;
-    const rawAcMappings = Array.isArray(story['storyMappings'])
-      ? story['storyMappings']
-      : (Array.isArray(story['acMappings']) ? story['acMappings'] : []);
+    const rawAcMappings = Array.isArray(story.storyMappings)
+      ? story.storyMappings
+      : (Array.isArray(story.acMappings) ? story.acMappings : []);
 
     const acMappings = (rawAcMappings as unknown[]).map((a) => {
       const acm = a as Record<string, unknown>;
-      const rawRefs = Array.isArray(acm['testReferences']) ? acm['testReferences'] : [];
+      const rawRefs = Array.isArray(acm.testReferences) ? acm.testReferences : [];
       const testReferences = (rawRefs as unknown[]).map((r) => {
         const ref = r as Record<string, unknown>;
         return TestReference.create({
-          filePath: String(ref['filePath'] ?? ''),
-          testType: String(ref['testType'] ?? ''),
+          filePath: String(ref.filePath ?? ''),
+          testType: String(ref.testType ?? ''),
         });
       });
-      return AcMapping.create({ acId: String(acm['acId'] ?? ''), testReferences });
+      return AcMapping.create({ acId: String(acm.acId ?? ''), testReferences });
     });
 
     return StoryMapping.create({
-      storyId: String(story['storyId'] ?? ''),
+      storyId: String(story.storyId ?? ''),
       acMappings,
     });
   });
@@ -86,6 +86,6 @@ export class CalculateCoverageUseCase {
       threshold = await this.coverageThresholdPort.getThreshold();
     }
 
-    return CoverageResultMapper.toOutput(coverageResult, threshold);
+    return toCalculateCoverageOutput(coverageResult, threshold);
   }
 }

package/scripts/harness/nyquist-validation/application/usecases/check-ac-coverage-gate-usecase.ts

@@ -24,29 +24,29 @@ export interface CheckAcCoverageGateUseCaseDeps {
 
 function buildMatrix(data: unknown): RequirementTestMatrix {
   const obj = data as Record<string, unknown>;
-  const rawStories = Array.isArray(obj['stories']) ? obj['stories'] : (Array.isArray(obj['storyMappings']) ? obj['storyMappings'] : []);
+  const rawStories = Array.isArray(obj.stories) ? obj.stories : (Array.isArray(obj.storyMappings) ? obj.storyMappings : []);
 
   const storyMappings = (rawStories as unknown[]).map((s) => {
     const story = s as Record<string, unknown>;
-    const rawAcMappings = Array.isArray(story['storyMappings'])
-      ? story['storyMappings']
-      : (Array.isArray(story['acMappings']) ? story['acMappings'] : []);
+    const rawAcMappings = Array.isArray(story.storyMappings)
+      ? story.storyMappings
+      : (Array.isArray(story.acMappings) ? story.acMappings : []);
 
     const acMappings = (rawAcMappings as unknown[]).map((a) => {
       const acm = a as Record<string, unknown>;
-      const rawRefs = Array.isArray(acm['testReferences']) ? acm['testReferences'] : [];
+      const rawRefs = Array.isArray(acm.testReferences) ? acm.testReferences : [];
       const testReferences = (rawRefs as unknown[]).map((r) => {
         const ref = r as Record<string, unknown>;
         return TestReference.create({
-          filePath: String(ref['filePath'] ?? ''),
-          testType: String(ref['testType'] ?? ''),
+          filePath: String(ref.filePath ?? ''),
+          testType: String(ref.testType ?? ''),
         });
       });
-      return AcMapping.create({ acId: String(acm['acId'] ?? ''), testReferences });
+      return AcMapping.create({ acId: String(acm.acId ?? ''), testReferences });
     });
 
     return StoryMapping.create({
-      storyId: String(story['storyId'] ?? ''),
+      storyId: String(story.storyId ?? ''),
       acMappings,
     });
   });

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

@@ -5,10 +5,12 @@
 
 import type { RequirementIntentCoverageService } from '../../domain/services/requirement-intent-coverage-service.js';
 import type {
+  AcLevelCoverageDto,
   GenerateMatrixOutput,
   MatrixAcMappingDto,
   MatrixStoryDto,
   MatrixTestReferenceDto,
+  OrphanAcTagDto,
   RequirementSourceDto,
   RequirementTestMatrixDto,
   TestReferenceSourceDto,
@@ -42,8 +44,12 @@ export interface GenerateRequirementTestMatrixUseCaseDeps {
   readonly now?: () => Date;
 }
 
+// HF2-05: dedup キーは binding を含める。1.0 マトリクス（binding undefined）は
+// "file" に正規化するため、binding を持たない既存参照と file-fallback 生成参照が
+// 同一キーに畳まれ、意図しない重複（＝L3-004 の testReferences 件数変化）を防ぐ。
 function referenceKey(reference: MatrixTestReferenceDto): string {
-  return `${reference.filePath}\0${reference.testType}\0${reference.testName ?? ''}`;
+  const binding = reference.binding ?? 'file';
+  return `${reference.filePath}\0${reference.testType}\0${reference.testName ?? ''}\0${binding}`;
 }
 
 function mergeReferences(
@@ -112,30 +118,77 @@ export class GenerateRequirementTestMatrixUseCase {
     }
 
     let preservedReferences = 0;
+    // HF2-05: 各 AC の ac-bound 判定を集計するためのアキュムレータ。
+    let acLevelTotal = 0;
+    let acLevelBound = 0;
+    let acLevelFileFallbackOnly = 0;
+    const orphanAcTags: OrphanAcTagDto[] = [];
     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,
-        }));
+        // HF2-05:
+        // - acIds を持つ参照は、その acId を含むときだけ binding="ac" で紐づく（ファンアウトしない）。
+        // - acIds を持たない参照は従来どおり全 AC へ binding="file" でファンアウトする（L3-004 不変）。
+        const generatedReferences: MatrixTestReferenceDto[] = [];
+        let hasAcBound = false;
+        for (const reference of storyReferences) {
+          const acIds = reference.acIds;
+          if (acIds && acIds.length > 0) {
+            if (acIds.includes(acId)) {
+              generatedReferences.push({
+                filePath: reference.filePath,
+                testType: reference.testType,
+                testName: reference.testName,
+                binding: 'ac',
+              });
+              hasAcBound = true;
+            }
+            continue;
+          }
+          generatedReferences.push({
+            filePath: reference.filePath,
+            testType: reference.testType,
+            testName: reference.testName,
+            binding: 'file',
+          });
+        }
         const existingReferences = normalizeExistingReferences(existingMatrix, requirement.storyId, acId);
         const merged = mergeReferences(generatedReferences, existingReferences);
         preservedReferences += merged.preserved;
+        // AC 単位カバレッジ集計（advisory）: linked（参照 1 件以上）な AC のみ分母に数える。
+        if (merged.references.length > 0) {
+          acLevelTotal += 1;
+          if (hasAcBound) {
+            acLevelBound += 1;
+          } else {
+            acLevelFileFallbackOnly += 1;
+          }
+        }
         return {
           acId,
           testReferences: merged.references,
         };
       });
+      // 解決に失敗した @ac タグを advisory として集約する。
+      for (const reference of storyReferences) {
+        if (reference.orphanAcTags) orphanAcTags.push(...reference.orphanAcTags);
+      }
       return {
         storyId: requirement.storyId,
         storyMappings: Object.freeze(storyMappings),
       };
     });
+    const acLevelCoverage: AcLevelCoverageDto = {
+      total: acLevelTotal,
+      acBound: acLevelBound,
+      fileFallbackOnly: acLevelFileFallbackOnly,
+    };
 
     const matrix: RequirementTestMatrixDto = {
-      version: '1.0',
+      // HF2-05: binding フィールドを付与するため schema 1.1 として出力する。
+      // 1.1 は 1.0 に対し optional な binding のみ追加であり、L3-004 の判定（各 AC に
+      // testReference が 1 件以上あるか）には一切影響しない。
+      version: '1.1',
       generatedAt: this.now().toISOString(),
       stories: Object.freeze(stories),
     };
@@ -150,6 +203,8 @@ export class GenerateRequirementTestMatrixUseCase {
       unknownStories: [...new Set(orphanTests.map((test) => test.storyId))],
       preservedReferences,
       intentCoverage,
+      acLevelCoverage,
+      orphanAcTags: Object.freeze(orphanAcTags),
     };
 
     if (input.write) {

package/scripts/harness/nyquist-validation/domain/aggregates/requirement-test-matrix.ts

@@ -5,7 +5,7 @@
  * requirement-test-matrix の集約ルート
  */
 import { DuplicateStoryMappingError } from '../errors/duplicate-story-mapping-error.js';
-import { StoryMapping } from '../entities/story-mapping.js';
+import type { StoryMapping } from '../entities/story-mapping.js';
 
 export interface RequirementTestMatrixCreateProps {
   readonly storyMappings: readonly StoryMapping[];

package/scripts/harness/nyquist-validation/domain/entities/story-mapping.ts

@@ -4,7 +4,7 @@
  *
  * ストーリー単位のAC→テスト参照マッピングエンティティ
  */
-import { AcMapping, type RawAcMapping } from '../value-objects/ac-mapping.js';
+import type { AcMapping, RawAcMapping } from '../value-objects/ac-mapping.js';
 
 export interface StoryMappingCreateProps {
   readonly storyId: string;

package/scripts/harness/nyquist-validation/domain/services/ac-coverage-gate-policy.ts

@@ -5,7 +5,7 @@
  * AC網羅ゲート判定ポリシー
  * validator-system の L3-004 が実行主体として呼び出す公開ポリシー
  */
-import { RequirementTestMatrix } from '../aggregates/requirement-test-matrix.js';
+import type { RequirementTestMatrix } from '../aggregates/requirement-test-matrix.js';
 
 export interface NyquistHarnessError {
   readonly code: string;

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

@@ -4,7 +4,7 @@
  *
  * AC網羅率算出サービス（純粋な算出ロジック）
  */
-import { RequirementTestMatrix } from '../aggregates/requirement-test-matrix.js';
+import type { RequirementTestMatrix } from '../aggregates/requirement-test-matrix.js';
 import { CoverageResult } from '../value-objects/coverage-result.js';
 
 export class CoverageCalculationService {

package/scripts/harness/nyquist-validation/domain/services/impact-analysis-service.ts

@@ -4,9 +4,9 @@
  *
  * テストケース逆引きサービス（v1: 直接マッピングのみ）
  */
-import { RequirementTestMatrix } from '../aggregates/requirement-test-matrix.js';
+import type { RequirementTestMatrix } from '../aggregates/requirement-test-matrix.js';
 import { ImpactAnalysisResult } from '../value-objects/impact-analysis-result.js';
-import { TestReference } from '../value-objects/test-reference.js';
+import type { TestReference } from '../value-objects/test-reference.js';
 
 export class ImpactAnalysisService {
   analyze(matrix: RequirementTestMatrix, storyId: string): ImpactAnalysisResult {