flow-workflows 0.92.0 → 0.93.0

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.92.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.93.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
@@ -253,7 +253,7 @@ assumed:
 <cmd> ask --question-file F --options-file F [--recommended N] [--free-text] [--gate NAME]
 <cmd> publish --title-file F --body-file F [--part N --of M]
 <cmd> blocked --reason-file F
-<cmd> done [--summary-file F]
+<cmd> done [--summary-file F] [--depends-on N]…
 <cmd> reply --thread ID --body-file F
 ```
 
@@ -314,12 +314,18 @@ runs the study phases as any run does, and three rules make it stop where it sho
   study to code crosses that door, an answered question that resumes straight into `build`
   included, so the phases before it carry no clause. The run kind is read there, never stored: the
   approval reuses the same work folder with `why = start`.
-- **At the door**, a study run first writes the statement of the change when the study holds none
+- **At the door**, a study run first checks each `meta.json.ticket_deps` entry: `N` = its `ticket`
+  without a leading `#`, the form `ticket --json` prints `number`, and it must match
+  `[A-Za-z0-9][A-Za-z0-9._-]*` — an `N` that does not (a space, a shell character, a leading `-`)
+  is never put on a command line: `blocked`, naming the entry, before anything below is written.
+  Then it writes the statement of the change when the study holds none
   (the command says which), then `done-summary.md` — the `flow-study` block of `$flow-work-handoff`
   §5, the same sections from the same sources, and, when `01-context.md` lists `## Study revisions`,
   the line `Revised at the reviewer's request: <n> reply(ies)` first under `## What and why`. It
   overwrites `00-summary.md`, sets the panel's `attention` to `done` and closes with
-  `done --summary-file`. Nothing else moves — no `mrs[]` entry, no branch, no brief — so
+  `done --summary-file`, plus one `--depends-on N` per `meta.json.ticket_deps` entry, in its order —
+  so the orchestrator can hold the ticket until those land; what it does with them is its call.
+  Nothing else moves — no `mrs[]` entry, no branch, no brief — so
   `meta.json.phase` stays at the last study phase and approval is an ordinary `start`.
 - **A person's changes rewind the study.** `$flow-work-run` §2 adds the reply to the ticket in
   `01-context.md` and sends the work back to `context`; the study phases then run again whole, the
@@ -332,7 +338,7 @@ person asking for changes, a ticket that already has code — is `$flow-work-run
 | Where | In `unattended` |
 |---|---|
 | Business brief before code (`build`, `fix`) | record — the brief is written to the phase artifact, marked `recorded (unattended)`, and travels in the MR/PR body |
-| The door to code in a study run (`build`, `fix` pre-flight) | done — `done-summary.md`, the study as `$flow-work-handoff` §5 writes it for the ticket |
+| The door to code in a study run (`build`, `fix` pre-flight) | done — `done-summary.md`, the study as `$flow-work-handoff` §5 writes it for the ticket, and one `--depends-on` per `meta.json.ticket_deps` entry |
 | Push and MR/PR creation (`ship`) | `publish` — the run commits on its own branch, writes title and body, and hands them over; the orchestrator pushes and opens the draft |
 | Writing a DB schema change, index or migration — in any phase, a review's own fixes included — or applying one (`validate`) | question `migration`, before the first line of it is written or run — except in `respond` and `green`, where it is blocked: a schema change agreed after the MR/PR exists goes back through `build` |
 | `review` with blockers or high-severity findings | question `high_findings` |
@@ -352,6 +358,7 @@ person asking for changes, a ticket that already has code — is `$flow-work-run
 | The next MR/PR of a train (`ship` close) | record — not started: one MR/PR per unattended run |
 | `build` with no startable MR/PR (its `depends_on` not `merged` in `meta.json`) | blocked — the reason names what must merge; an unattended `build` never stacks a branch on another, and never creates a remote branch |
 | The parent of a stacked MR/PR merged — rebase and force-push | blocked — never force-push unattended |
+| An approved study's branch (`run`, `why = start`, no build or fix begun) | record — fast-forwarded to its base when it holds no commit of its own (`$flow-work-run` §2); the base unreadable or the fast-forward failing → blocked. Not integrating: nothing of the run's is merged |
 | Integrating the base into the MR/PR's branch (`green`) | on `why = conflict`, record — `git merge origin/<base>` as the orchestrator left it, never rebase, each conflict resolved on its merits (`$flow-work-green` §5.C); on any other `why`, blocked — the orchestrator brings the base in |
 | Any offer about the work's own bookkeeping — a tracker issue, the first `KNOWLEDGE.md` or a knowledge save, a FLOW convention, an agent lesson or a saved specialist, the follow-up survey, carrying files over from the main checkout, a contract handoff, archiving the work | record — `Later`; nothing written outside the work folder |
 | A step the command cannot complete (a red suite it cannot fix, a tool missing, auth failing, the same check failing a second time) | blocked |

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

@@ -36,7 +36,15 @@ Read `~/.claude/flow/CORE.codex.md` first (shared rules: `FLOW.md` step 0, model
   would make — from the root cause and the constraints for the fix when the investigation has them,
   the reproduction and the ticket otherwise, `## Study revisions` included — the person approves a
   stated change, never `none`; then the summary, and
-  `<cmd> done --summary-file <work>/done-summary.md`. Nothing else in this command runs.
+  `<cmd> done --summary-file <work>/done-summary.md`, plus `--depends-on N` per
+  `meta.json.ticket_deps` entry, `N` its `ticket` with the leading `#` dropped — a bare `#` starts a
+  shell comment — and checked against `[A-Za-z0-9][A-Za-z0-9._-]*` before anything is written, else
+  `blocked` (flow-core §2.1). Nothing else in this command runs.
+- **`meta.json.ticket_deps` not empty, and not `unattended`** → the study rests on other tickets
+  (`$flow-feat-design` §5.1): name each — `<ticket> — <why>` — in the brief's stop (§2), one line,
+  so whoever builds confirms the piece is on **this work's branch**, not only on its base — the
+  branch was cut when the study began, and a piece that merged since needs the base brought in
+  before writing against it. Nothing is checked; waiting is the builder's call.
 - `size` `XS`: may start without `investigate`, but require a 2-3 line description of the fix — an `## Intended fix` in `03-investigation.md` is that description.
 - **An `## Intended fix` in `03-investigation.md` binds §2's brief at every size**: it is what a person approved at the end of a study (flow-core §2.1).
 - `size` ≥ S: require `investigate` in `phases_done` (on S it will have run its reproduction half only).

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

@@ -174,10 +174,21 @@ If `agents.fanout_tool` is set in `FLOW.md`, run the sweep through that tool; br
 - Do not touch X because…
 - Consider Y because…
 
+## Depends on other tickets
+<§4.1: `- <ticket> — <what it brings that the base branch lacks>`, then "Not dependencies (either order works)", or "none".>
+
 ## Investigation challenges
 <filled in by §5 with the challenger table>
 ```
 
+### 4.1 Tickets this fix depends on
+
+A fix can rest on another ticket the same way a design can — a corrected contract, a migration, a
+decision that lands only when that ticket merges. Detect and record it before the challenger, exactly
+as `$flow-feat-design` §5.1 says: the same rule, the same "Not dependencies (either order works)"
+line, the same `meta.json.ticket_deps` entries, written under `## Depends on other tickets` in
+`03-investigation.md`.
+
 ## 5. Root cause challenge (challenger)
 
 Before closing, launch a `Agent general-purpose` challenger with this task:

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

@@ -33,8 +33,15 @@ Implementation phase. Code is written here.
   and act as flow-core §2.1 "A study run" says. On `study` → this run writes no code: `size` XS and
   no `03-design.md` → first write the 2–3 line note below as that file, from `01-context.md` (its
   `## Study revisions` included) — the person approves a stated change, never `none`; then the
-  summary, and `<cmd> done --summary-file <work>/done-summary.md`. Nothing else in this command
-  runs.
+  summary, and `<cmd> done --summary-file <work>/done-summary.md`, plus `--depends-on N` per
+  `meta.json.ticket_deps` entry, `N` its `ticket` with the leading `#` dropped — a bare `#` starts a
+  shell comment — and checked against `[A-Za-z0-9][A-Za-z0-9._-]*` before anything is written, else
+  `blocked` (flow-core §2.1). Nothing else in this command runs.
+- **`meta.json.ticket_deps` not empty, and not `unattended`** → the study rests on other tickets
+  (`$flow-feat-design` §5.1): name each — `<ticket> — <why>` — in the brief's stop (§2), one line,
+  so whoever builds confirms the piece is on **this work's branch**, not only on its base — the
+  branch was cut when the study began, and a piece that merged since needs the base brought in
+  before writing against it. Nothing is checked; waiting is the builder's call.
 - `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`".)

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

@@ -290,6 +290,9 @@ Consolidate outputs into `.claude/work/<TICKET>/03-design.md`:
 - **Invariant**: <e.g. "after assignTo(user), ticket.assignee == user AND ticket.status != 'unassigned'">
 - **Edge / boundary**: <e.g. "empty input list → returns 0, does not throw">
 
+## Depends on other tickets
+<§5.1: one line per ticket this design cannot be built without — `- <ticket> — <what it brings that the base branch lacks>` — then, under "Not dependencies (either order works)", each premise on another ticket that holds whichever merges first, with one line why. Neither → "none".>
+
 ## Defensive mechanisms and their justification
 <One row per validation, guard, retry, lock, fallback, cache, idempotency, queue, or flag the design introduces. If you cannot name a REAL and PRESENT scenario that justifies it, the piece is unnecessary — remove it from the design.>
 
@@ -318,6 +321,33 @@ Consolidate outputs into `.claude/work/<TICKET>/03-design.md`:
 
 **"Acceptance criteria"**: start from the provisional list in `01-context.md` (pinned from the ticket in `$flow-feat-start`), fold in the clarifications and the internal/external contracts decided here, and promote it to the canonical enumerated list `$flow-feat-validate` gates against — observable, verifiable, proportional to size.
 
+### 5.1 Tickets this design depends on
+
+Fill `## Depends on other tickets` now, before the challenger of §6 reads the design. The study is
+often built by someone who never saw it made — another person, an unattended server — and who
+starts from the base. A design that rests on what another ticket has not delivered yet leaves that
+builder to find the piece missing and either ask or redo it.
+
+- **A dependency** is a piece, contract or decision the chosen design needs, that is **not on the
+  base this work builds from** (`meta.json.base`, empty → `git.default_base`) — checked there, after
+  a best-effort `git fetch origin <base>`, never assumed from a local ref — and that **another
+  ticket** of this tracker brings. Missing from the base with no ticket bringing it → it is scope
+  or an open question, not a dependency. A ticket in another repo is not a `ticket_deps` entry —
+  the orchestrator only resolves this tracker's numbers — so write it in the section as a
+  cross-repo dependency, for a person, and leave it out of the list.
+- **Not a dependency**: a premise that holds whichever ticket merges first. Say so under "Not
+  dependencies (either order works)", so nobody waits for it.
+- **Record each one** in that section and in `meta.json.ticket_deps` —
+  `{ "ticket": "<the reference as a ticket body writes it: #253, MT-123>", "why": "<one line>" }`,
+  never one twice. `ticket_deps` is the record the exits read (`$flow-work-handoff` §5, the door to
+  code of an unattended study run, flow-core §2.1); the section is the study's prose. Each run of
+  this phase writes the list whole from the design it closes; `plan`, which runs after it, appends
+  its own again. A §6 response or a §9 edit that changes what the design needs changes
+  the section and the list together. None → `[]` and "none".
+
+`ticket_deps` is not `mrs[].depends_on`: that one orders this work's own MRs/PRs, this one names
+other tickets. Flow never checks whether a dependency has closed — whoever builds waits for it.
+
 ## 6. Design challenge (challenger)
 
 Before closing, **challenge the design** with an `Agent general-purpose` and this self-contained brief:

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

@@ -126,6 +126,7 @@ Add the `mrs` array with the agreed plan:
 ```
 
 - `n` = execution order (topological): `depends_on` only ever references a **lower** `n`; `wave` groups MRs/PRs that can run in parallel. `$flow-feat-build §1` reads `depends_on` to pick the next **startable** MR/PR and to say which can go in parallel — keep both accurate whenever the plan is edited or renumbered.
+- **Another ticket is not a `depends_on`.** An MR/PR that turns out, while splitting, to need something another ticket brings is a dependency of the study: append it to `meta.json.ticket_deps` as `$flow-feat-design` §5.1 says, name it in that MR/PR's entry of `04-mr-plan.md` beside what it waits on, and leave `03-design.md` as it closed. The design's own entries stand as they are.
 - **`phases_done`** starts `[]` in every seeded entry: it tracks `build`/`review`/`validate` **for that MR/PR specifically**, so the gates in `$flow-feat-review §1`, `$flow-feat-validate §1` and `$flow-feat-ship §1` judge *this* MR/PR — a sibling's review never satisfies a new MR/PR's gate.
 - Estimates are **indicative**, not contractual. `$flow-feat-build` uses them as a thermometer: real work over `lines_est` +50% or `files_est + 2` triggers the "cut or continue" question (see §2.3 in build). **A thermometer is not a target** (flow-core §9): an estimate is never met by deleting comments, tests or blank lines, by compressing readable code, or by cutting where the piece is not coherent — the overrun is recorded instead, and a diff shaped to fit a number is the one case where these estimates lie to the phases downstream.
 

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

@@ -112,6 +112,9 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
       "note": "reason if closed/superseded; empty otherwise"
     }
   ],
+  "ticket_deps": [
+    { "ticket": "#253", "why": "one line, what that ticket brings that the base branch lacks" }
+  ],
   "related_repos": [
     { "repo": "sibling-project", "scope": "what's needed there", "status": "pending" | "in_progress" | "done", "contract_handoff": "none" | "pending" | "published → <location>" }
   ],
@@ -160,6 +163,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
   Two fields for the review because they are two facts. `reviewed_sha` used to be `git rev-parse HEAD` at the end of the phase, which by then held the round's own fixes — so `ship` compared a sha against itself and reported a match over code no reviewer had read. Read by `ship` at pre-flight against `HEAD`: a delta of test files and this work's own folder passes with a note in `06-review.md`; anything else stops and asks in every autonomy mode. Empty is not a mismatch; `fixed_sha` set with `reviewed_sha == HEAD` is one. `review` also reads `reviewed_sha` back as **its own base** on a re-review, so the second round reads the delta instead of the whole branch.
 - **`respond_rounds`**: rounds of `$flow-work-respond` on an MR/PR. `$flow-work-respond §1` reads it against `quality.respond_max_rounds` (empty = 3) and refuses the round that would exceed it, handing the open threads back to the user.
 - **`related_repos`**: the **other repos a task touches**. Captured at `$flow-feat-start` / `$flow-bug-start` §cross-repo, refined at `design`/`plan`, reminded at `ship`, shown by `daily`/`resume`/`status`. flow only notes and reminds — never touches the other repo. `[]` for single-repo.
+- **`ticket_deps`**: the **other tickets this study cannot be built without** — something the design needs that is not on the base branch and that another ticket brings (`$flow-feat-design` §5.1, `$flow-bug-investigate` §4.1). Read at the two exits of a study: `$flow-work-handoff` §5 writes a `Depends on <ticket>` line per entry into the ticket body, and an unattended study run passes `--depends-on N` per entry on its `done` (flow-core §2.1). Not `mrs[].depends_on`, which orders this work's own MRs/PRs. Written whole each time `design` (or `investigate`) runs, and removed when an unattended study is rewound. `[]` or absent when the study depends on nothing.
 - **`contract_handoff`**: whether the sibling knows **what shape to build against** (`scope` is prose; distinct from `status`). `none` — consumes no contract declared here. `pending` — consumes one, not handed over yet. `published → <location>` — published where that side reads it (normally the tracker ticket; `$flow-feat-ship` §6.3), picked up by the sibling's `$flow-feat-start` §3.6.
 - **`followups`**: work a phase deliberately did **not** do here — a neighbouring defect found while building, a piece put out of scope while planning, a risk recorded but not mitigated, an edge case left unchecked, a prevention action from a postmortem. Written by the phase that parks it (asks nothing) when it clears the bar of flow-core §7, triaged **once** at `ship`'s Close behind a skeptic and a ceiling on how many may become questions, published in the MR/PR description while still open, and surfaced by `status`/`daily`/`next` — including from `_archive/` — until `declined` or `done`. Shape and rules: flow-core §7. `[]` when the work deferred nothing.
 - **`defaults_used`**: an empty `FLOW.md` key a phase resolved with its default instead of asking — written in `guided`/`auto`, where asking would breach the never-a-question contract (flow-core §0). Not an error and not deferred work: a record, aggregated by `$flow-doctor` across every work including `_archive/`, so a key that keeps defaulting can be pinned once instead of decided every time. `[]` when nothing defaulted.

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

@@ -148,13 +148,27 @@ the ticket read it there, never in the work folder; the receiver does not parse
   <!-- 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.
+  Criteria keep their literal values. `## Design in brief` ends with each `meta.json.ticket_deps`
+  entry and its why — `Depends on #253: <why>` — so whoever approves the study sees what it waits
+  for; an unattended study's `done-summary.md` is this block, so it carries them too. 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
+  no markers yet, the block appended after a blank line. Then, for each `meta.json.ticket_deps`
+  entry (`$flow-feat-design` §5.1) whose line is not already a line of that body — same text,
+  ignoring case and surrounding whitespace — one line after the end marker, in `ticket_deps` order:
+
+  ```
+  Depends on #253
+  ```
+
+  `#253` being the entry's `ticket` as it stands. Outside the markers so a later rewrite of the
+  block leaves it alone, and never removed: a line a person wrote by hand looks exactly like one
+  flow wrote, and the convention is theirs too. 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.
+- **Show the block, and the `Depends on` lines it adds, and ask** with `AskUserQuestion`, **in
+  every mode**: it writes to a shared tracker. A `Depends on` line already in the body, outside the
+  markers, that no entry names — a dependency a revised study dropped, or one a person added — is named in the same
+  question and left in place: whether it still holds is theirs to say. **Write it** · **Skip**. Failure → its message in one line; the push stands.
 
 ## 6. Close
 

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

@@ -67,7 +67,7 @@ of truth, and an argument that disagrees with it is ignored and named in the log
 | `conflict` | exists | `$flow-work-green` — the MR/PR conflicts with its base; which base, and where it stands, come from `<cmd> events --json` |
 | `review` · `pipeline` · `conflict` | none | `blocked` — there is no work of this ticket to answer for |
 
-**The work's branch, on `start` and `study`.** The current branch is `meta.json.branch` → nothing to do. It is
+**The work's branch, on `start` and `study`.** The current branch is `meta.json.branch` → no switch. 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:
 
@@ -90,6 +90,21 @@ closing order is relaunched there — then, in this order:
    `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" }`.
 
+**On `start`, a study's branch catches up with its base** — once on the work's branch, the "no
+switch" case included, and only while no build or fix has begun (neither `05-implementation.md` nor
+`04-fix.md` exists). Every command below runs in the work's own checkout — step 2's worktree when
+that is where it lives. A study writes no code, so its branch still sits where the base was when the
+study began; an approval that waited for the tickets the study depends on (`meta.json.ticket_deps`)
+would otherwise build on a base that lacks them. `<base>` = `meta.json.base`, empty →
+`git.default_base`: `git fetch origin <base>`, then `<ref>` = `origin/<base>`; the fetch failing
+with a remote configured → `blocked`, since a stale ref would leave the build on the old base
+unnoticed. No remote → the local `<base>`. `git merge-base --is-ancestor HEAD <ref>` and `HEAD` is not
+`<ref>` → the branch holds no commit of its own and the base moved: `git merge --ff-only <ref>`, and
+record `{ "key": "unattended:base-caught-up", "default": "<old short sha> → <new short sha> on
+<base>", "phase": "run" }`. The fast-forward fails → `blocked`, its message as the reason. Not an
+ancestor → it holds commits a previous run made: leave it as it is — bringing the base into work in
+progress is the orchestrator's (flow-core §2.1).
+
 **A person's changes to a study, on `study`** (flow-core §2.1: they rewind it). The work's branch
 first, as above. `<work>/study-revision.md` holds the reply, as the row above wrote it. Each step
 can be run again: a run that dies part-way is finished by the next relaunch, whatever it serves.
@@ -113,7 +128,8 @@ can be run again: a run that dies part-way is finished by the next relaunch, wha
    `study-revision.md` and earlier `before-*/` folders into `<work>/before-<id7>/` — never
    overwriting a name already there — so no artifact, summary or agent answer of the discarded study
    leaks into the next. Then `meta.json`: `phase` = `context`, `phases_done` = `["context"]`, `mrs`
-   removed (the row that blocks a work past the study guarantees nothing was built), `notes`
+   removed (the row that blocks a work past the study guarantees nothing was built), `ticket_deps`
+   removed (the redone study finds its dependencies again), `notes`
    emptied, and every `followups[]` entry a study phase wrote (`source` `design`, `plan` or
    `investigate`) removed.
 5. **Re-size**: estimate the size again with `$flow-feat-start` §4's table (`$flow-bug-start`'s for

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.92.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.93.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
@@ -252,7 +252,7 @@ assumed:
 <cmd> ask --question-file F --options-file F [--recommended N] [--free-text] [--gate NAME]
 <cmd> publish --title-file F --body-file F [--part N --of M]
 <cmd> blocked --reason-file F
-<cmd> done [--summary-file F]
+<cmd> done [--summary-file F] [--depends-on N]…
 <cmd> reply --thread ID --body-file F
 ```
 
@@ -313,12 +313,18 @@ runs the study phases as any run does, and three rules make it stop where it sho
   study to code crosses that door, an answered question that resumes straight into `build`
   included, so the phases before it carry no clause. The run kind is read there, never stored: the
   approval reuses the same work folder with `why = start`.
-- **At the door**, a study run first writes the statement of the change when the study holds none
+- **At the door**, a study run first checks each `meta.json.ticket_deps` entry: `N` = its `ticket`
+  without a leading `#`, the form `ticket --json` prints `number`, and it must match
+  `[A-Za-z0-9][A-Za-z0-9._-]*` — an `N` that does not (a space, a shell character, a leading `-`)
+  is never put on a command line: `blocked`, naming the entry, before anything below is written.
+  Then it writes the statement of the change when the study holds none
   (the command says which), then `done-summary.md` — the `flow-study` block of `/flow:work:handoff`
   §5, the same sections from the same sources, and, when `01-context.md` lists `## Study revisions`,
   the line `Revised at the reviewer's request: <n> reply(ies)` first under `## What and why`. It
   overwrites `00-summary.md`, sets the panel's `attention` to `done` and closes with
-  `done --summary-file`. Nothing else moves — no `mrs[]` entry, no branch, no brief — so
+  `done --summary-file`, plus one `--depends-on N` per `meta.json.ticket_deps` entry, in its order —
+  so the orchestrator can hold the ticket until those land; what it does with them is its call.
+  Nothing else moves — no `mrs[]` entry, no branch, no brief — so
   `meta.json.phase` stays at the last study phase and approval is an ordinary `start`.
 - **A person's changes rewind the study.** `/flow:work:run` §2 adds the reply to the ticket in
   `01-context.md` and sends the work back to `context`; the study phases then run again whole, the
@@ -331,7 +337,7 @@ person asking for changes, a ticket that already has code — is `/flow:work:run
 | Where | In `unattended` |
 |---|---|
 | Business brief before code (`build`, `fix`) | record — the brief is written to the phase artifact, marked `recorded (unattended)`, and travels in the MR/PR body |
-| The door to code in a study run (`build`, `fix` pre-flight) | done — `done-summary.md`, the study as `/flow:work:handoff` §5 writes it for the ticket |
+| The door to code in a study run (`build`, `fix` pre-flight) | done — `done-summary.md`, the study as `/flow:work:handoff` §5 writes it for the ticket, and one `--depends-on` per `meta.json.ticket_deps` entry |
 | Push and MR/PR creation (`ship`) | `publish` — the run commits on its own branch, writes title and body, and hands them over; the orchestrator pushes and opens the draft |
 | Writing a DB schema change, index or migration — in any phase, a review's own fixes included — or applying one (`validate`) | question `migration`, before the first line of it is written or run — except in `respond` and `green`, where it is blocked: a schema change agreed after the MR/PR exists goes back through `build` |
 | `review` with blockers or high-severity findings | question `high_findings` |
@@ -351,6 +357,7 @@ person asking for changes, a ticket that already has code — is `/flow:work:run
 | The next MR/PR of a train (`ship` close) | record — not started: one MR/PR per unattended run |
 | `build` with no startable MR/PR (its `depends_on` not `merged` in `meta.json`) | blocked — the reason names what must merge; an unattended `build` never stacks a branch on another, and never creates a remote branch |
 | The parent of a stacked MR/PR merged — rebase and force-push | blocked — never force-push unattended |
+| An approved study's branch (`run`, `why = start`, no build or fix begun) | record — fast-forwarded to its base when it holds no commit of its own (`/flow:work:run` §2); the base unreadable or the fast-forward failing → blocked. Not integrating: nothing of the run's is merged |
 | Integrating the base into the MR/PR's branch (`green`) | on `why = conflict`, record — `git merge origin/<base>` as the orchestrator left it, never rebase, each conflict resolved on its merits (`/flow:work:green` §5.C); on any other `why`, blocked — the orchestrator brings the base in |
 | Any offer about the work's own bookkeeping — a tracker issue, the first `KNOWLEDGE.md` or a knowledge save, a FLOW convention, an agent lesson or a saved specialist, the follow-up survey, carrying files over from the main checkout, a contract handoff, archiving the work | record — `Later`; nothing written outside the work folder |
 | A step the command cannot complete (a red suite it cannot fix, a tool missing, auth failing, the same check failing a second time) | blocked |

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

@@ -32,7 +32,15 @@ Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, mode
   would make — from the root cause and the constraints for the fix when the investigation has them,
   the reproduction and the ticket otherwise, `## Study revisions` included — the person approves a
   stated change, never `none`; then the summary, and
-  `<cmd> done --summary-file <work>/done-summary.md`. Nothing else in this command runs.
+  `<cmd> done --summary-file <work>/done-summary.md`, plus `--depends-on N` per
+  `meta.json.ticket_deps` entry, `N` its `ticket` with the leading `#` dropped — a bare `#` starts a
+  shell comment — and checked against `[A-Za-z0-9][A-Za-z0-9._-]*` before anything is written, else
+  `blocked` (flow-core §2.1). Nothing else in this command runs.
+- **`meta.json.ticket_deps` not empty, and not `unattended`** → the study rests on other tickets
+  (`/flow:feat:design` §5.1): name each — `<ticket> — <why>` — in the brief's stop (§2), one line,
+  so whoever builds confirms the piece is on **this work's branch**, not only on its base — the
+  branch was cut when the study began, and a piece that merged since needs the base brought in
+  before writing against it. Nothing is checked; waiting is the builder's call.
 - `size` `XS`: may start without `investigate`, but require a 2-3 line description of the fix — an `## Intended fix` in `03-investigation.md` is that description.
 - **An `## Intended fix` in `03-investigation.md` binds §2's brief at every size**: it is what a person approved at the end of a study (flow-core §2.1).
 - `size` ≥ S: require `investigate` in `phases_done` (on S it will have run its reproduction half only).

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

@@ -170,10 +170,21 @@ If `agents.fanout_tool` is set in `FLOW.md`, run the sweep through that tool; br
 - Do not touch X because…
 - Consider Y because…
 
+## Depends on other tickets
+<§4.1: `- <ticket> — <what it brings that the base branch lacks>`, then "Not dependencies (either order works)", or "none".>
+
 ## Investigation challenges
 <filled in by §5 with the challenger table>
 ```
 
+### 4.1 Tickets this fix depends on
+
+A fix can rest on another ticket the same way a design can — a corrected contract, a migration, a
+decision that lands only when that ticket merges. Detect and record it before the challenger, exactly
+as `/flow:feat:design` §5.1 says: the same rule, the same "Not dependencies (either order works)"
+line, the same `meta.json.ticket_deps` entries, written under `## Depends on other tickets` in
+`03-investigation.md`.
+
 ## 5. Root cause challenge (challenger)
 
 Before closing, launch a `Agent general-purpose` challenger with this task:

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

@@ -29,8 +29,15 @@ Implementation phase. Code is written here.
   and act as flow-core §2.1 "A study run" says. On `study` → this run writes no code: `size` XS and
   no `03-design.md` → first write the 2–3 line note below as that file, from `01-context.md` (its
   `## Study revisions` included) — the person approves a stated change, never `none`; then the
-  summary, and `<cmd> done --summary-file <work>/done-summary.md`. Nothing else in this command
-  runs.
+  summary, and `<cmd> done --summary-file <work>/done-summary.md`, plus `--depends-on N` per
+  `meta.json.ticket_deps` entry, `N` its `ticket` with the leading `#` dropped — a bare `#` starts a
+  shell comment — and checked against `[A-Za-z0-9][A-Za-z0-9._-]*` before anything is written, else
+  `blocked` (flow-core §2.1). Nothing else in this command runs.
+- **`meta.json.ticket_deps` not empty, and not `unattended`** → the study rests on other tickets
+  (`/flow:feat:design` §5.1): name each — `<ticket> — <why>` — in the brief's stop (§2), one line,
+  so whoever builds confirms the piece is on **this work's branch**, not only on its base — the
+  branch was cut when the study began, and a piece that merged since needs the base brought in
+  before writing against it. Nothing is checked; waiting is the builder's call.
 - `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`".)

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

@@ -286,6 +286,9 @@ Consolidate outputs into `.claude/work/<TICKET>/03-design.md`:
 - **Invariant**: <e.g. "after assignTo(user), ticket.assignee == user AND ticket.status != 'unassigned'">
 - **Edge / boundary**: <e.g. "empty input list → returns 0, does not throw">
 
+## Depends on other tickets
+<§5.1: one line per ticket this design cannot be built without — `- <ticket> — <what it brings that the base branch lacks>` — then, under "Not dependencies (either order works)", each premise on another ticket that holds whichever merges first, with one line why. Neither → "none".>
+
 ## Defensive mechanisms and their justification
 <One row per validation, guard, retry, lock, fallback, cache, idempotency, queue, or flag the design introduces. If you cannot name a REAL and PRESENT scenario that justifies it, the piece is unnecessary — remove it from the design.>
 
@@ -314,6 +317,33 @@ Consolidate outputs into `.claude/work/<TICKET>/03-design.md`:
 
 **"Acceptance criteria"**: start from the provisional list in `01-context.md` (pinned from the ticket in `/flow:feat:start`), fold in the clarifications and the internal/external contracts decided here, and promote it to the canonical enumerated list `/flow:feat:validate` gates against — observable, verifiable, proportional to size.
 
+### 5.1 Tickets this design depends on
+
+Fill `## Depends on other tickets` now, before the challenger of §6 reads the design. The study is
+often built by someone who never saw it made — another person, an unattended server — and who
+starts from the base. A design that rests on what another ticket has not delivered yet leaves that
+builder to find the piece missing and either ask or redo it.
+
+- **A dependency** is a piece, contract or decision the chosen design needs, that is **not on the
+  base this work builds from** (`meta.json.base`, empty → `git.default_base`) — checked there, after
+  a best-effort `git fetch origin <base>`, never assumed from a local ref — and that **another
+  ticket** of this tracker brings. Missing from the base with no ticket bringing it → it is scope
+  or an open question, not a dependency. A ticket in another repo is not a `ticket_deps` entry —
+  the orchestrator only resolves this tracker's numbers — so write it in the section as a
+  cross-repo dependency, for a person, and leave it out of the list.
+- **Not a dependency**: a premise that holds whichever ticket merges first. Say so under "Not
+  dependencies (either order works)", so nobody waits for it.
+- **Record each one** in that section and in `meta.json.ticket_deps` —
+  `{ "ticket": "<the reference as a ticket body writes it: #253, MT-123>", "why": "<one line>" }`,
+  never one twice. `ticket_deps` is the record the exits read (`/flow:work:handoff` §5, the door to
+  code of an unattended study run, flow-core §2.1); the section is the study's prose. Each run of
+  this phase writes the list whole from the design it closes; `plan`, which runs after it, appends
+  its own again. A §6 response or a §9 edit that changes what the design needs changes
+  the section and the list together. None → `[]` and "none".
+
+`ticket_deps` is not `mrs[].depends_on`: that one orders this work's own MRs/PRs, this one names
+other tickets. Flow never checks whether a dependency has closed — whoever builds waits for it.
+
 ## 6. Design challenge (challenger)
 
 Before closing, **challenge the design** with an `Agent general-purpose` and this self-contained brief:

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

@@ -122,6 +122,7 @@ Add the `mrs` array with the agreed plan:
 ```
 
 - `n` = execution order (topological): `depends_on` only ever references a **lower** `n`; `wave` groups MRs/PRs that can run in parallel. `/flow:feat:build §1` reads `depends_on` to pick the next **startable** MR/PR and to say which can go in parallel — keep both accurate whenever the plan is edited or renumbered.
+- **Another ticket is not a `depends_on`.** An MR/PR that turns out, while splitting, to need something another ticket brings is a dependency of the study: append it to `meta.json.ticket_deps` as `/flow:feat:design` §5.1 says, name it in that MR/PR's entry of `04-mr-plan.md` beside what it waits on, and leave `03-design.md` as it closed. The design's own entries stand as they are.
 - **`phases_done`** starts `[]` in every seeded entry: it tracks `build`/`review`/`validate` **for that MR/PR specifically**, so the gates in `/flow:feat:review §1`, `/flow:feat:validate §1` and `/flow:feat:ship §1` judge *this* MR/PR — a sibling's review never satisfies a new MR/PR's gate.
 - Estimates are **indicative**, not contractual. `/flow:feat:build` uses them as a thermometer: real work over `lines_est` +50% or `files_est + 2` triggers the "cut or continue" question (see §2.3 in build). **A thermometer is not a target** (flow-core §9): an estimate is never met by deleting comments, tests or blank lines, by compressing readable code, or by cutting where the piece is not coherent — the overrun is recorded instead, and a diff shaped to fit a number is the one case where these estimates lie to the phases downstream.
 

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

@@ -108,6 +108,9 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
       "note": "reason if closed/superseded; empty otherwise"
     }
   ],
+  "ticket_deps": [
+    { "ticket": "#253", "why": "one line, what that ticket brings that the base branch lacks" }
+  ],
   "related_repos": [
     { "repo": "sibling-project", "scope": "what's needed there", "status": "pending" | "in_progress" | "done", "contract_handoff": "none" | "pending" | "published → <location>" }
   ],
@@ -156,6 +159,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
   Two fields for the review because they are two facts. `reviewed_sha` used to be `git rev-parse HEAD` at the end of the phase, which by then held the round's own fixes — so `ship` compared a sha against itself and reported a match over code no reviewer had read. Read by `ship` at pre-flight against `HEAD`: a delta of test files and this work's own folder passes with a note in `06-review.md`; anything else stops and asks in every autonomy mode. Empty is not a mismatch; `fixed_sha` set with `reviewed_sha == HEAD` is one. `review` also reads `reviewed_sha` back as **its own base** on a re-review, so the second round reads the delta instead of the whole branch.
 - **`respond_rounds`**: rounds of `/flow:work:respond` on an MR/PR. `/flow:work:respond §1` reads it against `quality.respond_max_rounds` (empty = 3) and refuses the round that would exceed it, handing the open threads back to the user.
 - **`related_repos`**: the **other repos a task touches**. Captured at `/flow:feat:start` / `/flow:bug:start` §cross-repo, refined at `design`/`plan`, reminded at `ship`, shown by `daily`/`resume`/`status`. flow only notes and reminds — never touches the other repo. `[]` for single-repo.
+- **`ticket_deps`**: the **other tickets this study cannot be built without** — something the design needs that is not on the base branch and that another ticket brings (`/flow:feat:design` §5.1, `/flow:bug:investigate` §4.1). Read at the two exits of a study: `/flow:work:handoff` §5 writes a `Depends on <ticket>` line per entry into the ticket body, and an unattended study run passes `--depends-on N` per entry on its `done` (flow-core §2.1). Not `mrs[].depends_on`, which orders this work's own MRs/PRs. Written whole each time `design` (or `investigate`) runs, and removed when an unattended study is rewound. `[]` or absent when the study depends on nothing.
 - **`contract_handoff`**: whether the sibling knows **what shape to build against** (`scope` is prose; distinct from `status`). `none` — consumes no contract declared here. `pending` — consumes one, not handed over yet. `published → <location>` — published where that side reads it (normally the tracker ticket; `/flow:feat:ship` §6.3), picked up by the sibling's `/flow:feat:start` §3.6.
 - **`followups`**: work a phase deliberately did **not** do here — a neighbouring defect found while building, a piece put out of scope while planning, a risk recorded but not mitigated, an edge case left unchecked, a prevention action from a postmortem. Written by the phase that parks it (asks nothing) when it clears the bar of flow-core §7, triaged **once** at `ship`'s Close behind a skeptic and a ceiling on how many may become questions, published in the MR/PR description while still open, and surfaced by `status`/`daily`/`next` — including from `_archive/` — until `declined` or `done`. Shape and rules: flow-core §7. `[]` when the work deferred nothing.
 - **`defaults_used`**: an empty `FLOW.md` key a phase resolved with its default instead of asking — written in `guided`/`auto`, where asking would breach the never-a-question contract (flow-core §0). Not an error and not deferred work: a record, aggregated by `/flow:doctor` across every work including `_archive/`, so a key that keeps defaulting can be pinned once instead of decided every time. `[]` when nothing defaulted.

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

@@ -144,13 +144,27 @@ the ticket read it there, never in the work folder; the receiver does not parse
   <!-- 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.
+  Criteria keep their literal values. `## Design in brief` ends with each `meta.json.ticket_deps`
+  entry and its why — `Depends on #253: <why>` — so whoever approves the study sees what it waits
+  for; an unattended study's `done-summary.md` is this block, so it carries them too. 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
+  no markers yet, the block appended after a blank line. Then, for each `meta.json.ticket_deps`
+  entry (`/flow:feat:design` §5.1) whose line is not already a line of that body — same text,
+  ignoring case and surrounding whitespace — one line after the end marker, in `ticket_deps` order:
+
+  ```
+  Depends on #253
+  ```
+
+  `#253` being the entry's `ticket` as it stands. Outside the markers so a later rewrite of the
+  block leaves it alone, and never removed: a line a person wrote by hand looks exactly like one
+  flow wrote, and the convention is theirs too. 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.
+- **Show the block, and the `Depends on` lines it adds, and ask** with `AskUserQuestion`, **in
+  every mode**: it writes to a shared tracker. A `Depends on` line already in the body, outside the
+  markers, that no entry names — a dependency a revised study dropped, or one a person added — is named in the same
+  question and left in place: whether it still holds is theirs to say. **Write it** · **Skip**. Failure → its message in one line; the push stands.
 
 ## 6. Close
 

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

@@ -63,7 +63,7 @@ of truth, and an argument that disagrees with it is ignored and named in the log
 | `conflict` | exists | `/flow:work:green` — the MR/PR conflicts with its base; which base, and where it stands, come from `<cmd> events --json` |
 | `review` · `pipeline` · `conflict` | none | `blocked` — there is no work of this ticket to answer for |
 
-**The work's branch, on `start` and `study`.** The current branch is `meta.json.branch` → nothing to do. It is
+**The work's branch, on `start` and `study`.** The current branch is `meta.json.branch` → no switch. 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:
 
@@ -86,6 +86,21 @@ closing order is relaunched there — then, in this order:
    `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" }`.
 
+**On `start`, a study's branch catches up with its base** — once on the work's branch, the "no
+switch" case included, and only while no build or fix has begun (neither `05-implementation.md` nor
+`04-fix.md` exists). Every command below runs in the work's own checkout — step 2's worktree when
+that is where it lives. A study writes no code, so its branch still sits where the base was when the
+study began; an approval that waited for the tickets the study depends on (`meta.json.ticket_deps`)
+would otherwise build on a base that lacks them. `<base>` = `meta.json.base`, empty →
+`git.default_base`: `git fetch origin <base>`, then `<ref>` = `origin/<base>`; the fetch failing
+with a remote configured → `blocked`, since a stale ref would leave the build on the old base
+unnoticed. No remote → the local `<base>`. `git merge-base --is-ancestor HEAD <ref>` and `HEAD` is not
+`<ref>` → the branch holds no commit of its own and the base moved: `git merge --ff-only <ref>`, and
+record `{ "key": "unattended:base-caught-up", "default": "<old short sha> → <new short sha> on
+<base>", "phase": "run" }`. The fast-forward fails → `blocked`, its message as the reason. Not an
+ancestor → it holds commits a previous run made: leave it as it is — bringing the base into work in
+progress is the orchestrator's (flow-core §2.1).
+
 **A person's changes to a study, on `study`** (flow-core §2.1: they rewind it). The work's branch
 first, as above. `<work>/study-revision.md` holds the reply, as the row above wrote it. Each step
 can be run again: a run that dies part-way is finished by the next relaunch, whatever it serves.
@@ -109,7 +124,8 @@ can be run again: a run that dies part-way is finished by the next relaunch, wha
    `study-revision.md` and earlier `before-*/` folders into `<work>/before-<id7>/` — never
    overwriting a name already there — so no artifact, summary or agent answer of the discarded study
    leaks into the next. Then `meta.json`: `phase` = `context`, `phases_done` = `["context"]`, `mrs`
-   removed (the row that blocks a work past the study guarantees nothing was built), `notes`
+   removed (the row that blocks a work past the study guarantees nothing was built), `ticket_deps`
+   removed (the redone study finds its dependencies again), `notes`
    emptied, and every `followups[]` entry a study phase wrote (`source` `design`, `plan` or
    `investigate`) removed.
 5. **Re-size**: estimate the size again with `/flow:feat:start` §4's table (`/flow:bug:start`'s for