Update Progress

---
name: update-progress
description: Verify a session's handoff document and update the repo's docs and kanban board from it. Run in a fresh session after session-handoff.
argument-hint: "handoff doc path (default: newest by mtime in the handoff folder)"
---

Treat every claim in the handoff as unverified until you've checked it.

1. **Locate** the handoff: given path, else the newest by mtime among `*.md` in the handoff folder (AGENTS.md/CLAUDE.md's, else `skilleddocs/handoffs/`) in every `git worktree list` entry (current worktree first; an uncommitted handoff lives in the task's worktree). In the other worktrees count only untracked files (`git -C <wt> ls-files --others -- <folder>`, no `--exclude-standard`: untracked mode excludes the folder); their tracked handoffs are checkout copies of committed ones, stamped with checkout time. Skip one whose issues all carry a "verified, merged" comment (already processed); one closed by a PR's `Closes #n` without it still runs, for the docs. Tied mtimes → list them and ask. None → newest handoff-looking file in the OS temp dir.
2. **Verify**: `git fetch origin` first. `git log` over the handoff's base SHA..head, else `git merge-base <default> <branch>`..branch (`<default>` per the `handoff-auto` skill's `TRACKING.md`). **Merged** = head is an ancestor of `origin/<default>` (`git merge-base --is-ancestor <head> origin/<default>`), or the branch has a merged PR containing head (`gh pr list -R <owner>/<repo> --head <branch> --state merged --json number,headRefOid`; `<owner>/<repo>` per [BOARD.md](../next/BOARD.md)): head == `headRefOid` → merged; else `git fetch origin pull/<number>/head` (the PR branch is often deleted after merge; GitHub keeps the PR ref), then `git merge-base --is-ancestor <head> <headRefOid>`. A fetch or command that errors (missing object, exit other than 0 or 1) is never merged. Squash and rebase merges never make head an ancestor, and a stale local `<default>` misses fresh merges. Decide merged **per issue** for steps 4–5: head merged, or the issue is closed by a merged PR (`gh issue view <n> -R <owner>/<repo> --json state,closedByPullRequestsReferences`, then that PR's `headRefOid`) whose head is in the range (`git merge-base --is-ancestor <headRefOid> <head>`); one issue merging mid-session doesn't wait for the rest. Run the repo's test command on the code the handoff describes: merged → the `<default>` checkout after `git pull --ff-only` (won't fast-forward → a temp `git worktree add --detach <tmp> origin/<default>`); else the worktree with `<branch>` checked out at head, else a temp `git worktree add --detach <tmp> <head>` (install deps there first; remove it after). Record the real result and where it ran.
3. **Review**: product code changed → call the Skill tool with `"code-review"` on the session's commits.
4. **Docs**, only for merged issues and only what the repo already has; a protected `<default>` (step 7) → switch to its docs branch before editing: tick roadmap checkboxes, add status/CHANGELOG entries, add a decisions row if the handoff records a decision.
   - The "current phase" marker follows where merges land. Merges in a later phase → move the marker; mark the earlier phase "done except gated (#…)".
   - Every capability merged this phase appears in the README / status summary. A missing one is drift; fix it here.
5. **Board** ([BOARD.md](../next/BOARD.md); its Target repo section first: `-R` on every `gh` call, on a fork ask before writing): comment a summary on each issue. Per issue: complete, verified and merged → Done, close the issue, comment "verified, merged". Complete and verified, not merged → In Review, comment "verified, awaiting merge" (the PR's `Closes #n` or a later run closes it). Otherwise set the status to where it really stands.
6. **Deviations** in `## Board status` → call the Skill tool with `"consult-plan"`.
7. **Commit** in the `<default>` checkout, on `<default>`, or when it is protected on the docs branch `docs/progress-<issue>[-<issue>…]` (the `handoff-auto` skill's `TRACKING.md`, "Protected `<default>`": test, branch, push gate): the step-4 doc edits, plus the handoff if it is uncommitted and that `TRACKING.md` says commit mode (untracked mode → leave it). A handoff in another worktree: move it into the `<default>` checkout's handoff folder first (left there, it blocks that branch's next merge).
8. Finish with the `next` skill.