phasegate 0.283.0 → 0.315.0

package/CHANGELOG.md

@@ -7,8 +7,24 @@ 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 の解決結果がプリセット定義と一致することも統合テストで固定。

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/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/package.json

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

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");
 

package/scripts/harness/agent-integration/domain/services/bash-write-target-extractor.ts

@@ -140,6 +140,28 @@ function getCommandName(tokens: Token[]): string | undefined {
   return undefined;
 }
 
+/** リダイレクト演算子の右辺を解釈し、fd 複製の場合は書き込み先なしとして扱う。 */
+function getRedirectTarget(tokens: Token[], redirectIndex: number): string | undefined {
+  const next = tokens[redirectIndex + 1];
+  if (next === undefined) return undefined;
+
+  if (next.quoted === 'none' && /^&\d+$/.test(next.value)) {
+    return undefined;
+  }
+
+  if (next.quoted === 'none' && next.value === '&') {
+    const afterAmpersand = tokens[redirectIndex + 2];
+    if (afterAmpersand === undefined) return undefined;
+    if (afterAmpersand.quoted === 'none' && /^\d+$/.test(afterAmpersand.value)) {
+      return undefined;
+    }
+    // `>& file` は csh 形式の実ファイル書き込みとして安全側で抽出する。
+    return afterAmpersand.value;
+  }
+
+  return next.value;
+}
+
 /**
  * 1 コマンド分のトークン列から書き込み先を抽出する。
  * リダイレクト先はコマンド種別によらず検出する (全コマンド共通)。
@@ -151,9 +173,9 @@ function extractFromSingleCommand(tokens: Token[]): string[] {
   for (let i = 0; i < tokens.length; i += 1) {
     const t = tokens[i];
     if (t.quoted === 'none' && (t.value === '>' || t.value === '>>' || t.value === '>|')) {
-      const next = tokens[i + 1];
-      if (next !== undefined) {
-        results.push(next.value);
+      const target = getRedirectTarget(tokens, i);
+      if (target !== undefined) {
+        results.push(target);
       }
     }
   }