phasegate 0.68.0 → 0.70.0

package/CHANGELOG.md

@@ -7,6 +7,205 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.70.0] - 2026-04-22
+
+### Added
+
+- ISSUE-007 Wave 5 — `docs/guide/retrofit-adoption.md` を追加。既存プロジェクトへの phasegate 後付け導入チュートリアル（`init` → `baseline` → `scaffold-design` の 4 ステップ、phase-gate エラーの読み方、baseline 卒業手順、よくある詰まり方の QA）。
+
+## [0.69.0] - 2026-04-22
+
+### Added
+
+- ISSUE-007 Wave 4 / Phase C — `npx phasegate scaffold-design --unit <id> --phase <logical|domain|uiux|unit-test|it-test> [--force] [--json]` CLI を追加。`templates/*.template.md` を読み取り `{{unit}}` プレースホルダを置換して `docs/product/construction/{unit}/*.md` に書き込む。既存ファイルは `--force` なしでは保護。Wave 3 の pre-tool-use hook エラーで emit される `scaffold:` 行が実動作するようになった。
+- `templates/{domain_model,uiux_design,unit_test_design,it_test_design}.template.md` を追加（5 phase すべてに minimum viable template）。
+
+### Changed
+
+- Wave 3 の L2-001 `defaultTemplatePath` を `docs/templates/logical_design.template.md` → `templates/logical_design.template.md` に修正（配布物と整合）。
+
+## [0.68.0] - 2026-04-22
+
+### Changed
+
+- `skills/` 同梱物のクリーンアップ — skill-creator の `scripts/__pycache__/` Python バイトコンパイルキャッシュが npm 配布物に混入していたため除去。`.gitignore` / `.npmignore` に `__pycache__/` と `*.pyc` を追加。skill-creator の使用例パスを Anthropic 原本の `skills/public` / `skills/private` から PhaseGate レイアウトに合わせた `skills` に統一。
+
+## [0.67.0] - 2026-04-22
+
+### Changed
+
+- ISSUE-007 Wave 3 / Phase B — `phase-gate` の HarnessError をアクショナブル化（足りない設計文書のパスと推奨アクションを `fix_example` に明示）。
+
+## [0.66.0] - 2026-04-22
+
+### Added
+
+- ISSUE-007 Wave 2 / Phase A-2 — `.phasegate/baseline.json` に登録済みかつ sha1 が一致するファイルを `phase-gate` 対象から除外する **baseline grandfather** を pre-tool-use hook に統合。レガシーリポジトリへの後付け導入時の摩擦を解消する。
+
+## [0.65.0] - 2026-04-21
+
+### Added
+
+- ISSUE-007 Wave 1 / Phase A-1 — `npx phasegate baseline [--dry-run|--force|--paths|--json]` CLI を追加。`.phasegate/baseline.json` スナップショットを生成し、phasegate.config.json に `baseline.{enabled, path}` スキーマを追加。
+
+## [0.64.0] - 2026-04-21
+
+### Added
+
+- ISSUE-006 Story B — `quickMode.fullModeRequiredWhen` の判定を pre-tool-use hook に統合。`mixedCategories` / `newDomainFile` / `apiContractChange` のいずれかが立つと書き込み時点で同期的に Full Mode へエスカレートしブロックする（block reason: `FULL_MODE_REQUIRED`）。
+
+## [0.63.0] - 2026-04-21
+
+### Added
+
+- ISSUE-006 Story A — `quickMode.fullModeRequiredWhen` 設定キー（`mixedCategories` / `newDomainFile` / `apiContractChange`、いずれもデフォルト `true`）を導入し、Quick Mode → Full Mode のエスカレート条件を設定駆動化。
+- `npx phasegate check-change-category --paths <csv> [--format json] [--fail-on-full-required]` CLI — 任意のファイルリストを Quick Mode カテゴリに分類し、Full Mode が必要かを返す。CI gate での使用を想定。
+
+## [0.62.0] - 2026-04-21
+
+### Added
+
+- ISSUE-013 C-6（軽量版）— UserPromptSubmit hook に violation detection を追加。
+
+## [0.61.0] - 2026-04-21
+
+### Added
+
+- ISSUE-013 C-5 — UserPromptSubmit hook で動的状態（現在の Quick/Full モード等）をプロンプトに注入。
+
+## [0.60.0] - 2026-04-21
+
+### Added
+
+- ISSUE-013 C-4 — SessionStart hook を追加し、セッション開始時に静的ルール（CLAUDE.md 等）を注入する仕組みを実装。
+
+## [0.59.0] - 2026-04-21
+
+### Added
+
+- ISSUE-013 A-1 / A-2 / B-3 — `phasegate init --agent <claude|codex|both>` オプションで Codex CLI 向けの `.codex/hooks.json` を自動配置。Codex dogfood セットアップを README に追記。
+
+## [0.58.0] - 2026-04-21
+
+### Added
+
+- ISSUE-013 Wave 2 — Codex CLI 統合の本体実装。`PreToolUse(Bash)` / `PostToolUse(Bash)` / `Stop` フックを Codex 向けに配線。
+
+## [0.57.0] - 2026-04-20
+
+### Added
+
+- ISSUE-013 Wave 1 — `BashWriteTargetExtractor` が Bash 経由 `apply_patch <<'PATCH'` heredoc の書き込み先パスを抽出するよう拡張。Codex の Bash ルートを pre-tool-use hook で押さえられるようになる。
+
+## [0.56.0] - 2026-04-20
+
+### Fixed
+
+- ISSUE-011 Wave 3 / P3-4 / HF2-04 — `initial-creation-expiration-checker` バリデータを修正。
+
+## [0.55.0] - 2026-04-20
+
+### Fixed
+
+- ISSUE-011 Wave 2 — Markdown parser の code-span / code-fence 内に書かれた `@unit` / `@layer` 等のメタタグを誤検出していたバグを修正（コードフェンス内をスキップするよう変更）。
+
+## [0.54.0] - 2026-04-20
+
+### Fixed
+
+- ISSUE-011 Wave 1 / P2-2 — CLI のエラー伝播を修正（内部エラーが exit code 0 で握り潰されていた問題）。
+- ISSUE-011 Wave 1 / P2-3 — `.mdx` / `.markdown` 拡張子を Markdown ドキュメント検証の対象に追加。
+
+## [0.53.0] - 2026-04-19
+
+### Added
+
+- ISSUE-008 Phase C-1〜C-3 + D — テストファイルへの `@story` メタデータ end-to-end 検証を完成。`templates/` 配下のサンプルファイルを実体化し、生成コードへのメタデータ付与を保証する経路を確立。
+
+## [0.52.0] - 2026-04-19
+
+### Changed
+
+- ISSUE-008 Phase B-3 — pre-commit フローに `.md` 設計文書の検証を接続。`logical_design.md` 等の frontmatter / メタデータが欠けたままコミットされるのを防ぐ。
+
+## [0.51.0] - 2026-04-19
+
+### Added
+
+- ISSUE-011 起票（`validate-metadata` UX / parser / drift 検出に関する改善集）。
+
+## [0.50.0] - 2026-04-19
+
+### Added
+
+- ISSUE-008 Phase B-2 — `validate-metadata` CLI に `.md` 分岐を追加。Markdown 設計文書のメタデータ（frontmatter）も検証対象になる。
+
+## [0.49.0] - 2026-04-19
+
+### Changed
+
+- ISSUE-008 Phase B-1 撤回 + P1-2 前提更新 — 設計文書 frontmatter 必須化（v0.48.0）の方針を再検討し前提を更新。
+
+## [0.48.0] - 2026-04-19
+
+### Added
+
+- ISSUE-008 Phase B-1 / P1-2 — 設計文書（`logical_design.md` / `domain_model.md` 等）の frontmatter を必須化。
+
+## [0.47.0] - 2026-04-18
+
+### Added
+
+- ISSUE-008 Phase A / P1-1 — 生成コードに `@unit` / `@layer` メタデータを必ず付与するよう、各実装スキル（`story-implementor` / `quick-implementor`）に指示を追加。
+
+## [0.46.0] - 2026-04-18
+
+### Added
+
+- ISSUE-007 起票（リトロフィット導入障壁 — レガシーリポジトリでの初回 phase-gate ブロック問題）。
+- ISSUE-008 起票（メタデータ emit 欠落 — 生成コードに `@unit` / `@layer` が付かないケース）。
+
+## [0.45.0] - 2026-04-18
+
+### Added
+
+- ISSUE-006 起票 + Phase P2-3 — `docs/guide/quick-vs-full-mode.md`（Quick Mode と Full Mode の選択ガイド）を新設。
+
+## [0.44.0] - 2026-04-18
+
+### Fixed
+
+- ISSUE-005 Phase D / P3-8 — Markdown のメタ見出し（`---` で囲まれた frontmatter 等）をパース時に正しくスキップするよう修正。
+- ISSUE-005 Phase D / P3-9 — ファイルパスから `@unit` を推定するロジックを改善。
+- ISSUE-005 Phase D / P3-10 — `list-errors` と `render-errors` の境界をドキュメント化（`list-errors` は定義駆動 / `render-errors` はランタイム駆動）。
+
+## [0.43.0] - 2026-04-18
+
+### Fixed
+
+- ISSUE-005 Phase C / P2-6 — `phasegate:check-phase` の `--help` / `--json` フラグが positional 引数として食われ unit 名扱いされていたバグを修正。
+- ISSUE-005 Phase C / P2-7 — `regression:*` 系コマンドの出力先を整理。
+
+## [0.42.0] - 2026-04-18
+
+### Fixed
+
+- ISSUE-005 Phase B-2 / P1-5 — `detect-drift` と L4-001 バリデータを統合し、設計-コード乖離検出の経路を一本化。
+
+## [0.41.0] - 2026-04-18
+
+### Fixed
+
+- ISSUE-005 Phase B-1 / P1-3 — fresh repo（履歴がない初期化直後のリポジトリ）での git 解析が失敗するバグを fallback 経路で修正。
+- ISSUE-005 Phase B-1 / P1-4 — `validate --layer` フィルタが効かないケースを修正。
+
+## [0.40.0] - 2026-04-18
+
+### Fixed
+
+- ISSUE-005 Phase A / P0-1 — pre-commit 経路の復旧（一部バリデータが pre-commit から呼ばれていなかった問題）。
+- ISSUE-005 Phase A / P0-2 — `ci:generate-template` の UX 改善（`--preset` 省略時のエラーメッセージを実用的に）。
+
 ## [0.39.0] - 2026-04-18
 
 ### Fixed
@@ -176,7 +375,36 @@ Pre-reset era (formerly v1.0.0 - v1.1.1). Initial release and early bug fixes:
 - ajv v8互換対応
 - 3件のバグ修正
 
-[Unreleased]: https://github.com/junpei-9898/phasegate/compare/v0.38.0...HEAD
+[Unreleased]: https://github.com/junpei-9898/phasegate/compare/v0.67.0...HEAD
+[0.67.0]: https://github.com/junpei-9898/phasegate/compare/v0.66.0...v0.67.0
+[0.66.0]: https://github.com/junpei-9898/phasegate/compare/v0.65.0...v0.66.0
+[0.65.0]: https://github.com/junpei-9898/phasegate/compare/v0.64.0...v0.65.0
+[0.64.0]: https://github.com/junpei-9898/phasegate/compare/v0.63.0...v0.64.0
+[0.63.0]: https://github.com/junpei-9898/phasegate/compare/v0.62.0...v0.63.0
+[0.62.0]: https://github.com/junpei-9898/phasegate/compare/v0.61.0...v0.62.0
+[0.61.0]: https://github.com/junpei-9898/phasegate/compare/v0.60.0...v0.61.0
+[0.60.0]: https://github.com/junpei-9898/phasegate/compare/v0.59.0...v0.60.0
+[0.59.0]: https://github.com/junpei-9898/phasegate/compare/v0.58.0...v0.59.0
+[0.58.0]: https://github.com/junpei-9898/phasegate/compare/v0.57.0...v0.58.0
+[0.57.0]: https://github.com/junpei-9898/phasegate/compare/v0.56.0...v0.57.0
+[0.56.0]: https://github.com/junpei-9898/phasegate/compare/v0.55.0...v0.56.0
+[0.55.0]: https://github.com/junpei-9898/phasegate/compare/v0.54.0...v0.55.0
+[0.54.0]: https://github.com/junpei-9898/phasegate/compare/v0.53.0...v0.54.0
+[0.53.0]: https://github.com/junpei-9898/phasegate/compare/v0.52.0...v0.53.0
+[0.52.0]: https://github.com/junpei-9898/phasegate/compare/v0.51.0...v0.52.0
+[0.51.0]: https://github.com/junpei-9898/phasegate/compare/v0.50.0...v0.51.0
+[0.50.0]: https://github.com/junpei-9898/phasegate/compare/v0.49.0...v0.50.0
+[0.49.0]: https://github.com/junpei-9898/phasegate/compare/v0.48.0...v0.49.0
+[0.48.0]: https://github.com/junpei-9898/phasegate/compare/v0.47.0...v0.48.0
+[0.47.0]: https://github.com/junpei-9898/phasegate/compare/v0.46.0...v0.47.0
+[0.46.0]: https://github.com/junpei-9898/phasegate/compare/v0.45.0...v0.46.0
+[0.45.0]: https://github.com/junpei-9898/phasegate/compare/v0.44.0...v0.45.0
+[0.44.0]: https://github.com/junpei-9898/phasegate/compare/v0.43.0...v0.44.0
+[0.43.0]: https://github.com/junpei-9898/phasegate/compare/v0.42.0...v0.43.0
+[0.42.0]: https://github.com/junpei-9898/phasegate/compare/v0.41.0...v0.42.0
+[0.41.0]: https://github.com/junpei-9898/phasegate/compare/v0.40.0...v0.41.0
+[0.40.0]: https://github.com/junpei-9898/phasegate/compare/v0.39.0...v0.40.0
+[0.39.0]: https://github.com/junpei-9898/phasegate/compare/v0.38.0...v0.39.0
 [0.38.0]: https://github.com/junpei-9898/phasegate/compare/v0.37.0...v0.38.0
 [0.37.0]: https://github.com/junpei-9898/phasegate/compare/v0.36.0...v0.37.0
 [0.36.0]: https://github.com/junpei-9898/phasegate/compare/v0.35.0...v0.36.0

package/README.ja.md

@@ -588,7 +588,7 @@ export class ConfigSchema { ... }
 
 | Hook | タイミング | 動作 |
 |---|---|---|
-| **PreToolUse** | Write/Edit/Bash 実行前 | フェーズゲート違反・保護ファイルへの書き込み・Bash 経由の書き込み(`sed -i`, `tee` 等)をブロック |
+| **PreToolUse** | Write/Edit/Bash 実行前 | フェーズゲート違反・保護ファイルへの書き込み・Bash 経由の書き込み(`sed -i`, `tee` 等)をブロック。`quickMode.fullModeRequiredWhen` トリガー時は Quick Mode → Full Mode へエスカレート（v0.64.0）。`.phasegate/baseline.json` 登録済みかつ未編集のファイルは grandfather として `phase-gate` をスキップ（v0.66.0） |
 | **PostToolUse** | Write/Edit 実行後 | Biome AST ルールを自動実行、違反を即時フィードバック |
 | **Stop** | セッション終了前 | L2-L4 全チェックを実行、全グリーンでないと終了を保留 |
 
@@ -807,4 +807,4 @@ phasegate 自体の開発（内部アーキテクチャ、回帰テスト、リ
 
 ---
 
-*Last updated: 2026-04-07 -- v0.33.0*
+*Last updated: 2026-04-22 -- v0.66.0*

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

@@ -50,6 +50,37 @@ Both modes keep **L1 in full strength** and **L2 metadata / test-quality** — `
 
 ---
 
+## Automatic Escalation: `fullModeRequiredWhen`
+
+Even when you launch `/quick-implementor`, the harness re-checks whether the in-flight change set actually qualifies as Quick. Three triggers force escalation back to Full Mode at the **pre-tool-use hook** (synchronous block, not just a post-hoc warning):
+
+| Trigger | `quickMode.fullModeRequiredWhen.*` flag | Default | Block reason on hook |
+|---|---|---|---|
+| Change set spans multiple categories (e.g. `bugfix` + `api`) | `mixedCategories` | `true` | `FULL_MODE_REQUIRED` |
+| New file added under any `domain/` directory | `newDomainFile` | `true` | `FULL_MODE_REQUIRED` |
+| Modification to a Port (`*port.ts`) or Adapter (`*adapter.ts`) | `apiContractChange` | `true` | `FULL_MODE_REQUIRED` |
+
+Introduced in v0.63.0 (ISSUE-006 Story A — config-driven flags + `check-change-category` CLI) and wired into the hook in v0.64.0 (Story B). Each flag can be flipped to `false` only when a project intentionally accepts the risk of merging that category of change without the design ceremony — e.g. early-stage prototypes where new domain files churn freely.
+
+### Dry-running the classifier
+
+Use `check-change-category` to evaluate an arbitrary file list without actually starting an implementation:
+
+```bash
+# Inspect what category each file lands in
+npx phasegate check-change-category --paths src/foo.ts,src/bar.ts
+
+# CI gate: hard-fail the build if Quick Mode would have to escalate
+npx phasegate check-change-category \
+  --paths "$(git diff --name-only origin/main...HEAD | paste -sd, -)" \
+  --fail-on-full-required \
+  --format json
+```
+
+`--fail-on-full-required` is opt-in; without it the command is purely informational (always exit 0).
+
+---
+
 ## Worked Examples
 
 ### Full Mode candidates
@@ -125,7 +156,7 @@ Not mechanically — Quick Mode does not inspect paths. A one-line bugfix inside
 Stop, commit nothing, and re-launch `/story-implementor`. Don't try to "finish in Quick" — you'll skip the design gate that would otherwise catch the scope creep.
 
 **Q. Can I disable Quick Mode entirely?**
-Yes — remove all entries from `quickMode.allowedCategories` in `phasegate.config.json`. All changes will route through Full Mode. This is reasonable for high-compliance projects.
+Yes — remove all entries from `quickMode.allowedCategories` in `phasegate.config.json`. All changes will route through Full Mode. This is reasonable for high-compliance projects. Alternatively, leave the categories as-is and set every `quickMode.fullModeRequiredWhen.*` flag to `true` (the default) so any non-trivial scope automatically escalates.
 
 **Q. Can I add custom categories?**
 No. `allowedCategories` is a fixed enum (`bugfix`, `docs`, `test`, `config`). If your workflow needs a fifth category, that is evidence the change is probably Full Mode material.

package/docs/guide/retrofit-adoption.md

@@ -0,0 +1,241 @@
+# Retrofit Adoption Guide
+
+既に動いているプロジェクトに phasegate を後付け導入するためのチュートリアル。
+
+## このガイドの対象
+
+- 既存コードベースに phasegate を導入したいメンテナ
+- 設計文書（logical_design.md / domain_model.md 等）が未整備のまま保守と新規開発を並行したい状態
+- 「phase-gate が既存コード編集で発火して保守が詰む」ことを避けたい
+
+phasegate は本来「新規プロジェクトをゼロから AIDLC で組む」前提で設計されている。
+既存コードに後付けすると、設計文書の無いファイルを触るたびに pre-tool-use hook が発火し、
+通常の保守作業が block される。このガイドは ISSUE-007 で導入した **baseline grandfather** と
+**scaffold-design CLI** を組み合わせて、段階的に phasegate 管理下に取り込む手順を示す。
+
+---
+
+## 前提
+
+- Node.js >= 18.0.0
+- 既存プロジェクトのソースコードが git で管理されている
+- phasegate >= v0.69.0（scaffold-design CLI 含む）
+
+```bash
+npm install --save-dev phasegate
+```
+
+---
+
+## 4 ステップ後付け導入
+
+```
+Step 1: npx phasegate init           # 雛形・スキル配布
+Step 2: npx phasegate baseline       # 既存コードを grandfather 登録
+Step 3: 既存ファイルの保守は gate をスキップ
+Step 4: 新規 Unit / 構造変更は scaffold-design で設計文書を起こしてから実装
+```
+
+---
+
+## Step 1: 初期化
+
+```bash
+npx phasegate init --name <project-name>
+```
+
+- `.claude/skills/` に 28 スキルを配置
+- `phasegate.config.json` を生成
+- `phasegate.config.json` の `baseline` セクションは既定で `enabled: true`
+
+`phasegate.config.json` の該当部分（デフォルト）:
+
+```json
+{
+  "baseline": {
+    "enabled": true,
+    "path": ".phasegate/baseline.json"
+  }
+}
+```
+
+`baseline.enabled` を `false` にすると grandfather が無効化され、既存ファイルも全て
+gate 対象になる（後付け導入では推奨しない）。
+
+---
+
+## Step 2: 既存コードを baseline に登録
+
+```bash
+npx phasegate baseline
+```
+
+実行すると、現時点の全 TS/JS ソースファイルの相対パスと sha1 ハッシュを
+`.phasegate/baseline.json` に保存する。
+
+```jsonc
+{
+  "version": 1,
+  "createdAt": "2026-04-22T10:00:00Z",
+  "entries": [
+    { "path": "src/foo.ts", "sha1": "abc123..." },
+    { "path": "src/bar.ts", "sha1": "def456..." }
+  ]
+}
+```
+
+### 確認だけしたい場合
+
+```bash
+npx phasegate baseline --dry-run --json
+```
+
+### 特定ディレクトリだけ登録
+
+```bash
+npx phasegate baseline --paths "src/**/*.ts,scripts/**/*.ts"
+```
+
+### `.phasegate/baseline.json` は commit する
+
+grandfather 対象はチーム全員で共有するため、`.phasegate/baseline.json` は
+`.gitignore` に入れず commit する。
+
+---
+
+## Step 3: 既存ファイルの保守
+
+baseline に登録されたファイルは pre-tool-use hook で gate をスキップする。
+
+- ファイル内容を編集しても sha1 が一致していれば許可（タイポ修正・コメント追加等）
+- 構造的変更（新規 export 追加・レイヤー変更等）で sha1 がズレた瞬間、grandfather
+  が外れて通常の gate 対象に戻る。その時は Step 4 に進む
+
+この段階では `logical_design.md` 等の設計文書が存在しなくても、既存ファイルの
+保守は通常通り行える。
+
+---
+
+## Step 4: 新規 Unit / 構造変更は scaffold-design
+
+新しい Unit を作る、あるいは baseline を外して既存 Unit を phasegate 管理下に
+取り込む場合、設計文書を先に起こす。
+
+### 4-1: phase-gate 発火時のエラーを読む
+
+設計文書が存在しない Unit に新規ファイルを作ろうとすると、pre-tool-use hook が
+以下の形式で block する（v0.67.0 以降）:
+
+```
+成果物が不足しています: docs/product/construction/harness-api/logical_design.md
+→ phase gate prerequisites are not met
+
+次のアクション: /story-implementor スキルを使用して設計フェーズから開始してください。
+  scaffold: npx phasegate scaffold-design --unit harness-api --phase logical
+  テンプレ: templates/logical_design.template.md
+```
+
+- **次のアクション**: `suggestedSkill` — 本格的に設計するなら Claude Code でこのスキルを呼ぶ
+- **scaffold**: `scaffoldCommand` — テンプレだけ先に生成して placeholder で埋めたい時はこちら
+- **テンプレ**: `templatePath` — 手書きしたい場合の参照元
+
+### 4-2: scaffold-design で雛形を生成
+
+```bash
+npx phasegate scaffold-design --unit harness-api --phase logical
+```
+
+出力例:
+
+```
+設計文書を生成しました: docs/product/construction/harness-api/logical_design.md
+テンプレ: /path/to/project/templates/logical_design.template.md
+Unit: harness-api / phase: logical
+TODO プレースホルダを実体で埋めてください。
+```
+
+生成されるファイルは `{{unit}}` が Unit ID に置換済みで、`TODO:` コメントが
+各セクションに残る。人間 / AI エージェントがこの TODO を埋めて設計を実体化する。
+
+### 対応する phase
+
+| `--phase` | 生成先 |
+|---|---|
+| `logical` | `docs/product/construction/{unit}/logical_design.md` |
+| `domain` | `docs/product/construction/{unit}/domain_model.md` |
+| `uiux` | `docs/product/construction/{unit}/uiux_design.md` |
+| `unit-test` | `docs/product/construction/{unit}/unit_test_design.md` |
+| `it-test` | `docs/product/construction/{unit}/it_test_design.md` |
+
+### 4-3: 既存ファイルがある場合
+
+既定では scaffold は既存ファイルを上書きしない:
+
+```
+既に存在します: docs/product/construction/harness-api/logical_design.md
+上書きするには --force を指定してください。
+```
+
+意図的に再生成したい場合のみ `--force` を付ける:
+
+```bash
+npx phasegate scaffold-design --unit harness-api --phase logical --force
+```
+
+### 4-4: JSON 出力（CI / スクリプト向け）
+
+```bash
+npx phasegate scaffold-design --unit harness-api --phase logical --json
+```
+
+exit code:
+
+| 状況 | code |
+|---|---|
+| 生成成功 / 上書き成功 | 0 |
+| 既存ファイルあり（--force なし） | 2 |
+| 引数不正 / テンプレ不在 | 2 |
+
+---
+
+## baseline から外して phasegate 管理下に取り込む
+
+Unit の設計文書が揃い、phasegate フル管理に昇格させたい場合の手順:
+
+1. `scaffold-design` で logical_design.md / domain_model.md を生成 → TODO を埋める
+2. 対象ファイルを `.phasegate/baseline.json` から削除（手動編集 or `--paths` で対象外にして再生成）
+3. 以降、構造変更のたびに phase-gate が走る通常の運用に移行
+
+---
+
+## よくある詰まり方
+
+### Q. `baseline` 作成後も gate が発火する
+
+**確認**: `phasegate.config.json` の `baseline.enabled` が `true` か。
+`baseline.path` と実ファイルの配置が一致しているか。
+
+### Q. scaffold した直後に L1 lint が失敗する
+
+scaffold は markdown テンプレのみ生成する。**TS/JS ソースファイルは生成しない**。
+ソースコードの雛形が必要な場合は `/story-implementor` スキルを使う。
+
+### Q. チームメイトの環境で baseline がズレる
+
+`.phasegate/baseline.json` は commit する必要がある。`.gitignore` に
+入れていないか確認。
+
+### Q. 既存ファイルを少し触っただけで grandfather が外れた
+
+sha1 一致で判定しているため、**フォーマット変更・インポート順序変更でも外れる**。
+意図的な編集であればそのまま設計文書を起こすフローに移る。自動フォーマッタが
+大量変更を起こす場合は、`baseline` を `--force` で取り直す運用も可。
+
+---
+
+## 関連
+
+- `docs/guide/cli-reference.md` — `baseline` / `scaffold-design` のフラグ一覧
+- `docs/guide/layer-model.md` — L0-L4 防御モデルと phase-gate の位置付け
+- `docs/ADR/ADR-013-story-reflection-gate.md` — phase-gate の思想的背景
+- ISSUE-007 — 本ガイドが対応する起票 issue（`docs/inception/issues/ISSUE-007/`）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.68.0",
+  "version": "0.70.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",

package/scripts/harness/ci-governance/application/dto/scaffold-design-input.ts

@@ -0,0 +1,8 @@
+// @unit ci-governance
+// @layer application
+
+export interface ScaffoldDesignInput {
+  readonly unit: string;
+  readonly phase: string;
+  readonly force?: boolean;
+}

package/scripts/harness/ci-governance/application/dto/scaffold-design-output.ts

@@ -0,0 +1,12 @@
+// @unit ci-governance
+// @layer application
+
+export interface ScaffoldDesignOutput {
+  readonly targetPath: string;
+  readonly templatePath: string;
+  readonly unit: string;
+  readonly phase: string;
+  readonly written: boolean;
+  readonly alreadyExists: boolean;
+  readonly overwritten: boolean;
+}

package/scripts/harness/ci-governance/application/usecases/scaffold-design-usecase.ts

@@ -0,0 +1,56 @@
+// @unit ci-governance
+// @layer application
+
+import { DesignPhase } from '../../domain/value-objects/design-phase.js';
+import type { TemplateRepositoryPort } from '../../domain/ports/template-repository-port.js';
+import type { DesignDocWriterPort } from '../../domain/ports/design-doc-writer-port.js';
+import type { ScaffoldDesignInput } from '../dto/scaffold-design-input.js';
+import type { ScaffoldDesignOutput } from '../dto/scaffold-design-output.js';
+
+const UNIT_PLACEHOLDER = /\{\{\s*unit\s*\}\}/g;
+
+export class ScaffoldDesignUseCase {
+  constructor(
+    private readonly templates: TemplateRepositoryPort,
+    private readonly writer: DesignDocWriterPort,
+  ) {}
+
+  async execute(input: ScaffoldDesignInput): Promise<ScaffoldDesignOutput> {
+    if (!input.unit || input.unit.trim().length === 0) {
+      throw new Error('--unit は必須です');
+    }
+    const phase = DesignPhase.create(input.phase);
+    const unit = input.unit.trim();
+    const force = input.force === true;
+
+    const templatePath = this.templates.resolvePath(phase);
+    const targetPath = this.writer.resolvePath(unit, phase);
+    const alreadyExists = await this.writer.exists(unit, phase);
+
+    if (alreadyExists && !force) {
+      return {
+        targetPath,
+        templatePath,
+        unit,
+        phase: phase.value,
+        written: false,
+        alreadyExists: true,
+        overwritten: false,
+      };
+    }
+
+    const raw = await this.templates.read(phase);
+    const rendered = raw.replace(UNIT_PLACEHOLDER, unit);
+    await this.writer.write(unit, phase, rendered);
+
+    return {
+      targetPath,
+      templatePath,
+      unit,
+      phase: phase.value,
+      written: true,
+      alreadyExists,
+      overwritten: alreadyExists && force,
+    };
+  }
+}

package/scripts/harness/ci-governance/composition-root.ts

@@ -40,11 +40,17 @@ import { GlobFileScannerAdapter } from './infrastructure/adapters/glob-file-scan
 import { FileSystemSha1HasherAdapter } from './infrastructure/adapters/file-system-sha1-hasher-adapter.js';
 import { BaselineJsonRepositoryAdapter } from './infrastructure/adapters/baseline-json-repository-adapter.js';
 
+import { ScaffoldDesignUseCase } from './application/usecases/scaffold-design-usecase.js';
+import { FileSystemTemplateRepositoryAdapter } from './infrastructure/adapters/file-system-template-repository-adapter.js';
+import { FileSystemDesignDocWriterAdapter } from './infrastructure/adapters/file-system-design-doc-writer-adapter.js';
+import { ScaffoldDesignHandler } from './presentation/handlers/scaffold-design-handler.js';
+
 export interface CiGovernanceCompositionRoot {
   generateCiTemplateHandler: GenerateCiTemplateHandler;
   migrateAgentsMdHandler: MigrateAgentsMdHandler;
   checkRepetitionHandler: CheckRepetitionHandler;
   createBaselineHandler: CreateBaselineHandler;
+  scaffoldDesignHandler: ScaffoldDesignHandler;
   // Use cases exposed for direct access
   recordErrorOccurrenceUseCase: RecordErrorOccurrenceUseCase;
   checkEscalationUseCase: CheckEscalationUseCase;
@@ -52,9 +58,13 @@ export interface CiGovernanceCompositionRoot {
   aggregateLessonsUseCase: AggregateLessonsUseCase;
   validatePointersUseCase: ValidatePointersUseCase;
   createBaselineUseCase: CreateBaselineUseCase;
+  scaffoldDesignUseCase: ScaffoldDesignUseCase;
 }
 
-export function buildCiGovernance(baseDir: string): CiGovernanceCompositionRoot {
+export function buildCiGovernance(
+  baseDir: string,
+  harnessRoot: string = baseDir,
+): CiGovernanceCompositionRoot {
   // Infrastructure adapters
   const validatorIdRegistryAdapter = new ValidatorIdRegistryAdapter();
   const presetConfigAdapter = new PresetConfigAdapter();
@@ -98,6 +108,14 @@ export function buildCiGovernance(baseDir: string): CiGovernanceCompositionRoot
     baselineRepository,
   );
 
+  // Scaffold design adapters & use case (ISSUE-007 Wave 4)
+  const templateRepository = new FileSystemTemplateRepositoryAdapter(harnessRoot);
+  const designDocWriter = new FileSystemDesignDocWriterAdapter(baseDir);
+  const scaffoldDesignUseCase = new ScaffoldDesignUseCase(
+    templateRepository,
+    designDocWriter,
+  );
+
   // Handlers
   const generateCiTemplateHandler = new GenerateCiTemplateHandler(
     generateCiTemplateUseCase,
@@ -106,17 +124,20 @@ export function buildCiGovernance(baseDir: string): CiGovernanceCompositionRoot
   const migrateAgentsMdHandler = new MigrateAgentsMdHandler(migrateAgentsMdUseCase);
   const checkRepetitionHandler = new CheckRepetitionHandler(checkEscalationUseCase);
   const createBaselineHandler = new CreateBaselineHandler(createBaselineUseCase);
+  const scaffoldDesignHandler = new ScaffoldDesignHandler(scaffoldDesignUseCase);
 
   return {
     generateCiTemplateHandler,
     migrateAgentsMdHandler,
     checkRepetitionHandler,
     createBaselineHandler,
+    scaffoldDesignHandler,
     recordErrorOccurrenceUseCase,
     checkEscalationUseCase,
     resetRepetitionUseCase,
     aggregateLessonsUseCase,
     validatePointersUseCase,
     createBaselineUseCase,
+    scaffoldDesignUseCase,
   };
 }

package/scripts/harness/ci-governance/domain/ports/design-doc-writer-port.ts

@@ -0,0 +1,18 @@
+// @unit ci-governance
+// @layer domain
+
+import type { DesignPhase } from '../value-objects/design-phase.js';
+
+export interface DesignDocWriterPort {
+  /** 書き込み先の絶対パスを返す（副作用なし） */
+  resolvePath(unit: string, phase: DesignPhase): string;
+
+  /** 書き込み先が既に存在するか */
+  exists(unit: string, phase: DesignPhase): Promise<boolean>;
+
+  /**
+   * 設計文書を書き込む（親ディレクトリが無ければ作成）。
+   * 書き込んだ絶対パスを返す。
+   */
+  write(unit: string, phase: DesignPhase, content: string): Promise<string>;
+}

package/scripts/harness/ci-governance/domain/ports/template-repository-port.ts

@@ -0,0 +1,15 @@
+// @unit ci-governance
+// @layer domain
+
+import type { DesignPhase } from '../value-objects/design-phase.js';
+
+export interface TemplateRepositoryPort {
+  /**
+   * 指定した phase に対応するテンプレートファイルを読み込む。
+   * 存在しない場合は例外を投げる。
+   */
+  read(phase: DesignPhase): Promise<string>;
+
+  /** テンプレートの絶対パスを返す（UI 出力用） */
+  resolvePath(phase: DesignPhase): string;
+}

package/scripts/harness/ci-governance/domain/value-objects/design-phase.ts

@@ -0,0 +1,65 @@
+// @unit ci-governance
+// @layer domain
+
+export const DESIGN_PHASES = [
+  'logical',
+  'domain',
+  'uiux',
+  'unit-test',
+  'it-test',
+] as const;
+
+export type DesignPhaseValue = (typeof DESIGN_PHASES)[number];
+
+export class DesignPhase {
+  private constructor(readonly value: DesignPhaseValue) {}
+
+  static create(input: string): DesignPhase {
+    if (!DESIGN_PHASES.includes(input as DesignPhaseValue)) {
+      throw new Error(
+        `未知の設計 phase: "${input}"。許容値: ${DESIGN_PHASES.join(', ')}`,
+      );
+    }
+    return new DesignPhase(input as DesignPhaseValue);
+  }
+
+  static isValid(input: string): input is DesignPhaseValue {
+    return (DESIGN_PHASES as readonly string[]).includes(input);
+  }
+
+  equals(other: DesignPhase): boolean {
+    return this.value === other.value;
+  }
+
+  /** このフェーズに対応するテンプレートファイル名（`docs/templates/` 配下） */
+  get templateFileName(): string {
+    switch (this.value) {
+      case 'logical':
+        return 'logical_design.template.md';
+      case 'domain':
+        return 'domain_model.template.md';
+      case 'uiux':
+        return 'uiux_design.template.md';
+      case 'unit-test':
+        return 'unit_test_design.template.md';
+      case 'it-test':
+        return 'it_test_design.template.md';
+    }
+  }
+
+  /** このフェーズで書き込む設計文書のファイル名（`docs/product/construction/{unit}/` 配下） */
+  get designDocFileName(): string {
+    switch (this.value) {
+      case 'logical':
+        return 'logical_design.md';
+      case 'domain':
+        return 'domain_model.md';
+      case 'uiux':
+        return 'uiux_design.md';
+      case 'unit-test':
+        return 'unit_test_design.md';
+      case 'it-test':
+        return 'it_test_design.md';
+    }
+  }
+}

package/scripts/harness/ci-governance/infrastructure/adapters/file-system-design-doc-writer-adapter.ts

@@ -0,0 +1,42 @@
+// @unit ci-governance
+// @layer infrastructure
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type { DesignDocWriterPort } from '../../domain/ports/design-doc-writer-port.js';
+import type { DesignPhase } from '../../domain/value-objects/design-phase.js';
+
+export class FileSystemDesignDocWriterAdapter implements DesignDocWriterPort {
+  private readonly baseDir: string;
+  private readonly constructionDir: string;
+
+  constructor(
+    baseDir: string,
+    constructionSubDir: string = path.join('docs', 'product', 'construction'),
+  ) {
+    this.baseDir = baseDir;
+    this.constructionDir = path.isAbsolute(constructionSubDir)
+      ? constructionSubDir
+      : path.join(baseDir, constructionSubDir);
+  }
+
+  resolvePath(unit: string, phase: DesignPhase): string {
+    return path.join(this.constructionDir, unit, phase.designDocFileName);
+  }
+
+  async exists(unit: string, phase: DesignPhase): Promise<boolean> {
+    try {
+      await fs.access(this.resolvePath(unit, phase));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async write(unit: string, phase: DesignPhase, content: string): Promise<string> {
+    const targetPath = this.resolvePath(unit, phase);
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.writeFile(targetPath, content, 'utf-8');
+    return targetPath;
+  }
+}

package/scripts/harness/ci-governance/infrastructure/adapters/file-system-template-repository-adapter.ts

@@ -0,0 +1,35 @@
+// @unit ci-governance
+// @layer infrastructure
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type { TemplateRepositoryPort } from '../../domain/ports/template-repository-port.js';
+import type { DesignPhase } from '../../domain/value-objects/design-phase.js';
+
+export class FileSystemTemplateRepositoryAdapter implements TemplateRepositoryPort {
+  private readonly templatesDir: string;
+
+  constructor(harnessRoot: string, subDir: string = 'templates') {
+    this.templatesDir = path.isAbsolute(subDir)
+      ? subDir
+      : path.join(harnessRoot, subDir);
+  }
+
+  resolvePath(phase: DesignPhase): string {
+    return path.join(this.templatesDir, phase.templateFileName);
+  }
+
+  async read(phase: DesignPhase): Promise<string> {
+    const filePath = this.resolvePath(phase);
+    try {
+      return await fs.readFile(filePath, 'utf-8');
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        throw new Error(
+          `テンプレートが見つかりません: ${filePath} (phase=${phase.value})`,
+        );
+      }
+      throw err;
+    }
+  }
+}

package/scripts/harness/ci-governance/presentation/handlers/scaffold-design-handler.ts

@@ -0,0 +1,97 @@
+// @unit ci-governance
+// @layer presentation
+
+import { DesignPhase } from '../../domain/value-objects/design-phase.js';
+import type { ScaffoldDesignUseCase } from '../../application/usecases/scaffold-design-usecase.js';
+
+export interface ScaffoldDesignHandlerArgs {
+  readonly unit?: string;
+  readonly phase?: string;
+  readonly force?: boolean;
+  readonly format?: 'human' | 'json';
+}
+
+export interface ScaffoldDesignHandlerResult {
+  readonly exitCode: number;
+  readonly output: string;
+}
+
+export class ScaffoldDesignHandler {
+  constructor(private readonly useCase: ScaffoldDesignUseCase) {}
+
+  async handle(args: ScaffoldDesignHandlerArgs): Promise<ScaffoldDesignHandlerResult> {
+    const format = args.format ?? 'human';
+
+    if (!args.unit || args.unit.trim().length === 0) {
+      return this.fail(format, '--unit <unit-id> は必須です', 2);
+    }
+    if (!args.phase || args.phase.trim().length === 0) {
+      return this.fail(
+        format,
+        `--phase <name> は必須です（許容値: logical, domain, uiux, unit-test, it-test）`,
+        2,
+      );
+    }
+    if (!DesignPhase.isValid(args.phase)) {
+      return this.fail(
+        format,
+        `未知の phase: "${args.phase}"（許容値: logical, domain, uiux, unit-test, it-test）`,
+        2,
+      );
+    }
+
+    let result;
+    try {
+      result = await this.useCase.execute({
+        unit: args.unit,
+        phase: args.phase,
+        force: args.force,
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return this.fail(format, `scaffold 失敗: ${msg}`, 2);
+    }
+
+    if (format === 'json') {
+      return {
+        exitCode: result.alreadyExists && !result.written ? 2 : 0,
+        output: JSON.stringify(result, null, 2),
+      };
+    }
+
+    if (result.alreadyExists && !result.written) {
+      return {
+        exitCode: 2,
+        output: [
+          `既に存在します: ${result.targetPath}`,
+          '上書きするには --force を指定してください。',
+        ].join('\n'),
+      };
+    }
+
+    const headerVerb = result.overwritten ? '上書き保存しました' : '生成しました';
+    return {
+      exitCode: 0,
+      output: [
+        `設計文書を${headerVerb}: ${result.targetPath}`,
+        `テンプレ: ${result.templatePath}`,
+        `Unit: ${result.unit} / phase: ${result.phase}`,
+        'TODO プレースホルダを実体で埋めてください。',
+      ].join('\n'),
+    };
+  }
+
+  private fail(
+    format: 'human' | 'json',
+    message: string,
+    exitCode: number,
+  ): ScaffoldDesignHandlerResult {
+    if (format === 'json') {
+      return {
+        exitCode,
+        output: JSON.stringify({ error: message }, null, 2),
+      };
+    }
+    return { exitCode, output: message };
+  }
+}

package/scripts/harness/harness-error/infrastructure/registry/l2-error-definitions.ts

@@ -44,7 +44,7 @@ export const L2_ERROR_DEFINITIONS = Object.freeze([
       "const requiredPlanPath = 'docs/inception/harness-error/it_test_logic_plan.md';",
     defaultSuggestedSkill: '/story-implementor',
     defaultScaffoldCommand: 'npx phasegate scaffold-design --unit <unit-id> --phase logical',
-    defaultTemplatePath: 'docs/templates/logical_design.template.md',
+    defaultTemplatePath: 'templates/logical_design.template.md',
   }),
   createDefinition({
     code: 'L2-002',

package/scripts/harness/main.ts

@@ -89,6 +89,7 @@ Commands:
   ci:migrate-agents-md         Migrate AGENTS.md (--dry-run, --validate-only, --json)
   ci:check-repetition          Check error repetition (--code <errorCode>, --reset, --json)
   baseline                     Create retrofit baseline snapshot (--dry-run, --force, --paths <glob,glob,...>, --json)
+  scaffold-design              Scaffold a design doc (--unit <id>, --phase <logical|domain|uiux|unit-test|it-test>, --force, --json)
 
   skill:execute-tdd-cycle      Execute TDD cycle (--unit, --story, --desc, --phase RED|GREEN|REFACTOR, --passed)
   skill:check-coverage         Check coverage (--story <storyId>, --json)
@@ -917,6 +918,23 @@ Examples:
         break;
       }
 
+      case 'scaffold-design': {
+        const mod = buildCiGovernance(rootDir, harnessRoot);
+        const unit = parseFlag(args, '--unit') ?? '';
+        const phase = parseFlag(args, '--phase') ?? '';
+        const force = hasFlag(args, '--force');
+        const format = json ? 'json' : 'human';
+        const result = await mod.scaffoldDesignHandler.handle({
+          unit,
+          phase,
+          force,
+          format,
+        });
+        console.log(result.output);
+        process.exit(result.exitCode);
+        break;
+      }
+
       // ── skill-quality ──
       case 'skill:execute-tdd-cycle': {
         const mod = createSkillQualityHandlers();

package/templates/domain_model.template.md

@@ -0,0 +1,51 @@
+---
+traceability:
+  initial_creation: true
+---
+
+# ドメインモデル: {{unit}}
+
+> **対応ストーリー**: <HXX-XX, HYY-YY>
+> **作成日**: <YYYY-MM-DD>
+> **Unit**: {{unit}}
+
+---
+
+## 集約 / エンティティ / 値オブジェクト
+
+@story-id <HXX-XX>
+### <集約名>
+
+**責務**: TODO: この集約が持つ責務
+
+**不変条件**:
+- TODO: 不変条件 1
+- TODO: 不変条件 2
+
+**関連**:
+- TODO: 他集約・エンティティへの参照
+
+---
+
+## ドメインサービス
+
+@story-id <HXX-XX>
+### <ドメインサービス名>
+
+**責務**: TODO: このサービスが担う domain ロジック
+
+**入出力**:
+- 入力: TODO
+- 出力: TODO
+
+---
+
+## ポート（依存反転インタフェース）
+
+@story-id <HXX-XX>
+### <Port 名>
+
+**役割**: TODO: domain が infrastructure に求める契約
+
+**メソッド**:
+- `methodName(arg: Type): ReturnType` — TODO

package/templates/it_test_design.template.md

@@ -0,0 +1,38 @@
+---
+traceability:
+  initial_creation: true
+---
+
+# IT（Integration）テスト設計: {{unit}}
+
+> **対応ストーリー**: <HXX-XX, HYY-YY>
+> **作成日**: <YYYY-MM-DD>
+> **Unit**: {{unit}}
+
+---
+
+## 結合スコープ
+
+- TODO: 結合対象（UseCase + Repository、Handler + UseCase など）
+- TODO: 外部依存（DB / API / FileSystem）の扱い
+
+---
+
+## テストケース一覧
+
+@story-id <HXX-XX>
+### IT-{{unit}}-001: <ケース名>
+
+**対象**: TODO: 結合対象
+**Arrange**: TODO: テンポラリ環境／フィクスチャ
+**Act**: TODO: 実行する操作
+**Assert**: TODO: 検証内容
+**副作用検証**: TODO: 書き込み/ログ等の副作用確認
+
+---
+
+## テスト環境
+
+- テンポラリディレクトリ: `fs.mkdtemp` ベース
+- ネットワーク: 禁止（外部 API は fake/stub）
+- クリーンアップ: afterEach で確実に破棄

package/templates/logical_design.template.md

@@ -3,17 +3,17 @@ traceability:
   initial_creation: true
 ---
 
-# 論理設計: <Unit名>
+# 論理設計: {{unit}}
 
 > **対応ストーリー**: <HXX-XX, HYY-YY>
 > **作成日**: <YYYY-MM-DD>
-> **Unit**: <UNIT_NAME>
+> **Unit**: {{unit}}
 
 ---
 
 ## 概要
 
-<このUnitが解決するビジネス課題を 2〜3 行で記述>
+TODO: Unit `{{unit}}` が解決するビジネス課題を 2〜3 行で記述
 
 ---
 
@@ -22,7 +22,7 @@ traceability:
 @story-id <HXX-XX>
 ### <集約 / エンティティ / 値オブジェクト名>
 
-<不変条件・責務・関連の説明>
+TODO: 不変条件・責務・関連の説明
 
 ---
 
@@ -36,13 +36,13 @@ traceability:
 **So that** <得られる価値>
 
 #### 事前条件
-- <前提>
+- TODO: 前提
 
 #### 基本フロー
-1. <ステップ>
+1. TODO: ステップ
 
 #### 例外フロー
-- <エラーケース>
+- TODO: エラーケース
 
 ---
 
@@ -74,6 +74,3 @@ presentation/    : CLI Handler / Controller
   - 直後に設計要素（空行を挟まない）
   - `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/uiux_design.template.md

@@ -0,0 +1,45 @@
+---
+traceability:
+  initial_creation: true
+---
+
+# UI/UX 設計: {{unit}}
+
+> **対応ストーリー**: <HXX-XX, HYY-YY>
+> **作成日**: <YYYY-MM-DD>
+> **Unit**: {{unit}}
+
+---
+
+## ユーザーフロー
+
+@story-id <HXX-XX>
+### <フロー名>
+
+1. TODO: ユーザー操作 1
+2. TODO: システム応答
+3. TODO: 画面遷移
+
+---
+
+## 画面構成
+
+@story-id <HXX-XX>
+### <画面名>
+
+**役割**: TODO: この画面が提供する価値
+
+**主要コンポーネント**:
+- TODO: コンポーネント 1
+- TODO: コンポーネント 2
+
+**状態**:
+- loading / success / error / empty
+
+---
+
+## アクセシビリティ
+
+- TODO: キーボード操作
+- TODO: スクリーンリーダ対応
+- TODO: カラーコントラスト

package/templates/unit_test_design.template.md

@@ -0,0 +1,39 @@
+---
+traceability:
+  initial_creation: true
+---
+
+# Unit テスト設計: {{unit}}
+
+> **対応ストーリー**: <HXX-XX, HYY-YY>
+> **作成日**: <YYYY-MM-DD>
+> **Unit**: {{unit}}
+
+---
+
+## テストケース一覧
+
+@story-id <HXX-XX>
+### UT-{{unit}}-001: <ケース名>
+
+**対象**: TODO: target クラス/関数
+**Arrange**: TODO: 前提条件セットアップ
+**Act**: TODO: 実行する操作
+**Assert**: TODO: 検証内容
+**期待結果**: TODO: 期待値
+
+---
+
+## カバレッジ方針
+
+- 分岐カバレッジ 90% 以上
+- ドメイン層のモック禁止
+- 値オブジェクトの不変条件は個別にテスト
+
+---
+
+## テスト命名規約
+
+- ケース名: 日本語で記述
+- ファイル名: kebab-case（例: `user-entity.test.ts`）
+- AAA パターン準拠