@tea-agent/loop-agent 0.1.0-fe-test.0

package/dist/worker/feature/types.js

@@ -0,0 +1 @@
+export {};

package/dist/worker/follow-up/approve.js

@@ -0,0 +1,273 @@
+import { randomUUID } from "node:crypto";
+import { cp, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+import { appendTaskPoolEvent, getEventsJsonlPath, getTaskStatePath, readTaskPoolState, writeTaskPoolState } from "../pool/run-store.js";
+import { taskGraphSpecSchema } from "../task-graph/task-graph-schema.js";
+import { validateFeatureTaskGraph } from "../task-graph/validate.js";
+import { taskSpecSchema } from "../task-spec/schema.js";
+import { assertSafeRuntimeId, assertSafeTaskFile, followUpDir } from "./paths.js";
+import { followUpApprovalSchema, followUpDraftSchema, followUpEvidenceSchema } from "./schema.js";
+import { cleanupPath, hashFeaturePacket, readFollowUpIndex, repoRef, resolveRepoFile, sha256File, withFollowUpLock, writeFollowUpIndex, writeJsonAtomic, writeTextAtomic } from "./store.js";
+export async function approveFollowUp(input) {
+    if (!input.owner.trim())
+        throw new Error("approve-followup requires a non-empty owner");
+    assertSafeRuntimeId(input.followUpId, "followUpId");
+    const repoRoot = path.resolve(input.repoRoot);
+    const featureDir = path.resolve(input.featureDir);
+    const graphPath = path.join(featureDir, "tasks", "task-graph.yaml");
+    const graph = taskGraphSpecSchema.parse(YAML.parse(await readFile(graphPath, "utf-8")));
+    const featureId = graph.feature_id;
+    assertSafeRuntimeId(featureId, "featureId");
+    if (input.dryRun)
+        return prepareApproval({ ...input, repoRoot, featureDir, featureId });
+    return withFollowUpLock(repoRoot, featureId, async () => executeApproval({ ...input, repoRoot, featureDir, featureId }));
+}
+async function prepareApproval(input) {
+    const loaded = await loadApprovalInputs(input);
+    if (loaded.existingApproval)
+        return resultFromApproval(loaded.existingApproval, input.repoRoot, loaded.approvalPath, true);
+    await assertApprovalPreconditions(loaded);
+    return {
+        schemaVersion: 1,
+        status: "planned",
+        idempotent: false,
+        followUpId: loaded.draft.follow_up_id,
+        proposedTaskId: loaded.draft.proposed_task_id,
+        taskSpecPath: repoRef(input.repoRoot, loaded.taskSpecPath),
+        graphPath: repoRef(input.repoRoot, loaded.graphPath),
+        statePath: repoRef(input.repoRoot, loaded.statePath),
+        approvalPath: repoRef(input.repoRoot, loaded.approvalPath),
+        eventPath: repoRef(input.repoRoot, getEventsJsonlPath(input.repoRoot)),
+    };
+}
+async function executeApproval(input) {
+    const loaded = await loadApprovalInputs(input);
+    if (loaded.existingApproval)
+        return resultFromApproval(loaded.existingApproval, input.repoRoot, loaded.approvalPath, true);
+    await assertApprovalPreconditions(loaded);
+    const beforeGraphText = await readFile(loaded.graphPath, "utf-8");
+    const beforeGraphHash = await sha256File(loaded.graphPath);
+    const stageDir = path.join(path.dirname(input.featureDir), `.followup-stage-${input.followUpId}-${randomUUID()}`);
+    await cp(input.featureDir, stageDir, { recursive: true });
+    const changedFiles = new Map();
+    let stateWritten = false;
+    let approvalWritten = false;
+    let indexWritten = false;
+    const originalIndex = await readFollowUpIndex(input.repoRoot, input.featureId);
+    try {
+        const stagedGraphPath = path.join(stageDir, "tasks", "task-graph.yaml");
+        const graph = taskGraphSpecSchema.parse(YAML.parse(await readFile(stagedGraphPath, "utf-8")));
+        graph.nodes.push(loaded.draft.proposed_graph_patch.add_node);
+        for (const rewire of loaded.draft.proposed_graph_patch.rewire_dependents) {
+            const node = graph.nodes.find((candidate) => candidate.id === rewire.task_id);
+            if (!node)
+                throw new Error(`rewire target is missing: ${rewire.task_id}`);
+            assertSafeTaskFile(node.task, `rewire task file for ${node.id}`);
+            node.depends_on = node.depends_on.map((dependency) => dependency === rewire.from_dependency ? rewire.to_dependency : dependency);
+            const stagedTaskPath = path.join(stageDir, "tasks", node.task);
+            const task = taskSpecSchema.parse(YAML.parse(await readFile(stagedTaskPath, "utf-8")));
+            task.depends_on = [...node.depends_on];
+            await writeTextAtomic(stagedTaskPath, YAML.stringify(task));
+        }
+        await writeTextAtomic(path.join(stageDir, "tasks", `${loaded.draft.proposed_task_id}.yaml`), YAML.stringify(loaded.draft.proposed_task_spec));
+        await writeTextAtomic(stagedGraphPath, YAML.stringify(graph));
+        const validation = await validateFeatureTaskGraph(stageDir);
+        if (!validation.ok)
+            throw new Error(`staged Feature validation failed: ${validation.errors.map((error) => error.code).join(", ")}`);
+        const afterGraphHash = await sha256File(stagedGraphPath);
+        const stagedRelativeFiles = [
+            path.join("tasks", `${loaded.draft.proposed_task_id}.yaml`),
+            "tasks/task-graph.yaml",
+            ...loaded.draft.proposed_graph_patch.rewire_dependents.map((rewire) => {
+                const node = graph.nodes.find((candidate) => candidate.id === rewire.task_id);
+                return path.join("tasks", node.task);
+            }),
+        ];
+        for (const relative of [...new Set(stagedRelativeFiles)]) {
+            const target = path.join(input.featureDir, relative);
+            changedFiles.set(target, await readOptional(target));
+            const temp = path.join(path.dirname(target), `.${path.basename(target)}.${randomUUID()}.tmp`);
+            try {
+                await writeFile(temp, await readFile(path.join(stageDir, relative)));
+                await input.faultInjector?.("before-packet-rename", relative);
+                await rename(temp, target);
+            }
+            finally {
+                await unlink(temp).catch(() => { });
+            }
+        }
+        await input.faultInjector?.("before-state-write");
+        await writeTaskPoolState(input.repoRoot, {
+            schemaVersion: 2,
+            featureId: input.featureId,
+            taskId: loaded.draft.proposed_task_id,
+            status: "Ready",
+            updatedAt: (input.now ?? new Date()).toISOString(),
+        });
+        stateWritten = true;
+        const approvedAt = (input.now ?? new Date()).toISOString();
+        const approval = {
+            schemaVersion: 1,
+            followUpId: loaded.draft.follow_up_id,
+            proposedTaskId: loaded.draft.proposed_task_id,
+            owner: input.owner,
+            approvedAt,
+            draftHash: await sha256File(loaded.draftPath),
+            beforeGraphHash,
+            afterGraphHash,
+            taskSpecPath: repoRef(input.repoRoot, loaded.taskSpecPath),
+            graphPath: repoRef(input.repoRoot, loaded.graphPath),
+            statePath: repoRef(input.repoRoot, loaded.statePath),
+            eventPath: repoRef(input.repoRoot, getEventsJsonlPath(input.repoRoot)),
+        };
+        followUpApprovalSchema.parse(approval);
+        await input.faultInjector?.("before-approval-write");
+        await writeJsonAtomic(loaded.approvalPath, approval);
+        approvalWritten = true;
+        const index = structuredClone(originalIndex);
+        const entry = index.entries.find((candidate) => candidate.followUpId === input.followUpId);
+        entry.status = "Approved";
+        entry.approvalPath = repoRef(input.repoRoot, loaded.approvalPath);
+        entry.approvedAt = approvedAt;
+        await input.faultInjector?.("before-index-write");
+        await writeFollowUpIndex(input.repoRoot, index);
+        indexWritten = true;
+        await input.faultInjector?.("before-event-append");
+        await appendTaskPoolEvent(input.repoRoot, {
+            schemaVersion: 1,
+            at: approvedAt,
+            type: "follow-up-approved",
+            featureId: input.featureId,
+            followUpId: input.followUpId,
+            proposedTaskId: loaded.draft.proposed_task_id,
+            parentTaskId: loaded.draft.lineage.parent_task_id,
+            workerRunId: loaded.draft.generated_from.worker_run_id,
+            owner: input.owner,
+            draftHash: approval.draftHash,
+            beforeGraphHash,
+            afterGraphHash,
+            artifactRefs: [repoRef(input.repoRoot, loaded.draftPath), repoRef(input.repoRoot, loaded.approvalPath)],
+        });
+        return resultFromApproval(approval, input.repoRoot, loaded.approvalPath, false);
+    }
+    catch (error) {
+        if (indexWritten)
+            await writeFollowUpIndex(input.repoRoot, originalIndex).catch(() => { });
+        if (approvalWritten)
+            await unlink(loaded.approvalPath).catch(() => { });
+        if (stateWritten)
+            await unlink(loaded.statePath).catch(() => { });
+        for (const [target, original] of [...changedFiles.entries()].reverse()) {
+            if (original === undefined)
+                await unlink(target).catch(() => { });
+            else
+                await writeTextAtomic(target, original).catch(() => { });
+        }
+        await writeTextAtomic(loaded.graphPath, beforeGraphText).catch(() => { });
+        throw error;
+    }
+    finally {
+        await cleanupPath(stageDir);
+    }
+}
+async function loadApprovalInputs(input) {
+    const index = await readFollowUpIndex(input.repoRoot, input.featureId);
+    const entry = index.entries.find((candidate) => candidate.followUpId === input.followUpId);
+    if (!entry)
+        throw new Error(`follow-up not found: ${input.followUpId}`);
+    if (entry.kind !== "TaskDraft" || !entry.proposedTaskId)
+        throw new Error(`follow-up is not an approvable TaskDraft: ${entry.kind}`);
+    const draftPath = await resolveRepoFile(input.repoRoot, entry.draftPath);
+    const approvalPath = path.join(followUpDir(input.repoRoot, input.featureId, input.followUpId), "approval.json");
+    const evidencePath = path.join(followUpDir(input.repoRoot, input.featureId, input.followUpId), "evidence.json");
+    let existingApproval;
+    try {
+        existingApproval = followUpApprovalSchema.parse(JSON.parse(await readFile(approvalPath, "utf-8")));
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            throw error;
+    }
+    const draft = followUpDraftSchema.parse(YAML.parse(await readFile(draftPath, "utf-8")));
+    for (const [value, label] of [
+        [draft.follow_up_id, "draft.followUpId"],
+        [draft.proposed_task_id, "draft.proposedTaskId"],
+        [draft.generated_from.feature_id, "draft.featureId"],
+        [draft.generated_from.task_id, "draft.taskId"],
+        [draft.lineage.parent_task_id, "draft.parentTaskId"],
+        ...draft.proposed_graph_patch.rewire_dependents.flatMap((rewire) => [[rewire.task_id, "rewire.taskId"], [rewire.from_dependency, "rewire.fromDependency"], [rewire.to_dependency, "rewire.toDependency"]]),
+    ])
+        assertSafeRuntimeId(value, label);
+    return {
+        entry, draft, draftPath, evidencePath, approvalPath, existingApproval,
+        taskSpecPath: path.join(input.featureDir, "tasks", `${draft.proposed_task_id}.yaml`),
+        graphPath: path.join(input.featureDir, "tasks", "task-graph.yaml"),
+        statePath: getTaskStatePath(input.repoRoot, { featureId: input.featureId, taskId: draft.proposed_task_id }),
+        featureId: input.featureId,
+        featureDir: input.featureDir,
+        repoRoot: input.repoRoot,
+    };
+}
+async function assertApprovalPreconditions(loaded) {
+    if (loaded.entry.status !== "Draft" || loaded.draft.status !== "Draft")
+        throw new Error(`follow-up is not Draft: ${loaded.entry.status}`);
+    if (loaded.draft.generated_from.feature_id !== loaded.featureId)
+        throw new Error("follow-up Feature lineage does not match its index");
+    if (await sha256File(loaded.draftPath) !== loaded.entry.draftHash)
+        throw new Error("follow-up draft hash changed; regenerate and review the draft");
+    const evidenceHash = await sha256File(loaded.evidencePath);
+    if (evidenceHash !== loaded.entry.evidenceHash || evidenceHash !== loaded.draft.evidence_manifest_hash)
+        throw new Error("follow-up evidence manifest changed; regenerate and review the draft");
+    const evidence = followUpEvidenceSchema.parse(JSON.parse(await readFile(loaded.evidencePath, "utf-8")));
+    if (evidence.followUpId !== loaded.draft.follow_up_id)
+        throw new Error("follow-up evidence lineage does not match the draft");
+    if (evidence.evidence.map((item) => item.ref).join("\0") !== loaded.draft.evidence_refs.join("\0"))
+        throw new Error("follow-up evidence refs do not match the draft");
+    for (const item of evidence.evidence) {
+        const evidencePath = await realpath(path.resolve(loaded.repoRoot, item.ref));
+        const canonicalRoot = await realpath(loaded.repoRoot);
+        const relative = path.relative(canonicalRoot, evidencePath).split(path.sep).join("/");
+        if (relative !== item.ref || relative.startsWith("..") || path.isAbsolute(relative) || await sha256File(evidencePath) !== item.sha256) {
+            throw new Error(`follow-up evidence changed or escaped the repo: ${item.ref}`);
+        }
+    }
+    if (await hashFeaturePacket(loaded.featureDir) !== loaded.draft.feature_packet_hash)
+        throw new Error("Feature Packet baseline changed; regenerate the follow-up draft");
+    if (await readOptional(loaded.taskSpecPath) !== undefined)
+        throw new Error(`proposed TaskSpec already exists: ${loaded.draft.proposed_task_id}`);
+    const graph = taskGraphSpecSchema.parse(YAML.parse(await readFile(loaded.graphPath, "utf-8")));
+    if (graph.nodes.some((node) => node.id === loaded.draft.proposed_task_id))
+        throw new Error(`proposed graph node already exists: ${loaded.draft.proposed_task_id}`);
+    if (await readTaskPoolState(loaded.repoRoot, { featureId: loaded.featureId, taskId: loaded.draft.proposed_task_id })) {
+        throw new Error(`Task Pool state already exists: ${loaded.draft.proposed_task_id}`);
+    }
+}
+function resultFromApproval(approval, repoRoot, approvalPath, idempotent) {
+    return {
+        schemaVersion: 1,
+        status: "approved",
+        idempotent,
+        followUpId: approval.followUpId,
+        proposedTaskId: approval.proposedTaskId,
+        taskSpecPath: approval.taskSpecPath,
+        graphPath: approval.graphPath,
+        statePath: approval.statePath,
+        approvalPath: repoRef(repoRoot, approvalPath),
+        eventPath: approval.eventPath,
+        approval,
+    };
+}
+async function readOptional(filePath) {
+    try {
+        return await readFile(filePath, "utf-8");
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw error;
+    }
+}
+function isNotFound(error) {
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}

package/dist/worker/follow-up/factory.js

@@ -0,0 +1,234 @@
+import { access, mkdir, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+import { findRunByWorkerRunId, getRunsJsonlPath, readJsonlFile } from "../pool/run-store.js";
+import { taskGraphSpecSchema } from "../task-graph/task-graph-schema.js";
+import { taskSpecSchema } from "../task-spec/schema.js";
+import { assertSafeRuntimeId, assertSafeTaskFile, followUpDir } from "./paths.js";
+import { followUpActionCardSchema, followUpDraftSchema, followUpEvidenceSchema } from "./schema.js";
+import { cleanupPath, hashFeaturePacket, readFollowUpIndex, repoRef, resolveRepoFile, sha256File, withFollowUpLock, writeFollowUpIndex, writeJsonAtomic, writeTextAtomic } from "./store.js";
+import { resolveFollowUpPolicy } from "./policy.js";
+export async function draftProductBugFollowUp(input) {
+    const result = await draftFollowUpDecision(input, true);
+    if (result.kind !== "TaskDraft")
+        throw new Error("ProductBug must create a TaskDraft");
+    return result;
+}
+export async function draftFollowUpDecision(input, productBugOnly = false) {
+    const repoRoot = path.resolve(input.repoRoot);
+    const featureDir = path.resolve(input.featureDir);
+    assertSafeRuntimeId(input.taskId, "taskId");
+    const run = await findRunByWorkerRunId(repoRoot, input.workerRunId);
+    if (!run || run.taskId !== input.taskId)
+        throw new Error(`failed run not found for ${input.taskId}/${input.workerRunId}`);
+    if (run.status === "succeeded")
+        throw new Error("cannot draft follow-up from a successful run");
+    const category = run.failure?.category;
+    if (!category)
+        throw new Error("failed run has no failure category");
+    if (productBugOnly && category !== "ProductBug")
+        throw new Error(`ProductBug draft required, found ${category}`);
+    const allRuns = await readJsonlFile(getRunsJsonlPath(repoRoot));
+    const policy = resolveFollowUpPolicy({
+        category,
+        recentTaskRuns: allRuns.filter((candidate) => candidate.featureId === run.featureId && candidate.taskId === input.taskId),
+    });
+    const graphPath = path.join(featureDir, "tasks", "task-graph.yaml");
+    const graph = taskGraphSpecSchema.parse(YAML.parse(await readFile(graphPath, "utf-8")));
+    assertSafeRuntimeId(graph.feature_id, "featureId");
+    assertSafeRuntimeId(run.featureId, "run.featureId");
+    if (run.featureId !== graph.feature_id)
+        throw new Error(`failed run belongs to ${run.featureId}, not ${graph.feature_id}`);
+    return withFollowUpLock(repoRoot, run.featureId, async () => {
+        const index = await readFollowUpIndex(repoRoot, run.featureId);
+        const dedupeKey = `${run.featureId}:${input.taskId}:${input.workerRunId}:${category}`;
+        const existing = index.entries.find((entry) => entry.dedupeKey === dedupeKey);
+        if (existing) {
+            const safeDraftPath = await resolveRepoFile(repoRoot, existing.draftPath);
+            const raw = YAML.parse(await readFile(safeDraftPath, "utf-8"));
+            if (existing.kind === "ActionCard") {
+                return actionResult(repoRoot, existing.followUpId, path.resolve(repoRoot, existing.draftPath), dedupeKey, followUpActionCardSchema.parse(raw), false);
+            }
+            if (!existing.proposedTaskId)
+                throw new Error("TaskDraft index is missing proposedTaskId");
+            return result(repoRoot, existing.followUpId, existing.proposedTaskId, path.resolve(repoRoot, existing.draftPath), dedupeKey, followUpDraftSchema.parse(raw), false);
+        }
+        if (graph.feature_id !== run.featureId)
+            throw new Error("Feature graph id does not match failed run");
+        const parentNode = graph.nodes.find((node) => node.id === input.taskId);
+        if (!parentNode)
+            throw new Error(`parent task is missing from graph: ${input.taskId}`);
+        assertSafeTaskFile(parentNode.task, "parent task file");
+        for (const node of graph.nodes.filter((candidate) => candidate.depends_on.includes(input.taskId))) {
+            assertSafeTaskFile(node.task, `rewire task file for ${node.id}`);
+        }
+        const sequence = nextSequence(index.entries.filter((entry) => entry.parentTaskId === input.taskId).map((entry) => entry.followUpId));
+        const suffix = String(sequence).padStart(2, "0");
+        const followUpId = `FU-${input.taskId}-${suffix}`;
+        assertSafeRuntimeId(followUpId, "followUpId");
+        const evidenceRefs = await Promise.all([
+            run.runRecordPath,
+            run.dagPath,
+            ...Object.values(run.failureArtifacts ?? {}),
+        ].filter((value) => Boolean(value)).map((value) => canonicalEvidenceRef(repoRoot, value)));
+        if (evidenceRefs.length === 0)
+            throw new Error("failed run has no canonical evidence refs");
+        const evidence = followUpEvidenceSchema.parse({
+            schemaVersion: 1,
+            followUpId,
+            evidence: await Promise.all(evidenceRefs.map(async (ref) => ({ ref, sha256: await sha256File(path.resolve(repoRoot, ref)) }))),
+        });
+        const directory = followUpDir(repoRoot, run.featureId, followUpId);
+        if (await exists(directory))
+            throw new Error(`follow-up id collision: ${followUpId}`);
+        await mkdir(directory, { recursive: false });
+        const draftPath = path.join(directory, "draft.yaml");
+        const evidencePath = path.join(directory, "evidence.json");
+        try {
+            await writeJsonAtomic(evidencePath, evidence);
+            const evidenceHash = await sha256File(evidencePath);
+            for (const entry of index.entries) {
+                if (entry.parentTaskId === input.taskId && (entry.status === "Draft" || entry.status === "ActionRequired"))
+                    entry.status = "Superseded";
+            }
+            if (policy.kind === "action-card") {
+                const actionCard = followUpActionCardSchema.parse({
+                    schema_version: 1,
+                    follow_up_id: followUpId,
+                    status: "ActionRequired",
+                    generated_from: { feature_id: run.featureId, task_id: input.taskId, worker_run_id: input.workerRunId, failure_category: category },
+                    action: policy.action,
+                    label: policy.label,
+                    ...(policy.recommendedCommand === "task-retry" ? { command: `agent-worker task retry ${JSON.stringify(input.taskId)} --feature-id ${JSON.stringify(run.featureId)} --repo ${JSON.stringify(repoRoot)}` } : {}),
+                    evidence_refs: evidenceRefs,
+                    dedupe_key: dedupeKey,
+                    created_at: (input.now ?? new Date()).toISOString(),
+                });
+                await writeTextAtomic(draftPath, YAML.stringify(actionCard));
+                index.entries.push({ kind: "ActionCard", followUpId, parentTaskId: input.taskId, workerRunId: input.workerRunId, dedupeKey, draftHash: await sha256File(draftPath), evidenceHash, status: "ActionRequired", draftPath: repoRef(repoRoot, draftPath), createdAt: actionCard.created_at });
+                await writeFollowUpIndex(repoRoot, index);
+                return actionResult(repoRoot, followUpId, draftPath, dedupeKey, actionCard, true);
+            }
+            const proposedTaskId = `${policy.taskIdPrefix}-${input.taskId}-${suffix}`;
+            assertSafeRuntimeId(proposedTaskId, "proposedTaskId");
+            const parentTaskPath = path.join(featureDir, "tasks", parentNode.task);
+            const parentTask = taskSpecSchema.parse(YAML.parse(await readFile(parentTaskPath, "utf-8")));
+            const proposedTaskSpec = buildFixTask(parentTask, proposedTaskId, input.workerRunId, category, policy);
+            const draft = {
+                schema_version: 1,
+                follow_up_id: followUpId,
+                proposed_task_id: proposedTaskId,
+                status: "Draft",
+                generated_from: {
+                    feature_id: run.featureId,
+                    task_id: input.taskId,
+                    worker_run_id: input.workerRunId,
+                    failure_category: category,
+                },
+                lineage: { parent_task_id: input.taskId, recommended_action: policy.recommendedAction },
+                evidence_refs: evidenceRefs,
+                evidence_manifest_hash: evidenceHash,
+                dedupe_key: dedupeKey,
+                feature_packet_hash: await hashFeaturePacket(featureDir),
+                proposed_task_spec: proposedTaskSpec,
+                proposed_graph_patch: {
+                    add_node: { id: proposedTaskId, task: `${proposedTaskId}.yaml`, type: policy.taskType, depends_on: [...parentNode.depends_on] },
+                    rewire_dependents: graph.nodes.filter((node) => node.depends_on.includes(input.taskId)).map((node) => ({ task_id: node.id, from_dependency: input.taskId, to_dependency: proposedTaskId })),
+                },
+                created_at: (input.now ?? new Date()).toISOString(),
+            };
+            followUpDraftSchema.parse(draft);
+            await writeTextAtomic(draftPath, YAML.stringify(draft));
+            const draftHash = await sha256File(draftPath);
+            index.entries.push({
+                kind: "TaskDraft",
+                followUpId,
+                proposedTaskId,
+                parentTaskId: input.taskId,
+                workerRunId: input.workerRunId,
+                dedupeKey,
+                draftHash,
+                evidenceHash,
+                status: "Draft",
+                draftPath: repoRef(repoRoot, draftPath),
+                createdAt: draft.created_at,
+            });
+            await writeFollowUpIndex(repoRoot, index);
+            return result(repoRoot, followUpId, proposedTaskId, draftPath, dedupeKey, draft, true);
+        }
+        catch (error) {
+            await cleanupPath(directory).catch(() => { });
+            throw error;
+        }
+    });
+}
+function buildFixTask(parent, taskId, workerRunId, category, policy) {
+    const qaScoped = category === "TestBug" || category === "FlakyTest";
+    const infraScoped = category === "DependencyFailure" || category === "EnvFailure";
+    const productBugFromQa = category === "ProductBug" && parent.type.startsWith("qa-");
+    const qaDiscoveredProductPaths = productBugFromQa
+        ? parent.constraints.forbidden_paths.filter((candidate) => /(^|\/)(src|services|app|apps)(\/|\*|$)/i.test(candidate))
+        : [];
+    const narrowedAllowedPaths = productBugFromQa
+        ? qaDiscoveredProductPaths
+        : qaScoped
+            ? parent.constraints.allowed_paths.filter((candidate) => /(^|\/)(test|tests|qa|spec)(\/|\*|$)/i.test(candidate))
+            : infraScoped
+                ? parent.constraints.allowed_paths.filter((candidate) => /package|lock|vendor|depend|config|script|(^|\/)ci(\/|$)|docker|\.github/i.test(candidate))
+                : [...parent.constraints.allowed_paths];
+    const forbidBusinessCode = qaScoped || infraScoped;
+    return taskSpecSchema.parse({
+        ...parent,
+        id: taskId,
+        title: `${policy.recommendedAction}: ${parent.id} — ${parent.title}`,
+        description: `Follow-up for ${category} from Worker run ${workerRunId}. ${parent.description}`.trim(),
+        type: policy.taskType,
+        risk_level: infraScoped && narrowedAllowedPaths.length === 0 ? "low" : parent.risk_level,
+        depends_on: [...parent.depends_on],
+        scope: {
+            ...parent.scope,
+            goals: [`${policy.goalPrefix} from ${parent.id}/${workerRunId}`, ...parent.scope.goals],
+            non_goals: productBugFromQa ? parent.scope.non_goals.filter((item) => !/do not modify product code/i.test(item)) : parent.scope.non_goals,
+        },
+        constraints: {
+            ...parent.constraints,
+            allowed_paths: narrowedAllowedPaths,
+            forbidden_paths: productBugFromQa
+                ? [...new Set([...parent.constraints.allowed_paths, "test/**", "tests/**", "qa/**"])]
+                : forbidBusinessCode
+                    ? [...new Set([...parent.constraints.forbidden_paths, "src/**", "services/**", "app/**", "apps/**"])]
+                    : [...parent.constraints.forbidden_paths],
+            hard_constraints: [...parent.constraints.hard_constraints.filter((item) => !productBugFromQa || !/read-only qa execution/i.test(item)), ...(productBugFromQa ? ["Do not weaken or remove the failing regression test"] : []), `Preserve lineage to failed run ${workerRunId}`],
+        },
+    });
+}
+function nextSequence(ids) {
+    return Math.max(0, ...ids.map((id) => Number.parseInt(id.match(/-(\d+)$/)?.[1] ?? "0", 10))) + 1;
+}
+async function canonicalEvidenceRef(repoRoot, value) {
+    try {
+        const canonicalRoot = await realpath(repoRoot);
+        const candidate = await resolveRepoFile(repoRoot, value);
+        return path.relative(canonicalRoot, candidate).split(path.sep).join("/");
+    }
+    catch {
+        throw new Error(`canonical evidence must be inside the target repo: ${value}`);
+    }
+}
+function result(repoRoot, followUpId, proposedTaskId, draftPath, dedupeKey, draft, created) {
+    const directory = path.dirname(draftPath);
+    return { schemaVersion: 1, kind: "TaskDraft", created, followUpId, proposedTaskId, draftPath, evidencePath: path.join(directory, "evidence.json"), indexPath: path.join(path.dirname(directory), "index.json"), dedupeKey, draft };
+}
+function actionResult(repoRoot, followUpId, draftPath, dedupeKey, actionCard, created) {
+    const directory = path.dirname(draftPath);
+    return { schemaVersion: 1, kind: "ActionCard", created, followUpId, draftPath, evidencePath: path.join(directory, "evidence.json"), indexPath: path.join(path.dirname(directory), "index.json"), dedupeKey, actionCard };
+}
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/worker/follow-up/paths.js

@@ -0,0 +1,25 @@
+import path from "node:path";
+import { getTaskPoolRoot } from "../pool/run-store.js";
+const SAFE_RUNTIME_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const SAFE_TASK_FILE = /^[A-Za-z0-9][A-Za-z0-9_-]*\.ya?ml$/;
+export function assertSafeRuntimeId(value, label) {
+    if (!SAFE_RUNTIME_ID.test(value)) {
+        throw new Error(`${label} contains unsafe path characters: ${JSON.stringify(value)}`);
+    }
+}
+export function assertSafeTaskFile(value, label) {
+    if (!SAFE_TASK_FILE.test(value) || path.basename(value) !== value) {
+        throw new Error(`${label} must be a safe single-file YAML reference: ${JSON.stringify(value)}`);
+    }
+}
+export function followUpRoot(repoRoot, featureId) {
+    assertSafeRuntimeId(featureId, "featureId");
+    return path.join(getTaskPoolRoot(repoRoot), "artifacts", "features", featureId, "follow-ups");
+}
+export function followUpIndexPath(repoRoot, featureId) {
+    return path.join(followUpRoot(repoRoot, featureId), "index.json");
+}
+export function followUpDir(repoRoot, featureId, followUpId) {
+    assertSafeRuntimeId(followUpId, "followUpId");
+    return path.join(followUpRoot(repoRoot, featureId), followUpId);
+}

package/dist/worker/follow-up/policy.js

@@ -0,0 +1,26 @@
+const TASK_POLICIES = {
+    ProductBug: { kind: "task-draft", recommendedAction: "dev-fix", taskIdPrefix: "FIX", taskType: "fix-from-failure", goalPrefix: "Resolve ProductBug" },
+    TestBug: { kind: "task-draft", recommendedAction: "qa-fix", taskIdPrefix: "FIX", taskType: "bugfix", goalPrefix: "Repair the failing test contract" },
+    FlakyTest: { kind: "task-draft", recommendedAction: "qa-failure-analysis", taskIdPrefix: "FIX", taskType: "qa-failure-analysis", goalPrefix: "Analyse and eliminate flaky verification" },
+    DependencyFailure: { kind: "task-draft", recommendedAction: "dependency-fix", taskIdPrefix: "FIX", taskType: "fix-from-failure", goalPrefix: "Restore the blocked dependency" },
+};
+const ACTION_POLICIES = {
+    SpecUnclear: { kind: "action-card", action: "clarify-spec", label: "Clarify the specification before creating a new TaskSpec." },
+    ContractMismatch: { kind: "action-card", action: "review-contract", label: "Review the architecture or API contract and let a human decide the next task." },
+    RiskyChange: { kind: "action-card", action: "review-risk", label: "Complete an architecture and human risk gate before changing scope." },
+    NeedsHuman: { kind: "action-card", action: "human-triage", label: "A human decision is required before work can continue." },
+    Unknown: { kind: "action-card", action: "human-triage", label: "Triage the unknown failure and classify it before creating work." },
+};
+export function resolveFollowUpPolicy(input) {
+    const taskPolicy = TASK_POLICIES[input.category];
+    if (taskPolicy)
+        return taskPolicy;
+    if (input.category === "EnvFailure") {
+        const recentFailures = input.recentTaskRuns.slice(-2);
+        if (recentFailures.length === 2 && recentFailures.every((run) => run.failure?.category === "EnvFailure")) {
+            return { kind: "task-draft", recommendedAction: "env-check", taskIdPrefix: "ENV-CHECK", taskType: "qa-analysis", goalPrefix: "Diagnose and correct repeated environment failure" };
+        }
+        return { kind: "action-card", action: "retry-task", label: "Correct the environment and retry the unchanged task first.", recommendedCommand: "task-retry" };
+    }
+    return ACTION_POLICIES[input.category];
+}

package/dist/worker/follow-up/schema.js

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import { taskSpecSchema } from "../task-spec/schema.js";
+import { taskGraphNodeSchema } from "../task-graph/task-graph-schema.js";
+const failureCategorySchema = z.enum(["SpecUnclear", "ContractMismatch", "ProductBug", "TestBug", "EnvFailure", "FlakyTest", "RiskyChange", "DependencyFailure", "NeedsHuman", "Unknown"]);
+export const followUpDraftSchema = z.object({
+    schema_version: z.literal(1),
+    follow_up_id: z.string().min(1),
+    proposed_task_id: z.string().min(1),
+    status: z.enum(["Draft", "Approved"]),
+    generated_from: z.object({
+        feature_id: z.string().min(1),
+        task_id: z.string().min(1),
+        worker_run_id: z.string().min(1),
+        dag_run_id: z.string().min(1).optional(),
+        failure_category: failureCategorySchema,
+    }),
+    lineage: z.object({
+        parent_task_id: z.string().min(1),
+        recommended_action: z.enum(["dev-fix", "qa-fix", "qa-failure-analysis", "dependency-fix", "env-check"]),
+    }),
+    evidence_refs: z.array(z.string().min(1)).min(1),
+    evidence_manifest_hash: z.string().regex(/^[a-f0-9]{64}$/),
+    dedupe_key: z.string().min(1),
+    feature_packet_hash: z.string().regex(/^[a-f0-9]{64}$/),
+    proposed_task_spec: taskSpecSchema,
+    proposed_graph_patch: z.object({
+        add_node: taskGraphNodeSchema,
+        rewire_dependents: z.array(z.object({
+            task_id: z.string().min(1),
+            from_dependency: z.string().min(1),
+            to_dependency: z.string().min(1),
+        })),
+    }),
+    created_at: z.string().datetime(),
+}).strict();
+export const followUpActionCardSchema = z.object({
+    schema_version: z.literal(1),
+    follow_up_id: z.string().min(1),
+    status: z.literal("ActionRequired"),
+    generated_from: z.object({
+        feature_id: z.string().min(1),
+        task_id: z.string().min(1),
+        worker_run_id: z.string().min(1),
+        failure_category: failureCategorySchema,
+    }),
+    action: z.enum(["retry-task", "clarify-spec", "review-contract", "review-risk", "human-triage"]),
+    label: z.string().min(1),
+    command: z.string().min(1).optional(),
+    evidence_refs: z.array(z.string().min(1)).min(1),
+    dedupe_key: z.string().min(1),
+    created_at: z.string().datetime(),
+}).strict();
+export const followUpIndexSchema = z.object({
+    schemaVersion: z.literal(1),
+    featureId: z.string().min(1),
+    entries: z.array(z.object({
+        kind: z.enum(["TaskDraft", "ActionCard"]),
+        followUpId: z.string().min(1),
+        proposedTaskId: z.string().min(1).optional(),
+        parentTaskId: z.string().min(1),
+        workerRunId: z.string().min(1),
+        dedupeKey: z.string().min(1),
+        draftHash: z.string().regex(/^[a-f0-9]{64}$/),
+        evidenceHash: z.string().regex(/^[a-f0-9]{64}$/),
+        status: z.enum(["Draft", "ActionRequired", "Approved", "Superseded", "Rejected"]),
+        draftPath: z.string().min(1),
+        approvalPath: z.string().min(1).optional(),
+        createdAt: z.string().datetime(),
+        approvedAt: z.string().datetime().optional(),
+    })),
+}).strict();
+export const followUpEvidenceSchema = z.object({
+    schemaVersion: z.literal(1),
+    followUpId: z.string().min(1),
+    evidence: z.array(z.object({
+        ref: z.string().min(1),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    })).min(1),
+}).strict();
+export const followUpApprovalSchema = z.object({
+    schemaVersion: z.literal(1),
+    followUpId: z.string().min(1),
+    proposedTaskId: z.string().min(1),
+    owner: z.string().min(1),
+    approvedAt: z.string().datetime(),
+    draftHash: z.string().regex(/^[a-f0-9]{64}$/),
+    beforeGraphHash: z.string().regex(/^[a-f0-9]{64}$/),
+    afterGraphHash: z.string().regex(/^[a-f0-9]{64}$/),
+    taskSpecPath: z.string().min(1),
+    graphPath: z.string().min(1),
+    statePath: z.string().min(1),
+    eventPath: z.string().min(1),
+}).strict();