@mcp-consultant-tools/azure-devops 30.0.0-beta.9 → 31.0.0-beta.2

package/build/sync/markdown-serializer.js

@@ -2,32 +2,51 @@
  * Markdown Serialization Utilities
  *
  * Convert between ADO work items and local markdown files.
- * Uses YAML frontmatter for metadata and markdown sections for content.
- */
-import { isHtmlContent, getAdditionalFieldConfig, ADDITIONAL_FIELD_DISPLAY_NAMES } from './html-detection.js';
-/**
- * Simple YAML serializer for frontmatter
- * Handles basic types: string, number, boolean, arrays
+ *
+ * Files use YAML frontmatter (scalar fields — ADO refnames or friendly
+ * aliases) + body sections (long text fields tagged with
+ * `<!-- ado-field: REFNAME -->` comments). The sync engine is generic:
+ * any field named in the file is pushed to ADO, any field not named is
+ * left alone.
+ *
+ * Legacy files (pre-annotation) are detected and parsed via a
+ * legacy-mappings fallback table. They auto-upgrade to the annotated
+ * format on the next pull.
  */
-function serializeFrontmatter(data) {
+import { isHtmlContent } from './html-detection.js';
+import { parseAnnotations, hasAnnotations, serializeAnnotatedSection, } from './annotation-parser.js';
+import { isReservedKey, resolveRefname, } from './field-aliases.js';
+import { resolveLegacyHeading } from './legacy-mappings.js';
+import { applyTemplatePlaceholders, loadTemplate, } from './template-loader.js';
+// ---------------------------------------------------------------------------
+// YAML helpers (frontmatter)
+// ---------------------------------------------------------------------------
+function serializeFrontmatter(data, order) {
     const lines = ['---'];
-    for (const [key, value] of Object.entries(data)) {
+    const orderedKeys = order ? [...order, ...Object.keys(data).filter((k) => !order.includes(k))] : Object.keys(data);
+    for (const key of orderedKeys) {
+        if (!(key in data))
+            continue;
+        const value = data[key];
         if (value === undefined || value === null)
             continue;
         if (Array.isArray(value)) {
             if (value.length === 0)
                 continue;
             lines.push(`${key}:`);
-            for (const item of value) {
+            for (const item of value)
                 lines.push(`- ${item}`);
-            }
         }
         else if (typeof value === 'string') {
-            // Quote strings that might be parsed as other types or contain special chars
-            if (value.includes(':') || value.includes('#') || value.includes('\n') ||
-                value.match(/^[\d.]+$/) || value === 'true' || value === 'false' ||
-                value === 'null' || value === '') {
-                lines.push(`${key}: "${value.replace(/"/g, '\\"')}"`);
+            if (value.includes(':') ||
+                value.includes('#') ||
+                value.includes('\n') ||
+                value.match(/^[\d.]+$/) ||
+                value === 'true' ||
+                value === 'false' ||
+                value === 'null' ||
+                value === '') {
+                lines.push(`${key}: "${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`);
             }
             else {
                 lines.push(`${key}: ${value}`);
@@ -40,19 +59,16 @@ function serializeFrontmatter(data) {
     lines.push('---');
     return lines.join('\n');
 }
-/**
- * Simple YAML parser for frontmatter
- */
 function parseFrontmatter(yamlContent) {
     const result = {};
     const lines = yamlContent.split('\n');
     let currentKey = null;
     let currentArray = null;
+    // Key regex supports ADO refnames with dots (e.g. System.Title, Custom.AgenticData).
+    const keyRe = /^([A-Za-z_][A-Za-z0-9_.\-]*)\s*:\s*(.*)?$/;
     for (const line of lines) {
-        // Skip empty lines
         if (!line.trim())
             continue;
-        // Array item
         if (line.match(/^\s*-\s+/)) {
             if (currentKey && currentArray !== null) {
                 const value = line.replace(/^\s*-\s+/, '').trim();
@@ -60,16 +76,12 @@ function parseFrontmatter(yamlContent) {
             }
             continue;
         }
-        // Key-value pair
-        const match = line.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*:\s*(.*)?$/);
+        const match = line.match(keyRe);
         if (match) {
-            // Save previous array if any
-            if (currentKey && currentArray !== null) {
+            if (currentKey && currentArray !== null)
                 result[currentKey] = currentArray;
-            }
             currentKey = match[1];
             const rawValue = match[2]?.trim();
-            // Check if this is start of array (no value after colon)
             if (!rawValue) {
                 currentArray = [];
             }
@@ -79,655 +91,705 @@ function parseFrontmatter(yamlContent) {
             }
         }
     }
-    // Save final array if any
-    if (currentKey && currentArray !== null) {
+    if (currentKey && currentArray !== null)
         result[currentKey] = currentArray;
-    }
     return result;
 }
-/**
- * Parse a YAML value string to appropriate type
- */
 function parseYamlValue(value) {
-    // Remove quotes and handle escape sequences
-    if ((value.startsWith('"') && value.endsWith('"')) ||
-        (value.startsWith("'") && value.endsWith("'"))) {
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
         return value.slice(1, -1).replace(/\\\\/g, '\\').replace(/\\"/g, '"');
     }
-    // Boolean
     if (value === 'true')
         return true;
     if (value === 'false')
         return false;
-    // Null
     if (value === 'null' || value === '~')
         return null;
-    // Number
     if (value.match(/^-?\d+$/))
         return parseInt(value, 10);
     if (value.match(/^-?\d+\.\d+$/))
         return parseFloat(value);
     return value;
 }
+// ---------------------------------------------------------------------------
+// Field coercion (ADO value ↔ frontmatter value)
+// ---------------------------------------------------------------------------
+/**
+ * Convert a raw ADO field value to a frontmatter-writable scalar or array.
+ * Handles the one weird case: `System.AssignedTo` comes back as an object
+ * `{displayName, uniqueName, ...}`; frontmatter shows the displayName.
+ * `System.Tags` is a semicolon-separated string; frontmatter shows an array.
+ */
+function adoValueToFrontmatter(refname, raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return null;
+    if (refname === 'System.AssignedTo') {
+        if (typeof raw === 'object' && raw.displayName)
+            return raw.displayName;
+        if (typeof raw === 'string')
+            return raw;
+        return null;
+    }
+    if (refname === 'System.Tags') {
+        if (typeof raw !== 'string')
+            return null;
+        return raw.split(';').map((t) => t.trim()).filter((t) => t);
+    }
+    if (typeof raw === 'object')
+        return String(raw);
+    return raw;
+}
+/**
+ * Convert a frontmatter value back to the shape ADO expects in a PATCH.
+ */
+function frontmatterValueToAdo(refname, value) {
+    if (refname === 'System.Tags' && Array.isArray(value)) {
+        return value.join('; ');
+    }
+    return value;
+}
+/**
+ * Stable comparison between a frontmatter value and the current ADO value.
+ */
+function fieldEquals(refname, local, remote) {
+    const remoteNorm = adoValueToFrontmatter(refname, remote);
+    if (local === undefined && (remoteNorm === null || remoteNorm === ''))
+        return true;
+    if (local === undefined || remoteNorm === null)
+        return false;
+    if (Array.isArray(local) && Array.isArray(remoteNorm)) {
+        return local.length === remoteNorm.length && local.every((v, i) => v === remoteNorm[i]);
+    }
+    return String(local) === String(remoteNorm);
+}
+// ---------------------------------------------------------------------------
+// DOWN: ADO work item → markdown file
+// ---------------------------------------------------------------------------
 /**
- * Convert an ADO work item to markdown file content
+ * Serialize an ADO work item to an annotated markdown file.
  *
- * @param workItem - The work item from ADO API
- * @param revision - The revision number
- * @returns Object with markdown content and list of skipped fields (if any were HTML)
+ * Follows the template for `fields['System.WorkItemType']`. Frontmatter
+ * order and body-section order come from the template. Fields the ADO
+ * response carries but the template doesn't mention are appended to the
+ * frontmatter with a discovery comment (see D4 in the design plan).
  */
 export function workItemToMarkdown(workItem, revision) {
     const fields = workItem.fields || {};
-    const fieldConfig = getAdditionalFieldConfig();
+    const workItemType = fields['System.WorkItemType'] || 'Unknown';
+    const project = fields['System.TeamProject'] || '';
+    const template = applyTemplatePlaceholders(loadTemplate(workItemType), { project });
     const skippedFields = [];
-    // Build frontmatter data
-    const frontmatter = {
-        id: workItem.id,
-        title: fields['System.Title'] || '',
-        type: fields['System.WorkItemType'] || 'Unknown',
-        state: fields['System.State'] || '',
-        url: workItem._links?.html?.href || `https://dev.azure.com/_workitems/edit/${workItem.id}`,
-    };
-    // Optional fields
-    if (fields['System.AssignedTo']?.displayName) {
-        frontmatter.assignedTo = fields['System.AssignedTo'].displayName;
-    }
-    if (fields['Microsoft.VSTS.Scheduling.StoryPoints'] !== undefined) {
-        frontmatter.storyPoints = fields['Microsoft.VSTS.Scheduling.StoryPoints'];
-    }
+    // ----- Frontmatter -----
+    const fmData = {};
+    const fmOrder = [];
+    // Reserved metadata (always at top)
+    fmData.id = workItem.id;
+    fmOrder.push('id');
+    fmData.type = workItemType;
+    fmOrder.push('type');
     if (fields['System.Parent']) {
-        frontmatter.parent = fields['System.Parent'];
-    }
-    // MoSCoW priority (custom field - varies by org)
-    const moscowField = fields['Custom.MoSCoW'] || fields['Microsoft.VSTS.Common.Priority'];
-    if (moscowField) {
-        frontmatter.moscow = moscowField;
-    }
-    // Tags
-    if (fields['System.Tags']) {
-        frontmatter.tags = fields['System.Tags'].split(';').map((t) => t.trim()).filter((t) => t);
-    }
-    if (fields['System.AreaPath']) {
-        frontmatter.areaPath = fields['System.AreaPath'];
-    }
-    if (fields['System.IterationPath']) {
-        frontmatter.iterationPath = fields['System.IterationPath'];
-    }
-    // Sync metadata
-    frontmatter.lastSyncedRevision = revision;
-    frontmatter.lastSyncedAt = new Date().toISOString();
-    // Build content sections
-    const description = fields['System.Description'] || '';
-    const acceptanceCriteria = fields['Microsoft.VSTS.Common.AcceptanceCriteria'] || '';
-    let content = serializeFrontmatter(frontmatter);
-    content += '\n\n# Description\n\n';
-    content += description.trim() || '_No description provided._';
-    content += '\n\n---\n\n# Acceptance Criteria\n\n';
-    content += acceptanceCriteria.trim() || '_No acceptance criteria provided._';
-    // Add additional fields if present and in markdown format
-    const addOptionalSection = (fieldName, displayName, sectionTitle) => {
-        const fieldContent = fields[fieldName];
-        if (!fieldContent || !fieldContent.trim()) {
-            return; // Field not present, skip silently
+        fmData.parent = fields['System.Parent'];
+        fmOrder.push('parent');
+    }
+    fmData.url = workItem._links?.html?.href || `https://dev.azure.com/_workitems/edit/${workItem.id}`;
+    fmOrder.push('url');
+    const bodyRefnames = new Set(template.bodyFields.map((f) => f.refname));
+    // Template-declared frontmatter fields (in template order)
+    for (const templateKey of template.frontmatterOrder) {
+        if (templateKey === 'type')
+            continue; // already emitted above
+        const refname = resolveRefname(templateKey);
+        if (refname === null)
+            continue; // reserved keys handled elsewhere
+        if (bodyRefnames.has(refname))
+            continue; // body fields don't go in frontmatter
+        const raw = fields[refname];
+        const value = adoValueToFrontmatter(refname, raw);
+        if (value === null || value === '') {
+            // Keep the template default as an empty placeholder so the agent sees the slot.
+            fmData[templateKey] = template.frontmatterDefaults[templateKey] ?? '';
         }
-        if (isHtmlContent(fieldContent)) {
-            skippedFields.push(`${displayName} (HTML)`);
-            return; // HTML format, skip with warning
+        else {
+            fmData[templateKey] = value;
         }
-        content += `\n\n---\n\n# ${sectionTitle}\n\n`;
-        content += fieldContent.trim();
-    };
-    addOptionalSection(fieldConfig.howToTest, ADDITIONAL_FIELD_DISPLAY_NAMES.howToTest, 'How to Test');
-    addOptionalSection(fieldConfig.predeploymentSteps, ADDITIONAL_FIELD_DISPLAY_NAMES.predeploymentSteps, 'Predeployment Steps');
-    addOptionalSection(fieldConfig.postdeploymentSteps, ADDITIONAL_FIELD_DISPLAY_NAMES.postdeploymentSteps, 'Postdeployment Steps');
-    addOptionalSection(fieldConfig.deploymentInformation, ADDITIONAL_FIELD_DISPLAY_NAMES.deploymentInformation, 'Deployment Information');
+        fmOrder.push(templateKey);
+    }
+    // ADO fields not in the template — surface as discovery entries.
+    // Short scalars go to frontmatter; long-form text goes to extra body sections.
+    const emittedRefnames = new Set();
+    for (const templateKey of template.frontmatterOrder) {
+        const r = resolveRefname(templateKey);
+        if (r)
+            emittedRefnames.add(r);
+    }
+    const extraBodyFields = [];
+    for (const [refname, raw] of Object.entries(fields)) {
+        if (emittedRefnames.has(refname))
+            continue;
+        if (bodyRefnames.has(refname))
+            continue;
+        if (isIgnoredSystemField(refname))
+            continue;
+        if (looksLikeBodyField(raw)) {
+            extraBodyFields.push({
+                refname,
+                heading: refnameToHeading(refname),
+                content: String(raw),
+                isHtml: isHtmlContent(String(raw)),
+            });
+            continue;
+        }
+        const value = adoValueToFrontmatter(refname, raw);
+        if (value === null || value === '')
+            continue;
+        fmData[refname] = value;
+        fmOrder.push(refname);
+    }
+    // Sync metadata (always at bottom)
+    fmData.lastSyncedRevision = revision;
+    fmOrder.push('lastSyncedRevision');
+    fmData.lastSyncedAt = new Date().toISOString();
+    fmOrder.push('lastSyncedAt');
+    // ----- Body -----
+    let content = serializeFrontmatter(fmData, fmOrder);
     content += '\n';
+    for (const bodyField of template.bodyFields) {
+        const raw = fields[bodyField.refname] || '';
+        if (!raw || !String(raw).trim()) {
+            content += '\n' + serializeAnnotatedSection(bodyField.heading, bodyField.refname, '');
+            continue;
+        }
+        if (isHtmlContent(raw)) {
+            skippedFields.push(`${bodyField.heading} (HTML)`);
+            content += '\n' + serializeAnnotatedSection(bodyField.heading, bodyField.refname, '');
+            continue;
+        }
+        content += '\n' + serializeAnnotatedSection(bodyField.heading, bodyField.refname, String(raw).trim());
+    }
+    // Extra body fields discovered from the ADO response (not in the template).
+    for (const extra of extraBodyFields) {
+        if (extra.isHtml) {
+            skippedFields.push(`${extra.heading} (HTML)`);
+            content += '\n' + serializeAnnotatedSection(extra.heading, extra.refname, '');
+            continue;
+        }
+        content += '\n' + serializeAnnotatedSection(extra.heading, extra.refname, extra.content.trim());
+    }
     return { content, skippedFields };
 }
 /**
- * Parse a markdown file to extract frontmatter and content sections
+ * Turn an ADO refname into a human-friendly heading.
+ * `Custom.AgenticData` → "Agentic Data".
+ * `Microsoft.VSTS.TCM.SystemInfo` → "System Info".
+ * `System.Description` → "Description".
  */
+function refnameToHeading(refname) {
+    const last = refname.split('.').pop() || refname;
+    // Split camelCase / PascalCase at word boundaries.
+    return last
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .trim();
+}
+function isIgnoredSystemField(refname) {
+    // Board/kanban state per work item — team-specific & not user-editable.
+    if (refname.startsWith('WEF_'))
+        return true;
+    // Computed hierarchy fields (derived from AreaPath/IterationPath).
+    if (refname.startsWith('System.AreaLevel') || refname.startsWith('System.IterationLevel'))
+        return true;
+    if (refname === 'System.AreaId' || refname === 'System.IterationId' || refname === 'System.NodeName')
+        return true;
+    // Audit and revision metadata — ADO controls these.
+    switch (refname) {
+        case 'System.Id':
+        case 'System.Rev':
+        case 'System.WorkItemType':
+        case 'System.TeamProject':
+        case 'System.CreatedBy':
+        case 'System.CreatedDate':
+        case 'System.ChangedBy':
+        case 'System.ChangedDate':
+        case 'System.AuthorizedAs':
+        case 'System.AuthorizedDate':
+        case 'System.RevisedDate':
+        case 'System.BoardColumn':
+        case 'System.BoardColumnDone':
+        case 'System.BoardLane':
+        case 'System.CommentCount':
+        case 'System.Watermark':
+        case 'System.PersonId':
+        case 'System.History':
+        case 'System.Reason':
+        case 'System.Parent': // surfaced as friendly `parent` in frontmatter
+        case 'Microsoft.VSTS.Common.StateChangeDate':
+        case 'Microsoft.VSTS.Common.ActivatedDate':
+        case 'Microsoft.VSTS.Common.ActivatedBy':
+        case 'Microsoft.VSTS.Common.ResolvedDate':
+        case 'Microsoft.VSTS.Common.ResolvedBy':
+        case 'Microsoft.VSTS.Common.ClosedDate':
+        case 'Microsoft.VSTS.Common.ClosedBy':
+            return true;
+        default:
+            return false;
+    }
+}
+/**
+ * Heuristic: an unknown ADO field should be surfaced as a body section (not
+ * a frontmatter scalar) when its value is a long-form text field. A single
+ * newline or any HTML pattern is strong evidence that the content belongs
+ * in body.
+ */
+function looksLikeBodyField(value) {
+    if (typeof value !== 'string')
+        return false;
+    if (value.includes('\n'))
+        return true;
+    if (value.length > 200)
+        return true;
+    if (isHtmlContent(value))
+        return true;
+    return false;
+}
+// ---------------------------------------------------------------------------
+// UP: markdown file → ADO (parse)
+// ---------------------------------------------------------------------------
 export function parseWorkItemMarkdown(content) {
-    // Extract frontmatter between ---
     const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
     if (!frontmatterMatch) {
         throw new Error('Invalid work item markdown file: missing YAML frontmatter');
     }
     const frontmatterRaw = frontmatterMatch[1];
     const frontmatterData = parseFrontmatter(frontmatterRaw);
-    // Validate required fields
     if (!frontmatterData.id || typeof frontmatterData.id !== 'number') {
         throw new Error('Invalid work item markdown file: missing or invalid "id" in frontmatter');
     }
-    const frontmatter = {
-        id: frontmatterData.id,
-        title: frontmatterData.title || '',
-        type: frontmatterData.type || 'Unknown',
-        state: frontmatterData.state || '',
-        url: frontmatterData.url || '',
-        assignedTo: frontmatterData.assignedTo,
-        storyPoints: frontmatterData.storyPoints,
-        parent: frontmatterData.parent,
-        moscow: frontmatterData.moscow,
-        tags: frontmatterData.tags,
-        areaPath: frontmatterData.areaPath,
-        iterationPath: frontmatterData.iterationPath,
-        lastSyncedRevision: frontmatterData.lastSyncedRevision || 0,
-        lastSyncedAt: frontmatterData.lastSyncedAt || '',
-    };
-    // Extract content after frontmatter
-    const contentAfterFrontmatter = content.slice(frontmatterMatch[0].length);
-    // Helper to extract a section by heading
-    // Looks for # SectionName and captures content until the next # heading or end of file
-    const extractSection = (sectionName) => {
-        // Match section heading followed by content, stopping at next level-1 heading or end of file
-        // Note: \n#\s+ only matches level-1 headings (# Foo), not ## or ### — those are preserved as content
-        // [^\S\n]* matches horizontal whitespace only (not \n) to avoid consuming the blank line after heading
-        const regex = new RegExp(`#\\s+${escapeRegex(sectionName)}[^\\S\\n]*\\n([\\s\\S]*?)(?=\\n#\\s+|$)`, 'i');
-        const match = contentAfterFrontmatter.match(regex);
-        if (!match)
-            return undefined;
-        // Strip trailing --- separators (visual formatting between sections, not content)
-        const sectionContent = match[1].trim().replace(/(\n---\s*)+$/, '').trim();
-        // Return undefined if it's just the placeholder text
-        if (sectionContent === `_No ${sectionName.toLowerCase()} provided._`) {
-            return undefined;
-        }
-        return sectionContent || undefined;
-    };
-    // Extract primary sections
-    let description = extractSection('Description');
-    if (description === undefined) {
-        // Only use fallback if there's genuinely no # Description heading at all
-        const hasDescriptionHeading = /(?:^|\n)#\s+Description[^\S\n]*\n/i.test(contentAfterFrontmatter);
-        if (!hasDescriptionHeading) {
-            description = extractFallbackDescription(contentAfterFrontmatter);
-        }
-        else {
-            description = '';
+    const body = content.slice(frontmatterMatch[0].length);
+    const workItemType = frontmatterData.type || 'Unknown';
+    // Build the scalar fieldMap from frontmatter (aliases resolved).
+    const fieldMap = {};
+    for (const [key, rawValue] of Object.entries(frontmatterData)) {
+        if (isReservedKey(key))
+            continue;
+        if (rawValue === undefined || rawValue === null)
+            continue;
+        const refname = resolveRefname(key);
+        if (!refname)
+            continue;
+        fieldMap[refname] = rawValue;
+    }
+    // Parse body sections.
+    let bodyFieldMap = {};
+    let localOnlySections = [];
+    if (hasAnnotations(body)) {
+        const parsed = parseAnnotations(body);
+        for (const section of parsed.annotated) {
+            if (!section.content.trim())
+                continue;
+            if (bodyFieldMap[section.refname]) {
+                bodyFieldMap[section.refname] += '\n\n' + section.content;
+            }
+            else {
+                bodyFieldMap[section.refname] = section.content;
+            }
         }
+        localOnlySections = parsed.localOnly;
     }
-    if (description === '_No description provided._') {
-        description = '';
-    }
-    let acceptanceCriteria = extractSection('Acceptance Criteria') || '';
-    if (acceptanceCriteria === '_No acceptance criteria provided._') {
-        acceptanceCriteria = '';
-    }
-    // Extract additional fields (optional)
-    const additionalFields = {};
-    const howToTest = extractSection('How to Test');
-    if (howToTest)
-        additionalFields.howToTest = howToTest;
-    const predeploymentSteps = extractSection('Predeployment Steps');
-    if (predeploymentSteps)
-        additionalFields.predeploymentSteps = predeploymentSteps;
-    const postdeploymentSteps = extractSection('Postdeployment Steps');
-    if (postdeploymentSteps)
-        additionalFields.postdeploymentSteps = postdeploymentSteps;
-    const deploymentInformation = extractSection('Deployment Information');
-    if (deploymentInformation)
-        additionalFields.deploymentInformation = deploymentInformation;
+    else {
+        // Legacy parse: map `#` or `##` headings via the legacy table.
+        bodyFieldMap = parseLegacyBody(body, workItemType, localOnlySections);
+    }
+    // Populate back-compat fields.
+    const frontmatter = buildLegacyFrontmatterView(frontmatterData, fieldMap);
+    const description = bodyFieldMap['System.Description'] || '';
+    const reproSteps = bodyFieldMap['Microsoft.VSTS.TCM.ReproSteps'] || '';
+    const acceptanceCriteria = bodyFieldMap['Microsoft.VSTS.Common.AcceptanceCriteria'] || '';
+    const additionalFields = {
+        howToTest: bodyFieldMap['Custom.Howtotest'],
+        deploymentInformation: bodyFieldMap['Custom.Deploymentinformation'],
+        predeploymentSteps: bodyFieldMap['Custom.7519d1bc-5305-4905-822b-2b380e61b154'],
+        postdeploymentSteps: bodyFieldMap['Custom.abd6763f-a242-4938-85ed-bda419e34e7e'],
+    };
     return {
         frontmatter,
+        fieldMap,
+        bodyFieldMap,
+        localOnlySections,
+        workItemType,
         description,
+        reproSteps,
         acceptanceCriteria,
         additionalFields,
         rawContent: content,
     };
 }
 /**
- * Fallback description extraction for files without a # Description heading.
- * Returns all content before the first recognized section heading, with
- * HTML template comments stripped.
+ * Parse legacy `# Heading` sections using the legacy-mappings fallback.
  */
-const RECOGNIZED_SECTIONS = [
-    'Acceptance Criteria',
-    'How to Test',
-    'Predeployment Steps',
-    'Postdeployment Steps',
-    'Deployment Information',
-];
-function extractFallbackDescription(contentAfterFrontmatter) {
-    // Find the earliest recognized section heading
-    let earliestIndex = contentAfterFrontmatter.length;
-    for (const section of RECOGNIZED_SECTIONS) {
-        const regex = new RegExp(`\\n#\\s+${escapeRegex(section)}\\s*\\n`, 'i');
-        const match = contentAfterFrontmatter.match(regex);
-        if (match && match.index !== undefined && match.index < earliestIndex) {
-            earliestIndex = match.index;
+function parseLegacyBody(body, workItemType, localOut) {
+    const lines = body.split('\n');
+    const headings = [];
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(/^(#{1,2})\s+(.+?)\s*$/);
+        if (m)
+            headings.push({ index: i, text: m[2].trim(), level: m[1].length });
+    }
+    const out = {};
+    for (let h = 0; h < headings.length; h++) {
+        const current = headings[h];
+        const next = headings[h + 1];
+        const bodyLines = lines.slice(current.index + 1, next ? next.index : lines.length);
+        const sectionContent = stripLegacySeparators(bodyLines.join('\n')).trim();
+        if (!sectionContent)
+            continue;
+        if (isPlaceholder(sectionContent, current.text))
+            continue;
+        const refname = resolveLegacyHeading(current.text, workItemType);
+        if (refname) {
+            if (out[refname]) {
+                out[refname] += '\n\n' + sectionContent;
+            }
+            else {
+                out[refname] = sectionContent;
+            }
+        }
+        else {
+            localOut.push({ heading: current.text, content: sectionContent, lineIndex: current.index });
         }
     }
-    let fallback = contentAfterFrontmatter.slice(0, earliestIndex);
-    // Strip only template-generated HTML comments (frontmatter hints), preserve user comments
-    fallback = fallback.replace(/<!--\s*Optional frontmatter fields[\s\S]*?-->/g, '');
-    // Strip trailing --- separators
-    fallback = fallback.replace(/(\n---\s*)+$/, '');
-    return fallback.trim();
+    return out;
 }
-/**
- * Escape special regex characters in a string
- */
-function escapeRegex(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+function stripLegacySeparators(content) {
+    return content.replace(/(\n\s*---\s*)+\s*$/, '').replace(/^\s*(---\s*\n)+/, '');
 }
-/**
- * Convert ADO comments to a read-only markdown file
- */
-export function commentsToMarkdown(workItem, comments) {
-    const fields = workItem.fields || {};
-    const frontmatter = {
-        id: workItem.id,
-        title: fields['System.Title'] || '',
-        commentCount: comments.length,
-        lastSyncedAt: new Date().toISOString(),
+function isPlaceholder(content, heading) {
+    const trimmed = content.trim();
+    return (trimmed === `_No ${heading.toLowerCase()} provided._` ||
+        trimmed === `[Your ${heading.toLowerCase()} here]`);
+}
+function buildLegacyFrontmatterView(raw, fieldMap) {
+    const tagsRaw = fieldMap['System.Tags'];
+    const tags = Array.isArray(tagsRaw)
+        ? tagsRaw
+        : typeof tagsRaw === 'string' && tagsRaw
+            ? tagsRaw.split(';').map((t) => t.trim()).filter(Boolean)
+            : undefined;
+    return {
+        id: raw.id,
+        title: fieldMap['System.Title'] || '',
+        type: raw.type || 'Unknown',
+        state: fieldMap['System.State'] || '',
+        url: raw.url || '',
+        assignedTo: fieldMap['System.AssignedTo'],
+        storyPoints: fieldMap['Microsoft.VSTS.Scheduling.StoryPoints'],
+        parent: raw.parent,
+        moscow: fieldMap['Custom.MoSCoW'],
+        tags,
+        areaPath: fieldMap['System.AreaPath'],
+        iterationPath: fieldMap['System.IterationPath'],
+        lastSyncedRevision: raw.lastSyncedRevision || 0,
+        lastSyncedAt: raw.lastSyncedAt || '',
     };
-    let content = serializeFrontmatter(frontmatter);
-    content += '\n\n# Comments\n\n';
-    content += '> **NOTE**: This file is read-only. Comments cannot be pushed back to ADO.\n\n';
-    if (comments.length === 0) {
-        content += '_No comments on this work item._\n';
-    }
-    else {
-        // Sort comments by date (oldest first)
-        const sortedComments = [...comments].sort((a, b) => {
-            const dateA = new Date(a.createdDate || a.publishedDate || 0);
-            const dateB = new Date(b.createdDate || b.publishedDate || 0);
-            return dateA.getTime() - dateB.getTime();
-        });
-        sortedComments.forEach((comment, index) => {
-            content += '---\n\n';
-            content += `## Comment #${index + 1}\n`;
-            content += `**Author**: ${comment.createdBy?.displayName || 'Unknown'}\n`;
-            content += `**Date**: ${comment.createdDate || comment.publishedDate || 'Unknown'}\n\n`;
-            content += `${comment.text || comment.content || ''}\n\n`;
-        });
-    }
-    return content;
 }
-/**
- * Build ADO patch operations from parsed markdown changes
- * Only updates fields that have actually changed.
- * Auto-converts HTML fields to markdown format unless skipAutoConvert is true.
- *
- * @param parsed - Parsed work item file
- * @param currentWorkItem - Current work item from ADO
- * @param skipAutoConvert - Skip automatic HTML-to-markdown conversion (default: false)
- */
+// ---------------------------------------------------------------------------
+// UP: build ADO patch operations
+// ---------------------------------------------------------------------------
 export function buildPatchOperations(parsed, currentWorkItem, skipAutoConvert = false) {
     const operations = [];
     const skippedFields = [];
     const convertedFields = [];
     const currentFields = currentWorkItem.fields || {};
-    const fieldConfig = getAdditionalFieldConfig();
-    // Check Title
-    const currentTitle = currentFields['System.Title'] || '';
-    if (parsed.frontmatter.title !== currentTitle) {
-        operations.push({
-            op: 'replace',
-            path: '/fields/System.Title',
-            value: parsed.frontmatter.title,
-        });
-    }
-    // Check Story Points
-    const currentStoryPoints = currentFields['Microsoft.VSTS.Scheduling.StoryPoints'];
-    const localStoryPoints = parsed.frontmatter.storyPoints;
-    if (localStoryPoints !== undefined && localStoryPoints !== currentStoryPoints) {
-        operations.push({
-            op: currentStoryPoints !== undefined ? 'replace' : 'add',
-            path: '/fields/Microsoft.VSTS.Scheduling.StoryPoints',
-            value: localStoryPoints,
-        });
-    }
-    // Check Description - always try to set markdown format when writing
-    const currentDescription = currentFields['System.Description'] || '';
-    const descriptionIsHtml = isHtmlContent(currentDescription);
-    if (descriptionIsHtml && skipAutoConvert) {
-        // Skip HTML field when skipAutoConvert is true
-        skippedFields.push('Description (HTML in ADO - skipAutoConvert=true)');
-    }
-    else if (parsed.description !== currentDescription || descriptionIsHtml) {
-        // Safety guard: don't push empty content when ADO has existing content
-        if (!parsed.description && currentDescription) {
-            skippedFields.push('Description (local file has no content — skipping to prevent data loss)');
+    const allRefnames = new Set([
+        ...Object.keys(parsed.fieldMap),
+        ...Object.keys(parsed.bodyFieldMap),
+    ]);
+    for (const refname of allRefnames) {
+        const isBodyField = refname in parsed.bodyFieldMap;
+        const localValue = isBodyField
+            ? parsed.bodyFieldMap[refname]
+            : parsed.fieldMap[refname];
+        const currentRaw = currentFields[refname];
+        const currentString = typeof currentRaw === 'string' ? currentRaw : '';
+        const isHtmlField = isBodyField && typeof currentRaw === 'string' && isHtmlContent(currentRaw);
+        if (isHtmlField && skipAutoConvert) {
+            skippedFields.push(`${refname} (HTML in ADO - skipAutoConvert=true)`);
+            continue;
         }
-        else {
-            // Write field value
+        // Data-loss guard: don't overwrite non-empty ADO content with empty local content.
+        const localIsEmpty = localValue === undefined ||
+            localValue === '' ||
+            (Array.isArray(localValue) && localValue.length === 0);
+        if (isBodyField) {
+            if (localIsEmpty && currentString.trim()) {
+                skippedFields.push(`${refname} (local file has no content — skipping to prevent data loss)`);
+                continue;
+            }
+            if (localIsEmpty && !currentString)
+                continue;
+            // Compare stringified body content.
+            if (String(localValue) === currentString && !isHtmlField)
+                continue;
             operations.push({
-                op: currentDescription ? 'replace' : 'add',
-                path: '/fields/System.Description',
-                value: parsed.description,
+                op: currentString ? 'replace' : 'add',
+                path: `/fields/${refname}`,
+                value: String(localValue),
             });
-            // Always set markdown format when writing to ensure ADO renders correctly
             operations.push({
                 op: 'add',
-                path: '/multilineFieldsFormat/System.Description',
+                path: `/multilineFieldsFormat/${refname}`,
                 value: 'Markdown',
             });
-            if (descriptionIsHtml) {
-                convertedFields.push('Description');
-            }
-        }
-    }
-    // Check Acceptance Criteria - always try to set markdown format when writing
-    const currentAC = currentFields['Microsoft.VSTS.Common.AcceptanceCriteria'] || '';
-    const acIsHtml = isHtmlContent(currentAC);
-    if (acIsHtml && skipAutoConvert) {
-        // Skip HTML field when skipAutoConvert is true
-        skippedFields.push('Acceptance Criteria (HTML in ADO - skipAutoConvert=true)');
-    }
-    else if (parsed.acceptanceCriteria !== currentAC || acIsHtml) {
-        // Safety guard: don't push empty content when ADO has existing content
-        if (!parsed.acceptanceCriteria && currentAC) {
-            skippedFields.push('Acceptance Criteria (local file has no content — skipping to prevent data loss)');
+            if (isHtmlField)
+                convertedFields.push(refname);
         }
         else {
-            // Write field value
-            operations.push({
-                op: currentAC ? 'replace' : 'add',
-                path: '/fields/Microsoft.VSTS.Common.AcceptanceCriteria',
-                value: parsed.acceptanceCriteria,
-            });
-            // Always set markdown format when writing to ensure ADO renders correctly
-            operations.push({
-                op: 'add',
-                path: '/multilineFieldsFormat/Microsoft.VSTS.Common.AcceptanceCriteria',
-                value: 'Markdown',
-            });
-            if (acIsHtml) {
-                convertedFields.push('Acceptance Criteria');
+            if (localIsEmpty && (currentRaw === undefined || currentRaw === '' || currentRaw === null)) {
+                continue;
             }
-        }
-    }
-    // Helper to check and add patch operation for additional field
-    // Always tries to set markdown format when writing to a field
-    const checkAdditionalField = (localValue, fieldName, displayName) => {
-        const currentValue = currentFields[fieldName] || '';
-        const localContent = localValue || '';
-        const fieldIsHtml = currentValue && isHtmlContent(currentValue);
-        if (fieldIsHtml && skipAutoConvert) {
-            // Skip HTML field when skipAutoConvert is true
-            skippedFields.push(`${displayName} (HTML in ADO - skipAutoConvert=true)`);
-            return;
-        }
-        if (localContent !== currentValue || fieldIsHtml) {
-            // Safety guard: don't push empty content when ADO has existing content
-            if (!localContent && currentValue) {
-                skippedFields.push(`${displayName} (local file has no content — skipping to prevent data loss)`);
-                return;
+            if (fieldEquals(refname, localValue, currentRaw))
+                continue;
+            if (localIsEmpty && currentRaw !== undefined && currentRaw !== '' && currentRaw !== null) {
+                // For scalar fields, allow setting to empty only when user clearly intended it.
+                // Convention: undefined (key missing) → skip; empty-string key → write empty.
+                if (localValue === undefined)
+                    continue;
             }
-            // Write field value
-            operations.push({
-                op: currentValue ? 'replace' : 'add',
-                path: `/fields/${fieldName}`,
-                value: localContent,
-            });
-            // Always set markdown format when writing to ensure ADO renders correctly
             operations.push({
-                op: 'add',
-                path: `/multilineFieldsFormat/${fieldName}`,
-                value: 'Markdown',
+                op: currentRaw !== undefined && currentRaw !== null && currentRaw !== '' ? 'replace' : 'add',
+                path: `/fields/${refname}`,
+                value: frontmatterValueToAdo(refname, localValue),
             });
-            if (fieldIsHtml) {
-                convertedFields.push(displayName);
-            }
         }
-    };
-    // Check additional fields
-    checkAdditionalField(parsed.additionalFields.howToTest, fieldConfig.howToTest, ADDITIONAL_FIELD_DISPLAY_NAMES.howToTest);
-    checkAdditionalField(parsed.additionalFields.predeploymentSteps, fieldConfig.predeploymentSteps, ADDITIONAL_FIELD_DISPLAY_NAMES.predeploymentSteps);
-    checkAdditionalField(parsed.additionalFields.postdeploymentSteps, fieldConfig.postdeploymentSteps, ADDITIONAL_FIELD_DISPLAY_NAMES.postdeploymentSteps);
-    checkAdditionalField(parsed.additionalFields.deploymentInformation, fieldConfig.deploymentInformation, ADDITIONAL_FIELD_DISPLAY_NAMES.deploymentInformation);
+    }
     return { operations, skippedFields, convertedFields };
 }
-/**
- * Update the lastSyncedRevision in a markdown file content
- */
-export function updateSyncRevision(content, newRevision) {
-    // Update lastSyncedRevision in frontmatter
-    const updatedContent = content.replace(/lastSyncedRevision:\s*\d+/, `lastSyncedRevision: ${newRevision}`);
-    // Update lastSyncedAt timestamp
-    return updatedContent.replace(/lastSyncedAt:\s*[^\n]+/, `lastSyncedAt: ${new Date().toISOString()}`);
-}
-/**
- * Check if a work item frontmatter indicates a new (not yet created) work item
- * New work items don't have an 'id' field
- */
 export function isNewWorkItem(frontmatter) {
     return !frontmatter.id || typeof frontmatter.id !== 'number';
 }
-/**
- * Parse a markdown file for a NEW work item (no id required)
- */
 export function parseNewWorkItemMarkdown(content) {
-    // Extract frontmatter between ---
     const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
     if (!frontmatterMatch) {
         throw new Error('Invalid work item markdown file: missing YAML frontmatter');
     }
-    const frontmatterRaw = frontmatterMatch[1];
-    const frontmatterData = parseFrontmatter(frontmatterRaw);
-    // Validate required fields for new work items
+    const frontmatterData = parseFrontmatter(frontmatterMatch[1]);
     if (!frontmatterData.title || typeof frontmatterData.title !== 'string') {
         throw new Error('New work item files require a "title" field');
     }
-    // Validate parent is a number if present
-    if (frontmatterData.parent !== undefined && frontmatterData.parent !== null && typeof frontmatterData.parent !== 'number') {
+    if (frontmatterData.parent !== undefined &&
+        frontmatterData.parent !== null &&
+        typeof frontmatterData.parent !== 'number') {
         throw new Error('The "parent" field must be a number (work item ID)');
     }
+    const body = content.slice(frontmatterMatch[0].length);
+    const workItemType = frontmatterData.type || 'User Story';
+    const fieldMap = {};
+    for (const [key, rawValue] of Object.entries(frontmatterData)) {
+        if (isReservedKey(key))
+            continue;
+        if (rawValue === undefined || rawValue === null)
+            continue;
+        const refname = resolveRefname(key);
+        if (!refname)
+            continue;
+        fieldMap[refname] = rawValue;
+    }
+    let bodyFieldMap = {};
+    const localOnlySections = [];
+    if (hasAnnotations(body)) {
+        const parsed = parseAnnotations(body);
+        for (const section of parsed.annotated) {
+            if (!section.content.trim())
+                continue;
+            if (isPlaceholder(section.content, section.heading))
+                continue;
+            bodyFieldMap[section.refname] = bodyFieldMap[section.refname]
+                ? bodyFieldMap[section.refname] + '\n\n' + section.content
+                : section.content;
+        }
+        localOnlySections.push(...parsed.localOnly);
+    }
+    else {
+        bodyFieldMap = parseLegacyBody(body, workItemType, localOnlySections);
+    }
+    const tagsRaw = fieldMap['System.Tags'];
+    const tags = Array.isArray(tagsRaw)
+        ? tagsRaw
+        : typeof tagsRaw === 'string' && tagsRaw
+            ? tagsRaw.split(';').map((t) => t.trim()).filter(Boolean)
+            : undefined;
     const frontmatter = {
         title: frontmatterData.title,
-        type: frontmatterData.type || 'User Story',
+        type: workItemType,
         state: frontmatterData.state || 'New',
         parent: frontmatterData.parent ?? undefined,
-        assignedTo: frontmatterData.assignedTo,
-        storyPoints: frontmatterData.storyPoints,
-        moscow: frontmatterData.moscow,
-        tags: frontmatterData.tags,
-        areaPath: frontmatterData.areaPath,
-        iterationPath: frontmatterData.iterationPath,
+        assignedTo: fieldMap['System.AssignedTo'],
+        storyPoints: fieldMap['Microsoft.VSTS.Scheduling.StoryPoints'],
+        moscow: fieldMap['Custom.MoSCoW'],
+        tags,
+        areaPath: fieldMap['System.AreaPath'],
+        iterationPath: fieldMap['System.IterationPath'],
     };
-    // Extract content after frontmatter
-    const contentAfterFrontmatter = content.slice(frontmatterMatch[0].length);
-    // Helper to extract a section by heading (reuse from parseWorkItemMarkdown)
-    const extractSection = (sectionName) => {
-        const regex = new RegExp(`#\\s+${escapeRegex(sectionName)}[^\\S\\n]*\\n([\\s\\S]*?)(?=\\n#\\s+|$)`, 'i');
-        const match = contentAfterFrontmatter.match(regex);
-        if (!match)
-            return undefined;
-        // Strip trailing --- separators (visual formatting between sections, not content)
-        const sectionContent = match[1].trim().replace(/(\n---\s*)+$/, '').trim();
-        if (sectionContent === `_No ${sectionName.toLowerCase()} provided._`) {
-            return undefined;
-        }
-        return sectionContent || undefined;
-    };
-    // Extract primary sections
-    let description = extractSection('Description') || '';
-    if (description === '_No description provided._' || description === '[Your description here]') {
-        description = '';
-    }
-    let acceptanceCriteria = extractSection('Acceptance Criteria') || '';
-    if (acceptanceCriteria === '_No acceptance criteria provided._' || acceptanceCriteria === '[Your acceptance criteria here]') {
-        acceptanceCriteria = '';
-    }
-    // Extract additional fields (optional)
-    const additionalFields = {};
-    const howToTest = extractSection('How to Test');
-    if (howToTest)
-        additionalFields.howToTest = howToTest;
-    const predeploymentSteps = extractSection('Predeployment Steps');
-    if (predeploymentSteps)
-        additionalFields.predeploymentSteps = predeploymentSteps;
-    const postdeploymentSteps = extractSection('Postdeployment Steps');
-    if (postdeploymentSteps)
-        additionalFields.postdeploymentSteps = postdeploymentSteps;
-    const deploymentInformation = extractSection('Deployment Information');
-    if (deploymentInformation)
-        additionalFields.deploymentInformation = deploymentInformation;
     return {
         frontmatter,
-        description,
-        acceptanceCriteria,
-        additionalFields,
+        fieldMap,
+        bodyFieldMap,
+        localOnlySections,
+        workItemType,
+        description: bodyFieldMap['System.Description'] || '',
+        reproSteps: bodyFieldMap['Microsoft.VSTS.TCM.ReproSteps'] || '',
+        acceptanceCriteria: bodyFieldMap['Microsoft.VSTS.Common.AcceptanceCriteria'] || '',
+        additionalFields: {
+            howToTest: bodyFieldMap['Custom.Howtotest'],
+            deploymentInformation: bodyFieldMap['Custom.Deploymentinformation'],
+            predeploymentSteps: bodyFieldMap['Custom.7519d1bc-5305-4905-822b-2b380e61b154'],
+            postdeploymentSteps: bodyFieldMap['Custom.abd6763f-a242-4938-85ed-bda419e34e7e'],
+        },
         rawContent: content,
     };
 }
-/**
- * Build ADO fields object for creating a new work item
- * Inherits areaPath and iterationPath from parent work item when available
- *
- * Returns fields split into standard (safe for creation) and custom (require
- * a follow-up update) because ADO rejects custom fields during work item creation.
- */
 export function buildNewWorkItemFields(parsed, parentWorkItem) {
     const parentFields = parentWorkItem?.fields || {};
-    const fieldConfig = getAdditionalFieldConfig();
-    const standardFields = {
-        'System.Title': parsed.frontmatter.title,
-        'System.State': parsed.frontmatter.state || 'New',
-    };
-    // Set description if provided
-    if (parsed.description) {
-        standardFields['System.Description'] = parsed.description;
-    }
-    // Set acceptance criteria if provided
-    if (parsed.acceptanceCriteria) {
-        standardFields['Microsoft.VSTS.Common.AcceptanceCriteria'] = parsed.acceptanceCriteria;
-    }
-    // Story points - only set if it's a valid number (including 0)
-    // YAML may parse empty value as null/undefined, or string if quoted
-    // Using 'any' cast because YAML parser may return types not matching interface
-    const storyPointsValue = parsed.frontmatter.storyPoints;
-    if (storyPointsValue !== undefined && storyPointsValue !== null && storyPointsValue !== '') {
-        const storyPoints = Number(storyPointsValue);
-        if (!isNaN(storyPoints)) {
-            standardFields['Microsoft.VSTS.Scheduling.StoryPoints'] = storyPoints;
-        }
-    }
-    // Tags - ensure it's an array with items before joining
-    if (Array.isArray(parsed.frontmatter.tags) && parsed.frontmatter.tags.length > 0) {
-        standardFields['System.Tags'] = parsed.frontmatter.tags.join('; ');
+    const standardFields = {};
+    const customFields = {};
+    // Title is mandatory; force it from the top-level frontmatter shape.
+    standardFields['System.Title'] = parsed.frontmatter.title;
+    standardFields['System.State'] = parsed.frontmatter.state || 'New';
+    // Fold in every scalar field from the fieldMap.
+    for (const [refname, value] of Object.entries(parsed.fieldMap)) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        const target = isStandardRefname(refname) ? standardFields : customFields;
+        target[refname] = frontmatterValueToAdo(refname, value);
     }
-    // Inherit areaPath from parent if not specified
-    if (parsed.frontmatter.areaPath) {
-        standardFields['System.AreaPath'] = parsed.frontmatter.areaPath;
+    // Fold in every body field (description, AC, repro steps, custom body fields).
+    for (const [refname, value] of Object.entries(parsed.bodyFieldMap)) {
+        if (!value || !value.trim())
+            continue;
+        const target = isStandardRefname(refname) ? standardFields : customFields;
+        target[refname] = value;
     }
-    else if (parentFields['System.AreaPath']) {
+    // Inherit area/iteration path from parent when not provided.
+    if (!standardFields['System.AreaPath'] && parentFields['System.AreaPath']) {
         standardFields['System.AreaPath'] = parentFields['System.AreaPath'];
     }
-    // Inherit iterationPath from parent if not specified
-    if (parsed.frontmatter.iterationPath) {
-        standardFields['System.IterationPath'] = parsed.frontmatter.iterationPath;
-    }
-    else if (parentFields['System.IterationPath']) {
+    if (!standardFields['System.IterationPath'] && parentFields['System.IterationPath']) {
         standardFields['System.IterationPath'] = parentFields['System.IterationPath'];
     }
-    // Custom fields — NOT valid during creation, must be set via follow-up update
-    const customFields = {};
-    // MoSCoW (custom field) - only set if non-empty
-    const moscowValue = parsed.frontmatter.moscow;
-    if (moscowValue && String(moscowValue).trim() !== '') {
-        customFields['Custom.MoSCoW'] = moscowValue;
-    }
-    // Additional custom fields
-    if (parsed.additionalFields.howToTest) {
-        customFields[fieldConfig.howToTest] = parsed.additionalFields.howToTest;
-    }
-    if (parsed.additionalFields.predeploymentSteps) {
-        customFields[fieldConfig.predeploymentSteps] = parsed.additionalFields.predeploymentSteps;
-    }
-    if (parsed.additionalFields.postdeploymentSteps) {
-        customFields[fieldConfig.postdeploymentSteps] = parsed.additionalFields.postdeploymentSteps;
-    }
-    if (parsed.additionalFields.deploymentInformation) {
-        customFields[fieldConfig.deploymentInformation] = parsed.additionalFields.deploymentInformation;
-    }
     return { standardFields, customFields };
 }
-/**
- * Generate a new work item template markdown file
- * When parentId is undefined, creates a standalone work item template
- */
+function isStandardRefname(refname) {
+    return refname.startsWith('System.') || refname.startsWith('Microsoft.VSTS.');
+}
+// ---------------------------------------------------------------------------
+// Template generation (new work item file scaffold)
+// ---------------------------------------------------------------------------
 export function generateNewWorkItemTemplate(parentId, parentTitle, project, workItemType = 'User Story') {
-    // Only include required fields - optional fields omitted to avoid empty value issues
-    const frontmatter = {
-        title: `New ${workItemType} Title`,
-        type: workItemType,
-        state: 'New',
-    };
-    // Only include parent in frontmatter when provided
+    const template = applyTemplatePlaceholders(loadTemplate(workItemType), {
+        project,
+        parent: parentId,
+    });
+    const fmData = { ...template.frontmatterDefaults };
+    const fmOrder = [...template.frontmatterOrder];
+    // Default `title` to a descriptive placeholder when blank in the template.
+    const titleKey = template.frontmatterOrder.includes('title')
+        ? 'title'
+        : Object.keys(fmData).find((k) => resolveRefname(k) === 'System.Title');
+    if (titleKey && (!fmData[titleKey] || fmData[titleKey] === '')) {
+        fmData[titleKey] = `New ${workItemType} Title`;
+    }
     if (parentId !== undefined) {
-        frontmatter.parent = parentId;
+        fmData.parent = parentId;
+        if (!fmOrder.includes('parent'))
+            fmOrder.splice(1, 0, 'parent'); // after `type`
     }
-    let content = serializeFrontmatter(frontmatter);
+    let content = serializeFrontmatter(fmData, fmOrder);
     content += '\n';
-    content += `<!-- Optional frontmatter fields (add to YAML above if needed):\n`;
-    if (parentId === undefined) {
-        content += `parent: 12345\n`;
-    }
-    content += `storyPoints: 3\n`;
-    content += `moscow: Should Have\n`;
-    content += `areaPath: Project\\Area\n`;
-    content += `iterationPath: Project\\Sprint 1\n`;
-    content += `tags:\n`;
-    content += `- tag1\n`;
-    content += `- tag2\n`;
-    content += `-->\n\n`;
     if (parentId !== undefined) {
-        content += `> Parent: **#${parentId}** - ${parentTitle}\n`;
+        content += `\n> Parent: **#${parentId}** - ${parentTitle}\n`;
     }
     content += `> Project: ${project}\n`;
-    content += '\n# Description\n\n';
-    content += '[Your description here]\n\n';
-    content += '---\n\n';
-    content += '# Acceptance Criteria\n\n';
-    content += '[Your acceptance criteria here]\n';
+    for (const bodyField of template.bodyFields) {
+        content += '\n' + serializeAnnotatedSection(bodyField.heading, bodyField.refname, '');
+    }
     return content;
 }
-/**
- * Update a new work item file after creation with the assigned ID
- * Converts it from a "new" file to a synced file with proper frontmatter
- */
+// ---------------------------------------------------------------------------
+// Comments (unchanged — read-only export)
+// ---------------------------------------------------------------------------
+export function commentsToMarkdown(workItem, comments) {
+    const fields = workItem.fields || {};
+    const frontmatter = {
+        id: workItem.id,
+        title: fields['System.Title'] || '',
+        commentCount: comments.length,
+        lastSyncedAt: new Date().toISOString(),
+    };
+    let content = serializeFrontmatter(frontmatter);
+    content += '\n\n# Comments\n\n';
+    content += '> **NOTE**: This file is read-only. Comments cannot be pushed back to ADO.\n\n';
+    if (comments.length === 0) {
+        content += '_No comments on this work item._\n';
+    }
+    else {
+        const sorted = [...comments].sort((a, b) => {
+            const da = new Date(a.createdDate || a.publishedDate || 0).getTime();
+            const db = new Date(b.createdDate || b.publishedDate || 0).getTime();
+            return da - db;
+        });
+        sorted.forEach((comment, index) => {
+            content += '---\n\n';
+            content += `## Comment #${index + 1}\n`;
+            content += `**Author**: ${comment.createdBy?.displayName || 'Unknown'}\n`;
+            content += `**Date**: ${comment.createdDate || comment.publishedDate || 'Unknown'}\n\n`;
+            content += `${comment.text || comment.content || ''}\n\n`;
+        });
+    }
+    return content;
+}
+// ---------------------------------------------------------------------------
+// Sync revision bump + new-file → synced-file conversion
+// ---------------------------------------------------------------------------
+export function updateSyncRevision(content, newRevision) {
+    const updated = content.replace(/lastSyncedRevision:\s*\d+/, `lastSyncedRevision: ${newRevision}`);
+    return updated.replace(/lastSyncedAt:\s*[^\n]+/, `lastSyncedAt: ${new Date().toISOString()}`);
+}
 export function convertNewFileToSynced(content, workItemId, revision, url) {
-    // Parse the existing content
     const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
     if (!frontmatterMatch) {
         throw new Error('Invalid work item markdown file: missing YAML frontmatter');
     }
-    const frontmatterRaw = frontmatterMatch[1];
-    const frontmatterData = parseFrontmatter(frontmatterRaw);
+    const frontmatterData = parseFrontmatter(frontmatterMatch[1]);
     const contentAfterFrontmatter = content.slice(frontmatterMatch[0].length);
-    // Build new frontmatter with id and sync metadata
-    const newFrontmatter = {
-        id: workItemId,
-        title: frontmatterData.title || '',
-        type: frontmatterData.type || 'User Story',
-        state: frontmatterData.state || 'New',
-        url: url,
-    };
-    // Copy optional fields
-    if (frontmatterData.assignedTo)
-        newFrontmatter.assignedTo = frontmatterData.assignedTo;
-    if (frontmatterData.storyPoints)
-        newFrontmatter.storyPoints = frontmatterData.storyPoints;
-    if (frontmatterData.parent)
-        newFrontmatter.parent = frontmatterData.parent;
-    if (frontmatterData.moscow)
-        newFrontmatter.moscow = frontmatterData.moscow;
-    if (frontmatterData.tags && frontmatterData.tags.length > 0)
-        newFrontmatter.tags = frontmatterData.tags;
-    if (frontmatterData.areaPath)
-        newFrontmatter.areaPath = frontmatterData.areaPath;
-    if (frontmatterData.iterationPath)
-        newFrontmatter.iterationPath = frontmatterData.iterationPath;
-    // Add sync metadata
-    newFrontmatter.lastSyncedRevision = revision;
-    newFrontmatter.lastSyncedAt = new Date().toISOString();
-    // Remove the "Parent:" and "Project:" note lines from the content
-    let cleanedContent = contentAfterFrontmatter
+    // Rebuild frontmatter with id + sync metadata inserted at the top.
+    const newData = { id: workItemId };
+    const newOrder = ['id'];
+    for (const [key, value] of Object.entries(frontmatterData)) {
+        if (key === 'id')
+            continue;
+        newData[key] = value;
+        newOrder.push(key);
+    }
+    newData.url = url;
+    if (!newOrder.includes('url'))
+        newOrder.push('url');
+    newData.lastSyncedRevision = revision;
+    newOrder.push('lastSyncedRevision');
+    newData.lastSyncedAt = new Date().toISOString();
+    newOrder.push('lastSyncedAt');
+    // Strip the transient "Parent:"/"Project:" note lines used only for template readability.
+    const cleaned = contentAfterFrontmatter
         .replace(/>\s*Parent:.*\n/i, '')
         .replace(/>\s*Project:.*\n/i, '');
-    return serializeFrontmatter(newFrontmatter) + cleanedContent;
+    return serializeFrontmatter(newData, newOrder) + cleaned;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers exposed for tests / sync-service
+// ---------------------------------------------------------------------------
+/**
+ * Return the list of large-text (body) refnames that should be HTML-checked
+ * for a given work-item type. Driven by the loaded template.
+ */
+export function templateBodyRefnamesForType(workItemType) {
+    return loadTemplate(workItemType).bodyFields.map((f) => f.refname);
 }
 //# sourceMappingURL=markdown-serializer.js.map