phasegate 0.107.0 → 0.109.0

package/CHANGELOG.md

@@ -7,6 +7,103 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.109.0] - 2026-04-25
+
+### Documentation
+
+- **WI-029: 5-Layer Defense Model docs の正確化** — L0 が legacy な `hook-config` / `gate-check` / `FUSEフック` 検証ではなく、**`agent-integration` unit の 5 種 runtime hook + Husky 2 種 git hook** で実現されている実態に docs を一致させた。
+  - `README.md` / `README.ja.md`: 5-Layer 表の L0 description を agent-runtime hooks (`PreToolUse` / `PostToolUse` / `Stop` / `SessionStart` / `UserPromptSubmit`) + Husky (`.husky/pre-commit` / `.husky/commit-msg`) に書き直し。L4 が `layers.L4.enabled: false` デフォルトであることも補足。
+  - `docs/guide/layer-model.md`: **L0: Agent Runtime Hooks + Git Hooks** セクションに全面改訂。L0-A（agent runtime 5 hook）と L0-B（Husky 2 hook）の責務表を追加。legacy validator `L0-001` / `L0-002` は disabled である旨を明記。L4 セクションにも「default disabled + opt-in による週次 cron 運用」を追記、`doc-freshness` / `pointer-validation` を validator 一覧に追加。
+  - `CLAUDE.md`: 「L0 FUSEフック検証」記述を「L0 legacy validator（現状 enabled: false）」に訂正し、実運用の L0 経路（agent-integration hook + Husky）を補足。
+
+Source code 改変なし。`list-errors --layer L0` の `L0-001` / `L0-002` definition は legacy として残置（削除は別 WI）。
+
+## [0.108.0] - 2026-04-25
+
+### Documentation
+
+- **WI-028: `migrate work-items` + WI taxonomy のドキュメント整備** — WI-026 / WI-027 で導入された機能の公開ドキュメント整合。
+  - `CHANGELOG.md`: v0.101..v0.107 の 7 リリースを Keep-a-Changelog 形式で追記。
+  - `README.md` / `README.ja.md`: CLI Reference 表に `migrate work-items` を追加。
+  - `docs/guide/cli-reference.md`: **Work Item Migration** セクションを新設し、検出パターン（`ISSUE-XXX` / `WI-XXX` / `H{NN}-{NN}`）、sequential allocator の挙動、frontmatter 注入の冪等性、legacy_id grep 互換性、exit code を解説。
+
+## [0.107.0] - 2026-04-25
+
+### Fixed
+
+- **WI-027 root cause 修正**: `FileSystemWorkItemMigrationApplyGateway#ensureFrontmatter` が `---\n` で始まる既存 frontmatter を常に保持してしまい、旧 story-style frontmatter (`id: H02-06`, `unit: ...`, `issue: ...`, `phase: ...`, `created: ...`) を持つ H-ID directory に対して planner 生成 frontmatter が prepend されないバグを解消。
+  - 既存 frontmatter なし → 従来通り planner 生成版を prepend（変更なし）。
+  - 既存 frontmatter の `id` が target WI と不一致 / `legacy_id` 不在 → planner 生成 frontmatter で旧 frontmatter を **置換**し、本文は保持。
+  - 既存 frontmatter が target WI と一致 + `legacy_id` も一致 → byte-for-byte **冪等保持**（再 apply 安全）。
+- 単体テスト追加: `apply-gateway` に「旧 frontmatter 置換」「冪等性」の 2 シナリオ + end-to-end dogfood で 3 シナリオ（stale 置換 / stub 生成 / 冪等保持）全 PASS。
+
+## [0.106.0] - 2026-04-25
+
+### Fixed
+
+- **WI-027 dogfood follow-up**: v0.105.0 適用時、5 件の H-ID directory が旧 story-style frontmatter (`id: H02-06` 形式) を保持していたため、`legacy_id` が記録されず directory 名と `id:` フィールドの不整合が発生していたデータ修正。対象: `agent-integration/WI-033`, `phase-dependency-model/WI-053`, `phase-dependency-model/WI-054`, `quick-mode/WI-060`, `skill-quality/WI-072`。
+- 各ファイルの frontmatter を planner 生成形式（`id: WI-XXX` / `type: story` / `severity: normal` / `status: drafted` / `legacy_id: H{NN}-{NN}`）に正規化。
+
+## [0.105.0] - 2026-04-25
+
+### Added
+
+- **WI-027: `migrate work-items` を H-ID 旧ストーリーレイアウトに拡張** — WI-026 残作業 G2-1/G2-2 の切り出し。`docs/inception/{unit}/H{NN}-{NN}/` 形式 directory（57 件）を `migrate work-items` の対象に含め、空き番号の若い順に `WI-XXX` へ採番する。
+  - **`WorkItemMigrationSourcePort#listExistingWorkItemIds()` 追加**: 既存 `_cross/WI-XXX/` + `{unit}/WI-XXX/` directory の ID を列挙。planner が採番時に予約番号として使用。
+  - **`WorkItemMigrationPlanner` の sequential allocator**: `existingWorkItemIds` + 同一 plan 内 ISSUE-XXX の embedded number を `usedNumbers` に登録し、H-ID には未使用の最小 WI 番号を割り当てる。ISSUE-XXX → WI-XXX の embedded mapping は変更なし（後方互換）。
+  - **H-ID 由来 candidate の frontmatter**: `type: story`（issue ではなく）+ `legacy_id: H{NN}-{NN}` を生成。`affects` は付かない（unit-scoped のため）。
+  - **`FileSystemWorkItemMigrationSourceGateway` の H-ID directory walker**: `^H\d{2}-\d{2}$` パターンで unit 配下の H-ID directory を列挙、`SKIPPED_INCEPTION_DIRS` (`_shared` / `_operation` / `_cross` / `issues`) は引き続き skip。
+  - **適用結果**: phasegate 自身の dogfood で 57 件の H-ID directory を `WI-028..WI-084` に物理 rename + frontmatter 注入。`description.md` 不在の 44 件には stub `# {legacyId}\n` を自動生成。
+
+### Fixed
+
+- **同梱修正: reflection adapter の unit-scoped legacy_id 解決** — `FileSystemStoryReflectionAdapter#readLegacyId` が `_cross/{WI-XXX}/description.md` のみを参照していたため、H-ID 移行で初出した unit-scoped WI（traceability-model/WI-074 等）に対する `@story-id H{NN}-{NN}` annotation が legacy_id 経由で反映認識されず、source 書込時に dead-lock を起こしていた。`{unit}/{WI-XXX}/description.md` も走査するよう拡張し、product 側既存 `@story-id H{NN}-{NN}` annotation が継続利用可能に。
+- 単体テスト UT-PD-169 追加（unit-scoped WI の legacy_id 経由 reflection 検出）。
+
+### Tests
+
+- planner: 5 ケース追加（H-ID 単独 / existingWorkItemIds skip / type: story frontmatter / ISSUE 混在 skip / 連続 H-ID 採番）。
+- gateway: 4 ケース追加（H-ID directory 列挙 / 既存 issues との混在 / `listExistingWorkItemIds` _cross+unit 併合 / 空 inception）。
+- plan use case: existingWorkItemIds を planner に渡すケース追加。
+- reflection adapter: UT-PD-169 (unit-scoped WI legacy_id 解決)。
+- 全 3440 tests green。
+
+## [0.104.0] - 2026-04-25
+
+### Fixed
+
+- **WI-026 残作業 G2-3〜G2-5 / G3 / G4** — Phase A-3 / G1 の続編として ISSUE-026 残債を清掃。
+  - **G2-3**: 空の `docs/inception/issues/` を物理削除（cross issue 旧 layout）。
+  - **G2-4**: `WriteTargetScope.fromPath` の legacy `issues` 分岐を撤去（`{unit}/issues/{ISSUE-XXX}` パスは全 WI 移行済のため不要）。
+  - **G2-5**: `FileSystemStoryReflectionAdapter#listUnitWorkItemDirectories` の `name !== "issues"` filter を撤去。
+  - **G3**: L2-STORY-REFLECTION のメッセージで storyId が `WI-` 始まりの場合 `@work-item-id` を出力（旧 `@story-id` 表記を統一）。
+  - **G4-1〜G4-3**: `_cross/WI-026/description.md` の `status` を `implemented` → `drafted` に戻し、AC checkbox を実態と一致させ、Phase 3 仕様文言を G1 採用案 B に合わせて訂正。
+
+## [0.103.0] - 2026-04-24
+
+### Fixed
+
+- **WI-026 残作業 G1: `_cross/WI-XXX/` inception 編集 dead-lock 解消** — `HandlePreToolUseUseCase#resolveStoryReflectionScope` で `docs/inception/**` への書込を reflection check 対象外にする（採用案 B）。`_cross/WI-XXX/{description,logical_design}.md` を新規作成しても `affects` 不一致による Level 3 reflection 要求でブロックされなくなる。`scripts/harness/{unit}/...` 書込での reflection check は維持。
+- integration test: `_cross/WI-099/{description,logical_design}.md` の新規作成が pass、agent-integration ソース書込で WI-001 reflection が依然要求されることを確認。
+
+## [0.102.0] - 2026-04-24
+
+### Added
+
+- **ISSUE-026 Phase A-2 (H03-04): WorkItem frontmatter parser** — 設計文書 frontmatter から WI メタデータを抽出する専用 parser を `traceability-model` に追加。既存 `parseFrontmatterFlags` は無変更・後方互換維持。
+  - 新規 API: `WorkItemFrontmatter` interface (`id` / `type` / `affects` / `severity` / `status` / `source` / `legacyId`、すべて readonly)、`WorkItemType` / `WorkItemSeverity` / `WorkItemStatus` string union、`parseWorkItemFrontmatter(content: string): WorkItemFrontmatter | null`、`WorkItemFrontmatterValidationError`、`WORK_ITEM_ID_PATTERN` (`WI-\d+` / `H\d{2}-\d{2}` / `HF\d+-\d{2}` / `ISSUE-\d+`)。
+  - UT-TM-W01〜W10 の 10 ケースで AC-1〜AC-10 を 1:1 カバー、3390 tests green。
+
+## [0.101.0] - 2026-04-24
+
+### Added
+
+- **ISSUE-026 Phase A-1 (H02-04): `@work-item-id` annotation parser 併存対応** — `FileSystemStoryReflectionAdapter#fileContainsStoryAnnotation` の regex を `/@(story-id|issue-id|work-item-id)[ \t]+([^\n\r]+)/g` に拡張し、`@story-id` / `@issue-id` / `@work-item-id` の 3 系統を同一規約で認識（後方互換維持）。HTML コメント形式 (`<!-- @work-item-id WI-001 -->`) およびカンマ/空白区切りの複数 ID 列挙にも対応。
+
+### Fixed
+
+- pre-commit の unitName 導出バグ修正。
+
 ## [0.100.0] - 2026-04-23
 
 ### Added

package/README.ja.md

@@ -83,11 +83,13 @@ npx phasegate update-skills   # スキルを最新版に同期
 
 | レイヤー | タイミング | チェック内容 | 実行コマンド |
 |---|---|---|---|
-| **L0** | Agent Hook | hook 設定検証・完了ゲートチェック | `npx phasegate validate --layer L0` |
+| **L0** | AI agent runtime (Claude Code / Codex) + Husky git hooks | PreToolUse が Write/Edit/Bash をゲート違反時に block（reflection 未済 / 保護ファイル / Bash 迂回検知）、PostToolUse が自動 lint/format、Stop で ReentryGuard + `complete-check`、`.husky/pre-commit` が staged files に L2 validators を適用、`.husky/commit-msg` が `Work-Item: WI-XXX` trailer を強制 | runtime 自動起動（`.claude/settings.json` / `.codex/hooks.json` / `.husky/` 経由） |
 | **L1** | エディタ保存時 | import グラフ・レイヤー違反・`@unit`/`@layer` メタデータ・AI アンチパターン | `npx phasegate lint` |
-| **L2** | コミット前 | フェーズゲート・メタデータ完全性・テスト品質 | `npx phasegate validate --layer L2` |
+| **L2** | コミット前（pre-commit hook 内でも評価） | フェーズゲート・メタデータ完全性・`@work-item-id` 反映（L2-STORY-REFLECTION）・テスト品質 | `npx phasegate validate --layer L2` |
 | **L3** | CI/CD | セキュリティ・パフォーマンス・カバレッジ・要件トレーサビリティ (※) | `npx phasegate validate --layer L3` |
-| **L4** | 週次（CI cron） | 設計-コード乖離検出・文書間整合性・デッドコード検出 | `npx phasegate validate --layer L4` |
+| **L4** | 週次（CI cron、現状 `layers.L4.enabled: false` がデフォルト — プロジェクト側で opt-in） | 設計-コード乖離検出・文書間整合性・デッドコード検出・文書鮮度・ポインタ検証 | `npx phasegate validate --layer L4` |
+
+> `list-errors --layer L0` に表示される `L0-001` / `L0-002` は初期設計期に定義された legacy validator で、`layers.L0.enabled: false` により無効化されています。**実際の L0 検知は上表のとおり agent-integration の 5 種の runtime hook と Husky の 2 種の git hook で担っています**。
 
 エラーは統一された `HarnessError` フォーマットで報告され、ADR 参照と修正コード例が含まれるため AI エージェントが自己修正できます。
 
@@ -443,6 +445,8 @@ npx phasegate <command> [options]
 | `validate-adr` | ADR 検証（`--all` または `<adrRef>`） |
 | `list-errors` | エラー定義一覧（`--layer L0-L4`） |
 | `ci:generate-template` | CI/CD テンプレート生成（`--type <type>`） |
+| `migrate work-items` | `docs/inception/` 配下の旧 `ISSUE-XXX` / `H{NN}-{NN}` directory を統一 `WI-XXX` レイアウトへ移行（v0.100.0 で導入、v0.105.0 で H-ID 検出に拡張）。frontmatter に `type` / `legacy_id` / `affects` を注入し、空き番号の若い順に sequential 採番（既存 WI 番号は予約）。`--dry-run` / `--apply` / `--json`。詳細は [CLI Reference -- Work Item Migration](docs/guide/cli-reference.md#work-item-migration) |
+| `migrate --schema v3` | `phasegate.config.json` を v3 スキーマへ昇格（`architecture` キーを追加、既存設定は保持）。冪等。 |
 
 ### Hook / 委任ラッパー
 

package/README.md

@@ -63,30 +63,38 @@ Launch your AI agent and run the `/product-architect` skill to begin.
 
 ```
 +------------------------------------------------------------------+
-|  L0  HOOKS ENGINE          Agent hook configuration              |
+|  L0  AGENT RUNTIME HOOKS   Claude Code / Codex hooks             |
+|  PreToolUse (Write/Edit/Bash block + guide), PostToolUse         |
+|  (auto lint/format), Stop (ReentryGuard + complete-check),       |
+|  SessionStart, UserPromptSubmit. Plus Husky .husky/pre-commit    |
+|  and .husky/commit-msg (Work-Item trailer enforcement).          |
 +------------------------------------------------------------------+
 |  L1  EDITOR TIME           Biome AST rules                       |
 |  require-unit-comment, no-layer-violation, no-any-abuse,         |
 |  enforce-folder-structure, no-ghost-file, no-code-duplication    |
 +------------------------------------------------------------------+
 |  L2  PRE-COMMIT            Validators                            |
-|  phase-gate, metadata completeness, test-quality (AAA pattern)   |
+|  phase-gate, metadata completeness, story-reflection,            |
+|  test-quality (AAA pattern)                                      |
 +------------------------------------------------------------------+
 |  L3  CI/CD                 Validators                            |
 |  security, performance, coverage threshold, nyquist traceability |
 +------------------------------------------------------------------+
-|  L4  SCHEDULED             Validators                            |
-|  drift-detection, consistency-check, dead-code analysis          |
+|  L4  SCHEDULED             Validators (default off)              |
+|  drift-detection, consistency-check, dead-code analysis,         |
+|  doc-freshness, pointer-validation                               |
 +------------------------------------------------------------------+
 ```
 
 | Layer | Trigger | Key Checks |
 |---|---|---|
-| L0 | Agent hooks | Hook config validation, gate checks |
-| L1 | Editor save / lint | Import graph, layer violations, AI anti-patterns |
-| L2 | Pre-commit | Phase gate, `@unit`/`@layer` metadata, test quality |
+| 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` trailer |
+| 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 |
-| L4 | Scheduled (weekly) | Design-code drift, cross-document consistency, dead code |
+| L4 | Scheduled (weekly). Currently `layers.L4.enabled: false` by default — opt-in per project | Design-code drift, cross-document consistency, dead code, doc freshness, pointer validation |
+
+> The `L0-001` / `L0-002` validators that appear in `list-errors --layer L0` output are legacy definitions from an earlier design and are disabled by default (`layers.L0.enabled: false`). The runtime L0 enforcement happens via the agent-integration hook scripts and Husky git hooks listed above, not via those validators.
 
 ---
 
@@ -339,6 +347,8 @@ npx phasegate <command> [options]
 | `hook <pre-tool-use\|post-tool-use\|stop>` | Run a Claude Code hook (reads JSON from stdin) |
 | `pre-commit` | Run L2 pre-commit validators on staged files |
 | `delegate-sonnet [...args]` | Delegate task to Sonnet 4.6 (transparent wrapper) |
+| `migrate work-items --dry-run` / `--apply` | Migrate legacy `ISSUE-XXX` / `H{NN}-{NN}` directories under `docs/inception/` to the unified `WI-XXX` layout (frontmatter `type` / `legacy_id` / `affects` injected). Sequential allocator skips numbers already used by existing WIs. See [CLI Reference -- Work Item Migration](docs/guide/cli-reference.md#work-item-migration). |
+| `migrate --schema v3` | Upgrade `phasegate.config.json` to v3 schema by adding the `architecture` key (idempotent). |
 
 See the [Japanese README](README.ja.md) for the complete CLI reference.
 

package/docs/guide/cli-reference.md

@@ -134,6 +134,114 @@ exit code は `0` = 生成成功 / 上書き成功、`2` = 既存ファイルあ
 
 ---
 
+## Work Item Migration
+
+`docs/inception/` 配下の work item directory を **統一 `WI-XXX` レイアウト**へ移行する CLI。
+WI-026 で導入（v0.100.0、`ISSUE-XXX` 系統）、WI-027 で `H{NN}-{NN}` 形式の旧ストーリー
+directory にも拡張（v0.105.0）、WI-027 follow-up で apply の冪等性を確立（v0.107.0）。
+
+| Command | Options | Description |
+|---|---|---|
+| `migrate work-items` | `--dry-run` / `--apply` / `--json` | 旧 directory を `WI-XXX` へ採番移行する。`--dry-run` と `--apply` は排他、どちらかが必須。|
+
+### 検出パターン
+
+`docs/inception/` 配下を走査し、以下のいずれかに合致する directory を candidate として列挙する:
+
+| 検出パターン | 配置 | scope | nextId 採番方式 |
+|---|---|---|---|
+| `^ISSUE-\d+$` | `docs/inception/issues/` または `{unit}/issues/` | `cross` / `unit` | embedded number そのまま (`ISSUE-026 → WI-026`) |
+| `^WI-\d+$` | 既に WI レイアウトの directory | `cross` / `unit` | 変更なし（idempotent skip） |
+| `^H\d{2}-\d{2}$` | `{unit}/` 直下 | `unit` のみ | sequential allocator: 既存 WI 番号 + 同一 plan 内 ISSUE-XXX 番号を予約したうえで、空き番号の若い順に `WI-XXX` を割り当て |
+
+skip 対象: `_shared/` / `_operation/` / `_cross/` / `issues/` 配下（`_cross/WI-XXX/` は WI レイアウトのため再走査不要）。
+
+### Sequential Allocator の挙動（H-ID 採番）
+
+```
+input:  entries (混在: WI-XXX / ISSUE-XXX / H{NN}-{NN})
+        existingWorkItemIds = ["WI-001", ..., "WI-027"]   # _cross/ + {unit}/ から列挙
+
+step 1. usedNumbers = parseToInts(existingWorkItemIds)            # {1..27}
+step 2. 同一 plan 内 ISSUE-XXX / WI-XXX の embedded number を usedNumbers に追加
+step 3. H-ID entries を sourcePath 昇順でループ:
+          cursor = 1
+          while usedNumbers.has(cursor): cursor++
+          assign WI-{cursor.padStart(3, "0")} to entry
+          usedNumbers.add(cursor)
+```
+
+不変条件:
+
+- 既存 WI-XXX directory の番号は新規 H-ID 採番で再利用されない。
+- 同一 plan 呼び出し内で `nextId` は重複しない（usedNumbers が共有される）。
+- `ISSUE-XXX → WI-XXX` の embedded mapping は変更しない（後方互換）。
+
+### Frontmatter 注入
+
+`--apply` 時、各 directory の `description.md` に以下の frontmatter を生成する。
+既存 frontmatter があれば **id 一致 + legacy_id 一致** のときだけ byte-for-byte
+保持し、それ以外は planner 生成版で置換する（v0.107.0 で冪等化）。
+
+```yaml
+---
+id: WI-XXX                    # 採番された ID
+type: story | issue           # H-ID 由来は story、ISSUE-XXX 由来は issue
+severity: trivial | normal | high  # 元 description の "深刻度" から抽出（既定: normal）
+status: drafted
+legacy_id: H02-04              # または ISSUE-026
+affects: [unit-a, unit-b]      # cross scope のみ。元 description の "影響Unit" から抽出
+---
+```
+
+`description.md` 不在の directory には `# {legacyId}\n` の stub を生成して frontmatter を prepend する。
+
+### 使用例
+
+```bash
+# 移行候補を表示（実際の rename は行わない）
+npx phasegate migrate work-items --dry-run
+
+# JSON 出力（CI / スクリプト向け）
+npx phasegate migrate work-items --dry-run --json
+
+# 実マイグレーション実行
+npx phasegate migrate work-items --apply
+
+# apply 結果を JSON で取得
+npx phasegate migrate work-items --apply --json
+```
+
+### exit code
+
+| code | 意味 |
+|---|---|
+| `0` | 成功（dry-run 時 conflict なし、apply 時 blocked なし）|
+| `1` | dry-run で conflict candidate あり（target directory が既に存在）/ apply で blocked |
+| `2` | 引数不正（`--dry-run` / `--apply` どちらも未指定、両方指定、`--apply` 未配線等）|
+
+### Legacy ID Grep 互換性
+
+WI-XXX へ移行後も、frontmatter の `legacy_id:` 経由で旧 ID を逆引きできる:
+
+```bash
+# 旧 H-ID から WI directory を逆引き
+grep -rn "^legacy_id: H02-04" docs/inception/
+
+# 旧 ISSUE-XXX から逆引き
+grep -rn "^legacy_id: ISSUE-026" docs/inception/
+
+# Work-Item commit trailer による履歴遡及
+git log --grep='Work-Item: WI-074'
+```
+
+また、ソースコード内の `// @story-id H02-04` などの legacy annotation は、
+`FileSystemStoryReflectionAdapter#readLegacyId` が `_cross/` と `{unit}/` の
+両方の `WI-XXX/description.md` を走査して `legacy_id` を解決するため、
+unit-scoped WI（H-ID 由来）の reflection check でも継続認識される（v0.105.0）。
+
+---
+
 ## Harness API
 
 Commands exposed as npm scripts (`npm run <command>`).

package/docs/guide/layer-model.md

@@ -19,21 +19,47 @@ Layers are additive: L1 rules still apply when L3 runs. The earlier a defect is
 
 ---
 
-## L0: Hooks Engine
+## L0: Agent Runtime Hooks + Git Hooks
 
-The Hooks Engine validates agent hook configuration and enforces completion gates before work can proceed.
+L0 is the **earliest defense layer** — it intercepts file writes and commits *before* they happen, so violations never land in the working tree or the history. There are two sub-systems:
 
-| Rule | Description |
-|------|-------------|
-| **hook-config** | Validates `.harness-hooks.yml` configuration structure and semantics |
-| **gate-check** | Verifies that all required completion gates have been satisfied |
+### L0-A: AI agent runtime hooks (`agent-integration` unit)
 
-**Command:**
+Registered via `.claude/settings.json` (Claude Code) and `.codex/hooks.json` (Codex). Every hook is implemented in `scripts/harness/agent-integration/presentation/*-hook.ts` and ships with the npm package.
+
+| Hook | Matcher / Trigger | Responsibility |
+|------|-------------------|----------------|
+| **pre-tool-use-hook** | `Write` / `Edit` / `Bash` | Blocks writes that violate phase gate, write-protected paths, Bash-based bypass (`tee`, `sed -i`, `cp`, heredoc, etc.), or miss `@work-item-id` reflection. Returns exit 2 with a structured guide message that the agent can act on. |
+| **post-tool-use-hook** | `Write` / `Edit` | Runs auto-lint / auto-format / error analysis on the file that was just modified (`format-settings-hook.sh`, `format-typescript-hook.sh`, `analyze-errors-hook.sh`). |
+| **stop-hook** | Agent `Stop` | Activates `ReentryGuard` to prevent infinite hook loops, then runs `phasegate:complete-check` (L2–L4 aggregate) as a final gate. |
+| **session-start-hook** | `startup` / `resume` | Loads session context for Codex (project status summary, recent changes). |
+| **user-prompt-submit-hook** | `UserPromptSubmit` | Refreshes status so the next prompt sees the current harness state. |
+
+Command-line entry points exist for debugging / CI use:
+
+```bash
+npx phasegate hook pre-tool-use < payload.json
+npx phasegate hook post-tool-use < payload.json
+npx phasegate hook stop < payload.json
+```
+
+### L0-B: Husky git hooks
+
+Deployed by `phasegate init --with-husky` into `.husky/`.
+
+| Hook file | Invokes | Responsibility |
+|-----------|---------|----------------|
+| **.husky/pre-commit** | `npx phasegate pre-commit` | Runs L2 validators (phase-gate / metadata / story-reflection / test-quality) on staged files. Fails the commit on violation. |
+| **.husky/commit-msg** | `npx phasegate commit-msg $1` | Enforces the `Work-Item: WI-XXX` trailer when WI directories or their contents are staged. Ensures every commit is traceable to a work item. |
+
+### About the `validate --layer L0` CLI
 
 ```bash
 npx phasegate validate --layer L0
 ```
 
+`list-errors --layer L0` surfaces `L0-001 fuse-hook-config` / `L0-002 fuse-mount-status` — these are **legacy validator definitions** from an earlier design and are disabled by default (`layers.L0.enabled: false`). The **runtime L0 enforcement happens via the agent-runtime hooks and Husky git hooks above**, not via those validators.
+
 ---
 
 ## L1: Editor Time — Biome AST Rules
@@ -112,13 +138,17 @@ npx phasegate validate --layer L3
 
 ## L4: Scheduled Validators
 
-L4 validators run on a weekly schedule. They detect slow-moving drift that accumulates over time.
+L4 validators are designed to run on a weekly schedule and detect slow-moving drift that accumulates over time.
+
+> **Status**: L4 is **disabled by default** (`layers.L4.enabled: false` in `phasegate.config.json`). Projects opt in by flipping the flag and scheduling the command via CI cron (see `ci:generate-template --type consistency-check`). Implementation-wise the validators listed below are functional; the default-off state is a conservative rollout choice, not a missing feature.
 
 | Validator | Description |
 |-----------|-------------|
 | **drift-detect** | Bidirectional design-code drift detection. Compares design documents against the actual codebase to find divergence in either direction. |
 | **consistency-check** | Cross-document layer consistency. Ensures that references between design documents, ADRs, and code remain coherent. |
 | **dead-code** | Detects unused exports and unreachable code that should be removed. |
+| **doc-freshness** | Flags design documents whose last update is older than a configured threshold while the corresponding code has diverged. |
+| **pointer-validation** | Verifies that relative-path pointers inside design docs resolve to files that actually exist. |
 
 **Command:**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.107.0",
+  "version": "0.109.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",