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

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

@@ -1,8 +1,11 @@
 // Azure DevOps work item tool logic. Exported for direct, in-process use by
 // mcp-server.ts — there is no CLI entry point here (nothing else in the
 // repo invoked this file as a CLI).
-import { AdoClient, adoProjectUrl, resolveProject } from './lib/client.ts'
-import { evaluateWorkflowTransition, formatWorkflowRefusal } from './workflow-rules.ts'
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { AdoClient, adoProjectUrl, resolveProject, resolveRepository } from './lib/client.ts'
+import { evaluateFeatureTransition, evaluateWorkflowTransition, formatWorkflowRefusal } from './workflow-rules.ts'
 
 // Work-item calls use the SAME org/project resolution as every other tool in
 // this package (`lib/client.ts`). They used to carry their own `config` object
@@ -36,16 +39,80 @@ export type WorkItemWriteArgs = {
   id?: number; type?: string; title?: string; description?: string; parentId?: number;
   predecessors?: number[]; related?: number[]; fields?: Record<string, unknown>; state?: string; comment?: string;
   assignedTo?: string; acceptanceCriteria?: string; priority?: number; startDate?: string; targetDate?: string;
+  /** T3: the Feature plan fields (board-rules.md § Plan fields), Feature type only. */
+  planRevision?: number; planHash?: string; baselineSha?: string;
 };
 
 const isAllowedType = (type: string | undefined): type is AllowedType => (ALLOWED_TYPES as readonly string[]).includes(type ?? '');
 function assertAllowedType(type: string | undefined): asserts type is AllowedType {
   if (!isAllowedType(type)) throw new Error(`type must be one of ${ALLOWED_TYPES.join(', ')}; got ${type ?? 'undefined'}`);
 }
+/** F5: the standing per-Epic container for Bugs found in closed Features. */
+const FIXES_FEATURE_TITLE = 'Fixes to closed Features';
+/** L1: "closed" for a Feature — no child may be added at or past these states. */
+const CLOSED_FEATURE_STATES: ReadonlySet<string> = new Set(['Awaiting Release', 'Done']);
+const L2_WARNING = 'L2 (staged refusal): a Feature needs at least one predecessor Feature; none given and other Features exist in the project — this will become a refusal';
+const L3_WARNING = 'L3 (staged refusal): a PBI/Bug carries no predecessor links; the implementation lead picks item order — this will become a refusal';
+
+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));
+}
+
+/** L2: true when the project holds another Feature besides Fixes containers (excluding `excludeId`). */
+async function projectHasNonFixesFeature(c: AdoClient, excludeId?: number): Promise<boolean> {
+  const clauses = [
+    `[System.TeamProject] = '${escapeWiql(resolveProject())}'`,
+    `[System.WorkItemType] = 'Feature'`,
+    `[System.Title] <> '${escapeWiql(FIXES_FEATURE_TITLE)}'`,
+  ];
+  if (excludeId !== undefined) clauses.push(`[System.Id] <> ${excludeId}`);
+  const result = await c.post<any>('/wit/wiql', { query: `SELECT [System.Id] FROM WorkItems WHERE ${clauses.join(' AND ')}` }, { 'api-version': '7.1', '$top': '1' });
+  return (result.workItems ?? []).length > 0;
+}
+
+/**
+ * L4: the predecessor rule for a Bug under a 'Fixes to closed Features'
+ * Feature. `siblingBugIds` are the other Bugs under the same Fixes Feature;
+ * `predecessorIds` are the links the Bug would carry after the write.
+ * Throws on violation.
+ */
+function assertFixesBugPredecessors(siblingBugIds: Set<number>, predecessorIds: number[]): void {
+  if (siblingBugIds.size === 0) {
+    if (predecessorIds.length) {
+      throw new Error(`the first Bug in a 'Fixes to closed Features' Feature carries no predecessor link; remove predecessor ${predecessorIds[0]} (L4)`);
+    }
+    return;
+  }
+  if (!predecessorIds.length) {
+    throw new Error(`a Bug under 'Fixes to closed Features' with sibling Bugs needs a predecessor link to one of them (L4)`);
+  }
+  if (!predecessorIds.some((id) => siblingBugIds.has(id))) {
+    throw new Error(`predecessor ${predecessorIds[0]} is not a Bug under the same 'Fixes to closed Features' Feature (L4)`);
+  }
+}
+
+/** L4: the sibling Bugs under a Fixes Feature (every child of type Bug except `excludeId`). */
+async function fixesSiblingBugIds(c: AdoClient, fixesFeature: any, excludeId?: number): Promise<Set<number>> {
+  const childIds = relationIds(fixesFeature, 'System.LinkTypes.Hierarchy-Forward');
+  if (!childIds.length) return new Set();
+  const children = await batchFetch(c, childIds);
+  return new Set(
+    children
+      .filter((child: any) => child.fields?.['System.WorkItemType'] === 'Bug' && child.id !== excludeId)
+      .map((child: any) => child.id as number),
+  );
+}
 interface WorkItemView {
   id: number; title: string; type: string; state: string; assignedTo: string | undefined; description: string | undefined; url: string | undefined;
   links: { parent: number | null; children: number[]; predecessors: number[]; successors: number[]; related: number[] };
-  effort: number | null; failureReason: string | null; fields?: Record<string, unknown>; relations?: unknown[];
+  effort: number | null; failureReason: string | null; planRevision: number | null; planHash: string | null; baselineSha: string | null;
+  fields?: Record<string, unknown>; relations?: unknown[];
+  /** L2/L3 staged refusals: the write succeeded, but the board rule that will harden rides here. */
+  warnings?: string[];
 }
 function formatItem(wi: any, raw: boolean): WorkItemView {
   const fields = wi.fields ?? {};
@@ -59,7 +126,10 @@ function formatItem(wi: any, raw: boolean): WorkItemView {
     if (relation.rel === 'System.LinkTypes.Related') links.related.push(relationId(relation.url));
   }
   const effort = fields['Microsoft.VSTS.Scheduling.Effort']; const failureReason = fields['Custom.FailureReason'];
-  const out: WorkItemView = { id: wi.id, title: fields['System.Title'], type: fields['System.WorkItemType'], state: fields['System.State'], assignedTo: fields['System.AssignedTo']?.displayName, description: fields['System.Description'], url: wi._links?.html?.href, links, effort: typeof effort === 'number' ? effort : null, failureReason: typeof failureReason === 'string' && failureReason ? failureReason : null };
+  // T3: the Feature plan fields ride the standard view (null when unset);
+  // raw mode still exposes every field verbatim.
+  const planRevision = fields['Custom.PlanRevision']; const planHash = fields['Custom.PlanHash']; const baselineSha = fields['Custom.BaselineSha'];
+  const out: WorkItemView = { id: wi.id, title: fields['System.Title'], type: fields['System.WorkItemType'], state: fields['System.State'], assignedTo: fields['System.AssignedTo']?.displayName, description: fields['System.Description'], url: wi._links?.html?.href, links, effort: typeof effort === 'number' ? effort : null, failureReason: typeof failureReason === 'string' && failureReason ? failureReason : null, planRevision: typeof planRevision === 'number' ? planRevision : null, planHash: typeof planHash === 'string' && planHash ? planHash : null, baselineSha: typeof baselineSha === 'string' && baselineSha ? baselineSha : null };
   if (raw) { out.fields = fields; out.relations = wi.relations ?? []; }
   return out;
 }
@@ -99,6 +169,9 @@ function buildWriteOps(args: WorkItemWriteArgs): any[] {
   const ops: any[] = [];
   const add = (field: string, value: unknown) => { if (value !== undefined) ops.push({ op: 'add', path: `/fields/${field}`, value }); };
   add('System.Title', args.title); add('System.Description', args.description); add('System.AssignedTo', args.assignedTo); add('Microsoft.VSTS.Common.AcceptanceCriteria', args.acceptanceCriteria); add('Microsoft.VSTS.Common.Priority', args.priority); add('Microsoft.VSTS.Scheduling.StartDate', args.startDate); add('Microsoft.VSTS.Scheduling.TargetDate', args.targetDate); add('System.State', args.state); add('System.History', args.comment);
+  // T3: the named plan-field arguments (validated Feature-only by the
+  // caller) write the presumed Custom.* reference names.
+  add('Custom.PlanRevision', args.planRevision); add('Custom.PlanHash', args.planHash); add('Custom.BaselineSha', args.baselineSha);
   for (const [field, value] of Object.entries(args.fields ?? {})) {
     if (!field.startsWith('Custom.')) throw new Error(`fields may only set Custom.* fields; '${field}' is managed by this tool`);
     add(field, value);
@@ -111,34 +184,89 @@ function buildWriteOps(args: WorkItemWriteArgs): any[] {
   return ops;
 }
 
+/** T3: the plan fields exist on Features only — PBIs and Bugs carry none. */
+function assertPlanFieldsAllowed(type: string | undefined): void {
+  if (type === 'Feature') return;
+  throw new Error('plan fields (planRevision, planHash, baselineSha) are Feature-only');
+}
+
+/** T3 value shape: a plan revision is a positive integer; the hashes are non-empty strings. */
+function assertPlanFieldValues(args: WorkItemWriteArgs): void {
+  if (args.planRevision !== undefined && (!Number.isInteger(args.planRevision) || (args.planRevision as number) < 1)) {
+    throw new Error('planRevision must be a positive integer');
+  }
+  if (args.planHash !== undefined && typeof args.planHash === 'string' && args.planHash.trim() === '') {
+    throw new Error('planHash must be a non-empty string');
+  }
+  if (args.baselineSha !== undefined && typeof args.baselineSha === 'string' && args.baselineSha.trim() === '') {
+    throw new Error('baselineSha must be a non-empty string');
+  }
+}
+
 export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<string> {
   if (args.id === undefined) {
     assertAllowedType(args.type); if (!args.title) throw new Error('title is required for create'); if (args.parentId === undefined) throw new Error(`${args.type} requires parentId`);
+    assertPlanFieldValues(args);
     // FENCE 1 (create): System.State via the raw fields escape hatch is
     // fenced for the gated types — the dedicated `state` argument exists so
-    // the workflow gate can evaluate the resulting state. Features carry no
-    // flags; for them the generic managed-field refusal in buildWriteOps
-    // still applies (unchanged behavior).
+    // the workflow gate can evaluate the resulting state. Features walk the
+    // Feature ladder instead (F3, evaluateFeatureTransition); for them the
+    // generic managed-field refusal in buildWriteOps still applies
+    // (unchanged behavior).
     if (args.type !== 'Feature' && args.fields !== undefined && 'System.State' in args.fields) {
       throw new Error('System.State via raw fields is fenced — pass the dedicated `state` argument so the workflow gate can evaluate it.');
     }
     // FENCE 2 (create): a new PBI/Bug starts at New, so a create whose
     // `state` lands anywhere past New is already a ladder refusal — G1
     // approval, merge automation and human cancellation all happen after
-    // create.
-    if (args.type !== 'Feature') {
+    // create. A Feature is created only at New (F3): any other requested
+    // state is refused outright, and the POST below carries no
+    // System.State op for Features at all.
+    if (args.type === 'Feature') {
       if (args.state !== undefined && args.state !== 'New') {
-        const violations = evaluateWorkflowTransition(args.type, 'New', args.state)
-        if (violations.length) throw new Error(formatWorkflowRefusal(violations))
+        throw new Error('Features are created only at New; move the Feature along its ladder after create');
       }
+    } else if (args.state !== undefined && args.state !== 'New') {
+      const violations = evaluateWorkflowTransition(args.type, 'New', args.state)
+      if (violations.length) throw new Error(formatWorkflowRefusal(violations))
+    }
+    // T3: plan fields are Feature-only (type is known at create).
+    if (args.type !== 'Feature' && (args.planRevision !== undefined || args.planHash !== undefined || args.baselineSha !== undefined)) {
+      assertPlanFieldsAllowed(args.type);
     }
-    const ops = buildWriteOps(args);
+    // F3: a Feature is created only at New, so the create POST carries no System.State op.
+    const createArgs: WorkItemWriteArgs = { ...args };
+    delete createArgs.state;
+    const ops = buildWriteOps(args.type === 'Feature' ? createArgs : args);
     const c = await getClient();
     const parent = await c.get<any>(`/wit/workitems/${args.parentId}`, { 'api-version': '7.1' });
     const expected = args.type === 'Feature' ? 'Epic' : 'Feature';
     if (parent.fields?.['System.WorkItemType'] !== expected) throw new Error(`${args.type} must be parented to a ${expected}; work item ${args.parentId} is a ${parent.fields?.['System.WorkItemType']}`);
+    // L1: a child may not be added under a closed Feature (Awaiting
+    // Release or Done), on create.
+    if (expected === 'Feature' && CLOSED_FEATURE_STATES.has(parent.fields?.['System.State'])) {
+      throw new Error(`work item ${args.parentId} is a Feature at ${parent.fields?.['System.State']}: no child can be added to a closed Feature (L1)`);
+    }
+    const warnings: string[] = [];
+    if (args.type === 'Feature') {
+      // L2 (soft, staged refusal): a Feature needs at least one
+      // predecessor Feature; only the very first Feature in a project
+      // (no other Features besides Fixes containers) carries none.
+      if (!(args.predecessors ?? []).length && await projectHasNonFixesFeature(c)) warnings.push(L2_WARNING);
+    } else if (args.type === 'Bug' && parent.fields?.['System.Title'] === FIXES_FEATURE_TITLE) {
+      // L4 (hard): a Bug under 'Fixes to closed Features' needs a Related
+      // link to its Responsible Feature, in any state, and its predecessor
+      // must be another Bug in the same Fixes Feature (none for the first).
+      if (!(args.related ?? []).length) throw new Error(`a Bug under '${FIXES_FEATURE_TITLE}' needs a Related link to its Responsible Feature (L4)`);
+      assertFixesBugPredecessors(await fixesSiblingBugIds(c, parent), args.predecessors ?? []);
+    } else if ((args.predecessors ?? []).length) {
+      // L3 (soft, staged refusal): a PBI carries no predecessor links.
+      warnings.push(L3_WARNING);
+    }
     const created = await c.post<any>(`/wit/workitems/$${encodeURIComponent(args.type)}`, ops, { 'api-version': '7.1' }, 'application/json-patch+json');
-    return JSON.stringify(formatItem(created, false), null, 2);
+    const createdView = formatItem(created, false);
+    if (warnings.length) createdView.warnings = warnings;
+    return JSON.stringify(createdView, null, 2);
   }
   if (args.type !== undefined) throw new Error('type cannot be changed on an existing work item');
   // System.State arriving through the raw fields escape hatch is deferred:
@@ -153,8 +281,14 @@ export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<s
   const current = await c.get<any>(`/wit/workitems/${args.id}`, { 'api-version': '7.1', $expand: 'all' });
   assertTracked(current);
   const currentType: AllowedType = current.fields?.['System.WorkItemType'];
-  // FENCE 1: System.State via raw fields on a gated type. Features carry no
-  // flags and keep the generic managed-field refusal instead.
+  assertPlanFieldValues(args);
+  // T3: plan fields are Feature-only (the type is only known after the read).
+  if (currentType !== 'Feature' && (args.planRevision !== undefined || args.planHash !== undefined || args.baselineSha !== undefined)) {
+    assertPlanFieldsAllowed(currentType);
+  }
+  // FENCE 1: System.State via raw fields on a gated type. Features keep the
+  // generic managed-field refusal instead; their ladder runs through the
+  // dedicated `state` argument (F3, evaluateFeatureTransition).
   if (stateViaRawFields) {
     if (currentType === 'Feature') throw new Error(`fields may only set Custom.* fields; 'System.State' is managed by this tool`);
     throw new Error('System.State via raw fields is fenced — pass the dedicated `state` argument so the workflow gate can evaluate it.');
@@ -163,11 +297,37 @@ export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<s
   // that moves System.State — a move that skips gates, reaches a human-owned
   // state (Approved/Done/Removed) or walks off the ladder is refused. Writes
   // that leave the state untouched are not gated.
-  if (currentType !== 'Feature') {
-    const currentState = current.fields?.['System.State']
+  const currentState = current.fields?.['System.State']
+  if (currentType === 'Feature') {
+    // F5: the standing Fixes container never walks the Feature ladder.
+    if (current.fields?.['System.Title'] === FIXES_FEATURE_TITLE && (args.state ?? currentState) !== 'In Progress') {
+      throw new Error(`fenced by feature ladder: '${FIXES_FEATURE_TITLE}' stays at In Progress; agents refuse every other target state`)
+    }
+    // F3: the Feature ladder is linear, one step at a time, never backward.
+    // F4: the surviving moves carry child/promotion preconditions, checked
+    // against the live board below.
+    const targetState = args.state ?? currentState
+    if (targetState !== currentState) {
+      const violations = evaluateFeatureTransition(currentState, targetState)
+      if (violations.length) throw new Error(formatWorkflowRefusal(violations))
+      await assertFeaturePreconditions(c, current, currentState, targetState)
+    }
+  } else {
     const violations = evaluateWorkflowTransition(currentType, currentState, args.state ?? currentState)
     if (violations.length) throw new Error(formatWorkflowRefusal(violations))
+    // F7 (provisional): a PBI entering Design Validation must find its
+    // parent Feature's requirements.md (or spec.md, when not yet renamed)
+    // in the current repo hashing to the Feature's Custom.PlanHash. Bugs
+    // skip the check — they have no plan hash and never reach Design
+    // Validation (F9).
+    if (currentType === 'Product Backlog Item' && (args.state ?? currentState) === 'Design Validation') {
+      await assertPlanHashMatches(c, current);
+    }
   }
+  // L1–L4 (update): the board link rules. L2/L3 are soft — staged
+  // refusals that ride the result as warnings; L1/L4 refuse here, before
+  // any PATCH.
+  let updateParent: any | undefined;
   if (args.parentId !== undefined) {
     // A parent is singular. Read the existing item so the write can remove all
     // old parent links before adding the one validated replacement.
@@ -177,6 +337,11 @@ export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<s
     if (parent.fields?.['System.WorkItemType'] !== expected) {
       throw new Error(`${type} must be parented to a ${expected}; work item ${args.parentId} is a ${parent.fields?.['System.WorkItemType']}`);
     }
+    // L1: an update may not move a child under a closed Feature either.
+    if (expected === 'Feature' && CLOSED_FEATURE_STATES.has(parent.fields?.['System.State'])) {
+      throw new Error(`work item ${args.parentId} is a Feature at ${parent.fields?.['System.State']}: no child can be added to a closed Feature (L1)`);
+    }
+    updateParent = parent;
     const oldParentIndexes = (current.relations ?? [])
       .map((relation: any, index: number) => relation.rel === 'System.LinkTypes.Hierarchy-Reverse' ? index : -1)
       .filter((index: number) => index >= 0)
@@ -188,6 +353,152 @@ export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<s
       ...(parentAdd ? [parentAdd] : []),
     ];
   }
+  const warnings: string[] = [];
+  if (currentType === 'Bug') {
+    // L4 (hard, in any state): a Bug under 'Fixes to closed Features'
+    // needs its Related link to the Responsible Feature, and its
+    // predecessor must be a sibling Bug in the same Fixes Feature.
+    const parent = updateParent ?? await fetchItemParent(c, current);
+    if (parent !== undefined && parent.fields?.['System.Title'] === FIXES_FEATURE_TITLE) {
+      const relatedIds = [...relationIds(current, 'System.LinkTypes.Related'), ...(args.related ?? [])];
+      if (!relatedIds.length) {
+        throw new Error(`a Bug under '${FIXES_FEATURE_TITLE}' needs a Related link to its Responsible Feature (L4)`);
+      }
+      const predecessorIds = [...new Set([...relationIds(current, 'System.LinkTypes.Dependency-Reverse'), ...(args.predecessors ?? [])])];
+      assertFixesBugPredecessors(await fixesSiblingBugIds(c, parent, args.id), predecessorIds);
+    } else if ((args.predecessors ?? []).length) {
+      // L3 (soft): an ordinary Bug carries no predecessor links.
+      warnings.push(L3_WARNING);
+    }
+  } else if (currentType === 'Product Backlog Item') {
+    if ((args.predecessors ?? []).length) warnings.push(L3_WARNING);
+  } else if (args.predecessors !== undefined) {
+    // L2 (soft): a Feature's predecessor set after this write must be
+    // non-empty once any other Feature exists in the project.
+    const predecessorIds = [...new Set([...relationIds(current, 'System.LinkTypes.Dependency-Reverse'), ...args.predecessors])];
+    if (!predecessorIds.length && await projectHasNonFixesFeature(c, args.id)) warnings.push(L2_WARNING);
+  }
   const updated = await c.patch<any>(`/wit/workitems/${args.id}`, ops, { 'api-version': '7.1' }, 'application/json-patch+json');
-  return JSON.stringify(formatItem(updated, false), null, 2);
+  const updatedView = formatItem(updated, false);
+  if (warnings.length) updatedView.warnings = warnings;
+  return JSON.stringify(updatedView, null, 2);
+}
+
+/** L3/L4: the parent of an item, fetched through its Hierarchy-Reverse relation (undefined when parentless). */
+async function fetchItemParent(c: AdoClient, item: any): Promise<any | undefined> {
+  const [parentId] = relationIds(item, 'System.LinkTypes.Hierarchy-Reverse');
+  if (parentId === undefined) return undefined;
+  return c.get<any>(`/wit/workitems/${parentId}`, { 'api-version': '7.1' });
+}
+
+/** F4: the children of a Feature, fetched live — the ladder preconditions read the board, not a cache. */
+async function featureChildStates(c: AdoClient, item: any): Promise<Array<{ id: number; state: string }>> {
+  const relationId = (url: string) => Number(/(\d+)\/?$/.exec(url)?.[1]);
+  const ids = (item.relations ?? [])
+    .filter((relation: any) => relation.rel === 'System.LinkTypes.Hierarchy-Forward')
+    .map((relation: any) => relationId(relation.url))
+    .filter((id: number) => Number.isInteger(id));
+  if (!ids.length) return [];
+  const children = await batchFetch(c, ids);
+  return children.map((child: any) => ({ id: child.id, state: child.fields?.['System.State'] }));
+}
+
+/**
+ * F4: the Feature ladder's preconditions, checked against the children (and,
+ * for Done, the promotion PR) after the pure ladder allowed the move:
+ *
+ * - New → In Progress: at least one child has left New.
+ * - In Progress → Awaiting Release: every child is Done or Removed.
+ * - Awaiting Release → Done: the integration → main promotion PR is merged
+ *   (G2 has passed for the code this Feature ships).
+ */
+async function assertFeaturePreconditions(c: AdoClient, item: any, fromState: string, toState: string): Promise<void> {
+  if (fromState === 'New' && toState === 'In Progress') {
+    const children = await featureChildStates(c, item);
+    if (!children.length) {
+      throw new Error('a Feature moves New → In Progress only once at least one child has left New; this Feature has no children');
+    }
+    if (!children.some((child) => child.state !== 'New')) {
+      throw new Error('a Feature moves New → In Progress only once at least one child has left New; every child is still at New');
+    }
+  }
+  if (fromState === 'In Progress' && toState === 'Awaiting Release') {
+    const children = await featureChildStates(c, item);
+    if (!children.length) {
+      throw new Error('a Feature moves In Progress → Awaiting Release only when every child is Done or Removed; this Feature has no children');
+    }
+    const open = children.find((child) => child.state !== 'Done' && child.state !== 'Removed');
+    if (open) {
+      throw new Error(`a Feature moves In Progress → Awaiting Release only when every child is Done or Removed; child ${open.id} is at ${open.state}`);
+    }
+  }
+  if (fromState === 'Awaiting Release' && toState === 'Done') {
+    const repository = resolveRepository();
+    const result = await c.get<any>(`/git/repositories/${repository}/pullRequests`, {
+      'api-version': '7.1',
+      'searchCriteria.status': 'completed',
+      'searchCriteria.sourceRefName': 'refs/heads/integration',
+      'searchCriteria.targetRefName': 'refs/heads/main',
+    });
+    if (!(result.value ?? []).length) {
+      throw new Error('Awaiting Release → Done needs the integration → main promotion PR merged; none found');
+    }
+  }
+}
+
+/**
+ * F7 (provisional — review after the first real runs): the plan hash is
+ * what G1 approved. Before an item enters Design Validation, the Feature's
+ * requirements.md (or spec.md, when not yet renamed) in the current repo
+ * must hash (sha256) to the Feature's Custom.PlanHash. A Feature without a
+ * plan hash is not checked.
+ */
+async function assertPlanHashMatches(c: AdoClient, item: any): Promise<void> {
+  const parent = await fetchItemParent(c, item);
+  if (parent === undefined) return;
+  const planHash = parent.fields?.['Custom.PlanHash'];
+  if (typeof planHash !== 'string' || !planHash.trim()) return;
+  const featureId = parent.id as number;
+  const planFile = findPlanFile(process.cwd(), featureId);
+  if (planFile === undefined) {
+    throw new Error(`F7: no requirements.md or spec.md found for Feature ${featureId} under plans/features/ — cannot verify Custom.PlanHash before Design Validation`);
+  }
+  const digest = createHash('sha256').update(readFileSync(planFile)).digest('hex');
+  if (digest !== planHash.trim().toLowerCase()) {
+    throw new Error(`F7: ${planFile} hashes to ${digest}, which does not hash to the Feature's Custom.PlanHash (${planHash}) — the approved plan and the repo disagree; re-validate before Design Validation`);
+  }
+}
+
+/** The Feature's plan file: plans/features/az<id>-<slug>/requirements.md, with spec.md as the not-yet-renamed fallback. */
+function findPlanFile(cwd: string, featureId: number): string | undefined {
+  const featuresDir = join(cwd, 'plans', 'features');
+  if (!existsSync(featuresDir)) return undefined;
+  for (const entry of readdirSync(featuresDir)) {
+    if (!entry.startsWith(`az${featureId}-`)) continue;
+    for (const name of ['requirements.md', 'spec.md']) {
+      const candidate = join(featuresDir, entry, name);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return undefined;
+}
+
+export type WorkItemCommentsReadArgs = { id: number };
+
+/**
+ * T1: read a work item's comments (Work Item Tracking Comments – List,
+ * GET .../_apis/wit/workItems/{id}/comments?api-version=7.1). The board's
+ * evidence contract (board-rules.md § Comments and evidence) writes
+ * evidence to System.History; --raw on workitem_list_or_get shows only the
+ * latest value, so this is the read path for everything a run wrote.
+ */
+export async function workitemCommentsRead(args: WorkItemCommentsReadArgs): Promise<string> {
+  const c = await getClient();
+  const result = await c.get<any>(`/wit/workItems/${args.id}/comments`, { 'api-version': '7.1' });
+  const comments = (result.comments ?? []).map((comment: any) => ({
+    author: comment.createdBy?.displayName ?? null,
+    createdDate: comment.createdDate ?? null,
+    text: comment.text ?? '',
+  }));
+  return JSON.stringify({ id: args.id, count: comments.length, comments }, null, 2);
 }

package/packages/azdo/src/cli.ts

@@ -45,6 +45,7 @@ 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: '--repository', key: 'repository', type: 'string' },
     ],
     validate: requirePullRequestWrite,
@@ -103,21 +104,60 @@ const commands: readonly Command[] = [
       { flag: '--priority', key: 'priority', type: 'integer' },
       { 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']); },
   },
+  {
+    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: [],
+  },
 ];
 
 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] [--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 [--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-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 {

package/packages/azdo/src/lib/agent-identity.ts

@@ -147,7 +147,7 @@ export interface AgentIdentityResolution {
  *  - `env.ADL_HUMAN_AZDO === '1'`: the EXACT string `"1"`, not `"true"`,
  *    not `"yes"`, not trimmed whitespace -- Tarun exports it from his own
  *    `.zshrc`. An agent must never set it (packages/agent-settings'
- *    GLOBAL-AGENTS.md, "Agent identity"; the hook's denial of an agent
+ *    TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md, "Agent identity"; the hook's denial of an agent
  *    setting it is packages/agent-hooks work, not this module's).
  *
  * No fallback, no trimming, no case-insensitivity: a near-miss value is

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

@@ -205,7 +205,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
 }