phasegate 0.145.2 → 0.145.4

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.145.4] - 2026-05-11
+
+### Added
+
+- **WI-148 — manifest-driven reconcile + init deprecation** — `phasegate reconcile --dry-run|--apply [--force] [--json]` を追加し、`.phasegate/manifest.json` に記録済みの PhaseGate managed files を現行 bundled template / package version に追従できるようにした。
+  - `merged` entries は PhaseGate managed portion だけを更新し、user scripts / hooks / dependencies は保持する。
+  - `created` entries は hash が manifest と一致する場合のみ template に追従し、user 改変ありの場合は `--force` 無しで refuse、force 時は `.phasegate/backups/reconcile-*/` に退避してから上書きする。
+  - manifest に無い現行 deploy target は install と同じく追加し、apply 後は manifest の version/hash を更新する。
+  - `update-skills` は互換 alias として `reconcile` に委譲し、`init` 実行時は v1.0 削除予定の deprecation warning を表示する。
+
+## [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

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,34 @@ 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 します。
+
+PhaseGate をアップグレードした後は、reconcile で既存の managed files を現在の bundled template に追従できます。
+
+```sh
+npx phasegate reconcile --dry-run
+npx phasegate reconcile --apply
+```
+
+`reconcile` は PhaseGate 管理部分だけを更新し、ユーザーの hook / script / dependency は保持します。新しい deploy target が追加されていれば install と同じく追加し、`.phasegate/manifest.json` の version / hash も更新します。install 後に user 改変された managed file は `--force` 無しでは refuse し、force 時は `.phasegate/backups/reconcile-<timestamp>/` に退避してから上書きします。
+
 ### 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,34 @@ 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/`.
+
+When you upgrade PhaseGate, reconcile existing managed files with the current bundled templates:
+
+```sh
+npx phasegate reconcile --dry-run
+npx phasegate reconcile --apply
+```
+
+`reconcile` updates only PhaseGate-managed portions, keeps user content, adds newly introduced managed targets, and refreshes `.phasegate/manifest.json` with the current version and hashes. If a managed file was edited after install, `reconcile --apply` refuses that entry until you rerun with `--force`; PhaseGate writes a backup under `.phasegate/backups/reconcile-<timestamp>/`.
+
 ### 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,49 @@ 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>/`.
+
+After upgrading PhaseGate, reconcile existing managed files with the bundled templates from the new version:
+
+```bash
+npx phasegate reconcile --dry-run
+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:
 
 ```bash
 cp node_modules/phasegate/docs/folder_management_rules.md docs/
@@ -52,11 +94,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 +130,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.2",
+  "version": "0.145.4",
   "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/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-reconcile.ts

@@ -0,0 +1,437 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-148
+
+import { access, chmod, copyFile, lstat, mkdir, readFile, readlink, symlink, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } 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 { HashCalculatorPort } from "../ports/hash-calculator-port.js";
+import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.js";
+
+type ReconcileAction = "missing-manifest" | "update" | "add" | "link" | "skip" | "refuse";
+type StrategyType = "json" | "shell" | "yaml-add" | "package-json" | "symlink" | "unknown";
+
+export interface ReconcilePlanItem {
+  readonly path: string;
+  readonly action: ReconcileAction;
+  readonly repairMode: RepairMode;
+  readonly strategy: StrategyType;
+  readonly changed: boolean;
+  readonly summary: string;
+  readonly diff: string;
+  readonly skillHint: string | null;
+}
+
+export interface RunReconcileInput {
+  readonly projectRoot: string;
+  readonly harnessRoot: string;
+  readonly phasegateVersion: string;
+  readonly dryRun: boolean;
+  readonly apply: boolean;
+  readonly force: boolean;
+}
+
+export interface RunReconcileResult {
+  readonly plan: readonly ReconcilePlanItem[];
+  readonly refused: readonly ReconcilePlanItem[];
+  readonly changed: readonly ReconcilePlanItem[];
+  readonly backupDir: string | null;
+}
+
+interface ReconcileTarget {
+  readonly path: string;
+  readonly strategy: StrategyType;
+  readonly templatePath?: string;
+  readonly executable?: boolean;
+  readonly block?: ManagedBlockInput;
+}
+
+const SKILL_HINT = "invoke /phasegate-config-doctor";
+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 escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function phasegateOwnedJsonEntry(entry: unknown): boolean {
+  return normalizeJsonEntry(entry).includes("phasegate");
+}
+
+function replaceHookArrays(existing: unknown, incoming: unknown): unknown[] {
+  const userEntries = (Array.isArray(existing) ? existing : []).filter((entry) => !phasegateOwnedJsonEntry(entry));
+  const seen = new Set(userEntries.map((entry) => normalizeJsonEntry(entry)));
+  const result = [...userEntries];
+  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 reconcileJsonObject(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 : {};
+  const nextHooks: Record<string, unknown> = {};
+  const events = new Set([...Object.keys(existingHooks), ...Object.keys(incomingHooks)]);
+  for (const event of events) {
+    const entries = replaceHookArrays(existingHooks[event], incomingHooks[event]);
+    if (entries.length > 0) nextHooks[event] = entries;
+  }
+  if (Object.keys(nextHooks).length > 0) result.hooks = nextHooks;
+  else delete result.hooks;
+
+  const existingPermissions = isRecord(existing.permissions) ? existing.permissions : {};
+  const incomingPermissions = isRecord(incoming.permissions) ? incoming.permissions : {};
+  const incomingDeny = Array.isArray(incomingPermissions.deny) ? incomingPermissions.deny : [];
+  if (Object.keys(existingPermissions).length > 0 || Object.keys(incomingPermissions).length > 0) {
+    const existingDeny = Array.isArray(existingPermissions.deny) ? existingPermissions.deny : [];
+    const preservedDeny = existingDeny.filter((entry) => typeof entry !== "string" || !incomingDeny.includes(entry));
+    result.permissions = {
+      ...existingPermissions,
+      ...incomingPermissions,
+      deny: [...new Set([...preservedDeny, ...incomingDeny])],
+    };
+  }
+  return result;
+}
+
+function reconcileShell(existing: string | null, incoming: string): string {
+  const incomingBlock = `${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, incomingBlock).replace(/\s*$/, "\n");
+  return `${existing.replace(/\s*$/, "\n\n")}${incomingBlock}\n`;
+}
+
+function reconcilePackageJson(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": "phasegate lint",
+      "phasegate:check-ready": "phasegate phasegate:check-ready",
+      "phasegate:doctor": "phasegate doctor",
+    },
+    devDependencies: {
+      ...devDependencies,
+      phasegate: `^${version}`,
+    },
+  };
+}
+
+export class RunReconcileUseCase {
+  constructor(
+    private readonly manifestRepository: ManifestRepositoryPort,
+    private readonly hashCalculator: HashCalculatorPort,
+  ) {}
+
+  async execute(input: RunReconcileInput): Promise<RunReconcileResult> {
+    const manifest = await this.manifestRepository.load(input.projectRoot);
+    if (manifest === null) {
+      const item = this.item(
+        ".phasegate/manifest.json",
+        "missing-manifest",
+        "manual",
+        "unknown",
+        false,
+        "manifest missing; run phasegate install before reconcile",
+        "manual setup required",
+        SKILL_HINT,
+      );
+      return { plan: [item], refused: [], changed: [], backupDir: null };
+    }
+
+    const targets = this.createTargets();
+    const targetsByPath = new Map(targets.map((target) => [target.path, target]));
+    let nextManifest = DeploymentManifest.reconstitute({
+      version: input.phasegateVersion,
+      installedAt: manifest.installedAt,
+      entries: manifest.entries,
+    });
+    const plan: ReconcilePlanItem[] = [];
+    const refused: ReconcilePlanItem[] = [];
+    const changed: ReconcilePlanItem[] = [];
+    const backupStamp = `reconcile-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+    let backupDir: string | null = null;
+
+    const outcomes: Array<{
+      readonly item: ReconcilePlanItem;
+      readonly needsBackup: boolean;
+      readonly apply: () => Promise<string | null>;
+    }> = [];
+
+    for (const entry of manifest.entries) {
+      const target = targetsByPath.get(entry.path);
+      if (target === undefined) {
+        const item = this.item(entry.path, "skip", "manual", "unknown", false, `${entry.path}: no bundled template`, "manual review required", SKILL_HINT);
+        plan.push(item);
+        continue;
+      }
+      const outcome = await this.planManagedEntry(input, entry, target);
+      outcomes.push(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" });
+      }
+    }
+
+    for (const target of targets) {
+      if (manifest.findEntry(target.path) !== null) continue;
+      const outcome = await this.planMissingTarget(input, target);
+      outcomes.push(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 };
+    }
+
+    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.item.path, backupDir);
+      }
+      const hashContent = await outcome.apply();
+      changed.push(outcome.item);
+      if (hashContent !== null) {
+        const mode = outcome.item.strategy === "symlink" ? "symlink" : outcome.item.action === "add" ? "created" : (manifest.findEntry(outcome.item.path)?.mode ?? "merged");
+        nextManifest = nextManifest.addEntry(
+          DeploymentEntry.create({
+            path: outcome.item.path,
+            mode,
+            block: mode === "merged" ? this.managedBlockFor(outcome.item.path, outcome.item.strategy) : null,
+            hash: this.hashCalculator.compute(hashContent),
+            deployedAt: new Date().toISOString(),
+          }),
+        );
+      }
+    }
+
+    if (changed.length > 0 || manifest.version !== input.phasegateVersion) {
+      await this.manifestRepository.save(input.projectRoot, nextManifest);
+    }
+    return { plan, refused, changed, backupDir };
+  }
+
+  private async planManagedEntry(input: RunReconcileInput, entry: DeploymentEntry, target: ReconcileTarget) {
+    if (target.strategy === "symlink") return this.planSymlink(input.projectRoot, target.path);
+    const absolutePath = this.resolveProjectPath(input.projectRoot, entry.path);
+    const before = await readTextOrNull(absolutePath);
+    if (before === null) return this.planMissingTarget(input, target);
+    const currentHash = this.hashCalculator.compute(before);
+    const matchesManifest = currentHash.equals(entry.hash);
+    const template = target.templatePath ? await readFile(join(input.harnessRoot, target.templatePath), "utf8") : "";
+    const next = entry.mode === "created" && target.strategy !== "package-json"
+      ? template
+      : this.reconcileContent(target, before, template, input.phasegateVersion);
+    const changed = before !== next;
+    const repairMode: RepairMode = matchesManifest ? "mechanical" : "ai-assisted";
+    return {
+      item: this.item(
+        entry.path,
+        changed ? "update" : "skip",
+        repairMode,
+        target.strategy,
+        changed,
+        changed ? `${entry.path}: update managed portion` : `${entry.path}: already up to date`,
+        this.diffSummary(before, next),
+        repairMode === "ai-assisted" ? SKILL_HINT : null,
+      ),
+      needsBackup: !matchesManifest || input.force,
+      apply: async () => {
+        await mkdir(dirname(absolutePath), { recursive: true });
+        await writeFile(absolutePath, next, "utf8");
+        if (target.executable) await chmod(absolutePath, 0o755);
+        return next;
+      },
+    };
+  }
+
+  private async planMissingTarget(input: RunReconcileInput, target: ReconcileTarget) {
+    if (target.strategy === "symlink") return this.planSymlink(input.projectRoot, target.path);
+    const absolutePath = this.resolveProjectPath(input.projectRoot, target.path);
+    const before = await readTextOrNull(absolutePath);
+    const template = target.templatePath ? await readFile(join(input.harnessRoot, target.templatePath), "utf8") : "";
+    const next = before === null && target.strategy !== "package-json"
+      ? template
+      : this.reconcileContent(target, before, template, input.phasegateVersion);
+    const changed = before !== next;
+    const repairMode: RepairMode = target.strategy === "shell" && before !== null && !before.includes(SHELL_BEGIN) ? "ai-assisted" : "mechanical";
+    return {
+      item: this.item(
+        target.path,
+        before === null ? "add" : changed ? "update" : "skip",
+        repairMode,
+        target.strategy,
+        changed,
+        changed ? `${target.path}: add missing managed target` : `${target.path}: already up to date`,
+        this.diffSummary(before, next),
+        repairMode === "ai-assisted" ? SKILL_HINT : null,
+      ),
+      needsBackup: before !== null,
+      apply: async () => {
+        await mkdir(dirname(absolutePath), { recursive: true });
+        await writeFile(absolutePath, next, "utf8");
+        if (target.executable) await chmod(absolutePath, 0o755);
+        return next;
+      },
+    };
+  }
+
+  private async planSymlink(projectRoot: string, relativePath: string) {
+    const absolutePath = this.resolveProjectPath(projectRoot, relativePath);
+    try {
+      const stat = await lstat(absolutePath);
+      if (stat.isSymbolicLink() && (await readlink(absolutePath)) === "../skills") {
+        return {
+          item: this.item(relativePath, "skip", "mechanical", "symlink", false, `${relativePath}: already linked`, "no changes", null),
+          needsBackup: false,
+          apply: async () => "../skills",
+        };
+      }
+      return {
+        item: this.item(relativePath, "skip", "manual", "symlink", false, `${relativePath}: existing non-phasegate path requires manual review`, "manual review required", SKILL_HINT),
+        needsBackup: false,
+        apply: async () => null,
+      };
+    } catch {
+      return {
+        item: this.item(relativePath, "link", "mechanical", "symlink", true, `${relativePath}: create symlink`, "+ symlink ../skills", null),
+        needsBackup: false,
+        apply: async () => {
+          await mkdir(join(projectRoot, "skills"), { recursive: true });
+          await mkdir(dirname(absolutePath), { recursive: true });
+          await symlink("../skills", absolutePath, process.platform === "win32" ? "junction" : "dir");
+          return "../skills";
+        },
+      };
+    }
+  }
+
+  private reconcileContent(target: ReconcileTarget, before: string | null, template: string, version: string): string {
+    if (target.strategy === "yaml-add") return template;
+    if (target.strategy === "shell") return reconcileShell(before, template);
+    if (target.strategy === "package-json") {
+      const existing = before === null ? {} : (JSON.parse(before) as unknown);
+      return `${JSON.stringify(reconcilePackageJson(isRecord(existing) ? existing : {}, version), null, 2)}\n`;
+    }
+    const existing = before === null ? {} : (JSON.parse(before) as unknown);
+    const incoming = JSON.parse(template) as unknown;
+    return `${JSON.stringify(reconcileJsonObject(isRecord(existing) ? existing : {}, isRecord(incoming) ? incoming : {}), null, 2)}\n`;
+  }
+
+  private createTargets(): readonly ReconcileTarget[] {
+    return [
+      { path: ".claude/settings.json", strategy: "json", templatePath: "templates/.claude/settings.json" },
+      { path: ".codex/hooks.json", strategy: "json", templatePath: "templates/.codex/hooks.json" },
+      {
+        path: ".husky/pre-commit",
+        strategy: "shell",
+        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",
+        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",
+        templatePath: "docs/templates/hooks/pre-push",
+        executable: true,
+        block: { start: SHELL_BEGIN, end: SHELL_END, content: "phasegate pre-push managed block" },
+      },
+      { path: ".github/workflows/phasegate-aidlc-gate.yml", strategy: "yaml-add", templatePath: "docs/templates/ci/aidlc-gate.yml" },
+      { path: "package.json", strategy: "package-json", templatePath: "package.json" },
+      { path: ".claude/skills", strategy: "symlink" },
+      { path: ".codex/skills", strategy: "symlink" },
+    ];
+  }
+
+  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 managedBlockFor(path: string, strategy: StrategyType): ManagedBlockInput | null {
+    if (strategy === "shell") return { start: SHELL_BEGIN, end: SHELL_END, content: `phasegate ${path} managed block` };
+    if (strategy === "json" || strategy === "package-json") {
+      return { start: "phasegate structured merge", end: "phasegate structured merge", content: `${strategy}:${path}` };
+    }
+    return null;
+  }
+
+  private resolveProjectPath(projectRoot: string, relativePath: string): string {
+    const absolutePath = resolve(projectRoot, relativePath);
+    const root = resolve(projectRoot);
+    if (absolutePath !== root && !absolutePath.startsWith(`${root}/`) && relative(root, absolutePath).startsWith("..")) {
+      throw new Error(`Manifest entry escapes project root: ${relativePath}`);
+    }
+    return absolutePath;
+  }
+
+  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`;
+  }
+
+  private item(
+    path: string,
+    action: ReconcileAction,
+    repairMode: RepairMode,
+    strategy: StrategyType,
+    changed: boolean,
+    summary: string,
+    diff: string,
+    skillHint: string | null,
+  ): ReconcilePlanItem {
+    return { path, action, repairMode, strategy, changed, summary, diff, skillHint };
+  }
+}