phasegate 0.72.0 → 0.74.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.74.0] - 2026-04-22
+
+### Fixed
+
+- ISSUE-007 Wave 9 — phase-gate ブロック時に出力される `scaffold:` 行に含まれる `<unit-id>` プレースホルダを、実 unit ID に置換するようにした。従来は L2-001 registry (`l2-error-definitions.ts`) の `defaultScaffoldCommand` が静的文字列 `npx phasegate scaffold-design --unit <unit-id> --phase logical` のまま出力されていたため、ユーザーが手で unit 名に書き換える必要があった。PHASE_GATE の場合は `metadata.unitId`、FULL_MODE_REQUIRED の場合は `targetFilePaths` から `WriteTargetScope.fromPath` で導出した unit ID を使って置換する。
+- IT-AI-GUIDE-UID-001 / IT-AI-GUIDE-UID-002 を追加（PHASE_GATE と FULL_MODE_REQUIRED の両経路で `<unit-id>` が実 unit に置換されることを検証）。
+
+## [0.73.0] - 2026-04-22
+
+### Added
+
+- ISSUE-007 Wave 8 — `phasegate.config.json` の `project.paths` セクションを schema (`harness-config-v2.schema.json`) に追加。`project.paths.source` (array, minItems: 1) で phase-gate の監視ディレクトリを override できるようになった。`project.paths.docs.construction` / `project.paths.docs.inception` も optional で指定可能。
+- IT-CF-PP-001a..d を追加（`project.paths.source` の valid/invalid パターン）。
+
+### Fixed
+
+- ISSUE-007 Wave 8 dogfood で発覚した retrofit blocker を解消 — 従来は adapter (`harness-config-config-query-adapter.ts`) が `config.project?.paths?.source` を読む設計だったにも関わらず schema がそれを additionalProperties として reject していたため、`src/` 配下を使う一般 Node.js プロジェクトでは phase-gate が実質無効化されていた。
+
+### Retrofit ガイド追補
+
+- `docs/guide/retrofit-adoption.md` に「source path の指定」セクションを追加。`src/` 系プロジェクトでは `project.paths.source: ["src"]` の明示が必須である旨を記載。
+
 ## [0.72.0] - 2026-04-22
 
 ### Changed

package/docs/guide/retrofit-adoption.md

@@ -63,6 +63,42 @@ grandfather をオフにしたい場合のみ `phasegate.config.json` に明示:
 `path` も省略時は `.phasegate/baseline.json` が使われる。retrofit 用途では
 この既定値のまま触らないのが最短。
 
+### source path の指定（v0.73.0 以降、`src/` 系 retrofit に必須）
+
+pre-tool-use hook の phase-gate は `project.paths.source` に記載されたディレクトリ
+配下のファイルのみを監視対象にする。既定値は `["scripts/harness"]` で、これは
+phasegate 本体のレイアウトに合わせたもの。**一般的な Node.js プロジェクト
+(`src/` 配下) では必ず上書きすること**。
+
+```json
+{
+  "project": {
+    "name": "your-project",
+    "preset": "standard",
+    "paths": {
+      "source": ["src"]
+    }
+  }
+}
+```
+
+monorepo など複数ディレクトリを持つ場合は配列で列挙:
+
+```json
+{
+  "project": {
+    "paths": {
+      "source": ["apps/web/src", "apps/api/src", "packages/shared/src"]
+    }
+  }
+}
+```
+
+この設定を忘れると、phase-gate は `scripts/harness/` 配下しか見ないため、
+retrofit 対象の新規コード作成が block されず、結果として **phasegate が
+無効化された運用** になってしまう（ISSUE-007 Wave 8 で schema 上 overridable
+になるまで、この設定は config validator で拒否されていた）。
+
 ---
 
 ## Step 2: 既存コードを baseline に登録

package/package.json

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

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

@@ -103,7 +103,14 @@ export class HandlePreToolUseUseCase {
           // fallthrough: continue to full-mode / story-reflection checks (which may also grandfather)
         } else {
           const guidance = await this.resolveGuidance('L2-001');
-          return HandlePreToolUseUseCase.buildPhaseGateBlockOutput(blockedFilePath, metadata, guidance);
+          const unitIdForGuidance =
+            metadata?.unitId ?? this.deriveUnitIdFromPaths(input.targetFilePaths);
+          return HandlePreToolUseUseCase.buildPhaseGateBlockOutput(
+            blockedFilePath,
+            metadata,
+            guidance,
+            unitIdForGuidance,
+          );
         }
       } else {
         return {
@@ -125,10 +132,12 @@ export class HandlePreToolUseUseCase {
         const fullModeResult = await this.fullModeRequirementQueryPort.check(input.targetFilePaths);
         if (fullModeResult.requiresFullMode) {
           const guidance = await this.resolveGuidance('L2-001');
+          const unitIdForGuidance = this.deriveUnitIdFromPaths(input.targetFilePaths);
           return HandlePreToolUseUseCase.buildFullModeRequiredBlockOutput(
             input.targetFilePaths[0],
             fullModeResult,
             guidance,
+            unitIdForGuidance,
           );
         }
       }
@@ -198,6 +207,7 @@ export class HandlePreToolUseUseCase {
       dominantCategory?: string;
     },
     guidance: ErrorGuidance | null,
+    unitId: string | undefined,
   ): HandlePreToolUseOutput {
     const fp = blockedFilePath ?? '不明なファイル';
     const lines: string[] = [
@@ -214,7 +224,7 @@ export class HandlePreToolUseUseCase {
     }
     const suggestedSkill = guidance?.suggestedSkill ?? '/story-implementor';
     lines.push(`次のアクション: ${suggestedSkill} スキルを使用して設計フェーズから開始してください。`);
-    HandlePreToolUseUseCase.appendGuidanceLines(lines, guidance);
+    HandlePreToolUseUseCase.appendGuidanceLines(lines, guidance, unitId);
 
     return {
       shouldBlock: true,
@@ -227,16 +237,34 @@ export class HandlePreToolUseUseCase {
     };
   }
 
-  private static appendGuidanceLines(lines: string[], guidance: ErrorGuidance | null): void {
+  private static appendGuidanceLines(
+    lines: string[],
+    guidance: ErrorGuidance | null,
+    unitId?: string,
+  ): void {
     if (guidance === null) return;
     if (guidance.scaffoldCommand !== null) {
-      lines.push(`  scaffold: ${guidance.scaffoldCommand}`);
+      const command = unitId !== undefined && unitId !== ''
+        ? guidance.scaffoldCommand.replaceAll('<unit-id>', unitId)
+        : guidance.scaffoldCommand;
+      lines.push(`  scaffold: ${command}`);
     }
     if (guidance.templatePath !== null) {
       lines.push(`  テンプレ: ${guidance.templatePath}`);
     }
   }
 
+  private deriveUnitIdFromPaths(targetFilePaths: readonly string[]): string | undefined {
+    const projectPaths = this.configQueryPort.getProjectPaths();
+    for (const targetFilePath of targetFilePaths) {
+      const scope = WriteTargetScope.fromPath(targetFilePath, projectPaths);
+      if (scope?.unitId !== undefined) {
+        return scope.unitId;
+      }
+    }
+    return undefined;
+  }
+
   private resolveStoryReflectionScope(input: HandlePreToolUseInput): WriteTargetScope | null {
     if (!HandlePreToolUseUseCase.WRITE_TOOLS.has(input.toolName)) {
       return null;
@@ -264,6 +292,7 @@ export class HandlePreToolUseUseCase {
     blockedFilePath: string | undefined,
     metadata: BlockMetadata,
     guidance: ErrorGuidance | null,
+    unitId: string | undefined,
   ): HandlePreToolUseOutput {
     const levelLabel = metadata.scopeLevel
       ? HandlePreToolUseUseCase.LEVEL_LABELS[metadata.scopeLevel] ?? `Level ${metadata.scopeLevel}`
@@ -286,7 +315,7 @@ export class HandlePreToolUseUseCase {
     if (metadata.unitId) {
       lines.push(`  実行例: ${suggestedSkill} --unit ${metadata.unitId}`);
     }
-    HandlePreToolUseUseCase.appendGuidanceLines(lines, guidance);
+    HandlePreToolUseUseCase.appendGuidanceLines(lines, guidance, unitId);
 
     return {
       shouldBlock: true,

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

@@ -32,6 +32,35 @@
             "standard",
             "strict"
           ]
+        },
+        "paths": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "source": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              },
+              "minItems": 1,
+              "uniqueItems": true
+            },
+            "docs": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "construction": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "inception": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            }
+          }
         }
       }
     },