finish-flow

finish-flow — Closing Sequence Forcing Function

Purpose: Dev-flow's closing sequences (L-5, H step 9, Fix wrap-up, S session-end) are multi-step and easy to compress mentally into "one thing to do". This skill guarantees each step becomes an independent, verifiable TaskCreate item that system-reminder surfaces until it's individually completed.

Why this exists: On 2026-03-17 and 2026-04-11, the same L-5 completion sequence was silently skipped twice — despite the dev-flow SKILL.md being patched with bolder markdown and anti-patterns. Passive text cannot force behavior. Active TaskCreate reminders can.

Project Config (auto-injected)

!cat .claude/finish-flow-config.md 2>/dev/null || true !cat .claude/dispatch-config.md 2>/dev/null || true

Entry Protocol (MANDATORY)

Before doing anything else:

1. Identify the current workflow size from the active project / branch:
   - Look at TaskList for phase task prefix (P0/P1/... ⇒ L-size)
   - Check branch name: fix/* ⇒ Fix, hotfix/* ⇒ H, otherwise infer
   - If unclear, ASK the user (or CEO evaluates within DOA)

2. Look up the size in the size → sub-tasks table below.

3. TaskCreate every sub-task listed for that size, in order.
   - Each sub-task must have the listed subject AND description
     (not abbreviated — copy the verification output clause verbatim).

4. Mark the parent closing task (L-5 / H-9 / etc.) as in_progress.

5. Begin working through the sub-tasks in order, marking each completed
   as its verification output is produced.

Do not combine. Each sub-task must be its own TaskCreate call and its own TaskUpdate status=completed call. Combining steps into one tool call defeats the forcing function.

Size → Sub-tasks

L-size — L-5 Completion (7 sub-tasks)

#	Subject	Description + verification output
L-5.1	Final Goal Review	Open the project README. For each success criterion, show (a) the criterion text and (b) the concrete evidence (command output, file contents, or diff) proving it's met. Verify EACH row of the dev-flow requirements ledger is DONE or explicitly deferred (named to the user in the report) — a silently dropped accepted requirement is a FAIL. Output: pass/fail list, zero unverified.
L-5.2	Pre-Merge Review (max 3 rounds)	Invoke autopilot:quality-pipeline (project config will select per-size flags). Up to 3 fix-review rounds allowed. This is the homogeneous quality-pipeline repair loop; in /l5 / /l6 contexts the engine implement-review loop is governed separately by resolver loop_max_rounds. (If the gate's tests are CI-backed and you're on Claude Code, the test step may wait on CI via the Monitor tool instead of busy-polling — see quality-pipeline Tests step / portability §7. Degrades to manual gh run watch elsewhere.) Output: final review result = zero blocking issues.
L-5.3	Merge to develop (or main per project convention)	For L5/L6, resolve autopilot_root with the package-root resolver below, set task_status_receipt to a new caller-owned path, then run node "$autopilot_root/bin/autopilot.js" status task --root-run-id "$root_run_id" --json >"$task_status_receipt" and assert the parsed JSON has can_merge === true (for example, node -e 'const v=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));if(v.can_merge!==true)process.exit(1)' "$task_status_receipt"). Only after that assertion passes run git checkout develop && git merge --no-ff <feature-branch>. The merge commit message MUST carry the qc-evidence trailer QC-Verdict: PASS (reviewer <id>, <YYYY-MM-DD>) once L-5.2 passed — the .githooks/pre-push qc-gate (scripts/resolve-qc-gate.sh, strength per .claude/qc-gate-config.md) refuses to push a protected-path range without it. Same trailer requirement applies to F.4 and H-9.3. Verify merge commit landed. Output: the pre-merge receipt with can_merge=true, plus git log -1 --format="%H %s%n%(trailers:key=QC-Verdict)" showing merge commit + trailer.
L-5.4	Post-Merge Review	Re-read critical files that were changed (pick 1–3 highest-risk) to verify merge didn't silently drop changes. Doc-sync (conditional): if the change touched user-facing behavior or 3+ modules, invoke autopilot:doc-sync in scoped mode (base = the merge-base) to confirm docs still match the merged code; OFFER full mode for large/user-facing ships. Triage confirmed findings per doc-sync's fix policy (user docs → reality; specs → STALE-fix or mark NOT-YET-IMPLEMENTED + BACKLOG). Output: grep/diff confirming each expected change is present on develop + doc-sync drift summary (or "doc-sync skipped: no user-facing/3+ module change").
L-5.5	Archive project	Move docs/projects/<project>/ → docs/projects/_archive/<project>/ (or the project-configured projects path). Update docs/projects/INDEX.md (remove from 進行中, add to 已完成 with date). If .claude/mission-routing-config.json points inside the moved directory, update graph_path to the archived path in the same change and require mission-routing-admission.test.sh plus session-mode.test.sh to pass after the move. Stale-qualifier guard: grep -E '^|' docs/projects/INDEX.md | grep -Ei '\((pending|target|in progress|WIP|TBD|draft)\)' MUST be empty (scan table rows only — the ^| prefilter excludes section headers like ## 進行中 (In Progress) which would otherwise false-positive under -i; -i then catches lowercase (wip) in a row); on hit, emit matched lines + halt. Release-hygiene gate (if this ship bumped the version): run scripts/preflight-release.sh — verifies CHANGELOG entry + INDEX row + version mirrors are consistent with canonical .claude-plugin/plugin.json; must exit 0. Output: ls docs/projects/_archive/<project>/ + grep guard pass-confirmation + preflight-release pass line.
L-5.6	L Session End (full checklist)	Run the dev-flow "Session End L-Full" checklist (verify completion, update project docs, knowledge extraction via autopilot:learn if warranted, episodic-distill evaluation (did this project produce a transferable methodology or a rework-tempered procedure? yes → suggest autopilot:distill episodic mode — learn records lesson-FACTS, distill produces executable PROCEDURES), deferred items to BACKLOG, triggered BACKLOG pickup, staging verify, escalation events exist for every triggered quality-floor emission point (or none fired), four-surface sweep (skill/doc/memory/knowledge) — for EACH of the four surfaces output either "updated: " or "not needed: "; the user must never have to ask 該補的都處理了嗎). Dispatch-branch gate: derive integration_target from project config; otherwise resolve the origin/HEAD symbolic ref and normalize only refs/remotes/origin/<name> or origin/<name> to the local <name>; if origin/HEAD is unavailable, use the unique local develop/main. In every case require refs/heads/<name> to exist (ambiguity, malformed remote target, or missing local ref ⇒ halt). Assign autopilot_root from the package-root resolver below and halt on nonzero. When CLAUDE_PLUGIN_ROOT or PLUGIN_ROOT is set, call autopilot_root="$(resolve_finish_flow_package_root)"; otherwise set active_finish_flow_skill to the one exact absolute active finish-flow/SKILL.md path shown by the harness catalog and call autopilot_root="$(resolve_finish_flow_package_root "$active_finish_flow_skill")". Never substitute the consumer git root or a newest-cache search. Then run bash "$autopilot_root/scripts/reap-dispatch-branches.sh" check --repo "$(git rev-parse --show-toplevel)" --into "$integration_target". Exit 1 blocks clean exit until every ahead candidate is integrated or preserved with exact-tip --ack + handoff rationale. Deliberate discard is manual human/depth-0 action only after verified preservation; the reaper never deletes an uncontained branch. Re-run until exit 0. LSM status gates (L5/L6 only): after merge and again immediately before marker clear, run node "$autopilot_root/bin/autopilot.js" status task --root-run-id "$root_run_id" --json >"$task_status_receipt"; preserve the final JSON receipt. Report product_merged, consumer_updated, pushed, and zero_residue independently. Never say “merged and clean” unless can_close=true. Session-mode marker: L5/L6 must run node "$autopilot_root/scripts/session-mode.js" clear --task-status-receipt "$task_status_receipt" --root-run-id "$root_run_id"; the command fails closed unless the fresh digest-valid receipt has the same root and can_close=true. L4 keeps node "$autopilot_root/scripts/session-mode.js" clear. S/Fix/H workflows retain their existing closing behavior. Output: pass/fail summary for each gate and four-surface per-surface lines.
L-5.7	Delete merged branch (local + remote)	The ship is merged + archived — delete the feature branch so it doesn't accumulate. This step exists because L-5 historically had no branch-cleanup sub-task (unlike F.5/H-9.5), so every L-ship left its feat/* branch behind (local AND on origin). Verify it's merged first (git branch --merged develop lists it), then: git branch -d <feature-branch> (local) and git push origin --delete <feature-branch> if it was ever pushed. Skip remote delete only if the branch was never pushed. (Placed AFTER L-5.6 — unlike H's H-9.5-before-H-9.6 order — intentionally: L-5.6 Session End's first check verifies merged-status, so deleting last consumes that verification. Don't "fix" the asymmetry.) Output: git branch + git ls-remote --heads origin <branch> both confirming the branch is gone.