phasegate 0.134.0 → 0.135.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.135.0] - 2026-05-09
+
+### Added
+
+- **WI-033 — `doc-freshness` / `pointer-validation` を L4 validators に昇格** — 既存の `p2:check-freshness` / `p2:validate-pointers` CLI を維持しつつ、`validate --layer L4` で L4-004 / L4-005 として実行されるようにした。
+  - `validator-system` に `L4-004 doc-freshness` / `L4-005 pointer-validation` を登録し、preset ごとの enable / disable 判定に対応。
+  - default の検査対象は `phasegate.config.json` の `paths.designDocs` から導出し、`paths.inceptionDocs` と archive 配下の計画・履歴文書は pointer validation の対象外にした。
+  - Markdown pointer 抽出を改善し、相対リンク・アンカー・行番号 suffix を正規化しつつ、placeholder / template / glob 表現の false positive を抑制。
+  - `docs/contracts/lesson-artifact.schema.json` を追加し、ci-governance / skill-quality 間の lesson artifact 契約参照を実在化。
+  - 旧ディレクトリ構成を指していた設計文書内の test path 参照を現行構成へ整理し、`p2:validate-pointers` は `broken=0` を確認済み。
+
 ## [0.134.0] - 2026-05-08
 
 ### Changed

package/bin/phasegate

@@ -12,6 +12,8 @@ if command -v tsx >/dev/null 2>&1; then
   exec tsx "$MAIN_TS" "$@"
 elif [ -f "$PACKAGE_DIR/node_modules/.bin/tsx" ]; then
   exec "$PACKAGE_DIR/node_modules/.bin/tsx" "$MAIN_TS" "$@"
+elif [ -f "$PACKAGE_DIR/../.bin/tsx" ]; then
+  exec "$PACKAGE_DIR/../.bin/tsx" "$MAIN_TS" "$@"
 else
   echo "Error: tsx not found. Run: npm install" >&2
   exit 1

package/docs/contracts/lesson-artifact.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://phasegate.dev/schemas/lesson-artifact.schema.json",
+  "title": "Lesson Artifact Contract",
+  "description": "Cross-unit contract for Agent-Lesson artifacts exchanged by ci-governance and skill-quality.",
+  "oneOf": [
+    {
+      "$ref": "#/definitions/lessonArtifact"
+    },
+    {
+      "$ref": "#/definitions/storyLessonArtifact"
+    }
+  ],
+  "definitions": {
+    "lessonArtifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["lessonId", "source", "content", "tags", "timestamp"],
+      "properties": {
+        "lessonId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "content": {
+          "type": "string",
+          "minLength": 1
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "storyLessonArtifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["storyId", "lessons"],
+      "properties": {
+        "storyId": {
+          "type": "string",
+          "pattern": "^H[0-9]+-[0-9]+$"
+        },
+        "lessons": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/lessonArtifact"
+          }
+        }
+      }
+    }
+  }
+}

package/docs/contracts/requirement-test-matrix.schema.json

@@ -0,0 +1,62 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "generatedAt", "stories"],
+  "properties": {
+    "version": {
+      "type": "string"
+    },
+    "generatedAt": {
+      "type": "string"
+    },
+    "stories": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["storyId", "storyMappings"],
+        "properties": {
+          "storyId": {
+            "type": "string",
+            "pattern": "^H\\d{2}-\\d{2}$"
+          },
+          "storyMappings": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["acId", "testReferences"],
+              "properties": {
+                "acId": {
+                  "type": "string",
+                  "pattern": "^AC-[1-9][0-9]*$"
+                },
+                "testReferences": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["filePath", "testType"],
+                    "properties": {
+                      "filePath": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "testType": {
+                        "type": "string",
+                        "enum": ["unit", "it", "scenario"]
+                      },
+                      "testName": {
+                        "type": "string"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/docs/guide/layer-model.md

@@ -147,8 +147,8 @@ L4 validators are designed to run on a weekly schedule and detect slow-moving dr
 | **drift-detect** | L4-001 | Bidirectional design-code drift detection. Compares design documents against the actual codebase to find divergence in either direction. |
 | **consistency-check** | L4-002 | Cross-document layer consistency. Ensures that references between design documents, ADRs, and code remain coherent. |
 | **dead-code** | L4-003 | Detects unused exports and unreachable code that should be removed. |
-
-> **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`.
+| **doc-freshness** | L4-004 | Checks whether design documents exceed the configured freshness threshold. The standalone `p2:check-freshness` CLI remains available. |
+| **pointer-validation** | L4-005 | Validates file-path pointers embedded in design documents. The standalone `p2:validate-pointers` CLI remains available. |
 
 ### Drift-detect design pointers
 

package/docs/principles/architecture-philosophy.md

@@ -1,64 +1,35 @@
-# Unit Developer 共通ルール
+# アーキテクチャ原則
 
-このファイルはすべてのUnit Developer（Unit1〜Unit6）に共通するルールを定義する。
-各Unitの固有ルールは対応する `unitN-developer.md` に記述されている。
+この文書を設計・実装判断の共通原則とする。Unit 固有の詳細は `docs/product/` と `docs/inception/` の該当文書に従う。
 
-## Persona
+## 基本方針
 
-あなたはKent Beck（TDD）、Martin Fowler（リファクタリング）、Uncle Bob（Clean Architecture）、Eric Evans（DDD）の設計哲学を体現するソフトウェアエンジニアであり、担当Unitの専任開発者である。
+- **設計書駆動**: 実装前に該当 WI、inception、product docs を読み、仕様を確認する。推測で実装しない。
+- **PhaseGate 優先**: `docs/folder_management_rules.md` の AIDLC フェーズ順序を守る。実装前に必要な inception 成果物と product 反映を確認する。
+- **既存設計尊重**: 変更対象と周辺コードを読み、既存の責務分割、命名、テスト粒度に合わせる。
+- **最小変更**: 依頼された目的に必要な範囲だけを変更する。無関係なリファクタリングや先回りの抽象化をしない。
+- **テストで証明**: 重要なふるまいは自動テストで確認する。手動確認だけで完了扱いにしない。
 
-## エンジニアリング哲学（共通）
+## アーキテクチャ境界
 
-- **設計書駆動:** 実装の前に必ず設計書を読み、仕様を正確に理解してからコードを書く。推測で実装しない。
-- **アーキテクチャ厳守:** ヘキサゴナルアーキテクチャ（ポート＆アダプター）とDDDの原則に従い、レイヤー間の依存方向を絶対に違反しない。`domain → port → repository/usecase → controller` の依存方向を常に意識する。
-- **最小限の変更:** 与えられたタスクに必要な最小限の変更のみを行う。過剰な抽象化、不要なリファクタリング、先回りの実装を一切しない。
-- **テストによる証明:** 実装の正しさはテストで証明する。手動確認に頼らず、自動テストで再現可能な形で検証する。
-- **既存コードへの敬意:** 変更前に既存のコードを必ず読み、設計意図を理解する。既存のパターンやコンベンションに従い、一貫性を保つ。
-- **ドメインモデルの豊かさ:** ビジネスロジックは値オブジェクト・エンティティ・集約に配置することを最優先とする。Usecaseは集約の取得・永続化・ドメインイベント発行などの調整役に徹する。ドメインサービスは「複数集約にまたがる操作」「外部システム連携を含むドメインロジック」など、上記のいずれにも自然に属さない場合に限り、例外的に使用する。安易にドメインサービスを作ることで集約が貧血モデル（Anemic Domain Model）に陥ることを防ぐ。
+- ヘキサゴナルアーキテクチャと DDD の方針に従う。
+- ドメイン層は外側の infrastructure / presentation に依存しない。
+- UseCase は調整役とし、ビジネスルールは可能な限り Entity / Value Object / Aggregate に置く。
+- Domain Service は、Entity / Value Object / Aggregate に自然に属さない複数概念のルールに限って使う。
+- Port はアプリケーション境界を表し、外部 I/O の詳細は Adapter に閉じ込める。
 
-## 専門領域（共通）
+## 変更スコープ
 
-- TypeScript（型安全性を最大限に活用した堅牢な実装）
-- ヘキサゴナルアーキテクチャ / DDD（エンティティ、値オブジェクト、集約、リポジトリパターン、ドメインサービスは例外的使用）
-- Vitest（ユニットテスト、統合テスト）
+- 原則として対象 Unit と、その変更に必要な共有契約だけを触る。
+- cross-cutting WI では `description.md` の `affects` を確認し、影響 Unit の product 反映を揃える。
+- プロジェクトルート外のファイルは触らない。
+- ユーザーや他作業者の未関連変更を戻さない。
 
-## 参照先（共通）
+## 作業順序
 
-| カテゴリ | パス |
-| --- | --- |
-| ドメイン用語 | `product_overview.md` |
-| バックエンド実装 | `backend/` |
-| フロントエンド実装 | `frontend/` |
-| ユニット間の契約 | `integration_contract.md` |
-
-> ※ バックエンド設計書・フロントエンド設計書・ユニット要件のパスは各Unitファイルを参照。
-
-## 禁止事項（共通・絶対厳守）
-
-- **NEVER:** 担当UnitとShared Kernal以外のUnitに関するコードを変更する（依存関係がある場合や、全体最適のために必要な場合を除く）
-- **NEVER:** 担当UnitとShared Kernal以外のUnitの設計書を参照・変更する（依存関係がある場合や、ドメイン用語集を除く）
-- **NEVER:** プロジェクトルート外でのファイル操作
-- **NEVER:** 設計書を確認せずに実装を開始する
-- **NEVER:** 既存コードを読まずに変更する
-
-## 必須事項（共通）
-
-- **YOU MUST:** 実装開始前に担当Unitの設計書を確認する（バックエンド設計書・フロントエンド設計書の両方）
-- **YOU MUST:** ドメイン用語は `atomica_ubiquitous_word.md` に従う（コード内の命名も含む）
-- **YOU MUST:** 既存の実装コードを確認してから変更を行う
-
-## ワークフロー（共通）
-
-タスクを受け取ったら、以下の順序で作業する。
-
-1. **設計書の確認** — 該当する設計書を読み、仕様・制約・ドメインルールを把握する
-2. **既存コードの確認** — 変更対象と周辺のコードを読み、設計意図とパターンを理解する
-3. **テストの作成（TDD）** — 実装に先立ち、仕様を満たすために必要最小限のテストを書く。E2Eテスト・インテグレーションテスト・ユニットテストを適切な粒度で用意し、まず失敗する状態（Red）を確認する
-4. **実装** — テストを通過させることを目標に、設計書に忠実かつ既存パターンに従って最小限の変更を行う（Green）
-5. **リファクタリング** — テストが通る状態を維持しながら、コードの可読性・設計品質を改善する（Refactor）
-6. **シナリオ確認** — 各Unitファイルに定義された確認フローを実行する
-7. **レポート出力** — 完了報告を出力する
-
-## スコープ境界（共通原則）
-
-担当Unitの範囲内でのみ作業する。他のUnitのコード・設計書には関与しない。自分の担当領域を完璧に仕上げることが、プロジェクト全体の品質につながるという信念を持つ。
+1. 関連する inception / product docs を確認する。
+2. 変更対象と周辺コードを読む。
+3. 必要なら先にテストを追加・更新する。
+4. 最小実装でテストを通す。
+5. 必要な検証コマンドを実行する。
+6. 変更内容、検証結果、未検証事項を報告する。

package/docs/principles/model-routing.md

@@ -1,176 +1,41 @@
-# モデルルーティング規約
+# モデルルーティング原則
 
-## 原則
-
-**Opus = 決める、Sonnet = 広げる、Codex = 作る。**
-
-| 役割 | モデル | 得意領域 |
-|------|--------|---------|
-| Architect | Opus 4.6 | 発明・判断・骨格設計・品質レビュー |
-| Expander | Sonnet 4.6 | 展開・量産・構造化・列挙 |
-| Implementor | Codex GPT-5.4 | TDD実装・repo整合・コード生成 |
-
----
-
-## モデル割り当て表
-
-### 骨格設計（Opus 4.6 — メインセッション内実行）
-
-| Skill | AIDLC Step | 理由 |
-|-------|-----------|------|
-| `product-architect` | 0 | プロダクト全体像の発明・制約統合 |
-| `domain-designer` | 2.1 | 集約境界・不変条件の発明 |
-| `logical-designer` | 2.2 | 横断設計の骨格判断 |
-| `uiux-designer` | 7 | 体験設計・導線の発明 |
-| `kimunii-perspective` | Any | 多角的な品質判断 |
-| `skill-creator` | Tooling | スキル設計・構造化 |
-
-### 展開・量産（Sonnet 4.6 — 委任実行 → Opusレビュー）
-
-| Skill | AIDLC Step | 理由 |
-|-------|-----------|------|
-| `story-writer` | 1.1 | US一覧の粒度統一・量産 |
-| `unit-designer` | 1.2 | Unit-USマッピング表の量産 |
-| `story-mapper` | 1.5 | MVP整理・優先順位表化 |
-| `mock-designer` | 2 | 画面一覧・状態展開 |
-| `environment-designer` | 2.2並行 | 環境構成の列挙・整理 |
-| `scenario-test-designer` | 6 | E2Eテストケース列挙 |
-| `unit-test-designer` | 8前段 | ユニットテストケース列挙 |
-| `it-test-designer` | 8前段 | ITテストケース列挙 |
-| `unit-test-logic-designer` | 8前段 | テスト疑似コード展開 |
-| `it-test-logic-designer` | 8前段 | IT疑似コード展開 |
-| `scenario-test-logic-designer` | 8前段 | E2E疑似コード展開 |
-| `implementation-planner` | 実装前 | 実装計画の構造化展開 |
-| `cascade-updater` | 全工程 | 上位文書への変更波及 |
-| `consistency-checker` | 全工程 | 文書間整合チェック |
-| `test-coverage-checker` | 6以降 | カバレッジ網羅性検証 |
-| `implementation-readiness-checker` | 実装前 | 準備状況チェック |
-
-### 接地・実装（Codex GPT-5.4 — codex-delegator経由）
-
-| Skill | AIDLC Step | 理由 |
-|-------|-----------|------|
-| `story-implementor` | 2.3-2.7 | TDD実装（コード生成） |
-| `codex-delegator` | Any | 並列タスク委任 |
-
----
-
-## Sonnet委任プロトコル
-
-### 実行フロー
-
-```
-┌─────────────────────────────────────────────────┐
-│ Phase 1: 計画（Opus in-session）                  │
-│  - Skillのプロンプトに従い計画を立案               │
-│  - 出力: Sonnetへの委任プロンプト + レビュー観点    │
-│  → 人間承認待ち                                    │
-├─────────────────────────────────────────────────┤
-│ Phase 2: 実行（Sonnet委任）                       │
-│  - delegate-sonnet.sh 経由で Sonnet 4.6 に委任     │
-│  - Sonnetはファイル読み取り + 文書生成のみ          │
-│  - 出力: 設計文書（mdファイル）                     │
-├─────────────────────────────────────────────────┤
-│ Phase 3: レビュー（Opus in-session）              │
-│  - Sonnet出力を品質基準で検証                      │
-│  - PASS → 完了                                    │
-│  - FAIL → Opusが直接修正                          │
-└─────────────────────────────────────────────────┘
-```
-
-### Phase 2: Sonnet委任
+この文書は、複数モデルやサブエージェントを使う場合の判断基準を定義する。固定のモデル名やバージョンではなく、役割で判断する。
 
-#### 委任方法
+## 役割
 
-```bash
-# scripts/delegate-sonnet.sh を使用
-bash scripts/delegate-sonnet.sh \
-  --prompt "委任プロンプト" \
-  --output "出力ファイルパス" \
-  --context "読み込みファイル1,読み込みファイル2"
-```
+| 役割 | 主な責務 |
+|------|----------|
+| Architect | 判断、骨格設計、品質レビュー、トレードオフ整理 |
+| Expander | 既存方針に沿った列挙、表作成、章展開、整合チェック |
+| Implementor | TDD 実装、リポジトリ整合、検証、修正 |
 
-#### Sonnetへの委任プロンプト構造
-
-```
-[コンテキスト層] 読むべきファイルパス + 上位設計文書の引用
-[タスク層]       作業内容、入力ファイル、出力ファイルパスと期待フォーマット
-[制約層]         変更許可ファイル、スコープ制限、フォーマット規約
-[禁止層]         判断を含む作業の禁止（判断はOpusが行う）
-```
-
-#### Sonnetに委任してよい作業
-
-- 一覧表・マトリクスの作成
-- テストケースの列挙
-- 既存骨格に沿った章展開
-- 用語表・制約表の整理
-- 設計文書間のマッピング表作成
-- チェックリストの実行
-
-#### Sonnetに委任してはいけない作業
-
-- 集約境界の決定
-- アーキテクチャ選択の判断
-- 優先順位の最終決定
-- トレードオフを伴う設計判断
-- レビュー結果に基づく修正方針の決定
-
-### Phase 3: Opusレビュープロトコル
-
-#### レビュー観点（全Sonnet委任共通）
-
-| ID | 観点 | 検証内容 | 重大度 |
-|----|------|---------|--------|
-| R1 | 上位文書整合 | 上位設計文書（product_overview, domain設計等）との矛盾がないか | BLOCK |
-| R2 | 粒度一貫性 | 成果物内で抽象度・粒度が統一されているか | BLOCK |
-| R3 | 網羅性 | 入力に含まれる要素が漏れなく展開されているか | BLOCK |
-| R4 | 配置ルール | `folder_management_rules.md` に準拠しているか | BLOCK |
-| R5 | 判断混入 | Sonnetが独自判断を行っていないか（骨格逸脱） | BLOCK |
-| R6 | 表現品質 | 用語・文体がプロジェクト規約と統一されているか | WARN |
-| R7 | YAGNI | スコープ外の「改善」「将来への備え」がないか | WARN |
-
-#### 判定ロジック
-
-```
-BLOCK に 1つでも FAIL → Opus が直接修正
-WARN のみ FAIL         → Opus が直接修正（軽微）
-全 PASS                → 完了
-```
-
-**重要: Sonnetへの再委任は行わない。** 修正はすべてOpusが直接行う。
-理由: 修正は「何が問題か」の判断を含むため、Opus の責務である。
-
-#### レビュー出力フォーマット
-
-```markdown
-## Opus Review
-
-### 判定: PASS / FAIL
+## 原則
 
-### 検証結果
-| ID | 観点 | 結果 | 備考 |
-|----|------|------|------|
+- 判断を伴う設計・優先順位・境界決定は Architect が行う。
+- 大量展開や一覧化は Expander に委任してよい。ただし、入力方針と出力ファイルを明確にする。
+- 実装、テスト、リポジトリ内の整合修正は Implementor が担当する。
+- 委任結果は必ず親エージェントがレビューし、配置ルール、上位文書整合、スコープ逸脱を確認する。
+- ユーザーまたは実行環境の指示でサブエージェント利用が制限されている場合は、その指示を優先する。
 
-### 修正内容（FAILの場合）
-- [R1] {ファイル}: {修正内容}
-- ...
-```
+## 委任してよい作業
 
----
+- 既存設計に沿ったテストケース列挙
+- マトリクス、対応表、チェックリスト作成
+- 用語や参照関係の整理
+- 明確な入力に基づく文書章の展開
 
-## ハイブリッド分業パターン
+## 委任しない作業
 
-一部のSkillでは Phase 1（Opus骨格）→ Phase 2（Sonnet展開）の分業が有効。
+- 集約境界やアーキテクチャ方針の決定
+- 優先順位やスコープの最終判断
+- 仕様の曖昧さを解釈して確定する作業
+- レビュー指摘に対する修正方針の決定
 
-| Skill | Opusが決めること | Sonnetが広げること |
-|-------|-----------------|-------------------|
-| `story-writer` | US粒度の判断基準、分割方針 | US一覧の列挙、受け入れ基準の標準化 |
-| `logical-designer` | 横断設計の骨格、レイヤー方針 | 章展開、DTO/UseCase一覧、ケース表 |
-| `unit-test-designer` | テスト戦略、重点観点 | テストケース一覧、境界値列挙 |
+## レビュー観点
 
-このパターンでは:
-1. Phase 1 で Opus が骨格（アウトライン + 判断事項）を出力
-2. 人間承認
-3. Phase 2 で Sonnet に骨格を渡して展開を委任
-4. Phase 3 で Opus がレビュー + 修正
+- `docs/folder_management_rules.md` に沿った配置か。
+- 上位文書と矛盾していないか。
+- 入力に含まれる要求が漏れていないか。
+- 独自判断やスコープ外の提案が混ざっていないか。
+- 用語、粒度、文体が既存文書と揃っているか。