@mcoda/core 0.1.8 → 0.1.11

package/dist/services/planning/CreateTasksService.js

@@ -6,17 +6,134 @@ import { setTimeout as delay } from "node:timers/promises";
 import { DocdexClient } from "@mcoda/integrations";
 import { JobService } from "../jobs/JobService.js";
 import { RoutingService } from "../agents/RoutingService.js";
+import { AgentRatingService } from "../agents/AgentRatingService.js";
+import { classifyTask } from "../backlog/TaskOrderingHeuristics.js";
+import { TaskOrderingService } from "../backlog/TaskOrderingService.js";
 import { createEpicKeyGenerator, createStoryKeyGenerator, createTaskKeyGenerator, } from "./KeyHelpers.js";
 const formatBullets = (items, fallback) => {
     if (!items || items.length === 0)
         return `- ${fallback}`;
     return items.map((item) => `- ${item}`).join("\n");
 };
+const normalizeStringArray = (value) => {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter(Boolean);
+};
+const normalizeEntrypoints = (value) => {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((entry) => {
+        if (!entry || typeof entry !== "object")
+            return null;
+        const record = entry;
+        const kind = record.kind;
+        if (kind !== "web" && kind !== "api" && kind !== "cli")
+            return null;
+        return {
+            kind,
+            base_url: typeof record.base_url === "string" ? record.base_url : undefined,
+            command: typeof record.command === "string" ? record.command : undefined,
+        };
+    })
+        .filter((entry) => Boolean(entry));
+};
+const normalizeQaReadiness = (value) => {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const record = value;
+    const qa = {
+        profiles_expected: normalizeStringArray(record.profiles_expected),
+        requires: normalizeStringArray(record.requires),
+        entrypoints: normalizeEntrypoints(record.entrypoints),
+        data_setup: normalizeStringArray(record.data_setup),
+        blockers: normalizeStringArray(record.blockers),
+        notes: typeof record.notes === "string" ? record.notes : undefined,
+    };
+    const hasValues = (qa.profiles_expected?.length ?? 0) > 0 ||
+        (qa.requires?.length ?? 0) > 0 ||
+        (qa.entrypoints?.length ?? 0) > 0 ||
+        (qa.data_setup?.length ?? 0) > 0 ||
+        (qa.blockers?.length ?? 0) > 0 ||
+        (qa.notes?.length ?? 0) > 0;
+    return hasValues ? qa : undefined;
+};
+const uniqueStrings = (items) => Array.from(new Set(items));
+const uniqueEntrypoints = (items) => {
+    const seen = new Set();
+    const result = [];
+    for (const entry of items) {
+        const key = `${entry.kind}|${entry.base_url ?? ""}|${entry.command ?? ""}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(entry);
+    }
+    return result;
+};
+const buildQaReadiness = (params) => {
+    const derivedProfiles = ["cli"];
+    if (params.classification.stage === "frontend")
+        derivedProfiles.push("chromium");
+    if (params.classification.stage === "backend")
+        derivedProfiles.push("api");
+    const profilesExpected = uniqueStrings([
+        ...derivedProfiles,
+        ...(params.overrides?.profiles_expected ?? []),
+        ...(params.planQa?.profiles_expected ?? []),
+    ]);
+    const entrypoints = uniqueEntrypoints([
+        ...(params.overrides?.entrypoints ?? []),
+        ...(params.planQa?.entrypoints ?? []),
+        ...(params.classification.stage === "frontend" ? params.preflight?.entrypoints ?? [] : []),
+    ]);
+    const blockers = uniqueStrings([
+        ...(params.overrides?.blockers ?? []),
+        ...(params.planQa?.blockers ?? []),
+        ...(params.preflight?.blockers ?? []),
+    ]);
+    if (params.classification.stage === "frontend" && entrypoints.length === 0) {
+        blockers.push("Missing UI entrypoint (dev/start script).");
+    }
+    return {
+        profiles_expected: profilesExpected,
+        requires: uniqueStrings([...(params.overrides?.requires ?? []), ...(params.planQa?.requires ?? [])]),
+        entrypoints: entrypoints.length ? entrypoints : undefined,
+        data_setup: uniqueStrings([...(params.overrides?.data_setup ?? []), ...(params.planQa?.data_setup ?? [])]),
+        blockers: blockers.length ? blockers : undefined,
+        notes: params.overrides?.notes ?? params.planQa?.notes,
+    };
+};
+const formatTestList = (items) => {
+    if (!items || items.length === 0)
+        return "Not applicable";
+    return items.join("; ");
+};
 const ensureNonEmpty = (value, fallback) => value && value.trim().length > 0 ? value.trim() : fallback;
+const extractScriptPort = (script) => {
+    const matches = [script.match(/(?:--port|-p)\s*(\d{2,5})/), script.match(/PORT\s*=\s*(\d{2,5})/)];
+    for (const match of matches) {
+        if (!match)
+            continue;
+        const parsed = Number.parseInt(match[1] ?? "", 10);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+    }
+    return undefined;
+};
 const estimateTokens = (text) => Math.max(1, Math.ceil(text.length / 4));
 const DOC_CONTEXT_BUDGET = 8000;
+const DOCDEX_HANDLE = /^docdex:/i;
+const VALID_AREAS = new Set(["web", "adm", "bck", "ops", "infra", "mobile"]);
+const VALID_TASK_TYPES = new Set(["feature", "bug", "chore", "spike"]);
 const inferDocType = (filePath) => {
     const name = path.basename(filePath).toLowerCase();
+    if (name.includes("openapi") || name.includes("swagger"))
+        return "OPENAPI";
     if (name.includes("sds"))
         return "SDS";
     if (name.includes("pdr"))
@@ -25,6 +142,48 @@ const inferDocType = (filePath) => {
         return "RFP";
     return "DOC";
 };
+const normalizeArea = (value) => {
+    if (typeof value !== "string")
+        return undefined;
+    const tokens = value
+        .toLowerCase()
+        .split(/[^a-z]+/)
+        .map((token) => token.trim())
+        .filter(Boolean);
+    for (const token of tokens) {
+        if (VALID_AREAS.has(token))
+            return token;
+    }
+    return undefined;
+};
+const normalizeTaskType = (value) => {
+    if (typeof value !== "string")
+        return undefined;
+    const tokens = value
+        .toLowerCase()
+        .split(/[^a-z]+/)
+        .map((token) => token.trim())
+        .filter(Boolean);
+    for (const token of tokens) {
+        if (VALID_TASK_TYPES.has(token))
+            return token;
+    }
+    return undefined;
+};
+const normalizeRelatedDocs = (value) => {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((entry) => {
+        if (typeof entry === "string")
+            return entry;
+        if (entry && typeof entry === "object" && "handle" in entry && typeof entry.handle === "string") {
+            return entry.handle;
+        }
+        return undefined;
+    })
+        .filter((entry) => Boolean(entry && DOCDEX_HANDLE.test(entry)));
+};
 const describeDoc = (doc, idx) => {
     const title = doc.title ?? doc.path ?? doc.id ?? `doc-${idx + 1}`;
     const source = doc.path ?? doc.id ?? "docdex";
@@ -32,19 +191,80 @@ const describeDoc = (doc, idx) => {
     return `- [${doc.docType}] ${title} (handle: docdex:${doc.id ?? `doc-${idx + 1}`}, source: ${source})${head ? `\n  Excerpt: ${head}` : ""}`;
 };
 const extractJson = (raw) => {
-    const fenced = raw.match(/```json([\s\S]*?)```/);
-    const candidate = fenced ? fenced[1] : raw;
-    const start = candidate.indexOf("{");
-    const end = candidate.lastIndexOf("}");
-    if (start === -1 || end === -1 || end <= start)
-        return undefined;
-    const body = candidate.slice(start, end + 1);
+    const fencedMatches = [...raw.matchAll(/```json([\s\S]*?)```/g)].map((match) => match[1]);
+    const stripped = raw.replace(/<think>[\s\S]*?<\/think>/g, "");
+    const candidates = [...fencedMatches, stripped, raw].filter((candidate) => candidate.trim().length > 0);
+    for (const candidate of candidates) {
+        const parsed = tryParseJson(candidate);
+        if (parsed && isPlanShape(parsed))
+            return parsed;
+    }
+    return undefined;
+};
+const isPlanShape = (value) => {
+    if (!value || typeof value !== "object")
+        return false;
+    return Array.isArray(value.epics) || Array.isArray(value.stories) || Array.isArray(value.tasks);
+};
+const tryParseJson = (value) => {
     try {
-        return JSON.parse(body);
+        return JSON.parse(value);
     }
     catch {
-        return undefined;
+        // continue
     }
+    const objects = extractJsonObjects(value).reverse();
+    for (const obj of objects) {
+        try {
+            return JSON.parse(obj);
+        }
+        catch {
+            // continue
+        }
+    }
+    return undefined;
+};
+const extractJsonObjects = (value) => {
+    const results = [];
+    let depth = 0;
+    let start = -1;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < value.length; i += 1) {
+        const ch = value[i];
+        if (inString) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (ch === "\\") {
+                escaped = true;
+                continue;
+            }
+            if (ch === "\"")
+                inString = false;
+            continue;
+        }
+        if (ch === "\"") {
+            inString = true;
+            continue;
+        }
+        if (ch === "{") {
+            if (depth === 0)
+                start = i;
+            depth += 1;
+        }
+        else if (ch === "}") {
+            if (depth === 0)
+                continue;
+            depth -= 1;
+            if (depth === 0 && start >= 0) {
+                results.push(value.slice(start, i + 1));
+                start = -1;
+            }
+        }
+    }
+    return results;
 };
 const buildEpicDescription = (epicKey, title, description, acceptance, relatedDocs) => {
     return [
@@ -100,7 +320,17 @@ const buildStoryDescription = (storyKey, title, userStory, description, acceptan
         formatBullets(relatedDocs, "Docdex handles, OpenAPI endpoints, code modules."),
     ].join("\n");
 };
-const buildTaskDescription = (taskKey, title, description, storyKey, epicKey, relatedDocs, dependencies) => {
+const buildTaskDescription = (taskKey, title, description, storyKey, epicKey, relatedDocs, dependencies, tests, qa) => {
+    const formatEntrypoints = (entrypoints) => {
+        if (!entrypoints || entrypoints.length === 0)
+            return "- Not specified";
+        return entrypoints
+            .map((entry) => {
+            const target = entry.base_url ?? entry.command ?? "TBD";
+            return `- ${entry.kind}: ${target}`;
+        })
+            .join("\n");
+    };
     return [
         `* **Task Key**: ${taskKey}`,
         "* **Objective**",
@@ -117,7 +347,18 @@ const buildTaskDescription = (taskKey, title, description, storyKey, epicKey, re
         "* **Definition of Done**",
         "- Tests passing, docs updated, review/QA complete.",
         "* **Testing & QA**",
-        "- Unit/integration coverage for changed areas.",
+        `- Unit tests: ${formatTestList(tests.unitTests)}`,
+        `- Component tests: ${formatTestList(tests.componentTests)}`,
+        `- Integration tests: ${formatTestList(tests.integrationTests)}`,
+        `- API tests: ${formatTestList(tests.apiTests)}`,
+        "* **QA Readiness**",
+        `- Profiles: ${qa?.profiles_expected?.length ? qa.profiles_expected.join(", ") : "TBD"}`,
+        `- Requires: ${qa?.requires?.length ? qa.requires.join("; ") : "None specified"}`,
+        `- Data setup: ${qa?.data_setup?.length ? qa.data_setup.join("; ") : "None specified"}`,
+        "* **QA Entry Points**",
+        formatEntrypoints(qa?.entrypoints),
+        "* **QA Blockers**",
+        formatBullets(qa?.blockers, "None known."),
         "* **Dependencies**",
         formatBullets(dependencies, "Enumerate prerequisite tasks by key."),
         "* **Risks & Gotchas**",
@@ -181,7 +422,18 @@ const TASK_SCHEMA_SNIPPET = `{
       "estimatedStoryPoints": 3,
       "priorityHint": 50,
       "dependsOnKeys": ["t0"],
-      "relatedDocs": ["docdex:..."]
+      "relatedDocs": ["docdex:..."],
+      "unitTests": ["unit test description"],
+      "componentTests": ["component test description"],
+      "integrationTests": ["integration test description"],
+      "apiTests": ["api test description"],
+      "qa": {
+        "profiles_expected": ["cli", "api", "chromium"],
+        "requires": ["dev server", "seed data"],
+        "entrypoints": [{ "kind": "web", "base_url": "http://localhost:<PORT>", "command": "npm run dev" }],
+        "data_setup": ["seed sample data"],
+        "notes": "optional QA notes"
+      }
     }
   ]
 }`;
@@ -194,14 +446,18 @@ export class CreateTasksService {
         this.repo = deps.repo;
         this.workspaceRepo = deps.workspaceRepo;
         this.routingService = deps.routingService;
+        this.ratingService = deps.ratingService;
+        this.taskOrderingFactory = deps.taskOrderingFactory ?? TaskOrderingService.create;
     }
     static async create(workspace) {
         const repo = await GlobalRepository.create();
         const agentService = new AgentService(repo);
         const routingService = await RoutingService.create();
+        const docdexRepoId = workspace.config?.docdexRepoId ?? process.env.MCODA_DOCDEX_REPO_ID ?? process.env.DOCDEX_REPO_ID;
         const docdex = new DocdexClient({
             workspaceRoot: workspace.workspaceRoot,
             baseUrl: workspace.config?.docdexUrl ?? process.env.MCODA_DOCDEX_URL,
+            repoId: docdexRepoId,
         });
         const jobService = new JobService(workspace);
         const workspaceRepo = await WorkspaceRepository.create(workspace.workspaceRoot);
@@ -232,6 +488,17 @@ export class CreateTasksService {
         const docdex = this.docdex;
         await swallow(docdex?.close?.bind(docdex));
     }
+    async seedPriorities(projectKey) {
+        const ordering = await this.taskOrderingFactory(this.workspace, { recordTelemetry: false });
+        try {
+            await ordering.orderTasks({
+                projectKey,
+            });
+        }
+        finally {
+            await ordering.close();
+        }
+    }
     async resolveAgent(agentName) {
         const resolved = await this.routingService.resolveAgentForCommand({
             workspace: this.workspace,
@@ -240,9 +507,23 @@ export class CreateTasksService {
         });
         return resolved.agent;
     }
+    ensureRatingService() {
+        if (!this.ratingService) {
+            this.ratingService = new AgentRatingService(this.workspace, {
+                workspaceRepo: this.workspaceRepo,
+                globalRepo: this.repo,
+                agentService: this.agentService,
+                routingService: this.routingService,
+            });
+        }
+        return this.ratingService;
+    }
     async prepareDocs(inputs) {
+        const resolvedInputs = inputs.length > 0 ? inputs : await this.resolveDefaultDocInputs();
+        if (resolvedInputs.length === 0)
+            return [];
         const documents = [];
-        for (const input of inputs) {
+        for (const input of resolvedInputs) {
             if (input.startsWith("docdex:")) {
                 const docId = input.replace(/^docdex:/, "");
                 try {
@@ -263,6 +544,11 @@ export class CreateTasksService {
                 throw new Error(`Failed to read input ${input}: ${error.message}`);
             }
             for (const filePath of paths) {
+                const baseName = path.basename(filePath);
+                if (baseName.endsWith(".meta.json") || baseName.endsWith("-first-draft.md"))
+                    continue;
+                if (!/\.(md|markdown|ya?ml|json)$/i.test(baseName))
+                    continue;
                 const docType = inferDocType(filePath);
                 try {
                     const doc = await this.docdex.ensureRegisteredFromFile(filePath, docType, {
@@ -277,6 +563,128 @@ export class CreateTasksService {
         }
         return documents;
     }
+    async resolveDefaultDocInputs() {
+        const candidates = [
+            path.join(this.workspace.mcodaDir, "docs"),
+            path.join(this.workspace.workspaceRoot, "docs"),
+            path.join(this.workspace.workspaceRoot, "openapi"),
+            path.join(this.workspace.workspaceRoot, "openapi.yaml"),
+            path.join(this.workspace.workspaceRoot, "openapi.yml"),
+            path.join(this.workspace.workspaceRoot, "openapi.json"),
+        ];
+        const existing = [];
+        for (const candidate of candidates) {
+            try {
+                const stat = await fs.stat(candidate);
+                if (stat.isFile() || stat.isDirectory())
+                    existing.push(candidate);
+            }
+            catch {
+                // Ignore missing candidates; fall back to empty inputs.
+            }
+        }
+        return existing;
+    }
+    async buildQaPreflight() {
+        const preflight = {
+            scripts: {},
+            entrypoints: [],
+            blockers: [],
+        };
+        const packagePath = path.join(this.workspace.workspaceRoot, "package.json");
+        let pkg = null;
+        try {
+            const raw = await fs.readFile(packagePath, "utf8");
+            pkg = JSON.parse(raw);
+        }
+        catch {
+            return preflight;
+        }
+        const scripts = pkg?.scripts;
+        if (scripts && typeof scripts === "object") {
+            for (const [name, value] of Object.entries(scripts)) {
+                if (typeof value === "string") {
+                    preflight.scripts[name] = value;
+                }
+            }
+        }
+        const dependencies = {
+            ...(pkg?.dependencies && typeof pkg.dependencies === "object" ? pkg.dependencies : {}),
+            ...(pkg?.devDependencies && typeof pkg.devDependencies === "object"
+                ? pkg.devDependencies
+                : {}),
+        };
+        const hasDev = typeof preflight.scripts.dev === "string";
+        const hasStart = typeof preflight.scripts.start === "string";
+        const devPort = hasDev ? extractScriptPort(preflight.scripts.dev) : undefined;
+        const startPort = hasStart ? extractScriptPort(preflight.scripts.start) : undefined;
+        if (hasDev) {
+            preflight.entrypoints.push({
+                kind: "web",
+                base_url: devPort ? `http://localhost:${devPort}` : undefined,
+                command: "npm run dev",
+            });
+        }
+        else if (hasStart) {
+            preflight.entrypoints.push({
+                kind: "web",
+                base_url: startPort ? `http://localhost:${startPort}` : undefined,
+                command: "npm start",
+            });
+        }
+        const testDirs = [
+            path.join(this.workspace.workspaceRoot, "tests"),
+            path.join(this.workspace.workspaceRoot, "__tests__"),
+        ];
+        const testFiles = [];
+        for (const dir of testDirs) {
+            try {
+                const stat = await fs.stat(dir);
+                if (!stat.isDirectory())
+                    continue;
+                testFiles.push(...(await collectFilesRecursively(dir)));
+            }
+            catch {
+                // ignore missing test dirs
+            }
+        }
+        const testCandidates = testFiles.filter((file) => /\b(test|spec)\b/i.test(path.basename(file)));
+        const hasSupertest = typeof dependencies.supertest === "string";
+        if (!hasSupertest && testCandidates.length > 0) {
+            for (const file of testCandidates) {
+                try {
+                    const content = await fs.readFile(file, "utf8");
+                    if (content.includes("supertest")) {
+                        preflight.blockers.push("Missing devDependency: supertest (required by test files).");
+                        break;
+                    }
+                }
+                catch {
+                    // ignore read errors
+                }
+            }
+        }
+        return preflight;
+    }
+    buildQaOverrides(options) {
+        const profiles = options.qaProfiles?.filter(Boolean);
+        const requires = options.qaRequires?.filter(Boolean);
+        const entrypoints = [];
+        if (options.qaEntryUrl || options.qaStartCommand) {
+            entrypoints.push({
+                kind: "web",
+                base_url: options.qaEntryUrl,
+                command: options.qaStartCommand,
+            });
+        }
+        if (!profiles?.length && !requires?.length && entrypoints.length === 0)
+            return undefined;
+        return {
+            profiles_expected: profiles,
+            requires,
+            entrypoints: entrypoints.length ? entrypoints : undefined,
+        };
+    }
     buildDocContext(docs) {
         const warnings = [];
         const blocks = [];
@@ -365,6 +773,10 @@ export class CreateTasksService {
                                     estimatedStoryPoints: 1,
                                     priorityHint: 10,
                                     relatedDocs: docRefs,
+                                    unitTests: [],
+                                    componentTests: [],
+                                    integrationTests: [],
+                                    apiTests: [],
                                 },
                                 {
                                     localId: "task-2",
@@ -375,6 +787,10 @@ export class CreateTasksService {
                                     priorityHint: 20,
                                     dependsOnKeys: ["task-1"],
                                     relatedDocs: docRefs,
+                                    unitTests: [],
+                                    componentTests: [],
+                                    integrationTests: [],
+                                    apiTests: [],
                                 },
                             ],
                         },
@@ -412,6 +828,7 @@ export class CreateTasksService {
         }
         let parsed = extractJson(output);
         if (!parsed) {
+            const attempt = 2;
             const fixPrompt = [
                 "Rewrite the previous response into valid JSON matching the expected schema.",
                 `Schema hint:\n${action === "epics" ? EPIC_SCHEMA_SNIPPET : action === "stories" ? STORY_SCHEMA_SNIPPET : TASK_SCHEMA_SNIPPET}`,
@@ -422,6 +839,32 @@ export class CreateTasksService {
                 const fix = await this.agentService.invoke(agent.id, { input: fixPrompt });
                 output = fix.output ?? "";
                 parsed = extractJson(output);
+                if (parsed) {
+                    const promptTokens = estimateTokens(prompt);
+                    const completionTokens = estimateTokens(output);
+                    const durationSeconds = (Date.now() - startedAt) / 1000;
+                    await this.jobService.recordTokenUsage({
+                        timestamp: new Date().toISOString(),
+                        workspaceId: this.workspace.workspaceId,
+                        jobId,
+                        commandRunId,
+                        agentId: agent.id,
+                        modelName: agent.defaultModel,
+                        promptTokens,
+                        completionTokens,
+                        tokensPrompt: promptTokens,
+                        tokensCompletion: completionTokens,
+                        tokensTotal: promptTokens + completionTokens,
+                        durationSeconds,
+                        metadata: {
+                            action: `create_tasks_${action}`,
+                            phase: `create_tasks_${action}`,
+                            attempt,
+                            ...(metadata ?? {}),
+                        },
+                    });
+                    return { output, promptTokens, completionTokens };
+                }
             }
             catch (error) {
                 throw new Error(`Agent retry failed (${action}): ${error.message}`);
@@ -446,7 +889,12 @@ export class CreateTasksService {
             tokensCompletion: completionTokens,
             tokensTotal: promptTokens + completionTokens,
             durationSeconds,
-            metadata: { action: `create_tasks_${action}`, ...(metadata ?? {}) },
+            metadata: {
+                action: `create_tasks_${action}`,
+                phase: `create_tasks_${action}`,
+                attempt: 1,
+                ...(metadata ?? {}),
+            },
         });
         return { output, promptTokens, completionTokens };
     }
@@ -458,11 +906,11 @@ export class CreateTasksService {
         return parsed.epics
             .map((epic, idx) => ({
             localId: epic.localId ?? `e${idx + 1}`,
-            area: epic.area,
+            area: normalizeArea(epic.area),
             title: epic.title ?? "Epic",
             description: epic.description,
             acceptanceCriteria: Array.isArray(epic.acceptanceCriteria) ? epic.acceptanceCriteria : [],
-            relatedDocs: Array.isArray(epic.relatedDocs) ? epic.relatedDocs : [],
+            relatedDocs: normalizeRelatedDocs(epic.relatedDocs),
             priorityHint: typeof epic.priorityHint === "number" ? epic.priorityHint : undefined,
             stories: [],
         }))
@@ -496,13 +944,21 @@ export class CreateTasksService {
             userStory: story.userStory ?? story.description,
             description: story.description,
             acceptanceCriteria: Array.isArray(story.acceptanceCriteria) ? story.acceptanceCriteria : [],
-            relatedDocs: Array.isArray(story.relatedDocs) ? story.relatedDocs : [],
+            relatedDocs: normalizeRelatedDocs(story.relatedDocs),
             priorityHint: typeof story.priorityHint === "number" ? story.priorityHint : undefined,
             tasks: [],
         }))
             .filter((s) => s.title);
     }
     async generateTasksForStory(agent, epic, story, docSummary, stream, jobId, commandRunId) {
+        const parseTestList = (value) => {
+            if (!Array.isArray(value))
+                return [];
+            return value
+                .filter((item) => typeof item === "string")
+                .map((item) => item.trim())
+                .filter(Boolean);
+        };
         const prompt = [
             `Generate tasks for story "${story.title}" (Epic: ${epic.title}).`,
             "Use the Task template: Objective; Context; Inputs; Implementation Plan; DoD; Testing & QA; Dependencies; Risks; References.",
@@ -510,6 +966,11 @@ export class CreateTasksService {
             TASK_SCHEMA_SNIPPET,
             "Rules:",
             "- Each task must include localId, title, description, type, estimatedStoryPoints, priorityHint.",
+            "- Include test arrays: unitTests, componentTests, integrationTests, apiTests. Use [] when not applicable.",
+            "- Only include tests that are relevant to the task's scope.",
+            "- If the task involves code or configuration changes, include at least one relevant test; do not leave all test arrays empty unless it's purely documentation or research.",
+            "- 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.",
             "- Use docdex handles when citing docs.",
             `Story context (key=${story.key ?? story.localId ?? "TBD"}):`,
@@ -526,16 +987,35 @@ export class CreateTasksService {
             throw new Error(`Agent did not return tasks for story ${story.title}`);
         }
         return parsed.tasks
-            .map((task, idx) => ({
-            localId: task.localId ?? `t${idx + 1}`,
-            title: task.title ?? "Task",
-            type: task.type,
-            description: task.description,
-            estimatedStoryPoints: typeof task.estimatedStoryPoints === "number" ? task.estimatedStoryPoints : undefined,
-            priorityHint: typeof task.priorityHint === "number" ? task.priorityHint : undefined,
-            dependsOnKeys: Array.isArray(task.dependsOnKeys) ? task.dependsOnKeys : [],
-            relatedDocs: Array.isArray(task.relatedDocs) ? task.relatedDocs : [],
-        }))
+            .map((task, idx) => {
+            const unitTests = parseTestList(task.unitTests);
+            const componentTests = parseTestList(task.componentTests);
+            const integrationTests = parseTestList(task.integrationTests);
+            const apiTests = parseTestList(task.apiTests);
+            const hasTests = unitTests.length || componentTests.length || integrationTests.length || apiTests.length;
+            const title = task.title ?? "Task";
+            const description = task.description ?? "";
+            const docOnly = /doc|documentation|readme|pdr|sds|openapi|spec/.test(`${title} ${description}`.toLowerCase());
+            if (!hasTests && !docOnly) {
+                unitTests.push(`Add tests for ${title} (unit/component/integration/api as applicable)`);
+            }
+            const qa = normalizeQaReadiness(task.qa);
+            return {
+                localId: task.localId ?? `t${idx + 1}`,
+                title,
+                type: normalizeTaskType(task.type) ?? "feature",
+                description,
+                estimatedStoryPoints: typeof task.estimatedStoryPoints === "number" ? task.estimatedStoryPoints : undefined,
+                priorityHint: typeof task.priorityHint === "number" ? task.priorityHint : undefined,
+                dependsOnKeys: Array.isArray(task.dependsOnKeys) ? task.dependsOnKeys : [],
+                relatedDocs: normalizeRelatedDocs(task.relatedDocs),
+                unitTests,
+                componentTests,
+                integrationTests,
+                apiTests,
+                qa,
+            };
+        })
             .filter((t) => t.title);
     }
     async generatePlanFromAgent(epics, agent, docSummary, options) {
@@ -571,7 +1051,7 @@ export class CreateTasksService {
         return { epics: planEpics, stories: planStories, tasks: planTasks };
     }
     async writePlanArtifacts(projectKey, plan, docSummary) {
-        const baseDir = path.join(this.workspace.workspaceRoot, ".mcoda", "tasks", projectKey);
+        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);
@@ -664,6 +1144,17 @@ export class CreateTasksService {
                 const epicId = epicIdByKey.get(task.epicKey);
                 if (!storyId || !epicId)
                     continue;
+                const classification = classifyTask({
+                    title: task.plan.title ?? `Task ${task.key}`,
+                    description: task.plan.description,
+                    type: task.plan.type,
+                });
+                const qaReadiness = buildQaReadiness({
+                    classification,
+                    planQa: task.plan.qa,
+                    preflight: options?.qaPreflight,
+                    overrides: options?.qaOverrides,
+                });
                 const depSlugs = (task.plan.dependsOnKeys ?? [])
                     .map((dep) => localToKey.get(dep))
                     .filter((value) => Boolean(value));
@@ -673,12 +1164,28 @@ export class CreateTasksService {
                     userStoryId: storyId,
                     key: task.key,
                     title: task.plan.title ?? `Task ${task.key}`,
-                    description: buildTaskDescription(task.key, task.plan.title ?? `Task ${task.key}`, task.plan.description, task.storyKey, task.epicKey, task.plan.relatedDocs, depSlugs),
+                    description: buildTaskDescription(task.key, task.plan.title ?? `Task ${task.key}`, task.plan.description, task.storyKey, task.epicKey, task.plan.relatedDocs, depSlugs, {
+                        unitTests: task.plan.unitTests,
+                        componentTests: task.plan.componentTests,
+                        integrationTests: task.plan.integrationTests,
+                        apiTests: task.plan.apiTests,
+                    }, qaReadiness),
                     type: task.plan.type ?? "feature",
                     status: "not_started",
                     storyPoints: task.plan.estimatedStoryPoints ?? null,
                     priority: task.plan.priorityHint ?? (taskInserts.length + 1),
-                    metadata: task.plan.relatedDocs ? { doc_links: task.plan.relatedDocs } : undefined,
+                    metadata: {
+                        doc_links: task.plan.relatedDocs ?? [],
+                        test_requirements: {
+                            unit: task.plan.unitTests ?? [],
+                            component: task.plan.componentTests ?? [],
+                            integration: task.plan.integrationTests ?? [],
+                            api: task.plan.apiTests ?? [],
+                        },
+                        stage: classification.stage,
+                        foundation: classification.foundation,
+                        qa: qaReadiness,
+                    },
                 });
             }
             taskRows = await this.workspaceRepo.insertTasks(taskInserts, false);
@@ -771,11 +1278,18 @@ export class CreateTasksService {
                 const docs = await this.prepareDocs(options.inputs);
                 const { docSummary, warnings: docWarnings } = this.buildDocContext(docs);
                 const { prompt } = this.buildPrompt(options.projectKey, docs, options);
+                const qaPreflight = await this.buildQaPreflight();
+                const qaOverrides = this.buildQaOverrides(options);
                 await this.jobService.writeCheckpoint(job.id, {
                     stage: "docs_indexed",
                     timestamp: new Date().toISOString(),
                     details: { count: docs.length, warnings: docWarnings },
                 });
+                await this.jobService.writeCheckpoint(job.id, {
+                    stage: "qa_preflight",
+                    timestamp: new Date().toISOString(),
+                    details: qaPreflight,
+                });
                 const 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);
@@ -810,7 +1324,10 @@ export class CreateTasksService {
                 const { epics: epicRows, stories: storyRows, tasks: taskRows, dependencies: dependencyRows } = await this.persistPlanToDb(project.id, options.projectKey, plan, job.id, commandRun.id, {
                     force: options.force,
                     resetKeys: options.force,
+                    qaPreflight,
+                    qaOverrides,
                 });
+                await this.seedPriorities(options.projectKey);
                 await this.jobService.updateJobStatus(job.id, "completed", {
                     payload: {
                         epicsCreated: epicRows.length,
@@ -822,6 +1339,27 @@ export class CreateTasksService {
                     },
                 });
                 await this.jobService.finishCommandRun(commandRun.id, "succeeded");
+                if (options.rateAgents) {
+                    try {
+                        const ratingService = this.ensureRatingService();
+                        await ratingService.rate({
+                            workspace: this.workspace,
+                            agentId: agent.id,
+                            commandName: "create-tasks",
+                            jobId: job.id,
+                            commandRunId: commandRun.id,
+                        });
+                    }
+                    catch (error) {
+                        const message = `Agent rating failed: ${error.message ?? String(error)}`;
+                        try {
+                            await this.jobService.appendLog(job.id, `${message}\n`);
+                        }
+                        catch {
+                            /* ignore rating log failures */
+                        }
+                    }
+                }
                 return {
                     jobId: job.id,
                     commandRunId: commandRun.id,
@@ -860,7 +1398,7 @@ export class CreateTasksService {
             commandName: "migrate-tasks",
             payload: { projectKey, planDir: options.planDir },
         });
-        const planDir = options.planDir ?? path.join(this.workspace.workspaceRoot, ".mcoda", "tasks", projectKey);
+        const planDir = options.planDir ?? path.join(this.workspace.mcodaDir, "tasks", projectKey);
         try {
             const planPath = path.join(planDir, "plan.json");
             const loadJson = async (file) => {