phasegate 0.91.0 → 0.108.0

package/docs/guide/cli-reference.md

@@ -134,6 +134,114 @@ exit code は `0` = 生成成功 / 上書き成功、`2` = 既存ファイルあ
 
 ---
 
+## Work Item Migration
+
+`docs/inception/` 配下の work item directory を **統一 `WI-XXX` レイアウト**へ移行する CLI。
+WI-026 で導入（v0.100.0、`ISSUE-XXX` 系統）、WI-027 で `H{NN}-{NN}` 形式の旧ストーリー
+directory にも拡張（v0.105.0）、WI-027 follow-up で apply の冪等性を確立（v0.107.0）。
+
+| Command | Options | Description |
+|---|---|---|
+| `migrate work-items` | `--dry-run` / `--apply` / `--json` | 旧 directory を `WI-XXX` へ採番移行する。`--dry-run` と `--apply` は排他、どちらかが必須。|
+
+### 検出パターン
+
+`docs/inception/` 配下を走査し、以下のいずれかに合致する directory を candidate として列挙する:
+
+| 検出パターン | 配置 | scope | nextId 採番方式 |
+|---|---|---|---|
+| `^ISSUE-\d+$` | `docs/inception/issues/` または `{unit}/issues/` | `cross` / `unit` | embedded number そのまま (`ISSUE-026 → WI-026`) |
+| `^WI-\d+$` | 既に WI レイアウトの directory | `cross` / `unit` | 変更なし（idempotent skip） |
+| `^H\d{2}-\d{2}$` | `{unit}/` 直下 | `unit` のみ | sequential allocator: 既存 WI 番号 + 同一 plan 内 ISSUE-XXX 番号を予約したうえで、空き番号の若い順に `WI-XXX` を割り当て |
+
+skip 対象: `_shared/` / `_operation/` / `_cross/` / `issues/` 配下（`_cross/WI-XXX/` は WI レイアウトのため再走査不要）。
+
+### Sequential Allocator の挙動（H-ID 採番）
+
+```
+input:  entries (混在: WI-XXX / ISSUE-XXX / H{NN}-{NN})
+        existingWorkItemIds = ["WI-001", ..., "WI-027"]   # _cross/ + {unit}/ から列挙
+
+step 1. usedNumbers = parseToInts(existingWorkItemIds)            # {1..27}
+step 2. 同一 plan 内 ISSUE-XXX / WI-XXX の embedded number を usedNumbers に追加
+step 3. H-ID entries を sourcePath 昇順でループ:
+          cursor = 1
+          while usedNumbers.has(cursor): cursor++
+          assign WI-{cursor.padStart(3, "0")} to entry
+          usedNumbers.add(cursor)
+```
+
+不変条件:
+
+- 既存 WI-XXX directory の番号は新規 H-ID 採番で再利用されない。
+- 同一 plan 呼び出し内で `nextId` は重複しない（usedNumbers が共有される）。
+- `ISSUE-XXX → WI-XXX` の embedded mapping は変更しない（後方互換）。
+
+### Frontmatter 注入
+
+`--apply` 時、各 directory の `description.md` に以下の frontmatter を生成する。
+既存 frontmatter があれば **id 一致 + legacy_id 一致** のときだけ byte-for-byte
+保持し、それ以外は planner 生成版で置換する（v0.107.0 で冪等化）。
+
+```yaml
+---
+id: WI-XXX                    # 採番された ID
+type: story | issue           # H-ID 由来は story、ISSUE-XXX 由来は issue
+severity: trivial | normal | high  # 元 description の "深刻度" から抽出（既定: normal）
+status: drafted
+legacy_id: H02-04              # または ISSUE-026
+affects: [unit-a, unit-b]      # cross scope のみ。元 description の "影響Unit" から抽出
+---
+```
+
+`description.md` 不在の directory には `# {legacyId}\n` の stub を生成して frontmatter を prepend する。
+
+### 使用例
+
+```bash
+# 移行候補を表示（実際の rename は行わない）
+npx phasegate migrate work-items --dry-run
+
+# JSON 出力（CI / スクリプト向け）
+npx phasegate migrate work-items --dry-run --json
+
+# 実マイグレーション実行
+npx phasegate migrate work-items --apply
+
+# apply 結果を JSON で取得
+npx phasegate migrate work-items --apply --json
+```
+
+### exit code
+
+| code | 意味 |
+|---|---|
+| `0` | 成功（dry-run 時 conflict なし、apply 時 blocked なし）|
+| `1` | dry-run で conflict candidate あり（target directory が既に存在）/ apply で blocked |
+| `2` | 引数不正（`--dry-run` / `--apply` どちらも未指定、両方指定、`--apply` 未配線等）|
+
+### Legacy ID Grep 互換性
+
+WI-XXX へ移行後も、frontmatter の `legacy_id:` 経由で旧 ID を逆引きできる:
+
+```bash
+# 旧 H-ID から WI directory を逆引き
+grep -rn "^legacy_id: H02-04" docs/inception/
+
+# 旧 ISSUE-XXX から逆引き
+grep -rn "^legacy_id: ISSUE-026" docs/inception/
+
+# Work-Item commit trailer による履歴遡及
+git log --grep='Work-Item: WI-074'
+```
+
+また、ソースコード内の `// @story-id H02-04` などの legacy annotation は、
+`FileSystemStoryReflectionAdapter#readLegacyId` が `_cross/` と `{unit}/` の
+両方の `WI-XXX/description.md` を走査して `legacy_id` を解決するため、
+unit-scoped WI（H-ID 由来）の reflection check でも継続認識される（v0.105.0）。
+
+---
+
 ## Harness API
 
 Commands exposed as npm scripts (`npm run <command>`).

package/docs/guide/codex-integration.md

@@ -7,15 +7,20 @@ Phasegate supports [OpenAI Codex CLI](https://developers.openai.com/codex/cli) t
 ### Quick setup (recommended)
 
 ```bash
-# 1. Initialize with Codex agent support
+# 1. Initialize the project for Codex
 npx phasegate init --name my-project --agent codex --with-husky
 
-# 2. Enable Codex hooks feature flag
+# 2. Enable the Codex CLI feature flag manually
 codex features enable codex_hooks
 ```
 
 For dual-agent projects (Claude + Codex), use `--agent both`.
 
+Responsibility split:
+
+- `phasegate init --agent codex` sets up **project-local artifacts** such as `phasegate.config.json`, `skills/`, `.codex/hooks.json`, and `.codex/skills`
+- `codex features enable codex_hooks` updates the **Codex CLI user environment** and is intentionally left as a manual step
+
 ### Manual setup
 
 Alternatively, set up Codex integration manually:

package/docs/guide/installation.md

@@ -36,7 +36,13 @@ npm install
 npx phasegate init --name <project-name>
 ```
 
-This deploys 28 skills to `.claude/skills/` and generates `phasegate.config.json`.
+This deploys 28 skills to `skills/`, creates the agent-facing skill links (for example `.claude/skills/` or `.codex/skills/`), and generates `phasegate.config.json`.
+
+For Codex, project initialization stops at the project boundary. After `npx phasegate init --agent codex`, enable the Codex CLI feature flag manually:
+
+```bash
+codex features enable codex_hooks
+```
 
 ### 2. Copy design principle documents
 
@@ -69,7 +75,9 @@ npx phasegate update-skills
 
 ```
 node_modules/
-.claude/skills/    # regenerated by npx phasegate init
+skills/            # regenerated by npx phasegate init
+.claude/skills/    # symlink to ../skills when Claude is enabled
+.codex/skills/     # symlink to ../skills when Codex is enabled
 dist/
 reports/
 .harness/

package/docs/guide/preset-selection.md

@@ -0,0 +1,170 @@
+# Architecture Preset Selection Guide
+
+phasegate の `phasegate.config.json` には `architecture.preset` を通じて「そのプロジェクトが採用しているアーキテクチャスタイル」を明示する。L1-003 (`no-layer-violation`) / L1-004 (`enforce-folder-structure`) はこの preset を参照して層名と依存方向を判定する。
+
+preset の選択が正しくないと、本来合法な import が violation として検出される / 本来検出されるべき違反が通過する等の誤判定が発生する。本ガイドは preset 選択の判断基準と実例を示す。
+
+---
+
+## 用語の整理（呼称の混同を避ける）
+
+phasegate には 2 系統の「プリセット」概念があり、役割が異なる:
+
+| 系統 | 概念 | 設定キー | 例 |
+|------|------|---------|----|
+| **防御プリセット** | L3 CI で検査強度を選ぶ | `ci.preset` | `strict` / `lenient` |
+| **アーキプリセット** | L1 の層構造と依存方向を定義 | `architecture.preset` | `clean` / `onion` / `hexagonal` / `layered` / `flat` / `strict-ddd` / `custom` |
+
+本ガイドの対象は **アーキプリセット**。CI 強度の選定は `docs/guide/configuration.md` を参照。
+
+---
+
+## 7 preset の早見表
+
+| preset | 層構成 | 典型的な採用対象 |
+|--------|--------|------------------|
+| `clean` (default) | `domain / application / infrastructure / presentation` | Clean Architecture / AIDLC フルハーネス構成 |
+| `strict-ddd` | `clean` + 循環依存禁止を厳格化 | DDD 重視の新規 PJ |
+| `onion` | `domain / application / interface` | Onion Architecture |
+| `hexagonal` | `core / ports / adapters` | Hexagonal / Ports-and-Adapters |
+| `layered` | `presentation / business / data` | 古典的 3 層レイヤード |
+| `flat` | 層分割なし | 小規模スクリプト・CLI ツール / retrofit 導入初期 |
+| `custom` | `layers` + `allowedDependencies` を明示指定 | どの既成プリセットにも当てはまらない PJ |
+
+各 preset の詳細な層行列は `docs/inception/issues/ISSUE-014/wave1_schema_proposal.md §1.2` を参照。
+
+---
+
+## 選択フロー
+
+```
+1. 既存 PJ か新規 PJ か？
+   ├─ 新規 → Q2 へ
+   └─ 既存 → retrofit-adoption.md を先に参照 / 初期は `flat` でも可
+
+2. DDD / Clean Architecture を明示採用している？
+   ├─ はい → Q3 へ
+   └─ いいえ → Q4 へ
+
+3. 4 層分離（domain / application / infrastructure / presentation）を守っている？
+   ├─ はい → `clean`（循環依存も潰したい場合は `strict-ddd`）
+   └─ いいえ → カスタム Q5 へ
+
+4. フレームワーク構造に寄せている？
+   ├─ Onion (3 層 domain/application/interface) → `onion`
+   ├─ Hexagonal (core/ports/adapters) → `hexagonal`
+   ├─ MVC / 古典 3 層 (presentation/business/data) → `layered`
+   ├─ 小規模スクリプト / 層概念なし → `flat`
+   └─ それ以外 → `custom`
+
+5. `custom` を選ぶ場合、`layers` と `allowedDependencies` を明示指定する（例は後述）。
+```
+
+---
+
+## 設定例
+
+### `clean`（default、省略可）
+
+```json
+{
+  "$schema": "./node_modules/phasegate/schemas/harness-config-v3.schema.json",
+  "architecture": { "preset": "clean" },
+  "l1": { "enabled": true, "rules": {} }
+}
+```
+
+### `onion`
+
+```json
+{
+  "architecture": { "preset": "onion" },
+  "l1": { "enabled": true, "rules": {} }
+}
+```
+
+ソースファイルの `@layer` タグは `domain` / `application` / `interface` のいずれかを使用する。
+
+### `hexagonal`
+
+```json
+{
+  "architecture": { "preset": "hexagonal" },
+  "l1": { "enabled": true, "rules": {} }
+}
+```
+
+`@layer core` / `@layer ports` / `@layer adapters`。
+
+### `flat`（層分割なし）
+
+```json
+{
+  "architecture": { "preset": "flat" },
+  "l1": { "enabled": true, "rules": {} }
+}
+```
+
+`flat` を指定すると L1-001 (`require-unit-comment`) / L1-002 (`require-layer-comment`) / L1-003 / L1-004 が user 明示なき限り auto-disable される。
+
+### `custom`（明示指定）
+
+```json
+{
+  "architecture": {
+    "preset": "custom",
+    "layers": ["model", "service", "controller", "view"],
+    "allowedDependencies": {
+      "model":      ["model"],
+      "service":    ["service", "model"],
+      "controller": ["controller", "service", "model"],
+      "view":       ["view", "controller"]
+    }
+  }
+}
+```
+
+`custom` では `layers` と `allowedDependencies` の両方が必須（片方欠けると config 検証で error）。
+
+---
+
+## override（preset に部分的な上書きを掛ける）
+
+preset を base にして一部の `allowedDependencies` のみ書き換えたい場合:
+
+```json
+{
+  "architecture": {
+    "preset": "clean",
+    "allowedDependencies": {
+      "presentation": ["presentation", "application"]
+    }
+  }
+}
+```
+
+上書きしなかった層（`domain` / `application` / `infrastructure`）は preset 既定のまま。
+
+詳細な semantic validation ルール（C1 自己参照 auto-fill / C2 キー不整合 error / C3 値不整合 error / C4 layer 欠落 auto-fill / C5 循環依存 warn）は `docs/inception/issues/ISSUE-014/wave1_schema_proposal.md §1.3` を参照。
+
+---
+
+## 既存 v2 config からの移行
+
+v0.86.0 より前の `phasegate.config.json` には `architecture` キーが無い。phasegate は後方互換で v2 も読めるが、**v3 への明示アップグレードを推奨**する:
+
+```bash
+npx phasegate migrate --schema v3
+```
+
+このコマンドは `phasegate.config.json` に `architecture: { preset: "clean" }` を追記して v3 化する（既に `architecture` がある場合は no-op）。
+
+---
+
+## 参照
+
+- `docs/inception/issues/ISSUE-014/wave1_schema_proposal.md` — 設計提案とプリセット詳細
+- `docs/inception/issues/ISSUE-014/issue_description.md` — issue 背景
+- `docs/ADR/ADR-015-architecture-preset.md` — アーキ設計決定
+- `docs/guide/retrofit-adoption.md` — 既存 PJ への後付け導入
+- `docs/guide/configuration.md` — 他の config 項目

package/docs/guide/quick-vs-full-mode.md

@@ -130,7 +130,7 @@ Running every change through Full AIDLC is genuinely heavy for one-person projec
 | Core | `docs/product/construction/<unit>/*.md` (contract docs) | Full |
 | Periphery | Internal helpers in `application/` that don't change ports | Quick-first, Full if contract impact emerges |
 | Periphery | `scripts/harness/presentation/` formatting / wording | Quick |
-| Periphery | `docs/guide/*`, `README.md`, `.claude/skills/*` tweaks | Quick |
+| Periphery | `docs/guide/*`, `README.md`, `skills/*` tweaks | Quick |
 | Periphery | Version bumps, `phasegate.config.json` value edits | Quick |
 
 Codify the split in your head (or in a project CLAUDE.md note) — "`domain/**` is core, everything else starts Quick" is a healthy default for a single-maintainer project.
@@ -168,5 +168,5 @@ No. `allowedCategories` is a fixed enum (`bugfix`, `docs`, `test`, `config`). If
 - [Skills Overview](skills-overview.md) — full catalogue of 28 skills
 - [Layer Model](layer-model.md) — L0 through L4 defence layers
 - [Configuration](configuration.md) — `quickMode` configuration reference
-- `.claude/skills/quick-implementor/SKILL.md` — the Quick Mode skill definition
-- `.claude/skills/story-implementor/SKILL.md` — the Full Mode skill definition
+- `skills/quick-implementor/SKILL.md` — the Quick Mode skill definition
+- `skills/story-implementor/SKILL.md` — the Full Mode skill definition

package/docs/guide/retrofit-adoption.md

@@ -44,7 +44,7 @@ Step 4: 新規 Unit / 構造変更は scaffold-design で設計文書を起こ
 npx phasegate init --name <project-name>
 ```
 
-- `.claude/skills/` に 28 スキルを配置
+- `skills/` に 28 スキルを配置し、有効な agent 用に `.claude/skills` / `.codex/skills` を作成
 - `phasegate.config.json` を生成
 - `phasegate.config.json` に `baseline` セクションが未記載でも、v0.71.0 以降は
   **`baseline.enabled` の default が `true`** のため grandfather は既定で有効
@@ -97,7 +97,24 @@ monorepo など複数ディレクトリを持つ場合は配列で列挙:
 この設定を忘れると、phase-gate は `scripts/harness/` 配下しか見ないため、
 retrofit 対象の新規コード作成が block されず、結果として **phasegate が
 無効化された運用** になってしまう（ISSUE-007 Wave 8 で schema 上 overridable
-になるまで、この設定は config validator で拒否されていた）。
+になるまで、この設定は config validator for 拒否されていた）。
+
+### architecture preset の選定（v0.86.0 以降）
+
+retrofit 対象 PJ のアーキテクチャスタイルに合わせて `architecture.preset` を
+選ぶと、L1-003 / L1-004 が preset の層構造に従って判定される。既存コードが
+Clean 4 層でない場合（オニオン / ヘキサゴナル / 古典レイヤード / 層分離なし）、
+preset を合わせないと合法な import が violation として検出される。
+
+初期は層分離無しで運用したい場合は `flat` を選ぶと L1-001〜004 が auto-disable
+される。選定ガイドと設定例は [Preset Selection Guide](./preset-selection.md) 参照。
+
+既存の v2 config（v0.86.0 未満相当、`architecture` キー無し）は下記で自動
+アップグレードできる:
+
+```bash
+npx phasegate migrate --schema v3
+```
 
 ---
 

package/docs/guide/skills-overview.md

@@ -1,6 +1,6 @@
 # Skills Overview
 
-Phasegate provides 28 skills covering the full AIDLC (AI-Driven Development Life Cycle). Skills are deployed to `.claude/skills/` by `npx phasegate init` and invoked as slash commands in AI agent sessions.
+Phasegate provides 28 skills covering the full AIDLC (AI-Driven Development Life Cycle). `npx phasegate init` deploys the skill bodies to `skills/` and exposes them to enabled agents through `.claude/skills/` / `.codex/skills/` links.
 
 ## AIDLC Process — Skill Execution Order
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.91.0",
+  "version": "0.108.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "Apache-2.0",
@@ -51,6 +51,12 @@
     "phasegate:disable": "npx tsx scripts/harness/main.ts disable-feature",
     "phasegate:check-phase": "npx tsx scripts/harness/main.ts phasegate:check-phase",
     "phasegate:check-ready": "npx tsx scripts/harness/main.ts phasegate:check-ready",
+    "harness:status": "pnpm phasegate:status",
+    "harness:init": "npx tsx scripts/harness/main.ts init",
+    "harness:enable": "pnpm phasegate:enable",
+    "harness:disable": "pnpm phasegate:disable",
+    "harness:check-phase": "pnpm phasegate:check-phase",
+    "harness:check-ready": "pnpm phasegate:check-ready",
     "test": "vitest run --config scripts/harness/__tests__/vitest.config.forks.ts && vitest run --config scripts/harness/__tests__/vitest.config.ts"
   },
   "dependencies": {