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

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

@@ -3,10 +3,11 @@
 // repo invoked this file as a CLI; see mcp-server.ts's runTool() history).
 import {
   validatePullRequestDescription,
-  validatePullRequestMetadata,
   validatePullRequestTitle,
 } from './lib/validate-pr-metadata.ts'
 import { AdoClient, PR_TARGET_BRANCH, adoProjectUrl, currentBranch, resolveRepository } from './lib/client.ts';
+import { uploadAttachment } from './azdo-attachments.ts';
+import { evaluateWorkflowTransition, formatWorkflowRefusal } from './workflow-rules.ts';
 
 let client: AdoClient | undefined
 
@@ -21,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}`;
 }
 
 /**
@@ -34,17 +35,22 @@ export function pullRequestWebUrl(repository: string, pullRequestId: number | st
  * the call succeeded, the tool reported success, and the PR stayed unarmed.
  * That silent no-op is why this is a named function with its own test rather
  * than an object literal at the call site.
+ *
+ * P2: `completionOptions.transitionWorkItems` is set by PR kind — true only
+ * for implementation and Fixes Bug PRs, where ADO moves the linked items to
+ * Done when the PR merges into integration (planning and ordinary PRs move
+ * nothing on merge).
  */
-export function autoCompleteBody(identityId: string): {
+export function autoCompleteBody(identityId: string, transitionWorkItems = false): {
   autoCompleteSetBy: { id: string }
-  completionOptions: { mergeStrategy: string; deleteSourceBranch: boolean }
+  completionOptions: { mergeStrategy: string; deleteSourceBranch: boolean; transitionWorkItems: boolean }
 } {
   if (!identityId) {
     throw new Error('cannot arm auto-complete: no identity to attribute it to')
   }
   return {
     autoCompleteSetBy: { id: identityId },
-    completionOptions: { mergeStrategy: 'squash', deleteSourceBranch: true },
+    completionOptions: { mergeStrategy: 'squash', deleteSourceBranch: true, transitionWorkItems },
   }
 }
 
@@ -121,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);
   }
 
@@ -147,8 +167,11 @@ export async function prListOrGet(args: PrListOrGetArgs): Promise<string> {
   return JSON.stringify(prs, null, 2);
 }
 
-function assertValidCreateMetadata(title: string, description: string) {
-  const metadataErrors = validatePullRequestMetadata(title, description)
+function assertValidCreateMetadata(title: string, description: string, docsOnlySections: boolean) {
+  const metadataErrors = [
+    ...validatePullRequestTitle(title),
+    ...validatePullRequestDescription(description, { docsOnlySections }),
+  ]
   if (metadataErrors.length === 0) return
   throw new Error(metadataErrors.map((error) => `pr-policy: FAIL — ${error}`).join('\n'))
 }
@@ -169,6 +192,12 @@ export type PrCreateOrUpdateArgs = {
   autoComplete?: boolean;
   mergeStrategy?: string;
   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. */
@@ -177,15 +206,272 @@ 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}`);
+}
+
+/**
+ * P1: the PR kind comes from the source branch naming a work item
+ * (azdo-git-process.md § PRs). `docs/az<id>-<slug>-plan` is a planning PR;
+ * `fix/az<bug id>-<slug>` is a Fixes Bug implementation PR naming one Bug;
+ * any other `<type>/az<id>-<slug>` branch names a Feature and is an
+ * implementation PR. Anything else is ordinary. The kind can still fall
+ * back to ordinary when the board holds no item in a wireable state.
+ */
+export type PrKind = 'planning' | 'implementation' | 'ordinary';
+
+export interface PrKindTarget {
+  kind: PrKind;
+  /** The work item the branch names (undefined for ordinary). */
+  itemId?: number;
+  itemType?: 'Feature' | 'Bug';
+}
+
+const PLANNING_BRANCH = /^docs\/az(\d+)-[a-z0-9-]+-plan$/;
+const FIXES_BUG_BRANCH = /^fix\/az(\d+)-[a-z0-9-]+$/;
+const FEATURE_BRANCH = /^(?:feat|chore|docs|perf|refactor)\/az(\d+)-[a-z0-9-]+$/;
+
+export function derivePrKind(sourceBranch: string): PrKindTarget {
+  const planning = PLANNING_BRANCH.exec(sourceBranch);
+  if (planning) return { kind: 'planning', itemId: Number(planning[1]), itemType: 'Feature' };
+  const fixes = FIXES_BUG_BRANCH.exec(sourceBranch);
+  if (fixes) return { kind: 'implementation', itemId: Number(fixes[1]), itemType: 'Bug' };
+  const feature = FEATURE_BRANCH.exec(sourceBranch);
+  if (feature) return { kind: 'implementation', itemId: Number(feature[1]), itemType: 'Feature' };
+  return { kind: 'ordinary' };
+}
+
+/** The board states P1 wires, per kind. Done is never wired (terminal); neither are the parked/removed states. */
+const PLANNING_WIREABLE: ReadonlySet<string> = new Set(['In Planning']);
+const PBI_IMPLEMENTATION_WIREABLE: ReadonlySet<string> = new Set(['Approved', 'Design Validation', 'In Implementation', 'In Testing', 'In Review', 'Updating Docs']);
+const BUG_IMPLEMENTATION_WIREABLE: ReadonlySet<string> = new Set(['Approved', 'In Reproduction', 'In Fixing', 'In Testing', 'In Review', 'Updating Docs']);
+
+/** P2's raise-time move targets: planning items → Awaiting Approval; loop items → Updating Docs. */
+const PBI_LOOP: ReadonlySet<string> = new Set(['In Implementation', 'In Testing', 'In Review', 'Updating Docs']);
+const BUG_LOOP: ReadonlySet<string> = new Set(['In Fixing', 'In Testing', 'In Review', 'Updating Docs']);
+
+export interface WiredItem {
+  id: number;
+  type: 'Product Backlog Item' | 'Bug';
+  state: string;
+}
+
+function relationIds(item: any, rel: string): number[] {
+  const relationId = (url: string) => Number(/(\d+)\/?$/.exec(url)?.[1]);
+  return (item.relations ?? [])
+    .filter((relation: any) => relation.rel === rel)
+    .map((relation: any) => relationId(relation.url))
+    .filter((id: number) => Number.isInteger(id));
+}
+
+/**
+ * P1: the items to wire, read from the board. Planning wires the Feature's
+ * in-scope items at In Planning; implementation wires the Feature's items
+ * (or the one Bug) at Approved or later. An empty result demotes the PR to
+ * ordinary — no links, no state moves, no attachment.
+ */
+export async function resolveWiredItems(c: AdoClient, target: PrKindTarget): Promise<WiredItem[]> {
+  if (target.itemId === undefined || target.itemType === undefined) return [];
+  const item = await c.get<any>(`/wit/workitems/${target.itemId}`, { 'api-version': '7.1', $expand: 'all' });
+  if (target.itemType === 'Bug') {
+    const state = item.fields?.['System.State'];
+    return BUG_IMPLEMENTATION_WIREABLE.has(state) ? [{ id: item.id, type: 'Bug', state }] : [];
+  }
+  const wireable = target.kind === 'planning' ? PLANNING_WIREABLE : PBI_IMPLEMENTATION_WIREABLE;
+  const childIds = relationIds(item, 'System.LinkTypes.Hierarchy-Forward');
+  if (!childIds.length) return [];
+  const batch = await c.post<any>('/wit/workitemsbatch', { ids: childIds, $expand: 'all' }, { 'api-version': '7.1' });
+  return (batch.value ?? [])
+    .filter((child: any) => ['Product Backlog Item', 'Bug'].includes(child.fields?.['System.WorkItemType']))
+    .filter((child: any) => wireable.has(child.fields?.['System.State']))
+    .map((child: any) => ({ id: child.id, type: child.fields['System.WorkItemType'], state: child.fields['System.State'] }));
+}
+
+/** P2's raise-time target state for one wired item, or undefined when the item stays where it is. */
+export function raiseMoveTarget(kind: PrKind, item: WiredItem): string | undefined {
+  if (kind === 'planning') return 'Awaiting Approval';
+  if (kind === 'implementation') {
+    const loop = item.type === 'Bug' ? BUG_LOOP : PBI_LOOP;
+    return loop.has(item.state) && item.state !== 'Updating Docs' ? 'Updating Docs' : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * P2: move the linked items themselves when the PR is raised. Every move is
+ * pre-checked against the workflow fence (the same rule an agent write
+ * faces) so a PR is never raised half-wired.
+ */
+async function moveWiredItems(c: AdoClient, kind: PrKind, items: WiredItem[]): Promise<void> {
+  for (const item of items) {
+    const to = raiseMoveTarget(kind, item);
+    if (to === undefined) continue;
+    const violations = evaluateWorkflowTransition(item.type, item.state, to);
+    if (violations.length) throw new Error(formatWorkflowRefusal(violations));
+    await c.patch<any>(
+      `/wit/workitems/${item.id}`,
+      [{ op: 'add', path: '/fields/System.State', value: to }],
+      { 'api-version': '7.1' },
+      'application/json-patch+json',
+    );
+  }
+}
+
+/**
+ * P4: the work item the mandatory attachment hangs off — the named Feature,
+ * or, for a Fixes Bug PR, its Fixes Feature (board-rules.md § Attachments).
+ * The file name is completed by the caller once the PR id exists.
+ */
+async function attachmentTargetWorkItemId(c: AdoClient, target: PrKindTarget): Promise<number> {
+  if (target.itemType === 'Bug') {
+    const bug = await c.get<any>(`/wit/workitems/${target.itemId}`, { 'api-version': '7.1', $expand: 'all' });
+    const [parentId] = relationIds(bug, 'System.LinkTypes.Hierarchy-Reverse');
+    if (parentId === undefined) throw new Error(`Fixes Bug ${target.itemId} has no parent Fixes Feature to attach the implementation report to (P4)`);
+    return parentId;
+  }
+  return target.itemId!;
 }
 
 /** The exact next steps returned after PR creation, including live-stage failure polling. */
-export function prCreateResult(repository: string, pullRequestId: number, title: string, status: string, autoComplete: boolean): Record<string, unknown> {
+export function prCreateResult(repository: string, pullRequestId: number, title: string, status: string, autoComplete: boolean, kind: PrKind = 'ordinary', wiredItems: number[] = []): Record<string, unknown> {
   const prRef = `refs/pull/${pullRequestId}/merge`;
   return {
     id: pullRequestId,
@@ -193,6 +479,8 @@ export function prCreateResult(repository: string, pullRequestId: number, title:
     status,
     url: pullRequestWebUrl(repository, pullRequestId),
     autoComplete,
+    kind,
+    workItems: wiredItems,
     summary: 'Creating this pull request started a validation build.',
     poll: [
       `1. build_list_or_get({ branch: '${prRef}' }) — take builds[0].id.`,
@@ -209,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)
 
@@ -235,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,
@@ -258,9 +569,42 @@ export async function prCreateOrUpdate(args: PrCreateOrUpdateArgs): Promise<stri
   assertPrSourceBranch(source);
   if (!title) throw new Error('title is required for create');
 
-  assertValidCreateMetadata(title, description)
-
   const c = await getClient()
+
+  // P1: derive the kind from the source branch AND the board. No item in a
+  // wireable state demotes the PR to ordinary — nothing links, moves or
+  // attaches (the intent.md PR is the standing example).
+  const kindTarget = derivePrKind(source);
+  const wired = kindTarget.kind === 'ordinary' ? [] : await resolveWiredItems(c, kindTarget);
+  const kind: PrKind = wired.length ? kindTarget.kind : 'ordinary';
+
+  // P3: a planning PR may write "none (docs-only)" in the last two sections.
+  assertValidCreateMetadata(title, description, kind === 'planning')
+
+  // P4: the agent supplies the mandatory attachment's content; a planning or
+  // implementation PR refuses to raise without it. The planning attachment's
+  // file name comes from the Feature's plan fields and is validated here,
+  // before any PR exists.
+  let planningAttachment: { workItemId: number; fileName: string } | undefined;
+  let implAttachmentTarget: number | undefined;
+  if (kind !== 'ordinary') {
+    if (args.attachmentContent === undefined || args.attachmentContent.trim() === '') {
+      const article = kind === 'implementation' ? 'an' : 'a';
+      throw new Error(`${article} ${kind} PR requires attachmentContent — the mandatory ${kind === 'planning' ? 'plan-r<N>-<sha7>.md plan attachment' : 'impl-report-pr<id>.md implementation report'} (P4); refusing to raise the PR without it`)
+    }
+    if (kind === 'planning') {
+      const feature = await c.get<any>(`/wit/workitems/${kindTarget.itemId}`, { 'api-version': '7.1' });
+      const revision = feature.fields?.['Custom.PlanRevision'];
+      const hash = feature.fields?.['Custom.PlanHash'];
+      if (typeof revision !== 'number' || typeof hash !== 'string' || !hash) {
+        throw new Error('a planning PR needs the Feature\'s Custom.PlanRevision and Custom.PlanHash to name the mandatory plan attachment (P4)')
+      }
+      planningAttachment = { workItemId: kindTarget.itemId!, fileName: `plan-r${revision}-${hash.slice(0, 7)}.md` };
+    } else {
+      implAttachmentTarget = await attachmentTargetWorkItemId(c, kindTarget);
+    }
+  }
+
   await assertBranchReadyForPr(c, repository, source, target)
   const body: any = {
     sourceRefName: `refs/heads/${source}`,
@@ -268,6 +612,9 @@ export async function prCreateOrUpdate(args: PrCreateOrUpdateArgs): Promise<stri
     title,
     description,
   };
+  // P1: link the wired items at create, as `az repos pr create --work-items`
+  // does through workItemRefs on the create body.
+  if (wired.length) body.workItemRefs = wired.map((item) => ({ id: item.id }));
 
   const pr = await c.post<any>(
     pullRequestsPath(repository),
@@ -275,15 +622,27 @@ export async function prCreateOrUpdate(args: PrCreateOrUpdateArgs): Promise<stri
     { 'api-version': '7.1' }
   );
 
+  // P2: the tool moves the linked items itself at raise — planning items to
+  // Awaiting Approval, loop items to Updating Docs. Implementation PRs also
+  // arm transitionWorkItems so ADO lands the linked items on Done at merge.
+  await moveWiredItems(c, kind, wired);
+
+  // P4: attach the mandatory Feature attachment now that the PR id exists.
+  if (planningAttachment) {
+    await uploadAttachment(c, planningAttachment.workItemId, planningAttachment.fileName, args.attachmentContent!);
+  } else if (implAttachmentTarget !== undefined) {
+    await uploadAttachment(c, implAttachmentTarget, `impl-report-pr${pr.pullRequestId}.md`, args.attachmentContent!);
+  }
+
   if (arm) {
     // The PR we just created was created BY us, so its `createdBy` is the
     // authenticated identity — no extra lookup needed to attribute the arming.
     await c.patch<any>(
       pullRequestsPath(repository, pr.pullRequestId),
-      autoCompleteBody(pr.createdBy?.id ?? ''),
+      autoCompleteBody(pr.createdBy?.id ?? '', kind === 'implementation'),
       { 'api-version': '7.1' }
     );
   }
 
-  return JSON.stringify(prCreateResult(repository, pr.pullRequestId, pr.title, pr.status, arm), null, 2);
+  return JSON.stringify(prCreateResult(repository, pr.pullRequestId, pr.title, pr.status, arm, kind, wired.map((item) => item.id)), null, 2);
 }