phasegate 0.111.0 → 0.114.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.114.0] - 2026-05-07
+
+### Security
+
+- **WI-035: phase2-extensions の git-log adapter におけるコマンドインジェクション脆弱性 (HIGH) を修正** — `/security-review` で発見。`execSync` テンプレート文字列に `documentPath` / `filePath` をダブルクオート展開していたため、ファイル名に `$()` / バッククオート / `;` 等のシェルメタ文字を含めると `/bin/sh -c` 経由で任意コードが実行される経路があった（攻撃者は POSIX 許容範囲のファイル名を含む公開リポジトリを 1 つ用意するだけで成立。clone / `gh pr checkout` でローカルに展開された時点で発火し、マージは不要）。
+  - `scripts/harness/phase2-extensions/infrastructure/adapters/git-log-document-age-adapter.ts` の `gitLogExecutor` を `execFileSync` 配列引数形式（`('git', ['log', '--format=%ai', '-1', '--', documentPath], ...)`）に置換。
+  - `scripts/harness/phase2-extensions/infrastructure/adapters/git-log-initial-creation-age-adapter.ts` の `gitExecutor` を同形式に置換（`runGit(args)` の signature も合わせて変更）。
+  - DI ポートの signature を `(command: string) => Buffer` から `(file: string, args: readonly string[], options) => Buffer` に変更。
+  - 悪意あるファイル名（`$()` / バッククオート / `;` / `"` / `|` 含む）でも引数が **配列要素のまま** 渡され、シェルメタ文字として評価されないことを assert する unit test を 2 ファイルに追加。
+  - 横展開監査結果: 同種パターン (`execSync(\`...${var}...\`)`) は他に `scripts/harness/skill-quality/infrastructure/adapters/git-commit-executor-adapter.ts:14` に 1 箇所存在（`JSON.stringify` 経由だが `$` / バッククオートが残存）。本 WI のスコープ (`affects: [phase2-extensions]`) 外のため follow-up WI として WI-035 description に記録。
+
 ## [0.110.0] - 2026-04-25
 
 ### Documentation

package/README.ja.md

@@ -1,10 +1,12 @@
+![Phasegate header](assets/phasegate-header.png)
+
 # Phasegate
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
 
-**AI が書いたコードに「設計してから書け」を物理的に強制するツールキット。**
-Claude Code / Codex / Cursor / Copilot — どの AI agent でも同じ防御が効きます。
+**AI agent に「設計してから書け」を hooks / git / CI で強制するツールキット。**
+Claude Code / Codex / Cursor / Copilot — どの AI agent でも設計意図・レイヤー境界・テスト規約を守らせます。
 
 [English README](README.md) ・ [開発者ガイド](DEVELOPMENT.ja.md)
 
@@ -12,7 +14,7 @@ Claude Code / Codex / Cursor / Copilot — どの AI agent でも同じ防御が
 
 ## 30 秒でわかる Phasegate
 
-1. **AI agent が設計文書なしで実装ファイルを書こうとすると、Write/Edit/Bash がブロックされる**（PreToolUse hook）
+1. **AI agent が設計文書なしで実装ファイルを書こうとすると、Write/Edit/Bash または git hook で止まる**
 2. **コミット前に L1〜L3 のバリデーションが自動で走り**、レイヤー違反・テスト品質違反・依存方向違反を弾く
 3. **ブロック時のエラーは AI が読んで自己修正できる形式**（理由・必要な設計文書・次に打つべきスキル名が出る）
 
@@ -24,7 +26,7 @@ Claude Code / Codex / Cursor / Copilot — どの AI agent でも同じ防御が
 
 AI agent は速いが、設計を飛ばして実装に走ります。レイヤー境界を平気で越え、`any` 型で型システムを骨抜きにし、テストはあるけど実装の写経になっている — そんなコードを高速に量産します。レビューで全部捕まえるのは現実的ではありません。
 
-Phasegate はこれを **「人がレビューで防ぐ」のではなく「ツールがファイルシステム/git/CI レベルで防ぐ」** で解決します。設計文書がなければそもそも書けない。レイヤー違反があれば commit が通らない。AI agent 自身が「次にどの設計スキルを呼べばいいか」を読んで自走します。
+Phasegate はこれを **「人がレビューで防ぐ」のではなく「ツールが hooks / git / CI レベルで防ぐ」** で解決します。設計文書がなければ書き込みまたは commit が止まる。レイヤー違反があれば CI が通らない。AI agent 自身が「次にどの設計スキルを呼べばいいか」を読んで自走します。
 
 ### こんなプロジェクトで効きます
 
@@ -51,7 +53,7 @@ AI agent が設計なしに `src/order/order-service.ts` を書こうとする
   実行例: /story-implementor --unit order
 ```
 
-Claude Code / Codex はこのメッセージを読んで `/story-implementor` を起動し、ドメイン設計→論理設計→TDD 実装の順で進みます。人間が「設計やってからね」と言わなくても自走します。
+Claude Code / Codex はこのメッセージを読んで `/story-implementor` を起動し、ドメイン設計→論理設計→TDD 実装の順で進みます。単に失敗させるのではなく、AI agent が復帰できる形で「次に何を作るべきか」を返します。
 
 ---
 
@@ -81,9 +83,19 @@ claude
 - `skills/` — 28 の AIDLC スキル一式
 - `.claude/skills/` ・ `.codex/skills/` — agent 向けの skill symlink
 - `.claude/settings.json` — PreToolUse / PostToolUse / Stop hook
-- `docs/principles/` ・ `docs/folder_management_rules.md` — 設計原則 docs
+- `.codex/hooks.json` — Codex CLI hooks 設定（`--agent codex|both` 時）
+- `docs/principles/*.md` — アーキテクチャ哲学・テスト規約（immutable）
+- `docs/folder_management_rules.md` — ドキュメント配置ルール（**正本**）
 - `--with-husky` を付けると `.husky/pre-commit` ・ `.husky/commit-msg` も配置
 
+**`init` が生成しないもの**（後で skill が作る）:
+
+- `docs/inception/` 配下の WI directory — `/product-architect` 以降のスキル実行で生成
+- `docs/product/` 配下の確定設計文書 — `/domain-designer` `/logical-designer` 等が生成
+- `docs/ADR/` — `/skill-creator` や手動で必要に応じて作成
+
+「設計してから書け」を強制する仕組みなので、設計文書はユーザーがスキル経由で作るのが既定動作です。
+
 ### Codex CLI を使う場合
 
 ```bash
@@ -91,7 +103,7 @@ npx phasegate init --name my-project --agent codex --with-husky
 codex features enable codex_hooks   # Codex 本体の feature flag を手動で有効化
 ```
 
-両方使う場合は `--agent both`。詳細は [Codex Integration Guide](docs/guide/codex-integration.md) を参照。
+両方使う場合は `--agent both`。Codex のネイティブ `apply_patch` は現時点で事前 hook を発火しないため、pre-commit (L2) で commit 時にブロックします。Bash 経由の書き込みは実行前に止まります。詳細は [Codex Integration Guide](docs/guide/codex-integration.md) を参照。
 
 ### アップデート
 
@@ -113,6 +125,7 @@ npx phasegate update-skills   # スキルを最新版に再デプロイ
 | **Claude Code / Codex Hooks** | Write/Edit/Bash 時に自動でゲートチェック・lint を実行 |
 | **HarnessError 形式** | 全エラーに ADR 参照 + 修正例が含まれ、AI が自己修正できる |
 | **Baseline (retrofit)** | 既存リポジトリ導入時、`baseline` snapshot に登録した既存ファイルは構造的に編集されるまで gate 対象外 |
+| **カスタム gate** | AIDLC 以外のプロジェクトでも schema-first など独自の前提条件を設定できる |
 
 ---
 
@@ -176,21 +189,43 @@ AIDLC (AI-Driven Development Life Cycle) は **要求定義 → 設計 → テ
 
 ## メタデータ規約
 
-ソースファイル先頭に `@unit` / `@layer` を、テストには `@story` を記載します。L1 はこれを使ってレイヤー違反検出と drift-detection を行います。
+ソースファイル先頭に `@unit` / `@layer` を、テストには `@story` または `@work-item-id` を記載します。L1 / L2 はこれを使ってレイヤー違反検出・drift-detection・WI トレーサビリティを行います。
 
 ```typescript
 // @unit config-foundation
 // @layer domain
-// @story US-001          ← テストファイルのみ
+// @work-item-id WI-042   ← 任意（traceability に貢献）
+// @story US-001          ← テストファイルのみ（legacy 互換）
 
 export class ConfigSchema { ... }
 ```
 
-| タグ | 値 |
-|---|---|
-| `@unit` | `/unit-designer` が定義した Unit 名（例: `config-foundation`） |
-| `@layer` | `architecture.preset` で定義した層名（例: `domain` / `application` / `infrastructure` / `presentation`） |
-| `@story` | 検証する US の ID（例: `US-001`） |
+| タグ | 値 | 必須性 |
+|---|---|---|
+| `@unit` | `/unit-designer` が定義した Unit 名（例: `config-foundation`） | **必須**（L1-001 が検証） |
+| `@layer` | `architecture.preset` で定義した層名（例: `domain` / `application` / `infrastructure` / `presentation`） | **必須**（L1-002 が検証） |
+| `@work-item-id` | このファイル変更を駆動した WI（例: `WI-042`） | 任意 |
+| `@story` | 検証する US / WI の ID（例: `US-001`, `H02-04`） | テストでは推奨（legacy 互換） |
+
+### product 文書での反映宣言
+
+product 文書（`docs/product/construction/{unit}/*.md`）の章ごとに、反映元の WI を `@work-item-id` で記載します:
+
+```markdown
+## ポート定義
+
+<!-- @work-item-id WI-042 -->
+### OrderRepository Port
+- findById(id: OrderId): Promise<Order>
+
+<!-- @work-item-id WI-042, WI-051 -->
+### PaymentGateway Port
+- charge(amount: Money): Promise<Receipt>
+```
+
+L2-STORY-REFLECTION バリデータがこのアノテーションを検出し、inception 設計が product に反映されているかを判定します。
+
+> **legacy 互換**: 既存 product 文書の `@story-id US-XXX` / `@story-id H##-##` / `@issue-id ISSUE-XXX` は、WI frontmatter の `legacy_id` 経由で読み替えられます。一括置換は **しません**。新規記述は `@work-item-id WI-XXX` を使ってください。
 
 ---
 
@@ -260,7 +295,7 @@ npx phasegate <command> [options]
 | `phasegate:status` | 全体の健全性サマリ |
 | `phasegate:check-phase --unit <id>` | 指定 Unit の現在フェーズ |
 | `phasegate:detect-drift` | 設計-コード乖離レポート |
-| `migrate work-items --dry-run` / `--apply` | 旧 `ISSUE-XXX` / `H{NN}-{NN}` を `WI-XXX` 統一レイアウトへ移行 |
+| `migrate work-items --dry-run` / `--apply` | 既存リポジトリの旧 `ISSUE-XXX` / `H{NN}-{NN}` directory を WI 統一レイアウト（`_cross/{WI-XXX}/` / `{unit}/{WI-XXX}/`）へ移行。frontmatter（`type` / `severity` / `legacy_id` / `affects`）を自動注入。冪等。`--json` で CI/スクリプト連携可。詳細: [Work Item Migration](docs/guide/cli-reference.md#work-item-migration) |
 | `migrate --schema v3` | `phasegate.config.json` を v3 schema へ昇格（`architecture` キー追加） |
 | `ci:generate-template --type <aidlc-gate\|pre-commit\|consistency-check>` | CI/CD テンプレート生成（`--render` でファイル出力） |
 | `list-errors --layer <L0-L4>` | エラー定義一覧 |
@@ -299,21 +334,104 @@ npx phasegate <command> [options]
 
 ---
 
+## ドキュメント・ライフサイクル
+
+Phasegate は **「inception で設計を起こし → product に確定させ → src に実装する」** という単方向のデータフローを物理的に強制します。各段階で生成される文書と PhaseGate の振る舞いが対応しています。
+
+### 三階層モデル
+
+```
+docs/inception/{unit}/{WI-XXX}/   ← 一時的な計画・設計（WI ごと、流動）
+        ↓ 設計成果物の反映（@work-item-id 付きで累積更新）
+docs/product/construction/{unit}/  ← 確定設計（Unit ごとの正本、永続）
+        ↕ フェーズゲート
+scripts/harness/{unit}/(domain|application|infrastructure|presentation)/*.ts
+```
+
+### Work Item (WI) の置き場
+
+WI は規模・影響範囲に応じて 3 通りに振り分けます。
+
+| 配置先 | 用途 |
+|---|---|
+| `docs/inception/_shared/` | 非 WI の横断計画・戦略・調査メモ |
+| `docs/inception/_cross/{WI-XXX}/` | 複数 Unit に影響する cross-cutting WI |
+| `docs/inception/{unit}/{WI-XXX}/` | 単一 Unit が所有する WI |
+
+> **廃止済み**（v0.104.0 で物理削除）: `docs/inception/issues/`, `docs/inception/{unit}/issues/`, `docs/inception/{unit}/{US-XXX}/`。既存資産は `npx phasegate migrate work-items --apply` で `WI-XXX` へ移行済み。`legacy_id` で旧 ID の grep 互換は維持。
+
+### WI frontmatter（必須）
+
+各 WI の `description.md` 先頭に:
+
+```yaml
+---
+id: WI-042
+type: story | issue | fix | refactor | chore   # 後述
+severity: trivial | normal | high
+status: drafted | reflected | implemented | tested   # PhaseGate が自動更新
+affects: [unit-a, unit-b]                            # cross-unit のみ列挙
+legacy_id: ISSUE-XXX | US-XXX | H{NN}-{NN}          # 任意
+---
+```
+
+L2 metadata validator が frontmatter の妥当性を検証します。
+
+### type による要求成果物の段階化
+
+| `type` | inception 必須 | product 反映 | 用途 |
+|---|---|---|---|
+| `story` | description + logical_design + domain_model + test 設計 | 全カテゴリ累積 | 新機能 |
+| `issue` | description + logical_design + domain_model + 関係 test 設計 | 関係カテゴリ累積 | バグ・仕様不整合 |
+| `refactor` | description + logical_design | logical_design 更新 | リファクタ |
+| `fix` | description + PR link | 関係カテゴリに `@work-item-id` 追記 | typo・依存更新等 |
+| `chore` | description.md 1 行 + PR link | 不要 | 雑用 |
+
+`fix` / `chore` は軽量パスとして提供。formal な story で起票するには重すぎる修正もここで証跡が残せます。
+
+### State Machine
+
+```
+DRAFTED (inception 揃う)
+  ↓ Phase 0/2 reflection
+REFLECTED (product に @work-item-id 反映済み)
+  ↓ Phase 3 implementation
+IMPLEMENTED (src 実装あり / lint・type・test green)
+  ↓ Phase 4 test
+TESTED (@work-item-id 付きテストあり / green)
+```
+
+`type: chore` は DRAFTED で完結。`type: fix` は DRAFTED → REFLECTED → IMPLEMENTED の簡略パス。`status` は PhaseGate が自動更新します。
+
+詳細仕様: [`docs/folder_management_rules.md`](docs/folder_management_rules.md)
+
+---
+
 ## 導入後のプロジェクト構造
 
 ```
 your-project/
 ├── phasegate.config.json
 ├── docs/
-│   ├── folder_management_rules.md
-│   ├── principles/                # アーキテクチャ哲学・テスト規約
-│   ├── product/construction/{unit}/   # 確定版設計（domain_model.md / logical_design.md）
-│   ├── inception/{unit}/{US-XXX}/     # AIDLC が生成する設計計画
+│   ├── folder_management_rules.md          # WI 仕様の正本（init で配置）
+│   ├── principles/                         # 開発原則（init で配置・immutable）
+│   ├── inception/                          # AIDLC スキルが生成
+│   │   ├── _shared/                        # 横断計画
+│   │   ├── _cross/{WI-XXX}/                # cross-unit WI
+│   │   └── {unit}/{WI-XXX}/                # Unit 所有 WI
+│   ├── product/                            # 確定設計（累積更新）
+│   │   ├── product_overview.md
+│   │   ├── user_stories.md
+│   │   ├── units/{unit}.md
+│   │   └── construction/{unit}/
+│   │       ├── domain_model.md
+│   │       ├── logical_design.md
+│   │       └── ...
 │   └── ADR/
-├── src/                            # 実装コード（@unit/@layer 必須）
+├── src/                                    # 実装コード（@unit/@layer 必須）
 ├── .claude/{settings.json, skills/}
-├── .codex/{hooks.json, skills/}
-└── skills/                         # init で再生成可能
+├── .codex/{hooks.json, skills/}            # --agent codex|both 時
+└── skills/                                 # init で再生成可能
 ```
 
 推奨 `.gitignore`:
@@ -329,9 +447,9 @@ reports/
 
 ---
 
-## ロードマップ
+## 既知の制約とロードマップ
 
-ドキュメントで言及があるが現状 partial 実装または user 配線に依存しているもの。各 Work Item は `docs/inception/_cross/WI-XXX/description.md` に起票済み。
+主要な導入パスはそのまま利用できますが、一部の機能は user 側の配線が必要、または今後の minor release での改善対象です。各 Work Item は `docs/inception/_cross/WI-XXX/description.md` に起票済みです。
 
 | Work Item | 内容 |
 |---|---|
@@ -340,7 +458,7 @@ reports/
 | **[WI-033](docs/inception/_cross/WI-033/description.md)** | `doc-freshness` / `pointer-validation` を L4 validator に昇格 |
 | **[WI-034](docs/inception/_cross/WI-034/description.md)** | L0 legacy validator (`L0-001` / `L0-002`) の撤去 |
 
-L3 Nyquist Validation の `requirement-test-matrix.json` 自動生成パイプラインも未完成（手動セットアップで利用可）。
+L3 Nyquist Validation の `requirement-test-matrix.json` 自動生成はまだ未自動化です。現時点では手動セットアップで利用できます。
 
 ---
 

package/README.md

@@ -1,61 +1,124 @@
+![Phasegate header](assets/phasegate-header.png)
+
 # Phasegate
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
 
-**Phasegate -- AI-agnostic quality defense toolkit.**
+**A toolkit that makes AI agents design before they code.**
+
+Phasegate adds project-local hooks, validators, and agent skills that keep generated code aligned with design intent, layer boundaries, and test discipline across Claude Code, Codex, Cursor, Copilot, and other AI coding agents.
 
-Enforces structural integrity between design intent and code, regardless of which AI agent you use.
+[日本語版](README.ja.md) | [Developer Guide](DEVELOPMENT.md)
 
 ---
 
-## Why Phasegate?
+## Phasegate in 30 Seconds
 
-AI coding agents are fast but unconstrained. They skip design steps, violate layer boundaries, and produce code that drifts from intent. Phasegate solves this with a portable, agent-independent defense layer that makes it **physically impossible** to implement without design, commit without validation, or merge without traceability.
+1. **When an AI agent tries to write implementation code without design docs, Phasegate blocks the write** through agent hooks or git hooks.
+2. **Before commit and CI, validators check layer boundaries, metadata, test quality, security, performance, and traceability.**
+3. **Every failure is returned in an agent-readable format** with the reason, missing artifacts, references, and the next skill or command to run.
 
-Works with **Claude Code, Codex, Cursor, Copilot**, or any other AI agent.
+Run `npx phasegate init` once and the project gets the guardrails, skills, and configuration needed to make that flow repeatable.
 
 ---
 
-## Features
+## Why Phasegate?
+
+AI coding agents are fast, but they do not naturally protect your architecture. They skip design steps, cross layer boundaries, weaken type systems with `any`, and generate tests that mirror implementation instead of proving behavior. Human review cannot reliably catch that at AI speed.
 
-| Feature | Description |
+Phasegate turns those expectations into enforcement. If the design is missing, the agent is told what to create first. If a change violates the architecture, commit or CI fails. If a design has not been reflected into canonical product docs, implementation is blocked until the trace exists.
+
+### Where it fits
+
+| Good fit | Poor fit |
 |---|---|
-| **5-Layer Defense Model** | L0 through L4 validators from editor time to scheduled audits |
-| **28 AIDLC Skills** | Full coverage from product architecture to story implementation |
-| **Phase Dependency Model** | Blocks implementation when required design documents are missing |
-| **Quick Mode** | Lightweight gate for bugfixes, docs, tests, and config changes |
-| **Claude Code Hooks** | Native PreToolUse / PostToolUse / Stop hook integration |
-| **Codex CLI Hooks** | `PreToolUse(Bash)` / `PostToolUse(Bash)` / `Stop` hook integration (native `apply_patch` falls back to pre-commit) |
-| **HarnessError Format** | Every error includes ADR references and fix examples for AI self-correction |
-| **Configurable Phase Gates** | Define custom gates with `gates[]` in config. Default uses AIDLC phase dependencies |
-| **Protected File Control** | Configure which files are protected from AI writes via `protectedFiles.exclude` |
-| **Bash Write Detection** | Detects and blocks shell-based file writes (`sed -i`, `tee`, `cp`, `mv`, redirects) |
-| **Presets** | minimal, standard, and strict -- choose your quality level |
+| Medium to large projects where AI agents implement multiple features | Throwaway scripts with no lasting structure |
+| Clean Architecture, DDD, Hexagonal, or layered systems | Codebases where architecture is intentionally ad hoc |
+| Teams that want TDD and test conventions enforced automatically | Projects that do not write automated tests |
+| Products that need design-code drift detection over time | Projects where code is the only source of truth |
+
+---
+
+## What It Looks Like
+
+When an agent tries to write `src/order/order-service.ts` before the `order` unit has design docs, Phasegate stops it:
+
+```text
+Phase gate violation: src/order/order-service.ts
+Scope: Level 3 (implementation), Unit: order
+Blocked because:
+  - docs/product/construction/order/domain_model.md is missing
+  - docs/product/construction/order/logical_design.md is missing
+Next action: run the /story-implementor skill and start from design.
+Example: /story-implementor --unit order
+```
+
+The point is not just to fail the edit. The error gives the AI agent enough structure to recover: create the missing design, reflect it into product docs, then implement with tests.
 
 ---
 
 ## Quick Start
 
-### 1. Install
+### Requirements
+
+Node.js >= 18, npm >= 9, TypeScript 5.x
+
+### 3 steps
 
 ```bash
+# 1. Install
 npm install --save-dev phasegate
+
+# 2. Initialize the project
+npx phasegate init --name my-project --with-husky
+
+# 3. Start your AI agent and begin with product design
+claude
+> /product-architect
 ```
 
-### 2. Initialize
+`init` creates:
+
+- `phasegate.config.json` as the quality settings source of truth
+- `skills/` with 28 AIDLC skills
+- `.claude/skills` and/or `.codex/skills` links for agent use
+- `.claude/settings.json` and/or `.codex/hooks.json` hook configuration
+- `docs/principles/*.md` and `docs/folder_management_rules.md`
+- `.husky/pre-commit` and `.husky/commit-msg` when `--with-husky` is passed
+
+`init` intentionally does **not** create `docs/inception/` work item directories or `docs/product/` design documents. Those are produced later by skills such as `/product-architect`, `/domain-designer`, and `/logical-designer`. That is the core contract: no design, no code.
+
+### Codex CLI
 
 ```bash
-npx phasegate init --name my-project
+npx phasegate init --name my-project --agent codex --with-husky
+codex features enable codex_hooks
 ```
 
-This deploys 28 skills to `skills/`, creates agent-specific links such as `.claude/skills` or `.codex/skills`, installs design principles docs (`docs/principles/*.md`, `docs/folder_management_rules.md`), and generates `phasegate.config.json`.
+Use `--agent both` for projects that use Claude Code and Codex together. Codex native `apply_patch` currently cannot be intercepted before the edit, so those violations are caught at pre-commit; Bash-based writes are blocked before execution.
 
-Optional: add `--with-husky` to also install a `.husky/pre-commit` hook that runs L2 validators.
+### Update
 
-### 3. Start the AIDLC
+```bash
+npm update phasegate
+npx phasegate update-skills
+```
+
+---
 
-Launch your AI agent and run the `/product-architect` skill to begin.
+## Core Capabilities
+
+| Capability | What it does |
+|---|---|
+| **Phase gates** | Blocks implementation writes until required design documents exist and have been reflected into product docs |
+| **5-layer validation** | Runs checks from agent runtime and editor time through pre-commit, CI, and scheduled audits |
+| **28 AIDLC skills** | Guides AI agents through product architecture, story writing, domain design, test design, and TDD implementation |
+| **Quick Mode** | Keeps bugfixes, docs, test-only changes, and config changes lightweight while preserving traceability |
+| **Claude Code / Codex hooks** | Runs checks around Write/Edit/Bash operations and session boundaries |
+| **Agent-readable HarnessError output** | Gives AI agents the reason, missing artifacts, references, and examples needed to self-correct |
+| **Retrofit baseline** | Lets existing repositories adopt Phasegate gradually by grandfathering unchanged files |
+| **Configurable gates** | Supports AIDLC defaults or custom gates such as schema-first API development |
 
 ---
 
@@ -100,60 +163,130 @@ Launch your AI agent and run the `/product-architect` skill to begin.
 
 ## 28 Skills
 
-Skills cover the full **AIDLC (AI-Driven Development Life Cycle)**, enforcing phase dependencies so that implementation cannot begin without design.
+Skills cover the full **AIDLC (AI-Driven Development Life Cycle)**: product definition, design, test design, and TDD implementation. Each skill consumes the artifacts from the previous phase.
 
-### Foundation (4)
+**First step**: run `/product-architect` inside Claude Code or Codex.
 
-| Skill | Purpose |
+| Group | Skills |
 |---|---|
-| `/product-architect` | Define product vision, domains, architecture, and constraints |
-| `/story-writer` | Create Who/What/Why user stories with acceptance criteria |
-| `/story-mapper` | Prioritize stories and define MVP scope |
-| `/unit-designer` | Group stories into independently buildable Units |
+| **Foundation (4)** | `/product-architect` `/story-writer` `/story-mapper` `/unit-designer` |
+| **Design (5)** | `/domain-designer` `/logical-designer` `/mock-designer` `/uiux-designer` `/environment-designer` |
+| **Test Engineering (7)** | `/unit-test-designer` `/it-test-designer` `/scenario-test-designer` `/unit-test-logic-designer` `/it-test-logic-designer` `/scenario-test-logic-designer` `/test-coverage-checker` |
+| **Implementation (4)** | `/story-implementor` `/quick-implementor` `/implementation-planner` `/implementation-readiness-checker` |
+| **Verification (8)** | `/consistency-checker` `/cascade-updater` `/codex-delegator` `/codebase-mapper` `/doc-freshness-checker` `/pointer-validator` `/engineering-perspective` `/skill-creator` |
 
-### Design (5)
+Details, prerequisites, and generated artifacts: [Skills Overview](docs/guide/skills-overview.md)
 
-| Skill | Purpose |
-|---|---|
-| `/domain-designer` | DDD tactical design -- aggregates, entities, value objects, events |
-| `/logical-designer` | Hexagonal architecture design (ports and adapters) |
-| `/mock-designer` | UI mockup design for early validation |
-| `/uiux-designer` | Final UI/UX definition from test cases and logical design |
-| `/environment-designer` | Local dev environment and infrastructure design |
+---
 
-### Test Engineering (7)
+## Document Lifecycle
 
-| Skill | Purpose |
-|---|---|
-| `/unit-test-designer` | Unit test case design from domain models |
-| `/it-test-designer` | Integration test case design from logical design |
-| `/scenario-test-designer` | E2E scenario test case design |
-| `/unit-test-logic-designer` | Vitest implementation logic with pseudocode |
-| `/it-test-logic-designer` | Integration test Vitest implementation logic |
-| `/scenario-test-logic-designer` | Playwright E2E implementation logic |
-| `/test-coverage-checker` | Coverage verification and Nyquist validation |
+Phasegate enforces a single-direction data flow: **inception → product → src**. Each step has a designated location and a corresponding PhaseGate behavior.
 
-### Implementation (4)
+### Three-tier model
 
-| Skill | Purpose |
-|---|---|
-| `/story-implementor` | TDD implementation (Red-Green-Refactor) with atomic commits |
-| `/quick-implementor` | Lightweight implementation for bugfixes, docs, tests, config |
-| `/implementation-planner` | Implementation plan from Unit specs and domain models |
-| `/implementation-readiness-checker` | Pre-implementation readiness verification |
+```
+docs/inception/{unit}/{WI-XXX}/    ← transient planning/design (per WI, fluid)
+        ↓ reflection (with @work-item-id, accumulated update)
+docs/product/construction/{unit}/   ← canonical design (per Unit, persistent)
+        ↕ phase gate
+scripts/harness/{unit}/(domain|application|infrastructure|presentation)/*.ts
+```
 
-### Verification (8)
+### Work Item (WI) layout
 
-| Skill | Purpose |
+WIs are placed in one of three buckets based on scope:
+
+| Path | Use |
 |---|---|
-| `/consistency-checker` | Cross-layer consistency check across design documents |
-| `/cascade-updater` | Propagate lower-phase discoveries to upstream design docs |
-| `/codex-delegator` | Delegate tasks to Codex CLI with quality oversight |
-| `/codebase-mapper` | Generate structure map from `@unit`/`@layer` annotations |
-| `/doc-freshness-checker` | Design document staleness detection (L4 extension) |
-| `/pointer-validator` | Validate file path references in design documents |
-| `/engineering-perspective` | Multi-perspective design review (Beck, Fowler, Martin, Evans) |
-| `/skill-creator` | Create or update agent skills |
+| `docs/inception/_shared/` | Cross-cutting plans/strategy/research not tied to a WI |
+| `docs/inception/_cross/{WI-XXX}/` | Cross-cutting WI affecting multiple Units |
+| `docs/inception/{unit}/{WI-XXX}/` | WI owned by a single Unit |
+
+> **Removed in v0.104.0**: `docs/inception/issues/`, `docs/inception/{unit}/issues/`, `docs/inception/{unit}/{US-XXX}/`. Existing assets are migrated via `npx phasegate migrate work-items --apply`. Legacy IDs are retained via `legacy_id` for grep compatibility.
+
+### WI frontmatter (required)
+
+Each WI's `description.md` must start with:
+
+```yaml
+---
+id: WI-042
+type: story | issue | fix | refactor | chore   # see below
+severity: trivial | normal | high
+status: drafted | reflected | implemented | tested   # auto-updated by PhaseGate
+affects: [unit-a, unit-b]                            # cross-unit only
+legacy_id: ISSUE-XXX | US-XXX | H{NN}-{NN}          # optional
+---
+```
+
+L2 metadata validator verifies the frontmatter shape.
+
+### Required artifacts by `type`
+
+| `type` | inception artifacts | product reflection | Use |
+|---|---|---|---|
+| `story` | description + logical_design + domain_model + test designs | All categories accumulated | New feature |
+| `issue` | description + logical_design + domain_model + relevant test designs | Relevant categories | Bug / spec mismatch |
+| `refactor` | description + logical_design | logical_design update | Refactor |
+| `fix` | description + PR link | `@work-item-id` annotation in relevant category | Typo / dep update |
+| `chore` | description.md (1 line) + PR link | None | Chore |
+
+`fix` / `chore` are lightweight paths — fixes too small for a formal story still get audit trail.
+
+### State machine
+
+```
+DRAFTED  (inception artifacts present per `type`)
+  ↓ Phase 0/2 reflection
+REFLECTED  (product carries @work-item-id WI-XXX)
+  ↓ Phase 3 implementation
+IMPLEMENTED  (src exists / lint+type+test green)
+  ↓ Phase 4 test
+TESTED  (test files annotated with @work-item-id, all green)
+```
+
+`type: chore` ends at DRAFTED. `type: fix` shortcuts via DRAFTED → REFLECTED → IMPLEMENTED. PhaseGate auto-updates `status`.
+
+Full spec: [`docs/folder_management_rules.md`](docs/folder_management_rules.md)
+
+---
+
+## Metadata Conventions
+
+Each source file declares its `@unit` / `@layer`. Tests add `@story` or `@work-item-id` for traceability.
+
+```typescript
+// @unit config-foundation
+// @layer domain
+// @work-item-id WI-042       ← optional (boosts traceability)
+// @story US-001              ← test files only (legacy)
+
+export class ConfigSchema { ... }
+```
+
+| Tag | Value | Required |
+|---|---|---|
+| `@unit` | Unit name from `/unit-designer` (e.g., `config-foundation`) | **Yes** (L1-001) |
+| `@layer` | Layer name from `architecture.preset` | **Yes** (L1-002) |
+| `@work-item-id` | WI driving this file change (e.g., `WI-042`) | Optional |
+| `@story` | US/WI being verified by tests (legacy) | Recommended for tests |
+
+In product docs, declare reflection per section using HTML-comment annotations:
+
+```markdown
+## Port Definitions
+
+<!-- @work-item-id WI-042 -->
+### OrderRepository Port
+- findById(id: OrderId): Promise<Order>
+
+<!-- @work-item-id WI-042, WI-051 -->
+### PaymentGateway Port
+- charge(amount: Money): Promise<Receipt>
+```
+
+L2-STORY-REFLECTION uses these annotations to verify inception design has been cascaded into product. Legacy `@story-id US-XXX` / `@story-id H##-##` / `@issue-id ISSUE-XXX` are still resolved via WI `legacy_id` — no bulk replacement needed for existing docs.
 
 ---
 
@@ -376,9 +509,9 @@ Additional resources:
 
 ---
 
-## Roadmap (Planned but not yet implemented)
+## Known Limits and Roadmap
 
-The following are documented behaviors that are partially implemented or rely on user-side wiring. Each is tracked as a Work Item and will land in a future minor release. Inception docs live under `docs/inception/_cross/WI-XXX/description.md`.
+The main path is ready for project use, but a few documented behaviors still require user-side wiring or are tracked for a future minor release. Each item has a Work Item under `docs/inception/_cross/WI-XXX/description.md`.
 
 | Work Item | Title | Why it matters |
 |---|---|---|
@@ -387,7 +520,7 @@ The following are documented behaviors that are partially implemented or rely on
 | **[WI-033](docs/inception/_cross/WI-033/description.md)** | Promote `doc-freshness` / `pointer-validation` to L4 validators | Both capabilities exist as `p2:check-freshness` / `p2:validate-pointers` CLI commands but are not registered as L4 validators, so `validate --layer L4` skips them. WI-033 plumbs them through `validator-system` so they run via the standard L4 path and presets. |
 | **[WI-034](docs/inception/_cross/WI-034/description.md)** | Retire legacy L0 validators (`L0-001` / `L0-002`) | The `fuse-hook-config` / `fuse-mount-status` validator IDs are leftovers from an earlier FUSE-based design. They are disabled by default and have no actual implementation behind them. WI-034 removes them and lets the agent-integration runtime hooks be the sole L0 surface. |
 
-`requirement-test-matrix.json` auto-generation for L3 Nyquist Validation is also a known gap; see the L3 section above.
+`requirement-test-matrix.json` auto-generation for L3 Nyquist Validation is not automated yet; see the L3 guide for the current manual setup.
 
 ---
 

package/docs/folder_management_rules.md

@@ -1,251 +1,316 @@
 # docs ディレクトリ管理ガイド
 
-本ドキュメントは`docs/`配下のドキュメント管理方針を定義します。
+本ドキュメントは `docs/` 配下のドキュメント管理方針を定義します。Phasegate が「設計なしの実装を物理的に拒否する」ための **正本となる構造とアノテーション規約**を記述しています。
+
+> WI-026 (v0.100.0..v0.104.0) で work item taxonomy が `WI-XXX` に統一されました。`docs/inception/issues/` および `docs/inception/{unit}/issues/` は **廃止済み**です。本ドキュメントは v0.105.0 以降の最新仕様で記述されています。
 
 ---
 
-## ディレクトリ構造
+## 1. ディレクトリ構造（全体像）
 
 ```
 docs/
-├── ADR/                    # Architecture Decision Records
-├── basic_input/            # 入力サンプル・テンプレート
-├── principles/             # 開発原則・ルール
-├── inception/              # 計画ドキュメント + 作業単位（US・issue）の設計
-└── product/                # 共有設計ドキュメント（確定版）
+├── ADR/                       # Architecture Decision Records
+├── principles/                # 開発原則・テスト規約（immutable）
+├── guide/                     # 公開ユーザーガイド
+├── inception/                 # 計画・work item の一時設計（流動）
+│   ├── _shared/               # 非 WI の横断計画（戦略・タスクリスト等）
+│   ├── _cross/                # cross-cutting WI（複数 Unit に影響）
+│   │   └── {WI-XXX}/
+│   └── {unit}/                # Unit 所有の WI と Unit 横断計画
+│       └── {WI-XXX}/
+└── product/                   # 確定した設計成果物（累積更新・正本）
+    ├── product_overview.md
+    ├── user_stories.md
+    ├── user_story_mapping.md
+    ├── units/{unit}.md
+    └── construction/{unit}/
+        ├── domain_model.md
+        ├── logical_design.md
+        ├── uiux_design.md
+        ├── unit_test_design.md
+        ├── it_test_design.md
+        ├── unit_test_logic.md
+        ├── it_test_logic.md
+        └── coverage_report.md
 ```
 
----
-
-## 各ディレクトリの役割
+### 役割の対応
 
-### ADR/
-アーキテクチャ決定記録。技術選定や設計方針の決定理由を記録する。
+| ディレクトリ | 役割 | 寿命 |
+|---|---|---|
+| `ADR/` | アーキテクチャ意思決定の永続記録 | 永続（status で管理） |
+| `principles/` | 全プロジェクトで遵守すべき不変ルール | 永続（変更には ADR 必須） |
+| `guide/` | 利用者向け公開ドキュメント | 永続（仕様変更で追従） |
+| `inception/` | 計画・調査・work item の一時設計 | 流動（実装後はアーカイブ） |
+| `product/` | Unit 単位の確定設計（累積更新） | 永続（生きたドキュメント） |
 
-### basic_input/
-入力データのサンプルやテンプレートを格納する。
+---
 
-### principles/
-開発原則、テストルール、アーキテクチャ哲学など、プロジェクト全体で遵守すべきルールを定義する。
+## 2. 三階層モデル: inception → product → src
 
-### inception/
-**計画ドキュメント**と**作業単位（US・issue）の設計**を格納する。inception 配下のドキュメントは一時的な作業用であり、設計成果物は `product/` に反映される。
+Phasegate の中核は **「inception で設計を起こし、product に確定させ、src（実装）に展開する」** という単方向のデータフローです。逆流はフェーズゲートでブロックされます。
 
 ```
-inception/
-├── _shared/                # 横断的な計画（複数Unitにまたがるもの）
-├── _operation/             # 運用・デプロイ関連の計画
-├── issues/                 # 横断的なissue（複数Unitにまたがるもの）
-│   └── {ISSUE-XXX}/
-│       ├── issue_description.md  # 問題の記述
-│       ├── logical_design.md     # 論理設計
-│       └── ...
-├── {Unit名}/               # Unit毎の階層
-│   ├── *_plan.md           # Unit全体の計画
-│   ├── {US-XXX}/           # ストーリー単位の計画・設計
-│   │   ├── *_plan.md       # 実装計画
-│   │   ├── uiux_design.md  # UI/UX設計
-│   │   └── ...             # その他ストーリー固有のドキュメント
-│   └── issues/             # Unit固有のissue（バグ・不整合）
-│       └── {ISSUE-XXX}/
-│           ├── issue_description.md  # 問題の記述
-│           ├── logical_design.md     # 論理設計
-│           └── tdd_implementation_plan.md
+docs/inception/{unit}/{WI-XXX}/   ← 一時的な計画・設計（WI ごと）
+        ↓ 設計成果物の反映（@work-item-id 付きで累積更新）
+docs/product/construction/{unit}/  ← 確定設計（Unit ごとの正本）
+        ↕ フェーズゲート
+scripts/harness/{unit}/(domain|application|infrastructure|presentation)/*.ts
 ```
 
-### product/
-**確定した設計ドキュメント**を格納する。作業単位（US-XXX / ISSUE-XXX）のドキュメントは含まない。
+### product docs ハブモデル（設計思想）
 
-> **設計思想（product docs ハブモデル）**:
->
-> `product/` はUnit単位で確定済みの仕様を集約する **ハブ** である。
->
-> ```
-> inception/{unit}/{作業単位}/   一時設計（US・issue ごと）
->         ↓ 設計成果物の反映（累積更新）
-> product/construction/{unit}/   正式設計（常に最新、Unitの真実のソース）
->         ↕ フェーズゲート
-> scripts/harness/{unit}/*.ts    実装ファイル
-> ```
+- **inception → product**: WI の設計成果が確定したら、対応する `product/construction/{unit}/{category}.md` に **累積更新**する（新規ファイルは作らない）
+- **product → src**: ソースの phase-gate は **product docs の存在**で判定する（inception の存在では判定しない）
+- **ソースと WI を直接紐付けない**: 一つのファイルに紐づく WI が増えると依存が複雑化するため、product docs を媒介させて間接的に紐付ける
+
+---
+
+## 3. inception/ — work item と計画の置き場
+
+### 3.1 物理レイアウト（v0.105.0 以降）
+
+| 配置先 | 用途 | 例 |
+|---|---|---|
+| `inception/_shared/` | 非 WI の横断計画・戦略・調査メモ | `oss_release_tasklist.md`, `wi-026-remediation-plan.md` |
+| `inception/_cross/{WI-XXX}/` | 複数 Unit に影響する cross-cutting WI | `_cross/WI-026/`, `_cross/WI-031/` |
+| `inception/{unit}/{WI-XXX}/` | 単一 Unit が所有する WI | `validator-system/WI-074/` |
+
+> **廃止された配置**（v0.104.0 で物理削除）:
+> - `docs/inception/issues/{ISSUE-XXX}/`
+> - `docs/inception/{unit}/issues/{ISSUE-XXX}/`
+> - `docs/inception/{unit}/{US-XXX}/`（旧 US 形式）
 >
-> - **inception → product**: US・issue の設計成果が確定したら product docs を累積更新する
-> - **product → source**: ソースファイルのフェーズゲートは product docs（Unit単位）の存在で判定する
-> - **ソースファイルと US/issue は直接紐付けない**: PJ のライフサイクルが進むほどにバグ修正や US 追加で一つのソースファイルに紐づくドキュメント数が増大し、依存関係が複雑になるため。product docs が常に最新に保たれることで、inception の一時ドキュメントと実装が間接的に紐づく
-> - **US/issue 単位で正として管理しない**: 整合性維持のコストが非常に大きくなるため、作業単位の設計は inception にアーカイブ的に保持し、確定した仕様のみを product に集約する
+> 既存資産は `migrate work-items --apply` で `WI-XXX` レイアウトに移行済み。`legacy_id` で旧 ID の grep 互換性は維持されています。
 
+### 3.2 WI frontmatter（必須）
+
+各 WI の `description.md` 先頭に以下の YAML frontmatter を必須とします（L2 metadata validator が検証）:
+
+```yaml
+---
+id: WI-XXX                                              # 必須: WI の一意 ID
+type: story | issue | fix | refactor | chore           # 必須: 後述
+severity: trivial | normal | high                       # 必須
+status: drafted | reflected | implemented | tested      # PhaseGate が自動更新
+affects: [unit-a, unit-b]                               # cross-unit のみ列挙。省略時は所有 Unit のみ
+legacy_id: ISSUE-XXX | US-XXX | H{NN}-{NN}             # 任意: 移行用エイリアス
+source: github#123 | slack | internal                   # 任意: 外部報告源
+---
 ```
-product/
-├── product_overview.md         # プロダクト概要
-├── user_stories.md             # ユーザーストーリー一覧
-├── user_story_mapping.md       # ストーリーマッピング
-├── construction/               # Unit毎の設計（確定版・累積更新）
-│   └── {Unit名}/
-│       ├── domain_model.md     # ドメインモデル
-│       ├── logical_design.md   # 論理設計
-│       ├── uiux_design.md      # UI/UX設計（Unit全体で1ファイル）
-│       ├── unit_test_design.md  # ユニットテストケース設計
-│       ├── it_test_design.md    # ITテストケース設計
-│       ├── unit_test_logic.md   # ユニットテストロジック設計
-│       ├── it_test_logic.md     # ITテストロジック設計
-│       └── coverage_report.md   # テストカバレッジレポート
-└── units/                      # Unit設計ドキュメント
-    ├── {unit_name}_unit.md     # Unit定義
-    └── integration_contract.md # 統合契約
-```
 
-> **`construction/{Unit名}/` のドキュメントは累積更新される「生きたドキュメント」です。**
-> ストーリー実装のたびに、新しい仕様を既存ファイルに追記・更新します。
+### 3.3 type による要求成果物の段階化
+
+WI の重さに応じて、生成必須の成果物が変わります。
+
+| `type` | inception 必須成果物 | product 反映 | 用途 |
+|---|---|---|---|
+| `story` | description + logical_design + domain_model + test 設計（+ uiux） | 全カテゴリ累積更新 | 新機能 |
+| `issue` | description + logical_design + domain_model + 関係 test 設計 | 関係カテゴリ累積更新 | バグ・仕様不整合 |
+| `refactor` | description + logical_design（構造変更の意図） | logical_design 更新 | リファクタ |
+| `fix` | description.md + PR link | 関係カテゴリに `@work-item-id` 追記 | typo・依存更新等 |
+| `chore` | description.md 1 行 + PR link | 不要 | 雑用 |
+
+`fix` / `chore` は軽量パスとして提供されています。formal な US で起票するには重すぎる修正もここで証跡が残せます。
+
+### 3.4 _shared/ の使い方
+
+`inception/_shared/` は **WI に紐付かない計画・調査文書**を置きます。例:
+
+- 戦略文書（`oss_public_release_strategy.md`）
+- 横断 remediation 計画（`wi-026-remediation-plan.md`）
+- TDD 実装計画の集約（`configurable_phase_gate_b4_tdd_plan.md`）
+
+`_shared/` 配下の文書は WI ではないため `description.md` の frontmatter は不要ですが、L2 metadata validator が staged 時に `@story-id` または `@work-item-id` を要求します。新規作成時は `traceability.initial_creation: true` か該当する `@story-id`（catalog 登録済み H##-##）を付与してください。
 
 ---
 
-## 重要なルール
+## 4. product/ — 確定設計の正本
 
-### 1. productには作業単位（US・issue）の設計を入れない
+### 4.1 構造
 
 ```
-# NG: product配下にUS-XXX/ISSUE-XXXディレクトリを作成
-product/construction/withholding_tax/US-217/
-product/construction/withholding_tax/issues/ISSUE-001/
-
-# OK: inception配下に作成
-inception/withholding_tax/US-217/
-inception/withholding_tax/issues/ISSUE-001/
+product/
+├── product_overview.md         # プロダクト全体像
+├── user_stories.md             # US / WI catalog（H## ID と WI のマッピングを含む）
+├── user_story_mapping.md       # MVP スコープ・優先順位
+├── units/
+│   ├── {unit}.md               # Unit 定義
+│   └── integration_contract.md # Unit 間統合契約
+└── construction/{unit}/
+    ├── domain_model.md         # ドメインモデル
+    ├── logical_design.md       # Hexagonal 論理設計
+    ├── uiux_design.md          # UI/UX（Unit 全体で 1 ファイル）
+    ├── unit_test_design.md     # ユニットテストケース設計
+    ├── it_test_design.md       # IT テストケース設計
+    ├── unit_test_logic.md      # ユニットテストロジック設計
+    ├── it_test_logic.md        # IT テストロジック設計
+    └── coverage_report.md      # カバレッジレポート
 ```
 
-### 2. 仕様変更時は既存のproductドキュメントを更新する
+### 4.2 重要なルール
 
-US 実装や issue 修正で仕様が確定したら、`product/`配下の既存ドキュメント（domain_model.md等）を累積更新する。新規ファイルを作成するのではなく、既存ファイルに変更を追記する。product docs は常に最新の状態を維持する「生きたドキュメント」である。
+1. **work item ディレクトリを置かない**: `product/construction/{unit}/WI-XXX/` のような階層は作らない（NG）
+2. **累積更新する**: 新しい WI の設計成果が確定したら **既存の `{category}.md` を編集**する（新規ファイル作成は禁止）
+3. **`@work-item-id` で反映を宣言**: product 文書内で「この章は WI-XXX に基づく」と機械的に判定するため、該当章の冒頭に `@work-item-id WI-XXX` を記載する
 
-### 3. ストーリー・issue単位の計画・設計は必ずinception配下に作成する
+### 4.3 `@work-item-id` の書き方
 
+```markdown
+<!-- product/construction/order/logical_design.md -->
+
+## ポート定義
+
+<!-- @work-item-id WI-042 -->
+### OrderRepository Port
+- findById(id: OrderId): Promise<Order>
+
+<!-- @work-item-id WI-042, WI-051 -->
+### PaymentGateway Port
+- charge(amount: Money): Promise<Receipt>
 ```
-# 新しいストーリーUS-999の計画を作成する場合
-inception/{該当Unit}/US-999/
-├── logical_design_plan.md
-├── scenario_test_plan.md
-├── scenario_test_design.md
-├── scenario_test_logic.md
-├── uiux_design_plan.md
-└── tdd_implementation_plan.md
-
-# Unit固有のissue（バグ・不整合）を起票する場合
-inception/{該当Unit}/issues/ISSUE-999/
-├── issue_description.md
-├── logical_design.md
-└── tdd_implementation_plan.md
-
-# 横断的なissue（複数Unitにまたがる）を起票する場合
-inception/issues/ISSUE-999/
-├── issue_description.md
-└── logical_design.md
+
+カンマ区切りで複数 WI を 1 つのアノテーションにまとめられます。
+
+> **legacy 互換**: 既存 product 文書の `@story-id US-XXX` / `@issue-id ISSUE-XXX` / `@story-id H##-##` は WI の `legacy_id` 経由で読み替えられます。一括置換は **しません**（履歴の対応関係を破壊しないため）。新規記述は `@work-item-id WI-XXX` を使ってください。
+
+---
+
+## 5. ソースコードのアノテーション規約
+
+`scripts/harness/` 配下のソースファイル先頭に以下を記載します。
+
+```typescript
+// @unit config-foundation
+// @layer domain
+// @work-item-id WI-042       ← 任意（traceability に貢献）
+// @story US-001              ← テストファイルのみ（legacy 互換）
+
+export class ConfigSchema { ... }
 ```
 
+| タグ | 意味 | 必須性 |
+|---|---|---|
+| `@unit` | このファイルが属する Unit 名 | **必須**（L1-001 が検証） |
+| `@layer` | 層名（preset で定義された値） | **必須**（L1-002 が検証） |
+| `@work-item-id` | このファイル変更を駆動した WI | 任意（traceability で活用） |
+| `@story` | テストが検証する US / WI（legacy 互換） | テストでは推奨 |
+
+`@layer` の有効値は `architecture.preset` で決まります（clean / onion / hexagonal / layered / strict-ddd / flat / custom）。
+
 ---
 
-## ドキュメント作成フロー
+## 6. ドキュメント作成フロー（AIDLC 準拠）
 
-AIDLCプロセスは **US（新機能）** と **issue（バグ・不整合）** の2つの起点を持つ。いずれも inception で計画を立て、product docs を更新し、実装に反映する流れは共通である。
+WI は以下の 5 段階で進行します。各段階で配置先と PhaseGate の挙動が決まっています。
 
-### US と issue の違い
+### Phase 0 — Product / 横断仕様（_cross WI のみ）
 
-| 起点 | フロー | inception 配置先 |
-|------|--------|-----------------|
-| **US（新機能）** | Phase 1 → Phase 2 → Phase 3 の全フローを上位から順に実行 | `inception/{unit}/{US-XXX}/` |
-| **issue（バグ・不整合）** | 原因フェーズを特定し、そのフェーズから下位に向けてドキュメント・実装をアップデート | `inception/{unit}/issues/{ISSUE-XXX}/` |
+**対象**: `docs/product/product_overview.md` / `user_stories.md` / `user_story_mapping.md` / `units/*.md`
 
-#### issue の処理フロー
+`_cross/{WI-XXX}/` かつ `type: story | issue` が戦略・スコープ・Unit 境界に影響する場合、上記いずれかに `@work-item-id WI-XXX` の反映が必要。未反映なら `affects` 全 Unit への Phase 2/3 書き込みをブロック。
 
-1. **issue 起票**: `inception/{unit}/issues/{ISSUE-XXX}/issue_description.md` に問題の記述・原因分析を記載
-2. **原因フェーズの特定**: バグや仕様の認識違いがどのフェーズに起因するかを判定
-   - ドメイン設計に起因 → domain_model から下位に向けてリファクタ
-   - 論理設計に起因 → logical_design から下位に向けてリファクタ
-   - テスト設計に起因 → test_design から下位に向けてリファクタ
-   - 実装のみに起因 → 実装の修正のみ
-3. **inception で計画**: 特定したフェーズから下位のフェーズに向けて、inception 配下に計画・設計文書を作成
-4. **product docs 更新**: 設計成果物を `product/construction/{unit}/` の該当ドキュメントに累積更新
-5. **TDD 実装**: テスト設計→実装の順序で修正を適用
+### Phase 1 — Inception（下書き・探索）
 
-> **issue が既存仕様に存在しない追加機能であった場合**: issue ではなく **US を新規作成** し、unit へのマッピングからドメイン設計→TDD 実装まで、下記の Phase 1〜3 の全フローに沿って実施する。
+**対象**: `docs/inception/{unit}/{WI-XXX}/` / `docs/inception/_cross/{WI-XXX}/`
 
----
+- WI directory 作成と `description.md` 編集は自由
+- 設計カテゴリ文書（`logical_design.md` 等）が新規作成・実質更新された時点で「反映義務フラグ」が立つ（`status: drafted`）
+- inception 配下のパスへの書き込みは Phase 1 work であり、**Phase 3 reflection check の対象外**（v0.103.0 で確定）
 
-### US のドキュメント作成フロー
+### Phase 2 — Product Construction（確定設計の累積）
 
-US は3つのフェーズで構成される。各フェーズでドキュメントの配置先が異なる。
+**対象**: `docs/product/construction/{unit}/{category}.md` / `product/*.md`
 
-### Phase 1: プロダクト全体設計（横断的・初回）
+- inception の各カテゴリ文書と同カテゴリの product 文書が `@work-item-id WI-XXX` を含み、かつ実質 diff を伴う
+- `_cross/` WI は `affects` 全 Unit について満たす必要あり
 
-プロダクトの全体像を定義し、ストーリー・Unitの構造を確立する。
+### Phase 3 — Implementation (TDD)
 
-| Step | スキル | 計画（inception） | 成果物（product） |
-|------|--------|-------------------|-------------------|
-| Step 0 | product-architect | `_shared/product_overview_plan.md` | `product_overview.md` |
-| Step 1.1 | story-writer | `_shared/story_writer_plan.md` | `user_stories.md` |
-| Step 1.5 | story-mapper | `_shared/story_mapping_plan.md` | `user_story_mapping.md` |
-| Step 2 | unit-designer | `_shared/unit_design_plan.md` | `units/{unit_name}.md` + `units/integration_contract.md` |
+**対象**: `scripts/harness/{unit}/(domain|application|infrastructure|presentation)/*.ts`
 
-### Phase 2: Unit横断設計（Unit単位）
+- 当該 Unit の open な WI のうち、Phase 2 反映が未完なら実装書き込みをブロック
+- `_cross/` WI の `affects` に含まれる Unit は、当該 WI の Phase 0 / 2 反映が完了するまで実装ブロック
 
-各Unitの設計を確定させる。成果物は`product/construction/{unit}/`に配置される累積更新ドキュメント。
+### Phase 4 — Test
 
-| Step | スキル | 計画（inception/{unit}/） | 成果物（product/construction/{unit}/） |
-|------|--------|--------------------------|----------------------------------------|
-| Step 3 | domain-designer | `domain_model_plan.md` | `domain_model.md` |
-| Step 4 | logical-designer（横断） | `logical_design_plan.md` | `logical_design.md` |
-| Step 5 | scenario-test-designer | → Phase 3で実行 | - |
-| Step 5 | it-test-designer | `it_test_design_plan.md` | `it_test_design.md` |
-| Step 5 | unit-test-designer | `unit_test_design_plan.md` | `unit_test_design.md` |
-| - | test-coverage-checker | `test_coverage_plan.md` | `coverage_report.md` |
-| Step 6 | unit-test-logic-designer | `unit_test_logic_plan.md` | `unit_test_logic.md` |
-| Step 6 | it-test-logic-designer | `it_test_logic_plan.md` | `it_test_logic.md` |
+**対象**: `scripts/harness/__tests__/(unit|integration)/**/*.test.ts`
 
-### Phase 3: ストーリー実装（US単位）/ issue 修正
+- product 側の `unit_test_design.md` / `it_test_design.md` に該当 WI の反映があること
+- テストファイルの `@work-item-id` から traceability-model が WI → test カバレッジを算出
 
-個別ストーリーの設計・テスト・実装。計画・成果物は`inception/{unit}/{US-XXX}/`に配置。
-issue の場合は `inception/{unit}/issues/{ISSUE-XXX}/` に配置し、原因フェーズから下位に向けて同様のドキュメントを作成する。
+---
 
-| Step | スキル | 計画（inception/{unit}/{US-XXX}/） | 成果物配置先 |
-|------|--------|-----------------------------------|-------------|
-| Step 4 | logical-designer（固有） | `logical_design_plan.md` | `logical_design.md`（同ディレクトリ） |
-| Step 5 | scenario-test-designer | `scenario_test_plan.md` | `scenario_test_design.md`（同ディレクトリ） |
-| Step 6 | scenario-test-logic-designer | `scenario_test_logic_plan.md` | `scenario_test_logic.md`（同ディレクトリ） |
-| Step 7 | uiux-designer | `uiux_design_plan.md` | `product/construction/{unit}/uiux_design.md`（※累積更新） |
-| Step 8 | story-implementor | `tdd_implementation_plan.md` | コード（TDD実装） |
-| 実装完了後 | - | - | `product/construction/{unit}/` の各ドキュメントを更新 |
+## 7. State Machine（WI のステータス遷移）
 
-> **uiux_design.mdについて**: 計画はストーリー単位（`inception/{unit}/{US-XXX}/`）に作成するが、
-> 成果物は`product/construction/{unit}/uiux_design.md`にUnit全体で1ファイルとして累積更新する。
-> これはUI/UXの全体一貫性を保つためで、他のproduct/construction配下のドキュメントと同じルールに従う。
+```
+DRAFTED       inception の必要成果物が type に応じて揃っている
+  ↓ (Phase 0 / Phase 2 reflection)
+REFLECTED     affects 全 Unit の product に @work-item-id 反映済み
+  ↓ (Phase 3 implementation)
+IMPLEMENTED   scripts/harness 配下に対応実装が存在し lint/type/test green
+  ↓ (Phase 4 test)
+TESTED        @work-item-id 付きテストが存在し green
+```
 
-### 横断的な計画
+- `type: chore` は DRAFTED で完結（product 反映不要、PR trailer のみ）
+- `type: fix` は DRAFTED → REFLECTED（@work-item-id の product 追記）→ IMPLEMENTED の簡略パス
+- `type: story | issue | refactor` はフル状態遷移
+
+`status` フィールドは PhaseGate が自動更新します（手動で書き換える必要はありません）。
+
+---
 
-複数Unitにまたがる計画は `inception/_shared/` に作成する。
+## 8. WI ID 採番ルール
 
-### 運用関連
+`migrate work-items --apply` および新規 WI 起票時の採番:
 
-デプロイ、IaC、運用手順は `inception/_operation/` に作成する。
+- 既存 WI 番号は予約（重複しない）
+- 空き番号の **若い順**で sequential allocation
+- legacy ID（`ISSUE-XXX` / `US-XXX` / `H{NN}-{NN}`）が存在する場合、frontmatter の `legacy_id` に保持
+
+詳細は [CLI Reference — Work Item Migration](./guide/cli-reference.md#work-item-migration) を参照。
 
 ---
 
-## ファイル命名規則
+## 9. ファイル命名規則
 
-| 種別 | 命名パターン | 例 |
-|-----|------------|---|
-| issue記述 | `issue_description.md` | - |
-| 計画 | `*_plan.md` | `domain_model_plan.md` |
+| 種別 | パターン | 例 |
+|---|---|---|
+| WI 記述 | `description.md` | `_cross/WI-026/description.md` |
+| 計画 | `*_plan.md` | `domain_model_plan.md`（inception のみ） |
 | ドメインモデル | `domain_model.md` | - |
 | 論理設計 | `logical_design.md` | - |
-| UI/UX設計 | `uiux_design.md` | - |
+| UI/UX 設計 | `uiux_design.md` | Unit 全体で 1 ファイル |
 | シナリオテスト設計 | `scenario_test_design.md` | - |
-| ITテスト設計 | `it_test_design.md` | - |
+| IT テスト設計 | `it_test_design.md` | - |
 | ユニットテスト設計 | `unit_test_design.md` | - |
 | テストロジック設計 | `*_test_logic.md` | `unit_test_logic.md` |
 | カバレッジレポート | `coverage_report.md` | - |
-| Unit定義 | `{unit_name}_unit.md` | `withholding_tax_unit.md` |
+| Unit 定義 | `{unit}.md` | `withholding_tax.md` |
 | 統合契約 | `integration_contract.md` | - |
 
 ---
 
+## 10. アンチパターン
+
+| NG | 理由 |
+|---|---|
+| `product/construction/{unit}/WI-XXX/` を作る | product は累積更新の正本。WI ディレクトリは inception のみ |
+| inception/{unit}/issues/ を新規作成する | v0.104.0 で廃止。`{unit}/{WI-XXX}/` を使う |
+| inception/{unit}/{US-XXX}/ を新規作成する | 旧形式。`migrate work-items` で `WI-XXX` に移行 |
+| product 文書に `@story-id US-XXX` を **新規記述**する | 新規は `@work-item-id WI-XXX` を使う（legacy は読み取り互換のみ） |
+| frontmatter の `status` を手動編集する | PhaseGate が自動更新する。手動上書きは状態機械を壊す |
+| `_cross/{WI-XXX}/` の `affects` を省略する | cross-unit WI は必須。省略するとどの Unit の reflection check も発火しない |
+
+---
+
 ## 関連ドキュメント
+
 - [アーキテクチャ哲学](./principles/architecture-philosophy.md)
 - [テストルール](./principles/testing-rules.md)
+- [CLI Reference — Work Item Migration](./guide/cli-reference.md#work-item-migration)
+- [Configuration — storyReflection / WI gate](./guide/configuration.md)
+- [Layer Model](./guide/layer-model.md)
+- WI 仕様の出典: [`docs/inception/_cross/WI-026/description.md`](./inception/_cross/WI-026/description.md)

package/docs/guide/cli-reference.md

@@ -140,6 +140,16 @@ exit code は `0` = 生成成功 / 上書き成功、`2` = 既存ファイルあ
 WI-026 で導入（v0.100.0、`ISSUE-XXX` 系統）、WI-027 で `H{NN}-{NN}` 形式の旧ストーリー
 directory にも拡張（v0.105.0）、WI-027 follow-up で apply の冪等性を確立（v0.107.0）。
 
+> **WI taxonomy の正式仕様**は [`docs/folder_management_rules.md`](../folder_management_rules.md) を参照してください。本セクションは CLI の挙動に焦点を絞ります。
+
+### いつ使うか
+
+- **既存リポジトリ**: `docs/inception/issues/` や `{unit}/{US-XXX}/` のような旧形式を残しているプロジェクトを v0.105.0 以降へ更新する初回マイグレーション
+- **新規開発で旧 ID を持ち込む**: 別リポジトリから `ISSUE-XXX` / `H{NN}-{NN}` directory をコピーした後、`legacy_id` を保ったまま `WI-XXX` に統一したいとき
+- **継続運用での再走査**: 既存 WI と新規 directory の混在状態に対し、未採番のものだけ採番する（既存 WI は idempotent skip）
+
+新規 PJ で最初から `WI-XXX` で起票している場合は不要です。
+
 | Command | Options | Description |
 |---|---|---|
 | `migrate work-items` | `--dry-run` / `--apply` / `--json` | 旧 directory を `WI-XXX` へ採番移行する。`--dry-run` と `--apply` は排他、どちらかが必須。|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.111.0",
+  "version": "0.114.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",

package/scripts/harness/phase2-extensions/infrastructure/adapters/git-log-document-age-adapter.ts

@@ -2,7 +2,7 @@
  * @layer infrastructure
  * @unit phase2-extensions
  */
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import type { DocumentAgePort } from '../../domain/ports/document-age-port.js';
@@ -17,20 +17,26 @@ export class GitLogDocumentAgeAdapter implements DocumentAgePort {
   constructor(
     private readonly projectRoot: string,
     private readonly nowProvider: () => Date = () => new Date(),
+    // WI-035: 配列引数で execFileSync を直接呼ぶことでシェル経由のメタ文字評価を遮断する。
     private readonly gitLogExecutor: (
-      command: string,
+      file: string,
+      args: readonly string[],
       options: { cwd: string; stdio?: readonly ['pipe', 'pipe', 'pipe'] },
-    ) => Buffer = execSync,
+    ) => Buffer = execFileSync,
   ) {}
 
   async getAge(documentPath: string): Promise<DocumentAge> {
     try {
-      const output = this.gitLogExecutor(`git log --format=%ai -1 -- "${documentPath}"`, {
-        cwd: this.projectRoot,
-        // ISSUE-005 P1-3: fresh repo では "fatal: your current branch ... does not have
-        // any commits yet" が 34回 stderr に漏れる。pipe に束ねて静音化する。
-        stdio: ['pipe', 'pipe', 'pipe'] as const,
-      })
+      const output = this.gitLogExecutor(
+        'git',
+        ['log', '--format=%ai', '-1', '--', documentPath],
+        {
+          cwd: this.projectRoot,
+          // ISSUE-005 P1-3: fresh repo では "fatal: your current branch ... does not have
+          // any commits yet" が 34回 stderr に漏れる。pipe に束ねて静音化する。
+          stdio: ['pipe', 'pipe', 'pipe'] as const,
+        },
+      )
         .toString()
         .trim();
 

package/scripts/harness/phase2-extensions/infrastructure/adapters/git-log-initial-creation-age-adapter.ts

@@ -2,14 +2,16 @@
  * @layer infrastructure
  * @unit phase2-extensions
  */
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import type { InitialCreationAgePort } from '../../domain/ports/initial-creation-age-port.js';
 import { InitialCreationAge } from '../../domain/value-objects/initial-creation-age.js';
 
+// WI-035: 配列引数で execFileSync を直接呼ぶことでシェル経由のメタ文字評価を遮断する。
 type GitExecutor = (
-  command: string,
+  file: string,
+  args: readonly string[],
   options: { cwd: string; stdio?: readonly ['pipe', 'pipe', 'pipe'] },
 ) => Buffer;
 
@@ -22,12 +24,12 @@ export class GitLogInitialCreationAgeAdapter implements InitialCreationAgePort {
   constructor(
     private readonly projectRoot: string,
     private readonly nowProvider: () => Date = () => new Date(),
-    private readonly gitExecutor: GitExecutor = execSync,
+    private readonly gitExecutor: GitExecutor = execFileSync,
   ) {}
 
   async getAge(filePath: string): Promise<InitialCreationAge> {
-    const dateOutput = this.runGit(`git log --diff-filter=A --format=%ai -- "${filePath}"`);
-    const countOutput = this.runGit(`git rev-list --count HEAD -- "${filePath}"`);
+    const dateOutput = this.runGit(['log', '--diff-filter=A', '--format=%ai', '--', filePath]);
+    const countOutput = this.runGit(['rev-list', '--count', 'HEAD', '--', filePath]);
 
     if (dateOutput !== null && dateOutput.length > 0) {
       const commitCount = this.parseCount(countOutput);
@@ -42,9 +44,9 @@ export class GitLogInitialCreationAgeAdapter implements InitialCreationAgePort {
     return this.fileMtimeFallback(filePath);
   }
 
-  private runGit(command: string): string | null {
+  private runGit(args: readonly string[]): string | null {
     try {
-      return this.gitExecutor(command, {
+      return this.gitExecutor('git', args, {
         cwd: this.projectRoot,
         // ISSUE-005 P1-3 と同様に、fresh repo の fatal stderr を静音化する。
         stdio: ['pipe', 'pipe', 'pipe'] as const,