phasegate 0.145.1 → 0.145.3

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.145.3] - 2026-05-11
+
+### Added
+
+- **WI-147 — manifest-driven uninstall** — `phasegate uninstall --dry-run|--apply [--force] [--json]` を追加し、`.phasegate/manifest.json` に記録された managed files を clean removal できるようにした。
+  - `created` / `symlink` entries は削除し、JSON / shell / `package.json` の `merged` entries は PhaseGate managed portion だけを除去して user content を保持する。
+  - hash mismatch は `--force` 無しで refuse し、force 時は `.phasegate/backups/uninstall-*/` に snapshot を保存してから削除する。
+  - uninstall 完了後、manifest は `.phasegate/uninstalled-*.json` に archive される。
+
+## [0.145.2] - 2026-05-11
+
+### Added
+
+- **WI-146 — structured install** — `phasegate install --dry-run|--apply [--force] [--json]` を追加し、既存設定を preserve しながら Claude / Codex hooks、Husky hooks、CI workflow、package scripts/devDependency、skills link、manifest entries を構造化 merge できるようにした。
+  - 既存カスタム hook は既定では拒否し、`--force` 時は `.phasegate/backups/` に退避してから managed block を適用する。
+
 ## [0.145.1] - 2026-05-11
 
 ### Fixed

package/README.ja.md

@@ -69,7 +69,7 @@ Node.js >= 18, npm >= 9, TypeScript 5.x
 # 1. インストール
 npm install --save-dev phasegate
 
-# 2. プロジェクトを初期化
+# 2. 新規プロジェクトを初期化
 npx phasegate init --name my-project --with-husky --with-ci
 
 # 3. AI agent を起動して /product-architect から始める
@@ -97,6 +97,25 @@ claude
 
 「設計してから書け」を強制する仕組みなので、設計文書はユーザーがスキル経由で作るのが既定動作です。
 
+既存プロジェクトに導入する場合は、構造化 install で差分を確認してから適用します。
+
+```bash
+npx phasegate install --dry-run
+npx phasegate install --apply
+npx phasegate doctor
+```
+
+`install` は既存の Claude / Codex hooks や Husky script を捨てずに PhaseGate の設定を merge します。書き込み前に変更予定を表示し、package scripts と `phasegate` devDependency、agent skill symlink、未作成の CI workflow、`.phasegate/manifest.json` を整えます。強制的な managed 更新が必要な場合は `npx phasegate install --apply --force` を使います。この場合、置き換え対象は `.phasegate/backups/` に退避されます。
+
+後で PhaseGate を外す場合は、manifest ベースの uninstall を使います。
+
+```bash
+npx phasegate uninstall --dry-run
+npx phasegate uninstall --apply
+```
+
+`uninstall` は manifest を読んで、PhaseGate が作成したファイルを削除し、merge した Claude / Codex / Husky / `package.json` から PhaseGate 管理部分だけを取り除きます。ユーザーの既存設定は保持し、manifest は `.phasegate/` 配下に履歴として archive します。
+
 ### Codex CLI を使う場合
 
 ```bash

package/README.md

@@ -70,7 +70,7 @@ Node.js >= 18, npm >= 9, TypeScript 5.x
 # 1. Install
 npm install --save-dev phasegate
 
-# 2. Initialize the project
+# 2. Initialize a new project
 npx phasegate init --name my-project --with-husky --with-ci
 
 # 3. Start your AI agent and begin with product design
@@ -90,6 +90,25 @@ claude
 
 `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:
+
+```bash
+npx phasegate install --dry-run
+npx phasegate install --apply
+npx phasegate doctor
+```
+
+`install` merges PhaseGate into the current project without discarding existing Claude/Codex hooks or Husky scripts. It reports planned changes before writing, adds package scripts and the `phasegate` devDependency, creates agent skill links, writes the CI workflow when missing, and records managed files in `.phasegate/manifest.json`. If an existing file needs a forced managed update, run `npx phasegate install --apply --force`; PhaseGate backs up replaced files under `.phasegate/backups/`.
+
+To remove PhaseGate from that project later, run:
+
+```bash
+npx phasegate uninstall --dry-run
+npx phasegate uninstall --apply
+```
+
+`uninstall` uses the manifest to delete created files and remove only PhaseGate-managed portions from merged Claude/Codex, Husky, and `package.json` files. User content is preserved, and the manifest is archived under `.phasegate/`.
+
 ### Codex CLI
 
 ```bash

package/docs/guide/installation.md

@@ -17,7 +17,7 @@ Or add it directly to your `package.json`:
 ```json
 {
   "devDependencies": {
-    "phasegate": "^0.14.0"
+    "phasegate": "^0.145.3"
   }
 }
 ```
@@ -30,7 +30,7 @@ npm install
 
 ## Project Setup
 
-### 1. Initialize
+### New Projects
 
 ```bash
 npx phasegate init --name <project-name>
@@ -44,7 +44,38 @@ For Codex, project initialization stops at the project boundary. After `npx phas
 codex features enable codex_hooks
 ```
 
-### 2. Copy design principle documents
+### Existing Projects
+
+Use `install` when the project already has package scripts, hooks, or CI files that should be preserved.
+
+```bash
+npx phasegate install --dry-run
+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`.
+
+If a managed update must replace existing custom content, use:
+
+```bash
+npx phasegate install --apply --force
+```
+
+Forced updates write backups under `.phasegate/backups/<timestamp>/` before applying changes.
+
+To remove PhaseGate-managed files later, preview and apply uninstall:
+
+```bash
+npx phasegate uninstall --dry-run
+npx phasegate uninstall --apply
+```
+
+`uninstall` reads `.phasegate/manifest.json`, deletes files that PhaseGate created, removes only PhaseGate-managed portions from merged JSON, Husky, and `package.json` files, and archives the manifest as `.phasegate/uninstalled-<timestamp>.json`. If a managed file was modified after install, `uninstall --apply` refuses that entry until you rerun with `--force`, which creates a backup under `.phasegate/backups/uninstall-<timestamp>/`.
+
+### Manual Setup Pieces
+
+If you do not use `init` or `install`, copy the design principle documents manually:
 
 ```bash
 cp node_modules/phasegate/docs/folder_management_rules.md docs/
@@ -52,11 +83,11 @@ mkdir -p docs/principles
 cp node_modules/phasegate/docs/principles/*.md docs/principles/
 ```
 
-### 3. Create product overview
+### Create product overview
 
 Create `docs/product/<your_product>_overview.md` as the starting point for AIDLC.
 
-### 4. Start Claude Code
+### Start Claude Code
 
 ```bash
 claude  # at project root
@@ -88,5 +119,6 @@ reports/
 ```bash
 npx phasegate --version
 npx phasegate lint
-npm run phasegate:status
+npx phasegate doctor
+npm run phasegate:check-ready
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.145.1",
+  "version": "0.145.3",
   "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/installation/application/ports/file-inspector-port.ts

@@ -2,10 +2,6 @@
 // @layer application
 // @work-item-id WI-145
 
-export interface FileInspectorPort {
-  exists(absolutePath: string): Promise<boolean>;
-  readText(absolutePath: string): Promise<string | null>;
-  readJson<T = unknown>(absolutePath: string): Promise<T | null>;
-  readSymlink(absolutePath: string): Promise<string | null>;
-  listFiles(absolutePath: string): Promise<string[]>;
-}
+import type { FileInspector } from "../../domain/ports/file-inspector.js";
+
+export type FileInspectorPort = FileInspector;

package/scripts/harness/installation/application/ports/manifest-repository-port.ts

@@ -8,5 +8,5 @@ export interface ManifestRepositoryPort {
   load(projectRoot: string): Promise<DeploymentManifest | null>;
   save(projectRoot: string, manifest: DeploymentManifest): Promise<void>;
   exists(projectRoot: string): Promise<boolean>;
-  archive(projectRoot: string): Promise<void>;
+  archive(projectRoot: string): Promise<string>;
 }

package/scripts/harness/installation/application/usecases/run-install.ts

@@ -0,0 +1,433 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-146
+
+import { mkdir, readFile, writeFile, copyFile, chmod, access, lstat, readlink, symlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { DeploymentEntry } from "../../domain/deployment-entry.js";
+import { DeploymentManifest } from "../../domain/deployment-manifest.js";
+import type { ManagedBlockInput } from "../../domain/managed-block.js";
+import type { RepairMode } from "../../domain/repair-mode.js";
+import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.js";
+import type { HashCalculatorPort } from "../ports/hash-calculator-port.js";
+
+type InstallAction = "missing" | "will-merge" | "will-skip" | "will-overwrite";
+type StrategyType = "json" | "shell" | "yaml-add" | "package-json";
+
+export interface InstallPlanItem {
+  readonly path: string;
+  readonly action: InstallAction;
+  readonly repairMode: RepairMode;
+  readonly strategy: StrategyType;
+  readonly changed: boolean;
+  readonly summary: string;
+  readonly diff: string;
+  readonly skillHint: string | null;
+}
+
+export interface RunInstallInput {
+  readonly projectRoot: string;
+  readonly harnessRoot: string;
+  readonly phasegateVersion: string;
+  readonly dryRun: boolean;
+  readonly apply: boolean;
+  readonly force: boolean;
+  readonly includeClaude?: boolean;
+  readonly includeCodex?: boolean;
+  readonly includeHusky?: boolean;
+  readonly includeCi?: boolean;
+}
+
+export interface RunInstallResult {
+  readonly plan: readonly InstallPlanItem[];
+  readonly refused: readonly InstallPlanItem[];
+  readonly changed: readonly InstallPlanItem[];
+  readonly backupDir: string | null;
+}
+
+interface InstallTarget {
+  readonly path: string;
+  readonly strategy: StrategyType;
+  readonly templatePath: string;
+  readonly executable?: boolean;
+  readonly block?: ManagedBlockInput;
+}
+
+const SKILL_HINT = "invoke /phasegate-config-doctor";
+const PHASEGATE_SCRIPT_VERSION = "^0.0.0";
+
+const SHELL_BEGIN = "# === phasegate managed (BEGIN) ===";
+const SHELL_END = "# === phasegate managed (END) ===";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readTextOrNull(path: string): Promise<string | null> {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function normalizeJsonEntry(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+function mergeHookArrays(existing: unknown, incoming: unknown): unknown[] {
+  const result = Array.isArray(existing) ? [...existing] : [];
+  const seen = new Set(result.map((entry) => normalizeJsonEntry(entry)));
+  for (const entry of Array.isArray(incoming) ? incoming : []) {
+    const key = normalizeJsonEntry(entry);
+    if (!seen.has(key)) {
+      result.push(entry);
+      seen.add(key);
+    }
+  }
+  return result;
+}
+
+function mergeJsonObject(existing: Record<string, unknown>, incoming: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...existing };
+  const existingHooks = isRecord(existing.hooks) ? existing.hooks : {};
+  const incomingHooks = isRecord(incoming.hooks) ? incoming.hooks : {};
+  result.hooks = { ...existingHooks };
+  for (const [event, incomingEntries] of Object.entries(incomingHooks)) {
+    (result.hooks as Record<string, unknown>)[event] = mergeHookArrays(existingHooks[event], incomingEntries);
+  }
+
+  const existingPermissions = isRecord(existing.permissions) ? existing.permissions : {};
+  const incomingPermissions = isRecord(incoming.permissions) ? incoming.permissions : {};
+  if (Object.keys(incomingPermissions).length > 0 || Object.keys(existingPermissions).length > 0) {
+    const deny = [
+      ...(Array.isArray(existingPermissions.deny) ? existingPermissions.deny : []),
+      ...(Array.isArray(incomingPermissions.deny) ? incomingPermissions.deny : []),
+    ];
+    result.permissions = {
+      ...existingPermissions,
+      ...incomingPermissions,
+      deny: [...new Set(deny)],
+    };
+  }
+  return result;
+}
+
+function mergeShell(existing: string | null, incoming: string): string {
+  if (existing === incoming || existing === `${incoming.trim()}\n`) return existing;
+  const block = `${SHELL_BEGIN}\n${incoming.trim()}\n${SHELL_END}`;
+  if (existing === null || existing.trim().length === 0) return `${incoming.trim()}\n`;
+  const pattern = new RegExp(`${escapeRegExp(SHELL_BEGIN)}[\\s\\S]*?${escapeRegExp(SHELL_END)}`);
+  if (pattern.test(existing)) return existing.replace(pattern, block).replace(/\s*$/, "\n");
+  return `${existing.replace(/\s*$/, "\n\n")}${block}\n`;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function mergePackageJson(existing: Record<string, unknown>, version: string): Record<string, unknown> {
+  const devDependencies = isRecord(existing.devDependencies) ? existing.devDependencies : {};
+  const scripts = isRecord(existing.scripts) ? existing.scripts : {};
+  return {
+    ...existing,
+    scripts: {
+      ...scripts,
+      "phasegate:lint": scripts["phasegate:lint"] ?? "phasegate lint",
+      "phasegate:check-ready": scripts["phasegate:check-ready"] ?? "phasegate phasegate:check-ready",
+      "phasegate:doctor": scripts["phasegate:doctor"] ?? "phasegate doctor",
+    },
+    devDependencies: {
+      ...devDependencies,
+      phasegate: `^${version}`,
+    },
+  };
+}
+
+function hasCustomJson(content: string | null): boolean {
+  if (content === null) return false;
+  try {
+    const parsed = JSON.parse(content) as unknown;
+    if (!isRecord(parsed)) return true;
+    const withoutEmptyHooks = { ...parsed };
+    if (isRecord(withoutEmptyHooks.hooks) && Object.keys(withoutEmptyHooks.hooks).length === 0) delete withoutEmptyHooks.hooks;
+    return Object.keys(withoutEmptyHooks).length > 0;
+  } catch {
+    return true;
+  }
+}
+
+function shellRepairMode(content: string | null): RepairMode {
+  if (content === null || content.trim().length === 0 || content.includes(SHELL_BEGIN)) return "mechanical";
+  return "ai-assisted";
+}
+
+function jsonRepairMode(content: string | null): RepairMode {
+  if (content === null) return "mechanical";
+  try {
+    JSON.parse(content);
+  } catch {
+    return "manual";
+  }
+  return "mechanical";
+}
+
+export class RunInstallUseCase {
+  constructor(
+    private readonly manifestRepository: ManifestRepositoryPort,
+    private readonly hashCalculator: HashCalculatorPort,
+  ) {}
+
+  async execute(input: RunInstallInput): Promise<RunInstallResult> {
+    const includeClaude = input.includeClaude ?? true;
+    const includeCodex = input.includeCodex ?? true;
+    const includeHusky = input.includeHusky ?? true;
+    const includeCi = input.includeCi ?? true;
+    const targets = this.createTargets({ includeClaude, includeCodex, includeHusky, includeCi });
+    const existingManifest = await this.manifestRepository.load(input.projectRoot);
+    const baseManifest = existingManifest ?? DeploymentManifest.create(input.phasegateVersion);
+    let manifest = baseManifest;
+    const plan: InstallPlanItem[] = [];
+    const refused: InstallPlanItem[] = [];
+    const changed: InstallPlanItem[] = [];
+    const backupStamp = new Date().toISOString().replace(/[:.]/g, "-");
+    let backupDir: string | null = null;
+
+    for (const target of targets) {
+      const absolutePath = join(input.projectRoot, target.path);
+      const before = await readTextOrNull(absolutePath);
+      const template = await readFile(join(input.harnessRoot, target.templatePath), "utf8");
+      const repairMode = this.repairMode(target, before);
+      const next = this.merge(target, before, template, input.phasegateVersion);
+      const didChange = before !== next;
+      const action = this.actionFor(before, didChange, input.force);
+      const item: InstallPlanItem = {
+        path: target.path,
+        action,
+        repairMode,
+        strategy: target.strategy,
+        changed: didChange,
+        summary: didChange ? `${target.path}: ${action}` : `${target.path}: already up to date`,
+        diff: this.diffSummary(before, next),
+        skillHint: repairMode === "ai-assisted" ? SKILL_HINT : null,
+      };
+      plan.push(item);
+
+      if (!input.apply || !didChange) continue;
+      if ((repairMode === "ai-assisted" || repairMode === "manual") && !input.force) {
+        refused.push(item);
+        continue;
+      }
+
+      if (before !== null && (input.force || before.includes(SHELL_BEGIN))) {
+        backupDir ??= join(input.projectRoot, ".phasegate", "backups", backupStamp);
+        await this.backup(input.projectRoot, target.path, backupDir);
+      }
+
+      await mkdir(dirname(absolutePath), { recursive: true });
+      await writeFile(absolutePath, next, "utf8");
+      if (target.executable) await chmod(absolutePath, 0o755);
+      changed.push(item);
+
+      const mode = before === null ? "created" : "merged";
+      const hash = this.hashCalculator.compute(next);
+      const existingEntry = baseManifest.findEntry(target.path);
+      if (existingEntry !== null && existingEntry.hash.equals(hash)) {
+        manifest = manifest.addEntry(existingEntry);
+      } else {
+        manifest = manifest.addEntry(
+          DeploymentEntry.create({
+            path: target.path,
+            mode,
+            block: mode === "merged" ? (target.block ?? this.managedBlockFor(target)) : null,
+            hash,
+            deployedAt: new Date().toISOString(),
+          }),
+        );
+      }
+    }
+
+    const linkPaths = [
+      ...(includeClaude ? [".claude/skills"] : []),
+      ...(includeCodex ? [".codex/skills"] : []),
+    ];
+    for (const linkPath of linkPaths) {
+      const item = await this.planSkillLink(input.projectRoot, linkPath);
+      plan.push(item);
+      if (!input.apply || !item.changed) continue;
+      await mkdir(join(input.projectRoot, "skills"), { recursive: true });
+      await mkdir(dirname(join(input.projectRoot, linkPath)), { recursive: true });
+      await symlink("../skills", join(input.projectRoot, linkPath), process.platform === "win32" ? "junction" : "dir");
+      changed.push(item);
+      const hash = this.hashCalculator.compute("../skills");
+      const existingEntry = baseManifest.findEntry(linkPath);
+      if (existingEntry !== null && existingEntry.hash.equals(hash)) {
+        manifest = manifest.addEntry(existingEntry);
+      } else {
+        manifest = manifest.addEntry(
+          DeploymentEntry.create({
+            path: linkPath,
+            mode: "symlink",
+            block: null,
+            hash,
+            deployedAt: new Date().toISOString(),
+          }),
+        );
+      }
+    }
+
+    if (input.apply && changed.length > 0) {
+      await this.manifestRepository.save(input.projectRoot, manifest);
+    }
+
+    return { plan, refused, changed, backupDir };
+  }
+
+  private createTargets(options: {
+    readonly includeClaude: boolean;
+    readonly includeCodex: boolean;
+    readonly includeHusky: boolean;
+    readonly includeCi: boolean;
+  }): readonly InstallTarget[] {
+    return [
+      ...(options.includeClaude
+        ? [{ path: ".claude/settings.json", strategy: "json" as const, templatePath: "templates/.claude/settings.json" }]
+        : []),
+      ...(options.includeCodex
+        ? [{ path: ".codex/hooks.json", strategy: "json" as const, templatePath: "templates/.codex/hooks.json" }]
+        : []),
+      ...(options.includeHusky
+        ? [
+            {
+              path: ".husky/pre-commit",
+              strategy: "shell" as const,
+              templatePath: "docs/templates/hooks/pre-commit",
+              executable: true,
+              block: { start: SHELL_BEGIN, end: SHELL_END, content: "phasegate pre-commit managed block" },
+            },
+            {
+              path: ".husky/commit-msg",
+              strategy: "shell" as const,
+              templatePath: "docs/templates/hooks/commit-msg",
+              executable: true,
+              block: { start: SHELL_BEGIN, end: SHELL_END, content: "phasegate commit-msg managed block" },
+            },
+            {
+              path: ".husky/pre-push",
+              strategy: "shell" as const,
+              templatePath: "docs/templates/hooks/pre-push",
+              executable: true,
+              block: { start: SHELL_BEGIN, end: SHELL_END, content: "phasegate pre-push managed block" },
+            },
+          ]
+        : []),
+      ...(options.includeCi
+        ? [
+            {
+              path: ".github/workflows/phasegate-aidlc-gate.yml",
+              strategy: "yaml-add" as const,
+              templatePath: "docs/templates/ci/aidlc-gate.yml",
+            },
+          ]
+        : []),
+      { path: "package.json", strategy: "package-json" as const, templatePath: "package.json" },
+    ];
+  }
+
+  private repairMode(target: InstallTarget, before: string | null): RepairMode {
+    if (target.strategy === "shell") return shellRepairMode(before);
+    if (target.strategy === "json") return jsonRepairMode(before);
+    return "mechanical";
+  }
+
+  private actionFor(before: string | null, changed: boolean, force: boolean): InstallAction {
+    if (!changed) return "will-skip";
+    if (before === null) return "missing";
+    return force ? "will-overwrite" : "will-merge";
+  }
+
+  private merge(target: InstallTarget, before: string | null, template: string, version: string): string {
+    if (target.strategy === "yaml-add") return before ?? template;
+    if (target.strategy === "shell") return mergeShell(before, template);
+    if (target.strategy === "package-json") {
+      const existing = before === null ? {} : (JSON.parse(before) as unknown);
+      const merged = mergePackageJson(isRecord(existing) ? existing : {}, version || PHASEGATE_SCRIPT_VERSION);
+      return `${JSON.stringify(merged, null, 2)}\n`;
+    }
+    const existing = before === null ? {} : (JSON.parse(before) as unknown);
+    const incoming = JSON.parse(template) as unknown;
+    const merged = mergeJsonObject(isRecord(existing) ? existing : {}, isRecord(incoming) ? incoming : {});
+    return `${JSON.stringify(merged, null, 2)}\n`;
+  }
+
+  private async backup(projectRoot: string, relativePath: string, backupDir: string): Promise<void> {
+    const source = join(projectRoot, relativePath);
+    const target = join(backupDir, relativePath);
+    if (!(await exists(source))) return;
+    await mkdir(dirname(target), { recursive: true });
+    await copyFile(source, target);
+  }
+
+  private managedBlockFor(target: InstallTarget): ManagedBlockInput {
+    return {
+      start: "phasegate structured merge",
+      end: "phasegate structured merge",
+      content: `${target.strategy}:${target.path}`,
+    };
+  }
+
+  private async planSkillLink(projectRoot: string, relativePath: string): Promise<InstallPlanItem> {
+    const absolutePath = join(projectRoot, relativePath);
+    try {
+      const stat = await lstat(absolutePath);
+      if (stat.isSymbolicLink() && (await readlink(absolutePath)) === "../skills") {
+        return {
+          path: relativePath,
+          action: "will-skip",
+          repairMode: "mechanical",
+          strategy: "yaml-add",
+          changed: false,
+          summary: `${relativePath}: already linked`,
+          diff: "no changes",
+          skillHint: null,
+        };
+      }
+      return {
+        path: relativePath,
+        action: "will-merge",
+        repairMode: "manual",
+        strategy: "yaml-add",
+        changed: false,
+        summary: `${relativePath}: existing non-phasegate path requires manual review`,
+        diff: "manual review required",
+        skillHint: null,
+      };
+    } catch {
+      return {
+        path: relativePath,
+        action: "missing",
+        repairMode: "mechanical",
+        strategy: "yaml-add",
+        changed: true,
+        summary: `${relativePath}: create symlink`,
+        diff: "+ symlink ../skills",
+        skillHint: null,
+      };
+    }
+  }
+
+  private diffSummary(before: string | null, next: string): string {
+    if (before === next) return "no changes";
+    if (before === null) return `+ ${next.split(/\r?\n/).filter(Boolean).length} lines`;
+    return `~ ${before.length} bytes -> ${next.length} bytes`;
+  }
+}

package/scripts/harness/installation/application/usecases/run-uninstall.ts

@@ -0,0 +1,365 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-147
+
+import { access, copyFile, lstat, mkdir, readFile, readlink, rm, rmdir, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import type { DeploymentEntry } from "../../domain/deployment-entry.js";
+import type { RepairMode } from "../../domain/repair-mode.js";
+import type { HashCalculatorPort } from "../ports/hash-calculator-port.js";
+import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.js";
+
+type UninstallAction = "missing-manifest" | "delete" | "unlink" | "reverse-merge" | "skip" | "refuse";
+type StrategyType = "created" | "json" | "shell" | "package-json" | "symlink" | "yaml-add" | "unknown";
+
+export interface UninstallPlanItem {
+  readonly path: string;
+  readonly action: UninstallAction;
+  readonly repairMode: RepairMode;
+  readonly strategy: StrategyType;
+  readonly changed: boolean;
+  readonly summary: string;
+  readonly diff: string;
+  readonly skillHint: string | null;
+}
+
+export interface RunUninstallInput {
+  readonly projectRoot: string;
+  readonly harnessRoot: string;
+  readonly dryRun: boolean;
+  readonly apply: boolean;
+  readonly force: boolean;
+}
+
+export interface RunUninstallResult {
+  readonly plan: readonly UninstallPlanItem[];
+  readonly refused: readonly UninstallPlanItem[];
+  readonly changed: readonly UninstallPlanItem[];
+  readonly backupDir: string | null;
+  readonly archivedManifestPath: string | null;
+}
+
+const SKILL_HINT = "invoke /phasegate-config-doctor";
+const SHELL_BEGIN = "# === phasegate managed (BEGIN) ===";
+const SHELL_END = "# === phasegate managed (END) ===";
+const PHASEGATE_SCRIPT_PREFIX = "phasegate:";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readTextOrNull(path: string): Promise<string | null> {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function normalizeJsonEntry(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+function removeHookEntries(existing: unknown, incoming: unknown): unknown[] {
+  const templateEntries = new Set((Array.isArray(incoming) ? incoming : []).map((entry) => normalizeJsonEntry(entry)));
+  return (Array.isArray(existing) ? existing : []).filter((entry) => !templateEntries.has(normalizeJsonEntry(entry)));
+}
+
+export function reverseJsonMerge(currentContent: string, templateContent: string): string {
+  const current = JSON.parse(currentContent) as unknown;
+  const template = JSON.parse(templateContent) as unknown;
+  const result: Record<string, unknown> = isRecord(current) ? { ...current } : {};
+  const currentHooks = isRecord(result.hooks) ? result.hooks : {};
+  const templateHooks = isRecord(template) && isRecord(template.hooks) ? template.hooks : {};
+  const nextHooks: Record<string, unknown> = {};
+  for (const [event, entries] of Object.entries(currentHooks)) {
+    const remaining = removeHookEntries(entries, templateHooks[event]);
+    if (remaining.length > 0) nextHooks[event] = remaining;
+  }
+  if (Object.keys(nextHooks).length > 0) result.hooks = nextHooks;
+  else delete result.hooks;
+
+  if (isRecord(result.permissions)) {
+    const templatePermissions = isRecord(template) && isRecord(template.permissions) ? template.permissions : {};
+    const templateDeny = new Set(Array.isArray(templatePermissions.deny) ? templatePermissions.deny : []);
+    const currentDeny = Array.isArray(result.permissions.deny) ? result.permissions.deny : [];
+    const remainingDeny = currentDeny.filter((entry) => !templateDeny.has(entry));
+    const nextPermissions = { ...result.permissions };
+    if (remainingDeny.length > 0) nextPermissions.deny = remainingDeny;
+    else delete nextPermissions.deny;
+    if (Object.keys(nextPermissions).length > 0) result.permissions = nextPermissions;
+    else delete result.permissions;
+  }
+
+  return `${JSON.stringify(result, null, 2)}\n`;
+}
+
+export function reverseShellMerge(currentContent: string): string {
+  const pattern = new RegExp(`\\n?${escapeRegExp(SHELL_BEGIN)}[\\s\\S]*?${escapeRegExp(SHELL_END)}\\n?`);
+  return currentContent.replace(pattern, "\n").replace(/\n{3,}/g, "\n\n").replace(/\s*$/, "\n").replace(/^\n/, "");
+}
+
+export function reversePackageJsonMerge(currentContent: string): string {
+  const parsed = JSON.parse(currentContent) as unknown;
+  const result = isRecord(parsed) ? { ...parsed } : {};
+  if (isRecord(result.devDependencies)) {
+    const devDependencies = { ...result.devDependencies };
+    delete devDependencies.phasegate;
+    if (Object.keys(devDependencies).length > 0) result.devDependencies = devDependencies;
+    else delete result.devDependencies;
+  }
+  if (isRecord(result.scripts)) {
+    const scripts = Object.fromEntries(Object.entries(result.scripts).filter(([name]) => !name.startsWith(PHASEGATE_SCRIPT_PREFIX)));
+    if (Object.keys(scripts).length > 0) result.scripts = scripts;
+    else delete result.scripts;
+  }
+  return `${JSON.stringify(result, null, 2)}\n`;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export class RunUninstallUseCase {
+  constructor(
+    private readonly manifestRepository: ManifestRepositoryPort,
+    private readonly hashCalculator: HashCalculatorPort,
+  ) {}
+
+  async execute(input: RunUninstallInput): Promise<RunUninstallResult> {
+    const manifest = await this.manifestRepository.load(input.projectRoot);
+    if (manifest === null) {
+      const item: UninstallPlanItem = {
+        path: ".phasegate/manifest.json",
+        action: "missing-manifest",
+        repairMode: "manual",
+        strategy: "unknown",
+        changed: false,
+        summary: "manifest missing; run phasegate doctor and clean up manually",
+        diff: "manual cleanup required",
+        skillHint: SKILL_HINT,
+      };
+      return { plan: [item], refused: [], changed: [], backupDir: null, archivedManifestPath: null };
+    }
+
+    const plan: UninstallPlanItem[] = [];
+    const refused: UninstallPlanItem[] = [];
+    const changed: UninstallPlanItem[] = [];
+    const backupStamp = `uninstall-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+    let backupDir: string | null = null;
+
+    const outcomes: Array<{
+      readonly entry: DeploymentEntry;
+      readonly item: UninstallPlanItem;
+      readonly needsBackup: boolean;
+      readonly apply: () => Promise<void>;
+    }> = [];
+    for (const entry of manifest.entries) {
+      const outcome = await this.planEntry(input, entry);
+      outcomes.push({ entry, ...outcome });
+      plan.push(outcome.item);
+      if (input.apply && outcome.item.changed && (outcome.item.repairMode === "ai-assisted" || outcome.item.repairMode === "manual") && !input.force) {
+        refused.push({ ...outcome.item, action: "refuse" });
+      }
+    }
+
+    if (!input.apply || refused.length > 0) {
+      return { plan, refused, changed, backupDir: null, archivedManifestPath: null };
+    }
+
+    for (const outcome of outcomes) {
+      if (!outcome.item.changed) continue;
+      if (outcome.needsBackup) {
+        backupDir ??= join(input.projectRoot, ".phasegate", "backups", backupStamp);
+        await this.backup(input.projectRoot, outcome.entry.path, backupDir);
+      }
+      await outcome.apply();
+      await this.cleanupEmptyParents(input.projectRoot, outcome.entry.path);
+      changed.push(outcome.item);
+    }
+
+    const archivedManifestPath = await this.manifestRepository.archive(input.projectRoot);
+    return { plan, refused, changed, backupDir, archivedManifestPath };
+  }
+
+  private async planEntry(input: RunUninstallInput, entry: DeploymentEntry): Promise<{
+    readonly item: UninstallPlanItem;
+    readonly needsBackup: boolean;
+    readonly apply: () => Promise<void>;
+  }> {
+    const absolutePath = this.resolveProjectPath(input.projectRoot, entry.path);
+    const currentContent = await readTextOrNull(absolutePath);
+    const strategy = this.strategyFor(entry.path, entry.mode);
+    if (currentContent === null && strategy !== "symlink") {
+      return {
+        item: this.item(entry.path, "skip", "mechanical", strategy, false, `${entry.path}: already absent`, "no changes", null),
+        needsBackup: false,
+        apply: async () => {},
+      };
+    }
+
+    if (entry.mode === "symlink") return this.planSymlink(input.projectRoot, entry);
+    if (entry.mode === "created") return this.planCreated(input.projectRoot, entry, currentContent ?? "");
+    return this.planMerged(input, entry, currentContent ?? "", strategy);
+  }
+
+  private async planSymlink(projectRoot: string, entry: DeploymentEntry) {
+    const absolutePath = this.resolveProjectPath(projectRoot, entry.path);
+    let target: string | null = null;
+    try {
+      const stat = await lstat(absolutePath);
+      target = stat.isSymbolicLink() ? await readlink(absolutePath) : null;
+    } catch {
+      target = null;
+    }
+    if (target === "../skills") {
+      return {
+        item: this.item(entry.path, "unlink", "mechanical", "symlink", true, `${entry.path}: remove symlink`, "- symlink ../skills", null),
+        needsBackup: false,
+        apply: async () => {
+          await rm(absolutePath, { force: true });
+        },
+      };
+    }
+    return {
+      item: this.item(entry.path, "skip", "manual", "symlink", false, `${entry.path}: non-phasegate symlink/path skipped`, "manual review required", null),
+      needsBackup: false,
+      apply: async () => {},
+    };
+  }
+
+  private async planCreated(projectRoot: string, entry: DeploymentEntry, currentContent: string) {
+    const absolutePath = this.resolveProjectPath(projectRoot, entry.path);
+    const currentHash = this.hashCalculator.compute(currentContent);
+    const matchesManifest = currentHash.equals(entry.hash);
+    const repairMode: RepairMode = matchesManifest ? "mechanical" : "ai-assisted";
+    return {
+      item: this.item(
+        entry.path,
+        "delete",
+        repairMode,
+        this.strategyFor(entry.path, entry.mode),
+        true,
+        matchesManifest ? `${entry.path}: delete created file` : `${entry.path}: hash mismatch; force required`,
+        "- file",
+        matchesManifest ? null : SKILL_HINT,
+      ),
+      needsBackup: !matchesManifest,
+      apply: async () => {
+        await rm(absolutePath, { force: true });
+      },
+    };
+  }
+
+  private async planMerged(input: RunUninstallInput, entry: DeploymentEntry, currentContent: string, strategy: StrategyType) {
+    const currentHash = this.hashCalculator.compute(currentContent);
+    const matchesManifest = currentHash.equals(entry.hash);
+    try {
+      const next = await this.reverseMerged(input.harnessRoot, entry.path, currentContent, strategy);
+      if (next === currentContent) {
+        return {
+          item: this.item(entry.path, "skip", "mechanical", strategy, false, `${entry.path}: managed portion already absent`, "no changes", null),
+          needsBackup: false,
+          apply: async () => {},
+        };
+      }
+      const repairMode: RepairMode = matchesManifest ? "mechanical" : "ai-assisted";
+      return {
+        item: this.item(
+          entry.path,
+          "reverse-merge",
+          repairMode,
+          strategy,
+          true,
+          matchesManifest ? `${entry.path}: remove managed portion` : `${entry.path}: hash mismatch; force required`,
+          `~ ${currentContent.length} bytes -> ${next.length} bytes`,
+          matchesManifest ? null : SKILL_HINT,
+        ),
+        needsBackup: !matchesManifest,
+        apply: async () => {
+          await writeFile(this.resolveProjectPath(input.projectRoot, entry.path), next, "utf8");
+        },
+      };
+    } catch {
+      return {
+        item: this.item(entry.path, "skip", "manual", strategy, false, `${entry.path}: reverse merge requires manual review`, "manual review required", SKILL_HINT),
+        needsBackup: false,
+        apply: async () => {},
+      };
+    }
+  }
+
+  private async reverseMerged(harnessRoot: string, path: string, currentContent: string, strategy: StrategyType): Promise<string> {
+    if (strategy === "shell") return currentContent.includes(SHELL_BEGIN) ? reverseShellMerge(currentContent) : currentContent;
+    if (strategy === "package-json") return reversePackageJsonMerge(currentContent);
+    if (strategy === "json") return reverseJsonMerge(currentContent, await readFile(join(harnessRoot, this.templateFor(path)), "utf8"));
+    throw new Error(`Unsupported merged strategy: ${strategy}`);
+  }
+
+  private strategyFor(path: string, mode: string): StrategyType {
+    if (mode === "symlink") return "symlink";
+    if (mode === "created") return path.endsWith(".yml") || path.endsWith(".yaml") ? "yaml-add" : "created";
+    if (path === "package.json") return "package-json";
+    if (path.endsWith(".json")) return "json";
+    if (path.startsWith(".husky/")) return "shell";
+    return "unknown";
+  }
+
+  private templateFor(path: string): string {
+    if (path === ".claude/settings.json") return "templates/.claude/settings.json";
+    if (path === ".codex/hooks.json") return "templates/.codex/hooks.json";
+    throw new Error(`No template for ${path}`);
+  }
+
+  private async backup(projectRoot: string, relativePath: string, backupDir: string): Promise<void> {
+    const source = this.resolveProjectPath(projectRoot, relativePath);
+    if (!(await exists(source))) return;
+    const target = join(backupDir, relativePath);
+    await mkdir(dirname(target), { recursive: true });
+    await copyFile(source, target);
+  }
+
+  private async cleanupEmptyParents(projectRoot: string, relativePath: string): Promise<void> {
+    let current = dirname(this.resolveProjectPath(projectRoot, relativePath));
+    const root = resolve(projectRoot);
+    while (current.startsWith(root) && current !== root && relative(root, current) !== ".phasegate") {
+      try {
+        await rmdir(current);
+      } catch {
+        return;
+      }
+      current = dirname(current);
+    }
+  }
+
+  private resolveProjectPath(projectRoot: string, relativePath: string): string {
+    const absolutePath = resolve(projectRoot, relativePath);
+    const root = resolve(projectRoot);
+    if (absolutePath !== root && !absolutePath.startsWith(`${root}/`)) {
+      throw new Error(`Manifest entry escapes project root: ${relativePath}`);
+    }
+    return absolutePath;
+  }
+
+  private item(
+    path: string,
+    action: UninstallAction,
+    repairMode: RepairMode,
+    strategy: StrategyType,
+    changed: boolean,
+    summary: string,
+    diff: string,
+    skillHint: string | null,
+  ): UninstallPlanItem {
+    return { path, action, repairMode, strategy, changed, summary, diff, skillHint };
+  }
+}

package/scripts/harness/installation/composition-root.ts

@@ -11,14 +11,31 @@ import { HuskyCommitMsgMissingCheck } from "./application/checks/husky-commit-ms
 import { HuskyPreCommitMissingCheck } from "./application/checks/husky-pre-commit-missing-check.js";
 import { HuskyPrePushMissingCheck } from "./application/checks/husky-pre-push-missing-check.js";
 import { PackageJsonDevdepMissingCheck } from "./application/checks/package-json-devdep-missing-check.js";
+import { RunInstallUseCase } from "./application/usecases/run-install.js";
+import { RunUninstallUseCase } from "./application/usecases/run-uninstall.js";
 import { RunDoctorDiagnosticsUseCase } from "./application/usecases/run-doctor-diagnostics.js";
+import type { MergeStrategy } from "./domain/ports/merge-strategy.js";
+import type { ReconcileStrategy } from "./domain/ports/reconcile-strategy.js";
+import type { UninstallReverseStrategy } from "./domain/ports/uninstall-reverse-strategy.js";
 import { FileSystemManifestRepositoryAdapter } from "./infrastructure/adapters/file-system-manifest-repository-adapter.js";
+import { NodeCryptoHashAdapter } from "./infrastructure/adapters/node-crypto-hash-adapter.js";
 import { NodeFsFileInspectorAdapter } from "./infrastructure/adapters/node-fs-file-inspector-adapter.js";
 import { DoctorHandler } from "./presentation/cli/doctor-handler.js";
+import { InstallHandler } from "./presentation/cli/install-handler.js";
+import { UninstallHandler } from "./presentation/cli/uninstall-handler.js";
+
+type FutureInstallationStrategyPorts = {
+  readonly merge?: MergeStrategy<unknown>;
+  readonly uninstall?: UninstallReverseStrategy;
+  readonly reconcile?: ReconcileStrategy;
+};
+
+const futureInstallationStrategyPorts: FutureInstallationStrategyPorts = {};
 
 export function createInstallationModule() {
   const inspector = new NodeFsFileInspectorAdapter();
   const manifestRepository = new FileSystemManifestRepositoryAdapter();
+  const hashCalculator = new NodeCryptoHashAdapter();
   const checks = [
     new ClaudeHookMissingCheck(),
     new CodexHookMissingCheck(),
@@ -31,9 +48,16 @@ export function createInstallationModule() {
     new CodexSkillsSymlinkCheck(),
   ];
   const runDoctorDiagnosticsUseCase = new RunDoctorDiagnosticsUseCase(checks, inspector, manifestRepository);
+  const runInstallUseCase = new RunInstallUseCase(manifestRepository, hashCalculator);
+  const runUninstallUseCase = new RunUninstallUseCase(manifestRepository, hashCalculator);
   return {
     manifestRepository,
     runDoctorDiagnosticsUseCase,
+    runInstallUseCase,
+    runUninstallUseCase,
     doctorHandler: new DoctorHandler(runDoctorDiagnosticsUseCase),
+    installHandler: new InstallHandler(runInstallUseCase),
+    uninstallHandler: new UninstallHandler(runUninstallUseCase),
+    futureInstallationStrategyPorts,
   };
 }

package/scripts/harness/installation/domain/ports/file-inspector.ts

@@ -0,0 +1,11 @@
+// @unit installation
+// @layer domain
+// @work-item-id WI-146
+
+export interface FileInspector {
+  exists(absolutePath: string): Promise<boolean>;
+  readText(absolutePath: string): Promise<string | null>;
+  readJson<T = unknown>(absolutePath: string): Promise<T | null>;
+  readSymlink(absolutePath: string): Promise<string | null>;
+  listFiles(absolutePath: string): Promise<string[]>;
+}

package/scripts/harness/installation/domain/ports/heuristic-check.ts

@@ -2,11 +2,11 @@
 // @layer domain
 // @work-item-id WI-145
 
-import type { FileInspectorPort } from "../../application/ports/file-inspector-port.js";
 import type { CheckId } from "../check-id.js";
 import type { DiagnosticFinding } from "../diagnostic-finding.js";
+import type { FileInspector } from "./file-inspector.js";
 
 export interface HeuristicCheck {
   readonly checkId: CheckId;
-  run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null>;
+  run(projectRoot: string, inspector: FileInspector): Promise<DiagnosticFinding | null>;
 }

package/scripts/harness/installation/infrastructure/adapters/file-system-manifest-repository-adapter.ts

@@ -52,8 +52,13 @@ export class FileSystemManifestRepositoryAdapter implements ManifestRepositoryPo
     }
   }
 
-  async archive(_projectRoot: string): Promise<void> {
-    throw new Error("Not yet implemented: manifest archive is owned by WI-147");
+  async archive(projectRoot: string): Promise<string> {
+    const phasegateDir = join(projectRoot, ".phasegate");
+    await mkdir(phasegateDir, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const archivedPath = join(phasegateDir, `uninstalled-${stamp}.json`);
+    await rename(this.manifestPath(projectRoot), archivedPath);
+    return archivedPath;
   }
 
   private manifestPath(projectRoot: string): string {

package/scripts/harness/installation/presentation/cli/install-handler.ts

@@ -0,0 +1,50 @@
+// @unit installation
+// @layer presentation
+// @work-item-id WI-146
+
+import type { RunInstallUseCase } from "../../application/usecases/run-install.js";
+
+export interface InstallHandlerInput {
+  readonly projectRoot: string;
+  readonly harnessRoot: string;
+  readonly phasegateVersion: string;
+  readonly dryRun: boolean;
+  readonly apply: boolean;
+  readonly force: boolean;
+  readonly json: boolean;
+}
+
+export interface InstallHandlerResult {
+  readonly stdout: string;
+  readonly exitCode: number;
+}
+
+export class InstallHandler {
+  constructor(private readonly useCase: RunInstallUseCase) {}
+
+  async execute(input: InstallHandlerInput): Promise<InstallHandlerResult> {
+    const result = await this.useCase.execute(input);
+    if (input.json) {
+      return {
+        stdout: JSON.stringify(result, null, 2),
+        exitCode: result.refused.length > 0 ? 1 : 0,
+      };
+    }
+    const lines = [
+      input.apply ? "phasegate install apply" : "phasegate install dry-run",
+      ...result.plan.map((item) => {
+        const hint = item.skillHint ? `; hint: ${item.skillHint}` : "";
+        return `- ${item.path}: ${item.action} (${item.repairMode}, ${item.strategy}); diff: ${item.diff}${hint}`;
+      }),
+    ];
+    if (result.backupDir !== null) lines.push(`backups: ${result.backupDir}`);
+    if (result.refused.length > 0) {
+      lines.push("");
+      lines.push("Refused ai-assisted/manual targets. Re-run with --force after reviewing the hint.");
+    }
+    return {
+      stdout: lines.join("\n"),
+      exitCode: result.refused.length > 0 ? 1 : 0,
+    };
+  }
+}

package/scripts/harness/installation/presentation/cli/uninstall-handler.ts

@@ -0,0 +1,50 @@
+// @unit installation
+// @layer presentation
+// @work-item-id WI-147
+
+import type { RunUninstallUseCase } from "../../application/usecases/run-uninstall.js";
+
+export interface UninstallHandlerInput {
+  readonly projectRoot: string;
+  readonly harnessRoot: string;
+  readonly dryRun: boolean;
+  readonly apply: boolean;
+  readonly force: boolean;
+  readonly json: boolean;
+}
+
+export interface UninstallHandlerResult {
+  readonly stdout: string;
+  readonly exitCode: number;
+}
+
+export class UninstallHandler {
+  constructor(private readonly useCase: RunUninstallUseCase) {}
+
+  async execute(input: UninstallHandlerInput): Promise<UninstallHandlerResult> {
+    const result = await this.useCase.execute(input);
+    if (input.json) {
+      return {
+        stdout: JSON.stringify(result, null, 2),
+        exitCode: result.refused.length > 0 ? 1 : 0,
+      };
+    }
+    const lines = [
+      input.apply ? "phasegate uninstall apply" : "phasegate uninstall dry-run",
+      ...result.plan.map((item) => {
+        const hint = item.skillHint ? `; hint: ${item.skillHint}` : "";
+        return `- ${item.path}: ${item.action} (${item.repairMode}, ${item.strategy}); diff: ${item.diff}${hint}`;
+      }),
+    ];
+    if (result.backupDir !== null) lines.push(`backups: ${result.backupDir}`);
+    if (result.archivedManifestPath !== null) lines.push(`archived manifest: ${result.archivedManifestPath}`);
+    if (result.refused.length > 0) {
+      lines.push("");
+      lines.push("Refused ai-assisted/manual targets. Re-run with --force after reviewing the hint.");
+    }
+    return {
+      stdout: lines.join("\n"),
+      exitCode: result.refused.length > 0 ? 1 : 0,
+    };
+  }
+}

package/scripts/harness/main.ts

@@ -151,8 +151,8 @@ Setup:
                                 --skills <core|all>, --agent <claude|codex|both>, --with-husky, --with-ci, --yes)
   update-skills                Re-deploy skills from current harness version
   doctor                       Diagnose silent installation failures (--json, --strict, --report-out <path>)
-  install                      Install phasegate managed files (stub until WI-146)
-  uninstall                    Uninstall phasegate managed files (stub until WI-147)
+  install                      Install phasegate managed files (--dry-run|--apply, --force)
+  uninstall                    Uninstall phasegate managed files (--dry-run|--apply, --force)
   reconcile                    Reconcile phasegate managed files (stub until WI-148)
 
 Commands:
@@ -371,6 +371,16 @@ Options:
   --skills <core|all>             Skill set to deploy
   --agent <claude|codex|both>     Agent integration target
   --help, -h                      Show this help`,
+  install: `Usage: phasegate install [options]
+
+Install phasegate managed files with structured merge.
+
+Options:
+  --dry-run                       Preview target actions without writing (default)
+  --apply                         Write merge results and manifest
+  --force                         Force ai-assisted/manual targets after backing up existing files
+  --json                          Output machine-readable JSON
+  --help, -h                      Show this help`,
   validate: `Usage: phasegate validate [options]
 
 Run validators against the project. Without --layer, runs all enabled validator layers (L2/L3/L4).
@@ -840,9 +850,30 @@ async function main(): Promise<void> {
           huskyPrePushResult?.created ? await createFileManifestRecord(rootDir, join(".husky", "pre-push")) : null,
           ...(ciWorkflowResult?.copiedFiles.map((path) => createFileManifestRecord(rootDir, path)) ?? []),
         ]);
+        const installModule = createInstallationModule();
+        const installResult = await installModule.runInstallUseCase.execute({
+          projectRoot: rootDir,
+          harnessRoot,
+          phasegateVersion: result.version,
+          dryRun: false,
+          apply: true,
+          force: false,
+          includeClaude: deployClaude,
+          includeCodex: deployCodex,
+          includeHusky: withHusky,
+          includeCi: withCi,
+        });
         console.log(
           `✓ Skills deployed to ${result.targetDir} (${result.deployedSkills.length} skills, set: ${skillSet})`,
         );
+        if (installResult.changed.length > 0) {
+          console.log(`✓ phasegate install structured merge applied (${installResult.changed.length} targets)`);
+        }
+        if (installResult.refused.length > 0) {
+          console.log(
+            `  phasegate install refused ${installResult.refused.length} ai-assisted/manual targets; run phasegate install --dry-run for details`,
+          );
+        }
         if (packageResult.created) {
           console.log(`✓ package.json created with phasegate devDependency`);
         } else if (packageResult.updated) {
@@ -1012,14 +1043,50 @@ async function main(): Promise<void> {
       }
 
       case "install": {
-        console.error("Not yet implemented: phasegate install is owned by WI-146");
-        process.exit(2);
+        const KNOWN_INSTALL_FLAGS = ["--dry-run", "--apply", "--force", "--json"];
+        const flagError = validateKnownFlags(args, KNOWN_INSTALL_FLAGS);
+        if (flagError) {
+          console.error(flagError);
+          process.exit(2);
+        }
+        const apply = hasFlag(args, "--apply");
+        const dryRun = hasFlag(args, "--dry-run") || !apply;
+        const mod = createInstallationModule();
+        const phasegateVersion = await getHarnessVersion(harnessRoot);
+        const result = await mod.installHandler.execute({
+          projectRoot: rootDir,
+          harnessRoot,
+          phasegateVersion,
+          dryRun,
+          apply,
+          force: hasFlag(args, "--force"),
+          json,
+        });
+        console.log(result.stdout);
+        process.exit(result.exitCode);
         break;
       }
 
       case "uninstall": {
-        console.error("Not yet implemented: phasegate uninstall is owned by WI-147");
-        process.exit(2);
+        const KNOWN_UNINSTALL_FLAGS = ["--dry-run", "--apply", "--force", "--json"];
+        const flagError = validateKnownFlags(args, KNOWN_UNINSTALL_FLAGS);
+        if (flagError) {
+          console.error(flagError);
+          process.exit(2);
+        }
+        const apply = hasFlag(args, "--apply");
+        const dryRun = hasFlag(args, "--dry-run") || !apply;
+        const mod = createInstallationModule();
+        const result = await mod.uninstallHandler.execute({
+          projectRoot: rootDir,
+          harnessRoot,
+          dryRun,
+          apply,
+          force: hasFlag(args, "--force"),
+          json,
+        });
+        console.log(result.stdout);
+        process.exit(result.exitCode);
         break;
       }