phasegate 0.160.13 → 0.160.15

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

@@ -8,8 +8,10 @@
 // @work-item-id WI-182
 // @work-item-id WI-183
 // @work-item-id WI-207
+// @work-item-id WI-208
+// @work-item-id WI-209
 
-import { mkdir, readFile, writeFile, copyFile, chmod, access, lstat, readlink, symlink } from "node:fs/promises";
+import { mkdir, readFile, writeFile, copyFile, chmod, access, lstat, readlink, symlink, readdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { DeploymentEntry } from "../../domain/deployment-entry.js";
 import { DeploymentManifest } from "../../domain/deployment-manifest.js";
@@ -19,7 +21,7 @@ import type { ManifestRepositoryPort } from "../ports/manifest-repository-port.j
 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" | "markdown-managed" | "text-managed" | "copy";
+type StrategyType = "json" | "shell" | "yaml-add" | "package-json" | "markdown-managed" | "text-managed" | "copy" | "copy-dir" | "symlink";
 
 export interface InstallPlanItem {
   readonly path: string;
@@ -83,6 +85,7 @@ const MARKDOWN_BEGIN = "<!-- phasegate:managed-section:start -->";
 const MARKDOWN_END = "<!-- phasegate:managed-section:end -->";
 const TEXT_BEGIN = "# phasegate personal install exclude (BEGIN)";
 const TEXT_END = "# phasegate personal install exclude (END)";
+const PERSONAL_AGENT_RUNTIME_FILES = new Set([".claude/settings.json", ".codex/hooks.json"]);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -105,6 +108,20 @@ async function readTextOrNull(path: string): Promise<string | null> {
   }
 }
 
+async function copyDirectory(src: string, dest: string): Promise<void> {
+  await mkdir(dest, { recursive: true });
+  const entries = await readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDirectory(srcPath, destPath);
+    } else if (entry.isFile()) {
+      await copyFile(srcPath, destPath);
+    }
+  }
+}
+
 function normalizeJsonEntry(value: unknown): string {
   return JSON.stringify(value);
 }
@@ -295,7 +312,7 @@ export class RunInstallUseCase {
     const workflow = input.workflow ?? "standard";
     const agent = input.agent ?? (includeClaude && includeCodex ? "both" : includeCodex ? "codex" : "claude");
     const targets = input.personal
-      ? this.createPersonalTargets()
+      ? this.createPersonalTargets({ includeClaude, includeCodex })
       : this.createTargets({ includeClaude, includeCodex, includeHusky, includeCi });
     const existingManifest = await this.manifestRepository.load(input.projectRoot);
     const baseManifest = existingManifest ?? DeploymentManifest.create(input.phasegateVersion);
@@ -313,8 +330,14 @@ export class RunInstallUseCase {
       const template = target.strategy === "markdown-managed"
         ? renderAgentContextTemplate(rawTemplate, { agent, skillSet, workflow, includeHusky, includeCi })
         : rawTemplate;
-      const repairMode = this.repairMode(target, before);
-      const next = this.merge(target, before, template, input.phasegateVersion);
+      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)
+        && before !== null
+        && (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;
       const action = this.actionFor(before, didChange, input.force);
       const item: InstallPlanItem = {
@@ -323,8 +346,10 @@ export class RunInstallUseCase {
         repairMode,
         strategy: target.strategy,
         changed: didChange,
-        summary: didChange ? `${target.path}: ${action}` : `${target.path}: already up to date`,
-        diff: this.diffSummary(before, next),
+        summary: unmanagedPersonalRuntimeFile
+          ? `${target.path}: existing non-phasegate path requires manual review`
+          : 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,
       };
       plan.push(item);
@@ -340,30 +365,30 @@ export class RunInstallUseCase {
         await this.backup(input.projectRoot, target.path, backupDir);
       }
 
+      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 mkdir(dirname(absolutePath), { recursive: true });
-        } catch (error) {
-          return this.withApplyError({ plan, refused, changed, backupDir }, target.path, "mkdir", error);
-        }
-        try {
-          await writeFile(absolutePath, next, "utf8");
+          await chmod(absolutePath, 0o755);
         } 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);
-          }
+          return this.withApplyError({ plan, refused, changed, backupDir }, target.path, "chmod", error);
         }
+      }
       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);
+      const manifestEntry = baseManifest.findEntry(target.path);
+      if (manifestEntry !== null && manifestEntry.hash.equals(hash)) {
+        manifest = manifest.addEntry(manifestEntry);
       } else {
         manifest = manifest.addEntry(
           DeploymentEntry.create({
@@ -377,52 +402,73 @@ export class RunInstallUseCase {
       }
     }
 
-    const linkPaths = input.personal ? [] : [
-      ...(includeClaude ? [".claude/skills"] : []),
-      ...(includeCodex ? [".codex/skills"] : []),
-    ];
-    for (const linkPath of linkPaths) {
-      const item = await this.planSkillLink(input.projectRoot, linkPath);
+    const personalSkillTargets = input.personal
+      ? [
+          ...(includeClaude ? [".claude/skills"] : []),
+          ...(includeCodex ? [".codex/skills"] : []),
+        ]
+      : [];
+    for (const skillPath of personalSkillTargets) {
+      const item = await this.planPersonalSkillDirectory(input, skillPath, baseManifest);
+      plan.push(item);
+      if (input.apply && item.changed && item.repairMode === "mechanical") {
+        try {
+          await copyDirectory(join(input.harnessRoot, "skills"), join(input.projectRoot, skillPath));
+          await writeFile(
+            join(input.projectRoot, skillPath, ".harness-version"),
+            `${JSON.stringify({ version: input.phasegateVersion, deployedAt: new Date().toISOString(), skillSet }, null, 2)}\n`,
+            "utf8",
+          );
+        } catch (error) {
+          return this.withApplyError({ plan, refused, changed, backupDir }, item.path, "copyDirectory", error);
+        }
+        changed.push(item);
+        manifest = this.addManifestEntry(baseManifest, manifest, {
+          path: item.path,
+          mode: "created",
+          contentForHash: this.personalSkillsHashInput(item.path, input.phasegateVersion, skillSet),
+        });
+      }
+    }
+
+    const linkSpecs = input.personal
+      ? []
+      : [
+          ...(includeClaude ? [{ path: ".claude/skills", target: "../skills" }] : []),
+          ...(includeCodex ? [{ path: ".codex/skills", target: "../skills" }] : []),
+        ];
+    for (const linkSpec of linkSpecs) {
+      const item = await this.planSkillLink(input.projectRoot, linkSpec.path, linkSpec.target);
       plan.push(item);
       if (!input.apply || !item.changed) continue;
       try {
-        await mkdir(join(input.projectRoot, "skills"), { recursive: true });
-        await mkdir(dirname(join(input.projectRoot, linkPath)), { recursive: true });
+        if (!input.personal) await mkdir(join(input.projectRoot, "skills"), { recursive: true });
+        await mkdir(dirname(join(input.projectRoot, linkSpec.path)), { recursive: true });
       } catch (error) {
-        return this.withApplyError({ plan, refused, changed, backupDir }, linkPath, "mkdir", error);
+        return this.withApplyError({ plan, refused, changed, backupDir }, linkSpec.path, "mkdir", error);
       }
       try {
-        await symlink("../skills", join(input.projectRoot, linkPath), 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 }, linkPath, "symlink", error);
+        return this.withApplyError({ plan, refused, changed, backupDir }, linkSpec.path, "symlink", error);
       }
       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(),
-          }),
-        );
-      }
+      manifest = this.addManifestEntry(baseManifest, manifest, {
+        path: linkSpec.path,
+        mode: "symlink",
+        contentForHash: linkSpec.target,
+      });
     }
 
     if (input.personal && includeCodex) {
       plan.push({
-        path: "~/.codex/hooks.json",
+        path: "~/.codex/config.toml",
         action: "will-skip",
         repairMode: "manual",
         strategy: "json",
         changed: false,
-        summary: "~/.codex/hooks.json: personal mode does not write user-level Codex settings; configure hooks manually",
-        diff: "manual user-level Codex hook setup required",
+        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,
       });
     }
@@ -465,6 +511,11 @@ export class RunInstallUseCase {
     readonly includeCi: boolean;
   }): readonly InstallTarget[] {
     return [
+      {
+        path: "phasegate.config.json",
+        strategy: "copy" as const,
+        templatePath: "docs/templates/project/phasegate.config.json",
+      },
       ...(options.includeClaude
         ? [
             { path: ".claude/settings.json", strategy: "json" as const, templatePath: "templates/.claude/settings.json" },
@@ -525,13 +576,31 @@ export class RunInstallUseCase {
     ];
   }
 
-  private createPersonalTargets(): readonly InstallTarget[] {
+  private createPersonalTargets(options: { readonly includeClaude: boolean; readonly includeCodex: boolean }): readonly InstallTarget[] {
     return [
       {
-        path: ".phasegate-local/config.json",
+        path: ".phasegate-local/phasegate.config.json",
         strategy: "copy" as const,
         templatePath: "docs/templates/personal/phasegate-local-config.json",
       },
+      ...(options.includeClaude
+        ? [
+            {
+              path: ".claude/settings.json",
+              strategy: "copy" as const,
+              templatePath: "templates/.claude/settings.json",
+            },
+          ]
+        : []),
+      ...(options.includeCodex
+        ? [
+            {
+              path: ".codex/hooks.json",
+              strategy: "copy" as const,
+              templatePath: "templates/.codex/hooks.json",
+            },
+          ]
+        : []),
       {
         path: ".git/info/exclude",
         strategy: "text-managed" as const,
@@ -545,6 +614,8 @@ export class RunInstallUseCase {
     if (target.strategy === "shell") return shellRepairMode(before);
     if (target.strategy === "text-managed") return "mechanical";
     if (target.strategy === "copy") return "mechanical";
+    if (target.strategy === "copy-dir") return "mechanical";
+    if (target.strategy === "symlink") return "mechanical";
     if (target.strategy === "json") return jsonRepairMode(before);
     if (target.strategy === "markdown-managed") return "mechanical";
     return "mechanical";
@@ -589,16 +660,69 @@ export class RunInstallUseCase {
     };
   }
 
-  private async planSkillLink(projectRoot: string, relativePath: string): Promise<InstallPlanItem> {
+  private async planPersonalSkillDirectory(
+    input: RunInstallInput,
+    relativePath: string,
+    baseManifest: DeploymentManifest,
+  ): Promise<InstallPlanItem> {
+    const absolutePath = join(input.projectRoot, relativePath);
+    const versionPath = join(absolutePath, ".harness-version");
+    const current = await readTextOrNull(versionPath);
+    const expectedNeedle = `"version": "${input.phasegateVersion}"`;
+    const manifestEntry = baseManifest.findEntry(relativePath);
+    const pathExists = await exists(absolutePath);
+    const unmanagedExisting = pathExists && (current === null || manifestEntry === null);
+    const changed = !unmanagedExisting && (current === null || !current.includes(expectedNeedle));
+    return {
+      path: relativePath,
+      action: changed ? "missing" : unmanagedExisting ? "will-merge" : "will-skip",
+      repairMode: unmanagedExisting ? "manual" : "mechanical",
+      strategy: "copy-dir",
+      changed,
+      summary: unmanagedExisting
+        ? `${relativePath}: existing non-phasegate directory requires manual review`
+        : changed ? `${relativePath}: deploy bundled skills` : `${relativePath}: already up to date`,
+      diff: unmanagedExisting ? "manual review required" : changed ? "+ bundled skills" : "no changes",
+      skillHint: null,
+    };
+  }
+
+  private personalSkillsHashInput(path: string, version: string, skillSet: "core" | "all"): string {
+    return `personal-skills:${path}:${version}:${skillSet}`;
+  }
+
+  private addManifestEntry(
+    baseManifest: DeploymentManifest,
+    manifest: DeploymentManifest,
+    input: { readonly path: string; readonly mode: "created" | "symlink"; readonly contentForHash: string },
+  ): DeploymentManifest {
+    const hash = this.hashCalculator.compute(input.contentForHash);
+    const existingEntry = baseManifest.findEntry(input.path);
+    if (existingEntry !== null && existingEntry.hash.equals(hash)) {
+      return manifest.addEntry(existingEntry);
+    }
+    return manifest.addEntry(
+      DeploymentEntry.create({
+        path: input.path,
+        mode: input.mode,
+        block: null,
+        hash,
+        deployedAt: new Date().toISOString(),
+      }),
+    );
+  }
+
+  private async planSkillLink(projectRoot: string, relativePath: string, target: string): Promise<InstallPlanItem> {
     const absolutePath = join(projectRoot, relativePath);
+    const parentPath = dirname(absolutePath);
     try {
       const stat = await lstat(absolutePath);
-      if (stat.isSymbolicLink() && (await readlink(absolutePath)) === "../skills") {
+      if (stat.isSymbolicLink() && (await readlink(absolutePath)) === target) {
         return {
           path: relativePath,
           action: "will-skip",
           repairMode: "mechanical",
-          strategy: "yaml-add",
+          strategy: "symlink",
           changed: false,
           summary: `${relativePath}: already linked`,
           diff: "no changes",
@@ -609,21 +733,36 @@ export class RunInstallUseCase {
         path: relativePath,
         action: "will-merge",
         repairMode: "manual",
-        strategy: "yaml-add",
+        strategy: "symlink",
         changed: false,
         summary: `${relativePath}: existing non-phasegate path requires manual review`,
         diff: "manual review required",
         skillHint: null,
       };
     } catch {
+      try {
+        const parentStat = await lstat(parentPath);
+        if (!parentStat.isDirectory()) {
+          return {
+            path: relativePath,
+            action: "will-merge",
+            repairMode: "manual",
+            strategy: "symlink",
+            changed: false,
+            summary: `${relativePath}: parent path exists and requires manual review`,
+            diff: "manual review required",
+            skillHint: null,
+          };
+        }
+      } catch {}
       return {
         path: relativePath,
         action: "missing",
         repairMode: "mechanical",
-        strategy: "yaml-add",
+        strategy: "symlink",
         changed: true,
         summary: `${relativePath}: create symlink`,
-        diff: "+ symlink ../skills",
+        diff: `+ symlink ${target}`,
         skillHint: null,
       };
     }

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

@@ -4,6 +4,8 @@
 // @work-item-id WI-174
 // @work-item-id WI-199
 // @work-item-id WI-207
+// @work-item-id WI-208
+// @work-item-id WI-209
 
 import { access, copyFile, lstat, mkdir, readFile, readlink, rm, rmdir, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
@@ -163,6 +165,7 @@ export class RunUninstallUseCase {
         repairMode: "manual",
         strategy: "unknown",
         changed: false,
+        protected: false,
         summary: "manifest missing; run phasegate doctor and clean up manually",
         diff: "manual cleanup required",
         skillHint: SKILL_HINT,
@@ -216,8 +219,12 @@ export class RunUninstallUseCase {
     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 (entry.mode === "symlink") return this.planSymlink(input.projectRoot, entry);
+    if (entry.mode === "created" && await this.isDirectory(absolutePath)) {
+      return this.planCreatedDirectory(input.projectRoot, entry);
+    }
+    const currentContent = await readTextOrNull(absolutePath);
     if (currentContent === null && strategy !== "symlink") {
       return {
         item: this.item(entry.path, "skip", "mechanical", strategy, false, `${entry.path}: already absent`, "no changes", null),
@@ -226,7 +233,6 @@ export class RunUninstallUseCase {
       };
     }
 
-    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);
   }
@@ -240,9 +246,9 @@ export class RunUninstallUseCase {
     } catch {
       target = null;
     }
-    if (target === "../skills") {
+    if (target !== null && this.hashCalculator.compute(target).equals(entry.hash)) {
       return {
-        item: this.item(entry.path, "unlink", "mechanical", "symlink", true, `${entry.path}: remove symlink`, "- symlink ../skills", null),
+        item: this.item(entry.path, "unlink", "mechanical", "symlink", true, `${entry.path}: remove symlink`, `- symlink ${target}`, null),
         needsBackup: false,
         apply: async () => {
           await rm(absolutePath, { force: true });
@@ -256,6 +262,35 @@ export class RunUninstallUseCase {
     };
   }
 
+  private async isDirectory(path: string): Promise<boolean> {
+    try {
+      const stat = await lstat(path);
+      return stat.isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  private async planCreatedDirectory(projectRoot: string, entry: DeploymentEntry) {
+    const absolutePath = this.resolveProjectPath(projectRoot, entry.path);
+    return {
+      item: this.item(
+        entry.path,
+        "delete",
+        "mechanical",
+        "created",
+        true,
+        `${entry.path}: delete created directory`,
+        "- directory",
+        null,
+      ),
+      needsBackup: false,
+      apply: async () => {
+        await rm(absolutePath, { recursive: true, force: true });
+      },
+    };
+  }
+
   private async planCreated(projectRoot: string, entry: DeploymentEntry, currentContent: string) {
     const absolutePath = this.resolveProjectPath(projectRoot, entry.path);
     const currentHash = this.hashCalculator.compute(currentContent);

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

@@ -2,6 +2,7 @@
 // @layer presentation
 // @work-item-id WI-145
 // @work-item-id WI-178
+// @work-item-id WI-208
 
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join } from "node:path";
@@ -37,6 +38,7 @@ export class DoctorHandler {
     const formatInput = {
       report: result.report,
       agent: result.agent,
+      installationMode: result.installationMode,
       scopedOutFindings: result.scopedOutFindings,
       phasegateVersion: input.phasegateVersion,
       projectRoot: input.projectRoot,

package/scripts/harness/installation/presentation/formatters/diagnostic-report-formatter.ts

@@ -4,6 +4,7 @@
 // @work-item-id WI-178
 // @work-item-id WI-179
 // @work-item-id WI-180
+// @work-item-id WI-208
 
 import type { DoctorAgentScope, ScopedOutDiagnosticFinding } from "../../application/usecases/run-doctor-diagnostics.js";
 import type { DiagnosticReport } from "../../domain/diagnostic-report.js";
@@ -11,6 +12,7 @@ import type { DiagnosticReport } from "../../domain/diagnostic-report.js";
 export interface DiagnosticReportFormatterInput {
   readonly report: DiagnosticReport;
   readonly agent: DoctorAgentScope;
+  readonly installationMode: "project" | "personal";
   readonly scopedOutFindings: readonly ScopedOutDiagnosticFinding[];
   readonly phasegateVersion: string;
   readonly projectRoot: string;
@@ -26,7 +28,8 @@ export class DiagnosticReportFormatter {
         projectRoot: input.projectRoot,
         scope: {
           agent: input.agent,
-          description: scopeDescription(input.agent),
+          installationMode: input.installationMode,
+          description: scopeDescription(input.agent, input.installationMode),
         },
         overallStatus: input.report.overallStatus,
         findings: input.report.findings.map((finding) => ({
@@ -60,7 +63,7 @@ export class DiagnosticReportFormatter {
     const lines = [
       `phasegate doctor v${input.phasegateVersion}`,
       `Project: ${input.projectRoot}`,
-      `Scope: ${input.agent} (${scopeDescription(input.agent)})`,
+      `Scope: ${input.agent} / ${input.installationMode} (${scopeDescription(input.agent, input.installationMode)})`,
       "",
     ];
     for (const finding of input.report.findings) {
@@ -86,7 +89,12 @@ export class DiagnosticReportFormatter {
   }
 }
 
-function scopeDescription(agent: DoctorAgentScope): string {
+function scopeDescription(agent: DoctorAgentScope, installationMode: "project" | "personal"): string {
+  if (installationMode === "personal") {
+    if (agent === "claude") return "Personal Claude Code sandbox; team/project Husky, CI, package, and Codex-only findings are not repair targets.";
+    if (agent === "codex") return "Personal Codex sandbox; team/project Husky, CI, package, and Claude-only findings are not repair targets.";
+    return "Personal sandbox diagnostics; team/project Husky, CI, and package findings are not repair targets.";
+  }
   if (agent === "claude") return "Claude Code and shared setup targets; Codex-only findings are not applicable.";
   if (agent === "codex") return "Codex and shared setup targets; Claude-only findings are not applicable.";
   return "Full setup diagnostics for Claude, Codex, and shared targets.";

package/scripts/harness/main.ts

@@ -171,7 +171,7 @@ Setup:
   scaffold-wi <unit|_cross> <story|issue|chore>
                                Create docs/inception/{unit}/WI-XXX/description.md
   emit-agent-rules             Print AGENTS.md / CLAUDE.md WI workflow rules block
-  install                      Install phasegate managed files (--dry-run|--apply, --force, --personal)
+  install                      Install phasegate managed files (--dry-run|--apply, --force, --personal, --agent <claude|codex|both>)
   uninstall                    Uninstall phasegate managed files (--dry-run|--apply, --force)
   reconcile                    Reconcile phasegate managed files (--dry-run|--apply, --force)
   setup:agent                  Diagnose repo setup and produce/apply an agent-readable setup plan
@@ -625,7 +625,8 @@ Options:
   --workflow <standard|strict>    Rendered agent context workflow mode (default: standard)
   --with-husky                    Include Husky hook targets
   --with-ci                       Include GitHub Actions target
-  --personal                      Use local-only install: no package.json, agent docs, Husky, CI, or .gitignore writes
+  --personal                      Use local-only install: no package.json, agent docs, Husky, CI, .gitignore, GitHub CLI, secrets, or CI setting writes.
+                                  With --agent claude, initializes .phasegate-local config/settings/skills and ignored .claude shims.
   --json                          Output machine-readable JSON
   --help, -h                      Show this help`,
   "setup:agent": `Usage: phasegate setup:agent [options]

package/skills/README.md

@@ -16,7 +16,7 @@
 
 `.agent/skills` は旧 setup 由来の互換パスです。新規導入では管理対象にしません。<!-- @work-item-id WI-157 -->
 
-`phasegate install --personal` はチーム所有リポジトリでの個人評価用です。このモードでは `.claude/skills` / `.codex/skills` のリンクを作成せず、`.phasegate-local/config.json` と `.git/info/exclude` の local-only managed block だけを扱います。通常の共有導入が必要になった時点で `phasegate install --dry-run` / `phasegate install --apply` を使います。<!-- @work-item-id WI-207 -->
+`phasegate install --personal` はチーム所有リポジトリでの個人評価用です。このモードでは team-owned files を変更せず、`.phasegate-local/phasegate.config.json` と `.git/info/exclude` の local-only managed block、選択 agent 用の real `.claude/*` / `.codex/*` runtime artifacts だけを扱います。通常の共有導入が必要になった時点で `phasegate install --dry-run` / `phasegate install --apply` を使います。<!-- @work-item-id WI-207 --> <!-- @work-item-id WI-209 -->
 
 ## 新しいスキルの追加
 

package/skills/phasegate-config-doctor/SKILL.md

@@ -35,7 +35,7 @@ phasegate を導入した直後の config は単純な default で、実プロ
 | hook config | `.claude/scripts/hook-config.json` | 既存 hook 設定確認 |
 | doctor report | 明示された report path、またはユーザーが指定した `.phasegate/last-doctor-report.json` | `repairMode` / `repairHint` / `suggestedSkill` の確認 |
 | manifest | `.phasegate/manifest.json` | install / reconcile / uninstall の managed target と hash 状態確認 |
-| personal config | `.phasegate-local/config.json` | `install --personal` の local-only 設定確認 |
+| personal config | `.phasegate-local/phasegate.config.json` | `install --personal` の local-only 設定確認 |
 | git local exclude | `.git/info/exclude` | `install --personal` の repository-local ignore block 確認 |
 | Claude hooks | `.claude/settings.json` | managed hook JSON と user customization の確認 |
 | Codex hooks | `.codex/hooks.json` | managed hook JSON と Codex hook 配線確認 |
@@ -129,7 +129,7 @@ product-architect で Unit を作り、いくつかの logical_design を書い
 #### 観点 9: setup lifecycle と doctor finding
 
 - `phasegate doctor --json` の finding に `repairMode: "ai-assisted"` と `suggestedSkill.skillName = "phasegate-config-doctor"` がある → 本 skill が merge 方針、保持する user content、実行すべき `install --apply` / `--force` / `reconcile --apply` を提案する
-- チーム所有リポジトリで個人評価だけを行う相談では、通常の `install --apply` ではなく `phasegate install --personal --dry-run` を先に提案する。personal install は `package.json`, `AGENTS.md`, `CLAUDE.md`, `.husky/*`, `.github/workflows/*`, `.gitignore`, `.codex/hooks.json`, skill symlink を変更対象にしない。変更対象は `.phasegate-local/config.json`, `.phasegate/manifest.json`, `.git/info/exclude` の managed block に限定し、Codex user-level hook setup は manual action として扱う。<!-- @work-item-id WI-207 -->
+- チーム所有リポジトリで個人評価だけを行う相談では、通常の `install --apply` ではなく `phasegate install --personal --agent claude --dry-run` を先に提案する。personal install は `package.json`, `AGENTS.md`, `CLAUDE.md`, `.husky/*`, `.github/workflows/*`, `.gitignore`, GitHub CLI config, repo secrets, CI settings を変更対象にしない。選択 agent 向けには `.phasegate-local/phasegate.config.json`, real `.claude/settings.json` / `.claude/skills/`, real `.codex/hooks.json` / `.codex/skills/`, `.phasegate/manifest.json`, `.git/info/exclude` の managed block を自動作成する。既存 `.claude/*` / `.codex/*` がある場合は上書きせず manual review として扱う。Codex user-level hook feature enablement は manual action として扱う。<!-- @work-item-id WI-207 --> <!-- @work-item-id WI-208 --> <!-- @work-item-id WI-209 -->
 - Claude-only / Codex-only 導入後は `phasegate doctor --agent claude --json` または `phasegate doctor --agent codex --json` を使って selected agent の readiness を読む。`scopedOutFindings` は未選択 agent の `not-applicable` 情報なので、ユーザーがその agent を導入したいと言っていない限り repair 提案にしない。`repairHint: null` / `suggestedSkill: null` は意図的な抑制で、`currentScopeRepairTarget: false` と `repairModeApplicability: "only-if-agent-selected"` は raw `repairMode` が current scope の修復指示ではないという印である。<!-- @work-item-id WI-178, WI-179, WI-180 -->
 - `repairHint` がある mechanical finding → 原則として hint のコマンドを優先し、実行前に対象ファイルと manifest の差分を確認
 - manifest parse error → `.phasegate/manifest.json` を手で修復する前に backup / uninstall / reinstall の選択肢を提示

package/skills/phasegate-toolkit-guide/SKILL.md

@@ -130,7 +130,7 @@ docs/guide/                          # phasegate リポジトリ自体 (dogfood)
 - 既存プロジェクト導入: `docs/guide/retrofit-adoption.md`
 - setup artifact / doctor finding / legacy artifact: `docs/guide/setup-artifacts.md`
 
-チーム所有リポジトリで個人評価だけを行いたい場合は、`docs/guide/installation.md` の personal install セクションを読む。`phasegate install --personal` は `package.json`、`AGENTS.md`、`CLAUDE.md`、`.husky/*`、`.github/workflows/*`、`.gitignore`、`.codex/hooks.json`、skill symlink を変更せず、`.phasegate-local/config.json` と `.git/info/exclude` の managed block を使う。Codex user-level hook setup は manual action として説明する。<!-- @work-item-id WI-207 -->
+チーム所有リポジトリで個人評価だけを行いたい場合は、`docs/guide/installation.md` の personal install セクションを読む。`phasegate install --personal --agent <agent>` は `package.json`、`AGENTS.md`、`CLAUDE.md`、`.husky/*`、`.github/workflows/*`、`.gitignore`、GitHub CLI config、repo secrets、CI settings を変更せず、`.phasegate-local/phasegate.config.json`、real `.claude/settings.json` / `.claude/skills/`、real `.codex/hooks.json` / `.codex/skills/`、`.git/info/exclude` の managed block を使う。Codex user-level hook feature enablement は manual action として説明する。<!-- @work-item-id WI-207 --> <!-- @work-item-id WI-208 --> <!-- @work-item-id WI-209 -->
 
 `setup-artifacts.md` は managed target / generated artifact / runtime state / legacy artifact / user-level setting の分類を持つ。`doctor --report-out` は明示 path への出力で、`.phasegate/last-doctor-report.json` は固定生成物ではない点もここを参照する。<!-- @work-item-id WI-153 -->