phasegate 0.152.9 → 0.153.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.153.0] - 2026-05-13
+
+### Added
+
+- **WI-175 — agent setup completeness and confidence** — adds `setup:agent` completeness summaries, `config:plan` managed/external action separation with `phasegate.config.json` patch previews, target-aware install permission error guidance, and regression coverage for strict setup no-diff behavior.
+
 ## [0.152.9] - 2026-05-13
 
 ### Added

package/README.md

@@ -109,6 +109,8 @@ npx phasegate setup:agent --intent recommended --dry-run --json
 npx phasegate config:plan --intent codex-hooks --dry-run --json
 ```
 
+`setup:agent --json` includes `plan.completeness`, which separates local configured/planned areas from external manual checks such as Codex user-level feature enablement or the first CI run. `config:plan` includes a read-only `configPatch` preview when an intent would change `phasegate.config.json`. <!-- @work-item-id WI-175 -->
+
 The first command reports detected setup state, missing questions, planned managed targets, rollback, and validation. The second maps a configuration change intent to files, commands, risks, and checks. <!-- @work-item-id WI-172, WI-173 -->
 
 To remove PhaseGate from that project later, run:

package/docs/guide/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-<!-- @work-item-id WI-171 -->
+<!-- @work-item-id WI-171, WI-175 -->
 
 Use this page when you want the shortest path from "PhaseGate is installed" to "the next command is obvious".
 
@@ -31,6 +31,8 @@ The first successful run is:
 - L2 validators pass or report only issues you intentionally left for a later rollout.
 - The active agent can read `AGENTS.md` or `CLAUDE.md` and see the PhaseGate managed instructions.
 
+`setup:agent --json` also returns `plan.completeness`. Treat `configured` and `planned` as local repository evidence, and treat `manual` entries as work PhaseGate cannot prove from local files, such as Codex user-level feature enablement or the first hosted CI run.
+
 ## Daily Use
 
 ```bash
@@ -48,7 +50,7 @@ npx phasegate setup:agent --dry-run --json
 npx phasegate config:plan --intent codex-hooks --dry-run --json
 ```
 
-`setup:agent` reads repository setup state and returns missing targets, questions, risk, rollback, and validation steps. `config:plan` maps natural-language change intents such as "enable Codex hooks" or "make L4 stricter" to concrete files, commands, and checks.
+`setup:agent` reads repository setup state and returns missing targets, completeness, questions, risk, rollback, and validation steps. `config:plan` maps natural-language change intents such as "enable Codex hooks" or "make L4 stricter" to concrete files, commands, checks, and a read-only `phasegate.config.json` patch preview when the intent changes local config.
 
 ## CI Use
 

package/docs/guide/recipes.md

@@ -62,4 +62,4 @@ npx phasegate check-change-category --paths <changed-files> --format json
 npx phasegate ci-check --quick --dry-run
 ```
 
-Use `config:plan` before changing `phasegate.config.json`. It separates repo-managed artifacts from user-level settings and lists the checks needed after the change.
+Use `config:plan` before changing `phasegate.config.json`. It separates repo-managed artifacts from user-level settings, previews the local config before/after for config-backed intents, and lists the checks needed after the change. <!-- @work-item-id WI-175 -->

package/docs/guide/troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshooting
 
-<!-- @work-item-id WI-171, WI-172, WI-173 -->
+<!-- @work-item-id WI-171, WI-172, WI-173, WI-175 -->
 
 Start with:
 
@@ -58,3 +58,16 @@ npx phasegate config:plan --intent codex-hooks --dry-run --json
 ```
 
 The planner output is intentionally agent-readable: detected state, questions, planned targets, risks, rollback, and validation commands are all explicit.
+
+## Setup Completeness Still Has Manual Checks
+
+`doctor` green means the local managed setup is consistent for the inspected targets. It does not prove user-level Codex feature flags, hosted GitHub Actions execution, npm registry state, or team policy acceptance.
+
+Check `plan.completeness` in `setup:agent --json`:
+
+- `configured`: PhaseGate found local evidence.
+- `planned`: `--apply` will create or refresh the local target.
+- `manual`: complete the listed external action yourself.
+- `not-applicable`: the current intent/options did not select that area.
+
+When `install` or `setup:agent --apply` returns a structured `error`, use its `target`, `operation`, `code`, `recovery`, and `partialChanges` fields before rerunning.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.152.9",
+  "version": "0.153.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/installation/application/usecases/run-install.ts

@@ -2,6 +2,7 @@
 // @layer application
 // @work-item-id WI-146
 // @work-item-id WI-174
+// @work-item-id WI-175
 
 import { mkdir, readFile, writeFile, copyFile, chmod, access, lstat, readlink, symlink } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -47,6 +48,16 @@ export interface RunInstallResult {
   readonly refused: readonly InstallPlanItem[];
   readonly changed: readonly InstallPlanItem[];
   readonly backupDir: string | null;
+  readonly error?: TargetAwareApplyError;
+}
+
+export interface TargetAwareApplyError {
+  readonly target: string;
+  readonly operation: string;
+  readonly code: string;
+  readonly likelyCause: string;
+  readonly recovery: string;
+  readonly partialChanges: readonly string[];
 }
 
 interface InstallTarget {
@@ -216,6 +227,26 @@ function hasCustomJson(content: string | null): boolean {
   }
 }
 
+function errorCode(error: unknown): string {
+  if (isRecord(error) && typeof error.code === "string") return error.code;
+  return "UNKNOWN";
+}
+
+function likelyCauseFor(code: string): string {
+  if (code === "EPERM") return "The filesystem or sandbox denied this write operation.";
+  if (code === "EACCES") return "The current user does not have permission to write this target.";
+  if (code === "EROFS") return "The project is on a read-only filesystem.";
+  if (code === "ENOTDIR") return "A parent path exists but is not a directory.";
+  return "The managed target could not be written.";
+}
+
+function recoveryFor(code: string, target: string): string {
+  if (code === "EPERM") return `Review sandbox or filesystem permissions for ${target}, then rerun phasegate setup:agent --apply or phasegate install --apply.`;
+  if (code === "EACCES") return `Fix ownership or permissions for ${target}, then rerun phasegate install --apply.`;
+  if (code === "EROFS") return `Move the project to a writable filesystem or rerun in a writable workspace before applying ${target}.`;
+  return `Inspect ${target}, run phasegate install --dry-run --json, then rerun with --apply after resolving the filesystem issue.`;
+}
+
 function shellRepairMode(content: string | null): RepairMode {
   if (content === null || content.trim().length === 0 || content.includes(SHELL_BEGIN)) return "mechanical";
   return "ai-assisted";
@@ -289,9 +320,23 @@ export class RunInstallUseCase {
         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);
+        try {
+          await mkdir(dirname(absolutePath), { recursive: true });
+        } catch (error) {
+          return this.withApplyError({ plan, refused, changed, backupDir }, target.path, "mkdir", error);
+        }
+        try {
+          await writeFile(absolutePath, next, "utf8");
+        } catch (error) {
+          return this.withApplyError({ plan, refused, changed, backupDir }, target.path, "writeFile", error);
+        }
+        if (target.executable) {
+          try {
+            await chmod(absolutePath, 0o755);
+          } catch (error) {
+            return this.withApplyError({ plan, refused, changed, backupDir }, target.path, "chmod", error);
+          }
+        }
       changed.push(item);
 
       const mode = before === null ? "created" : "merged";
@@ -320,9 +365,17 @@ export class RunInstallUseCase {
       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");
+      try {
+        await mkdir(join(input.projectRoot, "skills"), { recursive: true });
+        await mkdir(dirname(join(input.projectRoot, linkPath)), { recursive: true });
+      } catch (error) {
+        return this.withApplyError({ plan, refused, changed, backupDir }, linkPath, "mkdir", error);
+      }
+      try {
+        await symlink("../skills", join(input.projectRoot, linkPath), process.platform === "win32" ? "junction" : "dir");
+      } catch (error) {
+        return this.withApplyError({ plan, refused, changed, backupDir }, linkPath, "symlink", error);
+      }
       changed.push(item);
       const hash = this.hashCalculator.compute("../skills");
       const existingEntry = baseManifest.findEntry(linkPath);
@@ -342,12 +395,36 @@ export class RunInstallUseCase {
     }
 
     if (input.apply && changed.length > 0) {
-      await this.manifestRepository.save(input.projectRoot, manifest);
+      try {
+        await this.manifestRepository.save(input.projectRoot, manifest);
+      } catch (error) {
+        return this.withApplyError({ plan, refused, changed, backupDir }, ".phasegate/manifest.json", "manifest-save", error);
+      }
     }
 
     return { plan, refused, changed, backupDir };
   }
 
+  private withApplyError(
+    result: RunInstallResult,
+    target: string,
+    operation: string,
+    error: unknown,
+  ): RunInstallResult {
+    const code = errorCode(error);
+    return {
+      ...result,
+      error: {
+        target,
+        operation,
+        code,
+        likelyCause: likelyCauseFor(code),
+        recovery: recoveryFor(code, target),
+        partialChanges: result.changed.map((item) => item.path),
+      },
+    };
+  }
+
   private createTargets(options: {
     readonly includeClaude: boolean;
     readonly includeCodex: boolean;

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

@@ -1,6 +1,7 @@
 // @unit installation
 // @layer presentation
 // @work-item-id WI-146
+// @work-item-id WI-175
 
 import type { RunInstallUseCase } from "../../application/usecases/run-install.js";
 
@@ -34,7 +35,7 @@ export class InstallHandler {
     if (input.json) {
       return {
         stdout: JSON.stringify(result, null, 2),
-        exitCode: result.refused.length > 0 ? 1 : 0,
+        exitCode: result.refused.length > 0 || result.error !== undefined ? 1 : 0,
       };
     }
     const lines = [
@@ -45,13 +46,20 @@ export class InstallHandler {
       }),
     ];
     if (result.backupDir !== null) lines.push(`backups: ${result.backupDir}`);
+    if (result.error !== undefined) {
+      lines.push("");
+      lines.push(`Apply error: ${result.error.target} ${result.error.operation} failed with ${result.error.code}`);
+      lines.push(`Cause: ${result.error.likelyCause}`);
+      lines.push(`Recovery: ${result.error.recovery}`);
+      if (result.error.partialChanges.length > 0) lines.push(`Partial changes: ${result.error.partialChanges.join(", ")}`);
+    }
     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,
+      exitCode: result.refused.length > 0 || result.error !== undefined ? 1 : 0,
     };
   }
 }

package/scripts/harness/main.ts

@@ -4,6 +4,7 @@
  * @work-item-id WI-090 / WI-091
  * @work-item-id WI-113 / WI-142
  * @work-item-id WI-171 / WI-172 / WI-173
+ * @work-item-id WI-175
  *
  * Phasegate CLI エントリポイント。
  * 各Unitの Composition Root からハンドラーを取得し、コマンドに応じてディスパッチする。
@@ -723,6 +724,31 @@ type InitPhasePreset = "full" | "standard" | "minimal" | "custom";
 type AgentTarget = "claude" | "codex" | "both";
 type SetupIntent = "minimal" | "recommended" | "strict" | "ci-only" | "agent-hooks" | "retrofit";
 type ConfigChangeIntent = "l4-strict" | "codex-hooks" | "ci-fail-on-warning" | "baseline-reset" | "quick-mode-strict";
+type SetupCompletenessStatus = "configured" | "planned" | "manual" | "not-applicable" | "unknown";
+
+interface SetupCompletenessEntry {
+  readonly area: string;
+  readonly status: SetupCompletenessStatus;
+  readonly evidence: readonly string[];
+  readonly nextAction: string | null;
+  readonly risk: string | null;
+}
+
+interface ConfigPatchOperation {
+  readonly op: "add" | "replace";
+  readonly pointer: string;
+  readonly before: unknown;
+  readonly after: unknown;
+}
+
+interface ConfigPatchPreview {
+  readonly path: "phasegate.config.json";
+  readonly applicability: "applicable" | "not-applicable" | "blocked";
+  readonly blockedReason: string | null;
+  readonly before: unknown;
+  readonly after: unknown;
+  readonly operations: readonly ConfigPatchOperation[];
+}
 
 function parseInitPhasePreset(value: string | undefined): InitPhasePreset | undefined {
   if (value === undefined) return undefined;
@@ -773,6 +799,138 @@ async function projectFileExists(rootDir: string, relativePath: string): Promise
   }
 }
 
+function setupCompletenessEntry(input: {
+  readonly area: string;
+  readonly included: boolean;
+  readonly configured: boolean;
+  readonly plannedEvidence: string;
+  readonly configuredEvidence: string;
+  readonly nextAction: string;
+  readonly risk?: string;
+}): SetupCompletenessEntry {
+  if (!input.included) {
+    return {
+      area: input.area,
+      status: "not-applicable",
+      evidence: ["Not selected for this setup intent/options."],
+      nextAction: null,
+      risk: null,
+    };
+  }
+  if (input.configured) {
+    return {
+      area: input.area,
+      status: "configured",
+      evidence: [input.configuredEvidence],
+      nextAction: null,
+      risk: input.risk ?? null,
+    };
+  }
+  return {
+    area: input.area,
+    status: "planned",
+    evidence: [input.plannedEvidence],
+    nextAction: input.nextAction,
+    risk: input.risk ?? null,
+  };
+}
+
+function buildSetupCompleteness(input: {
+  readonly intent: SetupIntent;
+  readonly agent: AgentTarget;
+  readonly withHusky: boolean;
+  readonly withCi: boolean;
+  readonly checks: {
+    readonly packageJson: boolean;
+    readonly phasegateConfig: boolean;
+    readonly claudeSettings: boolean;
+    readonly codexHooks: boolean;
+    readonly agentsMd: boolean;
+    readonly claudeMd: boolean;
+    readonly huskyPreCommit: boolean;
+    readonly ciWorkflow: boolean;
+    readonly skillsVersion: boolean;
+  };
+}): readonly SetupCompletenessEntry[] {
+  const includeClaude = input.agent === "claude" || input.agent === "both";
+  const includeCodex = input.agent === "codex" || input.agent === "both";
+  const agentHooksConfigured = (!includeClaude || input.checks.claudeSettings) && (!includeCodex || input.checks.codexHooks);
+  const agentContextConfigured = (!includeClaude || input.checks.claudeMd) && (!includeCodex || input.checks.agentsMd);
+  const entries: SetupCompletenessEntry[] = [
+    setupCompletenessEntry({
+      area: "local-config",
+      included: true,
+      configured: input.checks.packageJson && input.checks.phasegateConfig,
+      configuredEvidence: "package.json and phasegate.config.json are present.",
+      plannedEvidence: "setup:agent will create or merge package.json scripts and phasegate.config.json.",
+      nextAction: "Run setup:agent --apply, then phasegate doctor.",
+    }),
+    setupCompletenessEntry({
+      area: "agent-hooks",
+      included: includeClaude || includeCodex,
+      configured: agentHooksConfigured,
+      configuredEvidence: "Selected agent hook settings are present.",
+      plannedEvidence: "setup:agent will create or refresh selected agent hook settings.",
+      nextAction: "Run setup:agent --apply for selected agents.",
+      risk: includeCodex ? "Codex user-level hook feature enablement remains a manual external check." : undefined,
+    }),
+    setupCompletenessEntry({
+      area: "agent-context",
+      included: includeClaude || includeCodex,
+      configured: agentContextConfigured,
+      configuredEvidence: "Selected AGENTS.md / CLAUDE.md managed context files are present.",
+      plannedEvidence: "setup:agent will create or refresh selected managed agent context sections.",
+      nextAction: "Run setup:agent --apply and review preserved user-owned content.",
+    }),
+    setupCompletenessEntry({
+      area: "skills",
+      included: true,
+      configured: input.checks.skillsVersion,
+      configuredEvidence: "skills/.harness-version is present.",
+      plannedEvidence: "setup:agent will deploy bundled PhaseGate skills.",
+      nextAction: "Run setup:agent --apply to deploy skills.",
+    }),
+    setupCompletenessEntry({
+      area: "git-hooks",
+      included: input.withHusky,
+      configured: input.checks.huskyPreCommit,
+      configuredEvidence: ".husky/pre-commit is present.",
+      plannedEvidence: "setup:agent will create or refresh Husky pre-commit, commit-msg, and pre-push hooks.",
+      nextAction: "Run setup:agent --apply --with-husky.",
+    }),
+    setupCompletenessEntry({
+      area: "ci",
+      included: input.withCi,
+      configured: input.checks.ciWorkflow,
+      configuredEvidence: ".github/workflows/phasegate-aidlc-gate.yml is present.",
+      plannedEvidence: "setup:agent will create or refresh the GitHub Actions PhaseGate workflow.",
+      nextAction: "Run setup:agent --apply --with-ci.",
+      risk: "A hosted CI run is still an external manual check.",
+    }),
+    setupCompletenessEntry({
+      area: "validation",
+      included: true,
+      configured: input.checks.packageJson && input.checks.phasegateConfig,
+      configuredEvidence: "Local validation commands can be run against the configured project.",
+      plannedEvidence: "Validation commands are planned after setup apply.",
+      nextAction: "Run phasegate doctor, phasegate phasegate:check-ready, and phasegate validate --layer L2 --format human.",
+    }),
+  ];
+
+  const externalActions: string[] = [];
+  if (includeCodex) externalActions.push("Run codex features enable codex_hooks if Codex hooks are not enabled for the user.");
+  if (input.withCi) externalActions.push("Trigger or inspect the first GitHub Actions PhaseGate workflow run.");
+  if (input.intent === "strict") externalActions.push("Confirm team policy accepts strict local and CI enforcement.");
+  entries.push({
+    area: "external-actions",
+    status: externalActions.length > 0 ? "manual" : "not-applicable",
+    evidence: externalActions.length > 0 ? externalActions : ["No external manual checks selected for this setup run."],
+    nextAction: externalActions.length > 0 ? externalActions.join(" ") : null,
+    risk: externalActions.length > 0 ? "PhaseGate cannot prove these user-level or hosted-service states from local files." : null,
+  });
+  return entries;
+}
+
 async function buildAgentSetupPlan(rootDir: string, input: {
   readonly intent: SetupIntent;
   readonly agent: AgentTarget;
@@ -789,6 +947,7 @@ async function buildAgentSetupPlan(rootDir: string, input: {
     claudeMd: await projectFileExists(rootDir, "CLAUDE.md"),
     huskyPreCommit: await projectFileExists(rootDir, ".husky/pre-commit"),
     ciWorkflow: await projectFileExists(rootDir, ".github/workflows/phasegate-aidlc-gate.yml"),
+    skillsVersion: await projectFileExists(rootDir, "skills/.harness-version"),
   };
   const includeClaude = input.agent === "claude" || input.agent === "both";
   const includeCodex = input.agent === "codex" || input.agent === "both";
@@ -810,6 +969,7 @@ async function buildAgentSetupPlan(rootDir: string, input: {
     intent: input.intent,
     agent: input.agent,
     detected: checks,
+    completeness: buildSetupCompleteness({ ...input, checks }),
     questions,
     changes,
     risks: [
@@ -829,47 +989,148 @@ async function buildAgentSetupPlan(rootDir: string, input: {
   };
 }
 
-function buildConfigChangePlan(intent: ConfigChangeIntent) {
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function readProjectJson(rootDir: string, relativePath: string): Promise<unknown | null> {
+  try {
+    return JSON.parse(await fsReadFile(join(rootDir, relativePath), "utf8")) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+function withNestedValue(source: unknown, path: readonly string[], value: unknown): Record<string, unknown> {
+  const root = isPlainRecord(source) ? { ...source } : {};
+  let cursor = root;
+  for (const segment of path.slice(0, -1)) {
+    const next = cursor[segment];
+    cursor[segment] = isPlainRecord(next) ? { ...next } : {};
+    cursor = cursor[segment] as Record<string, unknown>;
+  }
+  cursor[path[path.length - 1]] = value;
+  return root;
+}
+
+function getNestedValue(source: unknown, path: readonly string[]): unknown {
+  let cursor = source;
+  for (const segment of path) {
+    if (!isPlainRecord(cursor)) return undefined;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+
+function buildConfigPatchPreview(intent: ConfigChangeIntent, before: unknown | null): ConfigPatchPreview {
+  const configIntents: Record<ConfigChangeIntent, readonly { readonly pointer: string; readonly path: readonly string[]; readonly value: unknown }[]> = {
+    "l4-strict": [
+      { pointer: "/layers/L4/enabled", path: ["layers", "L4", "enabled"], value: true },
+      { pointer: "/layers/L4/failOnWarning", path: ["layers", "L4", "failOnWarning"], value: true },
+    ],
+    "ci-fail-on-warning": [
+      { pointer: "/ci/enabled", path: ["ci", "enabled"], value: true },
+      { pointer: "/layers/L4/failOnWarning", path: ["layers", "L4", "failOnWarning"], value: true },
+    ],
+    "quick-mode-strict": [
+      { pointer: "/quickMode/allowedCategories", path: ["quickMode", "allowedCategories"], value: ["chore"] },
+      { pointer: "/quickMode/relaxedGates", path: ["quickMode", "relaxedGates"], value: [] },
+    ],
+    "codex-hooks": [],
+    "baseline-reset": [],
+  };
+  const changes = configIntents[intent];
+  if (changes.length === 0) {
+    return {
+      path: "phasegate.config.json",
+      applicability: "not-applicable",
+      blockedReason: "Selected intent does not require a local phasegate.config.json mutation.",
+      before,
+      after: before,
+      operations: [],
+    };
+  }
+  let after: unknown = before;
+  const operations: ConfigPatchOperation[] = [];
+  for (const change of changes) {
+    const previous = getNestedValue(after, change.path);
+    after = withNestedValue(after, change.path, change.value);
+    operations.push({
+      op: previous === undefined ? "add" : "replace",
+      pointer: change.pointer,
+      before: previous ?? null,
+      after: change.value,
+    });
+  }
+  return {
+    path: "phasegate.config.json",
+    applicability: "applicable",
+    blockedReason: null,
+    before,
+    after,
+    operations,
+  };
+}
+
+function hasStructuredInstallError(value: unknown): boolean {
+  return isPlainRecord(value) && isPlainRecord(value.error);
+}
+
+async function buildConfigChangePlan(rootDir: string, intent: ConfigChangeIntent) {
   const catalog: Record<ConfigChangeIntent, {
     readonly targets: readonly string[];
+    readonly managedTargets: readonly string[];
+    readonly externalActions: readonly { readonly id: string; readonly label: string; readonly command: string | null; readonly blocking: boolean }[];
     readonly commands: readonly string[];
     readonly validations: readonly string[];
     readonly risks: readonly string[];
   }> = {
     "l4-strict": {
       targets: ["phasegate.config.json: layers.L4.enabled", "phasegate.config.json: layers.L4.failOnWarning"],
+      managedTargets: ["phasegate.config.json"],
+      externalActions: [],
       commands: ["phasegate validate --layer L4 --fail-on-warning --format human"],
       validations: ["phasegate phasegate:detect-drift --json", "phasegate phasegate:check-ready"],
       risks: ["L4 findings may be advisory today but become blocking when fail-on-warning is enabled."],
     },
     "codex-hooks": {
       targets: [".codex/hooks.json", "AGENTS.md", ".codex/skills"],
+      managedTargets: [".codex/hooks.json", "AGENTS.md", ".codex/skills"],
+      externalActions: [{ id: "codex-hooks-feature", label: "Enable Codex user-level hooks feature.", command: "codex features enable codex_hooks", blocking: true }],
       commands: ["phasegate install --agent codex --apply", "codex features enable codex_hooks"],
       validations: ["phasegate doctor --json", "phasegate phasegate:status --json"],
       risks: ["Codex apply_patch writes still require the pre-commit backstop for full coverage."],
     },
     "ci-fail-on-warning": {
       targets: [".github/workflows/phasegate-aidlc-gate.yml", "phasegate.config.json"],
+      managedTargets: [".github/workflows/phasegate-aidlc-gate.yml", "phasegate.config.json"],
+      externalActions: [{ id: "github-actions-first-run", label: "Trigger or inspect the first GitHub Actions PhaseGate run.", command: null, blocking: false }],
       commands: ["phasegate install --with-ci --apply", "phasegate validate --layer L4 --fail-on-warning"],
       validations: ["phasegate doctor", "phasegate ci:generate-template --type aidlc-gate --render"],
       risks: ["Existing warning-only projects may start failing CI after rollout."],
     },
     "baseline-reset": {
       targets: [".phasegate/baseline.json"],
+      managedTargets: [".phasegate/baseline.json"],
+      externalActions: [],
       commands: ["phasegate baseline --dry-run", "phasegate baseline --force --json"],
       validations: ["phasegate phasegate:status --json", "phasegate phasegate:check-ready"],
       risks: ["A reset can hide historical drift if reviewed without the generated diff."],
     },
     "quick-mode-strict": {
       targets: ["phasegate.config.json: quickMode"],
+      managedTargets: ["phasegate.config.json"],
+      externalActions: [],
       commands: ["phasegate check-change-category --paths <changed-files> --format json"],
       validations: ["phasegate ci-check --quick --dry-run", "phasegate phasegate:check-ready"],
       risks: ["More changes will require Full Mode validation before commit."],
     },
   };
+  const before = await readProjectJson(rootDir, "phasegate.config.json");
   return {
     intent,
     ...catalog[intent],
+    configPatch: buildConfigPatchPreview(intent, before),
     diffExplanation: "Review the listed targets first, apply through PhaseGate managed commands where possible, then run the validations in order.",
     rollback: "Use git diff for config changes; use phasegate uninstall/reconcile dry-runs for managed setup targets.",
   };
@@ -1315,7 +1576,7 @@ async function main(): Promise<void> {
           console.log("  • Q&A about phasegate concepts: invoke /phasegate-toolkit-guide");
           console.log("  • Diagnose & tune phasegate.config.json: invoke /phasegate-config-doctor");
         }
-        process.exit(0);
+        process.exit(hasStructuredInstallError(installResult) ? 1 : 0);
         break;
       }
 
@@ -1436,7 +1697,7 @@ async function main(): Promise<void> {
         const workflow = parseWorkflowMode(parseFlag(args, "--workflow") ?? (intent === "strict" ? "strict" : "standard"));
         const withCi = hasFlag(args, "--with-ci") || intent === "ci-only" || intent === "strict";
         const withHusky = hasFlag(args, "--with-husky") || intent === "agent-hooks" || intent === "strict";
-        const plan = await buildAgentSetupPlan(rootDir, { intent, agent, withHusky, withCi, workflow });
+        let plan = await buildAgentSetupPlan(rootDir, { intent, agent, withHusky, withCi, workflow });
         const apply = hasFlag(args, "--apply");
         let installResult: unknown = null;
         let bootstrapResult: unknown = null;
@@ -1469,6 +1730,7 @@ async function main(): Promise<void> {
             workflow,
             agent,
           });
+          plan = await buildAgentSetupPlan(rootDir, { intent, agent, withHusky, withCi, workflow });
         }
         const output = { plan, applied: apply, bootstrapResult, installResult };
         if (json) {
@@ -1496,7 +1758,7 @@ async function main(): Promise<void> {
           console.error(flagError);
           process.exit(2);
         }
-        const plan = buildConfigChangePlan(parseConfigChangeIntent(parseFlag(args, "--intent")));
+        const plan = await buildConfigChangePlan(rootDir, parseConfigChangeIntent(parseFlag(args, "--intent")));
         if (json) {
           console.log(JSON.stringify(plan, null, 2));
         } else {