phasegate 0.44.0 → 0.62.0

package/skills/story-implementor/SKILL.md

@@ -108,6 +108,64 @@ model: codex
 
 ---
 
+## ⚠️ 生成ファイルへのメタデータ付与（必須）
+
+**新規ソースファイルを作成する際、ファイル先頭に必ず `@unit` / `@layer` メタデータを記述する。これは L1 Biome ルール (`L1-001: require-unit-comment`, `L1-002: require-layer-comment`) の要件であり、欠落した状態での生成は許容されない。**
+
+### TypeScript / JavaScript ファイル
+
+```typescript
+// @unit <対象Unit名 — logical_design.md の Unit ID を使用>
+// @layer <domain | application | infrastructure | presentation>
+
+// 以下、実装コード
+```
+
+### `@unit` の決定方法
+
+- `docs/product/construction/{unit}/logical_design.md` の Unit ID をそのまま引用する
+- ストーリー固有実装の場合は、該当ストーリーが属する Unit の ID を使用
+- **複数 Unit にまたがる場合は story-implementor のスコープ違反** — `implementation-readiness-checker` に差し戻し、Unit 分割を検討する
+
+### `@layer` の決定方法
+
+生成ファイルの配置パスから機械的に決定する:
+
+| 配置パス | `@layer` の値 |
+|---------|-------------|
+| `**/domain/**` | `domain` |
+| `**/application/**` | `application` |
+| `**/infrastructure/**` | `infrastructure` |
+| `**/presentation/**` | `presentation` |
+
+Clean Architecture の 4 層構成に従わないプロジェクトは、プロジェクト側で層名を定義した上で phasegate のルール設定に同期させること。
+
+### テストファイルの場合
+
+テストファイル（`**/__tests__/**`, `*.test.ts`, `*.spec.ts`）には `@unit` / `@layer` に加えて **`@story` タグを付与する**:
+
+```typescript
+// @unit <被テストコードと同じ Unit ID>
+// @layer <被テストコードと同じ layer>
+// @story <HXX-XX 形式のストーリーID>
+```
+
+- `@story` は `docs/inception/{unit}/{story_id}/` の `story_id` を使用
+- 複数ストーリーをカバーするテストは `// @story H09-01, H09-02` のように列挙
+- US↔テストの逆引きが機械的に可能になることが目的（test-coverage-checker / nyquist が集計に使用）
+
+### 検証
+
+実装完了後、以下で L1 違反が無いことを確認する:
+
+```bash
+npx phasegate lint
+```
+
+`L1-001` / `L1-002` で違反が検出された場合、本スキル終了前に必ず解決すること。スキルを抜けた後で付け直すのはアンチパターン（直後の L1 有効化時に全違反がまとめて噴出する）。
+
+---
+
 ## ⚠️ 2フェーズ実行ルール
 
 **このスキルは必ず2フェーズに分けて実行する。Phase 1で実装計画を作成し、人間の承認を得てからPhase 2でTDD実装を行う。Phase 1とPhase 2を同時に実行してはならない。**

package/skills/unit-designer/SKILL.md

@@ -154,6 +154,47 @@ Unit分割の方針・グルーピングの根拠・不明点を整理し、人
 
 ---
 
+## 🔗 成果物のトレーサビリティメタデータ（必須）
+
+Phase 2 で生成する Unit 定義文書には、以下 2 種類のメタデータを emit する。`MetadataValidator.validateDesignDocument` が検証対象とし、ISSUE-008 Phase B-2/B-3 完了後は `npx phasegate validate-metadata` / pre-commit で自動チェックされる。
+
+### 1. YAML frontmatter（新規作成時）
+
+`docs/product/units/{unit_name}.md` の先頭に以下を付与する。既存 Unit 定義の改訂時は省略してよい。`integration_contract.md` は Unit 横断のため任意。
+
+```yaml
+---
+traceability:
+  initial_creation: true
+---
+```
+
+`initial_creation: true` は「新規作成であり、後述の `@story-id` 注釈が必須」であることを示す。
+
+### 2. `@story-id` インライン注釈
+
+ユーザーストーリーに紐づく機能要件・エンドポイント定義の直前に `@story-id HXX-XX` を独立行で記述する。
+
+```markdown
+@story-id H03-02
+### 機能要件: 注文確定
+```
+
+形式ルール:
+- **独立行** — 他のテキストと混在させない
+- **直後に設計要素** — 空行を挟まない
+- **StoryCatalog 存在** — `HXX-XX` は `docs/product/user_stories.md` に存在する ID
+- **複数ストーリー時** — 注釈行を連続で並べ、最後の直後に設計要素を置く
+
+### 3. Phase 3 レビューでの BLOCK 確認
+
+Phase 3 レビューで以下を BLOCK 基準として確認する:
+- 新規作成文書に `initial_creation: true` frontmatter が付与されているか
+- 担当ストーリーに対応する機能要件の直前に `@story-id` が配置されているか
+- 上記形式ルールに準拠しているか
+
+---
+
 ## Phase 3: レビュー（Opus review）
 
 ### 実行主体

package/skills/unit-test-logic-designer/SKILL.md

@@ -189,6 +189,24 @@ TDD実装フェーズ
 
 ---
 
+## 🔗 テストファイルのトレーサビリティメタデータ（必須）
+
+Phase 2 で設計するテストファイル（`*.test.ts` / `*.spec.ts`）の疑似コード冒頭には、ファイル先頭コメントブロックに `// @story HXX-XX` を emit するよう明記する。`MetadataValidator.validateTest` が検証対象とし、ISSUE-008 Phase C-2 以降は `npx phasegate validate-metadata` / pre-commit で自動チェックされる。
+
+```typescript
+// @unit <被テストコードと同じ Unit ID>
+// @layer <被テストコードと同じ layer>
+// @story H03-02
+```
+
+形式ルール:
+- `@unit` / `@layer` と同じヘッダーコメントブロックに配置
+- `HXX-XX` は `docs/product/user_stories.md` に存在する ID（StoryCatalog）
+- 複数ストーリーをカバーするテストは `// @story H03-01, H03-02` のようにカンマ区切りで列挙
+- 目的: US↔テストの逆引きを機械化（test-coverage-checker / nyquist の集計入力）
+
+---
+
 ## 注意事項
 
 - **テストコードは生成しない**（設計文書のみ）— 実装は `story-implementor` が行う

package/templates/.codex/hooks.json

@@ -0,0 +1,63 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx phasegate hook session-start",
+            "statusMessage": "phasegate: loading session context"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx phasegate hook user-prompt-submit",
+            "statusMessage": "phasegate: refreshing status"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx phasegate hook pre-tool-use",
+            "statusMessage": "phasegate: pre-tool-use check"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx phasegate hook post-tool-use",
+            "statusMessage": "phasegate: post-tool-use lint"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx phasegate hook stop",
+            "statusMessage": "phasegate: completion check",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/logical_design.template.md

@@ -0,0 +1,79 @@
+---
+traceability:
+  initial_creation: true
+---
+
+# 論理設計: <Unit名>
+
+> **対応ストーリー**: <HXX-XX, HYY-YY>
+> **作成日**: <YYYY-MM-DD>
+> **Unit**: <UNIT_NAME>
+
+---
+
+## 概要
+
+<このUnitが解決するビジネス課題を 2〜3 行で記述>
+
+---
+
+## ドメインモデル
+
+@story-id <HXX-XX>
+### <集約 / エンティティ / 値オブジェクト名>
+
+<不変条件・責務・関連の説明>
+
+---
+
+## ユースケース
+
+@story-id <HXX-XX>
+### UC-001: <ユースケース名>
+
+**As a** <役割>
+**I want to** <達成したいこと>
+**So that** <得られる価値>
+
+#### 事前条件
+- <前提>
+
+#### 基本フロー
+1. <ステップ>
+
+#### 例外フロー
+- <エラーケース>
+
+---
+
+## 層構成（Clean Architecture）
+
+```
+domain/          : Entity / ValueObject / Port / Domain Service
+application/     : UseCase / DTO
+infrastructure/  : Gateway / Adapter
+presentation/    : CLI Handler / Controller
+```
+
+---
+
+## トレーサビリティメタデータの使い方
+
+このテンプレートが emit する 2 種類のメタデータ:
+
+### 1. YAML frontmatter (`initial_creation: true`)
+- 文書の**新規作成時のみ**付与する
+- `@story-id` インライン注釈が必須であることを示すフラグ
+- 2 回目以降の改訂では frontmatter を削除（または `false` に変更）して構わない
+
+### 2. `@story-id` インライン注釈
+- ユーザーストーリーに紐づく設計要素の**直前に独立行で記述**
+- 形式: `@story-id HXX-XX`
+- ルール:
+  - 独立行（他のテキストと混在させない）
+  - 直後に設計要素（空行を挟まない）
+  - `HXX-XX` は `docs/product/user_stories.md` に存在する ID
+  - 複数ストーリー時は連続並列で並べ、最後の直後に設計要素
+
+これらは `MetadataValidator.validateDesignDocument` で検証され、
+ISSUE-008 Phase B-2 / B-3 以降は `npx phasegate validate-metadata` / pre-commit で自動チェックされる。

package/templates/source.template.ts

@@ -0,0 +1,18 @@
+// @unit <UNIT_NAME>
+// @layer <LAYER>
+
+/**
+ * phasegate ソースファイルテンプレート
+ *
+ * 使い方:
+ *   1. `<UNIT_NAME>` を `docs/product/construction/` 配下の Unit ID に置換
+ *      （例: traceability-model, harness-api）
+ *   2. `<LAYER>` を以下のいずれかに置換
+ *      - domain         : Entity / ValueObject / Port / Domain Service
+ *      - application    : UseCase / DTO / Application Service
+ *      - infrastructure : Gateway / Adapter（外部 I/O 接続）
+ *      - presentation   : CLI Handler / Controller / Formatter
+ *   3. 配置ディレクトリと `@layer` 値を一致させる（L1-004 ルール）
+ *
+ * このメタデータは L1 Biome ルール（L1-001 / L1-002）で検証される。
+ */

package/templates/test.template.ts

@@ -0,0 +1,37 @@
+// @unit <UNIT_NAME>
+// @layer test
+// @story <STORY_ID>
+
+/**
+ * phasegate テストファイルテンプレート
+ *
+ * 使い方:
+ *   1. `<UNIT_NAME>` を被テスト実装と同じ Unit ID に置換
+ *   2. `<STORY_ID>` を本テストがカバーする User Story ID に置換
+ *      （例: H03-02。複数カバーする場合は `H03-01, H03-02` のようにカンマ区切り）
+ *   3. `<TestSubject>` を対象のクラス / 関数名に置換
+ *   4. `target` / `context` は project の test-helpers から import される describe エイリアス
+ *
+ * このメタデータは `MetadataValidator.validateTest` で検証される:
+ *   - `@story` が存在すること
+ *   - `HXX-XX` 形式であること
+ *   - `docs/product/user_stories.md`（StoryCatalog）に存在する ID であること
+ *
+ * pre-commit 経路で自動チェックされる（ISSUE-008 Phase C-3）。
+ */
+
+import { describe, expect, it } from 'vitest';
+import { target, context } from '../helpers/test-helpers.js';
+
+target('<TestSubject>', () => {
+  context('<前提条件・シナリオ>', () => {
+    it('<期待される挙動を日本語で記述>', () => {
+      // Arrange
+      const input = 'TODO';
+      // Act
+      const actual = input;
+      // Assert
+      expect(actual).toBe('TODO');
+    });
+  });
+});