flex-md 4.7.2 → 4.7.4

package/dist-cjs/md/parse.cjs

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeName = normalizeName;
+exports.extractFencedBlocks = extractFencedBlocks;
+exports.parseHeadingsAndSections = parseHeadingsAndSections;
+exports.extractBullets = extractBullets;
+exports.parseMarkdownTable = parseMarkdownTable;
+exports.isIssuesEnvelopeCheck = isIssuesEnvelopeCheck;
+exports.markdownToJson = markdownToJson;
+const nx_helpers_1 = require("nx-helpers");
+const normalize_js_1 = require("./normalize.cjs");
+function normalizeName(s) {
+    return s.trim().replace(/\s+/g, " ").toLowerCase();
+}
+function extractFencedBlocks(text) {
+    const rx = /```(\w+)?\s*\n([\s\S]*?)\n```/g;
+    const blocks = [];
+    let m;
+    while ((m = rx.exec(text)) !== null) {
+        const full = m[0];
+        const lang = String(m[1] ?? "").trim().toLowerCase();
+        const content = m[2] ?? "";
+        const start = m.index;
+        const end = start + full.length;
+        // compute content start/end (best-effort)
+        const headerLen = full.indexOf("\n") + 1; // after first newline
+        const contentEnd = end - 3; // "```" at end
+        const contentStart = start + headerLen;
+        blocks.push({
+            lang,
+            start,
+            end,
+            contentStart,
+            contentEnd,
+            content,
+            full,
+        });
+    }
+    return blocks;
+}
+function parseHeadingsAndSections(md, options = {}) {
+    // Standard headings #... and alternative ===key.
+    // Also optionally allow "- Section" if specified in bulletNames.
+    const rx = /^((?:#{1,6})[ \t]+(.+?)[ \t]*|===(.+?)[ \t]*|([-*+])[ \t]+(.+?)[ \t]*)$/gm;
+    const headings = [];
+    const bulletNamesNormal = new Set((options.bulletNames || []).map(normalizeName));
+    let m;
+    while ((m = rx.exec(md)) !== null) {
+        const full = m[1] ?? "";
+        let level;
+        let name;
+        if (full.startsWith("===")) {
+            level = 1; // Treat ===key as a top-level heading
+            name = (m[3] ?? "").trim();
+        }
+        else if (m[4]) {
+            // It's a bullet (- / * / +)
+            const bulletChar = m[4];
+            const bulletText = (m[5] ?? "").trim();
+            const norm = normalizeName(bulletText);
+            if (bulletNamesNormal.has(norm)) {
+                level = 1;
+                name = bulletText;
+            }
+            else {
+                // Not a recognized section header bullet, ignore it
+                continue;
+            }
+        }
+        else {
+            const hashesMatch = full.match(/^#+/);
+            const hashes = hashesMatch ? hashesMatch[0] : "";
+            level = hashes.length;
+            name = (m[2] ?? "").trim();
+        }
+        const raw = m[0] ?? "";
+        const start = m.index;
+        const end = start + raw.length;
+        headings.push({
+            level,
+            raw,
+            name,
+            norm: normalizeName(name),
+            start,
+            end,
+        });
+    }
+    // compute section bodies
+    const sections = [];
+    for (let i = 0; i < headings.length; i++) {
+        const h = headings[i];
+        const bodyStart = nextLineIndex(md, h.end);
+        let bodyEnd = md.length;
+        for (let j = i + 1; j < headings.length; j++) {
+            const nxt = headings[j];
+            bodyEnd = nxt.start;
+            break;
+        }
+        sections.push({
+            heading: h,
+            bodyStart,
+            bodyEnd,
+            body: md.slice(bodyStart, bodyEnd).trimEnd(),
+        });
+    }
+    return sections;
+}
+function nextLineIndex(text, idx) {
+    if (idx >= text.length)
+        return text.length;
+    if (text[idx] === "\n")
+        return idx + 1;
+    const n = text.indexOf("\n", idx);
+    return n === -1 ? text.length : n + 1;
+}
+function extractBullets(body) {
+    const lines = body.split(/\r?\n/);
+    const out = [];
+    for (const line of lines) {
+        const m = line.match(/^\s*[-*•]\s+(.*)\s*$/) || line.match(/^\s*\d+\.\s+(.*)\s*$/);
+        if (m)
+            out.push(m[1].trim());
+    }
+    return out;
+}
+function parseMarkdownTable(body, columns) {
+    const lines = body.split(/\r?\n/).map(l => l.trim()).filter(l => l.startsWith("|"));
+    if (lines.length < 2)
+        return [];
+    // Identification of header vs separator
+    const headerLine = lines[0];
+    const separatorLine = lines[1];
+    // Check if second line is a separator (e.g. |---|---|)
+    const isSeparator = separatorLine && /^[|\s-:]+$/.test(separatorLine);
+    const dataStartIndex = isSeparator ? 2 : 1;
+    const dataLines = lines.slice(dataStartIndex);
+    const results = [];
+    for (const line of dataLines) {
+        const cells = line.split("|").map(c => c.trim()).filter((_, i, arr) => i > 0 && i < arr.length - 1);
+        const row = {};
+        // Match cells to provided columns by index
+        for (let i = 0; i < columns.length; i++) {
+            row[columns[i]] = cells[i] || "";
+        }
+        results.push(row);
+    }
+    return results;
+}
+function isIssuesEnvelopeCheck(md) {
+    const parsed = parseHeadingsAndSections(md);
+    const want = ["status", "issues", "expected", "found", "how to fix"].map(normalizeName);
+    const got = new Set(parsed.map(s => s.heading.norm));
+    const ok = want.every(w => got.has(w));
+    const sections = {};
+    if (ok) {
+        for (const sec of parsed) {
+            if (want.includes(sec.heading.norm)) {
+                sections[sec.heading.norm] = {
+                    heading: sec.heading.name,
+                    body: sec.body.trim(),
+                    bullets: extractBullets(sec.body),
+                };
+            }
+        }
+    }
+    return { isIssuesEnvelope: ok, sections };
+}
+function markdownToJson(md) {
+    // Robustly handle both actual newlines and literal \n (common in LLM JSON outputs)
+    const normalizedMd = (0, normalize_js_1.normalizeMarkdownInput)(md);
+    // Collect all bullet names that look like headers ("- Name")
+    // We look for patterns like "- Name\n" at the start of lines, ensuring it's not a sub-bullet.
+    const bulletNames = [];
+    const bulletLinesRx = /^[-*+]\s+([^—:\n\r]{2,50})$/gm;
+    let m;
+    while ((m = bulletLinesRx.exec(normalizedMd)) !== null) {
+        bulletNames.push(m[1].trim());
+    }
+    // Use Flex-MD's native parser (supports === headings and avoids colon-as-object bug)
+    const sections = parseHeadingsAndSections(normalizedMd, { bulletNames });
+    const result = {};
+    for (const sec of sections) {
+        const key = (0, nx_helpers_1.toCamelCase)(sec.heading.name);
+        const body = sec.body.trim();
+        // 1. Try to detect list
+        const bullets = extractBullets(body);
+        if (bullets.length > 0) {
+            result[key] = bullets;
+            continue;
+        }
+        // 2. Try to detect table (basic check)
+        const lines = body.split("\n").map(l => l.trim()).filter(l => l);
+        if (lines.length >= 2 && lines[0].startsWith("|") && /^[|\s-:]+$/.test(lines[1])) {
+            // It looks like a table - we could use nx-md-parser's table logic here safely
+        }
+        result[key] = body;
+    }
+    return result;
+}

package/dist-cjs/ofs/adapter.cjs

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ofsToSchema = ofsToSchema;
+exports.transformWithOfs = transformWithOfs;
+const nx_md_parser_1 = require("nx-md-parser");
+const memory_js_1 = require("./memory.cjs");
+const parse_js_1 = require("../md/parse.cjs");
+const normalize_js_1 = require("../md/normalize.cjs");
+const nx_helpers_1 = require("nx-helpers");
+const nx_json_parser_1 = require("nx-json-parser");
+const logger_js_1 = require("../logger.cjs");
+/**
+ * Converts a Flex-MD OutputFormatSpec to an nx-md-parser Schema.
+ */
+function ofsToSchema(spec) {
+    const properties = {};
+    for (const section of spec.sections) {
+        let type;
+        switch (section.kind) {
+            case "list":
+            case "ordered_list":
+                type = nx_md_parser_1.Schema.array(nx_md_parser_1.Schema.string());
+                break;
+            case "table":
+            case "ordered_table":
+                if (section.columns && section.columns.length > 0) {
+                    const rowProps = {};
+                    for (const col of section.columns) {
+                        rowProps[col] = nx_md_parser_1.Schema.string();
+                    }
+                    type = nx_md_parser_1.Schema.array(nx_md_parser_1.Schema.object(rowProps));
+                }
+                else {
+                    type = nx_md_parser_1.Schema.string();
+                }
+                break;
+            case "text":
+            default:
+                type = nx_md_parser_1.Schema.string();
+                break;
+        }
+        properties[section.name] = type;
+    }
+    if (spec.tables && spec.tables.length > 0) {
+        for (const table of spec.tables) {
+            const tableKey = table.columns.join("_");
+            const rowProps = {};
+            for (const col of table.columns) {
+                rowProps[col] = nx_md_parser_1.Schema.string();
+            }
+            properties[tableKey] = nx_md_parser_1.Schema.array(nx_md_parser_1.Schema.object(rowProps));
+        }
+    }
+    return nx_md_parser_1.Schema.object(properties);
+}
+/**
+ * Transforms markdown text using a Flex-MD OutputFormatSpec or a recallId.
+ * If no spec is provided, it attempts to infer it from the markdown (autospecs).
+ */
+function transformWithOfs(md, specOrRecallId) {
+    logger_js_1.logger.info("Starting Flex-MD transformation", {
+        inputLength: md.length,
+        hasSpec: !!specOrRecallId,
+        specType: specOrRecallId ? typeof specOrRecallId : 'none'
+    });
+    // 0. Normalize input (handle literal \n common in LLM outputs)
+    const normalizedMd = (0, normalize_js_1.normalizeMarkdownInput)(md);
+    logger_js_1.logger.debug("Input normalization", {
+        originalLength: md.length,
+        normalizedLength: normalizedMd.length,
+        changed: md !== normalizedMd
+    });
+    // 1. Automatic parsing (Dual-Response) using nx-json-parser
+    logger_js_1.logger.debug("Starting automatic parsing with nx-json-parser");
+    const parsedOutput = (0, nx_json_parser_1.markdownToJson)(normalizedMd);
+    logger_js_1.logger.debug("Automatic parsing completed", {
+        parsedKeys: Object.keys(parsedOutput),
+        parsedKeyCount: Object.keys(parsedOutput).length
+    });
+    if (!specOrRecallId) {
+        logger_js_1.logger.info("No spec provided, returning parsed output only");
+        return {
+            parsedOutput,
+            contractOutput: null,
+            contractStatus: "skipped",
+            status: "validated",
+            errors: []
+        };
+    }
+    let spec;
+    if (typeof specOrRecallId === "string") {
+        logger_js_1.logger.debug("Recalling spec from memory", { recallId: specOrRecallId });
+        const recalled = (0, memory_js_1.recall)(specOrRecallId);
+        if (!recalled) {
+            logger_js_1.logger.warn("Recall ID not found", { recallId: specOrRecallId });
+            return {
+                parsedOutput,
+                contractOutput: null,
+                contractStatus: "skipped",
+                status: "failed",
+                errors: [`Recall ID "${specOrRecallId}" not found in memory.`]
+            };
+        }
+        spec = recalled;
+        logger_js_1.logger.debug("Spec recalled successfully", {
+            sectionCount: spec.sections.length,
+            sectionNames: spec.sections.map(s => s.name)
+        });
+    }
+    else {
+        spec = specOrRecallId;
+        logger_js_1.logger.debug("Using provided spec directly", {
+            sectionCount: spec.sections.length,
+            sectionNames: spec.sections.map(s => s.name)
+        });
+    }
+    // 2. Parse sections using Flex-MD parser for the contract mapping
+    const bulletNames = spec.sections.map(s => s.name);
+    logger_js_1.logger.debug("Starting section parsing", {
+        expectedSections: bulletNames,
+        sectionCount: bulletNames.length
+    });
+    // Note: We use the local headings parser to find the specific sections defined in the spec
+    const parsedSections = (0, parse_js_1.parseHeadingsAndSections)(normalizedMd, { bulletNames });
+    logger_js_1.logger.debug("Section parsing completed", {
+        foundSections: parsedSections.map(s => s.heading.name),
+        foundCount: parsedSections.length
+    });
+    const parsedObj = {};
+    for (const sectionSpec of spec.sections) {
+        const normName = (0, parse_js_1.normalizeName)(sectionSpec.name);
+        const found = parsedSections.find(s => (0, parse_js_1.normalizeName)(s.heading.name) === normName);
+        logger_js_1.logger.verbose(`Processing section "${sectionSpec.name}"`, {
+            normalizedName: normName,
+            found: !!found,
+            kind: sectionSpec.kind,
+            hasColumns: !!sectionSpec.columns
+        });
+        if (found) {
+            let value;
+            switch (sectionSpec.kind) {
+                case "list":
+                case "ordered_list":
+                    value = (0, parse_js_1.extractBullets)(found.body);
+                    logger_js_1.logger.debug(`Extracted bullets for "${sectionSpec.name}"`, {
+                        bulletCount: Array.isArray(value) ? value.length : 'unknown'
+                    });
+                    break;
+                case "table":
+                case "ordered_table":
+                    if (sectionSpec.columns) {
+                        value = (0, parse_js_1.parseMarkdownTable)(found.body, sectionSpec.columns);
+                        logger_js_1.logger.debug(`Parsed table for "${sectionSpec.name}"`, {
+                            columns: sectionSpec.columns,
+                            rowCount: Array.isArray(value) ? value.length : 'unknown'
+                        });
+                    }
+                    else {
+                        value = found.body.trim();
+                        logger_js_1.logger.debug(`Using raw body for table "${sectionSpec.name}" (no columns specified)`);
+                    }
+                    break;
+                default:
+                    value = found.body.trim();
+                    logger_js_1.logger.debug(`Using trimmed body for "${sectionSpec.name}"`);
+                    break;
+            }
+            parsedObj[sectionSpec.name] = value;
+        }
+        else {
+            logger_js_1.logger.warn(`Section "${sectionSpec.name}" not found in markdown`);
+        }
+    }
+    logger_js_1.logger.debug("Contract parsing completed", {
+        parsedKeys: Object.keys(parsedObj),
+        parsedKeyCount: Object.keys(parsedObj).length
+    });
+    // 3. Transform using nx-md-parser (latest v2.2.0) for schema validation and fixing
+    const schema = ofsToSchema(spec);
+    const transformer = new nx_md_parser_1.JSONTransformer(schema);
+    const transformResult = transformer.transform(parsedObj);
+    // 4. Compare parsed results with contract results
+    const autoKeys = Object.keys(parsedOutput).sort();
+    const contractKeys = transformResult.result ? Object.keys(transformResult.result).map(k => (0, nx_helpers_1.toCamelCase)(k)).sort() : [];
+    const isSame = autoKeys.length > 0 &&
+        autoKeys.every(k => contractKeys.includes(k)) &&
+        contractKeys.length === autoKeys.length;
+    return {
+        parsedOutput,
+        contractOutput: transformResult.result,
+        contractStatus: isSame ? "ok" : "different",
+        status: transformResult.status,
+        errors: transformResult.errors || []
+    };
+}

package/dist-cjs/ofs/enricher.cjs

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMarkdownGuidance = buildMarkdownGuidance;
+exports.enrichInstructions = enrichInstructions;
+exports.enrichInstructionsWithFlexMd = enrichInstructionsWithFlexMd;
+/**
+ * Generates Markdown guidance instructions for the LLM based on the OFS and contract level.
+ * Strictly avoids the word "flex-md" and remains "tax-aware" by only including relevant rules.
+ */
+function buildMarkdownGuidance(spec, strict, opts) {
+    const level = strict.level ?? 0;
+    const fence = opts?.containerFence === "flexmd" ? "```flexmd" : "```markdown";
+    // L0 - Minimal Markdown
+    if (level === 0) {
+        return "Reply in Markdown.";
+    }
+    const lines = [];
+    // L2+ Container Rule
+    if (level >= 2) {
+        lines.push(`Return your entire answer inside a single ${fence} fenced block and nothing else.`);
+        lines.push("");
+        lines.push("Inside the block, include these section headings somewhere (order does not matter):");
+    }
+    else {
+        lines.push("Reply in Markdown.");
+        lines.push("");
+        lines.push("Include these section headings somewhere (order does not matter):");
+    }
+    // Heading List
+    for (const s of spec.sections) {
+        let suffix = "";
+        if (level >= 3) {
+            if (s.kind === "list")
+                suffix = " (list)";
+            else if (s.kind === "ordered_list")
+                suffix = " (ordered list)";
+        }
+        lines.push(`- ${s.name}${suffix}`);
+        if (level >= 1) {
+            if (s.description) {
+                lines.push(`  Description: ${s.description}`);
+            }
+            if (s.instruction) {
+                lines.push(`  Instruction: ${s.instruction}`);
+            }
+        }
+    }
+    lines.push("");
+    // None Rule
+    const noneRule = opts?.includeNoneRule ?? "auto";
+    const hasRequired = spec.sections.some(s => s.required !== false);
+    const includeNone = noneRule === "always" || (noneRule === "auto" && (hasRequired || level >= 3));
+    if (includeNone) {
+        lines.push(`If a section is empty, write \`None\`.`);
+        lines.push("");
+    }
+    // List Rules
+    const listRule = opts?.includeListRules ?? "auto";
+    const hasListDecls = spec.sections.some(s => s.kind === "list" || s.kind === "ordered_list");
+    const includeList = listRule === "always" || (listRule === "auto" && (hasListDecls || level >= 3));
+    if (includeList) {
+        lines.push("List rules:");
+        lines.push("- Use numbered lists (`1.`, `2.`, …) for ordered lists.");
+        lines.push("- Use `-` bullets for unordered lists.");
+        lines.push("");
+    }
+    // Table Rules
+    const tableRule = opts?.includeTableRules ?? "auto";
+    const hasTableDecls = (spec.tables && spec.tables.length > 0) || spec.sections.some(s => s.kind === "table" || s.kind === "ordered_table");
+    const includeTable = tableRule === "always" || (tableRule === "auto" && (hasTableDecls || level >= 3));
+    if (includeTable) {
+        const hasOrderedTable = spec.tables?.some(t => t.kind === "ordered_table") || spec.sections.some(s => s.kind === "ordered_table");
+        lines.push("Tables:");
+        lines.push("- If you include a table, use a Markdown pipe table.");
+        if (hasOrderedTable || level >= 3) {
+            lines.push("- For ordered tables, add a first column named `#` and number rows 1..N.");
+        }
+        lines.push("");
+    }
+    if (level >= 3) {
+        lines.push("Do not return JSON as the response format.");
+    }
+    return lines.join("\n").trim();
+}
+/**
+ * @deprecated Use buildMarkdownGuidance
+ */
+function enrichInstructions(spec, strict) {
+    return buildMarkdownGuidance(spec, strict);
+}
+/**
+ * Enrich instructions with flex-md compliance guidance.
+ * Returns detailed information about what was changed.
+ */
+async function enrichInstructionsWithFlexMd(instructions, strictnessLevel, spec // Optional spec, if provided will include section guidance
+) {
+    const originalLength = instructions.length;
+    const level = parseInt(strictnessLevel.slice(1));
+    // Default spec if none provided (minimal)
+    const effectiveSpec = spec ?? { sections: [] };
+    const guidance = buildMarkdownGuidance(effectiveSpec, { level });
+    // Check if guidance is already present (simple check)
+    if (instructions.includes(guidance)) {
+        return {
+            enriched: instructions,
+            changes: [],
+            originalLength,
+            enhancedLength: originalLength,
+            metadata: {
+                sectionsAdded: 0,
+                containerAdded: false,
+                guidanceAdded: false
+            }
+        };
+    }
+    const separator = instructions.trim().length > 0 ? "\n\n" : "";
+    const enriched = instructions.trim() + separator + guidance;
+    const enhancedLength = enriched.length;
+    const changes = [
+        {
+            type: "added-guidance",
+            description: `Added Flex-MD ${strictnessLevel} compliance guidance.`,
+            location: {
+                start: instructions.trim().length + separator.length,
+                end: enhancedLength
+            },
+            content: guidance
+        }
+    ];
+    if (level >= 2) {
+        changes.push({
+            type: "added-container",
+            description: "Added requirement for a fenced container block.",
+            location: {
+                start: instructions.trim().length + separator.length,
+                end: enhancedLength
+            }
+        });
+    }
+    return {
+        enriched,
+        changes,
+        originalLength,
+        enhancedLength,
+        metadata: {
+            sectionsAdded: effectiveSpec.sections.length,
+            containerAdded: level >= 2,
+            guidanceAdded: true
+        }
+    };
+}

package/dist-cjs/ofs/infer.cjs

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferOfsFromMarkdown = inferOfsFromMarkdown;
+const parse_js_1 = require("../md/parse.cjs");
+/**
+ * Infers an OutputFormatSpec from a Markdown string.
+ */
+function inferOfsFromMarkdown(md) {
+    // Collect all bullet names that look like headers ("- Name")
+    const lines = md.split("\n");
+    const bulletNames = [];
+    for (const line of lines) {
+        // Match "- Name" or "- Name\n" or "- Name " but NOT "- Name: more text"
+        const m = line.match(/^[-*+]\s+([^—:\n]+)$/);
+        if (m) {
+            bulletNames.push(m[1].trim());
+        }
+    }
+    const sections = (0, parse_js_1.parseHeadingsAndSections)(md, { bulletNames });
+    const specSections = [];
+    for (const sec of sections) {
+        const name = sec.heading.name;
+        const body = sec.body.trim();
+        // 1. Detect list
+        const bullets = (0, parse_js_1.extractBullets)(body);
+        if (bullets.length > 0) {
+            specSections.push({
+                name,
+                kind: "list",
+                required: true
+            });
+            continue;
+        }
+        // 2. Detect table (basic check)
+        const lines = body.split("\n").map(l => l.trim()).filter(Boolean);
+        if (lines.length >= 2 && lines[0].startsWith("|") && /^[|\s-:]+$/.test(lines[1])) {
+            // Extract columns
+            const cols = lines[0].split("|").map(c => c.trim()).filter(Boolean);
+            specSections.push({
+                name,
+                kind: "table",
+                columns: cols,
+                required: true
+            });
+            continue;
+        }
+        // Default to text
+        specSections.push({
+            name,
+            kind: "text",
+            required: true
+        });
+    }
+    return {
+        descriptorType: "output_format_spec",
+        format: "markdown",
+        sectionOrderMatters: false,
+        sections: specSections,
+        tablesOptional: true,
+        tables: [],
+        emptySectionValue: "None"
+    };
+}

package/dist-cjs/ofs/issuesEnvelope.cjs

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseIssuesEnvelope = parseIssuesEnvelope;
+exports.buildIssuesEnvelope = buildIssuesEnvelope;
+exports.buildIssuesEnvelopeAuto = buildIssuesEnvelopeAuto;
+const parse_js_1 = require("../md/parse.cjs");
+function parseIssuesEnvelope(md) {
+    return (0, parse_js_1.isIssuesEnvelopeCheck)(md);
+}
+function buildIssuesEnvelope(args) {
+    const issues = args.validation.issues
+        .filter(i => i.severity === "warn" || i.severity === "error")
+        .map(i => `- ${i.message}`);
+    const expected = args.expectedSummary.map(x => `- ${x}`);
+    const found = args.foundSummary.map(x => `- ${x}`);
+    const how = args.howToFix.map(x => `- ${x}`);
+    return [
+        "## Status",
+        "Non-compliant output (cannot be repaired to the required format).",
+        "",
+        "## Issues",
+        issues.length ? issues.join("\n") : "- None",
+        "",
+        "## Expected",
+        expected.length ? expected.join("\n") : "- None",
+        "",
+        "## Found",
+        found.length ? found.join("\n") : "- None",
+        "",
+        "## How to fix",
+        how.length ? how.join("\n") : "- None",
+        "",
+    ].join("\n");
+}
+function buildIssuesEnvelopeAuto(args) {
+    const v = args.validation;
+    const expected = [];
+    const found = [];
+    const how = [];
+    if (args.level >= 2) {
+        expected.push("One single ```markdown fenced block containing the entire answer (no text outside).");
+    }
+    if (args.level >= 1 && (args.requiredSectionNames?.length ?? 0) > 0) {
+        expected.push(`Section headings present (order does not matter): ${args.requiredSectionNames.join(", ")}`);
+    }
+    if (args.level >= 3 && (args.kindRequirements?.length ?? 0) > 0) {
+        for (const k of args.kindRequirements)
+            expected.push(k);
+    }
+    if (v.stats) {
+        found.push(`Detected sections: ${v.stats.sectionCount}`);
+        if (v.stats.missingRequired.length)
+            found.push(`Missing: ${v.stats.missingRequired.join(", ")}`);
+        if (v.stats.duplicates.length)
+            found.push(`Duplicates: ${v.stats.duplicates.join(", ")}`);
+        found.push(`Fences: ${v.stats.container.fenceCount} (langs: ${v.stats.container.fenceLangs.join(", ") || "none"})`);
+        found.push(`Outside text: ${v.stats.container.hasOutsideText ? "yes" : "no"}`);
+    }
+    if (args.level >= 2)
+        how.push("Return a single ```markdown fenced block and nothing else.");
+    if (args.level >= 1)
+        how.push("Include the required headings and put content under each (order does not matter).");
+    how.push('If a section is empty, write "None".');
+    if (args.level >= 3) {
+        how.push('Use numbered lists ("1.", "2.", …) for ordered lists and "-" bullets for unordered lists.');
+        how.push("Use Markdown pipe tables for table sections; ordered tables include a first column '#'.");
+        how.push("Do not return JSON as the response format.");
+    }
+    return buildIssuesEnvelope({
+        validation: v,
+        level: args.level,
+        expectedSummary: expected,
+        foundSummary: found,
+        howToFix: how,
+    });
+}