@mcoda/core 0.1.23 → 0.1.26

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) => {
@@ -356,11 +463,38 @@ const buildTaskDescription = (taskKey, title, description, storyKey, epicKey, re
         })
             .join("\n");
     };
+    const objectiveText = ensureNonEmpty(description, `Deliver ${title} for story ${storyKey}.`);
+    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 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.",
+    ];
+    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}`,
@@ -368,9 +502,9 @@ const buildTaskDescription = (taskKey, title, description, storyKey, epicKey, re
         "* **Inputs**",
         formatBullets(relatedDocs, "Docdex excerpts, SDS/PDR/RFP sections, OpenAPI endpoints."),
         "* **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)}`,
@@ -387,7 +521,7 @@ const buildTaskDescription = (taskKey, title, description, storyKey, epicKey, re
         "* **Dependencies**",
         formatBullets(dependencies, "Enumerate prerequisite tasks by key."),
         "* **Risks & Gotchas**",
-        "- Highlight edge cases or risky areas.",
+        formatBullets(riskLines, defaultRisks.join(" ")),
         "* **Related Documentation / References**",
         formatBullets(relatedDocs, "Docdex handles or file paths to consult."),
     ].join("\n");
@@ -594,6 +728,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 +749,7 @@ export class CreateTasksService {
             repo,
             workspaceRepo,
             routingService,
+            taskSufficiencyFactory: TaskSufficiencyService.create,
         });
     }
     async close() {
@@ -903,7 +1039,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 +1208,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 +1292,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;
@@ -1949,23 +2085,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 +2163,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) {
@@ -2047,10 +2231,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 +2244,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 +2256,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: [],
+                                },
                             ],
                         },
                     ],
@@ -2306,17 +2504,22 @@ export class CreateTasksService {
             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).",
             "- 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 +2590,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 +2616,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 +2632,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,7 +2720,53 @@ 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) {
         const baseDir = path.join(this.workspace.mcodaDir, "tasks", projectKey);
         await fs.mkdir(baseDir, { recursive: true });
         const write = async (file, data) => {
@@ -2504,6 +2777,7 @@ export class CreateTasksService {
         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 +2906,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,
@@ -2833,7 +3102,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);
                 await this.jobService.writeCheckpoint(job.id, {
                     stage: "plan_written",
                     timestamp: new Date().toISOString(),
@@ -2846,6 +3115,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 +3180,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");

package/dist/services/planning/RefineTasksService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RefineTasksService.d.ts","sourceRoot":"","sources":["../../../src/services/planning/RefineTasksService.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAE,gBAAgB,EAA6C,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC7G,OAAO,EAIL,kBAAkB,EAClB,iBAAiB,EAKlB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAKrE,UAAU,kBAAmB,SAAQ,kBAAkB;IACrD,SAAS,EAAE,mBAAmB,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA6MD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,IAAI,CAAmB;IAC/B,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,aAAa,CAAC,CAAqB;gBAGzC,SAAS,EAAE,mBAAmB,EAC9B,IAAI,EAAE;QACJ,MAAM,EAAE,YAAY,CAAC;QACrB,UAAU,EAAE,UAAU,CAAC;QACvB,YAAY,EAAE,YAAY,CAAC;QAC3B,IAAI,EAAE,gBAAgB,CAAC;QACvB,aAAa,EAAE,mBAAmB,CAAC;QACnC,cAAc,EAAE,cAAc,CAAC;QAC/B,aAAa,CAAC,EAAE,kBAAkB,CAAC;KACpC;WAYU,MAAM,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAuB1E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAkBd,cAAc;YAYd,YAAY;YAwBZ,mBAAmB;IA4CjC,OAAO,CAAC,mBAAmB;YAYb,WAAW;IA4KzB,OAAO,CAAC,iBAAiB;YASX,gBAAgB;IAmK9B,OAAO,CAAC,gBAAgB;IA+BxB,OAAO,CAAC,uBAAuB;YA+CjB,aAAa;YA4Eb,gBAAgB;YA+BhB,kBAAkB;IAkChC,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,kBAAkB;IAkB1B,OAAO,CAAC,iBAAiB;IA8EzB,OAAO,CAAC,WAAW;IA0BnB,OAAO,CAAC,iBAAiB;YAkBX,eAAe;YAqYf,WAAW;IAmGnB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAma3E"}
+{"version":3,"file":"RefineTasksService.d.ts","sourceRoot":"","sources":["../../../src/services/planning/RefineTasksService.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAE,gBAAgB,EAA6C,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC7G,OAAO,EAIL,kBAAkB,EAClB,iBAAiB,EAKlB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAKrE,UAAU,kBAAmB,SAAQ,kBAAkB;IACrD,SAAS,EAAE,mBAAmB,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAgOD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,IAAI,CAAmB;IAC/B,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,aAAa,CAAC,CAAqB;gBAGzC,SAAS,EAAE,mBAAmB,EAC9B,IAAI,EAAE;QACJ,MAAM,EAAE,YAAY,CAAC;QACrB,UAAU,EAAE,UAAU,CAAC;QACvB,YAAY,EAAE,YAAY,CAAC;QAC3B,IAAI,EAAE,gBAAgB,CAAC;QACvB,aAAa,EAAE,mBAAmB,CAAC;QACnC,cAAc,EAAE,cAAc,CAAC;QAC/B,aAAa,CAAC,EAAE,kBAAkB,CAAC;KACpC;WAYU,MAAM,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAuB1E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAkBd,cAAc;YAYd,YAAY;YAwBZ,mBAAmB;IA4CjC,OAAO,CAAC,mBAAmB;YAYb,WAAW;IA4KzB,OAAO,CAAC,iBAAiB;YASX,gBAAgB;IAmK9B,OAAO,CAAC,gBAAgB;IA+BxB,OAAO,CAAC,uBAAuB;YA+CjB,aAAa;YA4Eb,gBAAgB;YA+BhB,kBAAkB;IAkChC,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,kBAAkB;IAkB1B,OAAO,CAAC,iBAAiB;IA2GzB,OAAO,CAAC,WAAW;IA0BnB,OAAO,CAAC,iBAAiB;YAkBX,eAAe;YAmaf,WAAW;IAmGnB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAma3E"}