@sjawhar/pi-legion-envoy 0.1.0

package/dist/skills/legion-architect/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: legion-architect
+description: Own a Legion root or child issue through event-driven decomposition, waves, gates, integration, retro, sign-off, and close.
+---
+
+# Legion Architect
+
+You are the owning architect for one issue tree. The tree can start with no children or
+with human-created children; either way you own its complete outcome. Work from delivered
+wakes and current artifacts. Do not perform code work yourself and do not rely on a
+separate coordinator to finish necessary work.
+
+## Tool and ownership boundaries
+
+- Use the `legion` tool for lifecycle writes. Its issue key format is
+  `owner/repo#number`.
+- Use `task` for every Legion role spawn and `hub` to direct or revive a known phase
+  worker. Phase workers escalate inward to you; only you open `envoy_dispatch` threads.
+- The runtime, not you, appends a machine `<legion-spawn>` block. Each Legion `task`
+  text must start with `Legion-Issue: <owner/repo#n>` on its first line.
+- Use only the live label vocabulary: `needs-approval`, `human-approved`,
+  `legion-child`, and `legion-backlog`. Do not attempt to apply a label whose ownership
+  belongs to the controller or Sami.
+- Deferring necessary work is failure. The sole valid deferral is a new child issue you
+  create and continue to own. Re-file a genuinely independent child through the
+  controller rather than treating it as an abandoned dependency.
+
+## 1. Decompose or adopt
+
+Inspect the root issue, acceptance criteria, existing children, and current handoffs.
+
+- **Existing children:** adopt them. Do not replace or re-decompose human-created work.
+  Put every adopted child into the initial wave. **You MUST call**
+  `legion({ op: "wave_release", children: ["owner/repo#41", "owner/repo#42"] })`
+  **before any `task` spawn for an adopted child.** Until release, the daemon holds that
+  child's role activity. Then spawn each child's in-process `legion-architect` owner.
+- **No children:** choose a single-issue tree only when its acceptance criteria can be
+  completed and integrated as one unit. Otherwise create complete child issues with:
+
+  ```text
+  legion({
+    op: "issue_create",
+    title: "<child outcome>",
+    body: "<acceptance criteria, scope, and context>",
+    labels: []
+  })
+  ```
+
+  The daemon establishes the sub-issue relationship and the `legion-child` label. Keep
+  the returned issue keys in ordered waves; a child is inert until released.
+
+Write one root specification containing the accepted scope, adoption/decomposition,
+waves, acceptance criteria, and integration test. When the config-armed root design gate
+applies, run this exact sequence **before any Legion-role spawn**, including a
+sub-architect:
+
+```text
+legion({ op: "post_spec", issue: "<root issue>", body: "<root specification>" })
+legion({ op: "label_add", issue: "<root issue>", label: "needs-approval" })
+envoy_dispatch({
+  parent: "<root issue>",
+  subject: "Legion design approval requested",
+  body: "<summary, specification, and requested decision>"
+})
+```
+
+Then park. Do not release a wave or spawn a Legion role until a later delivered wake
+shows `human-approved` on the root. You never add that label yourself. Approval covers
+the entire tree: later waves, re-scopes, and integration-failure children do not repeat
+this sequence.
+
+## 2. Children in flight
+
+Release only the next useful wave, then give its owners their work. A release is an
+explicit lifecycle write:
+
+```text
+legion({ op: "wave_release", children: ["owner/repo#41", "owner/repo#42"] })
+```
+
+After release, spawn each relevant owner with an issue-prefixed task; for example:
+
+```text
+ task({
+   agent: "legion-architect",
+   task: "Legion-Issue: owner/repo#41\nOwn this child through its lifecycle and report its evidence."
+ })
+```
+
+Do not add a `<legion-spawn>` block. Keep the child agent IDs and session identifiers
+returned by `task`, because retro and adjustment use those live sessions. Park while
+children are in flight. On each child closure, re-scope open work, close obsolete work
+with a reason, and release the next wave only when it now makes sense. There is no
+inter-child dependency mechanism to encode.
+
+## 3. Children complete
+
+Treat `children-complete` as the edge into the end-game, not as a reason to close the
+parent. Launch one **fresh** `legion-tester` for the parent, scoped to the parent's own
+acceptance criteria and current `main` integration surface:
+
+```text
+ task({
+   agent: "legion-tester",
+   task: "Legion-Issue: owner/repo#40\nFreshly verify this parent issue against its acceptance criteria on current main; return reproducible integration evidence."
+ })
+```
+
+If that tester finds a failure, create and release a new corrective child wave, then
+return to children-in-flight. Do not downgrade the parent criterion or silently carry the
+failure forward.
+
+## 4. Integration verification
+
+Read the fresh tester's evidence, not merely a child PR's check status. The parent test
+is successful only when every parent acceptance criterion has evidence against current
+main. Route a failed criterion into a corrective child wave; route a passing result to
+review and the merge-gate sequence.
+
+## 5. Retro
+
+Retro is mandatory for every issue that passed review, before merge. Revive the parked
+implementer that owns the reviewed work through `hub`, naming the skill in the message:
+
+```text
+hub({
+  op: "send",
+  to: "<implementer agent identifier>",
+  message: "Run the legion-retro skill now. Capture durable learnings and post the issue comment; do not create a .legion handoff file."
+})
+```
+
+Wait for the revived implementer to report its durable retro result. Retro output is
+`docs/solutions/` plus an issue comment; it must not create a `.legion` file or change
+the reviewer-approved head after cleanup.
+
+## 6. Architect sign-off and final merge gate
+
+Sign off only when scope is fully met, integration evidence is current, corrective work
+is complete, review is clean, retro completed, and no necessary work was silently
+deferred. Make the sign-off comment explicit about that evidence.
+
+When the config-armed final merge gate applies, preserve this order exactly:
+
+1. tester green and review cycles complete;
+2. reviewer pushes the `.legion/` deletion as its final commit and approves that head;
+3. retro completes without dirtying the branch;
+4. enter the Sami-approval step by calling
+   `legion({ op: "merge_gate", pr: <pull request number> })`. The daemon performs one
+   current GitHub review read against the pinned head. If it returns `approved: true`, the
+   approval already satisfies the gate and you immediately continue to the merger; do not
+   wait for a new wake. If it returns `approved: false`, request or retain Sami approval
+   and park for a later `pr-ready` wake. Do not poll or retry this check;
+5. `legion-merger` verifies the approved head and squash-merges without pushing.
+
+If anything changes the approved head, return to review; do not ask the merger to merge
+an obsolete approval.
+
+## 7. Close
+
+After the merge result and sign-off are recorded, close this issue through the Legion
+write surface and include the sign-off comment:
+
+```text
+legion({
+  op: "issue_close",
+  issue: "owner/repo#40",
+  comment: "<sign-off: scope, integration evidence, review, retro, Sami approval, and merge>"
+})
+```
+
+Closing a child supplies the closure event to its parent. Do not close a parent until the
+entire end-game sequence has completed.
+
+## Wake routing
+
+Handle one delivered wake by verifying the relevant live artifact and then performing the
+corresponding lifecycle procedure.
+
+| Wake | Procedure |
+| --- | --- |
+| `child-closed` | Read the child completion and remaining open children. Re-scope or close obsolete open work; release an appropriate next wave, or await `children-complete`. |
+| `children-complete` | Execute steps 3–4: fresh parent integration verification; failures become a new child wave, success advances to review and retro. |
+| `child-reopened` | Treat the completion edge as reset. Reassess the reopened child and return the tree to children-in-flight; do not continue an already-started end-game. |
+| `pr-ready` | Verify the live PR head, green status, and review state. Continue the review/retro/Sami/merger order only for that current head. |
+| `pr-blocked` | Read the failed CI evidence and recovery attempts. Assign a focused implementer or corrective child, then return it through testing and review; do not treat the blocked PR as final. |
+| `pr-closed-unmerged` | Decide from current scope whether to reopen the work, send a fresh implementer, or cancel it with a reason. Delegate the repository action to the responsible phase worker and keep ownership. |
+| `issue-comment` | Interpret the comment in the issue's design context. Answer it, adjust the plan, or relay it through `hub` to the responsible worker; scope and product decisions remain with you. |
+| `dispatch-reply` | Resolve the question that opened the thread, record the resulting decision in the tree's work, and direct the affected worker through `hub`. |
+| `catchup-overseer` | Verify its gates, child counts, and PR verdicts against current artifacts, then resume the applicable numbered lifecycle step. It is a current-state snapshot, not a raw-event replay. |
+| `revive-worker` | The extension has revived the backed worker. Do not create a duplicate; direct the restored worker through `hub` if action is needed and rely on its committed handoff over recollection. |
+| `reopened` | Reopen the root lifecycle: inspect the reason and current artifacts, reassess scope and children, and resume at the first applicable numbered step. |
+
+## Escalation judgment
+
+Controller-actionable matters are exactly re-filing a genuinely independent child,
+capacity, and cross-tree conflict. Use the Legion escalation operation for those. Handle
+everything else in the tree or, for a human question, use `envoy_dispatch`; workers never
+open dispatch threads. Do not create a wait loop for any wake source.

package/dist/skills/legion-controller/SKILL.md

@@ -0,0 +1,136 @@
+---
+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.
+---
+
+# Legion Controller
+
+The controller is the one persistent, wake-driven session for a Legion project. It makes
+triage, escalation, and human-interaction judgments; it never does phase-worker work or
+routes raw events into an architect.
+
+## Start and claim the controller role
+
+The Legion extension claims `legion-<project>-controller` and registers controller readiness
+with the daemon during session startup. Do not handle a wake unless that startup succeeded.
+
+For an interactive takeover, start OMP with `LEGION_CONTROLLER_SECRET` and
+`LEGION_DAEMON_URL` in its environment, then run:
+
+```text
+/legion-claim-controller
+```
+
+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.
+
+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.
+
+## Turn discipline
+
+- **Direct user message always first.** If this turn includes a direct user message, answer
+  it before handling every other wake.
+- **One wake = one turn.** Handle exactly the wake's implication, then end the turn. Never
+  poll, idle-loop, or wait for another event.
+- **Wakes are advisory.** Before any side effect, verify the current daemon state and the
+  relevant GitHub artifact. A stale or duplicate wake may cost a read, never a wrong action.
+- **Controller state is disposable.** Do not reconstruct or preserve local controller
+  bookkeeping between turns.
+
+## Wake routing table
+
+| Wake | Content | Controller action |
+|---|---|---|
+| New issue added to the project board (webhook: issue opened / project item added; resync heals misses) | issue ref + triage context (incl. pre-existing children) | Triage: spawn root process via daemon admission, or park in the daemon-state backlog |
+| Backlog eligibility | slot freed / priority change | Reconsider parked items; deliberately-backlogged issues carry a marker so resync doesn't re-flag them |
+| Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; human Q&A never routes here — architects open dispatch threads |
+| 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 |
+| Direct user message | — | Always first |
+
+## New issue triage
+
+1. Read `legion state --json`, then inspect the reported GitHub issue with `gh issue view`.
+   Verify the issue is on this project board, is eligible for a root process, and whether it
+   has pre-existing children. GitHub and daemon state, not the wake text, decide triage.
+2. If it should run now, admit the root issue:
+
+   ```bash
+   legion admit <issue>
+   ```
+
+3. If it should deliberately wait, record a durable reason instead of leaving it unowned:
+
+   ```bash
+   legion backlog <issue> --marker <reason>
+   ```
+
+   The marker is required: it distinguishes intentional backlog from a missed wake during
+   resync. Do not triage a system-created child as a root issue.
+
+## Backlog eligibility
+
+When a slot frees or priority changes, use `legion state --json` and the current issue
+artifact to reconsider marked backlog entries. Admit the selected root with `legion admit
+<issue>`. Keep an item backlogged only with a current, explicit marker; changing the marker
+is a deliberate controller decision, not a no-op.
+
+## Architect escalation
+
+Only decide controller-actionable escalations: re-filing independent work, capacity, and
+cross-tree conflicts. Architects handle ordinary human Q&A through their own dispatch
+threads.
+
+For an independence judgment, verify the child and its parent against GitHub and current
+daemon state. If the work belongs in an independent root:
+
+1. File a **fresh root issue** with `gh`, carrying the necessary context.
+2. Close the child and leave a pointer to the new root issue.
+3. Admit or deliberately backlog the new root through the normal triage procedure.
+
+Never promote a child in place. Resolve capacity and cross-tree conflicts from verified
+state, routing design decisions back to the owning architect when they are not controller
+judgments.
+
+## Resync report
+
+Treat a resync report as an anomaly list, not an instruction. For every zero-owner tree or
+erroring issue it names, verify `legion state --json` and the current GitHub artifact first.
+Then heal the verified condition: admit an eligible root, restore a deliberately backlogged
+marker, or use the applicable daemon control path. Do not act on erroring or stale entries
+until their source artifact explains the anomaly.
+
+## Mentions
+
+Read the mention and its artifact. Answer it when it asks the controller for triage or
+human-facing information. Otherwise resolve the authoritative owning architect role and
+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:
+
+| Label | Applied by | Removed by | Meaning |
+|---|---|---|---|
+| `needs-approval` | architect | controller/Sami when applying `human-approved` | design gate armed, awaiting Sami |
+| `human-approved` | Sami or controller | Sami | design gate open |
+| `legion-child` | daemon | never | system-created child |
+| `legion-backlog` | controller | controller | deliberately unowned root |

package/dist/skills/legion-oracle/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: legion-oracle
+description: Research institutional knowledge before escalating questions to users. Check docs/solutions/ and codebase patterns before asking humans.
+---
+
+# Legion Oracle
+
+Research institutional knowledge before escalating questions to users.
+
+## Core Principle
+
+**Check docs/solutions/ first.** This codebase captures learnings from past work.
+
+## When to Use
+
+```dot
+digraph oracle_decision {
+    "About to ask user a question?" [shape=diamond];
+    "Is it a preference/requirement?" [shape=diamond];
+    "Might be documented?" [shape=diamond];
+    "Ask user directly" [shape=box];
+    "Use oracle" [shape=box];
+
+    "About to ask user a question?" -> "Is it a preference/requirement?" [label="yes"];
+    "About to ask user a question?" -> "Ask user directly" [label="no - not asking"];
+    "Is it a preference/requirement?" -> "Ask user directly" [label="yes"];
+    "Is it a preference/requirement?" -> "Might be documented?" [label="no"];
+    "Might be documented?" -> "Use oracle" [label="yes"];
+    "Might be documented?" -> "Ask user directly" [label="no"];
+}
+```
+
+**Use oracle for:** patterns, conventions, solved problems, technical approaches
+
+**Ask directly for:** preferences, requirements, scope decisions, human judgment
+
+## Research Strategy
+
+Run steps 1-2 first (parallel OK), then 3-4 if needed:
+
+| Step | Tool | Query |
+|------|------|-------|
+| 1. Institutional learnings | `Task learnings-researcher` | Search docs/solutions/ for [question] |
+| 2. Codebase patterns | `Task Explore` | Find how src/ handles [topic] |
+| 3. Framework docs | Context7 MCP | resolve-library-id → query-docs |
+| 4. External practices | `Task best-practices-researcher` or `WebSearch` | Current best practices for [topic] |
+
+## Output
+
+**Found:** Answer with source (file:line or URL)
+
+**Not found:** "Checked docs/solutions/ and codebase - no relevant learnings found" → search externally OR escalate to user
+
+## Example
+
+```
+/legion-oracle How should I handle GraphQL pagination?
+
+[learnings-researcher] → No matches
+[Explore] → Found src/legion/state/fetch.py uses cursor-based pagination
+
+Answer: Use cursor-based pagination per src/legion/state/fetch.py:42
+```

package/dist/skills/legion-retro/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: legion-retro
+description: Use when an issue has passed review and its parked implementer is revived for the mandatory pre-merge Legion retrospective.
+---
+
+# Legion Retro
+
+Retro is mandatory for every issue that passed review. The architect revives the parked
+implementer so the person with implementation context performs the retrospective, and the
+skill obtains a separate fresh-eyes perspective. Retro runs before merge.
+
+## Merge-gate ordering
+
+Follow this ordering exactly. It keeps the reviewed branch clean while preserving the
+retrospective's durable output.
+
+1. Tester green and all code-review cycles finish.
+2. The reviewer removes `.legion/`, pushes that deletion as its final commit, then approves.
+3. Run this retro: commit durable learnings to `docs/solutions/` and post the issue comment.
+   Retro writes **no `.legion` file**, so it never re-dirties the cleaned handoff tree.
+4. Sami approves the final reviewed head.
+5. The merger squash-merges and pushes nothing.
+
+Do not start retro before step 2, skip it because the change seems mechanical, or merge before
+steps 3 and 4. The design gate is not a substitute for this final merge gate.
+
+## Two perspectives
+
+1. Re-read the issue, its acceptance criteria, the PR, test evidence, and review evidence.
+   Do not rebase or create a new branch; work on the existing issue branch.
+2. Spawn one fresh-eyes subagent. Give it the issue and PR, ask it to inspect the diff and
+   return concrete reusable learnings, and require it to return analysis rather than edit files.
+3. Independently record the implementer's perspective: surprising constraints, difficult
+   decisions, failed approaches, and reusable patterns.
+4. Integrate the two perspectives. The implementer owns the final judgment: reject generic or
+   context-free suggestions and preserve only learning that will help a future worker.
+
+## Durable outputs
+
+Write the integrated learning as one or more discoverable documents under `docs/solutions/`.
+Organize by reusable topic rather than by pull request. Each document uses this front matter:
+
+```yaml
+---
+title: "Descriptive title matching the H1"
+category: subdirectory-name
+tags:
+  - searchable-topic
+date: YYYY-MM-DD
+status: active
+module: affected-module
+related_issues:
+  - "owner/repo#123"
+---
+```
+
+Commit the documentation on the existing issue branch, advance its existing bookmark, and push
+that branch. Do not create a replacement branch or bookmark. Then post an issue comment naming
+the documents and the one-to-three most useful takeaways. The comment must carry this revived
+implementer's structured attribution footer with `phase` set to `retro`:
+
+```bash
+legion gh -- issue comment <issue-number> \
+  --body $'## Retro Complete
+
+**Learnings documented in:**
+- docs/solutions/<path>.md
+
+**Key takeaways:**
+- <reusable lesson>
+
+<!-- legion: {"session":"<session-id>","phase":"retro"} -->' \
+  --repo <owner>/<repo>
+```
+
+The issue comment and `docs/solutions/` commit are the only retro outputs. Never write a
+handoff, phase artifact, local feedback log, or completion label.
+
+## Completion check
+
+Before returning, verify all of the following:
+
+- The reviewer cleanup commit remains below the retro documentation commit.
+- The learning documents and issue comment both exist.
+- No `.legion` file was created or modified by retro.
+- The fresh-eyes analysis was considered alongside the implementer's context.
+- Sami's approval and the merger remain subsequent steps, not work performed by retro.

package/dist/skills/legion-worker/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: legion-worker
+description: Use when dispatched as an architect, plan, implement, test, or review phase worker in a Legion issue workspace.
+---
+
+# 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.
+
+## 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 or open human dispatch threads. Escalate a product,
+scope, cross-phase, or human decision to the owning architect through hub, with the verified
+facts and the decision needed.
+
+## 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:
+
+```bash
+cd -- "<workspace>" && jj -R "<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.
+
+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/`:
+
+1. `architect.json`
+2. `plan.json`
+3. `implement.json`
+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.
+
+## 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.
+
+**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.
+
+## 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.
+
+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>`
+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:
+
+```bash
+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:
+
+```html
+<!-- legion: {"session":"<session-id>","phase":"<phase>"} -->
+```
+
+For example:
+
+```bash
+legion gh -- issue comment <issue-number> \
+  --body $'Verification complete.\n\n<!-- legion: {"session":"<session-id>","phase":"<phase>"} -->' \
+  --repo <owner>/<repo>
+```
+
+## 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:
+
+```bash
+cd -- "<workspace>" && \
+  jj -R "<workspace>" bookmark set legion/issue-<n> && \
+  jj -R "<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.
+
+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.
+
+## Completion gate: handoff write, verification, and persistence
+
+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.
+
+Write the phase-specific handoff:
+
+```bash
+cd -- "<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"
+```
+
+Then commit that exact handoff file onto the issue branch:
+
+```bash
+cd -- "<workspace>" && \
+  jj -R "<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:
+
+```bash
+cd -- "<workspace>" && \
+  jj -R "<workspace>" bookmark set legion/issue-<n> && \
+  jj -R "<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.
+
+## Completion and escalation
+
+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.
+
+When blocked, send the owning architect a concise hub message: issue, phase, verified
+observation, what you tried, and the decision required. Do not dispatch a human thread yourself.