devrites 3.2.21 → 3.2.22

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to DevRites are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and DevRites adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from Conventional Commits on `main`.
 
+## [3.2.22](https://github.com/ViktorsBaikers/DevRites/compare/v3.2.21...v3.2.22) (2026-07-28)
+
+### Fixed
+
+* **devrites:** prevent receipt-only agent spawns ([4cf4c19](https://github.com/ViktorsBaikers/DevRites/commit/4cf4c19cf8671b8fdd497b8875c50bd50faf85d9))
+
 ## [3.2.21](https://github.com/ViktorsBaikers/DevRites/compare/v3.2.20...v3.2.21) (2026-07-28)
 
 ### Fixed

package/README.md

@@ -25,7 +25,7 @@ final commit, push, and tag, and it requires a typed `GO` confirmation.
 Unattended runs may create local WIP checkpoint commits along the way, but only
 Ship collapses and pushes them.
 
-**Status:** [`v3.2.21`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.2.21): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v3.2.22`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.2.22): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 ## Quick start
 

package/engine/hooks_agent_dispatch.go

@@ -853,6 +853,10 @@ func conditionalDispatchInstruction() string {
 	return "CONDITIONAL DISPATCH RULE — If this skill reaches a child-agent step, call spawn_agent with the exact named agent_type=devrites-<role> specified by the skill, a unique task_name, and fork_turns=\"none\". GPT-5.6 V2 may omit agent_type from the visible tool schema; send agent_type anyway and never use a default child. Wait for the returned child and use its non-empty result."
 }
 
+func preDispatchStopInstruction() string {
+	return "PRE-DISPATCH STOP RULE — If a deterministic prerequisite forces STOP before any spawn attempt, do not spawn only to satisfy this receipt. Run exactly one successful standalone devrites-engine dispatch-waive <reason> before replying. Use only the matching observed predicate: no-active-workspace, wrong-phase, readiness-failed, no-eligible-work, or human-gate-before-dispatch. The successful PostToolUse receipt is required; never waive after a spawn attempt."
+}
+
 func incompleteDispatchReason(armed map[string]struct{}, attempts []*agentDispatchAttempt) string {
 	roles := make([]string, 0, len(armed))
 	for role := range armed {
@@ -871,7 +875,11 @@ func incompleteDispatchReason(armed map[string]struct{}, attempts []*agentDispat
 	if role == agentDispatchMetadataRole {
 		return "DevRites could not determine this skill's required agents because its installed required-agent-roles contract is invalid. Reinstall or repair the DevRites skill pack before continuing."
 	}
-	return fmt.Sprintf("DevRites dispatch for %s is not complete. %s", role, dispatchInstruction(role))
+	reason := fmt.Sprintf("DevRites dispatch for %s is not complete. %s", role, dispatchInstruction(role))
+	if len(attempts) == 0 {
+		reason += " " + preDispatchStopInstruction()
+	}
+	return reason
 }
 
 func preToolDeny(h harness.Harness, reason string, stdout, stderr io.Writer) int {
@@ -1022,8 +1030,9 @@ func hookAgentDispatch(h harness.Harness, stdin io.Reader, stdout, stderr io.Wri
 			}
 			fmt.Fprintf(
 				stdout,
-				"MANDATORY DISPATCH THIS TURN — At the skill's dispatch step, execute every required child before finishing or claiming completion; a success phrase is not evidence.\n%s",
+				"MANDATORY DISPATCH THIS TURN — At the skill's dispatch step, execute every required child before finishing or claiming completion; a success phrase is not evidence.\n%s\n%s",
 				strings.Join(instructions, "\n"),
+				preDispatchStopInstruction(),
 			)
 		}
 		if skillInvoked {

package/engine/tests/hook_test.go

@@ -1441,6 +1441,12 @@ func TestCodexAgentDispatchPromptGivesExactNamedCallBeforeCompletion(t *testing.
 		".codex/agents/" + role + ".toml",
 		"send agent_type anyway",
 		"Wait for the returned child",
+		"PRE-DISPATCH STOP RULE",
+		"do not spawn only to satisfy this receipt",
+		"devrites-engine dispatch-waive <reason>",
+		"readiness-failed",
+		"human-gate-before-dispatch",
+		"never waive after a spawn attempt",
 	} {
 		if !strings.Contains(out, want) {
 			t.Fatalf("initial dispatch guidance omitted %q:\n%s", want, out)
@@ -1692,7 +1698,9 @@ func TestCodexAgentDispatchBlocksFalseWaitAndStop(t *testing.T) {
 	if stopDecision.Decision != "block" ||
 		!strings.Contains(stopDecision.Reason, "spawn_agent") ||
 		!strings.Contains(stopDecision.Reason, "visible tool schema") ||
-		!strings.Contains(stopDecision.Reason, "send agent_type anyway") {
+		!strings.Contains(stopDecision.Reason, "send agent_type anyway") ||
+		!strings.Contains(stopDecision.Reason, "do not spawn only to satisfy this receipt") ||
+		!strings.Contains(stopDecision.Reason, "dispatch-waive <reason>") {
 		t.Fatalf("false completion not blocked: %#v", stopDecision)
 	}
 
@@ -1745,7 +1753,7 @@ func TestCodexAgentDispatchRequiresSuccessfulReasonBoundWaiver(t *testing.T) {
 		t.Fatalf("chained waiver was not denied: %s", out)
 	}
 
-	command := "devrites-engine dispatch-waive wrong-phase"
+	command := "devrites-engine dispatch-waive readiness-failed"
 	pre := hookPayload(t, map[string]any{
 		"hook_event_name": "PreToolUse",
 		"session_id":      sessionID,
@@ -1775,7 +1783,7 @@ func TestCodexAgentDispatchRequiresSuccessfulReasonBoundWaiver(t *testing.T) {
 		"turn_id":         turnID,
 		"tool_name":       "functions.exec_command",
 		"tool_input":      map[string]any{"cmd": command},
-		"tool_response":   "dispatch-waive: accepted wrong-phase",
+		"tool_response":   "dispatch-waive: accepted readiness-failed",
 	})
 	if out, stderr, code := runDevritesIO(t, root, post, nil,
 		"hook", "agent-dispatch", "--harness=codex"); code != 0 || strings.TrimSpace(out) != "" {
@@ -1887,6 +1895,7 @@ func TestCodexAgentDispatchConfirmsGenericRoleAndResult(t *testing.T) {
 	}
 	var blocked struct {
 		Decision string `json:"decision"`
+		Reason   string `json:"reason"`
 	}
 	if err := json.Unmarshal([]byte(strings.TrimSpace(out)), &blocked); err != nil {
 		t.Fatalf("invalid unawaited Stop response: %v\n%s", err, out)
@@ -1894,6 +1903,9 @@ func TestCodexAgentDispatchConfirmsGenericRoleAndResult(t *testing.T) {
 	if blocked.Decision != "block" {
 		t.Fatalf("unawaited child result passed Stop: %s", out)
 	}
+	if strings.Contains(blocked.Reason, "dispatch-waive") {
+		t.Fatalf("unavailable post-spawn waiver was suggested: %s", out)
+	}
 
 	wait := hookPayload(t, map[string]any{
 		"hook_event_name": "PreToolUse",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devrites",
-  "version": "3.2.21",
+  "version": "3.2.22",
   "description": "DevRites: a disciplined senior-engineer workflow pack for Claude Code and Codex",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/ViktorsBaikers/DevRites#readme",