@sjawhar/opencode-legion-envoy 0.6.1 → 0.8.0

package/skills/github/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: github
+description: Manage GitHub issues via Projects V2. Use when LEGION_ISSUE_BACKEND=github.
+---
+
+# GitHub (gh CLI)
+
+Direct CLI operations via `gh`. No embedded MCP — all commands are shell invocations.
+
+## Setup
+
+Requires `gh` CLI installed and authenticated:
+```bash
+gh auth login
+```
+
+## Operations
+
+### Search/List Issues (via project)
+
+List all items in a GitHub Project V2:
+
+```bash
+gh project item-list $PROJECT_NUM --owner $OWNER --format json
+```
+
+**Parameters:**
+- `$PROJECT_NUM`: Project number (from `LEGION_ID` format: `owner/project-number`)
+- `$OWNER`: Repository owner
+- `--format json`: Returns structured data for parsing
+
+**Example:**
+```bash
+gh project item-list 42 --owner acme --format json | jq '.items[] | {id, title, status}'
+```
+
+### Get Issue Details
+
+Fetch full issue metadata:
+
+```bash
+gh issue view $ISSUE_NUMBER --json title,body,labels,comments,state -R $OWNER/$REPO
+```
+
+**Parameters:**
+- `$ISSUE_NUMBER`: Issue number (e.g., `123`)
+- `-R $OWNER/$REPO`: Repository (required for multi-repo support)
+- `--json`: Fields to return (title, body, labels, comments, state, etc.)
+
+**Example:**
+```bash
+gh issue view 123 --json title,body,labels,state -R acme/backend
+```
+
+### Update Status (Projects V2 — GraphQL)
+
+Update issue status in a GitHub Project V2. Requires field and option IDs from project schema:
+
+```bash
+gh api graphql -f query='mutation {
+  updateProjectV2ItemFieldValue(input: {
+    projectId: "$PROJECT_ID"
+    itemId: "$ITEM_ID"
+    fieldId: "$STATUS_FIELD_ID"
+    value: { singleSelectOptionId: "$OPTION_ID" }
+  }) { projectV2Item { id } }
+}'
+```
+
+**Parameters:**
+- `$PROJECT_ID`: GraphQL ID of the project (not the number)
+- `$ITEM_ID`: GraphQL ID of the issue in the project
+- `$STATUS_FIELD_ID`: GraphQL ID of the Status field
+- `$OPTION_ID`: GraphQL ID of the status option (e.g., "In Progress", "Done")
+
+**Note:** Field and option IDs must be resolved from the project schema. The controller caches these after first query.
+
+**Resolve IDs (one-time):**
+```bash
+gh api graphql -f query='query {
+  repository(owner: "$OWNER", name: "$REPO") {
+    projectV2(number: $PROJECT_NUM) {
+      fields(first: 20) {
+        nodes {
+          ... on ProjectV2SingleSelectField {
+            id
+            name
+            options { id name }
+          }
+        }
+      }
+    }
+  }
+}'
+```
+
+### Add Label
+
+Add a label to an issue (additive — does not remove existing labels):
+
+```bash
+gh issue edit $ISSUE_NUMBER --add-label "needs-approval" -R $OWNER/$REPO
+```
+
+**Parameters:**
+- `$ISSUE_NUMBER`: Issue number
+- `--add-label`: Label to add (can be used multiple times)
+- `-R $OWNER/$REPO`: Repository
+
+**Example:**
+```bash
+gh issue edit 123 --add-label "needs-approval" -R acme/backend
+```
+
+### Remove Label
+
+Remove a label from an issue:
+
+```bash
+gh issue edit $ISSUE_NUMBER --remove-label "needs-approval" -R $OWNER/$REPO
+```
+
+**Parameters:**
+- `$ISSUE_NUMBER`: Issue number
+- `--remove-label`: Label to remove (can be used multiple times)
+- `-R $OWNER/$REPO`: Repository
+
+**Example:**
+```bash
+gh issue edit 123 --remove-label "legion-backlog" -R acme/backend
+```
+
+### Comment on Issue
+
+Add a comment to an issue:
+
+```bash
+gh issue comment $ISSUE_NUMBER --body "Fixed in commit abc123" -R $OWNER/$REPO
+```
+
+**Parameters:**
+- `$ISSUE_NUMBER`: Issue number
+- `--body`: Comment text (supports Markdown)
+- `-R $OWNER/$REPO`: Repository
+
+**Example:**
+```bash
+gh issue comment 123 --body "Implemented in PR #456" -R acme/backend
+```
+
+### Create Issue
+
+Create a new issue:
+
+```bash
+gh issue create --title "Bug: Login fails" --body "Details" -R $OWNER/$REPO
+```
+
+**Parameters:**
+- `--title`: Issue title (required)
+- `--body`: Issue description (optional, supports Markdown)
+- `-R $OWNER/$REPO`: Repository
+
+**Example:**
+```bash
+gh issue create --title "Feature: Add dark mode" --body "User request from #789" -R acme/backend
+```
+
+## Key Differences from Linear
+
+| Aspect | Linear | GitHub |
+|--------|--------|--------|
+| **Labels** | Replace all (read-modify-write) | Additive (`--add-label`, `--remove-label`) |
+| **Status** | Direct field update | Projects V2 GraphQL mutation |
+| **PR Association** | Attachment field | Native (issue ↔ PR link) |
+| **API** | MCP tool dispatch | Direct `gh` CLI |
+| **Multi-repo** | Single team | `-R owner/repo` per command |
+
+## Important Notes
+
+- **Always specify `-R $OWNER/$REPO`** for multi-repo project support
+- **Labels are additive**: Use `--add-label` and `--remove-label` separately (unlike Linear which replaces all)
+- **Status updates require Projects V2 GraphQL** — not just issue labels
+- **PR association is automatic** — GitHub links issues and PRs natively
+- **`$OWNER` and `$REPO` come from `LEGION_ID`** (format: `owner/project-number`)
+- **Field/option IDs must be cached** by the controller after first resolution
+
+## Error Handling
+
+Common errors and solutions:
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Could not resolve to a Repository` | Wrong `-R` format | Use `-R owner/repo` (not `owner-repo`) |
+| `Could not resolve to an Issue` | Issue doesn't exist | Verify issue number is correct |
+| `GraphQL error: Field not found` | Wrong field ID | Re-resolve field IDs from project schema |
+| `Not authenticated` | `gh` not logged in | Run `gh auth login` |
+
+## Reference
+
+- **Project number**: Visible in GitHub UI (e.g., `https://github.com/orgs/acme/projects/42` → `42`)
+- **Issue number**: Visible in URL (e.g., `https://github.com/acme/backend/issues/123` → `123`)
+- **GraphQL IDs**: Base64-encoded, returned by GraphQL queries (not human-readable)

package/skills/legion-architect/SKILL.md

@@ -0,0 +1,201 @@
+---
+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 lifecycle, scope, and cross-phase matters inward to you
+  through hub. Any role may use `dispatch` directly for a standalone human question;
+  replies return to the asking session.
+- 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" })
+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. |
+| `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 use `dispatch` for a human question; workers may reach
+Sami directly with `dispatch` the same way. Do not create a wait loop for any wake
+source.

package/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; 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 |
+| 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. Issue-scoped human Q&A goes through `dispatch` from the owning
+architect, not the controller.
+
+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/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/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.