feat(boatstack): repeated denials escalate their solutions, never their severity

labs/12-product-engineering-loop/boatstack-distribution/release-notes/2026-07-27-repeated-denials-escalate.md

@@ -0,0 +1,5 @@
+### A denial that repeats escalates its help, not its severity
+
+An agent that hits the same guardrail again and again is telling you the stated rule is not reaching it — and under that pressure agents drift toward worse moves, not better ones. The guard now keeps a small per-worktree count of identical denials. From the third identical denial, the message escalates its corrective information: the pick list expands from three commands to the full legal set, and the denial prescribes a fresh diagnostic (`boatstack-helper doctor`) instead of leaving the loop to continue.
+
+Nothing about admissibility changes — what was denied stays denied, what was allowed stays allowed, and the constitutional destruction floor is untouched. Any allowed mutating call counts as forward progress and clears the history, so an old denial streak never escalates an unrelated message. The ledger lives with the rest of the worktree's control state, is bounded, and degrades silently: if its file is corrupt or unwritable, the denial simply renders unescalated.

labs/12-product-engineering-loop/product-engineering-loop/denial.go

@@ -70,6 +70,31 @@ type Denial struct {
 	// denials), derived from the state-ownership map. Named, never compiled
 	// into runnable commands — their full arguments are not derivable here.
 	OwnerVerbs []string
+	// Escalated marks a denial that has repeated past the ledger threshold:
+	// the rendering lifts the pick-list cap to the full set and prescribes a
+	// fresh diagnostic. More corrective information, never more severity —
+	// what is denied never changes.
+	// control-law: repeated-denials-escalate-to-solutions
+	Escalated   bool
+	RepeatCount int
+}
+
+// optionTextLimit is the pick-list cap for the text renderings: compact by
+// default, the full structured cap once the denial has escalated.
+func (d Denial) optionTextLimit() int {
+	if d.Escalated {
+		return solutionSetCap
+	}
+	return solutionSetTextCap
+}
+
+// escalationLine is the repeat notice with the fresh-probe prescription; empty
+// until the denial escalates.
+func (d Denial) escalationLine() string {
+	if !d.Escalated {
+		return ""
+	}
+	return fmt.Sprintf("This denial repeated %d times. Run: boatstack-helper doctor --repo .", d.RepeatCount)
 }
 
 // --- ANSI palette (truecolor; matches the approved mockup) -------------------
@@ -160,10 +185,13 @@ func (d Denial) renderPlain(badge string) string {
 	if len(d.OwnerVerbs) > 0 {
 		b.WriteString("\n\nThis path is owned by: " + strings.Join(d.OwnerVerbs, ", ") + ".")
 	}
-	if lines := d.optionLines(solutionSetTextCap); len(lines) > 0 {
+	if lines := d.optionLines(d.optionTextLimit()); len(lines) > 0 {
 		b.WriteString("\n\nYou can:\n")
 		b.WriteString(strings.Join(lines, "\n"))
 	}
+	if escalation := d.escalationLine(); escalation != "" {
+		b.WriteString("\n\n" + escalation)
+	}
 	if d.Hint != "" {
 		b.WriteString("\n\nFalse positive? run: ")
 		b.WriteString(d.Hint)
@@ -186,12 +214,15 @@ func (d Denial) renderMarkdown(badge string) string {
 	if len(d.OwnerVerbs) > 0 {
 		b.WriteString("\n\nThis path is owned by: `" + strings.Join(d.OwnerVerbs, "`, `") + "`.")
 	}
-	if lines := d.optionLines(solutionSetTextCap); len(lines) > 0 {
+	if lines := d.optionLines(d.optionTextLimit()); len(lines) > 0 {
 		b.WriteString("\n\nYou can:\n")
 		for _, line := range lines {
 			b.WriteString("\n" + line)
 		}
 	}
+	if escalation := d.escalationLine(); escalation != "" {
+		b.WriteString("\n\n" + escalation)
+	}
 	if d.Hint != "" {
 		b.WriteString("\n\nFalse positive? run `" + d.Hint + "`")
 	}
@@ -214,12 +245,15 @@ func (d Denial) renderANSI(badge string) string {
 	if len(d.OwnerVerbs) > 0 {
 		b.WriteString("\n" + fgGray + "this path is owned by: " + ansiReset + fgCode + strings.Join(d.OwnerVerbs, ", ") + ansiReset)
 	}
-	if lines := d.optionLines(solutionSetTextCap); len(lines) > 0 {
+	if lines := d.optionLines(d.optionTextLimit()); len(lines) > 0 {
 		b.WriteString("\n" + fgGray + "you can:" + ansiReset)
 		for _, line := range lines {
 			b.WriteString("\n" + fgCode + line + ansiReset)
 		}
 	}
+	if escalation := d.escalationLine(); escalation != "" {
+		b.WriteString("\n" + fgGray + escalation + ansiReset)
+	}
 	if d.Hint != "" {
 		b.WriteString("\n" + fgGray + ansiDim + "false positive? run " + ansiReset + fgCode + d.Hint + ansiReset)
 	}
@@ -293,6 +327,10 @@ func (d Denial) Structured() map[string]any {
 	if len(d.OwnerVerbs) > 0 {
 		out["owner_verbs"] = d.OwnerVerbs
 	}
+	if d.Escalated {
+		out["escalated"] = true
+		out["repeat_count"] = d.RepeatCount
+	}
 	return out
 }
 
@@ -401,6 +439,10 @@ func denialWithOptions(repo, host string, finding SafetyFinding) Denial {
 	if finding.Category == "workflow-state-tamper" {
 		d.OwnerVerbs = tamperOwnerVerbs(repo, finding.AttemptedPath)
 	}
+	if finding.RepeatCount >= denialEscalationThreshold {
+		d.Escalated = true
+		d.RepeatCount = finding.RepeatCount
+	}
 	return d
 }
 

labs/12-product-engineering-loop/product-engineering-loop/denial_escalation_conformance_test.go

@@ -0,0 +1,176 @@
+package boatstack
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// control-law: repeated-denials-escalate-to-solutions
+//
+// Repetition of one denial is the signal that the stated law is not reaching
+// the model (the sibling harness's paid canary: sixteen identical no-progress
+// repair attempts, then a protected-boundary write). A repeat denial escalates
+// its corrective INFORMATION — the full solution set plus a fresh diagnostic
+// probe — never its severity or its admissibility. Boundaries held here:
+// the per-worktree ledger (recordDenial/resetDenialLedger), the HookDecision
+// deny/allow wiring, and the escalated rendering. The constitutional corpus
+// floor is held separately by safety_corpus_test.go and is untouched: this law
+// changes what a denial says, never what is denied.
+
+func tamperEvent(path string) []byte {
+	return []byte(fmt.Sprintf(
+		`{"hook_event_name":"PreToolUse","tool_name":"Write","tool_input":{"file_path":%q,"content":"{}"}}`, path))
+}
+
+// Positive: the third identical denial escalates — the rendering carries the
+// repeat notice and the fresh-probe prescription; the first two do not.
+func TestThirdIdenticalDenialEscalates(t *testing.T) {
+	repo := safetyTestRepo(t)
+	event := tamperEvent(".git/boatstack/deliveries/demo/state.json")
+	for attempt := 1; attempt <= denialEscalationThreshold; attempt++ {
+		output, denied := HookDecision(SafetyHookOptions{Host: "claude", Repo: repo, Input: event})
+		if !denied {
+			t.Fatalf("attempt %d: tamper write must be denied", attempt)
+		}
+		escalated := strings.Contains(string(output), "This denial repeated")
+		if attempt < denialEscalationThreshold && escalated {
+			t.Fatalf("attempt %d escalated before the threshold:\n%s", attempt, output)
+		}
+		if attempt == denialEscalationThreshold {
+			if !escalated {
+				t.Fatalf("attempt %d must escalate:\n%s", attempt, output)
+			}
+			if !strings.Contains(string(output), fmt.Sprintf("repeated %d times", denialEscalationThreshold)) {
+				t.Fatalf("escalation must carry the repeat count:\n%s", output)
+			}
+			if !strings.Contains(string(output), "boatstack-helper doctor") {
+				t.Fatalf("escalation must prescribe the fresh diagnostic:\n%s", output)
+			}
+		}
+	}
+}
+
+// Negative/reset: an ALLOWED mutation-capable call is forward progress and
+// clears the ledger — the next denial starts unescalated.
+func TestAllowedMutationResetsTheLedger(t *testing.T) {
+	repo := safetyTestRepo(t)
+	event := tamperEvent(".git/boatstack/deliveries/demo/state.json")
+	for i := 0; i < denialEscalationThreshold-1; i++ {
+		if _, denied := HookDecision(SafetyHookOptions{Host: "claude", Repo: repo, Input: event}); !denied {
+			t.Fatal("tamper write must be denied")
+		}
+	}
+	allowed := []byte(fmt.Sprintf(
+		`{"hook_event_name":"PreToolUse","tool_name":"Write","tool_input":{"file_path":%q,"content":"export const x = 1"}}`,
+		filepath.Join(repo, "src", "app.ts")))
+	if _, denied := HookDecision(SafetyHookOptions{Host: "claude", Repo: repo, Input: allowed}); denied {
+		t.Fatal("ordinary product write must be allowed")
+	}
+	output, denied := HookDecision(SafetyHookOptions{Host: "claude", Repo: repo, Input: event})
+	if !denied {
+		t.Fatal("tamper write must still be denied after the reset")
+	}
+	if strings.Contains(string(output), "This denial repeated") {
+		t.Fatalf("ledger must reset after allowed progress:\n%s", output)
+	}
+}
+
+// Relation: different denial keys never cross-escalate, and a read-only
+// allowed call does NOT reset the ledger (only mutation progress does).
+func TestDenialKeysAreIsolated(t *testing.T) {
+	repo := safetyTestRepo(t)
+	tamper := SafetyFinding{Category: "workflow-state-tamper", Source: "delivery-state"}
+	phase := SafetyFinding{Category: "workflow-phase-bypass", WorkflowStage: "DRAFT_PLAN", Source: "planning-state"}
+	if got := recordDenial(repo, tamper); got != 1 {
+		t.Fatalf("first tamper count = %d, want 1", got)
+	}
+	if got := recordDenial(repo, tamper); got != 2 {
+		t.Fatalf("second tamper count = %d, want 2", got)
+	}
+	if got := recordDenial(repo, phase); got != 1 {
+		t.Fatalf("a different category must count from 1, got %d", got)
+	}
+	// Same category at a different stage is a different key.
+	other := SafetyFinding{Category: "workflow-phase-bypass", WorkflowStage: "APPROVED", Source: "planning-state"}
+	if got := recordDenial(repo, other); got != 1 {
+		t.Fatalf("same category at a different stage must count from 1, got %d", got)
+	}
+	// A read-only allowed call must not reset: HookDecision only resets on
+	// mutation-capable allows, so the tamper key keeps its count.
+	readonly := []byte(`{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"git status"}}`)
+	if _, denied := HookDecision(SafetyHookOptions{Host: "claude", Repo: repo, Input: readonly}); denied {
+		t.Fatal("git status must be allowed")
+	}
+	if got := recordDenial(repo, tamper); got != 3 {
+		t.Fatalf("read-only allow must not reset the ledger; tamper count = %d, want 3", got)
+	}
+}
+
+// Failure-state: bookkeeping degrades, the denial never does. A corrupt ledger
+// starts fresh; an unresolvable repository still yields a usable count; the
+// escalated rendering is identical in admissibility to the unescalated one.
+func TestLedgerFailuresDegradeCalmly(t *testing.T) {
+	repo := safetyTestRepo(t)
+	path, ok := denialLedgerPath(repo)
+	if !ok {
+		t.Fatal("ledger path must resolve in a git fixture")
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte("{not json"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	finding := SafetyFinding{Category: "workflow-state-tamper", Source: "delivery-state"}
+	if got := recordDenial(repo, finding); got != 1 {
+		t.Fatalf("corrupt ledger must start fresh, got %d", got)
+	}
+	if got := recordDenial(t.TempDir(), finding); got < 1 {
+		t.Fatalf("an unresolvable ledger must still return a usable count, got %d", got)
+	}
+}
+
+// Bypass/bound: the ledger is pruned to its key bound, oldest first, so a
+// category-spraying session cannot grow unbounded per-worktree state.
+func TestLedgerStaysBounded(t *testing.T) {
+	repo := safetyTestRepo(t)
+	for i := 0; i < denialLedgerMaxKeys+8; i++ {
+		recordDenial(repo, SafetyFinding{Category: fmt.Sprintf("category-%02d", i), Source: "test"})
+	}
+	path, _ := denialLedgerPath(repo)
+	ledger := loadDenialLedger(path)
+	if len(ledger.Counts) > denialLedgerMaxKeys {
+		t.Fatalf("ledger holds %d keys, bound is %d", len(ledger.Counts), denialLedgerMaxKeys)
+	}
+}
+
+// Rendering: escalation lifts the pick cap to the full structured set and the
+// structured payload carries escalated/repeat_count; severity is unchanged.
+func TestEscalatedRenderingLiftsTheCapNotTheSeverity(t *testing.T) {
+	finding := SafetyFinding{
+		Category: "workflow-phase-bypass", Source: "planning-state",
+		WorkflowStage: "DRAFT_PLAN", NextOperation: "plan-gate", BlockingFeature: "demo",
+	}
+	calm := denialWithOptions(".", "claude", finding)
+	finding.RepeatCount = denialEscalationThreshold
+	escalated := denialWithOptions(".", "claude", finding)
+	if !escalated.Escalated || escalated.Severity != calm.Severity || escalated.Category != calm.Category {
+		t.Fatalf("escalation must change information only: %+v vs %+v", escalated, calm)
+	}
+	if len(escalated.Options) != len(calm.Options) {
+		t.Fatalf("the option SET is identical; only the rendered cap lifts")
+	}
+	if escalated.optionTextLimit() <= calm.optionTextLimit() && len(calm.Options) > calm.optionTextLimit() {
+		t.Fatal("escalated rendering must show more of the set")
+	}
+	structured := escalated.Structured()
+	if structured["escalated"] != true || structured["repeat_count"] != denialEscalationThreshold {
+		t.Fatalf("structured payload must carry escalation: %v", structured)
+	}
+	if _, present := calm.Structured()["escalated"]; present {
+		t.Fatal("unescalated payload must not carry the escalation keys")
+	}
+}