phasegate 0.264.0 → 0.315.0

package/scripts/harness/phase-dependency-model/infrastructure/filesystem/markdown-plan-document-reader.ts

@@ -3,20 +3,32 @@
  * @unit phase-dependency-model
  */
 
-import { readFile } from 'node:fs/promises';
-import * as path from 'node:path';
-import type { PlanDocumentReaderPort } from '../../domain/ports/plan-document-reader-port.js';
-import type { PhaseNode } from '../../domain/values/phase-node.js';
-import type { PlanningMode } from '../../domain/values/planning-mode.js';
-import { PlanEvidence } from '../../domain/values/plan-evidence.js';
+import { readFile } from "node:fs/promises";
+import * as path from "node:path";
+import type { PlanDocumentReaderPort } from "../../domain/ports/plan-document-reader-port.js";
+import type { PhaseNode } from "../../domain/values/phase-node.js";
+import { PlanEvidence } from "../../domain/values/plan-evidence.js";
+import type { PlanningMode } from "../../domain/values/planning-mode.js";
 
 export interface MarkdownPlanDocumentReaderDeps {
   readonly rootDir: string;
 }
 
-const QA_SECTION_PATTERN = /^## QA\b/m;
-const QUESTION_PATTERN = /^Q:/gm;
-const ANSWER_PATTERN = /^A:/gm;
+/**
+ * WI-358 (issue #29): 見出しの表記ゆれで Planning Mode の evidence 判定が落ちる罠を潰す。
+ *
+ * 旧パターンは "QA" 綴りしか受け付けず、エージェントが自然に書く `## Q&A` /
+ * 全角の `## Q＆A` を弾いていた。中身は同一なのに phase gate だけが落ち、
+ * 原因が見出しの綴りだと気付けないまま止まる。
+ *
+ * 緩和方向のみの変更であり、既存の `## QA` / `## 4. QA（不明点・確認事項）` は
+ * すべて従来どおりマッチする。
+ */
+const QA_SECTION_PATTERN = /^##+\s*(?:\d+[.．]\s*)?Q[&＆]?A\b/m;
+const QUESTION_PATTERN = /^(?:Q:|###\s*\[Question\])/gm;
+const LEGACY_ANSWER_PATTERN = /^A:/gm;
+const STRUCTURED_ANSWER_PATTERN = /^\[Answer\][ \t]*$/gm;
+const ANSWER_BODY_BOUNDARY_PATTERN = /^(?:###\s*\[Question\]|#{1,6}\s+)/m;
 
 export class MarkdownPlanDocumentReader implements PlanDocumentReaderPort {
   private readonly rootDir: string;
@@ -55,7 +67,7 @@ export class MarkdownPlanDocumentReader implements PlanDocumentReaderPort {
 
     let content: string;
     try {
-      content = await readFile(absolutePath, 'utf8');
+      content = await readFile(absolutePath, "utf8");
     } catch {
       return PlanEvidence.create({
         exists: false,
@@ -66,11 +78,7 @@ export class MarkdownPlanDocumentReader implements PlanDocumentReaderPort {
 
     const hasQaSection = QA_SECTION_PATTERN.test(content);
     const qaComplete = this.isQaComplete(content, hasQaSection, expectedMode);
-    const planningModeMatch = this.detectPlanningModeMatch(
-      content,
-      hasQaSection,
-      expectedMode,
-    );
+    const planningModeMatch = this.detectPlanningModeMatch(content, hasQaSection, expectedMode);
 
     return PlanEvidence.create({
       exists: true,
@@ -79,16 +87,12 @@ export class MarkdownPlanDocumentReader implements PlanDocumentReaderPort {
     });
   }
 
-  private isQaComplete(
-    content: string,
-    hasQaSection: boolean,
-    expectedMode: PlanningMode,
-  ): boolean {
+  private isQaComplete(content: string, hasQaSection: boolean, expectedMode: PlanningMode): boolean {
     if (expectedMode.requiresAnsweredQa()) {
       if (!hasQaSection) return false;
       const qaSection = this.extractQaSection(content);
       const questionCount = (qaSection.match(QUESTION_PATTERN) ?? []).length;
-      const answerCount = (qaSection.match(ANSWER_PATTERN) ?? []).length;
+      const answerCount = this.countAnswers(qaSection);
       return questionCount > 0 && questionCount === answerCount;
     }
 
@@ -99,16 +103,12 @@ export class MarkdownPlanDocumentReader implements PlanDocumentReaderPort {
     return true;
   }
 
-  private detectPlanningModeMatch(
-    content: string,
-    hasQaSection: boolean,
-    expectedMode: PlanningMode,
-  ): boolean {
+  private detectPlanningModeMatch(content: string, hasQaSection: boolean, expectedMode: PlanningMode): boolean {
     if (expectedMode.requiresAnsweredQa()) {
       if (!hasQaSection) return false;
       const qaSection = this.extractQaSection(content);
       const questionCount = (qaSection.match(QUESTION_PATTERN) ?? []).length;
-      const answerCount = (qaSection.match(ANSWER_PATTERN) ?? []).length;
+      const answerCount = this.countAnswers(qaSection);
       return questionCount > 0 && answerCount === questionCount;
     }
 
@@ -121,14 +121,42 @@ export class MarkdownPlanDocumentReader implements PlanDocumentReaderPort {
 
   private extractQaSection(content: string): string {
     const match = content.match(QA_SECTION_PATTERN);
-    if (!match || match.index === undefined) return '';
+    if (!match || match.index === undefined) return "";
 
     const start = match.index;
-    const nextSectionMatch = content.slice(start + match[0].length).match(/^## /m);
-    const end = nextSectionMatch?.index
-      ? start + match[0].length + nextSectionMatch.index
-      : content.length;
+    const sectionContentStart = start + match[0].length;
+    const sectionContent = content.slice(sectionContentStart);
+    const headingMarker = match[0].match(/^##+/)?.[0];
+    if (!headingMarker) return "";
+
+    const sameLevelHeadingPattern = new RegExp(`^${headingMarker}(?!#)[ \\t]+(.+)$`, "gm");
+    let end = content.length;
+    for (const headingMatch of sectionContent.matchAll(sameLevelHeadingPattern)) {
+      if (/^\[Question\](?:\s|$)/.test(headingMatch[1].trimStart())) continue;
+      if (headingMatch.index !== undefined) {
+        end = sectionContentStart + headingMatch.index;
+        break;
+      }
+    }
 
     return content.slice(start, end);
   }
+
+  private countAnswers(qaSection: string): number {
+    const legacyAnswerCount = (qaSection.match(LEGACY_ANSWER_PATTERN) ?? []).length;
+    let structuredAnswerCount = 0;
+
+    for (const answerMatch of qaSection.matchAll(STRUCTURED_ANSWER_PATTERN)) {
+      if (answerMatch.index === undefined) continue;
+      const bodyStart = answerMatch.index + answerMatch[0].length;
+      const followingContent = qaSection.slice(bodyStart);
+      const boundaryMatch = followingContent.match(ANSWER_BODY_BOUNDARY_PATTERN);
+      const answerBody =
+        boundaryMatch?.index === undefined ? followingContent : followingContent.slice(0, boundaryMatch.index);
+      const hasBody = answerBody.split(/\r?\n/).some((line) => line.trim().length > 0);
+      if (hasBody) structuredAnswerCount += 1;
+    }
+
+    return legacyAnswerCount + structuredAnswerCount;
+  }
 }

package/scripts/harness/phase2-extensions/presentation/handlers/check-freshness-handler.ts

@@ -2,8 +2,8 @@
  * @layer presentation
  * @unit phase2-extensions
  */
-import type { CheckDocFreshnessUseCase } from '../../application/usecases/check-doc-freshness-usecase.js';
-import { FreshnessResultFormatter } from '../formatters/freshness-result-formatter.js';
+import type { CheckDocFreshnessUseCase } from "../../application/usecases/check-doc-freshness-usecase.js";
+import { FreshnessResultFormatter } from "../formatters/freshness-result-formatter.js";
 
 export class CheckFreshnessHandler {
   private readonly formatter = new FreshnessResultFormatter();
@@ -12,26 +12,34 @@ export class CheckFreshnessHandler {
 
   async handle(args: string[]): Promise<{ exitCode: number; stdout: string }> {
     let targetPattern: string | undefined;
-    let format: 'text' | 'json' = 'text';
+    let format: "text" | "json" = "text";
     let dryRun = false;
 
     for (let index = 0; index < args.length; index += 1) {
       const arg = args[index];
-      if (arg === '--pattern') {
+      if (arg === "--pattern") {
         targetPattern = args[index + 1];
         index += 1;
-      } else if (arg === '--format') {
-        format = (args[index + 1] as 'text' | 'json') ?? 'text';
+      } else if (arg === "--format") {
+        format = (args[index + 1] as "text" | "json") ?? "text";
         index += 1;
-      } else if (arg === '--dry-run') {
+      } else if (arg === "--dry-run") {
         dryRun = true;
       }
     }
 
     const result = await this.useCase.execute({ targetPattern, format, dryRun });
+    // WI-359: `--dry-run` は「副作用なしで診断のみ」（skills/doc-health-checker/SKILL.md）であり、
+    // シナリオ仕様 SC-P2-002 の期待結果も exit 0 である。従来は dryRun をパースだけして
+    // 捨てており、error 閾値超過の文書が 1 件でもあると診断のみの実行でも exit 1 になっていた。
+    // その結果 SC-P2-002 の e2e は「コードを一切変えなくても暦の経過だけで落ちる」状態になっていた。
+    // 実運用の鮮度ゲートは L4-004（`validate --layer L4`）が担い、そちらは本 handler を
+    // 経由しないため、dry-run を report-only にしてもゲートは緩まない。
+    // フラグ未指定時の exit 1 は従来どおり維持する。
+    const exitCode = dryRun ? 0 : result.summary.error > 0 ? 1 : 0;
     return {
-      exitCode: result.summary.error > 0 ? 1 : 0,
-      stdout: format === 'json' ? this.formatter.formatJson(result) : this.formatter.formatText(result),
+      exitCode,
+      stdout: format === "json" ? this.formatter.formatJson(result) : this.formatter.formatText(result),
     };
   }
 }

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/services/quick-mode-judgment-engine.ts

@@ -2,6 +2,8 @@
  * @layer domain
  * @unit quick-mode
  * @work-item-id WI-204
+ * @work-item-id WI-349
+ * @work-item-id WI-352
  *
  * ChangedFile[]をChangeClassificationに変換し、3拒否ルールを評価してQuickModeEligibilityを返すドメインサービス
  */
@@ -24,6 +26,37 @@ const RISK_PRIORITY: Record<string, number> = {
   docs: 0,
 };
 
+// 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 categorizeFile(file: ChangedFile): ChangeCategory {
   const { filePath, changeKind } = file;
 
@@ -37,6 +70,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,6 +130,17 @@ function categorizeFile(file: ChangedFile): ChangeCategory {
   return ChangeCategory.fromString("bugfix");
 }
 
+/**
+ * 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 {
     if (changedFiles.length === 0) {
@@ -115,9 +176,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 +190,7 @@ export class QuickModeJudgmentEngine {
         return QuickModeEligibility.rejected(
           "MIXED_CHANGES",
           notAllowedFiles,
-          `allowedCategories外のファイルが含まれています: ${notAllowedFiles.map((f) => f.filePath).join(", ")}`,
+          `allowedCategories外のファイルが含まれています: ${notAllowedDescriptions.join(", ")}`,
         );
       }
     }
@@ -140,7 +205,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).toString()))
+            .join(", ")}`,
         );
       }
     }
@@ -155,7 +222,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).toString()))
+            .join(", ")}`,
         );
       }
     }

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