phasegate 0.160.14 → 0.160.15

package/README.md

@@ -109,7 +109,7 @@ npx phasegate install --personal --agent claude --dry-run
 npx phasegate install --personal --agent claude --apply
 ```
 
-`--personal` does not plan or write `package.json`, `AGENTS.md`, `CLAUDE.md`, `.husky/*`, `.github/workflows/*`, `.gitignore`, GitHub CLI config, repo secrets, or CI settings. For Claude Code it automatically creates `.phasegate-local/phasegate.config.json`, `.phasegate-local/claude/settings.json`, `.phasegate-local/skills/`, ignored root `.claude/settings.json` and `.claude/skills` shims, a managed local-only block in `.git/info/exclude`, and `.phasegate/manifest.json`. Codex user-level hook setup remains a manual action instead of a project-local `.codex/hooks.json` write. <!-- @work-item-id WI-207 --> <!-- @work-item-id WI-208 -->
+`--personal` does not plan or write `package.json`, `AGENTS.md`, `CLAUDE.md`, `.husky/*`, `.github/workflows/*`, `.gitignore`, GitHub CLI config, repo secrets, or CI settings. It creates `.phasegate-local/phasegate.config.json`, real local-only agent runtime artifacts for the selected agent (`.claude/settings.json` + `.claude/skills/` and/or `.codex/hooks.json` + `.codex/skills/`), a managed local-only block in `.git/info/exclude`, and `.phasegate/manifest.json`. Codex user-level hook feature enablement remains a manual action. <!-- @work-item-id WI-207 --> <!-- @work-item-id WI-208 --> <!-- @work-item-id WI-209 -->
 
 For agent-driven setup planning, use:
 

package/docs/guide/getting-started.md

@@ -12,7 +12,7 @@ Start with one question: what kind of repository are you setting up?
 |---|---|---|
 | New project with agent hooks | `npx phasegate init --name <project> --agent both --with-husky --with-ci` | `phasegate.config.json`, skills, hooks, agent context files, Husky, and CI targets exist |
 | Existing repository | `npx phasegate install --dry-run` then `npx phasegate install --apply` | Existing hooks/scripts are preserved and `.phasegate/manifest.json` records managed targets |
-| Personal evaluation in a team repository | `npx phasegate install --personal --agent claude --dry-run` then `npx phasegate install --personal --agent claude --apply` | Team-owned files stay untouched; `.phasegate-local/` stores config/settings/skills and ignored `.claude/*` shims expose them to Claude Code |
+| Personal evaluation in a team repository | `npx phasegate install --personal --agent claude --dry-run` then `npx phasegate install --personal --agent claude --apply` | Team-owned files stay untouched; `.phasegate-local/` stores config and ignored real `.claude/*` / `.codex/*` runtime artifacts expose hooks and skills to selected agents |
 | CI-only rollout | `npx phasegate setup:agent --intent ci-only --with-ci --dry-run --json` | The plan explains CI changes without requiring local hooks |
 | Codex-only project | `npx phasegate init --agent codex --with-husky` | `.codex/hooks.json`, `AGENTS.md`, `.codex/skills`, and pre-commit backstop are present |
 | Strict validation rollout | `npx phasegate setup:agent --intent strict --dry-run --json` | The plan lists strict checks, L4 risk, rollback, and validation commands |

package/docs/guide/installation.md

@@ -65,7 +65,7 @@ npx phasegate install --personal --agent claude --dry-run
 npx phasegate install --personal --agent claude --apply
 ```
 
-Personal install keeps team-owned files out of both the plan and apply path: `package.json`, `AGENTS.md`, `CLAUDE.md`, `.husky/*`, `.github/workflows/*`, `.gitignore`, GitHub CLI config, repo secrets, and CI settings are not touched. For Claude Code, PhaseGate writes local-only artifacts under `.phasegate-local/`, creates ignored root `.claude/settings.json` and `.claude/skills` shims for Claude discovery, records `.phasegate/manifest.json`, and manages a local exclude block in `.git/info/exclude`. Codex user-level hook setup is reported as a manual action instead of writing project-local `.codex/hooks.json`. <!-- @work-item-id WI-207 --> <!-- @work-item-id WI-208 -->
+Personal install keeps team-owned files out of both the plan and apply path: `package.json`, `AGENTS.md`, `CLAUDE.md`, `.husky/*`, `.github/workflows/*`, `.gitignore`, GitHub CLI config, repo secrets, and CI settings are not touched. PhaseGate writes `.phasegate-local/phasegate.config.json`, creates real local-only agent runtime artifacts for the selected agent (`.claude/settings.json` + `.claude/skills/` and/or `.codex/hooks.json` + `.codex/skills/`), records `.phasegate/manifest.json`, and manages a local exclude block in `.git/info/exclude`. Codex user-level hook feature enablement is still reported as a manual action. <!-- @work-item-id WI-207 --> <!-- @work-item-id WI-208 --> <!-- @work-item-id WI-209 -->
 
 For agent-readable planning before writing files:
 

package/docs/guide/setup-artifacts.md

@@ -6,16 +6,17 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 <!-- @work-item-id WI-157 -->
 <!-- @work-item-id WI-169 -->
 <!-- @work-item-id WI-208 -->
+<!-- @work-item-id WI-209 -->
 
 ## Artifact Classes
 
 | Class | Examples | Owner | Lifecycle |
 |---|---|---|---|
-| Managed target | `.claude/settings.json`, `.codex/hooks.json`, `CLAUDE.md`, `AGENTS.md`, `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`, `.github/workflows/phasegate-aidlc-gate.yml`, `.claude/skills`, `.codex/skills`, `package.json` PhaseGate scripts/devDependency | PhaseGate managed block or symlink plus user content | Created or merged by `install`, refreshed by `reconcile`, removed or reversed by `uninstall` |
-| Configuration | `phasegate.config.json`, `package.json` | User owned, PhaseGate assisted | Created by `init`; `install` may merge scripts/devDependency into `package.json` |
+| Managed target | `phasegate.config.json`, `.claude/settings.json`, `.codex/hooks.json`, `CLAUDE.md`, `AGENTS.md`, `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`, `.github/workflows/phasegate-aidlc-gate.yml`, `.claude/skills`, `.codex/skills`, `package.json` PhaseGate scripts/devDependency | PhaseGate managed block, real runtime artifact, or symlink plus user content | Created or merged by `install`, refreshed by `reconcile`, removed or reversed by `uninstall` |
+| Configuration | `phasegate.config.json`, `package.json` | User owned, PhaseGate assisted | Created by `init` or project install when absent; `install` may merge scripts/devDependency into `package.json` |
 | Generated artifact | `.phasegate/manifest.json`, `.phasegate/backups/*`, `.phasegate/uninstalled-*.json`, `.phasegate/baseline.json` | PhaseGate | Written by lifecycle commands and validators; safe to regenerate only through the owning command |
 | Runtime state/report | `.phasegate/hook-skip-events.jsonl`, explicit `doctor --report-out <path>` output, `reports/regression/*`, resolved `reporting.outputDir` reports | PhaseGate command output | Produced while hooks, doctor, and validation commands run |
-| Personal install artifact | `.phasegate-local/phasegate.config.json`, `.phasegate-local/claude/settings.json`, `.phasegate-local/skills/`, ignored root `.claude/settings.json` and `.claude/skills` shims, `.git/info/exclude` PhaseGate block | One developer on one machine | Created by `phasegate install --personal --agent claude`; team `.gitignore`, team-owned files, GitHub CLI config, repo secrets, and CI settings are not modified |
+| Personal install artifact | `.phasegate-local/phasegate.config.json`, ignored real `.claude/settings.json` + `.claude/skills/`, ignored real `.codex/hooks.json` + `.codex/skills/`, `.git/info/exclude` PhaseGate block | One developer on one machine | Created by `phasegate install --personal --agent <agent>`; team `.gitignore`, team-owned files, GitHub CLI config, repo secrets, and CI settings are not modified |
 | Legacy artifact | `.harness-hooks.yml`, old Fuse hook files, `.harness/session-state.json`, `.harness/context-priority.json`, `.harness/reports` fallback | Compatibility only | Not required for current install lifecycle unless a project intentionally keeps an archived integration |
 | User-level setting | Codex CLI `hooks` feature flag | User machine | Must be enabled manually with `codex features enable hooks`; project commands do not modify it |
 
@@ -28,6 +29,7 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 - Husky scripts when requested: `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`
 - CI workflow when requested: `.github/workflows/phasegate-aidlc-gate.yml`
 - Agent skill links: `.claude/skills`, `.codex/skills`
+- Project config: `phasegate.config.json` when absent, so installed agent hooks have a discoverable runtime config
 - Package metadata: PhaseGate scripts and `devDependencies.phasegate` in `package.json`
 - Manifest: `.phasegate/manifest.json`
 
@@ -37,9 +39,9 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 
 ## Personal Install Artifacts
 
-`phasegate install --personal --agent claude --apply` is a local-only bootstrap for evaluating PhaseGate in a team-owned repository. Substantive files are stored under `.phasegate-local/`, while root `.claude/settings.json` and `.claude/skills` are symlinks so Claude Code can discover the settings and skills. The root shims are hidden by `.git/info/exclude`; PhaseGate does not edit team `.gitignore`.
+`phasegate install --personal --agent claude --apply` is a local-only bootstrap for evaluating PhaseGate in a team-owned repository. PhaseGate config is stored under `.phasegate-local/`, while selected agent runtime paths are real project-local files/directories: `.claude/settings.json` and `.claude/skills/` for Claude Code, `.codex/hooks.json` and `.codex/skills/` for Codex. These paths are hidden by `.git/info/exclude`; PhaseGate does not edit team `.gitignore`.
 
-If `.claude/settings.json` or `.claude/skills` already exists and is not the PhaseGate personal shim, personal install reports manual review and preserves the existing path.
+If `.claude/*` or `.codex/*` already exists and is not a PhaseGate-managed personal artifact, personal install reports manual review and preserves the existing path. <!-- @work-item-id WI-209 -->
 
 ## Doctor Findings
 

package/docs/templates/project/phasegate.config.json

@@ -0,0 +1,29 @@
+{
+  "project": {
+    "name": "phasegate-project",
+    "preset": "standard"
+  },
+  "architecture": {
+    "preset": "clean"
+  },
+  "layers": {},
+  "quickMode": {},
+  "phaseDependencies": {
+    "preset": "default",
+    "override": false,
+    "customRules": []
+  },
+  "planningMode": {
+    "default": "interactive",
+    "perPhase": {}
+  },
+  "harnesses": {},
+  "paths": {
+    "designDocs": "docs/product/construction",
+    "inceptionDocs": "docs/inception"
+  },
+  "reporting": {
+    "format": "json",
+    "outputDir": "reports"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.160.14",
+  "version": "0.160.15",
   "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/checks/check-utils.ts

@@ -1,6 +1,7 @@
 // @unit installation
 // @layer application
 // @work-item-id WI-145
+// @work-item-id WI-209
 
 import { join } from "node:path";
 import type { CheckId } from "../../domain/check-id.js";
@@ -63,3 +64,7 @@ export function skillTargetLooksValid(target: string | null): boolean {
   const normalized = target.replaceAll("\\", "/").replace(/\/+$/, "");
   return normalized === "skills" || normalized === "../skills" || normalized.endsWith("/skills");
 }
+
+export function skillDirectoryLooksValid(files: readonly string[]): boolean {
+  return files.some((file) => file.endsWith("/SKILL.md") || file.endsWith("\\SKILL.md") || file.endsWith(".harness-version"));
+}

package/scripts/harness/installation/application/checks/claude-skills-symlink-check.ts

@@ -1,11 +1,12 @@
 // @unit installation
 // @layer application
 // @work-item-id WI-145
+// @work-item-id WI-209
 
 import type { FileInspectorPort } from "../ports/file-inspector-port.js";
 import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
 import type { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
-import { createFinding, projectPath, skillTargetLooksValid } from "./check-utils.js";
+import { createFinding, projectPath, skillDirectoryLooksValid, skillTargetLooksValid } from "./check-utils.js";
 
 export class ClaudeSkillsSymlinkCheck implements HeuristicCheck {
   readonly checkId = "claude-skills-symlink" as const;
@@ -14,11 +15,13 @@ export class ClaudeSkillsSymlinkCheck implements HeuristicCheck {
   async run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
     const link = await inspector.readSymlink(projectPath(projectRoot, this.target));
     if (skillTargetLooksValid(link)) return null;
+    const files = await inspector.listFiles(projectPath(projectRoot, this.target));
+    if (skillDirectoryLooksValid(files)) return null;
     return createFinding({
       checkId: this.checkId,
       severity: "red",
       target: this.target,
-      message: ".claude/skills が phasegate skills を指していません",
+      message: ".claude/skills に phasegate skills がありません",
       repairMode: link === null ? "mechanical" : "manual",
     });
   }

package/scripts/harness/installation/application/checks/codex-skills-symlink-check.ts

@@ -1,11 +1,12 @@
 // @unit installation
 // @layer application
 // @work-item-id WI-145
+// @work-item-id WI-209
 
 import type { FileInspectorPort } from "../ports/file-inspector-port.js";
 import type { HeuristicCheck } from "../../domain/ports/heuristic-check.js";
 import type { DiagnosticFinding } from "../../domain/diagnostic-finding.js";
-import { createFinding, projectPath, skillTargetLooksValid } from "./check-utils.js";
+import { createFinding, projectPath, skillDirectoryLooksValid, skillTargetLooksValid } from "./check-utils.js";
 
 export class CodexSkillsSymlinkCheck implements HeuristicCheck {
   readonly checkId = "codex-skills-symlink" as const;
@@ -14,11 +15,13 @@ export class CodexSkillsSymlinkCheck implements HeuristicCheck {
   async run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
     const link = await inspector.readSymlink(projectPath(projectRoot, this.target));
     if (skillTargetLooksValid(link)) return null;
+    const files = await inspector.listFiles(projectPath(projectRoot, this.target));
+    if (skillDirectoryLooksValid(files)) return null;
     return createFinding({
       checkId: this.checkId,
       severity: "red",
       target: this.target,
-      message: ".codex/skills が phasegate skills を指していません",
+      message: ".codex/skills に phasegate skills がありません",
       repairMode: link === null ? "mechanical" : "manual",
     });
   }

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

@@ -9,6 +9,7 @@
 // @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, readdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -84,8 +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_CLAUDE_SETTINGS_LINK = "../.phasegate-local/claude/settings.json";
-const PERSONAL_CLAUDE_SKILLS_LINK = "../.phasegate-local/skills";
+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);
@@ -312,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({ includeClaude })
+      ? 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);
@@ -330,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 = {
@@ -340,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);
@@ -378,9 +386,9 @@ export class RunInstallUseCase {
 
       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({
@@ -394,14 +402,20 @@ export class RunInstallUseCase {
       }
     }
 
-    if (input.personal && includeClaude) {
-      const item = await this.planPersonalSkills(input);
+    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) {
+      if (input.apply && item.changed && item.repairMode === "mechanical") {
         try {
-          await copyDirectory(join(input.harnessRoot, "skills"), join(input.projectRoot, ".phasegate-local", "skills"));
+          await copyDirectory(join(input.harnessRoot, "skills"), join(input.projectRoot, skillPath));
           await writeFile(
-            join(input.projectRoot, ".phasegate-local", "skills", ".harness-version"),
+            join(input.projectRoot, skillPath, ".harness-version"),
             `${JSON.stringify({ version: input.phasegateVersion, deployedAt: new Date().toISOString(), skillSet }, null, 2)}\n`,
             "utf8",
           );
@@ -412,20 +426,13 @@ export class RunInstallUseCase {
         manifest = this.addManifestEntry(baseManifest, manifest, {
           path: item.path,
           mode: "created",
-          contentForHash: this.personalSkillsHashInput(input.phasegateVersion, skillSet),
+          contentForHash: this.personalSkillsHashInput(item.path, input.phasegateVersion, skillSet),
         });
       }
     }
 
     const linkSpecs = input.personal
-      ? [
-          ...(includeClaude
-            ? [
-                { path: ".claude/settings.json", target: PERSONAL_CLAUDE_SETTINGS_LINK },
-                { path: ".claude/skills", target: PERSONAL_CLAUDE_SKILLS_LINK },
-              ]
-            : []),
-        ]
+      ? []
       : [
           ...(includeClaude ? [{ path: ".claude/skills", target: "../skills" }] : []),
           ...(includeCodex ? [{ path: ".codex/skills", target: "../skills" }] : []),
@@ -455,13 +462,13 @@ export class RunInstallUseCase {
 
     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,
       });
     }
@@ -504,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" },
@@ -564,7 +576,7 @@ export class RunInstallUseCase {
     ];
   }
 
-  private createPersonalTargets(options: { readonly includeClaude: boolean }): readonly InstallTarget[] {
+  private createPersonalTargets(options: { readonly includeClaude: boolean; readonly includeCodex: boolean }): readonly InstallTarget[] {
     return [
       {
         path: ".phasegate-local/phasegate.config.json",
@@ -574,12 +586,21 @@ export class RunInstallUseCase {
       ...(options.includeClaude
         ? [
             {
-              path: ".phasegate-local/claude/settings.json",
+              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,
@@ -639,25 +660,35 @@ export class RunInstallUseCase {
     };
   }
 
-  private async planPersonalSkills(input: RunInstallInput): Promise<InstallPlanItem> {
-    const versionPath = join(input.projectRoot, ".phasegate-local", "skills", ".harness-version");
+  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 changed = current === null || !current.includes(expectedNeedle);
+    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: ".phasegate-local/skills",
-      action: changed ? "missing" : "will-skip",
-      repairMode: "mechanical",
+      path: relativePath,
+      action: changed ? "missing" : unmanagedExisting ? "will-merge" : "will-skip",
+      repairMode: unmanagedExisting ? "manual" : "mechanical",
       strategy: "copy-dir",
       changed,
-      summary: changed ? ".phasegate-local/skills: deploy bundled skills" : ".phasegate-local/skills: already up to date",
-      diff: changed ? "+ bundled skills" : "no changes",
+      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(version: string, skillSet: "core" | "all"): string {
-    return `personal-skills:${version}:${skillSet}`;
+  private personalSkillsHashInput(path: string, version: string, skillSet: "core" | "all"): string {
+    return `personal-skills:${path}:${version}:${skillSet}`;
   }
 
   private addManifestEntry(

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

@@ -5,6 +5,7 @@
 // @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";

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

@@ -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 --agent claude --dry-run` を先に提案する。personal install は `package.json`, `AGENTS.md`, `CLAUDE.md`, `.husky/*`, `.github/workflows/*`, `.gitignore`, GitHub CLI config, repo secrets, CI settings, `.codex/hooks.json` を変更対象にしない。Claude Code向けには `.phasegate-local/phasegate.config.json`, `.phasegate-local/claude/settings.json`, `.phasegate-local/skills/`, ignored root `.claude/settings.json` / `.claude/skills` shim, `.phasegate/manifest.json`, `.git/info/exclude` の managed block を自動作成する。既存 `.claude/*` がある場合は上書きせず manual review として扱う。Codex user-level hook setup は manual action として扱う。<!-- @work-item-id WI-207 --> <!-- @work-item-id WI-208 -->
+- チーム所有リポジトリで個人評価だけを行う相談では、通常の `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 --agent claude` は `package.json`、`AGENTS.md`、`CLAUDE.md`、`.husky/*`、`.github/workflows/*`、`.gitignore`、GitHub CLI config、repo secrets、CI settings、`.codex/hooks.json` を変更せず、`.phasegate-local/phasegate.config.json`、`.phasegate-local/claude/settings.json`、`.phasegate-local/skills/`、ignored root `.claude/settings.json` / `.claude/skills` shim、`.git/info/exclude` の managed block を使う。Codex user-level hook setup は manual action として説明する。<!-- @work-item-id WI-207 --> <!-- @work-item-id WI-208 -->
+チーム所有リポジトリで個人評価だけを行いたい場合は、`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 -->