@mcoda/core 0.1.34 → 0.1.36

package/dist/services/docs/DocsService.js

@@ -166,6 +166,35 @@ const slugify = (value) => value
     .replace(/^-+|-+$/g, "")
     .replace(/-{2,}/g, "-") || "draft";
 const estimateTokens = (text) => Math.max(1, Math.ceil(text.length / 4));
+const extractJsonObject = (raw) => {
+    if (!raw)
+        return undefined;
+    const fenced = raw.match(/```json([\s\S]*?)```/i);
+    const candidate = fenced ? fenced[1] : raw;
+    const start = candidate.indexOf("{");
+    const end = candidate.lastIndexOf("}");
+    if (start === -1 || end === -1 || end < start)
+        return undefined;
+    try {
+        return JSON.parse(candidate.slice(start, end + 1));
+    }
+    catch {
+        return undefined;
+    }
+};
+const extractMarkdownFromOutput = (raw) => {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return "";
+    const fenced = [...trimmed.matchAll(/```(?:markdown|md)?\s*([\s\S]*?)```/gi)];
+    if (fenced.length === 0)
+        return trimmed;
+    const best = fenced
+        .map((match) => (match[1] ?? "").trim())
+        .sort((a, b) => b.length - a.length)[0];
+    return best || trimmed;
+};
+const nowIso = () => new Date().toISOString();
 const SDS_CONTEXT_TOKEN_BUDGET = 8000;
 const extractBullets = (content, limit = 20) => {
     return content
@@ -1168,11 +1197,13 @@ const ensureSdsStructuredDraft = (draft, projectKey, context, template) => {
         structured = ensureSectionContent(structured, section, fallbackFor(section));
     }
     if ((context.openapi?.length ?? 0) === 0) {
-        const interfaceTitle = sections.find((section) => /interface|contract/i.test(section)) ?? "Interfaces & Contracts";
+        const interfaceTitle = sections.find((section) => /(?:^|[\s,&/()-])(interface|interfaces|api|apis)(?:$|[\s,&/()-])/i.test(section)) ??
+            sections.find((section) => /contract/i.test(section)) ??
+            "Interfaces & Contracts";
         const extracted = extractSection(structured, interfaceTitle);
         if (extracted) {
             const scrubbed = stripInventedEndpoints(cleanBody(extracted.body ?? ""));
-            const openApiFallback = "No OpenAPI excerpts available. Capture interface needs as open questions (auth/identity, restaurant suggestions, voting cycles, results/analytics).";
+            const openApiFallback = "No OpenAPI excerpts available. Capture interface needs as explicit contracts, assumptions, and open questions without inventing endpoint paths.";
             let body = scrubbed.length > 0 && !/endpoint/i.test(scrubbed) ? scrubbed : cleanBody(openApiFallback);
             if (!/openapi/i.test(body)) {
                 body = `${body}\n- No OpenAPI excerpts available; keep endpoints as open questions.`;
@@ -1610,6 +1641,272 @@ export class DocsService {
         const slug = slugify(projectKey ?? "sds");
         return path.join(this.workspace.mcodaDir, "docs", "sds", `${slug}.md`);
     }
+    normalizeMaxIterations(value) {
+        if (!Number.isFinite(value))
+            return 100;
+        const floored = Math.floor(value);
+        if (floored < 1)
+            return 1;
+        if (floored > 100)
+            return 100;
+        return floored;
+    }
+    async listSdsSuggestionPathCandidates(projectKey) {
+        const projectSlug = slugify(projectKey ?? "sds");
+        const prioritized = [
+            path.join(this.workspace.workspaceRoot, "docs", "sds", "sds.md"),
+            path.join(this.workspace.workspaceRoot, "docs", "sds.md"),
+        ];
+        const dynamicDir = path.join(this.workspace.workspaceRoot, "docs", "sds");
+        const dynamicCandidates = [];
+        try {
+            const entries = await fs.readdir(dynamicDir, { withFileTypes: true });
+            const markdown = entries
+                .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".md"))
+                .map((entry) => path.join(dynamicDir, entry.name));
+            const statRows = await Promise.all(markdown.map(async (candidatePath) => ({
+                candidatePath,
+                stat: await fs.stat(candidatePath),
+            })));
+            statRows
+                .sort((a, b) => b.stat.mtimeMs - a.stat.mtimeMs)
+                .forEach((row) => dynamicCandidates.push(row.candidatePath));
+        }
+        catch {
+            // Directory may not exist.
+        }
+        const fallback = [
+            path.join(this.workspace.mcodaDir, "docs", "sds", `${projectSlug}.md`),
+            path.join(this.workspace.mcodaDir, "docs", "sds", "sds.md"),
+        ];
+        return Array.from(new Set([...prioritized, ...dynamicCandidates, ...fallback]));
+    }
+    async resolveSdsSuggestionsPath(projectKey, explicitSdsPath) {
+        if (explicitSdsPath) {
+            const resolved = path.isAbsolute(explicitSdsPath)
+                ? explicitSdsPath
+                : path.resolve(this.workspace.workspaceRoot, explicitSdsPath);
+            try {
+                await fs.access(resolved);
+            }
+            catch {
+                throw new Error(`Unable to locate SDS file at --sds-path: ${resolved}`);
+            }
+            return { path: resolved, attempted: [resolved] };
+        }
+        const attempted = await this.listSdsSuggestionPathCandidates(projectKey);
+        for (const candidate of attempted) {
+            try {
+                const stat = await fs.stat(candidate);
+                if (stat.isFile()) {
+                    return { path: candidate, attempted };
+                }
+            }
+            catch {
+                // keep trying
+            }
+        }
+        throw new Error(`Unable to locate an SDS file. Checked: ${attempted.join(", ")}. ` +
+            `Pass --sds-path <FILE> to specify the SDS explicitly.`);
+    }
+    async ensureSuggestionsDir() {
+        const suggestionsDir = path.join(this.workspace.workspaceRoot, "docs", "suggestions");
+        await fs.mkdir(suggestionsDir, { recursive: true });
+        return suggestionsDir;
+    }
+    async nextSuggestionsFilePath(suggestionsDir) {
+        const entries = await fs.readdir(suggestionsDir).catch(() => []);
+        const numbers = entries
+            .map((entry) => /^sds_suggestions(\d+)\.md$/i.exec(entry))
+            .filter((match) => Boolean(match))
+            .map((match) => Number.parseInt(match[1], 10))
+            .filter((value) => Number.isFinite(value));
+        const next = (numbers.length > 0 ? Math.max(...numbers) : 0) + 1;
+        return path.join(suggestionsDir, `sds_suggestions${next}.md`);
+    }
+    rankSdsSuggestionCandidates(candidates, required, preferred) {
+        const requiredCaps = Array.from(new Set(required));
+        const preferredCaps = Array.from(new Set(preferred));
+        const scored = candidates
+            .filter((candidate) => candidate.healthStatus !== "unreachable")
+            .map((candidate) => {
+            const caps = Array.from(new Set(candidate.capabilities ?? []));
+            const requiredMatches = requiredCaps.filter((cap) => caps.includes(cap)).length;
+            const preferredMatches = preferredCaps.filter((cap) => caps.includes(cap)).length;
+            const hasRequired = requiredCaps.length === 0 || requiredMatches === requiredCaps.length;
+            const rating = Number(candidate.agent.rating ?? 0);
+            const reasoning = Number(candidate.agent.reasoningRating ?? rating);
+            const cost = Number.isFinite(candidate.agent.costPerMillion)
+                ? Number(candidate.agent.costPerMillion)
+                : Number.POSITIVE_INFINITY;
+            return { candidate, requiredMatches, preferredMatches, hasRequired, rating, reasoning, cost };
+        });
+        scored.sort((a, b) => {
+            if (a.hasRequired !== b.hasRequired)
+                return a.hasRequired ? -1 : 1;
+            if (a.requiredMatches !== b.requiredMatches)
+                return b.requiredMatches - a.requiredMatches;
+            if (a.preferredMatches !== b.preferredMatches)
+                return b.preferredMatches - a.preferredMatches;
+            if (a.rating !== b.rating)
+                return b.rating - a.rating;
+            if (a.reasoning !== b.reasoning)
+                return b.reasoning - a.reasoning;
+            if (a.cost !== b.cost)
+                return a.cost - b.cost;
+            return (a.candidate.agent.slug ?? a.candidate.agent.id).localeCompare(b.candidate.agent.slug ?? b.candidate.agent.id);
+        });
+        return scored.map((row) => row.candidate);
+    }
+    async selectSdsSuggestionAgents(input) {
+        const required = ["doc_generation", "docdex_query"];
+        const preferred = ["sds_writing", "spec_generation", "code_review", "multiple_draft_generation"];
+        const warnings = [];
+        const candidates = this.rankSdsSuggestionCandidates(await this.collectDocgenCandidates(), required, preferred);
+        if (candidates.length === 0) {
+            throw new Error("No healthy agents are available for SDS suggestions.");
+        }
+        const findByName = async (name) => {
+            try {
+                return await this.agentService.resolveAgent(name);
+            }
+            catch {
+                throw new Error(`Unable to resolve agent: ${name}`);
+            }
+        };
+        const rankedIds = new Set(candidates.map((candidate) => candidate.agent.id));
+        const rankedSlugs = new Set(candidates.map((candidate) => candidate.agent.slug).filter(Boolean));
+        const isRankedCandidate = (agent) => rankedIds.has(agent.id) || (typeof agent.slug === "string" && rankedSlugs.has(agent.slug));
+        const reviewer = input.reviewAgentName
+            ? await findByName(input.reviewAgentName)
+            : candidates[0].agent;
+        const fixer = input.fixAgentName
+            ? await findByName(input.fixAgentName)
+            : candidates.find((candidate) => candidate.agent.id !== reviewer.id)?.agent ?? reviewer;
+        if (input.reviewAgentName && !isRankedCandidate(reviewer)) {
+            warnings.push(`Review agent override ${reviewer.slug ?? reviewer.id} is not in the healthy ranked candidate set; proceeding due explicit override.`);
+        }
+        if (input.fixAgentName && !isRankedCandidate(fixer)) {
+            warnings.push(`Fix agent override ${fixer.slug ?? fixer.id} is not in the healthy ranked candidate set; proceeding due explicit override.`);
+        }
+        if (reviewer.id === fixer.id) {
+            warnings.push(`Reviewer and fixer resolved to the same agent (${reviewer.slug ?? reviewer.id}); continuing with single-agent loop.`);
+        }
+        return { reviewer, fixer, warnings };
+    }
+    buildSdsSuggestionsReviewPrompt(input) {
+        const contextBlocks = input.context.blocks
+            .slice(0, 5)
+            .map((block) => `- ${block.summary}`)
+            .join("\n");
+        return [
+            "You are the SDS reviewer agent.",
+            "Review the SDS against surrounding project documentation and produce strict remediation guidance.",
+            "Focus on:",
+            "- open questions and optimum answers aligned to the rest of documentation,",
+            "- inconsistencies,",
+            "- issues/risks,",
+            "- possible enhancements.",
+            "",
+            "Return output in two parts:",
+            "1) A JSON object inside a ```json code block with schema:",
+            '{ "result": "PASS|FAIL", "issueCount": number, "summary": "short summary" }',
+            "2) Markdown sections:",
+            "## Open Questions and Optimum Answers",
+            "## Inconsistencies",
+            "## Issues",
+            "## Enhancements",
+            "## Suggested Fixes",
+            "",
+            "Set result=PASS and issueCount=0 only when there are no remaining issues.",
+            "",
+            `Iteration: ${input.iteration}`,
+            `Project: ${input.projectKey ?? "n/a"}`,
+            `SDS Path: ${input.sdsPath}`,
+            "",
+            `Context Summary: ${input.context.summary}`,
+            contextBlocks ? `Context Blocks:\n${contextBlocks}` : "Context Blocks: none",
+            "",
+            "SDS Content:",
+            input.sdsContent,
+        ].join("\n");
+    }
+    parseSdsSuggestionsReviewResult(raw) {
+        const parsed = extractJsonObject(raw);
+        const parsedResult = String(parsed?.result ?? parsed?.status ?? parsed?.outcome ?? "")
+            .trim()
+            .toUpperCase();
+        const parsedIssueCount = Number(parsed?.issueCount ?? parsed?.issues ?? parsed?.issue_count ?? NaN);
+        const summary = String(parsed?.summary ?? "").trim();
+        const normalized = raw.trim();
+        const hasNoIssuesSignal = /\bRESULT\s*:\s*PASS\b/i.test(normalized) ||
+            /\bno (remaining )?(issues|inconsistencies|open questions)\b/i.test(normalized) ||
+            /\ball clear\b/i.test(normalized);
+        const preliminaryResult = parsedResult === "PASS"
+            ? "PASS"
+            : parsedResult === "FAIL"
+                ? "FAIL"
+                : hasNoIssuesSignal
+                    ? "PASS"
+                    : "FAIL";
+        const issueCount = Number.isFinite(parsedIssueCount)
+            ? Math.max(0, Math.floor(parsedIssueCount))
+            : preliminaryResult === "PASS"
+                ? 0
+                : 1;
+        const result = preliminaryResult === "PASS" && issueCount === 0 ? "PASS" : "FAIL";
+        return {
+            result,
+            issueCount,
+            summary: summary || (result === "PASS" ? "No issues found." : "Issues detected."),
+            markdown: normalized,
+            raw,
+        };
+    }
+    buildSdsSuggestionsFixPrompt(input) {
+        return [
+            "You are the SDS fixer agent.",
+            "Apply all valid review suggestions to the SDS.",
+            "Integrate optimum answers for open questions and resolve inconsistencies/issues.",
+            "Preserve valid existing sections and improve structure where needed.",
+            "Return ONLY the full revised SDS markdown (no prose wrapper, no JSON).",
+            "",
+            `Project: ${input.projectKey ?? "n/a"}`,
+            `SDS Path: ${input.sdsPath}`,
+            "",
+            "Review Suggestions:",
+            input.suggestions,
+            "",
+            "Current SDS:",
+            input.currentSds,
+        ].join("\n");
+    }
+    renderSdsSuggestionArtifact(input) {
+        return [
+            `# SDS Suggestions ${input.iteration}`,
+            "",
+            `- Timestamp: ${input.timestamp}`,
+            `- Iteration: ${input.iteration}`,
+            `- Reviewer Agent: ${input.reviewer.slug ?? input.reviewer.id}`,
+            `- Fixer Agent: ${input.fixer.slug ?? input.fixer.id}`,
+            `- SDS Path: ${input.sdsPath}`,
+            `- Result: ${input.review.result}`,
+            `- Issue Count: ${input.review.issueCount}`,
+            `- Job ID: ${input.jobId}`,
+            `- Command Run ID: ${input.commandRunId}`,
+            "",
+            "## Review Summary",
+            input.review.summary,
+            "",
+            "## Reviewer Output",
+            input.review.markdown || "(empty reviewer output)",
+            "",
+            "## Fix Application",
+            `- Applied: ${input.fixApplied ? "yes" : "no"}`,
+            `- Summary: ${input.fixSummary}`,
+            "",
+        ].join("\n");
+    }
     async loadSdsTemplate(templateName) {
         const names = templateName
             ? [templateName.replace(/\.md$/i, "")]
@@ -3885,4 +4182,242 @@ export class DocsService {
             throw error;
         }
     }
+    async generateSdsSuggestions(options) {
+        const warnings = [];
+        await this.checkSdsDocdexProfile(warnings);
+        const assembler = new DocContextAssembler(this.docdex, this.workspace);
+        const stream = options.agentStream === true;
+        const maxIterations = this.normalizeMaxIterations(options.maxIterations);
+        const commandRun = await this.jobService.startCommandRun("docs-sds-suggestions", options.projectKey);
+        const job = await this.jobService.startJob("sds_suggestions", commandRun.id, options.projectKey, {
+            commandName: commandRun.commandName,
+            payload: {
+                projectKey: options.projectKey,
+                sdsPath: options.sdsPath,
+                reviewAgentName: options.reviewAgentName,
+                fixAgentName: options.fixAgentName,
+                maxIterations,
+            },
+        });
+        try {
+            const context = await assembler.buildSdsContext({ projectKey: options.projectKey });
+            warnings.push(...context.warnings);
+            const pathResolution = await this.resolveSdsSuggestionsPath(options.projectKey, options.sdsPath);
+            const sdsPath = pathResolution.path;
+            let sdsContent = await fs.readFile(sdsPath, "utf8");
+            const suggestionsDir = await this.ensureSuggestionsDir();
+            const agentSelection = await this.selectSdsSuggestionAgents({
+                reviewAgentName: options.reviewAgentName,
+                fixAgentName: options.fixAgentName,
+            });
+            warnings.push(...agentSelection.warnings);
+            const reviewer = agentSelection.reviewer;
+            const fixer = agentSelection.fixer;
+            const suggestionFiles = [];
+            let iterations = 0;
+            let finalStatus = "max_iterations_reached";
+            await this.jobService.writeCheckpoint(job.id, {
+                stage: "sds_loaded",
+                timestamp: nowIso(),
+                details: {
+                    sdsPath,
+                    attemptedPaths: pathResolution.attempted,
+                    maxIterations,
+                },
+            });
+            await this.jobService.writeCheckpoint(job.id, {
+                stage: "agents_selected",
+                timestamp: nowIso(),
+                details: {
+                    reviewerAgent: reviewer.slug ?? reviewer.id,
+                    fixerAgent: fixer.slug ?? fixer.id,
+                },
+            });
+            for (let iteration = 1; iteration <= maxIterations; iteration += 1) {
+                iterations = iteration;
+                const reviewPrompt = this.buildSdsSuggestionsReviewPrompt({
+                    iteration,
+                    projectKey: options.projectKey,
+                    sdsPath,
+                    sdsContent,
+                    context,
+                });
+                const reviewInvoke = await this.invokeAgent(reviewer, reviewPrompt, stream, job.id, options.onToken);
+                const reviewResult = this.parseSdsSuggestionsReviewResult(reviewInvoke.output);
+                const suggestionPath = await this.nextSuggestionsFilePath(suggestionsDir);
+                let fixApplied = false;
+                let fixSummary = "Fix pending.";
+                const preliminaryArtifact = this.renderSdsSuggestionArtifact({
+                    timestamp: nowIso(),
+                    iteration,
+                    reviewer,
+                    fixer,
+                    sdsPath,
+                    review: reviewResult,
+                    fixApplied,
+                    fixSummary,
+                    jobId: job.id,
+                    commandRunId: commandRun.id,
+                });
+                await fs.writeFile(suggestionPath, preliminaryArtifact, "utf8");
+                suggestionFiles.push(suggestionPath);
+                await this.jobService.writeCheckpoint(job.id, {
+                    stage: "iteration_reviewed",
+                    timestamp: nowIso(),
+                    details: {
+                        iteration,
+                        result: reviewResult.result,
+                        issueCount: reviewResult.issueCount,
+                        suggestionPath,
+                    },
+                });
+                if (reviewResult.result === "PASS" && reviewResult.issueCount === 0) {
+                    finalStatus = "pass";
+                    fixSummary = "Reviewer found no issues.";
+                    const artifact = this.renderSdsSuggestionArtifact({
+                        timestamp: nowIso(),
+                        iteration,
+                        reviewer,
+                        fixer,
+                        sdsPath,
+                        review: reviewResult,
+                        fixApplied,
+                        fixSummary,
+                        jobId: job.id,
+                        commandRunId: commandRun.id,
+                    });
+                    await fs.writeFile(suggestionPath, artifact, "utf8");
+                    break;
+                }
+                if (options.dryRun) {
+                    finalStatus = "dry_run";
+                    fixSummary = "Dry-run enabled; no SDS changes applied.";
+                    const artifact = this.renderSdsSuggestionArtifact({
+                        timestamp: nowIso(),
+                        iteration,
+                        reviewer,
+                        fixer,
+                        sdsPath,
+                        review: reviewResult,
+                        fixApplied,
+                        fixSummary,
+                        jobId: job.id,
+                        commandRunId: commandRun.id,
+                    });
+                    await fs.writeFile(suggestionPath, artifact, "utf8");
+                    break;
+                }
+                const suggestionsArtifact = await fs.readFile(suggestionPath, "utf8");
+                const fixPrompt = this.buildSdsSuggestionsFixPrompt({
+                    projectKey: options.projectKey,
+                    sdsPath,
+                    currentSds: sdsContent,
+                    suggestions: suggestionsArtifact,
+                });
+                const fixInvoke = await this.invokeAgent(fixer, fixPrompt, stream, job.id, options.onToken);
+                const candidateSds = extractMarkdownFromOutput(fixInvoke.output).trim();
+                if (candidateSds.length < 80) {
+                    fixSummary = "Fixer output was too short; previous SDS kept.";
+                    warnings.push(`Iteration ${iteration}: fixer output too short; no SDS write performed.`);
+                }
+                else if (candidateSds === sdsContent.trim()) {
+                    fixSummary = "Fixer returned unchanged SDS content.";
+                }
+                else {
+                    await fs.writeFile(sdsPath, candidateSds, "utf8");
+                    sdsContent = candidateSds;
+                    fixApplied = true;
+                    fixSummary = "SDS updated from fixer output.";
+                    if (context.docdexAvailable) {
+                        try {
+                            await this.registerSds(sdsPath, sdsContent, options.projectKey);
+                        }
+                        catch (error) {
+                            warnings.push(`Iteration ${iteration}: docdex register skipped: ${error.message}`);
+                        }
+                    }
+                }
+                const artifact = this.renderSdsSuggestionArtifact({
+                    timestamp: nowIso(),
+                    iteration,
+                    reviewer,
+                    fixer,
+                    sdsPath,
+                    review: reviewResult,
+                    fixApplied,
+                    fixSummary,
+                    jobId: job.id,
+                    commandRunId: commandRun.id,
+                });
+                await fs.writeFile(suggestionPath, artifact, "utf8");
+                await this.jobService.writeCheckpoint(job.id, {
+                    stage: "iteration_fixed",
+                    timestamp: nowIso(),
+                    details: {
+                        iteration,
+                        result: reviewResult.result,
+                        issueCount: reviewResult.issueCount,
+                        fixApplied,
+                        suggestionPath,
+                    },
+                });
+            }
+            if (finalStatus === "max_iterations_reached") {
+                warnings.push(`SDS suggestions stopped at max iterations (${maxIterations}) before reviewer returned PASS.`);
+            }
+            await this.jobService.updateJobStatus(job.id, "completed", {
+                payload: {
+                    sdsPath,
+                    suggestionsDir,
+                    suggestionFiles,
+                    reviewerAgentId: reviewer.id,
+                    fixerAgentId: fixer.id,
+                    iterations,
+                    finalStatus,
+                },
+            });
+            await this.jobService.finishCommandRun(commandRun.id, "succeeded");
+            if (options.rateAgents) {
+                try {
+                    const ratingService = await this.ensureRatingService();
+                    await ratingService.rate({
+                        workspace: this.workspace,
+                        agentId: reviewer.id,
+                        commandName: "docs-sds-suggestions-review",
+                        jobId: job.id,
+                        commandRunId: commandRun.id,
+                    });
+                    if (fixer.id !== reviewer.id) {
+                        await ratingService.rate({
+                            workspace: this.workspace,
+                            agentId: fixer.id,
+                            commandName: "docs-sds-suggestions-fix",
+                            jobId: job.id,
+                            commandRunId: commandRun.id,
+                        });
+                    }
+                }
+                catch (error) {
+                    warnings.push(`Agent rating failed: ${error.message ?? String(error)}`);
+                }
+            }
+            return {
+                jobId: job.id,
+                commandRunId: commandRun.id,
+                sdsPath,
+                suggestionsDir,
+                suggestionFiles,
+                reviewerAgentId: reviewer.id,
+                fixerAgentId: fixer.id,
+                iterations,
+                finalStatus,
+                warnings,
+            };
+        }
+        catch (error) {
+            await this.jobService.updateJobStatus(job.id, "failed", { errorSummary: error.message });
+            await this.jobService.finishCommandRun(commandRun.id, "failed", error.message);
+            throw error;
+        }
+    }
 }

package/dist/services/docs/review/gates/OpenQuestionsGate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OpenQuestionsGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/OpenQuestionsGate.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAA+B,MAAM,mBAAmB,CAAC;AAElF,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,uBAAuB,CAAC;CACpC;AAuLD,eAAO,MAAM,oBAAoB,GAC/B,OAAO,sBAAsB,KAC5B,OAAO,CAAC,gBAAgB,CA+C1B,CAAC"}
+{"version":3,"file":"OpenQuestionsGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/OpenQuestionsGate.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAA+B,MAAM,mBAAmB,CAAC;AAElF,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,uBAAuB,CAAC;CACpC;AAmMD,eAAO,MAAM,oBAAoB,GAC/B,OAAO,sBAAsB,KAC5B,OAAO,CAAC,gBAAgB,CA+C1B,CAAC"}

package/dist/services/docs/review/gates/OpenQuestionsGate.js

@@ -32,7 +32,9 @@ const IMPLICIT_PATTERNS = [
 const isFenceLine = (line) => /^```|^~~~/.test(line.trim());
 const isExampleHeading = (heading) => /example|sample/i.test(heading);
 const isOpenQuestionsHeading = (heading) => /open (questions?|issues?|items?)|unresolved questions?/i.test(heading);
-const RESOLVED_HINTS = [/^\s*resolved[:\]]/i, /^\s*decision:/i, /\[resolved\]/i];
+const MANAGED_PREFLIGHT_START = "<!-- mcoda:sds-preflight:start -->";
+const MANAGED_PREFLIGHT_END = "<!-- mcoda:sds-preflight:end -->";
+const RESOLVED_HINTS = [/^[-*+\d.)\s]*resolved[:\]]/i, /^[-*+\d.)\s]*decision:/i, /\[resolved\]/i];
 const isResolvedLine = (line) => RESOLVED_HINTS.some((pattern) => pattern.test(line.trim()));
 const normalizeQuestion = (text) => text
     .toLowerCase()
@@ -105,6 +107,7 @@ const extractQuestions = async (record) => {
         const lines = content.split(/\r?\n/);
         const questions = [];
         let inFence = false;
+        let inManagedPreflight = false;
         let allowSection = false;
         let inOpenSection = false;
         let currentHeading;
@@ -113,6 +116,14 @@ const extractQuestions = async (record) => {
             const trimmed = line.trim();
             if (!trimmed)
                 continue;
+            if (trimmed === MANAGED_PREFLIGHT_START) {
+                inManagedPreflight = true;
+                continue;
+            }
+            if (trimmed === MANAGED_PREFLIGHT_END) {
+                inManagedPreflight = false;
+                continue;
+            }
             if (isFenceLine(trimmed)) {
                 inFence = !inFence;
                 continue;
@@ -124,7 +135,7 @@ const extractQuestions = async (record) => {
                 inOpenSection = currentHeading ? isOpenQuestionsHeading(currentHeading) : false;
                 continue;
             }
-            if (inFence || allowSection)
+            if (inFence || inManagedPreflight || allowSection)
                 continue;
             if (isResolvedLine(trimmed))
                 continue;

package/dist/services/docs/review/gates/SdsNoUnresolvedItemsGate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SdsNoUnresolvedItemsGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/SdsNoUnresolvedItemsGate.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAe,MAAM,mBAAmB,CAAC;AAElE,MAAM,WAAW,6BAA6B;IAC5C,SAAS,EAAE,uBAAuB,CAAC;CACpC;AA4CD,eAAO,MAAM,2BAA2B,GACtC,OAAO,6BAA6B,KACnC,OAAO,CAAC,gBAAgB,CAsF1B,CAAC"}
+{"version":3,"file":"SdsNoUnresolvedItemsGate.d.ts","sourceRoot":"","sources":["../../../../../src/services/docs/review/gates/SdsNoUnresolvedItemsGate.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAe,MAAM,mBAAmB,CAAC;AAElE,MAAM,WAAW,6BAA6B;IAC5C,SAAS,EAAE,uBAAuB,CAAC;CACpC;AA8CD,eAAO,MAAM,2BAA2B,GACtC,OAAO,6BAA6B,KACnC,OAAO,CAAC,gBAAgB,CAgG1B,CAAC"}

package/dist/services/docs/review/gates/SdsNoUnresolvedItemsGate.js

@@ -11,6 +11,8 @@ const UNRESOLVED_PATTERNS = [
 const OPEN_QUESTIONS_HEADING = /open questions?/i;
 const RESOLVED_LINE = /^[-*+\d.)\s]*resolved:/i;
 const NO_OPEN_ITEMS_LINE = /no unresolved questions remain|no open questions remain/i;
+const MANAGED_PREFLIGHT_START = "<!-- mcoda:sds-preflight:start -->";
+const MANAGED_PREFLIGHT_END = "<!-- mcoda:sds-preflight:end -->";
 const isFenceLine = (line) => /^```|^~~~/.test(line.trim());
 const buildIssue = (input) => ({
     id: input.id,
@@ -46,17 +48,26 @@ export const runSdsNoUnresolvedItemsGate = async (input) => {
         const content = await fs.readFile(sds.path, "utf8");
         const lines = content.split(/\r?\n/);
         let inFence = false;
+        let inManagedPreflight = false;
         let inOpenQuestions = false;
         for (let i = 0; i < lines.length; i += 1) {
             const line = lines[i] ?? "";
             const trimmed = line.trim();
             if (!trimmed)
                 continue;
+            if (trimmed === MANAGED_PREFLIGHT_START) {
+                inManagedPreflight = true;
+                continue;
+            }
+            if (trimmed === MANAGED_PREFLIGHT_END) {
+                inManagedPreflight = false;
+                continue;
+            }
             if (isFenceLine(trimmed)) {
                 inFence = !inFence;
                 continue;
             }
-            if (inFence)
+            if (inFence || inManagedPreflight)
                 continue;
             const heading = trimmed.match(/^#{1,6}\s+(.*)$/);
             if (heading) {