feat(security): secure-files pipeline download via ViewSecrets elevation

- Add secure-files download for pipeline runs, auto-elevating ViewSecrets
  permission and reverting after download
- Correct Security API token (project UUID) and accessControlLists wrapper
- Support preview api-version and broaden no_scope detection
- Add permanent grant/revoke for ViewSecrets as escape hatch
- Remove secure-files download subcommand (MSA platform gap)
- Add pipelines secure-files tests and security tests
- Ignore docs/superpowers planning/spec docs

Author: gilbertwong96

.gitignore

@@ -43,3 +43,7 @@ node_modules/
 # Node.js test artifacts (root only)
 /package.json
 /package-lock.json
+.pi-subagents/
+
+# Superpowers planning/spec docs (not committed)
+docs/superpowers/

CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.5.0] - 2026-07-22
 
+### Unreleased
+
+- **`ado pipelines secure-files`** — list, show, upload, ~~download~~, and delete
+  Secure Files in the Pipeline Library (`/_apis/distributedtask/securefiles`).
+  Useful for shipping certs, kubeconfigs, and signing keys to pipeline agents
+  via the `DownloadSecureFile@1` task. **The `download` subcommand was
+  removed in this branch** — see "Removed" below.
+
+### Removed
+
+- **`ado pipelines secure-files download` subcommand (this branch only).**
+  Microsoft's secure-files API does not issue a `downloadTicket` field in
+  the metadata response to bearer tokens for personal Microsoft accounts
+  (e.g. `outlook.com` / `hotmail.com` / `live.com`), even with the
+  `vso.securefiles_read` PAT scope and the Library/ViewSecrets permission
+  explicitly granted (verified live with `allow:63 = View|Administer|
+  Create|ViewSecrets|Use|Owner`). The web UI works because it uses
+  session-cookie auth with a different code path. Direct REST does not.
+  Re-introduce this subcommand only when either (a) Microsoft fixes the
+  platform gap, or (b) the caller authenticates with a work/school
+  Entra ID (AAD) identity rather than a personal Microsoft account.
+  The other secure-files subcommands (`list`, `show`, `upload`, `delete`)
+  are unaffected and continue to work for all account types. See
+  `ado skills read ado-cli/references/pipelines.md` for examples.
+
+
+
 ### Added
 
 - **`ado prs reviewers list --search QUERY`** — fuzzy-filter PR reviewers

lib/ado_cli/cli.ex

@@ -97,6 +97,7 @@ defmodule AdoCli.CLI do
       areas: Areas,
       connections: Connections,
       extensions: Extensions,
+      security: Security,
       iterations: Iterations,
       imports: Imports,
       pipelines: Pipelines,

lib/ado_cli/cli/helpers.ex

@@ -13,6 +13,30 @@ defmodule AdoCli.CLI.Helpers do
   import CliMate.CLI
   alias AdoCli.CLI.Output
 
+  @doc """
+  Surfaces an API error to the user and halts with a non-zero exit code.
+
+  Shared by `AdoCli.CLI.Pipelines`, `AdoCli.CLI.WorkItems`, and
+  `AdoCli.CLI.PullRequests`. Previously duplicated in each module.
+  """
+  def bail(reason, parsed) do
+    handle_api_result({:error, reason}, parsed, nil)
+  end
+
+  @doc """
+  Extracts the human-readable `message` field from an Azure DevOps
+  error body. Returns `nil` if the body doesn't have one.
+
+      iex> extract_error_message(%{"message" => "Forbidden"})
+      "Forbidden"
+      iex> extract_error_message(%{"other" => "stuff"})
+      nil
+      iex> extract_error_message("not a map")
+      nil
+  """
+  def extract_error_message(%{"message" => m}) when is_binary(m), do: m
+  def extract_error_message(_), do: nil
+
   @doc """
   Handles a `{:ok, data} | {:error, reason}` result from the API client.