phasegate 0.44.0 → 0.63.0

package/README.ja.md

@@ -16,6 +16,7 @@ AIエージェント（Claude Code, Codex, Cursor, Copilot 等）が生成する
 - [AIDLC スキル](#aidlc-スキル)
 - [メタデータ規約](#メタデータ規約)
 - [Claude Code Hooks](#claude-code-hooks)
+- [Codex CLI Integration](#codex-cli-integration)
 - [カスタムフェーズゲート](#カスタムフェーズゲート)
 - [CI/CD テンプレート](#cicd-テンプレート)
 - [導入後のプロジェクト構造](#導入後のプロジェクト構造)
@@ -32,6 +33,7 @@ Phasegate は **「設計なしの実装を物理的に拒否する」** ツー
 | **5層バリデーション** | L1(AST) → L2(Pre-commit) → L3(CI) → L4(週次) の段階的品質チェック |
 | **28 AIDLC スキル** | 要求定義 → 設計 → テスト設計 → TDD実装の全フェーズをスキルとして提供 |
 | **Claude Code Hooks** | Write/Edit 時に自動でゲートチェック・Biome lint を実行 |
+| **Codex CLI Hooks** | Bash 書き込み時にフェーズゲート / 保護ファイル / Biome lint を実行（ネイティブ `apply_patch` は pre-commit でカバー） |
 | **Quick Mode** | バグ修正・ドキュメント修正など軽微な変更ではゲートを緩和して高速実行 |
 
 ---
@@ -576,6 +578,36 @@ export class ConfigSchema { ... }
 
 ---
 
+## Codex CLI Integration
+
+Phasegate は [OpenAI Codex CLI](https://developers.openai.com/codex/cli) でも同じ防御機構を提供します。CLI (`npx phasegate hook <event>`) 自体は agent-agnostic なため、Claude Code と Codex で同じコマンドが使えます。
+
+### セットアップ（2 ステップ）
+
+```bash
+# 1. Codex 向けに初期化（.codex/hooks.json を自動配置）
+npx phasegate init --name my-project --agent codex --with-husky
+
+# 2. Codex hooks フィーチャーフラグを有効化
+codex features enable codex_hooks
+```
+
+Claude + Codex 両対応プロジェクトは `--agent both` を指定してください。
+
+### カバレッジと既知の制約
+
+Codex のネイティブ `apply_patch` ツールは内部の `ApplyPatchHandler` 経由で実行され hook を発火しません（[openai/codex#16732](https://github.com/openai/codex/issues/16732)）。このため pre-edit hard block は Bash 経由の書き込みに限定され、ネイティブ `apply_patch` の違反は **pre-commit (L2)** で commit 時にブロックされます。
+
+| 編集経路 | 事前 hard block | commit 時 block |
+|---|---|---|
+| Bash 書き込み（`sed -i`, `tee`, heredoc, `cat >`） | ✅ `PreToolUse(Bash)` | ✅ pre-commit |
+| Bash 経由 `apply_patch <<'PATCH'` | ✅ `PreToolUse(Bash)`（`BashWriteTargetExtractor` で heredoc 解析） | ✅ pre-commit |
+| Codex ネイティブ `apply_patch` ツール | ❌ Codex 側の制約で hook 非発火 | ✅ pre-commit |
+
+**推奨運用**: こまめに commit することで、ネイティブ `apply_patch` 経由の違反を早期に surface できます。詳細は [docs/guide/codex-integration.md](docs/guide/codex-integration.md) を参照してください。
+
+---
+
 ## カスタムフェーズゲート
 
 デフォルトでは AIDLC フェーズ依存モデルが適用されますが、`gates[]` 配列で独自のゲートを定義できます。

package/README.md

@@ -26,6 +26,7 @@ Works with **Claude Code, Codex, Cursor, Copilot**, or any other AI agent.
 | **Phase Dependency Model** | Blocks implementation when required design documents are missing |
 | **Quick Mode** | Lightweight gate for bugfixes, docs, tests, and config changes |
 | **Claude Code Hooks** | Native PreToolUse / PostToolUse / Stop hook integration |
+| **Codex CLI Hooks** | `PreToolUse(Bash)` / `PostToolUse(Bash)` / `Stop` hook integration (native `apply_patch` falls back to pre-commit) |
 | **HarnessError Format** | Every error includes ADR references and fix examples for AI self-correction |
 | **Configurable Phase Gates** | Define custom gates with `gates[]` in config. Default uses AIDLC phase dependencies |
 | **Protected File Control** | Configure which files are protected from AI writes via `protectedFiles.exclude` |
@@ -253,6 +254,36 @@ All hook errors use the `HarnessError` format with ADR references and fix exampl
 
 ---
 
+## Codex CLI Integration
+
+Phasegate also integrates with [OpenAI Codex CLI](https://developers.openai.com/codex/cli) via hooks in `.codex/hooks.json`. The CLI itself is agent-agnostic, so the same `npx phasegate hook <event>` commands power both Claude Code and Codex.
+
+### Quick setup
+
+```bash
+# 1. Initialize with Codex agent support (auto-deploys .codex/hooks.json)
+npx phasegate init --name my-project --agent codex --with-husky
+
+# 2. Enable Codex hooks feature flag
+codex features enable codex_hooks
+```
+
+For dual-agent projects (Claude + Codex), use `--agent both`.
+
+### Coverage and known limitation
+
+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.
+
+| 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 |
+
+**Recommended mitigation**: commit frequently (e.g., after each logical change) so native `apply_patch` violations surface quickly. See the full guide for details.
+
+---
+
 ## CLI Reference
 
 ```bash
@@ -287,6 +318,8 @@ Detailed guides are available under `docs/guide/`:
 - [Skills Overview](docs/guide/skills-overview.md) -- 28 skills with AIDLC execution order
 - [5-Layer Defense Model](docs/guide/layer-model.md) -- L0-L4 layer details and HarnessError format
 - [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
+- [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
 
 Additional resources:
 

package/docs/guide/codex-integration.md

@@ -0,0 +1,162 @@
+# 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.
+
+## Setup
+
+### Quick setup (recommended)
+
+```bash
+# 1. Initialize with Codex agent support
+npx phasegate init --name my-project --agent codex --with-husky
+
+# 2. Enable Codex hooks feature flag
+codex features enable codex_hooks
+```
+
+For dual-agent projects (Claude + Codex), use `--agent both`.
+
+### 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]
+codex_hooks = true
+```
+
+#### 2. Install Phasegate hooks
+
+Copy the template into your project:
+
+```bash
+mkdir -p .codex
+cp node_modules/phasegate/templates/.codex/hooks.json .codex/hooks.json
+```
+
+Or merge the following into your existing `.codex/hooks.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx phasegate hook pre-tool-use",
+            "statusMessage": "phasegate: pre-tool-use check"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx phasegate hook post-tool-use",
+            "statusMessage": "phasegate: post-tool-use lint"
+          }
+        ]
+      }
+    ],
+    "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.
+
+| 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) |
+
+## Known Limitations
+
+### Native `apply_patch` bypasses hooks
+
+Per [OpenAI Codex docs](https://developers.openai.com/codex/hooks):
+
+> "Currently `PreToolUse` only supports Bash tool interception."
+
+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:
+
+- 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
+
+**Mitigation**: commit frequently (e.g., after each logical unit of work). This shortens the window between violation and detection.
+
+### Bash-invoked `apply_patch` is fully covered
+
+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
+
+## Troubleshooting
+
+### Hooks don't seem to run
+
+- Verify `codex_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
+
+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.
+
+### Native apply_patch violations slipped through
+
+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`.
+
+## 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)

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

@@ -0,0 +1,141 @@
+# Quick Mode vs Full Mode — Choosing the Right Flow
+
+Phasegate ships two implementation flows. Picking the wrong one is the most common source of friction: Full on trivial changes feels overkill, and Quick on contract-level changes defeats the whole point of the harness. This guide gives you a decision flow and worked examples so the choice is mechanical, not judgemental.
+
+> TL;DR — **Full Mode** (`/story-implementor`) is the default when a change touches API contracts, domain models, or new use cases. **Quick Mode** (`/quick-implementor`) is the escape hatch for bugfixes, docs, tests, and configuration tweaks. When in doubt, pick Full — a Full run on a small change is wasteful; a Quick run on a contract change is a latent bug.
+
+---
+
+## Decision Flow
+
+```mermaid
+flowchart TD
+    start([Change request]) --> q1{Does it add or rename<br/>a public API / Port / CLI flag?}
+    q1 -- yes --> full[Use Full Mode<br/>/story-implementor]
+    q1 -- no --> q2{Does it add or rename<br/>a Domain Entity / VO / Aggregate?}
+    q2 -- yes --> full
+    q2 -- no --> q3{Does it introduce<br/>a new UseCase / workflow?}
+    q3 -- yes --> full
+    q3 -- no --> q4{Is it bugfix / docs / test /<br/>config / refactor-only?}
+    q4 -- yes --> quick[Use Quick Mode<br/>/quick-implementor]
+    q4 -- no --> review[Stop and reconsider:<br/>scope may be unclear]
+    review --> start
+
+    style full fill:#f9d5e5,stroke:#c81d6c
+    style quick fill:#d6f5d6,stroke:#2f9e44
+    style review fill:#fff3bf,stroke:#f59f00
+```
+
+**Rule of thumb**: if the change alters something another module can *observe* (contract, schema, domain shape, new capability), go Full. If the change is invisible to consumers (internal fix, doc rewording, test addition, config bump), go Quick.
+
+---
+
+## Mode Comparison
+
+| Aspect | Full Mode (`/story-implementor`) | Quick Mode (`/quick-implementor`) |
+|---|---|---|
+| Prerequisite check | `/implementation-readiness-checker` required | Not required |
+| Phase Gate | Enforced — `logical_design.md` + `domain_model.md` must exist | Relaxed — design docs not required |
+| 2-Phase execution | Phase 1 (plan) → approval → Phase 2 (TDD) | Single phase |
+| TDD pyramid | Unit → IT → E2E in order | Fix + spot-test only |
+| Test design doc | Required before coding | Not required |
+| Coverage target | 90% or above | Existing coverage maintained |
+| L1 Biome rules | All 8 rules | **All 8 rules** |
+| L2 Pre-commit | phase-gate + metadata + test-quality | **metadata + test-quality** (phase-gate relaxed) |
+| L3 CI | security + performance + coverage + nyquist | security only |
+| L4 Scheduled | drift + consistency + dead-code | skipped |
+| Commit prefix | conventional (`feat:`, `fix:`, ...) | `[quick] ...` |
+
+Both modes keep **L1 in full strength** and **L2 metadata / test-quality** — `@unit` / `@layer` comments and AAA test structure are non-negotiable regardless of flow.
+
+---
+
+## Worked Examples
+
+### Full Mode candidates
+
+| Change | Why Full |
+|---|---|
+| Add a new `/phasegate inspect-unit` CLI command | New public surface — downstream users will depend on it |
+| Introduce a `ValidationReport` value object | New domain model; invariants must be designed up front |
+| Split a monolithic `PhaseGate` aggregate into two | Domain shape change — ripples into tests and consumers |
+| Add a new "scheduled-audit" UseCase | New workflow requires logical design + test design |
+| Change a Port interface (adapter contract) | Breaks existing adapters; contract change by definition |
+
+### Quick Mode candidates
+
+| Change | Why Quick |
+|---|---|
+| Fix a NaN in `calculate-coverage-usecase.ts` | Bugfix in existing code; no contract change |
+| Reword an error message in a Biome rule | User-visible but not semantically new |
+| Add a missing test case for an existing branch | Test-only; no production code touched |
+| Bump `vitest` to a patch version in `package.json` | Config / dependency change |
+| Rename a local helper variable across one file | Refactor with no external effect |
+| Update `docs/guide/*.md` for clarity | Pure documentation |
+| Add a new regex pattern to an existing `protectedFiles.exclude` list | Config tweak |
+
+### Ambiguous — default to Full
+
+| Change | Why not Quick |
+|---|---|
+| "Small" new feature, "just one function" | New behaviour is a contract addition; Quick would skip the test design gate |
+| Refactor that moves types between modules | Import graph changes can cascade; Full's L3 coverage/performance gates catch regressions |
+| "Tiny" adapter change that only adds one method | Port surface change — contract change even if code is short |
+
+---
+
+## Two-Tier Operation for Solo / Small Projects
+
+Running every change through Full AIDLC is genuinely heavy for one-person projects. A pragmatic pattern is the **core / periphery split**:
+
+- **Core scope** — the parts of the system where correctness, contracts, or domain invariants matter. Always Full.
+- **Periphery scope** — CLI glue, helper utilities, documentation, developer tooling, scheduled jobs that aren't in the hot path. Default to Quick, escalate to Full only when a change touches a contract.
+
+### Example partitioning (from the Phasegate repo itself)
+
+| Scope | Typical path | Default mode |
+|---|---|---|
+| Core | `scripts/harness/<unit>/domain/**`, Port interfaces, public CLI surface | Full |
+| Core | `docs/product/construction/<unit>/*.md` (contract docs) | Full |
+| Periphery | Internal helpers in `application/` that don't change ports | Quick-first, Full if contract impact emerges |
+| Periphery | `scripts/harness/presentation/` formatting / wording | Quick |
+| Periphery | `docs/guide/*`, `README.md`, `.claude/skills/*` tweaks | Quick |
+| Periphery | Version bumps, `phasegate.config.json` value edits | Quick |
+
+Codify the split in your head (or in a project CLAUDE.md note) — "`domain/**` is core, everything else starts Quick" is a healthy default for a single-maintainer project.
+
+---
+
+## Common Pitfalls
+
+1. **Using Quick to dodge a Phase Gate block.** If pre-tool-use blocks your write because `logical_design.md` is missing, the correct response is to create the design doc, not to re-launch in Quick Mode. Quick Mode is for changes that genuinely don't need design — not for bypassing the gate.
+2. **Declaring "bugfix" on what is really a new feature.** Adding a new branch to an existing function that handles a previously-unsupported case is a feature, not a bugfix. If consumers will see new behaviour they didn't see before, it is Full Mode material.
+3. **Drawing the core/periphery line too generously.** "Periphery" should mean "cannot affect contracts or domain invariants." If you're unsure, treat it as core for this change — you can re-classify later.
+4. **Batching a Full change and a Quick change in the same commit.** If a commit touches both a domain model and a doc typo, run Full — the `[quick]` prefix on a commit that also changes a domain file is misleading.
+5. **Using Quick for multi-Unit changes.** Cross-Unit work implies contract coordination; that is Full territory by definition.
+
+---
+
+## FAQ
+
+**Q. I have a one-line bugfix in `domain/`. Does "any file under `domain/`" auto-trigger Full?**
+Not mechanically — Quick Mode does not inspect paths. A one-line bugfix inside an existing domain method (fixing an off-by-one, null check, wrong comparator) is still Quick-eligible. What triggers Full is *adding or reshaping* a domain concept, not editing an existing one.
+
+**Q. What if Quick discovers the change is bigger than expected mid-flight?**
+Stop, commit nothing, and re-launch `/story-implementor`. Don't try to "finish in Quick" — you'll skip the design gate that would otherwise catch the scope creep.
+
+**Q. Can I disable Quick Mode entirely?**
+Yes — remove all entries from `quickMode.allowedCategories` in `phasegate.config.json`. All changes will route through Full Mode. This is reasonable for high-compliance projects.
+
+**Q. Can I add custom categories?**
+No. `allowedCategories` is a fixed enum (`bugfix`, `docs`, `test`, `config`). If your workflow needs a fifth category, that is evidence the change is probably Full Mode material.
+
+---
+
+## Related
+
+- [Skills Overview](skills-overview.md) — full catalogue of 28 skills
+- [Layer Model](layer-model.md) — L0 through L4 defence layers
+- [Configuration](configuration.md) — `quickMode` configuration reference
+- `.claude/skills/quick-implementor/SKILL.md` — the Quick Mode skill definition
+- `.claude/skills/story-implementor/SKILL.md` — the Full Mode skill definition

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.44.0",
+  "version": "0.63.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "Apache-2.0",

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

@@ -16,6 +16,8 @@
  *   - `touch`
  *   - 複合コマンド (`&&`, `;`, `||`) とパイプ (`|`) 分割
  *   - ダブル/シングルクォート対応
+ *   - `apply_patch` ヒアドキュメント (`*** Begin Patch` / `*** End Patch` ブロック内の
+ *     `*** Update|Add|Delete File: <path>` 行) — Codex CLI 対応 (ISSUE-013 Wave 1)
  */
 
 /** 引数トークン (値とクォート種別) */
@@ -219,6 +221,56 @@ function extractFromSingleCommand(tokens: Token[]): string[] {
   return results;
 }
 
+/** apply_patch ブロック境界マーカー (Begin/End) */
+const APPLY_PATCH_BEGIN_SOURCE = String.raw`\*\*\*\s+Begin\s+Patch`;
+const APPLY_PATCH_END_SOURCE = String.raw`\*\*\*\s+End\s+Patch`;
+/** ブロック内のファイル行: `*** (Update|Add|Delete) File: <path>` */
+const APPLY_PATCH_FILE_LINE_SOURCE = String.raw`^\s*\*\*\*\s+(?:Update|Add|Delete)\s+File:\s*(.+?)\s*$`;
+
+/**
+ * apply_patch ヒアドキュメント構文から対象ファイルパスを抽出する。
+ *
+ * Codex CLI 等が採用する unified-diff 風パッチフォーマット:
+ *   *** Begin Patch
+ *   *** Update File: <path>
+ *   *** Add File: <path>
+ *   *** Delete File: <path>
+ *   *** End Patch
+ *
+ * `*** End Patch` が欠けている場合は command 末尾までをブロックとして扱う
+ * (保護側に倒す — phase-gate の取りこぼしよりも誤検出のほうが許容される)。
+ */
+function extractApplyPatchTargets(command: string): string[] {
+  const beginGlobal = new RegExp(APPLY_PATCH_BEGIN_SOURCE, 'g');
+  const beginStarts: number[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = beginGlobal.exec(command)) !== null) {
+    beginStarts.push(m.index + m[0].length);
+  }
+  if (beginStarts.length === 0) return [];
+
+  const endGlobal = new RegExp(APPLY_PATCH_END_SOURCE, 'g');
+  const endStarts: number[] = [];
+  while ((m = endGlobal.exec(command)) !== null) {
+    endStarts.push(m.index);
+  }
+
+  const results: string[] = [];
+  for (let i = 0; i < beginStarts.length; i += 1) {
+    const start = beginStarts[i];
+    const nextBegin = i + 1 < beginStarts.length ? beginStarts[i + 1] : command.length;
+    const endInRange = endStarts.find((e) => e > start && e <= nextBegin);
+    const end = endInRange ?? nextBegin;
+    const body = command.slice(start, end);
+
+    const fileRegex = new RegExp(APPLY_PATCH_FILE_LINE_SOURCE, 'gm');
+    while ((m = fileRegex.exec(body)) !== null) {
+      results.push(m[1]);
+    }
+  }
+  return results;
+}
+
 export class BashWriteTargetExtractor {
   /**
    * Bash コマンド文字列から書き込み先ファイルパスを抽出する。
@@ -243,6 +295,14 @@ export class BashWriteTargetExtractor {
       }
     }
 
+    // apply_patch ヒアドキュメント対応 (ISSUE-013 Wave 1)
+    // 既存の token ベース抽出では heredoc body 内のマーカー行を拾えないため、
+    // raw command 文字列から独立にスキャンする。
+    const applyPatchTargets = extractApplyPatchTargets(command);
+    for (const p of applyPatchTargets) {
+      collected.push(p);
+    }
+
     // 重複除去 (挿入順保持)
     const seen = new Set<string>();
     const unique: string[] = [];