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

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
@@ -32,20 +35,125 @@ 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). 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 ?? '');
 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;
+  /** 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[];
 }
 function formatItem(wi: any, raw: boolean): WorkItemView {
   const fields = wi.fields ?? {};
@@ -59,7 +167,31 @@ 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'];
+  // 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;
 }
@@ -95,10 +227,19 @@ 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);
+  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`);
     add(field, value);
@@ -111,36 +252,216 @@ function buildWriteOps(args: WorkItemWriteArgs): any[] {
   return ops;
 }
 
-export async function workitemCreateOrUpdate(args: WorkItemWriteArgs): Promise<string> {
+/**
+ * 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: { 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');
+  }
+  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');
+  }
+}
+
+/** 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
-    // 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).
-    if (args.type !== 'Feature' && args.fields !== undefined && 'System.State' in args.fields) {
+    // 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 (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') {
-      if (args.state !== undefined && args.state !== 'New') {
-        const violations = evaluateWorkflowTransition(args.type, 'New', args.state)
-        if (violations.length) throw new Error(formatWorkflowRefusal(violations))
-      }
+    // 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.
+    assertCreateState(type, args.state);
+    // T3: plan fields are Feature-only (type is known at create).
+    if (type !== 'Feature' && (args.planRevision !== undefined || args.planHash !== undefined || args.baselineSha !== undefined)) {
+      assertPlanFieldsAllowed();
     }
-    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(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 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 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 (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 (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(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
@@ -148,13 +469,27 @@ 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'];
-  // FENCE 1: System.State via raw fields on a gated type. Features carry no
-  // flags and keep the generic managed-field refusal instead.
+  // 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();
+  }
+  // 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 +498,36 @@ 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']
+  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,17 +537,217 @@ 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)
       .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'
+    // 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) {
+      // 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 ?? [])])];
+      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.
+    // 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');
-  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);
+}
+
+/** 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');
+  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);
 }