@mcoda/core 0.1.33 → 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,8 +173,9 @@ 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";
 const inferDocType = (filePath) => {
     const name = path.basename(filePath).toLowerCase();
     if (name.includes("openapi") || name.includes("swagger"))
@@ -187,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")
@@ -212,6 +212,17 @@ const normalizeTaskType = (value) => {
     }
     return undefined;
 };
+const normalizeEpicServicePolicy = (value) => {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (!VALID_EPIC_SERVICE_POLICIES.has(normalized))
+        return undefined;
+    return normalized;
+};
+const normalizeEpicTags = (value) => uniqueStrings(normalizeStringArray(value)
+    .map((item) => item.toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_+|_+$/g, ""))
+    .filter(Boolean));
 const normalizeRelatedDocs = (value) => {
     if (!Array.isArray(value))
         return [];
@@ -239,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 [];
@@ -561,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 = [
@@ -573,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**",
@@ -667,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",
@@ -724,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}`;
@@ -750,16 +854,28 @@ 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"],
       "relatedDocs": ["docdex:..."],
-      "priorityHint": 50
+      "priorityHint": 50,
+      "serviceIds": ["backend-api"],
+      "tags": ["cross_service"]
     }
   ]
 }`;
@@ -916,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:"))
@@ -938,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}`;
@@ -963,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;
@@ -1143,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("://"))
-            return undefined;
-        if (/[\u0000-\u001f]/.test(normalized))
+        const root = normalized.split("/")[0]?.toLowerCase();
+        if (root && DOC_SCAN_IGNORE_DIRS.has(root))
             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 !== ".")
@@ -1223,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, "/")
@@ -1231,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);
@@ -1251,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;
     }
@@ -1260,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);
         }
@@ -1274,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, " ")
@@ -1297,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;
@@ -1380,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);
@@ -1426,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)) }));
@@ -1514,16 +1792,25 @@ export class CreateTasksService {
             ...plan.stories.map((story) => `${story.title}\n${story.description ?? ""}\n${story.userStory ?? ""}`),
             ...plan.tasks.map((task) => `${task.title}\n${task.description ?? ""}`),
         ].join("\n");
+        for (const epic of plan.epics) {
+            for (const serviceId of normalizeStringArray(epic.serviceIds)) {
+                register(serviceId);
+            }
+        }
         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);
@@ -1550,11 +1837,395 @@ 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)
+            return undefined;
+        const slug = normalizedName
+            .replace(/\s+/g, "-")
+            .replace(/[^a-z0-9-]+/g, "-")
+            .replace(/-+/g, "-")
+            .replace(/^-+|-+$/g, "");
+        if (!slug)
+            return undefined;
+        return /^[a-z]/.test(slug) ? slug : `svc-${slug}`;
+    }
+    normalizeServiceLookupKey(value) {
+        return value
+            .toLowerCase()
+            .replace(/[`"'()[\]{}]/g, " ")
+            .replace(/[._/-]+/g, " ")
+            .replace(/[^a-z0-9\s]+/g, " ")
+            .replace(/\s+/g, " ")
+            .trim();
+    }
+    createUniqueServiceId(baseId, used) {
+        if (!used.has(baseId)) {
+            used.add(baseId);
+            return baseId;
+        }
+        let suffix = 2;
+        while (used.has(`${baseId}-${suffix}`))
+            suffix += 1;
+        const next = `${baseId}-${suffix}`;
+        used.add(next);
+        return next;
+    }
+    buildServiceCatalogArtifact(projectKey, docs, graph) {
+        const serviceNames = new Set(graph.services);
+        for (const [dependent, dependencies] of graph.dependencies.entries()) {
+            serviceNames.add(dependent);
+            for (const dependency of dependencies)
+                serviceNames.add(dependency);
+        }
+        for (const foundation of graph.foundationalDependencies) {
+            const normalized = this.normalizeServiceName(foundation);
+            if (normalized)
+                serviceNames.add(normalized);
+        }
+        const orderedNames = [
+            ...graph.services,
+            ...Array.from(serviceNames)
+                .filter((name) => !graph.services.includes(name))
+                .sort((a, b) => a.localeCompare(b)),
+        ];
+        const usedServiceIds = new Set();
+        const serviceIdByName = new Map();
+        for (const name of orderedNames) {
+            const baseId = this.normalizeServiceId(name);
+            if (!baseId)
+                continue;
+            serviceIdByName.set(name, this.createUniqueServiceId(baseId, usedServiceIds));
+        }
+        const services = [];
+        for (const name of orderedNames) {
+            const id = serviceIdByName.get(name);
+            if (!id)
+                continue;
+            const aliases = uniqueStrings([
+                name,
+                ...(graph.aliases.get(name) ? Array.from(graph.aliases.get(name) ?? []) : []),
+            ]).sort((a, b) => a.localeCompare(b));
+            const dependencyNames = Array.from(graph.dependencies.get(name) ?? []);
+            const dependsOnServiceIds = uniqueStrings(dependencyNames
+                .map((dependency) => serviceIdByName.get(dependency))
+                .filter((value) => Boolean(value)));
+            const startupWave = graph.waveRank.get(name);
+            const wave = typeof startupWave === "number" && Number.isFinite(startupWave) ? startupWave : undefined;
+            services.push({
+                id,
+                name,
+                aliases,
+                startupWave: wave,
+                dependsOnServiceIds,
+                isFoundational: graph.foundationalDependencies.some((foundation) => this.normalizeServiceName(foundation) === name || this.normalizeServiceId(foundation) === id) || dependsOnServiceIds.length === 0,
+            });
+        }
+        if (services.length === 0) {
+            const fallbackServiceId = this.normalizeServiceId(`${projectKey} core`) ?? `${projectKey}-core`;
+            services.push({
+                id: fallbackServiceId,
+                name: `${projectKey} core`,
+                aliases: uniqueStrings([`${projectKey} core`, projectKey, "core"]),
+                dependsOnServiceIds: [],
+                isFoundational: true,
+            });
+        }
+        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,
+            generatedAt: new Date().toISOString(),
+            sourceDocs,
+            services,
+        };
+    }
+    buildServiceCatalogPromptSummary(catalog) {
+        if (!catalog.services.length) {
+            return "- No services detected. Infer services from SDS and ensure every epic includes at least one service id.";
+        }
+        const allIds = catalog.services.map((service) => service.id);
+        const idChunks = [];
+        for (let index = 0; index < allIds.length; index += 12) {
+            idChunks.push(allIds.slice(index, index + 12).join(", "));
+        }
+        const detailLimit = Math.min(catalog.services.length, 40);
+        const detailLines = catalog.services.slice(0, detailLimit).map((service) => {
+            const deps = service.dependsOnServiceIds.length > 0 ? service.dependsOnServiceIds.join(", ") : "none";
+            const wave = typeof service.startupWave === "number" ? `wave=${service.startupWave}` : "wave=unspecified";
+            return `- ${service.id} (${wave}; deps: ${deps}; aliases: ${service.aliases.slice(0, 5).join(", ")})`;
+        });
+        if (catalog.services.length > detailLimit) {
+            detailLines.push(`- ${catalog.services.length - detailLimit} additional services omitted from detailed lines (still listed in allowed serviceIds).`);
+        }
+        return [`- Allowed serviceIds (${allIds.length}):`, ...idChunks.map((chunk) => `  ${chunk}`), "- Service details:", ...detailLines].join("\n");
+    }
+    alignEpicsToServiceCatalog(epics, catalog, policy) {
+        const warnings = [];
+        const validServiceIds = new Set(catalog.services.map((service) => service.id));
+        const serviceOrder = new Map(catalog.services.map((service, index) => [service.id, index]));
+        const aliasToIds = new Map();
+        const idLookup = new Map();
+        const registerAlias = (rawValue, serviceId) => {
+            const normalized = this.normalizeServiceLookupKey(rawValue);
+            if (!normalized)
+                return;
+            const bucket = aliasToIds.get(normalized) ?? new Set();
+            bucket.add(serviceId);
+            aliasToIds.set(normalized, bucket);
+        };
+        for (const service of catalog.services) {
+            const normalizedId = this.normalizeServiceLookupKey(service.id);
+            if (normalizedId)
+                idLookup.set(normalizedId, service.id);
+            registerAlias(service.id, service.id);
+            registerAlias(service.name, service.id);
+            for (const alias of service.aliases) {
+                registerAlias(alias, service.id);
+            }
+        }
+        const containsLookupPhrase = (haystack, phrase) => {
+            if (!haystack || !phrase)
+                return false;
+            if (!phrase.includes(" ") && phrase.length < 4)
+                return false;
+            return ` ${haystack} `.includes(` ${phrase} `);
+        };
+        const mapCandidateToServiceId = (value) => {
+            const normalized = this.normalizeServiceLookupKey(value);
+            if (!normalized)
+                return {};
+            const directId = idLookup.get(normalized);
+            if (directId)
+                return { resolvedId: directId };
+            const aliasMatches = aliasToIds.get(normalized);
+            if (aliasMatches && aliasMatches.size === 1) {
+                return { resolvedId: Array.from(aliasMatches)[0] };
+            }
+            if (aliasMatches && aliasMatches.size > 1) {
+                return {
+                    ambiguousIds: Array.from(aliasMatches).sort((a, b) => (serviceOrder.get(a) ?? Number.MAX_SAFE_INTEGER) - (serviceOrder.get(b) ?? Number.MAX_SAFE_INTEGER)),
+                };
+            }
+            const idFromName = this.normalizeServiceId(normalized);
+            if (!idFromName)
+                return {};
+            if (validServiceIds.has(idFromName))
+                return { resolvedId: idFromName };
+            const candidates = Array.from(validServiceIds)
+                .filter((id) => id === idFromName || id.startsWith(`${idFromName}-`))
+                .sort((a, b) => (serviceOrder.get(a) ?? Number.MAX_SAFE_INTEGER) - (serviceOrder.get(b) ?? Number.MAX_SAFE_INTEGER));
+            if (candidates.length === 1)
+                return { resolvedId: candidates[0] };
+            if (candidates.length > 1)
+                return { ambiguousIds: candidates };
+            return {};
+        };
+        const inferServiceIdsFromEpicText = (epic) => {
+            const text = this.normalizeServiceLookupKey([epic.title, epic.description ?? "", ...(epic.acceptanceCriteria ?? [])]
+                .filter(Boolean)
+                .join("\n"));
+            if (!text)
+                return [];
+            const scored = new Map();
+            for (const service of catalog.services) {
+                let score = 0;
+                const idToken = this.normalizeServiceLookupKey(service.id);
+                if (idToken && containsLookupPhrase(text, idToken)) {
+                    score = Math.max(score, 120 + idToken.length);
+                }
+                const nameToken = this.normalizeServiceLookupKey(service.name);
+                if (nameToken && containsLookupPhrase(text, nameToken)) {
+                    score = Math.max(score, 90 + nameToken.length);
+                }
+                for (const alias of service.aliases) {
+                    const aliasToken = this.normalizeServiceLookupKey(alias);
+                    if (!aliasToken || aliasToken === idToken || aliasToken === nameToken)
+                        continue;
+                    if (containsLookupPhrase(text, aliasToken)) {
+                        score = Math.max(score, 60 + aliasToken.length);
+                    }
+                }
+                if (score > 0)
+                    scored.set(service.id, score);
+            }
+            return Array.from(scored.entries())
+                .sort((a, b) => b[1] - a[1] || (serviceOrder.get(a[0]) ?? 0) - (serviceOrder.get(b[0]) ?? 0))
+                .map(([id]) => id)
+                .slice(0, 4);
+        };
+        const pickFallbackServiceIds = (epic, count) => {
+            const text = this.normalizeServiceLookupKey([epic.title, epic.description ?? "", ...(epic.acceptanceCriteria ?? [])]
+                .filter(Boolean)
+                .join("\n"));
+            const ranked = catalog.services
+                .map((service) => {
+                let score = 0;
+                if (service.isFoundational)
+                    score += 100;
+                if (typeof service.startupWave === "number")
+                    score += Math.max(0, 40 - service.startupWave * 2);
+                if (service.dependsOnServiceIds.length === 0)
+                    score += 20;
+                const tokens = uniqueStrings([service.id, service.name, ...service.aliases])
+                    .map((value) => this.normalizeServiceLookupKey(value))
+                    .filter(Boolean);
+                for (const token of tokens) {
+                    if (containsLookupPhrase(text, token)) {
+                        score += 25 + token.length;
+                    }
+                }
+                return { id: service.id, score };
+            })
+                .sort((a, b) => b.score - a.score ||
+                (serviceOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER) - (serviceOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER));
+            return ranked.slice(0, Math.max(1, count)).map((entry) => entry.id);
+        };
+        const normalizedEpics = epics.map((epic, index) => {
+            const explicitServiceIds = normalizeStringArray(epic.serviceIds);
+            const resolvedServiceIds = [];
+            const unresolvedServiceIds = [];
+            const ambiguousServiceIds = [];
+            for (const candidate of explicitServiceIds) {
+                const mapped = mapCandidateToServiceId(candidate);
+                if (mapped.resolvedId) {
+                    resolvedServiceIds.push(mapped.resolvedId);
+                }
+                else if ((mapped.ambiguousIds?.length ?? 0) > 1) {
+                    ambiguousServiceIds.push({ candidate, options: mapped.ambiguousIds ?? [] });
+                    unresolvedServiceIds.push(candidate);
+                }
+                else {
+                    unresolvedServiceIds.push(candidate);
+                }
+            }
+            const inferredServiceIds = inferServiceIdsFromEpicText(epic);
+            const targetServiceCount = Math.max(1, Math.min(3, explicitServiceIds.length || 1));
+            if (policy === "auto-remediate") {
+                for (const inferred of inferredServiceIds) {
+                    if (resolvedServiceIds.includes(inferred))
+                        continue;
+                    resolvedServiceIds.push(inferred);
+                    if (resolvedServiceIds.length >= targetServiceCount)
+                        break;
+                }
+                if (resolvedServiceIds.length === 0 && catalog.services.length > 0) {
+                    resolvedServiceIds.push(...pickFallbackServiceIds(epic, 1));
+                }
+            }
+            else if (resolvedServiceIds.length === 0 && inferredServiceIds.length > 0) {
+                resolvedServiceIds.push(...inferredServiceIds.slice(0, Math.max(1, targetServiceCount)));
+            }
+            const dedupedServiceIds = uniqueStrings(resolvedServiceIds)
+                .filter((serviceId) => validServiceIds.has(serviceId))
+                .sort((a, b) => (serviceOrder.get(a) ?? Number.MAX_SAFE_INTEGER) - (serviceOrder.get(b) ?? Number.MAX_SAFE_INTEGER));
+            if (dedupedServiceIds.length === 0) {
+                throw new Error(`Epic ${epic.localId ?? index + 1} (${epic.title}) has no valid phase-0 service references. Allowed service ids: ${Array.from(validServiceIds).join(", ")}`);
+            }
+            if (unresolvedServiceIds.length > 0 || ambiguousServiceIds.length > 0) {
+                const unresolvedLabel = unresolvedServiceIds.length > 0 ? unresolvedServiceIds.join(", ") : "(none)";
+                const issueLabel = unresolvedServiceIds.length > 0 ? "unknown service ids" : "ambiguous service ids";
+                const ambiguity = ambiguousServiceIds.length > 0
+                    ? ` Ambiguous mappings: ${ambiguousServiceIds
+                        .map((item) => `${item.candidate} -> [${item.options.join(", ")}]`)
+                        .join("; ")}.`
+                    : "";
+                const message = `Epic ${epic.localId ?? index + 1} (${epic.title}) referenced ${issueLabel}: ${unresolvedLabel}.${ambiguity}`;
+                if (policy === "fail") {
+                    throw new Error(`${message} Allowed service ids: ${Array.from(validServiceIds).join(", ")}`);
+                }
+                warnings.push(`${message} Auto-remediated to: ${dedupedServiceIds.join(", ")}`);
+            }
+            const tags = normalizeEpicTags(epic.tags);
+            if (dedupedServiceIds.length > 1 && !tags.includes(CROSS_SERVICE_TAG)) {
+                tags.push(CROSS_SERVICE_TAG);
+            }
+            if (dedupedServiceIds.length <= 1 && tags.includes(CROSS_SERVICE_TAG)) {
+                warnings.push(`Epic ${epic.localId ?? index + 1} (${epic.title}) has tag ${CROSS_SERVICE_TAG} but only one service id (${dedupedServiceIds.join(", ")}). Keeping tag as explicit cross-cutting marker.`);
+            }
+            return {
+                ...epic,
+                serviceIds: dedupedServiceIds,
+                tags: uniqueStrings(tags),
+            };
+        });
+        return { epics: normalizedEpics, warnings };
+    }
     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(", ")}`);
@@ -1579,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
@@ -1593,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,
@@ -1600,6 +2274,7 @@ export class CreateTasksService {
             sourceDocs,
             startupWaves: graph.startupWaves.slice(0, 12),
             services: graph.services.slice(0, 40),
+            serviceIds: graph.services.map((service) => this.normalizeServiceId(service) ?? service.replace(/\s+/g, "-")).slice(0, 40),
             foundationalDependencies: graph.foundationalDependencies.slice(0, 16),
             buildMethod,
         };
@@ -1675,14 +2350,36 @@ export class CreateTasksService {
             return [service, wave * 10000 + order];
         }));
         const resolveEntityService = (text) => this.resolveServiceMentionFromPhrase(text, graph.aliases);
+        const resolveServiceFromIds = (serviceIds) => {
+            for (const serviceId of normalizeStringArray(serviceIds)) {
+                const resolved = resolveEntityService(serviceId) ?? this.addServiceAlias(graph.aliases, serviceId);
+                if (resolved)
+                    return resolved;
+            }
+            return undefined;
+        };
         const epics = plan.epics.map((epic) => ({ ...epic }));
         const stories = plan.stories.map((story) => ({ ...story }));
         const tasks = plan.tasks.map((task) => ({ ...task, dependsOnKeys: uniqueStrings(task.dependsOnKeys ?? []) }));
         const storyByScope = new Map(stories.map((story) => [this.scopeStory(story), story]));
+        const epicServiceByLocalId = new Map();
+        const storyServiceByScope = new Map();
         const taskServiceByScope = new Map();
+        for (const epic of epics) {
+            const serviceFromIds = resolveServiceFromIds(epic.serviceIds);
+            const serviceFromText = resolveEntityService(`${epic.title}\n${epic.description ?? ""}`);
+            epicServiceByLocalId.set(epic.localId, serviceFromIds ?? serviceFromText);
+        }
+        for (const story of stories) {
+            const storyScope = this.scopeStory(story);
+            const inherited = epicServiceByLocalId.get(story.epicLocalId);
+            const serviceFromText = resolveEntityService(`${story.title}\n${story.description ?? ""}\n${story.userStory ?? ""}`);
+            storyServiceByScope.set(storyScope, serviceFromText ?? inherited);
+        }
         for (const task of tasks) {
+            const storyScope = this.storyScopeKey(task.epicLocalId, task.storyLocalId);
             const text = `${task.title ?? ""}\n${task.description ?? ""}`;
-            taskServiceByScope.set(this.scopeTask(task), resolveEntityService(text));
+            taskServiceByScope.set(this.scopeTask(task), resolveEntityService(text) ?? storyServiceByScope.get(storyScope));
         }
         const tasksByStory = new Map();
         for (const task of tasks) {
@@ -1728,7 +2425,7 @@ export class CreateTasksService {
             const taskRanks = storyTasks
                 .map((task) => serviceRank.get(taskServiceByScope.get(this.scopeTask(task)) ?? ""))
                 .filter((value) => typeof value === "number");
-            const storyTextRank = serviceRank.get(resolveEntityService(`${story.title}\n${story.description ?? ""}\n${story.userStory ?? ""}`) ?? "");
+            const storyTextRank = serviceRank.get(storyServiceByScope.get(storyScope) ?? "");
             const rank = taskRanks.length > 0 ? Math.min(...taskRanks) : storyTextRank ?? Number.MAX_SAFE_INTEGER;
             storyRankByScope.set(storyScope, rank);
         }
@@ -1738,7 +2435,7 @@ export class CreateTasksService {
             const storyRanks = epicStories
                 .map((story) => storyRankByScope.get(this.scopeStory(story)))
                 .filter((value) => typeof value === "number");
-            const epicTextRank = serviceRank.get(resolveEntityService(`${epic.title}\n${epic.description ?? ""}`) ?? "");
+            const epicTextRank = serviceRank.get(epicServiceByLocalId.get(epic.localId) ?? "");
             const rank = storyRanks.length > 0 ? Math.min(...storyRanks) : epicTextRank ?? Number.MAX_SAFE_INTEGER;
             epicRankByLocalId.set(epic.localId, rank);
         }
@@ -1843,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: [
@@ -2205,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;
@@ -2295,8 +3007,8 @@ export class CreateTasksService {
         }
         return { docSummary: blocks.join("\n\n") || "(no docs)", warnings };
     }
-    buildPrompt(projectKey, docs, projectBuildMethod, 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}.` : "",
             options.maxStoriesPerEpic ? `Limit stories per epic to ${options.maxStoriesPerEpic}.` : "",
@@ -2317,8 +3029,14 @@ 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:",
             projectBuildMethod,
+            "Phase 0 service catalog (allowed serviceIds):",
+            serviceCatalogSummary,
             limits || "Use reasonable scope without over-generating epics.",
             "Docs available:",
             docSummary || "- (no docs provided; propose sensible epics).",
@@ -2363,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"],
@@ -2618,6 +3336,8 @@ export class CreateTasksService {
             acceptanceCriteria: Array.isArray(epic.acceptanceCriteria) ? epic.acceptanceCriteria : [],
             relatedDocs: normalizeRelatedDocs(epic.relatedDocs),
             priorityHint: typeof epic.priorityHint === "number" ? epic.priorityHint : undefined,
+            serviceIds: normalizeStringArray(epic.serviceIds),
+            tags: normalizeEpicTags(epic.tags),
             stories: [],
         }))
             .filter((e) => e.title);
@@ -2634,8 +3354,11 @@ 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)"}`,
+            `Epic tags: ${(epic.tags ?? []).join(", ") || "(none)"}`,
             "Project construction method:",
             projectBuildMethod,
             `Docs: ${docSummary || "none"}`,
@@ -2690,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.",
@@ -2789,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,
@@ -2893,65 +3617,349 @@ 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 writePlanArtifacts(projectKey, plan, docSummary, docs, buildPlan) {
+    async acquirePlanArtifactLock(baseDir, options) {
+        const timeoutMs = options?.timeoutMs ?? 10000;
+        const pollIntervalMs = options?.pollIntervalMs ?? 80;
+        const staleLockMs = options?.staleLockMs ?? 120000;
+        const lockPath = path.join(baseDir, ".plan-artifacts.lock");
+        const startedAtMs = Date.now();
+        while (true) {
+            try {
+                const handle = await fs.open(lockPath, "wx");
+                await handle.writeFile(JSON.stringify({ pid: process.pid, acquiredAt: new Date().toISOString() }), "utf8");
+                return async () => {
+                    try {
+                        await handle.close();
+                    }
+                    catch { }
+                    await fs.rm(lockPath, { force: true });
+                };
+            }
+            catch (error) {
+                const code = error.code;
+                if (code !== "EEXIST")
+                    throw error;
+                try {
+                    const stat = await fs.stat(lockPath);
+                    if (Date.now() - stat.mtimeMs > staleLockMs) {
+                        await fs.rm(lockPath, { force: true });
+                        continue;
+                    }
+                }
+                catch {
+                    continue;
+                }
+                if (Date.now() - startedAtMs >= timeoutMs) {
+                    throw new Error(`Timed out acquiring plan artifact lock for ${baseDir}`);
+                }
+                await delay(pollIntervalMs);
+            }
+        }
+    }
+    async writeJsonArtifactAtomic(targetPath, data) {
+        const tempPath = `${targetPath}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+        const payload = JSON.stringify(data, null, 2);
+        await fs.writeFile(tempPath, payload, "utf8");
+        try {
+            await fs.rename(tempPath, targetPath);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "EEXIST" || code === "EPERM") {
+                await fs.rm(targetPath, { force: true });
+                await fs.rename(tempPath, targetPath);
+            }
+            else {
+                await fs.rm(tempPath, { force: true });
+                throw error;
+            }
+        }
+    }
+    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 write = async (file, data) => {
-            const target = path.join(baseDir, file);
-            await fs.writeFile(target, JSON.stringify(data, null, 2), "utf8");
-        };
-        await write("plan.json", { projectKey, generatedAt: new Date().toISOString(), docSummary, buildPlan, ...plan });
-        await write("build-plan.json", buildPlan);
-        await write("epics.json", plan.epics);
-        await write("stories.json", plan.stories);
-        await write("tasks.json", plan.tasks);
-        await write("coverage-report.json", this.buildSdsCoverageReport(projectKey, docs, plan));
+        const releaseLock = await this.acquirePlanArtifactLock(baseDir);
+        try {
+            const write = async (file, data) => {
+                const target = path.join(baseDir, file);
+                await this.writeJsonArtifactAtomic(target, data);
+            };
+            await write("plan.json", {
+                projectKey,
+                generatedAt: new Date().toISOString(),
+                docSummary,
+                buildPlan,
+                serviceCatalog,
+                ...plan,
+            });
+            await write("build-plan.json", buildPlan);
+            await write("services.json", serviceCatalog);
+            await write("epics.json", plan.epics);
+            await write("stories.json", plan.stories);
+            await write("tasks.json", plan.tasks);
+            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();
+        }
         return { folder: baseDir };
     }
     async persistPlanToDb(projectId, projectKey, plan, jobId, commandRunId, options) {
@@ -2969,7 +3977,13 @@ export class CreateTasksService {
                 description: buildEpicDescription(key, epic.title || `Epic ${key}`, epic.description, epic.acceptanceCriteria, epic.relatedDocs),
                 storyPointsTotal: null,
                 priority: epic.priorityHint ?? (epicInserts.length + 1),
-                metadata: epic.relatedDocs ? { doc_links: epic.relatedDocs } : undefined,
+                metadata: epic.relatedDocs || (epic.serviceIds?.length ?? 0) > 0 || (epic.tags?.length ?? 0) > 0
+                    ? {
+                        ...(epic.relatedDocs ? { doc_links: epic.relatedDocs } : {}),
+                        ...(epic.serviceIds && epic.serviceIds.length > 0 ? { service_ids: epic.serviceIds } : {}),
+                        ...(epic.tags && epic.tags.length > 0 ? { tags: epic.tags } : {}),
+                    }
+                    : undefined,
             });
             epicMeta.push({ key, node: epic });
         }
@@ -3187,6 +4201,7 @@ export class CreateTasksService {
     }
     async createTasks(options) {
         const agentStream = options.agentStream !== false;
+        const unknownEpicServicePolicy = normalizeEpicServicePolicy(options.unknownEpicServicePolicy) ?? "auto-remediate";
         const commandRun = await this.jobService.startCommandRun("create-tasks", options.projectKey);
         const job = await this.jobService.startJob("create_tasks", commandRun.id, options.projectKey, {
             commandName: "create-tasks",
@@ -3196,6 +4211,7 @@ export class CreateTasksService {
                 agent: options.agentName,
                 agentStream,
                 sdsPreflightCommit: options.sdsPreflightCommit === true,
+                unknownEpicServicePolicy,
             },
         });
         let lastError;
@@ -3208,6 +4224,8 @@ export class CreateTasksService {
                 });
                 let sdsPreflight;
                 let sdsPreflightError;
+                let sdsPreflightBlockingReasons = [];
+                let continueAfterSdsPreflightWarnings = false;
                 if (this.sdsPreflightFactory) {
                     let sdsPreflightCloseError;
                     try {
@@ -3219,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,
                             });
@@ -3279,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,
@@ -3299,27 +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 projectBuildMethod = this.buildProjectConstructionMethod(docs, discoveryGraph);
-                const projectBuildPlan = this.buildProjectPlanArtifact(options.projectKey, docs, discoveryGraph, projectBuildMethod);
-                const { prompt } = this.buildPrompt(options.projectKey, docs, projectBuildMethod, 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",
@@ -3330,6 +4361,18 @@ export class CreateTasksService {
                         startupWaves: projectBuildPlan.startupWaves.length,
                     },
                 });
+                await this.jobService.writeCheckpoint(job.id, {
+                    stage: "phase0_services_defined",
+                    timestamp: new Date().toISOString(),
+                    details: {
+                        services: serviceCatalog.services.length,
+                        foundational: serviceCatalog.services.filter((service) => service.isFoundational).length,
+                        startupWaves: uniqueStrings(serviceCatalog.services
+                            .map((service) => (typeof service.startupWave === "number" ? String(service.startupWave) : ""))
+                            .filter(Boolean)).length,
+                        sourceDocs: serviceCatalog.sourceDocs.length,
+                    },
+                });
                 await this.jobService.writeCheckpoint(job.id, {
                     stage: "qa_preflight",
                     timestamp: new Date().toISOString(),
@@ -3342,7 +4385,12 @@ export class CreateTasksService {
                 try {
                     agent = await this.resolveAgent(options.agentName);
                     const { output: epicOutput } = await this.invokeAgentWithRetry(agent, prompt, "epics", agentStream, job.id, commandRun.id, { docWarnings });
-                    const epics = this.parseEpics(epicOutput, docs, options.projectKey).slice(0, options.maxEpics ?? Number.MAX_SAFE_INTEGER);
+                    const parsedEpics = this.parseEpics(epicOutput, docs, options.projectKey).slice(0, options.maxEpics ?? Number.MAX_SAFE_INTEGER);
+                    const normalizedEpics = this.alignEpicsToServiceCatalog(parsedEpics, serviceCatalog, unknownEpicServicePolicy);
+                    for (const warning of normalizedEpics.warnings) {
+                        await this.jobService.appendLog(job.id, `[create-tasks] ${warning}\n`);
+                    }
+                    const epics = normalizedEpics.epics;
                     await this.jobService.writeCheckpoint(job.id, {
                         stage: "epics_generated",
                         timestamp: new Date().toISOString(),
@@ -3359,6 +4407,10 @@ export class CreateTasksService {
                 }
                 catch (error) {
                     fallbackReason = error.message ?? String(error);
+                    if (unknownEpicServicePolicy === "fail" &&
+                        /unknown service ids|phase-0 service references/i.test(fallbackReason)) {
+                        throw error;
+                    }
                     planSource = "fallback";
                     await this.jobService.appendLog(job.id, `Agent planning failed, using deterministic fallback plan: ${fallbackReason}\n`);
                     plan = this.materializePlanFromSeed(this.fallbackPlan(options.projectKey, docs), {
@@ -3372,6 +4424,18 @@ export class CreateTasksService {
                         details: { epics: plan.epics.length, source: planSource, reason: fallbackReason },
                     });
                 }
+                const normalizedPlanEpics = this.alignEpicsToServiceCatalog(plan.epics, serviceCatalog, unknownEpicServicePolicy);
+                for (const warning of normalizedPlanEpics.warnings) {
+                    await this.jobService.appendLog(job.id, `[create-tasks] ${warning}\n`);
+                }
+                plan = {
+                    ...plan,
+                    epics: normalizedPlanEpics.epics.map((epic, index) => ({
+                        ...epic,
+                        localId: epic.localId ?? `e${index + 1}`,
+                        stories: [],
+                    })),
+                };
                 plan = this.enforceStoryScopedDependencies(plan);
                 plan = this.injectStructureBootstrapPlan(plan, docs, options.projectKey);
                 plan = this.enforceStoryScopedDependencies(plan);
@@ -3389,7 +4453,7 @@ export class CreateTasksService {
                     timestamp: new Date().toISOString(),
                     details: { tasks: plan.tasks.length, source: planSource, fallbackReason },
                 });
-                const { folder } = await this.writePlanArtifacts(options.projectKey, plan, docSummary, docs, projectBuildPlan);
+                const { folder } = await this.writePlanArtifacts(options.projectKey, plan, docSummary, docs, projectBuildPlan, serviceCatalog);
                 await this.jobService.writeCheckpoint(job.id, {
                     stage: "plan_written",
                     timestamp: new Date().toISOString(),
@@ -3483,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,
@@ -3508,6 +4597,8 @@ export class CreateTasksService {
                                 reportPath: sdsPreflight.reportPath,
                                 openQuestionsPath: sdsPreflight.openQuestionsPath,
                                 gapAddendumPath: sdsPreflight.gapAddendumPath,
+                                blockingReasons: sdsPreflightBlockingReasons,
+                                continuedWithWarnings: continueAfterSdsPreflightWarnings,
                                 warnings: sdsPreflight.warnings,
                             }
                             : undefined,
@@ -3555,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) {