phasegate 0.124.0 → 0.126.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,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [0.126.0] - 2026-05-08
|
|
11
|
+
|
|
12
|
+
### Fixed
|
|
13
|
+
|
|
14
|
+
- **WI-090 — `phasegate init` が unknown flag を silent ignore する問題を解消** — 例えば `phasegate init --skill-set core` (typo: 正しくは `--skills core`) を実行すると、従来は `--skill-set` 値が無視されて default の `all` で deploy されていた。本リリースで unknown flag を **exit 2 + suggestion** として error 化。
|
|
15
|
+
- **新規ヘルパー**: `scripts/harness/main.ts` に `validateKnownFlags` / `findClosestFlag` / `levenshtein` の 3 関数を inline 追加 (presentation layer の zero-dep CLI parser に組み込み、commander/yargs などの外部依存は追加しない方針を維持)。
|
|
16
|
+
- **挙動**: `init` 冒頭で `KNOWN_INIT_FLAGS = ["--name", "--preset", "--skills", "--agent", "--with-husky", "--yes"]` と照合し、未知の `--xxx` または `--xxx=value` を検出すると Levenshtein 距離 ≤ 4 の closest flag を `Did you mean '...'?` で提示、該当無しなら known flags の列挙を提示して exit 2。
|
|
17
|
+
- **互換性**: 既存の正しい flag 利用 (`--skills core` / `--name foo` 等) には一切影響しない。`--yes` は既存 user の script 互換のため known flag として受理 (no-op)。
|
|
18
|
+
- **help line 修正**: `main.ts` の `printUsage()` で表示される `init` 説明行に `--skills <core|all>` と `--yes` を追記 (従来 `--skills` が help から欠落していた)。
|
|
19
|
+
- **テスト追加**: 4 integration ケース (`scripts/harness/__tests__/integration/harness-api/init-flag-validation.integration.test.ts`):
|
|
20
|
+
- `--skill-set core` typo は `Did you mean '--skills'?` を出して exit 2
|
|
21
|
+
- `--skill-set=core` (=value 形式の typo) も同様に検出
|
|
22
|
+
- `--xyz-totally-unknown` は known flags の列挙を出して exit 2
|
|
23
|
+
- 正しい組み合わせ `--name foo --skills all --agent claude --yes` は flag validation で reject されない
|
|
24
|
+
- 全 3503 テスト (前回 3499 + 新規 4) グリーン、L1 lint 違反なし。
|
|
25
|
+
- **スコープ外**: 他 subcommand (update-skills / migrate / lint / validate / etc.) への validateKnownFlags 展開は段階適用のため別 WI。`--help` per subcommand 実装も別 WI。
|
|
26
|
+
|
|
27
|
+
## [0.125.0] - 2026-05-08
|
|
28
|
+
|
|
29
|
+
### Changed
|
|
30
|
+
|
|
31
|
+
- **WI-089 — WI-088 guidance skills の dogfood feedback 反映 (P1, P2, P4, P5 + cohesion audit)** — v0.124.0 で追加した `phasegate-toolkit-guide` / `phasegate-config-doctor` を別 PJ で dogfood 検証した結果を反映し、UX 改善 + skill 内部の冗長 / 凝集度 / 矛盾を解消。
|
|
32
|
+
- **P1 (discoverability)**: `phasegate init` 完了メッセージの末尾に `Need help?` ブロックを追加。`skillSet !== "core"` 時に `/phasegate-toolkit-guide` (Q&A) と `/phasegate-config-doctor` (config tuning) の起動方法を案内。
|
|
33
|
+
- **P2 (fresh init shortcut)**: `phasegate-config-doctor` に **Step 1.5: Fresh init 判定** を新設。default config + 設計文書空 + Unit 構造未着手の 3 条件を全て満たすプロジェクトには「先に `/product-architect` で AIDLC を開始するのが効率的」とショートカット応答し、9 観点の機械的診断ノイズを抑制。
|
|
34
|
+
- **P4 (UX 標準化)**: `phasegate-config-doctor` Step 4 (適用フロー) を `AskUserQuestion` ベースに書き換え。提案件数に応じて 1 回確認 / WARN→SUGGEST 分割を使い分ける指針を明記。
|
|
35
|
+
- **P5 (consumer noise 削除)**: 両 skill 本文から `WI-086` / `WI-087` 等の実装履歴 WI 番号を削除し、機能ベースの記述 (例: `(v0.122 以降)` / `monorepo 自動検出`) に置き換え。consumer プロジェクトの AI に意味のない historical noise を排除。
|
|
36
|
+
- **Cohesion audit** (`phasegate-toolkit-guide`): 「重要な設計原則」と「アンチパターン」「回答プロセス」と「回答時のスタイル」「マッピングが曖昧な場合 / 設定変更を伴う質問 / アンチパターン」の 3 重複を統合。設計原則を肯定形 4 項目に正規化、回答プロセスを 4 step に統合、境界条件を 1 セクションにまとめ、アンチパターン section を削除。
|
|
37
|
+
- **Cohesion audit** (`phasegate-config-doctor`): 設計原則を 6 項目の肯定形に正規化しアンチパターン section を削除、観点 1 (schema バージョン) と観点 3 (architecture.preset) を「観点 1: architecture セクション (preset / 整合性)」に統合 (architecture key 不在判定 + 推奨 preset 推測 + custom 値検証を一体化)、Step 3 末尾の重複した「適用しますか？」列挙を Step 4 に統合、Step 4 末尾と重複していた「出力例 (簡易)」section を削除。
|
|
38
|
+
- **矛盾解消** (`phasegate-config-doctor` 観点 3 paths): default path が「実プロジェクトのパスに合っていれば OK」という曖昧条件を「Read tool でリストして存在 + 中身ありなら OK / 存在しないか空なら scaffold 期 (Step 1.5) または別配置の可能性」と判定基準を明示化。
|
|
39
|
+
- **検証**: 両 SKILL.md を `skill-creator/scripts/quick_validate.py` で再 validation pass。全 3499 テストグリーン (前回と同数、新規テストは追加せず — UX 改善 + 文章整理のため挙動変更なし)。L1 lint 違反なし。
|
|
40
|
+
- **スコープ外**: P3 (canonical doc 日本語化 / 各 doc に日本語サマリ追加) は分量大のため別 WI (WI-090 候補) で扱う。
|
|
41
|
+
|
|
10
42
|
## [0.124.0] - 2026-05-08
|
|
11
43
|
|
|
12
44
|
### Added
|
package/package.json
CHANGED
package/scripts/harness/main.ts
CHANGED
|
@@ -81,7 +81,8 @@ Usage: phasegate <command> [options]
|
|
|
81
81
|
|
|
82
82
|
Setup:
|
|
83
83
|
init Initialize project: deploy skills + design docs + phasegate.config.json
|
|
84
|
-
(--name <project-name>, --preset <full|standard|minimal|custom>,
|
|
84
|
+
(--name <project-name>, --preset <full|standard|minimal|custom>,
|
|
85
|
+
--skills <core|all>, --agent <claude|codex|both>, --with-husky, --yes)
|
|
85
86
|
update-skills Re-deploy skills from current harness version
|
|
86
87
|
|
|
87
88
|
Commands:
|
|
@@ -166,6 +167,58 @@ function hasFlag(args: readonly string[], flag: string): boolean {
|
|
|
166
167
|
return args.includes(flag);
|
|
167
168
|
}
|
|
168
169
|
|
|
170
|
+
function levenshtein(a: string, b: string): number {
|
|
171
|
+
const m = a.length;
|
|
172
|
+
const n = b.length;
|
|
173
|
+
if (m === 0) return n;
|
|
174
|
+
if (n === 0) return m;
|
|
175
|
+
const dp: number[][] = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
|
|
176
|
+
for (let i = 0; i <= m; i++) dp[i][0] = i;
|
|
177
|
+
for (let j = 0; j <= n; j++) dp[0][j] = j;
|
|
178
|
+
for (let i = 1; i <= m; i++) {
|
|
179
|
+
for (let j = 1; j <= n; j++) {
|
|
180
|
+
const cost = a[i - 1] === b[j - 1] ? 0 : 1;
|
|
181
|
+
dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
return dp[m][n];
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
function findClosestFlag(input: string, known: readonly string[]): string | undefined {
|
|
188
|
+
let best: string | undefined;
|
|
189
|
+
let bestDist = Number.POSITIVE_INFINITY;
|
|
190
|
+
for (const flag of known) {
|
|
191
|
+
const dist = levenshtein(input, flag);
|
|
192
|
+
if (dist < bestDist) {
|
|
193
|
+
bestDist = dist;
|
|
194
|
+
best = flag;
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
return bestDist <= 4 ? best : undefined;
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
function validateKnownFlags(args: readonly string[], known: readonly string[]): string | null {
|
|
201
|
+
const knownSet = new Set(known);
|
|
202
|
+
let i = 0;
|
|
203
|
+
while (i < args.length) {
|
|
204
|
+
const arg = args[i];
|
|
205
|
+
if (!arg.startsWith("--")) {
|
|
206
|
+
i++;
|
|
207
|
+
continue;
|
|
208
|
+
}
|
|
209
|
+
const flagName = arg.includes("=") ? arg.slice(0, arg.indexOf("=")) : arg;
|
|
210
|
+
if (knownSet.has(flagName)) {
|
|
211
|
+
i++;
|
|
212
|
+
continue;
|
|
213
|
+
}
|
|
214
|
+
const suggestion = findClosestFlag(flagName, known);
|
|
215
|
+
return suggestion
|
|
216
|
+
? `Error: unknown flag '${flagName}'. Did you mean '${suggestion}'?`
|
|
217
|
+
: `Error: unknown flag '${flagName}'. Known flags: ${known.join(", ")}`;
|
|
218
|
+
}
|
|
219
|
+
return null;
|
|
220
|
+
}
|
|
221
|
+
|
|
169
222
|
/** フラグとその値を除いた位置引数のみを返す */
|
|
170
223
|
function parsePositionalArgs(args: readonly string[], flagsWithValues: readonly string[] = []): string[] {
|
|
171
224
|
const result: string[] = [];
|
|
@@ -434,6 +487,12 @@ async function main(): Promise<void> {
|
|
|
434
487
|
switch (command) {
|
|
435
488
|
// ── harness setup ──
|
|
436
489
|
case "init": {
|
|
490
|
+
const KNOWN_INIT_FLAGS = ["--name", "--preset", "--skills", "--agent", "--with-husky", "--yes"];
|
|
491
|
+
const flagError = validateKnownFlags(args, KNOWN_INIT_FLAGS);
|
|
492
|
+
if (flagError) {
|
|
493
|
+
console.error(flagError);
|
|
494
|
+
process.exit(2);
|
|
495
|
+
}
|
|
437
496
|
const projectName = parseFlag(args, "--name") ?? "my-project";
|
|
438
497
|
const rawPhasePreset = parseFlag(args, "--preset");
|
|
439
498
|
if (
|
|
@@ -564,6 +623,12 @@ async function main(): Promise<void> {
|
|
|
564
623
|
);
|
|
565
624
|
console.log(` See docs/guide/codex-integration.md for the native apply_patch limitation.`);
|
|
566
625
|
}
|
|
626
|
+
if (skillSet !== "core") {
|
|
627
|
+
console.log("");
|
|
628
|
+
console.log("Need help?");
|
|
629
|
+
console.log(" • Q&A about phasegate concepts: invoke /phasegate-toolkit-guide");
|
|
630
|
+
console.log(" • Diagnose & tune phasegate.config.json: invoke /phasegate-config-doctor");
|
|
631
|
+
}
|
|
567
632
|
process.exit(0);
|
|
568
633
|
break;
|
|
569
634
|
}
|
|
@@ -5,98 +5,121 @@ description: 現在の phasegate.config.json を schema + プロジェクト検
|
|
|
5
5
|
|
|
6
6
|
# Phasegate Config Doctor
|
|
7
7
|
|
|
8
|
-
現在の `phasegate.config.json` を診断し、改善案を **diff 形式** でユーザーに提示する skill
|
|
8
|
+
現在の `phasegate.config.json` を診断し、改善案を **diff 形式** でユーザーに提示する skill。
|
|
9
9
|
|
|
10
10
|
## このスキルが解決する問題
|
|
11
11
|
|
|
12
|
-
phasegate を導入した直後の config は単純な default で、実プロジェクトの構造 (monorepo / formatter 選定 / architecture style / Quick Mode の運用方針)
|
|
12
|
+
phasegate を導入した直後の config は単純な default で、実プロジェクトの構造 (monorepo / formatter 選定 / architecture style / Quick Mode の運用方針) に最適化されていない。AI が schema を知らずに勘で書き換えると壊れるため、**schema + 検出結果に基づいた決定的提案** が必要。
|
|
13
13
|
|
|
14
|
-
##
|
|
14
|
+
## 設計原則
|
|
15
15
|
|
|
16
|
-
1. **silent 書き換え禁止** —
|
|
17
|
-
2.
|
|
18
|
-
3.
|
|
19
|
-
4. **
|
|
20
|
-
5. **read-only な Q&A は phasegate-toolkit-guide に委譲** — 「L2 って何？」など概念質問は本 skill
|
|
16
|
+
1. **silent 書き換え禁止** — 提案は diff として提示し、`AskUserQuestion` で承認を取ってから Edit
|
|
17
|
+
2. **検出結果を優先** — 機械的に決定可能な部分 (workspace 構造、formatter、bash 互換性) は AI 推論ではなく検出結果を採用
|
|
18
|
+
3. **AI 推論は判断要素のみ** — architecture preset 選定、relaxedGates 推奨値などは AI が判断するが根拠を必ず示す
|
|
19
|
+
4. **schema は enum 違反確認時のみ Read** — 日常診断は本 SKILL 内の判定基準で十分。schema 全文 Read は値域不明時に限定する
|
|
20
|
+
5. **read-only な Q&A は phasegate-toolkit-guide に委譲** — 「L2 って何？」など概念質問は本 skill スコープ外
|
|
21
|
+
6. **変更後は L2 検証必須** — `npx phasegate validate --layer L2` を走らせてからユーザーに完了報告
|
|
21
22
|
|
|
22
23
|
## 診断プロセス
|
|
23
24
|
|
|
24
25
|
### Step 1: 現状把握 (read-only)
|
|
25
26
|
|
|
26
|
-
以下のファイルを
|
|
27
|
+
以下のファイルを Read してから診断する:
|
|
27
28
|
|
|
28
29
|
| 情報源 | パス | 用途 |
|
|
29
30
|
|---|---|---|
|
|
30
31
|
| 現 config | `phasegate.config.json` | 診断対象 |
|
|
31
|
-
| schema | `node_modules/phasegate/scripts/harness/config-foundation/infrastructure/schemas/harness-config-v3.schema.json` (or `harness-config-v2.schema.json` if v2) | 値域確認 |
|
|
32
32
|
| package.json | `package.json` | devDependencies (formatter 検出) / workspaces 検出 |
|
|
33
|
-
| pnpm workspace | `pnpm-workspace.yaml` | workspace 検出 |
|
|
34
|
-
| lerna config | `lerna.json` | workspace 検出 |
|
|
33
|
+
| pnpm workspace | `pnpm-workspace.yaml` (存在すれば) | workspace 検出 |
|
|
34
|
+
| lerna config | `lerna.json` (存在すれば) | workspace 検出 |
|
|
35
35
|
| hook config | `.claude/scripts/hook-config.json` | 既存 hook 設定確認 |
|
|
36
36
|
|
|
37
|
-
|
|
37
|
+
**schema は必要なときだけ Read** (enum 違反疑い時など): `node_modules/phasegate/scripts/harness/config-foundation/infrastructure/schemas/harness-config-v3.schema.json` (or `harness-config-v2.schema.json` if v2)。
|
|
38
|
+
|
|
39
|
+
phasegate リポジトリ自体 (dogfood) の場合は `node_modules/phasegate/` を `scripts/harness/config-foundation/...` に置換。
|
|
40
|
+
|
|
41
|
+
### Step 1.5: Fresh init 判定 (重要)
|
|
42
|
+
|
|
43
|
+
以下の **全条件** を満たす場合、フル診断は早期。Step 2 に進まず AIDLC 開始を案内する:
|
|
44
|
+
|
|
45
|
+
- `phasegate.config.json` が `phasegate init` 直後の default 状態 (`project.preset = "standard"` / `architecture.preset` 設定済 / `layers` / `quickMode` / `harnesses` が空 dict)
|
|
46
|
+
- `docs/product/construction/` が空または存在しない
|
|
47
|
+
- `scripts/`, `src/` 配下に Unit 構造 (`domain/application/infrastructure/presentation` 等) が無い
|
|
48
|
+
|
|
49
|
+
**該当時の応答**:
|
|
50
|
+
|
|
51
|
+
```
|
|
52
|
+
このプロジェクトは phasegate init 直後の状態のため、config を最適化するより先に
|
|
53
|
+
AIDLC を開始することを推奨します:
|
|
54
|
+
|
|
55
|
+
/product-architect
|
|
56
|
+
|
|
57
|
+
product-architect で Unit を作り、いくつかの logical_design を書いた後で本 skill を再実行すると、
|
|
58
|
+
実態に基づいた具体的な改善提案ができます。
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
該当しない場合のみ Step 2 に進む。
|
|
38
62
|
|
|
39
63
|
### Step 2: 診断観点
|
|
40
64
|
|
|
41
|
-
|
|
65
|
+
各観点で **OK / WARN / SUGGEST** のいずれかを出す。
|
|
42
66
|
|
|
43
|
-
#### 観点 1:
|
|
67
|
+
#### 観点 1: architecture セクション (preset / 整合性)
|
|
44
68
|
|
|
45
|
-
- `architecture` キーが無い → v2 として扱われる →
|
|
46
|
-
- `architecture.preset`
|
|
69
|
+
- `architecture` キーが無い → v2 として扱われる → SUGGEST: `architecture: { preset: "..." }` 追加
|
|
70
|
+
- `architecture.preset` 未指定 + `scripts/`, `src/` 配下のディレクトリ構造から推測 → SUGGEST:
|
|
71
|
+
- `domain/` `application/` `infrastructure/` `presentation/` の 4 層あり → `clean` 推奨
|
|
72
|
+
- DDD タクティカル (`entities/aggregates/repositories`) あり → `strict-ddd` 推奨
|
|
73
|
+
- `core/`, `adapters/`, `ports/` パターン → `hexagonal` 推奨
|
|
74
|
+
- 上記いずれも無し → ユーザーに確認 + `custom` 提案
|
|
75
|
+
- 検出根拠を必ず提示 (例:「`scripts/harness/{domain,application,infrastructure,presentation}` を検出 → `clean` 推奨」)
|
|
76
|
+
- `architecture.preset = "custom"` だが `architecture.layers` 未定義 → WARN: schema validator で reject される
|
|
47
77
|
|
|
48
78
|
#### 観点 2: project.preset (防御プリセット)
|
|
49
79
|
|
|
50
|
-
- `project.preset`
|
|
80
|
+
- `project.preset` 未指定 → SUGGEST: プロジェクト規模に応じて `minimal` / `standard` / `strict`
|
|
51
81
|
- 値が enum 外 → WARN
|
|
52
82
|
|
|
53
|
-
#### 観点 3:
|
|
54
|
-
|
|
55
|
-
- 未指定 + `scripts/`, `src/` 配下のディレクトリ構造を検査して推測:
|
|
56
|
-
- `domain/` `application/` `infrastructure/` `presentation/` の 4 層あり → `clean` を推奨
|
|
57
|
-
- DDD タクティカル (entities/aggregates/repositories) あり → `strict-ddd` を推奨
|
|
58
|
-
- `core/`, `adapters/`, `ports/` パターン → `hexagonal` を推奨
|
|
59
|
-
- 上記いずれも無し、または独自命名 → ユーザーに確認 + `custom` を提案
|
|
60
|
-
- 検出根拠を必ず提示 (例: 「`scripts/harness/{domain,application,infrastructure,presentation}` を検出 → `clean` 推奨」)
|
|
83
|
+
#### 観点 3: paths
|
|
61
84
|
|
|
62
|
-
|
|
85
|
+
- `paths.designDocs` / `paths.inceptionDocs` が default のまま (`docs/product/construction` / `docs/inception`):
|
|
86
|
+
- 実 path を Read tool でリスト確認し、存在 + 中身あり → OK
|
|
87
|
+
- 存在しない or 空 → fresh init scaffold 期 (Step 1.5 で早期 return しているはず) または別 path に置いている可能性 → ユーザーに確認
|
|
88
|
+
- default 以外で実 path に存在する → OK
|
|
63
89
|
|
|
64
|
-
|
|
65
|
-
- 異なるパスに設計文書がある場合 → SUGGEST: 実パスに合わせて変更
|
|
66
|
-
|
|
67
|
-
#### 観点 5: quickMode
|
|
90
|
+
#### 観点 4: quickMode
|
|
68
91
|
|
|
69
92
|
- `quickMode.allowedCategories` が default `['bugfix', 'docs', 'test', 'config']` のまま → プロジェクトの慣習に応じて拡張提案
|
|
70
93
|
- `quickMode.relaxedGates` が空 → small team なら `['phase-gate']` 追加を SUGGEST、enterprise なら現状維持を OK
|
|
71
94
|
|
|
72
|
-
#### 観点
|
|
95
|
+
#### 観点 5: harnesses (cascade / bundle / dead-code)
|
|
73
96
|
|
|
74
|
-
- `cascadeUpdate: false` → AI 主導開発なら true 推奨 (SUGGEST)
|
|
75
|
-
- `agentLessonCollection: false` → AI セッションの教訓を蓄積したいなら true 推奨 (SUGGEST)
|
|
97
|
+
- `cascadeUpdate: false` → AI 主導開発なら `true` 推奨 (SUGGEST)
|
|
98
|
+
- `agentLessonCollection: false` → AI セッションの教訓を蓄積したいなら `true` 推奨 (SUGGEST)
|
|
76
99
|
- `bundleSizeLimit: 0` → frontend プロジェクトなら値設定推奨
|
|
77
100
|
|
|
78
|
-
#### 観点
|
|
101
|
+
#### 観点 6: baseline
|
|
79
102
|
|
|
80
103
|
- `baseline` セクション不在 → default `enabled: true, path: .phasegate/baseline.json` (v0.117 以降)
|
|
81
104
|
- 既存大規模プロジェクトに後追い導入なら baseline 有効化推奨 (新規違反のみ厳しく検査)
|
|
82
105
|
|
|
83
|
-
#### 観点
|
|
106
|
+
#### 観点 7: agentIntegration.stopHook.enforce (v0.122 以降)
|
|
84
107
|
|
|
85
108
|
- 未指定 (`false` 相当) → AI セッションの Stop hook 失敗を **warning のみ** で許容
|
|
86
109
|
- `true` セット → Complete Check 失敗時に Claude Code の turn を hard block (exit 2)
|
|
87
110
|
- 推奨: AI 主導開発で本格運用するなら `true` を SUGGEST
|
|
88
111
|
|
|
89
|
-
#### 観点
|
|
112
|
+
#### 観点 8: hook-config.json (`.claude/scripts/`)
|
|
90
113
|
|
|
91
|
-
- `targetDirs: ["src"]` のままで monorepo の場合 → WARN: `phasegate init` を再実行すれば
|
|
114
|
+
- `targetDirs: ["src"]` のままで monorepo の場合 → WARN: `phasegate init` を再実行すれば monorepo 自動検出が効く (v0.120 以降)
|
|
92
115
|
- `formatter: "biome"` だが `@biomejs/biome` が devDependencies に無い → WARN: prettier に切り替え推奨
|
|
93
|
-
-
|
|
116
|
+
- v0.119 未満で deploy された hook script (bash 4 `mapfile` 使用) → WARN: macOS の bash 3.2 で silent fail。`phasegate init` 再実行で更新
|
|
94
117
|
|
|
95
|
-
### Step 3:
|
|
118
|
+
### Step 3: 診断レポート
|
|
96
119
|
|
|
97
|
-
|
|
120
|
+
診断結果を以下の形式で提示する:
|
|
98
121
|
|
|
99
|
-
|
|
122
|
+
````markdown
|
|
100
123
|
## phasegate.config.json 診断結果
|
|
101
124
|
|
|
102
125
|
### サマリ
|
|
@@ -116,7 +139,7 @@ phasegate リポジトリ自体 (dogfood) の場合は `node_modules/phasegate/`
|
|
|
116
139
|
+ "layers": [ /* layer 定義 */ ]
|
|
117
140
|
+ }
|
|
118
141
|
```
|
|
119
|
-
- 補足: layer 構造が clean / strict-ddd / hexagonal / onion / layered / flat
|
|
142
|
+
- 補足: layer 構造が clean / strict-ddd / hexagonal / onion / layered / flat のいずれかに該当するなら `preset: "<その値>"` のほうが簡潔
|
|
120
143
|
|
|
121
144
|
### 💡 改善提案 (SUGGEST)
|
|
122
145
|
|
|
@@ -135,20 +158,26 @@ phasegate リポジトリ自体 (dogfood) の場合は `node_modules/phasegate/`
|
|
|
135
158
|
- project.preset = "standard"
|
|
136
159
|
- paths.designDocs / paths.inceptionDocs はデフォルト値で実プロジェクトと一致
|
|
137
160
|
- baseline セクション不在 → default 有効 (v0.117+)
|
|
161
|
+
````
|
|
138
162
|
|
|
139
|
-
|
|
163
|
+
### Step 4: 適用 (AskUserQuestion 経由)
|
|
140
164
|
|
|
141
|
-
|
|
142
|
-
- [全て適用]
|
|
143
|
-
- [W1 のみ適用]
|
|
144
|
-
- [S1 のみ適用]
|
|
145
|
-
- [何も適用しない (情報のみ)]
|
|
146
|
-
- [カスタム (個別選択)]
|
|
147
|
-
```
|
|
165
|
+
提案件数に応じて使い分ける:
|
|
148
166
|
|
|
149
|
-
|
|
167
|
+
- **提案 1-3 件**: `AskUserQuestion` 1 回で「全て適用 / 個別選択 / 適用しない」を提示
|
|
168
|
+
- **提案 4 件以上**: WARN を先に `AskUserQuestion` で確認し、SUGGEST はバッチで別途確認
|
|
150
169
|
|
|
151
|
-
|
|
170
|
+
option 設計の例 (提案 2 件、WARN 1 + SUGGEST 1 のとき):
|
|
171
|
+
|
|
172
|
+
```
|
|
173
|
+
question: "phasegate.config.json に提案 2 件あります。どう適用しますか？"
|
|
174
|
+
options:
|
|
175
|
+
- label: "全て適用 (推奨) — W1 + S1"
|
|
176
|
+
- label: "WARN のみ適用 — W1 のみ"
|
|
177
|
+
- label: "適用しない (情報のみ受け取る)"
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
ユーザーが適用対象を確定したら `Edit` で `phasegate.config.json` を変更。
|
|
152
181
|
|
|
153
182
|
**変更後の必須検証**:
|
|
154
183
|
|
|
@@ -158,15 +187,6 @@ npx phasegate validate --layer L2
|
|
|
158
187
|
|
|
159
188
|
L2 でエラーが出た場合は変更を **rollback** し、ユーザーに報告 (silent に進めない)。
|
|
160
189
|
|
|
161
|
-
## アンチパターン
|
|
162
|
-
|
|
163
|
-
- ❌ 現 config を読まずに「一般論として推奨」を出す (実態と乖離する)
|
|
164
|
-
- ❌ schema を読まずに値を提案する (enum 外の値を出してしまう)
|
|
165
|
-
- ❌ ユーザー確認を取らずに Edit する
|
|
166
|
-
- ❌ 「とりあえず全部 strict にしておく」のような根拠なき強気提案
|
|
167
|
-
- ❌ phase-dependency-model 関連の改修を無検証で提案 (memory `feedback_dogfood_before_release.md` 適用 — paths config / Artifact 改修は dogfood 必須)
|
|
168
|
-
- ❌ 設定変更後に `npx phasegate validate --layer L2` を走らせずに完了報告
|
|
169
|
-
|
|
170
190
|
## phasegate-toolkit-guide との使い分け
|
|
171
191
|
|
|
172
192
|
| 質問種別 | 使う skill |
|
|
@@ -176,24 +196,4 @@ L2 でエラーが出た場合は変更を **rollback** し、ユーザーに報
|
|
|
176
196
|
| 「monorepo 対応されてる？」(現状確認) | phasegate-toolkit-guide |
|
|
177
197
|
| 「monorepo 用に config 直して」(設定変更) | phasegate-config-doctor |
|
|
178
198
|
|
|
179
|
-
ユーザー質問が両方にまたがる場合は、まず phasegate-toolkit-guide で概念を説明 →
|
|
180
|
-
|
|
181
|
-
## 出力例 (簡易)
|
|
182
|
-
|
|
183
|
-
ユーザー: 「phasegate のセットアップ最適化して」
|
|
184
|
-
|
|
185
|
-
```
|
|
186
|
-
[phasegate.config.json を Read]
|
|
187
|
-
[harness-config-v3.schema.json を Read]
|
|
188
|
-
[package.json / pnpm-workspace.yaml を Read]
|
|
189
|
-
[scripts/ ディレクトリ構造を ls]
|
|
190
|
-
|
|
191
|
-
診断結果:
|
|
192
|
-
- ✅ OK: 5 件 (project / paths / harnesses / reporting / baseline)
|
|
193
|
-
- ⚠️ WARN: 1 件 (W1: architecture.preset 未指定 → v2 schema 扱い → warning が出る)
|
|
194
|
-
- 💡 SUGGEST: 2 件 (S1: clean preset 推奨 / S2: cascadeUpdate=true 推奨)
|
|
195
|
-
|
|
196
|
-
提案 diff: [上記フォーマット]
|
|
197
|
-
|
|
198
|
-
どれを適用しますか？
|
|
199
|
-
```
|
|
199
|
+
ユーザー質問が両方にまたがる場合は、まず phasegate-toolkit-guide で概念を説明 → ユーザーが「じゃあ修正して」と言ったら本 skill に切り替える。
|
|
@@ -9,22 +9,23 @@ phasegate ツールキット自体の概念・仕様・設定について、ユ
|
|
|
9
9
|
|
|
10
10
|
## このスキルが解決する問題
|
|
11
11
|
|
|
12
|
-
ユーザーが phasegate
|
|
12
|
+
ユーザーが phasegate を導入したプロジェクトで AI に phasegate 関連の質問をしたとき、AI が `node_modules/phasegate/` を grep で調査して仕様を推測する非効率を防ぐ。
|
|
13
13
|
|
|
14
|
-
phasegate
|
|
14
|
+
phasegate の概念・仕様は **canonical doc が `node_modules/phasegate/docs/guide/` 配下に同梱されている**。本 skill はそれらへの正確なポインタを提供する。
|
|
15
15
|
|
|
16
|
-
##
|
|
16
|
+
## 設計原則
|
|
17
17
|
|
|
18
|
-
**
|
|
19
|
-
|
|
20
|
-
|
|
18
|
+
1. **canonical doc を必ず Read してから答える** — training data 依存で答えない (バージョン乖離リスク)
|
|
19
|
+
2. **knowledge を skill 本体に固定しない** — skill markdown には「どの doc を読めば答えられるか」のポインタだけを書く。`npm update phasegate` で knowledge が自動追従する構造を保つ
|
|
20
|
+
3. **read-only に徹する** — 「config の X を変更したい」など設定変更を伴う質問は範囲外。`phasegate-config-doctor` に委譲する
|
|
21
|
+
4. **doc 全文をユーザーに貼り付けない** — 要約 + 該当セクション名引用で返す
|
|
21
22
|
|
|
22
23
|
## 回答プロセス
|
|
23
24
|
|
|
24
25
|
1. ユーザー質問を以下の **概念カテゴリ** にマッピング
|
|
25
|
-
2. 対応する canonical doc を **Read tool で読む**
|
|
26
|
-
3. Read
|
|
27
|
-
4. 回答内に **doc
|
|
26
|
+
2. 対応する canonical doc を **Read tool で読む** — 長い doc は当該セクションを `offset` / `limit` で限定して読む
|
|
27
|
+
3. Read した内容に基づいて簡潔に回答 (2-3 段落 + コード例 1 つ程度)
|
|
28
|
+
4. 回答内に **doc 内の該当セクション名** を引用 (ユーザーが doc を直接開いたとき navigation できるように)
|
|
28
29
|
|
|
29
30
|
### canonical doc の場所
|
|
30
31
|
|
|
@@ -32,7 +33,7 @@ phasegate がインストールされたプロジェクトでは、以下のい
|
|
|
32
33
|
|
|
33
34
|
```
|
|
34
35
|
node_modules/phasegate/docs/guide/ # npm 経由でインストールされた consumer プロジェクト
|
|
35
|
-
docs/guide/
|
|
36
|
+
docs/guide/ # phasegate リポジトリ自体 (dogfood)
|
|
36
37
|
```
|
|
37
38
|
|
|
38
39
|
**先に `node_modules/phasegate/docs/guide/` を試し**、見つからなければ `docs/guide/` を試す。
|
|
@@ -48,7 +49,7 @@ docs/guide/ # phasegate リポジトリ自体 (dogfood
|
|
|
48
49
|
|
|
49
50
|
**参照先**: `docs/guide/layer-model.md`
|
|
50
51
|
|
|
51
|
-
|
|
52
|
+
各層 (L0 / L1 / L2 / L3 / L4) のセクションが見出しで区切られているので、質問された層のセクションのみ `offset` 指定で部分読みすると効率的。
|
|
52
53
|
|
|
53
54
|
### 2. 防御プリセット / アーキプリセット (重要: 2 系統あり)
|
|
54
55
|
|
|
@@ -75,9 +76,9 @@ docs/guide/ # phasegate リポジトリ自体 (dogfood
|
|
|
75
76
|
- 「relaxedGates って何のため？」
|
|
76
77
|
- 「allowedCategories はどこで設定する？」
|
|
77
78
|
|
|
78
|
-
**参照先**: `docs/guide/quick-vs-full-mode.md`
|
|
79
|
+
**参照先**: `docs/guide/quick-vs-full-mode.md` (Mode の概念と切り替え条件)
|
|
79
80
|
|
|
80
|
-
|
|
81
|
+
設定キー (`quickMode.allowedCategories` / `quickMode.relaxedGates` / `quickMode.fullModeRequiredWhen`) の詳細は `docs/guide/configuration.md` の `quickMode` セクション。
|
|
81
82
|
|
|
82
83
|
### 4. Hook 仕様 (PreToolUse / PostToolUse / Stop / SessionStart / UserPromptSubmit)
|
|
83
84
|
|
|
@@ -89,7 +90,7 @@ docs/guide/ # phasegate リポジトリ自体 (dogfood
|
|
|
89
90
|
|
|
90
91
|
**参照先**: `docs/guide/hooks-integration.md`
|
|
91
92
|
|
|
92
|
-
`Responsibility Separation` セクションに pre / post / Stop
|
|
93
|
+
`Responsibility Separation` セクションに pre / post / Stop の責務分担表があり、Stop hook を strict mode (turn を hard block) にする `agentIntegration.stopHook.enforce` オプションもそこに記載されている。
|
|
93
94
|
|
|
94
95
|
### 5. config 全般 (`phasegate.config.json`)
|
|
95
96
|
|
|
@@ -101,7 +102,7 @@ docs/guide/ # phasegate リポジトリ自体 (dogfood
|
|
|
101
102
|
|
|
102
103
|
**参照先**: `docs/guide/configuration.md`
|
|
103
104
|
|
|
104
|
-
各 top-level
|
|
105
|
+
各 top-level セクション (`project` / `layers` / `quickMode` / `phaseDependencies` / `harnesses` / `paths` / `reporting` / `architecture` / `agentIntegration` / `protectedFiles` / `baseline`) ごとに説明あり。
|
|
105
106
|
|
|
106
107
|
### 6. CLI コマンド一覧
|
|
107
108
|
|
|
@@ -120,7 +121,7 @@ docs/guide/ # phasegate リポジトリ自体 (dogfood
|
|
|
120
121
|
- 「既存プロジェクトに後から導入したい」
|
|
121
122
|
|
|
122
123
|
**参照先**:
|
|
123
|
-
- 新規導入: `docs/guide/installation.md
|
|
124
|
+
- 新規導入: `docs/guide/installation.md`
|
|
124
125
|
- 既存プロジェクト導入: `docs/guide/retrofit-adoption.md`
|
|
125
126
|
|
|
126
127
|
### 8. skill 一覧と使い分け
|
|
@@ -139,28 +140,18 @@ docs/guide/ # phasegate リポジトリ自体 (dogfood
|
|
|
139
140
|
|
|
140
141
|
**参照先**: `docs/guide/codex-integration.md`
|
|
141
142
|
|
|
142
|
-
##
|
|
143
|
+
## 境界条件
|
|
143
144
|
|
|
144
|
-
|
|
145
|
-
- canonical doc の **該当セクション名** を必ず引用 (ユーザーが doc を直接開いたときの navigation 補助)
|
|
146
|
-
- 質問が複数カテゴリにまたがる場合は、最も関連性の高い doc を先に読む
|
|
147
|
-
- doc を読まずに回答しない (本 skill の存在意義は「正確な情報源を引く」こと)
|
|
145
|
+
### 質問が複数カテゴリにまたがる場合
|
|
148
146
|
|
|
149
|
-
|
|
147
|
+
最も関連性の高い doc を先に読み、必要なら追加で別 doc を読んで補う。
|
|
150
148
|
|
|
151
|
-
|
|
149
|
+
### マッピングが曖昧な場合
|
|
152
150
|
|
|
153
151
|
1. `docs/guide/` 配下の doc 一覧 (`ls node_modules/phasegate/docs/guide/`) を取得
|
|
154
152
|
2. ファイル名から推測して最も近い doc を読む
|
|
155
153
|
3. それでも見つからなければ、ユーザーに **どの観点を知りたいか** を質問で絞り込む
|
|
156
154
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
「config の X を変更したい」など **設定変更を伴う質問** は、本 skill の範囲外。phasegate-config-doctor skill (存在すれば) に委譲するか、ユーザーに「設定変更には phasegate-config-doctor を起動するのが推奨」と案内する。本 skill は **read-only な Q&A に徹する**。
|
|
160
|
-
|
|
161
|
-
## アンチパターン
|
|
155
|
+
### 設定変更を伴う質問
|
|
162
156
|
|
|
163
|
-
|
|
164
|
-
- ❌ doc 全文をユーザーに貼り付ける (要約して該当セクションへのポインタを返す)
|
|
165
|
-
- ❌ `phasegate.config.json` を直接編集する (本 skill は read-only)
|
|
166
|
-
- ❌ skill 本文に概念解説を書き加える (doc に書くべき。skill はポインタ役)
|
|
157
|
+
「config の X を変更したい」など **設定変更を伴う質問** は本 skill のスコープ外。`phasegate-config-doctor` に委譲する (deploy 済の guidance skill。ユーザーに「設定変更には phasegate-config-doctor が推奨」と案内)。
|