@mcoda/core 0.1.26 → 0.1.28

package/dist/services/planning/CreateTasksService.js

@@ -13,6 +13,7 @@ import { TaskOrderingService } from "../backlog/TaskOrderingService.js";
 import { QaTestCommandBuilder } from "../execution/QaTestCommandBuilder.js";
 import { createEpicKeyGenerator, createStoryKeyGenerator, createTaskKeyGenerator, } from "./KeyHelpers.js";
 import { TaskSufficiencyService } from "./TaskSufficiencyService.js";
+import { SdsPreflightService } from "./SdsPreflightService.js";
 const formatBullets = (items, fallback) => {
     if (!items || items.length === 0)
         return `- ${fallback}`;
@@ -257,6 +258,14 @@ const extractMarkdownHeadings = (value, limit) => {
             !line.startsWith("*")) {
             headings.push(line);
         }
+        else {
+            const numberedHeading = line.match(/^(\d+(?:\.\d+)+)\s+(.+)$/);
+            if (numberedHeading) {
+                const headingText = `${numberedHeading[1]} ${numberedHeading[2]}`.trim();
+                if (/[a-z]/i.test(headingText))
+                    headings.push(headingText);
+            }
+        }
         if (headings.length >= limit)
             break;
     }
@@ -398,58 +407,133 @@ const extractJsonObjects = (value) => {
     }
     return results;
 };
+const normalizeAgentFailoverEvents = (value) => {
+    if (!Array.isArray(value))
+        return [];
+    const events = [];
+    for (const entry of value) {
+        if (!isPlainObject(entry))
+            continue;
+        if (typeof entry.type !== "string" || entry.type.trim().length === 0)
+            continue;
+        events.push({ ...entry });
+    }
+    return events;
+};
+const mergeAgentFailoverEvents = (left, right) => {
+    if (!left.length)
+        return right;
+    if (!right.length)
+        return left;
+    const seen = new Set();
+    const merged = [];
+    const signature = (event) => [
+        event.type ?? "",
+        event.fromAgentId ?? "",
+        event.toAgentId ?? "",
+        event.at ?? "",
+        event.until ?? "",
+        event.durationMs ?? "",
+    ].join("|");
+    for (const event of [...left, ...right]) {
+        const key = signature(event);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push(event);
+    }
+    return merged;
+};
+const mergeAgentInvocationMetadata = (current, incoming) => {
+    if (!current && !incoming)
+        return undefined;
+    if (!incoming)
+        return current;
+    if (!current)
+        return { ...incoming };
+    const merged = { ...current, ...incoming };
+    const currentEvents = normalizeAgentFailoverEvents(current.failoverEvents);
+    const incomingEvents = normalizeAgentFailoverEvents(incoming.failoverEvents);
+    if (currentEvents.length > 0 || incomingEvents.length > 0) {
+        merged.failoverEvents = mergeAgentFailoverEvents(currentEvents, incomingEvents);
+    }
+    return merged;
+};
+const summarizeAgentFailoverEvent = (event) => {
+    const type = String(event.type ?? "unknown");
+    if (type === "switch_agent") {
+        const from = typeof event.fromAgentId === "string" ? event.fromAgentId : "unknown";
+        const to = typeof event.toAgentId === "string" ? event.toAgentId : "unknown";
+        return `switch_agent ${from} -> ${to}`;
+    }
+    if (type === "sleep_until_reset") {
+        const duration = typeof event.durationMs === "number" && Number.isFinite(event.durationMs)
+            ? `${Math.round(event.durationMs / 1000)}s`
+            : "unknown duration";
+        const until = typeof event.until === "string" ? event.until : "unknown";
+        return `sleep_until_reset ${duration} (until ${until})`;
+    }
+    if (type === "stream_restart_after_limit") {
+        const from = typeof event.fromAgentId === "string" ? event.fromAgentId : "unknown";
+        return `stream_restart_after_limit from ${from}`;
+    }
+    return type;
+};
+const resolveTerminalFailoverAgentId = (events, fallbackAgentId) => {
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event?.type !== "switch_agent")
+            continue;
+        if (typeof event.toAgentId === "string" && event.toAgentId.trim().length > 0) {
+            return event.toAgentId;
+        }
+    }
+    return fallbackAgentId;
+};
+const compactNarrative = (value, fallback, maxLines = 5) => {
+    if (!value || value.trim().length === 0)
+        return fallback;
+    const lines = value
+        .split(/\r?\n/)
+        .map((line) => line
+        .replace(/^[*-]\s+/, "")
+        .replace(/^#+\s+/, "")
+        .replace(/^\*+\s*\*\*(.+?)\*\*\s*$/, "$1")
+        .trim())
+        .filter(Boolean)
+        .filter((line) => !/^(in scope|out of scope|key flows?|non-functional requirements|dependencies|risks|acceptance criteria|related docs?)\s*:/i.test(line))
+        .slice(0, maxLines);
+    return lines.length > 0 ? lines.join("\n") : fallback;
+};
 const buildEpicDescription = (epicKey, title, description, acceptance, relatedDocs) => {
+    const context = compactNarrative(description, `Deliver ${title} with implementation-ready scope and sequencing aligned to SDS guidance.`, 6);
     return [
         `* **Epic Key**: ${epicKey}`,
         `* **Epic Title**: ${title}`,
         "* **Context / Problem**",
         "",
-        ensureNonEmpty(description, "Summarize the problem, users, and constraints for this epic."),
-        "* **Goals & Outcomes**",
-        formatBullets(acceptance, "List measurable outcomes for this epic."),
-        "* **In Scope**",
-        "- Clarify during refinement; derived from RFP/PDR/SDS.",
-        "* **Out of Scope**",
-        "- To be defined; exclude unrelated systems.",
-        "* **Key Flows / Scenarios**",
-        "- Outline primary user flows for this epic.",
-        "* **Non-functional Requirements**",
-        "- Performance, security, reliability expectations go here.",
-        "* **Dependencies & Constraints**",
-        "- Capture upstream/downstream systems and blockers.",
-        "* **Risks & Open Questions**",
-        "- Identify risks and unknowns to resolve.",
+        context,
         "* **Acceptance Criteria**",
-        formatBullets(acceptance, "Provide 5–10 testable acceptance criteria."),
+        formatBullets(acceptance, "Define measurable and testable outcomes for this epic."),
         "* **Related Documentation / References**",
-        formatBullets(relatedDocs, "Link relevant docdex entries and sections."),
+        formatBullets(relatedDocs, "Link SDS/PDR/OpenAPI references used by this epic."),
     ].join("\n");
 };
 const buildStoryDescription = (storyKey, title, userStory, description, acceptanceCriteria, relatedDocs) => {
+    const userStoryText = compactNarrative(userStory, `As a user, I want ${title} so that it delivers clear product value.`, 3);
+    const contextText = compactNarrative(description, `Implement ${title} with concrete scope and dependency context.`, 5);
     return [
         `* **Story Key**: ${storyKey}`,
         "* **User Story**",
         "",
-        ensureNonEmpty(userStory, `As a user, I want ${title} so that it delivers value.`),
+        userStoryText,
         "* **Context**",
         "",
-        ensureNonEmpty(description, "Context for systems, dependencies, and scope."),
-        "* **Preconditions / Assumptions**",
-        "- Confirm required data, environments, and access.",
-        "* **Main Flow**",
-        "- Outline the happy path for this story.",
-        "* **Alternative / Error Flows**",
-        "- Capture error handling and non-happy paths.",
-        "* **UX / UI Notes**",
-        "- Enumerate screens/states if applicable.",
-        "* **Data & Integrations**",
-        "- Note key entities, APIs, queues, or third-party dependencies.",
+        contextText,
         "* **Acceptance Criteria**",
         formatBullets(acceptanceCriteria, "List testable outcomes for this story."),
-        "* **Non-functional Requirements**",
-        "- Add story-specific performance/reliability/security expectations.",
         "* **Related Documentation / References**",
-        formatBullets(relatedDocs, "Docdex handles, OpenAPI endpoints, code modules."),
+        formatBullets(relatedDocs, "Docdex handles, OpenAPI endpoints, and code modules."),
     ].join("\n");
 };
 const buildTaskDescription = (taskKey, title, description, storyKey, epicKey, relatedDocs, dependencies, tests, qa) => {
@@ -463,7 +547,7 @@ const buildTaskDescription = (taskKey, title, description, storyKey, epicKey, re
         })
             .join("\n");
     };
-    const objectiveText = ensureNonEmpty(description, `Deliver ${title} for story ${storyKey}.`);
+    const objectiveText = compactNarrative(description, `Deliver ${title} for story ${storyKey}.`, 3);
     const implementationLines = extractActionableLines(description, 4);
     const riskLines = extractRiskLines(description, 3);
     const testsDefined = (tests.unitTests?.length ?? 0) +
@@ -482,14 +566,14 @@ const buildTaskDescription = (taskKey, title, description, storyKey, epicKey, re
         qa?.blockers?.length ? "- Remaining QA blockers are explicit and actionable." : "- QA blockers are resolved or not present.",
     ];
     const defaultImplementationPlan = [
-        `- Implement ${title} with file/module-level changes aligned to the objective.`,
+        `Implement ${title} with concrete file/module-level changes aligned to the objective.`,
         dependencies.length
-            ? `- Respect dependency order before completion: ${dependencies.join(", ")}.`
-            : "- Validate assumptions and finalize concrete implementation steps before coding.",
+            ? `Respect dependency order before completion: ${dependencies.join(", ")}.`
+            : "Finalize concrete implementation steps before coding and keep scope bounded.",
     ];
     const defaultRisks = dependencies.length
-        ? [`- Delivery depends on upstream tasks: ${dependencies.join(", ")}.`]
-        : ["- Keep implementation aligned to SDS/OpenAPI contracts to avoid drift."];
+        ? [`Delivery depends on upstream tasks: ${dependencies.join(", ")}.`]
+        : ["Keep implementation aligned to SDS/OpenAPI contracts to avoid drift."];
     return [
         `* **Task Key**: ${taskKey}`,
         "* **Objective**",
@@ -500,7 +584,7 @@ const buildTaskDescription = (taskKey, title, description, storyKey, epicKey, re
         `- Epic: ${epicKey}`,
         `- Story: ${storyKey}`,
         "* **Inputs**",
-        formatBullets(relatedDocs, "Docdex excerpts, SDS/PDR/RFP sections, OpenAPI endpoints."),
+        formatBullets(relatedDocs, "No explicit external references."),
         "* **Implementation Plan**",
         formatBullets(implementationLines, defaultImplementationPlan.join(" ")),
         "* **Definition of Done**",
@@ -519,11 +603,11 @@ const buildTaskDescription = (taskKey, title, description, storyKey, epicKey, re
         "* **QA Blockers**",
         formatBullets(qa?.blockers, "None known."),
         "* **Dependencies**",
-        formatBullets(dependencies, "Enumerate prerequisite tasks by key."),
+        formatBullets(dependencies, "None."),
         "* **Risks & Gotchas**",
         formatBullets(riskLines, defaultRisks.join(" ")),
         "* **Related Documentation / References**",
-        formatBullets(relatedDocs, "Docdex handles or file paths to consult."),
+        formatBullets(relatedDocs, "None."),
     ].join("\n");
 };
 const collectFilesRecursively = async (target) => {
@@ -729,6 +813,7 @@ export class CreateTasksService {
         this.ratingService = deps.ratingService;
         this.taskOrderingFactory = deps.taskOrderingFactory ?? TaskOrderingService.create;
         this.taskSufficiencyFactory = deps.taskSufficiencyFactory ?? TaskSufficiencyService.create;
+        this.sdsPreflightFactory = deps.sdsPreflightFactory ?? SdsPreflightService.create;
     }
     static async create(workspace) {
         const repo = await GlobalRepository.create();
@@ -750,6 +835,7 @@ export class CreateTasksService {
             workspaceRepo,
             routingService,
             taskSufficiencyFactory: TaskSufficiencyService.create,
+            sdsPreflightFactory: SdsPreflightService.create,
         });
     }
     async close() {
@@ -838,6 +924,20 @@ export class CreateTasksService {
         const resolved = path.isAbsolute(input) ? input : path.join(this.workspace.workspaceRoot, input);
         return path.resolve(resolved).toLowerCase();
     }
+    mergeDocInputs(primary, extras) {
+        const merged = [];
+        const seen = new Set();
+        for (const input of [...primary, ...extras]) {
+            if (!input?.trim())
+                continue;
+            const key = this.normalizeDocInputForSet(input);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            merged.push(input);
+        }
+        return merged;
+    }
     docIdentity(doc) {
         const pathKey = `${doc.path ?? ""}`.trim().toLowerCase();
         const idKey = `${doc.id ?? ""}`.trim().toLowerCase();
@@ -1489,6 +1589,21 @@ export class CreateTasksService {
             "5) Keep task dependencies story-scoped while preserving epic/story/task ordering by this build method.",
         ].join("\n");
     }
+    buildProjectPlanArtifact(projectKey, docs, graph, buildMethod) {
+        const sourceDocs = docs
+            .map((doc) => doc.path ?? (doc.id ? `docdex:${doc.id}` : doc.title ?? "doc"))
+            .filter((value) => Boolean(value))
+            .slice(0, 24);
+        return {
+            projectKey,
+            generatedAt: new Date().toISOString(),
+            sourceDocs,
+            startupWaves: graph.startupWaves.slice(0, 12),
+            services: graph.services.slice(0, 40),
+            foundationalDependencies: graph.foundationalDependencies.slice(0, 16),
+            buildMethod,
+        };
+    }
     orderStoryTasksByDependencies(storyTasks, serviceRank, taskServiceByScope) {
         const byLocalId = new Map(storyTasks.map((task) => [task.localId, task]));
         const indegree = new Map();
@@ -2093,8 +2208,11 @@ export class CreateTasksService {
             const segmentHeadings = (doc.segments ?? [])
                 .map((segment) => segment.heading?.trim())
                 .filter((heading) => Boolean(heading));
+            const segmentContentHeadings = (doc.segments ?? [])
+                .flatMap((segment) => extractMarkdownHeadings(segment.content ?? "", Math.max(6, Math.ceil(limit / 4))))
+                .slice(0, limit);
             const contentHeadings = extractMarkdownHeadings(doc.content ?? "", limit);
-            for (const heading of [...segmentHeadings, ...contentHeadings]) {
+            for (const heading of [...segmentHeadings, ...segmentContentHeadings, ...contentHeadings]) {
                 const normalized = heading.replace(/[`*_]/g, "").trim();
                 if (!normalized)
                     continue;
@@ -2187,17 +2305,18 @@ export class CreateTasksService {
             .filter(Boolean)
             .join(" ");
         const prompt = [
-            `You are assisting in creating EPICS ONLY for project ${projectKey}.`,
-            "Follow mcoda SDS epic template:",
-            "- Context/Problem; Goals & Outcomes; In Scope; Out of Scope; Key Flows; Non-functional Requirements; Dependencies & Constraints; Risks & Open Questions; Acceptance Criteria; Related Documentation.",
+            `You are assisting in phase 1 of 3 for project ${projectKey}: generate epics only.`,
+            "Process is strict and direct: build plan -> epics -> stories -> tasks.",
+            "This step outputs only epics derived from the build plan and docs.",
             "Return strictly valid JSON (no prose) matching:",
             EPIC_SCHEMA_SNIPPET,
             "Rules:",
             "- Do NOT include final slugs; the system will assign keys.",
             "- Use docdex handles when referencing docs.",
             "- acceptanceCriteria must be an array of strings (5-10 items).",
-            "- Prefer dependency-first sequencing: foundational codebase/service setup epics should precede dependent feature epics.",
-            "- Keep output technology-agnostic and derived from docs; do not assume specific stacks unless docs state them.",
+            "- Keep epics actionable and implementation-oriented; avoid glossary/admin-only epics.",
+            "- Prefer dependency-first sequencing: foundational setup epics before dependent feature epics.",
+            "- Keep output derived from docs; do not assume stacks unless docs state them.",
             "Project construction method to follow:",
             projectBuildMethod,
             limits || "Use reasonable scope without over-generating epics.",
@@ -2337,6 +2456,7 @@ export class CreateTasksService {
     async invokeAgentWithRetry(agent, prompt, action, stream, jobId, commandRunId, metadata) {
         const startedAt = Date.now();
         let output = "";
+        let invocationMetadata;
         const logChunk = async (chunk) => {
             if (!chunk)
                 return;
@@ -2344,17 +2464,51 @@ export class CreateTasksService {
             if (stream)
                 process.stdout.write(chunk);
         };
+        const baseInvocationMetadata = {
+            command: "create-tasks",
+            action,
+            phase: `create_tasks_${action}`,
+        };
+        const logFailoverEvents = async (events) => {
+            if (!events.length)
+                return;
+            for (const event of events) {
+                await this.jobService.appendLog(jobId, `[create-tasks] agent failover (${action}): ${summarizeAgentFailoverEvent(event)}\n`);
+            }
+        };
+        const resolveUsageAgent = async (events) => {
+            const agentId = resolveTerminalFailoverAgentId(events, agent.id);
+            if (agentId === agent.id) {
+                return { id: agent.id, defaultModel: agent.defaultModel };
+            }
+            try {
+                const resolved = await this.agentService.resolveAgent(agentId);
+                return { id: resolved.id, defaultModel: resolved.defaultModel };
+            }
+            catch (error) {
+                await this.jobService.appendLog(jobId, `[create-tasks] unable to resolve failover agent (${agentId}) for usage accounting: ${error instanceof Error ? error.message : String(error)}\n`);
+                return { id: agent.id, defaultModel: agent.defaultModel };
+            }
+        };
         try {
             if (stream) {
-                const gen = await this.agentService.invokeStream(agent.id, { input: prompt });
+                const gen = await this.agentService.invokeStream(agent.id, {
+                    input: prompt,
+                    metadata: baseInvocationMetadata,
+                });
                 for await (const chunk of gen) {
                     output += chunk.output ?? "";
+                    invocationMetadata = mergeAgentInvocationMetadata(invocationMetadata, chunk.metadata);
                     await logChunk(chunk.output);
                 }
             }
             else {
-                const result = await this.agentService.invoke(agent.id, { input: prompt });
+                const result = await this.agentService.invoke(agent.id, {
+                    input: prompt,
+                    metadata: baseInvocationMetadata,
+                });
                 output = result.output ?? "";
+                invocationMetadata = mergeAgentInvocationMetadata(invocationMetadata, result.metadata);
                 await logChunk(output);
             }
         }
@@ -2371,10 +2525,22 @@ export class CreateTasksService {
                 `Original content:\n${output}`,
             ].join("\n\n");
             try {
-                const fix = await this.agentService.invoke(agent.id, { input: fixPrompt });
+                let retryInvocationMetadata;
+                const fix = await this.agentService.invoke(agent.id, {
+                    input: fixPrompt,
+                    metadata: {
+                        ...baseInvocationMetadata,
+                        attempt: 2,
+                        stage: "json_repair",
+                    },
+                });
                 output = fix.output ?? "";
+                retryInvocationMetadata = mergeAgentInvocationMetadata(retryInvocationMetadata, fix.metadata);
                 parsed = extractJson(output);
                 if (parsed) {
+                    const failoverEvents = normalizeAgentFailoverEvents(retryInvocationMetadata?.failoverEvents);
+                    await logFailoverEvents(failoverEvents);
+                    const usageAgent = await resolveUsageAgent(failoverEvents);
                     const promptTokens = estimateTokens(prompt);
                     const completionTokens = estimateTokens(output);
                     const durationSeconds = (Date.now() - startedAt) / 1000;
@@ -2383,8 +2549,8 @@ export class CreateTasksService {
                         workspaceId: this.workspace.workspaceId,
                         jobId,
                         commandRunId,
-                        agentId: agent.id,
-                        modelName: agent.defaultModel,
+                        agentId: usageAgent.id,
+                        modelName: usageAgent.defaultModel,
                         promptTokens,
                         completionTokens,
                         tokensPrompt: promptTokens,
@@ -2395,6 +2561,7 @@ export class CreateTasksService {
                             action: `create_tasks_${action}`,
                             phase: `create_tasks_${action}`,
                             attempt,
+                            failoverEvents: failoverEvents.length > 0 ? failoverEvents : undefined,
                             ...(metadata ?? {}),
                         },
                     });
@@ -2408,6 +2575,9 @@ export class CreateTasksService {
         if (!parsed) {
             throw new Error(`Agent output was not valid JSON for ${action}`);
         }
+        const failoverEvents = normalizeAgentFailoverEvents(invocationMetadata?.failoverEvents);
+        await logFailoverEvents(failoverEvents);
+        const usageAgent = await resolveUsageAgent(failoverEvents);
         const promptTokens = estimateTokens(prompt);
         const completionTokens = estimateTokens(output);
         const durationSeconds = (Date.now() - startedAt) / 1000;
@@ -2416,8 +2586,8 @@ export class CreateTasksService {
             workspaceId: this.workspace.workspaceId,
             jobId,
             commandRunId,
-            agentId: agent.id,
-            modelName: agent.defaultModel,
+            agentId: usageAgent.id,
+            modelName: usageAgent.defaultModel,
             promptTokens,
             completionTokens,
             tokensPrompt: promptTokens,
@@ -2428,6 +2598,7 @@ export class CreateTasksService {
                 action: `create_tasks_${action}`,
                 phase: `create_tasks_${action}`,
                 attempt: 1,
+                failoverEvents: failoverEvents.length > 0 ? failoverEvents : undefined,
                 ...(metadata ?? {}),
             },
         });
@@ -2453,14 +2624,15 @@ export class CreateTasksService {
     }
     async generateStoriesForEpic(agent, epic, docSummary, projectBuildMethod, stream, jobId, commandRunId) {
         const prompt = [
-            `Generate user stories for epic "${epic.title}".`,
-            "Use the User Story template: User Story; Context; Preconditions; Main Flow; Alternative/Error Flows; UX/UI; Data & Integrations; Acceptance Criteria; NFR; Related Docs.",
+            `Generate user stories for epic "${epic.title}" (phase 2 of 3).`,
+            "This phase is stories-only. Do not generate tasks yet.",
             "Return JSON only matching:",
             STORY_SCHEMA_SNIPPET,
             "Rules:",
             "- No tasks in this step.",
             "- acceptanceCriteria must be an array of strings.",
             "- Use docdex handles when citing docs.",
+            "- Keep stories direct and implementation-oriented; avoid placeholder-only narrative sections.",
             "- Keep story sequencing aligned with the project construction method.",
             `Epic context (key=${epic.key ?? epic.localId ?? "TBD"}):`,
             epic.description ?? "(no description provided)",
@@ -2498,8 +2670,8 @@ export class CreateTasksService {
                 .filter(Boolean);
         };
         const prompt = [
-            `Generate tasks for story "${story.title}" (Epic: ${epic.title}).`,
-            "Use the Task template: Objective; Context; Inputs; Implementation Plan; DoD; Testing & QA; Dependencies; Risks; References.",
+            `Generate tasks for story "${story.title}" (Epic: ${epic.title}, phase 3 of 3).`,
+            "This phase is tasks-only for the given story.",
             "Return JSON only matching:",
             TASK_SCHEMA_SNIPPET,
             "Rules:",
@@ -2517,6 +2689,7 @@ export class CreateTasksService {
             "- Keep dependencies strictly inside this story; never reference tasks from other stories/epics.",
             "- Order tasks from foundational prerequisites to dependents based on documented dependency direction and startup constraints.",
             "- Avoid placeholder wording (TBD, TODO, to be defined, generic follow-up phrases).",
+            "- Avoid documentation-only or glossary-only tasks unless story acceptance explicitly requires them.",
             "- Use docdex handles when citing docs.",
             "- If OPENAPI_HINTS are present in Docs, align tasks with hinted service/capability/stage/test_requirements.",
             "- If SDS_COVERAGE_HINTS are present in Docs, cover the relevant SDS sections in implementation tasks.",
@@ -2766,14 +2939,15 @@ export class CreateTasksService {
                 : ["Coverage is heading-based heuristic match between SDS sections and generated epic/story/task corpus."],
         };
     }
-    async writePlanArtifacts(projectKey, plan, docSummary, docs) {
+    async writePlanArtifacts(projectKey, plan, docSummary, docs, buildPlan) {
         const baseDir = path.join(this.workspace.mcodaDir, "tasks", projectKey);
         await fs.mkdir(baseDir, { recursive: true });
         const write = async (file, data) => {
             const target = path.join(baseDir, file);
             await fs.writeFile(target, JSON.stringify(data, null, 2), "utf8");
         };
-        await write("plan.json", { projectKey, generatedAt: new Date().toISOString(), docSummary, ...plan });
+        await write("plan.json", { projectKey, generatedAt: new Date().toISOString(), docSummary, buildPlan, ...plan });
+        await write("build-plan.json", buildPlan);
         await write("epics.json", plan.epics);
         await write("stories.json", plan.stories);
         await write("tasks.json", plan.tasks);
@@ -3021,6 +3195,7 @@ export class CreateTasksService {
                 inputs: options.inputs,
                 agent: options.agentName,
                 agentStream,
+                sdsPreflightCommit: options.sdsPreflightCommit === true,
             },
         });
         let lastError;
@@ -3031,10 +3206,113 @@ export class CreateTasksService {
                     name: options.projectKey,
                     description: `Workspace project ${options.projectKey}`,
                 });
-                const docs = await this.prepareDocs(options.inputs);
-                const { docSummary, warnings: docWarnings } = this.buildDocContext(docs);
+                let sdsPreflight;
+                let sdsPreflightError;
+                if (this.sdsPreflightFactory) {
+                    let sdsPreflightCloseError;
+                    try {
+                        const preflightService = await this.sdsPreflightFactory(this.workspace);
+                        try {
+                            sdsPreflight = await preflightService.runPreflight({
+                                workspace: options.workspace,
+                                projectKey: options.projectKey,
+                                inputPaths: options.inputs,
+                                sdsPaths: options.inputs,
+                                writeArtifacts: true,
+                                applyToSds: true,
+                                commitAppliedChanges: options.sdsPreflightCommit === true,
+                                commitMessage: options.sdsPreflightCommitMessage,
+                            });
+                        }
+                        finally {
+                            try {
+                                await preflightService.close();
+                            }
+                            catch (closeError) {
+                                sdsPreflightCloseError = closeError?.message ?? String(closeError);
+                                await this.jobService.appendLog(job.id, `SDS preflight close warning: ${sdsPreflightCloseError}\n`);
+                            }
+                        }
+                    }
+                    catch (error) {
+                        sdsPreflightError = error?.message ?? String(error);
+                    }
+                    if (!sdsPreflight) {
+                        const message = `create-tasks blocked: SDS preflight failed before backlog generation (${sdsPreflightError ?? "unknown error"}).`;
+                        await this.jobService.writeCheckpoint(job.id, {
+                            stage: "sds_preflight",
+                            timestamp: new Date().toISOString(),
+                            details: {
+                                status: "failed",
+                                error: message,
+                                readyForPlanning: false,
+                                qualityStatus: undefined,
+                                sourceSdsCount: 0,
+                                issueCount: 0,
+                                blockingIssueCount: 0,
+                                questionCount: 0,
+                                requiredQuestionCount: 0,
+                                reportPath: undefined,
+                                openQuestionsPath: undefined,
+                                gapAddendumPath: undefined,
+                                warnings: [],
+                            },
+                        });
+                        throw new Error(message);
+                    }
+                    const preflightWarnings = uniqueStrings([
+                        ...(sdsPreflight.warnings ?? []),
+                        ...(sdsPreflightCloseError ? [`SDS preflight close warning: ${sdsPreflightCloseError}`] : []),
+                    ]);
+                    const blockingReasons = [];
+                    if (sdsPreflight.qualityStatus === "fail") {
+                        blockingReasons.push("SDS quality gates failed.");
+                    }
+                    if (sdsPreflight.blockingIssueCount > 0) {
+                        blockingReasons.push(`Blocking SDS issues: ${sdsPreflight.blockingIssueCount}.`);
+                    }
+                    if (sdsPreflight.requiredQuestionCount > 0) {
+                        blockingReasons.push(`Required open questions remaining: ${sdsPreflight.requiredQuestionCount}.`);
+                    }
+                    if (!sdsPreflight.readyForPlanning) {
+                        blockingReasons.push("SDS preflight reported planning context is not ready.");
+                    }
+                    if (blockingReasons.length > 0) {
+                        sdsPreflightError = blockingReasons.join(" ");
+                    }
+                    await this.jobService.writeCheckpoint(job.id, {
+                        stage: "sds_preflight",
+                        timestamp: new Date().toISOString(),
+                        details: {
+                            status: blockingReasons.length > 0 ? "blocked" : "succeeded",
+                            error: sdsPreflightError,
+                            readyForPlanning: sdsPreflight.readyForPlanning,
+                            qualityStatus: sdsPreflight.qualityStatus,
+                            sourceSdsCount: sdsPreflight.sourceSdsPaths.length,
+                            issueCount: sdsPreflight.issueCount,
+                            blockingIssueCount: sdsPreflight.blockingIssueCount,
+                            questionCount: sdsPreflight.questionCount,
+                            requiredQuestionCount: sdsPreflight.requiredQuestionCount,
+                            reportPath: sdsPreflight.reportPath,
+                            openQuestionsPath: sdsPreflight.openQuestionsPath,
+                            gapAddendumPath: sdsPreflight.gapAddendumPath,
+                            appliedToSds: sdsPreflight.appliedToSds,
+                            appliedSdsCount: sdsPreflight.appliedSdsPaths.length,
+                            commitHash: sdsPreflight.commitHash,
+                            warnings: preflightWarnings,
+                        },
+                    });
+                    if (blockingReasons.length > 0) {
+                        throw new Error(`create-tasks blocked by SDS preflight. ${blockingReasons.join(" ")} Report: ${sdsPreflight.reportPath}`);
+                    }
+                }
+                const preflightDocInputs = this.mergeDocInputs(options.inputs, sdsPreflight ? [...sdsPreflight.sourceSdsPaths, ...sdsPreflight.generatedDocPaths] : []);
+                const docs = await this.prepareDocs(preflightDocInputs);
+                const { docSummary, warnings: indexedDocWarnings } = this.buildDocContext(docs);
+                const docWarnings = uniqueStrings([...(sdsPreflight?.warnings ?? []), ...indexedDocWarnings]);
                 const discoveryGraph = this.buildServiceDependencyGraph({ epics: [], stories: [], tasks: [] }, docs);
                 const projectBuildMethod = this.buildProjectConstructionMethod(docs, discoveryGraph);
+                const projectBuildPlan = this.buildProjectPlanArtifact(options.projectKey, docs, discoveryGraph, projectBuildMethod);
                 const { prompt } = this.buildPrompt(options.projectKey, docs, projectBuildMethod, options);
                 const qaPreflight = await this.buildQaPreflight();
                 const qaOverrides = this.buildQaOverrides(options);
@@ -3043,6 +3321,15 @@ export class CreateTasksService {
                     timestamp: new Date().toISOString(),
                     details: { count: docs.length, warnings: docWarnings, startupWaves: discoveryGraph.startupWaves.slice(0, 8) },
                 });
+                await this.jobService.writeCheckpoint(job.id, {
+                    stage: "build_plan_defined",
+                    timestamp: new Date().toISOString(),
+                    details: {
+                        sourceDocs: projectBuildPlan.sourceDocs.length,
+                        services: projectBuildPlan.services.length,
+                        startupWaves: projectBuildPlan.startupWaves.length,
+                    },
+                });
                 await this.jobService.writeCheckpoint(job.id, {
                     stage: "qa_preflight",
                     timestamp: new Date().toISOString(),
@@ -3102,7 +3389,7 @@ export class CreateTasksService {
                     timestamp: new Date().toISOString(),
                     details: { tasks: plan.tasks.length, source: planSource, fallbackReason },
                 });
-                const { folder } = await this.writePlanArtifacts(options.projectKey, plan, docSummary, docs);
+                const { folder } = await this.writePlanArtifacts(options.projectKey, plan, docSummary, docs, projectBuildPlan);
                 await this.jobService.writeCheckpoint(job.id, {
                     stage: "plan_written",
                     timestamp: new Date().toISOString(),
@@ -3118,57 +3405,83 @@ export class CreateTasksService {
                 let sufficiencyAudit;
                 let sufficiencyAuditError;
                 if (this.taskSufficiencyFactory) {
+                    let sufficiencyCloseError;
                     try {
                         const sufficiencyService = await this.taskSufficiencyFactory(this.workspace);
                         try {
-                            try {
-                                sufficiencyAudit = await sufficiencyService.runAudit({
-                                    workspace: options.workspace,
-                                    projectKey: options.projectKey,
-                                    sourceCommand: "create-tasks",
-                                });
-                            }
-                            catch (error) {
-                                sufficiencyAuditError = error?.message ?? String(error);
-                                await this.jobService.appendLog(job.id, `Task sufficiency audit failed; continuing with created backlog: ${sufficiencyAuditError}\n`);
-                            }
+                            sufficiencyAudit = await sufficiencyService.runAudit({
+                                workspace: options.workspace,
+                                projectKey: options.projectKey,
+                                sourceCommand: "create-tasks",
+                            });
                         }
                         finally {
                             try {
                                 await sufficiencyService.close();
                             }
                             catch (closeError) {
-                                const closeMessage = closeError?.message ?? String(closeError);
-                                const details = `Task sufficiency audit close failed; continuing with created backlog: ${closeMessage}`;
-                                sufficiencyAuditError = sufficiencyAuditError ? `${sufficiencyAuditError}; ${details}` : details;
-                                await this.jobService.appendLog(job.id, `${details}\n`);
+                                sufficiencyCloseError = closeError?.message ?? String(closeError);
+                                await this.jobService.appendLog(job.id, `Task sufficiency audit close warning: ${sufficiencyCloseError}\n`);
                             }
                         }
                     }
                     catch (error) {
                         sufficiencyAuditError = error?.message ?? String(error);
-                        await this.jobService.appendLog(job.id, `Task sufficiency audit setup failed; continuing with created backlog: ${sufficiencyAuditError}\n`);
+                    }
+                    if (!sufficiencyAudit) {
+                        const message = `create-tasks blocked: task sufficiency audit failed (${sufficiencyAuditError ?? "unknown error"}).`;
+                        await this.jobService.writeCheckpoint(job.id, {
+                            stage: "task_sufficiency_audit",
+                            timestamp: new Date().toISOString(),
+                            details: {
+                                status: "failed",
+                                error: message,
+                                jobId: undefined,
+                                commandRunId: undefined,
+                                satisfied: false,
+                                dryRun: undefined,
+                                totalTasksAdded: undefined,
+                                totalTasksUpdated: undefined,
+                                finalCoverageRatio: undefined,
+                                reportPath: undefined,
+                                remainingSectionCount: undefined,
+                                remainingFolderCount: undefined,
+                                remainingGapCount: undefined,
+                                warnings: [],
+                            },
+                        });
+                        throw new Error(message);
+                    }
+                    const sufficiencyWarnings = uniqueStrings([
+                        ...(sufficiencyAudit.warnings ?? []),
+                        ...(sufficiencyCloseError ? [`Task sufficiency audit close warning: ${sufficiencyCloseError}`] : []),
+                    ]);
+                    if (!sufficiencyAudit.satisfied) {
+                        sufficiencyAuditError = `SDS coverage target not reached (coverage=${sufficiencyAudit.finalCoverageRatio}, remaining gaps=${sufficiencyAudit.remainingGaps.total}).`;
                     }
                     await this.jobService.writeCheckpoint(job.id, {
                         stage: "task_sufficiency_audit",
                         timestamp: new Date().toISOString(),
                         details: {
-                            status: sufficiencyAudit ? "succeeded" : "failed",
+                            status: sufficiencyAudit.satisfied ? "succeeded" : "blocked",
                             error: sufficiencyAuditError,
-                            jobId: sufficiencyAudit?.jobId,
-                            commandRunId: sufficiencyAudit?.commandRunId,
-                            satisfied: sufficiencyAudit?.satisfied,
-                            dryRun: sufficiencyAudit?.dryRun,
-                            totalTasksAdded: sufficiencyAudit?.totalTasksAdded,
-                            totalTasksUpdated: sufficiencyAudit?.totalTasksUpdated,
-                            finalCoverageRatio: sufficiencyAudit?.finalCoverageRatio,
-                            reportPath: sufficiencyAudit?.reportPath,
-                            remainingSectionCount: sufficiencyAudit?.remainingSectionHeadings.length,
-                            remainingFolderCount: sufficiencyAudit?.remainingFolderEntries.length,
-                            remainingGapCount: sufficiencyAudit?.remainingGaps.total,
-                            warnings: sufficiencyAudit?.warnings,
+                            jobId: sufficiencyAudit.jobId,
+                            commandRunId: sufficiencyAudit.commandRunId,
+                            satisfied: sufficiencyAudit.satisfied,
+                            dryRun: sufficiencyAudit.dryRun,
+                            totalTasksAdded: sufficiencyAudit.totalTasksAdded,
+                            totalTasksUpdated: sufficiencyAudit.totalTasksUpdated,
+                            finalCoverageRatio: sufficiencyAudit.finalCoverageRatio,
+                            reportPath: sufficiencyAudit.reportPath,
+                            remainingSectionCount: sufficiencyAudit.remainingSectionHeadings.length,
+                            remainingFolderCount: sufficiencyAudit.remainingFolderEntries.length,
+                            remainingGapCount: sufficiencyAudit.remainingGaps.total,
+                            warnings: sufficiencyWarnings,
                         },
                     });
+                    if (!sufficiencyAudit.satisfied) {
+                        throw new Error(`create-tasks blocked: task sufficiency audit did not reach full coverage. Report: ${sufficiencyAudit.reportPath}`);
+                    }
                 }
                 await this.jobService.updateJobStatus(job.id, "completed", {
                     payload: {
@@ -3180,6 +3493,25 @@ export class CreateTasksService {
                         planFolder: folder,
                         planSource,
                         fallbackReason,
+                        sdsPreflight: sdsPreflight
+                            ? {
+                                readyForPlanning: sdsPreflight.readyForPlanning,
+                                qualityStatus: sdsPreflight.qualityStatus,
+                                sourceSdsCount: sdsPreflight.sourceSdsPaths.length,
+                                issueCount: sdsPreflight.issueCount,
+                                blockingIssueCount: sdsPreflight.blockingIssueCount,
+                                questionCount: sdsPreflight.questionCount,
+                                requiredQuestionCount: sdsPreflight.requiredQuestionCount,
+                                appliedToSds: sdsPreflight.appliedToSds,
+                                appliedSdsPaths: sdsPreflight.appliedSdsPaths,
+                                commitHash: sdsPreflight.commitHash,
+                                reportPath: sdsPreflight.reportPath,
+                                openQuestionsPath: sdsPreflight.openQuestionsPath,
+                                gapAddendumPath: sdsPreflight.gapAddendumPath,
+                                warnings: sdsPreflight.warnings,
+                            }
+                            : undefined,
+                        sdsPreflightError,
                         sufficiencyAudit: sufficiencyAudit
                             ? {
                                 jobId: sufficiencyAudit.jobId,