@floh-solutions/pharos-cli 0.23.0 → 0.25.0

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pharos
-description: "Use for AZURE DEVOPS work specifically — when the user says Azure DevOps, ADO or dev.azure.com, or names an ADO work item by number (\"pick up 4821\", \"what's on 210\"). Covers reading or updating an ADO work item, ticket, bug, story or epic; the ADO board, backlog, sprint or iteration; what is assigned to you in Azure DevOps; reading or writing an ADO project wiki page and its comments; linking a plan to an epic; attaching a file to a work item or taking one off; putting an inline image into a description, a comment, a wiki page or a wiki comment; @mentioning somebody so they are actually notified; importing Markdown, Word or PDF files as wiki pages; and whether a failed Azure DevOps call is worth retrying. NOT for other trackers — the Argus board, GitHub issues, Jira, Linear — where \"task\", \"todo\" and \"board\" mean something else entirely."
+description: "Use for AZURE DEVOPS work — when the user says Azure DevOps, ADO or dev.azure.com, or names an ADO work item by number (\"pick up 4821\", \"what's on 210\"). Covers reading or updating an ADO work item, ticket, bug, story or epic; the ADO board, backlog, sprint or iteration; what is assigned to you; reading or writing an ADO wiki page and its comments; linking a plan to an epic; attaching a file to a work item or taking one off; inline images in a field or wiki page; @mentioning somebody so they are notified; importing Markdown, Word or PDF as wiki pages; and whether a failed call is retryable. ALSO the GITHUB ISSUE ↔ work item EDGE: adopting an issue as a work item linked at both ends, bulk-adopting a repo, one reply reaching reporter and board, where they have drifted, closing both ends together, and changing a comment that ALREADY EXISTS: editing, deleting, reacting, hiding, pinning. NOT a GitHub CLI: listing or viewing an issue, or POSTING a comment, is `gh`'s job. NOT for other trackers — Argus, Jira, Linear."
 license: Proprietary
 ---
 
@@ -59,21 +59,54 @@ wiki image <file>              a picture for a PAGE or page comment. Different
 wiki import <file...>          .md .txt .docx .pdf .rtf .html -> pages. A
                                .pptx is refused, on purpose — see below
                                --under <path> --as <name>
-comment list | add | edit | delete   <target> is a work item id OR a wiki path
-comment react | unreact | reactors   like dislike heart hooray smile confused
+comment list | add | edit | delete   <target> is a work item id, a wiki path,
+comment react | unreact | reactors   OR a GitHub issue (contoso/widgets#45)
+comment hide | unhide | pin | unpin  GITHUB ONLY — Azure DevOps has neither
+                               REACTIONS ARE NOT ONE VOCABULARY. Azure DevOps:
+                               like dislike heart hooray smile confused. GitHub:
+                               thumbs-up thumbs-down laugh hooray confused heart
+                               rocket eyes. Passing one platform's name to the
+                               other is refused, not translated
+                               `comment add` is REFUSED on a GitHub issue — see
+                               "Editing a GitHub comment" below
+issue adopt <owner/name#45>    a GitHub ISSUE becomes a work item, with BOTH
+                               ends of the link written. --type --title --parent
+issue link <owner/name#45> <id>   join an existing pair — or finish a join that
+                               half-happened. Only the missing half is written
+issue say <owner/name#45>      ONE message, TWO audiences: the whole of it to
+                               the reporter on GitHub, a summary and that
+                               comment's URL to the board. --summary
+issue trail <id|owner/name#45> the whole trail from EITHER end, with the
+                               evidence for each half. Read-only
+issue drift                    where the two platforms DISAGREE — the report no
+                               other tool can produce. --repo --limit --wiql
+issue backfill <owner/name>    bulk adopt every issue the board does not link
+                               yet. Needs --yes. --limit --state --label
+issue close <id|owner/name#45> close BOTH ends, then RE-READ both to say what
+                               actually moved. --to --reason --all
+issue edit <owner/name#45>     the issue's OWN fields, behind a lost-update
+                               guard. Needs --yes. --title --text/--file/--stdin
+                               --milestone --add-label --remove-label
+                               --add-assignee --remove-assignee --if-title
+                               --if-body. `gh issue edit` is the UNGUARDED one
 hooks list | check | create | repoint | delete    service hooks for realtime.
                                `check` needs --hub <url>; `list` shows the URL
                                already in use
 plan <file>                    an implementation plan → a work item tree
 setup                          org, project, token → keychain + shell profile
                                --install ask|all|a,b  offer the optional
-                               capabilities (LibreOffice, poppler, converter)
+                               capabilities (LibreOffice, poppler, converter,
+                               the GitHub CLI)
+                               --repo owner/name --gh-account <login>  bind a
+                               repository to the GitHub account that reaches
+                               it. BOTH or NEITHER — `issue` needs this first
 doctor                         what is installed on THIS machine, what is
                                missing, and what each missing thing costs
 ```
 
 Text input: `--text` / `--file` / `--stdin`. Global: `--pretty` for a human,
-`--yes` for destructive verbs, `--dry-run` to preview.
+`--yes` for destructive verbs, `--dry-run` to preview, `--max-writes <n>` to
+change the per-invocation write cap (default 20; `0` is read-only).
 
 **`ADO_ORG`, `ADO_PROJECT` and `ADO_PAT` are already in the environment** after
 setup. Do not check them before working; a missing one announces itself as
@@ -83,8 +116,10 @@ setup. Do not check them before working; a missing one announces itself as
 commands further down name them with confidence they have not earned on yours.
 `pharos doctor` answers that in one call: what is present, its version and where
 it resolved, what is missing, and what each missing thing actually costs. It is
-read-only, offline, and works before anything is configured — so it is also the
-right first move when something behaves oddly.
+read-only and works before anything is configured — so it is also the right
+first move when something behaves oddly. Offline too, with one exception it
+names: `gh auth status` validates every token against github.com and there is
+no flag that stops it, so that probe runs only when `gh` is installed.
 
 `pharos setup --install ask` then offers to install them, driving Homebrew, apt
 or winget rather than vendoring anything. **Nothing installs without that flag**
@@ -596,6 +631,345 @@ leading slash**. Two things follow:
   website, that is why. `wiki links` and `unlink` both ask about **both** shapes,
   so old links still resolve and can still be removed.
 
+## GitHub issues: the join, and only the join
+
+**These verbs are newer than the CLI on most machines. Check before you promise
+one.** `pharos issue` shipped *after* **0.23.0**, so if `pharos --version` prints
+0.23.0 or lower it is not there and every verb below is an unknown command —
+`npm i -g @floh-solutions/pharos-cli@latest` is the fix. This skill and the CLI
+update by different routes and drift apart in both directions; `pharos doctor`
+prints both versions.
+
+**This is not a GitHub CLI and must not become one.** Listing, viewing and
+plainly commenting on an issue is `gh`'s job and `gh` is better at it; closing
+one *end* is `gh issue close`. Pharos owns the one thing `gh` cannot see: which
+work item tracks this issue, written so it survives in both databases.
+
+The one place that line moved: **a comment that already exists** is reachable
+through `pharos comment <verb> <owner/name#45>` — edit, delete, react, unreact,
+reactors, hide, unhide, pin, unpin. Two reasons, and neither is symmetry for its
+own sake. Editing or deleting one can destroy the link record, so it needs the
+guard below rather than a bare `gh api`. And hiding or pinning has **no
+first-class `gh` verb at all** — they are GraphQL mutations with no REST route,
+which is the "nothing else can do this" test the rest of these verbs pass.
+Posting a *new* comment is still not ours.
+
+The second place it moved, and it is the only verb here that overlaps `gh` head
+on: **`pharos issue edit` exists to REFUSE.** `gh issue edit` does the same
+write and does it well — what it cannot do is notice that somebody changed the
+thing you were overwriting. It reads nothing and compares nothing, so if a
+colleague renamed the issue while you were composing, their rename is gone and
+neither of you is told. That is fine for a human at a terminal and wrong for an
+agent, which reads an issue, spends a minute thinking, and writes back into a
+world that moved. **If you want an unguarded edit, use `gh issue edit` — it is
+right there and it is better at it.**
+
+Azure DevOps has its own GitHub integration and **the link it makes carries
+nothing** — title, body, comments, labels and state stay on their own island,
+and the transition only ever fires from a commit or a PR merge, never from
+closing an issue. That gap is the whole reason these verbs exist.
+
+```bash
+pharos issue adopt contoso/widgets#45 --parent 39   # an issue → a work item, both ends
+pharos issue link  contoso/widgets#45 4821          # join a pair that already exists
+pharos issue trail 4821                             # …or trail contoso/widgets#45
+pharos issue say   contoso/widgets#45 --file reply.md
+pharos issue drift                                  # where the two disagree
+pharos issue backfill contoso/widgets --limit 25 --yes
+pharos issue close 4821 --text "Shipped in 1.4.0."
+pharos issue edit  contoso/widgets#45 --title "Crash on resize" --yes
+```
+
+### Editing an issue, and the guard GitHub does not give us
+
+**There is no conditional write.** `PATCH /repos/{o}/{r}/issues/{n}` answers
+**400** to `If-Match` — measured, not assumed — so the `{"op":"test","path":
+"/rev"}` guarantee behind every Azure DevOps patch has no GitHub equivalent.
+Never send `If-Match` here yourself either: it is not inert, it fails the write,
+and the 400 reads like a malformed body.
+
+**And do not guard on `updated_at` or the ETag.** Both move when somebody merely
+*comments* on the issue, so a guard keyed on either refuses a good edit for a
+change that touched nothing — it fires on the case that is *not* a collision.
+
+So the guard compares the **value of the field you are overwriting**: re-read
+immediately before sending, and refuse only if that text moved. A comment cannot
+cause it, which is what makes the refusal worth reading.
+
+| you pass | the base is | what it protects |
+|---|---|---|
+| nothing | this command's own read | one round trip. Honest, and small |
+| `--if-title` / `--if-body` / `--if-body-file` | what **you** saw | the whole gap between your read and your write |
+
+Pass `--if-*` whenever you read the issue and then thought about it — that gap is
+where a collision actually happens. The output says which window it guarded, as
+`fields.guard.window`: `in-command` or `caller`.
+
+A refusal is `kind: "conflict"`, exit **1**, and carries `conflicts` (base,
+remote and proposed for each field) plus `attribution` naming who renamed it.
+Re-read, fold their change into yours, edit again with `--if-title` set to what
+you just read. **It is not atomic and nothing client-side can make it so** — it
+narrows the race to one round trip rather than closing it.
+
+Two things GitHub does *quietly*, which this verb reports and a bare `gh api`
+would not:
+
+| endpoint | the silence |
+|---|---|
+| `POST …/labels` | **creates** a repository label that does not exist — 200, grey, permanent, spelled exactly as you typed it. So an unknown label is REFUSED with the near misses named; `--create-label` is how you mean it |
+| `POST …/assignees` | **ignores** a login it will not assign and still answers 201. Read `assignees.ignored` — a status code is not the answer here |
+
+Labels and assignees go through those add/remove endpoints and never through the
+whole-issue PATCH, which carries them as *whole arrays* — one label write would
+otherwise blindly overwrite every label on the issue.
+
+### Bind the repository first, or none of this runs
+
+```bash
+pharos setup --repo contoso/widgets --gh-account alisina-tibata
+```
+
+**Both flags or neither**, and there is deliberately **no fallback to whichever
+account `gh` has active**: two accounts can each see a repository of the same
+name, so the wrong one answers **200** for a different repository — a wrong
+answer rather than an error.
+
+An unbound repository is `"kind": "config"` on exit 2, naming
+`~/.config/pharos/repos.json` — never a guess — **and it lists the repositories
+that ARE bound**, so a typo is visible without reading the file. That check runs
+before everything else here, so it is the first thing to fix. `gh` itself is
+optional: without it every `issue` verb is refused by name with the reason and
+the Azure DevOps verbs are untouched. `pharos doctor` reports both.
+
+A failure that came from GitHub says **`"platform": "github"`**, because these
+verbs touch two platforms in one call and which one refused is the first thing
+to know. Its absence means Azure DevOps or this tool, as everywhere else.
+
+### `adopt` is safe to re-run. `say` is NOT. Do not generalise from one.
+
+**Adopting the same issue twice never creates a second work item.** What it
+does instead depends on the state the pair is in, and the exit code tells you
+which:
+
+| exit **0**, `created: false` | the issue carries a marker. You get the work item it names and nothing is written — the state you asked for already holds |
+| exit **3**, `halfLinked: true` | a work item already links this issue and the issue says nothing about it. Refused, carrying `recover` — the link wants **finishing**, not repeating |
+| exit **3**, `workItemIds` with two entries | two work items claim one issue. Refused, both named, no `recover`: picking one would be inventing an answer |
+
+Azure DevOps is written **first**, because the work item id does not exist until
+the create lands, so the one failure `adopt` can leave is always the same shape:
+the board end written, the GitHub end not.
+
+```jsonc
+{ "error": { "createdWorkItem": 4821, "halfLinked": true, "wrote": ["hyperlink"],
+             "recover": "pharos issue link contoso/widgets#45 4821" } }
+```
+
+**Read more than `kind` on that error**: a work item now exists, and reading
+only the kind loses its id. `recover` is the literal command that finishes the
+job, and nothing needs undoing first.
+
+**Re-running `adopt` there is safe but it is not the repair** — it refuses,
+because the row above is exactly the state it detects, and the refusal hands
+back the same `recover` string. Take it either from the failure or from the
+refusal; they are the same command. `link` writes only the half that is missing,
+which makes it both the fix here and the ordinary way to join a pair that
+already exists. `pharos issue drift` finds this state later if nobody acted on
+it at the time — it reports it as `one-sided`, carrying the same repair.
+
+Every `adopt` reports `boardCheck`. `{"ran": true}` means the board was searched
+for a work item that already tracks this issue; `{"ran": false}` carries the
+reason it could not be, and then a half-link made on **another machine** would
+not have been seen — `pharos issue drift --repo <owner/name>` asks the same
+question deliberately.
+
+`say` is the opposite, and that is the trap. **GitHub is written first there**,
+because the board's comment carries the GitHub comment's URL and that does not
+exist until the POST returns. So a failure on the board half leaves a **public
+comment already posted**, and re-running posts a second one:
+
+```jsonc
+{ "error": { "halfSaid": true, "wrote": ["github-comment"],
+             "github": { "commentUrl": "https://github.com/…#issuecomment-950" },
+             "recover": "pharos comment add 4821 --stdin", "adoComment": "…" } }
+```
+
+Feed `adoComment` into `recover`. Do not re-run `say`.
+
+### `say` — one message, two audiences
+
+|  | GitHub | Azure DevOps |
+|---|---|---|
+| who reads it | the reporter, who has **no** Azure DevOps account and never will | the team |
+| what they get | the full explanation | a summary, and the URL of the comment carrying the rest |
+
+**The asymmetry is the verb.** The same words in both places is `gh issue
+comment` followed by `pharos comment add`, and neither of those knows the other
+happened. Without `--summary` the board gets the first paragraph cut to 200
+characters — a guess, and allowed to be one *only* because the comment's URL
+travels with it. GitHub is the record of what was said; the board never is.
+
+**Never pass a message that already carries a `<!-- pharos:v1 … -->` trailer.**
+It is refused (exit 3) before any call, on `say` and on `close`'s closing note
+alike. That trailer means the text is Pharos's own output coming back round — a
+comment you read and re-posted — and it is how a fan-out starts summarising its
+own summaries. Every comment these verbs post carries one on the way out; you
+never write one in.
+
+`say` starts from the **issue** end only. A work item may hyperlink several
+issues, so a bare id names no single reporter — `pharos issue trail <id>` is how
+you find out which one you meant.
+
+### `trail`, and the evidence worth reading
+
+Read-only, and it answers from **either** end with the same output shape. The
+field to read is `evidence`: `["hyperlink","marker"]` is a complete link, and
+either one **alone** is a link that only half exists — a finding, not a detail.
+The halves live in different places on purpose: a `Hyperlink` relation on the
+work item, and one comment on the issue carrying `AB#4821` plus the
+machine-readable trailer.
+
+**The marker goes in a comment, never the issue body.** Editing a reporter's
+body collides with them and needs write access nobody has on a community issue.
+
+### `drift` — the report no other tool can produce
+
+`gh` lists issues and Azure DevOps lists work items; **neither holds both
+sides**, so neither can say *these two disagree*. Four kinds, because they want
+four different actions:
+
+| kind | what it means |
+|---|---|
+| `state` | both ends exist and disagree about whether the work is finished |
+| `missing-issue` | the work item names an issue GitHub does not have |
+| `one-sided` | one platform carries the link and the other does not — what a failed `adopt` leaves. Carries the `pharos issue link …` that repairs it |
+| `unreadable` | the GitHub end could not be read, so nothing about this pair is known |
+
+**It scans links, not issues.** An unadopted issue is not drift — that is
+`backfill`'s question. On a repo with four hundred of them, counting "not
+linked" as a problem buries three real findings under three hundred and
+eighty-eight rows of noise.
+
+**"Finished" is read from the project, never guessed**: each work item is judged
+against its own type's categories and the report says which source it used —
+`Resolved` is terminal on a Bug and open on a User Story. When the catalogue
+cannot be read the stock names are used *and said out loud*, because a row is
+uninterpretable without knowing what was counted as finished. An unreadable
+repository is information rather than a fault and never fails the command.
+
+### `backfill` — the adoption path for the repo that already has 400 issues
+
+```bash
+pharos issue backfill contoso/widgets            # previews, then REFUSES (exit 3)
+pharos issue backfill contoso/widgets --dry-run  # the same preview, exit 0
+pharos issue backfill contoso/widgets --label bug --parent 39 --limit 25 --max-writes 50 --yes
+```
+
+**Read the preview before adding `--yes`.** It names the repository, the `gh`
+account it would be reached as, **and the Azure DevOps organisation and project
+the work items would land on** — nothing in the design pairs a repo with a
+board, and a mis-aimed `adopt` is one work item where a mis-aimed `backfill
+--yes` is four hundred, each with a public comment naming a board its reporter
+has nothing to do with.
+
+**Each adoption is two writes**, so four hundred issues is eight hundred against
+a default cap of 20. That cost is worked out *before* anything is written and a
+run that cannot finish is refused, naming both ways forward — rather than
+stopping at write nineteen, which is the outcome you can reason about least.
+
+**It is resumable and needs no state file.** The link *is* the progress record:
+a second run finds the ones the first adopted already linked and carries on, in
+issue-number order. `--state` defaults to `open`, because adopting a closed
+issue creates a work item that is finished before anybody looks at it.
+
+### `close` — the ending of the trail
+
+Closes **both** ends, comments on each pointing at the other, then **re-reads
+both** and reports what actually moved. Two 200s are not proof: a workflow rule
+can refuse a transition on a field the API happily accepted, so **`verified` is
+what was there afterwards** rather than what was sent. Read it.
+
+**There is no hardcodable `Closed`.** The state comes from the project's own
+categories — exactly one terminal state for that type is used, and *several* is
+a refusal naming them and `--to`, because `Done` and `Removed` are both finished
+and mean opposite things. If the catalogue cannot be read at all it refuses
+rather than guessing.
+
+`--to`, **not** `--state`: `--state` already means `open|closed|all` on
+`backfill`. Closing an already-closed pair writes nothing and exits 0. A work
+item linking several issues is refused unless `--all` says so — "close 4821"
+should not read as "close four strangers' issues".
+
+**Pull requests are out of scope and are refused by name.** On GitHub's API
+every PR is also an issue, so `adopt` on a PR number would otherwise mirror
+something none of this models. `close` does not compose `Closes #45` /
+`Fixes AB#123` into a PR body either: those fire on a PR *merge*, so there would
+be nothing to compose into and nothing to verify.
+
+### Editing a GitHub comment, and the trailer you must not break
+
+A comment that already exists is `pharos comment`, with the issue as the target.
+The verb set is the one you already know from work items and wiki pages:
+
+```bash
+pharos comment list   contoso/widgets#45              # ids, state, and what you MAY do
+pharos comment edit   contoso/widgets#45 900 --file fixed.md
+pharos comment delete contoso/widgets#45 900 --yes
+pharos comment react  contoso/widgets#45 900 thumbs-up
+pharos comment hide   contoso/widgets#45 900 off-topic
+pharos comment pin    contoso/widgets#45 900
+```
+
+**Start with `list`.** It is the only way to learn a comment id, and it also
+answers the question that saves a failed write: every row carries a `may` object
+— `edit`, `delete`, `hide`, `pin`, `react` — read from GitHub's own view of what
+this account may do. A comment you may not edit is `"edit": false` before you
+try, not a 403 afterwards. Each row also carries `pharosAuthored` and
+`workItemId`, so you can see at a glance which comment is the link.
+
+Two ids come back per comment and **both are printed because neither can be
+derived from the other**: `id` is the number that edit, delete and reactions
+address, `nodeId` is what hide and pin take. Either is accepted anywhere a
+comment is named; passing back the one the verb wants saves a request.
+
+**An edit cannot double or strip the `pharos:v1` trailer, and this is enforced
+rather than requested.** That trailer is the durable record of which work item
+tracks this issue *and* the guard that stops the two platforms summarising each
+other's summaries. So:
+
+| what you send | what happens |
+|---|---|
+| new prose, no trailer | the existing trailer is **restored**, and `markerPreserved: true` says so |
+| the body you read back, trailer intact | sent unchanged |
+| two trailers | refused — `doubled` |
+| a trailer naming a different work item | refused — `repointed`; `pharos issue link` is the verb for that |
+| a trailer on a comment that had none | refused — `forged` |
+
+You do not have to think about any of this: hand over the words you want and the
+record survives. It is written down because the refusals name a reason, and the
+reason is actionable.
+
+**Deleting the comment that carries the trailer destroys the GitHub half of the
+link.** It is allowed — a mis-adoption is a real thing — but the `--yes` refusal
+says so first, names the work item, and gives you the `pharos issue link` command
+that puts it back. Under `--dry-run` you get the same preview and exit 0. A
+delete that finds the comment already gone reports `alreadyGone: true` and
+succeeds, so a retry after a lost reply is safe.
+
+**`hide` and `pin` exist on GitHub and nowhere else** — they are GraphQL
+mutations with no REST route, which is why `gh` has no verb for them. Hiding
+needs a classifier and there is no neutral default, because GitHub shows it
+beside the hidden comment: `spam`, `abuse`, `off-topic`, `outdated`,
+`duplicate`, `resolved`, `low-quality`. Ask for `off-topic` and `off-topic` is
+what reads back. On a work item or a wiki page these four verbs are refused with
+"Azure DevOps has neither" rather than as an unknown verb — there is no endpoint
+to go looking for.
+
+**`pharos comment add` is refused on a GitHub issue.** Posting is already
+covered twice and which one you want depends on whether the board should hear:
+`pharos issue say` writes to the reporter *and* the work item, `gh issue comment`
+writes to GitHub only. A third door here would post on an adopted issue that the
+work item never hears about — the exact asymmetry `say` exists to prevent.
+
 ## What `pharos` does NOT do — read this before you go looking
 
 - **Free-text and code search.** Nothing here covers it. For work items,
@@ -606,6 +980,14 @@ leading slash**. Two things follow:
 - **Wiki content search.** `wiki tree` then `wiki read` is the only way through;
   there is no grep across pages.
 - Pull requests, builds, pipelines.
+- **Almost anything on GitHub that is not the join.** No issue list, no issue
+  view, no *posting* a comment, no labels or milestones, no pull requests — `gh`
+  does all of it better and a second GitHub CLI would only drift from it. The
+  seven `issue` verbs are the edge. The one addition is a comment that already
+  exists (`pharos comment <verb> <owner/name#45>`): editing or deleting one can
+  break the link record, and hiding or pinning has no `gh` verb at all.
+- **Jira, Linear, and the Argus board.** Not covered, not planned. "Task",
+  "todo" and "board" mean something else there.
 
 **There is no Azure DevOps MCP server here any more, and that is deliberate.**
 It authenticated through the Azure CLI, so it opened a browser mid-task — which
@@ -617,9 +999,9 @@ routing around it: several things here exist in no other Azure DevOps tool at
 all — wiki page comments and reactions, attachment upload AND removal, inline
 images for a work item field or a wiki page, mentioning somebody in a form that
 actually notifies, importing a Word document or a PDF as a page, editing or
-deleting a work item comment, service hooks, and applying a change under a
-`test` op on `/rev` so a teammate who wrote first cannot be silently
-overwritten. Those are what the
+deleting a work item comment, service hooks, the GitHub-issue join and the
+drift report over it, and applying a change under a `test` op on `/rev` so a
+teammate who wrote first cannot be silently overwritten. Those are what the
 guards are, and they are the reason to come back here rather than hand-roll.
 
 ## Start every task with one command
@@ -739,7 +1121,12 @@ true` means stop re-checking the token.
 | `0` | it worked | carry on |
 | `1` | the call failed | check `kind`; retry only if it is `rateLimit` (wait `retryAfterMs`) or transient |
 | `2` | called wrong, or not configured | **never retry unchanged.** Fix the call, or the setup |
-| `3` | a guard here refused | re-run with `--yes` — after deciding it is right |
+| `3` | a guard here refused | re-run with `--yes`, or raise `--max-writes` — after deciding it is right |
+
+**A failure carrying `"platform": "github"` came from GitHub**, not from Azure
+DevOps and not from here — `pharos issue` touches two platforms in one call, and
+which one refused decides whether the fix is a token, a repo binding or a field.
+Its absence means the other side, as it always did.
 
 `"kind": "conflict"` means somebody wrote first. Your work is still valid:
 re-read, re-apply. It carries both revisions — and note that **posting a comment
@@ -801,6 +1188,12 @@ it is about to break. Sub-pages move with their parent.
    not only in a chat log nobody else can read.
 5. Move the state when the work moves, not at the end.
 
+**When the work started as a GitHub issue the loop gains two ends and changes
+one step**: `pharos issue adopt` before step 1, `pharos issue close` after step
+5, and at step 4 the reply to the *reporter* is `pharos issue say` rather than a
+comment on the work item — a comment on the item is invisible to somebody with
+no Azure DevOps account, which is every reporter.
+
 **Every person uses their own token.** Board attribution is per-person, so
 anything you do is recorded against whoever owns `ADO_PAT`. Never suggest
 sharing one.
@@ -813,3 +1206,21 @@ profile that **scripted** shells read, and verifies both permission scopes —
 Work Items and Wiki are separate in Azure DevOps, and a token missing the second
 works fine until the first wiki write days later. A **new** shell is needed
 afterwards.
+
+**The GitHub half is configured separately and follows a different rule.** The
+environment carries no fourth secret: the credential comes from `gh`, and which
+account reaches which repository is a binding on disk, so a `config` error from
+an `issue` verb names `repos.json` rather than an environment variable.
+
+```bash
+pharos setup --repo contoso/widgets --gh-account alisina-tibata
+```
+
+**A verb whose target is a GitHub issue does not need `ADO_PAT` at all.**
+`pharos comment list|edit|delete|react|unreact|reactors|hide|unhide|pin|unpin
+<owner/name#n>` runs on `gh`'s credential alone, on a machine that has never had
+an Azure DevOps token. So a `config` error naming `ADO_PAT` from one of those is
+a defect worth reporting, not something to go and provision a token over. The
+two credentials are independent — separate keychain entries, and `pharos doctor`
+reports them separately — and `pharos issue` is the one family that genuinely
+needs both, because it writes to both platforms in one invocation.