phasegate 0.66.0 → 0.67.0

package/README.ja.md

@@ -196,7 +196,12 @@ npx phasegate ci:generate-template --type consistency-check --render > .github/w
   "quickMode": {
     "allowedCategories": ["bugfix", "docs", "test", "config"],
     "maintainedLayers": ["L1", "L2"],
-    "relaxedGates": ["phase-gate", "2-phase-execution"]
+    "relaxedGates": ["phase-gate", "2-phase-execution"],
+    "fullModeRequiredWhen": {
+      "mixedCategories": true,
+      "newDomainFile": true,
+      "apiContractChange": true
+    }
   },
   "phaseDependencies": {
     "preset": "standard",
@@ -204,10 +209,18 @@ npx phasegate ci:generate-template --type consistency-check --render > .github/w
   },
   "protectedFiles": {
     "exclude": ["package.json"]
+  },
+  "baseline": {
+    "enabled": true,
+    "path": ".phasegate/baseline.json"
   }
 }
 ```
 
+`quickMode.fullModeRequiredWhen` は **「Quick Mode で進めようとした変更を Full Mode に強制エスカレートする条件」** を宣言します（v0.63.0 / ISSUE-006 Story A で導入、v0.64.0 / Story B で pre-tool-use hook に統合）。3 トリガー（`mixedCategories` / `newDomainFile` / `apiContractChange`）はいずれも安全側のデフォルト `true`。プロジェクトが意図的にリスクを受け入れる場合のみ個別に `false` にできます。
+
+`baseline` は **Phase A-2 リトロフィット grandfather** をオン/オフします（v0.65.0 / ISSUE-007 Wave 1 で導入、v0.66.0 / Wave 2 で pre-tool-use hook に統合）。`.phasegate/baseline.json` に登録済みのファイルは、構造的に編集されるまで `phase-gate` 対象から除外されます。既存リポジトリへの導入時に `npx phasegate baseline` でスナップショットを生成してください。
+
 ### project.preset -- レイヤー厳密度
 
 | プリセット | 有効レイヤー | カバレッジ | 用途 |
@@ -343,10 +356,15 @@ Quick Mode は以下の方法で発動します:
 
 `bugfix`, `docs`, `test`, `config` カテゴリの変更では、Phase Gate と 2-Phase Execution を緩和し L1/L2 のみ維持します。
 
-**Quick Mode が拒否される条件**（フルチェックが強制されます）:
-- `domain/` 配下に新規ファイルを追加した場合
-- `*port.ts` や `*adapter.ts`（API 契約）を変更した場合
-- 新機能追加・新ドメインモデル追加に該当する変更
+**Quick Mode が拒否される条件**（`fullModeRequiredWhen` で設定駆動 / フルチェックが強制されます）:
+
+| 条件 | `fullModeRequiredWhen.*` フラグ |
+|---|---|
+| 複数カテゴリが混在する変更（例: `bugfix` + `api`） | `mixedCategories` |
+| `domain/` 配下に新規ファイルを追加 | `newDomainFile` |
+| `*port.ts` / `*adapter.ts`（API 契約）を変更 | `apiContractChange` |
+
+事前に判定したい場合は `npx phasegate check-change-category --paths <csv>` を使います。CI で gate にしたい場合は `--fail-on-full-required` を付与してください。
 
 ### protectedFiles -- AI 書き込み保護
 
@@ -398,6 +416,8 @@ npx phasegate <command> [options]
 | `ci-check` | CI フルチェック (L2-L4) | `--quick` `--dry-run` `--fail-on-reject` |
 | `check-phase-gate` | フェーズゲートチェック | `--level 1\|2\|3` |
 | `validate-metadata <files>` | メタデータ検証 | |
+| `check-change-category` | 変更ファイルを Quick Mode カテゴリに分類し、`quickMode.fullModeRequiredWhen` 評価結果（Full Mode 強制が必要か）を返す（v0.63.0 / ISSUE-006 Story A） | `--paths <csv>` `--format human\|json` `--fail-on-full-required` |
+| `baseline` | `.phasegate/baseline.json` スナップショットを生成（Phase A-2 grandfather）。登録済みファイルは構造的に編集されるまで `phase-gate` 対象から除外される（v0.65.0 / ISSUE-007 Wave 1） | `--dry-run` `--force` `--paths <glob,glob,...>` `--json` |
 
 ### phasegate コマンド
 
@@ -568,7 +588,7 @@ export class ConfigSchema { ... }
 
 | Hook | タイミング | 動作 |
 |---|---|---|
-| **PreToolUse** | Write/Edit/Bash 実行前 | フェーズゲート違反・保護ファイルへの書き込み・Bash 経由の書き込み(`sed -i`, `tee` 等)をブロック |
+| **PreToolUse** | Write/Edit/Bash 実行前 | フェーズゲート違反・保護ファイルへの書き込み・Bash 経由の書き込み(`sed -i`, `tee` 等)をブロック。`quickMode.fullModeRequiredWhen` トリガー時は Quick Mode → Full Mode へエスカレート（v0.64.0）。`.phasegate/baseline.json` 登録済みかつ未編集のファイルは grandfather として `phase-gate` をスキップ（v0.66.0） |
 | **PostToolUse** | Write/Edit 実行後 | Biome AST ルールを自動実行、違反を即時フィードバック |
 | **Stop** | セッション終了前 | L2-L4 全チェックを実行、全グリーンでないと終了を保留 |
 
@@ -787,4 +807,4 @@ phasegate 自体の開発（内部アーキテクチャ、回帰テスト、リ
 
 ---
 
-*Last updated: 2026-04-07 -- v0.33.0*
+*Last updated: 2026-04-22 -- v0.66.0*

package/README.md

@@ -189,7 +189,12 @@ Skills cover the full **AIDLC (AI-Driven Development Life Cycle)**, enforcing ph
   "quickMode": {
     "allowedCategories": ["bugfix", "docs", "test", "config"],
     "maintainedLayers": ["L1", "L2"],
-    "relaxedGates": ["phase-gate", "2-phase-execution"]
+    "relaxedGates": ["phase-gate", "2-phase-execution"],
+    "fullModeRequiredWhen": {
+      "mixedCategories": true,
+      "newDomainFile": true,
+      "apiContractChange": true
+    }
   },
   "phaseDependencies": {
     "preset": "standard",
@@ -197,10 +202,18 @@ Skills cover the full **AIDLC (AI-Driven Development Life Cycle)**, enforcing ph
   },
   "protectedFiles": {
     "exclude": ["tsconfig.json", "package.json"]
+  },
+  "baseline": {
+    "enabled": true,
+    "path": ".phasegate/baseline.json"
   }
 }
 ```
 
+`quickMode.fullModeRequiredWhen` declares which conditions force a Quick Mode change to escalate to the full `/story-implementor` flow. All three triggers default to `true` so retrofits stay safe; flip individual flags to `false` only when a project intentionally accepts the risk.
+
+`baseline` opts in to the **Phase A-2 retrofit grandfather**: pre-existing files captured in `.phasegate/baseline.json` are exempted from `phase-gate` until they are structurally modified. Generate the snapshot with `npx phasegate baseline` before introducing the harness to an existing repository.
+
 ---
 
 ## Configurable Phase Gates
@@ -246,7 +259,7 @@ Phasegate integrates natively with Claude Code via hooks in `.claude/settings.js
 
 | Hook | Trigger | Behavior |
 |---|---|---|
-| `PreToolUse` | `Write`, `Edit`, or `Bash` (write operations detected) | Blocks writes to source files without design docs; protects configured files; detects Bash write operations (`sed -i`, `tee`, `cp`, etc.) |
+| `PreToolUse` | `Write`, `Edit`, or `Bash` (write operations detected) | Blocks writes to source files without design docs; enforces `quickMode.fullModeRequiredWhen` (escalates Quick Mode → Full when triggered); skips files captured in the `.phasegate/baseline.json` snapshot until they are modified; protects configured files; detects Bash write operations (`sed -i`, `tee`, `cp`, etc.) |
 | `PostToolUse` | `Write` or `Edit` | Auto-formats and validates metadata |
 | `Stop` | Session end | Runs full test suite to ensure all tests pass |
 
@@ -299,6 +312,8 @@ npx phasegate <command> [options]
 | `update-skills` | Update skills to latest version |
 | `phasegate:status` | Display overall harness health summary |
 | `phasegate:check-phase --unit <id>` | Check current phase for a Unit |
+| `check-change-category --paths <csv>` | Classify changed files into Quick Mode categories and report whether Full Mode is required (`--format json`, `--fail-on-full-required`) |
+| `baseline` | Create `.phasegate/baseline.json` snapshot for Phase A-2 retrofit grandfather (`--dry-run`, `--force`, `--paths <glob,glob,...>`, `--json`) |
 | `list-errors --layer <L0-L4>` | List error definitions with fix examples |
 | `hook <pre-tool-use\|post-tool-use\|stop>` | Run a Claude Code hook (reads JSON from stdin) |
 | `pre-commit` | Run L2 pre-commit validators on staged files |

package/docs/guide/cli-reference.md

@@ -32,6 +32,66 @@ npx phasegate <command> [options]
 
 ---
 
+## Quick Mode
+
+| Command | Options | Description |
+|---|---|---|
+| `check-change-category` | `--paths <csv>` `--format human\|json` `--fail-on-full-required` | Classify changed file paths into Quick Mode categories (`api` / `domain` / `feature` / `bugfix` / `test` / `config` / `docs`) and report whether `quickMode.fullModeRequiredWhen` forces escalation to Full Mode. |
+
+### `check-change-category` の使い方
+
+ISSUE-006 Story A で導入。Quick Mode で取り扱おうとしている変更が
+`quickMode.fullModeRequiredWhen` のいずれかをトリガーするか事前に確認したいときに使う。
+
+```bash
+# JSON 出力 (CI で消費しやすい)
+npx phasegate check-change-category --paths src/foo.ts,src/bar.ts --format json
+
+# Full Mode が必要なら exit 1 (PR チェック等に使える)
+npx phasegate check-change-category \
+  --paths "$(git diff --name-only origin/main...HEAD | paste -sd, -)" \
+  --fail-on-full-required
+```
+
+`--fail-on-full-required` を指定しない場合、Full Mode が必要と判定されても exit 0 を返す
+（情報提供のみ）。CI で gate にしたいときは必ず付与すること。
+
+---
+
+## Baseline (Retrofit Grandfather)
+
+| Command | Options | Description |
+|---|---|---|
+| `baseline` | `--dry-run` `--force` `--paths <glob,glob,...>` `--json` | Create / refresh `.phasegate/baseline.json` snapshot. Files in the snapshot are exempted from `phase-gate` until they are structurally modified (sha1 mismatch). |
+
+### `baseline` の使い方
+
+ISSUE-007 Wave 1 で導入。既存リポジトリに phasegate を後付けする際、現状のコード資産を
+"Phase A-2 grandfather" として一度だけ凍結する。
+
+```bash
+# 現在のリポジトリ全体をスナップショット
+npx phasegate baseline
+
+# 何が含まれるかだけ確認 (ファイルは書かない)
+npx phasegate baseline --dry-run --json
+
+# 既存スナップショットを上書きして再生成
+npx phasegate baseline --force
+
+# 特定ディレクトリだけ含める
+npx phasegate baseline --paths "scripts/harness/**/*.ts,src/**/*.ts"
+```
+
+スナップショットに含まれるファイルは sha1 ハッシュで照合される。ファイルを構造的に
+編集した瞬間に grandfather が外れ、通常の `phase-gate` 対象に戻る。新規ファイルは
+最初から `phase-gate` の対象。
+
+`baseline.enabled = false` (デフォルトは `true`) を `phasegate.config.json` に書くと
+仕組み全体を無効化できる。スナップショットの保存先は `baseline.path` で変更可能。
+
+---
+
 ## Harness API
 
 Commands exposed as npm scripts (`npm run <command>`).

package/docs/guide/configuration.md

@@ -24,7 +24,12 @@ This file is the **Single Source of Truth** for all quality configuration in a P
   "quickMode": {
     "allowedCategories": ["bugfix", "docs", "test", "config"],
     "maintainedLayers": ["L1", "L2"],
-    "relaxedGates": ["phase-gate", "2-phase-execution"]
+    "relaxedGates": ["phase-gate", "2-phase-execution"],
+    "fullModeRequiredWhen": {
+      "mixedCategories": true,
+      "newDomainFile": true,
+      "apiContractChange": true
+    }
   },
   "phaseDependencies": {
     "preset": "standard",      // "full" | "standard" | "minimal" | "custom" ("default" -> "full")
@@ -53,6 +58,10 @@ This file is the **Single Source of Truth** for all quality configuration in a P
   "reporting": {
     "format": "json",
     "outputDir": "reports"
+  },
+  "baseline": {
+    "enabled": true,
+    "path": ".phasegate/baseline.json"
   }
 }
 ```
@@ -105,11 +114,26 @@ The five layers are:
 
 #### `quickMode`
 
-| Sub-field           | Type       | Default                                 | Description                                                                 |
-|---------------------|------------|-----------------------------------------|-----------------------------------------------------------------------------|
-| `allowedCategories` | `string[]` | `["bugfix", "docs", "test", "config"]`  | Change categories permitted under Quick Mode. Any category outside this list requires the full `story-implementor` workflow. |
-| `maintainedLayers`  | `string[]` | `["L1", "L2"]`                          | Layers that remain fully enforced even in Quick Mode.                       |
-| `relaxedGates`      | `string[]` | `["phase-gate", "2-phase-execution"]`   | Gates that are relaxed (not skipped) when Quick Mode is active.             |
+| Sub-field              | Type       | Default                                 | Description                                                                 |
+|------------------------|------------|-----------------------------------------|-----------------------------------------------------------------------------|
+| `allowedCategories`    | `string[]` | `["bugfix", "docs", "test", "config"]`  | Change categories permitted under Quick Mode. Any category outside this list requires the full `story-implementor` workflow. |
+| `maintainedLayers`     | `string[]` | `["L1", "L2"]`                          | Layers that remain fully enforced even in Quick Mode.                       |
+| `relaxedGates`         | `string[]` | `["phase-gate", "2-phase-execution"]`   | Gates that are relaxed (not skipped) when Quick Mode is active.             |
+| `fullModeRequiredWhen` | `object`   | all flags `true`                        | Conditions that force a Quick Mode change to escalate to the full `/story-implementor` flow. See below. |
+
+##### `fullModeRequiredWhen`
+
+Introduced in ISSUE-006 Story A (v0.63.0) and wired into the pre-tool-use hook by Story B (v0.64.0). Each flag is a hard escalation rule -- when triggered, the change cannot proceed under Quick Mode regardless of the file's category.
+
+| Flag                | Default | Trigger                                                                                       |
+|---------------------|---------|-----------------------------------------------------------------------------------------------|
+| `mixedCategories`   | `true`  | The change set spans more than one Quick Mode category (e.g. a `bugfix` file + an `api` file).|
+| `newDomainFile`     | `true`  | The change creates a new file under any `domain/` directory.                                  |
+| `apiContractChange` | `true`  | The change modifies a Port (`*port.ts`) or Adapter (`*adapter.ts`) file.                      |
+
+**Use `npx phasegate check-change-category --paths <csv>`** to dry-run the classifier against an arbitrary file list (see [CLI Reference](cli-reference.md#check-change-category-の使い方)). Combining `--fail-on-full-required` with a CI job makes "Quick Mode PR that should have been Full" a hard build failure.
+
+Set a flag to `false` only when the project intentionally accepts the risk of merging that category of change without the design ceremony -- e.g. an early-stage prototype where new domain files are expected to churn.
 
 #### `phaseDependencies`
 
@@ -381,6 +405,17 @@ Quick Mode with `relaxedGates: ["phase-gate"]` relaxes `storyReflection` as well
 | `format`    | `string` | `"json"`    | Output format for validation reports.                 |
 | `outputDir` | `string` | `"reports"` | Directory where reports are written.                  |
 
+#### `baseline` (retrofit grandfather)
+
+Introduced in ISSUE-007 Wave 1 (v0.65.0) and wired into the pre-tool-use hook by Wave 2 (v0.66.0). When phasegate is added to an existing repository, the `baseline` block lets you snapshot the current state of the codebase so legacy files do not trip `phase-gate` on first edit. Files in the snapshot are exempted **until they are structurally modified** (sha1 mismatch); new files are subject to `phase-gate` from the start.
+
+| Sub-field | Type      | Default                       | Description                                                                                  |
+|-----------|-----------|-------------------------------|----------------------------------------------------------------------------------------------|
+| `enabled` | `boolean` | `true`                        | Master switch. Set to `false` to disable retrofit grandfather and treat every file as new.   |
+| `path`    | `string`  | `".phasegate/baseline.json"`  | Snapshot location. Override only if `.phasegate/` conflicts with an existing path in the repo.|
+
+Generate or refresh the snapshot with `npx phasegate baseline` (`--dry-run` to inspect, `--force` to overwrite, `--paths <glob,glob,...>` to scope, `--json` for CI-friendly output). See the [Baseline section in CLI Reference](cli-reference.md#baseline-retrofit-grandfather) for details.
+
 ---
 
 ### Quick Mode

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.66.0",
+  "version": "0.67.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

@@ -18,6 +18,10 @@ import type {
   BaselineGrandfatherCheckResult,
   BaselineGrandfatherQueryPort,
 } from '../../domain/ports/baseline-grandfather-query-port.js';
+import type {
+  ErrorGuidance,
+  ErrorGuidanceQueryPort,
+} from '../../domain/ports/error-guidance-query-port.js';
 import { WriteTargetScope } from '../../domain/value-objects/write-target-scope.js';
 import type { HandlePreToolUseInput, HandlePreToolUseOutput } from '../dto/handle-pre-tool-use-dto.js';
 
@@ -28,6 +32,7 @@ export interface HandlePreToolUseUseCasePorts {
   fullModeRequirementQueryPort?: FullModeRequirementQueryPort;
   baselineGrandfatherQueryPort?: BaselineGrandfatherQueryPort;
   grandfatherLogger?: (reason: string, targetFilePaths: readonly string[]) => void;
+  errorGuidanceQueryPort?: ErrorGuidanceQueryPort;
 }
 
 export class HandlePreToolUseInputValidationError extends Error {
@@ -48,6 +53,7 @@ export class HandlePreToolUseUseCase {
   private readonly storyReflectionQueryPort?: StoryReflectionQueryPort;
   private readonly fullModeRequirementQueryPort?: FullModeRequirementQueryPort;
   private readonly baselineGrandfatherQueryPort?: BaselineGrandfatherQueryPort;
+  private readonly errorGuidanceQueryPort?: ErrorGuidanceQueryPort;
   private readonly grandfatherLogger: (
     reason: string,
     targetFilePaths: readonly string[],
@@ -58,6 +64,7 @@ export class HandlePreToolUseUseCase {
     this.storyReflectionQueryPort = ports.storyReflectionQueryPort;
     this.fullModeRequirementQueryPort = ports.fullModeRequirementQueryPort;
     this.baselineGrandfatherQueryPort = ports.baselineGrandfatherQueryPort;
+    this.errorGuidanceQueryPort = ports.errorGuidanceQueryPort;
     this.grandfatherLogger =
       ports.grandfatherLogger ??
       ((reason, paths) =>
@@ -95,7 +102,8 @@ export class HandlePreToolUseUseCase {
           this.grandfatherLogger('phase-gate', input.targetFilePaths);
           // fallthrough: continue to full-mode / story-reflection checks (which may also grandfather)
         } else {
-          return HandlePreToolUseUseCase.buildPhaseGateBlockOutput(blockedFilePath, metadata);
+          const guidance = await this.resolveGuidance('L2-001');
+          return HandlePreToolUseUseCase.buildPhaseGateBlockOutput(blockedFilePath, metadata, guidance);
         }
       } else {
         return {
@@ -116,9 +124,11 @@ export class HandlePreToolUseUseCase {
       } else {
         const fullModeResult = await this.fullModeRequirementQueryPort.check(input.targetFilePaths);
         if (fullModeResult.requiresFullMode) {
+          const guidance = await this.resolveGuidance('L2-001');
           return HandlePreToolUseUseCase.buildFullModeRequiredBlockOutput(
             input.targetFilePaths[0],
             fullModeResult,
+            guidance,
           );
         }
       }
@@ -168,6 +178,17 @@ export class HandlePreToolUseUseCase {
     }
   }
 
+  private async resolveGuidance(errorCode: string): Promise<ErrorGuidance | null> {
+    if (this.errorGuidanceQueryPort === undefined) {
+      return null;
+    }
+    try {
+      return await this.errorGuidanceQueryPort.getGuidance(errorCode);
+    } catch {
+      return null;
+    }
+  }
+
   private static buildFullModeRequiredBlockOutput(
     blockedFilePath: string | undefined,
     result: {
@@ -176,6 +197,7 @@ export class HandlePreToolUseUseCase {
       rejectionReason?: string;
       dominantCategory?: string;
     },
+    guidance: ErrorGuidance | null,
   ): HandlePreToolUseOutput {
     const fp = blockedFilePath ?? '不明なファイル';
     const lines: string[] = [
@@ -190,7 +212,9 @@ export class HandlePreToolUseUseCase {
     if (result.rejectionReason) {
       lines.push(`理由: ${result.rejectionReason}`);
     }
-    lines.push('次のアクション: /story-implementor スキルを使用して設計フェーズから開始してください。');
+    const suggestedSkill = guidance?.suggestedSkill ?? '/story-implementor';
+    lines.push(`次のアクション: ${suggestedSkill} スキルを使用して設計フェーズから開始してください。`);
+    HandlePreToolUseUseCase.appendGuidanceLines(lines, guidance);
 
     return {
       shouldBlock: true,
@@ -199,10 +223,20 @@ export class HandlePreToolUseUseCase {
       error: { message: lines.join('\n') },
       fullModeRejectionRule: result.rejectionRule,
       fullModeDominantCategory: result.dominantCategory,
-      nextAction: '/story-implementor',
+      nextAction: suggestedSkill,
     };
   }
 
+  private static appendGuidanceLines(lines: string[], guidance: ErrorGuidance | null): void {
+    if (guidance === null) return;
+    if (guidance.scaffoldCommand !== null) {
+      lines.push(`  scaffold: ${guidance.scaffoldCommand}`);
+    }
+    if (guidance.templatePath !== null) {
+      lines.push(`  テンプレ: ${guidance.templatePath}`);
+    }
+  }
+
   private resolveStoryReflectionScope(input: HandlePreToolUseInput): WriteTargetScope | null {
     if (!HandlePreToolUseUseCase.WRITE_TOOLS.has(input.toolName)) {
       return null;
@@ -229,6 +263,7 @@ export class HandlePreToolUseUseCase {
   private static buildPhaseGateBlockOutput(
     blockedFilePath: string | undefined,
     metadata: BlockMetadata,
+    guidance: ErrorGuidance | null,
   ): HandlePreToolUseOutput {
     const levelLabel = metadata.scopeLevel
       ? HandlePreToolUseUseCase.LEVEL_LABELS[metadata.scopeLevel] ?? `Level ${metadata.scopeLevel}`
@@ -246,10 +281,12 @@ export class HandlePreToolUseUseCase {
       }
     }
 
-    lines.push('次のアクション: /story-implementor スキルを使用して設計フェーズから開始してください。');
+    const suggestedSkill = guidance?.suggestedSkill ?? '/story-implementor';
+    lines.push(`次のアクション: ${suggestedSkill} スキルを使用して設計フェーズから開始してください。`);
     if (metadata.unitId) {
-      lines.push(`  実行例: /story-implementor --unit ${metadata.unitId}`);
+      lines.push(`  実行例: ${suggestedSkill} --unit ${metadata.unitId}`);
     }
+    HandlePreToolUseUseCase.appendGuidanceLines(lines, guidance);
 
     return {
       shouldBlock: true,
@@ -258,8 +295,8 @@ export class HandlePreToolUseUseCase {
       error: { message: lines.join('\n') },
       phaseGateBlockers: [...blockers],
       nextAction: metadata.unitId
-        ? `/story-implementor --unit ${metadata.unitId}`
-        : '/story-implementor',
+        ? `${suggestedSkill} --unit ${metadata.unitId}`
+        : suggestedSkill,
     };
   }
 

package/scripts/harness/agent-integration/domain/ports/error-guidance-query-port.ts

@@ -0,0 +1,20 @@
+// @unit agent-integration
+// @layer domain
+
+/**
+ * phase-gate 等のエラーに紐づく actionable なガイダンス情報
+ * （harness-error Unit の ErrorDefinition.defaultSuggestedSkill 等から供給される）
+ */
+export interface ErrorGuidance {
+  readonly suggestedSkill: string | null;
+  readonly scaffoldCommand: string | null;
+  readonly templatePath: string | null;
+}
+
+/**
+ * エラーコード → actionable guidance の lookup を行う port
+ * 実装は harness-error Unit の ErrorDefinitionRegistry を参照する
+ */
+export interface ErrorGuidanceQueryPort {
+  getGuidance(errorCode: string): Promise<ErrorGuidance | null>;
+}

package/scripts/harness/agent-integration/infrastructure/adapters/harness-error-guidance-adapter.ts

@@ -0,0 +1,49 @@
+// @unit agent-integration
+// @layer infrastructure
+
+import type {
+  ErrorGuidance,
+  ErrorGuidanceQueryPort,
+} from '../../domain/ports/error-guidance-query-port.js';
+
+/**
+ * harness-error Unit の ErrorDefinitionRegistry を lookup して
+ * actionable guidance を返す adapter
+ *
+ * Wave 2 の CiGovernanceBaselineGrandfatherAdapter と同じ
+ * infrastructure-to-infrastructure クロス Unit パターン
+ */
+export class HarnessErrorGuidanceAdapter implements ErrorGuidanceQueryPort {
+  private readonly rootDir: string;
+
+  constructor(options: { rootDir: string }) {
+    this.rootDir = options.rootDir;
+  }
+
+  async getGuidance(errorCode: string): Promise<ErrorGuidance | null> {
+    try {
+      const [{ createHarnessErrorModule }, { ErrorCode }] = await Promise.all([
+        import('../../../harness-error/composition-root.js'),
+        import('../../../harness-error/domain/value-objects/error-code.js'),
+      ]);
+      const mod = createHarnessErrorModule(this.rootDir);
+      const definition = mod.errorDefinitionRegistry.getDefinition(
+        ErrorCode.create(errorCode),
+      );
+      if (
+        definition.defaultSuggestedSkill === null
+        && definition.defaultScaffoldCommand === null
+        && definition.defaultTemplatePath === null
+      ) {
+        return null;
+      }
+      return {
+        suggestedSkill: definition.defaultSuggestedSkill,
+        scaffoldCommand: definition.defaultScaffoldCommand,
+        templatePath: definition.defaultTemplatePath,
+      };
+    } catch {
+      return null;
+    }
+  }
+}

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

@@ -14,6 +14,7 @@ import { PhaseGateQueryAdapter } from '../infrastructure/adapters/phase-gate-que
 import { FileSystemStoryReflectionQueryAdapter } from '../infrastructure/adapters/file-system-story-reflection-query-adapter.js';
 import { QuickModeFullModeRequirementAdapter } from '../infrastructure/adapters/quick-mode-full-mode-requirement-adapter.js';
 import { CiGovernanceBaselineGrandfatherAdapter } from '../infrastructure/adapters/ci-governance-baseline-grandfather-adapter.js';
+import { HarnessErrorGuidanceAdapter } from '../infrastructure/adapters/harness-error-guidance-adapter.js';
 import { createQuickModeCompositionRoot } from '../../quick-mode/composition-root.js';
 import * as path from 'node:path';
 import * as fs from 'node:fs/promises';
@@ -128,12 +129,16 @@ async function main(): Promise<void> {
       baseDir: path.dirname(configPath),
       configQueryPort,
     });
+    const errorGuidanceQueryPort = new HarnessErrorGuidanceAdapter({
+      rootDir: path.dirname(configPath),
+    });
     const useCase = new HandlePreToolUseUseCase({
       configQueryPort,
       phaseGateQueryPort,
       storyReflectionQueryPort,
       fullModeRequirementQueryPort,
       baselineGrandfatherQueryPort,
+      errorGuidanceQueryPort,
     });
 
     const output = await useCase.execute({ toolName: effectiveToolName, targetFilePaths });

package/scripts/harness/harness-error/application/dto/create-harness-error-input.ts

@@ -12,4 +12,7 @@ export interface CreateHarnessErrorInput {
   readonly adrRef?: string;
   readonly fixExample?: string;
   readonly validatorId: string;
+  readonly suggestedSkill?: string;
+  readonly scaffoldCommand?: string;
+  readonly templatePath?: string;
 }

package/scripts/harness/harness-error/application/dto/harness-error-contract.ts

@@ -11,4 +11,7 @@ export interface HarnessErrorContract {
   readonly suggestion: string;
   readonly adr_ref?: string;
   readonly fix_example?: string;
+  readonly suggested_skill?: string;
+  readonly scaffold_command?: string;
+  readonly template_path?: string;
 }

package/scripts/harness/harness-error/application/mappers/harness-error-contract-mapper.ts

@@ -20,6 +20,15 @@ export class HarnessErrorContractMapper {
       ...(harnessError.fixExample !== null
         ? { fix_example: harnessError.fixExample.toString() }
         : {}),
+      ...(harnessError.suggestedSkill !== null
+        ? { suggested_skill: harnessError.suggestedSkill }
+        : {}),
+      ...(harnessError.scaffoldCommand !== null
+        ? { scaffold_command: harnessError.scaffoldCommand }
+        : {}),
+      ...(harnessError.templatePath !== null
+        ? { template_path: harnessError.templatePath }
+        : {}),
     };
 
     return Object.freeze(contract);

package/scripts/harness/harness-error/application/usecases/create-harness-error-use-case.ts

@@ -34,6 +34,9 @@ export class CreateHarnessErrorUseCase {
       requestedSeverity: input.severity,
       adrRef: input.adrRef,
       fixExample: input.fixExample,
+      suggestedSkill: input.suggestedSkill,
+      scaffoldCommand: input.scaffoldCommand,
+      templatePath: input.templatePath,
     });
 
     return this.contractMapper.toReadonlyContract(harnessError);

package/scripts/harness/harness-error/domain/services/harness-error-factory.ts

@@ -29,6 +29,9 @@ export interface CreateHarnessErrorParams {
   readonly requestedSeverity?: 'error' | 'warning';
   readonly adrRef?: string | null;
   readonly fixExample?: string | null;
+  readonly suggestedSkill?: string | null;
+  readonly scaffoldCommand?: string | null;
+  readonly templatePath?: string | null;
 }
 
 export interface HarnessErrorFactoryDeps {
@@ -119,7 +122,12 @@ export class HarnessErrorFactory {
       }
     }
 
-    // 10. HarnessError 生成と凍結
+    // 10. actionable フィールドの解決（ErrorDefinition の default と input 引数の合成）
+    const resolvedSuggestedSkill = definition.resolveSuggestedSkill(input.suggestedSkill);
+    const resolvedScaffoldCommand = definition.resolveScaffoldCommand(input.scaffoldCommand);
+    const resolvedTemplatePath = definition.resolveTemplatePath(input.templatePath);
+
+    // 11. HarnessError 生成と凍結
     const harnessError = new HarnessError({
       code: errorCode,
       severity: effectiveSeverity,
@@ -127,6 +135,9 @@ export class HarnessErrorFactory {
       suggestion: input.suggestion,
       adrRef: resolvedAdrRef,
       fixExample: resolvedFixExample,
+      suggestedSkill: resolvedSuggestedSkill,
+      scaffoldCommand: resolvedScaffoldCommand,
+      templatePath: resolvedTemplatePath,
     });
 
     return Object.freeze(harnessError);

package/scripts/harness/harness-error/domain/value-objects/error-definition.ts

@@ -31,6 +31,9 @@ export interface ErrorDefinitionProps {
   readonly fixExampleRequired: boolean;
   readonly defaultFixExample: FixExample | null;
   readonly ownerValidatorId: string;
+  readonly defaultSuggestedSkill?: string | null;
+  readonly defaultScaffoldCommand?: string | null;
+  readonly defaultTemplatePath?: string | null;
 }
 
 export class ErrorDefinition {
@@ -43,6 +46,9 @@ export class ErrorDefinition {
   readonly fixExampleRequired: boolean;
   readonly defaultFixExample: FixExample | null;
   readonly ownerValidatorId: string;
+  readonly defaultSuggestedSkill: string | null;
+  readonly defaultScaffoldCommand: string | null;
+  readonly defaultTemplatePath: string | null;
 
   private constructor(props: ErrorDefinitionProps) {
     this.code = props.code;
@@ -54,6 +60,9 @@ export class ErrorDefinition {
     this.fixExampleRequired = props.fixExampleRequired;
     this.defaultFixExample = props.defaultFixExample;
     this.ownerValidatorId = props.ownerValidatorId;
+    this.defaultSuggestedSkill = props.defaultSuggestedSkill ?? null;
+    this.defaultScaffoldCommand = props.defaultScaffoldCommand ?? null;
+    this.defaultTemplatePath = props.defaultTemplatePath ?? null;
     Object.freeze(this);
   }
 
@@ -98,6 +107,27 @@ export class ErrorDefinition {
     return this.defaultFixExample;
   }
 
+  resolveSuggestedSkill(explicit?: string | null): string | null {
+    if (explicit) {
+      return explicit;
+    }
+    return this.defaultSuggestedSkill;
+  }
+
+  resolveScaffoldCommand(explicit?: string | null): string | null {
+    if (explicit) {
+      return explicit;
+    }
+    return this.defaultScaffoldCommand;
+  }
+
+  resolveTemplatePath(explicit?: string | null): string | null {
+    if (explicit) {
+      return explicit;
+    }
+    return this.defaultTemplatePath;
+  }
+
   equals(other: ErrorDefinition): boolean {
     const adrRefEqual =
       this.defaultAdrRef === null && other.defaultAdrRef === null

package/scripts/harness/harness-error/domain/value-objects/harness-error.ts

@@ -17,6 +17,9 @@ export interface HarnessErrorContract {
   readonly suggestion: string;
   readonly adr_ref?: string;
   readonly fix_example?: string;
+  readonly suggested_skill?: string;
+  readonly scaffold_command?: string;
+  readonly template_path?: string;
 }
 
 export interface HarnessErrorProps {
@@ -26,6 +29,9 @@ export interface HarnessErrorProps {
   readonly suggestion: string;
   readonly adrRef: AdrRef | null;
   readonly fixExample: FixExample | null;
+  readonly suggestedSkill?: string | null;
+  readonly scaffoldCommand?: string | null;
+  readonly templatePath?: string | null;
 }
 
 export class HarnessError {
@@ -35,6 +41,9 @@ export class HarnessError {
   readonly suggestion: string;
   readonly adrRef: AdrRef | null;
   readonly fixExample: FixExample | null;
+  readonly suggestedSkill: string | null;
+  readonly scaffoldCommand: string | null;
+  readonly templatePath: string | null;
 
   constructor(props: HarnessErrorProps) {
     this.code = props.code;
@@ -43,6 +52,9 @@ export class HarnessError {
     this.suggestion = props.suggestion;
     this.adrRef = props.adrRef;
     this.fixExample = props.fixExample;
+    this.suggestedSkill = props.suggestedSkill ?? null;
+    this.scaffoldCommand = props.scaffoldCommand ?? null;
+    this.templatePath = props.templatePath ?? null;
   }
 
   equals(other: HarnessError): boolean {
@@ -66,7 +78,10 @@ export class HarnessError {
       this.message === other.message &&
       this.suggestion === other.suggestion &&
       adrRefEqual &&
-      fixExampleEqual
+      fixExampleEqual &&
+      this.suggestedSkill === other.suggestedSkill &&
+      this.scaffoldCommand === other.scaffoldCommand &&
+      this.templatePath === other.templatePath
     );
   }
 
@@ -78,6 +93,18 @@ export class HarnessError {
     return this.fixExample !== null;
   }
 
+  hasSuggestedSkill(): boolean {
+    return this.suggestedSkill !== null;
+  }
+
+  hasScaffoldCommand(): boolean {
+    return this.scaffoldCommand !== null;
+  }
+
+  hasTemplatePath(): boolean {
+    return this.templatePath !== null;
+  }
+
   toContract(): Readonly<HarnessErrorContract> {
     const contract: HarnessErrorContract = {
       code: this.code.toString(),
@@ -88,6 +115,9 @@ export class HarnessError {
       ...(this.fixExample !== null
         ? { fix_example: this.fixExample.toString() }
         : {}),
+      ...(this.suggestedSkill !== null ? { suggested_skill: this.suggestedSkill } : {}),
+      ...(this.scaffoldCommand !== null ? { scaffold_command: this.scaffoldCommand } : {}),
+      ...(this.templatePath !== null ? { template_path: this.templatePath } : {}),
     };
     return Object.freeze(contract);
   }

package/scripts/harness/harness-error/infrastructure/registry/l2-error-definitions.ts

@@ -14,6 +14,9 @@ function createDefinition(input: {
   category: 'phase_gate' | 'architecture' | 'dependency' | 'quality' | 'security' | 'performance' | 'consistency' | 'metadata';
   ownerValidatorId: string;
   defaultFixExample: string;
+  defaultSuggestedSkill?: string;
+  defaultScaffoldCommand?: string;
+  defaultTemplatePath?: string;
 }): ErrorDefinition {
   return ErrorDefinition.create({
     code: ErrorCode.create(input.code),
@@ -25,6 +28,9 @@ function createDefinition(input: {
     fixExampleRequired: true,
     defaultFixExample: FixExample.create(input.defaultFixExample),
     ownerValidatorId: input.ownerValidatorId,
+    defaultSuggestedSkill: input.defaultSuggestedSkill ?? null,
+    defaultScaffoldCommand: input.defaultScaffoldCommand ?? null,
+    defaultTemplatePath: input.defaultTemplatePath ?? null,
   });
 }
 
@@ -36,6 +42,9 @@ export const L2_ERROR_DEFINITIONS = Object.freeze([
     ownerValidatorId: 'phase-gate',
     defaultFixExample:
       "const requiredPlanPath = 'docs/inception/harness-error/it_test_logic_plan.md';",
+    defaultSuggestedSkill: '/story-implementor',
+    defaultScaffoldCommand: 'npx phasegate scaffold-design --unit <unit-id> --phase logical',
+    defaultTemplatePath: 'docs/templates/logical_design.template.md',
   }),
   createDefinition({
     code: 'L2-002',