fix(flow): prevent premature task completion before review

[luoyanglang]

Summary

Issue: #191 - 六部派发闭环不稳定：任务常卡在中书省/尚书省
Type: Bug Fix
Severity: High

This PR closes one confirmed root cause behind Issue #191: tasks could be marked complete even when their todos were still unfinished. It aligns execution completion with the existing review flow, adds completion gates in the dashboard approval path, and adds regression coverage for both paths.

---

Root Cause

Two code paths could bypass the intended completion gate and write Done too early:

• scripts/kanban_update.py:439
  • cmd_done() wrote state = 'Done' directly from execution states without validating whether todos were fully completed.
• dashboard/server.py:697
  • handle_review_action(..., 'approve') allowed Review -> Done without checking todo completion, so the dashboard could also close tasks prematurely.
• scripts/file_lock.py:106
  • On Windows, atomic_json_update() wrote temp files without explicit UTF-8 encoding, which could raise UnicodeEncodeError during local reproduction when flow remarks contained emoji/Chinese text.

That left three inconsistent completion semantics in the codebase:

# Before
cmd_state('Review', 'Done') -> guarded by PendingConfirm
cmd_done(...) -> direct Done
handle_review_action(..., 'approve') -> direct Done

# After
cmd_state('Review', 'Done') -> existing guarded path unchanged
cmd_done(...) -> validate todos, then route back to Review
handle_review_action(..., 'approve') -> validate todos before Done

---

Fix Description

Changed files:

• scripts/kanban_update.py:234 - add _todo_counts() and reuse it in cmd_done()
• scripts/kanban_update.py:439 - change cmd_done() from direct completion to Review handoff with todo gate and rejection audit
• dashboard/server.py:690 - add _todo_progress() and block Review -> Done when todos are incomplete
• scripts/file_lock.py:106 - force UTF-8 temp writes in atomic JSON updates on Windows
• tests/test_kanban.py - update expectations for cmd_done() and add incomplete-todo regression coverage
• tests/test_dashboard_review_action.py - add dashboard approval regression tests

Why this approach:

• It reuses the existing Review state instead of introducing a new completion path.
• It keeps the final Done transition in the review layer, which matches the current workflow semantics better than letting execution agents close tasks outright.
• It fixes a Windows-only write-path issue that was interfering with reliable reproduction and regression testing.

Known limitation:

• This PR closes the confirmed premature-completion bug, but Issue [跟踪] 六部派发闭环不稳定：任务常卡在中书省/尚书省 #191 may still include separate runtime dispatch/retry instability that needs further investigation in a full OpenClaw environment.

---

Test Results

Test	Description	Status
pytest tests/test_kanban.py tests/test_dashboard_review_action.py	Covers cmd_done() handoff behavior and dashboard review completion gates	PASS
python -m py_compile scripts/file_lock.py scripts/kanban_update.py dashboard/server.py tests/test_kanban.py tests/test_dashboard_review_action.py	Syntax check for touched runtime and test files	PASS

Manual reproduction before fix:

1. Create a Doing task with todos at 2/5 complete.
2. Run cmd_done().
3. The task was written to Done directly.

Result after fix:

1. The same task is rejected from early completion and stays out of Done.
2. A task with all todos completed is routed back to Review for final approval.
3. Dashboard approve in Review now rejects incomplete todos instead of closing the task.

---

Disprove Analysis

Is this already fixed elsewhere?

• I checked Issue [跟踪] 六部派发闭环不稳定：任务常卡在中书省/尚书省 #191 on 2026-04-12; it is still open.
• I also checked for upstream PRs referencing 191 and did not find an in-flight fix covering this path.
• b7ad34a and 4e51e34 improved dispatch/retry behavior, but they did not close this completion-gate gap.

Default flow regression risk

• Tasks with fully completed todos can still progress to final completion.
• cmd_done() now returns work to Review, which preserves the existing review step instead of bypassing it.
• cmd_state('Review', 'Done') behavior is unchanged.

Edge cases considered

• No todos present: cmd_done() still allows handoff to Review.
• Incomplete todos in Review: dashboard approval now rejects completion with an explicit error.
• Windows local runs: UTF-8 temp writes prevent encoding-related false negatives during JSON updates.

Known limitation

• This PR does not claim to solve every symptom in [跟踪] 六部派发闭环不稳定：任务常卡在中书省/尚书省 #191. It specifically fixes the confirmed premature-completion paths and their regression coverage.

---

Checklist

• Code follows existing project style and keeps user-facing errors in Chinese where applicable
• Related issue number is referenced in this PR (#191)
• Tests were added/updated for the fixed paths
• No hardcoded secrets, paths, or debug-only output introduced

Found during issue triage and local reproduction. Happy to adjust if you prefer a different completion gate shape.

[luoyanglang]

Heads-up: the current red check on this PR is from the repository's Auto Label PRs / label workflow, not from the code change here. It fails on fork PRs with Resource not accessible by integration because actions/labeler cannot add labels with the fork-scoped GITHUB_TOKEN under pull_request.

I opened a small follow-up fix at #281 using the conservative approach: skip the label job for fork PRs while keeping size-label unchanged. If you prefer a different workflow shape, I'm happy to adjust there instead.