feat: recover empty and tool-end finalize (v0.7.3)

Detect synthetic blocked JSON and empty finalize, run finish-steer recovery
passes, and fall back to provisional done when disk/tool evidence already
proves writes landed. Add Python/Go knowledge bars for language expectations.

Author: piotrlaczkowski

Formula/slmcode.rb

@@ -9,7 +9,7 @@
 class Slmcode < Formula
   desc "Coding harness for SLMs and any OpenAI-compatible LLM"
   homepage "https://unicolab.ai"
-  version "0.7.2"
+  version "0.7.3"
   license "MIT"
 
   on_macos do

Makefile

@@ -1,6 +1,6 @@
 MODULE := github.com/UnicoLab/slmcode
 BIN    := slmcode
-VERSION ?= 0.7.2
+VERSION ?= 0.7.3
 PREFIX ?= $(HOME)/.local
 GIT_COMMIT := $(shell git rev-parse --short HEAD 2>/dev/null || echo unknown)
 BUILD_TIME := $(shell date -u +%Y-%m-%dT%H:%M:%SZ)

TODO.md

@@ -1,109 +1 @@
-## Fix agents in the studio
-**Done.** `GET /api/agents/{id}` returns full config including built-in `system_prompt`. Studio loads detail on row click / Edit. TUI `/agent show|edit` seeds from the same path. Verified live via Studio API.
 
-## Tester agent
-**Done.** Tester prompt/skill require real `ws_shell` execution. Soft-pass without `commands[]` is rejected. Per-task tester finish schema fixed. Finalize mandates commands. Live oMLX run executed `python main.py --help` / smoke checks.
-
-## Project plan
-**Done.** `ParsePlanJSON` accepts string or object steps; never dumps raw JSON into Summary. Unparsed output goes to a fenced Raw appendix. Live PLAN.md stayed structured.
-
-## Spec / functional code quality
-**Done.** Clarifier + greenfield harness (`requirements.txt` / pytest smoke) + auto tester task.
-Deterministic `post_worker_smoke` (`py_compile` / `go test`) before review; pre-test smoke before LLM tester;
-QA gate uses compileall/pytest (never `--help`). Soft-pass needs real Observation/smoke evidence.
-Live oMLX greenfield e2e PASS (~98s).
-
-## TUI improvements
-**Done.** Live throttled redraw during runs + mid-run board refresh. `KindDebug` for runner internals (hidden by default). Studio Debug toggle. Compact mode default on. SSE prefers latest event under backpressure.
-
-## Check the current failure and improve
-**Done.** Full `go test ./...` green. Offline quality e2e + live `TestLiveQualityGreenfieldPython` (oMLX) PASS — produced working `main.py` with real execution evidence.
-
-## Planning / scoping (PRD interview)
-**Done.** Claude Code AskUserQuestion + pi-clarify style interviewer (`clarify_mode`: auto|ask|off),
-locked PRD in CONTEXT, Studio ask modal + `POST /api/clarify/answer`, post-split `scope_judge`
-enriching every task with concrete acceptance/checklist before execute.
-
-## Claude Code gap ports
-**Done.** Plan approve gate · real CONTEXT `/compact context` · interactive shell ask ·
-wave rewind snapshots · hooks.json Pre/PostToolUse · thin read-only MCP (`mcp_call`) ·
-wired `auto_approve`.
-
-## little-coder SLM harness ports
-**Done.** Write-guard · read-before-edit · shell-write guard · tool/knowledge inject ·
-quality-monitor · reserved device names · path normalize · tool-output truncate.
-
-## Code quality > giant LLMs
-**Done.** Numbered ws_read + offset/limit + auto-trim · fuzzy edit recovery · static gate ·
-require smoke · finalize-warn + thinking-budget · text tool-call detection · JS smoke ·
-knowledge cards · stricter reviewer/corrector · cooler temps.
-
-**Also done.** Over-edit guard (refuse whole-file-style edits) · no-op edit refuse ·
-claims gate (hallucinated `files_changed`) · worker self-critique on weak output ·
-algorithm cheat-sheets (binary search, DP, two pointers, BFS/DFS, backtracking, sort).
-Config: `claims_gate`, `worker_critique`, `over_edit_guard` (default ON).
-
-## little-coder quality ports (round 4)
-**Done.** Worker multipass when `think_passes≥2` (incomplete JSON → critique/refine) ·
-finalize mid-run steer on ReAct resume · react context-watchdog (conversation compact at
-80% of `max_context_kb` with #68 hysteresis). Config: `react_compact`,
-`react_compact_at_percent` (default ON / 80).
-
-## little-coder quality ports (round 5)
-**Done.** Mid-ReAct loopguard (refuse verbatim repeated tool calls via wrappers) ·
-output-parser extract + arg-rich text-tool nudge · edit/write/patch failure recovery
-cards in tool results. `quality_monitor` now also wraps coding tools at register time.
-
-## little-coder quality ports (round 6)
-**Done.** Remaining knowledge cards (hash/tree/BFS-state/io-wrapper/string-rules/zipper) ·
-bash SAFE_PREFIXES whitelist (`shell_whitelist`, `shell_allow`) · thinking-budget hard
-abort recovery (post-turn) · first-write-wins file checkpoints · per-model profiles
-(`model_profiles`) · malformed_args quality detection.
-
-## UX + eval (v0.6.0)
-**Done.** `KindIntervention` / `KindTurn` SSE · TUI banners + turn meter + progress strip ·
-prompt history · `/clear` · `/plan` · richer `/help` · Studio intervention banner + turn chip ·
-read trim by context % · `slmcode eval` + `pkg/eval` harness · Studio UI markers aligned.
-
-## Quality: no more false success on placeholder scaffolds (TestSLMs)
-**Done.** Root cause: `promoteBoardOnQAGreen` + weak `compileall` QA rubber-stamped
-escalated/blocked tasks; static gate missed `# Placeholder implementation`; existence-only
-acceptance / already-satisfied skipped real work; Studio had no escalate intervention.
-
-Fixes:
-- Never promote escalated / `status=blocked` / missing files / static stubs on QA green
-- Weak QA (`compileall` / `py_compile`) does not clear tester rejection or escalate backlog
-- Run success requires no escalated tasks left
-- Static quality catches Placeholder comments + stub constant returns
-- Review-time static insurance + Studio `KindIntervention` on escalate / stub refuse
-- Vague acceptance rejects "exists and contain…", "tool evidence", `pytest --collect-only`
-- Architect/splitter/reviewer/tester/worker prompts require functional code, not stubs
-- Greenfield harness now catches "setup/template/folder structure" + LangGraph class agents
-  (auto-adds requirements.txt, main.py, pytest) + LangGraph knowledge card
-- Studio Live: overview grid (status / activity / enrich / deps) + dedicated `LiveLogs` panel
-- Studio pipeline header redesigned: Prepare/Design/Build/Verify/Finish groups, track fill,
-  live agent/task, board %, harness intervention chip
-- Static gate rejects `from langgraph import Graph`; clarifier/PRD defaults force runnable
-  LangGraph acceptance; e2e `TestLangGraphTemplateQueryPath` locks the harness path
-- Placeholder specialist (`@placeholder`) + project-wide stub scan after execute (polish phase);
-  fills real code or flags precise `path:line` gaps; Studio continue-ask when retries/QA
-  exhausted (`continue` / `stop` / `flag_only`) via `/api/continue/*`
-
-## Pipeline config + reference-quality bar (v0.7.0)
-**Done.** Config-driven pipeline (`.slmcode/pipeline.yaml`) with phase agent bindings,
-execute-loop reviewer/corrector, and insertable slots (before/after/replace) with full
-prompt/params control. Studio Pipeline tab + dynamic progress header follow the same config.
-`GET/PUT /api/pipeline`, custom agents usable in specialist mode and board roles.
-
-Also: project completeness reference bar (LangGraph/FastAPI/CLI), real-query eval suite,
-loop SSE (`kind=loop`) with continue/abort UX, preserve harness tasks when capping to 8,
-docs for pipeline + updated agents/studio/config/architecture.
-
-## Runnable quality bar + escalate HITL (v0.7.1 / v0.7.2)
-**Done.** Push SLM output past "compiles": greenfield Python QA → pytest; whitelisted
-acceptance commands run after workers; critique until smoke/static/acceptance green;
-syntax-only QA cannot alone mark run success.
-
-Mid-execute escalate pauses with Studio modal + `GET/POST /api/escalate/*`;
-TUI `/escalate re_scope|retry|mark_done|abort`. On timeout **@escalate** (or
-`escalate_timeout_agent`) decides — not blind re_scope.

cmd/slmcode/version.go

@@ -4,7 +4,7 @@ package main
 //
 //	go build -ldflags "-X main.Version=0.5.0 -X main.SourceRoot=/path -X main.GitCommit=abc -X main.BuildTime=…"
 var (
-	Version    = "0.7.2"
+	Version    = "0.7.3"
 	SourceRoot = "" // absolute path to the slmcode checkout used to build this binary
 	GitCommit  = "unknown"
 	BuildTime  = "unknown"

docs/changelog.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v0.7.3 — Incomplete finalize recovery
+
+### Highlights
+- Detect empty finalize and synthetic `model ended on a tool call` blocked JSON
+- Up to two finish-steer corrector passes (demand status JSON, stop tool chains)
+- Provisional done from disk/tool evidence when finalize still fails
+- Knowledge cards: Python / Go project bars for language expectations
+
+---
+
 ## v0.7.2 — Escalate timeout → SLM arbitrator
 
 ### Highlights

docs/install.md

@@ -75,7 +75,7 @@ One-liners fetch a shiny GitHub Release. Keep the compiler for contributing (or
 
     ```bash
     curl -fsSL https://raw.githubusercontent.com/UnicoLab/smlcode/main/scripts/install-remote.sh \
-      | bash -s -- --version v0.7.2
+      | bash -s -- --version v0.7.3
     ```
 
 === "🪟 PowerShell"

pkg/augment/augment.go

@@ -180,6 +180,34 @@ After writes: install deps if needed, run smoke, then status=done.`,
 - ZERO stub markers or fake {"output":"run_result"} returns
 After writes: pip install -r requirements.txt && python -m pytest -q && python main.py`,
 		},
+		{
+			Topic: "Python Project Bar", TokenCost: 120,
+			Keywords: []string{
+				"python", "pytest", "pip", "requirements.txt", "pyproject", "venv",
+				"fastapi", "django", "flask", ".py",
+			},
+			RequiresTools: []string{"ws_write", "ws_shell"},
+			Body: `Python expectations (unless the repo already disagrees):
+- Real modules, not Placeholder/TODO stubs; prefer typed public functions
+- tests/ with pytest (or test_*.py next to modules); no fake green asserts
+- requirements.txt or pyproject.toml with pinned direct deps
+- Entry: main.py or package __main__; runnable smoke after install
+Verify: python -m pip install -r requirements.txt && python -m pytest -q`,
+		},
+		{
+			Topic: "Go Project Bar", TokenCost: 120,
+			Keywords: []string{
+				"golang", "go mod", "go test", "go.mod", "goroutine", "pkg/",
+				"cmd/", ".go",
+			},
+			RequiresTools: []string{"ws_write", "ws_shell"},
+			Body: `Go expectations (unless the repo already disagrees):
+- Valid module path in go.mod; packages compile with go test ./... -short
+- Exported APIs documented lightly; no panic("TODO") / unimplemented stubs
+- Prefer table-driven tests; keep edits inside listed packages
+- cmd/ for entrypoints, pkg/ or internal/ for libraries when scaffolding
+Verify: go test ./... -short (or targeted package) before status=done`,
+		},
 	}
 	return append(base, AlgorithmKnowledge()...)
 }

pkg/augment/augment_test.go

@@ -84,3 +84,18 @@ func TestSelectKnowledgeLangGraphClassAgent(t *testing.T) {
 		t.Fatalf("expected LangGraph Class Agent card, got %#v", ks)
 	}
 }
+
+func TestSelectKnowledgePythonAndGoBars(t *testing.T) {
+	py := SelectKnowledge("add pytest coverage for the fastapi python service", DefaultKnowledge(), 400)
+	goK := SelectKnowledge("fix go test failures in pkg/loop", DefaultKnowledge(), 400)
+	assertTopic := func(ks []KnowledgeEntry, topic string) {
+		for _, k := range ks {
+			if k.Topic == topic {
+				return
+			}
+		}
+		t.Fatalf("expected %s card, got %#v", topic, ks)
+	}
+	assertTopic(py, "Python Project Bar")
+	assertTopic(goK, "Go Project Bar")
+}

pkg/loop/runner.go

@@ -344,62 +344,9 @@ func (r *Runner) runWave(ctx context.Context, board *plan.Board, wave []plan.Tas
 		if res.Iteration > 0 {
 			r.fireTurn(t.ID, res.Iteration, roleMaxIter(role))
 		}
-		// SLMs sometimes emit a bare tool call / empty finalize — nudge one corrective pass.
-		needNudge := looksLikeToolJunk(t.Output)
-		nudgeIssue := "Finish the task and return status JSON. Do not end on a tool call. Prefer ws_edit/ws_patch (ws_read first); ws_write only for NEW files."
-		if r.QualityMonitor && !needNudge {
-			assess := quality.AssessResponse(t.Output, nil, nil, nil)
-			if !assess.OK {
-				needNudge = true
-				nudgeIssue = quality.CorrectionMessage(assess.Reason)
-				if strings.HasPrefix(assess.Reason, "text_tool_calls:") {
-					if calls := quality.ParseTextToolCalls(t.Output); len(calls) > 0 {
-						nudgeIssue = quality.TextToolNudge(calls)
-					}
-				}
-				r.Log("%s quality-monitor: %s", t.ID, quality.PhraseForUser(assess.Reason))
-				r.fireIntervention(t.ID, assess.Reason, quality.PhraseForUser(assess.Reason), assess.Reason)
-			}
-		}
-		if !needNudge {
-			if calls := quality.ParseTextToolCalls(t.Output); len(calls) > 0 {
-				needNudge = true
-				nudgeIssue = quality.TextToolNudge(calls)
-				if r.AutoTextTools {
-					nudgeIssue = "AUTO_TEXT_TOOLS: re-issue these as NATIVE tool calls immediately, then status JSON.\n" + nudgeIssue
-				}
-				r.Log("%s text-tool-parser: recovered %d call(s)", t.ID, len(calls))
-				r.fireIntervention(t.ID, "text_tool_calls", "text tool calls recovered", nudgeIssue)
-			}
-		}
-		if !needNudge && r.ThinkingBudget &&
-			quality.ThinkingBudgetExceeded(t.Output, r.ThinkingBudgetTokens) {
-			needNudge = true
-			nudgeIssue = quality.ThinkingBudgetBreachMessage()
-			r.Log("%s thinking-budget: exceeded — forcing commit pass", t.ID)
-			r.fireIntervention(t.ID, "thinking_budget_exceeded", "thinking budget exceeded", nudgeIssue)
-		}
-		if needNudge {
-			r.Log("%s produced incomplete finalize; running corrector once", t.ID)
-			r.fire("agent_start", r.correctorID(), t.ID, "fix incomplete finalize", strings.Join(t.Files, ", "), "")
-			corrIn := formatCorrectPrompt(t, plan.ReviewResult{
-				Approved: false,
-				Issues:   []string{nudgeIssue},
-				Summary:  "incomplete finalize",
-			})
-			corr, _ := r.Executor.ExecuteSubAgents(ctx, []ggagent.SubAgentRequest{{
-				AgentID: r.correctorID(),
-				Input:   corrIn,
-				Timeout: r.Timeout, ShareState: true,
-			}}, r.Shared)
-			if len(corr) > 0 {
-				r.noteUsage(corr[0], corrIn, outputString(corr[0]))
-				if out := outputString(corr[0]); strings.TrimSpace(out) != "" {
-					t.Output = out
-				}
-			}
-			r.fire("agent_end", r.correctorID(), t.ID, "corrector finished", "", truncate(t.Output, 800))
-		}
+		// SLMs often empty-finalize or end on tool-junk / synthetic blocked JSON.
+		// Recover up to 2 finish-steer passes; then provisional-done if disk proves writes.
+		r.recoverIncompleteFinalize(ctx, &t, snapshots[i])
 		mergeFilesChanged(&t)
 		// Attach disk evidence hint for reviewer.
 		if hint := r.diskEvidenceHint(t, snapshots[i]); hint != "" {
@@ -1166,9 +1113,114 @@ func outputString(res ggagent.SubAgentResult) string {
 }
 
 func looksLikeToolJunk(raw string) bool {
-	lower := strings.ToLower(raw)
-	return strings.Contains(lower, "<function") || strings.Contains(lower, "<tool_call>") ||
-		strings.Contains(lower, "</tool_call>")
+	return quality.LooksLikeToolJunk(raw)
+}
+
+// recoverIncompleteFinalize nudges the corrector (up to 2 passes) when the
+// worker ended empty / on tool-junk / with GoLangGraph's synthetic blocked JSON.
+// If recovery still fails but disk/tool evidence shows writes, synthesize a
+// provisional done JSON so review/smoke can decide on real evidence.
+func (r *Runner) recoverIncompleteFinalize(ctx context.Context, t *plan.Task, baseline map[string]string) {
+	if r == nil || t == nil {
+		return
+	}
+	const maxPasses = 2
+	for pass := 0; pass < maxPasses; pass++ {
+		reason, nudgeIssue, ok := r.incompleteFinalizeNudge(*t)
+		if !ok {
+			return
+		}
+		r.Log("%s incomplete finalize (%s); finish-steer pass %d/%d", t.ID, reason, pass+1, maxPasses)
+		r.fireIntervention(t.ID, reason, quality.PhraseForUser(reason), nudgeIssue)
+		r.fire("agent_start", r.correctorID(), t.ID, "fix incomplete finalize", strings.Join(t.Files, ", "), "")
+		corrIn := formatCorrectPrompt(*t, plan.ReviewResult{
+			Approved: false,
+			Issues:   []string{nudgeIssue},
+			Summary:  "incomplete finalize",
+		})
+		corr, _ := r.Executor.ExecuteSubAgents(ctx, []ggagent.SubAgentRequest{{
+			AgentID: r.correctorID(),
+			Input:   corrIn,
+			Timeout: r.Timeout, ShareState: true,
+		}}, r.Shared)
+		if len(corr) > 0 {
+			r.noteUsage(corr[0], corrIn, outputString(corr[0]))
+			if out := outputString(corr[0]); strings.TrimSpace(out) != "" {
+				t.Output = out
+			}
+		}
+		r.fire("agent_end", r.correctorID(), t.ID, "corrector finished", "", truncate(t.Output, 800))
+	}
+	reason, _, stillBad := r.incompleteFinalizeNudge(*t)
+	if !stillBad {
+		return
+	}
+	hasWrite := r.hasRealWriteEvidence(*t, baseline) || hasToolWriteEvidence(t.Output) || hasDiskEvidenceSection(t.Output)
+	if !hasWrite {
+		r.Log("%s incomplete finalize persists after recovery (%s)", t.ID, reason)
+		return
+	}
+	files := append([]string{}, t.Files...)
+	files = append(files, parseFilesChanged(t.Output)...)
+	provisional := quality.ProvisionalDoneFromEvidence(uniqStrings(files), reason)
+	// Keep prior observations for smoke/static appendices that may already be present.
+	if rest := strings.TrimSpace(t.Output); rest != "" && !strings.HasPrefix(rest, "{") {
+		t.Output = provisional + "\n\n" + rest
+	} else {
+		t.Output = provisional
+	}
+	r.Log("%s provisional done from write evidence after incomplete finalize (%s)", t.ID, reason)
+	r.fireIntervention(t.ID, "provisional_finalize", "recovered finalize from disk/tool evidence", reason)
+}
+
+// incompleteFinalizeNudge returns whether the task output needs a finish-steer
+// pass, plus the reason and corrective issue text.
+func (r *Runner) incompleteFinalizeNudge(t plan.Task) (reason, nudgeIssue string, need bool) {
+	core := stripPostSections(t.Output)
+	if reason = quality.IncompleteFinalizeReason(core); reason != "" {
+		hasWrite := hasToolWriteEvidence(t.Output) || hasDiskEvidenceSection(t.Output)
+		return reason, quality.FinishSteerMessage(reason, hasWrite), true
+	}
+	if looksLikeToolJunk(core) {
+		return "ended_on_tool_call", quality.FinishSteerMessage("ended_on_tool_call", false), true
+	}
+	if r.QualityMonitor {
+		assess := quality.AssessResponse(core, nil, nil, nil)
+		if !assess.OK {
+			nudgeIssue = quality.CorrectionMessage(assess.Reason)
+			if strings.HasPrefix(assess.Reason, "text_tool_calls:") {
+				if calls := quality.ParseTextToolCalls(core); len(calls) > 0 {
+					nudgeIssue = quality.TextToolNudge(calls)
+				}
+			}
+			return assess.Reason, nudgeIssue, true
+		}
+	}
+	if calls := quality.ParseTextToolCalls(core); len(calls) > 0 {
+		nudgeIssue = quality.TextToolNudge(calls)
+		if r.AutoTextTools {
+			nudgeIssue = "AUTO_TEXT_TOOLS: re-issue these as NATIVE tool calls immediately, then status JSON.\n" + nudgeIssue
+		}
+		return "text_tool_calls", nudgeIssue, true
+	}
+	if r.ThinkingBudget && quality.ThinkingBudgetExceeded(core, r.ThinkingBudgetTokens) {
+		return "thinking_budget_exceeded", quality.ThinkingBudgetBreachMessage(), true
+	}
+	return "", "", false
+}
+
+func uniqStrings(in []string) []string {
+	seen := map[string]bool{}
+	var out []string
+	for _, s := range in {
+		s = strings.TrimSpace(s)
+		if s == "" || seen[s] {
+			continue
+		}
+		seen[s] = true
+		out = append(out, s)
+	}
+	return out
 }
 
 // stripPostSections removes harness-appended evidence/gate sections so JSON