dart-resume

Resume unfinished work to its real completion contract: $ARGUMENTS

Required Reading

@AGENTS.md @docs/dev_tasks/README.md @docs/ai/sessions.md @docs/ai/verification.md @docs/onboarding/ci-cd.md @docs/onboarding/contributing.md @docs/onboarding/changelog.md

Argument Handling

$ARGUMENTS may name a branch, PR, issue, or docs/dev_tasks/<task> path; scope-limiting modes are honored when given: status (report only), audit-only (no edits), plan-only (plan, no execution), slice / next-slice (one bounded increment). With no argument, infer the target from the current branch and dev-task state during recon.

Workflow

Step 1: Recon (no changes)

git rev-parse --show-toplevel
git status -sb && git branch -vv && git log -10 --oneline --decorate
git diff --stat && git stash list
gh pr list --head "$(git branch --show-current)"
gh pr status

Step 2: Reconstruct

Infer the task from branch name, commits, diffs, issue/PR description, and any docs/dev_tasks/<task>/ state. If the goal is still unclear after recon, stop and ask.

For a named docs/dev_tasks/<task>/, reconstruct the task's actual completion contract before editing. Treat the dev-task folder as an execution plan and evidence ledger first, not as cleanup inventory:

• read the task README, RESUME, dashboard, packet files, and verification notes;
• extract every acceptance criterion, open decision, required benchmark, required test, and explicit "do not complete until" condition;
• compare those criteria against current branch code, docs, tests, PR state, and available evidence; and
• treat task completion as satisfying those criteria with verification, not as merely promoting notes or deleting the temporary folder.

Step 3: Execute to completion

• Continue by executing the reconstructed plan until the task's acceptance criteria and verification methods are satisfied, or until the same real blocker has been proven and recorded. Preserve existing user changes.
• Do not narrow a broad dev-task objective to documentation cleanup, folder retirement, or evidence promotion unless the implementation criteria are already satisfied or the maintainer has explicitly approved deferring the remaining implementation work.
• Treat dev-task retirement as the final bookkeeping step after implementation completion or an explicitly approved deferral. It is never a substitute for running the plan, benchmarks, tests, and review/PR evidence the task requires.
• For active solver/paper implementations, keep the plan or dev-task resume surface explicit about the completed slice, the next missing paper-parity gap, and why focused green tests are not a full paper-completion claim.
• If the task is being completed, run a completion audit before finalizing: identify the exact docs/dev_tasks/<task>/ folder, inspect it for remaining plans/evidence/decisions, promote any durable dashboard, evidence matrix, API inventory, migration map, long-lived decision, or deferred-but-real work into release/onboarding/AI docs, update any durable status surface when the task changes roadmap state, then remove the dev-task folder completely in the completing change.
• If remaining work is real but blocked by a substantial design decision, maintainer direction, external dependency, or scope boundary that should not be resolved in the current session, ask the human before retiring the folder unless prior maintainer direction is already recorded. Record the parked or blocked work in the durable owner doc before deletion.
• Do not call a dev task complete while docs/dev_tasks/<task>/ still exists. If implementation is done but the folder remains, the remaining work is the durable-doc promotion plus folder cleanup.
• Run pixi run lint before committing.
• Run relevant tests; use pixi run test-all before done when feasible, and pixi run -e gazebo test-gz when package or downstream Gazebo/gz-physics compatibility could be affected.
• For model/scene, simulation, dynamics, collision/contact, Filament, or visual behavior, route through dart-verify-sim: establish a text correctness oracle first, then capture assessed claim-tied images/debug layers or record a graphics unavailable/not-applicable reason. A screenshot alone is not proof.
• Before finalizing a resumed task that changes behavior, public API, packaging, CI, docs workflow, AI-infra workflow, or user-visible docs, run the dart-changelog decision (decide/finalize) per docs/onboarding/changelog.md.
• Push with the same local and remote topic-branch name only after explicit maintainer/user approval: branch=$(git branch --show-current); git push -u origin "HEAD:${branch}".
• For already-published PRs, prefer additive follow-up commits. Amend or force-push only after explicit maintainer/user approval and only when the user explicitly requests it or when there is a clear reason such as removing sensitive content or repairing broken branch history.
• Before every approved push to a published PR branch, first fetch and merge the latest target base branch into it (on every push, not just the first), then push normally after explicit maintainer/user approval. Do not rebase published PR branches by default because that invalidates existing CI runs and makes PR review/comment history harder to follow. Rebase or force-push only when the maintainer explicitly requests it.