fix(#5182): watch a GSD-owned return receipt instead of the host transcript in the plan-phase stall watch

.changeset/lively-sloths-forage.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 5192
+---
+**plan-phase's stall watch now waits for the planner and plan-checker to actually return** — it no longer reports them finished at its first check because their own prompt or definition mentions the return markers, and a finished plan revision now continues instead of always ending in the stall menu. The plan-checker now declares `Write` for that one receipt file, so on Codex it runs `workspace-write` instead of `read-only`, and on Claude Code it is denied only `Edit` and `MultiEdit`; on OpenCode, Kilo and Copilot, which grant Write and Edit as one permission, the installer drops that `Write`, so the checker stays read-only there and writes no receipt. No receipt is created when the phase directory is a symlink or resolves outside the project root plan-phase resolved (for example through a symlinked parent), when its path has a `.` or `..` component, or when it holds a control character; a one-line stderr reason names the refusal, and the watch then ends on the agent's own completion result or as stalled. (#5182)

agents/gsd-plan-checker.md

@@ -1,8 +1,14 @@
 ---
 name: gsd-plan-checker
 description: Verifies plans will achieve phase goal before execution. Goal-backward analysis of plan quality. Spawned by /gsd:plan-phase orchestrator.
-tools: Read, Bash, Glob, Grep, Skill
+tools: Read, Write, Bash, Glob, Grep, Skill
 color: green
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "npx eslint --fix $FILE 2>/dev/null || true"
 ---
 
 <role>
@@ -960,6 +966,12 @@ Return all issues as a structured `issues:` YAML list (see dimension examples fo
 
 <structured_returns>
 
+**Return receipt (#5182):** if your prompt has a `<return_receipt>PATH</return_receipt>` line,
+your LAST action is to write the marker line you are about to return (e.g. `## ISSUES FOUND`)
+to PATH with the Write tool; never use `Bash(cat << 'EOF')` or heredoc. Its directory already exists. This is your only write: never use
+Write on a plan or any other file. If the write fails, or you have no Write tool (an install drops it where
+Write would grant full edit), note that in your return and continue; never write it another way.
+
 ## VERIFICATION PASSED
 
 ```markdown
@@ -1031,6 +1043,8 @@ Plans verified. Run `/gsd:execute-phase {phase}` to proceed.
 
 <anti_patterns>
 
+**DO NOT** use Write on any file except the `<return_receipt>` path, if your prompt gives one. You never write, split or fix a plan.
+
 **DO NOT** check code existence — that's gsd-verifier's job. You verify plans, not codebase.
 
 **DO NOT** run the application. Static plan analysis only.

agents/gsd-planner.md

@@ -931,6 +931,12 @@ See @~/.claude/gsd-core/references/planner-chunked.md for `## OUTLINE COMPLETE`
 
 Your orchestrator dispatches on exact marker strings in your final output. Emit exactly one of:
 
+**Return receipt (#5182):** if your prompt has a `<return_receipt>PATH</return_receipt>` line,
+your LAST action, after every plan write and commit, is to write the marker line you are about to
+return (e.g. `## PLANNING COMPLETE`, or `## REVISION COMPLETE` in revision mode) to PATH with
+the Write tool. Its directory already exists. The orchestrator's bounded stall watch reads only
+that file, so never write it early.
+
 ```markdown
 ## PLANNING COMPLETE
 ```
@@ -961,6 +967,11 @@ Your orchestrator dispatches on exact marker strings in your final output. Emit
 ```
 (cannot produce a plan, include exactly what is missing)
 
+```markdown
+## REVISION COMPLETE
+```
+(revision mode only — checker issues addressed; shape: `gsd-core/references/planner-revision.md` Step 7)
+
 ```markdown
 ## REVISION_CONFLICT
 ```

docs/AGENTS.md

@@ -239,8 +239,8 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp
 |----------|-------|
 | **Spawned by** | `/gsd-plan-phase` (verification loop, max 3 iterations) |
 | **Parallelism** | Single instance (iterative) |
-| **Tools** | Read, Bash, Glob, Grep, Skill |
-| **Disallowed Tools** | Write, Edit, MultiEdit |
+| **Tools** | Read, Write, Bash, Glob, Grep, Skill |
+| **Disallowed Tools** | Edit, MultiEdit |
 | **Model (balanced)** | Sonnet |
 | **Color** | Green |
 | **Produces** | PASS/FAIL verdict with specific feedback |
@@ -868,7 +868,7 @@ Thirteen additional agents ship under `agents/gsd-*.md` and are used by specialt
 | planner | ✓ | ✓ | | ✓ | ✓ | ✓ | | ✓ | ✓ |
 | roadmapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
 | executor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |
-| plan-checker | ✓ | | | ✓ | ✓ | ✓ | | | |
+| plan-checker | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
 | integration-checker | ✓ | | | ✓ | ✓ | ✓ | | | |
 | ui-checker | ✓ | | | ✓ | ✓ | ✓ | | | |
 | verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
@@ -882,7 +882,7 @@ Thirteen additional agents ship under `agents/gsd-*.md` and are used by specialt
 | security-auditor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |
 
 **Principle of Least Privilege:**
-- Checkers are read-only (no Write/Edit) — they evaluate, never modify
+- Checkers never modify what they check (no Edit); plan-checker's one Write is its stall-watch return receipt (#5182). OpenCode, Kilo and Copilot grant Write and Edit as one `edit` permission, so the installer drops plan-checker's Write there: it stays read-only and writes no receipt
 - Researchers have web access — they need current ecosystem information
 - Executors have Edit — they modify code but not web access
 - Mappers have Write — they write analysis documents but not Edit (no code changes)

docs/ja-JP/AGENTS.md

@@ -221,7 +221,7 @@ GSD はマルチエージェントアーキテクチャを採用しており、
 |------------|-----|
 | **スポーン元** | `/gsd-plan-phase`（検証ループ、最大3回の反復） |
 | **並列数** | 単一インスタンス（反復型） |
-| **ツール** | Read, Bash, Glob, Grep |
+| **ツール** | Read, Write, Bash, Glob, Grep |
 | **モデル (balanced)** | Sonnet |
 | **カラー** | Green |
 | **生成物** | 具体的なフィードバック付きの PASS/FAIL 判定 |
@@ -411,7 +411,7 @@ GSD はマルチエージェントアーキテクチャを採用しており、
 | planner | ✓ | ✓ | | ✓ | ✓ | ✓ | | ✓ | ✓ |
 | roadmapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
 | executor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |
-| plan-checker | ✓ | | | ✓ | ✓ | ✓ | | | |
+| plan-checker | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
 | integration-checker | ✓ | | | ✓ | ✓ | ✓ | | | |
 | ui-checker | ✓ | | | ✓ | ✓ | ✓ | | | |
 | verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
@@ -422,7 +422,7 @@ GSD はマルチエージェントアーキテクチャを採用しており、
 | user-profiler | ✓ | | | | | | | | |
 
 **最小権限の原則:**
-- チェッカーは読み取り専用（Write/Edit なし） — 評価のみを行い、変更は行わない
+- チェッカーは確認対象を変更しない（Edit なし） — plan-checker の唯一の Write はストール監視用のリターンレシート（#5182）。OpenCode・Kilo・Copilot は Write と Edit を 1 つの `edit` 権限として付与するため、インストーラーはそこで plan-checker の Write を外す（読み取り専用のまま、レシートは書かれない）
 - リサーチャーは Web アクセスを持つ — 最新のエコシステム情報が必要なため
 - エグゼキューターは Edit を持つ — コードを変更するが Web アクセスは不要
 - マッパーは Write を持つ — 分析ドキュメントを作成するが Edit は不要（コード変更なし）

docs/ko-KR/AGENTS.md

@@ -221,7 +221,7 @@ GSD는 멀티 에이전트 아키텍처를 사용합니다. 가벼운 오케스
 |----------|-------|
 | **생성 주체** | `/gsd-plan-phase` (검증 루프, 최대 3회 반복) |
 | **병렬성** | 단일 인스턴스 (반복적) |
-| **도구** | Read, Bash, Glob, Grep |
+| **도구** | Read, Write, Bash, Glob, Grep |
 | **모델 (balanced)** | Sonnet |
 | **색상** | Green |
 | **생성물** | 구체적인 피드백을 포함한 PASS/FAIL 판정 |
@@ -411,7 +411,7 @@ GSD는 멀티 에이전트 아키텍처를 사용합니다. 가벼운 오케스
 | planner | ✓ | ✓ | | ✓ | ✓ | ✓ | | ✓ | ✓ |
 | roadmapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
 | executor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | |
-| plan-checker | ✓ | | | ✓ | ✓ | ✓ | | | |
+| plan-checker | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
 | integration-checker | ✓ | | | ✓ | ✓ | ✓ | | | |
 | ui-checker | ✓ | | | ✓ | ✓ | ✓ | | | |
 | verifier | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
@@ -422,7 +422,7 @@ GSD는 멀티 에이전트 아키텍처를 사용합니다. 가벼운 오케스
 | user-profiler | ✓ | | | | | | | | |
 
 **최소 권한 원칙.**
-- Checker는 읽기 전용입니다 (Write/Edit 없음) — 평가만 하며 수정하지 않습니다
+- Checker는 검사 대상을 수정하지 않습니다 (Edit 없음) — plan-checker의 유일한 Write는 stall 감시용 반환 영수증입니다 (#5182). OpenCode, Kilo, Copilot은 Write와 Edit를 하나의 `edit` 권한으로 부여하므로, 설치 프로그램은 그곳에서 plan-checker의 Write를 제거합니다 (읽기 전용으로 유지되고 영수증은 작성되지 않습니다)
 - Researcher는 웹 접근 권한을 가집니다 — 최신 생태계 정보가 필요하기 때문입니다
 - Executor는 Edit 권한을 가집니다 — 코드를 수정하지만 웹 접근은 없습니다
 - Mapper는 Write 권한을 가집니다 — 분석 문서를 작성하지만 Edit은 없습니다 (코드 변경 없음)

gsd-core/references/agent-contracts.md

@@ -11,7 +11,7 @@ This doc describes what IS, not what should be. Casing inconsistencies are docum
 | Agent | Role | Completion Markers | Consumed by | Kind |
 |-------|------|--------------------|--------------|------|
 | gsd-ai-researcher | AI framework research | No marker (writes the AI-SPEC.md framework section via Edit) | `gsd-core/workflows/ai-integration-phase.md` reads the AI-SPEC.md section after the agent returns | artifact+query |
-| gsd-planner | Plan creation | `## PLANNING COMPLETE`, `## OUTLINE COMPLETE`, `## PHASE SPLIT RECOMMENDED`, `## ⚠ Source Audit`, `## CHECKPOINT REACHED`, `## PLANNING INCONCLUSIVE`, `## REVISION_CONFLICT` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/plan-phase/steps/chunked-planning-mode.md`, `gsd-core/workflows/plan-review-convergence.md`, `gsd-core/workflows/quick.md`, `gsd-core/workflows/quick/steps/plan-checker-loop.md`, `gsd-core/workflows/verify-work.md` | sentinel-match |
+| gsd-planner | Plan creation | `## PLANNING COMPLETE`, `## OUTLINE COMPLETE`, `## PHASE SPLIT RECOMMENDED`, `## ⚠ Source Audit`, `## CHECKPOINT REACHED`, `## PLANNING INCONCLUSIVE`, `## REVISION COMPLETE`, `## REVISION_CONFLICT` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/plan-phase/steps/chunked-planning-mode.md`, `gsd-core/workflows/plan-review-convergence.md`, `gsd-core/workflows/quick.md`, `gsd-core/workflows/quick/steps/plan-checker-loop.md`, `gsd-core/workflows/verify-work.md` | sentinel-match |
 | gsd-executor | Plan execution | `## PLAN COMPLETE`, `## CHECKPOINT REACHED` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/plan-phase/steps/chunked-planning-mode.md`, `agents/gsd-debug-session-manager.md`, `agents/gsd-debugger.md` | sentinel-match |
 | gsd-phase-researcher | Phase-scoped research | `## RESEARCH COMPLETE`, `## RESEARCH BLOCKED` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/quick/steps/research-phase.md`, `agents/gsd-project-researcher.md` | sentinel-match |
 | gsd-project-researcher | Project-wide research | `## RESEARCH COMPLETE`, `## RESEARCH BLOCKED` | `gsd-core/workflows/plan-phase.md`, `gsd-core/workflows/quick/steps/research-phase.md`, `agents/gsd-phase-researcher.md` | sentinel-match |