flow-workflows 0.93.0 → 0.94.0

package/README.md

@@ -204,8 +204,8 @@ Artifacts are **hand-editable**: rewrite `03-design.md` and the next phase respe
 
 `FLOW.md` at the repo root is the shared base. `FLOW.claude.md`, `FLOW.codex.md`,
 `FLOW.opencode.md`, `FLOW.gemini.md`, `FLOW.hermes.md`, or `FLOW.zcode.md` can sparsely override values for the product executing the
-command. Existing repos with only `FLOW.md` behave exactly as before; anything effectively empty
-is auto-detected or asked for.
+command. An optional `FLOW.<context>.md`, selected by `FLOW_CONTEXT=<name>` in the environment, sits between the two: a layer the repo commits for where flow runs (CI, a server, an orchestrator). Existing repos with only `FLOW.md` behave exactly as
+before; anything effectively empty is auto-detected or asked for.
 
 | Section | What it configures |
 |---|---|
@@ -222,8 +222,8 @@ is auto-detected or asked for.
 | `observability` | The profile `/flow:work:watch` monitors after a deploy |
 
 `/flow:init` writes a compact base and creates the active overlay only when it has a
-harness-specific value. It offers to git-ignore `/FLOW.md`, `/FLOW.*.md`, and `.claude/work/`.
-Both files are personal config, not team config
+harness-specific value. It offers to git-ignore `/FLOW.md`, each harness overlay by name, and
+`.claude/work/`. The base and overlays are personal config, not team config
 ([why](docs/PHILOSOPHY.md#personal-config-not-team-config)). Resolution and examples:
 [CONFIGURATION](docs/CONFIGURATION.md#harness-overlays).
 

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.93.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
@@ -25,10 +25,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,
@@ -38,24 +42,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
@@ -68,16 +95,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:
@@ -102,7 +130,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
@@ -1080,7 +1111,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/codex/skills/flow-bug-validate/SKILL.md

@@ -37,7 +37,7 @@ Read `~/.claude/flow/CORE.codex.md` first (shared rules: `FLOW.md` step 0, model
 
 **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/codex/skills/flow-doctor/SKILL.md

@@ -30,15 +30,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
@@ -52,14 +56,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.
@@ -73,7 +77,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:
 
@@ -123,10 +127,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.
 
@@ -266,10 +283,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/codex/skills/flow-feat-design/SKILL.md

@@ -103,8 +103,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.

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

@@ -533,7 +533,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/codex/skills/flow-feat-start/SKILL.md

@@ -50,7 +50,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/codex/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/codex/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/codex/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/codex/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.
@@ -248,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/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.93.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
@@ -1079,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/gemini/commands/flow/bug/validate.toml

@@ -33,7 +33,7 @@ Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, mode
 
 **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.