phasegate 0.335.0 → 0.341.0

package/CHANGELOG.md

@@ -7,14 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.341.0] - 2026-09-20
+
+### Changed
+
+- **WI-220 — Hook and CLI runtime improvements** — Avoid unnecessary read-only/disabled hook work, preserve legacy hook settings, load CLI modules and schemas lazily, and distribute compiled runtime JavaScript through the tested runtime tarball. Improve child-process cleanup, interrupted configuration/reconcile recovery, dependency-scoped reflection diagnostics, and cascade/TDD traceability. <!-- @work-item-id WI-220 -->
+
+### Known limitations
+
+- WI-220 remains incomplete: the absolute 500ms/format-only fast-path target, full semantic impact classification, and the agent reading comparison acceptance criterion remain unmet. This release does not mark those requirements as satisfied. <!-- @work-item-id WI-220 -->
+
+## Previous unreleased notes
+
 ### Added
 
+- **WI-385 — Grok Build / Antigravity pre-edit integration** — PreToolUse now detects flat snake_case, flat camelCase, and nested `toolCall` payloads structurally, maps Grok and Antigravity write vocabularies into the existing gate, and renders runtime-specific deny JSON without changing Claude/Codex stdout contracts. Install/init/setup/doctor accept `grok`, `antigravity`, and `all` while preserving `both=claude+codex`; lifecycle management adds the Antigravity named hook map, Grok/Antigravity structural doctor checks, trust/CLI-only notices, and explicit L2 backstop guidance. <!-- @work-item-id WI-385 -->
+
 - **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-390 — GitHub #47–#50 の hook / doctor / Quick Mode / trust-root 修正** — Biome の JavaScript formatter を single quote に固定し、Claude PostToolUse analyze hook を raw Biome から project-wide `phasegate lint` へ統一。doctor は `core.hooksPath` と Husky v8/v9 shim の実効状態を検査する。配置場所を問わず `.md` / `.mdx` を docs に分類し、単一の不許可カテゴリは `CATEGORY_NOT_ALLOWED`、複数カテゴリは `MIXED_CHANGES` として区別する。config・baseline・Husky runtime・root agent instructions を `protectedFiles.exclude` で解除できない trust root に格上げし、config 不在／不正時も direct Write/Edit を遮断する。 <!-- @work-item-id WI-390 -->
+
 - **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 を解消済みに更新。

package/README.ja.md

@@ -83,7 +83,7 @@ claude
 
 - `phasegate.config.json` — 品質設定の Single Source of Truth
 - `skills/` — 29 の AIDLC スキル一式
-- `.claude/skills/` ・ `.codex/skills/` — agent 向けの skill symlink
+- `.claude/skills/` ・ `.codex/skills/` ・ `.agents/skills/` — agent 向けの skill symlink
 - `.claude/settings.json` — PreToolUse / PostToolUse / Stop hook
 - `.codex/hooks.json` — Codex CLI hooks 設定（`--agent codex|both` 時）
 - `docs/principles/*.md` — アーキテクチャ哲学・テスト規約（immutable）
@@ -134,7 +134,7 @@ npx phasegate install --personal --agent claude --apply
 | **作るファイル** | `.phasegate-local/phasegate.config.json`（ローカル専用 config）／ runtime から見えるローカル agent context（Claude は `.claude/CLAUDE.md`、Codex は root の `AGENTS.md` が不在または既に PhaseGate 管理下のときのみ `AGENTS.md`）／ `.claude/settings.json` + `.claude/skills/` または `.codex/hooks.json` + `.codex/skills/`（選択した agent の runtime artifact）／ `.git/hooks/pre-commit` + `.git/hooks/commit-msg`（ローカル git hook）／ `.phasegate-local/docs/`（設計原則文書コピー）／ `.phasegate/manifest.json` |
 | **既存 skills の扱い** | 個人用 skills directory がある場合は merge — bundled skills を refresh し、user 所有の skill は保持する |
 | **コミット漏れ対策** | `.git/info/exclude` にローカル専用 block を管理して、個人用ファイルが誤ってチームの commit に混ざらないようにする。commit 時の L2 防御は `.git/hooks/` で発火する |
-| **Codex hook flag** | user-level feature flag の有効化は手動アクションとして残る（`codex features enable hooks`） |
+| **Codex hook trust** | Codex CLI >= 0.124.0 では hooks は stable / default-on。`.codex/hooks.json` 更新後は `/hooks` で current definition hash を再 trust する |
 
 チーム所有の `AGENTS.md` が既に存在する場合、Codex の personal install はそれを変更せず、`doctor --personal --agent codex` が残りの context ステップを（`AGENTS.override.md` に隠すのではなく）報告します。Codex を併用する場合は `--agent codex` または `--agent both` を指定します。アンインストールは team install と同様に `npx phasegate uninstall --apply` を使えば manifest 経由でローカル成果物のみが除去されます。<!-- @work-item-id WI-207 --> <!-- @work-item-id WI-208 --> <!-- @work-item-id WI-209 --> <!-- @work-item-id WI-213 --> <!-- @work-item-id WI-215 -->
 
@@ -159,11 +159,22 @@ npx phasegate reconcile --apply
 ### Codex CLI を使う場合
 
 ```bash
-npx phasegate init --name my-project --agent codex --with-husky
-codex features enable hooks   # Codex 本体の feature flag を手動で有効化
+npx phasegate install --agent codex --with-husky --apply
+npx phasegate doctor --agent codex
 ```
 
-両方使う場合は `--agent both`。Codex のネイティブ `apply_patch` は現時点で事前 hook を発火しないため、pre-commit (L2) で commit 時にブロックします。Bash 経由の書き込みは実行前に止まります。詳細は [Codex Integration Guide](docs/guide/codex-integration.md) を参照。
+両方使う場合は `--agent both`。Codex CLI >= 0.124.0 ではネイティブ `apply_patch` の Update/Add/Delete も編集前 hook に入り、違反を hard block します。`.codex/hooks.json` 更新後は `/hooks` で definition hash を再 trust してください。pre-commit (L2) は backstop として維持します。詳細は [Codex Integration Guide](docs/guide/codex-integration.md) を参照。<!-- @work-item-id WI-384 -->
+
+### Grok Build / Antigravity CLI を使う場合
+
+```bash
+npx phasegate install --agent grok --apply
+npx phasegate doctor --agent grok
+npx phasegate install --agent antigravity --apply
+npx phasegate doctor --agent antigravity
+```
+
+Grok は hooks 対応の CLI 1.0.0 系（検証対象）が最低要件です。Claude compatibility scanner を使うため、Phasegate は `.claude/settings.json` と `.claude/skills` を管理し、二重発火する `.grok/hooks` は作りません。hook が静かに効かない場合は `grok inspect`、`/hooks`、`--trust` または `/hooks-trust` で load / trust を確認してください。Antigravity hooks は CLI v1.0.14 以降が最低要件で、Phasegate は `agy` 1.1.x で検証しています。`.agents/hooks.json` の named `phasegate-gate` と `.agents/skills` を使い、静かに効かない場合は `agy` の `/hooks` で load を確認します。編集前 hard block の対応範囲は `agy` CLI で、IDE / desktop の hook 発火は保証しません。その範囲では L2 pre-commit が主防御です。全 runtime は `--agent all`、従来の `both` は Claude + Codex のままです。詳細は [Grok guide](docs/guide/grok-integration.md) と [Antigravity guide](docs/guide/antigravity-integration.md) を参照してください。<!-- @work-item-id WI-385 -->
 
 ### アップデート
 
@@ -185,7 +196,7 @@ npx phasegate reconcile --apply
 | **5 層バリデーション (L0-L4)** | エディタ保存 → pre-commit → CI → 週次まで段階的に品質チェック |
 | **29 AIDLC スキル** | 要求定義 → ドメイン設計 → テスト設計 → TDD 実装をスキルとして提供 |
 | **Quick Mode** | バグ修正・docs・テスト追加など軽微変更ではゲートを緩和して高速化 |
-| **Claude Code / Codex Hooks** | Write/Edit/Bash 時に自動でゲートチェック・lint を実行 |
+| **複数 runtime hooks** | Claude Code / Codex / Grok Build / Antigravity CLI の payload を形状で判定し編集前 gate を実行 |
 | **HarnessError 形式** | 全エラーに ADR 参照 + 修正例が含まれ、AI が自己修正できる |
 | **Baseline (retrofit)** | 既存リポジトリ導入時、`baseline` snapshot に登録した既存ファイルは構造的に編集されるまで gate 対象外 |
 | **カスタム gate** | AIDLC 以外のプロジェクトでも schema-first など独自の前提条件を設定できる |
@@ -462,15 +473,15 @@ npx phasegate <command> [options]
 
 ### Codex CLI
 
-`init --agent codex` で `.codex/hooks.json` を配置。Codex のネイティブ `apply_patch` ツールは hook を発火しないため（[openai/codex#16732](https://github.com/openai/codex/issues/16732)）、ネイティブ経路は **pre-commit (L2)** で commit 時にブロックされます。
+`install --agent codex --apply` で `.codex/hooks.json` を配置します。Codex CLI >= 0.124.0 の native `apply_patch` payload を受理し、全 target を既存 gate へ合流させます。hook definition 更新後は `/hooks` で再 trust が必要です。<!-- @work-item-id WI-384 -->
 
 | 編集経路 | 事前 hard block | commit 時 block |
 |---|---|---|
 | Bash 書き込み（`sed -i`, `tee`, heredoc, `cat >`） | ✅ PreToolUse(Bash) | ✅ pre-commit |
 | Bash 経由 `apply_patch <<'PATCH'` | ✅ PreToolUse(Bash) | ✅ pre-commit |
-| Codex ネイティブ `apply_patch` | ❌ Codex 側の制約で hook 非発火 | ✅ pre-commit |
+| Codex ネイティブ `apply_patch` Update/Add/Delete | ✅ PreToolUse(apply_patch) | ✅ pre-commit |
 
-**推奨運用**: こまめに commit して pre-commit でネイティブ `apply_patch` 違反を早期に surface する。
+PostToolUse(apply_patch) は既存 lint 経路を実行します。ローカル hook が未 trust / skip の場合に備え、pre-commit と CI を backstop / authoritative re-check として残します。
 
 詳細: [Hooks Integration](docs/guide/hooks-integration.md) ・ [Codex Integration](docs/guide/codex-integration.md)
 
@@ -613,6 +624,8 @@ L3 Nyquist Validation の `requirement-test-matrix.json` は `phasegate:generate
 - [5-Layer Defense Model](docs/guide/layer-model.md) — L0-L4 詳細・HarnessError 形式
 - [Hooks Integration](docs/guide/hooks-integration.md) — Claude Code Hooks 設定
 - [Codex Integration](docs/guide/codex-integration.md) — Codex CLI セットアップ・カバレッジ
+- [Grok Integration](docs/guide/grok-integration.md) — Claude 互換 hook、payload 対応、trust 確認
+- [Antigravity Integration](docs/guide/antigravity-integration.md) — `agy` CLI named hook、payload 対応、IDE / desktop 境界
 - [Quick Mode vs Full Mode](docs/guide/quick-vs-full-mode.md) — `/story-implementor` vs `/quick-implementor`
 - [Retrofit Adoption Guide](docs/guide/retrofit-adoption.md) — 既存リポジトリへの段階的導入
 - [Preset Selection Guide](docs/guide/preset-selection.md) — 3 系統の preset 選定

package/README.md

@@ -84,7 +84,7 @@ claude
 
 - `phasegate.config.json` as the quality settings source of truth
 - `skills/` with 29 AIDLC skills
-- `.claude/skills` and/or `.codex/skills` links for agent use
+- `.claude/skills`, `.codex/skills`, and/or `.agents/skills` links for agent use
 - `.claude/settings.json` and/or `.codex/hooks.json` hook configuration
 - `docs/principles/*.md` and `docs/folder_management_rules.md`
 - `.husky/pre-commit`, `.husky/commit-msg`, and `.husky/pre-push` when `--with-husky` is passed
@@ -143,11 +143,22 @@ npx phasegate reconcile --apply
 ### Codex CLI
 
 ```bash
-npx phasegate init --name my-project --agent codex --with-husky
-codex features enable hooks
+npx phasegate install --agent codex --with-husky --apply
+npx phasegate doctor --agent codex
 ```
 
-Use `--agent both` for projects that use Claude Code and Codex together. Codex native `apply_patch` currently cannot be intercepted before the edit, so those violations are caught at pre-commit; Bash-based writes are blocked before execution.
+Use `--agent both` for projects that use Claude Code and Codex together. Codex CLI >= 0.124.0 emits hooks for native `apply_patch`, so Update/Add/Delete targets are hard-blocked before editing when they violate Phasegate rules. After `.codex/hooks.json` changes, open `/hooks` and trust the current definition hash. L2 pre-commit remains the backstop. <!-- @work-item-id WI-384 -->
+
+### Grok Build / Antigravity CLI
+
+```bash
+npx phasegate install --agent grok --apply
+npx phasegate doctor --agent grok
+npx phasegate install --agent antigravity --apply
+npx phasegate doctor --agent antigravity
+```
+
+Grok requires the hook-capable CLI 1.0.0 series used for verification. It uses its Claude-compatible scanner: Phasegate manages `.claude/settings.json`, exposes skills through `.claude/skills`, and does not create a duplicate `.grok/hooks` source. If the hook is silently inactive, verify loading and trust with `grok inspect`, `/hooks`, and `--trust` or `/hooks-trust`. Antigravity hooks require CLI v1.0.14 or later; Phasegate verification targets `agy` 1.1.x. Antigravity uses the named `phasegate-gate` definition in `.agents/hooks.json` and project skills in `.agents/skills`; if it is silently inactive, confirm the loaded definition with `agy` `/hooks`. Pre-edit hard blocking is supported for the `agy` CLI surface; IDE/desktop hook execution is not guaranteed, so L2 pre-commit remains the primary backstop there. Use `--agent all` for every runtime; `both` intentionally remains Claude + Codex. See the [Grok](docs/guide/grok-integration.md) and [Antigravity](docs/guide/antigravity-integration.md) guides. <!-- @work-item-id WI-385 -->
 
 ### Update
 
@@ -169,7 +180,7 @@ npx phasegate reconcile --apply
 | **5-layer validation** | Runs checks from agent runtime and editor time through pre-commit, CI, and scheduled audits |
 | **29 AIDLC skills** | Guides AI agents through product architecture, story writing, domain design, test design, and TDD implementation |
 | **Quick Mode** | Keeps bugfixes, docs, test-only changes, and config changes lightweight while preserving traceability |
-| **Claude Code / Codex hooks** | Runs checks around Write/Edit/Bash operations and session boundaries |
+| **Multi-runtime hooks** | Runs shape-based pre-edit checks for Claude Code, Codex, Grok Build, and Antigravity CLI |
 | **Agent-readable HarnessError output** | Gives AI agents the reason, missing artifacts, references, and examples needed to self-correct |
 | **Retrofit baseline** | Lets existing repositories adopt Phasegate gradually by grandfathering unchanged files |
 | **Configurable gates** | Supports AIDLC defaults or custom gates such as schema-first API development |
@@ -181,7 +192,7 @@ npx phasegate reconcile --apply
 
 ```
 +------------------------------------------------------------------+
-|  L0  AGENT RUNTIME HOOKS   Claude Code / Codex hooks             |
+|  L0  AGENT RUNTIME HOOKS   Claude / Codex / Grok / Antigravity   |
 |  PreToolUse (Write/Edit/Bash block + guide), PostToolUse         |
 |  (auto lint/format), Stop (ReentryGuard + complete-check),       |
 |  SessionStart, UserPromptSubmit. Plus Husky .husky/pre-commit    |
@@ -551,28 +562,26 @@ Phasegate also integrates with [OpenAI Codex CLI](https://developers.openai.com/
 ### Quick setup
 
 ```bash
-# 1. Initialize the project for Codex (creates project-local files such as .codex/hooks.json and .codex/skills)
-npx phasegate init --name my-project --agent codex --with-husky
+# 1. Install project-local Codex hooks and the pre-commit backstop
+npx phasegate install --agent codex --with-husky --apply
 
-# 2. Enable the Codex CLI feature flag manually on your machine
-codex features enable hooks
+# 2. Verify wiring, then trust the current definition in Codex /hooks
+npx phasegate doctor --agent codex
 ```
 
 For dual-agent projects (Claude + Codex), use `--agent both`.
 
-`init` sets up files inside the project. The Codex CLI user-level hooks feature remains an explicit manual step.
-
-### Coverage and known limitation
+Codex CLI >= 0.124.0 is required. Hooks are stable and default-on, but a changed non-managed command hook must be re-trusted by definition hash through `/hooks`.
 
-Because Codex's native `apply_patch` tool is routed through an internal `ApplyPatchHandler` and does not emit hook events ([openai/codex#16732](https://github.com/openai/codex/issues/16732)), pre-edit hard-block coverage is limited to Bash-based writes. Native `apply_patch` violations are caught at commit time by the pre-commit layer.
+### Coverage
 
 | Path | Pre-edit hard block | Commit-time block |
 |---|---|---|
 | Shell writes (`sed -i`, `tee`, heredoc, `cat >`) | ✅ `PreToolUse(Bash)` | ✅ pre-commit |
 | Bash-invoked `apply_patch <<'PATCH'` | ✅ `PreToolUse(Bash)` (via `BashWriteTargetExtractor`) | ✅ pre-commit |
-| Native `apply_patch` tool call | ❌ not intercepted by Codex today | ✅ pre-commit |
+| Native `apply_patch` Update/Add/Delete | ✅ `PreToolUse(apply_patch)` | ✅ pre-commit |
 
-**Recommended mitigation**: commit frequently (e.g., after each logical change) so native `apply_patch` violations surface quickly. See the full guide for details.
+`PostToolUse(apply_patch)` runs the existing lint path. L2 pre-commit remains enabled as a backstop for untrusted or skipped local hooks. See the [Codex integration guide](docs/guide/codex-integration.md) for trust troubleshooting. <!-- @work-item-id WI-384 -->
 
 ---
 
@@ -588,7 +597,7 @@ README keeps only the entry points most users need. The full public/compatibilit
 
 | Command | Description |
 |---|---|
-| `init --name <name>` | Legacy-compatible bootstrap for new projects. Supports `--skills <core\|all>`, `--agent <claude\|codex\|both>`, `--with-husky`, `--with-ci`, and `--yes`. Prefer `install` when the project may already have hooks, scripts, or CI files. |
+| `init --name <name>` | Legacy-compatible bootstrap for new projects. Supports `--skills <core\|all>`, `--agent <claude\|codex\|both\|grok\|antigravity\|all>`, `--with-husky`, `--with-ci`, and `--yes`. Prefer `install` when the project may already have hooks, scripts, or CI files. |
 | `install --dry-run` / `--apply` | Idempotently merge PhaseGate into the current project, preserve existing user content, add package scripts/devDependency, and write `.phasegate/manifest.json`. Use `--force` only for managed-file replacement. |
 | `doctor` | Diagnose silent or partial installations (`--json`, `--strict`, `--report-out <path>`). `--report-out` is an explicit file path, not `reporting.outputDir`. |
 | `uninstall --dry-run` / `--apply` | Remove PhaseGate-managed files and managed blocks using `.phasegate/manifest.json`, preserving user content. |
@@ -652,6 +661,8 @@ Detailed guides are available under `docs/guide/`:
 - [Contract Traceability](docs/guide/contract-traceability.md) -- `L2-015` public contract, boundary, error, state, and observation annotations
 - [Hooks Integration](docs/guide/hooks-integration.md) -- Claude Code Hooks setup and behavior
 - [Codex Integration](docs/guide/codex-integration.md) -- Codex CLI setup, coverage matrix, and native `apply_patch` limitation
+- [Grok Integration](docs/guide/grok-integration.md) -- Claude-compatible hook setup, payload mapping, and trust checks
+- [Antigravity Integration](docs/guide/antigravity-integration.md) -- `agy` CLI named hooks, payload mapping, and IDE/desktop boundary
 - [Quick Mode vs Full Mode](docs/guide/quick-vs-full-mode.md) -- When to use `/story-implementor` vs `/quick-implementor`, with decision flow and case studies
 - [Retrofit Adoption Guide](docs/guide/retrofit-adoption.md) -- Onboard an existing project without getting blocked: `init` → `baseline` → `scaffold-design` in 4 steps
 

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

@@ -9,6 +9,7 @@ date: 2026-07-18
 
 <!-- @work-item-id WI-330 -->
 <!-- @work-item-id WI-333 -->
+<!-- @work-item-id WI-390 -->
 
 ## Context
 
@@ -41,7 +42,7 @@ config の解決順は project 直下 `phasegate.config.json` → `.phasegate-lo
 
 | 操作クラス ＼ 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 |
+| **config 自身への編集**（hook 経由 Write/Edit） | × protected-file block（WI-390 / ADR-041） | × protected-file block。bootstrap は managed CLI または人間の hook 外編集 | × protected-file block。hook / doctor 自体は fail-open | × protected-file block。doctor 完走後、人間が hook 外で修復 |
 | **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（警告付き） |
@@ -53,7 +54,7 @@ config の解決順は project 直下 `phasegate.config.json` → `.phasegate-lo
 - **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`）。
+- **config 自身の non-excludable protection（WI-390）**: `phasegate.config.json` と personal config は ADR-041 の trust root pattern であり、`protectedFiles.exclude` より先に合成される。hook / doctor の config load fail-open と direct mutation authorization を分離し、agent Write/Edit は全 config 状態で block する。
 - **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. 設計原則
@@ -61,6 +62,7 @@ config の解決順は project 直下 `phasegate.config.json` → `.phasegate-lo
 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. **config load fail-open は config mutation の許可を意味しない。** hook / doctor は missing / invalid config でも完走するが、agent hook 経由の config direct Write/Edit は ADR-041 の protected trust root として常に block する。復旧は managed command、または人間の hook 外編集で行う。 <!-- @work-item-id WI-390 -->
 
 ### 4. 既知ギャップ（本 ADR は現状を固定し、修正は別 WI）
 
@@ -76,3 +78,4 @@ config の解決順は project 直下 `phasegate.config.json` → `.phasegate-lo
 - 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 完全解消）。
+- WI-390 / ADR-041 で、自己修復経路を「direct agent mutation」から managed CLI / human out-of-band edit へ移し、config 自身を non-excludable protected trust root に改訂した。hook / doctor 起動と無関係操作の fail-open は維持する。

package/docs/ADR/041-non-excludable-agent-trust-roots.md

@@ -0,0 +1,68 @@
+---
+adr_id: "041"
+title: "agent hook の防御 trust root は config から除外不能にする"
+status: Accepted
+date: 2026-08-10
+---
+
+# agent hook の防御 trust root は config から除外不能にする
+
+<!-- @work-item-id WI-390 -->
+
+## Context
+
+GitHub #50 の Grok 実機 smoke で、pre-tool-use hook は `.husky/*` 書き込みを正しく block したが、
+block 文面に含まれた `phasegate.config.json protectedFiles.exclude` の手順を agent が実行し、再試行を成功させた。
+既存 `ProtectedFileList` は config 自身を既定保護せず、すべての default pattern を同じ `exclude` で削除できる。
+したがって gate の authorization input を gate 対象 agent 自身が書き換えられる循環が成立する。
+
+ADR-039 は authorization を hook が観測・検証できる state に限定したが、観測対象 config の保全境界は未定義だった。
+ADR-038 は自己修復デッドロック回避のため config direct Write を全状態で fail-open としたが、その後
+`install` / `init` / `setup:agent` / `config:plan --apply` という managed command が整備され、direct agent mutation を
+唯一の recovery path とする必要はなくなった。
+
+## Decision
+
+### 1. trust root patterns を config から除外不能にする
+
+次の path は `protectedFiles.exclude` より上位の non-excludable set とする。
+
+- project / personal `phasegate.config.json`
+- `.phasegate/baseline.json`
+- `.husky/**`
+- root agent instruction (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`)
+
+通常の formatter / compiler / package files と user additional patterns は従来どおり exclude 可能とする。
+
+### 2. config direct Write/Edit は config 状態を問わず block する
+
+valid / missing / invalid-json / invalid-schema のいずれでも、agent hook 経由の config direct mutation は
+path-based protected-file block とする。diff の「緩和方向」判定は採らない。before content の欠落、partial Edit、
+encoding、複数 path mutation により agent-controlled diff を authorization 根拠にできないためである。
+
+### 3. recovery path を managed command と human out-of-band edit に分離する
+
+- supported intent: `phasegate config:plan --intent ... --dry-run/--apply`
+- bootstrap: `phasegate install|init|setup:agent ... --apply`
+- invalid-schema や未対応 intent: 人間が agent hook 外で review して編集
+
+hook / doctor 自体の config load fail-open と無関係操作の継続は ADR-038 のまま維持する。
+
+### 4. block message に解除レシピを出さない
+
+stderr は managed route と documentation / human review を案内し、具体的な `protectedFiles.exclude` pattern を
+出力しない。security control の解除方法は agent-facing error contract に含めない。
+
+## Consequences
+
+- agent が hook の文面を実行して同一 session 内で防御を解除する経路は閉じる。
+- 既存 config が trust root を exclude していても新 version では無視される。
+- agent による arbitrary config editing はできなくなる。managed intent がない変更は人間の明示操作が必要になる。
+- ADR-038 の config 自身への編集行を改訂し、missing/invalid 状態の fail-open は hook 起動と無関係操作に限定する。
+- Markdown を一般 docs 分類しても root agent instructions は protected 境界で先に止まる。
+
+## Alternatives
+
+1. **緩和方向の JSON diff だけ block** — partial edits と invalid config で正しく比較できず、判定不能が新たな bypass になる。
+2. **block 後に confirmation token を要求** — agent が自己申告できない observable state の設計と lifecycle が必要で、本 WI の managed command より複雑。
+3. **message だけ変更** — config 自身が writable なため agent がソースや schema から同じ bypass を発見でき、trust boundary は直らない。

package/docs/folder_management_rules.md

@@ -101,7 +101,16 @@ legacy_id: ISSUE-XXX | US-XXX | H{NN}-{NN}             # 任意: 移行用エイ
 source: github#123 | slack | internal                   # 任意: 外部報告源
 ---
 ```
-
+<!-- @work-item-id WI-220 -->
+
+  `depends_on` はWI間の直接依存宣言です。フェーズ設定の
+  `dependsOn` とは別の項目です。
+  - 明示的な `[]` は「依存なし」、未記載は「不明」とします。
+  - 既存WIへの一括追記は行いません。
+  - 依存情報が不正・不足している場合、部分的な依存集合だけで必要な反映検査を省きません。
+  - 依存宣言自体は、設計内容の反映や承認の証明ではありません。
+  - 既存の通常metadata検査は変更せず、依存チェックの警告／明示選択した強制化経路で追加診断します。
+  
 ### 3.3 type による要求成果物の段階化
 
 WI の重さに応じて、生成必須の成果物が変わります。

package/docs/guide/antigravity-integration.md

@@ -0,0 +1,26 @@
+# Google Antigravity CLI Integration
+
+<!-- @work-item-id WI-385 -->
+
+Phasegate manages a named `phasegate-gate` definition in `.agents/hooks.json`. User-owned named definitions are preserved; install and reconcile replace only the Phasegate-owned key, and uninstall removes only that key from a merged file.
+
+Minimum supported runtime: Antigravity CLI v1.0.14, where hooks are available; Phasegate verification targets `agy` 1.1.x. If the gate appears silently inactive, open `agy`, run `/hooks`, and confirm `phasegate-gate` is loaded. Project skills are exposed through `.agents/skills`, which Phasegate links to the shared `skills/` catalog.
+
+## Setup
+
+```bash
+npx phasegate install --agent antigravity --with-husky --apply
+npx phasegate doctor --agent antigravity
+```
+
+The PreToolUse regular expression covers `write_to_file`, `replace_file_content`, `multi_replace_file_content`, and `run_command`, invoking `npx phasegate hook pre-tool-use` with a 30-second timeout. Nested `toolCall.name` / `toolCall.args` payloads accept defensive path candidates (`TargetFile`, `targetFile`, `target_file`, `filePath`, `file_path`, `path`), content candidates, and command candidates (`CommandLine`, `command`, `Command`). These candidate keys are compatibility inputs, not claims that every runtime/version has been verified. Missing targets or commands fail closed.
+
+## Result contract
+
+- Deny writes only documented top-level `decision: "deny"` and `reason` fields to stdout, writes the reason to stderr, and exits 2.
+- Allow exits 0 with empty stdout and does not override permission.
+- Workspace cwd uses `workspacePaths[0]`, falling back to the hook process cwd.
+
+## Supported surface and residual risk
+
+Pre-edit hard blocking is supported for the terminal `agy` CLI surface. Antigravity IDE/desktop hook execution is not guaranteed and is not advertised as protected; L2 pre-commit is the primary defense there. The exact args keys across releases, the meaning of exit code alone, and timeout/crash failure semantics remain unverified runtime behavior. Keep L2 pre-commit and CI enabled and inspect loaded hooks with `/hooks`.

package/docs/guide/cli-reference.md

@@ -22,12 +22,12 @@ Command names in this document are split into three surfaces:
 
 | Command | Description |
 |---|---|
-| `init --name <name>` | Legacy-compatible bootstrap for new projects: deploy skills, generate config, and optionally add hooks/CI. Options: `--preset <full\|standard\|minimal\|custom>`, `--skills <core\|all>`, `--agent <claude\|codex\|both>`, `--workflow <standard\|strict>`, `--language <language>`, `--with-husky`, `--with-ci`, `--yes`. `--language` writes `project.languages: ["<language>"]`; omitted language keeps the TypeScript-compatible default. <!-- @work-item-id WI-212 --> |
-| `install --dry-run` / `--apply` | Idempotently merge PhaseGate into an existing project, preserve user content, add package scripts/devDependency, create selected `AGENTS.md` / `CLAUDE.md` managed sections, and write `.phasegate/manifest.json`. `--agent <claude\|codex\|both>`, `--skills <core\|all>`, and `--workflow <standard\|strict>` affect rendered agent context; `--force` replaces managed targets after backup. |
-| `doctor` | Diagnose silent or partial installations and report repair hints (`--json`, `--strict`, `--agent <claude\|codex\|both>`, `--report-out <path>`). `--agent` defaults to `both`; single-agent scopes keep shared targets applicable and mark the other agent's findings as not applicable. `--report-out` writes exactly to the supplied path, not to `reporting.outputDir`. |
+| `init --name <name>` | Legacy-compatible bootstrap for new projects: deploy skills, generate config, and optionally add hooks/CI. Options: `--preset <full\|standard\|minimal\|custom>`, `--skills <core\|all>`, `--agent <claude\|codex\|both\|grok\|antigravity\|all>`, `--workflow <standard\|strict>`, `--language <language>`, `--with-husky`, `--with-ci`, `--yes`. `--language` writes `project.languages: ["<language>"]`; omitted language keeps the TypeScript-compatible default. <!-- @work-item-id WI-212, WI-385 --> |
+| `install --dry-run` / `--apply` | Idempotently merge PhaseGate into an existing project, preserve user content, add package scripts/devDependency, create selected context/hooks, and write `.phasegate/manifest.json`. `--agent <claude\|codex\|both\|grok\|antigravity\|all>` selects runtime targets; `both` remains Claude + Codex and `all` selects every supported runtime. `--force` replaces managed targets after backup. <!-- @work-item-id WI-385 --> |
+| `doctor` | Diagnose silent or partial installations and report repair hints (`--json`, `--strict`, `--agent <claude\|codex\|both\|grok\|antigravity\|all>`, `--report-out <path>`). Grok scope checks compatible matcher/timeout and emits trust guidance; Antigravity scope checks named schema/matcher/timeout and emits the CLI-only boundary. <!-- @work-item-id WI-385 --> |
 | `uninstall --dry-run` / `--apply` | Remove PhaseGate-managed files and managed blocks using `.phasegate/manifest.json`; `--force` handles managed conflict cases. |
 | `reconcile --dry-run` / `--apply` | Update PhaseGate-managed files to current package templates and refresh manifest hashes; `--force` allows managed-file replacement with backup. |
-| `setup:agent` | Agent-readable setup planner and optional apply path. Options: `--intent <minimal\|recommended\|strict\|ci-only\|agent-hooks\|retrofit>`, `--agent <claude\|codex\|both>`, `--workflow <standard\|strict>`, `--with-husky`, `--with-ci`, `--dry-run`, `--apply`, `--json`. <!-- @work-item-id WI-172 --> |
+| `setup:agent` | Agent-readable setup planner and optional apply path. Options: `--intent <minimal\|recommended\|strict\|ci-only\|agent-hooks\|retrofit>`, `--agent <claude\|codex\|both\|grok\|antigravity\|all>`, `--workflow <standard\|strict>`, `--with-husky`, `--with-ci`, `--dry-run`, `--apply`, `--json`. <!-- @work-item-id WI-172, WI-385 --> |
 | `config:plan` | Agent-readable configuration change planner. Options: `--intent <l4-strict\|codex-hooks\|ci-fail-on-warning\|baseline-reset\|quick-mode-strict\|quick-mode-relax\|retrofit-bootstrap\|planning-mode-relax>`, `--dry-run`, `--apply`, `--json`. <!-- @work-item-id WI-173 --> <!-- @work-item-id WI-201 --> <!-- @work-item-id WI-204 --> |
 | `session begin` / `session end` | Hook-visible Full Mode session manager. Use `session begin --mode full --unit <unit> --work-item <WI-XXX> --reason <text> --duration <ttl>` before implementation that must touch Quick Mode disallowed categories, and `session end --work-item <WI-XXX>` after completion. <!-- @work-item-id WI-206 --> |
 | `update-skills` | Compatibility alias for `reconcile`; use `reconcile` for new automation. |
@@ -39,6 +39,8 @@ Command names in this document are split into three surfaces:
 
 ### Setup JSON and report outputs
 
+`config:plan` does not initialize or reconstruct a missing/unreadable/malformed configuration. For unreadable or malformed input, config-changing previews report `configPatch.applicability: "blocked"`. Missing input retains the legacy preview (`before: null`, `applicability: "applicable"`, partial patch), with `phasegate install --dry-run` listed first; this preview is not permission to create a partial configuration. In all three cases, `--apply` refuses with exit 1 without changing files. For damaged JSON, an authorized operator should restore a known-good copy or repair the JSON before retrying; do not repeatedly attempt protected direct writes. Valid config updates retain a byte-preserving backup. Existing schema-validation failures still exit 2. <!-- @work-item-id WI-220 -->
+
 <!-- @work-item-id WI-158 -->
 
 Setup lifecycle commands support JSON for automation where shown by help: `install --json`, `reconcile --json`, `uninstall --json`, and `doctor --json`. `doctor --agent claude --json` and `doctor --agent codex --json` include `scope` and `scopedOutFindings` so agents can distinguish selected-agent readiness from full-install diagnostics. Scoped-out findings suppress immediate repair guidance with `repairHint: null`, `suggestedSkill: null`, `currentScopeRepairTarget: false`, `repairHintApplicability: "only-if-agent-selected"`, and `repairModeApplicability: "only-if-agent-selected"`; applicable `findings[]` use `currentScopeRepairTarget: true` with applicable repair fields. `doctor --report-out <path>` persists the doctor JSON payload to that exact path. Relative paths are resolved from the project root; absolute paths are used as-is. <!-- @work-item-id WI-178, WI-179, WI-180 -->
@@ -67,6 +69,14 @@ This is separate from `reporting.outputDir`. The configured report directory is
 
 ### `check-change-category` の使い方
 
+<!-- @work-item-id WI-220 -->
+
+任意の `--risk-snapshots snapshots.json` は既存分類とは別に `riskAdvice` を追加する。入力は `[{"filePath":"src/foo.ts","beforeContent":"...","afterContent":"..."}]`（内容はstringまたはnull）。filePathは `--paths` と完全一致させる。未指定時の出力・処理は従来どおり。指定しても `fullModeRequired` と `--fail-on-full-required` の終了コードは変えない。
+
+助言は `module-surface-change`（明示されたmodule宣言の差分）、`behavior-review`（宣言不変だが本文の意味は要確認）、`unknown`（情報不足・未対応）、`no-content-change`（提供された同文snapshotのみ）のいずれか。構文比較対象は明示型付きexport関数・interface・typeと、型が明示されたclass method/property/constructor。classの本文・property初期値は宣言比較から分離する。decorator、accessor、型推論、default引数、再export、宣言ファイル、create/delete等の未対応構文は不明になる。内部adapterであることや業務上の同値性をpathだけから認定しない。
+
+snapshotは呼出元の比較資料であり、現在のファイル・上位承認との一致を検証した証拠ではない。出力のbeforeHash/afterHashで比較内容を特定し、実revisionと照合する。契約差分候補は上位契約と利用者への影響、本文変更は認可・不変条件・保存形式を確認する。不明は自動許可・追加の強制拒否のどちらにも変換しない。助言機能だけで意味リスク判定が完成したとは扱わない。
+
 ISSUE-006 Story A で導入。Quick Mode で取り扱おうとしている変更が
 `quickMode.fullModeRequiredWhen` のいずれかをトリガーするか事前に確認したいときに使う。
 
@@ -374,7 +384,7 @@ The following are binary subcommands (`npx phasegate <command>`). Do not assume
 | `phasegate:check-phase` | `--unit <unitId>` `--json` | Current phase for a unit |
 | `phasegate:ci-check` | `--json` | Full CI check (L2-L4; disabled L4 is reported as skipped) |
 | `phasegate:detect-drift` | `--json` | Design-code drift report |
-| `phasegate:lint` | `--target <path>` `--json` | Lint via harness-api |
+| `phasegate:lint` | `--target <path>` (repeatable) `--json` | Analyze the full graph; restrict reported diagnostics to targets |
 | `phasegate:complete-check` | `--json` | L2-L4 full check |
 | `phasegate:impact-analysis` | `<storyId>` `--json` | Story impact analysis |
 | `phasegate:generate-matrix` | `--requirements <path>` `--tests <path>` `--out <path>` `--json` | Generate the requirement-test matrix |
@@ -490,12 +500,18 @@ ISSUE-005 P3-10 で明確化された境界:
 
 | Command | Options | Description |
 |---|---|---|
-| `skill:execute-tdd-cycle` | `--unit` `--story` `--desc` `--phase RED\|GREEN\|REFACTOR` `--passed` | Run TDD cycle |
+| `skill:execute-tdd-cycle` | `--unit` `--story` `--desc` `--phase RED\|GREEN\|REFACTOR` `--passed` `--configured-validation` (optional) | Validate commit readiness and commit staged changes |
 | `skill:check-coverage` | `--story <storyId>` `--json` | Coverage check |
 | `skill:collect-lessons` | `--story <storyId>` `--sources <paths>` `--write-artifact` | Collect agent lessons |
-| `skill:apply-cascade-update` | `--story <storyId>` `--dry-run` | Cascade update to upstream docs |
+| `skill:apply-cascade-update` | `--story <storyId>` `--dry-run` | Append traceability tags only; does not perform semantic design review. Counts changed files (planned changes in dry-run), not already-tagged files. |
 | `skill:validate-structure` | `--file <path>` `--json` | Validate skill structure |
 
+`skill:apply-cascade-update --story WI-220` writes `@work-item-id WI-220`; legacy story IDs keep `@story-id`. Existing legacy annotations remain readable and unchanged. IDs are matched exactly, including comma/space-separated lists. Repeated target paths are processed once per invocation, including failed reads; fix the reported cause before explicitly retrying. JS/TS source annotations are comments so tagging does not invalidate source syntax. This command still performs tag updates only, not semantic design review. <!-- @work-item-id WI-220 -->
+
+`skill:execute-tdd-cycle` does not run tests: `--passed` is the caller's assertion that tests passed. Run the relevant tests first. The command requires `REFACTOR` and `--passed`, runs its validation gates, and invokes a normal Git commit without bypassing hooks. With `--story WI-220` (or another `WI-<number>`), the commit includes a `Work-Item` trailer; legacy story IDs retain their existing subject without an inferred WI mapping.
+
+By default, the TDD command preserves its legacy L1/L2/L3 validation profile, including warning-as-blocking behavior. Existing settings previously ignored by this command do not silently introduce new blockers after an upgrade. To explicitly adopt the resolved L1/architecture and L2/L3 settings, use `--configured-validation`. In that profile, coverage thresholds and enabled World checks can add required findings; L2/L3 warnings follow `validate.failOnWarning`, while L1 warnings still block. Neither profile adds L4, runs tests on behalf of `--passed`, or bypasses Git hooks. The selected profile is printed. Review configuration and run the required checks before selecting the configured profile. <!-- @work-item-id WI-220 -->
+
 ---
 
 ## CI/CD
@@ -557,3 +573,7 @@ phasegate validate --layer L3
 ```
 
 Use `--json` to inspect `missingTests`, `orphanTests`, preserved references, and intent coverage.
+## Consumer skill selection
+
+<!-- @work-item-id WI-223 -->
+`init --skills consumer` and `install --skills consumer --dry-run` select 27 bundled skills, excluding Phasegate's own release-publisher and skill-creator. Apply install explicitly with `--apply`. The existing core/all sets and default all remain supported. Reconcile preserves the recorded set independently for shared/personal skill roots. No automatic deletion or migration of existing skills occurs when selecting a smaller set.