force-link-environment

> **Plugin check**: Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.

# force-link-environment

Move a dev or target environment's Power Platform Pipelines host association from one host to another. This is the documented remediation when `deploymentenvironments` create fails with *"this environment is already associated with another pipelines host"*, and also the right tool when intentionally migrating environments between hosts.

**Microsoft Learn (ground truth):** [Using Force Link to associate an environment with a new host](https://learn.microsoft.com/en-us/power-platform/alm/custom-host-pipelines#using-force-link-to-associate-an-environment-with-a-new-host)

## What this skill changes

In the **target host** (the new host the user wants to use):
- Marks the existing `deploymentenvironments` record as the active stamp for the BAP environment.
- Re-runs validation; on success, `validationstatus` flips to `Succeeded` (200000001).

In the **previous host** (the host the env was previously linked to):
- The corresponding `deploymentenvironments` row is **delinked**. Its `validationstatus` is left stale until refreshed in the previous host's UI.
- Makers who could run pipelines through that environment in the previous host **lose access** to those pipelines via this environment.

The action is reversible by running Force Link again from the previous host.

## Phase 1.5 — Microsoft Learn grounding (required)

Before any Dataverse call, refresh the agent's grounding by fetching the doc above via `mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch`. If the doc has updated behaviors (e.g., new permission requirements, new warning text), surface them to the user before continuing. See `${CLAUDE_PLUGIN_ROOT}/references/alm-docs-grounding.md` for the shared pattern.

## Phases

| # | Phase | Output |
|---|---|---|
| 1 | Prerequisites | Azure CLI token for the host environment; PAC CLI authenticated |
| 1.5 | MCP Learn grounding | Confirmed current behavior of Force Link / `ManageEnvironmentStamp` |
| 2 | Identify host + dev env | `hostEnvUrl`, target host's `deploymentEnvironmentId`, source BAP env GUID |
| 3 | Resolve `deploymentenvironments` record | Either an existing record on the new host, or a freshly created one |
| 4 | Confirm destructive action | Explicit user consent via `AskUserQuestion` |
| 5 | Execute Force Link | 204 from `ManageEnvironmentStamp` + post-validation Succeeded |
| 6 | Write marker + summary | `docs/alm/last-force-link.json` + human-readable summary |

Create all tasks at Phase 1 start with `TaskCreate`. Mark each `in_progress` when starting and `completed` when done.

---

## Phase 1 — Prerequisites

Reuse the shared verifier:

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/verify-alm-prerequisites.js"
```

Specifically required:
- **PAC CLI auth** — `pac env who` must report an authenticated environment (for `--dev-env` auto-discovery).
- **Azure CLI auth** — `az account show` succeeds.
- **Host-scoped token** — the caller must have Deployment Pipeline Administrator on the target host (the host the env is being linked TO). Without it, `ManageEnvironmentStamp` returns 403.

Fetch the host token from Azure CLI using the host's Dataverse URL as the resource. Reuse `getAuthToken` from `scripts/lib/validation-helpers.js`.

## Phase 1.5 — MCP Learn grounding

Call:

```
mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch(url=
  "https://learn.microsoft.com/en-us/power-platform/alm/custom-host-pipelines")
```

Confirm the *"Using Force Link…"* section's current warnings before proceeding. If the section now mentions new prerequisites or rollback constraints not covered in this skill, surface them to the user.

## Phase 2 — Identify host + dev env

<!-- gate: force-link-environment:2.host-url | category=plan | cancel-leaves=nothing -->

> 🚦 **Gate (plan · force-link-environment:2.host-url):** Pick the target host environment URL when arg / marker resolution paths all came up empty. Fires only on the "no `--host` arg, no `last-host-check.json`, no `last-pipeline.json`" branch (step 4 below).
>
> **Trigger:** Phase 2 resolution order steps 1–3 all returned no value.
> **Why we ask:** Auto-picking the wrong host runs `ManageEnvironmentStamp` against the wrong tenant and moves the stamp irreversibly without consent.
> **Cancel leaves:** Nothing — no API call yet.

<!-- gate: force-link-environment:2.dev-env | category=plan | cancel-leaves=nothing -->

> 🚦 **Gate (plan · force-link-environment:2.dev-env):** Pick (or paste) the source dev env's BAP env GUID when `--dev-env` arg is absent and `pac env who` didn't confirm. Fires only on the "no arg + no confirmation" branch (step 3 below).
>
> **Trigger:** Phase 2 BAP-GUID resolution steps 1–2 all returned no value.
> **Why we ask:** Auto-picking the wrong dev env relinks a different env to the new host — makers of the wrong env lose pipeline access.
> **Cancel leaves:** Nothing — no API call yet.

Resolution order for `hostEnvUrl`:
1. `--host <url>` argument, if supplied.
2. `docs/alm/last-host-check.json` (written by `ensure-pipelines-host`) — read `finalHostEnvUrl`.
3. `docs/alm/last-pipeline.json` — read `hostEnvUrl`.
4. Prompt user via `AskUserQuestion`.

Resolution order for the source dev env's BAP env GUID:
1. `--dev-env <guid>` argument, if supplied.
2. `pac env who` (current PAC CLI env) — but ONLY if the user confirms this is the env to relink.
3. Prompt user via `AskUserQuestion`.

## Phase 3 — Resolve `deploymentenvironments` record on the new host

**Goal of this phase:** obtain the `deploymentEnvironmentId` (the new host's record ID) regardless of whether it already exists, just got created, or got created in a Failed state. Force Link in Phase 5 cannot run without that GUID.

### Step 3.1 — Look up by BAP env GUID

```bash
GET {hostEnvUrl}/api/data/v9.1/deploymentenvironments?$filter=environmentid eq '{bapEnvId}'&$s