phasegate 0.283.0 → 0.335.0

package/scripts/harness/quick-mode/domain/value-objects/quick-mode-config.ts

@@ -5,12 +5,14 @@
  * Quick Mode設定を表す値オブジェクト
  */
 
-export class QuickModeConfigError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'QuickModeConfigError';
-  }
-}
+import { QuickModeConfigError } from '../errors/quick-mode-config-error.js';
+import {
+  CategoryOverrideRules,
+  type CategoryOverrideRulesInput,
+} from './category-override-rules.js';
+import { CHANGE_CATEGORY_VALUES, isChangeCategoryValue } from './change-category.js';
+
+export { QuickModeConfigError };
 
 export type FullModeRequiredRuleId = 'mixedCategories' | 'newDomainFile' | 'apiContractChange';
 
@@ -32,17 +34,21 @@ export class QuickModeConfig {
   readonly maintainedLayers: readonly string[];
   readonly relaxedGates: readonly string[];
   readonly fullModeRequiredWhen: FullModeRequiredRules;
+  /** @work-item-id WI-372 プロジェクト固有パスのカテゴリ割当ルール（未設定時は空） */
+  readonly categoryOverrides: CategoryOverrideRules;
 
   private constructor(
     allowedCategories: readonly string[],
     maintainedLayers: readonly string[],
     relaxedGates: readonly string[],
-    fullModeRequiredWhen: FullModeRequiredRules
+    fullModeRequiredWhen: FullModeRequiredRules,
+    categoryOverrides: CategoryOverrideRules
   ) {
     this.allowedCategories = allowedCategories;
     this.maintainedLayers = maintainedLayers;
     this.relaxedGates = relaxedGates;
     this.fullModeRequiredWhen = fullModeRequiredWhen;
+    this.categoryOverrides = categoryOverrides;
     Object.freeze(this);
   }
 
@@ -51,13 +57,26 @@ export class QuickModeConfig {
     maintainedLayers: string[];
     relaxedGates: string[];
     fullModeRequiredWhen?: Partial<FullModeRequiredRules>;
+    categoryOverrides?: CategoryOverrideRulesInput;
   }): QuickModeConfig {
-    const { allowedCategories, maintainedLayers, relaxedGates, fullModeRequiredWhen } = raw;
+    const { allowedCategories, maintainedLayers, relaxedGates, fullModeRequiredWhen, categoryOverrides } = raw;
 
     if (allowedCategories.length === 0) {
       throw new QuickModeConfigError('allowedCategories must not be empty');
     }
 
+    // WI-373: allowedCategories は ChangeCategory 7 値の enum。
+    // 従来は非空チェックのみだったため "typoo" のような未知値が黙って通り、
+    // 「設定したのに効かない」状態になっていた。分類結果のキーは常に小文字なので
+    // 大文字小文字の正規化はせず厳密一致で拒否する（正規化は効かない設定の黙認になる）。
+    for (const category of allowedCategories) {
+      if (!isChangeCategoryValue(category)) {
+        throw new QuickModeConfigError(
+          `allowedCategories contains unknown category "${category}". Valid values: ${CHANGE_CATEGORY_VALUES.join(', ')}`
+        );
+      }
+    }
+
     const mergedRules: FullModeRequiredRules = Object.freeze({
       mixedCategories: fullModeRequiredWhen?.mixedCategories ?? DEFAULT_FULL_MODE_REQUIRED_WHEN.mixedCategories,
       newDomainFile: fullModeRequiredWhen?.newDomainFile ?? DEFAULT_FULL_MODE_REQUIRED_WHEN.newDomainFile,
@@ -68,7 +87,8 @@ export class QuickModeConfig {
       Object.freeze([...allowedCategories]),
       Object.freeze([...maintainedLayers]),
       Object.freeze([...relaxedGates]),
-      mergedRules
+      mergedRules,
+      CategoryOverrideRules.create(categoryOverrides)
     );
   }
 
@@ -100,7 +120,8 @@ export class QuickModeConfig {
       JSON.stringify(this.relaxedGates) === JSON.stringify(other.relaxedGates) &&
       this.fullModeRequiredWhen.mixedCategories === other.fullModeRequiredWhen.mixedCategories &&
       this.fullModeRequiredWhen.newDomainFile === other.fullModeRequiredWhen.newDomainFile &&
-      this.fullModeRequiredWhen.apiContractChange === other.fullModeRequiredWhen.apiContractChange
+      this.fullModeRequiredWhen.apiContractChange === other.fullModeRequiredWhen.apiContractChange &&
+      this.categoryOverrides.equals(other.categoryOverrides)
     );
   }
 }

package/scripts/harness/quick-mode/index.ts

@@ -1,7 +1,13 @@
 // @unit quick-mode
 // @layer application
 
-export { ChangeCategory, UnknownChangeCategoryError } from './domain/value-objects/change-category.js';
+export {
+  CHANGE_CATEGORY_VALUES,
+  ChangeCategory,
+  isChangeCategoryValue,
+  UnknownChangeCategoryError,
+} from './domain/value-objects/change-category.js';
+export { CategoryOverrideRules } from './domain/value-objects/category-override-rules.js';
 export { ChangedFile } from './domain/value-objects/changed-file.js';
 export { ChangeClassification } from './domain/value-objects/change-classification.js';
 export { QuickModeConfig, QuickModeConfigError } from './domain/value-objects/quick-mode-config.js';

package/scripts/harness/quick-mode/infrastructure/adapters/fs-file-existence-adapter.ts

@@ -0,0 +1,38 @@
+/**
+ * @layer infrastructure
+ * @unit quick-mode
+ * @work-item-id WI-334
+ *
+ * FileExistencePort の fs 実装。
+ * 相対パスは baseDir（既定: process.cwd()）基準で解決する。
+ * stat が ENOENT / ENOTDIR 以外で失敗した場合（権限エラー等）は
+ * 「存在する」扱いにして呼び出し側の changeKind 推定を MODIFY 既定
+ * （従来どおりの安全側）に倒す。
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { FileExistencePort } from "../../application/ports/file-existence-port.js";
+
+export class FsFileExistenceAdapter implements FileExistencePort {
+  private readonly baseDir: string;
+
+  constructor(baseDir?: string) {
+    this.baseDir = baseDir ?? process.cwd();
+  }
+
+  async exists(filePath: string): Promise<boolean> {
+    const absolutePath = path.isAbsolute(filePath) ? filePath : path.join(this.baseDir, filePath);
+    try {
+      await fs.stat(absolutePath);
+      return true;
+    } catch (err) {
+      const error = err as NodeJS.ErrnoException;
+      if (error.code === "ENOENT" || error.code === "ENOTDIR") {
+        return false;
+      }
+      // stat 失敗（権限等）は存在扱い → changeKind は従来どおり MODIFY 既定（安全側）
+      return true;
+    }
+  }
+}

package/scripts/harness/quick-mode/infrastructure/adapters/harness-config-quick-mode-config-adapter.ts

@@ -2,81 +2,132 @@
  * @layer infrastructure
  * @unit quick-mode
  * @work-item-id WI-140
+ * @work-item-id WI-372
+ * @work-item-id WI-377
  *
  * phasegate.config.json から QuickModeConfig を取得する Adapter
+ *
+ * ADR-040: 実効値は config-foundation の防御プリセット解決を経由して決定する。
+ * preset 定義（presets/*.json の quickMode）が実効値の所在であり、
+ * 下の DEFAULT_QUICK_MODE_CONFIG は preset 解決不能時の fail-open 用フォールバックである。
  */
 
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
-import { QuickModeConfig } from '../../domain/value-objects/quick-mode-config.js';
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type {
+  HarnessConfigResolvedDocument,
+  HarnessConfigSourceDocument,
+  PresetId,
+} from "../../../config-foundation/domain/harness-config.js";
+import { PresetResolutionService } from "../../../config-foundation/domain/services/preset-resolution-service.js";
+import { PresetDefinitionStore } from "../../../config-foundation/infrastructure/preset-definition-store.js";
+import { QuickModeConfig } from "../../domain/value-objects/quick-mode-config.js";
 
 export class HarnessConfigNotFoundError extends Error {
   constructor(filePath: string) {
     super(`phasegate.config.json not found: ${filePath}`);
-    this.name = 'HarnessConfigNotFoundError';
+    this.name = "HarnessConfigNotFoundError";
   }
 }
 
 export class HarnessConfigParseError extends Error {
   constructor(message: string) {
     super(`Failed to parse phasegate.config.json: ${message}`);
-    this.name = 'HarnessConfigParseError';
+    this.name = "HarnessConfigParseError";
   }
 }
 
+/**
+ * preset 解決が使えない config（未知 preset / project 欠落 / 他セクション不正）でも
+ * Quick Mode 判定を止めないためのフォールバック。ADR-038 §3-1 の fail-open 原則に従い、
+ * preset 解決の導入によって新たな遮断経路を作らない。
+ */
 const DEFAULT_QUICK_MODE_CONFIG = {
-  allowedCategories: ['bugfix', 'docs', 'test', 'config'],
-  maintainedLayers: ['L1', 'L2-002', 'L2-003', 'L2-014', 'L3-001'],
-  relaxedGates: ['L2-001', 'L3-002', 'L3-003', 'L3-004', 'L4'],
+  allowedCategories: ["bugfix", "docs", "test", "config"],
+  maintainedLayers: ["L1", "L2-002", "L2-003", "L2-014", "L3-001"],
+  relaxedGates: ["L2-001", "L3-002", "L3-003", "L3-004", "L4"],
 };
 
+const PRESET_IDS: readonly PresetId[] = ["minimal", "standard", "strict"];
+
+type RawQuickMode = HarnessConfigResolvedDocument["quickMode"];
+
+function isPresetId(value: unknown): value is PresetId {
+  return typeof value === "string" && PRESET_IDS.includes(value as PresetId);
+}
+
 export class HarnessConfigQuickModeConfigAdapter {
   private readonly configPath: string;
+  private readonly presetDefinitionStore: PresetDefinitionStore;
+  private readonly presetResolutionService: PresetResolutionService;
 
   constructor(configPath?: string) {
-    this.configPath = configPath ?? path.resolve(process.cwd(), 'phasegate.config.json');
+    this.configPath = configPath ?? path.resolve(process.cwd(), "phasegate.config.json");
+    this.presetDefinitionStore = new PresetDefinitionStore();
+    this.presetResolutionService = new PresetResolutionService();
   }
 
   async getQuickModeConfig(): Promise<QuickModeConfig> {
+    const parsed = await this.readSourceDocument();
+    const quickMode = this.resolveQuickMode(parsed);
+
+    return QuickModeConfig.create({
+      allowedCategories: quickMode?.allowedCategories ?? DEFAULT_QUICK_MODE_CONFIG.allowedCategories,
+      maintainedLayers: quickMode?.maintainedLayers ?? DEFAULT_QUICK_MODE_CONFIG.maintainedLayers,
+      relaxedGates: quickMode?.relaxedGates ?? DEFAULT_QUICK_MODE_CONFIG.relaxedGates,
+      fullModeRequiredWhen: quickMode?.fullModeRequiredWhen,
+      // WI-372 × WI-377 合流点: categoryOverrides は preset 解決経路と raw 縮退経路の
+      // 双方が返す `quickMode` から一様に読む。preset 定義は当該キーを宣言しないため
+      // deepMerge は source の宣言をそのまま引き継ぎ（base 側 undefined → override を clone）、
+      // preset 解決が例外で縮退した場合も raw の宣言がそのまま渡る。未設定時は空ルール
+      // = 現行分類のまま。enum 違反は QuickModeConfig.create が QuickModeConfigError を
+      // 投げ、この try/catch の外側なので fail-closed 経路へ表面化する。
+      categoryOverrides: quickMode?.categoryOverrides,
+    });
+  }
+
+  private async readSourceDocument(): Promise<Record<string, unknown>> {
     let content: string;
 
     try {
-      content = await fs.readFile(this.configPath, 'utf8') as string;
+      content = (await fs.readFile(this.configPath, "utf8")) as string;
     } catch (err) {
       const error = err as NodeJS.ErrnoException;
-      if (error.code === 'ENOENT') {
+      if (error.code === "ENOENT") {
         throw new HarnessConfigNotFoundError(this.configPath);
       }
       throw err;
     }
 
-    let parsed: Record<string, unknown>;
     try {
-      parsed = JSON.parse(content) as Record<string, unknown>;
+      return JSON.parse(content) as Record<string, unknown>;
     } catch (err) {
       throw new HarnessConfigParseError(err instanceof Error ? err.message : String(err));
     }
+  }
+
+  /**
+   * 防御プリセット解決を経由した quickMode を返す。
+   * preset が特定できない、または解決が失敗する config では raw の quickMode に縮退し、
+   * 未宣言キーは呼び出し側で DEFAULT_QUICK_MODE_CONFIG に補完される。
+   */
+  private resolveQuickMode(parsed: Record<string, unknown>): Partial<RawQuickMode> | undefined {
+    const rawQuickMode = parsed["quickMode"] as Partial<RawQuickMode> | undefined;
+    const preset = (parsed["project"] as { preset?: unknown } | undefined)?.preset;
 
-    const quickMode = parsed['quickMode'] as {
-      allowedCategories?: string[];
-      maintainedLayers?: string[];
-      relaxedGates?: string[];
-      fullModeRequiredWhen?: {
-        mixedCategories?: boolean;
-        newDomainFile?: boolean;
-        apiContractChange?: boolean;
-      };
-    } | undefined;
-
-    if (!quickMode) {
-      return QuickModeConfig.create(DEFAULT_QUICK_MODE_CONFIG);
+    if (!isPresetId(preset)) {
+      return rawQuickMode;
     }
 
-    return QuickModeConfig.create({
-      allowedCategories: quickMode.allowedCategories ?? DEFAULT_QUICK_MODE_CONFIG.allowedCategories,
-      maintainedLayers: quickMode.maintainedLayers ?? DEFAULT_QUICK_MODE_CONFIG.maintainedLayers,
-      relaxedGates: quickMode.relaxedGates ?? DEFAULT_QUICK_MODE_CONFIG.relaxedGates,
-      fullModeRequiredWhen: quickMode.fullModeRequiredWhen,
-    });
+    try {
+      const presetDefinitions = this.presetDefinitionStore.load();
+      const resolved = this.presetResolutionService.resolve(
+        parsed as unknown as HarnessConfigSourceDocument,
+        presetDefinitions[preset],
+      );
+      return resolved.quickMode;
+    } catch {
+      return rawQuickMode;
+    }
   }
 }

package/scripts/harness/skill-quality/infrastructure/adapters/file-system-requirement-test-matrix-adapter.ts

@@ -2,26 +2,69 @@
  * @layer infrastructure
  * @unit skill-quality
  * @work-item-id WI-188
+ * @work-item-id WI-341
  */
-import { readFile } from 'node:fs/promises';
-import type { RequirementTestMatrixPort, RequirementTestMatrix } from '../../domain/ports/requirement-test-matrix-port.js';
-import { SkillQualityError } from '../../domain/errors/skill-quality-error.js';
+import { readFile } from "node:fs/promises";
+import { SkillQualityError } from "../../domain/errors/skill-quality-error.js";
+import type {
+  RequirementTestMatrix,
+  RequirementTestMatrixPort,
+} from "../../domain/ports/requirement-test-matrix-port.js";
+
+interface GeneratedMatrixAcMapping {
+  readonly acId: string;
+  readonly testReferences: readonly unknown[];
+}
+
+interface GeneratedMatrixStory {
+  readonly storyId: string;
+  readonly storyMappings: readonly GeneratedMatrixAcMapping[];
+}
 
 export class FileSystemRequirementTestMatrixAdapter implements RequirementTestMatrixPort {
-  constructor(private readonly matrixFilePath: string = '.harness/requirement-test-matrix.json') {}
+  constructor(private readonly matrixFilePath: string = ".harness/requirement-test-matrix.json") {}
 
   async read(storyId: string): Promise<RequirementTestMatrix> {
     let raw: string;
     try {
-      raw = await readFile(this.matrixFilePath, 'utf-8');
+      raw = await readFile(this.matrixFilePath, "utf-8");
     } catch {
-      throw new SkillQualityError('MATRIX_FILE_NOT_FOUND', `requirement-test-matrix.json not found at ${this.matrixFilePath}`);
+      throw new SkillQualityError(
+        "MATRIX_FILE_NOT_FOUND",
+        `requirement-test-matrix.json not found at ${this.matrixFilePath}`,
+      );
     }
-    const data = JSON.parse(raw) as Record<string, unknown>;
+    let data: Record<string, unknown>;
+    try {
+      data = JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      throw new SkillQualityError(
+        "MATRIX_FILE_NOT_FOUND",
+        `requirement-test-matrix.json could not be parsed at ${this.matrixFilePath}`,
+      );
+    }
+
+    if (Array.isArray(data.stories)) {
+      const story = (data.stories as GeneratedMatrixStory[]).find((candidate) => candidate.storyId === storyId);
+      if (story === undefined) {
+        throw new SkillQualityError("STORY_NOT_FOUND", `Story ${storyId} not found in ${this.matrixFilePath}`);
+      }
+
+      const uncoveredIds = story.storyMappings
+        .filter((mapping) => !Array.isArray(mapping.testReferences) || mapping.testReferences.length === 0)
+        .map((mapping) => mapping.acId);
+      return {
+        storyId,
+        total: story.storyMappings.length,
+        covered: story.storyMappings.length - uncoveredIds.length,
+        uncoveredIds,
+      };
+    }
+
     const rootEntry = data as { total?: unknown; covered?: unknown; uncoveredIds?: unknown };
     const explicitEntry = data[storyId];
     if (explicitEntry === undefined && rootEntry.total === undefined) {
-      throw new SkillQualityError('STORY_NOT_FOUND', `Story ${storyId} not found in ${this.matrixFilePath}`);
+      throw new SkillQualityError("STORY_NOT_FOUND", `Story ${storyId} not found in ${this.matrixFilePath}`);
     }
     const entry = (explicitEntry ?? data) as { total: number; covered: number; uncoveredIds: string[] };
     return {

package/scripts/harness/skill-quality/presentation/handlers/check-coverage-handler.ts

@@ -2,12 +2,14 @@
  * @layer presentation
  * @unit skill-quality
  * @work-item-id WI-188
+ * @work-item-id WI-341
  */
-import type { CheckCoverageUseCase } from '../../application/usecases/check-coverage-usecase.js';
+import type { CheckCoverageUseCase } from "../../application/usecases/check-coverage-usecase.js";
+import { SkillQualityError } from "../../domain/errors/skill-quality-error.js";
 
 export interface CheckCoverageArgs {
   storyId: string;
-  format?: 'human' | 'json';
+  format?: "human" | "json";
 }
 
 export class CheckCoverageHandler {
@@ -16,9 +18,9 @@ export class CheckCoverageHandler {
   async handle(args: CheckCoverageArgs): Promise<{ exitCode: number; message: string }> {
     try {
       const output = await this.useCase.execute({ storyId: args.storyId });
-      const format = args.format ?? 'human';
+      const format = args.format ?? "human";
 
-      if (format === 'json') {
+      if (format === "json") {
         return { exitCode: output.meetsThreshold ? 0 : 1, message: JSON.stringify(output, null, 2) };
       }
 
@@ -26,7 +28,7 @@ export class CheckCoverageHandler {
       const codeRate = output.coverageReport.codeCoverage.lineCoverage.toFixed(1);
       const msg = `Requirement coverage: ${reqRate}% (threshold: ${output.requirementThreshold}%)\nCode coverage: ${codeRate}% (threshold: ${output.codeThreshold}%)`;
 
-      if (output.skipped === true && output.skipReason === 'no-tests') {
+      if (output.skipped === true && output.skipReason === "no-tests") {
         return { exitCode: 0, message: `Coverage SKIPPED (no tests)\n${msg}` };
       }
 
@@ -35,7 +37,12 @@ export class CheckCoverageHandler {
       }
       return { exitCode: 1, message: `Coverage FAILED\n${msg}` };
     } catch (err) {
-      return { exitCode: 2, message: `Error: ${err instanceof Error ? err.message : String(err)}` };
+      const message = err instanceof Error ? err.message : String(err);
+      if (args.format === "json") {
+        const code = err instanceof SkillQualityError ? err.code : "UNEXPECTED_ERROR";
+        return { exitCode: 2, message: JSON.stringify({ error: { code, message } }, null, 2) };
+      }
+      return { exitCode: 2, message: `Error: ${message}` };
     }
   }
 }

package/scripts/harness/traceability-model/domain/value-objects/work-item-frontmatter.ts

@@ -1,5 +1,6 @@
 // @unit traceability-model
 // @layer domain
+// @work-item-id WI-337
 /**
  * WorkItemFrontmatter — 設計文書 frontmatter から抽出した WI メタデータ（H03-04 / ISSUE-026 Phase A-2）。
  *
@@ -8,7 +9,7 @@
  */
 
 export type WorkItemType = 'story' | 'issue' | 'fix' | 'refactor' | 'chore';
-export type WorkItemSeverity = 'trivial' | 'normal' | 'high';
+export type WorkItemSeverity = 'trivial' | 'normal' | 'medium' | 'high' | 'critical' | 'major';
 export type WorkItemStatus =
   | 'drafted'
   | 'reflected'
@@ -47,7 +48,10 @@ export const WORK_ITEM_TYPES: ReadonlySet<WorkItemType> = new Set([
 export const WORK_ITEM_SEVERITIES: ReadonlySet<WorkItemSeverity> = new Set([
   'trivial',
   'normal',
+  'medium',
   'high',
+  'critical',
+  'major',
 ]);
 
 export const WORK_ITEM_STATUSES: ReadonlySet<WorkItemStatus> = new Set([

package/scripts/harness/traceability-model/infrastructure/gateways/file-system-work-item-identity-gateway.ts

@@ -1,6 +1,7 @@
 // @unit traceability-model
 // @layer infrastructure
 // @work-item-id WI-106
+// @work-item-id WI-337
 
 import { readdir, readFile } from "node:fs/promises";
 import * as path from "node:path";
@@ -8,6 +9,7 @@ import type {
   WorkItemIdentityEntry,
   WorkItemIdentityPort,
 } from "../../domain/ports/work-item-identity-port.js";
+import { WorkItemFrontmatterValidationError } from "../../domain/value-objects/work-item-frontmatter.js";
 import { parseWorkItemFrontmatter } from "../parsers/work-item-frontmatter-parser.js";
 
 const WI_DIR_PATTERN = /^WI-\d+$/;
@@ -67,7 +69,10 @@ export class FileSystemWorkItemIdentityGateway implements WorkItemIdentityPort {
     try {
       const content = await readFile(path.join(this.rootDir, descriptionPath), "utf8");
       return parseWorkItemFrontmatter(content)?.id ?? null;
-    } catch {
+    } catch (error) {
+      if (error instanceof WorkItemFrontmatterValidationError) {
+        console.warn(`[phasegate] warning: ${descriptionPath} をスキップしました: ${error.message}`);
+      }
       return null;
     }
   }

package/scripts/harness/traceability-model/infrastructure/gateways/file-system-work-item-status-gateway.ts

@@ -1,11 +1,15 @@
 // @unit traceability-model
 // @layer infrastructure
 // @work-item-id WI-126 / WI-140
+// @work-item-id WI-337
 
 import { readdir, readFile, writeFile } from "node:fs/promises";
 import * as path from "node:path";
 import type { WorkItemStatusPort } from "../../domain/ports/work-item-status-port.js";
-import type { WorkItemFrontmatter } from "../../domain/value-objects/work-item-frontmatter.js";
+import {
+  type WorkItemFrontmatter,
+  WorkItemFrontmatterValidationError,
+} from "../../domain/value-objects/work-item-frontmatter.js";
 import type {
   WorkItemStatusApplyResult,
   WorkItemStatusInput,
@@ -52,7 +56,16 @@ export class FileSystemWorkItemStatusGateway implements WorkItemStatusPort {
     const inputs: WorkItemStatusInput[] = [];
     for (const entry of entries) {
       const content = await readFile(path.join(this.rootDir, entry.descriptionPath), "utf8");
-      const frontmatter = parseWorkItemFrontmatter(content);
+      let frontmatter: WorkItemFrontmatter | null;
+      try {
+        frontmatter = parseWorkItemFrontmatter(content);
+      } catch (error) {
+        if (error instanceof WorkItemFrontmatterValidationError) {
+          console.warn(`[phasegate] warning: ${entry.descriptionPath} をスキップしました: ${error.message}`);
+          continue;
+        }
+        throw error;
+      }
       if (frontmatter === null) continue;
 
       const aliases = this.aliasesFor(frontmatter);

package/scripts/harness/validator-system/application/use-cases/aggregate-validation-results-usecase.ts

@@ -4,9 +4,9 @@
  *
  * AggregateValidationResultsUseCase — H08-05: バリデータ結果統合集約
  */
-import type { ValidationResultContract } from '../dto/validation-result-contract.js';
-import type { AggregateResultsInput } from '../dto/aggregate-results-input.js';
-import type { AggregatedValidationReport } from '../dto/aggregated-validation-report.js';
+import { isEffectivelyPassed } from "../../domain/services/effective-severity-policy.js";
+import type { AggregateResultsInput } from "../dto/aggregate-results-input.js";
+import type { AggregatedValidationReport } from "../dto/aggregated-validation-report.js";
 
 export class AggregateValidationResultsUseCase {
   execute(input: AggregateResultsInput): AggregatedValidationReport {
@@ -24,7 +24,7 @@ export class AggregateValidationResultsUseCase {
     }[] = [];
     let totalErrors = 0;
     let totalWarnings = 0;
-    const errorsByLayer: Record<'L2' | 'L3' | 'L4', number> = { L2: 0, L3: 0, L4: 0 };
+    const errorsByLayer: Record<"L2" | "L3" | "L4", number> = { L2: 0, L3: 0, L4: 0 };
 
     for (const result of results) {
       if (result.skipped) {
@@ -32,12 +32,9 @@ export class AggregateValidationResultsUseCase {
         continue;
       }
 
-      // ADR-017: warning-only validator fail は failOnWarning=false で overall PASS、true で従来挙動 (FAIL)
-      const hasNonWarningError = result.errors.some((e) => e.severity !== 'warning');
-      const hasWarnings = result.errors.some((e) => e.severity === 'warning');
-      const isEmptyFail = !result.passed && result.errors.length === 0;
-      const hasFail =
-        !result.passed && (isEmptyFail || hasNonWarningError || (failOnWarning && hasWarnings));
+      // ADR-017 / WI-332: warning-only validator fail は failOnWarning=false で overall PASS、
+      // true で従来挙動 (FAIL)。実効判定は domain の共有実装 isEffectivelyPassed に一本化。
+      const hasFail = !isEffectivelyPassed(result, failOnWarning);
 
       if (hasFail) {
         failedValidators++;
@@ -54,7 +51,7 @@ export class AggregateValidationResultsUseCase {
         };
         allErrors.push(errorEntry);
 
-        if (error.severity === 'warning') {
+        if (error.severity === "warning") {
           totalWarnings++;
         } else {
           totalErrors++;
@@ -62,9 +59,9 @@ export class AggregateValidationResultsUseCase {
 
         // レイヤー別集計
         const code = error.code;
-        if (code.startsWith('L2-')) errorsByLayer.L2++;
-        else if (code.startsWith('L3-')) errorsByLayer.L3++;
-        else if (code.startsWith('L4-')) errorsByLayer.L4++;
+        if (code.startsWith("L2-")) errorsByLayer.L2++;
+        else if (code.startsWith("L3-")) errorsByLayer.L3++;
+        else if (code.startsWith("L4-")) errorsByLayer.L4++;
       }
     }
 

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

@@ -171,6 +171,9 @@ export class RunL3ValidatorsUseCase {
                     severity: "error",
                     message: `カバレッジ不足: 現在値 ${coverageData.overallCoverage}%、不足 ${threshold - coverageData.overallCoverage}%`,
                     suggestion: `テストカバレッジを ${threshold}% 以上に引き上げてください`,
+                    // WI-335: 閾値未達の解消はテスト追加（AI/人間の判断）が必要。
+                    // L3-003 の registry 既定は mechanical だが、この finding は機械適用不能なので明示的に上書きする。
+                    remediationType: "ai-assisted",
                   },
                 ],
                 0,
@@ -190,8 +193,13 @@ export class RunL3ValidatorsUseCase {
                   code: "L3-003",
                   severity: "error",
                   message: `coverageThreshold=${threshold}% が設定されていますがカバレッジレポートが見つかりません（テストをカバレッジ付きで実行してください）`,
+                  // WI-335: 選択肢 (b)「layers.L3.coverageThreshold を 0 に設定する」は config 編集のみで
+                  // 完結する機械適用可能な opt-out（WI-317 / github#37）なので mechanical と宣言する。
+                  // この文言（layers.L3.coverageThreshold を 0）を変える場合は remediation-round-trip
+                  // テスト（機械適用器が同じ文言を解析する）が fail する。
                   suggestion:
                     '次のいずれかで解消してください: (a) テストをカバレッジ付きで実行してレポートを生成する（例: vitest --coverage）、(b) カバレッジゲートを opt-out するなら config の layers.L3.coverageThreshold を 0 に設定する、(c) 非 JS/TS プロジェクトなら project.languages を宣言する（例: ["python"]。L3-003 自体が unsupported-language SKIP になる）',
+                  remediationType: "mechanical",
                 },
               ],
               0,

package/scripts/harness/validator-system/domain/services/effective-severity-policy.ts

@@ -0,0 +1,39 @@
+// @unit validator-system
+// @layer domain
+// @work-item-id WI-332
+
+/**
+ * effective-severity-policy — 実効 severity 判定の単一ソース (ADR-017 / ADR-021)。
+ *
+ * validator 1件が「実質 pass」かを severity-aware に判定するルール。
+ * WI-332 以前は同じ判定式が 3 箇所（validate 集約 usecase / harness-api CiCheckResult /
+ * pre-commit の手動集約）に複製・乖離しており、#38（complete-check だけ warning-only で
+ * exit 1）型の回帰を招いた。以後、実効判定は必ずこの関数を経由すること。
+ *
+ * 判定ルール（ADR-017 Decision の集計セマンティクスそのもの）:
+ * - skipped: 実質 pass
+ * - passed=true: 実質 pass
+ * - passed=false かつ error severity（!= warning）を含む: fail
+ * - passed=false かつ errors=[]（severity 判定不能）: 安全側に倒して fail
+ * - passed=false かつ warning のみ: failOnWarning=false（既定）で実質 pass、true で fail
+ */
+
+/**
+ * 判定に必要な最小構造。validator-system の ValidationResultContract と
+ * harness-api の ValidatorCheckItem の双方が構造的に満たす。
+ */
+export interface EffectiveSeverityCheckItem {
+  readonly passed: boolean;
+  readonly skipped?: boolean;
+  readonly errors?: readonly { readonly severity: string }[];
+}
+
+export function isEffectivelyPassed(item: EffectiveSeverityCheckItem, failOnWarning = false): boolean {
+  if (item.skipped || item.passed) return true;
+  const errors = item.errors ?? [];
+  const hasNonWarningError = errors.some((e) => e.severity !== "warning");
+  const hasWarnings = errors.some((e) => e.severity === "warning");
+  const isEmptyFail = errors.length === 0;
+  const hasFail = isEmptyFail || hasNonWarningError || (failOnWarning && hasWarnings);
+  return !hasFail;
+}