@knowttl/ado-axi 0.0.0-stage → 0.4.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jeffrey Haen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,262 @@
-# Temporary Holding Version
+# ado-axi (Azure DevOps axi)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This is a fork of [jeffreyhaen/ado-axi](https://github.com/jeffreyhaen/ado-axi), maintained at [knowttl/ado-axi](https://github.com/knowttl/ado-axi).
+
+[![npm](https://img.shields.io/npm/v/%40knowttl%2Fado-axi.svg)](https://www.npmjs.com/package/@knowttl/ado-axi)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](package.json)
+
+<p align="center">
+  <img src="assets/ado-axi-header.png" alt="ado-axi for Azure DevOps">
+</p>
+
+Agent-ergonomic CLI for **Azure DevOps** - work items, pull requests, repositories, Git refs, pipelines,
+and a raw REST escape hatch, in token-efficient [TOON](https://toonformat.dev/) output.
+
+`ado-axi` is an Azure DevOps [AXI](https://github.com/kunchenguid/axi) (Agent eXperience Interface): a CLI
+designed for autonomous agents rather than humans. It talks to the Azure DevOps REST API
+directly (no `az` round trips except for token acquisition), supports multiple organizations
+with different authentication through profiles, and answers with minimal schemas plus
+contextual next-step hints.
+
+## Why AXI: CLI vs MCP vs AXI
+
+Across extensive [AXI benchmark studies](https://axi.md/) (over 900 runs), agent-first CLIs achieve **100% task success** at **~50% fewer turns** and **50–66% lower cost** than MCP.
+
+This repository ships the harness behind its own measurements: 19 Azure DevOps scenarios, recorded
+against a private organization and replayed offline with the `o200k_base` tokenizer. The recordings
+stay local — see [`BENCHMARK.md`](BENCHMARK.md) for the method and for how to reproduce these
+numbers against your own organization.
+
+| Interface | Context (Turn 0) | Output | Measured payload | Write Safety | Guidance |
+|---|---|---|---|---|---|
+| **`ado-axi`** | Skill frontmatter always; body loaded on demand (see [recorded surface measurements](BENCHMARK.md#tool-surface-benchmark)) | **TOON** | **-94.5%** vs raw REST JSON (-90.0% mean per scenario) | ✅ **Opt-in writes; idempotent + CAS guards; no policy bypass** | Structured hints (`help[]`) |
+| **Raw CLI** (`az devops`) | ~0 tokens | JSON / ASCII | Baseline (full REST payloads, slow startup) | ❌ Direct mutations | Human text / exit codes |
+| **Azure DevOps MCP** | **16,356 tokens** (40 tool schemas, v2.10.0) | JSON-RPC | Highest overhead (full schemas resent every turn) | Varies | Schema validation errors |
+
+## Install
+
+Install globally (recommended for repeated use):
+
+```sh
+npm install -g @knowttl/ado-axi
+ado-axi --help
+```
+
+For a one-off invocation without installing:
+
+```sh
+npx -y @knowttl/ado-axi --help
+```
+
+## Agent integration
+
+Install the skill globally so an agent loads the usage guide on demand:
+
+```sh
+npx skills add knowttl/ado-axi --skill ado-axi -g
+```
+
+Omit `-g` to install the skill for the current project only.
+
+## Configure
+
+Profiles live in `~/.ado-axi/config.json` (override with `./ado-axi.config.json` or
+`$ADO_AXI_CONFIG`):
+
+Configuration writes require [write enablement](#behavior).
+
+```sh
+ADO_AXI_WRITES=1 ado-axi config init --org acme --project Platform --name acme --auth az
+ADO_AXI_WRITES=1 ado-axi config init --org contoso --project Web --name contoso --auth pat --pat-env ADO_CONTOSO_PAT
+ado-axi doctor
+```
+
+```json
+{
+  "defaultProfile": "acme",
+  "profiles": {
+    "acme": { "org": "acme", "project": "Platform", "auth": "az" },
+    "contoso": { "org": "contoso", "project": "Web", "auth": "pat", "patEnv": "ADO_CONTOSO_PAT" }
+  }
+}
+```
+
+- `org` — the Azure DevOps organization name or organization-root URL (`acme` or `https://dev.azure.com/acme`).
+- `project` — the default project inside that organization. Saves passing `--project` on commands requiring project context.
+- `auth: "az"` — uses the Azure CLI (`az account get-access-token`). Add `"tenant": "<id>"`
+  when the organization lives in another Entra tenant.
+- `auth: "pat"` — reads a personal access token from the env var named in `patEnv`.
+- Any command accepts `--profile <name>`, `--org <org>`, `--project <project>` — before or
+  after the command — and `$ADO_AXI_ORG` / `$ADO_AXI_PROJECT` work too. An org that matches a
+  configured profile inherits that profile's authentication. Organization-root URLs such as
+  `https://dev.azure.com/acme` or `https://acme.visualstudio.com` are normalized to the org name,
+  including in environment variables and profiles; project/API paths in `--org` are rejected.
+- Project context is never guessed. Pass `--project`, set `$ADO_AXI_PROJECT`, or use a
+  project-specific profile. Use `ado-axi project list --org <org>` to discover projects.
+
+## Use
+
+For the mutating examples below, first enable writes as described in [Behavior](#behavior).
+
+```sh
+ado-axi                                   # dashboard: your work items, active project PRs, recent runs
+ado-axi work-item list --assigned-to @me  # open work items
+ado-axi work-item get 4211 --comments
+ado-axi work-item list --fields id,created,System.AssignedTo,Custom.EventSeverity
+ado-axi work-item get 4211 --full
+ado-axi work-item comment 4211 --body "**Status:** ready"
+ado-axi work-item update 4211 --state "In Progress"
+ado-axi work-item update 4211 --add-tags agent-claimed --if-rev 7   # compare-and-swap claim
+ado-axi work-item link add 4211 --pr 812                            # attach the pull request
+ado-axi work-item link list 4211
+ado-axi work-item link types
+ADO_AXI_WRITES=1 ado-axi work-item attach 4211 --file ./evidence.png --comment "Test evidence" --if-rev 7
+ado-axi work-item attachment get 4211 --name evidence.png --out ./download.png
+ado-axi query run "Shared Queries/Open bugs" --limit 10
+ado-axi area list --depth 2
+ado-axi iteration list --depth 2
+ado-axi pr list --reviewer @me
+ado-axi pr comments 812 --full
+ado-axi pr thread list 812
+ado-axi pr thread reply 812 --thread 5 --body "Fixed in 3f2a1c9" --resolve
+ado-axi pr update 812 --draft false --auto-complete true
+ado-axi pr checks 812
+ado-axi pr diff 812 --limit 50
+ado-axi pr reviewer add 812 --reviewer jane@example.com
+ado-axi pr complete 812 --squash --delete-source-branch
+ado-axi pr abandon 812
+ado-axi pr approve 812
+ado-axi repo file /src/Program.cs --repo Web --ref main
+ado-axi ref list --repo Web --limit 50
+ado-axi repo create --name SyntheticRepo
+ado-axi repo update --repo SyntheticRepo --default-branch main
+ado-axi repo policy update 7 --policy-json '{"isEnabled":false}' --if-rev 3
+ado-axi ref create --repo Web --name feature/agent --source main
+ado-axi ref delete --repo Web --name feature/agent --old-object-id <40-hex>
+ado-axi pipeline runs --result failed
+ado-axi pipeline update 42 --definition '{"name":"CI"}' --if-rev 7
+ado-axi pipeline build tag add 98231 --tag verified
+ado-axi pipeline folder list --limit 20
+ado-axi pipeline runs artifact list 98231 --limit 20
+ado-axi pipeline runs artifact download 98231 --name drop --out ./drop.zip
+ado-axi pipeline release list --limit 20
+ado-axi pipeline timeline 98231
+ado-axi pipeline logs 98231 --failed-only --tail 200
+ado-axi pipeline logs 98231 --tail 200
+ado-axi pipeline watch 98231 --interval 10 --timeout 1800
+ado-axi test results 98231                # failing tests of a run, with error messages
+ado-axi api _apis/wiki/wikis               # anything not covered by a command
+cat payload.bin | ado-axi api POST _apis/wit/attachments --query 'fileName=payload.bin' --content-type application/octet-stream
+```
+
+Use `work-item attach` to upload and link a local file, and `work-item attachment get` to download it by name.
+See [attachment usage and recovery](doc/work-item-writes.md#attachments-td-062) for file requirements, size limits, revision guards, output fields, and overwrite behavior.
+
+`work-item list --limit` bounds the WIQL request and displayed items; the count reports only the number shown because WIQL results may not be exhaustive.
+
+See [Boards read commands](doc/boards-reads.md) for relation type discovery, saved queries, area and iteration paths, and their limit and count semantics.
+
+`work-item list --fields` accepts `id,type,title,state,assignee,created,changed` and any field reference name, including `System.*`, `Microsoft.VSTS.*`, and `Custom.*`.
+Unknown aliases and API-rejected reference names produce errors.
+`work-item get --full` includes the complete description plus every non-System field, keyed by reference name under `fields`; extra text fields are limited to 1200 characters with a truncation marker.
+
+## Behavior
+
+- **Idempotent mutations.** `work-item update`, `pr update`, reviewer changes, `pr thread resolve`,
+  `pr complete`, `pr abandon`, `work-item link add`, and `ref create|delete` report an already
+  applied request as a no-op and exit 0.
+- **Compare-and-swap.** `--if-rev <n>` on `work-item update|link add` fails instead of overwriting a
+  concurrently changed item. Calculated `--add-tags`/`--remove-tags` changes automatically test the
+  revision read before merging, even without `--if-rev`; conflicts fail without retrying.
+  `ref delete` sends the branch's current object ID as its guard.
+- **Work-item deletion and link removal (TD-068, TD-063).** See [work-item writes](https://github.com/knowttl/ado-axi/blob/main/doc/work-item-writes.md) for commands, revision guards, permanent destruction confirmation, and the DELETE race window.
+- **Pipeline administration (TD-065).** Definition create/update/delete, build and run tags, cancellation, and folder administration are available.
+  See [pipeline administration](https://github.com/knowttl/ado-axi/blob/main/doc/pipeline-admin.md) for JSON definitions, revision guards, delete confirmations, and bounded folder reads.
+- **Artifacts and releases (TD-065 slice 2 of 4).** List run artifacts, download a named ZIP to explicit `--out`, and list/show/create Classic releases.
+  Downloads cap at 100 MiB, report byte counts, and never overwrite without `--force`.
+  Artifact reads/downloads and release list/show work with writes disabled; release create requires `ADO_AXI_WRITES=1`.
+  See [artifacts and releases](https://github.com/knowttl/ado-axi/blob/main/doc/artifacts-releases.md) for commands, deployment behavior, and the artifact upload limitation.
+- **Repository and policy administration (TD-065 slice 3 of 4).** Repository create/update/delete/import and policy create/update/delete use the same default-off write boundary.
+  See [repository administration](https://github.com/knowttl/ado-axi/blob/main/doc/repository-admin.md) for JSON policy settings, revision behavior, import authentication, and concurrency limits.
+- **BREAKING CHANGE: writes default off.** Set `ADO_AXI_WRITES=1` to enable work-item, PR, pipeline, repository, and policy mutations, `ref create|delete`, and `config init|add`.
+  Without that exact value, the CLI refuses these commands before any request or local write with code `WRITES_DISABLED` and an enablement hint.
+  Raw `api` requests also require enablement for methods other than GET, HEAD, and OPTIONS, including implicit POST from a body or piped stdin.
+  Native read commands, including WIQL queries, and help remain available without enablement.
+- **Missing flag values fail.** Value-taking flags such as `--if-rev`, `--old-object-id`, and context
+  selectors require a value; a bare flag is a usage error (exit 2), not an omitted guard or selector.
+- **Policy is never bypassed.** `pr complete` sends the current source commit and separates
+  completed, queued, conflict, policy-blocked, and failed outcomes — run `pr checks` first.
+- **Failure triage in one call.** `pipeline timeline` names the failing stage/job/step with its
+  error issue and log id, `pipeline logs --failed-only` opens that log, and `test results`
+  summarizes test totals and failing tests with their error messages.
+- **Bounded output.** Lists take `--limit`/`--fields`, detail views truncate with a `--full` escape
+  hatch, and `repo file` refuses folders and binaries.
+- **ADO REST URLs.** `api` accepts relative paths or full HTTPS REST URLs on `dev.azure.com`, `vsrm.dev.azure.com`, `vssps.dev.azure.com`, `almsearch.dev.azure.com`, and `vsaex.dev.azure.com`.
+  For relative paths, `--host` accepts `dev` (default), `vsrm`, `vssps`, `almsearch`, or `vsaex`.
+  Full URLs supply org/project/host/query, select matching profile authentication, and do not inherit default project context.
+  Conflicting flags or profiles from another org fail locally; credentials, custom ports, fragments, dot segments, and duplicate query keys in URLs are rejected.
+- **Piped input.** `api` sends piped stdin as the raw request body when `--body` is omitted;
+  work-item and PR descriptions plus every comment command read stdin when their content flag is omitted.
+  For Markdown or multiline comments, use a quoted heredoc — never `--body "..."` with backticks,
+  `$`, `!`, or quotes. See [safe shell-input guidance](SKILL.md#safe-shell-input).
+- **Markdown comments.** Work item comments use Markdown by default; pass `--format html` only for raw HTML.
+- **Exit codes.** 0 success (including no-ops), 1 runtime error, 2 usage error. `pipeline watch`
+  exits non-zero on failed, cancelled, timed-out, and unexpected runs (poll interval and timeout in
+  seconds, 10s/1800s by default). It stops when the configured timeout is reached.
+
+Every command takes `--help` and answers with a concise reference; that is where per-command
+detail lives, alongside the agent-facing guide in [SKILL.md](SKILL.md).
+
+### Read-only audit evidence (TD-064)
+
+Audit reads cover repository policies, security groups and permissions, service endpoints, variable groups, pipeline variables and definitions, agents, pools, queues, users, teams, projects, and repositories.
+Lists use TOON, default to `--limit 100`, and report both the total and how many records were omitted.
+`--full` expands fields without lifting collection limits or revealing secret variables, service connection credentials, or agent capabilities.
+
+```sh
+ado-axi repo policy list --repo <repository-id> --limit 10
+ado-axi security group list
+ado-axi service-endpoint show <endpoint-id> --full
+ado-axi pipeline variable-group list --limit 10
+ado-axi pipeline variable list --pipeline <definition-id>
+ado-axi pipeline agent list --pool <pool-id>
+ado-axi user list --limit 10
+ado-axi team member list --team <team-id>
+ado-axi project show
+ado-axi repo show <repository-id>
+```
+
+See [audit command reference](docs/AUDIT_READS.md) for every list/show command, required selectors, pagination, and masking rules.
+
+## Design
+
+Built against the ten AXI principles: TOON output, 3-4 field default schemas, truncation with
+`--full`, pre-computed aggregates (review tallies, run failure counts, totals), definitive
+empty states, structured errors on stdout with exit code 2 for usage errors, a content-first
+no-argument dashboard, contextual next-step hints, and concise per-command help.
+
+## Development
+
+```sh
+pnpm install
+pnpm run build
+pnpm test
+```
+
+### Releasing
+
+The `.github/workflows/release-please.yml` workflow manages release pull requests from conventional commits on `main`.
+Merging a release pull request creates the tag and GitHub release, then builds and tests that tag before publishing the packed tarball to npm using OIDC trusted publishing with provenance.
+GitHub Actions checks run only for release publication; run the development checks locally for other changes.
+
+## License
+
+MIT
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## See also
+
+- [AXI — agent eXperience interface](https://axi.md/) · [kunchenguid/axi](https://github.com/kunchenguid/axi)
+- [TOON — token-optimized object notation](https://toonformat.dev/) · [toonformat/toon](https://github.com/toonformat/toon)

package/SKILL.md

@@ -0,0 +1,334 @@
+---
+name: ado-axi
+description: Use ado-axi to work with Azure DevOps — work items, pull requests, pipelines, repositories, and raw REST calls — through token-efficient TOON output. Use when the task involves Azure DevOps, ADO, boards, work items, WIQL, pull requests, code reviews, build pipelines, or Azure Repos.
+user-invocable: false
+---
+
+# ado-axi
+
+Agent-ergonomic CLI over the Azure DevOps REST API. Multiple organizations are handled with
+profiles; each profile carries its own org, project, and authentication (Azure CLI login or a
+personal access token).
+
+Install globally for normal use with `npm install -g @knowttl/ado-axi`. If `ado-axi` is not on PATH, prefix commands with `npx -y @knowttl/ado-axi`.
+
+Before running mutations, follow [write enablement](README.md#behavior).
+
+## Orientation
+
+Run `ado-axi` with no arguments first. It prints the active profile plus your open work items,
+project-active pull requests (`active-pull-requests`), and recent pipeline runs.
+
+```sh
+ado-axi                      # dashboard
+ado-axi config list          # configured profiles
+ado-axi doctor               # authentication check per profile
+ado-axi project list         # projects (30 most recently updated; --name <filter>, --limit N)
+```
+
+## Selecting org, project, and profile
+
+Every command accepts these, and they never count as unknown flags:
+
+- `--profile <name>` — a configured profile (`ado-axi config list`); may also be written
+  *before* the command (`ado-axi --profile acme pr list`), including on the bare dashboard
+- `--org <org>` / `--project <project>` — one-off overrides; an `--org` that matches a
+  configured profile inherits that profile's authentication. Organization-root URLs
+  (`https://dev.azure.com/<org>` or `https://<org>.visualstudio.com`) also work; no project/API path
+- `$ADO_AXI_ORG` / `$ADO_AXI_PROJECT` — environment overrides
+
+For pasted PR web URLs, extract org, project, repo, and id and pass them explicitly.
+Establish org/project from the task or a project-specific profile and reuse them for the session.
+If project context is missing, use `ado-axi project list --org <org>`; ask the user if the intended
+project remains unclear. Never select a project arbitrarily, especially for mutations.
+
+## Read-only audit evidence (TD-064)
+
+Use these GET-only commands for bounded TOON audit evidence.
+Lists default to `--limit 100`, report `count` and `omitted`, and accept `--fields a,b`.
+`--full` expands fields while preserving list limits and masking.
+
+```sh
+ado-axi repo policy list --repo <repository-id> [--branch <branch>]
+ado-axi repo policy show <policy-id>
+ado-axi security group list [--scope <descriptor>]
+ado-axi security group show <descriptor>
+ado-axi security membership list <descriptor> [--direction up|down]
+ado-axi security permission list --namespace <namespace-id> [--token <resource-token>] [--subject <descriptor>]
+ado-axi security permission show --namespace <namespace-id> --token <resource-token> [--subject <descriptor>]
+ado-axi service-endpoint list
+ado-axi service-endpoint show <endpoint-id> --full
+ado-axi pipeline variable-group list
+ado-axi pipeline variable-group show <group-id> --full
+ado-axi pipeline variable list --pipeline <definition-id>
+ado-axi pipeline show <definition-id> --full
+ado-axi pipeline agent list --pool <pool-id>
+ado-axi pipeline agent show <agent-id> --pool <pool-id>
+ado-axi pipeline pool list
+ado-axi pipeline pool show <pool-id>
+ado-axi pipeline queue list
+ado-axi pipeline queue show <queue-id>
+ado-axi user list
+ado-axi user show <entitlement-id>
+ado-axi team list
+ado-axi team member list --team <team-id>
+ado-axi project show [<project-name-or-id>]
+ado-axi repo show <repository-name-or-id>
+```
+
+`variable-group`, `agent`, `pool`, and `queue` also work as top-level commands.
+`security group membership list` aliases `security membership list`; `team list-member` aliases `team member list`.
+Secret variable values show `***` even under `--full` or `--fields value`.
+Service endpoint authorization, data, and URLs are withheld because they may embed credentials.
+Agent capabilities and API error details are withheld for the same reason.
+Lists count all server pages before returning, so small display limits can still require multiple GET requests.
+See [audit command reference](docs/AUDIT_READS.md).
+
+## Work items
+
+```sh
+ado-axi work-item list [--state open|all|<State>] [--type <type>] [--assigned-to @me|<name>]
+                       [--iteration @current|<path>] [--area <path>] [--tag <tag>] [--search <text>]
+                       [--query "<raw WIQL>"] [--limit 30]
+ado-axi work-item get <id> [--comments] [--full]       # includes `rev` for compare-and-swap
+ado-axi work-item create --type Task --title "..." [--description "..."] [--description-format markdown|html]
+                         [--assigned-to <user>] [--parent <id>] [--area <path>] [--iteration <path>] [--tags "a; b"]
+ado-axi work-item update <id> [--state <state>] [--title "..."] [--assigned-to <user>]
+                              [--description "..."] [--description-format markdown|html]
+                              [--add-tags a,b] [--remove-tags c] [--if-rev <n>]
+                              [--set '{"Microsoft.VSTS.Common.Priority": 1}']
+ado-axi work-item comment <id> [--body "..."] [--format markdown|html]
+ado-axi work-item delete <id> --if-rev <n> [--destroy --confirm-destroy]
+ado-axi work-item link list <id> [--limit 50]
+ado-axi work-item link remove <id> --index <n> --if-rev <n>
+ado-axi work-item link types [--limit 50] [--full]
+ado-axi work-item attach <id> --file <path> [--comment "..."] [--if-rev <n>]
+ado-axi work-item attachment get <id> --name <file> [--out <path>] [--force]
+ado-axi query run <id|path> [--limit 30] [--fields id,title,state]
+ado-axi area list [--depth 10] [--limit 50] [--full]
+ado-axi iteration list [--depth 10] [--limit 50] [--full]
+ado-axi work-item link add <id> (--parent <id> | --child <id> | --related <id> | --pr <id>
+                                 | --commit <40-hex> --repo <name> | --branch <name> --repo <name>)
+                                [--comment "..."] [--if-rev <n>]
+```
+
+See [attachment usage and recovery](https://github.com/knowttl/ado-axi/blob/main/doc/work-item-writes.md#attachments-td-062) for file requirements, size limits, revision guards, recovery, and download behavior.
+
+`link list` resolves hierarchy links to work item ids and artifact links to pull request ids,
+short commit SHAs, and branch names. `link add` builds the `vstfs://` artifact URI for you — pass
+the pull request id, not a URL — and treats an already-present link as a no-op.
+
+See [work-item writes](https://github.com/knowttl/ado-axi/blob/main/doc/work-item-writes.md) for `delete` and `link remove` examples, revision guards, permanent destruction confirmation, and the DELETE race window.
+
+`list` builds WIQL for you; drop to `--query` for anything the flags do not express.
+`--description-format markdown` renders a Markdown description; use `html` only when supplying HTML. The format is only applied when a description is supplied.
+See [README usage](README.md#use) for work-item list counts, field selection, and full-detail output limits.
+
+See [Boards read commands](doc/boards-reads.md) for saved query selectors, historical results, tree depth, and limit and count semantics.
+
+`work-item comment` stores comments as Markdown by default; use `--format html` only when supplying raw HTML. The comments API requires `7.1-preview.4` or later for this format selection.
+`update` is idempotent — setting a field to its current value reports a no-op and exits 0.
+
+### Safe concurrent updates
+
+`--if-rev <n>` turns an update into a compare-and-swap: the patch carries a JSON-Patch
+`{"op":"test","path":"/rev"}`, so the write either applies to exactly that revision or fails with
+`PRECONDITION_FAILED` — never a silent double-claim. Read `rev` from `work-item get`.
+`--if-rev` also disables the idempotent no-op skip, so the intended fields are always written.
+
+`--add-tags` / `--remove-tags` mutate the tag list in place (case-insensitive, deduplicated)
+instead of replacing `System.Tags`, so unrelated tags survive. They cannot be combined with
+`--tags`, which replaces the whole string.
+
+```sh
+ado-axi work-item get 4211                  # read `rev` from the output
+ado-axi work-item update 4211 --assigned-to me@corp.com --add-tags agent-claimed --if-rev 7
+```
+
+## Pull requests
+
+```sh
+ado-axi pr list [--repo <repo>] [--status active|draft|completed|abandoned|all] [--creator @me]
+                [--reviewer @me] [--target <branch>] [--limit 30]
+ado-axi pr get <id> [--threads] [--full]   # --full = complete description AND comment text
+ado-axi pr comments <id> [--full]          # alias for `pr get <id> --threads`
+ado-axi pr create --repo <repo> --source <branch> [--target main] --title "..." [--description "..."]
+                  [--reviewers a,b] [--draft] [--work-items 1,2]
+ado-axi pr update <id> [--title "..."] [--description "..."] [--draft true|false]
+                       [--auto-complete true|false]
+ado-axi pr complete <id> [--squash true|false] [--delete-source-branch true|false]
+ado-axi pr abandon <id>
+ado-axi pr checks <id> [--limit 10] [--full]
+ado-axi pr diff <id> [--limit 20] [--full]
+ado-axi pr reviewer list <id>
+ado-axi pr reviewer add|remove <id> --reviewer <identity> [--required]
+ado-axi pr approve <id> [--vote approve|approve-with-suggestions|wait-for-author|reject|reset]
+ado-axi pr comment <id> [--body "..."] [--file <path> --line <n>] [--thread <id>]
+ado-axi pr thread list <id> [--limit 20] [--full]
+ado-axi pr thread reply <id> --thread <n> [--body "..."] [--resolve]
+ado-axi pr thread resolve|reopen <id> --thread <n> [--status active|fixed|wont-fix|closed|by-design|pending]
+```
+
+Finish review feedback with `pr thread`: `list` gives thread ids plus an `unresolved` count,
+`reply --resolve` answers and closes a thread in one call, and `resolve`/`reopen` report an
+already-set status as a no-op.
+
+### Safe shell input
+
+For Markdown or multiline comment content, pipe a quoted heredoc to stdin for
+`work-item comment`, `pr comment`, and `pr thread reply`; omit `--body`:
+
+```sh
+ado-axi pr thread reply 812 --thread 5 --resolve <<'EOF'
+Fixed in `3f2a1c9`: `$value` is now validated.
+EOF
+```
+
+Never double-quote a flag value containing backticks, `$`, `!`, or quotes. Git Bash expands these
+before `ado-axi` starts, so the CLI receives valid but mangled input and cannot detect it. The
+same applies to `--title`, `--description`, `--set`, `--variables`, `--parameters`, and `--query`:
+use stdin where the command supports it, or pipe a complete JSON payload to `ado-axi api`.
+
+`pr list` shows a review tally (`2/3 approved`) so no follow-up call is needed to judge status.
+Work-item and PR descriptions may be piped when `--description` is omitted. `pr update` and reviewer
+mutations report safely detected retries as no-ops. `pr complete` uses the current source commit, never bypasses policy, and treats
+an already completed PR as a no-op. `pr abandon` treats an already abandoned PR as a no-op. Run `pr checks` before completion to see concise policy/status
+counts; use `--full` only when the bounded actionable list is insufficient.
+
+### Git Bash repository paths
+
+On Windows, Git Bash converts repository paths beginning with `/` even when quoted. Prefix inline
+comment commands with `MSYS_NO_PATHCONV=1` so `--file` reaches Azure DevOps unchanged.
+
+Example:
+```sh
+MSYS_NO_PATHCONV=1 ado-axi pr comment 812 --file '/src/Project/File.cs' --line 10 --body '...'
+```
+
+Without the prefix, the CLI restores paths converted by Git for Windows. It rejects other Windows
+paths, and paths under `/bin` or `/usr/bin`, before creating a thread.
+
+## Pipelines
+
+```sh
+ado-axi pipeline list [--name <filter>]
+ado-axi pipeline create --definition '<BuildDefinition JSON object>'
+ado-axi pipeline update <id> --definition '<changed fields JSON object>' [--if-rev <n>]
+ado-axi pipeline delete <id> --if-rev <n> --confirm-delete
+ado-axi pipeline build tag add|remove <run-id> --tag <tag>
+ado-axi pipeline runs tag add|remove <run-id> --tag <tag>
+ado-axi pipeline build cancel <run-id>
+ado-axi pipeline folder list [--path <folder>] [--limit 100] [--full]
+ado-axi pipeline folder create --path '<absolute-folder>'
+ado-axi pipeline folder delete --path '<absolute-folder>' --confirm-delete
+ado-axi pipeline runs artifact list <run-id> [--limit 100] [--full]
+ado-axi pipeline runs artifact download <run-id> --name <name> --out <path> [--force]
+ado-axi pipeline release list [--definition <id>] [--limit 100] [--full]
+ado-axi pipeline release show <id> [--limit 100] [--full]
+ado-axi pipeline release create --definition <id> [--description <text>] [--draft true|false] [--artifacts '<JSON array>']
+ado-axi pipeline runs [--pipeline <id>] [--branch <branch>] [--result failed] [--limit 20]
+ado-axi pipeline run --pipeline <id> [--branch <branch>] [--variables '{"k":"v"}']
+ado-axi pipeline logs <run-id> [--log <log-id>] [--tail 120] [--full] [--failed-only]
+ado-axi pipeline timeline <run-id> [--limit 20] [--full]
+ado-axi pipeline watch <run-id> [--interval 10] [--timeout 1800]
+```
+
+See [pipeline administration](https://github.com/knowttl/ado-axi/blob/main/doc/pipeline-admin.md) for JSON definition requirements, revision guards, delete safety, tag aliases, folder limits, and examples (TD-065).
+
+Artifact list/download and Classic release list/show stay read-only remotely and work with writes disabled.
+Artifact download requires a user-selected `--out` file, caps at 100 MiB, reports bytes, and never overwrites without `--force`.
+Lists stay bounded under `--full`; release detail masks secret variables and URLs.
+Release create requires `ADO_AXI_WRITES=1` and may trigger deployments unless `--draft true` is selected.
+Optional `--artifacts` selects release artifact versions, for example `[{"alias":"_CI","instanceReference":{"id":"42"}}]`.
+Artifact upload is omitted because the Build Artifacts create API registers existing resources rather than accepting local file bytes.
+See [artifacts and releases](https://github.com/knowttl/ado-axi/blob/main/doc/artifacts-releases.md) for TD-065 slice 2 of 4.
+
+`watch` uses seconds, refuses intervals below 2 seconds, and enforces its deadline across
+authentication, HTTP requests, and response bodies (30 minutes by default). Failed, cancelled,
+timed-out, and unexpected outcomes exit non-zero with TOON output.
+
+`logs` returns the tail of the last log by default — pass `--log <id>` for a specific step.
+
+When a run failed, start with `timeline`: it names the failing stage/job/step, includes the first
+error issue, and gives the log id to read. `logs --failed-only` goes straight to that step's log.
+
+## Tests
+
+```sh
+ado-axi test results <run-id> [--outcome failed|passed|aborted|not-executed|all] [--limit 20] [--full]
+ado-axi test results --run <test-run-id>
+```
+
+`<run-id>` is the pipeline run id. All pages of published test runs contribute to totals;
+result counts match `--outcome`. `--limit` bounds displayed results, not totals. `--full` expands
+error messages without increasing that limit. When a build is red, `test results` usually answers
+*what* broke and `pipeline logs --failed-only` *why*.
+
+## Repositories
+
+```sh
+ado-axi repo list [--name <filter>]
+ado-axi repo branches --repo <name> [--name <filter>]
+ado-axi repo file <path> --repo <name> [--ref <branch> | --commit <40-hex>] [--limit <lines>] [--full]
+ado-axi ref list --repo <name> [--name <prefix>] [--limit 50] [--full]
+ado-axi ref create --repo <name> --name <branch> (--source <branch> | --source-object-id <40-hex>)
+ado-axi ref delete --repo <name> --name <branch> [--old-object-id <40-hex>]
+ado-axi repo create --name <name>
+ado-axi repo update --repo <id|name> [--name <name>] [--default-branch <branch>] [--disabled true|false]
+ado-axi repo delete --repo <id|name> --confirm-delete
+ado-axi repo import --repo <id|name> --source-url <https-git-url> [--service-endpoint <id>]
+ado-axi repo policy create --policy-json '<JSON object>'
+ado-axi repo policy update <id> --policy-json '<changed fields JSON object>' [--if-rev <n>]
+ado-axi repo policy delete <id> --if-rev <n> --confirm-delete
+```
+
+See [repository administration](https://github.com/knowttl/ado-axi/blob/main/doc/repository-admin.md) for write enablement, profile selection, policy JSON, import authentication, output masking, and concurrency limits.
+
+`repo file` reads a single file straight from Azure DevOps: the default branch, a branch tip
+(`--ref`), or an exact revision (`--commit`). Use it for files outside the working copy — another
+repository, or the target-branch version of a file under review. Folders and binaries are refused,
+and paths follow the same `/src/Project/File.cs` form as `pr comment --file`.
+
+Ref creation never overwrites an existing branch. Deletion resolves the exact branch and uses its
+current object ID as the Azure DevOps concurrency guard; `--old-object-id` additionally asserts a
+previously observed version. Existing-at-the-intended-object and already-absent requests are no-ops.
+
+## Escape hatch
+
+Anything without a dedicated command, such as wikis, test plans, or code search, goes through the raw REST bridge:
+
+```sh
+ado-axi api _apis/wiki/wikis
+ado-axi api _apis/testplan/plans --query 'filterActivePlans=true'
+ado-axi api POST _apis/search/codesearchresults --host almsearch --body '{"searchText":"TODO"}'
+cat payload.bin | ado-axi api POST _apis/wit/attachments --query 'fileName=payload.bin' --content-type application/octet-stream
+ado-axi api _apis/projects --no-project           # organization-level path
+ado-axi api 'https://vsrm.dev.azure.com/acme/Platform/_apis/release/releases?api-version=7.1'
+ado-axi api PATCH _apis/wit/workitems/4211 --content-type json-patch \
+  --body '[{"op":"test","path":"/rev","value":7},{"op":"add","path":"/fields/System.State","value":"Active"}]'
+```
+
+Relative paths use `https://dev.azure.com/<org>/<project>/`.
+See [README behavior](README.md#behavior) for supported REST hosts and `--host` values.
+Full HTTPS REST URLs supply org/project/host/query, replace default context, and use matching profile authentication.
+Conflicting flags or a `--profile` from another org are rejected; do not override URL context.
+Quote URLs with query parameters. When `--body` is omitted and stdin is piped,
+stdin is sent unchanged as the request body. `--content-type` accepts the shorthands
+`json` (default), `json-patch`, `merge-patch`, `text`, or any media type — work item writes
+require `json-patch`. Use `--raw` for endpoints that return plain text, such as build logs.
+
+## Conventions
+
+- In ADO descriptions/comments, `#123` references a work item, `!123` an Azure DevOps PR;
+  for GitHub PRs use the full URL, never bare `#123` or `!123`, even when Boards/pipelines run in ADO.
+- Output is TOON on stdout; errors are TOON too, with a `help` list of next steps.
+- Exit codes: 0 success (including no-ops), 1 runtime error, 2 usage error.
+- Unknown flags are rejected by name — read the `help` line and retry once.
+- Lists take `--limit` and `--fields a,b`; detail views truncate and take `--full`.
+- On Windows/Git Bash, never pass large or multiline content through a `.cmd` shim as an
+  interpolated CLI argument such as `--description "$(cat file)"`; `cmd.exe` can truncate it.
+  Pipe it instead: `cat file | ado-axi work-item update <id>` or
+  `cat file | ado-axi api POST <path> --content-type <media-type>`.
+- Mutating commands (`create`, `update`, `complete`, reviewer add/remove, ref create/delete,
+  `comment`, `approve`, `pipeline run`) change real state — only run them when the user asked.
+- Never use PR completion to bypass policy and never delete a ref whose exact target is ambiguous.

package/dist/bin/ado-axi.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=ado-axi.d.ts.map

package/dist/bin/ado-axi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ado-axi.d.ts","sourceRoot":"","sources":["../../src/bin/ado-axi.ts"],"names":[],"mappings":""}