phasegate 0.315.0 → 0.335.0

package/docs/ADR/039-hook-observable-state-as-authorization-unit.md

@@ -0,0 +1,74 @@
+---
+adr_id: "039"
+title: "hook の authorization 単位は観測可能な state とし、skill 名を伝播しない"
+status: Accepted
+date: 2026-08-06
+---
+
+# hook の authorization 単位は観測可能な state とし、skill 名を伝播しない
+
+<!-- @work-item-id WI-375 -->
+<!-- @work-item-id WI-376 -->
+
+## Context
+
+pre-tool-use hook には「呼び出し元 skill 名」を受け取る口が 2 つ実装されていた。
+
+- hook input JSON の `caller_skill` フィールド（`scripts/harness/agent-integration/presentation/pre-tool-use-hook.ts` の `PreToolUseHookInput`）
+- 環境変数 `PHASEGATE_CALLER_SKILL`（同ファイルの `input.caller_skill ?? process.env.PHASEGATE_CALLER_SKILL`）
+
+WI-202 はこれを「block guidance の出し分けにのみ使う optional context」として設計した。しかし **値を供給する producer はどこにも存在しない**。
+
+1. **Claude Code の PreToolUse payload に skill 情報が無い。** hook に渡る JSON は `session_id` / `transcript_path` / `cwd` / `hook_event_name` / `tool_name` / `tool_input` / `permission_mode` であり、実行中の skill を示すフィールドは規定されていない。`caller_skill` は phasegate が独自に期待しているだけの未定義キーである。
+2. **配布物の `.claude/settings.json` にも `.codex/hooks.json` にも `PHASEGATE_CALLER_SKILL` を設定する env 宣言が無い。** skill 側（`skills/*/SKILL.md`）にも export する手順は書かれていない。
+3. 結果として `callerSkill` は常に `undefined` で hook に届き、`callerSkill === "quick-implementor"` の分岐は **到達不能なデッドパス**だった。それでも `HandlePreToolUseUseCase` を直接 new して `callerSkill: "quick-implementor"` を渡す統合テストは緑になっており、「実運用では一度も通らない経路が、テスト上は被覆されている」という**偽の被覆**を生んでいた（GitHub #27 Defect C / #44 課題 1）。
+
+WI-354 で guidance 分岐の一次条件を `dominantCategory`（Quick Mode の分類結果）に変更したため実害は解消済みだが、「カテゴリ未確定時のみ `callerSkill` を見る」フォールバックと受け口自体は残っていた。
+
+さらに本質的な問題として、**skill 名は仮に producer を作っても認証されない自己申告値である**。hook を呼ぶのはエージェント自身であり、`caller_skill: "quick-implementor"` を名乗ることは誰にでもできる。ADR-030（injection threat model）の trust root の考え方に照らせば、エージェントが自由に制御できる文字列は防御判定の入力にできない。GitHub #26 で「skill 名で full mode を許可する」案を退け、`phasegate config:plan --apply` のような **managed command 経路**（phasegate 自身が実行し、その痕跡をファイルとして残す経路）に倒した結論と同根である。
+
+## Decision
+
+### 1. authorization / guidance の入力は「hook が自ら観測・検証できる state」に限る
+
+pre-tool-use hook の判定と案内は、以下の観測可能な state のみを入力とする。
+
+| state | 実体 | 観測方法 |
+|-------|------|---------|
+| 書き込み対象パスと変更カテゴリ | `tool_input` から抽出した対象パス、Quick Mode の `dominantCategory` | hook 自身が分類（`quick-mode` unit） |
+| Full Mode session marker | `phasegate session begin --mode full --unit … --work-item …` が作るセッションファイル（WI / unit / 期限） | `FileSystemFullModeSessionQueryAdapter` がファイルを読む |
+| 設計文書の存在 | `docs/product/construction/{unit}/logical_design.md` / `domain_model.md` | `PhaseGateQueryAdapter.checkDesignDocsExist` |
+| WI の承認・reflection 状態 | inception 配下の WI 文書、story reflection | 各 query adapter がファイルを読む |
+| 解決済み config | `phasegate.config.json` + 防御プリセット解決結果 | config-foundation 経由 |
+| baseline / attestation | `.phasegate/baseline.json`、attestation マニフェスト | ci-governance / attestation unit |
+
+これらはすべて「phasegate 自身の managed command が書いた痕跡」または「リポジトリの実ファイル」であり、hook 実行時点で独立に再検証できる。
+
+### 2. エージェントの自己申告 identity は受け取らない
+
+skill 名・エージェント種別のような自己申告値は、**authorization にも guidance 分岐にも使わない**。よって受け口を削除する。
+
+- `PreToolUseHookInput.caller_skill` フィールドを削除する
+- 環境変数 `PHASEGATE_CALLER_SKILL` の参照を削除する
+- `HandlePreToolUseInput.callerSkill` を削除する
+- `shouldGuideQuickModeRelax` の `callerSkill === "quick-implementor"` フォールバックを削除する（判定は `dominantCategory` のみ）
+- `callerSkill` を注入するだけで成立していた統合テストを削除し、代わりに **category ベースの分岐が WI-354 の挙動のまま不変であること**を回帰テストで固定する
+
+「使われていない口を念のため残す」ことは、偽の被覆を生み、将来「値さえ入れれば許可が広がる」という誤った拡張余地を残すため採らない。
+
+### 3. skill context が必要になった場合の唯一の入口は managed command
+
+将来「どの skill が書いているか」に応じて挙動を変える必要が生じた場合も、hook input に新しい自己申告フィールドを足すことはしない。skill 側に `phasegate session begin` 等の **managed command を実行させ、その結果として生まれた検証可能な state**（session marker のフィールド）を hook が読む方式のみを採る。この経路では phasegate が引数を検証し、期限・unit・WI を自ら記録するため、値の出所が hook から追跡できる。
+
+## Consequences
+
+- pre-tool-use hook の入力契約から `caller_skill` が消える。未定義キーを送っていた呼び出し元があっても、hook は追加キーを無視するため互換性は壊れない（そもそも producer が存在しない）。
+- Full Mode ブロック時の復旧案内は `dominantCategory` のみから決まる。`bugfix` / `docs` / `test` / `config` は quick-mode-relax 案内、`feature` / `domain` / `api` および**カテゴリ未確定**は `/story-implementor` 案内という WI-354 の挙動が唯一の仕様となる（カテゴリ未確定時に skill 名で分岐が変わる可能性が消える）。
+- 「テストは緑だが実運用では到達しない」経路が 1 件減る。今後 hook の分岐を追加する際は、入力が上表の observable state に由来するかを ADR の基準として確認する。
+- 経緯: WI-202（受け口の追加）→ WI-206（skill 名を許可条件にしない方針の調査）→ #26（managed command 経路への結論）→ WI-354（guidance の category ベース化）→ 本 ADR（受け口の削除と原則の明文化）。
+
+## Alternatives
+
+1. **producer を実装する（`.claude/settings.json` の env に `PHASEGATE_CALLER_SKILL` を埋める / skill 側で export させる）。** 値はエージェントが自由に設定できる自己申告であり、authorization の入力としては防御にならない。guidance 専用に限定しても、配布物の env 設定はユーザーの settings 編集に依存し、欠落時に静かに分岐が消えるため、category ベース判定より劣る。
+2. **現状維持（受け口を残したまま到達不能分岐を放置）。** デッドパスと偽の被覆が残り、`callerSkill` を「渡せば許可が変わるフック」と誤解した拡張を招く。
+3. **Claude Code 側の payload 拡張を待つ。** phasegate は AI 非依存（ADR-006）を掲げており、特定エージェントの payload 拡張に防御設計を依存させない。

package/docs/ADR/040-quick-mode-config-via-preset-resolution.md

@@ -0,0 +1,66 @@
+---
+adr_id: "040"
+title: "Quick Mode の実効設定を防御プリセット解決経由で決定する"
+status: Accepted
+date: 2026-08-06
+---
+
+# Quick Mode の実効設定を防御プリセット解決経由で決定する
+
+<!-- @work-item-id WI-375 -->
+<!-- @work-item-id WI-377 -->
+<!-- @work-item-id WI-378 -->
+
+## Context
+
+ADR-007 は `phasegate.config.json` を品質設定の Single Source of Truth と定め、防御プリセット（`minimal` / `standard` / `strict`）の解決は config-foundation の `PresetResolutionService` + `PresetDefinitionStore` が担う。ところが Quick Mode の実効経路である `HarnessConfigQuickModeConfigAdapter`（`scripts/harness/quick-mode/infrastructure/adapters/harness-config-quick-mode-config-adapter.ts`）は、**`phasegate.config.json` を `fs.readFile` + `JSON.parse` で直接読み、preset 解決を経由していなかった**。
+
+その結果:
+
+- `scripts/harness/config-foundation/infrastructure/presets/*.json` の `quickMode` セクションは**どこからも読まれないデッド宣言**だった。
+- 実効既定値は adapter 内のハードコード定数 `DEFAULT_QUICK_MODE_CONFIG` にあり、宣言（presets）と実効値（adapter）が二重管理されていた。
+- WI-353 で `allowedCategories` の乖離（presets が `["bugfix"]`、実効値が 4 カテゴリ）を是正し契約テストで再発を検知できるようにしたが、`maintainedLayers` / `relaxedGates` は依然乖離していた（presets: `["L1","L2"]` / `[]`、実効値かつ `docs/guide/configuration.md` の記載: `["L1","L2-002","L2-003","L2-014","L3-001"]` / `["L2-001","L3-002","L3-003","L3-004","L4"]`）。
+- 「防御プリセットごとに Quick Mode の強度を変える」（例: `strict` では `allowedCategories` を絞る）という設計は、経路が繋がっていないため実現不能だった。
+
+GitHub #44 課題 2。**既存プロジェクトの実効挙動を変えない移行**が絶対条件である（#27 の再発防止）。
+
+## Decision
+
+### 1. Quick Mode 設定は preset 解決結果（resolved config）から決定する
+
+`HarnessConfigQuickModeConfigAdapter` は `PresetDefinitionStore` + `PresetResolutionService` を使い、`project.preset` に対応する preset 定義と `phasegate.config.json` の `quickMode` を config-foundation と同一の merge 規則（`deepMerge`: 配列はキー単位で全置換、未宣言キーは preset 値を継承）で解決した結果を使う。
+
+これにより presets の `quickMode` 宣言が実際に読まれ、防御プリセットごとに Quick Mode 強度を変える設計が有効化される。
+
+### 2. 移行時は挙動不変を絶対条件とし、presets の宣言値を実効既定値に揃える
+
+経路の載せ替えだけを行うと、`quickMode` を書いていない既存プロジェクトの `maintainedLayers` / `relaxedGates` が preset の宣言値（`["L1","L2"]` / `[]`）に変わってしまう。これは「Quick Mode で L2-001 phase-gate が維持され、L3-001 が維持されなくなる」という実挙動の変化であり、許容しない。
+
+したがって **3 プリセットの `quickMode` 宣言を実効既定値（= `docs/guide/configuration.md` が既定として記載している値）に揃える**。WI-353 が `allowedCategories` に対して行った是正を、`maintainedLayers` / `relaxedGates` にも適用する形になる。逆方向（実効値を preset 宣言に合わせる）は既存利用者への破壊的変更であり採らない。
+
+防御プリセットごとの Quick Mode 強度差（`strict` で絞る等）は**本 ADR では導入しない**。経路を繋ぐ変更と挙動を変える変更を同一コミットに混ぜないためである。今後差をつける場合は presets の該当ファイルのみを変更すれば実効値に反映される。
+
+### 3. 解決不能時は従来どおりの既定値に fail-open する
+
+`project.preset` が未知・未宣言、または preset 解決が例外を投げる config（他セクションが壊れている等）では、従来と同じく adapter 内の既定値 + raw `quickMode` の per-key フォールバックで動作する。ADR-038 §3-1 の「hook は config がどんな状態でも完走する」原則を維持し、preset 解決の導入によって**新たな遮断経路を作らない**。
+
+`HarnessConfigNotFoundError`（ENOENT）と `HarnessConfigParseError`（JSON 不正）は adapter の公開契約として維持する。
+
+### 4. WI-353 の契約テストは「宣言が実際に読まれること」の検証に昇格させる
+
+WI-353 のテストは「preset 宣言値 == adapter のハードコード既定値」という**二重管理の整合**を検査していた。経路が繋がった後は、`quickMode` を持たない config に対する adapter の実効値が preset 宣言値そのものであることを 3 プリセット分検証する形に置き換える。これによりデッド宣言の解消自体が回帰テストで固定される。
+
+あわせて「防御プリセット × `quickMode` キー有無 × 明示 override 有無」のマトリクス回帰テストで挙動不変を固定する。
+
+## Consequences
+
+- presets の `quickMode` が実効値の所在（single source）になり、adapter 内の既定値は preset 解決不能時の fail-open 用フォールバックという位置づけに縮小する。
+- `phasegate` が出力する解決済み config の `quickMode` と、Quick Mode 判定が実際に使う値が一致する（従来は前者だけが preset 由来で、後者と食い違っていた）。
+- 挙動不変の担保はテストで行う。preset 宣言を変更すると Quick Mode の実挙動が変わるため、presets の `quickMode` 変更は破壊的変更として扱う。
+- 経緯: WI-353（`allowedCategories` の宣言値是正・契約テスト）→ 本 ADR / WI-377（経路の載せ替えと残り 2 キーの是正）→ WI-378（契約テストの昇格）。
+
+## Alternatives
+
+1. **adapter の raw 読みを維持し、presets の `quickMode` セクションを削除する。** デッド宣言は消えるが、防御プリセットごとに Quick Mode 強度を変える設計余地を永久に失い、解決済み config から `quickMode` が消えて ADR-007 の Single Source of Truth と矛盾する。
+2. **経路を載せ替え、実効値を preset 宣言（`["L1","L2"]` / `[]`）に合わせる。** 既存プロジェクトの Quick Mode 緩和範囲が無告知で変わる破壊的変更であり、#27 と同種の事故を再発させる。
+3. **`LoadResolvedConfigUseCase` をそのまま呼ぶ（AJV schema 検証込みの完全経路）。** schema 違反 config で Quick Mode 判定が新たに例外を投げるようになり、ADR-038 の fail-open 表を変更してしまう。本 ADR は domain service（`PresetResolutionService`）と preset 定義のみを利用し、検証の厳格度は変えない。

package/docs/guide/cli-reference.md

@@ -127,7 +127,7 @@ npx phasegate baseline --paths "scripts/harness/**/*.ts,src/**/*.ts"
 
 | Command | Options | Description |
 |---|---|---|
-| `scaffold-design` | `--unit <id>` `--phase <logical\|domain\|uiux\|unit-test\|it-test>` `--force` `--json` | `templates/*.template.md` を読み取り `{{unit}}` を `--unit` 値で置換して `docs/product/construction/{unit}/*.md` を生成する。既存ファイルは `--force` なしでは保護（exit 2）。|
+| `scaffold-design` | `--unit <id>` `--phase <logical\|domain\|uiux\|unit-test\|it-test>` `--force` `--json` | `templates/*.template.md` を読み取り `{{unit}}` を `--unit` 値で置換して `{paths.designDocs}/{unit}/*.md` を生成する。既存ファイルは `--force` なしでは保護（exit 2）。|
 
 ### `scaffold-design` の使い方
 
@@ -146,21 +146,103 @@ npx phasegate scaffold-design --unit harness-api --phase logical --force
 npx phasegate scaffold-design --unit harness-api --phase logical --json
 ```
 
-生成先と対応テンプレ:
+生成先と対応テンプレ（生成先の `docs/product/construction` 部分は
+`phasegate.config.json` の `paths.designDocs` に追従する。WI-369 以前は
+ハードコードされており、`paths.designDocs` を移設した PJ では scaffold 先と
+フェーズゲートの検査先がズレていた）:
 
 | `--phase` | 生成先 | テンプレ |
 |---|---|---|
-| `logical` | `docs/product/construction/{unit}/logical_design.md` | `templates/logical_design.template.md` |
-| `domain` | `docs/product/construction/{unit}/domain_model.md` | `templates/domain_model.template.md` |
-| `uiux` | `docs/product/construction/{unit}/uiux_design.md` | `templates/uiux_design.template.md` |
-| `unit-test` | `docs/product/construction/{unit}/unit_test_design.md` | `templates/unit_test_design.template.md` |
-| `it-test` | `docs/product/construction/{unit}/it_test_design.md` | `templates/it_test_design.template.md` |
+| `logical` | `{paths.designDocs}/{unit}/logical_design.md` | `templates/logical_design.template.md` |
+| `domain` | `{paths.designDocs}/{unit}/domain_model.md` | `templates/domain_model.template.md` |
+| `uiux` | `{paths.designDocs}/{unit}/uiux_design.md` | `templates/uiux_design.template.md` |
+| `unit-test` | `{paths.designDocs}/{unit}/unit_test_design.md` | `templates/unit_test_design.template.md` |
+| `it-test` | `{paths.designDocs}/{unit}/it_test_design.md` | `templates/it_test_design.template.md` |
 
 exit code は `0` = 生成成功 / 上書き成功、`2` = 既存ファイルあり（`--force` 無）
 または引数不正。
 
 ---
 
+## Scaffold Inception (Phase Gate Level-1 Templates)
+
+| Command | Options | Description |
+|---|---|---|
+| `scaffold-inception` | `--kind <doc-kind>` `--dry-run`（既定）/ `--apply` `--force` `--json` | L2 の Level-1 フェーズゲートが要求する inception plan 文書と `product_overview.md` の雛形を生成する。既存ファイルは `--force` なしでは保護（exit 2）。|
+
+WI-368（GitHub issue #42）で導入。`scaffold-design` は `--unit` を必須とする
+construction 文書専用で、unit 軸を持たない `_shared/*_plan.md` や product 直下の
+文書を表現できないため、別コマンドとして分離している。
+
+```bash
+# 何がどこに生成されるかを確認（既定は dry-run）
+npx phasegate scaffold-inception --kind product-overview-plan
+
+# 実際に書き込む
+npx phasegate scaffold-inception --kind product-overview-plan --apply
+npx phasegate scaffold-inception --kind product-overview --apply
+
+# 既存ファイルを意図的に上書き
+npx phasegate scaffold-inception --kind product-overview-plan --apply --force
+```
+
+生成先と対応テンプレ:
+
+| `--kind` | 生成先 | テンプレ |
+|---|---|---|
+| `product-overview-plan` | `{paths.inceptionDocs}/_shared/product_overview_plan.md` | `templates/product_overview_plan.template.md` |
+| `product-overview` | `{paths.designDocs}/../product_overview.md` | `templates/product_overview.template.md` |
+| `story-writer-plan` | `{paths.inceptionDocs}/_shared/story_writer_plan.md` | `templates/story_writer_plan.template.md` |
+| `story-mapping-plan` | `{paths.inceptionDocs}/_shared/story_mapping_plan.md` | `templates/story_mapping_plan.template.md` |
+| `unit-design-plan` | `{paths.inceptionDocs}/_shared/unit_design_plan.md` | `templates/unit_design_plan.template.md` |
+
+### テンプレート = ゲート合格保証
+
+plan テンプレートは QA セクション見出しを必ず含むため、`--apply` の生成物は
+**無編集のまま** `planningMode: "interactive"`（既定）の Level-1 ゲートを通る。
+この性質はラウンドトリップテストで機械的に検証されている。
+
+`planningMode: "embedded-qa"` では `[Question]` と `[Answer]` の個数一致に加え
+`[Answer]` に本文があることが要求されるため、生成直後の雛形は**通らない**。
+これは意図した挙動であり、テンプレートが人間の承認証跡を偽造しないための境界。
+
+### スコープ外の doc-kind
+
+`user_stories.md` / `user_story_mapping.md` / `units/{unit}_unit.md` /
+`units/integration_contract.md` と、unit スコープの plan 文書
+（`{unit}/domain_model_plan.md` 等、Level-2 ゲート）は未収録。段階投入とする。
+
+---
+
+## Templates (Bundled Template Access)
+
+| Command | Options | Description |
+|---|---|---|
+| `templates list` | `--json` | 同梱テンプレート名を一覧表示する。|
+| `templates show <name>` | — | テンプレート本文を stdout に出力する。|
+
+WI-367（GitHub issue #42）で導入。consumer プロジェクトでは phasegate は
+`node_modules/phasegate/templates/` に入り、エージェントの sandbox が
+`node_modules` の Read を deny していると **テンプレート実体に到達できない**。
+`skills list` / `skills info` と同型の stdout 経路でこれを解消する。
+
+```bash
+npx phasegate templates list
+npx phasegate templates show product_overview_plan
+
+# 生成物としてそのまま保存できる（本文以外を混ぜない）
+npx phasegate templates show logical_design > docs/product/construction/foo/logical_design.md
+```
+
+`<name>` は同梱テンプレートの catalog（`templates/` の readdir 結果）と
+**完全一致照合**する。ユーザー入力文字列がパス構成要素になる経路を持たないため、
+`../../package.json` のようなパスは exit 2 で拒否され内容も出力されない。
+
+exit code は `0` = 成功、`2` = name 未指定 / 不正な name / 未知の name /
+未知のサブコマンド。
+
+---
+
 ## Work Item Migration
 
 `docs/inception/` 配下の work item directory を **統一 `WI-XXX` レイアウト**へ移行する CLI。

package/docs/guide/configuration.md

@@ -41,7 +41,8 @@ The plan identifies target fields, managed artifacts, commands, validation, risk
       "mixedCategories": true,
       "newDomainFile": true,
       "apiContractChange": true
-    }
+    },
+    "categoryOverrides": {}    // Optional. e.g. { "docs": ["results/**", "notes/**"] }
   },
   "phaseDependencies": {
     "preset": "standard",      // "full" | "standard" | "minimal" | "custom" ("default" -> "full")
@@ -198,10 +199,13 @@ The five layers are:
 
 | 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. |
+| `allowedCategories`    | `string[]` | `["bugfix", "docs", "test", "config"]`  | Change categories permitted under Quick Mode. Any category outside this list requires the full `story-implementor` workflow. **Enum** — only `bugfix`, `docs`, `test`, `config`, `feature`, `domain`, `api` are accepted; anything else is a config error. |
 | `maintainedLayers`     | `string[]` | `["L1", "L2-002", "L2-003", "L2-014", "L3-001"]` | Exact validator IDs that remain enforced in Quick Mode. `L1` is the only layer shorthand; `L2` is not expanded. |
 | `relaxedGates`         | `string[]` | `["L2-001", "L3-002", "L3-003", "L3-004", "L4"]` | Validators/layers relaxed by Quick Mode. `L4` means all L4 validators are skipped. |
 | `fullModeRequiredWhen` | `object`   | all flags `true`                        | Conditions that force a Quick Mode change to escalate to the full `/story-implementor` flow. See below. |
+| `categoryOverrides`    | `object`   | `{}`                                    | Maps a change category to a list of globs, so project-specific paths land in a category the built-in table cannot infer. See below. |
+
+The defaults above come from the defense preset declared in `project.preset`; Quick Mode resolves its effective settings through the same preset resolution as the rest of the config (ADR-040). Sub-fields you declare in `phasegate.config.json` replace the preset value for that sub-field only (arrays are replaced wholesale, not merged); sub-fields you omit keep the preset value. All three shipped presets (`minimal` / `standard` / `strict`) currently declare the same Quick Mode values, so switching the defense preset does not change Quick Mode strength today. <!-- @work-item-id WI-377 -->
 
 ##### `fullModeRequiredWhen`
 
@@ -217,6 +221,43 @@ Introduced in ISSUE-006 Story A (v0.63.0) and wired into the pre-tool-use hook b
 
 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.
 
+##### `allowedCategories` is an enum
+
+<!-- @work-item-id WI-373 -->
+
+`allowedCategories` accepts only the seven `ChangeCategory` values. A misspelling such as `"typoo"` is rejected as a config error rather than silently ignored, and case is not normalised — `"Docs"` is an error, not an alias for `"docs"`, because classification keys are always lowercase and a normalised spelling would only hide the same dead setting.
+
+If the quickMode section is invalid, the pre-tool-use hook fails **closed**: writes are blocked with an explicit "quickMode 設定が不正なため" reason until the config is fixed. (A *missing* config still fails open, so greenfield adoption is unaffected.)
+
+##### `categoryOverrides`
+
+<!-- @work-item-id WI-372 -->
+
+```jsonc
+{
+  "quickMode": {
+    "categoryOverrides": {
+      "docs": ["results/**", "notes/**"]
+    }
+  }
+}
+```
+
+Keys are the seven `ChangeCategory` values; values are lists of globs matched against project-relative POSIX paths. Supported syntax is `**` (crosses `/`), `*` (does not cross `/`), and `?` (one non-`/` character); brace expansion and negation are not supported.
+
+| Rule | Behaviour |
+|------|-----------|
+| Precedence | Overrides are evaluated **before** the built-in classification table, so an explicit declaration beats inference. |
+| Downgrade guard | A path the built-in rules classify as `domain` or `api` cannot be moved to a lower-risk category; an override may only raise the risk. |
+| Valid keys | All seven categories, including `domain` / `api` / `feature`. Assigning a path to those *hardens* the gate, since they sit outside the default `allowedCategories`. |
+| Rejection rules | `NEW_DOMAIN` and `API_CONTRACT` remain path-based and ignore overrides entirely. Only `MIXED_CHANGES` uses the override-adjusted category. |
+| Ties | If two categories match the same path, the higher-risk one wins, so the result never depends on JSON key order. |
+
+Overrides apply identically to the pre-tool-use hook, `check-change-category`, and `ci-check --quick`. Leaving `categoryOverrides` unset reproduces the pre-existing classification exactly. See [Quick vs Full Mode](quick-vs-full-mode.md#overriding-the-table-for-project-specific-paths) for worked reasoning.
+
+<!-- @work-item-id WI-380 -->
+`categoryOverrides` goes through the same preset resolution as the other Quick Mode sub-fields (ADR-040), and merges one level deeper than they do: the merge unit is the **category key**, not the whole object. None of the three shipped presets declares `categoryOverrides`, so today whatever you write in `phasegate.config.json` is the effective value verbatim. If a preset does declare it, a category you also declare replaces that category's glob list wholesale, while categories you leave out keep the preset's globs.
+
 <!-- @work-item-id WI-159 -->
 Quick Mode uses exact validator IDs for `maintainedLayers`. To keep all L2 validators active, list `L2-001`, `L2-002`, `L2-003`, `L2-013`, `L2-014`, and `L2-015` explicitly. The default keeps metadata, test-quality, work-item status, and security checks active while skipping phase-gate, CLI E2E coverage, contract traceability coverage, performance, coverage, nyquist, and L4 scheduled validators.
 

package/docs/guide/quick-vs-full-mode.md

@@ -77,6 +77,7 @@ The classifier is **path-based, not intent-based**. It never reads your commit m
 
 | Order | Match | Category |
 |---|---|---|
+| 0 | `quickMode.categoryOverrides` glob match (see below) | the configured category |
 | 1 | `*.config.json`, `*.config.ts`, `phasegate.config.json` | `config` |
 | 2 | `.github/workflows/*.yml`, `.github/workflows/*.yaml` | `config` |
 | 3 | Repo-root bootstrap files: `.gitignore`, `.gitattributes`, `.editorconfig`, `.npmrc`, `.nvmrc`, `tsconfig.json`, `tsconfig.*.json`, anything under `.husky/` | `config` |
@@ -96,6 +97,38 @@ Two consequences worth internalising:
 
 When the hook blocks a write, the message now names the deciding category and change kind per path (`foo.ts (category=feature, changeKind=CREATE)`), and — for `bugfix` / `docs` / `test` / `config` blocks — points at `allowedCategories` and `config:plan --intent quick-mode-relax` rather than at `/story-implementor`. <!-- @work-item-id WI-352 --> <!-- @work-item-id WI-354 -->
 
+### Overriding the table for project-specific paths
+
+<!-- @work-item-id WI-372 -->
+
+The built-in table has no knowledge of your project's own conventions. A directory such as `results/` or `notes/` holds documents, but the classifier sees an unknown path: `MODIFY` falls through to `bugfix`, and `CREATE` falls through to `feature` — a category that cannot be added to `allowedCategories` at all, so the write is permanently Full Mode.
+
+`quickMode.categoryOverrides` maps a category to a list of globs:
+
+```jsonc
+{
+  "quickMode": {
+    "allowedCategories": ["bugfix", "docs", "test", "config"],
+    "categoryOverrides": {
+      "docs": ["results/**", "notes/**"]
+    }
+  }
+}
+```
+
+Four rules govern how overrides interact with the table above:
+
+1. **Overrides are evaluated first — order 0 in the table.** They are an explicit declaration about your repository, so they beat inference. Without this, `notes/deploy.config.json` would still be caught by rule 1 and the setting would look broken.
+2. **Overrides cannot downgrade `domain` or `api`.** If the built-in rules classify a path as `domain` (rule 7) or `api` (rule 5), an override may only raise the risk, never lower it. `{"docs": ["scripts/**"]}` will *not* turn a domain file into a doc. The weakening vector is closed by construction, not by convention.
+3. **All seven categories are valid override keys**, including `domain`, `api`, and `feature`. Assigning a path to one of those only makes the gate harder to pass, since they sit outside the default `allowedCategories` — it is a hardening lever, e.g. `{"domain": ["packages/core/**"]}`.
+4. **`NEW_DOMAIN` and `API_CONTRACT` still apply.** The three rejection rules stay path-based and ignore overrides entirely, so a misconfigured override cannot let a new domain file or a port/adapter change slip through. Only `MIXED_CHANGES` consumes the override-adjusted category.
+
+If two override categories match the same path, the higher-risk one wins, so the result never depends on JSON key order.
+
+Supported glob syntax is deliberately small: `**` (crosses `/`), `*` (does not cross `/`), and `?` (one non-`/` character). Brace expansion and negation are not supported. Patterns are matched against project-relative POSIX paths.
+
+Overrides apply identically to all three consumers — the PreToolUse hook, `check-change-category`, and `ci-check --quick` — because they share one config load. With `categoryOverrides` unset the classification is exactly what it was before the feature existed.
+
 ### Dry-running the classifier
 
 Use `check-change-category` to evaluate an arbitrary file list without actually starting an implementation:
@@ -193,7 +226,9 @@ Stop, commit nothing, and re-launch `/story-implementor`. Don't try to "finish i
 Not by emptying the list — `allowedCategories: []` is rejected as invalid config (`allowedCategories must not be empty`), so it breaks the hook rather than tightening it. Narrow it instead: `allowedCategories: ["docs"]` routes effectively everything through Full Mode while staying valid. Alternatively, leave the categories as-is and set every `quickMode.fullModeRequiredWhen.*` flag to `true` (the default) so any non-trivial scope automatically escalates.
 
 **Q. Can I add custom categories?**
-No. `allowedCategories` accepts only values from a fixed enum — the seven `ChangeCategory` values `bugfix`, `docs`, `test`, `config`, `feature`, `domain`, `api`. The default allow-list is the first four; the remaining three exist so that a project can *deliberately* widen the gate (rarely a good idea), not so you can invent a new label. If your workflow needs a category outside this enum, that is evidence the change is probably Full Mode material.
+No. `allowedCategories` accepts only values from a fixed enum — the seven `ChangeCategory` values `bugfix`, `docs`, `test`, `config`, `feature`, `domain`, `api`. The default allow-list is the first four; the remaining three exist so that a project can *deliberately* widen the gate (rarely a good idea), not so you can invent a new label. The enum is enforced by both the config schema and `QuickModeConfig`, so a misspelling is a loud config error, not a setting that quietly never matches. <!-- @work-item-id WI-373 -->
+
+What you *can* customise is which paths map to which of those seven categories — see [Overriding the table for project-specific paths](#overriding-the-table-for-project-specific-paths). If your workflow needs a category outside the enum, that is evidence the change is probably Full Mode material.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.315.0",
+  "version": "0.335.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",
@@ -60,7 +60,7 @@
     "harness:check-phase": "pnpm phasegate:check-phase",
     "harness:check-ready": "pnpm phasegate:check-ready",
     "test": "vitest run --config scripts/harness/__tests__/vitest.config.forks.ts && vitest run --config scripts/harness/__tests__/vitest.config.ts",
-    "coverage": "node -e \"require('node:fs').rmSync('coverage',{recursive:true,force:true})\" && vitest run --config scripts/harness/__tests__/vitest.config.coverage.forks.ts --reporter=blob --outputFile=coverage/.blob/forks.json && vitest run --config scripts/harness/__tests__/vitest.config.coverage.ts --reporter=blob --outputFile=coverage/.blob/threads.json && vitest run --config scripts/harness/__tests__/vitest.config.coverage.ts --merge-reports=coverage/.blob",
+    "coverage": "node -e \"require('node:fs').rmSync('coverage',{recursive:true,force:true})\" && vitest run --config scripts/harness/__tests__/vitest.config.coverage.forks.ts --reporter=blob --reporter=default --outputFile.blob=coverage/.blob/forks.json && vitest run --config scripts/harness/__tests__/vitest.config.coverage.ts --reporter=blob --reporter=default --outputFile.blob=coverage/.blob/threads.json && vitest run --config scripts/harness/__tests__/vitest.config.coverage.ts --merge-reports=coverage/.blob",
     "ci": "npm run coverage && npm run test"
   },
   "dependencies": {

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

@@ -3,10 +3,14 @@
  * @unit agent-integration
  */
 
+/**
+ * WI-376 (ADR-039): 呼び出し元 skill 名を受け取るフィールドは持たない。
+ * 判定・案内の入力は hook が自ら観測・検証できる state（対象パス、変更カテゴリ、
+ * session marker、設計文書の存在、解決済み config 等）に限る。
+ */
 export interface HandlePreToolUseInput {
   toolName: string;
   targetFilePaths: string[];
-  callerSkill?: string;
   targetChanges?: {
     filePath: string;
     beforeContent?: string | null;

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

@@ -8,6 +8,7 @@
  * @work-item-id WI-214
  * @work-item-id WI-349
  * @work-item-id WI-354
+ * @work-item-id WI-376
  *
  * HandlePreToolUseUseCase
  * PreToolUse Hook処理のオーケストレーション
@@ -187,7 +188,6 @@ export class HandlePreToolUseUseCase {
               fullModeResult,
               guidance,
               unitIdForGuidance,
-              input.callerSkill,
               sessionResult,
             );
           }
@@ -284,7 +284,6 @@ export class HandlePreToolUseUseCase {
     },
     guidance: ErrorGuidance | null,
     unitId: string | undefined,
-    callerSkill?: string,
     sessionResult?: FullModeSessionQueryResult,
   ): HandlePreToolUseOutput {
     const fp = blockedFilePath ?? "不明なファイル";
@@ -311,7 +310,7 @@ export class HandlePreToolUseUseCase {
         nextAction: `${dryRunCommand} && ${applyCommand}`,
       };
     }
-    if (HandlePreToolUseUseCase.shouldGuideQuickModeRelax(result.dominantCategory, callerSkill)) {
+    if (HandlePreToolUseUseCase.shouldGuideQuickModeRelax(result.dominantCategory)) {
       const dryRunCommand = "phasegate config:plan --intent quick-mode-relax --dry-run --json";
       const applyCommand = "phasegate config:plan --intent quick-mode-relax --apply --json";
       const lines: string[] = [`Full mode 必須変更が検出されました: ${fp}`];
@@ -387,15 +386,18 @@ export class HandlePreToolUseUseCase {
    * 実運用で設定されず、この分岐は到達不能だった。カテゴリを一次条件にして
    * skill context なしでも実用的な復旧手順を出す。
    * feature / domain / api は従来どおり /story-implementor 誘導を維持する。
+   *
+   * WI-376 (ADR-039): 判定入力は hook が自ら観測できる state のみとする方針に従い、
+   * カテゴリ未確定時の callerSkill フォールバックを削除した。カテゴリが取れない場合は
+   * 一律 /story-implementor 誘導（従来のフォールバックも実運用では常にこの経路だった）。
    */
   private static readonly QUICK_MODE_SCOPE_CATEGORIES: readonly string[] = ["bugfix", "docs", "test", "config"];
 
-  private static shouldGuideQuickModeRelax(dominantCategory: string | undefined, callerSkill?: string): boolean {
-    if (dominantCategory !== undefined) {
-      return HandlePreToolUseUseCase.QUICK_MODE_SCOPE_CATEGORIES.includes(dominantCategory);
+  private static shouldGuideQuickModeRelax(dominantCategory: string | undefined): boolean {
+    if (dominantCategory === undefined) {
+      return false;
     }
-    // カテゴリ不明時は skill context だけが手掛かり
-    return callerSkill === "quick-implementor";
+    return HandlePreToolUseUseCase.QUICK_MODE_SCOPE_CATEGORIES.includes(dominantCategory);
   }
 
   /**
@@ -575,6 +577,12 @@ export class HandlePreToolUseUseCase {
       message: (fp) =>
         `保護ファイルへの書き込みがブロックされました: ${fp}\nClaude Code の設定変更は /update-config スキルを使用してください。`,
     },
+    {
+      // WI-363: .husky/ 配下は L0 runtime の実施点。Quick Mode でも書き換えさせない。
+      pattern: /(?:^|\/)\.husky\//,
+      message: (fp) =>
+        `保護ファイルへの書き込みがブロックされました: ${fp}\n.husky/ 配下は L0 runtime（pre-commit / commit-msg / pre-push）の実施点であり、Quick Mode でも変更できません。\n未導入 hook の配置は npx phasegate setup:agent --apply --with-husky を使用してください。\n意図的に手編集する場合は phasegate.config.json の protectedFiles.exclude に対象パターンを明示してください。`,
+    },
   ];
 
   private async buildProtectedFileBlockOutput(blockedFilePath: string | undefined): Promise<HandlePreToolUseOutput> {