[Feature]: wire caller-approved validation into agent self-reported completion

[NIU-123370]

Preflight

• I searched existing issues, discussions, and contributor tasks for this request.
• This request and its attachments contain no credentials or private/internal material.

Request origin

Observed need in a real workflow

Problem or unmet outcome

LoopX already ships strong, independent validation primitives:

• loopx/capabilities/issue_fix/acceptance_loop.py runs a caller-declared
  validation_command via subprocess and requires a real git diff before
  review_ready.
• loopx/capabilities/issue_fix/repository_commit_evidence.py performs real
  git ancestry/remote checks.
• loopx turn run-once is specified as "validate independently, write back,
  spend once".

Gap: on paths where an agent self-reports completion with free-text evidence,
the claim is recorded without invoking any caller-approved validation. For
example complete_task(todo_id, agent_id, evidence: str) in
loopx/claude_goal_mode/mcp/loopx_mcp.py validates the writeback packet
structure but not the truth of the claim. promotion_gate is freshness-only and
non-blocking; operator_gate is a manual decision recorder.

Failure cost: an agent can record a "done" todo from a free-text claim with no
independent check, unless someone manually runs the issue-fix caller-repo-branch
command.

Use case

A long-running engineering or issue-fix goal. An agent finishes a todo and
self-reports completion. If that work item has declared a caller-approved
validation_command (e.g. pytest tests/test_x.py, ruff check path/), LoopX
runs it before accepting the completion. On pass, the completion commits; on
fail, completion is blocked and the failure is surfaced. This turns "done" from
a self-report into a verified state, so a hallucinated or premature claim cannot
silently advance the goal.

Proposed outcome

When an agent self-reports a todo completion and that work item has declared a
caller-approved validation command, LoopX independently runs that validation
before the completion is allowed to commit. On pass the completion proceeds; on
fail it is blocked and the failure reason is surfaced. The desired behavior is
that a "done" todo reflects a verified outcome, not just a claim — achieved by
reusing LoopX's existing validation machinery rather than adding a new validator.

LoopX area

Control plane (goals, todos, quota, scheduler, registry, runtime)

Alternatives considered

• Status quo: caller-declared validation only runs when someone explicitly
  invokes the issue-fix caller-repo-branch command; self-reported completions go
  unchecked.
• Attach the check to promotion_gate or operator_gate: but promotion_gate is
  freshness-only / non-blocking and operator_gate is a manual recorder, so
  neither is the right place for an automatic gate.
• Force validation on every completion globally: too heavy — many todos have no
  declared validation command to run. Hence the proposal only fires when a
  command is already declared.

Scope and non-goals

In scope:

• On the self-reported completion path, when the work item declares a
  caller-approved validation_command, reuse acceptance_loop to run it and
  block completion on failure.
• One focused pytest including a negative/failure case.

Out of scope:

• No new validator (reuse only).
• No change to the run-once atomic transaction.
• No global forcing of validation on all completions.
• No change to promotion_gate / operator_gate semantics.
• No resident loop, scheduler, or background process.
• No capture of raw/private material (sessions, transcripts, credentials, local
  paths).

Contribution

• I may be able to help design, implement, document, or validate this request.

[huangruiteng]

Thanks for the well-scoped write-up — the gap is real, and the proposal lands in the right place with one adjustment: the natural home is the existing turn-driver validation phase rather than a bespoke check inside complete_task.

Grounding:

• The turn driver already has an independent validation seam: _run_task_validator / _task_validation_receipt in loopx/control_plane/turn_driver/executor.py (schema loopx_turn_task_validation_v0), with typed receipts, exit-code semantics, and the rule that material host results cannot skip independent task validation.
• The settlement algebra (loopx/control_plane/effect_program.py) models validation as the first typed settlement step (SettlementStepKind.VALIDATION) with an idempotency identity, followed by durable writeback and quota spend. This issue is effectively asking for a real caller of that step on the self-reported completion path.

The shape I would suggest:

1. Make validation_command (+ optional validation_label) a first-class optional field on the todo metadata or the completion request, public-safe and credential-free.
2. On todo complete / MCP complete_task, when the field is declared, run it through the existing validation phase (reusing acceptance_loop/issue-fix machinery as one handler) and require a validation_receipt before durable writeback commits. On failure, block completion and surface the typed failure — --evidence stays a claim; the receipt is the truth.
3. When no command is declared, keep the current fast path unchanged (no global forcing).
4. Add the focused negative pytest you proposed, plus a parity fixture for the no-command fast path, and a replay-reuse fixture if we land this on the fenced turn transaction (fix(turn): fence remote execution and terminal writeback #3074) — a journaled validation receipt should be replayable without re-running the command.

On the effect-program connection: this composes directly. The completion becomes a small effect program (validation -> durable writeback -> quota spend) with one effect identity; #3074 fences exactly these phases, so the validation receipt would be journaled and replayed instead of re-executed. No new generic validator or framework is needed — this is a data field plus a caller for an existing step.

I would be glad to review a PR along these lines; the focused scope you outlined (one pytest, reuse-only, no gate-semantics change) is the right size.

[NIU-123370]

Audited the remaining done-writing entry points on current main (5d73c343), following the GH-C85 row ("extend the same contract to other self-report paths such as the MCP complete_task route"). Short version: the named MCP route is already covered; the audit found one real bypass plus one open question.

1. The MCP complete_task route already goes through the gate. loopx/claude_goal_mode/mcp/loopx_mcp.py:143-155 builds ["todo", "complete", ...] and shells out to the loopx CLI → loopx/cli_commands/todo.py:775 (complete_goal_todo) → loopx/todos.py:1627-1636 unconditionally runs run_completion_validation_gate (internal no-ops for undeclared command / dry-run / already-completed). Verified end to end with a declared failing command through python -m loopx.cli ... todo complete: ok: False + typed receipt; the MCP spend-slot guard only credits ok, so blocked completions don't spend quota. The other complete_goal_todo callers are covered by construction — turn validated completion (cli_commands/turn.py:616), Codex/auto-research heartbeat (capabilities/auto_research/worker_runtime.py:432), issue-fix PR gates (capabilities/issue_fix/pr_gate_reconcile.py:141,317, pr_monitor_materialization.py:228), and task-lease completion keys (routed through todo complete --task-lease-idempotency-key). This part of the row may just need a board refresh.

2. Real bypass: user-role todos flip to done via todo update --status done without the gate.

• The update guard only rejects the agent role (loopx/todos.py:1394-1399, "agent todo completion must use complete_goal_todo"); a user-role todo falls through to :1493 and writes status=done directly.
• Meanwhile todo add accepts the validation fields for any role (loopx/todos.py:610-632 has no role restriction there), so a declared validation_command is enforced on the complete path but silently skipped on the update path.
• Reproduced on current main with a spy on run_caller_validation: a user todo declared with a command that always fails (raise SystemExit(1)) → todo update --todo-id X --role user --status done returns ok: True, the todo is done, gate invoked 0 times; the same fixture through complete_goal_todo correctly returns validation_blocked_completion and stays open.

Since the declared-field contract is "declared ⇒ enforced, undeclared ⇒ fast path unchanged" (independent of who declares it), the update path should fail closed too. Proposed smallest slice: in update_goal_todo, after resolve_todo_state_path and before the exclusive lock — mirroring complete_goal_todo's pre-lock pattern (todos.py:1619-1637) — run the gate when the normalized status is done and return the typed blocked payload instead of writing. Two precision points:

• Parse the target block read-only first and skip the gate for agent-role sections, so the existing :1394 ValueError path (message included) stays unchanged.
• The gate's already_completed short-circuit keeps repeated updates from re-running the command.

Tests planned next to the existing tests/control_plane/test_todo_completion_validation.py: (1) user todo + failing declared command → update blocked, state unchanged; (2) user todo without declaration → unchanged fast path; (3) re-update of an already-done todo doesn't re-run the command; (4) agent-role update --status done still raises the existing guard error with zero executions.

3. Open question: todo supersede also writes done with no gate (todos.py:2041-2049). Supersede is "void and replace", not a completion claim, so running the declared command there may be self-contradictory (a todo is superseded precisely because the work changed). But the written status=done is indistinguishable from verified completion downstream (control_plane/todos/completion_validation_projection.py:54 treats done as completed). Should supersede (a) run the gate, (b) write a distinguishable terminal form, or (c) stay exempt? Leaning (c) absent a reason, but flagging it since it's the only other done writer.

Happy to send the #2 PR once you confirm the direction (and whether the board row should be reworded to the update path).