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

package/packages/azdo/src/cli.ts

@@ -3,7 +3,7 @@ import { dispatchTool, type ToolArguments } from './tool-dispatch.ts';
 type Option = {
   flag: string;
   key: string;
-  type: 'string' | 'integer' | 'integer-list' | 'json-object' | 'date' | 'boolean';
+  type: 'string' | 'integer' | 'number' | 'integer-list' | 'json-object' | 'date' | 'boolean';
   values?: readonly string[];
 };
 
@@ -46,6 +46,8 @@ const commands: readonly Command[] = [
       { flag: '--merge-strategy', key: 'mergeStrategy', type: 'string', values: ['Squash'] },
       { flag: '--delete-source-branch', key: 'deleteSourceBranch', type: 'boolean' },
       { flag: '--attachment-content', key: 'attachmentContent', type: 'string' },
+      { flag: '--add-work-items', key: 'addWorkItems', type: 'integer-list' },
+      { flag: '--remove-work-items', key: 'removeWorkItems', type: 'integer-list' },
       { flag: '--repository', key: 'repository', type: 'string' },
     ],
     validate: requirePullRequestWrite,
@@ -86,29 +88,76 @@ const commands: readonly Command[] = [
     options: [{ flag: '--id', key: 'id', type: 'integer' }, { flag: '--ids', key: 'ids', type: 'string' }, { flag: '--type', key: 'type', type: 'string', values: WORK_ITEM_TYPES }, { flag: '--state', key: 'state', type: 'string' }, { flag: '--assigned-to', key: 'assignedTo', type: 'string' }, { flag: '--limit', key: 'limit', type: 'integer' }, { flag: '--raw', key: 'raw', type: 'boolean' }],
   },
   {
-    name: 'workitem-create-or-update',
-    tool: 'workitem_create_or_update',
+    name: 'workitem-create-or-update-feature',
+    tool: 'workitem_create_or_update_feature',
     options: [
       { flag: '--id', key: 'id', type: 'integer' },
-      { flag: '--type', key: 'type', type: 'string', values: WORK_ITEM_TYPES },
       { flag: '--title', key: 'title', type: 'string' },
       { flag: '--description', key: 'description', type: 'string' },
       { flag: '--parent-id', key: 'parentId', type: 'integer' },
       { flag: '--predecessors', key: 'predecessors', type: 'integer-list' },
       { flag: '--related', key: 'related', type: 'integer-list' },
+      { flag: '--remove-predecessor', key: 'removePredecessor', type: 'integer' },
+      { flag: '--remove-related', key: 'removeRelated', type: 'integer' },
       { flag: '--fields', key: 'fields', type: 'json-object' },
       { flag: '--state', key: 'state', type: 'string' },
       { flag: '--comment', key: 'comment', type: 'string' },
       { flag: '--assigned-to', key: 'assignedTo', type: 'string' },
       { flag: '--acceptance-criteria', key: 'acceptanceCriteria', type: 'string' },
-      { flag: '--priority', key: 'priority', type: 'integer' },
+      { flag: '--priority', key: 'priority', type: 'integer', values: ['1', '2', '3', '4'] },
       { flag: '--start-date', key: 'startDate', type: 'date' },
       { flag: '--target-date', key: 'targetDate', type: 'date' },
       { flag: '--plan-revision', key: 'planRevision', type: 'integer' },
       { flag: '--plan-hash', key: 'planHash', type: 'string' },
       { flag: '--baseline-sha', key: 'baselineSha', type: 'string' },
     ],
-    validate: (args) => { if (args.id === undefined) requireKeys(args, ['type', 'title', 'parentId']); },
+    validate: (args) => { if (args.id === undefined) requireKeys(args, ['title', 'parentId', 'priority', 'description']); },
+  },
+  {
+    name: 'workitem-create-or-update-pbi',
+    tool: 'workitem_create_or_update_pbi',
+    options: [
+      { flag: '--id', key: 'id', type: 'integer' },
+      { flag: '--title', key: 'title', type: 'string' },
+      { flag: '--description', key: 'description', type: 'string' },
+      { flag: '--parent-id', key: 'parentId', type: 'integer' },
+      { flag: '--related', key: 'related', type: 'integer-list' },
+      { flag: '--remove-related', key: 'removeRelated', type: 'integer' },
+      { flag: '--fields', key: 'fields', type: 'json-object' },
+      { flag: '--state', key: 'state', type: 'string' },
+      { flag: '--comment', key: 'comment', type: 'string' },
+      { flag: '--assigned-to', key: 'assignedTo', type: 'string' },
+      { flag: '--acceptance-criteria', key: 'acceptanceCriteria', type: 'string' },
+      { flag: '--priority', key: 'priority', type: 'integer', values: ['1', '2', '3', '4'] },
+      { flag: '--effort', key: 'effort', type: 'number' },
+      { flag: '--start-date', key: 'startDate', type: 'date' },
+      { flag: '--target-date', key: 'targetDate', type: 'date' },
+    ],
+    validate: (args) => { if (args.id === undefined) requireKeys(args, ['title', 'parentId', 'description', 'effort']); },
+  },
+  {
+    name: 'workitem-create-or-update-bug',
+    tool: 'workitem_create_or_update_bug',
+    options: [
+      { flag: '--id', key: 'id', type: 'integer' },
+      { flag: '--title', key: 'title', type: 'string' },
+      { flag: '--description', key: 'description', type: 'string' },
+      { flag: '--parent-id', key: 'parentId', type: 'integer' },
+      { flag: '--predecessors', key: 'predecessors', type: 'integer-list' },
+      { flag: '--related', key: 'related', type: 'integer-list' },
+      { flag: '--remove-predecessor', key: 'removePredecessor', type: 'integer' },
+      { flag: '--remove-related', key: 'removeRelated', type: 'integer' },
+      { flag: '--fields', key: 'fields', type: 'json-object' },
+      { flag: '--state', key: 'state', type: 'string' },
+      { flag: '--comment', key: 'comment', type: 'string' },
+      { flag: '--assigned-to', key: 'assignedTo', type: 'string' },
+      { flag: '--acceptance-criteria', key: 'acceptanceCriteria', type: 'string' },
+      { flag: '--priority', key: 'priority', type: 'integer', values: ['1', '2', '3', '4'] },
+      { flag: '--effort', key: 'effort', type: 'number' },
+      { flag: '--start-date', key: 'startDate', type: 'date' },
+      { flag: '--target-date', key: 'targetDate', type: 'date' },
+    ],
+    validate: (args) => { if (args.id === undefined) requireKeys(args, ['title', 'parentId', 'description', 'effort']); },
   },
   {
     name: 'workitem-comments-read',
@@ -148,12 +197,14 @@ const help = `Usage: adl mcp cli <command> [options]
 
 Commands:
   pr-list-or-get [--id ID] [--status active|completed|abandoned|all] [--repository REPOSITORY]
-  pr-create-or-update --action create|update [--pull-request-id ID] [--title TITLE] [--description DESCRIPTION] [--auto-complete|--no-auto-complete] [--merge-strategy Squash] [--delete-source-branch] [--attachment-content TEXT] [--repository REPOSITORY]
+  pr-create-or-update --action create|update [--pull-request-id ID] [--title TITLE] [--description DESCRIPTION] [--auto-complete|--no-auto-complete] [--merge-strategy Squash] [--delete-source-branch] [--attachment-content TEXT] [--add-work-items ID[,ID...]] [--remove-work-items ID[,ID...]] [--repository REPOSITORY]
   pr-review --pull-request-id ID [--comment TEXT] [--vote approve|approve-with-suggestions|reset|wait-for-author|reject] [--target-branch BRANCH] [--repository REPOSITORY]
   build-list-or-get [--build-id ID] [--branch BRANCH] [--top N] [--tail N]
   build-run --id ID [--branch BRANCH]
   workitem-list-or-get [--id ID] [--ids IDS] [--type TYPE] [--state STATE] [--assigned-to IDENTITY] [--limit N] [--raw]
-  workitem-create-or-update [--id ID] [--type 'Feature'|'Product Backlog Item'|'Bug'] [--title TITLE] [--description DESCRIPTION] [--parent-id ID] [--predecessors ID[,ID...]] [--related ID[,ID...]] [--fields JSON_OBJECT] [--state STATE] [--comment TEXT] [--assigned-to IDENTITY] [--acceptance-criteria TEXT] [--priority N] [--start-date YYYY-MM-DD] [--target-date YYYY-MM-DD] [--plan-revision N] [--plan-hash SHA256] [--baseline-sha SHA]
+  workitem-create-or-update-feature [--id ID] --title TITLE --parent-id ID --priority 1|2|3|4 --description DESCRIPTION [--predecessors ID[,ID...]] [--related ID[,ID...]] [--remove-predecessor ID] [--remove-related ID] [--fields JSON_OBJECT] [--state STATE] [--comment TEXT] [--assigned-to IDENTITY] [--acceptance-criteria TEXT] [--start-date YYYY-MM-DD] [--target-date YYYY-MM-DD] [--plan-revision N] [--plan-hash SHA256] [--baseline-sha SHA]
+  workitem-create-or-update-pbi [--id ID] --title TITLE --parent-id ID --description DESCRIPTION --effort DAYS [--related ID[,ID...]] [--remove-related ID] [--fields JSON_OBJECT] [--state STATE] [--comment TEXT] [--assigned-to IDENTITY] [--acceptance-criteria TEXT] [--priority 1|2|3|4] [--start-date YYYY-MM-DD] [--target-date YYYY-MM-DD]
+  workitem-create-or-update-bug [--id ID] --title TITLE --parent-id ID --description DESCRIPTION --effort DAYS [--predecessors ID[,ID...]] [--related ID[,ID...]] [--remove-predecessor ID] [--remove-related ID] [--fields JSON_OBJECT] [--state STATE] [--comment TEXT] [--assigned-to IDENTITY] [--acceptance-criteria TEXT] [--priority 1|2|3|4] [--start-date YYYY-MM-DD] [--target-date YYYY-MM-DD]
   workitem-comments-read --id ID
   workitem-attachments --id ID --action read|upload|delete [--file-name NAME] [--content TEXT]
   activity-add --note TEXT
@@ -177,6 +228,12 @@ function requirePullRequestWrite(args: ToolArguments): void {
     if (args.deleteSourceBranch !== undefined) {
       throw new Error('--delete-source-branch is only valid for pr-create-or-update update');
     }
+    if (args.addWorkItems !== undefined) {
+      throw new Error('--add-work-items is only valid for pr-create-or-update update');
+    }
+    if (args.removeWorkItems !== undefined) {
+      throw new Error('--remove-work-items is only valid for pr-create-or-update update');
+    }
     requireKeys(args, ['title', 'description']);
     return;
   }
@@ -187,12 +244,16 @@ function requirePullRequestWrite(args: ToolArguments): void {
     throw new Error('--target-branch is not supported; PRs always target integration');
   }
   requireKeys(args, ['pullRequestId']);
+  const hasAdd = Array.isArray(args.addWorkItems) && (args.addWorkItems as unknown[]).length > 0;
+  const hasRemove = Array.isArray(args.removeWorkItems) && (args.removeWorkItems as unknown[]).length > 0;
   if (
     args.title === undefined &&
     args.description === undefined &&
     args.autoComplete !== true &&
     args.mergeStrategy === undefined &&
-    args.deleteSourceBranch !== true
+    args.deleteSourceBranch !== true &&
+    !hasAdd &&
+    !hasRemove
   ) {
     throw new Error('pr-create-or-update update requires metadata or completion options');
   }
@@ -250,9 +311,18 @@ function parseOptions(command: Command, tokens: readonly string[]): ToolArgument
     const value = tokens[index + 1];
     if (value === undefined || value.startsWith('--')) throw new Error(`Option requires a value: ${token}`);
     index += 1;
+    // An allowed-values list applies to every option that takes one, not just strings — `--priority 5` is refused here rather than at the board.
+    if (option.values && !option.values.includes(value)) {
+      throw new Error(`Invalid value for ${token}: ${value}; expected ${option.values.join(', ')}`);
+    }
     if (option.type === 'integer') {
       if (!/^[1-9][0-9]*$/.test(value)) throw new Error(`Option requires a positive integer: ${token}`);
       args[option.key] = Number(value);
+    } else if (option.type === 'number') {
+      // Effort is days: a fraction is a normal value, a negative is not.
+      const days = Number(value);
+      if (!Number.isFinite(days) || days < 0) throw new Error(`Option requires a non-negative number of days: ${token}`);
+      args[option.key] = days;
     } else if (option.type === 'integer-list') {
       args[option.key] = parsePositiveIntegerList(token, value);
     } else if (option.type === 'json-object') {
@@ -261,9 +331,6 @@ function parseOptions(command: Command, tokens: readonly string[]): ToolArgument
       args[option.key] = parseDate(token, value);
     } else {
       if (value.trim() === '') throw new Error(`Option requires a non-empty value: ${token}`);
-      if (option.values && !option.values.includes(value)) {
-        throw new Error(`Invalid value for ${token}: ${value}; expected ${option.values.join(', ')}`);
-      }
       if (option.key === 'ids') {
         args[option.key] = parsePositiveIntegerList('--ids', value);
       } else {

package/packages/azdo/src/lib/client.ts

@@ -15,18 +15,29 @@ export interface AdoClientConfig {
 }
 
 /**
- * The Azure DevOps organization and project every tool in this package
- * addresses, and the ONLY place their defaults are written.
+ * Azure DevOps organization, project and PR target are NEVER hardcoded.
+ * `resolveOrg` / `resolveProject` derive org and project at call time from
+ * the checkout's git remote (the canonical source of truth —
+ * `parseAzureRemote` reads `git remote get-url origin`) and throw with a
+ * "what is missing" message when the remote is not Azure-shaped.
+ * `PR_TARGET_BRANCH` is the one exception: every PR in this fleet opens
+ * into `integration` and `azdo-pr.ts`'s create path refuses any caller
+ * override, so it lives as a constant.
  *
- * `enact-webview` is a REPOSITORY inside the `Enact` project, not a project —
- * `azdo-wit.ts` used to default the project to it, so work-item calls hit a
- * different URL than the PR and build calls in the same process. Anything
- * needing these values imports from here rather than restating them.
+ * `enact-webview` is a REPOSITORY inside the live project, not a project —
+ * an earlier version of this file defaulted the project to it, so work-item
+ * calls hit a different URL than the PR and build calls in the same process.
+ * That drift is the bug the explicit-resolver shape is meant to prevent.
+ *
+ * `resolveRepository` keeps an `AZURE_DEVOPS_REPO` env leg as a test
+ * affordance: many existing tests in this package set the env var to drive
+ * the resolver without standing up a fixture. The production contract is
+ * the same as the rest — the git remote is the source of truth — but the
+ * env leg stays because removing it would cascade into ~14 test files. The
+ * test preload's `setTestDefaults` is the long-term replacement; the env leg
+ * can be retired when those tests are migrated to fixture-driven cwd
+ * arguments.
  */
-export const DEFAULT_ORG = 'amsterdamdatalabs';
-export const DEFAULT_PROJECT = 'Enact';
-/** The one PR target this opinionated tool opens against. */
-export const PR_TARGET_BRANCH = 'integration';
 
 /** Current checkout branch, or undefined when git cannot determine it. */
 export function currentBranch(cwd?: string): string | undefined {
@@ -99,6 +110,18 @@ export function parseAzureRemote(url: string): AzureRemote | null {
  * every tool call.
  */
 let remoteCache: AzureRemote | null | undefined;
+/** Test seam: forget the cached remote. The remote cannot change under a real run, but a test process running multiple files in the same bun test invocation sees the cached value from the first file that called `currentRemote()` without a cwd. */
+export function resetRemoteCacheForTests(): void {
+  remoteCache = undefined;
+}
+/** Test seam: install defaults that `resolveOrg` / `resolveProject` / `resolveRepository` use when no argument and no git remote are available. Real runs never call this — the working directory's git remote is the canonical source of truth. Tests call it once from a `bunfig.toml` preload so every test file inherits the same values without per-file boilerplate. */
+let testDefaults: AzureRemote | null = null;
+export function setTestDefaults(remote: AzureRemote): void {
+  testDefaults = remote;
+}
+export function resetTestDefaults(): void {
+  testDefaults = null;
+}
 export function currentRemote(cwd?: string): AzureRemote | null {
   if (cwd !== undefined) {
     const probe = spawnSync('git', ['remote', 'get-url', 'origin'], { cwd, encoding: 'utf8', timeout: 5000 });
@@ -110,14 +133,51 @@ export function currentRemote(cwd?: string): AzureRemote | null {
   return remoteCache;
 }
 
+/**
+ * Resolve the Azure DevOps organization. Order: env `AZURE_DEVOPS_ORG` →
+ * cwd's git remote → testDefaults → throw.
+ *
+ * The env leg is a test affordance: many existing tests in this package set
+ * `AZURE_DEVOPS_ORG` and `AZURE_DEVOPS_PROJECT` in `beforeAll` to drive the
+ * resolver against fixtures whose identity names are coupled to a specific
+ * project string (e.g. `'Enact Build Service (amsterdamdatalabs)'`).
+ * Production runs always hit the cwd branch; the env leg never fires
+ * because real runs never set it.
+ */
 export function resolveOrg(cwd?: string): string {
-  return configured(process.env.AZURE_DEVOPS_ORG) ?? currentRemote(cwd)?.org ?? DEFAULT_ORG;
+  const org = configured(process.env.AZURE_DEVOPS_ORG) ?? currentRemote(cwd)?.org ?? testDefaults?.org;
+  if (org !== undefined) return org;
+  throw new Error(
+    'Cannot determine the Azure DevOps organization: AZURE_DEVOPS_ORG is not set, ' +
+      'and `git remote get-url origin` in this working directory is not an Azure DevOps remote. ' +
+      'Set AZURE_DEVOPS_ORG or run from a checkout of the target repo.',
+  );
 }
 
+/**
+ * Resolve the Azure DevOps project. Order: env `AZURE_DEVOPS_PROJECT` →
+ * cwd's git remote → testDefaults → throw. See `resolveOrg` for why the env
+ * leg is preserved.
+ */
 export function resolveProject(cwd?: string): string {
-  return configured(process.env.AZURE_DEVOPS_PROJECT) ?? currentRemote(cwd)?.project ?? DEFAULT_PROJECT;
+  const project = configured(process.env.AZURE_DEVOPS_PROJECT) ?? currentRemote(cwd)?.project ?? testDefaults?.project;
+  if (project !== undefined) return project;
+  throw new Error(
+    'Cannot determine the Azure DevOps project: AZURE_DEVOPS_PROJECT is not set, ' +
+      'and `git remote get-url origin` in this working directory is not an Azure DevOps remote. ' +
+      'Set AZURE_DEVOPS_PROJECT or run from a checkout of the target repo.',
+  );
 }
 
+/**
+ * The branch a PR is opened against. Every PR in this fleet targets
+ * `integration` so promotion through G2 is uniform; `azdo-pr.ts`'s create
+ * path enforces this by rejecting any caller-supplied `targetBranch`
+ * argument before the body is built. This is a design rule, not a value
+ * resolved at runtime, so it lives as a constant.
+ */
+export const PR_TARGET_BRANCH = 'integration';
+
 /**
  * Which repository a call addresses: the explicit per-call argument first (one
  * session can span repos), then `AZURE_DEVOPS_REPO` as an override, then the
@@ -135,10 +195,18 @@ export function resolveProject(cwd?: string): string {
  * writing somewhere real.
  */
 export function resolveRepository(repository?: string, cwd?: string): string {
-  const resolved = configured(repository) ?? configured(process.env.AZURE_DEVOPS_REPO) ?? currentRemote(cwd)?.repository;
+  // Order: explicit argument > AZURE_DEVOPS_REPO env > cwd's git remote > testDefaults > throw.
+  // The AZURE_DEVOPS_REPO env leg is a test affordance: many existing tests in
+  // this package set the env var to drive the resolver without standing up a
+  // fixture. The production contract is the same as the rest — the git remote
+  // is the source of truth — but the env leg stays because removing it would
+  // cascade into ~14 test files. The test preload's testDefaults is the
+  // long-term replacement; the env leg can be retired when those tests are
+  // migrated to fixture-driven cwd arguments.
+  const resolved = configured(repository) ?? configured(process.env.AZURE_DEVOPS_REPO) ?? currentRemote(cwd)?.repository ?? testDefaults?.repository;
   if (resolved === undefined) {
     throw new Error(
-      'Cannot determine the Azure DevOps repository: no `repository` argument, no AZURE_DEVOPS_REPO, ' +
+      'Cannot determine the Azure DevOps repository: no `repository` argument, ' +
         'and `git remote get-url origin` in this working directory is not an Azure DevOps remote. ' +
         'Pass `repository` explicitly or run from a checkout of the target repo.',
     );
@@ -151,9 +219,13 @@ export function resolveRepository(repository?: string, cwd?: string): string {
  * segments are written. The REST base appends `/_apis`; human-facing links
  * append `/_git/...`. Two builders restating this shape can disagree about
  * where a project lives just as easily as two default constants could.
+ *
+ * `cwd` is the test seam: pass the path of a fixture whose `origin` is the
+ * URL under test. Production callers omit it and resolve against this
+ * process's own working directory.
  */
-export function adoProjectUrl(): string {
-  return `https://dev.azure.com/${resolveOrg()}/${resolveProject()}`;
+export function adoProjectUrl(cwd?: string): string {
+  return `https://dev.azure.com/${resolveOrg(cwd)}/${resolveProject(cwd)}`;
 }
 
 export class AdoClient {

package/packages/azdo/src/mcp-server.ts

@@ -29,7 +29,7 @@ import {
 import pkg from '../package.json' with { type: 'json' };
 
 /**
- * Builds a fresh, unconnected `Server` with the 12 public tools registered.
+ * Builds a fresh, unconnected `Server` with the 14 public tools registered.
  * Called by `runMcpServer()` below; also usable directly by tests that want
  * to drive the server without stdio (e.g. via an in-memory transport).
  */
@@ -62,7 +62,7 @@ export function createServer(): Server {
       },
       {
         name: 'pr_create_or_update',
-        description: 'Create a pull request from the current branch into integration, or update a pull request. The create path derives the PR kind from the source branch and the board (planning / implementation / ordinary), links the wireable work items, moves them at raise, attaches the kind\'s mandatory Feature attachment (attachmentContent) and arms auto-complete with the matching transitionWorkItems. The body must contain non-empty ## Summary, ## Why, ## Changes, ## Test plan and ## Security impact considered sections (a planning PR may write "none (docs-only)" in the last two).',
+        description: 'Create a pull request from the current branch into integration, or update a pull request. The create path derives the PR kind from the source branch and the board (planning / implementation / ordinary), links the wireable work items, moves them at raise, attaches the kind\'s mandatory Feature attachment (attachmentContent) and arms auto-complete with the matching transitionWorkItems. The update path also accepts addWorkItems / removeWorkItems (update only, P5) — the only way to attach work items to a PR raised as kind: ordinary after the create call. The body must contain non-empty ## Summary, ## Why, ## Changes, ## Test plan and ## Security impact considered sections (a planning PR may write "none (docs-only)" in the last two).',
         inputSchema: {
           type: 'object',
           properties: {
@@ -74,6 +74,8 @@ export function createServer(): Server {
             mergeStrategy: { type: 'string', enum: ['Squash'] },
             deleteSourceBranch: { type: 'boolean' },
             attachmentContent: { type: 'string', description: 'Create only: the content of the kind\'s mandatory Feature attachment (plan-r<N>-<sha7>.md or impl-report-pr<id>.md); refused without it on planning/implementation PRs' },
+            addWorkItems: { type: 'array', items: { type: 'number' }, description: 'P5 update only: positive integer ids to link to the PR. For each id, JSON-PATCH `add /relations/-` against `/_apis/wit/workitems/{id}?api-version=7.1` with `application/json-patch+json` and an `ArtifactLink` of rel `Pull Request` pointing at `vstfs:///Git/PullRequestId/{projectId}%2F{repoId}%2F{prId}`. The relation is read back through `GET .../pullRequests/{prId}/workItems`. An id already linked is skipped (idempotent). An id in both addWorkItems and removeWorkItems is rejected (no PATCH issued).' },
+            removeWorkItems: { type: 'array', items: { type: 'number' }, description: 'P5 update only: positive integer ids to unlink from the PR. JSON-PATCH `remove /relations/{index}` against the work item, where {index} is the position of the matching `ArtifactLink` (matched by url). An id in both addWorkItems and removeWorkItems is rejected (no PATCH issued).' },
             repository: { type: 'string', description: 'Repository name; defaults to AZURE_DEVOPS_REPO' },
           },
           required: ['action'],
@@ -125,7 +127,7 @@ export function createServer(): Server {
       },
       {
         name: 'workitem_list_or_get',
-        description: 'Get one or many tracked work items, or query the scoped backlog. Each item carries effort, failureReason and the Feature plan fields planRevision, planHash and baselineSha (all null when unset).',
+        description: 'Get one or many tracked work items, or query the scoped backlog. Each item carries effort, priority, acceptanceCriteria, failureReason and the Feature plan fields planRevision, planHash and baselineSha (all null when unset).',
         inputSchema: {
           type: 'object',
           properties: {
@@ -134,17 +136,80 @@ export function createServer(): Server {
         },
       },
       {
-        name: 'workitem_create_or_update',
-        description: 'Create a tracked work item under its required parent, or update an existing item. The plan fields (planRevision, planHash, baselineSha) are Feature-only and map to the Custom.PlanRevision / Custom.PlanHash / Custom.BaselineSha process fields.',
+        name: 'workitem_create_or_update_feature',
+        description: "Create a Feature under an Epic, or update an existing Feature. Mandatory: title, parentId (an Epic), priority (1=Very High, 2=High, 3=Medium, 4=Low) and a description carrying the intent.md sections Why / Outcome / Constraints / Non-goals — on create and while the Feature is at New; acceptanceCriteria (itemised per requirements.md) plus the three plan fields on the New → In Progress move; a comment on every update. Features are created only at New.",
         inputSchema: {
           type: 'object',
           properties: {
-            id: { type: 'number' }, type: { type: 'string', enum: ['Feature', 'Product Backlog Item', 'Bug'] },
+            id: { type: 'number' },
+            title: { type: 'string' },
+            description: { type: 'string', description: 'Must carry the intent.md sections ## Why, ## Outcome, ## Constraints, ## Non-goals' },
+            parentId: { type: 'number', description: 'The Epic this Feature hangs under' },
+            predecessors: { type: 'array', items: { type: 'number' } },
+            related: { type: 'array', items: { type: 'number' } },
+            removePredecessor: { type: 'number', description: 'az698: drop a single predecessor link by id; idempotent on a missing link. Update path only.' },
+            removeRelated: { type: 'number', description: 'az698: drop a single related link by id; idempotent on a missing link. Update path only.' },
+            fields: { type: 'object' },
+            state: { type: 'string' },
+            comment: { type: 'string', description: 'Mandatory on every update' },
+            assignedTo: { type: 'string' },
+            acceptanceCriteria: { type: 'string', description: 'Required on the New → In Progress move, itemised per requirements.md' },
+            priority: { type: 'number', enum: [1, 2, 3, 4], description: '1=Very High, 2=High, 3=Medium, 4=Low (Microsoft.VSTS.Common.Priority)' },
+            startDate: { type: 'string' },
+            targetDate: { type: 'string' },
+            planRevision: { type: 'number', description: 'Required on the New → In Progress move: which plan revision G1 approves (Custom.PlanRevision)' },
+            planHash: { type: 'string', description: 'Required on the New → In Progress move: sha256 of requirements.md (Custom.PlanHash)' },
+            baselineSha: { type: 'string', description: 'Required on the New → In Progress move: the integration commit the plan was written against (Custom.BaselineSha)' },
+          },
+        },
+      },
+      {
+        name: 'workitem_create_or_update_pbi',
+        description: "Create a PBI (Product Backlog Item) under a Feature, or update an existing PBI. Mandatory on create: title, parentId (a Feature), a description carrying the item file's What it delivers / Verification sections, and effort in days. A comment is mandatory on every update. Predecessor links are refused as a staged warning (L3); the Feature plan fields do not exist on a PBI.",
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: { type: 'number' },
+            title: { type: 'string' },
+            description: { type: 'string', description: "Must carry the item file's sections ## What it delivers and ## Verification" },
+            parentId: { type: 'number', description: 'The Feature this PBI hangs under' },
+            related: { type: 'array', items: { type: 'number' } },
+            removeRelated: { type: 'number', description: 'az698: drop a single related link by id; idempotent on a missing link. Update path only.' },
+            fields: { type: 'object' },
+            state: { type: 'string' },
+            comment: { type: 'string', description: 'Mandatory on every update' },
+            assignedTo: { type: 'string' },
+            acceptanceCriteria: { type: 'string' },
+            priority: { type: 'number', enum: [1, 2, 3, 4], description: '1=Very High, 2=High, 3=Medium, 4=Low' },
+            effort: { type: 'number', description: 'Mandatory on create: engineering days, >= 0, fractions accepted (Microsoft.VSTS.Scheduling.Effort)' },
+            startDate: { type: 'string' },
+            targetDate: { type: 'string' },
+          },
+        },
+      },
+      {
+        name: 'workitem_create_or_update_bug',
+        description: "Create a Bug under a Feature, or update an existing Bug. Mandatory on create: title, parentId (a Feature — usually a 'Fixes to closed Features' container), a description carrying the bug item file's Current behaviour / Expected behaviour / Behaviour that must not change / Responsible Feature / Verification sections, and effort in days. A Bug under the Fixes Feature also needs a related link to its Responsible Feature and a predecessor that is a sibling Bug (L4). A comment is mandatory on every update.",
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: { type: 'number' },
             title: { type: 'string' },
-            description: { type: 'string' }, parentId: { type: 'number' }, predecessors: { type: 'array', items: { type: 'number' } }, related: { type: 'array', items: { type: 'number' } }, fields: { type: 'object' }, state: { type: 'string' }, comment: { type: 'string' }, assignedTo: { type: 'string' }, acceptanceCriteria: { type: 'string' }, priority: { type: 'number' }, startDate: { type: 'string' }, targetDate: { type: 'string' },
-            planRevision: { type: 'number', description: 'Feature only: which plan revision G1 approves (Custom.PlanRevision)' },
-            planHash: { type: 'string', description: 'Feature only: sha256 of requirements.md (Custom.PlanHash)' },
-            baselineSha: { type: 'string', description: 'Feature only: the integration commit the plan was written against (Custom.BaselineSha)' },
+            description: { type: 'string', description: "Must carry the bug item file's sections ## Current behaviour, ## Expected behaviour, ## Behaviour that must not change, ## Responsible Feature, ## Verification" },
+            parentId: { type: 'number', description: 'The Feature this Bug hangs under' },
+            predecessors: { type: 'array', items: { type: 'number' }, description: 'At most one, and only a sibling Bug under a Fixes Feature (L4)' },
+            related: { type: 'array', items: { type: 'number' }, description: 'Required under a Fixes Feature: the Responsible Feature (L4)' },
+            removePredecessor: { type: 'number', description: 'az698: drop a single predecessor link by id; idempotent on a missing link. Update path only.' },
+            removeRelated: { type: 'number', description: 'az698: drop a single related link by id; idempotent on a missing link. Update path only.' },
+            fields: { type: 'object' },
+            state: { type: 'string' },
+            comment: { type: 'string', description: 'Mandatory on every update' },
+            assignedTo: { type: 'string' },
+            acceptanceCriteria: { type: 'string' },
+            priority: { type: 'number', enum: [1, 2, 3, 4], description: '1=Very High, 2=High, 3=Medium, 4=Low' },
+            effort: { type: 'number', description: 'Mandatory on create: engineering days, >= 0, fractions accepted (Microsoft.VSTS.Scheduling.Effort)' },
+            startDate: { type: 'string' },
+            targetDate: { type: 'string' },
           },
         },
       },

package/packages/azdo/src/tool-dispatch.ts

@@ -10,7 +10,7 @@ import { prReview, VOTE_NAMES, type PrReviewArgs, type VoteName } from './azdo-p
 import { buildListOrGet, buildRun } from './azdo-pl.ts';
 import { workitemAttachments } from './azdo-attachments.ts';
 import { activityAdd, activityList } from './activity-log.ts';
-import { workitemCommentsRead, workitemCreateOrUpdate, workitemListOrGet } from './azdo-wit.ts';
+import { workitemCommentsRead, workitemCreateOrUpdateBug, workitemCreateOrUpdateFeature, workitemCreateOrUpdatePbi, workitemListOrGet, type WorkItemWriteArgs } from './azdo-wit.ts';
 
 type PullRequestWriteArguments = {
   action?: unknown;
@@ -21,6 +21,8 @@ type PullRequestWriteArguments = {
   mergeStrategy?: unknown;
   deleteSourceBranch?: unknown;
   attachmentContent?: unknown;
+  addWorkItems?: unknown;
+  removeWorkItems?: unknown;
   repository?: unknown;
   sourceBranch?: unknown;
   targetBranch?: unknown;
@@ -48,12 +50,16 @@ export function pullRequestWriteArgs(args: PullRequestWriteArguments): PrCreateO
     if (!Number.isInteger(args.pullRequestId)) errors.push('pullRequestId is required for update');
     if (typeof args.title === 'string') errors.push(...validatePullRequestTitle(args.title));
     if (typeof args.description === 'string') errors.push(...validatePullRequestDescription(args.description));
+    const hasAdd = Array.isArray(args.addWorkItems) && (args.addWorkItems as unknown[]).length > 0;
+    const hasRemove = Array.isArray(args.removeWorkItems) && (args.removeWorkItems as unknown[]).length > 0;
     if (
       args.title === undefined &&
       args.description === undefined &&
       args.autoComplete !== true &&
       args.mergeStrategy === undefined &&
-      args.deleteSourceBranch !== true
+      args.deleteSourceBranch !== true &&
+      !hasAdd &&
+      !hasRemove
     ) {
       errors.push('update requires metadata or completion options');
     }
@@ -64,6 +70,12 @@ export function pullRequestWriteArgs(args: PullRequestWriteArguments): PrCreateO
   if (args.attachmentContent !== undefined && typeof args.attachmentContent !== 'string') {
     errors.push('attachmentContent must be a string');
   }
+  if (args.addWorkItems !== undefined && (!Array.isArray(args.addWorkItems) || (args.addWorkItems as unknown[]).some((value) => !Number.isInteger(value)))) {
+    errors.push('addWorkItems must be an array of integers');
+  }
+  if (args.removeWorkItems !== undefined && (!Array.isArray(args.removeWorkItems) || (args.removeWorkItems as unknown[]).some((value) => !Number.isInteger(value)))) {
+    errors.push('removeWorkItems must be an array of integers');
+  }
   if (errors.length > 0) throw new Error(`Invalid pull request write:\n- ${errors.join('\n- ')}`);
 
   return {
@@ -76,6 +88,8 @@ export function pullRequestWriteArgs(args: PullRequestWriteArguments): PrCreateO
     ...(args.mergeStrategy === 'Squash' ? { mergeStrategy: args.mergeStrategy } : {}),
     ...(args.deleteSourceBranch === true ? { deleteSourceBranch: true } : {}),
     ...(typeof args.attachmentContent === 'string' ? { attachmentContent: args.attachmentContent } : {}),
+    ...(Array.isArray(args.addWorkItems) ? { addWorkItems: args.addWorkItems as number[] } : {}),
+    ...(Array.isArray(args.removeWorkItems) ? { removeWorkItems: args.removeWorkItems as number[] } : {}),
     ...(typeof args.repository === 'string' ? { repository: args.repository } : {}),
   };
 }
@@ -123,6 +137,33 @@ export function pullRequestReviewArgs(args: PullRequestReviewArguments): PrRevie
 
 export type ToolArguments = Record<string, unknown>;
 
+/** The three per-type work-item write tools take the same arguments — only the
+ *  name differs — so the raw MCP/CLI arguments are narrowed once, here. */
+function workItemWriteArgs(args: ToolArguments): WorkItemWriteArgs {
+  return {
+    ...(Number.isInteger(args.id) ? { id: args.id as number } : {}),
+    ...(typeof args.title === 'string' ? { title: args.title } : {}),
+    ...(typeof args.description === 'string' ? { description: args.description } : {}),
+    ...(Number.isInteger(args.parentId) ? { parentId: args.parentId as number } : {}),
+    ...(Array.isArray(args.predecessors) ? { predecessors: args.predecessors as number[] } : {}),
+    ...(Array.isArray(args.related) ? { related: args.related as number[] } : {}),
+    ...(args.fields && typeof args.fields === 'object' && !Array.isArray(args.fields) ? { fields: args.fields as Record<string, unknown> } : {}),
+    ...(typeof args.state === 'string' ? { state: args.state } : {}),
+    ...(typeof args.comment === 'string' ? { comment: args.comment } : {}),
+    ...(typeof args.assignedTo === 'string' ? { assignedTo: args.assignedTo } : {}),
+    ...(typeof args.acceptanceCriteria === 'string' ? { acceptanceCriteria: args.acceptanceCriteria } : {}),
+    ...(Number.isInteger(args.priority) ? { priority: args.priority as number } : {}),
+    ...(typeof args.effort === 'number' ? { effort: args.effort } : {}),
+    ...(typeof args.startDate === 'string' ? { startDate: args.startDate } : {}),
+    ...(typeof args.targetDate === 'string' ? { targetDate: args.targetDate } : {}),
+    ...(Number.isInteger(args.planRevision) ? { planRevision: args.planRevision as number } : {}),
+    ...(typeof args.planHash === 'string' ? { planHash: args.planHash } : {}),
+    ...(typeof args.baselineSha === 'string' ? { baselineSha: args.baselineSha } : {}),
+    ...(Number.isInteger(args.removePredecessor) ? { removePredecessor: args.removePredecessor as number } : {}),
+    ...(Number.isInteger(args.removeRelated) ? { removeRelated: args.removeRelated as number } : {}),
+  };
+}
+
 function assertString(args: ToolArguments, key: string, allowNumber = false): void {
   const value = args[key];
   if (value !== undefined && typeof value !== 'string' && !(allowNumber && typeof value === 'number')) {
@@ -142,12 +183,21 @@ function validateToolArguments(name: string, args: ToolArguments): void {
   switch (name) {
     case 'build_list_or_get': ['buildId', 'top', 'tail'].forEach((key) => assertString(args, key, true)); assertString(args, 'branch'); return;
     case 'build_run': assertString(args, 'id', true); assertString(args, 'branch'); return;
+    case 'pr_create_or_update':
+      ['pullRequestId'].forEach((key) => assertInteger(args, key));
+      ['addWorkItems', 'removeWorkItems'].forEach((key) => assertIntegerArray(args, key));
+      return;
     case 'workitem_list_or_get':
       ['id', 'limit'].forEach((key) => assertInteger(args, key)); assertIntegerArray(args, 'ids');
       ['type', 'state', 'assignedTo'].forEach((key) => assertString(args, key)); assertBoolean(args, 'raw'); return;
-    case 'workitem_create_or_update':
-      ['id', 'parentId', 'priority', 'planRevision'].forEach((key) => assertInteger(args, key)); ['predecessors', 'related'].forEach((key) => assertIntegerArray(args, key));
-      ['type', 'title', 'description', 'state', 'comment', 'assignedTo', 'acceptanceCriteria', 'startDate', 'targetDate', 'planHash', 'baselineSha'].forEach((key) => assertString(args, key));
+    case 'workitem_create_or_update_feature':
+    case 'workitem_create_or_update_pbi':
+    case 'workitem_create_or_update_bug':
+      ['id', 'parentId', 'priority', 'planRevision', 'removePredecessor', 'removeRelated'].forEach((key) => assertInteger(args, key));
+      ['predecessors', 'related'].forEach((key) => assertIntegerArray(args, key));
+      ['title', 'description', 'state', 'comment', 'assignedTo', 'acceptanceCriteria', 'startDate', 'targetDate', 'planHash', 'baselineSha'].forEach((key) => assertString(args, key));
+      // Effort is days and accepts fractions, so it is a plain number, not an integer.
+      if (args.effort !== undefined && typeof args.effort !== 'number') throw new Error('effort must be a number (days)');
       if (args.fields !== undefined && (typeof args.fields !== 'object' || args.fields === null || Array.isArray(args.fields))) throw new Error('fields must be an object');
       return;
     case 'workitem_comments_read':
@@ -202,27 +252,12 @@ export async function dispatchTool(name: string, args: ToolArguments = {}): Prom
         ...(Number.isInteger(args.limit) ? { limit: args.limit as number } : {}),
         ...(typeof args.raw === 'boolean' ? { raw: args.raw } : {}),
       });
-    case 'workitem_create_or_update':
-      return workitemCreateOrUpdate({
-        ...(Number.isInteger(args.id) ? { id: args.id as number } : {}),
-        ...(typeof args.type === 'string' ? { type: args.type } : {}),
-        ...(typeof args.title === 'string' ? { title: args.title } : {}),
-        ...(typeof args.description === 'string' ? { description: args.description } : {}),
-        ...(Number.isInteger(args.parentId) ? { parentId: args.parentId as number } : {}),
-        ...(Array.isArray(args.predecessors) ? { predecessors: args.predecessors as number[] } : {}),
-        ...(Array.isArray(args.related) ? { related: args.related as number[] } : {}),
-        ...(args.fields && typeof args.fields === 'object' && !Array.isArray(args.fields) ? { fields: args.fields as Record<string, unknown> } : {}),
-        ...(typeof args.state === 'string' ? { state: args.state } : {}),
-        ...(typeof args.comment === 'string' ? { comment: args.comment } : {}),
-        ...(typeof args.assignedTo === 'string' ? { assignedTo: args.assignedTo } : {}),
-        ...(typeof args.acceptanceCriteria === 'string' ? { acceptanceCriteria: args.acceptanceCriteria } : {}),
-        ...(Number.isInteger(args.priority) ? { priority: args.priority as number } : {}),
-        ...(typeof args.startDate === 'string' ? { startDate: args.startDate } : {}),
-        ...(typeof args.targetDate === 'string' ? { targetDate: args.targetDate } : {}),
-        ...(Number.isInteger(args.planRevision) ? { planRevision: args.planRevision as number } : {}),
-        ...(typeof args.planHash === 'string' ? { planHash: args.planHash } : {}),
-        ...(typeof args.baselineSha === 'string' ? { baselineSha: args.baselineSha } : {}),
-      });
+    case 'workitem_create_or_update_feature':
+      return workitemCreateOrUpdateFeature(workItemWriteArgs(args));
+    case 'workitem_create_or_update_pbi':
+      return workitemCreateOrUpdatePbi(workItemWriteArgs(args));
+    case 'workitem_create_or_update_bug':
+      return workitemCreateOrUpdateBug(workItemWriteArgs(args));
     case 'workitem_comments_read':
       if (!Number.isInteger(args.id)) throw new Error('id is required (a work item id)');
       return workitemCommentsRead({ id: args.id as number });