phasegate 0.138.0 → 0.139.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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` 経路で検出するようにした。
+  - `docs/folder_management_rules.md` / `AGENTS.md` に、新規 WI 作成時の global unique ルールを明記。
+  - `migrate work-items` の採番が `_cross` と Unit 配下の既存 WI 番号を避けることを回帰テストで固定。
+
 ## [0.138.0] - 2026-05-09
 
 ### Fixed

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/folder_management_rules.md

@@ -77,6 +77,8 @@ scripts/harness/{unit}/(domain|application|infrastructure|presentation)/*.ts
 | `inception/_cross/{WI-XXX}/` | 複数 Unit に影響する cross-cutting WI | `_cross/WI-026/`, `_cross/WI-031/` |
 | `inception/{unit}/{WI-XXX}/` | 単一 Unit が所有する WI | `validator-system/WI-074/` |
 
+`WI-XXX` は `docs/inception/**` 全体で一意でなければなりません。`_cross/WI-031` と `{unit}/WI-031` のように配置先が違っても同じ ID は使えません。`description.md` の frontmatter `id` は parent directory 名と一致させます。
+
 > **廃止された配置**（v0.104.0 で物理削除）:
 > - `docs/inception/issues/{ISSUE-XXX}/`
 > - `docs/inception/{unit}/issues/{ISSUE-XXX}/`
@@ -266,7 +268,8 @@ TESTED        @work-item-id 付きテストが存在し green
 
 `migrate work-items --apply` および新規 WI 起票時の採番:
 
-- 既存 WI 番号は予約（重複しない）
+- 既存 WI 番号は `docs/inception/**/WI-XXX` 全体で予約（`_cross` と Unit 配下をまたいで重複しない）
+- `description.md` の frontmatter `id` は parent directory 名 `WI-XXX` と一致させる
 - 空き番号の **若い順**で sequential allocation
 - legacy ID（`ISSUE-XXX` / `US-XXX` / `H{NN}-{NN}`）が存在する場合、frontmatter の `legacy_id` に保持
 

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.0",
+  "version": "0.139.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/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/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/scripts/harness/traceability-model/application/usecases/validate-design-story-annotations-usecase.ts

@@ -12,6 +12,11 @@ import {
 import type { ProjectRelativePath } from "../../domain/value-objects/project-relative-path.js";
 import type { WorkItemFrontmatter } from "../../domain/value-objects/work-item-frontmatter.js";
 import { WorkItemFrontmatterValidationError } from "../../domain/value-objects/work-item-frontmatter.js";
+import type { WorkItemIdentityPort } from "../../domain/ports/work-item-identity-port.js";
+import {
+  WorkItemIdentityValidationService,
+  type WorkItemIdentityViolation,
+} from "../../domain/services/work-item-identity-validation-service.js";
 import type { MetadataValidationOutput } from "../dto/metadata-validation-output.js";
 
 type DesignStoryAnnotationsValidator = Pick<MetadataValidator, "validateDesignDocument">;
@@ -41,6 +46,20 @@ status: drafted
 ---`,
   });
 
+const toWorkItemIdentityError = (violation: WorkItemIdentityViolation): TraceabilityHarnessError =>
+  Object.freeze({
+    code: "L2-002",
+    severity: "error",
+    message: violation.message,
+    suggestion: "docs/inception/**/WI-XXX/description.md の parent directory 名と frontmatter id を一致させ、WI id を inception 全体で一意にしてください",
+    fix_example: `---
+id: ${violation.workItemId}
+type: issue
+severity: normal
+status: drafted
+---`,
+  });
+
 const mergeValidationResult = (
   additionalErrors: readonly TraceabilityHarnessError[],
   result: MetadataValidationResult,
@@ -92,15 +111,22 @@ export class DesignDocumentReadApplicationError extends Error {
 export interface ValidateDesignStoryAnnotationsUseCaseDeps {
   readonly designDocumentPort: DesignDocumentPort;
   readonly validator: DesignStoryAnnotationsValidator;
+  readonly workItemIdentityPort?: WorkItemIdentityPort;
+  readonly workItemIdentityValidationService?: WorkItemIdentityValidationService;
 }
 
 export class ValidateDesignStoryAnnotationsUseCase {
   private readonly designDocumentPort: DesignDocumentPort;
   private readonly validator: DesignStoryAnnotationsValidator;
+  private readonly workItemIdentityPort?: WorkItemIdentityPort;
+  private readonly workItemIdentityValidationService: WorkItemIdentityValidationService;
 
   constructor(deps: ValidateDesignStoryAnnotationsUseCaseDeps) {
     this.designDocumentPort = deps.designDocumentPort;
     this.validator = deps.validator;
+    this.workItemIdentityPort = deps.workItemIdentityPort;
+    this.workItemIdentityValidationService =
+      deps.workItemIdentityValidationService ?? new WorkItemIdentityValidationService();
   }
 
   async execute(filePaths: readonly ProjectRelativePath[]): Promise<readonly Readonly<MetadataValidationOutput>[]> {
@@ -128,6 +154,11 @@ export class ValidateDesignStoryAnnotationsUseCase {
             }
           }
         }
+        if (this.workItemIdentityPort && isWorkItemDescriptionPath(filePath)) {
+          const entries = await this.workItemIdentityPort.listWorkItemIdentities();
+          const violations = this.workItemIdentityValidationService.validate(entries);
+          workItemFrontmatterErrors.push(...violations.map(toWorkItemIdentityError));
+        }
 
         const flags = await this.designDocumentPort.readFrontmatterFlags(filePath);
         const annotations = await this.designDocumentPort.readStoryAnnotations(filePath);
@@ -146,3 +177,7 @@ export class ValidateDesignStoryAnnotationsUseCase {
     return Object.freeze(results);
   }
 }
+
+function isWorkItemDescriptionPath(filePath: ProjectRelativePath): boolean {
+  return /(?:^|\/)WI-\d+\/description\.md$/.test(filePath.toString());
+}

package/scripts/harness/traceability-model/composition-root.ts

@@ -19,6 +19,7 @@ import { FileSystemInceptionPlanGateway } from "./infrastructure/gateways/file-s
 import { FileSystemMetadataReader } from "./infrastructure/gateways/file-system-metadata-reader.js";
 import { FileSystemWorkItemMigrationApplyGateway } from "./infrastructure/gateways/file-system-work-item-migration-apply-gateway.js";
 import { FileSystemWorkItemMigrationSourceGateway } from "./infrastructure/gateways/file-system-work-item-migration-source-gateway.js";
+import { FileSystemWorkItemIdentityGateway } from "./infrastructure/gateways/file-system-work-item-identity-gateway.js";
 import { MarkdownDesignDocumentGateway } from "./infrastructure/gateways/markdown-design-document-gateway.js";
 import { MarkdownStoryCatalogGateway } from "./infrastructure/gateways/markdown-story-catalog-gateway.js";
 import { MarkdownUnitDefinitionGateway } from "./infrastructure/gateways/markdown-unit-definition-gateway.js";
@@ -61,6 +62,7 @@ export function createTraceabilityModelModule(
   const inceptionPlan = new FileSystemInceptionPlanGateway({ rootDir });
   const workItemMigrationSource = new FileSystemWorkItemMigrationSourceGateway({ rootDir });
   const workItemMigrationApply = new FileSystemWorkItemMigrationApplyGateway({ rootDir });
+  const workItemIdentity = new FileSystemWorkItemIdentityGateway({ rootDir });
 
   // Domain services
   const metadataValidator = new MetadataValidator({
@@ -85,6 +87,7 @@ export function createTraceabilityModelModule(
   const validateDesignStoryAnnotationsUseCase = new ValidateDesignStoryAnnotationsUseCase({
     designDocumentPort: designDocument,
     validator: metadataValidator,
+    workItemIdentityPort: workItemIdentity,
   });
   const validateTestStoryMetadataUseCase = new ValidateTestStoryMetadataUseCase({
     metadataReaderPort: metadataReader,

package/scripts/harness/traceability-model/domain/ports/work-item-identity-port.ts

@@ -0,0 +1,13 @@
+// @unit traceability-model
+// @layer domain
+// @work-item-id WI-106
+
+export interface WorkItemIdentityEntry {
+  readonly filePath: string;
+  readonly directoryId: string;
+  readonly frontmatterId: string;
+}
+
+export interface WorkItemIdentityPort {
+  listWorkItemIdentities(): Promise<readonly WorkItemIdentityEntry[]>;
+}

package/scripts/harness/traceability-model/domain/services/work-item-identity-validation-service.ts

@@ -0,0 +1,46 @@
+// @unit traceability-model
+// @layer domain
+// @work-item-id WI-106
+
+import type { WorkItemIdentityEntry } from "../ports/work-item-identity-port.js";
+
+export interface WorkItemIdentityViolation {
+  readonly code: "duplicate-id" | "directory-id-mismatch";
+  readonly workItemId: string;
+  readonly filePaths: readonly string[];
+  readonly message: string;
+}
+
+export class WorkItemIdentityValidationService {
+  validate(entries: readonly WorkItemIdentityEntry[]): readonly WorkItemIdentityViolation[] {
+    const violations: WorkItemIdentityViolation[] = [];
+    const byId = new Map<string, WorkItemIdentityEntry[]>();
+
+    for (const entry of entries) {
+      if (entry.directoryId !== entry.frontmatterId) {
+        violations.push({
+          code: "directory-id-mismatch",
+          workItemId: entry.frontmatterId,
+          filePaths: Object.freeze([entry.filePath]),
+          message: `WI directory id ${entry.directoryId} does not match frontmatter id ${entry.frontmatterId}: ${entry.filePath}`,
+        });
+      }
+
+      const existing = byId.get(entry.frontmatterId) ?? [];
+      existing.push(entry);
+      byId.set(entry.frontmatterId, existing);
+    }
+
+    for (const [workItemId, sameIdEntries] of byId.entries()) {
+      if (sameIdEntries.length <= 1) continue;
+      violations.push({
+        code: "duplicate-id",
+        workItemId,
+        filePaths: Object.freeze(sameIdEntries.map((entry) => entry.filePath).sort()),
+        message: `WI id ${workItemId} is duplicated: ${sameIdEntries.map((entry) => entry.filePath).sort().join(", ")}`,
+      });
+    }
+
+    return Object.freeze(violations);
+  }
+}

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

@@ -0,0 +1,74 @@
+// @unit traceability-model
+// @layer infrastructure
+// @work-item-id WI-106
+
+import { readdir, readFile } from "node:fs/promises";
+import * as path from "node:path";
+import type {
+  WorkItemIdentityEntry,
+  WorkItemIdentityPort,
+} from "../../domain/ports/work-item-identity-port.js";
+import { parseWorkItemFrontmatter } from "../parsers/work-item-frontmatter-parser.js";
+
+const WI_DIR_PATTERN = /^WI-\d+$/;
+const SKIPPED_DIRS = new Set(["archive", "_shared", "_operation", "share"]);
+
+export interface FileSystemWorkItemIdentityGatewayDeps {
+  readonly rootDir: string;
+  readonly inceptionRoot?: string;
+}
+
+export class FileSystemWorkItemIdentityGateway implements WorkItemIdentityPort {
+  private readonly rootDir: string;
+  private readonly inceptionRoot: string;
+
+  constructor(deps: FileSystemWorkItemIdentityGatewayDeps) {
+    this.rootDir = deps.rootDir;
+    this.inceptionRoot = deps.inceptionRoot ?? "docs/inception";
+  }
+
+  async listWorkItemIdentities(): Promise<readonly WorkItemIdentityEntry[]> {
+    const results: WorkItemIdentityEntry[] = [];
+    await this.collect(this.inceptionRoot, results);
+    return Object.freeze(results.sort((a, b) => a.filePath.localeCompare(b.filePath)));
+  }
+
+  private async collect(relativeDir: string, results: WorkItemIdentityEntry[]): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(path.join(this.rootDir, relativeDir), { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (SKIPPED_DIRS.has(entry.name)) continue;
+
+      const childDir = path.posix.join(relativeDir, entry.name);
+      if (WI_DIR_PATTERN.test(entry.name)) {
+        const descriptionPath = path.posix.join(childDir, "description.md");
+        const frontmatter = await this.readFrontmatterId(descriptionPath);
+        if (frontmatter !== null) {
+          results.push({
+            filePath: descriptionPath,
+            directoryId: entry.name,
+            frontmatterId: frontmatter,
+          });
+        }
+        continue;
+      }
+
+      await this.collect(childDir, results);
+    }
+  }
+
+  private async readFrontmatterId(descriptionPath: string): Promise<string | null> {
+    try {
+      const content = await readFile(path.join(this.rootDir, descriptionPath), "utf8");
+      return parseWorkItemFrontmatter(content)?.id ?? null;
+    } catch {
+      return null;
+    }
+  }
+}

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)