@mcoda/core 0.1.8 → 0.1.9

package/dist/services/backlog/TaskOrderingService.js

@@ -522,23 +522,26 @@ export class TaskOrderingService {
                 warnings.push("Dependency cycle detected; ordering may be partial.");
             }
             let agentRank;
-            const docContext = await this.buildDocContext(project.key, warnings);
-            if (docContext && commandRun && this.recordTelemetry) {
-                const contextTokens = estimateTokens(docContext.content);
-                await this.jobService.recordTokenUsage({
-                    workspaceId: this.workspace.workspaceId,
-                    projectId: project.id,
-                    commandRunId: commandRun.id,
-                    jobId: job?.id,
-                    timestamp: new Date().toISOString(),
-                    commandName: "order-tasks",
-                    action: "docdex_context",
-                    tokensPrompt: contextTokens,
-                    tokensTotal: contextTokens,
-                    metadata: { source: docContext.source },
-                });
+            const enableAgent = Boolean(request.agentName);
+            let docContext;
+            if (enableAgent) {
+                docContext = await this.buildDocContext(project.key, warnings);
+                if (docContext && commandRun && this.recordTelemetry) {
+                    const contextTokens = estimateTokens(docContext.content);
+                    await this.jobService.recordTokenUsage({
+                        workspaceId: this.workspace.workspaceId,
+                        projectId: project.id,
+                        commandRunId: commandRun.id,
+                        jobId: job?.id,
+                        timestamp: new Date().toISOString(),
+                        commandName: "order-tasks",
+                        action: "docdex_context",
+                        tokensPrompt: contextTokens,
+                        tokensTotal: contextTokens,
+                        metadata: { source: docContext.source },
+                    });
+                }
             }
-            const enableAgent = request.agentName !== undefined || this.recordTelemetry;
             if (enableAgent) {
                 try {
                     const agent = await this.resolveAgent(request.agentName);

package/dist/services/docs/DocsService.d.ts

@@ -1,9 +1,10 @@
 import { AgentService } from "@mcoda/agents";
-import { GlobalRepository } from "@mcoda/db";
+import { GlobalRepository, WorkspaceRepository } from "@mcoda/db";
 import { DocdexClient } from "@mcoda/integrations";
 import { JobService } from "../jobs/JobService.js";
 import { WorkspaceResolution } from "../../workspace/WorkspaceManager.js";
 import { RoutingService } from "../agents/RoutingService.js";
+import { AgentRatingService } from "../agents/AgentRatingService.js";
 export interface GeneratePdrOptions {
     workspace: WorkspaceResolution;
     projectKey?: string;
@@ -12,6 +13,8 @@ export interface GeneratePdrOptions {
     outPath?: string;
     agentName?: string;
     agentStream?: boolean;
+    rateAgents?: boolean;
+    fast?: boolean;
     dryRun?: boolean;
     json?: boolean;
     onToken?: (token: string) => void;
@@ -32,6 +35,8 @@ export interface GenerateSdsOptions {
     agentName?: string;
     templateName?: string;
     agentStream?: boolean;
+    rateAgents?: boolean;
+    fast?: boolean;
     dryRun?: boolean;
     json?: boolean;
     force?: boolean;
@@ -53,12 +58,16 @@ export declare class DocsService {
     private agentService;
     private repo;
     private routingService;
+    private ratingService?;
+    private workspaceRepo?;
     constructor(workspace: WorkspaceResolution, deps: {
         docdex?: DocdexClient;
         jobService?: JobService;
         agentService: AgentService;
         repo: GlobalRepository;
         routingService: RoutingService;
+        workspaceRepo?: WorkspaceRepository;
+        ratingService?: AgentRatingService;
         noTelemetry?: boolean;
     });
     static create(workspace: WorkspaceResolution, options?: {
@@ -69,6 +78,7 @@ export declare class DocsService {
     private defaultSdsOutputPath;
     private loadSdsTemplate;
     private resolveAgent;
+    private ensureRatingService;
     private writePdrFile;
     private registerPdr;
     private writeSdsFile;

package/dist/services/docs/DocsService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocsService.d.ts","sourceRoot":"","sources":["../../../src/services/docs/DocsService.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DocsService.d.ts","sourceRoot":"","sources":["../../../src/services/docs/DocsService.ts"],"names":[],"mappings":"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"}

package/dist/services/docs/DocsService.js

@@ -1,12 +1,13 @@
 import path from "node:path";
 import { promises as fs } from "node:fs";
 import { AgentService } from "@mcoda/agents";
-import { GlobalRepository } from "@mcoda/db";
+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 { JobService } from "../jobs/JobService.js";
 import { RoutingService } from "../agents/RoutingService.js";
+import { AgentRatingService } from "../agents/AgentRatingService.js";
 const ensureDir = async (targetPath) => {
     await fs.mkdir(path.dirname(targetPath), { recursive: true });
 };
@@ -22,6 +23,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 +90,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;
@@ -330,10 +369,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 +434,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 +472,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 +497,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 (auth/identity, restaurant suggestions, voting cycles, results/analytics).";
+            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 +524,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 +534,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 +661,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 +933,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 +974,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 +1005,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`);
     }
@@ -983,6 +1078,8 @@ export class DocsService {
         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();
@@ -996,15 +1093,19 @@ export class DocsService {
         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"));
@@ -1045,6 +1146,23 @@ export class DocsService {
         });
         return resolved.agent;
     }
+    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;
+    }
     async writePdrFile(outPath, content) {
         await ensureDir(outPath);
         await fs.writeFile(outPath, content, "utf8");
@@ -1163,6 +1281,7 @@ export class DocsService {
                 workspaceId: this.workspace.workspaceId,
                 commandName: "docs-pdr-generate",
                 jobId: job.id,
+                commandRunId: commandRun.id,
                 action: "docdex_context",
                 promptTokens: 0,
                 completionTokens: 0,
@@ -1173,14 +1292,17 @@ export class DocsService {
             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 fastMode = options.fast === true || process.env.MCODA_DOCS_FAST === "1";
             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,6 +1317,7 @@ 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",
@@ -1218,11 +1341,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");
@@ -1241,12 +1367,17 @@ export class DocsService {
                 const firstDraftPath = path.join(this.workspace.mcodaDir, "docs", "pdr", `${path.basename(outputPath, path.extname(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, outputPath, 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, {
@@ -1263,10 +1394,15 @@ export class DocsService {
             if (!options.dryRun) {
                 await this.writePdrFile(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(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");
+                    }
+                    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;
@@ -1288,6 +1424,21 @@ export class DocsService {
                 payload: { outputPath, docdexId, segments, mirrorStatus },
             });
             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,
@@ -1423,6 +1574,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,
@@ -1452,11 +1604,14 @@ 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 fastMode = options.fast === true || process.env.MCODA_DOCS_FAST === "1";
             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 +1631,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",
@@ -1508,6 +1664,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,6 +1688,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: "draft_sds_resume_regenerate",
@@ -1539,34 +1697,44 @@ export class DocsService {
                     metadata: { adapter, provider: adapter, docdexAvailable: context.docdexAvailable, template: template.name },
                 });
             }
-            // 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`);
             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, outputPath, 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",
@@ -1582,10 +1750,15 @@ export class DocsService {
             if (!options.dryRun) {
                 await this.writeSdsFile(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(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");
+                    }
+                    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;
@@ -1613,6 +1786,21 @@ export class DocsService {
                 },
             });
             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,