phasegate 0.160.18 → 0.160.19

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. It creates `.phasegate-local/phasegate.config.json`, local agent context (`.claude/CLAUDE.local.md` and/or `.codex/AGENTS.local.md`), real local-only agent runtime artifacts for the selected agent (`.claude/settings.json` + `.claude/skills/` and/or `.codex/hooks.json` + `.codex/skills/`), local git hooks under `.git/hooks/`, local reference docs under `.phasegate-local/docs/`, 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 --> <!-- @work-item-id WI-213 -->
+`--personal` does not plan or write `package.json`, `CLAUDE.md`, `.husky/*`, `.github/workflows/*`, `.gitignore`, GitHub CLI config, repo secrets, or CI settings. It creates `.phasegate-local/phasegate.config.json`, runtime-visible local agent context (`.claude/CLAUDE.md` for Claude, and `AGENTS.md` for Codex only when that root file is absent or already PhaseGate-managed), real local-only agent runtime artifacts for the selected agent (`.claude/settings.json` + `.claude/skills/` and/or `.codex/hooks.json` + `.codex/skills/`), local git hooks under `.git/hooks/`, local reference docs under `.phasegate-local/docs/`, a managed local-only block in `.git/info/exclude`, and `.phasegate/manifest.json`. If a team `AGENTS.md` already exists, personal Codex install leaves it unchanged and `doctor --personal --agent codex` reports the remaining context step instead of hiding it behind `AGENTS.override.md`. 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 --> <!-- @work-item-id WI-213 --> <!-- @work-item-id WI-215 -->
 
 For agent-driven setup planning, use:
 

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. PhaseGate writes `.phasegate-local/phasegate.config.json`, creates local agent context (`.claude/CLAUDE.local.md` and/or `.codex/AGENTS.local.md`), creates real local-only agent runtime artifacts for the selected agent (`.claude/settings.json` + `.claude/skills/` and/or `.codex/hooks.json` + `.codex/skills/`), deploys local git hooks under `.git/hooks/`, copies reference docs under `.phasegate-local/docs/`, 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 --> <!-- @work-item-id WI-213 -->
+Personal install keeps team-owned files out of the apply path: `package.json`, `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 runtime-visible local agent context (`.claude/CLAUDE.md` for Claude, and `AGENTS.md` for Codex only when that root file is absent or already PhaseGate-managed), creates real local-only agent runtime artifacts for the selected agent (`.claude/settings.json` + `.claude/skills/` and/or `.codex/hooks.json` + `.codex/skills/`), deploys local git hooks under `.git/hooks/`, copies reference docs under `.phasegate-local/docs/`, records `.phasegate/manifest.json`, and manages a local exclude block in `.git/info/exclude`. If a team `AGENTS.md` already exists, personal Codex install leaves it unchanged and `doctor --personal --agent codex` reports the remaining context step instead of hiding it behind `AGENTS.override.md`. 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 --> <!-- @work-item-id WI-213 --> <!-- @work-item-id WI-215 -->
 
 If an existing repository keeps design or governance docs outside `docs/`, set `paths.designDocs`, `paths.inceptionDocs`, `paths.principlesDocs`, and `paths.folderRulesDoc` in `phasegate.config.json` before setup/reconcile. PhaseGate deploy and hook protection use those mappings instead of forcing the default `docs/` layout. <!-- @work-item-id WI-214 -->
 

package/docs/guide/setup-artifacts.md

@@ -7,6 +7,7 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 <!-- @work-item-id WI-169 -->
 <!-- @work-item-id WI-208 -->
 <!-- @work-item-id WI-209 -->
+<!-- @work-item-id WI-215 -->
 
 ## Artifact Classes
 
@@ -16,7 +17,7 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 | 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`, 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 |
+| Personal install artifact | `.phasegate-local/phasegate.config.json`, ignored real `.claude/CLAUDE.md` + `.claude/settings.json` + `.claude/skills/`, ignored real `.codex/hooks.json` + `.codex/skills/`, optional ignored root `AGENTS.md`, `.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 |
 
@@ -44,6 +45,8 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 
 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 -->
 
+Personal agent context is also placed only where the runtime will read it. Claude Code uses `.claude/CLAUDE.md`. Codex uses root `AGENTS.md` when PhaseGate can create or manage it locally; if a team `AGENTS.md` already exists, PhaseGate leaves it unchanged and doctor reports `codex-context-missing` instead of creating `AGENTS.override.md`. <!-- @work-item-id WI-215 -->
+
 Project install uses a different topology: selected bundled skills are deployed once to root `skills/`, and `.claude/skills` / `.codex/skills` point to that shared target. If an older project install has the links but an empty `skills/` target, `phasegate doctor` reports the selected agent skill check and `phasegate reconcile --apply` repairs the shared skill bodies. <!-- @work-item-id WI-210 -->
 
 ## Doctor Findings

package/docs/templates/personal/git-info-exclude

@@ -4,3 +4,4 @@
 .claude/
 skills/
 phasegate.config.json
+AGENTS.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.160.18",
+  "version": "0.160.19",
   "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/claude-context-missing-check.ts

@@ -0,0 +1,35 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-215
+
+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 } from "./check-utils.js";
+
+const MARKDOWN_BEGIN = "<!-- phasegate:managed-section:start -->";
+
+export class ClaudeContextMissingCheck implements HeuristicCheck {
+  readonly checkId = "claude-context-missing" as const;
+  private readonly target = ".claude/CLAUDE.md";
+  private readonly projectTarget = "CLAUDE.md";
+  private readonly legacyTarget = ".claude/CLAUDE.local.md";
+
+  async run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
+    const content = await inspector.readText(projectPath(projectRoot, this.target));
+    if (content?.includes(MARKDOWN_BEGIN) === true && content.includes("PhaseGate")) return null;
+    const projectContent = await inspector.readText(projectPath(projectRoot, this.projectTarget));
+    if (projectContent?.includes(MARKDOWN_BEGIN) === true && projectContent.includes("PhaseGate")) return null;
+
+    const legacyContent = await inspector.readText(projectPath(projectRoot, this.legacyTarget));
+    return createFinding({
+      checkId: this.checkId,
+      severity: "red",
+      target: this.target,
+      message: legacyContent?.includes("PhaseGate") === true
+        ? ".claude/CLAUDE.local.md は Claude Code の documented discovery path ではありません"
+        : ".claude/CLAUDE.md に runtime-visible PhaseGate context がありません",
+      repairMode: "mechanical",
+    });
+  }
+}

package/scripts/harness/installation/application/checks/codex-context-missing-check.ts

@@ -0,0 +1,32 @@
+// @unit installation
+// @layer application
+// @work-item-id WI-215
+
+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 } from "./check-utils.js";
+
+const MARKDOWN_BEGIN = "<!-- phasegate:managed-section:start -->";
+
+export class CodexContextMissingCheck implements HeuristicCheck {
+  readonly checkId = "codex-context-missing" as const;
+  private readonly target = "AGENTS.md";
+  private readonly legacyTarget = ".codex/AGENTS.local.md";
+
+  async run(projectRoot: string, inspector: FileInspectorPort): Promise<DiagnosticFinding | null> {
+    const content = await inspector.readText(projectPath(projectRoot, this.target));
+    if (content?.includes(MARKDOWN_BEGIN) === true && content.includes("PhaseGate")) return null;
+
+    const legacyContent = await inspector.readText(projectPath(projectRoot, this.legacyTarget));
+    return createFinding({
+      checkId: this.checkId,
+      severity: "red",
+      target: this.target,
+      message: legacyContent?.includes("PhaseGate") === true
+        ? ".codex/AGENTS.local.md は Codex の default discovery path ではありません"
+        : "AGENTS.md に runtime-visible PhaseGate context がありません",
+      repairMode: content === null ? "mechanical" : "manual",
+    });
+  }
+}

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

@@ -3,6 +3,7 @@
 // @work-item-id WI-145
 // @work-item-id WI-178
 // @work-item-id WI-208
+// @work-item-id WI-215
 
 import { DiagnosticReport } from "../../domain/diagnostic-report.js";
 import type { CheckId } from "../../domain/check-id.js";
@@ -32,8 +33,8 @@ export interface RunDoctorDiagnosticsOutput {
   readonly exitCode: number;
 }
 
-const CLAUDE_ONLY_CHECKS = new Set<CheckId>(["claude-hook-missing", "claude-skills-symlink"]);
-const CODEX_ONLY_CHECKS = new Set<CheckId>(["codex-hook-missing", "codex-skills-symlink"]);
+const CLAUDE_ONLY_CHECKS = new Set<CheckId>(["claude-hook-missing", "claude-context-missing", "claude-skills-symlink"]);
+const CODEX_ONLY_CHECKS = new Set<CheckId>(["codex-hook-missing", "codex-context-missing", "codex-skills-symlink"]);
 const PERSONAL_SCOPED_OUT_CHECKS = new Set<CheckId>([
   "husky-pre-commit-missing",
   "husky-commit-msg-missing",

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

@@ -13,6 +13,7 @@
 // @work-item-id WI-210
 // @work-item-id WI-213
 // @work-item-id WI-214
+// @work-item-id WI-215
 
 import { mkdir, readFile, writeFile, copyFile, chmod, access, lstat, readlink, symlink, readdir, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -78,6 +79,7 @@ interface InstallTarget {
   readonly templatePath: string;
   readonly executable?: boolean;
   readonly block?: ManagedBlockInput;
+  readonly personalManualIfUnmanaged?: boolean;
 }
 
 const SKILL_HINT = "invoke /phasegate-config-doctor";
@@ -89,7 +91,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"]);
+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";
@@ -350,8 +352,9 @@ export class RunInstallUseCase {
       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)
+        && (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);
@@ -364,7 +367,7 @@ export class RunInstallUseCase {
         strategy: target.strategy,
         changed: didChange,
         summary: unmanagedPersonalRuntimeFile
-          ? `${target.path}: existing non-phasegate path requires manual review`
+          ? `${target.path}: existing non-phasegate runtime 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,
@@ -629,10 +632,11 @@ export class RunInstallUseCase {
       ...(options.includeClaude
         ? [
             {
-              path: ".claude/CLAUDE.local.md",
+              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.local.md managed section" },
+              block: { start: MARKDOWN_BEGIN, end: MARKDOWN_END, content: "phasegate personal .claude/CLAUDE.md managed section" },
+              personalManualIfUnmanaged: true,
             },
             {
               path: ".claude/settings.json",
@@ -644,10 +648,11 @@ export class RunInstallUseCase {
       ...(options.includeCodex
         ? [
             {
-              path: ".codex/AGENTS.local.md",
+              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.local.md managed section" },
+              block: { start: MARKDOWN_BEGIN, end: MARKDOWN_END, content: "phasegate personal AGENTS.md managed section" },
+              personalManualIfUnmanaged: true,
             },
             {
               path: ".codex/hooks.json",

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

@@ -365,7 +365,9 @@ export class RunUninstallUseCase {
     if (mode === "symlink") return "symlink";
     if (mode === "created") return path.endsWith(".yml") || path.endsWith(".yaml") ? "yaml-add" : "created";
     if (path === "package.json") return "package-json";
-    if (path === "AGENTS.md" || path === "CLAUDE.md") return "markdown-managed";
+    if (path === "AGENTS.md" || path === "CLAUDE.md" || path === ".claude/CLAUDE.md" || path === ".claude/CLAUDE.local.md" || path === ".codex/AGENTS.local.md") {
+      return "markdown-managed";
+    }
     if (path === ".git/info/exclude") return "text-managed";
     if (path.endsWith(".json")) return "json";
     if (path.startsWith(".husky/")) return "shell";
@@ -376,7 +378,9 @@ export class RunUninstallUseCase {
     if (path === ".claude/settings.json") return "templates/.claude/settings.json";
     if (path === ".codex/hooks.json") return "templates/.codex/hooks.json";
     if (path === "CLAUDE.md") return "docs/templates/agent-context/CLAUDE.md.template.md";
+    if (path === ".claude/CLAUDE.md" || path === ".claude/CLAUDE.local.md") return "docs/templates/agent-context/CLAUDE.md.template.md";
     if (path === "AGENTS.md") return "docs/templates/agent-context/AGENTS.md.template.md";
+    if (path === ".codex/AGENTS.local.md") return "docs/templates/agent-context/AGENTS.md.template.md";
     throw new Error(`No template for ${path}`);
   }
 

package/scripts/harness/installation/composition-root.ts

@@ -2,9 +2,12 @@
 // @layer presentation
 // @work-item-id WI-145
 // @work-item-id WI-148
+// @work-item-id WI-215
 
+import { ClaudeContextMissingCheck } from "./application/checks/claude-context-missing-check.js";
 import { ClaudeHookMissingCheck } from "./application/checks/claude-hook-missing-check.js";
 import { ClaudeSkillsSymlinkCheck } from "./application/checks/claude-skills-symlink-check.js";
+import { CodexContextMissingCheck } from "./application/checks/codex-context-missing-check.js";
 import { CodexHookMissingCheck } from "./application/checks/codex-hook-missing-check.js";
 import { CodexSkillsSymlinkCheck } from "./application/checks/codex-skills-symlink-check.js";
 import { CiWorkflowMissingCheck } from "./application/checks/ci-workflow-missing-check.js";
@@ -42,7 +45,9 @@ export function createInstallationModule() {
   const hashCalculator = new NodeCryptoHashAdapter();
   const checks = [
     new ClaudeHookMissingCheck(),
+    new ClaudeContextMissingCheck(),
     new CodexHookMissingCheck(),
+    new CodexContextMissingCheck(),
     new HuskyPreCommitMissingCheck(),
     new HuskyCommitMsgMissingCheck(),
     new HuskyPrePushMissingCheck(),

package/scripts/harness/installation/domain/check-id.ts

@@ -1,10 +1,13 @@
 // @unit installation
 // @layer domain
 // @work-item-id WI-145
+// @work-item-id WI-215
 
 export const CHECK_IDS = [
   "claude-hook-missing",
+  "claude-context-missing",
   "codex-hook-missing",
+  "codex-context-missing",
   "husky-pre-commit-missing",
   "husky-commit-msg-missing",
   "husky-pre-push-missing",

package/scripts/harness/installation/domain/repair-table.ts

@@ -1,6 +1,7 @@
 // @unit installation
 // @layer domain
 // @work-item-id WI-145
+// @work-item-id WI-215
 
 import type { CheckId } from "./check-id.js";
 import { SuggestedSkill } from "./suggested-skill.js";
@@ -23,7 +24,9 @@ export class RepairTable {
   constructor() {
     this.table = new Map<CheckId, SuggestedSkill | null>([
       ["claude-hook-missing", CONFIG_DOCTOR],
+      ["claude-context-missing", CONFIG_DOCTOR],
       ["codex-hook-missing", CONFIG_DOCTOR],
+      ["codex-context-missing", CONFIG_DOCTOR],
       ["husky-pre-commit-missing", CONFIG_DOCTOR],
       ["husky-commit-msg-missing", CONFIG_DOCTOR],
       ["husky-pre-push-missing", null],