phasegate 0.146.0 → 0.148.0

package/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.147.0] - 2026-05-12
+
+### Added
+
+- **WI-144 — install/uninstall idempotency umbrella closure** — publish-ready rollup for the installation lifecycle work delivered across WI-145〜WI-148.
+  - Documents the complete lifecycle commands (`install`, `doctor`, `uninstall`, `reconcile`) in README / README.ja / guide docs.
+  - Marks the WI-144 umbrella as tested after the manifest, doctor, structured install, clean uninstall, reconcile, and init deprecation slices reached tested status.
+
 ## [0.145.4] - 2026-05-11
 
 ### Added

package/README.ja.md

@@ -18,7 +18,7 @@ Claude Code / Codex / Cursor / Copilot — どの AI agent でも設計意図・
 2. **コミット前に L1〜L3 のバリデーションが自動で走り**、レイヤー違反・テスト品質違反・依存方向違反を弾く
 3. **ブロック時のエラーは AI が読んで自己修正できる形式**（理由・必要な設計文書・次に打つべきスキル名が出る）
 
-`npx phasegate init` を 1 回打てば、上記が全部入ります。
+既存プロジェクトには `npx phasegate install` で既存 hooks / scripts を壊さずに組み込み、新規プロジェクトの legacy bootstrap には `npx phasegate init` を使います。導入後は `phasegate doctor` / `uninstall` / `reconcile` で状態確認・削除・アップグレード追従ができます。
 
 ---
 
@@ -77,7 +77,7 @@ claude
 > /product-architect
 ```
 
-`init` が生成するもの:
+`init` は初期 bootstrap として以下を生成します:
 
 - `phasegate.config.json` — 品質設定の Single Source of Truth
 - `skills/` — 28 の AIDLC スキル一式
@@ -95,7 +95,7 @@ claude
 - `docs/product/` 配下の確定設計文書 — `/domain-designer` `/logical-designer` 等が生成
 - `docs/ADR/` — `/skill-creator` や手動で必要に応じて作成
 
-「設計してから書け」を強制する仕組みなので、設計文書はユーザーがスキル経由で作るのが既定動作です。
+`init` は legacy 互換の bootstrap 経路です。既存 hooks / scripts / package metadata に構造化 merge したい場合は `install` を使います。「設計してから書け」を強制する仕組みなので、設計文書はユーザーがスキル経由で作るのが既定動作です。
 
 既存プロジェクトに導入する場合は、構造化 install で差分を確認してから適用します。
 
@@ -138,9 +138,12 @@ codex features enable codex_hooks   # Codex 本体の feature flag を手動で
 
 ```bash
 npm update phasegate
-npx phasegate update-skills   # スキルを最新版に再デプロイ
+npx phasegate reconcile --dry-run
+npx phasegate reconcile --apply
 ```
 
+`update-skills` は互換 alias として残っていますが、推奨は `reconcile` です。`.phasegate/manifest.json` に記録された PhaseGate 管理ファイル全体を最新版 template に追従できます。
+
 ---
 
 ## 主な機能
@@ -312,8 +315,12 @@ npx phasegate <command> [options]
 
 | コマンド | 説明 |
 |---|---|
-| `init --name <name>` | 初期化（skills/config/hooks 配置）。`--agent claude\|codex\|both`、`--with-husky`、`--with-ci`、`--preset <full\|standard\|minimal\|custom>` |
-| `update-skills` | スキルを最新版に再デプロイ |
+| `init --name <name>` | 新規プロジェクト向け legacy bootstrap（skills/config/hooks 配置）。既存 hooks/scripts/CI がある場合は `install` を推奨 |
+| `install --dry-run` / `--apply` | 既存設定を保持しながら PhaseGate を構造化 merge し、`.phasegate/manifest.json` を作成 |
+| `doctor` | silent / partial installation を診断し、修復 hint を表示（`--json`, `--strict`, `--report-out <path>`） |
+| `uninstall --dry-run` / `--apply` | manifest に基づいて PhaseGate 管理ファイル・管理 block を削除し、ユーザー設定は保持 |
+| `reconcile --dry-run` / `--apply` | 現在の package template に PhaseGate 管理ファイルを追従し、manifest hash を更新 |
+| `update-skills` | `reconcile` の互換 alias |
 | `lint` | L1 Biome AST チェック |
 | `validate --layer <L1\|L2\|L3\|L4\|all>` | 指定レイヤーのバリデータ実行（`--format human\|agent\|ci`） |
 | `ci-check` | CI フルチェック（L2-L4）。`--quick` で Quick Mode |

package/README.md

@@ -19,7 +19,7 @@ Phasegate adds project-local hooks, validators, and agent skills that keep gener
 2. **Before commit and CI, validators check layer boundaries, metadata, test quality, security, performance, and traceability.**
 3. **Every failure is returned in an agent-readable format** with the reason, missing artifacts, references, and the next skill or command to run.
 
-Run `npx phasegate init` once and the project gets the guardrails, skills, and configuration needed to make that flow repeatable.
+Run `npx phasegate install` to merge those guardrails into an existing project, or `npx phasegate init` for the legacy bootstrap path on a new project. `phasegate doctor`, `uninstall`, and `reconcile` keep the installation observable, removable, and upgradeable.
 
 ---
 
@@ -78,7 +78,7 @@ claude
 > /product-architect
 ```
 
-`init` creates:
+`init` creates the initial project-local harness files:
 
 - `phasegate.config.json` as the quality settings source of truth
 - `skills/` with 28 AIDLC skills
@@ -88,7 +88,7 @@ claude
 - `.husky/pre-commit`, `.husky/commit-msg`, and `.husky/pre-push` when `--with-husky` is passed
 - `.github/workflows/aidlc-gate.yml`, `.github/workflows/consistency-check.yml`, and `.github/workflows/agent-context-refresh.yml` when `--with-ci` is passed
 
-`init` intentionally does **not** create `docs/inception/` work item directories or `docs/product/` design documents. Those are produced later by skills such as `/product-architect`, `/domain-designer`, and `/logical-designer`. That is the core contract: no design, no code.
+`init` is the legacy-compatible bootstrap path. For idempotent setup with structured merge into existing hooks, scripts, and package metadata, use `install`. `init` intentionally does **not** create `docs/inception/` work item directories or `docs/product/` design documents. Those are produced later by skills such as `/product-architect`, `/domain-designer`, and `/logical-designer`. That is the core contract: no design, no code.
 
 For an existing project, preview and apply a structured install instead:
 
@@ -131,9 +131,12 @@ Use `--agent both` for projects that use Claude Code and Codex together. Codex n
 
 ```bash
 npm update phasegate
-npx phasegate update-skills
+npx phasegate reconcile --dry-run
+npx phasegate reconcile --apply
 ```
 
+`update-skills` remains available as a compatibility alias, but `reconcile` is the preferred upgrade path because it updates all PhaseGate-managed files recorded in `.phasegate/manifest.json`, not just skills.
+
 ---
 
 ## Core Capabilities
@@ -494,7 +497,11 @@ npx phasegate <command> [options]
 
 | Command | Description |
 |---|---|
-| `init --name <name>` | Initialize project, deploy skills, generate config. Use `--with-ci` to deploy GitHub Actions workflows. |
+| `init --name <name>` | Legacy-compatible bootstrap for new projects: deploy skills, generate config, and optionally add hooks/CI. Prefer `install` when the project may already have hooks, scripts, or CI files. |
+| `install --dry-run` / `--apply` | Idempotently merge PhaseGate into the current project, preserve existing user content, add package scripts/devDependency, and write `.phasegate/manifest.json`. |
+| `doctor` | Diagnose silent or partial installations and report repair hints (`--json`, `--strict`, `--report-out <path>`). |
+| `uninstall --dry-run` / `--apply` | Remove PhaseGate-managed files and managed blocks using `.phasegate/manifest.json`, preserving user content. |
+| `reconcile --dry-run` / `--apply` | Update PhaseGate-managed files to the current package templates and refresh manifest hashes. |
 | `lint` | Run L1 Biome AST checks |
 | `validate --layer <L1-L4\|all>` | Run validators for specified layer (`--layer L0` prints runtime hook guidance; explicit L4 runs even when scheduled L4 is disabled) |
 | `ci-check` | Full CI check (L2-L4; disabled L4 is reported as skipped) |
@@ -502,7 +509,7 @@ npx phasegate <command> [options]
 | `ci:auto-refresh-agent-context --dry-run` / `--apply` | Refresh AGENTS.md pointers and CLAUDE.md standard sections |
 | `refresh-claude-md --dry-run` / `--apply` | Refresh only CLAUDE.md while preserving the user-owned section |
 | `p2:check-agent-context` | Check AGENTS.md / CLAUDE.md freshness |
-| `update-skills` | Update skills to latest version |
+| `update-skills` | Compatibility alias for `reconcile` |
 | `phasegate:status` | Display overall harness health summary |
 | `work-items:status --dry-run` / `--apply` | Derive WI status from artifacts and optionally update stale `description.md` frontmatter. Apply refuses downgrades unless `--allow-downgrade` is supplied. |
 | `phasegate:check-phase --unit <id>` | Check current phase for a Unit |

package/docs/guide/cli-reference.md

@@ -12,8 +12,12 @@ npx phasegate <command> [options]
 
 | Command | Description |
 |---|---|
-| `init --name <name>` | Deploy skills and generate `phasegate.config.json` |
-| `update-skills` | Re-deploy skills to the latest version |
+| `init --name <name>` | Legacy-compatible bootstrap for new projects: deploy skills, generate config, and optionally add hooks/CI |
+| `install --dry-run` / `--apply` | Idempotently merge PhaseGate into an existing project, preserve user content, add package scripts/devDependency, and write `.phasegate/manifest.json` |
+| `doctor` | Diagnose silent or partial installations and report repair hints (`--json`, `--strict`, `--report-out <path>`) |
+| `uninstall --dry-run` / `--apply` | Remove PhaseGate-managed files and managed blocks using `.phasegate/manifest.json` |
+| `reconcile --dry-run` / `--apply` | Update PhaseGate-managed files to current package templates and refresh manifest hashes |
+| `update-skills` | Compatibility alias for `reconcile` |
 | `list-features` | List available features |
 | `enable-feature <name>` | Enable a feature |
 | `disable-feature <name>` | Disable a feature |

package/docs/guide/installation.md

@@ -6,7 +6,7 @@
 - **npm** 9+ or **pnpm**
 - **TypeScript** 5.x (included as a devDependency)
 
-## Install from GitHub
+## Install from npm
 
 ```bash
 npm install --save-dev phasegate
@@ -17,7 +17,7 @@ Or add it directly to your `package.json`:
 ```json
 {
   "devDependencies": {
-    "phasegate": "^0.145.3"
+    "phasegate": "^0.147.0"
   }
 }
 ```
@@ -38,6 +38,8 @@ npx phasegate init --name <project-name>
 
 This deploys 28 skills to `skills/`, creates the agent-facing skill links (for example `.claude/skills/` or `.codex/skills/`), and generates `phasegate.config.json`.
 
+`init` is the legacy-compatible bootstrap path for new projects. Use `install` when the project may already have hooks, package scripts, or CI files that should be preserved.
+
 For Codex, project initialization stops at the project boundary. After `npx phasegate init --agent codex`, enable the Codex CLI feature flag manually:
 
 ```bash
@@ -82,8 +84,6 @@ npx phasegate reconcile --apply
 
 `reconcile` updates PhaseGate-managed portions, preserves user content, adds newly introduced managed targets, and refreshes `.phasegate/manifest.json` with current version/hash metadata. If a managed file was edited after install, `reconcile --apply` refuses that entry until you rerun with `--force`, which creates a backup under `.phasegate/backups/reconcile-<timestamp>/`.
 
-`phasegate update-skills` remains available as a compatibility alias for `phasegate reconcile`.
-
 ### Manual Setup Pieces
 
 If you do not use `init` or `install`, copy the design principle documents manually:
@@ -110,9 +110,12 @@ Run `/product-architect` to begin the AIDLC process.
 
 ```bash
 npm update phasegate
-npx phasegate update-skills
+npx phasegate reconcile --dry-run
+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`.
+
 ## Recommended .gitignore additions
 
 ```

package/package.json

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

package/scripts/harness/biome-ast-engine/infrastructure/adapters/typescript-source-module-analyzer-adapter.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit biome-ast-engine
+ * @work-item-id WI-109
  */
 
 import * as ts from 'typescript';

package/scripts/harness/harness-api/domain/services/command-dispatch-service.ts

@@ -1,5 +1,6 @@
 // @layer domain
 // @unit harness-api
+// @work-item-id WI-108
 // command-dispatch-service.ts — CommandDispatchService Domain Service
 
 import { CommandRegistry } from './command-registry.js';

package/scripts/harness/integrations/pre-commit.ts

@@ -2,6 +2,7 @@
  * @unit harness-api
  * @layer presentation
  * @work-item-id WI-141
+ * @work-item-id WI-109
  *
  * Pre-commit CLI entry.
  * Runs L2 validators against staged TypeScript files AND design-document

package/scripts/harness/main.ts

@@ -1,6 +1,7 @@
 /**
  * @unit harness-api
  * @layer presentation
+ * @work-item-id WI-142
  *
  * Phasegate CLI エントリポイント。
  * 各Unitの Composition Root からハンドラーを取得し、コマンドに応じてディスパッチする。

package/scripts/harness/validator-system/application/use-cases/run-l1-validators-usecase.ts

@@ -4,6 +4,7 @@
  *
  * RunL1ValidatorsUseCase — H08-07/H08-08: L1バリデータ実行
  * L1-017 ITテスト内部モック検出、L1-018 スタブコメント残存検出を実行する。
+ * @work-item-id WI-110
  */
 import { ValidatorId } from '../../domain/value-objects/validator-id.js';
 import { ValidationResult } from '../../domain/value-objects/validation-result.js';

package/scripts/harness/validator-system/application/use-cases/run-l2-validators-usecase.ts

@@ -3,7 +3,7 @@
  * @unit validator-system
  *
  * RunL2ValidatorsUseCase — H08-01: L2バリデータ実行
- * @work-item-id WI-140
+ * @work-item-id WI-110 / WI-111 / WI-140
  */
 import { readFile } from 'node:fs/promises';
 import { ValidatorId, InvalidValidatorIdError } from '../../domain/value-objects/validator-id.js';

package/scripts/harness/validator-system/application/use-cases/run-l4-validators-usecase.ts

@@ -1,6 +1,7 @@
 /**
  * @layer application
  * @unit validator-system
+ * @work-item-id WI-107
  *
  * RunL4ValidatorsUseCase — H08-03: L4バリデータ実行
  */

package/scripts/harness/validator-system/composition-root.ts

@@ -3,6 +3,7 @@
  * @unit validator-system
  *
  * DI 組み立て — validator-system の全依存関係を構築する
+ * @work-item-id WI-110 / WI-111
  */
 import { ValidatorId } from './domain/value-objects/validator-id.js';
 import { ValidatorDefinition } from './domain/value-objects/validator-definition.js';

package/scripts/harness/validator-system/domain/ports/cli-command-registry-port.ts

@@ -1,6 +1,7 @@
 /**
  * @layer domain
  * @unit validator-system
+ * @work-item-id WI-111
  *
  * CliCommandRegistryPort — 登録済みCLIコマンド一覧取得ポート
  */
@@ -12,4 +13,4 @@ export interface CliCommandRegistryPort {
   getRegisteredCommands(): Promise<readonly string[]>;
 }
 
-// @story-id H08-07
+// @story-id H08-07

package/scripts/harness/validator-system/domain/ports/e2e-test-file-registry-port.ts

@@ -1,6 +1,7 @@
 /**
  * @layer domain
  * @unit validator-system
+ * @work-item-id WI-111
  *
  * E2eTestFileRegistryPort — E2Eテストファイル一覧取得ポート
  */
@@ -12,4 +13,4 @@ export interface E2eTestFileRegistryPort {
   getE2eTestFiles(): Promise<readonly string[]>;
 }
 
-// @story-id H08-07
+// @story-id H08-07

package/scripts/harness/validator-system/domain/services/cli-e2e-test-existence-service.ts

@@ -1,5 +1,6 @@
 // @unit validator-system
 // @layer domain
+// @work-item-id WI-111
 
 import { CliE2eTestCoverageReport, type CliCommandCoverageEntry } from '../value-objects/cli-e2e-test-coverage-report.js';
 

package/scripts/harness/validator-system/domain/value-objects/cli-e2e-test-coverage-report.ts

@@ -1,6 +1,7 @@
 /**
  * @layer domain
  * @unit validator-system
+ * @work-item-id WI-111
  *
  * CliE2eTestCoverageReport 値オブジェクト
  * CLIコマンド一覧とE2Eテストカバレッジ状況を表す不変値オブジェクト

package/scripts/harness/validator-system/infrastructure/adapters/cli-command-registry-adapter.ts

@@ -1,5 +1,6 @@
 // @unit validator-system
 // @layer infrastructure
+// @work-item-id WI-111
 
 import type { CliCommandRegistryPort } from '../../domain/ports/cli-command-registry-port.js';
 
@@ -19,4 +20,4 @@ export class CliCommandRegistryAdapter implements CliCommandRegistryPort {
   }
 }
 
-// @story-id H08-07
+// @story-id H08-07

package/scripts/harness/validator-system/infrastructure/adapters/e2e-test-file-registry-adapter.ts

@@ -1,6 +1,7 @@
 /**
  * @layer infrastructure
  * @unit validator-system
+ * @work-item-id WI-111
  *
  * E2eTestFileRegistryAdapter — E2eTestFileRegistryPort実装
  * E2Eテストファイルのパス一覧を提供する。