phasegate 0.31.0 → 0.39.0

package/README.md

@@ -48,17 +48,11 @@ npm install --save-dev phasegate
 npx phasegate init --name my-project
 ```
 
-This deploys 28 skills to `.claude/skills/` and generates `phasegate.config.json`.
+This deploys 28 skills, design principles docs (`docs/principles/*.md`, `docs/folder_management_rules.md`), and generates `phasegate.config.json`.
 
-### 3. Copy design principles
+Optional: add `--with-husky` to also install a `.husky/pre-commit` hook that runs L2 validators.
 
-```bash
-cp node_modules/phasegate/docs/folder_management_rules.md docs/
-mkdir -p docs/principles
-cp node_modules/phasegate/docs/principles/*.md docs/principles/
-```
-
-### 4. Start the AIDLC
+### 3. Start the AIDLC
 
 Launch your AI agent and run the `/product-architect` skill to begin.
 
@@ -275,6 +269,9 @@ npx phasegate <command> [options]
 | `phasegate:status` | Display overall harness health summary |
 | `phasegate:check-phase --unit <id>` | Check current phase for a Unit |
 | `list-errors --layer <L0-L4>` | List error definitions with fix examples |
+| `hook <pre-tool-use\|post-tool-use\|stop>` | Run a Claude Code hook (reads JSON from stdin) |
+| `pre-commit` | Run L2 pre-commit validators on staged files |
+| `delegate-sonnet [...args]` | Delegate task to Sonnet 4.6 (transparent wrapper) |
 
 See the [Japanese README](README.ja.md) for the complete CLI reference.
 
@@ -301,7 +298,7 @@ Additional resources:
 
 ## Contributing
 
-Contributions are welcome. Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before submitting a pull request.
+Contributions are welcome. See [DEVELOPMENT.md](DEVELOPMENT.md) for internal architecture, regression tests, and release procedures.
 
 ---
 
@@ -311,4 +308,4 @@ Contributions are welcome. Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
 
 ---
 
-[Japanese version / 日本語版](README.ja.md)
+[Japanese version / 日本語版](README.ja.md) | [Developer Guide](DEVELOPMENT.md) | [開発者ガイド](DEVELOPMENT.ja.md)

package/docs/folder_management_rules.md

@@ -0,0 +1,251 @@
+# docs ディレクトリ管理ガイド
+
+本ドキュメントは`docs/`配下のドキュメント管理方針を定義します。
+
+---
+
+## ディレクトリ構造
+
+```
+docs/
+├── ADR/                    # Architecture Decision Records
+├── basic_input/            # 入力サンプル・テンプレート
+├── principles/             # 開発原則・ルール
+├── inception/              # 計画ドキュメント + 作業単位（US・issue）の設計
+└── product/                # 共有設計ドキュメント（確定版）
+```
+
+---
+
+## 各ディレクトリの役割
+
+### ADR/
+アーキテクチャ決定記録。技術選定や設計方針の決定理由を記録する。
+
+### basic_input/
+入力データのサンプルやテンプレートを格納する。
+
+### principles/
+開発原則、テストルール、アーキテクチャ哲学など、プロジェクト全体で遵守すべきルールを定義する。
+
+### inception/
+**計画ドキュメント**と**作業単位（US・issue）の設計**を格納する。inception 配下のドキュメントは一時的な作業用であり、設計成果物は `product/` に反映される。
+
+```
+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
+```
+
+### product/
+**確定した設計ドキュメント**を格納する。作業単位（US-XXX / ISSUE-XXX）のドキュメントは含まない。
+
+> **設計思想（product docs ハブモデル）**:
+>
+> `product/` はUnit単位で確定済みの仕様を集約する **ハブ** である。
+>
+> ```
+> inception/{unit}/{作業単位}/   一時設計（US・issue ごと）
+>         ↓ 設計成果物の反映（累積更新）
+> product/construction/{unit}/   正式設計（常に最新、Unitの真実のソース）
+>         ↕ フェーズゲート
+> scripts/harness/{unit}/*.ts    実装ファイル
+> ```
+>
+> - **inception → product**: US・issue の設計成果が確定したら product docs を累積更新する
+> - **product → source**: ソースファイルのフェーズゲートは product docs（Unit単位）の存在で判定する
+> - **ソースファイルと US/issue は直接紐付けない**: PJ のライフサイクルが進むほどにバグ修正や US 追加で一つのソースファイルに紐づくドキュメント数が増大し、依存関係が複雑になるため。product docs が常に最新に保たれることで、inception の一時ドキュメントと実装が間接的に紐づく
+> - **US/issue 単位で正として管理しない**: 整合性維持のコストが非常に大きくなるため、作業単位の設計は inception にアーカイブ的に保持し、確定した仕様のみを product に集約する
+
+```
+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名}/` のドキュメントは累積更新される「生きたドキュメント」です。**
+> ストーリー実装のたびに、新しい仕様を既存ファイルに追記・更新します。
+
+---
+
+## 重要なルール
+
+### 1. productには作業単位（US・issue）の設計を入れない
+
+```
+# 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/
+```
+
+### 2. 仕様変更時は既存のproductドキュメントを更新する
+
+US 実装や issue 修正で仕様が確定したら、`product/`配下の既存ドキュメント（domain_model.md等）を累積更新する。新規ファイルを作成するのではなく、既存ファイルに変更を追記する。product docs は常に最新の状態を維持する「生きたドキュメント」である。
+
+### 3. ストーリー・issue単位の計画・設計は必ずinception配下に作成する
+
+```
+# 新しいストーリー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
+```
+
+---
+
+## ドキュメント作成フロー
+
+AIDLCプロセスは **US（新機能）** と **issue（バグ・不整合）** の2つの起点を持つ。いずれも inception で計画を立て、product docs を更新し、実装に反映する流れは共通である。
+
+### US と issue の違い
+
+| 起点 | フロー | inception 配置先 |
+|------|--------|-----------------|
+| **US（新機能）** | Phase 1 → Phase 2 → Phase 3 の全フローを上位から順に実行 | `inception/{unit}/{US-XXX}/` |
+| **issue（バグ・不整合）** | 原因フェーズを特定し、そのフェーズから下位に向けてドキュメント・実装をアップデート | `inception/{unit}/issues/{ISSUE-XXX}/` |
+
+#### issue の処理フロー
+
+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 実装**: テスト設計→実装の順序で修正を適用
+
+> **issue が既存仕様に存在しない追加機能であった場合**: issue ではなく **US を新規作成** し、unit へのマッピングからドメイン設計→TDD 実装まで、下記の Phase 1〜3 の全フローに沿って実施する。
+
+---
+
+### US のドキュメント作成フロー
+
+US は3つのフェーズで構成される。各フェーズでドキュメントの配置先が異なる。
+
+### Phase 1: プロダクト全体設計（横断的・初回）
+
+プロダクトの全体像を定義し、ストーリー・Unitの構造を確立する。
+
+| 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` |
+
+### Phase 2: Unit横断設計（Unit単位）
+
+各Unitの設計を確定させる。成果物は`product/construction/{unit}/`に配置される累積更新ドキュメント。
+
+| 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` |
+
+### Phase 3: ストーリー実装（US単位）/ issue 修正
+
+個別ストーリーの設計・テスト・実装。計画・成果物は`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}/` の各ドキュメントを更新 |
+
+> **uiux_design.mdについて**: 計画はストーリー単位（`inception/{unit}/{US-XXX}/`）に作成するが、
+> 成果物は`product/construction/{unit}/uiux_design.md`にUnit全体で1ファイルとして累積更新する。
+> これはUI/UXの全体一貫性を保つためで、他のproduct/construction配下のドキュメントと同じルールに従う。
+
+### 横断的な計画
+
+複数Unitにまたがる計画は `inception/_shared/` に作成する。
+
+### 運用関連
+
+デプロイ、IaC、運用手順は `inception/_operation/` に作成する。
+
+---
+
+## ファイル命名規則
+
+| 種別 | 命名パターン | 例 |
+|-----|------------|---|
+| issue記述 | `issue_description.md` | - |
+| 計画 | `*_plan.md` | `domain_model_plan.md` |
+| ドメインモデル | `domain_model.md` | - |
+| 論理設計 | `logical_design.md` | - |
+| UI/UX設計 | `uiux_design.md` | - |
+| シナリオテスト設計 | `scenario_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` |
+| 統合契約 | `integration_contract.md` | - |
+
+---
+
+## 関連ドキュメント
+- [アーキテクチャ哲学](./principles/architecture-philosophy.md)
+- [テストルール](./principles/testing-rules.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.31.0",
+  "version": "0.39.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",
@@ -31,11 +31,13 @@
     "!scripts/harness/__tests__/**",
     "scripts/harness/**/*.json",
     "!scripts/harness/__tests__/**/*.json",
+    "scripts/delegate-sonnet.sh",
     "skills/**",
     "templates/**",
     "docs/ADR/**",
     "docs/principles/**",
     "docs/guide/**",
+    "docs/folder_management_rules.md",
     "LICENSE",
     "CHANGELOG.md"
   ],
@@ -44,11 +46,11 @@
   },
   "scripts": {
     "phasegate": "npx tsx scripts/harness/main.ts",
-    "phasegate:status": "npx tsx scripts/harness/main.ts harness:status",
+    "phasegate:status": "npx tsx scripts/harness/main.ts phasegate:status",
     "phasegate:enable": "npx tsx scripts/harness/main.ts enable-feature",
     "phasegate:disable": "npx tsx scripts/harness/main.ts disable-feature",
-    "phasegate:check-phase": "npx tsx scripts/harness/main.ts harness:check-phase",
-    "phasegate:check-ready": "npx tsx scripts/harness/main.ts harness:check-ready",
+    "phasegate:check-phase": "npx tsx scripts/harness/main.ts phasegate:check-phase",
+    "phasegate:check-ready": "npx tsx scripts/harness/main.ts phasegate:check-ready",
     "test": "vitest run --config scripts/harness/__tests__/vitest.config.forks.ts && vitest run --config scripts/harness/__tests__/vitest.config.ts"
   },
   "dependencies": {

package/scripts/delegate-sonnet.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# delegate-sonnet.sh — Sonnet 4.6 にタスクを委任するラッパースクリプト
+#
+# Usage:
+#   bash scripts/delegate-sonnet.sh --prompt "プロンプト" --output "出力パス"
+#   bash scripts/delegate-sonnet.sh --prompt-file /tmp/prompt.md --output "出力パス"
+#
+# Options:
+#   --prompt        委任プロンプト（直接指定、2000文字以下推奨）
+#   --prompt-file   委任プロンプトファイル（長文の場合）
+#   --output        出力ファイルパス
+#   --max-turns     最大ターン数（デフォルト: 30）
+#   --dry-run       プロンプトを表示するだけで実行しない
+
+set -euo pipefail
+
+# --- 引数パース ---
+PROMPT=""
+PROMPT_FILE=""
+OUTPUT_PATH=""
+MAX_TURNS=30
+DRY_RUN=false
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --prompt)
+      PROMPT="$2"
+      shift 2
+      ;;
+    --prompt-file)
+      PROMPT_FILE="$2"
+      shift 2
+      ;;
+    --output)
+      OUTPUT_PATH="$2"
+      shift 2
+      ;;
+    --max-turns)
+      MAX_TURNS="$2"
+      shift 2
+      ;;
+    --dry-run)
+      DRY_RUN=true
+      shift
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# --- バリデーション ---
+if [[ -z "$PROMPT" && -z "$PROMPT_FILE" ]]; then
+  echo "Error: --prompt or --prompt-file is required" >&2
+  exit 1
+fi
+
+if [[ -z "$OUTPUT_PATH" ]]; then
+  echo "Error: --output is required" >&2
+  exit 1
+fi
+
+if [[ -n "$PROMPT_FILE" && ! -f "$PROMPT_FILE" ]]; then
+  echo "Error: Prompt file not found: $PROMPT_FILE" >&2
+  exit 1
+fi
+
+# --- プロンプト構築 ---
+if [[ -n "$PROMPT_FILE" ]]; then
+  FINAL_PROMPT=$(cat "$PROMPT_FILE")
+else
+  FINAL_PROMPT="$PROMPT"
+fi
+
+# 出力指示を付加
+FINAL_PROMPT="${FINAL_PROMPT}
+
+---
+## 出力制約
+- 出力は必ず ${OUTPUT_PATH} に書き出すこと
+- 出力以外のファイルを変更しないこと
+- 判断を含む作業（設計判断、優先順位決定、トレードオフ選択）は行わず、
+  展開・列挙・構造化に徹すること"
+
+# --- 実行 ---
+if [[ "$DRY_RUN" == "true" ]]; then
+  echo "=== DRY RUN ==="
+  echo "Model: claude-sonnet-4-6"
+  echo "Output: $OUTPUT_PATH"
+  echo "Max turns: $MAX_TURNS"
+  echo "---"
+  echo "$FINAL_PROMPT"
+  exit 0
+fi
+
+echo "[delegate-sonnet] Delegating to Sonnet 4.6..."
+echo "[delegate-sonnet] Output: $OUTPUT_PATH"
+
+claude --model claude-sonnet-4-6 \
+  -p "$FINAL_PROMPT" \
+  --max-turns "$MAX_TURNS" \
+  --output-format text
+
+echo "[delegate-sonnet] Done. Output written to: $OUTPUT_PATH"

package/scripts/harness/main.ts

@@ -29,10 +29,11 @@ import { buildCiGovernance } from './ci-governance/composition-root.js';
 import { createSkillQualityHandlers } from './skill-quality/composition-root.js';
 import { buildRegressionSuite } from './regression-suite/composition-root.js';
 import { buildPhase2Extensions } from './phase2-extensions/composition-root.js';
-import { deploySkills, deployHookScripts, getDeployedVersion, getHarnessVersion, initHarnessConfig, SKILL_CATEGORIES, getCategoryForSkill } from './setup/skill-deployer.js';
+import { deploySkills, deployHookScripts, getDeployedVersion, getHarnessVersion, initHarnessConfig, deployDesignDocs, deployHuskyHook, SKILL_CATEGORIES, getCategoryForSkill } from './setup/skill-deployer.js';
 import type { SkillSet } from './setup/skill-deployer.js';
 import type { HarnessConfigV2 } from './config-foundation/domain/harness-config.js';
 import { ConfigValidationError } from './config-foundation/domain/errors/config-validation-error.js';
+import { ConfigNotFoundError, ConfigPersistenceError } from './config-foundation/infrastructure/repositories/file-system-config-repository.js';
 
 /**
  * main.ts (scripts/harness/main.ts) から2階層上がパッケージルート。
@@ -51,8 +52,8 @@ function printUsage(): void {
 Usage: phasegate <command> [options]
 
 Setup:
-  init                         Initialize project: deploy skills + create phasegate.config.json
-                               (--name <project-name>, --preset <full|standard|minimal|custom>)
+  init                         Initialize project: deploy skills + design docs + phasegate.config.json
+                               (--name <project-name>, --preset <full|standard|minimal|custom>, --with-husky)
   update-skills                Re-deploy skills from current harness version
 
 Commands:
@@ -105,6 +106,9 @@ Commands:
   p2:check-freshness             Check doc freshness (--pattern <glob>, --dry-run, --format text|json)
   p2:validate-pointers           Validate doc pointers (--include-urls, --format text|json)
   p2:generate-e2e-template       Generate E2E test template (--phase <phase>, --output <path>)
+  hook <pre-tool-use|post-tool-use|stop>  Run Claude Code hook (reads JSON from stdin)
+  pre-commit                              Run L2 pre-commit validators on staged files
+  delegate-sonnet [...args]               Delegate task to Sonnet 4.6 (forwards args to scripts/delegate-sonnet.sh)
 
 Skills:
   skills list                  List all available skills
@@ -265,10 +269,22 @@ async function loadStoryReflectionProvider(
     };
     reporting?: { outputDir?: string };
   };
+  let content: string;
+  try {
+    content = await fsReadFile(configPath, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Warning: failed to read phasegate.config.json: ${message}\n`);
+    return null;
+  }
   try {
-    const content = await fsReadFile(configPath, 'utf8');
     raw = JSON.parse(content);
-  } catch {
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Warning: phasegate.config.json is not valid JSON: ${message}\n`);
     return null;
   }
   const section: PhaseDepConfigSection = {
@@ -325,7 +341,15 @@ async function loadResolvedConfig(): Promise<HarnessConfigV2 | undefined> {
       process.stderr.write(`Invalid phasegate.config.json: ${error.message}\n`);
       process.exit(2);
     }
-
+    if (error instanceof ConfigNotFoundError) {
+      return undefined;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof ConfigPersistenceError) {
+      process.stderr.write(`Warning: phasegate.config.json is not valid JSON: ${message}\n`);
+    } else {
+      process.stderr.write(`Warning: failed to load phasegate.config.json: ${message}\n`);
+    }
     return undefined;
   }
 }
@@ -379,6 +403,11 @@ async function main(): Promise<void> {
         const result = await deploySkills(harnessRoot, rootDir, skillSet);
         const configResult = await initHarnessConfig(rootDir, projectName, phasePreset);
         const hooksResult = await deployHookScripts(harnessRoot, rootDir);
+        const designDocsResult = await deployDesignDocs(harnessRoot, rootDir);
+        const withHusky = hasFlag(args, '--with-husky');
+        const huskyResult = withHusky
+          ? await deployHuskyHook(harnessRoot, rootDir)
+          : null;
         console.log(`✓ Skills deployed to ${result.targetDir} (${result.deployedSkills.length} skills, set: ${skillSet})`);
         if (configResult.created) {
           console.log(`✓ phasegate.config.json created`);
@@ -393,6 +422,19 @@ async function main(): Promise<void> {
         } else if (hooksResult.scriptsDeployed > 0) {
           console.log(`  .claude/settings.json already exists, skipped`);
         }
+        if (designDocsResult.copiedFiles.length > 0) {
+          console.log(`✓ Design docs deployed (${designDocsResult.copiedFiles.length} files)`);
+        }
+        for (const skipped of designDocsResult.skippedFiles) {
+          console.log(`  ${skipped} already exists, skipped`);
+        }
+        if (huskyResult !== null) {
+          if (huskyResult.created) {
+            console.log(`✓ .husky/pre-commit deployed`);
+          } else {
+            console.log(`  .husky/pre-commit already exists, skipped`);
+          }
+        }
         console.log(`✓ Harness v${result.version} initialized`);
         console.log('');
         console.log('Next steps:');
@@ -685,7 +727,7 @@ async function main(): Promise<void> {
         const flags: Record<string, boolean | string> = {};
         if (json) flags.json = true;
         await mod.handlers.status.handle({}, flags);
-        await printStoryReflectionStatusLine(rootDir);
+        if (!json) await printStoryReflectionStatusLine(rootDir);
         break;
       }
 
@@ -914,6 +956,49 @@ async function main(): Promise<void> {
         break;
       }
 
+      // ── agent integration / hooks ──
+      case 'hook': {
+        const subCommand = args[1];
+        if (!subCommand) {
+          console.error('Usage: phasegate hook <pre-tool-use|post-tool-use|stop>');
+          process.exit(2);
+        }
+        const hookFileName: Record<string, string> = {
+          'pre-tool-use': 'pre-tool-use-hook.js',
+          'post-tool-use': 'post-tool-use-hook.js',
+          'stop': 'stop-hook.js',
+        };
+        const fileName = hookFileName[subCommand];
+        if (!fileName) {
+          console.error(`Unknown hook subcommand: ${subCommand}`);
+          console.error('Usage: phasegate hook <pre-tool-use|post-tool-use|stop>');
+          process.exit(2);
+        }
+        const hookPath = join(harnessRoot, 'scripts/harness/agent-integration/presentation', fileName);
+        await import(hookPath);
+        break;
+      }
+
+      case 'pre-commit': {
+        const preCommitPath = join(harnessRoot, 'scripts/harness/integrations/pre-commit.js');
+        await import(preCommitPath);
+        break;
+      }
+
+      case 'delegate-sonnet': {
+        const { spawn } = await import('node:child_process');
+        const scriptPath = join(harnessRoot, 'scripts/delegate-sonnet.sh');
+        const forwardArgs = args.slice(1);
+        const child = spawn('bash', [scriptPath, ...forwardArgs], { stdio: 'inherit' });
+        await new Promise<void>((_, reject) => {
+          child.on('exit', (code) => {
+            process.exit(code ?? 1);
+          });
+          child.on('error', reject);
+        });
+        break;
+      }
+
       // ── skills ──
       case 'skills': {
         const subCommand = args[1];