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

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
 
@@ -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 },
   }
 }
 
@@ -147,8 +153,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 +178,8 @@ 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;
   /** Overrides `AZURE_DEVOPS_REPO` for this call. */
   repository?: string;
   /** Rejected removed routing input; PRs always use the checked-out branch. */
@@ -184,8 +195,130 @@ export function assertPrSourceBranch(source: string | undefined): asserts source
   if (source === 'main') throw new Error(`a pull request is never opened from main; open a branch into ${PR_TARGET_BRANCH}`);
 }
 
+/**
+ * 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 +326,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.`,
@@ -258,9 +393,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 +436,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 +446,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);
 }