phasegate 0.183.0 → 0.212.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **WI-256 — skill catalog 30 → 29 (BREAKING for skill consumers)** — the bundled skill catalog is reshaped. **Removed** `implementation-planner`, `doc-freshness-checker`, and `pointer-validator`. **Added** `doc-health-checker` (core / Verification, `kind: advisory`) and `release-publisher` (guidance / Operations, `kind: advisory`). Net advisory count 7 → 8, lifecycle 23 → 21, total 30 → 29. Both catalog sources (`skill-deployer.ts` `SKILL_CATEGORIES`, `bundled-skill-selection.ts`) and all count phrases / category headings were updated in the same batch.
+  - `implementation-planner` functionality (Unit identification, domain-model review, existing-implementation review, API-inclusive planning, and the Phase 2 minimum-output criteria) is now absorbed into **`story-implementor` Phase 1**.
+  - Doc-quality checks are now driven by **`doc-health-checker`**, which wraps the correct `p2:`-prefixed CLI commands: `npx phasegate p2:check-freshness` (freshness / code-design drift, L4-004) and `npx phasegate p2:validate-pointers` (broken file-path pointers, L4-005; supported flags are `--pattern` / `--include-urls` / `--format` — there is no auto-fix flag). The removed skills documented the wrong unprefixed command names (`phasegate check-freshness` / `phasegate validate-pointers`); those are corrected here.
+  - **Note**: `doc-freshness-checker` and `pointer-validator` also exist as **L4 validator IDs** (config presets, `validator-id.ts`, `ci-governance`). Those are a different concept and are **not** affected by this change — only the `skills/` directories were removed.
+
+#### Migration (manual removal required in consumer repos)
+
+`reconcile` does **not** prune skills that have left the bundle, so the three removed skill directories will remain as orphans in already-installed projects. Remove them manually:
+
+```bash
+rm -r skills/implementation-planner skills/doc-freshness-checker skills/pointer-validator
+# If personal-mode per-agent copies exist:
+rm -r .claude/skills/{implementation-planner,doc-freshness-checker,pointer-validator}
+rm -r .codex/skills/{implementation-planner,doc-freshness-checker,pointer-validator}
+```
+
+A permanent `reconcile`-based prune is deferred to a follow-up WI.
+
 ## [0.171.0] - 2026-07-05
 
 ### Added

package/README.ja.md

@@ -59,6 +59,8 @@ Claude Code / Codex はこのメッセージを読んで `/story-implementor`
 
 ## クイックスタート
 
+まず [Getting Started](docs/guide/getting-started.md) から始めると、新規リポジトリ / 既存リポジトリ / CI 専用 / agent hook / strict 導入の各パスを、次に打つコマンドと成功状態に対応づけて案内します。
+
 ### 前提
 
 Node.js >= 18, npm >= 9, TypeScript 5.x
@@ -80,7 +82,7 @@ claude
 `init` は初期 bootstrap として以下を生成します:
 
 - `phasegate.config.json` — 品質設定の Single Source of Truth
-- `skills/` — 30 の AIDLC スキル一式
+- `skills/` — 29 の AIDLC スキル一式
 - `.claude/skills/` ・ `.codex/skills/` — agent 向けの skill symlink
 - `.claude/settings.json` — PreToolUse / PostToolUse / Stop hook
 - `.codex/hooks.json` — Codex CLI hooks 設定（`--agent codex|both` 時）
@@ -129,11 +131,12 @@ npx phasegate install --personal --agent claude --apply
 | 項目 | personal install の挙動 |
 |---|---|
 | **触らないファイル** | `package.json` / `AGENTS.md` / `CLAUDE.md` / `.husky/*` / `.github/workflows/*` / `.gitignore` / GitHub CLI 設定 / repo secrets / CI 設定 |
-| **作るファイル** | `.phasegate-local/phasegate.config.json`（ローカル専用 config）／ `.claude/CLAUDE.local.md` または `.codex/AGENTS.local.md`（agent context）／ `.claude/settings.json` + `.claude/skills/` または `.codex/hooks.json` + `.codex/skills/`（選択した agent の runtime artifact）／ `.git/hooks/pre-commit` + `.git/hooks/commit-msg`（ローカル git hook）／ `.phasegate-local/docs/`（設計原則文書コピー）／ `.phasegate/manifest.json` |
+| **作るファイル** | `.phasegate-local/phasegate.config.json`（ローカル専用 config）／ runtime から見えるローカル agent context（Claude は `.claude/CLAUDE.md`、Codex は root の `AGENTS.md` が不在または既に PhaseGate 管理下のときのみ `AGENTS.md`）／ `.claude/settings.json` + `.claude/skills/` または `.codex/hooks.json` + `.codex/skills/`（選択した agent の runtime artifact）／ `.git/hooks/pre-commit` + `.git/hooks/commit-msg`（ローカル git hook）／ `.phasegate-local/docs/`（設計原則文書コピー）／ `.phasegate/manifest.json` |
+| **既存 skills の扱い** | 個人用 skills directory がある場合は merge — bundled skills を refresh し、user 所有の skill は保持する |
 | **コミット漏れ対策** | `.git/info/exclude` にローカル専用 block を管理して、個人用ファイルが誤ってチームの commit に混ざらないようにする。commit 時の L2 防御は `.git/hooks/` で発火する |
 | **Codex hook flag** | user-level feature flag の有効化は手動アクションとして残る（`codex features enable hooks`） |
 
-Codex を併用する場合は `--agent codex` または `--agent both` を指定します。アンインストールは team install と同様に `npx phasegate uninstall --apply` を使えば manifest 経由でローカル成果物のみが除去されます。<!-- @work-item-id WI-207 --> <!-- @work-item-id WI-208 --> <!-- @work-item-id WI-209 --> <!-- @work-item-id WI-213 -->
+チーム所有の `AGENTS.md` が既に存在する場合、Codex の personal install はそれを変更せず、`doctor --personal --agent codex` が残りの context ステップを（`AGENTS.override.md` に隠すのではなく）報告します。Codex を併用する場合は `--agent codex` または `--agent both` を指定します。アンインストールは team install と同様に `npx phasegate uninstall --apply` を使えば manifest 経由でローカル成果物のみが除去されます。<!-- @work-item-id WI-207 --> <!-- @work-item-id WI-208 --> <!-- @work-item-id WI-209 --> <!-- @work-item-id WI-213 --> <!-- @work-item-id WI-215 -->
 
 後で PhaseGate を外す場合は、manifest ベースの uninstall を使います。
 
@@ -157,7 +160,7 @@ npx phasegate reconcile --apply
 
 ```bash
 npx phasegate init --name my-project --agent codex --with-husky
-codex features enable codex_hooks   # Codex 本体の feature flag を手動で有効化
+codex features enable hooks   # Codex 本体の feature flag を手動で有効化
 ```
 
 両方使う場合は `--agent both`。Codex のネイティブ `apply_patch` は現時点で事前 hook を発火しないため、pre-commit (L2) で commit 時にブロックします。Bash 経由の書き込みは実行前に止まります。詳細は [Codex Integration Guide](docs/guide/codex-integration.md) を参照。
@@ -180,7 +183,7 @@ npx phasegate reconcile --apply
 |---|---|
 | **フェーズゲート** | 設計文書がないと実装ファイルへの Write/Edit/Bash をブロック。AIDLC 準拠 / カスタム gate の両方をサポート |
 | **5 層バリデーション (L0-L4)** | エディタ保存 → pre-commit → CI → 週次まで段階的に品質チェック |
-| **30 AIDLC スキル** | 要求定義 → ドメイン設計 → テスト設計 → TDD 実装をスキルとして提供 |
+| **29 AIDLC スキル** | 要求定義 → ドメイン設計 → テスト設計 → TDD 実装をスキルとして提供 |
 | **Quick Mode** | バグ修正・docs・テスト追加など軽微変更ではゲートを緩和して高速化 |
 | **Claude Code / Codex Hooks** | Write/Edit/Bash 時に自動でゲートチェック・lint を実行 |
 | **HarnessError 形式** | 全エラーに ADR 参照 + 修正例が含まれ、AI が自己修正できる |
@@ -201,10 +204,12 @@ npx phasegate reconcile --apply
 |     @unit / @layer メタデータ, レイヤー違反, AI アンチパターン   |
 +------------------------------------------------------------------+
 | L2  pre-commit                                                   |
-|     phase-gate, story-reflection, テスト品質 (semantic AAA)       |
+|     phase-gate, story-reflection, テスト品質 (semantic AAA),      |
+|     coverage-attestation-gating (L2-016, fail-closed)            |
 +------------------------------------------------------------------+
 | L3  CI/CD                                                        |
-|     security, performance, coverage 90%/95%, 要件カバレッジ        |
+|     security, performance, coverage 90%/95%, 要件カバレッジ,       |
+|     injection-scan (L3-006, advisory)                            |
 +------------------------------------------------------------------+
 | L4  週次 (default off)                                           |
 |     設計-コード乖離, 文書整合性, デッドコード,                  |
@@ -222,26 +227,50 @@ npx phasegate reconcile --apply
 
 エラーは `HarnessError` 形式（理由 / ADR 参照 / 修正例）で返されるため、AI agent が自己修正できます。
 
+**L2 の追加ゲート**: `L2-STORY-REFLECTION` は git の source-touch により layer-aware になり、複数 WI を含む commit では file-tag scoped の attribution で反映元を判定します。`L2-016 coverage-attestation-gating` は fail-closed で、`✅` を主張するには attestation ID が必須です（ID なしの ✅ はブロック）。既存の非ゲート行は `ungated-legacy` マーカーで可視化したまま段階返済します。
+
+**L3 の追加ゲート**: `L3-006 injection-scan` は指示搭載ファイルに対する advisory（**warning-only、非 blocking**）なインジェクションスキャナで、人間レビューへの注意喚起に留めます。
+
 詳細: [5-Layer Defense Model](docs/guide/layer-model.md)
 
 ---
 
-## 30 AIDLC スキル
+## セキュリティ姿勢
+
+Phasegate はプロンプトインジェクションを独立した新規脅威として扱いません。[ADR-030](docs/ADR/030-injection-threat-model-and-trust-root.md) の通り、インジェクションに成功したエージェントは、phasegate が元々仮定してきた **「洗浄を試みるエージェント」と同一の脅威** — すなわち正規の権限（Bash / ファイル書き込み / commit）で品質防御を回避しようとする悪意ある内部者 — として振る舞います。したがって対策は「穴を塞ぐ」「コンテンツが指示になる経路を減らす」の 2 軸に還元され、専用の別枠防御ではなく既存の L0-L4 モデルの延長で扱います。
+
+**信頼のルート**: L0-L2 はローカルで実行される以上、Bash を持つエージェントには原理的に偽造・迂回可能です。これらは **fast-path**（正直なエージェントの事故防止 / 騙されかけたエージェントの早期停止）として正直に位置づけます。**信頼のルート（authoritative）は L3 CI の再検証**で、攻撃者が制御できない環境で evidence を独立に再計算します。「ローカルが緑なら安全」は明示的に保証しません。
+
+この姿勢を 5 コンポーネントで実装します:
+
+| コンポーネント | 役割 | 正直な位置づけ |
+|---|---|---|
+| **指示ファイル整合性 pin** | 指示搭載ファイル（SKILL.md / `CLAUDE.md`・`AGENTS.md` テンプレート / hook 定義 / `.husky/*`）の SHA-256 manifest（`phasegate.integrity.json`）。`integrity:pin` で意図的変更を記録、SessionStart hook が drift を警告、CI が再計算して authoritative に照合 | ローカル照合は warn-only の fast-path、CI が authoritative |
+| **coverage attestation ゲート (L2-016)** | fail-closed の参照形式ゲート。`✅` の主張には attestation ID が必須で、bare ✅ はブロック。既存行は `ungated-legacy` で可視化し段階返済 | L2 は参照形式をゲートする。evidence の独立再実行は L3 側の将来分 |
+| **hook 出力の spotlighting** | hook が中継するリポジトリ由来の自由文字列を固定のデータ境界フェンスで包み、「データであって指示ではない」ことを明示 | リポジトリ由来テキストが指示に昇格する経路を減らす |
+| **advisory インジェクションスキャナ (L3-006)** | 指示搭載ファイルの既知インジェクションパターンを検査。**advisory / warning-only** で非 blocking のため「すり抜け＝安全」という誤った信頼を生まない | パターン検査は回避可能。finding は警告のみ、最終判断は人間レビュー |
+| **エージェント権限 allowlist** | エージェント操作を allowlist（明示的に許されたものだけ実行）に反転。網羅漏れのある deny 列挙（`git merge`/`checkout`/`reset` は deny 済みなのに `git switch` が漏れていた等）を是正 | 未知の危険操作を既定で拒否 |
+
+**ADR-030 が明記する残存リスク**: ローカル層（L0-L2）は偽造可能なので L3 が信頼のルート／スキャナは回避可能なので advisory に留める／CI を持たない PJ には信頼のルートが不在（`phasegate doctor` が警告）／red・警告付き PR を人間が手動 merge する経路は機械防御の対象外。
+
+---
+
+## 29 スキル
 
 AIDLC (AI-Driven Development Life Cycle) は **要求定義 → 設計 → テスト設計 → TDD 実装** の順序を強制するプロセスです。各スキルは前のレベルの成果物を入力にします。
 
 **最初の一歩**: Claude Code / Codex 内で `/product-architect` を実行。
 
-### 6 グループ（30 スキル）
+### 6 グループ（29 スキル）
 
 | グループ | スキル |
 |---|---|
 | **Foundation (4)** | `/product-architect` `/story-writer` `/story-mapper` `/unit-designer` |
 | **Design (5)** | `/domain-designer` `/logical-designer` `/mock-designer` `/uiux-designer` `/environment-designer` |
 | **Test Engineering (7)** | `/unit-test-designer` `/it-test-designer` `/scenario-test-designer` `/unit-test-logic-designer` `/it-test-logic-designer` `/scenario-test-logic-designer` `/test-coverage-checker` |
-| **Implementation (4)** | `/story-implementor` `/quick-implementor` `/implementation-planner` `/implementation-readiness-checker` |
-| **Verification (8)** | `/consistency-checker` `/cascade-updater` `/codex-delegator` `/codebase-mapper` `/doc-freshness-checker` `/pointer-validator` `/engineering-perspective` `/skill-creator` |
-| **Operations (2)** | `/phasegate-config-doctor` `/phasegate-toolkit-guide` |
+| **Implementation (3)** | `/story-implementor` `/quick-implementor` `/implementation-readiness-checker` |
+| **Verification (7)** | `/consistency-checker` `/cascade-updater` `/codex-delegator` `/codebase-mapper` `/doc-health-checker` `/engineering-perspective` `/skill-creator` |
+| **Operations (3)** | `/phasegate-config-doctor` `/phasegate-toolkit-guide` `/release-publisher` |
 
 各スキルの詳細・成果物・前提条件: [Skills Overview](docs/guide/skills-overview.md)
 
@@ -357,12 +386,17 @@ npx phasegate <command> [options]
 | `uninstall --dry-run` / `--apply` | manifest に基づいて PhaseGate 管理ファイル・管理 block を削除し、ユーザー設定は保持 |
 | `reconcile --dry-run` / `--apply` | 現在の package template に PhaseGate 管理ファイルを追従し、manifest hash を更新 |
 | `update-skills` | `reconcile` の互換 alias |
+| `setup:agent --dry-run` / `--apply` | リポジトリの setup 状態を診断し、質問 / risk / rollback / validation 付きの agent-readable な setup plan を生成・適用 |
+| `config:plan --intent <intent>` | 安全な設定変更 intent を対象ファイル / コマンド / risk / rollback / validation にマップ |
+| `integrity:pin` | 指示搭載ファイルの SHA-256 manifest（`phasegate.integrity.json`）を生成 / 更新（意図的変更を記録。`--dry-run`, `--json`） |
+| `integrity:verify` | manifest と実ファイルを照合。drift 検出時は exit 2、クリーン時は exit 0（`--json`）。ローカルは advisory、CI が authoritative |
 | `lint` | L1 Biome AST チェック |
 | `validate --layer <L1\|L2\|L3\|L4\|all>` | 指定レイヤーのバリデータ実行（`--format human\|agent\|ci`） |
 | `ci-check` | CI フルチェック（L2-L4）。`--quick` で Quick Mode |
 | `check-change-category --paths <csv>` | 変更ファイルを Quick Mode カテゴリに分類、Full Mode 強制が必要かを返す |
 | `baseline` | retrofit grandfather snapshot 生成（`--dry-run`, `--force`, `--paths <glob>`, `--json`） |
 | `scaffold-design --unit <id> --phase <logical\|domain\|uiux\|unit-test\|it-test>` | 最小構成の設計文書を `templates/` から生成 |
+| `scaffold-wi <unit> <type>` | 次の空き WI 番号で `docs/inception/{unit}/WI-XXX/description.md` を生成 |
 | `phasegate:status` | 全体の健全性サマリ |
 | `work-items:status --dry-run` / `--apply` | 成果物から WI status を導出し、必要に応じて `description.md` frontmatter を更新。`--apply` は既定で downgrade を拒否し、必要時のみ `--allow-downgrade` を指定 |
 | `phasegate:check-phase --unit <id>` | 指定 Unit の現在フェーズ |
@@ -374,7 +408,7 @@ npx phasegate <command> [options]
 | `refresh-claude-md --dry-run` / `--apply` | user section を保持して CLAUDE.md だけを更新 |
 | `p2:check-agent-context` | AGENTS.md / CLAUDE.md の鮮度を検査 |
 | `list-errors --layer <L0-L4>` | エラー定義一覧 |
-| `hook <pre-tool-use\|post-tool-use\|stop>` | agent hook を起動（stdin から JSON） |
+| `hook <pre-tool-use\|post-tool-use\|stop\|session-start\|user-prompt-submit>` | agent hook を起動（stdin から JSON を読む。session-start / user-prompt-submit は JSON context を出力） |
 | `pre-commit` | L2 pre-commit バリデータをステージファイルに適用 |
 | `bypass:audit --base <ref> [--head <ref>]` | push/CI range に pre-commit validation を再適用し、gate failure に structured bypass evidence を要求 |
 
@@ -393,6 +427,8 @@ npx phasegate <command> [options]
 | **PreToolUse** | Write/Edit/Bash の実行前 | フェーズゲート違反 / 保護ファイル / Bash 経由迂回をブロック。Quick→Full 強制条件のチェックも実行 |
 | **PostToolUse** | Write/Edit の実行後 | Biome AST ルールを自動実行、違反を即時フィードバック |
 | **Stop** | セッション終了前 | L2-L4 全チェックを実行、グリーンでないと終了を保留 |
+| **SessionStart** | セッション開始時 | harness status context を注入。指示ファイル整合性 pin を in-process で照合し、drift 時のみ **warn-only / fail-open** で警告（authoritative な照合は CI） |
+| **UserPromptSubmit** | プロンプト送信時 | リポジトリ由来 context を注入。中継するリポジトリ由来テキストを固定のデータ境界フェンスで包み（spotlighting）、指示ではなくデータとして扱わせる |
 
 ### Codex CLI
 
@@ -540,9 +576,10 @@ L3 Nyquist Validation の `requirement-test-matrix.json` は `phasegate:generate
 ## ドキュメント
 
 - [Installation](docs/guide/installation.md) — 詳細インストール手順
+- [Getting Started](docs/guide/getting-started.md) — 初回 / 日常 / CI / agent 利用の各パス
 - [Configuration](docs/guide/configuration.md) — `phasegate.config.json` 完全リファレンス
 - [CLI Reference](docs/guide/cli-reference.md) — 全 CLI コマンド・オプション
-- [Skills Overview](docs/guide/skills-overview.md) — 30 スキルの実行順序と成果物
+- [Skills Overview](docs/guide/skills-overview.md) — 29 スキルの実行順序と成果物
 - [5-Layer Defense Model](docs/guide/layer-model.md) — L0-L4 詳細・HarnessError 形式
 - [Hooks Integration](docs/guide/hooks-integration.md) — Claude Code Hooks 設定
 - [Codex Integration](docs/guide/codex-integration.md) — Codex CLI セットアップ・カバレッジ
@@ -560,4 +597,4 @@ phasegate 自体の開発: [DEVELOPMENT.ja.md](DEVELOPMENT.ja.md)
 
 ---
 
-*Last updated: 2026-04-25 — v0.110.0*
+*Last updated: 2026-07-15 — v0.211.0*

package/README.md

@@ -83,7 +83,7 @@ claude
 `init` creates the initial project-local harness files:
 
 - `phasegate.config.json` as the quality settings source of truth
-- `skills/` with 30 AIDLC skills
+- `skills/` with 29 AIDLC skills
 - `.claude/skills` and/or `.codex/skills` links for agent use
 - `.claude/settings.json` and/or `.codex/hooks.json` hook configuration
 - `docs/principles/*.md` and `docs/folder_management_rules.md`
@@ -167,7 +167,7 @@ npx phasegate reconcile --apply
 |---|---|
 | **Phase gates** | Blocks implementation writes until required design documents exist and have been reflected into product docs |
 | **5-layer validation** | Runs checks from agent runtime and editor time through pre-commit, CI, and scheduled audits |
-| **30 AIDLC skills** | Guides AI agents through product architecture, story writing, domain design, test design, and TDD implementation |
+| **29 AIDLC skills** | Guides AI agents through product architecture, story writing, domain design, test design, and TDD implementation |
 | **Quick Mode** | Keeps bugfixes, docs, test-only changes, and config changes lightweight while preserving traceability |
 | **Claude Code / Codex hooks** | Runs checks around Write/Edit/Bash operations and session boundaries |
 | **Agent-readable HarnessError output** | Gives AI agents the reason, missing artifacts, references, and examples needed to self-correct |
@@ -192,10 +192,12 @@ npx phasegate reconcile --apply
 +------------------------------------------------------------------+
 |  L2  PRE-COMMIT            Validators                            |
 |  phase-gate, metadata completeness, story-reflection,            |
-|  test-quality (semantic AAA + assertion strength)                |
+|  test-quality (semantic AAA + assertion strength),               |
+|  coverage-attestation-gating (L2-016, fail-closed)               |
 +------------------------------------------------------------------+
 |  L3  CI/CD                 Validators                            |
-|  security, performance, coverage threshold, nyquist traceability |
+|  security, performance, coverage threshold, nyquist              |
+|  traceability, injection-scan (L3-006, advisory)                 |
 +------------------------------------------------------------------+
 |  L4  SCHEDULED             Validators (default off)              |
 |  drift-detection, consistency-check, dead-code analysis,         |
@@ -207,13 +209,33 @@ npx phasegate reconcile --apply
 |---|---|---|
 | L0 | AI agent runtime (`.claude/settings.json` / `.codex/hooks.json`) + Husky git hooks | PreToolUse blocks Write/Edit/Bash that violate gates; PostToolUse runs lint/format; Stop enforces ReentryGuard + `complete-check`; `.husky/pre-commit` runs `phasegate pre-commit`; `.husky/commit-msg` enforces `Work-Item: WI-XXX` and bypass trailers; `.husky/pre-push` runs `phasegate bypass:audit` |
 | L1 | Editor save / `phasegate lint` | `@unit` / `@layer` metadata, layer violations, AI anti-patterns, dead code |
-| L2 | Pre-commit (also evaluated inside PreToolUse at L0) | Phase gate, metadata completeness, `@work-item-id` reflection (`L2-STORY-REFLECTION`), test quality |
-| L3 | CI/CD pipeline | Security, performance, coverage (90%/95%), requirements traceability |
+| L2 | Pre-commit (also evaluated inside PreToolUse at L0) | Phase gate, metadata completeness, `@work-item-id` reflection (`L2-STORY-REFLECTION`, now layer-aware with git source-touch + file-tag-scoped attribution for multi-WI commits), test quality, coverage-report attestation gate (`L2-016`, fail-closed: a bare ✅ without an attestation ID is blocked; pre-existing rows stay visible via the `ungated-legacy` marker) |
+| L3 | CI/CD pipeline | Security, performance, coverage (90%/95%), requirements traceability, advisory injection scan (`L3-006`, **warning-only**) over instruction-carrying files |
 | L4 | Scheduled (weekly). Currently `layers.L4.enabled: false` by default — opt-in per project | Design-code drift, cross-document consistency, dead code, doc freshness, and pointer validation. `p2:*` standalone commands remain available as compatibility entry points. |
 
 ---
 
-## 30 Skills
+## Security Posture
+
+Phasegate does not treat prompt injection as a separate threat. Per [ADR-030](docs/ADR/030-injection-threat-model-and-trust-root.md), a successfully injected agent behaves exactly like the "laundering agent" the toolkit already assumes: a malicious insider that uses its legitimate permissions (Bash, file writes, commits) to evade the quality defenses. The countermeasures therefore reduce to two axes — close the holes an agent can slip through, and reduce the paths by which external content becomes agent instructions — handled along the existing L0-L4 model rather than in a separate defense layer.
+
+**Trust root.** Because L0-L2 run locally, an agent with Bash can in principle forge or bypass them. They are positioned honestly as a **fast-path** (early accident detection for honest agents, early stop for misled ones). The **authoritative trust root is the L3 CI re-check**, which runs where an attacker cannot control the environment and recomputes evidence independently. "Local is green" is explicitly not a safety guarantee.
+
+Five components implement this posture:
+
+| Component | Role | Honest framing |
+|---|---|---|
+| **Instruction-file integrity pin** | SHA-256 manifest (`phasegate.integrity.json`) over instruction-carrying files (SKILL.md, `CLAUDE.md` / `AGENTS.md` templates, hook definitions, `.husky/*`). `integrity:pin` records intentional changes; the SessionStart hook warns on drift; CI recomputes as the authority. | Local check is a warn-only fast-path; CI is authoritative. |
+| **Coverage attestation gate (L2-016)** | Fail-closed reference-style gate: a `✅` coverage claim requires an attestation ID; bare ✅ is blocked. Pre-existing rows are surfaced via `ungated-legacy` and repaid gradually. | L2 gates on reference shape; independent evidence re-execution is L3's future scope. |
+| **Hook-output spotlighting** | Repo-derived free text relayed in hook output is wrapped in fixed data-boundary fences so it reads as data, not instructions. | Reduces the path by which repo content is promoted to the harness voice. |
+| **Advisory injection scanner (L3-006)** | Scans instruction-carrying files for known injection patterns. **Advisory / warning-only** — never blocking, so no "slipped past the scanner = safe" false confidence is created. It is a signal for human review. | Pattern checks are inherently evadable; findings are warnings only. |
+| **Agent-permission allowlist** | Agent operations are an allowlist (only explicitly permitted operations run), inverted from the previous deny-list that had gaps (e.g. `git switch` was missing while `git merge`/`checkout`/`reset` were denied). | Unknown dangerous operations are denied by default. |
+
+**Residual risks ADR-030 states plainly**: local layers (L0-L2) are forgeable, so L3 is the trust root; the scanner is evadable, so it stays advisory; a project without CI has no trust root (`phasegate doctor` warns); and a human manually merging a red/warned PR is outside machine defense.
+
+---
+
+## 29 Skills
 
 Skills cover the full **AIDLC (AI-Driven Development Life Cycle)**: product definition, design, test design, and TDD implementation. Each skill consumes the artifacts from the previous phase.
 
@@ -224,9 +246,9 @@ Skills cover the full **AIDLC (AI-Driven Development Life Cycle)**: product defi
 | **Foundation (4)** | `/product-architect` `/story-writer` `/story-mapper` `/unit-designer` |
 | **Design (5)** | `/domain-designer` `/logical-designer` `/mock-designer` `/uiux-designer` `/environment-designer` |
 | **Test Engineering (7)** | `/unit-test-designer` `/it-test-designer` `/scenario-test-designer` `/unit-test-logic-designer` `/it-test-logic-designer` `/scenario-test-logic-designer` `/test-coverage-checker` |
-| **Implementation (4)** | `/story-implementor` `/quick-implementor` `/implementation-planner` `/implementation-readiness-checker` |
-| **Verification (8)** | `/consistency-checker` `/cascade-updater` `/codex-delegator` `/codebase-mapper` `/doc-freshness-checker` `/pointer-validator` `/engineering-perspective` `/skill-creator` |
-| **Operations (2)** | `/phasegate-config-doctor` `/phasegate-toolkit-guide` |
+| **Implementation (3)** | `/story-implementor` `/quick-implementor` `/implementation-readiness-checker` |
+| **Verification (7)** | `/consistency-checker` `/cascade-updater` `/codex-delegator` `/codebase-mapper` `/doc-health-checker` `/engineering-perspective` `/skill-creator` |
+| **Operations (3)** | `/phasegate-config-doctor` `/phasegate-toolkit-guide` `/release-publisher` |
 
 Details, prerequisites, and generated artifacts: [Skills Overview](docs/guide/skills-overview.md)
 
@@ -488,6 +510,8 @@ Phasegate integrates natively with Claude Code via hooks in `.claude/settings.js
 | `PreToolUse` | `Write`, `Edit`, or `Bash` (write operations detected) | Blocks writes to source files without design docs; enforces `quickMode.fullModeRequiredWhen` (escalates Quick Mode → Full when triggered); skips files captured in the `.phasegate/baseline.json` snapshot until they are modified; protects configured files; detects Bash write operations (`sed -i`, `tee`, `cp`, etc.) |
 | `PostToolUse` | `Write` or `Edit` | Auto-formats and validates metadata |
 | `Stop` | Session end | Runs full test suite to ensure all tests pass |
+| `SessionStart` | Session start | Injects harness status context; verifies the instruction-file integrity pin in-process and warns (**warn-only, fail-open**) if drift is detected — CI remains the authoritative check |
+| `UserPromptSubmit` | Prompt submitted | Injects repo-derived context, wrapping relayed repo text in fixed data-boundary fences (spotlighting) so it reads as data, not instructions |
 
 All hook errors use the `HarnessError` format with ADR references and fix examples, enabling AI agents to self-correct without human intervention.
 
@@ -544,6 +568,10 @@ README keeps only the entry points most users need. The full public/compatibilit
 | `reconcile --dry-run` / `--apply` | Update PhaseGate-managed files to the current package templates and refresh manifest hashes. |
 | `setup:agent --dry-run` / `--apply` | Diagnose repository setup and produce or apply an agent-readable setup plan with questions, risks, rollback, and validation. |
 | `config:plan --intent <intent>` | Map a safe configuration-change intent to target files, commands, risks, rollback, and validation. |
+| `integrity:pin` | Generate/update the SHA-256 manifest (`phasegate.integrity.json`) over instruction-carrying files. Records intentional edits (`--dry-run`, `--json`). |
+| `integrity:verify` | Recompute and compare against the manifest. Exit 2 on drift (mismatch/added/missing/manifest-absent), exit 0 when clean (`--json`). Locally advisory; CI is authoritative. |
+| `list-adrs` | List ADRs, optionally filtered by `--status <Proposed\|Accepted\|...>`. |
+| `validate-adr` | Validate ADR structure (`--all` or a single `<adrRef>`). |
 | `lint` / `phasegate:lint` | Run L1 Biome AST checks. The `phasegate:*` form is a binary subcommand, not an npm script unless `package.json` defines it locally. |
 | `validate --layer <L1-L4\|all>` | Run validators for the specified layer (`--layer L0` prints runtime hook guidance). `--fail-on-warning` / `--no-fail-on-warning` override config. |
 | `ci-check` | Full CI check (L2-L4; disabled L4 is reported as skipped). Supports `--quick`, `--fail-on-reject`, `--dry-run`, and `--files`. |
@@ -589,7 +617,7 @@ Detailed guides are available under `docs/guide/`:
 - [Troubleshooting](docs/guide/troubleshooting.md) -- Doctor finding, repairHint, suggestedSkill, and setup recovery guide
 - [Configuration](docs/guide/configuration.md) -- `phasegate.config.json` full reference
 - [CLI Reference](docs/guide/cli-reference.md) -- All CLI commands and options
-- [Skills Overview](docs/guide/skills-overview.md) -- 30 skills with AIDLC execution order
+- [Skills Overview](docs/guide/skills-overview.md) -- 29 skills with AIDLC execution order
 - [5-Layer Defense Model](docs/guide/layer-model.md) -- L0-L4 layer details and HarnessError format
 - [Contract Traceability](docs/guide/contract-traceability.md) -- `L2-015` public contract, boundary, error, state, and observation annotations
 - [Hooks Integration](docs/guide/hooks-integration.md) -- Claude Code Hooks setup and behavior

package/docs/ADR/030-injection-threat-model-and-trust-root.md

@@ -0,0 +1,145 @@
+---
+adr_id: "030"
+title: "プロンプトインジェクション脅威モデルと信頼のルート宣言"
+status: Accepted
+date: 2026-07-10
+---
+
+# プロンプトインジェクション脅威モデルと信頼のルート宣言
+
+## Context
+
+phasegate は「設計意図とコードの構造的整合性を機械的に保証する」ことを目的とし、その前提として **「品質防御を回避（洗浄）しようとするエージェント」を脅威として仮定** してきた（ADR-006 エージェント非依存設計、ADR-013 storyReflection ゲート、coverage_report の attestation 化に関する既存の議論など）。
+
+一方で、AI エージェントを用いた開発フローが普及するにつれ、**プロンプトインジェクション**が新たな懸念として浮上した。しかし phasegate はこれを独立した新規脅威としては扱わない。理由を明文化するのが本 ADR の第一の目的である。
+
+### プロンプトインジェクションの作用機序
+
+インジェクションは、外部発コンテンツが「信頼できないテキストとしてエージェントの文脈に入る箇所」から作用する。phasegate の文脈で該当する主な経路は以下:
+
+- **npm 依存**（インストールされるパッケージの README・ソース・postinstall 出力等）
+- **PR 由来ファイル**（レビュー対象の diff、コミットされたドキュメント・コメント）
+- **エージェントが読む Web コンテンツ**（fetch した外部ページ・issue 本文・リンク先）
+
+これらのコンテンツがエージェントの指示として解釈されて成功すると、エージェントは **「悪意ある内部者」** として振る舞う。すなわち、正規の権限（Bash、ファイル書き込み、コミット）を用いて品質防御を回避しようとする。
+
+### 既存脅威モデルとの同一性
+
+この「悪意ある内部者と化したエージェント」は、phasegate が元々仮定してきた **「洗浄を試みるエージェント」と同一の脅威モデル** である。インジェクションは新しい攻撃の入口を増やすが、防御対象となる振る舞い（防御の偽装・迂回）は変わらない。
+
+したがって対策は 2 軸に還元される:
+
+1. **洗浄可能な残り穴を塞ぐ** — エージェントが権限で防御をすり抜けられる隙間を減らす。
+2. **コンテンツが指示になる経路を減らす** — 外部発テキストがエージェントの指示に昇格しにくくする。
+
+この整理により、phasegate は「インジェクション専用の別枠防御」を作らず、既存の 5 層防御モデル（L0–L4）の延長線上で一貫して対処する。本 ADR はその方針と、その前提となる **信頼のルート（trust root）** を宣言する。
+
+## Decision
+
+### 1. 信頼のルート（authoritative）は L3 CI の再検証である
+
+phasegate の防御層のうち、**L0–L2（ローカル hook / pre-commit）は Bash を持つエージェントには原理的に偽造・迂回可能** である。ローカルで実行される以上、同一プロセス権限を持つエージェントは hook の入出力・終了コード・pin ファイルを書き換えられる。したがって L0–L2 を「信頼のルート」と位置づけることはできない。
+
+L0–L2 は **fast-path** として正直に位置づける。fast-path の価値は次の 2 点に限定される:
+
+- **正直なエージェントの事故防止** — 意図せぬ規約違反をローカルで早期に検出し、無駄な往復を減らす。
+- **騙されかけたエージェントの早期停止** — インジェクションで逸脱し始めたエージェントを、ローカルの明示的なブロックで踏みとどまらせる。
+
+**信頼のルート（authoritative）は L3 CI の再検証** とする。CI は攻撃者（あるいは騙されたエージェント）が制御できない環境で:
+
+- 指示ファイルの **SHA-256 ハッシュを再計算** して pin と照合する。
+- coverage_report 等の **evidence を再実行** して主張の真偽を独立に確かめる。
+
+ローカルが何を主張しようと、最終的な合否は CI の再検証が決める。
+
+### 2. ローカル秘密鍵 / HMAC 方式は不採用
+
+「ローカル成果物を秘密鍵で署名し改竄を検出する」案は **採用しない**。理由:
+
+- **同一マシンの Bash からは鍵を隔離できない** — エージェントが鍵にアクセスできる以上、署名も偽造でき、見せかけの安全にしかならない。
+- **UX コストに見合わない** — 導入 PJ の全マシンで鍵を配布・ローテーション・保護する運用負担は、得られる（見せかけの）保証に釣り合わない。
+
+改竄検出は「秘密に依存しない再計算（ハッシュ）を、攻撃者が制御できない場所（CI）で行う」方式に統一する。
+
+### 3. 5 コンポーネント構成（実装順に記録）
+
+上記 2 軸（穴を塞ぐ / 指示経路を減らす）を、以下の 5 コンポーネントで実装する。番号は実装順を兼ねる。
+
+#### ① 指示ファイルの整合性 pin（穴を塞ぐ）
+
+指示を搭載するファイル群の SHA-256 を `phasegate.integrity.json` に pin する。対象:
+
+- SKILL.md × 30
+- `CLAUDE.md` / `AGENTS.md` テンプレート
+- hook 定義
+- `deny-check.sh`
+- `.husky/*`
+
+照合と更新のフロー:
+
+- **session-start hook** が起動時に pin と実ファイルを照合する（fast-path の改竄検出）。
+- **`phasegate integrity:pin`** コマンドで pin を正規に更新する（意図的な変更の記録手段）。
+- **CI が再計算** して照合する（authoritative）。ローカルの照合結果は信頼せず、CI が独立に確かめる。
+
+#### ② coverage_report の attestation ゲート（穴を塞ぐ）
+
+`phasegate:attest` を拡張し、coverage_report の主張を attestation で裏付ける。
+
+- **L2 で fail-closed** — `✅` を主張するには attestation ID が必須。ID なしの ✅ はブロックする。
+- **L3 が evidence を再実行** — attestation が指す証跡を CI が独立に再実行し、主張の真偽を確かめる（authoritative）。
+- **既存の非ゲート 72 件** は `ungated-legacy` マーカーで可視化し、段階的に返済する（一括ブロックによる運用停止を避けつつ、負債を隠さない）。
+
+#### ③ hook 出力の spotlighting（指示経路を減らす）
+
+hook がエージェントに返す出力を **固定テンプレート + データ境界マーカー** で構造化する。外部発コンテンツを hook が中継する際、それがデータであって指示ではないことをマーカーで明示し、コンテンツが指示に昇格する経路を減らす。
+
+#### ④ L3 advisory インジェクションスキャナ（指示経路を減らす）
+
+指示搭載ファイルの PR diff に対し、既知のインジェクションパターンを検査する L3 スキャナを追加する。
+
+- **advisory（非 blocking）とする** — パターン検査は本質的に回避可能であり、blocking にすると「検出をすり抜けた＝安全」という誤った信頼を生む。あくまで人間レビューへの注意喚起に留める。
+
+#### ⑤ エージェント権限の deny 列挙 → allowlist 反転（穴を塞ぐ）
+
+エージェントに許す操作を deny 列挙（ブラックリスト）から allowlist（ホワイトリスト）へ反転する。
+
+- deny 列挙は網羅漏れが原理的に避けられない。実例として、`git merge` / `git checkout` / `git reset` が deny 済みであるにもかかわらず、等価な危険操作である **`git switch` が漏れていた**。
+- allowlist 反転により「明示的に許されたものだけを実行できる」状態にし、未知の危険操作を既定で拒否する。
+
+### 4. 残存リスクの明記
+
+本設計は脅威を完全には消せない。以下を残存リスクとして明記し、隠さない:
+
+- **(a) ローカル層は偽造可能** — L0–L2 は原理的に迂回できる。だから L3 が信頼のルートである（本 ADR §Decision.1）。
+- **(b) ④ のスキャナは回避可能** — パターン検査はすり抜けられる。だから advisory であり blocking にしない（§Decision.3.④）。
+- **(c) CI を持たない利用側 PJ では信頼のルートが不在** — L3 再検証が動かない環境では authoritative な保証が得られない。**`phasegate doctor` で警告する** 方針とする。
+- **(d) 人間による手動 merge 経路は防げない** — red / 警告付きの PR を人間が手動で merge する経路は、機械防御の対象外である。
+
+## Consequences
+
+### Positive
+
+- インジェクションを既存脅威モデルに還元することで、専用の別枠防御を作らず一貫した設計を維持できる。
+- 信頼のルートを L3 CI に明示的に置くことで、「ローカルが緑なら安全」という誤った信頼を排除できる。
+- 秘密鍵運用を避けることで、導入 PJ の UX コストを増やさない。
+- 残存リスクを明文化することで、利用者が防御の限界を正しく理解できる。
+
+### Negative / Trade-off
+
+- **CI を持たない PJ は authoritative な保証を得られない** — fast-path のみとなる（`phasegate doctor` の警告で緩和）。
+- **integrity pin の運用負担** — 指示ファイルを正規に変更するたびに `phasegate integrity:pin` が必要になる。
+- **④ が advisory であるため誤検知・見逃しの両方が起こりうる** — 最終判断は人間レビューに委ねられる。
+- **既存 72 件の `ungated-legacy`** は段階返済の間、attestation ゲートの外に残る。
+
+## Alternatives
+
+- **ローカル秘密鍵 / HMAC 署名方式** — 同一マシンの Bash から鍵を隔離できず見せかけの安全にしかならず、全マシンでの鍵運用コストにも見合わないため不採用（§Decision.2）。
+- **④ を blocking にする案** — パターン検査は回避可能であり、blocking 化は「すり抜け＝安全」という誤った信頼を生むため advisory に留めた（§Decision.3.④）。
+- **インジェクション専用の独立防御層を新設する案** — インジェクションは既存の「洗浄を試みるエージェント」脅威モデルに還元できるため、別枠を設けず 5 層防御の延長で対処する方針を採った（§Context）。
+
+## 関連要件・文書
+
+- ADR-006（エージェント非依存設計原則）— 本 ADR の脅威モデルの基礎
+- ADR-013（storyReflection ゲート）— ローカル fast-path と CI 再検証の関係の先行例
+- `docs/guide/layer-model.md` §L0 — L0 の実体（hook / husky）
+- `phasegate.config.json` — 品質設定の Single Source of Truth

package/docs/guide/hooks-integration.md

@@ -111,7 +111,7 @@ Additional hooks can be placed in `.claude/scripts/`:
 
 | Script | Behavior |
 |--------|----------|
-| deny-check.sh | Block dangerous git/bash commands (git reset --hard, rm -rf, etc.) |
+| deny-check.sh | Enforce the agent command policy: git subcommands are default-deny (allowlist), plus explicit bash deny patterns (rm -rf, sudo, etc.). See [Agent git command allowlist](#agent-git-command-allowlist). |
 | format-settings-hook.sh | Auto-format settings.json on edit |
 | format-typescript-hook.sh | Auto-format TypeScript files (Biome / ESLint+Prettier) |
 | analyze-errors-hook.sh | Detect tsc/lint errors on TypeScript edit |
@@ -135,3 +135,52 @@ Additional hooks can be placed in `.claude/scripts/`:
 | formatterArgs | Arguments passed to formatter | ["check", "--write"] |
 
 Legacy `.harness-hooks.yml` and old Fuse hook files are not part of the current install lifecycle. Keep them only for archived integrations; new setup should use `install`, `doctor`, `reconcile`, `lint`, and `validate`. <!-- @work-item-id WI-157 -->
+
+## Agent git command allowlist
+
+<!-- @work-item-id WI-253 -->
+
+`deny-check.sh` runs as a `PreToolUse` hook on every `Bash` tool call and blocks disallowed commands by exiting with code 2. For git it uses a **default-deny allowlist** rather than an enumerated deny list.
+
+### Why allowlist instead of deny list
+
+An enumerated deny list always leaks. The original policy denied `git checkout*`, `git reset*`, `git merge*`, `git rebase*`, `git cherry-pick*`, `git revert*`, `git clean*`, and `git stash*`, but `git switch` was never listed — so an agent could change the working-tree/branch state through `git switch`, defeating the intent of the deny rules (no history or working-tree mutation). Overly broad globs also caused false positives: `git merge*` blocked the read-only `git merge-base`.
+
+Inverting to an allowlist makes the policy fail closed: any git subcommand not explicitly permitted is denied, including future subcommands the deny list would not have known about.
+
+### Allowed git subcommands
+
+The permitted set lives in `GIT_ALLOWED_SUBCOMMANDS` in `.claude/scripts/deny-check.sh`. It covers read-only inspection, staging/commit/tag creation, and worktree/fetch operations:
+
+```
+status log show diff add commit tag restore rev-parse rev-list
+merge-base branch worktree fetch grep cat-file ls-files ls-tree
+ls-remote config init remote describe blame shortlog
+symbolic-ref for-each-ref name-rev check-ignore check-attr
+stripspace var help version whatchanged push
+```
+
+History- and working-tree-mutating subcommands are intentionally **absent** so they fail closed, including: `checkout`, `switch`, `reset`, `rebase`, `merge`, `cherry-pick`, `revert`, `stash`, `clean`, `update-ref`, `reflog`, `filter-branch`, `replace`, and `am`.
+
+### How the subcommand is extracted
+
+The check tolerates global options placed before the subcommand, so evasion via flag stuffing does not bypass it. All of the following resolve to their real subcommand (`merge`, denied):
+
+```
+git merge x
+git -C /repo merge x
+git --no-pager merge x
+git -c core.pager=cat merge x
+```
+
+Denied commands smuggled behind chaining/substitution operators (`&&`, `|`, `;`, `$( )`, subshells) are also caught, because the hook inspects each command segment independently.
+
+### Adding a subcommand
+
+Default-deny means a genuinely needed subcommand must be added by a human. Edit `GIT_ALLOWED_SUBCOMMANDS` in `.claude/scripts/deny-check.sh` and add the subcommand name. The block message names the rejected subcommand and points here, e.g.:
+
+```
+Security policy violation: git subcommand 'switch' is not in the agent allowlist (default-deny for git). ...
+```
+
+Note: `git push` is on the allowlist so user-directed pushes are not hard-blocked by this hook; gating pushes further (e.g. an interactive confirmation) is handled by the harness permission layer, not by `deny-check.sh`.

package/docs/guide/installation.md

@@ -36,7 +36,7 @@ npm install
 npx phasegate init --name <project-name>
 ```
 
-This deploys 30 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 agent-facing skill links (for example `.claude/skills/` or `.codex/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 -->
 

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

@@ -174,7 +174,7 @@ No. `allowedCategories` is a fixed enum (`bugfix`, `docs`, `test`, `config`). If
 
 ## Related
 
-- [Skills Overview](skills-overview.md) — full catalogue of 30 skills
+- [Skills Overview](skills-overview.md) — full catalogue of 29 skills
 - [Layer Model](layer-model.md) — L0 through L4 defence layers
 - [Configuration](configuration.md) — `quickMode` configuration reference
 - `skills/quick-implementor/SKILL.md` — the Quick Mode skill definition