Bundles three operator-reliability guardrails (Vikunja #28/#29/#30) plus the
in-flight branch WIP they were built on top of (reasoning_content capture,
operator/project profile editor, write-jail workspaceRoot fix) — the tree is
interdependent (SessionOrchestrator references reasoningArtifactId from the WIP)
and does not compile as separable subsets, so it lands as one commit.
Guardrails:
- #28 mid-stage steering: ClientMessage.SteerSession -> GlobalStreamHandler ->
orchestrator.submitSteering, reusing SteeringNoteAddedEvent + existing context
fold (advisory, non-authoritative; invariants #3/#7). Closes the gap where
steering typed off an approval gate was silently dropped.
- #29 shell-in-file guardrail: ShellInFileContentRule (core:toolintent) blocks a
file_write whose content is a bare shell command (e.g. "mkdir -p ..."); FileWriteTool
description now advertises auto-mkdir of parent dirs. Basename-allowlist so the
extensionless case is caught; scripts/Makefiles/multiline exempt.
- #30 pt1 capability-gap detector: deterministic CapabilityGapDetector maps stage
intent -> implied ToolCapability, compares to granted tools, emits advisory
CapabilityGapDetectedEvent in FreestyleDriver.lockAndRun. Recorded, never fails
the gate and never auto-grants (invariants #3/#4/#5). Reflection rung is pt2.
Verified: ./gradlew check green (whole tree).
Found while live-QAing freestyle_planning on a 12B local model:
- list_dir tool: recursive, .gitignore-aware listing so weak models stop
flooding context with `ls -R` over node_modules/build/dist. Wired into
the fileRead toggle + advertised to the planner (architect_freestyle).
- ContextClassifier: assistantToolCall turns are STRUCTURED, so the token
pruner never shreds the model's own tool-call history — that was causing
amnesia loops (re-issuing calls it had already made).
- Retire instruction-doc LLMLingua pruning (DOC_SOURCE_TYPES emptied): it
fused load-bearing procedural text into unparseable soup. The static
block stays small by dropping CLAUDE.md at the loader instead.
- AgentInstructionsLoader: load only AGENTS.md, not CLAUDE.md — the latter
targets the outer assistant and polluted the agent's stage context.
- DefaultSessionReducer: WorkflowFailed flips session status to FAILED (was
stuck ACTIVE forever, so clients/approval loops never saw a terminal).
- ShellTool: run shell command lines (cd/&&/pipes) via `sh -c`; unrunnable
program is recoverable instead of an uncaught IOException killing the
stage; malformed argv (non-string/collapsed-array) rejected with guidance.
- llmlingua sidecar: cap force_tokens to max_force_token (big docs blew the
assert and 500'd, so doc pruning silently failed open).
Tests added/updated across all of the above.
The freestyle analyst can now break a large goal with dependency seams or
independent review/handoff points into a parent epic + DEPENDS_ON-linked children
in a single T2 approval, instead of N separate task_create calls. Parent
DEPENDS_ON every child (completes last); each child IMPLEMENTS parent. Resolves
depends_on by ref or index; rejects cycles, unresolved refs, missing title/goal,
and empty batches; same batch dedup + force_reason convention as task_create.
A session works one active task, so multi-task work is multi-session by
construction: the analyst names the single ready task this run works, the architect
threads only that one, and siblings are claimed by later runs via task_ready
(claim-driven; no scheduler, /tasks/next stays rejected).
Doctrine: analyst_freestyle.md picks one-task-vs-decompose and names the ready
task; architect_freestyle.md threads only that one; plus the L0 policy line.
freestyle_planning.toml analyst gains task_decompose (pinned by
FreestylePlanningWorkflowTest).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Two coupled gaps from tracing a real run:
1. Freestyle implements in phase 2 via stages compiled from the architect's
execution_plan (ExecutionPlanCompiler sets allowedTools = stage.tools), so the
static allow-lists never reach it and architect_freestyle.md banned every tool
but the file four. Teach the architect to thread an analysis-referenced task
through the plan: implementing stages get task_context/task_update and claim +
submit_for_review; the final/review stage completes it. No task referenced → no
task tools, and the plan never creates one.
2. Give the analyst task_create so the work is framed as a tracked item up front
(role_pipeline + freestyle). "Read-only" for the analyst means it writes no
files; a task is an event-log entry, not a file write — task_create is T2, so
opening one is approval-gated. The analyst names the new id in the analysis so
the implementer claims it and the reviewer completes it; the implementer now
creates only as a fallback.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Extend the role_pipeline wiring to the other workflows that act on a code work
item, matching each stage's tier:
- freestyle_planning: analyst (read-only) gets task_search/task_context to find
related work and ground the analysis; prompt updated to match.
- review_loop: implement gets the full set (claim, submit_for_review, notes),
review gets task_context/task_update to complete on an approved verdict. Its
prompt files don't ship, so the doctrine rides the L0 policy + tool descriptions.
Left untouched: research (external-research flow producing a report, not a code
work item), qa_ping (smoke test), and healthcheck (diagnostic) — none track work.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
kami