phasegate 0.132.0 → 0.133.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.133.0] - 2026-05-08
+
+### Added
+
+- **WI-095 — L4-001 drift-detect の design pointers 対応** — 設計見出し直下の `<!-- pointers: ... -->` / `<pointers>` block で実装ファイルpathを明示できるようにし、設計名とcode export名が異なる移行中ケースのfalse positiveを抑制。ADR-018でsyntaxとORセマンティクスを定義。
+
+### Fixed
+
+- **WI-096 — `phasegate:status` が `layers.L?.enabled` user override を表示に反映しない問題を修正** — status表示用のenabledLayersをpreset値と明示overrideから合成し、`strict + L4.enabled:false` / `minimal + L4.enabled:true` の双方に対応。
+
 ## [0.132.0] - 2026-05-08
 
 ### Fixed

package/docs/ADR/ADR-018-drift-detect-pointers.md

@@ -0,0 +1,47 @@
+# ADR-018: drift-detect の design pointers 仕様
+
+## Status
+
+Accepted — 2026-05-08
+
+## Context
+
+L4-001 `drift-detect` は設計文書の `##` / `###` 見出しから抽出した要素名と、TypeScript source の export 名を双方向に比較する。WI-091 で括弧 qualifier の normalize は導入済みだが、次のようなケースでは依然として false positive が起きる。
+
+- 設計名と実装 export 名が移行期間中だけ異なる
+- 設計文書では業務概念名、コードではより具体的な型名を使う
+- 同名・類似名の要素が複数 unit に存在し、ファイル path で対応を示したい
+- 実装ファイル名は安定しているが export 名を変更している
+
+GitHub Issue #4 の follow-up として WI-095 を起票した。
+
+## Decision
+
+設計見出し単位で、対応する実装ファイル path を明示できる `pointers` を導入する。初期実装では以下の2形式を正式に受け付ける。
+
+```markdown
+## UserProfile
+<!-- pointers: scripts/harness/user/domain/user-profile.ts -->
+```
+
+```markdown
+## UserProfile
+<pointers>
+  - scripts/harness/user/domain/user-profile.ts
+  - scripts/harness/user/domain/user-profile-types.ts
+</pointers>
+```
+
+セマンティクスは以下とする。
+
+- pointers がない要素は従来通り、設計要素名と code export 名の完全一致で判定する
+- pointers がある設計要素は、いずれか1つの pointer が code export の定義ファイル path と一致すれば、設計→コード drift とみなさない
+- pointer で対応付けられた code export は、名前が設計要素名と異なっていても code→design drift とみなさない
+- 複数 pointer は OR として扱う
+- path 比較は POSIX separator に正規化し、絶対 path の末尾が pointer と一致する場合も一致とする
+
+## Consequences
+
+`DesignDocumentPort` は後方互換のため既存 `getElements()` を維持し、optional な `getElementPointers()` を追加する。`SourceCodeAnalyzerPort` も optional な `getElementFilePathMap()` を追加する。両 optional port が未実装の場合、`DriftDetectionService` は従来挙動のまま動作する。
+
+YAML fenced metadata は今回採用しない。Markdown本文の構造と混ざりやすく、既存のコードブロック抽出や設計例との衝突リスクが高いため、必要になった時点で別ADRで拡張する。

package/docs/guide/layer-model.md

@@ -150,6 +150,27 @@ L4 validators are designed to run on a weekly schedule and detect slow-moving dr
 
 > **Note (2026-04-25)**: `doc-freshness` and `pointer-validation` capabilities exist as standalone CLI commands `p2:check-freshness` and `p2:validate-pointers` (implemented in the `phase2-extensions` unit), **not as L4 validators yet**. Promoting them to L4-004 / L4-005 is tracked as **WI-033**. Until that lands, run them explicitly via `npx phasegate p2:check-freshness` / `p2:validate-pointers`.
 
+### Drift-detect design pointers
+
+L4-001 normally matches design headings to code exports by name. When a heading intentionally maps to a differently named implementation file, add a pointer directly under the heading:
+
+```markdown
+## UserProfile
+<!-- pointers: scripts/harness/user/domain/user-profile.ts -->
+```
+
+For multiple files:
+
+```markdown
+## UserProfile
+<pointers>
+  - scripts/harness/user/domain/user-profile.ts
+  - scripts/harness/user/domain/user-profile-types.ts
+</pointers>
+```
+
+Pointers are optional and backward compatible. If any listed path matches the file defining a code export, drift-detect treats that design heading and export as corresponding even when their names differ.
+
 **Command:**
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.132.0",
+  "version": "0.133.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/harness-api/infrastructure/adapters/harness-config-query-adapter.ts

@@ -1,4 +1,5 @@
 // @layer infrastructure
+// @unit harness-api
 // harness-config-query-adapter.ts — HarnessConfigQueryAdapter
 
 import * as fs from 'node:fs/promises';
@@ -12,6 +13,7 @@ interface HarnessConfigJson {
     name: string;
     preset: 'minimal' | 'standard' | 'strict';
   };
+  layers?: Partial<Record<LayerId, { enabled?: boolean }>>;
   paths?: {
     designDocs?: string;
     integrationTests?: string;
@@ -46,7 +48,18 @@ export class HarnessConfigQueryAdapter implements ConfigQueryPort {
   async getPresetInfo(): Promise<PresetInfo> {
     const config = await this.readConfig();
     const preset = config.project.preset;
-    const enabledLayers = PRESET_LAYERS[preset] ?? ['L1', 'L2', 'L3'];
+    const presetLayers = PRESET_LAYERS[preset] ?? ['L1', 'L2', 'L3'];
+    const enabledLayerSet = new Set<LayerId>(presetLayers);
+
+    for (const [layerId, layerConfig] of Object.entries(config.layers ?? {}) as [LayerId, { enabled?: boolean }][]) {
+      if (layerConfig.enabled === true) {
+        enabledLayerSet.add(layerId);
+      } else if (layerConfig.enabled === false) {
+        enabledLayerSet.delete(layerId);
+      }
+    }
+
+    const enabledLayers = (['L1', 'L2', 'L3', 'L4'] as const).filter((layerId) => enabledLayerSet.has(layerId));
     return { name: preset, enabledLayers };
   }
 

package/scripts/harness/validator-system/domain/ports/design-document-port.ts

@@ -8,6 +8,7 @@
 export interface DesignDocumentConcept {
   readonly name: string;
   readonly type: 'class' | 'interface' | 'type' | 'value-object' | 'service';
+  readonly pointers?: readonly string[];
 }
 
 export interface StructuredDesignDoc {
@@ -24,4 +25,6 @@ export interface DesignDocumentPort {
   getLayerAnnotations?(targetDocs?: readonly string[]): Promise<Record<string, string>>;
   /** DriftDetectionService用: 要素名一覧取得 */
   getElements?(targetUnits?: readonly string[]): Promise<string[]>;
+  /** DriftDetectionService用: 設計要素から対応する実装ファイルへの明示ポインタ */
+  getElementPointers?(targetUnits?: readonly string[]): Promise<Record<string, readonly string[]>>;
 }

package/scripts/harness/validator-system/domain/ports/source-code-analyzer-port.ts

@@ -11,4 +11,5 @@ export interface SourceAnalysisResult {
 export interface SourceCodeAnalyzerPort {
   analyzeExports(targetUnits?: readonly string[]): Promise<readonly SourceAnalysisResult[]>;
   getElements?(targetUnits?: readonly string[]): Promise<string[]>;
+  getElementFilePathMap?(targetUnits?: readonly string[]): Promise<Record<string, readonly string[]>>;
 }

package/scripts/harness/validator-system/domain/services/l4/drift-detection-service.ts

@@ -9,6 +9,11 @@ import { DriftReport } from '../../value-objects/drift-report.js';
 
 export interface DriftDetectionDesignDocumentPort {
   getElements(targetUnits?: readonly string[]): Promise<string[]>;
+  /**
+   * WI-095: 設計要素 → 実装ファイル path の明示対応。
+   * 実装されていれば element 名完全一致に加えて drift 判定に使う。
+   */
+  getElementPointers?(targetUnits?: readonly string[]): Promise<Record<string, readonly string[]>>;
   /**
    * ISSUE-005 P3-9: element → unit 名のマップ。
    * 実装されていれば DriftReport.unitName の解決に使われる (fallback: 'unknown')。
@@ -18,6 +23,11 @@ export interface DriftDetectionDesignDocumentPort {
 
 export interface DriftDetectionSourceCodeAnalyzerPort {
   getElements(targetUnits?: readonly string[]): Promise<string[]>;
+  /**
+   * WI-095: export element → 定義ファイル path のマップ。
+   * 実装されていれば design pointer と照合する。
+   */
+  getElementFilePathMap?(targetUnits?: readonly string[]): Promise<Record<string, readonly string[]>>;
   /**
    * ISSUE-005 P3-9: element → unit 名のマップ。
    * 実装されていれば DriftReport.unitName の解決に使われる (fallback: 'unknown')。
@@ -42,6 +52,12 @@ export class DriftDetectionService {
   async detect(targetUnits?: readonly string[]): Promise<readonly DriftReport[]> {
     const designElements = await this.designDocumentPort.getElements(targetUnits);
     const codeElements = await this.sourceCodeAnalyzerPort.getElements(targetUnits);
+    const designPointers = this.designDocumentPort.getElementPointers
+      ? await this.designDocumentPort.getElementPointers(targetUnits)
+      : {};
+    const codeFilePathMap = this.sourceCodeAnalyzerPort.getElementFilePathMap
+      ? await this.sourceCodeAnalyzerPort.getElementFilePathMap(targetUnits)
+      : {};
 
     // ISSUE-005 P3-9: element → unit のマップを取得し、DriftReport.unitName の解決に使う
     const designUnitMap = this.designDocumentPort.getElementUnitMap
@@ -62,12 +78,28 @@ export class DriftDetectionService {
 
     const designSet = new Set(designElements);
     const codeSet = new Set(codeElements);
+    const pointerMatchedDesignElements = new Set<string>();
+    const pointerMatchedCodeElements = new Set<string>();
+
+    for (const element of designElements) {
+      const pointers = designPointers[element] ?? [];
+      if (pointers.length === 0) continue;
+      const matchedCodeElements = codeElements.filter((codeElement) =>
+        (codeFilePathMap[codeElement] ?? []).some((filePath) => pointers.some((pointer) => isSameOrNestedPath(filePath, pointer)))
+      );
+      if (matchedCodeElements.length > 0) {
+        pointerMatchedDesignElements.add(element);
+        for (const codeElement of matchedCodeElements) {
+          pointerMatchedCodeElements.add(codeElement);
+        }
+      }
+    }
 
     const reports: DriftReport[] = [];
 
     // 設計に存在するがコードに存在しない
     for (const element of designElements) {
-      if (!codeSet.has(element)) {
+      if (!codeSet.has(element) && !pointerMatchedDesignElements.has(element)) {
         reports.push(
           DriftReport.create({
             direction: 'design→code',
@@ -82,7 +114,7 @@ export class DriftDetectionService {
 
     // コードに存在するが設計に存在しない
     for (const element of codeElements) {
-      if (!designSet.has(element)) {
+      if (!designSet.has(element) && !pointerMatchedCodeElements.has(element)) {
         reports.push(
           DriftReport.create({
             direction: 'code→design',
@@ -100,3 +132,13 @@ export class DriftDetectionService {
     );
   }
 }
+
+function normalizePath(path: string): string {
+  return path.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function isSameOrNestedPath(actualPath: string, pointerPath: string): boolean {
+  const actual = normalizePath(actualPath);
+  const pointer = normalizePath(pointerPath);
+  return actual === pointer || actual.endsWith(`/${pointer}`);
+}

package/scripts/harness/validator-system/infrastructure/adapters/biome-ast-source-code-analyzer-adapter.ts

@@ -61,6 +61,17 @@ export class BiomeAstSourceCodeAnalyzerAdapter implements SourceCodeAnalyzerPort
     }
     return map;
   }
+
+  async getElementFilePathMap(targetUnits?: readonly string[]): Promise<Record<string, readonly string[]>> {
+    const results = await this.analyzeExports(targetUnits);
+    const map: Record<string, string[]> = {};
+    for (const result of results) {
+      for (const entry of result.exports) {
+        map[entry.name] = [...(map[entry.name] ?? []), result.filePath];
+      }
+    }
+    return map;
+  }
 }
 
 type ExportType = SourceAnalysisResult['exports'][number]['type'];

package/scripts/harness/validator-system/infrastructure/adapters/markdown-design-document-adapter.ts

@@ -30,9 +30,39 @@ function isMetaHeading(name: string): boolean {
   return DEFAULT_META_HEADING_PATTERNS.some((p) => p.test(name));
 }
 
-function extractConceptNames(markdown: string): string[] {
+function extractPointerLines(lines: readonly string[], startIndex: number, headingRegex: RegExp): string[] {
+  const pointers: string[] = [];
+  for (let i = startIndex + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (headingRegex.test(line)) break;
+
+    const commentMatch = /<!--\s*pointers?\s*:\s*(.+?)\s*-->/i.exec(line);
+    if (commentMatch) {
+      pointers.push(...commentMatch[1].split(',').map((p) => p.trim()).filter(Boolean));
+      continue;
+    }
+
+    const blockStartMatch = /^<pointers>\s*$/i.exec(line.trim());
+    if (blockStartMatch) {
+      for (let j = i + 1; j < lines.length; j++) {
+        const blockLine = lines[j].trim();
+        if (/^<\/pointers>\s*$/i.test(blockLine)) {
+          i = j;
+          break;
+        }
+        const itemMatch = /^-\s+(.+?)\s*$/.exec(blockLine);
+        if (itemMatch) pointers.push(itemMatch[1].trim());
+      }
+      continue;
+    }
+  }
+
+  return Array.from(new Set(pointers));
+}
+
+function extractConcepts(markdown: string): Array<{ name: string; pointers?: readonly string[] }> {
   const lines = markdown.split(/\r?\n/);
-  const headings: string[] = [];
+  const concepts: Array<{ name: string; pointers?: readonly string[] }> = [];
   const headingRegex = /^(#{2,3})\s+(.+?)\s*$/;
   for (let i = 0; i < lines.length; i++) {
     const m = headingRegex.exec(lines[i]);
@@ -59,10 +89,11 @@ function extractConceptNames(markdown: string): string[] {
       .replace(/[（(][^）)]*[）)]/g, '')
       .trim();
     if (stripped.length > 0) {
-      headings.push(stripped);
+      const pointers = extractPointerLines(lines, i, headingRegex);
+      concepts.push(pointers.length > 0 ? { name: stripped, pointers } : { name: stripped });
     }
   }
-  return headings;
+  return concepts;
 }
 
 export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
@@ -92,7 +123,7 @@ export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
         const doc: StructuredDesignDoc = {
           unitName,
           docPath,
-          concepts: extractConceptNames(markdown).map((name) => ({ name, type: 'class' })),
+          concepts: extractConcepts(markdown).map((concept) => ({ ...concept, type: 'class' })),
           layerDependencies: [],
           adrRefs: Array.from(new Set(markdown.match(ADR_PATTERN) ?? [])),
         };
@@ -115,6 +146,19 @@ export class MarkdownDesignDocumentAdapter implements DesignDocumentPort {
     return docs.flatMap((doc) => doc.concepts.map((concept) => concept.name));
   }
 
+  async getElementPointers(targetUnits?: readonly string[]): Promise<Record<string, readonly string[]>> {
+    const docs = await this.loadDesignDocuments(targetUnits);
+    const map: Record<string, readonly string[]> = {};
+    for (const doc of docs) {
+      for (const concept of doc.concepts) {
+        if (concept.pointers && concept.pointers.length > 0) {
+          map[concept.name] = concept.pointers;
+        }
+      }
+    }
+    return map;
+  }
+
   /**
    * ISSUE-005 P3-9: element 名から unit 名を引けるマップを返す。
    * 同名 element が複数 unit に存在する場合は最初に見つかった unit を採用する。