phasegate 0.283.0 → 0.335.0

package/scripts/harness/quick-mode/application/ports/file-existence-port.ts

@@ -0,0 +1,15 @@
+/**
+ * @layer application
+ * @unit quick-mode
+ * @work-item-id WI-334
+ *
+ * ファイルの存在確認を行う Application 層 Port。
+ * ClassifyChangeCategoryUseCase が targetChanges を受け取らない経路
+ * （CLI: check-change-category --paths）で changeKind を CREATE/MODIFY と
+ * 推定するために使用する。hook 経路（beforeContent=null → CREATE）との
+ * 判定一致を保証する目的で導入された（WI-334）。
+ */
+
+export interface FileExistencePort {
+  exists(filePath: string): Promise<boolean>;
+}

package/scripts/harness/quick-mode/application/usecases/classify-change-category-usecase.ts

@@ -6,10 +6,15 @@
  * paths から変更カテゴリを分類し fullModeRequired 判定と理由を返す UseCase
  */
 
-import { ChangedFile } from '../../domain/value-objects/changed-file.js';
-import { QuickModeJudgmentEngine } from '../../domain/services/quick-mode-judgment-engine.js';
-import type { QuickModeConfigPort } from '../ports/quick-mode-config-port.js';
-import type { ChangeCategoryClassificationContract, ChangeCategoryPerFile } from '../dto/change-category-classification-contract.js';
+import { QuickModeJudgmentEngine } from "../../domain/services/quick-mode-judgment-engine.js";
+import type { ChangeKind } from "../../domain/types/change-kind.js";
+import { ChangedFile } from "../../domain/value-objects/changed-file.js";
+import type {
+  ChangeCategoryClassificationContract,
+  ChangeCategoryPerFile,
+} from "../dto/change-category-classification-contract.js";
+import type { FileExistencePort } from "../ports/file-existence-port.js";
+import type { QuickModeConfigPort } from "../ports/quick-mode-config-port.js";
 
 export interface ClassifyChangeCategoryUseCaseInput {
   readonly paths: readonly string[];
@@ -23,20 +28,41 @@ export interface ClassifyChangeCategoryUseCaseInput {
 export interface ClassifyChangeCategoryUseCaseDeps {
   quickModeConfigPort: QuickModeConfigPort;
   judgmentEngine?: QuickModeJudgmentEngine;
+  fileExistencePort?: FileExistencePort;
 }
 
 export class ClassifyChangeCategoryUseCase {
   private readonly quickModeConfigPort: QuickModeConfigPort;
   private readonly judgmentEngine: QuickModeJudgmentEngine;
+  private readonly fileExistencePort?: FileExistencePort;
 
   constructor(deps: ClassifyChangeCategoryUseCaseDeps) {
     this.quickModeConfigPort = deps.quickModeConfigPort;
     this.judgmentEngine = deps.judgmentEngine ?? new QuickModeJudgmentEngine();
+    this.fileExistencePort = deps.fileExistencePort;
   }
 
-  async execute(
-    input: ClassifyChangeCategoryUseCaseInput
-  ): Promise<Readonly<ChangeCategoryClassificationContract>> {
+  /**
+   * targetChanges 引数自体が渡されない経路（CLI: check-change-category --paths）向けの
+   * changeKind 推定。hook 経路は beforeContent=null → CREATE と判定するため、同一パスで
+   * CLI=MODIFY(bugfix) / hook=CREATE(feature) に割れていた（WI-334）。
+   * ファイルが存在しない場合は CREATE、存在する場合は MODIFY と推定して hook 判定と一致させる。
+   * port 未注入・存在チェック失敗時は従来どおり MODIFY 既定（安全側）。
+   * なお hook は targetChanges を常に配列（空を含む）で渡すため推定対象外となり、
+   * Bash 抽出ターゲット等（配列にエントリが無いパス）の従来挙動は変えない。
+   */
+  private async inferChangeKind(filePath: string): Promise<ChangeKind> {
+    if (this.fileExistencePort === undefined) {
+      return "MODIFY";
+    }
+    try {
+      return (await this.fileExistencePort.exists(filePath)) ? "MODIFY" : "CREATE";
+    } catch {
+      return "MODIFY";
+    }
+  }
+
+  async execute(input: ClassifyChangeCategoryUseCaseInput): Promise<Readonly<ChangeCategoryClassificationContract>> {
     const config = await this.quickModeConfigPort.getConfig();
 
     if (input.paths.length === 0) {
@@ -47,21 +73,33 @@ export class ClassifyChangeCategoryUseCase {
       });
     }
 
+    const inferenceEnabled = input.targetChanges === undefined;
     const targetChanges = new Map((input.targetChanges ?? []).map((change) => [change.filePath, change]));
-    const changedFiles = input.paths.map((p) => {
-      const targetChange = targetChanges.get(p);
-      const beforeContent = targetChange?.beforeContent ?? null;
-      const afterContent = targetChange?.afterContent ?? null;
-      return ChangedFile.create({
-        filePath: p,
-        // 変更前の内容が無く変更後の内容がある場合は新規作成 (CREATE) とみなす。
-        // 以前は無条件で MODIFY 固定だったため、新規 domain/ ファイルが
-        // NEW_DOMAIN 判定を回避して quick mode をすり抜けていた。
-        changeKind: beforeContent === null && afterContent !== null ? 'CREATE' : 'MODIFY',
-        beforeContent,
-        afterContent,
-      });
-    });
+    const changedFiles = await Promise.all(
+      input.paths.map(async (p) => {
+        const targetChange = targetChanges.get(p);
+        if (targetChange === undefined && inferenceEnabled) {
+          // targetChanges 引数が渡されない経路（CLI）はファイル存在で CREATE/MODIFY を推定する（WI-334）
+          return ChangedFile.create({
+            filePath: p,
+            changeKind: await this.inferChangeKind(p),
+            beforeContent: null,
+            afterContent: null,
+          });
+        }
+        const beforeContent = targetChange?.beforeContent ?? null;
+        const afterContent = targetChange?.afterContent ?? null;
+        return ChangedFile.create({
+          filePath: p,
+          // 変更前の内容が無く変更後の内容がある場合は新規作成 (CREATE) とみなす。
+          // 以前は無条件で MODIFY 固定だったため、新規 domain/ ファイルが
+          // NEW_DOMAIN 判定を回避して quick mode をすり抜けていた。
+          changeKind: beforeContent === null && afterContent !== null ? "CREATE" : "MODIFY",
+          beforeContent,
+          afterContent,
+        });
+      }),
+    );
 
     const classification = this.judgmentEngine.classify(changedFiles, config);
     const eligibility = this.judgmentEngine.judge(changedFiles, config);
@@ -76,7 +114,7 @@ export class ClassifyChangeCategoryUseCase {
           categoryForFile = categoryKey;
         }
       });
-      perFile.push({ path, category: categoryForFile ?? 'unknown' });
+      perFile.push({ path, category: categoryForFile ?? "unknown" });
     }
 
     const fullModeRequired = !eligibility.isEligible();

package/scripts/harness/quick-mode/composition-root.ts

@@ -5,19 +5,20 @@
  * quick-mode ユニットの Composition Root
  */
 
-import { GitDiffChangedFilesAdapter } from './infrastructure/adapters/git-diff-changed-files-adapter.js';
-import { HarnessConfigQuickModeConfigAdapter } from './infrastructure/adapters/harness-config-quick-mode-config-adapter.js';
-import { ValidatorSystemValidatorIdRegistryAdapter } from './infrastructure/adapters/validator-system-validator-id-registry-adapter.js';
-import { ValidatorSystemQuickModeExecutionAdapter } from './infrastructure/adapters/validator-system-quick-mode-execution-adapter.js';
-import { QuickModeJudgmentEngine } from './domain/services/quick-mode-judgment-engine.js';
-import { ValidatorRelaxationService } from './domain/services/validator-relaxation-service.js';
-import { QuickModeDecisionContractMapper } from './application/mappers/quick-mode-decision-contract-mapper.js';
-import { JudgeQuickModeEligibilityUseCase } from './application/usecases/judge-quick-mode-eligibility-usecase.js';
-import { BuildRelaxationProfileUseCase } from './application/usecases/build-relaxation-profile-usecase.js';
-import { ExecuteQuickCiCheckUseCase } from './application/usecases/execute-quick-ci-check-usecase.js';
-import { ClassifyChangeCategoryUseCase } from './application/usecases/classify-change-category-usecase.js';
-import { CiCheckQuickModeHandler } from './presentation/handlers/ci-check-quick-mode-handler.js';
-import { CheckChangeCategoryHandler } from './presentation/handlers/check-change-category-handler.js';
+import { QuickModeDecisionContractMapper } from "./application/mappers/quick-mode-decision-contract-mapper.js";
+import { BuildRelaxationProfileUseCase } from "./application/usecases/build-relaxation-profile-usecase.js";
+import { ClassifyChangeCategoryUseCase } from "./application/usecases/classify-change-category-usecase.js";
+import { ExecuteQuickCiCheckUseCase } from "./application/usecases/execute-quick-ci-check-usecase.js";
+import { JudgeQuickModeEligibilityUseCase } from "./application/usecases/judge-quick-mode-eligibility-usecase.js";
+import { QuickModeJudgmentEngine } from "./domain/services/quick-mode-judgment-engine.js";
+import { ValidatorRelaxationService } from "./domain/services/validator-relaxation-service.js";
+import { FsFileExistenceAdapter } from "./infrastructure/adapters/fs-file-existence-adapter.js";
+import { GitDiffChangedFilesAdapter } from "./infrastructure/adapters/git-diff-changed-files-adapter.js";
+import { HarnessConfigQuickModeConfigAdapter } from "./infrastructure/adapters/harness-config-quick-mode-config-adapter.js";
+import { ValidatorSystemQuickModeExecutionAdapter } from "./infrastructure/adapters/validator-system-quick-mode-execution-adapter.js";
+import { ValidatorSystemValidatorIdRegistryAdapter } from "./infrastructure/adapters/validator-system-validator-id-registry-adapter.js";
+import { CheckChangeCategoryHandler } from "./presentation/handlers/check-change-category-handler.js";
+import { CiCheckQuickModeHandler } from "./presentation/handlers/ci-check-quick-mode-handler.js";
 
 export interface QuickModeCompositionRoot {
   handler: CiCheckQuickModeHandler;
@@ -28,12 +29,20 @@ export interface QuickModeCompositionRoot {
   classifyUseCase: ClassifyChangeCategoryUseCase;
 }
 
-export function createQuickModeCompositionRoot(): QuickModeCompositionRoot {
+export interface QuickModeCompositionRootOptions {
+  configPath?: string;
+  rootDir?: string;
+}
+
+export function createQuickModeCompositionRoot(
+  options: QuickModeCompositionRootOptions = {},
+): QuickModeCompositionRoot {
   // Infrastructure
   const gitDiffAdapter = new GitDiffChangedFilesAdapter();
-  const harnessConfigAdapter = new HarnessConfigQuickModeConfigAdapter();
+  const harnessConfigAdapter = new HarnessConfigQuickModeConfigAdapter(options.configPath);
   const validatorIdRegistryAdapter = new ValidatorSystemValidatorIdRegistryAdapter();
   const validatorExecutionPort = new ValidatorSystemQuickModeExecutionAdapter();
+  const fileExistencePort = new FsFileExistenceAdapter(options.rootDir);
 
   // Domain Services
   const judgmentEngine = new QuickModeJudgmentEngine();
@@ -72,6 +81,7 @@ export function createQuickModeCompositionRoot(): QuickModeCompositionRoot {
   const classifyUseCase = new ClassifyChangeCategoryUseCase({
     quickModeConfigPort,
     judgmentEngine,
+    fileExistencePort,
   });
 
   // Presentation

package/scripts/harness/quick-mode/domain/errors/quick-mode-config-error.ts

@@ -0,0 +1,19 @@
+/**
+ * @layer domain
+ * @unit quick-mode
+ * @work-item-id WI-372
+ *
+ * QuickMode 設定の不変条件違反を表すエラー。
+ *
+ * `quick-mode-config.ts` と `category-override-rules.ts` の双方から参照されるため、
+ * 循環 import を避ける目的で独立ファイルに切り出している。
+ * 後方互換のため `quick-mode-config.ts` からも re-export される。
+ */
+
+export class QuickModeConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'QuickModeConfigError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/scripts/harness/quick-mode/domain/services/quick-mode-judgment-engine.ts

@@ -2,10 +2,14 @@
  * @layer domain
  * @unit quick-mode
  * @work-item-id WI-204
+ * @work-item-id WI-349
+ * @work-item-id WI-352
+ * @work-item-id WI-372
  *
  * ChangedFile[]をChangeClassificationに変換し、3拒否ルールを評価してQuickModeEligibilityを返すドメインサービス
  */
 
+import { CategoryOverrideRules } from "../value-objects/category-override-rules.js";
 import { ChangeCategory } from "../value-objects/change-category.js";
 import { ChangeClassification } from "../value-objects/change-classification.js";
 import type { ChangedFile } from "../value-objects/changed-file.js";
@@ -13,18 +17,38 @@ import type { QuickModeConfig } from "../value-objects/quick-mode-config.js";
 import { QuickModeEligibility } from "../value-objects/quick-mode-eligibility.js";
 import { isCommentOnlyDiff } from "./comment-only-diff-detector.js";
 
-// リスク順優先度（api > domain > feature > bugfix > test > config > docs）
-const RISK_PRIORITY: Record<string, number> = {
-  api: 6,
-  domain: 5,
-  feature: 4,
-  bugfix: 3,
-  test: 2,
-  config: 1,
-  docs: 0,
-};
-
-function categorizeFile(file: ChangedFile): ChangeCategory {
+// config: リポジトリ直下の bootstrap 設定ファイル（列挙型 allowlist）。
+// これらは unit を持たず、CREATE だと feature に落ちて allowedCategories に
+// 入れる手段がないため greenfield な初期セットアップが恒久的にブロックされていた。
+// ワイルドカード（.github/** 等）には広げず、実在する bootstrap ファイル名のみを
+// 列挙して fail-closed を維持する（WI-334 の .github/workflows、
+// WI-261 の skills/**/*.md と同型の判断）。
+// package.json は protected-file 経路で別途保護されるためここには含めない。
+// @work-item-id WI-352
+const ROOT_BOOTSTRAP_CONFIG_FILES: ReadonlySet<string> = new Set([
+  ".gitignore",
+  ".gitattributes",
+  ".editorconfig",
+  ".npmrc",
+  ".nvmrc",
+  "tsconfig.json",
+]);
+
+const HUSKY_DIRECTORY_PREFIX = ".husky/";
+
+function isRootBootstrapConfigFile(filePath: string): boolean {
+  if (ROOT_BOOTSTRAP_CONFIG_FILES.has(filePath)) {
+    return true;
+  }
+  // tsconfig.*.json（tsconfig.build.json / tsconfig.test.json 等）もルート直下のみ許可
+  if (/^tsconfig\.[^/]+\.json$/.test(filePath)) {
+    return true;
+  }
+  // .husky/ 配下の hook スクリプト（L0 の runtime 定義）
+  return filePath.startsWith(HUSKY_DIRECTORY_PREFIX) && filePath.slice(HUSKY_DIRECTORY_PREFIX.length).length > 0;
+}
+
+function categorizeFileByBuiltInRules(file: ChangedFile): ChangeCategory {
   const { filePath, changeKind } = file;
 
   // Config files must stay config even when Edit payload snippets look like
@@ -37,6 +61,23 @@ function categorizeFile(file: ChangedFile): ChangeCategory {
     return ChangeCategory.fromString("config");
   }
 
+  // config: .github/workflows/ 配下の CI workflow（.yml / .yaml）。
+  // CI workflow は unit を持たない構成ファイルであり、CREATE でも config に分類する。
+  // 内容レベルの防御は L3-006 injection scanner と integrity pin が担う
+  // （WI-261 の skills/**/*.md → docs 分類と同型の判断）。
+  // MODIFY がフォールバックで bugfix として quick を通過する現状との整合も取る。
+  // .github/ 全体には広げず workflows/ 配下の yml/yaml に限定し、
+  // それ以外の .github/ 配下は従来どおりフォールバック（fail-closed）を維持する。
+  // @work-item-id WI-334
+  if (filePath.startsWith(".github/workflows/") && (filePath.endsWith(".yml") || filePath.endsWith(".yaml"))) {
+    return ChangeCategory.fromString("config");
+  }
+
+  // config: リポジトリ直下の bootstrap 設定ファイル（WI-352）
+  if (isRootBootstrapConfigFile(filePath)) {
+    return ChangeCategory.fromString("config");
+  }
+
   if (isCommentOnlyDiff(file)) {
     return ChangeCategory.fromString("docs");
   }
@@ -80,18 +121,67 @@ function categorizeFile(file: ChangedFile): ChangeCategory {
   return ChangeCategory.fromString("bugfix");
 }
 
+// 組み込み判定が構造的に高リスク（domain / api）のカテゴリは override で降格できない。
+// @work-item-id WI-372
+const NON_DOWNGRADABLE_BUILT_IN_CATEGORIES: ReadonlySet<string> = new Set(["domain", "api"]);
+
+/**
+ * WI-372: `quickMode.categoryOverrides` を反映したカテゴリ判定。
+ *
+ * override は「このパスはこの種類の変更である」という利用者の明示宣言なので、
+ * 組み込みルールより **先** に評価する（DD-1）。組み込みの後段に置くと
+ * `notes/x.config.json` のような偶発的な組み込みマッチに常に負け、
+ * 「設定したのに効かない」不可解な挙動になるため。
+ *
+ * ただし組み込み判定が `domain` / `api` のファイルは override で降格できない（DD-2）。
+ * `judge()` の NEW_DOMAIN は CREATE のみ、API_CONTRACT は port/adapter のみを見るため、
+ * ガードが無いと domain ファイルの MODIFY が `docs` として素通りしてしまう。
+ * 降格は禁じるが昇格（domain → api 等）は許す。
+ *
+ * override 未設定時は組み込み分類と完全に一致する（後方互換）。
+ */
+function categorizeFile(file: ChangedFile, overrides: CategoryOverrideRules): ChangeCategory {
+  const builtIn = categorizeFileByBuiltInRules(file);
+  if (overrides.isEmpty()) {
+    return builtIn;
+  }
+
+  const override = overrides.resolve(file.filePath);
+  if (override === null) {
+    return builtIn;
+  }
+
+  if (NON_DOWNGRADABLE_BUILT_IN_CATEGORIES.has(builtIn.toString())) {
+    return override.riskPriority() > builtIn.riskPriority() ? override : builtIn;
+  }
+
+  return override;
+}
+
+/**
+ * WI-349: 遮断理由に判定根拠（分類カテゴリと変更種別）を含める。
+ *
+ * 従来はパス列挙のみだったため「なぜそのパスが不許可なのか」が読み取れず、
+ * 利用者が「ワークツリーの無関係な変更のせいでブロックされている」と
+ * 誤認する原因になっていた（issue #41 症状②）。
+ */
+function describeChangedFile(file: ChangedFile, category: string): string {
+  return `${file.filePath} (category=${category}, changeKind=${file.changeKind})`;
+}
+
 export class QuickModeJudgmentEngine {
-  classify(changedFiles: readonly ChangedFile[], _config?: QuickModeConfig): ChangeClassification {
+  classify(changedFiles: readonly ChangedFile[], config?: QuickModeConfig): ChangeClassification {
     if (changedFiles.length === 0) {
       return new ChangeClassification(null, new Map(), 0);
     }
 
+    const overrides = config?.categoryOverrides ?? CategoryOverrideRules.empty();
     const categorizedMap = new Map<string, ChangedFile[]>();
     let dominantCategory: ChangeCategory | null = null;
     let dominantPriority = -1;
 
     for (const file of changedFiles) {
-      const category = categorizeFile(file);
+      const category = categorizeFile(file, overrides);
       const key = category.toString();
 
       if (!categorizedMap.has(key)) {
@@ -99,7 +189,7 @@ export class QuickModeJudgmentEngine {
       }
       categorizedMap.get(key)!.push(file);
 
-      const priority = RISK_PRIORITY[key] ?? 0;
+      const priority = category.riskPriority();
       if (priority > dominantPriority) {
         dominantPriority = priority;
         dominantCategory = category;
@@ -115,9 +205,13 @@ export class QuickModeJudgmentEngine {
     // 1. MIXED_CHANGES評価: allowedCategories 外のカテゴリが含まれる場合
     if (config.isFullModeRequiredFor("mixedCategories")) {
       const notAllowedFiles: ChangedFile[] = [];
+      const notAllowedDescriptions: string[] = [];
       classification.categorizedFiles.forEach((files, categoryKey) => {
         if (!config.isAllowed(categoryKey)) {
           notAllowedFiles.push(...files);
+          for (const file of files) {
+            notAllowedDescriptions.push(describeChangedFile(file, categoryKey));
+          }
         }
       });
 
@@ -125,7 +219,7 @@ export class QuickModeJudgmentEngine {
         return QuickModeEligibility.rejected(
           "MIXED_CHANGES",
           notAllowedFiles,
-          `allowedCategories外のファイルが含まれています: ${notAllowedFiles.map((f) => f.filePath).join(", ")}`,
+          `allowedCategories外のファイルが含まれています: ${notAllowedDescriptions.join(", ")}`,
         );
       }
     }
@@ -140,7 +234,9 @@ export class QuickModeJudgmentEngine {
         return QuickModeEligibility.rejected(
           "NEW_DOMAIN",
           newDomainFiles,
-          `domain/配下に新規ファイルが追加されています: ${newDomainFiles.map((f) => f.filePath).join(", ")}`,
+          `domain/配下に新規ファイルが追加されています: ${newDomainFiles
+            .map((f) => describeChangedFile(f, categorizeFile(f, config.categoryOverrides).toString()))
+            .join(", ")}`,
         );
       }
     }
@@ -155,7 +251,9 @@ export class QuickModeJudgmentEngine {
         return QuickModeEligibility.rejected(
           "API_CONTRACT",
           apiContractFiles,
-          `Port/Adapterインターフェースファイルの変更が含まれています: ${apiContractFiles.map((f) => f.filePath).join(", ")}`,
+          `Port/Adapterインターフェースファイルの変更が含まれています: ${apiContractFiles
+            .map((f) => describeChangedFile(f, categorizeFile(f, config.categoryOverrides).toString()))
+            .join(", ")}`,
         );
       }
     }

package/scripts/harness/quick-mode/domain/value-objects/category-override-rules.ts

@@ -0,0 +1,147 @@
+/**
+ * @layer domain
+ * @unit quick-mode
+ * @work-item-id WI-372
+ *
+ * `quickMode.categoryOverrides` を表す値オブジェクト。
+ * ChangeCategory 7 値をキー、glob パターン列を値とする写像で、
+ * プロジェクト固有パス（`results/**` 等）を任意カテゴリへ割り当てる。
+ */
+
+import { QuickModeConfigError } from '../errors/quick-mode-config-error.js';
+import {
+  CHANGE_CATEGORY_VALUES,
+  ChangeCategory,
+  type ChangeCategoryValue,
+  isChangeCategoryValue,
+} from './change-category.js';
+
+/**
+ * glob → 正規表現の変換。
+ *
+ * domain 層は repo 全体で外部 npm パッケージを import していないため
+ * （picomatch は infrastructure adapter 専用）、
+ * `agent-integration/domain/value-objects/protected-file-list.ts` と同型の
+ * 純正規表現実装を採る（logical_design.md LD-10）。
+ *
+ * サポートする記法:
+ * - `**` … `/` を含む任意の文字列
+ * - `*`  … `/` を含まない任意の文字列
+ * - `?`  … `/` 以外の 1 文字
+ * - その他はリテラル（正規表現メタ文字はエスケープ）
+ */
+function globToRegExp(pattern: string): RegExp {
+  const regexSource = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '__DOUBLE_STAR__')
+    .replace(/\*/g, '[^/]*')
+    .replace(/__DOUBLE_STAR__/g, '.*')
+    .replace(/\?/g, '[^/]');
+  return new RegExp(`^${regexSource}$`);
+}
+
+export type CategoryOverrideRulesInput = Readonly<Record<string, readonly string[]>>;
+
+export class CategoryOverrideRules {
+  private readonly patterns: ReadonlyMap<ChangeCategoryValue, readonly string[]>;
+  private readonly matchers: ReadonlyMap<ChangeCategoryValue, readonly RegExp[]>;
+
+  private constructor(
+    patterns: ReadonlyMap<ChangeCategoryValue, readonly string[]>,
+    matchers: ReadonlyMap<ChangeCategoryValue, readonly RegExp[]>,
+  ) {
+    this.patterns = patterns;
+    this.matchers = matchers;
+    Object.freeze(this);
+  }
+
+  static empty(): CategoryOverrideRules {
+    return new CategoryOverrideRules(new Map(), new Map());
+  }
+
+  static create(raw: CategoryOverrideRulesInput | undefined | null): CategoryOverrideRules {
+    if (raw === undefined || raw === null) {
+      return CategoryOverrideRules.empty();
+    }
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+      throw new QuickModeConfigError('categoryOverrides must be an object keyed by change category');
+    }
+
+    const patterns = new Map<ChangeCategoryValue, readonly string[]>();
+    const matchers = new Map<ChangeCategoryValue, readonly RegExp[]>();
+
+    for (const [key, value] of Object.entries(raw)) {
+      if (!isChangeCategoryValue(key)) {
+        throw new QuickModeConfigError(
+          `categoryOverrides contains unknown category "${key}". Valid values: ${CHANGE_CATEGORY_VALUES.join(', ')}`,
+        );
+      }
+      if (!Array.isArray(value)) {
+        throw new QuickModeConfigError(`categoryOverrides.${key} must be an array of glob patterns`);
+      }
+      for (const pattern of value) {
+        if (typeof pattern !== 'string' || pattern.length === 0) {
+          throw new QuickModeConfigError(
+            `categoryOverrides.${key} must not contain an empty or non-string glob pattern`,
+          );
+        }
+      }
+      if (value.length === 0) {
+        continue;
+      }
+      patterns.set(key, Object.freeze([...value]));
+      matchers.set(key, Object.freeze(value.map(globToRegExp)));
+    }
+
+    return new CategoryOverrideRules(patterns, matchers);
+  }
+
+  isEmpty(): boolean {
+    return this.matchers.size === 0;
+  }
+
+  /**
+   * パスに対応する override カテゴリを返す。
+   * 一致が無ければ null（組み込み分類へ委譲）。
+   * 複数カテゴリに一致した場合はリスク優先度が最も高いカテゴリを返すため、
+   * JSON のキー列挙順に依存しない決定的な結果になる（domain_model.md DD-4）。
+   */
+  resolve(filePath: string): ChangeCategory | null {
+    if (filePath === '' || this.matchers.size === 0) {
+      return null;
+    }
+
+    let resolved: ChangeCategory | null = null;
+    let resolvedPriority = -1;
+
+    for (const [category, regexps] of this.matchers) {
+      if (!regexps.some((regexp) => regexp.test(filePath))) {
+        continue;
+      }
+      const candidate = ChangeCategory.fromString(category);
+      const priority = candidate.riskPriority();
+      if (priority > resolvedPriority) {
+        resolvedPriority = priority;
+        resolved = candidate;
+      }
+    }
+
+    return resolved;
+  }
+
+  /** キーは ChangeCategory 語彙順に正規化する（equals をキー順に依存させないため） */
+  toRecord(): Readonly<Record<string, readonly string[]>> {
+    const record: Record<string, readonly string[]> = {};
+    for (const category of CHANGE_CATEGORY_VALUES) {
+      const globs = this.patterns.get(category);
+      if (globs !== undefined) {
+        record[category] = globs;
+      }
+    }
+    return Object.freeze(record);
+  }
+
+  equals(other: CategoryOverrideRules): boolean {
+    return JSON.stringify(this.toRecord()) === JSON.stringify(other.toRecord());
+  }
+}

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

@@ -24,6 +24,31 @@ const VALID_CATEGORIES: readonly ChangeCategoryValue[] = [
   'api',
 ] as const;
 
+/**
+ * ChangeCategory の語彙。config の enum 検証や categoryOverrides の
+ * キー検証はこの定義を唯一の権威として参照する。
+ * @work-item-id WI-372
+ */
+export const CHANGE_CATEGORY_VALUES: readonly ChangeCategoryValue[] = VALID_CATEGORIES;
+
+/** 与えられた文字列が ChangeCategory の語彙に含まれるか（正規化はしない） */
+export function isChangeCategoryValue(raw: string): raw is ChangeCategoryValue {
+  return VALID_CATEGORIES.includes(raw as ChangeCategoryValue);
+}
+
+// リスク順優先度（api > domain > feature > bugfix > test > config > docs）。
+// 複数の分類条件に一致した場合に、より高リスク側へ倒すための順序定義。
+// @work-item-id WI-372
+const RISK_PRIORITY: Record<ChangeCategoryValue, number> = {
+  api: 6,
+  domain: 5,
+  feature: 4,
+  bugfix: 3,
+  test: 2,
+  config: 1,
+  docs: 0,
+};
+
 export class UnknownChangeCategoryError extends Error {
   constructor(raw: string) {
     super(`Unknown change category: "${raw}". Valid values: ${VALID_CATEGORIES.join(', ')}`);
@@ -50,6 +75,14 @@ export class ChangeCategory {
     return this.value === 'domain' || this.value === 'feature' || this.value === 'api';
   }
 
+  /**
+   * リスク優先度。値が大きいほど高リスク（api=6 ... docs=0）。
+   * @work-item-id WI-372
+   */
+  riskPriority(): number {
+    return RISK_PRIORITY[this.value];
+  }
+
   toString(): string {
     return this.value;
   }