@mcoda/core 0.1.32 → 0.1.34

package/dist/services/planning/CreateTasksService.d.ts

@@ -25,6 +25,7 @@ export interface CreateTasksOptions {
     qaRequires?: string[];
     sdsPreflightCommit?: boolean;
     sdsPreflightCommitMessage?: string;
+    unknownEpicServicePolicy?: EpicServiceValidationPolicy;
 }
 export interface CreateTasksResult {
     jobId: string;
@@ -34,6 +35,7 @@ export interface CreateTasksResult {
     tasks: TaskRow[];
     dependencies: TaskDependencyRow[];
 }
+type EpicServiceValidationPolicy = "auto-remediate" | "fail";
 type TaskOrderingClient = Pick<TaskOrderingService, "orderTasks" | "close">;
 type TaskOrderingFactory = (workspace: WorkspaceResolution, options?: {
     recordTelemetry?: boolean;
@@ -99,6 +101,12 @@ export declare class CreateTasksService {
     private extractStartupWaveHints;
     private sortServicesByDependency;
     private buildServiceDependencyGraph;
+    private normalizeServiceId;
+    private normalizeServiceLookupKey;
+    private createUniqueServiceId;
+    private buildServiceCatalogArtifact;
+    private buildServiceCatalogPromptSummary;
+    private alignEpicsToServiceCatalog;
     private buildProjectConstructionMethod;
     private buildProjectPlanArtifact;
     private orderStoryTasksByDependencies;
@@ -125,6 +133,8 @@ export declare class CreateTasksService {
     private buildFallbackTasksForStory;
     private generatePlanFromAgent;
     private buildSdsCoverageReport;
+    private acquirePlanArtifactLock;
+    private writeJsonArtifactAtomic;
     private writePlanArtifacts;
     private persistPlanToDb;
     createTasks(options: CreateTasksOptions): Promise<CreateTasksResult>;

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

@@ -1 +1 @@
-{"version":3,"file":"CreateTasksService.d.ts","sourceRoot":"","sources":["../../../src/services/planning/CreateTasksService.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAEL,OAAO,EACP,gBAAgB,EAEhB,QAAQ,EAER,iBAAiB,EAEjB,OAAO,EACP,mBAAmB,EACpB,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,YAAY,EAAkB,MAAM,qBAAqB,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAErE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAOxE,OAAO,EAAE,sBAAsB,EAAmC,MAAM,6BAA6B,CAAC;AACtG,OAAO,EAAE,mBAAmB,EAA2B,MAAM,0BAA0B,CAAC;AAExF,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,mBAAmB,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,YAAY,EAAE,iBAAiB,EAAE,CAAC;CACnC;AAiGD,KAAK,kBAAkB,GAAG,IAAI,CAAC,mBAAmB,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC;AAC5E,KAAK,mBAAmB,GAAG,CACzB,SAAS,EAAE,mBAAmB,EAC9B,OAAO,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,KACpC,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAEjC,KAAK,qBAAqB,GAAG,IAAI,CAAC,sBAAsB,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC;AAChF,KAAK,sBAAsB,GAAG,CAAC,SAAS,EAAE,mBAAmB,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;AACjG,KAAK,kBAAkB,GAAG,IAAI,CAAC,mBAAmB,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC;AAC9E,KAAK,mBAAmB,GAAG,CAAC,SAAS,EAAE,mBAAmB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AA40B3F,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAK;IAC7C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAO;IAC9C,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,IAAI,CAAmB;IAC/B,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,aAAa,CAAC,CAAqB;IAC3C,OAAO,CAAC,mBAAmB,CAAsB;IACjD,OAAO,CAAC,sBAAsB,CAAyB;IACvD,OAAO,CAAC,mBAAmB,CAAsB;gBAG/C,SAAS,EAAE,mBAAmB,EAC9B,IAAI,EAAE;QACJ,MAAM,EAAE,YAAY,CAAC;QACrB,UAAU,EAAE,UAAU,CAAC;QACvB,YAAY,EAAE,YAAY,CAAC;QAC3B,IAAI,EAAE,gBAAgB,CAAC;QACvB,aAAa,EAAE,mBAAmB,CAAC;QACnC,cAAc,EAAE,cAAc,CAAC;QAC/B,aAAa,CAAC,EAAE,kBAAkB,CAAC;QACnC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;QAC1C,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;QAChD,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;KAC3C;WAeU,MAAM,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAyB1E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB5B,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,SAAS;YAIH,cAAc;YAYd,YAAY;IAS1B,OAAO,CAAC,mBAAmB;YAYb,WAAW;IAwBzB,OAAO,CAAC,uBAAuB;IAM/B,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,SAAS;IAYjB,OAAO,CAAC,mBAAmB;YAWb,qBAAqB;YAuCrB,uBAAuB;YAwCvB,iBAAiB;IAyB/B,OAAO,CAAC,iBAAiB;YAqBX,kBAAkB;IA2BhC,OAAO,CAAC,2BAA2B;IAoBnC,OAAO,CAAC,uBAAuB;IA0B/B,OAAO,CAAC,oBAAoB;IAsB5B,OAAO,CAAC,0BAA0B;IAclC,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,8BAA8B;IAiBtC,OAAO,CAAC,+BAA+B;IAyBvC,OAAO,CAAC,2BAA2B;IA8CnC,OAAO,CAAC,uBAAuB;IAwF/B,OAAO,CAAC,wBAAwB;IA+DhC,OAAO,CAAC,2BAA2B;IA+CnC,OAAO,CAAC,8BAA8B;IAyCtC,OAAO,CAAC,wBAAwB;IAqBhC,OAAO,CAAC,6BAA6B;IA2DrC,OAAO,CAAC,gCAAgC;IAmJxC,OAAO,CAAC,8BAA8B;IAStC,OAAO,CAAC,4BAA4B;IA+HpC,OAAO,CAAC,8BAA8B;IAuDtC,OAAO,CAAC,4BAA4B;YAgEtB,gBAAgB;IA+E9B,OAAO,CAAC,gBAAgB;IAmBxB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,uBAAuB;IAmD/B,OAAO,CAAC,2BAA2B;IAsBnC,OAAO,CAAC,qBAAqB;IAM7B,OAAO,CAAC,eAAe;IA6DvB,OAAO,CAAC,WAAW;IAqCnB,OAAO,CAAC,YAAY;IAwEpB,OAAO,CAAC,uBAAuB;YAgEjB,oBAAoB;IA0KlC,OAAO,CAAC,UAAU;YAmBJ,sBAAsB;YA+CtB,qBAAqB;IAqFnC,OAAO,CAAC,yBAAyB;IAwBjC,OAAO,CAAC,0BAA0B;YAqEpB,qBAAqB;IAsHnC,OAAO,CAAC,sBAAsB;YAoDhB,kBAAkB;YAsBlB,eAAe;IA6RvB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA2bpE,qBAAqB,CAAC,OAAO,EAAE;QACnC,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;QAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAiJ/B"}
+{"version":3,"file":"CreateTasksService.d.ts","sourceRoot":"","sources":["../../../src/services/planning/CreateTasksService.ts"],"names":[],"mappings":"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"}

package/dist/services/planning/CreateTasksService.js

@@ -172,6 +172,8 @@ const DEPENDENCY_SCAN_LINE_LIMIT = 1400;
 const STARTUP_WAVE_SCAN_LINE_LIMIT = 4000;
 const VALID_AREAS = new Set(["web", "adm", "bck", "ops", "infra", "mobile"]);
 const VALID_TASK_TYPES = new Set(["feature", "bug", "chore", "spike"]);
+const VALID_EPIC_SERVICE_POLICIES = new Set(["auto-remediate", "fail"]);
+const CROSS_SERVICE_TAG = "cross_service";
 const inferDocType = (filePath) => {
     const name = path.basename(filePath).toLowerCase();
     if (name.includes("openapi") || name.includes("swagger"))
@@ -212,6 +214,17 @@ const normalizeTaskType = (value) => {
     }
     return undefined;
 };
+const normalizeEpicServicePolicy = (value) => {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (!VALID_EPIC_SERVICE_POLICIES.has(normalized))
+        return undefined;
+    return normalized;
+};
+const normalizeEpicTags = (value) => uniqueStrings(normalizeStringArray(value)
+    .map((item) => item.toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_+|_+$/g, ""))
+    .filter(Boolean));
 const normalizeRelatedDocs = (value) => {
     if (!Array.isArray(value))
         return [];
@@ -759,7 +772,9 @@ const EPIC_SCHEMA_SNIPPET = `{
       "description": "Epic description using the epic template",
       "acceptanceCriteria": ["criterion"],
       "relatedDocs": ["docdex:..."],
-      "priorityHint": 50
+      "priorityHint": 50,
+      "serviceIds": ["backend-api"],
+      "tags": ["cross_service"]
     }
   ]
 }`;
@@ -1514,6 +1529,11 @@ export class CreateTasksService {
             ...plan.stories.map((story) => `${story.title}\n${story.description ?? ""}\n${story.userStory ?? ""}`),
             ...plan.tasks.map((task) => `${task.title}\n${task.description ?? ""}`),
         ].join("\n");
+        for (const epic of plan.epics) {
+            for (const serviceId of normalizeStringArray(epic.serviceIds)) {
+                register(serviceId);
+            }
+        }
         const structureTargets = this.extractStructureTargets(docs);
         for (const token of [...structureTargets.directories, ...structureTargets.files]) {
             register(this.deriveServiceFromPathToken(token));
@@ -1550,6 +1570,322 @@ export class CreateTasksService {
             foundationalDependencies: waveHints.foundationalDependencies,
         };
     }
+    normalizeServiceId(value) {
+        const normalizedName = this.normalizeServiceName(value);
+        if (!normalizedName)
+            return undefined;
+        const slug = normalizedName
+            .replace(/\s+/g, "-")
+            .replace(/[^a-z0-9-]+/g, "-")
+            .replace(/-+/g, "-")
+            .replace(/^-+|-+$/g, "");
+        if (!slug)
+            return undefined;
+        return /^[a-z]/.test(slug) ? slug : `svc-${slug}`;
+    }
+    normalizeServiceLookupKey(value) {
+        return value
+            .toLowerCase()
+            .replace(/[`"'()[\]{}]/g, " ")
+            .replace(/[._/-]+/g, " ")
+            .replace(/[^a-z0-9\s]+/g, " ")
+            .replace(/\s+/g, " ")
+            .trim();
+    }
+    createUniqueServiceId(baseId, used) {
+        if (!used.has(baseId)) {
+            used.add(baseId);
+            return baseId;
+        }
+        let suffix = 2;
+        while (used.has(`${baseId}-${suffix}`))
+            suffix += 1;
+        const next = `${baseId}-${suffix}`;
+        used.add(next);
+        return next;
+    }
+    buildServiceCatalogArtifact(projectKey, docs, graph) {
+        const serviceNames = new Set(graph.services);
+        for (const [dependent, dependencies] of graph.dependencies.entries()) {
+            serviceNames.add(dependent);
+            for (const dependency of dependencies)
+                serviceNames.add(dependency);
+        }
+        for (const foundation of graph.foundationalDependencies) {
+            const normalized = this.normalizeServiceName(foundation);
+            if (normalized)
+                serviceNames.add(normalized);
+        }
+        const orderedNames = [
+            ...graph.services,
+            ...Array.from(serviceNames)
+                .filter((name) => !graph.services.includes(name))
+                .sort((a, b) => a.localeCompare(b)),
+        ];
+        const usedServiceIds = new Set();
+        const serviceIdByName = new Map();
+        for (const name of orderedNames) {
+            const baseId = this.normalizeServiceId(name);
+            if (!baseId)
+                continue;
+            serviceIdByName.set(name, this.createUniqueServiceId(baseId, usedServiceIds));
+        }
+        const services = [];
+        for (const name of orderedNames) {
+            const id = serviceIdByName.get(name);
+            if (!id)
+                continue;
+            const aliases = uniqueStrings([
+                name,
+                ...(graph.aliases.get(name) ? Array.from(graph.aliases.get(name) ?? []) : []),
+            ]).sort((a, b) => a.localeCompare(b));
+            const dependencyNames = Array.from(graph.dependencies.get(name) ?? []);
+            const dependsOnServiceIds = uniqueStrings(dependencyNames
+                .map((dependency) => serviceIdByName.get(dependency))
+                .filter((value) => Boolean(value)));
+            const startupWave = graph.waveRank.get(name);
+            const wave = typeof startupWave === "number" && Number.isFinite(startupWave) ? startupWave : undefined;
+            services.push({
+                id,
+                name,
+                aliases,
+                startupWave: wave,
+                dependsOnServiceIds,
+                isFoundational: graph.foundationalDependencies.some((foundation) => this.normalizeServiceName(foundation) === name || this.normalizeServiceId(foundation) === id) || dependsOnServiceIds.length === 0,
+            });
+        }
+        if (services.length === 0) {
+            const fallbackServiceId = this.normalizeServiceId(`${projectKey} core`) ?? `${projectKey}-core`;
+            services.push({
+                id: fallbackServiceId,
+                name: `${projectKey} core`,
+                aliases: uniqueStrings([`${projectKey} core`, projectKey, "core"]),
+                dependsOnServiceIds: [],
+                isFoundational: true,
+            });
+        }
+        const sourceDocs = docs
+            .map((doc) => doc.path ?? (doc.id ? `docdex:${doc.id}` : doc.title ?? "doc"))
+            .filter((value) => Boolean(value))
+            .slice(0, 24);
+        return {
+            projectKey,
+            generatedAt: new Date().toISOString(),
+            sourceDocs,
+            services,
+        };
+    }
+    buildServiceCatalogPromptSummary(catalog) {
+        if (!catalog.services.length) {
+            return "- No services detected. Infer services from SDS and ensure every epic includes at least one service id.";
+        }
+        const allIds = catalog.services.map((service) => service.id);
+        const idChunks = [];
+        for (let index = 0; index < allIds.length; index += 12) {
+            idChunks.push(allIds.slice(index, index + 12).join(", "));
+        }
+        const detailLimit = Math.min(catalog.services.length, 40);
+        const detailLines = catalog.services.slice(0, detailLimit).map((service) => {
+            const deps = service.dependsOnServiceIds.length > 0 ? service.dependsOnServiceIds.join(", ") : "none";
+            const wave = typeof service.startupWave === "number" ? `wave=${service.startupWave}` : "wave=unspecified";
+            return `- ${service.id} (${wave}; deps: ${deps}; aliases: ${service.aliases.slice(0, 5).join(", ")})`;
+        });
+        if (catalog.services.length > detailLimit) {
+            detailLines.push(`- ${catalog.services.length - detailLimit} additional services omitted from detailed lines (still listed in allowed serviceIds).`);
+        }
+        return [`- Allowed serviceIds (${allIds.length}):`, ...idChunks.map((chunk) => `  ${chunk}`), "- Service details:", ...detailLines].join("\n");
+    }
+    alignEpicsToServiceCatalog(epics, catalog, policy) {
+        const warnings = [];
+        const validServiceIds = new Set(catalog.services.map((service) => service.id));
+        const serviceOrder = new Map(catalog.services.map((service, index) => [service.id, index]));
+        const aliasToIds = new Map();
+        const idLookup = new Map();
+        const registerAlias = (rawValue, serviceId) => {
+            const normalized = this.normalizeServiceLookupKey(rawValue);
+            if (!normalized)
+                return;
+            const bucket = aliasToIds.get(normalized) ?? new Set();
+            bucket.add(serviceId);
+            aliasToIds.set(normalized, bucket);
+        };
+        for (const service of catalog.services) {
+            const normalizedId = this.normalizeServiceLookupKey(service.id);
+            if (normalizedId)
+                idLookup.set(normalizedId, service.id);
+            registerAlias(service.id, service.id);
+            registerAlias(service.name, service.id);
+            for (const alias of service.aliases) {
+                registerAlias(alias, service.id);
+            }
+        }
+        const containsLookupPhrase = (haystack, phrase) => {
+            if (!haystack || !phrase)
+                return false;
+            if (!phrase.includes(" ") && phrase.length < 4)
+                return false;
+            return ` ${haystack} `.includes(` ${phrase} `);
+        };
+        const mapCandidateToServiceId = (value) => {
+            const normalized = this.normalizeServiceLookupKey(value);
+            if (!normalized)
+                return {};
+            const directId = idLookup.get(normalized);
+            if (directId)
+                return { resolvedId: directId };
+            const aliasMatches = aliasToIds.get(normalized);
+            if (aliasMatches && aliasMatches.size === 1) {
+                return { resolvedId: Array.from(aliasMatches)[0] };
+            }
+            if (aliasMatches && aliasMatches.size > 1) {
+                return {
+                    ambiguousIds: Array.from(aliasMatches).sort((a, b) => (serviceOrder.get(a) ?? Number.MAX_SAFE_INTEGER) - (serviceOrder.get(b) ?? Number.MAX_SAFE_INTEGER)),
+                };
+            }
+            const idFromName = this.normalizeServiceId(normalized);
+            if (!idFromName)
+                return {};
+            if (validServiceIds.has(idFromName))
+                return { resolvedId: idFromName };
+            const candidates = Array.from(validServiceIds)
+                .filter((id) => id === idFromName || id.startsWith(`${idFromName}-`))
+                .sort((a, b) => (serviceOrder.get(a) ?? Number.MAX_SAFE_INTEGER) - (serviceOrder.get(b) ?? Number.MAX_SAFE_INTEGER));
+            if (candidates.length === 1)
+                return { resolvedId: candidates[0] };
+            if (candidates.length > 1)
+                return { ambiguousIds: candidates };
+            return {};
+        };
+        const inferServiceIdsFromEpicText = (epic) => {
+            const text = this.normalizeServiceLookupKey([epic.title, epic.description ?? "", ...(epic.acceptanceCriteria ?? [])]
+                .filter(Boolean)
+                .join("\n"));
+            if (!text)
+                return [];
+            const scored = new Map();
+            for (const service of catalog.services) {
+                let score = 0;
+                const idToken = this.normalizeServiceLookupKey(service.id);
+                if (idToken && containsLookupPhrase(text, idToken)) {
+                    score = Math.max(score, 120 + idToken.length);
+                }
+                const nameToken = this.normalizeServiceLookupKey(service.name);
+                if (nameToken && containsLookupPhrase(text, nameToken)) {
+                    score = Math.max(score, 90 + nameToken.length);
+                }
+                for (const alias of service.aliases) {
+                    const aliasToken = this.normalizeServiceLookupKey(alias);
+                    if (!aliasToken || aliasToken === idToken || aliasToken === nameToken)
+                        continue;
+                    if (containsLookupPhrase(text, aliasToken)) {
+                        score = Math.max(score, 60 + aliasToken.length);
+                    }
+                }
+                if (score > 0)
+                    scored.set(service.id, score);
+            }
+            return Array.from(scored.entries())
+                .sort((a, b) => b[1] - a[1] || (serviceOrder.get(a[0]) ?? 0) - (serviceOrder.get(b[0]) ?? 0))
+                .map(([id]) => id)
+                .slice(0, 4);
+        };
+        const pickFallbackServiceIds = (epic, count) => {
+            const text = this.normalizeServiceLookupKey([epic.title, epic.description ?? "", ...(epic.acceptanceCriteria ?? [])]
+                .filter(Boolean)
+                .join("\n"));
+            const ranked = catalog.services
+                .map((service) => {
+                let score = 0;
+                if (service.isFoundational)
+                    score += 100;
+                if (typeof service.startupWave === "number")
+                    score += Math.max(0, 40 - service.startupWave * 2);
+                if (service.dependsOnServiceIds.length === 0)
+                    score += 20;
+                const tokens = uniqueStrings([service.id, service.name, ...service.aliases])
+                    .map((value) => this.normalizeServiceLookupKey(value))
+                    .filter(Boolean);
+                for (const token of tokens) {
+                    if (containsLookupPhrase(text, token)) {
+                        score += 25 + token.length;
+                    }
+                }
+                return { id: service.id, score };
+            })
+                .sort((a, b) => b.score - a.score ||
+                (serviceOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER) - (serviceOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER));
+            return ranked.slice(0, Math.max(1, count)).map((entry) => entry.id);
+        };
+        const normalizedEpics = epics.map((epic, index) => {
+            const explicitServiceIds = normalizeStringArray(epic.serviceIds);
+            const resolvedServiceIds = [];
+            const unresolvedServiceIds = [];
+            const ambiguousServiceIds = [];
+            for (const candidate of explicitServiceIds) {
+                const mapped = mapCandidateToServiceId(candidate);
+                if (mapped.resolvedId) {
+                    resolvedServiceIds.push(mapped.resolvedId);
+                }
+                else if ((mapped.ambiguousIds?.length ?? 0) > 1) {
+                    ambiguousServiceIds.push({ candidate, options: mapped.ambiguousIds ?? [] });
+                    unresolvedServiceIds.push(candidate);
+                }
+                else {
+                    unresolvedServiceIds.push(candidate);
+                }
+            }
+            const inferredServiceIds = inferServiceIdsFromEpicText(epic);
+            const targetServiceCount = Math.max(1, Math.min(3, explicitServiceIds.length || 1));
+            if (policy === "auto-remediate") {
+                for (const inferred of inferredServiceIds) {
+                    if (resolvedServiceIds.includes(inferred))
+                        continue;
+                    resolvedServiceIds.push(inferred);
+                    if (resolvedServiceIds.length >= targetServiceCount)
+                        break;
+                }
+                if (resolvedServiceIds.length === 0 && catalog.services.length > 0) {
+                    resolvedServiceIds.push(...pickFallbackServiceIds(epic, 1));
+                }
+            }
+            else if (resolvedServiceIds.length === 0 && inferredServiceIds.length > 0) {
+                resolvedServiceIds.push(...inferredServiceIds.slice(0, Math.max(1, targetServiceCount)));
+            }
+            const dedupedServiceIds = uniqueStrings(resolvedServiceIds)
+                .filter((serviceId) => validServiceIds.has(serviceId))
+                .sort((a, b) => (serviceOrder.get(a) ?? Number.MAX_SAFE_INTEGER) - (serviceOrder.get(b) ?? Number.MAX_SAFE_INTEGER));
+            if (dedupedServiceIds.length === 0) {
+                throw new Error(`Epic ${epic.localId ?? index + 1} (${epic.title}) has no valid phase-0 service references. Allowed service ids: ${Array.from(validServiceIds).join(", ")}`);
+            }
+            if (unresolvedServiceIds.length > 0 || ambiguousServiceIds.length > 0) {
+                const unresolvedLabel = unresolvedServiceIds.length > 0 ? unresolvedServiceIds.join(", ") : "(none)";
+                const issueLabel = unresolvedServiceIds.length > 0 ? "unknown service ids" : "ambiguous service ids";
+                const ambiguity = ambiguousServiceIds.length > 0
+                    ? ` Ambiguous mappings: ${ambiguousServiceIds
+                        .map((item) => `${item.candidate} -> [${item.options.join(", ")}]`)
+                        .join("; ")}.`
+                    : "";
+                const message = `Epic ${epic.localId ?? index + 1} (${epic.title}) referenced ${issueLabel}: ${unresolvedLabel}.${ambiguity}`;
+                if (policy === "fail") {
+                    throw new Error(`${message} Allowed service ids: ${Array.from(validServiceIds).join(", ")}`);
+                }
+                warnings.push(`${message} Auto-remediated to: ${dedupedServiceIds.join(", ")}`);
+            }
+            const tags = normalizeEpicTags(epic.tags);
+            if (dedupedServiceIds.length > 1 && !tags.includes(CROSS_SERVICE_TAG)) {
+                tags.push(CROSS_SERVICE_TAG);
+            }
+            if (dedupedServiceIds.length <= 1 && tags.includes(CROSS_SERVICE_TAG)) {
+                warnings.push(`Epic ${epic.localId ?? index + 1} (${epic.title}) has tag ${CROSS_SERVICE_TAG} but only one service id (${dedupedServiceIds.join(", ")}). Keeping tag as explicit cross-cutting marker.`);
+            }
+            return {
+                ...epic,
+                serviceIds: dedupedServiceIds,
+                tags: uniqueStrings(tags),
+            };
+        });
+        return { epics: normalizedEpics, warnings };
+    }
     buildProjectConstructionMethod(docs, graph) {
         const toLabel = (value) => value.replace(/\s+/g, "-");
         const structureTargets = this.extractStructureTargets(docs);
@@ -1600,6 +1936,7 @@ export class CreateTasksService {
             sourceDocs,
             startupWaves: graph.startupWaves.slice(0, 12),
             services: graph.services.slice(0, 40),
+            serviceIds: graph.services.map((service) => this.normalizeServiceId(service) ?? service.replace(/\s+/g, "-")).slice(0, 40),
             foundationalDependencies: graph.foundationalDependencies.slice(0, 16),
             buildMethod,
         };
@@ -1675,14 +2012,36 @@ export class CreateTasksService {
             return [service, wave * 10000 + order];
         }));
         const resolveEntityService = (text) => this.resolveServiceMentionFromPhrase(text, graph.aliases);
+        const resolveServiceFromIds = (serviceIds) => {
+            for (const serviceId of normalizeStringArray(serviceIds)) {
+                const resolved = resolveEntityService(serviceId) ?? this.addServiceAlias(graph.aliases, serviceId);
+                if (resolved)
+                    return resolved;
+            }
+            return undefined;
+        };
         const epics = plan.epics.map((epic) => ({ ...epic }));
         const stories = plan.stories.map((story) => ({ ...story }));
         const tasks = plan.tasks.map((task) => ({ ...task, dependsOnKeys: uniqueStrings(task.dependsOnKeys ?? []) }));
         const storyByScope = new Map(stories.map((story) => [this.scopeStory(story), story]));
+        const epicServiceByLocalId = new Map();
+        const storyServiceByScope = new Map();
         const taskServiceByScope = new Map();
+        for (const epic of epics) {
+            const serviceFromIds = resolveServiceFromIds(epic.serviceIds);
+            const serviceFromText = resolveEntityService(`${epic.title}\n${epic.description ?? ""}`);
+            epicServiceByLocalId.set(epic.localId, serviceFromIds ?? serviceFromText);
+        }
+        for (const story of stories) {
+            const storyScope = this.scopeStory(story);
+            const inherited = epicServiceByLocalId.get(story.epicLocalId);
+            const serviceFromText = resolveEntityService(`${story.title}\n${story.description ?? ""}\n${story.userStory ?? ""}`);
+            storyServiceByScope.set(storyScope, serviceFromText ?? inherited);
+        }
         for (const task of tasks) {
+            const storyScope = this.storyScopeKey(task.epicLocalId, task.storyLocalId);
             const text = `${task.title ?? ""}\n${task.description ?? ""}`;
-            taskServiceByScope.set(this.scopeTask(task), resolveEntityService(text));
+            taskServiceByScope.set(this.scopeTask(task), resolveEntityService(text) ?? storyServiceByScope.get(storyScope));
         }
         const tasksByStory = new Map();
         for (const task of tasks) {
@@ -1728,7 +2087,7 @@ export class CreateTasksService {
             const taskRanks = storyTasks
                 .map((task) => serviceRank.get(taskServiceByScope.get(this.scopeTask(task)) ?? ""))
                 .filter((value) => typeof value === "number");
-            const storyTextRank = serviceRank.get(resolveEntityService(`${story.title}\n${story.description ?? ""}\n${story.userStory ?? ""}`) ?? "");
+            const storyTextRank = serviceRank.get(storyServiceByScope.get(storyScope) ?? "");
             const rank = taskRanks.length > 0 ? Math.min(...taskRanks) : storyTextRank ?? Number.MAX_SAFE_INTEGER;
             storyRankByScope.set(storyScope, rank);
         }
@@ -1738,7 +2097,7 @@ export class CreateTasksService {
             const storyRanks = epicStories
                 .map((story) => storyRankByScope.get(this.scopeStory(story)))
                 .filter((value) => typeof value === "number");
-            const epicTextRank = serviceRank.get(resolveEntityService(`${epic.title}\n${epic.description ?? ""}`) ?? "");
+            const epicTextRank = serviceRank.get(epicServiceByLocalId.get(epic.localId) ?? "");
             const rank = storyRanks.length > 0 ? Math.min(...storyRanks) : epicTextRank ?? Number.MAX_SAFE_INTEGER;
             epicRankByLocalId.set(epic.localId, rank);
         }
@@ -2295,8 +2654,9 @@ export class CreateTasksService {
         }
         return { docSummary: blocks.join("\n\n") || "(no docs)", warnings };
     }
-    buildPrompt(projectKey, docs, projectBuildMethod, options) {
+    buildPrompt(projectKey, docs, projectBuildMethod, serviceCatalog, options) {
         const docSummary = docs.map((doc, idx) => describeDoc(doc, idx)).join("\n");
+        const serviceCatalogSummary = this.buildServiceCatalogPromptSummary(serviceCatalog);
         const limits = [
             options.maxEpics ? `Limit epics to ${options.maxEpics}.` : "",
             options.maxStoriesPerEpic ? `Limit stories per epic to ${options.maxStoriesPerEpic}.` : "",
@@ -2317,8 +2677,12 @@ export class CreateTasksService {
             "- Keep epics actionable and implementation-oriented; avoid glossary/admin-only epics.",
             "- Prefer dependency-first sequencing: foundational setup epics before dependent feature epics.",
             "- Keep output derived from docs; do not assume stacks unless docs state them.",
+            "- serviceIds is required and must contain one or more ids from the phase-0 service catalog below.",
+            `- If an epic spans multiple services, include tag \"${CROSS_SERVICE_TAG}\" in tags.`,
             "Project construction method to follow:",
             projectBuildMethod,
+            "Phase 0 service catalog (allowed serviceIds):",
+            serviceCatalogSummary,
             limits || "Use reasonable scope without over-generating epics.",
             "Docs available:",
             docSummary || "- (no docs provided; propose sensible epics).",
@@ -2618,6 +2982,8 @@ export class CreateTasksService {
             acceptanceCriteria: Array.isArray(epic.acceptanceCriteria) ? epic.acceptanceCriteria : [],
             relatedDocs: normalizeRelatedDocs(epic.relatedDocs),
             priorityHint: typeof epic.priorityHint === "number" ? epic.priorityHint : undefined,
+            serviceIds: normalizeStringArray(epic.serviceIds),
+            tags: normalizeEpicTags(epic.tags),
             stories: [],
         }))
             .filter((e) => e.title);
@@ -2636,6 +3002,8 @@ export class CreateTasksService {
             "- Keep story sequencing aligned with the project construction method.",
             `Epic context (key=${epic.key ?? epic.localId ?? "TBD"}):`,
             epic.description ?? "(no description provided)",
+            `Epic serviceIds: ${(epic.serviceIds ?? []).join(", ") || "(not provided)"}`,
+            `Epic tags: ${(epic.tags ?? []).join(", ") || "(none)"}`,
             "Project construction method:",
             projectBuildMethod,
             `Docs: ${docSummary || "none"}`,
@@ -2939,19 +3307,91 @@ export class CreateTasksService {
                 : ["Coverage is heading-based heuristic match between SDS sections and generated epic/story/task corpus."],
         };
     }
-    async writePlanArtifacts(projectKey, plan, docSummary, docs, buildPlan) {
+    async acquirePlanArtifactLock(baseDir, options) {
+        const timeoutMs = options?.timeoutMs ?? 10000;
+        const pollIntervalMs = options?.pollIntervalMs ?? 80;
+        const staleLockMs = options?.staleLockMs ?? 120000;
+        const lockPath = path.join(baseDir, ".plan-artifacts.lock");
+        const startedAtMs = Date.now();
+        while (true) {
+            try {
+                const handle = await fs.open(lockPath, "wx");
+                await handle.writeFile(JSON.stringify({ pid: process.pid, acquiredAt: new Date().toISOString() }), "utf8");
+                return async () => {
+                    try {
+                        await handle.close();
+                    }
+                    catch { }
+                    await fs.rm(lockPath, { force: true });
+                };
+            }
+            catch (error) {
+                const code = error.code;
+                if (code !== "EEXIST")
+                    throw error;
+                try {
+                    const stat = await fs.stat(lockPath);
+                    if (Date.now() - stat.mtimeMs > staleLockMs) {
+                        await fs.rm(lockPath, { force: true });
+                        continue;
+                    }
+                }
+                catch {
+                    continue;
+                }
+                if (Date.now() - startedAtMs >= timeoutMs) {
+                    throw new Error(`Timed out acquiring plan artifact lock for ${baseDir}`);
+                }
+                await delay(pollIntervalMs);
+            }
+        }
+    }
+    async writeJsonArtifactAtomic(targetPath, data) {
+        const tempPath = `${targetPath}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+        const payload = JSON.stringify(data, null, 2);
+        await fs.writeFile(tempPath, payload, "utf8");
+        try {
+            await fs.rename(tempPath, targetPath);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "EEXIST" || code === "EPERM") {
+                await fs.rm(targetPath, { force: true });
+                await fs.rename(tempPath, targetPath);
+            }
+            else {
+                await fs.rm(tempPath, { force: true });
+                throw error;
+            }
+        }
+    }
+    async writePlanArtifacts(projectKey, plan, docSummary, docs, buildPlan, serviceCatalog) {
         const baseDir = path.join(this.workspace.mcodaDir, "tasks", projectKey);
         await fs.mkdir(baseDir, { recursive: true });
-        const write = async (file, data) => {
-            const target = path.join(baseDir, file);
-            await fs.writeFile(target, JSON.stringify(data, null, 2), "utf8");
-        };
-        await write("plan.json", { projectKey, generatedAt: new Date().toISOString(), docSummary, buildPlan, ...plan });
-        await write("build-plan.json", buildPlan);
-        await write("epics.json", plan.epics);
-        await write("stories.json", plan.stories);
-        await write("tasks.json", plan.tasks);
-        await write("coverage-report.json", this.buildSdsCoverageReport(projectKey, docs, plan));
+        const releaseLock = await this.acquirePlanArtifactLock(baseDir);
+        try {
+            const write = async (file, data) => {
+                const target = path.join(baseDir, file);
+                await this.writeJsonArtifactAtomic(target, data);
+            };
+            await write("plan.json", {
+                projectKey,
+                generatedAt: new Date().toISOString(),
+                docSummary,
+                buildPlan,
+                serviceCatalog,
+                ...plan,
+            });
+            await write("build-plan.json", buildPlan);
+            await write("services.json", serviceCatalog);
+            await write("epics.json", plan.epics);
+            await write("stories.json", plan.stories);
+            await write("tasks.json", plan.tasks);
+            await write("coverage-report.json", this.buildSdsCoverageReport(projectKey, docs, plan));
+        }
+        finally {
+            await releaseLock();
+        }
         return { folder: baseDir };
     }
     async persistPlanToDb(projectId, projectKey, plan, jobId, commandRunId, options) {
@@ -2969,7 +3409,13 @@ export class CreateTasksService {
                 description: buildEpicDescription(key, epic.title || `Epic ${key}`, epic.description, epic.acceptanceCriteria, epic.relatedDocs),
                 storyPointsTotal: null,
                 priority: epic.priorityHint ?? (epicInserts.length + 1),
-                metadata: epic.relatedDocs ? { doc_links: epic.relatedDocs } : undefined,
+                metadata: epic.relatedDocs || (epic.serviceIds?.length ?? 0) > 0 || (epic.tags?.length ?? 0) > 0
+                    ? {
+                        ...(epic.relatedDocs ? { doc_links: epic.relatedDocs } : {}),
+                        ...(epic.serviceIds && epic.serviceIds.length > 0 ? { service_ids: epic.serviceIds } : {}),
+                        ...(epic.tags && epic.tags.length > 0 ? { tags: epic.tags } : {}),
+                    }
+                    : undefined,
             });
             epicMeta.push({ key, node: epic });
         }
@@ -3187,6 +3633,7 @@ export class CreateTasksService {
     }
     async createTasks(options) {
         const agentStream = options.agentStream !== false;
+        const unknownEpicServicePolicy = normalizeEpicServicePolicy(options.unknownEpicServicePolicy) ?? "auto-remediate";
         const commandRun = await this.jobService.startCommandRun("create-tasks", options.projectKey);
         const job = await this.jobService.startJob("create_tasks", commandRun.id, options.projectKey, {
             commandName: "create-tasks",
@@ -3196,6 +3643,7 @@ export class CreateTasksService {
                 agent: options.agentName,
                 agentStream,
                 sdsPreflightCommit: options.sdsPreflightCommit === true,
+                unknownEpicServicePolicy,
             },
         });
         let lastError;
@@ -3311,9 +3759,10 @@ export class CreateTasksService {
                 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, options);
+                const { prompt } = this.buildPrompt(options.projectKey, docs, projectBuildMethod, serviceCatalog, options);
                 const qaPreflight = await this.buildQaPreflight();
                 const qaOverrides = this.buildQaOverrides(options);
                 await this.jobService.writeCheckpoint(job.id, {
@@ -3330,6 +3779,18 @@ export class CreateTasksService {
                         startupWaves: projectBuildPlan.startupWaves.length,
                     },
                 });
+                await this.jobService.writeCheckpoint(job.id, {
+                    stage: "phase0_services_defined",
+                    timestamp: new Date().toISOString(),
+                    details: {
+                        services: serviceCatalog.services.length,
+                        foundational: serviceCatalog.services.filter((service) => service.isFoundational).length,
+                        startupWaves: uniqueStrings(serviceCatalog.services
+                            .map((service) => (typeof service.startupWave === "number" ? String(service.startupWave) : ""))
+                            .filter(Boolean)).length,
+                        sourceDocs: serviceCatalog.sourceDocs.length,
+                    },
+                });
                 await this.jobService.writeCheckpoint(job.id, {
                     stage: "qa_preflight",
                     timestamp: new Date().toISOString(),
@@ -3342,7 +3803,12 @@ export class CreateTasksService {
                 try {
                     agent = await this.resolveAgent(options.agentName);
                     const { output: epicOutput } = await this.invokeAgentWithRetry(agent, prompt, "epics", agentStream, job.id, commandRun.id, { docWarnings });
-                    const epics = this.parseEpics(epicOutput, docs, options.projectKey).slice(0, options.maxEpics ?? Number.MAX_SAFE_INTEGER);
+                    const parsedEpics = this.parseEpics(epicOutput, docs, options.projectKey).slice(0, options.maxEpics ?? Number.MAX_SAFE_INTEGER);
+                    const normalizedEpics = this.alignEpicsToServiceCatalog(parsedEpics, serviceCatalog, unknownEpicServicePolicy);
+                    for (const warning of normalizedEpics.warnings) {
+                        await this.jobService.appendLog(job.id, `[create-tasks] ${warning}\n`);
+                    }
+                    const epics = normalizedEpics.epics;
                     await this.jobService.writeCheckpoint(job.id, {
                         stage: "epics_generated",
                         timestamp: new Date().toISOString(),
@@ -3359,6 +3825,10 @@ export class CreateTasksService {
                 }
                 catch (error) {
                     fallbackReason = error.message ?? String(error);
+                    if (unknownEpicServicePolicy === "fail" &&
+                        /unknown service ids|phase-0 service references/i.test(fallbackReason)) {
+                        throw error;
+                    }
                     planSource = "fallback";
                     await this.jobService.appendLog(job.id, `Agent planning failed, using deterministic fallback plan: ${fallbackReason}\n`);
                     plan = this.materializePlanFromSeed(this.fallbackPlan(options.projectKey, docs), {
@@ -3372,6 +3842,18 @@ export class CreateTasksService {
                         details: { epics: plan.epics.length, source: planSource, reason: fallbackReason },
                     });
                 }
+                const normalizedPlanEpics = this.alignEpicsToServiceCatalog(plan.epics, serviceCatalog, unknownEpicServicePolicy);
+                for (const warning of normalizedPlanEpics.warnings) {
+                    await this.jobService.appendLog(job.id, `[create-tasks] ${warning}\n`);
+                }
+                plan = {
+                    ...plan,
+                    epics: normalizedPlanEpics.epics.map((epic, index) => ({
+                        ...epic,
+                        localId: epic.localId ?? `e${index + 1}`,
+                        stories: [],
+                    })),
+                };
                 plan = this.enforceStoryScopedDependencies(plan);
                 plan = this.injectStructureBootstrapPlan(plan, docs, options.projectKey);
                 plan = this.enforceStoryScopedDependencies(plan);
@@ -3389,7 +3871,7 @@ export class CreateTasksService {
                     timestamp: new Date().toISOString(),
                     details: { tasks: plan.tasks.length, source: planSource, fallbackReason },
                 });
-                const { folder } = await this.writePlanArtifacts(options.projectKey, plan, docSummary, docs, projectBuildPlan);
+                const { folder } = await this.writePlanArtifacts(options.projectKey, plan, docSummary, docs, projectBuildPlan, serviceCatalog);
                 await this.jobService.writeCheckpoint(job.id, {
                     stage: "plan_written",
                     timestamp: new Date().toISOString(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcoda/core",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "description": "Core services and APIs for the mcoda CLI.",
   "type": "module",
   "main": "dist/index.js",
@@ -32,11 +32,11 @@
   "dependencies": {
     "@apidevtools/swagger-parser": "^10.1.0",
     "yaml": "^2.4.2",
-    "@mcoda/shared": "0.1.32",
-    "@mcoda/db": "0.1.32",
-    "@mcoda/agents": "0.1.32",
-    "@mcoda/integrations": "0.1.32",
-    "@mcoda/generators": "0.1.32"
+    "@mcoda/shared": "0.1.34",
+    "@mcoda/db": "0.1.34",
+    "@mcoda/agents": "0.1.34",
+    "@mcoda/generators": "0.1.34",
+    "@mcoda/integrations": "0.1.34"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",