phasegate 0.315.0 → 0.340.0

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

package/docs/guide/codex-integration.md

@@ -1,56 +1,32 @@
 # Codex CLI Integration
 
-Phasegate supports [OpenAI Codex CLI](https://developers.openai.com/codex/cli) through its hooks system, providing quality enforcement similar to the Claude Code experience. Because Codex's hook coverage differs from Claude's, defense is layered across hook-time and commit-time mechanisms.
+<!-- @work-item-id WI-384 -->
+
+Phasegate supports OpenAI Codex CLI through project-local command hooks. Codex rust-v0.124.0 or newer is required for native `apply_patch` coverage; hooks are stable and enabled by default in those releases.
 
 ## Setup
 
-### Quick setup (recommended)
+Install or reconcile the managed Codex artifacts:
 
 ```bash
-# 1. Initialize the project for Codex
-npx phasegate init --name my-project --agent codex --with-husky
-
-# 2. Enable the Codex CLI feature flag manually
-codex features enable hooks
-```
-
-For dual-agent projects (Claude + Codex), use `--agent both`.
-
-Responsibility split:
-
-- `phasegate init --agent codex` sets up **project-local artifacts** such as `phasegate.config.json`, `skills/`, `.codex/hooks.json`, and `.codex/skills`
-- `codex features enable hooks` updates the **Codex CLI user environment** and is intentionally left as a manual step
-
-### Manual setup
-
-Alternatively, set up Codex integration manually:
-
-#### 1. Enable hooks in Codex config
-
-Add to `~/.codex/config.toml` (or project `.codex/config.toml`):
-
-```toml
-[features]
-hooks = true
+npx phasegate install --agent codex --with-husky --apply
+npx phasegate doctor --agent codex
 ```
 
-#### 2. Install Phasegate hooks
+Use `--agent both` for projects shared with Claude Code. After `.codex/hooks.json` is created or changed, open `/hooks` in Codex and trust the current hook definition hash. Trust is stored outside the project and cannot be verified by Phasegate, so install, reconcile, and doctor print an operator notice.
 
-Copy the template into your project:
+The deprecated `phasegate init --agent codex` path remains available and prints the same minimum-version and re-trust guidance.
 
-```bash
-mkdir -p .codex
-cp node_modules/phasegate/templates/.codex/hooks.json .codex/hooks.json
-```
+### Manual configuration
 
-Or merge the following into your existing `.codex/hooks.json`:
+The canonical matcher is `Bash|apply_patch` for both events:
 
 ```json
 {
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Bash",
+        "matcher": "Bash|apply_patch",
         "hooks": [
           {
             "type": "command",
@@ -62,7 +38,7 @@ Or merge the following into your existing `.codex/hooks.json`:
     ],
     "PostToolUse": [
       {
-        "matcher": "Bash",
+        "matcher": "Bash|apply_patch",
         "hooks": [
           {
             "type": "command",
@@ -71,97 +47,58 @@ Or merge the following into your existing `.codex/hooks.json`:
           }
         ]
       }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "npx phasegate hook stop",
-            "statusMessage": "phasegate: completion check",
-            "timeout": 30
-          }
-        ]
-      }
     ]
   }
 }
 ```
 
-#### 3. Enable the pre-commit hook (critical for Codex)
-
-Because Codex's native `apply_patch` tool does not trigger hooks (see [Codex's limitation](#known-limitations)), the pre-commit layer is the primary defense for apply_patch-based edits. Install via husky:
-
-```bash
-npx phasegate init --with-husky  # or rerun init with this flag
-```
-
-## Defense Layers in Codex
-
-Compared to Claude Code, the enforcement timing is shifted for `apply_patch`-based edits. Coverage is equivalent overall but arrives at different stages.
+`Write` and `Edit` aliases are not included in the Codex-specific template. `apply_patch` is the canonical upstream tool name.
 
-| Concern | Claude Code | Codex |
-|---|---|---|
-| Bash-based file writes (`sed -i`, `tee`, heredoc) | `PreToolUse(Bash)` — hard block | `PreToolUse(Bash)` — hard block (same) |
-| Bash-invoked `apply_patch <<'PATCH'` | `PreToolUse(Bash)` — hard block | `PreToolUse(Bash)` — hard block (via Wave 1 `apply_patch` heredoc detection) |
-| **Native `apply_patch` tool calls** | `PreToolUse(Write\|Edit)` — hard block | ⚠️ **Not intercepted by hooks** — deferred to pre-commit |
-| Protected file writes | hook — immediate block | hook (Bash path) + pre-commit (commit path) |
-| Phase-gate enforcement | hook — immediate block | hook (Bash path) + pre-commit (commit path) |
-| Post-edit formatter / lint | `PostToolUse(Write\|Edit)` | `PostToolUse(Bash)` (partial) |
-| Session completion check | `Stop` hook | `Stop` hook (same) |
+## Coverage
 
-## Known Limitations
+| Edit path | Pre-edit hard block | Post-edit lint | Commit-time backstop |
+|---|---|---|---|
+| Shell writes (`sed -i`, `tee`, heredoc, `cat >`) | ✅ `PreToolUse(Bash)` | ✅ `PostToolUse(Bash)` | ✅ L2 pre-commit |
+| Bash-invoked `apply_patch <<'PATCH'` | ✅ parsed by `BashWriteTargetExtractor` | ✅ `PostToolUse(Bash)` | ✅ L2 pre-commit |
+| Native `apply_patch` Update/Add/Delete/Move to | ✅ `PreToolUse(apply_patch)` | ✅ `PostToolUse(apply_patch)` | ✅ L2 pre-commit |
 
-### Native `apply_patch` bypasses hooks
+For native patches, Phasegate reads raw patch text from `tool_input.command`, preserves directive order, and maps Update/Add/Delete to MODIFY/CREATE/DELETE. An Update followed by `*** Move to:` adds the source as MODIFY and the destination as CREATE. All targets join the existing protected-file, phase-gate, story-reflection, and Quick/Full Mode checks. One violating target denies the whole patch before editing.
 
-Per [OpenAI Codex docs](https://developers.openai.com/codex/hooks):
+PostToolUse intentionally does not parse patch targets again. It sends the event through the existing fast lint path.
 
-> "Currently `PreToolUse` only supports Bash tool interception."
+## Hook result contract
 
-Codex's native `apply_patch` tool is routed through a separate `ApplyPatchHandler` (see [openai/codex#16732](https://github.com/openai/codex/issues/16732)) that never emits hook events. As a result:
+- Deny: exit 2 with non-empty stderr.
+- Continue: exit 0 with empty stdout. Informational stderr is allowed.
+- Phasegate does not emit `permissionDecision: "ask"` because that path can fail open.
+- Phasegate does not emit an `allow` response without `updatedInput`.
+- Missing `tool_input.command` or a patch without `*** Begin Patch` fails closed.
 
-- Phasegate cannot pre-block edits made through native `apply_patch`
-- Violations surface at **pre-commit time** instead
-- Feedback is delayed relative to the Claude Code experience
+## Layered defense and residual risk
 
-**Mitigation**: commit frequently (e.g., after each logical unit of work). This shortens the window between violation and detection.
+Command hooks are a fast path. They can be skipped until the updated definition is trusted, and project code cannot inspect Codex's external trust store. Keep `.husky/pre-commit` and CI enabled: L2 remains the commit-time backstop and CI remains the authoritative re-check.
 
-### Bash-invoked `apply_patch` is fully covered
+Codex CLI 0.144.5 still exposes `unified_exec`, whose interception coverage is incomplete. Commands routed through an unobserved `unified_exec` path may bypass the edit-time hook; L2 pre-commit and CI remain the fallback for that residual risk.
 
-If the model invokes `apply_patch` via a Bash command (`apply_patch <<'PATCH' ... PATCH`), `PreToolUse(Bash)` fires and Phasegate's `BashWriteTargetExtractor` parses the heredoc to identify target files. This path is hard-blocked like any other Bash write.
-
-### Windows is not supported
-
-Codex hooks themselves do not support Windows. Phasegate follows the same constraint.
-
-### `unified_exec` interception is incomplete
-
-Codex documents that the newer `unified_exec` mechanism has incomplete interception. Commands routed through `unified_exec` may bypass hooks. Phasegate falls back to pre-commit for any such bypass.
-
-## Recommended Workflow
-
-1. **Enable all three layers**: Codex hooks + pre-commit hook + CI validation
-2. **Commit frequently** to catch native apply_patch violations early
-3. **Review the coverage matrix** above so you understand which edits are hard-blocked vs caught later
+Windows Codex hooks and Codex versions older than 0.124.0 are not supported by this integration.
 
 ## Troubleshooting
 
-### Hooks don't seem to run
-
-- Verify `hooks = true` is set in `config.toml`
-- Verify `.codex/hooks.json` is in the project root or `~/.codex/`
-- Run `codex --version` to ensure you're on a version that supports hooks
-
-### False positives on Bash hooks
+### Native apply_patch is not intercepted
 
-If non-write Bash commands are being blocked, check your `phasegate.config.json` `protectedFiles.exclude` list. You can also disable the `PostToolUse(Bash)` hook if lint runs too frequently.
+1. Run `codex --version` and confirm 0.124.0 or newer.
+2. Confirm both matchers in `.codex/hooks.json` are `Bash|apply_patch`.
+3. Run `npx phasegate doctor --agent codex`.
+4. Run `npx phasegate reconcile --apply` if doctor reports stale wiring.
+5. Open `/hooks` and trust the current definition hash.
 
-### Native apply_patch violations slipped through
+### A patch is denied
 
-This is expected behavior until [openai/codex#16732](https://github.com/openai/codex/issues/16732) is fixed. The pre-commit layer will catch these at commit time. If immediate feedback is critical, consider instructing the model (via project-level context) to prefer Bash-based edits over native `apply_patch`.
+Read stderr for the blocked path and recovery guidance. Full Mode changes require an active `phasegate session begin --mode full ...` authorization. Malformed or target-less native patches are denied rather than silently allowed.
 
-## See Also
+## See also
 
-- [Claude Code Hooks Integration](./hooks-integration.md)
-- [Phasegate Layer Model](./layer-model.md)
-- [Codex Hooks Documentation (official)](https://developers.openai.com/codex/hooks)
+- [Hooks Integration](./hooks-integration.md)
+- [Layer Model](./layer-model.md)
+- [OpenAI Codex hooks documentation](https://developers.openai.com/codex/hooks)
+- [openai/codex PR #18391](https://github.com/openai/codex/pull/18391)

package/docs/guide/configuration.md

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

package/docs/guide/grok-integration.md

@@ -0,0 +1,26 @@
+# Grok Build Integration
+
+<!-- @work-item-id WI-385 -->
+
+Phasegate uses Grok Build's Claude-compatible project hook scanner. It manages `.claude/settings.json` as the single hook source and deliberately does not create `.grok/hooks`, avoiding duplicate invocation.
+
+Minimum supported runtime: the hook-capable Grok CLI 1.0.0 series, which is the series used to verify this integration. If hooks appear to be silently inactive, run `grok inspect` and confirm the project hook is loaded and trusted in `/hooks`.
+
+## Setup
+
+```bash
+npx phasegate install --agent grok --with-husky --apply
+npx phasegate doctor --agent grok
+```
+
+The managed PreToolUse entries collectively match `Bash|Write|Edit|apply_patch`; each Phasegate command has an explicit 30-second timeout. Grok otherwise defaults a hook to 5 seconds and fails open when the hook times out or crashes, so the distributed timeout gives Phasegate enough time to inspect a write while L2 pre-commit remains the backstop. `run_terminal_command`, `search_replace`, `write`, and `apply_patch` camelCase payloads are normalized to the existing Bash/Write/Edit/patch pipeline. Grok truncates tool input at 128 KB; a truncated command or patch is denied because the full target set cannot be proven. A direct tool with a complete path can still be checked.
+
+## Result contract
+
+- Deny writes top-level `{ "decision": "deny", "reason": ... }` and Claude-compatible `hookSpecificOutput` to stdout, writes the reason to stderr, and exits 2.
+- Allow exits 0 with empty stdout and does not override permission.
+- Agent/model fields and the selected install target are not authorization inputs.
+
+## Trust and residual risk
+
+Project hooks can be skipped before trust is approved, and Phasegate cannot inspect Grok's external trust state. Run `grok inspect`, open `/hooks`, and approve with `--trust` or `/hooks-trust`. Keep L2 pre-commit and CI enabled because timeout/crash remains fail-open even with the explicit 30-second limit. The canonical path key for every future Grok `write` variant remains runtime-controlled; unknown supported-write shapes fail closed rather than silently allowing.

package/docs/guide/hooks-integration.md

@@ -6,17 +6,28 @@ Phasegate integrates natively with Claude Code through its hooks system. This en
 
 For new or existing projects, prefer `npx phasegate install --dry-run` followed by `npx phasegate install --apply` so existing hook JSON is merged instead of replaced. Manual editing is still possible, but then `phasegate doctor` may report missing managed targets until the expected PhaseGate entries, skill links, Husky scripts, CI workflow, and manifest are present. See [Setup Artifacts](setup-artifacts.md). <!-- @work-item-id WI-152 --> <!-- @work-item-id WI-169 -->
 
-Add the following to `.claude/settings.json`:
+### Manual hook configuration
+
+If structured install is unavailable, use the same packaged commands and timeout as the distributed `.claude/settings.json`:
 
 ```jsonc
 {
   "hooks": {
     "PreToolUse": [
+      {
+        "matcher": "Bash|apply_patch",
+        "hooks": [{
+          "type": "command",
+          "command": "npx phasegate hook pre-tool-use",
+          "timeout": 30
+        }]
+      },
       {
         "matcher": "Write|Edit",
         "hooks": [{
           "type": "command",
-          "command": "npx tsx scripts/harness/agent-integration/presentation/pre-tool-use-hook.ts"
+          "command": "npx phasegate hook pre-tool-use",
+          "timeout": 30
         }]
       }
     ],
@@ -25,7 +36,7 @@ Add the following to `.claude/settings.json`:
         "matcher": "Write|Edit",
         "hooks": [{
           "type": "command",
-          "command": "npx tsx scripts/harness/agent-integration/presentation/post-tool-use-hook.ts"
+          "command": "npx phasegate hook post-tool-use"
         }]
       }
     ],
@@ -34,7 +45,7 @@ Add the following to `.claude/settings.json`:
         "matcher": "",
         "hooks": [{
           "type": "command",
-          "command": "npx tsx scripts/harness/agent-integration/presentation/stop-hook.ts"
+          "command": "npx phasegate hook stop"
         }]
       }
     ]
@@ -42,6 +53,18 @@ Add the following to `.claude/settings.json`:
 }
 ```
 
+## Runtime coverage matrix
+
+<!-- @work-item-id WI-385 -->
+
+| Runtime payload | Managed source | Pre-edit deny output | Coverage boundary |
+|---|---|---|---|
+| Claude / Codex flat snake_case | `.claude/settings.json` / `.codex/hooks.json` | empty stdout, stderr, exit 2 | Existing contract unchanged |
+| Grok flat camelCase | Claude-compatible `.claude/settings.json` | top-level deny plus `hookSpecificOutput`, stderr, exit 2 | Trust must be checked with `grok inspect` / `/hooks` |
+| Antigravity nested `toolCall` | named `.agents/hooks.json` | top-level `decision` / `reason`, stderr, exit 2 | Hard block supported for `agy` CLI only |
+
+All allow paths keep stdout empty and do not override runtime permission. Malformed, ambiguous, truncated command/patch, or supported write tools without extractable targets fail closed. L2 pre-commit and CI remain the backstops for untrusted/skipped hooks, Antigravity IDE/desktop, and unverified timeout/crash behavior.
+
 ## Hook Behaviors
 
 ### Responsibility Separation (important)

package/docs/guide/installation.md

@@ -36,7 +36,7 @@ npm install
 npx phasegate init --name <project-name>
 ```
 
-This deploys 29 skills to `skills/`, creates the agent-facing skill links (for example `.claude/skills/` or `.codex/skills/`), and generates `phasegate.config.json`.
+This deploys 29 skills to `skills/`, creates the selected agent-facing skill links (`.claude/skills/`, `.codex/skills/`, or `.agents/skills/`), and generates `phasegate.config.json`.
 
 `init` is the legacy-compatible bootstrap path for new projects. It also runs the structured install path for the selected agent target so `CLAUDE.md` and/or `AGENTS.md` receive a PhaseGate managed section. Use `install` when the project may already have hooks, package scripts, or CI files that should be preserved. <!-- @work-item-id WI-174 -->
 
@@ -56,7 +56,9 @@ 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`. 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 -->
+`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 the selected `.claude/skills`, `.codex/skills`, and `.agents/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 -->
+
+Agent targets are `claude | codex | both | grok | antigravity | all`. `both` is backward-compatible Claude + Codex. Grok shares `.claude/settings.json` and `.claude/skills`, receives `AGENTS.md` without Claude-only `CLAUDE.md`, and does not receive `.grok/hooks`. Antigravity receives `.agents/hooks.json`, `.agents/skills`, and `AGENTS.md`. `all` installs Claude, Codex, and Antigravity surfaces, with Grok covered once by the Claude-compatible hook. <!-- @work-item-id WI-385 -->
 
 For personal evaluation inside a team-owned repository:
 

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

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