flow-workflows 0.85.1 → 0.87.0

package/README.md

@@ -173,6 +173,7 @@ Symmetrically, `guided`/`auto` never ask about the flow's own machinery (panels,
 | `/flow:work:try` | Point the main checkout at a branch to test it, and print the manual test plan once it is up (then `--back`) |
 | `/flow:work:clean` | Sweep merged worktrees, dead branches, unarchived folders. Never deletes on a guess |
 | `/flow:work:abandon` | Close a work item without shipping |
+| `/flow:work:handoff` | Hand a finished study to whoever builds it elsewhere — pushes only its folder to a branch of its own, offers a summary for the ticket |
 | `/flow:news` | What changed in the plugin since the version you last saw |
 
 ## What a work looks like on disk

package/adapters/codex/CORE.md

@@ -17,7 +17,7 @@ Every `$flow-*` command assumes these rules. They are stated once, here, so a co
 carries what is specific to its phase. Read this once per session; a command that says "load
 `flow-core`" means this file.
 
-**This file belongs to flow `0.85.1`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.87.0`.** Compare it once, at the start of the session, against
 `version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
 is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
 — which is exactly what happens when a branch or a release candidate is loaded over an installed
@@ -264,6 +264,11 @@ assumed:
   `glab`, no tracker write in this mode — not before `ship`, not in it. The orchestrator also keeps,
   between runs, the work folder as the run left it and the work branch at the commit where it
   stopped; the run trusts that and does not re-check it.
+- **The work is the one `$flow-work-run` found** — by the ticket's `number`, never by the current
+  branch. A phase whose pre-flight says "load `meta.json` by current branch" takes that work instead:
+  the checkout can be the ticket's `base` (a study restored from elsewhere) or an umbrella branch (a
+  part just merged), and neither names the work. `run` puts a work whose branch is not checked out
+  back on it before handing over (its §2).
 - **Before any closing order, commit** what this run left uncommitted outside `.claude/work/`, new
   files included (`WIP <TICKET>: before <gate|order>` — `auto`'s WIP authority): the orchestrator
   keeps only what is committed. **Only on the work branch**: before it exists (`start` refusing a
@@ -298,6 +303,7 @@ run has.
 | Clarifying questions on the ticket (`start`) | question `clarify` — after the branch and the work folder exist, with the questions also written to `01-context.md` |
 | An unanswered high-severity challenge (`design`, `investigate`) | question `design_challenge` / `investigation_challenge` |
 | `<cmd> ticket` failing or empty, a checkout that is not clean on the ticket's `base` (`start`) | blocked — the orchestrator owns the checkout and the ticket |
+| A work whose branch is not checked out (`run`) | as `$flow-work-run` §2 says — switch onto a branch an unattended run made, or record `unattended:rehomed` and create `<number>-<slug>` from `base`; blocked on a dirty checkout or a branch with the work's name that no run here recorded |
 | Below-XS check (`start`) | record — open the work |
 | "Create the branch?" (`start`), the 2–3 line note an XS `build`/`fix` asks for, a contract the design left in prose (`build`) | record — create it · write the note from the ticket · convert it to literal and say so in the artifact |
 | `git.worktree: ask` | record — in place |

package/adapters/codex/skills/flow-bug-start/SKILL.md

@@ -183,7 +183,7 @@ Create the work directory per §0: `.claude/work/<TICKET>-<slug>/` in ticket mod
 
 **Live panel**: publish it now (flow-core §4 — the panel tools, or `<work-dir>/panel.json`). A bug has no MR/PR train, so it is short: the title (the symptom, `style: title`), a `Now` line for what is starting, a `Next` line for the phase this size routes to, and any sibling repo from §1.6 as a `block` line. Every later phase updates it.
 
-In `unattended`, add `"base"`: the ticket's `base`, the branch the fix starts from and targets. Omit it in every other mode.
+In `unattended`, add `"base"`: the ticket's `base`, or `git.default_base` when it is empty — never empty; the branch the fix starts from and targets. Omit it in every other mode.
 
 Populate `related_repos` from §1.6 — one `{ "repo": "<name>", "scope": "<one line>", "status": "pending", "contract_handoff": "pending" | "none" }` per *other* repo the fix touches; `[]` for a single-repo fix. `pending` only when the fix **changes a surface that sibling consumes** (a payload key, an error code, a route, an event shape); otherwise `none`.
 

package/adapters/codex/skills/flow-feat-build/SKILL.md

@@ -28,14 +28,14 @@ Implementation phase. Code is written here.
 
 ## 1. Pre-flight
 
-- Load `meta.json` by current branch. Read `meta.json` and `00-summary.md`; open in full only `03-design.md` (§"External contracts", verbatim) and the current MR/PR entry of `04-mr-plan.md`. (flow-core §5)
+- Load `meta.json` by current branch — in `unattended`, the work `$flow-work-run` found (flow-core §2.1). Read `meta.json` and `00-summary.md`; open in full only `03-design.md` (§"External contracts", verbatim) and the current MR/PR entry of `04-mr-plan.md`. (flow-core §5)
 - `size` M/L: require both `03-design.md` **and** `04-mr-plan.md`. Plan missing → send to `$flow-feat-plan`; design missing → send to `$flow-feat-design`.
 - `size` XS/S: may start without a design — ask the user for a 2-3 line note on what will be done and save it as a minimal `03-design.md`. No MR/PR plan (always 1 MR/PR).
 - **If `meta.json.mrs` has more than one entry**: pick the **startable** MR/PR — the `pending` one with the **lowest `n` whose `depends_on` are all `merged`**. Dependencies still `pending`/`in_progress` → not startable, even with a low `n`. (No `wave`/`depends_on` — an older plan — → "first pending by `n`".)
   - **Parallel siblings**: startable `pending` MRs/PRs in the **same `wave`** with no dependency between them can be built in parallel or as a train. `manual`: let the user choose which to take now (default: lowest `n`); `guided`/`auto`: take the lowest `n`, record the choice. Mark the chosen one `in_progress`.
   - All `merged` → warn: feature is done, nothing to build (in `unattended`: `done`, the summary saying so).
   - Some `pending` but **none** startable → start nothing: tell the user which MR/PR must merge to unlock the next wave, and stop. In `unattended`: `blocked`, the reason naming it.
-  - **Train/stacked** (never in `unattended`: there the startable MR/PR gets a **new branch of its own** from `meta.json.base` (empty → `git.default_base`) — the base the orchestrator gave the ticket, an umbrella branch once a split task's first part is merged. That branch may exist only on the remote, or locally without the part that just merged: `git fetch origin <base>` when a remote is configured (best-effort — a fetch the container cannot make is not an error), then start from `origin/<base>` when it resolves, the local `<base>` otherwise. Named `<ticket>-<slug>-<n>` and created as `$flow-feat-start §5.2` (in place) or `§5.4` (worktree) says — `git.worktree: always` → worktree, `off`/empty/`ask` → in place; that base is already decided, so §5.1 asks nothing; `--no-track`, no linked remote branch — and never commits onto a previous MR/PR's branch; flow-core §2.1): this MR/PR needs its own branch stacked on the previous one — do **not** keep committing on the previous MR/PR's branch. `$flow-feat-ship §6.2` creates and links it when it chains here; if you arrived directly and are still on the previous branch, create it now per `$flow-feat-start §5` (explicit base = the previous MR/PR's branch, `--no-track`, worktree per `git.worktree`) and, for `tracker.tool: gh`, the linked-branch step `$flow-feat-start §5.5`. Record `stacked_on` in `meta.json`. The train does **not** wait for the previous MR/PR to merge.
+  - **Train/stacked** (never in `unattended`: there the startable MR/PR gets a **new branch of its own** from `meta.json.base` (empty → `git.default_base`) — the base the orchestrator gave the ticket, an umbrella branch once a split task's first part is merged. That branch may exist only on the remote, or locally without the part that just merged: `git fetch origin <base>` when a remote is configured (best-effort — a fetch the container cannot make is not an error), then start from `origin/<base>` when it resolves, the local `<base>` otherwise. Named `<ticket>-<slug>-<n>`, written to `meta.json.branch` (a relaunch of this part then finds it) and created as `$flow-feat-start §5.2` (in place) or `§5.4` (worktree) says — `git.worktree: always` → worktree, `off`/empty/`ask` → in place; that base is already decided, so §5.1 asks nothing; `--no-track`, no linked remote branch — and never commits onto a previous MR/PR's branch; flow-core §2.1): this MR/PR needs its own branch stacked on the previous one — do **not** keep committing on the previous MR/PR's branch. `$flow-feat-ship §6.2` creates and links it when it chains here; if you arrived directly and are still on the previous branch, create it now per `$flow-feat-start §5` (explicit base = the previous MR/PR's branch, `--no-track`, worktree per `git.worktree`) and, for `tracker.tool: gh`, the linked-branch step `$flow-feat-start §5.5`. Record `stacked_on` in `meta.json`. The train does **not** wait for the previous MR/PR to merge.
 
 ## 2. Business brief (before typing)
 

package/adapters/codex/skills/flow-feat-design/SKILL.md

@@ -38,7 +38,7 @@ after writing each challenge's Response.
 
 ## 1. Pre-flight
 
-- Load `meta.json` by current branch. Missing → ask the user to start with `$flow-feat-start`.
+- Load `meta.json` by current branch — in `unattended`, the work `$flow-work-run` found (flow-core §2.1). Missing → ask the user to start with `$flow-feat-start`.
 - Read `meta.json` and `00-summary.md`; open in full only `01-context.md` (ticket, decisions, contracts received). (flow-core §5)
 - `size` is `XS` → suggest jumping to `$flow-feat-build` and stop unless the user insists.
 

package/adapters/codex/skills/flow-feat-plan/SKILL.md

@@ -28,7 +28,7 @@ Delivery planning phase. **No code is written.** Splits the feature into MRs/PRs
 
 ## 1. Pre-flight
 
-- Load `meta.json` by current branch. Missing → send the user to `$flow-feat-start`.
+- Load `meta.json` by current branch — in `unattended`, the work `$flow-work-run` found (flow-core §2.1). Missing → send the user to `$flow-feat-start`.
 - Require `design` in `phases_done`. Missing → send to `$flow-feat-design` and stop.
 - Read `meta.json` and `00-summary.md`; open in full only `03-design.md`. (flow-core §5)
 - **`size` `XS` or `S`** → warn that this phase does not apply (always 1 MR/PR), add `"plan:skipped"` to `phases_done`, suggest `$flow-feat-build`. Stop.

package/adapters/codex/skills/flow-feat-start/SKILL.md

@@ -255,7 +255,7 @@ Create the work directory per §1: `.claude/work/<TICKET>-<slug>/` (ticket mode)
 ```
 
 - Ticket-less (§2.5) → `draft_from_conversation: true`, `tracker_issue` = created issue id/url (or `null` if local-only). Ticket mode → defaults above.
-- `base` — `unattended` only: the ticket's `base` (the branch every MR/PR of this work starts from and targets; `$flow-work-run` refreshes it on `merged`). Omit it in every other mode.
+- `base` — `unattended` only: the ticket's `base`, or `git.default_base` when it is empty — never empty (the branch every MR/PR of this work starts from and targets; `$flow-work-run` refreshes it on `merged`). Omit it in every other mode.
 - `related_repos` from §3.5 — one `{ "repo": "<name>", "scope": "<one line>", "status": "pending", "contract_handoff": "pending" | "none" }` per *other* repo; `[]` for a single-repo task.
 - **This work *is* an accepted follow-up** (the ticket came from another work's `followups[]`, flow-core §7) → set `origin: { "work": "<originating work dir>", "followup": "F<n>" }`, carry that entry's recorded `why` into `01-context.md` verbatim instead of re-deriving it, and set the originating entry to `in_progress` with `work` naming this folder. Not a follow-up → omit `origin` entirely.
 

package/adapters/codex/skills/flow-work-README/SKILL.md

@@ -249,6 +249,7 @@ Two signals arrive on an open MR/PR, each with its own cross-cutting loop (feat
 - `$flow-work-daily [question]` — the **work assistant** (daily standup), read-only. **Local** (`.claude/work/` + git) + **forge** (open MRs/PRs, reviews awaiting you, red CI, unmergeable, unresolved threads via `git.cli`) + **tracker** (assigned tickets, priority changes via `tracker.tool`); where they cross, concrete commands (`$flow-feat-start`, `$flow-work-green`, `$flow-work-respond`). No argument → *yesterday · today · blockers*; a question → just that. External sources best-effort, never blocking; the only write is a "last seen" marker, like `$flow-news`.
 - `$flow-work-status` — all works in `.claude/work/`, current phase, divergence with git.
 - `$flow-work-run [ticket]` — the **entry an orchestrator launches** for an `unattended` run: asks it `why` (start · answer · merged · review · pipeline), routes to the phase that answers it, and makes no decision of its own. Refuses to run in any other mode.
+- `$flow-work-handoff` — hands a **finished study** to whoever builds it elsewhere (an unattended server, another machine): refuses an unfinished one, pushes only this work's folder as a parentless commit to `git.handoff_branch` without touching the checkout, asks before the push, then offers a marked summary for the ticket body (`tracker.edit_cmd`).
 - `$flow-work-resume` — detects the branch, reads `meta.json`, recaps, suggests the next step. **Re-reads the ticket's comment thread** (§2.5), reports only what is new since `01-context.md`, appends it to the artifact; never amends the design on its own.
 - `$flow-work-try <branch>` / `$flow-work-try --back` — point the main checkout at a branch to test it here, then return; re-syncs per `git.worktree_resync`. Resolves the work behind the branch and, once the environment is up, **prints the manual test plan already written** (the `needs-manual`/`unproven` criteria, or the acceptance criteria when `validate` has not run) and offers to collect Pass/Fail/Blocked into the validation artifact. No work behind the branch → the plain switch, as before.
 - `$flow-work-clean [--dry-run]` — **periodic sweep** of finished work's residue: worktree, local branch, `.claude/work/` folder (intermediate train MR/PRs never set `phase: done`, so the `ship`/`abandon` prompt never fires). Verdict per branch from **the forge** with local fallbacks, including patch-equivalence for **squash merges** (`git branch --merged` misses them); acts only on `merged`/`empty`. `unknown` never a candidate; dirty and unpushed protected; work folders **archived, never deleted**; remote never touched. **`autonomy.mode` does not authorize deletion**: `auto` confirms the list too. `--purge-archive <N>d`: separate opt-in pass over `_archive/`, only folders already committed to git.

package/adapters/codex/skills/flow-work-green/SKILL.md

@@ -70,7 +70,7 @@ resolve this way:
 
 ## 1. Pre-flight — locate the work and the MR/PR
 
-- Identify the current branch and its work folder `.claude/work/<TICKET>/` (via `meta.json`, matching `branch`). Read `meta.json` and `00-summary.md`; open in full only `09-ci.md` (previous rounds) and, when §3/§5.C need the recorded "why", `03-design.md`, `05-implementation.md`/`04-fix.md`. (flow-core §5)
+- Identify the current branch and its work folder `.claude/work/<TICKET>/` (via `meta.json`, matching `branch`) — in `unattended`, the work `$flow-work-run` found (flow-core §2.1). Read `meta.json` and `00-summary.md`; open in full only `09-ci.md` (previous rounds) and, when §3/§5.C need the recorded "why", `03-design.md`, `05-implementation.md`/`04-fix.md`. (flow-core §5)
 - **No** work folder (MR opened outside the flow) → **lightweight mode**: skip `meta.json`/artifact reads, warn once that there is no recorded design rationale, keep going.
 - Resolve the target MR/PR, in this order:
   1. `$ARGUMENTS` if given (IID or URL).

package/adapters/codex/skills/flow-work-handoff/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: flow-work-handoff
+description: "Hand a finished study to whoever builds it elsewhere — push only this work's folder to a branch of its own, then offer a summary for the ticket"
+---
+
+<!-- GENERATED by script/adapter-build.py from plugins/flow/commands/work/handoff.md — do not edit; change the plugin file and run the script. -->
+
+# `$flow-work-handoff`
+
+> **codex adapter — how the Claude Code primitives named below map here.**
+> - `AskUserQuestion` → ask in plain text with numbered options and wait for the reply.
+> - `Agent <role>` / `Agent general-purpose` / subagents → the subagent declared under `[agents.<name>]` in `~/.codex/config.toml`; the name comes from `agents.<role>` in `FLOW.md`, empty → do it in this context.
+> - Parallel fan-out → several subagents in one response, capped at `agents.fanout_max` (empty → 4); `agents.fanout_tool` is Claude Code-only, ignore it.
+> - `ScheduleWakeup` / `Monitor` / `/loop` → not available in-session: run one cycle, persist state in `monitor.md`, let the user schedule `codex exec "<command>"` with cron or Codex automations.
+> - `TaskCreate` → a markdown checklist in the phase artifact.
+> - `Skill commit-commands:commit-push-pr` → `git add` · `git commit` · `git push -u origin HEAD` · the `git.cli` CLI (`gh pr create` / `glab mr create`).
+> - `/model <value>` → the `--model` flag at launch (or `/model` if your Codex version has it).
+> - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared under `[mcp_servers.<name>]` in `config.toml` (see `config.snippet.toml`).
+> - `$ARGUMENTS` → whatever the user typed after the skill name, empty if nothing — Codex substitutes nothing, so read it off their message.
+
+Read `~/.claude/flow/CORE.codex.md` first (shared rules: `FLOW.md` step 0, autonomy, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session.
+
+**Panel words are closed** — `mark`: `done` · `current` · `pending` · `wait` · `block` · `info`; `style`: `normal` · `dim` · `title` · `accent` · `ok` · `warn` · `error`. Anything else is dropped by the reader in silence: the panel still paints, and nobody is told.
+
+For a study made here and built somewhere else — a server running `$flow-work-run` unattended,
+another person, another machine. The builder gets the work folder at the same path and nothing
+else: no conversation, maybe a less capable model. So this command checks the study can stand on
+its own, pushes the folder to a branch that holds only it, and offers to put a summary in the
+ticket for the people who review it.
+
+## 1. Pre-flight
+
+- Effective FLOW configuration per flow-core §0. `autonomy.mode: unattended` → refuse in one line:
+  an unattended run never pushes (flow-core §2.1); handing off is a person's step.
+- Locate the active `meta.json` by current branch; not found → ask the user for the ticket.
+- `git.handoff_branch` empty → refuse, naming the key and an example
+  (`git.handoff_branch: study/{TICKET}`): where the study goes is the receiver's convention, never
+  flow's guess. `{TICKET}` = `meta.json.ticket`.
+- `origin` not configured → refuse; there is nowhere to push.
+
+## 2. Is the study finished?
+
+The builder can ask no one. Refuse — pushing nothing, naming every reason that holds — when:
+
+- **The study's last phase is not in `phases_done`.** A feature: `context` on XS (what `start`
+  records), `design` on S, `plan` on M/L. A bug: `context` on XS, `investigate` otherwise.
+- **`meta.json.pending` is set** — a question is still waiting for its answer.
+- **A clarification is still open** — a question under "Decisions clarified at start" in
+  `01-context.md` recorded without its answer.
+
+Then, **before anything is pushed**: decisions this session settled while talking that no artifact
+records yet → write them where they belong now (`01-context.md` "Decisions clarified at start",
+`03-design.md` "Decisions (ADR-light)", `04-mr-plan.md`), and say which. What was decided only in
+the chat does not travel.
+
+## 3. Build the commit, without touching the checkout
+
+A throwaway index holds only this folder, so the current branch, `HEAD`, the real index (staged
+work included) and the working tree are never read into it nor written to, and a git-ignored
+`.claude/work/` is no obstacle.
+
+**Each block below is one shell call, run as it stands** — a harness need not keep variables from
+one call to the next, so every block sets its own. Replace each `@…@` with its literal value first:
+`@WORK@` the work folder relative to the repository root (`.claude/work/<work-dir>`, no trailing
+slash), `@BRANCH@` the resolved `git.handoff_branch`, `@TICKET@` `meta.json.ticket`, `@COMMIT@` the
+sha the build block printed. A value holding a `'` cannot go inside those quotes: refuse it and
+say which.
+
+First, the branch must not exist on `origin` — a second push would need a force, and this command
+never forces:
+
+```bash handoff-check
+BRANCH='@BRANCH@'
+git ls-remote --exit-code origin "refs/heads/$BRANCH" >/dev/null; echo "rc=$?"
+```
+
+`rc=0` → the branch exists: refuse, and say what the person does next — delete it on the forge
+(only when nothing still reads it), or set another name in `git.handoff_branch`. `rc=2` → absent,
+continue. Anything else → stop and say why (no network, no access). Then build the commit:
+
+```bash handoff-build
+WORK='@WORK@'; TICKET='@TICKET@'
+cd "$(git rev-parse --show-toplevel)" || exit 1
+[ -d "$WORK" ] || { echo "no such folder: $WORK"; exit 1; }
+tmp=$(mktemp -d) || exit 1
+idx="$tmp/index"   # does not exist yet: git starts an empty index there
+GIT_INDEX_FILE="$idx" git add -f -- "$WORK" ":(exclude)$WORK/panel.json" &&
+  files=$(GIT_INDEX_FILE="$idx" git ls-files) &&
+  tree=$(GIT_INDEX_FILE="$idx" git write-tree) &&
+  commit=$(git commit-tree "$tree" -m "study $TICKET")
+rc=$?; rm -rf "$tmp"
+[ "$rc" -eq 0 ] && [ -n "$files" ] || { echo "nothing was built (rc=$rc)"; exit 1; }
+printf '%s\n' "$files"; echo "commit=$commit"
+```
+
+`GIT_INDEX_FILE` is set per command, never exported, so a failure leaves no session pointing git
+at a deleted index. `panel.json` stays out: it is this machine's terminal panel, and on another one
+it would show this session's last state as if it were theirs. The block failing → its message, and
+stop: `commit-tree` with no git identity configured is the usual cause.
+
+## 4. Confirm, then push
+
+Show the branch, the remote and the file list the build printed — every path, one per line — then
+ask with `AskUserQuestion` **in every `autonomy.mode`**: a push leaves the machine (flow-core §2).
+**Push** · **Cancel**. Nothing between the list and the question (flow-core §3).
+
+```bash handoff-push
+BRANCH='@BRANCH@'; COMMIT='@COMMIT@'
+case "$COMMIT" in ''|*[!0-9a-f]*) echo "not a commit sha: $COMMIT"; exit 1 ;; esac
+git cat-file -e "$COMMIT^{commit}" || exit 1
+git push origin "$COMMIT:refs/heads/$BRANCH"
+```
+
+The sha is checked first because `git push origin :refs/heads/<branch>` — an empty source —
+deletes the branch on the remote. A rejected push → its message, verbatim, and stop. Never retried
+with `--force`.
+
+## 5. The ticket summary (offer)
+
+Only after a successful push, and only in ticket mode with a real tracker id. The people reviewing
+the ticket read it there, never in the work folder; the receiver does not parse it.
+
+- **Read the body back** — the summary goes inside the ticket's own text, never over it:
+  `gh` → `gh issue view {TICKET} --json body -q .body` · `glab` → `glab issue view {TICKET} -F json`,
+  its `description`. Any other tracker → the offer is not made: one line saying flow cannot read that
+  body back to keep its text.
+- **The write command** — `tracker.edit_cmd`, `{TICKET}` and `{BODY_FILE}` substituted. Empty →
+  `gh issue edit {TICKET} --body-file {BODY_FILE}` for `gh`,
+  `glab issue update {TICKET} --description-file {BODY_FILE}` for `glab`.
+- **The block**, short, in the language of the ticket. A feature takes it from `01-context.md`,
+  `03-design.md` and `04-mr-plan.md`; a bug from `01-context.md` and `03-investigation.md` — the
+  expected behaviour as its criteria, the root cause and the intended fix as its design, "Areas with
+  similar risk" as its risks. A section whose source does not exist (an XS study, an S feature with
+  no plan) says `none`:
+
+  ```
+  <!-- flow-study -->
+  ## What and why
+  ## Acceptance criteria
+  ## Design in brief
+  ## MR/PR plan
+  ## Risks
+  <!-- end flow-study -->
+  ```
+
+  Criteria keep their literal values. The plan lists each MR/PR with what it covers and what it
+  waits on; a bug's plan is its single fix.
+- **The new body**: the body read above with the block between the two markers replaced — or, with
+  no markers yet, the block appended after a blank line. Written to a `mktemp` file outside the
+  tree — `{BODY_FILE}` — so nothing of it can be committed later.
+- **Show the block and ask** with `AskUserQuestion`, **in every mode**: it writes to a shared
+  tracker. **Write it** · **Skip**. Failure → its message in one line; the push stands.
+
+## 6. Close
+
+Report following flow-core §3: the branch and the commit, the file count, whether the ticket
+summary was written. Refresh the panel: a `Now` line saying the study was handed off, no `Decision`
+line. `meta.json` gains nothing — the branch on `origin` is the record, and the §3 refusal reads it.

package/adapters/codex/skills/flow-work-respond/SKILL.md

@@ -85,7 +85,7 @@ back through it, and the hard gates above resolve this way:
 
 ## 1. Pre-flight — locate the work and the MR/PR
 
-- Identify the current branch and its work folder `.claude/work/<TICKET>/` (the `meta.json` whose `branch` matches). Read `meta.json` and `00-summary.md`; open in full only `08-feedback.md` (spent rounds, below) and, in §3, the rationale artifacts a thread needs (`03-design.md`, `05-implementation.md`/`04-fix.md`). (flow-core §5)
+- Identify the current branch and its work folder `.claude/work/<TICKET>/` (the `meta.json` whose `branch` matches) — in `unattended`, the work `$flow-work-run` found (flow-core §2.1). Read `meta.json` and `00-summary.md`; open in full only `08-feedback.md` (spent rounds, below) and, in §3, the rationale artifacts a thread needs (`03-design.md`, `05-implementation.md`/`04-fix.md`). (flow-core §5)
 - **No** work folder (MR opened outside the flow) → **lightweight mode**: skip `meta.json`/artifact reads, warn once that there is no recorded design rationale to draw on, keep going — triage and reply loop still work.
 - Resolve the target MR/PR, in this order:
   1. `$ARGUMENTS` if given (IID or URL).

package/adapters/codex/skills/flow-work-run/SKILL.md

@@ -50,15 +50,38 @@ of truth, and an argument that disagrees with it is ignored and named in the log
 | `start` | none for this ticket | `$flow-feat-start <number>` — `$flow-bug-start <number>` when `kind` is `bug` |
 | `start` | exists, `pending` set | a stop whose `ask` never landed, or a crash after it: send the same question again — `ask` with `<work>/<pending.question_file>`, `<work>/<pending.options_file>`, `--recommended 1` when that options file is not empty, `--free-text` when `pending.free_text`, `--gate pending.gate` — and end. `pending` stays as it is; nothing is recomputed |
 | `start` | exists, an `mrs[]` entry `published`, or `meta.json.published` true (a work with no `mrs`) | `done` — the summary says it is waiting for that merge; the next launch for it is `merged` |
-| `start` | exists, nothing pending | the phase after `meta.json.phase` on this work's route (`$flow-feat-start` §4 for a feature, `$flow-bug-start`'s routing for a bug, by `size`), or `phase` itself when its own Close never ran. A work folder the orchestrator restored from a study made elsewhere enters here, and is never started a second time |
+| `start` | exists, nothing pending | the work's branch first (below), then the phase after `meta.json.phase` on this work's route (`$flow-feat-start` §4 for a feature, `$flow-bug-start`'s routing for a bug, by `size`), or `phase` itself when its own Close never ran. A work folder the orchestrator restored from a study made elsewhere enters here, and is never started a second time |
 | `answer` | `pending` set | apply `<cmd> answer` as flow-core §2.1 "The answer comes back" says, then `pending.resume` at `pending.resume_at`. The order fails or prints nothing → `blocked` |
 | `answer` | nothing pending | `blocked` — there is no question for that answer to decide |
-| `merged` | exists, something published | the entry of `meta.json.mrs` whose `status` is `published` (the only one: one MR/PR per run) becomes `merged`; set `meta.json.base` to the `base` just read; the next startable MR/PR → `$flow-feat-build`; none left, or a work with no `mrs` and `published` true (one MR/PR, every bug) → `phase = done` and `done`, the summary naming the ticket as complete |
+| `merged` | exists, something published | the entry of `meta.json.mrs` whose `status` is `published` (the only one: one MR/PR per run) becomes `merged`; set `meta.json.base` to the `base` just read (empty → `git.default_base`); the next startable MR/PR → `$flow-feat-build`; none left, or a work with no `mrs` and `published` true (one MR/PR, every bug) → `phase = done` and `done`, the summary naming the ticket as complete |
 | `merged` | none, or nothing published | `blocked` — nothing of this ticket was published from here |
 | `review` | exists | `$flow-work-respond` — the threads come from `<cmd> events --json` |
 | `pipeline` | exists | `$flow-work-green` — the failed jobs come from `<cmd> events --json` |
 | `review` · `pipeline` | none | `blocked` — there is no work of this ticket to answer for |
 
+**The work's branch, on `start`.** The current branch is `meta.json.branch` → nothing to do. It is
+not — a study made on another machine arrives on the ticket's `base`, a run that died before its
+closing order is relaunched there — then, in this order:
+
+1. Anything `git status --porcelain` lists outside `.claude/work/` — untracked files included, since
+   the WIP commit before a closing order takes new files too → `blocked`: the orchestrator owns the
+   checkout.
+2. `meta.json.base` is set and `meta.json.worktree` is a worktree of this checkout (`git worktree
+   list`) whose branch is `meta.json.branch` → run the phase from there: `git switch` would refuse a
+   branch checked out elsewhere. A path that is not such a worktree falls through to step 3.
+3. `meta.json.base` is set — the work was started or re-homed by an unattended run, so its branch is
+   one this kind of run made — and `meta.json.branch` exists locally → `git switch` onto it, change
+   nothing. It holds the commits a previous run left.
+4. `<number>-<slug>` (`slug` from `meta.json`), or `meta.json.branch` without `meta.json.base`,
+   exists locally → `blocked`, naming it: a branch with the work's name that no run here recorded is
+   history nobody can vouch for.
+5. Otherwise create it as `$flow-feat-start` does in this mode: `git switch --create <name>
+   --no-track <base>` (`base` empty → `git.default_base`), `<name>` being `<number>-<slug>`, or
+   `<number>-<slug>-<n>` when the `in_progress` entry of `meta.json.mrs` has `n` > 1 — the name
+   `$flow-feat-build` gives that part, since the first part's name is already published. Then
+   `meta.json.branch` = it, `meta.json.base` = that base, `worktree` and `stacked_on` = `null` — paths and parents from the
+   other machine mean nothing here — and record `{ "key": "unattended:rehomed", "default": "<old branch> → <name> from <base>", "phase": "run" }`.
+
 The phase you hand the run to is unattended too: it reads §2.1, chains as `auto` and makes the
 run's one closing order. This command makes none of its own except the re-sent `ask`, the `blocked`
 and the `done` of the table above.

package/adapters/gemini/CORE.md

@@ -16,7 +16,7 @@ Every `/flow:*` command assumes these rules. They are stated once, here, so a co
 carries what is specific to its phase. Read this once per session; a command that says "load
 `flow-core`" means this file.
 
-**This file belongs to flow `0.85.1`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.87.0`.** Compare it once, at the start of the session, against
 `version` in `~/.claude/flow/.claude-plugin/plugin.json`. The two differing means the session
 is running a **mixture** — the commands from one copy of the plugin, these shared rules from another
 — which is exactly what happens when a branch or a release candidate is loaded over an installed
@@ -263,6 +263,11 @@ assumed:
   `glab`, no tracker write in this mode — not before `ship`, not in it. The orchestrator also keeps,
   between runs, the work folder as the run left it and the work branch at the commit where it
   stopped; the run trusts that and does not re-check it.
+- **The work is the one `/flow:work:run` found** — by the ticket's `number`, never by the current
+  branch. A phase whose pre-flight says "load `meta.json` by current branch" takes that work instead:
+  the checkout can be the ticket's `base` (a study restored from elsewhere) or an umbrella branch (a
+  part just merged), and neither names the work. `run` puts a work whose branch is not checked out
+  back on it before handing over (its §2).
 - **Before any closing order, commit** what this run left uncommitted outside `.claude/work/`, new
   files included (`WIP <TICKET>: before <gate|order>` — `auto`'s WIP authority): the orchestrator
   keeps only what is committed. **Only on the work branch**: before it exists (`start` refusing a
@@ -297,6 +302,7 @@ run has.
 | Clarifying questions on the ticket (`start`) | question `clarify` — after the branch and the work folder exist, with the questions also written to `01-context.md` |
 | An unanswered high-severity challenge (`design`, `investigate`) | question `design_challenge` / `investigation_challenge` |
 | `<cmd> ticket` failing or empty, a checkout that is not clean on the ticket's `base` (`start`) | blocked — the orchestrator owns the checkout and the ticket |
+| A work whose branch is not checked out (`run`) | as `/flow:work:run` §2 says — switch onto a branch an unattended run made, or record `unattended:rehomed` and create `<number>-<slug>` from `base`; blocked on a dirty checkout or a branch with the work's name that no run here recorded |
 | Below-XS check (`start`) | record — open the work |
 | "Create the branch?" (`start`), the 2–3 line note an XS `build`/`fix` asks for, a contract the design left in prose (`build`) | record — create it · write the note from the ticket · convert it to literal and say so in the artifact |
 | `git.worktree: ask` | record — in place |

package/adapters/gemini/commands/flow/bug/start.toml

@@ -179,7 +179,7 @@ Create the work directory per §0: `.claude/work/<TICKET>-<slug>/` in ticket mod
 
 **Live panel**: publish it now (flow-core §4 — the panel tools, or `<work-dir>/panel.json`). A bug has no MR/PR train, so it is short: the title (the symptom, `style: title`), a `Now` line for what is starting, a `Next` line for the phase this size routes to, and any sibling repo from §1.6 as a `block` line. Every later phase updates it.
 
-In `unattended`, add `"base"`: the ticket's `base`, the branch the fix starts from and targets. Omit it in every other mode.
+In `unattended`, add `"base"`: the ticket's `base`, or `git.default_base` when it is empty — never empty; the branch the fix starts from and targets. Omit it in every other mode.
 
 Populate `related_repos` from §1.6 — one `{ "repo": "<name>", "scope": "<one line>", "status": "pending", "contract_handoff": "pending" | "none" }` per *other* repo the fix touches; `[]` for a single-repo fix. `pending` only when the fix **changes a surface that sibling consumes** (a payload key, an error code, a route, an event shape); otherwise `none`.
 

package/adapters/gemini/commands/flow/feat/build.toml

@@ -24,14 +24,14 @@ Implementation phase. Code is written here.
 
 ## 1. Pre-flight
 
-- Load `meta.json` by current branch. Read `meta.json` and `00-summary.md`; open in full only `03-design.md` (§"External contracts", verbatim) and the current MR/PR entry of `04-mr-plan.md`. (flow-core §5)
+- Load `meta.json` by current branch — in `unattended`, the work `/flow:work:run` found (flow-core §2.1). Read `meta.json` and `00-summary.md`; open in full only `03-design.md` (§"External contracts", verbatim) and the current MR/PR entry of `04-mr-plan.md`. (flow-core §5)
 - `size` M/L: require both `03-design.md` **and** `04-mr-plan.md`. Plan missing → send to `/flow:feat:plan`; design missing → send to `/flow:feat:design`.
 - `size` XS/S: may start without a design — ask the user for a 2-3 line note on what will be done and save it as a minimal `03-design.md`. No MR/PR plan (always 1 MR/PR).
 - **If `meta.json.mrs` has more than one entry**: pick the **startable** MR/PR — the `pending` one with the **lowest `n` whose `depends_on` are all `merged`**. Dependencies still `pending`/`in_progress` → not startable, even with a low `n`. (No `wave`/`depends_on` — an older plan — → "first pending by `n`".)
   - **Parallel siblings**: startable `pending` MRs/PRs in the **same `wave`** with no dependency between them can be built in parallel or as a train. `manual`: let the user choose which to take now (default: lowest `n`); `guided`/`auto`: take the lowest `n`, record the choice. Mark the chosen one `in_progress`.
   - All `merged` → warn: feature is done, nothing to build (in `unattended`: `done`, the summary saying so).
   - Some `pending` but **none** startable → start nothing: tell the user which MR/PR must merge to unlock the next wave, and stop. In `unattended`: `blocked`, the reason naming it.
-  - **Train/stacked** (never in `unattended`: there the startable MR/PR gets a **new branch of its own** from `meta.json.base` (empty → `git.default_base`) — the base the orchestrator gave the ticket, an umbrella branch once a split task's first part is merged. That branch may exist only on the remote, or locally without the part that just merged: `git fetch origin <base>` when a remote is configured (best-effort — a fetch the container cannot make is not an error), then start from `origin/<base>` when it resolves, the local `<base>` otherwise. Named `<ticket>-<slug>-<n>` and created as `/flow:feat:start §5.2` (in place) or `§5.4` (worktree) says — `git.worktree: always` → worktree, `off`/empty/`ask` → in place; that base is already decided, so §5.1 asks nothing; `--no-track`, no linked remote branch — and never commits onto a previous MR/PR's branch; flow-core §2.1): this MR/PR needs its own branch stacked on the previous one — do **not** keep committing on the previous MR/PR's branch. `/flow:feat:ship §6.2` creates and links it when it chains here; if you arrived directly and are still on the previous branch, create it now per `/flow:feat:start §5` (explicit base = the previous MR/PR's branch, `--no-track`, worktree per `git.worktree`) and, for `tracker.tool: gh`, the linked-branch step `/flow:feat:start §5.5`. Record `stacked_on` in `meta.json`. The train does **not** wait for the previous MR/PR to merge.
+  - **Train/stacked** (never in `unattended`: there the startable MR/PR gets a **new branch of its own** from `meta.json.base` (empty → `git.default_base`) — the base the orchestrator gave the ticket, an umbrella branch once a split task's first part is merged. That branch may exist only on the remote, or locally without the part that just merged: `git fetch origin <base>` when a remote is configured (best-effort — a fetch the container cannot make is not an error), then start from `origin/<base>` when it resolves, the local `<base>` otherwise. Named `<ticket>-<slug>-<n>`, written to `meta.json.branch` (a relaunch of this part then finds it) and created as `/flow:feat:start §5.2` (in place) or `§5.4` (worktree) says — `git.worktree: always` → worktree, `off`/empty/`ask` → in place; that base is already decided, so §5.1 asks nothing; `--no-track`, no linked remote branch — and never commits onto a previous MR/PR's branch; flow-core §2.1): this MR/PR needs its own branch stacked on the previous one — do **not** keep committing on the previous MR/PR's branch. `/flow:feat:ship §6.2` creates and links it when it chains here; if you arrived directly and are still on the previous branch, create it now per `/flow:feat:start §5` (explicit base = the previous MR/PR's branch, `--no-track`, worktree per `git.worktree`) and, for `tracker.tool: gh`, the linked-branch step `/flow:feat:start §5.5`. Record `stacked_on` in `meta.json`. The train does **not** wait for the previous MR/PR to merge.
 
 ## 2. Business brief (before typing)
 

package/adapters/gemini/commands/flow/feat/design.toml

@@ -34,7 +34,7 @@ after writing each challenge's Response.
 
 ## 1. Pre-flight
 
-- Load `meta.json` by current branch. Missing → ask the user to start with `/flow:feat:start`.
+- Load `meta.json` by current branch — in `unattended`, the work `/flow:work:run` found (flow-core §2.1). Missing → ask the user to start with `/flow:feat:start`.
 - Read `meta.json` and `00-summary.md`; open in full only `01-context.md` (ticket, decisions, contracts received). (flow-core §5)
 - `size` is `XS` → suggest jumping to `/flow:feat:build` and stop unless the user insists.
 

package/adapters/gemini/commands/flow/feat/plan.toml

@@ -24,7 +24,7 @@ Delivery planning phase. **No code is written.** Splits the feature into MRs/PRs
 
 ## 1. Pre-flight
 
-- Load `meta.json` by current branch. Missing → send the user to `/flow:feat:start`.
+- Load `meta.json` by current branch — in `unattended`, the work `/flow:work:run` found (flow-core §2.1). Missing → send the user to `/flow:feat:start`.
 - Require `design` in `phases_done`. Missing → send to `/flow:feat:design` and stop.
 - Read `meta.json` and `00-summary.md`; open in full only `03-design.md`. (flow-core §5)
 - **`size` `XS` or `S`** → warn that this phase does not apply (always 1 MR/PR), add `"plan:skipped"` to `phases_done`, suggest `/flow:feat:build`. Stop.

package/adapters/gemini/commands/flow/feat/start.toml

@@ -251,7 +251,7 @@ Create the work directory per §1: `.claude/work/<TICKET>-<slug>/` (ticket mode)
 ```
 
 - Ticket-less (§2.5) → `draft_from_conversation: true`, `tracker_issue` = created issue id/url (or `null` if local-only). Ticket mode → defaults above.
-- `base` — `unattended` only: the ticket's `base` (the branch every MR/PR of this work starts from and targets; `/flow:work:run` refreshes it on `merged`). Omit it in every other mode.
+- `base` — `unattended` only: the ticket's `base`, or `git.default_base` when it is empty — never empty (the branch every MR/PR of this work starts from and targets; `/flow:work:run` refreshes it on `merged`). Omit it in every other mode.
 - `related_repos` from §3.5 — one `{ "repo": "<name>", "scope": "<one line>", "status": "pending", "contract_handoff": "pending" | "none" }` per *other* repo; `[]` for a single-repo task.
 - **This work *is* an accepted follow-up** (the ticket came from another work's `followups[]`, flow-core §7) → set `origin: { "work": "<originating work dir>", "followup": "F<n>" }`, carry that entry's recorded `why` into `01-context.md` verbatim instead of re-deriving it, and set the originating entry to `in_progress` with `work` naming this folder. Not a follow-up → omit `origin` entirely.
 

package/adapters/gemini/commands/flow/work/README.toml

@@ -245,6 +245,7 @@ Two signals arrive on an open MR/PR, each with its own cross-cutting loop (feat
 - `/flow:work:daily [question]` — the **work assistant** (daily standup), read-only. **Local** (`.claude/work/` + git) + **forge** (open MRs/PRs, reviews awaiting you, red CI, unmergeable, unresolved threads via `git.cli`) + **tracker** (assigned tickets, priority changes via `tracker.tool`); where they cross, concrete commands (`/flow:feat:start`, `/flow:work:green`, `/flow:work:respond`). No argument → *yesterday · today · blockers*; a question → just that. External sources best-effort, never blocking; the only write is a "last seen" marker, like `/flow:news`.
 - `/flow:work:status` — all works in `.claude/work/`, current phase, divergence with git.
 - `/flow:work:run [ticket]` — the **entry an orchestrator launches** for an `unattended` run: asks it `why` (start · answer · merged · review · pipeline), routes to the phase that answers it, and makes no decision of its own. Refuses to run in any other mode.
+- `/flow:work:handoff` — hands a **finished study** to whoever builds it elsewhere (an unattended server, another machine): refuses an unfinished one, pushes only this work's folder as a parentless commit to `git.handoff_branch` without touching the checkout, asks before the push, then offers a marked summary for the ticket body (`tracker.edit_cmd`).
 - `/flow:work:resume` — detects the branch, reads `meta.json`, recaps, suggests the next step. **Re-reads the ticket's comment thread** (§2.5), reports only what is new since `01-context.md`, appends it to the artifact; never amends the design on its own.
 - `/flow:work:try <branch>` / `/flow:work:try --back` — point the main checkout at a branch to test it here, then return; re-syncs per `git.worktree_resync`. Resolves the work behind the branch and, once the environment is up, **prints the manual test plan already written** (the `needs-manual`/`unproven` criteria, or the acceptance criteria when `validate` has not run) and offers to collect Pass/Fail/Blocked into the validation artifact. No work behind the branch → the plain switch, as before.
 - `/flow:work:clean [--dry-run]` — **periodic sweep** of finished work's residue: worktree, local branch, `.claude/work/` folder (intermediate train MR/PRs never set `phase: done`, so the `ship`/`abandon` prompt never fires). Verdict per branch from **the forge** with local fallbacks, including patch-equivalence for **squash merges** (`git branch --merged` misses them); acts only on `merged`/`empty`. `unknown` never a candidate; dirty and unpushed protected; work folders **archived, never deleted**; remote never touched. **`autonomy.mode` does not authorize deletion**: `auto` confirms the list too. `--purge-archive <N>d`: separate opt-in pass over `_archive/`, only folders already committed to git.

package/adapters/gemini/commands/flow/work/green.toml

@@ -66,7 +66,7 @@ resolve this way:
 
 ## 1. Pre-flight — locate the work and the MR/PR
 
-- Identify the current branch and its work folder `.claude/work/<TICKET>/` (via `meta.json`, matching `branch`). Read `meta.json` and `00-summary.md`; open in full only `09-ci.md` (previous rounds) and, when §3/§5.C need the recorded "why", `03-design.md`, `05-implementation.md`/`04-fix.md`. (flow-core §5)
+- Identify the current branch and its work folder `.claude/work/<TICKET>/` (via `meta.json`, matching `branch`) — in `unattended`, the work `/flow:work:run` found (flow-core §2.1). Read `meta.json` and `00-summary.md`; open in full only `09-ci.md` (previous rounds) and, when §3/§5.C need the recorded "why", `03-design.md`, `05-implementation.md`/`04-fix.md`. (flow-core §5)
 - **No** work folder (MR opened outside the flow) → **lightweight mode**: skip `meta.json`/artifact reads, warn once that there is no recorded design rationale, keep going.
 - Resolve the target MR/PR, in this order:
   1. `{{args}}` if given (IID or URL).