phasegate 0.108.0 → 0.109.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.
Files changed (5) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/README.ja.md +5 -3
  3. package/README.md +16 -8
  4. package/docs/guide/layer-model.md +38 -8
  5. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.109.0] - 2026-04-25
11
+
12
+ ### Documentation
13
+
14
+ - **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 を一致させた。
15
+ - `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` デフォルトであることも補足。
16
+ - `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 一覧に追加。
17
+ - `CLAUDE.md`: 「L0 FUSEフック検証」記述を「L0 legacy validator（現状 enabled: false）」に訂正し、実運用の L0 経路（agent-integration hook + Husky）を補足。
18
+
19
+ Source code 改変なし。`list-errors --layer L0` の `L0-001` / `L0-002` definition は legacy として残置（削除は別 WI）。
20
+
10
21
  ## [0.108.0] - 2026-04-25
11
22
 
12
23
  ### 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
 
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
 
package/docs/guide/layer-model.md CHANGED
@@ -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.
142
+
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.
116
144
 
117
145
  | Validator | Description |
118
146
  |-----------|-------------|
119
147
  | **drift-detect** | Bidirectional design-code drift detection. Compares design documents against the actual codebase to find divergence in either direction. |
120
148
  | **consistency-check** | Cross-document layer consistency. Ensures that references between design documents, ADRs, and code remain coherent. |
121
149
  | **dead-code** | Detects unused exports and unreachable code that should be removed. |
150
+ | **doc-freshness** | Flags design documents whose last update is older than a configured threshold while the corresponding code has diverged. |
151
+ | **pointer-validation** | Verifies that relative-path pointers inside design docs resolve to files that actually exist. |
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.109.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",