phasegate 0.152.7 → 0.152.8

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.152.8] - 2026-05-13
+
+### Changed
+
+- **WI-155 / WI-165 / WI-166 / WI-167 / WI-168 — product reflection and catalog cleanup** — aligns product unit catalog policy, ADR validator catalog references, Work Item reflection wording, hook skip observability docs, and coverage/test design refresh for WI-117..148 follow-up semantics.
+
 ## [0.152.7] - 2026-05-13
 
 ### Changed

package/docs/ADR/ADR-002-pre-commit-validators.md

@@ -10,13 +10,16 @@ AIエージェントは設計文書を無視して直接コードを書くこと
 
 ## Decision
 
-L2（Pre-commit）で以下の3バリデータにより設計-実装の順序を機械的に強制する。
+L2（Pre-commit）で以下のバリデータにより設計-実装の順序、メタデータ、テスト品質、CLI E2E、WI status、公開 contract traceability を機械的に強制または報告する。初期ADRの3バリデータ記述は履歴であり、現行 catalog は validator-system registry を正とする。<!-- @work-item-id WI-168 -->
 
 | バリデータ | コード | 検出対象 |
 |-----------|--------|---------|
 | phase-gate | L2-001 | 設計文書なしの実装コード変更を拒否 |
 | metadata | L2-002 | @unit/@layer/@US-XXX メタデータの完全性検証 |
 | test-quality | L2-003 | AAA パターン、actual 命名、日本語テスト名の検証 |
+| cli-e2e | L2-013 | public CLI entrypoint の基本 E2E 契約 |
+| wi-status | L2-014 | WI status と acceptance criteria の陳腐化検出 |
+| contract-traceability | L2-015 | public contract / boundary / observation の traceability coverage |
 
 ### Phase Gate の3層検証
 
@@ -27,7 +30,7 @@ L2（Pre-commit）で以下の3バリデータにより設計-実装の順序を
 ## Consequences
 
 - 設計文書なしのコード変更が物理的に不可能になる
-- `@US-XXX` によるトレーサビリティが機械的に保証される
+- `@work-item-id WI-XXX` と legacy annotation の対応によりトレーサビリティが機械的に保証される
 - テスト品質ルール（AAA, actual 命名）が全テストに強制される
 
 ## 関連要件

package/docs/ADR/ADR-004-scheduled-validators.md

@@ -10,13 +10,15 @@ Accepted
 
 ## Decision
 
-L4（Scheduled）で以下の3バリデータを週次で実行する。
+L4（Scheduled）で以下のバリデータを週次または明示実行で扱う。初期ADRの3バリデータ記述は履歴であり、現行 catalog は validator-system registry と `docs/guide/layer-model.md` を正とする。<!-- @work-item-id WI-168 -->
 
 | バリデータ | コード | 検出対象 |
 |-----------|--------|---------|
 | drift-detect | L4-001 | 設計にあるがコードにない / コードにあるが設計にない双方向乖離 |
 | consistency-check | L4-002 | 文書間のレイヤー整合性の破綻 |
 | dead-code | L4-003 | 未使用エクスポート、到達不能コード |
+| doc-freshness | L4-004 | 設計文書の freshness threshold 超過 |
+| pointer-validation | L4-005 | 設計文書 pointer の owner/type/source/severity/nextAction 付き検証 |
 
 ### 技術的実装
 
@@ -28,7 +30,7 @@ L4（Scheduled）で以下の3バリデータを週次で実行する。
 
 - 設計-実装の乖離が週次で自動検出される
 - 未使用コードの蓄積が防止される
-- strict プリセットでのみ L4 が有効（standard/minimal ではスキップ）
+- L4 は default-off の scheduled/advisory 層として扱い、strict または明示 `validate --layer L4` で実行できる。fail-on-warning policy がない限り warning-only findings は gate failure へ昇格しない。
 
 ## 関連要件
 

package/docs/ADR/ADR-013-story-reflection-gate.md

@@ -16,7 +16,7 @@ Phase Gate（L2-001）は設計文書の**存在**を検証するが、inception
 
 ## Decision
 
-`phaseDependencies.storyReflection` を導入し、**実装着手時（`src/` / `scripts/harness/` への Write/Edit）に inception → product 反映を機械的に検証**する。
+`phaseDependencies.storyReflection` を導入し、**実装着手時（`src/` / `scripts/harness/` への Write/Edit）に inception → product 反映を機械的に検証**する。現行の新規 reflection は `@work-item-id WI-XXX` を正とし、既存の `@story-id HXX-XX` / `@story-id US-XXX` は WI frontmatter の `legacy_id` 経由で履歴として解決する。<!-- @work-item-id WI-155 -->
 
 ### 設計原則
 
@@ -72,7 +72,7 @@ inception/order/US-002/logical_design.md は存在しますが、
 ### 関連コンポーネント
 
 - `PhaseConfigProviderPort.getStoryReflectionConfig()` — プリセット + config から有効な mappings を解決
-- `FileSystemStoryReflectionAdapter` — inception ディレクトリ列挙と product 文書内 `@story-id` 検索
+- `FileSystemStoryReflectionAdapter` — inception ディレクトリ列挙と product 文書内 `@work-item-id` / legacy `@story-id` 検索
 - `HandlePreToolUseUseCase` — src/ への Write 発火時に storyReflection チェックを呼び出し、未反映ならブロック
 - Quick Mode (`relaxedGates: ["phase-gate"]`) 時は storyReflection も緩和される（§4.6）
 

package/docs/guide/installation.md

@@ -17,7 +17,7 @@ Or add it directly to your `package.json`:
 ```json
 {
   "devDependencies": {
-    "phasegate": "^0.152.7"
+    "phasegate": "^0.152.8"
   }
 }
 ```

package/docs/guide/setup-artifacts.md

@@ -53,6 +53,23 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 - `.harness/reports` is a legacy fallback used only when a phase-dependency provider cannot resolve project config.
 - `.phasegate/hook-skip-events.jsonl` records hook bypass/skip observations for diagnosis; it is runtime state, not a managed install target.
 
+## Hook Skip Events
+
+<!-- @work-item-id WI-166 -->
+
+`.phasegate/hook-skip-events.jsonl` is a best-effort JSON Lines runtime log written by agent hooks when a hook intentionally skips or cannot complete its normal validation path. Each record is diagnostic evidence for `phasegate status --json`, not a gate result by itself.
+
+Typical fields are:
+
+| Field | Meaning |
+|---|---|
+| `hookType` | Hook family, for example `PostToolUse` or `Stop`. |
+| `reason` | Stable skip reason such as disabled hook, reentry detection, timeout, or unsupported native pre-edit path. |
+| `targetPaths` | Files or paths relevant to the hook event when available. |
+| `timestamp` | Event time in ISO format. |
+
+Recording is best-effort. A write failure must not change the original hook exit code. Operators should use the latest skip event and counts in `phasegate status --json` to decide whether to run `phasegate doctor`, refresh hooks with `reconcile`, enable Codex hook support, or rely on the L2 pre-commit backstop for edits that native hooks cannot observe before mutation.
+
 ## Legacy Retirement
 
 Current setup does not require `.harness-hooks.yml`, old Fuse hook files, `.harness/session-state.json`, or `.harness/context-priority.json`. Treat them as project-local compatibility artifacts. Before deleting them, check whether an archived workflow or local script still references them; otherwise prefer documenting them as retired rather than wiring new guidance around them.

package/package.json

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