@mcoda/core 0.1.34 → 0.1.36

package/dist/services/planning/CreateTasksService.js

@@ -12,7 +12,9 @@ import { classifyTask } from "../backlog/TaskOrderingHeuristics.js";
 import { TaskOrderingService } from "../backlog/TaskOrderingService.js";
 import { QaTestCommandBuilder } from "../execution/QaTestCommandBuilder.js";
 import { createEpicKeyGenerator, createStoryKeyGenerator, createTaskKeyGenerator, } from "./KeyHelpers.js";
-import { TaskSufficiencyService } from "./TaskSufficiencyService.js";
+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) => {
     if (!items || items.length === 0)
@@ -162,6 +164,7 @@ const DOC_CONTEXT_SEGMENTS_PER_DOC = 8;
 const DOC_CONTEXT_FALLBACK_CHUNK_LENGTH = 480;
 const SDS_COVERAGE_HINT_HEADING_LIMIT = 24;
 const SDS_COVERAGE_REPORT_SECTION_LIMIT = 80;
+const SDS_COVERAGE_REPORT_FOLDER_LIMIT = 240;
 const OPENAPI_HINT_OPERATIONS_LIMIT = 30;
 const DOCDEX_HANDLE = /^docdex:/i;
 const DOCDEX_LOCAL_HANDLE = /^docdex:local[-:/]/i;
@@ -170,7 +173,6 @@ const RELATIVE_DOC_PATH_PATTERN = /^(?:\.{1,2}\/)+[A-Za-z0-9._/-]+(?:\.[A-Za-z0-
 const FUZZY_DOC_CANDIDATE_LIMIT = 64;
 const DEPENDENCY_SCAN_LINE_LIMIT = 1400;
 const STARTUP_WAVE_SCAN_LINE_LIMIT = 4000;
-const VALID_AREAS = new Set(["web", "adm", "bck", "ops", "infra", "mobile"]);
 const VALID_TASK_TYPES = new Set(["feature", "bug", "chore", "spike"]);
 const VALID_EPIC_SERVICE_POLICIES = new Set(["auto-remediate", "fail"]);
 const CROSS_SERVICE_TAG = "cross_service";
@@ -189,16 +191,12 @@ const inferDocType = (filePath) => {
 const normalizeArea = (value) => {
     if (typeof value !== "string")
         return undefined;
-    const tokens = value
+    const normalized = value
         .toLowerCase()
-        .split(/[^a-z]+/)
-        .map((token) => token.trim())
-        .filter(Boolean);
-    for (const token of tokens) {
-        if (VALID_AREAS.has(token))
-            return token;
-    }
-    return undefined;
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-");
+    return normalized.length > 0 ? normalized.slice(0, 24) : undefined;
 };
 const normalizeTaskType = (value) => {
     if (typeof value !== "string")
@@ -252,40 +250,6 @@ const normalizeRelatedDocs = (value) => {
     }
     return normalized;
 };
-const extractMarkdownHeadings = (value, limit) => {
-    if (!value)
-        return [];
-    const lines = value.split(/\r?\n/);
-    const headings = [];
-    for (let index = 0; index < lines.length; index += 1) {
-        const line = lines[index]?.trim() ?? "";
-        if (!line)
-            continue;
-        const hashHeading = line.match(/^#{1,6}\s+(.+)$/);
-        if (hashHeading) {
-            headings.push(hashHeading[1].trim());
-        }
-        else if (index + 1 < lines.length &&
-            /^[=-]{3,}\s*$/.test((lines[index + 1] ?? "").trim()) &&
-            !line.startsWith("-") &&
-            !line.startsWith("*")) {
-            headings.push(line);
-        }
-        else {
-            const numberedHeading = line.match(/^(\d+(?:\.\d+)+)\s+(.+)$/);
-            if (numberedHeading) {
-                const headingText = `${numberedHeading[1]} ${numberedHeading[2]}`.trim();
-                if (/[a-z]/i.test(headingText))
-                    headings.push(headingText);
-            }
-        }
-        if (headings.length >= limit)
-            break;
-    }
-    return uniqueStrings(headings
-        .map((entry) => entry.replace(/[`*_]/g, "").trim())
-        .filter(Boolean));
-};
 const pickDistributedIndices = (length, limit) => {
     if (length <= 0 || limit <= 0)
         return [];
@@ -574,8 +538,8 @@ const buildTaskDescription = (taskKey, title, description, storyKey, epicKey, re
             ? "- Task-specific tests are added/updated and green in the task validation loop."
             : "- Verification evidence is captured in task logs/checklists for this scope.",
         relatedDocs?.length
-            ? "- Related contracts/docs are consistent with delivered behavior."
-            : "- Documentation impact is reviewed and no additional contract docs are required.",
+            ? "- Related interfaces/docs are consistent with delivered behavior."
+            : "- Documentation impact is reviewed and no additional interface docs are required.",
         qa?.blockers?.length ? "- Remaining QA blockers are explicit and actionable." : "- QA blockers are resolved or not present.",
     ];
     const defaultImplementationPlan = [
@@ -586,7 +550,7 @@ const buildTaskDescription = (taskKey, title, description, storyKey, epicKey, re
     ];
     const defaultRisks = dependencies.length
         ? [`Delivery depends on upstream tasks: ${dependencies.join(", ")}.`]
-        : ["Keep implementation aligned to SDS/OpenAPI contracts to avoid drift."];
+        : ["Keep implementation aligned to documented interfaces and dependency expectations to avoid drift."];
     return [
         `* **Task Key**: ${taskKey}`,
         "* **Objective**",
@@ -680,6 +644,51 @@ const SERVICE_PATH_CONTAINER_SEGMENTS = new Set([
     "lib",
     "src",
 ]);
+const SOURCE_LIKE_PATH_SEGMENTS = new Set([
+    "api",
+    "app",
+    "apps",
+    "bin",
+    "cmd",
+    "components",
+    "controllers",
+    "handlers",
+    "internal",
+    "lib",
+    "libs",
+    "pages",
+    "routes",
+    "screens",
+    "server",
+    "servers",
+    "spec",
+    "specs",
+    "src",
+    "test",
+    "tests",
+    "ui",
+    "web",
+]);
+const GENERIC_CONTAINER_PATH_SEGMENTS = new Set([
+    "adapters",
+    "apps",
+    "clients",
+    "consoles",
+    "domains",
+    "engines",
+    "features",
+    "modules",
+    "packages",
+    "platforms",
+    "plugins",
+    "products",
+    "servers",
+    "services",
+    "systems",
+    "tools",
+    "workers",
+]);
+const NON_RUNTIME_STRUCTURE_ROOT_SEGMENTS = new Set(["docs", "fixtures", "runbooks", "policies", "policy"]);
 const SERVICE_NAME_STOPWORDS = new Set([
     "the",
     "a",
@@ -737,10 +746,197 @@ 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 MARKDOWN_HEADING_PATTERN = /^(#{1,6})\s+(.+?)\s*$/;
+const RUNTIME_COMPONENTS_HEADING_PATTERN = /\b(runtime components?|runtime topology|system components?|component topology|services?)\b/i;
+const VERIFICATION_MATRIX_HEADING_PATTERN = /\b(verification matrix|validation matrix|test matrix|verification suites?)\b/i;
+const ACCEPTANCE_SCENARIOS_HEADING_PATTERN = /\b(required )?acceptance scenarios?\b/i;
+const BUILD_TARGET_RUNTIME_SEGMENTS = new Set([
+    "api",
+    "app",
+    "apps",
+    "bin",
+    "cli",
+    "client",
+    "clients",
+    "cmd",
+    "command",
+    "commands",
+    "engine",
+    "engines",
+    "feature",
+    "features",
+    "gateway",
+    "gateways",
+    "handler",
+    "handlers",
+    "module",
+    "modules",
+    "page",
+    "pages",
+    "processor",
+    "processors",
+    "route",
+    "routes",
+    "screen",
+    "screens",
+    "server",
+    "servers",
+    "service",
+    "services",
+    "src",
+    "ui",
+    "web",
+    "worker",
+    "workers",
+]);
+const BUILD_TARGET_INTERFACE_SEGMENTS = new Set([
+    "contract",
+    "contracts",
+    "dto",
+    "dtos",
+    "interface",
+    "interfaces",
+    "proto",
+    "protocol",
+    "protocols",
+    "schema",
+    "schemas",
+    "spec",
+    "specs",
+    "type",
+    "types",
+]);
+const BUILD_TARGET_DATA_SEGMENTS = new Set([
+    "cache",
+    "caches",
+    "data",
+    "db",
+    "ledger",
+    "migration",
+    "migrations",
+    "model",
+    "models",
+    "persistence",
+    "repository",
+    "repositories",
+    "storage",
+]);
+const BUILD_TARGET_TEST_SEGMENTS = new Set([
+    "acceptance",
+    "e2e",
+    "integration",
+    "spec",
+    "specs",
+    "test",
+    "tests",
+]);
+const BUILD_TARGET_OPS_SEGMENTS = new Set([
+    "deploy",
+    "deployment",
+    "deployments",
+    "helm",
+    "infra",
+    "k8s",
+    "ops",
+    "operation",
+    "operations",
+    "runbook",
+    "runbooks",
+    "script",
+    "scripts",
+    "systemd",
+    "terraform",
+]);
+const BUILD_TARGET_DOC_SEGMENTS = new Set(["docs", "policy", "policies", "rfp", "pdr", "sds"]);
+const MANIFEST_TARGET_BASENAME_PATTERN = /^(package\.json|pnpm-workspace\.yaml|pnpm-lock\.yaml|turbo\.json|tsconfig(?:\.[^.]+)?\.json|eslint(?:\.[^.]+)?\.(?:js|cjs|mjs|json)|prettier(?:\.[^.]+)?\.(?:js|cjs|mjs|json)|vite\.config\.[^.]+|webpack\.config\.[^.]+|rollup\.config\.[^.]+|cargo\.toml|pyproject\.toml|go\.mod|go\.sum|pom\.xml|build\.gradle(?:\.kts)?|settings\.gradle(?:\.kts)?|requirements\.txt|poetry\.lock|foundry\.toml|hardhat\.config\.[^.]+)$/i;
+const SERVICE_ARTIFACT_BASENAME_PATTERN = /(?:\.service|\.socket|\.timer|(?:^|[.-])compose\.(?:ya?ml|json)$|docker-compose\.(?:ya?ml|json)$)$/i;
+const GENERIC_IMPLEMENTATION_TASK_PATTERN = /update the concrete .* modules surfaced by the sds/i;
 const nextUniqueLocalId = (prefix, existing) => {
     let index = 1;
     let candidate = `${prefix}-${index}`;
@@ -763,11 +959,21 @@ const looksLikeSdsDoc = (doc) => {
         .slice(0, 5000);
     return STRICT_SDS_CONTENT_PATTERN.test(sample);
 };
+const looksLikePathishDocId = (value) => {
+    if (!value)
+        return false;
+    if (DOCDEX_LOCAL_HANDLE.test(value))
+        return false;
+    return (value.includes("/") ||
+        value.includes("\\") ||
+        FILE_EXTENSION_PATTERN.test(value) ||
+        STRICT_SDS_PATH_PATTERN.test(value.replace(/\\/g, "/").toLowerCase()));
+};
 const EPIC_SCHEMA_SNIPPET = `{
   "epics": [
     {
       "localId": "e1",
-      "area": "web|adm|bck|ops|infra|mobile",
+      "area": "documented-area-label",
       "title": "Epic title",
       "description": "Epic description using the epic template",
       "acceptanceCriteria": ["criterion"],
@@ -816,6 +1022,48 @@ const TASK_SCHEMA_SNIPPET = `{
     }
   ]
 }`;
+const FULL_PLAN_SCHEMA_SNIPPET = `{
+  "epics": [
+    {
+      "localId": "e1",
+      "area": "documented-area-label",
+      "title": "Epic title",
+      "description": "Epic description using the epic template",
+      "acceptanceCriteria": ["criterion"],
+      "relatedDocs": ["docdex:..."],
+      "priorityHint": 50,
+      "serviceIds": ["backend-api"],
+      "tags": ["cross_service"],
+      "stories": [
+        {
+          "localId": "us1",
+          "title": "Story title",
+          "userStory": "As a ...",
+          "description": "Story description using the template",
+          "acceptanceCriteria": ["criterion"],
+          "relatedDocs": ["docdex:..."],
+          "priorityHint": 50,
+          "tasks": [
+            {
+              "localId": "t1",
+              "title": "Task title",
+              "type": "feature|bug|chore|spike",
+              "description": "Task description using the template",
+              "estimatedStoryPoints": 3,
+              "priorityHint": 50,
+              "dependsOnKeys": ["t0"],
+              "relatedDocs": ["docdex:..."],
+              "unitTests": ["unit test description"],
+              "componentTests": ["component test description"],
+              "integrationTests": ["integration test description"],
+              "apiTests": ["api test description"]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}`;
 export class CreateTasksService {
     constructor(workspace, deps) {
         this.workspace = workspace;
@@ -931,7 +1179,7 @@ export class CreateTasksService {
         if (!documents.some((doc) => looksLikeSdsDoc(doc))) {
             throw new Error("create-tasks requires at least one SDS document. Add an SDS file (for example docs/sds.md) or pass SDS paths as input.");
         }
-        return this.sortDocsForPlanning(documents);
+        return this.sortDocsForPlanning(this.dedupePlanningDocs(documents.map((doc) => this.sanitizeDocForPlanning(doc))));
     }
     normalizeDocInputForSet(input) {
         if (input.startsWith("docdex:"))
@@ -953,8 +1201,19 @@ export class CreateTasksService {
         }
         return merged;
     }
+    canonicalizeDocPathKey(value) {
+        const trimmed = `${value ?? ""}`.trim();
+        if (!trimmed || DOCDEX_LOCAL_HANDLE.test(trimmed))
+            return undefined;
+        if (path.isAbsolute(trimmed))
+            return path.resolve(trimmed).toLowerCase();
+        if (looksLikePathishDocId(trimmed)) {
+            return path.resolve(this.workspace.workspaceRoot, trimmed).toLowerCase();
+        }
+        return undefined;
+    }
     docIdentity(doc) {
-        const pathKey = `${doc.path ?? ""}`.trim().toLowerCase();
+        const pathKey = this.canonicalizeDocPathKey(doc.path) ?? this.canonicalizeDocPathKey(doc.id);
         const idKey = `${doc.id ?? ""}`.trim().toLowerCase();
         if (pathKey)
             return `path:${pathKey}`;
@@ -978,6 +1237,61 @@ export class CreateTasksService {
         }
         return merged;
     }
+    sanitizeDocForPlanning(doc) {
+        const content = stripManagedSdsPreflightBlock(doc.content);
+        const segments = content !== doc.content
+            ? []
+            : (doc.segments ?? [])
+                .map((segment) => {
+                const sanitizedContent = stripManagedSdsPreflightBlock(segment.content ?? undefined);
+                return {
+                    ...segment,
+                    content: sanitizedContent ?? segment.content,
+                };
+            })
+                .filter((segment) => `${segment.content ?? ""}`.trim().length > 0 || `${segment.heading ?? ""}`.trim().length > 0);
+        const sanitized = {
+            ...doc,
+            content: content ?? doc.content,
+            segments,
+        };
+        if (looksLikeSdsDoc(sanitized) && `${sanitized.docType ?? ""}`.toUpperCase() !== "SDS") {
+            sanitized.docType = "SDS";
+        }
+        return sanitized;
+    }
+    scorePlanningDoc(doc) {
+        const segmentCount = doc.segments?.length ?? 0;
+        const contentLength = `${doc.content ?? ""}`.length;
+        return ((looksLikeSdsDoc(doc) ? 5000 : 0) +
+            (doc.path ? 400 : 0) +
+            segmentCount * 20 +
+            Math.min(300, contentLength));
+    }
+    mergePlanningDocPair(current, incoming) {
+        const [primary, secondary] = this.scorePlanningDoc(incoming) > this.scorePlanningDoc(current) ? [incoming, current] : [current, incoming];
+        const merged = {
+            ...secondary,
+            ...primary,
+            path: primary.path ?? secondary.path,
+            title: primary.title ?? secondary.title,
+            content: primary.content ?? secondary.content,
+            segments: (primary.segments?.length ?? 0) > 0 ? primary.segments : secondary.segments,
+        };
+        if (looksLikeSdsDoc(merged) && `${merged.docType ?? ""}`.toUpperCase() !== "SDS") {
+            merged.docType = "SDS";
+        }
+        return merged;
+    }
+    dedupePlanningDocs(docs) {
+        const merged = new Map();
+        for (const doc of docs) {
+            const identity = this.docIdentity(doc);
+            const existing = merged.get(identity);
+            merged.set(identity, existing ? this.mergePlanningDocPair(existing, doc) : doc);
+        }
+        return Array.from(merged.values());
+    }
     sortDocsForPlanning(docs) {
         return [...docs].sort((a, b) => {
             const aIsSds = looksLikeSdsDoc(a) ? 0 : 1;
@@ -1158,47 +1472,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))
-            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 === ".."))
+        const root = normalized.split("/")[0]?.toLowerCase();
+        if (root && DOC_SCAN_IGNORE_DIRS.has(root))
             return undefined;
-        if (parts.length === 1 && !TOP_LEVEL_STRUCTURE_PATTERN.test(parts[0]))
-            return undefined;
-        if (DOC_SCAN_IGNORE_DIRS.has(parts[0].toLowerCase()))
-            return undefined;
-        return parts.join("/");
+        return normalized;
     }
     extractStructureTargets(docs) {
         const directories = new Set();
         const files = new Set();
         for (const doc of docs) {
+            const relativeDocPath = doc.path ? path.relative(this.workspace.workspaceRoot, doc.path).replace(/\\/g, "/") : undefined;
+            const localDocPath = relativeDocPath && !relativeDocPath.startsWith("..") && !path.isAbsolute(relativeDocPath)
+                ? relativeDocPath
+                : undefined;
             const segments = (doc.segments ?? []).map((segment) => segment.content).filter(Boolean).join("\n");
-            const corpus = [doc.title, doc.path, doc.content, segments].filter(Boolean).join("\n");
-            for (const match of corpus.matchAll(DOC_PATH_TOKEN_PATTERN)) {
-                const token = match[2];
-                if (!token)
-                    continue;
+            const corpus = [localDocPath, doc.content, segments].filter(Boolean).join("\n");
+            for (const token of filterImplementationStructuredPaths(extractStructuredPaths(corpus, 256))) {
                 const normalized = this.normalizeStructurePathToken(token);
                 if (!normalized)
                     continue;
-                if (FILE_EXTENSION_PATTERN.test(path.basename(normalized))) {
+                if (isStructuredFilePath(path.basename(normalized))) {
                     files.add(normalized);
                     const parent = path.dirname(normalized).replace(/\\/g, "/");
                     if (parent && parent !== ".")
@@ -1238,6 +1534,61 @@ export class CreateTasksService {
             return undefined;
         return candidate.length >= 2 ? candidate : undefined;
     }
+    normalizeTextServiceName(value) {
+        const candidate = this.normalizeServiceName(value);
+        if (!candidate)
+            return undefined;
+        const tokens = candidate.split(" ").filter(Boolean);
+        if (tokens.length === 0 || tokens.length > 3)
+            return undefined;
+        const first = tokens[0] ?? "";
+        if (SERVICE_TEXT_INVALID_STARTERS.has(first))
+            return undefined;
+        if (tokens.length === 1) {
+            if (first.length < 3)
+                return undefined;
+            if (SERVICE_NAME_INVALID.has(first) || NON_RUNTIME_SERVICE_SINGLETONS.has(first))
+                return undefined;
+            if (SERVICE_NAME_STOPWORDS.has(first))
+                return undefined;
+        }
+        return candidate;
+    }
+    isLikelyServiceContainerSegment(parts, index) {
+        const segment = parts[index];
+        if (!segment)
+            return false;
+        if (SERVICE_PATH_CONTAINER_SEGMENTS.has(segment))
+            return true;
+        if (index !== 0)
+            return false;
+        const next = parts[index + 1];
+        if (!next)
+            return false;
+        const following = parts[index + 2];
+        const nextLooksSpecific = !SERVICE_PATH_CONTAINER_SEGMENTS.has(next) &&
+            !NON_RUNTIME_STRUCTURE_ROOT_SEGMENTS.has(next) &&
+            !SOURCE_LIKE_PATH_SEGMENTS.has(next) &&
+            !isStructuredFilePath(next);
+        if (!nextLooksSpecific)
+            return false;
+        if (GENERIC_CONTAINER_PATH_SEGMENTS.has(segment)) {
+            if (!following)
+                return true;
+            return SOURCE_LIKE_PATH_SEGMENTS.has(following) || isStructuredFilePath(following);
+        }
+        return false;
+    }
+    normalizePathDerivedServiceName(value) {
+        const candidate = this.normalizeServiceName(value);
+        if (!candidate)
+            return undefined;
+        if (NON_RUNTIME_SERVICE_SINGLETONS.has(candidate))
+            return undefined;
+        if (candidate.split(" ").some((token) => NON_RUNTIME_PATH_SERVICE_TOKENS.has(token)))
+            return undefined;
+        return candidate;
+    }
     deriveServiceFromPathToken(pathToken) {
         const parts = pathToken
             .replace(/\\/g, "/")
@@ -1246,11 +1597,18 @@ export class CreateTasksService {
             .filter(Boolean);
         if (!parts.length)
             return undefined;
+        if (NON_RUNTIME_STRUCTURE_ROOT_SEGMENTS.has(parts[0] ?? ""))
+            return undefined;
+        if (parts.length === 1 && isStructuredFilePath(parts[0] ?? ""))
+            return undefined;
         let idx = 0;
-        while (idx < parts.length - 1 && SERVICE_PATH_CONTAINER_SEGMENTS.has(parts[idx])) {
+        while (idx < parts.length - 1 && this.isLikelyServiceContainerSegment(parts, idx)) {
             idx += 1;
         }
-        return this.normalizeServiceName(parts[idx] ?? parts[0]);
+        const candidate = parts[idx] ?? parts[0];
+        if (isStructuredFilePath(candidate))
+            return undefined;
+        return this.normalizePathDerivedServiceName(candidate);
     }
     addServiceAlias(aliases, rawValue) {
         const canonical = this.normalizeServiceName(rawValue);
@@ -1266,6 +1624,10 @@ export class CreateTasksService {
             .trim();
         if (alias)
             existing.add(alias);
+        if (alias.endsWith("s") && alias.length > 3)
+            existing.add(alias.slice(0, -1));
+        if (!alias.endsWith("s") && alias.length > 2)
+            existing.add(`${alias}s`);
         aliases.set(canonical, existing);
         return canonical;
     }
@@ -1275,7 +1637,7 @@ export class CreateTasksService {
         const mentions = new Set();
         for (const match of text.matchAll(SERVICE_LABEL_PATTERN)) {
             const phrase = `${match[1] ?? ""} ${match[2] ?? ""}`.trim();
-            const normalized = this.normalizeServiceName(phrase);
+            const normalized = this.normalizeTextServiceName(phrase);
             if (normalized)
                 mentions.add(normalized);
         }
@@ -1289,7 +1651,18 @@ export class CreateTasksService {
         }
         return Array.from(mentions);
     }
-    resolveServiceMentionFromPhrase(phrase, aliases) {
+    deriveServiceMentionFromPathPhrase(phrase) {
+        for (const match of phrase.matchAll(DOC_PATH_TOKEN_PATTERN)) {
+            const token = match[2];
+            if (!token)
+                continue;
+            const derived = this.deriveServiceFromPathToken(token);
+            if (derived)
+                return derived;
+        }
+        return undefined;
+    }
+    resolveServiceMentionFromPhrase(phrase, aliases, options = {}) {
         const normalizedPhrase = phrase
             .toLowerCase()
             .replace(/[._/-]+/g, " ")
@@ -1312,6 +1685,11 @@ export class CreateTasksService {
         }
         if (best)
             return best.key;
+        const pathDerived = this.deriveServiceMentionFromPathPhrase(phrase);
+        if (pathDerived)
+            return pathDerived;
+        if (!options.allowAliasRegistration)
+            return undefined;
         const mention = this.extractServiceMentionsFromText(phrase)[0];
         if (!mention)
             return undefined;
@@ -1395,10 +1773,17 @@ export class CreateTasksService {
                     resolved.add(canonical);
             }
             if (resolved.size === 0) {
-                for (const mention of this.extractServiceMentionsFromText(cell)) {
-                    const canonical = this.addServiceAlias(aliases, mention);
-                    if (canonical)
-                        resolved.add(canonical);
+                const normalizedCell = this.normalizeServiceLookupKey(cell);
+                const haystack = normalizedCell ? ` ${normalizedCell} ` : "";
+                for (const [service, names] of aliases.entries()) {
+                    for (const alias of names) {
+                        if (!alias || alias.length < 2)
+                            continue;
+                        if (!haystack.includes(` ${alias} `))
+                            continue;
+                        resolved.add(service);
+                        break;
+                    }
                 }
             }
             return Array.from(resolved);
@@ -1441,6 +1826,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)) }));
@@ -1516,11 +1926,18 @@ export class CreateTasksService {
     buildServiceDependencyGraph(plan, docs) {
         const aliases = new Map();
         const dependencies = new Map();
+        const sourceBackedServices = new Set();
         const register = (value) => {
             if (!value)
                 return undefined;
             return this.addServiceAlias(aliases, value);
         };
+        const registerSourceBacked = (value) => {
+            const canonical = register(value);
+            if (canonical)
+                sourceBackedServices.add(canonical);
+            return canonical;
+        };
         const docsText = docs
             .map((doc) => [doc.title, doc.path, doc.content, ...(doc.segments ?? []).map((segment) => segment.content)].filter(Boolean).join("\n"))
             .join("\n");
@@ -1535,17 +1952,32 @@ export class CreateTasksService {
             }
         }
         const structureTargets = this.extractStructureTargets(docs);
-        for (const token of [...structureTargets.directories, ...structureTargets.files]) {
-            register(this.deriveServiceFromPathToken(token));
+        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;
+            }
+            registerSourceBacked(this.deriveServiceFromPathToken(token));
+        }
+        for (const component of this.extractRuntimeComponentNames(docs)) {
+            registerSourceBacked(component);
         }
         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);
+            registerSourceBacked(match[1]);
+        const docsHaveRuntimeTopologySignals = sourceBackedServices.size > 0 &&
+            (structureTargets.directories.length > 0 ||
+                structureTargets.files.length > 0 ||
+                this.collectDependencyStatements(docsText).length > 0 ||
+                WAVE_LABEL_PATTERN.test(docsText) ||
+                TOPOLOGY_HEADING_PATTERN.test(docsText));
+        if (!docsHaveRuntimeTopologySignals) {
+            for (const match of planText.matchAll(SERVICE_HANDLE_PATTERN))
+                register(match[1]);
+            for (const mention of this.extractServiceMentionsFromText(planText))
+                register(mention);
+        }
         const corpus = [docsText, planText].filter(Boolean);
         for (const text of corpus) {
             const statements = this.collectDependencyStatements(text);
@@ -1570,6 +2002,268 @@ 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))
+            .concat(this.extractRuntimeComponentNames(docs))).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,
+        };
+    }
+    buildSourceTopologyExpectation(docs) {
+        const signalSummary = this.summarizeTopologySignals(docs);
+        const docsOnlyGraph = this.buildServiceDependencyGraph({ epics: [], stories: [], tasks: [] }, docs);
+        return {
+            runtimeBearing: docsOnlyGraph.services.length > 0 ||
+                docsOnlyGraph.startupWaves.length > 0 ||
+                signalSummary.dependencyPairs.length > 0,
+            services: docsOnlyGraph.services,
+            startupWaves: docsOnlyGraph.startupWaves.map((wave) => ({
+                wave: wave.wave,
+                services: [...wave.services],
+            })),
+            dependencyPairs: signalSummary.dependencyPairs,
+            signalSummary,
+        };
+    }
+    buildCanonicalNameInventory(docs) {
+        const structureTargets = this.extractStructureTargets(docs);
+        const paths = uniqueStrings([...structureTargets.directories, ...structureTargets.files]
+            .map((token) => this.normalizeStructurePathToken(token))
+            .filter((value) => Boolean(value))).sort((a, b) => a.length - b.length || a.localeCompare(b));
+        const graph = this.buildServiceDependencyGraph({ epics: [], stories: [], tasks: [] }, docs);
+        const serviceAliases = new Map();
+        for (const [service, aliases] of graph.aliases.entries()) {
+            serviceAliases.set(service, new Set(aliases));
+        }
+        for (const service of graph.services) {
+            const existing = serviceAliases.get(service) ?? new Set();
+            existing.add(service);
+            serviceAliases.set(service, existing);
+        }
+        return {
+            paths,
+            pathSet: new Set(paths),
+            services: [...graph.services],
+            serviceAliases,
+        };
+    }
+    countCommonPrefixSegments(left, right) {
+        let count = 0;
+        while (count < left.length && count < right.length && left[count] === right[count]) {
+            count += 1;
+        }
+        return count;
+    }
+    countCommonSuffixSegments(left, right, prefixFloor = 0) {
+        let count = 0;
+        while (count < left.length - prefixFloor &&
+            count < right.length - prefixFloor &&
+            left[left.length - 1 - count] === right[right.length - 1 - count]) {
+            count += 1;
+        }
+        return count;
+    }
+    tokenizeCanonicalName(value) {
+        return this.normalizeServiceLookupKey(value)
+            .split(" ")
+            .map((token) => token.trim())
+            .filter(Boolean);
+    }
+    namesSemanticallyCollide(candidate, canonical) {
+        const candidateTokens = this.tokenizeCanonicalName(candidate);
+        const canonicalTokens = this.tokenizeCanonicalName(canonical);
+        if (candidateTokens.length === 0 || canonicalTokens.length === 0)
+            return false;
+        const canonicalSet = new Set(canonicalTokens);
+        const shared = candidateTokens.filter((token) => canonicalSet.has(token));
+        if (shared.length === 0)
+            return false;
+        if (shared.length === Math.min(candidateTokens.length, canonicalTokens.length))
+            return true;
+        const candidateNormalized = candidateTokens.join(" ");
+        const canonicalNormalized = canonicalTokens.join(" ");
+        return (candidateNormalized.includes(canonicalNormalized) || canonicalNormalized.includes(candidateNormalized));
+    }
+    findCanonicalPathConflict(candidatePath, inventory) {
+        if (!candidatePath || inventory.pathSet.has(candidatePath))
+            return undefined;
+        const candidateParts = candidatePath.split("/").filter(Boolean);
+        let bestMatch;
+        for (const canonicalPath of inventory.paths) {
+            if (candidatePath === canonicalPath)
+                continue;
+            const canonicalParts = canonicalPath.split("/").filter(Boolean);
+            const sharedPrefix = this.countCommonPrefixSegments(candidateParts, canonicalParts);
+            if (sharedPrefix === 0)
+                continue;
+            const sharedSuffix = this.countCommonSuffixSegments(candidateParts, canonicalParts, sharedPrefix);
+            if (sharedSuffix === 0)
+                continue;
+            const candidateCore = candidateParts.slice(sharedPrefix, candidateParts.length - sharedSuffix);
+            const canonicalCore = canonicalParts.slice(sharedPrefix, canonicalParts.length - sharedSuffix);
+            if (candidateCore.length !== 1 || canonicalCore.length !== 1)
+                continue;
+            const candidateSegment = candidateCore[0] ?? "";
+            const canonicalSegment = canonicalCore[0] ?? "";
+            if (!this.namesSemanticallyCollide(candidateSegment, canonicalSegment))
+                continue;
+            const candidateService = this.deriveServiceFromPathToken(candidatePath);
+            const canonicalService = this.deriveServiceFromPathToken(canonicalPath);
+            if (candidateService &&
+                canonicalService &&
+                candidateService !== canonicalService &&
+                !this.namesSemanticallyCollide(candidateService, canonicalService)) {
+                continue;
+            }
+            const score = sharedPrefix + sharedSuffix;
+            if (!bestMatch || score > bestMatch.score || (score === bestMatch.score && canonicalPath.length > bestMatch.canonicalPath.length)) {
+                bestMatch = { canonicalPath, canonicalService, score };
+            }
+        }
+        return bestMatch ? { canonicalPath: bestMatch.canonicalPath, canonicalService: bestMatch.canonicalService } : undefined;
+    }
+    collectCanonicalPlanSources(plan) {
+        const sources = [];
+        for (const epic of plan.epics) {
+            sources.push({
+                location: `epic:${epic.localId}`,
+                text: [epic.title, epic.description, ...(epic.acceptanceCriteria ?? []), ...(epic.serviceIds ?? []), ...(epic.tags ?? [])]
+                    .filter(Boolean)
+                    .join("\n"),
+            });
+        }
+        for (const story of plan.stories) {
+            sources.push({
+                location: `story:${story.epicLocalId}/${story.localId}`,
+                text: [story.title, story.userStory, story.description, ...(story.acceptanceCriteria ?? [])]
+                    .filter(Boolean)
+                    .join("\n"),
+            });
+        }
+        for (const task of plan.tasks) {
+            sources.push({
+                location: `task:${task.epicLocalId}/${task.storyLocalId}/${task.localId}`,
+                text: [
+                    task.title,
+                    task.description,
+                    ...(task.relatedDocs ?? []),
+                    ...(task.unitTests ?? []),
+                    ...(task.componentTests ?? []),
+                    ...(task.integrationTests ?? []),
+                    ...(task.apiTests ?? []),
+                ]
+                    .filter(Boolean)
+                    .join("\n"),
+            });
+        }
+        return sources.filter((source) => source.text.trim().length > 0);
+    }
+    assertCanonicalNameConsistency(projectKey, docs, plan) {
+        const inventory = this.buildCanonicalNameInventory(docs);
+        if (inventory.paths.length === 0 && inventory.services.length === 0)
+            return;
+        const conflicts = new Map();
+        for (const source of this.collectCanonicalPlanSources(plan)) {
+            const candidatePaths = uniqueStrings(filterImplementationStructuredPaths(extractStructuredPaths(source.text, 256))
+                .map((token) => this.normalizeStructurePathToken(token))
+                .filter((value) => Boolean(value)));
+            for (const candidatePath of candidatePaths) {
+                if (inventory.pathSet.has(candidatePath))
+                    continue;
+                const conflict = this.findCanonicalPathConflict(candidatePath, inventory);
+                if (!conflict)
+                    continue;
+                const key = `${source.location}|${candidatePath}|${conflict.canonicalPath}`;
+                conflicts.set(key, {
+                    location: source.location,
+                    candidate: candidatePath,
+                    canonical: conflict.canonicalPath,
+                });
+            }
+        }
+        if (conflicts.size === 0)
+            return;
+        const summary = Array.from(conflicts.values())
+            .slice(0, 8)
+            .map((conflict) => `${conflict.location}: ${conflict.candidate} -> ${conflict.canonical}`)
+            .join("; ");
+        throw new Error(`create-tasks failed canonical name validation for project "${projectKey}". Undocumented alternate implementation paths conflict with source-backed canonical names: ${summary}`);
+    }
+    formatTopologySignalSummary(signalSummary) {
+        return uniqueStrings([
+            ...signalSummary.structureServices.map((service) => `structure:${service}`),
+            ...signalSummary.topologyHeadings.map((heading) => `heading:${heading}`),
+            ...signalSummary.dependencyPairs.map((pair) => `dependency:${pair}`),
+            ...signalSummary.waveMentions.map((wave) => `wave:${wave}`),
+        ])
+            .slice(0, 10)
+            .join("; ");
+    }
+    validateTopologyExtraction(projectKey, expectation, graph) {
+        const topologySignals = expectation.signalSummary;
+        if (!expectation.runtimeBearing)
+            return topologySignals;
+        if (graph.services.length === 0) {
+            throw new Error(`create-tasks failed internal topology extraction for project "${projectKey}". SDS includes runtime topology signals but no services were resolved. Signals: ${this.formatTopologySignalSummary(topologySignals) || "unavailable"}`);
+        }
+        const missingServices = expectation.services.filter((service) => !graph.services.includes(service));
+        if (missingServices.length > 0) {
+            throw new Error(`create-tasks failed internal topology extraction for project "${projectKey}". Final planning artifacts lost source-backed services: ${missingServices.slice(0, 8).join(", ")}.`);
+        }
+        if (expectation.startupWaves.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("; ")}`);
+        }
+        const graphServicesByWave = new Map(graph.startupWaves.map((wave) => [wave.wave, new Set(wave.services)]));
+        const missingWaves = expectation.startupWaves
+            .map((wave) => wave.wave)
+            .filter((wave) => !graphServicesByWave.has(wave));
+        if (missingWaves.length > 0) {
+            throw new Error(`create-tasks failed internal topology extraction for project "${projectKey}". Final planning artifacts lost source-backed startup waves: ${missingWaves.slice(0, 8).join(", ")}.`);
+        }
+        const missingWaveServices = expectation.startupWaves.flatMap((wave) => {
+            const actualServices = graphServicesByWave.get(wave.wave);
+            return wave.services
+                .filter((service) => !(actualServices?.has(service) ?? false))
+                .map((service) => `wave ${wave.wave}:${service}`);
+        });
+        if (missingWaveServices.length > 0) {
+            throw new Error(`create-tasks failed internal topology extraction for project "${projectKey}". Final planning artifacts lost source-backed startup wave services: ${missingWaveServices.slice(0, 8).join(", ")}.`);
+        }
+        return topologySignals;
+    }
+    derivePlanningArtifacts(projectKey, docs, plan, expectation = this.buildSourceTopologyExpectation(docs)) {
+        const discoveryGraph = this.buildServiceDependencyGraph(plan, docs);
+        const topologySignals = this.validateTopologyExtraction(projectKey, expectation, discoveryGraph);
+        const serviceCatalog = this.buildServiceCatalogArtifact(projectKey, docs, discoveryGraph);
+        const projectBuildMethod = this.buildProjectConstructionMethod(docs, discoveryGraph);
+        const projectBuildPlan = this.buildProjectPlanArtifact(projectKey, docs, discoveryGraph, projectBuildMethod);
+        return {
+            discoveryGraph,
+            topologySignals,
+            serviceCatalog,
+            projectBuildMethod,
+            projectBuildPlan,
+        };
+    }
     normalizeServiceId(value) {
         const normalizedName = this.normalizeServiceName(value);
         if (!normalizedName)
@@ -1667,6 +2361,7 @@ export class CreateTasksService {
         const sourceDocs = docs
             .map((doc) => doc.path ?? (doc.id ? `docdex:${doc.id}` : doc.title ?? "doc"))
             .filter((value) => Boolean(value))
+            .filter((value, index, items) => items.indexOf(value) === index)
             .slice(0, 24);
         return {
             projectKey,
@@ -1889,8 +2584,16 @@ export class CreateTasksService {
     buildProjectConstructionMethod(docs, graph) {
         const toLabel = (value) => value.replace(/\s+/g, "-");
         const structureTargets = this.extractStructureTargets(docs);
-        const topDirectories = structureTargets.directories.slice(0, 10);
-        const topFiles = structureTargets.files.slice(0, 10);
+        const sourceDocPaths = new Set(docs
+            .map((doc) => (doc.path ? path.relative(this.workspace.workspaceRoot, doc.path).replace(/\\/g, "/") : undefined))
+            .filter((value) => Boolean(value)));
+        const sourceDocDirectories = new Set(Array.from(sourceDocPaths)
+            .map((docPath) => path.posix.dirname(docPath))
+            .filter((dir) => dir && dir !== "."));
+        const buildDirectories = structureTargets.directories.filter((dir) => !sourceDocDirectories.has(dir));
+        const buildFiles = structureTargets.files.filter((file) => !sourceDocPaths.has(file));
+        const topDirectories = (buildDirectories.length > 0 ? buildDirectories : structureTargets.directories).slice(0, 10);
+        const topFiles = (buildFiles.length > 0 ? buildFiles : structureTargets.files).slice(0, 10);
         const startupWaveLines = graph.startupWaves
             .slice(0, 8)
             .map((wave) => `- Wave ${wave.wave}: ${wave.services.map(toLabel).join(", ")}`);
@@ -1915,7 +2618,9 @@ export class CreateTasksService {
             ...(graph.foundationalDependencies.length > 0
                 ? graph.foundationalDependencies.map((dependency) => `   - foundation: ${dependency}`)
                 : ["   - foundation: infer runtime prerequisites from SDS deployment sections"]),
-            ...(startupWaveLines.length > 0 ? startupWaveLines : ["   - startup waves: infer from dependency contracts"]),
+            ...(startupWaveLines.length > 0
+                ? startupWaveLines
+                : ["   - startup waves: infer from documented dependency constraints"]),
             "3) Implement services by dependency direction and startup wave.",
             `   - service order: ${serviceOrderLine}`,
             ...(dependencyPairs.length > 0
@@ -1929,6 +2634,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,
@@ -1941,27 +2647,591 @@ export class CreateTasksService {
             buildMethod,
         };
     }
-    orderStoryTasksByDependencies(storyTasks, serviceRank, taskServiceByScope) {
-        const byLocalId = new Map(storyTasks.map((task) => [task.localId, task]));
-        const indegree = new Map();
-        const outgoing = new Map();
-        for (const task of storyTasks) {
-            indegree.set(task.localId, 0);
-        }
-        for (const task of storyTasks) {
-            for (const dep of task.dependsOnKeys ?? []) {
-                if (!byLocalId.has(dep) || dep === task.localId)
-                    continue;
-                indegree.set(task.localId, (indegree.get(task.localId) ?? 0) + 1);
-                const edges = outgoing.get(dep) ?? new Set();
-                edges.add(task.localId);
-                outgoing.set(dep, edges);
+    scoreServiceUnitForText(unit, text, graph) {
+        const normalizedText = this.normalizeServiceLookupKey(text);
+        if (!normalizedText)
+            return 0;
+        const tokens = normalizedText
+            .split(" ")
+            .map((token) => token.trim())
+            .filter((token) => token.length >= 3);
+        if (tokens.length === 0)
+            return 0;
+        const unitCorpus = this.normalizeServiceLookupKey([
+            unit.serviceName,
+            ...unit.aliases,
+            ...unit.directories,
+            ...unit.files,
+            ...unit.headings,
+            ...unit.dependsOnServiceIds,
+        ].join("\n"));
+        const overlap = tokens.filter((token) => unitCorpus.includes(token)).length;
+        let score = overlap * 10;
+        const direct = this.resolveServiceMentionFromPhrase(text, graph.aliases);
+        if (direct && unit.serviceName === direct)
+            score += 100;
+        if (normalizedText.includes(this.normalizeServiceLookupKey(unit.serviceName)))
+            score += 25;
+        if (unit.isFoundational)
+            score += 4;
+        return score;
+    }
+    buildSdsServiceUnits(docs, catalog, graph) {
+        const units = new Map();
+        const serviceById = new Map(catalog.services.map((service) => [service.id, service]));
+        const serviceByName = new Map(catalog.services.map((service) => [service.name, service]));
+        const orderedServiceIds = catalog.services.map((service) => service.id);
+        const primaryFoundationalServiceId = catalog.services.find((service) => service.isFoundational)?.id ?? catalog.services[0]?.id;
+        const opsServiceId = catalog.services.find((service) => /\b(ops|operation|deploy|infra|runtime|platform)\b/.test(this.normalizeServiceLookupKey([service.name, ...service.aliases].join(" "))))?.id ?? primaryFoundationalServiceId;
+        const coverageSignals = collectSdsCoverageSignalsFromDocs(docs.map((doc) => ({ content: doc.content })), { headingLimit: 200, folderLimit: 240 });
+        const structureTargets = this.extractStructureTargets(docs);
+        const runtimeComponents = this.extractRuntimeComponentNames(docs);
+        const ensureUnit = (serviceId) => {
+            if (!serviceId)
+                return undefined;
+            const service = serviceById.get(serviceId);
+            if (!service)
+                return undefined;
+            const existing = units.get(serviceId);
+            if (existing)
+                return existing;
+            const unit = {
+                serviceId: service.id,
+                serviceName: service.name,
+                aliases: uniqueStrings([service.name, ...service.aliases]),
+                startupWave: service.startupWave,
+                dependsOnServiceIds: [...service.dependsOnServiceIds],
+                directories: [],
+                files: [],
+                headings: [],
+                isFoundational: service.isFoundational,
+            };
+            units.set(serviceId, unit);
+            return unit;
+        };
+        for (const serviceId of orderedServiceIds)
+            ensureUnit(serviceId);
+        const selectUnitForText = (text, options) => {
+            const directName = this.resolveServiceMentionFromPhrase(text, graph.aliases);
+            if (directName) {
+                const direct = serviceByName.get(directName);
+                if (direct)
+                    return ensureUnit(direct.id);
+            }
+            const pathMatch = options?.pathLike ? this.deriveServiceFromPathToken(text) : undefined;
+            if (pathMatch) {
+                const fromPath = serviceByName.get(pathMatch);
+                if (fromPath)
+                    return ensureUnit(fromPath.id);
+            }
+            let bestUnit;
+            let bestScore = 0;
+            for (const unit of units.values()) {
+                const score = this.scoreServiceUnitForText(unit, text, graph);
+                if (score > bestScore) {
+                    bestScore = score;
+                    bestUnit = unit;
+                }
+            }
+            if (bestUnit && bestScore > 0)
+                return bestUnit;
+            const normalizedText = this.normalizeServiceLookupKey(text);
+            if (/\b(deploy|deployment|startup|rollback|recovery|observability|quality|release|failover|runbook|environment|secret|compute|operations?)\b/.test(normalizedText)) {
+                return ensureUnit(opsServiceId);
             }
+            return ensureUnit(primaryFoundationalServiceId);
+        };
+        for (const directory of structureTargets.directories) {
+            const unit = selectUnitForText(directory, { pathLike: true });
+            if (!unit)
+                continue;
+            unit.directories.push(directory);
         }
-        const priorityComparator = (a, b) => {
-            const classA = classifyTask({ title: a.title ?? "", description: a.description, type: a.type });
-            const classB = classifyTask({ title: b.title ?? "", description: b.description, type: b.type });
-            if (classA.foundation !== classB.foundation)
+        for (const file of structureTargets.files) {
+            const unit = selectUnitForText(file, { pathLike: true });
+            if (!unit)
+                continue;
+            unit.files.push(file);
+            const parent = path.dirname(file).replace(/\\/g, "/");
+            if (parent && parent !== ".")
+                unit.directories.push(parent);
+        }
+        for (const heading of coverageSignals.sectionHeadings) {
+            const unit = selectUnitForText(heading);
+            if (!unit)
+                continue;
+            unit.headings.push(normalizeHeadingCandidate(heading));
+        }
+        for (const component of runtimeComponents) {
+            const unit = selectUnitForText(component);
+            if (!unit)
+                continue;
+            unit.headings.push(normalizeHeadingCandidate(component));
+        }
+        return catalog.services
+            .map((service) => units.get(service.id))
+            .filter((unit) => Boolean(unit))
+            .map((unit) => ({
+            ...unit,
+            aliases: uniqueStrings(unit.aliases).sort((a, b) => a.localeCompare(b)),
+            directories: uniqueStrings(unit.directories).sort((a, b) => a.length - b.length || a.localeCompare(b)),
+            files: uniqueStrings(unit.files).sort((a, b) => a.length - b.length || a.localeCompare(b)),
+            headings: uniqueStrings(unit.headings),
+        }));
+    }
+    buildSdsDrivenPlan(projectKey, docs, catalog, graph) {
+        const units = this.buildSdsServiceUnits(docs, catalog, graph);
+        const verificationSuites = this.extractVerificationSuites(docs);
+        const acceptanceScenarios = this.extractAcceptanceScenarios(docs);
+        const localIds = new Set();
+        const epics = [];
+        const stories = [];
+        const tasks = [];
+        const rootPreview = (items, fallback) => items.length > 0 ? items.slice(0, 8).map((item) => `- ${item}`).join("\n") : `- ${fallback}`;
+        const chunk = (items, size) => {
+            const chunks = [];
+            for (let index = 0; index < items.length; index += size) {
+                chunks.push(items.slice(index, index + size));
+            }
+            return chunks;
+        };
+        const toDisplayName = (value) => value
+            .split(/\s+/)
+            .map((token) => (token ? token[0].toUpperCase() + token.slice(1) : token))
+            .join(" ");
+        const defaultArea = normalizeArea(projectKey) ?? "core";
+        for (const unit of units) {
+            const epicLocalId = nextUniqueLocalId(`svc-${unit.serviceId}`, localIds);
+            const epicTitle = `Build ${toDisplayName(unit.serviceName)}`;
+            epics.push({
+                localId: epicLocalId,
+                area: defaultArea,
+                title: epicTitle,
+                description: [
+                    `Implement the ${unit.serviceName} build slice from the SDS.`,
+                    unit.startupWave !== undefined ? `Startup wave: ${unit.startupWave}.` : undefined,
+                    unit.dependsOnServiceIds.length > 0
+                        ? `Dependencies: ${unit.dependsOnServiceIds.join(", ")}.`
+                        : "Dependencies: foundational or none.",
+                    unit.headings.length > 0
+                        ? `Covered SDS sections: ${unit.headings.slice(0, 5).join("; ")}.`
+                        : undefined,
+                ]
+                    .filter(Boolean)
+                    .join("\n"),
+                acceptanceCriteria: [
+                    `${unit.serviceName} structure and implementation surfaces are represented in the backlog.`,
+                    `${unit.serviceName} sequencing stays aligned to SDS dependency and startup ordering.`,
+                    `${unit.serviceName} validation work exists for the implemented scope.`,
+                ],
+                relatedDocs: docs
+                    .map((doc) => (doc.id ? `docdex:${doc.id}` : undefined))
+                    .filter((value) => Boolean(value))
+                    .slice(0, 12),
+                priorityHint: epics.length + 1,
+                serviceIds: [unit.serviceId],
+                tags: unit.isFoundational ? ["foundational"] : [],
+                stories: [],
+            });
+            if (unit.directories.length > 0 || unit.files.length > 0) {
+                const storyLocalId = nextUniqueLocalId(`svc-${unit.serviceId}-structure`, localIds);
+                stories.push({
+                    localId: storyLocalId,
+                    epicLocalId,
+                    title: `Establish ${toDisplayName(unit.serviceName)} structure`,
+                    userStory: `As an engineer, I need the ${unit.serviceName} scaffold in place before implementation continues.`,
+                    description: [
+                        `Create the SDS-defined folder and file scaffold for ${unit.serviceName}.`,
+                        "Use the documented target tree as the implementation baseline.",
+                    ].join("\n"),
+                    acceptanceCriteria: [
+                        `Required ${unit.serviceName} directories exist.`,
+                        `Required ${unit.serviceName} file entrypoints are present or explicitly queued in dependent tasks.`,
+                        `Follow-up tasks can reference real ${unit.serviceName} implementation paths.`,
+                    ],
+                    relatedDocs: [],
+                    priorityHint: 1,
+                    tasks: [],
+                });
+                const directoryChunks = chunk(unit.directories, 6);
+                const fileChunks = chunk(unit.files, 5);
+                if (directoryChunks.length > 0) {
+                    tasks.push({
+                        localId: nextUniqueLocalId(`svc-${unit.serviceId}-structure-task`, localIds),
+                        storyLocalId,
+                        epicLocalId,
+                        title: `Create ${unit.serviceName} directory scaffold`,
+                        type: "chore",
+                        description: [
+                            `Create the initial ${unit.serviceName} repository structure required by the SDS.`,
+                            "Target directories:",
+                            rootPreview(directoryChunks[0] ?? [], "Infer the concrete runtime directories from the SDS build tree."),
+                        ].join("\n"),
+                        estimatedStoryPoints: 2,
+                        priorityHint: 1,
+                        dependsOnKeys: [],
+                        relatedDocs: [],
+                        unitTests: [],
+                        componentTests: [],
+                        integrationTests: [],
+                        apiTests: [],
+                    });
+                }
+                if (fileChunks.length > 0) {
+                    const structureFileTargets = this.selectBuildTargets(unit, [`${unit.serviceName} structure entrypoints`], "structure", 5);
+                    tasks.push({
+                        localId: nextUniqueLocalId(`svc-${unit.serviceId}-structure-task`, localIds),
+                        storyLocalId,
+                        epicLocalId,
+                        title: `Create ${unit.serviceName} runtime entrypoints`,
+                        type: "feature",
+                        description: [
+                            `Create or stub the first concrete ${unit.serviceName} implementation files from the SDS folder tree.`,
+                            "Target files:",
+                            rootPreview(structureFileTargets.length > 0 ? structureFileTargets : fileChunks[0] ?? [], "Create the primary runtime entrypoints and implementation surfaces."),
+                        ].join("\n"),
+                        estimatedStoryPoints: 3,
+                        priorityHint: 2,
+                        dependsOnKeys: tasks.filter((task) => task.storyLocalId === storyLocalId).map((task) => task.localId),
+                        relatedDocs: [],
+                        unitTests: [],
+                        componentTests: [],
+                        integrationTests: [],
+                        apiTests: [],
+                    });
+                }
+            }
+            if (unit.headings.length > 0 || unit.files.length > 0) {
+                const storyLocalId = nextUniqueLocalId(`svc-${unit.serviceId}-implementation`, localIds);
+                stories.push({
+                    localId: storyLocalId,
+                    epicLocalId,
+                    title: `Implement ${toDisplayName(unit.serviceName)} capabilities`,
+                    userStory: `As a delivery team, we need the ${unit.serviceName} capability set implemented from the SDS.`,
+                    description: [
+                        `Implement the ${unit.serviceName} behavior defined across the SDS sections assigned to this build slice.`,
+                        unit.headings.length > 0 ? `Primary SDS sections: ${unit.headings.slice(0, 6).join("; ")}.` : undefined,
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                    acceptanceCriteria: [
+                        `${unit.serviceName} covers its assigned SDS capability sections.`,
+                        `${unit.serviceName} implementation targets are concrete and source-backed.`,
+                        `${unit.serviceName} leaves no generic placeholder work inside this story.`,
+                    ],
+                    relatedDocs: [],
+                    priorityHint: 2,
+                    tasks: [],
+                });
+                const headingChunks = chunk(unit.headings.length > 0 ? unit.headings : [`${unit.serviceName} runtime implementation`], 2);
+                headingChunks.slice(0, 6).forEach((group, index) => {
+                    const targetSlice = this.selectBuildTargets(unit, group, "implementation", 3);
+                    tasks.push({
+                        localId: nextUniqueLocalId(`svc-${unit.serviceId}-implementation-task`, localIds),
+                        storyLocalId,
+                        epicLocalId,
+                        title: `Implement ${group[0] ?? unit.serviceName}`,
+                        type: "feature",
+                        description: [
+                            `Implement the ${unit.serviceName} scope required by these SDS sections: ${group.join("; ")}.`,
+                            "Primary implementation targets:",
+                            rootPreview(targetSlice, `Extend the SDS-defined ${unit.serviceName} runtime surfaces captured in this build slice.`),
+                            unit.dependsOnServiceIds.length > 0
+                                ? `Keep dependency direction aligned to: ${unit.dependsOnServiceIds.join(", ")}.`
+                                : "Keep this slice buildable without introducing undocumented dependencies.",
+                        ].join("\n"),
+                        estimatedStoryPoints: Math.min(8, 3 + Math.max(0, Math.max(1, targetSlice.length) - 1)),
+                        priorityHint: index + 1,
+                        dependsOnKeys: [],
+                        relatedDocs: [],
+                        unitTests: targetSlice.length > 0 ? [`Cover ${unit.serviceName} implementation behavior for ${targetSlice[0]}.`] : [],
+                        componentTests: [],
+                        integrationTests: [],
+                        apiTests: [],
+                    });
+                });
+            }
+            if (unit.dependsOnServiceIds.length > 0) {
+                const storyLocalId = nextUniqueLocalId(`svc-${unit.serviceId}-integration`, localIds);
+                stories.push({
+                    localId: storyLocalId,
+                    epicLocalId,
+                    title: `Integrate ${toDisplayName(unit.serviceName)} dependencies`,
+                    userStory: `As an engineer, I need ${unit.serviceName} wired to its SDS-defined dependencies and interfaces.`,
+                    description: [
+                        `Implement dependency and interface wiring for ${unit.serviceName}.`,
+                        `SDS dependency chain: ${unit.dependsOnServiceIds.join(", ")}.`,
+                    ].join("\n"),
+                    acceptanceCriteria: [
+                        `${unit.serviceName} dependency integration is explicit and ordered.`,
+                        `${unit.serviceName} uses only documented runtime dependencies.`,
+                    ],
+                    relatedDocs: [],
+                    priorityHint: 3,
+                    tasks: [],
+                });
+                unit.dependsOnServiceIds.slice(0, 4).forEach((dependencyId, index) => {
+                    tasks.push({
+                        localId: nextUniqueLocalId(`svc-${unit.serviceId}-integration-task`, localIds),
+                        storyLocalId,
+                        epicLocalId,
+                        title: `Wire ${unit.serviceName} to ${dependencyId}`,
+                        type: "feature",
+                        description: [
+                            `Implement the SDS-defined dependency direction from ${unit.serviceName} to ${dependencyId}.`,
+                            "Update runtime interfaces, configuration reads, or orchestration flow as required.",
+                        ].join("\n"),
+                        estimatedStoryPoints: 2,
+                        priorityHint: index + 1,
+                        dependsOnKeys: [],
+                        relatedDocs: [],
+                        unitTests: [],
+                        componentTests: [],
+                        integrationTests: [`Validate ${unit.serviceName} integration with ${dependencyId}.`],
+                        apiTests: [],
+                    });
+                });
+            }
+            const verificationStoryLocalId = nextUniqueLocalId(`svc-${unit.serviceId}-verification`, localIds);
+            stories.push({
+                localId: verificationStoryLocalId,
+                epicLocalId,
+                title: `Verify ${toDisplayName(unit.serviceName)} readiness`,
+                userStory: `As a reviewer, I need concrete verification evidence for ${unit.serviceName}.`,
+                description: [
+                    `Add the validation work needed to prove ${unit.serviceName} against the SDS.`,
+                    unit.headings.length > 0 ? `Verification should cover: ${unit.headings.slice(0, 4).join("; ")}.` : undefined,
+                ]
+                    .filter(Boolean)
+                    .join("\n"),
+                acceptanceCriteria: [
+                    `${unit.serviceName} has deterministic validation coverage.`,
+                    `${unit.serviceName} evidence maps back to SDS responsibilities.`,
+                ],
+                relatedDocs: [],
+                priorityHint: 4,
+                tasks: [],
+            });
+            tasks.push({
+                localId: nextUniqueLocalId(`svc-${unit.serviceId}-verification-task`, localIds),
+                storyLocalId: verificationStoryLocalId,
+                epicLocalId,
+                title: `Add ${unit.serviceName} focused test coverage`,
+                type: "chore",
+                description: [
+                    `Add or update the smallest deterministic validation surface that proves ${unit.serviceName}.`,
+                    "Cover the implemented runtime paths, dependency behavior, and SDS acceptance expectations for this build slice.",
+                    "Primary verification targets:",
+                    rootPreview(this.selectBuildTargets(unit, [...unit.headings, `${unit.serviceName} verification`], "verification", 3), `Capture service-local validation against ${unit.serviceName} runtime surfaces.`),
+                ].join("\n"),
+                estimatedStoryPoints: 2,
+                priorityHint: 1,
+                dependsOnKeys: [],
+                relatedDocs: [],
+                unitTests: [`Validate ${unit.serviceName} internal behavior.`],
+                componentTests: unit.files.some((file) => /\b(ui|web|component|page|screen)\b/i.test(file))
+                    ? [`Validate ${unit.serviceName} component-level behavior.`]
+                    : [],
+                integrationTests: [`Validate ${unit.serviceName} end-to-end dependency behavior.`],
+                apiTests: [],
+            });
+        }
+        if (verificationSuites.length > 0 || acceptanceScenarios.length > 0) {
+            const releaseEpicLocalId = nextUniqueLocalId("release-verification", localIds);
+            epics.push({
+                localId: releaseEpicLocalId,
+                area: defaultArea,
+                title: "Verify Release Readiness",
+                description: [
+                    "Execute the named verification suites and acceptance scenarios documented in the SDS release gate.",
+                    verificationSuites.length > 0
+                        ? `Named suites: ${verificationSuites.map((suite) => suite.name).slice(0, 8).join("; ")}.`
+                        : undefined,
+                    acceptanceScenarios.length > 0
+                        ? `Acceptance scenarios: ${acceptanceScenarios.length} documented launch scenarios must be green.`
+                        : undefined,
+                ]
+                    .filter(Boolean)
+                    .join("\n"),
+                acceptanceCriteria: [
+                    "Every named verification suite from the SDS is represented as executable backlog work.",
+                    "Every required acceptance scenario from the SDS is represented as executable backlog work.",
+                    "Release verification evidence maps back to the SDS release gate.",
+                ],
+                relatedDocs: docs
+                    .map((doc) => (doc.id ? `docdex:${doc.id}` : undefined))
+                    .filter((value) => Boolean(value))
+                    .slice(0, 12),
+                priorityHint: epics.length + 1,
+                serviceIds: uniqueStrings(units.map((unit) => unit.serviceId)).slice(0, 12),
+                tags: [CROSS_SERVICE_TAG],
+                stories: [],
+            });
+            if (verificationSuites.length > 0) {
+                const verificationStoryLocalId = nextUniqueLocalId("release-verification-suites", localIds);
+                stories.push({
+                    localId: verificationStoryLocalId,
+                    epicLocalId: releaseEpicLocalId,
+                    title: "Execute named verification suites",
+                    userStory: "As a release reviewer, I need every named SDS verification suite to exist as executable backlog work.",
+                    description: "Create the exact named verification suites from the SDS verification matrix and map them to deterministic evidence.",
+                    acceptanceCriteria: [
+                        "All named SDS verification suites have backlog tasks with explicit scope.",
+                        "Suite tasks reference the exact SDS suite names instead of generic test placeholders.",
+                    ],
+                    relatedDocs: [],
+                    priorityHint: 1,
+                    tasks: [],
+                });
+                verificationSuites.forEach((suite, index) => {
+                    const draft = this.buildVerificationSuiteTaskDraft(suite, "the release slice");
+                    tasks.push({
+                        localId: nextUniqueLocalId("release-verification-suite-task", localIds),
+                        storyLocalId: verificationStoryLocalId,
+                        epicLocalId: releaseEpicLocalId,
+                        title: `Execute suite: ${suite.name}`,
+                        type: "chore",
+                        description: draft.description,
+                        estimatedStoryPoints: /\b(end-to-end|acceptance|drill|integration)\b/i.test(suite.name) ? 3 : 2,
+                        priorityHint: index + 1,
+                        dependsOnKeys: [],
+                        relatedDocs: [],
+                        unitTests: draft.unitTests,
+                        componentTests: draft.componentTests,
+                        integrationTests: draft.integrationTests,
+                        apiTests: draft.apiTests,
+                    });
+                });
+            }
+            if (acceptanceScenarios.length > 0) {
+                const scenarioStoryLocalId = nextUniqueLocalId("release-acceptance-scenarios", localIds);
+                stories.push({
+                    localId: scenarioStoryLocalId,
+                    epicLocalId: releaseEpicLocalId,
+                    title: "Run required acceptance scenarios",
+                    userStory: "As a launch approver, I need every required acceptance scenario executed before release.",
+                    description: "Create one executable backlog task per SDS acceptance scenario so launch approval is tied to concrete scenario evidence.",
+                    acceptanceCriteria: [
+                        "All numbered SDS acceptance scenarios exist as backlog tasks.",
+                        "Scenario tasks preserve the SDS launch wording closely enough for release review.",
+                    ],
+                    relatedDocs: [],
+                    priorityHint: 2,
+                    tasks: [],
+                });
+                acceptanceScenarios.forEach((scenario) => {
+                    tasks.push({
+                        localId: nextUniqueLocalId("release-acceptance-scenario-task", localIds),
+                        storyLocalId: scenarioStoryLocalId,
+                        epicLocalId: releaseEpicLocalId,
+                        title: `Validate acceptance scenario ${scenario.index}: ${scenario.title}`,
+                        type: "chore",
+                        description: [
+                            `Execute SDS acceptance scenario ${scenario.index}.`,
+                            scenario.details,
+                            "Capture deterministic pass/fail evidence and link it to the release gate.",
+                        ].join("\n"),
+                        estimatedStoryPoints: 2,
+                        priorityHint: scenario.index,
+                        dependsOnKeys: [],
+                        relatedDocs: [],
+                        unitTests: [],
+                        componentTests: [],
+                        integrationTests: [`Execute acceptance scenario ${scenario.index} end to end.`],
+                        apiTests: [],
+                    });
+                });
+            }
+        }
+        return { epics, stories, tasks };
+    }
+    hasStrongSdsPlanningEvidence(docs, catalog, expectation) {
+        const sdsDocs = docs.filter((doc) => looksLikeSdsDoc(doc));
+        if (sdsDocs.length === 0)
+            return false;
+        const coverageSignals = collectSdsCoverageSignalsFromDocs(docs.map((doc) => ({ content: doc.content })), { headingLimit: 200, folderLimit: 240 });
+        const structureTargets = this.extractStructureTargets(docs);
+        const structureSignalCount = structureTargets.directories.length + structureTargets.files.length;
+        const headingSignalCount = coverageSignals.sectionHeadings.length;
+        const topologySignalCount = expectation.services.length +
+            expectation.startupWaves.length +
+            expectation.dependencyPairs.length +
+            expectation.signalSummary.topologyHeadings.length +
+            expectation.signalSummary.waveMentions.length;
+        return (structureSignalCount >= 4 ||
+            headingSignalCount >= 8 ||
+            catalog.services.length >= 2 ||
+            topologySignalCount >= 4);
+    }
+    taskUsesOnlyWeakImplementationTargets(task, docs) {
+        if (!/\bimplement\b/i.test(`${task.title} ${task.description ?? ""}`))
+            return false;
+        const inventory = this.buildCanonicalNameInventory(docs);
+        if (!inventory.paths.some((candidate) => this.isStrongImplementationTarget(candidate)))
+            return false;
+        const candidateTargets = uniqueStrings(filterImplementationStructuredPaths(extractStructuredPaths(`${task.title}\n${task.description ?? ""}`, 64))
+            .map((token) => this.normalizeStructurePathToken(token))
+            .filter((value) => Boolean(value)));
+        if (candidateTargets.length === 0)
+            return false;
+        return candidateTargets.every((target) => !this.isStrongImplementationTarget(target));
+    }
+    planLooksTooWeakForSds(plan, docs, catalog, expectation) {
+        if (!this.hasStrongSdsPlanningEvidence(docs, catalog, expectation))
+            return false;
+        const genericTitles = plan.tasks.filter((task) => /initial planning|draft backlog|review inputs|baseline project scaffolding|integrate core dependencies|validate baseline behavior/i.test(`${task.title} ${task.description ?? ""}`)).length;
+        const genericImplementationTasks = plan.tasks.filter((task) => GENERIC_IMPLEMENTATION_TASK_PATTERN.test(`${task.title} ${task.description ?? ""}`)).length;
+        const weakImplementationTargetTasks = plan.tasks.filter((task) => this.taskUsesOnlyWeakImplementationTargets(task, docs)).length;
+        const verificationSuites = this.extractVerificationSuites(docs);
+        const acceptanceScenarios = this.extractAcceptanceScenarios(docs);
+        const planCorpus = this.normalizeServiceLookupKey([
+            ...plan.epics.map((epic) => `${epic.title}\n${epic.description ?? ""}`),
+            ...plan.stories.map((story) => `${story.title}\n${story.description ?? ""}\n${story.userStory ?? ""}`),
+            ...plan.tasks.map((task) => `${task.title}\n${task.description ?? ""}`),
+        ].join("\n"));
+        const coveredVerificationSuites = verificationSuites.filter((suite) => planCorpus.includes(this.normalizeServiceLookupKey(suite.name))).length;
+        const coveredAcceptanceScenarios = acceptanceScenarios.filter((scenario) => planCorpus.includes(`scenario ${scenario.index}`) ||
+            planCorpus.includes(this.normalizeServiceLookupKey(scenario.title))).length;
+        const coveredServiceIds = new Set(plan.epics.flatMap((epic) => normalizeStringArray(epic.serviceIds)));
+        return (plan.epics.length === 0 ||
+            plan.stories.length === 0 ||
+            plan.tasks.length === 0 ||
+            genericTitles >= Math.min(2, plan.tasks.length) ||
+            genericImplementationTasks > 0 ||
+            weakImplementationTargetTasks > 0 ||
+            (verificationSuites.length > 0 && coveredVerificationSuites === 0) ||
+            (acceptanceScenarios.length > 0 && coveredAcceptanceScenarios < Math.min(3, acceptanceScenarios.length)) ||
+            (genericTitles > 0 &&
+                catalog.services.length > 1 &&
+                coveredServiceIds.size > 0 &&
+                coveredServiceIds.size < Math.min(catalog.services.length, 2)));
+    }
+    backlogMostlyAlignedEnough(audit) {
+        if (!audit)
+            return true;
+        return audit.satisfied;
+    }
+    orderStoryTasksByDependencies(storyTasks, serviceRank, taskServiceByScope) {
+        const byLocalId = new Map(storyTasks.map((task) => [task.localId, task]));
+        const indegree = new Map();
+        const outgoing = new Map();
+        for (const task of storyTasks) {
+            indegree.set(task.localId, 0);
+        }
+        for (const task of storyTasks) {
+            for (const dep of task.dependsOnKeys ?? []) {
+                if (!byLocalId.has(dep) || dep === task.localId)
+                    continue;
+                indegree.set(task.localId, (indegree.get(task.localId) ?? 0) + 1);
+                const edges = outgoing.get(dep) ?? new Set();
+                edges.add(task.localId);
+                outgoing.set(dep, edges);
+            }
+        }
+        const priorityComparator = (a, b) => {
+            const classA = classifyTask({ title: a.title ?? "", description: a.description, type: a.type });
+            const classB = classifyTask({ title: b.title ?? "", description: b.description, type: b.type });
+            if (classA.foundation !== classB.foundation)
                 return classA.foundation ? -1 : 1;
             const rankA = serviceRank.get(taskServiceByScope.get(this.scopeTask(a)) ?? "") ?? Number.MAX_SAFE_INTEGER;
             const rankB = serviceRank.get(taskServiceByScope.get(this.scopeTask(b)) ?? "") ?? Number.MAX_SAFE_INTEGER;
@@ -2202,7 +3472,7 @@ export class CreateTasksService {
             .slice(0, 12);
         const bootstrapEpic = {
             localId: epicLocalId,
-            area: normalizeArea(projectKey) ?? "infra",
+            area: normalizeArea(projectKey) ?? "core",
             title: "Codebase Foundation and Structure Setup",
             description: "Create the SDS-defined codebase scaffold first (folders/files/service boundaries) before feature implementation tasks.",
             acceptanceCriteria: [
@@ -2564,17 +3834,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;
@@ -2584,6 +3869,336 @@ export class CreateTasksService {
         }
         return uniqueStrings(sections).slice(0, limit);
     }
+    collectSdsSections(docs) {
+        const sections = [];
+        for (const doc of docs) {
+            if (!looksLikeSdsDoc(doc))
+                continue;
+            const content = stripManagedSdsPreflightBlock(doc.content ?? "") ?? "";
+            const lines = content.split(/\r?\n/);
+            let currentHeading;
+            let currentBody = [];
+            let inCodeFence = false;
+            const flush = () => {
+                if (!currentHeading)
+                    return;
+                sections.push({ heading: currentHeading, body: [...currentBody] });
+            };
+            for (const rawLine of lines) {
+                const line = rawLine ?? "";
+                const trimmed = line.trim();
+                if (/^```/.test(trimmed)) {
+                    inCodeFence = !inCodeFence;
+                    currentBody.push(line);
+                    continue;
+                }
+                if (!inCodeFence) {
+                    const headingMatch = trimmed.match(MARKDOWN_HEADING_PATTERN);
+                    if (headingMatch) {
+                        flush();
+                        currentHeading = normalizeHeadingCandidate(headingMatch[2] ?? "");
+                        currentBody = [];
+                        continue;
+                    }
+                }
+                if (currentHeading)
+                    currentBody.push(line);
+            }
+            flush();
+        }
+        return sections;
+    }
+    normalizeRuntimeComponentCandidate(rawValue) {
+        let candidate = rawValue.trim();
+        if (!candidate)
+            return undefined;
+        const backtickMatch = candidate.match(/`([^`]+)`/);
+        if (backtickMatch?.[1]) {
+            candidate = backtickMatch[1];
+        }
+        const colonHead = candidate.split(/:\s+/, 2)[0]?.trim();
+        if (colonHead && colonHead.split(/\s+/).length <= 5) {
+            candidate = colonHead;
+        }
+        const dashHead = candidate.split(/\s+[—-]\s+/, 2)[0]?.trim();
+        if (dashHead && dashHead.split(/\s+/).length <= 5) {
+            candidate = dashHead;
+        }
+        candidate = candidate.replace(/\([^)]*\)/g, " ").replace(/[.;,]+$/, "").trim();
+        if (!candidate)
+            return undefined;
+        const normalized = this.normalizeTextServiceName(candidate) ?? this.normalizeServiceName(candidate);
+        if (!normalized)
+            return undefined;
+        if (normalized.split(" ").length > 4)
+            return undefined;
+        return normalized;
+    }
+    extractRuntimeComponentNames(docs) {
+        const components = new Set();
+        for (const section of this.collectSdsSections(docs)) {
+            if (!RUNTIME_COMPONENTS_HEADING_PATTERN.test(section.heading))
+                continue;
+            let inCodeFence = false;
+            for (const rawLine of section.body) {
+                const trimmed = rawLine.trim();
+                if (/^```/.test(trimmed)) {
+                    inCodeFence = !inCodeFence;
+                    continue;
+                }
+                if (inCodeFence)
+                    continue;
+                const listMatch = trimmed.match(/^(?:[-*]|\d+[.)])\s+(.+)$/);
+                if (!listMatch?.[1])
+                    continue;
+                const candidate = this.normalizeRuntimeComponentCandidate(listMatch[1]);
+                if (candidate)
+                    components.add(candidate);
+            }
+        }
+        return Array.from(components);
+    }
+    extractVerificationSuites(docs) {
+        const suites = [];
+        const seen = new Set();
+        for (const section of this.collectSdsSections(docs)) {
+            if (!VERIFICATION_MATRIX_HEADING_PATTERN.test(section.heading))
+                continue;
+            for (const rawLine of section.body) {
+                const trimmed = rawLine.trim();
+                if (!trimmed.startsWith("|"))
+                    continue;
+                if (/^\|\s*-+\s*\|/i.test(trimmed))
+                    continue;
+                const cells = trimmed
+                    .split("|")
+                    .map((cell) => cell.trim())
+                    .filter(Boolean);
+                if (cells.length < 2)
+                    continue;
+                if (/verification suite/i.test(cells[0] ?? ""))
+                    continue;
+                const name = normalizeHeadingCandidate(cells[0] ?? "");
+                if (!name)
+                    continue;
+                const key = this.normalizeServiceLookupKey(name);
+                if (!key || seen.has(key))
+                    continue;
+                seen.add(key);
+                suites.push({
+                    name,
+                    scope: cells[1] || undefined,
+                    sourceCoverage: cells[2] || undefined,
+                });
+            }
+        }
+        return suites;
+    }
+    extractAcceptanceScenarios(docs) {
+        const scenarios = [];
+        const seen = new Set();
+        for (const section of this.collectSdsSections(docs)) {
+            if (!ACCEPTANCE_SCENARIOS_HEADING_PATTERN.test(section.heading))
+                continue;
+            for (const rawLine of section.body) {
+                const trimmed = rawLine.trim();
+                const match = trimmed.match(/^(\d+)\.\s+(.+)$/);
+                if (!match?.[1] || !match[2])
+                    continue;
+                const index = Number.parseInt(match[1], 10);
+                if (!Number.isFinite(index) || seen.has(index))
+                    continue;
+                const details = match[2].trim();
+                const title = normalizeHeadingCandidate(details.split(/:\s+/, 2)[0] ?? details) || `Scenario ${index}`;
+                scenarios.push({ index, title, details });
+                seen.add(index);
+            }
+        }
+        return scenarios.sort((left, right) => left.index - right.index);
+    }
+    classifyBuildTarget(target) {
+        const normalized = this.normalizeStructurePathToken(target) ?? target.replace(/\\/g, "/").trim();
+        const segments = normalized
+            .toLowerCase()
+            .split("/")
+            .map((segment) => segment.trim())
+            .filter(Boolean);
+        const basename = segments[segments.length - 1] ?? normalized.toLowerCase();
+        const isFile = isStructuredFilePath(basename);
+        const isServiceArtifact = SERVICE_ARTIFACT_BASENAME_PATTERN.test(basename);
+        if (segments.some((segment) => BUILD_TARGET_DOC_SEGMENTS.has(segment))) {
+            return { normalized, basename, segments, isFile, kind: "doc", isServiceArtifact };
+        }
+        if (MANIFEST_TARGET_BASENAME_PATTERN.test(basename) || isServiceArtifact) {
+            return { normalized, basename, segments, isFile, kind: "manifest", isServiceArtifact };
+        }
+        if (segments.some((segment) => BUILD_TARGET_TEST_SEGMENTS.has(segment))) {
+            return { normalized, basename, segments, isFile, kind: "test", isServiceArtifact };
+        }
+        if (segments.some((segment) => BUILD_TARGET_OPS_SEGMENTS.has(segment))) {
+            return { normalized, basename, segments, isFile, kind: "ops", isServiceArtifact };
+        }
+        if (segments.some((segment) => BUILD_TARGET_INTERFACE_SEGMENTS.has(segment))) {
+            return { normalized, basename, segments, isFile, kind: "interface", isServiceArtifact };
+        }
+        if (segments.some((segment) => BUILD_TARGET_DATA_SEGMENTS.has(segment))) {
+            return { normalized, basename, segments, isFile, kind: "data", isServiceArtifact };
+        }
+        if (segments.some((segment) => BUILD_TARGET_RUNTIME_SEGMENTS.has(segment))) {
+            return { normalized, basename, segments, isFile, kind: "runtime", isServiceArtifact };
+        }
+        return { normalized, basename, segments, isFile, kind: "unknown", isServiceArtifact };
+    }
+    isStrongImplementationTarget(target) {
+        const classification = this.classifyBuildTarget(target);
+        return (classification.kind === "runtime" ||
+            classification.kind === "interface" ||
+            classification.kind === "data" ||
+            classification.kind === "test" ||
+            classification.kind === "ops");
+    }
+    deriveBuildFocusProfile(texts) {
+        const corpus = this.normalizeServiceLookupKey(texts.join("\n"));
+        return {
+            wantsOps: /\b(deploy|deployment|startup|release|rollback|recovery|rotation|drill|runbook|failover|proxy|operations?|runtime)\b/.test(corpus),
+            wantsVerification: /\b(verify|verification|acceptance|scenario|quality|suite|test|tests|matrix|gate|drill)\b/.test(corpus),
+            wantsData: /\b(data|storage|cache|ledger|pipeline|db|database|persistence)\b/.test(corpus),
+            wantsInterface: /\b(contract|policy|provider|gateway|rpc|api|interface|schema|oracle|protocol)\b/.test(corpus),
+        };
+    }
+    selectBuildTargets(unit, focusTexts, purpose, limit) {
+        const candidates = uniqueStrings([...unit.files, ...unit.directories])
+            .map((candidate) => this.normalizeStructurePathToken(candidate) ?? candidate.replace(/\\/g, "/").trim())
+            .filter(Boolean);
+        if (candidates.length === 0)
+            return [];
+        const focusCorpus = this.normalizeServiceLookupKey([unit.serviceName, ...unit.aliases, ...focusTexts].filter(Boolean).join("\n"));
+        const focusTokens = focusCorpus
+            .split(" ")
+            .map((token) => token.trim())
+            .filter((token) => token.length >= 3);
+        const focusProfile = this.deriveBuildFocusProfile(focusTexts);
+        const scored = candidates
+            .map((target) => {
+            const classification = this.classifyBuildTarget(target);
+            const normalizedTarget = this.normalizeServiceLookupKey(target.replace(/\//g, " "));
+            const overlap = focusTokens.filter((token) => normalizedTarget.includes(token)).length;
+            let score = overlap * 25 + (classification.isFile ? 12 : 0);
+            if (purpose === "structure") {
+                if (classification.kind === "runtime" || classification.kind === "interface")
+                    score += 90;
+                else if (classification.kind === "data")
+                    score += 75;
+                else if (classification.kind === "ops")
+                    score += 30;
+                else if (classification.kind === "manifest")
+                    score += 10;
+                else if (classification.kind === "doc")
+                    score -= 80;
+            }
+            else if (purpose === "implementation") {
+                if (classification.kind === "runtime")
+                    score += classification.isFile ? 170 : 140;
+                else if (classification.kind === "interface")
+                    score += classification.isFile ? 160 : 135;
+                else if (classification.kind === "data")
+                    score += classification.isFile ? 150 : 125;
+                else if (classification.kind === "test")
+                    score += 70;
+                else if (classification.kind === "ops")
+                    score += focusProfile.wantsOps ? 140 : 25;
+                else if (classification.kind === "manifest")
+                    score -= 140;
+                else if (classification.kind === "doc")
+                    score -= 180;
+            }
+            else {
+                if (classification.kind === "test")
+                    score += 170;
+                else if (classification.kind === "runtime")
+                    score += 120;
+                else if (classification.kind === "interface")
+                    score += 105;
+                else if (classification.kind === "data")
+                    score += 95;
+                else if (classification.kind === "ops")
+                    score += focusProfile.wantsOps ? 160 : 90;
+                else if (classification.kind === "manifest")
+                    score -= 120;
+                else if (classification.kind === "doc")
+                    score -= 180;
+            }
+            if (focusProfile.wantsOps && classification.kind === "ops")
+                score += 60;
+            if (focusProfile.wantsVerification && classification.kind === "test")
+                score += 60;
+            if (focusProfile.wantsData && classification.kind === "data")
+                score += 55;
+            if (focusProfile.wantsInterface && classification.kind === "interface")
+                score += 55;
+            if (focusProfile.wantsInterface && classification.kind === "runtime")
+                score += 20;
+            return { target, classification, score };
+        })
+            .sort((left, right) => right.score - left.score || left.target.length - right.target.length || left.target.localeCompare(right.target));
+        const strongExists = scored.some((entry) => entry.score > 0 &&
+            (entry.classification.kind === "runtime" ||
+                entry.classification.kind === "interface" ||
+                entry.classification.kind === "data" ||
+                entry.classification.kind === "test" ||
+                entry.classification.kind === "ops"));
+        const filtered = scored.filter((entry) => {
+            if (entry.score <= 0)
+                return false;
+            if (!strongExists)
+                return true;
+            if (purpose === "structure")
+                return entry.classification.kind !== "doc";
+            if (entry.classification.kind === "manifest")
+                return false;
+            return entry.classification.kind !== "doc";
+        });
+        const ranked = (filtered.length > 0 ? filtered : scored.filter((entry) => entry.score > 0)).map((entry) => entry.target);
+        return uniqueStrings(ranked).slice(0, Math.max(1, limit));
+    }
+    buildVerificationSuiteTaskDraft(suite, serviceName) {
+        const normalized = this.normalizeServiceLookupKey([suite.name, suite.scope, suite.sourceCoverage].filter(Boolean).join(" "));
+        const unitTests = [];
+        const componentTests = [];
+        const integrationTests = [];
+        const apiTests = [];
+        if (/\bunit\b/.test(normalized)) {
+            unitTests.push(`Execute the named suite "${suite.name}" for ${serviceName}.`);
+        }
+        if (/\b(component|ui|render|client)\b/.test(normalized)) {
+            componentTests.push(`Execute the named suite "${suite.name}" against the ${serviceName} surface.`);
+        }
+        if (/\b(integration|acceptance|end to end|end-to-end|drill|replay|failover)\b/.test(normalized)) {
+            integrationTests.push(`Execute the named suite "${suite.name}" end to end for ${serviceName}.`);
+        }
+        if (/\b(api|gateway|rpc|provider)\b/.test(normalized)) {
+            apiTests.push(`Execute the named suite "${suite.name}" against the ${serviceName} API/provider surface.`);
+        }
+        if (unitTests.length === 0 &&
+            componentTests.length === 0 &&
+            integrationTests.length === 0 &&
+            apiTests.length === 0) {
+            integrationTests.push(`Execute the named suite "${suite.name}" and capture deterministic evidence.`);
+        }
+        return {
+            description: [
+                `Implement and wire the named verification suite "${suite.name}" for ${serviceName}.`,
+                suite.scope ? `Scope: ${suite.scope}` : undefined,
+                suite.sourceCoverage ? `Source coverage: ${suite.sourceCoverage}` : undefined,
+            ]
+                .filter(Boolean)
+                .join("\n"),
+            unitTests,
+            componentTests,
+            integrationTests,
+            apiTests,
+        };
+    }
     buildSdsCoverageHints(docs) {
         const hints = this.extractSdsSectionCandidates(docs, SDS_COVERAGE_HINT_HEADING_LIMIT);
         if (hints.length === 0)
@@ -2654,8 +4269,213 @@ export class CreateTasksService {
         }
         return { docSummary: blocks.join("\n\n") || "(no docs)", warnings };
     }
-    buildPrompt(projectKey, docs, projectBuildMethod, serviceCatalog, options) {
-        const docSummary = docs.map((doc, idx) => describeDoc(doc, idx)).join("\n");
+    buildCreateTasksAgentMission(projectKey) {
+        return [
+            `You are the orchestration agent for mcoda create-tasks on project ${projectKey}.`,
+            "Your job in this run is to turn the SDS and supporting docs into an executable backlog that is enough to build the documented product.",
+            "You must understand the services/tools that need to exist, define implementation epics, define the user stories needed to finish each epic, and define the concrete tasks needed to finish each story.",
+            "Keep every phase aligned to the SDS folder tree, runtime topology, dependency order, startup waves, verification suites, acceptance scenarios, and named implementation targets.",
+            "Use only canonical documented names for services, modules, interfaces, commands, schemas, files, and runtime artifacts.",
+            "Do not invent stack choices, rename documented targets, emit placeholder work, or defer SDS gaps to a later manual pass.",
+            "If coverage gaps remain, refine the backlog itself until the backlog is enough to build the product.",
+        ].join("\n");
+    }
+    schemaSnippetForAction(action) {
+        switch (action) {
+            case "epics":
+                return EPIC_SCHEMA_SNIPPET;
+            case "stories":
+                return STORY_SCHEMA_SNIPPET;
+            case "tasks":
+                return TASK_SCHEMA_SNIPPET;
+            case "full_plan":
+                return FULL_PLAN_SCHEMA_SNIPPET;
+            default:
+                return FULL_PLAN_SCHEMA_SNIPPET;
+        }
+    }
+    buildPlanOutline(plan, options) {
+        const maxEpics = options?.maxEpics ?? 16;
+        const maxStoriesPerEpic = options?.maxStoriesPerEpic ?? 8;
+        const maxTasksPerStory = options?.maxTasksPerStory ?? 10;
+        const summary = {
+            epics: plan.epics.slice(0, maxEpics).map((epic) => ({
+                localId: epic.localId,
+                title: epic.title,
+                area: epic.area,
+                serviceIds: normalizeStringArray(epic.serviceIds),
+                tags: normalizeStringArray(epic.tags),
+                acceptanceCriteria: (epic.acceptanceCriteria ?? []).slice(0, 8),
+                stories: plan.stories
+                    .filter((story) => story.epicLocalId === epic.localId)
+                    .slice(0, maxStoriesPerEpic)
+                    .map((story) => ({
+                    localId: story.localId,
+                    title: story.title,
+                    userStory: story.userStory,
+                    acceptanceCriteria: (story.acceptanceCriteria ?? []).slice(0, 8),
+                    tasks: plan.tasks
+                        .filter((task) => task.epicLocalId === epic.localId && task.storyLocalId === story.localId)
+                        .slice(0, maxTasksPerStory)
+                        .map((task) => ({
+                        localId: task.localId,
+                        title: task.title,
+                        type: task.type,
+                        dependsOnKeys: normalizeStringArray(task.dependsOnKeys),
+                        description: task.description,
+                        unitTests: normalizeStringArray(task.unitTests),
+                        componentTests: normalizeStringArray(task.componentTests),
+                        integrationTests: normalizeStringArray(task.integrationTests),
+                        apiTests: normalizeStringArray(task.apiTests),
+                    })),
+                })),
+            })),
+        };
+        return JSON.stringify(summary, null, 2);
+    }
+    parseFullPlan(output, options) {
+        const parsed = extractJson(output);
+        if (!parsed || !Array.isArray(parsed.epics) || parsed.epics.length === 0) {
+            throw new Error("Agent did not return a full backlog plan in expected format");
+        }
+        return this.materializePlanFromSeed(parsed, options);
+    }
+    async normalizeGeneratedPlan(params) {
+        const normalizedPlanEpics = this.alignEpicsToServiceCatalog(params.plan.epics, params.serviceCatalog, params.unknownEpicServicePolicy);
+        for (const warning of normalizedPlanEpics.warnings) {
+            await this.jobService.appendLog(params.jobId, `[create-tasks] ${warning}\n`);
+        }
+        let plan = {
+            ...params.plan,
+            epics: normalizedPlanEpics.epics.map((epic, index) => ({
+                ...epic,
+                localId: epic.localId ?? `e${index + 1}`,
+                stories: [],
+            })),
+        };
+        plan = this.enforceStoryScopedDependencies(plan);
+        plan = this.injectStructureBootstrapPlan(plan, params.docs, params.serviceCatalog.projectKey);
+        plan = this.enforceStoryScopedDependencies(plan);
+        this.validatePlanLocalIdentifiers(plan);
+        plan = this.applyServiceDependencySequencing(plan, params.docs);
+        plan = this.enforceStoryScopedDependencies(plan);
+        this.validatePlanLocalIdentifiers(plan);
+        this.derivePlanningArtifacts(params.serviceCatalog.projectKey, params.docs, plan, params.sourceTopologyExpectation);
+        return plan;
+    }
+    buildRefinementPrompt(params) {
+        const serviceCatalogSummary = this.buildServiceCatalogPromptSummary(params.serviceCatalog);
+        const planOutline = this.buildPlanOutline(params.currentPlan, params.options);
+        const refinementLimits = [
+            params.options.maxEpics ? `- Limit epics to ${params.options.maxEpics}.` : "",
+            params.options.maxStoriesPerEpic ? `- Limit stories per epic to ${params.options.maxStoriesPerEpic}.` : "",
+            params.options.maxTasksPerStory ? `- Limit tasks per story to ${params.options.maxTasksPerStory}.` : "",
+        ]
+            .filter(Boolean)
+            .join("\n");
+        const plannedGapBundles = params.audit.plannedGapBundles.length > 0
+            ? JSON.stringify(params.audit.plannedGapBundles.slice(0, 48), null, 2)
+            : "[]";
+        return [
+            this.buildCreateTasksAgentMission(params.projectKey),
+            `Refinement iteration ${params.iteration}. The current backlog did not yet satisfy the SDS sufficiency audit.`,
+            "Return a complete replacement backlog as valid JSON only matching:",
+            FULL_PLAN_SCHEMA_SNIPPET,
+            "Refinement rules:",
+            "- Return the full revised backlog, not a delta.",
+            "- Preserve already-good backlog slices unless a stricter SDS-aligned replacement is required.",
+            "- Every epic must map to one or more serviceIds from the phase-0 service catalog.",
+            "- Every story must contain concrete tasks, and every task must stay scoped to its own story.",
+            "- Every task must be implementation-concrete, name real targets when the SDS exposes them, and include unit/component/integration/api test arrays ([] when not applicable).",
+            "- Fix the specific missing SDS coverage items listed below. Do not claim coverage unless the backlog contains executable work for them.",
+            "- Maintain dependency-first sequencing from foundational/runtime prerequisites through verification and acceptance evidence.",
+            refinementLimits || "- Use reasonable scope without over-generating backlog items.",
+            "Why this revision is required:",
+            formatBullets(params.reasons, "SDS coverage gaps remain."),
+            "Current backlog outline:",
+            planOutline,
+            "Remaining section headings:",
+            formatBullets(params.audit.remainingSectionHeadings, "none"),
+            "Remaining folder entries:",
+            formatBullets(params.audit.remainingFolderEntries, "none"),
+            "Actionable gap bundles (anchor + concrete implementation targets):",
+            plannedGapBundles,
+            "Project construction method:",
+            params.projectBuildMethod,
+            "Phase 0 service catalog (allowed serviceIds):",
+            serviceCatalogSummary,
+            "Docs available:",
+            params.docSummary || "- (no docs provided; propose sensible refinements).",
+        ].join("\n\n");
+    }
+    async refinePlanWithAgent(params) {
+        const prompt = this.buildRefinementPrompt({
+            projectKey: params.projectKey,
+            currentPlan: params.currentPlan,
+            audit: params.audit,
+            reasons: params.reasons,
+            docSummary: params.docSummary,
+            projectBuildMethod: params.projectBuildMethod,
+            serviceCatalog: params.serviceCatalog,
+            options: params.options,
+            iteration: params.iteration,
+        });
+        const { output } = await this.invokeAgentWithRetry(params.agent, prompt, "full_plan", params.agentStream, params.jobId, params.commandRunId, {
+            refinementIteration: params.iteration,
+            remainingGapCount: params.audit.remainingGaps.total,
+            remainingSectionCount: params.audit.remainingSectionHeadings.length,
+            remainingFolderCount: params.audit.remainingFolderEntries.length,
+        });
+        const refinedPlan = this.parseFullPlan(output, params.options);
+        return this.normalizeGeneratedPlan({
+            plan: refinedPlan,
+            docs: params.docs,
+            serviceCatalog: params.serviceCatalog,
+            sourceTopologyExpectation: params.sourceTopologyExpectation,
+            unknownEpicServicePolicy: params.unknownEpicServicePolicy,
+            jobId: params.jobId,
+        });
+    }
+    async runTaskSufficiencyAudit(params) {
+        if (!this.taskSufficiencyFactory) {
+            return { warnings: [] };
+        }
+        let audit;
+        let error;
+        let closeError;
+        try {
+            const sufficiencyService = await this.taskSufficiencyFactory(this.workspace);
+            try {
+                audit = await sufficiencyService.runAudit({
+                    workspace: params.workspace,
+                    projectKey: params.projectKey,
+                    sourceCommand: params.sourceCommand,
+                    dryRun: params.dryRun,
+                });
+            }
+            finally {
+                try {
+                    await sufficiencyService.close();
+                }
+                catch (caught) {
+                    closeError = caught?.message ?? String(caught);
+                    await this.jobService.appendLog(params.jobId, `Task sufficiency audit close warning: ${closeError}\n`);
+                }
+            }
+        }
+        catch (caught) {
+            error = caught?.message ?? String(caught);
+        }
+        return {
+            audit,
+            error,
+            warnings: uniqueStrings([
+                ...(audit?.warnings ?? []),
+                ...(closeError ? [`Task sufficiency audit close warning: ${closeError}`] : []),
+            ]),
+        };
+    }
+    buildPrompt(projectKey, docSummary, projectBuildMethod, serviceCatalog, options) {
         const serviceCatalogSummary = this.buildServiceCatalogPromptSummary(serviceCatalog);
         const limits = [
             options.maxEpics ? `Limit epics to ${options.maxEpics}.` : "",
@@ -2665,18 +4485,22 @@ export class CreateTasksService {
             .filter(Boolean)
             .join(" ");
         const prompt = [
-            `You are assisting in phase 1 of 3 for project ${projectKey}: generate epics only.`,
-            "Process is strict and direct: build plan -> epics -> stories -> tasks.",
+            this.buildCreateTasksAgentMission(projectKey),
+            `You are assisting in phase 1 of 3 for project ${projectKey}: understand the documented services/tools and generate epics only.`,
+            "Process is strict and direct: understand services/tools -> epics -> stories -> tasks -> sufficiency refinement.",
             "This step outputs only epics derived from the build plan and docs.",
             "Return strictly valid JSON (no prose) matching:",
             EPIC_SCHEMA_SNIPPET,
             "Rules:",
+            "- First reason through which documented services/tools must be created or changed, then express that understanding through executable implementation epics.",
             "- Do NOT include final slugs; the system will assign keys.",
             "- Use docdex handles when referencing docs.",
             "- acceptanceCriteria must be an array of strings (5-10 items).",
             "- Keep epics actionable and implementation-oriented; avoid glossary/admin-only epics.",
             "- Prefer dependency-first sequencing: foundational setup epics before dependent feature epics.",
             "- Keep output derived from docs; do not assume stacks unless docs state them.",
+            "- Use canonical documented names for modules, services, interfaces, commands, schemas, and files exactly as they appear in Docs and the project construction method.",
+            "- Do not rename explicit documented targets or replace them with invented alternatives.",
             "- serviceIds is required and must contain one or more ids from the phase-0 service catalog below.",
             `- If an epic spans multiple services, include tag \"${CROSS_SERVICE_TAG}\" in tags.`,
             "Project construction method to follow:",
@@ -2727,9 +4551,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"],
@@ -2884,7 +4708,7 @@ export class CreateTasksService {
             const attempt = 2;
             const fixPrompt = [
                 "Rewrite the previous response into valid JSON matching the expected schema.",
-                `Schema hint:\n${action === "epics" ? EPIC_SCHEMA_SNIPPET : action === "stories" ? STORY_SCHEMA_SNIPPET : TASK_SCHEMA_SNIPPET}`,
+                `Schema hint:\n${this.schemaSnippetForAction(action)}`,
                 "Return JSON only; no prose.",
                 `Original content:\n${output}`,
             ].join("\n\n");
@@ -2988,8 +4812,9 @@ export class CreateTasksService {
         }))
             .filter((e) => e.title);
     }
-    async generateStoriesForEpic(agent, epic, docSummary, projectBuildMethod, stream, jobId, commandRunId) {
+    async generateStoriesForEpic(agent, projectKey, epic, docSummary, projectBuildMethod, stream, jobId, commandRunId) {
         const prompt = [
+            this.buildCreateTasksAgentMission(projectKey),
             `Generate user stories for epic "${epic.title}" (phase 2 of 3).`,
             "This phase is stories-only. Do not generate tasks yet.",
             "Return JSON only matching:",
@@ -2999,7 +4824,9 @@ export class CreateTasksService {
             "- acceptanceCriteria must be an array of strings.",
             "- Use docdex handles when citing docs.",
             "- Keep stories direct and implementation-oriented; avoid placeholder-only narrative sections.",
+            "- Define the minimum set of user stories that, when completed, will finish this epic according to the SDS and construction method.",
             "- 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)"}`,
@@ -3028,7 +4855,7 @@ export class CreateTasksService {
         }))
             .filter((s) => s.title);
     }
-    async generateTasksForStory(agent, epic, story, docSummary, projectBuildMethod, stream, jobId, commandRunId) {
+    async generateTasksForStory(agent, projectKey, epic, story, docSummary, projectBuildMethod, stream, jobId, commandRunId) {
         const parseTestList = (value) => {
             if (!Array.isArray(value))
                 return [];
@@ -3038,6 +4865,7 @@ export class CreateTasksService {
                 .filter(Boolean);
         };
         const prompt = [
+            this.buildCreateTasksAgentMission(projectKey),
             `Generate tasks for story "${story.title}" (Epic: ${epic.title}, phase 3 of 3).`,
             "This phase is tasks-only for the given story.",
             "Return JSON only matching:",
@@ -3056,8 +4884,10 @@ export class CreateTasksService {
             "- Start from prerequisite codebase setup: add structure/bootstrap tasks before feature tasks when missing.",
             "- Keep dependencies strictly inside this story; never reference tasks from other stories/epics.",
             "- Order tasks from foundational prerequisites to dependents based on documented dependency direction and startup constraints.",
+            "- Generate the concrete work that would actually complete this story in one automated backlog pass; do not leave implied implementation gaps behind.",
             "- Avoid placeholder wording (TBD, TODO, to be defined, generic follow-up phrases).",
             "- Avoid documentation-only or glossary-only tasks unless story acceptance explicitly requires them.",
+            "- Preserve canonical documented names for modules, services, interfaces, commands, schemas, and files exactly as written.",
             "- Use docdex handles when citing docs.",
             "- If OPENAPI_HINTS are present in Docs, align tasks with hinted service/capability/stage/test_requirements.",
             "- If SDS_COVERAGE_HINTS are present in Docs, cover the relevant SDS sections in implementation tasks.",
@@ -3157,11 +4987,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,
@@ -3193,7 +5023,7 @@ export class CreateTasksService {
             },
         ];
     }
-    async generatePlanFromAgent(epics, agent, docSummary, options) {
+    async generatePlanFromAgent(projectKey, epics, agent, docSummary, options) {
         const planEpics = epics.map((epic, idx) => ({
             ...epic,
             localId: epic.localId ?? `e${idx + 1}`,
@@ -3205,7 +5035,7 @@ export class CreateTasksService {
             let stories = [];
             let usedFallbackStories = false;
             try {
-                stories = await this.generateStoriesForEpic(agent, { ...epic }, docSummary, options.projectBuildMethod, options.agentStream, options.jobId, options.commandRunId);
+                stories = await this.generateStoriesForEpic(agent, projectKey, { ...epic }, docSummary, options.projectBuildMethod, options.agentStream, options.jobId, options.commandRunId);
             }
             catch (error) {
                 usedFallbackStories = true;
@@ -3238,7 +5068,7 @@ export class CreateTasksService {
             }
             else {
                 try {
-                    tasks = await this.generateTasksForStory(agent, { key: story.epicLocalId, title: story.title }, story, docSummary, options.projectBuildMethod, options.agentStream, options.jobId, options.commandRunId);
+                    tasks = await this.generateTasksForStory(agent, projectKey, { key: story.epicLocalId, title: story.title }, story, docSummary, options.projectBuildMethod, options.agentStream, options.jobId, options.commandRunId);
                 }
                 catch (error) {
                     await this.jobService.appendLog(options.jobId, `Task generation failed for story "${story.title}" (${storyScope}). Using deterministic fallback tasks. Reason: ${error.message ?? String(error)}\n`);
@@ -3261,50 +5091,130 @@ 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);
-            }
-            else {
-                unmatched.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());
+                }
             }
         }
-        const totalSections = matched.length + unmatched.length;
-        const coverageRatio = totalSections === 0 ? 1 : matched.length / totalSections;
+        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.`);
+        }
+    }
+    assertPlanningArtifactConsistency(projectKey, buildPlan, serviceCatalog) {
+        const sort = (values) => [...values].sort((left, right) => left.localeCompare(right));
+        const catalogSourceDocs = sort(uniqueStrings(serviceCatalog.sourceDocs));
+        const buildPlanSourceDocs = sort(uniqueStrings(buildPlan.sourceDocs));
+        if (JSON.stringify(catalogSourceDocs) !== JSON.stringify(buildPlanSourceDocs)) {
+            throw new Error(`create-tasks produced inconsistent planning artifacts for project "${projectKey}". build-plan.json and services.json disagree on source docs.`);
+        }
+        const catalogServiceNames = serviceCatalog.services.map((service) => service.name);
+        const catalogServiceIds = serviceCatalog.services.map((service) => service.id);
+        const expectedBuildPlanServiceNames = catalogServiceNames.slice(0, buildPlan.services.length);
+        const expectedBuildPlanServiceIds = catalogServiceIds.slice(0, buildPlan.serviceIds.length);
+        if (JSON.stringify(buildPlan.services) !== JSON.stringify(expectedBuildPlanServiceNames) ||
+            JSON.stringify(buildPlan.serviceIds) !== JSON.stringify(expectedBuildPlanServiceIds)) {
+            throw new Error(`create-tasks produced inconsistent planning artifacts for project "${projectKey}". build-plan.json and services.json disagree on service identity ordering.`);
+        }
+        const catalogServicesByName = new Map(serviceCatalog.services.map((service) => [service.name, service]));
+        const unknownWaveServices = buildPlan.startupWaves.flatMap((wave) => wave.services
+            .filter((serviceName) => !catalogServicesByName.has(serviceName))
+            .map((serviceName) => `wave ${wave.wave}:${serviceName}`));
+        if (unknownWaveServices.length > 0) {
+            throw new Error(`create-tasks produced inconsistent planning artifacts for project "${projectKey}". build-plan.json references services missing from services.json: ${unknownWaveServices.slice(0, 8).join(", ")}.`);
+        }
+    }
+    async loadExpectedCoverageFromSufficiencyReport(reportPath) {
+        if (!reportPath)
+            return undefined;
+        let raw;
+        try {
+            raw = await fs.readFile(reportPath, "utf8");
+        }
+        catch (error) {
+            const message = error?.message ?? String(error);
+            throw new Error(`create-tasks failed to load task sufficiency coverage report from "${reportPath}": ${message}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (error) {
+            const message = error?.message ?? String(error);
+            throw new Error(`create-tasks failed to parse task sufficiency coverage report from "${reportPath}": ${message}`);
+        }
+        const finalCoverage = parsed.finalCoverage;
+        if (!finalCoverage ||
+            typeof finalCoverage.coverageRatio !== "number" ||
+            typeof finalCoverage.totalSignals !== "number" ||
+            !Array.isArray(finalCoverage.missingSectionHeadings) ||
+            !Array.isArray(finalCoverage.missingFolderEntries)) {
+            throw new Error(`create-tasks failed to load task sufficiency coverage report from "${reportPath}": finalCoverage is incomplete.`);
+        }
+        return {
+            coverageRatio: finalCoverage.coverageRatio,
+            totalSignals: finalCoverage.totalSignals,
+            missingSectionHeadings: finalCoverage.missingSectionHeadings.filter((value) => typeof value === "string"),
+            missingFolderEntries: finalCoverage.missingFolderEntries.filter((value) => typeof value === "string"),
+        };
+    }
+    buildSdsCoverageReport(projectKey, docs, plan, existingAnchors = new Set()) {
+        const coverageSignals = collectSdsCoverageSignalsFromDocs(docs, {
+            headingLimit: SDS_COVERAGE_REPORT_SECTION_LIMIT,
+            folderLimit: SDS_COVERAGE_REPORT_FOLDER_LIMIT,
+        });
+        const coverage = evaluateSdsCoverage(this.buildCoverageCorpus(plan), {
+            sectionHeadings: coverageSignals.sectionHeadings,
+            folderEntries: coverageSignals.folderEntries,
+        }, existingAnchors);
+        const matchedSections = coverageSignals.sectionHeadings.filter((heading) => !coverage.missingSectionHeadings.includes(heading));
+        const matchedFolderEntries = coverageSignals.folderEntries.filter((entry) => !coverage.missingFolderEntries.includes(entry));
         return {
             projectKey,
             generatedAt: new Date().toISOString(),
-            totalSections,
-            matched,
-            unmatched,
-            coverageRatio: Number(coverageRatio.toFixed(4)),
-            notes: totalSections === 0
-                ? ["No SDS section headings detected; coverage defaults to 1.0."]
-                : ["Coverage is heading-based heuristic match between SDS sections and generated epic/story/task corpus."],
+            totalSignals: coverage.totalSignals,
+            totalSections: coverageSignals.sectionHeadings.length,
+            totalFolderEntries: coverageSignals.folderEntries.length,
+            rawSectionSignals: coverageSignals.rawSectionHeadings.length,
+            rawFolderSignals: coverageSignals.rawFolderEntries.length,
+            skippedHeadingSignals: coverageSignals.skippedHeadingSignals,
+            skippedFolderSignals: coverageSignals.skippedFolderSignals,
+            matched: matchedSections,
+            unmatched: coverage.missingSectionHeadings,
+            matchedSections,
+            missingSectionHeadings: coverage.missingSectionHeadings,
+            matchedFolderEntries,
+            missingFolderEntries: coverage.missingFolderEntries,
+            existingAnchorsCount: existingAnchors.size,
+            coverageRatio: coverage.coverageRatio,
+            notes: coverage.totalSignals === 0
+                ? ["No actionable SDS implementation signals detected; coverage defaults to 1.0."]
+                : ["Coverage uses the same heading and folder signal model as task-sufficiency-audit."],
         };
     }
     async acquirePlanArtifactLock(baseDir, options) {
@@ -3365,11 +5275,171 @@ export class CreateTasksService {
             }
         }
     }
-    async writePlanArtifacts(projectKey, plan, docSummary, docs, buildPlan, serviceCatalog) {
+    splitPersistedAcceptanceCriteria(value) {
+        if (!value)
+            return [];
+        return uniqueStrings(value
+            .split(/\r?\n/)
+            .map((line) => line.replace(/^[-*]\s+/, "").trim())
+            .filter(Boolean));
+    }
+    async loadPersistedBacklog(projectId) {
+        const repoLike = this.workspaceRepo;
+        if (typeof repoLike.getDb !== "function") {
+            const epics = Array.isArray(repoLike.epics)
+                ? repoLike.epics.filter((row) => row.projectId === projectId)
+                : [];
+            const stories = Array.isArray(repoLike.stories)
+                ? repoLike.stories.filter((row) => row.projectId === projectId)
+                : [];
+            const tasks = Array.isArray(repoLike.tasks)
+                ? repoLike.tasks.filter((row) => row.projectId === projectId)
+                : [];
+            const taskIds = new Set(tasks.map((task) => task.id));
+            const dependencies = Array.isArray(repoLike.deps)
+                ? repoLike.deps.filter((row) => taskIds.has(row.taskId))
+                : [];
+            return { epics, stories, tasks, dependencies };
+        }
+        const db = repoLike.getDb();
+        const epicRows = await db.all(`SELECT id, project_id, key, title, description, story_points_total, priority, metadata_json, created_at, updated_at
+       FROM epics
+       WHERE project_id = ?
+       ORDER BY COALESCE(priority, 2147483647), datetime(created_at), key`, projectId);
+        const storyRows = await db.all(`SELECT id, project_id, epic_id, key, title, description, acceptance_criteria, story_points_total, priority, metadata_json, created_at, updated_at
+       FROM user_stories
+       WHERE project_id = ?
+       ORDER BY COALESCE(priority, 2147483647), datetime(created_at), key`, projectId);
+        const taskRows = await db.all(`SELECT id, project_id, epic_id, user_story_id, key, title, description, type, status, story_points, priority,
+              assigned_agent_id, assignee_human, vcs_branch, vcs_base_branch, vcs_last_commit_sha, metadata_json,
+              openapi_version_at_creation, created_at, updated_at
+       FROM tasks
+       WHERE project_id = ?
+       ORDER BY COALESCE(priority, 2147483647), datetime(created_at), key`, projectId);
+        const epics = epicRows.map((row) => ({
+            id: row.id,
+            projectId: row.project_id,
+            key: row.key,
+            title: row.title,
+            description: row.description,
+            storyPointsTotal: row.story_points_total ?? null,
+            priority: row.priority ?? null,
+            metadata: row.metadata_json ? JSON.parse(row.metadata_json) : undefined,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        }));
+        const stories = storyRows.map((row) => ({
+            id: row.id,
+            projectId: row.project_id,
+            epicId: row.epic_id,
+            key: row.key,
+            title: row.title,
+            description: row.description,
+            acceptanceCriteria: row.acceptance_criteria ?? null,
+            storyPointsTotal: row.story_points_total ?? null,
+            priority: row.priority ?? null,
+            metadata: row.metadata_json ? JSON.parse(row.metadata_json) : undefined,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        }));
+        const tasks = taskRows.map((row) => ({
+            id: row.id,
+            projectId: row.project_id,
+            epicId: row.epic_id,
+            userStoryId: row.user_story_id,
+            key: row.key,
+            title: row.title,
+            description: row.description,
+            type: row.type ?? null,
+            status: row.status,
+            storyPoints: row.story_points ?? null,
+            priority: row.priority ?? null,
+            assignedAgentId: row.assigned_agent_id ?? null,
+            assigneeHuman: row.assignee_human ?? null,
+            vcsBranch: row.vcs_branch ?? null,
+            vcsBaseBranch: row.vcs_base_branch ?? null,
+            vcsLastCommitSha: row.vcs_last_commit_sha ?? null,
+            metadata: row.metadata_json ? JSON.parse(row.metadata_json) : undefined,
+            openapiVersionAtCreation: row.openapi_version_at_creation ?? null,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        }));
+        const dependencies = typeof repoLike.getTaskDependencies === "function"
+            ? await repoLike.getTaskDependencies(tasks.map((task) => task.id))
+            : [];
+        return { epics, stories, tasks, dependencies };
+    }
+    buildPlanFromPersistedBacklog(backlog) {
+        const storyById = new Map(backlog.stories.map((story) => [story.id, story]));
+        const epicById = new Map(backlog.epics.map((epic) => [epic.id, epic]));
+        const taskById = new Map(backlog.tasks.map((task) => [task.id, task]));
+        const dependencyKeysByTaskId = new Map();
+        for (const dependency of backlog.dependencies) {
+            const current = dependencyKeysByTaskId.get(dependency.taskId) ?? [];
+            const dependsOn = taskById.get(dependency.dependsOnTaskId)?.key;
+            if (dependsOn && !current.includes(dependsOn))
+                current.push(dependsOn);
+            dependencyKeysByTaskId.set(dependency.taskId, current);
+        }
+        return {
+            epics: backlog.epics.map((epic) => {
+                const metadata = (epic.metadata ?? {});
+                return {
+                    localId: epic.key,
+                    area: epic.key.split("-")[0]?.toLowerCase() || "proj",
+                    title: epic.title,
+                    description: epic.description,
+                    acceptanceCriteria: [],
+                    relatedDocs: normalizeRelatedDocs(metadata.doc_links),
+                    priorityHint: epic.priority ?? undefined,
+                    serviceIds: normalizeStringArray(metadata.service_ids),
+                    tags: normalizeStringArray(metadata.tags),
+                    stories: [],
+                };
+            }),
+            stories: backlog.stories.map((story) => {
+                const metadata = (story.metadata ?? {});
+                return {
+                    localId: story.key,
+                    epicLocalId: epicById.get(story.epicId)?.key ?? story.epicId,
+                    title: story.title,
+                    userStory: undefined,
+                    description: story.description,
+                    acceptanceCriteria: this.splitPersistedAcceptanceCriteria(story.acceptanceCriteria),
+                    relatedDocs: normalizeRelatedDocs(metadata.doc_links),
+                    priorityHint: story.priority ?? undefined,
+                    tasks: [],
+                };
+            }),
+            tasks: backlog.tasks.map((task) => {
+                const metadata = (task.metadata ?? {});
+                const testRequirements = (metadata.test_requirements ?? {});
+                return {
+                    localId: task.key,
+                    epicLocalId: epicById.get(task.epicId)?.key ?? task.epicId,
+                    storyLocalId: storyById.get(task.userStoryId)?.key ?? task.userStoryId,
+                    title: task.title,
+                    type: task.type ?? "feature",
+                    description: task.description,
+                    estimatedStoryPoints: task.storyPoints ?? undefined,
+                    priorityHint: task.priority ?? undefined,
+                    dependsOnKeys: dependencyKeysByTaskId.get(task.id) ?? [],
+                    relatedDocs: normalizeRelatedDocs(metadata.doc_links),
+                    unitTests: normalizeStringArray(testRequirements.unit),
+                    componentTests: normalizeStringArray(testRequirements.component),
+                    integrationTests: normalizeStringArray(testRequirements.integration),
+                    apiTests: normalizeStringArray(testRequirements.api),
+                    qa: isPlainObject(metadata.qa) ? metadata.qa : undefined,
+                };
+            }),
+        };
+    }
+    async writePlanArtifacts(projectKey, plan, docSummary, docs, buildPlan, serviceCatalog, options) {
         const baseDir = path.join(this.workspace.mcodaDir, "tasks", projectKey);
         await fs.mkdir(baseDir, { recursive: true });
         const releaseLock = await this.acquirePlanArtifactLock(baseDir);
         try {
+            this.assertCanonicalNameConsistency(projectKey, docs, plan);
             const write = async (file, data) => {
                 const target = path.join(baseDir, file);
                 await this.writeJsonArtifactAtomic(target, data);
@@ -3387,7 +5457,12 @@ export class CreateTasksService {
             await write("epics.json", plan.epics);
             await write("stories.json", plan.stories);
             await write("tasks.json", plan.tasks);
-            await write("coverage-report.json", this.buildSdsCoverageReport(projectKey, docs, plan));
+            this.assertPlanningArtifactConsistency(projectKey, buildPlan, serviceCatalog);
+            const coverageReport = this.buildSdsCoverageReport(projectKey, docs, plan, options?.existingCoverageAnchors ?? new Set());
+            if (options?.expectedCoverage) {
+                this.assertCoverageConsistency(projectKey, coverageReport, options.expectedCoverage);
+            }
+            await write("coverage-report.json", coverageReport);
         }
         finally {
             await releaseLock();
@@ -3656,6 +5731,8 @@ export class CreateTasksService {
                 });
                 let sdsPreflight;
                 let sdsPreflightError;
+                let sdsPreflightBlockingReasons = [];
+                let continueAfterSdsPreflightWarnings = false;
                 if (this.sdsPreflightFactory) {
                     let sdsPreflightCloseError;
                     try {
@@ -3667,7 +5744,7 @@ export class CreateTasksService {
                                 inputPaths: options.inputs,
                                 sdsPaths: options.inputs,
                                 writeArtifacts: true,
-                                applyToSds: true,
+                                applyToSds: options.sdsPreflightApplyToSds === true,
                                 commitAppliedChanges: options.sdsPreflightCommit === true,
                                 commitMessage: options.sdsPreflightCommitMessage,
                             });
@@ -3727,12 +5804,15 @@ export class CreateTasksService {
                     }
                     if (blockingReasons.length > 0) {
                         sdsPreflightError = blockingReasons.join(" ");
+                        sdsPreflightBlockingReasons = [...blockingReasons];
+                        continueAfterSdsPreflightWarnings = true;
+                        await this.jobService.appendLog(job.id, `SDS preflight reported planning warnings but create-tasks will continue with remediation context: ${blockingReasons.join(" ")} Report: ${sdsPreflight.reportPath}\n`);
                     }
                     await this.jobService.writeCheckpoint(job.id, {
                         stage: "sds_preflight",
                         timestamp: new Date().toISOString(),
                         details: {
-                            status: blockingReasons.length > 0 ? "blocked" : "succeeded",
+                            status: blockingReasons.length > 0 ? "continued_with_warnings" : "succeeded",
                             error: sdsPreflightError,
                             readyForPlanning: sdsPreflight.readyForPlanning,
                             qualityStatus: sdsPreflight.qualityStatus,
@@ -3747,28 +5827,46 @@ export class CreateTasksService {
                             appliedToSds: sdsPreflight.appliedToSds,
                             appliedSdsCount: sdsPreflight.appliedSdsPaths.length,
                             commitHash: sdsPreflight.commitHash,
+                            blockingReasons,
+                            continuedWithWarnings: continueAfterSdsPreflightWarnings,
                             warnings: preflightWarnings,
                         },
                     });
-                    if (blockingReasons.length > 0) {
-                        throw new Error(`create-tasks blocked by SDS preflight. ${blockingReasons.join(" ")} Report: ${sdsPreflight.reportPath}`);
-                    }
                 }
-                const preflightDocInputs = this.mergeDocInputs(options.inputs, sdsPreflight ? [...sdsPreflight.sourceSdsPaths, ...sdsPreflight.generatedDocPaths] : []);
+                const preflightGeneratedDocInputs = sdsPreflight && (!sdsPreflight.appliedToSds || continueAfterSdsPreflightWarnings)
+                    ? sdsPreflight.generatedDocPaths
+                    : [];
+                const preflightDocInputs = this.mergeDocInputs(options.inputs, sdsPreflight ? [...sdsPreflight.sourceSdsPaths, ...preflightGeneratedDocInputs] : []);
                 const docs = await this.prepareDocs(preflightDocInputs);
                 const { docSummary, warnings: indexedDocWarnings } = this.buildDocContext(docs);
                 const docWarnings = uniqueStrings([...(sdsPreflight?.warnings ?? []), ...indexedDocWarnings]);
-                const discoveryGraph = this.buildServiceDependencyGraph({ epics: [], stories: [], tasks: [] }, docs);
-                const serviceCatalog = this.buildServiceCatalogArtifact(options.projectKey, docs, discoveryGraph);
-                const projectBuildMethod = this.buildProjectConstructionMethod(docs, discoveryGraph);
-                const projectBuildPlan = this.buildProjectPlanArtifact(options.projectKey, docs, discoveryGraph, projectBuildMethod);
-                const { prompt } = this.buildPrompt(options.projectKey, docs, projectBuildMethod, serviceCatalog, options);
+                const sourceTopologyExpectation = this.buildSourceTopologyExpectation(docs);
+                const initialArtifacts = this.derivePlanningArtifacts(options.projectKey, docs, { epics: [], stories: [], tasks: [] }, sourceTopologyExpectation);
+                const { discoveryGraph, topologySignals, serviceCatalog, projectBuildMethod, projectBuildPlan } = initialArtifacts;
+                const sdsDrivenPlan = this.buildSdsDrivenPlan(options.projectKey, docs, serviceCatalog, discoveryGraph);
+                const deterministicFallbackPlan = this.hasStrongSdsPlanningEvidence(docs, serviceCatalog, sourceTopologyExpectation)
+                    ? sdsDrivenPlan
+                    : this.materializePlanFromSeed(this.fallbackPlan(options.projectKey, docs), {
+                        maxEpics: options.maxEpics,
+                        maxStoriesPerEpic: options.maxStoriesPerEpic,
+                        maxTasksPerStory: options.maxTasksPerStory,
+                    });
+                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",
@@ -3814,7 +5912,7 @@ export class CreateTasksService {
                         timestamp: new Date().toISOString(),
                         details: { epics: epics.length, source: "agent" },
                     });
-                    plan = await this.generatePlanFromAgent(epics, agent, docSummary, {
+                    plan = await this.generatePlanFromAgent(options.projectKey, epics, agent, docSummary, {
                         agentStream,
                         jobId: job.id,
                         commandRunId: commandRun.id,
@@ -3829,38 +5927,41 @@ export class CreateTasksService {
                         /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), {
-                        maxEpics: options.maxEpics,
-                        maxStoriesPerEpic: options.maxStoriesPerEpic,
-                        maxTasksPerStory: options.maxTasksPerStory,
-                    });
+                    await this.jobService.appendLog(job.id, `Agent planning failed, using deterministic planner fallback: ${fallbackReason}\n`);
+                    planSource = deterministicFallbackPlan === sdsDrivenPlan ? "sds" : "fallback";
+                    plan = deterministicFallbackPlan;
                     await this.jobService.writeCheckpoint(job.id, {
                         stage: "epics_generated",
                         timestamp: new Date().toISOString(),
                         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 = await this.normalizeGeneratedPlan({
+                    plan,
+                    docs,
+                    serviceCatalog,
+                    sourceTopologyExpectation,
+                    unknownEpicServicePolicy,
+                    jobId: job.id,
+                });
+                if (this.planLooksTooWeakForSds(plan, docs, serviceCatalog, sourceTopologyExpectation)) {
+                    fallbackReason = [
+                        fallbackReason,
+                        `generated backlog was too weak for SDS-first acceptance (epics=${plan.epics.length}, tasks=${plan.tasks.length})`,
+                    ]
+                        .filter(Boolean)
+                        .join("; ");
+                    planSource = "sds";
+                    plan = await this.normalizeGeneratedPlan({
+                        plan: sdsDrivenPlan,
+                        docs,
+                        serviceCatalog,
+                        sourceTopologyExpectation,
+                        unknownEpicServicePolicy,
+                        jobId: job.id,
+                    });
+                    await this.jobService.appendLog(job.id, `create-tasks replaced the weak generated backlog with the SDS-first deterministic plan. Reason: ${fallbackReason}\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);
-                this.validatePlanLocalIdentifiers(plan);
-                plan = this.applyServiceDependencySequencing(plan, docs);
-                plan = this.enforceStoryScopedDependencies(plan);
-                this.validatePlanLocalIdentifiers(plan);
                 await this.jobService.writeCheckpoint(job.id, {
                     stage: "stories_generated",
                     timestamp: new Date().toISOString(),
@@ -3886,91 +5987,185 @@ export class CreateTasksService {
                 await this.seedPriorities(options.projectKey);
                 let sufficiencyAudit;
                 let sufficiencyAuditError;
-                if (this.taskSufficiencyFactory) {
-                    let sufficiencyCloseError;
-                    try {
-                        const sufficiencyService = await this.taskSufficiencyFactory(this.workspace);
-                        try {
-                            sufficiencyAudit = await sufficiencyService.runAudit({
-                                workspace: options.workspace,
-                                projectKey: options.projectKey,
-                                sourceCommand: "create-tasks",
-                            });
-                        }
-                        finally {
-                            try {
-                                await sufficiencyService.close();
-                            }
-                            catch (closeError) {
-                                sufficiencyCloseError = closeError?.message ?? String(closeError);
-                                await this.jobService.appendLog(job.id, `Task sufficiency audit close warning: ${sufficiencyCloseError}\n`);
-                            }
-                        }
-                    }
-                    catch (error) {
-                        sufficiencyAuditError = error?.message ?? String(error);
-                    }
+                const sufficiencyWarnings = [];
+                let refinementAttempt = 0;
+                while (true) {
+                    const auditResult = await this.runTaskSufficiencyAudit({
+                        workspace: options.workspace,
+                        projectKey: options.projectKey,
+                        sourceCommand: "create-tasks",
+                        dryRun: true,
+                        jobId: job.id,
+                    });
+                    sufficiencyAudit = auditResult.audit;
+                    sufficiencyAuditError = auditResult.error;
+                    sufficiencyWarnings.push(...auditResult.warnings);
                     if (!sufficiencyAudit) {
-                        const message = `create-tasks blocked: task sufficiency audit failed (${sufficiencyAuditError ?? "unknown error"}).`;
-                        await this.jobService.writeCheckpoint(job.id, {
-                            stage: "task_sufficiency_audit",
-                            timestamp: new Date().toISOString(),
-                            details: {
-                                status: "failed",
-                                error: message,
-                                jobId: undefined,
-                                commandRunId: undefined,
-                                satisfied: false,
-                                dryRun: undefined,
-                                totalTasksAdded: undefined,
-                                totalTasksUpdated: undefined,
-                                finalCoverageRatio: undefined,
-                                reportPath: undefined,
-                                remainingSectionCount: undefined,
-                                remainingFolderCount: undefined,
-                                remainingGapCount: undefined,
-                                warnings: [],
-                            },
-                        });
-                        throw new Error(message);
+                        break;
                     }
-                    const sufficiencyWarnings = uniqueStrings([
-                        ...(sufficiencyAudit.warnings ?? []),
-                        ...(sufficiencyCloseError ? [`Task sufficiency audit close warning: ${sufficiencyCloseError}`] : []),
-                    ]);
-                    if (!sufficiencyAudit.satisfied) {
-                        sufficiencyAuditError = `SDS coverage target not reached (coverage=${sufficiencyAudit.finalCoverageRatio}, remaining gaps=${sufficiencyAudit.remainingGaps.total}).`;
+                    if (sufficiencyAudit.satisfied) {
+                        sufficiencyAuditError = undefined;
+                        break;
                     }
+                    const refinementReasons = [
+                        `SDS coverage target not reached (coverage=${sufficiencyAudit.finalCoverageRatio}, remaining gaps=${sufficiencyAudit.remainingGaps.total}).`,
+                        ...(sufficiencyAudit.remainingSectionHeadings.length > 0
+                            ? [
+                                `Remaining section headings: ${sufficiencyAudit.remainingSectionHeadings.slice(0, 12).join(", ")}`,
+                            ]
+                            : []),
+                        ...(sufficiencyAudit.remainingFolderEntries.length > 0
+                            ? [
+                                `Remaining folder entries: ${sufficiencyAudit.remainingFolderEntries.slice(0, 12).join(", ")}`,
+                            ]
+                            : []),
+                    ];
+                    if (!agent || refinementAttempt >= CreateTasksService.MAX_AGENT_REFINEMENT_ATTEMPTS) {
+                        sufficiencyAuditError = refinementReasons[0];
+                        break;
+                    }
+                    refinementAttempt += 1;
                     await this.jobService.writeCheckpoint(job.id, {
-                        stage: "task_sufficiency_audit",
+                        stage: "backlog_refinement",
                         timestamp: new Date().toISOString(),
                         details: {
-                            status: sufficiencyAudit.satisfied ? "succeeded" : "blocked",
-                            error: sufficiencyAuditError,
-                            jobId: sufficiencyAudit.jobId,
-                            commandRunId: sufficiencyAudit.commandRunId,
-                            satisfied: sufficiencyAudit.satisfied,
-                            dryRun: sufficiencyAudit.dryRun,
-                            totalTasksAdded: sufficiencyAudit.totalTasksAdded,
-                            totalTasksUpdated: sufficiencyAudit.totalTasksUpdated,
-                            finalCoverageRatio: sufficiencyAudit.finalCoverageRatio,
-                            reportPath: sufficiencyAudit.reportPath,
+                            iteration: refinementAttempt,
+                            remainingGapCount: sufficiencyAudit.remainingGaps.total,
                             remainingSectionCount: sufficiencyAudit.remainingSectionHeadings.length,
                             remainingFolderCount: sufficiencyAudit.remainingFolderEntries.length,
-                            remainingGapCount: sufficiencyAudit.remainingGaps.total,
-                            warnings: sufficiencyWarnings,
+                            plannedGapBundleCount: sufficiencyAudit.plannedGapBundles.length,
+                            unresolvedBundleCount: sufficiencyAudit.unresolvedBundles.length,
                         },
                     });
-                    if (!sufficiencyAudit.satisfied) {
-                        throw new Error(`create-tasks blocked: task sufficiency audit did not reach full coverage. Report: ${sufficiencyAudit.reportPath}`);
+                    try {
+                        plan = await this.refinePlanWithAgent({
+                            agent,
+                            currentPlan: plan,
+                            audit: sufficiencyAudit,
+                            reasons: refinementReasons,
+                            docs,
+                            docSummary,
+                            projectKey: options.projectKey,
+                            projectBuildMethod,
+                            serviceCatalog,
+                            sourceTopologyExpectation,
+                            unknownEpicServicePolicy,
+                            options,
+                            agentStream,
+                            jobId: job.id,
+                            commandRunId: commandRun.id,
+                            iteration: refinementAttempt,
+                        });
+                        planSource = "agent";
+                        await this.persistPlanToDb(project.id, options.projectKey, plan, job.id, commandRun.id, {
+                            force: true,
+                            resetKeys: true,
+                            qaPreflight,
+                            qaOverrides,
+                        });
+                        await this.seedPriorities(options.projectKey);
+                        await this.jobService.appendLog(job.id, `create-tasks refinement iteration ${refinementAttempt} replaced the backlog with ${plan.epics.length} epics, ${plan.stories.length} stories, and ${plan.tasks.length} tasks.\n`);
                     }
+                    catch (error) {
+                        const message = error?.message ?? String(error);
+                        await this.jobService.appendLog(job.id, `create-tasks refinement iteration ${refinementAttempt} failed: ${message}\n`);
+                        sufficiencyAuditError = refinementReasons[0];
+                        if (refinementAttempt >= CreateTasksService.MAX_AGENT_REFINEMENT_ATTEMPTS) {
+                            break;
+                        }
+                    }
+                }
+                if (!sufficiencyAudit) {
+                    const message = `create-tasks blocked: task sufficiency audit failed (${sufficiencyAuditError ?? "unknown error"}).`;
+                    await this.jobService.writeCheckpoint(job.id, {
+                        stage: "task_sufficiency_audit",
+                        timestamp: new Date().toISOString(),
+                        details: {
+                            status: "failed",
+                            error: message,
+                            jobId: undefined,
+                            commandRunId: undefined,
+                            satisfied: false,
+                            dryRun: undefined,
+                            totalTasksAdded: undefined,
+                            totalTasksUpdated: undefined,
+                            finalCoverageRatio: undefined,
+                            reportPath: undefined,
+                            remainingSectionCount: undefined,
+                            remainingFolderCount: undefined,
+                            remainingGapCount: undefined,
+                            plannedGapBundleCount: undefined,
+                            warnings: [],
+                        },
+                    });
+                    throw new Error(message);
+                }
+                const uniqueSufficiencyWarnings = uniqueStrings(sufficiencyWarnings);
+                sufficiencyAudit = {
+                    ...sufficiencyAudit,
+                    warnings: uniqueSufficiencyWarnings,
+                };
+                if (!sufficiencyAudit.satisfied) {
+                    sufficiencyAuditError = `SDS coverage target not reached (coverage=${sufficiencyAudit.finalCoverageRatio}, remaining gaps=${sufficiencyAudit.remainingGaps.total}).`;
+                }
+                await this.jobService.writeCheckpoint(job.id, {
+                    stage: "task_sufficiency_audit",
+                    timestamp: new Date().toISOString(),
+                    details: {
+                        status: sufficiencyAudit.satisfied ? "succeeded" : "blocked",
+                        error: sufficiencyAuditError,
+                        jobId: sufficiencyAudit.jobId,
+                        commandRunId: sufficiencyAudit.commandRunId,
+                        satisfied: sufficiencyAudit.satisfied,
+                        dryRun: sufficiencyAudit.dryRun,
+                        totalTasksAdded: sufficiencyAudit.totalTasksAdded,
+                        totalTasksUpdated: sufficiencyAudit.totalTasksUpdated,
+                        finalCoverageRatio: sufficiencyAudit.finalCoverageRatio,
+                        reportPath: sufficiencyAudit.reportPath,
+                        remainingSectionCount: sufficiencyAudit.remainingSectionHeadings.length,
+                        remainingFolderCount: sufficiencyAudit.remainingFolderEntries.length,
+                        remainingGapCount: sufficiencyAudit.remainingGaps.total,
+                        plannedGapBundleCount: sufficiencyAudit.plannedGapBundles.length,
+                        unresolvedBundleCount: sufficiencyAudit.unresolvedBundles.length,
+                        warnings: uniqueSufficiencyWarnings,
+                    },
+                });
+                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, sourceTopologyExpectation);
+                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,
+                        acceptedWithResidualSectionGaps: false,
+                    },
+                });
+                const acceptedWithResidualSectionGaps = false;
+                if (sufficiencyAudit && !sufficiencyAudit.satisfied) {
+                    throw new Error(`create-tasks blocked: task sufficiency audit did not reach full coverage. Report: ${sufficiencyAudit.reportPath}`);
                 }
                 await this.jobService.updateJobStatus(job.id, "completed", {
                     payload: {
-                        epicsCreated: epicRows.length,
-                        storiesCreated: storyRows.length,
-                        tasksCreated: taskRows.length,
-                        dependenciesCreated: dependencyRows.length,
+                        epicsCreated: finalBacklog.epics.length,
+                        storiesCreated: finalBacklog.stories.length,
+                        tasksCreated: finalBacklog.tasks.length,
+                        dependenciesCreated: finalBacklog.dependencies.length,
                         docs: docSummary,
                         planFolder: folder,
                         planSource,
@@ -3990,6 +6185,8 @@ export class CreateTasksService {
                                 reportPath: sdsPreflight.reportPath,
                                 openQuestionsPath: sdsPreflight.openQuestionsPath,
                                 gapAddendumPath: sdsPreflight.gapAddendumPath,
+                                blockingReasons: sdsPreflightBlockingReasons,
+                                continuedWithWarnings: continueAfterSdsPreflightWarnings,
                                 warnings: sdsPreflight.warnings,
                             }
                             : undefined,
@@ -4006,6 +6203,8 @@ export class CreateTasksService {
                                 remainingSectionCount: sufficiencyAudit.remainingSectionHeadings.length,
                                 remainingFolderCount: sufficiencyAudit.remainingFolderEntries.length,
                                 remainingGapCount: sufficiencyAudit.remainingGaps.total,
+                                unresolvedBundleCount: sufficiencyAudit.unresolvedBundles.length,
+                                acceptedWithResidualSectionGaps,
                                 warnings: sufficiencyAudit.warnings,
                             }
                             : undefined,
@@ -4037,10 +6236,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) {
@@ -4203,3 +6402,4 @@ export class CreateTasksService {
 }
 CreateTasksService.MAX_BUSY_RETRIES = 6;
 CreateTasksService.BUSY_BACKOFF_MS = 500;
+CreateTasksService.MAX_AGENT_REFINEMENT_ATTEMPTS = 3;