phasegate 0.264.0 → 0.315.0

package/scripts/harness/installation/application/checks/config-status-check.ts

@@ -0,0 +1,52 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-330
+
+import type { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
+import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
+import type { ConfigStatusProbePort } from "../ports/config-status-probe-port.js";
+import type { FileInspectorPort } from "../ports/file-inspector-port.js";
+import { createFinding } from "./check-utils.js";
+
+/**
+ * WI-330 (GitHub #40 恒久化): phasegate.config.json の存在・妥当性を doctor で可視化する。
+ * - missing        → warn（既定設定の fail-open で動作していることをユーザーに知らせる）
+ * - invalid-json / invalid-schema → red（意図した設定が適用されていない）
+ * - valid          → finding なし
+ */
+export class ConfigStatusCheck implements HeuristicCheck {
+  readonly checkId = "config-status" as const;
+
+  constructor(private readonly probe: ConfigStatusProbePort) {}
+
+  async run(projectRoot: string, _inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
+    const result = await this.probe.probe(projectRoot);
+    if (result.status === "valid") {
+      return null;
+    }
+    if (result.status === "missing") {
+      return createFinding({
+        checkId: this.checkId,
+        severity: "warn",
+        target: result.configPath,
+        message:
+          "phasegate.config.json が存在しません（既定設定の fail-open モードで動作中）。`phasegate init` で生成できます",
+        repairMode: "mechanical",
+        repairHint: "npx phasegate init",
+      });
+    }
+    const reason = result.status === "invalid-json" ? "JSON 構文エラー" : "スキーマ違反";
+    const detail = result.detail !== null && result.detail.length > 0 ? ` — ${result.detail}` : "";
+    return createFinding({
+      checkId: this.checkId,
+      severity: "red",
+      target: result.configPath,
+      message: `phasegate.config.json が${reason}で壊れており、ユーザーの意図した設定が適用されていません（既定設定の fail-open モードで動作中）${detail}`,
+      repairMode: "manual",
+      repairHint:
+        result.status === "invalid-json"
+          ? "phasegate.config.json の JSON 構文エラーを修正するか、version control から復元してください"
+          : "報告されたパス・型のスキーマ違反を phasegate.config.json 上で修正するか、version control から復元してください",
+    });
+  }
+}

package/scripts/harness/installation/application/checks/husky-pre-commit-missing-check.ts

@@ -1,6 +1,7 @@
 // @unit installation
 // @layer application
 // @work-item-id WI-145
+// @work-item-id WI-340
 
 import type { FileInspectorPort } from "../ports/file-inspector-port.js";
 import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
@@ -22,6 +23,11 @@ export class HuskyPreCommitMissingCheck implements HeuristicCheck {
         "main.ts check-phase-gate",
         "$HARNESS_CMD lint",
         "$HARNESS_CMD check-phase-gate",
+        "phasegate pre-commit",
+        "main.ts pre-commit",
+        "$PHASEGATE_CMD lint",
+        "$PHASEGATE_CMD check-phase-gate",
+        "$PHASEGATE_CMD pre-commit",
       ])
     ) {
       return null;

package/scripts/harness/installation/application/ports/config-status-probe-port.ts

@@ -0,0 +1,9 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-330
+
+import type { ConfigStatusProbeResult } from "../../domain/config-status.js";
+
+export interface ConfigStatusProbePort {
+  probe(projectRoot: string): Promise<ConfigStatusProbeResult>;
+}

package/scripts/harness/installation/application/usecases/run-doctor-diagnostics.ts

@@ -4,11 +4,15 @@
 // @work-item-id WI-178
 // @work-item-id WI-208
 // @work-item-id WI-215
+// @work-item-id WI-330
+// @work-item-id WI-343
 
-import { DiagnosticReport } from "../../domain/diagnostic-report.js";
 import type { CheckId } from "../../domain/check-id.js";
+import type { ConfigStatus } from "../../domain/config-status.js";
 import type { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
+import { DiagnosticReport } from "../../domain/diagnostic-report.js";
 import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
+import type { ConfigStatusProbePort } from "../ports/config-status-probe-port.js";
 import type { FileInspectorPort } from "../ports/file-inspector-port.js";
 import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.js";
 
@@ -29,6 +33,7 @@ export interface RunDoctorDiagnosticsOutput {
   readonly report: DiagnosticReport;
   readonly agent: DoctorAgentScope;
   readonly installationMode: "project" | "personal";
+  readonly configStatus: ConfigStatus;
   readonly scopedOutFindings: readonly ScopedOutDiagnosticFinding[];
   readonly exitCode: number;
 }
@@ -48,15 +53,22 @@ export class RunDoctorDiagnosticsUseCase {
     private readonly checks: readonly HeuristicCheck[],
     private readonly inspector: FileInspectorPort,
     private readonly manifestRepository: ManifestRepositoryPort,
+    private readonly configStatusProbe: ConfigStatusProbePort,
   ) {}
 
   async execute(input: RunDoctorDiagnosticsInput): Promise<RunDoctorDiagnosticsOutput> {
     const agent = input.agent ?? "both";
     const manifest = await this.manifestRepository.load(input.projectRoot).catch(() => null);
-    const installationMode = manifest?.findEntry(".phasegate-local/phasegate.config.json") !== null && manifest !== null ? "personal" : "project";
-    const rawFindings = (await Promise.all(
-      this.checks.map((check) => check.run(input.projectRoot, this.inspector)),
-    )).filter((finding) => finding !== null);
+    const installationMode =
+      manifest?.findEntry(".phasegate-local/phasegate.config.json") !== null && manifest !== null
+        ? "personal"
+        : "project";
+    const configStatus = (await this.configStatusProbe.probe(input.projectRoot)).status;
+    const rawFindings = (
+      await Promise.all(
+        this.checks.map((check) => check.run(input.projectRoot, this.inspector, { installationMode })),
+      )
+    ).filter((finding) => finding !== null);
     const { findings, scopedOutFindings } = this.applyPersonalScope(
       this.applyAgentScope(rawFindings, agent),
       installationMode,
@@ -66,6 +78,7 @@ export class RunDoctorDiagnosticsUseCase {
       report,
       agent,
       installationMode,
+      configStatus,
       scopedOutFindings,
       exitCode: this.decideExitCode(report, input.strict),
     };
@@ -74,7 +87,10 @@ export class RunDoctorDiagnosticsUseCase {
   private applyAgentScope(
     findings: readonly DiagnosticFinding[],
     agent: DoctorAgentScope,
-  ): { readonly findings: readonly DiagnosticFinding[]; readonly scopedOutFindings: readonly ScopedOutDiagnosticFinding[] } {
+  ): {
+    readonly findings: readonly DiagnosticFinding[];
+    readonly scopedOutFindings: readonly ScopedOutDiagnosticFinding[];
+  } {
     if (agent === "both") return { findings, scopedOutFindings: [] };
     const scopedOutChecks = agent === "claude" ? CODEX_ONLY_CHECKS : CLAUDE_ONLY_CHECKS;
     const applicable: DiagnosticFinding[] = [];
@@ -93,9 +109,15 @@ export class RunDoctorDiagnosticsUseCase {
   }
 
   private applyPersonalScope(
-    scoped: { readonly findings: readonly DiagnosticFinding[]; readonly scopedOutFindings: readonly ScopedOutDiagnosticFinding[] },
+    scoped: {
+      readonly findings: readonly DiagnosticFinding[];
+      readonly scopedOutFindings: readonly ScopedOutDiagnosticFinding[];
+    },
     installationMode: "project" | "personal",
-  ): { readonly findings: readonly DiagnosticFinding[]; readonly scopedOutFindings: readonly ScopedOutDiagnosticFinding[] } {
+  ): {
+    readonly findings: readonly DiagnosticFinding[];
+    readonly scopedOutFindings: readonly ScopedOutDiagnosticFinding[];
+  } {
     if (installationMode !== "personal") return scoped;
     const applicable: DiagnosticFinding[] = [];
     const scopedOut: ScopedOutDiagnosticFinding[] = [...scoped.scopedOutFindings];

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

@@ -16,20 +16,44 @@
 // @work-item-id WI-215
 // @work-item-id WI-216
 // @work-item-id WI-219
-
-import { mkdir, readFile, writeFile, copyFile, chmod, access, lstat, readlink, symlink, readdir, rm } from "node:fs/promises";
+// @work-item-id WI-315
+// @work-item-id WI-326
+// @work-item-id WI-331
+
+import {
+  access,
+  chmod,
+  copyFile,
+  lstat,
+  mkdir,
+  readdir,
+  readFile,
+  readlink,
+  rm,
+  symlink,
+  writeFile,
+} 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 { DeploymentManifest, type InstallationFlags } from "../../domain/deployment-manifest.js";
 import type { ManagedBlockInput } from "../../domain/managed-block.js";
 import type { RepairMode } from "../../domain/repair-mode.js";
 import { getBundledSkillsForSet, type SkillSet } from "../bundled-skill-selection.js";
-import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.js";
 import type { HashCalculatorPort } from "../ports/hash-calculator-port.js";
+import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.js";
 import type { ModelDelegationPort } from "../ports/model-delegation-port.js";
 
 type InstallAction = "missing" | "will-merge" | "will-skip" | "will-overwrite";
-type StrategyType = "json" | "shell" | "yaml-add" | "package-json" | "markdown-managed" | "text-managed" | "copy" | "copy-dir" | "symlink";
+type StrategyType =
+  | "json"
+  | "shell"
+  | "yaml-add"
+  | "package-json"
+  | "markdown-managed"
+  | "text-managed"
+  | "copy"
+  | "copy-dir"
+  | "symlink";
 
 export interface InstallPlanItem {
   readonly path: string;
@@ -96,9 +120,17 @@ const SHELL_BEGIN = "# === phasegate managed (BEGIN) ===";
 const SHELL_END = "# === phasegate managed (END) ===";
 const MARKDOWN_BEGIN = "<!-- phasegate:managed-section:start -->";
 const MARKDOWN_END = "<!-- phasegate:managed-section:end -->";
+const USER_SECTION_BEGIN = "<!-- phasegate:user-section:start -->";
+const USER_SECTION_END = "<!-- phasegate:user-section:end -->";
+const USER_SECTION_PLACEHOLDER = "Project-specific agent instructions go here.";
 const TEXT_BEGIN = "# phasegate personal install exclude (BEGIN)";
 const TEXT_END = "# phasegate personal install exclude (END)";
-const PERSONAL_AGENT_RUNTIME_FILES = new Set([".claude/CLAUDE.md", ".claude/settings.json", "AGENTS.md", ".codex/hooks.json"]);
+const PERSONAL_AGENT_RUNTIME_FILES = new Set([
+  ".claude/CLAUDE.md",
+  ".claude/settings.json",
+  "AGENTS.md",
+  ".codex/hooks.json",
+]);
 const SHARED_SKILLS_VERSION_PATH = "skills/.harness-version";
 const PERSONAL_PRINCIPLES_DOCS = ".phasegate-local/docs/principles";
 const PERSONAL_FOLDER_RULES_DOC = ".phasegate-local/docs/folder_management_rules.md";
@@ -207,7 +239,10 @@ function mergeHookArrays(existing: unknown, incoming: unknown): unknown[] {
   return result;
 }
 
-function mergeJsonObject(existing: Record<string, unknown>, incoming: Record<string, unknown>): Record<string, unknown> {
+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 : {};
@@ -256,12 +291,71 @@ function managedMarkdownBlock(content: string): string {
   return content.slice(start, end + MARKDOWN_END.length).trim();
 }
 
+// Extracts the user-authored body between the user-section markers. Returns
+// null when the markers are absent or the body is blank, so callers fall back
+// to the template placeholder.
+function extractUserSectionBody(content: string | null): string | null {
+  if (content === null) return null;
+  const start = content.indexOf(USER_SECTION_BEGIN);
+  const end = content.indexOf(USER_SECTION_END);
+  if (start === -1 || end === -1 || end < start) return null;
+  const body = content.slice(start + USER_SECTION_BEGIN.length, end).trim();
+  return body.length === 0 ? null : body;
+}
+
+function hasUserSectionMarkers(content: string): boolean {
+  const start = content.indexOf(USER_SECTION_BEGIN);
+  const end = content.indexOf(USER_SECTION_END);
+  return start !== -1 && end !== -1 && start < end;
+}
+
+// Legacy (pre-WI-331) templates nested the user-section inside the managed
+// section, so replacing the managed block wholesale would wipe user-authored
+// instructions with the template placeholder. Re-inject the existing
+// user-section body into the incoming block. Blocks without user-section
+// markers (all current templates) are returned unchanged; the outside-of-block
+// migration for those is handled in mergeManagedMarkdown.
+function restoreUserSection(block: string, existing: string | null): string {
+  const start = block.indexOf(USER_SECTION_BEGIN);
+  const end = block.indexOf(USER_SECTION_END);
+  if (start === -1 || end === -1 || end < start) return block;
+  const preserved = extractUserSectionBody(existing);
+  if (preserved === null) return block;
+  return `${block.slice(0, start + USER_SECTION_BEGIN.length)}\n${preserved}\n${block.slice(end)}`;
+}
+
 function mergeManagedMarkdown(existing: string | null, incoming: string): string {
-  const block = managedMarkdownBlock(incoming);
   if (existing === null || existing.trim().length === 0) return `${incoming.trim()}\n`;
+  const incomingBlock = managedMarkdownBlock(incoming);
   const pattern = new RegExp(`${escapeRegExp(MARKDOWN_BEGIN)}[\\s\\S]*?${escapeRegExp(MARKDOWN_END)}`);
-  if (pattern.test(existing)) return existing.replace(pattern, block).replace(/\s*$/, "\n");
-  return `${block}\n\n${existing.replace(/\s*$/, "\n")}`;
+  if (!pattern.test(existing)) return `${incomingBlock}\n\n${existing.replace(/\s*$/, "\n")}`;
+
+  const blockStart = existing.indexOf(MARKDOWN_BEGIN);
+  const blockEnd = existing.indexOf(MARKDOWN_END) + MARKDOWN_END.length;
+  const existingBlock = existing.slice(blockStart, blockEnd);
+  const outsideBlock = existing.slice(0, blockStart) + existing.slice(blockEnd);
+  const block = restoreUserSection(incomingBlock, existing);
+  // Replacer function keeps user-authored text (possibly part of the block)
+  // from being interpreted as `$`-substitution patterns by String.replace.
+  let next = existing.replace(pattern, () => block);
+
+  // Structure migration (WI-331): the existing file nests the user-section
+  // inside the managed block (old template shape) while the incoming block
+  // keeps it outside. Replacing the block would drop the user-authored body,
+  // so relocate it to just after the managed block — the position the current
+  // template uses. When a user-section already exists outside the block, keep
+  // that one and do not duplicate.
+  if (
+    hasUserSectionMarkers(existingBlock) &&
+    !hasUserSectionMarkers(incomingBlock) &&
+    !hasUserSectionMarkers(outsideBlock)
+  ) {
+    const body = extractUserSectionBody(existingBlock) ?? USER_SECTION_PLACEHOLDER;
+    const insertAt = next.indexOf(MARKDOWN_END) + MARKDOWN_END.length;
+    const relocated = `\n\n## User Section\n\n${USER_SECTION_BEGIN}\n${body}\n${USER_SECTION_END}`;
+    next = `${next.slice(0, insertAt)}${relocated}${next.slice(insertAt)}`;
+  }
+  return next.replace(/\s*$/, "\n");
 }
 
 function renderAgentContextTemplate(
@@ -290,7 +384,7 @@ function renderAgentContextTemplate(
     .replaceAll("{{PHASEGATE_COMMANDS}}", commands)
     .replaceAll("{{PHASEGATE_SKILLS}}", options.skillSet === "core" ? "- `core skills`" : "- `all bundled skills`")
     .replaceAll("{{PHASEGATE_PRESETS}}", "- `minimal`\n- `standard`\n- `full`\n- `custom`")
-    .replaceAll("{{PHASEGATE_USER_SECTION}}", "Project-specific agent instructions go here.");
+    .replaceAll("{{PHASEGATE_USER_SECTION}}", USER_SECTION_PLACEHOLDER);
 }
 
 function escapeRegExp(value: string): string {
@@ -321,7 +415,8 @@ function hasCustomJson(content: string | null): boolean {
     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;
+    if (isRecord(withoutEmptyHooks.hooks) && Object.keys(withoutEmptyHooks.hooks).length === 0)
+      delete withoutEmptyHooks.hooks;
     return Object.keys(withoutEmptyHooks).length > 0;
   } catch {
     return true;
@@ -343,10 +438,13 @@ function likelyCauseFor(code: string): string {
 }
 
 function recoveryFor(code: string, target: string): string {
-  if (code === "EPERM") return `Review sandbox or filesystem permissions for ${target}, ask the user for write access when needed, then rerun phasegate setup:agent --apply or phasegate install --apply.`;
+  if (code === "EPERM")
+    return `Review sandbox or filesystem permissions for ${target}, ask the user for write access when needed, 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}.`;
-  if (code === "EEXIST" || code === "ENOTDIR") return `Inspect the parent path for ${target}; if it is user-owned, rename or move it before rerunning phasegate install --dry-run --json and then --apply.`;
+  if (code === "EROFS")
+    return `Move the project to a writable filesystem or rerun in a writable workspace before applying ${target}.`;
+  if (code === "EEXIST" || code === "ENOTDIR")
+    return `Inspect the parent path for ${target}; if it is user-owned, rename or move it before rerunning phasegate install --dry-run --json and then --apply.`;
   return `Inspect ${target}, run phasegate install --dry-run --json, then rerun with --apply after resolving the filesystem issue.`;
 }
 
@@ -380,12 +478,22 @@ export class RunInstallUseCase {
     const skillSet = input.skillSet ?? "all";
     const workflow = input.workflow ?? "standard";
     const agent = input.agent ?? (includeClaude && includeCodex ? "both" : includeCodex ? "codex" : "claude");
-    const targets = input.personal
+    const personal = input.personal ?? false;
+    const targets = personal
       ? this.createPersonalTargets({ includeClaude, includeCodex })
       : this.createTargets({ includeClaude, includeCodex, includeHusky, includeCi });
+    // Persist the effective opt-in state so a later reconcile can honor the
+    // original install options. Personal installs never deploy Husky/CI
+    // targets, so their effective state is recorded as false regardless of
+    // input.
+    const installationFlags: InstallationFlags = {
+      includeHusky: personal ? false : includeHusky,
+      includeCi: personal ? false : includeCi,
+      personal,
+    };
     const existingManifest = await this.manifestRepository.load(input.projectRoot);
     const baseManifest = existingManifest ?? DeploymentManifest.create(input.phasegateVersion);
-    let manifest = baseManifest;
+    let manifest = baseManifest.withInstallationFlags(installationFlags);
     const plan: InstallPlanItem[] = [];
     const refused: InstallPlanItem[] = [];
     const changed: InstallPlanItem[] = [];
@@ -396,16 +504,18 @@ export class RunInstallUseCase {
       const absolutePath = join(input.projectRoot, target.path);
       const before = await readTextOrNull(absolutePath);
       const rawTemplate = await readFile(join(input.harnessRoot, target.templatePath), "utf8");
-      const template = target.strategy === "markdown-managed"
-        ? renderAgentContextTemplate(rawTemplate, { agent, skillSet, workflow, includeHusky, includeCi })
-        : rawTemplate;
+      const template =
+        target.strategy === "markdown-managed"
+          ? renderAgentContextTemplate(rawTemplate, { agent, skillSet, workflow, includeHusky, includeCi })
+          : rawTemplate;
       const existingEntry = baseManifest.findEntry(target.path);
       const beforeHash = before === null ? null : this.hashCalculator.compute(before);
-      const unmanagedPersonalRuntimeFile = input.personal
-        && (PERSONAL_AGENT_RUNTIME_FILES.has(target.path) || target.personalManualIfUnmanaged === true)
-        && before !== null
-        && !before.includes(MARKDOWN_BEGIN)
-        && (existingEntry === null || beforeHash === null || !beforeHash.equals(existingEntry.hash));
+      const unmanagedPersonalRuntimeFile =
+        input.personal &&
+        (PERSONAL_AGENT_RUNTIME_FILES.has(target.path) || target.personalManualIfUnmanaged === true) &&
+        before !== null &&
+        !before.includes(MARKDOWN_BEGIN) &&
+        (existingEntry === null || beforeHash === null || !beforeHash.equals(existingEntry.hash));
       const repairMode = unmanagedPersonalRuntimeFile ? "manual" : this.repairMode(target, before);
       const next = unmanagedPersonalRuntimeFile ? before : this.merge(target, before, template, input.phasegateVersion);
       const didChange = before !== next;
@@ -414,11 +524,11 @@ export class RunInstallUseCase {
       // (merge returns `before`). For executable git hooks this means the
       // phasegate hook is NOT wired in — warn instead of skipping silently.
       const preservedExistingHook =
-        target.strategy === "copy"
-        && target.executable === true
-        && before !== null
-        && before.trim() !== template.trim()
-        && !input.force;
+        target.strategy === "copy" &&
+        target.executable === true &&
+        before !== null &&
+        before.trim() !== template.trim() &&
+        !input.force;
       const warning = preservedExistingHook
         ? `${target.path}: an existing hook was found and left unchanged; phasegate's checks are NOT wired in. Merge the phasegate hook manually (or rerun with --force to back up and overwrite).`
         : null;
@@ -432,7 +542,9 @@ export class RunInstallUseCase {
           ? `${target.path}: existing non-phasegate runtime path requires manual review`
           : warning !== null
             ? warning
-            : didChange ? `${target.path}: ${action}` : `${target.path}: already up to date`,
+            : didChange
+              ? `${target.path}: ${action}`
+              : `${target.path}: already up to date`,
         diff: unmanagedPersonalRuntimeFile ? "manual review required" : this.diffSummary(before, next),
         skillHint: repairMode === "ai-assisted" ? SKILL_HINT : null,
         warning,
@@ -488,10 +600,7 @@ export class RunInstallUseCase {
     }
 
     const personalSkillTargets = input.personal
-      ? [
-          ...(includeClaude ? [".claude/skills"] : []),
-          ...(includeCodex ? [".codex/skills"] : []),
-        ]
+      ? [...(includeClaude ? [".claude/skills"] : []), ...(includeCodex ? [".codex/skills"] : [])]
       : [];
     const selectedPersonalSkills = input.personal ? await listSelectedBundledSkills(input.harnessRoot, skillSet) : [];
     for (const skillPath of personalSkillTargets) {
@@ -499,7 +608,13 @@ export class RunInstallUseCase {
       plan.push(item);
       if (input.apply && item.changed && item.repairMode === "mechanical") {
         try {
-          await copySelectedSkillDirectories(this.modelDelegation, input.harnessRoot, input.projectRoot, join(input.projectRoot, skillPath), selectedPersonalSkills);
+          await copySelectedSkillDirectories(
+            this.modelDelegation,
+            input.harnessRoot,
+            input.projectRoot,
+            join(input.projectRoot, skillPath),
+            selectedPersonalSkills,
+          );
           await writeFile(
             join(input.projectRoot, skillPath, ".harness-version"),
             `${JSON.stringify({ version: input.phasegateVersion, deployedAt: new Date().toISOString(), skillSet }, null, 2)}\n`,
@@ -512,7 +627,12 @@ export class RunInstallUseCase {
         manifest = this.addManifestEntry(baseManifest, manifest, {
           path: `${item.path}/.harness-version`,
           mode: "created",
-          contentForHash: this.personalSkillsVersionHashInput(item.path, input.phasegateVersion, skillSet, selectedPersonalSkills),
+          contentForHash: this.personalSkillsVersionHashInput(
+            item.path,
+            input.phasegateVersion,
+            skillSet,
+            selectedPersonalSkills,
+          ),
         });
         for (const skill of selectedPersonalSkills) {
           manifest = this.addManifestEntry(baseManifest, manifest, {
@@ -567,7 +687,11 @@ export class RunInstallUseCase {
         return this.withApplyError({ plan, refused, changed, backupDir }, linkSpec.path, "mkdir", error);
       }
       try {
-        await symlink(linkSpec.target, join(input.projectRoot, linkSpec.path), process.platform === "win32" ? "junction" : "dir");
+        await symlink(
+          linkSpec.target,
+          join(input.projectRoot, linkSpec.path),
+          process.platform === "win32" ? "junction" : "dir",
+        );
       } catch (error) {
         return this.withApplyError({ plan, refused, changed, backupDir }, linkSpec.path, "symlink", error);
       }
@@ -586,24 +710,45 @@ export class RunInstallUseCase {
         repairMode: "manual",
         strategy: "json",
         changed: false,
-        summary: "~/.codex/config.toml: personal mode does not write user-level Codex feature flags; enable hooks manually when needed",
+        summary:
+          "~/.codex/config.toml: personal mode does not write user-level Codex feature flags; enable hooks manually when needed",
         diff: "manual Codex hooks feature enablement may be required",
         skillHint: null,
         warning: null,
       });
     }
 
-    if (input.apply && changed.length > 0) {
+    // Re-save on apply when the recorded install flags drift from a previous
+    // manifest (e.g. re-install with different --with-husky/--with-ci), even
+    // if no managed file content changed. A missing manifest with zero changes
+    // keeps the legacy behavior of not creating one.
+    const flagsDrifted =
+      existingManifest !== null && !this.installationFlagsEqual(existingManifest.installationFlags, installationFlags);
+    if (input.apply && (changed.length > 0 || flagsDrifted)) {
       try {
         await this.manifestRepository.save(input.projectRoot, manifest);
       } catch (error) {
-        return this.withApplyError({ plan, refused, changed, backupDir }, ".phasegate/manifest.json", "manifest-save", error);
+        return this.withApplyError(
+          { plan, refused, changed, backupDir },
+          ".phasegate/manifest.json",
+          "manifest-save",
+          error,
+        );
       }
     }
 
     return { plan, refused, changed, backupDir };
   }
 
+  private installationFlagsEqual(existing: InstallationFlags | undefined, next: InstallationFlags): boolean {
+    return (
+      existing !== undefined &&
+      existing.includeHusky === next.includeHusky &&
+      existing.includeCi === next.includeCi &&
+      existing.personal === next.personal
+    );
+  }
+
   private withApplyError(
     result: RunInstallResult,
     target: string,
@@ -638,7 +783,11 @@ export class RunInstallUseCase {
       },
       ...(options.includeClaude
         ? [
-            { path: ".claude/settings.json", strategy: "json" as const, templatePath: "templates/.claude/settings.json" },
+            {
+              path: ".claude/settings.json",
+              strategy: "json" as const,
+              templatePath: "templates/.claude/settings.json",
+            },
             {
               path: "CLAUDE.md",
               strategy: "markdown-managed" as const,
@@ -696,7 +845,10 @@ export class RunInstallUseCase {
     ];
   }
 
-  private createPersonalTargets(options: { readonly includeClaude: boolean; readonly includeCodex: boolean }): readonly InstallTarget[] {
+  private createPersonalTargets(options: {
+    readonly includeClaude: boolean;
+    readonly includeCodex: boolean;
+  }): readonly InstallTarget[] {
     return [
       {
         path: ".phasegate-local/phasegate.config.json",
@@ -709,7 +861,11 @@ export class RunInstallUseCase {
               path: ".claude/CLAUDE.md",
               strategy: "markdown-managed" as const,
               templatePath: "docs/templates/agent-context/CLAUDE.md.template.md",
-              block: { start: MARKDOWN_BEGIN, end: MARKDOWN_END, content: "phasegate personal .claude/CLAUDE.md managed section" },
+              block: {
+                start: MARKDOWN_BEGIN,
+                end: MARKDOWN_END,
+                content: "phasegate personal .claude/CLAUDE.md managed section",
+              },
               personalManualIfUnmanaged: true,
             },
             {
@@ -725,7 +881,11 @@ export class RunInstallUseCase {
               path: "AGENTS.md",
               strategy: "markdown-managed" as const,
               templatePath: "docs/templates/agent-context/AGENTS.md.template.md",
-              block: { start: MARKDOWN_BEGIN, end: MARKDOWN_END, content: "phasegate personal AGENTS.md managed section" },
+              block: {
+                start: MARKDOWN_BEGIN,
+                end: MARKDOWN_END,
+                content: "phasegate personal AGENTS.md managed section",
+              },
               personalManualIfUnmanaged: true,
             },
             {
@@ -861,9 +1021,15 @@ export class RunInstallUseCase {
         break;
       }
     }
-    const missingManifest = baseManifest.findEntry(`${relativePath}/.harness-version`) === null
-      || skills.some((skill) => baseManifest.findEntry(`${relativePath}/${skill}`) === null);
-    const changed = current === null || !current.includes(expectedVersion) || !current.includes(expectedSkillSet) || missingSkill || missingManifest;
+    const missingManifest =
+      baseManifest.findEntry(`${relativePath}/.harness-version`) === null ||
+      skills.some((skill) => baseManifest.findEntry(`${relativePath}/${skill}`) === null);
+    const changed =
+      current === null ||
+      !current.includes(expectedVersion) ||
+      !current.includes(expectedSkillSet) ||
+      missingSkill ||
+      missingManifest;
     return {
       path: relativePath,
       action: changed ? "missing" : "will-skip",
@@ -877,7 +1043,12 @@ export class RunInstallUseCase {
     };
   }
 
-  private personalSkillsVersionHashInput(path: string, version: string, skillSet: "core" | "all", skills: readonly string[]): string {
+  private personalSkillsVersionHashInput(
+    path: string,
+    version: string,
+    skillSet: "core" | "all",
+    skills: readonly string[],
+  ): string {
     return `personal-skills-version:${path}:${version}:${skillSet}:${skills.join(",")}`;
   }
 
@@ -902,9 +1073,15 @@ export class RunInstallUseCase {
         break;
       }
     }
-    const missingManifest = baseManifest.findEntry(SHARED_SKILLS_VERSION_PATH) === null
-      || skills.some((skill) => baseManifest.findEntry(`skills/${skill}`) === null);
-    const changed = current === null || !current.includes(expectedVersion) || !current.includes(expectedSkillSet) || missingSkill || missingManifest;
+    const missingManifest =
+      baseManifest.findEntry(SHARED_SKILLS_VERSION_PATH) === null ||
+      skills.some((skill) => baseManifest.findEntry(`skills/${skill}`) === null);
+    const changed =
+      current === null ||
+      !current.includes(expectedVersion) ||
+      !current.includes(expectedSkillSet) ||
+      missingSkill ||
+      missingManifest;
     return {
       path: "skills",
       action: changed ? "missing" : "will-skip",
@@ -918,7 +1095,11 @@ export class RunInstallUseCase {
     };
   }
 
-  private async deploySharedSkills(input: RunInstallInput, skills: readonly string[], skillSet: SkillSet): Promise<void> {
+  private async deploySharedSkills(
+    input: RunInstallInput,
+    skills: readonly string[],
+    skillSet: SkillSet,
+  ): Promise<void> {
     const targetRoot = join(input.projectRoot, "skills");
     await copySelectedSkillDirectories(this.modelDelegation, input.harnessRoot, input.projectRoot, targetRoot, skills);
     await writeFile(