phasegate 0.153.1 → 0.155.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.154.0] - 2026-05-13
+
+### Added
+
+- **WI-176 — Claude Code dogfood readiness** — adds `setup:agent` agent-specific readiness output for Claude, Codex, and shared setup state, plus Claude Code managed context and guide updates for recovery and validation.
+
 ## [0.153.1] - 2026-05-13
 
 ### Fixed

package/README.md

@@ -109,7 +109,7 @@ npx phasegate setup:agent --intent recommended --dry-run --json
 npx phasegate config:plan --intent codex-hooks --dry-run --json
 ```
 
-`setup:agent --json` includes `plan.completeness`, which separates local configured/planned areas from external manual checks such as Codex user-level feature enablement or the first CI run. `config:plan` includes a read-only `configPatch` preview when an intent would change `phasegate.config.json`. <!-- @work-item-id WI-175 -->
+`setup:agent --json` includes `plan.completeness`, which separates local configured/planned areas from external manual checks such as Codex user-level feature enablement or the first CI run. It also includes `plan.agentReadiness` so Claude Code, Codex, and shared setup state can be evaluated separately. `config:plan` includes a read-only `configPatch` preview when an intent would change `phasegate.config.json`. <!-- @work-item-id WI-175, WI-176 -->
 
 The first command reports detected setup state, missing questions, planned managed targets, rollback, and validation. The second maps a configuration change intent to files, commands, risks, and checks. <!-- @work-item-id WI-172, WI-173 -->
 

package/docs/guide/getting-started.md

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

package/docs/guide/troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshooting
 
-<!-- @work-item-id WI-171, WI-172, WI-173, WI-175 -->
+<!-- @work-item-id WI-171, WI-172, WI-173, WI-175, WI-176, WI-177 -->
 
 Start with:
 
@@ -71,3 +71,27 @@ Check `plan.completeness` in `setup:agent --json`:
 - `not-applicable`: the current intent/options did not select that area.
 
 When `install` or `setup:agent --apply` returns a structured `error`, use its `target`, `operation`, `code`, `recovery`, and `partialChanges` fields before rerunning.
+
+Common structured setup errors:
+
+| Code | Usually means | First recovery step |
+|---|---|---|
+| `EPERM` / `EACCES` | The current sandbox, user, or filesystem denied the write. | Ask the user to rerun in a writable workspace or approve the write, then retry the same `--apply` command. |
+| `EEXIST` / `ENOTDIR` | A parent path such as `.claude` or `.codex` exists as a file or incompatible path. | Inspect the path, decide whether it is user-owned, then move or rename it before rerunning. |
+| hash mismatch / refused target | A PhaseGate managed target contains user edits outside the expected hash. | Use `invoke /phasegate-config-doctor` and explain backup, merge, and `--force` tradeoffs before applying. |
+
+## Claude Code Setup Still Feels Unclear
+
+Run the Claude-specific planner path:
+
+```bash
+npx phasegate setup:agent --agent claude --intent strict --with-husky --dry-run --json
+```
+
+Check `plan.agentReadiness`:
+
+- `agent=claude`: local Claude Code targets (`.claude/settings.json`, `CLAUDE.md`, skills).
+- `agent=shared`: package/config/skills plus selected Husky and CI targets.
+- `agent=codex`: should be `not-applicable` unless you selected `--agent both` or `--agent codex`.
+
+When `claude` and `shared` are `configured`, the next step is work planning, not more setup. Confirm or create the WI under `docs/inception/**/{WI-XXX}/description.md`, write the needed inception plan/design files, reflect accepted design into `docs/product/...` with `@work-item-id WI-XXX`, then run `npx phasegate phasegate:check-ready` or the relevant `validate --layer ...` command.

package/docs/templates/agent-context/CLAUDE.md.template.md

@@ -1,6 +1,6 @@
 # CLAUDE.md
 
-<!-- @work-item-id WI-174 -->
+<!-- @work-item-id WI-174, WI-176, WI-177 -->
 
 <!-- phasegate:managed-section:start -->
 ## 必読ドキュメント
@@ -13,6 +13,23 @@
 
 {{PHASEGATE_COMMANDS}}
 
+## Setup Readiness
+
+Before planning implementation work in a new or upgraded repository, run `phasegate setup:agent --agent claude --dry-run --json` and inspect `plan.agentReadiness`.
+
+- `agent=claude` covers `.claude/settings.json`, `CLAUDE.md`, and shared skills.
+- `agent=shared` covers package scripts, `phasegate.config.json`, skills, and selected Husky/CI targets.
+- `manual` or `external-actions` entries require user or hosted-service confirmation; do not treat local readiness as proof that external CI or user-level agent settings are complete.
+
+After the `claude` and `shared` rows are `configured`, move from setup to work planning:
+
+1. Confirm the target WI under `docs/inception/**/{WI-XXX}/description.md`, or create the next unused WI if the user asks for new work.
+2. For implementation work, prepare or update the WI plan/design files under `docs/inception/.../{WI-XXX}/` before editing source or tests.
+3. Reflect the accepted design into the relevant `docs/product/...` files with `@work-item-id WI-XXX`.
+4. Run `phasegate phasegate:check-ready` or the requested `phasegate validate --layer ...` command before committing.
+
+If `setup:agent --apply --json` or `install --apply --json` fails with a structured `error`, explain `target`, `operation`, `code`, `likelyCause`, `recovery`, and `partialChanges` before retrying. Use `invoke /phasegate-config-doctor` for managed target conflicts and `invoke /phasegate-toolkit-guide` for read-only setup guidance.
+
 ## Phase Presets
 
 {{PHASEGATE_PRESETS}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.153.1",
+  "version": "0.155.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",

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

@@ -3,6 +3,7 @@
 // @work-item-id WI-146
 // @work-item-id WI-174
 // @work-item-id WI-175
+// @work-item-id WI-177
 
 import { mkdir, readFile, writeFile, copyFile, chmod, access, lstat, readlink, symlink } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -236,14 +237,16 @@ function likelyCauseFor(code: string): string {
   if (code === "EPERM") return "The filesystem or sandbox denied this write operation.";
   if (code === "EACCES") return "The current user does not have permission to write this target.";
   if (code === "EROFS") return "The project is on a read-only filesystem.";
+  if (code === "EEXIST") return "A parent path already exists as a file or incompatible filesystem entry.";
   if (code === "ENOTDIR") return "A parent path exists but is not a directory.";
   return "The managed target could not be written.";
 }
 
 function recoveryFor(code: string, target: string): string {
-  if (code === "EPERM") return `Review sandbox or filesystem permissions for ${target}, then rerun phasegate setup:agent --apply or phasegate install --apply.`;
+  if (code === "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.`;
   return `Inspect ${target}, run phasegate install --dry-run --json, then rerun with --apply after resolving the filesystem issue.`;
 }
 

package/scripts/harness/main.ts

@@ -5,6 +5,7 @@
  * @work-item-id WI-113 / WI-142
  * @work-item-id WI-171 / WI-172 / WI-173
  * @work-item-id WI-175
+ * @work-item-id WI-176
  *
  * Phasegate CLI エントリポイント。
  * 各Unitの Composition Root からハンドラーを取得し、コマンドに応じてディスパッチする。
@@ -734,6 +735,14 @@ interface SetupCompletenessEntry {
   readonly risk: string | null;
 }
 
+interface AgentReadinessEntry {
+  readonly agent: "claude" | "codex" | "shared";
+  readonly status: SetupCompletenessStatus;
+  readonly evidence: readonly string[];
+  readonly nextAction: string | null;
+  readonly risk: string | null;
+}
+
 interface ConfigPatchOperation {
   readonly op: "add" | "replace";
   readonly pointer: string;
@@ -931,6 +940,117 @@ function buildSetupCompleteness(input: {
   return entries;
 }
 
+function setupReadinessEntry(input: {
+  readonly agent: AgentReadinessEntry["agent"];
+  readonly included: boolean;
+  readonly configured: boolean;
+  readonly configuredEvidence: readonly string[];
+  readonly plannedEvidence: readonly string[];
+  readonly nextAction: string;
+  readonly risk?: string;
+}): AgentReadinessEntry {
+  if (!input.included) {
+    return {
+      agent: input.agent,
+      status: "not-applicable",
+      evidence: ["Not selected for this setup run."],
+      nextAction: null,
+      risk: null,
+    };
+  }
+  if (input.configured) {
+    return {
+      agent: input.agent,
+      status: "configured",
+      evidence: input.configuredEvidence,
+      nextAction: null,
+      risk: input.risk ?? null,
+    };
+  }
+  return {
+    agent: input.agent,
+    status: "planned",
+    evidence: input.plannedEvidence,
+    nextAction: input.nextAction,
+    risk: input.risk ?? null,
+  };
+}
+
+function buildAgentReadiness(input: {
+  readonly agent: AgentTarget;
+  readonly withHusky: boolean;
+  readonly withCi: boolean;
+  readonly checks: {
+    readonly packageJson: boolean;
+    readonly phasegateConfig: boolean;
+    readonly claudeSettings: boolean;
+    readonly codexHooks: boolean;
+    readonly agentsMd: boolean;
+    readonly claudeMd: boolean;
+    readonly huskyPreCommit: boolean;
+    readonly ciWorkflow: boolean;
+    readonly skillsVersion: boolean;
+  };
+}): readonly AgentReadinessEntry[] {
+  const includeClaude = input.agent === "claude" || input.agent === "both";
+  const includeCodex = input.agent === "codex" || input.agent === "both";
+  const sharedConfigured =
+    input.checks.packageJson &&
+    input.checks.phasegateConfig &&
+    input.checks.skillsVersion &&
+    (!input.withHusky || input.checks.huskyPreCommit) &&
+    (!input.withCi || input.checks.ciWorkflow);
+
+  return [
+    setupReadinessEntry({
+      agent: "claude",
+      included: includeClaude,
+      configured: input.checks.claudeSettings && input.checks.claudeMd && input.checks.skillsVersion,
+      configuredEvidence: [
+        ".claude/settings.json is present.",
+        "CLAUDE.md is present.",
+        "skills/.harness-version is present for the .claude/skills link target.",
+      ],
+      plannedEvidence: [
+        "setup:agent will create or refresh .claude/settings.json.",
+        "setup:agent will create or refresh the CLAUDE.md PhaseGate managed section.",
+        "setup:agent will deploy bundled skills for Claude Code.",
+      ],
+      nextAction: "Run setup:agent --agent claude --apply, then ask Claude Code to read CLAUDE.md before planning work.",
+    }),
+    setupReadinessEntry({
+      agent: "codex",
+      included: includeCodex,
+      configured: input.checks.codexHooks && input.checks.agentsMd && input.checks.skillsVersion,
+      configuredEvidence: [
+        ".codex/hooks.json is present.",
+        "AGENTS.md is present.",
+        "skills/.harness-version is present for the .codex/skills link target.",
+      ],
+      plannedEvidence: [
+        "setup:agent will create or refresh .codex/hooks.json.",
+        "setup:agent will create or refresh the AGENTS.md PhaseGate managed section.",
+        "setup:agent will deploy bundled skills for Codex.",
+      ],
+      nextAction: "Run setup:agent --agent codex --apply, then enable codex_hooks at user level if needed.",
+      risk: "Codex user-level hook feature enablement remains a manual external check.",
+    }),
+    setupReadinessEntry({
+      agent: "shared",
+      included: true,
+      configured: sharedConfigured,
+      configuredEvidence: [
+        "package.json, phasegate.config.json, skills, and selected Husky/CI targets are present.",
+      ],
+      plannedEvidence: [
+        "setup:agent will create or refresh package scripts, phasegate.config.json, skills, and selected Husky/CI targets.",
+      ],
+      nextAction: "Run setup:agent --apply, then phasegate doctor, phasegate phasegate:check-ready, and phasegate validate --layer L2 --format human.",
+      risk: input.withCi ? "A hosted CI run remains an external manual check." : undefined,
+    }),
+  ];
+}
+
 async function buildAgentSetupPlan(rootDir: string, input: {
   readonly intent: SetupIntent;
   readonly agent: AgentTarget;
@@ -970,6 +1090,7 @@ async function buildAgentSetupPlan(rootDir: string, input: {
     agent: input.agent,
     detected: checks,
     completeness: buildSetupCompleteness({ ...input, checks }),
+    agentReadiness: buildAgentReadiness({ ...input, checks }),
     questions,
     changes,
     risks: [

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

@@ -133,6 +133,7 @@ product-architect で Unit を作り、いくつかの logical_design を書い
 - Codex の `codex_hooks` feature flag は user-level setting。project-local `install` では変更されないため、必要なら `codex features enable codex_hooks` を案内
 - Codex native `apply_patch` bypass は hook で完全捕捉できない。`.husky/pre-commit` の `phasegate pre-commit` が backstop になるため、Husky 配線を診断対象に含める
 - 初回 setup / retrofit / CI-only / agent-hooks の判断が曖昧な場合は `npx phasegate setup:agent --dry-run --json` を先に使い、検出済み状態、質問、変更案、rollback、validation を根拠として提案する。<!-- @work-item-id WI-172 -->
+- Claude Code setup 相談では `npx phasegate setup:agent --agent claude --dry-run --json` を先に使い、`plan.agentReadiness` の `claude` / `shared` が `configured` なら setup 修復ではなく WI 起票、inception 計画、product reflection、validation の順で作業開始を案内する。`setup:agent --apply --json` または `install --apply --json` の structured `error` がある場合は、`target`, `operation`, `code`, `likelyCause`, `recovery`, `partialChanges` を読み、`.claude` が file として存在する path conflict、sandbox/permission denial、PhaseGate managed target hash mismatch を区別して説明する。<!-- @work-item-id WI-177 -->
 - 「L4 を厳しめにして」「Codex hook を有効にして」「CI で warning を fail にして」などの自然言語依頼は、`npx phasegate config:plan --intent <intent> --dry-run --json` で対象ファイル、コマンド、リスク、検証を確認してから diff を提案する。<!-- @work-item-id WI-173 -->
 - `AGENTS.md` は標準運用ルールの managed section と lesson pointer section を分ける。`ci:auto-refresh-agent-context --apply` は lesson pointers 専用 section を更新し、標準運用ルールや user-owned content を置換してはいけない。<!-- @work-item-id WI-174 -->
 

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

@@ -134,6 +134,8 @@ docs/guide/                          # phasegate リポジトリ自体 (dogfood)
 
 `setup:agent` は初回 setup / retrofit / CI-only / agent hook 有効化の agent-readable planner、`config:plan` は安全な設定変更 intent planner。質問が「次に何を実行するか」「この変更はどの file/validation に対応するか」に寄っている場合は、これらの guide と CLI を案内する。<!-- @work-item-id WI-171, WI-172, WI-173 -->
 
+Claude Code readiness の質問では `npx phasegate setup:agent --agent claude --dry-run --json` を案内し、`plan.agentReadiness` の `claude` / `shared` が `configured` なら setup ではなく作業導線へ進める。最短ルートは、WI の確認または起票、`docs/inception/.../{WI-XXX}/` への計画/設計、`docs/product/...` への `@work-item-id WI-XXX` 反映、`phasegate phasegate:check-ready` または該当 `validate` の実行である。`setup:agent --apply --json` の structured `error` は troubleshooting に委譲し、`target` / `operation` / `code` / `recovery` を読ませる。<!-- @work-item-id WI-177 -->
+
 ### 8. skill 一覧と使い分け
 
 ユーザー質問例: