@mcoda/core 0.1.8 → 0.1.11

package/dist/services/docs/DocsService.js

@@ -1,15 +1,81 @@
 import path from "node:path";
 import { promises as fs } from "node:fs";
 import { AgentService } from "@mcoda/agents";
-import { GlobalRepository } from "@mcoda/db";
+import { DocsScaffolder } from "@mcoda/generators";
+import { GlobalRepository, WorkspaceRepository } from "@mcoda/db";
 import { DocdexClient } from "@mcoda/integrations";
 import { DEFAULT_PDR_CHARACTER_PROMPT, DEFAULT_PDR_JOB_PROMPT, DEFAULT_PDR_RUNBOOK_PROMPT, } from "../../prompts/PdrPrompts.js";
 import { DEFAULT_SDS_CHARACTER_PROMPT, DEFAULT_SDS_JOB_PROMPT, DEFAULT_SDS_RUNBOOK_PROMPT, DEFAULT_SDS_TEMPLATE, } from "../../prompts/SdsPrompts.js";
+import { createEmptyArtifacts, } from "./DocgenRunContext.js";
+import { buildDocInventory } from "./DocInventory.js";
+import { DocPatchEngine, } from "./patch/DocPatchEngine.js";
+import { runApiPathConsistencyGate } from "./review/gates/ApiPathConsistencyGate.js";
+import { runOpenApiCoverageGate } from "./review/gates/OpenApiCoverageGate.js";
+import { runBuildReadyCompletenessGate } from "./review/gates/BuildReadyCompletenessGate.js";
+import { runDeploymentBlueprintGate } from "./review/gates/DeploymentBlueprintGate.js";
+import { runPlaceholderArtifactGate } from "./review/gates/PlaceholderArtifactGate.js";
+import { runSqlSyntaxGate } from "./review/gates/SqlSyntaxGate.js";
+import { runSqlRequiredTablesGate } from "./review/gates/SqlRequiredTablesGate.js";
+import { runTerminologyNormalizationGate } from "./review/gates/TerminologyNormalizationGate.js";
+import { runOpenQuestionsGate } from "./review/gates/OpenQuestionsGate.js";
+import { runNoMaybesGate } from "./review/gates/NoMaybesGate.js";
+import { runRfpConsentGate } from "./review/gates/RfpConsentGate.js";
+import { runRfpDefinitionGate } from "./review/gates/RfpDefinitionGate.js";
+import { runPdrInterfacesGate } from "./review/gates/PdrInterfacesGate.js";
+import { runPdrOwnershipGate } from "./review/gates/PdrOwnershipGate.js";
+import { runPdrOpenQuestionsGate } from "./review/gates/PdrOpenQuestionsGate.js";
+import { runSdsDecisionsGate } from "./review/gates/SdsDecisionsGate.js";
+import { runSdsPolicyTelemetryGate } from "./review/gates/SdsPolicyTelemetryGate.js";
+import { runSdsOpsGate } from "./review/gates/SdsOpsGate.js";
+import { runSdsAdaptersGate } from "./review/gates/SdsAdaptersGate.js";
+import { runAdminOpenApiSpecGate } from "./review/gates/AdminOpenApiSpecGate.js";
+import { runOpenApiSchemaSanityGate } from "./review/gates/OpenApiSchemaSanityGate.js";
+import { renderReviewReport } from "./review/ReviewReportRenderer.js";
+import { serializeReviewReport, } from "./review/ReviewReportSchema.js";
+import { aggregateReviewOutcome, } from "./review/ReviewTypes.js";
+import { findAdminSurfaceMentions, validateOpenApiSchemaContent } from "../openapi/OpenApiService.js";
 import { JobService } from "../jobs/JobService.js";
+import { cleanupWorkspaceStateDirs, resolveDocgenStatePath, } from "../../workspace/WorkspaceManager.js";
 import { RoutingService } from "../agents/RoutingService.js";
+import { AgentRatingService, selectBestAgentForCapabilities, } from "../agents/AgentRatingService.js";
+import { DocAlignmentPatcher } from "./alignment/DocAlignmentPatcher.js";
+import { ToolDenylist } from "../system/ToolDenylist.js";
 const ensureDir = async (targetPath) => {
     await fs.mkdir(path.dirname(targetPath), { recursive: true });
 };
+const parseDelimitedList = (value) => {
+    if (!value)
+        return [];
+    return value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+};
+const ALWAYS_BLOCKING_GATES = new Set([
+    "gate-placeholder-artifacts",
+    "gate-no-maybes",
+    "gate-pdr-open-questions-quality",
+]);
+const BUILD_READY_ONLY_GATES = new Set([
+    "gate-api-path-consistency",
+    "gate-openapi-schema-sanity",
+    "gate-openapi-coverage",
+    "gate-sql-syntax",
+    "gate-sql-required-tables",
+    "gate-admin-openapi-spec",
+    "gate-terminology-normalization",
+    "gate-open-questions",
+    "gate-rfp-consent-contradictions",
+    "gate-rfp-definition-coverage",
+    "gate-pdr-interfaces-pipeline",
+    "gate-pdr-ownership-consent-flow",
+    "gate-sds-explicit-decisions",
+    "gate-sds-policy-telemetry-metering",
+    "gate-sds-ops-observability-testing",
+    "gate-sds-external-adapters",
+    "gate-deployment-blueprint-validator",
+    "gate-build-ready-completeness",
+]);
 const readPromptIfExists = async (workspace, relative) => {
     const candidate = path.join(workspace.mcodaDir, relative);
     try {
@@ -22,6 +88,7 @@ const readPromptIfExists = async (workspace, relative) => {
 const PDR_REQUIRED_HEADINGS = [
     ["Introduction"],
     ["Scope"],
+    ["Technology Stack", "Tech Stack"],
     ["Requirements", "Requirements & Constraints"],
     ["Architecture", "Architecture Overview"],
     ["Interfaces", "Interfaces / APIs"],
@@ -88,6 +155,43 @@ const extractBullets = (content, limit = 20) => {
         .filter((line) => line.length > 0)
         .slice(0, limit);
 };
+const DEFAULT_TECH_STACK_FALLBACK = [
+    "- Frontend: React + TypeScript",
+    "- Backend/services: TypeScript (Node.js)",
+    "- Database: MySQL",
+    "- Cache/queues: Redis",
+    "- Scripting/ops: Bash",
+    "- Override defaults if the RFP specifies a different stack.",
+].join("\n");
+const ML_TECH_STACK_FALLBACK = [
+    "- Language: Python",
+    "- ML stack: PyTorch or TensorFlow (pick based on model requirements)",
+    "- Services/API: Python web framework (FastAPI/Flask) as needed",
+    "- Database: MySQL",
+    "- Cache/queues: Redis",
+    "- Scripting/ops: Bash",
+    "- Override defaults if the RFP specifies a different stack.",
+].join("\n");
+const contextIndicatesMlStack = (context) => {
+    const sources = [context.rfp?.content, ...context.related.map((doc) => doc.content ?? "")].filter(Boolean);
+    if (!sources.length)
+        return false;
+    const text = sources.join("\n").toLowerCase();
+    const patterns = [
+        /\bmachine learning\b/,
+        /\bdeep learning\b/,
+        /\bneural\b/,
+        /\bmodel training\b/,
+        /\bmodel inference\b/,
+        /\bml\b/,
+        /\bllm\b/,
+        /\bembeddings?\b/,
+    ];
+    return patterns.some((pattern) => pattern.test(text));
+};
+const resolveTechStackFallback = (context) => {
+    return contextIndicatesMlStack(context) ? ML_TECH_STACK_FALLBACK : DEFAULT_TECH_STACK_FALLBACK;
+};
 class DocContextAssembler {
     constructor(docdex, workspace) {
         this.docdex = docdex;
@@ -100,9 +204,28 @@ class DocContextAssembler {
     }
     async findLatestLocalDoc(docType) {
         const candidates = [];
+        const lower = docType.toLowerCase();
+        const explicitFiles = [
+            path.join(this.workspace.mcodaDir, "docs", `${lower}.md`),
+            path.join(this.workspace.workspaceRoot, "docs", `${lower}.md`),
+        ];
+        const addCandidate = async (candidatePath) => {
+            try {
+                const stat = await fs.stat(candidatePath);
+                if (stat.isFile()) {
+                    candidates.push({ path: candidatePath, mtime: stat.mtimeMs });
+                }
+            }
+            catch {
+                // ignore
+            }
+        };
+        for (const filePath of explicitFiles) {
+            await addCandidate(filePath);
+        }
         const dirs = [
-            path.join(this.workspace.mcodaDir, "docs", docType.toLowerCase()),
-            path.join(this.workspace.workspaceRoot, "docs", docType.toLowerCase()),
+            path.join(this.workspace.mcodaDir, "docs", lower),
+            path.join(this.workspace.workspaceRoot, "docs", lower),
         ];
         for (const dir of dirs) {
             try {
@@ -237,7 +360,7 @@ class DocContextAssembler {
                 existingSds = [localSds];
         }
         if (!pdrs.length && !rfp) {
-            throw new Error("No PDR or RFP content could be resolved. Ensure docdex is reachable with an sds_default profile or add local docs under .mcoda/docs/pdr and docs/rfp.");
+            throw new Error(`No PDR or RFP content could be resolved. Ensure docdex is reachable with an sds_default profile or add local docs under ${path.join(this.workspace.mcodaDir, "docs", "pdr")} and docs/rfp (or docs/rfp.md).`);
         }
         const blocks = [];
         if (rfp)
@@ -330,10 +453,22 @@ class DocContextAssembler {
         }
         let related = [];
         if (docdexAvailable) {
-            related = await this.docdex.search({ projectKey: input.projectKey, docType: "PDR", profile: "rfp_default" });
-            const sds = await this.docdex.search({ projectKey: input.projectKey, docType: "SDS", profile: "rfp_default" });
-            openapi = await this.docdex.search({ projectKey: input.projectKey, docType: "OPENAPI", profile: "rfp_default" });
-            related = [...related, ...sds];
+            try {
+                related = await this.docdex.search({ projectKey: input.projectKey, docType: "PDR", profile: "rfp_default" });
+                const sds = await this.docdex.search({ projectKey: input.projectKey, docType: "SDS", profile: "rfp_default" });
+                openapi = await this.docdex.search({
+                    projectKey: input.projectKey,
+                    docType: "OPENAPI",
+                    profile: "rfp_default",
+                });
+                related = [...related, ...sds];
+            }
+            catch (error) {
+                docdexAvailable = false;
+                related = [];
+                openapi = [];
+                warnings.push(`Docdex unavailable; continuing without related docs (${error.message ?? "unknown error"}).`);
+            }
         }
         const summaryParts = [
             `RFP: ${this.summarize(rfp)}`,
@@ -383,7 +518,7 @@ const buildRunPrompt = (context, projectKey, prompts, runbook) => {
         docdexNote,
         [
             "Return markdown with exactly these sections as H2 headings, one time each:",
-            "Introduction, Scope, Requirements & Constraints, Architecture Overview, Interfaces / APIs, Non-Functional Requirements, Risks & Mitigations, Open Questions, Acceptance Criteria",
+            "Introduction, Scope, Technology Stack, Requirements & Constraints, Architecture Overview, Interfaces / APIs, Non-Functional Requirements, Risks & Mitigations, Open Questions, Acceptance Criteria",
             "Do not use bold headings; use `##` headings only. Do not repeat sections.",
         ].join("\n"),
         runbookPrompt,
@@ -421,12 +556,14 @@ const buildSdsRunPrompt = (context, projectKey, prompts, runbook, template) => {
 const ensureStructuredDraft = (draft, projectKey, context, rfpSource) => {
     const canonicalTitles = PDR_REQUIRED_HEADINGS.map((variants) => variants[0]);
     const normalized = normalizeHeadingsToH2(draft, canonicalTitles);
+    const techStackFallback = resolveTechStackFallback(context);
     const required = [
         { title: "Introduction", fallback: `This PDR summarizes project ${projectKey ?? "N/A"} based on ${rfpSource}.` },
         {
             title: "Scope",
             fallback: "In-scope: todo CRUD (title required; optional description, due date, priority), status toggle, filters/sort/search, bulk complete/delete, keyboard shortcuts, responsive UI, offline/localStorage. Out-of-scope: multi-user/auth/sync/backends, notifications/reminders, team features, heavy UI kits.",
         },
+        { title: "Technology Stack", fallback: techStackFallback },
         {
             title: "Requirements & Constraints",
             fallback: context.bullets.map((b) => `- ${b}`).join("\n") ||
@@ -444,7 +581,20 @@ const ensureStructuredDraft = (draft, projectKey, context, rfpSource) => {
     for (const section of required) {
         const best = getBestSectionBody(normalized, section.title);
         const cleaned = cleanBody(best ?? "");
-        const body = cleaned && cleaned.length > 0 ? cleaned : cleanBody(section.fallback);
+        let body = cleaned && cleaned.length > 0 ? cleaned : cleanBody(section.fallback);
+        if (section.title === "Interfaces / APIs" && (context.openapi?.length ?? 0) === 0) {
+            const scrubbed = stripInventedEndpoints(body);
+            const openApiFallback = "No OpenAPI excerpts available. Capture interface needs as open questions (authentication/identity, data access, integrations, eventing, analytics/observability).";
+            if (!scrubbed || scrubbed.length === 0 || /endpoint/i.test(scrubbed)) {
+                body = cleanBody(openApiFallback);
+            }
+            else {
+                body = scrubbed;
+            }
+            if (!/openapi/i.test(body)) {
+                body = `${body}\n- No OpenAPI excerpts available; keep endpoints as open questions.`;
+            }
+        }
         parts.push(`## ${section.title}`);
         parts.push(body);
     }
@@ -458,7 +608,7 @@ const tidyPdrDraft = async (draft, agent, invoke) => {
         draft,
         "",
         "Requirements:",
-        "- Keep exactly one instance of each H2 section: Introduction, Scope, Requirements & Constraints, Architecture Overview, Interfaces / APIs, Non-Functional Requirements, Risks & Mitigations, Open Questions, Acceptance Criteria, Source RFP.",
+        "- Keep exactly one instance of each H2 section: Introduction, Scope, Technology Stack, Requirements & Constraints, Architecture Overview, Interfaces / APIs, Non-Functional Requirements, Risks & Mitigations, Open Questions, Acceptance Criteria, Source RFP.",
         "- Remove duplicate sections, bold headings posing as sections, placeholder sentences, and repeated bullet blocks. If the same idea appears twice, keep the richer/longer version and drop the restatement.",
         "- Do not add new sections or reorder the required outline.",
         "- Keep content concise and aligned to the headings. Do not alter semantics.",
@@ -468,6 +618,13 @@ const tidyPdrDraft = async (draft, agent, invoke) => {
     return output.trim();
 };
 const PDR_ENRICHMENT_SECTIONS = [
+    {
+        title: "Technology Stack",
+        guidance: [
+            "List frontend, backend/services, databases, caches/queues, infra/runtime, and scripting/tooling choices.",
+            "If the RFP omits stack details, state the default stack (TypeScript/React/MySQL/Redis/Bash) or a Python ML stack when neural/ML workloads are explicit.",
+        ],
+    },
     {
         title: "Architecture Overview",
         guidance: [
@@ -588,6 +745,19 @@ const ensureSdsStructuredDraft = (draft, projectKey, context, template) => {
     for (const section of sections) {
         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 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).";
+            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.`;
+            }
+            structured = replaceSection(structured, interfaceTitle, body);
+        }
+    }
     return structured;
 };
 const getSdsSections = (template) => {
@@ -847,6 +1017,7 @@ const PLACEHOLDER_PATTERNS = [
     /^[-*+.]?\s*Outstanding questions/i,
     /^[-*+.]?\s*Performance, reliability, compliance/i,
     /^[-*+.]?\s*Enumerate risks from the RFP/i,
+    /^I (will|am going to|plan to|am)\s+(read|review|analy[sz]e|gather|start|begin|look|scan)\b/i,
 ];
 const cleanBody = (body) => {
     const requiredTitles = PDR_REQUIRED_HEADINGS.flat().map((t) => t.toLowerCase());
@@ -887,6 +1058,14 @@ const cleanBody = (body) => {
     }
     return deduped.join("\n").trim();
 };
+const stripInventedEndpoints = (body) => {
+    const lines = body.split(/\r?\n/);
+    const filtered = lines.filter((line) => {
+        const normalized = line.replace(/[`*_]/g, "");
+        return !/(^|\s)\b(GET|POST|PUT|PATCH|DELETE)\b[^\n]*\//i.test(normalized);
+    });
+    return filtered.join("\n").trim();
+};
 const extractSection = (draft, title) => {
     const regex = new RegExp(`(^#{1,6}\\s+${title}\\b)([\\s\\S]*?)(?=^#{1,6}\\s+|(?![\\s\\S]))`, "im");
     const match = draft.match(regex);
@@ -910,7 +1089,7 @@ const getBestSectionBody = (draft, title) => {
 };
 const replaceSection = (draft, title, newBody) => {
     const normalizedBody = cleanBody(newBody);
-    const regex = new RegExp(`(^#{1,6}\\s+${title}\\b)([\\s\\S]*?)(?=^#{1,6}\\s+|$)`, "im");
+    const regex = new RegExp(`(^#{1,6}\\s+${title}\\b)([\\s\\S]*?)(?=^#{1,6}\\s+|(?![\\s\\S]))`, "im");
     if (regex.test(draft)) {
         return draft.replace(regex, `$1\n\n${normalizedBody}\n\n`);
     }
@@ -978,33 +1157,42 @@ const readGitBranch = async (workspaceRoot) => {
 export class DocsService {
     constructor(workspace, deps) {
         this.workspace = workspace;
-        this.docdex = deps?.docdex ?? new DocdexClient({ workspaceRoot: workspace.workspaceRoot });
+        const docdexRepoId = workspace.config?.docdexRepoId ?? process.env.MCODA_DOCDEX_REPO_ID ?? process.env.DOCDEX_REPO_ID;
+        this.docdex = deps?.docdex ?? new DocdexClient({ workspaceRoot: workspace.workspaceRoot, repoId: docdexRepoId });
         this.jobService = deps?.jobService ?? new JobService(workspace, undefined, { noTelemetry: deps?.noTelemetry });
         this.repo = deps.repo;
         this.agentService = deps.agentService;
         this.routingService = deps.routingService;
+        this.workspaceRepo = deps.workspaceRepo;
+        this.ratingService = deps.ratingService;
     }
     static async create(workspace, options = {}) {
         const repo = await GlobalRepository.create();
         const agentService = new AgentService(repo);
         const routingService = await RoutingService.create();
+        const docdexRepoId = workspace.config?.docdexRepoId ?? process.env.MCODA_DOCDEX_REPO_ID ?? process.env.DOCDEX_REPO_ID;
         const docdex = new DocdexClient({
             workspaceRoot: workspace.workspaceRoot,
             baseUrl: workspace.config?.docdexUrl ?? process.env.MCODA_DOCDEX_URL,
+            repoId: docdexRepoId,
         });
         const jobService = new JobService(workspace, undefined, { noTelemetry: options.noTelemetry });
         return new DocsService(workspace, { repo, agentService, routingService, docdex, jobService, noTelemetry: options.noTelemetry });
     }
     async close() {
-        if (this.agentService.close) {
-            await this.agentService.close();
-        }
-        if (this.repo.close) {
-            await this.repo.close();
-        }
-        if (this.jobService.close) {
-            await this.jobService.close();
-        }
+        const swallow = async (fn) => {
+            try {
+                if (fn)
+                    await fn();
+            }
+            catch {
+                // Best-effort close; ignore errors (including "database is closed").
+            }
+        };
+        await swallow(this.agentService.close?.bind(this.agentService));
+        await swallow(this.repo.close?.bind(this.repo));
+        await swallow(this.jobService.close?.bind(this.jobService));
+        await swallow(this.workspaceRepo?.close?.bind(this.workspaceRepo));
     }
     defaultPdrOutputPath(projectKey, rfpPath) {
         const slug = slugify(projectKey ?? (rfpPath ? path.basename(rfpPath, path.extname(rfpPath)) : "pdr"));
@@ -1036,14 +1224,1391 @@ export class DocsService {
         }
         return { name: templateName ?? "default", content: DEFAULT_SDS_TEMPLATE };
     }
-    async resolveAgent(agentName, commandAliases = ["docs-pdr-generate", "docs:pdr:generate", "pdr"]) {
-        const commandName = commandAliases[commandAliases.length - 1] ?? "pdr";
-        const resolved = await this.routingService.resolveAgentForCommand({
+    buildDocgenCapabilityProfile(input) {
+        const required = ["doc_generation", "docdex_query"];
+        const preferred = [];
+        if (input.commandName === "docs-pdr-generate") {
+            preferred.push("rfp_creation", "spec_generation");
+        }
+        if (input.commandName === "docs-sds-generate") {
+            preferred.push("sds_writing", "spec_generation");
+        }
+        if (input.iterationEnabled) {
+            preferred.push("multiple_draft_generation", "quick_bug_patching", "code_review");
+        }
+        return {
+            required: Array.from(new Set(required)),
+            preferred: Array.from(new Set(preferred)),
+        };
+    }
+    async collectDocgenCandidates(resolved) {
+        const candidates = new Map();
+        let agents = [];
+        try {
+            agents = await this.repo.listAgents();
+        }
+        catch {
+            agents = [];
+        }
+        let healthRows = [];
+        try {
+            healthRows = await this.repo.listAgentHealthSummary();
+        }
+        catch {
+            healthRows = [];
+        }
+        const healthById = new Map(healthRows.map((row) => [row.agentId, row.status]));
+        for (const agent of agents) {
+            let caps = [];
+            try {
+                caps = await this.repo.getAgentCapabilities(agent.id);
+            }
+            catch {
+                caps = agent.capabilities ?? [];
+            }
+            candidates.set(agent.id, {
+                agent,
+                capabilities: caps,
+                healthStatus: healthById.get(agent.id),
+            });
+        }
+        if (resolved) {
+            const existing = candidates.get(resolved.agent.id);
+            if (!existing || existing.capabilities.length === 0) {
+                candidates.set(resolved.agent.id, {
+                    agent: resolved.agent,
+                    capabilities: resolved.capabilities ?? [],
+                    healthStatus: resolved.healthStatus,
+                });
+            }
+        }
+        return Array.from(candidates.values());
+    }
+    async selectDocgenAgent(input) {
+        const commandName = input.commandAliases[input.commandAliases.length - 1] ?? input.commandName;
+        const profile = this.buildDocgenCapabilityProfile({
+            commandName: input.commandName,
+            iterationEnabled: input.iterationEnabled,
+        });
+        let resolved;
+        let resolveError;
+        try {
+            resolved = await this.routingService.resolveAgentForCommand({
+                workspace: this.workspace,
+                commandName,
+                overrideAgentSlug: input.agentName,
+                requiredCapabilities: profile.required,
+            });
+        }
+        catch (error) {
+            resolveError = error instanceof Error ? error : new Error(String(error));
+            resolved = undefined;
+        }
+        if (!resolved) {
+            const candidates = await this.collectDocgenCandidates();
+            const selection = selectBestAgentForCapabilities({
+                candidates,
+                required: profile.required,
+                preferred: profile.preferred,
+            });
+            if (!selection) {
+                throw resolveError ?? new Error("No agents available for doc generation.");
+            }
+            const selected = selection.agent;
+            const selectedLabel = selected.slug ?? selected.id;
+            const preferredLabel = input.agentName ?? "routing-default";
+            const warn = (message) => {
+                if (!input.warnings.includes(message)) {
+                    input.warnings.push(message);
+                }
+            };
+            warn(`Docgen preflight selected fallback agent ${selectedLabel} (preferred ${preferredLabel}).`);
+            if (selection.missingRequired.length > 0) {
+                warn(`Docgen preflight selected agent ${selectedLabel} missing required capabilities: ${selection.missingRequired.join(", ")}.`);
+            }
+            const logLines = [
+                `[docgen preflight] command=${input.commandName} routing=${commandName}`,
+                `[docgen preflight] preferred=${preferredLabel} selected=${selectedLabel} fallback=yes`,
+                `[docgen preflight] required=${profile.required.join(", ") || "none"}`,
+                `[docgen preflight] preferred_caps=${profile.preferred.join(", ") || "none"}`,
+                `[docgen preflight] missing_required=${selection.missingRequired.join(", ") || "none"}`,
+                `[docgen preflight] missing_preferred=${selection.missingPreferred.join(", ") || "none"}`,
+                `[docgen preflight] reason=${selection.reason}`,
+                resolveError ? `[docgen preflight] routing_error=${resolveError.message}` : undefined,
+            ].filter(Boolean);
+            await this.jobService.appendLog(input.jobId, `${logLines.join("\n")}\n`);
+            await this.jobService.writeCheckpoint(input.jobId, {
+                stage: "agent_preflight",
+                timestamp: new Date().toISOString(),
+                details: {
+                    commandName: input.commandName,
+                    routingCommand: commandName,
+                    preferredAgent: preferredLabel,
+                    selectedAgent: selectedLabel,
+                    fallbackUsed: true,
+                    requiredCapabilities: profile.required,
+                    preferredCapabilities: profile.preferred,
+                    missingRequired: selection.missingRequired,
+                    missingPreferred: selection.missingPreferred,
+                    reason: selection.reason,
+                    routingError: resolveError?.message,
+                },
+            });
+            return selected;
+        }
+        const resolvedMissing = profile.required.filter((cap) => !(resolved.capabilities ?? []).includes(cap));
+        const needsFallback = resolvedMissing.length > 0 || resolved.healthStatus === "unreachable";
+        const candidates = needsFallback ? await this.collectDocgenCandidates(resolved) : [];
+        const selection = needsFallback
+            ? selectBestAgentForCapabilities({
+                candidates,
+                required: profile.required,
+                preferred: profile.preferred,
+            })
+            : undefined;
+        const selected = selection?.agent ?? resolved.agent;
+        const missingRequired = selection?.missingRequired ?? resolvedMissing;
+        const missingPreferred = selection?.missingPreferred ??
+            profile.preferred.filter((cap) => !(resolved.capabilities ?? []).includes(cap));
+        const fallbackUsed = selected.id !== resolved.agent.id;
+        const preferredLabel = resolved.agent.slug ?? resolved.agent.id;
+        const selectedLabel = selected.slug ?? selected.id;
+        const warn = (message) => {
+            if (!input.warnings.includes(message)) {
+                input.warnings.push(message);
+            }
+        };
+        if (fallbackUsed) {
+            warn(`Docgen preflight selected fallback agent ${selectedLabel} (preferred ${preferredLabel}).`);
+        }
+        if (missingRequired.length > 0) {
+            warn(`Docgen preflight selected agent ${selectedLabel} missing required capabilities: ${missingRequired.join(", ")}.`);
+        }
+        const logLines = [
+            `[docgen preflight] command=${input.commandName} routing=${commandName}`,
+            `[docgen preflight] preferred=${preferredLabel} selected=${selectedLabel} fallback=${fallbackUsed ? "yes" : "no"}`,
+            `[docgen preflight] required=${profile.required.join(", ") || "none"}`,
+            `[docgen preflight] preferred_caps=${profile.preferred.join(", ") || "none"}`,
+            `[docgen preflight] missing_required=${missingRequired.join(", ") || "none"}`,
+            `[docgen preflight] missing_preferred=${missingPreferred.join(", ") || "none"}`,
+            `[docgen preflight] reason=${selection?.reason ?? "routing default"}`,
+        ];
+        await this.jobService.appendLog(input.jobId, `${logLines.join("\n")}\n`);
+        await this.jobService.writeCheckpoint(input.jobId, {
+            stage: "agent_preflight",
+            timestamp: new Date().toISOString(),
+            details: {
+                commandName: input.commandName,
+                routingCommand: commandName,
+                preferredAgent: preferredLabel,
+                selectedAgent: selectedLabel,
+                fallbackUsed,
+                requiredCapabilities: profile.required,
+                preferredCapabilities: profile.preferred,
+                missingRequired,
+                missingPreferred,
+                reason: selection?.reason,
+            },
+        });
+        return selected;
+    }
+    async ensureRatingService() {
+        if (this.ratingService)
+            return this.ratingService;
+        if (process.env.MCODA_DISABLE_DB === "1") {
+            throw new Error("Workspace DB disabled; agent rating requires DB access.");
+        }
+        if (!this.workspaceRepo) {
+            this.workspaceRepo = await WorkspaceRepository.create(this.workspace.workspaceRoot);
+        }
+        this.ratingService = new AgentRatingService(this.workspace, {
+            workspaceRepo: this.workspaceRepo,
+            globalRepo: this.repo,
+            agentService: this.agentService,
+            routingService: this.routingService,
+        });
+        return this.ratingService;
+    }
+    createRunContext(input) {
+        return {
+            version: 1,
+            commandName: input.commandName,
+            commandRunId: input.commandRunId,
+            jobId: input.jobId,
             workspace: this.workspace,
-            commandName,
-            overrideAgentSlug: agentName,
+            projectKey: input.projectKey,
+            rfpId: input.rfpId,
+            rfpPath: input.rfpPath,
+            templateName: input.templateName,
+            outputPath: input.outputPath,
+            createdAt: new Date().toISOString(),
+            flags: input.flags,
+            iteration: { current: 0, max: 0 },
+            artifacts: createEmptyArtifacts(),
+            warnings: input.warnings,
+        };
+    }
+    async recordDocgenStage(runContext, input) {
+        const iteration = runContext.iteration.max > 0 && runContext.iteration.current > 0
+            ? { current: runContext.iteration.current, max: runContext.iteration.max, phase: input.phase }
+            : undefined;
+        await this.jobService.recordJobProgress(runContext.jobId, {
+            stage: input.stage,
+            message: input.message,
+            iteration,
+            details: input.details,
+            totalItems: input.totalItems,
+            processedItems: input.processedItems,
+            heartbeat: input.heartbeat,
+        });
+    }
+    async enforceToolDenylist(input) {
+        const denylist = await ToolDenylist.load({
+            mcodaDir: this.workspace.mcodaDir,
+            env: process.env,
+        });
+        const identifiers = [input.agent.slug, input.agent.adapter, input.agent.id].filter((value) => Boolean(value));
+        const matched = denylist.findMatch(identifiers);
+        if (!matched)
+            return;
+        const message = denylist.formatViolation(matched);
+        const artifact = input.runContext.commandName === "docs-pdr-generate" ? "pdr" : "sds";
+        const issue = {
+            id: `gate-tool-denylist-${matched}`,
+            gateId: "gate-tool-denylist",
+            severity: "blocker",
+            category: "compliance",
+            artifact,
+            message,
+            remediation: "Select a non-deprecated agent or update the tool denylist configuration.",
+            location: {
+                kind: "heading",
+                heading: "Tooling Preflight",
+                path: input.runContext.outputPath,
+            },
+            metadata: {
+                matchedTool: matched,
+                identifiers,
+                agentId: input.agent.id,
+                agentSlug: input.agent.slug,
+                agentAdapter: input.agent.adapter,
+                denylist: denylist.list(),
+            },
+        };
+        const gateResult = {
+            gateId: "gate-tool-denylist",
+            gateName: "Tool Denylist",
+            status: "fail",
+            issues: [issue],
+            notes: [message],
+            metadata: {
+                matchedTool: matched,
+            },
+        };
+        if (input.runContext.iteration.max === 0) {
+            input.runContext.iteration.max = 1;
+        }
+        const report = this.buildReviewReport({
+            runContext: input.runContext,
+            gateResults: [gateResult],
+            remainingOpenItems: [issue],
+            fixesApplied: [],
+            iterationStatus: "completed",
+        });
+        await this.persistReviewReport(input.runContext, "review-final", report);
+        await this.jobService.appendLog(input.runContext.jobId, `${message}\n`);
+        await this.jobService.writeCheckpoint(input.runContext.jobId, {
+            stage: "tool_denylist_blocked",
+            timestamp: new Date().toISOString(),
+            details: {
+                matchedTool: matched,
+                identifiers,
+                denylist: denylist.list(),
+            },
+        });
+        throw new Error(message);
+    }
+    async applyDocPatches(runContext, patches, options) {
+        const engine = new DocPatchEngine();
+        return engine.apply({
+            runContext,
+            patches,
+            dryRun: options?.dryRun ?? runContext.flags.dryRun,
+        });
+    }
+    resolveMaxIterations() {
+        const raw = process.env.MCODA_DOCS_MAX_ITERATIONS;
+        if (!raw)
+            return 2;
+        const parsed = Number.parseInt(raw, 10);
+        if (!Number.isFinite(parsed) || parsed <= 0)
+            return 2;
+        return Math.max(1, parsed);
+    }
+    isIterationEnabled(runContext) {
+        if (runContext.flags.dryRun)
+            return false;
+        if (runContext.flags.iterate)
+            return true;
+        if (runContext.flags.fast)
+            return false;
+        return true;
+    }
+    shouldBlockGate(gateId, runContext) {
+        if (ALWAYS_BLOCKING_GATES.has(gateId))
+            return true;
+        const resolveOpenQuestions = runContext.flags.resolveOpenQuestions ||
+            process.env.MCODA_DOCS_RESOLVE_OPEN_QUESTIONS === "1";
+        if (gateId === "gate-open-questions" && resolveOpenQuestions) {
+            return true;
+        }
+        if (BUILD_READY_ONLY_GATES.has(gateId))
+            return runContext.flags.buildReady;
+        return false;
+    }
+    appendUniqueWarnings(runContext, values) {
+        for (const value of values) {
+            if (!value)
+                continue;
+            if (runContext.warnings.includes(value))
+                continue;
+            runContext.warnings.push(value);
+        }
+    }
+    summarizeIssues(issues) {
+        const summary = issues
+            .slice(0, 3)
+            .map((issue) => `${issue.artifact}: ${issue.message}`)
+            .join(" ");
+        const suffix = issues.length > 3 ? ` (+${issues.length - 3} more)` : "";
+        return `${summary}${suffix}`;
+    }
+    appendGateWarnings(runContext, gate, blocking) {
+        if (gate.notes?.length) {
+            this.appendUniqueWarnings(runContext, gate.notes);
+        }
+        if (blocking)
+            return;
+        if (gate.issues.length === 0)
+            return;
+        const summary = this.summarizeIssues(gate.issues);
+        this.appendUniqueWarnings(runContext, [
+            `${gate.gateName} issues (${gate.issues.length}). ${summary}`,
+        ]);
+    }
+    async runReviewGates(runContext, phase = "review") {
+        const gateResults = [];
+        const blockingIssues = [];
+        const phaseLabel = phase === "recheck" ? "Re-check" : "Review";
+        const runGate = async (gateId, gateName, runner) => {
+            await this.recordDocgenStage(runContext, {
+                stage: `${phase}:${gateId}`,
+                message: `${phaseLabel}: ${gateName}`,
+                phase,
+                heartbeat: true,
+                details: { gateId, gateName },
+            });
+            return await runner();
+        };
+        const addResult = (result) => {
+            const blocking = this.shouldBlockGate(result.gateId, runContext);
+            if (result.status === "fail" && blocking) {
+                blockingIssues.push(...result.issues);
+            }
+            const normalized = result.status === "fail" && !blocking ? { ...result, status: "warn" } : result;
+            this.appendGateWarnings(runContext, normalized, blocking);
+            gateResults.push(normalized);
+        };
+        const stateWarnings = (runContext.stateWarnings ?? []).filter((warning) => typeof warning === "string" && warning.trim().length > 0);
+        const stateArtifact = runContext.commandName === "docs-pdr-generate" ? "pdr" : "sds";
+        const stateIssues = stateWarnings.map((warning, index) => ({
+            id: `gate-state-dir-cleanup-${index + 1}`,
+            gateId: "gate-state-dir-cleanup",
+            severity: "info",
+            category: "compliance",
+            artifact: stateArtifact,
+            message: warning,
+            remediation: "Keep docgen intermediate state under .mcoda or OS temp directories and relocate legacy state directories into .mcoda.",
+            location: { kind: "heading", heading: "State Directory Cleanup", path: runContext.outputPath },
+        }));
+        addResult({
+            gateId: "gate-state-dir-cleanup",
+            gateName: "State Directory Cleanup",
+            status: stateIssues.length > 0 ? "warn" : "pass",
+            issues: stateIssues,
+        });
+        if (runContext.flags.noPlaceholders || runContext.flags.buildReady) {
+            const allowlist = parseDelimitedList(process.env.MCODA_DOCS_PLACEHOLDER_ALLOWLIST);
+            const denylist = parseDelimitedList(process.env.MCODA_DOCS_PLACEHOLDER_DENYLIST);
+            addResult(await runGate("gate-placeholder-artifacts", "Placeholder Artifacts", () => runPlaceholderArtifactGate({
+                artifacts: runContext.artifacts,
+                allowlist: allowlist.length > 0 ? allowlist : undefined,
+                denylist: denylist.length > 0 ? denylist : undefined,
+            })));
+        }
+        else {
+            const skippedGate = {
+                gateId: "gate-placeholder-artifacts",
+                gateName: "Placeholder Artifacts",
+                status: "skipped",
+                issues: [],
+                notes: ["Placeholder gate disabled (noPlaceholders/buildReady not set)."],
+            };
+            addResult(skippedGate);
+        }
+        addResult(await runGate("gate-api-path-consistency", "API Path Consistency", () => runApiPathConsistencyGate({ artifacts: runContext.artifacts })));
+        addResult(await runGate("gate-openapi-schema-sanity", "OpenAPI Schema Sanity", () => runOpenApiSchemaSanityGate({ artifacts: runContext.artifacts })));
+        addResult(await runGate("gate-openapi-coverage", "OpenAPI Coverage", () => runOpenApiCoverageGate({ artifacts: runContext.artifacts })));
+        addResult(await runGate("gate-sql-syntax", "SQL Syntax", () => runSqlSyntaxGate({ artifacts: runContext.artifacts })));
+        addResult(await runGate("gate-sql-required-tables", "SQL Required Tables", () => runSqlRequiredTablesGate({ artifacts: runContext.artifacts })));
+        addResult(await runGate("gate-admin-openapi-spec", "Admin OpenAPI Spec", () => runAdminOpenApiSpecGate({ artifacts: runContext.artifacts })));
+        addResult(await runGate("gate-terminology-normalization", "Terminology Normalization", () => runTerminologyNormalizationGate({ artifacts: runContext.artifacts })));
+        addResult(await runGate("gate-open-questions", "Open Questions", () => runOpenQuestionsGate({ artifacts: runContext.artifacts })));
+        const resolveOpenQuestions = runContext.flags.resolveOpenQuestions ||
+            process.env.MCODA_DOCS_RESOLVE_OPEN_QUESTIONS === "1";
+        const noMaybesEnabled = runContext.flags.noMaybes ||
+            process.env.MCODA_DOCS_NO_MAYBES === "1" ||
+            resolveOpenQuestions;
+        addResult(await runGate("gate-no-maybes", "No Maybes", () => runNoMaybesGate({
+            artifacts: runContext.artifacts,
+            enabled: noMaybesEnabled,
+        })));
+        addResult(await runGate("gate-rfp-consent", "RFP Consent", () => runRfpConsentGate({ rfpPath: runContext.rfpPath })));
+        const definitionAllowlist = parseDelimitedList(process.env.MCODA_DOCS_RFP_DEFINITION_ALLOWLIST);
+        addResult(await runGate("gate-rfp-definition", "RFP Definition Coverage", () => runRfpDefinitionGate({
+            rfpPath: runContext.rfpPath,
+            allowlist: definitionAllowlist.length > 0 ? definitionAllowlist : undefined,
+        })));
+        addResult(await runGate("gate-pdr-interfaces", "PDR Interfaces", () => runPdrInterfacesGate({ artifacts: runContext.artifacts })));
+        addResult(await runGate("gate-pdr-ownership", "PDR Ownership", () => runPdrOwnershipGate({ artifacts: runContext.artifacts })));
+        const openQuestionsEnabled = resolveOpenQuestions;
+        addResult(await runGate("gate-pdr-open-questions", "PDR Open Questions", () => runPdrOpenQuestionsGate({
+            artifacts: runContext.artifacts,
+            enabled: openQuestionsEnabled,
+        })));
+        addResult(await runGate("gate-sds-explicit-decisions", "SDS Explicit Decisions", () => runSdsDecisionsGate({ artifacts: runContext.artifacts })));
+        addResult(await runGate("gate-sds-policy-telemetry", "SDS Policy Telemetry", () => runSdsPolicyTelemetryGate({ artifacts: runContext.artifacts })));
+        addResult(await runGate("gate-sds-ops-observability-testing", "SDS Ops/Observability/Testing", () => runSdsOpsGate({ artifacts: runContext.artifacts })));
+        addResult(await runGate("gate-sds-external-adapters", "SDS External Adapters", () => runSdsAdaptersGate({ artifacts: runContext.artifacts })));
+        addResult(await runGate("gate-deployment-blueprint", "Deployment Blueprint", () => runDeploymentBlueprintGate({
+            artifacts: runContext.artifacts,
+            buildReady: runContext.flags.buildReady,
+        })));
+        addResult(await runGate("gate-build-ready-completeness", "Build Ready Completeness", () => runBuildReadyCompletenessGate({
+            artifacts: runContext.artifacts,
+            buildReady: runContext.flags.buildReady,
+        })));
+        return { gateResults, blockingIssues };
+    }
+    buildPatchPlanFromIssues(inputIssues) {
+        const patchesByPath = new Map();
+        const fixes = [];
+        const seenRanges = new Set();
+        for (const issue of inputIssues) {
+            if (issue.gateId !== "gate-placeholder-artifacts")
+                continue;
+            if (issue.location.kind !== "line_range")
+                continue;
+            const key = `${issue.location.path}:${issue.location.lineStart}-${issue.location.lineEnd}`;
+            if (seenRanges.has(key))
+                continue;
+            seenRanges.add(key);
+            const patch = patchesByPath.get(issue.location.path) ??
+                {
+                    path: issue.location.path,
+                    operations: [],
+                };
+            patch.operations.push({
+                type: "remove_block",
+                location: issue.location,
+            });
+            patchesByPath.set(issue.location.path, patch);
+            fixes.push({
+                issueId: issue.id,
+                summary: `Removed placeholder content in ${path.basename(issue.location.path)}`,
+                appliedAt: new Date().toISOString(),
+                metadata: {
+                    gateId: issue.gateId,
+                    path: issue.location.path,
+                    lineStart: issue.location.lineStart,
+                    lineEnd: issue.location.lineEnd,
+                },
+            });
+        }
+        return { patches: Array.from(patchesByPath.values()), fixes };
+    }
+    resolveQuestionDecision(question) {
+        const trimmed = question.trim().replace(/\?+$/, "").trim();
+        if (!trimmed)
+            return undefined;
+        const patterns = [
+            { pattern: /should we use\s+(.+)$/i, verb: "Use" },
+            { pattern: /^use\s+(.+)$/i, verb: "Use" },
+            { pattern: /^choose\s+(.+)$/i, verb: "Choose" },
+            { pattern: /^select\s+(.+)$/i, verb: "Select" },
+            { pattern: /decide on\s+(.+)$/i, verb: "Use" },
+        ];
+        for (const entry of patterns) {
+            const match = trimmed.match(entry.pattern);
+            if (!match)
+                continue;
+            const choice = match[1]?.trim() ?? "";
+            if (!choice)
+                continue;
+            if (/\bor\b|\/|either/i.test(choice))
+                continue;
+            const suffix = choice.endsWith(".") ? "" : ".";
+            return `${entry.verb} ${choice}${suffix}`;
+        }
+        return undefined;
+    }
+    sanitizeIndecisiveLine(line, patternId) {
+        const patterns = {
+            maybe: /\bmaybe\b/i,
+            optional: /\boptional\b/i,
+            could: /\bcould\b/i,
+            might: /\bmight\b/i,
+            possibly: /\bpossibly\b/i,
+            either: /\beither\b/i,
+            tbd: /\btbd\b/i,
+        };
+        const pattern = patterns[patternId];
+        if (!pattern)
+            return undefined;
+        const match = line.match(/^(\s*[-*+]\s+|\s*)(.*)$/);
+        const prefix = match?.[1] ?? "";
+        const body = match?.[2] ?? line;
+        const cleaned = body
+            .replace(pattern, "")
+            .replace(/\s{2,}/g, " ")
+            .replace(/\s+([,.;:])/g, "$1")
+            .trim();
+        if (!cleaned || cleaned === body.trim())
+            return undefined;
+        return `${prefix}${cleaned}`;
+    }
+    formatResolvedDecisions(decisions) {
+        const lines = [];
+        for (const decision of decisions) {
+            const metadata = (decision.metadata ?? {});
+            const question = typeof metadata.question === "string" && metadata.question.trim().length > 0
+                ? metadata.question.trim()
+                : undefined;
+            const suffix = question ? ` (question: ${question})` : "";
+            lines.push(`- ${decision.summary}${suffix}`);
+        }
+        return lines.join("\n");
+    }
+    async resolveOpenQuestions(runContext, gateResults) {
+        const enabled = runContext.flags.resolveOpenQuestions ||
+            process.env.MCODA_DOCS_RESOLVE_OPEN_QUESTIONS === "1";
+        if (!enabled)
+            return { decisions: [], warnings: [] };
+        const openQuestions = gateResults.find((gate) => gate.gateId === "gate-open-questions");
+        if (!openQuestions || openQuestions.issues.length === 0) {
+            return { decisions: [], warnings: [] };
+        }
+        const decisions = [];
+        const warnings = [];
+        const decisionTargets = new Map();
+        const lineReplacements = new Map();
+        const replacedLines = new Set();
+        for (const issue of openQuestions.issues) {
+            if (issue.location.kind !== "line_range")
+                continue;
+            const metadata = (issue.metadata ?? {});
+            const question = typeof metadata.question === "string" && metadata.question.trim().length > 0
+                ? metadata.question.trim()
+                : undefined;
+            const normalized = typeof metadata.normalized === "string" && metadata.normalized.trim().length > 0
+                ? metadata.normalized.trim()
+                : undefined;
+            const required = metadata.required === true;
+            if (!question)
+                continue;
+            const decisionSummary = this.resolveQuestionDecision(question);
+            if (!decisionSummary) {
+                if (required) {
+                    warnings.push(`Open question unresolved: ${question}`);
+                }
+                continue;
+            }
+            const fallbackId = question
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/g, "-")
+                .replace(/^-+|-+$/g, "");
+            const decisionIdBase = normalized ?? (fallbackId || issue.id);
+            const decisionId = `decision-${decisionIdBase}`;
+            const decision = {
+                id: decisionId,
+                summary: decisionSummary,
+                rationale: `Resolved from open question: "${question}"`,
+                decidedAt: new Date().toISOString(),
+                relatedIssueIds: [issue.id],
+                metadata: {
+                    question,
+                    normalized,
+                    target: metadata.target,
+                },
+            };
+            decisions.push(decision);
+            const target = typeof metadata.target === "string" && metadata.target.trim().length > 0
+                ? metadata.target.trim()
+                : issue.artifact;
+            let targetPath;
+            if (target === "pdr" || issue.artifact === "pdr") {
+                targetPath = runContext.artifacts.pdr?.path;
+            }
+            else if (target === "sds" || issue.artifact === "sds") {
+                targetPath = runContext.artifacts.sds?.path;
+            }
+            else {
+                targetPath = runContext.artifacts.sds?.path ?? runContext.artifacts.pdr?.path;
+            }
+            if (!targetPath) {
+                warnings.push(`Resolved decision could not be inserted (missing target doc): ${question}`);
+            }
+            else {
+                const existing = decisionTargets.get(targetPath);
+                if (existing) {
+                    existing.push(decision);
+                }
+                else {
+                    decisionTargets.set(targetPath, [decision]);
+                }
+            }
+            const lineIndex = issue.location.lineStart - 1;
+            const key = `${issue.location.path}:${lineIndex}`;
+            replacedLines.add(key);
+            if (!lineReplacements.has(issue.location.path)) {
+                lineReplacements.set(issue.location.path, new Map());
+            }
+            lineReplacements.get(issue.location.path)?.set(lineIndex, `Resolved: ${decision.summary}`);
+        }
+        const noMaybesGate = gateResults.find((gate) => gate.gateId === "gate-no-maybes");
+        if (noMaybesGate && noMaybesGate.issues.length > 0) {
+            const contentCache = new Map();
+            const loadContent = async (filePath) => {
+                if (contentCache.has(filePath))
+                    return contentCache.get(filePath);
+                try {
+                    const content = await fs.readFile(filePath, "utf8");
+                    contentCache.set(filePath, content);
+                    return content;
+                }
+                catch (error) {
+                    warnings.push(`Unable to read ${filePath} for indecisive cleanup: ${error.message ?? String(error)}`);
+                    return undefined;
+                }
+            };
+            for (const issue of noMaybesGate.issues) {
+                if (issue.location.kind !== "line_range")
+                    continue;
+                const lineIndex = issue.location.lineStart - 1;
+                const key = `${issue.location.path}:${lineIndex}`;
+                if (replacedLines.has(key))
+                    continue;
+                const content = await loadContent(issue.location.path);
+                if (!content)
+                    continue;
+                const lines = content.split(/\r?\n/);
+                if (lineIndex < 0 || lineIndex >= lines.length)
+                    continue;
+                const line = lines[lineIndex] ?? "";
+                const metadata = (issue.metadata ?? {});
+                const patternId = typeof metadata.patternId === "string" ? metadata.patternId : "";
+                const sanitized = this.sanitizeIndecisiveLine(line, patternId);
+                if (!sanitized)
+                    continue;
+                if (!lineReplacements.has(issue.location.path)) {
+                    lineReplacements.set(issue.location.path, new Map());
+                }
+                lineReplacements.get(issue.location.path)?.set(lineIndex, sanitized);
+            }
+        }
+        if (lineReplacements.size === 0 && decisionTargets.size === 0) {
+            return { decisions, warnings };
+        }
+        const patches = [];
+        for (const [filePath, replacements] of lineReplacements.entries()) {
+            const operations = [];
+            const sorted = Array.from(replacements.entries()).sort((a, b) => a[0] - b[0]);
+            for (const [lineIndex, content] of sorted) {
+                const lineNumber = lineIndex + 1;
+                operations.push({
+                    type: "replace_section",
+                    location: {
+                        kind: "line_range",
+                        path: filePath,
+                        lineStart: lineNumber,
+                        lineEnd: lineNumber,
+                    },
+                    content,
+                });
+            }
+            const decisionSet = decisionTargets.get(filePath);
+            if (decisionSet && decisionSet.length > 0) {
+                operations.push({
+                    type: "insert_section",
+                    heading: "Resolved Decisions",
+                    content: this.formatResolvedDecisions(decisionSet),
+                    position: "append",
+                    headingLevel: 2,
+                });
+            }
+            if (operations.length > 0) {
+                patches.push({ path: filePath, operations });
+            }
+        }
+        for (const [filePath, decisionSet] of decisionTargets.entries()) {
+            if (lineReplacements.has(filePath))
+                continue;
+            if (!decisionSet.length)
+                continue;
+            patches.push({
+                path: filePath,
+                operations: [
+                    {
+                        type: "insert_section",
+                        heading: "Resolved Decisions",
+                        content: this.formatResolvedDecisions(decisionSet),
+                        position: "append",
+                        headingLevel: 2,
+                    },
+                ],
+            });
+        }
+        if (patches.length > 0) {
+            const patchResult = await this.applyDocPatches(runContext, patches);
+            if (patchResult.warnings.length > 0) {
+                warnings.push(...patchResult.warnings);
+            }
+        }
+        return { decisions, warnings };
+    }
+    reviewReportDir(runContext) {
+        return path.join(this.workspace.mcodaDir, "jobs", runContext.jobId, "review");
+    }
+    reviewReportPaths(runContext, label) {
+        const reportDir = this.reviewReportDir(runContext);
+        const jobDir = path.join(this.workspace.mcodaDir, "jobs", runContext.jobId);
+        const jsonPath = path.join(reportDir, `${label}.json`);
+        const markdownPath = path.join(reportDir, `${label}.md`);
+        const markdownRelative = path.relative(jobDir, markdownPath) || path.basename(markdownPath);
+        return { jsonPath, markdownPath, markdownRelative };
+    }
+    buildReviewReport(input) {
+        const outcome = aggregateReviewOutcome({
+            gateResults: input.gateResults,
+            remainingOpenItems: input.remainingOpenItems,
+            fixesApplied: input.fixesApplied,
+            decisions: input.decisions ?? [],
+            generatedAt: new Date().toISOString(),
         });
-        return resolved.agent;
+        const iterationReports = input.iterationReports && input.iterationReports.length > 0
+            ? input.iterationReports
+            : undefined;
+        return {
+            version: 1,
+            generatedAt: outcome.generatedAt,
+            iteration: {
+                current: input.runContext.iteration.current,
+                max: input.runContext.iteration.max,
+                status: input.iterationStatus,
+            },
+            status: outcome.summary.status,
+            summary: outcome.summary,
+            gateResults: outcome.gateResults,
+            issues: outcome.issues,
+            remainingOpenItems: outcome.remainingOpenItems,
+            fixesApplied: outcome.fixesApplied,
+            decisions: outcome.decisions,
+            deltas: input.deltas ?? [],
+            metadata: {
+                commandName: input.runContext.commandName,
+                commandRunId: input.runContext.commandRunId,
+                jobId: input.runContext.jobId,
+                projectKey: input.runContext.projectKey,
+                iterationReports,
+            },
+        };
+    }
+    async persistReviewReport(runContext, label, report) {
+        const paths = this.reviewReportPaths(runContext, label);
+        await ensureDir(paths.jsonPath);
+        await fs.writeFile(paths.jsonPath, serializeReviewReport(report), "utf8");
+        await fs.writeFile(paths.markdownPath, renderReviewReport(report), "utf8");
+        return { markdownRelative: paths.markdownRelative };
+    }
+    async runIterationLoop(runContext) {
+        const iterationEnabled = this.isIterationEnabled(runContext);
+        const maxIterations = runContext.iteration.max > 0
+            ? runContext.iteration.max
+            : iterationEnabled
+                ? this.resolveMaxIterations()
+                : 1;
+        runContext.iteration.max = maxIterations;
+        const fixesApplied = [];
+        const alignmentDeltas = [];
+        const decisions = [];
+        const iterationReports = [];
+        let lastGateResults = [];
+        let lastBlockingIssues = [];
+        const alignmentPatcher = new DocAlignmentPatcher();
+        let finalReportRelative;
+        const persistIterationReport = async (status) => {
+            const report = this.buildReviewReport({
+                runContext,
+                gateResults: lastGateResults,
+                remainingOpenItems: lastBlockingIssues,
+                fixesApplied,
+                deltas: alignmentDeltas,
+                decisions,
+                iterationStatus: status,
+            });
+            const { markdownRelative } = await this.persistReviewReport(runContext, `review-iteration-${runContext.iteration.current}`, report);
+            iterationReports.push(markdownRelative);
+        };
+        const persistFinalReport = async (status) => {
+            const report = this.buildReviewReport({
+                runContext,
+                gateResults: lastGateResults,
+                remainingOpenItems: lastBlockingIssues,
+                fixesApplied,
+                deltas: alignmentDeltas,
+                decisions,
+                iterationStatus: status,
+                iterationReports,
+            });
+            const { markdownRelative } = await this.persistReviewReport(runContext, "review-final", report);
+            finalReportRelative = markdownRelative;
+        };
+        for (let iteration = 1; iteration <= maxIterations; iteration += 1) {
+            runContext.iteration.current = iteration;
+            await this.jobService.recordIterationProgress(runContext.jobId, {
+                current: iteration,
+                max: maxIterations,
+                phase: "review",
+            });
+            const review = await this.runReviewGates(runContext, "review");
+            lastGateResults = review.gateResults;
+            lastBlockingIssues = review.blockingIssues;
+            if (review.blockingIssues.length === 0) {
+                await persistIterationReport("completed");
+                await persistFinalReport("completed");
+                return { gateResults: review.gateResults, fixesApplied, reviewReportPath: finalReportRelative };
+            }
+            if (!iterationEnabled) {
+                await persistIterationReport("max_iterations");
+                await persistFinalReport("max_iterations");
+                const summary = this.summarizeIssues(review.blockingIssues);
+                throw new Error(`Doc generation review failed. ${summary}`);
+            }
+            const questionResolution = await this.resolveOpenQuestions(runContext, review.gateResults);
+            if (questionResolution.decisions.length > 0) {
+                decisions.push(...questionResolution.decisions);
+            }
+            if (questionResolution.warnings.length > 0) {
+                this.appendUniqueWarnings(runContext, questionResolution.warnings);
+            }
+            if (runContext.flags.crossAlign) {
+                const alignmentResult = await alignmentPatcher.apply({
+                    runContext,
+                    gateResults: review.gateResults,
+                });
+                if (alignmentResult.warnings.length > 0) {
+                    this.appendUniqueWarnings(runContext, alignmentResult.warnings);
+                }
+                if (alignmentResult.deltas.length > 0) {
+                    alignmentDeltas.push(...alignmentResult.deltas);
+                }
+            }
+            const patchPlan = this.buildPatchPlanFromIssues(review.blockingIssues);
+            await this.jobService.recordIterationProgress(runContext.jobId, {
+                current: iteration,
+                max: maxIterations,
+                phase: "patch",
+                details: { patches: patchPlan.patches.length, fixes: patchPlan.fixes.length },
+            });
+            if (patchPlan.patches.length > 0) {
+                fixesApplied.push(...patchPlan.fixes);
+                const patchResult = await this.applyDocPatches(runContext, patchPlan.patches);
+                if (patchResult.warnings.length > 0) {
+                    this.appendUniqueWarnings(runContext, patchResult.warnings);
+                }
+                await this.jobService.recordIterationProgress(runContext.jobId, {
+                    current: iteration,
+                    max: maxIterations,
+                    phase: "recheck",
+                });
+                const recheck = await this.runReviewGates(runContext, "recheck");
+                lastGateResults = recheck.gateResults;
+                lastBlockingIssues = recheck.blockingIssues;
+                if (recheck.blockingIssues.length === 0) {
+                    await persistIterationReport("completed");
+                    await persistFinalReport("completed");
+                    return { gateResults: recheck.gateResults, fixesApplied, reviewReportPath: finalReportRelative };
+                }
+            }
+            const iterationStatus = lastBlockingIssues.length === 0
+                ? "completed"
+                : iteration === maxIterations
+                    ? "max_iterations"
+                    : "in_progress";
+            await persistIterationReport(iterationStatus);
+        }
+        const summary = this.summarizeIssues(lastBlockingIssues);
+        await persistFinalReport("max_iterations");
+        throw new Error(`Doc generation review failed after ${maxIterations} iteration(s). ${summary}`);
+    }
+    async enforcePlaceholderArtifacts(runContext) {
+        if (!runContext.flags.noPlaceholders)
+            return;
+        const allowlist = parseDelimitedList(process.env.MCODA_DOCS_PLACEHOLDER_ALLOWLIST);
+        const denylist = parseDelimitedList(process.env.MCODA_DOCS_PLACEHOLDER_DENYLIST);
+        const result = await runPlaceholderArtifactGate({
+            artifacts: runContext.artifacts,
+            allowlist: allowlist.length > 0 ? allowlist : undefined,
+            denylist: denylist.length > 0 ? denylist : undefined,
+        });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status !== "fail")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => `${issue.artifact}: ${issue.message}`)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        throw new Error(`Placeholder artifacts detected (${result.issues.length}). ${summary}${suffix}`);
+    }
+    async enforceApiPathConsistency(runContext) {
+        const result = await runApiPathConsistencyGate({ artifacts: runContext.artifacts });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status !== "fail")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => `${issue.artifact}: ${issue.message}`)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        const message = `API path consistency check failed (${result.issues.length}). ${summary}${suffix}`;
+        if (runContext.flags.buildReady) {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
+    }
+    async enforceOpenApiSchemaSanity(runContext) {
+        if (!runContext.artifacts.openapi?.length)
+            return;
+        const issues = [];
+        for (const record of runContext.artifacts.openapi) {
+            try {
+                const content = await fs.readFile(record.path, "utf8");
+                const result = validateOpenApiSchemaContent(content);
+                if (result.errors.length > 0) {
+                    issues.push(...result.errors.map((error) => `${record.path}: ${error}`));
+                }
+            }
+            catch (error) {
+                runContext.warnings.push(`Unable to read OpenAPI spec ${record.path}: ${error.message ?? String(error)}`);
+            }
+        }
+        if (issues.length === 0)
+            return;
+        const summary = issues.slice(0, 3).join(" ");
+        const suffix = issues.length > 3 ? ` (+${issues.length - 3} more)` : "";
+        const message = `OpenAPI schema sanity issues (${issues.length}). ${summary}${suffix}`;
+        if (runContext.flags.buildReady) {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
+    }
+    async enforceOpenApiCoverage(runContext) {
+        const result = await runOpenApiCoverageGate({ artifacts: runContext.artifacts });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status !== "fail")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => `${issue.artifact}: ${issue.message}`)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        const message = `OpenAPI endpoint coverage check failed (${result.issues.length}). ${summary}${suffix}`;
+        if (runContext.flags.buildReady) {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
+    }
+    async enforceSqlSyntax(runContext) {
+        const result = await runSqlSyntaxGate({ artifacts: runContext.artifacts });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status !== "fail")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => `${issue.artifact}: ${issue.message}`)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        const message = `SQL syntax validation failed (${result.issues.length}). ${summary}${suffix}`;
+        if (runContext.flags.buildReady) {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
+    }
+    async enforceSqlRequiredTables(runContext) {
+        const result = await runSqlRequiredTablesGate({ artifacts: runContext.artifacts });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status !== "fail")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => `${issue.artifact}: ${issue.message}`)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        const message = `SQL required tables check failed (${result.issues.length}). ${summary}${suffix}`;
+        if (runContext.flags.buildReady) {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
+    }
+    async generateDeploymentBlueprint(runContext, sdsContent, projectKey) {
+        if (runContext.flags.dryRun) {
+            runContext.warnings.push("Dry run enabled; deployment blueprint generation skipped.");
+            return false;
+        }
+        const scaffolder = new DocsScaffolder();
+        const openapiRecords = runContext.artifacts.openapi ?? [];
+        const primaryOpenApi = openapiRecords.find((record) => record.variant !== "admin") ?? openapiRecords[0];
+        let openapiContent;
+        if (primaryOpenApi) {
+            try {
+                openapiContent = await fs.readFile(primaryOpenApi.path, "utf8");
+            }
+            catch (error) {
+                runContext.warnings.push(`Unable to read OpenAPI spec ${primaryOpenApi.path} for deployment blueprint: ${error.message ?? String(error)}`);
+            }
+        }
+        try {
+            await scaffolder.generateDeploymentBlueprintFiles({
+                sdsContent,
+                openapiContent,
+                outputDir: path.join(this.workspace.workspaceRoot, "deploy"),
+                serviceName: projectKey ?? "app",
+            });
+            return true;
+        }
+        catch (error) {
+            runContext.warnings.push(`Deployment blueprint generation failed: ${error.message ?? String(error)}`);
+            return false;
+        }
+    }
+    async enforceAdminOpenApiSpec(runContext) {
+        const docRecords = [runContext.artifacts.pdr, runContext.artifacts.sds].filter((record) => Boolean(record));
+        if (docRecords.length === 0)
+            return;
+        const mentions = [];
+        for (const record of docRecords) {
+            try {
+                const content = await fs.readFile(record.path, "utf8");
+                const found = findAdminSurfaceMentions(content);
+                for (const mention of found) {
+                    mentions.push({
+                        record,
+                        line: mention.line,
+                        excerpt: mention.heading ? `${mention.heading}: ${mention.excerpt}` : mention.excerpt,
+                    });
+                }
+            }
+            catch (error) {
+                runContext.warnings.push(`Unable to scan ${record.path} for admin surface mentions: ${error.message ?? String(error)}`);
+            }
+        }
+        if (mentions.length === 0)
+            return;
+        const openapiRecords = runContext.artifacts.openapi ?? [];
+        const hasAdminSpec = openapiRecords.some((record) => record.variant === "admin" || /admin/i.test(path.basename(record.path)));
+        if (hasAdminSpec)
+            return;
+        const summary = mentions
+            .slice(0, 2)
+            .map((entry) => `${path.basename(entry.record.path)}:${entry.line} ${entry.excerpt}`)
+            .join(" | ");
+        const suffix = mentions.length > 2 ? ` (+${mentions.length - 2} more)` : "";
+        const message = `Admin OpenAPI spec required (admin surfaces referenced): ${summary}${suffix}`;
+        if (runContext.flags.buildReady) {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
+    }
+    async enforceTerminologyNormalization(runContext) {
+        const result = await runTerminologyNormalizationGate({ artifacts: runContext.artifacts });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status === "pass")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => `${issue.artifact}: ${issue.message}`)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        const message = `Terminology normalization findings (${result.issues.length}). ${summary}${suffix}`;
+        if (result.status === "fail" && runContext.flags.buildReady) {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
+    }
+    async enforceOpenQuestions(runContext) {
+        const result = await runOpenQuestionsGate({ artifacts: runContext.artifacts });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status === "pass")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => `${issue.artifact}: ${issue.message}`)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        const message = `Open questions detected (${result.issues.length}). ${summary}${suffix}`;
+        if (result.status === "fail" && runContext.flags.buildReady) {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
+    }
+    async enforceNoMaybes(runContext) {
+        const enabled = runContext.flags.noMaybes ||
+            runContext.flags.resolveOpenQuestions ||
+            process.env.MCODA_DOCS_NO_MAYBES === "1" ||
+            process.env.MCODA_DOCS_RESOLVE_OPEN_QUESTIONS === "1";
+        const result = await runNoMaybesGate({ artifacts: runContext.artifacts, enabled });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status !== "fail")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => `${issue.artifact}: ${issue.message}`)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        throw new Error(`Indecisive language detected (${result.issues.length}). ${summary}${suffix}`);
+    }
+    async enforceRfpConsent(runContext) {
+        const result = await runRfpConsentGate({ rfpPath: runContext.rfpPath });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status === "pass" || result.status === "skipped")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => `${issue.message}`)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        const message = `RFP consent contradictions detected (${result.issues.length}). ${summary}${suffix}`;
+        if (runContext.flags.buildReady) {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
+    }
+    async enforceRfpDefinitionCoverage(runContext) {
+        const allowlist = parseDelimitedList(process.env.MCODA_DOCS_RFP_DEFINITION_ALLOWLIST);
+        const result = await runRfpDefinitionGate({
+            rfpPath: runContext.rfpPath,
+            allowlist: allowlist.length > 0 ? allowlist : undefined,
+        });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status === "pass" || result.status === "skipped")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => issue.message)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        const message = `RFP definition coverage issues (${result.issues.length}). ${summary}${suffix}`;
+        if (runContext.flags.buildReady) {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
+    }
+    async enforcePdrInterfaces(runContext) {
+        const result = await runPdrInterfacesGate({ artifacts: runContext.artifacts });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status === "pass" || result.status === "skipped")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => issue.message)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        const message = `PDR interface/pipeline issues (${result.issues.length}). ${summary}${suffix}`;
+        if (runContext.flags.buildReady) {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
+    }
+    async enforcePdrOwnership(runContext) {
+        const result = await runPdrOwnershipGate({ artifacts: runContext.artifacts });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status === "pass" || result.status === "skipped")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => issue.message)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        const message = `PDR ownership/consent flow issues (${result.issues.length}). ${summary}${suffix}`;
+        if (runContext.flags.buildReady) {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
+    }
+    async enforcePdrOpenQuestionsQuality(runContext) {
+        const enabled = process.env.MCODA_DOCS_RESOLVE_OPEN_QUESTIONS === "1";
+        const result = await runPdrOpenQuestionsGate({ artifacts: runContext.artifacts, enabled });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status === "pass" || result.status === "skipped")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => issue.message)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        const message = `PDR open question quality issues (${result.issues.length}). ${summary}${suffix}`;
+        throw new Error(message);
+    }
+    async enforceSdsExplicitDecisions(runContext) {
+        const result = await runSdsDecisionsGate({ artifacts: runContext.artifacts });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status === "pass" || result.status === "skipped")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => issue.message)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        const message = `SDS explicit decision issues (${result.issues.length}). ${summary}${suffix}`;
+        if (runContext.flags.buildReady) {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
+    }
+    async enforceSdsPolicyTelemetry(runContext) {
+        const result = await runSdsPolicyTelemetryGate({ artifacts: runContext.artifacts });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status === "pass" || result.status === "skipped")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => issue.message)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        const message = `SDS policy/telemetry/metering issues (${result.issues.length}). ${summary}${suffix}`;
+        if (runContext.flags.buildReady) {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
+    }
+    async enforceSdsOpsObservabilityTesting(runContext) {
+        const result = await runSdsOpsGate({ artifacts: runContext.artifacts });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status === "pass" || result.status === "skipped")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => issue.message)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        const message = `SDS ops/observability/testing issues (${result.issues.length}). ${summary}${suffix}`;
+        if (runContext.flags.buildReady) {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
+    }
+    async enforceSdsExternalAdapters(runContext) {
+        const result = await runSdsAdaptersGate({ artifacts: runContext.artifacts });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status === "pass" || result.status === "skipped")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => issue.message)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        const message = `SDS external adapter issues (${result.issues.length}). ${summary}${suffix}`;
+        if (runContext.flags.buildReady) {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
+    }
+    async enforceDeploymentBlueprint(runContext) {
+        const result = await runDeploymentBlueprintGate({
+            artifacts: runContext.artifacts,
+            buildReady: runContext.flags.buildReady,
+        });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status === "pass" || result.status === "skipped")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => `${issue.message}`)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        const message = `Deployment blueprint validation issues (${result.issues.length}). ${summary}${suffix}`;
+        if (result.status === "fail") {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
+    }
+    async enforceBuildReadyCompleteness(runContext) {
+        const result = await runBuildReadyCompletenessGate({
+            artifacts: runContext.artifacts,
+            buildReady: runContext.flags.buildReady,
+        });
+        if (result.notes?.length) {
+            runContext.warnings.push(...result.notes);
+        }
+        if (result.status === "pass" || result.status === "skipped")
+            return;
+        const summary = result.issues
+            .slice(0, 3)
+            .map((issue) => `${issue.artifact}: ${issue.message}`)
+            .join(" ");
+        const suffix = result.issues.length > 3 ? ` (+${result.issues.length - 3} more)` : "";
+        const message = `Build-ready completeness check failed (${result.issues.length}). ${summary}${suffix}`;
+        if (result.status === "fail") {
+            throw new Error(message);
+        }
+        runContext.warnings.push(message);
     }
     async writePdrFile(outPath, content) {
         await ensureDir(outPath);
@@ -1067,16 +2632,18 @@ export class DocsService {
         await ensureDir(outPath);
         await fs.writeFile(outPath, content, "utf8");
     }
-    async assertSdsDocdexProfile() {
+    async checkSdsDocdexProfile(warnings) {
         const base = this.workspace.config?.docdexUrl ?? process.env.MCODA_DOCDEX_URL;
         if (base)
             return;
-        const localStore = path.join(this.workspace.workspaceRoot, ".mcoda", "docdex", "documents.json");
+        const localStore = path.join(this.workspace.mcodaDir, "docdex", "documents.json");
         try {
             await fs.access(localStore);
+            return;
         }
         catch {
-            throw new Error("Docdex is not configured for SDS retrieval (missing docdexUrl and no local store). Configure docdexUrl or index docs with an sds_default profile.");
+            // No docdex URL or local store; continue with local docs if present.
+            warnings.push("Docdex is not configured for SDS retrieval; attempting local docs (no local docdex store found).");
         }
     }
     async registerSds(outPath, content, projectKey) {
@@ -1163,24 +2730,95 @@ export class DocsService {
                 workspaceId: this.workspace.workspaceId,
                 commandName: "docs-pdr-generate",
                 jobId: job.id,
+                commandRunId: commandRun.id,
                 action: "docdex_context",
                 promptTokens: 0,
                 completionTokens: 0,
                 metadata: { docdexAvailable: context.docdexAvailable },
             });
-            const agent = await this.resolveAgent(options.agentName);
+            const stream = options.agentStream ?? true;
+            const iterate = options.iterate === true;
+            const fastMode = iterate ? false : options.fast === true || process.env.MCODA_DOCS_FAST === "1";
+            const skipValidation = process.env.MCODA_SKIP_PDR_VALIDATION === "1";
+            const buildReady = options.buildReady === true || process.env.MCODA_DOCS_BUILD_READY === "1";
+            const resolveOpenQuestions = options.resolveOpenQuestions === true ||
+                process.env.MCODA_DOCS_RESOLVE_OPEN_QUESTIONS === "1";
+            const noMaybes = options.noMaybes === true ||
+                process.env.MCODA_DOCS_NO_MAYBES === "1" ||
+                resolveOpenQuestions;
+            const noPlaceholders = options.noPlaceholders === true ||
+                process.env.MCODA_DOCS_NO_PLACEHOLDERS === "1" ||
+                buildReady;
+            const crossAlign = options.crossAlign !== false;
+            const iterationEnabled = !options.dryRun && !fastMode;
+            const maxIterations = iterationEnabled ? this.resolveMaxIterations() : 1;
+            const agent = await this.selectDocgenAgent({
+                agentName: options.agentName,
+                commandName: "docs-pdr-generate",
+                commandAliases: ["docs-pdr-generate", "docs:pdr:generate", "pdr"],
+                jobId: job.id,
+                warnings: context.warnings,
+                iterationEnabled,
+            });
+            const outputPath = options.outPath ?? this.defaultPdrOutputPath(options.projectKey, context.rfp.path);
+            const runContext = this.createRunContext({
+                commandName: "docs-pdr-generate",
+                commandRunId: commandRun.id,
+                jobId: job.id,
+                projectKey: options.projectKey,
+                rfpId: options.rfpId,
+                rfpPath: context.rfp.path ?? options.rfpPath,
+                outputPath,
+                flags: {
+                    dryRun: options.dryRun === true,
+                    fast: fastMode,
+                    iterate,
+                    json: options.json === true,
+                    stream,
+                    buildReady,
+                    noPlaceholders,
+                    resolveOpenQuestions,
+                    noMaybes,
+                    crossAlign,
+                },
+                warnings: context.warnings,
+            });
+            runContext.iteration.max = maxIterations;
+            const stateCleanupWarnings = await cleanupWorkspaceStateDirs({
+                workspaceRoot: this.workspace.workspaceRoot,
+                mcodaDir: this.workspace.mcodaDir,
+            });
+            const { statePath: iterativeOutputPath, warnings: statePathWarnings } = resolveDocgenStatePath({
+                outputPath: runContext.outputPath,
+                mcodaDir: this.workspace.mcodaDir,
+                jobId: runContext.jobId,
+                commandName: runContext.commandName,
+            });
+            const stateWarnings = [...stateCleanupWarnings, ...statePathWarnings];
+            if (stateWarnings.length > 0) {
+                runContext.stateWarnings = stateWarnings;
+                this.appendUniqueWarnings(runContext, stateWarnings);
+            }
+            runContext.artifacts.pdr = { kind: "pdr", path: runContext.outputPath, meta: {} };
+            await this.enforceToolDenylist({ runContext, agent });
+            await this.recordDocgenStage(runContext, {
+                stage: "generation",
+                message: "Generating PDR draft",
+                totalItems: maxIterations,
+                processedItems: 0,
+            });
             const prompts = await this.agentService.getPrompts(agent.id);
             const runbook = (await readPromptIfExists(this.workspace, path.join("prompts", "commands", "pdr-generate.md"))) ||
                 DEFAULT_PDR_RUNBOOK_PROMPT;
             let draft = "";
+            let agentUsed = false;
             let agentMetadata;
             let adapter = agent.adapter;
-            const stream = options.agentStream ?? true;
-            const skipValidation = process.env.MCODA_SKIP_PDR_VALIDATION === "1";
             let lastInvoke;
             for (let attempt = 0; attempt < 2; attempt += 1) {
                 const prompt = buildRunPrompt(context, options.projectKey, prompts, attempt === 0 ? runbook : `${runbook}\n\nRETRY: The previous attempt failed validation. Ensure all required sections are present and non-empty. Do not leave placeholders.`);
                 const invoke = async (input) => {
+                    agentUsed = true;
                     const { output: out, adapter: usedAdapter, metadata } = await this.invokeAgent(agent, input, stream, job.id, options.onToken);
                     adapter = usedAdapter;
                     agentMetadata = metadata;
@@ -1195,12 +2833,18 @@ export class DocsService {
                     workspaceId: this.workspace.workspaceId,
                     commandName: "docs-pdr-generate",
                     jobId: job.id,
+                    commandRunId: commandRun.id,
                     agentId: agent.id,
                     modelName: agent.defaultModel,
                     action: attempt === 0 ? "draft_pdr" : "draft_pdr_retry",
                     promptTokens: estimateTokens(prompt),
                     completionTokens: estimateTokens(agentOutput),
-                    metadata: { adapter, docdexAvailable: context.docdexAvailable, attempt },
+                    metadata: {
+                        adapter,
+                        docdexAvailable: context.docdexAvailable,
+                        attempt: attempt + 1,
+                        phase: attempt === 0 ? "draft_pdr" : "draft_pdr_retry",
+                    },
                 });
                 if (valid) {
                     draft = structured;
@@ -1218,11 +2862,14 @@ export class DocsService {
             if (!draft) {
                 throw new Error("PDR draft generation failed; no valid draft produced.");
             }
-            if (lastInvoke) {
+            if (fastMode) {
+                context.warnings.push("Fast mode enabled; skipping PDR enrichment and tidy passes.");
+            }
+            else if (lastInvoke) {
                 draft = await enrichPdrDraft(draft, agent, context, options.projectKey, lastInvoke);
                 draft = ensureStructuredDraft(draft, options.projectKey, context, context.rfp.path ?? context.rfp.id ?? "RFP");
             }
-            if (lastInvoke) {
+            if (!fastMode && lastInvoke) {
                 try {
                     const tidiedRaw = await tidyPdrDraft(draft, agent, lastInvoke);
                     const tidied = ensureStructuredDraft(tidiedRaw, options.projectKey, context, context.rfp.path ?? context.rfp.id ?? "RFP");
@@ -1236,17 +2883,21 @@ export class DocsService {
                     context.warnings.push(`Tidy pass skipped: ${error.message ?? "unknown error"}`);
                 }
             }
-            const outputPath = options.outPath ?? this.defaultPdrOutputPath(options.projectKey, context.rfp.path);
             if (!options.dryRun) {
-                const firstDraftPath = path.join(this.workspace.mcodaDir, "docs", "pdr", `${path.basename(outputPath, path.extname(outputPath))}-first-draft.md`);
+                const firstDraftPath = path.join(this.workspace.mcodaDir, "docs", "pdr", `${path.basename(runContext.outputPath, path.extname(runContext.outputPath))}-first-draft.md`);
                 await ensureDir(firstDraftPath);
                 await fs.writeFile(firstDraftPath, draft, "utf8");
-                try {
-                    const iterativeDraft = await buildIterativePdr(options.projectKey, context, draft, outputPath, lastInvoke ?? (async (input) => this.invokeAgent(agent, input, stream, job.id, options.onToken)));
-                    draft = iterativeDraft;
+                if (fastMode) {
+                    context.warnings.push("Fast mode enabled; skipping iterative PDR refinement.");
                 }
-                catch (error) {
-                    context.warnings.push(`Iterative PDR refinement failed; keeping first draft. ${String(error)}`);
+                else {
+                    try {
+                        const iterativeDraft = await buildIterativePdr(options.projectKey, context, draft, iterativeOutputPath, lastInvoke ?? (async (input) => this.invokeAgent(agent, input, stream, job.id, options.onToken)));
+                        draft = iterativeDraft;
+                    }
+                    catch (error) {
+                        context.warnings.push(`Iterative PDR refinement failed; keeping first draft. ${String(error)}`);
+                    }
                 }
             }
             await this.jobService.writeCheckpoint(job.id, {
@@ -1257,23 +2908,29 @@ export class DocsService {
             let docdexId;
             let segments;
             let mirrorStatus = "skipped";
+            let reviewReportPath;
             if (options.dryRun) {
                 context.warnings.push("Dry run enabled; PDR was not written to disk or registered in docdex.");
             }
             if (!options.dryRun) {
-                await this.writePdrFile(outputPath, draft);
+                await this.writePdrFile(runContext.outputPath, draft);
                 if (context.docdexAvailable) {
-                    const registered = await this.registerPdr(outputPath, draft, options.projectKey);
-                    docdexId = registered.id;
-                    segments = (registered.segments ?? []).map((s) => s.id);
-                    await fs.writeFile(`${outputPath}.meta.json`, JSON.stringify({ docdexId, segments, projectKey: options.projectKey }, null, 2), "utf8");
+                    try {
+                        const registered = await this.registerPdr(runContext.outputPath, draft, options.projectKey);
+                        docdexId = registered.id;
+                        segments = (registered.segments ?? []).map((s) => s.id);
+                        await fs.writeFile(`${runContext.outputPath}.meta.json`, JSON.stringify({ docdexId, segments, projectKey: options.projectKey }, null, 2), "utf8");
+                    }
+                    catch (error) {
+                        context.warnings.push(`Docdex registration skipped: ${error.message}`);
+                    }
                 }
                 const publicDocsDir = path.join(this.workspace.workspaceRoot, "docs", "pdr");
                 const shouldMirror = this.workspace.config?.mirrorDocs !== false;
                 if (shouldMirror) {
                     try {
                         await ensureDir(path.join(publicDocsDir, "placeholder"));
-                        const mirrorPath = path.join(publicDocsDir, path.basename(outputPath));
+                        const mirrorPath = path.join(publicDocsDir, path.basename(runContext.outputPath));
                         await ensureDir(mirrorPath);
                         await fs.writeFile(mirrorPath, draft, "utf8");
                         mirrorStatus = "mirrored";
@@ -1283,18 +2940,54 @@ export class DocsService {
                         mirrorStatus = "failed";
                     }
                 }
+                try {
+                    await this.recordDocgenStage(runContext, {
+                        stage: "inventory",
+                        message: "Building doc inventory",
+                    });
+                    runContext.artifacts = await buildDocInventory({
+                        workspace: this.workspace,
+                        preferred: { pdrPath: runContext.outputPath },
+                    });
+                }
+                catch (error) {
+                    runContext.warnings.push(`Doc inventory build failed: ${error.message ?? String(error)}`);
+                }
+                const iterationResult = await this.runIterationLoop(runContext);
+                reviewReportPath = iterationResult.reviewReportPath;
             }
             await this.jobService.updateJobStatus(job.id, "completed", {
-                payload: { outputPath, docdexId, segments, mirrorStatus },
+                payload: {
+                    outputPath: runContext.outputPath,
+                    docdexId,
+                    segments,
+                    mirrorStatus,
+                    ...(reviewReportPath ? { reviewReportPath } : {}),
+                },
             });
             await this.jobService.finishCommandRun(commandRun.id, "succeeded");
+            if (options.rateAgents && agentUsed) {
+                try {
+                    const ratingService = await this.ensureRatingService();
+                    await ratingService.rate({
+                        workspace: this.workspace,
+                        agentId: agent.id,
+                        commandName: "docs-pdr-generate",
+                        jobId: job.id,
+                        commandRunId: commandRun.id,
+                    });
+                }
+                catch (error) {
+                    context.warnings.push(`Agent rating failed: ${error.message ?? String(error)}`);
+                }
+            }
             return {
                 jobId: job.id,
                 commandRunId: commandRun.id,
-                outputPath,
+                outputPath: runContext.outputPath,
                 draft,
                 docdexId,
-                warnings: context.warnings,
+                warnings: runContext.warnings,
             };
         }
         catch (error) {
@@ -1363,9 +3056,9 @@ export class DocsService {
         }
     }
     async generateSds(options) {
-        await this.assertSdsDocdexProfile();
-        const assembler = new DocContextAssembler(this.docdex, this.workspace);
         const warnings = [];
+        await this.checkSdsDocdexProfile(warnings);
+        const assembler = new DocContextAssembler(this.docdex, this.workspace);
         const commandRun = await this.jobService.startCommandRun("docs-sds-generate", options.projectKey);
         let job;
         let resumeDraft;
@@ -1423,6 +3116,7 @@ export class DocsService {
                 workspaceId: this.workspace.workspaceId,
                 commandName: "docs-sds-generate",
                 jobId: job.id,
+                commandRunId: commandRun.id,
                 action: "docdex_context",
                 promptTokens: 0,
                 completionTokens: 0,
@@ -1444,7 +3138,76 @@ export class DocsService {
                     }
                 }
             }
-            const agent = await this.resolveAgent(options.agentName, ["docs-sds-generate", "docs:sds:generate", "sds"]);
+            const stream = options.agentStream ?? true;
+            const iterate = options.iterate === true;
+            const fastMode = iterate ? false : options.fast === true || process.env.MCODA_DOCS_FAST === "1";
+            const skipValidation = process.env.MCODA_SKIP_SDS_VALIDATION === "1";
+            const buildReady = options.buildReady === true || process.env.MCODA_DOCS_BUILD_READY === "1";
+            const resolveOpenQuestions = options.resolveOpenQuestions === true ||
+                process.env.MCODA_DOCS_RESOLVE_OPEN_QUESTIONS === "1";
+            const noMaybes = options.noMaybes === true ||
+                process.env.MCODA_DOCS_NO_MAYBES === "1" ||
+                resolveOpenQuestions;
+            const noPlaceholders = options.noPlaceholders === true ||
+                process.env.MCODA_DOCS_NO_PLACEHOLDERS === "1" ||
+                buildReady;
+            const crossAlign = options.crossAlign !== false;
+            const iterationEnabled = !options.dryRun && !fastMode;
+            const maxIterations = iterationEnabled ? this.resolveMaxIterations() : 1;
+            const agent = await this.selectDocgenAgent({
+                agentName: options.agentName,
+                commandName: "docs-sds-generate",
+                commandAliases: ["docs-sds-generate", "docs:sds:generate", "sds"],
+                jobId: job.id,
+                warnings,
+                iterationEnabled,
+            });
+            const runContext = this.createRunContext({
+                commandName: "docs-sds-generate",
+                commandRunId: commandRun.id,
+                jobId: job.id,
+                projectKey: options.projectKey,
+                rfpPath: context.rfp?.path,
+                templateName: options.templateName,
+                outputPath,
+                flags: {
+                    dryRun: options.dryRun === true,
+                    fast: fastMode,
+                    iterate,
+                    json: options.json === true,
+                    stream,
+                    buildReady,
+                    noPlaceholders,
+                    resolveOpenQuestions,
+                    noMaybes,
+                    crossAlign,
+                },
+                warnings,
+            });
+            runContext.iteration.max = maxIterations;
+            const stateCleanupWarnings = await cleanupWorkspaceStateDirs({
+                workspaceRoot: this.workspace.workspaceRoot,
+                mcodaDir: this.workspace.mcodaDir,
+            });
+            const { statePath: iterativeOutputPath, warnings: statePathWarnings } = resolveDocgenStatePath({
+                outputPath: runContext.outputPath,
+                mcodaDir: this.workspace.mcodaDir,
+                jobId: runContext.jobId,
+                commandName: runContext.commandName,
+            });
+            const stateWarnings = [...stateCleanupWarnings, ...statePathWarnings];
+            if (stateWarnings.length > 0) {
+                runContext.stateWarnings = stateWarnings;
+                this.appendUniqueWarnings(runContext, stateWarnings);
+            }
+            runContext.artifacts.sds = { kind: "sds", path: runContext.outputPath, meta: {} };
+            await this.enforceToolDenylist({ runContext, agent });
+            await this.recordDocgenStage(runContext, {
+                stage: "generation",
+                message: "Generating SDS draft",
+                totalItems: maxIterations,
+                processedItems: 0,
+            });
             const prompts = await this.agentService.getPrompts(agent.id);
             const template = await this.loadSdsTemplate(options.templateName);
             const sdsSections = getSdsSections(template.content);
@@ -1452,11 +3215,11 @@ export class DocsService {
                 (await readPromptIfExists(this.workspace, path.join("prompts", "sds", "generate.md"))) ||
                 DEFAULT_SDS_RUNBOOK_PROMPT;
             let draft = resumeDraft ?? "";
+            let agentUsed = false;
             let agentMetadata;
             let adapter = agent.adapter;
-            const stream = options.agentStream ?? true;
-            const skipValidation = process.env.MCODA_SKIP_SDS_VALIDATION === "1";
             const invoke = async (input) => {
+                agentUsed = true;
                 const { output: out, adapter: usedAdapter, metadata } = await this.invokeAgent(agent, input, stream, job.id, options.onToken);
                 adapter = usedAdapter;
                 if (metadata)
@@ -1476,6 +3239,7 @@ export class DocsService {
                         workspaceId: this.workspace.workspaceId,
                         commandName: "docs-sds-generate",
                         jobId: job.id,
+                        commandRunId: commandRun.id,
                         agentId: agent.id,
                         modelName: agent.defaultModel,
                         action: attempt === 0 ? "draft_sds" : "draft_sds_retry",
@@ -1486,7 +3250,8 @@ export class DocsService {
                             provider: adapter,
                             docdexAvailable: context.docdexAvailable,
                             template: template.name,
-                            attempt,
+                            attempt: attempt + 1,
+                            phase: attempt === 0 ? "draft_sds" : "draft_sds_retry",
                         },
                     });
                     if (valid)
@@ -1508,6 +3273,7 @@ export class DocsService {
                         workspaceId: this.workspace.workspaceId,
                         commandName: "docs-sds-generate",
                         jobId: job.id,
+                        commandRunId: commandRun.id,
                         action: "draft_sds_resume",
                         promptTokens: 0,
                         completionTokens: estimateTokens(draft),
@@ -1531,42 +3297,60 @@ export class DocsService {
                     workspaceId: this.workspace.workspaceId,
                     commandName: "docs-sds-generate",
                     jobId: job.id,
+                    commandRunId: commandRun.id,
                     agentId: agent.id,
                     modelName: agent.defaultModel,
                     action: "draft_sds_resume_regenerate",
                     promptTokens: estimateTokens(prompt),
                     completionTokens: estimateTokens(agentOutput),
-                    metadata: { adapter, provider: adapter, docdexAvailable: context.docdexAvailable, template: template.name },
+                    metadata: {
+                        adapter,
+                        provider: adapter,
+                        docdexAvailable: context.docdexAvailable,
+                        template: template.name,
+                        phase: "draft_sds_resume_regenerate",
+                        attempt: 1,
+                    },
                 });
             }
-            // Enrich each section sequentially after a valid base draft exists.
-            draft = await enrichSdsDraft(draft, sdsSections, agent, context, options.projectKey, invoke);
-            draft = ensureSdsStructuredDraft(draft, options.projectKey, context, template.content);
-            if (!skipValidation && !(validateSdsDraft(draft) && headingHasContent(draft, "Architecture"))) {
-                warnings.push("Enriched SDS draft failed validation; using structured fallback.");
-                draft = ensureSdsStructuredDraft(draft, options.projectKey, context, template.content);
+            if (fastMode) {
+                warnings.push("Fast mode enabled; skipping SDS enrichment and tidy passes.");
             }
-            try {
-                const tidiedRaw = await tidySdsDraft(draft, sdsSections, agent, invoke);
-                const tidied = ensureSdsStructuredDraft(tidiedRaw, options.projectKey, context, template.content);
-                if (skipValidation || (validateSdsDraft(tidied) && headingHasContent(tidied, "Architecture"))) {
-                    draft = tidied;
+            else {
+                // Enrich each section sequentially after a valid base draft exists.
+                draft = await enrichSdsDraft(draft, sdsSections, agent, context, options.projectKey, invoke);
+                draft = ensureSdsStructuredDraft(draft, options.projectKey, context, template.content);
+                if (!skipValidation && !(validateSdsDraft(draft) && headingHasContent(draft, "Architecture"))) {
+                    warnings.push("Enriched SDS draft failed validation; using structured fallback.");
+                    draft = ensureSdsStructuredDraft(draft, options.projectKey, context, template.content);
+                }
+                try {
+                    const tidiedRaw = await tidySdsDraft(draft, sdsSections, agent, invoke);
+                    const tidied = ensureSdsStructuredDraft(tidiedRaw, options.projectKey, context, template.content);
+                    if (skipValidation || (validateSdsDraft(tidied) && headingHasContent(tidied, "Architecture"))) {
+                        draft = tidied;
+                    }
+                }
+                catch (error) {
+                    warnings.push(`SDS tidy pass skipped: ${error.message ?? "unknown error"}`);
                 }
-            }
-            catch (error) {
-                warnings.push(`SDS tidy pass skipped: ${error.message ?? "unknown error"}`);
             }
             await fs.mkdir(path.dirname(draftPath), { recursive: true });
             await fs.writeFile(draftPath, draft, "utf8");
-            const firstDraftPath = path.join(this.workspace.mcodaDir, "docs", "sds", `${path.basename(outputPath, path.extname(outputPath))}-first-draft.md`);
+            const firstDraftPath = path.join(this.workspace.mcodaDir, "docs", "sds", `${path.basename(runContext.outputPath, path.extname(runContext.outputPath))}-first-draft.md`);
             await ensureDir(firstDraftPath);
             await fs.writeFile(firstDraftPath, draft, "utf8");
-            try {
-                const iterativeDraft = await buildIterativeSds(options.projectKey, context, draft, sdsSections, outputPath, invoke);
-                draft = iterativeDraft;
+            if (fastMode) {
+                warnings.push("Fast mode enabled; skipping iterative SDS refinement.");
             }
-            catch (error) {
-                warnings.push(`Iterative SDS refinement failed; keeping first draft. ${String(error)}`);
+            else {
+                try {
+                    const iterativeDraft = await buildIterativeSds(options.projectKey, context, draft, sdsSections, iterativeOutputPath, invoke);
+                    draft = iterativeDraft;
+                }
+                catch (error) {
+                    warnings.push(`Iterative SDS refinement failed; keeping first draft. ${String(error)}`);
+                }
             }
             await this.jobService.writeCheckpoint(job.id, {
                 stage: "draft_completed",
@@ -1576,23 +3360,29 @@ export class DocsService {
             let docdexId;
             let segments;
             let mirrorStatus = "skipped";
+            let reviewReportPath;
             if (options.dryRun) {
                 warnings.push("Dry run enabled; SDS was not written to disk or registered in docdex.");
             }
             if (!options.dryRun) {
-                await this.writeSdsFile(outputPath, draft);
+                await this.writeSdsFile(runContext.outputPath, draft);
                 if (context.docdexAvailable) {
-                    const registered = await this.registerSds(outputPath, draft, options.projectKey);
-                    docdexId = registered.id;
-                    segments = (registered.segments ?? []).map((s) => s.id);
-                    await fs.writeFile(`${outputPath}.meta.json`, JSON.stringify({ docdexId, segments, projectKey: options.projectKey }, null, 2), "utf8");
+                    try {
+                        const registered = await this.registerSds(runContext.outputPath, draft, options.projectKey);
+                        docdexId = registered.id;
+                        segments = (registered.segments ?? []).map((s) => s.id);
+                        await fs.writeFile(`${runContext.outputPath}.meta.json`, JSON.stringify({ docdexId, segments, projectKey: options.projectKey }, null, 2), "utf8");
+                    }
+                    catch (error) {
+                        warnings.push(`Docdex registration skipped: ${error.message}`);
+                    }
                 }
                 const publicDocsDir = path.join(this.workspace.workspaceRoot, "docs", "sds");
                 const shouldMirror = this.workspace.config?.mirrorDocs !== false;
                 if (shouldMirror) {
                     try {
                         await ensureDir(path.join(publicDocsDir, "placeholder"));
-                        const mirrorPath = path.join(publicDocsDir, path.basename(outputPath));
+                        const mirrorPath = path.join(publicDocsDir, path.basename(runContext.outputPath));
                         await ensureDir(mirrorPath);
                         await fs.writeFile(mirrorPath, draft, "utf8");
                         mirrorStatus = "mirrored";
@@ -1601,25 +3391,76 @@ export class DocsService {
                         mirrorStatus = "failed";
                     }
                 }
+                try {
+                    await this.recordDocgenStage(runContext, {
+                        stage: "inventory",
+                        message: "Building doc inventory",
+                    });
+                    runContext.artifacts = await buildDocInventory({
+                        workspace: this.workspace,
+                        preferred: { sdsPath: runContext.outputPath },
+                    });
+                }
+                catch (error) {
+                    runContext.warnings.push(`Doc inventory build failed: ${error.message ?? String(error)}`);
+                }
+                await this.recordDocgenStage(runContext, {
+                    stage: "blueprint",
+                    message: "Generating deployment blueprint",
+                });
+                const blueprintGenerated = await this.generateDeploymentBlueprint(runContext, draft, options.projectKey);
+                if (blueprintGenerated) {
+                    try {
+                        await this.recordDocgenStage(runContext, {
+                            stage: "inventory",
+                            message: "Rebuilding doc inventory",
+                        });
+                        runContext.artifacts = await buildDocInventory({
+                            workspace: this.workspace,
+                            preferred: { sdsPath: runContext.outputPath },
+                        });
+                    }
+                    catch (error) {
+                        runContext.warnings.push(`Doc inventory rebuild after blueprint failed: ${error.message ?? String(error)}`);
+                    }
+                }
+                const iterationResult = await this.runIterationLoop(runContext);
+                reviewReportPath = iterationResult.reviewReportPath;
             }
             await this.jobService.updateJobStatus(job.id, "completed", {
                 payload: {
-                    outputPath,
+                    outputPath: runContext.outputPath,
                     docdexId,
                     segments,
                     template: template.name,
                     mirrorStatus,
                     agentMetadata,
+                    ...(reviewReportPath ? { reviewReportPath } : {}),
                 },
             });
             await this.jobService.finishCommandRun(commandRun.id, "succeeded");
+            if (options.rateAgents && agentUsed) {
+                try {
+                    const ratingService = await this.ensureRatingService();
+                    await ratingService.rate({
+                        workspace: this.workspace,
+                        agentId: agent.id,
+                        commandName: "docs-sds-generate",
+                        jobId: job.id,
+                        commandRunId: commandRun.id,
+                    });
+                }
+                catch (error) {
+                    warnings.push(`Agent rating failed: ${error.message ?? String(error)}`);
+                }
+            }
             return {
                 jobId: job.id,
                 commandRunId: commandRun.id,
-                outputPath,
+                outputPath: runContext.outputPath,
                 draft,
                 docdexId,
-                warnings,
+                warnings: runContext.warnings,
             };
         }
         catch (error) {