feat: task complete gains --force flag

[bborbe]

Summary

• task complete gains --force, bypassing the incomplete-checkbox guard (mirrors goal complete --force).
• commands/complete-task.md step (c) now actually passes --force to the CLI (it previously documented the flag in argument-hint and the abort-path advice but never wired it through).
• Added a note that --force is for items that were never the task's actual work, not for closing out unfinished work.

Why

commands/complete-task.md has advertised --force since it was written — but only goal complete implemented it. On the task path the advice was a dead end: the run failed with incomplete subtasks: N pending and the only way through was editing the task file to delete checkboxes, which is lossy. First reported 2026-08-11; hit twice again on 2026-08-16.

Test plan

• make precommit passes (8 packages, golangci-lint 0 issues, go vet clean, osv-scanner + trivy 0 vulns, CHANGELOG OK, license headers OK)
• New test: "task with incomplete checkboxes" — unforced blocks (error, no WriteTask, reason incomplete_items), forced completes and marks status

[ben-s-pull-request-reviewer]

This session is the worktree itself (we skipped worktree creation per the ALREADY_AT_HEAD short-circuit). No cleanup needed.

{
  "verdict": "approve",
  "summary": "PR adds --force flag to task complete, correctly wiring the flag through CLI -> ops layer with a bypass of the incomplete-checkbox guard. CHANGELOG uses correct feat: prefix, command docs are properly formatted, mock is correctly regenerated. All 150 mechanical findings are pre-existing patterns in unchanged code; no new violations introduced.",
  "comments": [],
  "concerns_addressed": []
}

superseded by new automated review

[ben-s-pull-request-reviewer]

Now I have all the information I need. Let me compile the findings:

Mechanical funnel findings (150 total) are pre-existing issues in the codebase — the PR adds a small amount of net new code but doesn't introduce new patterns. The core change is straightforward and correct.

Manual review of the PR:

1. pkg/ops/complete.go:100-106 — !force guard correctly wraps the checkSubtaskCompletion call. When force=true, the guard is bypassed; when force=false, it runs as before. ✅
2. pkg/cli/cli.go:151,180 — force is a bool variable captured by reference in the RunE closure and registered via BoolVar before return cmd. The capture is safe — cmd.RunE executes after all flag registration, and the closure reads force at call time, not at closure-creation time. ✅
3. mocks/complete-operation.go — auto-generated mock updated correctly to match new Execute(ctx, string, string, string, bool) signature. ✅
4. pkg/ops/complete_test.go — new tests cover force=false (block) and force=true (bypass) cases with appropriate assertions. ✅

Remaining mechanical findings in changed files are pre-existing in the codebase (not introduced by this PR) or are in test setup where mock setter methods (*Returns()) have no return value and the rule is a false positive for those patterns.

---

{
  "verdict": "approve",
  "summary": "The `--force` flag implementation is correct and well-tested. The guard bypass at `complete.go:100-106` is sound, the CLI closure capture is safe, the mock is properly updated, and the new tests cover both the blocked and bypassed paths. The CHANGELOG entry is well-written with clear motivation. Pre-existing mechanical findings in the diff are outside this PR's scope.",
  "comments": [
    {
      "file": "pkg/ops/complete_test.go",
      "line": 1,
      "severity": "minor",
      "message": "Test file lacks a companion *_suite_test.go with TestSuite + RunSpecs. Ginkgo will still discover specs via the Describe block, but without a suite file the TestSuite entry point is missing — tests will run but the harness lacks the standard setup/teardown hook. Non-blocking for this PR since the file was not introduced by this change."
    }
  ],
  "concerns_addressed": [
    "correctness: subtask completion guard is now conditional on !force — the bypass logic at complete.go:100-106 is correct (force=false → guard runs; force=true → guard skipped). Verified by new tests in complete_test.go.",
    "correctness: force flag boolVar is captured safely — force is declared before cmd construction, registered via Flags().BoolVar before return, and Read at execution time inside RunE. No stale closure capture issue.",
    "correctness: mock updated to match new Execute signature — mocks/complete-operation.go now includes arg5 bool in Execute signature throughout."
  ]
}