phasegate 0.83.0 → 0.107.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 (78) hide show
  1. package/CHANGELOG.md +313 -0
  2. package/README.ja.md +15 -7
  3. package/README.md +24 -4
  4. package/docs/ADR/ADR-014-presentation-domain-dependency.md +82 -0
  5. package/docs/ADR/ADR-015-architecture-preset.md +183 -0
  6. package/docs/guide/codex-integration.md +7 -2
  7. package/docs/guide/installation.md +10 -2
  8. package/docs/guide/preset-selection.md +170 -0
  9. package/docs/guide/quick-vs-full-mode.md +3 -3
  10. package/docs/guide/retrofit-adoption.md +19 -2
  11. package/docs/guide/skills-overview.md +1 -1
  12. package/package.json +7 -1
  13. package/scripts/harness/adr-foundation/application/dto/application-errors.ts +0 -13
  14. package/scripts/harness/agent-integration/application/usecases/handle-pre-tool-use-usecase.ts +108 -100
  15. package/scripts/harness/agent-integration/domain/ports/error-guidance-query-port.ts +0 -8
  16. package/scripts/harness/agent-integration/domain/ports/phase-gate-query-port.ts +3 -3
  17. package/scripts/harness/agent-integration/domain/value-objects/write-target-scope.ts +26 -30
  18. package/scripts/harness/agent-integration/infrastructure/adapters/file-system-story-reflection-query-adapter.ts +6 -2
  19. package/scripts/harness/biome-ast-engine/application/dto/analyze-import-graph-input.ts +3 -0
  20. package/scripts/harness/biome-ast-engine/application/dto/resolve-enabled-rules-output.ts +2 -0
  21. package/scripts/harness/biome-ast-engine/application/mappers/resolve-enabled-rules-output-mapper.ts +4 -1
  22. package/scripts/harness/biome-ast-engine/application/usecases/analyze-import-graph-usecase.ts +4 -1
  23. package/scripts/harness/biome-ast-engine/application/usecases/execute-lint-usecase.ts +2 -0
  24. package/scripts/harness/biome-ast-engine/application/usecases/resolve-enabled-rules-usecase.ts +31 -3
  25. package/scripts/harness/biome-ast-engine/composition-root.ts +10 -2
  26. package/scripts/harness/biome-ast-engine/domain/ports/rule-config-provider-port.ts +16 -0
  27. package/scripts/harness/biome-ast-engine/domain/ports/source-module-analyzer-port.ts +5 -1
  28. package/scripts/harness/biome-ast-engine/domain/services/lint-runner.ts +5 -1
  29. package/scripts/harness/biome-ast-engine/domain/services/rule-definition-registry.ts +1 -0
  30. package/scripts/harness/biome-ast-engine/domain/value-objects/architecture-spec.ts +38 -0
  31. package/scripts/harness/biome-ast-engine/domain/value-objects/layer-boundary.ts +7 -8
  32. package/scripts/harness/biome-ast-engine/domain/value-objects/layer-name.ts +15 -23
  33. package/scripts/harness/biome-ast-engine/domain/value-objects/source-module-snapshot.ts +11 -4
  34. package/scripts/harness/biome-ast-engine/infrastructure/adapters/harness-config-provider-adapter.ts +29 -3
  35. package/scripts/harness/biome-ast-engine/infrastructure/adapters/typescript-source-module-analyzer-adapter.ts +22 -15
  36. package/scripts/harness/biome-ast-engine/infrastructure/mappers/source-module-snapshot-mapper.ts +26 -17
  37. package/scripts/harness/config-foundation/application/dto/resolved-config-output.ts +1 -0
  38. package/scripts/harness/config-foundation/application/usecases/load-resolved-config-use-case.ts +34 -2
  39. package/scripts/harness/config-foundation/application/usecases/migrate-schema-use-case.ts +89 -0
  40. package/scripts/harness/config-foundation/composition-root.ts +8 -0
  41. package/scripts/harness/config-foundation/domain/harness-config.ts +6 -0
  42. package/scripts/harness/config-foundation/domain/services/architecture-resolution-service.ts +257 -0
  43. package/scripts/harness/config-foundation/domain/value-objects/architecture-config.ts +66 -0
  44. package/scripts/harness/config-foundation/domain/value-objects/architecture-preset-catalog.ts +75 -0
  45. package/scripts/harness/config-foundation/infrastructure/schemas/harness-config-v3.schema.json +546 -0
  46. package/scripts/harness/config-foundation/infrastructure/validators/ajv-config-schema-validator.ts +18 -6
  47. package/scripts/harness/config-foundation/presentation/cli/migrate-schema-command-handler.ts +83 -0
  48. package/scripts/harness/integrations/pre-commit.ts +211 -52
  49. package/scripts/harness/main.ts +460 -340
  50. package/scripts/harness/phase-dependency-model/domain/ports/story-reflection-file-system-port.ts +2 -4
  51. package/scripts/harness/phase-dependency-model/domain/services/story-reflection-checker.ts +54 -17
  52. package/scripts/harness/phase-dependency-model/infrastructure/filesystem/file-system-story-reflection-adapter.ts +154 -36
  53. package/scripts/harness/setup/skill-deployer.ts +140 -102
  54. package/scripts/harness/skill-quality/domain/errors/skill-quality-error.ts +24 -23
  55. package/scripts/harness/skill-quality/domain/value-objects/commit-message.ts +23 -7
  56. package/scripts/harness/traceability-model/application/usecases/apply-work-item-migration-usecase.ts +52 -0
  57. package/scripts/harness/traceability-model/application/usecases/plan-work-item-migration-usecase.ts +29 -0
  58. package/scripts/harness/traceability-model/application/usecases/validate-design-story-annotations-usecase.ts +83 -18
  59. package/scripts/harness/traceability-model/composition-root.ts +48 -30
  60. package/scripts/harness/traceability-model/domain/ports/design-document-port.ts +9 -15
  61. package/scripts/harness/traceability-model/domain/ports/work-item-migration-apply-port.ts +11 -0
  62. package/scripts/harness/traceability-model/domain/ports/work-item-migration-source-port.ts +9 -0
  63. package/scripts/harness/traceability-model/domain/services/metadata-validator.ts +1 -1
  64. package/scripts/harness/traceability-model/domain/services/work-item-migration-planner.ts +162 -0
  65. package/scripts/harness/traceability-model/domain/value-objects/story-id.ts +3 -3
  66. package/scripts/harness/traceability-model/domain/value-objects/work-item-frontmatter.ts +57 -0
  67. package/scripts/harness/traceability-model/domain/value-objects/work-item-migration-candidate.ts +47 -0
  68. package/scripts/harness/traceability-model/infrastructure/gateways/file-system-work-item-migration-apply-gateway.ts +110 -0
  69. package/scripts/harness/traceability-model/infrastructure/gateways/file-system-work-item-migration-source-gateway.ts +182 -0
  70. package/scripts/harness/traceability-model/infrastructure/gateways/markdown-design-document-gateway.ts +29 -43
  71. package/scripts/harness/traceability-model/infrastructure/parsers/story-catalog-parser.ts +2 -2
  72. package/scripts/harness/traceability-model/infrastructure/parsers/work-item-frontmatter-parser.ts +136 -0
  73. package/scripts/harness/traceability-model/presentation/cli/migrate-work-items-command-handler.ts +186 -0
  74. package/skills/quick-implementor/SKILL.md +17 -1
  75. package/templates/.husky/commit-msg +1 -0
  76. package/scripts/harness/adr-foundation/application/dto/seed-adr-definition.ts +0 -21
  77. package/scripts/harness/adr-foundation/application/usecases/seed-initial-adrs-use-case.ts +0 -84
  78. package/scripts/harness/adr-foundation/infrastructure/seeds/initial-adr-definitions.ts +0 -161
@@ -0,0 +1,183 @@
1
+ # ADR-015: アーキテクチャスタイルを preset 化し、PhaseGate を複数アーキに対応させる
2
+
3
+ ## Status
4
+
5
+ Accepted — 2026-04-23
6
+
7
+ ## Context
8
+
9
+ PhaseGate は「AI 非依存の品質防御ツールキット」を標榜するが、L1 層(Biome AST rule)の依存方向検査は Clean Architecture 4 層(`domain / application / infrastructure / presentation`)を前提として**ハードコード**されている。
10
+
11
+ ### ハードコードの実体(ISSUE-014 発見契機)
12
+
13
+ **`scripts/harness/biome-ast-engine/domain/value-objects/layer-name.ts:6`**:
14
+
15
+ ```typescript
16
+ export type LayerNameValue = 'domain' | 'application' | 'infrastructure' | 'presentation';
17
+ ```
18
+
19
+ **同ファイル:15-20**(ADR-014 適用後):
20
+
21
+ ```typescript
22
+ const ALLOWED_DEPENDENCIES = {
23
+ domain: ['domain'],
24
+ application: ['application', 'domain'],
25
+ infrastructure: ['infrastructure', 'application', 'domain'],
26
+ presentation: ['presentation', 'application', 'domain'],
27
+ };
28
+ ```
29
+
30
+ 層名・依存方向のいずれもコード内固定で、`phasegate.config.json` から変更する手段がない。
31
+
32
+ ### 影響範囲
33
+
34
+ | 導入対象 PJ | 発生する摩擦 |
35
+ |---|---|
36
+ | Onion(`domain / application / interface`) | `@layer interface` で `InvalidLayerNameError` |
37
+ | Hexagonal(`core / ports / adapters`) | 層名が全て未知、L1-001/L1-002 全件違反 |
38
+ | MVC / N-tier(`controller / service / repository`) | L1-003/L1-004 が無意味に発火 |
39
+ | Flat スクリプト・CLI ツール | `@layer` 強制が過剰 |
40
+ | 既存 PJ への retrofit(ISSUE-007) | baseline で grandfather できるが、新規ファイルに Clean 形状を強制 |
41
+
42
+ 「AI 非依存」という標語は達成済みだが、「Clean Architecture 前提」という暗黙制約が残存しており、PhaseGate の採用範囲を狭めている。
43
+
44
+ ### 関連する先行決定
45
+
46
+ - **ADR-005** — Hexagonal Architecture の採用。PhaseGate 自身の構造的選択としては維持
47
+ - **ADR-014** — `presentation → domain` を Robert C. Martin 版 Clean Architecture 解釈で許容。本 ADR と整合(`clean` preset の既定挙動として組み込み)
48
+
49
+ ## Decision
50
+
51
+ `phasegate.config.json` に `architecture` セクションを新設し、**アーキテクチャスタイルを preset ベースで選択可能**にする。
52
+
53
+ ### schema v3 概要
54
+
55
+ ```json
56
+ {
57
+ "architecture": {
58
+ "preset": "clean",
59
+ "layers": ["domain", "application", "infrastructure", "presentation"],
60
+ "allowedDependencies": {
61
+ "domain": ["domain"],
62
+ "application": ["application", "domain"],
63
+ "infrastructure": ["infrastructure", "application", "domain"],
64
+ "presentation": ["presentation", "application", "domain"]
65
+ },
66
+ "metadataTags": {
67
+ "layer": "@layer",
68
+ "unit": "@unit"
69
+ },
70
+ "layerDetection": {
71
+ "byPath": true,
72
+ "byTag": true
73
+ }
74
+ }
75
+ }
76
+ ```
77
+
78
+ `preset` を指定すれば層構成と依存規則がプリセットから注入され、`custom` 選択時のみ `layers` / `allowedDependencies` のユーザー定義が必須となる。
79
+
80
+ 詳細なスキーマ案と各 preset の層・依存定義は [`docs/inception/issues/ISSUE-014/wave1_schema_proposal.md`](../inception/issues/ISSUE-014/wave1_schema_proposal.md) を参照。
81
+
82
+ ### 採用する preset(7 種)
83
+
84
+ | `preset` | 層構成 | 想定用途 |
85
+ |---|---|---|
86
+ | `clean`(default) | domain / application / infrastructure / presentation | 大規模 BE、DDD 採用 PJ(PhaseGate 自身の構造、ADR-014 準拠) |
87
+ | `strict-ddd` | 同上(依存ルールのみ厳格) | Presentation → Domain 直接依存を禁じたい PJ(ADR-014 opt-out) |
88
+ | `onion` | domain / application / interface | Onion Architecture PJ |
89
+ | `hexagonal` | core / ports / adapters | Ports & Adapters 採用 PJ |
90
+ | `layered` | controller / service / repository | MVC / N-tier PJ |
91
+ | `flat` | (層なし) | 小規模スクリプト、CLI ツール、プロトタイプ |
92
+ | `custom` | ユーザー定義 | 独自アーキ |
93
+
94
+ ### `project.preset` との関係(直交)
95
+
96
+ 既存 schema v2 には `project.preset: "minimal" | "standard" | "strict"` が存在するが、本 ADR で追加する `architecture.preset` とは**完全に直交**する概念である:
97
+
98
+ | 既存 `project.preset` | 新設 `architecture.preset` |
99
+ |---|---|
100
+ | L0〜L4 レイヤー**各防御段**の有効化プリセット(どの validator を使うか) | 依存方向検査の**アーキスタイル**プリセット(どの層構成を採るか) |
101
+ | 例: `strict` = L0-L4 全有効 | 例: `clean` = 4 層 Clean Architecture |
102
+
103
+ 両者は独立に選択可能で、例えば `project.preset: "minimal"` + `architecture.preset: "hexagonal"` の組み合わせは有効。混同を避けるため、ドキュメント・CLI メッセージでは「防御プリセット / アーキプリセット」と区別して呼称する方針とする(Wave 6 のガイドで徹底)。
104
+
105
+ ### ADR-005(Hexagonal 採用)との関係
106
+
107
+ ADR-005 では「PhaseGate は Hexagonal Architecture を採用する」と記録したが、実際のコードは `domain / application / infrastructure / presentation` の 4 層構成で、これは Clean Architecture の一般的な命名。**本 ADR は ADR-005 を否定しない**:Hexagonal の「core を外部詳細から隔離する」哲学は 4 層構成でも成立し、PhaseGate の `domain` は Hexagonal の `core` に相当する。preset 名としては命名が近い `clean` を選ぶことで、ADR-005 の哲学を維持しつつ preset カテゴリにフィットさせる。外部 PJ が真に 3 層 Hexagonal(`core / ports / adapters`)で記述したい場合は `hexagonal` preset を選べる。
108
+
109
+ ### preset + 明示 layers 併記時の解決規則
110
+
111
+ - **`preset: "custom"` 以外 + 明示 `layers` / `allowedDependencies`**: **ユーザー明示値が preset 既定を override** する(partial override も許容)。`preset` は「出発点」として扱われ、明示フィールドで上書きできるが、整合性は引き続き schema v3 の semantic validation で検査される
112
+ - **`preset: "custom"`**: `layers` と `allowedDependencies` は必須入力。schema validation で required として強制
113
+
114
+ ### ADR-014 暗黙デフォルト変更との連続性
115
+
116
+ v0.86.0(ADR-014 適用)以降、`ALLOWED_DEPENDENCIES.presentation` に `'domain'` が追加され、既定挙動として `presentation → domain` が許容化された。本 ADR はこの挙動を `clean` preset の既定として**そのまま引き継ぐ**。v0.85.0 以前の厳格 DDD 挙動を継続したい導入 PJ は、v0.92.0 以降明示的に `architecture.preset: "strict-ddd"` を指定する必要がある点を Wave 6 ガイドで警告する。
117
+
118
+ ### `flat` preset の挙動
119
+
120
+ 層関連 L1 rule を自動で無効化し、汎用 rule のみ残す:
121
+
122
+ | rule | flat での挙動 |
123
+ |---|---|
124
+ | L1-001 require-unit-comment | 自動無効化 |
125
+ | L1-002 require-layer-comment | 自動無効化 |
126
+ | L1-003 no-layer-violation | 自動無効化 |
127
+ | L1-004 enforce-folder-structure | 自動無効化 |
128
+ | L1-005 no-any-abuse | 有効維持 |
129
+ | L1-006 no-ghost-file | 有効維持 |
130
+ | L1-007 no-comment-flood | 有効維持 |
131
+ | L1-008 no-code-duplication | 有効維持 |
132
+
133
+ ### メタデータタグの可変化
134
+
135
+ `@layer` / `@unit` というタグ名自体も `metadataTags` で差し替え可能とする。これにより、社内規約で `@tier` / `@module` 等を使う PJ にも対応できる。
136
+
137
+ ### 下位互換戦略
138
+
139
+ - **schema v2 → v3 識別**: 設定ファイルに明示的な `$schemaVersion` フィールドは**追加しない**(既存 config の無害変更を避ける)。代わりに**構造検出**を採用し、`architecture` キーが存在すれば v3 ロード、存在しなければ v2 互換モード(`preset: "clean"` を暗黙適用)とする。Wave 3 で loader に `detectSchemaVersion()` を実装
140
+ - **自動マイグレーション**: `architecture` セクション未指定時は `preset: "clean"` 相当のデフォルトが自動適用される(挙動不変)。ただし v0.86.0 未満から upgrade する user は ADR-014 の既定変更で暗黙に presentation→domain が許容されるため、明示的な変更通知を CHANGELOG / Wave 6 ガイドで提示
141
+ - **Phase 毎 rollout**: Wave 2〜6 で段階的に `LayerName` / `LayerBoundary` / schema validator を移行。各 Wave 独立にリリース可能
142
+ - **PhaseGate レポ自身**: `preset: "clean"` を明示設定(ドッグフード)。既存の Hexagonal 哲学(ADR-005)は `domain` 層を `core` とみなすことで整合
143
+
144
+ ## Consequences
145
+
146
+ ### ポジティブ
147
+
148
+ - Onion / Hexagonal / MVC / 小規模スクリプトなど、Clean 以外のアーキを採用する PJ への導入障壁が消滅
149
+ - retrofit-adoption(ISSUE-007)の延長で「既存アーキを尊重しつつ PhaseGate を被せる」ユースケースが成立
150
+ - メタデータタグ可変化で社内規約と衝突せず導入可能
151
+ - ADR-014(`presentation → domain` 許容)の厳格派向け opt-out が `strict-ddd` preset として提供可能になる(Philosophical tension の解消)
152
+
153
+ ### ネガティブ / トレードオフ
154
+
155
+ - **実装負荷**: `LayerName` / `LayerBoundary` / `biome-ast-engine` 配下の全 rule が config 注入を受けるため、影響範囲は広い(推定 ~4d、Wave 分割で管理)
156
+ - **preset の選定判断コスト**: 導入 PJ 側が「どの preset を選ぶか」を初回に判断する必要がある
157
+ - **緩和策**: README / retrofit-adoption.md に preset 選定フローチャートを追加(Wave 6)
158
+ - **フレームワーク固有構造(Django apps/, Rails MVC 等)の自動検出は非対応**: 層名とパス対応は `architecture.layers` で宣言ベース
159
+ - **判断**: 自動検出は phasegate の「明示的な品質防御」哲学と整合しない。宣言を強制する方が誤検出が少ない
160
+
161
+ ### スコープ外(本 ADR で扱わない)
162
+
163
+ - フレームワーク固有の自動層推論(Django / Rails / NestJS 等)
164
+ - ランタイム強制(依存方向違反の実行時 throw)— lint 時のみ
165
+ - 既存コードの層名リネーム自動変換ツール(`@layer domain` → `@tier core` 等)
166
+ - DDD 戦術パターン(Aggregate / Repository / UseCase 命名規約)の preset 化 — 別 issue
167
+
168
+ ## Migration
169
+
170
+ schema v3 移行の詳細は Wave 2 で `config-foundation` の migration script として実装する。本 ADR 時点での移行方針:
171
+
172
+ 1. `architecture` セクション未指定 → `preset: "clean"` を暗黙適用(既存挙動維持)
173
+ 2. `architecture.preset` のみ指定 → preset から layers / allowedDependencies を展開
174
+ 3. `architecture.preset: "custom"` → `layers` と `allowedDependencies` を必須入力として validate
175
+
176
+ ## 関連
177
+
178
+ - **ADR-005** — Hexagonal Architecture 採用(PhaseGate 自身の構造として維持、他 PJ には preset 化で選択肢提供)
179
+ - **ADR-014** — `presentation → domain` 許容。`clean` preset の既定挙動として組み込み、`strict-ddd` で opt-out 提供
180
+ - **ISSUE-014** — 本 ADR を駆動する issue。Wave 分割実装(Wave 1: 本 ADR + schema 設計, Wave 2: LayerName 注入, Wave 3: schema v3 実装, Wave 4: dogfood, Wave 5: custom/ドキュメント)
181
+ - **ISSUE-007 retrofit-adoption** — 既存 PJ への phasegate 導入。本 ADR により Clean 以外でも受け入れ可能になり、retrofit の適用範囲が拡大
182
+ - **`scripts/harness/biome-ast-engine/domain/value-objects/layer-name.ts:6,15-20`** — 現状のハードコード実体、Wave 2 の改修対象
183
+ - **`scripts/harness/config-foundation/infrastructure/schemas/harness-config-v2.schema.json`** — schema v3 の拡張対象、Wave 3 で改修
@@ -7,15 +7,20 @@ Phasegate supports [OpenAI Codex CLI](https://developers.openai.com/codex/cli) t
7
7
  ### Quick setup (recommended)
8
8
 
9
9
  ```bash
10
- # 1. Initialize with Codex agent support
10
+ # 1. Initialize the project for Codex
11
11
  npx phasegate init --name my-project --agent codex --with-husky
12
12
 
13
- # 2. Enable Codex hooks feature flag
13
+ # 2. Enable the Codex CLI feature flag manually
14
14
  codex features enable codex_hooks
15
15
  ```
16
16
 
17
17
  For dual-agent projects (Claude + Codex), use `--agent both`.
18
18
 
19
+ Responsibility split:
20
+
21
+ - `phasegate init --agent codex` sets up **project-local artifacts** such as `phasegate.config.json`, `skills/`, `.codex/hooks.json`, and `.codex/skills`
22
+ - `codex features enable codex_hooks` updates the **Codex CLI user environment** and is intentionally left as a manual step
23
+
19
24
  ### Manual setup
20
25
 
21
26
  Alternatively, set up Codex integration manually:
@@ -36,7 +36,13 @@ npm install
36
36
  npx phasegate init --name <project-name>
37
37
  ```
38
38
 
39
- This deploys 28 skills to `.claude/skills/` and generates `phasegate.config.json`.
39
+ This deploys 28 skills to `skills/`, creates the agent-facing skill links (for example `.claude/skills/` or `.codex/skills/`), and generates `phasegate.config.json`.
40
+
41
+ For Codex, project initialization stops at the project boundary. After `npx phasegate init --agent codex`, enable the Codex CLI feature flag manually:
42
+
43
+ ```bash
44
+ codex features enable codex_hooks
45
+ ```
40
46
 
41
47
  ### 2. Copy design principle documents
42
48
 
@@ -69,7 +75,9 @@ npx phasegate update-skills
69
75
 
70
76
  ```
71
77
  node_modules/
72
- .claude/skills/ # regenerated by npx phasegate init
78
+ skills/ # regenerated by npx phasegate init
79
+ .claude/skills/ # symlink to ../skills when Claude is enabled
80
+ .codex/skills/ # symlink to ../skills when Codex is enabled
73
81
  dist/
74
82
  reports/
75
83
  .harness/
@@ -0,0 +1,170 @@
1
+ # Architecture Preset Selection Guide
2
+
3
+ phasegate の `phasegate.config.json` には `architecture.preset` を通じて「そのプロジェクトが採用しているアーキテクチャスタイル」を明示する。L1-003 (`no-layer-violation`) / L1-004 (`enforce-folder-structure`) はこの preset を参照して層名と依存方向を判定する。
4
+
5
+ preset の選択が正しくないと、本来合法な import が violation として検出される / 本来検出されるべき違反が通過する等の誤判定が発生する。本ガイドは preset 選択の判断基準と実例を示す。
6
+
7
+ ---
8
+
9
+ ## 用語の整理(呼称の混同を避ける)
10
+
11
+ phasegate には 2 系統の「プリセット」概念があり、役割が異なる:
12
+
13
+ | 系統 | 概念 | 設定キー | 例 |
14
+ |------|------|---------|----|
15
+ | **防御プリセット** | L3 CI で検査強度を選ぶ | `ci.preset` | `strict` / `lenient` |
16
+ | **アーキプリセット** | L1 の層構造と依存方向を定義 | `architecture.preset` | `clean` / `onion` / `hexagonal` / `layered` / `flat` / `strict-ddd` / `custom` |
17
+
18
+ 本ガイドの対象は **アーキプリセット**。CI 強度の選定は `docs/guide/configuration.md` を参照。
19
+
20
+ ---
21
+
22
+ ## 7 preset の早見表
23
+
24
+ | preset | 層構成 | 典型的な採用対象 |
25
+ |--------|--------|------------------|
26
+ | `clean` (default) | `domain / application / infrastructure / presentation` | Clean Architecture / AIDLC フルハーネス構成 |
27
+ | `strict-ddd` | `clean` + 循環依存禁止を厳格化 | DDD 重視の新規 PJ |
28
+ | `onion` | `domain / application / interface` | Onion Architecture |
29
+ | `hexagonal` | `core / ports / adapters` | Hexagonal / Ports-and-Adapters |
30
+ | `layered` | `presentation / business / data` | 古典的 3 層レイヤード |
31
+ | `flat` | 層分割なし | 小規模スクリプト・CLI ツール / retrofit 導入初期 |
32
+ | `custom` | `layers` + `allowedDependencies` を明示指定 | どの既成プリセットにも当てはまらない PJ |
33
+
34
+ 各 preset の詳細な層行列は `docs/inception/issues/ISSUE-014/wave1_schema_proposal.md §1.2` を参照。
35
+
36
+ ---
37
+
38
+ ## 選択フロー
39
+
40
+ ```
41
+ 1. 既存 PJ か新規 PJ か?
42
+ ├─ 新規 → Q2 へ
43
+ └─ 既存 → retrofit-adoption.md を先に参照 / 初期は `flat` でも可
44
+
45
+ 2. DDD / Clean Architecture を明示採用している?
46
+ ├─ はい → Q3 へ
47
+ └─ いいえ → Q4 へ
48
+
49
+ 3. 4 層分離(domain / application / infrastructure / presentation)を守っている?
50
+ ├─ はい → `clean`(循環依存も潰したい場合は `strict-ddd`)
51
+ └─ いいえ → カスタム Q5 へ
52
+
53
+ 4. フレームワーク構造に寄せている?
54
+ ├─ Onion (3 層 domain/application/interface) → `onion`
55
+ ├─ Hexagonal (core/ports/adapters) → `hexagonal`
56
+ ├─ MVC / 古典 3 層 (presentation/business/data) → `layered`
57
+ ├─ 小規模スクリプト / 層概念なし → `flat`
58
+ └─ それ以外 → `custom`
59
+
60
+ 5. `custom` を選ぶ場合、`layers` と `allowedDependencies` を明示指定する(例は後述)。
61
+ ```
62
+
63
+ ---
64
+
65
+ ## 設定例
66
+
67
+ ### `clean`(default、省略可)
68
+
69
+ ```json
70
+ {
71
+ "$schema": "./node_modules/phasegate/schemas/harness-config-v3.schema.json",
72
+ "architecture": { "preset": "clean" },
73
+ "l1": { "enabled": true, "rules": {} }
74
+ }
75
+ ```
76
+
77
+ ### `onion`
78
+
79
+ ```json
80
+ {
81
+ "architecture": { "preset": "onion" },
82
+ "l1": { "enabled": true, "rules": {} }
83
+ }
84
+ ```
85
+
86
+ ソースファイルの `@layer` タグは `domain` / `application` / `interface` のいずれかを使用する。
87
+
88
+ ### `hexagonal`
89
+
90
+ ```json
91
+ {
92
+ "architecture": { "preset": "hexagonal" },
93
+ "l1": { "enabled": true, "rules": {} }
94
+ }
95
+ ```
96
+
97
+ `@layer core` / `@layer ports` / `@layer adapters`。
98
+
99
+ ### `flat`(層分割なし)
100
+
101
+ ```json
102
+ {
103
+ "architecture": { "preset": "flat" },
104
+ "l1": { "enabled": true, "rules": {} }
105
+ }
106
+ ```
107
+
108
+ `flat` を指定すると L1-001 (`require-unit-comment`) / L1-002 (`require-layer-comment`) / L1-003 / L1-004 が user 明示なき限り auto-disable される。
109
+
110
+ ### `custom`(明示指定)
111
+
112
+ ```json
113
+ {
114
+ "architecture": {
115
+ "preset": "custom",
116
+ "layers": ["model", "service", "controller", "view"],
117
+ "allowedDependencies": {
118
+ "model": ["model"],
119
+ "service": ["service", "model"],
120
+ "controller": ["controller", "service", "model"],
121
+ "view": ["view", "controller"]
122
+ }
123
+ }
124
+ }
125
+ ```
126
+
127
+ `custom` では `layers` と `allowedDependencies` の両方が必須(片方欠けると config 検証で error)。
128
+
129
+ ---
130
+
131
+ ## override(preset に部分的な上書きを掛ける)
132
+
133
+ preset を base にして一部の `allowedDependencies` のみ書き換えたい場合:
134
+
135
+ ```json
136
+ {
137
+ "architecture": {
138
+ "preset": "clean",
139
+ "allowedDependencies": {
140
+ "presentation": ["presentation", "application"]
141
+ }
142
+ }
143
+ }
144
+ ```
145
+
146
+ 上書きしなかった層(`domain` / `application` / `infrastructure`)は preset 既定のまま。
147
+
148
+ 詳細な semantic validation ルール(C1 自己参照 auto-fill / C2 キー不整合 error / C3 値不整合 error / C4 layer 欠落 auto-fill / C5 循環依存 warn)は `docs/inception/issues/ISSUE-014/wave1_schema_proposal.md §1.3` を参照。
149
+
150
+ ---
151
+
152
+ ## 既存 v2 config からの移行
153
+
154
+ v0.86.0 より前の `phasegate.config.json` には `architecture` キーが無い。phasegate は後方互換で v2 も読めるが、**v3 への明示アップグレードを推奨**する:
155
+
156
+ ```bash
157
+ npx phasegate migrate --schema v3
158
+ ```
159
+
160
+ このコマンドは `phasegate.config.json` に `architecture: { preset: "clean" }` を追記して v3 化する(既に `architecture` がある場合は no-op)。
161
+
162
+ ---
163
+
164
+ ## 参照
165
+
166
+ - `docs/inception/issues/ISSUE-014/wave1_schema_proposal.md` — 設計提案とプリセット詳細
167
+ - `docs/inception/issues/ISSUE-014/issue_description.md` — issue 背景
168
+ - `docs/ADR/ADR-015-architecture-preset.md` — アーキ設計決定
169
+ - `docs/guide/retrofit-adoption.md` — 既存 PJ への後付け導入
170
+ - `docs/guide/configuration.md` — 他の config 項目
@@ -130,7 +130,7 @@ Running every change through Full AIDLC is genuinely heavy for one-person projec
130
130
  | Core | `docs/product/construction/<unit>/*.md` (contract docs) | Full |
131
131
  | Periphery | Internal helpers in `application/` that don't change ports | Quick-first, Full if contract impact emerges |
132
132
  | Periphery | `scripts/harness/presentation/` formatting / wording | Quick |
133
- | Periphery | `docs/guide/*`, `README.md`, `.claude/skills/*` tweaks | Quick |
133
+ | Periphery | `docs/guide/*`, `README.md`, `skills/*` tweaks | Quick |
134
134
  | Periphery | Version bumps, `phasegate.config.json` value edits | Quick |
135
135
 
136
136
  Codify the split in your head (or in a project CLAUDE.md note) — "`domain/**` is core, everything else starts Quick" is a healthy default for a single-maintainer project.
@@ -168,5 +168,5 @@ No. `allowedCategories` is a fixed enum (`bugfix`, `docs`, `test`, `config`). If
168
168
  - [Skills Overview](skills-overview.md) — full catalogue of 28 skills
169
169
  - [Layer Model](layer-model.md) — L0 through L4 defence layers
170
170
  - [Configuration](configuration.md) — `quickMode` configuration reference
171
- - `.claude/skills/quick-implementor/SKILL.md` — the Quick Mode skill definition
172
- - `.claude/skills/story-implementor/SKILL.md` — the Full Mode skill definition
171
+ - `skills/quick-implementor/SKILL.md` — the Quick Mode skill definition
172
+ - `skills/story-implementor/SKILL.md` — the Full Mode skill definition
@@ -44,7 +44,7 @@ Step 4: 新規 Unit / 構造変更は scaffold-design で設計文書を起こ
44
44
  npx phasegate init --name <project-name>
45
45
  ```
46
46
 
47
- - `.claude/skills/` に 28 スキルを配置
47
+ - `skills/` に 28 スキルを配置し、有効な agent 用に `.claude/skills` / `.codex/skills` を作成
48
48
  - `phasegate.config.json` を生成
49
49
  - `phasegate.config.json` に `baseline` セクションが未記載でも、v0.71.0 以降は
50
50
  **`baseline.enabled` の default が `true`** のため grandfather は既定で有効
@@ -97,7 +97,24 @@ monorepo など複数ディレクトリを持つ場合は配列で列挙:
97
97
  この設定を忘れると、phase-gate は `scripts/harness/` 配下しか見ないため、
98
98
  retrofit 対象の新規コード作成が block されず、結果として **phasegate が
99
99
  無効化された運用** になってしまう(ISSUE-007 Wave 8 で schema 上 overridable
100
- になるまで、この設定は config validator で拒否されていた)。
100
+ になるまで、この設定は config validator for 拒否されていた)。
101
+
102
+ ### architecture preset の選定(v0.86.0 以降)
103
+
104
+ retrofit 対象 PJ のアーキテクチャスタイルに合わせて `architecture.preset` を
105
+ 選ぶと、L1-003 / L1-004 が preset の層構造に従って判定される。既存コードが
106
+ Clean 4 層でない場合(オニオン / ヘキサゴナル / 古典レイヤード / 層分離なし)、
107
+ preset を合わせないと合法な import が violation として検出される。
108
+
109
+ 初期は層分離無しで運用したい場合は `flat` を選ぶと L1-001〜004 が auto-disable
110
+ される。選定ガイドと設定例は [Preset Selection Guide](./preset-selection.md) 参照。
111
+
112
+ 既存の v2 config(v0.86.0 未満相当、`architecture` キー無し)は下記で自動
113
+ アップグレードできる:
114
+
115
+ ```bash
116
+ npx phasegate migrate --schema v3
117
+ ```
101
118
 
102
119
  ---
103
120
 
@@ -1,6 +1,6 @@
1
1
  # Skills Overview
2
2
 
3
- Phasegate provides 28 skills covering the full AIDLC (AI-Driven Development Life Cycle). Skills are deployed to `.claude/skills/` by `npx phasegate init` and invoked as slash commands in AI agent sessions.
3
+ Phasegate provides 28 skills covering the full AIDLC (AI-Driven Development Life Cycle). `npx phasegate init` deploys the skill bodies to `skills/` and exposes them to enabled agents through `.claude/skills/` / `.codex/skills/` links.
4
4
 
5
5
  ## AIDLC Process — Skill Execution Order
6
6
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "phasegate",
3
- "version": "0.83.0",
3
+ "version": "0.107.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",
@@ -51,6 +51,12 @@
51
51
  "phasegate:disable": "npx tsx scripts/harness/main.ts disable-feature",
52
52
  "phasegate:check-phase": "npx tsx scripts/harness/main.ts phasegate:check-phase",
53
53
  "phasegate:check-ready": "npx tsx scripts/harness/main.ts phasegate:check-ready",
54
+ "harness:status": "pnpm phasegate:status",
55
+ "harness:init": "npx tsx scripts/harness/main.ts init",
56
+ "harness:enable": "pnpm phasegate:enable",
57
+ "harness:disable": "pnpm phasegate:disable",
58
+ "harness:check-phase": "pnpm phasegate:check-phase",
59
+ "harness:check-ready": "pnpm phasegate:check-ready",
54
60
  "test": "vitest run --config scripts/harness/__tests__/vitest.config.forks.ts && vitest run --config scripts/harness/__tests__/vitest.config.ts"
55
61
  },
56
62
  "dependencies": {
@@ -9,13 +9,6 @@ export class AdrNotFoundApplicationError extends Error {
9
9
  }
10
10
  }
11
11
 
12
- export class DuplicateAdrIdApplicationError extends Error {
13
- constructor(adrRef: string) {
14
- super(`ADR ID が重複しています: ${adrRef}`);
15
- this.name = 'DuplicateAdrIdApplicationError';
16
- }
17
- }
18
-
19
12
  export class SupersededTargetNotFoundApplicationError extends Error {
20
13
  constructor(adrRef: string) {
21
14
  super(`superseded_by の参照先ADRが存在しません: ${adrRef}`);
@@ -51,9 +44,3 @@ export class InvalidAdrDateError extends Error {
51
44
  }
52
45
  }
53
46
 
54
- export class SeedAdrDefinitionCountError extends Error {
55
- constructor(actualCount: number) {
56
- super(`初期ADR定義は11件である必要があります: ${actualCount}`);
57
- this.name = 'SeedAdrDefinitionCountError';
58
- }
59
- }