@sjawhar/opencode-legion-envoy 0.12.2 → 0.13.0

package/dist/src/server.js

@@ -13881,7 +13881,7 @@ var DISPATCH_URGENCIES = ["low", "med", "high", "blocking"];
 var DISPATCH_TOOL_DESCRIPTION = "Raise a durable question to the human as a Dispatch thread (a GitHub issue shown on the dashboard), or continue an existing thread with a follow-up question. The reader has NOT seen your transcript. Open a thread with `subject`; continue one with `thread`. The reply arrives in this session as a steer.";
 var DISPATCH_ARGUMENTS = {
   subject: "Open a new thread: one line naming the decision needed (the issue title). Omit when continuing a thread with `thread`.",
-  thread: `Continue an existing thread: "<n>" (an issue in the working directory's repo) or "owner/name#<n>". When set, omit subject, urgency, repo, and parent.`,
+  thread: 'Continue an existing thread: "<n>" (an open issue in the repo; a plain work issue is adopted as a thread) or "owner/name#<n>". When set, omit subject, urgency, repo, and parent.',
   context: `What you are doing, what you found, why you are stuck \u2014 at most ${DISPATCH_CONTEXT_MAX} characters, at most three short paragraphs or a bullet list. The reader has NOT seen your transcript: no nouns you coined this session, no internal identifiers unless the question is about them. GitHub references (#N, owner/repo#N, URLs) may be bare; the dashboard unfurls them.`,
   question: `The ask, at most ${DISPATCH_QUESTION_MAX} characters, as a list: current state \u2192 desired state \u2192 your recommendation and why; options go in \`ask\`.`,
   ask: "Structured questions rendered as buttons on the dashboard. Each: { question, header?, options: [{ label, description? }], multiple?, custom? }. Use this whenever the answer is one of N choices.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {

package/skills/dispatch/SKILL.md

@@ -154,7 +154,8 @@ dispatch({
 ```
 
 - `thread` replaces `subject`; `urgency`, `repo`, and `parent` are not accepted with it.
-  The thread must be open and be a dispatch thread; otherwise the tool says so
+  `thread` names an open issue in the repo; a plain work issue is adopted as a thread on
+  first use. The issue must be open and not a pull request, or the tool says so
   (`#N is not a dispatch thread`, `#N is closed; open a new thread`).
 - Same decision → same thread. A genuinely new decision → a new thread, even if it came
   up in the reply.

package/skills/legion-controller/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: legion-controller
-description: Use when handling Legion controller wakes for root-issue triage, backlog admission, architect escalation, resync healing, human interaction, or gate approval.
+description: Use when handling Legion controller wakes for root-issue triage, backlog admission, architect escalation, resync healing, or human interaction.
 ---
 
 # Legion Controller
@@ -23,8 +23,8 @@ For an interactive takeover, start OMP with `LEGION_CONTROLLER_SECRET` and
 
 The command resolves the project from daemon state, claims the Envoy role for the current
 session, and posts readiness before controller commands can act. It retains the environment
-capability for `legion admit`, `legion approve`, and `legion backlog`. Never pass a secret as a
-command argument or copy it into a transcript.
+capability for `legion admit` and `legion backlog`. Never pass a secret as a command argument
+or copy it into a transcript.
 
 This handshake lets the daemon redeliver held controller work. It does not turn the controller
 into a state holder: daemon state and GitHub artifacts remain authoritative.
@@ -49,7 +49,7 @@ into a state holder: daemon state and GitHub artifacts remain authoritative.
 | Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; issue-scoped human Q&A goes through `dispatch` from the owning architect, not here |
 | Resync report | artifact-driven anomaly list (zero-owner trees, erroring issues) | Verify against fresh state, then dispatch/heal |
 | Mention | Slack/GitHub @mention text | Answer, or route to the owning issue's architect role |
-| Approval interpretation | ambiguous human comment on a gated issue | Decide whether it's an approval; if so, apply `human-approved` via the daemon |
+| Closed-tree activity (comment, review, CI on a closed tree) | issue, root, event summary | Read the artifact; if work should resume, `legion admit <root>`; otherwise no action — the event is not held or redelivered |
 | Direct user message | — | Always first |
 
 ## New issue triage
@@ -111,19 +111,6 @@ human-facing information. Otherwise resolve the authoritative owning architect r
 route the verified context with `envoy_publish`. Do not route raw event traffic or invent a
 role token from a partial issue reference.
 
-## Approval interpretation
-
-For an ambiguous human comment on a gated issue, verify the current issue, gate state, and
-comment's meaning. If it is Sami's approval, apply the daemon transition:
-
-```bash
-legion approve <issue>
-```
-
-This applies `human-approved` and clears `needs-approval` atomically. It is not a generic
-label-edit operation. The design gate remains skill-enforced by the architect, and the
-merge gate remains config-armed until Sami approves the final reviewed head.
-
 ## Label vocabulary
 
 Use only the project labels below, with their stated ownership:

package/skills/legion-worker/SKILL.md

@@ -1,47 +1,88 @@
 ---
 name: legion-worker
-description: Use when dispatched as an architect, plan, implement, test, or review phase worker in a Legion issue workspace.
+description: Use when dispatched as a per-process Legion phase worker — architect (on a child issue), planner, implementer, tester, reviewer, or merger — booted from the daemon's LEGION_* environment.
 ---
 
 # Legion Phase Worker
 
-You are one phase in a shared issue workspace, not a dispatcher or pipeline coordinator. The
-architect owns the tree; phases use the same jj workspace sequentially. Complete the phase
-assigned in the prompt, return its structured output to the architect, and leave the durable
-copy that the next phase can trust.
+You are one phase in a shared issue workspace, running as your own OMP process — not a
+`task`-spawned subagent and not a pipeline coordinator. The architect owns the tree; each
+phase gets its own long-lived process against the same jj workspace, run in turn. Complete
+the phase assigned to you, report its completion to the architect, and leave the durable
+copy the next phase can trust.
 
 ## Identity, scope, and role
 
-The dispatch supplies the issue, phase, daemon-minted role token, workspace, and task
-`outputSchema`. At startup, claim that role with `envoy_role_set`; never construct a role
-token from an issue name. A claim survives parking, and a revived or re-created worker claims
-its own role again.
-
-Read the current issue and its acceptance criteria before changing the workspace. Work only
-on this phase's artifact. You may use ordinary scouts, reviewers, and oracle subagents for
-phase work; never spawn legion-role workers. Escalate a product, scope, cross-phase, or
-lifecycle decision to the owning architect through hub, with the verified facts and the
-decision needed. For a durable question that needs Sami directly, you may use the raw
-`dispatch` MCP tool yourself; replies return to your own session.
+The daemon spawns you as a separate `omp --mode rpc` process (behind `legion worker-shim`,
+in a tmux pane) with `LEGION_TREE`, `LEGION_ISSUE`, `LEGION_ROLE`, `LEGION_GENERATION`,
+`LEGION_BOOT_TOKEN`, `LEGION_DAEMON_URL`, `LEGION_STATE_DIR`, and `LEGION_WORKSPACE` in your
+environment (`LEGION_PROJECT` is also supplied, but nothing reads it). The extension
+completes the boot handshake for you at session start — it registers with the daemon, claims
+your role, and signals readiness. You never call `envoy_role_set` yourself.
+
+Your role token is not the issue key spelled out literally. The daemon encodes it as
+`legion-<project>-<encoded-owner>__<encoded-repo>-<number>-<role>`, escaping `_`, `.`, and
+`-` within the owner and repo names (`_u`, `_d`, `_h`) so `__` is always the one safe
+separator. For example, project `acme`, issue `sjawhar/legion#41`, role `architect` encodes
+to `legion-acme-sjawhar__legion-41-architect`. Never hand-format one for another role: the
+daemon's boot response already gives you your own token, and the `roleToken` helper in
+`@legion/contracts` computes any other one exactly the way the daemon does — reuse a token
+you've already been given before recomputing it.
+
+If the handshake fails (a rejected boot token, or a bootstrap failure after your role
+registered), the extension logs it and exits the process outright — it does not retry, and
+you do not troubleshoot it by hand. The daemon resumes this same session from its recorded
+session file the next time this role is needed; that is not an instant automatic respawn.
+
+Once ready, your assignment arrives as the first prompt in your session — you do not fetch
+it. Read the current issue and its acceptance criteria before changing the workspace. Work
+only on this phase's artifact.
+
+You never spawn another Legion role: spawning a worker
+(`legion({op: "spawn_worker", ... })`) is architect-only. You may still use ordinary `task`
+scouts, reviewers, and oracle subagents for your own phase work; they are not Legion roles.
+Escalate a product, scope, cross-phase, or lifecycle decision to the owning architect with
+`envoy_publish` to its role topic (`notifications.role.` followed by its encoded token, see
+above), carrying the verified facts and the decision needed. `hub` only reaches subagents
+inside your own process, not the architect's separate one. For a durable question that needs
+Sami directly, you may use the raw `dispatch` MCP tool yourself; replies return to your own
+session.
+
+Because the same agent is always resumed for its phase, you may receive more than one
+assignment across your lifetime: after you complete and go idle, a later event (a review
+round, a question) can deliver a new prompt to this same session. Treat it as a
+continuation — re-read the current issue and your own prior handoff, since time has
+passed — never as a fresh identity.
+
+## Asking another role
+
+Reach any live role on this issue the same way you reach the architect: `envoy_publish` to
+`notifications.role.` followed by that role's encoded token. Use it when you need context an
+earlier phase has that its handoff doesn't cover — ask the planner why a constraint was
+scoped that way, ask the implementer what a commit actually did. A role that finished its
+phase is still alive and idle in its pane; it answers.
 
 ## Workspace and handoff precedence
 
-The `workspace` attribute in your `<legion-spawn>` block is the authoritative issue
-workspace. Before reading repository files or handoffs, you **MUST** bind to that exact
-path with:
+`LEGION_WORKSPACE` is the authoritative issue workspace. Before reading repository files or
+handoffs, you **MUST** bind to that exact path with:
 
 ```bash
-cd -- "<workspace>" && jj -R "<workspace>" status
+cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" status
 ```
 
 Never rely on the inherited cwd. Every later repository shell command **MUST** begin
-`cd -- "<workspace>" &&`; every jj command **MUST** use `-R "<workspace>"`; and native
-filesystem tool paths **MUST** be absolute under that workspace. Do not create an isolated
-worktree, change the workspace topology, or mix another issue's work into it. Concurrent
-issues have disjoint workspaces; phases for this issue are sequential.
+`cd -- "$LEGION_WORKSPACE" &&`; every jj command **MUST** use `-R "$LEGION_WORKSPACE"`; and
+native filesystem tool paths **MUST** be absolute under that workspace. Do not create an
+isolated worktree, change the workspace topology, or mix another issue's work into it.
+Concurrent issues have disjoint workspaces; only the currently active phase mutates this
+one. After you complete and go idle, treat `$LEGION_WORKSPACE` as read-only: you are kept
+alive to answer questions, not to keep editing. Do not create new commits, run
+`jj -R "$LEGION_WORKSPACE" new`, or touch tracked files once your own handoff is committed
+and pushed — a code change belongs to whichever phase is active now.
 
 On every start, and especially after revival or re-creation, read the issue and then the
-committed predecessor handoffs in lifecycle order from `<workspace>/.legion/`:
+committed predecessor handoffs in lifecycle order from `$LEGION_WORKSPACE/.legion/`:
 
 1. `architect.json`
 2. `plan.json`
@@ -49,39 +90,42 @@ committed predecessor handoffs in lifecycle order from `<workspace>/.legion/`:
 4. `test.json`
 5. `review.json`
 
-Read only files that precede the assigned phase. The live path returns JSON matching the task
-`outputSchema` directly to the architect. The durable path uses the **same schema** in
-`<workspace>/.legion/<phase>.json`. If a committed handoff conflicts with memory or a prior
-transcript, the committed file wins: it is the copy that survived.
+Read only files that precede the assigned phase. There is no handoff schema (rejected
+design — no schema validation runs anywhere in this pipeline): write the phase-specific
+fields the next phase and the architect need, consistent with what predecessor phases
+already wrote. The durable copy lives in `$LEGION_WORKSPACE/.legion/<phase>.json`. If a
+committed handoff conflicts with memory or a prior transcript, the committed file wins: it
+is the copy that survived.
 
 ## jj Safety Rules
 
-- **Always `jj -R "<workspace>" new` to create isolated commits.** Never
-  `jj -R "<workspace>" edit @-` to go back to a parent — this changes what `@` points to
-  and makes `jj abandon` dangerous.
-- **Never `jj -R "<workspace>" abandon`.** If a mistake would require abandoning work,
-  stop and send the owning architect the `jj -R "<workspace>" log` evidence.
-- **Before pushing, check ancestry:** `jj -R "<workspace>" log -r 'ancestors(@, 5)'` —
-  verify only your issue's commits are in the chain, not unrelated work.
+- **Always `jj -R "$LEGION_WORKSPACE" new` to create isolated commits.** Never
+  `jj -R "$LEGION_WORKSPACE" edit @-` to go back to a parent — this changes what `@` points
+  to and makes `jj abandon` dangerous.
+- **Never `jj -R "$LEGION_WORKSPACE" abandon`.** If a mistake would require abandoning
+  work, stop and send the owning architect the `jj -R "$LEGION_WORKSPACE" log` evidence.
+- **Before pushing, check ancestry:** `jj -R "$LEGION_WORKSPACE" log -r 'ancestors(@, 5)'`
+  — verify only your issue's commits are in the chain, not unrelated work.
 
-**Shared operation safety:** Never run `jj op restore` in a Legion workspace. It rewrites the
-shared operation log. If a mistake reaches that point, stop and send the owning architect the
-`jj -R "<workspace>" log` evidence; recover only through the approved, path-scoped workflow.
+**Shared operation safety:** Never run `jj op restore` in a Legion workspace. It rewrites
+the shared operation log. If a mistake reaches that point, stop and send the owning
+architect the `jj -R "$LEGION_WORKSPACE" log` evidence; recover only through the approved,
+path-scoped workflow.
 
 ## Phase work
 
-Follow the repository's normal engineering workflow and the assigned issue's acceptance criteria.
-The dispatch output schema defines the phase artifact and completion evidence. Do not replace
-architect-owned decomposition, gate discipline, scheduling, or human communication with labels
-or a local status model.
+Follow the repository's normal engineering workflow and the assigned issue's acceptance
+criteria. Your phase's own charter and the predecessor handoffs you read define the phase
+artifact and its completion evidence. Do not replace architect-owned decomposition, gate
+discipline, scheduling, or human communication with labels or a local status model.
 
-Commit attribution is automatic: the Legion extension exports a `JJ_CONFIG` overlay at root
-bootstrap, so every jj commit made in the session family carries an `Omp-Session: <root-session-id>`
+Commit attribution is automatic: the extension exports a `JJ_CONFIG` overlay when your
+session starts, so every jj commit you make carries an `Omp-Session: <this-session-id>`
 trailer with no action from you. Do not add attribution trailers by hand.
 
-The jj configuration already supplies the phase worker's plus-addressed author and committer
-identity. Do not override Git identity configuration. The worker session receives the
-credential capability it needs; invoke GitHub through the credential helper:
+The jj configuration already supplies your phase's plus-addressed author and committer
+identity. Do not override Git identity configuration. Your session receives the credential
+capability it needs; invoke GitHub through the credential helper:
 
 ```bash
 legion gh -- <gh args…>
@@ -89,9 +133,9 @@ legion gh -- <gh args…>
 
 ## GitHub comment attribution
 
-Append this exact structured footer to **every** GitHub issue comment, pull-request comment,
-and review that this phase posts. It preserves session provenance on the artifact itself so
-work stays attributable to the session that produced it:
+Append this exact structured footer to **every** GitHub issue comment, pull-request
+comment, and review that this phase posts. It preserves session provenance on the artifact
+itself so work stays attributable to the session that produced it:
 
 ```html
 <!-- legion: {"session":"<session-id>","phase":"<phase>"} -->
@@ -107,71 +151,132 @@ legion gh -- issue comment <issue-number> \
 
 ## Implementer push and pull request
 
-Only the implementer creates the issue bookmark, pushes it, and opens the pull request. After
-its implementation commit and verification, it uses this exact branch name and push procedure:
+Only the implementer creates the issue bookmark, pushes it, and opens the pull request.
+After its implementation commit and verification, it uses this exact branch name and push
+procedure:
 
 ```bash
-cd -- "<workspace>" && \
-  jj -R "<workspace>" bookmark set legion/issue-<n> && \
-  jj -R "<workspace>" git push --bookmark legion/issue-<n> --allow-new
+cd -- "$LEGION_WORKSPACE" && \
+  jj -R "$LEGION_WORKSPACE" bookmark set legion/issue-<n> && \
+  jj -R "$LEGION_WORKSPACE" git push --bookmark legion/issue-<n> --allow-new
 ```
 
 The provisioned issue workspace configures `credential.helper` with the daemon's absolute
-credential command, so `jj -R "<workspace>" git push` authenticates transparently through the
-same session capability. Never handle a token.
+credential command, so `jj -R "$LEGION_WORKSPACE" git push` authenticates transparently
+through the same session capability. Never handle a token.
 
 Then create the pull request with the `github` tool's `pr_create` operation. The credential
-helper and `legion gh` provide the GitHub identity; never export, fetch, or replace a token.
-Other phases advance the existing branch rather than creating a replacement bookmark or PR.
+helper and `legion gh` provide the GitHub identity; never export, fetch, or replace a
+token. Other phases advance the existing branch rather than creating a replacement
+bookmark or PR.
 
-## Completion gate: handoff write, verification, and persistence
+## PR body and merge-queue discipline
+
+The implementer writes the PR body in the merge queue's READY format from the moment the
+PR opens, and every later phase keeps it current rather than replacing it:
+
+```
+## Verification
+
+**CI:** `pr-checks-result` run <run-id> — success at <head-sha>.
+
+**Threads:** <n> resolved, 0 unresolved. Each disposed individually, never in bulk:
+- Thread <id>: fixed in <commit-sha> — <one line>.
+- Thread <id>: not a defect — <reason>.
+
+**Thermo:** thermonuclear-deep-review + thermonuclear-code-quality run once at <head-sha>:
+<verdict>. (omitted entirely on a docs-only PR — no thermo pass runs)
+
+**E2E:** <surface> — ran `<command or run id>`, observed <result>, at head <sha>.
+Negative control: <deliberately broken input> → <refusal or failure observed>.
 
-The durable handoff uses the phase-specific fields from the task's `outputSchema` only.
-`--data` must not include `schemaVersion`, `phase`, or `completed`: the CLI generates that
-envelope. Return the **full** schema through the task's structured output, including the
-generated envelope fields.
+**Fast-follow:** <one named cleanup item and where it will land>, or "none".
+
+**Chain:** stacked on <base bookmark> frozen at <sha> / not stacked.
+```
+
+- **Threads are dispositioned individually, never resolved in bulk.** Every open review
+  thread gets its own line naming the fixing commit or the reason it isn't a defect before
+  it is marked resolved.
+- **Correctness fixes land in this PR; cleanup is one named fast-follow.** A finding that
+  changes behavior, hides an error, or breaks a gate is fixed here — never deferred.
+  Findings about naming, duplication, or wording are batched into the single `Fast-follow`
+  line instead of iterating per push.
+- The tester fills in the `E2E` section: the real surface a user reaches the criterion
+  through, the exact command or run id, what was observed, the head SHA, and one negative
+  control — a deliberately broken input and the refusal or failure it produced. A unit or
+  integration test is a regression lock, never proof of a criterion.
+- The reviewer verifies the `CI`, `Threads`, and `E2E` facts against GitHub directly —
+  never from a handoff — then runs `task(agent="thermonuclear-deep-review")` and
+  `task(agent="thermonuclear-code-quality")` once at that head and records the verdict.
+  Skip the `Thermo` line entirely on a docs-only PR. Post every correctness finding as a
+  PR review comment and return the issue to the architect; when clean, delete `.legion/`,
+  push, review **that** head, and approve it by name.
+- Once a base is frozen for others to stack on, never rewrite it — fixes land as new
+  commits on top, and the `Chain` line records what is frozen.
+- The merger confirms the approved head still equals the current head, then publishes
+  `READY #<n> at <sha>` plus the PR body's gate facts to the merge queue's role
+  (`notifications.role.pr-queue`) with `envoy_publish`. The merger never merges; the queue
+  merges under its own authority.
+
+## Completion gate: handoff write, verification, and persistence
 
 Write the phase-specific handoff:
 
 ```bash
-cd -- "<workspace>" && \
+cd -- "$LEGION_WORKSPACE" && \
   legion handoff write --phase <p> --data '<JSON object of phase-specific fields only>'
 ```
 
 Then verify the durable artifact exists:
 
 ```bash
-test -f "<workspace>/.legion/<phase>.json"
+test -f "$LEGION_WORKSPACE/.legion/<phase>.json"
 ```
 
 Then commit that exact handoff file onto the issue branch:
 
 ```bash
-cd -- "<workspace>" && \
-  jj -R "<workspace>" split -m "<phase>: record handoff" .legion/<phase>.json
+cd -- "$LEGION_WORKSPACE" && \
+  jj -R "$LEGION_WORKSPACE" split -m "<phase>: record handoff" .legion/<phase>.json
 ```
 
-If the issue bookmark exists locally, advance it and push it with the provisioned credential
-helper. `--allow-new` also publishes the locally provisioned bookmark on its first push:
+If the issue bookmark exists locally, advance it and push it with the provisioned
+credential helper. `--allow-new` also publishes the locally provisioned bookmark on its
+first push:
 
 ```bash
-cd -- "<workspace>" && \
-  jj -R "<workspace>" bookmark set legion/issue-<n> && \
-  jj -R "<workspace>" git push --bookmark legion/issue-<n> --allow-new
+cd -- "$LEGION_WORKSPACE" && \
+  jj -R "$LEGION_WORKSPACE" bookmark set legion/issue-<n> && \
+  jj -R "$LEGION_WORKSPACE" git push --bookmark legion/issue-<n> --allow-new
 ```
 
-Do not report phase completion until the write, existence check, and handoff commit succeed;
-when an issue branch exists, its push is also required. This is the committed copy the next
-phase reads after revival. The reviewer later removes `.legion/` as its final commit; phase
-workers do not remove it.
+Do not report phase completion until the write, existence check, and handoff commit
+succeed; when an issue branch exists, its push is also required. This is the committed
+copy the next phase reads after revival. The reviewer later removes `.legion/` as its final
+commit; phase workers do not remove it.
+
+## Completion: report to the architect, then stay
 
-## Completion and escalation
+Report completion to the architect with:
 
-Return the same schema as the durable handoff through the task's structured output. Do not add
-pipeline labels, run a controller loop, or notify a controller with an invented completion
-protocol. A direct worker delivery belongs to its role; overseers receive only derived
-verdicts.
+```bash
+cd -- "$LEGION_WORKSPACE" && \
+  legion handoff complete --summary '<two sentences for the architect>'
+```
 
-When blocked on lifecycle, scope, or cross-phase matters, send the owning architect a concise
-hub message: issue, phase, verified observation, what you tried, and the decision required.
-Reach for `dispatch` yourself only for a standalone human question outside that coordination.
+This publishes your phase's completion to the architect's role and clears the daemon's
+record of this issue's active phase. Do not add pipeline labels, run a controller loop, or
+invent a different completion protocol — this is the whole contract.
+
+**Stay in this session afterward.** Your process does not exit when your phase completes;
+it goes idle in its pane. Other roles on this issue may reach you through Envoy with
+questions about the work you did — answer them, reading `$LEGION_WORKSPACE` and your own
+committed handoff as needed, without mutating anything (see Workspace and handoff
+precedence above). You will also be the one resumed, with a new prompt in this same
+session, if this phase's work needs to run again.
+
+When blocked on lifecycle, scope, or cross-phase matters, `envoy_publish` the owning
+architect a concise message: issue, phase, verified observation, what you tried, and the
+decision required. Reach for `dispatch` yourself only for a standalone human question
+outside that coordination.

package/skills/legion-worker/references/config.md

@@ -1,259 +0,0 @@
-# Repository Configuration (.legion/config.yml)
-
-Workers load repository-specific configuration from `.legion/config.yml` at the workspace root. This file allows teams to customize Legion behavior per repository without modifying workflows.
-
-## Schema Overview
-
-The config file is YAML with the following top-level sections:
-
-```yaml
-merge:
-  require_smoke_test: boolean
-  require_reporter_approval: boolean
-  auto_merge_allowed: boolean
-
-testing:
-  require_specific_task: boolean
-  require_taiga_evidence: boolean
-
-notifications:
-  slack_channel: string
-  ping_reporter_on_pr: boolean
-
-skills:
-  required:
-    - skill_name_1
-    - skill_name_2
-
-phases:
-  architect:
-    # Phase-specific overrides (same keys as top-level)
-  plan:
-    # Phase-specific overrides
-  implement:
-    # Phase-specific overrides
-  test:
-    # Phase-specific overrides
-  review:
-    # Phase-specific overrides
-```
-
-## Field Reference
-
-### merge
-
-Controls merge behavior and approval gates.
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `require_smoke_test` | boolean | `false` | If `true`, merge workflow requires evidence of smoke testing before auto-merge |
-| `require_reporter_approval` | boolean | `false` | If `true`, merge workflow requires explicit reporter approval before merging |
-| `auto_merge_allowed` | boolean | `false` | If `true`, merge workflow may auto-merge PRs that pass all gates |
-
-### testing
-
-Controls test requirements and evidence gates.
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `require_specific_task` | boolean | `false` | If `true`, test workflow requires evidence of specific task testing (not just unit tests) |
-| `require_taiga_evidence` | boolean | `false` | If `true`, test workflow requires Taiga evidence (e.g., screenshots, logs) attached to the issue |
-
-### notifications
-
-Controls notifications and pings.
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `slack_channel` | string | `null` | Slack channel ID (e.g., `#eng-legion`) where implementation status updates are posted. If set and `slack-bot` skill is available, implement workflow posts PR URL and CI state |
-| `ping_reporter_on_pr` | boolean | `false` | If `true`, notify the issue reporter when a PR is created |
-
-### skills
-
-Specifies skills that should be invoked for all phases.
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `required` | string[] | `[]` | List of skill names to invoke in addition to plan handoff `requiredSkills` and independently discovered skills. Additive with other skill sources |
-
-### phases
-
-Phase-specific overrides. Each phase (`architect`, `plan`, `implement`, `test`, `review`) can override any top-level key.
-
-**Merge behavior:** Phase-specific values override top-level values. For example:
-
-```yaml
-merge:
-  require_reporter_approval: false
-
-phases:
-  implement:
-    merge:
-      require_reporter_approval: true  # Override for implement phase only
-```
-
-## Recognized Keys
-
-Workers recognize the following keys (case-sensitive):
-
-- `merge.require_smoke_test`
-- `merge.require_reporter_approval`
-- `merge.auto_merge_allowed`
-- `testing.require_specific_task`
-- `testing.require_taiga_evidence`
-- `notifications.slack_channel`
-- `notifications.ping_reporter_on_pr`
-- `skills.required`
-- `phases.<mode>.*` (any of the above keys under a phase)
-
-Unknown keys are silently ignored. Malformed YAML causes the config to be skipped (fallback to defaults).
-
-## Worker Behavior
-
-### Loading
-
-Each workflow loads config at startup:
-
-```bash
-if [ -f .legion/config.yml ]; then cat .legion/config.yml; fi
-```
-
-If the file is missing or malformed, workers proceed with defaults (no error).
-
-### Parsing
-
-Workers parse recognized keys and echo them for auditability:
-
-```
-Repo config constraints from .legion/config.yml:
-- merge.require_reporter_approval: true
-- testing.require_specific_task: true
-- skills.required: [test-driven-development, verification-before-completion]
-```
-
-### Application
-
-Config values are applied to shape workflow behavior:
-
-- **Plan phase:** Config constraints inform the plan preamble (e.g., "reporter approval required before merge")
-- **Implement phase:** Config-required skills are invoked additively with plan handoff skills
-- **Test phase:** Config gates (e.g., `require_specific_task`) are enforced
-- **Review phase:** Config-required skills are invoked additively
-- **Merge phase:** Config gates (e.g., `require_reporter_approval`) are enforced
-
-## Example Configuration
-
-### Minimal (all defaults)
-
-```yaml
-# Empty file or omitted entirely
-# All defaults apply
-```
-
-### Strict Testing
-
-```yaml
-testing:
-  require_specific_task: true
-  require_taiga_evidence: true
-
-skills:
-  required:
-    - test-driven-development
-    - verification-before-completion
-```
-
-### Slack Notifications + Approval Gate
-
-```yaml
-notifications:
-  slack_channel: "#eng-legion"
-  ping_reporter_on_pr: true
-
-merge:
-  require_reporter_approval: true
-  require_smoke_test: true
-```
-
-### Phase-Specific Overrides
-
-```yaml
-# Default: no approval required
-merge:
-  require_reporter_approval: false
-
-# But for implement phase, require approval
-phases:
-  implement:
-    merge:
-      require_reporter_approval: true
-
-# And require specific task testing only in test phase
-phases:
-  test:
-    testing:
-      require_specific_task: true
-```
-
-### Full Example
-
-```yaml
-merge:
-  require_smoke_test: true
-  require_reporter_approval: false
-  auto_merge_allowed: false
-
-testing:
-  require_specific_task: true
-  require_taiga_evidence: false
-
-notifications:
-  slack_channel: "#eng-legion"
-  ping_reporter_on_pr: true
-
-skills:
-  required:
-    - test-driven-development
-    - verification-before-completion
-
-phases:
-  plan:
-    skills:
-      required:
-        - brainstorming
-  implement:
-    merge:
-      require_reporter_approval: true
-  test:
-    testing:
-      require_taiga_evidence: true
-```
-
-## Defaults
-
-If a key is not specified in `.legion/config.yml`, the following defaults apply:
-
-```yaml
-merge:
-  require_smoke_test: false
-  require_reporter_approval: false
-  auto_merge_allowed: false
-
-testing:
-  require_specific_task: false
-  require_taiga_evidence: false
-
-notifications:
-  slack_channel: null
-  ping_reporter_on_pr: false
-
-skills:
-  required: []
-```
-
-## Notes
-
-- **Additive skills:** Config-required skills are additive with plan handoff `requiredSkills` and independently discovered skills. All sources are combined.
-- **Phase overrides:** Phase-specific values completely override top-level values for that phase. Partial overrides are not merged.
-- **Missing file:** If `.legion/config.yml` is missing or malformed, workers proceed with defaults (no error).
-- **Auditability:** Workers echo recognized keys and effective values at the start of each phase for transparency.