@tea-agent/loop-agent 0.12.0 → 0.13.0-beta.0

package/dist/worker/pool/validation.js

@@ -1,20 +1,42 @@
 import { z } from "zod";
 import { readFile, readdir } from "node:fs/promises";
 import path from "node:path";
-import { getRunsJsonlPath, getTaskPoolRoot } from "./run-store.js";
+import { getRunsJsonlPath, getStatesRoot, } from "./run-store.js";
+import { TASK_POOL_STATE_ERROR_CODES, } from "./types.js";
 export const taskPoolRunFactSchema = z.object({
-    schemaVersion: z.literal(1), batchRunId: z.string().min(1), workerRunId: z.string().min(1), taskId: z.string().min(1), featureId: z.string().min(1),
-    status: z.enum(["succeeded", "failed", "run-error"]), recordedAt: z.string().datetime(),
+    schemaVersion: z.literal(1),
+    batchRunId: z.string().min(1),
+    workerRunId: z.string().min(1),
+    taskId: z.string().min(1),
+    featureId: z.string().min(1),
+    status: z.enum(["succeeded", "failed", "run-error"]),
+    recordedAt: z.string().datetime(),
 }).passthrough();
 export const taskPoolStateFactSchema = z.object({
-    taskId: z.string().min(1), status: z.enum(["Draft", "Ready", "Queued", "Running", "AgentCompleted", "VerificationRunning", "HumanReview", "Done", "Failed", "Blocked", "Abandoned"]), updatedAt: z.string().datetime(),
+    taskId: z.string().min(1),
+    status: z.enum([
+        "Draft",
+        "Ready",
+        "Queued",
+        "Running",
+        "AgentCompleted",
+        "VerificationRunning",
+        "HumanReview",
+        "Done",
+        "Failed",
+        "Blocked",
+        "Abandoned",
+    ]),
+    updatedAt: z.string().datetime(),
+    schemaVersion: z.union([z.literal(1), z.literal(2)]).optional(),
+    featureId: z.string().min(1).optional(),
 }).passthrough();
 export async function readValidTaskPoolRuns(repoRoot) {
     const records = [];
     const warnings = [];
     try {
         const raw = await readFile(getRunsJsonlPath(repoRoot), "utf-8");
-        for (const [index, line] of raw.split(/\r?\n/).filter(Boolean).entries())
+        for (const [index, line] of raw.split(/\r?\n/).filter(Boolean).entries()) {
             try {
                 const parsed = taskPoolRunFactSchema.safeParse(JSON.parse(line));
                 if (parsed.success)
@@ -25,6 +47,7 @@ export async function readValidTaskPoolRuns(repoRoot) {
             catch {
                 warnings.push(`Task Pool runs.jsonl line ${index + 1} is corrupt`);
             }
+        }
     }
     catch (error) {
         if (!isNotFound(error))
@@ -32,23 +55,80 @@ export async function readValidTaskPoolRuns(repoRoot) {
     }
     return { records, warnings };
 }
+/**
+ * Valid state reader for morning-report and similar consumers.
+ * - v2 feature-scoped states: included when path/content identity match.
+ * - bare taskId collisions among v2: warning, do not overwrite records.
+ * - legacy flat states: warning with migration-required code; never treated as Ready facts.
+ */
 export async function readValidTaskPoolStates(repoRoot) {
     const records = {};
     const warnings = [];
-    const stateDir = path.join(getTaskPoolRoot(repoRoot), "states");
+    const stateDir = getStatesRoot(repoRoot);
     try {
-        for (const entry of await readdir(stateDir))
-            if (entry.endsWith(".json"))
+        const entries = await readdir(stateDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name.endsWith(".json")) {
+                const entryPath = path.join(stateDir, entry.name);
                 try {
-                    const parsed = taskPoolStateFactSchema.safeParse(JSON.parse(await readFile(path.join(stateDir, entry), "utf-8")));
-                    if (parsed.success && parsed.data.taskId === entry.slice(0, -5))
-                        records[parsed.data.taskId] = parsed.data;
-                    else
-                        warnings.push(`Task Pool state is semantically invalid: ${entry}`);
+                    const parsed = taskPoolStateFactSchema.safeParse(JSON.parse(await readFile(entryPath, "utf-8")));
+                    if (!parsed.success) {
+                        warnings.push(`Task Pool state is semantically invalid: ${entry.name}`);
+                        continue;
+                    }
+                    const expectedTaskId = entry.name.slice(0, -5);
+                    if (parsed.data.taskId !== expectedTaskId) {
+                        warnings.push(`Task Pool state is semantically invalid: ${entry.name}`);
+                        continue;
+                    }
+                    warnings.push(`${TASK_POOL_STATE_ERROR_CODES.MIGRATION_REQUIRED}: legacy state ${entry.name}`);
                 }
                 catch {
-                    warnings.push(`Task Pool state is corrupt: ${entry}`);
+                    warnings.push(`Task Pool state is corrupt: ${entry.name}`);
                 }
+                continue;
+            }
+            if (!entry.isDirectory())
+                continue;
+            const featureId = entry.name;
+            const featureDir = path.join(stateDir, featureId);
+            let featureEntries;
+            try {
+                featureEntries = await readdir(featureDir);
+            }
+            catch {
+                warnings.push(`Task Pool feature state directory is unreadable: ${featureId}`);
+                continue;
+            }
+            for (const fileName of featureEntries) {
+                if (!fileName.endsWith(".json"))
+                    continue;
+                const relative = `${featureId}/${fileName}`;
+                try {
+                    const parsed = taskPoolStateFactSchema.safeParse(JSON.parse(await readFile(path.join(featureDir, fileName), "utf-8")));
+                    if (!parsed.success) {
+                        warnings.push(`Task Pool state is semantically invalid: ${relative}`);
+                        continue;
+                    }
+                    const expectedTaskId = fileName.slice(0, -5);
+                    const data = parsed.data;
+                    if (data.taskId !== expectedTaskId ||
+                        data.featureId !== featureId ||
+                        data.schemaVersion !== 2) {
+                        warnings.push(`${TASK_POOL_STATE_ERROR_CODES.PATH_MISMATCH}: ${relative}`);
+                        continue;
+                    }
+                    if (records[data.taskId]) {
+                        warnings.push(`${TASK_POOL_STATE_ERROR_CODES.IDENTITY_AMBIGUOUS}: multiple features share taskId ${data.taskId}`);
+                        continue;
+                    }
+                    records[data.taskId] = data;
+                }
+                catch {
+                    warnings.push(`Task Pool state is corrupt: ${relative}`);
+                }
+            }
+        }
     }
     catch (error) {
         if (!isNotFound(error))
@@ -56,4 +136,9 @@ export async function readValidTaskPoolStates(repoRoot) {
     }
     return { records, warnings };
 }
-function isNotFound(error) { return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT"); }
+function isNotFound(error) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

package/dist/worker/report/morning-report.js

@@ -23,7 +23,16 @@ export async function renderMorningReport(options) {
         ...(features.length === 0 ? ["- Status: no Feature Packet discovered", "- Next Action: add or locate a Feature Packet", "- Why: no shared Feature read model is available", "- Evidence: none"] : features.flatMap((feature) => {
             const why = feature.blockingItems[0]?.message ?? `${feature.summary.tasksSucceeded}/${feature.summary.tasksTotal} tasks; ${feature.summary.requiredAcCovered}/${feature.summary.requiredAcTotal} required AC`;
             const evidence = [feature.evidence.delivery, feature.evidence.closeout, feature.evidence.morningReport, feature.evidence.observeSnapshot, ...feature.blockingItems.flatMap((item) => item.evidence)].find(Boolean) ?? "none";
-            return [`### ${feature.featureId}`, "", `- Status: ${feature.status}`, `- Next Action: ${feature.nextAction?.command ?? feature.nextAction?.label ?? "none"}`, `- Why: ${why}`, `- Evidence: ${evidence}`, ""];
+            const selected = feature.planning?.selected[0];
+            const deferred = feature.planning?.deferred ?? [];
+            const blocked = feature.planning?.blocked ?? [];
+            const deferredText = deferred.length > 0
+                ? deferred.map((item) => `${item.taskId} (${item.reasonCode})`).join(", ")
+                : "none";
+            const blockedText = blocked.length > 0
+                ? blocked.map((item) => `${item.taskId} (${item.reasonCode}${item.blockedBy.length ? `; blockedBy ${item.blockedBy.join(",")}` : ""})`).join(", ")
+                : "none";
+            return [`### ${feature.featureId}`, "", `- Status: ${feature.status}`, `- Next Task: ${selected ? `${selected.taskId} (${selected.priority})` : "none"}`, `- Deferred: ${deferredText}`, `- Blocked: ${blockedText}`, `- Next Action: ${feature.nextAction?.command ?? feature.nextAction?.label ?? "none"}`, `- Why: ${why}`, `- Evidence: ${evidence}`, ""];
         })),
         "## Summary",
         "",
@@ -40,7 +49,8 @@ export async function renderMorningReport(options) {
     ];
     for (const run of runs) {
         const followUp = await followUpSummary(run, options.repoRoot);
-        lines.push(`| ${run.taskId} | ${run.status} | ${run.workerRunId} | ${run.failure?.category ?? "-"} | ${followUp ?? run.failure?.derivedFollowUpTaskId ?? "-"} | ${await artifactSummary(run)} |`);
+        const identity = `${run.featureId}/${run.taskId}`;
+        lines.push(`| ${identity} | ${run.status} | ${run.workerRunId} | ${run.failure?.category ?? "-"} | ${followUp ?? run.failure?.derivedFollowUpTaskId ?? "-"} | ${await artifactSummary(run)} |`);
     }
     if (followUps > 0) {
         lines.push("", "## Human Actions", "");

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

@@ -4,10 +4,10 @@ import path from "node:path";
 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, readAllTaskPoolStates, recordTaskPoolRun, writeTaskPoolState, } from "../pool/run-store.js";
+import { findRunByWorkerRunId, getTaskPoolRoot, readFeatureTaskPoolStates, recordTaskPoolRun, writeTaskPoolState, } from "../pool/run-store.js";
 import { runTaskSpec, } from "../run-task/run-task.js";
 import { formatDuration, noopProgressReporter, } from "../progress-reporter.js";
-import { computeReadyQueue } from "../task-graph/ready-queue.js";
+import { planReadyTasks } from "../task-graph/ready-planner.js";
 import { taskGraphSpecSchema } from "../task-graph/task-graph-schema.js";
 import { taskSpecSchema } from "../task-spec/schema.js";
 import { preflightTargetRepo } from "../preflight.js";
@@ -34,15 +34,26 @@ export async function runReadyTasks(options) {
     const startedAt = now.toISOString();
     const batchRunId = options.batchRunId ?? buildBatchRunId(now);
     const graph = await loadTaskGraph(options.featureDir);
-    const states = await readAllTaskPoolStates(options.repoRoot);
-    const readyTaskIds = computeReadyQueue(graph, toGraphState(states)).filter((taskId) => isPoolReady(states[taskId]));
-    const limitedTaskIds = readyTaskIds.slice(0, options.limit ?? readyTaskIds.length);
+    const featureId = graph.feature_id;
+    const states = await readFeatureTaskPoolStates(options.repoRoot, featureId);
+    const taskSpecs = await loadFeatureTaskSpecs(options.featureDir, graph);
+    const plan = planReadyTasks({
+        featureId,
+        graph,
+        taskSpecs,
+        states,
+        selectionLimit: options.limit ?? graph.nodes.length,
+    });
+    const limitedTaskIds = plan.selected.map((candidate) => candidate.taskId);
     const tasks = [];
     const runner = options.runTask ?? runTaskSpec;
     const progress = options.progress ?? noopProgressReporter;
     const total = limitedTaskIds.length;
     let index = 0;
     const batchStartedAt = Date.now();
+    const readyPlanPath = path.join(getTaskPoolRoot(options.repoRoot), "artifacts", batchRunId, "ready-plan.json");
+    await mkdir(path.dirname(readyPlanPath), { recursive: true });
+    await writeFile(readyPlanPath, `${JSON.stringify(plan, null, 2)}\n`, "utf-8");
     emit(progress, {
         type: "readyQueue.computed",
         source: "worker",
@@ -61,7 +72,10 @@ export async function runReadyTasks(options) {
         index += 1;
         const node = graph.nodes.find((candidate) => candidate.id === taskId);
         const taskSpecPath = path.join(options.featureDir, "tasks", node?.task ?? `${taskId}.yaml`);
-        const taskSpec = await loadTaskSpec(taskSpecPath);
+        const taskSpec = taskSpecs.get(taskId) ?? await loadTaskSpec(taskSpecPath);
+        if (taskSpec.feature_id !== featureId) {
+            throw new Error(`task ${taskId} feature_id ${taskSpec.feature_id} does not match graph feature_id ${featureId}`);
+        }
         const retryOfWorkerRunId = states[taskId]?.retryOfWorkerRunId;
         let workerRunId = retryOfWorkerRunId
             ? buildRetryWorkerRunId(taskId, retryOfWorkerRunId, now)
@@ -69,14 +83,14 @@ export async function runReadyTasks(options) {
                 buildStableWorkerRunId(taskId, taskSpec, now, controllerIdentity);
         if (workerRunId) {
             let existing = await findRunByWorkerRunId(options.repoRoot, workerRunId);
-            if (existing && !controllerRunCanBeReused(existing, controllerIdentity)) {
+            if (existing && !runCanBeReused(existing, featureId, taskId, controllerIdentity)) {
                 workerRunId = buildControllerScopedWorkerRunId(workerRunId, controllerIdentity);
                 existing = await findRunByWorkerRunId(options.repoRoot, workerRunId);
-                if (existing && !controllerRunCanBeReused(existing, controllerIdentity)) {
-                    throw new Error(`workerRunId collision has incompatible controller identity: ${workerRunId}`);
+                if (existing && !runCanBeReused(existing, featureId, taskId, controllerIdentity)) {
+                    throw new Error(`workerRunId collision has incompatible feature/controller identity: ${workerRunId}`);
                 }
             }
-            if (existing) {
+            if (existing && runCanBeReused(existing, featureId, taskId, controllerIdentity)) {
                 progress.task(`task ${index}/${total} ${taskId}: reuse existing run ${workerRunId}`);
                 emit(progress, {
                     type: "task.reused",
@@ -112,6 +126,8 @@ export async function runReadyTasks(options) {
         let result;
         try {
             await writeTaskPoolState(options.repoRoot, {
+                schemaVersion: 2,
+                featureId,
                 taskId,
                 status: "Running",
                 updatedAt: new Date().toISOString(),
@@ -277,6 +293,12 @@ export async function runReadyTasks(options) {
         summary,
         tasks,
         batchRunPath,
+        readyPlanPath,
+        selectedTaskIds: limitedTaskIds,
+        deferredTaskIds: plan.deferred.map((candidate) => candidate.taskId),
+        orderingPolicy: plan.orderingPolicy,
+        selectionLimit: plan.selectionLimit,
+        effectiveConcurrency: plan.effectiveConcurrency,
         ...(controllerIdentity ? { controllerIdentity } : {}),
     };
     await mkdir(path.dirname(batchRunPath), { recursive: true });
@@ -345,7 +367,9 @@ function buildControllerScopedWorkerRunId(baseWorkerRunId, controllerIdentity) {
         .slice(0, 10);
     return `${baseWorkerRunId}-controller-${hash}`;
 }
-function controllerRunCanBeReused(existing, controllerIdentity) {
+function runCanBeReused(existing, featureId, taskId, controllerIdentity) {
+    if (existing.featureId !== featureId || existing.taskId !== taskId)
+        return false;
     if (!existing.controllerIdentity && !controllerIdentity)
         return true;
     return controllerIdentitiesMatch(existing.controllerIdentity, controllerIdentity);
@@ -370,22 +394,13 @@ async function loadTaskGraph(featureDir) {
 async function loadTaskSpec(taskSpecPath) {
     return taskSpecSchema.parse(YAML.parse(await readFile(taskSpecPath, "utf-8")));
 }
-function toGraphState(states) {
-    const graphState = {};
-    for (const [taskId, state] of Object.entries(states)) {
-        if (state.status === "Done")
-            graphState[taskId] = "completed";
-        if (state.status === "Running" || state.status === "Queued")
-            graphState[taskId] = "running";
-        if (state.status === "Failed")
-            graphState[taskId] = "failed";
-        if (state.status === "Blocked")
-            graphState[taskId] = "blocked";
+async function loadFeatureTaskSpecs(featureDir, graph) {
+    const specs = new Map();
+    for (const node of graph.nodes) {
+        const taskSpec = await loadTaskSpec(path.join(featureDir, "tasks", node.task ?? `${node.id}.yaml`));
+        specs.set(node.id, taskSpec);
     }
-    return graphState;
-}
-function isPoolReady(state) {
-    return !state || state.status === "Ready";
+    return specs;
 }
 function summarize(tasks) {
     return {

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

@@ -0,0 +1,136 @@
+const OWN_STATUS_REASON = {
+    Draft: "task-draft",
+    Queued: "task-queued",
+    Running: "task-running",
+    AgentCompleted: "task-agent-completed",
+    VerificationRunning: "task-verification-running",
+    HumanReview: "task-human-review",
+    Done: "task-done",
+    Failed: "task-failed",
+    Blocked: "task-blocked",
+    Abandoned: "task-abandoned",
+};
+/** Contract severity: failed > blocked > not-completed > missing-state. */
+function dependencyReason(unmet) {
+    if (unmet.some((item) => item.state === "Failed"))
+        return "dependency-failed";
+    if (unmet.some((item) => item.state === "Blocked"))
+        return "dependency-blocked";
+    if (unmet.some((item) => item.state !== undefined))
+        return "dependency-not-completed";
+    return "dependency-missing-state";
+}
+function ownReason(status) {
+    if (status === "Ready")
+        return undefined;
+    return OWN_STATUS_REASON[status] ?? "task-state-invalid";
+}
+export function planReadyTasks(input) {
+    if (!Number.isInteger(input.selectionLimit) || input.selectionLimit < 1) {
+        throw new Error("selectionLimit must be a positive integer");
+    }
+    const eligible = [];
+    const blocked = [];
+    for (const [graphIndex, node] of input.graph.nodes.entries()) {
+        const spec = input.taskSpecs.get(node.id);
+        if (!spec) {
+            blocked.push({
+                featureId: input.featureId,
+                taskId: node.id,
+                reasonCode: "task-spec-missing",
+                reason: "TaskSpec is missing",
+                blockedBy: [],
+            });
+            continue;
+        }
+        if (spec.id !== node.id || spec.type !== node.type || !same(spec.depends_on, node.depends_on)) {
+            blocked.push({
+                featureId: input.featureId,
+                taskId: node.id,
+                priority: spec.priority,
+                reasonCode: "task-spec-mismatch",
+                reason: "TaskSpec does not match task graph",
+                blockedBy: [],
+            });
+            continue;
+        }
+        const state = input.states[node.id];
+        if (state) {
+            const own = ownReason(state.status);
+            if (own) {
+                blocked.push({
+                    featureId: input.featureId,
+                    taskId: node.id,
+                    priority: spec.priority,
+                    reasonCode: own,
+                    reason: own === "task-state-invalid"
+                        ? `task status is invalid: ${String(state.status)}`
+                        : `task status is ${state.status}`,
+                    blockedBy: [],
+                    currentStatus: state.status,
+                });
+                continue;
+            }
+        }
+        const deps = node.depends_on.map((id) => ({ id, state: input.states[id]?.status }));
+        const unmet = deps.filter(({ state: depState }) => depState !== "Done");
+        if (unmet.length) {
+            blocked.push({
+                featureId: input.featureId,
+                taskId: node.id,
+                priority: spec.priority,
+                reasonCode: dependencyReason(unmet),
+                reason: "dependencies are not completed",
+                blockedBy: unmet.map((item) => item.id),
+            });
+            continue;
+        }
+        eligible.push({
+            featureId: input.featureId,
+            taskId: node.id,
+            title: spec.title,
+            type: spec.type,
+            priority: spec.priority,
+            riskLevel: spec.risk_level,
+            graphIndex,
+            reason: "dependencies-satisfied",
+        });
+    }
+    eligible.sort((a, b) => priority(a.priority) - priority(b.priority) ||
+        a.graphIndex - b.graphIndex ||
+        ascii(a.taskId, b.taskId));
+    const selected = eligible.slice(0, input.selectionLimit);
+    const deferred = eligible.slice(input.selectionLimit).map((candidate) => ({
+        ...candidate,
+        reasonCode: "selection-limit",
+        selectedAhead: selected.map((item) => item.taskId),
+    }));
+    return {
+        schemaVersion: 1,
+        featureId: input.featureId,
+        executionMode: "serial",
+        effectiveConcurrency: 1,
+        selectionLimit: input.selectionLimit,
+        orderingPolicy: ["priority:P0>P1>P2>P3", "graph-order", "task-id"],
+        eligible,
+        blocked,
+        selected,
+        deferred,
+        summary: {
+            total: input.graph.nodes.length,
+            eligible: eligible.length,
+            blocked: blocked.length,
+            selected: selected.length,
+            deferred: deferred.length,
+        },
+    };
+}
+function priority(value) {
+    return { P0: 0, P1: 1, P2: 2, P3: 3 }[value];
+}
+function ascii(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function same(a, b) {
+    return a.length === b.length && a.every((value, index) => value === b[index]);
+}

package/dist/workflows/dag/backend-test-analysis-contract.js

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { writeDagRunJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
+export const BACKEND_TEST_ANALYSIS_SCHEMA_ID = "backend-test-analysis-v1";
+const sourceRefSchema = z.string().min(1);
+const fieldSchema = z.object({
+    name: z.string().min(1),
+    type: z.string().min(1).optional(),
+    required: z.boolean().optional(),
+    description: z.string().optional(),
+}).strict();
+const errorCaseSchema = z.object({
+    status: z.number().int().min(400).max(599).optional(),
+    code: z.string().min(1).optional(),
+    messageField: z.string().min(1).optional(),
+    description: z.string().min(1),
+}).strict();
+export const backendTestAnalysisContractSchema = z.object({
+    schemaVersion: z.literal(1),
+    sourceBinding: z.object({
+        taskId: z.string().min(1),
+        requirementPath: z.string().min(1),
+        requirementSha256: z.string().regex(/^[a-f0-9]{64}$/),
+        referencePaths: z.array(z.string().min(1)),
+        requirementIds: z.array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/)),
+    }).strict(),
+    acceptanceCriteria: z.array(z.object({
+        id: z.string().regex(/^AC-[A-Z0-9]+(?:-[A-Z0-9]+)*$/),
+        text: z.string().min(1),
+        sourceRef: sourceRefSchema,
+    }).strict()),
+    endpoints: z.array(z.object({
+        id: z.string().min(1),
+        method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]),
+        path: z.string().startsWith("/"),
+        requestFields: z.array(fieldSchema),
+        responseFields: z.array(fieldSchema),
+        successStatuses: z.array(z.number().int().min(100).max(399)),
+        errorCases: z.array(errorCaseSchema),
+    }).strict()),
+    dataModels: z.array(z.object({ id: z.string().min(1), description: z.string().min(1), sourceRef: sourceRefSchema }).strict()),
+    businessRules: z.array(z.object({ id: z.string().min(1), text: z.string().min(1), sourceRef: sourceRefSchema }).strict()),
+    stateTransitions: z.array(z.object({ from: z.string().min(1), to: z.string().min(1), trigger: z.string().min(1), sourceRef: sourceRefSchema }).strict()),
+    boundaryConstraints: z.array(z.object({ field: z.string().min(1), constraint: z.string().min(1), sourceRef: sourceRefSchema }).strict()),
+    externalDependencies: z.array(z.object({ name: z.string().min(1), description: z.string().min(1), sourceRef: sourceRefSchema.optional() }).strict()),
+    risks: z.array(z.object({ description: z.string().min(1), sourceRef: sourceRefSchema.optional() }).strict()),
+    evidenceGaps: z.array(z.object({ description: z.string().min(1), requirementId: z.string().optional(), sourceRef: sourceRefSchema.optional() }).strict()),
+}).strict();
+const SECRET_KEY = /(?:password|passwd|secret|token|api[_-]?key|private[_-]?key|credential|authorization)/i;
+const SECRET_VALUE = /(?:-----BEGIN [A-Z ]*PRIVATE KEY-----|\b(?:sk|ghp|github_pat|xox[baprs]|AKIA)[-_A-Za-z0-9]{12,}\b)/;
+function secretIssues(value, at = "$", issues = []) {
+    if (typeof value === "string" && SECRET_VALUE.test(value))
+        issues.push(`${at}: secret-like value is forbidden`);
+    if (Array.isArray(value))
+        value.forEach((item, index) => secretIssues(item, `${at}[${index}]`, issues));
+    else if (value && typeof value === "object") {
+        for (const [key, child] of Object.entries(value)) {
+            if (SECRET_KEY.test(key))
+                issues.push(`${at}.${key}: secret-shaped field name is forbidden`);
+            secretIssues(child, `${at}.${key}`, issues);
+        }
+    }
+    return issues;
+}
+export function extractStrictJsonObject(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith("{") && trimmed.endsWith("}"))
+        return JSON.parse(trimmed);
+    const blocks = [...trimmed.matchAll(/```json\s*\n([\s\S]*?)\n```/gi)];
+    if (blocks.length !== 1 || trimmed.replace(blocks[0][0], "").trim()) {
+        throw new Error("analysis output must be one pure JSON object or one fenced json block with no trailing text");
+    }
+    return JSON.parse(blocks[0][1]);
+}
+function assertSourceBinding(contract, binding) {
+    const requirement = binding.sources.find((source) => source.kind === "requirement");
+    const references = binding.sources.filter((source) => source.kind === "reference").map((source) => source.path).sort();
+    const actualReferences = [...contract.sourceBinding.referencePaths].sort();
+    if (!requirement || contract.sourceBinding.taskId !== binding.taskId || contract.sourceBinding.requirementPath !== requirement.path || contract.sourceBinding.requirementSha256 !== requirement.sha256) {
+        throw new Error("analysis source binding does not match DAG requirement source");
+    }
+    if (JSON.stringify(actualReferences) !== JSON.stringify(references))
+        throw new Error("analysis referencePaths do not match DAG source binding");
+    if (JSON.stringify(contract.sourceBinding.requirementIds) !== JSON.stringify(binding.requirementIds))
+        throw new Error("analysis requirementIds do not match DAG source binding");
+    const explicitAc = binding.requirementIds.filter((id) => id.startsWith("AC-"));
+    const contractAc = contract.acceptanceCriteria.map((item) => item.id);
+    for (const id of explicitAc)
+        if (!contractAc.includes(id) && !contract.evidenceGaps.some((gap) => gap.requirementId === id))
+            throw new Error(`analysis contract does not cover explicit acceptance criterion ${id}`);
+}
+export async function materializeBackendTestAnalysisContract(input) {
+    if (!input.sourceBinding)
+        throw new Error("backend-test analysis gate requires DAG sourceBinding");
+    if (!/^[a-z0-9][a-z0-9._-]*\.json$/.test(input.artifactName) || !/^[a-z0-9][a-z0-9._-]*$/.test(input.outputDir))
+        throw new Error("unsafe structured artifact path");
+    const nodePath = path.join(input.runDir, `${input.fromNodeId}.json`);
+    const record = JSON.parse(await readFile(nodePath, "utf8"));
+    const raw = record.assistantText?.trim() || record.stdout?.trim() || "";
+    let parsed;
+    try {
+        parsed = extractStrictJsonObject(raw);
+    }
+    catch (error) {
+        throw new Error(`invalid-output: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const secrets = secretIssues(parsed);
+    if (secrets.length)
+        throw new Error(`invalid-output: ${secrets.join("; ")}`);
+    const result = backendTestAnalysisContractSchema.safeParse(parsed);
+    if (!result.success)
+        throw new Error(`invalid-output: ${result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`);
+    assertSourceBinding(result.data, input.sourceBinding);
+    const relativePath = path.posix.join(input.outputDir, input.artifactName);
+    const artifactPath = await writeDagRunJsonArtifact(input.runDir, relativePath, result.data);
+    const normalized = `${JSON.stringify(result.data, null, 2)}\n`;
+    return { path: artifactPath, sha256: createHash("sha256").update(normalized).digest("hex"), schemaId: BACKEND_TEST_ANALYSIS_SCHEMA_ID };
+}