flow-workflows 0.92.0 → 0.94.0

package/adapters/opencode/commands/flow-feat-design.md

@@ -101,8 +101,8 @@ authorization, payments, personal data, a public contract, a migration):
 Each advisor gets this brief, with its lens substituted:
 
 > Propose ONE approach to solve ticket `<TICKET>`, from this lens: `<lens brief>`. Read
-> `.claude/work/<TICKET>/01-context.md` for context and the effective FLOW configuration (base plus
-> active harness overlay) for project conventions. What already exists in the repository:
+> `.claude/work/<TICKET>/01-context.md` for context and the effective FLOW configuration (base, the
+> context layer `FLOW_CONTEXT` selects, and the active harness overlay) for project conventions. What already exists in the repository:
 > `<the §1.5.1 inventory>` — propose a new piece only where nothing there fits. Do not
 > write code. Be specific about real modules and layers of this project. Report: name, what it is
 > (one sentence), modules/layers affected, main risk, and why it could be a bad idea. Under 250 words.
@@ -288,6 +288,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.>
 
@@ -316,6 +319,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/opencode/commands/flow-feat-plan.md

@@ -124,6 +124,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/opencode/commands/flow-feat-ship.md

@@ -531,7 +531,9 @@ Read `meta.json.conventions_candidates[]` (flow-core §8). **No entries with `st
    decision — the FLOW config is personal — so it is one question, never a negotiation.
 4. **Add / Replace** → append a `conventions` line to the base `FLOW.md`. For a `quality.<key>`,
    update the file its effective value came from, or the base when it was absent; otherwise an
-   overlay would immediately hide the correction. Show the old value and source in the result.
+   overlay would immediately hide the correction. A value from the context layer (flow-core §0) is
+   not edited here: that file is committed and the MR/PR is already out, so record the candidate as
+   a `followups[]` entry (`kind: "tooling"`) naming the file and the line instead. Show the old value and source in the result.
    Then `status: "added"`. **Not a rule** → `declined`, never offered again in any work.
    **Later** → stays `proposed` and is offered again by the next `ship` of a work that has it.
 5. **One line on screen**: how many rules were added and where, never a list of the texts —

package/adapters/opencode/commands/flow-feat-start.md

@@ -48,7 +48,7 @@ its reason file in a `mktemp -d` directory (flow-core §2.1).
 
 ## 1. Pre-flight
 
-- Read the effective FLOW configuration per flow-core §0; neither base nor active overlay → each
+- Read the effective FLOW configuration per flow-core §0; no FLOW layer present → each
   step's default. This command **creates** `00-summary.md` (§6) instead of reading it (flow-core §5).
 - No recognizable project structure → warn and stop.
 - **Determine the mode**: `$ARGUMENTS` non-empty → *ticket mode* (identifier = `$ARGUMENTS`); empty → *ticket-less* (identifier = the §2.5 slug).

package/adapters/opencode/commands/flow-feat-validate.md

@@ -36,7 +36,7 @@ One of the three below writes and two of them read, so they do not all go at onc
 
 **First, alone — the writer.** It is told the **test files are the deliverable**, saved as each one is finished, not at the end:
 
-1. **Testing agent**: the `agents.testing` agent from the effective FLOW config; if empty, `Agent general-purpose` with this role. Brief: "Review the branch changes and complete the test suite where coverage is missing. Focus: the acceptance criteria in `03-design.md` marked `test` that no current test demonstrably asserts (see the §3 mapping), plus edge cases from `03-design.md`, error paths, input validations, emitted domain events. Do not rewrite tests that already pass. Read `.claude/work/<TICKET>/03-design.md` and `05-implementation.md`. Follow the project's effective test conventions from `FLOW.md` plus the active harness overlay."
+1. **Testing agent**: the `agents.testing` agent from the effective FLOW config; if empty, `Agent general-purpose` with this role. Brief: "Review the branch changes and complete the test suite where coverage is missing. Focus: the acceptance criteria in `03-design.md` marked `test` that no current test demonstrably asserts (see the §3 mapping), plus edge cases from `03-design.md`, error paths, input validations, emitted domain events. Do not rewrite tests that already pass. Read `.claude/work/<TICKET>/03-design.md` and `05-implementation.md`. Follow the project's effective test conventions from `FLOW.md`, the context layer `FLOW_CONTEXT` selects and the active harness overlay."
 
 **Then, in parallel — the readers**, once the testing agent has reported and its files are on disk. The suite runs here and not earlier for a second reason beyond the collision: run after the writer, it is the first thing that has ever executed the tests this phase just added.
 

package/adapters/opencode/commands/flow-init.md

@@ -22,14 +22,17 @@ and optional harness-owned values in the active `FLOW.<harness>.md`. The active
 `FLOW.zcode.md`; identify it from the
 product executing this command, never from the selected model (zcode runs the Claude pages too, so
 the page you are reading does not name the harness). Every other `/flow-*` command reads
-the base and then that overlay. The user answers the **minimum**: what the repo can tell is
+the base, then the context layer `FLOW_CONTEXT` selects (flow-core §0), then that overlay. A
+context file is the repo's, committed for where flow runs: `init` writes neither it nor its key. The user answers the **minimum**: what the repo can tell is
 auto-detected and only confirmed.
 
 Key names and contract: `examples/FLOW.template.md` from the plugin. Do not invent keys that are not there.
 
 ## 1. If either configuration file already exists
 
-Show `FLOW.md` and the active overlay when each exists, then show their effective merged values.
+Show `FLOW.md` and the active overlay when each exists, then show their effective merged values —
+with the context layer `FLOW_CONTEXT` selects merged in and named when it is set (flow-core §0), so
+a value it masks is not offered as if the base still decided it.
 Ask: **update** (re-detect and re-ask, preserving what the user keeps) or **cancel**. Never read,
 change, or display another harness's overlay. Never overwrite either file without confirmation.
 Label harness-sensitive values that currently come from the base as **shared across harnesses**;
@@ -104,7 +107,7 @@ review, not a questionnaire. Then, and only then, five questions:
 4. **The quality commands as one block** (`quality.test`, `test_one`, `static_analysis`, `style_fix`,
    `db_update`, `db_diff`) — confirm or edit what §2 found, all in one question, each may stay empty
    (= auto-discover at the moment it is needed). Several suites chain into `test` with `&&`.
-5. **Git-ignore** `FLOW.md`, `FLOW.*.md`, and `.claude/work/` — see §5.
+5. **Git-ignore** `FLOW.md`, the six harness overlays by name, and `.claude/work/` — see §5.
 
 **Two keys are written without being asked**: `agents.fanout_max` (`4`) and `agents.budget_max`
 (`12`), with their default values, because they are the only brake on what a review costs and a key
@@ -123,7 +126,7 @@ overlay, never the base.
 
 ## 4. Write the base and, only when needed, the active overlay
 
-Write compact files at the repo root — every command reads the base and active overlay in every
+Write compact files at the repo root — every command reads every FLOW layer in every
 phase, so their size is paid on every step:
 
 - `FLOW.md` holds repo facts and shared preferences: tracker, git, autonomy, quality commands, cost
@@ -156,9 +159,10 @@ phase, so their size is paid on every step:
 - The base and overlays are **personal config, not team config** (repo facts mixed with one
   developer's flow preferences, tools and agents; **no secrets**) — they should not be committed.
   One `AskUserQuestion`, both parts in the same question:
-  - The root files not already git-ignored → **offer to add `/FLOW.md` and `/FLOW.*.md` to
-    `.gitignore`**. This edits a tracked file — confirm before writing. A team wanting the repo-fact
-    subset can still commit it deliberately. Do not use a recursive pattern: examples under the
-    plugin must remain visible.
+  - The root files not already git-ignored → **offer to add `/FLOW.md`, `/FLOW.claude.md`, `/FLOW.codex.md`, `/FLOW.gemini.md`, `/FLOW.hermes.md`, `/FLOW.opencode.md` and `/FLOW.zcode.md` to `.gitignore`**,
+    each by name. This edits a tracked file — confirm before writing. A team wanting the repo-fact
+    subset can still commit it deliberately. Never `/FLOW.*.md`: it also hides a context layer
+    (`FLOW.<context>.md`, flow-core §0), which a repo commits on purpose. Do not use a recursive
+    pattern either: examples under the plugin must remain visible.
   - Git-ignore `.claude/work/` too — recommended default: ignore it (artifacts are personal working state; teams that want to share them commit deliberately). `git.worktree` not `off` → offer `.worktrees/` in the same gesture.
 - Suggest `/flow-next` as the next step (it routes to `/flow-feat-start`, `/flow-work-resume` or `/flow-work-status`).

package/adapters/opencode/commands/flow-next.md

@@ -23,8 +23,9 @@ runs a phase on its own and never advances `meta.json`.
 
 ## 1. Look
 
-1. Identify the active harness. Does `FLOW.md` or its active `FLOW.<harness>.md` exist at the repo
-   root? An inactive harness's overlay does not configure this session.
+1. Identify the active harness. Does `FLOW.md`, the context file `FLOW_CONTEXT` selects, or the
+   active `FLOW.<harness>.md` exist (flow-core §0)? An inactive harness's overlay, or a context file
+   no variable selects, does not configure this session.
 2. `git branch --show-current`, and whether `.claude/work/*/meta.json` has a `branch` equal to it (also check `worktree` entries, and `.claude/work/_archive/` is ignored).
 3. `.claude/work/` — how many open works, and their `phase` (from `meta.json`; read `00-summary.md` when present, never the full artifacts).
 3b. `followups[]` across those works **and** `.claude/work/_archive/*/meta.json`: any entry `accepted` with no `work` started (flow-core §7).
@@ -34,7 +35,7 @@ runs a phase on its own and never advances `meta.json`.
 
 | Situation | Say | Propose |
 |---|---|---|
-| Neither base nor active overlay | "This repo is not configured for flow on this harness yet." One line on what the FLOW config is (personal config, auto-detected). | `/flow-init` |
+| No FLOW layer present | "This repo is not configured for flow on this harness yet." One line on what the FLOW config is (personal config, auto-detected). | `/flow-init` |
 | A work matches the current branch | Its stop header (flow-core §3: ticket · size · phase · MR #n of N) and the next phase for its size. | `/flow-work-resume` |
 | No match, but open works exist | Count, and the two most recently updated with their phase. | `/flow-work-status`, or `/flow-feat-start` / `/flow-bug-start` if the user said what they want to do |
 | No works at all, but an accepted follow-up is waiting | "Nothing in flight — but `<TICKET>` F1 was accepted and never started: `<title>`." | `/flow-feat-start <ticket>` (or `/flow-bug-start`) for that follow-up · `/flow-feat-start` for something else |
@@ -43,7 +44,7 @@ runs a phase on its own and never advances `meta.json`.
 - The SessionStart hook (`hooks/session-start.sh`) has already printed the first two rows of this table's second case — the header and what the last session was doing — off disk, without reading a ticket or an artifact. Say them again anyway: `next` is where the user asked, and a line they scrolled past is not an answer.
 - An `accepted` follow-up exists **and** other works are open → do not reroute; add one line naming it after the options. It is a standing commitment, not an interruption.
 - Dirty tree and no matching work → mention it in one line ("uncommitted changes on `<branch>`, no work is tracking them") before the options; `start` will warn again.
-- A base or active overlay is present but `/flow-doctor` has never been run in this session and the
+- A FLOW layer is present but `/flow-doctor` has never been run in this session and the
   git host CLI is not on `PATH` → add `/flow-doctor` as a secondary option.
 - In `autonomy.mode: guided`/`auto`, the route is still asked: `next` is where a session begins, and the mode governs what happens *inside* a phase, not which work the user wants to pick up.
 

package/adapters/opencode/commands/flow-work-README.md

@@ -24,8 +24,11 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
   commands, code conventions, and observability profile.
 - The active `FLOW.<harness>.md` is an optional sparse overlay (`claude`, `codex`, `opencode`,
   `gemini`, `hermes`, or `zcode`) for model names, agents, skills, orchestration, knowledge tools, or any other value that
-  differs on that harness. Every command reads the base and then the active overlay in step 0;
+  differs on that harness. Every command reads the base, the context layer below, and then the
+  active overlay in step 0;
   existing repos with only `FLOW.md` behave exactly as before.
+- `FLOW_CONTEXT=<name>` in the environment adds `FLOW.<name>.md` between the two: a layer the repo
+  commits for where flow runs (CI, a server, an orchestrator), with the overlay's merge rules.
 - An overlay key replaces the base even when explicitly empty; an absent key inherits it. Lists
   replace whole lists. Overlay `conventions` are added after base conventions. In the rest of this
   document, `FLOW.md` means the effective merged configuration unless a write target is explicit.
@@ -110,6 +113,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>" }
   ],
@@ -158,6 +164,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.
@@ -242,7 +249,7 @@ Two signals arrive on an open MR/PR, each with its own cross-cutting loop (feat
 
 ## Cross-cutting commands
 
-- `/flow-next` — the entry point: no base or active overlay → init; work on the current branch →
+- `/flow-next` — the entry point: no FLOW layer → init; work on the current branch →
   resume; otherwise status.
 - `/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.

package/adapters/opencode/commands/flow-work-handoff.md

@@ -146,13 +146,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/opencode/commands/flow-work-run.md

@@ -65,7 +65,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:
 
@@ -88,6 +88,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.
@@ -111,7 +126,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