@sjawhar/claude-envoy 0.0.0 → 1.0.0

package/legion/skills/legion-worker/references/conflicts-and-rewrites.md

@@ -0,0 +1,164 @@
+# Conflicts, retargets, fingerprints, and rewriting pushed commits
+
+Part of `skill://legion-worker`. Read it when GitHub reports the pull request `CONFLICTING`, the
+controller asks you to resolve a conflict, the change needs something only the base has, the pull
+request is retargeted to a new base, you compare two heads after such a merge, a push is refused
+because the handoff import moved the branch, or you are about to rewrite a commit you already
+pushed.
+Every path it cites is in cybermonklabs/legion.
+
+## Reintegrating the base
+
+- **Merge the base forward only on a real conflict, a need only the base meets, a retarget, or a
+  parent's last round, and never with `jj rebase`.**
+  The implementer merges the base into the issue branch only when GitHub reports it `CONFLICTING`, the controller asks
+  because of a conflict, the architect's backward move names a parent's last round,
+  the change needs something that exists only on the base (a fix for its
+  only red check, or a sentence it must change), or after the pull request is retargeted to a new
+  base. Otherwise, never reintegrate the base to pick up the default branch or refresh CI. Each
+  merge is a new head, reruns CI and can void a review. A single failed CI job is re-run on its
+  own (*Never waiting on CI* in `skill://legion-worker/references/pr-body.md`). After any forward merge, build the branch and
+  record the issue's checks again at the merge head, even with no text conflict: a clean merge once changed a
+  function's arity under the branch's own callers. Before you race another tree's pull request on
+  shared files, `envoy_publish` to its implementer's role topic, ask when its next push lands, and
+  merge once, after it. A forward merge that leaves the branch's diff unchanged is a
+  confirmation, not a new round (see *The unchanged-diff check* below). The check compares the
+  pull request's own lines file by file: a changed file sends the head through the tester again,
+  and your comment names it. Before merging, record
+  the fingerprint at the current tip; after pushing the merged branch, record it at the new
+  tip; post one PR comment (Legion footer):
+  `forward merge <old-tip-sha> → <new-tip-sha>; fingerprint <before> → <after>; unchanged|changed`.
+  The fingerprint answers one question only: whether the branch's own diff changed. It cannot
+  show an instance the merge brought in from the base, so before you push the merge search its
+  head for the class of every finding of every earlier review round and record each search
+  beside the fingerprints.
+  In a parent's last round, end that comment with `parent's last round: full test round`, the line
+  the tester reads for a full round (`skill://legion-architect/references/acceptance.md`,
+  "The last round").
+  On the tmux runtime, where issue workspaces are still jj workspaces of one shared clone,
+  `jj undo`, `jj abandon` and `jj op restore` rewrite the shared operation log, so a mistake there
+  is recovered forward (`jj -R "$LEGION_WORKSPACE" new`, or `jj -R "$LEGION_WORKSPACE" restore
+  <paths>` of files). In that shared repository jj always rebases every descendant of any commit it
+  rewrites — a revset naming the root of your own chain and rewriting it in place also rewrites
+  whatever another tree has stacked on that root, whichever selector chose it (`-s`, `-b`, and
+  `-r` all rewrite descendants; `-r` only re-parents them to fill the hole, which is worse).
+  Resolve the conflict with a forward merge instead of a rewrite — merge the branch's own
+  bookmark with the destination in one new commit, so nothing existing is rewritten and nothing
+  built on your prior commits, in this tree or another, ever moves. `base` is the pull request's
+  base branch (the repository's default branch unless the pull request is stacked), read as a jj
+  string literal: jj parses a bare bookmark name as an expression, and a name pasted between
+  quotes can close them itself (`release"@origin|"stable` would select `release` and `stable`), so
+  the revset is built from the serialized name alone:
+
+  ```bash
+  base=$(gh pr view <n> -R <owner>/<repo> --json baseRefName -q '.baseRefName | @json') && \
+    jj -R "$LEGION_WORKSPACE" new legion/<KEY> "${base}@origin" -m "merge: resolve conflict against ${base}@origin"
+  ```
+
+  Merge from the bookmark, never from `@`: a `jj split` leaves `@` an empty, undescribed
+  commit above the described one the bookmark already names, and `jj git push` refuses to push
+  any commit without a description — merging from `@` drags that undescribed commit into the
+  ancestry and the push fails (`Won't push commit … since it has no description`); the bookmark
+  is always on a described, already-pushed commit. If the merge conflicts, resolve it in that
+  one commit — edit the markers directly; there is nothing to squash, since the merge is the
+  only new commit. Then `jj -R "$LEGION_WORKSPACE" new` to move off it, and push it (*Every role
+  pushes its own commits* in `skill://legion-worker`; a merge is a code push like any other): the
+  merge descends from both the bookmark's old position and the destination, so it is a genuine
+  fast-forward and *Rewriting pushed commits* never applies.
+- **After the handoff import moved the branch.** `legion handoffs import` moves `legion/<KEY>`
+  once, with a commit whose message is `chore(legion): <KEY>'s handoffs are on its Dispatch issue
+  now`, which removes the `.legion/` directory where handoffs lived before they moved to Dispatch.
+  A push it refuses as a moved branch is cured forward: `jj -R "$LEGION_WORKSPACE" git fetch`,
+  then `jj -R "$LEGION_WORKSPACE" new @- legion/<KEY>@origin -m "merge: legion/<KEY>@origin after
+  the handoff import"` (from `@-`, your own described tip, since your local bookmark may now
+  disagree with the remote one), `jj -R "$LEGION_WORKSPACE" new`, and the push — never a rewrite.
+- **After a retarget.** Retargeting a pull request to a new base does not re-run Tests. Read
+  `base` again and merge the bookmark onto it in one command
+  (`base=$(gh pr view <n> -R <owner>/<repo> --json baseRefName -q '.baseRefName | @json') && jj -R "$LEGION_WORKSPACE" new legion/<KEY> "${base}@origin" -m "<message>"`) and push it the
+  ordinary way — a genuine fast-forward, never `--allow-backwards` — so the new head runs Tests
+  against the new merge result, and cite that run in the PR body.
+
+## The unchanged-diff check
+
+The fingerprint every role compares after a forward merge (every flag and the fileset
+verified on jj 0.45.1):
+
+```bash
+base=$(gh pr view <n> -R <owner>/<repo> --json baseRefName -q '.baseRefName | @json') && \
+cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && \
+fingerprint=$(set -o pipefail; jj -R "$LEGION_WORKSPACE" diff --from "fork_point(${base}@origin | <head-sha>)" --to <head-sha> \
+    --git --context 0 '~(.legion | docs/solutions)' \
+  | sed -e '/^@@/d' -e '/^index /d' | sha256sum) && echo "$fingerprint"
+```
+
+- `<head-sha>` is a full commit SHA; a jj commit id is the git SHA GitHub shows.
+- `fork_point(${base}@origin | <head-sha>)` is the base the branch was cut from *at that head*:
+  the old base for the head before the merge, the new base for the merge head, so one command serves
+  both sides. `base` is the pull request's base branch as a jj string literal, as in the merge
+  above.
+- A head the merge replaced is still addressable by its SHA in the shared workspace. The check
+  prints a fingerprint only when every step of it succeeded: the base read, the fetch and the
+  diff (`pipefail` keeps the diff's failure through `sed` and `sha256sum`, which would otherwise
+  hash empty input to `e3b0c442…`). A nonzero exit or no printed fingerprint (a failed read of the
+  base, or a SHA the workspace cannot resolve) counts as a changed diff — never as unchanged.
+- `--context 0` drops context lines; the `sed` drops `@@` hunk headers (line positions move
+  on a merge) and `index` lines (blob ids move when the base's copy of a file changed). What
+  is left is exactly the added and removed lines per file.
+- The single fileset `'~(.legion | docs/solutions)'` leaves out `.legion/`, where handoffs lived
+  before they moved to Dispatch (the handoff import's commit removes it), and retro's learnings:
+  paths the merge gate lets through above an approval
+  (`skill://legion-worker/references/merge-gate.md`), which change
+  between one role's verified head and the next without changing the product. This is what lets
+  each role compare against *its own* last verified head instead of trusting another role's
+  numbers. It must be one expression: jj unions positional filesets, so two separate
+  `'~.legion' '~docs/solutions'` arguments select every file and exclude nothing. Where
+  `.legion/` is gone, jj warns `No matching entries for paths: .legion` on stderr; the hash is
+  unaffected.
+
+Where each role gets its two heads: the implementer — the tip before and after its own forward merge;
+the tester — the commit its latest results name and the new head; the reviewer — the `commit_id` of
+its last submitted review (`gh api --paginate repos/{owner}/{repo}/pulls/{n}/reviews --jq '.[] | {commit_id, state, user: .user.login, body}'`, whose pages concatenate in order, so the last line is the last submitted review, and whose body tells a no-fix request that answered a READY refusal from any other)
+and the new head; the merger never computes a fingerprint — it quotes the `--summary` lines
+in READY, and the daemon holds the head to retro's commits.
+
+The fingerprint is not the whole check: a file the merge adds only moves the hash, exactly as an ordinary round of work does.
+So beside it, compare the *set* of files the pull request changes against its base, before and after the merge (`gh pr diff <n> --name-only`, or `jj diff --stat` at each of the two heads), and explain every path that appears or disappears.
+Remove a path that belongs to an already-merged pull request.
+The case that named this rule: #2588's forward merge, made after #2446 was squashed into main, re-added changelog fragments under `packages/envoy/.changes/unreleased/` whose entries main's fold had already written into `packages/envoy/CHANGELOG.md` 27.1.0, so the next fold would have written every one of them a second time.
+
+## Rewriting pushed commits
+
+**Rewriting pushed commits** — a `jj squash --into` a commit already on GitHub, or any other
+rewrite of a commit you already pushed — is the hazard *Reintegrating the base* describes, in a
+second shape: jj rebases every descendant of any commit it rewrites, and in the one shared
+repository a descendant can be another tree's branch stacked on your pushed commit, which then
+moves, with its bookmark, onto a rewritten copy. So look for a descendant outside your own chain
+first, after a fetch and while your chain still descends from the pushed tip:
+
+```bash
+cd -- "$LEGION_WORKSPACE" && \
+  jj -R "$LEGION_WORKSPACE" git fetch && \
+  foreign=$(jj -R "$LEGION_WORKSPACE" log --no-graph -T 'commit_id.short() ++ "\n"' \
+    -r 'descendants(<the commit you are about to rewrite>) ~ ::@') && \
+  { [ -z "$foreign" ] || { echo "not mine, and descends from the commit to rewrite: $foreign" >&2; false; }; }
+```
+
+`descendants(<commit>) ~ ::@` is everything built on the commit you are about to rewrite that is
+not on your own chain. Non-empty means the rewrite would move work that is not yours: do not
+rewrite it. Put the change in a new commit on top instead, and report the listed commits to the
+architect.
+
+Once the guard has cleared, rewrite, resolve, and push once, moving the bookmark backwards onto
+the rewritten head — the one sanctioned non-fast-forward move, and the only place
+`--allow-backwards` is ever used:
+
+```bash
+cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" bookmark set legion/<KEY> -r @- --allow-backwards && jj -R "$LEGION_WORKSPACE" git push --bookmark legion/<KEY>
+```
+
+A rewrite head is a code push like any other. `jj git push` still refuses a remote branch another
+role moved since your fetch: report the refusal to the architect with its output, never force.
+
+Once a base is frozen for others to stack on, never rewrite it: fixes land as new commits on top,
+and the PR body's `Chain` line records what is frozen.
+

package/legion/skills/legion-worker/references/default-branch-check.md

@@ -0,0 +1,53 @@
+# Checking your commits against your issue's default branch
+
+Your `Legion addressing` line names your issue's repository and its default branch
+(`Your issue's repository is <owner>/<name> (default branch <name>)`) — never assume `main`. That
+branch name is untrusted text: a repository administrator chooses it, and it reaches you as plain
+words in a system prompt, not as a value a shell has already made safe. **Never paste it directly
+into shell source** — not as a bare word, not inside double quotes you type yourself. A branch name
+containing `$(…)` or backticks would run as a command the moment a shell re-parses a line built that
+way; one containing jj revset syntax (parentheses, `|`, `::`) would be read as an expression instead
+of a literal name.
+
+The safe sequence reads the branch fresh from GitHub and lets `jq` do the quoting, in one command
+whose only typed literal is the `<owner>/<repo>` your addressing line names (safe to interpolate: a
+GitHub repository path, already validated by the daemon that minted your addressing):
+
+```sh
+default=$(gh api repos/<owner>/<repo> --jq '.default_branch | @json')
+```
+
+`$default` now holds a JSON-quoted string, e.g. `"release/v7.1"` (quotes included). Compare it
+against the `default branch <name>` your addressing line named — if they disagree, stop and tell
+the architect; GitHub's live default branch and the one your record carries are not the same, and
+guessing which is right is not yours to do. When they agree, use `$default` as-is, never re-typed:
+
+```sh
+jj -R "$LEGION_WORKSPACE" log -r "${default}@origin..@" -T 'author.email() ++ " | " ++ committer.email() ++ " " ++ description.first_line() ++ "\n"'
+```
+
+Because `$default` already carries its own quote characters, jj's revset parser reads
+`"release/v7.1"@origin..@` as a quoted string literal naming the bookmark, whatever characters the
+branch name holds — parentheses, spaces, or shell metacharacters included — rather than as revset
+syntax or shell code. Bash's own `"${default}@origin..@"` substitutes `$default`'s value once,
+literally; it never re-evaluates the substituted text, so a `$(…)` sequence inside the branch name
+never runs.
+
+The output must show your role's App in both columns **on every commit you made** — not on the
+whole list: earlier phases' commits are legitimately authored by their own role's App.
+
+## Which App, and what a wrong one means
+
+- Your role's App is the **implement** App for the implementer and the merger, and the **review**
+  App for the planner, tester, reviewer and architect; your pane's `JJ_USER` and `JJ_EMAIL` name
+  its bot account. A planner's commits authored by the review App are right.
+- Never set `user.name` or `user.email` in any jj or Git scope (`jj config set`, `--config`,
+  `git config`): `--config` outranks the pane's identity and puts the wrong App on your commits,
+  and the repository-scoped jj config is one file shared by every issue workspace of the clone.
+- A wrong identity on your own commit (the other App, or none) is a pane-environment problem:
+  report it to the architect, never pin it (cybermonklabs/legion
+  `docs/solutions/legion/shared-main-repo-hazards-for-concurrent-issue-workspaces.md`, Hazard 1).
+- Another role's commit with you as committer, which you did not rewrite under the guard in
+  *Rewriting pushed commits* (`skill://legion-worker/references/conflicts-and-rewrites.md`), means
+  something rewrote commits it should not have: stop and send the architect this log. A forward
+  merge rewrites nothing, so it changes no committer.

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

@@ -0,0 +1,199 @@
+# A finding outside your issue
+
+Read this when you find a problem the issue you work does not cover: a defect in another
+component, repository or tool, a gap in Legion itself, or a production check's `fail`. It holds for
+every Legion role (each phase worker, each architect, the controller) and for each of their
+subagents, and it replaces the filing step of `skill://dispatch-first` and `skill://dispatch`. The
+controller fixes nothing itself: it hands a finding to the tree that owns the code, as
+`skill://legion-controller`, "Findings, and the issues you file", says.
+
+## Fix it where you are, else hand it over, and ask only for a decision
+
+A finding outside your issue never becomes a `dispatch issue` you file. Take the first of these
+three steps that fits:
+
+1. **Fix it here.** A defect with a clear fix in code your tree touches or depends on goes into
+   your tree's own pull request, while you are in that code. The fix needs no choice a person must
+   make, and the evidence shows the defect. Say in your handoff and in the pull request body what
+   you fixed beside the issue's own work. A fix deferred to another issue is a fix nobody makes.
+2. **Hand it over.** Any other clear defect goes to the controller with its evidence, as [Send a
+   finding to the controller](#send-a-finding-to-the-controller) says. The controller gives it to
+   the running tree whose code it is. Only when no tree owns that code does it file a Legion root.
+3. **Ask.** A finding that needs a person's authority, taste or risk appetite is a `dispatch ask`
+   with one recommendation, as [Where it goes](#where-it-goes) says: whether the work is wanted at
+   all, which of several designs, who owns it, or a change of scope, cost or risk.
+
+A fix you are not sure of is not step 1: hand it over, or ask when a person must decide.
+
+- A problem inside your issue is not such a finding: fix it in your change, since nothing needed
+  for correctness is deferred.
+- A problem inside your tree is work its root spec's acceptance needs. A phase worker's such
+  problem outside its own issue goes to the tree's architect (`skill://legion-worker`, *Stop
+  rules*), which adds it to an open pull request of the tree, or files a child when it is a
+  separately deliverable change. Anything else, in the same
+  repository or not, is a finding.
+- Search first (`skill://dispatch-first`): when an open issue already tracks the problem, comment
+  the evidence on that issue and send or ask nothing. When an open ask on the report issue already
+  asks about it (`dispatch open-asks --project <PROJECT>` lists them), add your evidence under that
+  ask (`dispatch comment --issue <REPORT KEY> --reply-to-ask '<ask id>' --body-file -`, the
+  evidence on stdin) and open no second one.
+
+These issues are filed:
+
+- an architect's children of its own tree (`dispatch issue --parent`, `skill://legion-architect`)
+- a Legion root the controller files for a clear defect no running tree owns
+- an issue a person asked the controller to file, in a direct message, in a Slack request, or in
+  their answer to an ask
+- the report issue itself, which the controller creates once when the project has none
+
+`skill://legion-controller`, "Findings, and the issues you file", and
+`skill://legion-controller/references/daily-report.md` say how.
+
+## Send a finding to the controller
+
+Post the evidence first as a `dispatch comment` on the report issue ([Where it goes](#where-it-goes)
+says which), its first line exactly `Clear defect from <your role token>`. It prints
+`Posted comment <id>`. Then send the controller one message with
+`envoy_publish` to the controller topic your `Legion addressing` line names, with
+`expects_reply: none`. It holds:
+
+- your role token, from your `Legion addressing` line
+- the defect: what went wrong, where and to whom, with the numbers, and the issue it came from
+  (`dispatch://<KEY>`)
+- where the fix belongs: the repository and the component
+- the fix
+- the evidence comment, `dispatch://<REPORT KEY>/comment/<id>`
+
+The controller hands it to the running tree whose code it is, and files a Legion root only when no
+tree owns that code. Either way it replies under your evidence comment with where the work went.
+You file nothing, and you wait for nothing. When the report issue is missing or closed, put the
+evidence in the message itself. A production check's recorded result then names the defect as
+sent to the controller.
+
+### When no controller takes it
+
+The controller topic is a live wake: a message published while no controller runs reaches nobody
+at the time. `envoy_publish`'s own answer tells you whether one took it. A publish to a role
+answers with its live `holder`. With no claim on `legion-<project>-controller` at all, the answer
+says Envoy kept the message instead (`packages/envoy/cmd/listener`, the test "unheld role is kept
+and answered 202 without publishing on the role topic"): the next session that claims the role is
+handed each kept message once, within one hour of the keep. A keep is not a delivery: a
+controller can stay away for the whole hour, and a message kept longer than an hour is dropped
+unread, so a kept finding can reach nobody. It fails with `role legion-<project>-controller
+holder <session> lapsed; claim retained`, naming the holder, its `holder_state` and its
+`last_seen`, when a controller holds the role and its session has not registered within the live
+window: an `unresponsive` controller is not a stopped one, so release nothing, take nothing from
+it, and publish no second copy.
+Treat a kept answer as a controller not taking it. Either way the finding has not been taken yet,
+so make it an ask, as
+[What the ask says](#what-the-ask-says) spells it, on the first
+of these that holds, so a person sees it and the controller finds it when it returns:
+
+1. **The report issue is open:** ask there, the question opening `Clear defect from <your role
+   token>` and `--ref` naming your evidence comment. Then reply `Asked dispatch://<REPORT
+   KEY>/ask/<id>` under that comment, so the controller takes the ask and not the comment. The
+   report issue's assignee sees the ask, and the controller's catch-up takes it.
+2. **The report issue is missing or closed:** ask on your own issue, the evidence posted there as
+   a comment first. Then publish the ask's reference to your tree's architect (`skill://legion-worker`,
+   *Stop rules*). An architect holds its own. The architect holds your issue's
+   acceptance until a controller has taken the ask (`skill://legion-architect`, "Acceptance and the
+   merge"). That hold is what keeps the ask readable: an open ask on a closed issue drops out of
+   the controller's own listing (`asks.go`'s `listOpenAsks` takes `i.closed_at is null`), so an
+   issue that closed over one hides it for good.
+3. **Your own issue is closed too** (Dispatch refuses the ask `409 ISSUE_CLOSED`, as on a
+   production check): put the report issue back in reach yourself, with the `dispatch` commands
+   below, and ask there. Never `legion({op: "set_status"})`, which the controller's report steps
+   (`skill://legion-controller/references/daily-report.md`) use: that op is the controller's
+   alone, and your session is refused `set_status is not
+   available to a phase-worker session` (`packages/pi-legion/src/tools.ts`'s `OPERATIONS`). No
+   other issue can hold an answerable ask, so this is the one case a role writes the report issue.
+   - It exists and is closed: `dispatch issue-update --issue <REPORT KEY> --status icebox`. Send
+     the status by itself. A closed issue takes a reopening status alone, and refuses it beside
+     an assignee or any other field (`api/issue_patch.go`, the `before.ClosedAt` branch). This is
+     the one lifecycle status your own prompt lets you write. The report issue is in no tree, so
+     the daemon re-asserts nothing on it: `workflow`'s `sessionStatusWrite` acts only for a
+     session that claims the issue's tree, or for an admitted root.
+   - A search finds none: create it as "Where it goes" names it, `dispatch issue --project
+     <PROJECT> --title 'Legion daily report' --spec-file -`, with the Summary
+     `skill://legion-controller/references/daily-report.md` gives, then park it with
+     `dispatch issue-update --issue <NEW KEY> --status icebox`. It carries no `legion` label.
+   - Then post the evidence there and ask there, as [What the ask says](#what-the-ask-says)
+     spells it. Say in your summary that you reopened or created it, so the controller knows.
+
+Name the ask in your summary, and in the result a production check records.
+
+## Where it goes
+
+An ask goes on the controller's report issue whenever it is open: the issue the deployment
+instructions name for Legion's reports, else the project's `Legion daily report`, which
+`dispatch search --query '"Legion daily report"' --project <PROJECT>` finds. It stays open in
+`icebox`, so the ask stays answerable whatever happens to the issue it came from; once an issue
+closes, its close withdraws its open asks (a reopen brings them back), and Dispatch refuses their
+answers (`409 ISSUE_CLOSED`). The question names the issue the finding came from by its
+`dispatch://` reference.
+
+When the project has no report issue yet, or a person closed it (`dispatch read` shows `Status:
+done`, and Dispatch refuses the ask with `409 ISSUE_CLOSED`), do not create or reopen one yourself
+(the controller does): send the finding to the controller as text, with `envoy_publish` to the
+controller topic your `Legion addressing` line names (`expects_reply: none`), holding the problem,
+the issue it came from, the evidence and the decision it needs. The controller creates or reopens
+the report issue and opens the ask. When that publish fails because no controller holds the role,
+take step 2 or 3 of [When no controller takes it](#when-no-controller-takes-it). A production
+check's recorded result then names the finding as sent to the controller, or names the ask.
+
+## What the ask says
+
+The question stands alone, since the ask view shows no comment. It holds at most 2,000 characters,
+the `Ref: <reference>` line `--ref` appends included (about 75 characters for a comment's
+reference). Its first line names who asks: `Clear defect from <your role token>` for a clear
+defect no controller took, else `Finding from <your role token>`. The architect's acceptance and the
+controller's catch-up find a finding ask by that line. Then it names the concrete case before any
+general statement of it:
+
+- what went wrong, where and to whom: the issue it came from (`dispatch://<KEY>`), the machine,
+  file, command or session, and the numbers;
+- where the fix would belong: the repository and component, and a plain statement that it is not
+  Legion's when it is not. A problem is not Legion's because you work in Legion: name the
+  component that misbehaved;
+- the decision a person must make, what happens to whom under each option, and your
+  recommendation and its reason. A clear defect no controller took carries the fix instead, and its
+  options ask where the work goes, with `Hand it to the owning tree` first and recommended.
+
+Evidence the decision does not need (full command output, logs, every file and line, the pull
+request) goes in a comment. Post it first as a `dispatch comment` on the issue the ask goes on,
+which prints `Posted comment <id>`, and cite that comment with `--ref`, the one reference an ask
+takes. That issue,
+`<ASK KEY>` below, is the report issue, except as [When no controller takes
+it](#when-no-controller-takes-it) says:
+
+```bash
+dispatch comment --issue '<ASK KEY>' --body-file - <<'EOF'
+<the evidence: commands, output with its time, file:line, links>
+EOF
+# Keep `File it for Legion` only when your Legion addressing line lists the repository where the
+# fix belongs. For a clear defect no controller took, replace the `File an issue` option below with
+# 'Hand it to the owning tree: <the tree, when you know it>', the first option and recommended.
+dispatch ask --issue '<ASK KEY>' --ref 'dispatch://<ASK KEY>/comment/<id>' --question-file - \
+  --option 'File an issue: <what it would track, and who would own it>' \
+  --option 'File it for Legion: Legion works it once it is filed' \
+  --option 'Do not file: <what stays as it is>' <<'EOF'
+Finding from <your role token>
+<what went wrong, where and to whom, with dispatch://<KEY> and the numbers; where the fix belongs, and that it is not Legion's when it is not; what each option does to whom; your recommendation and why>
+EOF
+```
+
+Legion refuses to record an issue on a repository the project does not map, hence that condition.
+
+## Tell the controller about the ask
+
+The person answers in Dispatch, and the answer reaches only the ask's followers. So once the ask is
+open, `envoy_publish` its reference, `dispatch://<REPORT KEY>/ask/<id>` (the id from the
+`Asked <id> on …` line), to the controller topic your `Legion addressing` line names, with
+`expects_reply: none`. The controller follows the ask and files what the person's answer asks for;
+you file nothing, whatever the answer says. The controller itself skips this step, since it follows
+each ask it opens. When the listener kept that publish rather than a holder taking it, do nothing
+more for an ask on the report issue: the controller's catch-up follows it at its next start.
+
+An ask on the report issue blocks nothing of your own issue: its work goes on. One on your own
+issue holds its acceptance, as step 2 of [When no controller takes
+it](#when-no-controller-takes-it) says.