@mcoda/core 0.1.17 → 0.1.19

package/dist/services/planning/CreateTasksService.js

@@ -387,6 +387,110 @@ const collectFilesRecursively = async (target) => {
     }
     return [target];
 };
+const DOC_SCAN_MAX_DEPTH = 5;
+const DOC_SCAN_IGNORE_DIRS = new Set([
+    ".git",
+    ".hg",
+    ".svn",
+    ".mcoda",
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    ".next",
+    ".turbo",
+    ".cache",
+    "tmp",
+    "temp",
+]);
+const DOC_SCAN_FILE_PATTERN = /\.(md|markdown|txt|rst|ya?ml|json)$/i;
+const SDS_LIKE_PATH_PATTERN = /(^|\/)(sds|software[-_ ]design|design[-_ ]spec|requirements|prd|pdr|rfp|architecture|solution[-_ ]design)/i;
+const OPENAPI_LIKE_PATH_PATTERN = /(openapi|swagger)/i;
+const STRUCTURE_LIKE_PATH_PATTERN = /(^|\/)(tree|structure|layout|folder|directory|services?|modules?)(\/|[-_.]|$)/i;
+const DOC_PATH_TOKEN_PATTERN = /(^|[\s`"'([{<])([A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)+)(?=$|[\s`"')\]}>.,;:!?])/g;
+const FILE_EXTENSION_PATTERN = /\.[a-z0-9]{1,10}$/i;
+const SERVICE_PATH_CONTAINER_SEGMENTS = new Set([
+    "services",
+    "service",
+    "apps",
+    "app",
+    "packages",
+    "package",
+    "modules",
+    "module",
+    "libs",
+    "lib",
+    "src",
+]);
+const SERVICE_NAME_STOPWORDS = new Set([
+    "the",
+    "a",
+    "an",
+    "and",
+    "or",
+    "for",
+    "to",
+    "of",
+    "in",
+    "on",
+    "with",
+    "by",
+    "from",
+    "layer",
+    "stack",
+    "system",
+    "platform",
+    "project",
+    "repository",
+    "codebase",
+    "component",
+    "feature",
+    "implement",
+    "build",
+    "create",
+    "develop",
+    "deliver",
+    "setup",
+    "set",
+    "provision",
+    "define",
+    "configure",
+    "add",
+    "update",
+    "refactor",
+    "init",
+    "initialize",
+    "prepare",
+    "establish",
+    "support",
+    "enable",
+]);
+const SERVICE_NAME_INVALID = new Set([
+    "service",
+    "services",
+    "module",
+    "modules",
+    "app",
+    "apps",
+    "layer",
+    "stack",
+    "system",
+    "project",
+    "repository",
+    "codebase",
+]);
+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 nextUniqueLocalId = (prefix, existing) => {
+    let index = 1;
+    let candidate = `${prefix}-${index}`;
+    while (existing.has(candidate)) {
+        index += 1;
+        candidate = `${prefix}-${index}`;
+    }
+    existing.add(candidate);
+    return candidate;
+};
 const EPIC_SCHEMA_SNIPPET = `{
   "epics": [
     {
@@ -489,6 +593,18 @@ export class CreateTasksService {
         const docdex = this.docdex;
         await swallow(docdex?.close?.bind(docdex));
     }
+    storyScopeKey(epicLocalId, storyLocalId) {
+        return `${epicLocalId}::${storyLocalId}`;
+    }
+    taskScopeKey(epicLocalId, storyLocalId, taskLocalId) {
+        return `${epicLocalId}::${storyLocalId}::${taskLocalId}`;
+    }
+    scopeStory(story) {
+        return this.storyScopeKey(story.epicLocalId, story.localId);
+    }
+    scopeTask(task) {
+        return this.taskScopeKey(task.epicLocalId, task.storyLocalId, task.localId);
+    }
     async seedPriorities(projectKey) {
         const ordering = await this.taskOrderingFactory(this.workspace, { recordTelemetry: false });
         try {
@@ -584,7 +700,818 @@ export class CreateTasksService {
                 // Ignore missing candidates; fall back to empty inputs.
             }
         }
-        return existing;
+        if (existing.length > 0)
+            return existing;
+        return this.findFuzzyDocInputs();
+    }
+    async walkDocCandidates(currentDir, depth, collector) {
+        if (depth > DOC_SCAN_MAX_DEPTH)
+            return;
+        let entries = [];
+        try {
+            entries = await fs.readdir(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const entryPath = path.join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                if (DOC_SCAN_IGNORE_DIRS.has(entry.name.toLowerCase()))
+                    continue;
+                await this.walkDocCandidates(entryPath, depth + 1, collector);
+                continue;
+            }
+            if (entry.isFile()) {
+                collector(entryPath);
+            }
+        }
+    }
+    scoreDocCandidate(filePath) {
+        const workspaceRelative = path.relative(this.workspace.workspaceRoot, filePath).replace(/\\/g, "/").toLowerCase();
+        const mcodaRelative = path.relative(this.workspace.mcodaDir, filePath).replace(/\\/g, "/").toLowerCase();
+        const relative = workspaceRelative && !workspaceRelative.startsWith("..")
+            ? workspaceRelative
+            : mcodaRelative && !mcodaRelative.startsWith("..")
+                ? mcodaRelative
+                : path.basename(filePath).toLowerCase();
+        const normalized = `/${relative}`;
+        const baseName = path.basename(relative);
+        if (!DOC_SCAN_FILE_PATTERN.test(baseName))
+            return 0;
+        let score = 0;
+        if (SDS_LIKE_PATH_PATTERN.test(normalized))
+            score += 100;
+        if (OPENAPI_LIKE_PATH_PATTERN.test(normalized))
+            score += 80;
+        if (STRUCTURE_LIKE_PATH_PATTERN.test(normalized))
+            score += 30;
+        if (normalized.includes("/docs/"))
+            score += 20;
+        if (normalized.endsWith(".md") || normalized.endsWith(".markdown"))
+            score += 10;
+        return score;
+    }
+    async findFuzzyDocInputs() {
+        const ranked = [];
+        const seen = new Set();
+        const collect = (candidate) => {
+            const resolved = path.resolve(candidate);
+            if (seen.has(resolved))
+                return;
+            const score = this.scoreDocCandidate(resolved);
+            if (score <= 0)
+                return;
+            ranked.push({ path: resolved, score });
+            seen.add(resolved);
+        };
+        await this.walkDocCandidates(this.workspace.workspaceRoot, 0, collect);
+        const mcodaDocs = path.join(this.workspace.mcodaDir, "docs");
+        try {
+            const stat = await fs.stat(mcodaDocs);
+            if (stat.isDirectory()) {
+                await this.walkDocCandidates(mcodaDocs, 0, collect);
+            }
+        }
+        catch {
+            // Ignore missing workspace docs.
+        }
+        return ranked
+            .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
+            .slice(0, 24)
+            .map((entry) => entry.path);
+    }
+    normalizeStructurePathToken(value) {
+        const normalized = value
+            .replace(/\\/g, "/")
+            .replace(/^[./]+/, "")
+            .replace(/^\/+/, "")
+            .trim();
+        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 parts = normalized.split("/").filter(Boolean);
+        if (parts.length < 2)
+            return undefined;
+        if (parts.some((part) => part === "." || part === ".."))
+            return undefined;
+        if (DOC_SCAN_IGNORE_DIRS.has(parts[0].toLowerCase()))
+            return undefined;
+        return parts.join("/");
+    }
+    extractStructureTargets(docs) {
+        const directories = new Set();
+        const files = new Set();
+        for (const doc of docs) {
+            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 normalized = this.normalizeStructurePathToken(token);
+                if (!normalized)
+                    continue;
+                if (FILE_EXTENSION_PATTERN.test(path.basename(normalized))) {
+                    files.add(normalized);
+                    const parent = path.dirname(normalized).replace(/\\/g, "/");
+                    if (parent && parent !== ".")
+                        directories.add(parent);
+                }
+                else {
+                    directories.add(normalized);
+                }
+            }
+        }
+        return {
+            directories: Array.from(directories).sort((a, b) => a.length - b.length || a.localeCompare(b)).slice(0, 32),
+            files: Array.from(files).sort((a, b) => a.length - b.length || a.localeCompare(b)).slice(0, 32),
+        };
+    }
+    normalizeServiceName(value) {
+        const normalized = value
+            .toLowerCase()
+            .replace(/[`"'()[\]{}]/g, " ")
+            .replace(/[._/-]+/g, " ")
+            .replace(/[^a-z0-9\s]+/g, " ")
+            .replace(/\s+/g, " ")
+            .trim();
+        if (!normalized)
+            return undefined;
+        const keepTokens = new Set(["api", "ui", "db", "qa", "ml", "ai", "etl"]);
+        const tokens = normalized
+            .split(" ")
+            .map((token) => token.trim())
+            .filter(Boolean)
+            .filter((token) => keepTokens.has(token) || !SERVICE_NAME_STOPWORDS.has(token))
+            .slice(0, 4);
+        if (!tokens.length)
+            return undefined;
+        const candidate = tokens.join(" ");
+        if (SERVICE_NAME_INVALID.has(candidate))
+            return undefined;
+        return candidate.length >= 2 ? candidate : undefined;
+    }
+    deriveServiceFromPathToken(pathToken) {
+        const parts = pathToken
+            .replace(/\\/g, "/")
+            .split("/")
+            .map((part) => part.trim().toLowerCase())
+            .filter(Boolean);
+        if (!parts.length)
+            return undefined;
+        let idx = 0;
+        while (idx < parts.length - 1 && SERVICE_PATH_CONTAINER_SEGMENTS.has(parts[idx])) {
+            idx += 1;
+        }
+        return this.normalizeServiceName(parts[idx] ?? parts[0]);
+    }
+    addServiceAlias(aliases, rawValue) {
+        const canonical = this.normalizeServiceName(rawValue);
+        if (!canonical)
+            return undefined;
+        const existing = aliases.get(canonical) ?? new Set();
+        existing.add(canonical);
+        const alias = rawValue
+            .toLowerCase()
+            .replace(/[._/-]+/g, " ")
+            .replace(/[^a-z0-9\s]+/g, " ")
+            .replace(/\s+/g, " ")
+            .trim();
+        if (alias)
+            existing.add(alias);
+        aliases.set(canonical, existing);
+        return canonical;
+    }
+    extractServiceMentionsFromText(text) {
+        if (!text)
+            return [];
+        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);
+            if (normalized)
+                mentions.add(normalized);
+        }
+        for (const match of text.matchAll(DOC_PATH_TOKEN_PATTERN)) {
+            const token = match[2];
+            if (!token)
+                continue;
+            const normalized = this.deriveServiceFromPathToken(token);
+            if (normalized)
+                mentions.add(normalized);
+        }
+        return Array.from(mentions);
+    }
+    resolveServiceMentionFromPhrase(phrase, aliases) {
+        const normalizedPhrase = phrase
+            .toLowerCase()
+            .replace(/[._/-]+/g, " ")
+            .replace(/[^a-z0-9\s]+/g, " ")
+            .replace(/\s+/g, " ")
+            .trim();
+        if (!normalizedPhrase)
+            return undefined;
+        let best;
+        const haystack = ` ${normalizedPhrase} `;
+        for (const [service, names] of aliases.entries()) {
+            for (const alias of names) {
+                const needle = ` ${alias} `;
+                if (!haystack.includes(needle))
+                    continue;
+                if (!best || alias.length > best.aliasLength) {
+                    best = { key: service, aliasLength: alias.length };
+                }
+            }
+        }
+        if (best)
+            return best.key;
+        const mention = this.extractServiceMentionsFromText(phrase)[0];
+        if (!mention)
+            return undefined;
+        return this.addServiceAlias(aliases, mention);
+    }
+    collectDependencyStatements(text) {
+        const statements = [];
+        const lines = text
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .slice(0, 300);
+        const dependencyPatterns = [
+            {
+                regex: /^(.+?)\b(?:depends on|requires|needs|uses|consumes|calls|reads from|writes to|must come after|comes after|built after|runs after|backed by)\b(.+)$/i,
+                dependentGroup: 1,
+                dependencyGroup: 2,
+            },
+            {
+                regex: /^(.+?)\b(?:before|prerequisite for)\b(.+)$/i,
+                dependentGroup: 2,
+                dependencyGroup: 1,
+            },
+        ];
+        for (const rawLine of lines) {
+            const line = rawLine.replace(/^[-*]\s+/, "").trim();
+            if (!line)
+                continue;
+            for (const match of line.matchAll(SERVICE_ARROW_PATTERN)) {
+                const dependent = match[1]?.trim();
+                const dependency = match[2]?.trim();
+                if (dependent && dependency) {
+                    statements.push({ dependent, dependency });
+                }
+            }
+            for (const pattern of dependencyPatterns) {
+                const match = line.match(pattern.regex);
+                if (!match)
+                    continue;
+                const dependent = match[pattern.dependentGroup]?.trim();
+                const dependency = match[pattern.dependencyGroup]?.trim();
+                if (!dependent || !dependency)
+                    continue;
+                statements.push({ dependent, dependency });
+            }
+        }
+        return statements;
+    }
+    sortServicesByDependency(services, dependencies) {
+        const nodes = Array.from(new Set(services));
+        const indegree = new Map();
+        const adjacency = new Map();
+        const dependedBy = new Map();
+        for (const node of nodes) {
+            indegree.set(node, 0);
+            dependedBy.set(node, 0);
+        }
+        for (const [dependent, dependencySet] of dependencies.entries()) {
+            if (!indegree.has(dependent)) {
+                indegree.set(dependent, 0);
+                dependedBy.set(dependent, 0);
+                nodes.push(dependent);
+            }
+            for (const dependency of dependencySet) {
+                if (!indegree.has(dependency)) {
+                    indegree.set(dependency, 0);
+                    dependedBy.set(dependency, 0);
+                    nodes.push(dependency);
+                }
+                indegree.set(dependent, (indegree.get(dependent) ?? 0) + 1);
+                const out = adjacency.get(dependency) ?? new Set();
+                out.add(dependent);
+                adjacency.set(dependency, out);
+                dependedBy.set(dependency, (dependedBy.get(dependency) ?? 0) + 1);
+            }
+        }
+        const compare = (a, b) => {
+            const dependedByA = dependedBy.get(a) ?? 0;
+            const dependedByB = dependedBy.get(b) ?? 0;
+            if (dependedByA !== dependedByB)
+                return dependedByB - dependedByA;
+            return a.localeCompare(b);
+        };
+        const queue = nodes.filter((node) => (indegree.get(node) ?? 0) === 0).sort(compare);
+        const ordered = [];
+        while (queue.length) {
+            const current = queue.shift();
+            if (!current)
+                continue;
+            ordered.push(current);
+            const out = adjacency.get(current);
+            if (!out)
+                continue;
+            for (const neighbor of out) {
+                const nextInDegree = (indegree.get(neighbor) ?? 0) - 1;
+                indegree.set(neighbor, nextInDegree);
+                if (nextInDegree === 0) {
+                    queue.push(neighbor);
+                }
+            }
+            queue.sort(compare);
+        }
+        if (ordered.length === nodes.length)
+            return ordered;
+        const remaining = nodes.filter((node) => !ordered.includes(node)).sort(compare);
+        return [...ordered, ...remaining];
+    }
+    buildServiceDependencyGraph(plan, docs) {
+        const aliases = new Map();
+        const dependencies = new Map();
+        const register = (value) => {
+            if (!value)
+                return undefined;
+            return this.addServiceAlias(aliases, value);
+        };
+        const docsText = docs
+            .map((doc) => [doc.title, doc.path, doc.content, ...(doc.segments ?? []).map((segment) => segment.content)].filter(Boolean).join("\n"))
+            .join("\n");
+        const planText = [
+            ...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 structureTargets = this.extractStructureTargets(docs);
+        for (const token of [...structureTargets.directories, ...structureTargets.files]) {
+            register(this.deriveServiceFromPathToken(token));
+        }
+        for (const mention of this.extractServiceMentionsFromText(docsText))
+            register(mention);
+        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);
+            for (const statement of statements) {
+                const dependent = this.resolveServiceMentionFromPhrase(statement.dependent, aliases);
+                const dependency = this.resolveServiceMentionFromPhrase(statement.dependency, aliases);
+                if (!dependent || !dependency || dependent === dependency)
+                    continue;
+                const next = dependencies.get(dependent) ?? new Set();
+                next.add(dependency);
+                dependencies.set(dependent, next);
+            }
+        }
+        const services = this.sortServicesByDependency(Array.from(aliases.keys()), dependencies);
+        return { services, dependencies, aliases };
+    }
+    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;
+            if (rankA !== rankB)
+                return rankA - rankB;
+            const priorityA = a.priorityHint ?? Number.MAX_SAFE_INTEGER;
+            const priorityB = b.priorityHint ?? Number.MAX_SAFE_INTEGER;
+            if (priorityA !== priorityB)
+                return priorityA - priorityB;
+            return a.localId.localeCompare(b.localId);
+        };
+        const queue = storyTasks.filter((task) => (indegree.get(task.localId) ?? 0) === 0).sort(priorityComparator);
+        const ordered = [];
+        const seen = new Set();
+        while (queue.length > 0) {
+            const next = queue.shift();
+            if (!next || seen.has(next.localId))
+                continue;
+            seen.add(next.localId);
+            ordered.push(next);
+            const dependents = outgoing.get(next.localId);
+            if (!dependents)
+                continue;
+            for (const dependent of dependents) {
+                const updated = (indegree.get(dependent) ?? 0) - 1;
+                indegree.set(dependent, updated);
+                if (updated === 0) {
+                    const depTask = byLocalId.get(dependent);
+                    if (depTask)
+                        queue.push(depTask);
+                }
+            }
+            queue.sort(priorityComparator);
+        }
+        if (ordered.length === storyTasks.length)
+            return ordered;
+        const remaining = storyTasks.filter((task) => !seen.has(task.localId)).sort(priorityComparator);
+        return [...ordered, ...remaining];
+    }
+    applyServiceDependencySequencing(plan, docs) {
+        const graph = this.buildServiceDependencyGraph(plan, docs);
+        if (!graph.services.length)
+            return plan;
+        const serviceRank = new Map(graph.services.map((service, index) => [service, index]));
+        const resolveEntityService = (text) => this.resolveServiceMentionFromPhrase(text, graph.aliases);
+        const epics = plan.epics.map((epic) => ({ ...epic }));
+        const stories = plan.stories.map((story) => ({ ...story }));
+        const tasks = plan.tasks.map((task) => ({ ...task, dependsOnKeys: uniqueStrings(task.dependsOnKeys ?? []) }));
+        const storyByScope = new Map(stories.map((story) => [this.scopeStory(story), story]));
+        const taskServiceByScope = new Map();
+        for (const task of tasks) {
+            const text = `${task.title ?? ""}\n${task.description ?? ""}`;
+            taskServiceByScope.set(this.scopeTask(task), resolveEntityService(text));
+        }
+        const tasksByStory = new Map();
+        for (const task of tasks) {
+            const storyScope = this.storyScopeKey(task.epicLocalId, task.storyLocalId);
+            const bucket = tasksByStory.get(storyScope) ?? [];
+            bucket.push(task);
+            tasksByStory.set(storyScope, bucket);
+        }
+        for (const storyTasks of tasksByStory.values()) {
+            const tasksByService = new Map();
+            for (const task of storyTasks) {
+                const service = taskServiceByScope.get(this.scopeTask(task));
+                if (!service)
+                    continue;
+                const serviceTasks = tasksByService.get(service) ?? [];
+                serviceTasks.push(task);
+                tasksByService.set(service, serviceTasks);
+            }
+            for (const serviceTasks of tasksByService.values()) {
+                serviceTasks.sort((a, b) => (a.priorityHint ?? Number.MAX_SAFE_INTEGER) - (b.priorityHint ?? Number.MAX_SAFE_INTEGER));
+            }
+            for (const task of storyTasks) {
+                const service = taskServiceByScope.get(this.scopeTask(task));
+                if (!service)
+                    continue;
+                const requiredServices = graph.dependencies.get(service);
+                if (!requiredServices || requiredServices.size === 0)
+                    continue;
+                for (const requiredService of requiredServices) {
+                    const candidate = tasksByService.get(requiredService)?.[0];
+                    if (!candidate || candidate.localId === task.localId)
+                        continue;
+                    if (!(task.dependsOnKeys ?? []).includes(candidate.localId)) {
+                        task.dependsOnKeys = uniqueStrings([...(task.dependsOnKeys ?? []), candidate.localId]);
+                    }
+                }
+            }
+        }
+        const storyRankByScope = new Map();
+        for (const story of stories) {
+            const storyScope = this.scopeStory(story);
+            const storyTasks = tasksByStory.get(storyScope) ?? [];
+            const taskRanks = storyTasks
+                .map((task) => serviceRank.get(taskServiceByScope.get(this.scopeTask(task)) ?? ""))
+                .filter((value) => typeof value === "number");
+            const storyTextRank = serviceRank.get(resolveEntityService(`${story.title}\n${story.description ?? ""}\n${story.userStory ?? ""}`) ?? "");
+            const rank = taskRanks.length > 0 ? Math.min(...taskRanks) : storyTextRank ?? Number.MAX_SAFE_INTEGER;
+            storyRankByScope.set(storyScope, rank);
+        }
+        const epicRankByLocalId = new Map();
+        for (const epic of epics) {
+            const epicStories = stories.filter((story) => story.epicLocalId === epic.localId);
+            const storyRanks = epicStories
+                .map((story) => storyRankByScope.get(this.scopeStory(story)))
+                .filter((value) => typeof value === "number");
+            const epicTextRank = serviceRank.get(resolveEntityService(`${epic.title}\n${epic.description ?? ""}`) ?? "");
+            const rank = storyRanks.length > 0 ? Math.min(...storyRanks) : epicTextRank ?? Number.MAX_SAFE_INTEGER;
+            epicRankByLocalId.set(epic.localId, rank);
+        }
+        const isBootstrap = (value) => /bootstrap|foundation|structure/i.test(value);
+        epics.sort((a, b) => {
+            const bootstrapA = isBootstrap(`${a.title} ${a.description ?? ""}`);
+            const bootstrapB = isBootstrap(`${b.title} ${b.description ?? ""}`);
+            if (bootstrapA !== bootstrapB)
+                return bootstrapA ? -1 : 1;
+            const rankA = epicRankByLocalId.get(a.localId) ?? Number.MAX_SAFE_INTEGER;
+            const rankB = epicRankByLocalId.get(b.localId) ?? Number.MAX_SAFE_INTEGER;
+            if (rankA !== rankB)
+                return rankA - rankB;
+            const priorityA = a.priorityHint ?? Number.MAX_SAFE_INTEGER;
+            const priorityB = b.priorityHint ?? Number.MAX_SAFE_INTEGER;
+            if (priorityA !== priorityB)
+                return priorityA - priorityB;
+            return a.localId.localeCompare(b.localId);
+        });
+        epics.forEach((epic, index) => {
+            epic.priorityHint = index + 1;
+        });
+        const storiesOrdered = [];
+        const tasksOrdered = [];
+        for (const epic of epics) {
+            const epicStories = stories
+                .filter((story) => story.epicLocalId === epic.localId)
+                .sort((a, b) => {
+                const bootstrapA = isBootstrap(`${a.title} ${a.description ?? ""}`);
+                const bootstrapB = isBootstrap(`${b.title} ${b.description ?? ""}`);
+                if (bootstrapA !== bootstrapB)
+                    return bootstrapA ? -1 : 1;
+                const rankA = storyRankByScope.get(this.scopeStory(a)) ?? Number.MAX_SAFE_INTEGER;
+                const rankB = storyRankByScope.get(this.scopeStory(b)) ?? Number.MAX_SAFE_INTEGER;
+                if (rankA !== rankB)
+                    return rankA - rankB;
+                const priorityA = a.priorityHint ?? Number.MAX_SAFE_INTEGER;
+                const priorityB = b.priorityHint ?? Number.MAX_SAFE_INTEGER;
+                if (priorityA !== priorityB)
+                    return priorityA - priorityB;
+                return a.localId.localeCompare(b.localId);
+            });
+            epicStories.forEach((story, index) => {
+                story.priorityHint = index + 1;
+                storiesOrdered.push(story);
+                const storyTasks = tasksByStory.get(this.scopeStory(story)) ?? [];
+                const orderedTasks = this.orderStoryTasksByDependencies(storyTasks, serviceRank, taskServiceByScope);
+                orderedTasks.forEach((task, taskIndex) => {
+                    task.priorityHint = taskIndex + 1;
+                    tasksOrdered.push(task);
+                });
+            });
+        }
+        const orderedStoryScopes = new Set(storiesOrdered.map((story) => this.scopeStory(story)));
+        for (const story of stories) {
+            if (orderedStoryScopes.has(this.scopeStory(story)))
+                continue;
+            storiesOrdered.push(story);
+        }
+        const orderedTaskScopes = new Set(tasksOrdered.map((task) => this.scopeTask(task)));
+        for (const task of tasks) {
+            if (orderedTaskScopes.has(this.scopeTask(task)))
+                continue;
+            tasksOrdered.push(task);
+        }
+        // Keep parent linkage intact even if malformed story references exist.
+        for (const story of storiesOrdered) {
+            if (!storyByScope.has(this.scopeStory(story)))
+                continue;
+            story.epicLocalId = storyByScope.get(this.scopeStory(story))?.epicLocalId ?? story.epicLocalId;
+        }
+        return { epics, stories: storiesOrdered, tasks: tasksOrdered };
+    }
+    shouldInjectStructureBootstrap(plan, docs) {
+        if (docs.length === 0)
+            return false;
+        return !plan.tasks.some((task) => /codebase structure|folder tree|scaffold|bootstrap|repository layout|project skeleton/i.test(`${task.title} ${task.description ?? ""}`));
+    }
+    injectStructureBootstrapPlan(plan, docs, projectKey) {
+        if (!this.shouldInjectStructureBootstrap(plan, docs))
+            return plan;
+        const localIds = new Set([
+            ...plan.epics.map((epic) => epic.localId),
+            ...plan.stories.map((story) => story.localId),
+            ...plan.tasks.map((task) => task.localId),
+        ]);
+        const epicLocalId = nextUniqueLocalId("bootstrap-epic", localIds);
+        const storyLocalId = nextUniqueLocalId("bootstrap-story", localIds);
+        const task1LocalId = nextUniqueLocalId("bootstrap-task", localIds);
+        const task2LocalId = nextUniqueLocalId("bootstrap-task", localIds);
+        const task3LocalId = nextUniqueLocalId("bootstrap-task", localIds);
+        const structureTargets = this.extractStructureTargets(docs);
+        const directoryPreview = structureTargets.directories.length
+            ? structureTargets.directories.slice(0, 20).map((item) => `- ${item}`).join("\n")
+            : "- Infer top-level source directories from SDS sections and create them.";
+        const filePreview = structureTargets.files.length
+            ? structureTargets.files.slice(0, 20).map((item) => `- ${item}`).join("\n")
+            : "- Create minimal entrypoint/config placeholders required by the SDS-defined architecture.";
+        const relatedDocs = docs
+            .map((doc) => (doc.id ? `docdex:${doc.id}` : undefined))
+            .filter((value) => Boolean(value))
+            .slice(0, 12);
+        const bootstrapEpic = {
+            localId: epicLocalId,
+            area: normalizeArea(projectKey) ?? "infra",
+            title: "Codebase Foundation and Structure Setup",
+            description: "Create the SDS-defined codebase scaffold first (folders/files/service boundaries) before feature implementation tasks.",
+            acceptanceCriteria: [
+                "Required folder tree exists for the planned architecture.",
+                "Minimal entrypoint/config files exist for each discovered service/module.",
+                "Service dependency assumptions are explicit and actionable in follow-up tasks.",
+            ],
+            relatedDocs,
+            priorityHint: 1,
+            stories: [],
+        };
+        const bootstrapStory = {
+            localId: storyLocalId,
+            epicLocalId,
+            title: "Bootstrap repository structure from SDS",
+            userStory: "As an engineer, I want a concrete codebase scaffold first so implementation tasks can target real modules instead of only tests.",
+            description: [
+                "Parse SDS/PDR/OpenAPI context and establish the expected folder/file tree.",
+                "Start with dependencies-first service ordering (foundational components before dependents).",
+            ].join("\n"),
+            acceptanceCriteria: [
+                "Repository scaffold matches documented architecture at a high level.",
+                "Core service/module placeholders are committed as executable starting points.",
+                "Follow-up tasks reference real directories/files under the scaffold.",
+            ],
+            relatedDocs,
+            priorityHint: 1,
+            tasks: [],
+        };
+        const bootstrapTasks = [
+            {
+                localId: task1LocalId,
+                storyLocalId,
+                epicLocalId,
+                title: "Create SDS-aligned folder tree",
+                type: "chore",
+                description: [
+                    "Create the initial folder tree inferred from SDS and related docs.",
+                    "Target directories:",
+                    directoryPreview,
+                ].join("\n"),
+                estimatedStoryPoints: 2,
+                priorityHint: 1,
+                dependsOnKeys: [],
+                relatedDocs,
+                unitTests: [],
+                componentTests: [],
+                integrationTests: [],
+                apiTests: [],
+            },
+            {
+                localId: task2LocalId,
+                storyLocalId,
+                epicLocalId,
+                title: "Create foundational file stubs for discovered modules",
+                type: "chore",
+                description: [
+                    "Create minimal file stubs/config entrypoints for the scaffolded modules/services.",
+                    "Target files:",
+                    filePreview,
+                ].join("\n"),
+                estimatedStoryPoints: 3,
+                priorityHint: 2,
+                dependsOnKeys: [task1LocalId],
+                relatedDocs,
+                unitTests: [],
+                componentTests: [],
+                integrationTests: [],
+                apiTests: [],
+            },
+            {
+                localId: task3LocalId,
+                storyLocalId,
+                epicLocalId,
+                title: "Define service dependency baseline for implementation sequencing",
+                type: "spike",
+                description: "Document and codify service/module dependency direction so highly depended foundational services are implemented first.",
+                estimatedStoryPoints: 2,
+                priorityHint: 3,
+                dependsOnKeys: [task2LocalId],
+                relatedDocs,
+                unitTests: [],
+                componentTests: [],
+                integrationTests: [],
+                apiTests: [],
+            },
+        ];
+        return {
+            epics: [bootstrapEpic, ...plan.epics],
+            stories: [bootstrapStory, ...plan.stories],
+            tasks: [...bootstrapTasks, ...plan.tasks],
+        };
+    }
+    enforceStoryScopedDependencies(plan) {
+        const taskMap = new Map(plan.tasks.map((task) => [
+            this.scopeTask(task),
+            {
+                ...task,
+                dependsOnKeys: uniqueStrings((task.dependsOnKeys ?? []).filter(Boolean)),
+            },
+        ]));
+        const tasksByStory = new Map();
+        for (const task of taskMap.values()) {
+            const storyScope = this.storyScopeKey(task.epicLocalId, task.storyLocalId);
+            const storyTasks = tasksByStory.get(storyScope) ?? [];
+            storyTasks.push(task);
+            tasksByStory.set(storyScope, storyTasks);
+        }
+        for (const storyTasks of tasksByStory.values()) {
+            const localIds = new Set(storyTasks.map((task) => task.localId));
+            const foundationTasks = storyTasks
+                .filter((task) => classifyTask({
+                title: task.title ?? "",
+                description: task.description,
+                type: task.type,
+            }).foundation)
+                .sort((a, b) => (a.priorityHint ?? Number.MAX_SAFE_INTEGER) - (b.priorityHint ?? Number.MAX_SAFE_INTEGER));
+            const foundationAnchor = foundationTasks.find((task) => !(task.dependsOnKeys ?? []).some((dep) => localIds.has(dep)))?.localId ??
+                foundationTasks[0]?.localId;
+            for (const task of storyTasks) {
+                const filtered = (task.dependsOnKeys ?? []).filter((dep) => dep !== task.localId && localIds.has(dep));
+                const classification = classifyTask({
+                    title: task.title ?? "",
+                    description: task.description,
+                    type: task.type,
+                });
+                if (foundationAnchor &&
+                    foundationAnchor !== task.localId &&
+                    !classification.foundation &&
+                    !filtered.includes(foundationAnchor)) {
+                    filtered.push(foundationAnchor);
+                }
+                task.dependsOnKeys = uniqueStrings(filtered);
+            }
+        }
+        return {
+            ...plan,
+            tasks: plan.tasks.map((task) => taskMap.get(this.scopeTask(task)) ?? task),
+        };
+    }
+    validatePlanLocalIdentifiers(plan) {
+        const errors = [];
+        const epicIds = new Set();
+        for (const epic of plan.epics) {
+            if (!epic.localId || !epic.localId.trim()) {
+                errors.push("epic has missing localId");
+                continue;
+            }
+            if (epicIds.has(epic.localId)) {
+                errors.push(`duplicate epic localId: ${epic.localId}`);
+                continue;
+            }
+            epicIds.add(epic.localId);
+        }
+        const storyScopes = new Set();
+        for (const story of plan.stories) {
+            const scope = this.scopeStory(story);
+            if (!epicIds.has(story.epicLocalId)) {
+                errors.push(`story ${scope} references unknown epicLocalId ${story.epicLocalId}`);
+            }
+            if (storyScopes.has(scope)) {
+                errors.push(`duplicate story scope: ${scope}`);
+                continue;
+            }
+            storyScopes.add(scope);
+        }
+        const taskScopes = new Set();
+        const storyTaskLocals = new Map();
+        for (const task of plan.tasks) {
+            const storyScope = this.storyScopeKey(task.epicLocalId, task.storyLocalId);
+            const taskScope = this.scopeTask(task);
+            if (!storyScopes.has(storyScope)) {
+                errors.push(`task ${taskScope} references unknown story scope ${storyScope}`);
+            }
+            if (taskScopes.has(taskScope)) {
+                errors.push(`duplicate task scope: ${taskScope}`);
+                continue;
+            }
+            taskScopes.add(taskScope);
+            const locals = storyTaskLocals.get(storyScope) ?? new Set();
+            locals.add(task.localId);
+            storyTaskLocals.set(storyScope, locals);
+        }
+        for (const task of plan.tasks) {
+            const storyScope = this.storyScopeKey(task.epicLocalId, task.storyLocalId);
+            const localIds = storyTaskLocals.get(storyScope) ?? new Set();
+            for (const dep of task.dependsOnKeys ?? []) {
+                if (!dep || dep === task.localId)
+                    continue;
+                if (!localIds.has(dep)) {
+                    errors.push(`task ${this.scopeTask(task)} has dependency ${dep} that is outside story scope ${storyScope}`);
+                }
+            }
+        }
+        if (errors.length > 0) {
+            throw new Error(`Invalid generated plan local identifiers:\n- ${errors.join("\n- ")}`);
+        }
     }
     async buildQaPreflight() {
         const preflight = {
@@ -737,6 +1664,8 @@ export class CreateTasksService {
             "- Do NOT include final slugs; the system will assign keys.",
             "- Use docdex handles when referencing docs.",
             "- acceptanceCriteria must be an array of strings (5-10 items).",
+            "- Prefer dependency-first sequencing: foundational codebase/service setup epics should precede dependent feature epics.",
+            "- Keep output technology-agnostic and derived from docs; do not assume specific stacks unless docs state them.",
             limits || "Use reasonable scope without over-generating epics.",
             "Docs available:",
             docSummary || "- (no docs provided; propose sensible epics).",
@@ -973,6 +1902,9 @@ export class CreateTasksService {
             "- When known, include qa object with profiles_expected/requires/entrypoints/data_setup to guide QA.",
             "- Do not hardcode ports. For QA entrypoints, use http://localhost:<PORT> placeholders or omit base_url when unknown.",
             "- dependsOnKeys must reference localIds in this story.",
+            "- 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 (infrastructure -> backend/services -> frontend/consumers where applicable).",
             "- Use docdex handles when citing docs.",
             `Story context (key=${story.key ?? story.localId ?? "TBD"}):`,
             story.description ?? story.userStory ?? "",
@@ -1124,21 +2056,24 @@ export class CreateTasksService {
             for (const story of storyMeta) {
                 const storyId = storyIdByKey.get(story.storyKey);
                 const existingTaskKeys = storyId ? await this.workspaceRepo.listTaskKeys(storyId) : [];
-                const tasks = plan.tasks.filter((t) => t.storyLocalId === story.node.localId);
+                const tasks = plan.tasks.filter((t) => t.storyLocalId === story.node.localId && t.epicLocalId === story.node.epicLocalId);
                 const taskKeyGen = createTaskKeyGenerator(story.storyKey, existingTaskKeys);
                 for (const task of tasks) {
                     const key = taskKeyGen();
                     const localId = task.localId ?? key;
                     taskDetails.push({
                         localId,
+                        epicLocalId: story.node.epicLocalId,
                         key,
+                        storyLocalId: story.node.localId,
                         storyKey: story.storyKey,
                         epicKey: story.epicKey,
                         plan: task,
                     });
                 }
             }
-            const localToKey = new Map(taskDetails.map((t) => [t.localId, t.key]));
+            const scopedLocalKey = (epicLocalId, storyLocalId, localId) => this.taskScopeKey(epicLocalId, storyLocalId, localId);
+            const localToKey = new Map(taskDetails.map((t) => [scopedLocalKey(t.epicLocalId, t.storyLocalId, t.localId), t.key]));
             const taskInserts = [];
             const testCommandBuilder = new QaTestCommandBuilder(this.workspace.workspaceRoot);
             for (const task of taskDetails) {
@@ -1198,7 +2133,7 @@ export class CreateTasksService {
                     blockers: qaBlockers.length ? qaBlockers : undefined,
                 };
                 const depSlugs = (task.plan.dependsOnKeys ?? [])
-                    .map((dep) => localToKey.get(dep))
+                    .map((dep) => localToKey.get(scopedLocalKey(task.plan.epicLocalId, task.storyLocalId, dep)))
                     .filter((value) => Boolean(value));
                 const metadata = {
                     doc_links: task.plan.relatedDocs ?? [],
@@ -1235,17 +2170,17 @@ export class CreateTasksService {
             for (const detail of taskDetails) {
                 const row = taskRows.find((t) => t.key === detail.key);
                 if (row) {
-                    taskByLocal.set(detail.localId, row);
+                    taskByLocal.set(scopedLocalKey(detail.epicLocalId, detail.storyLocalId, detail.localId), row);
                 }
             }
             const depKeys = new Set();
             const dependencies = [];
             for (const detail of taskDetails) {
-                const current = taskByLocal.get(detail.localId);
+                const current = taskByLocal.get(scopedLocalKey(detail.epicLocalId, detail.storyLocalId, detail.localId));
                 if (!current)
                     continue;
                 for (const dep of detail.plan.dependsOnKeys ?? []) {
-                    const target = taskByLocal.get(dep);
+                    const target = taskByLocal.get(scopedLocalKey(detail.plan.epicLocalId, detail.storyLocalId, dep));
                     if (!target || target.id === current.id)
                         continue;
                     const depKey = `${current.id}|${target.id}|blocks`;
@@ -1340,13 +2275,19 @@ export class CreateTasksService {
                     timestamp: new Date().toISOString(),
                     details: { epics: epics.length },
                 });
-                const plan = await this.generatePlanFromAgent(epics, agent, docSummary, {
+                let plan = await this.generatePlanFromAgent(epics, agent, docSummary, {
                     agentStream,
                     jobId: job.id,
                     commandRunId: commandRun.id,
                     maxStoriesPerEpic: options.maxStoriesPerEpic,
                     maxTasksPerStory: options.maxTasksPerStory,
                 });
+                plan = this.enforceStoryScopedDependencies(plan);
+                plan = this.injectStructureBootstrapPlan(plan, docs, options.projectKey);
+                plan = this.enforceStoryScopedDependencies(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(),
@@ -1468,11 +2409,15 @@ export class CreateTasksService {
                 name: projectKey,
                 description: `Workspace project ${projectKey}`,
             });
-            const plan = {
+            let plan = {
                 epics: epics,
                 stories: stories,
                 tasks: tasks,
             };
+            plan = this.enforceStoryScopedDependencies(plan);
+            plan = this.applyServiceDependencySequencing(plan, []);
+            plan = this.enforceStoryScopedDependencies(plan);
+            this.validatePlanLocalIdentifiers(plan);
             const loadRefinePlans = async () => {
                 const candidates = [];
                 if (options.refinePlanPath)