phasegate 0.153.0 → 0.154.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ 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
+
+- **WI-175 — setup apply structured error exit code** — makes `setup:agent --apply --json` exit non-zero when the underlying install result contains a structured target-aware apply error.
+
 ## [0.153.0] - 2026-05-13
 
 ### Added

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 -->
 
 Start with:
 
@@ -71,3 +71,17 @@ 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.
+
+## 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`.

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 -->
 
 <!-- phasegate:managed-section:start -->
 ## 必読ドキュメント
@@ -13,6 +13,14 @@
 
 {{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.
+
 ## Phase Presets
 
 {{PHASEGATE_PRESETS}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.153.0",
+  "version": "0.154.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/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: [
@@ -1747,7 +1868,7 @@ async function main(): Promise<void> {
           console.log("Validation:");
           for (const command of plan.validation) console.log(`- ${command}`);
         }
-        process.exit(0);
+        process.exit(hasStructuredInstallError(installResult) ? 1 : 0);
         break;
       }