phasegate 0.335.0 → 0.341.0

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

@@ -1,5 +1,29 @@
 # Configuration
 
+## Work-item dependency declarations
+
+<!-- @work-item-id WI-220 -->
+
+A WI description may declare direct dependencies in its frontmatter:
+
+```yaml
+depends_on: [WI-123, WI-124]
+```
+
+A block list of WI IDs is also supported. An explicit `depends_on: []` means no declared dependencies; an omitted field means unknown, not an empty dependency set. Do not add empty declarations to old WIs without reviewing their dependencies. This is separate from phase configuration's `dependsOn` and is not evidence of semantic design approval.
+
+The dependency-specific reader diagnoses malformed lists, duplicate keys and invalid WI IDs. The existing metadata reader retains its previous behavior; adding this declaration does not itself enable a new blocking gate.
+
+For implementation writes permitted by a valid Full Mode session, the candidate runtime checks the session WI and its declared transitive dependencies and prints advisory reflection warnings to stderr. Existing session permission and exit 0 are retained, including when dependency information is incomplete or unreadable. Inception/product edits remain outside this additional check; `storyReflection.enabled: false` disables it. An omitted dependency declaration is reported as unverified, not silently interpreted as no dependencies.
+
+The session advisory uses `paths.inceptionDocs` and `paths.designDocs` consistently for dependency discovery, design artifacts, reflection mappings, and legacy aliases. Existing mapping templates retain their canonical `docs/inception/` and `docs/product/construction/` prefixes; this session path resolves those prefixes to the configured roots. Product mappings outside construction, such as `docs/product/units/`, are unchanged. Invalid roots are reported as unverified rather than falling back to default directories. Older non-session reflection calls retain their previous behavior.
+
+This checks configured reflection annotations, not semantic approval. A `fix` item needs reflection in at least one configured product candidate per affected unit; choosing the semantically relevant categories remains a review responsibility. Missing required design artifacts are reported as unverified in advisory mode.
+
+For the authenticated Full Mode session path, v3 configuration may explicitly select `agentIntegration.preToolUse.dependencyReflection: "enforce"` (or `"advisory"`, the default behavior when omitted). No setting is added automatically. Enforce mode blocks known missing reflection and required artifacts; `storyReflection.enabled: false` still disables this check. Incomplete dependency information falls back to the existing Unit-wide reflection check and reports an unverified warning, even if that fallback passes. Read/configuration failures retain the existing session permission with an unverified warning. This is not a fail-closed semantic approval system.
+
+Repair the indicated inception and product documents separately, obtain any required upstream decisions, and retry the implementation operation. WI inception Markdown design repair is no longer subjected to downstream implementation gates; protected-file checks, source-root overlaps, existing shared-plan/description gates, product gates, and implementation paths remain enforced. Do not treat adding a tag alone as design approval. Standard-gate CLI tests cover both unreflected existing product documents and missing product documents followed by repair and resumption.
+
 ## phasegate.config.json
 
 Place at project root. Generated by `npx phasegate init`.
@@ -666,9 +690,11 @@ Introduced in ISSUE-007 Wave 1 (v0.65.0) and wired into the pre-tool-use hook by
 
 Generate or refresh the snapshot with `npx phasegate baseline` (`--dry-run` to inspect, `--force` to overwrite, `--paths <glob,glob,...>` to scope, `--json` for CI-friendly output). See the [Baseline section in CLI Reference](cli-reference.md#baseline-retrofit-grandfather) for details.
 
-#### `agentIntegration` (Stop hook strict mode)
+#### `agentIntegration` (Hook controls)
+
+Controls agent-side hook behavior. In v3 configuration, optional `preToolUse.enabled` and `postToolUse.enabled` boolean values override the legacy `harnesses.agentLessonCollection` and `harnesses.cascadeUpdate` mappings respectively. When omitted, each legacy value is preserved (default `true` when that legacy key is also absent). No existing config is rewritten automatically. These controls do not remove protected-file or trust-root enforcement. <!-- @work-item-id WI-220 -->
 
-Controls how phasegate's agent-side hooks integrate with Claude Code. Currently only `stopHook.enforce` is exposed.
+The independent keys require a version whose v3 schema supports them. Do not add them while older schema readers are still in use. Before downgrading, restore the configuration saved before adding these keys. There is currently no `config:plan` intent for these fields: use a human-reviewed, out-of-agent-hook edit under the trust-root policy rather than asking the agent to rewrite its own protection configuration.
 
 ```jsonc
 {

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)
@@ -59,7 +82,7 @@ This separation is intentional:
 - **Post = "is what was written valid?"** — concerns the resulting code's quality.
 - **Stop = "is the session ready to end?"** — concerns the cumulative state across the session.
 
-If you expect L1 lint (e.g., missing `@unit` annotation) to **block** a Write before it happens, that is by design **not** the case. The PreToolUse hook intentionally does not run lint, because lint requires the resulting file content (which only exists after the write). Lint violations surface as **PostToolUse** decision JSON (`decision: "block"`) and trigger Claude Code to retry.
+The PreToolUse hook does not run lint, because lint requires the resulting file content. The packaged `phasegate hook post-tool-use` command reports lint failures as advisory stderr with exit 0; it does not emit a block decision or request automatic retries. Separate shell hooks such as `analyze-errors-hook.sh` have their own output contract and are not changed by this packaged-command behavior. Commit and CI checks remain independent enforcement points.
 
 ### PreToolUse (before file write)
 - Enforces Phase Gate: blocks writing to source files if required design documents don't exist
@@ -91,6 +114,12 @@ Use /quick-implementor skill for version changes in package.json.
 - Runs Biome AST rules automatically
 - Provides immediate feedback on violations
 
+<!-- @work-item-id WI-220 -->
+
+The packaged command resolves direct-edit and complete patch targets relative to the payload's working directory, then runs lint from the project's configuration root. Multiple targets are retained. Analysis keeps the full dependency graph; only the reported diagnostics are scoped. Unknown shell commands and incomplete targets retain full lint rather than a potentially incomplete target list.
+
+Read/Glob/Grep and disabled hooks finish silently without starting lint. The lint subprocess has a five-second limit; timeout is reported as **validation incomplete**, not a pass. It does not automatically retry. Run `phasegate lint` explicitly when ready to complete validation. This timeout covers the child lint process, not the host runtime's own hook timeout.
+
 ### Stop (before session end)
 - Runs `phasegate:complete-check` (L2-L4 full validation)
 - The built-in Stop hook runs the packaged PhaseGate CLI command; downstream projects do not need to provide `scripts/harness/cli/complete-check.ts`.

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/setup-artifacts.md

@@ -14,7 +14,7 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 
 | Class | Examples | Owner | Lifecycle |
 |---|---|---|---|
-| Managed target | `phasegate.config.json`, `.claude/settings.json`, `.codex/hooks.json`, `CLAUDE.md`, `AGENTS.md`, `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`, `.github/workflows/phasegate-aidlc-gate.yml`, root `skills/` bundled skill bodies, `.claude/skills`, `.codex/skills`, `package.json` PhaseGate scripts/devDependency | PhaseGate managed block, real runtime artifact, shared skill body, or symlink plus user content | Created or merged by `install`, refreshed by `reconcile`, removed or reversed by `uninstall` |
+| Managed target | `phasegate.config.json`, `.claude/settings.json`, `.codex/hooks.json`, `.agents/hooks.json`, `CLAUDE.md`, `AGENTS.md`, `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`, `.github/workflows/phasegate-aidlc-gate.yml`, root `skills/` bundled skill bodies, `.claude/skills`, `.codex/skills`, `.agents/skills`, `package.json` PhaseGate scripts/devDependency | PhaseGate managed block, real runtime artifact, shared skill body, or symlink plus user content | Created or merged by `install`, refreshed by `reconcile`, removed or reversed by `uninstall` |
 | Configuration | `phasegate.config.json`, `package.json` | User owned, PhaseGate assisted | Created by `init` or project install when absent; `install` may merge scripts/devDependency into `package.json` |
 | Generated artifact | `.phasegate/manifest.json`, `.phasegate/backups/*`, `.phasegate/uninstalled-*.json`, `.phasegate/baseline.json` | PhaseGate | Written by lifecycle commands and validators; safe to regenerate only through the owning command |
 | Runtime state/report | `.phasegate/hook-skip-events.jsonl`, explicit `doctor --report-out <path>` output, `reports/regression/*`, resolved `reporting.outputDir` reports | PhaseGate command output | Produced while hooks, doctor, and validation commands run |
@@ -26,11 +26,11 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 
 `install --apply` and `reconcile --apply` manage only explicit targets. The current structured lifecycle covers:
 
-- Agent hook JSON: `.claude/settings.json`, `.codex/hooks.json`
+- Agent hook JSON: `.claude/settings.json`, `.codex/hooks.json`, `.agents/hooks.json`
 - Agent context files: `CLAUDE.md` and `AGENTS.md` managed sections. `AGENT.md` singular is not a PhaseGate managed target; treat it as user-owned content or migrate it manually. <!-- @work-item-id WI-174 -->
 - Husky scripts when requested: `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`
 - CI workflow when requested: `.github/workflows/phasegate-aidlc-gate.yml`
-- Agent skill links: `.claude/skills`, `.codex/skills`
+- Agent skill links: `.claude/skills`, `.codex/skills`, `.agents/skills`
 - Project shared bundled skills: selected `skills/<name>/` directories plus `skills/.harness-version`
 - Project config: `phasegate.config.json` when absent, so installed agent hooks have a discoverable runtime config
 - Package metadata: PhaseGate scripts and `devDependencies.phasegate` in `package.json`
@@ -48,7 +48,7 @@ If `.claude/*` or `.codex/*` already exists and is not a PhaseGate-managed perso
 
 Personal agent context is also placed only where the runtime will read it. Claude Code uses `.claude/CLAUDE.md`. Codex uses root `AGENTS.md` when PhaseGate can create or manage it locally; if a team `AGENTS.md` already exists, PhaseGate leaves it unchanged and doctor reports `codex-context-missing` instead of creating `AGENTS.override.md`. <!-- @work-item-id WI-215 -->
 
-Project install uses a different topology: selected bundled skills are deployed once to root `skills/`, and `.claude/skills` / `.codex/skills` point to that shared target. Existing root `skills/` is also a mergeable catalog: selected bundled skill directories are refreshed, selection-excluded or user-owned skills are not removed, and uninstall deletes only manifest-managed bundled skills plus metadata. If an older project install has the links but an empty `skills/` target, `phasegate doctor` reports the selected agent skill check and `phasegate reconcile --apply` repairs the shared skill bodies. <!-- @work-item-id WI-210 --> <!-- @work-item-id WI-216 -->
+Project install uses a different topology: selected bundled skills are deployed once to root `skills/`, and `.claude/skills` / `.codex/skills` / `.agents/skills` point to that shared target. Existing root `skills/` is also a mergeable catalog: selected bundled skill directories are refreshed, selection-excluded or user-owned skills are not removed, and uninstall deletes only manifest-managed bundled skills plus metadata. If an older project install has the links but an empty `skills/` target, `phasegate doctor` reports the selected agent skill check and `phasegate reconcile --apply` repairs the shared skill bodies. <!-- @work-item-id WI-210 --> <!-- @work-item-id WI-216 -->
 
 ## Doctor Findings
 

package/docs/guide/skills-overview.md

@@ -1,6 +1,9 @@
 # Skills Overview
 
-Phasegate provides 29 skills covering the full AIDLC (AI-Driven Development Life Cycle). `npx phasegate init` and project `npx phasegate install` deploy skill bodies to root `skills/` and expose them to enabled agents through `.claude/skills/` / `.codex/skills/` links. Personal install instead writes real local-only per-agent skill directories. <!-- @work-item-id WI-210 -->
+<!-- @work-item-id WI-223 -->
+For consumer projects, explicitly select `phasegate install --skills consumer --dry-run` (then `--apply` after review). This deploys 27 skills, excluding the Phasegate-maintainer-only `release-publisher` and `skill-creator`. Legacy `core` (7), `all` (29), and the omitted-option default (`all`) remain unchanged. `init` also accepts `consumer`. Reconcile preserves the set recorded in each skill root's `.harness-version`; missing/invalid/unknown metadata retains the legacy `all` fallback. Changing sets does not delete previously installed or user-owned skills. This is audience separation, not a claim of language-independent test tooling.
+
+Phasegate provides 29 skills covering the full AIDLC (AI-Driven Development Life Cycle). `npx phasegate init` and project `npx phasegate install` deploy skill bodies to root `skills/` and expose them to enabled agents through `.claude/skills/`, `.codex/skills/`, or `.agents/skills/` links. Personal install instead writes real local-only per-agent skill directories. <!-- @work-item-id WI-210 --> <!-- @work-item-id WI-385 -->
 
 Bundled `SKILL.md` files include `languages: [typescript]` frontmatter so PhaseGate can distinguish current TypeScript-oriented guidance from future language-specific skill variants. The metadata is advisory for applicability and does not prevent non-TypeScript projects from installing the catalog. <!-- @work-item-id WI-212 -->
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.335.0",
+  "version": "0.341.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",
@@ -47,6 +47,7 @@
     "phasegate": "bin/phasegate"
   },
   "scripts": {
+    "pack:runtime": "node scripts/pack-runtime.mjs",
     "phasegate": "npx tsx scripts/harness/main.ts",
     "phasegate:status": "npx tsx scripts/harness/main.ts phasegate:status",
     "phasegate:enable": "npx tsx scripts/harness/main.ts enable-feature",

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

@@ -26,7 +26,7 @@ export interface HandlePreToolUseOutput {
   phaseGateBlockers?: string[];
   storyReflectionBlockers?: string[];
   storyReflectionWarnings?: string[];
-  fullModeRejectionRule?: 'MIXED_CHANGES' | 'NEW_DOMAIN' | 'API_CONTRACT';
+  fullModeRejectionRule?: 'CATEGORY_NOT_ALLOWED' | 'MIXED_CHANGES' | 'NEW_DOMAIN' | 'API_CONTRACT';
   fullModeDominantCategory?: string;
   nextAction?: string;
   // Quick Mode が write を許可した際に dominant カテゴリを presentation 層に伝える。

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

@@ -0,0 +1,32 @@
+/**
+ * @unit agent-integration
+ * @layer application
+ * @work-item-id WI-385
+ */
+
+export type PayloadShape = "FLAT_SNAKE_CASE" | "FLAT_CAMEL_CASE" | "NESTED_TOOL_CALL";
+
+export type HookResponseProfile = "LEGACY_EXIT_ONLY" | "COMPATIBILITY_DENY_ENVELOPE" | "TOP_LEVEL_DENY_ENVELOPE";
+
+export interface CanonicalPreToolUseInput {
+  readonly path?: string;
+  readonly file_path?: string;
+  readonly paths?: readonly string[];
+  readonly command?: string;
+  readonly content?: string;
+  readonly old_string?: string;
+  readonly new_string?: string;
+}
+
+export interface NormalizedPreToolUseRequest {
+  readonly shape: PayloadShape;
+  readonly responseProfile: HookResponseProfile;
+  readonly cwd?: string;
+  readonly toolName: string;
+  readonly toolInput: CanonicalPreToolUseInput;
+  readonly inputTruncated: boolean;
+}
+
+export type PreToolUseNormalizationResult =
+  | { readonly ok: true; readonly request: NormalizedPreToolUseRequest }
+  | { readonly ok: false; readonly reason: string; readonly responseProfile?: HookResponseProfile };

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

@@ -1,6 +1,7 @@
 /**
  * @layer application
  * @unit agent-integration
+ * @work-item-id WI-220
  * @story H11-03
  *
  * HandlePostToolUseUseCase
@@ -39,6 +40,9 @@ export class HandlePostToolUseUseCase {
   }
 
   async execute(input: HandlePostToolUseInput): Promise<HandlePostToolUseOutput> {
+    if (input.affectedFilePaths.length === 0 && ['Read', 'Glob', 'Grep'].includes(input.toolName)) {
+      return { executed: false, skipReason: 'READ_ONLY' };
+    }
     const hookEvent = HookEvent.createPostToolUse(input.toolName, input.affectedFilePaths);
     const translationResult = await this.translator.translate(hookEvent);