phasegate 0.108.0 → 0.110.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.110.0] - 2026-04-25
11
+
12
+ ### Documentation
13
+
14
+ - **WI-030: README / layer-model 主張と実装の乖離訂正** — README.ja.md と docs/guide/layer-model.md の audit で発見した不整合を訂正。
15
+ - **README.ja.md L180**: 「毎週月曜 09:00 UTC + GitHub Issue 自動作成」の記述を実態に合わせて訂正。bundled template (`scripts/harness/templates/.github/workflows/consistency-check.yml`) は月曜 04:00 UTC + issue 自動化、CLI 生成 (`ci:generate-template --type consistency-check`) は毎日 02:00 UTC + issue 化なし、と二系統あることを明示。`phasegate init` が workflow を自動配置しない点も補足。
16
+ - **README.ja.md L408**: feature flag disclaimer 「ランタイム動作未実装」を削除し、`agentLessonCollection` / `cascadeUpdate` / `bundleSizeLimit` / `deadCodeGC` の各 runtime 動作実装箇所を表に追記。
17
+ - **docs/guide/layer-model.md L4 セクション**: WI-029 で誤って追加した `doc-freshness` / `pointer-validation` を L4 validators 一覧から削除し、これらは `phase2-extensions` unit の `p2:check-freshness` / `p2:validate-pointers` CLI として実装されている旨を注記(L4-004 / L4-005 への昇格は WI-033 に分離)。
18
+ - **README.md / README.ja.md に Roadmap 節を新設** — partial 実装 / user-side wiring 依存の機能を 4 件の Work Item として明示:
19
+ - WI-031: CI template 二系統統一 + `phasegate init --with-ci`
20
+ - WI-032: AGENTS.md / CLAUDE.md auto-refresh パイプライン
21
+ - WI-033: `doc-freshness` / `pointer-validation` を L4 validator に昇格
22
+ - WI-034: L0 legacy validator (`L0-001` / `L0-002`) の撤去
23
+
24
+ Source code 改変なし。次のリリースで上記 Roadmap WI が順次対応される予定。
25
+
26
+ ## [0.109.0] - 2026-04-25
27
+
28
+ ### Documentation
29
+
30
+ - **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 を一致させた。
31
+ - `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` デフォルトであることも補足。
32
+ - `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 一覧に追加。
33
+ - `CLAUDE.md`: 「L0 FUSEフック検証」記述を「L0 legacy validator(現状 enabled: false)」に訂正し、実運用の L0 経路(agent-integration hook + Husky)を補足。
34
+
35
+ Source code 改変なし。`list-errors --layer L0` の `L0-001` / `L0-002` definition は legacy として残置(削除は別 WI)。
36
+
10
37
  ## [0.108.0] - 2026-04-25
11
38
 
12
39
  ### Documentation
package/README.ja.md CHANGED
@@ -83,11 +83,13 @@ npx phasegate update-skills # スキルを最新版に同期
83
83
 
84
84
  | レイヤー | タイミング | チェック内容 | 実行コマンド |
85
85
  |---|---|---|---|
86
- | **L0** | Agent Hook | hook 設定検証・完了ゲートチェック | `npx phasegate validate --layer L0` |
86
+ | **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/` 経由) |
87
87
  | **L1** | エディタ保存時 | import グラフ・レイヤー違反・`@unit`/`@layer` メタデータ・AI アンチパターン | `npx phasegate lint` |
88
- | **L2** | コミット前 | フェーズゲート・メタデータ完全性・テスト品質 | `npx phasegate validate --layer L2` |
88
+ | **L2** | コミット前(pre-commit hook 内でも評価) | フェーズゲート・メタデータ完全性・`@work-item-id` 反映(L2-STORY-REFLECTION)・テスト品質 | `npx phasegate validate --layer L2` |
89
89
  | **L3** | CI/CD | セキュリティ・パフォーマンス・カバレッジ・要件トレーサビリティ (※) | `npx phasegate validate --layer L3` |
90
- | **L4** | 週次(CI cron) | 設計-コード乖離検出・文書間整合性・デッドコード検出 | `npx phasegate validate --layer L4` |
90
+ | **L4** | 週次(CI cron、現状 `layers.L4.enabled: false` がデフォルト — プロジェクト側で opt-in) | 設計-コード乖離検出・文書間整合性・デッドコード検出・文書鮮度・ポインタ検証 | `npx phasegate validate --layer L4` |
91
+
92
+ > `list-errors --layer L0` に表示される `L0-001` / `L0-002` は初期設計期に定義された legacy validator で、`layers.L0.enabled: false` により無効化されています。**実際の L0 検知は上表のとおり agent-integration の 5 種の runtime hook と Husky の 2 種の git hook で担っています**。
91
93
 
92
94
  エラーは統一された `HarnessError` フォーマットで報告され、ADR 参照と修正コード例が含まれるため AI エージェントが自己修正できます。
93
95
 
@@ -175,7 +177,11 @@ L4 は CI の cron スケジュールで週次実行します。`consistency-che
175
177
  npx phasegate ci:generate-template --type consistency-check --render > .github/workflows/consistency-check.yml
176
178
  ```
177
179
 
178
- デフォルトは毎週月曜 09:00 UTC に実行。乖離やデッドコードが検出されると GitHub Issue が自動作成されます。手動で実行する場合は `npx phasegate validate --layer L4` を使います。
180
+ **bundled template (`scripts/harness/templates/.github/workflows/consistency-check.yml`) user 側で `.github/workflows/` にコピー**する場合は、月曜 04:00 UTC に走り、検出時に `github.rest.issues.create` で GitHub Issue を自動作成します。
181
+
182
+ 一方、`ci:generate-template --type consistency-check --render` で **CLI 生成した YAML** は現状 `cron: "0 2 * * *"` (毎日 02:00 UTC) で出力され、issue 自動作成 logic は含まれていません(両経路の統一は **WI-031** で予定)。
183
+
184
+ 手動実行は `npx phasegate validate --layer L4` を使います。なお `phasegate init` は workflow を自動配置しないため、L4 を CI で動かすには user 側で workflow を `.github/workflows/` 配下に commit する必要があります(自動配置は WI-031 `--with-ci` フラグで予定)。
179
185
 
180
186
  ---
181
187
 
@@ -398,14 +404,14 @@ npx phasegate <command> [options]
398
404
 
399
405
  利用可能な Feature flags:
400
406
 
401
- | Feature | 説明 | デフォルト |
402
- |---|---|---|
403
- | `agentLessonCollection` | AI エージェントの学習ログを収集 | off (`strict` で on) |
404
- | `cascadeUpdate` | 下位フェーズの変更を上位設計に自動反映 | off |
405
- | `bundleSizeLimit` | バンドルサイズ制限チェック (KB) | off (`strict` で 500KB) |
406
- | `deadCodeGC` | デッドコード検出・削除 | off (`strict` で on) |
407
+ | Feature | 説明 | デフォルト | ランタイム動作 |
408
+ |---|---|---|---|
409
+ | `agentLessonCollection` | AI エージェントの学習ログを収集 | off (`strict` で on) | ✅ 実装済(agent-integration unit の `harness-config-config-query-adapter.ts:86` で参照、pre-tool-use hook 経路で機能) |
410
+ | `cascadeUpdate` | 下位フェーズの変更を上位設計に反映 | off | ✅ 実装済(`CascadeUpdateService` 経由で `skill:apply-cascade-update` CLI / cascade-updater skill が動作) |
411
+ | `bundleSizeLimit` | バンドルサイズ制限チェック (`number`、単位は KB) | `0` (off) / `strict` で `500` | ✅ 実装済(L3-002 performance validator が threshold として参照) |
412
+ | `deadCodeGC` | デッドコード検出 | off (`strict` で on) | ✅ 実装済(L4 `dead-code-detection-service` が threshold 経由で受領) |
407
413
 
408
- > **注意**: Feature flags config への保存・読み出しは動作しますが、フラグに応じたランタイム動作は未実装です(将来バージョンで対応予定)。
414
+ > **補足**: 過去のバージョンでは「Feature flags のランタイム動作未実装」と記載していましたが、`v0.110.0` 時点では上表のとおり 4 機能とも実 runtime で動作します。
409
415
 
410
416
  ### 品質チェック
411
417
 
@@ -812,10 +818,25 @@ reports/
812
818
 
813
819
  ---
814
820
 
821
+ ## 今後の実装予定 (Roadmap)
822
+
823
+ README/docs 上で言及があるが、現状 partial 実装か user 側 wiring に依存しているもの。それぞれ Work Item として `docs/inception/_cross/WI-XXX/description.md` 配下に起票済み。
824
+
825
+ | Work Item | タイトル | 概要 |
826
+ |---|---|---|
827
+ | **[WI-031](docs/inception/_cross/WI-031/description.md)** | CI template の二系統統一 + `phasegate init --with-ci` | bundled template と `ci:generate-template` 出力が cron / GitHub Issue 自動化ロジックで乖離。さらに `phasegate init` は workflow を自動配置しないため L4 が user 配置に依存している。両方を解消する。|
828
+ | **[WI-032](docs/inception/_cross/WI-032/description.md)** | AGENTS.md / CLAUDE.md auto-refresh パイプライン | `ci:migrate-agents-md` の一回限り CLI は存在するが定期実行機構が無く、CLAUDE.md は完全な手動メンテ。週次 workflow + CLAUDE.md template-driven 再生成(user 編集領域を保護)を追加する。|
829
+ | **[WI-033](docs/inception/_cross/WI-033/description.md)** | `doc-freshness` / `pointer-validation` を L4 validator に昇格 | 機能は `p2:check-freshness` / `p2:validate-pointers` CLI として実装済みだが、L4 validator として登録されておらず `validate --layer L4` で走らない。validator-system に編入する。|
830
+ | **[WI-034](docs/inception/_cross/WI-034/description.md)** | L0 legacy validator (`L0-001` / `L0-002`) の撤去 | FUSE 構想の名残として残存している `fuse-hook-config` / `fuse-mount-status` の definition を削除。実態の L0 は agent-integration の runtime hook + Husky として既に確立しているため、誤解を招く legacy を整理する。|
831
+
832
+ L3 Nyquist Validation の `requirement-test-matrix.json` 自動生成パイプラインも依然未完成であり、§5層防御モデル の L3 Nyquist 節を参照のこと。
833
+
834
+ ---
835
+
815
836
  ## 開発者向けドキュメント
816
837
 
817
838
  phasegate 自体の開発(内部アーキテクチャ、回帰テスト、リリース手順等)については [DEVELOPMENT.ja.md](DEVELOPMENT.ja.md) を参照してください。
818
839
 
819
840
  ---
820
841
 
821
- *Last updated: 2026-04-22 -- v0.66.0*
842
+ *Last updated: 2026-04-25 -- v0.110.0*
package/README.md CHANGED
@@ -63,30 +63,38 @@ Launch your AI agent and run the `/product-architect` skill to begin.
63
63
 
64
64
  ```
65
65
  +------------------------------------------------------------------+
66
- | L0 HOOKS ENGINE Agent hook configuration |
66
+ | L0 AGENT RUNTIME HOOKS Claude Code / Codex hooks |
67
+ | PreToolUse (Write/Edit/Bash block + guide), PostToolUse |
68
+ | (auto lint/format), Stop (ReentryGuard + complete-check), |
69
+ | SessionStart, UserPromptSubmit. Plus Husky .husky/pre-commit |
70
+ | and .husky/commit-msg (Work-Item trailer enforcement). |
67
71
  +------------------------------------------------------------------+
68
72
  | L1 EDITOR TIME Biome AST rules |
69
73
  | require-unit-comment, no-layer-violation, no-any-abuse, |
70
74
  | enforce-folder-structure, no-ghost-file, no-code-duplication |
71
75
  +------------------------------------------------------------------+
72
76
  | L2 PRE-COMMIT Validators |
73
- | phase-gate, metadata completeness, test-quality (AAA pattern) |
77
+ | phase-gate, metadata completeness, story-reflection, |
78
+ | test-quality (AAA pattern) |
74
79
  +------------------------------------------------------------------+
75
80
  | L3 CI/CD Validators |
76
81
  | security, performance, coverage threshold, nyquist traceability |
77
82
  +------------------------------------------------------------------+
78
- | L4 SCHEDULED Validators |
79
- | drift-detection, consistency-check, dead-code analysis |
83
+ | L4 SCHEDULED Validators (default off) |
84
+ | drift-detection, consistency-check, dead-code analysis, |
85
+ | doc-freshness, pointer-validation |
80
86
  +------------------------------------------------------------------+
81
87
  ```
82
88
 
83
89
  | Layer | Trigger | Key Checks |
84
90
  |---|---|---|
85
- | L0 | Agent hooks | Hook config validation, gate checks |
86
- | L1 | Editor save / lint | Import graph, layer violations, AI anti-patterns |
87
- | L2 | Pre-commit | Phase gate, `@unit`/`@layer` metadata, test quality |
91
+ | 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 |
92
+ | L1 | Editor save / `phasegate lint` | `@unit` / `@layer` metadata, layer violations, AI anti-patterns, dead code |
93
+ | L2 | Pre-commit (also evaluated inside PreToolUse at L0) | Phase gate, metadata completeness, `@work-item-id` reflection (`L2-STORY-REFLECTION`), test quality |
88
94
  | L3 | CI/CD pipeline | Security, performance, coverage (90%/95%), requirements traceability |
89
- | L4 | Scheduled (weekly) | Design-code drift, cross-document consistency, dead code |
95
+ | 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 |
96
+
97
+ > 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.
90
98
 
91
99
  ---
92
100
 
@@ -368,6 +376,21 @@ Additional resources:
368
376
 
369
377
  ---
370
378
 
379
+ ## Roadmap (Planned but not yet implemented)
380
+
381
+ The following are documented behaviors that are partially implemented or rely on user-side wiring. Each is tracked as a Work Item and will land in a future minor release. Inception docs live under `docs/inception/_cross/WI-XXX/description.md`.
382
+
383
+ | Work Item | Title | Why it matters |
384
+ |---|---|---|
385
+ | **[WI-031](docs/inception/_cross/WI-031/description.md)** | CI template unification + `phasegate init --with-ci` | Today the bundled YAML and the `ci:generate-template` output diverge (different cron schedule, only the bundled one creates GitHub Issues). `phasegate init` does not deploy the workflow, so L4 only runs after the user manually copies the file. WI-031 unifies the two paths and adds an opt-in deploy flag. |
386
+ | **[WI-032](docs/inception/_cross/WI-032/description.md)** | AGENTS.md / CLAUDE.md auto-refresh pipeline | `ci:migrate-agents-md` exists as a one-shot CLI but there is no scheduled job, and CLAUDE.md is fully hand-maintained. WI-032 adds an `auto-refresh-agent-context` workflow plus a template-driven CLAUDE.md regenerator that preserves user-owned sections. |
387
+ | **[WI-033](docs/inception/_cross/WI-033/description.md)** | Promote `doc-freshness` / `pointer-validation` to L4 validators | Both capabilities exist as `p2:check-freshness` / `p2:validate-pointers` CLI commands but are not registered as L4 validators, so `validate --layer L4` skips them. WI-033 plumbs them through `validator-system` so they run via the standard L4 path and presets. |
388
+ | **[WI-034](docs/inception/_cross/WI-034/description.md)** | Retire legacy L0 validators (`L0-001` / `L0-002`) | The `fuse-hook-config` / `fuse-mount-status` validator IDs are leftovers from an earlier FUSE-based design. They are disabled by default and have no actual implementation behind them. WI-034 removes them and lets the agent-integration runtime hooks be the sole L0 surface. |
389
+
390
+ `requirement-test-matrix.json` auto-generation for L3 Nyquist Validation is also a known gap; see the L3 section above.
391
+
392
+ ---
393
+
371
394
  ## Contributing
372
395
 
373
396
  Contributions are welcome. See [DEVELOPMENT.md](DEVELOPMENT.md) for internal architecture, regression tests, and release procedures.
@@ -19,21 +19,47 @@ Layers are additive: L1 rules still apply when L3 runs. The earlier a defect is
19
19
 
20
20
  ---
21
21
 
22
- ## L0: Hooks Engine
22
+ ## L0: Agent Runtime Hooks + Git Hooks
23
23
 
24
- The Hooks Engine validates agent hook configuration and enforces completion gates before work can proceed.
24
+ 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:
25
25
 
26
- | Rule | Description |
27
- |------|-------------|
28
- | **hook-config** | Validates `.harness-hooks.yml` configuration structure and semantics |
29
- | **gate-check** | Verifies that all required completion gates have been satisfied |
26
+ ### L0-A: AI agent runtime hooks (`agent-integration` unit)
30
27
 
31
- **Command:**
28
+ 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.
29
+
30
+ | Hook | Matcher / Trigger | Responsibility |
31
+ |------|-------------------|----------------|
32
+ | **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. |
33
+ | **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`). |
34
+ | **stop-hook** | Agent `Stop` | Activates `ReentryGuard` to prevent infinite hook loops, then runs `phasegate:complete-check` (L2–L4 aggregate) as a final gate. |
35
+ | **session-start-hook** | `startup` / `resume` | Loads session context for Codex (project status summary, recent changes). |
36
+ | **user-prompt-submit-hook** | `UserPromptSubmit` | Refreshes status so the next prompt sees the current harness state. |
37
+
38
+ Command-line entry points exist for debugging / CI use:
39
+
40
+ ```bash
41
+ npx phasegate hook pre-tool-use < payload.json
42
+ npx phasegate hook post-tool-use < payload.json
43
+ npx phasegate hook stop < payload.json
44
+ ```
45
+
46
+ ### L0-B: Husky git hooks
47
+
48
+ Deployed by `phasegate init --with-husky` into `.husky/`.
49
+
50
+ | Hook file | Invokes | Responsibility |
51
+ |-----------|---------|----------------|
52
+ | **.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. |
53
+ | **.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. |
54
+
55
+ ### About the `validate --layer L0` CLI
32
56
 
33
57
  ```bash
34
58
  npx phasegate validate --layer L0
35
59
  ```
36
60
 
61
+ `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.
62
+
37
63
  ---
38
64
 
39
65
  ## L1: Editor Time — Biome AST Rules
@@ -112,13 +138,17 @@ npx phasegate validate --layer L3
112
138
 
113
139
  ## L4: Scheduled Validators
114
140
 
115
- L4 validators run on a weekly schedule. They detect slow-moving drift that accumulates over time.
141
+ L4 validators are designed to run on a weekly schedule and detect slow-moving drift that accumulates over time.
116
142
 
117
- | Validator | Description |
118
- |-----------|-------------|
119
- | **drift-detect** | Bidirectional design-code drift detection. Compares design documents against the actual codebase to find divergence in either direction. |
120
- | **consistency-check** | Cross-document layer consistency. Ensures that references between design documents, ADRs, and code remain coherent. |
121
- | **dead-code** | Detects unused exports and unreachable code that should be removed. |
143
+ > **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.
144
+
145
+ | Validator | ID | Description |
146
+ |-----------|-----|-------------|
147
+ | **drift-detect** | L4-001 | Bidirectional design-code drift detection. Compares design documents against the actual codebase to find divergence in either direction. |
148
+ | **consistency-check** | L4-002 | Cross-document layer consistency. Ensures that references between design documents, ADRs, and code remain coherent. |
149
+ | **dead-code** | L4-003 | Detects unused exports and unreachable code that should be removed. |
150
+
151
+ > **Note (2026-04-25)**: `doc-freshness` and `pointer-validation` capabilities exist as standalone CLI commands `p2:check-freshness` and `p2:validate-pointers` (implemented in the `phase2-extensions` unit), **not as L4 validators yet**. Promoting them to L4-004 / L4-005 is tracked as **WI-033**. Until that lands, run them explicitly via `npx phasegate p2:check-freshness` / `p2:validate-pointers`.
122
152
 
123
153
  **Command:**
124
154
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "phasegate",
3
- "version": "0.108.0",
3
+ "version": "0.110.0",
4
4
  "packageManager": "pnpm@10.30.1",
5
5
  "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
6
6
  "license": "Apache-2.0",