flow-workflows 0.69.0 → 0.71.0

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

@@ -14,7 +14,7 @@ prompt = """
 > - `/model <value>` → the `--model` flag at launch.
 > - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared under `mcpServers` in `settings.json` (see `settings.snippet.json`).
 
-Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, `panel.json`, `00-summary.md`) — skip if you already read it in this session. **Models: the subagents it launches take `models.agents`.**
+Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session. **Models: the subagents it launches take `models.agents`.**
 
 Implementation phase. Code is written here.
 
@@ -55,7 +55,7 @@ Rules for writing it:
 
 **Ask the user with `AskUserQuestion`** whether the brief reflects what they expect — **hard gate, in every autonomy mode, `auto` included**: it is the last point where scope can be corrected before there is a diff to argue with.
 
-In `guided`/`auto` this is one of the only two stops per MR/PR, so it carries the **full stop header** (flow-core §3) — ticket, size, phase, `MR #<n> of <N>`, plan state — followed by the brief. Options:
+In `auto` this is one of the only two stops per MR/PR (`guided` adds the plan of §2.0ter on a big one), so it carries the **full stop header** (flow-core §3) — ticket, size, phase, `MR #<n> of <N>`, plan state — followed by the brief. Options:
 - **Yes, proceed** → start building.
 - **No, something is extra or missing** → the user clarifies, adjust the brief, ask again. **Do not touch code** until the brief is confirmed.
 
@@ -80,7 +80,36 @@ Hard rules:
 - **If there is a "Pattern deviation" section**: copy it too — it reminds you at coding time not to mimic the repo pattern.
 - **If the design says "none"** (no external surfaces), skip this step and record: "## Contracts to respect — none declared in design".
 
-Without this copy, do not proceed to §2.1.
+Without this copy, do not proceed to §2.0ter.
+
+## 2.0ter Plan this MR/PR (size-gated)
+
+`03-design.md` §"Implementation plan (order)" is the **feature's** order, written before `/flow:feat:plan` split anything — it does not know which of its steps belong to this MR/PR. The brief above says what this MR/PR delivers in business terms; neither says which files are touched in which order. On a MR/PR big enough to lose its thread, that plan is written here.
+
+**Gate — run this step only when the current `mrs[]` entry is big enough**: `lines_est > 150` **or** `files_est > 5`. No estimates in the entry (an older plan) → fall back to its `size`: `M`/`L` run it, `XS`/`S` skip. No `mrs[]` at all (XS/S, single MR/PR) → skip; the brief and the contracts are the whole plan, and a 30-line change does not earn a planning round. Skipped → record one line in `05-implementation.md` — the estimates that let it through (`plan: skipped — 40 lines / 2 files`), or `plan: skipped — single MR/PR` when there is no entry to read — and go to §2.1.
+
+Write it against `03-design.md` and the contracts just copied — **no code yet, no exploratory edits**. Under 250 words, as numbered steps:
+
+```markdown
+## Plan MR/PR #N
+1. <step> — `<file or path>` — <test that proves it, or "covered by step M">
+2. …
+
+- **Point of no return**: <the migration, contract, published event or flag after which rollback stops being a revert — or "none">.
+- **Out of this plan**: <what belongs to a later MR/PR and will be tempting while inside these files>.
+```
+
+Rules for the steps:
+- **A step is a thing on disk**, not a phase of thought: "add the nullable column + migration", not "analyse the schema". A step nobody can tell is finished is two steps or none.
+- **Order by what unblocks what**, and put the point of no return as late as the design allows: everything reversible lands before it.
+- **Every step names its test** or the step that covers it. A step that proves no acceptance criterion and guards no contract is a candidate to cut — same bar as `03-design.md` §"Planned tests".
+- Steps come from the **design**, not from the repo you are about to open. A step the design never mentions is either a deviation to log (§3 "Deviations from design") or scope that belongs in §2.4.
+
+**Present it, then behave by mode:**
+- `manual` / `guided` → **stop**: full stop header (flow-core §3), the plan, and one `AskUserQuestion` — **Approve and build** · **Change the order or the steps** (the user edits, rewrite it, ask again). This is a genuine decision point: the order of an irreversible step is exactly what is expensive to argue with once there is a diff.
+- `auto` → **do not stop**. Print the numbered steps and the point of no return, record the plan as accepted, and open the same message with the call that starts §2.1 (flow-core §3: a report is never the last thing in a turn you meant to continue).
+
+Save it in `05-implementation.md` under `## Plan MR/PR #N`, right after the brief. It is what seeds `TaskCreate` in §2.1, and what a §2.3 hot cut splits: the steps already done stay in this MR/PR, the ones still pending move to the new entry.
 
 ## 2.1 Work
 
@@ -111,7 +140,7 @@ Execution mode:
   - **Give it a bounded first step.** A piece with no natural first move ("do the whole module") produces nothing for hours; split it by file or by numbered step until it has one.
   - **Check the round at every stop of this command**, not only at the end: an agent past `agents.stall_after_minutes` (empty → 25) with nothing written to its path is stopped, split in two and relaunched.
 
-Use `TaskCreate` to track the steps from the design's implementation plan. Mark each step `in_progress` when starting and `completed` when done — do not batch.
+Use `TaskCreate` to track the steps of the **§2.0ter plan for this MR/PR** — one task per numbered step, same order. Step skipped there (small MR/PR) → seed from `03-design.md` §"Implementation plan (order)", taking only the steps this MR/PR covers per `04-mr-plan.md`; the feature's plan predates the split and carries steps that belong to siblings. Mark each step `in_progress` when starting and `completed` when done — do not batch.
 
 ### 2.1bis The premise this change rests on (any size, XS included)
 
@@ -217,7 +246,7 @@ Warning thresholds:
 
 If either is exceeded, **pause** and ask the user with `AskUserQuestion` (options, in this order):
 
-1. **Cut here (recommended if the current piece is coherent)**. What is built so far stays as this MR/PR; what remains of the plan goes into a new one inserted in `meta.json.mrs` right after. Zero code wasted.
+1. **Cut here (recommended if the current piece is coherent)**. What is built so far stays as this MR/PR; what remains — the §2.0ter steps still pending, or what is left of `04-mr-plan.md` where that step was skipped — goes into a new one inserted in `meta.json.mrs` right after. Zero code wasted.
 2. **Continue and record the overrun**. When the cut would be artificial. Note the deviation in `05-implementation.md` to calibrate `/flow:feat:plan` on future tickets.
 3. **Reopen plan**. Return to `/flow:feat:plan` to rethink the entire split. Only if the overrun shows the plan is wrong at a deeper level, not just that this MR/PR is slightly underestimated.
 
@@ -265,6 +294,9 @@ Keep `.claude/work/<TICKET>/05-implementation.md` updated as you work (not at th
 **This MR/PR does NOT include**:
 - <pieces that are out of scope>
 
+## Plan MR/PR #N
+<the numbered steps of §2.0ter, its point of no return and its "out of this plan" line — or one line saying the step was skipped and why (`plan: skipped — 40 lines / 2 files`). What §2.1 seeds `TaskCreate` from and what a §2.3 cut splits. Steps are struck through or annotated as they are reworked, never deleted: a plan edited to match what happened records nothing.>
+
 ## Changes per file
 - <file> — what changed and why (1 line each)
 
@@ -356,6 +388,6 @@ If there were no copied contracts (design said "none"), skip this step and recor
 - Update `meta.json`: `phase = "build"`, add to `phases_done`.
 - Multi-MR/PR build: leave the current MR/PR `in_progress` in `meta.json.mrs` (it becomes `merged` when `/flow:feat:ship` confirms the merge). **Also add `build` to that MR/PR's own `phases_done`** (its `mrs[]` entry) — the per-MR/PR marker the downstream gates read.
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5).
-- Report **following the stop header** (flow-core §3) **only when this is a stop** — `manual`, or a blocker in any mode. Then in bullets: files touched (high level), pending items, **result of §4.2 (contracts verified)**, and **any premise left unsettled by §2.1bis** — one line, in the language of what breaks if it is false. An open premise the user never hears about is an assumption they were not asked about. In `guided`/`auto` `/flow:feat:review` runs in this same turn, so there is no report here: those same points go to the phase artifact, `panel.json` carries `Now`/`Next`, and the turn opens with the call that chains.
+- Report **following the stop header** (flow-core §3) **only when this is a stop** — `manual`, or a blocker in any mode. Then in bullets: files touched (high level), pending items, **result of §4.2 (contracts verified)**, and **any premise left unsettled by §2.1bis** — one line, in the language of what breaks if it is false. An open premise the user never hears about is an assumption they were not asked about. In `guided`/`auto` `/flow:feat:review` runs in this same turn, so there is no report here: those same points go to the phase artifact, the panel carries `Now`/`Next`, and the turn opens with the call that chains.
 - **Autonomy handoff.** The summary is a report, not the end of the flow. `manual`: stop and propose `/flow:feat:review` with a single `AskUserQuestion` (recommended option by default); invoke it only on confirmation, never make the user type it. `guided`/`auto`: **chain into `/flow:feat:review` automatically** in this same turn, without asking — never end the turn with the next command as a suggestion.
 """

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

@@ -14,7 +14,7 @@ prompt = """
 > - `/model <value>` → the `--model` flag at launch.
 > - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared under `mcpServers` in `settings.json` (see `settings.snippet.json`).
 
-Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, `panel.json`, `00-summary.md`) — skip if you already read it in this session. **Models: the subagents it launches take `models.agents`; its parallel rounds take `models.workers`.**
+Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session. **Models: the subagents it launches take `models.agents`; its parallel rounds take `models.workers`.**
 
 Technical design phase. **Still no production code is written.** Opens the option space first (M/L), then designs the approach that was chosen. Output: a plan the next step executes.
 

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

@@ -14,7 +14,7 @@ prompt = """
 > - `/model <value>` → the `--model` flag at launch.
 > - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared under `mcpServers` in `settings.json` (see `settings.snippet.json`).
 
-Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, `panel.json`, `00-summary.md`) — skip if you already read it in this session. **Models: the subagents it launches take `models.agents`.**
+Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session. **Models: the subagents it launches take `models.agents`.**
 
 Delivery planning phase. **No code is written.** Splits the feature into MRs/PRs that can each live on the main branch even if the subsequent ones never land.
 
@@ -148,7 +148,7 @@ A slice landing in **another repo** is not one of *this* repo's `mrs`: record it
 
 - Update `meta.json`: `phase = "plan"`, add `plan` to `phases_done`.
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5).
-- Refresh `panel.json`: from here on it carries one line per `mrs[]` entry. Nothing is merged or open yet, so every entry carries `mark: "pending"`, the not-yet-started ones collapsed into a single `#a–#z` line, and **no heading over the train** — `mark` states each entry's real state (schema in `/flow:work:README`).
+- Refresh the panel — a new train is a new *shape*, so republish it whole (flow-core §4): from here on it carries one line per `mrs[]` entry. Nothing is merged or open yet, so every entry carries `mark: "pending"`, the not-yet-started ones collapsed into a single `#a–#z` line, and **no heading over the train** — `mark` states each entry's real state (schema in `/flow:work:README`).
 - **Show the plan the way it will be executed**, not just as a list: print the wave line first, then the table:
 
   ```

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

@@ -14,7 +14,7 @@ prompt = """
 > - `/model <value>` → the `--model` flag at launch.
 > - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared under `mcpServers` in `settings.json` (see `settings.snippet.json`).
 
-Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, `panel.json`, `00-summary.md`) — skip if you already read it in this session. **Models: the subagents it launches take `models.agents`; its parallel rounds take `models.workers`.**
+Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session. **Models: the subagents it launches take `models.agents`; its parallel rounds take `models.workers`.**
 
 Mandatory review phase. **`/flow:feat:ship` cannot run without passing through here and resolving blockers.**
 

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

@@ -14,7 +14,7 @@ prompt = """
 > - `/model <value>` → the `--model` flag at launch.
 > - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared under `mcpServers` in `settings.json` (see `settings.snippet.json`).
 
-Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, `panel.json`, `00-summary.md`) — skip if you already read it in this session. **Models: this command runs with the model it was launched with; the wait it delegates takes `models.supervisors`.**
+Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session. **Models: this command runs with the model it was launched with; the wait it delegates takes `models.supervisors`.**
 
 Closes the feature: commit, push, MR/PR (assigned per `git.assignee`, squash per `git.squash`, sections per `git.request_sections`) and an optional offer to consolidate knowledge.
 
@@ -175,7 +175,7 @@ Only here — with the content approved in §3 — invoke `Skill commit-commands
 - `git.assignee` not empty → assign to that user. `git.squash` `true` → enable squash-before-merge.
 - `commit-push-pr` skill unavailable → commit and push manually and create the MR/PR with the `git.cli` CLI from `FLOW.md` — always with the content confirmed in §3.
 
-**Record the URL the moment it exists**: write it into this MR/PR's `meta.json.mrs` entry and refresh `panel.json` right here, before §4.2 and before anything else can fail.
+**Record the URL the moment it exists**: write it into this MR/PR's `meta.json.mrs` entry and refresh the panel (flow-core §4) right here, before §4.2 and before anything else can fail.
 
 **The push just started a pipeline, and this thread does not sit on it.** Its result belongs to `/flow:work:green`, not here, so either close the ship with CI reported as *running* — the honest state — or, when the user wants to hear how it ended, delegate the wait as any other (flow-core §6.5): one supervisor subagent on `models.supervisors`, a deadline, and back with status plus failing-job evidence. Whatever it returns, a red pipeline is triaged by `/flow:work:green`; this command never fixes CI and never closes reporting a green it did not see.
 
@@ -268,7 +268,7 @@ In every scenario:
   ```
 
   Nothing back → the content is **not** on the base whatever the forge says (see §6.2.1). Do not mark the entry `merged`: leave it `in_progress` with a `note`, tell the user in one line, and recover it with a fresh MR/PR against `git.default_base` before the train moves on.
-- Refresh `panel.json` from the updated `meta.json`. A shipped-but-open MR/PR is a `wait` line carrying its `link`; it becomes `done` only when confirmed merged. When this ship sets `phase = "done"`, say so in plain words (`mark: "info"` with `style: "ok"`: nothing left here) and drop the `Decision` line.
+- Refresh the panel from the updated `meta.json`. A shipped-but-open MR/PR is a `wait` line carrying its `link`; it becomes `done` only when confirmed merged. When this ship sets `phase = "done"`, say so in plain words (`mark: "info"` with `style: "ok"`: nothing left here) and drop the `Decision` line.
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5).
 
 ### 6.1.1 Tracker: move to done

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

@@ -14,7 +14,7 @@ prompt = """
 > - `/model <value>` → the `--model` flag at launch.
 > - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared under `mcpServers` in `settings.json` (see `settings.snippet.json`).
 
-Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, `panel.json`, `00-summary.md`) — skip if you already read it in this session. **Models: this command runs with the model it was launched with (no `models` key).**
+Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session. **Models: this command runs with the model it was launched with (no `models` key).**
 
 `{{args}}` is **optional**:
 
@@ -231,9 +231,9 @@ Create the work directory per §1: `.claude/work/<TICKET>-<slug>/` (ticket mode)
 - `related_repos` from §3.5 — one `{ "repo": "<name>", "scope": "<one line>", "status": "pending", "contract_handoff": "pending" | "none" }` per *other* repo; `[]` for a single-repo task.
 - **This work *is* an accepted follow-up** (the ticket came from another work's `followups[]`, flow-core §7) → set `origin: { "work": "<originating work dir>", "followup": "F<n>" }`, carry that entry's recorded `why` into `01-context.md` verbatim instead of re-deriving it, and set the originating entry to `in_progress` with `work` naming this folder. Not a follow-up → omit `origin` entirely.
 
-### `panel.json`
+### Live panel
 
-Write it now, next to `meta.json`, in the flow-core §4 shape. No train yet (`plan` has not run), so: the title (`style: title`), a `Now` line for what is starting, a `Next` line for the phase this size routes to, any §3.5 sibling repo as a `block` line. Every later phase overwrites it whole.
+Publish it now, in the flow-core §4 shape and by the transport that section selects. No train yet (`plan` has not run), so: the title (`style: title`), a `Now` line for what is starting, a `Next` line for the phase this size routes to, any §3.5 sibling repo as a `block` line. Every later phase updates it.
 
 ### `00-summary.md`
 
@@ -281,6 +281,6 @@ Run `tracker.start_cmd` with `{TICKET}` = `meta.json.ticket`, `{ASSIGNEE}` = `tr
 ## 7. Close
 
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5) — first written in §6; refresh it if §6.5 changed anything.
-- Report **following the stop header** (flow-core §3), branch added, body 2-3 lines: ticket, size, branch; recommended next command per the §4 table — in `guided`/`auto` you run it in this same turn, so there is no report and no question here: update `panel.json` and chain (flow-core §3).
+- Report **following the stop header** (flow-core §3), branch added, body 2-3 lines: ticket, size, branch; recommended next command per the §4 table — in `guided`/`auto` you run it in this same turn, so there is no report and no question here: update the panel and chain (flow-core §3).
 - Apply `autonomy.mode`: `manual` → stop and let the user invoke the recommended command; `guided`/`auto` → chain into it, subject to the hard gates (the §5 branch-base ambiguity already stops on its own).
 """

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

@@ -14,7 +14,7 @@ prompt = """
 > - `/model <value>` → the `--model` flag at launch.
 > - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared under `mcpServers` in `settings.json` (see `settings.snippet.json`).
 
-Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, `panel.json`, `00-summary.md`) — skip if you already read it in this session. **Models: the subagents it launches take `models.agents`; the wait it delegates takes `models.supervisors`.**
+Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session. **Models: the subagents it launches take `models.agents`; the wait it delegates takes `models.supervisors`.**
 
 Verify the feature is complete: test coverage, edge cases, performance, regressions.
 

package/adapters/gemini/commands/flow/next.toml

@@ -48,5 +48,5 @@ runs a phase on its own and never advances `meta.json`.
 ## 3. Hand over
 
 Invoke the confirmed command with the arguments the user chose. Nothing to write, no
-artifact, no `panel.json`: the command it hands to owns the rest.
+artifact, no panel: the command it hands to owns the rest.
 """

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

@@ -33,9 +33,9 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 ## Principles
 
 - **Shared rules live in the `flow-core` skill** (`skills/flow-core/SKILL.md`): configuration merge,
-  `models`, autonomy and hard gates, never-a-question list, stop header, `panel.json`,
+  `models`, autonomy and hard gates, never-a-question list, stop header, the live panel,
   `00-summary.md`. Every command loads it once per session.
-- **One folder per ticket**: `.claude/work/{TICKET}/` holds `meta.json`, `00-summary.md`, `panel.json` and the numbered markdown artifacts.
+- **One folder per ticket**: `.claude/work/{TICKET}/` holds `meta.json`, `00-summary.md`, the numbered markdown artifacts and — where the terminal offers no panel tools — `panel.json`.
 - **Numbered artifacts**: each phase writes a `NN-phase.md` that the next step reads.
 - **`evidence/`**: what `/flow:*:validate` actually observed when it drove the running app — a screenshot, a response body, a log excerpt, one file per criterion, with a **before** where the change alters something already visible. `/flow:*:ship` attaches it to the MR/PR description. `quality.evidence: off` disables both halves.
 - **`meta.json` is the source of truth** for state (current phase, size, branch). Without it, commands refuse to continue.
@@ -60,7 +60,7 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - **Commits follow the autonomy mode** (`/flow:feat:build` §2.2, `/flow:bug:fix` §2.1): changes **always reported before anything is recorded**. `manual`: **no `git commit` on its own**. `guided`: asks **once**. `auto`: WIP commit per step, cut by step (§2.3) — **`autonomy.mode: auto` plus typing the command is the explicit authorization**. WIP commits on the work branch **only**; push and MR/PR creation stay hard gates in every mode.
 - **A named next command is not a handoff**: each `## Close` carries the **autonomy handoff** — `manual` proposes the next command with one `AskUserQuestion`; `guided`/`auto` **chain in the same turn**. Never chained: `ship` (hard gate in every mode) and anything downstream of a red gate.
 - **Every stop opens with where you are** (flow-core §3): stop header, then ≤ ~10 product-altitude lines. Own process → the artifact; subagent notifications never earn a turn.
-- **The stop is also written to disk**: `.claude/work/<work>/panel.json` ([schema below](#paneljson-schema), flow-core §4), **overwritten whole, never patched**, written **before** a long stretch with an honest `updated_at`.
+- **The stop is also published to the live panel** ([document below](#the-panel-document), flow-core §4): through the terminal's `panel_set` / `panel_patch` tools where they exist, and `.claude/work/<work>/panel.json` **overwritten whole, never patched** where they do not. Published **before** a long stretch, never after, with an honest `updated_at`.
 - **What is never a question is as binding as what always is**: hard gates stop in **every** mode; in `guided`/`auto` flow mechanics, WIP commits, the train's next MR/PR, size confirmation and anything already decided are never asked (flow-core §2). Only new evidence reopens a decision.
 - **A correction is a convention, and a convention is written down**: when the user overrides something a phase proposed and the same correction would apply to an unrelated ticket in this repo, it becomes a `meta.json.conventions_candidates[]` row and a `## Conventions learned` line in the phase artifact, asking nothing (flow-core §8). `review`'s idiom audit reads them in the same work; `ship` offers them to `FLOW.md` once, at Close, in every mode. What is about *this* ticket stays in the artifact and goes no further.
 - **Work you decide not to do is recorded, not narrated**: every "idea for a separate ticket", out-of-scope piece, unmitigated risk, unchecked edge case and prevention action becomes a `meta.json.followups[]` entry (flow-core §7) alongside its artifact section. Written without asking, and only when it clears the bar of §7 (a named subject, a path someone has actually seen, waiting costing more than doing it). Triaged **once** at `ship`'s Close, behind a skeptic: 3 or more candidates go to an agent whose job is to refute that each deserves a ticket, and only the strongest `tracker.followup_ask_max` (empty → **2**) become questions (**Do it** / **Not worth it** / **Later**). The rest are logged. Published in the MR/PR description while still open, and surfaced by `status`/`daily`/`next` — from `_archive/` too — until decided. Creating the tracker issue for an accepted one is outward-facing: **asks in every mode**. Two kinds are not deferred work: a **`decision`** the diff depends on is asked when it surfaces (in every mode) and only a deferred one is recorded; a **`tooling`** gap is recorded with no question at all and never goes to the tracker.
@@ -153,9 +153,9 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 
 **`00-summary.md`** (flow-core §5): **≤ 15 lines, overwritten whole at every `## Close`**, read first by every phase (with `meta.json`) before any full artifact. Contents: what the work is (one line), size and current MR/PR, standing decisions (one line each), contracts declared or received (names and where the literal shape lives), what is pending, what the next phase must open in full. Missing (older work) → read the artifacts, write it at Close.
 
-## `panel.json` schema
+## The panel document
 
-`meta.json` is the *state machine*; `panel.json` is the *view* a reader outside the chat polls. Optional: a work that never writes it still resolves from `meta.json` alone. Writer rules (order, when, ceiling): flow-core §4.
+`meta.json` is the *state machine*; the panel is the *view* a reader outside the chat watches. Optional: a work that never publishes it still resolves from `meta.json` alone. Writer rules (order, when, ceiling) and the two transports — the terminal's `panel_set` / `panel_patch` / `panel_get` tools, or `.claude/work/<work>/panel.json` — are flow-core §4. The document below is the same either way.
 
 ```json
 {
@@ -186,11 +186,13 @@ This system **orchestrates** the project's existing sub-agents and skills (it do
 - **`style`** — `normal` · `dim` · `title` · `accent` · `ok` · `warn` · `error`; semantic names, the reader owns the palette.
 - **`header`** — `true` (default): the reader draws ticket, type, phase and age, which never belong in `lines`. `false` hands every line to the writer.
 - **`phase`** — the phase running **right now** (`meta.json.phase` advances only at close); the reader prefers it.
-- **`updated_at`** — local ISO-8601 with offset from the real clock, never carried over; lets the reader flag a stale snapshot.
+- **`updated_at`** — local ISO-8601 with offset from the real clock, never carried over; lets the reader flag a stale snapshot. Over the tools the app stamps each delivery itself.
+- **`attention`** *(tools only)* — `wait` · `block` · `done`, beside `phase`, absent while simply working: the pane's claim on the user's attention, which the app never deduces from a line's `mark`. A tab's card shows the strongest claim among its panes, so an uncleared `wait` flags that tab for ever.
+- **`key`** *(tools only)* — a unique, never-painted name on any line a later `panel_patch` may replace or delete (`title`, `mr-1`, `now`, `next`, `decision`, `block-1`).
 
 **No headings over the train.** A shipped MR/PR is *open, waiting to merge*; `mark` says it per entry — `wait` shipped, `current` being worked, `done` only merged.
 
-**Who writes it.** The 18 phase commands (flow-core §4); `/flow:feat:ship` and `/flow:bug:ship` the instant an MR/PR URL exists; `/flow:feat:plan` when the train is populated; `/flow:work:resume` (§5); `/flow:work:watch` every cycle; `/flow:work:abandon` with a terminal state. Read-only `status`, `daily`, `config`, `doctor`, `news` never write it; `/flow:work:clean` archives the folder with the panel inside.
+**Who publishes it.** The 18 phase commands (flow-core §4); `/flow:feat:ship` and `/flow:bug:ship` the instant an MR/PR URL exists; `/flow:feat:plan` when the train is populated — a new train is a new shape, so a full republish; `/flow:work:resume` (§5), after reading what is on screen; `/flow:work:watch` every cycle; `/flow:work:abandon` with a terminal state. Read-only `status`, `daily`, `config`, `doctor`, `news` never publish; `/flow:work:clean` archives the folder with any panel file inside.
 
 ## Shortcuts by size
 

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

@@ -14,7 +14,7 @@ prompt = """
 > - `/model <value>` → the `--model` flag at launch.
 > - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared under `mcpServers` in `settings.json` (see `settings.snippet.json`).
 
-Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, autonomy, how a stop reads, `panel.json`, `00-summary.md`) — skip if you already read it in this session.
+Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, autonomy, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session.
 
 Clean closure for works that will not reach the base branch: a feature discarded after `design`, a bug that is not one (expected behavior, external problem, user misconfiguration), a work absorbed by another ticket.
 
@@ -87,7 +87,7 @@ Ask the user what to do with the branch — do not decide alone:
 - Update `meta.json`: `phase = "abandoned"`; `phases_done` not touched (it reflects what was actually done); `notes` += abandonment reason; `updated_at` updated.
 - Overwrite `00-summary.md` whole (≤15 lines, flow-core §5).
 - **Tracker: move to won't-do** (never "done" — this work did not ship). Only if `tracker.tool` is not `none`/empty, `tracker.abandon_cmd` is set, and `meta.json.ticket` is a **real tracker id** (skip for local-only slugs). Run `tracker.abandon_cmd` substituting `{TICKET}` = `meta.json.ticket`. Same contract as `/flow:feat:start §6.5`: **best-effort, idempotent, gated** (ask once in `autonomy.mode: manual`; automatic in `guided`/`auto`); failure or already-in-state ticket → warn and continue, never block. `tracker.abandon_cmd` empty → do nothing (the user closes the ticket by hand if they want).
-- `panel.json` present (`/flow:work:README`) → overwrite with a terminal state before archiving: the title, one `block` line saying the work was abandoned and why, no `Decision` line.
+- Panel published for this work (flow-core §4) → publish a terminal state before archiving: the title, one `block` line saying the work was abandoned and why, no `Decision` line, and `attention` cleared where the panel tools carry it — nothing is waiting on anyone any more.
 - Move the folder to `.claude/work/_archive/` **keeping its directory name** (`_archive/<work-dir>/`, the folder located in §1 — e.g. `<TICKET>-<slug>`) so `/flow:work:status` no longer lists it.
 - Report to the user: ticket abandoned, reason, what was done with the branch.
 

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

@@ -14,7 +14,7 @@ prompt = """
 > - `/model <value>` → the `--model` flag at launch.
 > - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared under `mcpServers` in `settings.json` (see `settings.snippet.json`).
 
-Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, autonomy, how a stop reads, `panel.json`, `00-summary.md`) — skip if you already read it in this session.
+Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, autonomy, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session.
 
 The forge (`git.cli`) is **best-effort**: CLI missing, unauthenticated, or over ~5s → fall back to the local evidence in §4 and say so in one line; never block.
 

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

@@ -14,7 +14,7 @@ prompt = """
 > - `/model <value>` → the `--model` flag at launch.
 > - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared under `mcpServers` in `settings.json` (see `settings.snippet.json`).
 
-Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, autonomy, how a stop reads, `panel.json`, `00-summary.md`) — skip if you already read it in this session.
+Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, autonomy, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session.
 
 External sources (tracker, forge, `knowledge`) are all **best-effort**: a CLI missing/unauthenticated, an MCP failing, or a call over ~3s → continue without that source and note it in a single line; **never block**.
 

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

@@ -28,7 +28,7 @@ Usage: `/flow:work:green [mr-iid-or-url]` — optional; default is the MR/PR of
 
 Extract from `git`: `host`, `cli` (empty → the default for that host), `default_base`. The term MR/PR follows `host`. From `tracker`: `tool`, `prefix`. From `quality`: `test`, `test_one`, `static_analysis`, `style_fix` (local reproduce/verify commands, §5; empty → auto-discover from Makefile / npm / composer scripts), `review_skill` (§5, non-trivial fixes). `agents`: expert sub-agents to delegate fixes to. `knowledge.search` set → `knowledge.search` in §3.
 
-Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, `panel.json`, `00-summary.md`) — skip if you already read it in this session. **Models: the subagents it launches take `models.agents`; the wait it delegates takes `models.supervisors`.**
+Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session. **Models: the subagents it launches take `models.agents`; the wait it delegates takes `models.supervisors`.**
 
 **Autonomy.** Modes as in flow-core §2; `guided`/`auto` record their choices in `09-ci.md` (e.g. a pure formatter auto-fix). **Hard gates — ALWAYS stop and ask, in every mode, no exceptions:**
 1. **Any push** (§6).

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

@@ -14,7 +14,7 @@ prompt = """
 > - `/model <value>` → the `--model` flag at launch.
 > - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared under `mcpServers` in `settings.json` (see `settings.snippet.json`).
 
-Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, `panel.json`, `00-summary.md`) — skip if you already read it in this session. **Models: the subagents it launches take `models.agents`; its parallel rounds take `models.workers`.**
+Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session. **Models: the subagents it launches take `models.agents`; its parallel rounds take `models.workers`.**
 
 **A query is approved by its plan, not by prose.** Fact sheet → challenger attacks → each point settled with a **plan or a number**. **Cross-cutting** (feat or bug), **repeatable**, does **not** advance `meta.json.phase`; runs with or without a work folder.
 

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

@@ -24,7 +24,7 @@ Cross-cutting (`feat` or `bug` MR/PR alike), repeatable (one invocation per revi
 
 Extract from `git`: `host`, `cli` (empty → the default for that host), `assignee`. The term MR/PR follows `host`. From `tracker`: `tool` and `prefix`. From `quality`: `review_skill` (§6, non-trivial rounds). If `knowledge.search` is set, `knowledge.search` runs in §3.
 
-Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, `panel.json`, `00-summary.md`) — skip if you already read it in this session. **Models: this command runs with the model it was launched with (no `models` key).**
+Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session. **Models: this command runs with the model it was launched with (no `models` key).**
 
 **Autonomy.** Modes as in flow-core §2 (`autonomy.mode`: `manual` | `guided` | `auto`; empty = `manual`); `guided`/`auto` record their choices in `08-feedback.md`. **Hard gates — ALWAYS stop and ask, in every mode, no exceptions:**
 1. **Posting any comment/reply** to the MR/PR (§7).

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

@@ -14,7 +14,7 @@ prompt = """
 > - `/model <value>` → the `--model` flag at launch.
 > - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared under `mcpServers` in `settings.json` (see `settings.snippet.json`).
 
-Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, autonomy, how a stop reads, `panel.json`, `00-summary.md`) — skip if you already read it in this session.
+Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, autonomy, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session.
 
 Use when returning to a work after a break (next morning, another session).
 
@@ -88,7 +88,7 @@ With what is new (there is already work on disk):
 
 ## 5. Rebuild the live panel
 
-After a break `.claude/work/<work>/panel.json` is most likely stale. Overwrite it **whole** from the state just rebuilt (`meta.json`, git, the ticket) — rules in flow-core §4:
+After a break the panel is most likely stale, and a resumed session is exactly where flow-core §4 asks for `panel_get` **before** publishing: read what is on screen, then publish the whole document from the state just rebuilt (`meta.json`, git, the ticket) — `panel_set` where the terminal offers the panel tools, `.claude/work/<work>/panel.json` overwritten whole where it does not:
 
 ```json
 {
@@ -116,5 +116,5 @@ After a break `.claude/work/<work>/panel.json` is most likely stale. Overwrite i
 - `Decision` marked `wait` is always set after a resume — nothing is running, the next move is the user's.
 - `block` lines for the blockers §4 surfaced (`contract_handoff` `pending` in a sibling repo, a red pipeline, an unmerged dependency).
 - Train: one entry per `meta.json.mrs[]`, not-started collapsed into one `#a–#z` line; omit without `mrs`.
-- `updated_at` from `date -Iseconds`; every fact from `meta.json` and the artifacts; language of the work's artifacts.
+- `updated_at` from `date -Iseconds` when the panel goes to the file; every fact from `meta.json` and the artifacts; language of the work's artifacts.
 """

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

@@ -14,7 +14,7 @@ prompt = """
 > - `/model <value>` → the `--model` flag at launch.
 > - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared under `mcpServers` in `settings.json` (see `settings.snippet.json`).
 
-Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, autonomy, how a stop reads, `panel.json`, `00-summary.md`) — skip if you already read it in this session.
+Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, autonomy, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session.
 
 Overview of works in progress; detects divergences between artifacts and actual git state.
 

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

@@ -14,7 +14,7 @@ prompt = """
 > - `/model <value>` → the `--model` flag at launch.
 > - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared under `mcpServers` in `settings.json` (see `settings.snippet.json`).
 
-Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, autonomy, how a stop reads, `panel.json`, `00-summary.md`) — skip if you already read it in this session.
+Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, autonomy, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session.
 
 Temporarily point the **main checkout** at another branch to test it against this checkout's live environment (running stack, DB, containers), then return — a generic `make wt-try`/`wt-back` pair. The git switch is built in; the project-specific re-sync (e.g. migrations) comes from `git.worktree_resync` in `FLOW.md`. Operates **in place**; never creates or touches worktrees.
 

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

@@ -14,7 +14,7 @@ prompt = """
 > - `/model <value>` → the `--model` flag at launch.
 > - `knowledge.*` roles → whatever tools `FLOW.md` names there; an MCP tool keeps its name, its server is declared under `mcpServers` in `settings.json` (see `settings.snippet.json`).
 
-Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, `panel.json`, `00-summary.md`) — skip if you already read it in this session. **Models: this command runs with the model it was launched with; the wait it delegates takes `models.supervisors`.**
+Read `~/.claude/flow/CORE.gemini.md` first (shared rules: `FLOW.md` step 0, models, autonomy modes and hard gates, how a stop reads, the live panel, `00-summary.md`) — skip if you already read it in this session. **Models: this command runs with the model it was launched with; the wait it delegates takes `models.supervisors`.**
 
 **Autopiloted post-deploy monitoring**: signals **scoped to the change** over a window (default 30 min), against a baseline; alert on errors or performance regressions from the deploy.
 
@@ -125,7 +125,7 @@ Over `[last cycle, now]`, scoped to the surface. **Default thresholds** (tunable
 
 After each cycle: update `monitor.md` (accumulated state — no repeated alerts, feeds the final summary) and **reschedule with `ScheduleWakeup`** (~270-300s, or the chosen interval) passing the same `/flow:work:watch {PREFIX}XXXXX` until `T_end`. Platform fails or slow → retry next cycle, never break.
 
-**Refresh the live panel every cycle** (only with a `<work-dir>` from §1). Overwrite `.claude/work/<work>/panel.json` **whole**:
+**Refresh the live panel every cycle** (only with a `<work-dir>` from §1), by the transport flow-core §4 selects — the panel tools where the terminal has them, `.claude/work/<work>/panel.json` overwritten **whole** where it does not:
 
 ```json
 {
@@ -166,7 +166,7 @@ Write the summary to `<work-dir>/monitor.md` (§1) and present it:
 - **Evidence strength**: low traffic (§4) → say it ("green, but the flow barely executed during the window: weak evidence"). Never sell a zero-traffic green as a guarantee.
 - **Honest limits**: no slow leaks, no regressions needing input not exercised in the window. A first-hour safety net.
 
-Final verdict to `panel.json` too — `mark: "info"` plus `style: ok|warn|error` for 🟢/🟡/🔴 — and a `Now` line reading `nothing — the watch window is over`. On 🔴, a `Decision` line marked `wait` pointing at `/flow:bug:start`.
+Final verdict to the panel too — `mark: "info"` plus `style: ok|warn|error` for 🟢/🟡/🔴 — and a `Now` line reading `nothing — the watch window is over`. On 🔴, a `Decision` line marked `wait` pointing at `/flow:bug:start`.
 
 `knowledge.stage` is set → `knowledge.stage` relevant findings (measured baselines, low-traffic signals, error patterns) for this branch's staging.
 

package/adapters/hermes/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.69.0`.** Compare it once, at the start of the session, against
+**This file belongs to flow `0.71.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
@@ -236,7 +236,7 @@ terminal by construction, the turn is over before you notice.
 - **The continuing call goes first.** When a step closes and the next one runs anyway
   (`guided`/`auto` chaining, §2), the turn opens with the call that starts it, not with prose about
   the one that ended. **A report is never the last thing in a turn you meant to continue.**
-- **Progress belongs to the panel, not to a turn.** Someone watching reads `panel.json` (§4):
+- **Progress belongs to the panel, not to a turn.** Someone watching reads the live panel (§4):
   `Now`, `Next`. Writing it costs no turn and no stop; saying it in chat costs both.
 - **Stopping? Then say so.** `I need:` names the decision or the action you are waiting on. It
   never announces that you are continuing — if you were, you would not be writing this header.
@@ -260,11 +260,19 @@ I need: <one line — the decision or action you are waiting on>
 - **Zero-context rule.** First mention of an identifier carries 4–6 words of what it is. Never cite a section number without naming what it is. No jargon the user has not used first.
 - **If it is a question, it is `AskUserQuestion`.** Never end a message with a question in prose. If it does not deserve the menu, it is a decision you take and record.
 
-## 4. Live panel — `panel.json`
+## 4. Live panel — over the terminal's MCP, or `panel.json`
 
-Whenever the state a panel would show changes, overwrite `.claude/work/<work>/panel.json`
-**whole** (never patch) from `meta.json` plus what you know right now. **Any progress line you were
-about to type into the chat is a panel write instead** (§3):
+Whenever the state a panel would show changes, publish the panel from `meta.json` plus what you know
+right now. **Any progress line you were about to type into the chat is a panel update instead**
+(§3).
+
+**Two transports, one document.** When the tools `panel_set` / `panel_patch` / `panel_get` are
+available, this console is a pane of agent-terminal: publish the panel through them (§4.2) and
+**stop writing `.claude/work/<work>/panel.json`** — while a pane is claimed, its file is not read at
+all. When the tools are not there, write the file exactly as before (§4.3). No work folder
+(lightweight `respond`/`green`) → nothing to publish, either way.
+
+### 4.1 The document — the same whichever transport carries it
 
 ```json
 {
@@ -290,11 +298,75 @@ about to type into the chat is a panel write instead** (§3):
 - **`mark` says what a line is**; the reader draws it. `done` · `current` (at most one) · `pending` · `wait` (waiting on someone else: an open MR/PR, a user decision) · `block` · `info`. Marked lines form an aligned column: symbol, `ref`, text, link pinned right. Do not set `style` on a marked line — except `mark: "info"` + `style: ok|warn|error` when the colour *is* the information (a monitoring verdict).
 - **`ref` need not be a number**: `#1`, `#3–#6`, `Now`, `Next`, `Decision`. Column width is per block; blocks are separated by blank lines — use them so the MR/PR train and the labels below do not drag each other wide.
 - **`link` is a field, never a URL inside `text`.**
-- **Order:** (1) work title (`style: title`, no mark); (2) the MR/PR train, one entry per `meta.json.mrs[]` with `ref` `#n`, short title, real-state `mark`, `link` when there is a URL — not-started entries collapse into one `#a–#z` `pending` line; omit the block without `mrs`; (3) `Now` — what is running, the one fact `meta.json` cannot hold; (4) `Next`; (5) `Decision`, `mark: wait`, **only** when parked on the user; (6) blockers, `mark: block` (a sibling repo with `contract_handoff: pending`, a red pipeline, an unmerged dependency).
-- **When:** (a) in pre-flight, as soon as `meta.json` is loaded; (b) immediately **before** every stop header; (c) **before** any long stretch (fan-out, full suite, CI poll) — never after, so a step that dies halfway is not shown as finished. When the stretch will outlast the ~30 min staleness warning, set `stale_after_minutes` to what it will really take; (d) wherever `## Close` updates `meta.json`.
-- **Rules:** `phase` is the phase you are **running now** (not `meta.json.phase`, which advances only at Close). `header: true` means ticket, type, phase and age are drawn by the reader — do not repeat them in `lines`. Keep it under ~14 lines. Every fact from `meta.json` and the artifacts — an invented MR/PR state is worse than a blank panel. `updated_at` from the real clock (`date -Iseconds`), never carried over. Write in the language of the work's artifacts. No work folder (lightweight `respond`/`green`) → nothing to write.
+- **Order:** (1) work title (`style: title`, no mark); (2) the MR/PR train, one entry per `meta.json.mrs[]` with `ref` `#n`, short title, real-state `mark`, `link` when there is a URL — not-started entries collapse into one `#a–#z` `pending` line; omit the block without `mrs`; (3) `Now` — what is running, the one fact `meta.json` cannot hold; (4) `Next`; (5) `Decision`, `mark: wait`, **only** when parked on the user — over the tools it travels with `attention: "wait"` (§4.2), and both are cleared together; (6) blockers, `mark: block` (a sibling repo with `contract_handoff: pending`, a red pipeline, an unmerged dependency).
+- **Rules:** `phase` is the phase you are **running now** (not `meta.json.phase`, which advances only at Close). `header: true` means ticket, type, phase and age are drawn by the reader — do not repeat them in `lines`. Keep it under ~14 lines. Every fact from `meta.json` and the artifacts — an invented MR/PR state is worse than a blank panel. Write in the language of the work's artifacts.
+
+### 4.2 Over the terminal's MCP — `panel_set` once, `panel_patch` from then on
+
+**The first publication of the session — `panel_set`.** `source: "flow"`. It claims the pane for as
+long as this session lives, and a second producer is refused by name. The document is the one §4.1
+specifies, plus two additions:
+
+- **`attention`, at the top level**, beside `phase`: `wait` when parked on the user, `block` when
+  stuck on somebody else (red pipeline, sibling repo's contract), `done` when the cycle closed and
+  nobody has looked. Absent while simply working. The app never deduces it: a `mark: "wait"` inside
+  `lines` is body text and claims nothing. The tab's card shows the strongest claim among its panes,
+  so a `wait` you forget to clear flags that tab for ever — clear it with
+  `{"op": "set", "field": "attention", "value": null}`.
+- **A `key` on every line you may want to change later** — `title`, `mr-1`, `now`, `next`,
+  `decision`, `block-1`. It is never painted, and it must be unique: a key that names two lines
+  refuses every patch addressing it.
+
+**Everything after that is `panel_patch`:**
+
+```json
+{"ops": [
+  {"op": "replace", "key": "now",
+   "line": {"key": "now", "ref": "Now", "text": "unit suite over #2", "mark": "info"}},
+  {"op": "set", "field": "phase", "value": "validate"},
+  {"op": "set", "field": "attention", "value": "wait"}]}
+```
+
+- Ops: `replace`, `before`, `after`, `delete` (by `key`), `first`, `last`, and `set` for `phase`,
+  `attention`, `header` or `stale_after_minutes`. They see each other, in the order written.
+- **Either the whole list applies or none of it does**, so a patch is safe to send without reading
+  first: the worst case is that nothing happened and you were told why.
+- **A patch whose answer never arrived may have been applied — send it again.** The resend is
+  refused rather than doubling the line.
+- At most 64 ops per call. `actions` are not patchable: change buttons with a whole `panel_set`.
+- Republish with `panel_set` only when the *shape* changes (a new MR/PR train, a different body).
+
+**Refusals are information, not noise.** `no line of this panel carries the key "…"` → your keys and
+the panel disagree: `panel_get` and republish. `publish with panel_set before patching` → this pane
+is still on its file. `this panel is held by "…"` → another producer owns it; do not fight it, say
+so at the next stop.
+
+**After a compaction, a restart or a resumed work**, call `panel_get` **before publishing**. It
+returns the document on screen — yours or one that arrived by file — and publishing it back leaves
+the panel exactly as it is. What comes back is the document as the app understood it: unknown fields
+are gone and defaults come back absent.
+
+**Optional — buttons at a stop.** At a stop parked on the user, `actions` (up to 8) paint a button
+whose command is shown literally and is written into this pane's program on one click — which here
+is this very session's prompt. So `{"label": "Approve the design", "send": "approve"}` answers you
+without the user typing. Plain text, no line breaks, never a credential: it is painted on screen and
+lands in the shell history.
+
+### 4.3 Without those tools — `.claude/work/<work>/panel.json`
+
+Overwrite the file **whole** (never patch) with the §4.1 document. `updated_at` from the real clock
+(`date -Iseconds`), never carried over — it is how the reader flags a stale snapshot. `attention`
+and `key` buy nothing here: the file panel is drawn from `mark` and `ref` alone.
+
+### 4.4 When to publish — whichever transport is in play
+
+(a) In pre-flight, as soon as `meta.json` is loaded; (b) immediately **before** every stop header;
+(c) **before** any long stretch (fan-out, full suite, CI poll) — never after, so a step that dies
+halfway is not shown as finished. When the stretch will outlast the ~30 min staleness warning, set
+`stale_after_minutes` to what it will really take; (d) wherever `## Close` updates `meta.json`. A
+held panel still goes stale: the app stamps each delivery's arrival.
 
-### `meta.json.cost[]` — what a phase measured, when it could
+### 4.5 `meta.json.cost[]` — what a phase measured, when it could
 
 A phase that can measure what it spent appends one entry: `{ "phase": "review", "at": "<ISO>",
 "reviewers": 8, "usd": 0.0124, "source": "harness" }`. `flow review --record` writes it; `flow cost`
@@ -322,7 +394,7 @@ single largest token cost of a work, so every work carries a short handoff:
 - **Name the phase, never the command.** An artifact outlives the session that wrote it and may be
   resumed from a different agent, where the same phase is invoked under another name. Write the
   phase — `validate`, `review`, `ship #2` — not the invocation. Applies to `00-summary.md`,
-  `panel.json`'s `Next` line and every numbered artifact; the prose you *say* at a stop is exempt.
+  the panel's `Next` line and every numbered artifact; the prose you *say* at a stop is exempt.
 
 ## 6. Delegating — what every brief owes the parent
 
@@ -445,7 +517,7 @@ and the evidence; the verdict stays here.
 bills and saves nothing. What wakes you is whatever the harness offers — a background task that
 re-invokes you when it finishes, a scheduled wake-up, a message back to this thread; where it offers
 none, the supervisor's evidence file is read at your next stop, and **you say that** rather than
-implying something is being watched. Refresh `panel.json` before you go (§4): the line carries
+implying something is being watched. Refresh the panel before you go (§4): the line carries
 `mark: "wait"` and `stale_after_minutes` set to the deadline you gave, because a thread that goes
 quiet with `current` on screen reads as a session that died.