@sjawhar/opencode-legion-envoy 3.13.0 → 3.15.0

package/skills/legion-worker/references/merge-gate.md

@@ -0,0 +1,101 @@
+# The merge gate: review, retro, READY, and the production check
+
+Part of `skill://legion-worker`. Read it when you are the reviewer submitting a review or an
+approval, the implementer pushing the `.legion/` deletion or recording the production check, or
+the merger publishing READY. Every path it cites is in sjawhar/legion.
+
+The order, in full: the tester's evidence green → the implementer's `.legion/` deletion push →
+the reviewer's approval of that head → retro → the merger's READY → the human merge → the
+implementer's production check. After the approval, only retro's `docs/solutions/` commit leaves
+it standing on its own (*Retro*, below). A conflict-forced merge goes back to the reviewer for a
+confirmation or a new round, as the fingerprint decides (*The reviewer*, below, and
+`skill://legion-worker/references/conflicts-and-rewrites.md`), and any other change voids it.
+
+## The reviewer
+
+- 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 — the head the implementer's
+  simplify pass left final — and records the verdict.
+  Approval is refused while either `E2E (implementer)` or `E2E (tester)` is missing: `REQUEST_CHANGES` naming the missing line.
+  Skip the `Thermo` line entirely on a docs-only PR. Submit **one review per round** —
+  `REQUEST_CHANGES` when any correctness finding stands, otherwise `COMMENT` while the head
+  still carries `.legion/`; `APPROVE` only for a head that carries no `.legion/` — the head
+  that differs from the reviewed one by the `.legion/` deletion alone, or, after a
+  conflict-forced rebase, the new head whose fingerprint equals the approved head's — always
+  named by SHA — carrying every inline comment in that single
+  call: `legion gh -- api --method POST repos/{owner}/{repo}/pulls/{number}/reviews --input body.json`
+  with `commit_id`, `event` (`REQUEST_CHANGES`, `COMMENT`, or `APPROVE`), `body` (with the
+  Legion footer), and a `comments[]` array of `{path, line, side, body}`, one entry per
+  finding — never one `pr review` call per finding (each submission fires a `pr-review` wake).
+  Then return the issue to the architect; when clean, have the architect send the implementer
+  back to push the `.legion/` deletion, then review **that** head and approve it by name. After a
+  conflict-forced rebase, compute the fingerprint (*The unchanged-diff check* in
+  `skill://legion-worker/references/conflicts-and-rewrites.md`) at the
+  `commit_id` of your last submitted review and at the new head. Equal and that review was
+  `APPROVE`: submit one more `APPROVE` naming the new head by SHA, its body naming both SHAs
+  and the fingerprint — a confirmation, not a round; no thermo pass, no thread pass. Equal and
+  that review was `COMMENT` or `REQUEST_CHANGES`: continue that round against the new head;
+  nothing restarts. Different: a new round — thermo again, one review.
+- Answer every thread you opened, and every thread a bot opened that is none of Legion's role
+  Apps, as `skill://legion-worker/references/review-threads.md` says; the same reference says
+  when every thread is settled enough to approve.
+
+A reviewer's phase ends with its completion, not with its review. A round that writes a handoff
+takes this order: write, commit and push the handoff; submit the review of the head that push
+made, by its SHA; then complete. An approval waits for the CI verdict to settle green at that head
+before you submit it, since an approval stands only on green checks and GitHub can dismiss one
+once the head moves, and a verdict that settles red there makes the round's decision a request for
+changes naming the failing checks; a request for changes does not wait, since it stands whatever CI says and the
+issue leaves reviewing with it. A review of a head the handoff push then replaces names a head
+the pull request no longer has. A round that writes none (the final approval of the `.legion/`
+deletion head) reviews the head as it is. The daemon moves the issue once both are in —
+the decision GitHub reports and your completion, in either order — so a review posted without a
+completion leaves the issue in reviewing until you finish.
+
+## Retro
+
+- **Retro's commit does not void the reviewer's approval.** After the reviewer approves the
+  cleaned head, retro commits its learnings under `docs/solutions/` on top of it; that commit
+  stays, the approval stands, and the tree goes to the merger — never back to the tester or
+  reviewer. Anything else above the approved head does void it, and the merger tells the
+  architect the head must return to review instead of publishing. A conflict-forced rebase
+  after retro moves those documents with the branch; retro never re-runs.
+
+## The merger
+
+- The merger runs `legion threads resolve --pr <n> --repo <owner>/<repo>` (it acts as the same
+  code-writing App as the implementer; resolving a thread changes no commit, so this run never
+  invalidates the approval), does not publish while any `left open` line remains or the command
+  exits 1 (report the thread to the architect instead), then proves that rule with two commands.
+  First `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && jj -R
+  "$LEGION_WORKSPACE" diff --from <approved-sha> --to <tip-sha> --summary`, whose output is quoted
+  in READY (an empty output is quoted as `no file changes above the approved head`); then the same
+  with `'~docs/solutions'` appended, which must print nothing. The merger always posts
+  `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)` (the shape
+  `packages/pi-envoy/roles/merger.md` defines), its summary, and the PR body's gate facts as a
+  `dispatch_message` on the issue. When the `Legion addressing` line names a merge queue, it also
+  publishes the same packet there with `envoy_publish`; a 404 means the Dispatch message remains
+  the durable notice and the merger stays idle. The READY packet names both the implementer's and
+  tester's `E2E` lines; a missing one is reported to the architect instead of published. Legion
+  never merges.
+
+## After the human merge
+
+- **After a human merges, the implementer verifies in production.** Sami, 2026-09-13,
+  verbatim: "the agent that developed it should be responsible for testing in production."
+  The architect sends the implementer back once the merge lands; the implementer watches the
+  deploy slot that carries the merge to `production-apply` (or the equivalent publish step),
+  drives the changed path in production through the user's own access path, and records the
+  observation on the PR and the issue before the architect signs off. A staging pass is not
+  this: on 2026-09-12 a slot's entire staging gate passed at 00:02Z and its production-apply
+  failed at 00:12Z on a resource staging never runs. If the slot fails on the change, the
+  implementer owns the fix and the next slot.
+  The record has three places: the PR body's `Production:` line, one pull-request comment
+  carrying the Legion footer, and a `dispatch_message` on the issue — the reviewer and merger
+  read GitHub, the architect reads the issue. When the deploy that carries the merge has not
+  happened (a shared profile still holding the previous plugin release, a daemon still running
+  the previous commit, a slot nobody has run), open a `dispatch_ask` naming the exact install or
+  restart step, with options for its outcomes, keep the `Production:` line at `pending <what is
+  missing>`, and complete the check once the human answers that it is done. Never record a
+  staging pass as the production check, and never let the architect sign off on a `pending` line.

package/skills/legion-worker/references/pr-body.md

@@ -0,0 +1,125 @@
+# PR body, proofs, and the simplify pass
+
+Part of `skill://legion-worker`. Read it before you write or edit any line of the pull request
+body, put a `proof` array in a handoff, verify another phase's proof, or run the simplify pass.
+Every path it cites is in sjawhar/legion.
+
+## The READY format
+
+The implementer writes the PR body in the READY format from the moment the PR opens, and every
+later phase keeps it current rather than replacing it:
+
+```
+## Verification
+
+**CI:** `Tests` run <run-id> — jobs lint, typecheck, test all success at <head-sha>; `PR Title` run <run-id> — job pr-title 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>.
+`legion threads resolve --pr <n> --repo <owner>/<repo>` at <head-sha>:
+resolved <thread URL> — its opener's acceptance
+resolved <thread URL> — the Legion reviewer's acceptance of a bot's thread
+left open <thread URL> — newest reply by <login> is not an acceptance
+left open <thread URL> — newest reply by <login> is an unsubmitted draft in a pending review
+left open <thread URL> — newest reply by <login> is not its opener's or the Legion reviewer's acceptance
+
+**Thermo:** `ce-simplify-code` once at <head-sha>: <0 applied | applied → new head <sha>>; thermonuclear pair at the final head <sha>:
+<verdict>. (omitted entirely on a docs-only PR — there is no code for either pass, so neither runs)
+
+**E2E (implementer):** <surface> — ran `<command or run id>`, observed <result>, at head <sha>.
+Negative control: <deliberately broken input> → <refusal or failure observed>.
+
+**E2E (tester):** <surface> — ran `<command or run id>`, observed <result>, at head <sha>.
+Negative control: <deliberately broken input> → <refusal or failure observed>.
+Verified the implementer's proof by <re-running its command | driving the same surface independently>.
+
+**Production:** <what was checked in production, how, what was observed> — merge commit <sha>.
+(written by the implementer after the merge lands; `pending <what is missing>` until then)
+
+**Fast-follow:** <one named cleanup item and where it will land>, or "none".
+
+**Chain:** stacked on <base bookmark> frozen at <sha> / not stacked.
+```
+
+## What a proof is
+
+**A proof** is the changed behaviour exercised on the surface a user reaches it through, recorded
+as 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 observed. The surface is
+**production-like** — the repository's real-process test harness and fixtures, a sandbox
+repository, a real browser, a devN stack, staging, or a local stack with real migrations, one that
+has the resource the change touches — and each `E2E` line carries a **link** to that run,
+screenshot, or e2e; human review does not replace user-facing verification, and a green unit suite
+is not it. A unit or integration test is a regression lock, never proof of a criterion. Sami,
+2026-09-13, verbatim: "They need to test everything in a production-like
+environment before merging, and it is the agent that develops the feature that is responsible
+for doing that. If there's anything blocking that, we need to fix it: if it's infrastructure, we
+need to fix it; if it's tooling, we need to develop it; if it's skills, we need to fix the skills
+... it should not require deploying to production to realize your feature doesn't work."
+Evidence for the rule: in the week of 2026-09-08 three surfaces merged green and were wrong on
+inspection (the Astrolabe IPI stack, Dispatch on ECS, the candidate flow), and on 2026-09-12 six
+deploy slots died on code first executed after merge, including a production-only ECS bootstrap
+the whole staging gate never ran. The implementer's proof and the tester's proof below are both
+this proof.
+
+## The rules every phase's evidence follows
+
+- **The implementer proves the change before its phase completes, and writes the `E2E (implementer)` line when the pull request opens.**
+  The proof is the one defined above. It goes into `.legion/implement.json` as the required `proof`
+  array (`handoff_write` for phase `implement` refuses a payload without one, or with a blank or
+  whitespace-only field, and names the field), and into the PR body, because the reviewer and the
+  merger verify facts on GitHub and never from a handoff.
+- **The tester verifies the implementer's proof and adds its own `E2E (tester)` line.** It re-runs
+  the implementer's command or drives the same surface independently, and records the verdict in
+  `.legion/test.json` as `implementerProof` (`{verdict, how}`).
+  A test handoff whose predecessor carried no proof is a test failure, not a gap for the tester to fill:
+  record it in `failures` with `implementerProof.verdict: "rejected"`, complete the phase, and let
+  the architect return the issue to the implementer — the agent that developed the change owns
+  proving it (`handoff_write` for phase `test` refuses a rejected verdict, or `failed > 0`,
+  with no recorded failure). Otherwise, add your own proof before completing — a proof as defined
+  above — as the `E2E (tester)` line and the `proof` array `handoff_write` for
+  phase `test` requires whenever you report no failure. A code path whose first execution is after merge — a
+  deploy workflow's inline step, a post-merge helper, a production-only resource — is untested
+  until the implementer has executed it against a devN stack; if no surface can reach it, the
+  tester names that missing surface as the blocker instead of passing the phase. Environment or
+  secret-scrub evidence (e.g. "`LEGION_*`/`DISPATCH_*`/`ENVOY_*` unset") is recorded once, in
+  `.legion/test.json`, and only when the issue's acceptance criteria call for it — never
+  re-pasted into the PR body each round. After a conflict-forced rebase, compute the
+  fingerprint (*The unchanged-diff check* in
+  `skill://legion-worker/references/conflicts-and-rewrites.md`) at the head your `E2E` line
+  names and at the new head. Equal: re-run only the
+  bare gates — the repository's CI green at the new head and its smoke check — and change the
+  `E2E` line's head to the new SHA with
+  `rebase re-check <old-sha> → <new-sha>: fingerprint unchanged, bare gates only`; the
+  real-surface verification is not repeated. Different: a full test round.
+- **The implementer runs `skill://ce-simplify-code` once per pull request, after the last review round
+  closes and before the reviewer's final pass, when the diff touches runtime code; a docs-only
+  diff gets none.** It is scoped to the pull request's own diff, at the head where the last review
+  round closed: nothing applied leaves that head final; applied → the applied head is the final
+  head: CI runs on it, the pair runs once on it, and the E2E proof re-runs on it for the surface
+  the simplify diff touched (Sami, 2026-09-13: test on the real surface before merging, no
+  shortcuts — a refactor that "preserves behaviour" is a claim until it is executed). That cost is
+  why 0-applied is the expected outcome and a pass that applies is spent sparingly. At the applied
+  head the implementer re-cites the `CI` line and re-runs its own proof into `E2E (implementer)`,
+  and the tester re-runs its proof for the touched surface into `E2E (tester)`, before the
+  reviewer's final pass. Simplify is the last code change; the pair is the last review. Record it
+  in the `Thermo` line.
+- **No deferrals** is the body's rule (*PR body, review, and the merge gate* in
+  `skill://legion-worker`): the `Fast-follow:` line holds naming, duplication, or wording cleanup
+  only. A base frozen for others to stack on is never rewritten (*Rewriting pushed commits* in
+  `skill://legion-worker/references/conflicts-and-rewrites.md`); the `Chain` line records it.
+
+## When no surface reaches the changed path
+
+No surface reaches the changed path is a report to the architect, never a reason to complete the phase.
+Say which surface is missing and what it would have to do — a rig that can spawn the role, a
+sandbox that holds the resource, a credential, a command that does not exist yet — and send it to
+the architect with `envoy_publish` to its role topic. The architect creates a child issue in this
+tree to build it (infrastructure, tooling, or a skill) and resumes you once it lands. Sami,
+2026-09-13, verbatim: "If there's anything blocking that, we need to fix it: if it's
+infrastructure, we need to fix it; if it's tooling, we need to develop it; if it's skills, we need
+to fix the skills." A code path whose first execution would be after the merge — a deploy
+workflow's inline step, a post-merge helper, a production-only resource — is untested until you
+have executed it somewhere production-like; completing with a unit-test-only handoff is the
+failure this rule exists to stop.

package/skills/legion-worker/references/review-threads.md

@@ -0,0 +1,71 @@
+# Review threads
+
+Part of `skill://legion-worker`. Read it when you reply to, accept, or resolve a review thread,
+or run `legion threads resolve`: the implementer before every push that answers a review, the
+reviewer on every re-review, the merger before READY. Every path it cites is in sjawhar/legion.
+
+- **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. The
+  reviewer answers each thread it opened, and each thread a bot opened that is none of Legion's
+  role Apps, with exactly one of `Accepted: fixed in <commit> — <one line>`,
+  `Accepted: not a defect — <reason>`, or `Still open: <what remains>`; nothing else is an
+  acceptance, and nobody replies after an `Accepted:` (any later reply that is not itself an
+  `Accepted:` — the opener's own follow-up included — leaves the thread open, because resolution
+  considers only the newest comment). The review App can reply on a thread but cannot resolve it:
+  GitHub grants resolving a review thread to the pull request's author, and the implementer opens
+  every Legion pull request (`packages/daemon/src/daemon/AGENTS.md`, GitHub Apps).
+  When `LEGION_GRANT_FILE` or `LEGION_GRANT` is set, use `legion threads resolve --pr <number> --repo <owner>/<repo>`.
+  When neither is set, add `--gh` to that command, which applies the fallback's rule below through
+  your own `gh`; where no `legion` command is installed, use `gh api graphql` with the session's
+  GitHub credential and the fallback below.
+  In a Legion pane, the **implementer** runs the command before every push that answers a review
+  (the corrective push and the final `.legion/` deletion push) and pastes its output into the
+  `Threads` section. The command resolves each unresolved thread whose newest submitted comment is
+  the opener's own `Accepted:` reply. On a thread a bot account opened that is none of Legion's
+  role Apps (the daemon names them, keyed by App role), the Legion reviewer's `Accepted:` also
+  closes it. GitHub cannot tell a CI bot, which never accepts, from a person whose `gh` is routed
+  to an App, so the reviewer adjudicates such a finding, and it may accept one an App-routed person
+  raised. The subject of a finding never closes it: the implementer's `Fixed in <commit>: …` or
+  `Declined: …` answers a thread and closes none. A thread either Legion App opened, a reviewer's
+  finding included, still needs its opener's `Accepted:`. It makes one `resolveReviewThread` per
+  thread, prints `resolved <url> — <whose acceptance>` (its opener's, or the Legion reviewer's on a
+  bot's thread, so the ledger shows which) or `left open <url> — newest reply by <login> is …`
+  naming why, and exits 1 naming the thread's URL and GitHub's message when GitHub refuses one.
+
+  Without a grant, page through `reviewThreads`, skip `isResolved: true`, and compare the opener
+  with the newest comment. Query shape, inside `repository { pullRequest { … } }`:
+
+  ```graphql
+  reviewThreads(first: 100, after: $after) {
+    pageInfo { hasNextPage endCursor }
+    nodes {
+      id isResolved
+      opener: comments(first: 1) { nodes { author { __typename login } } }
+      newest: comments(last: 1) { nodes { author { __typename login } body state } }
+    }
+  }
+  ```
+
+  Resolve only when the newest comment is submitted, its `author` is the opener's account (the same
+  `__typename` and `login`: a login alone is a string anyone may register), and its `body`, after
+  removing leading spaces, tabs, CR, and LF, begins `Accepted:`. Without a
+  grant nothing names Legion's own App logins, so this route closes a bot's thread only on its
+  opener's `Accepted:`: leave one the Legion reviewer accepted for the implementer's or merger's
+  run in a pane, or report it. For each thread to resolve:
+
+  ```graphql
+  mutation($threadId: ID!) {
+    resolveReviewThread(input: { threadId: $threadId }) { thread { isResolved } }
+  }
+  ```
+
+  Re-read `reviewThreads` and confirm that thread's `isResolved` is true. In either route, report
+  a refused resolution to the architect, which opens an ask for a human to resolve the thread by
+  hand — never skip it silently. The merger runs the command once more before publishing READY
+  and does not publish while any `left open` line remains.
+
+- **The reviewer, on a re-review.** When you re-review after a corrective push, answer every
+  thread you opened in one of the three forms above — `Accepted:` is the only reply the
+  implementer's `legion threads resolve` acts on — and approve only once every thread you opened
+  carries your `Accepted:` reply and the implementer's run has resolved it (verify
+  `isResolved: true` with `gh api graphql`, never from the PR body).

package/src/server.ts

@@ -5,6 +5,7 @@ import { agentSubject, dispatchToolSpecs, zodSchemaApi } from "@legion/contracts
 import { envoyDefaultsFromEnvironment } from "@legion/envoy-client/defaults";
 import { resolveDispatchConfig } from "@legion/envoy-client/dispatch-config";
 import { executeDispatchTool } from "@legion/envoy-client/dispatch-execute";
+import { dispatchFirstSkillFile } from "@legion/envoy-client/dispatch-first";
 import { machineID } from "@legion/envoy-client/machine";
 import {
   envoyToolSpecs,
@@ -53,6 +54,20 @@ export default async (input: { serverUrl: URL }) => {
       `envoy: dispatch tools disabled — ${dispatchConfig.error ?? "no Dispatch URL configured"}`
     );
   }
+  // With Dispatch configured, every session carries the dispatch-first skill as an instruction
+  // file: OpenCode reads instruction files into the main loop's system prompt on every request
+  // and leaves them out of title and compaction requests. A package without the skill fails
+  // here, naming the file, rather than serving sessions that silently lack it.
+  let dispatchFirst: string | undefined;
+  if (dispatchConfig.enabled) {
+    if (skillsDirectory === undefined) {
+      throw new Error(`envoy: no skills directory beside ${moduleDirectory}`);
+    }
+    dispatchFirst = dispatchFirstSkillFile(skillsDirectory);
+    if (!existsSync(dispatchFirst)) {
+      throw new Error(`envoy: the dispatch-first skill ${dispatchFirst} is missing`);
+    }
+  }
   const envoyDefaults = envoyDefaultsFromEnvironment(process.env);
   const envoy = createEnvoyClient({ baseUrl: envoyDefaults.envoyUrl, fetch: globalThis.fetch });
   let activeSessionID: string | null = null;
@@ -195,7 +210,9 @@ export default async (input: { serverUrl: URL }) => {
   }
 
   return {
-    config: (cfg: { skills?: { paths?: string[] } } & Record<string, unknown>) => {
+    config: (
+      cfg: { skills?: { paths?: string[] }; instructions?: string[] } & Record<string, unknown>
+    ) => {
       // Serve the bundled legion skills to every session on this serve.
       if (skillsDirectory) {
         cfg.skills ??= {};
@@ -204,6 +221,10 @@ export default async (input: { serverUrl: URL }) => {
           cfg.skills.paths.push(skillsDirectory);
         }
       }
+      if (dispatchFirst !== undefined) {
+        cfg.instructions ??= [];
+        if (!cfg.instructions.includes(dispatchFirst)) cfg.instructions.push(dispatchFirst);
+      }
     },
     event: async ({
       event,

package/skills/legion-worker/references/knowledge-injection.md

@@ -1,98 +0,0 @@
-# Knowledge Injection Algorithm
-
-Canonical algorithm for injecting relevant learnings from `docs/solutions/` before phase-specific work begins. All worker workflows reference this file for the injection procedure; each workflow specifies its own keyword sources.
-
-## Overview
-
-Before starting main work, each phase checks the learnings index for applicable prior knowledge. This surfaces patterns, pitfalls, and institutional knowledge that previous workers documented.
-
-**Injection must never block work.** If any step fails (missing index, invalid JSON, missing files, empty handoff data), skip silently and proceed with the phase's main work.
-
-## Algorithm
-
-### 1. Read the Index
-
-Assemble the index by reading all per-entry JSON files in `docs/solutions/.index/`:
-
-```bash
-# Read and merge all entry files in .index/ directory
-for f in docs/solutions/.index/*.json; do
-  [ -f "$f" ] && cat "$f"
-done
-```
-
-Each file has the format `{ "version": 1, "entries": { "key": ["learning-path", ...] } }`. Merge all `entries` maps together, deduplicating learning paths per key.
-
-If the `.index/` directory doesn't exist or contains no valid JSON files, skip injection entirely — proceed to the phase's main work.
-
-### 2. Extract Keywords
-
-Collect keywords from the phase-specific sources (defined in each workflow file). The extraction algorithm:
-
-1. **Collect raw text** from the specified keyword sources (see the calling workflow's keyword source table)
-2. **Tokenize**: split on whitespace, `/`, `-`, `_`, and camelCase boundaries
-3. **Normalize**: lowercase all tokens
-4. **Filter**: remove tokens < 3 chars and common stopwords (the, and, for, with, this, that, from, into, when, will, should, would, could, also, been, have, each, etc.)
-5. **Deduplicate** tokens
-6. **Extract full path segments**: e.g., `packages/daemon/src/state` — keep as-is for path matching in addition to individual tokens
-
-Also look for references to:
-- Source path segments (e.g., `packages/daemon/src/state/`, `serve-manager`)
-- Module names (e.g., "daemon", "controller", "worker", "state")
-- Component names (e.g., "serve-manager", "decision", "fetch")
-- Feature areas (e.g., "skills", "linear", "github", "review", "retro")
-- Integration concerns (e.g., "PR", "labels", "MCP")
-- Domain concepts and error keywords from the context
-
-### 3. Match Keywords Against Index
-
-Use two matching modes against the keys in `.index`:
-
-- **Path matching**: For each key that does NOT start with `tag:`, check if any extracted keyword appears as a substring of the key (case-insensitive). Collect all matched learning file paths.
-- **Tag matching**: For each key that starts with `tag:`, extract the tag name (e.g., `tag:race-condition` → `race-condition`). Check if any extracted keyword matches the tag name (case-insensitive). Collect matched learning file paths.
-
-### 4. Deduplicate and Rank
-
-- Remove duplicates (same file matched via multiple keys)
-- **Status filter**: For each candidate, read its YAML front matter `status` field. Exclude any file with `status: superseded`. If the file doesn't exist or has no front matter, include it (graceful degradation).
-- **Primary rank: tag overlap** — For each remaining candidate, read its `tags` front matter field. Count how many of its tags appear in the extracted keywords (case-insensitive). Higher overlap = higher rank.
-- **Secondary rank: key specificity** — Learnings matched via longer/more-specific keys rank higher (e.g., a match on `packages/daemon/src/state` outranks a match on `packages/daemon`)
-- **Tertiary rank: match count** — Number of distinct key matches (more matches = more relevant)
-- **Cap at 3 learnings maximum**
-
-### 5. Read Matched Learnings
-
-For each matched learning file (from `docs/solutions/<path>`):
-
-1. Read YAML front matter: extract `title` and `tags` fields
-2. Skip past front matter (`---` blocks) and headings, take the first paragraph of prose (typically the Problem or Overview section)
-3. Prepend structured header: `[{title} | tags: {comma-separated tags}]`
-4. Truncate entire output (header + prose) to **350 characters**
-
-**If a matched file doesn't exist on disk:** Skip that entry silently (stale index entry from a file rename). Do not error.
-
-### 6. Output Injected Learnings
-
-Output the injected learnings visibly in the session before proceeding with the phase's main work:
-
-```
-## Relevant Learnings (from docs/solutions/)
-
-1. [docs/solutions/<path>]: [{title} | tags: {tag1}, {tag2}] <prose excerpt> (350 chars max total)
-2. [docs/solutions/<path>]: [{title} | tags: {tag1}, {tag2}] <prose excerpt>
-3. [docs/solutions/<path>]: [{title} | tags: {tag1}, {tag2}] <prose excerpt>
-
-(Review these for patterns and pitfalls relevant to this phase's work.)
-```
-
-**If no matches found:** Output "No relevant learnings found." and proceed. Do NOT add an empty section.
-
-**Canonical identifiers:** All references to learnings use their `docs/solutions/` relative file path (e.g., `daemon/controller-lifecycle-separation.md`). These paths are the stable IDs used for injection, handoff tracking, and future aggregation. Never use titles or truncated text as identifiers.
-
-## Fallback Behavior
-
-When a keyword source is unavailable (missing handoff data, empty fields, missing phase data), silently fall back to the next available source as defined in the calling workflow's fallback rules. Never error on missing data.
-
-## Integration with Handoffs
-
-If the phase writes handoff data, include a `learningsInjected` field listing the `docs/solutions/` relative paths of all injected learnings. This enables downstream phases to see what knowledge was available and supports future aggregation.