smol-symphony 0.2.0 → 0.3.0

package/{WORKFLOW.template.md → WORKFLOW.template.yaml}

@@ -1,23 +1,24 @@
-<!--
-WORKFLOW.template.md — annotated reference for symphony workflow files.
-
-A workflow file is a YAML front-matter block plus a Liquid-templated prompt
-body. The orchestrator parses the front matter into ServiceConfig (defined in
-src/types.ts) and renders the prompt body once per dispatched issue, with the
-Liquid context `{ issue, attempt }`.
-
-This document lists every supported section, every option within it, the
-parser default, and a small example. For a complete worked example, see
-WORKFLOW.md in this repo.
-
-Notation:
-  • Required keys are marked (required).
-  • Types: `string`, `int`, `bool`, `path` (string resolved relative to the
-    workflow file's directory unless absolute), `string[]`, `map<K, V>`.
-  • Defaults are what the parser writes when the key is absent.
--->
-
----
+# ─────────────────────────────────────────────────────────────────────────────
+# WORKFLOW.template.yaml — annotated reference for symphony workflow files.
+#
+# A workflow file is pure YAML config. The orchestrator parses it into
+# ServiceConfig (see src/types/config.ts) and, per dispatched issue, renders the
+# active state's prompt — its `prompt_file` wrapped in the shared
+# `prompt.preamble_file` / `prompt.footer_file` — with the Liquid context
+# `{ issue, attempt }`.
+#
+# This document lists every supported section, every option within it, the
+# parser default, and a small example. For a complete worked example, see
+# WORKFLOW.yaml in this repo. For the smallest thing that runs — what
+# `npx smol-symphony` scaffolds by default — see WORKFLOW.minimal.yaml; reach for
+# the options below only when you want a power feature it omits.
+#
+# Notation:
+#   • Required keys are marked (required).
+#   • Types: `string`, `int`, `bool`, `path` (string resolved relative to the
+#     workflow file's directory unless absolute), `string[]`, `map<K, V>`.
+#   • Defaults are what the parser writes when the key is absent.
+# ─────────────────────────────────────────────────────────────────────────────
 # ─────────────────────────────────────────────────────────────────────────────
 # tracker — where issues come from.
 # ─────────────────────────────────────────────────────────────────────────────
@@ -26,9 +27,15 @@ tracker:
   # files under `root`, one per issue, organized by state subdirectory).
   kind: local
 
-  # root (path): directory containing `<state>/<id>.md` files. Required.
-  # Resolved relative to the workflow file if not absolute.
-  root: ./issues
+  # root (path): directory containing `<state>/<id>.md` files. Optional.
+  # An explicit value resolves absolute as-is, `~`-expanded against $HOME, or
+  # (relative) against the workflow file's directory.
+  # Default (unset): ~/.symphony/trackers/<project> — durable tracker state lives
+  # OUTSIDE the repo working tree by default, so it survives a delete / re-clone
+  # of the repo. <project> is the `workspace.github_repo` slug's repo name
+  # (owner/repo → repo), falling back to this workflow file's directory basename;
+  # sanitized so two different projects on one machine never collide.
+  # root: ~/.symphony/trackers/my-project
 
 # ─────────────────────────────────────────────────────────────────────────────
 # states — per-state configuration map. REQUIRED. Every workflow must declare
@@ -47,17 +54,21 @@ tracker:
 #                and the landing directory for `symphony.propose_issue`.
 #   adapter   (string, optional): override the workflow-level `acp.adapter` for
 #             agents dispatched in this state. Must be a known profile (claude,
-#             codex, opencode). All use host-side credential substitution at
-#             Gondolin egress and are startup-probed so a missing credential
-#             fails fast. claude has a
-#             single host credential file (~/.claude/.credentials.json) that is
-#             probed for readability; codex passes when either ~/.codex/auth.json
-#             holds a token (ChatGPT-OAuth tokens.access_token or a top-level
-#             OPENAI_API_KEY) or the host OPENAI_API_KEY env var is set; opencode
-#             passes when either ~/.local/share/opencode/auth.json holds a
-#             github-copilot token (run `opencode auth login` -> GitHub Copilot
-#             on the host) or a COPILOT_GITHUB_TOKEN/GH_TOKEN/GITHUB_TOKEN env
-#             var is set.
+#             codex). Both use host-side credential substitution at Gondolin
+#             egress and are startup-probed so a missing credential fails fast.
+#             claude has a single host credential file
+#             (~/.claude/.credentials.json) that is probed for readability; codex
+#             passes when either ~/.codex/auth.json holds a token (ChatGPT-OAuth
+#             tokens.access_token or a top-level OPENAI_API_KEY) or the host
+#             OPENAI_API_KEY env var is set.
+#   prompt_file (path): this state's prompt template, in its own file. The shell
+#             loader reads it and assembles `prompt.preamble_file` + this file +
+#             `prompt.footer_file` (see the top-level `prompt:` block below) into
+#             the template rendered for issues in this state. Every active
+#             (dispatched) state should declare one; a state without `prompt_file`
+#             renders the generic fallback prompt. Resolved relative to the
+#             workflow file. A missing/unparseable file fails at startup (and
+#             `symphony doctor`), not mid-dispatch.
 #   model     (string, optional): override `acp.model` for this state.
 #             Blank or whitespace-only values normalize to "use the adapter
 #             default" (same as the workflow-level acp.model semantics).
@@ -117,12 +128,7 @@ tracker:
 #             Recognized kinds:
 #               push_branch          { remote, ref }
 #               create_pr_if_missing { base, head, title_from, body_from }
-#               ensure_branch        { name, seed_from? }
-#               checkout             { ref }
-#               merge                { source, target, on_conflict }
-#               delete_branch        { name, scope: local|remote|both, remote? }
 #               run_in_vm            { name, cmd: [...], env?, timeout? }
-#               propose_followup     { title, body?, labels?, priority? }
 #
 #             Templating: `$varname` references the fixed ActionContext
 #             namespace ($identifier, $workspace, $branch, $base_branch,
@@ -137,20 +143,24 @@ tracker:
 #             Retry: optional `on_error.retry: { count, backoff_ms }`. Default
 #             policy is 3 retries with exponential backoff starting at 1s,
 #             then abort. `on_error.then: { route_to: <state> }` reroutes the
-#             issue to a holding state instead of aborting.
-#
-#             merge's `on_conflict: { route_to: <state> }` is a fast-path
-#             reroute. Use `on_conflict: abort` to fail the action and abort
-#             the cleanup pass without a state move.
-#
-#             run_in_vm has content-hash caching: identical (workspace tree
-#             ⊕ cmd ⊕ env) tuples skip execution and re-use the prior
-#             successful result. The workspace-tree hash reflects live
-#             contents (tracked + modified + untracked-not-gitignored), so
-#             an uncommitted agent edit forces a cache miss. Cache lives
-#             under `~/.cache/symphony/actions/run_in_vm/<name>/<sha256>/`.
-#             `symphony rerun --check=<name>` drops the whole `<name>/`
-#             namespace dir so the next dispatch re-runs that one check.
+#             issue OUT of the action's state into <state> (which must be
+#             declared — validated at parse time) instead of aborting; the
+#             runner moves the tracker file there with the failure reason
+#             appended as notes. The canonical use is the Done handoff (issue
+#             235): a `push_branch` / `create_pr_if_missing` that fails after
+#             its retries reroutes into a `HandoffFailed` holding state so a
+#             stranded handoff (no branch on the remote, no PR) is operator-
+#             visible instead of dead-ending silently in terminal Done. A
+#             rerouted handoff also RETAINS the per-issue workspace (the
+#             handoff-pending marker, issue 234) so the unpushed commit
+#             survives for a manual push. A `.github/workflows/`-touching push
+#             is the common trigger: the shared fine-grained PAT is not granted
+#             Workflows:write, so GitHub server-side-declines it and the routed
+#             reason is rewritten to an actionable "manual SSH push required".
+#
+#             run_in_vm runs uncached: every dispatch into the state re-execs
+#             the command on the live per-issue VM. `name` labels its run-log
+#             output (no caching layer; the action is the plain escape hatch).
 #   pr        (map, optional): PR autopilot routing for this state (issue 139).
 #             Valid only on a `terminal` state, and only acts when the
 #             top-level `pr:` engine block (below) has `enabled: true`. This is
@@ -174,6 +184,39 @@ tracker:
 #             terminal state may declare `auto_merge`, and at most one may
 #             declare `close`; an `on_conflict.route_to` naming an undeclared
 #             state is rejected at parse time.
+#   spawn     (map, optional): recurring-spawn trigger for this state (the sleep
+#             cycle as a recurring STATE). Valid only on an `active` state. When
+#             a trigger fires the orchestrator MINTS a FRESH ephemeral issue into
+#             this state (it runs once and terminates in a dedicated terminal),
+#             instead of re-arming one immortal parked ticket. Fields:
+#               • on_idle (bool): spawn when the orchestrator is idle AND >=1
+#                 issue reached a terminal state since the last cycle (the ">=1
+#                 since last cycle" gate is load-bearing — without it an idle
+#                 orchestrator re-spawns in a tight loop with nothing new to
+#                 mine). Default false.
+#               • after_terminal (int): a backstop for busy stretches that never
+#                 go idle — spawn once this many issues have reached a terminal
+#                 state (Done/Cancelled/the spawn's terminal) since the last
+#                 cycle. 0 disables the count trigger. Default 0.
+#               • title (string): title template for the minted issue;
+#                 `{{ stamp }}` → the mint timestamp (e.g. "2026-06-03 12:00").
+#                 Default "Reflection {{ stamp }}".
+#               • body (string, optional): lead-in line for the GENERATED
+#                 provenance body (the trigger + counter + timestamp the static
+#                 prompt can't know are always appended). Default: a generic
+#                 "Auto-spawned reflection cycle." lead-in.
+#               • max_in_flight (int): never mint a second issue while this many
+#                 are already live in the spawn state. Load-bearing — it replaces
+#                 the immortal ticket's built-in "one location = one reflection"
+#                 mutex, so a busy-stretch after_terminal trigger can't pile up
+#                 cycles. Default 1.
+#             The terminal-transition counter resets to 0 on a successful mint
+#             and is held in orchestrator memory only (a restart resets it). At
+#             most one active state may declare `spawn` (so the spawn state is
+#             unambiguous). The spawn's terminal must be a DEDICATED terminal
+#             with no `pr:` / `actions:` — a minted issue runs on an empty branch,
+#             so a Done-style PR autopilot would try to open a PR off nothing.
+#             See the SLEEP CYCLE section below for the full pattern.
 #
 # Declaration order matters: role-filtered listings (active states, terminal
 # states) follow it, and the dashboard renders state columns in the same order.
@@ -181,6 +224,7 @@ tracker:
 states:
   Todo:
     role: active
+    prompt_file: prompts/Todo.md   # this state's prompt template (see `prompt:` below)
     adapter: claude
     model: claude-opus-4-7
     effort: xhigh
@@ -188,6 +232,7 @@ states:
     max_concurrent: 1          # at most one implementer agent at a time
   Review:
     role: active
+    prompt_file: prompts/Review.md
     adapter: codex
     model: gpt-5-codex
     max_turns: 4
@@ -205,14 +250,22 @@ states:
     # open a PR if one does not already exist. Templates resolve against the
     # fixed ActionContext namespace; the orchestrator stages $pr_title and
     # $pr_body_file from the issue file before firing.
+    # A handoff that fails after its retries reroutes the issue OUT of Done into
+    # the HandoffFailed holding state (issue 235) via `on_error.then.route_to`,
+    # so a stranded handoff is operator-visible instead of silently terminal-Done.
     # actions:
-    #   - { kind: push_branch, remote: origin, ref: $branch, if: $repo }
+    #   - kind: push_branch
+    #     remote: origin
+    #     ref: $branch
+    #     if: $repo
+    #     on_error: { then: { route_to: HandoffFailed } }
     #   - kind: create_pr_if_missing
     #     base: $base_branch
     #     head: $branch
     #     title_from: $pr_title
     #     body_from: $pr_body_file
     #     if: $repo
+    #     on_error: { then: { route_to: HandoffFailed } }
   Cancelled:
     role: terminal
     # PR autopilot close state (issue 139). Derived as the close state because
@@ -221,11 +274,46 @@ states:
     #   close: true
   Triage:
     role: holding
+  HandoffFailed:
+    # Landing state for a Done handoff that FAILED (issue 235): the failing
+    # action's `on_error.then.route_to` (above) reroutes the issue here with the
+    # reason appended. Holding → never dispatched; it parks for an operator to
+    # push the branch by hand (the workspace is retained by issue 234's marker)
+    # and move the issue back to Done, or to Cancelled. Declared AFTER Triage so
+    # Triage stays the `propose_issue` landing (the first declared holding state).
+    role: holding
 
 # ─────────────────────────────────────────────────────────────────────────────
-# SLEEP CYCLE — a reflection state that mines finished work for harness
+# prompt — shared prompt-assembly files (per-state prompt split). OPTIONAL.
+#
+# When an active state declares a `prompt_file` (see the states block above), the
+# shell loader builds that state's prompt by concatenating, in order:
+#
+#     prompt.preamble_file   (shared header)
+#   + the state's prompt_file (the state-specific body)
+#   + prompt.footer_file     (shared footer)
+#
+# and renders the result — so the config reads as the shape of the workflow and
+# each state's prompt lives in its own file under `prompts/`. The Liquid context
+# is `{ issue, attempt }`; each file is an ordinary Liquid template fragment.
+#
+# Both keys are paths resolved relative to the workflow file, and both are
+# optional: omit `preamble_file`/`footer_file` to wrap a state body in nothing.
+# A workflow file is pure YAML config — there is no inline prompt body. Every
+# active state names its own `prompt_file`; a state without one renders the
+# generic fallback prompt, so give each dispatched state a `prompt_file`. See
+# WORKFLOW.minimal.yaml for the smallest example and WORKFLOW.yaml in this repo
+# for a full worked example.
+#
+#   prompt:
+#     preamble_file: prompts/_preamble.md
+#     footer_file:   prompts/_footer.md
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ─────────────────────────────────────────────────────────────────────────────
+# SLEEP CYCLE — a recurring reflection STATE that mines finished work for harness
 # improvements (issue 122). Optional, opt-in pattern; layered on top of the
-# states block above. The shipped smol-symphony WORKFLOW.md wires it for the
+# states block above. The shipped smol-symphony WORKFLOW.yaml wires it for the
 # dogfooding (symphony-on-symphony) setup.
 #
 # The idea: every dispatch starts from the same static prompt + config, no
@@ -233,16 +321,21 @@ states:
 # rejected, burn their turn budget, or fight the harness. A periodic
 # "reflection" turn closes that feedback loop — it reads completed-task history
 # (the read-only mounts `eval_mode` exposes), distils *recurring* friction, and
-# files improvement proposals against the HARNESS (this WORKFLOW.md's prompt
+# files improvement proposals against the HARNESS (this WORKFLOW.yaml's prompt
 # branches and per-state model/max_turns/allowed_transitions/effort/actions, the
 # gondolin image config, acceptance criteria, timeouts) — never the product code under
 # review. Proposals land in Triage via `propose_issue`, so a human stays the
 # gate. This is the "self-improving agent" pattern aimed at the harness rather
 # than the product.
 #
-# Two states implement it:
+# SHAPE: recurring STATE, NOT an immortal ticket. The cycle is modelled as a
+# recurring state that SPAWNS ephemeral reflection issues. There is no parked
+# "Sleep cycle" ticket that ping-pongs between two states forever: when a trigger
+# fires the orchestrator MINTS a fresh issue into the spawn state; it runs once
+# and terminates in a dedicated terminal, like every other ticket. Two states
+# implement it:
 #
-#   Reflect (role: active, eval_mode: true):
+#   Reflect (role: active, eval_mode: true, spawn: {...}):
 #     - eval_mode binds /symphony/issues (all state dirs, incl. the Done/*.md
 #       handoff transcripts) + /symphony/logs (per-issue JSONL run logs)
 #       read-only into the VM. No extra mount plumbing — it reuses the existing
@@ -250,23 +343,24 @@ states:
 #     - Give it a capable adapter/model (large context helps: a reflection turn
 #       reads many transcripts + logs) and a higher max_turns than your
 #       implement/review states.
-#     - allowed_transitions: [Dormant] — the reflector may ONLY go dormant. It
-#       cannot route itself into the implement/review/done flow. Filing
-#       improvements goes through propose_issue (→ Triage), which is independent
-#       of allowed_transitions.
-#     - The prompt body's `when "Reflect"` branch encodes the
+#     - allowed_transitions: [Reflected] — the reflector may ONLY terminate in
+#       its dedicated terminal. It cannot route itself into the
+#       implement/review/done flow. Filing improvements goes through
+#       propose_issue (→ Triage), which is independent of allowed_transitions.
+#     - The `spawn:` block (see the states-field docs above) declares the
+#       triggers (on_idle / after_terminal), the minted-issue title template, and
+#       max_in_flight. This is what makes the cycle recurring — no cron needed.
+#     - The Reflect state's `prompt_file` encodes the
 #       read → distil → propose loop and the GUARDRAILS below.
 #
-#   Dormant (role: holding):
-#     - Resting place for the single recurring "Sleep cycle" issue between runs.
-#       Holding → never dispatched. Declare it AFTER your Triage state so Triage
-#       stays the first holding state (the `propose_issue` landing + triage
-#       approve/discard target both resolve the FIRST declared holding state).
-#     - Dashboard caveat: the dashboard currently renders triage approve/discard
-#       buttons on every holding row, and the tracker resolves a move by issue
-#       id regardless of source directory — so clicking those buttons on a
-#       Dormant issue would mis-route it. Re-arm via cron/CLI/filesystem, not the
-#       dashboard buttons.
+#   Reflected (role: terminal):
+#     - DEDICATED terminal for a completed reflection — NOT Done. Done carries the
+#       PR autopilot `actions:` (push_branch + create_pr_if_missing); a minted
+#       reflection runs on an empty branch (it only files propose_issue), so
+#       terminating in Done would try to open a PR off nothing. So `Reflected`
+#       declares NO `pr:` and NO `actions:`. Each cycle lands here as a browsable,
+#       per-run audit trail — one issue per cycle — instead of one ever-growing
+#       immortal ticket body.
 #
 # GUARDRAILS (this is a self-modifying loop — keep the human in it):
 #   - Output is proposals into Triage (holding, never auto-dispatched). The
@@ -276,13 +370,14 @@ states:
 #   - Each proposal must cite the issue ids that motivated it, so the operator
 #     checks the lesson against the evidence rather than the reflector's summary.
 #
-# CADENCE (v1 — operator/scheduled-triggered, no orchestrator trigger logic):
-#   A single recurring issue (e.g. titled "Sleep cycle") oscillates Reflect ↔
-#   Dormant. The operator drops it into Reflect (dashboard, or `mv` on disk), or
-#   an external cron / a `symphony reflect` verb arms it. After it files
-#   proposals it transitions to Dormant and waits to be re-armed. Auto-arm on
-#   idle (no active issues) or after N transitions into Done is a deliberate
-#   follow-up, out of scope for v1.
+# CADENCE: the orchestrator auto-spawns a fresh reflection issue from the
+# Reflect state's `spawn:` block — `on_idle` (idle with >=1 issue finished since
+# the last cycle) or `after_terminal` (a backstop once N issues have reached a
+# terminal state since the last cycle). The counter resets on a successful mint;
+# `max_in_flight: 1` prevents a second cycle while one is live. An operator can
+# also mint a cycle by hand by creating a Reflect issue (a real dashboard
+# "reflect now" button or a `symphony reflect` verb is a natural fit) — a clean
+# replacement for the old "re-arm by mv/cron" path.
 #
 # Example states to add (names are yours to choose):
 #
@@ -294,11 +389,16 @@ states:
 #       model: claude-opus-4-8[1m]   # large context for reading transcripts
 #       max_turns: 20                # higher than implement/review
 #       eval_mode: true
-#       allowed_transitions: [Dormant]
+#       allowed_transitions: [Reflected]
+#       spawn:
+#         on_idle: true
+#         after_terminal: 10         # backstop for busy stretches (0 disables)
+#         title: "Reflection {{ stamp }}"
+#         max_in_flight: 1           # never two reflections live at once
 #     Triage:
-#       role: holding                # declared before Dormant
-#     Dormant:
 #       role: holding
+#     Reflected:
+#       role: terminal               # dedicated terminal — NO pr:/actions:
 # ─────────────────────────────────────────────────────────────────────────────
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -359,47 +459,50 @@ pr:
   # within the window. Default 30000.
   poll_interval_ms: 30000
 # ----------------------------------------------------------------------------
-# SLEEP CYCLE (auto-arm) — issue 140 moved this trigger ONTO the active state it
-# arms. There is NO top-level `sleep_cycle:` block anymore; declare an `arm:`
-# block on the active state (e.g. Reflect) in the `states:` map above:
+# SLEEP CYCLE (recurring spawn) — the recurrence lives in the `spawn:` block on
+# the active reflection state (see the states-field docs + the SLEEP CYCLE
+# section above). There is NO top-level `sleep_cycle:` block and NO `arm:` block;
+# instead of re-arming one immortal parked ticket, the orchestrator MINTS a fresh
+# ephemeral reflection issue when a trigger fires:
 #
 #   states:
 #     Reflect:
 #       role: active
-#       arm:
-#         issue: sleep-cycle      # the recurring issue to auto-enter this state
-#         from: Dormant           # the holding state it rests in between runs
-#         on_idle: true           # arm when idle with >=1 terminal since last run
-#         after_terminal: 10      # arm after N terminal transitions (0 disables)
-#
-# SEMANTICS (unchanged from the old sleep_cycle block):
-#   - on_idle: arm when the orchestrator is idle (nothing running, claimed, or
+#       allowed_transitions: [Reflected]
+#       spawn:
+#         on_idle: true            # spawn when idle with >=1 terminal since last cycle
+#         after_terminal: 10       # spawn after N terminal transitions (0 disables)
+#         title: "Reflection {{ stamp }}"
+#         max_in_flight: 1         # never two reflections live at once
+#     Reflected:
+#       role: terminal             # dedicated terminal — NO pr:/actions:
+#
+# SEMANTICS:
+#   - on_idle: spawn when the orchestrator is idle (nothing running, claimed, or
 #     pending retry, and no active candidate this poll) AND >=1 issue has reached
-#     a terminal state since the last run. The ">=1 since last run" gate is
-#     load-bearing: without it an idle orchestrator re-arms in a tight loop with
+#     a terminal state since the last cycle. The ">=1 since last cycle" gate is
+#     load-bearing: without it an idle orchestrator re-spawns in a tight loop with
 #     nothing new to mine.
-#   - after_terminal: a backstop for busy stretches that never go idle — arm once
-#     this many issues have reached a terminal state (Done/Cancelled) since the
-#     last run. 0 disables the count trigger.
-# The terminal-transition counter resets to 0 the moment the issue is armed and
-# is held in orchestrator memory only (a restart resets it).
+#   - after_terminal: a backstop for busy stretches that never go idle — spawn
+#     once this many issues have reached a terminal state since the last cycle.
+#     0 disables the count trigger.
+#   - max_in_flight: never mint a second issue while this many are already live in
+#     the spawn state (replaces the immortal ticket's built-in one-at-a-time
+#     mutex). Default 1.
+# The terminal-transition counter resets to 0 on a successful mint (and is
+# restored if the mint fails) and is held in orchestrator memory only (a restart
+# resets it). A finished reflection's OWN terminal move (out of the spawn state)
+# is excluded from the counter, so a completed cycle never counts toward spawning
+# the next.
 #
 # VALIDATION (structural, from each state's own role — no dedicated re-validator):
-# `arm:` is only valid on an `active` state, `arm.from` must be a declared
-# `holding` state, `arm.issue` is required, and at most one active state may
-# declare `arm`.
+# `spawn:` is only valid on an `active` state, and at most one active state may
+# declare `spawn`. Unlike the retired `arm:` block it needs no parked issue and
+# no from-state.
 #
-# GUARDRAILS: arming ONLY moves the issue into the armed state. The proposals the
+# GUARDRAILS: spawning ONLY mints the reflection issue. The proposals the
 # reflector files still land in Triage and still require human approve/discard —
-# arming does not bypass the human gate. Requires a single issue with id
-# `arm.issue` resting in `arm.from` (created by the operator); the trigger is
-# inert until that issue exists.
-#
-# MIGRATION: a deprecated top-level `sleep_cycle:` block is still parsed for one
-# release and folded onto states.<reflect_state>.arm (dormant_state -> from,
-# reflect_state -> the armed state, issue_id -> issue, arm_on_idle -> on_idle,
-# arm_after_done -> after_terminal) with a startup deprecation warning. Prefer
-# the per-state `arm:` block.
+# spawning does not bypass the human gate.
 # ----------------------------------------------------------------------------
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -415,8 +518,11 @@ polling:
 # ─────────────────────────────────────────────────────────────────────────────
 workspace:
   # root (path): parent directory holding `<issue-id>/` working trees.
-  # Default: $TMPDIR/symphony_workspaces
-  root: ./.symphony/workspaces
+  # An explicit value resolves absolute as-is, `~`-expanded against $HOME, or
+  # (relative) against the workflow file's directory.
+  # Default (unset): ~/.symphony/workspaces/<project> (same <project> derivation
+  # as tracker.root above).
+  # root: ~/.symphony/workspaces/my-project
 
   # github_repo (string | null): the GitHub `owner/repo` slug symphony pushes the
   # per-issue `agent/<id>` branch to and opens a PR against on the Done-state
@@ -512,8 +618,11 @@ workspace:
 #
 # Console routing: while the file sink is active (the default), the structured
 # stream goes to the file ONLY — the console shows just the startup banner
-# (workflow, tracker root, dashboard URL, log-file path). `tail -f` the log
-# file to follow the detail. Pass `--verbose` (alias `--foreground`) to mirror
+# (workflow, tracker root, dashboard URL, MCP endpoint, ACP `/acp` WebSocket
+# endpoint, log-file path). The dashboard/MCP/ACP all share the one HTTP port,
+# which defaults to ephemeral, so the banner is how the operator learns which
+# port got bound. `tail -f` the
+# log file to follow the detail. Pass `--verbose` (alias `--foreground`) to mirror
 # the structured stream back onto the console for interactive debugging. With
 # no file sink configured, the structured stream stays on stderr.
 #
@@ -523,8 +632,11 @@ workspace:
 # ─────────────────────────────────────────────────────────────────────────────
 logs:
   # root (path): directory holding per-issue JSONL files and symphony.log.
-  # Default: ./.symphony/logs
-  root: ./.symphony/logs
+  # An explicit value resolves absolute as-is, `~`-expanded against $HOME, or
+  # (relative) against the workflow file's directory.
+  # Default (unset): ~/.symphony/logs/<project> (same <project> derivation as
+  # tracker.root above) — durable run logs live OUTSIDE the repo tree by default.
+  # root: ~/.symphony/logs/my-project
 
 # ─────────────────────────────────────────────────────────────────────────────
 # workspace lifecycle — no shell `hooks:` surface.
@@ -537,7 +649,7 @@ logs:
 #     branch cut + origin/identity) is owned by the orchestrator's TypeScript
 #     `setupWorkspaceDir`. The workspace arrives at the agent with: a hardlinked
 #     `git clone --local --no-tags` of the source repo (`SYMPHONY_SOURCE_REPO`,
-#     default: the dir containing WORKFLOW.md) on the base branch
+#     default: the dir containing WORKFLOW.yaml) on the base branch
 #     (`SYMPHONY_BASE_BRANCH`, default `main`); all network remotes stripped; an
 #     `origin` restored to the canonical HTTPS URL when `workspace.github_repo`
 #     (or the `SYMPHONY_REPO` env override) is set (so the Done-state push can
@@ -622,12 +734,6 @@ acp:
   #              bearer (in a fake ~/.codex/auth.json); the host substitutes the
   #              real OpenAI/ChatGPT token at egress. No real credential — and no
   #              real OPENAI_API_KEY — enters the VM.
-  #   opencode — opencode acp, backed by GitHub Copilot (issue 130). The host
-  #              exchanges the operator's `opencode auth login` GitHub OAuth token
-  #              for a short-lived Copilot token host-side and substitutes it at
-  #              egress — the GitHub token never enters the VM. One Copilot
-  #              credential unlocks many models (GPT-4o/4.1, Claude Sonnet,
-  #              Gemini, o-series, …).
   adapter: claude
 
   # Credentials never enter the VM (issue 113; codex generalized in 116). The
@@ -650,17 +756,6 @@ acp:
   # so codex-acp runs in its native mode without an in-VM OAuth handshake or
   # refresh (both stay host-side). Every credential-bearing var is stripped from
   # the forwarded VM boot env.
-  #
-  # For opencode: a staged opencode.json (at /root/.config/opencode/opencode.json)
-  # declares a custom @ai-sdk/openai-compatible provider whose baseURL/apiKey read
-  # the OPENCODE_PROXY_* env vars (a `gho_`-shaped placeholder bearer). The host
-  # reads the durable GitHub OAuth token from ~/.local/share/opencode/auth.json
-  # (COPILOT_GITHUB_TOKEN/GH_TOKEN/GITHUB_TOKEN env fallback), exchanges it
-  # host-side at api.github.com/copilot_internal/v2/token for a short-lived Copilot
-  # token (cached + TTL-refreshed before expiry), injects the Copilot editor
-  # headers, and substitutes it at egress to api.githubcopilot.com. The durable
-  # GitHub token never enters the VM — so do NOT also list it in
-  # `gondolin.forward_env`. See docs/research/opencode-copilot-accept-matrix.md.
 
   # model (string | null): optional model selector forwarded to the chosen adapter.
   # Each adapter profile knows how to surface it natively:
@@ -668,10 +763,6 @@ acp:
   #             claude-agent-acp would (aliases like "opus", "sonnet", or full IDs
   #             like "claude-opus-4-7").
   #   codex   — passed as `-c model="<value>"` argv to codex-acp (parsed as TOML).
-  #   opencode— baked into the staged opencode.json as model="symphony-copilot/<value>".
-  #             Use a Copilot chat-completions model id (e.g. gpt-4o, gpt-4.1,
-  #             claude-sonnet-4.5, gemini-2.5-pro); codex-class models served only
-  #             on Copilot's /responses path are NOT reachable. Default: gpt-4o.
   # Leave unset / null to use the adapter's own default model. Default: null.
   # model: claude-opus-4-7
 
@@ -689,7 +780,7 @@ acp:
   # Leave unset / null for the adapter's own default. Default: null.
   # effort: xhigh
 
-  # NOTE: the launch shape is fixed (an in-VM agent dials back over the bridge
+  # NOTE: the launch shape is fixed (an in-VM agent dials back the `/acp` WebSocket
   # and spawns the chosen adapter). Customizing what the agent spawns requires
   # forking that agent and rebuilding the VM image with the fork in place.
 
@@ -709,37 +800,19 @@ acp:
   # the turn is killed and retried. Default: 300000
   stall_timeout_ms: 300000
 
-  # bridge — host-side TCP listener the in-VM agent dials back to for ACP traffic.
-  #
-  # This replaced the earlier in-VM-exec stdio path. Symphony writes ACP JSON-RPC frames
-  # onto an authenticated TCP socket; the in-VM agent (`/opt/symphony/vm-agent.mjs`)
-  # spawns the adapter via `child_process.spawn` with kernel pipes and bridges the
-  # socket to the adapter's stdio. This decouples symphony from any particular
-  # sandbox's stdio quirks — any sandbox that can launch a process with env vars and
-  # reach the host loopback works unchanged.
-  bridge:
-    # bind_host (string): host symphony binds the listener on. 0.0.0.0 allows any
-    # in-VM interface to reach the host loopback (Gondolin maps a synthetic guest host to
-    # host loopback transparently). Default: 0.0.0.0
-    bind_host: 0.0.0.0
-
-    # bind_port (int): port symphony binds the listener on. 0 picks an ephemeral
-    # port (used port surfaces via the in-VM SYMPHONY_ACP_URL env var). Default: 8788
-    bind_port: 8788
-
-    # reach_host (string): host the in-VM agent dials back to. Under Gondolin this is
-    # 127.0.0.1 because the guest loopback hits the host loopback. Other sandboxes
-    # may need a different alias. Default: 127.0.0.1
-    reach_host: 127.0.0.1
-
-    # reach_url (string|null): full URL override for the in-VM agent's dial
-    # destination, e.g. through a reverse proxy or different scheme. When null,
-    # symphony constructs `tcp://<reach_host>:<bind_port>`. Default: null
-    # reach_url: null
-
-    # connect_timeout_ms (int): how long to wait for the in-VM agent to connect after
-    # the sandbox is launched, before failing the attempt. Default: 30000
-    connect_timeout_ms: 30000
+  # ACP transport — the in-VM agent dials back a `/acp` WebSocket on symphony's unified
+  # HTTP server (the SAME listener that serves the dashboard + MCP), reached through the
+  # SAME `tcp.hosts` tunnel MCP uses (the guest dials `ws://symphony-mcp:7001/acp`). It
+  # authenticates with a per-dispatch bearer sent as the first WebSocket message, then ACP
+  # JSON-RPC frames flow as WebSocket frames; the in-VM agent (`/opt/symphony/vm-agent.mjs`)
+  # spawns the adapter via `child_process.spawn` with kernel pipes and pumps the frames to
+  # the adapter's stdio. There is NO separate ACP listener / bind port — the raw-TCP bridge
+  # (`acp.bridge.*`: bind_host/bind_port/reach_host/reach_url) was retired; those keys are
+  # ignored if present.
+
+  # connect_timeout_ms (int): how long to wait for the in-VM agent to dial back the `/acp`
+  # WebSocket after the sandbox is launched, before failing the attempt. Default: 30000
+  connect_timeout_ms: 30000
 
 # ─────────────────────────────────────────────────────────────────────────────
 # credentials — host credential lifecycle (issue 113). The host substitutes the
@@ -758,20 +831,82 @@ credentials:
   # systemd timer instead). Default: 21600000 (6 hours).
   ticker_interval_ms: 21600000
 
+  # refresh_margin_ms (int): how far ahead of a token's expiry the host refreshes it.
+  # Drives BOTH the per-VM proactive tick (scheduled at `expiresAt - margin`) AND the
+  # egress request-side lazy refresh (a request bound for a credential host within this
+  # margin of expiry awaits a fresh token before going out). Must comfortably cover the
+  # refresh round-trip (`claude -p ok` rotate + re-read + fan-out) plus any in-flight long
+  # request, or a token expiring mid-dispatch loses the refresh/request race and 401s the
+  # egress (issue 214). Default: 300000 (5 minutes).
+  refresh_margin_ms: 300000
+
 # ─────────────────────────────────────────────────────────────────────────────
 # gondolin — microVM execution environment (Gondolin substrate).
 # ─────────────────────────────────────────────────────────────────────────────
 gondolin:
-  # image (string | null): the agent rootfs the VM boots, expressed as a Gondolin
-  # image selector. Build it ONCE with `npm run build:image` (see images/agents/) —
-  # the build prints a content-addressed build id (a digest); pin that id here for
-  # an immutable, reproducible reference. A `name:tag` ref (e.g.
-  # `symphony-agents:latest`) or a path to an exported asset directory also work.
-  # The image bakes a Node.js runtime, every ACP-capable coding agent
-  # (claude-agent-acp, codex-acp, opencode), and the in-VM launcher at
-  # /opt/symphony/vm-agent.mjs — so dispatch needs no runtime mounts. REQUIRED:
-  # the runner fails fast at boot when this is unset. Default: null.
-  image: symphony-agents:latest
+  # image: the agent rootfs source. THREE forms, in precedence order
+  # (image > oci_image > managed):
+  #
+  #   1. `managed` (the DEFAULT when neither `image` nor `oci_image` is set, and what a
+  #      fresh scaffold emits): FETCH a prebuilt Gondolin asset published to symphony's
+  #      OWN GitHub releases for the running symphony version + host arch (issue 224).
+  #      No docker, no `npm run build:image`, no local convert — onboarding is
+  #      `scaffold → run`. On the first poll the orchestrator downloads + verifies (against
+  #      the published `.sha256`) + imports the asset ONCE (the dashboard shows the
+  #      one-time fetch) and HOLDS VM dispatch until it's ready, then boots the cached
+  #      asset. Published for x86_64 and arm64/aarch64 (the `release.yml` agent-image
+  #      matrix); any OTHER arch makes the managed source inert and the doctor FAILs
+  #      with an unsupported-arch message.
+  #      Override `SYMPHONY_RELEASE_REPO` to fetch from a fork/staging release.
+  #
+  #   2. a PRE-CONVERTED asset selector — the low-level escape hatch. Build it ONCE with
+  #      `npm run build:image` (see images/agents/); the build prints a content-addressed
+  #      build id (a digest) — pin that here for an immutable reference. A `name:tag` ref
+  #      (e.g. `symphony-agents:latest`) or a path to an exported asset directory also
+  #      work. WINS over `oci_image` and the managed source when set.
+  #
+  #   3. `oci_image` (below): a normal OCI ref symphony auto-converts on first reconcile.
+  #
+  # The image ships only `mise`; node + the ACP CLIs (claude-agent-acp, codex-acp)
+  # are mise-installed at dispatch and the in-VM launcher is staged at
+  # /opt/symphony/vm-agent.mjs — so dispatch needs no runtime mounts. Default: managed.
+  image: managed
+
+  # oci_image (string | null): a NORMAL OCI image reference (a docker/podman repo
+  # string, optionally `:tag` or `@sha256:…`) that symphony auto-converts + caches into
+  # a Gondolin asset as part of the reconcile loop (issue 206) — no manual
+  # `npm run build:image` step. On the first poll where the asset isn't cached, the
+  # orchestrator converts it ONCE (the dashboard shows a "building microVM image
+  # (one-time setup)" banner) and HOLDS VM dispatch until it's ready; the cache key is
+  # the resolved OCI digest, re-checked cheaply each reconcile tick (a read-only LOCAL
+  # resolve, no pull), so a moving tag whose locally-resolved digest changes (e.g. after
+  # a re-pull) reconverts before dispatch resumes — readiness tracks the live digest, not
+  # a ref string that converted once. `oci_pull_policy` governs the one-time conversion
+  # pull, not this readiness check. Once converted, dispatch boots the cached asset
+  # automatically — set ONLY
+  # this key and go; you do NOT also need to set `image`. The MVP targets the "golden"
+  # path — a published ref that already bakes the guest contract (Node ≥ 21 + the ACP
+  # CLIs on PATH; the launcher is staged at dispatch). `image` stays the escape hatch
+  # for an asset you converted yourself, and WINS when both are set: when `image` is
+  # set the reconcile gate boots IT and the `oci_image` auto-convert path is bypassed
+  # entirely — dispatch is never held and no one-time build runs. Default: null.
+  # oci_image: ghcr.io/your-org/symphony-agents:1.0.0
+
+  # oci_pull_policy (if-not-present | always | never): how the OCI image is pulled
+  # while resolving its digest for the one-time conversion. `if-not-present` pulls
+  # only when the ref isn't already in the local container store; `always` re-pulls
+  # even when it IS present locally, so a moving tag (`repo:latest`) picks up its
+  # fresh registry digest (and reconverts when that digest changed); `never` never
+  # pulls and requires the image to already be in the local store. The cache key and
+  # the converted asset are always keyed on the POST-pull digest, so `always` can't
+  # cache against a stale local one. Only consulted when `oci_image` is set (and not
+  # by the per-tick readiness probe, which is always pull-free). Default: if-not-present.
+  # oci_pull_policy: if-not-present
+
+  # oci_runtime (docker | podman | null): container runtime used for the conversion
+  # pull/export. null = auto-detect (prefers docker, falls back to podman). Only
+  # consulted when `oci_image` is set. Default: null (auto-detect).
+  # oci_runtime: docker
 
   # cpus (int): vCPU count per VM. Default: 2.
   cpus: 2
@@ -779,6 +914,14 @@ gondolin:
   # mem_mib (int): RAM per VM in MiB. Default: 2048.
   mem_mib: 4096
 
+  # rootfs_size (string): guest rootfs virtual-disk size (qemu size syntax, e.g. "3G"),
+  # passed to the VM substrate as the MINIMUM rootfs size. The agent toolchain installs
+  # onto the guest ROOTFS each dispatch (chmod works there; the sandboxfs bind mount
+  # silently drops it — issue 222), so the rootfs must be big enough for the ephemeral
+  # install: node alone is ~123 MB plus the agent CLIs, and the default ~593 MB rootfs
+  # leaves too little headroom. Default: "3G".
+  # rootfs_size: 3G
+
   # volumes (list): additional host:guest VFS mounts beyond the auto-mounted
   # workspace. Gondolin's VFS is programmable (no hard per-VM mount cap), but keep
   # this lean — if ANY state sets `eval_mode: true` it adds two read-only mounts
@@ -800,6 +943,38 @@ gondolin:
     - OPENAI_API_KEY
     - ANTHROPIC_API_KEY
 
+  # mise (jdx/mise) toolchain provisioning. This is ALWAYS ON and is the ONLY toolchain
+  # path (issue 233) — there is no enable/disable toggle. The agent image ships ONLY the
+  # `mise` binary (+ glibc essentials); node + the agent CLIs (claude-code, codex,
+  # claude-agent-acp, codex-acp) come from a mise SYSTEM config symphony
+  # STAGES into the guest at /etc/mise/config.toml at dispatch, and a consuming repo's
+  # own `mise.toml` / `.tool-versions` (higher precedence) ADDS project toolchains
+  # (rust, go, kotlin+gradle, a different node, …) on top. `mise install` runs once
+  # per dispatch, installing the toolchain onto the guest ROOTFS at /opt/symphony/mise-data
+  # (EPHEMERAL per VM — see below); the agent runtime node is resolved system-scoped via
+  # `mise which node` (so a project mise.toml can't downgrade the agent below the Node ≥ 21
+  # the launcher needs). Bumping an agent CLI is a one-line edit to
+  # assets/symphony-mise.system.toml + a restart — NO image rebuild + digest repin.
+  #
+  # WHY the rootfs, not a bind mount (issue 222): the gondolin sandboxfs bind mount has no
+  # chmod opcode (chmod is a silent no-op there), so mise's create-then-chmod extractor +
+  # npm postinstall would produce NON-executable binaries on it; the guest rootfs (ext4)
+  # honors chmod, so installs land there executable. Grow it via `gondolin.rootfs_size`
+  # (default 3G) so the per-VM install fits. Only the pure downloads (node tarballs + the
+  # npm package cache) persist across dispatches, on the bind-mounted `data_dir` below.
+  #
+  # The only tunable here is `data_dir` (the download cache location).
+  mise:
+    # data_dir (string): host directory bind-mounted RW → /opt/symphony/mise-cache as the
+    # persistent mise DOWNLOAD CACHE (node tarballs + the npm package cache) — NOT the
+    # install dir (issue 222): installs need chmod, which the sandboxfs bind mount silently
+    # drops, so the toolchain installs onto the ephemeral guest rootfs and only the pure
+    # downloads live here (so a cold install isn't re-downloaded every dispatch). SHARED
+    # across every VM; host-isolated from your own ~/.local/share/mise. Absolute as-is,
+    # `~`/`$VAR`-expanded, relative → resolved against the workflow-file dir.
+    # Default: ~/.symphony/mise.
+    # data_dir: ~/.symphony/mise
+
 # ─────────────────────────────────────────────────────────────────────────────
 # egress — general dev-tooling firewall for the in-VM agent.
 #
@@ -819,12 +994,23 @@ gondolin:
 # ─────────────────────────────────────────────────────────────────────────────
 egress:
   # allowed_hosts (string[]): hostnames the in-VM agent may reach for dev tooling.
-  # Default: [] (no extra hosts — the agent can reach only its inference host).
-  # Bare hostnames ONLY — no scheme, port, or path (`github.com`, not
+  # Default: the mise provisioning hosts [nodejs.org, registry.npmjs.org, mise.jdx.dev,
+  # mise-versions.jdx.dev] — ALWAYS, since mise provisioning is unconditional (issue 233)
+  # — so `mise install` of the staged SYSTEM config isn't firewall-blocked. Bare
+  # hostnames ONLY — no scheme, port, or path (`github.com`, not
   # `https://github.com/...`). A malformed entry fails safe (the host simply stays
   # blocked, never opened). Each entry is matched against the request host exactly.
+  #
+  # An explicit list REPLACES the default — so if you set `allowed_hosts`, re-list all
+  # four mise hosts here alongside your own (omitting mise-versions.jdx.dev re-hits the
+  # cold-cache node@<N> resolution failure issue 223 documents). PROJECT toolchains pull
+  # from their own hosts; add those too (rust → static.rust-lang.org, gradle →
+  # services.gradle.org, JDK → api.adoptium.net, …).
   allowed_hosts:
-    - registry.npmjs.org             # npm install
+    - nodejs.org                     # mise node prebuilts
+    - registry.npmjs.org             # npm install + mise npm: backend (agent CLIs)
+    - mise.jdx.dev                   # mise registry redirect
+    - mise-versions.jdx.dev          # mise precompiled tool version lists (node@N, etc.)
     - github.com                     # git-based deps / release pages
     - codeload.github.com            # GitHub tarball fetch
     - objects.githubusercontent.com  # release-binary downloads
@@ -833,9 +1019,13 @@ egress:
 # server — HTTP dashboard + MCP endpoint listener.
 # ─────────────────────────────────────────────────────────────────────────────
 server:
-  # port (int | null): when null, no HTTP server is started. `--port <n>` on
-  # the CLI overrides this. Default: null.
-  port: 8787
+  # port (int | null): HTTP listener port. `--port <n>` on the CLI overrides
+  # this. When both are unset symphony binds an ephemeral port (0 → the kernel
+  # picks a free port), so it "just works" with no config and two concurrent
+  # instances never collide; the actually-bound port + dashboard URL are printed
+  # to stdout at startup. Set a value here to pin a fixed port. Default: null
+  # (ephemeral).
+  # port: 8787
 
   # host (string): bind address. Default: '127.0.0.1'. Bind to '0.0.0.0' only
   # inside a trusted network boundary; the dashboard has no built-in auth.
@@ -880,68 +1070,31 @@ mcp:
   # orchestrator through the host gateway (e.g. bridge networking with a
   # fixed reverse-proxy URL). Default: null.
   host_url: null
----
-<!--
-Liquid-templated prompt body. Rendered once per dispatched issue. Context:
-
-  issue.identifier   — the issue's external id (e.g. "DEMO-42").
-  issue.title        — issue title (string).
-  issue.state        — current state (string, matches a key in `states:`).
-  issue.description  — body text (string or empty). `symphony.transition`
-                       appends its `notes` block here before the file moves,
-                       so the next state's agent reads the previous state's
-                       handoff message verbatim.
-  issue.priority     — number or null.
-  issue.labels       — list of strings (lowercased).
-  attempt            — int, 1-based attempt counter; absent on first attempt.
-
-Available Liquid filters: standard Shopify Liquid plus `escape_once`.
-
-Per-state prompt branching (V1 pattern): when `states:` declares more than
-one active role (e.g. Todo + Review), wrap the state-specific instructions in
-a `{% case issue.state %}` / `{% when "..." %}` / `{% else %}` block. The
-runner renders the prompt fresh on every dispatch, so each state's agent sees
-only its own instructions plus whatever common preamble / postamble lives
-outside the case. See WORKFLOW.md in this repo for a worked example.
-
-The body below is the literal prompt sent to the agent. Keep it specific to
-this workflow; orchestrator behavior (transition, request_human_steering,
-propose_issue) is the same no matter what you write here.
--->
-
-You are picking up a single issue and shepherding it through the workflow.
-
-Issue: **{{ issue.identifier }} — {{ issue.title }}**
-State: {{ issue.state }}
-{% if issue.priority -%}Priority: {{ issue.priority }}{%- endif %}
-{% if issue.labels.size > 0 -%}Labels: {% for l in issue.labels %}{{ l }}{% unless forloop.last %}, {% endunless %}{% endfor %}{%- endif %}
-
-{% if issue.description -%}
-Description:
-
-{{ issue.description }}
-{%- endif %}
-
-Goals:
-
-1. Work in the current directory only; treat it as the issue workspace.
-2. Make the smallest correct change that satisfies the issue.
-3. Hand off when done. `symphony.transition({ to_state, notes? })` is the
-   canonical (and only) exit verb: pass a declared state name and optional
-   markdown notes that get appended to the issue body for the next agent.
-   For single-agent workflows, transition straight into the first declared
-   `role: terminal` state to end the run.
-4. If you cannot proceed without human input, call
-   `symphony.request_human_steering({ question, context? })`. Your turn ends
-   immediately; the human's reply arrives as your next prompt.
-5. If you notice work out of scope for this issue — unrelated bugs, follow-ups
-   a human should size, refactors worth a separate dispatch — call
-   `symphony.propose_issue({ title, description?, labels?, priority? })`. It
-   lands in the first declared `role: holding` state directory (defaults to
-   `Triage/`); the operator approves or discards. Do not graft unrelated
-   edits onto this branch.
-
-{% if attempt -%}
-This is continuation/retry attempt {{ attempt }}. Inspect the workspace before
-making new edits; your previous run may have left state behind.
-{%- endif %}
+
+# ─────────────────────────────────────────────────────────────────────────────
+# prompts — per-state files (there is NO inline prompt body).
+#
+# A workflow file is pure YAML config; it carries no prompt body. Each active
+# state's prompt is its `states.<name>.prompt_file` (a Liquid template) wrapped
+# in the shared `prompt.preamble_file` / `prompt.footer_file` (see the `prompt:`
+# and `states:` sections above). The runner renders the matching state's
+# assembled template fresh on every dispatch, so each state's agent sees only its
+# own instructions plus the shared preamble / footer.
+#
+# Liquid context available to every prompt file ({ issue, attempt }):
+#   issue.identifier   — the issue's external id (e.g. "DEMO-42").
+#   issue.title        — issue title (string).
+#   issue.state        — current state (string, matches a key in `states:`).
+#   issue.description  — body text (string or empty). `symphony.transition`
+#                        appends its `notes` block here before the file moves, so
+#                        the next state's agent reads the previous state's handoff
+#                        message verbatim.
+#   issue.priority     — number or null.
+#   issue.labels       — list of strings (lowercased).
+#   attempt            — int, 1-based attempt counter; absent on first attempt.
+#
+# Available Liquid filters: standard Shopify Liquid plus `escape_once`.
+#
+# See prompts/ alongside WORKFLOW.yaml in this repo for worked prompt files, and
+# WORKFLOW.minimal.yaml for the smallest single-state example.
+# ─────────────────────────────────────────────────────────────────────────────