flow-workflows 0.92.0 → 0.94.0

package/adapters/hermes/skills/flow-feat-validate/SKILL.md

@@ -38,7 +38,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/hermes/skills/flow-init/SKILL.md

@@ -24,14 +24,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**;
@@ -106,7 +109,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
@@ -125,7 +128,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
@@ -158,9 +161,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/hermes/skills/flow-next/SKILL.md

@@ -25,8 +25,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).
@@ -36,7 +37,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 |
@@ -45,7 +46,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/hermes/skills/flow-work-README/SKILL.md

@@ -26,8 +26,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.
@@ -112,6 +115,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 +166,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.
@@ -244,7 +251,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/hermes/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/hermes/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/opencode/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.94.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
@@ -24,10 +24,14 @@ copy that stays enabled: the harness resolves a command from the one and a skill
 silently. Name both numbers at the first stop and say which half is which; a rule this file adds and
 a command relies on is simply absent in that session, and nothing else will report it.
 
-## 0. Effective FLOW config — base plus harness overlay
+## 0. Effective FLOW config — base, context layer and harness overlay
 
 - **Look before you read.** The first thing a phase does about configuration is list what is there:
-  `ls <root>/FLOW*.md` (the root being the one the next bullet resolves). One call, and it is not
+  `find <root> -maxdepth 1 -name 'FLOW*.md'; printf 'FLOW_CONTEXT=%q\n' "${FLOW_CONTEXT-}"` (the roots
+  being the ones the bullets below resolve — in a worktree, name both in the same `find`). A quoted
+  `-name`, not a shell glob: in zsh a glob that matches nothing aborts the whole command, so the
+  root that has no FLOW file would hide the one that does; and `%q`, not `echo`, so a trailing
+  space or a `\r` from a CRLF `.env` shows instead of reading as a clean name. One call, and it is not
   optional — **an overlay you did not list is an overlay you did not read**, and nothing downstream
   will notice. Every command and artifact calls the effective configuration "`FLOW.md`", a file that
   exists, so reading it and stopping feels finished — and a missed overlay reports its keys as unset,
@@ -37,24 +41,47 @@ a command relies on is simply absent in that session, and nothing else will repo
   this command: `FLOW.claude.md`, `FLOW.codex.md`, `FLOW.opencode.md`, `FLOW.gemini.md`,
   `FLOW.hermes.md`, or `FLOW.zcode.md`. The
   harness is the product executing the command, never guessed from a model name. An overlay is
-  valid without a base file; unknown `FLOW.*.md` names are ignored. **A page can outlive the product it
+  valid without a base file. **A page can outlive the product it
   was written for**: zcode reads the plugin's Claude pages as well as its own `/flow:`-prefixed
   mirror of them, so a `claude` in a path or in a `--harness` flag records where the page was
   written, never who is running it. On zcode the overlay is `FLOW.zcode.md` and the flag is
   `--harness zcode`, whichever of the two pages you were handed. Throughout every command,
   **"FLOW.md" means this effective merged configuration** unless the command explicitly names a
   file it will edit.
+- **The context layer sits between the two, and whoever launches flow picks it.** `FLOW_CONTEXT`
+  set in the environment → `FLOW.<FLOW_CONTEXT>.md` is read after the base and before the harness
+  overlay, with the overlay's merge rules. It is how a repo commits what only makes sense where
+  flow runs unattended, in CI or on a server — a way to drive the app in a container, a convention
+  for those MRs/PRs — without it reaching every laptop through the base. Flow never needs to know
+  who set it. Unset or empty → no context layer, and nothing else changes. Set, and the file is
+  not there → not an error; say so beside the files you name (`FLOW_CONTEXT=ci: FLOW.ci.md not
+  found`), because a typo in the variable is otherwise a repo with no context file. **The name is
+  one plain segment, taken exactly as written**: an ASCII letter or digit, then ASCII letters,
+  digits, `-` or `_` — nothing trimmed, so a padded `" ci"` fails — and not a harness name in any case
+  (`FLOW_CONTEXT=Claude` would read an overlay as the wrong layer). A name that fails → read no
+  context layer, say so in the same place, and carry on — never a stop. `flow-workflows` applies
+  the same rule, so the two of you resolve the same layers.
+  Any other `FLOW.<name>.md` at the root is a context file this run did not select: unread, by
+  design.
 - **"The repo root" is the main checkout's, not the worktree's.** With `git.worktree` set, every
   phase after `start` runs inside a linked worktree — and a `FLOW.md` the repo git-ignores (the
   normal case for a personal config, and always the case for a harness overlay) exists **only in
   the main checkout**. Looking for it where the phase happens finds nothing, and a configuration
   that resolves to every fallback looks exactly like a repo that never had one: the models, the
   ceilings and the sensitive paths are silently the defaults, and the phase reports nothing
-  because from where it stands there is nothing to report. So: prefer a `FLOW.md` in the directory
-  you are in — a repo that commits its config has one in every worktree, and it may legitimately
-  differ — and otherwise read both files from the main checkout, which
+  because from where it stands there is nothing to report. So, **for each file on its own**: prefer
+  the copy in the directory you are in — a repo that commits its config has one in every worktree,
+  and it may legitimately differ — and otherwise read it from the main checkout, which
   `git rev-parse --path-format=absolute --git-common-dir` locates from anywhere (its parent
-  directory). Name the file you actually read when a stop reports configuration.
+  directory) — **unless that checkout tracks it**: the main checkout's HEAD is the first `HEAD`
+  line of `git worktree list --porcelain`, and `git ls-tree --name-only <that sha> -- <file>`
+  printing the name means it is tracked. A tracked file missing here is this branch's own state,
+  deleted, renamed or not added yet, and the main checkout's copy is another branch's version.
+  Either command failing → do not borrow the file, and say so where you name the files you read.
+  The file name matches exactly, case included, even where the filesystem would not care. One root for all of them misses a file whenever
+  they live apart: a committed context file is in the worktree while the git-ignored base exists
+  only in the main checkout. Name the file you actually
+  read, and where, when a stop reports configuration.
   **This is a rule about reading a git-ignored config, and it inverts for anything a phase
   writes into the repo.** A tracked file belongs to the branch, and the branch is the worktree:
   written to the main checkout it lands on whatever that checkout is standing on — usually the
@@ -67,16 +94,17 @@ a command relies on is simply absent in that session, and nothing else will repo
   ("add this to try it once") would be read as the configuration it illustrates, while the prose
   around it says otherwise and nothing reports the disagreement. **Skip fenced regions when you read a FLOW
   file**; `flow-workflows` does the same, so the two of you resolve the same config.
-- Merge by section and key. A key present in the active overlay replaces the base value; a key
-  absent there inherits the base. **A present-but-empty overlay key masks the base** and resolves
+- Merge by section and key, in order: base, context layer, active overlay. A key present in a
+  later layer replaces the earlier value; a key absent there inherits it. **A present-but-empty key
+  masks what came before** and resolves
   to the normal empty-key fallback — this is how Codex can inherit its session model while a legacy
   `FLOW.md` still names a Claude model. A list-valued key is replaced as a whole, never appended.
-  `conventions` is the one unkeyed section: its overlay lines are added after the base lines, so
-  both sets apply. **Every value carries the file it came from**, and a phase that prints a value
+  `conventions` is the one unkeyed section: each layer's lines are added after the previous ones,
+  so every set applies. **Every value carries the file it came from**, and a phase that prints a value
   prints that file with it — "`agents: opus` (`FLOW.claude.md`)", never the value alone. `doctor` reports it and later
   edits preserve it.
-- The sections in either file are tracker, git, autonomy, quality, agents, models, data,
-  conventions, notes, knowledge, and observability. Both files missing, or an effective empty key
+- The sections in any of the files are tracker, git, autonomy, quality, agents, models, data,
+  conventions, notes, knowledge, and observability. No layer found, or an effective empty key
   → the default or auto-discovery each step names. Never stop because a file or key is empty.
 - **An empty key that is a real decision for this repo is offered where it first matters**, and
   nowhere else. Three steps, in order:
@@ -101,7 +129,10 @@ a command relies on is simply absent in that session, and nothing else will repo
   The FLOW config is personal, so writing a line is not a team decision; it is still an edit to the
   tree, so the option is an explicit choice the user makes, never a default action (same bar as
   flow-core §8's convention offer, and the two share their wording). Update a value in the file it
-  came from. A new repo fact or shared preference goes to `FLOW.md`; a new harness-owned model,
+  came from — **except that the context layer is not personal**: it is committed, a value it holds
+  is the repo's, and changing it is a change to a tracked file of this branch, written here (the
+  inversion above) and shipped in the MR/PR like code, never offered as a quick config line. A new
+  key never goes to the context layer by this route. A new repo fact or shared preference goes to `FLOW.md`; a new harness-owned model,
   agent, skill, orchestration tool, or knowledge-tool name goes to the active overlay. Never edit an
   inactive harness's overlay.
 - **Knowledge sources, by role** (`knowledge` section): `search` (one or more tools or commands
@@ -252,7 +283,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 +344,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 +368,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 +388,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 |
@@ -1072,7 +1110,10 @@ learned during `build` is enforced in the review of that same MR/PR, not of the
 **`ship` offers them once, at Close** — one `AskUserQuestion`, batched up to 4, options **Add to
 FLOW.md** · **Not a rule** · **Later**, the `text` being the whole prompt. *Add* appends a convention
 to the base `FLOW.md`. A `quality` correction updates the file its effective value came from, or the
-base when the key was absent: otherwise an overlay would immediately hide the correction. The FLOW
+base when the key was absent: otherwise an overlay would immediately hide the correction. A value
+that came from the context layer is the exception (§0): that file is committed, so the correction
+is a change to this branch, made before the MR/PR is created or offered as a follow-up — never a
+config line written after it. The FLOW
 config is personal, but this is still an edit to a file in the tree, so **it is asked in every
 mode**, like `KNOWLEDGE.md`'s first creation. No candidates → the step does not exist and says
 nothing.

package/adapters/opencode/commands/flow-bug-fix.md

@@ -34,7 +34,15 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
   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/opencode/commands/flow-bug-investigate.md

@@ -172,10 +172,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/opencode/commands/flow-bug-validate.md

@@ -35,7 +35,7 @@ Read `~/.claude/flow/CORE.opencode.md` first (shared rules: `FLOW.md` step 0, mo
 
 **Mandatory regression test**: launch the `agents.testing` agent from FLOW.md (empty → `Agent general-purpose` with a test-writing role):
 
-> Write a test that **fails** before the fix and **passes** after. Read `.claude/work/<TICKET>/03-investigation.md` (minimal reproduction), `04-fix.md` (what was changed). Follow the effective conventions from `FLOW.md` plus the active harness overlay. Report the path of the added test.
+> Write a test that **fails** before the fix and **passes** after. Read `.claude/work/<TICKET>/03-investigation.md` (minimal reproduction), `04-fix.md` (what was changed). Follow the effective conventions from `FLOW.md`, the context layer `FLOW_CONTEXT` selects and the active harness overlay. Report the path of the added test.
 
 Then:
 1. Run only that test with `quality.test_one` from FLOW.md; it must pass.

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

@@ -28,15 +28,19 @@ changing machines, after `/flow-init`, or when a command failed the way an envir
 ## 1. Load
 
 - Identify the active harness and read the effective configuration exactly as flow-core §0: base
-  `FLOW.md`, then its `FLOW.<harness>.md` overlay. Never read another harness's overlay. Both absent
+  `FLOW.md`, then the context layer `FLOW.<FLOW_CONTEXT>.md` when the variable is set, then its
+  `FLOW.<harness>.md` overlay. Never read another harness's overlay. **Name the active context** —
+  its value and the file it selects, `none` when the variable is unset, and the reason when the name
+  was refused or the file is missing (flow-core §0): a context set on a server and lost on the way
+  reads here as `none`, and nowhere else. No layer present
   is **not** an error: say so in one line, check what needs no config (git, hooks, harness, base
   branch, plugin files), and note that `/flow-init` would let this command check the rest.
   **Say which checkout the configuration came from** whenever it is not the directory you are in
   (flow-core §0: a worktree does not carry a git-ignored `FLOW.md`). A diagnosis run from a
   worktree that quietly read nothing is the one that certifies a repo as unconfigured.
-- Parse both files by section: `tracker`, `git`, `autonomy`, `quality`, `agents`, `models`, `data`,
+- Parse each layer by section: `tracker`, `git`, `autonomy`, `quality`, `agents`, `models`, `data`,
   `conventions`, `notes`, `knowledge`, `observability`; merge keys and empty masks per flow-core §0.
-  Keep the source of every effective value. Both absent → §1.5 runs with **every** key empty (all
+  Keep the source of every effective value. No layer present → §1.5 runs with **every** key empty (all
   fallbacks), which is a legitimate and complete answer.
 
 ## 1.5 What the configuration says
@@ -50,14 +54,14 @@ documented keys absent from the effective configuration (the "empty → fallback
 For **every** documented key in `examples/FLOW.template.md`, one row:
 
 - **set** → the value and source file (list keys like `git.worktree_resync` or
-  `quality.reviewers`: the items). A value overridden by the active overlay names only the active
-  value here; do not make the user mentally merge two tables.
+  `quality.reviewers`: the items). A value overridden by a later layer names only the winning
+  value and its file here; do not make the user mentally merge two tables.
 - **empty / absent** → `(empty → <what happens>)`, taken from the key's comment in the template
   (e.g. `quality.test` → "auto-discover from Makefile/npm/composer/Gradle/dotnet/Xcode/Flutter"; `tracker.tool` → "manual paste";
   `agents.security` → "general-purpose with the role"; `git.worktree` → "off / in-place";
   `git.worktree_resync` → "`/flow-work-try` only switches, no re-sync"; `quality.review_depth` →
-  "proportional" — the other depths are `light` and `full`). An empty overlay mask says
-  `(masked by FLOW.<harness>.md → <what happens>)`. Never leave a reader guessing what an empty key
+  "proportional" — the other depths are `light` and `full`). An empty mask says
+  `(masked by FLOW.<context or harness>.md → <what happens>)`. Never leave a reader guessing what an empty key
   does.
 
 For `knowledge`, print the four roles resolved with who decided each: the `knowledge` key, or empty with its fallback (`search` → no lookups; `stage` → artifact only; `read_staging` → artifacts; `save` → `KNOWLEDGE.md`). A `domain_memory` section still in the file → one line: *"`domain_memory` is no longer read; name the tools you want under `knowledge`"* — it is retired configuration, not an error.
@@ -71,7 +75,7 @@ print one informational line: those values currently apply to every harness with
 override. This is valid configuration, not a warning and never a claim that a free-text model name
 is invalid.
 
-#### 1.5.2 Resolved models (only if either file has a `models` key)
+#### 1.5.2 Resolved models (only if any layer has a `models` key)
 
 Three keys, all about subagents. Print what each one actually reaches:
 
@@ -121,10 +125,23 @@ data.volumes         (none — duel ran schema-only)  2 works   last: query
 
 ### 1.5.4 Problems in the configuration files (flag, do not fix)
 
-Report problems, change nothing. Validate the base and active overlay separately, name the file
-that owns each problem, and ignore inactive overlays. An unknown root `FLOW.*.md` file gets one
-warning listing the supported harness names because no command will read it. **Scope: these files.**
-Whether the world they describe exists —
+Report problems, change nothing. Validate the base, the active context file and the active
+overlay separately, name the file that owns each problem, and ignore inactive overlays. Any other
+root `FLOW.<name>.md` is a context file this run did not select: list it once, as inactive, with the
+`FLOW_CONTEXT=<name>` that would select it and the six harness overlay names beside it — a
+misspelled overlay (`FLOW.cluade.md`) reads exactly like a context, and only the reader can tell —
+never as unknown, and its keys are not validated. Only a name the context rule refuses (flow-core
+§0) gets a warning, because nothing will ever read it.
+- **A context file git would swallow**: run `git check-ignore -v --no-index FLOW.flow-probe.md` at
+  the repo root — a name no repo tracks, so a context file that was force-added does not hide the
+  rule, and `--no-index` asks the ignore rules rather than the index. It prints a rule that does not
+  start with `!` → one warning naming that rule and its file (`.gitignore`, `.git/info/exclude`, a
+  global excludes file): a `FLOW.*.md` written by an older `/flow-init` hides every new context file
+  from `git add`, and the run that needs it reports it `not found` somewhere else, long after.
+  Replace the glob with the names `/flow-init` §5 lists. A `!` rule, or nothing printed → no
+  warning.
+
+**Scope: these files.** Whether the world they describe exists —
 CLIs installed *and authenticated*, agents discoverable, hooks executable, the MCP reachable, the
 base branch resolvable — is §2 below; flag the key here, check the world there, never both.
 
@@ -264,10 +281,11 @@ refuse) · **degraded** (it runs, quietly worse than the config promises), plus
 ## 3. Output
 
 §1.5 always prints — it is the answer to half the question. Start it with one line naming the files
-that produced the effective configuration (`FLOW.md + FLOW.codex.md`, `FLOW.md only`, active
-overlay only, or defaults only). **The checks are quiet on success**:
+that produced the effective configuration, in merge order and with the checkout each came from
+when it is not this one (`FLOW.md + FLOW.ci.md [FLOW_CONTEXT=ci] + FLOW.codex.md`, `FLOW.md only`,
+active overlay only, or defaults only), and the active context on the next line. **The checks are quiet on success**:
 one line per check that is *not* ok, grouped by the six areas above, plus a summary line. Close with
-`N effective keys set (O from overlay), M using fallbacks, K warnings` from §1.5 next to the
+`N effective keys set (C from the context layer, O from overlay), M using fallbacks, K warnings` from §1.5 next to the
 findings count.
 
 

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

@@ -31,8 +31,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`".)