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

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

@@ -35,12 +35,49 @@ export function resetClientForTests(): void {
 const ALLOWED_TYPES = ['Feature', 'Product Backlog Item', 'Bug'] as const;
 type AllowedType = (typeof ALLOWED_TYPES)[number];
 export type WorkItemListOrGetArgs = { id?: number; ids?: number[]; type?: string; state?: string; assignedTo?: string; limit?: number; raw?: boolean };
-export type WorkItemWriteArgs = {
-  id?: number; type?: string; title?: string; description?: string; parentId?: number;
+
+/** The per-type write surface (azdo-type-split plan). One arg shape per type; the
+ *  three sibling tool names — `workitem_create_or_update_feature` /
+ *  `_pbi` / `_bug` — are dispatched to `workitemCreateOrUpdateFeature` /
+ *  `Pbi` / `Bug` (see tool-dispatch.ts). The blanket
+ * `workitem_create_or_update` is gone. */
+export type WorkItemFeatureWriteArgs = {
+  id?: number; 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. */
+  /** T3: the Feature plan fields (board-rules.md § Plan fields). Required on
+   *  the New → In Progress move; a Feature created at New does not carry them
+   *  until it walks its ladder. */
   planRevision?: number; planHash?: string; baselineSha?: string;
+  /** az698: drop a single predecessor or related link by id (idempotent on a missing link). Update path only. */
+  removePredecessor?: number; removeRelated?: number;
+};
+export type WorkItemPbiWriteArgs = {
+  id?: number; title?: string; description?: string; parentId?: number;
+  predecessors?: number[]; related?: number[]; fields?: Record<string, unknown>; state?: string; comment?: string;
+  assignedTo?: string; acceptanceCriteria?: string; priority?: number; effort?: number; startDate?: string; targetDate?: string;
+  /** az698: drop a single predecessor or related link by id. */
+  removePredecessor?: number; removeRelated?: number;
+};
+export type WorkItemBugWriteArgs = {
+  id?: number; title?: string; description?: string; parentId?: number;
+  predecessors?: number[]; related?: number[]; fields?: Record<string, unknown>; state?: string; comment?: string;
+  assignedTo?: string; acceptanceCriteria?: string; priority?: number; effort?: number; startDate?: string; targetDate?: string;
+  /** az698: drop a single predecessor or related link by id. */
+  removePredecessor?: number; removeRelated?: number;
+};
+
+/** The merged shape all three per-type arg shapes satisfy — what
+ *  `tool-dispatch.ts` builds once and hands to whichever type-named tool was
+ *  called. The board type is never an argument: it is the tool name. */
+export type WorkItemWriteArgs = WorkItemFeatureWriteArgs & WorkItemPbiWriteArgs & WorkItemBugWriteArgs;
+
+/** The tool-name suffix each board type writes through — `Product Backlog Item`
+ *  is the one type whose board name is not its tool name. */
+const TOOL_SUFFIX: Record<AllowedType, 'feature' | 'pbi' | 'bug'> = {
+  Feature: 'feature',
+  'Product Backlog Item': 'pbi',
+  Bug: 'bug',
 };
 
 const isAllowedType = (type: string | undefined): type is AllowedType => (ALLOWED_TYPES as readonly string[]).includes(type ?? '');
@@ -110,6 +147,10 @@ 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; planRevision: number | null; planHash: string | null; baselineSha: string | null;
+  /** Priority is the literal set {1, 2, 3, 4} (1=Very High, 2=High, 3=Medium, 4=Low). null when unset or not one of the four (azdo-type-split plan). */
+  priority: number | null;
+  /** Acceptance Criteria; null when unset. Required on a Feature's New → In Progress move; optional for PBI / Bug. */
+  acceptanceCriteria: 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[];
@@ -129,7 +170,28 @@ function formatItem(wi: any, raw: boolean): WorkItemView {
   // 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 };
+  // Priority is the literal set {1, 2, 3, 4}; anything else reads as null (mirrors effort's lax null rule).
+  const rawPriority = fields['Microsoft.VSTS.Common.Priority'];
+  const priority = typeof rawPriority === 'number' && [1, 2, 3, 4].includes(rawPriority) ? rawPriority : null;
+  const ac = fields['Microsoft.VSTS.Common.AcceptanceCriteria'];
+  const acceptanceCriteria = typeof ac === 'string' && ac ? ac : null;
+  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,
+    priority,
+    acceptanceCriteria,
+  };
   if (raw) { out.fields = fields; out.relations = wi.relations ?? []; }
   return out;
 }
@@ -165,12 +227,18 @@ export async function workitemListOrGet(args: WorkItemListOrGetArgs = {}): Promi
   return JSON.stringify({ items: items.map((item) => formatItem(item, args.raw ?? false)), count: selected.length, truncated: ids.length > limit, defaultsApplied: args.state === undefined }, null, 2);
 }
 
-function buildWriteOps(args: WorkItemWriteArgs): any[] {
+/** The per-type write arg shapes (azdo-type-split plan) give `buildWriteOps`
+ *  a narrowed surface by construction. The `fields` escape hatch still
+ *  cannot land managed fields — see the `Custom.*` check below.
+ *  planRevision / planHash / baselineSha remain Feature-only at the type
+ *  level (PBI/Bug args don't carry them at all); effort rides Feature +
+ *  PBI + Bug. */
+function buildWriteOps(args: { title?: string; description?: string; assignedTo?: string; acceptanceCriteria?: string; priority?: number; effort?: number; startDate?: string; targetDate?: string; state?: string; comment?: string; planRevision?: number; planHash?: string; baselineSha?: string; fields?: Record<string, unknown>; parentId?: number; predecessors?: number[]; related?: number[]; }): 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('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.Effort', args.effort); 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 are Feature-only; the type-specific
+  // caller is responsible for never passing them on PBI/Bug.
   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`);
@@ -184,14 +252,17 @@ 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;
+/**
+ * T3: the plan fields exist on Features only — PBIs and Bugs carry none.
+ * Both call sites below already guard `type !== 'Feature'` before calling, so
+ * this refuses unconditionally; the caller owns the type test.
+ */
+function assertPlanFieldsAllowed(): void {
   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 {
+function assertPlanFieldValues(args: { planRevision?: number; planHash?: string; baselineSha?: string }): void {
   if (args.planRevision !== undefined && (!Number.isInteger(args.planRevision) || (args.planRevision as number) < 1)) {
     throw new Error('planRevision must be a positive integer');
   }
@@ -203,9 +274,139 @@ function assertPlanFieldValues(args: WorkItemWriteArgs): void {
   }
 }
 
-export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<string> {
+/** Priority is the literal set {1, 2, 3, 4} — 1=Very High, 2=High, 3=Medium, 4=Low. Not any integer. */
+function assertPriority(priority: number): void {
+  if (!Number.isInteger(priority) || ![1, 2, 3, 4].includes(priority)) {
+    throw new Error('priority must be one of 1 (Very High), 2 (High), 3 (Medium), 4 (Low)');
+  }
+}
+
+/** Effort is days, finite, ≥ 0. Floats accepted. */
+function assertEffort(effort: number): void {
+  if (!Number.isFinite(effort) || effort < 0) {
+    throw new Error('effort must be a non-negative number (days; floats accepted)');
+  }
+}
+
+/** Every heading in `headings` must appear in `description` as an H2 section.
+ *  Headings may sit at the start of the description, on their own line, or
+ *  after a blank line — the gate only checks presence, not prose quality
+ *  (azdo-type-split plan § Out of Scope). */
+function assertDescriptionHasHeadings(description: string, headings: readonly string[], shapeName: string): void {
+  for (const heading of headings) {
+    // The heading is present if any line of the description equals `## <heading>`
+    // (a heading at the start of a line) — case-sensitive, exact. Matches
+    // the heading at end of description with or without a trailing newline.
+    const atLineStart = new RegExp(`(^|\\n)\\s*##\\s+${heading.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}\\b`);
+    if (!atLineStart.test(description)) {
+      throw new Error(`description must carry the '${heading}' section (${shapeName})`);
+    }
+  }
+}
+
+/** The board file each type's description is written from, and the H2 sections
+ *  that file carries — a Feature from intent.md, a PBI and a Bug from their
+ *  item file. */
+const DESCRIPTION_SHAPE: Record<AllowedType, { file: string; headings: readonly string[] }> = {
+  Feature: { file: 'intent.md', headings: ['Why', 'Outcome', 'Constraints', 'Non-goals'] },
+  'Product Backlog Item': { file: 'item file', headings: ['What it delivers', 'Verification'] },
+  Bug: {
+    file: 'bug item file',
+    headings: ['Current behaviour', 'Expected behaviour', 'Behaviour that must not change', 'Responsible Feature', 'Verification'],
+  },
+};
+
+/** What the description is missing: nothing, or the sections it must carry.
+ *  Returns the wording for a refusal rather than throwing, so the caller can
+ *  list every missing field in one message. */
+function missingDescription(type: AllowedType, description: string | undefined): string | undefined {
+  if (description === undefined || description.trim() === '') return 'non-empty';
+  const { file, headings } = DESCRIPTION_SHAPE[type];
+  try {
+    assertDescriptionHasHeadings(description, headings, `${file} shape`);
+    return undefined;
+  } catch {
+    return `carrying ${headings.map((heading) => `## ${heading}`).join(', ')} (${file})`;
+  }
+}
+
+/** Every create lands at New: a Feature walks its own ladder only after it
+ *  exists, and a PBI/Bug starts at New (G1 approval, merge automation and
+ *  human cancellation all happen later). */
+function assertCreateState(type: AllowedType, state: string | undefined): void {
+  if (state === undefined || state === 'New') return;
+  if (type === 'Feature') {
+    throw new Error('Features are created only at New; move the Feature along its ladder after create');
+  }
+  const violations = evaluateWorkflowTransition(type, 'New', state);
+  if (violations.length) throw new Error(formatWorkflowRefusal(violations));
+}
+
+/** Per-type mandatory fields (Tarun, 2026-10-15), create path:
+ *  - Feature: title, parentId (an Epic), priority, description (intent.md shape).
+ *  - PBI / Bug: title, parentId (a Feature), description (item file shape), effort.
+ *  Runs before any network call and lists every missing field in one message. */
+function assertMandatoryOnCreate(type: AllowedType, args: WorkItemWriteArgs): void {
+  const missing: string[] = [];
+  if (args.title === undefined || args.title.trim() === '') missing.push('title');
+  if (args.parentId === undefined) missing.push('parentId');
+  else if (!Number.isInteger(args.parentId) || args.parentId < 1) missing.push('parentId (a positive integer)');
+  const missingShape = missingDescription(type, args.description);
+  if (missingShape !== undefined) missing.push(`description (${missingShape})`);
+  if (type === 'Feature') {
+    if (args.priority === undefined) missing.push('priority (1=Very High, 2=High, 3=Medium, 4=Low)');
+    else assertPriority(args.priority);
+  } else if (args.effort === undefined) {
+    missing.push('effort (days)');
+  } else {
+    assertEffort(args.effort);
+  }
+  if (missing.length) {
+    throw new Error(`a ${type} create requires ${missing.join(', ')}`);
+  }
+}
+
+/** Per-type mandatory fields on the update path (Tarun, 2026-10-15). Every
+ *  update carries a comment. A Feature at New must re-send its create fields;
+ *  the New → In Progress move additionally requires the acceptance criteria
+ *  itemised per requirements.md and the three plan fields. A PBI or Bug carries
+ *  nothing beyond the comment once it exists. */
+function assertMandatoryOnUpdate(type: AllowedType, currentState: string, targetState: string, args: WorkItemWriteArgs): void {
+  assertUpdateComment(args.comment);
+  if (type !== 'Feature' || currentState !== 'New') return;
+  const missing: string[] = [];
+  if (args.title === undefined || args.title.trim() === '') missing.push('title');
+  if (args.parentId === undefined) missing.push('parentId');
+  if (args.priority === undefined) missing.push('priority');
+  else assertPriority(args.priority);
+  const missingShape = missingDescription(type, args.description);
+  if (missingShape !== undefined) missing.push(`description (${missingShape})`);
+  if (targetState === 'In Progress') {
+    if (args.acceptanceCriteria === undefined || args.acceptanceCriteria.trim() === '') missing.push('acceptanceCriteria');
+    if (args.planRevision === undefined) missing.push('planRevision');
+    if (args.planHash === undefined || args.planHash.trim() === '') missing.push('planHash');
+    if (args.baselineSha === undefined || args.baselineSha.trim() === '') missing.push('baselineSha');
+  }
+  if (missing.length) {
+    throw new Error(`a Feature at New requires ${missing.join(', ')} on this update`);
+  }
+}
+
+/** `comment` is mandatory on every update; on create, it's optional.
+ *  Trims; throws on empty/whitespace. */
+function assertUpdateComment(comment: string | undefined): void {
+  if (typeof comment !== 'string' || comment.trim() === '') {
+    throw new Error('comment is required on every update (mandatory evidence)');
+  }
+}
+
+/** The one write implementation behind the three per-type tools. `type` is the
+ *  tool's own name, never an argument — a Feature write can no longer land on a
+ *  PBI by passing the wrong `type`. */
+async function writeWorkItem(type: AllowedType, 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`);
+    // Per-type mandatory fields (Tarun, 2026-10-15) run before any network.
+    assertMandatoryOnCreate(type, args);
     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
@@ -213,7 +414,7 @@ export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<s
     // 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) {
+    if (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
@@ -222,38 +423,31 @@ export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<s
     // 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') {
-        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))
-    }
+    assertCreateState(type, args.state);
     // 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);
+    if (type !== 'Feature' && (args.planRevision !== undefined || args.planHash !== undefined || args.baselineSha !== undefined)) {
+      assertPlanFieldsAllowed();
     }
     // 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 ops = buildWriteOps(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']}`);
+    const expected = type === 'Feature' ? 'Epic' : 'Feature';
+    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: 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') {
+    if (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) {
+    } else if (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).
@@ -263,12 +457,11 @@ export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<s
       // 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');
+    const created = await c.post<any>(`/wit/workitems/$${encodeURIComponent(type)}`, ops, { 'api-version': '7.1' }, 'application/json-patch+json');
     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:
   // its refusal is type-dependent (FENCE 1 below) and the type is only known
   // after the read. Every OTHER managed field is still refused inside
@@ -276,15 +469,23 @@ export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<s
   const fields = args.fields ?? {};
   const stateViaRawFields = 'System.State' in fields;
   const fieldsForOps = stateViaRawFields ? Object.fromEntries(Object.entries(fields).filter(([name]) => name !== 'System.State')) : fields;
-  let ops = buildWriteOps({ ...args, fields: fieldsForOps }); if (!ops.length && !stateViaRawFields) throw new Error('nothing to write: no fields, state, comment, or relations were supplied');
+  let ops = buildWriteOps({ ...args, fields: fieldsForOps }); if (!ops.length && !stateViaRawFields && args.removePredecessor === undefined && args.removeRelated === undefined) throw new Error('nothing to write: no fields, state, comment, or relations were supplied');
   const c = await getClient();
   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'];
+  // The tool name IS the type: writing a PBI through `..._feature` is refused
+  // by name rather than silently landing on the item.
+  if (currentType !== type) {
+    throw new Error(`work item ${args.id} is a ${currentType}; write it with the workitem_create_or_update_${TOOL_SUFFIX[currentType]} tool`);
+  }
+  const currentState = current.fields?.['System.State']
+  // Per-type mandatory fields on an update (Tarun, 2026-10-15).
+  assertMandatoryOnUpdate(type, currentState, args.state ?? currentState, args);
   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);
+    assertPlanFieldsAllowed();
   }
   // FENCE 1: System.State via raw fields on a gated type. Features keep the
   // generic managed-field refusal instead; their ladder runs through the
@@ -297,7 +498,6 @@ 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.
-  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') {
@@ -346,13 +546,31 @@ export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<s
       .map((relation: any, index: number) => relation.rel === 'System.LinkTypes.Hierarchy-Reverse' ? index : -1)
       .filter((index: number) => index >= 0)
       .sort((left: number, right: number) => right - left);
-    const parentAdd = ops.find((operation) => operation.path === '/relations/-' && operation.value?.rel === 'System.LinkTypes.Hierarchy-Reverse');
+    // buildWriteOps emitted the Hierarchy-Reverse add for every parentId, so the find always hits.
+    const parentAdd = ops.find((operation) => operation.path === '/relations/-' && operation.value?.rel === 'System.LinkTypes.Hierarchy-Reverse')!;
     ops = [
       ...ops.filter((operation) => operation !== parentAdd),
       ...oldParentIndexes.map((index: number) => ({ op: 'remove', path: `/relations/${index}` })),
-      ...(parentAdd ? [parentAdd] : []),
+      parentAdd,
     ];
   }
+  // az698: --remove-predecessor / --remove-related drop a single relation
+  // link by id. The relation index comes from the LIVE read of `current.relations`
+  // (mirrors the parent-remove pattern above), and the op is idempotent: a
+  // remove on an id that is not present is a no-op (zero ops added), and the
+  // PATCH still lands for the rest of the write. L1–L4 re-validation below
+  // uses the post-write set (current ∪ added − removed) for the L4 check.
+  for (const [rel, removeId] of [
+    ['System.LinkTypes.Dependency-Reverse', args.removePredecessor],
+    ['System.LinkTypes.Related', args.removeRelated],
+  ] as const) {
+    if (removeId === undefined) continue;
+    const indexes = (current.relations ?? [])
+      .map((relation: any, index: number) => relation.rel === rel && Number(/(\d+)\/?$/.exec(relation.url ?? '')?.[1]) === removeId ? index : -1)
+      .filter((index: number) => index >= 0)
+      .sort((left: number, right: number) => right - left);
+    for (const index of indexes) ops.push({ op: 'remove', path: `/relations/${index}` });
+  }
   const warnings: string[] = [];
   if (currentType === 'Bug') {
     // L4 (hard, in any state): a Bug under 'Fixes to closed Features'
@@ -360,8 +578,14 @@ export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<s
     // 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) {
+      // az698: the post-write Related set is current ∪ added − removed. A
+      // --remove-related that would clear the last Related link to the
+      // Responsible Feature is refused here, before any PATCH, with the
+      // same L4 wording the add path uses.
+      const relatedAfter = new Set(relationIds(current, 'System.LinkTypes.Related'));
+      for (const id of args.related ?? []) relatedAfter.add(id);
+      if (args.removeRelated !== undefined) relatedAfter.delete(args.removeRelated);
+      if (!relatedAfter.size) {
         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 ?? [])])];
@@ -375,8 +599,11 @@ export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<s
   } 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);
+    // az698: a --remove-predecessor is part of the post-write set.
+    const predecessorAfter = new Set(relationIds(current, 'System.LinkTypes.Dependency-Reverse'));
+    for (const id of args.predecessors) predecessorAfter.add(id);
+    if (args.removePredecessor !== undefined) predecessorAfter.delete(args.removePredecessor);
+    if (!predecessorAfter.size && 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');
   const updatedView = formatItem(updated, false);
@@ -384,6 +611,28 @@ export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<s
   return JSON.stringify(updatedView, null, 2);
 }
 
+/** Create or update a Feature under its Epic (Tarun's per-type write surface).
+ *  Mandatory: title, parentId, priority, description (intent.md shape) on
+ *  create and while the Feature is at New; acceptanceCriteria plus the three
+ *  plan fields on the New → In Progress move; a comment on every update. */
+export function workitemCreateOrUpdateFeature(args: WorkItemFeatureWriteArgs): Promise<string> {
+  return writeWorkItem('Feature', args);
+}
+
+/** Create or update a PBI under its Feature. Mandatory on create: title,
+ *  parentId, description (item/*.md shape), effort in days. A comment is
+ *  mandatory on every update. */
+export function workitemCreateOrUpdatePbi(args: WorkItemPbiWriteArgs): Promise<string> {
+  return writeWorkItem('Product Backlog Item', args);
+}
+
+/** Create or update a Bug under its Feature (usually a Fixes Feature).
+ *  Mandatory on create: title, parentId, description (item/*.md shape), effort
+ *  in days. A comment is mandatory on every update. */
+export function workitemCreateOrUpdateBug(args: WorkItemBugWriteArgs): Promise<string> {
+  return writeWorkItem('Bug', args);
+}
+
 /** 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');