@mcoda/core 0.1.24 → 0.1.27

package/dist/services/planning/CreateTasksService.js

@@ -12,6 +12,7 @@ import { classifyTask } from "../backlog/TaskOrderingHeuristics.js";
 import { TaskOrderingService } from "../backlog/TaskOrderingService.js";
 import { QaTestCommandBuilder } from "../execution/QaTestCommandBuilder.js";
 import { createEpicKeyGenerator, createStoryKeyGenerator, createTaskKeyGenerator, } from "./KeyHelpers.js";
+import { TaskSufficiencyService } from "./TaskSufficiencyService.js";
 const formatBullets = (items, fallback) => {
     if (!items || items.length === 0)
         return `- ${fallback}`;
@@ -116,6 +117,33 @@ const formatTestList = (items) => {
     return items.join("; ");
 };
 const ensureNonEmpty = (value, fallback) => value && value.trim().length > 0 ? value.trim() : fallback;
+const normalizeTaskLine = (line) => line.replace(/^[-*]\s+/, "").trim();
+const looksLikeSectionHeader = (line) => /^\* \*\*.+\*\*$/.test(line.trim());
+const isReferenceOnlyLine = (line) => /^(epic|story|references?|related docs?|inputs?|objective|context|implementation plan|definition of done|testing & qa)\s*:/i.test(line.trim());
+const extractActionableLines = (description, limit) => {
+    if (!description)
+        return [];
+    const lines = description
+        .split(/\r?\n/)
+        .map((line) => normalizeTaskLine(line))
+        .filter(Boolean)
+        .filter((line) => !looksLikeSectionHeader(line))
+        .filter((line) => !isReferenceOnlyLine(line));
+    const actionable = lines.filter((line) => /^(?:\d+[.)]\s+|implement\b|create\b|update\b|add\b|define\b|wire\b|integrate\b|enforce\b|publish\b|configure\b|materialize\b|validate\b|verify\b)/i.test(line));
+    const source = actionable.length > 0 ? actionable : lines;
+    return uniqueStrings(source.slice(0, limit));
+};
+const extractRiskLines = (description, limit) => {
+    if (!description)
+        return [];
+    const lines = description
+        .split(/\r?\n/)
+        .map((line) => normalizeTaskLine(line))
+        .filter(Boolean)
+        .filter((line) => !looksLikeSectionHeader(line));
+    const risks = lines.filter((line) => /\b(risk|edge case|gotcha|constraint|failure|flaky|drift|regression)\b/i.test(line));
+    return uniqueStrings(risks.slice(0, limit));
+};
 const extractScriptPort = (script) => {
     const matches = [script.match(/(?:--port|-p)\s*(\d{2,5})/), script.match(/PORT\s*=\s*(\d{2,5})/)];
     for (const match of matches) {
@@ -129,8 +157,18 @@ const extractScriptPort = (script) => {
 };
 const estimateTokens = (text) => Math.max(1, Math.ceil(text.length / 4));
 const DOC_CONTEXT_BUDGET = 8000;
+const DOC_CONTEXT_SEGMENTS_PER_DOC = 8;
+const DOC_CONTEXT_FALLBACK_CHUNK_LENGTH = 480;
+const SDS_COVERAGE_HINT_HEADING_LIMIT = 24;
+const SDS_COVERAGE_REPORT_SECTION_LIMIT = 80;
 const OPENAPI_HINT_OPERATIONS_LIMIT = 30;
 const DOCDEX_HANDLE = /^docdex:/i;
+const DOCDEX_LOCAL_HANDLE = /^docdex:local[-:/]/i;
+const RELATED_DOC_PATH_PATTERN = /^(?:~\/|\/|[A-Za-z]:[\\/]|[A-Za-z0-9._-]+\/)[A-Za-z0-9._/-]+(?:\.[A-Za-z0-9._-]+)?(?:#[A-Za-z0-9._:-]+)?$/;
+const RELATIVE_DOC_PATH_PATTERN = /^(?:\.{1,2}\/)+[A-Za-z0-9._/-]+(?:\.[A-Za-z0-9._-]+)?(?:#[A-Za-z0-9._:-]+)?$/;
+const FUZZY_DOC_CANDIDATE_LIMIT = 64;
+const DEPENDENCY_SCAN_LINE_LIMIT = 1400;
+const STARTUP_WAVE_SCAN_LINE_LIMIT = 4000;
 const VALID_AREAS = new Set(["web", "adm", "bck", "ops", "infra", "mobile"]);
 const VALID_TASK_TYPES = new Set(["feature", "bug", "chore", "spike"]);
 const inferDocType = (filePath) => {
@@ -176,16 +214,85 @@ const normalizeTaskType = (value) => {
 const normalizeRelatedDocs = (value) => {
     if (!Array.isArray(value))
         return [];
-    return value
-        .map((entry) => {
-        if (typeof entry === "string")
-            return entry;
-        if (entry && typeof entry === "object" && "handle" in entry && typeof entry.handle === "string") {
-            return entry.handle;
-        }
-        return undefined;
-    })
-        .filter((entry) => Boolean(entry && DOCDEX_HANDLE.test(entry)));
+    const seen = new Set();
+    const normalized = [];
+    for (const entry of value) {
+        const candidate = typeof entry === "string"
+            ? entry.trim()
+            : entry && typeof entry === "object" && "handle" in entry && typeof entry.handle === "string"
+                ? entry.handle.trim()
+                : "";
+        if (!candidate)
+            continue;
+        if (DOCDEX_LOCAL_HANDLE.test(candidate))
+            continue;
+        const isDocHandle = DOCDEX_HANDLE.test(candidate);
+        const isHttp = /^https?:\/\/\S+$/i.test(candidate);
+        const isPath = RELATED_DOC_PATH_PATTERN.test(candidate) || RELATIVE_DOC_PATH_PATTERN.test(candidate);
+        if (!isDocHandle && !isHttp && !isPath)
+            continue;
+        if (seen.has(candidate))
+            continue;
+        seen.add(candidate);
+        normalized.push(candidate);
+    }
+    return normalized;
+};
+const extractMarkdownHeadings = (value, limit) => {
+    if (!value)
+        return [];
+    const lines = value.split(/\r?\n/);
+    const headings = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index]?.trim() ?? "";
+        if (!line)
+            continue;
+        const hashHeading = line.match(/^#{1,6}\s+(.+)$/);
+        if (hashHeading) {
+            headings.push(hashHeading[1].trim());
+        }
+        else if (index + 1 < lines.length &&
+            /^[=-]{3,}\s*$/.test((lines[index + 1] ?? "").trim()) &&
+            !line.startsWith("-") &&
+            !line.startsWith("*")) {
+            headings.push(line);
+        }
+        if (headings.length >= limit)
+            break;
+    }
+    return uniqueStrings(headings
+        .map((entry) => entry.replace(/[`*_]/g, "").trim())
+        .filter(Boolean));
+};
+const pickDistributedIndices = (length, limit) => {
+    if (length <= 0 || limit <= 0)
+        return [];
+    if (length <= limit)
+        return Array.from({ length }, (_, index) => index);
+    const selected = new Set();
+    for (let index = 0; index < limit; index += 1) {
+        const ratio = limit === 1 ? 0 : index / (limit - 1);
+        selected.add(Math.round(ratio * (length - 1)));
+    }
+    return Array.from(selected)
+        .sort((a, b) => a - b)
+        .slice(0, limit);
+};
+const sampleRawContent = (value, chunkLength) => {
+    if (!value)
+        return [];
+    const content = value.trim();
+    if (!content)
+        return [];
+    if (content.length <= chunkLength)
+        return [content];
+    const anchors = [
+        0,
+        Math.max(0, Math.floor(content.length / 2) - Math.floor(chunkLength / 2)),
+        Math.max(0, content.length - chunkLength),
+    ];
+    const sampled = anchors.map((anchor) => content.slice(anchor, anchor + chunkLength).trim()).filter(Boolean);
+    return uniqueStrings(sampled);
 };
 const isPlainObject = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
 const parseStructuredDoc = (raw) => {
@@ -291,58 +398,50 @@ const extractJsonObjects = (value) => {
     }
     return results;
 };
+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) => {
@@ -356,21 +455,48 @@ const buildTaskDescription = (taskKey, title, description, storyKey, epicKey, re
         })
             .join("\n");
     };
+    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) +
+        (tests.componentTests?.length ?? 0) +
+        (tests.integrationTests?.length ?? 0) +
+        (tests.apiTests?.length ?? 0) >
+        0;
+    const definitionOfDone = [
+        `- Implementation for \`${taskKey}\` is complete and scoped to ${storyKey}.`,
+        testsDefined
+            ? "- Task-specific tests are added/updated and green in the task validation loop."
+            : "- Verification evidence is captured in task logs/checklists for this scope.",
+        relatedDocs?.length
+            ? "- Related contracts/docs are consistent with delivered behavior."
+            : "- Documentation impact is reviewed and no additional contract docs are required.",
+        qa?.blockers?.length ? "- Remaining QA blockers are explicit and actionable." : "- QA blockers are resolved or not present.",
+    ];
+    const defaultImplementationPlan = [
+        `Implement ${title} with concrete file/module-level changes aligned to the objective.`,
+        dependencies.length
+            ? `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."];
     return [
         `* **Task Key**: ${taskKey}`,
         "* **Objective**",
         "",
-        ensureNonEmpty(description, `Deliver ${title} for story ${storyKey}.`),
+        objectiveText,
         "* **Context**",
         "",
         `- Epic: ${epicKey}`,
         `- Story: ${storyKey}`,
         "* **Inputs**",
-        formatBullets(relatedDocs, "Docdex excerpts, SDS/PDR/RFP sections, OpenAPI endpoints."),
+        formatBullets(relatedDocs, "No explicit external references."),
         "* **Implementation Plan**",
-        "- Break this into concrete steps during execution.",
+        formatBullets(implementationLines, defaultImplementationPlan.join(" ")),
         "* **Definition of Done**",
-        "- Tests passing, docs updated, review/QA complete.",
+        definitionOfDone.join("\n"),
         "* **Testing & QA**",
         `- Unit tests: ${formatTestList(tests.unitTests)}`,
         `- Component tests: ${formatTestList(tests.componentTests)}`,
@@ -385,11 +511,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**",
-        "- Highlight edge cases or risky areas.",
+        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) => {
@@ -594,6 +720,7 @@ export class CreateTasksService {
         this.routingService = deps.routingService;
         this.ratingService = deps.ratingService;
         this.taskOrderingFactory = deps.taskOrderingFactory ?? TaskOrderingService.create;
+        this.taskSufficiencyFactory = deps.taskSufficiencyFactory ?? TaskSufficiencyService.create;
     }
     static async create(workspace) {
         const repo = await GlobalRepository.create();
@@ -614,6 +741,7 @@ export class CreateTasksService {
             repo,
             workspaceRepo,
             routingService,
+            taskSufficiencyFactory: TaskSufficiencyService.create,
         });
     }
     async close() {
@@ -903,7 +1031,7 @@ export class CreateTasksService {
         }
         return ranked
             .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
-            .slice(0, 24)
+            .slice(0, FUZZY_DOC_CANDIDATE_LIMIT)
             .map((entry) => entry.path);
     }
     normalizeStructurePathToken(value) {
@@ -1072,7 +1200,7 @@ export class CreateTasksService {
             .split(/\r?\n/)
             .map((line) => line.trim())
             .filter(Boolean)
-            .slice(0, 300);
+            .slice(0, DEPENDENCY_SCAN_LINE_LIMIT);
         const dependencyPatterns = [
             {
                 regex: /^(.+?)\b(?:depends on|requires|needs|uses|consumes|calls|reads from|writes to|must come after|comes after|built after|runs after|backed by)\b(.+)$/i,
@@ -1156,7 +1284,7 @@ export class CreateTasksService {
             .split(/\r?\n/)
             .map((line) => line.trim())
             .filter(Boolean)
-            .slice(0, 2000);
+            .slice(0, STARTUP_WAVE_SCAN_LINE_LIMIT);
         for (const line of lines) {
             if (!line.startsWith("|"))
                 continue;
@@ -1353,6 +1481,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();
@@ -1949,23 +2092,59 @@ export class CreateTasksService {
         }
         return lines.join("\n");
     }
+    extractSdsSectionCandidates(docs, limit) {
+        const sections = [];
+        for (const doc of docs) {
+            if (!looksLikeSdsDoc(doc))
+                continue;
+            const segmentHeadings = (doc.segments ?? [])
+                .map((segment) => segment.heading?.trim())
+                .filter((heading) => Boolean(heading));
+            const contentHeadings = extractMarkdownHeadings(doc.content ?? "", limit);
+            for (const heading of [...segmentHeadings, ...contentHeadings]) {
+                const normalized = heading.replace(/[`*_]/g, "").trim();
+                if (!normalized)
+                    continue;
+                sections.push(normalized);
+                if (sections.length >= limit)
+                    break;
+            }
+            if (sections.length >= limit)
+                break;
+        }
+        return uniqueStrings(sections).slice(0, limit);
+    }
+    buildSdsCoverageHints(docs) {
+        const hints = this.extractSdsSectionCandidates(docs, SDS_COVERAGE_HINT_HEADING_LIMIT);
+        if (hints.length === 0)
+            return "";
+        return hints.map((hint) => `- ${hint}`).join("\n");
+    }
     buildDocContext(docs) {
         const warnings = [];
         const blocks = [];
         let budget = DOC_CONTEXT_BUDGET;
-        const sorted = [...docs].sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
+        const sorted = [...docs].sort((a, b) => {
+            const sdsDelta = Number(looksLikeSdsDoc(b)) - Number(looksLikeSdsDoc(a));
+            if (sdsDelta !== 0)
+                return sdsDelta;
+            return (b.updatedAt ?? "").localeCompare(a.updatedAt ?? "");
+        });
         for (const [idx, doc] of sorted.entries()) {
-            const segments = (doc.segments ?? []).slice(0, 5);
-            const content = segments.length
-                ? segments
+            const segments = doc.segments ?? [];
+            const sampledSegments = pickDistributedIndices(segments.length, DOC_CONTEXT_SEGMENTS_PER_DOC)
+                .map((index) => segments[index])
+                .filter(Boolean);
+            const content = sampledSegments.length
+                ? sampledSegments
                     .map((seg, i) => {
                     const trimmed = seg.content.length > 600 ? `${seg.content.slice(0, 600)}...` : seg.content;
                     return `  - (${i + 1}) ${seg.heading ? `${seg.heading}: ` : ""}${trimmed}`;
                 })
                     .join("\n")
-                : doc.content
-                    ? doc.content.slice(0, 800)
-                    : "";
+                : sampleRawContent(doc.content, DOC_CONTEXT_FALLBACK_CHUNK_LENGTH)
+                    .map((chunk, i) => `  - (${i + 1}) ${chunk.length > 600 ? `${chunk.slice(0, 600)}...` : chunk}`)
+                    .join("\n");
             const entry = [`[${doc.docType}] docdex:${doc.id ?? `doc-${idx + 1}`}`, describeDoc(doc, idx), content]
                 .filter(Boolean)
                 .join("\n");
@@ -1991,6 +2170,18 @@ export class CreateTasksService {
                 warnings.push("Context truncated due to token budget; skipped OpenAPI hint summary.");
             }
         }
+        const sdsCoverageHints = this.buildSdsCoverageHints(sorted);
+        if (sdsCoverageHints) {
+            const hintBlock = ["[SDS_COVERAGE_HINTS]", sdsCoverageHints].join("\n");
+            const hintCost = estimateTokens(hintBlock);
+            if (budget - hintCost >= 0) {
+                budget -= hintCost;
+                blocks.push(hintBlock);
+            }
+            else {
+                warnings.push("Context truncated due to token budget; skipped SDS coverage hints.");
+            }
+        }
         return { docSummary: blocks.join("\n\n") || "(no docs)", warnings };
     }
     buildPrompt(projectKey, docs, projectBuildMethod, options) {
@@ -2003,17 +2194,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.",
@@ -2047,10 +2239,10 @@ export class CreateTasksService {
                             tasks: [
                                 {
                                     localId: "task-1",
-                                    title: "Summarize requirements",
-                                    type: "chore",
-                                    description: "Summarize key asks from docs and SDS/PDR/RFP inputs.",
-                                    estimatedStoryPoints: 1,
+                                    title: "Implement baseline project scaffolding",
+                                    type: "feature",
+                                    description: "Create SDS-aligned baseline structure and core implementation entrypoints from the available docs.",
+                                    estimatedStoryPoints: 3,
                                     priorityHint: 10,
                                     relatedDocs: docRefs,
                                     unitTests: [],
@@ -2060,10 +2252,10 @@ export class CreateTasksService {
                                 },
                                 {
                                     localId: "task-2",
-                                    title: "Propose tasks and ordering",
+                                    title: "Integrate core contracts and dependencies",
                                     type: "feature",
-                                    description: "Break down the scope into tasks with initial dependencies.",
-                                    estimatedStoryPoints: 2,
+                                    description: "Wire key contracts/interfaces and dependency paths so core behavior can execute end-to-end.",
+                                    estimatedStoryPoints: 3,
                                     priorityHint: 20,
                                     dependsOnKeys: ["task-1"],
                                     relatedDocs: docRefs,
@@ -2072,6 +2264,20 @@ export class CreateTasksService {
                                     integrationTests: [],
                                     apiTests: [],
                                 },
+                                {
+                                    localId: "task-3",
+                                    title: "Validate baseline behavior and regressions",
+                                    type: "chore",
+                                    description: "Add targeted validation coverage and readiness evidence for the implemented baseline capabilities.",
+                                    estimatedStoryPoints: 2,
+                                    priorityHint: 30,
+                                    dependsOnKeys: ["task-2"],
+                                    relatedDocs: docRefs,
+                                    unitTests: [],
+                                    componentTests: [],
+                                    integrationTests: [],
+                                    apiTests: [],
+                                },
                             ],
                         },
                     ],
@@ -2255,14 +2461,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)",
@@ -2300,23 +2507,29 @@ 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:",
             "- Each task must include localId, title, description, type, estimatedStoryPoints, priorityHint.",
+            "- Descriptions must be implementation-concrete and include target modules/files/services where work happens.",
+            "- Prioritize software construction tasks before test-only/docs-only chores unless story scope explicitly requires those first.",
             "- Include test arrays: unitTests, componentTests, integrationTests, apiTests. Use [] when not applicable.",
             "- Only include tests that are relevant to the task's scope.",
             "- Prefer including task-relevant tests when they are concrete and actionable; do not invent generic placeholders.",
             "- When known, include qa object with profiles_expected/requires/entrypoints/data_setup to guide QA.",
             "- Do not hardcode ports. For QA entrypoints, use http://localhost:<PORT> placeholders or omit base_url when unknown.",
             "- dependsOnKeys must reference localIds in this story.",
+            "- If dependsOnKeys is non-empty, include dependency rationale in the task description.",
             "- Start from prerequisite codebase setup: add structure/bootstrap tasks before feature tasks when missing.",
             "- 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.",
             "- Follow the project construction method and startup-wave order from SDS when available.",
             `Story context (key=${story.key ?? story.localId ?? "TBD"}):`,
             story.description ?? story.userStory ?? "",
@@ -2387,17 +2600,22 @@ export class CreateTasksService {
             .slice(0, 6)
             .map((criterion) => `- ${criterion}`)
             .join("\n");
+        const objectiveLine = story.description && story.description.trim().length > 0
+            ? story.description.trim().split(/\r?\n/)[0]
+            : `Deliver story scope for "${story.title}".`;
         return [
             {
                 localId: "t-fallback-1",
-                title: `Fallback planning for ${story.title}`,
-                type: "chore",
+                title: `Implement core scope for ${story.title}`,
+                type: "feature",
                 description: [
-                    `Draft a concrete implementation plan for story "${story.title}" using SDS/OpenAPI context.`,
-                    "List exact files/modules to touch and implementation order.",
+                    `Implement the core product behavior for story "${story.title}".`,
+                    `Primary objective: ${objectiveLine}`,
+                    "Create or update concrete modules/files and wire baseline runtime paths first.",
+                    "Capture exact implementation targets and sequencing in commit-level task notes.",
                     criteriaLines ? `Acceptance criteria to satisfy:\n${criteriaLines}` : "Acceptance criteria: use story definition.",
                 ].join("\n"),
-                estimatedStoryPoints: 2,
+                estimatedStoryPoints: 3,
                 priorityHint: 1,
                 dependsOnKeys: [],
                 relatedDocs: story.relatedDocs ?? [],
@@ -2408,11 +2626,12 @@ export class CreateTasksService {
             },
             {
                 localId: "t-fallback-2",
-                title: `Fallback implementation for ${story.title}`,
+                title: `Integrate contracts for ${story.title}`,
                 type: "feature",
                 description: [
-                    `Implement story "${story.title}" according to the fallback planning task.`,
-                    "Ensure done criteria and test requirements are explicitly documented for execution.",
+                    `Integrate dependent contracts/interfaces for "${story.title}" after core scope implementation.`,
+                    "Align internal/external interfaces, data contracts, and dependency wiring with SDS/OpenAPI context.",
+                    "Record dependency rationale and compatibility constraints in the task output.",
                 ].join("\n"),
                 estimatedStoryPoints: 3,
                 priorityHint: 2,
@@ -2423,6 +2642,24 @@ export class CreateTasksService {
                 integrationTests: [],
                 apiTests: [],
             },
+            {
+                localId: "t-fallback-3",
+                title: `Validate ${story.title} regressions and readiness`,
+                type: "chore",
+                description: [
+                    `Validate "${story.title}" end-to-end with focused regression coverage and readiness evidence.`,
+                    "Add/update targeted tests and verification scripts tied to implemented behavior.",
+                    "Document release/code-review/QA evidence and unresolved risks explicitly.",
+                ].join("\n"),
+                estimatedStoryPoints: 2,
+                priorityHint: 3,
+                dependsOnKeys: ["t-fallback-2"],
+                relatedDocs: story.relatedDocs ?? [],
+                unitTests: [],
+                componentTests: [],
+                integrationTests: [],
+                apiTests: [],
+            },
         ];
     }
     async generatePlanFromAgent(epics, agent, docSummary, options) {
@@ -2493,17 +2730,65 @@ export class CreateTasksService {
         }
         return { epics: planEpics, stories: planStories, tasks: planTasks };
     }
-    async writePlanArtifacts(projectKey, plan, docSummary) {
+    buildSdsCoverageReport(projectKey, docs, plan) {
+        const sections = this.extractSdsSectionCandidates(docs, SDS_COVERAGE_REPORT_SECTION_LIMIT);
+        const normalize = (value) => value
+            .toLowerCase()
+            .replace(/[`*_]/g, "")
+            .replace(/[^a-z0-9\s/-]+/g, " ")
+            .replace(/\s+/g, " ")
+            .trim();
+        const planCorpus = normalize([
+            ...plan.epics.map((epic) => `${epic.title} ${epic.description ?? ""} ${(epic.acceptanceCriteria ?? []).join(" ")}`),
+            ...plan.stories.map((story) => `${story.title} ${story.userStory ?? ""} ${story.description ?? ""} ${(story.acceptanceCriteria ?? []).join(" ")}`),
+            ...plan.tasks.map((task) => `${task.title} ${task.description ?? ""}`),
+        ].join("\n"));
+        const matched = [];
+        const unmatched = [];
+        for (const section of sections) {
+            const normalizedSection = normalize(section);
+            if (!normalizedSection)
+                continue;
+            const keywords = normalizedSection
+                .split(/\s+/)
+                .filter((token) => token.length >= 4)
+                .slice(0, 6);
+            const hasDirectMatch = normalizedSection.length >= 6 && planCorpus.includes(normalizedSection);
+            const hasKeywordMatch = keywords.some((keyword) => planCorpus.includes(keyword));
+            if (hasDirectMatch || hasKeywordMatch) {
+                matched.push(section);
+            }
+            else {
+                unmatched.push(section);
+            }
+        }
+        const totalSections = matched.length + unmatched.length;
+        const coverageRatio = totalSections === 0 ? 1 : matched.length / totalSections;
+        return {
+            projectKey,
+            generatedAt: new Date().toISOString(),
+            totalSections,
+            matched,
+            unmatched,
+            coverageRatio: Number(coverageRatio.toFixed(4)),
+            notes: totalSections === 0
+                ? ["No SDS section headings detected; coverage defaults to 1.0."]
+                : ["Coverage is heading-based heuristic match between SDS sections and generated epic/story/task corpus."],
+        };
+    }
+    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);
+        await write("coverage-report.json", this.buildSdsCoverageReport(projectKey, docs, plan));
         return { folder: baseDir };
     }
     async persistPlanToDb(projectId, projectKey, plan, jobId, commandRunId, options) {
@@ -2632,12 +2917,7 @@ export class CreateTasksService {
                         discoveredTestCommands = [];
                     }
                 }
-                const qaBlockers = uniqueStrings([
-                    ...(qaReadiness.blockers ?? []),
-                    ...(testsRequired && discoveredTestCommands.length === 0
-                        ? ["No runnable test harness discovered for required tests during planning."]
-                        : []),
-                ]);
+                const qaBlockers = uniqueStrings(qaReadiness.blockers ?? []);
                 const qaReadinessWithHarness = {
                     ...qaReadiness,
                     blockers: qaBlockers.length ? qaBlockers : undefined,
@@ -2766,6 +3046,7 @@ export class CreateTasksService {
                 const { docSummary, warnings: docWarnings } = this.buildDocContext(docs);
                 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);
@@ -2774,6 +3055,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(),
@@ -2833,7 +3123,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);
+                const { folder } = await this.writePlanArtifacts(options.projectKey, plan, docSummary, docs, projectBuildPlan);
                 await this.jobService.writeCheckpoint(job.id, {
                     stage: "plan_written",
                     timestamp: new Date().toISOString(),
@@ -2846,6 +3136,61 @@ export class CreateTasksService {
                     qaOverrides,
                 });
                 await this.seedPriorities(options.projectKey);
+                let sufficiencyAudit;
+                let sufficiencyAuditError;
+                if (this.taskSufficiencyFactory) {
+                    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`);
+                            }
+                        }
+                        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`);
+                            }
+                        }
+                    }
+                    catch (error) {
+                        sufficiencyAuditError = error?.message ?? String(error);
+                        await this.jobService.appendLog(job.id, `Task sufficiency audit setup failed; continuing with created backlog: ${sufficiencyAuditError}\n`);
+                    }
+                    await this.jobService.writeCheckpoint(job.id, {
+                        stage: "task_sufficiency_audit",
+                        timestamp: new Date().toISOString(),
+                        details: {
+                            status: sufficiencyAudit ? "succeeded" : "failed",
+                            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,
+                        },
+                    });
+                }
                 await this.jobService.updateJobStatus(job.id, "completed", {
                     payload: {
                         epicsCreated: epicRows.length,
@@ -2856,6 +3201,22 @@ export class CreateTasksService {
                         planFolder: folder,
                         planSource,
                         fallbackReason,
+                        sufficiencyAudit: sufficiencyAudit
+                            ? {
+                                jobId: sufficiencyAudit.jobId,
+                                commandRunId: sufficiencyAudit.commandRunId,
+                                satisfied: sufficiencyAudit.satisfied,
+                                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,
+                            }
+                            : undefined,
+                        sufficiencyAuditError,
                     },
                 });
                 await this.jobService.finishCommandRun(commandRun.id, "succeeded");