phasegate 0.165.0 → 0.167.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.167.0] - 2026-07-05
+
+### Added
+
+- **WI-222 / HF2-05 — AC-level traceability (`@ac` contract, additive)** — adds a mechanical (AST-free, ADR-019-compliant) `@ac` annotation contract so individual test cases can record which acceptance criterion they assert. The `TypeScriptTestReferenceSourceAdapter` parses absolute (`// @ac H05-02-1`), story-relative (`// @ac AC-2`, resolved only when the file has exactly one `@story`), and multi-AC (`// @ac H05-02-1 H05-02-2`) forms via a positional scan that binds the nearest preceding `@ac` since the last `it(`/`test(`. New DTO fields: `TestReferenceSourceDto.acIds`, `MatrixTestReferenceDto.binding` (`"ac" | "file"`), report `acLevelCoverage` (`{ total, acBound, fileFallbackOnly }`) and `orphanAcTags`.
+- **WI-222 / HF2-05 — L4-007 `ac-level-traceability` advisory validator (`validator-system` unit)** — a new L4 validator that surfaces file-fallback-only ACs and orphan `@ac` tags as **warning-severity findings only (never errors)**. It is **default-OFF** (registered in the registry but not in the default/standard/strict enabled validator sets, so it always `skipped=true` in `ci-check`), **advisory/non-blocking**, and **attestation-trust-excluded** (the attestation `GranularityDerivationService` re-derives granularity solely from the static `KNOWN_LIMITATIONS_REGISTRY`, which whitelists only L3-004; L4-007 is ignored by construction). New domain service `AcLevelTraceabilityService`, port `AcLevelTraceabilityPort`, and infrastructure adapter `NyquistAcLevelTraceabilityAdapter`.
+- **requirement-test-matrix schema 1.1** — adds an optional `binding` enum (`["ac","file"]`) on `testReferences`, keeping `additionalProperties:false` and full backward compatibility so existing 1.0 matrices (without `binding`) still validate.
+
+### Changed
+
+- **L3-004 verdict preserved (byte-identical)** — references without `@ac` continue to fan out to all ACs with `binding:"file"` exactly as before; the reference dedup key now incorporates `binding` and normalizes `undefined → "file"` so 1.0 matrices without `binding` produce no spurious duplicates. Proven invariant by golden-matrix comparison (all 358 pre-existing ACs: identical coverage, 0 missing before/after). Generated matrix `version` bumped `1.0 → 1.1`.
+- **Attestation granularity unchanged** — `granularity.traceability.level` remains `"file"`; `level:"ac"` is design-gated on a future fail-closed **L3-005 "AC-bound coverage"** validator flipping the static registry binary/global (documented in `nyquist-validation/logical_design.md` and the L3-004 ratchet R5 row).
+
+## [0.166.0] - 2026-07-05
+
+### Fixed
+
+- **WI-220 — noUselessTernary dogfooding fix (`harness-api` unit, `scripts/harness/main.ts`)** — replaces two `lint/complexity/noUselessTernary` violations in the `setup` install path (`includeHusky: personal ? false : true` / `includeCi: personal ? false : true`) with the behavior-preserving `!personal`. Clears self-repo biome lint debt; `npx biome lint scripts/harness/main.ts` now reports 0 errors. No behavior change — `!personal` is semantically identical to `personal ? false : true`.
+
 ## [0.165.0] - 2026-07-05
 
 ### Added

package/docs/contracts/requirement-test-matrix.schema.json

@@ -48,6 +48,11 @@
                       },
                       "testName": {
                         "type": "string"
+                      },
+                      "binding": {
+                        "type": "string",
+                        "enum": ["ac", "file"],
+                        "description": "HF2-05 (schema 1.1): AC単位で紐づいた参照は 'ac'、@ac注釈なしで全ACにファンアウトした参照は 'file'。省略可（1.0後方互換）。"
                       }
                     }
                   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.165.0",
+  "version": "0.167.0",
   "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/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/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/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/infrastructure/adapters/type-script-test-reference-source-adapter.ts

@@ -1,17 +1,31 @@
 // @layer infrastructure
 // @unit nyquist-validation
 // @work-item-id WI-125
+// @work-item-id WI-222
 
 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';
+import type { OrphanAcTagDto, TestReferenceSourceDto } from '../../application/dto/generate-matrix-output.js';
 
 // StoryId は HXX-XX 形式に加え Phase 2 拡張 Epic の HF\d+-XX 形式も許容する
 // （markdown-requirement-source-adapter の STORY_HEADING / traceability-model の StoryId 正規表現と整合）。
 // 旧 /H\d{2}-\d{2}/ は HF2-01 等を取りこぼし、正しく注釈されたテストが「テストなし」と誤判定されていた。
 const STORY_TAG = /@story(?:-id)?\s+(H(?:F\d+|\d{2})-\d{2})/;
-const TEST_NAME = /\b(?:it|test)(?:\.each\([^)]*\))?\s*\(\s*['"`]([^'"`]+)['"`]/g;
+const STORY_TAG_GLOBAL = /@story(?:-id)?\s+(H(?:F\d+|\d{2})-\d{2})/g;
+// HF2-05: @ac は 1 行に複数 AC を許容する。行末までの全トークンを個別に解釈する。
+// 各トークンは絶対形式 `HXX-YY-N`（story-relative でない）または相対形式 `AC-N`。
+const AC_TAG_LINE = /@ac\s+(.+?)\s*$/;
+const AC_ABSOLUTE_TOKEN = /^(H(?:F\d+|\d{2})-\d{2})-([1-9][0-9]*)$/;
+const AC_RELATIVE_TOKEN = /^AC-([1-9][0-9]*)$/;
+// テストケース開始行の検出（it / test、.each やスペースを許容）。
+const TEST_START = /\b(?:it|test)(?:\.each\([^)]*\))?\s*\(\s*['"`]([^'"`]+)['"`]/;
+
+interface PendingAcToken {
+  readonly rawTag: string;
+  readonly resolvedAcId: string | null;
+  readonly reason: OrphanAcTagDto['reason'] | null;
+}
 
 async function collectTestFiles(root: string): Promise<readonly string[]> {
   const rootStat = await stat(root).catch(() => null);
@@ -43,15 +57,103 @@ export class TypeScriptTestReferenceSourceAdapter implements TestReferenceSource
       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 });
+      // HF2-05: 相対 @ac (AC-N) はファイルに @story がちょうど 1 件のときのみ解決する。
+      const storyCount = [...content.matchAll(STORY_TAG_GLOBAL)].length;
+      references.push(...this.scanFile({ content, storyId, relativePath, testType, storyCount }));
+    }
+    return Object.freeze(references);
+  }
+
+  /**
+   * HF2-05: ファイル内容を行単位で走査し、直前の it()/test() 以降に現れた @ac を
+   * 「最近接の @ac」として次のテストケースへ紐づける（positional scan）。
+   * @ac が無いテストは従来どおり acIds 無しの参照を生成する。
+   */
+  private scanFile(args: {
+    content: string;
+    storyId: string;
+    relativePath: string;
+    testType: 'unit' | 'it' | 'scenario';
+    storyCount: number;
+  }): TestReferenceSourceDto[] {
+    const { content, storyId, relativePath, testType, storyCount } = args;
+    const lines = content.split('\n');
+    const result: TestReferenceSourceDto[] = [];
+    let pending: PendingAcToken[] = [];
+
+    for (const line of lines) {
+      const acMatch = line.match(AC_TAG_LINE);
+      if (acMatch) {
+        for (const token of acMatch[1].trim().split(/\s+/)) {
+          if (token.length > 0) pending.push(this.resolveAcToken(token, storyId, storyCount));
+        }
         continue;
       }
-      for (const testName of names) {
-        references.push({ storyId, filePath: relativePath, testType, testName });
+      const testMatch = line.match(TEST_START);
+      if (testMatch) {
+        result.push(this.buildReference({
+          storyId,
+          relativePath,
+          testType,
+          testName: testMatch[1],
+          pending,
+        }));
+        pending = [];
       }
     }
-    return Object.freeze(references);
+
+    // it()/test() が 1 件も無い注釈済みファイルは、file-level 参照 1 件を維持する（従来挙動）。
+    if (result.length === 0) {
+      result.push({ storyId, filePath: relativePath, testType });
+    }
+    return result;
+  }
+
+  private buildReference(args: {
+    storyId: string;
+    relativePath: string;
+    testType: 'unit' | 'it' | 'scenario';
+    testName: string;
+    pending: readonly PendingAcToken[];
+  }): TestReferenceSourceDto {
+    const { storyId, relativePath, testType, testName, pending } = args;
+    const base: TestReferenceSourceDto = { storyId, filePath: relativePath, testType, testName };
+    if (pending.length === 0) return base;
+
+    const acIds = pending.filter((p) => p.resolvedAcId !== null).map((p) => p.resolvedAcId as string);
+    const orphanAcTags: OrphanAcTagDto[] = pending
+      .filter((p) => p.resolvedAcId === null && p.reason !== null)
+      .map((p) => ({ storyId, filePath: relativePath, testName, rawTag: p.rawTag, reason: p.reason as OrphanAcTagDto['reason'] }));
+
+    return {
+      ...base,
+      ...(acIds.length > 0 ? { acIds: Object.freeze([...new Set(acIds)]) } : {}),
+      ...(orphanAcTags.length > 0 ? { orphanAcTags: Object.freeze(orphanAcTags) } : {}),
+    };
+  }
+
+  /**
+   * 1 個の @ac トークンを解釈する。
+   * - 絶対形式 `HXX-YY-N`: story が一致すれば `AC-N` に解決、不一致なら ac-not-in-story orphan。
+   * - 相対形式 `AC-N`: @story が単一なら `AC-N` に解決、複数なら relative-multi-story orphan。
+   */
+  private resolveAcToken(token: string, storyId: string, storyCount: number): PendingAcToken {
+    const absolute = token.match(AC_ABSOLUTE_TOKEN);
+    if (absolute) {
+      const [, tokenStory, acNumber] = absolute;
+      if (tokenStory === storyId) {
+        return { rawTag: token, resolvedAcId: `AC-${acNumber}`, reason: null };
+      }
+      return { rawTag: token, resolvedAcId: null, reason: 'ac-not-in-story' };
+    }
+    const relative = token.match(AC_RELATIVE_TOKEN);
+    if (relative) {
+      if (storyCount === 1) {
+        return { rawTag: token, resolvedAcId: `AC-${relative[1]}`, reason: null };
+      }
+      return { rawTag: token, resolvedAcId: null, reason: 'relative-multi-story' };
+    }
+    // 形式不明トークンは advisory orphan として ac-not-in-story 扱い。
+    return { rawTag: token, resolvedAcId: null, reason: 'ac-not-in-story' };
   }
 }

package/scripts/harness/nyquist-validation/infrastructure/schema/matrix-schema-loader.ts

@@ -1,8 +1,13 @@
 /**
  * @layer infrastructure
  * @unit nyquist-validation
+ * @work-item-id WI-222
  *
  * requirement-test-matrix.schema.json ローダー（シングルトンキャッシュ付き）
+ *
+ * HF2-05 (schema 1.1): testReferences に optional な `binding` enum（"ac"|"file"）を追加。
+ * 1.1 は追加フィールドが optional かつ additionalProperties:false を満たすため、
+ * `binding` を持たない 1.0 マトリクスも引き続き検証を通過する（後方互換）。
  */
 import { readFile } from 'node:fs/promises';
 import { resolve, join } from 'node:path';

package/scripts/harness/validator-system/application/use-cases/run-l4-validators-usecase.ts

@@ -23,6 +23,8 @@ import type { DeadCodeDetectionService } from '../../domain/services/l4/dead-cod
 import type { ArchitectureSemanticAnalysisService } from '../../domain/services/l4/architecture-semantic-analysis-service.js';
 import { SkillCatalogDriftService } from '../../domain/services/l4/skill-catalog-drift-service.js';
 import type { SkillCatalogDriftPort } from '../../domain/ports/skill-catalog-drift-port.js';
+import { AcLevelTraceabilityService } from '../../domain/services/l4/ac-level-traceability-service.js';
+import type { AcLevelTraceabilityPort } from '../../domain/ports/ac-level-traceability-port.js';
 
 interface ScheduledHarnessErrorContract {
   readonly severity: string;
@@ -73,6 +75,7 @@ export interface RunL4ValidatorsUseCaseDeps {
   deadCodeDetectionService?: DeadCodeDetectionService;
   architectureSemanticAnalysisService?: ArchitectureSemanticAnalysisService;
   skillCatalogDriftPort?: SkillCatalogDriftPort;
+  acLevelTraceabilityPort?: AcLevelTraceabilityPort;
   pathRoots?: {
     readonly inceptionRoot: string;
     readonly designRoot: string;
@@ -92,6 +95,8 @@ export class RunL4ValidatorsUseCase {
   private readonly architectureSemanticAnalysisService?: ArchitectureSemanticAnalysisService;
   private readonly skillCatalogDriftPort?: SkillCatalogDriftPort;
   private readonly skillCatalogDriftService = new SkillCatalogDriftService();
+  private readonly acLevelTraceabilityPort?: AcLevelTraceabilityPort;
+  private readonly acLevelTraceabilityService = new AcLevelTraceabilityService();
   private readonly pathRoots: { readonly inceptionRoot: string; readonly designRoot: string };
   private readonly checkDocFreshnessUseCase?: CheckDocFreshnessUseCasePort;
   private readonly validateDocPointersUseCase?: ValidateDocPointersUseCasePort;
@@ -107,6 +112,7 @@ export class RunL4ValidatorsUseCase {
     this.deadCodeDetectionService = deps.deadCodeDetectionService;
     this.architectureSemanticAnalysisService = deps.architectureSemanticAnalysisService;
     this.skillCatalogDriftPort = deps.skillCatalogDriftPort;
+    this.acLevelTraceabilityPort = deps.acLevelTraceabilityPort;
     this.pathRoots = deps.pathRoots ?? {
       inceptionRoot: 'docs/inception',
       designRoot: 'docs/product/construction',
@@ -263,6 +269,23 @@ export class RunL4ValidatorsUseCase {
       }
     }
 
+    if (this.acLevelTraceabilityPort) {
+      const l4007Result = overrideMap.get('L4-007');
+      // default-OFF: L4-007 が enabled validator set に含まれず skip される場合は上書きしない。
+      if (l4007Result && !l4007Result.skipped) {
+        const snapshot = await this.acLevelTraceabilityPort.collect();
+        const report = this.acLevelTraceabilityService.check(snapshot);
+        // advisory-only: finding があっても severity は必ず warning。overall gate は
+        // failOnWarning=false（既定）で PASS のまま（ADR-019 §5）。finding が無ければ PASS。
+        overrideMap.set(
+          'L4-007',
+          report.hasFindings()
+            ? ValidationResult.fail(ValidatorId.create('L4-007'), report.toHarnessErrors(), 0)
+            : ValidationResult.pass(ValidatorId.create('L4-007'), 0),
+        );
+      }
+    }
+
     const finalResults = definitions.map(
       (definition) => overrideMap.get(definition.validatorId.value) ?? ValidationResult.skip(definition.validatorId),
     );

package/scripts/harness/validator-system/composition-root.ts

@@ -39,6 +39,7 @@ import { AdrFoundationReferenceAdapter } from './infrastructure/adapters/adr-fou
 import { ImportGraphSourceAnalysisAdapter } from './infrastructure/adapters/import-graph-source-analysis-adapter.js';
 import { FileSystemArchitectureSemanticSourceAdapter } from './infrastructure/adapters/file-system-architecture-semantic-source-adapter.js';
 import { FileSystemSkillCatalogDriftAdapter } from './infrastructure/adapters/file-system-skill-catalog-drift-adapter.js';
+import { NyquistAcLevelTraceabilityAdapter } from './infrastructure/adapters/nyquist-ac-level-traceability-adapter.js';
 import { FileSystemWorkItemReflectionAdapter } from './infrastructure/adapters/file-system-work-item-reflection-adapter.js';
 import { DriftDetectionService } from './domain/services/l4/drift-detection-service.js';
 import { ConsistencyCheckService } from './domain/services/l4/consistency-check-service.js';
@@ -117,6 +118,9 @@ export function buildDefaultRegistry(): ValidatorRegistry {
     createDef('L4-004', 'L4', 'always'),
     createDef('L4-005', 'L4', 'always'),
     createDef('L4-006', 'L4', 'always', 'SkillCatalogDriftPort'),
+    // WI-222 / HF2-05: L4-007 (ac-level-traceability) は registry には登録するが
+    // default-OFF（DEFAULT_CONFIG.layers.L4.validators に含めない）。advisory-only。
+    createDef('L4-007', 'L4', 'always', 'AcLevelTraceabilityPort'),
   ];
 
   return new ValidatorRegistry(definitions);
@@ -206,6 +210,11 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
   const sourceAnalysisPort = new ImportGraphSourceAnalysisAdapter();
   const architectureSemanticSourcePort = new FileSystemArchitectureSemanticSourceAdapter();
   const skillCatalogDriftPort = new FileSystemSkillCatalogDriftAdapter(cwd);
+  // WI-222 / HF2-05: L4-007 (advisory) 用の AC 単位トレーサビリティ port。
+  // matrix path は L3-004 と同じ config キーを参照する。
+  const acLevelTraceabilityPort = new NyquistAcLevelTraceabilityAdapter({
+    matrixFilePath: configData.layers?.L3?.requirementMatrixPath ?? '.harness/requirement-test-matrix.json',
+  });
   const workItemReflectionPort = new FileSystemWorkItemReflectionAdapter(cwd);
 
   const driftDetectionService = new DriftDetectionService({
@@ -236,6 +245,7 @@ export function createValidatorSystemModule(config?: object): ValidatorSystemMod
     deadCodeDetectionService,
     architectureSemanticAnalysisService,
     skillCatalogDriftPort,
+    acLevelTraceabilityPort,
     pathRoots: {
       inceptionRoot: inceptionDocsRoot,
       designRoot: designDocsRoot,

package/scripts/harness/validator-system/domain/ports/ac-level-traceability-port.ts

@@ -0,0 +1,14 @@
+/**
+ * @layer domain
+ * @unit validator-system
+ * @work-item-id WI-222
+ *
+ * HF2-05 / L4-007: nyquist-validation のマトリクス生成レポートを AC 単位トレーサビリティの
+ * snapshot へ橋渡しする port。実装（infrastructure adapter）が nyquist の generate-matrix
+ * usecase を実行し、acLevelCoverage / fileFallbackOnlyAcs / orphanAcTags を収集する。
+ */
+import type { AcLevelTraceabilitySnapshot } from '../services/l4/ac-level-traceability-service.js';
+
+export interface AcLevelTraceabilityPort {
+  collect(): Promise<AcLevelTraceabilitySnapshot>;
+}

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 [];
+    }
+  }
+}