@tea-agent/loop-agent 0.14.0 → 0.16.0

package/dist/worker/run-task/run-task.js

@@ -7,6 +7,9 @@ import { controllerIdentityExpectationFailure, resolveControllerIdentity, } from
 import { materializeTaskSpec, } from "../materialize/harness-task-materializer.js";
 import { preflightTargetRepo } from "../preflight.js";
 import { getTaskPoolRoot } from "../pool/run-store.js";
+import { checkRequiredOutputs } from "../outcomes/gate.js";
+import { projectOutcome } from "../outcomes/projector.js";
+import { writeOutcome } from "../outcomes/store.js";
 export const DEFAULT_RUN_DAG_TIMEOUT_MS = 1_800_000;
 export const MAX_WORKER_TIMEOUT_MS = 7_200_000;
 export async function runTaskSpec(options) {
@@ -150,7 +153,7 @@ export async function runTaskSpec(options) {
         });
         return decision;
     }, { statusForResult: (decision) => decision.succeeded ? "succeeded" : "failed" });
-    const status = reportDecision.succeeded ? "succeeded" : "failed";
+    let status = reportDecision.succeeded ? "succeeded" : "failed";
     progress.step(`report decision: ${status} (${reportDecision.reason}${reportDecision.runStatus ? `, status=${reportDecision.runStatus}` : ""})`);
     const failureArtifacts = reportDecision.succeeded
         ? undefined
@@ -161,7 +164,83 @@ export async function runTaskSpec(options) {
             taskArtifactsDir,
             eventCtx,
         });
-    if (reportDecision.succeeded && !options.skipSuccessFinalization) {
+    // The outcome adapter reads a canonical worker record. Persist that fact
+    // before gating, but do not promote or close out until the projection passes.
+    const provisionalRecord = {
+        schemaVersion: 1,
+        status,
+        workerRunId,
+        businessId: options.taskSpec.id,
+        harnessTaskId: materializeManifest.harnessTaskId,
+        featureId: options.taskSpec.feature_id,
+        workflow: materializeManifest.workflow,
+        loopAgentProfile: materializeManifest.loopAgentProfile,
+        dagPath,
+        runRecordPath,
+        materializeManifest,
+        reportDecision,
+        commands,
+        ...(failureArtifacts ? { failureArtifacts } : {}),
+        ...(controllerIdentity ? { controllerIdentity } : {}),
+    };
+    await writeFile(runRecordPath, `${JSON.stringify(provisionalRecord, null, 2)}\n`, "utf-8");
+    let outcome;
+    let outcomeFailure;
+    const projection = await projectOutcome({
+        repoRoot: options.repoRoot,
+        workerRunId,
+        taskSpec: options.taskSpec,
+        taskSpecPath: options.taskSpecPath,
+        runRecord: {
+            featureId: options.taskSpec.feature_id,
+            taskId: options.taskSpec.id,
+            workerRunId,
+            harnessTaskId: materializeManifest.harnessTaskId,
+            workflow: materializeManifest.workflow,
+            ...(controllerIdentity ? { controllerIdentity } : {}),
+        },
+        reportDecision,
+        runRecordPath,
+        dagPath,
+        acceptanceRefs: options.taskSpec.acceptance_refs,
+        now,
+    });
+    if (!projection.ok) {
+        status = "failed";
+        outcomeFailure = { category: projection.category, reason: projection.reason };
+        progress.step(`outcome projection failed: ${projection.category} (${projection.reason})`);
+    }
+    else {
+        let envelope = projection.envelope;
+        const gate = checkRequiredOutputs(envelope, options.taskSpec.outputs.required);
+        if (reportDecision.succeeded && !gate.passed) {
+            status = "failed";
+            outcomeFailure = {
+                category: "ContractMismatch",
+                reason: `missing required outputs: ${gate.missing.join(", ")}`,
+            };
+            envelope = {
+                ...envelope,
+                outcomeStatus: "failed",
+                outcomeFailure: {
+                    category: "ContractMismatch",
+                    reason: `missing required outputs: ${gate.missing.join(", ")}`,
+                    missingOutputs: [...gate.missing],
+                },
+            };
+            progress.step(`required output gate failed: ${gate.missing.join(", ")}`);
+        }
+        else if (envelope.outcomeFailure) {
+            outcomeFailure = {
+                category: envelope.outcomeFailure.category,
+                reason: envelope.outcomeFailure.reason,
+            };
+        }
+        // Persist succeeded and failed envelopes so read models can inspect
+        // outcomeFailure without re-parsing run-record / report decision.
+        outcome = await writeOutcome(options.repoRoot, envelope);
+    }
+    if (status === "succeeded" && !options.skipSuccessFinalization) {
         await runObservedStep(eventCtx, "promote-run", async () => {
             progress.step("promote run");
             await runRequiredCommand(options.repoRoot, client, "promote-run", ["promote-run", materializeManifest.harnessTaskId, "--run-id", workerRunId], true, undefined, eventCtx);
@@ -178,6 +257,7 @@ export async function runTaskSpec(options) {
         businessId: options.taskSpec.id,
         harnessTaskId: materializeManifest.harnessTaskId,
         featureId: options.taskSpec.feature_id,
+        workflow: materializeManifest.workflow,
         loopAgentProfile: materializeManifest.loopAgentProfile,
         dagPath,
         runRecordPath,
@@ -211,9 +291,12 @@ export async function runTaskSpec(options) {
         workerRunId,
         businessId: options.taskSpec.id,
         harnessTaskId: materializeManifest.harnessTaskId,
+        workflow: materializeManifest.workflow,
         runRecordPath,
         dagPath,
         reportDecision,
+        ...(outcome ? { outcome } : {}),
+        ...(outcomeFailure ? { outcomeFailure } : {}),
         ...(failureArtifacts ? { failureArtifacts } : {}),
     };
 }

package/dist/worker/runner/run-ready.js

@@ -5,6 +5,7 @@ import YAML from "yaml";
 import { controllerIdentitiesMatch, controllerIdentityExpectationFailure, resolveControllerIdentity, } from "../loop-agent/loop-agent-client.js";
 import { deriveFailureRoute, deriveFailureRouteFromError, } from "../pool/failure-routing.js";
 import { findRunByWorkerRunId, getTaskPoolRoot, readFeatureTaskPoolStates, recordTaskPoolRun, writeTaskPoolState, } from "../pool/run-store.js";
+import { readVerifiedOutcome } from "../outcomes/store.js";
 import { runTaskSpec, } from "../run-task/run-task.js";
 import { formatDuration, noopProgressReporter, } from "../progress-reporter.js";
 import { planReadyTasks } from "../task-graph/ready-planner.js";
@@ -36,12 +37,14 @@ export async function runReadyTasks(options) {
     const graph = await loadTaskGraph(options.featureDir);
     const featureId = graph.feature_id;
     const states = await readFeatureTaskPoolStates(options.repoRoot, featureId);
+    const outcomes = await loadVerifiedOutcomes(options.repoRoot, states);
     const taskSpecs = await loadFeatureTaskSpecs(options.featureDir, graph);
     const plan = planReadyTasks({
         featureId,
         graph,
         taskSpecs,
         states,
+        outcomes,
         selectionLimit: options.limit ?? graph.nodes.length,
     });
     const limitedTaskIds = plan.selected.map((candidate) => candidate.taskId);
@@ -211,7 +214,14 @@ export async function runReadyTasks(options) {
             });
             continue;
         }
-        const failure = deriveFailureRoute(result);
+        const failure = result.outcomeFailure
+            ? {
+                category: result.outcomeFailure.category,
+                recommendedFollowUpKind: "manual-review",
+                derivedFollowUpTaskId: `${taskId}-outcome-contract-review`,
+                source: "report-decision",
+            }
+            : deriveFailureRoute(result);
         emit(progress, {
             type: "task.finished",
             source: "worker",
@@ -256,6 +266,8 @@ export async function runReadyTasks(options) {
             ...(retryOfWorkerRunId ? { retryOfWorkerRunId } : {}),
             ...(result.failureArtifacts ? { failureArtifacts: result.failureArtifacts } : {}),
             ...(controllerIdentity ? { controllerIdentity } : {}),
+            ...(result.workflow ? { workflow: result.workflow } : {}),
+            ...(result.outcome ? { outcomePath: result.outcome.outcomePath, outcomeSha256: result.outcome.outcomeSha256 } : {}),
         };
         let recorded = false;
         try {
@@ -314,6 +326,25 @@ export async function runReadyTasks(options) {
     });
     return output;
 }
+async function loadVerifiedOutcomes(repoRoot, states) {
+    const outcomes = new Map();
+    for (const state of Object.values(states)) {
+        if (!state.workerRunId)
+            continue;
+        const run = await findRunByWorkerRunId(repoRoot, state.workerRunId);
+        if (!run)
+            continue;
+        const outcome = await readVerifiedOutcome({
+            repoRoot,
+            workerRunId: state.workerRunId,
+            outcomePath: run.outcomePath,
+            outcomeSha256: run.outcomeSha256,
+        });
+        if (outcome)
+            outcomes.set(state.workerRunId, outcome);
+    }
+    return outcomes;
+}
 function emit(progress, input) {
     const structured = progress;
     if (typeof structured.event !== "function")

package/dist/worker/task-graph/acceptance-schema.js

@@ -12,6 +12,18 @@ export const acceptanceItemSchema = z
         .object({
         expected_task_refs: z.array(z.string().min(1)).min(1),
         suggested_tests: z.array(z.string().min(1)).optional().default([]),
+        /**
+         * fullstack-v1 dual-coverage declarations (M4). All optional so legacy
+         * packets and inline fixtures using only `expected_task_refs` keep
+         * parsing unchanged. Kept strict: no passthrough, otherwise typed
+         * validators/read models could not read these fields.
+         */
+        implementation_task_refs: z.array(z.string().min(1)).optional(),
+        verification_task_refs: z.array(z.string().min(1)).optional(),
+        required_evidence: z.array(z.string().min(1)).optional(),
+        integration: z
+            .enum(["not-applicable", "mock-allowed", "real-required"])
+            .optional(),
     })
         .strict(),
 })

package/dist/worker/task-graph/ready-planner.js

@@ -31,6 +31,19 @@ export function planReadyTasks(input) {
     }
     const eligible = [];
     const blocked = [];
+    // Build a producer->declared-kinds index once (loop-free) so the artifact
+    // gate can verify graph-level consumes/produces consistency without reading
+    // `produces` per-node. The gate is only consulted when `outcomes` is
+    // injected, so this index is unused otherwise (no behavior change).
+    const producerKinds = new Map();
+    for (const node of input.graph.nodes) {
+        if (node.produces && node.produces.length > 0) {
+            const set = producerKinds.get(node.id) ?? new Set();
+            for (const decl of node.produces)
+                set.add(decl.kind);
+            producerKinds.set(node.id, set);
+        }
+    }
     for (const [graphIndex, node] of input.graph.nodes.entries()) {
         const spec = input.taskSpecs.get(node.id);
         if (!spec) {
@@ -85,6 +98,19 @@ export function planReadyTasks(input) {
             });
             continue;
         }
+        const gateFailure = evaluateArtifactGate(node.consumes ?? [], input.featureId, input.states, input.outcomes, producerKinds);
+        if (gateFailure) {
+            blocked.push({
+                featureId: input.featureId,
+                taskId: node.id,
+                priority: spec.priority,
+                reasonCode: "required-artifact-missing",
+                reason: "required artifact is missing or invalid",
+                blockedBy: gateFailure.blockedBy,
+                artifactGate: gateFailure.projection,
+            });
+            continue;
+        }
         eligible.push({
             featureId: input.featureId,
             taskId: node.id,
@@ -125,6 +151,111 @@ export function planReadyTasks(input) {
         },
     };
 }
+/**
+ * Evaluate artifact-gate eligibility for a node whose dependencies are all
+ * `Done`. Returns the first blocking projection, or `undefined` when eligible.
+ *
+ * Envelope-level binding only: Feature / producer task / kind / optional
+ * schemaId / optional sourceBinding must match the injected Outcome. The
+ * planner is pure and synchronous — it does **not** re-read artifact files or
+ * recompute sha256. Callers must inject envelopes via `readVerifiedOutcome`
+ * (path/hash of the outcome JSON). File-level artifact sha256 is enforced at
+ * `projectOutcome` and again at Feature Verification Bundle / verify-final /
+ * Delivery / Closeout (`verifyArtifactRefs`).
+ *
+ * When `outcomes` is omitted, this gate is skipped (legacy callers unchanged).
+ */
+function evaluateArtifactGate(consumes, featureId, states, outcomes, producerKinds) {
+    if (!outcomes || !consumes || consumes.length === 0)
+        return undefined;
+    for (const ref of consumes) {
+        // Graph-level precheck (gap B): the producer must exist in the graph and
+        // must declare the consumed `kind`. This runs *before* envelope lookup so
+        // a stray matching envelope can never bypass a missing/misdeclared wire.
+        const declaredKinds = producerKinds.get(ref.producerTaskId);
+        if (!declaredKinds) {
+            return {
+                blockedBy: [ref.producerTaskId],
+                projection: {
+                    producerTaskId: ref.producerTaskId,
+                    kind: ref.kind,
+                    missingKind: "producer-kind-undeclared",
+                    detail: `producer node ${ref.producerTaskId} not in graph`,
+                },
+            };
+        }
+        if (!declaredKinds.has(ref.kind)) {
+            return {
+                blockedBy: [ref.producerTaskId],
+                projection: {
+                    producerTaskId: ref.producerTaskId,
+                    kind: ref.kind,
+                    missingKind: "producer-kind-undeclared",
+                    detail: `producer ${ref.producerTaskId} does not declare kind ${ref.kind}`,
+                },
+            };
+        }
+        const failure = evaluateArtifactRef(ref, featureId, states, outcomes);
+        if (failure)
+            return failure;
+    }
+    return undefined;
+}
+function evaluateArtifactRef(ref, featureId, states, outcomes) {
+    const projection = (missingKind, detail) => ({
+        blockedBy: [ref.producerTaskId],
+        projection: { producerTaskId: ref.producerTaskId, kind: ref.kind, missingKind, detail },
+    });
+    const depState = states[ref.producerTaskId];
+    // Non-Done producers are handled by the existing dependency gate; do not
+    // duplicate that classification here.
+    if (depState?.status !== undefined && depState.status !== "Done")
+        return undefined;
+    const workerRunId = depState?.workerRunId;
+    if (!workerRunId)
+        return projection("outcome-absent", "producer state has no workerRunId");
+    const envelope = outcomes.get(workerRunId);
+    if (!envelope)
+        return projection("outcome-absent", "no outcome envelope injected for workerRunId");
+    // Fail-closed (gap A): a producer run that ended in `failed` carries no
+    // trustworthy artifact even if its `kind` happens to match. Such an envelope
+    // must never make a downstream Ready.
+    if (envelope.outcomeStatus !== "succeeded") {
+        return projection("outcome-absent", `producer outcome status ${envelope.outcomeStatus}`);
+    }
+    if (envelope.identity.featureId !== featureId) {
+        return projection("feature-cross-wire", `envelope featureId ${envelope.identity.featureId} != ${featureId}`);
+    }
+    if (envelope.identity.taskId !== ref.producerTaskId) {
+        return projection("producer-task-mismatch", `envelope taskId ${envelope.identity.taskId} != ${ref.producerTaskId}`);
+    }
+    const artifact = envelope.artifacts.find((item) => item.kind !== undefined && item.kind === ref.kind);
+    if (!artifact) {
+        return projection("artifact-kind-absent", `no artifact with kind ${ref.kind}`);
+    }
+    if (ref.schemaId !== undefined) {
+        const artifactSchemaId = artifact.schemaId ?? artifact.kind;
+        if (artifactSchemaId !== ref.schemaId) {
+            return projection("schema-mismatch", `artifact schemaId ${String(artifactSchemaId)} != ${ref.schemaId}`);
+        }
+    }
+    if (ref.sourceBinding) {
+        const envBinding = envelope.sourceBinding;
+        if (!envBinding) {
+            return projection("source-binding-mismatch", "envelope has no sourceBinding");
+        }
+        if (ref.sourceBinding.sourceFiles !== undefined) {
+            const envFile = envBinding.sourceFiles?.[0];
+            if (envFile !== ref.sourceBinding.sourceFiles[0]) {
+                return projection("source-binding-mismatch", `sourceFiles[0] ${String(envFile)} != ${ref.sourceBinding.sourceFiles[0]}`);
+            }
+        }
+        if (ref.sourceBinding.sha256 !== undefined && envBinding.sha256 !== ref.sourceBinding.sha256) {
+            return projection("source-binding-mismatch", "sourceBinding sha256 mismatch");
+        }
+    }
+    return undefined;
+}
 function priority(value) {
     return { P0: 0, P1: 1, P2: 2, P3: 3 }[value];
 }

package/dist/worker/task-graph/task-graph-schema.js

@@ -1,11 +1,42 @@
 import { z } from "zod";
 import { taskSpecTypeSchema } from "../task-spec/schema.js";
+/** Producer-side artifact declaration on a graph node. */
+export const artifactDeclSchema = z
+    .object({
+    kind: z.string().min(1),
+    path: z.string().min(1).optional(),
+    schemaId: z.string().min(1).optional(),
+})
+    .strict();
+/**
+ * Consumer-side artifact reference. Ready Planner validates envelope-level
+ * Feature / producer / kind / optional schemaId / optional sourceBinding.
+ * File-level path+sha256 of artifact bytes is enforced at Outcome projection
+ * and Feature Verification Bundle / Delivery / Closeout — not inside the
+ * synchronous Ready Planner.
+ */
+export const artifactRefSchema = z
+    .object({
+    kind: z.string().min(1),
+    schemaId: z.string().min(1).optional(),
+    producerTaskId: z.string().min(1),
+    sourceBinding: z
+        .object({
+        sourceFiles: z.array(z.string().min(1)).optional(),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
 export const taskGraphNodeSchema = z
     .object({
     id: z.string().min(1),
     task: z.string().min(1),
     type: taskSpecTypeSchema,
     depends_on: z.array(z.string().min(1)).optional().default([]),
+    produces: z.array(artifactDeclSchema).optional(),
+    consumes: z.array(artifactRefSchema).optional(),
 })
     .strict();
 export const taskGraphSpecSchema = z

package/dist/worker/task-graph/validate.js

@@ -6,21 +6,27 @@ import { validateTaskSpec } from "../task-spec/validate.js";
 import { acceptanceSpecSchema } from "./acceptance-schema.js";
 import { computeReadyQueue } from "./ready-queue.js";
 import { taskGraphSpecSchema } from "./task-graph-schema.js";
+import { FEATURE_PROFILE_FILENAME, featureProfileSchema, isFullstackProfile, } from "../feature/profile-schema.js";
+import { validateFullstackStructure } from "../feature/fullstack-validate.js";
 export async function validateFeatureTaskGraph(featureDir, options = {}) {
     const errors = [];
     const acceptance = await loadAcceptanceSpec(featureDir, options, errors);
     const graph = await loadTaskGraphSpec(featureDir, options, errors);
     if (!acceptance || !graph) {
-        return result("", acceptance, graph, errors);
+        return result("", acceptance, graph, errors, "generic");
     }
     checkDuplicateNodeIds(graph, errors);
     checkDuplicateAcceptanceIds(acceptance, errors);
     checkAcceptanceTaskRefs(acceptance, graph, errors);
     checkUnknownDependencies(graph, errors);
     checkCycles(graph, errors);
-    await checkTaskFiles(featureDir, graph, acceptance, errors);
+    const taskSpecs = await checkTaskFiles(featureDir, graph, acceptance, errors);
     await checkQaCloseoutOrder(featureDir, options, errors);
-    return result(graph.feature_id, acceptance, graph, errors);
+    const profile = await loadFeatureProfile(featureDir, options, acceptance.feature_id, errors);
+    if (acceptance && graph && profile && isFullstackProfile(profile) && taskSpecs) {
+        errors.push(...validateFullstackStructure({ profile, acceptance, graph, taskSpecs }));
+    }
+    return result(graph.feature_id, acceptance, graph, errors, profile?.profile ?? "generic");
 }
 async function checkQaCloseoutOrder(featureDir, options, errors) {
     const closeoutPath = path.join(featureDir, "closeout.yaml");
@@ -163,6 +169,7 @@ function checkCycles(graph, errors) {
 }
 async function checkTaskFiles(featureDir, graph, acceptance, errors) {
     const acceptanceIds = new Set(acceptance.acceptance.map((item) => item.id));
+    const taskSpecs = new Map();
     for (const node of graph.nodes) {
         const taskPath = path.join(featureDir, "tasks", node.task);
         if (!(await exists(taskPath))) {
@@ -184,6 +191,7 @@ async function checkTaskFiles(featureDir, graph, acceptance, errors) {
             continue;
         }
         const taskSpec = parsedTask.data;
+        taskSpecs.set(node.id, taskSpec);
         const detailed = await validateTaskSpec(rawTask, { taskSpecPath: taskPath });
         for (const issue of detailed.errors) {
             errors.push({
@@ -223,8 +231,9 @@ async function checkTaskFiles(featureDir, graph, acceptance, errors) {
             });
         }
     }
+    return taskSpecs;
 }
-function result(featureId, acceptance, graph, errors) {
+function result(featureId, acceptance, graph, errors, profile) {
     return {
         ok: errors.length === 0,
         featureId,
@@ -232,6 +241,7 @@ function result(featureId, acceptance, graph, errors) {
             acceptanceCount: acceptance?.acceptance.length ?? 0,
             nodeCount: graph?.nodes.length ?? 0,
             readyWithoutState: graph ? computeReadyQueue(graph, {}) : [],
+            profile,
         },
         errors,
     };
@@ -251,3 +261,33 @@ function sameStringSet(left, right) {
     const rightSet = new Set(right);
     return left.every((value) => rightSet.has(value));
 }
+async function loadFeatureProfile(featureDir, options, expectedFeatureId, errors) {
+    const profilePath = path.join(featureDir, FEATURE_PROFILE_FILENAME);
+    let raw = options.profileOverride;
+    if (raw === undefined) {
+        if (!(await exists(profilePath))) {
+            // No feature.yaml → generic packet. Legacy/generic validation behavior is
+            // preserved; fullstack gates do not fire.
+            return undefined;
+        }
+        raw = YAML.parse(await readFile(profilePath, "utf-8"));
+    }
+    const parsed = featureProfileSchema.safeParse(raw);
+    if (!parsed.success) {
+        errors.push({
+            code: "feature-profile-schema-invalid",
+            message: parsed.error.issues.map((issue) => issue.message).join("; "),
+            path: FEATURE_PROFILE_FILENAME,
+        });
+        return undefined;
+    }
+    if (parsed.data.feature_id !== expectedFeatureId) {
+        errors.push({
+            code: "feature-profile-id-mismatch",
+            message: `feature.yaml feature_id ${parsed.data.feature_id} differs from acceptance/graph ${expectedFeatureId}`,
+            path: `${FEATURE_PROFILE_FILENAME}:feature_id`,
+        });
+        return undefined;
+    }
+    return parsed.data;
+}

package/dist/worker/task-spec/schema.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { taskCapabilitySchema, verifyModeSchema, verifyPresetSchema, verifyQuotaSchema, } from "../../task/config-types.js";
+import { workflowSchema } from "./workflow-routing.js";
 export const taskSpecTypeSchema = z.enum([
     "architecture",
     "backend-feature",
@@ -92,6 +93,14 @@ export const taskSpecSchema = z
         create_worktree: z.boolean().optional().default(false),
     })
         .strict(),
+    /**
+     * Optional explicit runtime workflow that routes the TaskSpec to a DAG.
+     * Orthogonal to the business {@link type} and the governance loop_agent
+     * profile. When absent, legacy backend/frontend feature types route
+     * deterministically; legacy QA types retain their current default behavior
+     * with migration guidance until they declare it explicitly.
+     */
+    execution: z.object({ workflow: workflowSchema }).strict().optional(),
     loop_agent: z
         .object({
         profile_policy: z.literal("mapped"),

package/dist/worker/task-spec/validate.js

@@ -4,6 +4,7 @@ import YAML from "yaml";
 import { resolveLoopAgentProfile } from "../profile-mapping.js";
 import { mapRiskLevelToComplexity } from "./complexity-mapping.js";
 import { taskSpecSchema } from "./schema.js";
+import { resolveWorkflow, validateWorkflowCompatibility, } from "./workflow-routing.js";
 const CODE_WRITING_TYPES = new Set([
     "backend-feature",
     "frontend-feature",
@@ -42,6 +43,7 @@ export async function validateTaskSpec(input, options = {}) {
                 pathBoundary: failureFor("schema-invalid", "Skipped because schema validation failed"),
                 verifyCommands: failureFor("schema-invalid", "Skipped because schema validation failed"),
                 profileMapping: failureFor("schema-invalid", "Skipped because schema validation failed"),
+                workflow: failureFor("schema-invalid", "Skipped because schema validation failed"),
             },
             errors,
             warnings: [],
@@ -56,12 +58,15 @@ export async function validateTaskSpec(input, options = {}) {
     const pathBoundaryCheck = checkPathBoundaries(taskSpec, errors, warnings);
     const verifyCommandsCheck = checkVerifyCommands(taskSpec, errors);
     const profileMapping = resolveLoopAgentProfile(taskSpec);
+    const workflowCheck = checkWorkflow(taskSpec, errors, warnings);
+    const resolved = workflowCheck === "ok" ? resolveWorkflow(taskSpec) : undefined;
     return buildResult({
         taskId: taskSpec.id,
         featureId: taskSpec.feature_id,
         businessProfile: taskSpec.type,
         riskLevel: taskSpec.risk_level,
         loopAgentProfilePreview: profileMapping.loopAgentProfile,
+        ...(resolved ? { workflow: resolved.workflow, taskKind: resolved.taskKind } : {}),
         checks: {
             schema: "ok",
             sourceDocs: sourceDocsCheck,
@@ -70,6 +75,7 @@ export async function validateTaskSpec(input, options = {}) {
             pathBoundary: pathBoundaryCheck,
             verifyCommands: verifyCommandsCheck,
             profileMapping: "ok",
+            workflow: workflowCheck,
         },
         errors,
         warnings,
@@ -90,6 +96,8 @@ function buildResult(input) {
         riskLevel: input.riskLevel,
         complexityPreview: mapRiskLevelToComplexity(riskLevel),
         loopAgentProfilePreview: input.loopAgentProfilePreview,
+        ...(input.workflow ? { workflow: input.workflow } : {}),
+        ...(input.taskKind ? { taskKind: input.taskKind } : {}),
         checks: input.checks,
         errors: input.errors,
         warnings: input.warnings,
@@ -253,6 +261,37 @@ function checkVerifyCommands(taskSpec, errors) {
     }
     return "ok";
 }
+/**
+ * Deterministic workflow compatibility check. Surfaces migration guidance for
+ * legacy QA types without an explicit `execution.workflow`, and rejects
+ * incompatible explicit workflow/type combinations before materialize.
+ */
+function checkWorkflow(taskSpec, errors, warnings) {
+    const result = validateWorkflowCompatibility(taskSpec);
+    if (result.migrationGuidance) {
+        warnings.push({
+            code: "qa-workflow-migration-required",
+            message: result.migrationGuidance,
+            path: "execution.workflow",
+        });
+    }
+    if (result.issues.length === 0)
+        return "ok";
+    for (const issue of result.issues) {
+        errors.push({
+            layer: "schema",
+            code: issue.code,
+            message: issue.message,
+            path: issue.path,
+        });
+    }
+    return toFailure({
+        layer: "schema",
+        code: result.issues[0].code,
+        message: result.issues[0].message,
+        path: result.issues[0].path,
+    });
+}
 function getTaskSpecDir(options) {
     return options.taskSpecPath ? path.dirname(options.taskSpecPath) : undefined;
 }