@tea-agent/loop-agent 0.9.0 → 0.10.0

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)} --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();

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

@@ -0,0 +1,96 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, readdir, realpath, rename, rm, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { followUpIndexSchema } from "./schema.js";
+import { followUpIndexPath, followUpRoot } from "./paths.js";
+export async function readFollowUpIndex(repoRoot, featureId) {
+    const indexPath = followUpIndexPath(repoRoot, featureId);
+    try {
+        return followUpIndexSchema.parse(JSON.parse(await readFile(indexPath, "utf-8")));
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return { schemaVersion: 1, featureId, entries: [] };
+        throw error;
+    }
+}
+export async function writeFollowUpIndex(repoRoot, index) {
+    await writeJsonAtomic(followUpIndexPath(repoRoot, index.featureId), index);
+}
+export async function writeJsonAtomic(filePath, value) {
+    await writeTextAtomic(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+export async function writeTextAtomic(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${randomUUID()}.tmp`);
+    await writeFile(tempPath, value, "utf-8");
+    await rename(tempPath, filePath);
+}
+export async function withFollowUpLock(repoRoot, featureId, run) {
+    const root = followUpRoot(repoRoot, featureId);
+    await mkdir(root, { recursive: true });
+    const lockPath = path.join(root, ".lock");
+    let handle;
+    try {
+        handle = await open(lockPath, "wx");
+    }
+    catch (error) {
+        throw new Error(`follow-up transaction is already active for ${featureId}`, { cause: error });
+    }
+    try {
+        return await run();
+    }
+    finally {
+        await handle.close().catch(() => { });
+        await unlink(lockPath).catch(() => { });
+    }
+}
+export async function hashFeaturePacket(featureDir) {
+    const files = await listFiles(featureDir);
+    const hash = createHash("sha256");
+    for (const filePath of files) {
+        const relative = path.relative(featureDir, filePath).split(path.sep).join("/");
+        hash.update(relative);
+        hash.update("\0");
+        hash.update(await readFile(filePath));
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+export async function sha256File(filePath) {
+    return createHash("sha256").update(await readFile(filePath)).digest("hex");
+}
+export function repoRef(repoRoot, filePath) {
+    const relative = path.relative(repoRoot, filePath);
+    return relative.startsWith("..") || path.isAbsolute(relative)
+        ? filePath
+        : relative.split(path.sep).join("/");
+}
+export async function resolveRepoFile(repoRoot, ref) {
+    const canonicalRoot = await realpath(repoRoot);
+    const candidate = await realpath(path.resolve(repoRoot, ref));
+    const relative = path.relative(canonicalRoot, candidate);
+    if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`path must be inside the target repo: ${ref}`);
+    }
+    return candidate;
+}
+export async function cleanupPath(filePath) {
+    await rm(filePath, { recursive: true, force: true });
+}
+async function listFiles(root) {
+    const output = [];
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        if (entry.name.startsWith(".followup-stage-"))
+            continue;
+        const absolute = path.join(root, entry.name);
+        if (entry.isDirectory())
+            output.push(...await listFiles(absolute));
+        if (entry.isFile())
+            output.push(absolute);
+    }
+    return output.sort();
+}
+function isNotFound(error) {
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}

package/dist/worker/metrics/projector.js

@@ -0,0 +1,139 @@
+import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { loadFeatureDecisionModels } from "../feature/decision-loader.js";
+import { readFollowUpIndex } from "../follow-up/store.js";
+import { getTaskPoolRoot } from "../pool/run-store.js";
+import { readValidTaskPoolRuns } from "../pool/validation.js";
+export async function projectMonthlyMetrics(input) {
+    if (!/^\d{4}-\d{2}$/.test(input.month))
+        throw new Error("metrics month must be YYYY-MM");
+    const repoRoot = path.resolve(input.repoRoot);
+    const start = new Date(`${input.month}-01T00:00:00.000Z`);
+    const end = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth() + 1, 1));
+    if (!Number.isFinite(start.getTime()) || start.toISOString().slice(0, 7) !== input.month)
+        throw new Error("metrics month must be a valid YYYY-MM");
+    const { features, projectionWarnings } = await loadFeatureDecisionModels(repoRoot);
+    const validRuns = await readValidTaskPoolRuns(repoRoot);
+    const allRuns = validRuns.records;
+    projectionWarnings.push(...validRuns.warnings);
+    const runs = dedupeRuns(allRuns).filter((run) => inWindow(run.recordedAt, start, end));
+    const featureById = new Map(features.map((feature) => [feature.featureId, feature]));
+    const entered = new Set(runs.map((run) => run.featureId));
+    let closed = 0;
+    for (const id of entered) {
+        const feature = featureById.get(id);
+        if (feature?.status === "closed" && feature.evidence.closeout)
+            try {
+                const raw = (await import("yaml")).default.parse(await readFile(feature.evidence.closeout, "utf-8"));
+                if (raw.appliedAt && inWindow(raw.appliedAt, start, end))
+                    closed += 1;
+            }
+            catch { }
+    }
+    const metricWarnings = [];
+    const followUps = new Map();
+    for (const id of new Set(allRuns.map((run) => run.featureId)))
+        try {
+            followUps.set(id, await readFollowUpIndex(repoRoot, id));
+        }
+        catch {
+            metricWarnings.push(`follow-up index unavailable for ${id}`);
+        }
+    const failed = runs.filter((run) => run.status !== "succeeded");
+    const handled = failed.filter((run) => followUps.get(run.featureId)?.entries.some((entry) => entry.workerRunId === run.workerRunId)).length;
+    const approved = [...followUps.entries()].flatMap(([featureId, index]) => index.entries.map((entry) => ({ ...entry, featureId }))).filter((entry) => entry.status === "Approved" && entry.approvedAt && inWindow(entry.approvedAt, start, end));
+    const executedApproved = approved.filter((entry) => allRuns.some((run) => run.featureId === entry.featureId && run.taskId === entry.proposedTaskId && Boolean(entry.approvedAt) && run.recordedAt >= entry.approvedAt));
+    const approvedSuccess = executedApproved.filter((entry) => allRuns.some((run) => run.featureId === entry.featureId && run.taskId === entry.proposedTaskId && run.status === "succeeded" && run.recordedAt >= entry.approvedAt)).length;
+    const taskTypes = new Map(features.flatMap((feature) => feature.tasks.map((task) => [`${feature.featureId}:${task.taskId}`, task.type])));
+    const successfulDev = new Set(runs.filter((run) => run.status === "succeeded" && isDevelopmentType(taskTypes.get(`${run.featureId}:${run.taskId}`))).map((run) => `${run.featureId}:${run.taskId}`));
+    const deliveryTasks = new Set();
+    for (const feature of features)
+        if (feature.evidence.delivery)
+            try {
+                const manifest = JSON.parse(await readFile(feature.evidence.delivery, "utf-8"));
+                if (manifest.createdAt && inWindow(manifest.createdAt, start, end))
+                    for (const task of manifest.tasks ?? [])
+                        if (task.taskId)
+                            deliveryTasks.add(`${feature.featureId}:${task.taskId}`);
+            }
+            catch { }
+    const required = features.filter((feature) => entered.has(feature.featureId)).flatMap((feature) => feature.acceptanceCoverage.filter((item) => item.required));
+    const acComplete = required.filter((item) => item.status === "covered" || item.status === "waived").length;
+    const decisionLatencies = approved.flatMap((entry) => entry.approvedAt ? [new Date(entry.approvedAt).getTime() - new Date(entry.createdAt).getTime()] : []).filter((value) => value >= 0).sort((a, b) => a - b);
+    const recoveryRounds = [];
+    const recoveredTasks = new Set();
+    for (const taskId of new Set(runs.filter((run) => run.status !== "succeeded").map((run) => `${run.featureId}:${run.taskId}`))) {
+        const [featureId, id] = taskId.split(":");
+        const history = runs.filter((run) => run.featureId === featureId && run.taskId === id).sort((a, b) => a.recordedAt.localeCompare(b.recordedAt));
+        const firstFail = history.findIndex((run) => run.status !== "succeeded");
+        const success = history.findIndex((run, index) => index > firstFail && run.status === "succeeded");
+        if (firstFail >= 0 && success > firstFail) {
+            recoveryRounds.push(success - firstFail);
+            recoveredTasks.add(taskId);
+        }
+    }
+    for (const entry of executedApproved) {
+        const parentKey = `${entry.featureId}:${entry.parentTaskId}`;
+        if (recoveredTasks.has(parentKey))
+            continue;
+        const sourceRun = allRuns.find((run) => run.featureId === entry.featureId && run.workerRunId === entry.workerRunId);
+        const replacementSucceeded = runs.some((run) => run.featureId === entry.featureId && run.taskId === entry.proposedTaskId && run.status === "succeeded" && run.recordedAt >= entry.approvedAt);
+        if (!sourceRun || !replacementSucceeded)
+            continue;
+        const failedAttempts = runs.filter((run) => run.featureId === entry.featureId && run.taskId === entry.parentTaskId && run.status !== "succeeded" && run.recordedAt <= sourceRun.recordedAt).length;
+        if (failedAttempts > 0) {
+            recoveryRounds.push(failedAttempts);
+            recoveredTasks.add(parentKey);
+        }
+    }
+    const boundary = await countBoundaryInterceptions(path.join(getTaskPoolRoot(repoRoot), "artifacts", "features"), start, end);
+    const latencySum = decisionLatencies.reduce((a, b) => a + b, 0);
+    const recoverySum = recoveryRounds.reduce((a, b) => a + b, 0);
+    const metrics = { schemaVersion: 1, month: input.month, window: { start: start.toISOString(), end: end.toISOString() }, generatedAt: (input.now ?? new Date()).toISOString(), metrics: {
+            featureClosureRate: ratio(closed, entered.size, [...(entered.size ? [] : ["no Feature entered execution in window"]), ...projectionWarnings]),
+            orphanFreeFailureRate: ratio(handled, failed.length, [...(failed.length ? [] : ["no failed runs in window"]), ...metricWarnings, ...projectionWarnings]),
+            approvedFollowUpSuccessRate: ratio(approvedSuccess, executedApproved.length, [...(executedApproved.length ? [] : approved.length ? ["approved Follow-up exists but has not executed"] : ["no approved Follow-up in window"]), ...metricWarnings, ...projectionWarnings]),
+            deliverableOutputRate: ratio([...successfulDev].filter((id) => deliveryTasks.has(id)).length, successfulDev.size, [...(successfulDev.size ? [] : ["no successful development task in window"]), ...projectionWarnings]),
+            requiredAcEvidenceRate: ratio(acComplete, required.length, [...(required.length ? ["formal Blocked decisions are not yet a distinct persisted fact"] : ["no required AC discovered"]), ...projectionWarnings]),
+            humanDecisionLatency: { numerator: latencySum, denominator: decisionLatencies.length, value: decisionLatencies.length ? latencySum / decisionLatencies.length : null, sampleSize: decisionLatencies.length, valuesMs: decisionLatencies, medianMs: median(decisionLatencies), missingData: [...(decisionLatencies.length ? [] : ["no completed approval decision in window"]), ...projectionWarnings] },
+            failureRecoveryRounds: { numerator: recoverySum, denominator: recoveryRounds.length, value: recoveryRounds.length ? recoverySum / recoveryRounds.length : null, sampleSize: recoveryRounds.length, values: recoveryRounds, average: recoveryRounds.length ? recoverySum / recoveryRounds.length : null, missingData: [...(recoveryRounds.length ? [] : ["no failed task recovered inside the requested window"]), ...projectionWarnings] },
+            writeBoundaryInterceptions: { numerator: boundary.interceptions, denominator: boundary.audited, value: boundary.audited ? boundary.interceptions / boundary.audited : null, count: boundary.interceptions, sampleSize: boundary.audited, missingData: [...(boundary.audited ? [] : ["no boundary audit artifacts in window"]), ...projectionWarnings] },
+        } };
+    const outputDir = path.join(getTaskPoolRoot(repoRoot), "artifacts", "metrics");
+    const jsonPath = path.join(outputDir, `monthly-${input.month}.json`);
+    const markdownPath = path.join(outputDir, `monthly-${input.month}.md`);
+    await mkdir(outputDir, { recursive: true });
+    await atomicWrite(jsonPath, `${JSON.stringify(metrics, null, 2)}\n`);
+    await atomicWrite(markdownPath, renderMetrics(metrics));
+    return { metrics, jsonPath, markdownPath };
+}
+function ratio(numerator, denominator, missingData) { return { numerator, denominator, value: denominator ? numerator / denominator : null, sampleSize: denominator, missingData }; }
+function median(values) { if (!values.length)
+    return null; const middle = Math.floor(values.length / 2); return values.length % 2 ? values[middle] : (values[middle - 1] + values[middle]) / 2; }
+function inWindow(value, start, end) { const time = new Date(value).getTime(); return time >= start.getTime() && time < end.getTime(); }
+function dedupeRuns(runs) { return [...new Map(runs.map((run) => [run.workerRunId, run])).values()]; }
+async function countBoundaryInterceptions(root, start, end) { let interceptions = 0; let audited = 0; try {
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        const target = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            const child = await countBoundaryInterceptions(target, start, end);
+            interceptions += child.interceptions;
+            audited += child.audited;
+        }
+        else if (entry.name === "failure.json")
+            try {
+                const raw = JSON.parse(await readFile(target, "utf-8"));
+                if (typeof raw.writeBoundaryAudit?.ok === "boolean" && raw.capturedAt && inWindow(raw.capturedAt, start, end)) {
+                    audited += 1;
+                    if (!raw.writeBoundaryAudit.ok)
+                        interceptions += 1;
+                }
+            }
+            catch { }
+    }
+}
+catch { } return { interceptions, audited }; }
+async function atomicWrite(filePath, content) { const temp = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${randomUUID()}.tmp`); await writeFile(temp, content); await rename(temp, filePath); }
+function renderMetrics(metrics) { const rows = Object.entries(metrics.metrics).map(([name, value]) => `| ${name} | ${value.numerator} | ${value.denominator} | ${value.value ?? "n/a"} | ${value.sampleSize} | ${value.missingData.join("; ") || "none"} |`); return `# Monthly Metrics ${metrics.month}\n\nWindow: ${metrics.window.start} — ${metrics.window.end}\n\n| Metric | Numerator | Denominator | Value | Sample | Missing data |\n|---|---:|---:|---:|---:|---|\n${rows.join("\n")}\n`; }
+function isDevelopmentType(type) { return Boolean(type && !type.startsWith("qa-") && !["architecture", "review"].includes(type)); }