phasegate 0.283.0 → 0.335.0

package/docs/guide/troubleshooting.md

@@ -27,6 +27,43 @@ Each finding has a severity, a repair mode, and optional next-step fields.
 | `ci-workflow-missing` | `npx phasegate setup:agent --intent ci-only --with-ci --dry-run --json` |
 | agent context drift | `npx phasegate reconcile --dry-run` |
 
+## Phase Gate Blocked a Write and I Do Not Know What the Document Should Contain
+
+<!-- @work-item-id WI-356 -->
+
+Phase Gate blocks (`L2-001`, `FULL_MODE_REQUIRED`) mean a required inception or product design document is missing. Two things are needed: the file skeleton, and the section structure to fill in.
+
+**1. Generate the skeleton.** `scaffold-design` writes a placeholder document for the missing phase:
+
+```bash
+npx phasegate scaffold-design --unit <unit-id> --phase logical --dry-run
+npx phasegate scaffold-design --unit <unit-id> --phase logical --apply
+```
+
+Accepted `--phase` values: `logical`, `domain`, `uiux`, `unit-test`, `it-test`.
+
+**2. Read the section structure from the skill definition.** PhaseGate does not ship fill-in templates into your repo; the authoritative structure of every plan and inception artifact lives in the skill markdown that produces it. `install` / `init` copy these into `skills/` in your repository:
+
+| Document | Skill definition |
+|---|---|
+| product architecture / unit decomposition | `skills/product-architect/SKILL.md` |
+| story map | `skills/story-mapper/SKILL.md` |
+| story descriptions / acceptance criteria | `skills/story-writer/SKILL.md` |
+| unit plan | `skills/unit-designer/SKILL.md` |
+| `logical_design.md` | `skills/logical-designer/SKILL.md` |
+| `domain_model.md` | `skills/domain-designer/SKILL.md` |
+| UI/UX design | `skills/uiux-designer/SKILL.md` |
+| unit / IT / scenario test plans | `skills/unit-test-designer/SKILL.md`, `skills/it-test-designer/SKILL.md`, `skills/scenario-test-designer/SKILL.md` |
+
+If `skills/` is not present in your repository — the personal install path does not copy it — read the same content from PhaseGate's own package instead:
+
+```bash
+npx phasegate skills list
+npx phasegate skills info logical-designer
+```
+
+`skills info` prints the full SKILL.md to stdout, so it works from a sandboxed agent that cannot read `node_modules/`.
+
 ## Refused Managed Target
 
 If `install`, `reconcile`, or `uninstall` refuses a target, do not immediately force it. Inspect the diff and ask the agent to explain:

package/docs/templates/agent-context/CLAUDE.md.template.md

@@ -1,6 +1,6 @@
 # CLAUDE.md
 
-<!-- @work-item-id WI-174, WI-176, WI-177 -->
+<!-- @work-item-id WI-174, WI-176, WI-177, WI-331 -->
 
 <!-- phasegate:managed-section:start -->
 ## 必読ドキュメント
@@ -38,13 +38,13 @@ If `setup:agent --apply --json` or `install --apply --json` fails with a structu
 
 {{PHASEGATE_SKILLS}}
 
+## Agent Context Refresh
+
+Run `phasegate ci:auto-refresh-agent-context --dry-run` to preview updates and `phasegate ci:auto-refresh-agent-context --apply` to write AGENTS.md / CLAUDE.md.
+<!-- phasegate:managed-section:end -->
+
 ## User Section
 
 <!-- phasegate:user-section:start -->
 {{PHASEGATE_USER_SECTION}}
 <!-- phasegate:user-section:end -->
-
-## Agent Context Refresh
-
-Run `phasegate ci:auto-refresh-agent-context --dry-run` to preview updates and `phasegate ci:auto-refresh-agent-context --apply` to write AGENTS.md / CLAUDE.md.
-<!-- phasegate:managed-section:end -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.283.0",
+  "version": "0.335.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",
@@ -60,7 +60,7 @@
     "harness:check-phase": "pnpm phasegate:check-phase",
     "harness:check-ready": "pnpm phasegate:check-ready",
     "test": "vitest run --config scripts/harness/__tests__/vitest.config.forks.ts && vitest run --config scripts/harness/__tests__/vitest.config.ts",
-    "coverage": "node -e \"require('node:fs').rmSync('coverage',{recursive:true,force:true})\" && vitest run --config scripts/harness/__tests__/vitest.config.coverage.forks.ts --reporter=blob --outputFile=coverage/.blob/forks.json && vitest run --config scripts/harness/__tests__/vitest.config.coverage.ts --reporter=blob --outputFile=coverage/.blob/threads.json && vitest run --config scripts/harness/__tests__/vitest.config.coverage.ts --merge-reports=coverage/.blob",
+    "coverage": "node -e \"require('node:fs').rmSync('coverage',{recursive:true,force:true})\" && vitest run --config scripts/harness/__tests__/vitest.config.coverage.forks.ts --reporter=blob --reporter=default --outputFile.blob=coverage/.blob/forks.json && vitest run --config scripts/harness/__tests__/vitest.config.coverage.ts --reporter=blob --reporter=default --outputFile.blob=coverage/.blob/threads.json && vitest run --config scripts/harness/__tests__/vitest.config.coverage.ts --merge-reports=coverage/.blob",
     "ci": "npm run coverage && npm run test"
   },
   "dependencies": {

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

@@ -3,10 +3,14 @@
  * @unit agent-integration
  */
 
+/**
+ * WI-376 (ADR-039): 呼び出し元 skill 名を受け取るフィールドは持たない。
+ * 判定・案内の入力は hook が自ら観測・検証できる state（対象パス、変更カテゴリ、
+ * session marker、設計文書の存在、解決済み config 等）に限る。
+ */
 export interface HandlePreToolUseInput {
   toolName: string;
   targetFilePaths: string[];
-  callerSkill?: string;
   targetChanges?: {
     filePath: string;
     beforeContent?: string | null;

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

@@ -6,6 +6,9 @@
  * @work-item-id WI-202 / WI-204
  * @work-item-id WI-206
  * @work-item-id WI-214
+ * @work-item-id WI-349
+ * @work-item-id WI-354
+ * @work-item-id WI-376
  *
  * HandlePreToolUseUseCase
  * PreToolUse Hook処理のオーケストレーション
@@ -17,11 +20,11 @@ import type {
 } from "../../domain/ports/baseline-grandfather-query-port.js";
 import type { ConfigQueryPort } from "../../domain/ports/config-query-port.js";
 import type { ErrorGuidance, ErrorGuidanceQueryPort } from "../../domain/ports/error-guidance-query-port.js";
+import type { FullModeRequirementQueryPort } from "../../domain/ports/full-mode-requirement-query-port.js";
 import type {
   FullModeSessionQueryPort,
   FullModeSessionQueryResult,
 } from "../../domain/ports/full-mode-session-query-port.js";
-import type { FullModeRequirementQueryPort } from "../../domain/ports/full-mode-requirement-query-port.js";
 import type { PhaseGateQueryPort } from "../../domain/ports/phase-gate-query-port.js";
 import type { StoryReflectionQueryPort } from "../../domain/ports/story-reflection-query-port.js";
 import { AsyncHookToCliTranslator } from "../../domain/services/hook-to-cli-translator.js";
@@ -185,7 +188,7 @@ export class HandlePreToolUseUseCase {
               fullModeResult,
               guidance,
               unitIdForGuidance,
-              input.callerSkill,
+              sessionResult,
             );
           }
         } else {
@@ -281,22 +284,20 @@ export class HandlePreToolUseUseCase {
     },
     guidance: ErrorGuidance | null,
     unitId: string | undefined,
-    callerSkill?: string,
+    sessionResult?: FullModeSessionQueryResult,
   ): HandlePreToolUseOutput {
     const fp = blockedFilePath ?? "不明なファイル";
     if (result.dominantCategory === "config" && /(?:^|\/)phasegate\.config\.json$/.test(fp)) {
       const dryRunCommand = "phasegate config:plan --intent quick-mode-relax --dry-run --json";
       const applyCommand = "phasegate config:plan --intent quick-mode-relax --apply --json";
-      const lines = [
-        `Full mode 必須変更が検出されました: ${fp}`,
-        "カテゴリ: config",
-      ];
+      const lines = [`Full mode 必須変更が検出されました: ${fp}`, "カテゴリ: config"];
       if (result.rejectionRule) {
         lines.push(`判定ルール: ${result.rejectionRule}`);
       }
       if (result.rejectionReason) {
         lines.push(`理由: ${result.rejectionReason}`);
       }
+      HandlePreToolUseUseCase.appendJudgmentContextLines(lines, sessionResult);
       lines.push(`次のアクション: ${dryRunCommand} で差分を確認し、承認後に ${applyCommand} を実行してください。`);
 
       return {
@@ -309,22 +310,24 @@ export class HandlePreToolUseUseCase {
         nextAction: `${dryRunCommand} && ${applyCommand}`,
       };
     }
-    if (
-      callerSkill === "quick-implementor" &&
-      result.dominantCategory !== undefined &&
-      ["bugfix", "docs", "test", "config"].includes(result.dominantCategory)
-    ) {
+    if (HandlePreToolUseUseCase.shouldGuideQuickModeRelax(result.dominantCategory)) {
       const dryRunCommand = "phasegate config:plan --intent quick-mode-relax --dry-run --json";
       const applyCommand = "phasegate config:plan --intent quick-mode-relax --apply --json";
       const lines: string[] = [`Full mode 必須変更が検出されました: ${fp}`];
-      lines.push(`カテゴリ: ${result.dominantCategory}`);
+      if (result.dominantCategory) {
+        lines.push(`カテゴリ: ${result.dominantCategory}`);
+      }
       if (result.rejectionRule) {
         lines.push(`判定ルール: ${result.rejectionRule}`);
       }
       if (result.rejectionReason) {
         lines.push(`理由: ${result.rejectionReason}`);
       }
-      lines.push(`次のアクション: Quick Mode の許可カテゴリを確認してください。緩和する場合は ${dryRunCommand} で差分を確認し、承認後に ${applyCommand} を実行してください。`);
+      HandlePreToolUseUseCase.appendJudgmentContextLines(lines, sessionResult);
+      lines.push(
+        `次のアクション: Quick Mode の許可カテゴリを確認してください。緩和する場合は ${dryRunCommand} で差分を確認し、承認後に ${applyCommand} を実行してください。`,
+      );
+      lines.push(`  分類の確認: npx phasegate check-change-category --paths ${fp}`);
 
       return {
         shouldBlock: true,
@@ -346,9 +349,15 @@ export class HandlePreToolUseUseCase {
     if (result.rejectionReason) {
       lines.push(`理由: ${result.rejectionReason}`);
     }
+    HandlePreToolUseUseCase.appendJudgmentContextLines(lines, sessionResult);
     const suggestedSkill = guidance?.suggestedSkill ?? "/story-implementor";
     lines.push(`次のアクション: ${suggestedSkill} スキルを使用して設計フェーズから開始してください。`);
     if (unitId !== undefined && unitId !== "") {
+      if (HandlePreToolUseUseCase.isSessionActiveButRejected(sessionResult)) {
+        lines.push(
+          `  既存 session は上記理由で今回の書き込みに使えません。張り直す場合: phasegate session end --work-item ${sessionResult?.workItemId ?? "<WI-XXX>"} を実行してから下記を実行してください。`,
+        );
+      }
       lines.push(
         `  実装フェーズ開始時: phasegate session begin --mode full --unit ${unitId} --work-item <WI-XXX> --reason "<reason>" --duration 1h`,
       );
@@ -367,6 +376,59 @@ export class HandlePreToolUseUseCase {
     };
   }
 
+  /**
+   * Quick Mode スコープのカテゴリ（bugfix / docs / test / config）は quick-implementor で
+   * 完遂できる変更であり、遮断の実体は「allowedCategories が絞られている」ことである。
+   * ここで /story-implementor を案内すると、設計フェーズからやり直せという誤った指示になる。
+   *
+   * WI-354: 従来は callerSkill === "quick-implementor" を条件にしていたが、
+   * callerSkill を供給する producer（hook input の caller_skill / PHASEGATE_CALLER_SKILL）は
+   * 実運用で設定されず、この分岐は到達不能だった。カテゴリを一次条件にして
+   * skill context なしでも実用的な復旧手順を出す。
+   * feature / domain / api は従来どおり /story-implementor 誘導を維持する。
+   *
+   * WI-376 (ADR-039): 判定入力は hook が自ら観測できる state のみとする方針に従い、
+   * カテゴリ未確定時の callerSkill フォールバックを削除した。カテゴリが取れない場合は
+   * 一律 /story-implementor 誘導（従来のフォールバックも実運用では常にこの経路だった）。
+   */
+  private static readonly QUICK_MODE_SCOPE_CATEGORIES: readonly string[] = ["bugfix", "docs", "test", "config"];
+
+  private static shouldGuideQuickModeRelax(dominantCategory: string | undefined): boolean {
+    if (dominantCategory === undefined) {
+      return false;
+    }
+    return HandlePreToolUseUseCase.QUICK_MODE_SCOPE_CATEGORIES.includes(dominantCategory);
+  }
+
+  /**
+   * WI-349: ブロック理由に判定根拠を明示する。
+   *
+   * - 判定対象は「今回の書き込み対象パス」だけであり、ワークツリー上の未コミット変更は
+   *   一切含まれない。この誤解が「無関係な変更のせいでブロックされている」という
+   *   誤った原因究明を招いていた（issue #41 症状②）。
+   * - アクティブな Full Mode session がありながら不許可だった場合は、その理由
+   *   （unit 不一致 / category 不一致 / 期限切れ 等）を提示する。これがないと
+   *   「session begin せよ」と案内されながら session は既に有効、という最悪の混乱になる。
+   */
+  private static appendJudgmentContextLines(
+    lines: string[],
+    sessionResult: FullModeSessionQueryResult | undefined,
+  ): void {
+    lines.push("判定対象: 今回の書き込み対象パスのみです（ワークツリー上の他の未コミット変更は判定に含まれません）。");
+    if (!HandlePreToolUseUseCase.isSessionActiveButRejected(sessionResult)) {
+      return;
+    }
+    const workItemId = sessionResult?.workItemId ?? "<unknown>";
+    const unit = sessionResult?.unit ?? "<unknown>";
+    const expiresAt = sessionResult?.expiresAt ?? "<unknown>";
+    lines.push(`アクティブな Full Mode session: ${workItemId} (unit=${unit}, expiresAt=${expiresAt})`);
+    lines.push(`session が書き込みを許可しなかった理由: ${sessionResult?.reason ?? "<unknown>"}`);
+  }
+
+  private static isSessionActiveButRejected(sessionResult: FullModeSessionQueryResult | undefined): boolean {
+    return sessionResult !== undefined && sessionResult.active && !sessionResult.allowed;
+  }
+
   private static appendGuidanceLines(lines: string[], guidance: ErrorGuidance | null, unitId?: string): void {
     if (guidance === null) return;
     if (guidance.scaffoldCommand !== null) {
@@ -377,10 +439,25 @@ export class HandlePreToolUseUseCase {
       lines.push(`  scaffold: ${command}`);
     }
     if (guidance.templatePath !== null) {
-      lines.push(`  テンプレ: ${guidance.templatePath}`);
+      lines.push(`  構成リファレンス: ${HandlePreToolUseUseCase.describeStructureReference(guidance.templatePath)}`);
     }
   }
 
+  /**
+   * WI-356 (issue #29): 参照先が skill 定義（skills/<name>/SKILL.md）の場合、
+   * skills/ をユーザー repo に配置しない personal install 経路でも読めるよう
+   * stdout 経路（phasegate skills info）を併記する。
+   */
+  private static readonly SKILL_REFERENCE_PATTERN = /^skills\/([^/]+)\/SKILL\.md$/;
+
+  private static describeStructureReference(templatePath: string): string {
+    const skillMatch = HandlePreToolUseUseCase.SKILL_REFERENCE_PATTERN.exec(templatePath);
+    if (skillMatch === null) {
+      return templatePath;
+    }
+    return `${templatePath}（未配置なら: npx phasegate skills info ${skillMatch[1]}）`;
+  }
+
   private deriveUnitIdFromPaths(targetFilePaths: readonly string[]): string | undefined {
     const projectPaths = this.configQueryPort.getProjectPaths();
     for (const targetFilePath of targetFilePaths) {
@@ -419,8 +496,15 @@ export class HandlePreToolUseUseCase {
   }
 
   private static isUnderInception(targetFilePath: string, inceptionPath: string): boolean {
-    const normalizedTarget = targetFilePath.replaceAll("\\", "/").replace(/^\.\/+/, "").replace(/\/+/g, "/");
-    const normalizedBase = inceptionPath.replaceAll("\\", "/").replace(/^\.\/+/, "").replace(/\/+/g, "/").replace(/\/$/, "");
+    const normalizedTarget = targetFilePath
+      .replaceAll("\\", "/")
+      .replace(/^\.\/+/, "")
+      .replace(/\/+/g, "/");
+    const normalizedBase = inceptionPath
+      .replaceAll("\\", "/")
+      .replace(/^\.\/+/, "")
+      .replace(/\/+/g, "/")
+      .replace(/\/$/, "");
     return normalizedTarget === normalizedBase || normalizedTarget.startsWith(`${normalizedBase}/`);
   }
 
@@ -493,6 +577,12 @@ export class HandlePreToolUseUseCase {
       message: (fp) =>
         `保護ファイルへの書き込みがブロックされました: ${fp}\nClaude Code の設定変更は /update-config スキルを使用してください。`,
     },
+    {
+      // WI-363: .husky/ 配下は L0 runtime の実施点。Quick Mode でも書き換えさせない。
+      pattern: /(?:^|\/)\.husky\//,
+      message: (fp) =>
+        `保護ファイルへの書き込みがブロックされました: ${fp}\n.husky/ 配下は L0 runtime（pre-commit / commit-msg / pre-push）の実施点であり、Quick Mode でも変更できません。\n未導入 hook の配置は npx phasegate setup:agent --apply --with-husky を使用してください。\n意図的に手編集する場合は phasegate.config.json の protectedFiles.exclude に対象パターンを明示してください。`,
+    },
   ];
 
   private async buildProtectedFileBlockOutput(blockedFilePath: string | undefined): Promise<HandlePreToolUseOutput> {
@@ -577,9 +667,7 @@ export class HandlePreToolUseUseCase {
     lines.push("");
     lines.push("修正方法:");
     lines.push("  1. cascade-updater を実行して product 文書を更新");
-    lines.push(
-      `  2. または手動で該当 product 文書に @${annotationKey} ${details?.storyId ?? "<WORK-ITEM-ID>"} を追加`,
-    );
+    lines.push(`  2. または手動で該当 product 文書に @${annotationKey} ${details?.storyId ?? "<WORK-ITEM-ID>"} を追加`);
     lines.push("");
     lines.push("参照: ADR-XXX");
 

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

@@ -9,7 +9,8 @@
  *
  * 副作用なし・純粋関数相当。対応パターンは以下:
  *   - リダイレクト `>` / `>>` / `>|` (clobber)
- *   - heredoc (`<<EOF > path`)
+ *   - heredoc (`<<EOF > path`) — ヒアドキュメント**本文**はシェル構文解析の対象外
+ *     (本文中の `<...>` をリダイレクトと誤認しないため。WI-362)
  *   - `tee` / `tee -a`
  *   - `sed -i` / `sed -i ''` (BSD)
  *   - `cp` / `mv` (宛先のみ)
@@ -111,6 +112,191 @@ function tokenize(input: string): Token[] {
   return tokens;
 }
 
+/** ヒアドキュメント開始演算子で宣言された終端デリミタ */
+type HeredocDelimiter = {
+  /** クォート・エスケープを解除した終端語 */
+  readonly word: string;
+  /** `<<-` 形式か (終端行の先頭タブを無視する) */
+  readonly allowIndent: boolean;
+};
+
+/** デリミタ語の終端となる文字 (空白およびシェル演算子) */
+const DELIMITER_TERMINATORS = new Set([' ', '\t', ';', '&', '|', '<', '>', '(', ')']);
+
+/**
+ * 1 行から ヒアドキュメント開始演算子 (`<<WORD` / `<<-WORD` / `<<'WORD'`) を検出し、
+ * 宣言順に終端デリミタを返す。
+ *
+ * クォート状態を追跡し、クォート内の `<<` は演算子として扱わない
+ * (例: `echo "a << b" > out.txt` の `<<` はヒアドキュメントではない)。
+ * `$( ... )` コマンド置換の内側ではクォート文脈がリセットされるため、
+ * `git commit -m "$(cat <<'EOF'` のような入れ子も検出できる。
+ * ヒアストリング `<<<` は本文を持たないため対象外。
+ */
+function findHeredocDelimiters(line: string): HeredocDelimiter[] {
+  const found: HeredocDelimiter[] = [];
+  const substitutionStack: ('none' | 'single' | 'double')[] = [];
+  let quote: 'none' | 'single' | 'double' = 'none';
+  let i = 0;
+
+  while (i < line.length) {
+    const ch = line[i];
+
+    if (quote === 'single') {
+      if (ch === "'") quote = 'none';
+      i += 1;
+      continue;
+    }
+
+    if (ch === '\\') {
+      i += 2;
+      continue;
+    }
+
+    if (ch === '$' && line[i + 1] === '(') {
+      substitutionStack.push(quote);
+      quote = 'none';
+      i += 2;
+      continue;
+    }
+
+    if (quote === 'double') {
+      if (ch === '"') quote = 'none';
+      i += 1;
+      continue;
+    }
+
+    if (ch === "'") {
+      quote = 'single';
+      i += 1;
+      continue;
+    }
+
+    if (ch === '"') {
+      quote = 'double';
+      i += 1;
+      continue;
+    }
+
+    if (ch === ')' && substitutionStack.length > 0) {
+      quote = substitutionStack.pop() ?? 'none';
+      i += 1;
+      continue;
+    }
+
+    if (ch === '<' && line[i + 1] === '<') {
+      if (line[i + 2] === '<') {
+        // ヒアストリング `<<<` は本文行を持たない
+        i += 3;
+        continue;
+      }
+      i += 2;
+      let allowIndent = false;
+      if (line[i] === '-') {
+        allowIndent = true;
+        i += 1;
+      }
+      while (i < line.length && (line[i] === ' ' || line[i] === '\t')) i += 1;
+      const word = readHeredocDelimiterWord(line, i);
+      i = word.nextIndex;
+      if (word.value.length > 0) {
+        found.push({ word: word.value, allowIndent });
+      }
+      continue;
+    }
+
+    i += 1;
+  }
+
+  return found;
+}
+
+/** `<<` 直後のデリミタ語を読む。クォート/バックスラッシュを解除した値を返す。 */
+function readHeredocDelimiterWord(line: string, start: number): { value: string; nextIndex: number } {
+  let value = '';
+  let i = start;
+
+  while (i < line.length) {
+    const ch = line[i];
+
+    if (ch === "'") {
+      i += 1;
+      while (i < line.length && line[i] !== "'") {
+        value += line[i];
+        i += 1;
+      }
+      i += 1;
+      continue;
+    }
+
+    if (ch === '"') {
+      i += 1;
+      while (i < line.length && line[i] !== '"') {
+        if (line[i] === '\\' && i + 1 < line.length) {
+          value += line[i + 1];
+          i += 2;
+          continue;
+        }
+        value += line[i];
+        i += 1;
+      }
+      i += 1;
+      continue;
+    }
+
+    if (ch === '\\' && i + 1 < line.length) {
+      value += line[i + 1];
+      i += 2;
+      continue;
+    }
+
+    if (DELIMITER_TERMINATORS.has(ch)) break;
+
+    value += ch;
+    i += 1;
+  }
+
+  return { value, nextIndex: i };
+}
+
+/** 終端行判定 (`<<-` は先頭タブを無視し、行末の空白・CR は許容する) */
+function isHeredocTerminator(line: string, delimiter: HeredocDelimiter): boolean {
+  const candidate = delimiter.allowIndent ? line.replace(/^\t+/, '') : line;
+  return candidate.trimEnd() === delimiter.word;
+}
+
+/**
+ * ヒアドキュメント本文行を除去する。
+ *
+ * 本文はシェル構文ではなくデータであり、`Co-Authored-By: Claude <noreply@example.com>`
+ * のような `<...>` をリダイレクトと誤解釈すると無関係なコマンドが誤ブロックされる (WI-362)。
+ * 除去対象は**本文行と終端行のみ**で、開始演算子のある行はそのまま残すため
+ * `cat <<EOF > path` の `> path` は従来どおり検出される (fail-closed 維持)。
+ */
+function stripHeredocBodies(command: string): string {
+  if (!command.includes('<<')) return command;
+
+  const lines = command.split('\n');
+  const kept: string[] = [];
+  const pending: HeredocDelimiter[] = [];
+
+  for (const line of lines) {
+    if (pending.length > 0) {
+      // 本文行 / 終端行はいずれも構文解析対象から外す
+      if (isHeredocTerminator(line, pending[0])) {
+        pending.shift();
+      }
+      continue;
+    }
+    kept.push(line);
+    for (const delimiter of findHeredocDelimiters(line)) {
+      pending.push(delimiter);
+    }
+  }
+
+  return kept.join('\n');
+}
+
 const OPERATOR_SEPARATORS = new Set(['&&', '||', ';', '|']);
 
 /** トークン列を複合・パイプ境界で分割 */
@@ -140,6 +326,28 @@ function getCommandName(tokens: Token[]): string | undefined {
   return undefined;
 }
 
+/** リダイレクト演算子の右辺を解釈し、fd 複製の場合は書き込み先なしとして扱う。 */
+function getRedirectTarget(tokens: Token[], redirectIndex: number): string | undefined {
+  const next = tokens[redirectIndex + 1];
+  if (next === undefined) return undefined;
+
+  if (next.quoted === 'none' && /^&\d+$/.test(next.value)) {
+    return undefined;
+  }
+
+  if (next.quoted === 'none' && next.value === '&') {
+    const afterAmpersand = tokens[redirectIndex + 2];
+    if (afterAmpersand === undefined) return undefined;
+    if (afterAmpersand.quoted === 'none' && /^\d+$/.test(afterAmpersand.value)) {
+      return undefined;
+    }
+    // `>& file` は csh 形式の実ファイル書き込みとして安全側で抽出する。
+    return afterAmpersand.value;
+  }
+
+  return next.value;
+}
+
 /**
  * 1 コマンド分のトークン列から書き込み先を抽出する。
  * リダイレクト先はコマンド種別によらず検出する (全コマンド共通)。
@@ -151,9 +359,9 @@ function extractFromSingleCommand(tokens: Token[]): string[] {
   for (let i = 0; i < tokens.length; i += 1) {
     const t = tokens[i];
     if (t.quoted === 'none' && (t.value === '>' || t.value === '>>' || t.value === '>|')) {
-      const next = tokens[i + 1];
-      if (next !== undefined) {
-        results.push(next.value);
+      const target = getRedirectTarget(tokens, i);
+      if (target !== undefined) {
+        results.push(target);
       }
     }
   }
@@ -289,7 +497,9 @@ function collectPositionals(tokens: Token[]): Token[] {
 
 /** コマンド文字列を token 化 → 演算子分割 → 各コマンドから書き込み先を抽出する内部関数。 */
 function extractFromCommandString(command: string): string[] {
-  const tokens = tokenize(command);
+  // ヒアドキュメント本文はデータなのでシェル構文解析の対象外にする (WI-362)。
+  // apply_patch 抽出は元の command 文字列を直接走査するため影響を受けない。
+  const tokens = tokenize(stripHeredocBodies(command));
   const groups = splitByOperators(tokens);
   const collected: string[] = [];
   for (const group of groups) {

package/scripts/harness/agent-integration/domain/value-objects/protected-file-list.ts

@@ -25,6 +25,11 @@ const DEFAULT_PATTERNS = [
   // grandfather bypass を防ぐため、書き込み自体を保護対象とする。
   '.phasegate/baseline.json',
   '**/.phasegate/baseline.json',
+  // WI-363: .husky/ 配下は L0 runtime の実施点（pre-commit / commit-msg / pre-push）。
+  // WI-352 で config カテゴリに分類されるようになり Quick Mode の書き込み許可対象に
+  // 入ったため、防御機構そのものの書き換えを protected file として明示的に止める。
+  '.husky/**',
+  '**/.husky/**',
 ];
 
 /**