@mcoda/core 0.1.34 → 0.1.35

package/dist/services/planning/CreateTasksService.js

@@ -12,6 +12,8 @@ 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 { collectSdsCoverageSignalsFromDocs, evaluateSdsCoverage, normalizeCoverageText, } from "./SdsCoverageModel.js";
+import { collectSdsImplementationSignals, extractStructuredPaths, filterImplementationStructuredPaths, headingLooksImplementationRelevant, isStructuredFilePath, normalizeHeadingCandidate, normalizeStructuredPathToken, stripManagedSdsPreflightBlock, } from "./SdsStructureSignals.js";
 import { TaskSufficiencyService } from "./TaskSufficiencyService.js";
 import { SdsPreflightService } from "./SdsPreflightService.js";
 const formatBullets = (items, fallback) => {
@@ -162,6 +164,7 @@ 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 SDS_COVERAGE_REPORT_FOLDER_LIMIT = 240;
 const OPENAPI_HINT_OPERATIONS_LIMIT = 30;
 const DOCDEX_HANDLE = /^docdex:/i;
 const DOCDEX_LOCAL_HANDLE = /^docdex:local[-:/]/i;
@@ -170,7 +173,6 @@ const RELATIVE_DOC_PATH_PATTERN = /^(?:\.{1,2}\/)+[A-Za-z0-9._/-]+(?:\.[A-Za-z0-
 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 VALID_EPIC_SERVICE_POLICIES = new Set(["auto-remediate", "fail"]);
 const CROSS_SERVICE_TAG = "cross_service";
@@ -189,16 +191,12 @@ const inferDocType = (filePath) => {
 const normalizeArea = (value) => {
     if (typeof value !== "string")
         return undefined;
-    const tokens = value
+    const normalized = value
         .toLowerCase()
-        .split(/[^a-z]+/)
-        .map((token) => token.trim())
-        .filter(Boolean);
-    for (const token of tokens) {
-        if (VALID_AREAS.has(token))
-            return token;
-    }
-    return undefined;
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-");
+    return normalized.length > 0 ? normalized.slice(0, 24) : undefined;
 };
 const normalizeTaskType = (value) => {
     if (typeof value !== "string")
@@ -252,40 +250,6 @@ const normalizeRelatedDocs = (value) => {
     }
     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);
-        }
-        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;
-    }
-    return uniqueStrings(headings
-        .map((entry) => entry.replace(/[`*_]/g, "").trim())
-        .filter(Boolean));
-};
 const pickDistributedIndices = (length, limit) => {
     if (length <= 0 || limit <= 0)
         return [];
@@ -574,8 +538,8 @@ const buildTaskDescription = (taskKey, title, description, storyKey, epicKey, re
             ? "- 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.",
+            ? "- Related interfaces/docs are consistent with delivered behavior."
+            : "- Documentation impact is reviewed and no additional interface docs are required.",
         qa?.blockers?.length ? "- Remaining QA blockers are explicit and actionable." : "- QA blockers are resolved or not present.",
     ];
     const defaultImplementationPlan = [
@@ -586,7 +550,7 @@ const buildTaskDescription = (taskKey, title, description, storyKey, epicKey, re
     ];
     const defaultRisks = dependencies.length
         ? [`Delivery depends on upstream tasks: ${dependencies.join(", ")}.`]
-        : ["Keep implementation aligned to SDS/OpenAPI contracts to avoid drift."];
+        : ["Keep implementation aligned to documented interfaces and dependency expectations to avoid drift."];
     return [
         `* **Task Key**: ${taskKey}`,
         "* **Objective**",
@@ -680,6 +644,51 @@ const SERVICE_PATH_CONTAINER_SEGMENTS = new Set([
     "lib",
     "src",
 ]);
+const SOURCE_LIKE_PATH_SEGMENTS = new Set([
+    "api",
+    "app",
+    "apps",
+    "bin",
+    "cmd",
+    "components",
+    "controllers",
+    "handlers",
+    "internal",
+    "lib",
+    "libs",
+    "pages",
+    "routes",
+    "screens",
+    "server",
+    "servers",
+    "spec",
+    "specs",
+    "src",
+    "test",
+    "tests",
+    "ui",
+    "web",
+]);
+const GENERIC_CONTAINER_PATH_SEGMENTS = new Set([
+    "adapters",
+    "apps",
+    "clients",
+    "consoles",
+    "domains",
+    "engines",
+    "features",
+    "modules",
+    "packages",
+    "platforms",
+    "plugins",
+    "products",
+    "servers",
+    "services",
+    "systems",
+    "tools",
+    "workers",
+]);
+const NON_RUNTIME_STRUCTURE_ROOT_SEGMENTS = new Set(["docs", "fixtures", "runbooks", "policies", "policy"]);
 const SERVICE_NAME_STOPWORDS = new Set([
     "the",
     "a",
@@ -737,10 +746,92 @@ const SERVICE_NAME_INVALID = new Set([
     "repository",
     "codebase",
 ]);
+const SERVICE_TEXT_INVALID_STARTERS = new Set([
+    "active",
+    "are",
+    "artifact",
+    "artifacts",
+    "be",
+    "been",
+    "being",
+    "block",
+    "blocks",
+    "build",
+    "builder",
+    "built",
+    "canonical",
+    "chain",
+    "configured",
+    "dedicated",
+    "deployment",
+    "discovered",
+    "failure",
+    "first",
+    "is",
+    "last",
+    "listing",
+    "mode",
+    "modes",
+    "never",
+    "no",
+    "not",
+    "ordered",
+    "owned",
+    "private",
+    "public",
+    "resolved",
+    "runtime",
+    "second",
+    "startup",
+    "third",
+    "validation",
+    "wave",
+    "waves",
+    "was",
+    "were",
+]);
+const NON_RUNTIME_SERVICE_SINGLETONS = new Set([
+    "artifact",
+    "artifacts",
+    "compose",
+    "config",
+    "configs",
+    "doc",
+    "docs",
+    "interface",
+    "interfaces",
+    "key",
+    "keys",
+    "libraries",
+    "library",
+    "pdr",
+    "read",
+    "rfp",
+    "sds",
+    "script",
+    "scripts",
+    "src",
+    "systemd",
+    "test",
+    "tests",
+    "types",
+    "write",
+]);
+const NON_RUNTIME_PATH_SERVICE_TOKENS = new Set([
+    "artifact",
+    "artifacts",
+    "manifest",
+    "manifests",
+    "schema",
+    "schemas",
+    "taxonomy",
+    "taxonomies",
+]);
 const SERVICE_LABEL_PATTERN = /\b([A-Za-z][A-Za-z0-9]*(?:[ _/-]+[A-Za-z][A-Za-z0-9]*){0,3})\s+(service|api|backend|frontend|worker|gateway|database|db|ui|client|server|adapter)\b/gi;
 const SERVICE_ARROW_PATTERN = /([A-Za-z][A-Za-z0-9 _/-]{1,80})\s*(?:->|=>|→)\s*([A-Za-z][A-Za-z0-9 _/-]{1,80})/g;
 const SERVICE_HANDLE_PATTERN = /\b((?:svc|ui|worker)-[a-z0-9-*]+)\b/gi;
 const WAVE_LABEL_PATTERN = /\bwave\s*([0-9]{1,2})\b/i;
+const TOPOLOGY_HEADING_PATTERN = /\b(service|services|component|components|module|modules|interface|interfaces|runtime|runtimes|worker|workers|client|clients|gateway|gateways|server|servers|engine|engines|pipeline|pipelines|registry|registries|adapter|adapters|processor|processors|daemon|daemons|ops|operations|deployment|deployments|topology)\b/i;
 const nextUniqueLocalId = (prefix, existing) => {
     let index = 1;
     let candidate = `${prefix}-${index}`;
@@ -763,11 +854,21 @@ const looksLikeSdsDoc = (doc) => {
         .slice(0, 5000);
     return STRICT_SDS_CONTENT_PATTERN.test(sample);
 };
+const looksLikePathishDocId = (value) => {
+    if (!value)
+        return false;
+    if (DOCDEX_LOCAL_HANDLE.test(value))
+        return false;
+    return (value.includes("/") ||
+        value.includes("\\") ||
+        FILE_EXTENSION_PATTERN.test(value) ||
+        STRICT_SDS_PATH_PATTERN.test(value.replace(/\\/g, "/").toLowerCase()));
+};
 const EPIC_SCHEMA_SNIPPET = `{
   "epics": [
     {
       "localId": "e1",
-      "area": "web|adm|bck|ops|infra|mobile",
+      "area": "documented-area-label",
       "title": "Epic title",
       "description": "Epic description using the epic template",
       "acceptanceCriteria": ["criterion"],
@@ -931,7 +1032,7 @@ export class CreateTasksService {
         if (!documents.some((doc) => looksLikeSdsDoc(doc))) {
             throw new Error("create-tasks requires at least one SDS document. Add an SDS file (for example docs/sds.md) or pass SDS paths as input.");
         }
-        return this.sortDocsForPlanning(documents);
+        return this.sortDocsForPlanning(this.dedupePlanningDocs(documents.map((doc) => this.sanitizeDocForPlanning(doc))));
     }
     normalizeDocInputForSet(input) {
         if (input.startsWith("docdex:"))
@@ -953,8 +1054,19 @@ export class CreateTasksService {
         }
         return merged;
     }
+    canonicalizeDocPathKey(value) {
+        const trimmed = `${value ?? ""}`.trim();
+        if (!trimmed || DOCDEX_LOCAL_HANDLE.test(trimmed))
+            return undefined;
+        if (path.isAbsolute(trimmed))
+            return path.resolve(trimmed).toLowerCase();
+        if (looksLikePathishDocId(trimmed)) {
+            return path.resolve(this.workspace.workspaceRoot, trimmed).toLowerCase();
+        }
+        return undefined;
+    }
     docIdentity(doc) {
-        const pathKey = `${doc.path ?? ""}`.trim().toLowerCase();
+        const pathKey = this.canonicalizeDocPathKey(doc.path) ?? this.canonicalizeDocPathKey(doc.id);
         const idKey = `${doc.id ?? ""}`.trim().toLowerCase();
         if (pathKey)
             return `path:${pathKey}`;
@@ -978,6 +1090,61 @@ export class CreateTasksService {
         }
         return merged;
     }
+    sanitizeDocForPlanning(doc) {
+        const content = stripManagedSdsPreflightBlock(doc.content);
+        const segments = content !== doc.content
+            ? []
+            : (doc.segments ?? [])
+                .map((segment) => {
+                const sanitizedContent = stripManagedSdsPreflightBlock(segment.content ?? undefined);
+                return {
+                    ...segment,
+                    content: sanitizedContent ?? segment.content,
+                };
+            })
+                .filter((segment) => `${segment.content ?? ""}`.trim().length > 0 || `${segment.heading ?? ""}`.trim().length > 0);
+        const sanitized = {
+            ...doc,
+            content: content ?? doc.content,
+            segments,
+        };
+        if (looksLikeSdsDoc(sanitized) && `${sanitized.docType ?? ""}`.toUpperCase() !== "SDS") {
+            sanitized.docType = "SDS";
+        }
+        return sanitized;
+    }
+    scorePlanningDoc(doc) {
+        const segmentCount = doc.segments?.length ?? 0;
+        const contentLength = `${doc.content ?? ""}`.length;
+        return ((looksLikeSdsDoc(doc) ? 5000 : 0) +
+            (doc.path ? 400 : 0) +
+            segmentCount * 20 +
+            Math.min(300, contentLength));
+    }
+    mergePlanningDocPair(current, incoming) {
+        const [primary, secondary] = this.scorePlanningDoc(incoming) > this.scorePlanningDoc(current) ? [incoming, current] : [current, incoming];
+        const merged = {
+            ...secondary,
+            ...primary,
+            path: primary.path ?? secondary.path,
+            title: primary.title ?? secondary.title,
+            content: primary.content ?? secondary.content,
+            segments: (primary.segments?.length ?? 0) > 0 ? primary.segments : secondary.segments,
+        };
+        if (looksLikeSdsDoc(merged) && `${merged.docType ?? ""}`.toUpperCase() !== "SDS") {
+            merged.docType = "SDS";
+        }
+        return merged;
+    }
+    dedupePlanningDocs(docs) {
+        const merged = new Map();
+        for (const doc of docs) {
+            const identity = this.docIdentity(doc);
+            const existing = merged.get(identity);
+            merged.set(identity, existing ? this.mergePlanningDocPair(existing, doc) : doc);
+        }
+        return Array.from(merged.values());
+    }
     sortDocsForPlanning(docs) {
         return [...docs].sort((a, b) => {
             const aIsSds = looksLikeSdsDoc(a) ? 0 : 1;
@@ -1158,47 +1325,29 @@ export class CreateTasksService {
             .map((entry) => entry.path);
     }
     normalizeStructurePathToken(value) {
-        const normalized = value
-            .replace(/\\/g, "/")
-            .replace(/^[./]+/, "")
-            .replace(/^\/+/, "")
-            .trim();
+        const normalized = normalizeStructuredPathToken(value);
         if (!normalized)
             return undefined;
-        if (normalized.length > 140)
-            return undefined;
-        if (!normalized.includes("/"))
-            return undefined;
-        if (normalized.includes("://"))
+        const root = normalized.split("/")[0]?.toLowerCase();
+        if (root && DOC_SCAN_IGNORE_DIRS.has(root))
             return undefined;
-        if (/[\u0000-\u001f]/.test(normalized))
-            return undefined;
-        const hadTrailingSlash = /\/$/.test(normalized);
-        const parts = normalized.split("/").filter(Boolean);
-        if (parts.length < 2 && !(hadTrailingSlash && parts.length === 1))
-            return undefined;
-        if (parts.some((part) => part === "." || part === ".."))
-            return undefined;
-        if (parts.length === 1 && !TOP_LEVEL_STRUCTURE_PATTERN.test(parts[0]))
-            return undefined;
-        if (DOC_SCAN_IGNORE_DIRS.has(parts[0].toLowerCase()))
-            return undefined;
-        return parts.join("/");
+        return normalized;
     }
     extractStructureTargets(docs) {
         const directories = new Set();
         const files = new Set();
         for (const doc of docs) {
+            const relativeDocPath = doc.path ? path.relative(this.workspace.workspaceRoot, doc.path).replace(/\\/g, "/") : undefined;
+            const localDocPath = relativeDocPath && !relativeDocPath.startsWith("..") && !path.isAbsolute(relativeDocPath)
+                ? relativeDocPath
+                : undefined;
             const segments = (doc.segments ?? []).map((segment) => segment.content).filter(Boolean).join("\n");
-            const corpus = [doc.title, doc.path, doc.content, segments].filter(Boolean).join("\n");
-            for (const match of corpus.matchAll(DOC_PATH_TOKEN_PATTERN)) {
-                const token = match[2];
-                if (!token)
-                    continue;
+            const corpus = [localDocPath, doc.content, segments].filter(Boolean).join("\n");
+            for (const token of filterImplementationStructuredPaths(extractStructuredPaths(corpus, 256))) {
                 const normalized = this.normalizeStructurePathToken(token);
                 if (!normalized)
                     continue;
-                if (FILE_EXTENSION_PATTERN.test(path.basename(normalized))) {
+                if (isStructuredFilePath(path.basename(normalized))) {
                     files.add(normalized);
                     const parent = path.dirname(normalized).replace(/\\/g, "/");
                     if (parent && parent !== ".")
@@ -1238,6 +1387,61 @@ export class CreateTasksService {
             return undefined;
         return candidate.length >= 2 ? candidate : undefined;
     }
+    normalizeTextServiceName(value) {
+        const candidate = this.normalizeServiceName(value);
+        if (!candidate)
+            return undefined;
+        const tokens = candidate.split(" ").filter(Boolean);
+        if (tokens.length === 0 || tokens.length > 3)
+            return undefined;
+        const first = tokens[0] ?? "";
+        if (SERVICE_TEXT_INVALID_STARTERS.has(first))
+            return undefined;
+        if (tokens.length === 1) {
+            if (first.length < 3)
+                return undefined;
+            if (SERVICE_NAME_INVALID.has(first) || NON_RUNTIME_SERVICE_SINGLETONS.has(first))
+                return undefined;
+            if (SERVICE_NAME_STOPWORDS.has(first))
+                return undefined;
+        }
+        return candidate;
+    }
+    isLikelyServiceContainerSegment(parts, index) {
+        const segment = parts[index];
+        if (!segment)
+            return false;
+        if (SERVICE_PATH_CONTAINER_SEGMENTS.has(segment))
+            return true;
+        if (index !== 0)
+            return false;
+        const next = parts[index + 1];
+        if (!next)
+            return false;
+        const following = parts[index + 2];
+        const nextLooksSpecific = !SERVICE_PATH_CONTAINER_SEGMENTS.has(next) &&
+            !NON_RUNTIME_STRUCTURE_ROOT_SEGMENTS.has(next) &&
+            !SOURCE_LIKE_PATH_SEGMENTS.has(next) &&
+            !isStructuredFilePath(next);
+        if (!nextLooksSpecific)
+            return false;
+        if (GENERIC_CONTAINER_PATH_SEGMENTS.has(segment)) {
+            if (!following)
+                return true;
+            return SOURCE_LIKE_PATH_SEGMENTS.has(following) || isStructuredFilePath(following);
+        }
+        return false;
+    }
+    normalizePathDerivedServiceName(value) {
+        const candidate = this.normalizeServiceName(value);
+        if (!candidate)
+            return undefined;
+        if (NON_RUNTIME_SERVICE_SINGLETONS.has(candidate))
+            return undefined;
+        if (candidate.split(" ").some((token) => NON_RUNTIME_PATH_SERVICE_TOKENS.has(token)))
+            return undefined;
+        return candidate;
+    }
     deriveServiceFromPathToken(pathToken) {
         const parts = pathToken
             .replace(/\\/g, "/")
@@ -1246,11 +1450,18 @@ export class CreateTasksService {
             .filter(Boolean);
         if (!parts.length)
             return undefined;
+        if (NON_RUNTIME_STRUCTURE_ROOT_SEGMENTS.has(parts[0] ?? ""))
+            return undefined;
+        if (parts.length === 1 && isStructuredFilePath(parts[0] ?? ""))
+            return undefined;
         let idx = 0;
-        while (idx < parts.length - 1 && SERVICE_PATH_CONTAINER_SEGMENTS.has(parts[idx])) {
+        while (idx < parts.length - 1 && this.isLikelyServiceContainerSegment(parts, idx)) {
             idx += 1;
         }
-        return this.normalizeServiceName(parts[idx] ?? parts[0]);
+        const candidate = parts[idx] ?? parts[0];
+        if (isStructuredFilePath(candidate))
+            return undefined;
+        return this.normalizePathDerivedServiceName(candidate);
     }
     addServiceAlias(aliases, rawValue) {
         const canonical = this.normalizeServiceName(rawValue);
@@ -1266,6 +1477,10 @@ export class CreateTasksService {
             .trim();
         if (alias)
             existing.add(alias);
+        if (alias.endsWith("s") && alias.length > 3)
+            existing.add(alias.slice(0, -1));
+        if (!alias.endsWith("s") && alias.length > 2)
+            existing.add(`${alias}s`);
         aliases.set(canonical, existing);
         return canonical;
     }
@@ -1275,7 +1490,7 @@ export class CreateTasksService {
         const mentions = new Set();
         for (const match of text.matchAll(SERVICE_LABEL_PATTERN)) {
             const phrase = `${match[1] ?? ""} ${match[2] ?? ""}`.trim();
-            const normalized = this.normalizeServiceName(phrase);
+            const normalized = this.normalizeTextServiceName(phrase);
             if (normalized)
                 mentions.add(normalized);
         }
@@ -1289,7 +1504,18 @@ export class CreateTasksService {
         }
         return Array.from(mentions);
     }
-    resolveServiceMentionFromPhrase(phrase, aliases) {
+    deriveServiceMentionFromPathPhrase(phrase) {
+        for (const match of phrase.matchAll(DOC_PATH_TOKEN_PATTERN)) {
+            const token = match[2];
+            if (!token)
+                continue;
+            const derived = this.deriveServiceFromPathToken(token);
+            if (derived)
+                return derived;
+        }
+        return undefined;
+    }
+    resolveServiceMentionFromPhrase(phrase, aliases, options = {}) {
         const normalizedPhrase = phrase
             .toLowerCase()
             .replace(/[._/-]+/g, " ")
@@ -1312,6 +1538,11 @@ export class CreateTasksService {
         }
         if (best)
             return best.key;
+        const pathDerived = this.deriveServiceMentionFromPathPhrase(phrase);
+        if (pathDerived)
+            return pathDerived;
+        if (!options.allowAliasRegistration)
+            return undefined;
         const mention = this.extractServiceMentionsFromText(phrase)[0];
         if (!mention)
             return undefined;
@@ -1395,10 +1626,17 @@ export class CreateTasksService {
                     resolved.add(canonical);
             }
             if (resolved.size === 0) {
-                for (const mention of this.extractServiceMentionsFromText(cell)) {
-                    const canonical = this.addServiceAlias(aliases, mention);
-                    if (canonical)
-                        resolved.add(canonical);
+                const normalizedCell = this.normalizeServiceLookupKey(cell);
+                const haystack = normalizedCell ? ` ${normalizedCell} ` : "";
+                for (const [service, names] of aliases.entries()) {
+                    for (const alias of names) {
+                        if (!alias || alias.length < 2)
+                            continue;
+                        if (!haystack.includes(` ${alias} `))
+                            continue;
+                        resolved.add(service);
+                        break;
+                    }
                 }
             }
             return Array.from(resolved);
@@ -1441,6 +1679,31 @@ export class CreateTasksService {
             for (const service of resolveServicesFromCell(cells[0]))
                 registerWave(service, waveIndex);
         }
+        for (let index = 0; index < lines.length; index += 1) {
+            const line = lines[index];
+            const waveMatch = line.match(WAVE_LABEL_PATTERN);
+            if (!waveMatch)
+                continue;
+            const waveIndex = Number.parseInt(waveMatch[1] ?? "", 10);
+            if (!Number.isFinite(waveIndex))
+                continue;
+            const contextLines = [line];
+            for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+                const next = lines[cursor];
+                if (WAVE_LABEL_PATTERN.test(next))
+                    break;
+                if (/^#{1,6}\s+/.test(next))
+                    break;
+                if (/^(?:[-*]|\d+[.)])\s+/.test(next))
+                    break;
+                contextLines.push(next);
+                if (contextLines.length >= 4)
+                    break;
+            }
+            for (const service of resolveServicesFromCell(contextLines.join(" "))) {
+                registerWave(service, waveIndex);
+            }
+        }
         const startupWaves = Array.from(startupWavesMap.entries())
             .sort((a, b) => a[0] - b[0])
             .map(([wave, services]) => ({ wave, services: Array.from(services).sort((a, b) => a.localeCompare(b)) }));
@@ -1535,15 +1798,19 @@ export class CreateTasksService {
             }
         }
         const structureTargets = this.extractStructureTargets(docs);
-        for (const token of [...structureTargets.directories, ...structureTargets.files]) {
+        const structureTokens = [...structureTargets.directories, ...structureTargets.files];
+        for (const token of structureTokens) {
+            if (!token.includes("/") &&
+                !isStructuredFilePath(path.basename(token)) &&
+                structureTokens.some((candidate) => candidate !== token && candidate.startsWith(`${token}/`))) {
+                continue;
+            }
             register(this.deriveServiceFromPathToken(token));
         }
         for (const match of docsText.matchAll(SERVICE_HANDLE_PATTERN))
             register(match[1]);
         for (const match of planText.matchAll(SERVICE_HANDLE_PATTERN))
             register(match[1]);
-        for (const mention of this.extractServiceMentionsFromText(docsText))
-            register(mention);
         for (const mention of this.extractServiceMentionsFromText(planText))
             register(mention);
         const corpus = [docsText, planText].filter(Boolean);
@@ -1570,6 +1837,65 @@ export class CreateTasksService {
             foundationalDependencies: waveHints.foundationalDependencies,
         };
     }
+    summarizeTopologySignals(docs) {
+        const structureTargets = this.extractStructureTargets(docs);
+        const structureServices = uniqueStrings([...structureTargets.directories, ...structureTargets.files]
+            .map((token) => this.deriveServiceFromPathToken(token))
+            .filter((value) => Boolean(value))).slice(0, 24);
+        const topologyHeadings = this.extractSdsSectionCandidates(docs, 64)
+            .filter((heading) => TOPOLOGY_HEADING_PATTERN.test(heading))
+            .slice(0, 24);
+        const docsText = docs
+            .map((doc) => [doc.title, doc.path, doc.content, ...(doc.segments ?? []).map((segment) => segment.content)].filter(Boolean).join("\n"))
+            .join("\n");
+        const dependencyPairs = uniqueStrings(this.collectDependencyStatements(docsText).map((statement) => `${statement.dependent} -> ${statement.dependency}`)).slice(0, 16);
+        const waveMentions = docsText
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .filter((line) => WAVE_LABEL_PATTERN.test(line))
+            .slice(0, 16);
+        return {
+            structureServices,
+            topologyHeadings,
+            dependencyPairs,
+            waveMentions,
+        };
+    }
+    validateTopologyExtraction(projectKey, docs, graph) {
+        const topologySignals = this.summarizeTopologySignals(docs);
+        const hasServiceSignals = topologySignals.structureServices.length > 0 ||
+            topologySignals.topologyHeadings.length > 0 ||
+            topologySignals.dependencyPairs.length > 0;
+        if (hasServiceSignals && graph.services.length === 0) {
+            const signalSummary = uniqueStrings([
+                ...topologySignals.structureServices.map((service) => `structure:${service}`),
+                ...topologySignals.topologyHeadings.map((heading) => `heading:${heading}`),
+                ...topologySignals.dependencyPairs.map((pair) => `dependency:${pair}`),
+            ])
+                .slice(0, 8)
+                .join("; ");
+            throw new Error(`create-tasks failed internal topology extraction for project "${projectKey}". SDS includes runtime topology signals but no services were resolved. Signals: ${signalSummary || "unavailable"}`);
+        }
+        if (topologySignals.waveMentions.length > 0 && graph.startupWaves.length === 0) {
+            throw new Error(`create-tasks failed internal topology extraction for project "${projectKey}". SDS includes startup wave signals but no startup waves were resolved. Signals: ${topologySignals.waveMentions.slice(0, 6).join("; ")}`);
+        }
+        return topologySignals;
+    }
+    derivePlanningArtifacts(projectKey, docs, plan) {
+        const discoveryGraph = this.buildServiceDependencyGraph(plan, docs);
+        const topologySignals = this.validateTopologyExtraction(projectKey, docs, discoveryGraph);
+        const serviceCatalog = this.buildServiceCatalogArtifact(projectKey, docs, discoveryGraph);
+        const projectBuildMethod = this.buildProjectConstructionMethod(docs, discoveryGraph);
+        const projectBuildPlan = this.buildProjectPlanArtifact(projectKey, docs, discoveryGraph, projectBuildMethod);
+        return {
+            discoveryGraph,
+            topologySignals,
+            serviceCatalog,
+            projectBuildMethod,
+            projectBuildPlan,
+        };
+    }
     normalizeServiceId(value) {
         const normalizedName = this.normalizeServiceName(value);
         if (!normalizedName)
@@ -1667,6 +1993,7 @@ export class CreateTasksService {
         const sourceDocs = docs
             .map((doc) => doc.path ?? (doc.id ? `docdex:${doc.id}` : doc.title ?? "doc"))
             .filter((value) => Boolean(value))
+            .filter((value, index, items) => items.indexOf(value) === index)
             .slice(0, 24);
         return {
             projectKey,
@@ -1889,8 +2216,16 @@ export class CreateTasksService {
     buildProjectConstructionMethod(docs, graph) {
         const toLabel = (value) => value.replace(/\s+/g, "-");
         const structureTargets = this.extractStructureTargets(docs);
-        const topDirectories = structureTargets.directories.slice(0, 10);
-        const topFiles = structureTargets.files.slice(0, 10);
+        const sourceDocPaths = new Set(docs
+            .map((doc) => (doc.path ? path.relative(this.workspace.workspaceRoot, doc.path).replace(/\\/g, "/") : undefined))
+            .filter((value) => Boolean(value)));
+        const sourceDocDirectories = new Set(Array.from(sourceDocPaths)
+            .map((docPath) => path.posix.dirname(docPath))
+            .filter((dir) => dir && dir !== "."));
+        const buildDirectories = structureTargets.directories.filter((dir) => !sourceDocDirectories.has(dir));
+        const buildFiles = structureTargets.files.filter((file) => !sourceDocPaths.has(file));
+        const topDirectories = (buildDirectories.length > 0 ? buildDirectories : structureTargets.directories).slice(0, 10);
+        const topFiles = (buildFiles.length > 0 ? buildFiles : structureTargets.files).slice(0, 10);
         const startupWaveLines = graph.startupWaves
             .slice(0, 8)
             .map((wave) => `- Wave ${wave.wave}: ${wave.services.map(toLabel).join(", ")}`);
@@ -1915,7 +2250,9 @@ export class CreateTasksService {
             ...(graph.foundationalDependencies.length > 0
                 ? graph.foundationalDependencies.map((dependency) => `   - foundation: ${dependency}`)
                 : ["   - foundation: infer runtime prerequisites from SDS deployment sections"]),
-            ...(startupWaveLines.length > 0 ? startupWaveLines : ["   - startup waves: infer from dependency contracts"]),
+            ...(startupWaveLines.length > 0
+                ? startupWaveLines
+                : ["   - startup waves: infer from documented dependency constraints"]),
             "3) Implement services by dependency direction and startup wave.",
             `   - service order: ${serviceOrderLine}`,
             ...(dependencyPairs.length > 0
@@ -1929,6 +2266,7 @@ export class CreateTasksService {
         const sourceDocs = docs
             .map((doc) => doc.path ?? (doc.id ? `docdex:${doc.id}` : doc.title ?? "doc"))
             .filter((value) => Boolean(value))
+            .filter((value, index, items) => items.indexOf(value) === index)
             .slice(0, 24);
         return {
             projectKey,
@@ -2202,7 +2540,7 @@ export class CreateTasksService {
             .slice(0, 12);
         const bootstrapEpic = {
             localId: epicLocalId,
-            area: normalizeArea(projectKey) ?? "infra",
+            area: normalizeArea(projectKey) ?? "core",
             title: "Codebase Foundation and Structure Setup",
             description: "Create the SDS-defined codebase scaffold first (folders/files/service boundaries) before feature implementation tasks.",
             acceptanceCriteria: [
@@ -2564,17 +2902,32 @@ export class CreateTasksService {
         for (const doc of docs) {
             if (!looksLikeSdsDoc(doc))
                 continue;
+            const scanLimit = Math.max(limit * 4, limit + 12);
+            const contentHeadings = collectSdsImplementationSignals(doc.content ?? "", {
+                headingLimit: scanLimit,
+                folderLimit: 0,
+            }).sectionHeadings;
             const segmentHeadings = (doc.segments ?? [])
-                .map((segment) => segment.heading?.trim())
+                .map((segment) => normalizeHeadingCandidate(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, ...segmentContentHeadings, ...contentHeadings]) {
-                const normalized = heading.replace(/[`*_]/g, "").trim();
+                .flatMap((segment) => collectSdsImplementationSignals(segment.content ?? "", {
+                headingLimit: Math.max(12, Math.ceil(scanLimit / 2)),
+                folderLimit: 0,
+            }).sectionHeadings)
+                .slice(0, scanLimit);
+            for (const heading of uniqueStrings([...contentHeadings, ...segmentHeadings, ...segmentContentHeadings])) {
+                const normalized = normalizeHeadingCandidate(heading);
                 if (!normalized)
                     continue;
+                if (!headingLooksImplementationRelevant(normalized))
+                    continue;
+                if (/^software design specification$/i.test(normalized))
+                    continue;
+                if (/^(?:\d+(?:\.\d+)*\.?\s*)?roles$/i.test(normalized))
+                    continue;
+                if (sections.includes(normalized))
+                    continue;
                 sections.push(normalized);
                 if (sections.length >= limit)
                     break;
@@ -2654,8 +3007,7 @@ export class CreateTasksService {
         }
         return { docSummary: blocks.join("\n\n") || "(no docs)", warnings };
     }
-    buildPrompt(projectKey, docs, projectBuildMethod, serviceCatalog, options) {
-        const docSummary = docs.map((doc, idx) => describeDoc(doc, idx)).join("\n");
+    buildPrompt(projectKey, docSummary, projectBuildMethod, serviceCatalog, options) {
         const serviceCatalogSummary = this.buildServiceCatalogPromptSummary(serviceCatalog);
         const limits = [
             options.maxEpics ? `Limit epics to ${options.maxEpics}.` : "",
@@ -2677,6 +3029,8 @@ export class CreateTasksService {
             "- 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.",
+            "- Use canonical documented names for modules, services, interfaces, commands, schemas, and files exactly as they appear in Docs and the project construction method.",
+            "- Do not rename explicit documented targets or replace them with invented alternatives.",
             "- serviceIds is required and must contain one or more ids from the phase-0 service catalog below.",
             `- If an epic spans multiple services, include tag \"${CROSS_SERVICE_TAG}\" in tags.`,
             "Project construction method to follow:",
@@ -2727,9 +3081,9 @@ export class CreateTasksService {
                                 },
                                 {
                                     localId: "task-2",
-                                    title: "Integrate core contracts and dependencies",
+                                    title: "Integrate core dependencies and interfaces",
                                     type: "feature",
-                                    description: "Wire key contracts/interfaces and dependency paths so core behavior can execute end-to-end.",
+                                    description: "Wire key dependencies, interfaces, and integration paths so core behavior can execute end-to-end.",
                                     estimatedStoryPoints: 3,
                                     priorityHint: 20,
                                     dependsOnKeys: ["task-1"],
@@ -3000,6 +3354,7 @@ export class CreateTasksService {
             "- 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.",
+            "- Preserve canonical documented names for modules, services, interfaces, commands, schemas, and files exactly as written.",
             `Epic context (key=${epic.key ?? epic.localId ?? "TBD"}):`,
             epic.description ?? "(no description provided)",
             `Epic serviceIds: ${(epic.serviceIds ?? []).join(", ") || "(not provided)"}`,
@@ -3058,6 +3413,7 @@ export class CreateTasksService {
             "- 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.",
+            "- Preserve canonical documented names for modules, services, interfaces, commands, schemas, and files exactly as written.",
             "- 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.",
@@ -3157,11 +3513,11 @@ export class CreateTasksService {
             },
             {
                 localId: "t-fallback-2",
-                title: `Integrate contracts for ${story.title}`,
+                title: `Integrate dependencies for ${story.title}`,
                 type: "feature",
                 description: [
-                    `Integrate dependent contracts/interfaces for "${story.title}" after core scope implementation.`,
-                    "Align internal/external interfaces, data contracts, and dependency wiring with SDS/OpenAPI context.",
+                    `Integrate dependent interfaces and runtime dependencies for "${story.title}" after core scope implementation.`,
+                    "Align internal/external interfaces, data shapes, and dependency wiring with the documented context.",
                     "Record dependency rationale and compatibility constraints in the task output.",
                 ].join("\n"),
                 estimatedStoryPoints: 3,
@@ -3261,50 +3617,99 @@ export class CreateTasksService {
         }
         return { epics: planEpics, stories: planStories, tasks: planTasks };
     }
-    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([
+    buildCoverageCorpus(plan) {
+        return normalizeCoverageText([
             ...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);
+    }
+    collectCoverageAnchorsFromBacklog(backlog) {
+        const anchors = new Set();
+        for (const task of backlog.tasks) {
+            const sufficiencyAudit = task.metadata?.sufficiencyAudit;
+            const anchor = typeof sufficiencyAudit?.anchor === "string" ? sufficiencyAudit.anchor.trim() : "";
+            if (anchor)
+                anchors.add(anchor);
+            if (Array.isArray(sufficiencyAudit?.anchors)) {
+                for (const value of sufficiencyAudit.anchors) {
+                    if (typeof value !== "string" || value.trim().length === 0)
+                        continue;
+                    anchors.add(value.trim());
+                }
             }
-            else {
-                unmatched.push(section);
+        }
+        return anchors;
+    }
+    assertCoverageConsistency(projectKey, report, expected) {
+        const sort = (values) => [...values].sort((left, right) => left.localeCompare(right));
+        const sameSectionGaps = JSON.stringify(sort(report.missingSectionHeadings)) === JSON.stringify(sort(expected.missingSectionHeadings));
+        const sameFolderGaps = JSON.stringify(sort(report.missingFolderEntries)) === JSON.stringify(sort(expected.missingFolderEntries));
+        if (report.totalSignals !== expected.totalSignals ||
+            report.coverageRatio !== expected.coverageRatio ||
+            !sameSectionGaps ||
+            !sameFolderGaps) {
+            throw new Error(`create-tasks produced inconsistent coverage artifacts for project "${projectKey}". coverage-report.json diverged from task sufficiency coverage.`);
+        }
+    }
+    async loadExpectedCoverageFromSufficiencyReport(reportPath) {
+        if (!reportPath)
+            return undefined;
+        try {
+            const raw = await fs.readFile(reportPath, "utf8");
+            const parsed = JSON.parse(raw);
+            const finalCoverage = parsed.finalCoverage;
+            if (!finalCoverage)
+                return undefined;
+            if (typeof finalCoverage.coverageRatio !== "number" ||
+                typeof finalCoverage.totalSignals !== "number" ||
+                !Array.isArray(finalCoverage.missingSectionHeadings) ||
+                !Array.isArray(finalCoverage.missingFolderEntries)) {
+                return undefined;
             }
+            return {
+                coverageRatio: finalCoverage.coverageRatio,
+                totalSignals: finalCoverage.totalSignals,
+                missingSectionHeadings: finalCoverage.missingSectionHeadings.filter((value) => typeof value === "string"),
+                missingFolderEntries: finalCoverage.missingFolderEntries.filter((value) => typeof value === "string"),
+            };
+        }
+        catch {
+            return undefined;
         }
-        const totalSections = matched.length + unmatched.length;
-        const coverageRatio = totalSections === 0 ? 1 : matched.length / totalSections;
+    }
+    buildSdsCoverageReport(projectKey, docs, plan, existingAnchors = new Set()) {
+        const coverageSignals = collectSdsCoverageSignalsFromDocs(docs, {
+            headingLimit: SDS_COVERAGE_REPORT_SECTION_LIMIT,
+            folderLimit: SDS_COVERAGE_REPORT_FOLDER_LIMIT,
+        });
+        const coverage = evaluateSdsCoverage(this.buildCoverageCorpus(plan), {
+            sectionHeadings: coverageSignals.sectionHeadings,
+            folderEntries: coverageSignals.folderEntries,
+        }, existingAnchors);
+        const matchedSections = coverageSignals.sectionHeadings.filter((heading) => !coverage.missingSectionHeadings.includes(heading));
+        const matchedFolderEntries = coverageSignals.folderEntries.filter((entry) => !coverage.missingFolderEntries.includes(entry));
         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."],
+            totalSignals: coverage.totalSignals,
+            totalSections: coverageSignals.sectionHeadings.length,
+            totalFolderEntries: coverageSignals.folderEntries.length,
+            rawSectionSignals: coverageSignals.rawSectionHeadings.length,
+            rawFolderSignals: coverageSignals.rawFolderEntries.length,
+            skippedHeadingSignals: coverageSignals.skippedHeadingSignals,
+            skippedFolderSignals: coverageSignals.skippedFolderSignals,
+            matched: matchedSections,
+            unmatched: coverage.missingSectionHeadings,
+            matchedSections,
+            missingSectionHeadings: coverage.missingSectionHeadings,
+            matchedFolderEntries,
+            missingFolderEntries: coverage.missingFolderEntries,
+            existingAnchorsCount: existingAnchors.size,
+            coverageRatio: coverage.coverageRatio,
+            notes: coverage.totalSignals === 0
+                ? ["No actionable SDS implementation signals detected; coverage defaults to 1.0."]
+                : ["Coverage uses the same heading and folder signal model as task-sufficiency-audit."],
         };
     }
     async acquirePlanArtifactLock(baseDir, options) {
@@ -3365,7 +3770,166 @@ export class CreateTasksService {
             }
         }
     }
-    async writePlanArtifacts(projectKey, plan, docSummary, docs, buildPlan, serviceCatalog) {
+    splitPersistedAcceptanceCriteria(value) {
+        if (!value)
+            return [];
+        return uniqueStrings(value
+            .split(/\r?\n/)
+            .map((line) => line.replace(/^[-*]\s+/, "").trim())
+            .filter(Boolean));
+    }
+    async loadPersistedBacklog(projectId) {
+        const repoLike = this.workspaceRepo;
+        if (typeof repoLike.getDb !== "function") {
+            const epics = Array.isArray(repoLike.epics)
+                ? repoLike.epics.filter((row) => row.projectId === projectId)
+                : [];
+            const stories = Array.isArray(repoLike.stories)
+                ? repoLike.stories.filter((row) => row.projectId === projectId)
+                : [];
+            const tasks = Array.isArray(repoLike.tasks)
+                ? repoLike.tasks.filter((row) => row.projectId === projectId)
+                : [];
+            const taskIds = new Set(tasks.map((task) => task.id));
+            const dependencies = Array.isArray(repoLike.deps)
+                ? repoLike.deps.filter((row) => taskIds.has(row.taskId))
+                : [];
+            return { epics, stories, tasks, dependencies };
+        }
+        const db = repoLike.getDb();
+        const epicRows = await db.all(`SELECT id, project_id, key, title, description, story_points_total, priority, metadata_json, created_at, updated_at
+       FROM epics
+       WHERE project_id = ?
+       ORDER BY COALESCE(priority, 2147483647), datetime(created_at), key`, projectId);
+        const storyRows = await db.all(`SELECT id, project_id, epic_id, key, title, description, acceptance_criteria, story_points_total, priority, metadata_json, created_at, updated_at
+       FROM user_stories
+       WHERE project_id = ?
+       ORDER BY COALESCE(priority, 2147483647), datetime(created_at), key`, projectId);
+        const taskRows = await db.all(`SELECT id, project_id, epic_id, user_story_id, key, title, description, type, status, story_points, priority,
+              assigned_agent_id, assignee_human, vcs_branch, vcs_base_branch, vcs_last_commit_sha, metadata_json,
+              openapi_version_at_creation, created_at, updated_at
+       FROM tasks
+       WHERE project_id = ?
+       ORDER BY COALESCE(priority, 2147483647), datetime(created_at), key`, projectId);
+        const epics = epicRows.map((row) => ({
+            id: row.id,
+            projectId: row.project_id,
+            key: row.key,
+            title: row.title,
+            description: row.description,
+            storyPointsTotal: row.story_points_total ?? null,
+            priority: row.priority ?? null,
+            metadata: row.metadata_json ? JSON.parse(row.metadata_json) : undefined,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        }));
+        const stories = storyRows.map((row) => ({
+            id: row.id,
+            projectId: row.project_id,
+            epicId: row.epic_id,
+            key: row.key,
+            title: row.title,
+            description: row.description,
+            acceptanceCriteria: row.acceptance_criteria ?? null,
+            storyPointsTotal: row.story_points_total ?? null,
+            priority: row.priority ?? null,
+            metadata: row.metadata_json ? JSON.parse(row.metadata_json) : undefined,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        }));
+        const tasks = taskRows.map((row) => ({
+            id: row.id,
+            projectId: row.project_id,
+            epicId: row.epic_id,
+            userStoryId: row.user_story_id,
+            key: row.key,
+            title: row.title,
+            description: row.description,
+            type: row.type ?? null,
+            status: row.status,
+            storyPoints: row.story_points ?? null,
+            priority: row.priority ?? null,
+            assignedAgentId: row.assigned_agent_id ?? null,
+            assigneeHuman: row.assignee_human ?? null,
+            vcsBranch: row.vcs_branch ?? null,
+            vcsBaseBranch: row.vcs_base_branch ?? null,
+            vcsLastCommitSha: row.vcs_last_commit_sha ?? null,
+            metadata: row.metadata_json ? JSON.parse(row.metadata_json) : undefined,
+            openapiVersionAtCreation: row.openapi_version_at_creation ?? null,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        }));
+        const dependencies = typeof repoLike.getTaskDependencies === "function"
+            ? await repoLike.getTaskDependencies(tasks.map((task) => task.id))
+            : [];
+        return { epics, stories, tasks, dependencies };
+    }
+    buildPlanFromPersistedBacklog(backlog) {
+        const storyById = new Map(backlog.stories.map((story) => [story.id, story]));
+        const epicById = new Map(backlog.epics.map((epic) => [epic.id, epic]));
+        const taskById = new Map(backlog.tasks.map((task) => [task.id, task]));
+        const dependencyKeysByTaskId = new Map();
+        for (const dependency of backlog.dependencies) {
+            const current = dependencyKeysByTaskId.get(dependency.taskId) ?? [];
+            const dependsOn = taskById.get(dependency.dependsOnTaskId)?.key;
+            if (dependsOn && !current.includes(dependsOn))
+                current.push(dependsOn);
+            dependencyKeysByTaskId.set(dependency.taskId, current);
+        }
+        return {
+            epics: backlog.epics.map((epic) => {
+                const metadata = (epic.metadata ?? {});
+                return {
+                    localId: epic.key,
+                    area: epic.key.split("-")[0]?.toLowerCase() || "proj",
+                    title: epic.title,
+                    description: epic.description,
+                    acceptanceCriteria: [],
+                    relatedDocs: normalizeRelatedDocs(metadata.doc_links),
+                    priorityHint: epic.priority ?? undefined,
+                    serviceIds: normalizeStringArray(metadata.service_ids),
+                    tags: normalizeStringArray(metadata.tags),
+                    stories: [],
+                };
+            }),
+            stories: backlog.stories.map((story) => {
+                const metadata = (story.metadata ?? {});
+                return {
+                    localId: story.key,
+                    epicLocalId: epicById.get(story.epicId)?.key ?? story.epicId,
+                    title: story.title,
+                    userStory: undefined,
+                    description: story.description,
+                    acceptanceCriteria: this.splitPersistedAcceptanceCriteria(story.acceptanceCriteria),
+                    relatedDocs: normalizeRelatedDocs(metadata.doc_links),
+                    priorityHint: story.priority ?? undefined,
+                    tasks: [],
+                };
+            }),
+            tasks: backlog.tasks.map((task) => {
+                const metadata = (task.metadata ?? {});
+                const testRequirements = (metadata.test_requirements ?? {});
+                return {
+                    localId: task.key,
+                    epicLocalId: epicById.get(task.epicId)?.key ?? task.epicId,
+                    storyLocalId: storyById.get(task.userStoryId)?.key ?? task.userStoryId,
+                    title: task.title,
+                    type: task.type ?? "feature",
+                    description: task.description,
+                    estimatedStoryPoints: task.storyPoints ?? undefined,
+                    priorityHint: task.priority ?? undefined,
+                    dependsOnKeys: dependencyKeysByTaskId.get(task.id) ?? [],
+                    relatedDocs: normalizeRelatedDocs(metadata.doc_links),
+                    unitTests: normalizeStringArray(testRequirements.unit),
+                    componentTests: normalizeStringArray(testRequirements.component),
+                    integrationTests: normalizeStringArray(testRequirements.integration),
+                    apiTests: normalizeStringArray(testRequirements.api),
+                    qa: isPlainObject(metadata.qa) ? metadata.qa : undefined,
+                };
+            }),
+        };
+    }
+    async writePlanArtifacts(projectKey, plan, docSummary, docs, buildPlan, serviceCatalog, options) {
         const baseDir = path.join(this.workspace.mcodaDir, "tasks", projectKey);
         await fs.mkdir(baseDir, { recursive: true });
         const releaseLock = await this.acquirePlanArtifactLock(baseDir);
@@ -3387,7 +3951,11 @@ 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));
+            const coverageReport = this.buildSdsCoverageReport(projectKey, docs, plan, options?.existingCoverageAnchors ?? new Set());
+            if (options?.expectedCoverage) {
+                this.assertCoverageConsistency(projectKey, coverageReport, options.expectedCoverage);
+            }
+            await write("coverage-report.json", coverageReport);
         }
         finally {
             await releaseLock();
@@ -3656,6 +4224,8 @@ export class CreateTasksService {
                 });
                 let sdsPreflight;
                 let sdsPreflightError;
+                let sdsPreflightBlockingReasons = [];
+                let continueAfterSdsPreflightWarnings = false;
                 if (this.sdsPreflightFactory) {
                     let sdsPreflightCloseError;
                     try {
@@ -3667,7 +4237,7 @@ export class CreateTasksService {
                                 inputPaths: options.inputs,
                                 sdsPaths: options.inputs,
                                 writeArtifacts: true,
-                                applyToSds: true,
+                                applyToSds: options.sdsPreflightApplyToSds === true,
                                 commitAppliedChanges: options.sdsPreflightCommit === true,
                                 commitMessage: options.sdsPreflightCommitMessage,
                             });
@@ -3727,12 +4297,15 @@ export class CreateTasksService {
                     }
                     if (blockingReasons.length > 0) {
                         sdsPreflightError = blockingReasons.join(" ");
+                        sdsPreflightBlockingReasons = [...blockingReasons];
+                        continueAfterSdsPreflightWarnings = true;
+                        await this.jobService.appendLog(job.id, `SDS preflight reported planning warnings but create-tasks will continue with remediation context: ${blockingReasons.join(" ")} Report: ${sdsPreflight.reportPath}\n`);
                     }
                     await this.jobService.writeCheckpoint(job.id, {
                         stage: "sds_preflight",
                         timestamp: new Date().toISOString(),
                         details: {
-                            status: blockingReasons.length > 0 ? "blocked" : "succeeded",
+                            status: blockingReasons.length > 0 ? "continued_with_warnings" : "succeeded",
                             error: sdsPreflightError,
                             readyForPlanning: sdsPreflight.readyForPlanning,
                             qualityStatus: sdsPreflight.qualityStatus,
@@ -3747,28 +4320,37 @@ export class CreateTasksService {
                             appliedToSds: sdsPreflight.appliedToSds,
                             appliedSdsCount: sdsPreflight.appliedSdsPaths.length,
                             commitHash: sdsPreflight.commitHash,
+                            blockingReasons,
+                            continuedWithWarnings: continueAfterSdsPreflightWarnings,
                             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 preflightGeneratedDocInputs = sdsPreflight && (!sdsPreflight.appliedToSds || continueAfterSdsPreflightWarnings)
+                    ? sdsPreflight.generatedDocPaths
+                    : [];
+                const preflightDocInputs = this.mergeDocInputs(options.inputs, sdsPreflight ? [...sdsPreflight.sourceSdsPaths, ...preflightGeneratedDocInputs] : []);
                 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 serviceCatalog = this.buildServiceCatalogArtifact(options.projectKey, docs, discoveryGraph);
-                const projectBuildMethod = this.buildProjectConstructionMethod(docs, discoveryGraph);
-                const projectBuildPlan = this.buildProjectPlanArtifact(options.projectKey, docs, discoveryGraph, projectBuildMethod);
-                const { prompt } = this.buildPrompt(options.projectKey, docs, projectBuildMethod, serviceCatalog, options);
+                const initialArtifacts = this.derivePlanningArtifacts(options.projectKey, docs, { epics: [], stories: [], tasks: [] });
+                const { discoveryGraph, topologySignals, serviceCatalog, projectBuildMethod, projectBuildPlan } = initialArtifacts;
+                const { prompt } = this.buildPrompt(options.projectKey, docSummary, projectBuildMethod, serviceCatalog, options);
                 const qaPreflight = await this.buildQaPreflight();
                 const qaOverrides = this.buildQaOverrides(options);
                 await this.jobService.writeCheckpoint(job.id, {
                     stage: "docs_indexed",
                     timestamp: new Date().toISOString(),
-                    details: { count: docs.length, warnings: docWarnings, startupWaves: discoveryGraph.startupWaves.slice(0, 8) },
+                    details: {
+                        count: docs.length,
+                        warnings: docWarnings,
+                        startupWaves: discoveryGraph.startupWaves.slice(0, 8),
+                        topologySignals: {
+                            structureServices: topologySignals.structureServices.slice(0, 8),
+                            topologyHeadings: topologySignals.topologyHeadings.slice(0, 8),
+                            waveMentions: topologySignals.waveMentions.slice(0, 4),
+                        },
+                    },
                 });
                 await this.jobService.writeCheckpoint(job.id, {
                     stage: "build_plan_defined",
@@ -3965,12 +4547,37 @@ export class CreateTasksService {
                         throw new Error(`create-tasks blocked: task sufficiency audit did not reach full coverage. Report: ${sufficiencyAudit.reportPath}`);
                     }
                 }
+                if ((sufficiencyAudit?.totalTasksAdded ?? 0) > 0) {
+                    await this.seedPriorities(options.projectKey);
+                }
+                const finalBacklog = await this.loadPersistedBacklog(project.id);
+                const finalPlan = this.buildPlanFromPersistedBacklog(finalBacklog);
+                const finalArtifacts = this.derivePlanningArtifacts(options.projectKey, docs, finalPlan);
+                const finalCoverageAnchors = this.collectCoverageAnchorsFromBacklog(finalBacklog);
+                const expectedCoverage = await this.loadExpectedCoverageFromSufficiencyReport(sufficiencyAudit?.reportPath);
+                await this.writePlanArtifacts(options.projectKey, finalPlan, docSummary, docs, finalArtifacts.projectBuildPlan, finalArtifacts.serviceCatalog, {
+                    existingCoverageAnchors: finalCoverageAnchors,
+                    expectedCoverage,
+                });
+                await this.jobService.writeCheckpoint(job.id, {
+                    stage: "plan_refreshed",
+                    timestamp: new Date().toISOString(),
+                    details: {
+                        folder,
+                        epics: finalBacklog.epics.length,
+                        stories: finalBacklog.stories.length,
+                        tasks: finalBacklog.tasks.length,
+                        dependencies: finalBacklog.dependencies.length,
+                        services: finalArtifacts.serviceCatalog.services.length,
+                        startupWaves: finalArtifacts.projectBuildPlan.startupWaves.length,
+                    },
+                });
                 await this.jobService.updateJobStatus(job.id, "completed", {
                     payload: {
-                        epicsCreated: epicRows.length,
-                        storiesCreated: storyRows.length,
-                        tasksCreated: taskRows.length,
-                        dependenciesCreated: dependencyRows.length,
+                        epicsCreated: finalBacklog.epics.length,
+                        storiesCreated: finalBacklog.stories.length,
+                        tasksCreated: finalBacklog.tasks.length,
+                        dependenciesCreated: finalBacklog.dependencies.length,
                         docs: docSummary,
                         planFolder: folder,
                         planSource,
@@ -3990,6 +4597,8 @@ export class CreateTasksService {
                                 reportPath: sdsPreflight.reportPath,
                                 openQuestionsPath: sdsPreflight.openQuestionsPath,
                                 gapAddendumPath: sdsPreflight.gapAddendumPath,
+                                blockingReasons: sdsPreflightBlockingReasons,
+                                continuedWithWarnings: continueAfterSdsPreflightWarnings,
                                 warnings: sdsPreflight.warnings,
                             }
                             : undefined,
@@ -4037,10 +4646,10 @@ export class CreateTasksService {
                 return {
                     jobId: job.id,
                     commandRunId: commandRun.id,
-                    epics: epicRows,
-                    stories: storyRows,
-                    tasks: taskRows,
-                    dependencies: dependencyRows,
+                    epics: finalBacklog.epics,
+                    stories: finalBacklog.stories,
+                    tasks: finalBacklog.tasks,
+                    dependencies: finalBacklog.dependencies,
                 };
             }
             catch (error) {