@amsterdamdatalabs/enact-extensions 0.1.5 → 0.1.10

package/extensions/enact-factory/agents/planner.toml

@@ -0,0 +1,23 @@
+name = "planner"
+description = "Structured implementation planner that never writes production code"
+model_reasoning_effort = "medium"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+You are the Enact Loop planner agent.
+
+Role:
+- Turn a goal into a small, reviewable execution plan with clear acceptance criteria.
+- You do not implement code.
+
+Rules:
+- Never write production code.
+- Prefer 3 to 6 concrete steps.
+- Include dependencies, risks, and verification expectations.
+- Escalate unresolved product-direction choices instead of guessing.
+
+Output contract:
+- plan_summary
+- steps
+- acceptance_criteria
+- risks_and_open_questions
+"""

package/extensions/enact-factory/agents/verifier.toml

@@ -0,0 +1,29 @@
+name = "verifier"
+description = "Evidence-first verifier for real-surface QA and completion claims — independent grader"
+model_reasoning_effort = "high"
+sandbox_mode = "danger-full-access"
+tools = "Read, Grep, Glob, Bash"
+developer_instructions = """
+You are the Enact Loop verifier agent. You are an INDEPENDENT GRADER.
+
+You run on a different model and vendor from the executor. You must reach your own verdict
+independently — do not defer to the executor's self-assessment. Your verdict is recorded by
+`loop_grader_verdict` and is required before the judgment stage can close.
+
+Role:
+- Check whether completion claims are supported by fresh evidence.
+- Focus on commands run, outputs observed, and uncovered gaps.
+
+Rules:
+- Never edit files.
+- Do not trust prior claims without rerunning or directly reading evidence.
+- Mark each requirement VERIFIED, PARTIAL, or MISSING.
+- Separate missing evidence from failing behavior.
+- Record your GO/NO-GO verdict via loop_grader_verdict — do not self-report on behalf of the executor.
+
+Output contract:
+- verdict: PASS, FAIL, or INCOMPLETE
+- evidence: commands and observed results
+- requirement_matrix
+- remaining_gaps
+"""

package/extensions/enact-factory/skills/ai-slop-cleaner/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: ai-slop-cleaner
+description: "Walk the diff for TODO/placeholder/silent-catch noise and replace each with a concrete implementation or remove it entirely."
+---
+
+# AI Slop Cleaner
+
+## Purpose
+
+Removes low-quality AI-generated residue from code produced in a loop session: `// TODO`,
+"for now", "later", silent empty catch blocks, unreachable fallback layers, and placeholder strings.
+Each removal is replaced with a real implementation or an explicit compile-time error — never just
+deleted.
+
+## Use When
+
+- after an implementation pass before the loop reaches closure
+- before verification stages run
+- when a diff review reveals TODO comments, "for now" strings, or swallowed exceptions
+
+## Workflow
+
+1. Identify the files changed in the current session (use `git diff --name-only`).
+2. For each changed file, scan for these patterns:
+   - `// TODO`, `// FIXME`, `// HACK`, `// XXX`
+   - String literals containing "for now", "placeholder", "stub", "later", "not yet implemented"
+   - Empty catch blocks or catch blocks that only log without re-throwing or handling
+   - Fallback return values that hide real errors (e.g., `return null`, `return []` with no explanation)
+   - Dead code gated on `if (false)` or `if (process.env.NEVER)`
+3. For each hit, choose one action:
+   - Replace with a real implementation if the intent is clear
+   - Replace with an explicit thrown error if the path should never be reached
+   - Remove the dead code entirely if it adds no value
+4. After cleanup, re-run the project's doctor/lint check to confirm nothing broken.
+5. Re-run the project's test suite to confirm no regressions.
+6. Run a second grep pass to confirm zero hits remain:
+   ```
+   grep -rE "TODO|FIXME|HACK|for now|placeholder|stub" <changed-files>
+   ```
+
+## State Contract
+
+- Reads: changed files in the working tree
+- Writes: same files (in-place edits only); no new files, no new state in `.enact/loop/`
+
+## Final Check
+
+- Zero `TODO`, `FIXME`, `HACK`, or placeholder strings in changed files
+- No empty or swallowed catch blocks remain
+- Doctor/lint still passes after cleanup
+- Test suite still passes after cleanup
+- No code was deleted without a replacement or explicit error

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

@@ -0,0 +1,262 @@
+---
+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
+
+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/* PR to integration ── PR CI ──► auto-merge to integration
+fix/*  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" \
+     --auto-complete true \
+     --delete-source-branch true \
+     --detect
+   ```
+
+4. CI runs automatically on the PR. When CI passes the PR **auto-merges** 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/*`                            | Build + test + lint                                                                             |
+| Push to `fix/*`                             | **Nothing** — local Docker CI is the gate                                                       |
+| PR opened / updated targeting `integration` | Build + test + lint                                                                             |
+| Push to `integration` (after PR merged)     | Build + test + lint                                                                             |
+| 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.
+- Version bumps are done manually by the repo owner before approving that PR.
+
+## Version management
+
+- No automated changesets or version bots.
+- Repo owner bumps `package.json` / `Cargo.toml` version manually.
+- Automation opens or updates the `integration → main` PR.
+- Repo owner merges that PR to trigger publish.
+
+## Pipeline trigger config (all packages)
+
+```yaml
+trigger:
+  branches:
+    include:
+      - integration
+      - feat/*
+      - main
+
+pr:
+  branches:
+    include:
+      - integration
+```
+
+`feat/*` is included so pushes to feature branches run CI (per the table above);
+`fix/*` is intentionally excluded — local Docker CI is its only gate.
+
+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.
+
+## Canonical doc
+
+`enact-docs/05-operations/cross-package/git-branching-strategy.md`

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

@@ -0,0 +1,60 @@
+# 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

@@ -0,0 +1,87 @@
+# 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

@@ -0,0 +1,132 @@
+# 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.