@floh-solutions/pharos-cli 0.27.0 → 0.29.0

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pharos
-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\"). Covers reading or updating a work item, bug, story or epic; the board, backlog, sprint or iteration; what is assigned to you; reading or writing a wiki page and its comments; searching the board and wiki for a phrase; linking a plan to an epic; attaching a file to a work item or taking one off; inline images in a field or page; @mentioning somebody so they are notified; importing Markdown, Word or PDF as pages; and whether a 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 both, where they drifted, closing both ends together, a PULL REQUEST and its work item, 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."
+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\"). Covers reading or updating a work item, bug, story or epic; the board, backlog, sprint or iteration; what is assigned to you; reading or writing a wiki page and its comments; searching the board and wiki for a phrase; linking a plan to an epic; attaching a file to a work item or taking one off; inline images in a field or page; @mentioning somebody so they are notified; importing Markdown, Word or PDF as pages; and whether a 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 both, where they 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
 ---
 
@@ -84,13 +84,6 @@ issue say <owner/name#45>      ONE message, TWO audiences: the whole of it to
                                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
-pr <owner/name#123>            a PULL REQUEST and the work it belongs to:
-                               state, draft, review verdict, WHICH CHECKS ARE
-                               RED, the issues it closes, and the work items it
-                               reaches — via AB#123 in the body OR via an
-                               adopted issue named by "Fixes #45". Also where
-                               the pull request and the board DISAGREE
-                               --no-work-items  skip the transitive lookup
 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
@@ -105,7 +98,10 @@ issue edit <owner/name#45>     the issue's OWN fields, behind a lost-update
 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
+plan <file>                    an implementation plan → a work item tree.
+                               The plan file writes Epic/Issue/Task and
+                               To Do/Doing/Done; the run maps them to whatever
+                               THIS project calls those roles
 setup                          org, project, token → keychain + shell profile
                                --install ask|all|a,b  offer the optional
                                capabilities (LibreOffice, poppler, converter,
@@ -201,64 +197,6 @@ It parses, returns 200, and matches **everything** — `IN GROUP` covers work it
 TYPE categories only, and an unknown group resolves to the empty set with no
 error. Measured, 2026-08-05.
 
-## After adoption, the work becomes code: `pharos pr`
-
-`issue trail` follows filing -> adoption -> close. It stops at the moment the
-work becomes a branch. `pharos pr` is the part that does not.
-
-```bash
-pharos pr contoso/widgets#123              # the pull request AND the board
-pharos pr contoso/widgets#123 --pretty
-pharos pr contoso/widgets#123 --no-work-items   # skip the transitive lookup
-```
-
-One call replaces `gh pr view` + `gh pr checks` + a WIQL query + a relations
-read, across two credentials — and answers one question none of them can.
-
-**Two paths reach a work item, and the implicit one is the one that fires:**
-
-| | |
-|---|---|
-| `AB#4821` in the body | explicit. What Azure Boards' own app reads |
-| `Fixes #45`, where #45 is adopted | **the one that actually happens** |
-
-The second costs one read per closed issue (its comments, where the `pharos:v1`
-trailer lives) and is why `--no-work-items` exists for when you do not need it.
-
-### `disagreements` is the part nothing else can produce
-
-```jsonc
-{
-  "pullRequest": { "number": 123, "state": "MERGED", "merged": true,
-                   "review": "APPROVED", "checks": "FAILURE",
-                   "failingChecks": [ { "name": "e2e-tests", "conclusion": "FAILURE" } ] },
-  "closesIssues": [45],
-  "workItems": [ { "id": 4821, "type": "Issue", "state": "To Do", "title": "…" } ],
-  "disagreements": [
-    "#4821 is \"To Do\" but this pull request is already MERGED — the work shipped and the board never moved."
-  ],
-  "problems": []
-}
-```
-
-Azure DevOps cannot see the pull request and GitHub does not know the work item
-exists, so **neither system will ever report this**. An empty `disagreements`
-means they agree; it is silent when there is nothing to say.
-
-Three things about the shape:
-
-- **`checks` is the rollup and it is authoritative. `failingChecks` names the
-  red ones** — found by filtering every context, not by showing the first few.
-  Measured: real pull requests report a `FAILURE` rollup while their first
-  several contexts all read `SUCCESS`, because the red one is further down.
-- **`NONE` is not `SUCCESS`.** A pull request with no checks configured reports
-  `NONE`, and a still-running one is `PENDING`, not a failure.
-- **`state` has three values** — `OPEN`, `CLOSED`, `MERGED`. Merged is its own
-  state, not a kind of closed, and `merged: true` is the field to test.
-
-Posting a comment on a pull request is still `gh`'s job, exactly as it is for an
-issue. This verb reads; it does not write.
-
 ## Finding where it is WRITTEN: `pharos search`
 
 `query` answers *which work items*. `search` answers *where has this been
@@ -660,6 +598,15 @@ states exist" and "which mean finished" are different questions — `Inactive` i
 finished on a Test Plan and appears in nobody's hard-coded Done/Closed/Removed
 list.
 
+**Nothing in this CLI writes a state name it was not told.** `query` reads the
+categories to decide what "open" means, `update` refuses a state the type does
+not have, `issue close` moves an item into the project's own terminal state,
+`issue adopt` and `issue backfill` resolve the work item TYPE by role, and
+`plan` maps its file's `Epic`/`Issue`/`Task` and `To Do`/`Doing`/`Done` onto
+whatever this project calls those roles. Where any of them cannot read the
+project it falls back to the stock names **and says so** — `source: "fallback"`,
+a `note`, or a warning on stderr. If you see one, the answer is a guess.
+
 `pharos whoami` is the other one worth reaching for early: it names the identity
 behind `ADO_PAT`, which is who `@Me` resolves to and who every write is
 attributed to. A shared or service token quietly makes "assigned to me" mean
@@ -1015,11 +962,19 @@ pharos issue backfill contoso/widgets --label bug --parent 39 --limit 25 --max-w
 ```
 
 **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.
+account it would be reached as, **the Azure DevOps organisation and project the
+work items would land on**, and **`workItemType` — what they would be created
+as** — 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.
+
+**The type is resolved per issue, from the project, exactly as `adopt` resolves
+it.** It reads which type this project maps to the requirement role and which to
+the bug role, so an issue labelled as a bug becomes a bug and the rest become
+the requirement type — `Issue` and `Issue` on Basic, `Bug` and `User Story` on
+Agile. Every adopted row carries `typeSource` saying which answer it got:
+`category`, `repo-default`, `label`, `flag`, or `fallback` for "the project
+could not be asked". Pass `--type` to pin one for the whole run.
 
 **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