@mcoda/core 0.1.18 → 0.1.20

package/dist/services/execution/QaTasksService.js

@@ -27,7 +27,7 @@ import { GlobalRepository } from '@mcoda/db';
 import { DocdexClient } from '@mcoda/integrations';
 import { RoutingService } from '../agents/RoutingService.js';
 import { AgentRatingService } from '../agents/AgentRatingService.js';
-import { isDocContextExcluded, loadProjectGuidance, normalizeDocType } from '../shared/ProjectGuidance.js';
+import { ensureProjectGuidance, isDocContextExcluded, loadProjectGuidance, normalizeDocType, } from '../shared/ProjectGuidance.js';
 import { buildDocdexUsageGuidance } from '../shared/DocdexGuidance.js';
 import { createTaskCommentSlug, formatTaskCommentBody } from '../tasks/TaskCommentFormatter.js';
 import { AUTH_ERROR_REASON, isAuthErrorMessage } from '../shared/AuthErrors.js';
@@ -409,6 +409,8 @@ export class QaTasksService {
         this.workspace = workspace;
         this.deps = deps;
         this.dryRunGuard = false;
+        this.debugLogging = false;
+        this.projectKeyById = new Map();
         this.selectionService = deps.selectionService ?? new TaskSelectionService(workspace, deps.workspaceRepo);
         this.stateService = deps.stateService ?? new TaskStateService(deps.workspaceRepo);
         this.profileService =
@@ -930,7 +932,29 @@ export class QaTasksService {
             return 'unclear';
         return 'pass';
     }
-    async gatherDocContext(task, taskRunId, docLinks = []) {
+    async resolveTaskProjectKey(task, fallbackProjectKey) {
+        if (fallbackProjectKey?.trim())
+            return fallbackProjectKey.trim();
+        const taskMetadata = task.metadata ?? {};
+        const metadataProjectKey = typeof taskMetadata.project_key === 'string' ? taskMetadata.project_key.trim() : '';
+        if (metadataProjectKey)
+            return metadataProjectKey;
+        const cached = this.projectKeyById.get(task.projectId);
+        if (cached)
+            return cached;
+        try {
+            const project = await this.deps.workspaceRepo.getProjectById(task.projectId);
+            if (project?.key) {
+                this.projectKeyById.set(task.projectId, project.key);
+                return project.key;
+            }
+        }
+        catch {
+            // best effort only
+        }
+        return undefined;
+    }
+    async gatherDocContext(task, taskRunId, docLinks = [], projectKey) {
         if (!this.docdex)
             return '';
         let openApiIncluded = false;
@@ -946,16 +970,8 @@ export class QaTasksService {
             if (typeof this.docdex?.ensureRepoScope === 'function') {
                 await this.docdex.ensureRepoScope();
             }
-            const querySeeds = [task.key, task.title, ...(task.acceptanceCriteria ?? [])]
-                .filter(Boolean)
-                .join(' ')
-                .slice(0, 200);
-            const docs = await this.docdex.search({
-                projectKey: task.projectId,
-                profile: 'qa',
-                query: querySeeds,
-            });
             const snippets = [];
+            const seenRefs = new Set();
             const resolveDocType = async (doc) => {
                 const content = doc.segments?.[0]?.content ?? doc.content ?? '';
                 const normalized = normalizeDocType({
@@ -969,20 +985,94 @@ export class QaTasksService {
                 }
                 return normalized.docType;
             };
-            const filteredDocs = docs.filter((doc) => !isDocContextExcluded(doc.path ?? doc.title ?? doc.id, true));
-            for (const doc of filteredDocs.slice(0, 5)) {
-                const segments = (doc.segments ?? []).slice(0, 2);
-                const body = segments.length
-                    ? segments
-                        .map((seg, idx) => `  (${idx + 1}) ${seg.heading ? `${seg.heading}: ` : ''}${seg.content.slice(0, 400)}`)
-                        .join('\n')
-                    : doc.content
-                        ? doc.content.slice(0, 600)
-                        : '';
-                const docType = await resolveDocType(doc);
-                if (!shouldIncludeDocType(docType))
+            const runSearch = async (filter) => {
+                return await this.docdex.search(filter);
+            };
+            const pushDocs = async (docs) => {
+                const filteredDocs = docs.filter((doc) => !isDocContextExcluded(doc.path ?? doc.title ?? doc.id, true));
+                let added = 0;
+                for (const doc of filteredDocs.slice(0, 2)) {
+                    const ref = doc.path ?? doc.id ?? doc.title ?? 'doc';
+                    if (seenRefs.has(ref))
+                        continue;
+                    seenRefs.add(ref);
+                    const segments = (doc.segments ?? []).slice(0, 2);
+                    const body = segments.length
+                        ? segments
+                            .map((seg, idx) => `  (${idx + 1}) ${seg.heading ? `${seg.heading}: ` : ''}${(seg.content ?? '').slice(0, 400)}`)
+                            .join('\n')
+                        : doc.content
+                            ? doc.content.slice(0, 600)
+                            : '';
+                    const docType = await resolveDocType(doc);
+                    if (!shouldIncludeDocType(docType))
+                        continue;
+                    snippets.push(`- [${docType}] ${doc.title ?? doc.path ?? doc.id}\n${body}`.trim());
+                    added += 1;
+                }
+                return added;
+            };
+            const queryCandidates = Array.from(new Set([task.key, task.title, ...(task.acceptanceCriteria ?? [])].map((entry) => entry?.trim()).filter(Boolean))).slice(0, 6);
+            for (const query of queryCandidates) {
+                let structuredHits = 0;
+                try {
+                    const docs = await runSearch({
+                        query,
+                        projectKey,
+                        docType: 'SDS',
+                        profile: 'workspace-code',
+                    });
+                    structuredHits += await pushDocs(docs);
+                }
+                catch (error) {
+                    if (taskRunId) {
+                        await this.logTask(taskRunId, `Docdex SDS search failed for "${query}": ${error?.message ?? error}`, 'docdex');
+                    }
+                }
+                try {
+                    const docs = await runSearch({
+                        query,
+                        projectKey,
+                        docType: 'OPENAPI',
+                        profile: 'workspace-code',
+                    });
+                    structuredHits += await pushDocs(docs);
+                }
+                catch (error) {
+                    if (taskRunId) {
+                        await this.logTask(taskRunId, `Docdex OPENAPI search failed for "${query}": ${error?.message ?? error}`, 'docdex');
+                    }
+                }
+                if (structuredHits > 0)
                     continue;
-                snippets.push(`- [${docType}] ${doc.title ?? doc.path ?? doc.id}\n${body}`.trim());
+                try {
+                    const docs = await runSearch({
+                        query,
+                        projectKey,
+                        profile: 'qa',
+                    });
+                    await pushDocs(docs);
+                }
+                catch (error) {
+                    if (taskRunId) {
+                        await this.logTask(taskRunId, `Docdex QA search failed for "${query}": ${error?.message ?? error}`, 'docdex');
+                    }
+                }
+            }
+            if (!snippets.length && projectKey) {
+                try {
+                    const docs = await runSearch({
+                        query: 'sds openapi requirements architecture',
+                        projectKey,
+                        profile: 'workspace-code',
+                    });
+                    await pushDocs(docs);
+                }
+                catch (error) {
+                    if (taskRunId) {
+                        await this.logTask(taskRunId, `Docdex fallback search failed: ${error?.message ?? error}`, 'docdex');
+                    }
+                }
             }
             const normalizeDocLink = (value) => {
                 const trimmed = value.trim();
@@ -1683,7 +1773,9 @@ export class QaTasksService {
         const taskKeys = new Set(tasks.map((task) => task.task.key));
         const agent = await this.resolveAgent(request.agentName);
         const prompts = await this.loadPrompts(agent.id);
-        const projectGuidance = await loadProjectGuidance(this.workspace.workspaceRoot, this.workspace.mcodaDir);
+        const projectGuidance = await loadProjectGuidance(this.workspace.workspaceRoot, this.workspace.mcodaDir, {
+            projectKey: request.projectKey,
+        });
         const guidanceBlock = projectGuidance?.content ? `Project Guidance (read first):\n${projectGuidance.content}` : undefined;
         const systemPrompt = [guidanceBlock, prompts.jobPrompt, prompts.characterPrompt]
             .filter(Boolean)
@@ -1987,7 +2079,7 @@ export class QaTasksService {
         }
         return undefined;
     }
-    async interpretResult(task, profile, result, agentName, stream, jobId, commandRunId, taskRunId, commentBacklog, abortSignal) {
+    async interpretResult(task, profile, result, agentName, stream, jobId, commandRunId, taskRunId, projectKey, commentBacklog, abortSignal) {
         if (!this.agentService) {
             return { recommendation: this.mapOutcome(result) };
         }
@@ -2022,16 +2114,21 @@ export class QaTasksService {
             abortIfSignaled();
             const agent = await this.resolveAgent(agentName);
             const prompts = await this.loadPrompts(agent.id);
-            const projectGuidance = await loadProjectGuidance(this.workspace.workspaceRoot, this.workspace.mcodaDir);
+            const projectGuidance = await loadProjectGuidance(this.workspace.workspaceRoot, this.workspace.mcodaDir, {
+                projectKey,
+            });
             if (projectGuidance && taskRunId) {
                 await this.logTask(taskRunId, `Loaded project guidance from ${projectGuidance.source}`, 'project_guidance');
+                for (const warning of projectGuidance.warnings ?? []) {
+                    await this.logTask(taskRunId, `Project guidance warning: ${warning}`, 'project_guidance');
+                }
             }
             const guidanceBlock = projectGuidance?.content ? `Project Guidance (read first):\n${projectGuidance.content}` : undefined;
             const systemPrompt = [guidanceBlock, prompts.jobPrompt, prompts.characterPrompt, prompts.commandPrompt, QA_TEST_POLICY]
                 .filter(Boolean)
                 .join('\n\n');
             const docLinks = Array.isArray(task.task.metadata?.doc_links) ? task.task.metadata.doc_links : [];
-            const docCtx = await this.gatherDocContext(task.task, taskRunId, docLinks);
+            const docCtx = await this.gatherDocContext(task.task, taskRunId, docLinks, projectKey);
             const acceptance = (task.task.acceptanceCriteria ?? []).map((line) => `- ${line}`).join('\n');
             const prompt = [
                 systemPrompt,
@@ -2064,19 +2161,21 @@ export class QaTasksService {
             ]
                 .filter(Boolean)
                 .join('\n\n');
-            const separator = "============================================================";
-            console.info(separator);
-            console.info("[qa-tasks] START OF TASK");
-            console.info(`[qa-tasks] Task key: ${task.task.key}`);
-            console.info(`[qa-tasks] Title: ${task.task.title ?? '(none)'}`);
-            console.info(`[qa-tasks] Description: ${task.task.description ?? '(none)'}`);
-            console.info(`[qa-tasks] Story points: ${typeof task.task.storyPoints === 'number' ? task.task.storyPoints : '(none)'}`);
-            console.info(`[qa-tasks] Dependencies: ${task.dependencies.keys.length ? task.dependencies.keys.join(', ') : '(none available)'}`);
-            if (acceptance)
-                console.info(`[qa-tasks] Acceptance criteria:\n${acceptance}`);
-            console.info(`[qa-tasks] System prompt used:\n${systemPrompt || '(none)'}`);
-            console.info(`[qa-tasks] Task prompt used:\n${prompt}`);
-            console.info(separator);
+            if (this.debugLogging) {
+                const separator = "============================================================";
+                console.info(separator);
+                console.info("[qa-tasks] START OF TASK");
+                console.info(`[qa-tasks] Task key: ${task.task.key}`);
+                console.info(`[qa-tasks] Title: ${task.task.title ?? '(none)'}`);
+                console.info(`[qa-tasks] Description: ${task.task.description ?? '(none)'}`);
+                console.info(`[qa-tasks] Story points: ${typeof task.task.storyPoints === 'number' ? task.task.storyPoints : '(none)'}`);
+                console.info(`[qa-tasks] Dependencies: ${task.dependencies.keys.length ? task.dependencies.keys.join(', ') : '(none available)'}`);
+                if (acceptance)
+                    console.info(`[qa-tasks] Acceptance criteria:\n${acceptance}`);
+                console.info(`[qa-tasks] System prompt used:\n${systemPrompt || '(none)'}`);
+                console.info(`[qa-tasks] Task prompt used:\n${prompt}`);
+                console.info(separator);
+            }
             let output = '';
             let chunkCount = 0;
             if (stream && this.agentService.invokeStream) {
@@ -2530,9 +2629,15 @@ export class QaTasksService {
             return [];
         const agent = await this.resolveAgent(undefined);
         const prompts = await this.loadPrompts(agent.id);
-        const projectGuidance = await loadProjectGuidance(this.workspace.workspaceRoot, this.workspace.mcodaDir);
+        const projectKey = await this.resolveTaskProjectKey(task.task);
+        const projectGuidance = await loadProjectGuidance(this.workspace.workspaceRoot, this.workspace.mcodaDir, {
+            projectKey,
+        });
         if (projectGuidance && taskRunId) {
             await this.logTask(taskRunId, `Loaded project guidance from ${projectGuidance.source}`, 'project_guidance');
+            for (const warning of projectGuidance.warnings ?? []) {
+                await this.logTask(taskRunId, `Project guidance warning: ${warning}`, 'project_guidance');
+            }
         }
         const guidanceBlock = projectGuidance?.content ? `Project Guidance (read first):\n${projectGuidance.content}` : undefined;
         const systemPrompt = [guidanceBlock, prompts.jobPrompt, prompts.characterPrompt, prompts.commandPrompt].filter(Boolean).join('\n\n');
@@ -2654,47 +2759,99 @@ export class QaTasksService {
         }
         const skipReview = await this.shouldSkipQaForNoChanges(task.task);
         if (skipReview.skip) {
-            const message = 'QA skipped: code review reported no code changes to validate.';
-            await this.logTask(taskRun.id, message, 'qa-skip', { reason: 'review_no_changes', decision: skipReview.decision });
-            if (!this.dryRunGuard) {
-                await this.applyStateTransition(task.task, 'pass', statusContextBase);
-                await this.finishTaskRun(taskRun, 'succeeded');
-                await this.deps.workspaceRepo.createTaskQaRun({
-                    taskId: task.task.id,
-                    taskRunId: taskRun.id,
-                    jobId: ctx.jobId,
-                    commandRunId: ctx.commandRunId,
-                    source: 'auto',
-                    mode: 'auto',
-                    rawOutcome: 'pass',
-                    recommendation: 'pass',
-                    profileName: undefined,
-                    runner: undefined,
-                    metadata: { reason: 'review_no_changes', decision: skipReview.decision, reviewId: skipReview.reviewId },
-                });
-                const slug = createTaskCommentSlug({ source: 'qa-tasks', message, category: 'qa_result' });
-                const body = formatTaskCommentBody({
-                    slug,
-                    source: 'qa-tasks',
-                    message,
-                    status: 'resolved',
-                    category: 'qa_result',
-                });
-                await this.deps.workspaceRepo.createTaskComment({
-                    taskId: task.task.id,
-                    taskRunId: taskRun.id,
-                    jobId: ctx.jobId,
-                    sourceCommand: 'qa-tasks',
-                    authorType: 'agent',
-                    category: 'qa_result',
-                    slug,
-                    status: 'resolved',
-                    body,
-                    createdAt: new Date().toISOString(),
-                    resolvedAt: new Date().toISOString(),
+            const noChangesPolicy = ctx.request.noChangesPolicy ?? 'require_qa';
+            if (noChangesPolicy === 'skip') {
+                const message = 'QA skipped: code review reported no code changes to validate.';
+                await this.logTask(taskRun.id, message, 'qa-skip', { reason: 'review_no_changes', decision: skipReview.decision });
+                if (!this.dryRunGuard) {
+                    await this.applyStateTransition(task.task, 'pass', statusContextBase);
+                    await this.finishTaskRun(taskRun, 'succeeded');
+                    await this.deps.workspaceRepo.createTaskQaRun({
+                        taskId: task.task.id,
+                        taskRunId: taskRun.id,
+                        jobId: ctx.jobId,
+                        commandRunId: ctx.commandRunId,
+                        source: 'auto',
+                        mode: 'auto',
+                        rawOutcome: 'pass',
+                        recommendation: 'pass',
+                        profileName: undefined,
+                        runner: undefined,
+                        metadata: { reason: 'review_no_changes', decision: skipReview.decision, reviewId: skipReview.reviewId },
+                    });
+                    const slug = createTaskCommentSlug({ source: 'qa-tasks', message, category: 'qa_result' });
+                    const body = formatTaskCommentBody({
+                        slug,
+                        source: 'qa-tasks',
+                        message,
+                        status: 'resolved',
+                        category: 'qa_result',
+                    });
+                    await this.deps.workspaceRepo.createTaskComment({
+                        taskId: task.task.id,
+                        taskRunId: taskRun.id,
+                        jobId: ctx.jobId,
+                        sourceCommand: 'qa-tasks',
+                        authorType: 'agent',
+                        category: 'qa_result',
+                        slug,
+                        status: 'resolved',
+                        body,
+                        createdAt: new Date().toISOString(),
+                        resolvedAt: new Date().toISOString(),
+                    });
+                }
+                return { taskKey: task.task.key, outcome: 'pass', notes: 'review_no_changes' };
+            }
+            if (noChangesPolicy === 'manual') {
+                const message = 'QA requires manual validation: code review reported no code changes and policy is manual.';
+                await this.logTask(taskRun.id, message, 'qa-manual', {
+                    reason: 'review_no_changes_manual',
+                    decision: skipReview.decision,
                 });
+                if (!this.dryRunGuard) {
+                    await this.finishTaskRun(taskRun, 'succeeded');
+                    await this.deps.workspaceRepo.createTaskQaRun({
+                        taskId: task.task.id,
+                        taskRunId: taskRun.id,
+                        jobId: ctx.jobId,
+                        commandRunId: ctx.commandRunId,
+                        source: 'auto',
+                        mode: 'auto',
+                        rawOutcome: 'unclear',
+                        recommendation: 'unclear',
+                        profileName: undefined,
+                        runner: undefined,
+                        metadata: {
+                            reason: 'review_no_changes_manual',
+                            decision: skipReview.decision,
+                            reviewId: skipReview.reviewId,
+                        },
+                    });
+                    const slug = createTaskCommentSlug({ source: 'qa-tasks', message, category: 'qa_issue' });
+                    const body = formatTaskCommentBody({
+                        slug,
+                        source: 'qa-tasks',
+                        message,
+                        status: 'open',
+                        category: 'qa_issue',
+                    });
+                    await this.deps.workspaceRepo.createTaskComment({
+                        taskId: task.task.id,
+                        taskRunId: taskRun.id,
+                        jobId: ctx.jobId,
+                        sourceCommand: 'qa-tasks',
+                        authorType: 'agent',
+                        category: 'qa_issue',
+                        slug,
+                        status: 'open',
+                        body,
+                        createdAt: new Date().toISOString(),
+                        metadata: { reason: 'review_no_changes_manual' },
+                    });
+                }
+                return { taskKey: task.task.key, outcome: 'unclear', notes: 'review_no_changes_manual' };
             }
-            return { taskKey: task.task.key, outcome: 'pass', notes: 'review_no_changes' };
         }
         const branchCheck = await this.ensureTaskBranch(task, taskRun.id, ctx.jobId, ctx.request.allowDirty ?? false, ctx.request.cleanIgnorePaths);
         if (!branchCheck.ok) {
@@ -3376,10 +3533,11 @@ export class QaTasksService {
             });
             const commentContext = await this.loadCommentContext(task.task.id);
             const commentBacklog = buildCommentBacklog(commentContext.unresolved);
+            const taskProjectKey = await this.resolveTaskProjectKey(task.task, ctx.request.projectKey);
             let interpretation;
             try {
                 if (this.shouldUseAgentInterpretation()) {
-                    interpretation = await this.interpretResult(task, profile, result, ctx.request.agentName, ctx.request.agentStream ?? true, ctx.jobId, ctx.commandRunId, taskRun.id, commentBacklog, ctx.request.abortSignal);
+                    interpretation = await this.interpretResult(task, profile, result, ctx.request.agentName, ctx.request.agentStream ?? true, ctx.jobId, ctx.commandRunId, taskRun.id, taskProjectKey, commentBacklog, ctx.request.abortSignal);
                 }
                 else {
                     interpretation = this.buildDeterministicInterpretation(task, profile, result);
@@ -3797,6 +3955,8 @@ export class QaTasksService {
     async run(request) {
         this.qaProfilePlan = undefined;
         this.qaTaskPlans = undefined;
+        this.projectKeyById.clear();
+        this.debugLogging = request.debug === true;
         const resume = request.resumeJobId ? await this.deps.jobService.getJob(request.resumeJobId) : undefined;
         if (request.resumeJobId && !resume) {
             throw new Error(`Resume requested but job ${request.resumeJobId} not found`);
@@ -3807,6 +3967,14 @@ export class QaTasksService {
         const effectiveTasks = request.taskKeys?.length ? request.taskKeys : resume?.payload?.tasks;
         const effectiveStatus = request.statusFilter ?? resume?.payload?.statusFilter ?? ['ready_to_qa'];
         const effectiveLimit = request.limit ?? resume?.payload?.limit;
+        const effectiveDependencyPolicy = request.dependencyPolicy ?? resume?.payload?.dependencyPolicy ?? 'enforce';
+        const effectiveNoChangesPolicy = request.noChangesPolicy ?? resume?.payload?.noChangesPolicy ?? 'require_qa';
+        const normalizedRequest = {
+            ...request,
+            projectKey: effectiveProject,
+            dependencyPolicy: effectiveDependencyPolicy,
+            noChangesPolicy: effectiveNoChangesPolicy,
+        };
         const ignoreStatusFilter = Boolean(effectiveTasks?.length) || request.ignoreStatusFilter === true;
         const { filtered: statusFilter, rejected } = filterTaskStatuses(ignoreStatusFilter ? [] : effectiveStatus, QA_ALLOWED_STATUSES, QA_ALLOWED_STATUSES);
         const selection = await this.selectionService.selectTasks({
@@ -3816,7 +3984,7 @@ export class QaTasksService {
             taskKeys: effectiveTasks,
             statusFilter,
             limit: effectiveLimit,
-            ignoreDependencies: true,
+            ignoreDependencies: effectiveDependencyPolicy === 'ignore',
             ignoreStatusFilter,
         });
         if (rejected.length > 0 && !ignoreStatusFilter) {
@@ -3836,12 +4004,12 @@ export class QaTasksService {
                 throw new Error(resolveAbortReason());
             }
         };
-        const mode = request.mode ?? 'auto';
+        const mode = normalizedRequest.mode ?? 'auto';
         this.dryRunGuard = request.dryRun ?? false;
         if (request.dryRun) {
             const dryResults = [];
             if (mode !== 'manual') {
-                this.qaProfilePlan = await this.planProfilesWithAgent(selection.ordered, request, {
+                this.qaProfilePlan = await this.planProfilesWithAgent(selection.ordered, normalizedRequest, {
                     warnings: selection.warnings,
                 });
             }
@@ -3852,7 +4020,7 @@ export class QaTasksService {
                 abortIfSignaled();
                 let profiles = [];
                 try {
-                    profiles = await this.resolveProfilesForRequest(task.task, request);
+                    profiles = await this.resolveProfilesForRequest(task.task, normalizedRequest);
                 }
                 catch {
                     profiles = [];
@@ -3878,6 +4046,18 @@ export class QaTasksService {
             };
         }
         await this.ensureMcoda();
+        try {
+            const guidance = await ensureProjectGuidance(this.workspace.workspaceRoot, {
+                mcodaDir: this.workspace.mcodaDir,
+                projectKey: effectiveProject,
+            });
+            for (const warning of guidance.warnings ?? []) {
+                selection.warnings.push(`project_guidance_warning:${warning}`);
+            }
+        }
+        catch (error) {
+            selection.warnings.push(`project_guidance_bootstrap_failed:${error instanceof Error ? error.message : String(error)}`);
+        }
         const completedKeys = new Set();
         const checkpoints = request.resumeJobId ? await this.deps.jobService.readCheckpoints(request.resumeJobId) : [];
         const priorResults = new Map();
@@ -3913,18 +4093,21 @@ export class QaTasksService {
                     statusFilter,
                     limit: effectiveLimit,
                     mode,
-                    profile: request.profileName,
-                    level: request.level,
-                    agent: request.agentName,
+                    profile: normalizedRequest.profileName,
+                    level: normalizedRequest.level,
+                    agent: normalizedRequest.agentName,
                     agentStream,
-                    createFollowups: request.createFollowupTasks ?? 'auto',
+                    createFollowups: normalizedRequest.createFollowupTasks ?? 'auto',
+                    dependencyPolicy: effectiveDependencyPolicy,
+                    noChangesPolicy: effectiveNoChangesPolicy,
+                    debug: normalizedRequest.debug ?? false,
                     dryRun: request.dryRun ?? false,
                 },
                 totalItems: selection.ordered.length,
                 processedItems: completedKeys.size,
             });
         if (mode !== 'manual') {
-            this.qaProfilePlan = await this.planProfilesWithAgent(selection.ordered, request, {
+            this.qaProfilePlan = await this.planProfilesWithAgent(selection.ordered, normalizedRequest, {
                 jobId: job.id,
                 commandRunId: commandRun.id,
                 warnings: selection.warnings,
@@ -4034,11 +4217,11 @@ export class QaTasksService {
                 if (abortRemainingReason)
                     break;
                 abortIfSignaled();
-                const mode = request.mode ?? 'auto';
+                const mode = normalizedRequest.mode ?? 'auto';
                 const startedAt = new Date().toISOString();
                 const taskStartMs = Date.now();
                 const sessionId = formatSessionId(startedAt);
-                const qaAgentLabel = request.agentName ?? '(auto)';
+                const qaAgentLabel = normalizedRequest.agentName ?? '(auto)';
                 emitQaStart({
                     taskKey: task.task.key,
                     alias: `QA task ${task.task.key}`,
@@ -4053,10 +4236,10 @@ export class QaTasksService {
                 let result;
                 try {
                     if (mode === 'manual') {
-                        result = await this.runManual(task, { jobId: job.id, commandRunId: commandRun.id, request });
+                        result = await this.runManual(task, { jobId: job.id, commandRunId: commandRun.id, request: normalizedRequest });
                     }
                     else {
-                        result = await this.runAuto(task, { jobId: job.id, commandRunId: commandRun.id, request, warnings });
+                        result = await this.runAuto(task, { jobId: job.id, commandRunId: commandRun.id, request: normalizedRequest, warnings });
                     }
                 }
                 catch (error) {

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

@@ -12,7 +12,9 @@ export interface TaskSelectionFilters {
     limit?: number;
     parallel?: number;
     ignoreDependencies?: boolean;
+    missingContextPolicy?: MissingContextPolicy;
 }
+export type MissingContextPolicy = "allow" | "warn" | "block";
 export interface SelectedTask {
     task: TaskRow & {
         epicKey: string;
@@ -46,6 +48,7 @@ export declare class TaskSelectionService {
     private buildTaskFromRow;
     private loadTasks;
     private loadDependencies;
+    private loadMissingContext;
     private topologicalOrder;
     selectTasks(filters: TaskSelectionFilters): Promise<TaskSelectionPlan>;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"TaskSelectionService.d.ts","sourceRoot":"","sources":["../../../src/services/execution/TaskSelectionService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAErE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAE1E,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,GAAG;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;KAC/B,CAAC;IACF,YAAY,EAAE;QACZ,GAAG,EAAE,MAAM,EAAE,CAAC;QACd,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,OAAO,EAAE,oBAAoB,GAAG;QAAE,iBAAiB,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAChE,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA0HD,qBAAa,oBAAoB;IACnB,OAAO,CAAC,SAAS;IAAuB,OAAO,CAAC,aAAa;gBAArD,SAAS,EAAE,mBAAmB,EAAU,aAAa,EAAE,mBAAmB;WAEjF,MAAM,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAK5E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAId,YAAY;IAK1B,OAAO,CAAC,gBAAgB;YAiCV,SAAS;YA2DT,gBAAgB;IAgC9B,OAAO,CAAC,gBAAgB;IAgElB,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CA6G7E"}
+{"version":3,"file":"TaskSelectionService.d.ts","sourceRoot":"","sources":["../../../src/services/execution/TaskSelectionService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAErE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAE1E,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;CAC7C;AAED,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,GAAG;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;KAC/B,CAAC;IACF,YAAY,EAAE;QACZ,GAAG,EAAE,MAAM,EAAE,CAAC;QACd,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,OAAO,EAAE,oBAAoB,GAAG;QAAE,iBAAiB,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAChE,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA0HD,qBAAa,oBAAoB;IACnB,OAAO,CAAC,SAAS;IAAuB,OAAO,CAAC,aAAa;gBAArD,SAAS,EAAE,mBAAmB,EAAU,aAAa,EAAE,mBAAmB;WAEjF,MAAM,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAK5E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAId,YAAY;IAK1B,OAAO,CAAC,gBAAgB;YAiCV,SAAS;YA2DT,gBAAgB;YAgChB,kBAAkB;IAgBhC,OAAO,CAAC,gBAAgB;IAgElB,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAkI7E"}

package/dist/services/execution/TaskSelectionService.js

@@ -215,6 +215,19 @@ export class TaskSelectionService {
         }
         return grouped;
     }
+    async loadMissingContext(taskIds) {
+        if (taskIds.length === 0)
+            return new Set();
+        const placeholders = taskIds.map(() => "?").join(", ");
+        const rows = await this.workspaceRepo.getDb().all(`
+        SELECT DISTINCT task_id
+        FROM task_comments
+        WHERE task_id IN (${placeholders})
+          AND LOWER(category) = 'missing_context'
+          AND (status IS NULL OR LOWER(status) = 'open')
+      `, ...taskIds);
+        return new Set(rows.map((row) => row.task_id));
+    }
     topologicalOrder(tasks, deps) {
         const warnings = [];
         const taskMap = new Map(tasks.map((t) => [t.task.id, t]));
@@ -330,6 +343,8 @@ export class TaskSelectionService {
         }
         const candidateIds = dedupedTasks.map((t) => t.task_id);
         const deps = await this.loadDependencies(candidateIds);
+        const missingContextPolicy = filters.missingContextPolicy ?? "warn";
+        const missingContext = missingContextPolicy === "allow" ? new Set() : await this.loadMissingContext(candidateIds);
         const taskMap = new Map();
         for (const row of dedupedTasks) {
             const task = this.buildTaskFromRow(row);
@@ -340,6 +355,8 @@ export class TaskSelectionService {
         }
         const eligible = [];
         const skippedDependencies = [];
+        const skippedMissingContext = [];
+        const warnedMissingContext = [];
         const ignoreDependencies = filters.ignoreDependencies === true;
         for (const [taskId, entry] of taskMap.entries()) {
             const depRows = deps.get(taskId) ?? [];
@@ -373,12 +390,27 @@ export class TaskSelectionService {
                 skippedDependencies.push(entry.task.key);
                 continue;
             }
+            if (missingContext.has(taskId)) {
+                if (missingContextPolicy === "block") {
+                    skippedMissingContext.push(entry.task.key);
+                    continue;
+                }
+                if (missingContextPolicy === "warn") {
+                    warnedMissingContext.push(entry.task.key);
+                }
+            }
             eligible.push(entry);
         }
         const { ordered, warnings: topoWarnings } = this.topologicalOrder(eligible, deps);
         if (skippedDependencies.length > 0) {
             selectionWarnings.push(`Skipped ${skippedDependencies.length} task(s) due to dependencies not ready.`);
         }
+        if (missingContextPolicy === "warn" && warnedMissingContext.length > 0) {
+            selectionWarnings.push(`Tasks with open missing_context comments: ${warnedMissingContext.length}.`);
+        }
+        if (missingContextPolicy === "block" && skippedMissingContext.length > 0) {
+            selectionWarnings.push(`Skipped ${skippedMissingContext.length} task(s) with open missing_context comments.`);
+        }
         const combinedWarnings = [...dedupeWarnings, ...selectionWarnings, ...topoWarnings];
         const limited = typeof filters.limit === "number" && filters.limit > 0 ? ordered.slice(0, filters.limit) : ordered;
         return {
@@ -389,6 +421,7 @@ export class TaskSelectionService {
                 effectiveStatuses,
                 includeTypes: includeTypes.length ? includeTypes : undefined,
                 excludeTypes: excludeTypes.length ? excludeTypes : undefined,
+                missingContextPolicy,
             },
             ordered: limited,
             warnings: combinedWarnings,