@mcoda/core 0.1.19 → 0.1.21

package/dist/services/execution/WorkOnTasksService.d.ts

@@ -26,6 +26,7 @@ export interface WorkOnTasksRequest extends TaskSelectionFilters {
     allowFileOverwrite?: boolean;
     missingTestsPolicy?: MissingTestsPolicy;
     allowMissingTests?: boolean;
+    executionContextPolicy?: ExecutionContextPolicy;
 }
 export interface TaskExecutionResult {
     taskKey: string;
@@ -40,7 +41,8 @@ export interface WorkOnTasksResult {
     results: TaskExecutionResult[];
     warnings: string[];
 }
-export type MissingTestsPolicy = "block_job" | "skip_task" | "fail_task";
+export type MissingTestsPolicy = "block_job" | "skip_task" | "fail_task" | "continue_task";
+export type ExecutionContextPolicy = "best_effort" | "require_any" | "require_sds_or_openapi";
 export declare class WorkOnTasksService {
     private workspace;
     private deps;
@@ -79,6 +81,8 @@ export declare class WorkOnTasksService {
     private logTask;
     private recordTokenUsage;
     private updateTaskPhase;
+    private enforceExecutionContextPolicy;
+    private resolveExecutionPlanningContext;
     private gatherDocContext;
     private parseCommentBody;
     private buildCommentBacklog;

package/dist/services/execution/WorkOnTasksService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WorkOnTasksService.d.ts","sourceRoot":"","sources":["../../../src/services/execution/WorkOnTasksService.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,YAAY,EAAgD,MAAM,eAAe,CAAC;AAC3F,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE9D,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAuB,MAAM,WAAW,CAAC;AAEvF,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAiB,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC1G,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAsFrE,MAAM,WAAW,kBAAmB,SAAQ,oBAAoB;IAC9D,SAAS,EAAE,mBAAmB,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA6wBD,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AA2rCzE,qBAAa,kBAAkB;IA0B3B,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,IAAI;IA1Bd,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,YAAY,CAAmB;IACvC,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,aAAa,CAAC,CAAqB;YAC7B,eAAe;gBAmBnB,SAAS,EAAE,mBAAmB,EAC9B,IAAI,EAAE;QACZ,YAAY,EAAE,YAAY,CAAC;QAC3B,MAAM,EAAE,YAAY,CAAC;QACrB,UAAU,EAAE,UAAU,CAAC;QACvB,aAAa,EAAE,mBAAmB,CAAC;QACnC,gBAAgB,CAAC,EAAE,oBAAoB,CAAC;QACxC,YAAY,CAAC,EAAE,gBAAgB,CAAC;QAChC,IAAI,EAAE,gBAAgB,CAAC;QACvB,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,cAAc,EAAE,cAAc,CAAC;QAC/B,aAAa,CAAC,EAAE,kBAAkB,CAAC;KACpC;YASW,WAAW;YAsDX,WAAW;YAIX,mBAAmB;YAOnB,oBAAoB;YAUpB,UAAU;WAUX,MAAM,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA6B1E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB5B,qBAAqB,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;YAQlD,YAAY;IAU1B,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,UAAU;YAMJ,OAAO;YAWP,gBAAgB;YAsChB,eAAe;YAcf,gBAAgB;IAsH9B,OAAO,CAAC,gBAAgB;IA2BxB,OAAO,CAAC,mBAAmB;IAmC3B,OAAO,CAAC,YAAY;YAgBN,kBAAkB;YASlB,WAAW;YAOX,2BAA2B;YAY3B,uBAAuB;IAwGrC,OAAO,CAAC,WAAW;YAsCL,kBAAkB;IAoBhC,OAAO,CAAC,cAAc;YAYR,oBAAoB;YAkDpB,cAAc;IAmM5B,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,oBAAoB;IAI5B,OAAO,CAAC,oBAAoB;IAI5B,OAAO,CAAC,uBAAuB;IAI/B,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,oBAAoB;YAGd,gBAAgB;IA6D9B,OAAO,CAAC,aAAa;YAiBP,yBAAyB;YA4CzB,sBAAsB;YA4DtB,YAAY;YAsOZ,eAAe;IAuE7B,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,qBAAqB;YASf,qBAAqB;YA0BrB,2BAA2B;YAkE3B,QAAQ;IA4ChB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAqhG3E"}
+{"version":3,"file":"WorkOnTasksService.d.ts","sourceRoot":"","sources":["../../../src/services/execution/WorkOnTasksService.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,YAAY,EAAgD,MAAM,eAAe,CAAC;AAC3F,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE9D,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAuB,MAAM,WAAW,CAAC;AAEvF,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAiB,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC1G,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAsFrE,MAAM,WAAW,kBAAmB,SAAQ,oBAAoB;IAC9D,SAAS,EAAE,mBAAmB,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;CACjD;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA6wBD,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,eAAe,CAAC;AAC3F,MAAM,MAAM,sBAAsB,GAAG,aAAa,GAAG,aAAa,GAAG,wBAAwB,CAAC;AA2tC9F,qBAAa,kBAAkB;IA0B3B,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,IAAI;IA1Bd,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,YAAY,CAAmB;IACvC,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,aAAa,CAAC,CAAqB;YAC7B,eAAe;gBAmBnB,SAAS,EAAE,mBAAmB,EAC9B,IAAI,EAAE;QACZ,YAAY,EAAE,YAAY,CAAC;QAC3B,MAAM,EAAE,YAAY,CAAC;QACrB,UAAU,EAAE,UAAU,CAAC;QACvB,aAAa,EAAE,mBAAmB,CAAC;QACnC,gBAAgB,CAAC,EAAE,oBAAoB,CAAC;QACxC,YAAY,CAAC,EAAE,gBAAgB,CAAC;QAChC,IAAI,EAAE,gBAAgB,CAAC;QACvB,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,cAAc,EAAE,cAAc,CAAC;QAC/B,aAAa,CAAC,EAAE,kBAAkB,CAAC;KACpC;YASW,WAAW;YAsDX,WAAW;YAIX,mBAAmB;YAOnB,oBAAoB;YAUpB,UAAU;WAUX,MAAM,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA6B1E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB5B,qBAAqB,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;YAQlD,YAAY;IAU1B,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,UAAU;YAMJ,OAAO;YAWP,gBAAgB;YAsChB,eAAe;IAc7B,OAAO,CAAC,6BAA6B;YAuBvB,+BAA+B;YAwC/B,gBAAgB;IAwJ9B,OAAO,CAAC,gBAAgB;IA2BxB,OAAO,CAAC,mBAAmB;IAmC3B,OAAO,CAAC,YAAY;YAgBN,kBAAkB;YASlB,WAAW;YAOX,2BAA2B;YAY3B,uBAAuB;IAwGrC,OAAO,CAAC,WAAW;YAsCL,kBAAkB;IAoBhC,OAAO,CAAC,cAAc;YAYR,oBAAoB;YAkDpB,cAAc;IAmM5B,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,oBAAoB;IAI5B,OAAO,CAAC,oBAAoB;IAI5B,OAAO,CAAC,uBAAuB;IAI/B,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,oBAAoB;YAGd,gBAAgB;IA6D9B,OAAO,CAAC,aAAa;YAiBP,yBAAyB;YA4CzB,sBAAsB;YA4DtB,YAAY;YAsOZ,eAAe;IAuE7B,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,qBAAqB;YASf,qBAAqB;YA0BrB,2BAA2B;YAkE3B,QAAQ;IA4ChB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CA+jG3E"}

package/dist/services/execution/WorkOnTasksService.js

@@ -833,12 +833,31 @@ const splitFileBlocksByExistence = (fileBlocks, cwd) => {
     }
     return { existing, remaining };
 };
-const DEFAULT_MISSING_TESTS_POLICY = "block_job";
+const DEFAULT_MISSING_TESTS_POLICY = "continue_task";
+const DEFAULT_EXECUTION_CONTEXT_POLICY = "best_effort";
 const normalizeMissingTestsPolicy = (value) => {
     if (typeof value !== "string")
         return undefined;
     const normalized = value.trim().toLowerCase().replace(/-/g, "_");
-    if (normalized === "block_job" || normalized === "skip_task" || normalized === "fail_task") {
+    if (normalized === "block_job" ||
+        normalized === "skip_task" ||
+        normalized === "fail_task" ||
+        normalized === "continue_task" ||
+        normalized === "continue" ||
+        normalized === "allow" ||
+        normalized === "warn_task") {
+        if (normalized === "continue" || normalized === "allow" || normalized === "warn_task") {
+            return "continue_task";
+        }
+        return normalized;
+    }
+    return undefined;
+};
+const normalizeExecutionContextPolicy = (value) => {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "best_effort" || normalized === "require_any" || normalized === "require_sds_or_openapi") {
         return normalized;
     }
     return undefined;
@@ -1412,6 +1431,15 @@ const allowsTestsOnlyCompletion = (task, metadata, allowedFiles) => {
     return false;
 };
 const hasProductTouchedFiles = (touchedFiles) => touchedFiles.some((file) => !isTestLikePath(file) && !isDocumentationPath(file));
+const classifyExecutionContextKind = (doc) => {
+    const type = (doc.docType ?? "").toLowerCase();
+    const label = `${doc.path ?? ""} ${doc.title ?? ""}`.toLowerCase();
+    if (type.includes("sds") || /\bsds\b/.test(label))
+        return "sds";
+    if (type.includes("openapi") || type.includes("swagger") || /(openapi|swagger)/.test(label))
+        return "openapi";
+    return "fallback";
+};
 const buildDocContextQuery = (task, allowedFiles) => {
     const seeds = [
         task.key,
@@ -2260,6 +2288,61 @@ export class WorkOnTasksService {
         await this.logTask(taskRunId, `${phase}:${status}`, phase, payload);
         await this.checkpoint(jobId, `task:${taskKey}:${phase}:${status}`, payload);
     }
+    enforceExecutionContextPolicy(policy, context) {
+        if (policy === "best_effort")
+            return;
+        if (policy === "require_any") {
+            if (!context) {
+                throw new Error("Execution context is required but no planning documents were resolved (policy=require_any).");
+            }
+            return;
+        }
+        if (!context) {
+            throw new Error("Execution context requires SDS/OpenAPI sources, but none were resolved (policy=require_sds_or_openapi).");
+        }
+        if (context.kind !== "sds" && context.kind !== "openapi") {
+            throw new Error(`Execution context policy require_sds_or_openapi rejected source '${context.source}' (kind=${context.kind}).`);
+        }
+    }
+    async resolveExecutionPlanningContext(projectKey, warnings) {
+        if (!projectKey)
+            return undefined;
+        const pickFirst = async (filter) => {
+            const docs = await this.deps.docdex.search(filter);
+            return docs[0];
+        };
+        try {
+            const sdsDoc = await pickFirst({ projectKey, docType: "SDS", profile: "workspace-code" });
+            if (sdsDoc) {
+                return {
+                    source: sdsDoc.id ?? sdsDoc.path ?? sdsDoc.title ?? "sds",
+                    kind: classifyExecutionContextKind(sdsDoc),
+                };
+            }
+            const openapiDoc = await pickFirst({ projectKey, docType: "OPENAPI", profile: "workspace-code" });
+            if (openapiDoc) {
+                return {
+                    source: openapiDoc.id ?? openapiDoc.path ?? openapiDoc.title ?? "openapi",
+                    kind: classifyExecutionContextKind(openapiDoc),
+                };
+            }
+            const fallbackDoc = await pickFirst({
+                projectKey,
+                profile: "workspace-code",
+                query: "sds requirements architecture openapi swagger",
+            });
+            if (!fallbackDoc)
+                return undefined;
+            return {
+                source: fallbackDoc.id ?? fallbackDoc.path ?? fallbackDoc.title ?? "workspace-code",
+                kind: classifyExecutionContextKind(fallbackDoc),
+            };
+        }
+        catch (error) {
+            warnings.push(`Execution context preflight failed to query docdex: ${error.message}`);
+            return undefined;
+        }
+    }
     async gatherDocContext(task, projectKey, docLinks = [], allowedFiles = []) {
         const warnings = [];
         const parts = [];
@@ -2286,9 +2369,36 @@ export class WorkOnTasksService {
             }
         }
         try {
-            let docs = await this.deps.docdex.search({ projectKey, profile: "workspace-code", query: docQuery });
+            const docs = [];
+            const seen = new Set();
+            const appendDocs = async (filter) => {
+                const found = await this.deps.docdex.search(filter);
+                for (const doc of found) {
+                    const key = String(doc.id ?? doc.path ?? doc.title ?? "");
+                    if (!key)
+                        continue;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    docs.push(doc);
+                }
+            };
+            const sdsFilter = docQuery
+                ? { projectKey, docType: "SDS", profile: "workspace-code", query: docQuery }
+                : { projectKey, docType: "SDS", profile: "workspace-code" };
+            const openapiFilter = docQuery
+                ? { projectKey, docType: "OPENAPI", profile: "workspace-code", query: docQuery }
+                : { projectKey, docType: "OPENAPI", profile: "workspace-code" };
+            await appendDocs(sdsFilter);
+            await appendDocs(openapiFilter);
+            if (!docs.length) {
+                const genericFilter = docQuery
+                    ? { projectKey, profile: "workspace-code", query: docQuery }
+                    : { projectKey, profile: "workspace-code" };
+                await appendDocs(genericFilter);
+            }
             if (!docs.length && docQuery) {
-                docs = await this.deps.docdex.search({ projectKey, profile: "workspace-code" });
+                await appendDocs({ projectKey, profile: "workspace-code" });
             }
             const filteredDocs = docs.filter((doc) => !isDocContextExcluded(doc.path ?? doc.title ?? doc.id, false) &&
                 (includeTestDocs || !isTestLikePath(doc.path ?? doc.title ?? doc.id)));
@@ -3388,13 +3498,20 @@ export class WorkOnTasksService {
         const enforceCommentBacklog = isCommentBacklogEnforced();
         const commentBacklogMaxFails = resolveCommentBacklogMaxFails();
         const requestedMissingTestsPolicy = normalizeMissingTestsPolicy(request.missingTestsPolicy);
-        const missingTestsPolicy = requestedMissingTestsPolicy ?? (request.allowMissingTests ? "skip_task" : DEFAULT_MISSING_TESTS_POLICY);
+        const missingTestsPolicy = requestedMissingTestsPolicy ??
+            (request.allowMissingTests === true
+                ? "continue_task"
+                : request.allowMissingTests === false
+                    ? "block_job"
+                    : DEFAULT_MISSING_TESTS_POLICY);
+        const requestedExecutionContextPolicy = normalizeExecutionContextPolicy(request.executionContextPolicy);
+        const executionContextPolicy = requestedExecutionContextPolicy ?? DEFAULT_EXECUTION_CONTEXT_POLICY;
         const baseCodaliEnvOverrides = codaliRequired ? buildCodaliEnvOverrides() : {};
         const configuredBaseBranch = this.workspace.config?.branch;
         const requestedBaseBranch = request.baseBranch;
         const resolvedBaseBranch = (requestedBaseBranch ?? configuredBaseBranch ?? DEFAULT_BASE_BRANCH).trim();
         const normalizedBaseBranch = resolvedBaseBranch === "dev" ? DEFAULT_BASE_BRANCH : resolvedBaseBranch;
-        const baseBranch = DEFAULT_BASE_BRANCH;
+        const baseBranch = normalizedBaseBranch || DEFAULT_BASE_BRANCH;
         const configuredAutoMerge = this.workspace.config?.autoMerge;
         const configuredAutoPush = this.workspace.config?.autoPush;
         const autoMerge = request.autoMerge ?? configuredAutoMerge ?? true;
@@ -3405,6 +3522,9 @@ export class WorkOnTasksService {
         if (request.missingTestsPolicy && !requestedMissingTestsPolicy) {
             runnerWarnings.push(`Unknown missing-tests policy "${String(request.missingTestsPolicy)}"; using "${missingTestsPolicy}".`);
         }
+        if (request.executionContextPolicy && !requestedExecutionContextPolicy) {
+            runnerWarnings.push(`Unknown execution-context policy "${String(request.executionContextPolicy)}"; using "${executionContextPolicy}".`);
+        }
         const explicitTaskSelection = Boolean(request.taskKeys?.length);
         const ignoreDependencies = request.ignoreDependencies === true || explicitTaskSelection;
         const ignoreStatusFilter = explicitTaskSelection || request.ignoreStatusFilter === true;
@@ -3428,9 +3548,6 @@ export class WorkOnTasksService {
         if (codaliRequired && isPatchModeEnabled()) {
             runnerWarnings.push("work-on-tasks patch mode is ignored when codali is required.");
         }
-        if (normalizedBaseBranch && normalizedBaseBranch !== DEFAULT_BASE_BRANCH) {
-            baseBranchWarnings.push(`Base branch ${normalizedBaseBranch} ignored; work-on-tasks always uses ${DEFAULT_BASE_BRANCH}.`);
-        }
         const commandRun = await this.deps.jobService.startCommandRun(commandName, request.projectKey, {
             taskIds: request.taskKeys,
         });
@@ -3454,6 +3571,7 @@ export class WorkOnTasksService {
                 agentStream,
                 missingTestsPolicy,
                 allowMissingTests: request.allowMissingTests ?? false,
+                executionContextPolicy,
             },
         });
         const workspaceRoot = request.workspace.workspaceRoot;
@@ -3519,6 +3637,29 @@ export class WorkOnTasksService {
             return message === resolveAbortReason();
         };
         try {
+            const warnings = [...baseBranchWarnings, ...statusWarnings, ...runnerWarnings];
+            try {
+                const guidance = await ensureProjectGuidance(this.workspace.workspaceRoot, {
+                    mcodaDir: this.workspace.mcodaDir,
+                    projectKey: request.projectKey,
+                });
+                if (guidance.status !== "existing") {
+                    warnings.push(`project_guidance_${guidance.status}: ${guidance.path}`);
+                }
+                for (const warning of guidance.warnings ?? []) {
+                    warnings.push(`project_guidance_warning:${warning}`);
+                }
+            }
+            catch (error) {
+                warnings.push(`project_guidance_bootstrap_failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const executionContext = await this.resolveExecutionPlanningContext(request.projectKey, warnings);
+            this.enforceExecutionContextPolicy(executionContextPolicy, executionContext);
+            await this.checkpoint(job.id, "execution_context_preflight", {
+                policy: executionContextPolicy,
+                source: executionContext?.source ?? null,
+                kind: executionContext?.kind ?? null,
+            });
             await this.checkoutBaseBranch(baseBranch, { allowDirty: true });
             selection = await this.selectionService.selectTasks({
                 projectKey: request.projectKey,
@@ -3530,6 +3671,7 @@ export class WorkOnTasksService {
                 includeTypes,
                 excludeTypes,
                 ignoreDependencies,
+                missingContextPolicy: request.missingContextPolicy ?? "block",
                 limit: request.limit,
                 parallel: request.parallel,
             });
@@ -3544,20 +3686,9 @@ export class WorkOnTasksService {
                 totalItems: selection.ordered.length,
                 processedItems: 0,
             });
+            warnings.push(...selection.warnings);
             const results = [];
             const taskSummaries = new Map();
-            const warnings = [...baseBranchWarnings, ...statusWarnings, ...runnerWarnings, ...selection.warnings];
-            try {
-                const guidance = await ensureProjectGuidance(this.workspace.workspaceRoot, {
-                    mcodaDir: this.workspace.mcodaDir,
-                });
-                if (guidance.status !== "existing") {
-                    warnings.push(`project_guidance_${guidance.status}: ${guidance.path}`);
-                }
-            }
-            catch (error) {
-                warnings.push(`project_guidance_bootstrap_failed: ${error instanceof Error ? error.message : String(error)}`);
-            }
             if (missingTestsPolicy === "block_job") {
                 const missingHarnessTasks = await this.findMissingTestHarnessTasks(selection.ordered);
                 if (missingHarnessTasks.length > 0) {
@@ -4095,18 +4226,26 @@ export class WorkOnTasksService {
                                 await emitTaskEndOnce();
                                 throw new Error(`missing_test_harness: ${task.task.key} requires tests but no runnable test commands were found`);
                             }
-                            await this.logTask(taskRun.id, "Tests required but no runnable test commands were found; failing task.", "tests", { testRequirements, missingTestsPolicy });
-                            await this.stateService.markFailed(task.task, "tests_not_configured", statusContext);
-                            await this.deps.workspaceRepo.updateTaskRun(taskRun.id, {
-                                status: "failed",
-                                finishedAt: new Date().toISOString(),
-                            });
-                            setFailureReason("tests_not_configured");
-                            results.push({ taskKey: task.task.key, status: "failed", notes: "tests_not_configured" });
-                            taskStatus = "failed";
-                            await this.deps.jobService.updateJobStatus(job.id, "running", { processedItems: index + 1 });
-                            await emitTaskEndOnce();
-                            continue taskLoop;
+                            if (missingTestsPolicy === "continue_task") {
+                                const warning = `Task ${task.task.key}: tests required but no runnable test harness was found; proceeding without automated tests.` +
+                                    " Add metadata.tests/testCommands or tests/all.js.";
+                                warnings.push(warning);
+                                await this.logTask(taskRun.id, "Tests required but no runnable test commands were found; continuing without automated tests due to missing-tests policy.", "tests", { testRequirements, missingTestsPolicy });
+                            }
+                            else {
+                                await this.logTask(taskRun.id, "Tests required but no runnable test commands were found; failing task.", "tests", { testRequirements, missingTestsPolicy });
+                                await this.stateService.markFailed(task.task, "tests_not_configured", statusContext);
+                                await this.deps.workspaceRepo.updateTaskRun(taskRun.id, {
+                                    status: "failed",
+                                    finishedAt: new Date().toISOString(),
+                                });
+                                setFailureReason("tests_not_configured");
+                                results.push({ taskKey: task.task.key, status: "failed", notes: "tests_not_configured" });
+                                taskStatus = "failed";
+                                await this.deps.jobService.updateJobStatus(job.id, "running", { processedItems: index + 1 });
+                                await emitTaskEndOnce();
+                                continue taskLoop;
+                            }
                         }
                         const shouldRunTests = !request.dryRun && (testsRequired ? hasRunnableTests : testCommands.length > 0);
                         let mergeConflicts = [];
@@ -4463,9 +4602,14 @@ export class WorkOnTasksService {
                             continue taskLoop;
                         }
                         await endPhase("context", { docWarnings, docSummary: Boolean(docSummary) });
-                        const projectGuidance = await loadProjectGuidance(this.workspace.workspaceRoot, this.workspace.mcodaDir);
+                        const projectGuidance = await loadProjectGuidance(this.workspace.workspaceRoot, this.workspace.mcodaDir, {
+                            projectKey: request.projectKey,
+                        });
                         if (projectGuidance) {
                             await this.logTask(taskRun.id, `Loaded project guidance from ${projectGuidance.source}`, "project_guidance");
+                            for (const warning of projectGuidance.warnings ?? []) {
+                                await this.logTask(taskRun.id, `Project guidance warning: ${warning}`, "project_guidance");
+                            }
                         }
                         await startPhase("prompt", { docSummary: Boolean(docSummary), agent: agent.id });
                         commentContext = await this.loadCommentContext(task.task.id);

package/dist/services/openapi/OpenApiService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OpenApiService.d.ts","sourceRoot":"","sources":["../../../src/services/openapi/OpenApiService.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"OpenApiService.d.ts","sourceRoot":"","sources":["../../../src/services/openapi/OpenApiService.ts"],"names":[],"mappings":"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"}

package/dist/services/openapi/OpenApiService.js

@@ -139,6 +139,7 @@ export const findAdminSurfaceMentions = (raw) => {
 };
 const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "options", "head", "trace"];
 const OPERATION_ID_PATTERN = /^[A-Za-z0-9_.-]+$/;
+const TASK_HINT_STAGE_VALUES = new Set(["foundation", "backend", "frontend", "other"]);
 const isPlainObject = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
 const operationUsesJsonSchema = (operation) => {
     const contentBlocks = [];
@@ -230,6 +231,43 @@ export const validateOpenApiSchema = (doc) => {
                 else {
                     operationIds.set(operationId, `${method.toUpperCase()} ${pathKey}`);
                 }
+                const taskHints = operation["x-mcoda-task-hints"];
+                if (taskHints !== undefined) {
+                    if (!isPlainObject(taskHints)) {
+                        errors.push(`Invalid x-mcoda-task-hints for ${method.toUpperCase()} ${pathKey}: must be an object.`);
+                    }
+                    else {
+                        const stage = taskHints.stage;
+                        if (stage !== undefined && (typeof stage !== "string" || !TASK_HINT_STAGE_VALUES.has(stage))) {
+                            errors.push(`Invalid x-mcoda-task-hints.stage for ${method.toUpperCase()} ${pathKey}: expected one of foundation|backend|frontend|other.`);
+                        }
+                        const complexity = taskHints.complexity;
+                        if (complexity !== undefined &&
+                            (typeof complexity !== "number" || !Number.isFinite(complexity) || complexity < 0)) {
+                            errors.push(`Invalid x-mcoda-task-hints.complexity for ${method.toUpperCase()} ${pathKey}: expected non-negative number.`);
+                        }
+                        const dependsOn = taskHints.depends_on_operations;
+                        if (dependsOn !== undefined &&
+                            (!Array.isArray(dependsOn) || dependsOn.some((entry) => typeof entry !== "string"))) {
+                            errors.push(`Invalid x-mcoda-task-hints.depends_on_operations for ${method.toUpperCase()} ${pathKey}: expected string array.`);
+                        }
+                        const testRequirements = taskHints.test_requirements;
+                        if (testRequirements !== undefined) {
+                            if (!isPlainObject(testRequirements)) {
+                                errors.push(`Invalid x-mcoda-task-hints.test_requirements for ${method.toUpperCase()} ${pathKey}: expected object.`);
+                            }
+                            else {
+                                for (const key of ["unit", "component", "integration", "api"]) {
+                                    const value = testRequirements[key];
+                                    if (value !== undefined &&
+                                        (!Array.isArray(value) || value.some((entry) => typeof entry !== "string"))) {
+                                        errors.push(`Invalid x-mcoda-task-hints.test_requirements.${key} for ${method.toUpperCase()} ${pathKey}: expected string array.`);
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
             }
         }
     }
@@ -400,7 +438,7 @@ class OpenapiContextAssembler {
                 sdsDocs = [local];
             }
             else {
-                warnings.push("No SDS found in docdex or local workspace.");
+                throw new Error("openapi-from-docs requires an SDS document. Generate SDS first (mcoda docs sds generate) or add docs/sds/sds.md.");
             }
         }
         else {
@@ -594,8 +632,8 @@ export class OpenApiService {
             : "";
         return [
             "You are generating an OpenAPI 3.1 YAML for THIS workspace/project using only the provided PDR/SDS/RFP context.",
-            "Derive resources, schemas, and HTTP endpoints directly from the product requirements (e.g., todos CRUD, filters, search, bulk actions).",
-            "If the documents describe a frontend-only/localStorage app, design a minimal REST API that could back those features (e.g., /todos, /todos/{id}, bulk operations, search/filter params) instead of returning an empty spec.",
+            "Derive resources, schemas, and HTTP endpoints directly from SDS-grounded product requirements only.",
+            "Do not invent endpoints, workflows, or schemas that are not traceable to SDS/PDR/RFP context.",
             "Prefer concise tags derived from domain resources (e.g., Todos). Avoid generic mcoda/system endpoints unless explicitly described in the context.",
             `Use OpenAPI version ${OPENAPI_VERSION}, set info.title to the project name from context (fallback \"mcoda API\"), and info.version ${cliVersion}.`,
             adminNote,
@@ -605,8 +643,9 @@ export class OpenApiService {
             "- Derive endpoints, schemas, and tags from the provided PDR/SDS/RFP context only.",
             "- Do NOT emit generic mcoda CLI/system endpoints unless explicitly described.",
             "- Prefer concise schemas and operations that map to described APIs; omit unused boilerplate.",
+            "- For each operation, include x-mcoda-task-hints with fields: service (string), capability (string), stage (foundation|backend|frontend|other), complexity (number), depends_on_operations (string[]), test_requirements ({ unit: string[], component: string[], integration: string[], api: string[] }).",
             "Context:",
-            contextBlocks || "No context available; if none, produce a minimal empty spec with paths: {}.",
+            contextBlocks || "SDS context is required and should always be present.",
         ].join("\n\n");
     }
     async ensureOpenapiDir() {

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

@@ -66,6 +66,11 @@ export declare class CreateTasksService {
     private resolveAgent;
     private ensureRatingService;
     private prepareDocs;
+    private normalizeDocInputForSet;
+    private docIdentity;
+    private mergeDocs;
+    private sortDocsForPlanning;
+    private collectDocsFromInputs;
     private resolveDefaultDocInputs;
     private walkDocCandidates;
     private scoreDocCandidate;
@@ -78,8 +83,10 @@ export declare class CreateTasksService {
     private extractServiceMentionsFromText;
     private resolveServiceMentionFromPhrase;
     private collectDependencyStatements;
+    private extractStartupWaveHints;
     private sortServicesByDependency;
     private buildServiceDependencyGraph;
+    private buildProjectConstructionMethod;
     private orderStoryTasksByDependencies;
     private applyServiceDependencySequencing;
     private shouldInjectStructureBootstrap;
@@ -88,13 +95,18 @@ export declare class CreateTasksService {
     private validatePlanLocalIdentifiers;
     private buildQaPreflight;
     private buildQaOverrides;
+    private isOpenApiDoc;
+    private buildOpenApiHintSummary;
     private buildDocContext;
     private buildPrompt;
     private fallbackPlan;
+    private materializePlanFromSeed;
     private invokeAgentWithRetry;
     private parseEpics;
     private generateStoriesForEpic;
     private generateTasksForStory;
+    private buildFallbackStoryForEpic;
+    private buildFallbackTasksForStory;
     private generatePlanFromAgent;
     private writePlanArtifacts;
     private persistPlanToDb;

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":"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"}
+{"version":3,"file":"CreateTasksService.d.ts","sourceRoot":"","sources":["../../../src/services/planning/CreateTasksService.ts"],"names":[],"mappings":"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"}