docs(review): close deterministic target adoption

Author: elkaix

docs/en/release-notes/changelog.md

@@ -17,6 +17,10 @@ GitHub Releases page; `0.8.0` is the new starting line.
 
 ## Unreleased
 
+- **Reviewer subagents now receive deterministic Git scopes.** Structured automatic,
+  uncommitted, base, and commit targets resolve to full commit anchors before dispatch, reject
+  invalid or empty scopes explicitly, and keep repository metadata isolated from instructions
+  across foreground and background runs.
 - **Parallel streamed tool calls are now correlated safely.** Interleaved argument chunks stay attached to their indexed calls, malformed or truncated call streams stop before tool execution, and failed attempts are not retried after output has already been shown.
 - **Provider compatibility and Z.AI routing are now explicit.** Immutable compatibility profiles keep request-format quirks behind the chat-provider boundary, while independent Z.AI Coding Plan and API login routes use separate credentials, endpoints, model identities, catalog refresh, logout, and usage/rate-limit state. Curated GLM requests now apply exact context/output limits, thinking controls, reasoning replay, and tool-stream support without activating for local or unknown models.
 

docs/superpowers/specs/2026-07-15-review-target-resolution-design.md

@@ -1,6 +1,7 @@
 # Deterministic reviewer target resolution design
 
-**Status:** Approved on 2026-07-15
+**Status:** Implemented; feature verified, repository gate baseline-blocked on the clean-main PTY
+Escape test (2026-07-15)
 
 ## Problem
 

tasks/agent-harness-adoption-plan.md

@@ -48,11 +48,19 @@ generic pythinker agent enhancements — no external product names in code, comm
 
 **Files.** `src/pythinker_code/ui/print/__init__.py`, `<ref>/exec/src/lib.rs`
 
-### `review-mode/deterministic-review-target-resolution-and-prompt-synthesis` — partial, S, high
-
-**Today.** The standalone review engine resolves diffs deterministically with base/staged/working-tree/range modes, fallback refs, and a fallback audit trail (packages/pythinker-review/src/pythinker_review/engine/diff_source.py). But agent-mediated review dispatch leaves git scoping entirely to the model — system.md only instructs it prose-style to compute the merge base (src/pythinker_code/agents/default/system.md:120), and git-context injection is gated to explore subagents only (src/pythinker_code/subagents/core.py:90).
-
-**Verifier note.** Claim CONFIRMED as stated; all three cited anchors verified. The standalone engine is deterministic; the agent-mediated path has no deterministic diff scoping anywhere — the review/code-reviewer subagent specs receive scope purely via the parent's prompt text.
+### `review-mode/deterministic-review-target-resolution-and-prompt-synthesis` — done, S, high
+
+**Today.** Done. `src/pythinker_code/subagents/review_target.py` resolves structured auto,
+uncommitted, base, and commit targets before child allocation. `subagents/core.py` composes generic
+Git context, the caller task, and the authoritative target in that order and revalidates live
+`HEAD`; the Agent/RunAgents and background manager/runner paths preserve the requested and resolved
+target plus its safe hint across foreground and background execution.
+
+**Verifier note.** DONE. Resolver, malformed/empty/failure, merge, fallback, and drift behavior is
+pinned by `tests/subagents/test_review_target.py`; prompt ordering and resume behavior by
+`tests/core/test_prepare_soul.py`; tool schema, foreground, and mixed-batch transport by
+`tests/tools/test_agent_tool.py`; and background persistence/transport/failure by
+`tests/background/test_manager.py` and `tests/background/test_task_metadata.py`.
 
 **Adopt.** Add a small resolver (target -> prompt + hint) that precomputes the merge-base SHA via the async git helper and renders one of three template prompts (uncommitted / base-branch-with-sha + backup variant / commit-with-title), then prepend it to the review subagent's prompt at dispatch. Also extend collect_git_context injection in subagents/core.py to reviewer-class agents so every review run starts with branch, dirty files, and merge-base already in context instead of burning turns rediscovering them.
 

tasks/lessons.md

@@ -5,6 +5,10 @@ Format: trigger → rule.
 
 ## Subagent orchestration
 
+- **When testing that subagent preparation failed before a prompt snapshot was written**, assert
+  that `prompt.txt` remains empty rather than absent — `SubagentStore` intentionally pre-creates
+  instance files during allocation, so path existence is not evidence of a snapshot write.
+
 - **When dispatching subagents whose results you will immediately synthesize**
   (review + report, parallel analysis with no interleaved work), use
   **foreground fan-out** (`RunAgents` foreground mode) — results return inline,

tasks/todo.md

@@ -9,15 +9,42 @@
 - [x] Review and approve
       `docs/superpowers/specs/2026-07-15-review-target-resolution-design.md`.
 - [x] Write the implementation plan with TDD and verification checkpoints.
-- [ ] Implement the approved plan in the isolated feature worktree.
-- [ ] Add the required `CHANGELOG.md` Unreleased entry.
-- [ ] Run focused tests, `make check-pythinker-code`, `make test-pythinker-code`, and final review.
+- [x] Implement the approved plan in the isolated feature worktree.
+- [x] Add the required `CHANGELOG.md` Unreleased entry.
+- [x] Run focused tests, `make check-pythinker-code`, `make test-pythinker-code`, and final review.
 
 Acceptance: every fresh reviewer receives one pre-resolved authoritative Git target; invalid or
 empty explicit targets fail before child allocation; `Agent` and per-child `RunAgents` behavior is
 identical across foreground and background execution; generic Git context cannot contradict the
 resolved target; non-reviewer and resume behavior remains compatible.
 
+#### Review: deterministic reviewer target resolution
+
+- **Outcome:** structured auto, uncommitted, base, and commit targets now resolve before reviewer
+  allocation; foreground, per-child batch, and background paths preserve the requested and resolved
+  target and fail explicitly at the appropriate boundary.
+- **Reviewed range:** `10aedf26..a12a4840` (seven branch commits, from the design checkpoint through
+  the amended failure-boundary hardening commit).
+- **Focused verification:** the exact 11-file feature set passed `289 passed, 1 warning in 14.43s`.
+- **Static verification:** `make check-pythinker-code` passed with Ruff clean, `1262 files already
+  formatted`, Pyright `0 errors, 0 warnings, 0 informations`, and ty clean.
+- **Repository test gate:** `make test-pythinker-code` remains red solely at
+  `tests/e2e/test_shell_pty_e2e.py::test_shell_cancel_running_command_kills_process_and_recovers`:
+  `1 failed, 7131 passed, 9 skipped, 1 xfailed, 5 warnings in 379.30s`, before the separate
+  `tests_e2e` phase. The isolated branch node also failed because Escape was ignored and the command
+  completed; the identical isolated node fails on clean `main`, proving this is a baseline,
+  out-of-scope blocker rather than a feature regression.
+- **Remaining branch verification:** excluding only that baseline node passed `7131 passed, 9
+  skipped, 1 deselected, 1 xfailed, 5 warnings in 325.71s`; the separate `tests_e2e` suite passed
+  `65 passed, 4 skipped, 1 warning in 89.35s`. `git diff --check` was silent.
+- **Review verdict:** final implementation review after `a12a4840` found no Critical, Important, or
+  Minor findings; C01/C03/C05/C06/C08/C12/C13/C14/C15 all passed; ready to merge: yes.
+- **Approved limitation:** uncommitted/base scopes pin `HEAD` and revalidate it immediately before
+  execution, but the index and worktree remain explicitly live. The feature does not claim an
+  immutable patch snapshot.
+- **Blocker:** the repository-wide package test gate is blocked solely by the reproducible
+  clean-main PTY Escape failure above. No feature-owned failure remains.
+
 ### TUI thinking Markdown and activity motion (2026-07-11)
 
 - [x] Execute `docs/superpowers/plans/2026-07-11-tui-thinking-markdown-and-activity-motion.md`