phasegate 0.138.1 → 0.140.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.140.0] - 2026-05-09
+
+### Added
+
+- **WI-024 — configurable L1 metadata tag names** — `architecture.metadataTags.unit` / `architecture.metadataTags.layer` を biome-ast-engine の L1 parser / analyzer / runner に反映し、`@module` / `@tier` などのプロジェクト語彙を単一の有効タグ名として使えるようにした。
+  - 既定値は従来通り `@unit` / `@layer`。
+  - カスタムタグ設定時は旧タグを alias として扱わず、欠落メッセージも設定タグ名を表示する。
+
+## [0.139.0] - 2026-05-09
+
+### Added
+
+- **WI-012 — pre-commit implementation extension 設定** — `preCommit.implementationExtensions` を config schema / preset / pre-commit adapter に追加し、`.ts` 以外の実装ファイル拡張子を検査対象にできるようにした。
+
+### Fixed
+
+- **WI-015 — quick mode comment-only API diff** — API 面の TypeScript ファイルでコメントのみが変わった場合、quick mode が implementation 証拠なしで `pending` に戻さないようにした。
+- **WI-030 — README / layer-model drift correction** — 公開ドキュメントの validator 数と L0 記述を現行仕様に合わせて更新した。
+- **WI-061 / WI-062 / WI-063 / WI-064 / WI-071 — reflected regression / skill WI closure** — 既存実装と回帰テストの証跡に基づき、対応済み WI を `tested` に整理した。
+
+## [0.138.1] - 2026-05-09
+
 ### Fixed
 
 - **WI-106 — inception WI ID 重複防止** — `docs/inception/**/WI-XXX/description.md` の frontmatter `id` を global scan し、`_cross` と Unit 配下をまたぐ重複、および parent directory 名と `id` の不一致を `validate-metadata` 経路で検出するようにした。

package/README.ja.md

@@ -148,7 +148,7 @@ npx phasegate update-skills   # スキルを最新版に再デプロイ
 |     security, performance, coverage 90%/95%, 要件カバレッジ        |
 +------------------------------------------------------------------+
 | L4  週次 (default off)                                           |
-|     設計-コード乖離, 文書整合性, デッドコード, 文書鮮度          |
+|     設計-コード乖離, 文書整合性, デッドコード                    |
 +------------------------------------------------------------------+
 ```
 

package/README.md

@@ -146,7 +146,7 @@ npx phasegate update-skills
 +------------------------------------------------------------------+
 |  L4  SCHEDULED             Validators (default off)              |
 |  drift-detection, consistency-check, dead-code analysis,         |
-|  doc-freshness, pointer-validation                               |
+|  phase2 freshness/pointer checks via standalone p2:* commands    |
 +------------------------------------------------------------------+
 ```
 
@@ -156,7 +156,7 @@ npx phasegate update-skills
 | L1 | Editor save / `phasegate lint` | `@unit` / `@layer` metadata, layer violations, AI anti-patterns, dead code |
 | L2 | Pre-commit (also evaluated inside PreToolUse at L0) | Phase gate, metadata completeness, `@work-item-id` reflection (`L2-STORY-REFLECTION`), test quality |
 | L3 | CI/CD pipeline | Security, performance, coverage (90%/95%), requirements traceability |
-| L4 | Scheduled (weekly). Currently `layers.L4.enabled: false` by default — opt-in per project | Design-code drift, cross-document consistency, dead code, doc freshness, pointer validation |
+| L4 | Scheduled (weekly). Currently `layers.L4.enabled: false` by default — opt-in per project | Design-code drift, cross-document consistency, dead code. Doc freshness and pointer checks are standalone `p2:*` commands until WI-033. |
 
 ---
 

package/docs/guide/configuration.md

@@ -58,6 +58,9 @@ This file is the **Single Source of Truth** for all quality configuration in a P
     "format": "json",
     "outputDir": "reports"
   },
+  "preCommit": {
+    "implementationExtensions": [".ts"]
+  },
   "baseline": {
     "enabled": true,
     "path": ".phasegate/baseline.json"
@@ -144,6 +147,24 @@ Set a flag to `false` only when the project intentionally accepts the risk of me
 | `gates`            | `array`    | `[]`         | Array of custom phase gate definitions. See [gates\[\]](#gates-custom-phase-gates) below. Optional; defaults to empty. |
 | `storyReflection`  | `object`   | preset-based | See [storyReflection](#storyreflection-inception--product-gate) below. Omit entirely for zero-config defaults per preset. |
 
+#### `preCommit`
+
+| Sub-field | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `implementationExtensions` | `string[]` | `[".ts"]` | File extensions treated as implementation files by `phasegate pre-commit`. Add entries such as `".py"` or `".go"` for non-TypeScript projects. |
+
+Example for Python and TypeScript:
+
+```jsonc
+{
+  "preCommit": {
+    "implementationExtensions": [".ts", ".py"]
+  }
+}
+```
+
+The metadata validators read `@unit` and `@layer` with language-agnostic regular expressions, so Python `# @unit api` and Go `// @unit api` style comments are both valid as long as the file extension is included here.
+
 ##### Phase Dependency Presets
 
 | Preset     | Phase 3 Gates | storyReflection default                                                 | Use Case                                           |

package/docs/guide/layer-model.md

@@ -147,8 +147,8 @@ L4 validators are designed to run on a weekly schedule and detect slow-moving dr
 | **drift-detect** | L4-001 | Bidirectional design-code drift detection. Compares design documents against the actual codebase to find divergence in either direction. |
 | **consistency-check** | L4-002 | Cross-document layer consistency. Ensures that references between design documents, ADRs, and code remain coherent. |
 | **dead-code** | L4-003 | Detects unused exports and unreachable code that should be removed. |
-| **doc-freshness** | L4-004 | Checks whether design documents exceed the configured freshness threshold. The standalone `p2:check-freshness` CLI remains available. |
-| **pointer-validation** | L4-005 | Validates file-path pointers embedded in design documents. The standalone `p2:validate-pointers` CLI remains available. |
+
+`doc-freshness` and `pointer-validation` are implemented as `phase2-extensions` CLI commands (`p2:check-freshness` and `p2:validate-pointers`). They are not registered as L4 validators yet, so `validate --layer L4` does not run them until WI-033 promotes them into `validator-system`.
 
 ### Drift-detect design pointers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.138.1",
+  "version": "0.140.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",

package/scripts/harness/agent-integration/application/dto/handle-pre-tool-use-dto.ts

@@ -6,6 +6,11 @@
 export interface HandlePreToolUseInput {
   toolName: string;
   targetFilePaths: string[];
+  targetChanges?: {
+    filePath: string;
+    beforeContent?: string | null;
+    afterContent?: string | null;
+  }[];
 }
 
 export interface HandlePreToolUseOutput {

package/scripts/harness/agent-integration/application/usecases/handle-pre-tool-use-usecase.ts

@@ -143,7 +143,10 @@ export class HandlePreToolUseUseCase {
       if (grandfather.allGrandfathered) {
         this.grandfatherLogger("full-mode", input.targetFilePaths);
       } else {
-        const fullModeResult = await this.fullModeRequirementQueryPort.check(input.targetFilePaths);
+        const fullModeResult = await this.fullModeRequirementQueryPort.check(
+          input.targetFilePaths,
+          input.targetChanges,
+        );
         if (fullModeResult.requiresFullMode) {
           // ISSUE-021: 当該Unitの必須設計文書が揃っている場合は full mode block を bypass
           //（hook がスキルコンテキストを参照できない構造的ギャップへの対処）

package/scripts/harness/agent-integration/domain/ports/full-mode-requirement-query-port.ts

@@ -8,6 +8,15 @@ export interface FullModeRequirementQueryResult {
   readonly dominantCategory?: string;
 }
 
+export interface FullModeTargetChange {
+  readonly filePath: string;
+  readonly beforeContent?: string | null;
+  readonly afterContent?: string | null;
+}
+
 export interface FullModeRequirementQueryPort {
-  check(targetFilePaths: readonly string[]): Promise<FullModeRequirementQueryResult>;
+  check(
+    targetFilePaths: readonly string[],
+    targetChanges?: readonly FullModeTargetChange[],
+  ): Promise<FullModeRequirementQueryResult>;
 }

package/scripts/harness/agent-integration/infrastructure/adapters/quick-mode-full-mode-requirement-adapter.ts

@@ -4,6 +4,7 @@
 import type {
   FullModeRequirementQueryPort,
   FullModeRequirementQueryResult,
+  FullModeTargetChange,
 } from '../../domain/ports/full-mode-requirement-query-port.js';
 import type { ClassifyChangeCategoryUseCase } from '../../../quick-mode/application/usecases/classify-change-category-usecase.js';
 
@@ -18,14 +19,20 @@ export class QuickModeFullModeRequirementAdapter implements FullModeRequirementQ
     this.classifyUseCaseFactory = deps.classifyUseCaseFactory;
   }
 
-  async check(targetFilePaths: readonly string[]): Promise<FullModeRequirementQueryResult> {
+  async check(
+    targetFilePaths: readonly string[],
+    targetChanges?: readonly FullModeTargetChange[],
+  ): Promise<FullModeRequirementQueryResult> {
     if (targetFilePaths.length === 0) {
       return { requiresFullMode: false };
     }
 
     try {
       const useCase = this.classifyUseCaseFactory();
-      const contract = await useCase.execute({ paths: [...targetFilePaths] });
+      const contract = await useCase.execute({
+        paths: [...targetFilePaths],
+        targetChanges,
+      });
       if (!contract.fullModeRequired) {
         return {
           requiresFullMode: false,

package/scripts/harness/agent-integration/presentation/pre-tool-use-hook.ts

@@ -27,10 +27,21 @@ interface PreToolUseHookInput {
     file_path?: string;
     paths?: string[];
     command?: string;
+    content?: string;
+    old_string?: string;
+    new_string?: string;
+    old_str?: string;
+    new_str?: string;
     [key: string]: unknown;
   };
 }
 
+interface TargetChange {
+  filePath: string;
+  beforeContent?: string | null;
+  afterContent?: string | null;
+}
+
 async function readStdin(): Promise<string> {
   const chunks: Buffer[] = [];
   for await (const chunk of process.stdin) {
@@ -98,6 +109,8 @@ async function main(): Promise<void> {
     targetFilePaths.push(...input.tool_input.paths.map(toRelative));
   }
 
+  const targetChanges = await buildTargetChanges(input, cwd, toRelative);
+
   // Bash 経由書き込みのフェーズゲート対応 (A-2.5)
   // Bash command 文字列からリダイレクト・tee・sed -i・cp・mv・touch 等の
   // 書き込み先ファイルパスを抽出し、フェーズゲートチェック対象に含める。
@@ -141,7 +154,7 @@ async function main(): Promise<void> {
       errorGuidanceQueryPort,
     });
 
-    const output = await useCase.execute({ toolName: effectiveToolName, targetFilePaths });
+    const output = await useCase.execute({ toolName: effectiveToolName, targetFilePaths, targetChanges });
 
     if (output.shouldBlock) {
       const msg = output.error?.message
@@ -165,6 +178,48 @@ async function main(): Promise<void> {
   }
 }
 
+async function buildTargetChanges(
+  input: PreToolUseHookInput,
+  cwd: string,
+  toRelative: (p: string) => string,
+): Promise<TargetChange[]> {
+  const toolInput = input.tool_input;
+  if (toolInput === undefined) {
+    return [];
+  }
+
+  const rawPath = toolInput.file_path ?? toolInput.path;
+  if (rawPath === undefined) {
+    return [];
+  }
+
+  const filePath = toRelative(rawPath);
+  const oldString = typeof toolInput.old_string === 'string' ? toolInput.old_string : toolInput.old_str;
+  const newString = typeof toolInput.new_string === 'string' ? toolInput.new_string : toolInput.new_str;
+  if (typeof oldString === 'string' && typeof newString === 'string') {
+    return [{ filePath, beforeContent: oldString, afterContent: newString }];
+  }
+
+  if (typeof toolInput.content === 'string') {
+    return [{
+      filePath,
+      beforeContent: await readExistingContent(cwd, rawPath),
+      afterContent: toolInput.content,
+    }];
+  }
+
+  return [];
+}
+
+async function readExistingContent(cwd: string, filePath: string): Promise<string | null> {
+  const absolutePath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  try {
+    return await fs.readFile(absolutePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
 main().catch((error) => {
   process.stderr.write(`予期しないエラー: ${String(error)}\n`);
   process.exit(2);

package/scripts/harness/biome-ast-engine/application/usecases/resolve-enabled-rules-usecase.ts

@@ -60,6 +60,7 @@ export class ResolveEnabledRulesUseCase {
     const architectureSpec = freezeArchitectureSpec({
       layers: architecture.layers,
       allowedDependencies: architecture.allowedDependencies,
+      metadataTags: architecture.metadataTags,
     });
 
     return toResolveEnabledRulesOutput(

package/scripts/harness/biome-ast-engine/domain/ports/rule-config-provider-port.ts

@@ -16,6 +16,10 @@ export interface ArchitectureProviderInfo {
   readonly preset: ArchitecturePresetIdValue;
   readonly layers: readonly string[];
   readonly allowedDependencies: Readonly<Record<string, readonly string[]>>;
+  readonly metadataTags?: {
+    readonly unit?: string;
+    readonly layer?: string;
+  };
 }
 
 export interface RuleConfigProviderPort {

package/scripts/harness/biome-ast-engine/domain/services/lint-runner.ts

@@ -75,7 +75,7 @@ export class LintRunner {
                   line: 1,
                   column: 1,
                   ruleName: rule.name,
-                  message: '@unitコメントが必要です',
+                  message: `${architecture.metadataTags.unit}コメントが必要です`,
                   severity: rule.severity,
                 })
               );
@@ -92,7 +92,7 @@ export class LintRunner {
                   line: 1,
                   column: 1,
                   ruleName: rule.name,
-                  message: '@layerコメントが必要です',
+                  message: `${architecture.metadataTags.layer}コメントが必要です`,
                   severity: rule.severity,
                 })
               );

package/scripts/harness/biome-ast-engine/domain/value-objects/architecture-spec.ts

@@ -6,8 +6,25 @@
 export type ArchitectureSpec = {
   readonly layers: readonly string[];
   readonly allowedDependencies: Readonly<Record<string, readonly string[]>>;
+  readonly metadataTags: ArchitectureMetadataTags;
 };
 
+export type ArchitectureMetadataTags = {
+  readonly unit: string;
+  readonly layer: string;
+};
+
+export type ArchitectureSpecInput = {
+  readonly layers: readonly string[];
+  readonly allowedDependencies: Readonly<Record<string, readonly string[]>>;
+  readonly metadataTags?: Partial<ArchitectureMetadataTags>;
+};
+
+export const DEFAULT_METADATA_TAGS: ArchitectureMetadataTags = Object.freeze({
+  unit: '@unit',
+  layer: '@layer',
+});
+
 const freezeDependencyMap = (
   map: Record<string, readonly string[]>
 ): Readonly<Record<string, readonly string[]>> => {
@@ -20,10 +37,14 @@ const freezeDependencyMap = (
   return Object.freeze(frozen);
 };
 
-export const freezeArchitectureSpec = (spec: ArchitectureSpec): ArchitectureSpec => {
+export const freezeArchitectureSpec = (spec: ArchitectureSpecInput): ArchitectureSpec => {
   return Object.freeze({
     layers: Object.freeze([...spec.layers]),
     allowedDependencies: freezeDependencyMap({ ...spec.allowedDependencies }),
+    metadataTags: Object.freeze({
+      ...DEFAULT_METADATA_TAGS,
+      ...spec.metadataTags,
+    }),
   });
 };
 

package/scripts/harness/biome-ast-engine/infrastructure/adapters/harness-config-provider-adapter.ts

@@ -29,6 +29,10 @@ const DEFAULT_ARCHITECTURE: ArchitectureConfigInput = Object.freeze({
     infrastructure: Object.freeze(['infrastructure', 'application', 'domain']),
     presentation: Object.freeze(['presentation', 'application', 'domain']),
   }),
+  metadataTags: Object.freeze({
+    unit: '@unit',
+    layer: '@layer',
+  }),
 });
 
 /**

package/scripts/harness/biome-ast-engine/infrastructure/adapters/typescript-source-module-analyzer-adapter.ts

@@ -56,8 +56,8 @@ export class TypeScriptSourceModuleAnalyzerAdapter implements SourceModuleAnalyz
       }
 
       const sourceText = sourceFile.getFullText();
-      const unitResult = parseUnitComment(sourceText);
-      const layerResult = parseLayerComment(sourceText);
+      const unitResult = parseUnitComment(sourceText, architecture?.metadataTags.unit);
+      const layerResult = parseLayerComment(sourceText, architecture?.metadataTags.layer);
       const densityResult = parseCommentDensity(sourceText);
       const imports = this.extractImports(sourceFile, filePath);
       const anyCount = this.countAnyTypes(sourceFile);
@@ -69,7 +69,7 @@ export class TypeScriptSourceModuleAnalyzerAdapter implements SourceModuleAnalyz
         SourceModuleSnapshot.create(
           {
             filePath,
-            declaredUnit: unitResult.unitNames[0],
+            declaredUnit: unitResult.unitNames[0] ?? null,
             declaredLayer: layerResult.layerName,
             imports,
             anyTypeCount: anyCount,

package/scripts/harness/biome-ast-engine/infrastructure/parsers/layer-comment-parser.ts

@@ -1,14 +1,22 @@
 // @unit biome-ast-engine
 // @layer infrastructure
 
-const LAYER_COMMENT_PATTERN = /^\s*(?:\/\/|\/\*\*?\s*|\*)\s*@layer\s+(\S+)/m;
+const DEFAULT_LAYER_TAG = '@layer';
+
+const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+const createLayerCommentPattern = (tagName: string): RegExp =>
+  new RegExp(`^\\s*(?:\\/\\/|\\/\\*\\*?\\s*|\\*)\\s*${escapeRegExp(tagName)}\\s+(\\S+)`, 'm');
 
 export type LayerCommentResult = {
   readonly layerName: string | null;
 };
 
-export const parseLayerComment = (sourceCode: string): LayerCommentResult => {
-  const match = sourceCode.match(LAYER_COMMENT_PATTERN);
+export const parseLayerComment = (
+  sourceCode: string,
+  tagName: string = DEFAULT_LAYER_TAG
+): LayerCommentResult => {
+  const match = sourceCode.match(createLayerCommentPattern(tagName));
 
   if (!match) {
     return { layerName: null };

package/scripts/harness/biome-ast-engine/infrastructure/parsers/unit-comment-parser.ts

@@ -1,15 +1,23 @@
 // @unit biome-ast-engine
 // @layer infrastructure
 
-// カンマ区切り複数ユニット対応 + 複数行の @unit を収集、重複除去。
-const UNIT_COMMENT_PATTERN = /^\s*(?:\/\/|\/\*\*?\s*|\*)\s*@unit\s+(.+)/gm;
+// カンマ区切り複数ユニット対応 + 複数行の metadata unit tag を収集、重複除去。
+const DEFAULT_UNIT_TAG = '@unit';
+
+const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+const createUnitCommentPattern = (tagName: string): RegExp =>
+  new RegExp(`^\\s*(?:\\/\\/|\\/\\*\\*?\\s*|\\*)\\s*${escapeRegExp(tagName)}\\s+(.+)`, 'gm');
 
 export type UnitCommentResult = {
   readonly unitNames: readonly string[];
 };
 
-export const parseUnitComment = (sourceCode: string): UnitCommentResult => {
-  const matches = sourceCode.matchAll(UNIT_COMMENT_PATTERN);
+export const parseUnitComment = (
+  sourceCode: string,
+  tagName: string = DEFAULT_UNIT_TAG
+): UnitCommentResult => {
+  const matches = sourceCode.matchAll(createUnitCommentPattern(tagName));
   const names: string[] = [];
 
   for (const match of matches) {

package/scripts/harness/config-foundation/domain/harness-config.ts

@@ -52,6 +52,7 @@ export interface HarnessConfigSourceDocument {
   reporting: HarnessConfigResolvedDocument['reporting'];
   ci?: HarnessConfigResolvedDocument['ci'];
   validate?: HarnessConfigResolvedDocument['validate'];
+  preCommit?: Partial<HarnessConfigResolvedDocument['preCommit']>;
   architecture?: ArchitectureConfigSource;
 }
 
@@ -117,6 +118,9 @@ export interface HarnessConfigResolvedDocument {
   validate: {
     failOnWarning: boolean;
   };
+  preCommit?: {
+    implementationExtensions: string[];
+  };
   architecture?: ArchitectureConfigDocument;
 }
 

package/scripts/harness/config-foundation/domain/services/preset-resolution-service.ts

@@ -19,6 +19,7 @@ export interface PresetDefinition {
   paths: HarnessConfigResolvedDocument['paths'];
   reporting: HarnessConfigResolvedDocument['reporting'];
   validate: HarnessConfigResolvedDocument['validate'];
+  preCommit?: HarnessConfigResolvedDocument['preCommit'];
 }
 
 export class InvalidPresetDefinitionError extends ConfigFoundationDomainError {
@@ -184,6 +185,11 @@ export class PresetResolutionService {
         sourceDocument.validate,
         'validate',
       ),
+      preCommit: deepMerge(
+        presetDefinition.preCommit ?? { implementationExtensions: ['.ts'] },
+        sourceDocument.preCommit,
+        'preCommit',
+      ),
     };
   }
 

package/scripts/harness/config-foundation/infrastructure/presets/minimal.json

@@ -49,5 +49,8 @@
   },
   "validate": {
     "failOnWarning": false
+  },
+  "preCommit": {
+    "implementationExtensions": [".ts"]
   }
 }

package/scripts/harness/config-foundation/infrastructure/presets/standard.json

@@ -49,5 +49,8 @@
   },
   "validate": {
     "failOnWarning": false
+  },
+  "preCommit": {
+    "implementationExtensions": [".ts"]
   }
 }

package/scripts/harness/config-foundation/infrastructure/presets/strict.json

@@ -49,5 +49,8 @@
   },
   "validate": {
     "failOnWarning": true
+  },
+  "preCommit": {
+    "implementationExtensions": [".ts"]
   }
 }

package/scripts/harness/config-foundation/infrastructure/schemas/harness-config-v2.schema.json

@@ -357,6 +357,21 @@
         }
       }
     },
+    "preCommit": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "implementationExtensions": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^\\.[A-Za-z0-9]+$"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      }
+    },
     "planningMode": {
       "type": "object",
       "additionalProperties": false,

package/scripts/harness/config-foundation/infrastructure/schemas/harness-config-v3.schema.json

@@ -357,6 +357,21 @@
         }
       }
     },
+    "preCommit": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "implementationExtensions": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^\\.[A-Za-z0-9]+$"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      }
+    },
     "planningMode": {
       "type": "object",
       "additionalProperties": false,

package/scripts/harness/integrations/pre-commit.ts

@@ -32,7 +32,7 @@ const BOLD = "\x1b[1m";
 const DIM = "\x1b[2m";
 const RESET = "\x1b[0m";
 
-const TS_EXTENSION = ".ts";
+const DEFAULT_IMPLEMENTATION_EXTENSIONS = Object.freeze([".ts"]);
 const MD_EXTENSION = ".md";
 const WORK_ITEM_PATH_PATTERN = /(?:^|\/)WI-\d+(?:\/|$)/;
 const WORK_ITEM_TRAILER_PATTERN = /^Work-Item:\s*WI-\d+\s*$/m;
@@ -62,6 +62,17 @@ async function loadTraceabilityModelOptions(): Promise<
   }
 }
 
+async function loadPreCommitImplementationExtensions(): Promise<readonly string[] | undefined> {
+  const configMod = createConfigFoundationModule();
+  try {
+    const resolvedConfig = await configMod.usecases.loadResolvedConfigUseCase.execute();
+    return resolvedConfig.config.preCommit?.implementationExtensions;
+  } catch (err) {
+    if (err instanceof ConfigNotFoundError) return undefined;
+    throw err;
+  }
+}
+
 function isTestFile(path: string): boolean {
   return TEST_FILE_SUFFIXES.some((suffix) => path.endsWith(suffix));
 }
@@ -179,6 +190,7 @@ export interface PreCommitOptions {
    * intentionally opt-in and preserves existing local pre-commit behavior.
    */
   readonly commitMessage?: string;
+  readonly implementationExtensions?: readonly string[];
 }
 
 function getStagedFiles(): string[] {
@@ -233,17 +245,29 @@ function hasWorkItemTrailer(commitMessage: string): boolean {
   return WORK_ITEM_TRAILER_PATTERN.test(commitMessage);
 }
 
+function normalizeImplementationExtensions(extensions: readonly string[] | undefined): readonly string[] {
+  const rawExtensions = extensions === undefined || extensions.length === 0
+    ? DEFAULT_IMPLEMENTATION_EXTENSIONS
+    : extensions;
+  return rawExtensions.map((extension) => extension.startsWith(".") ? extension : `.${extension}`);
+}
+
+function hasAnyExtension(filePath: string, extensions: readonly string[]): boolean {
+  return extensions.some((extension) => filePath.endsWith(extension));
+}
+
 export async function runPreCommit(
   stagedFiles: readonly string[],
   deps: PreCommitDeps,
   options: PreCommitOptions = {},
 ): Promise<PreCommitResult> {
-  const tsFiles = stagedFiles.filter((f) => f.endsWith(TS_EXTENSION));
+  const implementationExtensions = normalizeImplementationExtensions(options.implementationExtensions);
+  const implementationFiles = stagedFiles.filter((f) => hasAnyExtension(f, implementationExtensions));
   const mdFiles = stagedFiles.filter((f) => f.endsWith(MD_EXTENSION) && isMetadataMarkdownFile(f));
-  const testFiles = tsFiles.filter((f) => isTestFile(f));
+  const testFiles = implementationFiles.filter((f) => isTestFile(f));
   const metadataFiles = [...mdFiles, ...testFiles];
 
-  if (tsFiles.length === 0 && mdFiles.length === 0) {
+  if (implementationFiles.length === 0 && mdFiles.length === 0) {
     return {
       exitCode: 0,
       stdout: `${DIM}[phasegate] No staged files to check. Skipping.${RESET}`,
@@ -252,17 +276,18 @@ export async function runPreCommit(
 
   const sections: string[] = [];
   sections.push(
-    `${BOLD}[phasegate]${RESET} Pre-commit check ` + `(${tsFiles.length} .ts file(s), ${mdFiles.length} .md file(s))`,
+    `${BOLD}[phasegate]${RESET} Pre-commit check ` +
+      `(${implementationFiles.length} implementation file(s), ${mdFiles.length} .md file(s))`,
   );
 
   let exitCode: 0 | 1 | 2 = 0;
 
-  if (tsFiles.length > 0) {
+  if (implementationFiles.length > 0) {
     // staged TS file を Unit ごとにグルーピングし、Unit 単位で L2 phase gate
     // （L2-001 の `{unit}_unit.md` 等）を評価する。Unit を特定できないファイルは
     // 別グループ（unitName=''）として従来挙動で評価する。
     const filesByUnit = new Map<string, string[]>();
-    for (const f of tsFiles) {
+    for (const f of implementationFiles) {
       const unit = (await resolveUnitName(f)) ?? "";
       const bucket = filesByUnit.get(unit);
       if (bucket) {
@@ -285,7 +310,7 @@ export async function runPreCommit(
     const merged = mergePerUnitResults(runs);
     const report = buildReport(merged);
     sections.push("");
-    sections.push(`${BOLD}== TypeScript 実装 (${tsFiles.length} file(s)) ==${RESET}`);
+    sections.push(`${BOLD}== 実装ファイル (${implementationFiles.length} file(s)) ==${RESET}`);
     sections.push(new HumanValidationResultFormatter().format(report));
     if (!report.overallPassed) {
       exitCode = maxExitCode(exitCode, 1);
@@ -345,6 +370,7 @@ export async function runPreCommitCli(): Promise<void> {
       },
       {
         commitMessage: process.env.PHASEGATE_COMMIT_MESSAGE,
+        implementationExtensions: await loadPreCommitImplementationExtensions(),
       },
     );
 
@@ -378,7 +404,10 @@ export async function runCommitMsgCli(commitMessagePath: string | undefined): Pr
         runL2ValidatorsUseCase: validatorMod.runL2ValidatorsUseCase,
         validateMetadataCommandHandler: traceabilityMod.validateMetadataCommandHandler,
       },
-      { commitMessage },
+      {
+        commitMessage,
+        implementationExtensions: await loadPreCommitImplementationExtensions(),
+      },
     );
 
     process.stdout.write(`${result.stdout}\n`);

package/scripts/harness/main.ts

@@ -490,6 +490,7 @@ function toArchitectureInput(resolvedConfig: HarnessConfigV2) {
     preset: resolvedConfig.architecture.preset,
     layers: resolvedConfig.architecture.layers,
     allowedDependencies: resolvedConfig.architecture.allowedDependencies,
+    metadataTags: resolvedConfig.architecture.metadataTags,
   };
 }
 

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

@@ -13,6 +13,11 @@ import type { ChangeCategoryClassificationContract, ChangeCategoryPerFile } from
 
 export interface ClassifyChangeCategoryUseCaseInput {
   readonly paths: readonly string[];
+  readonly targetChanges?: readonly {
+    readonly filePath: string;
+    readonly beforeContent?: string | null;
+    readonly afterContent?: string | null;
+  }[];
 }
 
 export interface ClassifyChangeCategoryUseCaseDeps {
@@ -42,9 +47,16 @@ export class ClassifyChangeCategoryUseCase {
       });
     }
 
-    const changedFiles = input.paths.map((p) =>
-      ChangedFile.create({ filePath: p, changeKind: 'MODIFY' })
-    );
+    const targetChanges = new Map((input.targetChanges ?? []).map((change) => [change.filePath, change]));
+    const changedFiles = input.paths.map((p) => {
+      const targetChange = targetChanges.get(p);
+      return ChangedFile.create({
+        filePath: p,
+        changeKind: 'MODIFY',
+        beforeContent: targetChange?.beforeContent ?? null,
+        afterContent: targetChange?.afterContent ?? null,
+      });
+    });
 
     const classification = this.judgmentEngine.classify(changedFiles, config);
     const eligibility = this.judgmentEngine.judge(changedFiles, config);

package/scripts/harness/quick-mode/domain/services/comment-only-diff-detector.ts

@@ -0,0 +1,94 @@
+/**
+ * @layer domain
+ * @unit quick-mode
+ * @work-item-id WI-015
+ */
+
+import type { ChangedFile } from '../value-objects/changed-file.js';
+
+type ScannerState = 'normal' | 'single' | 'double' | 'template' | 'lineComment' | 'blockComment';
+
+function stripCommentsAndWhitespace(source: string): string {
+  let state: ScannerState = 'normal';
+  let output = '';
+  let escaped = false;
+
+  for (let i = 0; i < source.length; i += 1) {
+    const char = source[i] ?? '';
+    const next = source[i + 1] ?? '';
+
+    if (state === 'lineComment') {
+      if (char === '\n' || char === '\r') {
+        state = 'normal';
+      }
+      continue;
+    }
+
+    if (state === 'blockComment') {
+      if (char === '*' && next === '/') {
+        i += 1;
+        state = 'normal';
+      }
+      continue;
+    }
+
+    if (state === 'single' || state === 'double' || state === 'template') {
+      output += char;
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (char === '\\') {
+        escaped = true;
+        continue;
+      }
+      if (
+        (state === 'single' && char === "'") ||
+        (state === 'double' && char === '"') ||
+        (state === 'template' && char === '`')
+      ) {
+        state = 'normal';
+      }
+      continue;
+    }
+
+    if (char === '/' && next === '/') {
+      state = 'lineComment';
+      i += 1;
+      continue;
+    }
+    if (char === '/' && next === '*') {
+      state = 'blockComment';
+      i += 1;
+      continue;
+    }
+    if (char === "'") {
+      state = 'single';
+      output += char;
+      continue;
+    }
+    if (char === '"') {
+      state = 'double';
+      output += char;
+      continue;
+    }
+    if (char === '`') {
+      state = 'template';
+      output += char;
+      continue;
+    }
+    if (!/\s/.test(char)) {
+      output += char;
+    }
+  }
+
+  return output;
+}
+
+export function isCommentOnlyDiff(file: ChangedFile): boolean {
+  if (typeof file.beforeContent !== 'string' || typeof file.afterContent !== 'string') {
+    return false;
+  }
+
+  return stripCommentsAndWhitespace(file.beforeContent) === stripCommentsAndWhitespace(file.afterContent);
+}

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

@@ -8,6 +8,7 @@
 import { ChangeCategory } from '../value-objects/change-category.js';
 import { ChangeClassification } from '../value-objects/change-classification.js';
 import { QuickModeEligibility } from '../value-objects/quick-mode-eligibility.js';
+import { isCommentOnlyDiff } from './comment-only-diff-detector.js';
 import type { ChangedFile } from '../value-objects/changed-file.js';
 import type { QuickModeConfig } from '../value-objects/quick-mode-config.js';
 
@@ -25,6 +26,10 @@ const RISK_PRIORITY: Record<string, number> = {
 function categorizeFile(file: ChangedFile): ChangeCategory {
   const { filePath, changeKind } = file;
 
+  if (isCommentOnlyDiff(file)) {
+    return ChangeCategory.fromString('docs');
+  }
+
   // api: *port.ts or *adapter.ts（最高優先度）
   if (filePath.endsWith('port.ts') || filePath.endsWith('adapter.ts')) {
     return ChangeCategory.fromString('api');
@@ -137,7 +142,7 @@ export class QuickModeJudgmentEngine {
     // 3. API_CONTRACT評価: *port.ts / *adapter.ts の変更
     if (config.isFullModeRequiredFor('apiContractChange')) {
       const apiContractFiles = changedFiles.filter(
-        (f) => f.filePath.endsWith('port.ts') || f.filePath.endsWith('adapter.ts')
+        (f) => (f.filePath.endsWith('port.ts') || f.filePath.endsWith('adapter.ts')) && !isCommentOnlyDiff(f)
       );
 
       if (apiContractFiles.length > 0) {

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

@@ -10,14 +10,31 @@ import { type ChangeKind, isChangeKind } from '../types/change-kind.js';
 export class ChangedFile {
   readonly filePath: string;
   readonly changeKind: ChangeKind;
+  readonly beforeContent!: string | null;
+  readonly afterContent!: string | null;
 
-  private constructor(filePath: string, changeKind: ChangeKind) {
+  private constructor(filePath: string, changeKind: ChangeKind, beforeContent: string | null, afterContent: string | null) {
     this.filePath = filePath;
     this.changeKind = changeKind;
+    Object.defineProperty(this, 'beforeContent', {
+      value: beforeContent,
+      enumerable: false,
+      writable: false,
+    });
+    Object.defineProperty(this, 'afterContent', {
+      value: afterContent,
+      enumerable: false,
+      writable: false,
+    });
   }
 
-  static create(params: { filePath: string; changeKind: string }): ChangedFile {
-    const { filePath, changeKind } = params;
+  static create(params: {
+    filePath: string;
+    changeKind: string;
+    beforeContent?: string | null;
+    afterContent?: string | null;
+  }): ChangedFile {
+    const { filePath, changeKind, beforeContent = null, afterContent = null } = params;
 
     if (!filePath) {
       throw new Error('filePath must not be empty');
@@ -29,7 +46,7 @@ export class ChangedFile {
       throw new Error(`changeKind must be one of 'CREATE', 'MODIFY', 'DELETE'. Got: "${changeKind}"`);
     }
 
-    return new ChangedFile(filePath, changeKind);
+    return new ChangedFile(filePath, changeKind, beforeContent, afterContent);
   }
 
   isUnder(directoryPrefix: string): boolean {
@@ -51,6 +68,11 @@ export class ChangedFile {
   }
 
   equals(other: ChangedFile): boolean {
-    return this.filePath === other.filePath && this.changeKind === other.changeKind;
+    return (
+      this.filePath === other.filePath &&
+      this.changeKind === other.changeKind &&
+      this.beforeContent === other.beforeContent &&
+      this.afterContent === other.afterContent
+    );
   }
 }

package/templates/.claude/scripts/analyze-errors-hook.sh

@@ -15,7 +15,7 @@ CONFIG_FILE="$SCRIPT_DIR/hook-config.json"
 TARGET_DIRS=()
 
 if [[ -f "$CONFIG_FILE" ]] && command -v jq >/dev/null 2>&1; then
-    # bash 3.2 (macOS default) has no mapfile; use portable while-read.
+    # bash 3.2 compatible: use portable while-read.
     while IFS= read -r line; do
         [[ -n "$line" ]] && TARGET_DIRS+=("$line")
     done < <(jq -r '.targetDirs[]' "$CONFIG_FILE" 2>/dev/null)

package/templates/.claude/scripts/format-typescript-hook.sh

@@ -17,7 +17,7 @@ FORMATTER="biome"
 FORMATTER_ARGS=()
 
 if [[ -f "$CONFIG_FILE" ]] && command -v jq &> /dev/null; then
-    # bash 3.2 (macOS default) has no mapfile; use portable while-read.
+    # bash 3.2 compatible: use portable while-read.
     while IFS= read -r line; do
         [[ -n "$line" ]] && TARGET_DIRS+=("$line")
     done < <(jq -r '.targetDirs[]' "$CONFIG_FILE" 2>/dev/null)