@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.37 → 0.1.46

package/packages/agent-skills/src/deploy.ts

@@ -42,6 +42,16 @@ export interface DeploySkillsOptions {
   readonly profile?: DeployProfile;
   /** Computes the exact same written/unchanged/removed/conflicts/retiredRemovals result without writing anything (independent review, 2026-09-29, finding 6). */
   readonly dryRun?: boolean;
+  /**
+   * When set, deploy only the named surface (profile.surfaces[].name) —
+   * the deploy half of the per-surface knob (az567). Other surfaces are
+   * left untouched: their files are not written, their conflicts are not
+   * reported, their retired-folder cleanup does not run. The deploy
+   * profile's `retired` list is the closed set of "skill folders no
+   * surface reads any more"; for surface-prepare this list is also
+   * filtered to the active surfaces.
+   */
+  readonly surfaceFilter?: string;
 }
 
 export interface SkillConflict {
@@ -95,6 +105,201 @@ export function removeEmptyParents(root: string, dir: string): void {
   }
 }
 
+// ---------------------------------------------------------------------------
+// az696 — `adl skills uninstall`: the removal primitive.
+//
+// `removeDeployedSkillFolders` removes the skill folders a previous
+// `deploySkills` wrote, in the same resolution order (assets/ as the
+// source of truth, the deploy profile as the closed set of surfaces, the
+// repo's `[assets.skills]` subset respected on input).
+//
+// The function is split out from `deploySkills` because the deployment
+// hot path should never carry the removal logic. The two are
+// intentionally NOT one function with a flag — deploy's return value
+// (written/unchanged/removed/conflicts/adopted) and uninstall's return
+// value (removed/absent/refused) carry different fields, and a single
+// result type would force both callers to ignore the half they don't
+// care about.
+//
+// Safety: the only paths this function will remove are exactly the paths
+// recorded in the deploy manifest. Anything else in the target repo —
+// a hand-authored skill, an extra file the manifest did not write, a
+// hand-edited deploy-written file — is reported in `refused` and never
+// touched. This mirrors deploy's own contract that it never writes a
+// file it did not itself originate (deploy.ts's header).
+// ---------------------------------------------------------------------------
+
+export interface SkillRefusal {
+  readonly folder: string;
+  readonly skill: string;
+  /** Repo-relative posix path to the entry the primitive refused to remove. */
+  readonly path: string;
+  /** Human-readable reason the entry was refused. */
+  readonly reason: string;
+}
+
+export interface RemoveDeployedSkillFoldersOptions {
+  readonly assetsDir: string;
+  readonly targetRepo: string;
+  /** Defaults to loadProfile() (the package's own deploy-profile.json) — pass explicitly when the caller has already resolved real on-disk paths (see profile.ts's header). */
+  readonly profile?: DeployProfile;
+  /** When set, only the skill folders for this surface (profile.surfaces[].name) are in scope. */
+  readonly surfaceFilter?: string;
+  /** When set, only this skill id (assets/ skill folder name) is in scope. */
+  readonly skillFilter?: string;
+  /** Computes the exact same removed/absent/refused result without unlinking anything. */
+  readonly dryRun?: boolean;
+}
+
+export interface RemoveDeployedSkillFoldersResult {
+  /** Repo-relative posix paths the primitive actually removed (or would have, in --dry-run). Sorted, deduplicated. */
+  readonly removed: readonly string[];
+  /** (surface, skill) pairs the deploy profile resolves to that are in scope but were already absent on disk. Sorted, deduplicated, "<folder>/<skill>". */
+  readonly absent: readonly string[];
+  /** Entries the manifest did not record but which live inside a managed skill dir or surface folder — never removed, always reported. */
+  readonly refused: readonly SkillRefusal[];
+}
+
+/**
+ * The deployed-skill removal primitive (az696). Removes every file the
+ * deploy manifest records, restricted by `surfaceFilter`/`skillFilter`
+ * (intersection) and the repo's `[assets.skills]` subset. Idempotent: a
+ * second call with the same arguments reports every target in `absent`.
+ */
+export function removeDeployedSkillFolders(options: RemoveDeployedSkillFoldersOptions): RemoveDeployedSkillFoldersResult {
+  const { assetsDir, targetRepo } = options;
+  const dryRun = options.dryRun === true;
+
+  if (!existsSync(assetsDir) || !statSync(assetsDir).isDirectory()) {
+    throw new Error(`agent-skills assets directory not found: ${assetsDir}`);
+  }
+  if (!existsSync(targetRepo) || !statSync(targetRepo).isDirectory()) {
+    throw new Error(`uninstall target is not a directory: ${targetRepo}`);
+  }
+
+  const profile = options.profile ?? loadProfile();
+  const availableSkills = listSourceSkillNames(assetsDir);
+
+  const selection = resolveSkillSelection(targetRepo, availableSkills);
+  if (!selection.ok) throw new Error(selection.error);
+  const selectedSkills = [...new Set(selection.skills)].sort();
+
+  const manifest = readManifest(targetRepo);
+
+  // Build the in-scope (surface, skill) set, applying both filters as
+  // intersection. An unknown surfaceFilter or skillFilter is silently
+  // out-of-scope — the caller (the CLI) validates the names first and
+  // the primitive trusts its inputs.
+  const inScopeSurfaces = profile.surfaces.filter(
+    (surface) => options.surfaceFilter === undefined || surface.name === options.surfaceFilter,
+  );
+  const inScopeSkills = selectedSkills.filter(
+    (skill) => options.skillFilter === undefined || skill === options.skillFilter,
+  );
+
+  // Build the manifest-ownership set restricted to the in-scope
+  // (surface, skill) pairs. Everything the manifest records under those
+  // pairs is removable; everything else is not in scope.
+  const ownedPaths = new Set<string>();
+  for (const surface of inScopeSurfaces) {
+    for (const skill of inScopeSkills) {
+      const prefix = `${surface.folder}/${skill}/`;
+      for (const file of manifest.files) {
+        if (file.startsWith(prefix)) ownedPaths.add(file);
+      }
+    }
+  }
+
+  const removed: string[] = [];
+  for (const relPath of [...ownedPaths].sort()) {
+    const absolute = join(targetRepo, relPath);
+    if (existsSync(absolute)) {
+      if (!dryRun) {
+        unlinkSync(absolute);
+        removeEmptyParents(targetRepo, dirname(absolute));
+      }
+    }
+    removed.push(relPath);
+  }
+
+  // Safety check: every path inside a managed skill dir or surface
+  // folder that is NOT in the manifest is reported as a refusal. The
+  // surface folder itself (e.g. `.claude/skills`) is reported when it
+  // exists and is not under any managed skill dir — the agent never
+  // removes the surface root on its own, only the skill dirs under it.
+  const refused: SkillRefusal[] = [];
+  for (const surface of inScopeSurfaces) {
+    const surfaceAbs = join(targetRepo, surface.folder);
+    if (!existsSync(surfaceAbs)) continue;
+    const inScope = options.skillFilter === undefined
+      ? inScopeSkills
+      : inScopeSkills.filter((skill) => skill === options.skillFilter);
+
+    // Hand-authored skill dirs the manifest did not write.
+    for (const name of directoryNames(surfaceAbs)) {
+      if (inScope.includes(name)) continue;
+      // A skill the manifest owns under this surface is in-scope; an
+      // unrecorded same-name dir is user-authored and refused.
+      const isManaged = manifest.files.some((file) => file.startsWith(`${surface.folder}/${name}/`));
+      if (isManaged) continue; // already handled in the removal pass above
+      refused.push({
+        folder: surface.folder,
+        skill: name,
+        path: `${surface.folder}/${name}`,
+        reason: "folder is not recorded in the deploy manifest; refusing to remove user-authored content",
+      });
+    }
+
+    // For each in-scope skill dir, any file inside that is not in the
+    // manifest is reported and never removed.
+    for (const skill of inScope) {
+      const skillDirAbs = join(surfaceAbs, skill);
+      if (!existsSync(skillDirAbs)) continue;
+      const isManaged = manifest.files.some((file) => file.startsWith(`${surface.folder}/${skill}/`));
+      if (!isManaged) continue; // already refused above as user-authored
+      for (const relFile of walkFiles(skillDirAbs)) {
+        const relPath = `${surface.folder}/${skill}/${relFile}`;
+        if (ownedPaths.has(relPath)) continue;
+        refused.push({
+          folder: surface.folder,
+          skill,
+          path: relPath,
+          reason: "file is inside a managed skill dir but is not recorded in the deploy manifest; refusing to remove user-authored content",
+        });
+      }
+    }
+  }
+  refused.sort((a, b) => a.path.localeCompare(b.path));
+
+  // The "absent" report: every (surface, skill) pair the deploy profile
+  // resolves to, filtered to in-scope, that has no files on disk and no
+  // manifest record. This is the idempotency signal a second run will
+  // see.
+  const absent: string[] = [];
+  for (const surface of inScopeSurfaces) {
+    for (const skill of inScopeSkills) {
+      const skillDirAbs = join(targetRepo, surface.folder, skill);
+      const prefix = `${surface.folder}/${skill}/`;
+      const hasManifestEntry = manifest.files.some((file) => file.startsWith(prefix));
+      if (!hasManifestEntry && !existsSync(skillDirAbs)) {
+        absent.push(`${surface.folder}/${skill}`);
+      }
+    }
+  }
+  absent.sort();
+
+  // Rewrite the manifest to drop the paths we removed (and only those).
+  // The surviving set keeps every path the manifest recorded that is
+  // outside the in-scope (surface, skill) pairs — those belong to other
+  // surfaces/skills the user did not ask to uninstall.
+  if (!dryRun) {
+    const surviving = manifest.files.filter((file) => !ownedPaths.has(file));
+    writeManifest(targetRepo, surviving);
+  }
+
+  return { removed: removed.sort(), absent, refused };
+}
+
 export function deploySkills(options: DeploySkillsOptions): DeploySkillsResult {
   const { assetsDir, targetRepo } = options;
   const dryRun = options.dryRun === true;
@@ -164,6 +369,10 @@ export function deploySkills(options: DeploySkillsOptions): DeploySkillsResult {
       }
     };
     for (const surface of profile.surfaces) {
+      // az567 surfaceFilter: skip non-target surfaces entirely. The
+      // legacy-takeover pass for the non-target surface is irrelevant
+      // when only one surface is being deployed.
+      if (options.surfaceFilter !== undefined && surface.name !== options.surfaceFilter) continue;
       for (const skill of selectedSkills) {
         const skillDirRel = `${surface.folder}/${skill}`;
         const skillDirAbs = join(targetRepo, skillDirRel);
@@ -180,12 +389,23 @@ export function deploySkills(options: DeploySkillsOptions): DeploySkillsResult {
 
       legacyRetired(surface.folder, true);
     }
-    for (const folder of retiredFolders(profile)) legacyRetired(folder, false);
+    for (const folder of retiredFolders(profile)) {
+      // az567 surfaceFilter: retired-folder cleanup is also filtered to
+      // the active surfaces. A non-target surface's retired folder is
+      // left exactly as found.
+      if (options.surfaceFilter !== undefined) {
+        const isTargetActive = profile.surfaces.some((s) => s.folder === folder && s.name === options.surfaceFilter);
+        if (!isTargetActive) continue;
+      }
+      legacyRetired(folder, false);
+    }
   }
 
   const manifestFiles = new Set([...manifest.files, ...takeoverFiles]);
   const adopted: string[] = [];
 
+  // Total over `selectedSkills`: every loop below iterates that same array, so
+  // `sourceFilesBySkill.get(skill)` is never undefined and needs no fallback.
   const sourceFilesBySkill = new Map<string, readonly string[]>();
   for (const skill of selectedSkills) sourceFilesBySkill.set(skill, walkFiles(join(assetsDir, skill)));
 
@@ -195,6 +415,10 @@ export function deploySkills(options: DeploySkillsOptions): DeploySkillsResult {
   const keptPaths = new Set<string>();
 
   for (const surface of profile.surfaces) {
+    // az567 surfaceFilter: only iterate the named surface. Other
+    // surfaces' deploy paths, conflicts, and removal decisions are out
+    // of scope and never appear in this result.
+    if (options.surfaceFilter !== undefined && surface.name !== options.surfaceFilter) continue;
     for (const skill of selectedSkills) {
       const skillDirRel = `${surface.folder}/${skill}`;
       const skillDirAbs = join(targetRepo, skillDirRel);
@@ -204,7 +428,7 @@ export function deploySkills(options: DeploySkillsOptions): DeploySkillsResult {
       // An unrecorded folder whose whole tree is byte-identical to the asset
       // is adopted: its files fall through to the write loop below as
       // unchanged and so land in the manifest. Anything else stays a conflict.
-      if (skillDirExists && !managedByUs && folderIdenticalToAsset(skillDirAbs, join(assetsDir, skill), sourceFilesBySkill.get(skill) ?? [])) {
+      if (skillDirExists && !managedByUs && folderIdenticalToAsset(skillDirAbs, join(assetsDir, skill), sourceFilesBySkill.get(skill)!)) {
         managedByUs = true;
         adopted.push(skillDirRel);
       }
@@ -220,7 +444,7 @@ export function deploySkills(options: DeploySkillsOptions): DeploySkillsResult {
         continue; // never write into it, never claim its files in the manifest
       }
 
-      for (const relFile of sourceFilesBySkill.get(skill) ?? []) {
+      for (const relFile of sourceFilesBySkill.get(skill)!) {
         const targetRel = `${skillDirRel}/${relFile}`;
         keptPaths.add(targetRel);
         const targetAbs = join(targetRepo, targetRel);
@@ -245,6 +469,14 @@ export function deploySkills(options: DeploySkillsOptions): DeploySkillsResult {
     // profile actually manages, even though every manifest entry should
     // already satisfy that by construction.
     if (!profile.surfaces.some((surface) => relPath.startsWith(`${surface.folder}/`))) continue;
+    // az567 surfaceFilter: paths under a non-target surface are not in
+    // scope and must not be removed during a per-surface deploy.
+    if (options.surfaceFilter !== undefined) {
+      const inTargetSurface = profile.surfaces.some(
+        (surface) => surface.name === options.surfaceFilter && relPath.startsWith(`${surface.folder}/`),
+      );
+      if (!inTargetSurface) continue;
+    }
     const absolute = join(targetRepo, relPath);
     if (existsSync(absolute)) {
       if (!dryRun) {
@@ -270,6 +502,12 @@ export function deploySkills(options: DeploySkillsOptions): DeploySkillsResult {
   const retiredRemovals: string[] = [];
   const availableSkillSet = new Set(availableSkills);
   for (const folder of retiredFolders(profile)) {
+    // az567 surfaceFilter: only clean up retired folders that are NOT
+    // tied to a non-target surface. A retired folder is per-profile
+    // (the active-surface filters above do not reduce the retired list);
+    // when a surfaceFilter is set, retired-folder cleanup runs the same
+    // way it does for a full deploy, because retired folders are not
+    // tied to a particular active surface.
     const folderAbs = join(targetRepo, folder);
     if (!existsSync(folderAbs)) continue;
 

package/packages/agent-skills/src/index.ts

@@ -1,4 +1,13 @@
-export { deploySkills, type DeploySkillsOptions, type DeploySkillsResult, type SkillConflict } from "./deploy.js";
+export {
+  deploySkills,
+  type DeploySkillsOptions,
+  type DeploySkillsResult,
+  type SkillConflict,
+  removeDeployedSkillFolders,
+  type RemoveDeployedSkillFoldersOptions,
+  type RemoveDeployedSkillFoldersResult,
+  type SkillRefusal,
+} from "./deploy.js";
 export {
   doctorAssets,
   doctorDeployment,

package/packages/azdo/README.md

@@ -68,13 +68,22 @@ adl mcp cli pr-create-or-update --action create \
   --title 'feat(cli): add direct mode' \
   --description $'## Summary\n\nAdds a CLI path.\n\n## Why\n\nMCP can be unavailable.\n\n## Changes\n\n- Add CLI mode'
 adl mcp cli build-run --id 17 --branch refs/heads/integration
-adl mcp cli workitem-create-or-update --type Bug --title 'CLI failure' --parent-id 378
+adl mcp cli workitem-create-or-update-bug --title 'CLI failure' --parent-id 378 --effort 1 --description $'## Current behaviour\n\nCLI exits 2.\n\n## Expected behaviour\n\nExits 0.\n\n## Behaviour that must not change\n\nJSON on stdout.\n\n## Responsible Feature\n\naz378\n\n## Verification\n\nRe-run the failing command.'
 ```
 
 Run `adl mcp cli --help` for the complete flag contract. The CLI has exactly the
-current MCP surface: `pr_list_or_get`, `pr_create_or_update`, `build_list_or_get`,
-`build_run`, `workitem_list_or_get`, and `workitem_create_or_update`; the CLI exposes
-their hyphenated equivalents.
+current MCP surface: `pr_list_or_get`, `pr_create_or_update`, `pr_review`,
+`build_list_or_get`, `build_run`, `workitem_list_or_get`,
+`workitem_create_or_update_feature`, `workitem_create_or_update_pbi`,
+`workitem_create_or_update_bug`, `workitem_comments_read`, `workitem_attachments`,
+`activity_add` and `activity_list`; the CLI exposes their hyphenated equivalents.
+The blanket `workitem_create_or_update` was split per work-item type so the agent
+gate can enforce each type's mandatory fields (Feature: title + parentId + priority
++ intent.md description; PBI/Bug: title + parentId + item-file description + effort
+in days; `comment` on every update of any type); the read side
+(`workitem_list_or_get`) stays one tool. Per-type mandatory fields and the
+heading-parse gates: see
+`packages/agent-skills/assets/workitems-process/references/ado-and-git.md` §1a.
 
 ## Source
 

package/packages/azdo/bunfig.toml

@@ -0,0 +1,6 @@
+# Bun test config — like Python's conftest.py: a preload file runs once
+# before every test in this package. tests/setup.ts installs the test-only
+# AzureRemote defaults (org / project / repository) that the resolvers
+# fall back to when no argument and no git remote resolve.
+[test]
+preload = ["./tests/setup.ts"]

package/packages/azdo/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "start": "bun src/mcp-server.ts",
-    "test": "bun test --coverage",
+    "test": "bun test --isolate --coverage --timeout 30000",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

package/packages/azdo/src/azdo-attachments.ts

@@ -63,7 +63,8 @@ export async function uploadAttachment(c: AdoClient, workItemId: number, fileNam
 /** The T2 guard (board-rules.md § Attachments): a plan-r* file refuses deletion once any item of its Feature has left Awaiting Approval — the plan G1 approved stays on the board. */
 async function assertPlanAttachmentDeletable(c: AdoClient, feature: any, fileName: string): Promise<void> {
   const relationId = (url: string) => Number(/(\d+)\/?$/.exec(url)?.[1]);
-  const childIds = (feature.relations ?? [])
+  // `feature.relations` is always an array here: attachedFiles() returned a target off this same object, so the property was a non-empty array moments earlier -- the nullish fallback was unreachable.
+  const childIds = feature.relations
     .filter((relation: any) => relation.rel === 'System.LinkTypes.Hierarchy-Forward')
     .map((relation: any) => relationId(relation.url))
     .filter((id: number) => Number.isInteger(id));

package/packages/azdo/src/azdo-pr.ts

@@ -22,8 +22,8 @@ export function resetClientForTests(): void {
 }
 
 /** The human-facing PR link, built from the same org/project root the API call uses. */
-export function pullRequestWebUrl(repository: string, pullRequestId: number | string): string {
-  return `${adoProjectUrl()}/_git/${repository}/pullrequest/${pullRequestId}`;
+export function pullRequestWebUrl(repository: string, pullRequestId: number | string, cwd?: string): string {
+  return `${adoProjectUrl(cwd)}/_git/${repository}/pullrequest/${pullRequestId}`;
 }
 
 /**
@@ -127,6 +127,20 @@ export async function prListOrGet(args: PrListOrGetArgs): Promise<string> {
       pullRequestsPath(repository, args.id),
       { 'api-version': '7.1' }
     );
+    // Embed the relation inline (Bug 706) so callers can verify the
+    // work-items set on the single-PR view without a second request. The
+    // PR's own response carries `_links.workItems.href` but no inline
+    // array; this follow-on reads the sub-resource and overlays the ids.
+    // The list branch below intentionally keeps the small PR shape
+    // (no inline array); only the per-PR fetch path embeds it.
+    const workItems = await c.get<{ value?: Array<{ id?: number }> }>(
+      pullRequestsPath(repository, args.id) + '/workItems',
+      { 'api-version': '7.1' }
+    );
+    pr.workItems = (workItems.value ?? [])
+      .map((entry) => Number(entry.id))
+      .filter((id) => Number.isInteger(id))
+      .sort((a, b) => a - b);
     return JSON.stringify(pr, null, 2);
   }
 
@@ -180,6 +194,10 @@ export type PrCreateOrUpdateArgs = {
   deleteSourceBranch?: boolean;
   /** P4: the content of the kind's mandatory Feature attachment (planning/implementation PRs only). */
   attachmentContent?: string;
+  /** P5: positive integer work-item ids to add to the PR's work-items relation on update. */
+  addWorkItems?: number[];
+  /** P5: positive integer work-item ids to remove from the PR's work-items relation on update. */
+  removeWorkItems?: number[];
   /** Overrides `AZURE_DEVOPS_REPO` for this call. */
   repository?: string;
   /** Rejected removed routing input; PRs always use the checked-out branch. */
@@ -188,11 +206,146 @@ export type PrCreateOrUpdateArgs = {
   targetBranch?: never;
 };
 
+/**
+ * P5: the public signature of the post-create work-items update.
+ *
+ * The shape per the doc the human pasted (2026-10-14): a separate
+ * `/workitems` sub-endpoint does not exist; the PR's own endpoint does
+ * not honour `workItems` as an updatable field. The real route is the
+ * work-item's `relations` array, mutated via JSON-Patch on the work item
+ * itself. Each `--add-work-items` id gets an `ArtifactLink` of rel
+ * `Pull Request` pointing at the PR; the PR's `workItems` sub-endpoint
+ * (a READ) then lists the same ids, which is the live verification.
+ *
+ *   PATCH /_apis/wit/workitems/{workItemId}?api-version=7.1
+ *   Content-Type: application/json-patch+json
+ *   Body: [{ op: "add", path: "/relations/-", value: { rel: "ArtifactLink",
+ *            url: "vstfs:///Git/PullRequestId/{projectId}%2F{repoId}%2F{prId}",
+ *            attributes: { name: "Pull Request" } } }]
+ *
+ * The function validates the inputs (no id in both lists; positive integers;
+ * dedupe), and for each add issues a PATCH on the work item. A `remove`
+ * issues a JSON-Patch `remove` on the matching `ArtifactLink` (matched by
+ * the work item's `relations` array; the `url` field is the only stable
+ * identifier). Returns the merged id set the PR's workItems sub-endpoint
+ * reports back. The `pr_create_or_update` tool's update path calls this
+ * when at least one of `--add-work-items` / `--remove-work-items` is
+ * supplied.
+ */
+export type UpdatePrWorkItemLinksArgs = {
+  add: number[];
+  remove: number[];
+};
+
+export async function updatePrWorkItemLinks(
+  c: AdoClient,
+  prId: number,
+  args: UpdatePrWorkItemLinksArgs,
+): Promise<number[]> {
+  const additions = dedupeIntegers(args.add);
+  const removals = dedupeIntegers(args.remove);
+  const overlap = additions.find((id) => removals.includes(id));
+  if (overlap !== undefined) {
+    throw new Error(`work-item ${overlap} is in both add and remove; an id can only appear on one side of the PATCH (P5 FENCE)`);
+  }
+  if (!Number.isInteger(prId) || prId <= 0) {
+    throw new Error(`prId must be a positive integer`);
+  }
+  // Resolve the project + repository GUIDs at call time from ADO. The vstfs
+  // URL is `vstfs:///Git/PullRequestId/{projectId}%2F{repoId}%2F{prId}` —
+  // both GUIDs are required and are not on the PR's own response. The
+  // canonical Azure DevOps REST shape returns both on
+  // `GET /{org}/{project}/_apis/git/repositories/{repoName}`. We cache the
+  // resolution so the loop below does not call it per work item.
+  const repository = resolveRepository();
+  const repoDoc = await c.get<{ id?: string; project?: { id?: string } }>(
+    `/git/repositories/${repository}`,
+    { 'api-version': '7.1' },
+  );
+  const repoId = repoDoc.id;
+  const projectId = repoDoc.project?.id;
+  if (!repoId || !projectId) {
+    throw new Error(`updatePrWorkItemLinks could not resolve repository GUIDs; GET .../repositories/${repository} returned id=${repoId}, project.id=${projectId}`);
+  }
+  const prLinkUrl = `vstfs:///Git/PullRequestId/${projectId}%2F${repoId}%2F${prId}`;
+  for (const workItemId of additions) {
+    const current = await c.get<{ relations?: Array<{ rel?: string; url?: string }> }>(
+      `/wit/workitems/${workItemId}`,
+      { 'api-version': '7.1', $expand: 'relations' },
+    );
+    const relations = current.relations ?? [];
+    const alreadyLinked = relations.some(
+      (rel) => rel.rel === 'ArtifactLink' && rel.url === prLinkUrl,
+    );
+    if (alreadyLinked) continue;
+    await c.patch<unknown>(
+      `/wit/workitems/${workItemId}`,
+      [
+        {
+          op: 'add',
+          path: '/relations/-',
+          value: {
+            rel: 'ArtifactLink',
+            url: prLinkUrl,
+            attributes: { name: 'Pull Request' },
+          },
+        },
+      ],
+      { 'api-version': '7.1' },
+      'application/json-patch+json',
+    );
+  }
+  if (removals.length > 0) {
+    // For each work item, fetch the current relations, find the one whose
+    // url matches the PR's vstfs URL, and remove it via JSON-Patch.
+    for (const workItemId of removals) {
+      const current = await c.get<{ relations?: Array<{ rel?: string; url?: string }> }>(
+        `/wit/workitems/${workItemId}`,
+        { 'api-version': '7.1', $expand: 'relations' },
+      );
+      const relations = current.relations ?? [];
+      const targetIndex = relations.findIndex((r) => r.url === prLinkUrl);
+      if (targetIndex === -1) continue;
+      await c.patch<unknown>(
+        `/wit/workitems/${workItemId}`,
+        [{ op: 'remove', path: `/relations/${targetIndex}` }],
+        { 'api-version': '7.1' },
+        'application/json-patch+json',
+      );
+    }
+  }
+  // Read the PR's workItems sub-endpoint as the verification surface. This
+  // is the only server endpoint that lists the relation; the PR's own
+  // response does not carry workItems. The path uses the repository NAME
+  // (the package convention for REST URLs — see `pullRequestsPath`), not
+  // the GUID that the vstfs URL above embeds.
+  const verify = await c.get<{ value?: Array<{ id?: number }> }>(
+    pullRequestsPath(repository, prId) + '/workItems',
+    { 'api-version': '7.1' },
+  );
+  return (verify.value ?? []).map((entry) => Number(entry.id)).filter((id) => Number.isInteger(id)).sort((a, b) => a - b);
+}
+
+function dedupeIntegers(list: readonly number[]): number[] {
+  const seen = new Set<number>();
+  const out: number[] = [];
+  for (const value of list) {
+    if (!Number.isInteger(value) || value <= 0) {
+      throw new Error(`work-item ids must be positive integers`);
+    }
+    if (seen.has(value)) continue;
+    seen.add(value);
+    out.push(value);
+  }
+  return out;
+}
+
 export function assertPrSourceBranch(source: string | undefined): asserts source is string {
   if (!source) throw new Error('could not determine the current branch; run from the repository checkout');
   if (source === 'HEAD') throw new Error('this checkout is in detached HEAD state; check out a branch first');
-  if (source === PR_TARGET_BRANCH) throw new Error(`already on ${PR_TARGET_BRANCH}; create a feature branch first`);
-  if (source === 'main') throw new Error(`a pull request is never opened from main; open a branch into ${PR_TARGET_BRANCH}`);
+  const target = PR_TARGET_BRANCH;
+  if (source === target) throw new Error(`already on ${target}; create a feature branch first`);
+  if (source === 'main') throw new Error(`a pull request is never opened from main; open a branch into ${target}`);
 }
 
 /**
@@ -344,7 +497,9 @@ export async function prCreateOrUpdate(args: PrCreateOrUpdateArgs): Promise<stri
   const repository = resolveRepository(args.repository);
 
   if (args.id) {
-    const { id, title, description, autoComplete, mergeStrategy, deleteSourceBranch } = args;
+    const { id, title, description, autoComplete, mergeStrategy, deleteSourceBranch, addWorkItems, removeWorkItems } = args;
+    const prId = Number(id);
+    const hasWorkItemChange = (addWorkItems?.length ?? 0) > 0 || (removeWorkItems?.length ?? 0) > 0;
 
     assertValidUpdateMetadata(title, description)
 
@@ -370,10 +525,31 @@ export async function prCreateOrUpdate(args: PrCreateOrUpdateArgs): Promise<stri
       Object.assign(body, autoCompleteBody(existing.createdBy?.id ?? ''))
     }
 
-    if (Object.keys(body).length === 0) {
+    if (Object.keys(body).length === 0 && !hasWorkItemChange) {
       throw new Error('update requires title, description, or completion options');
     }
 
+    if (hasWorkItemChange) {
+      // P5: post-create mutability of the PR's work-items relation. Runs even
+      // when no metadata changes are present, so an ordinary PR whose source
+      // branch name does not match any of the three branch-name regexes still
+      // has a way to be wired. The flag path replaces workItemRefs at create
+      // for ordinary PRs (and complements it for implementation/planning).
+      const linked = await updatePrWorkItemLinks(c, prId, {
+        add: addWorkItems ?? [],
+        remove: removeWorkItems ?? [],
+      });
+      if (Object.keys(body).length === 0) {
+        return JSON.stringify({ pullRequestId: prId, workItems: linked, summary: 'work-items relation updated; no PR metadata changed' }, null, 2);
+      }
+      const pr = await c.patch<any>(
+        pullRequestsPath(repository, id),
+        body,
+        { 'api-version': '7.1' }
+      );
+      return JSON.stringify({ ...pr, workItems: linked, summary: 'PR metadata and work-items relation updated' }, null, 2);
+    }
+
     const pr = await c.patch<any>(
       pullRequestsPath(repository, id),
       body,