@amsterdamdatalabs/enact-extensions 0.1.37 → 0.1.47

package/extensions/enact-factory/skills/azdo-ci-strategy/SKILL.md

@@ -1,309 +0,0 @@
----
-name: azdo-ci-strategy
-description: >-
-  Azure DevOps CI/CD for enact-os: the branch / PR / release strategy plus the
-  az CLI + REST commands to run it. Use when opening or promoting PRs (to
-  integration or main), setting branch policies (merge-strategy,
-  build-validation), registering pipelines, diagnosing why a pipeline did not
-  trigger, or reading build failures. Triggers on "PR to integration", "promote
-  to main", "pipeline failing", "branch policy", "az repos", "az pipelines".
-compatibility: >-
-  Requires the az CLI (>= 2.30) with the azure-devops extension, an
-  authenticated `az login`, and network access to an Azure DevOps organization.
-metadata:
-  author: Amsterdam Data Labs
-  version: 1.0.0
----
-
-# Azure DevOps CI/CD Strategy — enact-os
-
-> **Storage is GLOBAL — never write to a repo-local `.enact` dir.** Resolve the project's global dir:
-> 1. `ROOT="$(git rev-parse --show-toplevel)"`
-> 2. In `~/.enact/workspaces.json` → `workspaces`, find the entry whose `.root` == `$ROOT`; its object key is `<name>-<id>`.
-> 3. Factory planning artifacts go under `~/.enact/factory/projects/<key>/…`; this skill itself does not define durable markdown artifacts.
-
-The enact-os branch / release strategy and pipeline conventions. The `az` CLI
-and REST command catalogs live in `references/` (see [Reference files](#reference-files))
-and load on demand — this file holds the strategy and the everyday workflow.
-
-> **Relationship to the `enact-factory` MCP server.** This is a standalone
-> knowledge skill — it needs only the `az` CLI, no MCP server. When the
-> `enact-factory` MCP *is* available, prefer its tools (`factory_workitem_*`,
-> pipeline governance) for **live board/WorkItem/pipeline state**; use the
-> CLI/REST recipes here for **branch & merge policies, PR creation/promotion,
-> and build-failure diagnosis** — the operations the MCP doesn't cover, or for
-> when it isn't connected. See the sibling `workitem-triage` skill for the
-> read-only WorkItem triage surface.
-
-## Branch flow
-
-```text
-feat/* local CI ──► PR to integration ── PR CI ──► auto-merge to integration
-fix/*  local CI ──► PR to integration ── PR CI ──► auto-merge to integration
-integration ── automation creates or updates one PR to main ──► main
-main ── manual approval + CI ──► publish
-```
-
-- Branch from `integration` (never from `main`). One branch per logical unit,
-  kebab-case. Never commit directly to `integration` or `main`.
-- **Create a fresh branch only when no open PR to `integration` is left
-  outstanding** for your prior work — let that PR merge (or close it) first. Keep
-  one open `integration` PR at a time so the branch → PR → merge cycle stays
-  serialized and you never stack new work on a base that's still moving. Check
-  before branching:
-
-  ```bash
-  az repos pr list --target-branch integration --status active \
-    --creator "$(az account show --query user.name -o tsv)" -o table
-  ```
-- `feat/*` — new functionality, tooling, or docs. `fix/*` — bug/CI/config fixes.
-
-## Setup
-
-```bash
-az extension add --name azure-devops   # az cli 2.30+
-az login
-```
-
-For any command surface not spelled out in the references, run `az <group>
---help` — e.g. `az repos pr --help`, `az pipelines --help`, `az devops --help`.
-The references document only the non-obvious flags, gotchas, and the REST calls
-the CLI can't make; the CLI's own help covers the rest.
-
-## Variables
-
-Every command and URL in this skill (including the reference files) references
-these. Set them once per shell (or pass `--detect` inside a repo to infer
-org/project from the git remote). Nothing here is tied to one tenant —
-substitute your own org/project:
-
-```bash
-ORG_URL="https://dev.azure.com/<your-org>"            # e.g. .../amsterdamdatalabs
-PROJECT="<your-project>"                               # e.g. Enact
-AZDO_RESOURCE="499b84ac-1321-427f-aa17-267ca6975798"  # constant AAD app id for AzDO access tokens
-
-# Optional: set CLI defaults so --org/--project can be omitted on every command.
-az devops configure --defaults organization="$ORG_URL" project="$PROJECT"
-```
-
-## Developer workflow
-
-0. Before starting any task: confirm you have no open `integration` PR left from
-   prior work, then sync local `integration` and branch from it:
-
-   ```bash
-   # Gate: must return nothing before you branch (let any prior PR merge/close first)
-   az repos pr list --target-branch integration --status active \
-     --creator "$(az account show --query user.name -o tsv)" -o table
-
-   git checkout integration
-   git pull --ff-only origin integration
-   git checkout -b feat/my-branch   # or fix/my-branch
-   ```
-
-1. Work on a `feat/*` or `fix/*` branch.
-2. Run local Docker CI before opening a PR. Each package has a wrapper at
-   `./scripts/ci-local-<package>.sh` (run from the `enact-os` workspace root):
-
-   - `ci-local-agent.sh` · `ci-local-context.sh` · `ci-local-eval.sh`
-   - `ci-local-factory.sh` · `ci-local-gateway.sh` · `ci-local-observe.sh`
-   - `ci-local-operator.sh` · `ci-local-proc-tap.sh` · `ci-local-runtime.sh`
-   - `ci-local-voice.sh` · `ci-local-watchdog.sh` · `ci-local-wiki.sh`
-
-   (Verify the exact set with `ls scripts/ci-local-*.sh` — it grows as packages
-   are added.) For `enact-factory` and `enact-wiki`, the Docker wrapper is the
-   source of truth for Azure parity; direct host-local Vitest can differ because
-   of optional native bindings on non-Linux machines.
-
-3. Open a PR targeting **`integration`** only — never directly to `main`. Always
-   pass **both** `--auto-complete true` and `--delete-source-branch true` (these
-   are NOT inherited by CLI-created PRs — see the auto-complete gotcha in
-   `references/cli-reference.md`):
-
-   ```bash
-   az repos pr create \
-     --source-branch feat/my-branch \
-     --target-branch integration \
-     --title "feat: description" \
-     --squash true \
-     --auto-complete true \
-     --delete-source-branch true \
-     --detect
-   ```
-
-   **Merge strategy is policy-gated.** `integration` requires the **squash**
-   strategy — without `--squash true`, completion fails with
-   `Merge strategy is not allowed by policy`. Note `pr create` may still create
-   the PR while rejecting the auto-complete settings; in that case set them on
-   the existing PR (idempotent):
-
-   ```bash
-   az repos pr update --id <pr-id> --squash true --auto-complete true --delete-source-branch true
-   ```
-
-4. CI runs automatically on the PR. When CI passes the PR **auto-merges** (squash)
-   into `integration`. No reviewer is required on integration.
-5. After each successful merge to `integration`, automation creates or updates
-   one open `integration → main` PR.
-6. The `integration → main` PR stays **manual** — owner approval on it is the
-   release gate. (Create/update commands: `references/cli-reference.md`.)
-
-## CI triggers
-
-| Trigger                                     | What runs                                                                                       |
-| ------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| Push to `feat/*`                            | **Nothing** — local Docker CI is the gate                                                       |
-| Push to `fix/*`                             | **Nothing** — local Docker CI is the gate                                                       |
-| PR opened / updated targeting `integration` | Build + test + lint (no version bump — see Version management)                                   |
-| Push to `integration` (after PR merged)     | Build + test + lint + **patch version auto-bump** (pushed directly to `integration`, `***NO_CI***`) |
-| Push to `main` (after PR merged)            | Build + test + lint + **Publish** for publishable packages; CI only for internal-only packages |
-
-> **⛔ NEVER use `az pipelines run` to manually trigger CI as a substitute for a
-> PR push.** Manual runs do not update PR build status and give false
-> confidence. If CI is not triggering on a PR, push a new commit (even empty):
->
-> ```bash
-> git commit --allow-empty -m "ci: re-trigger pipeline"
-> git push
-> ```
->
-> The only permitted use of `az pipelines run` is a deliberate Publish-stage
-> retag/hotfix on `main`, performed explicitly by the repo owner.
-
-## Publish gate
-
-- Publish only runs on `refs/heads/main`.
-- `main` is branch-protected — direct push blocked; only PR merges allowed.
-- Internal-only packages can omit a publish stage while keeping the same
-  `integration` / `main` CI trigger pattern.
-- Merging the `integration → main` PR IS the manual approval for publish.
-- Patch auto-bumps per PR (see Version management); the owner sets minor/major and
-  gates the `integration → main` merge that triggers publish.
-
-## Version management
-
-- **Patch auto-bumps on the `integration` build, AFTER each PR merges.** The
-  integration CI runs `version-bump.sh --integration` and pushes the bumped
-  `package.json` commit **directly to `integration`**, marked `***NO_CI***` so
-  Azure skips it (no re-trigger). This needs the Project Build Service to have
-  **"Bypass policies when pushing"** on the repo (set in the Git Repositories
-  security namespace). Previously this bump ran on the `feat/*`/`fix/*` source
-  branch pre-merge, but pushing the bump there updated the PR source and forced a
-  second PR validation build (a wasteful double-trigger) — moving it to the
-  post-merge integration build removes that. (The bump is one patch per merged PR.)
-- Minor/major bumps are set manually by the repo owner; no changeset tooling.
-- **`integration → main` promotion + publish are owner-gated**: automation
-  opens/updates the `integration → main` PR; the owner approves the merge, which
-  triggers the versioned publish on `main`.
-- Exception: packages whose version lives in a non-npm file (e.g. Python —
-  enact-observe/gateway/voice) disable the auto-bump and bump manually.
-
-## Pipeline trigger config (all packages)
-
-```yaml
-trigger:
-  branches:
-    include:
-      - integration
-      - main
-
-pr:
-  branches:
-    include:
-      - integration
-```
-
-`feat/*` and `fix/*` are intentionally excluded — local Docker CI is the only
-branch gate before opening a PR to `integration`.
-
-Publish stage condition:
-
-```yaml
-condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
-```
-
-## Version pins for local CI scripts
-
-Tool versions for all `ci-local-*.sh` scripts are pinned in
-`scripts/ci-versions.env`:
-
-```bash
-NODE_IMAGE="node:22-bookworm"
-ZIG_VERSION="0.14.0"
-PYTHON_IMAGE="python:3.12-bookworm"
-UV_VERSION="0.11.8"   # must match enact-observe/pyproject.toml [tool.uv]
-```
-
-When upgrading a tool version: (1) update `scripts/ci-versions.env`, **then**
-(2) update the `variables:` block in the relevant `azure-pipelines.yml` — Azure
-Pipelines does NOT read this file; keep the two in sync manually.
-
-## Version-skip pattern
-
-All publish steps must handle already-published versions gracefully:
-
-- **npm public**: check `npm view <pkg> version`, skip if matches local.
-- **Azure Artifacts**: catch `403|409|already exist|upstream sources`, exit 0.
-- **cargo**: check the Azure Artifacts sparse index or crates.io API, skip if
-  the version already exists.
-
-## Examples
-
-**"Open a PR for my fix branch."**
-→ Run the step-0 gate (no open integration PR), then `az repos pr create` to
-`integration` with `--auto-complete true --delete-source-branch true`.
-→ Result: PR opens, CI runs, and on green it auto-merges — no reviewer needed.
-
-**"Promote integration to main."**
-→ Create/update the `integration → main` PR (NO `--auto-complete`,
-`references/cli-reference.md`). → Result: PR awaits the owner's approval; merging
-it triggers the versioned publish.
-
-**"Why didn't CI run on my PR?"**
-→ Follow the diagnosis in `references/build-failures.md`: push an empty commit,
-confirm the build-validation policy is enabled, ensure the PR is open and
-targets `integration`. → Result: the pipeline re-queues on the next push event.
-
-**"The pipeline is red — what failed?"**
-→ Pull the build timeline via token + curl (`references/build-failures.md`) while
-logs are still live. → Result: a printed list of failed Task/Job/Stage records
-with their first error messages.
-
-## Reference files
-
-Detailed command catalogs live under `references/` and load on demand. They all
-assume the [Variables](#variables) above are set.
-
-- **`references/cli-reference.md`** — az command catalog (PRs, work items,
-  pipelines, repos), the full PR workflow, the auto-complete gotcha, common flags.
-- **`references/policies-and-pipelines.md`** — REST recipes for merge-strategy
-  and build-validation policies, registering a pipeline, variable-group
-  authorization.
-- **`references/build-failures.md`** — pull failing-build timelines/logs via
-  token + curl; diagnose why CI did not trigger.
-- **`references/troubleshooting.md`** — `msrestazure` fix, `az repos` vs
-  `az devops`, pipeline bootstrap gotchas, first-run checklist.
-
-## Local branch maintenance (`git-maintain`)
-
-Local clones are kept tidy by a developer-machine LaunchAgent — you do not prune
-branches by hand. It is local-only (never deletes remote branches, never touches
-a working tree).
-
-- Script `~/.local/bin/git-maintain.sh`, agent `com.enact.git-maintain` (every
-  3 h + at login), log `~/.enact/logs/git-maintain.log`.
-- Per `enact-*` repo: `fetch --prune` → fast-forward local `integration` without
-  disturbing the working tree → **safe-only** prune (keeps `integration`/`main` +
-  current `HEAD` + latest 3; deletes only `[gone]`-upstream via `-D` and true
-  `--merged` via `-d`; squash-merged branches with a live remote are kept as
-  `unconfirmed merged`).
-- Preview: `GIT_MAINTAIN_DRY=1 ~/.local/bin/git-maintain.sh`. Disable:
-  `launchctl bootout gui/$(id -u)/com.enact.git-maintain`.
-
-This is why **`--delete-source-branch true` on every PR matters**: it lets a
-squash-merged branch's remote go away, which is the signal the agent prunes on.
-Full detail in the canonical doc below.
-
-## Canonical doc
-
-`enact-docs/05-operations/cross-package/git-branching-strategy.md`

package/extensions/enact-factory/skills/azdo-ci-strategy/references/build-failures.md

@@ -1,60 +0,0 @@
-# Reading build failures & diagnosing CI
-
-Assumes the **Variables** block from `../SKILL.md` is set (`$ORG_URL`,
-`$PROJECT`, `$AZDO_RESOURCE`).
-
-## Reading build failure output
-
-AzDO pipeline logs expire quickly (timeline returns HTTP 204 after ~24h). Get
-them while the run is fresh. **`az rest` does NOT work for AzDO URLs** — it
-cannot derive the right AAD scope; use a bearer token + `curl`.
-
-```bash
-TOKEN=$(az account get-access-token \
-  --resource "$AZDO_RESOURCE" \
-  --query accessToken -o tsv)
-
-# Failure summary from the build timeline (works while logs are live)
-curl -s -H "Authorization: Bearer $TOKEN" \
-  "$ORG_URL/$PROJECT/_apis/build/builds/<buildId>/timeline?api-version=7.1" \
-  | python3 -c "
-import sys, json
-d = json.load(sys.stdin)
-failed = [r for r in d.get('records', [])
-          if r.get('result') == 'failed' and r.get('type') in ('Task','Job','Stage')]
-for r in sorted(failed, key=lambda x: x.get('order', 0)):
-    print(r.get('type'), '|', r.get('name'))
-    for i in (r.get('issues') or [])[:3]:
-        print('  !', i.get('message', '')[:300])
-"
-
-# Logs container URL from a run
-az pipelines runs show --id <run-id> --output json \
-  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['logs']['url'])"
-
-# Fetch a specific log entry (<logId> from the logs index)
-curl -s -H "Authorization: Bearer $TOKEN" \
-  "$ORG_URL/$PROJECT/_apis/build/builds/<buildId>/logs/<logId>?api-version=7.1"
-```
-
-Timeline returns HTTP 204 (empty) once logs expire — check the AzDO web UI then.
-
-## Diagnosing why CI did not trigger on a PR
-
-CI should trigger automatically when commits land on a PR source branch. If it
-doesn't, do NOT manually queue a run:
-
-1. **Push a new commit** (even empty) to the source branch:
-   ```bash
-   git commit --allow-empty -m "ci: re-trigger pipeline"
-   git push
-   ```
-2. Check the PR's **build-validation policy** is enabled (pipeline registered and
-   the policy references the correct pipeline ID — see
-   `policies-and-pipelines.md`).
-3. Check the PR is open and targeting `integration`. Closed/draft PRs don't
-   trigger CI.
-
-For bootstrap PRs introducing `azure-pipelines.yml` for the first time, use
-`git push --force-with-lease` to force a new push event (see
-`troubleshooting.md` → pipeline bootstrap gotchas).

package/extensions/enact-factory/skills/azdo-ci-strategy/references/cli-reference.md

@@ -1,87 +0,0 @@
-# Azure DevOps CLI reference
-
-Command catalog for the enact-os workflow. Assumes the **Variables** block from
-`../SKILL.md` is set (`$ORG_URL`, `$PROJECT`, `$AZDO_RESOURCE`). For anything not
-listed here, run `az <group> --help`.
-
-## Most-used commands
-
-```bash
-# My PRs
-az repos pr list --creator "$(az account show --query user.name -o tsv)"
-az repos pr list --reviewer "$(az account show --query user.name -o tsv)"
-az repos pr show --id <pr-id>
-az repos pr checkout --id <pr-id>
-
-# My work items
-az boards query --wiql "SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.AssignedTo] = @Me AND [System.State] <> 'Closed' ORDER BY [System.ChangedDate] DESC"
-az boards work-item show --id <work-item-id>
-az boards work-item create --title "Task title" --type "Task"
-az boards work-item update --id <id> --state "In Progress"
-
-# Pipelines
-az pipelines list
-az pipelines runs list --top 10
-az pipelines runs show --id <run-id>
-
-# Repositories
-az repos list
-az repos show --repository <repo-name>
-az repos create --name "new-repo"
-```
-
-## Pull request workflow
-
-```bash
-# Create PR to integration — always auto-complete + delete-source-branch
-az repos pr create \
-  --source-branch feat/my-branch \
-  --target-branch integration \
-  --title "feat: description" \
-  --auto-complete true \
-  --delete-source-branch true \
-  --detect
-# CI passes → PR auto-merges. No reviewer required on integration.
-
-# Promotion PR to main (integration→main) — created/updated by automation,
-# merge stays MANUAL. Owner approval on this PR is the release gate.
-az repos pr create \
-  --source-branch integration \
-  --target-branch main \
-  --title "release: promote integration → main" \
-  --detect
-# NO --auto-complete         ← merge of the main PR is the manual release gate
-# NO --delete-source-branch  ← integration is permanent
-
-# Enable auto-complete on an existing integration PR (e.g. opened without flags)
-az repos pr update --id <pr-id> --auto-complete true --delete-source-branch true
-
-# Reviewers / votes / manual completion
-az repos pr update --id <pr-id> --reviewers user@email.com
-az repos pr set-vote --id <pr-id> --vote 10   # 10 approve · 5 approve-w/-suggestions · -5 wait · -10 reject
-az repos pr update --id <pr-id> --status completed
-```
-
-## Auto-complete gotcha (CLI/REST PRs)
-
-The project setting **"Set PRs to auto-complete on creation by default"**
-(Project settings → Repositories → Settings) is enabled, **but it applies only
-to PRs created in the web UI** — PRs created via `az repos pr create` / REST do
-NOT inherit it (verified: a CLI-created PR had auto-complete OFF despite the
-default). So for the CLI workflow, always pass **both** `--auto-complete true`
-and `--delete-source-branch true` explicitly. AzDO has no repo-level policy to
-force-delete branches on merge — enforce it at PR creation. Fix a PR opened
-without the flags after the fact:
-
-```bash
-az repos pr update --id <N> --auto-complete true --delete-source-branch true
-```
-
-## Common flags
-
-| Flag                | Description                                         |
-| ------------------- | --------------------------------------------------- |
-| `--org`             | Organization URL (or set via `az devops configure`) |
-| `--project`         | Project name (or set via `az devops configure`)     |
-| `--detect`          | Auto-detect org/project from the git remote         |
-| `-o json/table/tsv` | Output format                                       |

package/extensions/enact-factory/skills/azdo-ci-strategy/references/policies-and-pipelines.md

@@ -1,132 +0,0 @@
-# Branch policies, pipelines & variable groups (REST)
-
-Assumes the **Variables** block from `../SKILL.md` is set (`$ORG_URL`,
-`$PROJECT`, `$AZDO_RESOURCE`).
-
-## Enforcing merge strategy on a branch
-
-> **Do NOT use `az repos policy merge-strategy create`** — it warns
-> `This command is from the following extension: azure-devops`. Use the REST API
-> directly (bearer token + curl). Policy type id:
-> `fa4e907d-c16b-4a4c-9dfa-4916e5d171ab`.
-
-**integration — squash only** (1 clean commit per PR, linear history):
-
-```bash
-TOKEN=$(az account get-access-token \
-  --resource "$AZDO_RESOURCE" --query accessToken -o tsv)
-
-curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-  "$ORG_URL/$PROJECT/_apis/policy/configurations?api-version=7.1" \
-  -d '{
-    "isEnabled": true, "isBlocking": true,
-    "type": {"id": "fa4e907d-c16b-4a4c-9dfa-4916e5d171ab"},
-    "settings": {
-      "allowSquash": true, "allowNoFastForward": false,
-      "allowRebase": false, "allowRebaseMerge": false,
-      "scope": [{"repositoryId": "<repo-id>", "refName": "refs/heads/integration", "matchKind": "exact"}]
-    }
-  }'
-```
-
-**main — basic merge or fast-forward, no squash** (preserves full integration
-history on promotion):
-
-```bash
-# POST (new) uses the URL above with these settings; if a policy already exists,
-# PUT to .../policy/configurations/<policy-id>?api-version=7.1 instead.
-curl -s -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-  "$ORG_URL/$PROJECT/_apis/policy/configurations/<policy-id>?api-version=7.1" \
-  -d '{
-    "isEnabled": true, "isBlocking": true,
-    "type": {"id": "fa4e907d-c16b-4a4c-9dfa-4916e5d171ab"},
-    "settings": {
-      "allowSquash": false, "allowNoFastForward": true,
-      "allowRebase": true, "allowRebaseMerge": false,
-      "scope": [{"repositoryId": "<repo-id>", "refName": "refs/heads/main", "matchKind": "exact"}]
-    }
-  }'
-```
-
-POST fails with "rejected by policy" if a merge-strategy policy already exists on
-that branch — use PUT with the existing policy ID. Find existing IDs:
-
-```bash
-curl -s -H "Authorization: Bearer $TOKEN" \
-  "$ORG_URL/$PROJECT/_apis/policy/configurations?api-version=7.1" \
-  | python3 -c "
-import sys,json
-MERGE_TYPE='fa4e907d-c16b-4a4c-9dfa-4916e5d171ab'
-for p in json.load(sys.stdin).get('value',[]):
-    if p.get('type',{}).get('id') == MERGE_TYPE:
-        for s in p['settings'].get('scope',[]):
-            print(p['id'], s.get('repositoryId'), s.get('refName'))
-"
-```
-
-## Register a pipeline
-
-```bash
-# Run from inside the repo directory — --detect infers org/project/repo
-az pipelines create \
-  --name "<package-name> CI" \
-  --repository <repo-name> \
-  --repository-type tfsgit \
-  --branch <default-branch> \
-  --yml-path azure-pipelines.yml \
-  --skip-first-run \
-  --detect
-```
-
-## Build-validation policy (blocking CI gate)
-
-```bash
-az repos policy build create \
-  --repository-id <repo-id> \
-  --branch integration \
-  --build-definition-id <pipeline-id> \
-  --queue-on-source-update-only false \
-  --manual-queue-only false \
-  --valid-duration 0 \
-  --blocking true \
-  --enabled true \
-  --display-name "CI must pass before merge" \
-  --detect
-
-# List / delete policies for a repo
-az repos policy list --repository-id <repo-id> --detect -o table
-az repos policy delete --id <policy-id> --detect
-```
-
-Get `--repository-id` via `az repos show --repository <repo-name> --query id -o tsv --detect`.
-Policies for the enact-os packages were created 2026-05-19 with the above.
-
-## Variable-group authorization (first run)
-
-A pipeline referencing a variable group (e.g. `enact-dev-secrets`) for the first
-time queues but stays `notStarted` until authorized. Two ways:
-
-```bash
-# UI: open the stuck run and click "Permit" on the variable group.
-az pipelines runs list --pipeline-id <id> --output table
-# $ORG_URL/$PROJECT/_build/results?buildId=<run-id>
-```
-
-```bash
-# REST (no UI):
-TOKEN=$(az account get-access-token \
-  --resource "$AZDO_RESOURCE" --query accessToken -o tsv)
-az pipelines variable-group list --output table     # get <groupId>
-
-# Authorize specific pipelines:
-curl -s -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-  "$ORG_URL/$PROJECT/_apis/pipelines/pipelinePermissions/variablegroup/<groupId>?api-version=7.1-preview.1" \
-  -d '{"pipelines": [{"id": 9, "authorized": true}, {"id": 10, "authorized": true}]}'
-
-# …or all pipelines at once:
-curl -s -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-  "$ORG_URL/$PROJECT/_apis/pipelines/pipelinePermissions/variablegroup/<groupId>?api-version=7.1-preview.1" \
-  -d '{"allPipelines": {"authorized": true}}'
-```
-
-The authorization persists for that pipeline permanently.

package/extensions/enact-factory/skills/azdo-ci-strategy/references/troubleshooting.md

@@ -1,53 +0,0 @@
-# Troubleshooting & bootstrap gotchas
-
-Assumes the **Variables** block from `../SKILL.md` is set where commands use it.
-
-## Quick checks
-
-```bash
-az devops configure --list      # current config
-az account show                 # verify auth
-az extension show --name azure-devops
-```
-
-## PR commands live under `az repos`, not `az devops`
-
-```bash
-az devops pr create ...    # WRONG — 'pr' is not a subcommand of az devops
-az repos pr create --source-branch feature/x --target-branch integration --detect   # CORRECT
-```
-
-## Extension fails with `No module named 'msrestazure'`
-
-The `azure-devops` extension depends on `msrestazure`, not bundled in newer
-Homebrew `azure-cli` installs. Install it into az's own Python:
-
-```bash
-az --version 2>&1 | grep "Python location"   # e.g. .../azure-cli/2.76.0/libexec/bin/python
-/opt/homebrew/Cellar/azure-cli/<version>/libexec/bin/python -m pip install msrestazure
-
-# If the extension directory is corrupt, remove and reinstall:
-rm -rf ~/.azure/cliextensions/azure-devops
-az extension add --name azure-devops
-```
-
-## Pipeline bootstrap gotchas
-
-### First PR that adds `azure-pipelines.yml` will not trigger CI
-
-AzDO evaluates the `pr:` trigger using the YAML **in the target branch**
-(`integration`). If `azure-pipelines.yml` doesn't exist in `integration` yet
-(because the PR adding it hasn't merged), the trigger never fires. Merge the
-bootstrap PR manually once — subsequent PRs auto-trigger.
-
-### First-run checklist (new pipeline bootstrap)
-
-1. **Validate YAML locally:**
-   `python3 -c "import yaml; yaml.safe_load(open('azure-pipelines.yml')); print('OK')"`
-2. **Check tool versions exist:** e.g. Zig at
-   `https://ziglang.org/download/<version>/zig-linux-x86_64-<version>.tar.xz`
-   (`curl -sI`, expect 200).
-3. **Variable group authorized:** see `policies-and-pipelines.md` →
-   variable-group authorization.
-4. **Multi-checkout repos accessible:** if `resources: repositories` is used,
-   confirm the service connection has read access to each sibling repo.