phasegate 0.264.0 → 0.315.0

package/CHANGELOG.md

@@ -7,8 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **WI-335 — エラー案内の機械往復保証（remediationType 分類 + round-trip テスト）** — suggested action が本当に「従えば直る」かを人間レビュー頼みにせず CI で保証する仕組み。HarnessError に optional `remediationType`（mechanical / ai-assisted / manual、未設定は manual 扱い）を導入し、代表 validator を分類（L2-002 metadata=mechanical、L3-003 レポート不在=mechanical・閾値未達=ai-assisted、L3-001=manual、L4-001/002=ai-assisted）。mechanical 宣言されたエラーは「エラー → suggestion 文言を機械適用 → 再実行 → pass」の往復テストで固定し、案内文言と実挙動が乖離すると（#37/#39 型の破れ）テストが落ちる構造にした。
+
+- **WI-329 — 実分布リリースゲート（tarball release-smoke）** — 単体テスト全 green でも新規インストール即クラッシュ（#34）・非 TS リポで fail-closed（#37/#39）・dead flag（#36）がすり抜けた教訓から、`npm pack` した tarball を実分布相当 fixture（純 Python / Go monorepo / docs のみ）にクリーンインストールし install → doctor → validate → uninstall を実走する E2E を追加。通常 suite では skip（`PHASEGATE_RELEASE_SMOKE=1` ガードで hermetic 性維持）し、CI の新 job `release-smoke` が pack job の実バイト列 artifact に対して実行する。`--with-husky` のフラグ有効性 assert で dead-flag 再発も検知。
+
 ### Fixed
 
+- **WI-334 — CI workflow ファイルの change-category 分類取りこぼしを修正** — `.github/workflows/*.yml` の新規作成が CREATE→feature フォールバックに落ちて pre-tool-use hook にブロックされ、かつ .github/ は unit を持たないため案内される story-implementor 経路が構造的に完遂不能だった（WI-329 のドッグフードで発見。MODIFY は bugfix で通るため防御としても不整合）。WI-261（skills/**/*.md → docs）と同型の明示ルールで `.github/workflows/` 配下の yml/yaml を config に分類（内容防御は L3-006 + integrity pin が担当）。併せて CLI `check-change-category` の changeKind をファイル存在で推定し hook 判定と一致させた（hook の Bash 経路は従来挙動を完全維持）。
+
+- **WI-333 — config 不在時の hook 全遮断デッドロックを解消（ADR-038 G1 / GitHub #40 完全解消）** — config **不在**（ENOENT）で pre-tool-use hook が未捕捉例外→exit 2 となり、config を作成する Write すら遮断される自己修復デッドロックが missing 状態に残っていた（WI-314 は invalid のみ対応）。hook 用 config adapter で ENOENT を警告+既定値の fail-open に変更（EACCES 等の真の異常は従来どおり throw）。gated パスへの書き込みは phase-gate 側が config-foundation 経由の独立 load で fail-closed を維持することをテストで固定。ADR-038 の許可表と G1 を解消済みに更新。
+
+- **WI-330 — doctor の config 状態可視化と許可ポリシーの仕様化（GitHub #40 恒久化）** — doctor が config 不在・不正でも他項目が揃っていれば GREEN を報告していた盲点を解消。新 check `config-status` を追加し、missing → warn（「既定 fail-open で動作中、`phasegate init` で生成可」）、invalid-json / invalid-schema → red（修復の一手つき）、JSON・human 出力に `configStatus` を明示。「config 状態 × 操作クラス」の許可表を ADR-038 として仕様化し、既知ギャップも正直に記録（**G1: config 不在時に pre-tool-use hook が ENOENT 未捕捉で全ツール遮断＝自己修復デッドロックが missing 状態では現存**、G2: invalid-json の検査系が fail-open で原則より緩い）。G1 は WI-333 で修正。
+
+- **WI-331 — CLAUDE.md の user-section を managed block の外へ移す構造修正（GitHub #35 根本修正）** — #35 の根本原因は CLAUDE.md テンプレートだけ user-section が managed block の内側にあり（AGENTS.md は外側）、block 置換のたびに WI-315 の「抽出→再注入」に頼っていたこと。テンプレートを AGENTS.md と対称の外側配置に変更し、install / reconcile は旧構造（内側）を検出すると本文を保持したまま外側へ移設する冪等 migration を実行（2 回目適用で byte 同値をテスト固定）。refresh 経路（claude-md-composer）は新テンプレート採用で自動移行、`$` シーケンス保護と空行保持も強化。新構造では uninstall 後も user-section が生存する副次改善あり。
+
+- **WI-332 — severity 実効判定の単一ソース化と横断 regression（GitHub #38 恒久化）** — 実効 severity 判定（ADR-017 の isEffectivelyPassed）が harness-api と validator-system に複製され、pre-commit は独自集約で severity を見ておらず warning-only failure が exit 1 になっていた。判定を `validator-system/domain/services/effective-severity-policy.ts` に一本化し、validate 集約・CiCheckResult（ci-check / complete-check）・pre-commit の全経路が同一実装を通る形に統一（pre-commit の warning-only は ADR-017 どおり exit 0 へ）。同一結果セットを 3 経路に通して実効判定の一致を assert する横断 regression を追加し、将来の乖離を機械検知する。
+
+- **WI-328 — 実効言語と出所を phasegate:status に表示（GitHub #39 残課題）** — WI-319/320 の言語自動検出の結果がどこにも表示されず、どの validator が有効/SKIP になるか知る術がなかった。`phasegate:status` の JSON に `languages: { effective, source }`（source = `declared` / `detected` / `fallback`）を追加。解決ロジックは validator-system の `resolveProjectLanguages()`（WI-319 の検出テーブル）に一本化して再利用し、validator の有効/SKIP 判定と必ず同じ結果を表示する。ConfigQueryPort への追加は optional メソッドで後方互換。
+
+- **WI-327 — 最小 config（project のみ）で動作可能に** — 手書き `phasegate.config.json` のスキーマが top-level 8 項目を required とし、`{"project": {"name": ..., "preset": ...}}` の最小構成で L1-001 が連発していた。プリセット解決（`PresetResolutionService.deepMerge`）は省略セクションの補完を既に完備していたため、v3 **と v2**（architecture キーなしの最小 config は v2 検証に振られる）の top-level required を `["project"]` に緩和し、型定義を実態に一致させた。**検証は弱めていない**: セクション内の required・型・enum・additionalProperties は不変で、書かれているが不正なキーは従来どおりエラー（spawn E2E で exit 2 を固定）。最小 config の解決結果がプリセット定義と一致することも統合テストで固定。
+
+- **WI-326 — install フラグ状態を manifest に永続化（GitHub #36 残課題）** — `--with-husky` / `--with-ci` / personal の install 時オプションが `.phasegate/manifest.json` に記録されず、後の reconcile が「全 target 対象」を仮定して opt-out したはずの Husky / CI workflow を追加し直す食い違いがあった。manifest に optional `installationFlags` を追加して install（apply）時に実効フラグを記録し、reconcile は明示指定 > manifest 記録 > 従来挙動の優先順で target を構成する。フィールドを持たない旧 manifest は推測せず従来挙動のまま（load / save round-trip のバイト互換もテストで固定）。
+
+- **WI-324 — フレッシュプロジェクトで L3-004 を SKIP に（オンボーディング阻害の解消）** — phasegate 導入直後（story 未作成・requirement-test-matrix 未生成）でも L3-004 が「マトリクス不在」で fail-closed FAIL になり導入体験を阻害していた。「matrix 不在 かつ StoryCatalog（user_stories.md）の story ゼロ」の場合のみ skipWithReason（WI-317 の L3-003 と同表現）で透過 SKIP に変更。**story が 1 件でも存在するのに matrix 不在なら従来どおり fail-closed**（あるべき matrix の消失事故は見逃さない）。story 数の取得に失敗した場合も判定不能として fail-closed 側に倒す。
+
+- **WI-323 — 非ゲート hook の payload フィールド欠落を fail-open 化（GitHub #40 残課題）** — stop hook が stdin payload の `session_id` 欠落で exit 2 になり、WI-314 の「hook は開発フローを止めない」方針と不整合だった。stop（`SESSION_ID_MISSING`）と post-tool-use（`TOOL_NAME_MISSING`）を警告 + hook-skip-event 記録 + exit 0 の fail-open に変更。**pre-tool-use の `tool_name` 欠落 exit 2 は書き込みゲートのため意図的に fail-closed を維持**し、回帰ガードテストで固定。usecase 契約（空 sessionId エラー）は presentation 入口ガード方式で不変。
+
+- **WI-322 — config なし fallback の coverageThreshold 90 を opt-out の 0 に修正（GitHub #37 残課題）** — WI-317 で「カバレッジゲートはオプトイン、0 = 正規の opt-out」と定義したのに、config なし環境で使われる validator-system の `DEFAULT_CONFIG` fallback が `coverageThreshold: 90` のままで、config を持たない環境だけ勝手に 90% が強制される矛盾を解消。fallback のみの変更でプリセット定義（minimal / standard / strict）は不変。fallback 経由で L3-003 が透過 SKIP になることを回帰テストで固定。
+
+- **WI-321 — complete-check の JSON 出力に warning 詳細を含める（GitHub #38 残課題）** — `phasegate:complete-check` が warning を `summary.warnings` の件数のみで返し、どの validator のどんな warning かが出力に含まれなかった非対称を修正。ci-check case と同じく `CiCheckResult` を data ペイロードとして pass / fail 双方で返す（`data.validatorResults[].validatorId / errors[]`）。validator 結果 0 件時は従来どおり data なし。判定ロジック・exit code・lint 合流は不変。
+
+- **WI-325 — load 経路の JSON パース失敗が "Failed to persist" と誤表示される問題を修正** — `FileSystemConfigRepository.load()` の JSON 構文エラーが書き込み用の `ConfigPersistenceError`（"Failed to persist config"）で送出され、読み込み失敗なのに永続化失敗と誤解させるメッセージになっていた。`ConfigParseError extends ConfigPersistenceError` を新設して load 経路を "Failed to parse config JSON" に分離。サブクラス化により main.ts の `instanceof ConfigPersistenceError` fail-open 判定（WI-314）は無変更で互換維持。save 経路は従来どおり。
+
+- **WI-320 — 言語自動検出を実 CLI 経路で有効化（GitHub #39 フォローアップ）** — WI-319 の検出は adapter に実装されたが、実 CLI では preset 解決（`preset-resolution-service`）・mapper・`ProjectConfig` VO の 3 箇所が未宣言時に `["typescript"]` を注入するため dead code だった（シナリオ検証で発見）。「未宣言」シグナルを resolved config から adapter まで生存させ、純 Python リポジトリで L3-003 が unsupported-language SKIP になることを実 CLI spawn の E2E で固定。宣言時の挙動・検証は不変。
+
+- **WI-319 — project.languages のファイルシステム自動検出（GitHub #39）** — `project.languages` 未宣言時に無条件で `["typescript"]` へフォールバックし、純 Python プロジェクトでも TS 専用 validator（L3-002 / L3-003 / L4-003）が既定で走っていた問題を修正。マーカーファイル（python: pyproject.toml 等 / go.mod / Cargo.toml / pom.xml / Gemfile / composer.json、typescript: tsconfig.json または package.json の typescript 依存のみ — phasegate 導入時の package.json を誤検出しないため存在自体は根拠にしない）から検出し、config 宣言は引き続き最優先、検出ゼロ時は従来どおり typescript フォールバック。
+
+- **WI-318 — complete-check に severity-aware 集約を適用（GitHub #38）** — `phasegate:complete-check` が validator の生の `passed` だけを見ており、warning-only failure でも exit 1 になって `validate` / `ci-check` と乖離していた。Stop hook が叩くのは complete-check のため、L2-016 の `ungated-legacy` マーカー（error→可視 warning 降格）が実質無効化されていた。ci-check と同一の `CiCheckResult.fromResults()`（ADR-017 / WI-260 の `isEffectivelyPassed`）を通す集約に修正し、warning 件数を summary に反映。skipped validator が fail 扱いされる潜在バグも同時に解消。lint fail → exit 1 の合流は不変。
+
+- **WI-317 — coverageThreshold の opt-out を到達可能に（GitHub #37）** — L3-003 実装は「カバレッジゲートはオプトイン」と明記しつつ、opt-out 手段（`null`）がスキーマで拒否され、`0` を設定してもレポート不在で fail-closed FAIL になる矛盾があった。ドメイン VO `L3Config.hasCoverageGate()` の「threshold > 0 でのみ有効」の意図に run-l3 を揃え、`coverageThreshold: 0`（および null）を正規の opt-out として SKIP にした（minimal preset の 0 も本来の opt-out として機能）。レポート不在 FAIL の suggestion に (a) カバレッジ付き実行 (b) `coverageThreshold: 0` での opt-out (c) 非 JS/TS プロジェクトの `project.languages` 宣言、の 3 択を案内する。
+
+- **WI-316 — install の `--with-husky` / `--with-ci` dead flag を修正（GitHub #36）** — install コマンドがこの 2 フラグを一度も読まず、`--personal` なしでは常に `.husky/*` と `.github/workflows/phasegate-aidlc-gate.yml` を書き込んでいた。ヘルプ記載・`init` / `setup:agent` と同じ opt-in（フラグ明示時のみ書き込み）に配線を揃え、CLI 統合テストとドキュメントで固定した。usecase のプログラマティック契約（既定 true）は不変。
+
+- **WI-315 — install / reconcile が CLAUDE.md の user-section を上書きする問題を修正（GitHub #35）** — CLAUDE.md テンプレートは user-section が managed-section の内側にあるため、`install --apply` / `reconcile` の managed block 置換がユーザー自身の記述を placeholder で消失させていた。merge 時に既存 user-section 本文を抽出して新 block に再注入する方式で保持するようにした（AGENTS.md の既存挙動は不変）。併せて、ユーザー本文が `String.replace` の置換文字列として `$` シーケンス解釈される潜在破損を replacer 関数で封じた。
+
+- **WI-314 — 不正 config の hook / doctor 自己修復デッドロック解消（GitHub #40）** — スキーマ違反の `phasegate.config.json` が dispatch 上流の fail-closed で全コマンドを exit 2 にし、pre-tool-use hook 経由で Bash / Write / Edit を全遮断して config 自身の修復も不能になる問題を修正。`hook` / `doctor` は警告 + 既定設定で続行する fail-open とし（診断・自己修復経路の常時確保）、`validate` / `ci-check` 等の検査系は復旧手順の案内付きで fail-closed を維持。hook 内部 adapter の素 `JSON.parse` throw も同様に fail-open 化し、構文破壊 JSON での再デッドロックを塞いだ。gated スコープへの書き込みは phase-gate 判定が引き続き fail-closed でブロックする。
+
+- **WI-313 — typescript peer range を `<7.0.0` に制限（GitHub #34）** — peer 自動インストールで typescript@7 が解決されると classic compiler API（`ts.ScriptTarget` 等）が存在せず全コマンドが `Cannot read properties of undefined (reading 'ESNext')` でクラッシュする問題を修正。TypeScript 7 系を peer range で弾き、packaging contract テストで range を固定した。
+
+- **WI-312 — coverage-producing CI gate** — production workflowとbundled `aidlc-gate`がL3-003実行前に`coverage/coverage-summary.json`を生成せず、clean checkoutでcoverageThresholdに対してfail-closedとなる既存欠陥を修正。self-repoはcoverage付きunit / integrationとcoverage対象外E2Eを各1回だけ実行してplain full suiteの二重実行を避け、threads開始時にもforks blobを保持して両poolをmergeする。templateは採用projectの`coverage` scriptをpackage manager別に必須実行し、test / coverage → matrix → World derive二重一致 → L3 → attestation → integrityの順序を維持する。
+
+- **WI-311 — hermetic CI-facing harness integration tests** — GitHub Actionsのtest-before-matrix順序で、real lint integrationとCLI E2Eがself-repo cwd、coverage、untracked requirement matrixを暗黙のPASS入力としていた既存欠陥を修正。lint adapterへ明示rootを注入してtracked minimal workspaceだけを実scanし、`phasegate:ci-check --json`とlegacy `complete-check`はL3 / Worldを明示無効化したtemp configで公開command契約を検証する。productionのfail-closedとCI gate順序は変更しない。
+
+- **WI-310 — hermetic large-stdout CLI regression** — WI-308の64 KiB超assertionがuntracked requirement matrixとself-repoの604 adopted-legacy warningsへ依存していた欠陥を修正。tracked World-enabled configを使うtemp corpusに160組のduplicate fragment IDを生成し、CIのtest-before-matrix順序でも`validate --layer L2 --format json` / `--json`が決定的に64 KiBを超えて完全parseできる契約へ置換した。
+
 - **WI-309 — WI-305 validator domain reflection repair** — `DesignChangeDeclarationPolicy`を実装・配線しながらvalidator-system `domain_model.md`へのWI-305累積反映を欠落させ、story reflection corpusが検出したbaseline外違反を正規に解消。exact `corpusRole + DeclaredKey`照合、pinned change限定、Work-Item trailer intersection、unique sorted finding、local fast-path / L3 authority境界を実コードどおり記録し、baseline / allowlistには触れていない。
 
 - **WI-308 — CLI large stdout drain** — self-repoのWorld enforcement有効化により`validate --layer L2 --json`が604件のadopted-legacy warningを含む64 KiB超のJSONとなり、`console.log`直後の`process.exit`がpipe bufferをdrainせず末尾を切断する回帰を修正。direct stdout resultを返す全top-level CLI経路を共通graceful exitへ統合し、warningを省略せず任意サイズの完全な出力と既存exit codeを維持する。64 KiB超を必須条件とするprocess E2Eで`--format json` / `--json`双方を固定し、同E2E fileの全subprocess caseへ明示60秒timeoutを適用した。

package/docs/ADR/017-warning-severity-aggregation.md

@@ -212,3 +212,20 @@ human/agent/ci formatter で `[FAIL]` と `[WARN]` を分離:
 2. **(B) warning も exit 1 を default に保つ（CI 互換性優先）** — default を変えず移行コストはゼロだが、`defaultSeverity: warning` 宣言と「常に fail」実装の semantic 乖離が残るため不採用。
 
 採用理由の詳細は上記 Decision「採用理由」を参照。
+
+## 追記 (WI-332, 2026-07-18): 実効判定の共有実装と全経路の経由
+
+本 ADR の Decision（集計セマンティクス）自体は変更しない。実装配置に関する追記のみ。
+
+github#38（`complete-check` だけが独自集約を持ち warning-only failure で exit 1 になった回帰。
+WI-318 で修正）の恒久化として、WI-332 で「実効 severity 判定」を単一の共有実装に集約した:
+
+- **共有実装（単一ソース）**: `scripts/harness/validator-system/domain/services/effective-severity-policy.ts` の `isEffectivelyPassed()`。本 ADR Decision の集計セマンティクス（skipped / passed=true は実質 pass、error 含みは fail、errors=[] は防御的に fail、warning-only は `failOnWarning=false` 既定で実質 pass）をそのまま実装する
+- **全経路がこれを経由する**:
+  - `validate` 集約 — `validator-system/application/use-cases/aggregate-validation-results-usecase.ts`（WI-332 で複製実装を削除し共有実装を参照）
+  - `ci-check` / `complete-check` — `harness-api/domain/value-objects/ci-check-result.ts` の `CiCheckResult.fromResults()`（WI-318 で 2 コマンド共有化、WI-332 で複製実装を削除し共有実装を参照）
+  - `pre-commit` / `commit-msg` / `bypass-audit` — `integrations/pre-commit.ts` の `buildReport()` / `classifyValidatorFailure()`（WI-332 で手動集約 `failed === 0` を共有実装経由に変更。pre-commit 経路には `validate.failOnWarning` の config 配線が無いため、既定値 `false` に固定）
+- **例外**: `status` コマンドは「failure を表示しつつ常に exit 0」という独立契約のため、本判定の対象外
+- **回帰防御**: `scripts/harness/__tests__/integration/validator-system/severity-aggregation-consistency.test.ts` が同一の validator 結果セット（全 pass / warning-only / error / mixed / errors=[] / skipped）を 3 経路（validate 集約・CiCheckResult・pre-commit 集約）に通し、実効判定の一致を assert する。どれかの経路が独自判定に戻るとこのテストが落ちる
+
+新しい集約経路を追加する場合は、必ず `isEffectivelyPassed()` を経由し、上記横断テストに経路を追加すること（ADR-021 の格下げ禁止契約も併せて参照）。

package/docs/ADR/038-config-state-operation-permission-policy.md

@@ -0,0 +1,78 @@
+---
+adr_id: "038"
+title: "config 状態と操作クラスの許可ポリシー"
+status: Accepted
+date: 2026-07-18
+---
+
+# config 状態と操作クラスの許可ポリシー
+
+<!-- @work-item-id WI-330 -->
+<!-- @work-item-id WI-333 -->
+
+## Context
+
+GitHub #40 は「スキーマ違反の `phasegate.config.json` があると pre-tool-use hook が exit 2 で全ツールを遮断し、config を修復する経路自体が消える（自己修復デッドロック）」という障害だった。WI-314 で hook / doctor を fail-open にする応急処置を入れ、WI-323 で hook 側 adapter の JSON parse fail-open、WI-325 で `ConfigParseError` の導入（誤メッセージ修正）を行った。しかし、
+
+- (a) doctor は config 不在・不正でも config 状態を diagnostics に含めず、他が揃っていれば GREEN を報告していた。
+- (b) 「config がどの状態のとき、どの操作クラスが許可されるか」を定義した仕様書が存在せず、各修正がアドホックな穴埋めになっていた。
+- (c) config **missing** 系のテストが欠落しており、missing 状態の実挙動は未検証だった。
+
+WI-330 で許可表を実測に基づいて仕様化し、doctor に config 状態 check（`config-status`）を追加し、欠落マスをテストで固定した。
+
+## Decision
+
+### 1. config 状態は 4 値で分類する
+
+`missing` / `invalid-json` / `invalid-schema` / `valid`。判定は config-foundation の実 load 経路（`FileSystemConfigRepository` の JSON parse + AJV schema 検証 + preset 解決）をそのまま使う。エラー型との対応:
+
+| 状態 | 検出エラー型 | 定義箇所 |
+|------|-------------|---------|
+| missing | `ConfigNotFoundError` | `scripts/harness/config-foundation/infrastructure/repositories/file-system-config-repository.ts:12` |
+| invalid-json | `ConfigParseError`（`ConfigPersistenceError` のサブクラス、WI-325） | 同ファイル `:41` |
+| invalid-schema | `ConfigValidationError`（AJV 違反・未知 preset を含む） | `scripts/harness/config-foundation/domain/errors/config-validation-error.ts:9`、throw 箇所は `load-resolved-config-use-case.ts:71-99` |
+| valid | —（load 成功） | — |
+
+config の解決順は project 直下 `phasegate.config.json` → `.phasegate-local/phasegate.config.json`（personal install）で、CLI は cwd から上方探索する（`file-system-config-repository.ts:58-81` `findNearestConfig`）。
+
+### 2. 許可表（config 状態 × 操作クラス）
+
+2026-07-18 時点の**実測**（`invalid-config-fail-open.integration.test.ts` で固定。missing 列は WI-333 で fail-open 化）。○ = 許可 / ● = 意図したゲート判定で通過・遮断 / × = 遮断。
+
+| 操作クラス ＼ config 状態 | valid | missing | invalid-json | invalid-schema |
+|---|---|---|---|---|
+| **config 自身への編集**（hook 経由 Write/Edit） | ○ fail-open（既定では保護対象外。`protectedFiles.patterns` に含めた場合のみ CLI 誘導 block） | ○ fail-open（WI-333。自己修復経路） | ○ fail-open | ○ fail-open |
+| **gated パス書込**（`scripts/harness/` 等、hook 経由） | ● phase-gate 判定（fail-closed） | ● 既定設定で phase-gate 判定（fail-closed 維持、WI-333） | ● 既定設定で phase-gate 判定（fail-closed 維持） | ● 既定設定で phase-gate 判定（fail-closed 維持） |
+| **無関係パス書込**（hook 経由） | ○ | ○ fail-open（警告付き、WI-333） | ○ fail-open | ○ fail-open |
+| **無関係 Bash**（書込抽出なし、hook 経由） | ○ | ○ fail-open（警告付き、WI-333） | ○ fail-open（警告付き） | ○ fail-open（警告付き） |
+| **検査系コマンド**（`validate` / `ci-check` 等） | ○ 通常実行 | ○ fail-open（既定設定で実行、exit 0） | **○ fail-open（警告付き exit 0）【設計意図より緩い】** | × fail-closed（exit 2 + Recovery 手順） |
+| **hook・doctor 起動** | ○ | ○ fail-open（doctor は `configStatus: missing` → warn。hook は警告 + 既定設定で完走、WI-333） | ○ fail-open（doctor は `configStatus: invalid-json` → red） | ○ fail-open（`CONFIG_FAIL_OPEN_COMMANDS`。doctor は `configStatus: invalid-schema` → red） |
+
+コード根拠:
+
+- **CLI dispatch 層の fail-open/fail-closed 分岐**: `scripts/harness/main.ts:1867` `CONFIG_FAIL_OPEN_COMMANDS = new Set(["hook", "doctor"])`、`main.ts:1869-1902` `loadResolvedConfig()` — `ConfigValidationError` は hook/doctor のみ fail-open・他は exit 2（`:1878-1889`）、`ConfigNotFoundError` は全コマンド silent fail-open（`:1891-1893`）、`ConfigParseError`（`instanceof ConfigPersistenceError`）は全コマンド警告付き fail-open（`:1894-1900`）。
+- **hook 実行層の fail-open**: `scripts/harness/agent-integration/infrastructure/adapters/harness-config-config-query-adapter.ts` `loadConfig()` — JSON parse 失敗と `fs.readFileSync` の ENOENT（missing、WI-333）はいずれも警告 + 空 config（既定値）で続行。ENOENT **以外**の fs エラー（EACCES / EISDIR 等の真の異常）は従来どおり throw し、`scripts/harness/agent-integration/presentation/pre-tool-use-hook.ts` の outer catch で「実行エラー」exit 2 になる。fallback config path は `pre-tool-use-hook.ts:58-76` `findConfigPath()`（不在時は `startDir/phasegate.config.json` を返す）。
+- **missing の gated パス fail-closed**: hook 側 config は既定値に縮退するが、gated パス書込は `phase-gate-query-adapter.ts` が config-foundation の `ConfigNotFoundError` を generic catch で「評価不能 = NOT passed」に落とすため、phase-gate block（フェーズゲート違反、exit 2）が維持される。
+- **config 自身が gated/protected でない根拠**: 既定の保護パターンに `phasegate.config.json` は含まれない（`scripts/harness/agent-integration/domain/value-objects/protected-file-list.ts:17-27` `DEFAULT_PATTERNS`）。ユーザーが `protectedFiles.patterns` で保護した場合のみ CLI 誘導付き block（`handle-pre-tool-use-usecase.ts:480-495`）。
+- **doctor の config 状態可視化（WI-330 で追加)**: `scripts/harness/installation/infrastructure/adapters/config-status-probe-adapter.ts`（分類）、`installation/application/checks/config-status-check.ts`（missing → warn / invalid-* → red）、`installation/presentation/formatters/diagnostic-report-formatter.ts`（JSON `configStatus` フィールドと human `Config:` 行）。
+
+### 3. 設計原則
+
+1. **自己修復例外は復旧経路の保証であり、検査系の fail-closed は緩めない。** hook（エージェントのツール遮断点）と doctor（自己診断）は config がどんな状態でも起動・完走できなければならない。逆に `validate` / `ci-check` 等の検査系は、設定が壊れた状態の検査結果を「合格」として流通させないため fail-closed を原則とする。
+2. **fail-open は必ず可視化とセットにする。** fail-open で既定設定に落ちた事実は stderr 警告（CLI/hook）と doctor の `configStatus` + `config-status` finding（missing = warn、invalid-* = red）で必ず表面化させる。「不正 config でも doctor GREEN」は本 ADR をもって仕様違反である。
+3. **gated スコープの fail-closed は config 状態に依存しない。** config が壊れていても、gated パスへの書込は既定設定による phase-gate 判定で引き続きブロックされる（fail-open は「遮断の解除」ではなく「既定設定への縮退」）。
+
+### 4. 既知ギャップ（本 ADR は現状を固定し、修正は別 WI）
+
+| # | ギャップ | 現状 | あるべき姿 |
+|---|---------|------|-----------|
+| G1 | **missing 状態で pre-tool-use hook が全ツール遮断**（config 自身への Write も遮断 = 自己修復デッドロック復活） | **WI-333 で解消**: `harness-config-config-query-adapter.ts` `loadConfig()` が ENOENT を捕捉し「警告 + 既定値で続行」の fail-open。config 自身への Write / 無関係 Bash は exit 0、gated パス書込は既定設定の phase-gate 判定で fail-closed 維持（`invalid-config-fail-open.integration.test.ts` の WI-333 テストで固定） | invalid-json と同じ「警告 + 既定値で続行」 — 達成済み |
+| G2 | **invalid-json の検査系が fail-open**（invalid-schema より緩い） | `ConfigParseError` が `ConfigPersistenceError` 経路で全コマンド fail-open（exit 0） | 検査系は invalid-schema と同様 fail-closed が原則に忠実。ただし挙動変更は breaking のため要判断 |
+
+いずれも `scripts/harness/__tests__/integration/harness-api/invalid-config-fail-open.integration.test.ts` のテストで挙動を固定済み（G1 は fail-open 期待に反転済み）。挙動を修正する際はテストの期待値反転とこの表の更新を同一変更で行うこと。
+
+## Consequences
+
+- doctor は config 状態を常に報告する（JSON: `configStatus`、human: `Config:` 行、finding: `config-status`）。config 不在・不正のまま GREEN を報告することはなくなる（missing は warn、invalid-* は red で exit 1）。
+- 許可表が仕様となったため、fail-open/fail-closed の変更は本 ADR の改訂を伴う。
+- 経緯: WI-314（hook/doctor fail-open 化）→ WI-323（hook adapter の JSON parse fail-open）→ WI-325（`ConfigParseError` 導入）→ WI-330（本 ADR・doctor 可視化・missing 系テスト固定）→ WI-333（G1 解消: hook adapter の ENOENT fail-open、github#40 完全解消）。

package/docs/guide/installation.md

@@ -56,7 +56,7 @@ npx phasegate install --apply
 npx phasegate doctor
 ```
 
-`install --dry-run` reports whether each target will be created, merged, skipped, or refused. `install --apply` performs the merge, adds package scripts and the `phasegate` devDependency, deploys selected bundled skills to root `skills/`, creates `.claude/skills` and `.codex/skills` links, writes `CLAUDE.md` / `AGENTS.md` managed sections for selected agent targets, writes `.github/workflows/phasegate-aidlc-gate.yml` when CI is enabled, and records managed entries in `.phasegate/manifest.json`. Existing skills catalogs are merged: PhaseGate refreshes only bundled skill directories selected by `--skills core|all` and preserves user-owned skills. See [Setup Artifacts](setup-artifacts.md) for the full managed target, generated artifact, runtime state, legacy artifact, and user-level setting inventory. <!-- @work-item-id WI-152 --> <!-- @work-item-id WI-169 --> <!-- @work-item-id WI-174 --> <!-- @work-item-id WI-216 -->
+`install --dry-run` reports whether each target will be created, merged, skipped, or refused. `install --apply` performs the merge, adds package scripts and the `phasegate` devDependency, deploys selected bundled skills to root `skills/`, creates `.claude/skills` and `.codex/skills` links, writes `CLAUDE.md` / `AGENTS.md` managed sections for selected agent targets, writes `.github/workflows/phasegate-aidlc-gate.yml` when CI is enabled, and records managed entries in `.phasegate/manifest.json`. Husky hook targets (`.husky/*`) and the GitHub Actions target are opt-in, matching `init` and `setup:agent`: pass `--with-husky` and/or `--with-ci` to include them — without these flags `install` does not touch `.husky/` or `.github/workflows/`. <!-- @work-item-id WI-316 --> Existing skills catalogs are merged: PhaseGate refreshes only bundled skill directories selected by `--skills core|all` and preserves user-owned skills. See [Setup Artifacts](setup-artifacts.md) for the full managed target, generated artifact, runtime state, legacy artifact, and user-level setting inventory. <!-- @work-item-id WI-152 --> <!-- @work-item-id WI-169 --> <!-- @work-item-id WI-174 --> <!-- @work-item-id WI-216 -->
 
 For personal evaluation inside a team-owned repository:
 

package/docs/guide/layer-model.md

@@ -43,6 +43,8 @@ npx phasegate hook post-tool-use < payload.json
 npx phasegate hook stop < payload.json
 ```
 
+> **Config 状態と許可ポリシー**: `phasegate.config.json` が不在・破損している状態で各 hook / コマンドがどう振る舞うか（fail-open / fail-closed の別、自己修復経路、doctor の `configStatus` 報告）は [ADR-038](../ADR/038-config-state-operation-permission-policy.md) の許可表で仕様化されている。
+
 ### L0-B: Husky git hooks
 
 Deployed by `phasegate init --with-husky` into `.husky/`.

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

@@ -71,6 +71,31 @@ npx phasegate session end --work-item <WI-XXX>
 
 The PreToolUse hook validates `.phasegate/session.json` by TTL, unit, and dominant category. The `/story-implementor` skill is still the design/TDD guide; the session marker is the authorization the hook can actually observe. <!-- @work-item-id WI-206 -->
 
+### How a path becomes a category
+
+The classifier is **path-based, not intent-based**. It never reads your commit message or your stated purpose; it looks at the write target's path and its change kind (`CREATE` / `MODIFY` / `DELETE`). Rules are evaluated in this order, first match wins:
+
+| Order | Match | 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` |
+| 4 | Comment/whitespace-only diff | `docs` |
+| 5 | `*port.ts`, `*adapter.ts` | `api` |
+| 6 | `__tests__/`, `*.test.ts`, `*.spec.ts` | `test` |
+| 7 | Anything under a `domain/` directory | `domain` |
+| 8 | Anything under `docs/` | `docs` |
+| 9 | `skills/**/*.md` | `docs` |
+| 10 | Any other `CREATE` | `feature` |
+| 11 | Any other `MODIFY` / `DELETE` | `bugfix` |
+
+Two consequences worth internalising:
+
+- The `config` rules are an **explicit allow-list**, not a wildcard. `.github/dependabot.yml`, `packages/app/.gitignore`, or a `Dockerfile` are *not* `config` — created fresh they fall through to `feature` and are blocked. This is deliberate fail-closed behaviour: widening the list is a config decision, not an inference the hook makes for you.
+- `feature` is the fallback for **every new non-test source file**. "It's only a tiny helper" does not change the classification.
+
+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 -->
+
 ### Dry-running the classifier
 
 Use `check-change-category` to evaluate an arbitrary file list without actually starting an implementation:
@@ -159,16 +184,16 @@ Codify the split in your head (or in a project CLAUDE.md note) — "`domain/**`
 ## FAQ
 
 **Q. I have a one-line bugfix in `domain/`. Does "any file under `domain/`" auto-trigger Full?**
-Not mechanically — Quick Mode does not inspect paths. A one-line bugfix inside an existing domain method (fixing an off-by-one, null check, wrong comparator) is still Quick-eligible. What triggers Full is *adding or reshaping* a domain concept, not editing an existing one.
+Yes — mechanically. The classifier is path-based (see [How a path becomes a category](#how-a-path-becomes-a-category)), so *any* write under a `domain/` directory lands in the `domain` category, which is outside the default `allowedCategories`, and the hook blocks it with `MIXED_CHANGES`. Judgement about "it's only an off-by-one" does not enter into it. If the fix is genuinely trivial, the sanctioned routes are a Full Mode session (`phasegate session begin --mode full --unit <unit> ...`) or, when the project has decided domain edits are routinely Quick-eligible, widening `allowedCategories` via `config:plan`. Do not expect the hook to infer intent.
 
 **Q. What if Quick discovers the change is bigger than expected mid-flight?**
 Stop, commit nothing, and re-launch `/story-implementor`. Don't try to "finish in Quick" — you'll skip the design gate that would otherwise catch the scope creep.
 
 **Q. Can I disable Quick Mode entirely?**
-Yes — remove all entries from `quickMode.allowedCategories` in `phasegate.config.json`. All changes will route through Full Mode. This is reasonable for high-compliance projects. Alternatively, leave the categories as-is and set every `quickMode.fullModeRequiredWhen.*` flag to `true` (the default) so any non-trivial scope automatically escalates.
+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` is a fixed enum (`bugfix`, `docs`, `test`, `config`). If your workflow needs a fifth category, 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. If your workflow needs a category outside this enum, that is evidence the change is probably Full Mode material.
 
 ---
 

package/docs/guide/troubleshooting.md

@@ -27,6 +27,43 @@ Each finding has a severity, a repair mode, and optional next-step fields.
 | `ci-workflow-missing` | `npx phasegate setup:agent --intent ci-only --with-ci --dry-run --json` |
 | agent context drift | `npx phasegate reconcile --dry-run` |
 
+## Phase Gate Blocked a Write and I Do Not Know What the Document Should Contain
+
+<!-- @work-item-id WI-356 -->
+
+Phase Gate blocks (`L2-001`, `FULL_MODE_REQUIRED`) mean a required inception or product design document is missing. Two things are needed: the file skeleton, and the section structure to fill in.
+
+**1. Generate the skeleton.** `scaffold-design` writes a placeholder document for the missing phase:
+
+```bash
+npx phasegate scaffold-design --unit <unit-id> --phase logical --dry-run
+npx phasegate scaffold-design --unit <unit-id> --phase logical --apply
+```
+
+Accepted `--phase` values: `logical`, `domain`, `uiux`, `unit-test`, `it-test`.
+
+**2. Read the section structure from the skill definition.** PhaseGate does not ship fill-in templates into your repo; the authoritative structure of every plan and inception artifact lives in the skill markdown that produces it. `install` / `init` copy these into `skills/` in your repository:
+
+| Document | Skill definition |
+|---|---|
+| product architecture / unit decomposition | `skills/product-architect/SKILL.md` |
+| story map | `skills/story-mapper/SKILL.md` |
+| story descriptions / acceptance criteria | `skills/story-writer/SKILL.md` |
+| unit plan | `skills/unit-designer/SKILL.md` |
+| `logical_design.md` | `skills/logical-designer/SKILL.md` |
+| `domain_model.md` | `skills/domain-designer/SKILL.md` |
+| UI/UX design | `skills/uiux-designer/SKILL.md` |
+| unit / IT / scenario test plans | `skills/unit-test-designer/SKILL.md`, `skills/it-test-designer/SKILL.md`, `skills/scenario-test-designer/SKILL.md` |
+
+If `skills/` is not present in your repository — the personal install path does not copy it — read the same content from PhaseGate's own package instead:
+
+```bash
+npx phasegate skills list
+npx phasegate skills info logical-designer
+```
+
+`skills info` prints the full SKILL.md to stdout, so it works from a sandboxed agent that cannot read `node_modules/`.
+
 ## Refused Managed Target
 
 If `install`, `reconcile`, or `uninstall` refuses a target, do not immediately force it. Inspect the diff and ask the agent to explain:

package/docs/templates/agent-context/CLAUDE.md.template.md

@@ -1,6 +1,6 @@
 # CLAUDE.md
 
-<!-- @work-item-id WI-174, WI-176, WI-177 -->
+<!-- @work-item-id WI-174, WI-176, WI-177, WI-331 -->
 
 <!-- phasegate:managed-section:start -->
 ## 必読ドキュメント
@@ -38,13 +38,13 @@ If `setup:agent --apply --json` or `install --apply --json` fails with a structu
 
 {{PHASEGATE_SKILLS}}
 
+## Agent Context Refresh
+
+Run `phasegate ci:auto-refresh-agent-context --dry-run` to preview updates and `phasegate ci:auto-refresh-agent-context --apply` to write AGENTS.md / CLAUDE.md.
+<!-- phasegate:managed-section:end -->
+
 ## User Section
 
 <!-- phasegate:user-section:start -->
 {{PHASEGATE_USER_SECTION}}
 <!-- phasegate:user-section:end -->
-
-## Agent Context Refresh
-
-Run `phasegate ci:auto-refresh-agent-context --dry-run` to preview updates and `phasegate ci:auto-refresh-agent-context --apply` to write AGENTS.md / CLAUDE.md.
-<!-- phasegate:managed-section:end -->

package/docs/templates/ci/aidlc-gate.yml

@@ -7,10 +7,11 @@
 # 実行内容:
 #   1. bypass:audit — bypass trailer / evidence 監査
 #   2. phasegate lint  — L1 Biome AST ルール検証
-#   3. requirement-test matrix をcurrent testsから再生成
-#   4. world.enabled=true の場合、world:derive を2回実行してbyte一致を検証
-#   5. phasegate:ci-check — L3 CI バリデータ（security / performance / coverage / nyquist / World）
-#   6. 失敗時: PR にエラーサマリーをコメント
+#   3. package の coverage script を実行し、L3-003 の入力を生成
+#   4. requirement-test matrix をcurrent testsから再生成
+#   5. world.enabled=true の場合、world:derive を2回実行してbyte一致を検証
+#   6. phasegate:ci-check — L3 CI バリデータ（security / performance / coverage / nyquist / World）
+#   7. 失敗時: PR にエラーサマリーをコメント
 
 name: AIDLC Quality Gate
 
@@ -79,6 +80,23 @@ jobs:
           echo "exit_code=$EXIT_CODE" >> $GITHUB_OUTPUT
           exit $EXIT_CODE
 
+      # L3-003 is fail-closed when coverageThreshold is configured but the
+      # report is absent. The adopting project owns this script and must emit
+      # coverage/coverage-summary.json; package-manager selection follows the
+      # lockfile used during dependency installation above.
+      - name: Test and generate coverage
+        shell: bash
+        run: |
+          set -euo pipefail
+          node -e "const scripts=require('./package.json').scripts ?? {}; if (!scripts.coverage) { throw new Error('phasegate aidlc-gate requires package.json scripts.coverage to generate coverage/coverage-summary.json'); }"
+          if [ -f pnpm-lock.yaml ]; then
+            pnpm run coverage
+          elif [ -f yarn.lock ]; then
+            yarn coverage
+          else
+            npm run coverage
+          fi
+
       # L3-004 consumes the generated requirement-test matrix. Always rebuild it
       # from this checkout instead of trusting a stale or persisted artifact.
       - name: Generate requirement-test matrix

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.264.0",
+  "version": "0.315.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",
@@ -78,7 +78,7 @@
     "vitest": "^3.0.0"
   },
   "peerDependencies": {
-    "typescript": ">=5.0.0"
+    "typescript": ">=5.0.0 <7.0.0"
   },
   "peerDependenciesMeta": {
     "typescript": {

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

@@ -6,6 +6,8 @@
  * @work-item-id WI-202 / WI-204
  * @work-item-id WI-206
  * @work-item-id WI-214
+ * @work-item-id WI-349
+ * @work-item-id WI-354
  *
  * HandlePreToolUseUseCase
  * PreToolUse Hook処理のオーケストレーション
@@ -17,11 +19,11 @@ import type {
 } from "../../domain/ports/baseline-grandfather-query-port.js";
 import type { ConfigQueryPort } from "../../domain/ports/config-query-port.js";
 import type { ErrorGuidance, ErrorGuidanceQueryPort } from "../../domain/ports/error-guidance-query-port.js";
+import type { FullModeRequirementQueryPort } from "../../domain/ports/full-mode-requirement-query-port.js";
 import type {
   FullModeSessionQueryPort,
   FullModeSessionQueryResult,
 } from "../../domain/ports/full-mode-session-query-port.js";
-import type { FullModeRequirementQueryPort } from "../../domain/ports/full-mode-requirement-query-port.js";
 import type { PhaseGateQueryPort } from "../../domain/ports/phase-gate-query-port.js";
 import type { StoryReflectionQueryPort } from "../../domain/ports/story-reflection-query-port.js";
 import { AsyncHookToCliTranslator } from "../../domain/services/hook-to-cli-translator.js";
@@ -186,6 +188,7 @@ export class HandlePreToolUseUseCase {
               guidance,
               unitIdForGuidance,
               input.callerSkill,
+              sessionResult,
             );
           }
         } else {
@@ -282,21 +285,20 @@ export class HandlePreToolUseUseCase {
     guidance: ErrorGuidance | null,
     unitId: string | undefined,
     callerSkill?: string,
+    sessionResult?: FullModeSessionQueryResult,
   ): HandlePreToolUseOutput {
     const fp = blockedFilePath ?? "不明なファイル";
     if (result.dominantCategory === "config" && /(?:^|\/)phasegate\.config\.json$/.test(fp)) {
       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 = [
-        `Full mode 必須変更が検出されました: ${fp}`,
-        "カテゴリ: config",
-      ];
+      const lines = [`Full mode 必須変更が検出されました: ${fp}`, "カテゴリ: config"];
       if (result.rejectionRule) {
         lines.push(`判定ルール: ${result.rejectionRule}`);
       }
       if (result.rejectionReason) {
         lines.push(`理由: ${result.rejectionReason}`);
       }
+      HandlePreToolUseUseCase.appendJudgmentContextLines(lines, sessionResult);
       lines.push(`次のアクション: ${dryRunCommand} で差分を確認し、承認後に ${applyCommand} を実行してください。`);
 
       return {
@@ -309,22 +311,24 @@ export class HandlePreToolUseUseCase {
         nextAction: `${dryRunCommand} && ${applyCommand}`,
       };
     }
-    if (
-      callerSkill === "quick-implementor" &&
-      result.dominantCategory !== undefined &&
-      ["bugfix", "docs", "test", "config"].includes(result.dominantCategory)
-    ) {
+    if (HandlePreToolUseUseCase.shouldGuideQuickModeRelax(result.dominantCategory, callerSkill)) {
       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}`];
-      lines.push(`カテゴリ: ${result.dominantCategory}`);
+      if (result.dominantCategory) {
+        lines.push(`カテゴリ: ${result.dominantCategory}`);
+      }
       if (result.rejectionRule) {
         lines.push(`判定ルール: ${result.rejectionRule}`);
       }
       if (result.rejectionReason) {
         lines.push(`理由: ${result.rejectionReason}`);
       }
-      lines.push(`次のアクション: Quick Mode の許可カテゴリを確認してください。緩和する場合は ${dryRunCommand} で差分を確認し、承認後に ${applyCommand} を実行してください。`);
+      HandlePreToolUseUseCase.appendJudgmentContextLines(lines, sessionResult);
+      lines.push(
+        `次のアクション: Quick Mode の許可カテゴリを確認してください。緩和する場合は ${dryRunCommand} で差分を確認し、承認後に ${applyCommand} を実行してください。`,
+      );
+      lines.push(`  分類の確認: npx phasegate check-change-category --paths ${fp}`);
 
       return {
         shouldBlock: true,
@@ -346,9 +350,15 @@ export class HandlePreToolUseUseCase {
     if (result.rejectionReason) {
       lines.push(`理由: ${result.rejectionReason}`);
     }
+    HandlePreToolUseUseCase.appendJudgmentContextLines(lines, sessionResult);
     const suggestedSkill = guidance?.suggestedSkill ?? "/story-implementor";
     lines.push(`次のアクション: ${suggestedSkill} スキルを使用して設計フェーズから開始してください。`);
     if (unitId !== undefined && unitId !== "") {
+      if (HandlePreToolUseUseCase.isSessionActiveButRejected(sessionResult)) {
+        lines.push(
+          `  既存 session は上記理由で今回の書き込みに使えません。張り直す場合: phasegate session end --work-item ${sessionResult?.workItemId ?? "<WI-XXX>"} を実行してから下記を実行してください。`,
+        );
+      }
       lines.push(
         `  実装フェーズ開始時: phasegate session begin --mode full --unit ${unitId} --work-item <WI-XXX> --reason "<reason>" --duration 1h`,
       );
@@ -367,6 +377,56 @@ export class HandlePreToolUseUseCase {
     };
   }
 
+  /**
+   * Quick Mode スコープのカテゴリ（bugfix / docs / test / config）は quick-implementor で
+   * 完遂できる変更であり、遮断の実体は「allowedCategories が絞られている」ことである。
+   * ここで /story-implementor を案内すると、設計フェーズからやり直せという誤った指示になる。
+   *
+   * WI-354: 従来は callerSkill === "quick-implementor" を条件にしていたが、
+   * callerSkill を供給する producer（hook input の caller_skill / PHASEGATE_CALLER_SKILL）は
+   * 実運用で設定されず、この分岐は到達不能だった。カテゴリを一次条件にして
+   * skill context なしでも実用的な復旧手順を出す。
+   * feature / domain / api は従来どおり /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);
+    }
+    // カテゴリ不明時は skill context だけが手掛かり
+    return callerSkill === "quick-implementor";
+  }
+
+  /**
+   * WI-349: ブロック理由に判定根拠を明示する。
+   *
+   * - 判定対象は「今回の書き込み対象パス」だけであり、ワークツリー上の未コミット変更は
+   *   一切含まれない。この誤解が「無関係な変更のせいでブロックされている」という
+   *   誤った原因究明を招いていた（issue #41 症状②）。
+   * - アクティブな Full Mode session がありながら不許可だった場合は、その理由
+   *   （unit 不一致 / category 不一致 / 期限切れ 等）を提示する。これがないと
+   *   「session begin せよ」と案内されながら session は既に有効、という最悪の混乱になる。
+   */
+  private static appendJudgmentContextLines(
+    lines: string[],
+    sessionResult: FullModeSessionQueryResult | undefined,
+  ): void {
+    lines.push("判定対象: 今回の書き込み対象パスのみです（ワークツリー上の他の未コミット変更は判定に含まれません）。");
+    if (!HandlePreToolUseUseCase.isSessionActiveButRejected(sessionResult)) {
+      return;
+    }
+    const workItemId = sessionResult?.workItemId ?? "<unknown>";
+    const unit = sessionResult?.unit ?? "<unknown>";
+    const expiresAt = sessionResult?.expiresAt ?? "<unknown>";
+    lines.push(`アクティブな Full Mode session: ${workItemId} (unit=${unit}, expiresAt=${expiresAt})`);
+    lines.push(`session が書き込みを許可しなかった理由: ${sessionResult?.reason ?? "<unknown>"}`);
+  }
+
+  private static isSessionActiveButRejected(sessionResult: FullModeSessionQueryResult | undefined): boolean {
+    return sessionResult !== undefined && sessionResult.active && !sessionResult.allowed;
+  }
+
   private static appendGuidanceLines(lines: string[], guidance: ErrorGuidance | null, unitId?: string): void {
     if (guidance === null) return;
     if (guidance.scaffoldCommand !== null) {
@@ -377,10 +437,25 @@ export class HandlePreToolUseUseCase {
       lines.push(`  scaffold: ${command}`);
     }
     if (guidance.templatePath !== null) {
-      lines.push(`  テンプレ: ${guidance.templatePath}`);
+      lines.push(`  構成リファレンス: ${HandlePreToolUseUseCase.describeStructureReference(guidance.templatePath)}`);
     }
   }
 
+  /**
+   * WI-356 (issue #29): 参照先が skill 定義（skills/<name>/SKILL.md）の場合、
+   * skills/ をユーザー repo に配置しない personal install 経路でも読めるよう
+   * stdout 経路（phasegate skills info）を併記する。
+   */
+  private static readonly SKILL_REFERENCE_PATTERN = /^skills\/([^/]+)\/SKILL\.md$/;
+
+  private static describeStructureReference(templatePath: string): string {
+    const skillMatch = HandlePreToolUseUseCase.SKILL_REFERENCE_PATTERN.exec(templatePath);
+    if (skillMatch === null) {
+      return templatePath;
+    }
+    return `${templatePath}（未配置なら: npx phasegate skills info ${skillMatch[1]}）`;
+  }
+
   private deriveUnitIdFromPaths(targetFilePaths: readonly string[]): string | undefined {
     const projectPaths = this.configQueryPort.getProjectPaths();
     for (const targetFilePath of targetFilePaths) {
@@ -419,8 +494,15 @@ export class HandlePreToolUseUseCase {
   }
 
   private static isUnderInception(targetFilePath: string, inceptionPath: string): boolean {
-    const normalizedTarget = targetFilePath.replaceAll("\\", "/").replace(/^\.\/+/, "").replace(/\/+/g, "/");
-    const normalizedBase = inceptionPath.replaceAll("\\", "/").replace(/^\.\/+/, "").replace(/\/+/g, "/").replace(/\/$/, "");
+    const normalizedTarget = targetFilePath
+      .replaceAll("\\", "/")
+      .replace(/^\.\/+/, "")
+      .replace(/\/+/g, "/");
+    const normalizedBase = inceptionPath
+      .replaceAll("\\", "/")
+      .replace(/^\.\/+/, "")
+      .replace(/\/+/g, "/")
+      .replace(/\/$/, "");
     return normalizedTarget === normalizedBase || normalizedTarget.startsWith(`${normalizedBase}/`);
   }
 
@@ -577,9 +659,7 @@ export class HandlePreToolUseUseCase {
     lines.push("");
     lines.push("修正方法:");
     lines.push("  1. cascade-updater を実行して product 文書を更新");
-    lines.push(
-      `  2. または手動で該当 product 文書に @${annotationKey} ${details?.storyId ?? "<WORK-ITEM-ID>"} を追加`,
-    );
+    lines.push(`  2. または手動で該当 product 文書に @${annotationKey} ${details?.storyId ?? "<WORK-ITEM-ID>"} を追加`);
     lines.push("");
     lines.push("参照: ADR-XXX");