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

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[];
 };
 
@@ -45,6 +45,9 @@ const commands: readonly Command[] = [
       { flag: '--no-auto-complete', key: 'autoComplete', type: 'boolean' },
       { 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,
@@ -85,26 +88,108 @@ 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',
+    tool: 'workitem_comments_read',
+    options: [{ flag: '--id', key: 'id', type: 'integer' }],
+    validate: (args) => requireKeys(args, ['id']),
+  },
+  {
+    name: 'workitem-attachments',
+    tool: 'workitem_attachments',
+    options: [
+      { flag: '--id', key: 'id', type: 'integer' },
+      { flag: '--action', key: 'action', type: 'string', values: ['read', 'upload', 'delete'] },
+      { flag: '--file-name', key: 'fileName', type: 'string' },
+      { flag: '--content', key: 'content', type: 'string' },
+    ],
+    validate: (args) => {
+      requireKeys(args, ['id', 'action']);
+      if (args.action === 'upload' || args.action === 'delete') requireKeys(args, ['fileName']);
+      if (args.action === 'upload') requireKeys(args, ['content']);
+    },
+  },
+  {
+    name: 'activity-add',
+    tool: 'activity_add',
+    options: [{ flag: '--note', key: 'note', type: 'string' }],
+    validate: (args) => requireKeys(args, ['note']),
+  },
+  {
+    name: 'activity-list',
+    tool: 'activity_list',
+    options: [],
   },
 ];
 
@@ -112,12 +197,18 @@ 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] [--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]
+  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
+  activity-list
 `;
 
 function requireKeys(args: ToolArguments, keys: string[]): void {
@@ -137,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;
   }
@@ -147,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');
   }
@@ -210,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') {
@@ -221,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 {
@@ -205,7 +277,13 @@ export class AdoClient {
       redirect: 'error',
       method,
       headers,
-      body: options.body ? JSON.stringify(options.body) : undefined,
+      // JSON bodies are stringified; an octet-stream upload (T2
+      // attachments) is sent exactly as supplied.
+      body: options.body === undefined
+        ? undefined
+        : contentType === 'application/octet-stream'
+          ? (options.body as string | Uint8Array)
+          : JSON.stringify(options.body),
     });
 
     if (!resp.ok) {

package/packages/azdo/src/lib/validate-pr-metadata.ts

@@ -2,10 +2,13 @@ import { BRANCH_PREFIXES } from './commit-types.ts'
 
 // A PR title never carries the pipeline-reserved `release`, so its types are the branch prefixes.
 const TITLE_PATTERN = new RegExp(`^(${BRANCH_PREFIXES.join('|')})(\\([a-z0-9][a-z0-9-]*\\))?: .+$`)
-const REQUIRED_SECTIONS = ['Summary', 'Why', 'Changes']
+// P3 (azdo-git-process.md § PR body): every PR carries the same five sections; a planning PR may write the exact text "none (docs-only)" in the last two.
+const REQUIRED_SECTIONS = ['Summary', 'Why', 'Changes', 'Test plan', 'Security impact considered']
+const DOCS_ONLY_SECTIONS = new Set(['Test plan', 'Security impact considered'])
+export const DOCS_ONLY = 'none (docs-only)'
 
-export function validatePullRequestMetadata(title: string, description: string): string[] {
-  return [...validatePullRequestTitle(title), ...validatePullRequestDescription(description)]
+export function validatePullRequestMetadata(title: string, description: string, docsOnlySections = false): string[] {
+  return [...validatePullRequestTitle(title), ...validatePullRequestDescription(description, { docsOnlySections })]
 }
 
 export function validatePullRequestTitle(title: string): string[] {
@@ -20,11 +23,17 @@ export function validatePullRequestTitle(title: string): string[] {
   return errors
 }
 
-export function validatePullRequestDescription(description: string): string[] {
+export function validatePullRequestDescription(description: string, options: { docsOnlySections?: boolean } = {}): string[] {
   const errors: string[] = []
   for (const section of REQUIRED_SECTIONS) {
     const match = description.match(new RegExp(`(?:^|\\n)## ${section}[ \\t]*\\n([\\s\\S]*?)(?=\\n## |$)`, 'i'))
-    if (!match?.[1]?.trim()) errors.push(`description requires a non-empty ## ${section} section`)
+    const text = match?.[1]?.trim()
+    if (!text) {
+      errors.push(`description requires a non-empty ## ${section} section`)
+      continue
+    }
+    // P3: "none (docs-only)" is special only in the last two sections of a planning PR; anywhere else it is ordinary body text.
+    if (options.docsOnlySections && DOCS_ONLY_SECTIONS.has(section) && text === DOCS_ONLY) continue
   }
   return errors
 }

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 7 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,17 +62,20 @@ 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.',
+        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: {
             title: { type: 'string', description: 'Conventional lowercase title: <type>(<scope>): <subject>' },
-            description: { type: 'string', description: 'Must contain non-empty ## Summary, ## Why, and ## Changes sections' },
+            description: { type: 'string', description: 'Must contain non-empty ## Summary, ## Why, ## Changes, ## Test plan and ## Security impact considered sections' },
             action: { type: 'string', enum: ['create', 'update'] },
             pullRequestId: { type: 'number' },
             autoComplete: { type: 'boolean' },
             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'],
@@ -124,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 and failureReason (both 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: {
@@ -133,15 +136,125 @@ export function createServer(): Server {
         },
       },
       {
-        name: 'workitem_create_or_update',
-        description: 'Create a tracked work item under its required parent, or update an existing item.',
+        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' }, 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' },
+            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', 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' },
+          },
+        },
+      },
+      {
+        name: 'workitem_comments_read',
+        description: "Read a work item's comments (Work Item Tracking Comments – List). This is the read path for the board's evidence: --raw on workitem_list_or_get shows only the latest System.History value.",
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: { type: 'number', description: 'The work item id whose comments are read' },
+          },
+          required: ['id'],
+        },
+      },
+      {
+        name: 'workitem_attachments',
+        description: 'Read, upload or delete a work item\'s attachments (Feature attachments only, per board-rules.md § Attachments). Upload POSTs an octet-stream to the attachments endpoint and PATCHes an AttachedFile relation with a test/rev guard. Delete removes only the AttachedFile relation (the stored file stays; Attachments-Delete is 7.2-preview only) and refuses a plan-r* file once any item of the Feature has left Awaiting Approval.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: { type: 'number', description: 'The work item id (the Feature carrying the attachments)' },
+            action: { type: 'string', enum: ['read', 'upload', 'delete'] },
+            fileName: { type: 'string', description: 'upload/delete: the attachment file name' },
+            content: { type: 'string', description: 'upload: the file content, sent as an octet-stream body' },
           },
+          required: ['id', 'action'],
+        },
+      },
+      {
+        name: 'activity_add',
+        description: 'Append one entry to this repository\'s local agent activity log (.adl/agent-activity.sqlite, gitignored; A1, replaces docs/notes.md). Only the note is supplied — the server fills time (UTC ISO-8601), surface, agent identity and repository. Requires a resolvable agent identity, like every other tool.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            note: { type: 'string', description: 'The note text; non-empty' },
+          },
+          required: ['note'],
+        },
+      },
+      {
+        name: 'activity_list',
+        description: 'Read this repository\'s local agent activity log (.adl/agent-activity.sqlite): every entry, oldest first, each with time (UTC ISO-8601), surface, agent identity, repository and note.',
+        inputSchema: {
+          type: 'object',
+          properties: {},
         },
       },
     ],