phasegate 0.152.5 → 0.152.6

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.152.6] - 2026-05-13
+
+### Changed
+
+- **WI-152 / WI-153 / WI-154 / WI-157 / WI-169 — setup lifecycle documentation refresh** — adds the setup artifact inventory, aligns installation product construction docs with the current doctor/install/reconcile contract, refreshes bundled setup guidance skills, and modernizes developer skill documentation before publish prep.
+
 ## [0.152.3] - 2026-05-12
 
 ### Fixed

package/docs/guide/cli-reference.md

@@ -391,7 +391,7 @@ ISSUE-005 P3-10 で明確化された境界:
 
 | Command | Options | Description |
 |---|---|---|
-| `hooks:config validate` | | Validate `.harness-hooks.yml` |
+| `hooks:config validate` | | Compatibility validator for legacy `.harness-hooks.yml`; new setup should use `install`, `doctor`, `reconcile`, `lint`, and `validate` |
 | `hooks:gate-check` | `--story <id>` | Completion gate check |
 
 ---

package/docs/guide/configuration.md

@@ -6,6 +6,8 @@ Place at project root. Generated by `npx phasegate init`.
 
 This file is the **Single Source of Truth** for all quality configuration in a Phasegate project. Every layer validator, skill, and harness behavior reads from this file.
 
+It is not the whole setup state. Hook JSON, Husky scripts, CI workflow files, skill links, `.phasegate/manifest.json`, runtime reports, and Codex user-level feature flags are tracked separately. Use [Setup Artifacts](setup-artifacts.md) when auditing whether a project is fully installed. <!-- @work-item-id WI-152 -->
+
 ### Full Reference
 
 ```jsonc

package/docs/guide/hooks-integration.md

@@ -4,6 +4,8 @@ Phasegate integrates natively with Claude Code through its hooks system. This en
 
 ## Setup
 
+For new or existing projects, prefer `npx phasegate install --dry-run` followed by `npx phasegate install --apply` so existing hook JSON is merged instead of replaced. Manual editing is still possible, but then `phasegate doctor` may report missing managed targets until the expected PhaseGate entries, skill links, Husky scripts, CI workflow, and manifest are present. See [Setup Artifacts](setup-artifacts.md). <!-- @work-item-id WI-152 --> <!-- @work-item-id WI-169 -->
+
 Add the following to `.claude/settings.json`:
 
 ```jsonc
@@ -130,3 +132,5 @@ Additional hooks can be placed in `.claude/scripts/`:
 | targetDirs | Directories where hooks apply (relative to project root) | [] (skip if empty) |
 | formatter | "biome" or "eslint-prettier" | "biome" |
 | formatterArgs | Arguments passed to formatter | ["check", "--write"] |
+
+Legacy `.harness-hooks.yml` and old Fuse hook files are not part of the current install lifecycle. Keep them only for archived integrations; new setup should use `install`, `doctor`, `reconcile`, `lint`, and `validate`. <!-- @work-item-id WI-157 -->

package/docs/guide/installation.md

@@ -17,7 +17,7 @@ Or add it directly to your `package.json`:
 ```json
 {
   "devDependencies": {
-    "phasegate": "^0.147.0"
+    "phasegate": "^0.152.6"
   }
 }
 ```
@@ -56,7 +56,7 @@ npx phasegate install --apply
 npx phasegate doctor
 ```
 
-`install --dry-run` reports whether each target will be created, merged, skipped, or refused. `install --apply` performs the merge, adds package scripts and the `phasegate` devDependency, creates `.claude/skills` and `.codex/skills` links, writes the CI workflow when missing, and records managed entries in `.phasegate/manifest.json`.
+`install --dry-run` reports whether each target will be created, merged, skipped, or refused. `install --apply` performs the merge, adds package scripts and the `phasegate` devDependency, creates `.claude/skills` and `.codex/skills` links, writes `.github/workflows/phasegate-aidlc-gate.yml` when CI is enabled, and records managed entries in `.phasegate/manifest.json`. See [Setup Artifacts](setup-artifacts.md) for the full managed target, generated artifact, runtime state, legacy artifact, and user-level setting inventory. <!-- @work-item-id WI-152 --> <!-- @work-item-id WI-169 -->
 
 If a managed update must replace existing custom content, use:
 
@@ -116,6 +116,8 @@ npx phasegate reconcile --apply
 
 `phasegate update-skills` remains available as a compatibility alias, but `reconcile` is the preferred upgrade path because it updates all managed files recorded in `.phasegate/manifest.json`.
 
+`doctor --report-out <path>` writes exactly to the provided path. `.phasegate/last-doctor-report.json` is not a fixed output file unless you choose that path explicitly. <!-- @work-item-id WI-152 -->
+
 ## Recommended .gitignore additions
 
 ```

package/docs/guide/setup-artifacts.md

@@ -0,0 +1,60 @@
+# Setup Artifacts
+
+PhaseGate setup is more than `phasegate.config.json`. A healthy installation is the combination of project configuration, managed targets, generated state, runtime reports, and a small number of user-level settings.
+
+<!-- @work-item-id WI-152 -->
+<!-- @work-item-id WI-157 -->
+<!-- @work-item-id WI-169 -->
+
+## Artifact Classes
+
+| Class | Examples | Owner | Lifecycle |
+|---|---|---|---|
+| Managed target | `.claude/settings.json`, `.codex/hooks.json`, `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`, `.github/workflows/phasegate-aidlc-gate.yml`, `.claude/skills`, `.codex/skills`, `package.json` PhaseGate scripts/devDependency | PhaseGate managed block or symlink plus user content | Created or merged by `install`, refreshed by `reconcile`, removed or reversed by `uninstall` |
+| Configuration | `phasegate.config.json`, `package.json` | User owned, PhaseGate assisted | Created by `init`; `install` may merge scripts/devDependency into `package.json` |
+| Generated artifact | `.phasegate/manifest.json`, `.phasegate/backups/*`, `.phasegate/uninstalled-*.json`, `.phasegate/baseline.json` | PhaseGate | Written by lifecycle commands and validators; safe to regenerate only through the owning command |
+| Runtime state/report | `.phasegate/hook-skip-events.jsonl`, explicit `doctor --report-out <path>` output, `reports/regression/*`, resolved `reporting.outputDir` reports | PhaseGate command output | Produced while hooks, doctor, and validation commands run |
+| Legacy artifact | `.harness-hooks.yml`, old Fuse hook files, `.harness/session-state.json`, `.harness/context-priority.json`, `.harness/reports` fallback | Compatibility only | Not required for current install lifecycle unless a project intentionally keeps an archived integration |
+| User-level setting | Codex CLI `codex_hooks` feature flag | User machine | Must be enabled manually with `codex features enable codex_hooks`; project commands do not modify it |
+
+## Managed Targets
+
+`install --apply` and `reconcile --apply` manage only explicit targets. The current structured lifecycle covers:
+
+- Agent hook JSON: `.claude/settings.json`, `.codex/hooks.json`
+- Husky scripts when requested: `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`
+- CI workflow when requested: `.github/workflows/phasegate-aidlc-gate.yml`
+- Agent skill links: `.claude/skills`, `.codex/skills`
+- Package metadata: PhaseGate scripts and `devDependencies.phasegate` in `package.json`
+- Manifest: `.phasegate/manifest.json`
+
+`init --with-ci` still deploys the legacy-compatible template set, including `.github/workflows/aidlc-gate.yml`, `.github/workflows/consistency-check.yml`, and `.github/workflows/agent-context-refresh.yml`. Structured `install` uses `.github/workflows/phasegate-aidlc-gate.yml` so it can coexist with existing project CI without taking over a generic workflow filename.
+
+## Doctor Findings
+
+`phasegate doctor` evaluates setup health from the managed targets and related project state. Findings include `repairMode`, optional `repairHint`, and optional `suggestedSkill`.
+
+| Field | Meaning |
+|---|---|
+| `repairMode: "mechanical"` | A PhaseGate command can usually fix the target, for example `npx phasegate install --apply` or `--force`. |
+| `repairMode: "ai-assisted"` | Existing user content needs judgment before merging. Doctor includes `suggestedSkill`, usually `phasegate-config-doctor`. |
+| `repairMode: "manual"` | Human review is required, commonly for semantic CI/workflow conflicts. |
+| `repairHint` | Copyable command for mechanical cases. |
+| `suggestedSkill` | Skill name, rationale, and invoke command for agent-assisted repair planning. |
+
+`doctor --report-out <path>` writes exactly to the path you pass. `.phasegate/last-doctor-report.json` is not created automatically; it is only a conventional path you may choose.
+
+## Reports And Runtime Files
+
+`reporting.outputDir` is the default project-visible report directory for phase dependency and phase-gate reports. Some command families have their own contracts:
+
+- `doctor --report-out <path>` writes to the explicit path only.
+- `regression:*` commands write under `reports/regression/`.
+- `.harness/reports` is a legacy fallback used only when a phase-dependency provider cannot resolve project config.
+- `.phasegate/hook-skip-events.jsonl` records hook bypass/skip observations for diagnosis; it is runtime state, not a managed install target.
+
+## Legacy Retirement
+
+Current setup does not require `.harness-hooks.yml`, old Fuse hook files, `.harness/session-state.json`, or `.harness/context-priority.json`. Treat them as project-local compatibility artifacts. Before deleting them, check whether an archived workflow or local script still references them; otherwise prefer documenting them as retired rather than wiring new guidance around them.
+
+`hooks:config validate` is a compatibility command for old `.harness-hooks.yml` projects. New setup should use `install`, `doctor`, `reconcile`, `lint`, and `validate`.

package/package.json

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

package/skills/README.md

@@ -1,21 +1,21 @@
 # Skills ディレクトリ
 
-このディレクトリには、AIエージェントの共有スキル定義が含まれています。
+このディレクトリには、AIエージェントの共有スキル定義が含まれています。現在の配布対象は 30 skills です。公開一覧は `docs/guide/skills-overview.md`、setup lifecycle の管理対象は `docs/guide/setup-artifacts.md` を正とします。<!-- @work-item-id WI-154 -->
 
 ## ディレクトリ構成と同期
 
 このディレクトリはスキルの**唯一の信頼できる情報源 (Single Source of Truth)** です。
-`.agent` と `.claude` の両方の環境から同じスキルにアクセスできるように、各ディレクトリには以下のようなシンボリックリンクが作成されています：
+`.claude` と `.codex` の両方の環境から同じスキルにアクセスできるように、`phasegate install` / `phasegate reconcile` は必要に応じて以下のシンボリックリンクを管理します：
 
-- `.agent/skills` -> `./skills` (プロジェクトルートからの相対パス)
 - `.claude/skills` -> `./skills` (プロジェクトルートからの相対パス)
 - `.codex/skills` -> `./skills` (プロジェクトルートからの相対パス)
 
 技術的には、リンクは以下のように設定されています：
-- `.agent/skills` -> `../skills`
 - `.claude/skills` -> `../skills`
 - `.codex/skills` -> `../skills`
 
+`.agent/skills` は旧 setup 由来の互換パスです。新規導入では管理対象にしません。<!-- @work-item-id WI-157 -->
+
 ## 新しいスキルの追加
 
-新しいスキルを追加する場合は、この `skills` ディレクトリに直接追加してください。シンボリックリンクを通じて、両方のエージェントから自動的に利用可能になります。
+新しいスキルを追加する場合は、この `skills` ディレクトリに直接追加してください。あわせて `docs/guide/skills-overview.md`、README の skill 数、必要なら `skills/phasegate-toolkit-guide/SKILL.md` の参照先を更新します。シンボリックリンクを通じて、対応エージェントから利用可能になります。<!-- @work-item-id WI-154 -->

package/skills/phasegate-config-doctor/SKILL.md

@@ -9,7 +9,7 @@ description: 現在の phasegate.config.json を schema + プロジェクト検
 
 ## このスキルが解決する問題
 
-phasegate を導入した直後の config は単純な default で、実プロジェクトの構造 (monorepo / formatter 選定 / architecture style / Quick Mode の運用方針) に最適化されていない。AI が schema を知らずに勘で書き換えると壊れるため、**schema + 検出結果に基づいた決定的提案** が必要。
+phasegate を導入した直後の config は単純な default で、実プロジェクトの構造 (monorepo / formatter 選定 / architecture style / Quick Mode の運用方針) に最適化されていない。さらに setup lifecycle は `phasegate.config.json` だけでは完結せず、manifest、hook JSON、Husky、CI、skill link、doctor finding を合わせて読む必要がある。AI が schema や setup contract を知らずに勘で書き換えると壊れるため、**schema + 検出結果に基づいた決定的提案** が必要。<!-- @work-item-id WI-153 -->
 
 ## 設計原則
 
@@ -18,7 +18,7 @@ phasegate を導入した直後の config は単純な default で、実プロ
 3. **AI 推論は判断要素のみ** — architecture preset 選定、relaxedGates 推奨値などは AI が判断するが根拠を必ず示す
 4. **schema は enum 違反確認時のみ Read** — 日常診断は本 SKILL 内の判定基準で十分。schema 全文 Read は値域不明時に限定する
 5. **read-only な Q&A は phasegate-toolkit-guide に委譲** — 「L2 って何？」など概念質問は本 skill スコープ外
-6. **変更後は L2 検証必須** — `npx phasegate validate --layer L2` を走らせてからユーザーに完了報告
+6. **変更後は対象別に検証** — config 変更は `npx phasegate validate --layer L2`、setup lifecycle 変更は `npx phasegate doctor`、hook/script/metadata 変更は `npx phasegate lint` または `npm run phasegate:check-ready` を走らせてからユーザーに完了報告
 
 ## 診断プロセス
 
@@ -33,11 +33,19 @@ phasegate を導入した直後の config は単純な default で、実プロ
 | pnpm workspace | `pnpm-workspace.yaml` (存在すれば) | workspace 検出 |
 | lerna config | `lerna.json` (存在すれば) | workspace 検出 |
 | hook config | `.claude/scripts/hook-config.json` | 既存 hook 設定確認 |
+| doctor report | 明示された report path、またはユーザーが指定した `.phasegate/last-doctor-report.json` | `repairMode` / `repairHint` / `suggestedSkill` の確認 |
+| manifest | `.phasegate/manifest.json` | install / reconcile / uninstall の managed target と hash 状態確認 |
+| Claude hooks | `.claude/settings.json` | managed hook JSON と user customization の確認 |
+| Codex hooks | `.codex/hooks.json` | managed hook JSON と Codex hook 配線確認 |
+| Husky scripts | `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push` | pre-commit backstop と bypass audit の確認 |
+| CI workflows | `.github/workflows/*` | `phasegate-aidlc-gate.yml` や既存 workflow との競合確認 |
 
 **schema は必要なときだけ Read** (enum 違反疑い時など): `node_modules/phasegate/scripts/harness/config-foundation/infrastructure/schemas/harness-config-v3.schema.json` (or `harness-config-v2.schema.json` if v2)。
 
 phasegate リポジトリ自体 (dogfood) の場合は `node_modules/phasegate/` を `scripts/harness/config-foundation/...` に置換。
 
+`doctor --report-out <path>` は指定された path にだけ書く。`.phasegate/last-doctor-report.json` は固定生成物ではないため、存在しない場合は `npx phasegate doctor --json` を実行して現状を読み取る。<!-- @work-item-id WI-152 -->
+
 ### Step 1.5: Fresh init 判定 (重要)
 
 以下の **全条件** を満たす場合、フル診断は早期。Step 2 に進まず AIDLC 開始を案内する:
@@ -115,6 +123,15 @@ product-architect で Unit を作り、いくつかの logical_design を書い
 - `formatter: "biome"` だが `@biomejs/biome` が devDependencies に無い → WARN: prettier に切り替え推奨
 - v0.119 未満で deploy された hook script (bash 4 `mapfile` 使用) → WARN: macOS の bash 3.2 で silent fail。`phasegate init` 再実行で更新
 
+#### 観点 9: setup lifecycle と doctor finding
+
+- `phasegate doctor --json` の finding に `repairMode: "ai-assisted"` と `suggestedSkill.skillName = "phasegate-config-doctor"` がある → 本 skill が merge 方針、保持する user content、実行すべき `install --apply` / `--force` / `reconcile --apply` を提案する
+- `repairHint` がある mechanical finding → 原則として hint のコマンドを優先し、実行前に対象ファイルと manifest の差分を確認
+- manifest parse error → `.phasegate/manifest.json` を手で修復する前に backup / uninstall / reinstall の選択肢を提示
+- reconcile / uninstall が refuse → user modified managed target として扱い、`--force` のリスクと backup path を説明して承認を取る
+- Codex の `codex_hooks` feature flag は user-level setting。project-local `install` では変更されないため、必要なら `codex features enable codex_hooks` を案内
+- Codex native `apply_patch` bypass は hook で完全捕捉できない。`.husky/pre-commit` の `phasegate pre-commit` が backstop になるため、Husky 配線を診断対象に含める
+
 ### Step 3: 診断レポート
 
 診断結果を以下の形式で提示する:
@@ -179,13 +196,21 @@ options:
 
 ユーザーが適用対象を確定したら `Edit` で `phasegate.config.json` を変更。
 
-**変更後の必須検証**:
+**変更後の検証**:
 
 ```bash
 npx phasegate validate --layer L2
 ```
 
-L2 でエラーが出た場合は変更を **rollback** し、ユーザーに報告 (silent に進めない)。
+setup target を触った場合は以下も使い分ける:
+
+```bash
+npx phasegate doctor
+npx phasegate lint
+npm run phasegate:check-ready
+```
+
+検証でエラーが出た場合は変更を **rollback** し、ユーザーに報告 (silent に進めない)。
 
 ## phasegate-toolkit-guide との使い分け
 

package/skills/phasegate-toolkit-guide/SKILL.md

@@ -119,10 +119,15 @@ docs/guide/                          # phasegate リポジトリ自体 (dogfood)
 - 「phasegate のインストール方法は？」
 - 「monorepo で使うときは？」
 - 「既存プロジェクトに後から導入したい」
+- 「doctor の repairMode / suggestedSkill って何？」
+- 「.phasegate/manifest.json や hook-skip-events は何？」
 
 **参照先**:
 - 新規導入: `docs/guide/installation.md`
 - 既存プロジェクト導入: `docs/guide/retrofit-adoption.md`
+- setup artifact / doctor finding / legacy artifact: `docs/guide/setup-artifacts.md`
+
+`setup-artifacts.md` は managed target / generated artifact / runtime state / legacy artifact / user-level setting の分類を持つ。`doctor --report-out` は明示 path への出力で、`.phasegate/last-doctor-report.json` は固定生成物ではない点もここを参照する。<!-- @work-item-id WI-153 -->
 
 ### 8. skill 一覧と使い分け