phasegate 0.154.0 → 0.155.0

package/docs/guide/troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshooting
 
-<!-- @work-item-id WI-171, WI-172, WI-173, WI-175, WI-176 -->
+<!-- @work-item-id WI-171, WI-172, WI-173, WI-175, WI-176, WI-177 -->
 
 Start with:
 
@@ -72,6 +72,14 @@ Check `plan.completeness` in `setup:agent --json`:
 
 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:
@@ -85,3 +93,5 @@ 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, WI-176 -->
+<!-- @work-item-id WI-174, WI-176, WI-177 -->
 
 <!-- phasegate:managed-section:start -->
 ## 必読ドキュメント
@@ -21,6 +21,15 @@ Before planning implementation work in a new or upgraded repository, run `phaseg
 - `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.154.0",
+  "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/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 一覧と使い分け
 
 ユーザー質問例: