phasegate 0.254.0 → 0.283.0

package/scripts/harness/validator-system/domain/ports/world-constraint-admission-policy-port.ts

@@ -0,0 +1,28 @@
+// @unit validator-system
+// @layer domain
+// @work-item-id WI-301
+
+export type WorldAdmissionClassification = "adopted-legacy" | "new-structural" | "invalid-declaration" | "waived";
+
+export interface WorldConstraintAdmissionObligation {
+  readonly ruleId: string;
+  readonly violationFingerprint: string;
+  readonly constraintId: string | null;
+  readonly classification: WorldAdmissionClassification;
+}
+
+export interface WorldConstraintAdmissionDiagnostic {
+  readonly code: string;
+  readonly path: string;
+  readonly message: string;
+  readonly scope: "constraint" | "other";
+}
+
+export interface WorldConstraintAdmissionObservation {
+  readonly obligations: readonly WorldConstraintAdmissionObligation[];
+  readonly diagnostics: readonly WorldConstraintAdmissionDiagnostic[];
+}
+
+export interface WorldConstraintAdmissionPolicyPort {
+  collect(): Promise<WorldConstraintAdmissionObservation>;
+}

package/scripts/harness/validator-system/domain/ports/world-constraint-rederivation-policy-port.ts

@@ -0,0 +1,11 @@
+// @unit validator-system
+// @layer domain
+// @work-item-id WI-302
+
+import type { WorldConstraintAdmissionObservation } from "./world-constraint-admission-policy-port.js";
+
+export type WorldConstraintRederivationObservation = WorldConstraintAdmissionObservation;
+
+export interface WorldConstraintRederivationPolicyPort {
+  collect(): Promise<WorldConstraintRederivationObservation>;
+}

package/scripts/harness/validator-system/domain/services/design-change-declaration-policy.ts

@@ -0,0 +1,75 @@
+// @unit validator-system
+// @layer domain
+// @work-item-id WI-305
+
+export interface DesignChangedFragmentInput {
+  readonly corpusRole: "product" | "inception";
+  readonly declaredKey: string;
+  readonly path: string;
+  readonly workItemIds: readonly string[];
+}
+
+export interface DesignPinnedEndpointInput {
+  readonly constraintId: string;
+  readonly endpoint: "claimant" | "premise";
+  readonly corpusRole: "product" | "inception";
+  readonly declaredKey: string;
+}
+
+export interface DesignChangeDeclarationFinding {
+  readonly code: "design-change-declaration-missing";
+  readonly corpusRole: "product" | "inception";
+  readonly declaredKey: string;
+  readonly path: string;
+  readonly expectedWorkItemIds: readonly string[];
+  readonly constraintIds: readonly string[];
+}
+
+export interface DesignChangeDeclarationEvaluation {
+  readonly checkedFragmentCount: number;
+  readonly findings: readonly DesignChangeDeclarationFinding[];
+}
+
+export interface DesignChangeDeclarationInput {
+  readonly changedFragments: readonly DesignChangedFragmentInput[];
+  readonly pinnedEndpoints: readonly DesignPinnedEndpointInput[];
+  readonly trailerWorkItemIds: readonly string[];
+}
+
+const compare = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+const keyOf = (value: { readonly corpusRole: string; readonly declaredKey: string }): string =>
+  `${value.corpusRole}\u0000${value.declaredKey}`;
+const uniqueSorted = (values: readonly string[]): readonly string[] =>
+  Object.freeze([...new Set(values)].sort(compare));
+
+export class DesignChangeDeclarationPolicy {
+  evaluate(input: DesignChangeDeclarationInput): DesignChangeDeclarationEvaluation {
+    const endpointsByFragment = new Map<string, DesignPinnedEndpointInput[]>();
+    for (const endpoint of input.pinnedEndpoints) {
+      const key = keyOf(endpoint);
+      const current = endpointsByFragment.get(key) ?? [];
+      current.push(endpoint);
+      endpointsByFragment.set(key, current);
+    }
+    const trailerIds = new Set(input.trailerWorkItemIds);
+    const pinnedChanges = input.changedFragments
+      .filter((fragment) => endpointsByFragment.has(keyOf(fragment)))
+      .sort((left, right) => compare(keyOf(left), keyOf(right)) || compare(left.path, right.path));
+    const findings = pinnedChanges.flatMap((fragment): readonly DesignChangeDeclarationFinding[] => {
+      if (fragment.workItemIds.some((workItemId) => trailerIds.has(workItemId))) return [];
+      return [
+        Object.freeze({
+          code: "design-change-declaration-missing" as const,
+          corpusRole: fragment.corpusRole,
+          declaredKey: fragment.declaredKey,
+          path: fragment.path,
+          expectedWorkItemIds: uniqueSorted(fragment.workItemIds),
+          constraintIds: uniqueSorted(
+            (endpointsByFragment.get(keyOf(fragment)) ?? []).map((endpoint) => endpoint.constraintId),
+          ),
+        }),
+      ];
+    });
+    return Object.freeze({ checkedFragmentCount: pinnedChanges.length, findings: Object.freeze(findings) });
+  }
+}

package/scripts/harness/validator-system/domain/services/world-constraint-admission-service.ts

@@ -0,0 +1,78 @@
+// @unit validator-system
+// @layer domain
+// @work-item-id WI-301
+
+import type {
+  WorldAdmissionClassification,
+  WorldConstraintAdmissionObservation,
+} from "../ports/world-constraint-admission-policy-port.js";
+
+export interface WorldConstraintAdmissionFinding {
+  readonly severity: "error" | "warning";
+  readonly ruleId: string | null;
+  readonly violationFingerprint: string | null;
+  readonly constraintId: string | null;
+  readonly classification: WorldAdmissionClassification | "constraint-input-invalid" | "local-evaluation-incomplete";
+  readonly message: string;
+  readonly suggestion: string;
+  readonly sourcePath: string | null;
+}
+
+const LOCAL_TRUST_NOTICE = "Local L2 evidence can be forged; authoritative L3 re-derivation is required.";
+const AUTHORITATIVE_SUGGESTION =
+  "Repair the declaration or structural finding, then rely on authoritative L3 clean-corpus re-derivation.";
+
+const compareNullable = (left: string | null, right: string | null): number =>
+  (left ?? "") < (right ?? "") ? -1 : (left ?? "") > (right ?? "") ? 1 : 0;
+
+export class WorldConstraintAdmissionService {
+  evaluate(observation: WorldConstraintAdmissionObservation): readonly WorldConstraintAdmissionFinding[] {
+    const obligationFindings = observation.obligations.map((obligation): WorldConstraintAdmissionFinding => {
+      const blocking =
+        obligation.classification === "new-structural" || obligation.classification === "invalid-declaration";
+      const label =
+        obligation.classification === "invalid-declaration"
+          ? "non-adoptable invalid World constraint declaration"
+          : obligation.classification === "new-structural"
+            ? "new World structural violation"
+            : obligation.classification === "adopted-legacy"
+              ? "adopted legacy World violation"
+              : "actively waived World violation";
+      return Object.freeze({
+        severity: blocking ? "error" : "warning",
+        ruleId: obligation.ruleId,
+        violationFingerprint: obligation.violationFingerprint,
+        constraintId: obligation.constraintId,
+        classification: obligation.classification,
+        message: `L2 local fast-path reports ${label}: ${obligation.ruleId} ${obligation.violationFingerprint}. ${LOCAL_TRUST_NOTICE}`,
+        suggestion: AUTHORITATIVE_SUGGESTION,
+        sourcePath: null,
+      });
+    });
+    const diagnosticFindings = observation.diagnostics.map((item): WorldConstraintAdmissionFinding => {
+      const constraintInput = item.scope === "constraint";
+      return Object.freeze({
+        severity: constraintInput ? "error" : "warning",
+        ruleId: constraintInput ? "WCR-001" : null,
+        violationFingerprint: null,
+        constraintId: null,
+        classification: constraintInput ? "constraint-input-invalid" : "local-evaluation-incomplete",
+        message: constraintInput
+          ? `L2 local fast-path cannot admit constraint declaration input (${item.code}): ${item.message}. ${LOCAL_TRUST_NOTICE}`
+          : `L2 local fast-path could not complete non-constraint policy observation (${item.code}): ${item.message}. ${LOCAL_TRUST_NOTICE}`,
+        suggestion: AUTHORITATIVE_SUGGESTION,
+        sourcePath: item.path,
+      });
+    });
+
+    return Object.freeze(
+      [...obligationFindings, ...diagnosticFindings].sort(
+        (left, right) =>
+          compareNullable(left.ruleId, right.ruleId) ||
+          compareNullable(left.violationFingerprint, right.violationFingerprint) ||
+          compareNullable(left.sourcePath, right.sourcePath) ||
+          left.classification.localeCompare(right.classification),
+      ),
+    );
+  }
+}

package/scripts/harness/validator-system/domain/services/world-constraint-rederivation-service.ts

@@ -0,0 +1,76 @@
+// @unit validator-system
+// @layer domain
+// @work-item-id WI-302
+
+import type { WorldAdmissionClassification } from "../ports/world-constraint-admission-policy-port.js";
+import type { WorldConstraintRederivationObservation } from "../ports/world-constraint-rederivation-policy-port.js";
+
+export interface WorldConstraintRederivationFinding {
+  readonly severity: "error" | "warning";
+  readonly ruleId: string | null;
+  readonly violationFingerprint: string | null;
+  readonly constraintId: string | null;
+  readonly classification:
+    | WorldAdmissionClassification
+    | "constraint-input-invalid"
+    | "authoritative-evaluation-failed";
+  readonly message: string;
+  readonly suggestion: string;
+  readonly sourcePath: string | null;
+}
+
+const REPAIR_SUGGESTION =
+  "Repair the versioned declaration or current corpus finding, then rerun authoritative L3 clean-corpus re-derivation.";
+
+const compareNullable = (left: string | null, right: string | null): number =>
+  (left ?? "") < (right ?? "") ? -1 : (left ?? "") > (right ?? "") ? 1 : 0;
+
+export class WorldConstraintRederivationService {
+  evaluate(observation: WorldConstraintRederivationObservation): readonly WorldConstraintRederivationFinding[] {
+    const obligationFindings = observation.obligations.map((obligation): WorldConstraintRederivationFinding => {
+      const blocking =
+        obligation.classification === "new-structural" || obligation.classification === "invalid-declaration";
+      const label =
+        obligation.classification === "invalid-declaration"
+          ? "non-adoptable invalid World constraint declaration"
+          : obligation.classification === "new-structural"
+            ? "new World structural violation"
+            : obligation.classification === "adopted-legacy"
+              ? "adopted legacy World violation"
+              : "actively waived World violation";
+      return Object.freeze({
+        severity: blocking ? "error" : "warning",
+        ruleId: obligation.ruleId,
+        violationFingerprint: obligation.violationFingerprint,
+        constraintId: obligation.constraintId,
+        classification: obligation.classification,
+        message: `L3 authoritative clean-corpus re-derivation reports ${label}: ${obligation.ruleId} ${obligation.violationFingerprint}.`,
+        suggestion: REPAIR_SUGGESTION,
+        sourcePath: null,
+      });
+    });
+    const diagnosticFindings = observation.diagnostics.map((item): WorldConstraintRederivationFinding => {
+      const constraintInput = item.scope === "constraint";
+      return Object.freeze({
+        severity: "error",
+        ruleId: constraintInput ? "WCR-001" : null,
+        violationFingerprint: null,
+        constraintId: null,
+        classification: constraintInput ? "constraint-input-invalid" : "authoritative-evaluation-failed",
+        message: `L3 authoritative clean-corpus re-derivation cannot produce a trustworthy result (${item.code}): ${item.message}.`,
+        suggestion: REPAIR_SUGGESTION,
+        sourcePath: item.path,
+      });
+    });
+
+    return Object.freeze(
+      [...obligationFindings, ...diagnosticFindings].sort(
+        (left, right) =>
+          compareNullable(left.ruleId, right.ruleId) ||
+          compareNullable(left.violationFingerprint, right.violationFingerprint) ||
+          compareNullable(left.sourcePath, right.sourcePath) ||
+          left.classification.localeCompare(right.classification),
+      ),
+    );
+  }
+}

package/scripts/harness/validator-system/domain/value-objects/validator-id.ts

@@ -14,6 +14,8 @@
  * WI-258 (ADR-030 §Decision.3.②) で L2-016（coverage-attestation-gating, fail-closed）を追加
  * WI-259 (ADR-030 §Decision.3.④) で L3-006（injection-scan, advisory warning-only）を追加
  * WI-268 (ADR-030 §Decision.1・§Decision.3.② 第2段) で L3-007（coverage-attestation-verification, fail-closed）を追加
+ * WI-301 で L2-017（world-constraint-admission, local fast-path）を追加
+ * WI-302 で L3-008（world-constraint-rederivation, authoritative）を追加
  */
 
 export class InvalidValidatorIdError extends Error {
@@ -38,6 +40,7 @@ const VALIDATOR_NAME_MAP: Record<string, string> = {
   "L2-014": "work-item-status-staleness",
   "L2-015": "contract-traceability-coverage",
   "L2-016": "coverage-attestation-gating",
+  "L2-017": "world-constraint-admission",
   "L3-001": "security",
   "L3-002": "performance",
   "L3-003": "coverage",
@@ -45,6 +48,7 @@ const VALIDATOR_NAME_MAP: Record<string, string> = {
   "L3-005": "ac-bound-coverage",
   "L3-006": "injection-scan",
   "L3-007": "coverage-attestation-verification",
+  "L3-008": "world-constraint-rederivation",
   "L4-001": "drift-detect",
   "L4-002": "consistency-check",
   "L4-003": "dead-code",

package/scripts/harness/validator-system/infrastructure/adapters/harness-config-validator-config-adapter.ts

@@ -3,51 +3,150 @@
  * @unit validator-system
  * @work-item-id WI-156
  * @work-item-id WI-212
+ * @work-item-id WI-301
+ * @work-item-id WI-302
+ * @work-item-id WI-319
+ * @work-item-id WI-328
  *
  * HarnessConfigValidatorConfigAdapter — ValidatorConfigPort実装
  * HarnessConfigV2からLayerConfig VOを構築する
  */
-import { LayerConfig } from '../../domain/value-objects/layer-config.js';
-import { ValidatorId } from '../../domain/value-objects/validator-id.js';
-import type { ValidatorConfigPort } from '../../domain/ports/validator-config-port.js';
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ValidatorConfigPort } from "../../domain/ports/validator-config-port.js";
+import { LayerConfig } from "../../domain/value-objects/layer-config.js";
+import { ValidatorId } from "../../domain/value-objects/validator-id.js";
 
 export interface HarnessConfigLayers {
   L2?: { enabled?: boolean; validators?: string[]; strictOnly?: boolean; preset?: string };
-  L3?: { enabled?: boolean; validators?: string[]; strictOnly?: boolean; preset?: string; coverageThreshold?: number; bundleSizeLimit?: number };
+  L3?: {
+    enabled?: boolean;
+    validators?: string[];
+    strictOnly?: boolean;
+    preset?: string;
+    coverageThreshold?: number;
+    bundleSizeLimit?: number;
+  };
   L4?: { enabled?: boolean; validators?: string[]; strictOnly?: boolean; preset?: string; deadCodeGC?: boolean };
 }
 
 export interface HarnessConfigV2Like {
-  preset?: 'minimal' | 'standard' | 'strict';
-  project?: { preset?: 'minimal' | 'standard' | 'strict'; languages?: readonly string[] };
+  preset?: "minimal" | "standard" | "strict";
+  project?: { preset?: "minimal" | "standard" | "strict"; languages?: readonly string[] };
   layers?: HarnessConfigLayers;
   harnesses?: {
     bundleSizeLimit?: number;
     deadCodeGC?: boolean;
   };
+  world?: { enabled?: boolean };
+}
+
+/**
+ * WI-319 (github#39): project.languages 未宣言時にファイルシステムから言語を検出するためのマーカー定義。
+ * typescript は package.json の存在自体を根拠にできない（phasegate 導入時に phasegate 用
+ * package.json が置かれるため）ので、この表には含めず hasTypescriptMarker() で個別判定する。
+ */
+const LANGUAGE_MARKER_FILES: ReadonlyArray<{ readonly language: string; readonly markers: readonly string[] }> = [
+  { language: "python", markers: ["pyproject.toml", "setup.py", "setup.cfg", "requirements.txt"] },
+  { language: "go", markers: ["go.mod"] },
+  { language: "rust", markers: ["Cargo.toml"] },
+  { language: "java", markers: ["pom.xml", "build.gradle", "build.gradle.kts"] },
+  { language: "ruby", markers: ["Gemfile"] },
+  { language: "php", markers: ["composer.json"] },
+];
+
+/** WI-328: 実効言語リストの出所。status 表示等で「なぜこの言語判定になったか」を示す。 */
+export type ProjectLanguageSource = "declared" | "detected" | "fallback";
+
+export interface ResolvedProjectLanguages {
+  readonly languages: readonly string[];
+  readonly source: ProjectLanguageSource;
+}
+
+/**
+ * WI-328 (github#39 残課題): 実効言語リストとその出所を解決する唯一の実装。
+ * getProjectLanguages()（WI-319 の検出ロジック）と phasegate:status の言語表示が
+ * 同じテーブル・同じ優先順位を共有するために export する。
+ *
+ * 優先順位:
+ * 1. declared — config の project.languages 宣言（従来どおり最優先）
+ * 2. detected — project root のマーカーファイルから検出（WI-319 / github#39）
+ * 3. fallback — 検出ゼロなら typescript フォールバック（純 JS リポジトリ等の挙動維持）
+ */
+export function resolveProjectLanguages(
+  declaredLanguages: readonly string[] | undefined,
+  rootDir: string,
+): ResolvedProjectLanguages {
+  if (declaredLanguages && declaredLanguages.length > 0) {
+    return { languages: [...declaredLanguages], source: "declared" };
+  }
+  const detected = detectLanguagesFromFilesystem(rootDir);
+  if (detected.length > 0) {
+    return { languages: detected, source: "detected" };
+  }
+  return { languages: ["typescript"], source: "fallback" };
+}
+
+function detectLanguagesFromFilesystem(rootDir: string): string[] {
+  const detected: string[] = [];
+  if (hasTypescriptMarker(rootDir)) detected.push("typescript");
+  for (const { language, markers } of LANGUAGE_MARKER_FILES) {
+    if (markers.some((marker) => existsSync(join(rootDir, marker)))) {
+      detected.push(language);
+    }
+  }
+  return detected;
+}
+
+/**
+ * typescript の根拠は tsconfig.json の存在、または package.json の
+ * dependencies / devDependencies に typescript があることのみ。
+ * package.json の存在自体は根拠にしない（phasegate 導入時に phasegate 用
+ * package.json が置かれるため、誤検出の原因になる）。
+ */
+function hasTypescriptMarker(rootDir: string): boolean {
+  if (existsSync(join(rootDir, "tsconfig.json"))) return true;
+  const packageJsonPath = join(rootDir, "package.json");
+  if (!existsSync(packageJsonPath)) return false;
+  try {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    };
+    return parsed.dependencies?.typescript !== undefined || parsed.devDependencies?.typescript !== undefined;
+  } catch {
+    // parse 失敗は typescript 根拠なしとして扱う（throw しない）
+    return false;
+  }
 }
 
 export class HarnessConfigValidatorConfigAdapter implements ValidatorConfigPort {
   private readonly config: HarnessConfigV2Like;
+  private readonly rootDir: string;
 
-  constructor(config: HarnessConfigV2Like) {
+  constructor(config: HarnessConfigV2Like, rootDir: string = process.cwd()) {
     this.config = config;
+    this.rootDir = rootDir;
   }
 
-  async getLayerConfig(layer: 'L2' | 'L3' | 'L4'): Promise<LayerConfig> {
-    const preset = (this.config.project?.preset ?? this.config.preset ?? 'standard') as 'minimal' | 'standard' | 'strict';
-    const strictOnly = preset === 'strict';
+  async getLayerConfig(layer: "L2" | "L3" | "L4"): Promise<LayerConfig> {
+    const preset = (this.config.project?.preset ?? this.config.preset ?? "standard") as
+      | "minimal"
+      | "standard"
+      | "strict";
+    const strictOnly = preset === "strict";
     const layerData = this.config.layers?.[layer] ?? {};
 
     const defaultValidators: Record<string, string[]> = {
-      L2: ['L2-001', 'L2-002', 'L2-003', 'L2-013', 'L2-014', 'L2-015'],
-      L3: ['L3-001', 'L3-002', 'L3-003', 'L3-004'],
-      L4: ['L4-001', 'L4-002', 'L4-003', 'L4-004', 'L4-005', 'L4-006'],
+      L2: ["L2-001", "L2-002", "L2-003", "L2-013", "L2-014", "L2-015"],
+      L3: ["L3-001", "L3-002", "L3-003", "L3-004"],
+      L4: ["L4-001", "L4-002", "L4-003", "L4-004", "L4-005", "L4-006"],
     };
 
     const thresholds: Record<string, number> = {};
 
-    if (layer === 'L3') {
+    if (layer === "L3") {
       const l3 = this.config.layers?.L3;
       if (l3?.coverageThreshold !== undefined) thresholds.coverageThreshold = l3.coverageThreshold;
       if (l3?.bundleSizeLimit !== undefined) thresholds.bundleSizeLimit = l3.bundleSizeLimit;
@@ -56,16 +155,24 @@ export class HarnessConfigValidatorConfigAdapter implements ValidatorConfigPort
       }
     }
 
-    if (layer === 'L4') {
+    if (layer === "L4") {
       if (this.config.harnesses?.deadCodeGC !== undefined) {
         thresholds.deadCodeGC = this.config.harnesses.deadCodeGC ? 1 : 0;
       }
     }
 
+    const configuredValidatorIds = layerData.validators ?? defaultValidators[layer];
+    const automaticWorldValidatorId = layer === "L2" ? "L2-017" : layer === "L3" ? "L3-008" : null;
+    const selectedValidatorIds =
+      automaticWorldValidatorId === null
+        ? configuredValidatorIds
+        : this.config.world?.enabled === true
+          ? [...configuredValidatorIds, automaticWorldValidatorId]
+          : configuredValidatorIds.filter((validatorId) => validatorId !== automaticWorldValidatorId);
     return LayerConfig.create({
       layer,
       enabled: layerData.enabled !== false,
-      validatorIds: (layerData.validators ?? defaultValidators[layer]).map((idOrName) => this.normalizeValidatorId(idOrName)),
+      validatorIds: [...new Set(selectedValidatorIds.map((idOrName) => this.normalizeValidatorId(idOrName)))],
       thresholds,
       strictOnly: layerData.strictOnly ?? strictOnly,
       preset,
@@ -73,8 +180,9 @@ export class HarnessConfigValidatorConfigAdapter implements ValidatorConfigPort
   }
 
   async getProjectLanguages(): Promise<readonly string[]> {
-    const languages = this.config.project?.languages;
-    return languages && languages.length > 0 ? [...languages] : ['typescript'];
+    // WI-319 の宣言優先 → FS 検出 → typescript フォールバックの解決は
+    // resolveProjectLanguages() に一本化（WI-328 で status 表示と共有）。
+    return [...resolveProjectLanguages(this.config.project?.languages, this.rootDir).languages];
   }
 
   private normalizeValidatorId(idOrName: string): string {

package/scripts/harness/validator-system/infrastructure/adapters/nyquist-ac-coverage-policy-adapter.ts

@@ -18,18 +18,25 @@
  * （layers.L3.requirementMatrixPath）から供給される。未指定時は既定値
  * `.harness/requirement-test-matrix.json` を用いる。マトリクスが不在の場合は
  * fail-closed で「設定されているが不在」という実行可能なメッセージを返す。
+ *
+ * FRESH PROJECT SKIP (WI-324): 例外として「matrix 不在 かつ StoryCatalog の
+ * story がゼロ」の場合のみ skipped=true を返す。phasegate 導入直後（story 未作成・
+ * matrix 未生成）のオンボーディングを fail-closed で阻害しないため。story が
+ * 1件でも存在するのに matrix が不在なら「あるべき matrix が消えた事故」として
+ * 従来どおり fail-closed。story 数の取得自体に失敗した場合も判定不能として
+ * 保守的に fail-closed 側へ倒す。
  */
-import { access } from 'node:fs/promises';
-import { isAbsolute, join } from 'node:path';
-import type { AcCoveragePolicyPort } from '../../domain/ports/ac-coverage-policy-port.js';
-import type { HarnessErrorLike } from '../../domain/value-objects/validation-result.js';
+import { access } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import type { AcCoveragePolicyPort } from "../../domain/ports/ac-coverage-policy-port.js";
+import type { HarnessErrorLike } from "../../domain/value-objects/validation-result.js";
 
-const DEFAULT_MATRIX_PATH = '.harness/requirement-test-matrix.json';
+const DEFAULT_MATRIX_PATH = ".harness/requirement-test-matrix.json";
 
 function toL3004Error(message: string, suggestion: string): HarnessErrorLike {
   return {
-    code: { value: 'L3-004', toString: () => 'L3-004' },
-    severity: { value: 'error', toString: () => 'error' },
+    code: { value: "L3-004", toString: () => "L3-004" },
+    severity: { value: "error", toString: () => "error" },
     message,
     suggestion,
   };
@@ -39,21 +46,29 @@ export class NyquistAcCoveragePolicyAdapter implements AcCoveragePolicyPort {
   async checkCoverage(context: { matrixFilePath?: string }): Promise<{
     passed: boolean;
     errors: readonly HarnessErrorLike[];
+    skipped?: boolean;
+    skipReason?: string;
   }> {
     const rootDir = process.cwd();
     const relativeOrAbsolute =
-      context.matrixFilePath && context.matrixFilePath.length > 0
-        ? context.matrixFilePath
-        : DEFAULT_MATRIX_PATH;
-    const matrixFilePath = isAbsolute(relativeOrAbsolute)
-      ? relativeOrAbsolute
-      : join(rootDir, relativeOrAbsolute);
+      context.matrixFilePath && context.matrixFilePath.length > 0 ? context.matrixFilePath : DEFAULT_MATRIX_PATH;
+    const matrixFilePath = isAbsolute(relativeOrAbsolute) ? relativeOrAbsolute : join(rootDir, relativeOrAbsolute);
 
     // マトリクス不在は threshold-configured-but-absent と同様に fail-closed で
     // 明確なメッセージを返す（ENOENT の生メッセージで落とさない）。
+    // 例外（WI-324）: story がゼロのフレッシュプロジェクトのみ SKIP を返す。
     try {
       await access(matrixFilePath);
     } catch {
+      if (await this.hasZeroStories(rootDir)) {
+        return {
+          passed: true,
+          errors: [],
+          skipped: true,
+          skipReason:
+            "story 未作成のため L3-004 をスキップ（story 作成後に requirement-test-matrix を生成すると有効化されます）",
+        };
+      }
       return {
         passed: false,
         errors: [
@@ -69,7 +84,7 @@ export class NyquistAcCoveragePolicyAdapter implements AcCoveragePolicyPort {
       // 有効 storyId 一覧を traceability-model の StoryCatalog から取得する（REAL registry）
       const storyIds = await this.loadValidStoryIds(rootDir);
 
-      const { createNyquistValidationModule } = await import('../../../nyquist-validation/composition-root.js');
+      const { createNyquistValidationModule } = await import("../../../nyquist-validation/composition-root.js");
       const mod = createNyquistValidationModule({
         getStoryIds: async () => storyIds,
       });
@@ -79,9 +94,7 @@ export class NyquistAcCoveragePolicyAdapter implements AcCoveragePolicyPort {
 
       return {
         passed: output.passed,
-        errors: output.errors.map((err) =>
-          toL3004Error(err.message, ''),
-        ),
+        errors: output.errors.map((err) => toL3004Error(err.message, "")),
       };
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
@@ -91,19 +104,35 @@ export class NyquistAcCoveragePolicyAdapter implements AcCoveragePolicyPort {
         errors: [
           toL3004Error(
             `AC網羅ゲートの検査に失敗しました（fail-closed）: ${message}`,
-            'requirement-test-matrix.json の存在・形式・スキーマ整合性を確認してください',
+            "requirement-test-matrix.json の存在・形式・スキーマ整合性を確認してください",
           ),
         ],
       };
     }
   }
 
+  /**
+   * WI-324: 「story がゼロ」判定。StoryCatalog（traceability-model）の登録 story 数を
+   * シグナルとする。StoryCatalog は requirement-test-matrix の生成元と同じ
+   * user_stories.md を読むため、「matrix が本来存在しうるか」と一貫した判定になる。
+   * catalog 読み込み自体が失敗した場合（config 不正等）は判定不能として false を返し、
+   * 呼び出し側を保守的に fail-closed へ倒す。
+   */
+  private async hasZeroStories(rootDir: string): Promise<boolean> {
+    try {
+      const storyIds = await this.loadValidStoryIds(rootDir);
+      return storyIds.length === 0;
+    } catch {
+      return false;
+    }
+  }
+
   private async loadValidStoryIds(rootDir: string): Promise<readonly string[]> {
-    const { createConfigFoundationModule } = await import('../../../config-foundation/composition-root.js');
+    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 { createTraceabilityModelModule } = await import("../../../traceability-model/composition-root.js");
     const traceModule = createTraceabilityModelModule(rootDir, {
       pathRoots: { designDocsRoot: resolvedConfig.config.paths.designDocs },
     });