ADO Lens 0.2.0

CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.2.0 — 2026-10-14
+
+Checking work against what was asked, and where it is.
+
+- `ado_trace` (tool set `trace`): the acceptance criteria (from the parent for a task) and whether they changed after
+  coding started; changesets, commits and pull requests linked to the item and its tasks, with the X++ objects they
+  touch; builds, also those deleted by retention; every release stage of the code's branches with YES / NOT YET, in all
+  projects the code lives in; for Git, whether the change is merged into each mapped branch; tests, tasks, signals.
+- `ado_changes`: files of a changeset, pull request or commit with added / changed / removed X++ methods per object;
+  the diff of one file — AOT XML per method plus the metadata without raw XML noise; other files as unified diffs.
+- Environments per connection: `adolens config --connection <c> --env staging=UAT` maps branches, release definitions or
+  single release stages (`"Definition/Stage=UAT + SCM"`) to environment names; any number of steps, listed in that order.
+- Git flows with a PR per step (feature -> dev, -> staging, -> release branch -> master): a stage has the work when any
+  of its PRs reached it, later changes not there yet are named; a PR and its merge commit are one change; release
+  merges are one line.
+- Skill `po-verify` (`skills/po-verify`): guides Claude through checking a work item for a Product Owner.
+- Server instructions keep only advice the tool descriptions do not give (fewer tokens per session); the tool size
+  check measures the JSON Claude really receives and only guards against accidental growth.
+- Pull requests (tool set `pr`): `ado_pr` (waiting for my review, mine, all active; one PR with votes, checks, work
+  items and the open threads people wrote) and `ado_pr_update` (create, comment on a file and line, reply, resolve,
+  vote, publish, complete, abandon; `@[name]` mentions).
+- Pipelines (tool set `pipelines`): `ado_pipeline` (recent builds; a failed build with its failed steps, errors and the
+  error lines of the log without MSBuild noise) and `ado_pipeline_run`.
+- `ado_settings`: shows the connection and saves the environment map; when the map is missing, `ado_trace` ends with a
+  SETUP note (the flow it found and a first guess) so Claude asks the user once and saves the answer.
+- CLI: `trace`, `changes`, `pr`, `pipeline`.
+
 ## 0.1.0 — 2026-10-14
 
 First release: work items, sprints, boards, backlogs and the wiki for Claude Desktop and Claude Code.

README.md

@@ -13,7 +13,8 @@ not thousands. Changes between versions: [CHANGELOG.md](CHANGELOG.md). The road
 Azure DevOps is a trademark of Microsoft.
 
 > Status: **0.x — in development.** Connections, Claude registration, the local work item structure, work items,
-> sprints, boards, backlogs and the wiki work; tracing work to code, pull requests and pipelines follow the plan.
+> sprints, boards, backlogs, the wiki, tracing work to code and deployments, pull requests and pipelines work; the
+> installer follows the plan.
 
 ## What it does differently
 
@@ -92,8 +93,26 @@ adolens config --add-toolset pipelines       # one more tool set on top of the m
 adolens config --confirm-above 3             # updates of more items are previewed first (0: always)
 adolens config --usage-log false
 adolens config --show-tokens true            # end every answer with [~N tokens]
+adolens config --connection contoso --env staging=UAT --env master=PROD   # what branches mean (for ado_trace)
 ```
 
+**Environments.** Azure DevOps does not know that the branch `staging` means UAT. Map your flow per connection, as many
+steps as it has, in its order — `--env key=label`, `--remove-env key`. A key is a branch (`dev`, `staging`; for TFVC the
+last part of the branch path, e.g. `Main`), a release definition, or one release stage as `"Definition/Stage"` — useful
+when one stage deploys to two environments at once:
+
+```powershell
+adolens config --connection contoso --env dev="DEV (sbx01)" --env staging="UAT (sbx03)" --env master=PROD
+adolens config --connection fabrikam --env "Main-Deploy/Stage 1=UAT + SCM"
+```
+
+`ado_trace` then lists the stages in that order with their labels ("UAT (sbx03): YES") and, for Git, also checks whether
+the work is merged into each mapped branch even when no release pipeline deploys it.
+
+Nobody has to set this up in advance: when the map is missing, `ado_trace` ends with a short SETUP note listing the flow
+it found (branches and release stages, with a first guess such as dev → DEV, staging → UAT, master → PROD). Claude asks
+the user once how they call these environments and saves the answer with `ado_settings` — for good.
+
 Settings live in `%LOCALAPPDATA%\ado-lens\adolens.json` (no secrets) — they can be edited by hand too.
 
 ### Modes and tool sets
@@ -103,12 +122,15 @@ never a permission.
 
 | Tool set | Tools | po | dev | full |
 |---|---|:-:|:-:|:-:|
-| `core` | `ado_status`, `ado_fields` | ✓ | ✓ | ✓ |
+| `core` | `ado_status`, `ado_settings`, `ado_fields` | ✓ | ✓ | ✓ |
 | `work` | `ado_work_item`, `ado_query`, `ado_create`, `ado_update`, `ado_comment`, `ado_link` | ✓ | ✓ | ✓ |
+| `pr` | `ado_pr`, `ado_pr_update` | – | ✓ | ✓ |
+| `pipelines` | `ado_pipeline`, `ado_pipeline_run` | – | ✓ | ✓ |
 | `boards` | `ado_sprint`, `ado_board`, `ado_backlog`, `ado_my_day` | ✓ | – | ✓ |
 | `wiki` | `ado_wiki`, `ado_wiki_write` | ✓ | ✓ | ✓ |
-| `trace`, `test`, `recipes` | planned | ✓ | (trace, recipes) | ✓ |
-| `code`, `pr`, `pipelines` | planned | – | ✓ | ✓ |
+| `trace` | `ado_trace`, `ado_changes` | ✓ | ✓ | ✓ |
+| `test`, `recipes` | planned | ✓ | (recipes) | ✓ |
+| `code` | planned | – | ✓ | ✓ |
 
 ## Tool map
 
@@ -117,6 +139,7 @@ What each MCP tool answers, when Claude should reach for it, and the CLI command
 | Tool | Answers | When | CLI |
 |---|---|---|---|
 | `ado_status` | version, connection, signed-in user, PAT source, metadata age | checking the setup | `adolens status` |
+| `ado_settings` | the connection's settings; with `environments` saves for good what branches and release stages mean, in flow order (`dev=DEV (sbx01); staging=UAT (sbx03); master=PROD`) | `ado_trace` asks for it once (SETUP), the user answers in words | `adolens config --connection c --env dev=DEV` |
 | `ado_fields` | types by backlog level; for a type: states, transitions, fields, required flags, allowed values; for a field: where it is used and its values; structure changes over time | before writing fields or WIQL; "which fields does a Bug have", "what changed in our process this month" | `adolens fields --type Bug`, `adolens fields --field Severity`, `adolens fields --changes 30d` |
 | `ado_work_item` | one or more items: state, people, paths, filled fields, description and acceptance criteria as markdown, parent / children / related, linked changesets, commits, PRs and builds; with `include`: comments, history | "what is #123 about", "who changed the criteria and when" | `adolens item 123 456 --include comments,history --detail summary` |
 | `ado_query` | items found by WIQL (with `@Me`, `@CurrentIteration`…) or a saved query, one line each | lists, filters, "open bugs of the sprint" | `adolens query --wiql "SELECT …"`, `adolens query --query "Shared Queries/Open bugs"` |
@@ -127,6 +150,12 @@ What each MCP tool answers, when Claude should reach for it, and the CLI command
 | `ado_sprint` | a team's sprint (`current`, `next`, `previous` or by name): dates and working day, items by state, estimates, remaining work against the capacity left, items needing attention (no change for days, blocked, no estimate, no criteria, unassigned), task progress per item; says plainly when the sprint has ended | stand-up, sprint review, "will we make it" | `adolens sprint`, `adolens sprint next --team "Demo Team" --detail summary` |
 | `ado_board` | a team's board: columns with WIP limits (over-limit flagged) and their cards; `move` + `column` moves a card — the state follows the column's mapping for the item's type | "what is in progress", moving cards | `adolens board`, `adolens board --move 123 --column "In Progress"` |
 | `ado_backlog` | a team's backlog in priority order (requirement, portfolio, task, or by name); `move` + `above`/`below` reorders | refinement, priorities | `adolens backlog --top 20`, `adolens backlog --move 123 --above 456` |
+| `ado_trace` | was it done as asked, and where is it: the acceptance criteria (from the parent for a task) and whether they changed after coding started; changesets, commits and pull requests linked to the item and its tasks with the X++ objects they touch; builds (also those deleted by retention); every release stage of the code's branches with **YES / NOT YET**, labelled by the environment map (`staging` → UAT); for Git, whether the change is merged into each mapped branch; tests, tasks and warning signals | "did they do what I asked", "is it on UAT yet" | `adolens trace 123` |
+| `ado_changes` | the files of a changeset (`523`), pull request (`PR 482`) or commit (sha + `repo`) with X++ objects and their added / changed / removed methods; `file` gives the diff of one file — for AOT XML per method plus the metadata (fields, controls, properties) without raw XML noise | reading what exactly changed | `adolens changes 523`, `adolens changes 523 --file AxClass/SalesTable_Extension.xml` |
+| `ado_pr` | without id: pull requests waiting for my review and mine (`list=active`: all); with id: status, reviewers and votes, checks (build, work item linking, reviewers), linked work items, open comment threads written by people (not system notes) | code review, "what is blocking my PR" | `adolens pr`, `adolens pr 482` |
+| `ado_pr_update` | `create` (repo, source, target, title, markdown text, work items, reviewers, draft), `comment` (general or on a file and line), `reply`, `resolve`, `vote`, `publish`, `complete`, `abandon`; `@[name]` notifies | reviewing, opening and finishing PRs | — |
+| `ado_pipeline` | recent builds (of a pipeline, a branch); with `build`: the failed stage, job and steps, their errors, and the lines of the log that report errors (MSBuild noise cut) | "why is the build red" | `adolens pipeline`, `adolens pipeline 900` |
+| `ado_pipeline_run` | queues a pipeline by name or id, optionally on a branch, with variables | re-running a build | — |
 | `ado_wiki` | the project wiki: page tree (`depth`), one page as markdown with its version and subpages, or search across the project's wikis with snippets; long pages are cut unless `detail=full` | "how does X work", finding documentation | `adolens wiki`, `adolens wiki "Team/Setup"`, `adolens wiki --search "dual write"` |
 | `ado_wiki_write` | `create` a page, `append` / `prepend` to it, or `replace` it with the version from the last full read — a page changed by someone else in the meantime is never overwritten; optional change comment | release notes, keeping docs current | `adolens wiki-write "Team/Release notes" --file notes.md --mode append` |
 | `ado_my_day` | since the previous working day (or `since`): where you were mentioned (all projects), your items and followed items changed by others, pull requests waiting for your review | the start of the day | `adolens myday --since 3d` |
@@ -158,7 +187,7 @@ Estimates are characters / 4; Claude's tokenizer differs a little (Polish text r
 ## CLI
 
 ```
-adolens item|query|create|update|comment|link|fields|sprint|board|backlog|myday|wiki|wiki-write …
+adolens item|query|create|update|comment|link|fields|sprint|board|backlog|myday|wiki|wiki-write|trace|changes|pr|pipeline …
 adolens login|logout|connections|config|status|register|unregister|refresh|stats|api|mcp|version
 ```
 
@@ -221,6 +250,8 @@ regular expression per line, `!word` for allowed words. Without a list the relea
 | `SetupTests.cs` | settings, connections and PAT order (Credential Manager first), command line, Claude configuration edits, Credential Manager, HTTP retries and errors, tool definition budget per mode |
 | `MetadataTests.cs` | fetching the structure (levels, inherited process name, bugs on the requirement backlog), change history, compact `ado_fields` answers |
 | `BoardTests.cs` | sprint progress, capacity left with days off, attention list, picking sprints, ended sprints, board columns and WIP, moving cards with the state mapping, backlog order and reordering, my day |
+| `PrPipelineTests.cs` | PR lists and details (votes, checks, human threads only), PR actions (vote, comment on a line with a mention, create), failed build errors and log lines, running pipelines by name, saving environments, guessing the flow |
+| `TraceTests.cs` | line diff (Myers, unified hunks), X++ per method with form data sources, object names from AOT paths, `ado_trace` across TFVC and Git (deployed stages YES / NOT YET, environment labels, merged branches, deleted builds, criteria changed after coding), `ado_changes` lists and file diffs |
 | `WikiTests.cs` | page tree, page with version, replace only with the current version (412 never overwrites), append, create over an existing page, search snippets |
 | `WorkItemTests.cs` | work item answers, required fields and allowed values before writing, transitions, preview and confirm of bulk updates, mentions, links, queries, HTML ⇄ markdown, PAT never sent to other hosts |
 
@@ -235,6 +266,10 @@ issues or commits.
 | work item reads, writes, checks | `WorkItems.cs`, `WorkQueries.cs`; output in `WorkItemFormat.cs` |
 | sprints, capacity, boards, backlogs, my day | `Boards.cs` (API in `Boards`, answers in `BoardQueries`) |
 | wiki | `Wiki.cs` |
+| pull requests | `PullRequests.cs` |
+| builds and pipeline runs | `Pipelines.cs` |
+| changesets, commits, PRs, builds, deployments | `Code.cs`; tracing in `Trace.cs`; diffs and X++ per method in `Diff.cs` |
+| skills for Claude | `skills\<name>\SKILL.md` |
 | work item structure (types, fields, states) | `MetadataService.cs` (fetch), `MetaStore.cs` (SQLite; raise `SchemaVersion` to refetch), `Metadata.cs` (change detection) |
 | rich text | `Html.cs` |
 | people | `Identities.cs` |