fix(sdd): make terminal task blocks actionable

[dnlrsls]

Linked Issue

Closes #2629

---

PR Type

• type:bug: Bug fix (non-breaking change that fixes an issue)
• type:feature: New feature (non-breaking change that adds functionality)
• type:docs: Documentation only
• type:refactor: Code refactoring (no functional changes)
• type:chore: Build, CI, or tooling changes
• type:breaking-change: Breaking change (fix or feature that changes existing behavior)

---

Summary

• Preserve executable same-session blocking after an empty or malformed SDD task result.
• Distinguish the original failed phase from a later requested phase that was never launched.
• Give users an actionable recovery: inspect state once, surface the prior failure, then continue in a new OpenCode session after an explicit decision.

---

Changes

File / Area	What Changed
internal/assets/opencode/plugins/review-result-artifacts.ts	Builds typed failures from structured data and emits a truthful actionable handoff for blocked later phases.
internal/assets/review_plugin_recovery_test.go	Covers cross-phase blocking, other-session isolation, lifecycle cleanup, metadata sanitization, and artifact preservation.
internal/assets/assets_test.go	Pins the actionable blocked-failure helper in the plugin asset contract.
bench/axis_sdd_task_result.go	Drives a downstream SDD launch and proves hard blocking plus new-session recovery.

---

Test Plan

Unit Tests

• go test ./internal/assets -count=1
• Focused terminal and lifecycle tests
• go test ./... -count=1 passes in CI. Local execution was environment-limited in non-candidate Windows packages.

Go Format

• go run ./internal/gofmtcheck
• git diff --check origin/main...HEAD

E2E Tests

• E2E passes in CI. e2e/docker-test.sh remains unavailable locally because Docker is not installed and WSL has no Linux distribution.

Benchmark Validation

• Driven tr01-sdd-empty-task-result: 1 completed, 0 unsupported, 0 failed.

Manual Validation

• Confirmed the original phase, code, model, and continuation remain bound to the actual failed task.
• Confirmed the requested later phase is reported as not launched.
• Confirmed a different parent session remains unaffected.

---

Automated Checks

Check	Status	Description
Check PR Cognitive Load	PASS	157 changed lines, below the 400-line budget.
Check Issue Reference	PASS	Body contains Closes #2629.
Check Issue Has status:approved	PASS	#2629 was approved before implementation.
Check PR Has type:* Label	PASS	Exactly type:bug is applied.
Unit Tests	PASS	The full cross-platform suite passed in CI.
Go Format	PASS	Local and CI format checks passed.
E2E Tests	PASS	E2E passed in CI.

---

Contributor Checklist

• PR is linked to an issue with status:approved
• PR stays within 400 changed lines
• I have added the appropriate type:* label to this PR
• Full go test ./... passes in CI
• Go format passes (go run ./internal/gofmtcheck)
• E2E passes in CI
• Benchmark validation completed
• Documentation is not required; the changed behavior is covered by typed summaries, tests, and the driven journey
• My commits follow Conventional Commits format
• My commits do not include Co-Authored-By trailers

---

Notes for Reviewers

Please focus on the ownership boundary: the plugin retains hard no-retry/no-advance enforcement, while the replacement handoff describes the earlier failure rather than claiming the requested phase ran. The wire schema, code, original phase, task model, and continuation remain unchanged.

Summary by CodeRabbit

• Bug Fixes
  • Improved handling of empty or failed SDD task results with clearer terminal recovery guidance.
  • Prevented downstream SDD actions from running after a failed phase until explicit continuation.
  • Isolated failures to the affected session so unrelated sessions can continue normally.
  • Ensured retained failure state is cleared when a session is disposed.

[coderabbitai]

📝 Walkthrough

Walkthrough

The plugin now records structured SDD failures, blocks failed phases within their originating sessions, and provides new-session recovery guidance. Tests and benchmarks validate terminal handoffs, downstream blocking, session isolation, and disposal reset behavior.

Changes

SDD failure recovery

Layer / File(s)	Summary
Structured SDD failure handling internal/assets/opencode/plugins/review-result-artifacts.ts, internal/assets/assets_test.go	SDD failures now store structured summary and continuation data. Blocked phases throw structured failure errors with recovery guidance. Contract tests require blockedSDDTaskFailure.
Session-scoped recovery validation internal/assets/review_plugin_recovery_test.go	Recovery tests distinguish SDD phases, scope failures to parent sessions, validate terminal handoffs and empty-result cases, and verify that dispose clears failures.
Terminal enforcement checks bench/axis_sdd_task_result.go	The benchmark requires typed handoff details, preserved SDD phase information, blocked sdd-apply execution, and new-session instructions.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant SDDTask
  participant review_result_artifacts
  participant OpenCodeSession
  SDDTask->>review_result_artifacts: create structured SDD failure
  review_result_artifacts->>OpenCodeSession: return terminal handoff
  OpenCodeSession->>review_result_artifacts: retry failed SDD phase
  review_result_artifacts-->>OpenCodeSession: block phase and provide new-session guidance

Loading

Possibly related PRs

• Gentleman-Programming/gentle-ai#2186: Both changes address SDD empty-result failure handling across the plugin and recovery tests.
• Gentleman-Programming/gentle-ai#2724: Both changes modify SDD failure recovery in the plugin and its tests.
• Gentleman-Programming/gentle-ai#2750: Both changes modify SDD task failure handling and recovery contract tests.

Suggested reviewers: alan-thegentleman, matam15

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes satisfy issue #2629 by providing typed failure diagnostics, preserving session state, and defining safe new-session recovery guidance.
Out of Scope Changes check	✅ Passed	The plugin changes, tests, asset contract coverage, and benchmark updates directly support actionable terminal SDD failure handling.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the primary change: making terminal SDD task blocks actionable after failures.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[dnlrsls]

Please add Closes #2948 alongside Closes #2629.

The PR satisfies #2948's accepted alternative: after an empty or malformed SDD result it preserves the same-session block, truthfully reports that the later requested phase was not launched, requires a new session after an explicit decision, isolates unrelated sessions, and clears retained state on disposal. The original post-mutation Result Contract loss remains separately tracked by #2855.

[dnlrsls]

Correction to my earlier routing comment: please add Closes #2948, and change Closes #2629 to Refs #2629.

This PR implements #2948's accepted permanent same-session-block alternative: it preserves the block, states that the requested later phase was not launched, requires an explicit decision and a new OpenCode session, isolates other parent sessions, and clears retained state on disposal.

#2629's original generic Pi/provider API failure remains outside this SDD parent-session cache scope, so the PR should reference rather than close it. The dispatched Result Contract loss remains separately tracked by #2855, and the unbound continuation by #2790.

[dnlrsls]

Closing this PR without merging it. As the maintainer clarified in this thread, this SDD same-session block addresses the scope of #2948, not #2629's generic Pi/provider API failure; #2855 and #2790 are separate. #2948 was subsequently delivered by commit e57bcbb with a different truthful sdd_task_dispatch_latched handoff, and #4967 retired the SDD plugin and assets this patch changes. There is no current SDD target for this implementation. This closure does not approve the historical patch or claim its tests passed against current main.

#2629 remains separately NOT_PLANNED, not fixed by this PR. If a current provider flow loses an actionable error, please report exact Gentle AI/gentle-pi/Pi and provider versions, the route and authentication mode, task-settlement evidence, and the caller-visible result so that generic behavior can be assessed on its own.